instar 1.3.665 → 1.3.667

package/upgrades/1.3.666.md

@@ -0,0 +1,131 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+An Instar session could be silently, permanently wedged by an agent-framework approval
+prompt it cannot answer. Claude Code 2.1.176-177 added a hardcoded Bash safety prompt —
+`cd <dir> && <cmd>` combined with a redirect/pipe pops "Do you want to proceed? ❯ 1. Yes
+/ 2. No / Esc to cancel" — that runs BEFORE all permission rules and PermissionRequest
+hooks, so `--dangerously-skip-permissions` and `permissions.allow` cannot suppress it.
+A remote-driven session (Telegram/dashboard) cannot press a terminal key, so it freezes
+while still *looking* busy (PresenceProxy could even report "actively working"). The
+empirically-confirmed reason it bit the fleet: the existing PromptGate/AutoApprover
+pipeline was persisted `enabled:false` on deployed agents (a stale-`false` config wins
+over a newer `true` default), so nothing answered the prompt.
+
+- **New `src/monitoring/PermissionPromptAutoResolver.ts`** — an always-on, deterministic,
+  zero-LLM safety floor driven once per monitoring tick. It detects a live, focused
+  approval menu in a session's tmux tail and sends the approve keystroke itself.
+  - **Layer 2 (auto-answer):** requires ≥2 distinct registered prose patterns AND a live
+    glyph-led `❯`-cursor-on-an-approve-option line at the genuine bottom of the tail
+    while not generating; sends **`Enter`** only (confirm the highlighted "Yes"), with a
+    re-capture-before-send check. Because a text capture cannot *perfectly* distinguish a
+    real TUI selector from displayed content containing the same characters, this is
+    bar-raising mitigation (stated honestly), bounded by Enter-only (a false match is a
+    benign empty submit), a per-episode `MAX_ATTEMPTS=3` (reset-on-clear so distinct
+    prompts are independent), and a terminal defect.
+  - **Layer 3 (broad detector):** a prose-agnostic `detectPersistingMenu` surfaces ANY
+    persisting glyph-led menu the auto-answer declines (cursor-not-on-approve, or a future
+    prompt whose wording drifts) as a single deduped Attention defect — so nothing is ever
+    silently stranded, and it doubles as the prompt-string drift detector.
+- **`src/core/paneTail.ts`** gains a pure `leadGlyphsOf(line)` helper so the detector can
+  test for the `❯` selector glyph (U+276F) specifically.
+- **`StuckSignatureClassifier`** gains an `approval-prompt-waiting` kind; **`PresenceProxy`**
+  never surfaces it as a user message (the sole user-facing surface is the terminal
+  defect), killing the false "actively working" report for a prompt-wedged session.
+- **The floor is unconditional — no persisted `enabled:true` to rot to `false`** (the
+  exact trap that caused the bug). The only opt-out is `monitoring.permissionPromptAutoResolver.emergencyDisable`
+  (absent ⇒ on). A computed guard-posture key (`guardPosture.ts`) + a runtime
+  `guardStatus()` + a `GUARD_MANIFEST` entry make a disabled floor a visible incident in
+  `GET /guards`.
+- Existing wedged sessions recover automatically: the server restart that deploys the
+  update restarts the monitor loop, which auto-clears any session currently parked on the
+  prompt. No new setting, no manual step.
+
+The resolver answers a UI-flow prompt only; it never widens what commands are allowed
+(the destructive `dangerous-command-guard` denylist remains an independent guard). The
+auto-approve is accepted under the operator full-machine-access trust model. Converged
+through 6 spec-review rounds (6 internal reviewers + codex/gemini cross-model).
+
+CMT-1785: the idle-error detector that decides "did this paused session stall on a transient API
+error (nudge it) or stop normally (leave it)?" is migrated from a brittle bare-substring scan to a
+tail-gated, frame-discriminated SIGNAL.
+
+- New pure modules `src/core/paneTail.ts` (shared `liveTail`/`stripLineLead`/`wasGlyphLed` — ONE
+  definition of "the live tail", extracted so it is no longer copied per consumer) and
+  `src/core/IdleErrorClassifier.ts` (`classifyIdleError`).
+- The old gate `TERMINAL_ERROR_PATTERNS.some(p => recentOutput.includes(p))` (a bare `.includes()`
+  over the whole capture) is replaced by `classifyIdleError`, which fires only when a terminal-error
+  token sits in the live tail (last 20 non-empty lines) on a Claude-EMITTED error frame — a two-tier
+  begins-with rule: **Tier A** the line begins with `API Error:`; **Tier B** the line is glyph-led
+  (`⏺`/`⎿`/…) and begins with one of the 11 patterns. The match set is a strict subset of the old
+  buffer-wide match, so the change can only SUPPRESS spurious fires, never add one.
+- The idle-error capture is widened 30→45 rows (`RATE_LIMIT_SETTLED_CAPTURE_LINES`): Claude Code's
+  input box + footer render 15-25 rows BELOW the error, so a 30-row capture could miss it entirely.
+- `StuckSignatureClassifier` is migrated onto the shared `liveTail` (behavior-preserving via
+  `.join('\n')`; its existing test corpus is the characterization guard).
+- A once-per-idle-episode structured record (`{event:'idle-error-classify', result:'fired'|'suppressed', …}`)
+  lands in `logs/server.log` so a wave of suppressions on genuine errors (the under-fire risk) is
+  observable. Cleared in both the re-arm block and `sessionComplete` (no leak on the death path).
+
+The signal still feeds the existing `apiErrorAtIdle` → `rateLimitSentinel` recovery actuator and gains
+no blocking authority (Signal vs Authority).
+
+## What to Tell Your User
+
+Your agent will no longer get silently stuck on a pop-up it can't answer. A recent
+update to the coding tool added a safety pop-up ("Do you want to proceed? Yes / No") that
+freezes the session, because nobody can press a key on it from your phone — and there's no
+setting to turn it off. Now a small always-on layer answers that pop-up itself, only ever
+pressing the harmless "Yes", and it's built into the code with no on/off switch that could
+get stuck "off" (a stuck-off setting is exactly what caused the freeze). If it ever hits a
+pop-up it genuinely can't clear (say a future version changes the wording), it stops and
+sends you one "please take a look" notice instead of freezing silently. Nothing for you to
+do; your agent just stays reachable.
+
+Nothing you need to do. Under the hood, the agent got more reliable at telling a session that genuinely
+stalled on an API error (which it nudges back to life) apart from one that's merely *showing* an old or
+quoted error on screen. The old check was a blunt text search that sometimes kicked off a needless
+recovery on a healthy session, and — more importantly — sometimes read too little of the screen and
+missed a real stall. The new check looks at the live bottom of the screen, reads enough of it to clear
+the input box, and only counts a line the tool actually emitted as an error. Net: fewer false recoveries
+AND fewer missed real ones, so paused sessions get the right treatment faster. No new setting; behavior
+is otherwise unchanged, and it's a one-line revert if ever needed.
+
+## Summary of New Capabilities
+
+- An always-on safety floor that auto-answers an un-answerable framework approval prompt,
+  so a remote-driven session is never silently wedged.
+- Honest, bounded detection (live glyph-led menu, Enter-only, re-capture, attempt cap) +
+  a prose-agnostic backstop so a drifted/unrecognized prompt surfaces rather than strands.
+- Visible in `GET /guards` (`on-confirmed`); an audit trail at
+  `logs/permission-prompt-resolver.jsonl` (matched-pattern names only, never raw tail);
+  emergency opt-out via `monitoring.permissionPromptAutoResolver.emergencyDisable`.
+
+- `paneTail` + `IdleErrorClassifier` — a precise, tail-gated, frame-discriminated idle-error signal
+  replacing the bare buffer-wide substring scan; widened capture (45 rows) so the input-box chrome can
+  no longer hide a real error; structured once-per-episode observability of fired-vs-suppressed
+  decisions. Internal robustness improvement to session-stall recovery; no user-facing surface to
+  configure.
+
+## Evidence
+
+- `tests/unit/IdleErrorClassifier.test.ts` (28) — both sides of every boundary, pinned to REAL captured
+  render fixtures: fires on `⏺ API Error:` / `  ⎿  API Error:` / glyph-led network tokens / wrapped
+  errors; suppresses stale-scrollback, prose mentions, quoted source literals (the self-collision case),
+  a tool's own `Error: …ECONNREFUSED`; the 45-vs-30 input-box-chrome capture test; parametrized over all
+  11 patterns; bounded audit fields; paneTail helpers.
+- `tests/integration/idle-error-classifier-production-wiring.test.ts` (7) — the REAL exported
+  `TERMINAL_ERROR_PATTERNS` produce correct decisions on real panes; the SessionManager call-site is
+  wired to the classifier, the 45-row capture, the dual once-per-episode clears, and the structured record.
+- `tests/e2e/idle-error-classifier-lifecycle.test.ts` (2) — the real SessionManager constructs and the
+  `apiErrorAtIdle` recovery handoff is attachable; the production-pattern live decision is correct.
+- `tests/unit/monitoring/StuckSignatureClassifier.test.ts` (13) — unchanged, the characterization guard
+  proving the shared-`liveTail` migration is behavior-preserving.
+- `npm run build` + `tsc --noEmit` clean; full unit suite green.
+- Driven by the converged + approved spec; convergence report at
+  `docs/specs/reports/idle-error-tailgate-corroboration-convergence.md` (4 rounds; the review caught a
+  CRITICAL under-fire-on-the-common-error-form flaw before any code).

