@dmsdc-ai/aigentry-telepty 0.1.97 → 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.97",
+  "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/codex-inject-spec.md

@@ -0,0 +1,201 @@
+# SPEC: Codex inject reliability — 4 issues
+
+**Bug source:** orchestrator inject e9f41301...
+**Session:** aigentry-telepty
+**Status:** SPEC — awaiting orchestrator approval
+
+---
+
+## Goal
+
+Make `telepty inject` work reliably with codex sessions. Currently 4 failure
+modes: Enter not pressed, active work overwrite, REPORT not sent, multi-task
+partial processing.
+
+---
+
+## Root Cause Analysis
+
+### Issue 1: inject succeeds but Enter NOT pressed
+
+**Flow:** daemon `deliverInjectionToSession()` → mailbox → `tick()` →
+`writeDataToSession()` sends text via WS → allow-bridge → `child.write(text)`.
+Then 500ms later, `writeDataToSession(id, session, '\r')` → WS → allow-bridge →
+`child.write('\r')`.
+
+**Root cause:** codex CLI puts terminal in raw mode with custom input handling.
+PTY-level `\r` via `child.write('\r')` is NOT equivalent to pressing Enter in
+codex's input model. codex reads PTY input character by character in raw mode
+and interprets `\r` differently than a keyboard Enter event.
+
+**Evidence:** Project memory: "PTY `\r` 직접 의존 금지" — don't depend on PTY
+`\r` directly. "inject submit은 항상 osascript/kitty terminal-level submit 우선".
+
+The `--submit` flag exists in CLI but POST /submit also uses `submitViaPty()` →
+same `\r` via WS. It does NOT use terminal-level submit (kitty/cmux).
+
+### Issue 2: New inject overwrites active work
+
+**Flow:** `deliverInjectionToSession()` enqueues to mailbox and calls
+`mailboxDelivery.tick()` immediately. Text goes via WS → allow-bridge.
+
+Allow-bridge has queuing: if `isIdle()` is false, text goes to
+`enqueueBridgeMessage()`. The safety timer flushes after 5s regardless. But the
+daemon doesn't check session state — it pushes immediately.
+
+**Root cause:** Two layers of the problem:
+1. Daemon sends inject regardless of session state (working/thinking/idle)
+2. Allow-bridge 5s safety flush writes queued text to PTY even if session is
+   still working, which interrupts codex's current task
+
+### Issue 3: REPORT not sent after completion
+
+**Flow:** Auto-report mechanism (`pendingReports`) triggers when allow-bridge
+sends `{ type: 'ready' }` WS message. The `ready` signal fires when
+`promptPattern.test(data)` matches in the PTY output.
+
+**Root cause:** codex prompt pattern `codex: /[❯>]\s*$/` doesn't reliably match
+codex's actual prompt output. If prompt is never detected → `ready` never sent →
+`pendingReports` never cleared → auto-report never fires.
+
+The new session state machine (#185) detects `idle` via OSC 133 + silence
+timeout, but auto-report still uses the legacy `ready` WS signal (daemon.js
+line 2290-2315), not the `session_auto_state` transitions.
+
+### Issue 4: Multiple tasks in one inject — partial processing
+
+**Root cause:** AI behavior, not telepty bug. When a --ref file contains Task A
++ Task B, codex processes Task A and returns to prompt. This is standard LLM
+behavior — no telepty fix needed.
+
+**Mitigation:** Orchestrator should split multi-task injects into separate
+sequential calls with idle-gating between them (orchestrator-side logic).
+
+---
+
+## Scope
+
+**Phase 1 (this spec):** Fix Issues 1 and 3 (guaranteed Enter + guaranteed
+REPORT). These are telepty-side fixes.
+
+**Phase 2 (separate task):** Fix Issue 2 (inject queuing during active work).
+Requires daemon-side session state awareness.
+
+**Out of scope:** Issue 4 (orchestrator-level task splitting).
+
+---
+
+## Files to Modify
+
+| File | Change |
+|---|---|
+| `daemon.js` | Fix 1: `deliverInjectionToSession()` — use `sendViaKitty()` for CR instead of PTY `\r`. Fix 3: Wire auto-report to session state `idle` transition instead of legacy `ready` signal. |
+| `daemon.js` | Fix 1: POST `/submit` endpoint — use kitty send-text with cmux fallback instead of `submitViaPty()`. |
+
+---
+
+## Approach
+
+### Fix 1: Terminal-level submit for wrapped sessions
+
+Replace PTY `\r` with `sendViaKitty()` in `deliverInjectionToSession()`:
+
+```js
+// BEFORE (daemon.js ~line 590):
+if (!options.noEnter && session.type !== 'aterm') {
+  const submitDelay = session.type === 'wrapped' ? 500 : 300;
+  setTimeout(async () => {
+    const submitResult = await writeDataToSession(id, session, '\r');
+    // ...
+  }, submitDelay);
+}
+
+// AFTER:
+if (!options.noEnter && session.type !== 'aterm') {
+  const submitDelay = session.type === 'wrapped' ? 500 : 300;
+  setTimeout(async () => {
+    let submitted = false;
+    // Priority 1: kitty send-text (terminal-level, bypasses PTY quirks)
+    if (session.type === 'wrapped') {
+      submitted = sendViaKitty(id, '\r');
+    }
+    // Priority 2: cmux send-key (for cmux-managed sessions)
+    if (!submitted && session.backend === 'cmux' && session.cmuxWorkspaceId) {
+      submitted = submitViaCmux(id);
+    }
+    // Priority 3: PTY fallback (spawned sessions without kitty)
+    if (!submitted) {
+      const submitResult = await writeDataToSession(id, session, '\r');
+      if (!submitResult.success) {
+        emitInjectFailureEvent(id, submitResult.code, submitResult.error, {
+          phase: 'submit', source: options.source || 'inject'
+        }, session);
+      }
+    }
+  }, submitDelay);
+}
+```
+
+Also update POST `/submit` endpoint to use same priority chain instead of
+always calling `submitViaPty()`.
+
+### Fix 3: Auto-report via session state machine
+
+Wire auto-report to the `session_auto_state` transition event (already emitted
+by `sessionStateManager.onTransition()`). When a session transitions to `idle`
+and has a pending report, fire the auto-report.
+
+```js
+// In the existing sessionStateManager.onTransition callback (daemon.js ~line 37):
+sessionStateManager.onTransition((sessionId, from, to, detail) => {
+  const session = sessions[sessionId];
+  if (!session) return;
+  broadcastSessionEvent('session_auto_state', sessionId, session, {
+    extra: { auto_state: to, auto_state_from: from, auto_detail: detail }
+  });
+
+  // Auto-report: fire when session transitions to idle after inject
+  if (to === 'idle' && pendingReports[sessionId]) {
+    const pendingReport = pendingReports[sessionId];
+    delete pendingReports[sessionId];
+    const elapsed = ((Date.now() - new Date(pendingReport.injectedAt).getTime()) / 1000).toFixed(1);
+    const reportMsg = `TASK_COMPLETE: ${sessionId} is now idle after processing inject (${elapsed}s)`;
+    const srcId = resolveSessionAlias(pendingReport.source) || pendingReport.source;
+    const srcSession = sessions[srcId];
+    if (srcSession) {
+      deliverInjectionToSession(srcId, srcSession, reportMsg, { noEnter: false, source: 'auto_report' });
+      console.log(`[AUTO-REPORT] ${sessionId} → ${srcId}: idle after ${elapsed}s`);
+    }
+  }
+});
+```
+
+Keep the legacy `ready`-based auto-report as fallback (don't remove it).
+
+---
+
+## Verification
+
+1. **Test:** `telepty inject xtem-rtm "echo hello"` → codex processes it
+   (Enter pressed via kitty send-text)
+2. **Test:** `telepty inject --ref --from orchestrator xtem-rtm 'task'` → after
+   codex completes → auto-report fires via idle state transition
+3. **Test:** Sessions without kitty (spawned) → PTY `\r` fallback still works
+4. **Test:** Existing 131 tests still pass
+
+---
+
+## Risks
+
+1. **kitty not available.** Mitigated: 3-tier fallback (kitty → cmux → PTY).
+   PTY path preserved as last resort.
+2. **`sendViaKitty()` needs kitty socket + window ID match.** Already
+   implemented and working for other features. If kitty window not found,
+   falls through to PTY.
+3. **Auto-report via state machine may fire too early.** The idle detection
+   uses 5s silence timeout. If codex pauses >5s mid-task, it may fire
+   prematurely. Mitigated: auto-report has `AUTO_REPORT_IDLE_SECONDS` (10s)
+   threshold. Can add a minimum elapsed time guard.
+4. **Dual auto-report paths (state machine + legacy ready).** Could fire
+   twice. Mitigated: `delete pendingReports[sessionId]` in both paths —
+   whichever fires first consumes the pending report.

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