polygram 0.8.0 → 0.9.0-rc.2

package/lib/pm-interface.js

@@ -1,19 +1,23 @@
 /**
  * Canonical Pm interface (JSDoc typedef).
  *
- * Both `lib/process-manager.js` (CLI pm) and `lib/process-manager-sdk.js`
- * (SDK pm) implement this. `lib/pm-router.js`'s `createPmRouter()`
- * forwards calls to one or the other based on per-chat policy.
+ * Implemented by `lib/sdk/process-manager.js` (the only pm impl
+ * post-0.9.0). `lib/sdk/router.js`'s `createPmRouter()` wraps the
+ * pm and is currently an identity passthrough — kept as a forward-
+ * compat seam for future alternate pm impls (a pi-agent-core
+ * adapter, a synthetic test pm). When that lands, the router
+ * becomes the per-chat dispatch layer again; this interface stays
+ * the contract.
  *
- * Optional methods are marked `?` — the router exposes them too but
- * returns documented sentinels when the routed pm doesn't implement
- * them. Sites that need to feature-detect should call
- * `pm.pickFor(sessionKey)` and probe `typeof X === 'function'` on
- * the returned pm instance, not on the router.
+ * Optional methods are marked `?`. SDK pm currently exposes ALL
+ * of them, so post-0.9.0 polygram.js can call them directly
+ * without `typeof === 'function'` guards. Future alternate impls
+ * may opt out of an optional method; if they do, callers will
+ * need to feature-detect at the call site.
  *
  * @typedef {object} PmEntry
- *   The shape pm.get(sessionKey) returns. Different pms decorate it
- *   with their own internal fields; only the documented fields below
+ *   The shape pm.get(sessionKey) returns. The pm impl decorates it
+ *   with its own internal fields; only the documented fields below
  *   are part of the public contract.
  * @property {string} sessionKey
  * @property {string|null} chatId
@@ -45,16 +49,15 @@
  *
  * @typedef {object} PmSpawnContext
  *   What polygram passes to spawnFn(sessionKey, ctx). Internal to
- *   each pm but documented here so callers know what's available.
+ *   the pm but documented here so callers know what's available.
  * @property {string|null} chatId
  * @property {string|null} threadId
  * @property {string} label
  *
  * @typedef {object} Pm
- *   The unified ProcessManager interface. Both CLI and SDK pm
- *   implement these; the router forwards.
+ *   The unified ProcessManager interface.
  *
- *   Required (every pm has these):
+ *   Required:
  * @property {(sessionKey: string) => boolean} has
  * @property {(sessionKey: string) => PmEntry|null} get
  * @property {(sessionKey: string, ctx: PmSpawnContext) => Promise<PmEntry>} getOrSpawn
@@ -65,30 +68,25 @@
  * @property {() => Promise<void>} shutdown
  *   — graceful daemon-wide drain + close.
  *
- *   Optional (only one of the two pms implements these — feature-detect):
+ *   Optional (SDK pm exposes all of these; future alt impls may not):
  * @property {((sessionKey: string, text: string, opts?: object) => boolean)=} steer
- *   — SDK pm only (rc.9 priority='now' direct push, opt-in shouldQuery).
+ *   — priority='now' direct push, opt-in shouldQuery.
  * @property {((sessionKey: string, opts: {content: string, priority?: 'now'|'next'|'later', shouldQuery?: boolean, parent_tool_use_id?: string|null}) => boolean)=} injectUserMessage
- *   — SDK pm only (rc.42 native autosteer / queue via SDKUserMessage
- *     priority hint). Returns false on CLI pm (no inputController
- *     surface) or when sessionKey not found.
+ *   — native autosteer / queue via SDKUserMessage priority hint.
+ *     Returns false when sessionKey not found.
  * @property {((sessionKey: string, model: string) => Promise<boolean>)=} setModel
- *   — SDK pm only (Query.setModel live).
+ *   — Query.setModel live (no respawn).
  * @property {((sessionKey: string, settings: {effortLevel?: string}) => Promise<boolean>)=} applyFlagSettings
- *   — SDK pm only (Query.applyFlagSettings live).
+ *   — Query.applyFlagSettings live (no respawn).
  * @property {((sessionKey: string, mode: string) => Promise<boolean>)=} setPermissionMode
- *   — SDK pm only.
- * @property {((sessionKey: string, reason?: string) => {killed: boolean, queued: number})=} requestRespawn
- *   — CLI pm only (drain pending queue then kill; respawn on next send).
  * @property {((sessionKey: string, errCode: string) => number)=} drainQueue
- *   — SDK pm only (reject all queued pendings with errCode).
+ *   — reject all queued pendings with errCode.
  * @property {((sessionKey: string) => Promise<void>)=} interrupt
- *   — SDK pm only (Query.interrupt — non-destructive).
+ *   — Query.interrupt (non-destructive — preserves session for resume).
  * @property {((sessionKey: string, opts?: {reason?: string}) => Promise<{closed: boolean, drainedPendings: number}>)=} resetSession
- *   — SDK pm only (close Query + clear sessionId from DB).
+ *   — close Query + clear sessionId from DB.
  *
- *   Lifecycle introspection (for tests / debugging — not required
- *   to be present, but both current pms expose them):
+ *   Lifecycle introspection (for tests / debugging):
  * @property {() => string[]=} keys      — sessionKey list
  * @property {() => number=} size        — number of live sessions
  */

