@dmsdc-ai/aigentry-telepty 0.1.98 → 0.3.5

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/init/print-snippet.js

@@ -0,0 +1,114 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { createHash } = require('node:crypto');
+
+const VERSION = 'telepty-snippet/v1';
+const TARGETS = ['claude', 'agents', 'gemini'];
+const FORMATS = ['markdown', 'json'];
+const SNIPPET_DIR = path.join(__dirname, 'snippets');
+const HELP = 'usage: telepty init --print-snippet [--target {claude|agents|gemini|all}] [--format {markdown|json}]';
+
+function sha256Hex(body) {
+  return createHash('sha256').update(body, 'utf8').digest('hex');
+}
+
+function loadBody(target, options = {}) {
+  const snippetDir = options.snippetDir || SNIPPET_DIR;
+  return fs.readFileSync(path.join(snippetDir, `${target}.md`), 'utf8');
+}
+
+function expandTargets(target) {
+  return target === 'all' ? TARGETS : [target];
+}
+
+function emitMarkdown(target, body) {
+  const sha8 = sha256Hex(body).slice(0, 8);
+  return `<!-- ${VERSION} BEGIN target=${target} sha256=${sha8} -->\n${body}<!-- ${VERSION} END target=${target} -->\n`;
+}
+
+function emitJson(target, body) {
+  return JSON.stringify({
+    version: VERSION,
+    target,
+    sha256: sha256Hex(body),
+    body
+  }) + '\n';
+}
+
+function parseArgs(args) {
+  const parsed = {
+    printSnippet: false,
+    target: 'all',
+    format: 'markdown',
+    help: false
+  };
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === '--help' || arg === '-h') {
+      parsed.help = true;
+    } else if (arg === '--print-snippet') {
+      parsed.printSnippet = true;
+    } else if (arg === '--target') {
+      parsed.target = args[index + 1] || '';
+      index += 1;
+    } else if (arg.startsWith('--target=')) {
+      parsed.target = arg.slice('--target='.length);
+    } else if (arg === '--format') {
+      parsed.format = args[index + 1] || '';
+      index += 1;
+    } else if (arg.startsWith('--format=')) {
+      parsed.format = arg.slice('--format='.length);
+    }
+  }
+
+  return parsed;
+}
+
+function buildOutput(args, options = {}) {
+  const parsed = parseArgs(args);
+  const stdout = options.stdout || process.stdout;
+  const stderr = options.stderr || process.stderr;
+
+  if (parsed.help || !parsed.printSnippet) {
+    stdout.write(`${HELP}\n`);
+    return 0;
+  }
+
+  if (![...TARGETS, 'all'].includes(parsed.target)) {
+    stderr.write('error: --target must be one of claude, agents, gemini, all\n');
+    return 2;
+  }
+
+  if (!FORMATS.includes(parsed.format)) {
+    stderr.write('error: --format must be one of markdown, json\n');
+    return 2;
+  }
+
+  try {
+    const outputs = expandTargets(parsed.target).map((target) => {
+      const body = loadBody(target, options);
+      return parsed.format === 'json' ? emitJson(target, body) : emitMarkdown(target, body);
+    });
+
+    stdout.write(parsed.format === 'json' ? outputs.join('') : outputs.join('\n'));
+    return 0;
+  } catch (error) {
+    stderr.write(`error: failed to generate telepty snippet: ${error.message}\n`);
+    return 4;
+  }
+}
+
+module.exports = {
+  HELP,
+  TARGETS,
+  VERSION,
+  buildOutput,
+  emitJson,
+  emitMarkdown,
+  loadBody,
+  main: buildOutput,
+  sha256Hex
+};

package/src/init/snippets/agents.md

@@ -0,0 +1,15 @@
+## telepty-snippet:agents
+
+**telepty** is the aigentry ecosystem's PTY multiplexer and session orchestrator. It allows wrapping AI CLI sessions under stable IDs and addressing them across local and cross-machine boundaries via a daemon-mediated transport.
+
+Quick-start (5 commands):
+
+    telepty daemon
+    telepty allow --id <name> claude
+    telepty list
+    telepty inject <name> "<prompt>"
+    telepty attach <name>
+
+`telepty allow` wraps a CLI under the chosen `<name>`; `telepty list` enumerates known sessions; `telepty inject` sends a prompt to a wrapped session; `telepty attach` interactively connects to one.
+
+Run `telepty --help` for the full command list. Run `telepty <command> --help` for per-command flags.

package/src/init/snippets/claude.md

@@ -0,0 +1,15 @@
+## telepty-snippet:claude
+
+**telepty** is the aigentry ecosystem's PTY multiplexer and session orchestrator. It allows wrapping AI CLI sessions under stable IDs and addressing them across local and cross-machine boundaries via a daemon-mediated transport.
+
+Quick-start (5 commands):
+
+    telepty daemon
+    telepty allow --id <name> claude
+    telepty list
+    telepty inject <name> "<prompt>"
+    telepty attach <name>
+
+`telepty allow` wraps a CLI under the chosen `<name>`; `telepty list` enumerates known sessions; `telepty inject` sends a prompt to a wrapped session; `telepty attach` interactively connects to one.
+
+Run `telepty --help` for the full command list. Run `telepty <command> --help` for per-command flags.

package/src/init/snippets/gemini.md

@@ -0,0 +1,15 @@
+## telepty-snippet:gemini
+
+**telepty** is the aigentry ecosystem's PTY multiplexer and session orchestrator. It allows wrapping AI CLI sessions under stable IDs and addressing them across local and cross-machine boundaries via a daemon-mediated transport.
+
+Quick-start (5 commands):
+
+    telepty daemon
+    telepty allow --id <name> claude
+    telepty list
+    telepty inject <name> "<prompt>"
+    telepty attach <name>
+
+`telepty allow` wraps a CLI under the chosen `<name>`; `telepty list` enumerates known sessions; `telepty inject` sends a prompt to a wrapped session; `telepty attach` interactively connects to one.
+
+Run `telepty --help` for the full command list. Run `telepty <command> --help` for per-command flags.

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,
+};