@north-light/crouter 0.3.263 → 0.3.270

package/dist/core/__tests__/integration/lifecycle-hooks.test.js

@@ -0,0 +1,182 @@
+import assert from 'node:assert/strict';
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import test from 'node:test';
+import { contextDir, jobDir, nodeDir, reportsDir } from '../../canvas/paths.js';
+import { validateHookManifest } from '../../command-hooks/schema.js';
+import { headlessBrokerHost } from '../../runtime/host.js';
+import { reviveNode } from '../../runtime/revive.js';
+import { createHarness } from '../helpers/harness.js';
+function installLifecyclePlugin(harness, name, op) {
+    const ops = typeof op === 'string' ? [op] : op;
+    const root = join(harness.agentHome, '.crouter', 'plugins', name);
+    mkdirSync(join(root, '.crouter-plugin'), { recursive: true });
+    writeFileSync(join(root, '.crouter-plugin', 'plugin.json'), JSON.stringify({
+        name,
+        version: '0.1.0',
+        description: 'lifecycle hook fixture',
+        hooks: 'hooks.json',
+        hookExecutable: 'bin/hook.js',
+    }));
+    writeFileSync(join(root, 'hooks.json'), JSON.stringify({
+        schemaVersion: 2,
+        lifecycle: ops.map((entry) => ({ event: 'node:start', phase: 'on', op: entry, description: `${entry} fixture`, effects: ['writes fixture state'] })),
+    }));
+    const executable = join(root, 'bin', 'hook.js');
+    mkdirSync(join(root, 'bin'), { recursive: true });
+    writeFileSync(executable, `#!/usr/bin/env node
+const { existsSync, writeFileSync } = require('node:fs');
+const { join } = require('node:path');
+let input = '';
+process.stdin.on('data', (chunk) => { input += chunk; });
+process.stdin.on('end', () => {
+  const request = JSON.parse(input);
+  writeFileSync(join(request.node.contextDir, 'lifecycle-order'), request.op + '\\n', { flag: 'a' });
+  if (request.op === 'record') writeFileSync(join(request.node.contextDir, 'lifecycle-request.json'), JSON.stringify(request));
+  if (request.op === 'hang') {
+    writeFileSync(join(request.node.contextDir, 'lifecycle-hang-started'), 'started');
+    setInterval(() => {}, 1000);
+    return;
+  }
+  if (request.op === 'bad') {
+    process.stdout.write('not a JSON envelope');
+    return;
+  }
+  if (request.op === 'nonzero') {
+    writeFileSync(join(request.node.contextDir, 'lifecycle-nonzero-started'), 'started');
+    process.stdout.write(JSON.stringify({ protocolVersion: 1, ok: true }));
+    process.exitCode = 1;
+    return;
+  }
+  process.stdout.write(JSON.stringify({ protocolVersion: 1, ok: true }));
+});
+`);
+    chmodSync(executable, 0o755);
+}
+function installV1CommandHook(harness) {
+    const root = join(harness.agentHome, '.crouter', 'plugins', 'z-v1-command');
+    mkdirSync(join(root, '.crouter-plugin'), { recursive: true });
+    writeFileSync(join(root, '.crouter-plugin', 'plugin.json'), JSON.stringify({
+        name: 'z-v1-command', version: '0.1.0', description: 'v1 command hook fixture', hooks: 'hooks.json', hookExecutable: 'bin/hook.js',
+    }));
+    writeFileSync(join(root, 'hooks.json'), JSON.stringify({
+        schemaVersion: 1,
+        hooks: [{ target: 'sys version', phase: 'before', op: 'v1_check', description: 'v1 command hook', effects: ['writes fixture state'] }],
+    }));
+    const executable = join(root, 'bin', 'hook.js');
+    mkdirSync(join(root, 'bin'), { recursive: true });
+    writeFileSync(executable, `#!/usr/bin/env node
+const { writeFileSync } = require('node:fs');
+const { join } = require('node:path');
+let input = '';
+process.stdin.on('data', (chunk) => { input += chunk; });
+process.stdin.on('end', () => {
+  JSON.parse(input);
+  writeFileSync(join(__dirname, '..', 'v1-ran'), 'ran');
+  process.stdout.write(JSON.stringify({ protocolVersion: 1, ok: true }));
+});
+`);
+    chmodSync(executable, 0o755);
+    return join(root, 'v1-ran');
+}
+test('node:start hooks receive resolved paths before broker launch; invalid and hanging hooks do not block launch', async () => {
+    const harness = await createHarness({ headless: true, sessionPrefix: 'crtr-lifecycle-hooks' });
+    const originalLaunch = headlessBrokerHost.launch;
+    try {
+        installLifecyclePlugin(harness, 'aa-lifecycle-order', ['first', 'second']);
+        installLifecyclePlugin(harness, 'a-lifecycle-record', 'record');
+        installLifecyclePlugin(harness, 'b-lifecycle-bad', 'bad');
+        installLifecyclePlugin(harness, 'c-lifecycle-nonzero', 'nonzero');
+        installLifecyclePlugin(harness, 'd-lifecycle-hang', 'hang');
+        const v1Marker = installV1CommandHook(harness);
+        const show = harness.cli(null, ['--json', 'pkg', 'plugin', 'show', 'a-lifecycle-record', '--scope', 'user']);
+        assert.equal(show.code, 0, show.stderr);
+        assert.deepEqual(show.json.hooks.lifecycle, [{
+                event: 'node:start', phase: 'on', op: 'record', description: 'record fixture', effects: ['writes fixture state'],
+            }]);
+        const doctor = harness.cli(null, ['--json', 'sys', 'doctor', '--scope', 'user']);
+        assert.equal(doctor.code, 0, doctor.stderr);
+        const hookCheck = doctor.json.checks.find((check) => check.name === 'plugin:a-lifecycle-record:hooks');
+        assert.match(hookCheck?.message ?? '', /node:start \[on record; effects: writes fixture state\]/);
+        const nodeId = harness.fabricateBrokerNode({ id: 'lifecycle-hook-node', pi_pid: null, pi_session_id: null, pi_session_file: null });
+        const requestPath = join(contextDir(nodeId), 'lifecycle-request.json');
+        let requestExistedBeforeLaunch = false;
+        headlessBrokerHost.launch = ((id, ...args) => {
+            if (id === nodeId)
+                requestExistedBeforeLaunch = existsSync(requestPath);
+            return originalLaunch.call(headlessBrokerHost, id, ...args);
+        });
+        const startedAt = Date.now();
+        const starting = reviveNode(nodeId, { resume: false, capacity: 'freeze' });
+        const contender = await reviveNode(nodeId, { resume: false, capacity: 'freeze' });
+        const result = await starting;
+        const elapsedMs = Date.now() - startedAt;
+        await harness.awaitBoot(nodeId);
+        assert.equal(result.outcome, 'launched');
+        assert.equal(contender.outcome, 'already-live', 'a concurrent revive cannot cross the awaited hook gap');
+        assert.equal(requestExistedBeforeLaunch, true, 'the lifecycle hook finishes before broker launch');
+        assert.equal(existsSync(join(contextDir(nodeId), 'lifecycle-nonzero-started')), true, 'a non-zero executable ran without blocking launch');
+        assert.equal(existsSync(join(contextDir(nodeId), 'lifecycle-hang-started')), true, 'the hanging executable started and was subject to the lifecycle timeout');
+        assert.ok(elapsedMs >= 4_500 && elapsedMs < 8_000, `the 5s hanging hook was bounded before launch (${elapsedMs}ms)`);
+        assert.deepEqual(readFileSync(join(contextDir(nodeId), 'lifecycle-order'), 'utf8').trim().split('\n'), ['record', 'first', 'second', 'bad', 'nonzero', 'hang'], 'lifecycle hooks preserve plugin-name then declaration-index discovery order');
+        assert.equal(existsSync(v1Marker), false, 'a command-only v1 manifest adds no node-start subprocess');
+        const request = JSON.parse(readFileSync(requestPath, 'utf8'));
+        assert.equal(request.protocolVersion, 1);
+        assert.equal(request.op, 'record');
+        assert.equal(request.event, 'node:start');
+        assert.equal(request.phase, 'on');
+        assert.match(request.operationId, /^[0-9a-f]{32}$/);
+        assert.deepEqual(request.context, { cwd: harness.node(nodeId).cwd });
+        assert.deepEqual(request.node, {
+            id: nodeId,
+            name: nodeId,
+            kind: 'developer',
+            mode: 'base',
+            lifecycle: 'terminal',
+            cwd: harness.node(nodeId).cwd,
+            nodeDir: nodeDir(nodeId),
+            contextDir: contextDir(nodeId),
+            jobDir: jobDir(nodeId),
+            reportsDir: reportsDir(nodeId),
+        });
+        assert.deepEqual(request.runtime, { isBirth: true, canvasHome: harness.home, profile: null });
+        const v1Command = harness.cli(null, ['--json', 'sys', 'version']);
+        assert.equal(v1Command.code, 0, v1Command.stderr);
+        assert.equal(existsSync(v1Marker), true, 'a v1 command hook still executes around its declared command');
+    }
+    finally {
+        headlessBrokerHost.launch = originalLaunch;
+        await harness.dispose();
+    }
+});
+test('hooks.json v1 remains command-only while v2 accepts a lifecycle-only declaration', () => {
+    const v1 = validateHookManifest({
+        schemaVersion: 1,
+        hooks: [{ target: 'canvas list', phase: 'before', op: 'check', description: 'check', effects: ['writes a log'] }],
+    });
+    assert.deepEqual(v1, {
+        manifest: {
+            schemaVersion: 1,
+            hooks: [{ target: 'canvas list', phase: 'before', op: 'check', description: 'check', effects: ['writes a log'] }],
+        },
+        issues: [],
+    });
+    const v2 = validateHookManifest({
+        schemaVersion: 2,
+        lifecycle: [{ event: 'node:start', phase: 'on', op: 'prepare', description: 'prepare', effects: ['creates a directory'] }],
+    });
+    assert.deepEqual(v2.issues, []);
+    assert.deepEqual(v2.manifest, {
+        schemaVersion: 2,
+        hooks: [],
+        lifecycle: [{ event: 'node:start', phase: 'on', op: 'prepare', description: 'prepare', effects: ['creates a directory'] }],
+    });
+    for (const manifest of [
+        { schemaVersion: 2, hooks: [], lifecycle: [] },
+        { schemaVersion: 2, lifecycle: [{ event: 'node:stop', phase: 'on', op: 'prepare', description: 'prepare', effects: ['creates a directory'] }] },
+        { schemaVersion: 2, lifecycle: [{ event: 'node:start', phase: 'before', op: 'prepare', description: 'prepare', effects: ['creates a directory'] }] },
+        { schemaVersion: 2, lifecycle: [{ event: 'node:start', phase: 'on', op: 'prepare', description: 'prepare', effects: ['creates a directory'], unexpected: true }] },
+    ]) {
+        assert.equal(validateHookManifest(manifest).manifest, undefined, 'invalid v2 lifecycle declarations are rejected');
+    }
+});

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

