polygram 0.10.0-rc.9 → 0.11.0-rc.11

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "polygram",
-  "version": "0.10.0-rc.9",
+  "version": "0.11.0-rc.11",
   "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

@@ -98,7 +98,9 @@
       "cwd": "/Users/you/admin-agent",
       "requireMention": true,
       "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}. 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_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.",
       "topics": {
         "100": "Customer A",
         "200": {
@@ -107,7 +109,8 @@
           "cwd": "/Users/you/customer-b-projects",
           "model": "opus",
           "effort": "high",
-          "permissionMode": "default"
+          "permissionMode": "default",
+          "isolateUserConfig": true
         }
       }
     },

package/lib/autosteered-refs.js

@@ -46,12 +46,22 @@
  *   logged to opts.logger?.error — they never block clearing of
  *   subsequent refs.
  * @param {{ error?: (msg: string) => void }} [opts.logger]
+ * @param {number} [opts.minIntervalMs=250]
+ *   minimum gap (ms) between successive applyClear calls inside a
+ *   single clear() loop. Telegram's setMessageReaction rate limit
+ *   is ~5/sec/chat; 250ms (4/sec) stays under that. Pass 0 to
+ *   disable pacing in tests / contexts where the underlying applyClear
+ *   doesn't talk to a rate-limited API. Only the GAP between calls
+ *   is paced — the first call fires immediately, single-ref clears
+ *   incur no delay. L7 fix 2026-05-16: was unpaced, exceeded the
+ *   Telegram cap under N≥6 autosteers per turn.
  * @returns {AutosteeredRefs}
  */
