Research + add a generic read-only repo/worktree milestone monitor (non-interfering watch); check cost & whether Claude Code already covers it

[Data-Wise]

Summary

Add a generic, read-only, non-interfering "monitor" command to craft — something that watches
another repo / worktree / branch and pings the operator at milestones (new commits, a
subagent-driven-development ledger marking a task complete, idle/done), without ever writing to
the target. This generalizes a pattern that proved very useful in practice but currently has to
be hand-rolled as raw run_in_background bash loops.

Before building, please research + brainstorm + cost it (see "Asks" below) — in particular,
check how much of this Claude Code already provides natively, so craft only adds the thin
convention layer that's actually missing.

Motivation / the pattern worth capturing

While a separate Claude Code session bootstrapped a sibling repo (its own cwd-pinned session,
running subagent-driven-development), the supervising session needed to observe progress without
touching the active worktree — concurrent writers on one branch corrupt the worker's commit-range
bookkeeping and review packages. The working solution was a series of background bash watchers:

• poll git -C <repo> rev-list --count HEAD and report new commits with git log --oneline
• watch the sdd progress ledger ($(git rev-parse --git-path sdd)/progress.md) for
  Task N: complete
• detect "done/idle" (ledger end-state OR no commit for N minutes)
• watch for a specific deliverable to appear (git ls-files --error-unmatch CLAUDE.md)

Each fires a task-notification that re-invokes the supervising agent, which does a read-only
correctness check and reports. Strict non-interference (no edits/commits/builds against the
target) was the whole point — and it had to be enforced by hand.

This is generic and recurring: supervising a worktree feature build, an orchestrated multi-repo
migration, a long CI/codegen run, a teammate's branch. It deserves a first-class command instead
of bespoke bash each time.

Asks (research + brainstorm BEFORE implementing)

1. Check what Claude Code already does so we don't reinvent it. Map our needs onto the existing
   primitives and report the gap:

   • run_in_background Bash + task-notification re-invocation (what the pattern uses today)
   • the /loop skill (recurring prompt/command on an interval or self-paced)
   • schedule / cron routines (CronCreate) for scheduled cloud agents
   • ScheduleWakeup (self-paced dynamic wake-ups, with documented prompt-cache TTL cost notes)
   • any native "watch a file/branch" facility
     Conclusion should state: what's native, what's a thin wrapper, what's genuinely new.

2. Distinguish from craft's existing watchers. We already have ci:watch, ci:status,
   code:release-watch, code:desktop-watch — but those are domain-specific (CI runs, upstream
   releases). This is a generic git/worktree/file milestone monitor. Decide: extend the
   *-watch family, or a new /craft:git:monitor (or /craft:watch)?

3. Cost analysis (important). Each milestone wake-up re-invokes the agent and re-reads context
   — real token cost. Please quantify / give guidance on:

   • poll cadence vs. the ~5-min prompt-cache TTL (sub-300s polls stay cache-warm; longer polls eat
     a cache miss — same tradeoff ScheduleWakeup documents)
   • milestone-only re-invocation (cheap: bash loop sleeps, only wakes the agent on a real event)
     vs. interval re-invocation (expensive: agent wakes every tick)
   • a recommended default cadence + a "max wake-ups / max duration" guard so a forgotten monitor
     can't burn tokens indefinitely
   • whether the watch loop itself (a sleeping background bash process) has any cost while idle
     (it shouldn't — it's local shell, not agent turns)

4. Brainstorm the interface. Rough sketch to react to (not a mandate):

   /craft:git:monitor <path|repo> [--until commits|task-complete|idle|file:<path>]
                                  [--cadence 60s] [--max-wakes N] [--readonly(default)]
   

   • milestone types: new-commit, sdd-ledger task-complete, idle-for-N, file-appears, branch-merged
   • hard read-only guarantee — the command must refuse to ever write/commit/build the target;
     document this as the core contract
   • what the ping reports (commit list + a one-line read-only correctness summary)
   • composability with orchestrate (supervisor watches worker worktrees)

Acceptance (for the eventual feature, post-research)

• A documented command that watches a target and pings at chosen milestones, provably without
  writing to the target.
