polygram 0.12.0-rc.2 → 0.12.0-rc.21

package/lib/process/cli-process.js

@@ -48,6 +48,13 @@ const { Process, UnsupportedOperationError } = require('./process');
 const { ChannelsBridgeServer } = require('./channels-bridge-server');
 const { writeHookFiles, removeHookFiles } = require('./hook-settings');
 const { createHookTail } = require('./hook-event-tail');
+// File-send staging: reuse the dispatcher's allowlist root so the dir we
+// create exactly matches the realpath the validator accepts (no /tmp vs
+// /private/tmp drift — one of the original Music-topic failures).
+const { DEFAULT_ATTACHMENT_BASE } = require('./channels-tool-dispatcher');
+const { resolveFileCaps } = require('../attachments');
+const { resolveCompactionWarnConfig } = require('../compaction-warn');
+const { readContextTokens, contextPct } = require('../context-usage');
 const { runStartupGate } = require('../tmux/startup-gate');
 const { POLYGRAM_DISPLAY_HINT } = require('../telegram/display-hint');
 
@@ -113,6 +120,17 @@ const STREAMING_HINT_RE = /esc to interrupt/i;
 // — false positives surface as no-op telemetry, false negatives surface
 // as the idle-ceiling timeout (~10min).
 const UNKNOWN_PROMPT_HEURISTIC_RE = /(\?\s*$|\(y\/N\)|Yes\/No|❯\s|^\s*[12345]\.\s)/im;
+// rc.14: a previous rc (rc.11) had a BRIDGE_DEAD_RE here that matched the pane
+// line "server:polygram-bridge  no MCP server configured with that name" and
+// treated it as a dead bridge to recover from. That was a MISDIAGNOSIS: this
+// line is a BENIGN, persistent banner that `--dangerously-load-development-
+// channels` + `--strict-mcp-config` prints on EVERY healthy session — the
+// channel still delivers messages and the reply tool still works (reproduced
+// 2026-06-01 with a test MCP server that demonstrably functions). The pane
+// matcher therefore false-fired ~5s into every channels turn and KILLED
+// healthy sessions (the Music-topic "mid-turn detach" regression). Real bridge
+// loss is caught by the socket-close path (bridgeServer 'bridge-disconnected'
+// → _handleBridgeDisconnected). There is no reliable pane signal — removed.
 // Per-pattern rate limit so a dialog that lingers across multiple polls
 // doesn't spam sendControl/event emissions. Aligned with the 5s poll cadence.
 const MID_TURN_DEDUP_WINDOW_MS = 30_000;
