@north-light/crouter 0.3.282 → 0.3.284

package/dist/core/__tests__/seam/node-outcome-delivery.test.js

@@ -0,0 +1,153 @@
+// Run with: npm run build && node --test --test-timeout=180000 dist/core/__tests__/seam/node-outcome-delivery.test.js
+//
+// Pins the terminal-outcome delivery boundary: a real node publishes a canonical
+// final through the CLI, then the compiled daemon lane gives the registered
+// command its immutable outcome document on stdin and honors its exit code.
+import { after, before, test } from 'node:test';
+import assert from 'node:assert/strict';
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { closeDb } from '../../canvas/db.js';
+import { readOutcomeDelivery } from '../../canvas/node-outcome-deliveries.js';
+import { createHeadlessHarness } from '../helpers/harness.js';
+let h;
+let root;
+let project;
+function assertKeys(value, expected, label) {
+    assert.deepEqual(Object.keys(value).sort(), [...expected].sort(), `${label} has the pinned document fields`);
+}
+function readCapture(action, attempt) {
+    const path = join(project, `${action}-${attempt}.json`);
+    assert.ok(existsSync(path), `${action} attempt ${attempt} captured stdin`);
+    return JSON.parse(readFileSync(path, 'utf8'));
+}
+function assertResultDocument(document, nodeId, action, payloadJson, attempt) {
+    assertKeys(document, ['schema', 'outcomeId', 'nodeId', 'revision', 'kind', 'reason', 'settledAt', 'node', 'result', 'action', 'delivery'], 'node outcome document');
+    assert.equal(document.schema, 'crtr.node-outcome/v1');
+    assert.equal(document.outcomeId, `${nodeId}:1`);
+    assert.equal(document.nodeId, nodeId);
+    assert.equal(document.revision, 1);
+    assert.equal(document.kind, 'result');
+    assert.equal(document.reason, 'finalized');
+    assert.match(document.settledAt, /^\d{4}-\d{2}-\d{2}T/);
+    assert.equal(document.failure, undefined, 'result documents do not carry a failure discriminator');
+    assertKeys(document.node, ['name', 'kind', 'mode', 'lifecycle', 'status', 'terminalReason', 'cwd', 'createdAt', 'parent', 'spawnedBy'], 'document node');
+    assert.equal(document.node['kind'], 'general');
+    assert.equal(document.node['mode'], 'base');
+    assert.equal(document.node['lifecycle'], 'terminal');
+    assert.equal(document.node['status'], 'done');
+    assert.equal(document.node['terminalReason'], 'finalized');
+    assert.equal(document.node['cwd'], project);
+    assert.equal(document.node['parent'], root);
+    assert.equal(document.node['spawnedBy'], root);
+    assertKeys(document.result, ['finalReport'], 'result document');
+    const finalReport = document.result['finalReport'];
+    assertKeys(finalReport, ['basename', 'path'], 'result final-report pointer');
+    assert.equal(typeof finalReport['basename'], 'string');
+    assert.equal(typeof finalReport['path'], 'string');
+    assertKeys(document.action, ['name', 'payload'], 'document action');
+    assert.equal(document.action.name, action);
+    assert.equal(JSON.stringify(document.action.payload), payloadJson, 'action payload reaches stdin byte-identically');
+    assertKeys(document.delivery, ['attempt'], 'document delivery');
+    assert.equal(document.delivery.attempt, attempt);
+}
+function deliveryWhen(nodeId, predicate, label) {
+    return h.waitFor(() => {
+        closeDb();
+        const delivery = readOutcomeDelivery(nodeId);
+        return delivery !== null && predicate(delivery) ? delivery : null;
+    }, { label, timeoutMs: 20_000 });
+}
+async function createAndFinalize(action, payload) {
+    const payloadJson = JSON.stringify(payload);
+    const created = h.cli(root, [
+        '--json', 'node', 'new', '--kind', 'general', '--cwd', project,
+        '--outcome-action', action, '--outcome-payload', payloadJson,
+        `outcome delivery ${action}`,
+    ]);
+    assert.equal(created.code, 0, `node new for ${action}: ${created.stderr}`);
+    const createdBody = created.json;
+    assert.equal(typeof createdBody?.node_id, 'string', `node new returns its node id for ${action}`);
+    const nodeId = createdBody.node_id;
+    await h.awaitBoot(nodeId);
+    closeDb();
+    const armed = readOutcomeDelivery(nodeId);
+    assert.notEqual(armed, null, `node birth arms ${action} delivery`);
+    assert.equal(armed.state, 'armed');
+    assert.equal(armed.actionName, action);
+    assert.equal(armed.argv[0], join(project, `${action}.sh`));
+    assert.equal(armed.cwd, project);
+    assert.equal(armed.configOrigin, join(project, '.crouter', 'config.json'));
+    assert.equal(JSON.stringify(armed.payload), payloadJson, 'registered payload is frozen before launch');
+    assert.equal(armed.attempt, 0);
+    const finalized = h.cli(nodeId, ['push', 'final', `canonical final for ${action}`]);
+    assert.equal(finalized.code, 0, `push final for ${action}: ${finalized.stderr}`);
+    const pending = await deliveryWhen(nodeId, (delivery) => delivery.state === 'pending', `${action} delivery pending after canonical final`);
+    assert.notEqual(pending.document, null, 'canonical final composes the immutable delivery document');
+    return { nodeId, payloadJson };
+}
+function writeCaptureAction(action, exitPolicy) {
+    const script = join(project, `${action}.sh`);
+    writeFileSync(script, `#!/bin/sh
+attempt_file=.${action}.attempt
+attempt=$(cat "$attempt_file" 2>/dev/null || printf 0)
+attempt=$((attempt + 1))
+printf '%s' "$attempt" > "$attempt_file"
+cat > "${action}-$attempt.json"
+${exitPolicy}
+`);
+    chmodSync(script, 0o755);
+}
+before(async () => {
+    h = await createHeadlessHarness({ sessionPrefix: 'crtr-node-outcome-delivery' });
+    root = h.spawnRoot('node outcome delivery seam root');
+    project = join(h.agentHome, 'outcome-delivery-project');
+    mkdirSync(join(project, '.crouter'), { recursive: true });
+    writeCaptureAction('accepted', 'exit 0');
+    writeCaptureAction('permanent', 'exit 78');
+    writeCaptureAction('retry', 'if [ "$attempt" -eq 1 ]; then exit 1; fi\nexit 0');
+    writeFileSync(join(project, '.crouter', 'config.json'), JSON.stringify({
+        humanActions: {
+            accepted: { argv: ['accepted.sh'], cwd: '.' },
+            permanent: { argv: ['permanent.sh'], cwd: '.' },
+            retry: { argv: ['retry.sh'], cwd: '.' },
+        },
+    }));
+});
+after(async () => {
+    if (h !== undefined)
+        await h.dispose();
+});
+test('canonical outcomes deliver the exact document and honor accepted, permanent, and retry exits', { timeout: 60_000 }, async () => {
+    const acceptedPayload = JSON.parse('{"callbackToken":"accepted-token","callbackId":"accepted-id","nested":{"emoji":"✓"}}');
+    const accepted = await createAndFinalize('accepted', acceptedPayload);
+    await h.tick();
+    const acceptedDelivery = await deliveryWhen(accepted.nodeId, (delivery) => delivery.state === 'accepted' && delivery.attempt === 1, 'accepted outcome delivery');
+    assert.equal(acceptedDelivery.acceptedAt === null, false, 'exit 0 settles delivery as accepted');
+    assertResultDocument(readCapture('accepted', 1), accepted.nodeId, 'accepted', accepted.payloadJson, 1);
+    const permanentPayload = JSON.parse('{"callbackToken":"permanent-token","callbackId":"permanent-id","nested":{"emoji":"✓"}}');
+    const permanent = await createAndFinalize('permanent', permanentPayload);
+    await h.tick();
+    const permanentDelivery = await deliveryWhen(permanent.nodeId, (delivery) => delivery.state === 'permanent_failed' && delivery.attempt === 1, 'permanent outcome delivery');
+    assert.equal(permanentDelivery.permanentFailedAt === null, false, 'exit 78 permanently fails delivery');
+    assert.equal(permanentDelivery.lastFailure?.exitCode, 78);
+    assertResultDocument(readCapture('permanent', 1), permanent.nodeId, 'permanent', permanent.payloadJson, 1);
+    const retryPayload = JSON.parse('{"callbackToken":"retry-token","callbackId":"retry-id","nested":{"emoji":"✓"}}');
+    const retry = await createAndFinalize('retry', retryPayload);
+    await h.tick();
+    const first = await deliveryWhen(retry.nodeId, (delivery) => delivery.state === 'pending' && delivery.attempt === 1 && delivery.lastFailure?.kind === 'exit', 'retryable first outcome delivery');
+    assert.ok(first.nextAttemptAt > Date.now(), 'exit 1 schedules a later retry');
+    assert.equal(first.lastFailure?.exitCode, 1);
+    const firstDocument = readCapture('retry', 1);
+    assertResultDocument(firstDocument, retry.nodeId, 'retry', retry.payloadJson, 1);
+    await h.tick(first.nextAttemptAt + 1);
+    const retried = await deliveryWhen(retry.nodeId, (delivery) => delivery.state === 'accepted' && delivery.attempt === 2, 'second outcome delivery accepted');
+    assert.equal(retried.acceptedAt === null, false, 'the second attempt accepts delivery');
+    const secondDocument = readCapture('retry', 2);
+    assertResultDocument(secondDocument, retry.nodeId, 'retry', retry.payloadJson, 2);
+    const { delivery: firstDelivery, ...firstImmutable } = firstDocument;
+    const { delivery: secondDelivery, ...secondImmutable } = secondDocument;
+    assert.deepEqual(secondImmutable, firstImmutable, 'only delivery.attempt changes across retries');
+    assert.deepEqual(firstDelivery, { attempt: 1 });
+    assert.deepEqual(secondDelivery, { attempt: 2 });
+});

