Liveness Discipline (FR-27)

The failure (why this rule exists)

A long/silent command (probe, test script, deploy, fetch loop, browser automation), a sub-agent, or a harness-auto-backgrounded workflow that HANGS emits no completion event. The host therefore never re-invokes the agent, which idles indefinitely while appearing "done" — until a human asks "is it still running?". The hang→no-event→idle failure is invisible from inside: the hung call fires no post-call hook, the agent waiting on it cannot act, and a host stall watchdog that excludes tool-call time does not see it. It is visible from outside: a separate bounded watcher that polls activity (SHA, mtime, byte count) and exits on progress, completion or stall (§ Wake interval). So this rule is not enforced by a gate, and a Stop-time "watchdog: applied" signal would be attestation theatre. Enforcement = safe-default tooling (hooks/local/lib/bounded-run.sh) + present-by-construction delivery (this skill in context at launch time) + an outside watcher (§ Wake interval).

Guardrail (the rule's floor)

Quality/safety floor unchanged. Never launch bare — but a liveness guarantee is the floor, not a license to kill a slow-but-progressing job. A bounded deadline is sized for the work, never so tight it trains premature kills (the FR-26 "budget gate trains truncation" lesson, inverse). Diagnose before you kill.

Protocol — never launch bare → attach ≥1 liveness guarantee

Before launching ANY long/silent work, attach at least one of these. In preference order:

Mandatory regardless of which guarantee you pick:

• Internal watchdog from the FIRST version — put the deadline in at authoring time, not after it hangs once. Retrofitting a timeout after the first idle is too late.
• Per-call timeouts — every individual fetch/RPC/subprocess inside a loop carries its own timeout, not just the outer wrapper.
• Always flush partial results — write durable facts AS THEY OCCUR (skeleton first, rows as earned) so a kill at the deadline still leaves evidence (flow-skills/task-delegation progress ledger, flow-skills/smoke-testing record-then-read).
• Incremental progress logging to stderr — a job that prints "still working: step 3/8" cannot masquerade as a hang, and bounded_run does this for you.

Compact bounded-run example (D5 — the copy-paste skeleton)

bounded_run <deadline-secs> <progress-label> -- <cmd> [args...] sources the shared core from run-with-timeout.sh (so the ffhc_* health-check API is untouched), bounds the MONITORED process to the deadline, logs a heartbeat to stderr every interval, and ALWAYS emits a terminal line — either the command's completion or a bounded-run: TIMEOUT line — so the job reaches completion-or-death instead of a silent idle.

#!/usr/bin/env bash
set -uo pipefail
source "$(git rev-parse --show-toplevel)/hooks/local/lib/bounded-run.sh"

# Bound a slow re-verify probe to 120s; heartbeat to stderr; terminal line guaranteed.
bounded_run 120 "re-verify probe" -- ./scripts/reverify.sh --target "$URL"
rc=$?
# rc 124 = deadline elapsed; rc 137 = ignored SIGTERM, SIGKILLed after the -k grace.
# On timeout the wrapper already printed the terminal "bounded-run: TIMEOUT" line —
# surface it, flush partial results, then diagnose (do not blind-retry).

# Long run: launch the WRAPPER as the host's background command (Claude Code: run_in_background), or `&`
# only from a shell that outlives the wait — never `&` under it. Then wait on its terminal line in <=230 s
# slices (tool timeout >=240 s); bounded_wait rc 124 = not yet: re-issue it, or arm a watcher.
bounded_run 1800 "suite" -- ./scripts/run-suite.sh >suite.log 2>&1 &
bounded_wait suite.log '^bounded-run: (done|TIMEOUT|SKIPPED).* — suite( \(rc |$)'

Heartbeat file. Each call also writes state/audit/liveness/<label>-<pid>-<n>.hb (git-excluded on upgrade; BOUNDED_RUN_HB_DIR moves it, empty disables; pruned after 7 days untouched): a header, one running <s>/<deadline> line per heartbeat, then done / TIMEOUT / SKIPPED. It proves the wrapper is alive, not that the work progresses. No terminal record = the wrapper has not returned yet: an rc-137 return lands after deadline + the 5 s kill grace, so treat it as hung only with no terminal record by launch + deadline + grace + ~30 s (MSYS reap slack).

Honest scope (D7 — do not overstate). bounded_run bounds the monitored process only. It does NOT:

• kill a grandchild you &-detached or Start-Process'd out from under it — so don't detach under the wrapper; keep the work in the monitored process tree;
• interrupt an uninterruptible OS wait;
• prove the host re-invokes you — it ensures the process reaches completion/death so a host that surfaces background completion has an event to deliver, and so a 0-byte silent idle becomes a visible timeout line.

Therefore: put a deadline INSIDE long scripts too (an event-loop-blocked setTimeout won't fire; an inner fetch needs its own timeout), don't &-detach under the wrapper, and always flush partial results.

Diagnose a suspected hang (activity, not existence)

A slow-but-progressing job is NOT a hang. Distinguish before you kill:

• Check activity: last log line, output file mtime, byte growth, last progress marker — NOT mere "the file exists" (a 0-byte file proves nothing) and NOT "the process is listed".
• Slow but progressing (mtime advancing, new log lines, byte count climbing) → let it run; widen the deadline if the work legitimately needs it.
• Stalled (no activity past the expected interval, no heartbeat, deadline elapsed) → confirmed hang; recover.

Recover from a confirmed hang

1. Stop the stalled process (the wrapper's timeout line means it already terminated; otherwise terminate it).
2. Re-run the robust version — the same launch with a deadline + incremental logging attached (never blind-retry the bare launch; that's the two-strike anti-pattern, FR-26).
3. Clean residue — partial files, locks, half-written state from the killed run.
4. Retry only transient rate-limits with bounded, labeled backoff; a structural hang is not a rate-limit and re-attempting it unchanged is forbidden.

Zero-trust sub-agent liveness (mandatory — WS8)

A dispatched sub-agent (or Codex) is a long/silent launch under someone else's control — the same hang→no-event→idle failure applies, plus you cannot see its process. Never trust or passively wait on its completion ping. The completion notification can be missing, late, or fire on a transcript that is 0 bytes. Apply the zero-trust protocol:

This is the sub-agent application of the FR-27 floor; flow-skills/task-delegation owns the turn-completion / BLOCKED-AT return shape (cross-linked below, not duplicated).

Wake interval (canonical)

Every model-side check re-reads the waiting agent's whole context, and a check after its cache lifetime re-writes it (token-economy TE-20). Poll in the shell; wake the model on events. A liveness check reads one SHA, mtime or byte count — never the output (that is evidence: record-then-read).

Large-context orchestrator (host listed in § Host wake paths as able to wake you; otherwise the "No watcher can wake you" row): after dispatch, arm the watcher, then end the turn — the watcher does FR-27's proactive polling shell-side. On each wake read the one fact it reports: still running → arm a fresh watcher before ending the turn again; done → § Zero-trust Verify before trusting, then trust the result; stalled → § Diagnose a suspected hang. A report-back is an extra wake, never the only one (a missing ping is no information). Never poll model-side while a watcher can wake you.

A watcher cannot cover: your own hung foreground call (its wake queues behind it — bound that call), a session that cannot be re-invoked after its turn (→ in-turn loop), a host freeze (a same-host watcher freezes too).

Host wake paths

Bounded delegate-retry envelope (canonical — the ONE exception)

The single sanctioned exception to don't-poll-while-running / record-then-read (token-economy TE-08) and to the two-strike rule (TE-05). It covers ONLY a delegate that never STARTED — transient provider rate-limit, server error, no-start. A structural hang, a started-then-wrong result, and a failing approach are all outside it and get zero retries under this envelope.

When delegate-progress polling overrides record-then-read: record-then-read presumes a durable surface that outlives the run. A delegate that never started writes nothing, so no record exists to read afterwards — the interval progress read is the only available evidence, and it is capped at one read per interval. The moment the delegate IS producing progress the override ends: judge the work from its commits and artifacts, never by watching it run (liveness checks continue at § Wake interval — a SHA, mtime or byte count, never the output).

Re-dispatches inside this envelope are not two-strike attempts: the approach was never executed. A retry after the delegate has started IS a strike.

Cross-links (reuse, do not duplicate)

Anti-patterns

• Launching a background probe/deploy/fetch-loop with no timeout, or ending the turn on background work with no watcher armed — "running in background — I'll resume when it completes" (you won't — nothing re-invokes you for a hung call; on a host listed in § Host wake paths a bounded watcher's exit, or a bounded_run job's own exit, does; elsewhere, and in a delegated session, stay in-turn with ≤4-min checks or return BLOCKED-AT-<gate>).
• Adding a hook or Stop-time signal that claims to VERIFY this protocol was applied — attestation theatre (the inert-lever anti-pattern). Detecting a stall is the outside watcher's job (§ Wake interval), never an attestation.
• A blocking gate on background launches — the failure is semantic (real hang vs legitimate long-live run); a gate trains premature kills (intelligence damage).
• &-detaching under bounded_run and assuming the deadline still bounds the detached grandchild (it does not).
• Diagnosing a hang by "the output file exists" (0-byte existence proves nothing) instead of by activity/mtime/last-progress.
• Blind-retrying the same bare launch after it hung (two-strike, FR-26) instead of re-running the robust, bounded, logged version.
• Reading a delegate's transient provider-limit death as a task verdict (FAILED / "it couldn't") — the work was never attempted; re-dispatch "try again", retrying only inside § Bounded delegate-retry envelope above (max 3 attempts / 5 min), then judge.
• Treating a missing completion ping as either completion or death — it is no information; poll for progress instead.
• Re-pasting this protocol into every handoff — it lives here; handoffs carry the promoted Hard-invariant clause + a pointer (FR-23/FR-24).

Clean-room note

Original Fusebase Flow content. Designed after reviewing public AI coding workflow patterns; no third-party code, prompts, skill files, or hook scripts are copied. The bounded-run tooling reuses Fusebase Flow's own run-with-timeout.sh core (not a third-party watchdog). See docs/source-map.md.