@north-light/crouter 0.3.318 → 0.3.320

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

@@ -1,1509 +0,0 @@
-// 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 { spawn } from 'node:child_process';
-import { writeFileSync, readFileSync, existsSync, mkdirSync, appendFileSync, unlinkSync, } from 'node:fs';
-import { join, dirname, resolve } from 'node:path';
-import { randomUUID } from 'node:crypto';
-import { DefaultPackageManager, DefaultResourceLoader, getAgentDir, SettingsManager } from '@earendil-works/pi-coding-agent';
-import { MANAGED_PROVIDER_COOLING_DIAGNOSTIC } from '../../runtime/managed-provider-cooling.js';
-import { PROVIDER_FAILURE_DIAGNOSTIC } from '../../provider-failure.js';
-import { CANVAS_EXTENSIONS } from '../../runtime/canvas-extensions.js';
-import registerCanvasBashValve, { createValveOperations } from '../../../pi-extensions/canvas-bash-valve.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, '');
-        const sessionId = `fake-sess-${randomUUID()}`;
-        writeFileSync(`${sessionFile}.id`, sessionId);
-        return new SessionManager(sessionId, 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 saved session identity with its .jsonl path. */
-    static open(path) {
-        const sessionId = readFileSync(`${path}.id`, 'utf8').trim();
-        if (sessionId === '')
-            throw new Error(`fake session identity is empty: ${path}.id`);
-        return new SessionManager(sessionId, 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. 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;
-    }
-    /** Reconstructs a prior process's tree from its persisted snapshot — the
-     *  fake's analog of the real SessionManager.open() reading every entry back
-     *  from the .jsonl. A genuine resume (not a fresh cycle) must see this
-     *  broker's actual history, not an empty tree, or nothing downstream that
-     *  reads the branch past a crash can ever observe real prior content. */
-    hydrate(entries, leafId) {
-        for (const entry of entries) {
-            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 = leafId;
-    }
-    /** 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 };
-    }
-    /** Every entry in the session file, active branch or abandoned tail alike —
-     *  the real SessionManager.getEntries(). */
-    getEntries() {
-        return [...this.entries.values()];
-    }
-    /** The active branch root→leaf — the real SessionManager.getBranch(). The
-     *  extensions that scan for their own marker read THIS, not the whole file:
-     *  a new cycle must not see a previous branch's markers. */
-    getBranch(fromId) {
-        return this.branchIds(fromId).map((id) => this.entries.get(id)).filter((entry) => entry !== undefined);
-    }
-    branchMessages() {
-        return this.branchIds().map((id) => this.entries.get(id)?.message).filter((m) => m !== undefined);
-    }
-    /** One branch's entry ids, root→leaf, from `fromId` (default: the current
-     *  leaf) — the real SessionManager.getBranch(fromId?) contract. */
-    branchIds(fromId) {
-        const ids = [];
-        let cur = fromId ?? this.leafId;
-        while (cur !== null && cur !== undefined) {
-            const entry = this.entries.get(cur);
-            if (entry === undefined)
-                break;
-            ids.push(cur);
-            cur = entry.parentId;
-        }
-        ids.reverse();
-        return ids;
-    }
-    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;
-    /** Compiled-seam graceful-teardown vehicle: a real active turn that only settles
-     * after abort(), so the broker's bounded abort wait is observable. */
-    heldTurn;
-    retryAbort;
-    // 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 compiled seam 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;
-        // A genuine resume (not a fresh cycle) must see this broker's own prior
-        // history — the fake's analog of the real SessionManager.open() replaying
-        // every persisted entry. A cycling revive has already rooted a fresh cycle
-        // marker on `sm` before this construction (broker.ts), which is exactly what
-        // distinguishes it here: `sm.getLeafId()` is non-null only on that path, so
-        // a cycling boot deliberately skips hydration and starts clean.
-        if (sm.resumed && sm.getLeafId() === null)
-            this.hydrateFromPriorSnapshot();
-        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.
-    // Built once and cached: the real SessionManager is a single object the
-    // broker's advertised-command contract monkey-patches
-    // (appendCustomMessageEntry), so a fresh literal per access would silently
-    // discard that patch.
-    smFacade;
-    get sessionManager() {
-        this.smFacade ??= {
-            buildSessionContext: () => this.tree.buildSessionContext(),
-            getLeafId: () => this.tree.getLeafId(),
-            getEntry: (id) => this.tree.getEntry(id),
-            getTree: () => this.tree.getTree(),
-            getBranch: (fromId) => this.tree.getBranch(fromId),
-            getEntries: () => this.tree.getEntries(),
-            getUserMessagesForForking: () => this.tree.getUserMessagesForForking(),
-            getSessionId: () => this.sm.getSessionId(),
-            getSessionFile: () => this.sm.getSessionFile(),
-            getSessionDir: () => this.sm.getSessionDir(),
-            appendCustomMessageEntry: (customType, content, display, details) => this.tree.append({ role: 'custom', customType, content, display, details }).id,
-        };
-        return this.smFacade;
-    }
-    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;
-    bashAbort;
-    bashRun;
-    get thinkingLevel() {
-        return this.currentThinkingLevel;
-    }
-    setThinkingLevel(level) {
-        if (this.currentThinkingLevel === level)
-            return;
-        this.currentThinkingLevel = level;
-        this.emit({ type: 'thinking_level_changed', level });
-    }
-    cycleThinkingLevel() {
-        const levels = ['off', 'minimal', 'low', 'medium', 'high', 'xhigh'];
-        const current = this.currentThinkingLevel === undefined ? -1 : levels.indexOf(this.currentThinkingLevel);
-        const next = levels[(current + 1) % levels.length];
-        this.setThinkingLevel(next);
-        return next;
-    }
-    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 };
-    }
-    getContextUsage() {
-        try {
-            const tokens = Number(readFileSync(join(this.dir, 'fake-pi.context-tokens'), 'utf8'));
-            return Number.isFinite(tokens) ? { tokens } : undefined;
-        }
-        catch {
-            return { tokens: 1000 };
-        }
-    }
-    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(),
-                // Flat entries + leafId are the reload shape a future process's
-                // hydrateFromPriorSnapshot() reads back — getTree()'s nested form is
-                // proof-only and not reconstructed from.
-                entries: this.tree.getEntries(),
-                userMessagesForForking: this.tree.getUserMessagesForForking(),
-            }, null, 2));
-        }
-        catch {
-            /* best effort */
-        }
-    }
-    /** Reads the crashed process's last `fake-pi.tree.json` (if any) and rebuilds
-     *  this process's tree from it. Best-effort: a first boot (no snapshot yet)
-     *  leaves the tree empty, matching today's behavior. */
-    hydrateFromPriorSnapshot() {
-        try {
-            const raw = readFileSync(join(this.dir, 'fake-pi.tree.json'), 'utf8');
-            const parsed = JSON.parse(raw);
-            if (!Array.isArray(parsed.entries) || parsed.entries.length === 0)
-                return;
-            this.tree.hydrate(parsed.entries, parsed.leafId ?? null);
-        }
-        catch {
-            /* no prior snapshot — fresh tree */
-        }
-    }
-    // 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'));
-        }
-        options?.preflightResult?.(true);
-        // The inbox watcher now enters through the broker-owned prompt bridge, not
-        // the Pi extension runtime. Keep its existing observable wake record for
-        // the compiled dormancy seam while the prompt drives the real lifecycle.
-        if (text.startsWith('<runtime kind="inbox"'))
-            this.recordInjected({ content: text });
-        // 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 });
-    }
-    /** The unrun queues the welcome snapshot reports (`snapshot.queued`). Real
-     *  pi holds a steer + followUp queue and drains it when the next turn runs;
-     *  the fake records the same texts and clears them in emitTurn, so a client
-     *  attaching mid-queue sees what a real broker would hand it. Both readers
-     *  exist on the real AgentSession, so omitting them does not make the fake
-     *  merely queueless — it makes buildSnapshot throw, and every attach test
-     *  then times out waiting for a welcome the broker never built. */
-    steering = [];
-    followUps = [];
-    getSteeringMessages() {
-        return this.steering;
-    }
-    getFollowUpMessages() {
-        return this.followUps;
-    }
-    steer(text) {
-        this.steering.push(text);
-        return Promise.resolve();
-    }
-    followUp(text) {
-        this.followUps.push(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) {
-        const customMessage = {
-            customType: message.customType,
-            content: message.content,
-            display: message.display,
-            deliverAs: options?.deliverAs,
-        };
-        this.customMessages.push(customMessage);
-        try {
-            appendFileSync(join(this.dir, 'fake-pi.custom-messages.jsonl'), JSON.stringify(customMessage) + '\n');
-        }
-        catch {
-            /* best effort test proof */
-        }
-        return Promise.resolve();
-    }
-    abort() {
-        const held = this.heldTurn;
-        if (held !== undefined) {
-            held.release();
-            return held.settled;
-        }
-        this.bashAbort?.abort();
-        return this.bashRun ?? Promise.resolve();
-    }
-    abortRetry() {
-        this.retryAbort?.();
-    }
-    /** 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));
-        // A turn consumes whatever was queued for it, as the real session does.
-        this.steering.length = 0;
-        this.followUps.length = 0;
-        let releaseGate;
-        if (process.env['PI_FAKE_ENGINE_HOLD_TURN'] === '1') {
-            let release;
-            let resolveSettled;
-            const settled = new Promise((resolve) => { resolveSettled = resolve; });
-            releaseGate = new Promise((resolve) => { release = resolve; });
-            this.heldTurn = { release, settled, resolveSettled };
-        }
-        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 });
-        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_PROFILE_ID: env['CRTR_PROFILE_ID'] ?? 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(),
-                // The session-scanning extensions (context-intro, review-boundary,
-                // recap) read the branch at session_start to decide whether their own
-                // marker is already present. Both exist on the real SessionManager, so
-                // a fake missing them is not a degraded fixture but a broken one: the
-                // handler throws, session_start never completes, and every attach test
-                // times out waiting for a welcome that the broker never sends.
-                getBranch: () => this.tree.getBranch(),
-                getEntries: () => this.tree.getEntries(),
-            },
-            getContextUsage: () => this.getContextUsage(),
-            // 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 'self_close': {
-                const cli = join(dirname(new URL(import.meta.url).pathname), '../../../cli.js');
-                const resultPath = join(this.dir, 'self-close-result');
-                const pidPath = join(this.dir, 'self-close-shell.pid');
-                const shell = spawn('sh', ['-c', `"${process.execPath}" "${cli}" node lifecycle close --node "$CRTR_NODE_ID"; code=$?; printf '%s\\n' "$code" > "${resultPath}"; while :; do sleep 1; done`], { detached: true, stdio: 'ignore', env: process.env });
-                if (shell.pid !== undefined)
-                    writeFileSync(pidPath, `${shell.pid}\n`);
-                shell.unref();
-                break;
-            }
-            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 'bash': {
-                const nodeId = process.env['CRTR_NODE_ID'];
-                const contextDir = process.env['CRTR_CONTEXT_DIR'];
-                if (nodeId === undefined || contextDir === undefined)
-                    throw new Error('bash control requires canvas node paths');
-                this.streaming = true;
-                await this.fire('agent_start', {}, ctx);
-                this.emit({ type: 'agent_start' });
-                // The resource loader imports extensions through jiti while this fixture
-                // imports its valve operations through Node. Register the same module
-                // instance here so its SIGTERM listener owns this real test job too.
-                registerCanvasBashValve({ on: () => { } });
-                const controller = new AbortController();
-                this.bashAbort = controller;
-                const run = createValveOperations(nodeId, contextDir).exec(cmd.command ?? 'true', process.cwd(), {
-                    onData: () => { },
-                    signal: controller.signal,
-                }).then(() => { });
-                this.bashRun = run;
-                try {
-                    await run;
-                }
-                finally {
-                    this.bashAbort = undefined;
-                    this.bashRun = undefined;
-                    this.streaming = false;
-                }
-                await this.fire('agent_end', { messages: [] }, ctx);
-                this.emit({ type: 'agent_end', messages: [], willRetry: false });
-                await this.fire('agent_settled', { type: 'agent_settled' }, ctx);
-                this.emit({ type: 'agent_settled' });
-                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: message_end reaches broker fallback policy
-                // before the stophook sees agent_end while the run is active; the
-                // subscriber receives agent_settled after it clears.
-                this.streaming = true;
-                const diagnostics = [
-                    ...(cmd.deadline === undefined ? [] : [{
-                            type: MANAGED_PROVIDER_COOLING_DIAGNOSTIC,
-                            timestamp: Date.now(),
-                            details: { rateLimitedUntil: cmd.deadline },
-                        }]),
-                    ...(cmd.providerFailure === undefined ? [] : [{
-                            type: PROVIDER_FAILURE_DIAGNOSTIC,
-                            timestamp: Date.now(),
-                            details: cmd.providerFailure,
-                        }]),
-                ];
-                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 }),
-                        ...(diagnostics.length === 0 ? {} : { diagnostics }),
-                        content: [{ type: 'text', text: cmd.text ?? '' }],
-                    },
-                ];
-                this.emit({ type: 'message_end', message: stopMessages[0] });
-                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': {
-                // Pi emits agent_end for the failed attempt, then auto_retry_start, and
-                // only then creates the AbortController for its delay. The capacity
-                // fallback must defer abortRetry one microtask to cancel this retry.
-                const retryMessages = [{
-                        role: 'assistant', stopReason: 'error', errorMessage: cmd.errorMessage ?? 'rate limit exceeded', content: [],
-                    }];
-                this.streaming = true;
-                await this.fire('agent_end', { messages: retryMessages }, ctx);
-                this.emit({ type: 'agent_end', messages: retryMessages, willRetry: true });
-                this.emit({ type: 'auto_retry_start', errorMessage: cmd.errorMessage ?? 'rate limit exceeded' });
-                let aborted = false;
-                this.retryAbort = () => { aborted = true; };
-                await new Promise((resolve) => setImmediate(resolve));
-                this.retryAbort = undefined;
-                if (aborted)
-                    this.emit({ type: 'auto_retry_end', success: false, finalError: 'Retry cancelled' });
-                this.streaming = false;
-                await this.fire('agent_settled', { type: 'agent_settled' }, ctx);
-                this.emit({ type: 'agent_settled' });
-                writeFileSync(join(this.dir, 'fake-pi.auto-retry.json'), JSON.stringify({ at: Date.now(), aborted }));
-                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)}`);
-        }
-    }
-}
-function fakeModel(provider, id) {
-    try {
-        const capacities = JSON.parse(readFileSync(join(nodeDirFromEnv(), 'fake-pi.model-capacities.json'), 'utf8'));
-        const contextWindow = capacities[`${provider}/${id}`];
-        return typeof contextWindow === 'number' && Number.isFinite(contextWindow)
-            ? { provider, id, contextWindow }
-            : { provider, id };
-    }
-    catch {
-        return { provider, id };
-    }
-}
-/** 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-6-astra' },
-    { 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,
-];
-/** Source harnesses use native imports only for an isolated, mandatory-only
- * canvas fixture. Every other source stays on the SDK file-loader path. */
-async function sourceCanvasExtensionLoaderOptions(cwd, agentDir, options) {
-    const extensionPaths = options?.additionalExtensionPaths;
-    const mandatoryOnly = extensionPaths?.length === CANVAS_EXTENSIONS.length
-        && extensionPaths.every((path, index) => path === CANVAS_EXTENSIONS[index]);
-    if (!import.meta.url.endsWith('.ts') || !mandatoryOnly)
-        return { additionalExtensionPaths: extensionPaths };
-    const settingsManager = SettingsManager.create(cwd, agentDir);
-    const resolved = await new DefaultPackageManager({ cwd, agentDir, settingsManager }).resolve();
-    if (resolved.extensions.some((extension) => extension.enabled)) {
-        return { additionalExtensionPaths: extensionPaths, settingsManager };
-    }
-    const inlinePaths = new Map();
-    const fileLoaderErrors = new Map();
-    const missingPaths = [];
-    const extensionFactories = [];
-    for (const inputPath of extensionPaths) {
-        const path = resolve(cwd, inputPath);
-        if (!existsSync(path)) {
-            missingPaths.push(path);
-            continue;
-        }
-        inlinePaths.set(`<inline:${path}>`, path);
-        let factory;
-        try {
-            const loaded = await import(path);
-            if (typeof loaded.default !== 'function') {
-                fileLoaderErrors.set(path, `Extension does not export a valid factory function: ${path}`);
-                factory = () => { throw new Error(fileLoaderErrors.get(path)); };
-            }
-            else {
-                factory = loaded.default;
-            }
-        }
-        catch {
-            // Let the original loader produce its own import/transform diagnostic.
-            return { additionalExtensionPaths: extensionPaths, settingsManager };
-        }
-        extensionFactories.push({ name: path, factory });
-    }
-    return {
-        additionalExtensionPaths: [],
-        extensionFactories,
-        settingsManager,
-        restoreCliExtensionMetadata: (loader) => {
-            const result = loader.getExtensions();
-            for (const extension of result.extensions) {
-                const path = inlinePaths.get(extension.path);
-                if (path === undefined)
-                    continue;
-                const sourceInfo = { path, source: 'cli', scope: 'temporary', origin: 'top-level', baseDir: undefined };
-                extension.path = path;
-                extension.resolvedPath = path;
-                extension.sourceInfo = sourceInfo;
-                for (const command of extension.commands.values())
-                    command.sourceInfo = sourceInfo;
-                for (const tool of extension.tools.values())
-                    tool.sourceInfo = sourceInfo;
-            }
-            for (const error of result.errors) {
-                const path = inlinePaths.get(error.path);
-                if (path !== undefined) {
-                    error.path = path;
-                    const isConflict = /^(?:Tool|Flag) ".*" conflicts with /.test(error.error);
-                    error.error = fileLoaderErrors.get(path) ?? (isConflict ? error.error : `Failed to load extension: ${error.error}`);
-                }
-                for (const [inlinePath, filePath] of inlinePaths) {
-                    error.error = error.error.replaceAll(inlinePath, filePath);
-                }
-            }
-            result.errors.push(...missingPaths.map((path) => ({ path, error: `Extension path does not exist: ${path}` })));
-        },
-    };
-}
-export async function createAgentSessionServices(options) {
-    const agentDir = options.agentDir ?? getAgentDir();
-    const extensionOptions = await sourceCanvasExtensionLoaderOptions(options.cwd, agentDir, options.resourceLoaderOptions);
-    const { restoreCliExtensionMetadata, ...loaderOptions } = extensionOptions;
-    const loader = new DefaultResourceLoader({
-        cwd: options.cwd,
-        agentDir,
-        ...loaderOptions,
-        appendSystemPrompt: options.resourceLoaderOptions?.appendSystemPrompt,
-    });
-    await loader.reload();
-    restoreCliExtensionMetadata?.(loader);
-    // 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 unauthenticatedProviderSentinel = join(home, 'fake-pi.unauthenticated-provider');
-    const zeroAuth = () => home !== '' && existsSync(noAuthSentinel);
-    const readUnauthenticatedProvider = () => {
-        try {
-            return readFileSync(unauthenticatedProviderSentinel, 'utf8').trim() || undefined;
-        }
-        catch {
-            return undefined;
-        }
-    };
-    // Unlike the all-or-nothing no-auth seam, this mirrors ModelRuntime's cached
-    // configuredProviders snapshot: a provider-specific auth change becomes
-    // visible only after refresh() completes.
-    let unauthenticatedProvider = readUnauthenticatedProvider();
-    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 : fakeModel(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: (provider) => !zeroAuth() && provider !== unauthenticatedProvider,
-            getError: () => undefined,
-            refresh: async () => {
-                await new Promise((resolve) => setImmediate(resolve));
-                unauthenticatedProvider = readUnauthenticatedProvider();
-            },
-        },
-    };
-}
-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 — 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 };
-}