@stigmer/runner 3.15.0 → 3.15.2-dev.20260913223433

package/dist/activities/execute-deep-agent/__test-utils__/contract-subject.d.ts

@@ -0,0 +1,93 @@
+/**
+ * The native deep-agent harness as a `HarnessContractSubject` — the REAL
+ * `createDeepAgentAdapter()` driven through the harness contract kit, with
+ * the kit's engine-neutral scenario vocabulary translated onto the
+ * `ScriptedModel` double that every native hermetic golden already runs on.
+ *
+ * The sibling of `execute-cursor/__test-utils__/contract-subject.ts` (the
+ * mold) and of `gateway-substrate.ts` (the native side of the approval
+ * contract kit): the kit owns the invariants and the runtime stand-in, this
+ * module owns the ENGINE — what the model will do on its next call — and
+ * reports what really happened. The adapter under test is the production
+ * one, untouched; the model client is the one module doubled
+ * (`scripted-model-module.ts`, S3 M0 ruling Q-M0-1), and the tools the model
+ * calls are deepagents' real built-ins over the real gate.
+ *
+ * ── The engine is per execution, and its memory is the conversation ────────
+ * One `ScriptedModel` per execution, minted at the first `arrange` and handed
+ * out by the double for every build production requests under that
+ * execution's `headerScope.executionId` — the attribution header the proxy
+ * already carries, so concurrent executions each reach their own engine
+ * through an id nothing was added to send. The kit arranges a turn as a
+ * PLAN, and on every model call the engine plays the first step the
+ * conversation does not yet show: a `propose` or `read` whose tool-call id
+ * already has a `ToolMessage` anywhere on the thread (executed, or the
+ * gate's denial) is done; a `say` already spoken in THIS turn's segment
+ * (after the last human message) is done; `usage` folds into the turn's
+ * first model call only. Nothing is remembered on the subject: the sqlite
+ * checkpoint IS the engine's memory, which is why the same plan is right on
+ * a `Command(resume)` (the tool result is in the transcript before the model
+ * is asked) and on a later turn of the same thread (an approved-and-run call
+ * is not proposed again — Cursor's "obedient model" of Q-M4-4, derived
+ * instead of stored).
+ *
+ * ── The translation, one rule per word ──────────────────────────────────────
+ *  - `say(text)`      → the turn's text. A second `say` before any tool step
+ *                       inserts an ungated `think` call as the step boundary:
+ *                       a LangGraph agent cannot speak twice without acting
+ *                       (only the cost-cap arm's `[say, usage, say]` needs it).
+ *  - `propose(id, a)` → ONE gated built-in whose execution is counted by a
+ *                       REAL side effect the subject reads back:
+ *                       `write r` → `edit_file` appending `id` as a line to a
+ *                       ledger the subject seeded at the path the backend
+ *                       resolves `r` to (`resolveWorkspacePath`, the virtual
+ *                       root). FILE_EDIT and FILE_WRITE are one `write`
+ *                       category by design (`tool-kind.ts`); unlike
+ *                       `write_file`, which refuses an existing path and so
+ *                       leaves no trace of a second execution, an edit
+ *                       counts EVERY execution.
+ *                       `shell r` → `execute` appending `id` to the session's
+ *                       shell ledger, `r` riding as a trailing comment.
+ *                       `delete` and `mcp` are refused as test bugs: no kit
+ *                       invariant asks for them here.
+ *                       `executionCount(id)` is the number of ledger lines
+ *                       equal to `id` — the safety-critical observable, read
+ *                       off disk, independent of anything the adapter wrote.
+ *  - `read(id, path)` → `read_file` of a file the subject seeds; the ungated
+ *                       tool call every harness flushes a persist on.
+ *  - `usage(delta)`   → the model turn's `usage_metadata` (the cache buckets
+ *                       under `input_token_details`); consecutive deltas sum,
+ *                       the kit judges sums.
+ *  - `hang`           → the turn parks on the run's abort signal after its
+ *                       chunks (`ScriptedTurn.ends`); the park resolves
+ *                       `whenHanging()`. Never a timer.
+ *  - `fail(msg, s)`   → the turn throws `msg` after its chunks. `engine` and
+ *                       `internal` are one act here: the native adapter has
+ *                       ONE failure surface (`turn.ts` classifies every
+ *                       escaped error `internal`); `actionable` is refused.
+ *  - `limit`          → a `think` call under a fresh id on every model call,
+ *                       until the graph's recursion limit stops the run.
+ *  - `cancelled`      → refused: this harness has no engine-side cancel (the
+ *                       runtime arm is declared off for it).
+ */
+import { type BaseMessage } from "@langchain/core/messages";
+import type { HarnessAdapter } from "../../../harness/types.js";
+import type { HarnessContractSubject } from "../../../__test-utils__/harness-contract/types.js";
+import type { HermeticEnvironment } from "../../../__test-utils__/hermetic-activity.js";
+import { ScriptedModel } from "./scripted-model.js";
+export interface DeepAgentContractSubject extends HarnessContractSubject {
+    readonly adapter: HarnessAdapter;
+    /** The engine minted for an execution, once the kit has arranged a turn for it. */
+    engineFor(executionId: string): ScriptedModel | undefined;
+    /** The conversation the engine was last asked with, for the subject file's observations of what the graph shows the model. */
+    lastTranscriptOf(executionId: string): readonly BaseMessage[] | undefined;
+    /** The session's workspace directory, as the runtime's provisioner resolves it and as this subject seeds it. */
+    workspaceDirOf(sessionId: string): string;
+}
+/**
+ * Build the subject over one hermetic environment (the temp `HOME` the sqlite
+ * checkpoints land under, the temp workspace root). The environment is the
+ * caller's to create before and dispose after; the model-client double is
+ * bound for the module here, so a file holds one subject.
+ */
+export declare function createDeepAgentContractSubject(env: HermeticEnvironment): DeepAgentContractSubject;