package/dist/core/bash-jobs.d.ts

@@ -117,6 +117,12 @@ export declare function activeBackgroundBashJobs(contextDir: string): BashJobSta
  * passed at `now`. The daemon's deadline lane stops exactly these. A job with
  * no deadline (deliberate handoff, or one the node claimed) never appears. */
 export declare function expiredAutoBackgroundBashJobs(contextDir: string, now: number): BashJobStatus[];
+/** Credit every armed auto-cancel deadline for an interval the node was not
+ * permitted to run. A profile pause stops the owning node, so without this the
+ * claim window burns down while the only agent that could claim it is stopped,
+ * and resume greets it with a job already canceled for not being claimed. A
+ * deliberate handoff carries no deadline and is untouched. */
+export declare function shiftAutoBackgroundBashDeadlines(contextDir: string, byMs: number): number;
 export type BackgroundBashJobResult = 'backgrounded' | 'already-backgrounded' | 'finished' | 'missing';
 /** Atomically hand one foreground job to its detached supervisor. The rename
  * is the ownership decision: exactly one caller can move job.run to job.bg,

package/dist/core/bash-jobs.js

@@ -268,6 +268,28 @@ export function activeBackgroundBashJobs(contextDir) {
 export function expiredAutoBackgroundBashJobs(contextDir, now) {
     return activeBackgroundBashJobs(contextDir).filter((job) => job.deadlineAtMs !== null && now >= job.deadlineAtMs);
 }
+/** Credit every armed auto-cancel deadline for an interval the node was not
+ * permitted to run. A profile pause stops the owning node, so without this the
+ * claim window burns down while the only agent that could claim it is stopped,
+ * and resume greets it with a job already canceled for not being claimed. A
+ * deliberate handoff carries no deadline and is untouched. */
+export function shiftAutoBackgroundBashDeadlines(contextDir, byMs) {
+    if (!Number.isFinite(byMs) || byMs <= 0)
+        return 0;
+    let shifted = 0;
+    for (const job of activeBackgroundBashJobs(contextDir)) {
+        if (job.deadlineAtMs === null)
+            continue;
+        try {
+            writeJobDeadlineMs(bashJobPaths(contextDir, job.jobId), job.deadlineAtMs + byMs);
+            shifted += 1;
+        }
+        catch {
+            /* best-effort — a job that vanished mid-scan needs no credit */
+        }
+    }
+    return shifted;
+}
 /** Atomically hand one foreground job to its detached supervisor. The rename
  * is the ownership decision: exactly one caller can move job.run to job.bg,
  * while the supervisor races to move the same source to job.done. */

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

