Consume lane restart-requests via scheduled headless reader

[kyle-sexton]

Context

Nothing restarts a stopped lane: a cycle-budget hit, crash, or harness restart writes a restart-request to a surface with no consumer, making every budget or expiry hit a terminal manual-restart state. The repo has already named the gap and its preferred fix: "a scheduled headless claude -p reading each lane's telemetry restart_request". Cloud Routines were considered and rejected for lane work (no access to local checkouts). Source analysis (item 6, Tier 2, REPO-INTERNAL): https://github.com/melodic-software/knowledge-corpus/blob/main/sources/webinars/getting-started-with-loops/analysis/action-items.md.

Proposed work

• Build the restart-request consumer, probably in plugins/claude-ops/skills/lanes/ — a scheduled local headless reader of each lane's telemetry restart_request
• Pursue the repo's named local answer; do not re-litigate cloud Routines for this (rejected on evidence at prompts/loops/loop-lane-prompts.md:703-708)

Acceptance criteria

• A written restart_request results in the lane being relaunched without manual intervention
• The consumer is itself observable (its failures don't become a second silent gap)
• Restart respects the lane's existing launch shape and autonomy tier

References

• https://github.com/melodic-software/knowledge-corpus/blob/main/sources/webinars/getting-started-with-loops/analysis/action-items.md (item 6)
• prompts/loops/loop-lane-prompts.md (no-relaunch-owner diagnosis; Routines rejection at :703-708)

[kyle-sexton]

Design decision: Windows Task Scheduler (OS-level scheduler) backs the headless reader

Recorded before implementation so the reasoning survives a lost session. Decided by a
three-option bake-off against the repo's actual constraints and official docs fetched
2026-07-27.

Decision

The restart-request consumer is a deterministic OS-agnostic bash script
(plugins/claude-ops/skills/lanes/scripts/restart-consumer.sh), reached through a new
consume-restarts action on the existing /claude-ops:lanes skill, and driven on a
schedule by an OS-level scheduler registered under the operator's own account —
schtasks.exe on Windows, with launchd / systemd --user / cron documented as the
equivalents. The scheduled command is a local headless
claude -p "/claude-ops:lanes consume-restarts".

Why — the discriminating constraint is what survives

Option	Survives clean cycle-budget stop	Survives lane crash	Survives harness restart / reboot
Watchdog/wake lane (/loop + ScheduleWakeup)	yes	no	no
Stop hook on the dying lane	conditionally	no	no
OS scheduler (chosen)	yes	yes	yes

• A watchdog lane is circular: it is itself a /loop session bounded by the same
  seven-day expiry, cycle budget, and crash risk it exists to remediate
  (docs/conventions/loop-lane/README.md:190, :209). Two lanes watching each other are
  co-launched and expire in the same window. Rejected.
• A Stop hook is non-circular (the hook config lives outside the session) and uniquely
  event-driven, but it structurally cannot fire when the thing that failed is the process
  or the machine — and a lane crash and a harness restart are two of the three failure
  modes named in the issue's Context. It also fires on every turn of every session in
  every repo and carries no session name in its input, so self-scoping costs a subprocess
  per Stop everywhere. Deferred, not discarded (trigger below).
• Only an OS scheduler covers cold start after reboot, which is the case where every
  lane is down and nothing in-harness is alive to notice.
• A plugin-owned long-lived supervisor process was also weighed: it dies with the login
  session and does not survive reboot, so it buys the OS scheduler's install cost without
  the OS scheduler's guarantee.

/schedule cloud routines remain rejected and were not re-litigated — they cannot reach a
local checkout (prompts/loops/loop-lane-prompts.md:703-708).

Verified this session (2026-07-27)

• claude -p headless print mode, --output-format, --permission-mode, --allowedTools,
  --bg, -n/--name, claude agents, claude stop, claude respawn:
  https://code.claude.com/docs/en/cli-reference
• Empirically on the target machine (claude 2.1.220):
  claude -p "Reply with exactly: pong" --output-format text returns exit 0 and
  authenticates from the user profile in a plain non-interactive Git Bash shell — no TTY,
  no interactive login.
• claude respawn <id> restarts a background session with the conversation intact, so
  it is explicitly not the relaunch primitive here: a restart-request exists precisely
  because a fresh context is the only reset a lane gets
  (plugins/claude-ops/skills/lanes/SKILL.md, "A relaunch is the only context reset a loop
  lane gets"). The consumer therefore relaunches through lane-launcher.sh restart <lane>.

The restart_request shape actually emitted

Discovered from the producers, not assumed. Both lane loops
(plugins/work-items/skills/work-loop/SKILL.md,
plugins/source-control/skills/babysit-loop/SKILL.md) write one sentinel-marked comment
<!-- claude-ops:lane-telemetry marker=<MARKER> --> on a per-lane Lane telemetry: <lane>
tracking issue, whose body carries a fenced JSON durable-state block:

{"schema":"work-items/loop-state@1","cycle":12,"clean_streak":1,"item_cap":2,
 "rate_limit_latch":false,"first_drain_complete":false,"guard_mode":"proactive",
 "loop_started_at":"2026-07-23T15:00:00Z","restart_request":null}

Markers in use: work-items:work-loop, source-control:babysit-loop. Schemas:
work-items/loop-state@1, source-control/babysit-loop-state@1.

The producer specifies no non-null shape for restart_request; the consumer therefore
treats any non-null value as a request and additionally parses a documented optional
object form. No producer edit is in scope for this issue — the consumer is written to
the shape that is actually emitted today.

Relaunch predicate (self-idempotent, no write to another writer's comment)

Restart a lane iff all hold:

1. the lane is named in the operator's local lane config (a hostile issue comment can never
   name a lane the operator has not configured — the comment supplies a signal, never a
   target);
2. its telemetry state block parses and restart_request is non-null;
3. the lane is not currently running (claude agents --json, name match + kind: background);
4. the per-lane circuit breaker has room (default 3 restarts / rolling 24 h).

Condition 3 makes the predicate self-clearing: after a relaunch the lane is running, so a
stale non-null restart_request cannot fire twice, and the consumer never has to PATCH a
telemetry comment whose marker another writer identity owns.

The relaunch itself delegates to lane-launcher.sh restart <lane>, which already carries
that lane's prompt file, --model, --effort, and --settings (the autonomy-tier
override) from config — so acceptance criterion 3 (respects the lane's existing launch
shape and autonomy tier) is satisfied by delegation, not by new launch code.

Consumer observability (acceptance criterion 2)

The consumer upserts its own sentinel-marked telemetry comment
(marker claude-ops:restart-consumer) emitting the lane: / last-cycle: / flags:
fields morning-brief.sh already parses, so it renders in /claude-ops:morning-brief with
no reader change and inherits that reader's STALE (>Nh) detection. That is what catches
the failure mode a run log alone would miss: the scheduled task never fired at all. A
JSONL run ledger under ${CLAUDE_PLUGIN_DATA} is the detail layer.

Parked / deferred

• Registering the scheduled task is an operator action and is NOT performed by the PR.
  The skill ships print-schedule emitting the exact schtasks /Create and schtasks /Delete lines; the operator runs them.
• Stop-hook relaunch — deferred with a trigger. Revisit when (a) a Stop hook gains a
  session-name discriminator in its input, or (b) lane bodies mandate
  ScheduleWakeup(stop: true) so a clean stop is unambiguously detectable. It would then
  be a latency improvement layered on top of the OS scheduler, never a replacement — it
  cannot cover crash or reboot.
• UNVERIFIED: whether a claude --bg session launched from a Task Scheduler process
  outlives that process on Windows. The consumer mitigates rather than assumes: after each
  relaunch it re-polls claude agents --json and records whether the lane actually came
  up, so a failure here is loud in the consumer's own telemetry instead of silent.