package/lib/sdk/build-options.js

@@ -0,0 +1,177 @@
+/**
+ * Factory for the SDK pm's spawn `Options` builder.
+ *
+ * polygram.js wires this at boot via createBuildSdkOptions(deps);
+ * the returned function is what gets passed to ProcessManagerSdk
+ * as `spawnFn`. Per-call, it composes the SdkOptions object the SDK
+ * needs: model + effort + cwd + permissionMode +
+ * canUseTool wiring + agent overlay + per-topic overrides + env
+ * shadow + appended display hint.
+ *
+ * Why a factory instead of a top-level function: buildSdkOptions
+ * needs polygram-runtime context (config, botName, childHome,
+ * makeCanUseTool, logEvent, agentLoader). Passing them via
+ * factory closure keeps the per-call signature `(sessionKey, ctx)`
+ * — the shape pm-sdk's spawnFn contract requires.
+ *
+ * Per v4 plan §6.5.7 — explicit env enumeration (Options.env is
+ * SHADOW per Phase 0 gate 33), bypassPermissions +
+ * allowDangerouslySkipPermissions both set for forward-compat,
+ * agent-loader composes per-chat agent into systemPrompt + skills +
+ * mcpServers, optional resume sessionId for continuity.
+ */
+
+'use strict';
+
+const agentLoader = require('../agents/loader');
+const { getTopicConfig } = require('../session-key');
+const { appendDisplayHint } = require('../telegram/display-hint');
+
+// Env: SHADOW semantics — must enumerate every var the spawned
+// worker is allowed to see. Anything else is dropped.
+const CHILD_ENV_ALLOWLIST = new Set([
+  'PATH', 'HOME', 'USER', 'LOGNAME', 'SHELL', 'TERM', 'COLORTERM',
+  'TMPDIR', 'TMP', 'TEMP', 'TZ', 'LANG', 'PWD', 'SHLVL',
+]);
+const CHILD_ENV_PREFIXES = ['LC_', 'NODE_', 'CLAUDE_', 'ANTHROPIC_'];
+
+function filterEnv(src) {
+  const out = {};
+  for (const [k, v] of Object.entries(src)) {
+    if (CHILD_ENV_ALLOWLIST.has(k) || CHILD_ENV_PREFIXES.some((p) => k.startsWith(p))) {
+      out[k] = v;
+    }
+  }
+  return out;
+}
+
+/**
+ * @param {object} deps
+ * @param {object} deps.config             — runtime config object (config.bot, config.chats, config.defaults)
+ * @param {string} deps.botName            — current bot's name
+ * @param {string} deps.childHome          — HOME passed to spawned child
+ * @param {(sessionKey: string) => Function} deps.makeCanUseTool  — closure that builds canUseTool callbacks
+ * @param {(kind: string, detail: object) => void} deps.logEvent  — bound to db
+ * @param {object} [deps.logger=console]
+ * @param {object} [deps.processEnv=process.env]  — overridable for tests
+ * @returns {(sessionKey: string, ctx: object) => object}  spawnFn
+ */
+function createBuildSdkOptions({
+  config,
+  botName,
+  childHome,
+  makeCanUseTool,
+  logEvent,
+  logger = console,
+  processEnv = process.env,
+} = {}) {
+
+  return function buildSdkOptions(sessionKey, ctx) {
+    const { chatConfig, existingSessionId, label, chatId, threadId } = ctx;
+
+    // rc.48: per-topic config overrides. Per-topic agent / cwd /
+    // permissionMode take precedence over chat-level config when
+    // isolateTopics is true (each topic has its own SDK Query).
+    const topicConfig = getTopicConfig(chatConfig, threadId);
+    const effectiveAgent = topicConfig.agent || chatConfig.agent;
+
+    // Per-chat agent: load + compose. Failure is non-fatal — chat
+    // falls back to defaults; the failure is logged for ops.
+    let agentBundle = null;
+    if (effectiveAgent) {
+      try {
+        agentBundle = agentLoader.loadAgent(effectiveAgent, {
+          homeDir: childHome,
+          cwd: topicConfig.cwd || chatConfig.cwd,
+          logger,
+        });
+      } catch (err) {
+        logger.error?.(`[${label}] agent-loader: ${err.message}`);
+        logEvent('agent-load-failed', {
+          chat_id: chatId, agent: effectiveAgent, error: err.message,
+          topic: threadId || null,
+        });
+      }
+    }
+
+    const effectiveModel = topicConfig.model || chatConfig.model;
+    const effectiveEffort = topicConfig.effort || chatConfig.effort;
+    const agentSuffix = effectiveAgent && effectiveAgent !== chatConfig.agent
+      ? ` agent=${effectiveAgent}` : '';
+    logger.log?.(`[${label}] Spawning SDK Query (${effectiveModel}/${effectiveEffort}${agentSuffix})`);
+
+    // Env scrub: SHADOW. Pass the bot's per-call additions on top.
+    const botConfig = config.bot || {};
+    const childEnv = filterEnv(processEnv);
+    childEnv.HOME = childHome;
+    childEnv.CLAUDE_CHANNEL_BOT = botName;
+    // 0.9.0: gated behind explicit opt-in. Pre-cleanup, the IPC secret
+    // was unconditionally exported so the deleted bin/approval-hook.js
+    // could authenticate; with the hook gone, the only IPC consumers
+    // are external scripts (cron-driven sends) running in their own
+    // processes with their own access to /tmp/polygram-<bot>.secret.
+    if (botConfig.exposeIpcSecretToChildren && processEnv.POLYGRAM_IPC_SECRET) {
+      childEnv.POLYGRAM_IPC_SECRET = processEnv.POLYGRAM_IPC_SECRET;
+    }
+    if (botConfig.needsToken) {
+      childEnv.TELEGRAM_BOT_TOKEN = botConfig.token || '';
+    }
+
+    // canUseTool: in-process approval flow. Wire up only when
+    // approvals.gatedTools is configured for this bot — otherwise
+    // leave canUseTool unset and rely on bypassPermissions.
+    const apprCfg = config.bot?.approvals;
+    const useCanUseTool = apprCfg && apprCfg.adminChatId
+      && Array.isArray(apprCfg.gatedTools) && apprCfg.gatedTools.length > 0;
+
+    const baseOpts = {
+      model: chatConfig.model || config.defaults.model,
+      effort: chatConfig.effort || config.defaults.effort,
+      cwd: chatConfig.cwd,
+      env: childEnv,
+      permissionMode: useCanUseTool ? 'default' : 'bypassPermissions',
+      allowDangerouslySkipPermissions: !useCanUseTool,
+      ...(useCanUseTool && { canUseTool: makeCanUseTool(sessionKey) }),
+      hooks: {},
+      executable: 'node',
+      ...(existingSessionId && { resume: existingSessionId }),
+      ...(processEnv.POLYGRAM_CLAUDE_BIN && {
+        pathToClaudeCodeExecutable: processEnv.POLYGRAM_CLAUDE_BIN,
+      }),
+    };
+
+    // agent-loader precedence: topicConfig > chatConfig > agent > defaults.
+    const composed = agentLoader.composeSdkOptions(
+      {
+        model: chatConfig.model,
+        effort: chatConfig.effort,
+        cwd: chatConfig.cwd,
+        ...(chatConfig.thinking && { thinking: chatConfig.thinking }),
+      },
+      agentBundle,
+      baseOpts,
+      topicConfig,
+    );
+
+    // rc.48: keep permissionMode + allowDangerouslySkipPermissions
+    // consistent. If a topic flipped permissionMode away from
+    // 'bypassPermissions', also disable the skip flag.
+    if (composed.permissionMode && composed.permissionMode !== 'bypassPermissions') {
+      composed.allowDangerouslySkipPermissions = false;
+    }
+
+    // Append polygram's display constraints to the systemPrompt —
+    // infrastructure-layer hint, not agent business logic.
+    composed.systemPrompt = appendDisplayHint(composed.systemPrompt);
+    return composed;
+  };
+}
+
+module.exports = {
+  createBuildSdkOptions,
+  // Exposed for tests + adjacent extractions that need the same env
+  // discipline (e.g. lib/sdk/callbacks.js when it ships).
+  filterEnv,
+  CHILD_ENV_ALLOWLIST,
+  CHILD_ENV_PREFIXES,
+};

