@north-light/crouter 0.3.281 → 0.3.283

package/dist/core/canvas/canvas.js

@@ -93,16 +93,21 @@ function upsertRow(meta) {
          pi_session_file=excluded.pi_session_file`)
         .run(meta.node_id, meta.name, meta.description ?? null, meta.cycles ?? null, meta.kind, meta.mode, meta.lifecycle, meta.cwd, meta.host_kind ?? null, meta.profile_id ?? null, meta.parent ?? null, meta.created, typeof meta.pi_session_file === 'string' ? canonicalSessionFile(meta.pi_session_file) : null);
 }
-/** Seed a node's row at BIRTH: identity columns + runtime columns taken from the
- *  incoming meta (defaults: status='active', the rest null). The only writer
- *  that sets runtime columns alongside identity in one statement — afterwards
- *  the atomic setters are the sole runtime writers. */
-function seedRow(meta) {
-    openDb()
+function insertArmedOutcomeDelivery(db, nodeId, delivery) {
+    const payloadJson = delivery.payload === undefined ? null : JSON.stringify(delivery.payload);
+    if (payloadJson === undefined)
+        throw new TypeError('outcome delivery payload must be JSON-serializable');
+    const now = Date.now();
+    db.prepare(`INSERT INTO node_outcome_deliveries
+      (node_id, state, action_name, argv_json, cwd, config_origin, payload_json, next_attempt_at, created_at, updated_at)
+     VALUES (?, 'armed', ?, ?, ?, ?, ?, 0, ?, ?)`).run(nodeId, delivery.actionName, JSON.stringify(delivery.argv), delivery.cwd, delivery.configOrigin, payloadJson, now, now);
+}
+function seedRow(meta, db = openDb()) {
+    db
         .prepare(`INSERT INTO nodes
          (node_id, name, description, cycles, kind, mode, lifecycle, cwd, host_kind, profile_id, parent, created, pi_session_file,
-          status, intent, waiting_for, final_report, finalized_at, pi_pid, "window", tmux_session, pane)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+          status, intent, waiting_for, final_report, finalized_at, deadline_at, pi_pid, "window", tmux_session, pane)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
        ON CONFLICT(node_id) DO UPDATE SET
          name=excluded.name, description=excluded.description, cycles=excluded.cycles,
          kind=excluded.kind, mode=excluded.mode,