package/dist/activities/execute-deep-agent/__test-utils__/contract-subject.js

@@ -0,0 +1,348 @@
+/**
+ * The native deep-agent harness as a `HarnessContractSubject` — the REAL
+ * `createDeepAgentAdapter()` driven through the harness contract kit, with
+ * the kit's engine-neutral scenario vocabulary translated onto the
+ * `ScriptedModel` double that every native hermetic golden already runs on.
+ *
+ * The sibling of `execute-cursor/__test-utils__/contract-subject.ts` (the
+ * mold) and of `gateway-substrate.ts` (the native side of the approval
+ * contract kit): the kit owns the invariants and the runtime stand-in, this
+ * module owns the ENGINE — what the model will do on its next call — and
+ * reports what really happened. The adapter under test is the production
+ * one, untouched; the model client is the one module doubled
+ * (`scripted-model-module.ts`, S3 M0 ruling Q-M0-1), and the tools the model
+ * calls are deepagents' real built-ins over the real gate.
+ *
+ * ── The engine is per execution, and its memory is the conversation ────────
+ * One `ScriptedModel` per execution, minted at the first `arrange` and handed
+ * out by the double for every build production requests under that
+ * execution's `headerScope.executionId` — the attribution header the proxy
+ * already carries, so concurrent executions each reach their own engine
+ * through an id nothing was added to send. The kit arranges a turn as a
+ * PLAN, and on every model call the engine plays the first step the
+ * conversation does not yet show: a `propose` or `read` whose tool-call id
+ * already has a `ToolMessage` anywhere on the thread (executed, or the
+ * gate's denial) is done; a `say` already spoken in THIS turn's segment
+ * (after the last human message) is done; `usage` folds into the turn's
+ * first model call only. Nothing is remembered on the subject: the sqlite
+ * checkpoint IS the engine's memory, which is why the same plan is right on
+ * a `Command(resume)` (the tool result is in the transcript before the model
+ * is asked) and on a later turn of the same thread (an approved-and-run call
+ * is not proposed again — Cursor's "obedient model" of Q-M4-4, derived
+ * instead of stored).
+ *
+ * ── The translation, one rule per word ──────────────────────────────────────
+ *  - `say(text)`      → the turn's text. A second `say` before any tool step
+ *                       inserts an ungated `think` call as the step boundary:
+ *                       a LangGraph agent cannot speak twice without acting
+ *                       (only the cost-cap arm's `[say, usage, say]` needs it).
+ *  - `propose(id, a)` → ONE gated built-in whose execution is counted by a
+ *                       REAL side effect the subject reads back:
+ *                       `write r` → `edit_file` appending `id` as a line to a
+ *                       ledger the subject seeded at the path the backend
+ *                       resolves `r` to (`resolveWorkspacePath`, the virtual
+ *                       root). FILE_EDIT and FILE_WRITE are one `write`
+ *                       category by design (`tool-kind.ts`); unlike
+ *                       `write_file`, which refuses an existing path and so
+ *                       leaves no trace of a second execution, an edit
+ *                       counts EVERY execution.
+ *                       `shell r` → `execute` appending `id` to the session's
+ *                       shell ledger, `r` riding as a trailing comment.
+ *                       `delete` and `mcp` are refused as test bugs: no kit
+ *                       invariant asks for them here.
+ *                       `executionCount(id)` is the number of ledger lines
+ *                       equal to `id` — the safety-critical observable, read
+ *                       off disk, independent of anything the adapter wrote.
+ *  - `read(id, path)` → `read_file` of a file the subject seeds; the ungated
+ *                       tool call every harness flushes a persist on.
+ *  - `usage(delta)`   → the model turn's `usage_metadata` (the cache buckets
+ *                       under `input_token_details`); consecutive deltas sum,
+ *                       the kit judges sums.
+ *  - `hang`           → the turn parks on the run's abort signal after its
+ *                       chunks (`ScriptedTurn.ends`); the park resolves
+ *                       `whenHanging()`. Never a timer.
+ *  - `fail(msg, s)`   → the turn throws `msg` after its chunks. `engine` and
+ *                       `internal` are one act here: the native adapter has
+ *                       ONE failure surface (`turn.ts` classifies every
+ *                       escaped error `internal`); `actionable` is refused.
+ *  - `limit`          → a `think` call under a fresh id on every model call,
+ *                       until the graph's recursion limit stops the run.
+ *  - `cancelled`      → refused: this harness has no engine-side cancel (the
+ *                       runtime arm is declared off for it).
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { isAIMessage, isHumanMessage, isToolMessage } from "@langchain/core/messages";
+import { resolveWorkspacePath } from "../../../shared/file-change.js";
+import { createDeepAgentAdapter } from "../adapter.js";
+import { hermeticDeepAgentConfig } from "./hermetic-deep-agent.js";
+import { ScriptedModel } from "./scripted-model.js";
+import { bindScriptedModel } from "./scripted-model-module.js";
+/** The user's message every kit turn asks; the prompt builder needs one and the kit has none to give. */
+const KIT_USER_MESSAGE = "Do what the scenario says.";
+/** The one line a write ledger starts with; every execution appends its id under it, so the edit's anchor stays unique. */
+const WRITE_LEDGER_MARK = "KIT-LEDGER";
+/** What a seeded `read` target contains; the content is never asserted, the completed row is. */
+const READ_FILE_CONTENT = "seeded by the harness contract kit\n";
+/**
+ * Build the subject over one hermetic environment (the temp `HOME` the sqlite
+ * checkpoints land under, the temp workspace root). The environment is the
+ * caller's to create before and dispose after; the model-client double is
+ * bound for the module here, so a file holds one subject.
+ */
+export function createDeepAgentContractSubject(env) {
+    return new DeepAgentSubject(env);
+}
+class DeepAgentSubject {
+    env;
+    name = "deep-agent";
+    harness = "deep-agent";
+    adapter;
+    config;
+    engines = new Map();
+    arranged = new Map();
+    lastTranscripts = new Map();
+    ledgers = new Map();
+    hangWaiters = [];
+    mintCounter = 0;
+    constructor(env) {
+        this.env = env;
+        this.config = hermeticDeepAgentConfig(env, "sqlite");
+        this.adapter = createDeepAgentAdapter();
+        bindScriptedModel((opts) => {
+            const executionId = opts.headerScope?.executionId;
+            const engine = executionId ? this.engines.get(executionId) : undefined;
+            if (!engine) {
+                throw new Error(`${this.name}: buildChatModel asked for execution '${executionId ?? "<none>"}' but no turn was arranged for it (kit bug)`);
+            }
+            return engine;
+        });
+    }
+    // ── HarnessContractSubject ────────────────────────────────────────────────
+    arrange(turn, view) {
+        // A word this subject cannot translate is refused HERE, as a test bug:
+        // refused at play time it would surface as an engine failure and read as
+        // the adapter's behaviour.
+        for (const step of turn)
+            this.refuseUnproducible(step);
+        mkdirSync(this.workspaceDirOf(view.sessionId), { recursive: true });
+        for (const step of turn)
+            this.seedFor(step, view);
+        this.arranged.set(view.executionId, { steps: turn, view });
+        if (!this.engines.has(view.executionId))
+            this.engines.set(view.executionId, this.mintEngine(view.executionId));
+    }
+    inputOverrides(view) {
+        // No model is named: the adapter resolves the registry's featured native
+        // model, which is the fixture's — the production "no model named" path.
+        return { workspaceDir: this.workspaceDirOf(view.sessionId), message: KIT_USER_MESSAGE };
+    }
+    whenHanging() {
+        return new Promise((resolve) => this.hangWaiters.push(resolve));
+    }
+    executionCount(toolCallId) {
+        const ledger = this.ledgers.get(toolCallId);
+        if (!ledger || !existsSync(ledger.file))
+            return 0;
+        return readFileSync(ledger.file, "utf8")
+            .split("\n")
+            .filter((line) => line === toolCallId).length;
+    }
+    // ── The subject file's observations ──────────────────────────────────────
+    engineFor(executionId) {
+        return this.engines.get(executionId);
+    }
+    lastTranscriptOf(executionId) {
+        return this.lastTranscripts.get(executionId);
+    }
+    /** The directory the runtime's provisioner gives a session with no workspace entries (`session-root.ts`). */
+    workspaceDirOf(sessionId) {
+        return join(this.env.workspaceRootDir, "sessions", sessionId);
+    }
+    // ── The engine ────────────────────────────────────────────────────────────
+    mintEngine(executionId) {
+        return new ScriptedModel(() => (transcript) => this.play(executionId, transcript), [], {
+            onPark: () => {
+                for (const waiter of this.hangWaiters.splice(0))
+                    waiter();
+            },
+        });
+    }
+    /** The words this subject has no honest translation for (see the header); each is a kit-file bug, named. */
+    refuseUnproducible(step) {
+        switch (step.kind) {
+            case "propose":
+                if (step.action.kind !== "write" && step.action.kind !== "shell") {
+                    throw new Error(`${this.name}: propose(${step.action.kind}) is not translated by this subject (no kit invariant asks for it); test bug`);
+                }
+                return;
+            case "fail":
+                if (step.surface === "actionable") {
+                    throw new Error(`${this.name}: fail(..., "actionable") is not producible by this subject (the native adapter has one failure surface, internal); test bug`);
+                }
+                return;
+            case "cancelled":
+                throw new Error(`${this.name}: cancelled() is not producible by this subject (this harness has no engine-side cancel; the runtime arm is declared off for it); test bug`);
+            case "say":
+            case "read":
+            case "usage":
+            case "hang":
+            case "limit":
+                return;
+            default: {
+                const exhaustive = step;
+                throw new Error(`${this.name}: unknown scenario step ${JSON.stringify(exhaustive)}`);
+            }
+        }
+    }
+    /** The shell ledger of one session; outside the session's workspace so the engine's tree holds only what the engine wrote. */
+    shellLedgerOf(sessionId) {
+        return join(this.env.workspaceRootDir, "kit-ledgers", `${sessionId}.log`);
+    }
+    /** Put on disk what a step's tool will find there: the write ledger under its mark, the read target. */
+    seedFor(step, view) {
+        const workspaceDir = this.workspaceDirOf(view.sessionId);
+        if (step.kind === "propose" && step.action.kind === "write") {
+            const file = resolveWorkspacePath(step.action.resource, workspaceDir, true).absolutePath;
+            seedFile(file, `${WRITE_LEDGER_MARK}\n`);
+            this.ledgers.set(step.toolCallId, { kind: "write", file });
+        }
+        else if (step.kind === "propose" && step.action.kind === "shell") {
+            const file = this.shellLedgerOf(view.sessionId);
+            mkdirSync(dirname(file), { recursive: true });
+            this.ledgers.set(step.toolCallId, { kind: "shell", file });
+        }
+        else if (step.kind === "read") {
+            seedFile(resolveWorkspacePath(step.path, workspaceDir, true).absolutePath, READ_FILE_CONTENT);
+        }
+    }
+    /**
+     * The one turn to play now: the plan's steps in order, each skipped when
+     * the conversation already shows it, until a step closes the turn (a tool
+     * call, a hang, a failure) or the plan runs out (an empty message, which
+     * ends the graph run).
+     */
+    play(executionId, transcript) {
+        const plan = this.arranged.get(executionId);
+        if (!plan)
+            throw new Error(`${this.name}: the model was asked for execution '${executionId}' with no turn arranged (kit bug)`);
+        this.lastTranscripts.set(executionId, transcript);
+        const settled = settledToolCallIds(transcript);
+        const segment = messagesOfThisTurn(transcript);
+        const spoken = new Set(segment.filter((m) => isAIMessage(m)).map((m) => m.text));
+        const firstCallOfTurn = !segment.some((m) => isAIMessage(m));
+        let text;
+        let usage;
+        const close = (rest) => ({ text, usage, ...rest });
+        for (const step of plan.steps) {
+            switch (step.kind) {
+                case "say":
+                    if (spoken.has(step.text))
+                        break;
+                    if (text !== undefined)
+                        return close({ toolCalls: [this.thinkCall("boundary")] });
+                    text = step.text;
+                    break;
+                case "propose":
+                    if (settled.has(step.toolCallId))
+                        break;
+                    return close({ toolCalls: [this.gatedCall(step.toolCallId, step.action, plan.view)] });
+                case "read":
+                    if (settled.has(step.toolCallId))
+                        break;
+                    return close({ toolCalls: [{ id: step.toolCallId, name: "read_file", args: { file_path: step.path } }] });
+                case "usage":
+                    if (!firstCallOfTurn)
+                        break;
+                    usage = addUsage(usage, step.delta);
+                    break;
+                case "hang":
+                    return close({ ends: { kind: "hang" } });
+                case "fail":
+                    return close({ ends: { kind: "fail", error: new Error(step.message) } });
+                case "limit":
+                    return close({ toolCalls: [this.thinkCall("limit")] });
+                case "cancelled":
+                    // Refused at `arrange`; unreachable in a plan that got this far.
+                    throw new Error(`${this.name}: cancelled() reached the engine (arrange should have refused it)`);
+                default: {
+                    const exhaustive = step;
+                    throw new Error(`${this.name}: unknown scenario step ${JSON.stringify(exhaustive)}`);
+                }
+            }
+        }
+        return close({});
+    }
+    /** An ungated, effect-free tool call: the step boundary a LangGraph agent needs between two texts, and the loop a `limit` spins. */
+    thinkCall(why) {
+        return { id: `kit-think-${why}-${++this.mintCounter}`, name: "think", args: { thought: `kit: ${why}` } };
+    }
+    gatedCall(toolCallId, action, view) {
+        switch (action.kind) {
+            case "write":
+                return {
+                    id: toolCallId,
+                    name: "edit_file",
+                    args: {
+                        file_path: action.resource,
+                        old_string: WRITE_LEDGER_MARK,
+                        new_string: `${WRITE_LEDGER_MARK}\n${toolCallId}`,
+                    },
+                };
+            case "shell":
+                return {
+                    id: toolCallId,
+                    name: "execute",
+                    args: { command: `printf '%s\\n' '${toolCallId}' >> '${this.shellLedgerOf(view.sessionId)}' # ${action.resource}` },
+                };
+            case "delete":
+            case "read":
+            case "mcp":
+                // Refused at `arrange`; unreachable in a plan that got this far.
+                throw new Error(`${this.name}: propose(${action.kind}) reached the engine (arrange should have refused it)`);
+            default: {
+                const exhaustive = action.kind;
+                throw new Error(`${this.name}: unknown action kind ${String(exhaustive)}`);
+            }
+        }
+    }
+}
+// ── Reading the conversation ────────────────────────────────────────────────
+/** Every tool call the thread has an answer for — executed, or answered by the gate's denial. */
+function settledToolCallIds(transcript) {
+    const ids = new Set();
+    for (const m of transcript)
+        if (isToolMessage(m))
+            ids.add(m.tool_call_id);
+    return ids;
+}
+/** The messages after the last human message: what this kit turn has said and done so far. */
+function messagesOfThisTurn(transcript) {
+    let start = 0;
+    transcript.forEach((m, i) => {
+        if (isHumanMessage(m))
+            start = i + 1;
+    });
+    return transcript.slice(start);
+}
+function addUsage(total, delta) {
+    const carriesCache = total?.cacheReadTokens !== undefined || delta.cacheReadTokens !== undefined || delta.cacheWriteTokens !== undefined;
+    return {
+        inputTokens: (total?.inputTokens ?? 0) + (delta.inputTokens ?? 0),
+        outputTokens: (total?.outputTokens ?? 0) + (delta.outputTokens ?? 0),
+        ...(carriesCache
+            ? {
+                cacheReadTokens: (total?.cacheReadTokens ?? 0) + (delta.cacheReadTokens ?? 0),
+                cacheWriteTokens: (total?.cacheWriteTokens ?? 0) + (delta.cacheWriteTokens ?? 0),
+            }
+            : {}),
+    };
+}
+/** Create `file` with `content` unless it exists — a ledger keeps what earlier turns appended. */
+function seedFile(file, content) {
+    if (existsSync(file))
+        return;
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, content);
+}
+//# sourceMappingURL=contract-subject.js.map

