pi-tracks #

A repo can declare parked in tracks.json, an array of track names that /track and /pickup never start or resume until the name is removed from it.

verifyTimeoutSeconds in tracks.json is how long the declared verify may run when a tick gates the primary checkout or a track's review runs it (default 120); running past it counts as a failure with exit 124.

A scheduled tick holds the repo's lock while its poll script and its model session run, so each has a time limit: SPEC_WATCH_POLL_TIMEOUT and SPEC_WATCH_SESSION_TIMEOUT, in seconds (default 7200 each, 0 for none). Past it the command's process group is stopped (TERM, then KILL after up to 30 seconds) and its exit line in the tick log reads 124. The Node-based wrapper enforces this on Linux and macOS without requiring GNU timeout.

Spec-driven coordinator #

Repos that declare specWatch in tracks.json can run /spec-watch. One tick derives each spec's state from git, starts detached Pi or Claude writers in isolated worktrees, runs the declared verification gate, and has spec-reviewer review the work before marking it awaiting-approval. It never merges or tags; a person lands approved work with /land spec-<name>.

The schedule drives every spec-driven repository (bin/spec-watch-schedule.sh install <repo>); no interactive session does, so opening or closing sessions never starts or stops work. Every tick, scheduled or run by hand, goes through bin/spec-watch-tick.sh, which holds a per-repository lock so two ticks never act on the same state; /spec-watch refuses to run outside it. While a tick runs, <basename>.tick.pid in the state directory names its process, and every due check saves each track's stage under stages/; a status line reads both to show what is happening in a repository without reading the specs itself.

The scheduled tick never starts a model for a snapshot the last tick already acted on: bin/spec-watch-due.mjs fingerprints every spec's derived state (no model involved) and reports a tick due only when the fingerprint changed. A due answer only claims the snapshot; the tick marks it finished with spec-watch-due.mjs --complete as its last step, so a tick that dies part-way is retried on the next check (three times, then hourly). spec-watch-due.mjs --peek answers without claiming anything, for asking by hand. The one-hour recovery retry applies only while machine-actionable work remains, so a quiet repository costs no model at all.

A Claude writer's background session outlives its worktree, so every Claude check, idle or due, first runs bin/prune-sessions.mjs (no model involved): it removes this repository's background sessions whose worktree is gone, including a lane writer's session on its lane host over ssh, and logs what it removed. A landed track's session therefore goes even when nothing is left to tick. A local session mid-turn is never removed, and one idle but still reporting working (possibly waiting on a background subagent) is removed only once its track/<name> branch is gone too, since landing deletes the branch and moving a worktree does not. A failed prune is logged and retried on the next check.

A tick records what waits on a person in the ## Waiting on a decision section of the base branch's handoff.md through bin/spec-watch-roster.mjs, which splices the section in and writes the file without committing it. A handoff is never committed: the roster and each track's handoff share the path, so a commit of either can overwrite another worktree's copy on a fast-forward, and handoffs not crossing machines by git is the accepted cost. That is only safe when handoff.md is gitignored, so the script refuses a tracked or unignored one with the one-time fix (git rm --cached handoff.md, then add it to .gitignore) and writes nothing. It writes nothing when the section is unchanged.

Runtime PIDs, logs, round counts and review verdicts live under $HOME/.local/state/spec-watch/, outside all repositories.

That state is keyed by path: each worktree's record by a hash of its real path, the tick lock, the tick pid file, the stage record and the due record by the repository's directory name or path. Renaming or moving a checkout therefore orphans it, and the next status read deletes a record whose worktree path is gone. bin/spec-watch-migrate-path.mjs <old-repo-path> <new-repo-path> [--dry-run] [--remove-old] carries all of it to the new path. It rewrites the recorded worktree paths, leaves the lane, review, rounds and writer fields as they are, and copies rather than moves: the old files stay until --remove-old, and a rerun changes nothing. It refuses while a tick's pid file names a live process, while a recorded Pi writer is alive, or when a target file already exists with different content. The rename sequence:

