/re0-watch

name: re0-watch
disable-model-invocation: true
description: "Watch a long-running agent job for stalls and alert by default, with recovery only as a proposal a human approves."

Watch one running job across time, separating completion, declared pauses, healthy silence, and suspected stalls.

Goal

Arm an observable watch for one running job only on explicit human invocation. Alert-only is the default act. Hand recovery proposals to a human; never recover unattended.

Workflow

1. **Name the run.** Record its immutable run identity, owning host, authoritative terminal source, advancing progress signal, liveness artifact, pause source, and alert destination. A self-reported `running` string alone is insufficient. If identity, terminal truth, or meaningful progress cannot be established, report the missing capability and stop with an advisory. 2. **Recommend three separate timing quantities.** Check frequency is how often the observer wakes; silence threshold is how long progress may remain frozen; alert cooldown is the minimum interval between repeated alerts for the same run and the same frozen signals. Record each number's provenance separately, including who supplied or accepted the cooldown. Derive the threshold from observed cadence, roughly 2 to 3 times the longest healthy silence, and the cost of delayed detection. Only when neither supplied nor derivable, propose 30 minutes as an unvalidated starting recommendation. Propose 10 as an unvalidated attempt-count cap, not a frequency or spacing. Check frequency, alert cooldown, and retry spacing have no defaults. Require a positive check interval strictly below the accepted threshold; respect known retry-after and require an explicit elapsed-time cap for any recovery proposal. 3. **Bind accepted settings.** Read back settings supplied or approved for this run without asking again or replacing them. Obtain acceptance for new settings; if no threshold is accepted, stop advisory. Persist an arm record naming the run, observer, and registration/disarm owner. Record signal locations and baselines, the terminal condition, accepted threshold, frequency, and alert cooldown with each setting's provenance. Include the last alert time and frozen signals per run, any declared pause signature protocol's algorithm and key, recovery proposal scope, spacing, count and elapsed bounds, and previous attempts. Recovery scope defaults to neither resume nor restart; a recorded scope authorizes only a proposal. 4. **Arm through the host.** Use the existing registration primitive and enforce one observer per run identity. A later duplicate declines registration and reports the existing observer. The component that registers owns disarming. With no registration primitive, do not arm: return the signals, suggested threshold, and suspected-stall condition as advisory, explicitly marked `unattended capability unavailable`, then stop. A manual reminder is not an armed watch, and neither is a background process printing into a terminal nobody reads: an alert counts only when something wakes the session or the human to receive it.

A Codex thread goal that wakes the session for each continuation is a registration primitive, and its objective is the arm record's identity: it ends with one `Watch ids:` line naming every run it observes. A thread holds one goal, the host refuses a new goal while one is unfinished, and complete is the only status the agent may set that frees the slot, so re-arming is a supersede and never a second registration. Run it as a script, not a judgment: write the host's `get_goal` result and the desired objective to files, run `node scripts/goal-rearm.mjs plan --current <goal.json> --objective <objective.txt> --gh`, and follow the printed `action`. `create` and `keep` need no completion. `supersede` prints an objective that carries every id the old goal still owed unless the host records it closed, so the old watch's obligation moves into the new one before the old goal is completed: call `update_goal` with `complete`, then `create_goal` with the printed objective, then pass the new `get_goal` result to `node scripts/goal-rearm.mjs verify --plan <plan.json> --readback <goal.json>`. Exit 2 from either command, a refused plan or a mismatched readback, means the watch is not armed: report it and do not claim coverage. Never complete an unfinished goal on any other path. ARMED holds only at that moment: the host can later move the goal to blocked or budget-limited, which ends the wakes silently. 5. **Evaluate each wake in order.** First confirm the registration still wakes this session: for a Codex thread goal, pass the current `get_goal` result to `node scripts/goal-rearm.mjs check --current <goal.json>`. `LAPSED` (exit 2) means coverage stopped at the goal's last update: alert with that gap, re-arm through the step 4 supersede, and never report the watch as running until `verify` prints `ARMED` again. Then write what this wake read from the host (the run's terminal source, the pause artifact, each signal) to an observation file and run `node scripts/wake.mjs --arm <arm.json> --observation <observation.json> --json`. The arm record supplies the accepted settings, signal baselines, last alert and any pause algorithm and key; the output is the rung reached, the outcome with its reason, and the updated signals and last alert to write back into the arm record on every exit, since a silent cooldown observation keeps the last alert time. Exit 0 sends nothing, 2 alerts, 3 hands you a case for judgment, and the script's usage names the file shapes. The ladder below is the specification the script implements. What stays yours: reading each artifact fully into the observation (a read that fails is `unreadable`, never an empty answer), a pause protocol the script reports as `needs-judgment`, and rung 7, which a recovery proposal reaches only when the output says `recoveryProposalMayFollow` and every rung 7 prerequisite holds. 6. **Hand off a