package/dist/activities/execute-deep-agent/__test-utils__/contract-subject.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract-subject.js","sourceRoot":"","sources":["../../../../src/activities/execute-deep-agent/__test-utils__/contract-subject.ts"],"names":[],"mappings":"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"}

package/dist/activities/execute-deep-agent/__test-utils__/hermetic-deep-agent.d.ts

@@ -0,0 +1,170 @@
+/**
+ * The native (deep-agent) slice of the hermetic activity driver: build the
+ * fixture record, bind the scripted model and the `Config`, run the REAL
+ * `ExecuteDeepAgent` activity under `MockActivityEnvironment` with the REAL
+ * deepagents graph, and hand back what it persisted.
+ *
+ * Layering (the `approval-contract/` + `gateway-substrate.ts` split): everything
+ * harness-agnostic lives in `src/__test-utils__/hermetic-activity.ts` (the
+ * activity environment, the execution record behind the client, the temp
+ * `~/.stigmer`, the ticking clock, the shutdown signal) and its fixtures
+ * (`execution-record-fixture.ts`, `model-registry-fixture.ts`,
+ * `git-workspace-fixture.ts`). This module adds only what is native's: the
+ * scripted model as the one LLM (`scripted-model.ts`, reached through the
+ * `shared/model-client.ts` double), the native `Config` slice with its
+ * checkpointer, the per-scenario reset of module caches and of the session's
+ * durable state, and the production wire shape of the activity input.
+ *
+ * What the two `vi.mock` calls a scenario file must carry look like — they are
+ * hoisted by vitest and so cannot live here:
+ *
+ * ```ts
+ * vi.mock("../../../../shared/model-client.js", async () =>
+ *   (await import("../../__test-utils__/scripted-model-module.js")).scriptedModelClientModule());
+ * vi.mock("../../../../client/stigmer-client.js", async () =>
+ *   (await import("../../../../__test-utils__/hermetic-activity.js")).hermeticStigmerClientModule());
+ * ```
+ *
+ * Two facts about this harness the driver encodes, both read from production:
+ *
+ *  - `thread_id` is `thread-{sessionId}` on EVERY invocation, the first
+ *    included (`invoke-agent-execution.ts` runs `EnsureThread` once and passes
+ *    the same id to `firstInvoke` and every `reinvoke`; `ensure-thread.ts`
+ *    derives it from the session). Cursor's driver sends `""` on a first turn
+ *    because Cursor's engine mints its own id; copying that here would key the
+ *    sqlite checkpoint on `""` in turn 1 and look it up under `thread-…` in
+ *    turn 2. A scenario overrides the default only to stage the empty-id edge.
+ *  - The `memory` checkpointer is recreated empty per invocation
+ *    (`checkpointer/factory.ts`), so a HITL reinvocation REPLAYS the graph; the
+ *    `sqlite` checkpointer keys one file per session under `~/.stigmer`, so a
+ *    reinvocation RESUMES from the interrupt — the durable posture with no
+ *    network. A scenario picks one; the HITL arms record both.
+ *
+ * The ONE knowledge of production this driver holds is `activityFactory`: how
+ * to obtain the `ExecuteDeepAgent` function from a `Config`. Since S3 M2a it
+ * is the harness registry's: the native adapter booted and bound to its
+ * byte-pinned activity name through `createHarnessActivities`, exactly the
+ * way the composition roots bind it since S3 M2b through `harness-adapters.ts`
+ * (and the way the Cursor driver binds its own, `hermetic-cursor.ts`). The
+ * orchestrator this adapter replaced (`index.ts`, `setup.ts`) was deleted at
+ * M2b; the goldens moved once, with the M2a flip, each hunk quoted with its
+ * ruling in its test's header (Q-M2a-1), and the switch of the roots moved
+ * none (Q-M2b-4).
+ *
+ * `boot` registers the deepagents harness profiles as production does
+ * (S3 M2a F-M2a-14: the orchestrator-driven runs never did, so deepagents
+ * auto-injected its ungated `general-purpose` sub-agent into every M0
+ * scenario; the scripted model never delegated to it).
+ *
+ * Determinism beyond S0's: the clock ticks once per model turn (the scripted
+ * model's `onTurn`), so status timestamps and the persist cadence land on the
+ * same instants every run; a scenario's interruption (pause, worker shutdown)
+ * is scheduled on a model turn through the same hook, never on a timer.
+ */
+import type { Config } from "../../../config.js";
+import type { StigmerClient } from "../../../client/stigmer-client.js";
+import type { ExecuteActivityInput } from "../../../shared/activity-input.js";
+import { ExecutionRecord, ScriptedClock, type ActivityInvocation, type HermeticEnvironment, type InvocationControls } from "../../../__test-utils__/hermetic-activity.js";
+import { type ExecutionRecordOptions } from "../../../__test-utils__/execution-record-fixture.js";
+import { ScriptedModel, type ScriptSelector, type ScriptedTurnInfo } from "./scripted-model.js";
+export declare const FIXTURE: {
+    readonly org: "hermetic-org";
+    readonly executionId: "aex_hermetic_0001";
+    readonly sessionId: "ses_hermetic_0001";
+    readonly agentInstanceId: "ain_hermetic_0001";
+    readonly agentId: "agt_hermetic_0001";
+    readonly agentName: "hermetic-agent";
+    /** The pinned model; in the registry document as the native entry. */
+    readonly model: "claude-haiku-4.5";
+    /** The LangGraph thread id the control plane sends on every invocation (`ensure-thread.ts`). */
+    readonly threadId: "thread-ses_hermetic_0001";
+};
+/** The record's knobs; the ids and the default model are this harness's fixture. */
+export type DeepAgentRecordOptions = Omit<ExecutionRecordOptions, "ids">;
+/** The four resources of one execution, wired by id into a chain, under the native fixture ids. */
+export declare function deepAgentExecutionRecord(options: DeepAgentRecordOptions): ExecutionRecord;
+export type HermeticCheckpointer = "memory" | "sqlite";
+/** The OSS/local runner posture: no proxy, local mode, the scenario's checkpointer. */
+export declare function hermeticDeepAgentConfig(env: HermeticEnvironment, checkpointerType: HermeticCheckpointer): Config;
+/**
+ * The primary workspace directory a session with NO workspace entries runs in
+ * (`session-root.ts`: `<workspaceRootDir>/sessions/<sessionId>`). A scenario
+ * seeds the files its script reads here.
+ */
+export declare function sessionWorkspaceDir(env: HermeticEnvironment): string;
+/** The `ExecuteDeepAgent` function as the runner serves it: the typed object OR the legacy positional pair. */
+export type ExecuteDeepAgentFn = (arg0: ExecuteActivityInput | string, arg1?: string) => Promise<unknown>;
+/** How the driver obtains the activity from a `Config` — the one seam M2 flips. */
+export type ActivityFactory = (config: Config) => Promise<ExecuteDeepAgentFn>;
+/**
+ * The adapter through the registry: `createDeepAgentAdapter()` booted on the
+ * scenario's config, bound to `ExecuteDeepAgent` by `createHarnessActivities`
+ * over the turn runtime. Imported lazily so the scenario file's `vi.mock`
+ * declarations are in force before the engine slice loads the model client
+ * and before the registry loads the `StigmerClient` module.
+ */
+export declare const runtimeActivityFactory: ActivityFactory;
+/**
+ * Drop every module-level cache the harness keeps across invocations and
+ * every durable trace the session left behind (its sqlite checkpoint, its
+ * session workspace), so a scenario starts where a new session starts.
+ * Called at the START of a scenario, never between its invocations: a HITL
+ * scenario relies on the sqlite checkpoint surviving from turn 1 into turn 2
+ * exactly as it does in a live runner.
+ */
+export declare function resetDeepAgentScenarioState(env: HermeticEnvironment): void;
+/** One scenario: the record, the one LLM, the runner it runs on, and the invocation in flight. */
+export declare class DeepAgentScenario {
+    readonly env: HermeticEnvironment;
+    readonly clock: ScriptedClock;
+    readonly record: ExecutionRecord;
+    /** The runner this scenario runs on: the OSS posture plus the scenario's knobs. */
+    readonly config: Config;
+    /** The controls of the invocation in flight; set by {@link runDeepAgentTurn} before the activity starts. */
+    controls: InvocationControls | undefined;
+    readonly model: ScriptedModel;
+    constructor(env: HermeticEnvironment, clock: ScriptedClock, record: ExecutionRecord, 
+    /** The runner this scenario runs on: the OSS posture plus the scenario's knobs. */
+    config: Config, script: ScriptSelector, onTurn: DeepAgentScenarioOptions["onTurn"]);
+}
+export interface DeepAgentScenarioOptions {
+    readonly env: HermeticEnvironment;
+    readonly clock: ScriptedClock;
+    readonly record: ExecutionRecord;
+    /** The per-role script the one LLM plays (`scripted-model.ts`). */
+    readonly script: ScriptSelector;
+    /** `memory` (replay on reinvocation; the OSS default) or `sqlite` (durable resume). Defaults to `memory`. */
+    readonly checkpointer?: HermeticCheckpointer;
+    /**
+     * Runs on every model turn after the clock ticks, with the in-flight
+     * invocation's controls: where a scenario stages a user pause or a worker
+     * shutdown at a chosen role and round.
+     */
+    readonly onTurn?: (info: ScriptedTurnInfo, controls: InvocationControls) => void | Promise<void>;
+    /**
+     * Control-plane facets the scenario opts INTO, or faults it injects, over
+     * the record's everyday answers (`ExecutionRecord.client`): a rejecting
+     * `getAgent` is how a blueprint-resolution failure is staged.
+     */
+    readonly clientOverrides?: Partial<StigmerClient>;
+    /** Runner knobs over {@link hermeticDeepAgentConfig}: the workspace-lock window, for one. */
+    readonly config?: Partial<Config>;
+}
+/** Bind the record and the model for a scenario; resets the harness's module and session state first. */
+export declare function beginDeepAgentScenario(options: DeepAgentScenarioOptions): DeepAgentScenario;
+export interface DeepAgentTurnOptions {
+    /** The HITL cycle index (0 on the first turn); mints the change-set id. */
+    readonly turnSeq?: number;
+    /** Overrides the production thread id ({@link FIXTURE.threadId}) — only to stage the empty-id edge. */
+    readonly threadId?: string;
+    /** Drive the legacy positional `(executionId, threadId)` wire shape instead of the typed object. */
+    readonly positional?: boolean;
+    readonly activityFactory?: ActivityFactory;
+    readonly onControls?: (controls: InvocationControls) => void;
+}
+/**
+ * Run ONE `ExecuteDeepAgent` invocation for the scenario. Built per invocation
+ * (the factory constructs its client, which is the one bound at
+ * `beginDeepAgentScenario`).
+ */
+export declare function runDeepAgentTurn(scenario: DeepAgentScenario, options?: DeepAgentTurnOptions): Promise<ActivityInvocation>;