instar 0.28.91 → 0.28.93

package/upgrades/side-effects/multishot-stuck-input-recovery.md

@@ -0,0 +1,151 @@
+# Side-Effects Review — Multi-Shot Stuck-Input Recovery
+
+## Change Summary
+
+`SessionManager.verifyInjection` upgrades from single-shot to multi-shot
+polling with escalating recovery actions. When the recovery Enter is itself
+eaten by the same paste-end race that caused the original stuck state, the
+loop keeps trying — with different key combinations — until the marker
+clears the `❯` prompt or the bounded schedule (4 attempts over 6.5s)
+exhausts.
+
+Three surface changes in `src/core/SessionManager.ts`:
+
+1. `verifyInjection` now polls at 500ms, 1500ms, 3500ms, 6500ms from
+   injection. Each tick checks pane state; stops as soon as the marker
+   clears the prompt. Single Degradation entry on the first recovery firing.
+2. `isMarkerStuckAtPrompt(pane, marker)` extracted as a named method so the
+   polling loop and tests share one detection rule.
+3. `fireStuckInputRecovery(tmuxSession, attempt)` escalates the recovery
+   action: attempts 0 and 1 send `Enter`; attempt 2 sends `C-m` (literal
+   carriage return — bypasses any Enter-specific consumer); attempt 3 sends
+   `Enter` + 150ms sleep + `Enter` (covers sub-second race windows).
+
+## Failure Mode Being Fixed
+
+Reproduced live in `/Users/justin/.instar/agents/echo/logs/server.log`:
+
+```
+01:31:49 [LOG] Injected initial message into "echo-telegram-messages-pausing-in-input" (297 chars)
+01:33:49 [WARN] Injection stuck — marker "[telegram:7195] Your session j…" still at prompt. Resending Enter.
+01:33:49 [DEGRADATION] SessionManager.verifyInjection: Enter eaten by paste-end race
+01:34:15 [WARN] Injection stuck — marker "[telegram:7195] Your session j…" still at prompt. Resending Enter.
+01:34:15 [DEGRADATION] SessionManager.verifyInjection: Enter eaten by paste-end race
+```
+
+Two observations:
+
+- The async setTimeout(1500ms) fired 120 seconds after injection — the Node
+  event loop was blocked, likely by initial-message-driven session startup
+  work. Single-shot timing is unreliable under load.
+- The recovery Enter itself failed (the second `Injection stuck` log line
+  for the same marker proves the first recovery did not unstick the input).
+
+The single-shot design assumed both: (a) the timer fires near 1.5s and (b)
+the recovery Enter always lands. Both assumptions break in practice.
+
+## Over-Block Risk
+
+**Polling more times = more chances to send a spurious Enter.** The
+detection gate is unchanged from the single-shot version: marker (first
+40 chars, stripped of leading whitespace, ≥8 chars) must appear on or
+immediately after a line containing `❯`. Claude Code only renders `❯` on
+the active input prompt row — not on transcript history — so the marker
+cannot match a historic echo of the message. Each polling tick re-runs the
+same gate; if the message has submitted, the gate refuses and recovery
+does not fire.
+
+Worst-case false-positive: marker is genuinely visible at `❯` because the
+user is still typing the same prefix the agent just injected. Extremely
+implausible (the marker is the message's first 40 chars, not a common
+prefix). Impact if it happened: one or more extra Enters in the input
+box. The user would see their typing submitted prematurely. Acceptable
+trade for fixing the stuck-message bug.
+
+The escalation to `C-m` and double-Enter applies only on attempts 2 and
+3 — after two consecutive ticks showed the marker still stuck at `❯`.
+That's an additional safety margin against accidental escalation.
+
+## Under-Block Risk
+
+If the polling schedule's last tick (6500ms) still shows the marker stuck
+despite four recovery attempts, the loop exits without further action.
+The existing recovery layers below still apply:
+
+- `StallTriageNurse` fast-path nudges stuck inputs when its periodic
+  diagnosis pass runs.
+- The `pasteRetried` mechanism handles the `[Pasted text #N]` placeholder
+  case.
+- The idle-prompt zombie reaper eventually kills sessions with no output
+  changes past the configured threshold.
+
+A session that survives all four ticks without recovery is almost certainly
+not suffering the paste-end race — something else is wrong (tmux frozen,
+terminal in a weird state, etc.) and continued Enter-hammering would not
+help.
+
+## Level-of-Abstraction Fit
+
+Same as the single-shot version: `verifyInjection`,
+`isMarkerStuckAtPrompt`, and `fireStuckInputRecovery` are all private
+methods on `SessionManager` and operate at the tmux-send-keys abstraction
+layer. No new public API. No upward leakage of tmux details. Helpers are
+extracted only because polling and detection are now distinct concerns
+that benefit from named test boundaries.
+
+## Signal vs Authority Compliance
+
+`verifyInjection` is a verification (signal-emitting) layer. It detects a
+specific structural failure (`marker visible at ❯ after Enter was sent`)
+and takes one bounded structural action per detection (one Enter / C-m /
+Enter+sleep+Enter). It does not replace any higher gate; it is the only
+component at this layer with both the context (the marker text and the
+injection timing) and the authority (it owns the tmux session interaction)
+to perform the recovery. There is no higher gate to defer to.
+
+The escalation across attempts is a structural escalation in mitigation
+strategy, not in authority. Each recovery attempt remains "send one of N
+recovery key sequences to tmux" — same authority bound throughout.
+
+## Interactions With Existing Recovery Paths
+
+| Layer | Trigger | Scope | Conflicts with multi-shot? |
+|-------|---------|-------|----------------------------|
+| `verifyInjection` polling (new) | After every `rawInject` | per-injection, bounded by 6.5s schedule | n/a — this is the new layer |
+| `pasteRetried` | `[Pasted text #N]` visible at idle prompt | per-session lifetime | independent — different match string, fires from idle detector |
+| `StallTriageNurse` fast-path | text at ❯ with no glyphs, before LLM | per-triage-pass | independent — runs from triage scheduler. Could fire AFTER verifyInjection's 6.5s window if the session is still stuck. Sending one more Enter at that point is harmless. |
+| Zombie-kill timer | `idleMs > idlePromptKillMinutes` | global | unchanged — only fires if all prior layers missed and session sat for the configured minutes |
+
+The four layers gate from fast-and-proactive (per-injection polling) to
+slow-and-destructive (zombie kill). Adding more ticks to the proactive
+layer is monotonically safer — it shifts more stuck-state recovery to the
+fast path rather than waiting for the LLM-backed triage.
+
+## Rollback Cost
+
+- Revert: restore the single `setTimeout` body from the prior version of
+  `verifyInjection`; delete `isMarkerStuckAtPrompt` and
+  `fireStuckInputRecovery`. Pure additive — no state, no schema, no
+  migration.
+- Tests added: `tests/unit/session-multishot-recovery.test.ts` (12 tests).
+  Existing structural tests (`tests/unit/session-injection-verify.test.ts`)
+  were updated to assert the bounded-multi-shot invariants — 10 tests pass.
+- Branch surface area: 1 source file modified, 1 test file modified, 1 test
+  file added.
+
+## Evidence
+
+- Live failure: `/Users/justin/.instar/agents/echo/logs/server.log`
+  01:31–01:34 — two stuck-then-eaten-recovery events on the same injection
+  marker.
+- `tests/unit/session-multishot-recovery.test.ts` — 12 tests covering
+  multi-shot polling, escalation across attempts, bounded recovery count,
+  early-stop on submission detected, no-op for clean injections, no-op for
+  short markers, halt on tmux session disappearance, and detection-
+  heuristic edge cases.
+- `tests/unit/session-injection-verify.test.ts` — 10 structural tests
+  asserting the new design contract (bounded retries, monotonic backoff
+  schedule, recovery-method escalation, early-stop predicate).
+- No regression: `SessionManager-injection.test.ts`,
+  `paste-stuck-detection.test.ts`, `session-telegram-inject.test.ts`,
+  `stall-triage-typed-not-submitted.test.ts` all pass (25 tests).

