polygram 0.38.0 → 0.38.1

package/.claude-plugin/plugin.json

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

@@ -0,0 +1,75 @@
+'use strict';
+
+const ROOT_ERROR_CODES = new Set([
+  'CODEX_PROTOCOL_ERROR',
+  'CODEX_TRANSPORT_ERROR',
+  'CODEX_PROCESS_EXITED',
+  'CODEX_PROCESS_ERROR',
+  'CODEX_RPC_TIMEOUT',
+  'CODEX_SINK_TIMEOUT',
+  'CODEX_PROCESS_CLOSE_TIMEOUT',
+  'CODEX_PROCESS_CLEANUP_UNVERIFIED',
+  'unknown',
+]);
+
+const FAULT_CLASSES = new Set([
+  'stderr-limit',
+  'transport',
+  'protocol',
+  'process-exit',
+  'rpc-timeout',
+  'sink',
+  'cleanup',
+  'unknown',
+]);
+
+const NOTIFICATION_METHODS = new Set([
+  'error',
+  'thread/status/changed',
+  'thread/settings/updated',
+  'turn/started',
+  'turn/completed',
+  'item/started',
+  'item/completed',
+  'item/agentMessage/delta',
+]);
+
+const PROCESS_STATES = new Set([
+  'Spawning',
+  'Initializing',
+  'AttachingThread',
+  'Idle',
+  'StartingTurn',
+  'Active',
+  'BackgroundWorking',
+  'BackgroundSettling',
+  'Settling',
+  'Quiescing',
+  'Stopped',
+  'Closing',
+  'Closed',
+  'FailedAmbiguous',
+  'RecoveryConflict',
+  'DurabilityBlocked',
+  'ContainmentFailed',
+  'unknown',
+]);
+
+function sanitizeCodexFaultProvenance(input) {
+  const safe = {};
+  if (ROOT_ERROR_CODES.has(input?.clientRootErrorCode)) {
+    safe.clientRootErrorCode = input.clientRootErrorCode;
+  }
+  if (FAULT_CLASSES.has(input?.clientFaultClass)) {
+    safe.clientFaultClass = input.clientFaultClass;
+  }
+  if (NOTIFICATION_METHODS.has(input?.notificationMethod)) {
+    safe.notificationMethod = input.notificationMethod;
+  }
+  if (PROCESS_STATES.has(input?.observedProcessState)) {
+    safe.observedProcessState = input.observedProcessState;
+  }
+  return safe;
+}
+
+module.exports = { sanitizeCodexFaultProvenance };

package/lib/codex/runtime-controller.js

@@ -6,6 +6,9 @@ const orchestraDefault = require('@shumkov/orchestra');
 const { resolvePinnedCodexBinary } = require('./binary');
 const { resolveCodexHostIdentity } = require('./host-identity');
 const { CodexModelCatalog } = require('./model-catalog');
+const {
+  sanitizeCodexFaultProvenance,
+} = require('./fault-provenance');
 const {
   createCodexRuntimeProfileBuilder,
 } = require('./runtime-profile');
@@ -1432,6 +1435,7 @@ function createCodexRuntimeController({
         app_server_session_id: expectedAppServerSessionId,
         reason: deliveryResultString(payload.reason, 'containment reason'),
         source: 'managed-group-empty',
+        ...sanitizeCodexFaultProvenance(payload),
         allow_missing_generation: !record.durable,
         ts: payload.ts ?? Date.now(),
       });

package/lib/db/codex-failed-generation.js