package/upgrades/1.3.667.md

@@ -0,0 +1,32 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Fixed the "session paused" lockout (topic 28130): `MessageSentinel` was consuming the operator's benign inbound messages whenever its LLM classifier returned — or capacity-shed to — `'pause'`, and the "send a message to resume" recovery routed back through the same failing gate, an inescapable loop. New constitutional standard **"The Operator Channel Is Sacred — Critical-Path Gates Fail Toward Delivery"** (in `STANDARDS-REGISTRY.md`) + its exemplar fix:
+
+- `'pause'` now consumes a message ONLY on a DETERMINISTIC fast-path match; a bare-LLM or capacity-shed `'pause'` routes THROUGH (delivered to the agent), never consumed.
+- Before routing a non-deterministic result through, a non-word-count-gated stop-token scan rescues a long-form genuine "stop" to a kill (so a real stop is never dropped).
+- A per-topic circuit-breaker bounds blast radius (a misclassification stream can't permanently lock the operator out).
+- Both inbound consume paths (`onSentinelIntercept` + `/internal/telegram-forward`) decide via one shared `MessageSentinel.decideInboundDisposition`, so policy can't diverge.
+- `/sentinel/stats` now exposes disposition counters (consumed / routed-through / breaker-recovered).
+
+## What to Tell Your User
+
+If your agent ever appeared "paused" and ignored your messages — replying "Session paused. Send a message to resume." in a loop — that's fixed. A safety check could mislabel an ordinary message as a "pause" command and silently eat it (worse, under load it defaulted to pausing). Now your messages are delivered unless you *unambiguously* typed a pause/stop command, and a genuine "stop" is always honored. The channel to your agent can no longer be sealed by a wrong guess.
+
+## Summary of New Capabilities
+
+- Standard "The Operator Channel Is Sacred" — a gate on the operator's inbound channel must fail toward DELIVERY; a brittle signal may not consume/block a message; recovery must not route through the failing gate; decision-gates have bounded blast radius.
+- `MessageSentinel.decideInboundDisposition` + `hasStopToken` + disposition observability counters.
+
+## Evidence
+
+- `tests/unit/MessageSentinel-operator-channel-sacred.test.ts` (13) — deterministic pause consumes; benign LLM-pause + capacity-shed route through; long-form stop rescued to kill; circuit-breaker auto-recovers; per-topic isolation; counters; hasStopToken both-sides.
+- `tests/integration/operator-channel-sacred-wiring.test.ts` (3) — both consume sites use the shared disposition helper; old consume-on-any-pause gone.
+- `tests/integration/telegram-forward-sentinel-intercept.test.ts` — updated to the disposition contract incl. a new route-through-delivers test.
+- `tests/e2e/operator-channel-lockout-regression.test.ts` (4) — no benign stream (even with the LLM mislabeling every message, or sustained capacity-shed) can lock the channel; recovery is escapable; a genuine stop still honored.
+- `npm run build` + `tsc --noEmit` clean; consume-path + MessageSentinel suites green.
+- Converged + approved spec; convergence report at docs/specs/reports/operator-channel-sacred-convergence.md.

package/upgrades/side-effects/operator-channel-sacred.md

@@ -0,0 +1,31 @@
+# Side-Effects Review — Operator Channel Is Sacred (MessageSentinel pause-lockout fix)
+
+Spec: docs/specs/operator-channel-sacred.md (converged + approved). Standard integrated into docs/STANDARDS-REGISTRY.md.
+Change: MessageSentinel `'pause'` consumes a message ONLY on a deterministic match; a bare-LLM or capacity-shed `'pause'` routes THROUGH (with a stop-token rescue); a per-topic circuit-breaker bounds blast radius; both inbound consume paths (server.ts onSentinelIntercept + routes.ts /internal/telegram-forward) decide via one shared `decideInboundDisposition`.
+
+## 1. Over-block
+The change can ONLY reduce consumption (more messages delivered). The one residual: `hasStopToken` is intentionally conservative (a whole-word "stop" anywhere → rescue to kill), so a benign message that the classifier already called 'pause' AND contains a whole-word stop ("non-stop") would be killed. Accepted: a kill is RECOVERABLE ("send a new message to start fresh"), unlike the pause lockout; and it only triggers on an already-pause-classified message, not normal traffic.
+
+## 2. Under-block
+A genuine pause directive that is non-deterministic (LLM-only) is now NOT honored (routes through). Accepted per the standard + the code's own comment ("pause's value is politeness, not safety"). A genuine STOP is preserved: deterministic fast-path stop fires instantly; a long-form/capacity-shed stop is rescued by `hasStopToken`.
+
+## 3. Level-of-abstraction fit
+The standard lives in ONE place (`MessageSentinel.decideInboundDisposition`); both consume sites call it, so policy cannot diverge between the poll path and the lifeline-forward path. Signal-vs-Authority: the classifier signals; the deterministic gate holds consume authority.
+
+## 4. Signal vs authority compliance
+Compliant + the exemplar of the new standard. A brittle (LLM/capacity-shed) signal no longer has authority to consume the operator's message; only a deterministic match (or a rescued stop) actuates.
+
+## 5. Interactions
+- detectRateLimited / throttle path: unchanged (separate).
+- The capacity-shed return (llmClassify catch, confidence 0.4) now routes through instead of consuming — reconciled with the fork-bomb/No-Silent-Degradation fail-closed posture as a NAMED inbound exception (the deterministic emergency-stop pre-check + the stop-token rescue keep a real stop from ever being dropped).
+- Emergency-stop kill path + resume-queue stop custody: unchanged for `disposition: 'kill'`.
+- Circuit-breaker is in-memory shared across both paths (same MessageSentinel instance); in-memory is safe because the PRIMARY guard is deterministic-only-consume — a restart resetting the breaker cannot reintroduce the lockout. (Reasoned deviation from the spec's "durable" FD2: the build showed deterministic-only-consume makes breaker durability non-load-bearing; documented here.)
+
+## 6. External surfaces
+The user-facing change: benign messages that were being eaten as "Session paused" now reach the agent. `getStats()` (/sentinel/stats) now also exposes `disposition` counters (pause.consumed / .routed-through / breaker.recovered) — additive. No new route, no config schema change (the existing `externalOperations.sentinel.enabled` still gates the whole sentinel).
+
+## 7. Multi-machine posture
+Machine-local: each machine's MessageSentinel decides for its own inbound; both consume paths on a machine share its one instance + breaker. No cross-machine state. (Lifeline-owned agents hit the routes.ts path; poll-mode hits onSentinelIntercept — both on the same machine, same sentinel.)
+
+## 8. Rollback cost
+Single-commit revert restores the prior classify-then-consume logic. No migration, no durable state. The interim safeguard (`externalOperations.sentinel.enabled:false`) can stay until this merges, then be re-enabled (this fix makes the sentinel safe to re-enable).

package/upgrades/1.3.665.md

@@ -1,68 +0,0 @@
-# Upgrade Guide — vNEXT
-
-<!-- assembled-by: assemble-next-md -->
-<!-- bump: patch -->
-
-## What Changed
-
-CMT-1785: the idle-error detector that decides "did this paused session stall on a transient API
-error (nudge it) or stop normally (leave it)?" is migrated from a brittle bare-substring scan to a
-tail-gated, frame-discriminated SIGNAL.
-
-- New pure modules `src/core/paneTail.ts` (shared `liveTail`/`stripLineLead`/`wasGlyphLed` — ONE
-  definition of "the live tail", extracted so it is no longer copied per consumer) and
-  `src/core/IdleErrorClassifier.ts` (`classifyIdleError`).
-- The old gate `TERMINAL_ERROR_PATTERNS.some(p => recentOutput.includes(p))` (a bare `.includes()`
-  over the whole capture) is replaced by `classifyIdleError`, which fires only when a terminal-error
-  token sits in the live tail (last 20 non-empty lines) on a Claude-EMITTED error frame — a two-tier
-  begins-with rule: **Tier A** the line begins with `API Error:`; **Tier B** the line is glyph-led
-  (`⏺`/`⎿`/…) and begins with one of the 11 patterns. The match set is a strict subset of the old
-  buffer-wide match, so the change can only SUPPRESS spurious fires, never add one.
-- The idle-error capture is widened 30→45 rows (`RATE_LIMIT_SETTLED_CAPTURE_LINES`): Claude Code's
-  input box + footer render 15-25 rows BELOW the error, so a 30-row capture could miss it entirely.
-- `StuckSignatureClassifier` is migrated onto the shared `liveTail` (behavior-preserving via
-  `.join('\n')`; its existing test corpus is the characterization guard).
-- A once-per-idle-episode structured record (`{event:'idle-error-classify', result:'fired'|'suppressed', …}`)
-  lands in `logs/server.log` so a wave of suppressions on genuine errors (the under-fire risk) is
-  observable. Cleared in both the re-arm block and `sessionComplete` (no leak on the death path).
-
-The signal still feeds the existing `apiErrorAtIdle` → `rateLimitSentinel` recovery actuator and gains
-no blocking authority (Signal vs Authority).
-
-## What to Tell Your User
-
-Nothing you need to do. Under the hood, the agent got more reliable at telling a session that genuinely
-stalled on an API error (which it nudges back to life) apart from one that's merely *showing* an old or
-quoted error on screen. The old check was a blunt text search that sometimes kicked off a needless
-recovery on a healthy session, and — more importantly — sometimes read too little of the screen and
-missed a real stall. The new check looks at the live bottom of the screen, reads enough of it to clear
-the input box, and only counts a line the tool actually emitted as an error. Net: fewer false recoveries
-AND fewer missed real ones, so paused sessions get the right treatment faster. No new setting; behavior
-is otherwise unchanged, and it's a one-line revert if ever needed.
-
-## Summary of New Capabilities
-
-- `paneTail` + `IdleErrorClassifier` — a precise, tail-gated, frame-discriminated idle-error signal
-  replacing the bare buffer-wide substring scan; widened capture (45 rows) so the input-box chrome can
-  no longer hide a real error; structured once-per-episode observability of fired-vs-suppressed
-  decisions. Internal robustness improvement to session-stall recovery; no user-facing surface to
-  configure.
-
-## Evidence
-
-- `tests/unit/IdleErrorClassifier.test.ts` (28) — both sides of every boundary, pinned to REAL captured
-  render fixtures: fires on `⏺ API Error:` / `  ⎿  API Error:` / glyph-led network tokens / wrapped
-  errors; suppresses stale-scrollback, prose mentions, quoted source literals (the self-collision case),
-  a tool's own `Error: …ECONNREFUSED`; the 45-vs-30 input-box-chrome capture test; parametrized over all
-  11 patterns; bounded audit fields; paneTail helpers.
-- `tests/integration/idle-error-classifier-production-wiring.test.ts` (7) — the REAL exported
-  `TERMINAL_ERROR_PATTERNS` produce correct decisions on real panes; the SessionManager call-site is
-  wired to the classifier, the 45-row capture, the dual once-per-episode clears, and the structured record.
-- `tests/e2e/idle-error-classifier-lifecycle.test.ts` (2) — the real SessionManager constructs and the
-  `apiErrorAtIdle` recovery handoff is attachable; the production-pattern live decision is correct.
-- `tests/unit/monitoring/StuckSignatureClassifier.test.ts` (13) — unchanged, the characterization guard
-  proving the shared-`liveTail` migration is behavior-preserving.
-- `npm run build` + `tsc --noEmit` clean; full unit suite green.
-- Driven by the converged + approved spec; convergence report at
-  `docs/specs/reports/idle-error-tailgate-corroboration-convergence.md` (4 rounds; the review caught a
-  CRITICAL under-fire-on-the-common-error-form flaw before any code).