no-mistakes(document): Clarify native and compatibility AFK delivery

Author: ruby-dlee

AGENTS.md

@@ -83,7 +83,7 @@ config/secondmate-account-pool  optional Agent Fleet pool the PRIMARY uses for S
 config/backlog-backend  backlog backend override; LOCAL, gitignored; absent or "tasks-axi" = default tasks-axi backend, "manual" = force routine backlog updates to hand-editing; inherited by secondmate homes (section 10)
 config/backend  runtime session-provider backend override for new tasks; LOCAL, gitignored; absent = falls through to runtime auto-detection (the runtime firstmate itself is executing inside), then tmux; tmux is the verified reference backend, herdr/zellij/cmux are experimental new-task spawn backends, and Orca is legacy-recovery-only (docs/tmux-backend.md, docs/herdr-backend.md, docs/zellij-backend.md, docs/orca-backend.md, docs/cmux-backend.md) - herdr and cmux can also be selected by runtime auto-detection, zellij and Orca never are (always explicit), and codex-app is not accepted; see docs/codex-app-backend.md; not inherited into secondmate homes
 config/cmux-socket-password  optional cmux control-socket password; LOCAL, gitignored; read fresh on every cmux CLI call and passed through without ever overriding an operator's own ambient CMUX_SOCKET_PASSWORD when absent (docs/cmux-backend.md "Setup")
-config/wedge-alarm  optional away-mode wedge-alarm active-alert directives; LOCAL, gitignored; absent means auto (macOS Notification Center when available); see docs/wedge-alarm.md
+config/wedge-alarm  optional active-alert directives for wedged terminal-backed away-mode compatibility delivery; LOCAL, gitignored; absent means auto (macOS Notification Center when available); see docs/wedge-alarm.md
 config/x-mode.env    generated X-mode watcher cadence; LOCAL, gitignored; source before arming watcher when present
 data/                personal fleet records; LOCAL, gitignored as a whole
   backlog.md         task queue, dependencies, history

README.md

@@ -169,7 +169,7 @@ Claude and grok use the slash form shown here; codex uses the same names with `$
 
 | Skill              | What it does                                                                                                                                  |
 | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
-| `/afk`             | Enter away-mode supervision: the sub-supervisor self-handles routine wakes in bash, escalates captain-relevant events and bounded declared-external-wait rechecks as batched digests, and actively alerts if delivery wedges while you step away |
+| `/afk`             | Enter away-mode supervision: the sub-supervisor self-handles routine wakes in bash and wakes the parked first mate with a batched digest only for captain-relevant events and bounded declared-external-wait rechecks |
 | `/bearings`        | Generate a "pick up where I left off" status report from the read-only fleet snapshot - backlog, per-task crew state, open PRs, scout reports, pending decisions, and date-gated queued work - written to a dated file in `data/` and surfaced concisely in chat; read-mostly, mutates no task state |
 | `/reports`         | Browse, search, open, or summarize the machine-global completion report stack, including visual evidence and follow-ups                        |
 | `/updatefirstmate` | Self-update the running firstmate and its secondmates to the latest from origin with fast-forward-only pulls, then re-read instructions and nudge secondmates |
@@ -191,7 +191,7 @@ Firstmate's skills live in two separate places with different audiences:
 
 - [docs/architecture.md](docs/architecture.md) - how the crew, supervision, worktrees, secondmates, account routing, completion reports, and project modes work.
 - [docs/configuration.md](docs/configuration.md) - environment variables, `FM_HOME`, runtime backend and Agent Fleet account routing, optional X mode, the files you set, and harness support.
-- [docs/wedge-alarm.md](docs/wedge-alarm.md) - configure the active alert for a wedged away-mode escalation delivery.
+- [docs/wedge-alarm.md](docs/wedge-alarm.md) - configure the active alert for wedged terminal-backed away-mode compatibility delivery.
 - [docs/tmux-backend.md](docs/tmux-backend.md) - setup guide for the tmux reference backend: prerequisites, attaching, and watching crew windows.
 - [docs/herdr-backend.md](docs/herdr-backend.md) - setup guide for the experimental herdr backend, plus its verification notes and known gaps.
 - [docs/zellij-backend.md](docs/zellij-backend.md) - setup guide for the experimental zellij backend, plus its verification notes and known gaps.

bin/backends/herdr.sh

@@ -2809,11 +2809,11 @@ fm_backend_herdr_composer_state() {  # <target> -> empty|pending|unknown
 # away-mode daemon. Root cause: composer-content submit confirmation was too
 # sensitive to harness rendering details. Real claude/codex use bare prompt
 # rows, and real codex adds dynamic idle suggestions after `›`; the later
-# ANSI-aware composer classifier now handles the pre-injection guard for that
-# Codex shape, but idle-baseline submit confirmation deliberately stays on
-# native agent-state so delivery does not depend on composer text. Composer
-# content is retained for other callers (the away-mode daemon's PRE-injection
-# empty-box guard, still dispatched via fm_backend_composer_state /
+# ANSI-aware composer classifier now handles the compatibility pre-injection
+# guard for that Codex shape, but idle-baseline submit confirmation deliberately
+# stays on native agent-state so delivery does not depend on composer text.
+# Composer content is retained for other callers (the terminal-backed away-mode
+# compatibility path's empty-box guard, still dispatched via fm_backend_composer_state /
 # fm_backend_herdr_composer_state) and for submit attempts whose pre-Enter
 # agent-state baseline is not legibly idle.
 #

bin/backends/tmux.sh

@@ -14,8 +14,8 @@
 # inline with these same send/current-path primitives.
 #
 # The verified composer/busy-detection and verify-and-retry-submit primitives
-# already live in bin/fm-tmux-lib.sh, shared with the away-mode daemon
-# (bin/fm-supervise-daemon.sh); this adapter sources that file and re-exports
+# already live in bin/fm-tmux-lib.sh, shared with the terminal-backed away-mode
+# compatibility path; this adapter sources that file and re-exports
 # its submit core under the backend's naming convention rather than
 # duplicating it, so the two consumers cannot drift apart.
 # shellcheck source=bin/fm-tmux-lib.sh

bin/fm-composer-lib.sh

@@ -8,11 +8,11 @@
 # agent composer" decision, and the copies drifted. The dangerous drift: a BARE
 # shell prompt glyph (`>`, `$`, `%`, `#`) - what a pane shows once its agent has
 # exited to a plain login shell - was treated as an empty, ready-to-inject