@@ -180,7 +180,8 @@ test('a resumed revive replays the persisted LaunchSpec (model, tools, extension
         pi_session_id: 'uuid-9',
         pi_session_file: sessionFile,
         launch: {
-            model: 'anthropic/sonnet',
+            model: 'anthropic/claude-opus-5:high',
+            modelExact: true,
             tools: ['bash', 'read'],
             extensions: ['/ext/a.js', '/ext/b.js'],
             systemPrompt: 'You are a developer orchestrator.',
@@ -196,7 +197,8 @@ test('a resumed revive replays the persisted LaunchSpec (model, tools, extension
     assert.equal(argv[ea - 1], '-e');
     // Model + tools + system prompt + resume target.
     const mi = argv.indexOf('--model');
-    assert.equal(argv[mi + 1], 'anthropic/sonnet');
+    assert.equal(argv[mi + 1], 'anthropic/claude-opus-5:high');
+    assert.ok(argv.includes('--crtr-model-exact'), 'revive preserves the exact-model contract');
     const ti = argv.indexOf('--tools');
     assert.equal(argv[ti + 1], 'bash,read');
     assert.ok(argv.includes('--append-system-prompt'), 'system prompt replayed');
@@ -229,7 +231,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, capacity: 'freeze' });
+        const res = await 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)');
     }