@@ -251,6 +269,10 @@ class CliProcess extends Process {
     // pending turn(s): turn_id → { resolve, reject, replies: [], quietTimer, hardTimer, startedAt }
     this.pendingTurns = new Map();
 
+    // File-send outbound cap (bot → user). Safe cloud default; overwritten in
+    // _spawnTmuxClaude with the backend/chat-resolved value before any turn.
+    this.maxOutboundFileBytes = resolveFileCaps({ localApi: false }).outBytes;
+
     // P1 security (review #8): track resolved permission request_ids so a
     // double-fire of respond() can't write a second perm_verdict for the same
     // request. TmuxProcess gates on _pendingApprovalId; this is the channels
@@ -297,6 +319,23 @@ class CliProcess extends Process {
     // permit files under the agent's workspace.
     this.sessionCwd = opts.cwd || null;
 
+    // File-send staging dir (2026-06 file-send feature). The dispatcher
+    // allowlist always permits <DEFAULT_ATTACHMENT_BASE>/<sessionKey>/, but
+    // nothing ever CREATED it — so claude's reply(files) attempts at
+    // /tmp/polygram-attachments failed (dir absent / realpath mismatch) and
+    // it flailed across other paths. Create it here and surface it to the
+    // prompt so claude has one blessed, always-allowed place to stage a file
+    // before sending. realpathSync so the stored path matches what the
+    // validator resolves (the /tmp ↔ /private/tmp fix).
+    try {
+      const dir = path.join(DEFAULT_ATTACHMENT_BASE, String(this.sessionKey));
+      fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+      this.attachmentStagingDir = fs.realpathSync(dir);
+    } catch (err) {
+      this.attachmentStagingDir = null;
+      this.logger.warn?.(`[${this.label}] channels: staging dir create failed: ${err.message}`);
+    }
+
     // Opaque random token for socket filename — do NOT leak sessionKey to /tmp.
     const socketToken = crypto.randomBytes(16).toString('hex');
     this.sockPath = path.join(os.tmpdir(), `polygram-${socketToken}.sock`);
@@ -416,28 +455,7 @@ class CliProcess extends Process {
 
     this.bridgeServer.on('bridge-message', msg => this._handleBridgeMessage(msg));
 
-    this.bridgeServer.on('bridge-disconnected', () => {
-      this.bridgeReady = false;
-      this.mcpReady = false;
-      if (!this.closed) {
-        this.logger.warn?.(`[${this.label}] channels: bridge disconnected unexpectedly`);
-        // P1 #5: drain pendingTurns immediately so hardTimers don't run 10min.
-        for (const [, pending] of this.pendingTurns) {
-          if (pending.quietTimer) clearTimeout(pending.quietTimer);
-          if (pending.hardTimer) clearTimeout(pending.hardTimer);
-          if (pending.absoluteTimer) clearTimeout(pending.absoluteTimer);
-          if (pending._stopGraceTimer) clearTimeout(pending._stopGraceTimer);
-          const err = new Error('bridge disconnected');
-          err.code = 'BRIDGE_DISCONNECTED';
-          try { pending.reject(err); } catch {}
-        }
-        this.pendingTurns.clear();
-        this.pendingQueue.length = 0;
-        this.inFlight = false;
-        this.emit('bridge-disconnected');
-        this._logEvent('bridge-disconnected', { reason: 'socket-close' });
-      }
-    });
+    this.bridgeServer.on('bridge-disconnected', () => this._handleBridgeDisconnected());
 
     await this.bridgeServer.listen();
   }
@@ -493,6 +511,26 @@ class CliProcess extends Process {
     const effort = topicConfig?.effort || opts.chatConfig?.effort || opts.effort;
     const resolvedCwd = topicConfig?.cwd || opts.chatConfig?.cwd || opts.cwd;
 
+    // File-send outbound cap (bot → user). Backend-derived (cloud 50MB vs
+    // local Bot API server 2GB via opts.localApi) with per-topic/chat
+    // maxFileBytes override, clamped to the backend ceiling. Stored for the
+    // dispatcher (live size-check) and the system prompt (so claude states
+    // the right limit). Resolved here so it follows the same topic→chat
+    // precedence as cwd/agent above.
+    const _capOverride = topicConfig?.maxFileBytes ?? opts.chatConfig?.maxFileBytes ?? null;
+    this.maxOutboundFileBytes = resolveFileCaps({
+      localApi: !!opts.localApi,
+      override: _capOverride,
+    }).outBytes;
+
+    // 0.12.0-rc.13: per-chat/topic compaction warning (default OFF). Same
+    // topic→chat precedence as the file cap above. When enabled, the channels
+    // backend warns the chat as context fills (propose /compact at a break)
+    // and on auto-compaction (the event that detaches the bridge mid-turn).
+    const _compactionWarnRaw = topicConfig?.compactionWarnings ?? opts.chatConfig?.compactionWarnings;
+    this.compactionWarn = resolveCompactionWarnConfig({ compactionWarnings: _compactionWarnRaw });
+    this._compactionWarned = false;  // proactive warn-once per climb; reset on PostCompact
+
     // Parity audit P8 + rc.8 fs-guard (2026-05-26 shumorobot Music topic):
     // `--session-id <id>` creates a NEW claude session with that id;
     // `--resume <id>` resumes the EXISTING conversation. Lazy-respawn after
@@ -540,6 +578,9 @@ class CliProcess extends Process {
         );
       }
     }
+    // Finding 0.12-M2: record the resume decision so _armHookTail (run
+    // after spawn) skips the prior session's still-on-disk hook ndjson.
+    this._resumedSession = canResume;
     if (agent)  claudeArgs.push('--agent', agent);
     if (model)  claudeArgs.unshift('--model', model);
     if (effort) claudeArgs.push('--effort', effort);
@@ -616,6 +657,28 @@ class CliProcess extends Process {
       'Internal tool calls (Bash, Edit, Write, Read, etc.) are fine to use',
       'as normal — only the FINAL user-visible message needs to go through',
       'the reply tool.',
+      '',
+      '### Sending FILES (tracks, images, docs) to the user',
+      '',
+      'The `mcp__polygram-bridge__reply` tool takes an optional `files` array of',
+      'absolute paths. This is the ONLY way to send a file. Do NOT use Bash,',
+      'curl, the Telegram Bot API, or polygram-ipc to send files — those fail.',
+      '',
+      ...(this.attachmentStagingDir ? [
+        `To send a file: COPY it into the staging dir \`${this.attachmentStagingDir}\`,`,
+        'then call reply with its absolute path, e.g.:',
+        `  reply(chat_id="<id>", text="Here's the track", files=["${this.attachmentStagingDir}/track.flac"])`,
+        'polygram auto-deletes staged files after the turn — you do not need to clean up.',
+        'You may also send directly from the agent workspace (cwd); other paths are rejected.',
+      ] : [
+        'Copy the file somewhere under your workspace (cwd) and pass its absolute',
+        'path in `files`. Paths outside the workspace are rejected for safety.',
+      ]),
+      '',
+      `Max file size for sending: ${Math.round(this.maxOutboundFileBytes / (1024 * 1024))} MB. ` +
+        'For larger lossless audio, convert to FLAC/MP3 under the limit first, ' +
+        'or tell the user it exceeds the limit. Images go as photos; everything ' +
+        'else as documents.',
     ].join('\n'));
 
     // Parity audit P6: honor isolateUserConfig — mirrors tmux pattern at