• A short cost section: recommended cadence, cache-TTL guidance, a wake-up/duration cap.
• A "do we even need this vs. native Claude Code" determination written up in the issue first — if
  native primitives cover it, downgrade to a docs/recipe page instead of a command.

Context

Emerged supervising a sibling-repo bootstrap from a separate session; the non-interference
constraint (don't touch the active worktree) is exactly why a read-only monitor — not an
orchestrator that acts — was the right tool. Related friction issue: #168 (force-delete auth).

[Data-Wise]

Consolidation note (2026-07-01)

A separate thread (the 2026-06-24 Claude usage report — 68% of usage from 8+ hour sessions, 15% from 4+ parallel sessions) proposed a narrower SessionStart hook to surface this session's own elapsed time / concurrent-session count as a live signal, rather than only in the weekly retrospective.

Rather than filing that as a competing spec, folding it in here — it's the same underlying ask at a narrower scope: two additional milestone types for this issue's eventual monitor.

Two milestone types to add to the list in the issue body (alongside new-commit, sdd-ledger task-complete, idle-for-N, file-appears, branch-merged):

• duration-threshold — the current session (not a supervised sibling repo) has been active N hours. Motivating case: long-running/background sessions that should be confirmed intentional, not silently accumulating usage.
• parallel-count-threshold — N+ sessions are concurrently active and sharing one usage limit. Motivating case: nudging toward queueing instead of running everything at once when it isn't actually necessary.

Existing reference implementation worth reusing regardless of scope: governance/session_hook.py — a SessionStart hook already in the repo with the exact shape any milestone-monitor implementation will need: quiet-by-design (silent when clean, silent on any internal error, never breaks a session), mtime/state-cache so an unchanged state skips re-audit, env-var overrides for hermetic testing, and additionalContext as the injection channel. Whatever /craft:git:monitor (or equivalent) ends up looking like, this is a proven pattern to build on rather than a new one to invent.

Same open research question, asked once instead of twice: does SessionStart actually re-fire mid-session (needed for a duration check to mean anything beyond "elapsed time at session start, always ~0"), or does this need ScheduleWakeup / a periodic check on another hook event? This is exactly Ask #1 in the issue body ("map our needs onto the existing primitives and report the gap") — the duration/parallelism case doesn't need a separate answer, just needs its milestone types included in that same research pass.

No new spec filed for this — see docs/specs/SPEC-session-duration-monitor-2026-07-01.md in the repo for the (now superseded) original draft, kept only as a pointer back here.

[Data-Wise]

Audit finding: this is an open research ask, nothing to falsify against current code. Note this session now has both /loop and /schedule skills available (recurring-task + cron-based scheduled agents) — worth checking whether either already covers the 'non-interfering repo/worktree watch' use case before building a new craft-native command. Likely downgrades to a docs/recipe page rather than new code. Leaving open pending that check.

[Data-Wise]

Audit finding (2026-07-26): re-scope from "build a command" to "write a docs recipe."

The core mechanism this issue asked to research is now platform-native: this session's harness has a Monitor tool (background poll-loop, notifies only on real state change), and the user's own ~/.claude/rules/monitor-vs-loop-polling.md already documents exactly this pattern — a background poll script over ScheduleWakeup//loop, with the same cost reasoning (cache-TTL cadence, milestone-only wakeup vs. interval wakeup) this issue's Ask #3 wanted quantified. This directly answers Ask #1 ("map our needs onto existing primitives") for the watching mechanism itself.

No /craft:git:monitor or /craft:watch command exists in the repo (confirmed), and craft's existing *-watch family (ci:watch, code:release-watch) is domain-specific, not the generic case this issue describes — so there's still a real gap, just not a code gap.

What's missing: craft-specific packaging — milestone-type vocabulary (task-complete, idle-for-N, file-appears, branch-merged), a documented read-only-guarantee contract, and orchestrate composability (supervisor watching worker worktrees). None of that needs a new command; it fits the pattern of docs/cookbook/release-watch-recipes.md.

Recommendation: re-scope to a docs/cookbook recipe page showing Monitor + these milestone patterns as ready-to-copy poll scripts, per this issue's own stated fallback ("if native primitives cover it, downgrade to a docs/recipe page instead of a command"). Not closing — the docs work is still open.