@@ -7,6 +7,9 @@ const {
 const {
   CODEX_APP_SERVER_NAMESPACE,
 } = require('./sessions');
+const {
+  sanitizeCodexFaultProvenance,
+} = require('../codex/fault-provenance');
 const SETTLEMENT_SOURCES = new Set([
   'managed-group-empty',
   'exclusive-takeover-grace',
@@ -428,7 +431,11 @@ function settleCodexFailedGeneration(rawDb, input) {
     `).run(
       generationId,
       providerSessionId,
-      JSON.stringify({ source, reason }),
+      JSON.stringify({
+        source,
+        reason,
+        ...sanitizeCodexFaultProvenance(input),
+      }),
       ts,
     );
 

package/lib/db/events-retention.js

@@ -44,6 +44,7 @@ const DEFAULT_POLICY = {
     // silently lost? Kept so "why didn't my message get answered after the
     // restart?" is answerable beyond the 90d default (still capped).
     'replay-on-boot', 'replay-notice-sent', 'replay-notice-failed',
+    'clean-restart-qualification-observed',
     // 0.15 secret-redaction audit — what was redacted/flagged, kept for review.
     'secret-sweep', 'secret-sweep-failed',
     'secret-redacted-by-agent', 'secret-redact-requested-no-match',

package/lib/db.js

@@ -23,6 +23,9 @@ const {
   codexError,
   requiredString: requiredCodexString,
 } = require('./db/codex-input');
+const {
+  sanitizeCodexFaultProvenance,
+} = require('./codex/fault-provenance');
 
 // 0.8.0 Phase 1: bumped from 9 → 10. Adds migration
 // 010-tool-use-id.sql (pending_approvals.tool_use_id column for the
@@ -894,6 +897,7 @@ function wrap(db) {
         if (value != null) detail[key] = value;
       }
     }
+    Object.assign(detail, sanitizeCodexFaultProvenance(input));
     return Object.keys(detail).length > 0 ? JSON.stringify(detail) : null;
   }
 

package/lib/handlers/poll.js

@@ -33,76 +33,150 @@ function createPollLoop({
   getTopicName,
   logger = console,
 } = {}) {
-  async function pollBot(bot) {
-    await bot.init();
-    bot._setBotUsername(bot.botInfo.username);
-    logger.log?.(`[${botName}] Bot @${bot.botInfo.username} ready`);
+  let running = true;
+  let pollStarted = false;
+  let pollSettled = false;
+  let lastAdmittedUpdateId = null;
+  let resolvePollQuiescence;
+  let rejectPollQuiescence;
+  const pollQuiescence = new Promise((resolve, reject) => {
+    resolvePollQuiescence = resolve;
+    rejectPollQuiescence = reject;
+  });
+  pollQuiescence.catch(() => {});
 
-    await bot.api.deleteWebhook();
+  const settlePollSuccess = () => {
+    if (pollSettled) return;
+    pollSettled = true;
+    resolvePollQuiescence({ lastAdmittedUpdateId });
+  };
+  const settlePollFailure = (error) => {
+    if (pollSettled) return;
+    pollSettled = true;
+    rejectPollQuiescence(error);
+  };
+  const stopPolling = () => {
+    running = false;
+    if (!pollStarted) settlePollSuccess();
+    return pollQuiescence;
+  };
+  const awaitPollSettlement = ({ timeoutMs } = {}) => {
+    if (timeoutMs == null) return pollQuiescence;
+    let timer;
+    const timeout = new Promise((_, reject) => {
+      timer = setTimeout(() => {
+        const error = new Error(`polling ingress did not settle within ${timeoutMs}ms`);
+        error.code = 'POLL_SETTLEMENT_TIMEOUT';
+        reject(error);
+      }, timeoutMs);
+    });
+    return Promise.race([pollQuiescence, timeout])
+      .finally(() => clearTimeout(timer));
+  };
 
-    // Restore polling offset from DB so a restart doesn't re-process
-    // the backlog Telegram accumulated while we were down.
-    let offset = 0;
+  async function pollBot(bot) {
+    if (!running) return;
+    pollStarted = true;
+    bot._stop = stopPolling;
     try {
-      const saved = db?.getPollingOffset?.(botName);
-      if (saved && saved > 0) {
-        offset = saved + 1;
-        logger.log?.(`[${botName}] resuming polling from update_id ${saved}`);
+      await bot.init();
+      if (!running) {
+        settlePollSuccess();
+        return;
       }
-    } catch (err) {
-      logger.error?.(`[${botName}] getPollingOffset failed: ${err.message}`);
-    }
-    let running = true;
-    bot._lastPollTs = Date.now();
-    bot._stop = () => { running = false; };
+      bot._setBotUsername(bot.botInfo.username);
+      logger.log?.(`[${botName}] Bot @${bot.botInfo.username} ready`);
 
-    while (running) {
+      await bot.api.deleteWebhook();
+      if (!running) {
+        settlePollSuccess();
+        return;
+      }
+
+      // Restore polling offset from DB so a restart doesn't re-process
+      // the backlog Telegram accumulated while we were down.
+      let offset = 0;
       try {
-        const updates = await bot.api.getUpdates({
-          offset,
-          timeout: 25,
-          allowed_updates: ['message', 'edited_message', 'callback_query'],
-        });
-        bot._lastPollTs = Date.now();
+        const saved = db?.getPollingOffset?.(botName);
+        if (saved && saved > 0) {
+          offset = saved + 1;
+          logger.log?.(`[${botName}] resuming polling from update_id ${saved}`);
+        }
+      } catch (err) {
+        logger.error?.(`[${botName}] getPollingOffset failed: ${err.message}`);
+      }
+      bot._lastPollTs = Date.now();
+
+      while (running) {
+        try {
+          const updates = await bot.api.getUpdates({
+            offset,
+            timeout: 25,
+            allowed_updates: ['message', 'edited_message', 'callback_query'],
+          });
+          bot._lastPollTs = Date.now();
+          if (!running) break;
 
-        for (const update of updates) {
-          offset = update.update_id + 1;
-          if (update.message && isWellFormedMessage(update.message)) {
-            const m = update.message;
-            const chatId = m.chat.id.toString();
-            const chatConfig = config.chats[chatId];
-            const threadId = m.message_thread_id?.toString();
-            const topicName = threadId
-              ? (chatConfig ? getTopicName(chatConfig, threadId) : threadId)
-              : null;
-            const chatLabel = chatConfig?.name || chatId;
-            const label = topicName ? `${chatLabel}/${topicName}` : chatLabel;
-            logger.log?.(`[${botName}] ← ${label}: ${(m.text || m.caption || '(media)').slice(0, 60)}`);
+          let batchLastAdmittedId = null;
+          for (const update of updates) {
+            if (!running) break;
+            offset = update.update_id + 1;
+            batchLastAdmittedId = update.update_id;
+            lastAdmittedUpdateId = update.update_id;
+            if (update.message && isWellFormedMessage(update.message)) {
+              const m = update.message;
+              const chatId = m.chat.id.toString();
+              const chatConfig = config.chats[chatId];
+              const threadId = m.message_thread_id?.toString();
+              const topicName = threadId
+                ? (chatConfig ? getTopicName(chatConfig, threadId) : threadId)
+                : null;
+              const chatLabel = chatConfig?.name || chatId;
+              const label = topicName ? `${chatLabel}/${topicName}` : chatLabel;
+              logger.log?.(`[${botName}] ← ${label}: ${(m.text || m.caption || '(media)').slice(0, 60)}`);
+            }
+            try {
+              await bot.handleUpdate(update);
+            } catch (err) {
+              logger.error?.(`[${botName}] Handler error: ${err.message}`);
+            }
           }
-          try {
-            await bot.handleUpdate(update);
-          } catch (err) {
-            logger.error?.(`[${botName}] Handler error: ${err.message}`);
+          // Persist offset after batch dispatch — only on non-empty
+          // batches to avoid churning the row on every 25s idle poll.
+          if (batchLastAdmittedId != null) {
+            dbWrite(() => db.savePollingOffset(botName, batchLastAdmittedId),
+              'save polling offset');
+          }
+          // No sleep on the success path: long-poll already blocks
+          // up to 25s when idle.
+        } catch (err) {
+          if (!running) break;
+          if (err.error_code === 409) {
+            logger.log?.(`[${botName}] 409, waiting 3s...`);
+            await new Promise((r) => setTimeout(r, 3000));
+          } else {
+            logger.error?.(`[${botName}] Poll error: ${err.message}`);
+            await new Promise((r) => setTimeout(r, 3000));
           }
         }
-        // Persist offset after batch dispatch — only on non-empty
-        // batches to avoid churning the row on every 25s idle poll.
-        if (updates.length > 0) {
-          dbWrite(() => db.savePollingOffset(botName, updates[updates.length - 1].update_id),
-            'save polling offset');
-        }
-        // No sleep on the success path: long-poll already blocks
-        // up to 25s when idle.
-      } catch (err) {
-        if (!running) break;
-        if (err.error_code === 409) {
-          logger.log?.(`[${botName}] 409, waiting 3s...`);
-          await new Promise((r) => setTimeout(r, 3000));
-        } else {
-          logger.error?.(`[${botName}] Poll error: ${err.message}`);
-          await new Promise((r) => setTimeout(r, 3000));
+      }
+
+      if (lastAdmittedUpdateId != null) {
+        try {
+          await db.savePollingOffset(botName, lastAdmittedUpdateId);
+        } catch (error) {
+          const persistenceError = new Error(
+            `failed to persist the shutdown polling offset: ${error.message}`,
+            { cause: error },
+          );
+          persistenceError.code = 'POLL_OFFSET_PERSISTENCE_FAILED';
+          throw persistenceError;
         }
       }
+      settlePollSuccess();
+    } catch (error) {
+      settlePollFailure(error);
+      throw error;
     }
   }
 
@@ -131,7 +205,12 @@ function createPollLoop({
     }, 30_000);
   }
 
-  return { pollBot, startPollWatchdog };
+  return {
+    pollBot,
+    startPollWatchdog,
+    stopPolling,
+    awaitPollSettlement,
+  };
 }
 
 module.exports = {

package/lib/handlers/questions.js

@@ -8,6 +8,8 @@
  *   tryConsumeAsAnswer   — dispatcher hook: a typed message while a question is
  *                          open (free-text "Other", or a nudge for the wrong user).
  *   expireQuestion       — timeout sweep / cancel: answer {timedout}/{cancelled}, strip.
+ *   beginShutdownDisposition — cancel locally during provider retirement without
+ *                          sending a synthetic answer into the retiring turn.
  *
  * Security (review): per-row 128-bit token in callback_data + claim-on-first-tap
  * respondent authz + plain-text body (no parse_mode) for agent content.
@@ -246,6 +248,22 @@ function createQuestionHandlers({
     logEvent('question-expired', { session_key: row.session_key, tool_call_id: row.tool_call_id, status });
   }
 
+  function beginShutdownDisposition(row, {
+    message = 'Bot is restarting — this question was cancelled.',
+  } = {}) {
+    const ids = JSON.parse(row.message_ids_json || '[]');
+    const editing = ids[0]
+      ? strip(row.chat_id, ids[0], row.thread_id, message)
+      : Promise.resolve();
+    questions.resolve(row.id, 'cancelled');
+    logEvent('question-expired', {
+      session_key: row.session_key,
+      tool_call_id: row.tool_call_id,
+      status: 'cancelled',
+    });
+    return editing;
+  }
+
   // shared: record an advanced result, post a receipt, then next-Q or resolve.
   async function advance(ctx, row, res, fromText) {
     const msgId = (JSON.parse(row.message_ids_json || '[]'))[0];
@@ -283,7 +301,14 @@ function createQuestionHandlers({
     return ctx.answerCallbackQuery(text ? { text, show_alert: alert } : undefined).catch(() => {});
   }
 
-  return { renderAsk, handleQuestionCallback, tryConsumeAsAnswer, expireQuestion, isAwaitingOtherFrom };
+  return {
+    renderAsk,
+    handleQuestionCallback,
+    tryConsumeAsAnswer,
+    expireQuestion,
+    beginShutdownDisposition,
+    isAwaitingOtherFrom,
+  };
 }
 
 module.exports = { createQuestionHandlers };

package/lib/ipc/handlers.js

@@ -8,25 +8,35 @@
 'use strict';
 
 const { buildBusySnapshot } = require('../queue-utils');
+const {
+  assertClosedQualificationRequest,
+  projectQualificationResponse,
+} = require('../ops/clean-restart-qualification');
 
 /**
  * @param {object} opts
  * @param {string} opts.botName
+ * @param {object} opts.daemonIdentity
  * @param {() => Map<string, number>} opts.getInFlightHandlers — read late, not
  *   captured: the dispatcher's map is assigned during boot and replaced on
  *   reload, so a value bound at wiring time can go stale.
  * @param {(req) => any} opts.handleSendOverIpc
  * @param {(req) => any} opts.requestDeployRestart
+ * @param {() => any} opts.inspectCleanRestartQualification
  */
 function createIpcHandlers({
   botName,
+  daemonIdentity,
   getInFlightHandlers,
   handleSendOverIpc,
   requestDeployRestart,
+  inspectCleanRestartQualification,
 } = {}) {
   return {
     ping: async () => ({ pong: true, bot: botName }),
 
+    identity: async () => ({ bot: botName, ...daemonIdentity }),
+
     // Deploy pre-flight: what would restarting this daemon interrupt right now?
     // Counts and session keys only — enough to decide, nothing quotable.
     busy: async () => buildBusySnapshot({
@@ -36,6 +46,21 @@ function createIpcHandlers({
 
     deploy_restart: (req) => requestDeployRestart(req),
 
+    clean_restart_qualification: async (req) => {
+      assertClosedQualificationRequest(req);
+      let observation = null;
+      try {
+        observation = typeof inspectCleanRestartQualification === 'function'
+          ? await inspectCleanRestartQualification()
+          : null;
+      } catch {}
+      return projectQualificationResponse({
+        botName,
+        daemonIdentity,
+        observation,
+      });
+    },
+
     send: (req) => handleSendOverIpc(req),
   };
 }

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

@@ -0,0 +1,260 @@
+'use strict';
+
+const { createHash } = require('node:crypto');
+
+const SHA256_RE = /^[a-f0-9]{64}$/;
+const PROCESS_STATES = new Set([
+  'Spawning', 'Initializing', 'AttachingThread', 'Idle', 'StartingTurn',
+  'Active', 'BackgroundWorking', 'BackgroundSettling', 'Settling',
+  'Quiescing', 'Stopped', 'Closing', 'Closed', 'FailedAmbiguous',
+  'RecoveryConflict', 'DurabilityBlocked', 'ContainmentFailed', 'unknown',
+]);
+const OUTCOME_CODES = new Set([
+  'eligible', 'active-turn', 'pending-delivery', 'background-owner',
+  'background-terminals', 'pagination-incomplete', 'process-not-idle',
+  'process-not-ready', 'no-codex-generation', 'unsupported', 'lease-drift',
+  'generation-drift', 'activity-epoch-drift', 'fence-drift',
+  'inspection-failed', 'invalid-expectation', 'incoherent',
+]);
+const OBSERVATION_KEYS = [
+  'outcome',
+  'reason',
+  'generationDigest',
+  'activityEpoch',
+  'processState',
+  'activeTurnCount',
+  'pendingDeliveryCount',
+  'backgroundOwnerCount',
+  'backgroundTerminalCount',
+  'backgroundTerminalRegistryComplete',
+  'observedAtMs',
+];
+
+function isPlainObject(value) {
+  return value != null
+    && typeof value === 'object'
+    && !Array.isArray(value)
+    && Object.getPrototypeOf(value) === Object.prototype;
+}
+
+function hasExactKeys(value, expectedKeys) {
+  if (!isPlainObject(value)) return false;
+  const keys = Object.keys(value);
+  return keys.length === expectedKeys.length
+    && expectedKeys.every((key) => Object.hasOwn(value, key));
+}
+
+function validOptionalFence(value, validator) {
+  return value === null || validator(value);
+}
+
+function fallbackObservation(now = Date.now) {
+  return Object.freeze({
+    outcome: 'mismatch',
+    reason: 'inspection-failed',
+    generationDigest: null,
+    activityEpoch: null,
+    processState: 'unknown',
+    activeTurnCount: 0,
+    pendingDeliveryCount: 0,
+    backgroundOwnerCount: 0,
+    backgroundTerminalCount: 0,
+    backgroundTerminalRegistryComplete: false,
+    observedAtMs: now(),
+  });
+}
+
+function normalizeQualificationObservation(observation, { now = Date.now } = {}) {
+  if (
+    !hasExactKeys(observation, OBSERVATION_KEYS)
+    || !['qualified', 'mismatch'].includes(observation.outcome)
+    || !OUTCOME_CODES.has(observation.reason)
+    || !validOptionalFence(
+      observation.generationDigest,
+      (value) => SHA256_RE.test(value),
+    )
+    || !validOptionalFence(
+      observation.activityEpoch,
+      (value) => Number.isSafeInteger(value) && value >= 0,
+    )
+    || !PROCESS_STATES.has(observation.processState)
+    || ![0, 1].includes(observation.activeTurnCount)
+    || ![0, 1].includes(observation.pendingDeliveryCount)
+    || ![0, 1].includes(observation.backgroundOwnerCount)
+    || !Number.isSafeInteger(observation.backgroundTerminalCount)
+    || observation.backgroundTerminalCount < 0
+    || observation.backgroundTerminalCount > 1_600
+    || typeof observation.backgroundTerminalRegistryComplete !== 'boolean'
+    || !Number.isSafeInteger(observation.observedAtMs)
+    || observation.observedAtMs < 0
+  ) {
+    return fallbackObservation(now);
+  }
+
+  const qualified = observation.outcome === 'qualified';
+  const eligibleShape = (
+    observation.reason === 'eligible'
+    && SHA256_RE.test(observation.generationDigest)
+    && Number.isSafeInteger(observation.activityEpoch)
+    && observation.processState === 'Idle'
+    && observation.activeTurnCount === 0
+    && observation.pendingDeliveryCount === 0
+    && observation.backgroundOwnerCount === 0
+    && observation.backgroundTerminalCount === 0
+    && observation.backgroundTerminalRegistryComplete === true
+  );
+  if (
+    (qualified && !eligibleShape)
+    || (!qualified && observation.reason === 'eligible')
+  ) {
+    return fallbackObservation(now);
+  }
+
+  return Object.freeze({
+    outcome: observation.outcome,
+    reason: observation.reason,
+    generationDigest: observation.generationDigest,
+    activityEpoch: observation.activityEpoch,
+    processState: observation.processState,
+    activeTurnCount: observation.activeTurnCount,
+    pendingDeliveryCount: observation.pendingDeliveryCount,
+    backgroundOwnerCount: observation.backgroundOwnerCount,
+    backgroundTerminalCount: observation.backgroundTerminalCount,
+    backgroundTerminalRegistryComplete: observation.backgroundTerminalRegistryComplete,
+    observedAtMs: observation.observedAtMs,
+  });
+}
+
+function normalizeDeployQualificationExpectation(request) {
+  if (!isPlainObject(request)) return null;
+  const requestKeys = Object.keys(request);
+  const allowedRequestKeys = new Set([
+    'op', 'id', 'secret', 'qualification_expectation',
+  ]);
+  const hasUnknownRequestField = requestKeys.some(
+    (key) => !allowedRequestKeys.has(key),
+  );
+  const hasExpectation = Object.hasOwn(request, 'qualification_expectation');
+  if (!hasExpectation && !hasUnknownRequestField) return undefined;
+  if (hasUnknownRequestField) return null;
+
+  const expectation = request.qualification_expectation;
+  if (!hasExactKeys(expectation, ['generation_digest', 'activity_epoch'])) {
+    return null;
+  }
+  if (
+    !SHA256_RE.test(expectation.generation_digest)
+    || !Number.isSafeInteger(expectation.activity_epoch)
+    || expectation.activity_epoch < 0
+  ) {
+    return null;
+  }
+  return Object.freeze({
+    expectedGenerationDigest: expectation.generation_digest,
+    expectedActivityEpoch: expectation.activity_epoch,
+  });
+}
+
+function projectQualificationResponse({
+  botName,
+  daemonIdentity,
+  observation,
+  now = Date.now,
+} = {}) {
+  const normalized = normalizeQualificationObservation(observation, { now });
+  return Object.freeze({
+    bot: botName,
+    daemon_instance_id: daemonIdentity?.daemon_instance_id ?? null,
+    package_version: daemonIdentity?.package_version ?? null,
+    observed_at_ms: normalized.observedAtMs,
+    generation_digest: normalized.generationDigest,
+    activity_epoch: normalized.activityEpoch,
+    process_state: normalized.processState,
+    active_turn_count: normalized.activeTurnCount,
+    pending_delivery_count: normalized.pendingDeliveryCount,
+    background_owner_count: normalized.backgroundOwnerCount,
+    background_terminal_count: normalized.backgroundTerminalCount,
+    background_terminal_registry_complete: normalized.backgroundTerminalRegistryComplete,
+    outcome_code: normalized.reason,
+  });
+}
+
+function buildQualificationEvent({
+  botName,
+  daemonIdentity,
+  restartRequestId,
+  expectation,
+  observation,
+  now = Date.now,
+} = {}) {
+  const normalized = normalizeQualificationObservation(observation, { now });
+  const expectationValid = (
+    isPlainObject(expectation)
+    && hasExactKeys(expectation, [
+      'expectedGenerationDigest',
+      'expectedActivityEpoch',
+    ])
+    && SHA256_RE.test(expectation.expectedGenerationDigest)
+    && Number.isSafeInteger(expectation.expectedActivityEpoch)
+    && expectation.expectedActivityEpoch >= 0
+  );
+  const exactMatch = Boolean(
+    expectationValid
+    && normalized.outcome === 'qualified'
+    && normalized.reason === 'eligible'
+    && normalized.generationDigest === expectation.expectedGenerationDigest
+    && normalized.activityEpoch === expectation.expectedActivityEpoch
+    && normalized.processState === 'Idle'
+    && normalized.activeTurnCount === 0
+    && normalized.pendingDeliveryCount === 0
+    && normalized.backgroundOwnerCount === 0
+    && normalized.backgroundTerminalCount === 0
+    && normalized.backgroundTerminalRegistryComplete === true
+  );
+  return Object.freeze({
+    bot: botName,
+    restart_request_sha256: createHash('sha256')
+      .update(restartRequestId)
+      .digest('hex'),
+    daemon_instance_id: daemonIdentity?.daemon_instance_id ?? null,
+    package_version: daemonIdentity?.package_version ?? null,
+    observed_at_ms: normalized.observedAtMs,
+    generation_digest: normalized.generationDigest,
+    expected_activity_epoch: expectationValid
+      ? expectation.expectedActivityEpoch
+      : null,
+    observed_activity_epoch: normalized.activityEpoch,
+    process_state: normalized.processState,
+    active_turn_count: normalized.activeTurnCount,
+    pending_delivery_count: normalized.pendingDeliveryCount,
+    background_owner_count: normalized.backgroundOwnerCount,
+    background_terminal_count: normalized.backgroundTerminalCount,
+    background_terminal_registry_complete: normalized.backgroundTerminalRegistryComplete,
+    exact_match: exactMatch,
+    outcome_code: normalized.reason,
+  });
+}
+
+function assertClosedQualificationRequest(request) {
+  if (!isPlainObject(request)) {
+    throw new TypeError('clean restart qualification request is invalid');
+  }
+  const allowed = new Set(['op', 'id', 'secret']);
+  if (
+    request.op !== 'clean_restart_qualification'
+    || Object.keys(request).some((key) => !allowed.has(key))
+  ) {
+    const error = new Error('clean restart qualification request has unknown fields');
+    error.code = 'INVALID_CLEAN_RESTART_QUALIFICATION_REQUEST';
+    throw error;
+  }
+  return request;
+}
+
+module.exports = {
+  assertClosedQualificationRequest,
+  buildQualificationEvent,
+  normalizeDeployQualificationExpectation,
+  normalizeQualificationObservation,
+  projectQualificationResponse,
+};

package/lib/ops/clean-resume.js

@@ -147,6 +147,17 @@ async function executeCleanResumeClaim(claim, {
     policy_version: claim?.policy_version ?? null,
   };
   const codex = isCodexClaim(claim);
+  let continuationDispatched = false;
+  const markContinuationDispatched = () => {
+    if (continuationDispatched) return;
+    continuationDispatched = true;
+    logEvent('clean-resume-continuation-dispatched', {
+      ...eventDetail,
+      provider: codex ? 'codex' : 'claude',
+      command_kind: 'continue',
+    });
+    markReady();
+  };
   const source = typeof loadSource === 'function'
     ? loadSource(claim.source_message_id)
     : null;
@@ -295,7 +306,7 @@ async function executeCleanResumeClaim(claim, {
       text: 'continue',
       sourceMsgId: codex ? null : source.msg_id,
       expectedProcess: spawned.process,
-      onDispatched: markReady,
+      onDispatched: markContinuationDispatched,
     });
     markReady();
   } catch (error) {

package/lib/ops/clean-shutdown.js

@@ -3,8 +3,10 @@
 async function prepareCleanRetirement({
   pm,
   deliveryBarrier,
+  awaitIngressSettlement,
   awaitHandlerSettlement,
   settlementTimeoutMs = 30_000,
+  qualificationExpectation,
 } = {}) {
   if (typeof deliveryBarrier?.fenceAndDrain !== 'function'
       || typeof deliveryBarrier?.inspect !== 'function') {
@@ -13,22 +15,118 @@ async function prepareCleanRetirement({
   if (typeof pm?.retireForCleanRestart !== 'function') {
     throw new TypeError('ProcessManager.retireForCleanRestart is required');
   }
+  if (typeof awaitIngressSettlement !== 'function') {
+    throw new TypeError('clean shutdown requires ingress settlement');
+  }
   if (typeof awaitHandlerSettlement !== 'function') {
     throw new TypeError('clean shutdown requires handler settlement');
   }
 
-  const deliveryDrain = deliveryBarrier.fenceAndDrain();
-  const processRetirement = pm.retireForCleanRestart({
+  const deliveryDrain = captureSettlement(() => deliveryBarrier.fenceAndDrain());
+  const processRetirement = captureSettlement(() => pm.retireForCleanRestart({
     getDeliveryEvidence: (sessionKey, sourceMsgId) => (
       deliveryBarrier.inspect(sessionKey, sourceMsgId)
     ),
-  });
-  const [, snapshots] = await Promise.all([
+    ...(qualificationExpectation !== undefined
+      ? { qualificationExpectation }
+      : {}),
+  }));
+  const [deliveryResult, retirementResult] = await Promise.allSettled([
     deliveryDrain,
     processRetirement,
   ]);
-  await awaitHandlerSettlement({ timeoutMs: settlementTimeoutMs });
-  return { snapshots: Array.isArray(snapshots) ? snapshots : [] };
+
+  let fallbackResult = null;
+  if (retirementResult.status === 'rejected') {
+    fallbackResult = await settleOne(() => {
+      if (typeof pm?.shutdown !== 'function') {
+        throw new TypeError('ProcessManager.shutdown fallback is required');
+      }
+      return pm.shutdown();
+    });
+  }
+
+  const ingressResult = await settleOne(() => (
+    awaitIngressSettlement({ timeoutMs: settlementTimeoutMs })
+  ));
+  const handlerResult = await settleOne(() => (
+    awaitHandlerSettlement({ timeoutMs: settlementTimeoutMs })
+  ));
+
+  throwFirstRejected([
+    retirementResult,
+    deliveryResult,
+    fallbackResult,
+    ingressResult,
+    handlerResult,
+  ]);
+  const snapshots = retirementResult.value;
+  const normalizedSnapshots = Array.isArray(snapshots) ? snapshots : [];
+  return {
+    snapshots: normalizedSnapshots,
+    qualification: Object.hasOwn(normalizedSnapshots, 'qualification')
+      ? normalizedSnapshots.qualification
+      : null,
+  };
+}
+
+async function settleCrashShutdown({
+  pm,
+  deliveryBarrier,
+  awaitIngressSettlement,
+  awaitHandlerSettlement,
+  settlementTimeoutMs = 30_000,
+} = {}) {
+  if (typeof deliveryBarrier?.fenceAndDrain !== 'function') {
+    throw new TypeError('crash shutdown requires a delivery barrier');
+  }
+  if (typeof pm?.shutdown !== 'function') {
+    throw new TypeError('ProcessManager.shutdown is required');
+  }
+  if (typeof awaitIngressSettlement !== 'function') {
+    throw new TypeError('crash shutdown requires ingress settlement');
+  }
+  if (typeof awaitHandlerSettlement !== 'function') {
+    throw new TypeError('crash shutdown requires handler settlement');
+  }
+
+  const deliveryDrain = captureSettlement(() => deliveryBarrier.fenceAndDrain());
+  const processShutdown = captureSettlement(() => pm.shutdown());
+  const [deliveryResult, shutdownResult] = await Promise.allSettled([
+    deliveryDrain,
+    processShutdown,
+  ]);
+  const ingressResult = await settleOne(() => (
+    awaitIngressSettlement({ timeoutMs: settlementTimeoutMs })
+  ));
+  const handlerResult = await settleOne(() => (
+    awaitHandlerSettlement({ timeoutMs: settlementTimeoutMs })
+  ));
+
+  throwFirstRejected([
+    shutdownResult,
+    deliveryResult,
+    ingressResult,
+    handlerResult,
+  ]);
+}
+
+function captureSettlement(operation) {
+  try {
+    return Promise.resolve(operation());
+  } catch (error) {
+    return Promise.reject(error);
+  }
+}
+
+async function settleOne(operation) {
+  const [result] = await Promise.allSettled([captureSettlement(operation)]);
+  return result;
+}
+
+function throwFirstRejected(results) {
+  const rejected = results.find((result) => result?.status === 'rejected');
+  if (rejected) throw rejected.reason;
 }
 
 function buildResumeIntents({
@@ -116,5 +214,6 @@ function buildResumeIntents({
 
 module.exports = {
   prepareCleanRetirement,
+  settleCrashShutdown,
   buildResumeIntents,
 };

package/lib/ops/daemon-identity.js

@@ -0,0 +1,42 @@
+'use strict';
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+const PACKAGE_VERSION_RE = /^[0-9A-Za-z][0-9A-Za-z.+-]{0,127}$/;
+
+function createDaemonIdentity({
+  mainPath,
+  packageVersion,
+  pid = process.pid,
+  randomUUID = crypto.randomUUID,
+  realpathSync = fs.realpathSync,
+} = {}) {
+  if (typeof mainPath !== 'string' || mainPath.length === 0) {
+    throw new TypeError('daemon main path is required');
+  }
+  if (!PACKAGE_VERSION_RE.test(packageVersion || '')) {
+    throw new TypeError('daemon package version is invalid');
+  }
+  if (!Number.isSafeInteger(pid) || pid <= 1) {
+    throw new TypeError('daemon PID is invalid');
+  }
+
+  const daemonInstanceId = randomUUID();
+  if (!UUID_RE.test(daemonInstanceId)) {
+    throw new TypeError('daemon instance identity is invalid');
+  }
+  const mainRealpath = realpathSync(mainPath);
+
+  return Object.freeze({
+    pid,
+    daemon_instance_id: daemonInstanceId,
+    package_version: packageVersion,
+    main_realpath_sha256: crypto.createHash('sha256')
+      .update(mainRealpath)
+      .digest('hex'),
+  });
+}
+
+module.exports = { createDaemonIdentity };

package/lib/ops/systemd-invocation.js

@@ -9,11 +9,18 @@ function parseSystemdInvocationId(env = process.env) {
   return value;
 }
 
-function lifecycleDetail(detail, invocationId) {
+function lifecycleDetail(detail, invocationId, daemonIdentity = null) {
   const value = detail && typeof detail === 'object' ? detail : {};
-  return invocationId == null
+  const withDaemonIdentity = daemonIdentity == null
     ? value
-    : { ...value, invocation_id: invocationId };
+    : {
+      ...value,
+      daemon_instance_id: daemonIdentity.daemon_instance_id,
+      pid: daemonIdentity.pid,
+    };
+  return invocationId == null
+    ? withDaemonIdentity
+    : { ...withDaemonIdentity, invocation_id: invocationId };
 }
 
 module.exports = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polygram",
-  "version": "0.38.0",
+  "version": "0.38.1",
   "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": {
@@ -63,7 +63,7 @@
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "0.2.123",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@shumkov/orchestra": "0.10.14",
+    "@shumkov/orchestra": "0.10.16",
     "better-sqlite3": "^12.9.0",
     "grammy": "^1.42.0",
     "markdown-it": "^14.1.1",

package/polygram.js

@@ -34,11 +34,17 @@ const { createIpcHandlers } = require('./lib/ipc/handlers');
 const {
   requireRestartRequestId,
 } = require('./lib/ipc/restart-request-id');
+const {
+  buildQualificationEvent,
+  normalizeDeployQualificationExpectation,
+} = require('./lib/ops/clean-restart-qualification');
 const { classifyOrphanSweep } = require('./lib/ops/tmux-preflight');
 const {
   parseSystemdInvocationId,
   lifecycleDetail,
 } = require('./lib/ops/systemd-invocation');
+const { createDaemonIdentity } = require('./lib/ops/daemon-identity');
+const packageMetadata = require('./package.json');
 const { filterAttachments, resolveFileCaps, resolveMaxFileOverride, MAX_TOTAL_BYTES } = require('./lib/attachments');
 // 0.9.0: SDK ProcessManager is the only pm. CLI pm
 // (lib/process-manager.js) deleted in commit 6.
@@ -194,6 +200,7 @@ const { createCgroupOomObserver } = require('./lib/ops/cgroup-oom-observer');
 const { persistShutdownDisposition } = require('./lib/ops/shutdown-disposition');
 const {
   prepareCleanRetirement,
+  settleCrashShutdown,
   buildResumeIntents,
 } = require('./lib/ops/clean-shutdown');
 const {
@@ -3539,10 +3546,16 @@ function createBot(token) {
 // ─── Manual polling — extracted to lib/handlers/poll.js ────────────
 let pollBot = null;
 let startPollWatchdog = null;
+let stopPolling = null;
+let awaitPollSettlement = null;
 
 // ─── Main ───────────────────────────────────────────────────────────
 
 async function main() {
+  const daemonIdentity = createDaemonIdentity({
+    mainPath: __filename,
+    packageVersion: packageMetadata.version,
+  });
   const cgroupOomObserver = createCgroupOomObserver();
   const invocationId = parseSystemdInvocationId();
   let abnormalProviderTermination = null;
@@ -3787,7 +3800,7 @@ async function main() {
     db.logEvent('polygram-start', lifecycleDetail({
       migration: migration.reason,
       imported: migration.imported,
-    }, invocationId));
+    }, invocationId, daemonIdentity));
     if (cgroupOomObserver.startup.status === 'unavailable') {
       console.warn(`[oom-observer] unavailable (${cgroupOomObserver.startup.reason}); handled shutdown signals will retain clean-restart behavior`);
       db.logEvent('oom-observer-unavailable', { reason: cgroupOomObserver.startup.reason });
@@ -4483,7 +4496,7 @@ async function main() {
   dropRedeliverer = createDropRedeliverer({
     db, redeliver: redeliverAsFreshTurn, logEvent, logger: console,
   });
-  ({ pollBot, startPollWatchdog } = createPollLoop({
+  ({ pollBot, startPollWatchdog, stopPolling, awaitPollSettlement } = createPollLoop({
     db, dbWrite, config, botName: BOT_NAME,
     isWellFormedMessage, getTopicName,
     logger: console,
@@ -4533,6 +4546,7 @@ async function main() {
     continuationAuthorized = false,
     trigger = 'signal',
     restartRequestId = null,
+    qualificationExpectation,
   } = {}) => {
     if (isShuttingDown) return;
     const shutdownObservation = cgroupOomObserver.sample();
@@ -4545,22 +4559,30 @@ async function main() {
     isShuttingDown = true;
     console.log(`\nShutting down (${trigger})...`);
     // 1. Stop accepting new inbound first so nothing new queues behind the drain.
-    if (bot && bot._stop) bot._stop();
-
-    // 1.5 (0.13 D1): expire open interactive questions {cancelled} BEFORE the
-    // drain. With D1 the asking turn stays in flight for the whole wait, so a
-    // deploy during a question would otherwise eat the entire 30s drain and
-    // mark the inbound replay-pending mid-ask. Cancelling unblocks claude's
-    // ask so the cycle can end inside the drain; the boot-replay re-ask is the
-    // documented recovery path (design §3 D1 ask-wait semantics).
+    stopPolling();
+    const awaitIngressSettlement = ({ timeoutMs } = {}) => (
+      awaitPollSettlement({ timeoutMs })
+    );
+
+    // Resolve open questions before provider settlement. Authorized deploys
+    // register the card edit and cancel the row without answering the retiring
+    // provider; ordinary stops keep the existing answer-and-await behavior.
     try {
       const openQuestions = questionStore.listOpen?.(BOT_NAME) || [];
-      for (const row of openQuestions) {
-        // eslint-disable-next-line no-await-in-loop
-        await questionHandlers.expireQuestion(row, {
-          status: 'cancelled',
-          message: 'Bot is restarting — this question was cancelled. It may be re-asked in a moment.',
-        }).catch(() => {});
+      if (continuationAuthorized) {
+        for (const row of openQuestions) {
+          questionHandlers.beginShutdownDisposition(row, {
+            message: 'Bot is restarting — this question was cancelled. It may be re-asked in a moment.',
+          });
+        }
+      } else {
+        for (const row of openQuestions) {
+          // eslint-disable-next-line no-await-in-loop
+          await questionHandlers.expireQuestion(row, {
+            status: 'cancelled',
+            message: 'Bot is restarting — this question was cancelled. It may be re-asked in a moment.',
+          }).catch(() => {});
+        }
       }
       if (openQuestions.length) {
         logEvent('shutdown-questions-cancelled', { count: openQuestions.length });
@@ -4619,13 +4641,15 @@ async function main() {
     // 2. Drain in-flight handlers. Wait for inFlightHandlers to empty or
     //    SHUTDOWN_DRAIN_MS to elapse. pm handlers resolve naturally when
     //    result events arrive; the dispatcher's .finally decrements.
-    const drainStart = Date.now();
-    while (inFlightHandlers.size > 0) {
-      if (Date.now() - drainStart >= SHUTDOWN_DRAIN_MS) break;
-      await new Promise((r) => setTimeout(r, 100));
+    let drainElapsed = 0;
+    if (!continuationAuthorized) {
+      const drainStart = Date.now();
+      while (inFlightHandlers.size > 0) {
+        if (Date.now() - drainStart >= SHUTDOWN_DRAIN_MS) break;
+        await new Promise((r) => setTimeout(r, 100));
+      }
+      drainElapsed = Date.now() - drainStart;
     }
-    const drainElapsed = Date.now() - drainStart;
-    const remaining = countInFlight(inFlightHandlers);
 
     // 3. A clean stop closes both output boundaries before persisting any
     //    recovery intent. The ProcessManager receipt is the only authority for
@@ -4636,14 +4660,38 @@ async function main() {
       ? 'provider-process-terminated'
       : null;
     let resumeIntents = [];
-    if (shutdownObservation?.detected !== true) {
+    if (shutdownObservation?.detected === true) {
+      try {
+        await settleCrashShutdown({
+          pm,
+          deliveryBarrier,
+          awaitIngressSettlement,
+          awaitHandlerSettlement,
+          settlementTimeoutMs: SHUTDOWN_DRAIN_MS,
+        });
+      } catch (err) {
+        console.error(`[shutdown] crash settlement failed: ${err.message}`);
+      }
+      pmRetired = true;
+    } else {
       try {
         const retirement = await prepareCleanRetirement({
           pm,
           deliveryBarrier,
+          awaitIngressSettlement,
           awaitHandlerSettlement,
           settlementTimeoutMs: SHUTDOWN_DRAIN_MS,
+          qualificationExpectation,
         });
+        if (qualificationExpectation !== undefined) {
+          logEvent('clean-restart-qualification-observed', buildQualificationEvent({
+            botName: BOT_NAME,
+            daemonIdentity,
+            restartRequestId,
+            expectation: qualificationExpectation,
+            observation: retirement.qualification,
+          }));
+        }
         pmRetired = true;
         const projected = continuationAuthorized ? buildResumeIntents({
           snapshots: retirement.snapshots,
@@ -4686,12 +4734,16 @@ async function main() {
           });
         }
       } catch (err) {
-        forceCrashReason = 'clean-retirement-failed';
+        forceCrashReason = err?.code === 'POLL_OFFSET_PERSISTENCE_FAILED'
+          ? 'poll-offset-persistence-failed'
+          : err?.code === 'POLL_SETTLEMENT_TIMEOUT'
+            ? 'poll-settlement-timeout'
+            : 'clean-retirement-failed';
         console.error(`[shutdown] clean retirement failed: ${err.message}`);
-        if (pm) await pm.shutdown().catch(() => {});
         pmRetired = true;
       }
     }
+    const remaining = countInFlight(inFlightHandlers);
 
     // 4. Persist only after the old delivery/process boundary is closed and
     //    every dispatcher-owned continuation has settled. Any uncertainty is
@@ -4732,7 +4784,7 @@ async function main() {
             ? restartRequestId
             : null,
           ...(res.oomKillDelta != null ? { oom_kill_delta: res.oomKillDelta } : {}),
-        }, invocationId));
+        }, invocationId, daemonIdentity));
         console.log(`[shutdown] ${res.clean ? 'clean' : 'crash-like'} shutdown recorded (${res.shutdownReason}); ${inFlightAtSignal} in-flight at signal, drained ${drainElapsed}ms, ${remaining} still in-flight, ${res.replayMarked} marked replay-pending`);
       } catch (err) {
         console.error(`[shutdown] persistence failed: ${err.message}`);
@@ -4766,7 +4818,7 @@ async function main() {
     if (pm && !pmRetired) await pm.shutdown().catch(() => {});
     if (db) {
       try {
-        db.logEvent('polygram-stop', lifecycleDetail({}, invocationId));
+        db.logEvent('polygram-stop', lifecycleDetail({}, invocationId, daemonIdentity));
         db.raw.close();
       } catch {}
     }
@@ -4802,8 +4854,12 @@ async function main() {
       secret: ipcSecret,
       handlers: createIpcHandlers({
         botName: BOT_NAME,
+        daemonIdentity,
         getInFlightHandlers: () => inFlightHandlers,
         handleSendOverIpc: (req) => handleSendOverIpc(req),
+        inspectCleanRestartQualification: () => (
+          pm.inspectCleanRestartQualification(undefined)
+        ),
         requestDeployRestart: (req) => {
           if (isShuttingDown) {
             const error = new Error('shutdown already in progress');
@@ -4811,11 +4867,13 @@ async function main() {
             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}`);
           });
@@ -5337,7 +5395,7 @@ async function main() {
 
   logEvent('polygram-admission-open', lifecycleDetail({
     bot: BOT_NAME,
-  }, invocationId));
+  }, invocationId, daemonIdentity));
   console.log(`[${BOT_NAME}] Starting...`);
   const pollPromise = pollBot(bot).catch(err => {
     console.error(`[${BOT_NAME}] Fatal:`, err.message);

package/scripts/ipc-smoke.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 /**
  * Quick IPC round-trip probe.
- * Usage: node scripts/ipc-smoke.js <bot-name> [busy|restart] [restart-request-id]
+ * Usage: node scripts/ipc-smoke.js <bot-name> [busy|identity|restart] [restart-request-id]
  */
 
 const crypto = require('node:crypto');
@@ -14,6 +14,9 @@ function restartRequestId(value) {
   return requireRestartRequestId(value || crypto.randomUUID());
 }
 
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+const SHA256_RE = /^[0-9a-f]{64}$/;
+
 (async () => {
   const bot = process.argv[2] || 'shumabit';
   const command = process.argv[3] || 'ping';
@@ -67,12 +70,44 @@ function restartRequestId(value) {
     return;
   }
 
+  if (command === 'identity') {
+    const result = await call({
+      path,
+      op: 'identity',
+      secret: readSecret(bot),
+      connectTimeoutMs: 5_000,
+      callTimeoutMs: 5_000,
+    });
+    if (
+      result.ok !== true
+      || result.bot !== bot
+      || !Number.isSafeInteger(result.pid)
+      || result.pid <= 1
+      || !UUID_RE.test(result.daemon_instance_id)
+      || typeof result.package_version !== 'string'
+      || result.package_version.length === 0
+      || result.package_version.length > 128
+      || !SHA256_RE.test(result.main_realpath_sha256)
+    ) {
+      throw new Error('invalid daemon identity response');
+    }
+    console.log(JSON.stringify({
+      bot: result.bot,
+      pid: result.pid,
+      daemon_instance_id: result.daemon_instance_id,
+      package_version: result.package_version,
+      main_realpath_sha256: result.main_realpath_sha256,
+    }));
+    return;
+  }
+
   console.log('path:', path);
   console.log('ping:', JSON.stringify(await call({ path, op: 'ping' })));
   console.log('DONE');
 })().catch((err) => {
-  const message = process.argv[3] === 'busy'
-    ? 'busy request failed'
+  const command = process.argv[3];
+  const message = command === 'busy' || command === 'identity'
+    ? `${command} request failed`
     : err.message;
   console.error('ERR:', message);
   process.exit(1);