@@ -705,6 +768,20 @@ class CliProcess extends Process {
       ],
       readySignal: /Listening for channel messages from: server:polygram-bridge/i,
       timeoutCode: 'CHANNELS_DIALOG_TIMEOUT',
+      // Progress-aware gate (shumorobot General incident 2026-05-30): a
+      // cold spawn that's mid-download (runtime fetch, "24%" progress bar)
+      // is genuinely working and must NOT be killed by the blind 30s
+      // wall-clock. stallMs fails fast only when the pane is FROZEN; an
+      // actively-changing pane (download bar, dialog nav) keeps resetting
+      // the stall clock and rides out to the ready signal. deadlineMs stays
+      // the absolute backstop. 30s of zero pane activity = genuinely wedged.
+      // Stall = pane rendered then went static (genuinely wedged). 60s, not
+      // 30s: some topics' TUIs cold-render slowly (Music ~45s, slow MCP
+      // startup) — 30s was too tight and false-aborted them. Blank panes
+      // don't arm the stall timer at all now (see runStartupGate), so this
+      // only bounds a TUI that rendered and then truly hung.
+      stallMs: this.startupGateStallMs ?? 60_000,
+      deadlineMs: this.startupGateDeadlineMs ?? 180_000,
       logger: this.logger,
       label: `${this.label}:startup-gate`,
     });
