instar 1.3.664 → 1.3.666

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-06-25T10:17:36.090Z",
-  "instarVersion": "1.3.664",
+  "generatedAt": "2026-06-25T23:12:52.494Z",
+  "instarVersion": "1.3.666",
   "entryCount": 202,
   "entries": {
     "hook:session-start": {
@@ -11,7 +11,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/session-start.sh",
-      "contentHash": "1498dde6dd7c50457734d66245474781b703ecea97ea6d51391ca4de91ddaf3d",
+      "contentHash": "3f5b94f3892478477e6048a95a3b4b565c4b4050b803ad777356843b249c8889",
       "since": "2025-01-01"
     },
     "hook:dangerous-command-guard": {
@@ -20,7 +20,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/dangerous-command-guard.sh",
-      "contentHash": "1498dde6dd7c50457734d66245474781b703ecea97ea6d51391ca4de91ddaf3d",
+      "contentHash": "3f5b94f3892478477e6048a95a3b4b565c4b4050b803ad777356843b249c8889",
       "since": "2025-01-01"
     },
     "hook:grounding-before-messaging": {
@@ -29,7 +29,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/grounding-before-messaging.sh",
-      "contentHash": "1498dde6dd7c50457734d66245474781b703ecea97ea6d51391ca4de91ddaf3d",
+      "contentHash": "3f5b94f3892478477e6048a95a3b4b565c4b4050b803ad777356843b249c8889",
       "since": "2025-01-01"
     },
     "hook:compaction-recovery": {
@@ -38,7 +38,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/compaction-recovery.sh",
-      "contentHash": "1498dde6dd7c50457734d66245474781b703ecea97ea6d51391ca4de91ddaf3d",
+      "contentHash": "3f5b94f3892478477e6048a95a3b4b565c4b4050b803ad777356843b249c8889",
       "since": "2025-01-01"
     },
     "hook:external-operation-gate": {
@@ -47,7 +47,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/external-operation-gate.js",
-      "contentHash": "1498dde6dd7c50457734d66245474781b703ecea97ea6d51391ca4de91ddaf3d",
+      "contentHash": "3f5b94f3892478477e6048a95a3b4b565c4b4050b803ad777356843b249c8889",
       "since": "2025-01-01"
     },
     "hook:deferral-detector": {
@@ -56,7 +56,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/deferral-detector.js",
-      "contentHash": "1498dde6dd7c50457734d66245474781b703ecea97ea6d51391ca4de91ddaf3d",
+      "contentHash": "3f5b94f3892478477e6048a95a3b4b565c4b4050b803ad777356843b249c8889",
       "since": "2025-01-01"
     },
     "hook:self-stop-guard": {
@@ -65,7 +65,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/self-stop-guard.js",
-      "contentHash": "1498dde6dd7c50457734d66245474781b703ecea97ea6d51391ca4de91ddaf3d",
+      "contentHash": "3f5b94f3892478477e6048a95a3b4b565c4b4050b803ad777356843b249c8889",
       "since": "2025-01-01"
     },
     "hook:post-action-reflection": {
@@ -74,7 +74,7 @@
       "domain": "evolution",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/post-action-reflection.js",
-      "contentHash": "1498dde6dd7c50457734d66245474781b703ecea97ea6d51391ca4de91ddaf3d",
+      "contentHash": "3f5b94f3892478477e6048a95a3b4b565c4b4050b803ad777356843b249c8889",
       "since": "2025-01-01"
     },
     "hook:external-communication-guard": {
@@ -83,7 +83,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/external-communication-guard.js",
-      "contentHash": "1498dde6dd7c50457734d66245474781b703ecea97ea6d51391ca4de91ddaf3d",
+      "contentHash": "3f5b94f3892478477e6048a95a3b4b565c4b4050b803ad777356843b249c8889",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-collector": {
@@ -92,7 +92,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-collector.js",
-      "contentHash": "1498dde6dd7c50457734d66245474781b703ecea97ea6d51391ca4de91ddaf3d",
+      "contentHash": "3f5b94f3892478477e6048a95a3b4b565c4b4050b803ad777356843b249c8889",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-checkpoint": {
@@ -101,7 +101,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-checkpoint.js",
-      "contentHash": "1498dde6dd7c50457734d66245474781b703ecea97ea6d51391ca4de91ddaf3d",
+      "contentHash": "3f5b94f3892478477e6048a95a3b4b565c4b4050b803ad777356843b249c8889",
       "since": "2025-01-01"
     },
     "hook:free-text-guard": {
@@ -110,7 +110,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/free-text-guard.sh",
-      "contentHash": "1498dde6dd7c50457734d66245474781b703ecea97ea6d51391ca4de91ddaf3d",
+      "contentHash": "3f5b94f3892478477e6048a95a3b4b565c4b4050b803ad777356843b249c8889",
       "since": "2025-01-01"
     },
     "hook:claim-intercept": {
@@ -119,7 +119,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept.js",
-      "contentHash": "1498dde6dd7c50457734d66245474781b703ecea97ea6d51391ca4de91ddaf3d",
+      "contentHash": "3f5b94f3892478477e6048a95a3b4b565c4b4050b803ad777356843b249c8889",
       "since": "2025-01-01"
     },
     "hook:claim-intercept-response": {
@@ -128,7 +128,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept-response.js",
-      "contentHash": "1498dde6dd7c50457734d66245474781b703ecea97ea6d51391ca4de91ddaf3d",
+      "contentHash": "3f5b94f3892478477e6048a95a3b4b565c4b4050b803ad777356843b249c8889",
       "since": "2025-01-01"
     },
     "hook:stop-gate-router": {
@@ -137,7 +137,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/stop-gate-router.js",
-      "contentHash": "1498dde6dd7c50457734d66245474781b703ecea97ea6d51391ca4de91ddaf3d",
+      "contentHash": "3f5b94f3892478477e6048a95a3b4b565c4b4050b803ad777356843b249c8889",
       "since": "2025-01-01"
     },
     "hook:auto-approve-permissions": {
@@ -146,7 +146,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/auto-approve-permissions.js",
-      "contentHash": "1498dde6dd7c50457734d66245474781b703ecea97ea6d51391ca4de91ddaf3d",
+      "contentHash": "3f5b94f3892478477e6048a95a3b4b565c4b4050b803ad777356843b249c8889",
       "since": "2025-01-01"
     },
     "job:health-check": {
@@ -1538,7 +1538,7 @@
       "type": "subsystem",
       "domain": "sessions",
       "sourcePath": "src/core/SessionManager.ts",
-      "contentHash": "7ea591c3a48b752c066a2fdf0179804a6319177b3664bde1bcc20d9fc0a0d508",
+      "contentHash": "07c12341d721732f00a07e617140a0b4c6a3ad89d0c450c78a79f052d835be1e",
       "since": "2025-01-01"
     },
     "subsystem:auto-updater": {
@@ -1562,7 +1562,7 @@
       "type": "subsystem",
       "domain": "updates",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
-      "contentHash": "1498dde6dd7c50457734d66245474781b703ecea97ea6d51391ca4de91ddaf3d",
+      "contentHash": "3f5b94f3892478477e6048a95a3b4b565c4b4050b803ad777356843b249c8889",
       "since": "2025-01-01"
     },
     "subsystem:scheduler": {

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/side-effects/idle-error-tailgate-corroboration.md

@@ -0,0 +1,65 @@
+# Side-Effects Review — Idle-Error Detection: Tail-Gated, Frame-Discriminated Signal (CMT-1785)
+
+Spec: `docs/specs/idle-error-tailgate-corroboration.md` (converged 4 rounds, approved).
+Change: replace the bare `TERMINAL_ERROR_PATTERNS.some(includes)` idle-error detector at the
+`SessionManager` idle path with a tail-gated, frame-discriminated classifier (`IdleErrorClassifier`)
+fed by a shared `paneTail` helper; widen the idle-error capture 30→45 rows; add a once-per-episode
+structured observability record.
+
+## 1. Over-block (what legitimate inputs does this reject that it shouldn't?)
+The classifier can SUPPRESS a fire the old bare match would have made — that is the whole point —
+but the risk is suppressing a GENUINE error (under-fire). Mitigated: (a) the two-tier begins-with
+grammar fires on real Claude render forms (`⏺ API Error:` / `  ⎿  API Error:`), pinned by tests using
+the actual captured fixtures; (b) the 45-row capture clears the input-box chrome that pushes the
+error up; (c) the 20-line non-empty tail clears realistic chrome with margin; (d) a missed error
+falls through to the pre-existing 15m idle-kill (slower recovery, never silent loss); (e) the
+`result:'suppressed'` structured record makes a wave of real misses observable.
+
+## 2. Under-block (what failure modes does it still miss?)
+- A genuine Claude error rendered in a form that is neither `API Error:`-led nor a glyph-led
+  begins-with-pattern line (unknown future render) → missed → 15m idle-kill fallback. The drift
+  test fails loudly if the known render fixtures stop matching.
+- A residual false-POSITIVE (accepted): a tool result rendered glyph-led whose line begins with a
+  terminal token (e.g. `⎿ fetch failed`) fires. Bounded: the actuator is non-destructive (one wasted
+  nudge the verify step proves a no-op). Documented in the spec §5.
+
+## 3. Level-of-abstraction fit
+Correct layer: this is a deterministic SIGNAL-emitter (Signal vs Authority), feeding the existing
+`apiErrorAtIdle` → `rateLimitSentinel` recovery actuator. It gains no blocking authority. The shared
+`paneTail` helper is the right home for the tail-gating logic (was being copied per consumer). The
+recovery actuator it feeds is honestly named a deterministic Tier-0 non-destructive self-heal (nudge
+→ verify → escalate-to-notice + zombie-kill veto; no respawn).
+
+## 4. Signal vs authority compliance
+Compliant. The classifier returns a boolean SIGNAL; the actuator decides and verifies before any
+action. The match set is a strict subset of the old buffer-wide match (tail + frame ⊂ buffer-wide),
+so the change is monotonic-suppressing — it can only reduce spurious actuations, never add one.
+
+## 5. Interactions
+- The `detectRateLimited` branch runs FIRST and is untouched — a server throttle still routes to
+  `rateLimitedAtIdle` and never reaches the classifier (pinned by the wiring test's intent; the
+  branch order is preserved). The wider 45-row capture is a no-op for `detectRateLimited` (it slices
+  its own last ~20 lines).
+- `errorNudgedSessions` (the nudge episode guard) is unchanged; the new `idleErrorClassified` set
+  mirrors its full lifecycle (armed once/episode; cleared in BOTH the re-arm block AND
+  `sessionComplete` — no leak on the session-death path).
+- `StuckSignatureClassifier` migrates to the shared `liveTail` via `.join('\n')` — behavior-preserving
+  (its existing 13-test corpus passes unchanged = the characterization guard).
+
+## 6. External surfaces
+None new. No HTTP route, no config, no agent-installed file, no user-facing message. The only new
+output is structured `console.log` records to `logs/server.log` (operator log), once per idle episode,
+credential-free (matchedPattern is a fixed token; no raw pane content is logged).
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+Machine-local BY DESIGN. The classifier reads one local tmux pane on the host running the session —
+no cross-machine state, no generated URL, no replicated surface. The downstream `rateLimitSentinel`
+has a Telegram-notify surface, but the change is monotonic-suppressing, so it can only REDUCE
+user-facing cross-machine notices, never add one. Correct posture, declared explicitly.
+
+## 8. Rollback cost
+Single-commit revert: restore the bare `.some(includes)` gate + the 30-row capture, delete
+`IdleErrorClassifier.ts` + `paneTail.ts` + tests + the `idleErrorClassified` field/clears + the
+structured record, and revert the `StuckSignatureClassifier` import (behavior-preserving, mechanical).
+No migration, no durable state, no config. The revert IS the immediate operator action if a future
+Claude render change is ever suspected of under-firing.