polygram 0.37.2 → 0.38.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 {
@@ -482,6 +489,13 @@ let richEditMessageText;
 // classification, but it never throws: its caller holds the only copy of the
 // reply and owns the plain fallback.
 let richSendMessage;
+// The rich half of the reply-tool delivery chain, hoisted so the interactive
+// turn path can reuse the same instance rather than configure a second one.
+// Two instances would be two capability latches, two styling verdicts and two
+// sets of ceilings to keep in step; one is the only way they cannot drift.
+// Null until main() wires it — callers fall back to plain, which is what a
+// chat without rich gets anyway.
+let makeRichDeliverText = null;
 let richMediaFileIdCache;
 
 // 0.15 secret redaction (agent-flagged path): the agent marks a secret it saw
@@ -1554,12 +1568,15 @@ async function handleMessage(sessionKey, chatId, msg, bot) {
   // path — same contract for "not opted in", "capability known
   // unsupported", and "content doesn't need it" (needsRichRendering
   // inside toTelegramRichBlocks handles the last one).
-  // Rich delivery is limited to this interactive streamer instance.
-  // A reply that never crosses minChars (stays idle → delivered via
-  // deliverReplies) and any non-streaming send path — autonomous-wakeup/
+  // This callback covers the streamed bubble only. A turn that ends with
+  // text instead of streaming it renders rich too, through the reply tool's
+  // own factory reused at the non-streamed branch below — one gate, one
+  // sender, one latch, so the same markdown cannot format two ways
+  // depending on how the answer arrived.
+  // Still plain: the non-streaming send paths — autonomous-wakeup/
   // auto-resume/autosteer via lib/telegram/process-agent-reply.js, cron/
-  // IPC sends — never render rich even when richText is on and the
-  // content qualifies. Those delivery paths intentionally remain plain.
+  // IPC sends. Those render plain even when richText is on and the content
+  // qualifies.
   // Re-read both controls for every flush so a config change or a
   // capability result applies to the turn already in progress.
   // Typed media resolution for rich replies. Same
@@ -2907,27 +2924,78 @@ async function handleMessage(sessionKey, chatId, msg, bot) {
         console.error(`[${label}] sendSticker failed: ${err.message}`);
       });
     } else if (parsed.text) {
-      // 0.7.0: use markdown-aware chunker + deliverReplies primitive.
-      // The old chunkText was newline/byte-only; chunkMarkdownText also
-      // respects code-fence boundaries (closes + reopens across chunks).
-      // Short replies never went live-rich, so image markdown from a
-      // rich-enabled chat degrades to caption text here too — never a
-      // raw local path in the bubble.
-      const shortText = resolveRichTextEnabled(config, chatId, threadId)
-        ? stripMediaMarkdown(parsed.text)
-        : parsed.text;
-      const chunks = chunkMarkdownText(shortText, TG_CHUNK_BUDGET);
-      const deliveryResult = await deliverReplies({
-        bot,
-        send: (b, method, params, m) => tg(b, method, params, m),
-        chatId,
-        threadId,
-        chunks,
-        replyToMessageId: msg.message_id,
-        meta: outMeta,
-        logger: { error: (m) => console.error(`[${label}] ${m}`) },
-      });
-      mediaContext.recordTextFailures(deliveryResult.failed.length);
+      // A turn that ends with text instead of calling the reply tool lands
+      // here. It is the same agent writing the same markdown as the reply
+      // tool, so it renders through the same gate and the same sender —
+      // otherwise a table is a table or a wall of pipes depending only on
+      // which way the answer happened to arrive, which is not a distinction
+      // the reader can see or act on.
+      //
+      // Text-only by construction: no allowedRoots, so media stays degraded
+      // to caption text exactly as it was here before, and this path opens no
+      // upload surface of its own.
+      // Wrapped even though the factory is contracted not to throw: that
+      // contract is convention, and its styling-retry ladder evaluates
+      // blocksAreStyled/flattenStyledBlocks outside any try. A throw escaping
+      // here would skip the plain arm and cost the whole reply, so this catch
+      // is the difference between a flat answer and no answer.
+      let richOut = null;
+      try {
+        richOut = makeRichDeliverText
+          ? await makeRichDeliverText({ chatId, threadId })({
+            text: parsed.text,
+            replyToMessageId: msg.message_id,
+            // Its own source, because rich-message-sent carries none and the
+            // streamed rich open reports as bot-reply-stream-open-rich.
+            // Without a distinct tag nothing downstream can tell this branch
+            // from the other sites writing the bare streamer tag.
+            meta: { ...outMeta, source: 'bot-reply-final-rich' },
+          })
+          : null;
+      } catch (richErr) {
+        // Named apart from the turn's own `err` on purpose: this is the
+        // rich attempt failing, not the turn, and the completion tail is
+        // located in tests by scanning for the turn handler's catch.
+        console.error(`[${label}] rich delivery threw, falling back to plain: ${richErr.message}`);
+        richOut = null;
+      }
+      if (richOut?.handled) {
+        // One bubble, no chunks, nothing failed — but still report, because
+        // this is the same incomplete-delivery gate the plain arm feeds and
+        // it must hear from whichever arm ran.
+        mediaContext.recordTextFailures(richOut.failed.length);
+      } else {
+        // 0.7.0: use markdown-aware chunker + deliverReplies primitive.
+        // The old chunkText was newline/byte-only; chunkMarkdownText also
+        // respects code-fence boundaries (closes + reopens across chunks).
+        // Image markdown from a rich-enabled chat degrades to caption text
+        // here too — never a raw local path in the bubble.
+        //
+        // The `??` arm is load-bearing: a chat with rich off declines with
+        // no body at all, and chunking `undefined` would drop the reply
+        // entirely for most of the fleet. Both arms strip through the same
+        // call, so the delivered text is byte-identical either way.
+        const shortText = richOut?.text ?? (resolveRichTextEnabled(config, chatId, threadId)
+          ? stripMediaMarkdown(parsed.text)
+          : parsed.text);
+        const chunks = chunkMarkdownText(shortText, TG_CHUNK_BUDGET);
+        const deliveryResult = await deliverReplies({
+          bot,
+          send: (b, method, params, m) => tg(b, method, params, m),
+          chatId,
+          threadId,
+          chunks,
+          replyToMessageId: msg.message_id,
+          // Tagged like its rich sibling. Five call sites write the bare
+          // 'bot-reply-stream' tag and three of them deliver reply bodies,
+          // so a row carrying it says nothing about which one produced it.
+          // Naming both arms makes this branch identifiable from the
+          // messages table whichever way the reply went out.
+          meta: { ...outMeta, source: 'bot-reply-final' },
+          logger: { error: (m) => console.error(`[${label}] ${m}`) },
+        });
+        mediaContext.recordTextFailures(deliveryResult.failed.length);
+      }
     }
 
     // A turn whose final output was a solo sticker/reaction skips the