@@ -849,15 +926,18 @@ class CliProcess extends Process {
     // rate-limit / chat-id-mismatch path. Live shumorobot 2026-05-26 23:44
     // observed 3+ "Called polygram-bridge" entries in the TUI pane with
     // ZERO OUT messages delivered to TG and zero warn-level diagnostics —
-    // need to see args.text / args.chat_id / args.turn_id to know whether
-    // claude is calling reply with empty text, wrong chat_id, or something
-    // else entirely.
-    this.logger.warn?.(
+    // need to see args.chat_id / args.turn_id to know whether claude is
+    // calling reply with empty text, wrong chat_id, or something else.
+    // L13: root-caused — demoted to debug and DROPPED text_head. Logging
+    // the first 80 chars of every reply at warn level leaked private chat
+    // content / file excerpts / secrets into the default log sink,
+    // unconditionally. name/chat_id/turn_id/text_len diagnose dispatch
+    // without exposing message content.
+    this.logger.debug?.(
       `[${this.label}] channels: tool-call name=${msg.name} ` +
       `chat_id=${JSON.stringify(args.chat_id)} ` +
       `turn_id=${JSON.stringify(args.turn_id)} ` +
-      `text_len=${typeof args.text === 'string' ? args.text.length : 'non-string'} ` +
-      `text_head=${JSON.stringify((args.text || '').slice(0, 80))}`,
+      `text_len=${typeof args.text === 'string' ? args.text.length : 'non-string'}`,
     );
 
     // Review P1 #7: idempotency. If we've already ACK'd this tool_call_id,
@@ -948,6 +1028,7 @@ class CliProcess extends Process {
         text: args.text,
         files: args.files,
         sessionCwd: this.sessionCwd,        // P0 #2: dispatcher uses this to allowlist file roots
+        maxOutboundFileBytes: this.maxOutboundFileBytes, // backend/chat-derived upload cap
       });
     } catch (err) {
       this._writeToBridge({ kind: 'tool_ack', tool_call_id: msg.tool_call_id, ok: false, error: err.message });
@@ -1122,13 +1203,27 @@ class CliProcess extends Process {
       this._finalizeTurn(turnId);
     };
     const onStop = (info) => {
-      // Capture the fallback text; the actual finalize call below will pick
-      // it up via pending._stopHookData.
+      // Finding 0.12-M1: the Stop hook carries NO turn_id, and a single
+      // global 'stop-hook' emission fires EVERY per-turn onStop listener.
+      // When more than one turn is in stop-grace we cannot attribute this
+      // Stop (or its last_assistant_message) to a specific turn — the
+      // pre-fix code let one Stop finalize all grace-pending turns and
+      // cross-attribute one turn's text to another (the exact class the
+      // F#3 reply routing prevents). Mirror that drop-rather-than-
+      // misattribute discipline: only consume the Stop when exactly ONE
+      // turn is in grace; otherwise ignore it and let each turn finalize
+      // on its own grace timer (each keeps its own reply text).
+      let graceCount = 0;
+      for (const p of this.pendingTurns.values()) if (p._stopGracePending) graceCount++;
+      if (graceCount !== 1) return;
       pending._stopHookData = info;
       clearTimeout(pending._stopGraceTimer);
       pending._stopGraceTimer = null;
       finalize();
     };
+    // L5: stash the closure so teardown paths that bypass Process.kill()'s
+    // removeAllListeners (bridge-disconnect drain, resetSession) can off it.
+    pending._onStop = onStop;
     pending._stopGraceTimer = setTimeout(finalize, this.stopGraceMs);
     // unref so a never-fired grace doesn't pin the event loop. In tests
     // where a CliProcess is created, send() is called, then the test
@@ -1154,6 +1249,7 @@ class CliProcess extends Process {
     if (pending.hardTimer) clearTimeout(pending.hardTimer);
     if (pending.absoluteTimer) clearTimeout(pending.absoluteTimer);
     if (pending._stopGraceTimer) clearTimeout(pending._stopGraceTimer);
+    const hadReplyToolCalls = pending.replies.length > 0;
     let text = pending.replies.join('\n\n');
     // 0.12 Phase 1.7 fallback: if no reply tool calls landed (claude ended
     // the turn without calling mcp__polygram-bridge__reply), use the Stop
@@ -1171,12 +1267,14 @@ class CliProcess extends Process {
     // to appear free in dashboards.
     const result = {
       text,
-      // Review F#2: dispatcher has ALREADY delivered text to Telegram on each
-      // reply tool call (incremental real-time UX is the channels delivery
-      // model). polygram.js's post-pm.send pipeline must short-circuit its
-      // streamer.finalize / deliverReplies branch — otherwise every turn
-      // delivers twice. Logging + DB transcript still use result.text.
-      alreadyDelivered: true,
+      // Review F#2: when claude used reply tool calls, the dispatcher ALREADY
+      // delivered that text to Telegram incrementally — polygram.js must
+      // short-circuit its deliverReplies branch or every turn delivers twice.
+      // BUT a turn finalized via the Stop fallback (no reply tool calls — the
+      // stuck-turn case) has delivered NOTHING; marking it alreadyDelivered
+      // would resolve the turn silently and the user still sees nothing. So
+      // only claim already-delivered when reply tool calls actually fired.
+      alreadyDelivered: hadReplyToolCalls,
       sessionId: this.claudeSessionId,
       cost: null,             // Channels protocol doesn't expose per-turn cost
       duration,
@@ -1195,6 +1293,27 @@ class CliProcess extends Process {
     pending.resolve(result);
     this.emit('result', { subtype: 'success' }, { streamText: text });
     this.emit('idle');
+    // File-send staging auto-purge (your choice — no "claude must delete").
+    // Once the LAST turn settles, wipe the staging dir's contents so files
+    // claude copied in to send don't accumulate on disk across turns. Only
+    // when fully idle, so a file staged for a still-pending concurrent turn
+    // isn't yanked mid-send.
+    if (this.pendingTurns.size === 0) this._purgeStagingDir();
+  }
+
+  /**
+   * Empty the per-session file-send staging dir (keep the dir itself).
+   * Best-effort; never throws. Called when the session goes idle and on kill.
+   */
+  _purgeStagingDir() {
+    if (!this.attachmentStagingDir) return;
+    let entries;
+    try { entries = fs.readdirSync(this.attachmentStagingDir); }
+    catch { return; }
+    for (const name of entries) {
+      try { fs.rmSync(path.join(this.attachmentStagingDir, name), { recursive: true, force: true }); }
+      catch { /* best-effort */ }
+    }
   }
 
   // ─── public Process API ──────────────────────────────────────────
@@ -1386,6 +1505,63 @@ class CliProcess extends Process {
     this._interruptGraceTimer.unref?.();
   }
 
+  /**
+   * Is claude actually still working, regardless of the resolved-turn flag?
+   *
+   * "Stop" incident (shumorobot Music, 2026-05-31 13:08): the channels
+   * backend resolves a turn on the quiet-window after claude's last reply
+   * tool call (inFlight → false), but claude can keep working afterwards
+   * (a subagent, a long Bash). The abort handler keyed its ack on inFlight
+   * alone, so "Stop" said "Nothing to stop" one second after the bot said
+   * "On it — downloading…" while a subagent churned.
+   *
+   * The TUI prints "esc to interrupt" (STREAMING_HINT_RE) continuously
+   * whenever claude is busy — capture-pane is the truthful signal, the
+   * channels analog of the (deleted) tmux hasBackgroundShell() probe.
+   *
+   * Returns a STRUCTURED probe (not just a boolean) so the abort path can
+   * log the raw signals — pane tail + flags — to the events DB. That lets
+   * us later characterize which states the heuristic gets right/wrong and
+   * refine it (e.g. add signals beyond the esc-hint) without guessing.
+   *
+   * Never throws — a failed capture returns captured:false, busy:false.
+   *
+   * @returns {Promise<{busy:boolean, streaming:boolean, inFlight:boolean,
+   *   pendingTurns:number, captured:boolean, paneTail:(string|null)}>}
+   */
+  async probeBusyState() {
+    const base = {
+      busy: false, streaming: false,
+      inFlight: this.inFlight, pendingTurns: this.pendingTurns.size,
+      captured: false, paneTail: null,
+    };
+    if (this.closed || !this.tmuxSession || typeof this.runner?.captureWide !== 'function') {
+      return base;
+    }
+    let pane;
+    try {
+      pane = await this.runner.captureWide(this.tmuxSession);
+    } catch (err) {
+      this.logger.warn?.(`[${this.label}] channels: probeBusyState captureWide failed: ${err.message}`);
+      return base;
+    }
+    if (!pane) return base;
+    const streaming = STREAMING_HINT_RE.test(pane);
+    return {
+      ...base,
+      busy: streaming,
+      streaming,
+      captured: true,
+      paneTail: pane.slice(-200),
+    };
+  }
+
+  /** Boolean shorthand for probeBusyState().busy (abort-path convenience). */
+  async isBusy() {
+    const { busy } = await this.probeBusyState();
+    return busy;
+  }
+
   async kill(reason = 'kill') {
     if (this.closed) return;
     // Parity P19: re-entry guard for concurrent kill() calls. Mirrors
@@ -1415,17 +1591,18 @@ class CliProcess extends Process {
       this.logger.warn?.(`[${this.label}] _armHookTail: _hookNdjsonPath unset; hooks disabled. Phase 1.2 may have failed.`);
       return;
     }
-    // Fresh spawn: ndjson was just touched by writeHookFiles and is empty,
-    // so `skipExisting: false` (default) is correct. For lazy-respawn on
-    // existingSessionId, we currently re-run writeHookFiles which touches
-    // a NEW file with the same name (overwrite). If we ever switch to
-    // resume-without-touch, set skipExisting: true to avoid replaying
-    // stale events from the prior process — same pattern tmux uses on
-    // --resume per rc.42 #5.
+    // Finding 0.12-M2: writeHookFiles opens the ndjson in APPEND mode
+    // ('a') and never truncates, so on a --resume respawn the prior
+    // session's hook lines are still on disk under the same path. Replaying
+    // them re-drives the turn state machine from stale Stop/PreToolUse
+    // events (a stale Stop can finalize the fresh turn). So skip existing
+    // content when (and only when) this is a resumed session — the same
+    // discipline the JSONL tail uses on --resume. A fresh spawn's ndjson is
+    // empty, so skipExisting:false is correct there.
     this._hookTail = createHookTail({
       path: this._hookNdjsonPath,
       logger: this.logger,
-      skipExisting: false,
+      skipExisting: this._resumedSession === true,
     });
     this._hookTail.on('event', (ev) => {
       try {
@@ -1458,6 +1635,22 @@ class CliProcess extends Process {
   _handleHookEvent(ev) {
     if (!ev || typeof ev !== 'object') return;
 
+    // rc.16 observability: emit once when the FIRST hook event arrives for
+    // this session, confirming the claude→ndjson→tail pipeline is actually
+    // flowing. The 2026-06-02 stuck turn had a session whose hook ndjson was
+    // 0 bytes — claude emitted no hooks polygram could see, so no Stop ever
+    // arrived to finalize the turn. Without this signal that's invisible: a
+    // turn that hangs with NO `cli-hook-stream-live` for its session means the
+    // hook pipeline is dead for it (distinct from "Stop fired but wasn't
+    // acted on", which `cli-turn-resolved-by-stop` now covers).
+    if (!this._sawHookStream) {
+      this._sawHookStream = true;
+      this._logEvent('cli-hook-stream-live', {
+        session_id: this.claudeSessionId,
+        first_event: ev.type,
+      });
+    }
+
     // 0.12 Phase 1.8 (Finding 0.4.A): per-event lag measurement.
     // polygram_received_at_ms is stamped by the helper subprocess at write
     // time; subtracting from Date.now() gives the helper-write → tail-emit
@@ -1465,25 +1658,18 @@ class CliProcess extends Process {
     // gates tag-out on median < 2s and p99 < 5s across the events DB.
     if (Number.isFinite(ev.receivedAtMs)) {
       const lagMs = Date.now() - ev.receivedAtMs;
+      // L10: emit ONLY — the onHookLagSample callback owns the DB write
+      // (CALLBACK_TO_EVENT → callbacks.js). Previously this ALSO wrote
+      // directly via this.db.logEvent, double-persisting every sample and
+      // inflating the Phase 1.8 soak-gate row count. Consistent with how
+      // tool-result / subagent-start / subagent-done are handled (emit,
+      // don't double-write).
       this.emit('hook-lag-sample', {
         hookEventName: ev.type,
         lagMs,
         toolName: ev.toolName || null,
         backend: this.backend,
       });
-      // Log to events DB if wired. db is optional (factory injects when
-      // available) — same pattern as the other parity-P1 _logEvent calls.
-      if (this.db?.logEvent) {
-        try {
-          this.db.logEvent('hook-lag-sample', {
-            session_key: this.sessionKey,
-            backend: this.backend,
-            hook_event_name: ev.type,
-            tool_name: ev.toolName || null,
-            lag_ms: lagMs,
-          });
-        } catch {}
-      }
     }
 
     switch (ev.type) {
@@ -1503,6 +1689,16 @@ class CliProcess extends Process {
           const subagentType = ev.toolInput?.subagent_type
             || ev.toolInput?.agent_type
             || 'general-purpose';
+          // Finding 0.12-M4: SubagentStop carries agent_id/agent_type but
+          // NOT the originating Agent tool_use_id, so without help the
+          // subagent-start/subagent-done rows share no JOIN key (the
+          // documented soak query on $.tool_use_id returns zero rows).
+          // Track the in-flight Agent tool_use_id keyed by subagent type so
+          // the paired SubagentStop below can stamp it onto subagent-done.
+          (this._pendingSubagentStarts ||= []).push({
+            agentType: subagentType,
+            toolUseId: ev.toolUseId,
+          });
           this.emit('subagent-start', {
             agentType: subagentType,
             // PreToolUse for Agent carries no agent_id (set later on
@@ -1541,24 +1737,102 @@ class CliProcess extends Process {
         });
         return;
 
-      case 'SubagentStop':
+      case 'SubagentStop': {
+        // Finding 0.12-M4: recover the originating Agent tool_use_id so the
+        // subagent-start/subagent-done pair is JOINable. Prefer a match on
+        // agent type (correct for parallel subagents of different types);
+        // fall back to the oldest pending start when types don't line up.
+        let subagentToolUseId = null;
+        const pendingStarts = this._pendingSubagentStarts;
+        if (pendingStarts && pendingStarts.length) {
+          let idx = pendingStarts.findIndex(s => s.agentType === ev.agentType);
+          if (idx < 0) idx = 0;
+          subagentToolUseId = pendingStarts.splice(idx, 1)[0]?.toolUseId ?? null;
+        }
         this.emit('subagent-done', {
           agentType: ev.agentType,
           agentId: ev.agentId,
           durationMs: ev.durationMs,
+          toolUseId: subagentToolUseId,
           backend: this.backend,
         });
         return;
+      }
 
-      case 'Stop':
-        // Phase 1.7 (TODO) will use this as the authoritative turn-end
-        // signal with stopGraceMs. For now: pass through as 'stop-hook'
-        // event so the resolver in Phase 1.7 can subscribe.
-        this.emit('stop-hook', {
+      case 'Stop': {
+        // 0.12.0 Phase 1.7 (rc.16): Stop is the AUTHORITATIVE turn-end signal.
+        const info = {
           stopHookActive: ev.stopHookActive,
           lastAssistantMessage: ev.lastAssistantMessage,
           backend: this.backend,
-        });
+        };
+        // Turns already resolving via a reply quiet-window consume this via
+        // their per-turn onStop listener (the text-fallback rescue inside
+        // _resolveTurn). Emit first so that path runs synchronously and any
+        // grace-pending turn is finalized + removed before the check below.
+        this.emit('stop-hook', info);
+
+        // THE FIX (2026-06-02 stuck-turn): a turn that ended WITHOUT a reply
+        // tool call has no quiet-window to fire _resolveTurn — pre-fix it hung
+        // until the 30-min wall-clock backstop while the unknown-prompt
+        // watchdog spun. Stop IS the turn-end; resolve the single in-flight
+        // turn now (reply text if any, else last_assistant_message). After the
+        // emit above, a grace-pending turn is already gone, so this only fires
+        // for the no-reply case. Gated on exactly one in-flight turn — Stop
+        // carries no turn_id, so we cannot attribute it when turns are
+        // concurrent (the M1 cross-attribution hazard).
+        if (this.pendingTurns.size === 1) {
+          const [turnId, p] = [...this.pendingTurns.entries()][0];
+          if (!p._stopGracePending) {
+            p._stopHookData = info;
+            this._logEvent('cli-turn-resolved-by-stop', {
+              turn_id: turnId,
+              reply_count: p.replies?.length || 0,
+              via_text_fallback: (p.replies?.length || 0) === 0,
+              session_id: this.claudeSessionId,
+            });
+            this._finalizeTurn(turnId);
+          }
+        } else if (this.pendingTurns.size > 1) {
+          // Can't attribute Stop to one of several concurrent turns — surface
+          // it so a turn that waited for its grace timer (instead of resolving
+          // on Stop) is explained in the events DB.
+          this._logEvent('cli-stop-unattributed', { pending_count: this.pendingTurns.size });
+        }
+
+        // 0.12.0-rc.13 proactive compaction warning: on turn-end, if enabled
+        // for this chat and not already warned this climb, sample context
+        // occupancy from the transcript and warn (propose /compact) BEFORE
+        // claude auto-compacts mid-turn and detaches the bridge. Fire-and-
+        // forget — transcript IO must never block the stop path.
+        if (this.compactionWarn?.enabled && !this._compactionWarned && ev.transcriptPath) {
+          this._maybeProactiveCompactionWarn(ev.transcriptPath);
+        }
+        return;
+      }
+
+      case 'PreCompact':
+        // 0.12.0-rc.13: auto-compaction is the event that detaches the
+        // channels MCP bridge mid-turn. Record it; and on the dangerous AUTO
+        // case (manual /compact is the user's own deliberate action — never
+        // nag), emit a reactive warning the chat layer posts. The proactive
+        // warning (on Stop) tries to PREVENT this; this is the backstop.
+        this._logEvent('cli-compaction-imminent', { trigger: ev.trigger });
+        if (this.compactionWarn?.enabled && ev.trigger === 'auto') {
+          this.emit('compaction-warn', {
+            kind: 'reactive',
+            trigger: 'auto',
+            sessionId: this.claudeSessionId,
+            backend: this.backend,
+          });
+        }
+        return;
+
+      case 'PostCompact':
+        // Context just dropped — re-arm the proactive warn-once so the next
+        // climb can warn again.
+        this._compactionWarned = false;
+        this._logEvent('cli-compaction-done', { trigger: ev.trigger });
         return;
 
       case 'Notification':
@@ -1597,15 +1871,22 @@ class CliProcess extends Process {
         {
           const requestId = ev.toolUseId || `hook-notification-${Date.now()}`;
           const toolName = ev.toolName;
-          const toolInput = this._formatToolInputForApproval(
-            ev.prompt || null,
-            // Use the structured tool_input as the "preview" — it's
-            // already structured by claude rather than truncated to
-            // 200 chars like the channels bridge perm_req does.
-            typeof ev.toolInput === 'string'
-              ? ev.toolInput
-              : JSON.stringify(ev.toolInput || {}),
-          );
+          // Finding #11 fix: pass the STRUCTURED tool_input through. makeCanUseTool
+          // matches gated patterns via matchesAnyPattern, which reads
+          // input.command (Bash) / input.url (WebFetch) — a formatted STRING
+          // makes those undefined so a gated `Bash(rm *)` never matches and the
+          // tool is allowed with NO approval card (silent gating bypass). The
+          // hook Notification payload carries structured tool_input, so forward
+          // it as-is; the approval card (approvalCardText) renders a structured
+          // object fine — same shape the SDK canUseTool path already uses. Fall
+          // back to the formatted-string preview only if claude sent no
+          // structured tool_input (degenerate — tool needs perm but no input).
+          const toolInput = (ev.toolInput && typeof ev.toolInput === 'object')
+            ? ev.toolInput
+            : this._formatToolInputForApproval(
+                ev.prompt || null,
+                typeof ev.toolInput === 'string' ? ev.toolInput : JSON.stringify(ev.toolInput || {}),
+              );
           this.emit('approval-required', {
             id: requestId,
             toolName,
@@ -1665,6 +1946,50 @@ class CliProcess extends Process {
     }
   }
 
+  /**
+   * Drain on unexpected bridge socket loss (claude crash, bridge crash,
+   * EOF). Extracted from the inline 'bridge-disconnected' handler so the
+   * teardown is testable and consistent with _doKill.
+   *
+   * Findings 0.12-L5 + L6: in addition to clearing the per-turn timers
+   * and rejecting pendings (the original P1 #5 behavior), this now also
+   * (L5) removes each turn's stop-hook listener — this drain does NOT go
+   * through Process.kill()'s blanket removeAllListeners, so a turn torn
+   * down mid-stop-grace would otherwise leak its onStop closure — and
+   * (L6) clears _interruptGraceTimer, matching _doKill (a /stop verdict
+   * landing just before the disconnect would otherwise leave a stray
+   * timer on the dead instance).
+   */
+  _handleBridgeDisconnected(reason = 'socket-close') {
+    this.bridgeReady = false;
+    this.mcpReady = false;
+    if (this.closed) return;
+    this.logger.warn?.(`[${this.label}] channels: bridge disconnected unexpectedly (${reason})`);
+    // L6: clear the interrupt grace timer alongside the rest of the lifecycle.
+    if (this._interruptGraceTimer) {
+      clearTimeout(this._interruptGraceTimer);
+      this._interruptGraceTimer = null;
+    }
+    // P1 #5: drain pendingTurns immediately so hardTimers don't run 10min.
+    for (const [, pending] of this.pendingTurns) {
+      if (pending.quietTimer) clearTimeout(pending.quietTimer);
+      if (pending.hardTimer) clearTimeout(pending.hardTimer);
+      if (pending.absoluteTimer) clearTimeout(pending.absoluteTimer);
+      if (pending._stopGraceTimer) clearTimeout(pending._stopGraceTimer);
+      // L5: remove the per-turn stop-hook listener (this path bypasses
+      // Process.kill()'s removeAllListeners).
+      if (pending._onStop) this.off('stop-hook', pending._onStop);
+      const err = new Error('bridge disconnected');
+      err.code = 'BRIDGE_DISCONNECTED';
+      try { pending.reject(err); } catch {}
+    }
+    this.pendingTurns.clear();
+    this.pendingQueue.length = 0;
+    this.inFlight = false;
+    this.emit('bridge-disconnected');
+    this._logEvent('bridge-disconnected', { reason });
+  }
+
   async _doKill(reason) {
     this.closed = true;
     this.inFlight = false;
@@ -1688,6 +2013,7 @@ class CliProcess extends Process {
       if (pending.hardTimer) clearTimeout(pending.hardTimer);
       if (pending.absoluteTimer) clearTimeout(pending.absoluteTimer);
       if (pending._stopGraceTimer) clearTimeout(pending._stopGraceTimer);
+      if (pending._onStop) this.off('stop-hook', pending._onStop); // L5
       const err = new Error(`session killed: ${reason}`);
       err.code = 'KILLED';
       pending.reject(err);
@@ -1734,6 +2060,12 @@ class CliProcess extends Process {
     if (this.botName && this.claudeSessionId) {
       try { removeHookFiles({ botName: this.botName, sessionId: this.claudeSessionId }); } catch {}
     }
+    // File-send staging: remove the whole per-session dir on kill (purge only
+    // empties it between turns; kill is end-of-life so drop it entirely).
+    if (this.attachmentStagingDir) {
+      try { fs.rmSync(this.attachmentStagingDir, { recursive: true, force: true }); } catch {}
+      this.attachmentStagingDir = null;
+    }
 
     this.emit('close', 0);
   }
@@ -1876,6 +2208,8 @@ class CliProcess extends Process {
       if (pending.quietTimer) clearTimeout(pending.quietTimer);
       if (pending.hardTimer) clearTimeout(pending.hardTimer);
       if (pending.absoluteTimer) clearTimeout(pending.absoluteTimer);
+      if (pending._stopGraceTimer) clearTimeout(pending._stopGraceTimer); // L5
+      if (pending._onStop) this.off('stop-hook', pending._onStop);        // L5
       const err = new Error(`session reset: ${reason}`);
       err.code = 'RESET';
       try { pending.reject(err); } catch {}
@@ -2088,6 +2422,37 @@ class CliProcess extends Process {
    * Extracted as a separate async method so unit tests can drive it
    * directly without waiting for the setInterval tick.
    */
+  /**
+   * 0.12.0-rc.13: proactive compaction warning. Read the transcript's current
+   * context occupancy and, if past the per-chat threshold, emit a
+   * 'compaction-warn' the chat layer turns into "you're ~N% full, run
+   * /compact" — giving the user a window to compact on their terms BEFORE
+   * claude auto-compacts mid-turn (which detaches the channels bridge). Warns
+   * once per climb (this._compactionWarned), re-armed on PostCompact.
+   * Fire-and-forget: swallows its own errors so transcript IO never breaks
+   * the turn-end path.
+   */
+  async _maybeProactiveCompactionWarn(transcriptPath) {
+    try {
+      if (!this.compactionWarn?.enabled || this._compactionWarned) return;
+      const usage = await readContextTokens(transcriptPath);
+      if (!usage) return;
+      const pct = contextPct(usage.total) * 100;
+      if (pct < this.compactionWarn.thresholdPct) return;
+      if (this._compactionWarned) return;   // re-check after the async gap
+      this._compactionWarned = true;
+      this.emit('compaction-warn', {
+        kind: 'proactive',
+        pct: Math.round(pct),
+        totalTokens: usage.total,
+        sessionId: this.claudeSessionId,
+        backend: this.backend,
+      });
+    } catch (err) {
+      this.logger.warn?.(`[${this.label}] compaction-warn sample failed: ${err.message}`);
+    }
+  }
+
   async _pollMidTurnDialogs() {
     if (this.closed) return;
     if (this.pendingTurns.size === 0) return;        // no work to do when idle
@@ -2106,6 +2471,15 @@ class CliProcess extends Process {
     }
     if (!pane) return;
 
+    // rc.14: removed the rc.11 pane-based "dead bridge" detection here. It
+    // matched the BENIGN banner "server:polygram-bridge  no MCP server
+    // configured with that name" — a cosmetic line that
+    // `--dangerously-load-development-channels` + `--strict-mcp-config` prints
+    // on EVERY healthy session (channel still delivers; reply tool still
+    // works). The matcher false-fired ~5s into every channels turn and killed
+    // healthy sessions. Real bridge loss is the socket-close path
+    // (_handleBridgeDisconnected), not anything observable in the pane.
+
     const now = Date.now();
 
     // 0.12 Phase 3.2: liveness heartbeat. The TUI prints "esc to interrupt"