@north-light/crouter 0.3.236 → 0.3.237

package/dist/core/__tests__/cron-self-cancel-delivery.test.js

@@ -0,0 +1,72 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/cron-self-cancel-delivery.test.ts
+//
+// A cron whose own command cancels its row mid-run must still deliver the
+// output that run produced: cancellation retires the schedule, not the run in
+// flight.
+import { after, afterEach, before, test } from 'node:test';
+import assert from 'node:assert/strict';
+import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { closeDb } from '../canvas/db.js';
+import { armCron, cancelCron, getCron } from '../canvas/crons.js';
+import { executeCron, markSelfCanceledCronRun } from '../../daemon/cron-run.js';
+let home;
+let realHome;
+function arm(overrides) {
+    armCron({
+        name: overrides.cron_id,
+        created_by: null,
+        fire_at: new Date(Date.now() - 1_000).toISOString(),
+        recur: null,
+        tz: null,
+        expires_at: null,
+        anchor_node: null,
+        cancel_on_wake: false,
+        cwd: home,
+        env_json: null,
+        profile: null,
+        scope: 'profile',
+        run_timeout_s: 30,
+        overlap: 'skip',
+        on_output: 'silent',
+        sink: '{}',
+        tier: 'normal',
+        ...overrides,
+    });
+}
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-cron-broker-capacity-'));
+    realHome = process.env['CRTR_HOME'];
+    process.env['CRTR_HOME'] = home;
+});
+afterEach(() => {
+    closeDb();
+});
+after(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+    if (realHome === undefined)
+        delete process.env['CRTR_HOME'];
+    else
+        process.env['CRTR_HOME'] = realHome;
+});
+test('an on-change cron that cancels itself still delivers its final output', async () => {
+    const runIdPath = join(home, 'self-cancel-run-id');
+    arm({
+        cron_id: 'self-cancel-delivery',
+        command: `printf '%s' "$CRTR_RUN_ID" > '${runIdPath}'; echo settled; sleep 0.1`,
+        recur: JSON.stringify({ every: '1h' }),
+        on_output: 'on-change',
+        sink: JSON.stringify({ human: true }),
+    });
+    const run = executeCron(getCron('self-cancel-delivery'), { outOfBand: false });
+    for (let i = 0; i < 50 && !existsSync(runIdPath); i++)
+        await delay(10);
+    assert.ok(existsSync(runIdPath), 'the live run exposed its id to its self-cancel command');
+    assert.equal(markSelfCanceledCronRun('self-cancel-delivery', readFileSync(runIdPath, 'utf8')), true);
+    assert.equal(cancelCron('self-cancel-delivery', { preserveRunningProcess: true }), true);
+    const record = await run;
+    assert.equal(record?.delivered, 'delivered: human send --inbox');
+});

package/dist/core/__tests__/daemon-boot.test.js

@@ -15,6 +15,7 @@ import { verifyDaemonStartup, waitForDaemonExit } from '../../daemon/manage.js';
 import { waitForBrokerViewSocket } from '../runtime/placement-tmux.js';
 import { viewSocketPath } from '../canvas/paths.js';
 import { markBusy, clearBusy } from '../runtime/busy.js';
+import { headlessBrokerHost } from '../runtime/host.js';
 import { bindTestFleet } from './helpers/fleet.js';
 import { resetFleetForTests } from '../runtime/fleet.js';
 let home;
@@ -92,34 +93,45 @@ test('never-booted broker exit is marked dead and surfaced to the parent as urge
     assert.ok(wake, 'the doctrine wake rides beside the urgent push');
     assert.match(wake.label, /crashed/i);
 });
