polygram 0.38.0 → 0.38.2

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

@@ -0,0 +1,261 @@
+'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',
+    'foreground_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/deploy-restart-handler.js

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