package/upgrades/side-effects/project-scope-phase1b-pr1.md

@@ -0,0 +1,252 @@
+# Side-Effects Review — project-scope Phase 1b PR 1 (Drift checker + supervisor git-creds fix)
+
+**Version / slug:** `project-scope-phase1b-pr1`
+**Date:** `2026-05-11`
+**Author:** `echo`
+**Second-pass reviewer:** `required (new LLM-mediated surface + new tmux-spawn flag)`
+
+## Summary of the change
+
+First PR of Phase 1b for the project-scope feature. Ships the *signal*
+producer that Phase 1.5's round-runner will consume — the drift
+checker that asks an `IntelligenceProvider` whether a spec's stated
+premises still hold against the files it depends on. By itself it is
+inert: nothing wires it up yet. The Phase 1b PR 2 (round runner) is
+the first consumer.
+
+Tag-along: a one-line fix to the server supervisor that has been
+producing a runaway "Server unhealthy" restart loop on every fresh
+spawn since at least v0.28.87. Discovered during the Phase 1a gate
+verification this evening. Fix lives in the same PR because it
+unblocks the supervisor (and therefore unblocks every agent that runs
+into the credential-prompt loop) and is one line of code.
+
+Spec source: `docs/specs/PROJECT-SCOPE-SPEC.md` § Phase 1.4 (drift
+checker). Supervisor fix is not spec'd — it's a defect repair.
+
+New files:
+- `src/core/ProjectDriftChecker.ts` (≈480 lines) — the verdict
+  producer. Path-jails every file via the existing `jailPath` helper,
+  reads spec + referenced files, enforces hard limits (count / per-file
+  bytes / per-file lines / total token budget), wraps content in
+  `<UNTRUSTED_SPEC_BODY>` / `<UNTRUSTED_FILE_CONTENT>` blocks, calls
+  the provider with a 30s timeout + 1 retry, parses + structurally
+  validates the response, re-verifies every citation against the bytes
+  on disk, downgrades to `manual-review-required` whenever anything
+  can't be trusted.
+- `tests/unit/ProjectDriftChecker.test.ts` (45 tests) — covers path
+  jail (`../`, absolute, symlink escape), prompt-injection delimiters,
+  over-budget (count / bytes / lines / tokens), empty-spec,
+  deleted-files, partial-deleted-files, schema-fail (no JSON / bad
+  enum / non-string rationale / non-array citations), citation
+  verification (byteRange OOB, fabricated file, LLM-claimed excerpt
+  discarded), all-citations-fail downgrade, zero-citations no-downgrade,
+  timeout (both calls fail) + timeout-then-success retry, non-timeout
+  error bails immediately, code-fenced JSON tolerance, cacheKeyInputs
+  determinism across file-order and instability across file-content /
+  template-version / model-id changes.
+
+Modified files:
+- `src/core/types.ts` (+50/-2) — adds `DriftVerdict` and
+  `VerifiedCitation` types, adds `timeoutMs` to `IntelligenceOptions`.
+- `src/core/InitiativeTracker.ts` (+5/-2) — types
+  `InitiativeRound.lastDriftVerdict` as `DriftVerdict` (was `unknown`,
+  flagged "typed in Phase 1b" in the source comment), adds two
+  companion fields `lastDriftVerdictAt` and
+  `lastDriftReferencedFileHashes` that the round-runner will populate
+  in PR 2.
+- `src/lifeline/ServerSupervisor.ts` (+9/-1) — adds
+  `'-e', 'GIT_TERMINAL_PROMPT=0'` to the `tmux new-session` invocation
+  in `spawnServer()`. Comment block explains why (askpass fallback +
+  inherited tmux server env). Source-pattern test in
+  `tests/unit/server-supervisor-preflight.test.ts` (+25) asserts the
+  flag is present in the new-session args.
+
+Nothing else moves.
+
+## Decision-point inventory
+
+The drift checker IS a decision point — that's its purpose — but its
+output is a **signal**, not authority. Round-runner (Phase 1b PR 2)
+combines this signal with deterministic artifact checks before
+deciding to start a round. The signal-vs-authority separation is
+enforced both by the type system (the verdict is consumed only by
+`ProjectRoundRunner` in PR 2) and by the spec.
+
+- **Drift verdict** (`ProjectDriftChecker.run`) — **add** — produces
+  one of `no-drift | minor-drift | premise-violated |
+  manual-review-required`. The verdict alone is not enough to block
+  or start a round; the round-runner combines it with frontmatter
+  re-validation, PR/CI artifact checks, ownership, and ack state.
+- **Path-jail rejection** (delegated to `jailPath`) — **reuse** —
+  inherits the same allow-list behavior the StageTransitionValidator
+  uses. Failure produces `manual-review-required`, never a soft pass.
+- **Token-budget rejection** — **add** — over-budget input is rejected
+  with `manual-review-required(over-budget)` rather than silently
+  truncated. The spec explicitly forbids silent summarization to
+  prevent a half-evaluated drift verdict being trusted.
+- **Citation re-verification** — **add** — every LLM-proposed citation
+  is independently re-read off disk. The LLM's claimed excerpt is
+  discarded. If the LLM produced citations and none survived
+  verification, the verdict is downgraded to
+  `manual-review-required(failed-citation-verification)` — defense
+  against fabricated evidence supporting a fabricated verdict.
+- **Schema-fail downgrade** — **add** — any malformed LLM output
+  (non-JSON, bad enum, missing fields) produces
+  `manual-review-required(schema-fail)` rather than a best-guess.
+
+Supervisor change has no decision-point semantics — it's an env-flag
+addition that prevents git from prompting interactively. Drift is in
+the BEHAVIOR of git-on-tmux, not in any agent decision.
+
+## Over-block vs under-block analysis
+
+### Drift checker
+
+The verdict producer is at the right level of abstraction. It does
+**not** read project records, it does **not** decide whether a round
+may start, it does **not** persist anything. It takes an input
+struct, returns a verdict struct. The round-runner (PR 2) holds all
+authority. This matches the signal-vs-authority memory rule and the
+spec.
+
+Could it be over-blocking? The four "downgrade to
+manual-review-required" paths (path-jail-fail, over-budget,
+schema-fail, failed-citation-verification, timeout, no-provider) are
+**deliberately conservative**. The spec is explicit: any failure mode
+that means the verdict cannot be trusted MUST surface as user
+attention rather than be treated as a soft pass. The cost of a
+false-positive manual review is the user's eyeballs; the cost of a
+soft pass is shipping something that doesn't match the code on disk.
+
+Could it be under-blocking? The checker accepts a list of referenced
+files from the caller — it doesn't *find* them itself by parsing the
+spec. That's deliberate: parsing files-the-spec-claims-to-depend-on
+is a job for the round-runner (or for spec frontmatter), not the
+drift checker. Otherwise we'd have two places where spec parsing
+lives, and they'd drift (irony noted).
+
+The 50,000-token budget is a static cap rather than dynamically sized
+to the provider. Caller bears the risk if they're using a provider
+with a smaller context window — but in practice every supported
+model has a window far bigger than 50k. Documented as a constant
+that tests can override.
+
+### Supervisor fix
+
+The flag only affects git operations performed inside the spawned
+tmux session. It does NOT change:
+- Whether git is invoked (the auto-pull / git-sync code is unchanged).
+- Whether credentials are tried (osxkeychain credential helper still
+  runs first as configured).
+- Whether non-interactive auth works (it does, as the same git pull
+  works from any shell that inherits the supervisor env).
+
+It only blocks the *interactive fallback* — git's behavior when both
+the credential helper AND `GIT_ASKPASS` have failed. Before this PR
+that fallback hung indefinitely behind a TTY prompt. After this PR
+git returns a normal "could not read Username" error and the bash
+command exits, the supervisor logs a degradation, and the next
+restart attempt proceeds normally.
+
+Under-block risk: zero. The flag does not silence auth errors, only
+the prompt. Misconfigured credentials still surface as a visible
+failure; they just no longer wedge the supervisor.
+
+Over-block risk: a user who *wants* git to prompt them interactively
+when running `git pull` inside `tmux attach -t echo-server` will no
+longer see the prompt — but that's already an unusual workflow on a
+supervisor-managed tmux session (the user is supposed to use their
+own shell for that). Acceptable trade-off; the alternative is the
+loop.
+
+## Signal vs authority audit
+
+Drift checker is a **signal source**. Three structural guarantees:
+
+1. The verdict is the **only** thing the checker returns. It does not
+   call into the InitiativeTracker, does not write to disk, does not
+   short-circuit any other path. Authority for "may this round start"
+   lives entirely in the round-runner (PR 2).
+2. The `manual-review-required` verdict is **distinct** from the
+   three "trustable" verdicts. Consumers cannot accidentally treat it
+   as a soft pass: the type system requires them to discriminate.
+3. Citation excerpts shown to the user / surfaced in the digest are
+   re-rendered from disk by the checker, **not** the LLM's claimed
+   text. A model that fabricates evidence cannot poison the digest
+   that the user reads.
+
+Supervisor fix has no signal-vs-authority semantics — it's an env
+flag.
+
+## Interactions with existing systems
+
+- **IntelligenceProvider.** The checker is the third consumer of the
+  abstraction (after `DiscoveryEvaluator` and `MessageSentinel`).
+  Same call shape (`evaluate(prompt, options)`), same `'fast' |
+  'balanced' | 'capable'` model tiers. Adds a per-call `timeoutMs`
+  to `IntelligenceOptions`; existing providers ignore the field
+  (signature is additive), and the checker enforces the timeout
+  externally via `Promise.race` regardless. No provider needs to be
+  updated.
+- **InitiativeTracker.** The two new fields (`lastDriftVerdictAt`,
+  `lastDriftReferencedFileHashes`) are optional and unused until the
+  round-runner ships in PR 2. Records persisted today round-trip
+  through TaskFlow's `stateJson` blob; the new fields will appear on
+  read for any record they're written to and be silently absent for
+  records that predate them.
+- **Server supervisor.** The tmux flag survives an existing tmux
+  server (per `man tmux`, `-e` is the per-session env that
+  process.env cannot reach once tmux is already running). The flag
+  is set on every new server-session spawn, including the recovery
+  path after a wake or a restart.
+- **Existing routes / skills.** No route changes in this PR. The
+  `/projects/:id/drift-check` endpoint mentioned in the spec lands
+  with the round-runner in PR 2.
+
+## Rollback cost
+
+Drift checker is inert if reverted — no callers, no migration to
+unwind, no on-disk state. Reverting `src/core/types.ts` removes the
+`DriftVerdict` export, which is a compile-time impact for any
+downstream code that imports it — but no such code exists yet.
+
+Supervisor fix is a one-line revert. The git-prompt-hang behavior
+returns; mitigation is to set `GIT_TERMINAL_PROMPT=0` in the user's
+launchd plist environment (which is also why the source comment
+explains *why* the flag is needed: future authors will not
+accidentally remove it thinking it's redundant).
+
+## What this PR explicitly defers
+
+Per spec § Phase 1.4, these belong to drift but ship in Phase 1b
+PR 2 alongside the round-runner:
+
+- **Cache** keyed by `sha256(promptTemplateVersion + modelId +
+  specBodySha + sortedFileHashes)`, TTL 24h. The function that builds
+  the cache-key inputs is shipped here (`cacheKeyInputs`) so the
+  consumer in PR 2 doesn't fork the implementation; what's missing
+  is the store + lookup + TTL.
+- **Mtime fast-path** — re-uses last cache entry if (specPath mtime,
+  referenced-file mtimes) all match, skipping the sha256 work.
+- **Cost ledger** at `.instar/drift-spend-YYYY-MM-DD.jsonl` with
+  flock-protected pre-reservation and a $1/day per-agent ceiling.
+- **`POST /projects/:id/drift-check` HTTP endpoint** (mutex-guarded
+  per-project).
+
+Each of these is additive — the checker as shipped returns a correct
+verdict on every call, just without rate-limit or memoization.
+
+## Verification
+
+- `npm run lint` — passes (tsc + lint-no-direct-destructive).
+- `npx vitest run tests/unit/ProjectDriftChecker.test.ts
+  tests/unit/server-supervisor-preflight.test.ts` — 50/50 pass.
+- Manual review of the source against spec § Phase 1.4: the four
+  hardening properties (path jail, prompt delimiters, schema validation,
+  citation re-verification) are each backed by at least two test
+  cases. The token budget enforces the spec's "never silently
+  summarize" rule.
+- Supervisor fix verified live: setting `GIT_TERMINAL_PROMPT=0` at
+  the tmux global env unblocked the runaway-restart loop on the
+  author's own server during this evening's gate verification.

package/upgrades/side-effects/stuck-input-sentinel.md

@@ -0,0 +1,137 @@
+# Side-Effects Review — Persistent Stuck-Input Sentinel
+
+**Version / slug:** `stuck-input-sentinel`
+**Date:** `2026-05-11`
+**Author:** `echo`
+**Second-pass reviewer:** `general-purpose subagent` *(required: sentinel terminology + session-lifecycle interaction)*
+
+## Summary of the change
+
+Adds `src/core/StuckInputSentinel.ts`, a long-lived periodic worker that runs alongside `SessionManager.startMonitoring()`. Every `tickMs` (default 10s) it scans every running session, captures the bottom of the tmux pane, and decides whether the prompt holds unsubmitted text. If the same text persists across two ticks (≥20s with defaults) AND the pane shows no working indicator, it fires the same escalating recovery the in-process `verifyInjection` uses (`SessionManager.fireStuckInputRecovery`) — Enter, Enter, C-m, Enter+sleep+Enter — bounded at four attempts per stuck event. Each fire writes one row to `<stateDir>/stuck-input-events.jsonl` for operator audit and DegradationReporter consumption.
+
+This is the durable backstop for PR #159 (v0.28.92). The in-process polling schedule (500/1500/3500/6500ms) sits entirely inside a single server process. A crash inside that 6.5s window — exactly what happened on echo 2026-05-11 during the better-sqlite3 ABI-rebuild loop that put the server in a 30+ minute restart cycle — drops every armed timer with no recovery. The sentinel re-attempts recovery from a fresh state on every restart, so the window of "stuck and undetected" is bounded by the tick interval rather than by the crash schedule.
+
+**Files touched:**
+- `src/core/StuckInputSentinel.ts` (new, 290 lines)
+- `src/core/SessionManager.ts` (visibility change: `isMarkerStuckAtPrompt` and `fireStuckInputRecovery` `private` → public so the sentinel can reuse them without inheriting from SessionManager or duplicating logic)
+- `src/commands/server.ts` (instantiate the sentinel after `sessionManager.startMonitoring()`; stop it during the shutdown handler)
+- `tests/unit/StuckInputSentinel.test.ts` (new — 20 behavior tests)
+- `tests/unit/session-injection-verify.test.ts` (regex regression: the previous test asserted the `private` keyword in the recovery helper definition; updated to match either visibility)
+
+## Decision-point inventory
+
+- `StuckInputSentinel.evaluateSession` — **add** — decides "does this pane look stuck right now?" (text-at-prompt + no working indicator + persistent across ticks)
+- `StuckInputSentinel.fireStuckInputRecovery` *(delegated)* — **pass-through** — reuses the existing `SessionManager.fireStuckInputRecovery` escalation; not a new authority surface, just a new caller.
+- `SessionManager.isMarkerStuckAtPrompt` / `fireStuckInputRecovery` — **modify** — visibility relaxed (private → public). Behavior unchanged.
+
+---
+
+## 1. Over-block
+
+**No block/allow surface — over-block not applicable.**
+
+The sentinel does not gate or filter messages. Its single action surface is `tmux send-keys ... Enter` (or `C-m`) into a pane the SessionManager already owns. The "false positive" failure mode is "Enter pressed against an idle prompt that had no actual text" — and the sentinel's preconditions (extractPromptText returns non-empty AND minTicksBeforeFire elapsed) make this concrete shape essentially impossible: if `extractPromptText` returns empty, the sentinel returns early and never fires.
+
+The closest analog to over-block is "Enter fired during a transient state that wasn't actually stuck." The `isPaneActivelyWorking` guard rejects that case: any pane showing a Claude Code footer activity hint (`esc to interrupt`, `ctrl+t to hide tasks`, `tokens · esc`) is skipped without firing. We deliberately **do not** key on line-start spinner glyphs (`✻ ✶` etc.) because past-tense markers like `✻ Brewed for 14m 11s` and `✻ Churned for 1m 16s` stick around as visible pane content long after the turn finished. Live reproduction on echo's 2026-05-11 stuck sessions (`echo-qalatra`, `echo-exploring-slack-integration`) showed both held a stale `Brewed`/`Churned` line while genuinely idle — keying on the glyph would have caused the sentinel to skip exactly the cases it's meant to recover. The footer hints, on the other hand, are structurally only rendered mid-turn, so they're the precise tell. The min-ticks-before-fire requirement (default 2 ticks, ≥20s) gives `verifyInjection`'s 6.5s window full priority on fresh injections — the sentinel never races with the in-process recovery on the same event.
+
+## 2. Under-block
+
+**No block/allow surface — under-block not applicable.**
+
+What the sentinel _misses_ is recoverable text that takes longer than `maxAttempts * tickMs` to recover (default ≥40s, all four Enter forms tried). After that, the per-session record marks itself `exhausted` and the sentinel stops firing on that exact prompt text until the user types something new. This is intentional: if four escalating recovery forms can't unstick a pane, more of the same won't help, and the user is now in a state where manual intervention is appropriate. The sentinel records the exhausted state to the events log so operators can see what was tried.
+
+The other "miss": panes whose state genuinely needs something other than Enter (e.g., the pane is showing a `[Y/n]` confirmation prompt that ate the injection's Enter and is now waiting for `y`). Pressing Enter against a `[Y/n]` prompt typically takes the default — usually the safe choice. This is the same behavior `verifyInjection`'s recovery has today; not a regression.
+
+## 3. Level-of-abstraction fit
+
+This belongs at the **session-lifecycle layer** (alongside `SessionManager`), not at the messaging layer (Telegram/Slack/iMessage adapters) and not at the per-injection layer (`verifyInjection`).
+
+- Adapter layer is wrong because the bug isn't messaging-specific; any text that arrives at the tmux prompt and never submits is affected, regardless of how it got there.
+- Per-injection layer is the existing `verifyInjection` — it owns the fast path (≤6.5s). The sentinel _complements_ it at the slow / restart-resilient path, not replaces it.
+- Session-lifecycle layer is correct: the sentinel reads sessions from `SessionManager.listRunningSessions()`, captures via `SessionManager.captureOutput`, and reuses `fireStuckInputRecovery`. It owns one specific recovery concern — "did the prompt accept this Enter?" — and has no other responsibility.
+
+A lower-level primitive worth flagging: the `extractPromptText` heuristic ("text after the last ❯") is brittle to Claude Code TUI changes. If a future Claude Code release replaces ❯ with a different prompt glyph, the sentinel goes silent (no over-fires, just no recoveries). That's acceptable behavior — the sentinel degrades to a no-op, and `verifyInjection`'s existing heuristic is updated alongside. Both heuristics live in code that's easy to find and change together (`isMarkerStuckAtPrompt` and `extractPromptText` are both in `src/core/`).
+
+---
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+- [x] No — this change has no block/allow surface.
+
+The sentinel is a **recovery detector with a bounded action surface**. It does not gate messages, does not block any flow, does not produce a 4xx response, does not refuse to dispatch. It produces one `tmux send-keys Enter` at most per tick per session, bounded at four attempts per stuck event, against a pane whose state is unambiguous (text-at-prompt + no working indicator + persistent).
+
+The "Enter" action against a pane that turns out not to be stuck is provably benign: an empty Enter at an idle Claude Code prompt is a no-op. We're not in the "brittle detector with blocking authority" risk category — there is no blocking authority anywhere in this change.
+
+---
+
+## 5. Interactions
+
+- **Shadowing of `verifyInjection`:** the sentinel's `minTicksBeforeFire = 2` (≥20s with default `tickMs = 10s`) sits well past `verifyInjection`'s last attempt at 6.5s, so the two never race on the same event. The sentinel takes over only after the in-process path either succeeded (prompt clear → sentinel never sees it as stuck) or exhausted (prompt still stuck after 6.5s → sentinel picks up at ~20s).
+- **Shadowing of `SessionManager.monitorTick`:** independent setInterval, independent `tickInProgress` guard. They share `listRunningSessions` reads but each call is `O(running)` and the data is already cached on the SessionManager. No mutual write contention.
+- **Double-fire on the same Enter:** would require `verifyInjection`'s schedule still ticking past the 20s mark, which the schedule does not (max attempt is at 6.5s). Cannot happen by construction.
+- **Race with session-killing path:** if a session gets killed between `listRunningSessions()` and the per-session pane capture, `captureOutput` returns null (or throws); the sentinel swallows the error and moves on. The GC step at end of `tick()` drops the record so a respawned session with the same name starts clean.
+- **Race with `purgeDeadSessions`:** purge runs once at boot before `startMonitoring`; the sentinel starts only after monitoring is up, so it never sees the pre-purge set.
+- **Feedback loop with itself:** firing Enter against a non-stuck pane (false positive) appears at the next tick as a different (or empty) prompt text, which resets the per-session record. The sentinel cannot loop on its own action.
+
+---
+
+## 6. External surfaces
+
+- **Other agents on the same machine:** none — the sentinel only sends keys to tmux sessions this agent's SessionManager owns. Cross-agent tmux interaction is impossible because tmux sessions are namespaced per-agent (`echo-…`, `dawn-…`).
+- **Other users:** none — runtime addition with no API surface.
+- **External systems:** none — `tmux send-keys` is a local IPC.
+- **Persistent state:** new file `<stateDir>/stuck-input-events.jsonl`, append-only, one row per fire. No schema migration; consumers can ignore the file. The file is best-effort — failures to write don't halt the sentinel.
+- **Timing/runtime conditions:** the sentinel's effectiveness depends on the server being up at least one `tickMs` past the stuck event. If the server crashes faster than `tickMs` *every* time after a stuck event, recovery never fires. This is a degenerate case — the underlying server crash is the bug, and other mechanisms (lifeline restart counter, manual operator intervention) catch it.
+
+---
+
+## 7. Rollback cost
+
+**Pure code addition. Revert and ship as next patch.**
+
+- No persistent state migration. The JSONL events log is append-only and can simply stop being written.
+- No schema changes.
+- No agent state repair. Disabling the sentinel mid-run loses no in-flight work — verifyInjection still handles the fast path.
+- User-visible regression during rollback: zero. The sentinel only fires Enter against panes the user *wants* to recover; removing it returns to v0.28.92 behavior.
+
+Worst case if the sentinel misbehaves in production: false-positive Enters against idle prompts (no-ops) or against `[Y/n]` confirmations (takes the default). Neither is destructive. A hot-fix that disables the sentinel via early-return at `start()` is a one-line change.
+
+---
+
+## Conclusion
+
+This change closes the architectural hole in PR #159 (v0.28.92): in-process timers don't survive server restarts, and the bug the user reported on 2026-05-11 is _specifically_ that gap. The sentinel is decoupled from injection-time state — it observes panes purely from `captureOutput`, holds state in memory, and recovers from a fresh start on every server boot. The signal-vs-authority principle does not apply because there is no blocking surface; the action surface is one Enter keypress per attempt, bounded.
+
+A second-pass review is required by the skill (sentinel terminology + session-lifecycle interaction). The reviewer should specifically check the `isPaneActivelyWorking` heuristic (does it correctly skip "✶ Running…" panes? does it correctly NOT skip a stale `✻ Brewed for…` past-tense marker?) and confirm that no race with `verifyInjection` can produce double-fires within the 6.5s window.
+
+---
+
+## Second-pass review (if required)
+
+**Reviewer:** general-purpose subagent
+**Independent read of the artifact: concur (with two tight-but-acceptable callouts)**
+
+A. Verified clean. `evaluateSession` sets `consecutiveTicks=1` on first sight and returns; firing requires `consecutiveTicks >= minTicksBeforeFire` (=2), so the earliest fire is one full `tickMs` (10s) after first observation. That's safely past `verifyInjection`'s 6.5s window in wall-clock terms — even if a tick fires immediately after server start and observes a prompt that an injection just landed, the second observation is ~10s later, by which point `verifyInjection`'s last attempt has already resolved. (`src/core/StuckInputSentinel.ts:220-236`.)
+
+B. *Originally flagged as tight-but-acceptable; resolved before commit.* After live-testing the sentinel against echo's 2026-05-11 stuck sessions (`echo-qalatra`, `echo-exploring-slack-integration`), both panes held a stale `✻ Brewed for…` / `✻ Churned for…` line — exactly the user-visible failure mode this change is meant to recover. The spinner-glyph branch was removed; `isPaneActivelyWorking` now keys solely on the footer activity hints (`esc to interrupt`, `ctrl+t to hide tasks`, `tokens · esc`), which Claude Code only renders mid-turn. Tests updated: the suite now explicitly asserts that stale Brewed/Churned lines are treated as idle (the previously-mis-flagged case) and that present-tense glyph lines are also ignored unless accompanied by a footer hint.
+
+C. `extractPromptText` iterates bottom-up and picks the LAST `❯` line, which matches Claude Code's TUI invariant (active prompt at bottom). Historical `❯` glyphs higher in scrollback are correctly ignored. For 3+ line wrapped input, only the first wrapped line is read (`lines[i+1]`); this is sufficient as a stability fingerprint across ticks even if it doesn't capture the full wrapped body. Tight-but-acceptable callout: if Claude Code ever wraps such that `lines[i+1]` is whitespace and `lines[i+2]` holds the real content, the prompt looks empty and the sentinel returns null (silent no-op). Low-likelihood under current TUI behavior; flag for re-test on any Claude Code TUI bump.
+
+D. Cross-restart unboundedness acknowledged in §6. Worst case is N+M Enters across a crash boundary (N before, M after); after the first successful Enter the prompt clears and subsequent Enters land on an idle pane (no-op). Cost bounded and benign.
+
+E. `tick()` is fully synchronous; the `try / finally` at `StuckInputSentinel.ts:144-152` resets `tickInProgress=false` even if `tick()` throws. The inner `evaluateSession` also wraps tmux failures locally, so an error there won't escape past the outer finally. Clean.
+
+F. Confirmed pure side-effect surface. The sentinel only delegates to `SessionManager.fireStuckInputRecovery`, which is exclusively `execFileSync(tmuxPath, ['send-keys', …])`. No message gate, no transport-layer block, no 4xx response path. Signal-vs-authority compliance holds.
+
+Net: ship.
+
+---
+
+## Evidence pointers
+
+- Live reproduction: echo's tmux sessions `echo-exploring-slack-integration`, `echo-qalatra`, `echo-threadline-dev` on 2026-05-11 — text-at-prompt with no spinner, no submission, after a server crash-loop window. None of these messages reached the corresponding Claude Code transcripts (`grep -l "start the rewrite now" ~/.claude/projects/-Users-justin--instar-agents-echo/*.jsonl` returns nothing).
+- Unit tests: `tests/unit/StuckInputSentinel.test.ts` — 20 passing tests covering extraction, working-state detection, tick lifecycle, escalation order, max-attempts cap, prompt-change reset, prompt-clear reset, session-GC.
+- Regression coverage: `tests/unit/session-injection-verify.test.ts`, `tests/unit/session-multishot-recovery.test.ts`, `tests/unit/SessionManager-injection.test.ts` all green after the visibility-relaxation regex update.
+- Type-check: `tsc --noEmit -p .` clean.