@dmsdc-ai/aigentry-telepty 0.1.98 → 0.3.3

package/docs/superpowers/specs/2026-05-02-submit-force-and-retry.md

@@ -0,0 +1,139 @@
+# 2026-05-02 — `inject --submit-force` + idempotent client retry
+
+Closes task #347 (telepty 0.3.2 `--submit` prompt-symbol gate reliability —
+context-ref inject arrived at orchestrator but Enter was skipped when the
+input area had a transient render mismatch: autocomplete dropdown open,
+cursor moved, mid-render race).
+
+## Problem
+
+`telepty inject --submit` runs three layers of gating before pressing
+Enter:
+
+| Layer | File | Trigger | Skip behavior |
+|---|---|---|---|
+| 3. Prompt-symbol (0.3.2) | `src/submit-gate.js` `awaitPromptSymbol` | `cmux read-screen` does not show the per-CLI prompt symbol stably for ≥200 ms within 8 s | Falls through to Layer 1 (`no_prompt_symbol_seen`) |
+| 1. State-gated (0.3.1) | `src/submit-gate.js` `awaitReplReady` | `sessionStateManager` is not in `idle`/`waiting` with conf ≥ 0.5 within 10 s | Best-effort dispatch on `timeout`; hard-fail short-circuits to 504 on `session_dead`/`error`/`restarting`/`no_state` |
+| Verify | `src/submit-gate.js` `verifyBodyConsumed` | Injected body still visible in `outputRing` after dispatch | One bounded retry; if still visible, 504 with `reason: 'gated_dispatch_unconsumed'` |
+
+In production this still produces a residual failure rate when the
+orchestrator session has a transient render mismatch (autocomplete drop-down,
+cursor outside input area, mid-paste). The body is injected, the gate times
+out, the dispatch fires Enter into a "wrong" focus, and `verifyBodyConsumed`
+correctly sees the body still in the input box → 504. Sub-sessions then
+print `⚠️ Submit gated-timeout` and the human user has to press Enter
+manually for the orchestrator to consume the inject.
+
+## Constraints
+
+- **Article 1 (경량)**: minimum-touch fix. No new modules, no new daemon
+  endpoint, no new helper module.
+- **Article 17 (무의존)**: no new runtime dependency.
+- **Article 9 (독립)**: telepty must keep working standalone (no cmux/kitty
+  required for the new flags).
+- **Backward compat**: existing `--submit` semantics unchanged. Default
+  `--submit-retry` value MUST be 0-effect on the happy path (which is the
+  vast majority of calls, currently shipping reliably).
+- **Idempotency**: a retry must never double-press Enter.
+
+## Approach
+
+Two opt-in CLI knobs on `telepty inject`, both implemented client-side
+in `cli.js`. Daemon `/submit` endpoint is untouched — `force: true` is
+already supported (introduced in 0.3.1 for `telepty send-key`); we just
+plumb it through from the inject path.
+
+### `--submit-force`
+
+Adds `force: true` to the `/submit` POST body. Daemon-side this skips
+both Layer 3 (prompt-symbol) and Layer 1 (state-gate) and dispatches Enter
+once via the existing `terminalLevelSubmit` chain (kitty → cmux → PTY).
+
+Use case: caller is confident the target REPL is ready (e.g., orchestrator
+visibly idle, or Phase-6 cascade where sub-session has just verified the
+orchestrator's last bus event). Mirrors the existing `telepty send-key`
+escape hatch but at the inject level so a single command does both.
+
+### `--submit-retry N` (default 1, clamp [0, 3])
+
+After a 504 from `/submit` with a **retry-safe** reason, wait 300 ms and
+re-issue the same `/submit` request up to N times. Retry-safe reasons:
+
+| Reason | Source | Why retry is idempotent |
+|---|---|---|
+| `gated_dispatch_unconsumed` | `daemon.js:1680` | The verify path saw the body STILL in the input box after best-effort dispatch. Re-firing Enter when the body is visibly un-consumed cannot double-submit. |
+| `gate_timeout` | `awaitReplReady` returning `timeout` (no longer reaches 504 directly in 0.3.1, but kept for forward-compat) | Same: body has not been consumed if we're still on the gated path. |
+| `no_prompt_symbol_seen` | `awaitPromptSymbol` Layer 3 timeout (also not currently a 504 source, but kept for forward-compat) | Layer 3 alone never emits 504 today. Listed for completeness. |
+
+Retry is **explicitly NOT** safe for hard-fail reasons — `session_dead`,
+`session_error`, `session_restarting`, `no_state`, `no_state_manager`. Those
+short-circuit the loop immediately because re-firing won't recover. Same
+for any non-504 status (4xx) — no point retrying a malformed request.
+
+The retry preserves the original flag set (`force` stays `force`, etc.).
+The `attemptsMade` counter is rendered into the success line as
+`[retry K/N]` so operators can see when the retry path actually fired.
+
+### Why client-side (not daemon-side)?
+
+- Server-side already retries once internally inside `verifyBodyConsumed`
+  (`daemon.js:1663-1672`). Adding a second loop server-side conflates two
+  feedback signals (the inner verify retry vs. the outer client retry) in
+  one response shape.
+- Per-call client control is more flexible — sub-sessions that have
+  cheap evidence of orchestrator readiness can pass `--submit-retry 0`
+  to avoid the extra round-trip; ones that don't can pass `--submit-retry 2`.
+- Keeps the daemon stable. 0.3.0 cluster (memory:
+  `feedback_telepty_send_key_regression.md`) was a daemon-side change that
+  rippled into manual-override breakage. Client-side change has a strictly
+  smaller blast radius.
+
+## File map
+
+| File | Change | LoC delta |
+|---|---|---|
+| `cli.js` (inject command) | Parse `--submit-force` + `--submit-retry`. Wrap existing `useSubmit` block in idempotent retry loop on 504-with-safe-reason. | +~55, -~25 |
+| `test/cli.test.js` | Three new tests: --submit-force passes force=true; --submit-retry retries on safe-reason 504; --submit-retry does NOT retry on hard-fail 504. | +~120 |
+| `CHANGELOG.md` | 0.3.3 entry. | +~30 |
+| `package.json` | 0.3.2 → 0.3.3. | +1, -1 |
+| `test/enforce-report.test.js:280` | Update stale version assertion 0.2.0 → 0.3.3. | +1, -1 |
+| `README.md` | Mention new flags in inject summary. | +~6 |
+
+No new files outside `test/` and `docs/`. No daemon changes. No new
+dependencies. Total surface ≪ 200 LoC including tests.
+
+## Tests
+
+### Unit / integration (`test/cli.test.js`)
+
+1. **`--submit-force` passes `force: true` to /submit**
+   Spawn a session, intercept `/submit` (use existing harness method or
+   inspect bus event), invoke `telepty inject --submit --submit-force <id>
+   "x"`, assert daemon received `{ force: true }` in the request body.
+
+2. **`--submit-retry N` retries on safe-reason 504**
+   Mock the daemon to return 504 `{reason: 'gated_dispatch_unconsumed'}`
+   on the first call and 200 on the second. Assert the CLI made exactly
+   2 POST /submit calls and exited 0. Assert `[retry 1/N]` is present
+   in stdout.
+
+3. **`--submit-retry N` does NOT retry on hard-fail 504**
+   Mock the daemon to return 504 `{reason: 'session_dead'}`. Assert the
+   CLI made exactly 1 POST /submit call (no retry).
+
+### Regression — full suite
+
+`npm test` — 229 tests, all should pass after updating the stale
+`enforce-report.test.js:280` version assertion.
+
+## Future-proofing notes
+
+- If the daemon adds new 504 reasons, they are by default **NOT** retry-
+  safe (the safe set is an explicit allowlist). Adding a new safe reason
+  is a one-line `RETRY_SAFE_REASONS.add(...)` change in `cli.js`.
+- The flag pair composes: `--submit-force --submit-retry 0` (force-once),
+  `--submit-force --submit-retry 2` (force, with idempotent retry on the
+  rare 503 — though force never returns 504 today).
+- The 300 ms retry delay is a constant, not a flag, to keep the surface
+  small. Empirically chosen at the upper end of the architect's
+  100–300 ms window for the autocomplete-dropdown-close case.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dmsdc-ai/aigentry-telepty",
-  "version": "0.1.98",
+  "version": "0.3.3",
   "main": "daemon.js",
   "bin": {
     "aigentry-telepty": "install.js",
@@ -9,9 +9,9 @@
     "telepty-mcp": "mcp-server/index.mjs"
   },
   "scripts": {
-    "test": "node --test test/auth.test.js test/daemon.test.js test/daemon-singleton.test.js test/cli.test.js test/skill-installer.test.js test/interactive-terminal.test.js test/runtime-info.test.js test/session-routing.test.js test/session-state.test.js test/mailbox-lock.test.js",
-    "test:watch": "node --test --watch test/auth.test.js test/daemon.test.js test/daemon-singleton.test.js test/cli.test.js test/skill-installer.test.js test/interactive-terminal.test.js test/runtime-info.test.js test/session-routing.test.js test/session-state.test.js test/mailbox-lock.test.js",
-    "test:ci": "node --test --test-reporter=spec test/auth.test.js test/daemon.test.js test/daemon-singleton.test.js test/cli.test.js test/skill-installer.test.js test/interactive-terminal.test.js test/runtime-info.test.js test/session-routing.test.js test/session-state.test.js test/mailbox-lock.test.js"
+    "test": "node --test test/auth.test.js test/daemon.test.js test/daemon-singleton.test.js test/cli.test.js test/skill-installer.test.js test/interactive-terminal.test.js test/runtime-info.test.js test/session-routing.test.js test/session-state.test.js test/mailbox-lock.test.js test/report-enforcement.test.js test/enforce-report.test.js test/submit-gate.test.js test/prompt-symbol-registry.test.js test/inject-submit-flags.test.js",
+    "test:watch": "node --test --watch test/auth.test.js test/daemon.test.js test/daemon-singleton.test.js test/cli.test.js test/skill-installer.test.js test/interactive-terminal.test.js test/runtime-info.test.js test/session-routing.test.js test/session-state.test.js test/mailbox-lock.test.js test/report-enforcement.test.js test/enforce-report.test.js test/submit-gate.test.js test/prompt-symbol-registry.test.js test/inject-submit-flags.test.js",
+    "test:ci": "node --test --test-reporter=spec test/auth.test.js test/daemon.test.js test/daemon-singleton.test.js test/cli.test.js test/skill-installer.test.js test/interactive-terminal.test.js test/runtime-info.test.js test/session-routing.test.js test/session-state.test.js test/mailbox-lock.test.js test/report-enforcement.test.js test/enforce-report.test.js test/submit-gate.test.js test/prompt-symbol-registry.test.js test/inject-submit-flags.test.js"
   },
   "keywords": [
     "pty",

package/specs/enforce-report-spec.md

@@ -0,0 +1,237 @@
+# SPEC: Enforce result-summary REPORT when sessions go idle
+
+**Source:** orchestrator inject d94c9990...
+**Session:** aigentry-telepty
+**Status:** SPEC — awaiting orchestrator approval
+**Topic:** REPORT enforcement after inject-driven idle transitions
+
+---
+
+## 1. Design options & recommendation
+
+### Option A — Gate idle transition until REPORT arrives
+Prevent `idle` transition from firing for N seconds until content REPORT
+detected as sent by the session.
+
+- ❌ Violates invariant: "Do NOT break existing idle detection"
+- ❌ Requires invasive state machine changes
+- **Rejected.**
+
+### Option B — Auto-summarize PTY output
+Scrape last X lines of session PTY output, strip ANSI, attach as
+`auto_summary` field on `TASK_COMPLETE`.
+
+- ✅ Zero session-side changes
+- ✅ Always provides content payload
+- ❌ PTY scraping is noisy (progress bars, status lines, spinner remnants)
+- ❌ Masks the root cause — sessions still forget to REPORT
+- **Keep as fallback, not primary.**
+
+### Option C — Two-stage notification
+On idle transition, fire `TASK_IDLE_NO_REPORT` (not `TASK_COMPLETE`).
+Watch for content REPORT inject BACK to the source session for N seconds.
+If REPORT detected → emit `TASK_COMPLETE_WITH_REPORT`. Else → emit
+`TASK_TIMEOUT_NO_REPORT` with `auto_summary` fallback (Option B).
+
+- ✅ Observable from orchestrator without code changes (richer events)
+- ✅ Doesn't break existing idle detection (fires AFTER idle transition)
+- ✅ No session-side changes required
+- ✅ Backward-compat (old consumers see bus event, just with new `type`)
+- ✅ Provides clear state difference between "REPORTed" and "idled silently"
+- **Recommended primary.**
+
+### Option D — Prompt-injection reminder
+When session about to go idle after inject, auto-inject reminder text.
+
+- ❌ Interferes with active work
+- ❌ Doesn't guarantee compliance
+- ❌ Session might be in final cleanup — inject causes confusion
+- **Rejected.**
+
+### Recommendation: **Option C + Option B fallback**
+
+Two-stage notification with PTY-scrape auto-summary as timeout fallback.
+Minimal blast radius, maximal observability, preserves all invariants.
+
+---
+
+## 2. Content REPORT schema
+
+Parse from inject body text via prefix. Structured envelope would require
+session-side library; free-text prefix keeps all LLMs compatible.
+
+**Detection rule:** An inject from session X BACK to session Y (where Y was
+the original `--from` source for X's last inject) whose prompt text starts
+with one of:
+- `REPORT:` (completed / partial result)
+- `STATUS:` (blocked / dismissed / error)
+- `ENFORCE-SPEC:`, `SPEC:`, `OWNER-DIAGNOSIS:` — recognized REPORT variants
+
+Required fields (parsed from pipe-separated text):
+- `source_session` — auto (sender of the reply inject)
+- `target_session` — auto (recipient, i.e. the original orchestrator)
+- `inject_ref` — auto (matched via pendingReports tracking)
+- `status` — parsed from prefix: `REPORT:` → completed; `STATUS: blocked` → blocked; etc.
+- `summary` — the full prompt text (20-500 chars recommended, not enforced)
+- `artifacts` — optional, parsed from `files={...}` pipe-field
+- `next_action` — optional, parsed from `next={...}` pipe-field
+
+**Non-breaking:** If the reply inject doesn't match any REPORT prefix, it's
+treated as a regular inject (current behavior preserved).
+
+---
+
+## 3. Timeout + failure handling
+
+| Condition | Action | Notification |
+|---|---|---|
+| REPORT arrives within `reportTimeoutSecs` (default 120s) | Cancel timer, mark as reported | `TASK_COMPLETE_WITH_REPORT` (rich payload) |
+| No REPORT within `reportTimeoutSecs` | Fire timeout | `TASK_TIMEOUT_NO_REPORT` with `auto_summary` (last 40 non-blank stripAnsi lines from `session.outputRing`) |
+| Session sends `STATUS: blocked` explicitly | Immediate settlement | `TASK_BLOCKED_WITH_REASON` |
+| Session dies before REPORT | Detected via `dead` transition | `TASK_DEAD_NO_REPORT` with `auto_summary` |
+
+**Interaction with existing 60s deliberation timeout:** Orthogonal. Deliberation
+timeout is a separate orchestrator-level concept. This daemon-level REPORT
+timeout fires AFTER idle but BEFORE any orchestrator follow-up. Default 120s
+gives orchestrator time to see `TASK_IDLE_NO_REPORT` and follow up before
+auto-summary fires.
+
+---
+
+## 4. Back-compat
+
+- Legacy `TASK_COMPLETE: {session} is now idle after processing inject ({N}s)`
+  text format: **deprecated but kept emitting** for 1 minor version. Emit BOTH
+  the new `TASK_IDLE_NO_REPORT` bus event AND the legacy text-inject-to-source
+  during transition period.
+- New bus event types: `TASK_IDLE_NO_REPORT`, `TASK_COMPLETE_WITH_REPORT`,
+  `TASK_TIMEOUT_NO_REPORT`, `TASK_BLOCKED_WITH_REASON`, `TASK_DEAD_NO_REPORT`.
+- Sessions that never send REPORT: grandfathered — they get
+  `TASK_TIMEOUT_NO_REPORT` with auto-summary fallback (no hard failure).
+- Orchestrator code that parses legacy `TASK_COMPLETE: ...` text: still works
+  (text still emitted during transition).
+
+---
+
+## 5. Scope boundaries
+
+| Work source | Require REPORT? | How distinguished |
+|---|---|---|
+| Inject with `--from X` | ✅ Yes (track in `pendingReports[sessionId]`) | `pendingReports` map populated on inject |
+| Inject without `--from` | ❌ No (no one to report to) | `pendingReports` key absent |
+| User typed directly | ❌ No | No inject event, no pendingReport entry |
+| Self-initiated REPORT inject | ❌ No (it IS the report) | prefix match: `REPORT:` etc. |
+
+**Key rule:** Only sessions with a `pendingReports[id]` entry are subject to
+enforcement. User-driven work naturally doesn't populate this map.
+
+---
+
+## 6. Files to modify
+
+| File | Change |
+|---|---|
+| `daemon.js` — sessionStateManager.onTransition (lines 37-57) | Replace direct auto-report with two-stage notification. Fire `TASK_IDLE_NO_REPORT`, start REPORT watch timer. |
+| `daemon.js` — inject endpoint (lines 1547-1550) | Extend `pendingReports[id]` with `awaitingReport: true`, `reportWatchUntil: ts`. |
+| `daemon.js` — inject endpoint (new detection) | Check incoming inject prompt for REPORT prefix + reverse-match to originating pendingReport. If matched: cancel timer, fire `TASK_COMPLETE_WITH_REPORT`. |
+| `daemon.js` — state machine `dead` transition handler | Fire `TASK_DEAD_NO_REPORT` with auto-summary. |
+| `daemon.js` — new helper `buildAutoSummary(session)` | Read `session.outputRing`, strip ANSI, filter blanks, take last 40 lines, max 4KB. |
+| `src/mailbox/config.js` or similar config | Add `reportTimeoutSecs: 120`, `autoSummaryLines: 40`, `autoSummaryMaxBytes: 4096`. |
+| `daemon.js` — legacy auto-report removal (lines 2131-2147, 2328-2346) | Retire duplicate legacy paths (or keep with deprecation flag). |
+| `test/daemon.test.js` | New tests: REPORT-detected path, timeout path, dead-before-report path, no-inject-source ignored path. |
+
+No new files. No new ports. No new process spawning.
+
+---
+
+## 7. Test plan
+
+**Unit tests (test/daemon.test.js additions):**
+1. Idle after inject → emits `TASK_IDLE_NO_REPORT` bus event (NOT `TASK_COMPLETE`)
+2. REPORT-prefixed inject reply within timeout → emits `TASK_COMPLETE_WITH_REPORT` with parsed fields
+3. No REPORT within timeout → emits `TASK_TIMEOUT_NO_REPORT` with auto_summary containing last session output
+4. `STATUS: blocked` reply → immediate `TASK_BLOCKED_WITH_REASON`
+5. Session dies before report → `TASK_DEAD_NO_REPORT` with auto_summary
+6. Idle WITHOUT pendingReports entry (user-driven work) → no enforcement events
+7. `buildAutoSummary()`: strips ANSI, drops blanks, truncates to 40 lines / 4KB
+8. Legacy text-inject to source still fires (back-compat grandfathering)
+
+**E2E tests:**
+1. Full cycle: `inject --from A B "task"` → B works → B sends `telepty inject --from B A "REPORT: ..."` → A receives REPORT → bus emits `TASK_COMPLETE_WITH_REPORT`
+2. Timeout cycle: same but B never replies → after 120s → A receives `TASK_TIMEOUT_NO_REPORT` with auto_summary
+
+**Regression:**
+- All 131 existing tests pass unchanged
+- Existing `TASK_COMPLETE:` text format still emitted (grandfather)
+
+---
+
+## 8. Semver
+
+**Minor bump → 0.2.0.**
+
+Justification:
+- New bus event types (additive, not breaking)
+- New config keys (additive with defaults)
+- Legacy notification text preserved (back-compat)
+- No breaking API changes
+- Observable new behavior that consumers may opt into
+
+Not a patch because it introduces new observable event types.
+Not major because nothing is removed or renamed.
+
+---
+
+## 9. Risks — top 3
+
+1. **REPORT detection false positives** — an inject back to source that
+   happens to start with "REPORT:" but is actually a new task request gets
+   miscategorized. Mitigation: REPORT detection requires BOTH prefix match
+   AND reverse-match to `pendingReports[senderSession]` with matching
+   `inject_ref`. If no pending outbound report tracked, treat as new inject.
+2. **Auto-summary leaks sensitive output** — PTY output may contain secrets
+   (tokens, passwords echoed). Mitigation: honor a denylist regex
+   (`api[_-]?key|password|token=\\S+`) before attaching; truncate aggressive.
+   Document that auto_summary is best-effort preview, not full transcript.
+3. **Timeout storm on orchestrator** — if many sessions timeout simultaneously,
+   orchestrator receives a flurry of `TASK_TIMEOUT_NO_REPORT` events.
+   Mitigation: rate-limit timeout emissions per-orchestrator via mailbox
+   coalescing (existing `notifyCoalesceMs`).
+
+---
+
+## 10. Open questions
+
+1. **Should `TASK_IDLE_NO_REPORT` be delivered as an inject (legacy) or ONLY
+   as a bus event?** Recommendation: bus event only during transition — legacy
+   text-inject preserved unchanged. Rich event flows via bus where consumers
+   can subscribe.
+2. **Cross-machine:** Does the REPORT watch timer survive tailnet peer relay?
+   Current `pendingReports` is in-memory on the daemon handling the inject.
+   If orchestrator is on a different machine, does the remote peer also track?
+   Recommendation: timer stays on the daemon that accepted the original
+   inject; remote orchestrator gets events via existing bus relay. No
+   cross-machine state sync needed.
+3. **Should `dismissed` be session-initiated or orchestrator-initiated?**
+   Proposed: session sends `STATUS: dismissed` (I decided not to do this);
+   orchestrator can also mark via `DELETE /api/pendingReports/{id}`
+   (new endpoint). Both clear the watch.
+4. **Two injects in quick succession from same orchestrator:** First inject
+   creates pendingReport; second inject arrives before REPORT for first.
+   Does second inject overwrite or queue? Recommendation: overwrite (only
+   latest inject expects REPORT). Log `[AUTO-REPORT] overwritten pending`
+   warning for observability.
+5. **reportTimeoutSecs default (120s):** Is this the right baseline? Evidence
+   table shows tasks ranging 7.5s → 649s. 120s too short for long tasks.
+   Alternative: no default timer — only fire fallback when `dead` detected
+   or explicit orchestrator-side query. Needs orchestrator input.
+
+---
+
+## Invariants honored
+
+- ✅ Existing idle detection unchanged (state machine onTransition fires as before)
+- ✅ Orchestrator needs no code changes to benefit (bus events flow passively)
+- ✅ No new process spawning / no new network ports
+- ✅ Cross-machine sync via existing mailbox unchanged
+- ✅ Scoped to REPORT enforcement — no inject rewrite

package/src/prompt-symbol-registry.js

@@ -0,0 +1,97 @@
+// src/prompt-symbol-registry.js — Per-CLI prompt-symbol detection (0.3.2)
+// See docs/superpowers/specs/2026-04-26-prompt-symbol-render-gate.md
+//
+// Maps `session.command` (e.g. 'claude', 'codex', 'gemini') to a
+//   { symbol, byteSeq, detect(screen) → { found, line_index?, col? } }
+// entry. The detect() function takes the rendered screen text from
+// `cmux read-screen` (already terminal-state-applied; no ANSI stripping
+// needed) and returns the LAST occurrence (closest to the bottom) so
+// transcript echoes earlier in the viewport do not produce false positives.
+//
+// Adding a new CLI: append a new entry + write a unit test against a
+// captured `cmux read-screen` sample.
+
+'use strict';
+
+const ENTRIES = {
+  // claude renders an empty input row as "❯" + spaces, sandwiched between
+  // two horizontal-rule lines made of U+2500 ('─').
+  claude: {
+    symbol: '❯',
+    byteSeq: Buffer.from([0xE2, 0x9D, 0xAF]),
+    detect(screen) {
+      const lines = String(screen == null ? '' : screen).split('\n');
+      for (let i = lines.length - 1; i >= 1; i--) {
+        const line = lines[i];
+        if (!/^❯\s*$/.test(line)) continue;
+        const above = lines[i - 1] || '';
+        const below = lines[i + 1] || '';
+        if (above.includes('─') || below.includes('─')) {
+          return { found: true, line_index: i, col: line.indexOf('❯') + 1 };
+        }
+      }
+      return { found: false };
+    },
+  },
+  // codex renders idle as " › <placeholder>" (column 2). Status footer
+  // ("gpt-5.5 …" or "gpt-5 …") sits 1–2 lines below.
+  codex: {
+    symbol: '›',
+    byteSeq: Buffer.from([0xE2, 0x80, 0xBA]),
+    detect(screen) {
+      const lines = String(screen == null ? '' : screen).split('\n');
+      for (let i = lines.length - 1; i >= 0; i--) {
+        const line = lines[i];
+        if (!/^ › /.test(line)) continue;
+        const footer = (lines[i + 1] || '') + '\n' + (lines[i + 2] || '');
+        if (/gpt-\d/.test(footer)) {
+          return { found: true, line_index: i, col: 2 };
+        }
+      }
+      return { found: false };
+    },
+  },
+  // gemini empty input: " *   Type your message or @path/to/file"
+  // gemini non-empty: " *   <user typed text>"
+  // Geometry: bracketed by U+2580 ('▀') above and U+2584 ('▄') below.
+  gemini: {
+    symbol: '*',
+    byteSeq: Buffer.from([0x2A]),
+    detect(screen) {
+      const lines = String(screen == null ? '' : screen).split('\n');
+      for (let i = lines.length - 1; i >= 1; i--) {
+        const line = lines[i];
+        if (!/^ \* {2,}/.test(line)) continue;
+        const above = lines[i - 1] || '';
+        const below = lines[i + 1] || '';
+        if (above.includes('▀') || below.includes('▄')) {
+          return { found: true, line_index: i, col: 2 };
+        }
+      }
+      return { found: false };
+    },
+  },
+};
+
+// Normalize: strip path and args
+//   '/usr/local/bin/claude --resume' → 'claude'
+//   'codex resume'                   → 'resume' (false negative — see note)
+//
+// The naive split/pop returns the LAST whitespace-or-slash-delimited token,
+// which is correct for absolute paths but wrong for `<bin> <subcmd>` forms.
+// We compensate by also trying the FIRST path-stripped token before falling
+// back to the last token, matching whichever ENTRIES key exists.
+function lookup(command) {
+  if (!command) return null;
+  const raw = String(command).trim();
+  if (!raw) return null;
+  const tokens = raw.split(/\s+/).filter(Boolean);
+  for (const tok of tokens) {
+    const base = tok.split('/').filter(Boolean).pop() || '';
+    const key = base.toLowerCase();
+    if (ENTRIES[key]) return ENTRIES[key];
+  }
+  return null;
+}
+
+module.exports = { lookup, ENTRIES };

package/src/report-enforcement.js

@@ -0,0 +1,86 @@
+// src/report-enforcement.js — REPORT enforcement helpers (0.2.0)
+// See specs/enforce-report-spec.md
+//
+// Exports pure, testable helpers:
+//   - classifyReportPrompt(prompt): categorize an inject prompt
+//   - buildAutoSummary(session, opts): scrape last lines of output with redaction
+//   - ANSI_STRIPPER_RE, SECRET_DENYLIST_RE: regex constants (exported for tests)
+//   - REPORT_PREFIX_RE, REPORT_STATUS_*_RE: classification regexes
+
+'use strict';
+
+// Prefix patterns that identify a content REPORT inject (reverse-match required)
+const REPORT_PREFIX_RE = /^\s*(REPORT|STATUS|SPEC|OWNER-DIAGNOSIS|ENFORCE-SPEC|LOG-FIX-SPEC|LOG-FIX-IMPLEMENTED|FIX-SPEC|FIX-IMPLEMENTED|SPEC-SYNC|DIAGNOSIS|ENFORCE-IMPLEMENTED)[:\s]/;
+const REPORT_STATUS_BLOCKED_RE = /^\s*STATUS:\s*blocked\b/i;
+const REPORT_STATUS_DISMISSED_RE = /^\s*STATUS:\s*dismissed\b/i;
+const REPORT_STATUS_ERROR_RE = /^\s*STATUS:\s*error\b/i;
+
+// ANSI stripper (matches session-state.js)
+const ANSI_STRIPPER_RE = /\x1b\[[0-9;]*[a-zA-Z]|\x1b\][^\x07]*\x07|\x1b[()][AB012]|\x1b\[[\?]?[0-9;]*[hlm]/g;
+
+// Secret denylist — redact common credential patterns
+const SECRET_DENYLIST_RE = /(api[_-]?key\s*[:=]\s*\S+|password\s*[:=]\s*\S+|token\s*[:=]\s*\S+|secret\s*[:=]\s*\S+)/gi;
+
+// Default config (overridable via options)
+const DEFAULT_AUTO_SUMMARY_LINES = 40;
+const DEFAULT_AUTO_SUMMARY_MAX_BYTES = 4096;
+
+/**
+ * Classify incoming inject prompt for REPORT enforcement.
+ * Returns one of: 'report_dismissed', 'report_blocked', 'report_error',
+ * 'report_complete', or null (not a report).
+ *
+ * Order matters: STATUS variants checked before generic prefix.
+ */
+function classifyReportPrompt(prompt) {
+  if (typeof prompt !== 'string') return null;
+  if (REPORT_STATUS_DISMISSED_RE.test(prompt)) return 'report_dismissed';
+  if (REPORT_STATUS_BLOCKED_RE.test(prompt)) return 'report_blocked';
+  if (REPORT_STATUS_ERROR_RE.test(prompt)) return 'report_error';
+  if (REPORT_PREFIX_RE.test(prompt)) return 'report_complete';
+  return null;
+}
+
+/**
+ * Build an auto_summary from a session's output ring.
+ * - Strips ANSI sequences
+ * - Filters blank lines
+ * - Takes last N non-blank lines
+ * - Redacts secrets via denylist regex
+ * - Caps at max_bytes total (UTF-8 byte length)
+ *
+ * @param {Object} session — { outputRing: string[] }
+ * @param {Object} [options]
+ * @param {number} [options.maxLines] — default 40
+ * @param {number} [options.maxBytes] — default 4096
+ * @returns {string}
+ */
+function buildAutoSummary(session, options = {}) {
+  const maxLines = options.maxLines || DEFAULT_AUTO_SUMMARY_LINES;
+  const maxBytes = options.maxBytes || DEFAULT_AUTO_SUMMARY_MAX_BYTES;
+  if (!session || !session.outputRing || session.outputRing.length === 0) return '';
+
+  const raw = session.outputRing.join('');
+  const stripped = raw.replace(ANSI_STRIPPER_RE, '');
+  const lines = stripped.split(/\r?\n/).map(l => l.trim()).filter(l => l.length > 0);
+  const tail = lines.slice(-maxLines);
+  let joined = tail.join('\n');
+  joined = joined.replace(SECRET_DENYLIST_RE, '[REDACTED]');
+  if (Buffer.byteLength(joined, 'utf8') > maxBytes) {
+    joined = joined.slice(0, maxBytes);
+  }
+  return joined;
+}
+
+module.exports = {
+  classifyReportPrompt,
+  buildAutoSummary,
+  REPORT_PREFIX_RE,
+  REPORT_STATUS_BLOCKED_RE,
+  REPORT_STATUS_DISMISSED_RE,
+  REPORT_STATUS_ERROR_RE,
+  ANSI_STRIPPER_RE,
+  SECRET_DENYLIST_RE,
+  DEFAULT_AUTO_SUMMARY_LINES,
+  DEFAULT_AUTO_SUMMARY_MAX_BYTES,
+};