1. Remove the schedule: bin/spec-watch-schedule.sh remove <old-repo-path>.
2. Wait until no tick is running and no writer is working in any worktree. The script cannot see a Claude writer; check claude agents yourself.
3. Back up $HOME/.local/state/spec-watch/.
4. Move the directory, then run git worktree repair from the new location so each worktree's link back to the repository is rewritten.
5. Run bin/spec-watch-migrate-path.mjs <old> <new> --dry-run, read the list, then run it without --dry-run. Run nothing that reads track status (spec-status.mjs, a tick, a due check) in between: that read removes the records still keyed to the old path.
6. Once the new location has been checked, run it once more with --remove-old.
7. Reinstall the schedule: bin/spec-watch-schedule.sh install <new-repo-path>.

Not carried over: the schedule itself, the tick log, hand-made launch-*.sh, brief-*.txt and verify-*.sh files in the state directory, and a lane's own copy of a worktree.

Read-only status consumers and footer activity #

bin/spec-status.mjs [repo] --read-only [--tool pi|claude] provides the same JSON derivation without runtime pruning, log deletion, retired-lane writes, or Git's optional index refresh writes. Repeated calls leave stale external state alone. The default still performs coordinator maintenance. --read-only refuses --verify: running arbitrary repository verification cannot promise no writes. Peek/other observational consumers should use --read-only, not default status. This flag is not a fast footer API: it still derives all specs and, for Claude lanes, can query remote liveness just as default status does.

