@north-light/crouter 0.3.154

package/dist/core/__tests__/fixtures/fake-engine.js

@@ -0,0 +1,1210 @@
+// fake-engine.ts — a deterministic in-process stand-in for the pi SDK engine,
+// the SDK analog of fixtures/fake-pi-host.ts.
+//
+// This is NOT an LLM and NOT a mock of the canvas extensions. It occupies the
+// pi SDK's place INSIDE the REAL broker (src/core/runtime/broker.ts): the broker
+// loads it through the `CRTR_BROKER_ENGINE` seam (broker-sdk.ts `loadBrokerEngine`),
+// then drives it exactly as it drives the real `@earendil-works/pi-coding-agent`
+// engine — SessionManager.open/create, createAgentSession, session.bindExtensions,
+// session.subscribe, session.prompt. We load the REAL `-e` canvas extensions (the
+// modules the runtime put in the node's broker-launch.json) and fire REAL
+// lifecycle events under harness control, so the real hooks (canvas-stophook,
+// canvas-inbox-watcher) and the real broker drive real canvas state — across the
+// detached broker process boundary, with NOTHING in the broker mocked.
+//
+// It is run UNDER tsx in the broker process (the harness puts `--import tsx/esm`
+// in the broker's NODE_OPTIONS), so the `.ts` extension paths and this `.ts`
+// module both resolve. By the time the broker calls our SessionManager/
+// createAgentSession, piInvocationToSdkConfig has merged inv.env into
+// process.env, so CRTR_NODE_ID / CRTR_HOME are set — that is how we find the
+// node dir.
+//
+// Proof / control surface — IDENTICAL filenames to fake-pi-host.ts, so the
+// EXISTING harness observers (awaitBoot, awaitWake, eventCount, bootCount,
+// injected) work for broker nodes UNCHANGED:
+//   <nodeDir>/fake-pi.boot.json     — argv + env + loaded exts (latest boot)
+//   <nodeDir>/fake-pi.boots.jsonl    — append-only, one line per boot (broker pid)
+//   <nodeDir>/fake-pi.events.jsonl   — append-only, one line per fired event
+//   <nodeDir>/fake-pi.injected.jsonl — every sendUserMessage (inbox-watcher wake)
+//   <nodeDir>/fake-pi.error          — any boot/import failure
+//   <nodeDir>/fake-pi.cmd            — harness writes ONE JSON command (turn|stop|auto_retry|dialog)
+//   <nodeDir>/fake-pi.dialog.jsonl   — one line per resolved unattended dialog (§5.4)
+import { writeFileSync, readFileSync, existsSync, mkdirSync, appendFileSync, unlinkSync, } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { DefaultResourceLoader, getAgentDir } from '@earendil-works/pi-coding-agent';
+import { MANAGED_PROVIDER_COOLING_DIAGNOSTIC } from '../../runtime/managed-provider-cooling.js';
+/** Test seams for prompt-scoped failures before session_start. The one-shot
+ *  variant records its first failure per node so the next cycling retry can
+ *  reach boot confirmation. */
+export const FAIL_BEFORE_SESSION_START = '__FAIL_BEFORE_SESSION_START__';
+export const FAIL_BEFORE_SESSION_START_ONCE = '__FAIL_BEFORE_SESSION_START_ONCE__';
+/** Text marker that makes `session.prompt()` REJECT outright (no agent_start,
+ *  no turn) — the shape a broker whose model resolved but whose provider has
+ *  no installed credential produces ("No API key found for <provider>"). */
+export const REJECT_PROMPT_CALL = '__REJECT_PROMPT_CALL__';
+// ---------------------------------------------------------------------------
+// node dir / proof helpers
+// ---------------------------------------------------------------------------
+function nodeDirFromEnv() {
+    const home = (process.env['CRTR_HOME'] ?? '').trim();
+    const nodeId = (process.env['CRTR_NODE_ID'] ?? '').trim();
+    if (home === '' || nodeId === '') {
+        throw new Error('[fake-engine] CRTR_HOME / CRTR_NODE_ID missing in env');
+    }
+    const dir = join(home, 'nodes', nodeId);
+    mkdirSync(dir, { recursive: true });
+    return dir;
+}
+function recordError(dir, msg) {
+    try {
+        appendFileSync(join(dir, 'fake-pi.error'), msg + '\n');
+    }
+    catch {
+        /* best effort */
+    }
+    try {
+        process.stderr.write('[fake-engine] ' + msg + '\n');
+    }
+    catch {
+        /* ignore */
+    }
+}
+// ---------------------------------------------------------------------------
+// SessionManager — the broker calls .open(path) (resume) or .create(cwd) (fresh)
+// and hands the result to createAgentSession. sessionId/sessionFile round-trip
+// through it, so a resume (`--session <pi_session_file>`) re-opens the SAME
+// .jsonl the fresh start created — the load-bearing identity for revive.
+// ---------------------------------------------------------------------------
+export class SessionManager {
+    sessionId;
+    sessionFile;
+    resumed;
+    constructor(sessionId, sessionFile, resumed) {
+        this.sessionId = sessionId;
+        this.sessionFile = sessionFile;
+        this.resumed = resumed;
+    }
+    /** Fresh start: a brand-new session whose .jsonl lives under the node dir
+     *  (created empty if missing, like fake-pi-host). */
+    static create(_cwd) {
+        const dir = nodeDirFromEnv();
+        const sessionFile = join(dir, 'fake-session.jsonl');
+        if (!existsSync(sessionFile))
+            writeFileSync(sessionFile, '');
+        return new SessionManager(`fake-sess-${randomUUID()}`, sessionFile, false);
+    }
+    /** Spawn-time fork: create the fork's distinct fake session. The focused
+     *  broker tests do not replay source history, but they must reach the same
+     *  post-fork model/session construction path as the real engine. */
+    static forkFrom(_source, cwd) {
+        return SessionManager.create(cwd);
+    }
+    /** Resume: round-trip the .jsonl PATH the revive passed via `--session`. */
+    static open(path) {
+        return new SessionManager(`fake-sess-resume-${randomUUID()}`, path, true);
+    }
+    getSessionId() {
+        return this.sessionId;
+    }
+    getSessionFile() {
+        return this.sessionFile;
+    }
+    /** The directory containing the session file — the real SessionManager's
+     *  getSessionDir(). The broker prewarms the session-list cache with it at boot
+     *  (broker.ts runBroker), so the fixture must expose it or every broker boot
+     *  crashes before it binds view.sock. */
+    getSessionDir() {
+        return dirname(this.sessionFile);
+    }
+    leafId = null;
+    /** Cycling support (crtr-cycle marker) — mirrors the real SDK's getLeafId/
+     *  resetLeaf/appendCustomEntry just enough that `buildBrokerSession`'s cycling
+     *  branch (broker.ts) doesn't throw. The fake has no real cross-boot tree at
+     *  this point (FakeSession builds a fresh SessionTree every boot regardless),
+     *  so these are recording stubs, not a faithful branch model —
+     *  cycleAwareMessages already degrades to single-cycle passthrough for a
+     *  session manager without getEntries/getBranch (never implemented on the
+     *  fake), so multi-cycle REPLAY is out of scope for the fixture; only "does
+     *  not crash" is in scope. */
+    getLeafId() {
+        return this.leafId;
+    }
+    resetLeaf() {
+        this.leafId = null;
+    }
+    appendCustomEntry(_customType, _data) {
+        this.leafId = `fake-cycle-${randomUUID().slice(0, 8)}`;
+        return this.leafId;
+    }
+}
+// ---------------------------------------------------------------------------
+// AgentSessionEvent stream synthesis (T8 / G1, G3, G4, G8). The fake emits a
+// REALISTIC streaming assistant turn through session.subscribe — the SAME channel
+// the real pi engine feeds the broker's fan-out — so the frames a `crtr surface attach`
+// client receives are byte-for-byte real AgentSessionEvents. The EMITTED event
+// shapes are typed against the real `AgentSessionEvent` union from pi (whose full
+// 17 variants are message_start/update/end, tool_execution_start/update/end,
+// agent_start/end, turn_start/end, queue_update, compaction_start/end, auto_retry_
+// start/end, session_info_changed, thinking_level_changed) — emit() takes that
+// union, so a drift in the shape of any variant emitTurn() constructs (the
+// streaming subset: the message_*, tool_execution_*, agent/turn start+end events)
+// fails the build, not a test.
+// ---------------------------------------------------------------------------
+/** A minimal but fully-typed AssistantMessage. `pad` bytes of filler text let a
+ *  test size a single frame to multiple MiB (G8 backpressure flood). */
+function assistantMessage(text, pad = 0) {
+    return {
+        role: 'assistant',
+        content: [{ type: 'text', text: pad > 0 ? `${text} ${'x'.repeat(pad)}` : text }],
+        api: 'anthropic-messages',
+        provider: 'anthropic',
+        model: 'fake-sonnet',
+        usage: {
+            input: 10,
+            output: 5,
+            cacheRead: 0,
+            cacheWrite: 0,
+            totalTokens: 15,
+            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+        },
+        stopReason: 'stop',
+        timestamp: Date.now(),
+    };
+}
+/** A streaming text-delta event (the `assistantMessageEvent` carried by a
+ *  message_update). Kept small (the big payload rides in message_update.message). */
+function textDelta(partial, delta) {
+    return { type: 'text_delta', contentIndex: 0, delta, partial };
+}
+class SessionTree {
+    entries = new Map();
+    children = new Map();
+    leafId = null;
+    append(message) {
+        const entry = {
+            type: 'message',
+            id: randomUUID().slice(0, 8),
+            parentId: this.leafId,
+            timestamp: new Date().toISOString(),
+            message,
+        };
+        this.entries.set(entry.id, entry);
+        const siblings = this.children.get(entry.parentId) ?? [];
+        siblings.push(entry.id);
+        this.children.set(entry.parentId, siblings);
+        this.leafId = entry.id;
+        return entry;
+    }
+    /** Synthetic in-place rewind for the broker navigate_tree regression lock:
+     *  drop the last turn (assistant leaf + its user parent) by re-anchoring the
+     *  leaf past it. The abandoned tail is left in the map (not deleted), mirroring
+     *  a real branch switch — only the ACTIVE branch shortens. */
+    rewindOneTurn() {
+        const leaf = this.leafId === null ? undefined : this.entries.get(this.leafId);
+        if (leaf === undefined)
+            return;
+        const user = leaf.parentId === null ? undefined : this.entries.get(leaf.parentId);
+        this.leafId = user !== undefined ? user.parentId : leaf.parentId;
+    }
+    getLeafId() {
+        return this.leafId;
+    }
+    getEntry(id) {
+        return this.entries.get(id);
+    }
+    getTree() {
+        return (this.children.get(null) ?? []).map((id) => this.node(id)).filter((node) => node !== null);
+    }
+    getUserMessagesForForking() {
+        return [...this.entries.values()]
+            .filter((entry) => entry.message.role === 'user')
+            .map((entry) => ({ entryId: entry.id, text: this.textOf(entry.message), timestamp: entry.timestamp }));
+    }
+    buildSessionContext() {
+        return { messages: this.branchMessages(), thinkingLevel: 'off', model: null };
+    }
+    branchMessages() {
+        const ids = [];
+        let cur = this.leafId;
+        while (cur !== null) {
+            const entry = this.entries.get(cur);
+            if (entry === undefined)
+                break;
+            ids.push(cur);
+            cur = entry.parentId;
+        }
+        ids.reverse();
+        return ids.map((id) => this.entries.get(id)?.message).filter((m) => m !== undefined);
+    }
+    node(id) {
+        const entry = this.entries.get(id);
+        if (entry === undefined)
+            return null;
+        return {
+            entry,
+            children: (this.children.get(id) ?? []).map((child) => this.node(child)).filter((node) => node !== null),
+        };
+    }
+    textOf(message) {
+        const content = Array.isArray(message.content) ? message.content : [];
+        for (const part of content) {
+            if (typeof part?.text === 'string' && part.text !== '')
+                return part.text;
+        }
+        return '';
+    }
+}
+class FakeSession {
+    sm;
+    loader;
+    dir;
+    tree = new SessionTree();
+    promptFailuresRemaining;
+    extensions = [];
+    injected = [];
+    uiContext;
+    shutdownHandler;
+    streaming = false;
+    disposed = false;
+    eventSeq = 0;
+    timer;
+    /** Full-tier graceful-teardown seam: a real active turn that only settles
+     * after abort(), so the broker's bounded abort wait is observable. */
+    heldTurn;
+    // The broker's fan-out subscribers (broker.ts `session.subscribe(...)`) and the
+    // accumulating message history the catch-up snapshot serializes (G3).
+    listeners = new Set();
+    /** Idle watcher sends received while bindExtensions is still running. They
+     * start naturally as soon as broker.ts subscribes, without a retry loop that
+     * could keep a failed broker process alive forever. */
+    pendingIdlePrompts = [];
+    messageLog = [];
+    turnEndLeafId = null;
+    /** Testability seam: `hasPendingMessages()` reported to `agent_settled`
+     *  handlers. Real pi's `AgentSession.hasPendingMessages()` reflects its
+     *  steer+followUp queue; this fake has no such queue, so a test that needs to
+     *  reproduce a settle observed WITH pending sends (the real incident this
+     *  fixture otherwise cannot exercise) sets CRTR_FAKE_ENGINE_PENDING_AT_SETTLE=1
+     *  before spawning the broker. Unset → false, matching the fixture's actual
+     *  (queueless) state. */
+    pendingAtSettle = process.env['CRTR_FAKE_ENGINE_PENDING_AT_SETTLE'] === '1';
+    // The construction-time services.modelRuntime (broker-sdk services path). For
+    // a model-less (tier-3) boot this is broker.ts's SELF-HEALING masking PROXY
+    // (modelLessRegistry): getAvailable()/getModel() answer empty/undefined while
+    // masked, then broker.ts reveal()s the SAME proxy the instant construction
+    // returns. Exposing it as `session.modelRuntime` (real-SDK parity — broker.ts
+    // registryOf(session) builds its facade over it) lets the broker's
+    // list_models handler observe the 0a self-heal — a post-/login list_models
+    // reports the now-available model iff reveal() actually ran.
+    modelRt;
+    constructor(sm, loader, model, modelRuntime) {
+        this.sm = sm;
+        this.loader = loader;
+        this.modelRt = modelRuntime;
+        this.dir = nodeDirFromEnv();
+        // Mirror the real pi SDK: a model-less construction (`model === undefined`)
+        // does NOT leave `session.model` undefined — Agent.createMutableAgentState()
+        // falls back to a hardcoded unknown-stub. Representing that here is what
+        // makes the full/ tests exercise the broker's real sessionHasNoModel()/
+        // isUnknownModel() guard path (broker.ts) rather than the `=== undefined`
+        // shortcut that never happens against the real engine.
+        this.currentModel = model ?? UNKNOWN_MODEL_STUB;
+        this.recordModel();
+        const configured = Number(process.env['CRTR_FAKE_ENGINE_PROMPT_FAILS'] ?? '0');
+        this.promptFailuresRemaining = Number.isFinite(configured) && configured > 0 ? Math.floor(configured) : 0;
+        this.syncTreeSnapshot();
+    }
+    // --- broker-read getters. buildSnapshot (on a client hello) reads messages/
+    //     stats/model: T8 clients attach and assert on welcome.snapshot, so messages
+    //     returns the accrued history; stats/model stay cheap stubs. ---------------
+    get messages() {
+        return this.tree.buildSessionContext().messages;
+    }
+    // The broker's catch-up snapshot reconstructs history from the persisted
+    // session tree (sessionManager.buildSessionContext) — the single source of
+    // truth, since `session.messages` can be sliced by pi's retry/overflow/
+    // compaction recovery. Mirror that surface so the fake's snapshot still serves
+    // the accrued history (G2/G3). The fake's persisted analog is the active branch.
+    get sessionManager() {
+        return {
+            buildSessionContext: () => this.tree.buildSessionContext(),
+            getLeafId: () => this.tree.getLeafId(),
+            getEntry: (id) => this.tree.getEntry(id),
+            getTree: () => this.tree.getTree(),
+            getUserMessagesForForking: () => this.tree.getUserMessagesForForking(),
+            getSessionId: () => this.sm.getSessionId(),
+            getSessionFile: () => this.sm.getSessionFile(),
+            getSessionDir: () => this.sm.getSessionDir(),
+        };
+    }
+    get sessionId() {
+        return this.sm.getSessionId();
+    }
+    get sessionFile() {
+        return this.sm.getSessionFile();
+    }
+    get model() {
+        return this.currentModel;
+    }
+    // set_model regression surface: the broker resolves the spec via the services
+    // registry stub below, calls setModel, then broadcasts `model_changed` off
+    // this getter — store whatever it hands us.
+    currentModel;
+    currentThinkingLevel;
+    get thinkingLevel() {
+        return this.currentThinkingLevel;
+    }
+    setThinkingLevel(level) {
+        this.currentThinkingLevel = level;
+    }
+    recordModel() {
+        // Treat the unknown-stub as "no model" on the recorded surface (parity with
+        // broker.ts formatModelSpec) so a zero-auth boot's model reads `null`, not
+        // a bogus `unknown/unknown`.
+        const m = this.currentModel;
+        const record = m === undefined || isUnknownModelStub(m) ? null : m;
+        writeFileSync(join(this.dir, 'fake-pi.model.json'), JSON.stringify(record));
+    }
+    setModel(model) {
+        this.currentModel = model;
+        this.recordModel();
+        return Promise.resolve();
+    }
+    // --- list_models / cycle_model read surface (real-SDK parity) ----------------
+    /** The broker's read-op picker data (buildListModelsData → registryOf(session))
+     *  reads this. For a model-less boot it is the self-healing mask proxy — see
+     *  modelRt. */
+    get modelRuntime() {
+        // Inert empty runtime if a construction ever omitted it — no production
+        // path does (createAgentSessionFromServices always threads it), so this only
+        // guards list_models against throwing inside the broker's data builder.
+        return this.modelRt ?? {
+            getModel: () => undefined,
+            getAvailableSnapshot: () => [],
+            getAvailable: async () => [],
+            getModels: () => [],
+            hasConfiguredAuth: () => false,
+            getError: () => undefined,
+            refresh: async () => { },
+        };
+    }
+    /** The `--models` scoped cycle set — none in these fixtures. */
+    get scopedModels() {
+        return [];
+    }
+    /** The slice of SettingsManager the list_models data builder touches. */
+    get settingsManager() {
+        return { getEnabledModels: () => null };
+    }
+    get isStreaming() {
+        return this.streaming;
+    }
+    getSessionStats() {
+        return { messages: 0, tokens: 0 };
+    }
+    syncTreeSnapshot() {
+        try {
+            writeFileSync(join(this.dir, 'fake-pi.tree.json'), JSON.stringify({
+                leafId: this.tree.getLeafId(),
+                activeBranch: this.tree.buildSessionContext().messages,
+                tree: this.tree.getTree(),
+                userMessagesForForking: this.tree.getUserMessagesForForking(),
+            }, null, 2));
+        }
+        catch {
+            /* best effort */
+        }
+    }
+    // --- naming is cosmetic (broker calls it in a try/catch) ---------------------
+    setSessionName(_name) {
+        /* no-op recording stub */
+    }
+    // --- controller-drive stubs (no controller connects in these tests) ----------
+    prompt(text, _options) {
+        // Rejection seam: the engine refuses the call itself (pi's no-provider-
+        // credential shape) — the promise rejects and NO lifecycle event fires.
+        if (text.includes(REJECT_PROMPT_CALL)) {
+            return Promise.reject(new Error('No API key found for anthropic'));
+        }
+        // The broker calls this for the controller-less retry path. Emit the turn
+        // on the broker's subscribe channel and also run the real extension hooks so
+        // the canvas stophook records the fault marker and the broker can schedule
+        // the next retry.
+        const fail = this.promptFailuresRemaining > 0;
+        if (fail)
+            this.promptFailuresRemaining--;
+        return this.emitTurn(text, { fail, runHooks: true });
+    }
+    steer(_text) {
+        return Promise.resolve();
+    }
+    followUp(_text) {
+        return Promise.resolve();
+    }
+    /** In-memory recording only — no proof file, matching the offline in-process
+     *  contract broker-sdk-wiring.test.ts's REAL-SDK tests already use. Purely
+     *  defensive: broker.ts's driveEngine now calls `session.sendCustomMessage`
+     *  on ANY frame whose inline memory-reference guidance resolves, so a fake-
+     *  engine-backed lifecycle test whose fixture prompt text happens to contain
+     *  a resolvable `/name` token must not crash on a missing method. */
+    customMessages = [];
+    sendCustomMessage(message, options) {
+        this.customMessages.push({
+            customType: message.customType,
+            content: message.content,
+            display: message.display,
+            deliverAs: options?.deliverAs,
+        });
+        return Promise.resolve();
+    }
+    abort() {
+        const held = this.heldTurn;
+        if (held === undefined)
+            return Promise.resolve();
+        held.release();
+        return held.settled;
+    }
+    /** In-place tree rewind (broker `navigate_tree`). Mirrors the real SDK's
+     *  contract: the session file is unchanged, the live history is truncated,
+     *  and the navigated-to user message's text comes back as `editorText`. The
+     *  fake's "rewind" re-anchors the active branch without deleting the abandoned
+     *  tail so the welcome snapshot can prove the one-nudge property. */
+    async navigateTree(targetId, _options) {
+        // The broker regression this locks is pure frame plumbing (navigate_tree →
+        // reWelcomeAll + ack.detail), not real tree traversal, so the viewer sends a
+        // SYNTHETIC targetId. Rewind the active branch by one full turn (the last
+        // user+assistant pair) so the re-welcome serves an observably shorter
+        // transcript, and echo the target as editorText (pi parity: the navigator
+        // restores the navigated-to user message's text to the editor).
+        const hold = join(this.dir, 'fake-pi.navigate-hold');
+        if (existsSync(hold)) {
+            writeFileSync(join(this.dir, 'fake-pi.navigate-started'), '');
+            await new Promise((resolve) => {
+                const wait = () => {
+                    if (existsSync(join(this.dir, 'fake-pi.navigate-release')))
+                        resolve();
+                    else
+                        setTimeout(wait, 10);
+                };
+                wait();
+            });
+        }
+        this.tree.rewindOneTurn();
+        this.syncTreeSnapshot();
+        return { cancelled: false, editorText: `rewound-to:${targetId}` };
+    }
+    // --- the single engine event stream the broker fans out (broker.ts subscribes
+    //     here and broadcasts each event VERBATIM to every attached viewer) --------
+    subscribe(listener) {
+        const l = listener;
+        this.listeners.add(l);
+        // The loader starts extension timers before broker.ts reaches subscribe().
+        // An idle watcher send in that narrow bind window is held here until the
+        // broker can observe its lifecycle; no polling/retry loop survives a failed
+        // bind with no subscriber.
+        const pending = this.pendingIdlePrompts.splice(0);
+        for (const content of pending)
+            this.startIdlePrompt(content);
+        return () => {
+            this.listeners.delete(l);
+        };
+    }
+    startIdlePrompt(content) {
+        setImmediate(() => {
+            if (this.disposed)
+                return;
+            void this.prompt(content).catch((e) => recordError(this.dir, `inbox prompt: ${String(e)}`));
+        });
+    }
+    /** Fan one typed AgentSessionEvent out to every broker subscriber. A throwing
+     *  listener is recorded, never propagated (mirrors the broker's m7 try/catch). */
+    emit(event) {
+        for (const l of this.listeners) {
+            try {
+                l(event);
+            }
+            catch (e) {
+                recordError(this.dir, `subscribe listener threw: ${String(e)}`);
+            }
+        }
+    }
+    /** Emit a realistic streaming assistant turn on the subscribe channel:
+     *  agent_start → turn_start → message_start → message_update×N →
+     *  tool_execution_start/update/end → message_end → turn_end → agent_end. Drives
+     *  G1 (controller prompt relay), G3 (produce-while-detached, accrues messageLog),
+     *  and G8 (a fast event stream — `updates`/`padBytes` size the flood that sheds a
+     *  stalled viewer at the broker HWM). A per-update setImmediate yield lets a
+     *  fast viewer drain between frames so only the stalled one trips the HWM. */
+    async emitTurn(text, opts = {}) {
+        if (this.disposed)
+            return;
+        const updates = opts.updates ?? 3;
+        const pad = opts.padBytes ?? 0;
+        const withTool = opts.tool ?? true;
+        const fail = opts.fail === true;
+        const small = assistantMessage(text);
+        // A normal turn yields with setImmediate (fast). A sized flood (G8, pad>0) is
+        // PACED with a small real delay so a fast (reading) viewer always drains each
+        // frame and stays under the HWM, while a stalled (non-reading) viewer's backlog
+        // still climbs monotonically past the 32 MiB byte cap and is shed. Without the
+        // pace the burst outruns the reader's event loop and sheds the fast viewer too.
+        const yieldTick = () => pad > 0 ? new Promise((r) => setTimeout(r, 3)) : new Promise((r) => setImmediate(r));
+        this.streaming = true;
+        if (opts.runHooks === true) {
+            await this.fire('agent_start', {}, this.buildCtx());
+        }
+        this.emit({ type: 'agent_start' });
+        this.emit({ type: 'turn_start' });
+        this.emit({ type: 'message_start', message: small });
+        if (process.env['PI_FAKE_ENGINE_HOLD_TURN'] === '1') {
+            let release;
+            let resolveSettled;
+            const settled = new Promise((resolve) => { resolveSettled = resolve; });
+            const releaseGate = new Promise((resolve) => { release = resolve; });
+            this.heldTurn = { release, settled, resolveSettled };
+            await releaseGate;
+        }
+        // F2 (message_update coalescing): the broker now coalesces message_update
+        // relays (latest-wins, ~75 ms window), so a padded flood riding message_update
+        // can no longer climb a stalled viewer's backlog — the coalescer would shed
+        // the flood before the HWM does. A sized flood (pad>0, G8) therefore rides
+        // tool_execution_update frames, which the broker relays VERBATIM (only
+        // message_update is coalesced — tool output streams remain the realistic
+        // unbounded-backlog vector M1 guards against). The flood gets its own
+        // tool_execution_start so the frame sequence stays well-formed.
+        const floodToolCallId = pad > 0 ? `flood-${++this.eventSeq}` : undefined;
+        if (floodToolCallId !== undefined) {
+            this.emit({
+                type: 'tool_execution_start',
+                toolCallId: floodToolCallId,
+                toolName: 'read',
+                args: { path: 'flood.txt' },
+            });
+        }
+        for (let i = 0; i < updates; i++) {
+            if (this.disposed)
+                return;
+            this.emit({
+                type: 'message_update',
+                message: assistantMessage(`${text} [${i + 1}/${updates}]`),
+                assistantMessageEvent: textDelta(small, `chunk ${i + 1}`),
+            });
+            if (floodToolCallId !== undefined) {
+                // The big payload (G8) rides the partialResult; ~padBytes per frame.
+                this.emit({
+                    type: 'tool_execution_update',
+                    toolCallId: floodToolCallId,
+                    toolName: 'read',
+                    args: { path: 'flood.txt' },
+                    partialResult: { chunk: 'x'.repeat(pad) },
+                });
+            }
+            await yieldTick();
+        }
+        if (floodToolCallId !== undefined) {
+            this.emit({
+                type: 'tool_execution_end',
+                toolCallId: floodToolCallId,
+                toolName: 'read',
+                result: { ok: true },
+                isError: false,
+            });
+        }
+        if (withTool) {
+            const toolCallId = `call-${++this.eventSeq}`;
+            this.emit({ type: 'tool_execution_start', toolCallId, toolName: 'read', args: { path: 'README.md' } });
+            this.emit({
+                type: 'tool_execution_update',
+                toolCallId,
+                toolName: 'read',
+                args: { path: 'README.md' },
+                partialResult: { bytes: 42 },
+            });
+            this.emit({ type: 'tool_execution_end', toolCallId, toolName: 'read', result: { ok: true }, isError: false });
+        }
+        if (this.disposed)
+            return;
+        const userMsg = {
+            role: 'user',
+            content: [{ type: 'text', text }],
+            timestamp: Date.now(),
+        };
+        this.tree.append(userMsg);
+        this.syncTreeSnapshot();
+        const finalMsg = fail
+            ? { ...assistantMessage(text), stopReason: 'error', errorMessage: 'Connection error.' }
+            : assistantMessage(text);
+        this.emit({ type: 'message_end', message: finalMsg });
+        this.emit({ type: 'turn_end', message: finalMsg, toolResults: [] });
+        this.messageLog.push(finalMsg);
+        const anchorBeforeFinal = this.tree.getLeafId();
+        this.turnEndLeafId = anchorBeforeFinal;
+        this.tree.append(finalMsg);
+        this.syncTreeSnapshot();
+        if (opts.runHooks === true) {
+            const hookCtx = this.buildCtx();
+            await this.fire('turn_end', { message: finalMsg, toolResults: [] }, hookCtx);
+            const hookMessages = fail
+                ? [...this.tree.buildSessionContext().messages, finalMsg]
+                : this.tree.buildSessionContext().messages.slice();
+            await this.fire('agent_end', { messages: hookMessages, willRetry: false }, hookCtx);
+            // Pi settles extensions before it notifies session subscribers. This order
+            // is load-bearing for the broker's cooperative shutdown: the watcher
+            // commits its inbox cursor at settle, then the broker may exit.
+            await this.fire('agent_settled', { type: 'agent_settled' }, hookCtx);
+        }
+        this.turnEndLeafId = null;
+        // Pi exposes agent_end while the run is still active; agent_settled is the
+        // first subscriber event after isStreaming clears. Keep that production
+        // ordering so broker retry tests cannot green-light an impossible arm point.
+        const agentEndMessages = fail
+            ? [...this.tree.buildSessionContext().messages, finalMsg]
+            : this.tree.buildSessionContext().messages.slice();
+        this.emit({ type: 'agent_end', messages: agentEndMessages, willRetry: false });
+        this.streaming = false;
+        this.emit({ type: 'agent_settled' });
+        const held = this.heldTurn;
+        this.heldTurn = undefined;
+        held?.resolveSettled();
+    }
+    dispose() {
+        this.disposed = true;
+        if (this.timer !== undefined)
+            clearInterval(this.timer);
+    }
+    // --- bindExtensions: drive the loader's ALREADY-loaded extensions. The REAL
+    //     DefaultResourceLoader.reload() (broker.ts, BEFORE createAgentSession) has
+    //     already imported the `-e` canvas extensions via jiti and called each
+    //     default(pi) against the SDK's `notInitialized` runtime — registering their
+    //     handlers but leaving every action method (pi.sendUserMessage, …) a stub
+    //     that THROWS during load. We must NOT re-import them: a native import() is a
+    //     jiti-independent SECOND module instance, so the inbox-watcher's module-
+    //     level timer would run TWICE — and the reload() copy (bound to the throwing
+    //     runtime) wins the race for the shared on-disk inbox cursor, consuming the
+    //     entry and never delivering. Instead we replicate the minimal slice of
+    //     agent-session's bindCore: swap the shared runtime's action methods IN PLACE
+    //     so the real handlers' pi.sendUserMessage delivers into our proof files,
+    //     then emit session_start into their handler maps so the REAL canvas-stophook
+    //     records pi_session_id/file + recordPid(process.pid=broker pid). The broker's
+    //     shutdownHandler is wired into ctx.shutdown so the stophook's done/idle-
+    //     release/refresh branches exit the broker. -------------------------------
+    async bindExtensions(opts) {
+        this.uiContext = opts.uiContext;
+        this.shutdownHandler = opts.shutdownHandler;
+        const { argv, extPaths, label, prompt } = readLaunch(this.dir);
+        // SessionManager.open backs both strict resume and in-place cycling. The
+        // latter roots a fresh context, so report and fault-inject it as non-resuming.
+        const resuming = this.sm.resumed && !argv.includes('--crtr-new-cycle');
+        // M-1 regression seam: simulate a broker that throws BEFORE session_start
+        // (no pid, no session ever recorded). Only a fresh start carries the kickoff
+        // prompt; the throw propagates out of bindExtensions → runBroker rejects →
+        // broker-cli's fatal catch logs to job/broker.log + exit(1).
+        if (!resuming && (prompt ?? '').includes(FAIL_BEFORE_SESSION_START)) {
+            throw new Error('[fake-engine] simulated pre-session_start boot failure');
+        }
+        if (!resuming && (prompt ?? '').includes(FAIL_BEFORE_SESSION_START_ONCE)) {
+            const marker = join(this.dir, 'yield-retry.once-failed');
+            if (!existsSync(marker)) {
+                writeFileSync(marker, '1');
+                throw new Error('[fake-engine] simulated one-shot pre-session_start boot failure');
+            }
+        }
+        // bindCore (minimal): adopt the loader's extensions + their shared runtime, and
+        // replace the throwing notInitialized action methods with working ones. The
+        // handlers themselves stay the REAL ones the SDK registered during reload().
+        const loaded = [];
+        const failedExt = [];
+        try {
+            const result = this.loader?.getExtensions();
+            this.extensions = result?.extensions ?? [];
+            for (const e of this.extensions)
+                loaded.push(e.path);
+            for (const err of result?.errors ?? []) {
+                failedExt.push(String(err?.error ?? err));
+            }
+            const rt = result?.runtime;
+            if (rt !== undefined) {
+                rt.assertActive = () => { };
+                rt.sendUserMessage = (content, options) => {
+                    this.recordInjected({ content, deliverAs: options?.deliverAs });
+                    // Pi's unqualified idle send starts a prompt. Drive that actual fake
+                    // session lifecycle so a watcher wake reaches agent_end/settled and the
+                    // broker subscriber naturally, rather than asking a test to dispatch a
+                    // separate synthetic turn. Steered/follow-up sends remain queued proof
+                    // records: they belong to an already-running turn in this focused fake.
+                    if (options?.deliverAs === undefined) {
+                        // The loader's watcher timer can tick while bindExtensions is still
+                        // awaiting session_start, before broker.ts installs subscribe(). Hold
+                        // that send until subscription rather than completing an unobserved
+                        // turn or spinning an event-loop retry if bind fails.
+                        if (this.listeners.size === 0)
+                            this.pendingIdlePrompts.push(content);
+                        else
+                            this.startIdlePrompt(content);
+                    }
+                };
+                rt.sendMessage = (message, options) => this.recordInjected({ content: JSON.stringify(message), deliverAs: options?.deliverAs });
+                rt.setSessionName = () => { };
+            }
+            else {
+                recordError(this.dir, 'bindExtensions: resourceLoader.getExtensions() returned no runtime');
+            }
+        }
+        catch (e) {
+            recordError(this.dir, `bindExtensions getExtensions/bindCore failed: ${String(e)}`);
+        }
+        const ctx = this.buildCtx();
+        // session_start: the real boot-confirm hook captures session id/file + the
+        // broker's pid (recordPid(process.pid)) and clears any pending refresh.
+        await this.fire('session_start', { reason: resuming ? 'resume' : 'startup' }, ctx);
+        // The boot proof the harness asserts on (same shape as fake-pi-host's boot).
+        const env = process.env;
+        const boot = {
+            pid: process.pid, // the broker pid (recorded as pi_pid by the stophook)
+            nodeId: (env['CRTR_NODE_ID'] ?? '').trim(),
+            home: (env['CRTR_HOME'] ?? '').trim(),
+            rawArgv: argv,
+            extPaths,
+            loaded,
+            failedExt,
+            sessionId: this.sm.getSessionId(),
+            sessionFile: this.sm.getSessionFile(),
+            resuming,
+            label: label ?? null,
+            prompt: prompt ?? null,
+            env: {
+                CRTR_NODE_ID: env['CRTR_NODE_ID'] ?? null,
+                CRTR_KIND: env['CRTR_KIND'] ?? null,
+                CRTR_MODE: env['CRTR_MODE'] ?? null,
+                CRTR_LIFECYCLE: env['CRTR_LIFECYCLE'] ?? null,
+                CRTR_NODE_CWD: env['CRTR_NODE_CWD'] ?? null,
+                CRTR_HOME: env['CRTR_HOME'] ?? null,
+                CRTR_PARENT_NODE_ID: env['CRTR_PARENT_NODE_ID'] ?? null,
+                CRTR_ROOT_SESSION: env['CRTR_ROOT_SESSION'] ?? null,
+                CRTR_SUBTREE: env['CRTR_SUBTREE'] ?? null,
+                CRTR_FRONT_DOOR: env['CRTR_FRONT_DOOR'] ?? null,
+            },
+            injectedDuringBoot: this.injected.slice(),
+        };
+        writeFileSync(join(this.dir, 'fake-pi.boot.json'), JSON.stringify(boot, null, 2));
+        try {
+            appendFileSync(join(this.dir, 'fake-pi.boots.jsonl'), JSON.stringify(boot) + '\n');
+        }
+        catch {
+            /* best effort */
+        }
+        // Control loop: poll for one harness command at a time (turn | stop | dialog).
+        this.timer = setInterval(() => {
+            void this.step().catch((e) => recordError(this.dir, `step: ${String(e)}`));
+        }, 100);
+        if (typeof this.timer.unref === 'function')
+            this.timer.unref();
+    }
+    // --- record an injected user message (the inbox-watcher wake proof). Called by
+    //     the runtime's swapped-in sendUserMessage/sendMessage. ---------------------
+    recordInjected(rec) {
+        this.injected.push(rec);
+        try {
+            appendFileSync(join(this.dir, 'fake-pi.injected.jsonl'), JSON.stringify({ ...rec, ts: Date.now() }) + '\n');
+        }
+        catch {
+            /* best effort */
+        }
+    }
+    // --- the ctx passed to fired handlers (union across both focus extensions) ---
+    buildCtx() {
+        return {
+            sessionManager: {
+                getSessionId: () => this.sm.getSessionId(),
+                getSessionFile: () => this.sm.getSessionFile(),
+                getLeafId: () => this.turnEndLeafId ?? this.tree.getLeafId(),
+            },
+            getContextUsage: () => ({ tokens: 1000 }),
+            // Wired to the broker's shutdownHandler: the stophook calls ctx.shutdown()
+            // in exactly its done / idle-release / refresh branches → disposeAndExit.
+            shutdown: () => {
+                this.shutdownHandler?.();
+            },
+            isIdle: () => !this.streaming,
+            abort: () => { },
+            hasPendingMessages: () => this.pendingAtSettle,
+        };
+    }
+    // Append a durable record of every fired event BEFORE its handlers run — the
+    // harness's robust "the broker received my command and is dispatching it"
+    // signal, surviving a handler that exits the process (agent_end → ctx.shutdown
+    // → broker disposeAndExit → process.exit).
+    recordEvent(event, ev) {
+        try {
+            const reason = ev?.reason;
+            appendFileSync(join(this.dir, 'fake-pi.events.jsonl'), JSON.stringify({ seq: ++this.eventSeq, event, reason: reason ?? null, ts: Date.now() }) + '\n');
+        }
+        catch {
+            /* best effort */
+        }
+    }
+    async fire(event, ev, ctx) {
+        this.recordEvent(event, ev);
+        // Dispatch into the loader's REAL extension handler maps (the same handlers
+        // the SDK's reload() registered as each extension called pi.on(event, …)).
+        for (const ext of this.extensions) {
+            for (const h of ext.handlers.get(event) ?? []) {
+                try {
+                    await h(ev, ctx);
+                }
+                catch (e) {
+                    recordError(this.dir, `handler ${event} threw: ${String(e)}`);
+                }
+            }
+        }
+    }
+    // --- the command channel: one JSON command at a time, atomically renamed in --
+    async step() {
+        if (this.disposed)
+            return;
+        const cmdFile = join(this.dir, 'fake-pi.cmd');
+        if (!existsSync(cmdFile))
+            return;
+        let cmd = null;
+        try {
+            cmd = JSON.parse(readFileSync(cmdFile, 'utf8'));
+        }
+        catch {
+            cmd = null;
+        }
+        try {
+            unlinkSync(cmdFile);
+        }
+        catch {
+            /* ignore */
+        }
+        if (cmd)
+            await this.dispatch(cmd);
+    }
+    async dispatch(cmd) {
+        const ctx = this.buildCtx();
+        switch (cmd.cmd) {
+            case 'stream':
+                // Drive a subscribe-channel streaming turn WITHOUT a controller (G3:
+                // produce-while-detached) or with sized frames (G8: a fast event stream
+                // that sheds a stalled viewer at the HWM). Pure fan-out — no stophook, no
+                // exit — so the broker stays alive.
+                await this.emitTurn(cmd.text ?? 'streamed turn', {
+                    updates: cmd.updates,
+                    padBytes: cmd.padBytes,
+                    tool: cmd.tool,
+                });
+                break;
+            case 'turn':
+                this.streaming = true;
+                await this.fire('agent_start', {}, ctx);
+                this.emit({ type: 'agent_start' });
+                this.streaming = false;
+                await this.fire('turn_end', { message: { role: 'assistant', usage: { input: 10, output: 5 }, model: 'fake' } }, ctx);
+                await this.fire('agent_end', { messages: [{ role: 'assistant', stopReason: 'stop', content: [{ type: 'text', text: cmd.text ?? '' }] }] }, ctx);
+                await this.fire('agent_settled', { type: 'agent_settled' }, ctx);
+                this.emit({ type: 'agent_settled' });
+                break;
+            case 'stop': {
+                // Match pi's lifecycle: the stophook sees agent_end while the run is
+                // active, then the subscriber receives agent_settled after it clears.
+                this.streaming = true;
+                const stopMessages = [
+                    {
+                        role: 'assistant',
+                        stopReason: cmd.reason ?? 'stop',
+                        // A real engine attaches errorMessage on a stopReason:'error'
+                        // turn; the stophook classifies it for the active-fault marker.
+                        // Forward it so a test can drive a CONNECTION stall faithfully.
+                        ...(cmd.errorMessage === undefined ? {} : { errorMessage: cmd.errorMessage }),
+                        // A managed-provider cooling terminal carries the earliest pool
+                        // deadline as a typed diagnostic that survives verbatim into
+                        // agent_end.messages; the stophook reads it (extractCoolingDeadline)
+                        // to stamp retry.nextAt. Attached only when a test drives `deadline`.
+                        ...(cmd.deadline === undefined
+                            ? {}
+                            : {
+                                diagnostics: [
+                                    {
+                                        type: MANAGED_PROVIDER_COOLING_DIAGNOSTIC,
+                                        timestamp: Date.now(),
+                                        details: { rateLimitedUntil: cmd.deadline },
+                                    },
+                                ],
+                            }),
+                        content: [{ type: 'text', text: cmd.text ?? '' }],
+                    },
+                ];
+                await this.fire('agent_end', { messages: stopMessages }, ctx);
+                // Every attempt reaches the broker subscriber while streaming; only the
+                // following settled event may publish its fault or arm a retry timer.
+                this.emit({ type: 'agent_end', messages: stopMessages, willRetry: false });
+                this.streaming = false;
+                await this.fire('agent_settled', { type: 'agent_settled' }, ctx);
+                this.emit({ type: 'agent_settled' });
+                break;
+            }
+            case 'overflow': {
+                const raw = {
+                    role: 'assistant',
+                    stopReason: 'error',
+                    errorMessage: 'Your input exceeds the context window of this model.',
+                    content: [],
+                };
+                const rawMessages = [raw];
+                const emitAttemptEnd = async () => {
+                    await this.fire('agent_end', { messages: rawMessages, willRetry: false }, ctx);
+                    this.emit({ type: 'agent_end', messages: rawMessages, willRetry: false });
+                };
+                const emitRecoveredContinuation = async () => {
+                    await this.fire('agent_start', {}, ctx);
+                    this.emit({ type: 'agent_start' });
+                    const recovered = assistantMessage('recovered after compaction');
+                    await this.fire('turn_end', { message: recovered, toolResults: [] }, ctx);
+                    this.emit({ type: 'turn_end', message: recovered, toolResults: [] });
+                    await this.fire('agent_end', { messages: [recovered], willRetry: false }, ctx);
+                    this.emit({ type: 'agent_end', messages: [recovered], willRetry: false });
+                };
+                const emitDefinitiveOverflowFailure = () => {
+                    this.emit({
+                        type: 'compaction_end',
+                        reason: 'overflow',
+                        result: undefined,
+                        aborted: false,
+                        willRetry: false,
+                        errorMessage: 'Context overflow recovery failed after one compact-and-retry attempt. Try reducing context or switching to a larger-context model.',
+                    });
+                };
+                this.streaming = true;
+                await this.fire('agent_start', {}, ctx);
+                this.emit({ type: 'agent_start' });
+                await emitAttemptEnd();
+                if (cmd.outcome === 'recover') {
+                    this.emit({
+                        type: 'compaction_end',
+                        reason: 'overflow',
+                        result: { summary: 'compacted', firstKeptEntryId: 'entry-1', tokensBefore: 200_000 },
+                        aborted: false,
+                        willRetry: true,
+                    });
+                    await emitRecoveredContinuation();
+                }
+                else if (cmd.outcome === 'fail') {
+                    this.emit({
+                        type: 'compaction_end',
+                        reason: 'overflow',
+                        result: { summary: 'compacted', firstKeptEntryId: 'entry-1', tokensBefore: 200_000 },
+                        aborted: false,
+                        willRetry: true,
+                    });
+                    await this.fire('agent_start', {}, ctx);
+                    this.emit({ type: 'agent_start' });
+                    await emitAttemptEnd();
+                    emitDefinitiveOverflowFailure();
+                }
+                else if (cmd.outcome === 'failure-continued') {
+                    emitDefinitiveOverflowFailure();
+                    await emitRecoveredContinuation();
+                }
+                this.streaming = false;
+                await this.fire('agent_settled', { type: 'agent_settled' }, ctx);
+                this.emit({ type: 'agent_settled' });
+                writeFileSync(join(this.dir, 'fake-pi.overflow.json'), JSON.stringify({ outcome: cmd.outcome ?? 'uncompacted' }));
+                break;
+            }
+            case 'auto_retry':
+                // Drive the exact broker subscription event that pi emits before its
+                // retry timer, so provider fallback policy runs in the live broker.
+                this.emit({ type: 'auto_retry_start', errorMessage: cmd.errorMessage ?? 'rate limit exceeded' });
+                // The broker begins its fallback async; the next check phase follows
+                // its resolved registry/setModel microtasks and is a deterministic
+                // receipt for a rejected target (which intentionally never changes model).
+                await new Promise((resolve) => setImmediate(resolve));
+                writeFileSync(join(this.dir, 'fake-pi.auto-retry.json'), JSON.stringify({ at: Date.now() }));
+                break;
+            case 'display':
+                // Paint through the broker's REAL uiContext exactly as an extension does.
+                // These are LEVELS with no pi getter, so the broker is their only holder
+                // and must carry them in the catch-up snapshot for a LATE joiner.
+                this.uiContext?.setStatus?.(cmd.text ?? 'k', cmd.reason ?? 'v');
+                this.uiContext?.setWidget?.(cmd.text ?? 'k', [cmd.reason ?? 'v'], {
+                    placement: 'aboveEditor',
+                });
+                this.uiContext?.setTitle?.(cmd.reason ?? 'v');
+                break;
+            case 'dialog':
+                // Raise a blocking confirm() through the broker's REAL uiContext. The path
+                // taken depends on who is attached when it raises:
+                //   • ZERO viewers (C2 / G6a): makeBrokerUiContext resolves the default
+                //     (false) IMMEDIATELY — noOp fallback, no timer, no wait, no deadlock.
+                //   • a controller attached (G5): forwarded as an extension_ui_request the
+                //     controller answers via extension_ui_response — the engine proceeds.
+                //   • a controller attached but silent (G6b): resolves on the broker-side
+                //     timeout. Pass a SHORT explicit per-dialog `timeout` so that path is
+                //     fast and deterministic (never the broker's 120s default).
+                await this.runDialog(cmd.timeout ?? 0);
+                break;
+            default:
+                recordError(this.dir, `unknown cmd: ${String(cmd.cmd)}`);
+        }
+    }
+    async runDialog(timeout) {
+        const start = Date.now();
+        try {
+            const resolved = await Promise.resolve(this.uiContext?.confirm?.('headless-dialog', 'forward-progress check', { timeout }));
+            appendFileSync(join(this.dir, 'fake-pi.dialog.jsonl'), JSON.stringify({ resolved: resolved ?? null, ms: Date.now() - start, ts: Date.now() }) + '\n');
+        }
+        catch (e) {
+            recordError(this.dir, `dialog: ${String(e)}`);
+        }
+    }
+}
+/** The real pi SDK's model-less sentinel (Agent.DEFAULT_MODEL). The fake mirrors
+ *  it so `session.model` is NEVER literally `undefined` after a model-less boot,
+ *  matching prod — see the FakeSession constructor. */
+const UNKNOWN_MODEL_STUB = { provider: 'unknown', id: 'unknown', api: 'unknown' };
+function isUnknownModelStub(m) {
+    return m !== undefined && m.provider === 'unknown' && m.id === 'unknown' && m.api === 'unknown';
+}
+const FAKE_AVAILABLE_MODEL = { provider: 'fake', id: 'fake-model' };
+// Every model cell the default ladders (types.ts defaultModelLaddersConfig) can
+// resolve to must appear here: `getModels()` IS the ordered fallback set the
+// broker's launch resolver enumerates, so a ladder cell missing from this roster
+// resolves as a bare stub through `getModel()` yet can never be chosen as a
+// fallback — which silently inverts fallback direction. Keep in step with the
+// ladders.
+const FAKE_REGISTERED_MODELS = [
+    { provider: 'anthropic', id: 'claude-fable-5' },
+    { provider: 'anthropic', id: 'claude-opus-5' },
+    { provider: 'anthropic', id: 'claude-opus-4-8' },
+    { provider: 'anthropic', id: 'claude-sonnet-5' },
+    { provider: 'anthropic', id: 'claude-haiku-4-5' },
+    { provider: 'openai-codex', id: 'gpt-5.6-sol' },
+    { provider: 'openai-codex', id: 'gpt-5.6-terra' },
+    { provider: 'openai-codex', id: 'gpt-5.6-luna' },
+    FAKE_AVAILABLE_MODEL,
+];
+export async function createAgentSessionServices(options) {
+    const loader = new DefaultResourceLoader({
+        cwd: options.cwd,
+        agentDir: options.agentDir ?? getAgentDir(),
+        additionalExtensionPaths: options.resourceLoaderOptions?.additionalExtensionPaths,
+        appendSystemPrompt: options.resourceLoaderOptions?.appendSystemPrompt,
+    });
+    await loader.reload();
+    // Zero-auth test seam. While <CRTR_HOME>/fake-pi.no-auth exists, the registry
+    // reports a GENUINE zero-auth boot (nothing registered, nothing authenticated)
+    // so resolveLaunchModel (broker.ts) falls all the way to a tier-3 model-less
+    // boot — the stock always-authenticated FAKE_AVAILABLE_MODEL below can't
+    // express that. Two properties matter, both satisfied by a HOME-level sentinel
+    // FILE checked LIVE (not a one-shot env read — custom env vars don't survive
+    // cleanBaseEnv into the initial `node new --headless` boot):
+    //   • RACE-FREE ARMING: the test writes it BEFORE spawning (no per-node-dir
+    //     dependency on an id that only exists post-spawn, and the broker races to
+    //     read the registry the instant it boots).
+    //   • LIVE FLIP: a reload_auth frame's modelRegistry.refresh() re-reads these
+    //     getters, so DELETING the sentinel mid-test flips auth ON and the broker's
+    //     reload_auth re-drive observes it with zero extra plumbing — the exact
+    //     login/re-drive transition.
+    // Absent (the common case) → unchanged always-authenticated behavior.
+    const home = (process.env['CRTR_HOME'] ?? '').trim();
+    const noAuthSentinel = join(home, 'fake-pi.no-auth');
+    const zeroAuth = () => home !== '' && existsSync(noAuthSentinel);
+    return {
+        resourceLoader: loader,
+        modelRuntime: {
+            // A minimal model stub for any spec — the set_model regression test drives
+            // the broker's findModelSpec → session.setModel path through it. Nothing is
+            // findable during a zero-auth window.
+            getModel: (provider, id) => (zeroAuth() ? undefined : { provider, id }),
+            // Always-authenticated single fake model — the M-9 no-boot-model branch
+            // (broker.ts) picks `available[0]` and must never see an empty list here —
+            // EXCEPT during a zero-auth window, when nothing is available/registered.
+            getAvailableSnapshot: () => (zeroAuth() ? [] : [FAKE_AVAILABLE_MODEL]),
+            getAvailable: async () => (zeroAuth() ? [] : [FAKE_AVAILABLE_MODEL]),
+            getModels: () => (zeroAuth() ? [] : FAKE_REGISTERED_MODELS),
+            hasConfiguredAuth: () => !zeroAuth(),
+            getError: () => undefined,
+            refresh: async () => { },
+        },
+    };
+}
+export async function createAgentSessionFromServices(options) {
+    const session = new FakeSession(options.sessionManager, options.services.resourceLoader, options.model, options.services.modelRuntime);
+    // Parity with the real SDK: a construction-time thinking level IS the
+    // session's thinking level from the first turn on. The broker formats
+    // `model:thinking` off this getter, and that suffix is what distinguishes two
+    // ladder cells sharing one model id (openai ultra/strong are both
+    // gpt-5.6-sol) — dropping it here silently misroutes turn-time rotation.
+    if (options.thinkingLevel !== undefined)
+        session.setThinkingLevel(options.thinkingLevel);
+    return { session };
+}
+class FakeAgentSessionRuntime {
+    createRuntime;
+    cwd;
+    agentDir;
+    session;
+    services;
+    rebindSession;
+    constructor(createRuntime, cwd, agentDir, session, services) {
+        this.createRuntime = createRuntime;
+        this.cwd = cwd;
+        this.agentDir = agentDir;
+        this.session = session;
+        this.services = services;
+    }
+    setRebindSession(rebindSession) {
+        this.rebindSession = rebindSession;
+    }
+    async newSession() {
+        const next = await this.createRuntime({ cwd: this.cwd, agentDir: this.agentDir, sessionManager: SessionManager.create(this.cwd) });
+        this.session = next.session;
+        this.services = next.services;
+        await this.rebindSession?.(next.session);
+        return { cancelled: false };
+    }
+    async dispose() {
+        this.session.dispose();
+    }
+}
+export async function createAgentSessionRuntime(createRuntime, options) {
+    const initial = await createRuntime(options);
+    return new FakeAgentSessionRuntime(createRuntime, options.cwd, options.agentDir, initial.session, initial.services);
+}
+// ---------------------------------------------------------------------------
+// VERSION — set to the SDK's published version so assertEngineVersion (which
+// only logs, never throws) emits no spurious mismatch warning.
+// ---------------------------------------------------------------------------
+export const VERSION = '0.78.1';
+// ---------------------------------------------------------------------------
+// Parse the broker-launch.json recipe the host serialized (the PiInvocation
+// buildPiArgv produced) for the proof shape — the same `-e`/`-n`/positional
+// vocabulary fake-pi-host parses off its argv.
+// ---------------------------------------------------------------------------
+function readLaunch(dir) {
+    let argv = [];
+    try {
+        const inv = JSON.parse(readFileSync(join(dir, 'broker-launch.json'), 'utf8'));
+        argv = Array.isArray(inv.argv) ? inv.argv : [];
+    }
+    catch {
+        /* no launch file — leave argv empty */
+    }
+    const extPaths = [];
+    let label;
+    let prompt;
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === '-e')
+            extPaths.push(argv[++i]);
+        else if (a === '-n')
+            label = argv[++i];
+        else if (a === '--session' || a === '--model' || a === '--tools' || a === '--append-system-prompt' || a === '--fork')
+            i++;
+        else if (!a.startsWith('-'))
+            prompt = a; // positional kickoff (fresh start only)
+    }
+    return { argv, extPaths, label, prompt };
+}