-function createAutosteeredRefs({ applyClear, logger = console } = {}) {
+function createAutosteeredRefs({ applyClear, logger = console, minIntervalMs = 250 } = {}) {
   if (typeof applyClear !== 'function') {
     throw new TypeError('applyClear function required');
   }
+  const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
   /** @type {Map<string, MsgRef[]>} */
   const refs = new Map();
 
@@ -79,7 +89,15 @@ function createAutosteeredRefs({ applyClear, logger = console } = {}) {
     if (!list || list.length === 0) return 0;
     refs.delete(sessionKey);
     let cleared = 0;
-    for (const ref of list) {
+    // L7: pace inter-call gaps to stay under Telegram's
+    // setMessageReaction rate limit (~5/sec/chat). The first call
+    // fires immediately — pacing applies only to the gap BEFORE the
+    // 2nd+ call. minIntervalMs=0 disables pacing entirely.
+    for (let i = 0; i < list.length; i += 1) {
+      const ref = list[i];
+      if (i > 0 && minIntervalMs > 0) {
+        await sleep(minIntervalMs);
+      }
       try {
         await applyClear(ref);
         cleared += 1;

package/lib/claude-bin.js

@@ -0,0 +1,78 @@
+'use strict';
+
+const os = require('os');
+const path = require('path');
+const fs = require('fs');
+
+/**
+ * Resolve + verify the pinned claude CLI binary for the tmux backend.
+ *
+ * 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.
+ *
+ * Before this module the tmux runner spawned the bare string
+ * `claude`, resolved through $PATH. The claude CLI installs each
+ * version as a standalone binary at
+ *   ~/.local/share/claude/versions/<version>
+ * and points ~/.local/bin/claude (a symlink) at the active one.
+ * Its auto-updater re-points that symlink whenever a new version
+ * lands — so a $PATH spawn silently drifts (shumorobot 2026-05-16:
+ * CLI auto-updated 2.1.142 → 2.1.143 between deploys).
+ *
+ * Spawning the ABSOLUTE versioned path is immune to that: the
+ * updater only ADDS new version files, it never overwrites an
+ * existing one. `versions/2.1.142` stays byte-identical forever.
+ */
+
+/**
+ * Absolute path to the pinned claude binary.
+ *
+ * Resolution order:
+ *   1. POLYGRAM_CLAUDE_BIN env — explicit override (non-standard
+ *      installs, CI, hosts where the layout differs).
+ *   2. ~/.local/share/claude/versions/<version> — the standard
+ *      claude-CLI install location.
+ *
+ * The returned path is NOT guaranteed to exist — callers verify
+ * via verifyPinnedClaudeBin().
+ *
+ * @param {string} version — pinned version, e.g. '2.1.142'
+ * @returns {string} absolute path
+ */
+function resolvePinnedClaudeBin(version) {
+  const override = process.env.POLYGRAM_CLAUDE_BIN;
+  if (override) return override;
+  return path.join(os.homedir(), '.local', 'share', 'claude', 'versions', version);
+}
+
+/**
+ * Verify the pinned binary exists and is executable.
+ *
+ * @param {string} version — pinned version, e.g. '2.1.142'
+ * @returns {{ ok: boolean, path: string, reason?: string }}
+ *   ok=true → path is a spawnable binary.
+ *   ok=false → reason carries an operator-actionable message.
+ */
+function verifyPinnedClaudeBin(version) {
+  const binPath = resolvePinnedClaudeBin(version);
+  try {
+    fs.accessSync(binPath, fs.constants.X_OK);
+    return { ok: true, path: binPath };
+  } catch (err) {
+    const code = err && err.code ? err.code : (err && err.message) || 'unknown';
+    return {
+      ok: false,
+      path: binPath,
+      reason: `pinned claude CLI v${version} not found or not executable at `
+        + `${binPath} (${code}). Install it with \`claude install ${version}\` `
+        + 'or set POLYGRAM_CLAUDE_BIN to the correct binary path.',
+    };
+  }
+}
+
+module.exports = { resolvePinnedClaudeBin, verifyPinnedClaudeBin };

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

@@ -95,4 +95,145 @@ function getClaudeSessionId(db, sessionKey) {
   return row?.claude_session_id || null;
 }
 
-module.exports = { migrateJsonToDb, getClaudeSessionId, countSessions };
+// ─── S2: session-config drift ────────────────────────────────────────
+//
+// A stored `sessions` row records the config the claude session was
+// SPAWNED under. Two of the recorded fields are spawn-identity:
+//   - agent — `--agent <name>` is baked into the spawned process;
+//     resuming a session spawned under agent X under agent Y forces
+//     claude to use Y's system prompt + tool whitelist against
+//     conversation history built under X's. Incoherent.
+//   - cwd — `--cwd <path>` (SDK) / tmux session cwd; claude resolves
+//     project-local config (.claude/settings.json, agent files,
+//     plugins) relative to it. Mid-conversation cwd drift means
+//     half the messages are answered with one project's allowlist
+//     and the other half with another's.
+//
+// pm_backend was REMOVED from spawn-identity (rc.32, 2026-05-21).
+// Both backends spawn the same pinned claude binary and write the
+// same on-disk JSONL (~/.claude/projects/<cwd-enc>/<sid>.jsonl) —
+// claude itself doesn't know or care which Node-side wrapper invoked
+// it. Treating a backend flip as drift was destructively dropping
+// context across the SDK→tmux migration window, costing every chat
+// its conversation history on its first turn under the new backend.
+// shumorobot 2026-05-20 18:51 incident: the Music topic flipped
+// tmux→sdk→tmux during runtime and lost its agent's prior context
+// at each flip. The orphan-tmux problem that the flip ALSO triggered
+// is solved by rc.31's spawn-time reconcile (TmuxProcess.start) —
+// independently, so a backend flip is now a no-op for session-state.
+//
+// shumorobot 2026-05-17 22:03, topic :3 (the original drift incident)
+// remains correctly handled: that row had agent+cwd drift in
+// addition to backend, so the agent+cwd drift alone still drops it.
+//
+// model + effort are deliberately EXCLUDED from the invalidating set.
+// They are NOT spawn-identity: a live `/model` or `/effort` change is
+// pushed into the running session by `pm.setModel` /
+// `pm.applyFlagSettings` with no respawn (lib/handlers/slash-commands.js,
+// lib/handlers/config-callback.js). Including them here would
+// destructively drop the whole session — discarding all context — on
+// every model switch, double-handling what the live-apply path
+// already covers cleanly. The stored model/effort columns are
+// informational, not identity.
+const SPAWN_IDENTITY_FIELDS = ['agent', 'cwd'];
+
+/**
+ * Decide whether a stored session can be resumed for the next spawn,
+ * or whether config drift means it must be dropped and re-spawned
+ * fresh.
+ *
+ * On drift the stale row is DELETED here — so the very next spawn
+ * mints a fresh claude_session_id under the correct config and the
+ * `onInit` callback re-upserts the row. This self-heals every
+ * pre-migration stale row across all chats with no manual SQL.
+ *
+ * @param {object|null} db          — DB handle (null → fresh spawn)
+ * @param {string} sessionKey
+ * @param {object} resolved         — freshly-resolved spawn config
+ * @param {string} [resolved.agent]
+ * @param {string} [resolved.cwd]
+ * @param {string} [resolved.backend] — 'sdk' | 'tmux' (resolved by
+ *   process/factory.js pickBackend); compared to the row's pm_backend
+ * @returns {{ existingSessionId: string|null, drift: object|null }}
+ *   existingSessionId — pass to start() for --resume, or null for a
+ *     fresh spawn (no stored row, or drift dropped it)
+ *   drift — null when no drift; otherwise { fields, before, after }
+ *     for the `session-config-drift` telemetry event
+ */
+function resolveSessionForSpawn(db, sessionKey, resolved = {}) {
+  if (!db) return { existingSessionId: null, drift: null };
+  const row = db.getSession(sessionKey);
+  if (!row || !row.claude_session_id) {
+    return { existingSessionId: null, drift: null };
+  }
+
+  // Normalise: a missing field on either side is treated as equal to
+  // a missing field on the other (both null/undefined → no drift).
+  const after = {
+    agent: resolved.agent || null,
+    cwd: resolved.cwd || null,
+    pm_backend: resolved.backend || null,
+  };
+  const before = {
+    agent: row.agent || null,
+    cwd: row.cwd || null,
+    pm_backend: row.pm_backend || null,
+  };
+  const drifted = SPAWN_IDENTITY_FIELDS.filter((f) => {
+    // If the resolved config does not specify a field, do not treat
+    // it as drift — we have nothing to compare against.
+    if (after[f] == null) return false;
+    return before[f] !== after[f];
+  });
+
+  // 0.11.0 channels boundary (2026-05-25): SDK ↔ tmux flips remain
+  // non-invalidating per rc.32's reasoning. But channels mode is
+  // genuinely different on the claude side:
+  //
+  //   - bridge MCP server is mounted (--mcp-config + --strict-mcp-config)
+  //   - additional --append-system-prompt directive enforces the
+  //     reply-tool contract (claude must call mcp__polygram-bridge__reply
+  //     instead of writing inline). Sessions created without this
+  //     directive don't have the contract baked into their context.
+  //   - agent behavior expectations differ — same agent file, but
+  //     conversation flow is "user msg arrives via channel, reply via
+  //     tool" rather than "user msg arrives inline, reply inline."
+  //
+  // Live shumorobot 2026-05-25 incident: Music topic resumed a
+  // pre-channels session id (4837f61a-…) that had been mid-soulseek-
+  // curation. The user's "how are you" got interpreted as a continuation
+  // 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) {
+    drifted.push('pm_backend');
+  }
+
+  if (drifted.length === 0) {
+    return { existingSessionId: row.claude_session_id, drift: null };
+  }
+
+  // Drift: drop the stale row so the next spawn is fresh + correct.
+  db.clearSessionId(sessionKey);
+  return {
+    existingSessionId: null,
+    drift: {
+      fields: drifted,
+      before: { ...before, claude_session_id: row.claude_session_id },
+      after,
+    },
+  };
+}
+
+module.exports = {
+  migrateJsonToDb,
+  getClaudeSessionId,
+  resolveSessionForSpawn,
+  countSessions,
+  SPAWN_IDENTITY_FIELDS,
+};

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 ChannelsProcess 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

@@ -41,13 +41,37 @@ function createHandleAbort({
 
     const threadId = msg.message_thread_id?.toString();
     const sessionKey = getSessionKey(chatId, threadId, chatConfig);
-    const hadActive = pm.has(sessionKey) && !!pm.get(sessionKey)?.inFlight;
+    const proc = pm.has(sessionKey) ? pm.get(sessionKey) : null;
+    const 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);
 
+    // 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
+    // outlives the turn; the tmux TUI shows an `N shell` indicator.
+    // When there is no live turn, check for such a shell and stop it
+    // so "Stop" acts truthfully instead of replying "Nothing to stop"
+    // while work is still churning. tmux-only — the SDK Process has no
+    // hasBackgroundShell()/killBackgroundShells(); the typeof guards
+    // make this a no-op there.
+    let killedBackgroundShell = false;
+    if (!hadActive && proc
+      && typeof proc.hasBackgroundShell === 'function'
+      && typeof proc.killBackgroundShells === 'function') {
+      try {
+        if (await proc.hasBackgroundShell()) {
+          markSessionAborted(sessionKey);
+          killedBackgroundShell = await proc.killBackgroundShells();
+        }
+      } catch (err) {
+        logger.error?.(`[${botName}] background-shell stop failed: ${err.message}`);
+      }
+    }
+
     // SDK abort: interrupt() + drainQueue(). interrupt() cancels
     // the in-flight turn at SDK level WITHOUT tearing down the
     // Query (cheap to reuse for the user's next message);
@@ -62,6 +86,7 @@ function createHandleAbort({
     logEvent('abort-requested', {
       chat_id: chatId, user_id: msg.from?.id || null,
       had_active: hadActive,
+      killed_background_shell: killedBackgroundShell,
       trigger: cleanText.slice(0, 40),
     });
 
@@ -69,10 +94,23 @@ function createHandleAbort({
     // detection is crude but reliable for ru/en.
     const lang = /[а-яё]/i.test(cleanText) ? 'ru' : 'en';
     const strs = {
-      en: { stopped: 'Stopped.',     nothing: 'Nothing to stop.' },
-      ru: { stopped: 'Остановлено.', nothing: 'Нечего останавливать.' },
+      en: {
+        stopped: 'Stopped.',
+        bgStopped: 'Stopped the background task.',
+        nothing: 'Nothing to stop.',
+      },
+      ru: {
+        stopped: 'Остановлено.',
+        bgStopped: 'Фоновая задача остановлена.',
+        nothing: 'Нечего останавливать.',
+      },
     }[lang];
-    const reply = hadActive ? strs.stopped : strs.nothing;
+    // Truthful ack: a stopped in-flight turn → "Stopped"; a stopped
+    // background shell → "Stopped the background task"; neither →
+    // "Nothing to stop".
+    const reply = hadActive ? strs.stopped
+      : killedBackgroundShell ? strs.bgStopped
+      : strs.nothing;
     try {
       await tg(bot, 'sendMessage', {
         chat_id: chatId, text: reply,

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/process/channels-bridge-protocol.js

@@ -0,0 +1,168 @@
+/**
+ * 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
+ * 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.
+ *
+ * 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
+ *      _onBridgeMsg or channels-bridge.mjs handleDaemonMessage)
+ *
+ * Validation policy:
+ *   - Daemon side uses `safeParse` and drops malformed messages with a warn
+ *     (downgrades silent corruption into observable log)
+ *   - Bridge side does the same on inbound from daemon
+ *   - All validation happens AFTER hello-handshake auth (the auth gate is
+ *     the first line of defense; schema is the second)
+ */
+
+'use strict';
+
+const { z } = require('zod');
+
+// ─── shared primitives ─────────────────────────────────────────────
+
+const NonEmptyString = z.string().min(1);
+const OptionalString = z.string().optional();
+const ToolCallId     = z.string().min(1);
+const RequestId      = z.string().min(1);
+const TurnId         = z.string().min(1);
+
+// ─── bridge → daemon ───────────────────────────────────────────────
+
+const HelloSchema = z.object({
+  kind: z.literal('hello'),
+  session_key: NonEmptyString,
+  secret:      NonEmptyString,
+}).passthrough();
+
+const SessionInitSchema = z.object({
+  kind: z.literal('session_init'),
+  claude_session_id: z.string(),   // may be empty if claude generated one before bridge sees it
+}).passthrough();
+
+const ToolCallMessageSchema = z.object({
+  kind: z.literal('tool'),
+  session: NonEmptyString,
+  tool_call_id: ToolCallId,
+  name: z.enum(['reply', 'react', 'edit_message']),
+  args: z.object({}).passthrough(),
+}).passthrough();
+
+const PermRequestMessageSchema = z.object({
+  kind: z.literal('perm_req'),
+  session: NonEmptyString,
+  request_id: RequestId,
+  tool_name: NonEmptyString,
+  description: z.string(),
+  input_preview: z.string(),
+}).passthrough();
+
+const PongMessageSchema = z.object({
+  kind: z.literal('pong'),
+}).passthrough();
+
+const AnyBridgeToDaemonMessage = z.discriminatedUnion('kind', [
+  HelloSchema,
+  SessionInitSchema,
+  ToolCallMessageSchema,
+  PermRequestMessageSchema,
+  PongMessageSchema,
+]);
+
+// ─── daemon → bridge ───────────────────────────────────────────────
+
+const HelloAckSchema = z.object({
+  kind: z.literal('hello_ack'),
+}).passthrough();
+
+const HelloRejectSchema = z.object({
+  kind: z.literal('hello_reject'),
+  reason: z.string().optional(),
+}).passthrough();
+
+const UserMessageSchema = z.object({
+  kind: z.literal('user_msg'),
+  text: z.string(),
+  chat_id: z.union([z.string(), z.number()]).optional(),
+  user:    OptionalString,
+  msg_id:  z.union([z.string(), z.number()]).optional(),
+  turn_id: OptionalString,
+}).passthrough();
+
+const PermVerdictMessageSchema = z.object({
+  kind: z.literal('perm_verdict'),
+  request_id: RequestId,
+  behavior: z.enum(['allow', 'deny']),
+}).passthrough();
+
+const ToolAckMessageSchema = z.object({
+  kind: z.literal('tool_ack'),
+  tool_call_id: ToolCallId,
+  ok: z.boolean(),
+  error: z.string().optional(),
+}).passthrough();
+
+const PingMessageSchema = z.object({
+  kind: z.literal('ping'),
+}).passthrough();
+
+const AnyDaemonToBridgeMessage = z.discriminatedUnion('kind', [
+  HelloAckSchema,
+  HelloRejectSchema,
+  UserMessageSchema,
+  PermVerdictMessageSchema,
+  ToolAckMessageSchema,
+  PingMessageSchema,
+]);
+
+// ─── helpers ──────────────────────────────────────────────────────
+
+/**
+ * Parse + validate a bridge → daemon message. Returns
+ * {ok:true, msg} on success or {ok:false, error} on failure.
+ *
+ * @param {unknown} raw — already JSON.parsed object
+ * @returns {{ok: true, msg: object}|{ok: false, error: string}}
+ */
+function parseBridgeToDaemonMessage(raw) {
+  const r = AnyBridgeToDaemonMessage.safeParse(raw);
+  if (r.success) return { ok: true, msg: r.data };
+  return { ok: false, error: zodErrorBrief(r.error, raw?.kind) };
+}
+
+function parseDaemonToBridgeMessage(raw) {
+  const r = AnyDaemonToBridgeMessage.safeParse(raw);
+  if (r.success) return { ok: true, msg: r.data };
+  return { ok: false, error: zodErrorBrief(r.error, raw?.kind) };
+}
+
+function zodErrorBrief(err, kindHint) {
+  const issues = (err?.issues || []).slice(0, 3).map(i => `${i.path.join('.')}: ${i.message}`);
+  return `kind=${kindHint || '?'} — ${issues.join('; ') || 'unknown'}`;
+}
+
+module.exports = {
+  // schemas (exported for tests + downstream consumers)
+  HelloSchema,
+  SessionInitSchema,
+  ToolCallMessageSchema,
+  PermRequestMessageSchema,
+  PongMessageSchema,
+  AnyBridgeToDaemonMessage,
+  HelloAckSchema,
+  HelloRejectSchema,
+  UserMessageSchema,
+  PermVerdictMessageSchema,
+  ToolAckMessageSchema,
+  PingMessageSchema,
+  AnyDaemonToBridgeMessage,
+  // helpers
+  parseBridgeToDaemonMessage,
+  parseDaemonToBridgeMessage,
+};