polygram 0.37.2 → 0.38.1

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/lib/telegram/display-hint.js

@@ -90,6 +90,7 @@ const richSection = (inlineMedia) => [
   '- A numbered sequence (steps, ranked facts, top-N) → a real ordered list (`1.` at line start, continuation lines indented under their item), not bold pseudo-items like `**1. First thing.**` on their own paragraphs. A real list renders with native numbering and hanging indentation; the bold fake renders as flat paragraphs that merely start with a digit.',
   '- A list of items each with a yes/no/pending state (approve this? confirm that?) → a real task list (`- [ ] item`), not `• item` with an emoji glued on.',
   '- A comparison or key/value summary → a real markdown table.',
+  '- Rows and columns you are laying out yourself → a real markdown table, never hand-aligned columns inside a ``` fence. A fence is not a table: its columns are just whitespace you typed, so the client cannot re-lay-out them to fit and on a narrow screen the rows break mid-row and the alignment collapses into noise. Keep fences for code, logs, and command output you are quoting verbatim — including output that is already table-shaped, which you reproduce exactly rather than retype as a markdown table.',
   '- A quoted aside, caveat, or callout you want visually set apart → a real blockquote (`> like this`), not a bold prefix.',
   '- A visual break between distinct sections of a long reply → a real divider (`---` on its own line), the same way you already reach for it, but now it renders as a divider instead of literal dashes.',
   '- Verbose supporting detail (a diff, a log, raw output) you want available but not front-and-center → `<details><summary>Label</summary>...</details>`.',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polygram",
-  "version": "0.37.2",
+  "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",