@@ -1,7 +1,20 @@
-import type { NodeMeta, NodeIdentity, NodeRow, NodeStatus, ExitIntent, SubscriptionRef, Mode, Lifecycle, TerminalReason } from './types.js';
+import type { NodeMeta, NodeIdentity, NodeRow, NodeStatus, ExitIntent, SubscriptionRef, Mode, Lifecycle, TerminalReason, NodeOutcomeKind } from './types.js';
+/** 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. */
+export interface OutcomeDeliveryBinding {
+    actionName: string;
+    argv: string[];
+    cwd: string;
+    configOrigin: string;
+    payload?: unknown;
+}
 /** 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 declare function createNode(meta: NodeMeta): NodeMeta;
+export declare function createNode(meta: NodeMeta, opts?: {
+    outcomeDelivery?: OutcomeDeliveryBinding;
+}): NodeMeta;
 /** The canonical node record: durable identity (meta.json) ∪ authoritative
  *  runtime (the row). Null if unknown. */
 export declare function getNode(nodeId: string): NodeMeta | null;
@@ -15,6 +28,12 @@ export declare function getRow(nodeId: string): NodeRow | null;
  *  to adopt a caller's pane as a focus). pane is not UNIQUE in the schema, but a
  *  live pane backs at most one node, so this returns the single match. */
 export declare function getRowByPane(pane: string): NodeRow | null;