The shared bin/statusline.sh instead calls bin/track-activity.mjs only in the primary checkout. It reads the first six current track/* worktrees from Git, excluding names in tracks.json.parked, and never reads cached coordinator stages or runs a full spec scan. A live local Pi process must have that exact real cwd inside that worktree and a Pi executable/script identity; saved PIDs (including reused, invalid or dead PIDs) cannot establish activity. Both manually started Pi sessions and canonical spec-launch workers can therefore show ACTIVE writer without any runtime record. This means a live writer, not a guessed verify/review phase or proof the writer is currently generating tokens. Linux uses /proc; macOS uses bounded ps/lsof checks (not live-tested here).

With the Claude harness selected, a bounded local claude agents query supplies working/blocked activity, with the existing 30-minute transcript stall rule. No SSH, model, or network request is made by the footer. An exact current spec/tip review pair can show REVIEWED, a failed pair or committed non-handoff work NEEDS-REVIEW, and a current park or blocked Claude session BLOCKED. Otherwise it shows inactive; that is no observed active writer, not proof of absence on an inaccessible host. Live writer evidence overrides review metadata. Each snapshot has a 2.2s command budget, bounded process/output/row limits, 40-character names, and no prompt/log/argv output. Shell layout retains model, context, cost, branch and path. Shared shell/helper changes apply when this package lands; no installed checkout was modified to demonstrate them.

The existing, unchanged Pi frontend invokes this shared script every ten seconds without a turn. Landing the shell/helper at the shared package path makes these labels available on its next successful refresh; no Pi reload is needed for these script changes. This has not been checked in an installed/live frontend. If the helper cannot observe activity, a successful script refresh emits the current fallback labels rather than preserving previous helper output. However, if the whole script refresh fails, the existing frontend retains its last successful output, which can include a stale ACTIVE label until a refresh succeeds.

Frontend lifecycle hardening is not included in this scoped delivery: the attempted TypeScript replacement was refused by the editing guard (see this track's handoff). Disposal/session-switch/headless guards and failed-refresh clearing remain deferred to a separately authorized frontend task. The delivered scope is writer labels on successful periodic refreshes and the read-only status API, not completion of the historical full frontend brief.

spec-status.mjs and spec-watch-tick.sh take a --tool claude|pi argument (falling back to the TRACKS_TOOL environment variable, then to pi) that switches how a live writer is detected and, for claude, which model a writer runs on. Everything else -- state derivation, the round and review rules, scheduling -- is identical for both.

A repo can declare specWatch.lanes {count, launch, fetch} to send Claude writers to dedicated build hardware over ssh instead of running them locally: the coordinator picks the least-loaded lane, spec-watch-launch.mjs --lane-index <n> runs the repo's own launch script and records where the writer landed, and spec-status.mjs reads that writer's liveness -- working, blocked, idle, done, stalled (a live-looking session whose transcript and every subagent's have gone quiet), or unreachable (a dropped connection, never treated as dead) -- over ssh instead of locally. A handoff is never committed and a lane copy is synced from git-visible files, so the lane brief carries the worktree's handoff.md text and spec-watch-fetch.mjs copies the lane copy's handoff.md back with rsync after a successful fetch. A dead or stalled writer, and a rebase conflict hit while landing, share one three-relaunch cap tracked in the track's runtime state file.

A repo can also declare specWatch.landScript, handing the merge decision at awaiting-approval to that script instead of stopping there for a person; see prompts/spec-watch.md for its exit-code contract and the park record a repeated rebase conflict leaves for a person to resolve.

A repo that moves its work off the model entirely can declare specWatch.pollScript, a path inside the repo, with specWatch.pollEnv, an object of NAME: "value" strings exported for it. Each scheduled tick for that repo then runs the script from the repo root, under the same per-repo lock and on the same schedule line, instead of the due check and the model session; its output and exit code go to spec-watch.log between === poll and === exit lines. A pollScript that is absolute, reaches outside the repo, is not an executable file, or comes with a malformed pollEnv is logged as refused, and no model tick runs in its place. A repo that wants both sets specWatch.pollThenTick: true: each tick runs the pollScript first and then, whatever its exit, the due check and the model session under the same lock.

Models #

Everything uses its harness's default model unless set otherwise. Writer and reviewer each resolve in this order: the spec's front matter field, then the environment variable, then the harness's own default. Pi has no per-agent pin, so an unset value is null and the verdict omits that flag; Claude Code's spec-reviewer adapter pins sonnet, so its status read reports that value and its verdict names it. The writer's environment fallback is Pi's; Claude Code resolves its writer from the spec's model, else specWatch.writerModel, else its adapter default.

The recommendations are not defaults in code; set them per machine in $HOME/.config/pi-tracks/env:

SPEC_WATCH_WRITER_MODEL=openai-codex/gpt-5.5
SPEC_WATCH_REVIEWER_MODEL=zai/glm-5.3

Neither cron nor launchd passes a shell's environment through, so the tick also reads them, and TRACKS_TOOL, from that file (plain NAME=value lines). spec-status.mjs reports the resolved values per spec as model and reviewerModel (null means that leg left the choice to the harness), and spec-watch-runtime.mjs review keeps them in the recorded verdict (--writer-model, --reviewer-model) on every leg, so runs of one spec under different models can be compared. Editing a spec's model fields changes the spec file, so it counts as an amendment like any other edit: the spec's sha is the last base-branch commit touching the file, and that sha also names the landing tag.

Writer failover #

A writer that runs out of credits, or dies for any reason at all, is relaunched by the next tick into the same worktree. Without failover every relaunch reuses the same model, so one exhausted provider burns all three relaunches and the track parks. With a failover chain configured, the launcher counts the model each previous writer ran on as failed and starts the replacement on the chain entry with the fewest failures (ties to the earliest entry), so the next attempt lands on a different provider even when every spec prefers the same one.

A chain is configured in one place: specWatch.writerModelFallbacks in tracks.json (an array of model ids, the durable place), or the SPEC_WATCH_WRITER_MODEL_FALLBACKS environment variable (comma- or space-separated) for a per-machine choice. The spec's resolved model is the head of the chain and the fallbacks follow it; the first configured source wins, and a malformed list is skipped rather than trusted. With no chain configured nothing changes. A spec with no model of its own (Pi would run its default) puts the fallbacks themselves at the head: a repo that configures a chain names the models its writers run on, whichever position they start from. spec-status.mjs reports the model the current writer was launched on as launchedModel, and the verdict records it via --writer-model, so a review always names the model that produced the work. A spec amendment resets the record so the chain starts from the head again.

By default the launcher picks the entry with the fewest failures (ties to the earliest), so work concentrates where things work. A repo that prefers spread declares specWatch.writerModelRandom: true in tracks.json (or sets SPEC_WATCH_WRITER_MODEL_RANDOM=1 on the host): every writer then draws its chain entry at random, weighted by the same failure counts -- a model that has failed n times is drawn n+1 times less often, so failed providers fade out, the healthy ones share the work, and nothing is ruled out for good. A boolean in tracks.json overrides the host variable.

/spec interviews a person and writes a spec file in the repo's declared specs directory, with a runnable verify command, touches scope, and the two model fields (blank falls back).

Model pools #

Writers and reviewers each select from a declared pool of approved model+provider combos, and the two pools may overlap. The rule for a given assignment -- write or review -- is: keep selecting combos from the pool, skipping the ones already tried in this assignment, until one works. No tiers, no weights, no permanent bans: a down provider is not retried within the assignment, and the next assignment starts from the whole pool again.

• Writers: specWatch.writerPool in tracks.json (legacy key writerModelFallbacks reads as the same pool). The spec's resolved model heads the selection; the launcher counts the model a failed writer ran on and the relaunch selects a different combo, so "until one works" spans relaunches. writerModelRandom keeps its weighted spread for writers.
• Reviewers: specWatch.reviewPool (legacy key reviewerModelFallbacks reads as the same pool). The rule is enforced in one place, bin/model-pools.mjs, consumed by the spec-loop, pi's subagent extension for spec-reviewer dispatches, and the prompt runbooks that dispatch agents by hand. A candidate that does not answer is logged and the next untried one goes; an exhausted pool waits for the next pass.

Every verdict records --writer-model and --reviewer-model, so a review always names who wrote and who reviewed. A malformed pool is skipped, not fatal. Both pools are exposed by spec-status.mjs (reviewPool on every read) for the runbooks and the status line.

Tick failover #

The writer chain cannot save the tick's own model session: when the model a tick starts on is dead, the session hangs — no output, no exit — and nothing gets far enough to relaunch a writer. A hang is not an error, so it is detected by a deadline, not an exit status. The pi leg of a tick therefore runs through bin/spec-watch-tick-chain.mjs, which tries a chain of models inside one tick: SPEC_WATCH_MODEL is the head, then specWatch.tickModelFallbacks in tracks.json (or, when that list is absent, specWatch.writerModelFallbacks, so a repo that configured writer failover gets it for the tick too), or SPEC_WATCH_MODEL_FALLBACKS in the per-machine env file. A malformed declared list is skipped whole rather than half-trusted.

Each attempt is bounded by a first-output deadline — specWatch.tickFirstOutputSeconds (default 120) or SPEC_WATCH_TICK_FIRST_OUTPUT_SECONDS — separate from SPEC_WATCH_SESSION_TIMEOUT, which stays the cap for a session that is working: the attempt's output is streamed as it arrives, so "no first byte within N seconds" moves the tick on to the next entry instead of burning a whole session limit on a dead provider. The first attempt that answers ends the rotation for that tick. Either limit set to 0 disables that limit, as elsewhere in the tick; the session cap still reaches the model process, so a stop never leaves a model holding the repo behind the tick.

A circuit breaker keeps a dead head from eating that budget on every tick: an entry with three consecutive failures is in cooldown and is skipped, and exactly one cooled entry keeps a rotating probe slot per tick, so a recovered provider is felt within a few ticks. A success clears the count and leaves the cooldown. The counts live in the repo-keyed state the writer launcher weights its picks by, so a model the tick keeps failing on is also drawn less often by writers.

The two lists are a tier split when a subscription prices its models unequally: put the coordinator-grade models in tickModelFallbacks and the cheaper worker-grade models in writerModelFallbacks — the tick walks its list failover-first, writers draw at weighted random from theirs (writerModelRandom). Each list stands alone; nothing forces one to derive from the other.

The winner is recorded per repo in the runtime state (tickModel, reported by spec-status.mjs at the top level), and the next tick's chain starts there — a dead provider at the head is probed once, not every interval. A model that hangs increments the same modelFailures counts the writer chain weights its picks by, and a model that answers clears its own count, so a provider that stalls the tick also fades out of writer selection. When every entry fails, the tick exits rather than retrying, leaving the snapshot claimed and the reason in the log. With no chain configured the tick runs exactly one attempt, as before; the claude tick path is unchanged.

Scheduling #

bin/spec-watch-schedule.sh install <repo> [intervalSeconds]
bin/spec-watch-schedule.sh remove <repo>
bin/spec-watch-schedule.sh pause <repo>
bin/spec-watch-schedule.sh resume <repo>
bin/spec-watch-schedule.sh status <repo>

Execution permission is per repository. A coordinator can pause its repo before drafting specs and resume it when work is ready; resuming repo A never resumes repo B. A pause survives coordinator restarts and schedule installation/removal. It skips both scheduled and manual ticks, including pollScript, pruning and model launches, without consuming a due snapshot. It does not cancel a tick or writer already running, and does not prohibit explicit manual launches or merges.

The switch lives in local Git config (pi-tracks.specWatchPaused), shared by that repo's worktrees, not in tracked files or machine-wide environment. It does not dirty the checkout. status reports paused or enabled (execution permission, not whether a schedule is installed). Existing repos remain enabled until paused. resume only grants permission; it neither installs a schedule nor immediately runs a tick. For holding just one spec, use its enabled: false front matter instead.

On Linux this adds or removes one marked crontab line per repo and leaves every other line alone; on macOS it manages a LaunchAgent. The interval defaults to specWatch.intervalSeconds in tracks.json, else 300 seconds, minimum 60; cron rounds it up to whole minutes. Each tick appends to $HOME/.local/state/spec-watch/spec-watch.log. On Linux, overlapping ticks for one repo are skipped via flock.

Install the schedule from the checkout pi uses: the crontab line or LaunchAgent records the tick script's absolute path.

Agent track operation #

An interactive session may act on a track between ticks, and may advance it - the tick is the recurring driver, not a fence. /track-ops is the runbook: it names the commands and their boundaries. In brief:

bin/track-stop.mjs <worktree>                       # stop a track's live writer, wherever it runs
bin/spec-watch-runtime.mjs reset <worktree>         # clear rounds, relaunch cap and park
bin/spec-watch-launch.mjs <worktree> <repo> --tool <pi|claude> [--model <model>]
bin/spec-watch-runtime.mjs relaunch <worktree>      # count one relaunch of a dead writer
bin/track-rebase.sh <worktree> <base>               # rebase onto base, handoff.md conflicts resolved
bin/spec-watch-runtime.mjs park <worktree> <tip> <sha> rebase-conflict <paths>
bin/spec-watch-runtime.mjs review <worktree> <tip> <sha> pass|fail <notes-file>
bin/spec-watch-schedule.sh pause <repo>             # stop (and resume) the scheduler's execution permission

/track-ops also carries the tick's review sequence (fresh gate, one spec-reviewer run, verdict recorded against the exact tip and spec sha) and landing an approved track: that walks the /land runbook from the primary checkout, which by itself owns every merge, spec/... tag, worktree removal and branch deletion. A bare merge or tag never appears outside /land.

track-stop.mjs finds the writer from the track's runtime state: the recorded Pi process (signaled as a group, since the launcher starts it detached), the local Claude Code registry (claude stop <id>), or the track's lane over ssh when it has one. It stops sessions; it never removes them or touches the worktree, branch or state -- uncommitted work stays in the tree for the next writer, and prune-sessions.mjs owns removal once a worktree is gone. Stopping a spec-driven track's writer, or resetting a track, hands the work back to the next tick: pause the repo first when the stop should hold.

Ticks never run in an interactive session (SPEC_WATCH_TICK_LOCK unset makes /spec-watch refuse); bin/spec-watch-tick.sh <repo> run from a person's shell is the way to run one by hand.

Validation #

Run the complete local validation suite with:

npm run validate

It runs ShellCheck and syntax checks, integration tests against disposable git repositories, and a model-free Pi extension loading smoke test. The integration suite covers track placement and status, spec lifecycle and review freshness, runtime-state updates, detached writer launch and namespace expansion, and idempotent cron installation/removal.

Use npm test to run only the integration tests.

Migrating from localcode #

Older localcode versions generated these same prompts and extensions into ~/.pi/agent/prompts/, ~/.pi/agent/extensions/{chook,track-context}/ and ~/.pi/agent/agents/spec-reviewer.md. Remove those copies, or pi loads each twice.