-# AGENT composer. The away-mode escalation injector (bin/fm-supervise-daemon.sh)
-# reads composer-emptiness to decide whether a pane is a safe injection target,
-# so a dead-shell pane misread as "empty" meant an escalation could be typed
-# into (and, worst case, executed by) that shell. Consolidating the one decision
-# here means the safety rule cannot silently drift across adapters again.
+# AGENT composer. The terminal-backed away-mode compatibility injector reads
+# composer-emptiness to decide whether a pane is a safe injection target, so a
+# dead-shell pane misread as "empty" meant an escalation could be typed into (and,
+# worst case, executed by) that shell. Consolidating the one decision here means
+# the safety rule cannot silently drift across adapters again.
 #
 # THE SAFETY RULE this owner enforces: a bare shell prompt glyph is a genuine
 # empty agent composer ONLY when it appears INSIDE a real agent-composer
@@ -26,9 +26,9 @@
 # afk-herdr-false-pending): a harness fills an otherwise-empty composer with
 # de-emphasized ghost text - claude's rotating prompt suggestion, codex's idle
 # suggestion, grok's placeholder - which a plain capture cannot tell apart from
-# text a human typed, so the away-mode injector reads the idle pane as "pending
-# input" and defers every escalation (the overnight wedge that motivated this
-# consolidation). fm_composer_strip_ghost is the ONE ANSI-aware extractor of
+# text a human typed, so the compatibility injector reads the idle pane as
+# "pending input" and defers every escalation (the overnight wedge that motivated
+# this consolidation). fm_composer_strip_ghost is the ONE ANSI-aware extractor of
 # "real typed content": it drops every de-emphasized run - dim/faint (SGR 2, how
 # claude and codex render ghost text) AND a dark/muted TRUECOLOR foreground (how
 # grok renders placeholder/hint text) - and keeps only normal-intensity,

bin/fm-marker-lib.sh

@@ -25,17 +25,17 @@
 # travels with the live secondmate, and is summarized in AGENTS.md.
 #
 # Distinct from the afk daemon marker, on purpose.
-# The away-mode daemon (bin/fm-supervise-daemon.sh) marks its daemon->firstmate
-# escalations with a BARE leading unit separator (FM_INJECT_MARK, ASCII 0x1f).
+# The terminal-backed away-mode compatibility path marks daemon->firstmate
+# injections with a BARE leading unit separator (FM_INJECT_MARK, ASCII 0x1f).
 # The from-firstmate marker instead uses U+2063 INVISIBLE SEPARATOR after its
 # human-readable label. U+2063 has no normal keyboard keystroke but travels as
 # UTF-8 text rather than a terminal control byte. The original ASCII 0x1f
 # separator did not survive terminal input faithfully: on Herdr 0.7.3 feeding
 # it to a real Pi composer removed the preceding label, so Pi received only the
 # unmarked request (docs/herdr-backend.md records the incident and live proof).