package/lib/sdk/callbacks.js

@@ -0,0 +1,213 @@
+/**
+ * Factory for the SDK pm's lifecycle callbacks.
+ *
+ * polygram.js wires this at boot via createSdkCallbacks(deps); the
+ * returned object is spread into ProcessManagerSdk's constructor as
+ * `{ onInit, onClose, onStreamChunk, onToolUse,
+ *    onAssistantMessageStart, onAutonomousAssistantMessage,
+ *    onCompactBoundary }`.
+ *
+ * Each callback is a thin glue layer: pm-sdk emits a typed event,
+ * polygram's callback decides what to persist (db / events) and
+ * what to surface to the user (telegram).
+ *
+ * Why factory: callbacks need polygram-runtime context (db, config,
+ * bot, BOT_NAME, tg, logEvent, dbWrite, classifyToolName, announce,
+ * shouldAnnounce, contextHintShown, extractAssistantText, getChatIdFromKey,
+ * getThreadIdFromKey). Closing over them at boot keeps each callback's
+ * runtime signature compatible with pm-sdk's contract.
+ */
+
+'use strict';
+
+function createSdkCallbacks({
+  db,
+  dbWrite,
+  config,
+  bot,
+  botName,
+  tg,
+  logEvent,
+  classifyToolName,
+  announce,
+  shouldAnnounce,
+  contextHintShown,
+  extractAssistantText,
+  getChatIdFromKey,
+  getThreadIdFromKey,
+  logger = console,
+} = {}) {
+  return {
+    onInit: (sessionKey, event, entry) => {
+      dbWrite(() => db.upsertSession({
+        session_key: sessionKey,
+        chat_id: entry.chatId,
+        thread_id: entry.threadId,
+        claude_session_id: event.session_id,
+        agent: config.chats[entry.chatId]?.agent || null,
+        cwd: config.chats[entry.chatId]?.cwd || null,
+        model: config.chats[entry.chatId]?.model || null,
+        effort: config.chats[entry.chatId]?.effort || null,
+      }), `upsert session ${sessionKey}`);
+    },
+
+    onClose: (sessionKey, code, entry) => {
+      logger.log?.(`[${entry.label}] Process exited (code ${code})`);
+      logEvent('process-close', { chat_id: entry.chatId, session_key: sessionKey, code });
+    },
+
+    onStreamChunk: (sessionKey, partial, entry) => {
+      // Route to the head pending's per-turn streamer. In the
+      // concurrent-pending model, only the HEAD is the turn Claude
+      // is actively emitting events for.
+      const head = entry.pendingQueue?.[0];
+      const s = head?.context?.streamer;
+      if (s) s.onChunk(partial).catch(() => {});
+      // Heartbeat the reactor so long text generation doesn't trip
+      // the 10s STALL → 🥱 / 30s TIMEOUT → 😨 promotion.
+      const r = head?.context?.reactor;
+      if (r && typeof r.heartbeat === 'function') r.heartbeat();
+    },
+
+    onToolUse: (sessionKey, toolName, entry) => {
+      const head = entry.pendingQueue?.[0];
+      const r = head?.context?.reactor;
+      if (r) r.setState(classifyToolName(toolName));
+      // Subagent announce: when Claude uses Task to spawn a subagent,
+      // post a brief informational message. Per-chat 30s debounce
+      // prevents announce-storms in tool-heavy turns.
+      const chatCfg = config.chats[entry.chatId] || {};
+      const optOut = chatCfg.announceSubagents != null
+        ? chatCfg.announceSubagents === false
+        : config.bot?.announceSubagents === false;
+      if (toolName === 'Task' && !optOut) {
+        if (shouldAnnounce(entry.chatId)) {
+          announce({
+            send: (b, method, params, m) => tg(b, method, params, m),
+            bot, chatId: entry.chatId,
+            threadId: head?.context?.threadId ?? null,
+            text: '🤖 Spawning subagent…',
+            meta: { botName, source: 'subagent-announce' },
+            logger: { error: (m) => logger.error?.(`[${entry.label}] ${m}`) },
+          });
+        }
+      }
+    },
+
+    // Each new top-level assistant message gets its own bubble.
+    // When Claude emits text, then tool_use, then more text in a NEW
+    // assistant message, the previous bubble's content stays visible
+    // as a "thinking out loud" intermediate; the new message starts
+    // fresh below.
+    onAssistantMessageStart: (sessionKey, entry) => {
+      const head = entry.pendingQueue?.[0];
+      const s = head?.context?.streamer;
+      if (s) s.forceNewMessage();
+      // Heartbeat at every assistant-message boundary too. A long
+      // thinking phase (effort=high, 30+s before first chunk) doesn't
+      // fire onStreamChunk; without this, the freeze timer could
+      // expire while the model is "still thinking but about to speak".
+      const r = head?.context?.reactor;
+      if (r && typeof r.heartbeat === 'function') r.heartbeat();
+    },
+
+    // rc.47: autonomous wakeup forwarding. Fires when an SDK
+    // assistant message arrives with no head pending — typical
+    // ScheduleWakeup case where the agent self-fires without an
+    // inbound user message. Best-effort send: failures are logged
+    // but don't propagate.
+    onAutonomousAssistantMessage: (sessionKey, msg /* , entry */) => {
+      try {
+        const text = extractAssistantText(msg);
+        if (!text) return;
+        const chatId = getChatIdFromKey(sessionKey);
+        const threadIdRaw = getThreadIdFromKey(sessionKey);
+        const threadId = threadIdRaw ? parseInt(threadIdRaw, 10) : null;
+        if (!bot) {
+          logger.error?.(`[${botName}] autonomous wakeup: bot not ready, dropping ${text.length} chars`);
+          return;
+        }
+        const params = {
+          chat_id: chatId,
+          text,
+          ...(Number.isInteger(threadId) && { message_thread_id: threadId }),
+        };
+        // Don't await — keep the pm-sdk event loop unblocked.
+        tg(bot, 'sendMessage', params,
+          { source: 'autonomous-wakeup', botName }).catch((err) => {
+            logger.error?.(`[${botName}] autonomous wakeup send failed: ${err.message}`);
+          });
+        logEvent('autonomous-wakeup-message', {
+          chat_id: chatId,
+          session_key: sessionKey,
+          thread_id: threadIdRaw,
+          text_len: text.length,
+        });
+      } catch (err) {
+        logger.error?.(`[${botName}] autonomous wakeup handler: ${err.message}`);
+      }
+    },
+
+    // SDK auto-compaction observability. Fires when SDK emits
+    // SDKCompactBoundaryMessage. Surfaces a quiet system status note
+    // to the chat so the user knows the bot is busy reorganising
+    // context. ON by default; set per-chat or per-bot
+    // `announceCompact: false` to silence.
+    onCompactBoundary: async (sessionKey, msg, entry) => {
+      // Clear the contextHint once-per-cycle gate. After compaction,
+      // context drops below threshold; if it climbs back up the next
+      // cycle should fire a fresh hint.
+      contextHintShown.delete(sessionKey);
+
+      const chatCfg = config.chats[entry.chatId] || {};
+      const optOut = chatCfg.announceCompact != null
+        ? chatCfg.announceCompact === false
+        : config.bot?.announceCompact === false;
+      if (optOut) return;
+      const threadId = entry.threadId || undefined;
+
+      // Word the message based on what actually happened. Pre-rc.62
+      // every event read as "💭 Catching up…" — but compact_boundary
+      // fires AFTER compaction completes, leaving users confused
+      // when nothing followed. Now: distinguish manual vs auto and
+      // surface the compression ratio.
+      const meta = msg?.compact_metadata || {};
+      const trigger = meta.trigger;        // 'manual' | 'auto'
+      const preTokens = meta.pre_tokens;
+      const postTokens = meta.post_tokens;
+      const durationMs = meta.duration_ms;
+      const fmtTok = (n) => {
+        if (n == null) return null;
+        if (n >= 1000) return `${(n / 1000).toFixed(1)}k`;
+        return String(n);
+      };
+      const ratio = (preTokens && postTokens)
+        ? `${fmtTok(preTokens)} → ${fmtTok(postTokens)}` : null;
+      const duration = durationMs ? `${(durationMs / 1000).toFixed(1)}s` : null;
+      const stats = [ratio, duration].filter(Boolean).join(', ');
+
+      let text;
+      if (trigger === 'manual') {
+        text = stats
+          ? `✅ Compacted (${stats}). Ready for your next message.`
+          : `✅ Compacted. Ready for your next message.`;
+      } else {
+        text = stats
+          ? `💭 Auto-compacted (${stats}). Continuing…`
+          : `💭 Auto-compacted. Continuing…`;
+      }
+
+      try {
+        await tg(bot, 'sendMessage', {
+          chat_id: entry.chatId,
+          text,
+          ...(threadId ? { message_thread_id: threadId } : {}),
+        }, { source: 'compact-boundary', botName });
+      } catch (err) {
+        logger.error?.(`[${entry.label}] compact-boundary post: ${err.message}`);
+      }
+    },
+  };
+}
+
+module.exports = { createSdkCallbacks };