@@ -257,7 +259,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, capacity: 'freeze' });
+        await 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');
@@ -301,11 +303,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, capacity: 'freeze' });
+        await 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, capacity: 'freeze' });
+        await reviveNode(woken, { resume: true, capacity: 'freeze' });
         assert.equal(hasPendingCancelOnWakeCron(woken), false, 'a wake revive won the race and cancels the deadline');
     }
     finally {
@@ -356,7 +358,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, capacity: 'freeze' });
+        const res = await 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');
@@ -368,7 +370,7 @@ test('reviveNode fresh-fallback clears the stale session identity (Major-3: no p
         await h.dispose();
     }
 });
-test('unbound forks replay one durable source file for node-id, path, and UUID operands', () => {
+test('unbound forks replay one durable source file for node-id, path, and UUID operands', async () => {
     const originalLaunch = headlessBrokerHost.launch;
     const tf = bindTestFleet();
     const forkFile = join(home, 'ordinary-fork-source.jsonl');
@@ -402,7 +404,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, capacity: 'freeze' });
+            await 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`);
@@ -435,7 +437,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, 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');
+        await assert.rejects(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)');
     }
@@ -453,7 +455,7 @@ test('reviveNode relaunches fresh when the session header cwd was removed (NL-14
         const M = h.fabricateBrokerNode({
             status: 'active', intent: null, pi_pid: deadPid(), pi_session_id: 'stale-session', pi_session_file: sessionFile,
         });
-        const result = reviveNode(M, { resume: true, capacity: 'freeze', recovery: true });
+        const result = await reviveNode(M, { resume: true, capacity: 'freeze', recovery: true });
         assert.equal(result.resumed, false, 'the missing session cwd vetoes --session and launches fresh');
         assert.equal(h.node(M)?.pi_session_id, null, 'the stale session id is cleared before the fresh launch');
         assert.equal(h.node(M)?.pi_session_file, null, 'the stale session file is cleared before the fresh launch');
@@ -477,7 +479,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, capacity: 'freeze' }), /refusing to revive/i);
+        await assert.rejects(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');
@@ -510,7 +512,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, capacity: 'freeze' }), /refusing to revive/i);
+        await assert.rejects(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);
@@ -530,7 +532,7 @@ test('reviveNode fans a doctrine wake to subscribers when launch/preflight throw
 // nothing. It woke, flailed over an empty context dir and reported itself
 // confused. Such a relaunch is a BIRTH: replay the spawn mandate if there is
 // one, else boot promptless and take no turn at all.
-test('an unstarted node relaunches as a birth, not a "revived fresh" kickoff', () => {
+test('an unstarted node relaunches as a birth, not a "revived fresh" kickoff', async () => {
     const originalLaunch = headlessBrokerHost.launch;
     const tf = bindTestFleet();
     const launches = [];
@@ -545,19 +547,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, capacity: 'freeze' });
+        await 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, capacity: 'freeze' });
+        await 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, capacity: 'freeze' });
+        await 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__/model-pin-durability.test.js

@@ -20,7 +20,7 @@ import { join } from 'node:path';
 import { buildLaunchSpec, isProviderPinnedModelToken, normalizeModel } from '../runtime/launch.js';
 import { defaultModelLaddersConfig } from '../../types.js';
 import { persistDormantModel } from '../runtime/model-swap.js';
-import { promote } from '../runtime/promote.js';
+import { promote, reshapeNode } from '../runtime/promote.js';
 import { createNode, getNode } from '../canvas/canvas.js';
 import { closeDb } from '../canvas/db.js';
 const ladders = defaultModelLaddersConfig();
@@ -86,6 +86,15 @@ test('only concrete provider/id tokens pin; logical family/tier refs remain pref
     assert.equal(isProviderPinnedModelToken('ultra'), false, 'a bare tier has no `/` and stays unpinned');
     assert.equal(isProviderPinnedModelToken('opus'), false, 'a bare family alias has no `/` and stays unpinned');
 });
+test('a new --model override resolves once and freezes portable and concrete requests', () => {
+    for (const requested of ['anthropic/opus', 'strong', 'anthropic/claude-fable-5:high']) {
+        const launch = buildSpec({ model: requested, modelOverride: true });
+        assert.equal(launch.model, normalizeModel(requested, ladders), `${requested} resolves through the configured ladder`);
+        assert.equal(launch.modelExact, true, `${requested} is exact after resolution`);
+        assert.equal(launch.modelIntent, undefined, `${requested} has no portable route intent`);
+        assert.equal(launch.env.CRTR_MODEL_INTENT, undefined, `${requested} cannot re-enable fallback on revive`);
+    }
+});
 // Direction 1: an EXPLICIT concrete pin must SURVIVE a config/lifecycle rebuild
 // even when the carried override has portablized back to a bare tier.
 test('an explicit concrete pin survives a config/lifecycle rebuild whose portablized override reads as a bare tier', () => {
@@ -103,6 +112,20 @@ test('an explicit concrete pin survives a config/lifecycle rebuild whose portabl
 // Direction 2: a deliberately TIER-run (unpinned) node must NOT be wrongly
 // re-pinned when a subsequent rebuild/persist normalizes its override to the
 // concrete cell it happens to share bytes with.
+test('reshape resolves and persists a new --model override as the exact revive recipe', () => {
+    createNode(node('override-node', {
+        model_override: 'strong',
+        launch: { extensions: [], env: { CRTR_MODEL_INTENT: 'anthropic/strong' }, model: normalizeModel('strong', ladders), modelIntent: { family: 'anthropic', strength: 'strong' } },
+    }));
+    reshapeNode('override-node', { model: 'anthropic/opus' });
+    const after = getNode('override-node');
+    const expected = normalizeModel('anthropic/opus', ladders);
+    assert.equal(after?.model_override, expected, 'the raw alias never becomes the durable override');
+    assert.equal(after?.launch?.model, expected, 'revive replays the resolved provider/model');
+    assert.equal(after?.launch?.modelExact, true, 'retries and revives reject substitutes');
+    assert.equal(after?.launch?.modelIntent, undefined);
+    assert.equal(after?.launch?.env.CRTR_MODEL_INTENT, undefined);
+});
 test('promotion preserves the exact-model contract required to revive a private human-work fork', () => {
     const exactModel = 'openai-codex/gpt-5.6-sol:max';
     createNode(node('exact-node', {
@@ -134,6 +157,7 @@ test('a deliberately tier-run node is not wrongly re-pinned when a rebuild or pe
     const after = getNode('tier-node');
     assert.equal(after?.launch?.model, ULTRA_CELL, 'the concrete spec is persisted as the launch model');
     assert.equal(after?.model_override, ULTRA_CELL, 'the concrete spec is persisted as the override');
+    assert.equal(after?.launch?.modelExact, true, 'an explicit model change remains exact on revive');
     assert.equal(after?.launch?.modelIntent, undefined, 'an explicit concrete choice clears the prior logical route intent');
     assert.equal(after?.launch?.env.CRTR_MODEL_INTENT, undefined, 'the revived broker does not inherit the prior logical route intent');
     assert.equal(after?.launch?.modelProviderPinned, false, 'an explicit bare-tier decision clears a prior pin — the raw-token decision wins over the concrete spec shape');

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, capacity: 'freeze' }), /finaliz/i, 'reviveNode\'s own belt-and-suspenders check refuses a now-latched target');
+    await assert.rejects(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__/relaunch-root.test.js

@@ -18,6 +18,7 @@ import { createNode, getNode, subscribe } from '../canvas/canvas.js';
 import { closeDb } from '../canvas/db.js';
 import { apiSocketPath } from '../canvas/paths.js';
 import { brokerCapReached, resetFleetForTests } from '../runtime/fleet.js';
+import { buildPiArgv } from '../runtime/launch.js';
 import { relaunchRoot } from '../runtime/reset.js';
 import { bindTestFleet } from './helpers/fleet.js';
 let home;
@@ -106,6 +107,22 @@ test('relaunchRoot parks the old root done and mints a fresh active root, reapin
     assert.equal(getNode('child')?.status, 'canceled', 'descendant child canceled');
     assert.equal(getNode('grand')?.status, 'canceled', 'descendant grandchild canceled');
 });
+test('relaunchRoot preserves an explicit model override as an exact replay recipe', async () => {
+    const exactModel = 'anthropic/claude-opus-5:high';
+    createNode(node('root', {
+        parent: null,
+        lifecycle: 'resident',
+        model_override: exactModel,
+        launch: { extensions: [], env: {}, model: exactModel, modelExact: true },
+    }));
+    const { deps } = makeDeps(4242);
+    const result = await relaunchRoot('root', deps);
+    assert.ok(result);
+    const replacement = getNode(result.newNodeId);
+    assert.equal(replacement?.launch?.model, exactModel);
+    assert.equal(replacement?.launch?.modelExact, true, 'the replacement cannot route away from the override');
+    assert.ok(buildPiArgv(replacement, {}).argv.includes('--crtr-model-exact'), 'broker replay preserves the exact-model contract');
+});
 test('relaunchRoot on a boot failure leaves the old root + descendants fully intact', async () => {
     // The mint-and-boot-FIRST ordering: a launch failure (pid=null) must occur
     // BEFORE the old root is parked or its descendants reaped.

package/dist/core/__tests__/revive-capacity.test.js

@@ -52,9 +52,9 @@ function node(id, over = {}) {
     return id;
 }
 /** Fill the ledger to the cap with live brokers. */
-function saturate() {
-    reviveNode(node(`filler-a-${seq}`), { resume: false, capacity: 'refuse' });
-    reviveNode(node(`filler-b-${seq}`), { resume: false, capacity: 'refuse' });
+async function saturate() {
+    await reviveNode(node(`filler-a-${seq}`), { resume: false, capacity: 'refuse' });
+    await reviveNode(node(`filler-b-${seq}`), { resume: false, capacity: 'refuse' });
     assert.equal(tf.fleet.size(), 2, 'precondition: the ledger is at its cap of 2');
 }
 before(() => {
@@ -78,10 +78,10 @@ after(() => {
     delete process.env['CRTR_HOME'];
     rmSync(home, { recursive: true, force: true });
 });
-test('a refusing caller gets an error naming the cap and the live count, never a silent no-op', () => {
-    saturate();
+test('a refusing caller gets an error naming the cap and the live count, never a silent no-op', async () => {
+    await saturate();
     const turned = node('refused', { pi_session_id: 'sess-refused' });
-    assert.throws(() => reviveNode(turned, { resume: true, capacity: 'refuse' }), (err) => {
+    await assert.rejects(() => reviveNode(turned, { resume: true, capacity: 'refuse' }), (err) => {
         const details = err.details ?? {};
         assert.equal(details['error'], 'broker_cap_reached', 'the refusal is a typed InputError, so it survives the /v1 error body');
         assert.match(String(details['message']), /2 live brokers at the cap of 2/, 'the message names both the live count and the cap');
@@ -110,21 +110,21 @@ test('a pre-spawn launch failure releases the reservation', () => {
         stubLaunch();
     }
 });
-test('a freezing caller gets a frozen row, marked once and left otherwise untouched', () => {
-    saturate();
+test('a freezing caller gets a frozen row, marked once and left otherwise untouched', async () => {
+    await saturate();
     const waiting = node('frozen', { pi_session_id: 'sess-frozen' });
-    const first = reviveNode(waiting, { resume: true, capacity: 'freeze' });
+    const first = await reviveNode(waiting, { resume: true, capacity: 'freeze' });
     assert.equal(first.outcome, 'frozen', 'the caller learns it got no engine');
     const marked = getNode(waiting);
     assert.ok(marked.frozen_at != null, 'the row carries the durable wait mark the thaw order reads');
     assert.equal(marked.pi_pid ?? null, null, 'a frozen row holds no pid — every status surface reads it as frozen, not stale-active');
     assert.equal(marked.cycles ?? 0, 0, 'a frozen node never spent a cycle');
-    const second = reviveNode(waiting, { resume: true, capacity: 'freeze' });
+    const second = await reviveNode(waiting, { resume: true, capacity: 'freeze' });
     assert.equal(second.outcome, 'frozen');
     assert.equal(getNode(waiting).frozen_at, marked.frozen_at, 'freezing is once-per-episode: a second saturated tick keeps the original wait timestamp');
 });
 test('a durable daemon message reports capacity_frozen when its wake cannot launch', async () => {
-    saturate();
+    await saturate();
     const waiting = node('message-frozen');
     const delivery = await deliverNodeMessage({
         node_id: waiting,
@@ -137,26 +137,26 @@ test('a durable daemon message reports capacity_frozen when its wake cannot laun
     assert.equal(delivery.revived, false);
     assert.equal(delivery.reason, 'capacity_frozen');
 });
-test('an already-live node is admitted at the cap — it consumes no new slot', () => {
+test('an already-live node is admitted at the cap — it consumes no new slot', async () => {
     const live = node('already-live');
-    reviveNode(live, { resume: false, capacity: 'refuse' });
-    reviveNode(node('already-live-filler'), { resume: false, capacity: 'refuse' });
+    await reviveNode(live, { resume: false, capacity: 'refuse' });
+    await reviveNode(node('already-live-filler'), { resume: false, capacity: 'refuse' });
     assert.equal(tf.fleet.size(), 2, 'precondition: this node holds one of the two slots, and the ledger is full');
     // Both dispositions agree: liveness is answered before capacity ever is.
-    assert.equal(reviveNode(live, { resume: true, capacity: 'refuse' }).outcome, 'already-live');
-    assert.equal(reviveNode(live, { resume: true, capacity: 'freeze' }).outcome, 'already-live');
+    assert.equal((await reviveNode(live, { resume: true, capacity: 'refuse' })).outcome, 'already-live');
+    assert.equal((await reviveNode(live, { resume: true, capacity: 'freeze' })).outcome, 'already-live');
     assert.equal(getNode(live).frozen_at ?? null, null, 'a live node is never marked as waiting for a slot');
 });
 test('a freed slot lets the frozen row launch, and the launch retires the mark', async () => {
     const filler = node('filler-exits');
-    reviveNode(filler, { resume: false, capacity: 'refuse' });
-    reviveNode(node('filler-stays'), { resume: false, capacity: 'refuse' });
+    await reviveNode(filler, { resume: false, capacity: 'refuse' });
+    await reviveNode(node('filler-stays'), { resume: false, capacity: 'refuse' });
     const waiting = node('thaws', { pi_session_id: 'sess-thaws' });
-    assert.equal(reviveNode(waiting, { resume: true, capacity: 'freeze' }).outcome, 'frozen');
+    assert.equal((await reviveNode(waiting, { resume: true, capacity: 'freeze' })).outcome, 'frozen');
     // A real exit frees the slot; its policy job runs on the lane like production.
     tf.fleet.deliverExit(filler, { code: 0, signal: null });
     await tf.drain();
-    assert.equal(reviveNode(waiting, { resume: true, capacity: 'freeze' }).outcome, 'launched');
+    assert.equal((await reviveNode(waiting, { resume: true, capacity: 'freeze' })).outcome, 'launched');
     assert.equal(getNode(waiting).frozen_at ?? null, null, 'a launch is the definition of not-frozen');
     assert.equal(tf.fleet.has(waiting), true, 'the thawed node owns the freed slot');
 });

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

@@ -103,10 +103,10 @@ 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', () => {
+test('a parked node with mail waiting re-enters fresh even when the caller asked to resume, and the marker clears', async () => {
     parkResident('parked', { roadmap: '# Roadmap\n\n- one open item\n' });
     deliverMail('parked');
-    const result = reviveNode('parked', { resume: true, capacity: 'freeze' });
+    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');
@@ -115,15 +115,15 @@ test('a parked node with mail waiting re-enters fresh even when the caller asked
     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');
 });
-test('a parked node grounded only by a goal still re-enters fresh when mail rides the revive', () => {
+test('a parked node grounded only by a goal still re-enters fresh when mail rides the revive', async () => {
     parkResident('goal-only', { goal: 'Watch the deploy lane.' });
     deliverMail('goal-only');
-    assert.equal(reviveNode('goal-only', { resume: true, capacity: 'freeze' }).resumed, false);
+    assert.equal((await reviveNode('goal-only', { resume: true, capacity: 'freeze' })).resumed, false);
     assert.equal(kickedOff(launches[0]), true);
 });
-test('an input-less revival of a parked node quietly resumes and injects no kickoff', () => {
+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' });
-    const result = reviveNode('quiet', { resume: true, capacity: 'freeze' });
+    const result = await reviveNode('quiet', { resume: true, capacity: 'freeze' });
     assert.equal(result.resumed, true, 'nothing arrived, so there is nothing a fresh window would answer');
     assert.deepEqual(placements(), [{ nodeId: 'quiet', resuming: true }]);
     assert.equal(kickedOff(launches[0]), false, 'a quiet resume generates nothing');
@@ -132,29 +132,29 @@ test('an input-less revival of a parked node quietly resumes and injects no kick
     assert.equal(reopened.status, 'active');
     assert.equal(reopened.intent ?? null, null, 'the park marker clears on a quiet resume too');
 });
-test('deferred mail alone is not input, so the revival still resumes quietly', () => {
+test('deferred mail alone is not input, so the revival still resumes quietly', async () => {
     parkResident('deferred', { roadmap: '# Roadmap\n\n- one open item\n' });
     deliverMail('deferred', 'deferred');
-    assert.equal(reviveNode('deferred', { resume: true, capacity: 'freeze' }).resumed, true);
+    assert.equal((await reviveNode('deferred', { resume: true, capacity: 'freeze' })).resumed, true);
     assert.equal(kickedOff(launches[0]), false);
     assert.equal(readCursor('deferred'), undefined, 'the deferred entry rides the next natural cycle, unconsumed');
 });
-test('mail already covered by the cursor is not input, so the revival still resumes quietly', () => {
+test('mail already covered by the cursor is not input, so the revival still resumes quietly', async () => {
     parkResident('stale', { roadmap: '# Roadmap\n\n- one open item\n' });
     writeCursor('stale', deliverMail('stale'));
-    assert.equal(reviveNode('stale', { resume: true, capacity: 'freeze' }).resumed, true, 'only the UNSEEN suffix counts as input');
+    assert.equal((await reviveNode('stale', { resume: true, capacity: 'freeze' })).resumed, true, 'only the UNSEEN suffix counts as input');
     assert.equal(kickedOff(launches[0]), false);
 });
-test('a parked node with no goal and no roadmap resumes its transcript rather than waking amnesiac', () => {
+test('a parked node with no goal and no roadmap resumes its transcript rather than waking amnesiac', async () => {
     parkResident('bare');
     deliverMail('bare');
-    const result = reviveNode('bare', { resume: true, capacity: 'freeze' });
+    const result = await reviveNode('bare', { resume: true, capacity: 'freeze' });
     assert.equal(result.resumed, true, 'the degraded park has nothing on disk to ground a fresh window');
     assert.deepEqual(placements(), [{ nodeId: 'bare', resuming: true }]);
 });
-test('an ordinary done node with a roadmap still resumes — only the park marker vetoes', () => {
+test('an ordinary done node with a roadmap still resumes — only the park marker vetoes', async () => {
     parkResident('finished', { roadmap: '# Roadmap\n\n- one open item\n' });
     transition('finished', 'revive');
     transition('finished', 'finish');
-    assert.equal(reviveNode('finished', { resume: true, capacity: 'freeze' }).resumed, true);
+    assert.equal((await reviveNode('finished', { resume: true, capacity: 'freeze' })).resumed, true);
 });

package/dist/core/__tests__/seam/broker-cap-freeze.test.js

@@ -117,7 +117,7 @@ test('a birth at the cap freezes instead of booting, survives saturated ticks, a
     const filler = await h.spawnHeadlessChild(root, 'terminal thaw filler');
     assert.equal(h.fleet.size(), 2, 'the parked target is non-live while the cap remains full');
     appendInbox(second, { from: root, tier: 'normal', kind: 'message', label: 'durable wake' });
-    assert.equal(reviveNode(second, { resume: true, capacity: 'freeze' }).outcome, 'frozen');
+    assert.equal((await reviveNode(second, { resume: true, capacity: 'freeze' })).outcome, 'frozen');
     closeDb();
     const frozenTerminal = h.node(second);
     assert.equal(frozenTerminal.status, 'done', 'freezing preserves the terminal status');
@@ -144,7 +144,7 @@ test('a birth at the cap freezes instead of booting, survives saturated ticks, a
         created: new Date().toISOString(),
         pi_session_id: 'resident-drain-session',
     });
-    assert.equal(reviveNode('resident-drain', { resume: true, capacity: 'freeze' }).outcome, 'frozen');
+    assert.equal((await reviveNode('resident-drain', { resume: true, capacity: 'freeze' })).outcome, 'frozen');
     await h.tick();
     closeDb();
     const drained = h.node('resident-drain');