@@ -113,7 +118,7 @@ function seedRow(meta) {
          final_report=excluded.final_report, finalized_at=excluded.finalized_at,
          pi_pid=excluded.pi_pid, "window"=excluded."window", tmux_session=excluded.tmux_session,
          pane=excluded.pane`)
-        .run(meta.node_id, meta.name, meta.description ?? null, meta.cycles ?? null, meta.kind, meta.mode, meta.lifecycle, meta.cwd, meta.host_kind ?? null, meta.profile_id ?? null, meta.parent ?? null, meta.created, typeof meta.pi_session_file === 'string' ? canonicalSessionFile(meta.pi_session_file) : null, meta.status ?? 'active', meta.intent ?? null, meta.waiting_for ?? null, meta.final_report ?? null, meta.finalized_at ?? null, meta.pi_pid ?? null, meta.window ?? null, meta.tmux_session ?? null, meta.pane ?? null);
+        .run(meta.node_id, meta.name, meta.description ?? null, meta.cycles ?? null, meta.kind, meta.mode, meta.lifecycle, meta.cwd, meta.host_kind ?? null, meta.profile_id ?? null, meta.parent ?? null, meta.created, typeof meta.pi_session_file === 'string' ? canonicalSessionFile(meta.pi_session_file) : null, meta.status ?? 'active', meta.intent ?? null, meta.waiting_for ?? null, meta.final_report ?? null, meta.finalized_at ?? null, meta.deadline_at ?? null, meta.pi_pid ?? null, meta.window ?? null, meta.tmux_session ?? null, meta.pane ?? null);
 }
 function rowFrom(r) {
     return {
@@ -140,6 +145,12 @@ function rowFrom(r) {
         terminal_reason: r['terminal_reason'] ?? null,
         final_report: r['final_report'] ?? null,
         finalized_at: r['finalized_at'] ?? null,
+        outcome_kind: r['outcome_kind'] ?? null,
+        outcome_reason: r['outcome_reason'] ?? null,
+        outcome_at: r['outcome_at'] ?? null,
+        outcome_revision: r['outcome_revision'] ?? 0,
+        outcome_detail_json: r['outcome_detail_json'] ?? null,
+        deadline_at: r['deadline_at'] ?? null,
         pi_pid: r['pi_pid'] ?? null,
         pi_pid_identity: r['pi_pid_identity'] ?? null,
         window: r['window'] ?? null,
@@ -151,7 +162,7 @@ function rowFrom(r) {
  *  no row exists yet (the hydration then falls back to whatever the meta held). */
 function runtimeFromRow(nodeId) {
     const r = openDb()
-        .prepare('SELECT status, intent, waiting_for, frozen_at, respawn_failures, respawn_not_before, launched_at, last_settled_at, terminal_reason, final_report, finalized_at, pi_pid, pi_pid_identity, "window", tmux_session, pane FROM nodes WHERE node_id = ?')
+        .prepare('SELECT status, intent, waiting_for, frozen_at, respawn_failures, respawn_not_before, launched_at, last_settled_at, terminal_reason, final_report, finalized_at, outcome_kind, outcome_reason, outcome_at, outcome_revision, outcome_detail_json, deadline_at, pi_pid, pi_pid_identity, "window", tmux_session, pane FROM nodes WHERE node_id = ?')
         .get(nodeId);
     if (r === undefined)
         return null;
@@ -167,6 +178,12 @@ function runtimeFromRow(nodeId) {
         terminal_reason: r['terminal_reason'] ?? null,
         final_report: r['final_report'] ?? null,
         finalized_at: r['finalized_at'] ?? null,
+        outcome_kind: r['outcome_kind'] ?? null,
+        outcome_reason: r['outcome_reason'] ?? null,
+        outcome_at: r['outcome_at'] ?? null,
+        outcome_revision: r['outcome_revision'] ?? 0,
+        outcome_detail_json: r['outcome_detail_json'] ?? null,
+        deadline_at: r['deadline_at'] ?? null,
         pi_pid: r['pi_pid'] ?? null,
         pi_pid_identity: r['pi_pid_identity'] ?? null,
         window: r['window'] ?? null,
@@ -177,7 +194,7 @@ function runtimeFromRow(nodeId) {
 // Nodes
 /** Create a node: scaffold its dirs, persist identity to meta.json, and seed the
  *  row (identity + runtime from the incoming meta). Returns the hydrated view. */
-export function createNode(meta) {
+export function createNode(meta, opts = {}) {
     ensureHome();
     const scaffolded = !existsSync(nodeDir(meta.node_id));
     ensureNodeDirs(meta.node_id);
@@ -191,7 +208,11 @@ export function createNode(meta) {
             rmSync(nodeDir(meta.node_id), { recursive: true, force: true });
         throw error;
     }
-    seedRow(meta);
+    withCanvasWrite((db) => {
+        seedRow(meta, db);
+        if (opts.outcomeDelivery !== undefined)
+            insertArmedOutcomeDelivery(db, meta.node_id, opts.outcomeDelivery);
+    });
     return getNode(meta.node_id);
 }
 /** The canonical node record: durable identity (meta.json) ∪ authoritative
@@ -237,6 +258,35 @@ export function getRowByPane(pane) {
         .get(pane);
     return r ? rowFrom(r) : null;
 }
+/** Nodes whose persisted spawn deadline has elapsed and that remain live work. */
+export function dueNodeDeadlines(nowIso) {
+    return openDb().prepare(`SELECT * FROM nodes
+     WHERE deadline_at IS NOT NULL AND outcome_at IS NULL
+       AND deadline_at <= ? AND status IN ('active','idle') AND kind != 'human'
+     ORDER BY deadline_at, created, node_id`).all(nowIso).map(rowFrom);
+}
+/** Write a claimed warm spare's deadline before it is handed to its caller. */
+export function setNodeDeadline(nodeId, deadlineAt) {
+    return Number(openDb().prepare('UPDATE nodes SET deadline_at = ? WHERE node_id = ?').run(deadlineAt, nodeId).changes) === 1;
+}
+/** Shift active/idle profile deadlines by a completed profile pause duration. */
+export function shiftProfileNodeDeadlines(profileId, pauseDurationMs) {
+    if (!Number.isFinite(pauseDurationMs) || pauseDurationMs <= 0)
+        return 0;
+    return withCanvasWrite((db) => {
+        const rows = db.prepare(`SELECT node_id, deadline_at FROM nodes
+       WHERE profile_id = ? AND deadline_at IS NOT NULL AND status IN ('active', 'idle')`).all(profileId);
+        const update = db.prepare('UPDATE nodes SET deadline_at = ? WHERE node_id = ? AND deadline_at = ?');
+        let shifted = 0;
+        for (const row of rows) {
+            const at = Date.parse(row.deadline_at);
+            if (Number.isNaN(at))
+                continue;
+            shifted += Number(update.run(new Date(at + pauseDurationMs).toISOString(), row.node_id, row.deadline_at).changes);
+        }
+        return shifted;
+    });
+}
 /** Merge an IDENTITY patch into a node's meta.json and re-index its identity
  *  columns. Identity has a single writer per node, so this read-modify-write is
  *  safe (the contended runtime fields were moved out — see the atomic setters
@@ -279,32 +329,84 @@ export function setIntent(nodeId, intent) {
  *  unchanged. Returns the row-changed count so the caller can distinguish "no
  *  such node", "gate failed", and "already applied" without a second query. */
 export function transitionStatusIntent(nodeId, fields, opts = {}) {
-    const assignments = [];
-    const values = [];
-    if (Object.prototype.hasOwnProperty.call(fields, 'status')) {
-        assignments.push('status = ?');
-        values.push(fields.status ?? null);
-    }
-    if (Object.prototype.hasOwnProperty.call(fields, 'intent')) {
-        assignments.push('intent = ?');
-        values.push(fields.intent ?? null);
-    }
-    if (Object.prototype.hasOwnProperty.call(fields, 'terminal_reason')) {
-        assignments.push('terminal_reason = ?');
-        values.push(fields.terminal_reason ?? null);
-    }
-    const predicates = ['node_id = ?'];
-    values.push(nodeId);
-    if (opts.fromStatuses !== undefined) {
-        predicates.push(`status IN (${opts.fromStatuses.map(() => '?').join(', ')})`);
-        values.push(...opts.fromStatuses);
+    // Keep the ordinary lifecycle write exactly as its pre-outcome form: one
+    // conditional UPDATE and no transaction boundary.
+    if (opts.outcome === undefined) {
+        const assignments = [];
+        const values = [];
+        if (Object.prototype.hasOwnProperty.call(fields, 'status')) {
+            assignments.push('status = ?');
+            values.push(fields.status ?? null);
+        }
+        if (Object.prototype.hasOwnProperty.call(fields, 'intent')) {
+            assignments.push('intent = ?');
+            values.push(fields.intent ?? null);
+        }
+        if (Object.prototype.hasOwnProperty.call(fields, 'terminal_reason')) {
+            assignments.push('terminal_reason = ?');
+            values.push(fields.terminal_reason ?? null);
+        }
+        const predicates = ['node_id = ?'];
+        values.push(nodeId);
+        if (opts.fromStatuses !== undefined) {
+            predicates.push(`status IN (${opts.fromStatuses.map(() => '?').join(', ')})`);
+            values.push(...opts.fromStatuses);
+        }
+        if (opts.requireNoFinalReport === true)
+            predicates.push('final_report IS NULL');
+        const result = openDb()
+            .prepare(`UPDATE nodes SET ${assignments.join(', ')} WHERE ${predicates.join(' AND ')}`)
+            .run(...values);
+        return Number(result.changes);
     }
-    if (opts.requireNoFinalReport === true)
-        predicates.push('final_report IS NULL');
-    const result = openDb()
-        .prepare(`UPDATE nodes SET ${assignments.join(', ')} WHERE ${predicates.join(' AND ')}`)
-        .run(...values);
-    return Number(result.changes);
+    const outcome = opts.outcome;
+    return withCanvasWrite((db) => {
+        const assignments = [];
+        const values = [];
+        if (Object.prototype.hasOwnProperty.call(fields, 'status')) {
+            assignments.push('status = ?');
+            values.push(fields.status ?? null);
+        }
+        if (Object.prototype.hasOwnProperty.call(fields, 'intent')) {
+            assignments.push('intent = ?');
+            values.push(fields.intent ?? null);
+        }
+        if (Object.prototype.hasOwnProperty.call(fields, 'terminal_reason')) {
+            assignments.push('terminal_reason = ?');
+            values.push(fields.terminal_reason ?? null);
+        }
+        const outcomeValue = (value, column) => outcome.supersede === true ? '?' : `CASE WHEN outcome_at IS NULL THEN ? ELSE ${column} END`;
+        assignments.push(`outcome_kind = ${outcomeValue(outcome.kind, 'outcome_kind')}`, `outcome_reason = ${outcomeValue(outcome.reason, 'outcome_reason')}`, `outcome_detail_json = ${outcomeValue(outcome.detailJson, 'outcome_detail_json')}`, `outcome_revision = ${outcome.supersede === true ? 'outcome_revision + 1' : 'CASE WHEN outcome_at IS NULL THEN outcome_revision + 1 ELSE outcome_revision END'}`, `outcome_at = ${outcomeValue(outcome.at, 'outcome_at')}`);
+        values.push(outcome.kind, outcome.reason, outcome.detailJson, outcome.at);
+        const predicates = ['node_id = ?'];
+        values.push(nodeId);
+        if (opts.fromStatuses !== undefined) {
+            predicates.push(`status IN (${opts.fromStatuses.map(() => '?').join(', ')})`);
+            values.push(...opts.fromStatuses);
+        }
+        if (opts.requireNoFinalReport === true)
+            predicates.push('final_report IS NULL');
+        const result = db.prepare(`UPDATE nodes SET ${assignments.join(', ')} WHERE ${predicates.join(' AND ')}`).run(...values);
+        if (Number(result.changes) === 0)
+            return 0;
+        const latched = db.prepare('SELECT outcome_at FROM nodes WHERE node_id = ?').get(nodeId);
+        if (outcome.supersede === true || latched.outcome_at === outcome.at) {
+            const now = Date.now();
+            if (outcome.supersede === true) {
+                db.prepare(`UPDATE node_outcome_deliveries
+           SET state = 'pending', attempt = 0, document_json = ?, next_attempt_at = ?,
+               claimed_at = NULL, claim_owner = NULL, accepted_at = NULL, permanent_failed_at = NULL,
+               last_failure_json = NULL, updated_at = ?
+           WHERE node_id = ?`).run(outcome.documentJson ?? null, now, now, nodeId);
+            }
+            else {
+                db.prepare(`UPDATE node_outcome_deliveries
+           SET state = 'pending', next_attempt_at = ?, document_json = ?, updated_at = ?
+           WHERE node_id = ? AND state = 'armed' AND ? IS NOT NULL`).run(now, outcome.documentJson ?? null, now, nodeId, outcome.documentJson ?? null);
+            }
+        }
+        return Number(result.changes);
+    });
 }
 /** Read a node's committed-final latch pointer. Pure read, no side effect. */
 export function getFinalReport(nodeId) {
@@ -479,6 +581,15 @@ export function listNodes(filter) {
         .all(...params);
     return rows.map(rowFrom);
 }
+/** Identity-only projection of every user-visible row: the broker's report
+ *  resolver needs only "does this sender exist, and what is it called", and a
+ *  three-column read stays cheap against a canvas of thousands of rows where a
+ *  full `listNodes()` hydration does not. */
+export function listNodeIdentities() {
+    return openDb()
+        .prepare(`SELECT node_id, name, created FROM nodes WHERE ${NOT_A_SPARE} ORDER BY created`)
+        .all();
+}
 // Warm pool — spare booted roots awaiting a `prefer_warm` claim (see
 // `runtime/warm-pool.ts` for the recipe key and the mint/refill policy).
 /** Mark an already-spawned node as an unclaimed spare for `recipeKey`. Hides it
@@ -553,7 +664,7 @@ function spareIsClaimable(row) {
  *  spare must not sort as an hour-old conversation. This is the one sanctioned
  *  write of `created` after birth (`upsertRow` deliberately never touches it);
  *  the caller mirrors the same stamp into meta.json. */
-export function claimWarmSpare(recipeKey, created) {
+export function claimWarmSpare(recipeKey, created, opts = {}) {
     return withCanvasWrite((db) => {
         const row = warmSpareRowsFor(db, recipeKey).find(spareIsClaimable);
         if (row === undefined)
@@ -561,7 +672,10 @@ export function claimWarmSpare(recipeKey, created) {
         const res = db.prepare('DELETE FROM warm_pool WHERE node_id = ?').run(row.node_id);
         if (res.changes === 0)
             return null;
-        db.prepare('UPDATE nodes SET created = ? WHERE node_id = ?').run(created, row.node_id);
+        db.prepare('UPDATE nodes SET created = ?, deadline_at = ? WHERE node_id = ?')
+            .run(created, opts.deadlineAt ?? null, row.node_id);
+        if (opts.outcomeDelivery !== undefined)
+            insertArmedOutcomeDelivery(db, row.node_id, opts.outcomeDelivery);
         return row.node_id;
     });
 }

package/dist/core/canvas/crons.js

@@ -21,6 +21,7 @@
 // serve the daemon-owned run executor in src/daemon/cron-run.ts.
 import { openDb, withCanvasWrite } from './db.js';
 import { capturePidIdentities, identitiesMatch, killProcessGroup } from './pid.js';
+import { isProfilePaused } from '../profiles/manifest.js';
 /** Ring bound for `cron_runs`: recordCronRun prunes each cron's history to
  *  its most recent this-many rows. */
 export const CRON_RUN_RING = 20;
@@ -305,7 +306,7 @@ export function dueClockCrons(nowIso) {
         .prepare(`SELECT * FROM crons
          WHERE state = 'active' AND run_state = 'idle' AND fire_at <= ?
          ORDER BY fire_at, created, cron_id`)
-        .all(nowIso).map(cronFrom);
+        .all(nowIso).map(cronFrom).filter((cron) => !isProfilePaused(cron.profile));
 }
 /** Atomically acquire the idle run lease: flips `run_state` to 'running' and
  *  records lease/pid metadata, but ONLY if the row is still idle (the

package/dist/core/canvas/index.d.ts

@@ -6,5 +6,6 @@ export * from './source.js';
 export * from './history.js';
 export * from './focuses.js';
 export * from './crons.js';
+export * from './node-outcome-deliveries.js';
 export * from './telemetry.js';
 export { openDb, closeDb } from './db.js';

package/dist/core/canvas/index.js

@@ -8,5 +8,6 @@ export * from './source.js';
 export * from './history.js';
 export * from './focuses.js';
 export * from './crons.js';
+export * from './node-outcome-deliveries.js';
 export * from './telemetry.js';
 export { openDb, closeDb } from './db.js';

package/dist/core/canvas/migrations.js

@@ -1360,6 +1360,52 @@ function addNodeLabelColumns(db) {
         upd.run(description, cycles, id);
     }
 }
+/** v39 — durable terminal outcomes, spawn deadlines, and externally-owned
+ * outcome-delivery attempts. The outcome columns live on `nodes` so the same
+ * conditional terminal-status UPDATE can latch them atomically. */
+function addNodeOutcomeAndDeadline(db) {
+    const columns = nodeColumns(db);
+    addNodeColumnIfMissing(db, columns, 'outcome_kind', 'ALTER TABLE nodes ADD COLUMN outcome_kind TEXT;');
+    addNodeColumnIfMissing(db, columns, 'outcome_reason', 'ALTER TABLE nodes ADD COLUMN outcome_reason TEXT;');
+    addNodeColumnIfMissing(db, columns, 'outcome_at', 'ALTER TABLE nodes ADD COLUMN outcome_at TEXT;');
+    addNodeColumnIfMissing(db, columns, 'outcome_revision', 'ALTER TABLE nodes ADD COLUMN outcome_revision INTEGER NOT NULL DEFAULT 0;');
+    addNodeColumnIfMissing(db, columns, 'outcome_detail_json', 'ALTER TABLE nodes ADD COLUMN outcome_detail_json TEXT;');
+    addNodeColumnIfMissing(db, columns, 'deadline_at', 'ALTER TABLE nodes ADD COLUMN deadline_at TEXT;');
+    db.exec(`
+CREATE TABLE IF NOT EXISTS node_outcome_deliveries (
+  node_id              TEXT PRIMARY KEY,
+  state                TEXT NOT NULL,
+  attempt              INTEGER NOT NULL DEFAULT 0,
+  action_name          TEXT NOT NULL,
+  argv_json            TEXT NOT NULL,
+  cwd                  TEXT NOT NULL,
+  config_origin        TEXT NOT NULL,
+  payload_json         TEXT,
+  document_json        TEXT,
+  next_attempt_at      INTEGER NOT NULL DEFAULT 0,
+  claimed_at           INTEGER,
+  claim_owner          TEXT,
+  accepted_at          INTEGER,
+  permanent_failed_at  INTEGER,
+  last_failure_json    TEXT,
+  created_at           INTEGER NOT NULL,
+  updated_at           INTEGER NOT NULL,
+  FOREIGN KEY(node_id) REFERENCES nodes(node_id) ON DELETE CASCADE
+);
+CREATE INDEX IF NOT EXISTS idx_node_outcome_deliveries_due
+  ON node_outcome_deliveries(state, next_attempt_at);
+CREATE INDEX IF NOT EXISTS idx_nodes_deadline ON nodes(deadline_at) WHERE deadline_at IS NOT NULL;
+
+UPDATE nodes SET outcome_kind='result', outcome_reason='finalized',
+       outcome_at=finalized_at, outcome_revision=1
+ WHERE final_report IS NOT NULL AND outcome_at IS NULL;
+
+UPDATE nodes SET outcome_kind='failure',
+       outcome_reason=COALESCE(terminal_reason,'crashed'),
+       outcome_at=COALESCE(finalized_at, created), outcome_revision=1
+ WHERE final_report IS NULL AND status IN ('done','dead','canceled') AND outcome_at IS NULL;
+`);
+}
 /** The journaled lane of the state-migration registry, adapted to this chain's
  *  step shape. Registry order is preserved, so these versions stay stable as
  *  long as the registry is append-only (same contract as the local list). */
@@ -1411,6 +1457,7 @@ export const MIGRATIONS = [
     /* v36 */ makeNodeSessionFileUnique,
     /* v37 */ repairNodeSessionFileUniqueIndex,
     /* v38 */ addNodeLabelColumns,
+    /* v39 */ addNodeOutcomeAndDeadline,
     ...JOURNALED_STATE_MIGRATIONS,
 ];
 /** Migration indexes that manage their OWN transaction and therefore must not

package/dist/core/canvas/node-outcome-deliveries.d.ts

@@ -0,0 +1,80 @@
+import { type NodeOutcomeKind, type TerminalReason } from './types.js';
+export type OutcomeDeliveryState = 'armed' | 'pending' | 'running' | 'accepted' | 'permanent_failed';
+export interface OutcomeDeliveryFailure {
+    kind: 'exit' | 'signal' | 'timeout' | 'spawn_error';
+    exitCode?: number;
+    signal?: string;
+    message?: string;
+    stderr?: string;
+}
+/** Durable exponential retry delay for the attempt that just failed. */
+export declare function outcomeDeliveryBackoffMs(attempt: number): number;
+export interface OutcomeDeliveryRecord {
+    nodeId: string;
+    state: OutcomeDeliveryState;
+    attempt: number;
+    actionName: string;
+    argv: string[];
+    cwd: string;
+    configOrigin: string;
+    payload: unknown | null;
+    document: unknown | null;
+    nextAttemptAt: number;
+    claimedAt: number | null;
+    claimOwner: string | null;
+    acceptedAt: number | null;
+    permanentFailedAt: number | null;
+    lastFailure: OutcomeDeliveryFailure | null;
+    createdAt: number;
+    updatedAt: number;
+}
+export interface OutcomeDocumentSnapshot {
+    kind: NodeOutcomeKind;
+    reason: TerminalReason;
+    at: string;
+    revision: number;
+    detailJson: string | null;
+}
+/** Compose every delivery document from the hydrated identity and the immutable outcome latch. */
+export declare function composeOutcomeDeliveryDocument(args: {
+    nodeId: string;
+    outcome: OutcomeDocumentSnapshot;
+    action: {
+        name: string;
+        payload: unknown;
+    };
+    finalReport?: string | null;
+    structuredResult?: unknown;
+}): string;
+/** Register a target atomically against the outcome latch. A still-armed target
+ * is replaceable; a settled registration is not. When the outcome already
+ * exists, the row is born pending with its complete immutable document. */
+export declare function armOutcomeDelivery(row: {
+    nodeId: string;
+    actionName: string;
+    argv: string[];
+    cwd: string;
+    configOrigin: string;
+    payload?: unknown;
+    now?: number;
+}): OutcomeDeliveryRecord | null;
+export declare function readOutcomeDelivery(nodeId: string): OutcomeDeliveryRecord | null;
+export declare function dueOutcomeDeliveries(now: number): OutcomeDeliveryRecord[];
+export declare function claimOutcomeDelivery(nodeId: string, now: number, claimOwner: string): OutcomeDeliveryRecord | null;
+export type OutcomeDeliverySettlement = {
+    state: 'accepted';
+} | {
+    state: 'permanent_failed';
+    failure: OutcomeDeliveryFailure;
+} | {
+    state: 'pending';
+    nextAttemptAt: number;
+    failure: OutcomeDeliveryFailure;
+};
+/** Settle only the still-owned running attempt, fencing stale delivery processes. */
+export declare function settleOutcomeDelivery(nodeId: string, attempt: number, claimOwner: string, settlement: OutcomeDeliverySettlement, now: number): boolean;
+export declare function recoverRunningOutcomeDeliveries(now: number): number;
+/** Disarming is deliberately limited to registrations that have not started delivery. */
+export declare function disarmOutcomeDelivery(nodeId: string): boolean;
+/** A canonical final is the one allowed outcome supersede: discard any old claim and retry state. */
+export declare function resetOutcomeDeliveryForSupersede(nodeId: string, documentJson: string | null, now: number): boolean;

package/dist/core/canvas/node-outcome-deliveries.js

@@ -0,0 +1,163 @@
+// Durable delivery registration and attempt state for a node's terminal outcome.
+import { openDb, withCanvasWrite } from './db.js';
+import { getNode } from './canvas.js';
+import { OUTCOME_PAYLOAD_MAX_BYTES } from './types.js';
+import { composeNodeOutcomeDocument } from '../runtime/outcome-document.js';
+/** Durable exponential retry delay for the attempt that just failed. */
+export function outcomeDeliveryBackoffMs(attempt) {
+    return Math.min(5_000 * 2 ** (attempt - 1), 3_600_000);
+}
+function serializedPayload(payload) {
+    if (payload === undefined)
+        return null;
+    const json = JSON.stringify(payload);
+    if (json === undefined)
+        throw new TypeError('outcome delivery payload must be JSON-serializable');
+    if (Buffer.byteLength(json, 'utf8') > OUTCOME_PAYLOAD_MAX_BYTES) {
+        throw new RangeError(`outcome delivery payload exceeds ${OUTCOME_PAYLOAD_MAX_BYTES} bytes`);
+    }
+    return json;
+}
+function outcomeDeliveryFrom(row) {
+    return {
+        nodeId: row.node_id,
+        state: row.state,
+        attempt: row.attempt,
+        actionName: row.action_name,
+        argv: JSON.parse(row.argv_json),
+        cwd: row.cwd,
+        configOrigin: row.config_origin,
+        payload: row.payload_json === null ? null : JSON.parse(row.payload_json),
+        document: row.document_json === null ? null : JSON.parse(row.document_json),
+        nextAttemptAt: row.next_attempt_at,
+        claimedAt: row.claimed_at,
+        claimOwner: row.claim_owner,
+        acceptedAt: row.accepted_at,
+        permanentFailedAt: row.permanent_failed_at,
+        lastFailure: row.last_failure_json === null ? null : JSON.parse(row.last_failure_json),
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+    };
+}
+/** The latch, rather than a later mutable row, defines the terminal view in a delivery document. */
+function nodeAtOutcome(node, outcome) {
+    let status;
+    let intent;
+    if (outcome.kind === 'result' || outcome.reason === 'finished' || outcome.reason === 'declined') {
+        status = 'done';
+        intent = 'done';
+    }
+    else if (outcome.reason === 'parked') {
+        status = 'done';
+        intent = 'parked';
+    }
+    else if (outcome.reason === 'closed' || outcome.reason === 'retired' || outcome.reason === 'stranded' || outcome.reason === 'deadline_exceeded') {
+        status = 'canceled';
+        intent = null;
+    }
+    else {
+        status = 'dead';
+        intent = null;
+    }
+    return { ...node, status, intent, terminal_reason: outcome.reason };
+}
+/** Compose every delivery document from the hydrated identity and the immutable outcome latch. */
+export function composeOutcomeDeliveryDocument(args) {
+    const node = getNode(args.nodeId);
+    if (node === null)
+        throw new Error(`unknown node ${args.nodeId}`);
+    return JSON.stringify(composeNodeOutcomeDocument({
+        node: nodeAtOutcome(node, args.outcome),
+        outcome: args.outcome,
+        action: args.action,
+        ...(args.finalReport === undefined ? {} : { finalReport: args.finalReport }),
+        ...(args.structuredResult === undefined ? {} : { structuredResult: args.structuredResult }),
+    }));
+}
+/** Register a target atomically against the outcome latch. A still-armed target
+ * is replaceable; a settled registration is not. When the outcome already
+ * exists, the row is born pending with its complete immutable document. */
+export function armOutcomeDelivery(row) {
+    const now = row.now ?? Date.now();
+    const payloadJson = serializedPayload(row.payload);
+    return withCanvasWrite((db) => {
+        const node = db.prepare('SELECT * FROM nodes WHERE node_id = ?').get(row.nodeId);
+        if (node === undefined)
+            throw new Error(`unknown node ${row.nodeId}`);
+        const settled = node.outcome_at !== null;
+        if (settled && (node.outcome_kind === null || node.outcome_reason === null)) {
+            throw new Error(`outcome latch is incomplete for node ${row.nodeId}`);
+        }
+        const documentJson = !settled
+            ? null
+            : composeOutcomeDeliveryDocument({
+                nodeId: row.nodeId,
+                outcome: {
+                    kind: node.outcome_kind,
+                    reason: node.outcome_reason,
+                    at: node.outcome_at,
+                    revision: node.outcome_revision,
+                    detailJson: node.outcome_detail_json,
+                },
+                action: { name: row.actionName, payload: row.payload ?? null },
+                finalReport: node.final_report,
+            });
+        const state = settled ? 'pending' : 'armed';
+        const inserted = db.prepare(`INSERT INTO node_outcome_deliveries
+        (node_id, state, action_name, argv_json, cwd, config_origin, payload_json, document_json, next_attempt_at, created_at, updated_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT(node_id) DO UPDATE SET
+         state = excluded.state, action_name = excluded.action_name, argv_json = excluded.argv_json,
+         cwd = excluded.cwd, config_origin = excluded.config_origin, payload_json = excluded.payload_json,
+         document_json = excluded.document_json, next_attempt_at = excluded.next_attempt_at,
+         updated_at = excluded.updated_at
+       WHERE node_outcome_deliveries.state = 'armed'`).run(row.nodeId, state, row.actionName, JSON.stringify(row.argv), row.cwd, row.configOrigin, payloadJson, documentJson, settled ? now : 0, now, now);
+        if (Number(inserted.changes) === 0)
+            return null;
+        return outcomeDeliveryFrom(db.prepare('SELECT * FROM node_outcome_deliveries WHERE node_id = ?').get(row.nodeId));
+    });
+}
+export function readOutcomeDelivery(nodeId) {
+    const row = openDb().prepare('SELECT * FROM node_outcome_deliveries WHERE node_id = ?').get(nodeId);
+    return row === undefined ? null : outcomeDeliveryFrom(row);
+}
+export function dueOutcomeDeliveries(now) {
+    return openDb().prepare(`SELECT * FROM node_outcome_deliveries
+     WHERE state = 'pending' AND next_attempt_at <= ?
+     ORDER BY next_attempt_at, created_at, node_id`).all(now).map(outcomeDeliveryFrom);
+}
+export function claimOutcomeDelivery(nodeId, now, claimOwner) {
+    return withCanvasWrite((db) => {
+        const claimed = db.prepare(`UPDATE node_outcome_deliveries
+       SET state = 'running', attempt = attempt + 1, claimed_at = ?, claim_owner = ?, updated_at = ?
+       WHERE node_id = ? AND state = 'pending' AND next_attempt_at <= ?`).run(now, claimOwner, now, nodeId, now);
+        if (Number(claimed.changes) === 0)
+            return null;
+        return outcomeDeliveryFrom(db.prepare('SELECT * FROM node_outcome_deliveries WHERE node_id = ?').get(nodeId));
+    });
+}
+/** Settle only the still-owned running attempt, fencing stale delivery processes. */
+export function settleOutcomeDelivery(nodeId, attempt, claimOwner, settlement, now) {
+    const failure = settlement.state === 'accepted' ? null : JSON.stringify(settlement.failure);
+    return withCanvasWrite((db) => Number(db.prepare(`UPDATE node_outcome_deliveries
+     SET state = ?, next_attempt_at = ?, claimed_at = NULL, claim_owner = NULL,
+         accepted_at = ?, permanent_failed_at = ?, last_failure_json = ?, updated_at = ?
+     WHERE node_id = ? AND state = 'running' AND attempt = ? AND claim_owner = ?`).run(settlement.state, settlement.state === 'pending' ? settlement.nextAttemptAt : now, settlement.state === 'accepted' ? now : null, settlement.state === 'permanent_failed' ? now : null, failure, now, nodeId, attempt, claimOwner).changes) === 1);
+}
+export function recoverRunningOutcomeDeliveries(now) {
+    return withCanvasWrite((db) => Number(db.prepare(`UPDATE node_outcome_deliveries
+     SET state = 'pending', next_attempt_at = ?, claimed_at = NULL, claim_owner = NULL, updated_at = ?
+     WHERE state = 'running'`).run(now, now).changes));
+}
+/** Disarming is deliberately limited to registrations that have not started delivery. */
+export function disarmOutcomeDelivery(nodeId) {
+    return withCanvasWrite((db) => Number(db.prepare("DELETE FROM node_outcome_deliveries WHERE node_id = ? AND state = 'armed'").run(nodeId).changes) === 1);
+}
+/** A canonical final is the one allowed outcome supersede: discard any old claim and retry state. */
+export function resetOutcomeDeliveryForSupersede(nodeId, documentJson, now) {
+    return withCanvasWrite((db) => Number(db.prepare(`UPDATE node_outcome_deliveries
+     SET state = 'pending', attempt = 0, document_json = ?, next_attempt_at = ?,
+         claimed_at = NULL, claim_owner = NULL, accepted_at = NULL, permanent_failed_at = NULL,
+         last_failure_json = NULL, updated_at = ?
+     WHERE node_id = ?`).run(documentJson, now, now, nodeId).changes) === 1);
+}

package/dist/core/canvas/pid.d.ts

@@ -4,6 +4,13 @@
  *  zombies and processes reaped between the two probes. Only an unavailable
  *  `ps` probe fails open to alive. A null/undefined pid reads dead. */
 export declare function isPidAlive(pid: number | null | undefined): boolean;
+/** Existence-only liveness for READ-ONLY display projections: the signal-0
+ *  probe alone, no `ps`. A zombie reads alive here, which a dashboard column
+ *  tolerates and which no lifecycle decision may rely on — revive, teardown,
+ *  and every other authority stays on `isPidAlive`. Exists because the
+ *  dashboard snapshot runs this per live row per request; a `ps` spawn each
+ *  time was a third of daemon CPU on a large canvas. */
+export declare function isPidPresent(pid: number | null | undefined): boolean;
 /** THE single precision-aware identity compare, used EVERYWHERE two
  *  `composeIdentity` fingerprints are compared (this module's own
  *  `recordedPidLiveness`, `captureTeardownSnapshot`'s reuse check, and

package/dist/core/canvas/pid.js

@@ -46,6 +46,23 @@ export function isPidAlive(pid) {
     const state = psProcessState(pid);
     return state !== 'zombie' && state !== 'gone';
 }
+/** Existence-only liveness for READ-ONLY display projections: the signal-0
+ *  probe alone, no `ps`. A zombie reads alive here, which a dashboard column
+ *  tolerates and which no lifecycle decision may rely on — revive, teardown,
+ *  and every other authority stays on `isPidAlive`. Exists because the
+ *  dashboard snapshot runs this per live row per request; a `ps` spawn each
+ *  time was a third of daemon CPU on a large canvas. */
+export function isPidPresent(pid) {
+    if (pid == null)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e.code === 'EPERM';
+    }
+}
 /** Matches the kernel `boot_id` UUID shape (`/proc/sys/kernel/random/boot_id`),
  *  used to tell a NEW-format identity base (a per-boot UUID) apart from a
  *  LEGACY one (a `ps lstart` wall-clock timestamp). A boot_id is a lowercase