@north-light/crouter 0.3.154

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

@@ -0,0 +1,732 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/broker-sdk-wiring.test.ts
+//
+// 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 { 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, isLeadingEngineCommand, chooseGuidanceDeliveryMode, promptWithNextTurnGuidance, isHiddenJsonlBranchEntry, stripHiddenEntriesFromJsonlExport, engineLeadingCommandTokens, } from '../runtime/broker.js';
+import { readManagedProviderRotationPolicy } from '../runtime/managed-provider-cooling.js';
+import { CANVAS_EXTENSIONS } from '../runtime/launch.js';
+import { buildRefInventory } from '../memory/inline-ref-inventory.js';
+import { buildGuidance } from '../memory/inline-ref-guidance.js';
+import { resetScopeCache } from '../scope.js';
+import { clearSessionCache } from '../substrate/session-cache.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 = 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');
+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, { 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, { 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 script = `
+    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 { writeSubscriptionPool, readRotationConfig } = await import(${JSON.stringify(new URL('../subscription-state.ts', import.meta.url).href)});
+    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, preferred: readRotationConfig().preferredModel }));
+    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 — broker launch falls back to a non-managed provider when no managed provider is authenticated', async () => {
+    const cwd = mkdtempSync(join(tmpdir(), 'crtr-c3c-'));
+    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 {
+        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');
+    assert.equal(selected.preferred, undefined);
+});
+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');
+    assert.equal(selected.preferred, undefined);
+});
+// (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)');
+});
+test('broker UI exposes the live provider pin policy to package extensions', () => {
+    let pinned = false;
+    const ctx = makeBrokerUiContext({
+        writable: () => [],
+        forward: () => { },
+        pending: new Map(),
+        broadcast: () => { },
+        providerRotationPolicy: () => pinned
+            ? { allowCrossProviderFallback: false, reason: 'provider-pinned' }
+            : { allowCrossProviderFallback: true },
+    });
+    assert.deepEqual(readManagedProviderRotationPolicy(ctx), { allowCrossProviderFallback: true });
+    pinned = true;
+    assert.deepEqual(readManagedProviderRotationPolicy(ctx), {
+        allowCrossProviderFallback: false,
+        reason: 'provider-pinned',
+    }, 'the same running UI context observes a live set_model pin change');
+});
+// ===========================================================================
+// 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 — inline memory-reference read-op, memoized inventory + reload
+// invalidation, 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 the fast tier does not boot a broker
+// process to drive raw wire frames (that end-to-end plumbing lives in the
+// full/ tier 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 full-tier-covered `list_models` dispatch whose only
+// non-trivial input, `engineLeadingCommandTokens(session)`, is proven below
+// against a real session.
+// ===========================================================================
+test('C5 — isLeadingEngineCommand truth table against structural stubs (pure, no live session)', () => {
+    // Extension command: matches / does not match.
+    const extOnly = { extensionRunner: { getCommand: (name) => (name === 'dev' ? { name: 'dev' } : undefined) } };
+    assert.equal(isLeadingEngineCommand('/dev', extOnly), true, 'registered extension command matches');
+    assert.equal(isLeadingEngineCommand('/dev extra args', extOnly), true, 'space-separated still matches (name up to first space)');
+    assert.equal(isLeadingEngineCommand('/nope', extOnly), false, 'unregistered command name does not match');
+    // Skill: matches / does not match.
+    const skillOnly = { resourceLoader: { getSkills: () => ({ skills: [{ name: 'myskill' }] }) } };
+    assert.equal(isLeadingEngineCommand('/skill:myskill', skillOnly), true, 'registered skill matches');
+    assert.equal(isLeadingEngineCommand('/skill:other', skillOnly), false, 'unregistered skill name does not match');
+    // Template: matches / does not match.
+    const templateOnly = { promptTemplates: [{ name: 'mytemplate' }] };
+    assert.equal(isLeadingEngineCommand('/mytemplate', templateOnly), true, 'registered prompt template matches');
+    assert.equal(isLeadingEngineCommand('/other', templateOnly), false, 'unregistered template name does not match');
+    // Prose with no leading slash never matches any of the three checks.
+    assert.equal(isLeadingEngineCommand('no leading slash here /dev', extOnly), false, 'a leading command check only looks at text start');
+    // An engine missing an accessor entirely degrades to "not a match", never throws.
+    assert.equal(isLeadingEngineCommand('/dev', {}), false, 'a bare {} session (no accessors) degrades to false without throwing');
+    // A throwing accessor for one check must not abort the OTHER independent
+    // checks — here extensionRunner.getCommand throws, but the SAME text still
+    // correctly resolves via promptTemplates.
+    const throwingExtButRealTemplate = {
+        extensionRunner: {
+            getCommand: () => {
+                throw new Error('boom: no live extensionRunner');
+            },
+        },
+        promptTemplates: [{ name: 'mytemplate' }],
+    };
+    assert.equal(isLeadingEngineCommand('/mytemplate', throwingExtButRealTemplate), true, 'a throwing extensionRunner check degrades to false for ITSELF but does not abort the template check');
+});
+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). Those two branches are covered structurally instead, in the
+    // stub-based truth-table test above — same decision logic, same code path,
+    // proven against a plain object shaped like the real accessors.
+    const cwd = mkdtempSync(join(tmpdir(), 'crtr-c5-cmd-'));
+    try {
+        const { session } = await buildBrokerSession(realEngine, cfg(cwd, { extensionPaths: [...brokerExts(), 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('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 — buildRefInventory reflects a new doc only after clearSessionCache (the invalidation contract `case \'reload\'` relies on)', () => {
+    const canvasHome = mkdtempSync(join(tmpdir(), 'crtr-c5-inv-canvas-'));
+    const userHome = mkdtempSync(join(tmpdir(), 'crtr-c5-inv-user-'));
+    const projectBase = mkdtempSync(join(tmpdir(), 'crtr-c5-inv-project-'));
+    const projectRoot = join(projectBase, 'root');
+    const prevCanvasHome = process.env['CRTR_HOME'];
+    const prevUserHome = process.env['HOME'];
+    const prevNodeId = process.env['CRTR_NODE_ID'];
+    const prevCwd = process.cwd();
+    try {
+        mkdirSync(projectRoot, { recursive: true });
+        process.env['CRTR_HOME'] = canvasHome;
+        process.env['HOME'] = userHome;
+        delete process.env['CRTR_NODE_ID'];
+        process.chdir(projectRoot);
+        resetScopeCache();
+        clearSessionCache();
+        const memoryDir = join(projectRoot, '.crouter', 'memory');
+        mkdirSync(memoryDir, { recursive: true });
+        writeFileSync(join(memoryDir, 'crtr-c5-inv-first.md'), '---\nkind: knowledge\n---\nBody.\n');
+        const first = buildRefInventory();
+        assert.ok(first.names.has('crtr-c5-inv-first'), 'the first doc is visible on the first build');
+        // A second doc written after the first inventory build must NOT appear
+        // until the session parse cache is cleared — this is the exact mechanism
+        // broker.ts's `case 'reload'` invalidates by calling `clearSessionCache()`
+        // (and, in broker.ts, also resetting its own `memoizedRefInventory`).
+        writeFileSync(join(memoryDir, 'crtr-c5-inv-second.md'), '---\nkind: knowledge\n---\nBody.\n');
+        const stale = buildRefInventory();
+        assert.ok(!stale.names.has('crtr-c5-inv-second'), 'a doc written after the cache was warmed is NOT yet visible');
+        clearSessionCache();
+        const fresh = buildRefInventory();
+        assert.ok(fresh.names.has('crtr-c5-inv-second'), 'clearSessionCache() makes the new doc visible — the reload contract');
+    }
+    finally {
+        process.chdir(prevCwd);
+        resetScopeCache();
+        clearSessionCache();
+        rmSync(canvasHome, { recursive: true, force: true });
+        rmSync(userHome, { recursive: true, force: true });
+        rmSync(projectBase, { recursive: true, force: true });
+        if (prevCanvasHome === undefined)
+            delete process.env['CRTR_HOME'];
+        else
+            process.env['CRTR_HOME'] = prevCanvasHome;
+        if (prevUserHome === undefined)
+            delete process.env['HOME'];
+        else
+            process.env['HOME'] = prevUserHome;
+        if (prevNodeId === undefined)
+            delete process.env['CRTR_NODE_ID'];
+        else
+            process.env['CRTR_NODE_ID'] = prevNodeId;
+    }
+});
+test('C5 — guidance composition mirrors broker.ts\'s private resolveFrameGuidance: leading-command check first, then buildGuidance', () => {
+    // Mirrors broker.ts's private `resolveFrameGuidance(text)`:
+    //   if (isLeadingEngineCommand(text, session)) return null;
+    //   return buildGuidance(text, getRefInventory().names);
+    // `isLeadingEngineCommand`/`buildGuidance` are each independently covered
+    // above / in C4's own suite (inline-memory-refs.test.ts) — this proves only
+    // the ORDER of composition: a leading match short-circuits before any ref
+    // in the SAME text is ever resolved.
+    const stubSession = { extensionRunner: { getCommand: () => undefined } };
+    const names = new Set(['dev']);
+    assert.equal(isLeadingEngineCommand('/dev /dev', stubSession), false, 'not a registered command against this stub');
+    assert.equal(buildGuidance('/dev /dev', names), [
+        'The human explicitly referenced these memory documents. Before acting on the portion of their message that references each document, run the corresponding command and treat its returned content as authoritative context:',
+        '- crtr memory read dev',
+    ].join('\n'), 'a non-leading-command text with a resolvable ref still produces guidance');
+    assert.equal(buildGuidance('/nope has nothing to do with it', names), null, 'an unresolvable ref alone produces no guidance');
+});
+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 — pre-fix sequence (sendCustomMessage THEN prompt, no cleanup) reproduces the leak this fix removes', async () => {
+    // Negative control: proves the fixture/interception setup above genuinely
+    // exercises the leak window — the OLD sequencing (what driveEngine did
+    // before this fix) strands the guidance under the exact same interception.
+    const cwd = mkdtempSync(join(tmpdir(), 'crtr-m1-repro-'));
+    try {
+        const { session } = await buildBrokerSession(realEngine, cfg(cwd, { extensionPaths: [C5_EXT] }));
+        try {
+            await session.sendCustomMessage({ customType: 'crtr-memory-refs', content: 'guidance', display: false }, { deliverAs: 'nextTurn' });
+            await session.prompt('/devcmd', {});
+            const pending = session._pendingNextTurnMessages;
+            assert.equal(pending.length, 1, 'Major 1 (control): the pre-fix sequence strands exactly the guidance message it pushed');
+        }
+        finally {
+            session.dispose();
+        }
+    }
+    finally {
+        rmSync(cwd, { recursive: true, force: true });
+    }
+});
+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 exactly matches isLeadingEngineCommand\'s sources (round-trip, pure stubs)', () => {
+    const session = {
+        extensionRunner: {
+            getRegisteredCommands: () => [{ invocationName: 'devcmd' }],
+            getCommand: (n) => (n === 'devcmd' ? {} : undefined),
+        },
+        resourceLoader: { getSkills: () => ({ skills: [{ name: 'myskill' }] }) },
+        promptTemplates: [{ name: 'mytemplate' }],
+    };
+    const tokens = engineLeadingCommandTokens(session);
+    assert.deepEqual(new Set(tokens), new Set(['devcmd', 'skill:myskill', 'mytemplate']), 'every one of the three sources is enumerated, in isLeadingEngineCommand\'s own token shape');
+    for (const token of tokens) {
+        assert.equal(isLeadingEngineCommand(`/${token}`, session), true, `emitted token "${token}" round-trips through isLeadingEngineCommand as a leading match`);
+    }
+    assert.equal(isLeadingEngineCommand('/nope', session), false, 'a name NOT in the enumeration correctly does not match');
+});
+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: [...brokerExts(), 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 });
+    }
+});