@reddb-io/red-skills-dev 2.75.2

package/skills/engineering/afk/docs/CONFIG.md

@@ -0,0 +1,238 @@
+# AFK configuration & lifecycle hooks (reference)
+
+> Extracted from `afk/SKILL.md` for progressive disclosure. Consulted on demand — not the agent's step-by-step loop.
+>
+> Every `.red/config.yaml` knob and `RED_AFK_*` env var the loop reads, and the lifecycle-hook contract.
+
+## Configuration
+
+Scalar run settings live in `.red/config.yaml` under the `afk:` key (alongside the `afk.hooks` block documented below). Each one has a matching `RED_AFK_*` env override that wins over the config value, so an E2E/CI run can pick a setting without mutating the target repo's config.
+
+| Config key | Env override | Default | Meaning |
+|---|---|---|---|
+| `afk.default_runner` | `RED_AFK_RUNNER` | `claude` | Caller runner identity/default backend consumed before ambient sniffing. |
+| `afk.model` | — | runner-specific | Legacy global model override. Prefer tiered `afk.models.<runner>.<tier>.model` so Codex never receives a Claude-only model. |
+| `afk.models.<runner>` | — | runner-specific | Legacy per-runner scalar model override. Used only when no explicit tier model is set. |
+| `afk.models.claude.<tier>.model` | — | tier-specific | Claude Code model id for `validate`, `simple`, `complex`, or `think`. |
+| `afk.models.claude.<tier>.effort` | — | tier-specific | Claude Code effort for that tier. |
+| `afk.models.codex.<tier>.model` | — | tier-specific | Codex model id for `validate`, `simple`, `complex`, or `think`. |
+| `afk.models.codex.<tier>.effort` | — | tier-specific | Codex effort for that tier. |
+| `afk.sandbox` | `RED_AFK_SANDBOX` | `none` | Isolation backend (`none` \| `docker` \| `podman`, ADR 0033). |
+| `afk.max_iterations` | `RED_AFK_MAX_ITERATIONS` | `12` | Sandcastle re-invocation ceiling (issue #322) — the safety cap for "the agent never emits `<promise>DONE</promise>` or `<promise>BLOCKED</promise>`". The completion sentinel is the real terminator, so a normal issue finishes in 1–3 iterations; this leaves headroom without letting repeated no-sentinel failures run for too long. A non-numeric / zero / negative value in either the env or the config is ignored (falls through to the default) so a typo can never disable the cap or pin the agent to 1. |
+| — | `RED_AFK_IDLE_TIMEOUT_S` | `600` | Sandcastle's per-iteration **silence** watchdog (seconds): an iteration that produces no stream output for this long is aborted. The actual termination bound on a quiet hang. Env-only; typo-safe (non-numeric / zero / negative is ignored → default). |
+| `afk.claim_reaper.refresh_s` | `RED_AFK_CLAIM_REFRESH_S` | `300` | Cross-host stale-claim refresh cadence (seconds). The stale window is `refresh_s × (stale_tolerance + 1)`. |
+| `afk.claim_reaper.stale_tolerance` | `RED_AFK_CLAIM_STALE_TOLERANCE` | `3` | Consecutive missed claim refreshes tolerated before the stale-claim sweep may recover the issue. `0` is allowed. |
+| `afk.claim_reaper.grace_s` | `RED_AFK_CLAIM_REAPER_GRACE_S` | `300` | Minimum claim age before the stale-claim sweep may recover a `running` issue, even if the stale window is configured aggressively. |
+| `afk.claim_reaper.recent_commit_s` | `RED_AFK_CLAIM_REAPER_RECENT_COMMIT_S` | `2700` | Sliding progress-protection window: a live `afk/*/<issue>-*` attempt branch with a commit this recent protects the claimed issue from stale-claim recovery. |
+| `afk.statusline_cache_ttl` | `RED_AFK_STATUSLINE_CACHE_TTL_S` | `180` | TTL (seconds) of every EXPENSIVE FETCHED statusline number — the GitHub-derived queue/human + open-PR/open-issue counts AND the repo-global local diffstat, cached in `.red/state/statusline/statusline-cache.toon` / `.red/state/statusline/statusline-repo-cache.toon` (issue #1178, #1217). The statusline renders on every prompt, so a per-render gh/git round-trip would freeze the TUI; the network cost is paid at most once per TTL. Also drives the monitor's stale-cache marker. Use the **flat** key — do **not** nest it under `afk.statusline` (that key is the boolean statusline opt-out; YAML cannot make one key both a boolean and a map). Typo-safe (env > config > default): a non-numeric / zero / negative value in **either** source falls through to the next and ultimately the 180 default — never 0 (a 0 TTL would refresh on every render, defeating the cache). |
+| `afk.backpressure` | — | _(empty)_ | Ordered list of shell commands run as an extra pre-merge gate on the DONE path (issue #430, PRD #429). |
+| `afk.validation.node_max_old_space_mb` | — | `2048` | Node heap cap applied to feedback/backpressure validation subprocesses via `NODE_OPTIONS=--max-old-space-size=<mb>` (#1758). Keeps heavy Vitest/build validation bounded per worker. |
+| `afk.validation.vitest_max_workers` | — | `1` | Vitest worker fan-out cap exposed as `VITEST_MAX_WORKERS` to validation subprocesses (#1758). Repos with larger machines may raise it; the conservative default prevents width-2 fleets from multiplying heavy suites. |
+| `afk.validation.heavy_available_memory_mb` | — | `4096` | Minimum free-memory threshold for admitting known-heavy validation work (#1758). Heavy validation admission serializes when another heavy validation is active, and otherwise waits until this much memory is available. |
+| `afk.output_shaping.terse_steering` | — | `false` | Opt-in AFK output-shaping experiment (#1638). When true, even-numbered issues receive a phrasing-only terse steering block; odd-numbered issues are the holdout. The assignment is persisted in worker state beside heartbeat output-token counters and reported by `afk-output-shaping`. |
+| `afk.worktree_launches_pull_request` | — | `true` | Landing **mode**, decoupled from the branch-lock (ADR 0030 amended, #842). `true` (default) → the attempt lands via an **admin-merged PR** into the resolved base; `false` → a **direct merge** into that base (offline, no PR — only the post-commit push the worker already does). The branch-lock now only resolves the *target* base (lock > pin > main, ADR 0031); this flag decides PR-vs-direct **independently**. So: no lock + `true` → admin-PR to `main`; no lock + `false` → direct merge to `main`; lock=`X` + `true` → admin-PR to `X`; lock=`X` + `false` → direct merge to `X`. *How* a PR merges (admin vs `wait_for_review` vs `review_gate`) stays governed by `afk.merge.*`. **Migration:** the default `true` flips the old *locked* behaviour (which direct-merged) — a locked repo now gets an admin-PR to its lock branch; set `false` to keep the old offline/direct-promotion flow. |
+| `afk.merge.wait_for_review` | — | `false` | Merge-gate policy (ADR 0048). When `false` (default), the unlocked admin-merge proceeds **ignoring advisory review checks** (e.g. CodeRabbit) — the binding gates are `drift-guard` (the `pre_merge` hook) + in-process backpressure/feedback. When `true`, the unlocked landing **waits** for the configured review check to conclude before merging, then merges regardless of its verdict (the review stays advisory). `drift-guard` is a hard gate either way. |
+| `afk.merge.review_check` | — | `CodeRabbit` | Name (case-insensitive substring) of the advisory review check `wait_for_review` polls via `gh pr checks`. Only consulted when `afk.merge.wait_for_review` is `true`. |
+| `afk.merge.ci_aware` | — | `false` | CI-aware merge (#812). When `false` (default), the unlocked admin-merge fires immediately — correct only on a base with **no** required status checks. When `true`, the unlocked landing first polls `gh pr view --json mergeStateStatus,statusCheckRollup` until the PR settles, then admin-merges **only** once it is genuinely ready (`CLEAN`, or `BLOCKED` solely by a required review `--admin` waives). Required for any `enforce_admins` base, where an admin-merge **cannot** bypass required checks: a real conflict / `DIRTY` / `BEHIND` → `blocked:merge-conflict`; a **failed** required check → `blocked:ci`; checks still **pending** at the timeout → `blocked:ci` with the open PR preserved (never re-runs the inner agent). |
+| `RED_AFK_MERGE_CI_TIMEOUT_S` | env | `1800` | CI-aware merge wait budget, in seconds (#812). The poll runs at a fixed 10s cadence until `mergeStateStatus` settles; on timeout the open, MERGEABLE PR is handed off (`ci-pending` → `blocked:ci`) instead of re-running the agent. Non-positive / unparseable → the 1800s default. Only consulted when `afk.merge.ci_aware` is `true`. |
+| `afk.review_gate.enabled` | — | `false` | PR review gate (ADR 0064 §10, #749). When `true`, a completed **non-mechanical** attempt (classified tier at/above `afk.review_gate.threshold`) gets `ready-for-review` on its PR — firing the advisory review — and **holds the merge** for a fresh-agent review by a different agent than the one that implemented it. Mechanical/trivial work keeps the fast-merge path. Only affects a PR landing (`worktree_launches_pull_request: true`); a direct merge never opens a PR, so the gate is moot there. Off by default so the "merge fast / no drift" loop is unchanged until a repo opts in. |
+| `afk.review_gate.threshold` | — | `complex` | The cheapest issue-classifier tier (`validate` \| `simple` \| `complex` \| `think`) counted as non-mechanical. Tiers below it stay mechanical (fast-merge); this tier and above request review. |
+| `afk.companion.iteration_churn` | — | `8` | Companion (active) monitor drift threshold (#921): a live worker at/above this iteration **and** below `min_progress_loc` added lines is judged `iteration-churn`. Only read when `monitor --companion` / `--active` is set (off → byte-for-byte read-only dashboard, no gh writes). A non-positive override falls back to the default. |
+| `afk.companion.waiting_windows` | — | `20` | Companion drift threshold: a flat-diff worker with this many zero-progress waiting windows is judged `stuck-waiting`. |
+| `afk.companion.diff_drift_loc` | — | `4000` | Companion drift threshold: total churn (added + removed) at/above this is judged `scope-creep` (sprawling past the issue), the highest-priority signal. |
+| `afk.companion.min_progress_loc` | — | `5` | Companion progress floor: a worker that has added at least this many lines has produced real work and is never flagged for churn/stuck. |
+| `afk.companion.*` (cap) | `RED_AFK_RETRY_DRIFT` | `2` | Companion bounded re-enqueue budget. Each detected drift on an attempt injects **one** correction (write-only, idempotent via a fingerprint, rewriting `## Agent brief`); once the attempt count reaches this cap the companion **escalates** to `ready-for-human` (a `## Current blocker` of kind `drift`) instead of correcting again. Shares the bounded-recovery policy (`core/recovery.ts`); never kills a process — termination/respawn is the reaper + fleet's job. |
+| `afk.drain.max_cost_usd` | `RED_AFK_DRAIN_MAX_COST_USD` / `fleet --budget-usd` | _(unset)_ | Per-drain USD budget for the fleet supervisor. Spend is read from WorkerVitals (`current.cost_usd`) in worker state files, not a parallel ledger. Tiers are OK below 75%, WARNING at 75%, CRITICAL at 90%, and HARD_STOP at 100%. CRITICAL spawns new workers with one model-tier-policy downgrade; HARD_STOP stops all new spawns, lets in-flight workers finish, and records a TOON budget event in `.red/tmp/supervisors/default/supervisor.log.toonl`. |
+
+```yaml
+afk:
+  worktree_launches_pull_request: true   # true → admin-PR landing; false → direct merge (offline). Decoupled from the lock (#842)
+  models:
+    claude:
+      think:
+        model: claude-opus-4-8
+        effort: high
+    codex:
+      think:
+        model: gpt-5.5
+        effort: high
+  sandbox: none
+  max_iterations: 12      # override the default re-invocation ceiling here
+  statusline_cache_ttl: 180   # statusline gh/git cache TTL (seconds); flat key, NOT under afk.statusline
+  backpressure:           # extra pre-merge gate, runs after the feedback gate
+    - npm run test
+    - npm run lint
+  validation:
+    node_max_old_space_mb: 2048
+    vitest_max_workers: 1
+    heavy_available_memory_mb: 4096
+  output_shaping:
+    terse_steering: false # true → even issues steered, odd issues holdout; report with afk-output-shaping
+  merge:
+    wait_for_review: false   # true → hold the unlocked admin-merge until the review check concludes
+    review_check: CodeRabbit
+    ci_aware: false          # true → poll mergeStateStatus and merge only once required checks settle (#812; needed for enforce_admins bases)
+  review_gate:
+    enabled: false           # true → non-mechanical PRs get ready-for-review + hold the merge for a fresh-agent review
+    threshold: complex       # cheapest tier counted as non-mechanical (validate|simple|complex|think)
+```
+
+`RED_AFK_IDLE_TIMEOUT_S` is env-only (no `afk.*` config key); `sandbox`, `max_iterations`, and `statusline_cache_ttl` resolve env > config > default. The three runtime bounds — silence (`idleTimeoutSeconds`), re-invocation count (`maxIterations`), and the fixed no-commit-progress attempt guard — are detailed under *Attempt Completion & Termination Bounds*.
+
+### Backpressure gate
+
+`afk.backpressure` is an operator-declared, ordered list of shell commands that **supplements** the auto-derived feedback gate (it does not replace it). On a successful DONE attempt — after the scope-derived `test`/`typecheck`/`lint`/`build` feedback gate passes, before landing — AFK runs each backpressure command in order (`sh -c <command>`) against a checkout of the worker branch. If **any** command exits non-zero the merge is blocked and the issue is parked to `ready-for-human` with `blocked:validation`, exactly like a feedback failure: the failing command and its output tail land in the terminal envelope and in the `red.afk.validation.v1` validation sidecar (records named `backpressure:<command>`). An absent or empty block is a no-op (today's behaviour). The namespaced `plugins.dev.afk.backpressure` location is honoured with the legacy bare `afk.backpressure` fallback (ADR 0042).
+
+**This is how maintainers tell an inner agent the exact gate it must satisfy — without ad-hoc `-r` retry guidance.** When `afk.backpressure` is set, every inner-agent handoff carries a `<merge-gate>` section listing the configured commands verbatim, and the agent's exit-protocol completion contract instructs it to run and pass those commands *before* emitting `<promise>DONE</promise>` (issue #849). The contract distinguishes two kinds of check: the **touched-package confidence checks** the agent runs while developing (the package's own `test`/`typecheck`/`lint`/`build`) versus the **binding merge gate** the orchestrator enforces after DONE (these backpressure commands plus `drift-guard`). So for repos with a broader gate than any single touched package — `cargo fmt --all -- --check`, a workspace-wide `cargo clippy`, an integration smoke — declare it once under `afk.backpressure` and the agent sees and satisfies it on the first attempt instead of bouncing as `blocked:validation`. On a retry, the prior failure's command and output tail remain visible through `<prior-attempt-context>`, so the next agent can target the real blocker. The agent is told **not** to re-run an unbounded full repository suite after its final commit; the listed gate commands are the contract.
+
+### Merge-gate policy
+
+The unlocked admin-merge (`gh pr merge --admin --merge`, ADR 0030) **ignores advisory review checks by default** — this is intentional, not an oversight. The binding gates on a landing are:
+
+1. **`drift-guard`** — the `pre_merge` hook, a hard gate that aborts the merge for this issue and routes through bounded `blocked:merge-conflict` recovery.
+2. **In-process backpressure / feedback** — the pre-merge feedback-validation step (typecheck/tests, ADR 0008) that only mechanism can refuse a merge on.
+
+External advisory reviewers (CodeRabbit and the like) are **not** binding: the worker is autonomous, and gating an autonomous loop on a human-paced external reviewer would stall the queue (ADR 0048). Opt into waiting with `afk.merge.wait_for_review: true` — the unlocked landing then polls `afk.merge.review_check` until it concludes and merges regardless of the verdict (so its comments are posted before the merge, but the review never blocks the land). The wait is **fail-open**: a reviewer that never registers or never concludes within the poll budget does not wedge the landing.
+
+## Lifecycle Hooks
+
+`/afk` exposes a fixed set of lifecycle points declared in `.red/config.yaml` under `afk.hooks` and resolved as ordered lists of shell commands. Every hook follows a single interceptor contract:
+
+- Input: documented `RED_AFK_*` env vars (unset — *not* empty-string — when the field is irrelevant to the current point) plus the full mutable context as JSON on stdin.
+- Output: empty stdout → context unchanged; JSON object on stdout → AFK replaces the documented mutable slice with the returned value. Non-JSON stdout is treated as a parse failure.
+- Exit code: `0` continues the chain; non-zero is routed through a per-hook policy table — `pre_*` aborts the step, `post_*` / `on_idle` / `on_*_error` log and continue so a broken notifier never wedges AFK.
+
+Within a single hook list, **built-in defaults run first, user-declared commands run after**, and declaration order is preserved inside each group. A bare string is shorthand for a one-element list. An unknown hook name in `.red/config.yaml` is a hard error at session boot. Disable a built-in default with `afk.hooks.defaults.<name>: false` — reordering is not supported.
+
+Every hook command emits explicit dispatch breadcrumbs around the shell call:
+`[afk:hooks] <point>: enter: <command>` and
+`[afk:hooks] <point>: exit rc=<n>: <command>`. Session-scoped hooks write those
+lines to the session output, per-issue hooks write them to the attempt's
+`afk.log`, and fleet hooks use the analogous `[afk:fleet-hooks]` prefix in the
+supervisor log. A quiet Worker can therefore still show policy/hook activity
+without pretending the inner agent lane advanced.
+
+### Hook Hardening Contract
+
+Shipped RedSkills hook implementations and hook launchers must satisfy this
+checklist even though operator-authored AFK hooks may still use the lifecycle
+exit-code policy table above:
+
+- Exit 0 unconditionally. Blocking host hooks return a structured denial
+  payload on stdout; crashes and missing dependencies fail open with `{}`.
+- Drain stdin with a deadline. Shell hooks use
+  `timeout "${RED_SKILLS_HOOK_STDIN_TIMEOUT_S:-5s}" cat ... || true`; Node hooks
+  use an async bounded drain rather than `readFileSync(0)`.
+- Arm a bounded, unref'd process deadline for Node hook processes that do work
+  after startup. A hook must not keep a host session alive because a timer or
+  child process is still referenced.
+- Parse tool input as structured stdin JSON. Do not interpolate raw tool input
+  into a shell command string; if a hook must deny a command, emit JSON that asks
+  the host to deny it.
+
+Run `scripts/audit-hook-hardening-contract.sh` before shipping changes to
+`plugins/*/hooks/`, AFK library hooks, or hook launcher wrappers. The audit is
+intentionally greppable: it catches pattern-matchable regressions and includes a
+violating fixture that must fail.
+
+The full lifecycle table is defined in PRD #207. The hooks shipped so far:
+
+| Hook            | When it fires                              | Env vars              | Mutable slice   | Exit-code policy        |
+|-----------------|--------------------------------------------|-----------------------|-----------------|-------------------------|
+| `pre_session`   | Boot, before any queue work                | `RED_AFK_RUNNER`, `RED_AFK_WORKSPACE` | session config (`runner`, `worker_id`, `filter`, `iter_cap`) | non-zero **aborts** the session loudly |
+| `pre_pick`      | Before listing the tracker queue           | `RED_AFK_RUNNER`, `RED_AFK_WORKSPACE` | query params (`label`, `state`, `limit`) — `filter.{kind,value}` is read-only context | non-zero **aborts** the pick; queue listing is **skipped this iteration** and AFK falls through to the empty-queue / `on_idle` path |
+| `post_pick`     | After listing, before claiming             | `RED_AFK_RUNNER`, `RED_AFK_WORKSPACE` | `issues[]` (filter / reorder; replace with `{issues:[…]}`) — extra keys are silently ignored | non-zero is **logged** and AFK continues with the **un-mutated** list (defensive default — a broken filter must not silently drop work) |
+| `pre_worktree`  | After claim, before `git worktree add`     | `RED_AFK_RUNNER`, `RED_AFK_WORKSPACE`, `RED_AFK_ISSUE`, `RED_AFK_SLOT` | `issue`, `target` (worktree path), `env` (k/v map merged into the parent shell so `CARGO_TARGET_DIR` etc. propagate to the runner) — `branch` is read-only context | non-zero **aborts**: the claim is restored to `ready-for-agent`, the iteration tear-down runs, and the worktree is **not** created |
+| `pre_attempt`    | After worktree exists, **before each runner invocation** (per attempt, not per issue — re-fires on a `--fallback-runner` swap with `attempt_n=2`) | `RED_AFK_RUNNER`, `RED_AFK_WORKSPACE` (now the worktree), `RED_AFK_ISSUE` | `issue`, `workspace` (worktree path), `attempt_n` — `runner` is read-only context | non-zero **skips runner invocation**: the worktree is preserved, the heartbeat stops, and the claim is restored to `ready-for-agent` so post-pick state is reconciled cleanly |
+| `post_attempt`   | After the runner returned **with an authored `<promise>` exit** — DONE or BLOCKED — for that attempt. Does **not** fire on runner crash or EOF-without-sentinel (see `on_attempt_error`). Under `--fallback-runner` it fires once per runner invocation (the swapped-away attempt closes with `result.status=exhausted`). The parsed sentinel outcome (`done` / `blocked` / `no_more_tasks`, or `""` for the exhausted firings) rides in `result.outcome` (ADR 0028). | `RED_AFK_RUNNER`, `RED_AFK_WORKSPACE` (the worktree), `RED_AFK_ISSUE`, `RED_AFK_RESULT_STATUS` (`success` \| `fail`), `RED_AFK_RESULT_OUTCOME` (`done` \| `blocked` \| `no_more_tasks` \| empty) | `issue`, `workspace`, `result` (`{status, outcome}`), `attempt_n` | non-zero is **logged** and the loop continues — a broken notifier/pager must never wedge AFK |
+| `on_attempt_error` | When the attempt produced **no authored exit**: either an unhandled exception in the worker path (`run_inner` exited non-zero outside the quota branch — `runner-crash`), or the runner's pipe closed with **no `<promise>` sentinel** (EOF-without-sentinel — `no-sentinel`, ADR 0028; the issue routes through bounded `blocked:crashed` recovery). Distinct from `post_attempt` with `result.status=fail`, so hook authors do not have to demultiplex. | `RED_AFK_RUNNER`, `RED_AFK_WORKSPACE` (the worktree), `RED_AFK_ISSUE`, `RED_AFK_ERROR_CLASS` (`runner-crash` \| `no-sentinel`) | `issue`, `workspace`, `error` (`{class, rc}`), `attempt_n` | non-zero is **logged** and the loop continues |
+| `pre_feedback`  | After a green attempt, before the scope-derived feedback gate (the merge gate, ADR 0008) runs (#832). The resolved scopes are on stdin so a guard can veto validation. | `RED_AFK_RUNNER`, `RED_AFK_WORKSPACE` (the worktree), `RED_AFK_ISSUE` | `issue`, `workspace`, `scopes[]` | non-zero **aborts** the feedback gate; the attempt routes through the bounded `blocked:policy` (hook-aborted) recovery, branch/PR preserved |
+| `on_baseline_probe` | After the feedback gate **failed** and the "already failing on the base branch?" probe ran (ADR 0071). Fires only on a gate failure (the probe never runs on green). `downgraded[]` lists the checks reclassified from `failed` to `skipped` because they also failed on the baseline. | `RED_AFK_RUNNER`, `RED_AFK_WORKSPACE`, `RED_AFK_ISSUE` | `issue`, `workspace`, `ok` (always `false` here), `downgraded[]` — read-only context | non-zero is **logged** and the loop continues |
+| `on_feedback_classify` | After a feedback failure is classified **INFRA vs SEMANTIC** (ADR 0071), before the recovery routing reads the verdict. **Mutable**: a hook may override the classification. | `RED_AFK_RUNNER`, `RED_AFK_WORKSPACE`, `RED_AFK_ISSUE`, `RED_AFK_FEEDBACK_CLASS` (`infra` \| `semantic`) | `issue`, `workspace`, `class` (`infra` \| `semantic`) — return `{class:…}` to override; any other value keeps the computed class | non-zero is **logged** and the computed class stands |
+| `post_feedback` | After the scope-derived feedback gate produced its verdict (#832), on both pass and fail, before the merge or the failure routing. | `RED_AFK_RUNNER`, `RED_AFK_WORKSPACE`, `RED_AFK_ISSUE` | `issue`, `workspace`, `result` (`{status: pass\|fail}`) | non-zero is **logged** and the loop continues |
+| `pre_merge`     | Before the merge mechanism (`git merge --no-ff` into the pinned base). The diff between the merge base and the worker branch is on stdin so a guard hook can reject changes by size, file pattern, etc. The merge itself plus conflict resolution remain **mechanism** (ADR 0008) and sit between `pre_merge` and `post_merge` — never dispatched as a hook. | `RED_AFK_RUNNER`, `RED_AFK_WORKSPACE` (primary checkout), `RED_AFK_ISSUE`, `RED_AFK_MERGE_BASE` | `issue`, `workspace`, `diff` — `branch` is read-only context | non-zero **aborts the merge** for this issue; the failure surfaces as a worker-failure and routes through bounded `blocked:merge-conflict` recovery |
+| `post_merge`    | After a successful merge and push to origin/`{pinned}`. The merge commit already exists, so user notifiers can include the real merge commit URL. Does **not** fire when the merge was aborted (`pre_merge` rejection, conflict resolver exhausted, push rejected). | `RED_AFK_RUNNER`, `RED_AFK_WORKSPACE` (primary checkout), `RED_AFK_ISSUE`, `RED_AFK_MERGE_COMMIT` (full sha), `RED_AFK_MERGE_SHA` (short sha) | `issue`, `workspace`, `merge_commit` (`{sha, short}`) — extended by the built-in `validation` default with `result.{validation_status, validation_summary}` | non-zero is **logged** and the loop continues — the merge has already landed; a broken notifier or a flaky smoke test must never roll it back |
+| `on_attempt_timeout` | When the commit-anchored progress guard fires (ADR 0044/0045, #832): the attempt was alive but produced no new commit within the cap. Fires before the no-agent reconcile / escalation routing. | `RED_AFK_RUNNER`, `RED_AFK_WORKSPACE` (the worktree), `RED_AFK_ISSUE`, `RED_AFK_RECOVERY_REASON` (`timeout`) | `issue`, `workspace`, `attempt_n`, `reason` (`timeout`) — read-only context | non-zero is **logged** and the loop continues |
+| `on_recovery_decision` | After the disposition composer proposes **retry vs escalate** for a terminal failure (#832), before any label is applied. **Mutable**: a hook may override the decision. | `RED_AFK_ISSUE`, `RED_AFK_RECOVERY_DECISION` (`retry` \| `escalate`), `RED_AFK_RECOVERY_REASON` | `issue`, `decision` (`retry` \| `escalate`), `reason`, `attempt_n` — return `{decision:…}` to override | non-zero is **logged** and the composer's decision stands |
+| `on_blocked`    | After an issue is parked to a human gate (the escalate path, #832): the typed `blocked:*` label and `ready-for-human` are applied. | `RED_AFK_ISSUE`, `RED_AFK_BLOCKED_LABEL` (`blocked:<reason>`), `RED_AFK_RECOVERY_REASON` | `issue`, `blocked_label`, `reason`, `attempt_n` — read-only context | non-zero is **logged** and the loop continues |
+| `on_reconcile`  | After the no-agent reconcile (ADR 0055, #832) re-validated a parked mechanical branch and **landed / parked / skipped** it without re-running the agent. | `RED_AFK_ISSUE`, `RED_AFK_RECONCILE_OUTCOME` (`landed` \| `parked` \| `skipped`) | `issue`, `workspace`, `attempt_n`, `outcome` — read-only context | non-zero is **logged** and the loop continues |
+| `on_heartbeat`  | Once per attempt-guard poll (~60s) during an inner-agent run — a periodic proof-of-life point, not a once-per-lifecycle one. The context carries the **full worker vitals** (ADR 0065/#832: tools/text/reasoning/reasoning-tokens/loc/cost) so an operator can drive custom live alerting. | `RED_AFK_RUNNER`, `RED_AFK_WORKSPACE`, `RED_AFK_ISSUE`, `RED_AFK_VITAL_*` (one per numeric vital) | `issue`, `workspace`, `runner`, `attempt_n`, `vitals` (`{tools_called_count, text_chunk_count, reasoning_events, reasoning_tokens, waiting_count, input_tokens, output_tokens, cost_usd, loc_added, loc_removed}`) — read-only context | non-zero is **logged** and the loop continues |
+| `on_idle`       | Queue drained at top of loop iteration, before sleep/exit. Distinct from `post_session` — this is "between drains" maintenance (e.g. cache cleanup), not session termination. Does **not** fire on session exit. | `RED_AFK_RUNNER`, `RED_AFK_WORKSPACE` | none in this slice — `stats.{done,blocked,total}` are read-only context | non-zero is **logged** and the loop continues |
+| `post_session`  | Normal session termination                 | `RED_AFK_RUNNER`, `RED_AFK_WORKSPACE` | session stats (`runner`, `worker_id`, `stats.{done,blocked,total}`) | non-zero is **logged** and the session ends as `NO MORE TASKS` |
+| `on_session_error` | Last gasp — the AFK loop itself crashed (unhandled `set -e` exit, supervisor died, unrecoverable orchestrator exception). Distinct from `on_attempt_error` (a single attempt blew up; the loop continued) and from `post_session` (clean shutdown). This is the only path that guarantees a notification when the autonomous worker stopped without the operator noticing. Does **not** fire on a user-requested abort (`pre_session` rejection, straggler decline, Ctrl+C / SIGTERM through the cleanup trap) — those set the clean-exit sentinel before exiting. | `RED_AFK_RUNNER`, `RED_AFK_WORKSPACE`, `RED_AFK_ERROR_CLASS` (`session-crash` by default), `RED_AFK_ERROR_MESSAGE` | `error` (`{class, rc, message}`) — none mutable (the loop is already collapsing) | non-zero is **logged** but the process still exits — this hook cannot rescue the session, only announce its death |
+
+### Hook context schema (generated)
+
+> Generated from the canonical hook registry (`apps/dev/src/core/hook-registry.ts`, #834). A drift test (`hook-registry.test.ts`) fails if this block and the registry disagree, so the contract below can never drift from the wired hooks. Edit the registry, not this table.
+
+The stdin-JSON context each point receives, the **mutable slice** a hook may rewrite via stdout JSON (everything else is read-only context), and the exit-code policy class:
+
+<!-- BEGIN GENERATED: hook-context-schema -->
+| Hook | Stdin context (JSON) | Mutable slice | Exit policy |
+|---|---|---|---|
+| `pre_session` | `runner`, `worker_id`, `filter`, `iter_cap` | `runner`, `worker_id`, `filter`, `iter_cap` | non-zero **aborts** |
+| `pre_pick` | `label`, `state`, `limit`, `filter` | `label`, `state`, `limit` | non-zero **aborts** |
+| `post_pick` | `issues[]` | `issues[]` | non-zero **logged**, continues |
+| `pre_worktree` | `issue`, `target`, `env`, `branch` | `issue`, `target`, `env` | non-zero **aborts** |
+| `pre_attempt` | `issue`, `workspace`, `attempt_n`, `runner` | `issue`, `workspace`, `attempt_n` | non-zero **aborts** |
+| `post_attempt` | `issue`, `workspace`, `result`, `attempt_n` | `issue`, `workspace`, `result`, `attempt_n` | non-zero **logged**, continues |
+| `pre_feedback` | `issue`, `workspace`, `scopes[]` | `issue`, `workspace`, `scopes[]` | non-zero **aborts** |
+| `on_baseline_probe` | `issue`, `workspace`, `ok`, `downgraded[]` | _none (read-only)_ | non-zero **logged**, continues |
+| `on_feedback_classify` | `issue`, `workspace`, `class` | `class` | non-zero **logged**, continues |
+| `post_feedback` | `issue`, `workspace`, `result` | `issue`, `workspace`, `result` | non-zero **logged**, continues |
+| `pre_merge` | `issue`, `workspace`, `diff`, `branch` | `issue`, `workspace`, `diff` | non-zero **aborts** |
+| `post_merge` | `issue`, `workspace`, `merge_commit` | `issue`, `workspace`, `merge_commit` | non-zero **logged**, continues |
+| `on_attempt_error` | `issue`, `workspace`, `error`, `attempt_n` | `issue`, `workspace`, `error`, `attempt_n` | non-zero **logged**, continues |
+| `on_attempt_timeout` | `issue`, `workspace`, `attempt_n`, `reason` | _none (read-only)_ | non-zero **logged**, continues |
+| `on_recovery_decision` | `issue`, `decision`, `reason`, `attempt_n` | `decision` | non-zero **logged**, continues |
+| `on_blocked` | `issue`, `blocked_label`, `reason`, `attempt_n` | _none (read-only)_ | non-zero **logged**, continues |
+| `on_reconcile` | `issue`, `workspace`, `attempt_n`, `outcome` | _none (read-only)_ | non-zero **logged**, continues |
+| `on_idle` | `stats` | _none (read-only)_ | non-zero **logged**, continues |
+| `on_heartbeat` | `issue`, `workspace`, `runner`, `attempt_n`, `vitals` | _none (read-only)_ | non-zero **logged**, continues |
+| `post_session` | `runner`, `worker_id`, `stats` | `runner`, `worker_id`, `stats` | non-zero **logged**, continues |
+| `on_session_error` | `error` | _none (read-only)_ | non-zero **logged**, continues |
+<!-- END GENERATED: hook-context-schema -->
+
+**Attempt vocabulary & back-compat (issue #226, ADR 0026).** The attempt-level hooks were renamed from `pre_worker` / `post_worker` / `on_worker_error` to `pre_attempt` / `post_attempt` / `on_attempt_error` so "worker" unambiguously names the orchestrator process (`RED_AFK_WORKER_ID`) and the hooks align 1:1 with ADR 0017's `attempt` (one node = one runner invocation). They fire **per runner invocation**, so a `--fallback-runner` swap on one issue yields two `pre_attempt → post_attempt` cycles; `attempt_n` remains in the mutable hook context for the first runner versus fallback swap distinction, but it is no longer exported as a `RED_AFK_*` environment variable.
+
+### Built-in defaults
+
+Defaults are AFK-shipped commands registered before any user hook at the
+same lifecycle point. They run **first**, in a fixed registration order
+that users cannot change — only **disable** individual defaults via
+`afk.hooks.defaults.<name>: false`. The disable-not-reorder rule keeps
+later defaults (and user hooks) able to assume an earlier default has
+already had its turn at the env.
+
+Currently shipped:
+
+| Default  | Lifecycle point | Effect                                                                                  | Disable                              |
+|----------|-----------------|-----------------------------------------------------------------------------------------|--------------------------------------|
+| `cargo`  | `pre_worktree`  | When `Cargo.toml` exists at `$PROJECT_ROOT`, sets `CARGO_TARGET_DIR=${RED_AFK_CARGO_TARGET_BASE:-/opt/cargo-target}/slot-${RED_AFK_SLOT}` (mkdir-p'd) so each slot's cargo state is isolated. | `afk.hooks.defaults.cargo: false`  |
+| `gradle` | `pre_worktree`  | When `build.gradle*` exists at `$PROJECT_ROOT` **and** `RED_AFK_GRADLE_USER_HOME_BASE` is set, sets `GRADLE_USER_HOME=${RED_AFK_GRADLE_USER_HOME_BASE}/slot-${RED_AFK_SLOT}` so each slot's Gradle daemons / caches are isolated. The env-var opt-in is deliberate — AFK will not claim a path on your filesystem without consent. | `afk.hooks.defaults.gradle: false` |
+| `heartbeat` | `post_attempt`  | Stops the orchestrator's per-minute heartbeat sub-shell (`RED_AFK_HEARTBEAT_PID`) and appends the `iteration stopped` boundary marker to `RED_AFK_ITER_LOG`. Migrated from an inline `heartbeat_stop` call so the heartbeat now terminates *before* any user `post_attempt` hook runs. | `afk.hooks.defaults.heartbeat: false` |
+| `envelope`  | `post_attempt`  | Reconciles `result.status` onto the AFK state file (`current.result_status` in `RED_AFK_STATE_FILE`) so a user `post_attempt` notifier reading state sees the worker's terminal status without re-deriving it from the sentinel. | `afk.hooks.defaults.envelope: false` |
+| `validation` | `post_merge`  | Runs `pnpm test` / `typecheck` / `lint` / `build` against the merged primary checkout (when a `package.json` is present at the workspace root), then attaches `result.{validation_status, validation_summary}` to the post_merge context so user hooks see the CI/smoke outcome reconciled before they fire. Migrated from the inline post-merge CI/smoke call; the pre-merge feedback-validation step remains as the mechanism-owned safety gate (ADR 0008 — only mechanism can refuse a merge), so this default is observability + notification surface, not a gate. | `afk.hooks.defaults.validation: false` |
+
+Example configuration:
+
+```yaml
+afk:
+  hooks:
+    pre_session: "echo boot"            # bare-string shorthand
+    post_pick:
+      # filter the queue to issues you opened — RED_AFK_GITHUB_LOGIN must be set
+      - "RED_AFK_GITHUB_LOGIN=$(gh api user --jq .login) \
+         plugins/dev/skills/engineering/afk/examples/only-mine.sh"
+    pre_worktree:
+      # user hooks see CARGO_TARGET_DIR / GRADLE_USER_HOME already exported
+      # by the built-in `cargo` / `gradle` defaults that ran before them
+      - "echo isolated cargo dir: $CARGO_TARGET_DIR"
+    on_idle:
+      - "cargo clean -p reddb-storage"  # safe between drains, not on exit
+    post_session:
+      - "echo session done"
+      - "curl -s -X POST $SLACK_URL -d \"done=$(jq -r .stats.done)\""
+    defaults:
+      gradle: false                     # opt out of the gradle built-in
+```

package/skills/engineering/afk/docs/ENVELOPE.md

@@ -0,0 +1,177 @@
+# AFK terminal-event envelope, stage detection, live header, state file (reference)
+
+> Extracted from `afk/SKILL.md` for progressive disclosure. Consulted on demand — not the agent's step-by-step loop.
+>
+> The wire formats: the per-terminal-event issue comment (schema Slice C depends on), how stages are read off the agent stream, the live terminal header, and the `afk.state.json` schema.
+
+## Terminal-Event Envelope
+
+Every terminal event of an iteration posts **exactly one** structured comment on the issue. The comment is the canonical record of what the worker saw and did, and a future Slice C parser will reconstruct iteration history by walking these envelopes in a thread.
+
+Envelope statuses are the wire-level `data-attempt-status` facet. They are intentionally coarser than the full Attempt Outcome vocabulary below: several outcomes emit a `blocked` envelope, and some short-circuit outcomes record labels/history without a per-issue terminal envelope.
+
+| `data-attempt-status` | trigger |
+|---|---|
+| `blocked` | generic failure envelope: spec block, validation failure, or another failure folded into the blocked bucket |
+| `no-sentinel` | inner agent exited without `DONE` or `BLOCKED` and the path emits the crash envelope |
+| `merge-conflict` | orchestrator could not merge to `main` |
+| `done` | success — merged, closing envelope |
+| `discarded` | supervisor slot/circuit discard envelope |
+
+Attempt Outcome is the runtime's terminal vocabulary. It owns the typed `blocked:<reason>` label, recovery policy key, and envelope-status mapping:
+
+| Attempt Outcome | `data-attempt-status` | typed label | recovery |
+|---|---|---|---|
+| `done` | `done` | none | none |
+| `blocked` | `blocked` | `blocked:spec` | none |
+| `no-sentinel` | `no-sentinel` | `blocked:crashed` | `crashed` |
+| `merge-conflict` | `merge-conflict` | `blocked:merge-conflict` | `merge-conflict` |
+| `feedback-failed` | `blocked` | `blocked:validation` | none |
+| `hook-aborted` | `blocked` | `blocked:policy` | `policy` |
+| `exhausted` | `blocked` | `blocked:quota` | `quota` |
+| `runner-transient` | `blocked` | `blocked:runner-transient` | `runner-transient` |
+| `stalled` | `blocked` | `blocked:stalled` | none |
+| `infra` | `blocked` | `blocked:infra` | none |
+| `claim-lost` | `blocked` | none | none |
+
+Schema (deterministic — Slice C depends on this shape):
+
+```html
+<details data-attempt-status="blocked"><summary>worker `wZ2R4` · status: blocked · duration: 2m5s · diff: +42 -10 · attempt: 1</summary>
+
+<details data-section="notes"><summary>notes</summary>
+
+…handoff `<agent-notes>` body…
+
+</details>
+
+</details>
+```
+
+Per-status body sections:
+
+- `blocked` → one `data-section="notes"` block carrying the handoff's `<agent-notes>` body (the inner agent's appended progress/blockers).
+- `no-sentinel` → both `data-section="notes"` (handoff `<agent-notes>`, may be empty placeholder) **and** `data-section="log"` (last 50 lines of the captured inner-agent stdout, fenced).
+- `merge-conflict` → one `data-section="log"` block carrying the merge-conflict diff tail (last 50 lines of `git merge` output), fenced. Mirrors the no-sentinel log shape.
+- `done` → one `data-section="validation"` block carrying the package-aware feedback report. Summary carries `diff: merged` and `merge: ` `<sha>` (GitHub auto-links bare SHAs to the commit on `main`). The merge commit on `main` *is* the diff — no need to duplicate it inline.
+
+**User-hook executions section (issue #215).** Every non-`discarded` terminal Envelope also carries a trailing `data-section="hooks"` block when at least one **user-declared** lifecycle hook ran during the issue's lifecycle. Built-in defaults (`cargo`, `gradle`, `heartbeat`, `envelope`, `validation` — see the *Lifecycle Hooks* table) are deliberately excluded; the block exists to surface the policy the operator wrote in `.red/config.yaml`, not the skill's own machinery. Each line has the deterministic shape `<lifecycle_name> <command> exit=<rc>`, in execution order across the entire lifecycle (`pre_session` → `pre_pick` → `post_pick` → `pre_worktree` → `pre_attempt` → `post_attempt` → `pre_merge` → `post_merge` → `on_attempt_error` → `on_idle` → `post_session` / `on_session_error`). Non-zero exits are listed with their exit code — never omitted — so a reviewer can see which user-declared policy guarded the merge or mutated the queue, and whether it failed. When no user hook ran (the common case for projects without an `afk.hooks` block in `.red/config.yaml`), the section is omitted entirely rather than rendered empty. The `discarded` supervisor envelope never carries this section: discards record a slot-park decision made above the per-issue lifecycle, so no per-issue hook chain exists to enumerate.
+
+**Branch namespace — `afk/*` (issue #191, ADR 0103).** AFK uses one remote worker namespace:
+
+- `afk/{id}/{N}-{slug}` is the **live-iteration** branch. It's pushed at worktree-create (`push_initial`), kept in sync after every inner-agent commit by a per-worktree `post-commit` hook (`install_post_commit_hook`), and deleted on DONE after `gh issue close` succeeds (`delete_remote`). On any terminal failure the live ref is **not** deleted — it survives on origin so a human can `git fetch && git checkout afk/{id}/{N}-{slug}` to inspect mid-iteration state.
+
+### Validation Sidecar
+
+During feedback validation, AFK also writes a structured JSONL sidecar at
+`$ITER_DIR/validation.jsonl`. It is not rendered into the issue comment; it is
+the machine-readable source used by the optional Memory bridge.
+
+Each line is one command/check execution:
+
+```json
+{"schema":"red.afk.validation.v1","name":"test:plugins/memory","command":"pnpm -C /repo/plugins/memory test","status":"passed","durationMs":1234,"summary":"command exited 0"}
+```
+
+Fields:
+
+- `schema`: literal `red.afk.validation.v1`.
+- `name`: stable check name, usually `{script}:{scope}` such as `typecheck:root` or `lint:plugins/memory`.
+- `command`: command string when a command ran; omitted for skipped checks.
+- `status`: `passed`, `failed`, or `skipped`.
+- `durationMs`: command duration when a command ran.
+- `summary`: short relevant output/error summary, or a skip reason.
+
+The Memory attempt writer only consumes this structured sidecar after parsing it
+as JSON. It must not derive validation graph nodes by parsing free-form stdout,
+Envelope notes, validation-summary prose, or `<agent-notes>`.
+
+Summary line is always `worker `{id}` · status: {status} · duration: NmSs · diff: {diff} · attempt: K [· merge: {sha}]`, where `{diff}` is `+N -M` against `origin/main` for non-DONE statuses and the literal `merged` for DONE.
+
+After a successful POST (any 2xx), the orchestrator sets `envelope.posted: true` in the iteration state file. The boot-time *Orphan Cleanup* reads that field to pick a TTL for preserved `ready-for-human` dirs: 1 day when the envelope made it to the issue (the thread carries the canonical record), 7 days when the POST failed (the local dir is the only copy of the notes/log). The field is initialised `false` at iteration start.
+
+On any terminal **failure** (BLOCKED, no-sentinel, merge-conflict), the envelope's `data-section="diff"` block carries a clickable **live-branch** `tree/afk/{id}/{N}-{slug}` link (the live ref survives on origin after a terminal failure, so a human can `git checkout` it to inspect or continue, #443), the local worktree path, and a `+N -M files=K` diffstat. DONE iterations delete the live remote branch after the issue closes because the merge commit on `main` is the diff. Terminal failures do not create a separate snapshot branch; the envelope plus pushed worker-branch commits are the forensic record.
+
+The Slice D heartbeat-glyph cleanup has landed — there is no periodic `:one: :two: …` traffic on the issue thread to defer or replace.
+
+## Stage Detection
+
+Inner agent stages, derived from the sandcastle agent stream (the `onAgentStreamEvent` callback AFK fans into `agent.log.jsonl` + the firehose), not from a raw runner stdout pipe:
+
+| stage | signal |
+|-------|--------|
+| setup | first output line |
+| explore | `git ls-files`, `find`, repeated `Read` |
+| impl | first `Edit`/`Write` call |
+| tests | `pnpm test` invocation |
+| commit | `git commit` invocation |
+| merge | orchestrator stage, post-inner |
+| push | orchestrator stage |
+| close | orchestrator stage |
+
+Each transition writes to state file. The monitor renders the current stage.
+
+## Live Header
+
+Redraw every 3 s on the controlling TTY, top of the scroll buffer. Use `tput sc; tput cup 0 0; …; tput rc` so the inner agent's stream below stays intact.
+
+```
+┌─ /afk ────────────────────────────────────────────────────┐
+│ runner: codex          elapsed: 00:14:23   eta: ~01:20:00 │
+│ done: 3 / 12 (25%)     blocked: 0          merged: 3      │
+│                                                            │
+│ ▶ #142 wire OAuth callback                                 │
+│   worktree: .red/tmp/workers/wZ2R4/142-a1/worktree          │
+│   stage: impl                                              │
+│   last: writing tests for callback handler                 │
+│                                                            │
+│ queue: #143 #144 #145 #146 ...                             │
+└────────────────────────────────────────────────────────────┘
+```
+
+If stdout is not a TTY (CI, piped log), skip header rendering and print one JSON line per state transition to stderr.
+
+## State File
+
+Path: `.red/tmp/workers/{id}/{N}-a{n}/afk.state.json` — one snapshot per (worker, issue, attempt). Schema:
+
+```json
+{
+  "version": 1,
+  "worker_id": "wZ2R4",
+  "pid": 12340,
+  "pid_start_time": "123456789",
+  "log": ".red/tmp/workers/wZ2R4/142-a1/afk.log",
+  "started_at": "2026-05-16T12:00:00-03:00",
+  "runner": "codex",
+  "filter": { "kind": "prd|issues|all", "value": "42" },
+  "total": 12,
+  "done": 3,
+  "failed": 0,
+  "blocked": 0,
+  "completed": [139, 140, 141],
+  "queue": [143, 144, 145, 146],
+  "current": {
+    "number": 142,
+    "title": "wire OAuth callback",
+    "slug": "wire-oauth-callback",
+    "worktree": ".red/tmp/workers/wZ2R4/142-a1/worktree",
+    "handoff": ".red/tmp/workers/wZ2R4/142-a1/handoff.md",
+    "started_at": "2026-05-16T12:14:00-03:00",
+    "stage": "impl",
+    "heartbeat_glyph": null,
+    "heartbeat_pid": null,
+    "runner": "codex",
+    "retries": 0,
+    "last_stream_line": "writing tests for callback handler"
+  },
+  "durations_seconds": [820, 940, 760],
+  "envelope": { "posted": false }
+}
+```
+
+`pid_start_time` is a best-effort process identity token paired with `pid`
+(Linux `/proc/<pid>/stat` field 22). It is empty on legacy or unsupported
+platforms; readers then fall back to pid-only liveness.
+
+Atomic write: write to `afk.state.json.tmp` inside the attempt directory, `mv` over the original. `/afk monitor` and any other reader open it read-only. Between issues the worker has no live state file — monitor renders that as "idle".

package/skills/engineering/afk/docs/HANDOFF.md

@@ -0,0 +1,70 @@
+# AFK handoff file template (reference)
+
+> Extracted from `afk/SKILL.md` for progressive disclosure. Consulted on demand — not the agent's step-by-step loop.
+>
+> The exact `handoff.md` the inner agent reads — the XML-wrapped issue body, prior attempts, human guidance, and agent notes.
+
+## Handoff File Template
+
+`.red/tmp/workers/{id}/{N}-a{n}/handoff.md`:
+
+Top-level content is XML elements (not markdown headers) so the inner agent
+cannot confuse the issue body with comments, or human direction with
+orchestrator audits. Markdown sections like `## Agent brief`, `## Acceptance`,
+`## Refs`, and `## Suggested Skills` live *inside* the `<issue-body>` element
+(they are part of the issue body verbatim).
+
+```markdown
+# Issue #{N} — {title} [AFK]
+
+source: {gh-url}
+prd: {prd-url-or-issue-ref}        # omit if none
+runner: {claude|codex}
+started: {iso8601}
+attempt: {1..}
+
+<issue-body>
+{issue body verbatim — includes the `## Agent brief`, `## Acceptance`, `## Refs`,
+and `## Suggested Skills` markdown sections written by /triage}
+</issue-body>
+
+<previous-attempts>                                    <!-- omitted when empty -->
+<previous-attempt n="1" status="blocked" worker="wXXXX" duration="0m50s" branch="afk/wXXXX/N-slug">
+<notes>
+{inner agent's appended notes from prior attempt}
+</notes>
+<log>
+{tail of prior attempt's stdout, if captured}
+</log>
+</previous-attempt>
+</previous-attempts>
+
+<prior-attempt-context>                                <!-- omitted on a first attempt -->
+prev-attempt: 1
+prev-snapshot-branch: (none)
+prev-failure-reason:
+{verbatim failure.reason from the previous attempt — the envelope summary}
+{branch fresh off the base — do NOT fix-forward on prior history}
+</prior-attempt-context>
+
+<human-guidance-thread>                                <!-- omitted when empty -->
+<human-guidance author="@alice" at="{iso8601}">
+{verbatim content of one extracted <details data-kind="directive"> marker — one
+<human-guidance> element per directive, so a single comment carrying two markers
+emits two siblings with identical author/at}
+</human-guidance>
+</human-guidance-thread>
+
+<thread-discussion>                                    <!-- omitted when empty -->
+<thread-discussion-entry author="@alice" at="{iso8601}">
+{human comment body verbatim that carried no directive marker — advisory only,
+lowest authority; orchestrator audits already filtered out by body shape}
+</thread-discussion-entry>
+</thread-discussion>
+
+<agent-notes>
+<!-- inner agent appends progress/blockers here across attempts -->
+</agent-notes>
+```
+
+The handoff file follows the same minimalism as the `/handoff` skill — reference artifacts by path, do not duplicate their content.

package/skills/engineering/afk/docs/LIVENESS.md

@@ -0,0 +1,56 @@
+# AFK liveness: heartbeat + solo-run stall protection (reference)
+
+> Extracted from `afk/SKILL.md` for progressive disclosure. Consulted on demand — not the agent's step-by-step loop.
+>
+> How a running worker signals it is alive and how a hung inner agent is caught. Bundle-internal; the agent does not drive these.
+
+## Heartbeat (local-only, post-Slice-D)
+
+The issue-thread heartbeat (`:one:` / `:two:` / `:three:` / `:four:` cycling every 10 minutes via `gh issue comment`) was removed in Slice D. The issue thread is now timeline-only: boot stamp, attempt envelopes, human guidance, closing envelope. No periodic noise.
+
+Local liveness is signalled by:
+
+- **Inner-agent stream**, captured by sandcastle whose `logging.path` lane is pointed at the attempt dir's **`afk.log`** (the one unified human log — no separate `sandcastle.log`), and surfaced through the `onAgentStreamEvent` callback AFK forwards into the JSONL lanes — forensic inspection of a running worker tails this file. Because red-castle's file-log IS `afk.log`, the setup phase it narrates (worktree / sandbox / deps) lands there too, so the log is never empty before the agent streams; the plaintext `[agent]` mirror is dropped so turns are not doubled.
+- **Clean agent lane + firehose** (issue #250) — alongside `afk.log`, the runtime fans each assistant turn out to a clean single-writer `agent.log.jsonl` TOONL lane (one `type=agent` record per turn, nothing synthetic — the true liveness signal, readable as a live transcript with `tail -f … | tq -p toonl -o json -r .msg`) and to a `log.jsonl` firehose that also carries the heartbeat vitals, hook dispatches, runner timings, and errors in the uniform envelope. `tq` is a pinned required host binary, so there is no jq fallback for reading RedSkills-owned TOONL lanes. The heartbeat writes its vitals to the firehose as a `type=heartbeat` record but never to the agent lane, so the agent lane's silence is real silence (the masking that defeated stall/reaper detection in #243). `afk.log` now carries red-castle's unified stream (setup narration + agent text/tools) plus the `[heartbeat]` lines.
+- **Fleet supervisor firehose** — the supervisor's shared live lane at `.red/tmp/supervisors/default/supervisor.log.toonl` is written as append-only TOONL records with an honest extension. A one-time boot migration moves the legacy structured firehose copies out of `.red/tmp/` / `.red/state/afk/` / `.red/state/castle/`. Tail heartbeat messages with `tail -f .red/tmp/supervisors/default/supervisor.log.toonl | tq -p toonl -o json -r .msg`. Readers sniff each row, so older JSONL rows and mixed legacy+TOONL files remain readable; history is never rewritten.
+- **Monitor activity counters** — compact `/afk monitor --once` renders the canonical WorkerVitals activity group (`tools:<n> reason:<n> text:<n> wait:<n>`) and a cursor-backed `afk.log` line count (`log:<total>(+<new>)`). These are tie-breakers for the common "quiet but pid-live" case: agent-lane silence alone must not mark a Worker done while the orchestrator pid is still alive.
+- **State-file liveness verdict**, derived once by the Worker state reader. The monitor pairs the orchestrator `pid` with `pid_start_time` when the platform exposes a stable process-start token, so a recycled PID does not resurrect a finished worker. It then combines pid identity with activity freshness to render `[live]` (pid identity matches + recent activity), `[quiet]` (pid identity matches, agent lane quiet), or `[stale]` (pid dead/identity mismatch).
+- **Iteration boundary markers** — `heartbeat_start` / `heartbeat_stop` write a single `[heartbeat] iteration started/stopped` line each to `afk.log` so forensic readers can see when an iteration entered and left the inner-agent stage.
+- **Periodic orchestrator heartbeat** (issue #194) — `heartbeat_start` also spawns a side-channel sub-shell that appends one line every `RED_AFK_HEARTBEAT_S` (default 60s) to `afk.log`:
+
+  ```
+  [heartbeat] stage:tests t+00:14:02 last_stream_line="..." cpu=12% rss=420M
+  ```
+
+  The loop re-reads `current.stage` and `current.last_stream_line` from `afk.state.json` on every tick (so a mid-iteration stage flip shows up in the next heartbeat) and reads cpu/rss from `ps` against the orchestrator pid. Because it lives in its own sub-shell — independent of the inner-agent stream tee that buffers inside the runner pipeline — a forcibly hung worker (`kill -STOP` on the inner agent, or a runner that never flushes) still produces one heartbeat line per minute with stage frozen and wall-clock advancing. The `no-sentinel` envelope's `data-section=log` carries these lines, so the issue thread alone is enough to diagnose where the hang occurred. Set `RED_AFK_HEARTBEAT_S=0` to disable the periodic loop (boundary markers still fire).
+
+The terminal header has its own independent 3 s redraw tick — see *Live Header* below. It is unrelated to (and survives the removal of) the GitHub-thread heartbeat.
+
+**Deprecated state fields.** `current.heartbeat_glyph` and `current.heartbeat_pid` are kept as `null` for one release window so older monitors don't error on read; they are no longer written meaningfully and may be removed in a future release.
+
+## Solo-run stall protection (issues #400, #363)
+
+A solo `/afk run` worker is protected against a hung inner agent by **two complementary in-process layers**, both armed only under no-sandbox isolation (under docker/podman the agent commits and builds in an isolated copy the host can't see, so both guards stand down and only the per-iteration idle timeout + max-iterations apply):
+
+- **Attempt progress guard (#400, commit-anchored).** Polls the worker branch HEAD on the attempt-guard cadence and **aborts the run when no NEW commit lands within 2700 seconds**, resetting the deadline on every commit. This catches the *productive-looking infinite loop* — an agent that is busy and emitting output but never converging on work. The abort maps to the `timeout` outcome → `blocked:stalled`, `ready-for-human`, PR/worktree preserved. It is the backstop for the fatal "hang forever" case (applies solo and fleet) and is the **progress** signal — never duplicated by the layer below.
+- **Lane-idle reaper (#363, idle-anchored).** The solo-path port of Fleet Mode's passive stall detector + hard stall reaper, reusing the SAME fleet detector (`computeStalled`) and reaper-signal busy-predicate (`deriveSnapshot` + `decideReaperSignal`) — not a second mechanism. It samples the active attempt's **agent lane** `agent.log.jsonl` mtime (the clean liveness signal — never `afk.log` / the firehose `log.jsonl`, which the per-minute heartbeat keeps fresh and would mask a real stall, the #243 masking) every `RED_AFK_STALL_POLL_S` (default 30s) on a side-channel poll independent of the inner-agent stream, so a fully-hung runner is still observed. A worker alive ≥ `RED_AFK_STALL_THRESHOLD_S` (default 600s) whose agent lane has been idle ≥ the same is a **candidate**; once the lane is idle past `RED_AFK_STALL_KILL_THRESHOLD_S` (default 1800s) the irreversible kill is **gated behind the busy-predicate** — a worker with an active `vitest`/`tsc`/`cargo`/build descendant under its process tree, or non-trivial aggregate cpu, is **busy** and left alone, while a genuinely stuck worker [idle past the threshold, no active descendant, flat cpu] is reaped tree-wide (SIGTERM then SIGKILL after the grace). The reap aborts the run → `no-sentinel`, which flows through the existing no-sentinel terminal policy (envelope with the attempt-dir `afk.log` tail, label rotated back to `ready-for-agent`/`ready-for-human`, worktree dropped). This is the **faster idle layer**: it cuts an idle hang at the stall threshold (minutes) rather than only at the progress cap. `RED_AFK_STALL_KILL_THRESHOLD_S` must be strictly greater than `RED_AFK_STALL_THRESHOLD_S`, validated at boot (the same invariant the supervisor enforces) — a `<=` config fails fast before the run claims an issue.
+
+The two layers share the run's `AbortController`: progress watches commits, lane-idle watches the agent lane. The threshold env vars (`RED_AFK_STALL_THRESHOLD_S`, `RED_AFK_STALL_KILL_THRESHOLD_S`, `RED_AFK_STALL_POLL_S`) are consistent with Fleet Mode.
+
+## Host-level OOM signature (#1758)
+
+When the worker log, supervisor tick log, and an unrelated interactive operator
+session all stop in the same short window, treat it as a host-level kill/OOM
+signature, not a worker-code bug. The expected recovery path is:
+
+- relaunch the fleet;
+- let the boot sweep reconcile any dangling `running` claims and stale slots;
+- inspect the preserved pushed `afk/*` branch before deciding whether work was
+  lost.
+
+Heavy validation suites are bounded by `afk.validation.*` config: validation
+subprocesses receive a Node heap cap and Vitest worker cap, and known-heavy
+validation admission serializes when another heavy validation is already active
+or when available memory is below the configured threshold. On small reference
+machines, keep the default `vitest_max_workers: 1` and avoid raising fleet width
+without also raising the per-host memory budget.