@reddb-io/red-skills-dev 2.75.2

package/skills/engineering/afk/fleet.md

@@ -0,0 +1,127 @@
+# AFK Fleet Mode — running `afk fleet` (multi-worker supervisor)
+
+This file serves the `afk fleet` branch: launching, stopping, and supervising `N`
+concurrent `run` workers on one checkout. Reached from *When To Use*
+(`/afk fleet [N]`, `/afk fleet stop`) in [`SKILL.md`](./SKILL.md).
+
+## Fleet Mode (runner-portable — binding)
+
+`/dev:afk fleet [N]` and `/dev:afk fleet stop` are the user-facing fleet commands. They let one terminal command spin up (or shut down) `N` concurrent `run` workers on the current checkout, with the supervisor handling respawn, the circuit breaker, the **passive stall detector** (samples each slot's per-attempt **agent lane** `agent.log.jsonl` mtime — the clean liveness signal — every `RED_AFK_STALL_POLL_S=30s`; flags any slot alive ≥ `RED_AFK_STALL_THRESHOLD_S=600` whose agent lane has been idle ≥ the same — surfaces as `⏸️ stalled` in `/dev:afk monitor`. It keys off the agent lane, never `afk.log`/`log.jsonl`, because the orchestrator heartbeat writes those every minute and would mask a real stall — the masking that defeated detection in #243), the **hard stall reaper** (a slot silent on the agent lane past `RED_AFK_STALL_KILL_THRESHOLD_S=1800` is only a *candidate*: the irreversible kill is gated behind a reaper-signal predicate, so a worker mid-build/test — an active `vitest`/`tsc`/`cargo`/… descendant under its 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 killed tree-wide, a `data-attempt-status="no-sentinel"` envelope is posted with the attempt-dir `afk.log` tail, the issue label is rotated back to `ready-for-agent`, the worktree + attempt dir are removed, and the slot is freed for the next health-check respawn — `RED_AFK_STALL_KILL_THRESHOLD_S` must be strictly greater than `RED_AFK_STALL_THRESHOLD_S`, validated at supervisor boot), and per-slot build isolation.
+
+**Worker env passthrough.** Any `RED_AFK_*` variable exported in the operator's shell before `/dev:afk fleet` is auto-forwarded to every worker the supervisor spawns. Use this for worker-side toggles like `RED_AFK_SKIP_PERF=1` or `RED_AFK_SKIP_COMPETITIVE_BASELINE=1` without writing a hook. Internal supervisor knobs (`RED_AFK_TARGET`, `RED_AFK_POLL_S`, `RED_AFK_STALL_*`, `RED_AFK_CIRCUIT_*`, `RED_AFK_RUNNER`, `RED_AFK_REQUEST`, `RED_AFK_PLUGIN_DIR`) and the per-slot `*_BASE` build-isolation vars are excluded — they have dedicated wiring and the supervisor denylists them from passthrough. The supervisor re-pins `RED_AFK_RUNNER=<runner>` for each worker.
+
+```bash
+$ export RED_AFK_SKIP_PERF=1
+$ export RED_AFK_SKIP_COMPETITIVE_BASELINE=1
+$ /dev:afk fleet 1   # every worker sees both vars
+```
+
+Fleet mode is **runner-portable**: the supervisor is plain process orchestration, not a Claude Code primitive. Claude Code, Codex, and bare terminals may all launch and stop the supervisor when the normal AFK hard preconditions pass. Runner-specific observability degrades independently:
+
+- Claude Code: launch fleet. For manual monitoring, run `/dev:afk monitor` or tail `.red/tmp/supervisors/default/supervisor.log.toonl`.
+- Codex: launch fleet with `RED_AFK_RUNNER=codex` and spawn one read-only Codex monitor agent from the bundle's `codex-monitor-agent --mode fleet` prompt when a sub-agent primitive is available. If no sub-agent primitive is available, launch fleet anyway and print `monitor loop unavailable in this runner; run /dev:afk monitor or tail .red/tmp/supervisors/default/supervisor.log.toonl manually.`
+- Bare terminal / unknown runner: launch fleet and print the manual-monitor guidance.
+
+**Release recycle rule.** A fleet supervisor keeps running the exact dev bundle
+version it was launched from. After any RedSkills release that changes AFK or
+castle engine behavior, stop and relaunch the fleet before starting or counting
+a proving drain; otherwise the drain may still be executing on the pre-release
+engine. `monitor` and the statusline fleet cell show the running bundle version
+and mark skew against a newer locally cached bundle so stale supervisors are
+visible. Automatic drain-and-respawn on version change is a future enhancement,
+not part of the current fleet contract.
+
+### `/dev:afk fleet [N]` — launch
+
+`N` is optional and defaults to `2`. Parse it as a non-negative integer; reject anything else (including `stop`, which is the other subcommand and routes below). Steps the agent must perform, in order:
+
+1. **Resolve runner.** Determine the active runner using the same intent as the normal AFK cascade: explicit user `--runner` if present, else `RED_AFK_RUNNER`, else runner env/process/path signals, else `claude`. The resolved value is carried into the supervisor as `RED_AFK_RUNNER=<runner>` so detached workers do not fall through to the supervisor's historical `claude` fallback. Under Codex, this must resolve to `codex`.
+2. **PID-file pre-check / live directive.** Read `.red/tmp/supervisors/default/afk-supervisor.pid`. If it exists and `kill -0 <pid>` succeeds, do not launch a second supervisor. Instead the bundle command writes the `afk-supervisor.resize` directive file in the supervisor runtime lane (`.red/tmp/supervisors/default/`) as the live directive:
+   - `fleet <N>` changes the desired worker count while keeping the current runner.
+   - `fleet <N> --shrink-mode hard-kill|drain-then-retire` changes the resize shrink behavior. The default is `drain-then-retire`.
+   - `fleet <N> --runner <runner>` asks the running supervisor to switch runner. A changed runner is applied by re-pinning the supervisor's worker env, marking every live slot `drain-then-retire`, letting in-flight claims finish, then respawning replacement slots on the new runner. An unchanged runner is a no-op.
+   After writing the directive, the launcher reads `.red/tmp/supervisors/default/state.toon` and prints `fleet directive applied ...` when the heartbeat already echoes the requested target/runner/shrink-mode, or `fleet directive pending ...` while waiting for the next supervisor tick to apply it.
+
+   Older launch guidance used to say a live supervisor is refused:
+   ```
+   ✗ fleet already running (supervisor pid=<pid>, log .red/tmp/supervisors/default/supervisor.log.toonl).
+     to stop it: /dev:afk fleet stop
+   ```
+   That remains the model for truly conflicting second supervisors, but `fleet <N>` is now the supported live resize/switch surface. A stale PID file (file exists but `kill -0` fails) is left alone — the `fleet` command clears it itself when it acquires the supervisor lock.
+3. **Launch the fleet.** From the project root, run the bundle's `fleet` command with the target and any flags:
+   ```bash
+   RED_AFK_RUNNER=<runner> red-skills-dev fleet <N> [--request <text>]
+   ```
+   The command performs the PID-file pre-check from step 2 itself (refusing if a live supervisor already runs), detaches the supervisor, and forwards the resolved runner and the `--request/-r` text to every worker it spawns. It waits up to 3 s for `.red/tmp/supervisors/default/afk-supervisor.pid` to appear and contain a live PID, then prints the launched supervisor PID and target; on failure it reports the tail of `.red/tmp/supervisors/default/supervisor.log.toonl`. Capture the reported PID for the *Report back* step. The launched supervisor is the native `__supervise` entrypoint of the same bundle.
+4. **Attach the best available monitor surface.**
+   - Claude Code: no automatic monitor cron. Tell the user to run `/dev:afk monitor` manually or tail `.red/tmp/supervisors/default/supervisor.log.toonl`.
+   - Codex: fetch a sub-agent spawn primitive via `ToolSearch` (query: `spawn agent background monitor`). If available, emit the canonical prompt with `RED_AFK_RUNNER=codex red-skills-dev codex-monitor-agent --project-root "$PWD" --mode fleet` and spawn exactly one read-only Codex monitor agent for this newly-launched supervisor. Its task: from the project root, periodically run `/dev:afk monitor --once` (the bundle's `monitor --once`), report concise progress, and auto-close when `.red/tmp/supervisors/default/afk-supervisor.pid` is missing/dead and no `[live]` workers remain. It must never edit files, claim issues, stop workers, or run merges. The user may close it manually; workers continue. If the primitive is unavailable, skip and use the manual-monitor line.
+   - Bare/unknown: skip native monitor setup and use the manual-monitor line.
+5. **Report back.** Print:
+   ```
+   🚀 fleet launched (supervisor pid=<pid>, target=<N>)
+      log:   .red/tmp/supervisors/default/supervisor.log.toonl
+      stop:  /dev:afk fleet stop
+      <monitor-status-line>
+   ```
+   Monitor status line choices:
+   - Claude Code: `monitor: run /dev:afk monitor or tail .red/tmp/supervisors/default/supervisor.log.toonl`
+   - Codex monitor agent spawned: `Codex monitor agent spawned — auto-closes when fleet exits; manual monitor: /dev:afk monitor.`
+   - Codex monitor unavailable: `monitor loop unavailable in this runner; run /dev:afk monitor or tail .red/tmp/supervisors/default/supervisor.log.toonl manually.`
+   - Bare/unknown: `monitor loop unavailable in this runner; run /dev:afk monitor or tail .red/tmp/supervisors/default/supervisor.log.toonl manually.`
+
+### `/dev:afk fleet stop` — graceful shutdown
+
+Steps, in order:
+
+1. **Liveness check.** Read `.red/tmp/supervisors/default/afk-supervisor.pid`. The three cases:
+   - File missing → print `no fleet running.` and continue to step 3 (still try runner-specific monitor teardown).
+   - File present but `kill -0` fails → stale. Print `no fleet running (stale pid file at .red/tmp/supervisors/default/afk-supervisor.pid — cleaning).`, `rm -f` it, and continue to step 3.
+   - File present and PID alive → continue to step 2.
+2. **Touch the stop file.** `touch .red/tmp/supervisors/default/afk-supervisor.stop`. The supervisor's health-check cycle (default `RED_AFK_POLL_S=15s`) picks it up and runs `cleanup`, which SIGTERMs every worker, removes the PID file, removes the stop file, and exits. Wait up to **30 s** for the PID file to disappear (poll every 1 s, deadline-bounded — never bare `while`). If it's gone, print `🛑 fleet stopped (supervisor pid=<pid> exited).`. If the deadline trips, print one warning line naming the PID and the log path, and continue to step 3 anyway — the stop file is still there and the supervisor will pick it up eventually.
+3. **Tear down runner-specific monitors.**
+   - Claude Code: no automatic monitor cron to cancel. Print `no auto-monitor cron (manual monitoring only).`
+   - Codex: do not stop workers through the monitor agent. It auto-closes when it observes no supervisor/live workers, and the user may close it manually. Print `Codex monitor agent will self-close when it observes fleet stopped.`
+   - Bare/unknown: print `no native monitor teardown for this runner.`
+4. **Idempotency.** Re-running `/dev:afk fleet stop` after a successful stop just hits the "file missing" branch in step 1 and the runner-specific teardown no-op in step 3. Exit 0 either way.
+
+### `/dev:afk fleet logs` — local structured log reader
+
+`/dev:afk fleet logs --supervisor`, `/dev:afk fleet logs --worker <id>`, and
+`/dev:afk fleet logs --all` are read-only local views over the castle lanes.
+They do not call GitHub and do not mutate fleet state. They decode structured
+TOONL records and render human-readable lines only at read time:
+
+- `--supervisor` reads supervisor lanes under `.red/tmp/supervisors/`.
+- `--worker <id>` reads that worker's `.red/tmp/workers/<id>/worker.log.toonl`.
+- `--all` reads every worker lane, merges records by timestamp, and prefixes
+  each rendered line with `[worker-id]`.
+- `--follow` keeps polling the selected lane set and streams appended records
+  until the caller stops the command.
+
+### Circuit Trip Sweep
+
+When the circuit breaker parks a slot (`CIRCUIT_K` fast deaths inside `CIRCUIT_WINDOW_S`) the supervisor — not a human — runs `sweep_parked_slot` to clean up after the burned workers. Three actions, in order, gated on the trip:
+
+1. **Sweep affected attempt dirs.** From the dated slot log (`.red/tmp/logs/<yyyy-mm-dd>/afk-supervisor-slot-{slot}.log`) the supervisor parses every `[afk] worker: w…` boot stamp emitted while the slot was alive, globs `.red/tmp/workers/{wid}/*/` for each ID, and reads `afk.state.json`'s `.current.number` to identify the affected issues. During the logs TTL aging window, the reader also accepts the legacy tmp-root `afk-supervisor-slot-{slot}.log` path so pre-migration slot logs can be swept before the janitor reclaims them. Each attempt dir is `rm -rf`'d after its issue has been processed.
+2. **Post a discard envelope on each affected issue.** Same `<details data-attempt-status="…">` schema as the per-issue terminal envelope, with `status="discarded"` and a summary line that names the runner and the trip cause (`runner-broken, slot parked after K fast deaths`). The envelope's `data-section="summary"` block carries the slot index, comma-joined worker IDs, fast-death count, and the supervisor log path. No `notes`, `drop`, or `log` sections — the attempts produced no usable artefacts.
+3. **Restore label state on each affected issue.** Single `gh issue edit` adds `ready-for-agent` and `runner-error`, removes `ready-for-human` and (defensively) `running` — covers both the "issue had already been promoted to `ready-for-human`" path and the "issue was still `running` at the moment of trip" path.
+
+The `runner-error` label is created idempotently by `/red-setup` (see [triage-labels.md](../red-setup/triage-labels.md)). The supervisor still calls `gh label create runner-error` on the fly during a trip so cleanup never fails just because the label is missing.
+
+Idempotency: `SLOT_SWEPT[slot]=1` blocks a second sweep within the same supervisor lifetime. Across restarts a new trip yields fresh worker IDs and fresh attempt dirs, so re-tripping never re-touches the previously swept issues. A trip that finds no claimed issues (all workers exited before claiming) parks the slot but posts no envelopes — the attempt-dir sweep is a no-op.
+
+## Fleet Width by Disjunction
+
+The safe fleet width for a given queue is the **degree of disjunction** — the maximum number of concurrently `ready-for-agent` slices that touch non-overlapping file sets.
+
+- **Disjoint queue** (each slice writes to files no other ready slice touches): run the full fleet. `fleet 4` is safe when the queue has four independent file cones.
+- **Partially entangled queue**: lower the fleet width to the number of disjoint groups. If two groups of two slices each are independent between groups but internally serialized via `req:N`, `fleet 2` drains both chains in parallel without risk.
+- **Fully entangled refactor** (every slice touches shared files, serialized via `req:N`): run `fleet 1` or bare `/afk`. Parallel workers share no ready-for-agent work at any moment — extra slots sit idle and raise the risk of a spurious merge conflict should a `req:N` edge be missing.
+
+**Rule: fleet width = degree of disjunction.** Raise it when the queue is disjoint; lower it to `fleet 1` when slices are entangled. The `/to-tickets` slicing skill is responsible for expressing file-level dependencies as `req:N` edges before the queue is published, so a correctly-sliced backlog never produces a file-overlap merge conflict from concurrent workers.
+
+### Refs
+
+- The bundle's `fleet` / `fleet stop` commands — the entrypoints this section drives. Stop-file path, env contract, circuit breaker, and trip-sweep are part of the supervisor behaviour described above.
+- [`monitor.md`](./monitor.md) — the readonly dashboard and native-task mirror.

package/skills/engineering/afk/hooks/red-cargo

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+# red-cargo — built-in pre_worktree library hook for Rust projects.
+#
+# Contract (ADR 0026, PRD #207, issue #211):
+#   stdin   — JSON object: pre_worktree context (issue, target, branch, env).
+#   stdout  — empty (context unchanged) when no Cargo.toml is present at
+#             $PROJECT_ROOT, OR a JSON object that merges
+#             {env: {CARGO_TARGET_DIR: <slot dir>}} into the context.
+#   exit    — 0 on either branch. Never aborts the chain.
+#
+# Side effect: mkdir -p the slot target dir so cargo can use it immediately.
+# CARGO_TARGET_DIR=${RED_AFK_CARGO_TARGET_BASE:-/opt/cargo-target}/slot-${RED_AFK_SLOT:-0}
+# so each worker slot gets its own target directory and Cargo never
+# serializes on .cargo-lock between workers.
+#
+# Env contract (RED_AFK_* exported by the orchestrator):
+#   RED_AFK_SLOT                — worker slot number (0-based); defaults to 0.
+#   RED_AFK_CARGO_TARGET_BASE   — base dir for slot target dirs; defaults to
+#                                 /opt/cargo-target. Set in .red/config.yaml
+#                                 via afk.cargo_target_base or by environment.
+#
+# Shadowing: place a same-named file in .red/hooks/red-cargo to replace this
+# default with a project-local variant. An empty (exit-0) file disables it.
+
+set -uo pipefail
+
+project_root="${PROJECT_ROOT:-$(pwd)}"
+ctx="$(timeout "${RED_SKILLS_HOOK_STDIN_TIMEOUT_S:-5s}" cat 2>/dev/null || true)"
+[[ -z "$ctx" ]] && ctx='{}'
+
+if [[ ! -f "$project_root/Cargo.toml" ]]; then
+  # Not a Rust project — pass-through.
+  exit 0
+fi
+
+slot="${RED_AFK_SLOT:-0}"
+base="${RED_AFK_CARGO_TARGET_BASE:-/opt/cargo-target}"
+target_dir="${base}/slot-${slot}"
+
+mkdir -p "$target_dir" 2>/dev/null || true
+
+printf '%s' "$ctx" | jq -c \
+  --arg t "$target_dir" \
+  '. + {env: ((.env // {}) + {CARGO_TARGET_DIR: $t})}'

package/skills/engineering/afk/hooks/red-envelope

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+# red-envelope — built-in post_attempt library hook (ADR 0026, PRD #207,
+# issue #212; renamed from post_worker in #226).
+#
+# Reconciles the iteration's intermediate envelope state on the AFK state
+# file as soon as the runner returns — before any user post_attempt hook
+# runs, so a user notifier/pager integration that reads state already sees
+# the worker's terminal result classified.
+#
+# Contract:
+#   stdin   — JSON object: post_attempt context with .result.status of
+#             "success" or "fail".
+#   stdout  — empty (context unchanged). Pure side-effect on the state file.
+#   exit    — 0. Never aborts the chain.
+#
+# Env contract (RED_AFK_* exported by the orchestrator):
+#   RED_AFK_STATE_FILE      — absolute path to the iteration's afk.state.json;
+#                             when unset/missing, the default is a no-op.
+#   RED_AFK_RESULT_STATUS   — redundant fallback ("success"|"fail") for
+#                             runners/tests that cannot shape a context JSON;
+#                             if ctx.result.status is absent this is used
+#                             instead.
+#
+# Shadowing: place a same-named file in .red/hooks/red-envelope to replace
+# this default with a project-local variant. An empty (exit-0) file disables
+# it.
+
+set -uo pipefail
+
+ctx="$(timeout "${RED_SKILLS_HOOK_STDIN_TIMEOUT_S:-5s}" cat 2>/dev/null || true)"
+
+state_file="${RED_AFK_STATE_FILE:-}"
+[[ -z "$state_file" || ! -f "$state_file" ]] && exit 0
+
+status=""
+if [[ -n "$ctx" ]]; then
+  status="$(printf '%s' "$ctx" | jq -r '.result.status // empty' 2>/dev/null || true)"
+fi
+[[ -z "$status" ]] && status="${RED_AFK_RESULT_STATUS:-}"
+[[ -z "$status" ]] && exit 0
+
+tmp="${state_file}.tmp.$$"
+if jq --arg s "$status" '.current = ((.current // {}) + {result_status: $s})' \
+     "$state_file" > "$tmp" 2>/dev/null; then
+  mv "$tmp" "$state_file"
+else
+  rm -f "$tmp"
+fi
+
+exit 0

package/skills/engineering/afk/hooks/red-gradle

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+# red-gradle — built-in pre_worktree library hook for Gradle projects.
+#
+# Contract (ADR 0026, PRD #207, issue #211):
+#   stdin   — JSON object: pre_worktree context (issue, target, branch, env).
+#   stdout  — empty (context unchanged) when no build.gradle* is present at
+#             $PROJECT_ROOT, OR when RED_AFK_GRADLE_USER_HOME_BASE is unset
+#             (opt-in by env var — we do not claim a path on the user's
+#             filesystem without their consent). Otherwise a JSON object
+#             that merges {env: {GRADLE_USER_HOME: <slot dir>}} into ctx.
+#   exit    — 0 on either branch. Never aborts the chain.
+#
+# Side effect: mkdir -p the slot Gradle home so daemons / caches are isolated
+# between worker slots.
+#
+# Env contract (RED_AFK_* exported by the orchestrator):
+#   RED_AFK_SLOT                   — worker slot number (0-based); defaults to 0.
+#   RED_AFK_GRADLE_USER_HOME_BASE  — base dir for per-slot Gradle homes;
+#                                    UNSET by default (opt-in). Set in
+#                                    .red/config.yaml or by environment to
+#                                    activate per-slot Gradle isolation.
+#
+# Shadowing: place a same-named file in .red/hooks/red-gradle to replace this
+# default with a project-local variant. An empty (exit-0) file disables it.
+
+set -uo pipefail
+
+project_root="${PROJECT_ROOT:-$(pwd)}"
+ctx="$(timeout "${RED_SKILLS_HOOK_STDIN_TIMEOUT_S:-5s}" cat 2>/dev/null || true)"
+[[ -z "$ctx" ]] && ctx='{}'
+
+shopt -s nullglob
+matches=("$project_root"/build.gradle*)
+shopt -u nullglob
+if [[ "${#matches[@]}" -eq 0 ]]; then
+  exit 0
+fi
+
+if [[ -z "${RED_AFK_GRADLE_USER_HOME_BASE:-}" ]]; then
+  exit 0
+fi
+
+slot="${RED_AFK_SLOT:-0}"
+home_dir="${RED_AFK_GRADLE_USER_HOME_BASE}/slot-${slot}"
+
+mkdir -p "$home_dir" 2>/dev/null || true
+
+printf '%s' "$ctx" | jq -c \
+  --arg h "$home_dir" \
+  '. + {env: ((.env // {}) + {GRADLE_USER_HOME: $h})}'

package/skills/engineering/afk/hooks/red-heartbeat

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# red-heartbeat — built-in post_attempt library hook (ADR 0026, PRD #207,
+# issue #212; renamed from post_worker in #226).
+#
+# Stops the orchestrator's per-minute heartbeat side-channel (when a PID is
+# available) and writes the "iteration stopped" boundary marker into the
+# iteration log, migrating the inline heartbeat_stop that used to fire from
+# afk.sh right after run_inner returned.
+#
+# Contract:
+#   stdin   — JSON object: post_attempt context (issue, workspace, result).
+#   stdout  — empty (context unchanged). Pure side-effect.
+#   exit    — 0. Never aborts the post_attempt chain.
+#
+# Env contract (RED_AFK_* exported by the orchestrator):
+#   RED_AFK_HEARTBEAT_PID — PID of the orchestrator heartbeat subprocess;
+#                           empty/unset when no external heartbeat runs
+#                           (e.g. the native TS runtime manages heartbeat
+#                           internally). Killing a stale pid is guarded via
+#                           kill -0.
+#   RED_AFK_ITER_LOG      — absolute path to the iteration log (afk.log);
+#                           the boundary line is appended only when the file
+#                           exists. Unset/empty → skip the marker.
+#
+# Shadowing: place a same-named file in .red/hooks/red-heartbeat to replace
+# this default. An empty (exit-0) file disables it; the orchestrator EXIT
+# trap remains the backstop for heartbeat teardown.
+
+set -uo pipefail
+
+# Drain stdin (context flows through unchanged — emit nothing).
+timeout "${RED_SKILLS_HOOK_STDIN_TIMEOUT_S:-5s}" cat >/dev/null 2>&1 || true
+
+pid="${RED_AFK_HEARTBEAT_PID:-}"
+if [[ -n "$pid" ]] && kill -0 "$pid" 2>/dev/null; then
+  kill "$pid" 2>/dev/null || true
+  # Best-effort reap; the sub-shell may already be exiting.
+  wait "$pid" 2>/dev/null || true
+fi
+
+iterlog="${RED_AFK_ITER_LOG:-}"
+if [[ -n "$iterlog" && -f "$iterlog" ]]; then
+  printf '[heartbeat] iteration stopped at %s\n' "$(date -Is)" >> "$iterlog"
+fi
+
+exit 0

package/skills/engineering/afk/hooks/red-validation

@@ -0,0 +1,79 @@
+#!/usr/bin/env bash
+# red-validation — built-in post_merge library hook (ADR 0026, PRD #207,
+# issue #213).
+#
+# Runs CI/smoke validation against the merged primary checkout so user
+# post_merge hooks see the validation status already reconciled into the
+# context. The pre-merge feedback() step in the mechanism layer stays as the
+# safety gate (ADR 0008 — anything that must abort the merge loudly is
+# mechanism, not a hook); this default exposes a post-merge re-run hook
+# authors can disable, observe, or replace.
+#
+# Contract:
+#   stdin   — JSON object: post_merge context (issue, workspace, merge_commit).
+#   stdout  — JSON object: the same context with
+#             .result = {validation_status: "passed"|"failed"|"skipped",
+#                        validation_summary: <one-line string>} merged into
+#             it. Non-JSON stdin → pass-through with no validation attempt.
+#   exit    — 0. Post_merge policy is continue; even a failing validation
+#             only logs (it cannot roll back the merge — that ship has sailed
+#             at this lifecycle point).
+#
+# Env contract (RED_AFK_* exported by the orchestrator):
+#   RED_AFK_WORKSPACE    — primary checkout (post-merge tip). When unset or
+#                          not a directory, the default is a no-op.
+#   RED_AFK_MERGE_COMMIT — full sha of the merge commit on target. Not
+#                          consumed by this default but documented so user
+#                          hooks reading env directly see a consistent view.
+#
+# Shadowing: place a same-named file in .red/hooks/red-validation to replace
+# this default with a project-local variant. An empty (exit-0) file disables
+# it.
+
+set -uo pipefail
+
+ctx="$(timeout "${RED_SKILLS_HOOK_STDIN_TIMEOUT_S:-5s}" cat 2>/dev/null || true)"
+ws="${RED_AFK_WORKSPACE:-}"
+
+emit_ctx() {
+  local status="$1" summary="$2"
+  if [[ -z "$ctx" ]]; then
+    return 0
+  fi
+  printf '%s' "$ctx" \
+    | jq --arg s "$status" --arg sum "$summary" \
+        '.result = ((.result // {}) + {validation_status: $s, validation_summary: $sum})' \
+        2>/dev/null \
+    || printf '%s' "$ctx"
+}
+
+if [[ -z "$ws" || ! -d "$ws" ]]; then
+  emit_ctx "skipped" "no workspace"
+  exit 0
+fi
+
+if ! [[ -f "$ws/package.json" ]]; then
+  emit_ctx "skipped" "no package.json"
+  exit 0
+fi
+
+# Run pnpm test/typecheck/lint/build at the workspace root if the script
+# exists. This mirrors the mechanism-owned feedback() step shape but
+# operates on the merged tip rather than the worker's worktree.
+overall="passed"
+parts=""
+for script in test typecheck lint build; do
+  if jq -e --arg s "$script" '.scripts[$s] // empty' "$ws/package.json" >/dev/null 2>&1; then
+    if ( cd "$ws" && pnpm -s "$script" >/dev/null 2>&1 ); then
+      parts+="${script}:✓ "
+    else
+      parts+="${script}:✗ "
+      overall="failed"
+    fi
+  else
+    parts+="${script}:skip "
+  fi
+done
+
+emit_ctx "$overall" "${parts% }"
+exit 0

package/skills/engineering/afk/monitor.md

@@ -0,0 +1,170 @@
+# AFK Monitor — running `afk monitor` (readonly dashboard + task mirror)
+
+This file serves the `afk monitor` branch: the readonly aggregated dashboard
+across all live workers, the native-task mirror and its self-cancel teardown, and
+the Codex monitor agent. Reached from *When To Use* (`/afk monitor`).
+
+## The binding mirror rule (authoritative — stated once)
+
+**The mirror is binding: every monitor tick must (1) render the dashboard and (2) mirror live workers onto the host runner's native task surface, re-checking `afk.state.json` on every tick.** It is never optional and never a shortcut — skipping it because "nothing changed" or because the user "only asked for status" is a bug, not an optimization, since `monitor --mirror-plan` is idempotent and emits zero descriptors when nothing changed. Per-runner mapping:
+
+- **Claude Code:** pipe the tracked-task JSONL into the bundle's `monitor --mirror-plan` and apply the emitted call plan via `TaskCreate` (one task per live worker, titled `#<n> w<id> — <title>`) and `TaskUpdate` (description carries `stage:<x>`, terminal events flip `state` to `completed`/`failed`). See *Task Mirror* below for the full protocol.
+- **Codex:** run `monitor --mirror-plan --runner codex`. Today Codex exposes no native task surface, so the sink emits an empty plan and the mirror falls back to the dashboard plus a one-line notice — that *is* the mirror under Codex; do not silently skip. If Codex grows a native surface, the sink emits the same call-plan descriptors against it.
+- **Bare terminal / unknown runner:** skip the mirror silently — the `monitor` dashboard is the canonical view.
+
+## Dashboard
+
+`/afk monitor` is the readonly aggregated view across all live workers. **Run the bundle's `monitor` command — do not reinvent the rendering in inline bash.** It:
+
+1. Globs `.red/tmp/workers/*/*/afk.state.json` and renders one section per active attempt.
+2. Verifies liveness via the orchestrator PID recorded in `afk.state.json` (`.pid` field), paired with `pid_start_time` when the platform exposes a stable process-start token. Attempts whose PID identity is dead or mismatched are flagged `stale`/`gone`; PID-live but agent-lane-quiet workers render `[quiet]` and are still counted as running.
+3. Reads sibling `afk.log` line counts through the monitor cursor and renders `log:<total>(+<new>)` when available, without re-reading whole logs on every tick.
+4. Renders WorkerVitals activity counters (`tools:<n> reason:<n> text:<n> wait:<n>`) so a quiet but pid-live worker can show useful progress signals.
+5. Renders the 48h sparkline header (next subsection) on every refresh.
+
+To invoke, from the project root:
+
+```bash
+RED_AFK_RUNNER=<runner> red-skills-dev monitor
+```
+
+The command has **two modes**, auto-selected by stdout type:
+
+- **TTY (real terminal)**: full box-drawing layout, refreshes every 3 s, `clear` between frames. Ctrl-C to exit.
+- **Non-TTY (piped, captured by an agent, redirected)**: one-shot **compact dashboard** — one sparkline header + one line per worker, then exit 0. Force this with `--once` or `RED_AFK_MONITOR_COMPACT=1` even from a TTY.
+
+Compact output shape (≈3 lines total for 2 workers — fits inline without truncation in an agent transcript):
+
+```
+48h: ···············································█  (4 closed, peak 4/h, all workers)   Δ fleet +382 -45
+wZ2R4 [live] claude  issues 4/5  #150 [blog/D] Agent SDK on RedDB  stage:impl  00:23:01  +382 -45  tools:39 reason:4 text:112 wait:2  log:540(+12)
+wK7M2 [live] codex   issues 0/16  idle  +0 -0
+```
+
+The progress counter is `issues <done>/<total>` — issues *closed* over the queue total, **not** a completion percentage (the old `(80%)` form read as "no work done" while a worker had already committed thousands of lines). The real volume signal is the `+A -R` **diff** (committed + uncommitted, measured from the branch's merge-base with `origin/main`), which is rendered on **every** worker line unconditionally — idle and `+0 -0` included — and **summed across the fleet** into the `Δ fleet +A -R` suffix on the sparkline header, so the total diff volume is always visible at a glance.
+
+When invoking from inside another agent session (Claude Code, Codex), prefer `--once` even if stdin is a pipe — explicit beats inference. Don't use the full TTY mode in agent transcripts; the 3 s refresh loop floods the captured stream and gets truncated to garbage.
+
+Single-worker operation shows one section/line. Multi-worker adds one section/line per live worker, sorted by `started_at`. The sparkline aggregates **all workers** in this checkout's `.red/state/castle/history.toonl` — not fractured per-worker; the `Δ fleet` diff total likewise sums every worker.
+
+The header of every render shows a **48h sparkline** of issues closed, one glyph per hour, scaled to the peak hour:
+
+```
+48h: ·▁··▁·▁·▁··█▁▁··▁·▁···▁·▁·▆▁▁··▁···▁▆·▁··▁▃▁·▃▁·  (35 closed, peak 5/h)
+```
+
+Source data: `.red/state/castle/history.toonl`, an append-only TOONL event log written by the orchestrator on every terminal event. `tq` is the pinned required reader for this lane; do not document or use a jq fallback.
+
+```toonl
+[]{ts,epoch,worker,issue,event,duration_s,runner,merge_sha,reason}:
+"2026-05-17T12:14:00-03:00",1747494840,wK7M2,571,done,816,codex,0936ba54,null
+"2026-05-17T12:18:00-03:00",1747495080,wK7M2,569,blocked,120,codex,null,merge-conflict
+"2026-05-17T12:20:00-03:00",1747495200,wK7M2,568,exhausted,0,claude,null,both-runners
+```
+
+Example inspection:
+
+```bash
+tq -p toonl -o json 'select(.event == "done") | {issue: .issue, worker: .worker, runner: .runner}' .red/state/castle/history.toonl
+```
+
+`.red/state/` is gitignored. The orchestrator creates it during bootstrap, parallel workers serialise appends via `flock`, and the boot-time orphan sweep truncates the file to the last 10000 lines if it grows past that cap.
+
+The sparkline only counts `event == "done"`. Blockers and exhausted runs are recorded for forensics but excluded from the throughput view.
+
+## Self-Cancel (binding when invoked under Claude Code via a manual /loop)
+
+When the user has manually set up a `/loop`-based recurring `/dev:afk monitor` run, each tick is responsible for tearing down the loop once there are no workers left to watch.
+
+After rendering the dashboard, the agent must:
+
+1. Count observable workers with status `[live]` or `[quiet]` in the rendered output (i.e., orchestrator pid identity alive, post-orphan-cleanup).
+2. If `observable_workers == 0`:
+   - Fetch `CronList` and `CronDelete` via `ToolSearch` if not already loaded.
+   - `CronList` — find every job with `prompt == "/dev:afk monitor"`.
+   - `CronDelete` each match.
+   - Append one line to the user-facing output: `🛑 no live workers — cancelled monitor loop (cron <id>).`
+
+When `CronList` / `CronDelete` are unavailable (Codex runner, or `/afk monitor` invoked outside Claude Code), skip the teardown silently — the cron infrastructure isn't running there to begin with.
+
+## Task Mirror
+
+Every `/dev:afk monitor` run also **mirrors each live worker onto the runner's native task list when that runner exposes one**, so a `/afk` session surfaces progress on the host's native UI — advancing through stages on its own, with no extra typing. This is a **read-only reflection of `afk.state.json`**; the mirror never writes state and never touches the orchestration.
+
+**Host capability matrix (binding — no parity).** The Task mirror is per-runner by construction (ADR 0003/0015): there is **no shared native task API** across the hosts, so each runner gets its own explicit adapter, never a generic cross-runner abstraction. The honest matrix — encoded as `taskMirrorCapability(host)` in `core/mirror.ts` and exercised by `tests/mirror.test.ts` — is:
+
+| Host (Agent runner) | Surface | Native task API | Adapter / sink | Today's behavior |
+|---|---|---|---|---|
+| Claude Code | `native-task` | yes | `mirrorPlan` (`TaskCreate`/`TaskUpdate`) | the in-session Agent runner drives the native Task mirror through the host task tools |
+| Codex | `monitor-agent` | no | `codexSinkPlan` | no task API — the mirror falls back to the `monitor` dashboard plus **one read-only Codex monitor agent** |
+| OpenCode runner | `headless` | no | none (empty plan) | a headless API-auth **Worker** with no host session — there is no surface to mirror into, so no native calls are ever emitted |
+
+The three surfaces are deliberately distinct values (never a single `supported: boolean`) so the matrix can **never imply parity**. Exactly one host (Claude Code) exposes a native task API; the other two degrade explicitly, each on its own adapter. An unknown host fails loudly rather than silently inheriting the Claude native path.
+
+The mirror surfaces **two signals on one lifecycle** (issue #811): the task **title** carries the calm **macro phase** — `w<id> [<n>/5 <phase>] #<issue> <slug>` — while the task **description** carries the fine **micro stage** — `stage: <impl|explore|tests|commit>`. The phase vocabulary is the ordered `setup → coding → validating → merging → done` (1-based `n/5`), plus the terminal `blocked` which drops the `n/5` and renders `[blocked]`. The title changes only when the macro phase moves, so it never flickers on every inner-agent tool call.
+
+The mirror is a pure diff: it reconciles the live worker state files against the tasks already on the native surface and emits a **call plan**. After rendering the dashboard, the agent (under Claude Code only) must:
+
+1. Fetch `TaskCreate`, `TaskUpdate`, and `TaskList` via `ToolSearch` if not already loaded (deferred tools).
+2. **Build the tracked set.** `TaskList` → keep the mirror-owned tasks (those whose title matches `w<id> [<…>] #<n> <slug>`). For each, emit one JSONL line `{"key":"<worker_id>:<issue>","stage":"<last stage>","phase":"<last phase>"}`, reading the key (`worker_id` from the leading token, `issue` from the `#<n>`) and the **phase** (the word inside the title's `[…]` bracket, after any `n/5 `) from the title, and the **stage** from the description (`stage: <x>`). Keep a key→task_id map for step 4.
+3. **Compute the plan.** Pipe the tracked JSONL from step 2 into the bundle's `monitor --mirror-plan` subcommand:
+   ```bash
+   printf '%s\n' "$tracked" | red-skills-dev monitor --mirror-plan
+   ```
+   The command globs the state files and reconciles them against the tracked set on stdin (keyed by `worker_id:issue`, so parallel workers each get exactly one task and re-runs never duplicate), then prints a JSONL **call plan** to stdout — one descriptor per harness call (empty stdin → cold reconcile; empty plan → no output). A `TaskUpdate` rewrites the **title** when the macro phase moves and refreshes the **description** when the micro stage moves; a terminal failure re-titles to `[blocked]` and flips the task to `failed`:
+   ```jsonl
+   {"call":"TaskCreate","key":"wAAAA:22","title":"wAAAA [2/5 coding] #22 extract state.sh","description":"stage: impl","state":"in_progress"}
+   {"call":"TaskUpdate","key":"wAAAA:22","title":"wAAAA [3/5 validating] #22 extract state.sh","description":"stage: tests","state":"in_progress"}
+   {"call":"TaskUpdate","key":"wAAAA:22","state":"completed"}
+   ```
+4. **Apply the plan.** For each descriptor in order:
+   - `TaskCreate` → create the task; record `key → task_id`.
+   - `TaskUpdate` → resolve `key` to its `task_id` via the map and update. A `state` of `completed`/`failed` marks the worker's terminal event (`done`/`blocked`); the task drops off the active list and the mirror self-cleans. A descriptor whose `key` has no known `task_id` (e.g. a complete for a task that was never created in this session) is skipped.
+
+An empty plan means nothing changed since the last tick — apply no calls. Because the plan is keyed by `worker_id:issue`, an idempotent re-run with no stage advance emits zero descriptors.
+
+**Re-hydration on session reopen.** A native task dies with the Claude Code session; the `nohup` AFK worker does not. When a session opens with workers still running, `TaskList` (step 2) returns no mirror-owned tasks, so the tracked set is **empty** and `monitor --mirror-plan` reconciles cold — emitting a `TaskCreate` for every live worker. The status bar recovers the per-worker tasks with no operator action. This is the same path as steady-state, not a new one: only workers whose orchestrator PID (the `.pid` field in `afk.state.json`, via `state_is_live`) is alive re-hydrate (dead workers are untracked-terminal on a cold tick → no ghost task), and the next tick is idempotent because the freshly-created tasks now form the tracked set.
+
+When `TaskCreate` / `TaskUpdate` are unavailable because the session is **outside any runner** (a bare terminal), **skip the mirror silently** — there is no native surface to drive, and the `monitor` dashboard is already the canonical view.
+
+**Codex sink (runner-specific — binding).** The mirror is per-runner, mirroring the `runner-claude.md` / `runner-codex.md` split (ADR 0003). Under Codex the state reader and plan reconciler are reused unchanged — only the sink differs. After rendering the dashboard, the Codex agent runs `monitor --mirror-plan --runner codex` instead of the Claude `TaskCreate`/`TaskUpdate` loop:
+
+- If Codex grows a native background-task surface, the sink emits the **same call-plan descriptors** the Claude sink applies — apply them against the Codex primitive.
+- Otherwise (today's reality), `--runner codex` emits an **empty plan**, so the mirror falls back to the `monitor` dashboard and a one-line notice. No native calls are emitted, so there is no half-rendered state, and a dashboard hiccup is swallowed so the tick never crashes.
+
+Do **not** invent a cross-runner task abstraction (rejected in ADR 0003) — keep the adapter explicitly per-runner.
+
+## Codex Monitor Agent (Codex only — binding)
+
+Codex does not expose Claude Code's `TaskCreate` / `TaskUpdate` task surface, and
+its `tui.status_line` only renders built-in footer widgets. It does expose a
+native sub-agent UI in hosts where the sub-agent primitive is available. For
+Codex runs, use that sub-agent UI as a read-only presentation layer over the
+canonical `/afk monitor` dashboard.
+
+When `/afk` launches a normal detached worker under Codex (`run`, not
+`monitor`, not `--once`, not `--boot-only`), or `/dev:afk fleet N` launches a new
+supervisor under Codex:
+
+1. Fetch a sub-agent spawn primitive via `ToolSearch` (query:
+   `spawn agent background monitor`).
+2. If unavailable, continue the worker launch and print:
+   `monitor loop unavailable in this runner; run /dev:afk monitor or tail .red/tmp/workers/*/*/afk.log manually.`
+3. If available, emit the canonical prompt from the bundle (use `--mode run` for a
+   single worker, `--mode fleet` for a supervisor, so the read-only rules stay
+   identical across launches):
+   ```bash
+   RED_AFK_RUNNER=codex red-skills-dev codex-monitor-agent --project-root "$PWD" --mode run
+   ```
+   Spawn exactly one monitor agent with that prompt. The monitor agent is a
+   presentation consumer only: it periodically runs `/dev:afk monitor --once`,
+   reports concise progress in the Codex UI, and exits once no supervisor or
+   live workers remain.
+4. Tell the user one line:
+   `Codex monitor agent spawned — auto-closes when AFK exits; manual monitor: /dev:afk monitor.`
+
+Hard boundaries for the monitor agent are non-negotiable: it must never edit
+files, claim issues, change labels, comment, stop workers, run validation, push,
+merge, `/retake`, `/go`, `/hitl`, `/triage`, `/afk run`, `/afk fleet`, `/afk fleet stop`,
+`/afk reap`, or `/afk requeue`. Closing it manually must not affect the AFK
+worker.