@@ -3478,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;
@@ -3726,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 });
@@ -4062,6 +4136,38 @@ async function main() {
   //
   // Neither feature may switch the other off, which a single strategy slot
   // could not express.
+  // Built before the chain rather than inline in it, because the interactive
+  // turn path reuses this exact instance for its non-streamed replies. See
+  // the makeRichDeliverText declaration for why it must be one instance.
+  // Injected rather than imported by the dispatcher: rich-media.js requires
+  // the dispatcher module, so the reverse direction would be a require cycle.
+  makeRichDeliverText = createRichDeliveryFactory({
+    bot,
+    sendRich: (args) => richSendMessage(args),
+    isRichTextEnabled: (chatId, threadId) => resolveRichTextEnabled(config, chatId, threadId),
+    getRichKnownUnsupported: () => richSendKnownUnsupported,
+    // No config knob: the automatic flatten-and-retry below IS the control,
+    // and it needs no operator to notice anything. A knob would add a state
+    // where styling is off while the server accepts it, which nothing in
+    // the system can detect or correct.
+    isInlineStylingEnabled: () => !richInlineStylingUnsupported,
+    onStylingRejected: () => richStylingLatch?.recordStylingRejection(),
+    onStylingAccepted: () => richStylingLatch?.recordHealthyOutcome(),
+    redactError: redactBotToken,
+    // Media for one reply. The envelope itself (no URL media, the `files:`
+    // fan-out ceiling, the shared stat) lives in rich-media.js so it is
+    // pinned by behavior rather than by this literal — nothing executes
+    // this file. `allowedRoots` arrives per call from the dispatcher, which
+    // computed it once and validates `files:` against that very array, so a
+    // path the reply tool may upload is exactly a path image syntax may
+    // upload. The interactive path passes none, so it renders text-only.
+    makeMediaWiring: makeReplyMediaWiring({
+      config,
+      fileIdCache: richMediaFileIdCache,
+      logEvent,
+      botName: BOT_NAME,
+    }),
+  });
   const makeDeliverText = composeDeliverTextFactories([
     createDeliverTextFactory({
       registry: streamerRegistry,
@@ -4079,35 +4185,7 @@ async function main() {
         resolveRichTextEnabled(config, chatId, threadId) ? stripMediaMarkdown(text) : text
       ),
     }),
-    // Injected rather than imported by the dispatcher: rich-media.js requires
-    // the dispatcher module, so the reverse direction would be a require cycle.
-    createRichDeliveryFactory({
-      bot,
-      sendRich: (args) => richSendMessage(args),
-      isRichTextEnabled: (chatId, threadId) => resolveRichTextEnabled(config, chatId, threadId),
-      getRichKnownUnsupported: () => richSendKnownUnsupported,
-      // No config knob: the automatic flatten-and-retry below IS the control,
-      // and it needs no operator to notice anything. A knob would add a state
-      // where styling is off while the server accepts it, which nothing in
-      // the system can detect or correct.
-      isInlineStylingEnabled: () => !richInlineStylingUnsupported,
-      onStylingRejected: () => richStylingLatch?.recordStylingRejection(),
-      onStylingAccepted: () => richStylingLatch?.recordHealthyOutcome(),
-      redactError: redactBotToken,
-      // Media for one reply. The envelope itself (no URL media, the `files:`
-      // fan-out ceiling, the shared stat) lives in rich-media.js so it is
-      // pinned by behavior rather than by this literal — nothing executes
-      // this file. `allowedRoots` arrives per call from the dispatcher, which
-      // computed it once and validates `files:` against that very array, so a
-      // path the reply tool may upload is exactly a path image syntax may
-      // upload.
-      makeMediaWiring: makeReplyMediaWiring({
-        config,
-        fileIdCache: richMediaFileIdCache,
-        logEvent,
-        botName: BOT_NAME,
-      }),
-    }),
+    makeRichDeliverText,
   ]);
 
   // The edit tool's counterpart to the reply chain above. An agent that posts
@@ -4418,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,
@@ -4468,6 +4546,7 @@ async function main() {
     continuationAuthorized = false,
     trigger = 'signal',
     restartRequestId = null,
+    qualificationExpectation,
   } = {}) => {
     if (isShuttingDown) return;
     const shutdownObservation = cgroupOomObserver.sample();
@@ -4480,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 });
@@ -4554,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
@@ -4571,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,
@@ -4621,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
@@ -4667,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}`);
@@ -4701,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 {}
     }
@@ -4737,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');
@@ -4746,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}`);
           });
@@ -5272,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);