package/lib/{process-manager-sdk.js → sdk/process-manager.js}

@@ -1,34 +1,29 @@
 /**
- * SDK-backed ProcessManager — `@anthropic-ai/claude-agent-sdk` Query
- * objects in place of `child_process.spawn('claude', ...)` and
- * stream-json line parsing.
+ * ProcessManager — `@anthropic-ai/claude-agent-sdk` Query objects.
  *
- * Public API matches `lib/process-manager.js` (the CLI version) so
- * polygram.js can swap implementations via env flag (POLYGRAM_USE_SDK=1).
- * Phase 4 deletes the CLI version after Phase 5 soak proves the SDK
- * version stable.
- *
- * Per v4 plan §6.5.7 (buildSdkOptions), §6.6 (ship-breaker
- * mitigations), Phase 0 spike findings (docs/0.8.0-phase0-findings.md).
+ * The canonical pm impl post-0.9.0. Pre-0.9.0 polygram ran a dual-pm
+ * router (CLI subprocess pm + this SDK pm) behind env flags; the CLI
+ * variant was deleted with the rest of the migration safety net once
+ * both bots had soaked on SDK pm. See `lib/pm-interface.js` for the
+ * canonical contract and `docs/0.8.0-sdk-migration-plan.md` for the
+ * migration history.
  *
  * Architecture:
- *   - One Query per active sessionKey, held for the chat lifetime
- *     (Phase 0 gate 1 PASS — long-lived input AsyncIterable works).
+ *   - One Query per active sessionKey, held for the chat lifetime.
  *   - inputController is the writable end of an
  *     AsyncIterable<SDKUserMessage>; pm.send() pushes user messages
  *     onto it; the SDK's streamInput() consumes from the other end.
  *   - iteratePromise is the for-await loop over the Query's
  *     AsyncGenerator output. Wrapped in try/catch (D7 commitment).
  *   - pendingQueue maps N user messages → N SDKResultMessage events
- *     in FIFO order (same as CLI version's stream-json model).
- *   - LRU eviction across the procs Map (cap = DEFAULT_CAP) — same
- *     behaviour as CLI version, with Query.close() instead of
- *     proc.kill().
+ *     in FIFO order.
+ *   - LRU eviction across the procs Map (cap = DEFAULT_CAP) via
+ *     Query.close().
  *
- * Decisions encoded:
+ * Decisions encoded (v4 plan):
  *   D1 streaming: subscribe to SDKAssistantMessage (cumulative)
  *   D2 long-lived Query per chat
- *   D3 /effort via applyFlagSettings — DELETE requestRespawn
+ *   D3 /effort via applyFlagSettings (no respawn)
  *   D5 Options.env SHADOW — buildSdkOptions enumerates everything
  *   D6 Query.close() is fast — 100ms shutdown timeout safe
  *   D7 killChat Promise.allSettled with 5s per-Query timeout
@@ -39,7 +34,7 @@
 'use strict';
 
 const { query } = require('@anthropic-ai/claude-agent-sdk');
-const { isTransientHttpError } = require('./error-classify');
+const { isTransientHttpError } = require('../error/classify');
 
 const DEFAULT_CAP = 10;
 const DEFAULT_QUEUE_CAP = 50;
@@ -169,14 +164,11 @@ function makeInputController({ queueCap = DEFAULT_QUEUE_CAP } = {}) {
 // ─── ProcessManager ────────────────────────────────────────────────
 
 /**
- * @anthropic-ai/claude-agent-sdk-backed ProcessManager. Implements
- * the canonical Pm interface (`lib/pm-interface.js`). Optional
- * methods exposed: `steer`, `setModel`, `applyFlagSettings`,
- * `setPermissionMode`, `drainQueue`, `interrupt`, `resetSession`.
- *
- * Optional methods NOT implemented (CLI pm has this): `requestRespawn`.
- * For mid-session config changes use `applyFlagSettings` (effort)
- * or `setModel`.
+ * @anthropic-ai/claude-agent-sdk-backed ProcessManager. The canonical
+ * pm impl post-0.9.0. Implements the Pm interface
+ * (`lib/pm-interface.js`); optional methods exposed: `steer`,
+ * `setModel`, `applyFlagSettings`, `setPermissionMode`, `drainQueue`,
+ * `interrupt`, `resetSession`.
  *
  * @implements {import('./pm-interface.js').Pm}
  */
