@north-light/crouter 0.3.311 → 0.3.312

package/dist/core/__tests__/context-intro.test.js

@@ -48,8 +48,8 @@ after(() => {
     delete process.env['CRTR_HOME'];
     delete process.env['CRTR_NODE_ID'];
 });
-test('the stored situational card rides the bearings body; absent when unset', () => {
-    const meta = spawnNode({ kind: 'general', cwd: '/tmp/work', parent: null });
+test('the stored situational card rides the bearings body; absent when unset', async () => {
+    const meta = await spawnNode({ kind: 'general', cwd: '/tmp/work', parent: null });
     assert.equal(situationalContextEnvelope(meta.node_id), null, 'no card until something is set');
     assert.doesNotMatch(buildContextIntro(meta.node_id), /kind="situational"/, 'bearings carry no card when unset');
     appendSituationalContext(meta.node_id, formatSituationalProse('user is looking at the billing applet'));
@@ -73,7 +73,7 @@ function fakeCtx(pi) {
     return { sessionManager: { getBranch: () => pi.entries } };
 }
 test('session_start injects the block as the first message of an empty session', async () => {
-    const meta = spawnNode({ kind: 'general', cwd: '/tmp/work', parent: null });
+    const meta = await spawnNode({ kind: 'general', cwd: '/tmp/work', parent: null });
     process.env['CRTR_NODE_ID'] = meta.node_id;
     const pi = makeFakePi();
     registerCanvasContextIntro(pi);
@@ -87,7 +87,7 @@ test('session_start injects the block as the first message of an empty session',
     assert.match(pi.sent[0].content, /<crtr-bearings>/);
 });
 test('session_start is idempotent across resume (skips if already in history)', async () => {
-    const meta = spawnNode({ kind: 'general', cwd: '/tmp/work', parent: null });
+    const meta = await spawnNode({ kind: 'general', cwd: '/tmp/work', parent: null });
     process.env['CRTR_NODE_ID'] = meta.node_id;
     // Restored session already carries OUR block (which names this node id) → no
     // duplicate injection. The content matters: the guard is fork-aware and only

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

@@ -45,9 +45,9 @@ async function withMutedStdout(fn) {
         process.stdout.write = originalWrite;
     }
 }
-function bridgeUnder() {
-    const parent = spawnNode({ kind: 'general', parent: null, cwd: home, name: 'asker' }).node_id;
-    const bridge = spawnNode({ kind: 'human', parent, creator: parent, cwd: home, name: 'human-page', lifecycle: 'terminal' }).node_id;
+async function bridgeUnder() {
+    const parent = (await spawnNode({ kind: 'general', parent: null, cwd: home, name: 'asker' })).node_id;
+    const bridge = (await spawnNode({ kind: 'human', parent, creator: parent, cwd: home, name: 'human-page', lifecycle: 'terminal' })).node_id;
     return { parent, bridge };
 }
 function submitBridgePage(bridge) {
@@ -97,7 +97,7 @@ after(() => {
 });
 describe('enqueue is producer-only', () => {
     test('send preserves title and subtitle from the authored page', async () => {
-        const parent = spawnNode({ kind: 'general', parent: null, cwd: home, name: 'asker' }).node_id;
+        const parent = (await spawnNode({ kind: 'general', parent: null, cwd: home, name: 'asker' })).node_id;
         process.env['CRTR_NODE_ID'] = parent;
         const page = join(home, 'release-decision.tsx');
         writeFileSync(page, 'export default () => (\n  <Page title="Release decision" subtitle="Decide whether to release now so the launch can proceed.">\n    <p>This first line stays page content.</p>\n    <UserText id="question" initialText="" />\n  </Page>\n);\n');
@@ -117,7 +117,7 @@ describe('enqueue is producer-only', () => {
         assert.equal(manifest.slots.filter((slot) => slot.kind === 'text').length, 1);
     });
     test('send materializes a piped page before validation and publication', async () => {
-        const parent = spawnNode({ kind: 'general', parent: null, cwd: home, name: 'asker' }).node_id;
+        const parent = (await spawnNode({ kind: 'general', parent: null, cwd: home, name: 'asker' })).node_id;
         process.env['CRTR_NODE_ID'] = parent;
         const document = 'export default () => (\n  <Page title="Piped question" subtitle="Answer the question to unblock this task.">\n    <UserText id="question" initialText="" />\n  </Page>\n);\n';
         const result = (await humanSend.run({ document }));
@@ -128,7 +128,7 @@ describe('enqueue is producer-only', () => {
 });
 describe('terminal ticket delivery', () => {
     test("resolvePageTicket pushFinals the person's words once and wakes the subscribed parent", async () => {
-        const { parent, bridge } = bridgeUnder();
+        const { parent, bridge } = await bridgeUnder();
         const dir = submitBridgePage(bridge);
         const result = await resolvePageTicket(bridge, { question: { text: 'yes, ship', edited: true } });
         assert.equal(result.kind, 'page');
@@ -142,7 +142,7 @@ describe('terminal ticket delivery', () => {
         assert.ok(!body.includes(join(dir, 'response.json')));
     });
     test('settlement delivers feedback outside the human-answer entry', async () => {
-        const { parent, bridge } = bridgeUnder();
+        const { parent, bridge } = await bridgeUnder();
         const dir = submitBridgePage(bridge);
         writeFileSync(pageFeedbackPath(dir), JSON.stringify({
             schema: 'crtr.page-feedback/v1',
@@ -167,7 +167,7 @@ describe('terminal ticket delivery', () => {
         assert.deepEqual(answer, { kind: 'final', disposition: 'human-answer', body: `yes, ship\n\nRead this report with \`crtr canvas history read ${final.ref}\`.`, ref: final.ref });
     });
     test('a replay against a terminal bridge is a no-op', async () => {
-        const { parent, bridge } = bridgeUnder();
+        const { parent, bridge } = await bridgeUnder();
         submitBridgePage(bridge);
         await resolvePageTicket(bridge, { question: { text: 'yes', edited: true } });
         assert.equal(await deliverTerminalResult(bridge), true);
@@ -176,9 +176,9 @@ describe('terminal ticket delivery', () => {
         assert.equal(finals.length, 1, 'replay after a terminal bridge pushes nothing further');
     });
     test('approved companions receive one canonical final while dismissed companions remain canceled', async () => {
-        const { bridge } = bridgeUnder();
+        const { bridge } = await bridgeUnder();
         const dir = submitBridgePage(bridge);
-        const companion = spawnNode({ kind: 'general', parent: bridge, creator: bridge, cwd: home, name: 'feedback companion', lifecycle: 'resident' }).node_id;
+        const companion = (await spawnNode({ kind: 'general', parent: bridge, creator: bridge, cwd: home, name: 'feedback companion', lifecycle: 'resident' })).node_id;
         createPageFeedbackComment(dir, { quote: 'Ship it?', note: 'Confirm the release.', companionNodeId: companion });
         transition(companion, 'finish');
         await resolvePageTicket(bridge, { question: { text: 'yes', edited: true } });
@@ -193,9 +193,9 @@ describe('terminal ticket delivery', () => {
         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');
         await assert.rejects(reviveNode(companion, { resume: true, capacity: 'freeze' }), /finalization latch/);
-        const { bridge: dismissedBridge } = bridgeUnder();
+        const { bridge: dismissedBridge } = await bridgeUnder();
         const dismissedDir = submitBridgePage(dismissedBridge);
-        const dismissedCompanion = spawnNode({ kind: 'general', parent: dismissedBridge, creator: dismissedBridge, cwd: home, name: 'dismissed feedback companion', lifecycle: 'resident' }).node_id;
+        const dismissedCompanion = (await spawnNode({ kind: 'general', parent: dismissedBridge, creator: dismissedBridge, cwd: home, name: 'dismissed feedback companion', lifecycle: 'resident' })).node_id;
         createPageFeedbackComment(dismissedDir, { quote: 'Ship it?', note: 'Do not ship.', companionNodeId: dismissedCompanion });
         await cancelHumanTicket(dismissedBridge, { reason: 'dismissed', actor: 'human' });
         assert.equal(getNode(dismissedCompanion)?.status, 'canceled');
@@ -206,9 +206,9 @@ describe('terminal ticket delivery', () => {
         assert.equal(getNode(dismissedCompanion)?.final_report, null);
     });
     test('cancelHumanTicket finishes the bridge and notifies non-actor subscribers', async () => {
-        const actor = spawnNode({ kind: 'general', parent: null, cwd: home, name: 'actor' }).node_id;
-        const bridge = spawnNode({ kind: 'human', parent: actor, creator: actor, cwd: home, name: 'human-page', lifecycle: 'terminal' }).node_id;
-        const other = spawnNode({ kind: 'general', parent: null, cwd: home, name: 'other' }).node_id;
+        const actor = (await spawnNode({ kind: 'general', parent: null, cwd: home, name: 'actor' })).node_id;
+        const bridge = (await spawnNode({ kind: 'human', parent: actor, creator: actor, cwd: home, name: 'human-page', lifecycle: 'terminal' })).node_id;
+        const other = (await spawnNode({ kind: 'general', parent: null, cwd: home, name: 'other' })).node_id;
         const { subscribe } = await import('../canvas/canvas.js');
         subscribe(other, bridge, true);
         submitBridgePage(bridge);
@@ -222,9 +222,9 @@ describe('terminal ticket delivery', () => {
         assert.match(notes[0].label, /canceled/);
     });
     test('cancellation reaches subscribers when the bridge is already done, and retries conflict rather than fail', async () => {
-        const actor = spawnNode({ kind: 'general', parent: null, cwd: home, name: 'actor' }).node_id;
-        const bridge = spawnNode({ kind: 'human', parent: actor, creator: actor, cwd: home, name: 'human-page', lifecycle: 'terminal' }).node_id;
-        const other = spawnNode({ kind: 'general', parent: null, cwd: home, name: 'other' }).node_id;
+        const actor = (await spawnNode({ kind: 'general', parent: null, cwd: home, name: 'actor' })).node_id;
+        const bridge = (await spawnNode({ kind: 'human', parent: actor, creator: actor, cwd: home, name: 'human-page', lifecycle: 'terminal' })).node_id;
+        const other = (await spawnNode({ kind: 'general', parent: null, cwd: home, name: 'other' })).node_id;
         const { subscribe } = await import('../canvas/canvas.js');
         subscribe(other, bridge, true);
         submitBridgePage(bridge);

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

@@ -88,8 +88,8 @@ function reportBody(ref) {
     return resolved.body;
 }
 test('malformed resolves leave the mounted ticket claim in place', async () => {
-    const parent = spawnNode({ kind: 'general', parent: null, cwd: home, name: 'asker' }).node_id;
-    const pageBridge = spawnNode({ kind: 'human', parent, creator: parent, cwd: home, name: 'human-page', lifecycle: 'terminal' }).node_id;
+    const parent = (await spawnNode({ kind: 'general', parent: null, cwd: home, name: 'asker' })).node_id;
+    const pageBridge = (await spawnNode({ kind: 'human', parent, creator: parent, cwd: home, name: 'human-page', lifecycle: 'terminal' })).node_id;
     const pageDir = submitBridgePage(pageBridge);
     const pageClaim = claimTicket(pageDir);
     assert.ok(pageClaim !== null);
@@ -101,7 +101,7 @@ test('malformed resolves leave the mounted ticket claim in place', async () => {
         await expectReviewSubmitGuidance(pageBridge, body);
         assert.equal(readTicketClaim(pageDir)?.token, pageClaim.token, 'feedback-shaped input must not take over the live claim');
     }
-    const reviewBridge = spawnNode({ kind: 'human', parent, creator: parent, cwd: home, name: 'human-review', lifecycle: 'terminal' }).node_id;
+    const reviewBridge = (await spawnNode({ kind: 'human', parent, creator: parent, cwd: home, name: 'human-review', lifecycle: 'terminal' })).node_id;
     const reviewDir = ticketDir(reviewBridge);
     const file = join(home, 'review.md');
     writeFileSync(file, '# Review\n');
@@ -113,8 +113,8 @@ test('malformed resolves leave the mounted ticket claim in place', async () => {
     assert.equal(readTicketClaim(reviewDir)?.token, reviewClaim.token, 'review ticket resolve must not take over the live claim');
 });
 test('the ticket resolve route pushFinals the readable answer to the parent', async () => {
-    const parent = spawnNode({ kind: 'general', parent: null, cwd: home, name: 'asker' }).node_id;
-    const bridge = spawnNode({ kind: 'human', parent, creator: parent, cwd: home, name: 'human-page', lifecycle: 'terminal' }).node_id;
+    const parent = (await spawnNode({ kind: 'general', parent: null, cwd: home, name: 'asker' })).node_id;
+    const bridge = (await spawnNode({ kind: 'human', parent, creator: parent, cwd: home, name: 'human-page', lifecycle: 'terminal' })).node_id;
     const dir = submitBridgePage(bridge);
     const result = await client.resolveHumanTicket(bridge, { responses: { question: { text: 'yes, ship', edited: true } } });
     assert.deepEqual(result, { completed: true, reply_delivered: true, kind: 'page' });

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

@@ -1,11 +1,17 @@
 import assert from 'node:assert/strict';
-import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import test from 'node:test';
 import { contextDir, jobDir, nodeDir, reportsDir } from '../../canvas/paths.js';
+import { listNodes, listWarmSpares } from '../../canvas/canvas.js';
 import { validateHookManifest } from '../../command-hooks/schema.js';
 import { headlessBrokerHost } from '../../runtime/host.js';
 import { reviveNode } from '../../runtime/revive.js';
+import { handleCreate, handleFork } from '../../../daemon/api/handlers/nodes.js';
+import { armCron, getCron } from '../../canvas/crons.js';
+import { settleRun } from '../../../daemon/cron/settle.js';
+import { relaunchRoot } from '../../runtime/reset.js';
+import { recycleNode } from '../../runtime/recycle.js';
 import { createHarness } from '../helpers/harness.js';
 function installLifecyclePlugin(harness, name, op) {
     const ops = typeof op === 'string' ? [op] : op;
@@ -53,6 +59,64 @@ process.stdin.on('end', () => {
 `);
     chmodSync(executable, 0o755);
 }
+function installCreateLifecyclePlugin(harness, name, declarations, behavior) {
+    const root = join(harness.agentHome, '.crouter', 'plugins', name);
+    const records = join(root, 'records.jsonl');
+    mkdirSync(join(root, '.crouter-plugin'), { recursive: true });
+    writeFileSync(join(root, '.crouter-plugin', 'plugin.json'), JSON.stringify({
+        name,
+        version: '0.1.0',
+        description: 'node create lifecycle fixture',
+        hooks: 'hooks.json',
+        hookExecutable: 'bin/hook.js',
+    }));
+    writeFileSync(join(root, 'hooks.json'), JSON.stringify({
+        schemaVersion: 2,
+        lifecycle: declarations.map((declaration) => ({ ...declaration, description: `${declaration.op} 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 { appendFileSync, existsSync, readdirSync } = require('node:fs');
+const { join } = require('node:path');
+const behavior = ${JSON.stringify(behavior)};
+let input = '';
+process.stdin.on('data', (chunk) => { input += chunk; });
+process.stdin.on('end', () => {
+  const request = JSON.parse(input);
+  appendFileSync(${JSON.stringify(records)}, JSON.stringify(request) + '\\n');
+  if (request.event === 'node:create' && behavior === 'refuse') {
+    process.stdout.write(JSON.stringify({ protocolVersion: 1, ok: false, error: { code: 'refused', message: 'fixture refusal' } }));
+    return;
+  }
+  if (request.event === 'node:create' && behavior === 'crash') process.exit(1);
+  if (request.event === 'node:create' && behavior === 'hang') return setInterval(() => {}, 1000);
+  if (request.event === 'node:create' && behavior === 'bad-output') return process.stdout.write('not an envelope');
+  if (request.event === 'node:create' && behavior === 'second-refuses') {
+    const nodes = join(request.runtime.canvasHome, 'nodes');
+    if (existsSync(nodes) && readdirSync(nodes).some((entry) => entry !== 'index.json')) {
+      process.stdout.write(JSON.stringify({ protocolVersion: 1, ok: false, error: { code: 'occupied', message: 'second create refused' } }));
+      return;
+    }
+  }
+  if (request.event === 'node:start' && behavior === 'start-refuses') {
+    process.stdout.write(JSON.stringify({ protocolVersion: 1, ok: false, error: { code: 'ignored', message: 'start refusal' } }));
+    return;
+  }
+  process.stdout.write(JSON.stringify({ protocolVersion: 1, ok: true }));
+});
+`);
+    chmodSync(executable, 0o755);
+    return { root, records };
+}
+function createContext(body, params = {}) {
+    return { method: 'POST', path: '/v1/nodes', params, query: new URLSearchParams(), body };
+}
+function lifecycleRecords(path) {
+    return existsSync(path)
+        ? readFileSync(path, 'utf8').trim().split('\n').filter(Boolean).map((line) => JSON.parse(line))
+        : [];
+}
 function installV1CommandHook(harness) {
     const root = join(harness.agentHome, '.crouter', 'plugins', 'z-v1-command');
     mkdirSync(join(root, '.crouter-plugin'), { recursive: true });
@@ -149,6 +213,233 @@ test('node:start hooks receive resolved paths before broker launch; invalid and
         await harness.dispose();
     }
 });
+test('node:create fails closed before a row exists and node:start fires on cold birth', async () => {
+    const harness = await createHarness({ headless: true, sessionPrefix: 'crtr-node-create-hooks' });
+    try {
+        const birth = installCreateLifecyclePlugin(harness, 'birth-fixture', [
+            { event: 'node:create', phase: 'before', op: 'record-create' },
+            { event: 'node:start', phase: 'on', op: 'record-start' },
+        ], 'start-refuses');
+        const created = await handleCreate(createContext({ kind: 'developer', root: true, profile: null, cwd: harness.agentHome, prompt: '' }));
+        const nodeId = created.body.node_id;
+        await harness.awaitBoot(nodeId);
+        const records = lifecycleRecords(birth.records);
+        const create = records.find((record) => record.event === 'node:create');
+        assert.deepEqual(create.create, {
+            kind: 'developer', mode: 'base', cwd: harness.agentHome, profile: null, root: true, parentId: null, requestingNodeId: null, lifecycle: 'resident', replaces: null,
+        });
+        assert.deepEqual(create.runtime, { canvasHome: harness.home, profile: null });
+        assert.deepEqual(create.context, { cwd: harness.agentHome });
+        assert.equal(Object.hasOwn(create, 'node'), false);
+        const start = records.find((record) => record.event === 'node:start');
+        assert.equal(start.runtime.isBirth, true);
+        assert.ok(harness.node(nodeId), 'a refusing node:start hook leaves the cold birth launched');
+        rmSync(birth.root, { recursive: true, force: true });
+        for (const behavior of ['refuse', 'crash', 'bad-output', 'hang']) {
+            const plugin = installCreateLifecyclePlugin(harness, `create-${behavior}`, [{ event: 'node:create', phase: 'before', op: behavior }], behavior);
+            const count = listNodes().length;
+            await assert.rejects(() => handleCreate(createContext({ kind: 'developer', root: true, profile: null, cwd: harness.agentHome, prompt: '' })), (error) => {
+                assert.equal(error.code, 'node_create_refused');
+                assert.match(error.message, new RegExp(`${behavior === 'refuse' ? 'fixture refusal' : `plugin "create-${behavior}" lifecycle hook "${behavior}"`}`));
+                return true;
+            });
+            assert.equal(listNodes().length, count, `${behavior} leaves no node row`);
+            rmSync(plugin.root, { recursive: true, force: true });
+        }
+        const missing = installCreateLifecyclePlugin(harness, 'create-missing', [{ event: 'node:create', phase: 'before', op: 'missing-op' }], 'allow');
+        rmSync(join(missing.root, 'bin', 'hook.js'));
+        await assert.rejects(() => handleCreate(createContext({ kind: 'developer', root: true, profile: null, cwd: harness.agentHome, prompt: '' })), (error) => {
+            assert.equal(error.code, 'node_create_refused');
+            assert.match(error.message, /plugin "create-missing" lifecycle hook "missing-op"/);
+            return true;
+        });
+        rmSync(missing.root, { recursive: true, force: true });
+        const malformed = installCreateLifecyclePlugin(harness, 'create-malformed', [
+            { event: 'node:create', phase: 'before', op: 'valid-create' },
+            { event: 'node:create', phase: 'on', op: 'invalid-create' },
+        ], 'allow');
+        const count = listNodes().length;
+        await assert.rejects(() => handleCreate(createContext({ kind: 'developer', root: true, profile: null, cwd: harness.agentHome, prompt: '' })), (error) => {
+            assert.equal(error.code, 'node_create_refused');
+            assert.match(error.message, /plugin "create-malformed" lifecycle hook "valid-create"/);
+            return true;
+        });
+        assert.equal(listNodes().length, count, 'a later malformed node:create declaration leaves no node row');
+        rmSync(malformed.root, { recursive: true, force: true });
+        const malformedOtherLifecycle = installCreateLifecyclePlugin(harness, 'create-malformed-other-lifecycle', [
+            { event: 'node:start', phase: 'before', op: 'invalid-start' },
+            { event: 'node:create', phase: 'before', op: 'valid-create' },
+        ], 'allow');
+        await assert.rejects(() => handleCreate(createContext({ kind: 'developer', root: true, profile: null, cwd: harness.agentHome, prompt: '' })), (error) => {
+            assert.equal(error.code, 'node_create_refused');
+            assert.match(error.message, /plugin "create-malformed-other-lifecycle" lifecycle hook "valid-create"/);
+            return true;
+        });
+        rmSync(malformedOtherLifecycle.root, { recursive: true, force: true });
+    }
+    finally {
+        await harness.dispose();
+    }
+});
+test('node:fork runs the node:create gate for its new resident root', async () => {
+    const harness = await createHarness({ headless: true, sessionPrefix: 'crtr-node-fork-create' });
+    try {
+        const plugin = installCreateLifecyclePlugin(harness, 'fork-create', [{ event: 'node:create', phase: 'before', op: 'record-fork' }], 'allow');
+        const source = await handleCreate(createContext({ kind: 'developer', root: true, profile: null, cwd: harness.agentHome, prompt: '' }));
+        const sourceId = source.body.node_id;
+        await harness.awaitBoot(sourceId);
+        const fork = await handleFork(createContext({}, { id: sourceId }));
+        const forkId = fork.body.node_id;
+        await harness.awaitBoot(forkId);
+        const creates = lifecycleRecords(plugin.records).filter((record) => record.event === 'node:create');
+        assert.equal(creates.length, 2);
+        assert.deepEqual(creates[1].create, {
+            kind: 'developer', mode: 'base', cwd: harness.agentHome, profile: null, root: true, parentId: null, requestingNodeId: null, lifecycle: 'resident', replaces: null,
+        });
+    }
+    finally {
+        await harness.dispose();
+    }
+});
+test('node:create gates warm mint and warm claim with the birth payload', async () => {
+    const harness = await createHarness({ headless: true, sessionPrefix: 'crtr-node-create-warm' });
+    const priorWarmPool = process.env['CRTR_WARM_POOL'];
+    process.env['CRTR_WARM_POOL'] = '1';
+    try {
+        const plugin = installCreateLifecyclePlugin(harness, 'warm-create', [{ event: 'node:create', phase: 'before', op: 'record-warm' }], 'allow');
+        const first = await handleCreate(createContext({ kind: 'developer', root: true, profile: null, cwd: harness.agentHome, prompt: '', prefer_warm: true }));
+        await harness.awaitBoot(first.body.node_id);
+        let spareId;
+        for (let i = 0; i < 100; i++) {
+            spareId = listWarmSpares()[0]?.node_id;
+            if (spareId !== undefined)
+                break;
+            await new Promise((resolve) => setTimeout(resolve, 25));
+        }
+        assert.ok(spareId, 'the cold create refills one warm spare');
+        await harness.awaitBoot(spareId);
+        const createsBeforeClaim = lifecycleRecords(plugin.records).filter((record) => record.event === 'node:create').length;
+        const second = await handleCreate(createContext({ kind: 'developer', root: true, profile: null, cwd: harness.agentHome, prompt: '', prefer_warm: true }));
+        assert.equal(second.body.node_id, spareId, 'the second request claims the pre-born spare');
+        const creates = lifecycleRecords(plugin.records).filter((record) => record.event === 'node:create');
+        assert.equal(creates.length, createsBeforeClaim + 1, 'claiming the spare runs one additional create gate');
+        for (const record of creates) {
+            assert.deepEqual(record.create, {
+                kind: 'developer', mode: 'base', cwd: harness.agentHome, profile: null, root: true, parentId: null, requestingNodeId: null, lifecycle: 'resident', replaces: null,
+            });
+        }
+        let replacementSpareId;
+        for (let i = 0; i < 100; i++) {
+            replacementSpareId = listWarmSpares()[0]?.node_id;
+            if (replacementSpareId !== undefined)
+                break;
+            await new Promise((resolve) => setTimeout(resolve, 25));
+        }
+        assert.ok(replacementSpareId, 'a claimed spare is refilled before the test tears down its harness');
+        await harness.awaitBoot(replacementSpareId);
+    }
+    finally {
+        if (priorWarmPool === undefined)
+            delete process.env['CRTR_WARM_POOL'];
+        else
+            process.env['CRTR_WARM_POOL'] = priorWarmPool;
+        await harness.dispose();
+    }
+});
+test('a refused recycle leaves the old root active', async () => {
+    const harness = await createHarness({ headless: true, sessionPrefix: 'crtr-node-create-recycle' });
+    const priorWarmPool = process.env['CRTR_WARM_POOL'];
+    process.env['CRTR_WARM_POOL'] = '0';
+    try {
+        const source = await handleCreate(createContext({ kind: 'developer', root: true, profile: null, cwd: harness.agentHome, prompt: '' }));
+        const sourceId = source.body.node_id;
+        await harness.awaitBoot(sourceId);
+        installCreateLifecyclePlugin(harness, 'recycle-refusal', [{ event: 'node:create', phase: 'before', op: 'refuse-recycle' }], 'refuse');
+        await assert.rejects(() => recycleNode(sourceId, '%recycle-refusal'), /fixture refusal/);
+        assert.equal(harness.node(sourceId)?.status, 'active', 'the old root is unchanged when the replacement hook refuses');
+    }
+    finally {
+        if (priorWarmPool === undefined)
+            delete process.env['CRTR_WARM_POOL'];
+        else
+            process.env['CRTR_WARM_POOL'] = priorWarmPool;
+        await harness.dispose();
+    }
+});
+test('node:create reports the root replaced by /new', async () => {
+    const harness = await createHarness({ headless: true, sessionPrefix: 'crtr-node-create-relaunch' });
+    const priorWarmPool = process.env['CRTR_WARM_POOL'];
+    process.env['CRTR_WARM_POOL'] = '0';
+    try {
+        const plugin = installCreateLifecyclePlugin(harness, 'relaunch-create', [{ event: 'node:create', phase: 'before', op: 'record-relaunch' }], 'allow');
+        const source = await handleCreate(createContext({ kind: 'developer', root: true, profile: null, cwd: harness.agentHome, prompt: '' }));
+        const sourceId = source.body.node_id;
+        await harness.awaitBoot(sourceId);
+        const result = await relaunchRoot(sourceId, {
+            launchBroker: () => ({ pid: 999_999, exited: new Promise(() => { }) }),
+            waitForViewSocket: () => true,
+            respawnViewer: () => true,
+            teardownBroker: async () => ({ confirmed: true }),
+        });
+        assert.ok(result);
+        const create = lifecycleRecords(plugin.records).filter((record) => record.event === 'node:create').at(-1);
+        assert.deepEqual(create.create, {
+            kind: 'developer', mode: 'base', cwd: harness.agentHome, profile: null, root: true, parentId: null, requestingNodeId: null, lifecycle: 'resident', replaces: sourceId,
+        });
+    }
+    finally {
+        if (priorWarmPool === undefined)
+            delete process.env['CRTR_WARM_POOL'];
+        else
+            process.env['CRTR_WARM_POOL'] = priorWarmPool;
+        await harness.dispose();
+    }
+});
+test('a refused cron spawn records its failure and does not throw', async () => {
+    const harness = await createHarness({ headless: true, sessionPrefix: 'crtr-node-create-cron' });
+    try {
+        installCreateLifecyclePlugin(harness, 'cron-create', [{ event: 'node:create', phase: 'before', op: 'refuse-cron' }], 'refuse');
+        armCron({
+            cron_id: 'refused-cron-spawn', name: 'refused cron spawn', created_by: null, command: 'echo fixture', fire_at: new Date().toISOString(), recur: null, tz: null, expires_at: null, anchor_node: null, cancel_on_wake: false,
+            cwd: harness.agentHome, env_json: null, profile: null, scope: 'global', run_timeout_s: 30, overlap: 'skip', on_output: 'always', sink: JSON.stringify({ spawn: 'developer' }), tier: 'normal',
+        });
+        const cron = getCron('refused-cron-spawn');
+        const record = await settleRun(cron, {
+            outOfBand: false,
+            outcome: {
+                kind: 'disposed',
+                ctx: {
+                    runId: 'refused-cron-run', startedAtIso: new Date().toISOString(), exitCode: 0, timedOut: false, runTimeoutS: 30, processErrorMessage: null,
+                    stdoutHead: 'fixture output', stdoutSha256: 'fixture-output-hash', stderrHead: '',
+                },
+            },
+            record: { runId: 'refused-cron-run', startedAtIso: new Date().toISOString(), finishedAtMs: Date.now(), durationMs: 1, exitCode: 0, stdoutHead: 'fixture output', stderrHead: null },
+            lease: 'none',
+        });
+        assert.match(record.delivered ?? '', /fixture refusal/, 'the cron run records the refused birth');
+        assert.equal(getCron(cron.cron_id)?.state, 'paused', 'the refused delivery pauses the cron instead of throwing or retrying');
+        assert.equal(listNodes().length, 0, 'neither the sink nor escalation writes a node row');
+    }
+    finally {
+        await harness.dispose();
+    }
+});
+test('node:create serializes concurrent creates through the persisted row', async () => {
+    const harness = await createHarness({ headless: true, sessionPrefix: 'crtr-node-create-lock' });
+    try {
+        installCreateLifecyclePlugin(harness, 'create-lock', [{ event: 'node:create', phase: 'before', op: 'only-one' }], 'second-refuses');
+        const request = () => handleCreate(createContext({ kind: 'developer', root: true, profile: null, cwd: harness.agentHome, prompt: '' }));
+        const results = await Promise.allSettled([request(), request()]);
+        assert.equal(results.filter((result) => result.status === 'fulfilled').length, 1);
+        const refusal = results.find((result) => result.status === 'rejected');
+        assert.equal(refusal.reason.code, 'node_create_refused');
+        assert.match(refusal.reason.message, /second create refused/);
+        assert.equal(listNodes().length, 1);
+    }
+    finally {
+        await harness.dispose();
+    }
+});
 test('hooks.json v1 remains command-only while v2 accepts a lifecycle-only declaration', () => {
     const v1 = validateHookManifest({
         schemaVersion: 1,
@@ -176,10 +467,17 @@ test('hooks.json v1 remains command-only while v2 accepts a lifecycle-only decla
         lifecycle: [{ event: 'node:close', phase: 'on', op: 'cleanup', description: 'cleanup', effects: ['removes a directory'] }],
     });
     assert.deepEqual(close.issues, []);
+    const create = validateHookManifest({
+        schemaVersion: 2,
+        lifecycle: [{ event: 'node:create', phase: 'before', op: 'guard', description: 'guard', effects: ['refuses a create'] }],
+    });
+    assert.deepEqual(create.issues, []);
     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:create', phase: 'on', op: 'prepare', description: 'prepare', effects: ['creates a directory'] }] },
+        { schemaVersion: 2, lifecycle: [{ event: 'node:close', 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/spawn-root.test.js

@@ -66,9 +66,9 @@ after(() => {
     else
         process.env['CRTR_PIDFILE'] = previousPidfile;
 });
-test('managed child: parent on the spine + active subscription + provenance', () => {
+test('managed child: parent on the spine + active subscription + provenance', async () => {
     createNode(spawner('A'));
-    const child = spawnNode({ kind: 'developer', cwd: '/tmp/work', parent: 'A', creator: 'A' });
+    const child = await spawnNode({ kind: 'developer', cwd: '/tmp/work', parent: 'A', creator: 'A' });
     const meta = getNode(child.node_id);
     assert.equal(meta.parent, 'A', 'child keeps its spine parent');
     assert.equal(meta.spawned_by, 'A', 'child provenance defaults to its parent');
@@ -78,10 +78,10 @@ test('managed child: parent on the spine + active subscription + provenance', ()
     assert.equal(subs[0].node_id, 'A');
     assert.equal(subs[0].active, true, 'parent subscription is active');
 });
-test('external child birth is deferred, persists its creator, and renders its age at delivery in both inbox mirrors', () => {
+test('external child birth is deferred, persists its creator, and renders its age at delivery in both inbox mirrors', async () => {
     createNode(spawner('A'));
-    const creator = spawnNode({ kind: 'general', cwd: '/tmp/work', parent: null, name: 'Core' });
-    const child = spawnNode({ kind: 'developer', cwd: '/tmp/work', parent: 'A', creator: creator.node_id, name: 'worker' });
+    const creator = await spawnNode({ kind: 'general', cwd: '/tmp/work', parent: null, name: 'Core' });
+    const child = await spawnNode({ kind: 'developer', cwd: '/tmp/work', parent: 'A', creator: creator.node_id, name: 'worker' });
     const saved = getNode(child.node_id);
     assert.equal(saved.creator, creator.node_id, 'creator persists through meta.json and getNode');
     const [entry] = readInboxSince('A');
@@ -106,14 +106,14 @@ test('external child birth is deferred, persists its creator, and renders its ag
             assert.doesNotMatch(card, /\[\[CRTR_BIRTH_ANNOUNCEMENT_AGE\]\]/, 'the marker is not visible to the recipient');
         }
     }
-    spawnNode({ kind: 'developer', cwd: '/tmp/work', parent: 'A', creator: 'A' });
+    await spawnNode({ kind: 'developer', cwd: '/tmp/work', parent: 'A', creator: 'A' });
     assert.equal(readInboxSince('A').length, 1, 'a parent-created child stays silent');
-    spawnNode({ kind: 'developer', cwd: '/tmp/work', parent: null });
+    await spawnNode({ kind: 'developer', cwd: '/tmp/work', parent: null });
     assert.equal(readInboxSince('A').length, 1, 'a root never announces');
 });
-test('independent root: provenance only, no parent, no subscription', () => {
+test('independent root: provenance only, no parent, no subscription', async () => {
     createNode(spawner('A'));
-    const root = spawnNode({
+    const root = await spawnNode({
         kind: 'developer',
         cwd: '/tmp/work',
         parent: null,
@@ -135,10 +135,10 @@ test('resolveSpawner: a --root spawn needs no caller; a managed child does (regr
     assert.equal(resolveSpawner('A', null, false), 'A', 'explicit parent satisfies a child spawn');
     assert.throws(() => resolveSpawner(undefined, null, false), /requires a calling node/, 'a managed child with no caller still throws');
 });
-test('unknown parent: spawnNode throws and mints NO node dir / row (validate before create)', () => {
+test('unknown parent: spawnNode throws and mints NO node dir / row (validate before create)', async () => {
     // Pre-allocate the would-be id so we can prove nothing was scaffolded for it.
     const orphanId = 'orphan-under-ghost';
-    assert.throws(() => spawnNode({ kind: 'developer', cwd: '/tmp/work', parent: 'ghost', nodeId: orphanId }), /cannot spawn under unknown parent node: ghost/);
+    await assert.rejects(() => spawnNode({ kind: 'developer', cwd: '/tmp/work', parent: 'ghost', nodeId: orphanId }), /cannot spawn under unknown parent node: ghost/);
     // No half-born orphan: no meta (getNode null), no db row, no node dir on disk.
     assert.equal(getNode(orphanId), null, 'no meta.json written for the orphan');
     assert.equal(getRow(orphanId), null, 'no index row written for the orphan');

package/dist/core/__tests__/on-read-crouter-home-fence.test.js

@@ -44,8 +44,8 @@ after(() => {
     else
         process.env['HOME'] = prevHomeEnv;
 });
-test('a store nested in the crouter home does not leak into a canvas-artifact read', () => {
-    const node = spawnNode({ kind: 'general', cwd: fakeHome, parent: null }).node_id;
+test('a store nested in the crouter home does not leak into a canvas-artifact read', async () => {
+    const node = (await spawnNode({ kind: 'general', cwd: fakeHome, parent: null })).node_id;
     // A private store misresolved into the crouter home: `~/.crouter/.crouter/memory/`.
     const leakedStore = join(fakeHome, '.crouter', '.crouter', 'memory');
     mkdirSync(leakedStore, { recursive: true });

package/dist/core/__tests__/on-read-dedup-resume.test.js

@@ -56,11 +56,11 @@ after(() => {
     else
         process.env['HOME'] = prevHomeEnv;
 });
-test('project and user memory docs without read surfaces do not fire on file reads', () => {
+test('project and user memory docs without read surfaces do not fire on file reads', async () => {
     const fakeHome = mkdtempSync(join(tmpdir(), 'crtr-onread-user-home-'));
     process.env['HOME'] = fakeHome;
     resetScopeCache();
-    const node = spawnNode({ kind: 'general', cwd: join(fakeHome, 'work'), parent: null }).node_id;
+    const node = (await spawnNode({ kind: 'general', cwd: join(fakeHome, 'work'), parent: null })).node_id;
     const userMemDir = join(fakeHome, '.crouter', 'memory');
     mkdirSync(userMemDir, { recursive: true });
     writeFileSync(join(userMemDir, 'noisy-global.md'), '---\nkind: preference\n' +
@@ -79,8 +79,8 @@ test('project and user memory docs without read surfaces do not fire on file rea
     assert.equal(rendered, '', 'no file context renders without an explicit trigger');
     rmSync(fakeHome, { recursive: true, force: true });
 });
-test('on-read exposure survives a strict resume and resets for a fresh context', () => {
-    const node = spawnNode({ kind: 'general', cwd: work, parent: null }).node_id;
+test('on-read exposure survives a strict resume and resets for a fresh context', async () => {
+    const node = (await spawnNode({ kind: 'general', cwd: work, parent: null })).node_id;
     // A file-routed substrate doc in a `.crouter/memory/` ancestor. The
     // `./`-anchored glob pins the repo-relative anchor: `src/file.ts` matches
     // only relative to the doc's owning repo dir, never absolutely.
@@ -111,8 +111,8 @@ test('on-read exposure survives a strict resume and resets for a fresh context',
     const stateFresh = loadContextExposureState(node);
     assert.ok(renderOnReadDocs(node, readFile, exposureTarget(stateFresh, 'transcript')).includes(FIXTURE_BODY), 'a fresh transcript surfaces the doc again');
 });
-test('an explicitly routed doc injects on-read under its frontmatter name, not the path-derived one', () => {
-    const node = spawnNode({ kind: 'general', cwd: work, parent: null }).node_id;
+test('an explicitly routed doc injects on-read under its frontmatter name, not the path-derived one', async () => {
+    const node = (await spawnNode({ kind: 'general', cwd: work, parent: null })).node_id;
     const memDir = join(work, '.crouter', 'memory');
     declareRepositoryRoot(memDir);
     writeFileSync(join(memDir, 'physical-guide.md'), '---\nkind: knowledge\n' +