opencode-thrum-pro 0.1.12 → 0.1.14

package/assets/skills/coordinator-context-monitoring/SKILL.md

@@ -1,685 +0,0 @@
----
-name: coordinator-context-monitoring
-description: "Use when managing live implementer/brainstormer agents during a long coordination session, at epic merge gates, after a busy dispatch hour, or whenever you suspect an agent is approaching context limits. Prevents 97%-context silent blow-ups by running a sweep + pre-emptive restart before the agent degrades. Safe to wire into a recurring cron that INVOKES this skill — the skill applies tier-ladder judgment, surfacing (and, only when explicitly opted in via config, autonomously restarting) at the >85% tier. What's forbidden is a cron/script that fires restarts unconditionally without going through this skill's tier ladder."
----
-
-# Coordinator: Context Monitoring and Pre-emptive Restart
-
-## When to invoke
-
-Trigger this pattern at each of:
-
-- Receipt of an `ALERT: flagged=…` message from the `context-monitoring` thrum
-  monitor (the canonical scheduled sweep, outer tick `@every 30m`, self-gated
-  so effective rate is slower; see "How the scheduled sweep works")
-- Epic merge gates (after merging a sub-epic — E6.4, E6.5, etc.)
-- After dispatching 3+ tasks in quick succession
-- After any agent has been running for 60+ minutes without a restart
-- On observing slow or degraded responses from an implementer
-- Manually whenever the session feels "intense" (lots of cycles in a short
-  window)
-
-The skill applies tier-ladder judgment: the >85% tier surfaces a
-`recommend-restart-extended` reason (or, when `restart_actuation=true` in
-config, runs a snapshot-gated restart) only on actual ctx %, not on every sweep.
-What's forbidden is a script that bypasses this skill and fires
-`thrum tmux restart --force` unconditionally (that violates
-`feedback_restart_discipline` — burn the runway, don't restart on schedule).
-
-## Coordinator self-restart — ALWAYS the EXTENDED form, compact-extended FIRST
-
-This skill's tier ladder (Steps 3–5) governs how the coordinator restarts
-**other** agents. When the **coordinator restarts ITSELF**, a different rule
-applies and it is absolute — but the current ruling
-REVERSES which command that is:
-
-> **The coordinator ALWAYS uses the EXTENDED snapshot grade for itself — never
-> the standard/compact form. Which command carries that grade is
-> runtime-directed: `/thrum:compact-extended` on any runtime with a verified
-> compact-equivalent skill (the default), `/thrum:restart-extended` ONLY
-> as the fallback on a runtime without one (today: muse, copilot).**
-
-This is a REVERSAL of the prior absolute rule ("ALWAYS restart-extended, NEVER
-compact") — that rule is retired, not merely relaxed. Do not restore it.
-
-Rationale: the coordinator is the nerve center. Its handoff must carry the full
-16-section snapshot (wire contracts, capability matrix, cycle history, open
-L-questions, anticipated Q&A, design rationale) so the next session resumes
-steady-state coordination without re-deriving fleet state — that requirement
-is UNCHANGED and is what "EXTENDED" governs; only the compact-vs-restart choice
-changed. Compacting (rather than restarting) additionally keeps the SAME
-process/session alive — sub-agents, background loops, and cron schedules the
-coordinator owns survive the compaction, where a restart would drop them.
-There is no ctx-band at which the coordinator downgrades to the standard/
-compact-grade snapshot — the tier ladder below governs OTHER agents, not this.
-
-Practical trigger points for coordinator self-restart/compact:
-
-- A warn-tier context nudge fires on the coordinator's own pane (e.g. 70%+).
-- The coordinator hits a clean checkpoint and elects a fresh session.
-- Rate-limit / stuck-state recovery on the coordinator itself.
-
-In every one of these: run `/thrum:compact-extended` if the coordinator's
-runtime has a compact equivalent (the default); `/thrum:restart-extended` only
-if it does not. (The role-rule `coord-always-restart-extended` — `Coordinator
-ALWAYS uses /thrum:restart-extended` — is RETIRED; see
-`thrum memory` for its retirement record. This skill is the always-loaded home
-so the CURRENT rule survives even when memory isn't consulted.)
-
-Note the distinction from Steps 3–5 below: those steps drive `/thrum:restart`
-(Step 4) and `/thrum:restart-extended` (Step 5) into
-**implementer/brainstormer** panes per their ctx tier — that tiering is correct
-for worker agents. The carve-out here is ONLY about the coordinator's own
-restart/compact, which is unconditionally the extended grade, compact-first.
-
-## How the scheduled sweep works (v0.10.6+ — thrum monitor)
-
-The sweep runs as a daemon-managed `thrum monitor` job named
-`context-monitoring`, registered with an `@every 30m` schedule. The 30-min tick
-is the outer envelope — the sweep is self-gated: daytime ticks only fire
-when the fleet is busy (`agent_status=working`), and overnight ticks fire only
-every other tick (effective 60-min rate), so most ticks may be silent no-ops.
-There is a SINGLE monitor for ALL lenses in v1 — not one per lens. The job
-invokes
-`scripts/error-and-context-agent-sweep.sh --no-nudge --out /tmp/agent-sweep.txt`.
-The script emits a single consolidated `ALERT:` line to stdout when ANY agent
-crosses a threshold (ctx >= 50% OR api-error OR capture-fail); when the fleet is
-clean, the script is silent so no message fires. The monitor's
-`--match '^ALERT:'` filter routes the ALERT line as a message to the
-`coordinator` role (fanned out to every LIVE local coordinator — if no
-coordinator is currently live, the sweep is a silent no-op rather than queuing
-for an offline one), which triggers this skill.
-
-Format of the ALERT line:
-
-```text
-ALERT: flagged=N stuck=S stuck_working=W tier3=T tier2=U — agent_a(92%,api-err,STUCK,stuck-working); agent_b(88%); …
-```
-
-or, on a benign-only tick once the periodic heartbeat interval has elapsed:
-
-```text
-ALERT: all-clear — N agents healthy, 0 actionable (sweep alive)
-```
-
-- `flagged` — total agents needing attention
-- `stuck` — api-errored on TWO consecutive sweeps (state file tracks this across
-  runs)
-- `stuck_working` — agent_status=working AND tmux quiet > threshold AND no
-  recent JSONL tool calls; threshold tunable via `--silence-threshold-min`,
-  default 10 min
-- `tier3` — count with ctx >= 85% (snapshot-gated restart candidates; see
-  Step 5)
-- `tier2` — count with 70-84% ctx (tmux-send nudge candidates)
-- Per-agent segment: `name(ctx%,reason-if-any,classifier)` joined by `;`
-
-### RUN vs DELIVER
-
-The sweep now ALWAYS computes flags every scheduled tick (daytime; overnight
-keeps its even-tick-only cadence) — RUN is no longer gated on a coarse
-fleet-busy signal, which used to silently suppress genuinely actionable signals
-before flags were even computed.
-
-DELIVERY of the `ALERT:` line is a separate decision, made AFTER flags are
-computed:
-
-- **ACTIONABLE** (delivers the real ALERT) — tier2/tier3 ctx, workstall, stuck /
-  stuck_working, waiting-on-coord, blocked-on-human, capture-fail,
-  ctx-unknown-idle, api-err, idle-mid-task (abandoned), finished-impl (recommend
-  teardown), awaiting-restart, pending-human.
-- **BENIGN-ONLY** (never delivers on its own) — idle-no-task and/or bare ctx
-  tier1 (50-69%) alone. `flagged=20 tier3=0` where every one of those 20 is
-  benign-only does **not** fire an ALERT — `flagged` counts everything written
-  to the per-agent report; it does not imply delivery.
-- **Periodic all-clear heartbeat** — configurable via `.thrum/config.json`
-  `heartbeat.allclear_interval_min` (default 60). If no actionable ALERT has
-  fired for that long, the sweep emits the minimal `all-clear` line above so a
-  benign-quiet fleet is never mistaken for a dead monitor. Any delivered ALERT
-  (actionable or all-clear) resets this clock.
-
-The full per-agent report stays at `/tmp/agent-sweep.txt` (overwritten each
-sweep) for on-demand drill-down — read it AFTER receiving an ALERT to see which
-specific panes are at risk.
-
-The previous keepalive-cron pattern (CronCreate `<id>`) is deprecated in
-favor of this scheduled monitor. The bookkeeping responsibility moves out of the
-coordinator's per-session re-add chore and into the daemon's durable monitors
-table (survives daemon restart, no per-session re-init needed for this monitor —
-though OTHER CronCreate jobs may still require it per
-`feedback_cron_reinit_each_session`).
-
-## Lenses
-
-Every lens SURFACES or RECOMMENDS by default — none take autonomous action on
-their own. The ONLY exception is `context_tiers`' snapshot-gated restart, and
-even that requires an explicit `restart_actuation: true` opt-in in config. There
-is a single monitor for all lenses in v1, not one per lens.
-
-### Default-ON lenses (implemented, E1–E6)
-
-| Lens                        | Default | Disposition                                                                                                                                                       |
-| --------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `context_tiers`             | ON      | The ctx%/stuck-working ladder (L1). Sole autonomous actuator when `restart_actuation=true`; otherwise RECOMMEND via `recommend-restart-extended` reason in ALERT. |
-| `idle_mid_task`             | ON      | L2 — 30-min idle-with-open-task detection (bead cross-ref). RECOMMEND `/thrum:sleep-extended`; a no-task variant REPORTs `idle-no-task` at lower priority.        |
-| `snapshot_awaiting_restart` | ON      | L3 — pane text + fresh-snapshot two-signal heuristic. RECOMMEND `thrum tmux restart <agent>` (never autonomous).                                                  |
-| `blocked_on_human_modal`    | ON      | L4 — detects spend-limit/permission/consent modal prompts. DETECTION ONLY, never auto-answers; routes into the L5 ledger.                                         |
-| `pending_human_ledger`      | ON      | L5 — flat JSONL ledger of items awaiting a human. EXEMPT from progressive backoff — surfaces every tick. `hb_ledger_resolve` (the resolution path) is defined but has zero call sites — nothing marks an entry resolved, so the ledger is append-only-forever, not "until resolved." |
-| `waiting_on_coord`          | ON      | L9 — 21-rule pattern match (folded in from the standalone waiting-on-coord sweep) + warm-hold exemption. RECOMMEND coordinator answer.                            |
-
-### Default-OFF lenses (E8, flag-gated — NOT YET IMPLEMENTED as of E7)
-
-These lenses are reserved for E8. They exist as config flags for future work but
-produce no output until enabled.
-
-| Lens                    | Default | Disposition                      |
-| ----------------------- | ------- | -------------------------------- |
-| `merge_ready_queue`     | OFF     | L6 — REPORT                      |
-| `merge_reconciliation`  | OFF     | L7 — REPORT                      |
-| `base_deploy_staleness` | OFF     | L8 — REPORT                      |
-| `ready_vs_capacity`     | OFF     | L10 — RECOMMEND                  |
-| `stale_agent_gc`        | OFF     | L11 — propose-only GC, RECOMMEND |
-| `daemon_wedge_trend`    | OFF     | L12 — REPORT                     |
-
-## Configuration
-
-The heartbeat system is configured under the `heartbeat` key in
-`.thrum/config.json` (Go type: `HeartbeatConfig`). Example:
-
-```json
-{
-  "heartbeat": {
-    "schema_version": 1,
-    "enabled": true,
-    "cadence_minutes_day": 30,
-    "cadence_minutes_overnight": 60,
-    "busy_only_daytime": true,
-    "busy_signal": "working_or_activity_30m",
-    "overnight_window": {
-      "from": "22:00",
-      "to": "07:00",
-      "tz": "America/New_York"
-    },
-    "backoff": { "start_after": 2, "multiplier": 2, "floor_every": 4 },
-    "lenses": {
-      "context_tiers": {
-        "enabled": true,
-        "params": {
-          "restart_actuation": false,
-          "degrading_flag_after_ticks": 3
-        }
-      },
-      "idle_mid_task": { "enabled": true },
-      "...": "..."
-    }
-  }
-}
-```
-
-**Field reference:**
-
-| Field                                                    | Purpose                                                                                                                                                                |
-| -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `cadence_minutes_day`                                    | Daytime cadence target (default 30 min). The underlying monitor runs `@every 30m` and self-gates so only busy-fleet daytime ticks fire.                                |
-| `cadence_minutes_overnight`                              | Overnight cadence target (default 60 min). The monitor fires every other `@every 30m` tick overnight (effective 60-min rate).                                          |
-| `busy_only_daytime`                                      | When `true`, daytime ticks are skipped unless any agent has `agent_status=working` (busy-signal gate).                                                              |
-| `busy_signal`                                            | Algorithm for "is the fleet busy?" Default `working_or_activity_30m`: any agent working OR activity in the last 30 min.                                                |
-| `overnight_window.tz`                                    | **MUST be an explicit IANA timezone** (e.g. `"America/New_York"`). If unset, the sweep warns and falls back to always-daytime-rate rather than silently guessing. |
-| `backoff.start_after`                                    | Number of consecutive unchanged detections of the same problem before progressive backoff begins.                                                                   |
-| `backoff.multiplier`                                     | Each backoff step multiplies the surface interval by this factor (default 2×).                                                                                         |
-| `backoff.floor_every`                                    | The surface interval is capped at this many ticks — the problem is never fully silenced (always surfaces at least once per `floor_every` ticks).                       |
-| `lenses.<name>.enabled`                                  | Enable/disable a lens individually.                                                                                                                                    |
-| `lenses.<name>.params`                                   | Per-lens parameters. The only actuation opt-in in the whole system is `context_tiers.params.restart_actuation` (default `false`).                                      |
-| `lenses.context_tiers.params.degrading_flag_after_ticks` | After this many consecutive tier3 surfaced ticks without a successful restart, a `degrading-no-restart` reason is added to the ALERT (default 3).         |
-
-### Editing the config (there is NO `thrum config set`)
-
-`thrum config` only has a `show` subcommand — you **hand-edit
-`.thrum/config.json`** to configure the heartbeat. Two gotchas make this
-non-obvious; both bite silently.
-
-**1. All-or-nothing merge (the sharp footgun).** The config
-loader (`LoadThrumConfig`) applies
-`DefaultHeartbeatConfig()` **only when the stanza is effectively absent**
-(`schema_version == 0` AND zero lenses):
-
-```go
-if cfg.Heartbeat.SchemaVersion == 0 && len(cfg.Heartbeat.Lenses) == 0 {
-    cfg.Heartbeat = DefaultHeartbeatConfig()
-}
-```
-
-There is **no field-level deep merge.** The moment you write a stanza with
-`"schema_version": 1`, every field you _omit_ takes its Go zero-value —
-`cadence_minutes_day: 0`, `enabled: false`, and **all 12 lenses disabled**. So
-"I'll just set the timezone" with a three-line stanza silently turns the whole
-sweep off. **Always write the COMPLETE stanza** — copy
-`DefaultHeartbeatConfig()` in full, then change
-only what you need.
-
-**2. `overnight_window.tz` MUST be an explicit IANA zone.** Default is `""` (the
-source comment reads "TZ set by operator"). Left unset, the sweep prints
-`warning: heartbeat.overnight_window.tz not configured — using local time for gating`
-and falls back to the box's local clock (warns rather than silently
-guessing). Set it to the operator's zone, e.g. `"America/Los_Angeles"` (PST/PDT)
-or `"America/New_York"` (EST/EDT). Never `"local"`.
-
-**Procedure** — back up, write the full stanza, validate, done (no restart):
-
-```bash
-cp .thrum/config.json .thrum/config.json.bak
-# Build a COMPLETE heartbeat block mirroring DefaultHeartbeatConfig with your tz,
-# then splice it in (jq keeps the rest of config.json intact):
-jq --slurpfile hb /tmp/hb-block.json '.heartbeat = $hb[0]' .thrum/config.json > /tmp/c.json \
-  && mv /tmp/c.json .thrum/config.json
-jq -e '.heartbeat.overnight_window.tz != "" and (.heartbeat.lenses|length)==12' .thrum/config.json
-```
-
-**No daemon restart is required.** The scheduled monitor invokes the sweep
-_script_, which reads `.thrum/config.json` directly on every tick — the new tz
-takes effect on the next sweep. (`thrum config show` reflects the daemon's
-in-memory config, cached at boot, so it will lag until the next daemon start;
-that lag does not affect the script-driven sweep.) Avoid a
-restart-just-for-config — it needlessly risks a cold-boot WAL-replay
-brick.
-
-## Subagent model selection
-
-> **Model tiers:** pass an explicit `model:` on every dispatch; choose model and effort per the `choosing-subagent-models` skill (read `runtime.role_models` at the moment of use). Never let a sub-agent inherit your own model.
-
-## Step 1 — Run the sweep
-
-```bash
-bash scripts/error-and-context-agent-sweep.sh --out /tmp/agent-sweep.txt
-grep -E 'ctx_used:|^===== ' /tmp/agent-sweep.txt
-```
-
-The script emits one `ctx_used: X.X%` line per live agent. It captures the
-Claude Code status bar footer, normalizing UTF-8 non-breaking spaces
-(`\xc2\xa0`) before matching `Ctx Used: X.X%`. Runtimes without that footer
-(Codex, Cursor) fall back to `(n/a)`.
-
-## Step 2 — Threshold logic
-
-### 🔴 ORCHESTRATORS ARE NOT ON THE CONTEXT LADDER — they restart on a PLAN BOUNDARY
-
-**The context thresholds below are a COORDINATOR rule. Orchestrators inherited it
-rather than being chosen for it, and it is not cost-optimal for them.** Do not
-hold an orchestrator open to reach 70–75%, and do not restart one mid-plan to
-chase the cost curve.
-
-**The orchestrator rule:**
-
-> **Restart an orchestrator at PLAN COMPLETION — where completion means the plan
-> is MERGED *and* the follow-up beads filed during that plan have been FIXED.**
-> Not at the merge report. Not at the merge.
-
-**Why the follow-ups clause is load-bearing, not a detail.** The standing
-fix-while-warm rule says a bug found mid-work gets FIXED while warm, because
-file-and-move-on costs ~10x — the research has to be redone before the fix can
-start. Bugs found during a plan are therefore filed and swept up at the END of
-the plan, while the orchestrator *and its implementers* still hold the context.
-**A restart at the merge boundary destroys exactly that warmth, and does so
-INVISIBLY — the follow-ups still get done, just cold and at the 10x price.** A
-restart rule keyed to "the merge" does not merely mistime a restart; it silently
-repeals fix-while-warm.
-
-**Why the split is real, not stylistic**:
-
-- Per-turn cost scales LINEARLY with context size (the whole prefix is re-sent
-  and billed at the cache-read rate every turn), so cumulative session cost is
-  roughly QUADRATIC in how far context is allowed to grow. Break-even for a
-  restart is **under one turn** once context is meaningfully above the re-prime
-  floor.
-- **Orchestrators re-prime far cheaper than coordinators, and it is structural:**
-  the prime output filter gives ONLY `role=="coordinator"` the full
-  project-state passthrough. Measured orchestrator re-prime ≈ 30k tokens.
-- Coordinators keep the ladder below for a stated reason — larger re-entry cost,
-  plus decision-dense context a snapshot cannot faithfully reconstruct.
-
-**What the plan boundary buys:** it is the one point where the cost argument and
-the preserve-in-flight-judgment argument AGREE. The work has just been handed off
-in a merge report and the follow-ups are closed, so in-flight judgment is at its
-minimum and state is externalised into beads.
-
-**Applying it in this sweep:** an orchestrator flagged in the 50–85% bands is
-NOT a restart candidate on context alone. Check whether its plan is complete
-(merged + follow-ups closed). If it is, restart regardless of how low its
-context is. If it is not, leave it alone regardless of how high.
-
-
-
-| ctx_tier | stuck_working | Action                                                                                                                                                                                                                                                                   |
-| -------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| < 50%    | N             | No action — agent has runway                                                                                                                                                                                                                                             |
-| < 50%    | Y             | Tmux-send "are you stuck? `/continue` if waiting" nudge; if not recovered in next sweep, surface to operator                                                                                                                                                             |
-| 50-70%   | N             | **NOT a warning** — OPTIONAL restart-if-IDLE only: directed inbox restart request when the agent is idle. A BUSY agent (or a coordinator, or a warm-hold/on-call/parked consultant) at 50-70% gets no action — see role/state carve-out below. |
-| 50-70%   | Y             | Tmux-send nudge; defer the tier-1 directed restart request until the next sweep confirms the pane is active again AND ctx is still in this band                                                                                                                          |
-| 70-85%   | N             | Tmux-send `/thrum:restart` (bypasses inbox; more forceful) — for coordinators/warm-hold consultants ACTIVELY WORKING, this band doesn't apply until the role/state carve-out's higher floor (75%, see below)                                                             |
-| 70-85%   | Y             | Surface to operator immediately (degraded + stuck → human-eyes-needed)                                                                                                                                                                                                   |
-| > 85%    | any           | Snapshot-gated restart (opt-in): surface `recommend-restart-extended` by default; autonomous restart only when `restart_actuation=true` in config (see Step 5)                                                                                                       |
-| `(n/a)`  | any           | Pane capture failed OR runtime has no Ctx footer — check tmux session manually                                                                                                                                                                                           |
-
-**Role/state-aware carve-out:** coordinators, and any agent explicitly standing by as a
-warm-hold:/on-call:/parked: consultant in an ongoing impl, are treated exactly
-like a coordinator — while ACTIVELY WORKING (not idle) they only flag at
-**ctx >= 75%**, not the normal 50% `CTX_THRESHOLD`. An IDLE coordinator (or idle
-consultant) still flags at the normal threshold — idle restarts are cheap, no
-exemption needed there. Implemented as `hb_effective_ctx_threshold` in
-`scripts/heartbeat-lib.sh` — the 75% floor is a named var
-(`HB_COORD_CTX_THRESHOLD_WORKING`), a one-line swap if it ever changes. Locked
-test scenarios: coord@72%+working → NOT flagged; coord@76%+working → flagged;
-coord@60%+idle → flagged; non-coordinator roles are unaffected (still 50% while
-working or idle).
-
-**Warm-hold/on-call/parked exemption:** if the agent's `intent` field starts with `^warm-hold:`,
-`^on-call:`, or `^parked:`, skip nudge + restart for all tiers below >85% (and
-apply the coordinator-equivalent 75% floor above while working). The >85%
-bracket still fires regardless. These are EXPLICIT DECLARED states, not a
-heuristic guess at coordination intent — a consultant/on-call/done-planning
-researcher must set one of these prefixes ITSELF via
-`thrum session set-intent "warm-hold: <reason>"` (or `on-call:`/`parked:`).
-
-**A coordinator CANNOT set another agent's intent.** `thrum session set-intent`
-takes TEXT only — it sets the intent for the CURRENT SESSION and accepts no
-agent argument and no `--to`. To get an intent onto another agent, message that
-agent and have it set its own; then verify in the focused fleet view with
-`thrum team @AGENT --offline --include-inactive --json`
-rather than by counting acks.
-
-**Background-child-aware busy detection:** an agent with an OPEN in-progress bead, a recent JSONL tool_use
-(`state == "working"`), or a pane showing it's driving background sub-agents
-(`Waiting for N background agent...`) is BUSY, not idle — even if pane-silent.
-This is checked BEFORE the idle/abandoned classification (`hb_idle_classify`'s
-`is_busy` param) so an orchestrator quietly waiting on its own dispatched
-sub-agents is never misread as abandoned just because it hasn't committed
-recently.
-
-**Finished-impl teardown:** a closed bead + idle + no
-new dispatch classifies as `finished`, which surfaces a `recommend-teardown`
-ALERT to the coordinator — it is a RECOMMENDATION only, never autonomous;
-teardown itself stays coordinator-actuated (kill-tmux → worktree-teardown per
-lifecycle discipline in `implementer-status-and-handoff`).
-
-## Step 2.5 — Stuck-working axis
-
-`stuck_working` is **orthogonal** to `ctx_tier`. They can compound. Treat the
-table above as a composite lookup: the action depends on the _cell_, not on
-either axis alone.
-
-`stuck_working` measures "is this agent currently unable to make progress?"
-while `ctx_tier` measures "how soon will this agent degrade if left alone?" An
-agent can be:
-
-- ctx-fine but stuck-working (waiting on a hung tool call) → nudge to unstick
-- ctx-degraded but not stuck-working (working normally but burning context) →
-  restart cleanly
-- both → composite action per the table; high-degradation cases skip the nudge
-  step since the agent likely can't recover from the nudge alone
-
-The sweep's STUCK-WORKING classification (sweep script's per-agent
-`stuck_working` line + ALERT-line `stuck_working=N` axis) fires when:
-
-1. `agent_status = "working"` (the agent claims to be mid-work; set by the
-   Pattern D self-write in role skills), AND
-2. tmux silence > `SILENCE_THRESHOLD_MIN` minutes (default 10; tunable via
-   `--silence-threshold-min N`), AND
-3. JSONL transcript's last assistant message has `stop_reason = tool_use` AND
-   was emitted more than `SILENCE_THRESHOLD_MIN` minutes ago (Claude runtime
-   only; non-Claude runtimes use tmux silence alone)
-4. `intent` does NOT start with `^warm-hold:` (warm-hold exemption)
-
-The classification is sweep-side only — it does NOT write to identity files. The
-identity-file `agent_status="stuck"` semantic stays reserved for
-`permission.markAgentStuck` writes (permission-cadence give-up).
-
-**Reliability ladder rationale:** the inbox → tmux-send → snapshot-gated restart
-progression goes from polite to forceful. Inbox messages can fail (delivery
-bugs, agent too degraded to check inbox at high ctx, or the documented self-echo
-regression). Tmux-send types literally into the agent's input field — bypasses
-inbox entirely. The snapshot-gated restart (Step 5) bypasses the agent's
-willingness but not the worktree safety: it first solicits a snapshot, then
-restarts gracefully only after one lands.
-
-Agents degrade _silently_ before they blow; 50% is the "still coherent enough to
-write a good snapshot" window.
-
-## Step 3 — Directed inbox restart request for 50% – 70% agents
-
-```bash
-thrum send --to @<agent_name> --stdin <<'EOF'
-Your context is at ~X%. Please run /thrum:restart now — write your snapshot and I will re-dispatch after.
-EOF
-```
-
-The agent writes their restart snapshot to
-`.thrum/agents/<agent>/sessions/<timestamp>-restart.md` and goes idle.
-Coordinator waits for the "snapshot written" acknowledgement before
-re-dispatching the next task.
-
-If the agent acks without writing the snapshot first (anti-pattern), gently
-remind them to write the snapshot before going idle so the next session restores
-cleanly.
-
-If the agent doesn't respond within ~5 minutes OR you see them keep working,
-escalate to Step 4 (tmux-send nudge).
-
-## Step 4 — Tmux-send nudge for 70% – 85% agents
-
-The inbox path may not be reaching them at this context level. Bypass the inbox
-by typing the restart command directly into their input field:
-
-```bash
-thrum tmux send <tmux_session_name> '/thrum:restart'
-```
-
-If it exits 3 (Enter WITHHELD, text already typed) or 4 (verdict unknown), do NOT retype it: `thrum tmux capture` the pane and submit with `thrum tmux send <tmux_session_name> --keys Enter` only if no dialog is showing.
-
-(Find the tmux session name in sweep output — it's typically the worktree
-basename, e.g. `myepic-impl`, NOT the agent_id.)
-
-This causes the runtime to immediately execute `/thrum:restart` as if the user
-typed it. The agent writes their snapshot + restarts.
-
-If the tmux-send doesn't trigger a restart within ~5 minutes (agent may be too
-degraded to process input), escalate to Step 5 (snapshot-gated restart).
-
-## Step 5 — Snapshot-gated restart for >85% agents
-
-The >85% tier is the ONLY autonomous actuator in the whole heartbeat system —
-and even it is **opt-in, off by default**. The behavior is controlled by
-`heartbeat.lenses.context_tiers.params.restart_actuation` in config (default:
-`false`).
-
-### When `restart_actuation` is `false` (the default)
-
-The sweep does NOT restart anything. It emits a `recommend-restart-extended`
-reason in the ALERT line, surfacing the situation to the coordinator role. When
-this reason appears, decide whether to run `/thrum:restart-extended` on the
-agent — a deliberate, human-in-the-loop action. No automatic restart fires.
-
-### When `restart_actuation` is `true` (explicitly enabled by the operator)
-
-The sweep runs a 4-step snapshot-gated procedure automatically:
-
-1. **Capture pre-send timestamp** — record the current wall-clock time.
-2. **Send `/thrum:restart-extended` via raw tmux send-keys** — types the restart
-   command directly into the agent's pane (bypasses inbox).
-3. **Sleep a settle window** — default 180 s, tunable via `HB_SNAPSHOT_SETTLE`
-   env var.
-4. **Check for a FRESH snapshot file** — looks for a `*-restart.md` file in
-   `.thrum/agents/<agent>/sessions/` written within the freshness window
-   (default 200 s, tunable via `HB_SNAPSHOT_WINDOW` — a distinct env var from
-   Step 3's settle window, `HB_SNAPSHOT_SETTLE`):
-   - **Fresh snapshot found:** runs `thrum tmux restart <agent_id>` (graceful).
-     **NEVER `--force`.** The `thrum tmux restart` call in this path takes no
-     `--force` flag, by design — if the agent wrote a snapshot, there is no
-     reason to force-interrupt mid-call.
-   - **No fresh snapshot:** does NOT force anything. The agent is tracked in a
-     `no_snapshot` backstop instead (see A2 note below).
-
-**NEVER `--force`.** This path does not use `--force` under any circumstances.
-Forceful interruption of a mid-tool-call agent is not worth the risk when the
-graceful path is available and the agent has runway before catastrophic
-degradation.
-
-### Safety checks that still apply
-
-The following guards from "Pre-restart safety checks" carry forward and are
-checked BEFORE the snapshot-gated procedure fires:
-
-- **Warm-hold exemption** — if `intent` starts with `^warm-hold:`, skip ALL
-  restart actions for this agent (the >85% bracket is NOT exempt from warm-hold
-  in the snapshot-gated model; an operator who sets warm-hold is taking explicit
-  responsibility).
-- **Cooldown** — do not restart the same agent twice within 30 minutes. If an
-  agent crosses threshold again that fast, surface to operator rather than
-  restart-loop.
-- **No-restart-mid-merge** — never restart an agent whose pane shows a Git merge
-  conflict or active rebase. Surface to operator instead.
-
-### "degrading-no-restart" backstop
-
-If an agent stays at tier3 without a successful restart landing — whether
-because `restart_actuation` is `false`, or because a snapshot never appeared
-within the settle window — for N consecutive surfaced ticks (default: 3,
-config-tunable via
-`heartbeat.lenses.context_tiers.params.degrading_flag_after_ticks`), the sweep
-adds a distinct `degrading-no-restart` reason to the ALERT. This ensures the
-coordinator still sees that the agent needs eyes even when the system alone
-cannot fix it.
-
-### After a successful restart
-
-See "Post-restart procedure" below.
-
-## Step 6 — API-error recovery (who nudges depends on how the sweep runs)
-
-When you run the sweep **manually** (the command in Step 1, no flags), it still
-auto-nudges every agent whose pane shows an `API Error` line — it types
-`continue` into the affected pane via `tmux send-keys` (bypassing the
-`thrum tmux send` wrapper queue, which stalls on fully-silent panes). The report header lists who was auto-nudged:
-
-```text
-# auto-nudged 3 agent(s) on api_errors with 'continue':
-#   - impl_foo @ foo-impl:0.0
-#   ...
-```
-
-Pass `--no-nudge` (alias `--report-only`) to get a pure detection run with **no
-pane writes** — useful to inspect before acting.
-
-**The daemon does NOT auto-nudge from the sweep.** The daemon-hosted built-in
-sweep always runs the script with `--no-nudge`: a daemon must not silently type
-into agent panes as a side-effect of a _detection_ sweep. It reports flagged
-agents to the coordinator role only.
-
-**Deliberate daemon auto-remediation is a separate, opt-in feature**
-(`daemon.auto_remediation.enabled`, **default OFF**). When an operator turns it
-on, the daemon — not this skill — applies the recovery tier ladder:
-
-- 1st detection of an agent's API error → one `continue` nudge.
-- Still erroring on the next tick (nudge didn't clear it) → it escalates
-  SUSPECTED-STUCK to the operator chain instead of re-nudging (no nudge-loops).
-- It skips panes mid git merge/rebase, audits every nudge/escalation, and resets
-  an agent's state on recovery.
-
-So if `daemon.auto_remediation.enabled` is on, you don't manage API-error
-recovery by hand — the daemon does, with the same no-repeat + escalate
-safeguards described here.
-
-Anthropic 529s and rate limits are transient (typically resolve in
-seconds-to-minutes); the agent's previous tool call is queued in-session, so a
-single `continue` reactivates them without losing in-flight state.
-
-**When to escalate (manual runs / daemon off):** if the same agent shows an API
-error on TWO consecutive sweeps despite a nudge, the issue isn't transient —
-surface to operator as SUSPECTED-STUCK and investigate manually
-(status.claude.com, network, account limits). (When daemon auto-remediation is
-on, it raises this escalation for you.)
-
-**When NOT to nudge:** before shipping a release, to fold one more fix into the
-current cycle while an agent is stuck, run with `--no-nudge` (or hold the
-manual sweep). Once `continue` fires, the agent
-resumes its previous tool call immediately — there's no recovery window.
-
-## Pre-restart safety checks
-
-Whether triggered by the scheduled `context-monitoring` thrum monitor or by the
-coordinator manually invoking the skill, run these guards BEFORE firing a
-restart:
-
-1. **Verify the daemon is reachable**:
-   Run `thrum daemon status`; on error, skip the sweep and surface to operator.
-   Inspect the local online roster with `thrum team --json` (`.team.members`);
-   use `--offline --include-inactive` for offline, stale and retired rows.
-2. **Confirm the monitor is alive**: `thrum monitor list` should show
-   `context-monitoring` in `running` status with a non-empty `SCHEDULE` column.
-   If absent or dead, the scheduled ALERTs aren't firing and the skill must be
-   invoked manually from a recurring cron until the monitor is restored. (See
-   "Re-register the monitor" below.)
-3. **Check if any agent is mid-commit** (active tool call): look for
-   `Running bash` or active spinner in the sweep pane lines — if so, defer
-   restart for that agent until the tool completes.
-4. **Never restart (graceful or otherwise) an agent whose pane shows a Git merge
-   conflict or active rebase** — that corrupts the worktree. Surface to operator
-   instead.
-5. **Cooldown**: do not restart the same agent twice within 30 minutes. If an
-   agent crosses threshold again that fast, something's wrong with their
-   workload — surface to operator rather than restart-loop.
-
-### Re-register the monitor
-
-If `thrum monitor list` doesn't show `context-monitoring`, register it from the
-main repo. The script path must be absolute (the daemon runs the command from a
-clean env, not the coordinator's shell), so resolve it from the repo root first:
-
-```bash
-SCRIPT="$(git -C /path/to/thrum/main-repo rev-parse --show-toplevel)/scripts/error-and-context-agent-sweep.sh"
-thrum monitor add \
-  --name context-monitoring \
-  --schedule "@every 30m" \
-  --match '^ALERT:' \
-  --to coordinator \
-  -- bash "$SCRIPT" --no-nudge --out /tmp/agent-sweep.txt
-```
-
-(Or substitute the literal absolute path if no shell is handy in the
-daemon's environment.) The monitor fires one-shot per scheduled tick; in between
-ticks the child does not run, so there's no continuous CPU cost from the sweep.
-Note that `@every 30m` is the outer envelope — the sweep script self-gates
-so most ticks produce no ALERT output and thus no message fires.
-
-## Post-restart procedure
-
-When a restart fires (Step 4 or 5 — tmux-send nudge or snapshot-gated restart):
-
-1. Surface a brief status note to the coordinator: "Restarted @\<agent_name\>
-   at \<ctx\>% — snapshot at
-   `.thrum/agents/<agent>/sessions/<timestamp>-restart.md`".
-2. Wait for the agent to come back online (`thrum team @AGENT --offline --include-inactive` shows them online again,
-   or their pane shows the runtime prompt).
-3. Re-send their current dispatch with the full scope + plan refs + AC targets —
-   treat them as a fresh implementer who needs the full briefing again.
-4. Note any WIP files they may have left in their worktree from the prior
-   attempt (they'll audit salvage-vs-discard before substantive code).
-5. If they had a partial DONE, the coordinator's git log should still have it;
-   the agent may need a pointer to commits they shipped before the blow.
-
-## Reference
-
-- **Sweep script**: `scripts/error-and-context-agent-sweep.sh` (captures
-  `ctx_used: X.X%` from Claude JSONL transcript; falls back to pane scan for
-  non-Claude runtimes). Now part of a sweep-script family (sibling:
-  `waiting-on-coord-agent-sweep.sh`).
-- **Memory key**: project-local `coordinator-rule-context-check-broadcast` may
-  capture project-specific tweaks; load via
-  `thrum memory list --kind agent_rule --scope role`.
-- **Related discipline**:
-  - `feedback_restart_discipline` — burn the runway; don't preempt-restart at
-    clean checkpoints
-  - `feedback_byte_equality_pane_detection` — pane-snapshot byte diffs are
-    unreliable; use structural anchors + settle windows
-- **Why thresholds matter**: agents at 97% context silently produce degraded
-  output (missed instructions, partial tool calls, slow responses) before they
-  blow. The 70%/85% thresholds give the system 15-30% runway to extract a
-  snapshot or trigger a graceful restart cleanly.