@north-light/crouter 0.3.281 → 0.3.283

package/dist/core/__tests__/revive-parked-fresh.test.js

@@ -1,17 +1,10 @@
 // Run with: node --conditions=crtr-src --import tsx/esm --test src/core/__tests__/revive-parked-fresh.test.ts
 //
-// Re-entering a parked node starts a FRESH cycle grounded in goal + roadmap
-// rather than replaying the transcript its parking turn already concluded —
-// but only when the revival CARRIES NEW INPUT. Wake-worthy mail that the node
-// has not seen is that input: every doorway that wakes a parked node because
-// something arrived appends its durable inbox entry before calling in. An
-// input-less revival (a bare lifecycle revive, a viewer attach, a focus) has
-// nothing to answer, so it quietly resumes the old transcript and injects no
-// kickoff. The rule is a property of the node, evaluated once inside
-// reviveNode, so every doorway gets it from one strict-resume veto. Its other
-// exception is a park with nothing on disk to stand on (reachable only on the
-// degraded path, which writes no summary): resuming an old transcript beats
-// waking amnesiac.
+// Re-entering a parked node resumes its main transcript: the isolated parking
+// turn never wrote to it. Wake-worthy mail remains durable for the inbox watcher
+// to deliver after boot; it does not create a fresh-cycle kickoff. An input-less
+// revival likewise resumes quietly. The rule is a property of the node,
+// evaluated once inside reviveNode, so every doorway gets it uniformly.
 import { after, afterEach, before, beforeEach, test } from 'node:test';
 import assert from 'node:assert/strict';
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
@@ -103,23 +96,23 @@ after(() => {
     else
         process.env['CRTR_HOME'] = priorHome;
 });
-test('a parked node with mail waiting re-enters fresh even when the caller asked to resume, and the marker clears', async () => {
+test('a parked node with mail waiting resumes its main transcript and clears the marker', async () => {
     parkResident('parked', { roadmap: '# Roadmap\n\n- one open item\n' });
     deliverMail('parked');
     const result = await reviveNode('parked', { resume: true, capacity: 'freeze' });
-    assert.equal(result.resumed, false, 'the concluded transcript is not replayed');
-    assert.deepEqual(placements(), [{ nodeId: 'parked', resuming: false }]);
-    assert.equal(kickedOff(launches[0]), true, 'the fresh window is handed its bearings');
+    assert.equal(result.resumed, true, 'the isolated parking turn never concluded the main transcript');
+    assert.deepEqual(placements(), [{ nodeId: 'parked', resuming: true }]);
+    assert.equal(kickedOff(launches[0]), false, 'the inbox watcher delivers the mail after the resumed boot');
     const reopened = getNode('parked');
     assert.equal(reopened.status, 'active');
     assert.equal(reopened.intent ?? null, null, 'the park marker clears on revival');
-    assert.equal(reopened.cycle_pending, true, 'the fresh cycle is provisional until session_start confirms it');
+    assert.equal(reopened.cycle_pending, false, 'a strict resume does not open a new cycle');
 });
-test('a parked node grounded only by a goal still re-enters fresh when mail rides the revive', async () => {
+test('a parked node grounded only by a goal still resumes when mail rides the revive', async () => {
     parkResident('goal-only', { goal: 'Watch the deploy lane.' });
     deliverMail('goal-only');
-    assert.equal((await reviveNode('goal-only', { resume: true, capacity: 'freeze' })).resumed, false);
-    assert.equal(kickedOff(launches[0]), true);
+    assert.equal((await reviveNode('goal-only', { resume: true, capacity: 'freeze' })).resumed, true);
+    assert.equal(kickedOff(launches[0]), false);
 });
 test('an input-less revival of a parked node quietly resumes and injects no kickoff', async () => {
     parkResident('quiet', { roadmap: '# Roadmap\n\n- one open item\n' });

package/dist/core/__tests__/seam/broker-provider-retry.test.js

@@ -394,7 +394,11 @@ test('reload_auth restores a newly authenticated personal route before the next
     const unauthenticatedProvider = join(h.home, 'fake-pi.unauthenticated-provider');
     mkdirSync(userConfigDir, { recursive: true });
     writeFileSync(userConfigPath, JSON.stringify({
-        kinds: { general: { whenToUse: 'General work.', model: 'anthropic/medium' } },
+        // A fixture-private kind, never `general`: the child launches with the
+        // package root as cwd, so an ambient project-scope config above the repo
+        // (`~/.crouter/config.json`) overrides this user-scope `general` and the
+        // child boots on that machine's default strength instead of medium.
+        kinds: { 'test/logical-anthropic': { whenToUse: 'Logical Anthropic routing test.', model: 'anthropic/medium' } },
         modelRoutes: {
             personal: { family: 'anthropic', credentialSource: 'user', providerId: personal.provider, models: { ultra: personalSpec, strong: personalSpec, medium: personalSpec, light: personalSpec } },
             funded: { family: 'anthropic', credentialSource: 'northlight', providerId: funded.provider, models: { ultra: `${funded.provider}/${funded.id}:medium`, strong: `${funded.provider}/${funded.id}:medium`, medium: `${funded.provider}/${funded.id}:medium`, light: `${funded.provider}/${funded.id}:medium` } },
@@ -404,7 +408,7 @@ test('reload_auth restores a newly authenticated personal route before the next
     writeFileSync(unauthenticatedProvider, personal.provider);
     try {
         const parent = h.spawnRoot('auth route reconciliation parent');
-        const child = await h.spawnHeadlessChild(parent, 'auth route reconciliation child');
+        const child = await h.spawnHeadlessChild(parent, 'auth route reconciliation child', { kind: 'test/logical-anthropic' });
         assert.deepEqual(model(child), funded, 'the logical request starts on the funded route while personal auth is absent');
         const controller = await kit.connectRaw(child, { read: true });
         controller.send({ type: 'hello', role: 'controller', client_id: 'auth-route-reconciliation' });

package/dist/core/__tests__/seam/dormancy-release.test.js

@@ -175,7 +175,7 @@ test('an unattended resident with no live obligation completes on the daemon clo
         await reviveNode(nodeId, { resume: true, capacity: 'freeze' });
         const boot = await h.awaitBoot(nodeId);
         assert.equal(h.fleet.has(nodeId), true, 'the revived broker is fleet-owned');
-        const seenAt = 10_000;
+        const seenAt = Date.now();
         await h.tick(seenAt);
         await h.tick(seenAt + 1499);
         assert.equal(h.fleet.has(nodeId), true, 'the daemon keeps the broker through the full grace');
@@ -228,7 +228,7 @@ test('a non-attending observer does not prevent unattended resident parking', {
     await attach.attach(nodeId, 'observer', 'system-observer-test', { attends: false });
     assert.equal(JSON.parse(readFileSync(join(h.home, 'nodes', nodeId, 'job', 'attach.json'), 'utf8')).viewers, 0, 'a non-attending hello is not persisted as human attendance');
     try {
-        const seenAt = 12_000;
+        const seenAt = Date.now();
         await h.tick(seenAt);
         await h.tick(seenAt + 1500);
         await h.tick(seenAt + 1500 + 1000);
@@ -383,7 +383,7 @@ test('a resident managed child parks without finalizing while a terminal child i
         };
         const residentPid = await boot(resident);
         const terminalPid = await boot(terminal);
-        const seenAt = 50_000;
+        const seenAt = Date.now();
         await h.tick(seenAt);
         // Clock expiry arms the resident's pending park and requests its summary
         // turn; the terminal child is cancelled outright by the same pass.

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

@@ -0,0 +1 @@
+export {};

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