@north-light/crouter 0.3.310 → 0.3.312

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' +

package/dist/core/__tests__/on-read-nested-store.test.js

@@ -76,9 +76,9 @@ function makeWorkTree() {
         'NESTED NEIGHBOUR BODY\n');
     return work;
 }
-test('a nested store front door surfaces on a read beneath its owning dir, not outside it', () => {
+test('a nested store front door surfaces on a read beneath its owning dir, not outside it', async () => {
     const work = makeWorkTree();
-    const node = spawnNode({ kind: 'general', cwd: work, parent: null }).node_id;
+    const node = (await spawnNode({ kind: 'general', cwd: work, parent: null })).node_id;
     const inside = join(work, 'pkg', 'lib', 'file.ts');
     mkdirSync(join(work, 'pkg', 'lib'), { recursive: true });
     writeFileSync(inside, 'export const x = 1;\n');
@@ -93,9 +93,9 @@ test('a nested store front door surfaces on a read beneath its owning dir, not o
     const renderedOutside = renderOnReadDocs(node, outside, freshTranscriptTarget());
     assert.ok(!renderedOutside.includes(NESTED_BODY), `read outside pkg must not surface the nested front door; got: ${renderedOutside}`);
 });
-test('workspace-open and on-read share one exposure ledger', () => {
+test('workspace-open and on-read share one exposure ledger', async () => {
     const work = makeWorkTree();
-    const node = spawnNode({ kind: 'general', cwd: work, parent: null }).node_id;
+    const node = (await spawnNode({ kind: 'general', cwd: work, parent: null })).node_id;
     const transcript = freshTranscriptTarget();
     const opened = renderWorkspaceOpenDocs(node, transcript);
     assert.ok(opened.includes(ROOT_BODY), 'workspace open delivers the mounted root front door');
@@ -109,7 +109,7 @@ test('workspace-open and on-read share one exposure ledger', () => {
     assert.ok(onRead.includes('name="work/pkg"'), 'the nested front door answers under the root namespace plus owner path');
     assert.ok(!onRead.includes(ROOT_BODY), 'the root front door already delivered at workspace open — never twice');
 });
-test('a hand-authored `./`-anchored read glob in a user-scope doc never matches a read', () => {
+test('a hand-authored `./`-anchored read glob in a user-scope doc never matches a read', async () => {
     const userStore = join(fakeHome, '.crouter', 'memory');
     mkdirSync(userStore, { recursive: true });
     writeFileSync(join(userStore, 'control.md'), '---\nkind: knowledge\n' +
@@ -124,7 +124,7 @@ test('a hand-authored `./`-anchored read glob in a user-scope doc never matches
         'USER DOT BODY MUST NOT FIRE\n');
     const work = join(fakeHome, 'work');
     mkdirSync(work, { recursive: true });
-    const node = spawnNode({ kind: 'general', cwd: work, parent: null }).node_id;
+    const node = (await spawnNode({ kind: 'general', cwd: work, parent: null })).node_id;
     const readFile = join(fakeHome, 'notes', 'thing.md');
     mkdirSync(join(fakeHome, 'notes'), { recursive: true });
     writeFileSync(readFile, '# a note\n');