polygram 0.38.1 → 0.38.2

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "polygram",
-  "version": "0.38.1",
+  "version": "0.38.2",
   "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/lib/db.js

@@ -462,6 +462,25 @@ function wrap(db) {
     ORDER BY id DESC LIMIT 1
   `);
 
+  const getForegroundCanaryTargetStmt = db.prepare(`
+    SELECT message.id AS message_id,
+           message.chat_id,
+           message.thread_id,
+           selection.telegram_message_id,
+           message.handler_status,
+           selection.session_key,
+           selection.provider
+      FROM messages AS message
+      JOIN inbound_runtime_selections AS selection
+        ON selection.bot_name = message.bot_name
+       AND selection.telegram_chat_id = message.chat_id
+       AND selection.telegram_message_id = ?
+     WHERE message.direction = 'in'
+       AND message.bot_name = ?
+       AND message.chat_id = ?
+       AND message.msg_id = ?
+  `);
+
   const setMessageTextStmt = db.prepare(`
     UPDATE messages
        SET text = @text
@@ -4698,6 +4717,32 @@ function wrap(db) {
       `).get(messageId);
     },
 
+    getForegroundCanaryTarget({ botName, chatId, telegramMessageId }) {
+      const messageIdText = String(telegramMessageId);
+      const messageId = Number(messageIdText);
+      if (
+        !Number.isSafeInteger(messageId)
+        || messageId <= 0
+        || String(messageId) !== messageIdText
+      ) return null;
+      const row = getForegroundCanaryTargetStmt.get(
+        messageIdText,
+        String(botName),
+        String(chatId),
+        messageId,
+      );
+      if (!row) return null;
+      return {
+        messageId: row.message_id,
+        chatId: String(row.chat_id),
+        threadId: row.thread_id == null ? null : String(row.thread_id),
+        telegramMessageId: row.telegram_message_id,
+        sessionKey: row.session_key,
+        provider: row.provider,
+        handlerStatus: row.handler_status,
+      };
+    },
+
     listFailedAttachments({ since = null, limit = 100 } = {}) {
       const cutoff = since ?? Date.now() - 24 * 60 * 60 * 1000;
       return db.prepare(`

package/lib/handlers/dispatcher.js

@@ -77,6 +77,7 @@ function createDispatcher({
   // Per-session in-flight handler count.
   const inFlightHandlers = new Map();
   const activeHandlers = new Set();
+  const activeHandlerTargets = new Set();
 
   function trackTask(task) {
     activeHandlers.add(task);
@@ -265,6 +266,15 @@ function createDispatcher({
   }
 
   function dispatchHandleMessage(sessionKey, chatId, msg, bot) {
+    const activeHandlerTarget = Object.freeze({
+      sessionKey: String(sessionKey),
+      chatId: String(chatId),
+      threadId: msg?.message_thread_id == null
+        ? null
+        : String(msg.message_thread_id),
+      telegramMessageId: String(msg?.message_id),
+    });
+    activeHandlerTargets.add(activeHandlerTarget);
     const count = (inFlightHandlers.get(sessionKey) || 0) + 1;
     inFlightHandlers.set(sessionKey, count);
     const warnAt = queueWarnThreshold();
@@ -562,6 +572,7 @@ function createDispatcher({
         }
       }
     }).finally(() => {
+      activeHandlerTargets.delete(activeHandlerTarget);
       const n = (inFlightHandlers.get(sessionKey) || 1) - 1;
       if (n <= 0) inFlightHandlers.delete(sessionKey);
       else inFlightHandlers.set(sessionKey, n);
@@ -575,6 +586,8 @@ function createDispatcher({
     errorReplyText,
     queueWarnThreshold,
     inFlightHandlers,  // exposed so polygram.js can introspect for shutdown drain
+    getActiveHandlerCount: () => activeHandlers.size,
+    getActiveHandlerTargets: () => [...activeHandlerTargets],
     awaitSettlement,
     trackTask,
   };

package/lib/ipc/handlers.js

@@ -22,6 +22,7 @@ const {
  *   reload, so a value bound at wiring time can go stale.
  * @param {(req) => any} opts.handleSendOverIpc
  * @param {(req) => any} opts.requestDeployRestart
+ * @param {(req) => any} opts.requestForegroundCanaryTarget
  * @param {() => any} opts.inspectCleanRestartQualification
  */
 function createIpcHandlers({
@@ -30,6 +31,7 @@ function createIpcHandlers({
   getInFlightHandlers,
   handleSendOverIpc,
   requestDeployRestart,
+  requestForegroundCanaryTarget,
   inspectCleanRestartQualification,
 } = {}) {
   return {
@@ -46,6 +48,8 @@ function createIpcHandlers({
 
     deploy_restart: (req) => requestDeployRestart(req),
 
+    foreground_canary_target: (req) => requestForegroundCanaryTarget(req),
+
     clean_restart_qualification: async (req) => {
       assertClosedQualificationRequest(req);
       let observation = null;

package/lib/ops/clean-restart-qualification.js

@@ -130,6 +130,7 @@ function normalizeDeployQualificationExpectation(request) {
   const requestKeys = Object.keys(request);
   const allowedRequestKeys = new Set([
     'op', 'id', 'secret', 'qualification_expectation',
+    'foreground_expectation',
   ]);
   const hasUnknownRequestField = requestKeys.some(
     (key) => !allowedRequestKeys.has(key),

package/lib/ops/deploy-restart-handler.js

@@ -0,0 +1,111 @@
+'use strict';
+
+const {
+  requireRestartRequestId,
+} = require('../ipc/restart-request-id');
+const {
+  normalizeDeployQualificationExpectation,
+} = require('./clean-restart-qualification');
+const {
+  normalizeDeployForegroundExpectation,
+} = require('./foreground-canary-target');
+
+function createDeployRestartHandler({
+  getIsShuttingDown,
+  getPid,
+  foregroundCanaryAuthorizer,
+  persistForegroundCanaryAuthorization,
+  shutdown,
+  logger = console,
+} = {}) {
+  if (typeof getIsShuttingDown !== 'function') {
+    throw new TypeError('deploy restart shutdown-state reader is required');
+  }
+  if (typeof getPid !== 'function') {
+    throw new TypeError('deploy restart PID reader is required');
+  }
+  if (typeof persistForegroundCanaryAuthorization !== 'function') {
+    throw new TypeError('foreground canary authorization persistence is required');
+  }
+  if (typeof shutdown !== 'function') {
+    throw new TypeError('deploy restart shutdown function is required');
+  }
+
+  function rejected(oldPid, restartRequestId, rejectionCode) {
+    return {
+      accepted: false,
+      old_pid: oldPid,
+      restart_request_id: restartRequestId,
+      rejection_code: rejectionCode,
+    };
+  }
+
+  return function requestDeployRestart(request) {
+    const oldPid = getPid();
+    const isForegroundRequest = request != null
+      && typeof request === 'object'
+      && Object.hasOwn(request, 'foreground_expectation');
+    if (getIsShuttingDown() && !isForegroundRequest) {
+      const error = new Error('shutdown already in progress');
+      error.code = 'SHUTDOWN_IN_PROGRESS';
+      throw error;
+    }
+    let restartRequestId;
+    try {
+      restartRequestId = requireRestartRequestId(request?.id);
+    } catch {
+      return rejected(oldPid, null, 'invalid-request');
+    }
+    if (getIsShuttingDown()) {
+      return rejected(oldPid, restartRequestId, 'shutdown-in-progress');
+    }
+
+    const qualificationExpectation = normalizeDeployQualificationExpectation(request);
+    const foregroundExpectation = normalizeDeployForegroundExpectation(request);
+    if (qualificationExpectation === null || foregroundExpectation === null) {
+      return rejected(oldPid, restartRequestId, 'invalid-request');
+    }
+
+    if (foregroundExpectation !== undefined) {
+      if (typeof foregroundCanaryAuthorizer?.authorizeRestart !== 'function') {
+        return rejected(oldPid, restartRequestId, 'target-unavailable');
+      }
+      const authorization = foregroundCanaryAuthorizer.authorizeRestart({
+        requestId: restartRequestId,
+        expectation: foregroundExpectation,
+      });
+      if (!authorization?.accepted) {
+        return rejected(
+          oldPid,
+          restartRequestId,
+          authorization?.rejectionCode || 'target-unavailable',
+        );
+      }
+      try {
+        persistForegroundCanaryAuthorization(authorization.authorizationEvent);
+      } catch {
+        return rejected(
+          oldPid,
+          restartRequestId,
+          'authorization-evidence-unavailable',
+        );
+      }
+    }
+
+    shutdown({
+      continuationAuthorized: true,
+      trigger: 'deploy-ipc',
+      restartRequestId,
+      qualificationExpectation,
+    }).catch((error) => {
+      logger.error?.(`[shutdown] deploy restart failed: ${error.message}`);
+    });
+    return {
+      accepted: true,
+      old_pid: oldPid,
+      restart_request_id: restartRequestId,
+    };
+  };
+}
+
+module.exports = { createDeployRestartHandler };

package/lib/ops/foreground-canary-target.js

@@ -0,0 +1,454 @@
+'use strict';
+
+const {
+  createHash,
+  createHmac,
+  timingSafeEqual,
+} = require('node:crypto');
+const {
+  getSessionKey,
+  getTopicName,
+} = require('../session-key');
+
+const SHA256_RE = /^[a-f0-9]{64}$/;
+const TOKEN_RE = /^[a-f0-9]{64}$/;
+const UUID_RE = /^[a-f0-9]{8}-[a-f0-9]{4}-[1-5][a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/i;
+const PROVIDERS = new Set(['claude', 'codex']);
+const LIVE_HANDLER_STATUSES = new Set(['dispatched', 'processing']);
+const DEPLOY_REQUEST_KEYS = new Set([
+  'op',
+  'id',
+  'secret',
+  'foreground_expectation',
+  'qualification_expectation',
+]);
+const EXPECTATION_KEYS = [
+  'schema_version',
+  'daemon_instance_id',
+  'pid',
+  'provider',
+  'configured_scope_sha256',
+  'target_token',
+];
+const PROBE_KEYS = [
+  'op',
+  'id',
+  'secret',
+  'provider',
+  'configured_scope_sha256',
+];
+
+function isPlainObject(value) {
+  return value != null
+    && typeof value === 'object'
+    && !Array.isArray(value)
+    && Object.getPrototypeOf(value) === Object.prototype;
+}
+
+function hasExactKeys(value, keys) {
+  if (!isPlainObject(value)) return false;
+  const actual = Object.keys(value);
+  return actual.length === keys.length
+    && keys.every((key) => Object.hasOwn(value, key));
+}
+
+function isBoundedString(value, maxBytes = 256) {
+  return typeof value === 'string'
+    && value.length > 0
+    && Buffer.byteLength(value, 'utf8') <= maxBytes
+    && !/[\x00-\x1f\x7f]/.test(value);
+}
+
+function validRequestId(value) {
+  return UUID_RE.test(value ?? '');
+}
+
+function configuredScopeSha256({
+  botName,
+  chatId,
+  threadId,
+  chatName,
+  topicName,
+  isolateTopics,
+} = {}) {
+  return createHash('sha256').update(JSON.stringify([
+    String(botName),
+    String(chatId),
+    threadId == null ? null : String(threadId),
+    String(chatName),
+    topicName == null ? null : String(topicName),
+    isolateTopics === true,
+  ])).digest('hex');
+}
+
+function configuredScopes({ config, botName } = {}) {
+  const scopes = [];
+  for (const [chatId, chatConfig] of Object.entries(config?.chats ?? {})) {
+    if (!chatConfig || typeof chatConfig !== 'object') continue;
+    const base = {
+      botName,
+      chatId: String(chatId),
+      threadId: null,
+      chatName: String(chatConfig.name ?? ''),
+      topicName: null,
+      isolateTopics: chatConfig.isolateTopics === true,
+      sessionKey: getSessionKey(String(chatId), null, chatConfig),
+    };
+    scopes.push(Object.freeze({
+      ...base,
+      digest: configuredScopeSha256(base),
+    }));
+    for (const threadId of Object.keys(chatConfig.topics ?? {})) {
+      const topic = {
+        ...base,
+        threadId: String(threadId),
+        topicName: getTopicName(chatConfig, String(threadId)),
+        sessionKey: getSessionKey(String(chatId), String(threadId), chatConfig),
+      };
+      scopes.push(Object.freeze({
+        ...topic,
+        digest: configuredScopeSha256(topic),
+      }));
+    }
+  }
+  return scopes;
+}
+
+function resolveConfiguredScope({ config, botName, digest } = {}) {
+  if (!SHA256_RE.test(digest ?? '')) return null;
+  const matches = configuredScopes({ config, botName })
+    .filter((scope) => scope.digest === digest);
+  return matches.length === 1 ? matches[0] : null;
+}
+
+function normalizeDeployForegroundExpectation(request) {
+  if (!isPlainObject(request)) return null;
+  const keys = Object.keys(request);
+  const unknown = keys.some((key) => !DEPLOY_REQUEST_KEYS.has(key));
+  const present = Object.hasOwn(request, 'foreground_expectation');
+  if (!present && !unknown) return undefined;
+  if (
+    unknown
+    || request.op !== 'deploy_restart'
+    || !validRequestId(request.id)
+    || !isBoundedString(request.secret, 1024)
+  ) return null;
+
+  const expectation = request.foreground_expectation;
+  if (
+    !hasExactKeys(expectation, EXPECTATION_KEYS)
+    || expectation.schema_version !== 1
+    || !UUID_RE.test(expectation.daemon_instance_id ?? '')
+    || !Number.isSafeInteger(expectation.pid)
+    || expectation.pid <= 0
+    || !PROVIDERS.has(expectation.provider)
+    || !SHA256_RE.test(expectation.configured_scope_sha256 ?? '')
+    || !TOKEN_RE.test(expectation.target_token ?? '')
+  ) {
+    return null;
+  }
+  return Object.freeze({
+    daemonInstanceId: expectation.daemon_instance_id,
+    pid: expectation.pid,
+    provider: expectation.provider,
+    configuredScopeSha256: expectation.configured_scope_sha256,
+    targetToken: expectation.target_token,
+  });
+}
+
+function normalizedActiveTarget(value) {
+  if (!isPlainObject(value)) return null;
+  const sessionKey = value.sessionKey;
+  const chatId = value.chatId;
+  const threadId = value.threadId;
+  const telegramMessageId = value.telegramMessageId;
+  if (
+    !isBoundedString(sessionKey, 512)
+    || !isBoundedString(chatId, 128)
+    || !(threadId === null || isBoundedString(threadId, 128))
+    || !isBoundedString(telegramMessageId, 128)
+  ) return null;
+  return {
+    sessionKey,
+    chatId,
+    threadId,
+    telegramMessageId,
+  };
+}
+
+function normalizedSelectedTarget(value) {
+  if (!isPlainObject(value)) return null;
+  if (
+    !Number.isSafeInteger(value.messageId)
+    || value.messageId <= 0
+    || !isBoundedString(value.chatId, 128)
+    || !(value.threadId === null || isBoundedString(value.threadId, 128))
+    || !isBoundedString(value.telegramMessageId, 128)
+    || !isBoundedString(value.sessionKey, 512)
+    || !PROVIDERS.has(value.provider)
+    || !isBoundedString(value.handlerStatus, 64)
+  ) return null;
+  return {
+    messageId: value.messageId,
+    chatId: value.chatId,
+    threadId: value.threadId,
+    telegramMessageId: value.telegramMessageId,
+    sessionKey: value.sessionKey,
+    provider: value.provider,
+    handlerStatus: value.handlerStatus,
+  };
+}
+
+function sameTarget(left, right) {
+  return left.sessionKey === right.sessionKey
+    && left.chatId === right.chatId
+    && left.threadId === right.threadId
+    && left.telegramMessageId === right.telegramMessageId;
+}
+
+function sameBinding(left, right) {
+  return sameTarget(left, right)
+    && left.messageId === right.messageId
+    && left.provider === right.provider
+    && left.scopeDigest === right.scopeDigest;
+}
+
+function safeTokenEqual(left, right) {
+  if (!TOKEN_RE.test(left ?? '') || !TOKEN_RE.test(right ?? '')) return false;
+  return timingSafeEqual(Buffer.from(left), Buffer.from(right));
+}
+
+function createForegroundCanaryAuthorizer({
+  botName,
+  daemonIdentity,
+  config,
+  tokenSecret,
+  getActiveHandlerCount,
+  getActiveHandlerTargets,
+  getForegroundCanaryTarget,
+  now = Date.now,
+  tokenTtlMs = 300_000,
+  tokenLimit = 64,
+} = {}) {
+  if (!isBoundedString(botName, 128)) {
+    throw new TypeError('foreground canary bot name is required');
+  }
+  if (
+    !isPlainObject(daemonIdentity)
+    || !UUID_RE.test(daemonIdentity.daemon_instance_id ?? '')
+    || !Number.isSafeInteger(daemonIdentity.pid)
+    || daemonIdentity.pid <= 0
+    || !isBoundedString(daemonIdentity.package_version, 128)
+  ) {
+    throw new TypeError('foreground canary daemon identity is invalid');
+  }
+  if (!isBoundedString(tokenSecret, 1024)) {
+    throw new TypeError('foreground canary token secret is required');
+  }
+  if (typeof getActiveHandlerCount !== 'function') {
+    throw new TypeError('foreground canary active-handler count reader is required');
+  }
+  if (typeof getActiveHandlerTargets !== 'function') {
+    throw new TypeError('foreground canary active-handler reader is required');
+  }
+  if (typeof getForegroundCanaryTarget !== 'function') {
+    throw new TypeError('foreground canary database reader is required');
+  }
+  if (!Number.isSafeInteger(tokenTtlMs) || tokenTtlMs <= 0) {
+    throw new TypeError('foreground canary token TTL is invalid');
+  }
+  if (!Number.isSafeInteger(tokenLimit) || tokenLimit <= 0) {
+    throw new TypeError('foreground canary token limit is invalid');
+  }
+
+  const tokens = new Map();
+
+  function reject(rejectionCode) {
+    return { rejectionCode };
+  }
+
+  function inspectLiveTarget({ provider, scopeDigest }) {
+    const scope = resolveConfiguredScope({ config, botName, digest: scopeDigest });
+    if (!scope) return reject('configured-scope-mismatch');
+
+    let activeCount;
+    let active;
+    try {
+      activeCount = getActiveHandlerCount();
+      active = getActiveHandlerTargets();
+    } catch {
+      return reject('target-unavailable');
+    }
+    if (activeCount !== 1 || !Array.isArray(active) || active.length !== 1) {
+      return reject('daemon-busy');
+    }
+    const activeTarget = normalizedActiveTarget(active[0]);
+    if (!activeTarget) return reject('source-mismatch');
+    if (
+      activeTarget.chatId !== scope.chatId
+      || activeTarget.threadId !== scope.threadId
+      || activeTarget.sessionKey !== scope.sessionKey
+    ) {
+      return reject('source-mismatch');
+    }
+
+    let selected;
+    try {
+      selected = normalizedSelectedTarget(getForegroundCanaryTarget({
+        botName,
+        chatId: activeTarget.chatId,
+        telegramMessageId: activeTarget.telegramMessageId,
+      }));
+    } catch {
+      return reject('target-unavailable');
+    }
+    if (!selected) return reject('target-not-live');
+    if (!sameTarget(activeTarget, selected)) return reject('source-mismatch');
+    if (selected.provider !== provider) return reject('provider-mismatch');
+    if (!LIVE_HANDLER_STATUSES.has(selected.handlerStatus)) {
+      return reject('target-not-live');
+    }
+    return {
+      binding: Object.freeze({
+        ...selected,
+        scopeDigest,
+      }),
+    };
+  }
+
+  function probe(request) {
+    if (
+      !hasExactKeys(request, PROBE_KEYS)
+      || request.op !== 'foreground_canary_target'
+      || !validRequestId(request.id)
+      || !isBoundedString(request.secret, 1024)
+      || !PROVIDERS.has(request.provider)
+      || !SHA256_RE.test(request.configured_scope_sha256 ?? '')
+    ) {
+      return {
+        outcome: 'rejected',
+        rejection_code: 'invalid-request',
+      };
+    }
+
+    const issuedAt = now();
+    for (const [requestId, stored] of tokens) {
+      if (issuedAt > stored.expiresAt) tokens.delete(requestId);
+    }
+    if (!tokens.has(request.id) && tokens.size >= tokenLimit) {
+      return {
+        outcome: 'rejected',
+        rejection_code: 'target-unavailable',
+      };
+    }
+
+    const inspected = inspectLiveTarget({
+      provider: request.provider,
+      scopeDigest: request.configured_scope_sha256,
+    });
+    if (!inspected.binding) {
+      return {
+        outcome: 'rejected',
+        rejection_code: inspected.rejectionCode,
+      };
+    }
+
+    const token = createHmac('sha256', tokenSecret).update(JSON.stringify([
+      request.id,
+      daemonIdentity.daemon_instance_id,
+      daemonIdentity.pid,
+      inspected.binding.provider,
+      inspected.binding.scopeDigest,
+      inspected.binding.sessionKey,
+      inspected.binding.messageId,
+      inspected.binding.telegramMessageId,
+      issuedAt,
+    ])).digest('hex');
+    tokens.set(request.id, Object.freeze({
+      token,
+      binding: inspected.binding,
+      expiresAt: issuedAt + tokenTtlMs,
+    }));
+    return {
+      outcome: 'live',
+      bot: botName,
+      daemon_instance_id: daemonIdentity.daemon_instance_id,
+      pid: daemonIdentity.pid,
+      package_version: daemonIdentity.package_version,
+      provider: request.provider,
+      configured_scope_sha256: request.configured_scope_sha256,
+      target_token: token,
+    };
+  }
+
+  function authorizeRestart({ requestId, expectation } = {}) {
+    if (!validRequestId(requestId) || !isPlainObject(expectation)) {
+      return { accepted: false, rejectionCode: 'invalid-request' };
+    }
+    if (
+      expectation.daemonInstanceId !== daemonIdentity.daemon_instance_id
+      || expectation.pid !== daemonIdentity.pid
+    ) {
+      return { accepted: false, rejectionCode: 'daemon-identity-mismatch' };
+    }
+
+    const stored = tokens.get(requestId);
+    if (!stored || !safeTokenEqual(stored.token, expectation.targetToken)) {
+      return { accepted: false, rejectionCode: 'target-token-invalid' };
+    }
+    if (now() > stored.expiresAt) {
+      tokens.delete(requestId);
+      return { accepted: false, rejectionCode: 'target-token-expired' };
+    }
+    if (
+      expectation.provider !== stored.binding.provider
+      || expectation.configuredScopeSha256 !== stored.binding.scopeDigest
+    ) {
+      tokens.delete(requestId);
+      return { accepted: false, rejectionCode: 'target-binding-mismatch' };
+    }
+
+    const inspected = inspectLiveTarget({
+      provider: expectation.provider,
+      scopeDigest: expectation.configuredScopeSha256,
+    });
+    if (!inspected.binding) {
+      tokens.delete(requestId);
+      return { accepted: false, rejectionCode: inspected.rejectionCode };
+    }
+    if (!sameBinding(stored.binding, inspected.binding)) {
+      tokens.delete(requestId);
+      return { accepted: false, rejectionCode: 'source-mismatch' };
+    }
+
+    tokens.delete(requestId);
+    return {
+      accepted: true,
+      authorizationEvent: Object.freeze({
+        bot: botName,
+        daemon_instance_id: daemonIdentity.daemon_instance_id,
+        pid: daemonIdentity.pid,
+        package_version: daemonIdentity.package_version,
+        provider: stored.binding.provider,
+        configured_scope_sha256: stored.binding.scopeDigest,
+        session_key: stored.binding.sessionKey,
+        source_message_id: stored.binding.messageId,
+        restart_request_sha256: createHash('sha256')
+          .update(requestId)
+          .digest('hex'),
+      }),
+    };
+  }
+
+  return Object.freeze({
+    probe,
+    authorizeRestart,
+  });
+}
+
+module.exports = {
+  configuredScopeSha256,
+  createForegroundCanaryAuthorizer,
+  normalizeDeployForegroundExpectation,
+  resolveConfiguredScope,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polygram",
-  "version": "0.38.1",
+  "version": "0.38.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",
   "bin": {

package/polygram.js

@@ -31,13 +31,15 @@ const {
 const { buildPrompt, resolvePromptBackend } = require('./lib/prompt');
 const { countInFlight } = require('./lib/queue-utils');
 const { createIpcHandlers } = require('./lib/ipc/handlers');
-const {
-  requireRestartRequestId,
-} = require('./lib/ipc/restart-request-id');
 const {
   buildQualificationEvent,
-  normalizeDeployQualificationExpectation,
 } = require('./lib/ops/clean-restart-qualification');
+const {
+  createForegroundCanaryAuthorizer,
+} = require('./lib/ops/foreground-canary-target');
+const {
+  createDeployRestartHandler,
+} = require('./lib/ops/deploy-restart-handler');
 const { classifyOrphanSweep } = require('./lib/ops/tmux-preflight');
 const {
   parseSystemdInvocationId,
@@ -1075,6 +1077,8 @@ let attemptAutoResume = null;
 let errorReplyText = null;
 let queueWarnThreshold = null;
 let inFlightHandlers = null;
+let getActiveHandlerCount = null;
+let getActiveHandlerTargets = null;
 let awaitHandlerSettlement = null;
 let trackHandlerTask = null;
 let recoverCodexRequest = null;
@@ -4423,6 +4427,8 @@ async function main() {
     errorReplyText,
     queueWarnThreshold,
     inFlightHandlers,
+    getActiveHandlerCount,
+    getActiveHandlerTargets,
     awaitSettlement: awaitHandlerSettlement,
     trackTask: trackHandlerTask,
   } = createDispatcher({
@@ -4849,6 +4855,27 @@ async function main() {
     // scripts, hook); also exported to spawned Claude processes via env.
     const ipcSecret = ipcServer.writeSecret(BOT_NAME);
     process.env.POLYGRAM_IPC_SECRET = ipcSecret;
+    const foregroundCanaryAuthorizer = createForegroundCanaryAuthorizer({
+      botName: BOT_NAME,
+      daemonIdentity,
+      config,
+      tokenSecret: ipcSecret,
+      getActiveHandlerCount: () => getActiveHandlerCount(),
+      getActiveHandlerTargets: () => getActiveHandlerTargets(),
+      getForegroundCanaryTarget: (input) => (
+        db.getForegroundCanaryTarget(input)
+      ),
+    });
+    const requestDeployRestart = createDeployRestartHandler({
+      getIsShuttingDown: () => isShuttingDown,
+      getPid: () => process.pid,
+      foregroundCanaryAuthorizer,
+      persistForegroundCanaryAuthorization: (detail) => (
+        db.logEvent('foreground-canary-target-authorized', detail)
+      ),
+      shutdown,
+      logger: console,
+    });
     ipcCloser = await ipcServer.start({
       path: ipcServer.socketPathFor(BOT_NAME),
       secret: ipcSecret,
@@ -4857,28 +4884,13 @@ async function main() {
         daemonIdentity,
         getInFlightHandlers: () => inFlightHandlers,
         handleSendOverIpc: (req) => handleSendOverIpc(req),
+        requestForegroundCanaryTarget: (req) => (
+          foregroundCanaryAuthorizer.probe(req)
+        ),
         inspectCleanRestartQualification: () => (
           pm.inspectCleanRestartQualification(undefined)
         ),
-        requestDeployRestart: (req) => {
-          if (isShuttingDown) {
-            const error = new Error('shutdown already in progress');
-            error.code = 'SHUTDOWN_IN_PROGRESS';
-            throw error;
-          }
-          const restartRequestId = requireRestartRequestId(req.id);
-          const qualificationExpectation = normalizeDeployQualificationExpectation(req);
-          const oldPid = process.pid;
-          shutdown({
-            continuationAuthorized: true,
-            trigger: 'deploy-ipc',
-            restartRequestId,
-            qualificationExpectation,
-          }).catch((error) => {
-            console.error(`[shutdown] deploy restart failed: ${error.message}`);
-          });
-          return { accepted: true, old_pid: oldPid };
-        },
+        requestDeployRestart,
       }),
       logger: console,
     });