-// BROKER CUT: surfaceChildDeath was DELETED and the tick runs no liveness pass.
-// A crashed booted child (engine pid DEAD, pi_session_id set) is never marked
-// `dead` by a tick and never fans a "child died" notice — recovery rides the
-// broker's real exit event (policy rows 5/6 revive it on its saved session), so
-// a fabricated row with no fleet entry is simply left revivable and the doctrine wake
-// relocated (the revived child pushes when it truly finishes; a deliberate close
-// is woken by close.ts). This test preserves the discriminating intent in the
-// new model: a crash is never reaped to `dead` and never raises a false
-// boot-failure alarm.
-test('a crashed booted child is revivable, not reaped, and raises no false boot-failure alarm', async () => {
-    createNode(node('P2', { kind: 'developer', lifecycle: 'resident' }));
-    createNode(node('C2', {
-        parent: 'P2',
-        kind: 'explore',
-        pi_pid: deadPid(), // engine crashed — its recorded pid is dead
-        pi_session_id: '019e8f00-booted-once', // it booted before dying
-        intent: null,
-    }));
-    spawnEdge('P2', 'C2');
-    markBusy('C2'); // died mid-generation
-    await superviseTick();
-    // The tick has no liveness pass: a stale recorded pid is metadata, not a
-    // death signal — the row stays active/revivable, never reaped to `dead`.
-    assert.equal(getNode('C2').status, 'active', 'crashed booted child stays revivable, NOT marked dead');
-    // surfaceChildDeath is gone and this is not a never-booted node, so the daemon
-    // fans NO push here — no false boot-failure / child-death alarm on a crash.
-    assert.equal(readInboxSince('P2').length, 0, 'no false boot-failure / child-death push on a crash (wake relocated to push/close)');
-    clearBusy('C2');
+// surfaceChildDeath was DELETED, and the node-lifecycle tick recovers a crashed
+// booted child through the SAME policy table its exit event would have used
+// (design D-12), so tick recovery and exit recovery can never diverge. A row
+// whose recorded pid is provably dead and whose session was recorded is a
+// resumable crash: it is relaunched on that saved session, never reaped to
+// `dead` and never announced as a boot failure or a child death.
+test('a crashed booted child is relaunched on its saved session, not reaped, and raises no false boot-failure alarm', async () => {
+    const originalLaunch = headlessBrokerHost.launch;
+    const launches = [];
+    headlessBrokerHost.launch = (nodeId) => {
+        launches.push(nodeId);
+        const handle = { pid: 424_242, exited: new Promise(() => { }) };
+        tf.fleet.register(nodeId, handle); // the real host contract: registration at the launch seam
+        return handle;
+    };
+    try {
+        createNode(node('P2', { kind: 'developer', lifecycle: 'resident' }));
+        createNode(node('C2', {
+            cwd: home, // a cwd that exists — reviveNode's preflight refuses a missing one
+            parent: 'P2',
+            kind: 'explore',
+            pi_pid: deadPid(), // engine crashed — its recorded pid is dead
+            pi_session_id: '019e8f00-booted-once', // it booted before dying
+            intent: null,
+        }));
+        spawnEdge('P2', 'C2');
+        markBusy('C2'); // died mid-generation
+        await superviseTick();
+        assert.deepEqual(launches, ['C2'], 'the tick recovers the crash through the policy table, exactly as the exit event would');
+        assert.equal(getNode('C2').status, 'active', 'crashed booted child is relaunched, NOT marked dead');
+        // surfaceChildDeath is gone and this is not a never-booted node, so the daemon
+        // fans NO push here — no false boot-failure / child-death alarm on a crash.
+        assert.equal(readInboxSince('P2').length, 0, 'no false boot-failure / child-death push on a crash (wake relocated to push/close)');
+        clearBusy('C2');
+    }
+    finally {
+        headlessBrokerHost.launch = originalLaunch;
+        tf.fleet.forget('C2');
+    }
 });
 // An unplaced active node is not daemon-managed; the daemon leaves it untouched
 // rather than treating the missing broker/session fields as a boot failure.

package/dist/core/__tests__/human-deliver.test.js

@@ -192,7 +192,7 @@ describe('terminal ticket delivery', () => {
         await deliverTerminalResult(bridge);
         assert.equal(getNode(companion)?.final_report, finalReport, 'terminal replay preserves the first canonical final');
         assert.equal(getNode(companion)?.finalized_at, finalizedAt, 'terminal replay preserves the first finalization time');
-        assert.throws(() => reviveNode(companion, { resume: true }), /finalization latch/);
+        assert.throws(() => reviveNode(companion, { resume: true, capacity: 'freeze' }), /finalization latch/);
         const { bridge: dismissedBridge } = bridgeUnder();
         const dismissedDir = submitBridgePage(dismissedBridge);
         const dismissedCompanion = spawnNode({ kind: 'general', parent: dismissedBridge, cwd: home, name: 'dismissed feedback companion', lifecycle: 'resident' }).node_id;

package/dist/core/__tests__/human-node-not-supervised.test.js

@@ -14,12 +14,11 @@
 // (pid==null, session==null) as a never-booted broker and boot-failed it —
 // killing the human prompt before the person could ever answer.
 //
-// THE FIX under exit-event authority lives in TWO filters, both driven here:
-// superviseTick drops kind:'human' rows from every row pass, and the startup
-// recovery sweep skips them before classification — the sweep treats every
-// swept row as known-dead, so an unfiltered human row (session null, no fork
-// claim) would land in policy row 8 (boot failure), the modern re-incarnation
-// of the exact bug.
+// THE FIX under exit-event authority is superviseTick's one filter, driven
+// here: it drops kind:'human' rows before every row pass, including the
+// node-lifecycle tick that classifies a row with no live broker as known-dead.
+// An unfiltered human row (session null, no fork claim) would land in policy
+// row 8 (boot failure), the modern re-incarnation of the exact bug.
 import { test, before, after, beforeEach } from 'node:test';
 import assert from 'node:assert/strict';
 import { mkdtempSync, rmSync } from 'node:fs';
@@ -28,7 +27,7 @@ import { join } from 'node:path';
 import { createNode, getNode, subscribe } from '../canvas/canvas.js';
 import { closeDb } from '../canvas/db.js';
 import { readInboxSince } from '../feed/inbox.js';
-import { superviseTick, runStartupRecoverySweep } from '../../daemon/crtrd.js';
+import { superviseTick } from '../../daemon/crtrd.js';
 import { bindTestFleet } from './helpers/fleet.js';
 import { resetFleetForTests } from '../runtime/fleet.js';
 let home;
@@ -49,7 +48,7 @@ function node(id, over = {}) {
 before(() => {
     home = mkdtempSync(join(tmpdir(), 'crtr-human-not-supervised-'));
     process.env['CRTR_HOME'] = home;
-    tf = bindTestFleet(); // superviseTick + the sweep require a bound fleet (D-2)
+    tf = bindTestFleet(); // superviseTick requires a bound fleet (D-2)
 });
 beforeEach(() => {
     closeDb();
@@ -79,16 +78,12 @@ test('a kind:"human" bridge row is NEVER boot-failed by the daemon (it has no br
     // the tick leave IT alone — it is only here to catch a push.
     createNode(node('ASKER', { status: 'idle', intent: 'idle-release', pi_session_id: 'booted' }));
     subscribe('ASKER', 'HUMAN', true);
-    // Two well-spaced ticks: under exit-event authority the tick runs no liveness
-    // pass at all, and its row passes (controller-wait settle, pass-2 inbox wake)
-    // must drop the human row before reading it.
+    // Two well-spaced ticks: the row passes (controller-wait settle, inbox wake,
+    // and the node-lifecycle classification of a row with no live broker) must
+    // all drop the human row before reading it.
     const t0 = Date.now();
     await superviseTick(t0);
     await superviseTick(t0 + 10_000_000);
-    // The startup recovery sweep is the sharper threat: it classifies every swept
-    // active|idle row as known-dead, so only its kind:'human' filter keeps the
-    // bridge row out of policy row 8 (boot failure).
-    await runStartupRecoverySweep(tf.fleet);
     assert.equal(getNode('HUMAN').status, 'active', 'human bridge row stays alive — never crash-reaped as a dead broker');
     assert.equal(readInboxSince('ASKER').length, 0, 'no surfaceBootFailure urgent push — the asker is never told its human prompt "never started"');
 });

package/dist/core/__tests__/integration/revive.test.js

@@ -226,7 +226,7 @@ test('reviveNode no-ops when the node has a live fleet entry — double-revive g
         });
         h.fleet.register(M, { pid: 424242, exited: new Promise(() => { }) });
         const before = h.node(M).cycles ?? 0;
-        const res = reviveNode(M, { resume: true });
+        const res = reviveNode(M, { resume: true, capacity: 'freeze' });
         assert.equal(res.resumed, false, 'guard path does not re-resume');
         assert.equal(h.node(M).cycles ?? 0, before, 'cycle counter NOT bumped (guard returned early)');
     }
@@ -254,7 +254,7 @@ test('reviveNode PROCEEDS when the node has NO fleet entry — cycle counter bum
             pi_session_file: sessionFile,
         });
         assert.equal(h.node(M).cycles ?? 0, 0, 'fabricated at cycle 0 (no revive yet)');
-        reviveNode(M, { resume: true });
+        reviveNode(M, { resume: true, capacity: 'freeze' });
         const after = h.node(M);
         assert.equal(after.cycles, 1, 'a real (non-guard) revive bumped the cycle counter to 1');
         assert.notEqual(after.pi_pid, stalePid, 'revive records the fresh broker pid immediately, not the stale dead pid');
@@ -298,11 +298,11 @@ test('a recovery relaunch keeps the armed deadline; a wake revive consumes it',
     try {
         const recovered = h.fabricateBrokerNode({ status: 'active', intent: null, pi_pid: deadPid(), pi_session_id: 'uuid-1' });
         armDeadline(recovered, 'cron-recovery');
-        reviveNode(recovered, { resume: true, recovery: true });
+        reviveNode(recovered, { resume: true, recovery: true, capacity: 'freeze' });
         assert.equal(hasPendingCancelOnWakeCron(recovered), true, 'the daemon replacing a dead broker is not a wake — the deadline survives so the wait can still settle');
         const woken = h.fabricateBrokerNode({ status: 'active', intent: null, pi_pid: deadPid(), pi_session_id: 'uuid-2' });
         armDeadline(woken, 'cron-wake');
-        reviveNode(woken, { resume: true });
+        reviveNode(woken, { resume: true, capacity: 'freeze' });
         assert.equal(hasPendingCancelOnWakeCron(woken), false, 'a wake revive won the race and cancels the deadline');
     }
     finally {
@@ -327,7 +327,7 @@ test('reviveNode fresh-fallback clears the stale session identity (Major-3: no p
             pi_session_id: 'uuid-stale',
             pi_session_file: missingFile,
         });
-        const res = reviveNode(M, { resume: true });
+        const res = reviveNode(M, { resume: true, capacity: 'freeze' });
         assert.equal(res.resumed, false, 'a missing .jsonl forces a fresh (non-resuming) launch');
         const after = h.node(M);
         assert.equal(after.pi_session_id, null, 'stale pi_session_id cleared before the fresh launch');
@@ -373,7 +373,7 @@ test('unbound forks replay one durable source file for node-id, path, and UUID o
         deleteNode('ordinary-fork-source');
         for (let index = 0; index < operands.length; index++) {
             const destination = `ordinary-fork-${index}`;
-            reviveNode(destination, { resume: index !== 1 });
+            reviveNode(destination, { resume: index !== 1, capacity: 'freeze' });
             const argv = launches[index];
             const fork = argv.indexOf('--fork');
             assert.equal(argv[fork + 1], forkFile, `${operands[index]} retries from the durable resolved file`);
@@ -406,7 +406,7 @@ test('reviveNode throws a typed cwd_missing error and does NOT crash the node wh
             pi_pid: deadPid(),
         });
         updateNode(M, { cwd: missingCwd });
-        assert.throws(() => reviveNode(M, { resume: true }), (e) => e instanceof InputError && e.payload.error === 'cwd_missing' && e.message.includes(missingCwd), 'reviveNode must throw a typed InputError naming the missing cwd path');
+        assert.throws(() => reviveNode(M, { resume: true, capacity: 'freeze' }), (e) => e instanceof InputError && e.payload.error === 'cwd_missing' && e.message.includes(missingCwd), 'reviveNode must throw a typed InputError naming the missing cwd path');
         const after = h.node(M);
         assert.equal(after.status, 'active', 'a cwd-missing preflight refusal must NOT crash the node (fixable in place, not a dead engine)');
     }
@@ -429,7 +429,7 @@ test('reviveNode crashes and clears pid when launch/preflight throws', async ()
             pi_session_file: sessionFile,
         });
         headlessBrokerHost.launch = (_nodeId, _inv, _opts) => { throw new Error('boom'); };
-        assert.throws(() => reviveNode(M, { resume: true }), /refusing to revive/i);
+        assert.throws(() => reviveNode(M, { resume: true, capacity: 'freeze' }), /refusing to revive/i);
         const after = h.node(M);
         assert.equal(after.status, 'dead', 'failed revive marks the node dead');
         assert.equal(after.pi_pid, null, 'failed revive clears the stale pid');
@@ -462,7 +462,7 @@ test('reviveNode fans a doctrine wake to subscribers when launch/preflight throw
         // was fabricated directly, not spawned through the CLI.
         subscribe(root, M, true);
         headlessBrokerHost.launch = (_nodeId, _inv, _opts) => { throw new Error('boom'); };
-        assert.throws(() => reviveNode(M, { resume: true }), /refusing to revive/i);
+        assert.throws(() => reviveNode(M, { resume: true, capacity: 'freeze' }), /refusing to revive/i);
         assert.equal(h.node(M).status, 'dead', 'failed revive marks the node dead');
         const entries = readInboxSince(root, undefined);
         const notice = entries.find((e) => e.data?.['reason'] === 'child-crashed' && e.data?.['child'] === M);
@@ -497,19 +497,19 @@ test('an unstarted node relaunches as a birth, not a "revived fresh" kickoff', (
         const missing = join(home, 'sessions', 'never-written.jsonl');
         // (1) Bare interactive node — nothing on disk anywhere: launch promptless.
         createNode(node('bare-unstarted', { cwd: home, pi_session_id: 'uuid-a', pi_session_file: missing }));
-        reviveNode('bare-unstarted', { resume: true });
+        reviveNode('bare-unstarted', { resume: true, capacity: 'freeze' });
         const bare = launches[0];
         assert.equal(bare.some((a) => isReviveKickoff(a)), false, 'an unstarted node is never told it lost context it never had');
         assert.deepEqual(bare, buildPiArgv(getNode('bare-unstarted'), {}).argv, 'a promptless boot — the argv carries no trailing prompt positional at all');
         // (2) Spawned with a mandate whose first turn never persisted: replay it.
         createNode(node('mandate-unstarted', { cwd: home, pi_session_id: 'uuid-b', pi_session_file: missing }));
         writeGoal('mandate-unstarted', 'do the thing');
-        reviveNode('mandate-unstarted', { resume: true });
+        reviveNode('mandate-unstarted', { resume: true, capacity: 'freeze' });
         assert.equal(launches[1].at(-1), 'do the thing', 'a birth replays the spawn mandate');
         // (3) Real durable progress on disk → still a genuine fresh revive.
         createNode(node('progressed', { cwd: home, pi_session_id: 'uuid-c', pi_session_file: missing }));
         seedRoadmap('progressed', { goal: 'ship it' });
-        reviveNode('progressed', { resume: true });
+        reviveNode('progressed', { resume: true, capacity: 'freeze' });
         assert.equal(isReviveKickoff(launches[2].at(-1)), true, 'a node with a roadmap still rebuilds from the kickoff');
     }
     finally {

package/dist/core/__tests__/integration/spawn-root.test.js

@@ -15,6 +15,8 @@ import { spawnNode } from '../../runtime/nodes.js';
 import { readGoal } from '../../runtime/kickoff.js';
 import { spawnChild, resolveSpawner } from '../../runtime/spawn.js';
 import { headlessBrokerHost } from '../../runtime/host.js';
+import { resetFleetForTests } from '../../runtime/fleet.js';
+import { bindTestFleet } from '../helpers/fleet.js';
 import { recordFault } from '../../runtime/fault.js';
 import { piSessionsRoot } from '../../runtime/pi-vendored.js';
 import { emptyContextExposureState, exposureTarget, loadContextExposureState, registerExposure, saveContextExposureState, } from '../../substrate/injected-store.js';
@@ -40,6 +42,9 @@ before(() => {
     process.env['CRTR_HOME'] = home;
     previousPidfile = process.env['CRTR_PIDFILE'];
     process.env['CRTR_PIDFILE'] = join(home, 'crtrd.pid');
+    // Every launcher claims a slot from the ledger before it reaches the host, so
+    // a spawn in-process needs a bound fleet (D-2).
+    bindTestFleet();
 });
 beforeEach(() => {
     closeDb();
@@ -52,6 +57,7 @@ beforeEach(() => {
 });
 after(() => {
     closeDb();
+    resetFleetForTests();
     rmSync(home, { recursive: true, force: true });
     if (previousPidfile === undefined)
         delete process.env['CRTR_PIDFILE'];

package/dist/core/__tests__/integration/worktree-reap.test.js

@@ -9,6 +9,9 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { gitSync } from '../../git.js';
 import { createManagedWorktree, closeManagedWorktree } from '../../worktree.js';
+import { createApiServer } from '../../../daemon/api/server.js';
+import { apiSocketPath } from '../../canvas/paths.js';
+import { CrtrClient } from '../../../api/index.js';
 import { createNode, getNode } from '../../canvas/canvas.js';
 import { closeDb } from '../../canvas/db.js';
 let home;
@@ -193,6 +196,35 @@ test('autoDropCleanManagedWorktree refuses a worktree with real uncommitted chan
     assert.equal(result, null, 'real uncommitted changes must never be silently dropped');
     assert.equal(getNode(nodeId)?.managed_worktree?.state, 'open');
 });
+test('abandon preserves committed and dirty work, records its retained tip, and releases finalization', async () => {
+    const nodeId = 'wt-abandon';
+    const wt = createManagedWorktree(sourceDir, nodeId);
+    writeFileSync(join(wt.path, 'committed.txt'), 'committed work\n');
+    run(['add', '.'], wt.path);
+    run(['-c', 'user.email=test@example.com', '-c', 'user.name=Test', 'commit', '-m', 'real work'], wt.path);
+    writeFileSync(join(wt.path, 'dirty.txt'), 'dirty work\n');
+    createNode(node(nodeId, { cwd: wt.path, status: 'done', managed_worktree: wt }));
+    const server = createApiServer();
+    try {
+        await new Promise((resolve) => setTimeout(resolve, 25));
+        const client = new CrtrClient({ socketPath: apiSocketPath(), autostart: false });
+        const result = await client.abandonWorktree(nodeId, { by: 'test-invoker' });
+        const meta = getNode(nodeId);
+        assert.equal(gitSync(['rev-parse', wt.branch], sourceDir).stdout.trim(), result.tip_sha, 'the retained branch names the recorded tip');
+        assert.equal(gitSync(['show', `${result.tip_sha}:committed.txt`], sourceDir).stdout, 'committed work\n', 'the pre-existing commit remains reachable');
+        assert.equal(gitSync(['show', `${result.tip_sha}:dirty.txt`], sourceDir).stdout, 'dirty work\n', 'the WIP commit preserves dirty work');
+        assert.equal(gitSync(['show', '-s', '--format=%an <%ae>%n%s%n%(trailers:only)', result.tip_sha], sourceDir).stdout, `crtr-abandon <crtr-abandon@localhost>\ncrtr-abandon\nCrtr-Abandon: ${nodeId} ${meta?.managed_worktree?.abandoned?.at}\n\n`, 'the WIP commit has the reserved author, subject sentinel, and durable trailer');
+        assert.equal(existsSync(wt.path), false, 'the checkout is removed');
+        assert.equal(meta?.managed_worktree?.state, 'abandoned', 'the node records the abandoned disposition');
+        assert.deepEqual(meta?.managed_worktree?.abandoned, { branch: wt.branch, tip_sha: result.tip_sha, at: meta?.managed_worktree?.abandoned?.at, by: 'test-invoker' }, 'the metadata names the retained tip and invoker');
+        assert.equal(meta?.cwd, wt.repo_root, 'the node cwd repoints to the repository root');
+        await client.pushReport(nodeId, { tier: 'final', body: 'abandoned work preserved' });
+        assert.ok(getNode(nodeId)?.final_report, 'push final proceeds after abandon releases the worktree gate');
+    }
+    finally {
+        await server.close();
+    }
+});
 // The actual #327 positive case: a branch with REAL commits whose tip is
 // already contained in a base that moved forward past this worktree's
 // original base_sha (a manager landed the same change another way, without

package/dist/core/__tests__/lifecycle-terminal-reasons.test.d.ts

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

package/dist/core/__tests__/lifecycle-terminal-reasons.test.js

@@ -0,0 +1,61 @@
+import { after, before, beforeEach, test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createNode, getNode } from '../canvas/canvas.js';
+import { closeDb } from '../canvas/db.js';
+import { transition } from '../runtime/lifecycle.js';
+let home;
+function seed(nodeId) {
+    const node = {
+        node_id: nodeId,
+        name: nodeId,
+        created: new Date().toISOString(),
+        cwd: '/tmp/work',
+        kind: 'general',
+        mode: 'base',
+        lifecycle: 'terminal',
+        status: 'active',
+    };
+    createNode(node);
+}
+function reason(nodeId) {
+    return getNode(nodeId)?.terminal_reason;
+}
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-lifecycle-reasons-'));
+    process.env['CRTR_HOME'] = home;
+});
+beforeEach(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+});
+after(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+    delete process.env['CRTR_HOME'];
+});
+test('transition records terminal reasons and clears them on terminal-to-live transitions', () => {
+    for (const [event, expected] of [
+        ['finish', 'finished'],
+        ['park', 'parked'],
+        ['cancel', 'stranded'],
+        ['crash', 'crashed'],
+        ['yield', null],
+        ['release', null],
+    ]) {
+        const nodeId = `event-${event}`;
+        seed(nodeId);
+        transition(nodeId, event);
+        assert.equal(reason(nodeId), expected, `${event} records its terminal reason`);
+    }
+    seed('refresh-launch');
+    transition('refresh-launch', 'cancel');
+    transition('refresh-launch', 'refresh-launch');
+    assert.equal(reason('refresh-launch'), null, 'refresh-launch clears a terminal reason');
+    seed('revive');
+    transition('revive', 'finish');
+    transition('revive', 'revive');
+    assert.equal(reason('revive'), null, 'revive clears a terminal reason');
+});

package/dist/core/__tests__/migration.test.js

@@ -215,6 +215,43 @@ test('a fresh db has the four additive runtime columns', () => {
     assert.equal(rt['window'], null);
     assert.equal(rt['tmux_session'], null);
 });
+test('node lifecycle substrate migration adds six columns and backfills terminal reasons', () => {
+    ensureHome();
+    const raw = new DatabaseSync(canvasDbPath());
+    migrateToVersion(raw, 34);
+    const lifecycleColumns = [
+        'frozen_at',
+        'respawn_failures',
+        'respawn_not_before',
+        'launched_at',
+        'last_settled_at',
+        'terminal_reason',
+    ];
+    for (const column of lifecycleColumns)
+        assert.ok(!nodeColumns(raw).includes(column));
+    const insert = raw.prepare('INSERT INTO nodes (node_id, name, kind, status, intent, final_report, cwd, created) VALUES (?, ?, ?, ?, ?, ?, ?, ?)');
+    const created = '2020-01-01T00:00:00Z';
+    insert.run('finalized', 'finalized', 'general', 'done', 'done', 'final.md', '/tmp', created);
+    insert.run('parked', 'parked', 'general', 'done', 'parked', null, '/tmp', created);
+    insert.run('finished', 'finished', 'general', 'done', 'done', null, '/tmp', created);
+    insert.run('stranded', 'stranded', 'general', 'canceled', null, null, '/tmp', created);
+    insert.run('crashed', 'crashed', 'general', 'dead', null, null, '/tmp', created);
+    insert.run('active', 'active', 'general', 'active', null, null, '/tmp', created);
+    raw.close();
+    const db = openDb();
+    assert.equal(userVersion(db), MIGRATIONS.length);
+    for (const column of lifecycleColumns)
+        assert.ok(nodeColumns(db).includes(column));
+    const reasons = Object.fromEntries(db.prepare('SELECT node_id, terminal_reason FROM nodes ORDER BY node_id').all().map((row) => [row.node_id, row.terminal_reason]));
+    assert.deepEqual(reasons, {
+        active: null,
+        crashed: 'crashed',
+        finalized: 'finalized',
+        finished: 'finished',
+        parked: 'parked',
+        stranded: 'stranded',
+    });
+});
 // v4: edges FK ON DELETE CASCADE (the one irreversible rebuild)
 /** Build a hand-rolled db at exactly v3 (baseline tables + the four runtime
  *  columns, edges with NO foreign key, `user_version = 3`) — the shape the live
@@ -337,7 +374,7 @@ test('v16 repairs a v15 database missing canonical finalization columns', () =>
     ensureHome();
     const db = new DatabaseSync(join(home, 'finalization.db'));
     try {
-        MIGRATIONS[0](db);
+        migrateToVersion(db, 13);
         db.exec('PRAGMA user_version = 15');
         migrate(db);
         const columns = nodeColumns(db);

package/dist/core/__tests__/push-final-guard.test.js

@@ -179,6 +179,6 @@ test('reviveNode refuses to revive a node that became finalized after the caller
     process.env['CRTR_NODE_ID'] = id;
     await pushFinal(id, 'concurrent final');
     assert.equal(getNode(id)?.status, 'done');
-    assert.throws(() => reviveNode(id, { resume: true }), /finaliz/i, 'reviveNode\'s own belt-and-suspenders check refuses a now-latched target');
+    assert.throws(() => reviveNode(id, { resume: true, capacity: 'freeze' }), /finaliz/i, 'reviveNode\'s own belt-and-suspenders check refuses a now-latched target');
     assert.equal(getNode(id)?.status, 'done', 'the node stays done, never silently revived into an unsatisfiable mandate');
 });

package/dist/core/__tests__/revive-capacity.test.d.ts

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