@@ -333,7 +325,6 @@ class ProcessManagerSdk {
       inFlight: false,
       lastUsedTs: Date.now(),
       iteratePromise: null,
-      needsRespawn: null,
     };
 
     inputController.onDrop((dropped) => {
@@ -640,9 +631,6 @@ class ProcessManagerSdk {
       if (!entry || entry.closed) {
         return reject(new Error('No process for session'));
       }
-      if (entry.needsRespawn) {
-        return reject(new Error(`Session awaiting respawn (${entry.needsRespawn})`));
-      }
 
       entry.lastUsedTs = Date.now();
 

package/lib/{telegram.js → telegram/api.js}

@@ -26,8 +26,8 @@ const {
   isMessageNotModifiedError,
   isRateLimitError,
   getRetryAfterMs,
-} = require('./telegram-format');
-const { isSafeToRetry, redactBotToken } = require('./net-errors');
+} = require('./format');
+const { isSafeToRetry, redactBotToken } = require('../error/net');
 
 // Topic deletion race: a user can delete a forum topic while a turn is in
 // flight, turning a valid `message_thread_id` into a 404. Telegram's error

package/lib/{telegram-prompt.js → telegram/display-hint.js}

@@ -97,22 +97,8 @@ function appendDisplayHint(systemPromptOpt, hint = POLYGRAM_DISPLAY_HINT) {
   return systemPromptOpt;
 }
 
-/**
- * For the CLI pm (`claude -p ...`), the equivalent of an appended
- * system prompt is the `--append-system-prompt <text>` flag. This
- * helper returns the args the CLI pm should add to its argv.
- *
- * @param {string} [hint] — override (tests)
- * @returns {string[]}    — argv tail, e.g. ['--append-system-prompt', '...']
- */
-function appendDisplayHintCliArgs(hint = POLYGRAM_DISPLAY_HINT) {
-  if (!hint) return [];
-  return ['--append-system-prompt', hint];
-}
-
 module.exports = {
   POLYGRAM_DISPLAY_HINT,
   TELEGRAM_TABLE_WIDTH_BUDGET,
   appendDisplayHint,
-  appendDisplayHintCliArgs,
 };

package/lib/{stream-reply.js → telegram/streamer.js}

@@ -211,10 +211,10 @@ function createStreamer({
   }
 
   // Reset bubble state so the next onChunk creates a NEW message.
-  // Used by `onAssistantMessageStart` in process-manager.js when Claude
-  // emits a new top-level assistant message mid-turn (post tool-result):
-  // we want it in its own bubble below the previous one, not appended
-  // via editMessageText to the original.
+  // Used by `onAssistantMessageStart` in lib/process-manager-sdk.js
+  // when Claude emits a new top-level assistant message mid-turn
+  // (post tool-result): we want it in its own bubble below the
+  // previous one, not appended via editMessageText to the original.
   //
   // rc.44: by default, the previous bubble is PRESERVED (not archived
   // for end-of-turn deletion). Intermediate text segments are

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "polygram",
-  "version": "0.8.0",
+  "version": "0.9.0-rc.2",
   "description": "Telegram daemon for Claude Code that preserves the OpenClaw per-chat session model. Migration path for OpenClaw users moving to Claude Code.",
-  "main": "lib/ipc-client.js",
+  "main": "lib/ipc/client.js",
   "bin": {
     "polygram": "polygram.js",
     "polygram-split-db": "scripts/split-db.js",
@@ -11,7 +11,6 @@
   },
   "files": [
     "polygram.js",
-    "bin/",
     "lib/",
     "migrations/",
     "scripts/split-db.js",