polygram 0.11.0-rc.9 → 0.12.0-rc.10

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "polygram",
-  "version": "0.11.0-rc.9",
+  "version": "0.11.0-rc.15",
   "description": "Telegram integration for Claude Code that preserves the OpenClaw per-chat session model. Migration target for OpenClaw users. Multi-bot, multi-chat, per-topic isolation; SQLite transcripts; inline-keyboard approvals. Bundles /polygram:status|logs|pair-code|approvals admin commands plus history (transcript queries) and polygram-send (out-of-turn IPC sends with file-upload validation) skills.",
   "keywords": [
     "telegram",

package/config.example.json

@@ -4,6 +4,7 @@
   "bots": {
     "admin-bot": {
       "token": "REPLACE_WITH_BOT_TOKEN_FROM_BOTFATHER",
+      "_comment_apiRoot": "Optional. Point grammy at a self-hosted Telegram Bot API server (e.g. 'http://localhost:8082' from a local `telegram-bot-api --local` process) to raise file send/receive limits from cloud's 50MB-out / 20MB-in to 2GB both ways. Omit for cloud Telegram (default, unchanged). The server is a separate localhost-only companion daemon — see docs/0.12.0-file-send.md.",
       "allowConfigCommands": true,
       "_comment_adminChatId": "Required when allowConfigCommands is true for pairing commands (/pair-code, /pairings, /unpair) to work. These grant cross-chat trust and are gated to the admin chat only.",
       "adminChatId": "123456789",
@@ -70,7 +71,8 @@
       "model": "opus",
       "effort": "medium",
       "cwd": "/Users/you/admin-agent",
-      "timeout": 600
+      "timeout": 600,
+      "_comment_maxFileBytes": "OPTIONAL per-chat (or per-topic; topic wins) file-size cap in BYTES. There is NO fixed default — the default is backend-derived: cloud Telegram = 50MB send / 20MB receive; with a local Bot API server (bot.apiRoot set) = 2GB both ways. This key only LOWERS that ceiling for this chat (Telegram rejects anything above the backend limit regardless); omit it to use the full backend default. To set one, add e.g. \"maxFileBytes\": 104857600 (=100MB) — only meaningful when apiRoot is set, since cloud already clamps to 50/20MB."
     },
 
     "-1000000000001": {
@@ -100,7 +102,7 @@
       "isolateTopics": true,
       "_comment_topics": "rc.48: each topic entry is EITHER a string (legacy: just a label) OR an object with optional fields {name, agent, cwd, model, effort, permissionMode, isolateUserConfig}. Object form lets a topic override chat-level config. Per-topic permissionMode overrides chat-level — typical use: scope one topic to permissionMode:'default' (so settings.json gates apply) while the rest of the chat stays on bypassPermissions. Object form requires isolateTopics: true (each topic gets its own SDK Query); polygram emits a startup warning otherwise.",
       "_comment_isolateUserConfig": "0.10.0, tmux backend only: isolateUserConfig:true spawns the topic's claude TUI cut off from the user-level ~/.claude config — passes --strict-mcp-config (zero MCP servers load) and --setting-sources project,local (drops ~/.claude/settings.json; the spawn cwd's own .claude/settings.json still loads). Use it when a topic's agent would otherwise inherit slow user-global MCP servers whose cold-start (tens of seconds) wedges the TUI before it can accept a prompt. Settable at chat OR topic level (topic wins). Default false.",
-      "_comment_pm": "0.11.0: 'pm' selects the Process backend: 'sdk' (default; per-token Console API; full SDK features), 'tmux' (subscription-priced claude CLI in tmux; JSONL/pane parsing for IO), 'channels' (subscription-priced claude CLI in tmux; structured IO via the official Channels MCP protocol — see docs/0.11.0-channels-driver-plan.md). Settable at bot, chat, OR topic level (topic > chat > bot). Channels requires Pro/Max subscription, Claude Code v2.1.80+, and is in research preview — invokes --dangerously-load-development-channels.",
+      "_comment_pm": "0.12.0: 'pm' selects the Process backend. Two canonical values: 'sdk' (default; per-token Console API billing; full SDK features) and 'cli' (subscription-priced claude CLI in tmux + Channels MCP bridge + hooks ndjson observability — see docs/0.12.0-cli-driver-plan.md). Settable at bot, chat, OR topic level (topic > chat > bot). Aliases preserved for back-compat with 0.10/0.11 configs: 'channels' and 'tmux' both resolve to 'cli' with a once-at-boot deprecation warn. CLI requires Pro/Max subscription, Claude Code v2.1.80+, and uses --dangerously-load-development-channels (research preview flag).",
       "topics": {
         "100": "Customer A",
         "200": {

package/lib/attachments.js

@@ -22,8 +22,48 @@
  *     extension — the fallback only kicks in when MIME is unhelpful.
  */
 
-const MAX_FILE_BYTES = 10 * 1024 * 1024;
-const MAX_TOTAL_BYTES = 20 * 1024 * 1024;
+// Inbound (user → bot) per-file cap. Telegram's cloud Bot API hard-caps
+// bot file DOWNLOADS (getFile) at 20 MB, so 20 MB is the real ceiling on
+// cloud — raised from 10 MB so users can send larger tracks/docs. With a
+// self-hosted Bot API server (config.bot.apiRoot) the Telegram limit rises
+// to 2 GB; resolveFileCaps() raises the default accordingly.
+const MAX_FILE_BYTES = 20 * 1024 * 1024;
+const MAX_TOTAL_BYTES = 50 * 1024 * 1024;
+
+// ─── Backend-derived file-size caps (cloud vs local Bot API server) ──
+//
+// These are the HARD ceilings Telegram itself enforces — a per-chat
+// override can lower them but never exceed them (Telegram rejects beyond
+// regardless). NOT "adaptive": there is no intermediate tier. Cloud is a
+// flat 20 in / 50 out; a local `telegram-bot-api --local` server is a flat
+// 2 GB both ways.
+const CLOUD_MAX_IN_BYTES  = 20 * 1024 * 1024;          // getFile download limit
+const CLOUD_MAX_OUT_BYTES = 50 * 1024 * 1024;          // sendDocument upload limit
+const LOCAL_MAX_BYTES     = 2000 * 1024 * 1024;        // --local server, both ways
+
+/**
+ * Resolve the effective per-file caps for a chat/topic.
+ *
+ * @param {object} opts
+ * @param {boolean} opts.localApi   — true when config.bot.apiRoot is set
+ *   (a local Bot API server is in use → 2 GB ceiling).
+ * @param {...number} opts.override  — per-chat/topic maxFileBytes (bytes).
+ *   Resolved by the caller from topic → chat → undefined; clamped to the
+ *   backend ceiling.
+ * @returns {{ inBytes:number, outBytes:number, ceiling:number, localApi:boolean }}
+ */
+function resolveFileCaps({ localApi = false, override = null } = {}) {
+  const ceiling = localApi ? LOCAL_MAX_BYTES : null;
+  const defIn  = localApi ? LOCAL_MAX_BYTES : CLOUD_MAX_IN_BYTES;
+  const defOut = localApi ? LOCAL_MAX_BYTES : CLOUD_MAX_OUT_BYTES;
+  // A numeric override sets BOTH directions to the same value, clamped to
+  // the backend hard ceiling (cloud uses the per-direction default as the
+  // clamp so an override can't push past Telegram's own limit).
+  const ovr = (typeof override === 'number' && override > 0) ? override : null;
+  const inBytes  = ovr ? (localApi ? Math.min(ovr, ceiling) : Math.min(ovr, CLOUD_MAX_IN_BYTES))  : defIn;
+  const outBytes = ovr ? (localApi ? Math.min(ovr, ceiling) : Math.min(ovr, CLOUD_MAX_OUT_BYTES)) : defOut;
+  return { inBytes, outBytes, ceiling: ceiling ?? CLOUD_MAX_OUT_BYTES, localApi };
+}
 const MIME_ALLOW = [
   /^image\//, /^audio\//, /^video\//,
   /^application\/pdf$/, /^text\/plain$/,
@@ -109,8 +149,12 @@ function filterAttachments(attachments, opts = {}) {
 
 module.exports = {
   filterAttachments,
+  resolveFileCaps,
   MAX_FILE_BYTES,
   MAX_TOTAL_BYTES,
+  CLOUD_MAX_IN_BYTES,
+  CLOUD_MAX_OUT_BYTES,
+  LOCAL_MAX_BYTES,
   MIME_ALLOW,
   EXTENSION_ALLOW,
   FALLBACK_MIMES,

package/lib/claude-bin.js

@@ -4,16 +4,20 @@ const os = require('os');
 const path = require('path');
 const fs = require('fs');
 
+// 0.12 Phase 4: moved from lib/process/tmux-process.js into the helper module
+// that consumes it, so the constant survives TmuxProcess deletion. CliProcess
+// + spike scripts + polygram boot all import from here now.
+const CLAUDE_CLI_PINNED_VERSION = '2.1.142';
+
 /**
- * Resolve + verify the pinned claude CLI binary for the tmux backend.
+ * Resolve + verify the pinned claude CLI binary.
  *
- * Why this exists: the tmux backend reads claude CLI INTERNAL
- * artefacts (JSONL events, queue-operation semantics, TUI banner
- * ASCII, READY hint strings, stop_reason values) — none a stable
- * public contract. polygram pins ONE version
- * (CLAUDE_CLI_PINNED_VERSION in lib/process/tmux-process.js) and
- * must spawn THAT binary, never whatever `claude` on $PATH happens
- * to resolve to.
+ * Why this exists: the tmux + CLI backends read claude CLI internal
+ * artefacts (TUI banner ASCII, READY hint strings, channel notification
+ * registration timing, MCP-init order) — none a stable public contract.
+ * polygram pins ONE version (`CLAUDE_CLI_PINNED_VERSION`) and must
+ * spawn THAT binary, never whatever `claude` on $PATH happens to
+ * resolve to.
  *
  * Before this module the tmux runner spawned the bare string
  * `claude`, resolved through $PATH. The claude CLI installs each
@@ -75,4 +79,4 @@ function verifyPinnedClaudeBin(version) {
   }
 }
 
-module.exports = { resolvePinnedClaudeBin, verifyPinnedClaudeBin };
+module.exports = { resolvePinnedClaudeBin, verifyPinnedClaudeBin, CLAUDE_CLI_PINNED_VERSION };

package/lib/db/auto-resume.js

@@ -90,6 +90,13 @@ function createAutoResumeTracker({ cooldownMs = DEFAULT_COOLDOWN_MS, now = Date.
  */
 function isAutoResumable({ error, aborted, replay, shuttingDown }) {
   if (aborted || replay || shuttingDown) return false;
+  // Review F#6: channels analog of the tmux 'idle with no Claude activity'
+  // pattern. The bridge socket dropped mid-turn (claude crashed, bridge
+  // process died) — that's a wedge, not a runaway. Same intent as the
+  // regex match below, just expressed via err.code because channels throws
+  // a different message string. TURN_TIMEOUT stays NON-resumable (it's
+  // the channels analog of the wall-clock ceiling — likely a runaway).
+  if (error?.code === 'BRIDGE_DISCONNECTED') return true;
   const msg = String(error?.message || error || '');
   return /idle with no Claude activity/i.test(msg);
 }

package/lib/db/sessions.js

@@ -205,12 +205,20 @@ function resolveSessionForSpawn(db, sessionKey, resolved = {}) {
   // of THAT task; claude responded with music release info, inline,
   // never calling the reply tool. Every turn timed out at 3min.
   //
-  // Rule: any transition TO or FROM channels drops the prior session.
-  // XOR — flips between channels and {sdk,tmux} invalidate; sdk↔tmux
-  // flips remain free.
-  const wasChannels = before.pm_backend === 'channels';
-  const willBeChannels = after.pm_backend === 'channels';
-  if (after.pm_backend != null && wasChannels !== willBeChannels) {
+  // Rule: any transition TO or FROM the channels/CLI backend drops the
+  // prior session. XOR — flips between (channels|cli) and {sdk,tmux}
+  // invalidate; sdk↔tmux flips remain free (rc.32 reasoning).
+  //
+  // 0.12: 'cli' is the canonical name for what was 'channels' in 0.11.
+  // Treat both as the same "channels-class" backend for transition
+  // invalidation purposes — a row persisted with pm_backend='channels'
+  // before 0.12 and a row created today with pm_backend='cli' are
+  // semantically the same in terms of session-context invariants
+  // (bridge MCP server mounted, reply-tool contract enforced).
+  const CHANNELS_CLASS = new Set(['channels', 'cli']);
+  const wasChannelsClass = CHANNELS_CLASS.has(before.pm_backend);
+  const willBeChannelsClass = CHANNELS_CLASS.has(after.pm_backend);
+  if (after.pm_backend != null && wasChannelsClass !== willBeChannelsClass) {
     drifted.push('pm_backend');
   }
 

package/lib/error/classify.js

@@ -163,6 +163,47 @@ const CODES = {
     isTransient: false,
     autoRecover: null,
   },
+  // Review F#5: channels-specific error codes. Pre-fix these fell through
+  // to the generic 'unknown' kind (errorReplyText: "Hit a snag. Try
+  // resending.") which lies about what happened. Mirrors the rc.46→rc.47
+  // tmuxToolWedge fix where backend-specific codes needed their own kinds.
+  //
+  // BRIDGE_DISCONNECTED: thrown by CliProcess when the mcp-bridge
+  // socket drops mid-turn (claude crashed, bridge process died, etc).
+  // isTransient: true because the daemon retries spawning the backend.
+  BRIDGE_DISCONNECTED: {
+    kind: 'bridgeDisconnected',
+    userMessage: '🔌 Lost the bridge to Claude mid-turn. Retrying — please resend if I don\'t reply in 30s.',
+    isTransient: true,
+    autoRecover: null,
+  },
+  // CHANNELS_HANDSHAKE_TIMEOUT: bridge process never sent session_init
+  // within the handshake window during start(). Usually means the bridge
+  // crashed pre-init or the socket file is stale.
+  CHANNELS_HANDSHAKE_TIMEOUT: {
+    kind: 'channelsHandshakeTimeout',
+    userMessage: '⏳ Couldn\'t start a Claude session — the bridge didn\'t respond in time. Try again in a moment.',
+    isTransient: true,
+    autoRecover: null,
+  },
+  // CHANNELS_DIALOG_TIMEOUT: a permission / usage-limit / context-overflow
+  // dialog opened mid-turn and we couldn't auto-respond within the dialog
+  // window. The turn is dead; user needs to retry.
+  CHANNELS_DIALOG_TIMEOUT: {
+    kind: 'channelsDialogTimeout',
+    userMessage: '🚧 Claude hit a dialog (permission/usage-limit) mid-turn and I couldn\'t auto-respond in time. Please resend.',
+    isTransient: false,
+    autoRecover: null,
+  },
+  // TURN_TIMEOUT: 10-min wall-clock cap on a single channels turn. Mirror
+  // of the tmux wall-clock ceiling — typically a runaway, not a wedge.
+  // Not transient (auto-retry would just runaway again).
+  TURN_TIMEOUT: {
+    kind: 'turnTimeout',
+    userMessage: '⏱ The turn ran past the 10-minute cap. Resend if the answer still matters.',
+    isTransient: false,
+    autoRecover: null,
+  },
 };
 
 /**

package/lib/handlers/abort.js

@@ -42,13 +42,37 @@ function createHandleAbort({
     const threadId = msg.message_thread_id?.toString();
     const sessionKey = getSessionKey(chatId, threadId, chatConfig);
     const proc = pm.has(sessionKey) ? pm.get(sessionKey) : null;
-    const hadActive = !!proc?.inFlight;
+    let hadActive = !!proc?.inFlight;
 
     // Mark BEFORE killing: the 'close' event fires almost immediately
     // after interrupt, and the surrounding handleMessage's catch
     // needs to see the flag to skip the generic error-reply.
     if (hadActive) markSessionAborted(sessionKey);
 
+    // "Stop" incident (shumorobot Music, 2026-05-31 13:08): on the
+    // CliProcess/channels backend a turn resolves on the quiet-window
+    // after claude's last reply tool call (inFlight → false), but claude
+    // can still be working (subagent, long Bash). Keying the ack on
+    // inFlight alone made "Stop" say "Nothing to stop" while a subagent
+    // download churned. probeBusyState() reads the TUI "esc to interrupt"
+    // hint — the truthful signal — so detection, the abort mark, and the
+    // ack all agree. The probe result is logged below (forensics) so the
+    // heuristic can be refined against real states later. Channels analog
+    // of the (deleted) tmux hasBackgroundShell branch; typeof-guarded so
+    // it's a no-op on backends without it.
+    let busyProbe = null;
+    if (!hadActive && proc && typeof proc.probeBusyState === 'function') {
+      try {
+        busyProbe = await proc.probeBusyState();
+        if (busyProbe?.busy) {
+          hadActive = true;
+          markSessionAborted(sessionKey);
+        }
+      } catch (err) {
+        logger.error?.(`[${botName}] busy-probe failed: ${err.message}`);
+      }
+    }
+
     // Bug 1 (incident 2026-05-18): "Stop" was turn-scoped — it only
     // looked at an in-flight TURN. But the agent can leave a DETACHED
     // background shell running (a `run_in_background:true` Bash) that
@@ -87,6 +111,19 @@ function createHandleAbort({
       chat_id: chatId, user_id: msg.from?.id || null,
       had_active: hadActive,
       killed_background_shell: killedBackgroundShell,
+      // "Stop" incident forensics: the raw busy-probe signals at decision
+      // time. Lets us query, across real aborts, where the esc-hint /
+      // inFlight / pending-turn signals agreed vs diverged and refine the
+      // heuristic later. null when no probe ran (turn was already inFlight,
+      // or the backend has no probeBusyState).
+      busy_probe: busyProbe ? {
+        busy: busyProbe.busy,
+        streaming: busyProbe.streaming,
+        in_flight: busyProbe.inFlight,
+        pending_turns: busyProbe.pendingTurns,
+        captured: busyProbe.captured,
+        pane_tail: busyProbe.paneTail,
+      } : null,
       trigger: cleanText.slice(0, 40),
     });
 

package/lib/handlers/slash-commands.js

@@ -199,7 +199,17 @@ function createSlashCommands({
         }), 'log model change');
         const { anyActive } = await applyConfigChange('model', newModel);
         const ver = (modelVersionsDesc && modelVersionsDesc[newModel]) || newModel;
-        const suffix = anyActive ? ` — I'll switch when I finish` : '';
+        // Review F#10: channels backend can't apply model/effort changes
+        // live — its setModel/applyFlagSettings throw UNSUPPORTED_OPERATION,
+        // pm.setModel returns false → `anyActive` is true → user saw the
+        // misleading "I'll switch when I finish" message. Now we detect
+        // the channels backend explicitly and give an honest answer:
+        // settings are persisted to chatConfig and take effect on the next
+        // /reset or /new (channels lacks an in-place re-init path).
+        const backendName = typeof pm.getBackend === 'function' ? pm.getBackend(sessionKey) : null;
+        const suffix = backendName === 'channels'
+          ? ` — applies on next /reset (channels)`
+          : (anyActive ? ` — I'll switch when I finish` : '');
         await sendReply(`Model → ${newModel} (${ver})${suffix}`);
       } else {
         await sendReply(`Unknown model. Use: opus, sonnet, haiku`);
@@ -219,7 +229,17 @@ function createSlashCommands({
           user: cmdUser, user_id: cmdUserId, source: 'command',
         }), 'log effort change');
         const { anyActive } = await applyConfigChange('effort', newEffort);
-        const suffix = anyActive ? ` — I'll switch when I finish` : '';
+        // Review F#10: channels backend can't apply model/effort changes
+        // live — its setModel/applyFlagSettings throw UNSUPPORTED_OPERATION,
+        // pm.setModel returns false → `anyActive` is true → user saw the
+        // misleading "I'll switch when I finish" message. Now we detect
+        // the channels backend explicitly and give an honest answer:
+        // settings are persisted to chatConfig and take effect on the next
+        // /reset or /new (channels lacks an in-place re-init path).
+        const backendName = typeof pm.getBackend === 'function' ? pm.getBackend(sessionKey) : null;
+        const suffix = backendName === 'channels'
+          ? ` — applies on next /reset (channels)`
+          : (anyActive ? ` — I'll switch when I finish` : '');
         await sendReply(`Effort → ${newEffort}${suffix}`);
       } else {
         await sendReply(`Unknown effort. Use: low, medium, high, xhigh, max`);

package/lib/ipc/file-validator.js

@@ -50,7 +50,14 @@ function validateIpcFileParam(method, params = {}) {
   const fileParam = FILE_PARAM_BY_METHOD[method];
   if (!fileParam) return null;
   const val = params[fileParam];
-  if (typeof val !== 'string') return null;       // envelope/Buffer/etc — pass through
+  // { source: '/abs/path' } envelope — now coerced to a grammy InputFile in
+  // tg() (coerceFileParams). Validate it has a usable absolute source, else
+  // pass through (Buffer / stream / InputFile shapes).
+  if (val && typeof val === 'object' && typeof val.source === 'string') {
+    if (val.source.length === 0) return `polygram IPC: ${fileParam}.source is empty`;
+    return null;
+  }
+  if (typeof val !== 'string') return null;       // Buffer/InputFile/etc — pass through
   if (val.length === 0) return `polygram IPC: ${fileParam} is empty`;
 
   const looksUrl = /^(https?|ftp):\/\//i.test(val);

package/lib/process/channels-bridge-protocol.js

@@ -2,7 +2,7 @@
  * Bridge ↔ daemon socket protocol — typed schemas.
  *
  * Wire format: newline-delimited JSON over a unix socket per session.
- * Both endpoints (ChannelsProcess and channels-bridge.mjs) speak the same
+ * Both endpoints (CliProcess and channels-bridge.mjs) speak the same
  * message kinds. This module centralizes the shape so both sides safeParse
  * inbound messages with the same constraints — protecting against malformed
  * payloads silently corrupting pending-state Maps.
@@ -10,7 +10,7 @@
  * Adding a new message kind:
  *   1. Define its schema below as `<KindName>MessageSchema`
  *   2. Add it to `AnyDaemonToBridgeMessage` or `AnyBridgeToDaemonMessage`
- *   3. Handle it in the corresponding switch (channels-process.js
+ *   3. Handle it in the corresponding switch (cli-process.js
  *      _onBridgeMsg or channels-bridge.mjs handleDaemonMessage)
  *
  * Validation policy:
@@ -67,12 +67,22 @@ const PongMessageSchema = z.object({
   kind: z.literal('pong'),
 }).passthrough();
 
+// 0.12 Phase 1.6: bridge tells daemon when claude has finished registering
+// the bridge as an MCP server (claude sent its first ListToolsRequest).
+// Polygram's _waitForBridgeHandshake gates on this in addition to hello,
+// eliminating the cold-spawn race (Finding 0.3.A).
+const McpReadyMessageSchema = z.object({
+  kind: z.literal('mcp-ready'),
+  session: NonEmptyString,
+}).passthrough();
+
 const AnyBridgeToDaemonMessage = z.discriminatedUnion('kind', [
   HelloSchema,
   SessionInitSchema,
   ToolCallMessageSchema,
   PermRequestMessageSchema,
   PongMessageSchema,
+  McpReadyMessageSchema,
 ]);
 
 // ─── daemon → bridge ───────────────────────────────────────────────

package/lib/process/channels-bridge-server.js

@@ -2,11 +2,11 @@
  * ChannelsBridgeServer — per-session unix-socket server for the bridge
  * subprocess to connect back to.
  *
- * Extracted from ChannelsProcess (M1 refactor) so the socket lifecycle —
+ * Extracted from CliProcess (M1 refactor) so the socket lifecycle —
  * listen with restrictive umask, accept ONE bridge, hello-handshake auth,
  * line-delimited JSON I/O, schema validation, single-bridge-per-session
  * enforcement, clean teardown — lives in one focused class instead of
- * sprawling across ChannelsProcess.
+ * sprawling across CliProcess.
  *
  * Owns:
  *   - net.Server lifecycle (listen / close)
@@ -17,11 +17,14 @@
  *
  * Does NOT own:
  *   - protocol semantics (tool routing, perm relay, turn lifecycle) — those
- *     stay in ChannelsProcess, which subscribes to the events this class emits
+ *     stay in CliProcess, which subscribes to the events this class emits
  *   - claude/bridge process lifecycle
  *
  * Event surface (EventEmitter):
- *   'bridge-ready'        — handshake complete; safe to send daemon→bridge msgs
+ *   'bridge-ready'        — daemon-side handshake (hello + session_init) complete
+ *   'mcp-ready'           — claude-side MCP-server registration complete (first
+ *                            ListToolsRequest received from claude). 0.12 P1.6
+ *                            cold-spawn race fix — see channels-bridge.mjs.
  *   'bridge-message', msg — every validated bridge→daemon message (post-auth)
  *   'bridge-disconnected' — single-bridge connection closed
  *   'error', err          — socket-level errors (rare; non-fatal)
@@ -29,6 +32,7 @@
 
 'use strict';
 
+const crypto = require('node:crypto');
 const EventEmitter = require('node:events');
 const fs = require('node:fs');
 const net = require('node:net');
@@ -162,14 +166,26 @@ class ChannelsBridgeServer extends EventEmitter {
         }
 
         if (!authenticated) {
-          if (raw.kind === 'hello'
-              && raw.session_key === this.sessionKey
-              && raw.secret === this.sockSecret) {
+          // Review F#7: harden the hello-handshake.
+          //   1. timingSafeEqual for the secret compare so a same-uid
+          //      attacker can't byte-by-byte probe via response-timing.
+          //   2. ROTATE the secret after first successful auth (set to
+          //      null) so a stale POLYGRAM_SOCK_SECRET leaked via
+          //      /proc/<pid>/environ can't replay against this
+          //      CliProcess after the legit bridge disconnects.
+          //      The bridge process is one-shot per spawn anyway (it
+          //      exits on socket close — see channels-bridge.mjs:109),
+          //      so legitimate re-auth within one CliProcess
+          //      instance never happens — only a hijacker would.
+          const verdict = this._verifyHelloAuth(raw);
+          if (verdict.ok) {
             authenticated = true;
             this.authenticated = true;
+            this.sockSecret = null;   // invalidate — single-shot per instance
             try { conn.write(JSON.stringify({ kind: 'hello_ack' }) + '\n'); } catch {}
             continue;
           }
+          this.logger.warn?.(`[${this.label}] hello rejected — reason=${verdict.reason}`);
           try { conn.write(JSON.stringify({ kind: 'hello_reject', reason: 'auth' }) + '\n'); } catch {}
           conn.end();
           this.conn = null;
@@ -193,6 +209,13 @@ class ChannelsBridgeServer extends EventEmitter {
           this.emit('bridge-ready');
           continue;
         }
+        if (parsed.msg.kind === 'mcp-ready') {
+          // 0.12 Phase 1.6: bridge signals that claude has finished
+          // registering it as an MCP server. Polygram gates send() on this
+          // (Finding 0.3.A — cold-spawn race).
+          this.emit('mcp-ready', parsed.msg);
+          continue;
+        }
         this.emit('bridge-message', parsed.msg);
       }
     });
@@ -209,6 +232,43 @@ class ChannelsBridgeServer extends EventEmitter {
       this.logger.warn?.(`[${this.label}] bridge conn error: ${err.message}`);
     });
   }
+
+  /**
+   * Review F#7: hello-handshake verification, extracted as a pure method so it
+   * can be exercised in isolation. Returns `{ ok: true }` on accept or
+   * `{ ok: false, reason }` on reject. Uses crypto.timingSafeEqual for the
+   * secret compare and refuses if this.sockSecret has already been consumed
+   * (post-auth rotation).
+   *
+   * @param {object} raw — parsed bridge→daemon hello payload
+   * @returns {{ ok: true } | { ok: false, reason: string }}
+   */
+  _verifyHelloAuth(raw) {
+    if (this.sockSecret == null) {
+      return { ok: false, reason: 'secret-consumed' };
+    }
+    if (!raw || raw.kind !== 'hello') {
+      return { ok: false, reason: 'not-hello' };
+    }
+    if (raw.session_key !== this.sessionKey) {
+      return { ok: false, reason: 'wrong-session-key' };
+    }
+    if (typeof raw.secret !== 'string' || raw.secret.length === 0) {
+      return { ok: false, reason: 'no-secret' };
+    }
+    const a = Buffer.from(raw.secret, 'utf8');
+    const b = Buffer.from(this.sockSecret, 'utf8');
+    if (a.length !== b.length) {
+      // timingSafeEqual requires equal-length inputs; length mismatch is a
+      // wrong-secret signal but constant-time compares MUST short-circuit
+      // here (otherwise we'd leak the secret's length).
+      return { ok: false, reason: 'wrong-secret' };
+    }
+    if (!crypto.timingSafeEqual(a, b)) {
+      return { ok: false, reason: 'wrong-secret' };
+    }
+    return { ok: true };
+  }
 }
 
 module.exports = { ChannelsBridgeServer };