-# The afk contract keys on a LEADING 0x1f, while this marker begins with its
-# label and contains no 0x1f, so the two cannot conflate. The visible label is
-# what the secondmate's LLM reads; U+2063 remains invisible.
+# The legacy afk injection contract keys on a LEADING 0x1f, while this marker
+# begins with its label and contains no 0x1f, so the two cannot conflate. The
+# visible label is what the secondmate's LLM reads; U+2063 remains invisible.
 #
 # Sourced by bin/fm-send.sh, bin/fm-brief.sh, and the tests. No side effects on
 # source. set -u / set -e safe.

bin/fm-supervise-daemon.sh

@@ -16,8 +16,8 @@
 #
 # PRESENCE-GATING (the /afk contract). The daemon is the away-mode engine: it
 # delivers ONLY when the durable away-mode flag state/.afk is present. Invoking
-# the /afk skill sets that flag and starts this daemon; any real (unmarked)
-# user message clears it and firstmate resumes full responsiveness.
+# the /afk skill sets that flag and starts this daemon; any real user message
+# clears it and firstmate resumes full responsiveness.
 # When afk is off, normal fm-watch.sh always-on triage is the active mechanism.
 # Any buffered daemon escalations that remain while afk is off survive in
 # state/.subsuper-escalations and are flushed on the next "while you were out"
@@ -55,9 +55,9 @@
 #     have missed (e.g. a status verb outside CAPTAIN_RE) and escalates it.
 #
 # The robustness shell from the prior always-inject version is preserved:
-# single-instance lock (portable helper, no flock dependency), crash-loop
-# backoff, pane-gone guard, and a signal-trapped shutdown that flushes buffered
-# escalations before exit.
+# single-instance lock (portable helper, no flock dependency) and crash-loop
+# backoff remain shared. The compatibility path retains its pane-gone guard and
+# shutdown flush; native shutdown preserves buffered escalations for catch-up.
 #
 # Usage: fm-supervise-daemon.sh
 #          Long-lived background loop. Normally started by the /afk skill, which
@@ -79,10 +79,9 @@
 #                                   resolves the runtime firstmate itself is
 #                                   executing inside - $TMUX_PANE selects tmux,
 #                                   $HERDR_ENV=1 selects herdr - falling back to
-#                                   tmux). zellij, orca, and cmux are not yet
-#                                   supported as supervisor backends; the daemon
-#                                   refuses loudly at startup rather than trying
-#                                   tmux primitives against a non-tmux pane.
+#                                   tmux). Applies only to compatibility injection:
+#                                   zellij, orca, and cmux are not supported there,
+#                                   and that mode refuses loudly at startup.
 #          FM_INJECT_SKIP           |-prefixes force-self-handle bypassing
 #                                   classification (default "heartbeat"); empty
 #                                   disables. Use sparingly: it overrides the
@@ -99,10 +98,10 @@
 #          FM_HOUSEKEEPING_TICK     seconds between housekeeping passes while
 #                                   the watcher is mid-cycle (default 15)
 #          FM_BUSY_REGEX            OR-ed busy signatures (mirrors fm-watch.sh)
-#          FM_COMPOSER_IDLE_RE      empty-composer regex applied after dim-ghost
+#          FM_COMPOSER_IDLE_RE      compatibility injection empty-composer regex applied after dim-ghost
 #                                   and structural border stripping (default:
 #                                   bare prompt glyphs plus busy footers)
-#          FM_MAX_DEFER_SECS        max seconds a buffered escalation may sit
+#          FM_MAX_DEFER_SECS        compatibility-only max seconds a buffered escalation may sit
 #                                   undelivered before one normal flush attempt;
 #                                   if that cannot confirm a submit, a wedge
 #                                   alarm fires (default 300; 0 disables)
@@ -112,7 +111,7 @@
 #                                   absent file/var means auto: on macOS that is
 #                                   an OS-level notification, so the alarm is
 #                                   never silent. See wedge_alarm_notify below
-#                                   and docs/configuration.md.
+#                                   and docs/configuration.md. Compatibility only.
 #          FM_WEDGE_ALARM_EXEC      notifier seam: when set, every notifier
 #                                   channel routes through this command as
 #                                   `<cmd> <channel> <summary>` instead of
@@ -139,9 +138,10 @@
 #          FM_STATE_OVERRIDE        alternate state dir (testing)
 #          Logs each wake to state/.supervise-daemon.log (size-capped). Single
 #          instance via portable lock on state/.supervise-daemon.lock. Trapped
