polygram 0.38.0 → 0.38.2

package/polygram.js

@@ -32,13 +32,21 @@ 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');
+  buildQualificationEvent,
+} = 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,
   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 +202,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 {
@@ -1068,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;
@@ -3539,10 +3550,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 +3804,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 });
@@ -4410,6 +4427,8 @@ async function main() {
     errorReplyText,
     queueWarnThreshold,
     inFlightHandlers,
+    getActiveHandlerCount,
+    getActiveHandlerTargets,
     awaitSettlement: awaitHandlerSettlement,
     trackTask: trackHandlerTask,
   } = createDispatcher({
@@ -4483,7 +4502,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 +4552,7 @@ async function main() {
     continuationAuthorized = false,
     trigger = 'signal',
     restartRequestId = null,
+    qualificationExpectation,
   } = {}) => {
     if (isShuttingDown) return;
     const shutdownObservation = cgroupOomObserver.sample();
@@ -4545,22 +4565,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 +4647,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 +4666,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 +4740,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 +4790,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 +4824,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 {}
     }
@@ -4797,30 +4855,42 @@ 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,
       handlers: createIpcHandlers({
         botName: BOT_NAME,
+        daemonIdentity,
         getInFlightHandlers: () => inFlightHandlers,
         handleSendOverIpc: (req) => handleSendOverIpc(req),
-        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 oldPid = process.pid;
-          shutdown({
-            continuationAuthorized: true,
-            trigger: 'deploy-ipc',
-            restartRequestId,
-          }).catch((error) => {
-            console.error(`[shutdown] deploy restart failed: ${error.message}`);
-          });
-          return { accepted: true, old_pid: oldPid };
-        },
+        requestForegroundCanaryTarget: (req) => (
+          foregroundCanaryAuthorizer.probe(req)
+        ),
+        inspectCleanRestartQualification: () => (
+          pm.inspectCleanRestartQualification(undefined)
+        ),
+        requestDeployRestart,
       }),
       logger: console,
     });
@@ -5337,7 +5407,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);