@north-light/crouter 0.3.318 → 0.3.319

package/dist/core/__tests__/integration/broker-sdk-wiring.test.js

@@ -1,750 +0,0 @@
-// Run with: npm run test:integration
-//
-// REAL-SDK regression tests for the latent broker gaps the viewer-reuse scout
-// (node mq5thyli) found (findings-viewer-reuse.md §Q2). These deliberately drive
-// the ACTUAL `@earendil-works/pi-coding-agent` SDK — NOT the `CRTR_BROKER_ENGINE`
-// fake the lifecycle suite uses — because C3 and C4 slipped past the Phase-3 gate
-// PRECISELY because that gate mocked the SDK out. Each test exercises the exact
-// production wiring (`buildBrokerSession` / `makeBrokerUiContext`) and would FAIL
-// against the pre-fix broker:
-//
-//   C3 — the broker drives the SERVICES path, so an extension-registered custom
-//        model provider is registered into the ModelRegistry and resolves onto
-//        the session. Plain createAgentSession never calls registerProvider, so a
-//        custom-provider node would get NO model.
-//   C2 — with ZERO viewers attached, the broker UI context resolves confirm() /
-//        select() / input() / editor() to deny/cancel IMMEDIATELY (noOp), instead
-//        of relying on a per-dialog timeout and hanging the agent turn forever.
-//
-// These run offline (no network/auth): registration + system-prompt assembly +
-// dialog routing are all local. No tmux, no broker process — direct unit drives.
-import { after, before, test } from 'node:test';
-import assert from 'node:assert/strict';
-import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync } from 'node:fs';
-import { spawnSync } from 'node:child_process';
-import { tmpdir } from 'node:os';
-import { join, dirname } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { createAgentSessionServices, createAgentSessionFromServices, SessionManager, VERSION, } from '../../runtime/broker-sdk.js';
-import { buildBrokerSession, makeBrokerUiContext, snapshotMessages } from '../../runtime/broker.js';
-import { isLeadingEngineCommand, resolveSteerCall, chooseGuidanceDeliveryMode, promptWithNextTurnGuidance, engineLeadingCommandTokens, } from '../../runtime/broker/engine-routing.js';
-import { isHiddenJsonlBranchEntry, stripHiddenEntriesFromJsonlExport, } from '../../runtime/broker/frame-session.js';
-import { CANVAS_EXTENSIONS } from '../../runtime/launch.js';
-import { prepareAdvertisedCommandPersistence, promptWithAdvertisedCommandInvocation, } from '../../runtime/advertised-command-invocation.js';
-import { closeDb, migrate, openDb } from '../../canvas/db.js';
-import { closeScopedStores } from '../../scoped-state/db.js';
-import { initializeFreshScopedStore } from '../../scoped-state/migrate.js';
-// The REAL engine, assembled from broker-sdk's static SDK re-exports — bypasses
-// the CRTR_BROKER_ENGINE seam entirely so these tests can never accidentally hit
-// the fake (the whole point: prove the wiring the mock hid).
-const realEngine = {
-    createAgentSessionServices,
-    createAgentSessionFromServices,
-    SessionManager,
-    VERSION,
-};
-const HERE = join(dirname(fileURLToPath(import.meta.url)), '..');
-const C3_EXT = join(HERE, 'fixtures', 'c3-custom-provider-ext.ts');
-const C5_EXT = join(HERE, 'fixtures', 'c5-command-boundary-ext.ts');
-const priorModelIntent = process.env['CRTR_MODEL_INTENT'];
-const priorNodeCwd = process.env['CRTR_NODE_CWD'];
-const priorProfileId = process.env['CRTR_PROFILE_ID'];
-const priorHome = process.env['HOME'];
-const priorCanvasHome = process.env['CRTR_HOME'];
-const priorAgentDir = process.env['PI_CODING_AGENT_DIR'];
-let home;
-let agentDir;
-before(() => {
-    home = mkdtempSync(join(tmpdir(), 'crtr-sdk-wiring-home-'));
-    agentDir = join(home, '.pi', 'agent');
-    closeDb();
-    closeScopedStores();
-    process.env['HOME'] = home;
-    process.env['CRTR_HOME'] = join(home, '.crouter', 'canvas');
-    process.env['PI_CODING_AGENT_DIR'] = agentDir;
-    migrate(openDb());
-    initializeFreshScopedStore({ kind: 'user', root: join(home, '.crouter') });
-    initializeFreshScopedStore({ kind: 'provider', root: agentDir });
-    // buildBrokerSession normally receives its environment through buildBrokerEnv,
-    // which strips the launcher's CRTR_* values before applying the target recipe.
-    // These direct SDK tests bypass that boundary, so clear the ambient node's
-    // routing scope and intent to exercise only each fixture's explicit config.
-    delete process.env['CRTR_MODEL_INTENT'];
-    delete process.env['CRTR_NODE_CWD'];
-    delete process.env['CRTR_PROFILE_ID'];
-});
-after(() => {
-    closeDb();
-    closeScopedStores();
-    if (priorModelIntent === undefined)
-        delete process.env['CRTR_MODEL_INTENT'];
-    else
-        process.env['CRTR_MODEL_INTENT'] = priorModelIntent;
-    if (priorNodeCwd === undefined)
-        delete process.env['CRTR_NODE_CWD'];
-    else
-        process.env['CRTR_NODE_CWD'] = priorNodeCwd;
-    if (priorProfileId === undefined)
-        delete process.env['CRTR_PROFILE_ID'];
-    else
-        process.env['CRTR_PROFILE_ID'] = priorProfileId;
-    if (priorHome === undefined)
-        delete process.env['HOME'];
-    else
-        process.env['HOME'] = priorHome;
-    if (priorCanvasHome === undefined)
-        delete process.env['CRTR_HOME'];
-    else
-        process.env['CRTR_HOME'] = priorCanvasHome;
-    if (priorAgentDir === undefined)
-        delete process.env['PI_CODING_AGENT_DIR'];
-    else
-        process.env['PI_CODING_AGENT_DIR'] = priorAgentDir;
-    rmSync(home, { recursive: true, force: true });
-});
-function brokerExts() {
-    return [...CANVAS_EXTENSIONS, C3_EXT];
-}
-function cfg(cwd, extra = {}) {
-    return { cwd, extensionPaths: brokerExts(), ...extra };
-}
-// C3 — the SERVICES path registers an extension's custom model provider, so the
-// broker resolves a model that plain createAgentSession (no registerProvider)
-// would never see.
-test('C3 — services path registers an extension model provider; the broker session gets it', async () => {
-    const cwd = mkdtempSync(join(tmpdir(), 'crtr-c3-'));
-    try {
-        const { session, services } = await buildBrokerSession(realEngine, cfg(cwd, { extensionPaths: [C3_EXT], model: 'c3prov/c3model' }));
-        try {
-            // The extension's provider was registered into the SERVICES model runtime (this
-            // is the registerProvider step plain createAgentSession skips).
-            const found = services.modelRuntime.getModel('c3prov', 'c3model');
-            assert.ok(found, 'C3: extension-registered model is present in the services ModelRuntime');
-            assert.equal(found.provider, 'c3prov', 'C3: provider name round-trips');
-            assert.equal(found.id, 'c3model', 'C3: model id round-trips');
-            // …and the broker resolved it onto the session AGAINST the services runtime
-            // (a fresh ModelRuntime would have returned undefined → no model).
-            assert.equal(session.model?.id, 'c3model', 'C3: the broker session got the custom-provider model');
-        }
-        finally {
-            session.dispose();
-        }
-    }
-    finally {
-        rmSync(cwd, { recursive: true, force: true });
-    }
-});
-test('C3b — broker splits model thinking suffix before SDK registry lookup', async () => {
-    const cwd = mkdtempSync(join(tmpdir(), 'crtr-c3b-'));
-    try {
-        const { session } = await buildBrokerSession(realEngine, cfg(cwd, { extensionPaths: [C3_EXT], model: 'c3prov/c3model:high' }));
-        try {
-            assert.equal(session.model?.id, 'c3model', 'C3b: suffixed model specs resolve by model id instead of falling back to SDK default');
-        }
-        finally {
-            session.dispose();
-        }
-    }
-    finally {
-        rmSync(cwd, { recursive: true, force: true });
-    }
-});
-test('C3c — mandatory canvas extensions must be loaded, not merely passed in argv', async () => {
-    const cwd = mkdtempSync(join(tmpdir(), 'crtr-c3c-'));
-    try {
-        const badServiceFailureEngine = {
-            createAgentSessionServices: async () => ({
-                cwd,
-                agentDir: cwd,
-                modelRegistry: { hasConfiguredAuth: () => false, getAvailable: () => [] },
-                diagnostics: [],
-                resourceLoader: {
-                    getExtensions: () => ({
-                        extensions: CANVAS_EXTENSIONS.slice(1).map((path) => ({
-                            path,
-                            resolvedPath: path,
-                            sourceInfo: {},
-                            handlers: new Map(),
-                            tools: new Map(),
-                            messageRenderers: new Map(),
-                        })),
-                        errors: [{ path: CANVAS_EXTENSIONS[0], error: 'boom' }],
-                        runtime: {},
-                    }),
-                },
-            }),
-            createAgentSessionFromServices: async () => {
-                throw new Error('C3c: must fail before session creation');
-            },
-            SessionManager: class {
-                static create = () => ({});
-            },
-            VERSION: 'test',
-        };
-        await assert.rejects(() => buildBrokerSession(badServiceFailureEngine, cfg(cwd, { model: 'c3prov/c3model' })), /mandatory canvas extensions failed to load/);
-    }
-    finally {
-        rmSync(cwd, { recursive: true, force: true });
-    }
-});
-function runIsolatedManagedLaunch(pool) {
-    const home = mkdtempSync(join(tmpdir(), 'crtr-c3-managed-home-'));
-    const cwd = mkdtempSync(join(tmpdir(), 'crtr-c3-managed-cwd-'));
-    const canvasHome = join(home, '.crouter', 'canvas');
-    const agentDir = join(home, '.pi', 'agent');
-    const script = `
-    process.env.CRTR_HOME = ${JSON.stringify(canvasHome)};
-    process.env.PI_CODING_AGENT_DIR = ${JSON.stringify(agentDir)};
-    const { createAgentSessionServices, createAgentSessionFromServices, SessionManager, VERSION } = await import(${JSON.stringify(new URL('../../runtime/broker-sdk.ts', import.meta.url).href)});
-    const { buildBrokerSession } = await import(${JSON.stringify(new URL('../../runtime/broker.ts', import.meta.url).href)});
-    const { migrate, openDb } = await import(${JSON.stringify(new URL('../../canvas/db.ts', import.meta.url).href)});
-    const { initializeFreshScopedStore } = await import(${JSON.stringify(new URL('../../scoped-state/migrate.ts', import.meta.url).href)});
-    const { writeSubscriptionPool } = await import(${JSON.stringify(new URL('../../subscription-state.ts', import.meta.url).href)});
-    migrate(openDb());
-    initializeFreshScopedStore({ kind: 'user', root: ${JSON.stringify(join(home, '.crouter'))} });
-    initializeFreshScopedStore({ kind: 'provider', root: ${JSON.stringify(agentDir)} });
-    await writeSubscriptionPool('anthropic', ${JSON.stringify(pool)});
-    const realEngine = { createAgentSessionServices, createAgentSessionFromServices, SessionManager, VERSION };
-    const engine = {
-      ...realEngine,
-      async createAgentSessionServices(options) {
-        const services = await realEngine.createAgentSessionServices(options);
-        const fallback = services.modelRuntime.getModel('c3prov', 'c3model');
-        if (!fallback) throw new Error('test fallback model was not registered');
-        const requested = { ...fallback, provider: 'anthropic', id: 'cooling-model' };
-        // The broker reads models through pi's sync ModelRegistry facade, which delegates
-        // getModel/getModels/getAvailableSnapshot/hasConfiguredAuth to the runtime.
-        const modelRuntime = Object.create(services.modelRuntime);
-        modelRuntime.getModel = (provider, id) =>
-          provider === 'anthropic' && id === 'cooling-model' ? requested : provider === 'c3prov' && id === 'c3model' ? fallback : undefined;
-        modelRuntime.getModels = () => [requested, fallback];
-        modelRuntime.getAvailableSnapshot = () => [fallback];
-        modelRuntime.hasConfiguredAuth = (providerId) => providerId === fallback.provider;
-        return { ...services, modelRuntime };
-      },
-    };
-    const { session } = await buildBrokerSession(engine, { cwd: ${JSON.stringify(cwd)}, extensionPaths: [${JSON.stringify(C3_EXT)}], model: 'anthropic/cooling-model' });
-    console.log(JSON.stringify({ provider: session.model?.provider, id: session.model?.id }));
-    session.dispose();
-  `;
-    try {
-        const result = spawnSync(process.execPath, ['--import', 'tsx/esm', '--input-type=module', '-e', script], {
-            cwd: process.cwd(),
-            env: { ...process.env, HOME: home },
-            encoding: 'utf8',
-        });
-        assert.equal(result.status, 0, result.stderr);
-        return JSON.parse(result.stdout);
-    }
-    finally {
-        rmSync(home, { recursive: true, force: true });
-        rmSync(cwd, { recursive: true, force: true });
-    }
-}
-test('C3f — a logical request can reach a non-managed raw-registry fallback when no managed provider is authenticated', async () => {
-    const cwd = mkdtempSync(join(tmpdir(), 'crtr-c3c-'));
-    const priorIntent = process.env['CRTR_MODEL_INTENT'];
-    const priorNodeCwd = process.env['CRTR_NODE_CWD'];
-    process.env['CRTR_MODEL_INTENT'] = 'custom/strong';
-    process.env['CRTR_NODE_CWD'] = cwd;
-    mkdirSync(join(cwd, '.crouter'), { recursive: true });
-    writeFileSync(join(cwd, '.crouter', 'config.json'), `${JSON.stringify({
-        modelRoutes: {
-            c3: {
-                family: 'custom',
-                credentialSource: 'user',
-                providerId: 'c3prov',
-                models: { ultra: 'c3prov/c3model', strong: 'c3prov/c3model', medium: 'c3prov/c3model', light: 'c3prov/c3model' },
-            },
-        },
-    })}\n`);
-    try {
-        const deterministicEngine = {
-            ...realEngine,
-            async createAgentSessionServices(options) {
-                const services = await realEngine.createAgentSessionServices(options);
-                const requested = services.modelRuntime.getModel('c3prov', 'c3model');
-                const fallback = services.modelRuntime.getModel('c3fallback', 'fallback-model');
-                // 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 = () => [requested, fallback];
-                modelRuntime.getAvailableSnapshot = () => [fallback];
-                modelRuntime.hasConfiguredAuth = (providerId) => providerId === fallback.provider;
-                return { ...services, modelRuntime };
-            },
-        };
-        // The requested model (c3prov/c3model) is registered but UNauthenticated, and
-        // the only authenticated candidate is the non-managed c3fallback/fallback-model.
-        // With NO managed provider authenticated, resolveLaunchModel's tier-2 promotes
-        // that authenticated non-managed model to an automatic fallback — so the launch
-        // SUCCEEDS on it rather than rejecting.
-        const { session } = await buildBrokerSession(deterministicEngine, cfg(cwd, { extensionPaths: [C3_EXT], model: 'c3prov/c3model' }));
-        try {
-            assert.equal(`${session.model?.provider}/${session.model?.id}`, 'c3fallback/fallback-model');
-        }
-        finally {
-            session.dispose();
-        }
-    }
-    finally {
-        if (priorIntent === undefined)
-            delete process.env['CRTR_MODEL_INTENT'];
-        else
-            process.env['CRTR_MODEL_INTENT'] = priorIntent;
-        if (priorNodeCwd === undefined)
-            delete process.env['CRTR_NODE_CWD'];
-        else
-            process.env['CRTR_NODE_CWD'] = priorNodeCwd;
-        rmSync(cwd, { recursive: true, force: true });
-    }
-});
-test('C3g — an explicit managed subscription pool authenticates a registered requested model without SDK auth', () => {
-    const selected = runIsolatedManagedLaunch([
-        { label: 'explicit', refresh: 'r', access: 'a', expires: Date.now() + 60_000, rateLimitedUntil: 0, lastAttemptAt: 0, lastRateLimitedAt: 0 },
-    ]);
-    assert.equal(selected.provider, 'anthropic');
-    assert.equal(selected.id, 'cooling-model');
-});
-test('C3h — a cooling managed launch target boots model-less rather than falling back to a non-managed provider', () => {
-    // The managed anthropic target is registered + pool-authenticated but COOLING
-    // (rateLimitedUntil in the future). Because a managed provider IS authenticated,
-    // resolveLaunchModel's tier-2 refuses the non-managed c3prov/c3model fallback;
-    // the only managed target is cooling ⇒ tier-3 selects no model ⇒ the broker boots
-    // MODEL-LESS (the real SDK's unknown-stub) instead of throwing 'no viable launch
-    // model'. The title's intent — a cooling managed target does NOT drag in a
-    // non-managed provider — now holds by booting model-less.
-    const selected = runIsolatedManagedLaunch([
-        { label: 'explicit', refresh: 'r', access: 'a', expires: Date.now() + 60_000, rateLimitedUntil: Date.now() + 60_000, lastAttemptAt: 0, lastRateLimitedAt: 0 },
-    ]);
-    assert.equal(selected.provider, 'unknown');
-    assert.equal(selected.id, 'unknown');
-});
-// (C4 — project guidance now comes from the document substrate: crouter keeps
-// `noContextFiles: true` in buildBrokerSession, and buildContextIntro's
-// `<project_context>` block is environment-only. Covered by
-// context-intro.test.ts's environment-only regression.)
-// C2 — zero-writable dialogs resolve to deny/cancel IMMEDIATELY (noOp), never
-// hanging the turn and never waiting on a per-dialog timeout. Drives the REAL
-// makeBrokerUiContext (the exact ExtensionUIContext the SDK hands extensions),
-// with a writable() snapshot that reports zero writable viewers.
-test('C2 — zero-writable UI context resolves dialogs to deny/cancel immediately (noOp, no hang)', async () => {
-    const ctx = makeBrokerUiContext({
-        writable: () => [], // ZERO writable viewers attached
-        forward: () => {
-            throw new Error('C2: must NOT forward a dialog when no writable viewer is attached');
-        },
-        pending: new Map(),
-        broadcast: () => { },
-    });
-    // confirm() WITH a large timeout: the fix must resolve at once (deny), NOT after
-    // the timeout — the old timeout-reliant path would have waited 60s (or, with no
-    // timeout, hung forever). Race against a 2s "HANG" sentinel to make a regression
-    // a hard failure rather than a slow pass.
-    const start = Date.now();
-    const confirmed = await Promise.race([
-        ctx.confirm('proceed?', 'really?', { timeout: 60_000 }),
-        new Promise((r) => setTimeout(() => r('HANG'), 2_000)),
-    ]);
-    assert.equal(confirmed, false, 'C2: confirm() denies (false) with zero viewers');
-    assert.ok(Date.now() - start < 1_000, 'C2: resolved immediately, not after the 60s timeout');
-    // The other blocking dialogs cancel to undefined — including editor(), which
-    // takes NO opts at all (so it could never carry a timeout to lean on).
-    assert.equal(await ctx.select('pick', ['a', 'b']), undefined, 'C2: select() cancels (undefined)');
-    assert.equal(await ctx.input('name'), undefined, 'C2: input() cancels (undefined)');
-    assert.equal(await ctx.editor('edit'), undefined, 'C2: editor() cancels (undefined)');
-});
-// M2 (review mq5wkqep / T4) — REPLACES the Wave-0 M-1 cancel-on-detach. A dialog
-// forwarded to a writable viewer that then DETACHES must NOT be cancelled: it
-// stays pending so a brief detach/reattach (or another writable viewer joining)
-// does not lose an answerable dialog. The broker-side default timeout is the ONLY
-// non-answer resolution (proven here with a short per-dialog timeout standing in
-// for the 120s default). Guards against regressing to the over-eager cancel.
-test('M2 — a forwarded dialog stays pending when its writable viewer detaches, resolving only on the broker-side timeout', async () => {
-    const pending = new Map();
-    let attached = true;
-    const ctx = makeBrokerUiContext({
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        writable: () => (attached ? [{ id: 'c1' }] : []),
-        forward: () => {
-            /* a real writable viewer would receive the request over its socket */
-        },
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        pending: pending,
-        broadcast: () => { },
-    });
-    // A writable viewer attached → confirm() forwards + registers a pending dialog
-    // (with the request retained for welcome.pending_dialog / replay, T4) and does
-    // NOT resolve yet. A short per-dialog timeout stands in for the 120s broker default.
-    const p = ctx.confirm('proceed?', 'really?', { timeout: 80 });
-    assert.equal(pending.size, 1, 'M2: a forwarded dialog is pending while a writable viewer is attached');
-    const entry = [...pending.values()][0];
-    assert.ok(entry.request, 'M2: the pending entry retains the request (welcome/re-route need it)');
-    assert.equal(entry.cancel, undefined, 'M2: there is no cancel-on-detach path anymore');
-    // The writable viewer detaches → the dialog STAYS pending (the broker no longer cancels it).
-    attached = false;
-    assert.equal(pending.size, 1, 'M2: writable-viewer detach does NOT cancel the in-flight dialog');
-    // Only the broker-side timeout resolves it, to the SAFE default (deny).
-    const resolved = await Promise.race([
-        p,
-        new Promise((r) => setTimeout(() => r('HANG'), 2_000)),
-    ]);
-    assert.equal(resolved, false, 'M2: resolves to deny on the broker-side timeout, never hangs');
-    assert.equal(pending.size, 0, 'M2: the pending registry is drained after the timeout');
-});
-// C5 — exact leading engine-command suppression and hidden display:false
-// guidance delivery ordering.
-//
-// REACHABILITY NOTE: broker.ts's `handleFrame`/`driveEngine` switches are
-// private closures inside `runBroker`, so this serialized source suite does not
-// boot a broker process to drive raw wire frames (that end-to-end plumbing lives
-// in the compiled seam alongside the sibling `list_models` read-op). Instead every
-// EXPORTED building block those closures call is driven directly — the pure
-// decision functions (`isLeadingEngineCommand`, `chooseGuidanceDeliveryMode`,
-// `engineLeadingCommandTokens`) AND the stateful delivery/export helpers
-// (`promptWithNextTurnGuidance`, `stripHiddenEntriesFromJsonlExport` /
-// `isHiddenJsonlBranchEntry`) — against a REAL SDK session or REAL exported
-// JSONL bytes, including the exact interception/leak window (Major 1) and the
-// actual exported file (Major 2). What remains untested here is only the
-// one-line frame relay (`sendFrame(client, buildListMemoryRefsData(id))`), a
-// verbatim sibling of the compiled-seam-covered `list_models` dispatch whose only
-// non-trivial input, `engineLeadingCommandTokens(session)`, is proven below
-// against a real session.
-test('a streaming extension command uses prompt preflight instead of the rejecting steer queue', () => {
-    const session = { extensionRunner: { getCommand: (name) => (name === 'recap' ? { name: 'recap' } : undefined) } };
-    assert.equal(resolveSteerCall('/recap', session), 'prompt');
-    assert.equal(resolveSteerCall('new information', session), 'steer');
-});
-test('C5 — isLeadingEngineCommand against a REAL session (registered extension command)', async () => {
-    // Only the extension-command branch is driven against a REAL session here.
-    // Skill/prompt-template discovery requires `session.bindExtensions(...)`
-    // (the real broker's initial-boot step, which fires `resources_discover`) —
-    // not reachable from `buildBrokerSession` alone, and driving it directly
-    // pulls in this machine's full local pi resource corpus (slow, environment-
-    // dependent). The skill/prompt-template branches run the same accessor-
-    // guarded decision logic as the extension-command branch proven here.
-    const cwd = mkdtempSync(join(tmpdir(), 'crtr-c5-cmd-'));
-    try {
-        const { session } = await buildBrokerSession(realEngine, cfg(cwd, { extensionPaths: [C3_EXT, C5_EXT], model: 'c3prov/c3model' }));
-        try {
-            assert.equal(isLeadingEngineCommand('/devcmd', session), true, 'a real registered extension command matches');
-            assert.equal(isLeadingEngineCommand('/devcmd extra args', session), true, 'space-separated still matches against a real session');
-            assert.equal(isLeadingEngineCommand('/nope', session), false, 'an unregistered command does not match against a real session');
-        }
-        finally {
-            session.dispose();
-        }
-    }
-    finally {
-        rmSync(cwd, { recursive: true, force: true });
-    }
-});
-test('an advertised custom command persists its exact raw invocation without replacing expanded agent input', async () => {
-    const cwd = mkdtempSync(join(tmpdir(), 'crtr-advertised-command-'));
-    try {
-        const { session } = await buildBrokerSession(realEngine, cfg(cwd, { extensionPaths: [C5_EXT] }));
-        try {
-            const raw = '/gatewaycmd   exact  spacing  ';
-            await promptWithAdvertisedCommandInvocation(session, raw, () => session.prompt(raw, {}));
-            const custom = session.sessionManager
-                .buildSessionContext()
-                .messages.find((message) => message.role === 'custom' && message.customType === 'fixture-output');
-            assert.deepEqual(custom, {
-                role: 'custom',
-                customType: 'fixture-output',
-                content: 'expanded agent input',
-                display: true,
-                details: { fixture: true },
-                crouterAdvertisedCommandInvocation: { raw },
-                timestamp: custom?.timestamp,
-            });
-            const welcome = snapshotMessages(session);
-            assert.ok(welcome);
-            const welcomeCustom = welcome.filter(({ message }) => message.role === 'custom' && message.customType === 'fixture-output');
-            assert.equal(welcomeCustom.length, 1, 'welcome reconstructs one advertised custom message');
-            assert.deepEqual(welcomeCustom[0].message
-                .crouterAdvertisedCommandInvocation, { raw }, 'welcome preserves the exact advertised invocation spacing');
-            const persisted = session.sessionManager
-                .getEntries()
-                .find((entry) => entry.type === 'custom_message' &&
-                entry.customType === 'fixture-output');
-            assert.equal(persisted?.type, 'custom_message');
-            if (persisted?.type !== 'custom_message')
-                assert.fail('custom message was not persisted');
-            assert.equal(persisted.content, 'expanded agent input');
-            assert.deepEqual(persisted.details, {
-                crouterPersistenceEnvelope: true,
-                crouterAdvertisedCommandInvocation: { raw },
-                extensionDetails: { fixture: true },
-            });
-        }
-        finally {
-            session.dispose();
-        }
-    }
-    finally {
-        rmSync(cwd, { recursive: true, force: true });
-    }
-});
-test('advertised invocation metadata survives nextTurn delivery and null content normalization', async () => {
-    const cwd = mkdtempSync(join(tmpdir(), 'crtr-advertised-next-turn-'));
-    try {
-        const { session } = await buildBrokerSession(realEngine, cfg(cwd, { extensionPaths: [C5_EXT] }));
-        try {
-            const rawA = '/gatewaynext  first exact text ';
-            const rawB = '/gatewaynext  second exact text ';
-            for (const raw of [rawA, rawB]) {
-                await promptWithAdvertisedCommandInvocation(session, raw, () => session.prompt(raw, {}));
-            }
-            const pending = session._pendingNextTurnMessages;
-            assert.deepEqual(pending.map((queued) => ({
-                content: queued.content,
-                details: queued.details,
-                invocation: queued.crouterAdvertisedCommandInvocation,
-            })), [
-                {
-                    content: [],
-                    details: 'extension-details',
-                    invocation: { raw: rawA },
-                },
-                {
-                    content: [],
-                    details: 'extension-details',
-                    invocation: { raw: rawB },
-                },
-            ]);
-            // Simulate a queue policy draining B before A. Payload equality cannot
-            // identify them; the app-message metadata must bind each persistence.
-            for (const queued of [pending[1], pending[0]]) {
-                prepareAdvertisedCommandPersistence(session, queued);
-                session.sessionManager.appendCustomMessageEntry(queued.customType, queued.content, queued.display, queued.details);
-            }
-            const restored = session.sessionManager
-                .buildSessionContext()
-                .messages.slice(-2);
-            assert.deepEqual(restored.map((message) => ({
-                details: message.details,
-                invocation: message.crouterAdvertisedCommandInvocation,
-            })), [
-                { details: 'extension-details', invocation: { raw: rawB } },
-                { details: 'extension-details', invocation: { raw: rawA } },
-            ]);
-        }
-        finally {
-            session.dispose();
-        }
-    }
-    finally {
-        rmSync(cwd, { recursive: true, force: true });
-    }
-});
-test('C5 — chooseGuidanceDeliveryMode truth table (pure)', () => {
-    // idle prompt (routeCall='prompt', not streaming) -> guidance precedes the
-    // human call, in the SAME turn.
-    assert.equal(chooseGuidanceDeliveryMode('prompt', 'prompt', false), 'nextTurn');
-    // idle follow_up escalated to a prompt route -> same as above.
-    assert.equal(chooseGuidanceDeliveryMode('follow_up', 'prompt', false), 'nextTurn');
-    // a TRUE mid-stream follow_up -> followUp, human call first.
-    assert.equal(chooseGuidanceDeliveryMode('follow_up', 'followUp', true), 'followUp');
-    // a steer frame -> steer, always, regardless of routeCall/isStreaming.
-    assert.equal(chooseGuidanceDeliveryMode('steer', undefined, false), 'steer');
-    assert.equal(chooseGuidanceDeliveryMode('steer', 'prompt', true), 'steer');
-    // a prompt frame arriving WHILE streaming (m-B steer-while-streaming) ->
-    // steer, never nextTurn (that would attach guidance to a later, unrelated turn).
-    assert.equal(chooseGuidanceDeliveryMode('prompt', 'prompt', true), 'steer');
-});
-test('C5 — fake-engine sendCustomMessage records the call in order without crashing', async () => {
-    const home = mkdtempSync(join(tmpdir(), 'crtr-c5-fake-home-'));
-    const cwd = mkdtempSync(join(tmpdir(), 'crtr-c5-fake-cwd-'));
-    const prevHome = process.env['CRTR_HOME'];
-    const prevNodeId = process.env['CRTR_NODE_ID'];
-    try {
-        process.env['CRTR_HOME'] = home;
-        process.env['CRTR_NODE_ID'] = 'crtr-c5-fake-node';
-        const fake = await import('.././fixtures/fake-engine.js');
-        const services = await fake.createAgentSessionServices({ cwd });
-        const sessionManager = fake.SessionManager.create(cwd);
-        const { session } = await fake.createAgentSessionFromServices({ services, sessionManager });
-        try {
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            const anySession = session;
-            await anySession.sendCustomMessage({ customType: 'crtr-memory-refs', content: 'guidance text', display: false }, { deliverAs: 'nextTurn' });
-            assert.deepEqual(anySession.customMessages, [
-                { customType: 'crtr-memory-refs', content: 'guidance text', display: false, deliverAs: 'nextTurn' },
-            ]);
-        }
-        finally {
-            session.dispose();
-        }
-    }
-    finally {
-        if (prevHome === undefined)
-            delete process.env['CRTR_HOME'];
-        else
-            process.env['CRTR_HOME'] = prevHome;
-        if (prevNodeId === undefined)
-            delete process.env['CRTR_NODE_ID'];
-        else
-            process.env['CRTR_NODE_ID'] = prevNodeId;
-        rmSync(home, { recursive: true, force: true });
-        rmSync(cwd, { recursive: true, force: true });
-    }
-});
-// Review fix (Major 1) — promptWithNextTurnGuidance atomically clears its own
-// pending nextTurn guidance if the prompt it rode alongside never reaches pi's
-// internal drain point (agent-session.js `prompt()` step 8) — an extension-
-// command interception (step 1, `_tryExecuteExtensionCommand`) is a genuine,
-// fully offline SDK early-return that proves the exact leak window the review
-// flagged, without touching model/auth/network.
-test('Major 1 fix — promptWithNextTurnGuidance clears its own pending guidance when the human prompt is intercepted by an extension command (never reaches pi\'s drain)', async () => {
-    const cwd = mkdtempSync(join(tmpdir(), 'crtr-m1-atomic-'));
-    try {
-        const { session } = await buildBrokerSession(realEngine, cfg(cwd, { extensionPaths: [C5_EXT] }));
-        try {
-            // '/devcmd' is a REAL registered extension command (c5-command-boundary-
-            // ext.ts) — pi's own `_tryExecuteExtensionCommand` intercepts it at the
-            // FIRST await inside `prompt()`, well before the pending-nextTurn drain,
-            // and resolves the whole call successfully (handled=true) without ever
-            // reaching it. Pre-fix (`sendGuidance(...).then(() => session.prompt(...))`
-            // with no cleanup), this exact sequence stranded the guidance message in
-            // `_pendingNextTurnMessages` to leak into whatever LATER unrelated prompt
-            // happened to drain it next.
-            await promptWithNextTurnGuidance(session, 'crtr memory read dev', () => session.prompt('/devcmd', {}));
-            const pending = session._pendingNextTurnMessages;
-            assert.deepEqual(pending, [], 'Major 1: an intercepted prompt leaves NO stranded guidance — an unrelated later prompt would receive nothing');
-        }
-        finally {
-            session.dispose();
-        }
-    }
-    finally {
-        rmSync(cwd, { recursive: true, force: true });
-    }
-});
-test('promptWithNextTurnGuidance uses a structured-clone-safe cleanup marker', async () => {
-    const pending = [];
-    const session = {
-        _pendingNextTurnMessages: pending,
-        async sendCustomMessage(message) {
-            // Pi structured-clones the queued custom message while assembling a real
-            // turn. A Symbol marker reaches this seam and aborts the prompt before
-            // the provider runs; clone here to keep that runtime failure covered.
-            pending.push(structuredClone(message));
-        },
-    };
-    await promptWithNextTurnGuidance(session, 'crtr memory read dev', async () => undefined);
-    assert.deepEqual(pending, [], 'clone-safe marker still identifies and clears exactly its own pending entry');
-});
-test('Major 1 fix — promptWithNextTurnGuidance leaves the queue drained (not doubly-cleared) on a normal successful prompt', async () => {
-    // Guards against the cleanup over-firing on the HAPPY path: a prompt that
-    // genuinely reaches pi's drain already empties `_pendingNextTurnMessages`
-    // itself (folding the guidance into the SAME turn) — the cleanup must be a
-    // no-op here, not remove something pi already consumed correctly. Uses the
-    // '/devcmd' extension-command interception again (offline, no model/auth
-    // needed) as the "prompt call that settles" — what matters for this
-    // assertion is only that the queue ends empty either way, proving the
-    // splice-by-marker never throws or misbehaves on an already-empty queue.
-    const cwd = mkdtempSync(join(tmpdir(), 'crtr-m1-happy-'));
-    try {
-        const { session } = await buildBrokerSession(realEngine, cfg(cwd, { extensionPaths: [C5_EXT] }));
-        try {
-            await promptWithNextTurnGuidance(session, 'crtr memory read dev', () => session.prompt('/devcmd', {}));
-            await promptWithNextTurnGuidance(session, 'crtr memory read dev', () => session.prompt('/devcmd', {}));
-            const pending = session._pendingNextTurnMessages;
-            assert.deepEqual(pending, [], 'Major 1: repeated calls never accumulate a stale entry');
-        }
-        finally {
-            session.dispose();
-        }
-    }
-    finally {
-        rmSync(cwd, { recursive: true, force: true });
-    }
-});
-// Review fix (Major 2) — JSONL export (`session.exportToJsonl` via the broker
-// `case 'export'` handler) must honor the general `display:false` boundary,
-// not just `crtr-memory-refs` guidance. `stripHiddenEntriesFromJsonlExport`
-// rewrites the exported file in place; covers ACTUAL exported JSONL bytes,
-// not `transcriptMarkdown`.
-test('Major 2 fix — isHiddenJsonlBranchEntry recognizes both persisted display:false shapes', () => {
-    assert.equal(isHiddenJsonlBranchEntry({ type: 'custom_message', display: false }), true, 'a hidden custom_message entry matches');
-    assert.equal(isHiddenJsonlBranchEntry({ type: 'custom_message', display: true }), false, 'a visible custom_message entry does not match');
-    assert.equal(isHiddenJsonlBranchEntry({ type: 'custom_message' }), false, 'a custom_message entry with no display field does not match (only explicit false hides)');
-    assert.equal(isHiddenJsonlBranchEntry({ type: 'message', message: { role: 'custom', display: false } }), true, 'a hidden role:custom message entry matches');
-    assert.equal(isHiddenJsonlBranchEntry({ type: 'message', message: { role: 'custom', display: true } }), false, 'a visible role:custom message entry does not match');
-    assert.equal(isHiddenJsonlBranchEntry({ type: 'message', message: { role: 'user', display: false } }), false, 'a non-custom role message entry never matches, even with display:false');
-    assert.equal(isHiddenJsonlBranchEntry({ type: 'model_change' }), false, 'an unrelated branch entry type never matches');
-    assert.equal(isHiddenJsonlBranchEntry(null), false, 'null degrades to false without throwing');
-    assert.equal(isHiddenJsonlBranchEntry('not-an-object'), false, 'a non-object degrades to false without throwing');
-});
-test('Major 2 fix — exportToJsonl (via the broker export path) strips display:false custom messages, re-chains a valid linear branch', async () => {
-    const cwd = mkdtempSync(join(tmpdir(), 'crtr-m2-jsonl-'));
-    try {
-        const { session } = await buildBrokerSession(realEngine, cfg(cwd, { extensionPaths: [] }));
-        try {
-            // No deliverAs + not streaming ⇒ sendCustomMessage's synchronous
-            // "append directly to persisted state" branch (a type:'custom_message'
-            // entry) — no model/auth/network needed.
-            await session.sendCustomMessage({ customType: 'crtr-memory-refs', content: 'hidden guidance', display: false });
-            await session.sendCustomMessage({ customType: 'some-visible-thing', content: 'visible content', display: true });
-            const outPath = join(cwd, 'export-test.jsonl');
-            const resolved = session.exportToJsonl(outPath);
-            stripHiddenEntriesFromJsonlExport(resolved);
-            const lines = readFileSync(resolved, 'utf8').split('\n').filter((l) => l !== '');
-            const header = JSON.parse(lines[0]);
-            assert.equal(header.type, 'session', 'header line (line 1) is untouched');
-            const entries = lines.slice(1).map((l) => JSON.parse(l));
-            assert.ok(entries.every((e) => e.customType !== 'crtr-memory-refs'), 'the hidden guidance entry is stripped from the exported JSONL bytes');
-            assert.ok(entries.some((e) => e.customType === 'some-visible-thing'), 'a visible custom entry survives the export');
-            // Linear-branch invariant re-established around the stripped entry: the
-            // first surviving entry's parentId equals the LAST entry BEFORE it that
-            // survived (here, whatever preceded the hidden entry — unaffected since
-            // it comes first among our two custom entries), and each subsequent kept
-            // entry's parentId equals the prior kept entry's id.
-            let prevId = null;
-            for (const e of entries) {
-                assert.equal(e.parentId, prevId, 'parentId re-chains around the stripped entry, keeping a single valid linear branch');
-                prevId = e.id;
-            }
-        }
-        finally {
-            session.dispose();
-        }
-    }
-    finally {
-        rmSync(cwd, { recursive: true, force: true });
-    }
-});
-// Review fix (Major 6, broker/protocol half) — the `list_memory_refs` read-op
-// publishes `engineLeadingCommandNames` as metadata SEPARATE from `refs`
-// (RefMeta rows), exactly matching `isLeadingEngineCommand`'s three sources,
-// so viewers can combine it with their own locally-consumed commands.
-test('Major 6 (broker half) — engineLeadingCommandTokens degrades to empty per-source without throwing, and never touches refs/RefMeta shape', () => {
-    assert.deepEqual(engineLeadingCommandTokens({}), [], 'a bare session with no accessors at all degrades to an empty enumeration');
-    const throwingExtButRealTemplate = {
-        extensionRunner: {
-            getRegisteredCommands: () => {
-                throw new Error('boom: no live extensionRunner');
-            },
-        },
-        promptTemplates: [{ name: 'mytemplate' }],
-    };
-    assert.deepEqual(engineLeadingCommandTokens(throwingExtButRealTemplate), ['mytemplate'], 'a throwing extensionRunner source degrades to none for ITSELF but does not abort the other independent sources');
-});
-test('Major 6 (broker half) — engineLeadingCommandTokens against a REAL session enumerates the real registered extension command', async () => {
-    const cwd = mkdtempSync(join(tmpdir(), 'crtr-m6-cmd-'));
-    try {
-        const { session } = await buildBrokerSession(realEngine, cfg(cwd, { extensionPaths: [C3_EXT, C5_EXT], model: 'c3prov/c3model' }));
-        try {
-            const tokens = engineLeadingCommandTokens(session);
-            assert.ok(tokens.includes('devcmd'), 'the real registered extension command name is present in the enumeration');
-            assert.equal(isLeadingEngineCommand('/devcmd', session), true, 'cross-check: the enumerated token independently round-trips through isLeadingEngineCommand against the SAME real session');
-        }
-        finally {
-            session.dispose();
-        }
-    }
-    finally {
-        rmSync(cwd, { recursive: true, force: true });
-    }
-});