-#          SIGTERM/SIGINT shut down within ~1s, flush escalations, release the
-#          lock. A crashing fm-watch.sh is logged and restarted, never killing
-#          the daemon; a tight crash-restart spin is detected and backed off.
+#          SIGTERM/SIGINT shut down within ~1s and release the lock; compatibility
+#          injection flushes, while native delivery preserves its buffer. A
+#          crashing fm-watch.sh is logged and restarted, never killing the daemon;
+#          a tight crash-restart spin is detected and backed off.
 set -u
 
 FM_DAEMON_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
@@ -176,9 +176,9 @@ fm_refuse_if_gate_agent
 . "$FM_DAEMON_DIR/fm-supervisor-target-lib.sh"
 
 # --- tunables ---------------------------------------------------------------
-# Supervisor backends this daemon knows how to inject into today. zellij, orca,
+# Supervisor backends the compatibility path can inject into today. zellij, orca,
 # and cmux are real backends elsewhere in firstmate (bin/fm-backend.sh) but this
-# daemon has no verified composer/busy primitives wired up for them yet - see
+# compatibility path has no verified composer/busy primitives for them yet - see
 # docs/herdr-backend.md and AGENTS.md section 4's
 # harness-verification discipline. Selecting one refuses loudly at startup
 # instead of silently running tmux primitives against a pane that is not a tmux
@@ -190,9 +190,9 @@ STALE_ESCALATE_SECS_DEFAULT=240
 ESCALATE_BATCH_SECS_DEFAULT=90
 HEARTBEAT_SCAN_SECS_DEFAULT=300
 HOUSEKEEPING_TICK_DEFAULT=15
-# Max time a buffered escalation may sit undelivered before the daemon retries
-# the normal flush path and, if that cannot confirm a submit, raises a loud wedge
-# alarm. The escape hatch makes a guard false-positive visible instead of silent.
+# Compatibility-only max time a buffered escalation may sit undelivered before
+# the daemon retries the injection path and, if that cannot confirm a submit,
+# raises a loud wedge alarm.
 MAX_DEFER_SECS_DEFAULT=300
 WEDGE_ALARM_TIMEOUT_SECS_DEFAULT=10
 WEDGE_ALARM_LAST_EPOCH=0
@@ -1402,7 +1402,7 @@ fm_super_main() {
   log "daemon starting (pid $$); delivery=$DELIVERY; target=$TARGET; target_source=$target_source; backend=$BACKEND; backend_source=$backend_source; afk=$afk_status; inject_skip='${FM_INJECT_SKIP:-$INJECT_SKIP_DEFAULT}'; stale_escalate=${FM_STALE_ESCALATE_SECS:-$STALE_ESCALATE_SECS_DEFAULT}s; batch=${FM_ESCALATE_BATCH_SECS:-$ESCALATE_BATCH_SECS_DEFAULT}s"
   migrate_watcher_pause_markers "$STATE"
 
-  # --- shutdown: flush buffered escalations, reap child, release lock -------
+  # --- shutdown: compatibility flush or native preserve, reap child, unlock -
   local WATCHER_PID="" CUR_TMP=""
   cleanup() {
     trap - TERM INT

bin/fm-supervisor-target-lib.sh

@@ -1,9 +1,9 @@
 #!/usr/bin/env bash
 # fm-supervisor-target-lib.sh - the single owner of supervisor-pane discovery.
 #
-# The away-mode daemon (bin/fm-supervise-daemon.sh) must know which pane runs
-# firstmate itself, both to inject escalations into it and, for the daemon, to
-# validate that target at startup. The script-owned away launcher
+# The terminal-backed away-mode compatibility path must know which pane runs
+# firstmate itself, both to inject escalations into it and to validate that
+# target at startup. Native tracked delivery never resolves a pane. The launcher
 # (bin/fm-afk-launch.sh) must resolve the SAME captain pane BEFORE it creates a
 # separate, non-visible terminal for the daemon, so it can pass that pane in as
 # FM_SUPERVISOR_TARGET (otherwise the daemon, running in its own terminal, would

bin/fm-tmux-lib.sh

@@ -2,9 +2,9 @@
 # fm-tmux-lib.sh — shared tmux pane primitives for firstmate.
 #
 # ONE source of truth for: busy detection, composer-empty (pending-input)
-# detection, and a verify-and-retry-Enter submit. Sourced by both the away-mode
-# daemon (bin/fm-supervise-daemon.sh) and bin/fm-send.sh so the composer/submit
-# logic cannot drift between the two.
+# detection, and a verify-and-retry-Enter submit. Sourced by both the terminal-
+# backed away-mode compatibility path and bin/fm-send.sh so composer/submit logic
+# cannot drift between the two.
 #
 # Why this exists (incident afk-invx-i5): the daemon's old composer check only
 # recognized a BARE prompt glyph ("> ") as an empty composer. claude draws its