@north-light/crouter 0.3.154

package/dist/core/__tests__/branded-host-concurrency.test.js

@@ -0,0 +1,72 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { spawn, spawnSync } from 'node:child_process';
+function reconcileInChild(home, moduleUrl) {
+    const script = `
+    const host = await import(${JSON.stringify(moduleUrl)});
+    const path = host.ensureBrandedHost();
+    process.stdout.write(JSON.stringify({ path, healthy: host.brandedHostWorks(path) }));
+  `;
+    return new Promise((resolve, reject) => {
+        const child = spawn(process.execPath, ['--import', 'tsx', '--input-type=module', '-e', script], {
+            cwd: process.cwd(),
+            env: { ...process.env, HOME: home },
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        let stdout = '';
+        let stderr = '';
+        child.stdout.setEncoding('utf8').on('data', (chunk) => { stdout += chunk; });
+        child.stderr.setEncoding('utf8').on('data', (chunk) => { stderr += chunk; });
+        child.once('error', reject);
+        child.once('close', (code) => resolve({ code, stdout, stderr }));
+    });
+}
+test('concurrent processes reconcile one coherent branded host tuple', async () => {
+    const home = mkdtempSync(join(tmpdir(), 'crtr-branded-host-race-'));
+    const hostDir = join(home, '.crouter', 'host');
+    mkdirSync(hostDir, { recursive: true });
+    writeFileSync(join(hostDir, '.source.json'), JSON.stringify({ version: 2, source: '/stale/node', libnode: 'libnode.stale.dylib' }));
+    writeFileSync(join(hostDir, 'libnode.stale.dylib'), 'stale');
+    const deadOwner = spawnSync(process.execPath, ['-e', '']).pid;
+    assert.ok(deadOwner !== undefined);
+    const abandonedLock = join(home, '.crouter', 'host.lock');
+    mkdirSync(abandonedLock);
+    writeFileSync(join(abandonedLock, 'owner.json'), JSON.stringify({ pid: deadOwner, token: 'abandoned' }));
+    try {
+        const moduleUrl = pathToFileURL(join(process.cwd(), 'src/core/runtime/branded-host.ts')).href;
+        const results = await Promise.all(Array.from({ length: 4 }, () => reconcileInChild(home, moduleUrl)));
+        const expectedPath = join(hostDir, 'crouter');
+        for (const result of results) {
+            assert.equal(result.code, 0, result.stderr);
+            assert.doesNotMatch(result.stderr, /codesign failed|permission denied|no such file or directory/i);
+            assert.deepEqual(JSON.parse(result.stdout), { path: expectedPath, healthy: true });
+        }
+        const marker = JSON.parse(readFileSync(join(hostDir, '.source.json'), 'utf8'));
+        assert.deepEqual(marker, {
+            version: 2,
+            source: realpathSync(process.execPath),
+            libnode: marker.libnode,
+        });
+        assert.equal(existsSync(expectedPath), true);
+        assert.equal(marker.libnode === null || existsSync(join(hostDir, marker.libnode)), true);
+        assert.equal(existsSync(join(hostDir, 'libnode.stale.dylib')), false);
+        assert.equal(existsSync(abandonedLock), false, 'the completed owner releases the reclaimed lock');
+        const health = spawnSync(expectedPath, ['-e', ''], { stdio: 'ignore', timeout: 2_000 });
+        assert.equal(health.status, 0, 'the published host and its matching libnode launch together');
+        if (process.platform === 'darwin') {
+            for (const path of [expectedPath, marker.libnode === null ? null : join(hostDir, marker.libnode)]) {
+                if (path === null)
+                    continue;
+                const verified = spawnSync('codesign', ['--verify', '--deep', '--strict', path], { encoding: 'utf8' });
+                assert.equal(verified.status, 0, verified.stderr);
+            }
+        }
+    }
+    finally {
+        rmSync(home, { recursive: true, force: true });
+    }
+});

package/dist/core/__tests__/broker-fork-seam.test.d.ts

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

package/dist/core/__tests__/broker-fork-seam.test.js

@@ -0,0 +1,118 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/broker-fork-seam.test.ts
+//
+// BUG-REGRESSION (broker-universal-host cut, design §B.broker; U1 report
+// mq8ftenr-5d55313d). Before the cut, the headless broker had NO fork path — its
+// session selection THREW `--fork is not supported by the headless broker`. After
+// the cut EVERY node is a broker, so `node new --fork-from <id>` would always hit
+// that throw. The fix routes the broker's fork through pi's REAL fork seam,
+// SessionManager.forkFrom (broker.ts buildBrokerSession, the `forking` branch) —
+// the same method pi's own `--fork` CLI flag uses.
+//
+// This test drives the BROKER's OWN fork branch (broker.ts buildBrokerSession,
+// the `forking` branch ~1106) end to end: it calls `buildBrokerSession` with
+// `cfg.forkFrom` set to a real source session .jsonl — the EXACT path a
+// `node new --fork-from <id>` boot takes through the broker — and asserts the
+// resulting live session is a genuine fork: a NEW session id (not a colliding
+// copy) and a `parentSession` header pointing at the source, with the source's
+// history copied in. Because it invokes `buildBrokerSession` (not
+// `SessionManager.forkFrom` directly), it goes RED if broker.ts's fork branch
+// reverts to `throw "--fork is not supported by the headless broker"` — it
+// guards its own stated regression.
+//
+// Like the C3/C4 real-SDK wiring tests, it drives the REAL engine (broker-sdk's
+// static SDK re-exports) — NOT the CRTR_BROKER_ENGINE fake the lifecycle suite
+// uses, whose fixture omits forkFrom and so could never exercise this branch. It
+// runs offline (fork + session/services assembly are all local: no network/auth).
+//
+// (fork.test.ts covers the pure argv/resolve layers — buildPiArgv emitting
+// `--fork`, resolveForkSource turning a ref into a path. THIS file covers the
+// broker runtime branch those layers feed.)
+import { test, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createAgentSessionServices, createAgentSessionFromServices, SessionManager, VERSION, } from '../runtime/broker-sdk.js';
+import { CANVAS_EXTENSIONS } from '../runtime/launch.js';
+import { buildBrokerSession } from '../runtime/broker.js';
+// M-9 (broker.ts fault-and-die model gate): buildBrokerSession with no cfg.model
+// now calls the REAL SDK's modelRegistry.getAvailable() and faults if it's empty
+// — which it always is on a host/CI runner with no authenticated provider. This
+// test drives the fork branch only, so it registers the SAME hermetic
+// fake-but-authenticated model the C3 wiring tests use, rather than depending on
+// ambient host credentials (which don't exist in CI — see broker-sdk-wiring's
+// c3-custom-provider-ext.ts fixture).
+const HERE = dirname(fileURLToPath(import.meta.url));
+const C3_EXT = join(HERE, 'fixtures', 'c3-custom-provider-ext.ts');
+// The REAL engine — bypasses the CRTR_BROKER_ENGINE fake entirely (the whole
+// point: the fake omits forkFrom, so only the real SDK can prove the branch).
+const realEngine = {
+    createAgentSessionServices,
+    createAgentSessionFromServices,
+    SessionManager,
+    VERSION,
+};
+let dir;
+before(() => {
+    dir = mkdtempSync(join(tmpdir(), 'crtr-fork-seam-'));
+});
+after(() => {
+    rmSync(dir, { recursive: true, force: true });
+});
+/** A minimal but VALID pi session .jsonl (the exact on-disk shape v3 emits): a
+ *  `session` header line + two `message` entries. This is what a node that has
+ *  run a turn or two carries on disk — the source the broker forks from. */
+function writeSourceSession(path, srcId) {
+    const lines = [
+        JSON.stringify({ type: 'session', version: 3, id: srcId, timestamp: '2026-06-10T20:27:32.891Z', cwd: dir }),
+        JSON.stringify({ type: 'message', id: 'a42170e1', parentId: null, timestamp: '2026-06-10T20:27:32.893Z', message: { role: 'user', content: 'source turn one' } }),
+        JSON.stringify({ type: 'message', id: 'f309b932', parentId: 'a42170e1', timestamp: '2026-06-10T20:27:32.893Z', message: { role: 'assistant', content: 'source reply one' } }),
+    ];
+    writeFileSync(path, lines.join('\n') + '\n');
+    return 2; // entry count (the two message lines)
+}
+test('D2 broker fork branch: buildBrokerSession(cfg.forkFrom) yields a NEW id + parentSession header, copying history (never throws "fork not supported")', async () => {
+    // 1. A real source session on disk.
+    const srcFile = join(dir, 'src.jsonl');
+    const srcId = '019eb338-029b-7536-b3eb-d33bd6f641a8';
+    const srcEntryCount = writeSourceSession(srcFile, srcId);
+    // 2. Drive the BROKER's fork branch: buildBrokerSession with cfg.forkFrom set —
+    //    the same recipe a `node new --fork-from <id>` boot produces. The OLD broker
+    //    THREW in this branch ("--fork is not supported by the headless broker"), so
+    //    if broker.ts:~1106 reverts to that throw, this rejects and the test goes RED.
+    const cfg = {
+        cwd: dir,
+        extensionPaths: [...CANVAS_EXTENSIONS, C3_EXT],
+        forkFrom: srcFile,
+        model: 'c3prov/c3model',
+    };
+    let session;
+    let resuming;
+    await assert.doesNotReject(async () => {
+        const built = await buildBrokerSession(realEngine, cfg);
+        session = built.session;
+        resuming = built.resuming;
+    }, 'the broker fork branch must NOT throw "fork is not supported by the headless broker"');
+    assert.ok(session !== undefined, 'buildBrokerSession returned a live session for the fork');
+    try {
+        // 3. A fork boots as a FRESH spawn (resuming=false) so the kickoff firstPrompt
+        //    fires — the new node gets the source history AND a new task to start on.
+        assert.equal(resuming, false, 'a fork is a fresh spawn (resuming=false) so the kickoff fires');
+        // 4. Real fork metadata on the broker's selected SessionManager, not a
+        //    colliding .jsonl copy.
+        const sm = session.sessionManager;
+        assert.notEqual(sm.getSessionId(), srcId, 'the fork is a NEW session id (not a copy that would collide on resume)');
+        const header = sm.getHeader();
+        assert.equal(header?.parentSession, srcFile, 'the fork header records parentSession pointing at the source .jsonl');
+        // 5. The source history is carried into the fork (fork copies, not empty
+        //    start). The broker boot may append its own session-start entry, so the
+        //    fork holds AT LEAST the source's messages — a naïve empty session would
+        //    have zero.
+        assert.ok(sm.getEntries().length >= srcEntryCount, `the fork carries the source conversation history forward ` +
+            `(>= ${srcEntryCount} source entries; got ${sm.getEntries().length})`);
+    }
+    finally {
+        session.dispose();
+    }
+});

package/dist/core/__tests__/broker-launch-candidates.test.d.ts

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

package/dist/core/__tests__/broker-launch-candidates.test.js

@@ -0,0 +1,241 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createAgentSessionFromServices, createAgentSessionServices, SessionManager, VERSION } from '../runtime/broker-sdk.js';
+import { buildBrokerSession, isUnknownModel } from '../runtime/broker.js';
+import { resolveProviderCandidates } from '../subscription-state.js';
+const realEngine = { createAgentSessionServices, createAgentSessionFromServices, SessionManager, VERSION };
+const C3_EXT = join(dirname(fileURLToPath(import.meta.url)), 'fixtures', 'c3-custom-provider-ext.ts');
+const requested = { provider: 'anthropic', id: 'requested' };
+const alternative = { provider: 'openai-codex', id: 'alternative' };
+const DEFAULT_MANAGED_PROVIDERS = new Set(['anthropic', 'openai-codex']);
+// The unified `resolveProviderCandidates` is the ONE resolver governing launch,
+// turn-time retry, and rotation fallback (issue #236). This adapter reproduces
+// the launch caller's contract — requested model first (its provider pinned when
+// pinned), then registry order — and maps the result back to the original
+// `{ model, rejections }` shape so every launch behavior assertion below still
+// holds against the surviving resolver.
+const REJECTION_TEXT = {
+    unregistered: 'not registered',
+    unauthenticated: 'provider has no configured credentials',
+    cooling: 'managed provider is cooling down',
+    'non-managed-fallback': 'non-managed provider is not an automatic fallback',
+};
+function resolve(options) {
+    const key = (provider, id) => `${provider}/${id}`;
+    const registered = new Set((options.registered ?? options.available).map((m) => key(m.provider, m.id)));
+    const authenticated = new Set((options.authenticated ?? options.available).map((m) => key(m.provider, m.id)));
+    const cooling = new Set((options.cooling ?? []).map((m) => key(m.provider, m.id)));
+    const COOL_UNTIL = Date.now() + 10 * 60_000;
+    // Ordered candidate set: requested provider/id first, then available in order.
+    const ordered = [];
+    const seen = new Set();
+    const push = (provider, id) => {
+        const k = key(provider, id);
+        if (seen.has(k))
+            return;
+        seen.add(k);
+        ordered.push({ provider, id });
+    };
+    if (options.requested !== undefined && options.requested !== '') {
+        const slash = options.requested.indexOf('/');
+        push(options.requested.slice(0, slash), options.requested.slice(slash + 1));
+    }
+    for (const m of options.available)
+        push(m.provider, m.id);
+    // Mirrors resolveLaunchModel's own first pass: a non-managed candidate is
+    // only an automatic fallback when no managed provider is registered AND
+    // authenticated anywhere in this candidate set, regardless of cooling.
+    const hasManagedAuthenticated = ordered.some((m) => DEFAULT_MANAGED_PROVIDERS.has(m.provider) && registered.has(key(m.provider, m.id)) && authenticated.has(key(m.provider, m.id)));
+    const result = resolveProviderCandidates(ordered.map((m, index) => ({
+        providerId: m.provider,
+        modelId: m.id,
+        automaticFallback: index === 0 && options.requested !== undefined && options.requested !== ''
+            ? true
+            : DEFAULT_MANAGED_PROVIDERS.has(m.provider) || !hasManagedAuthenticated,
+        registered: registered.has(key(m.provider, m.id)),
+        authenticated: registered.has(key(m.provider, m.id)) && authenticated.has(key(m.provider, m.id)),
+        coolingUntil: cooling.has(key(m.provider, m.id)) ? COOL_UNTIL : undefined,
+    })), Date.now(), { pinnedToFirst: options.modelProviderPinned === true && options.requested !== undefined && options.requested !== '' });
+    // Return the ORIGINAL Model object by reference so identity assertions hold.
+    const pools = [options.available, options.registered ?? [], options.authenticated ?? [], options.cooling ?? []];
+    const findModel = (provider, id) => {
+        for (const pool of pools) {
+            const m = pool.find((x) => x.provider === provider && x.id === id);
+            if (m !== undefined)
+                return m;
+        }
+        return { provider, id };
+    };
+    const selected = result.candidates[0];
+    return {
+        model: selected === undefined ? undefined : findModel(selected.providerId, selected.modelId),
+        rejections: result.rejected.map(({ candidate, reason }) => ({
+            spec: key(candidate.providerId, candidate.modelId),
+            reason: REJECTION_TEXT[reason],
+        })),
+    };
+}
+test('launch candidate resolver keeps a healthy explicit provider pin ahead of authenticated alternatives', () => {
+    const result = resolve({ requested: 'anthropic/requested', available: [alternative, requested], modelProviderPinned: true });
+    assert.equal(result.model, requested);
+    assert.deepEqual(result.rejections, []);
+});
+test('launch candidate resolver selects a non-managed candidate as automatic fallback when no managed provider is authenticated', () => {
+    const localModel = { provider: 'lm-studio', id: 'qwen' };
+    const result = resolve({ requested: 'missing/missing', available: [localModel] });
+    assert.equal(result.model, localModel);
+    assert.deepEqual(result.rejections, [
+        { spec: 'missing/missing', reason: 'not registered' },
+    ]);
+});
+test('broker launch falls back to a non-managed provider when no managed provider is authenticated', async () => {
+    const cwd = mkdtempSync(join(tmpdir(), 'crtr-launch-candidate-'));
+    try {
+        const engine = {
+            ...realEngine,
+            async createAgentSessionServices(options) {
+                const services = await realEngine.createAgentSessionServices(options);
+                const custom = services.modelRuntime.getModel('c3prov', 'c3model');
+                // The broker reads models through pi's sync ModelRegistry facade, which delegates
+                // getAll/getAvailable/hasConfiguredAuth straight to these three runtime methods.
+                const modelRuntime = Object.create(services.modelRuntime);
+                modelRuntime.getModels = () => [custom];
+                modelRuntime.getAvailableSnapshot = () => [custom];
+                modelRuntime.hasConfiguredAuth = (providerId) => providerId === custom.provider;
+                return { ...services, modelRuntime };
+            },
+        };
+        const { session } = await buildBrokerSession(engine, { cwd, extensionPaths: [C3_EXT], model: 'missing/missing' });
+        try {
+            assert.equal(`${session.model?.provider}/${session.model?.id}`, 'c3prov/c3model');
+        }
+        finally {
+            session.dispose();
+        }
+    }
+    finally {
+        rmSync(cwd, { recursive: true, force: true });
+    }
+});
+test('broker launch honors an explicitly requested non-managed provider', async () => {
+    const cwd = mkdtempSync(join(tmpdir(), 'crtr-launch-candidate-'));
+    try {
+        const { session } = await buildBrokerSession(realEngine, { cwd, extensionPaths: [C3_EXT], model: 'c3prov/c3model' });
+        try {
+            assert.equal(`${session.model?.provider}/${session.model?.id}`, 'c3prov/c3model');
+        }
+        finally {
+            session.dispose();
+        }
+    }
+    finally {
+        rmSync(cwd, { recursive: true, force: true });
+    }
+});
+test('launch candidate resolver rejects an unregistered explicit provider pin without trying alternatives', () => {
+    const result = resolve({
+        requested: 'anthropic/missing',
+        available: [alternative],
+        modelProviderPinned: true,
+    });
+    assert.equal(result.model, undefined);
+    assert.deepEqual(result.rejections, [{ spec: 'anthropic/missing', reason: 'not registered' }]);
+});
+test('launch candidate resolver rejects an unauthenticated explicit provider pin without trying alternatives', () => {
+    const result = resolve({
+        requested: 'anthropic/requested',
+        available: [requested, alternative],
+        authenticated: [alternative],
+        modelProviderPinned: true,
+    });
+    assert.equal(result.model, undefined);
+    assert.deepEqual(result.rejections, [{ spec: 'anthropic/requested', reason: 'provider has no configured credentials' }]);
+});
+test('launch candidate resolver tries a cross-provider alternative when an explicit managed provider pin is cooling', () => {
+    const result = resolve({
+        requested: 'anthropic/requested',
+        available: [requested, alternative],
+        cooling: [requested],
+        modelProviderPinned: true,
+    });
+    assert.equal(result.model, alternative);
+    assert.deepEqual(result.rejections, [{ spec: 'anthropic/requested', reason: 'managed provider is cooling down' }]);
+});
+test('launch candidate resolver leaves no model selected when every candidate is unavailable, unauthenticated, or cooling', () => {
+    const unconfigured = { provider: 'openai-codex', id: 'unconfigured' };
+    const result = resolve({
+        requested: 'anthropic/missing',
+        available: [unconfigured, requested],
+        registered: [unconfigured, requested],
+        authenticated: [requested],
+        cooling: [requested],
+    });
+    assert.equal(result.model, undefined);
+    assert.deepEqual(result.rejections, [
+        { spec: 'anthropic/missing', reason: 'not registered' },
+        { spec: 'openai-codex/unconfigured', reason: 'provider has no configured credentials' },
+        { spec: 'anthropic/requested', reason: 'managed provider is cooling down' },
+    ]);
+});
+test('launch candidate resolver blocks a non-managed fallback while a managed provider is authenticated, even though it is currently cooling', () => {
+    const managedCooling = { provider: 'anthropic', id: 'managed' };
+    const localModel = { provider: 'lm-studio', id: 'qwen' };
+    const result = resolve({
+        requested: 'missing/missing',
+        available: [managedCooling, localModel],
+        authenticated: [managedCooling, localModel],
+        cooling: [managedCooling],
+    });
+    assert.equal(result.model, undefined);
+    assert.deepEqual(result.rejections, [
+        { spec: 'missing/missing', reason: 'not registered' },
+        { spec: 'anthropic/managed', reason: 'managed provider is cooling down' },
+        { spec: 'lm-studio/qwen', reason: 'non-managed provider is not an automatic fallback' },
+    ]);
+});
+test('launch candidate resolver leaves no model selected on a genuine zero-auth boot', () => {
+    const result = resolve({ requested: 'anthropic/missing', available: [] });
+    assert.equal(result.model, undefined);
+});
+test('real SDK contract: a model-less session boots to the unknown-stub (never undefined) and prompt() rejects on missing auth', async () => {
+    const cwd = mkdtempSync(join(tmpdir(), 'crtr-launch-candidate-'));
+    const agentDir = mkdtempSync(join(tmpdir(), 'crtr-launch-candidate-agent-'));
+    try {
+        const services = await realEngine.createAgentSessionServices({ cwd, agentDir });
+        const sessionManager = realEngine.SessionManager.create(cwd);
+        const { session } = await realEngine.createAgentSessionFromServices({
+            services,
+            sessionManager,
+            model: undefined,
+            tools: [],
+        });
+        try {
+            // The pinned pi SDK NEVER yields `session.model === undefined` for a
+            // model-less construction: Agent.createMutableAgentState() falls back to a
+            // hardcoded `{ provider:'unknown', id:'unknown', api:'unknown', … }` stub.
+            // A literal `=== undefined` guard (which the fake engine satisfies) is
+            // therefore DEAD in production — the broker's isUnknownModel() is what
+            // actually recognizes this stub as "no model", so pin the contract here.
+            assert.notEqual(session.model, undefined);
+            assert.equal(session.model?.provider, 'unknown');
+            assert.equal(session.model?.id, 'unknown');
+            assert.equal(isUnknownModel(session.model), true);
+            // prompt() against the stub rejects on the MISSING API KEY — the SDK's
+            // `if (!this.model)` "No model selected" guard is never reached because
+            // the stub is truthy — so a model-less boot is only usable once a /login
+            // re-drive selects a real model.
+            await assert.rejects(() => session.prompt('hi'), /no api key found/i);
+        }
+        finally {
+            session.dispose();
+        }
+    }
+    finally {
+        rmSync(cwd, { recursive: true, force: true });
+        rmSync(agentDir, { recursive: true, force: true });
+    }
+});

package/dist/core/__tests__/broker-preflight.test.d.ts

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

package/dist/core/__tests__/broker-preflight.test.js

@@ -0,0 +1,95 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/broker-preflight.test.ts
+//
+// Bug-regression: preflight broker launch validation should resolve the default
+// broker package, reject broken custom engines, and fail before a detached broker
+// process is spawned when session args are invalid or missing.
+import { test, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, readFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { preflightBrokerLaunch } from '../runtime/host.js';
+import { CANVAS_EXTENSIONS } from '../runtime/launch.js';
+const HERE = dirname(fileURLToPath(import.meta.url));
+const FAKE_ENGINE = join(HERE, 'fixtures', 'fake-engine.ts');
+let home;
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-preflight-'));
+    process.env['CRTR_HOME'] = home;
+});
+after(() => {
+    rmSync(home, { recursive: true, force: true });
+    delete process.env['CRTR_HOME'];
+});
+function validArgv(...tail) {
+    return [...CANVAS_EXTENSIONS.flatMap((path) => ['-e', path]), ...tail];
+}
+function assertLaunchWrote(nodeId, inv) {
+    const launchPath = join(home, 'nodes', nodeId, 'broker-launch.json');
+    const parsed = JSON.parse(readFileSync(launchPath, 'utf8'));
+    assert.deepEqual(parsed, inv, 'the launch recipe exists and parses as JSON');
+}
+test('preflightBrokerLaunch uses the installed default broker package when no engine override is set', () => {
+    const nodeId = 'preflight-default-engine';
+    const inv = {
+        argv: validArgv('hello'),
+        env: {},
+    };
+    const prev = process.env['CRTR_BROKER_ENGINE'];
+    delete process.env['CRTR_BROKER_ENGINE'];
+    try {
+        assert.doesNotThrow(() => preflightBrokerLaunch(nodeId, inv, '/tmp/work'));
+    }
+    finally {
+        if (prev === undefined)
+            delete process.env['CRTR_BROKER_ENGINE'];
+        else
+            process.env['CRTR_BROKER_ENGINE'] = prev;
+    }
+    assertLaunchWrote(nodeId, inv);
+});
+test('preflightBrokerLaunch fails fast when the broker engine module cannot be resolved', () => {
+    const nodeId = 'preflight-bad-engine';
+    const inv = {
+        argv: validArgv('hello'),
+        env: { CRTR_BROKER_ENGINE: '@crouton-kit/does-not-exist' },
+    };
+    assert.throws(() => preflightBrokerLaunch(nodeId, inv, '/tmp/work'), /cannot resolve broker engine/i);
+    assertLaunchWrote(nodeId, inv);
+});
+test('preflightBrokerLaunch rejects missing or duplicate mandatory canvas hooks before broker readiness', () => {
+    const missing = { argv: ['hello'], env: { CRTR_BROKER_ENGINE: FAKE_ENGINE } };
+    assert.throws(() => preflightBrokerLaunch('preflight-missing-hook', missing, '/tmp/work'), /canvas extension.*found 0/i);
+    const duplicate = { argv: [...validArgv(), '-e', CANVAS_EXTENSIONS[0], 'hello'], env: { CRTR_BROKER_ENGINE: FAKE_ENGINE } };
+    assert.throws(() => preflightBrokerLaunch('preflight-duplicate-hook', duplicate, '/tmp/work'), /canvas extension.*found 2/i);
+});
+test('preflightBrokerLaunch validates the exact broker engine env passed to the detached broker', () => {
+    const nodeId = 'preflight-empty-engine';
+    const inv = {
+        argv: validArgv('hello'),
+        env: { CRTR_BROKER_ENGINE: '   ' },
+    };
+    assert.throws(() => preflightBrokerLaunch(nodeId, inv, '/tmp/work'), /cannot resolve broker engine/i);
+    assertLaunchWrote(nodeId, inv);
+});
+test('preflightBrokerLaunch fails fast when a bare --session id would be rejected by the broker', () => {
+    const nodeId = 'preflight-bare-session';
+    const inv = {
+        argv: validArgv('--session', 'uuid-123'),
+        env: { CRTR_BROKER_ENGINE: FAKE_ENGINE },
+    };
+    assert.throws(() => preflightBrokerLaunch(nodeId, inv, '/tmp/work'), /bare --session id/i);
+    assertLaunchWrote(nodeId, inv);
+});
+test('preflightBrokerLaunch fails fast when a plainly-encoded session file path is missing', () => {
+    const nodeId = 'preflight-missing-session';
+    const inv = {
+        argv: validArgv('--session', join(home, 'sessions', 'missing.jsonl')),
+        env: { CRTR_BROKER_ENGINE: FAKE_ENGINE },
+    };
+    assert.throws(() => preflightBrokerLaunch(nodeId, inv, '/tmp/work'), /missing session file/i);
+    const launchPath = join(home, 'nodes', nodeId, 'broker-launch.json');
+    const parsed = JSON.parse(readFileSync(launchPath, 'utf8'));
+    assert.deepEqual(parsed, inv, 'the launch recipe exists and parses as JSON');
+});

package/dist/core/__tests__/broker-sdk-wiring.test.d.ts

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