+/** Nodes whose persisted spawn deadline has elapsed and that remain live work. */
+export declare function dueNodeDeadlines(nowIso: string): NodeRow[];
+/** Write a claimed warm spare's deadline before it is handed to its caller. */
+export declare function setNodeDeadline(nodeId: string, deadlineAt: string | null): boolean;
+/** Shift active/idle profile deadlines by a completed profile pause duration. */
+export declare function shiftProfileNodeDeadlines(profileId: string, pauseDurationMs: number): number;
 /** 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
@@ -39,6 +58,17 @@ export declare function transitionStatusIntent(nodeId: string, fields: {
 }, opts?: {
     fromStatuses?: readonly NodeStatus[];
     requireNoFinalReport?: boolean;
+    /** Present ⇒ latch an outcome and make an armed delivery pending atomically. */
+    outcome?: {
+        kind: NodeOutcomeKind;
+        reason: TerminalReason;
+        detailJson: string | null;
+        at: string;
+        /** Canonical-final only: replace a prior failure outcome. */
+        supersede?: boolean;
+        /** The document composed at outcome time for an armed delivery. */
+        documentJson?: string | null;
+    };
 }): number;
 /** Read a node's committed-final latch pointer. Pure read, no side effect. */
 export declare function getFinalReport(nodeId: string): string | null;
@@ -135,6 +165,11 @@ export declare function listNodes(filter?: {
     withRecordedPid?: boolean;
     withRecordedPidOrFrozen?: boolean;
 }): NodeRow[];
+/** 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 declare function listNodeIdentities(): Array<Pick<NodeRow, 'node_id' | 'name' | 'created'>>;
 /** Mark an already-spawned node as an unclaimed spare for `recipeKey`. Hides it
  *  from every listing until it is claimed. */
 export declare function registerWarmSpare(nodeId: string, recipeKey: string): void;
@@ -178,7 +213,10 @@ export declare function isWarmSpare(nodeId: string): boolean;
  *  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 declare function claimWarmSpare(recipeKey: string, created: string): string | null;
+export declare function claimWarmSpare(recipeKey: string, created: string, opts?: {
+    deadlineAt?: string;
+    outcomeDelivery?: OutcomeDeliveryBinding;
+}): string | null;
 /** How many CLAIMABLE spares are parked for `recipeKey` (the depth check a
  *  refill reads before minting). Uses the same liveness test as the claim, so a
  *  spare the claim would skip can never hold the pool at depth 1 and starve

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