@stigmer/runner 3.14.0 → 3.15.0

package/dist/.build-fingerprint

@@ -1 +1 @@
-{"hash":"7c856383e6ad237f","builtAt":"2026-09-10T09:47:17.422Z","fileCount":293}
+{"hash":"2ac96be487c6ce2c","builtAt":"2026-09-13T09:42:32.154Z","fileCount":325}

package/dist/__test-utils__/execution-record-fixture.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The four resources of one execution, wired by id into the chain the turn
+ * runtime resolves (`execution.spec.sessionId` → `session.spec.
+ * agentInstanceId` → `agentInstance.spec.agentId` → the agent), as an
+ * `ExecutionRecord` the hermetic client answers from.
+ *
+ * Harness-agnostic: the record is the control plane's, and the runtime's
+ * phases read it the same way whatever engine runs the turn. A harness's
+ * driver supplies its own fixture ids and model (`execute-cursor/__test-
+ * utils__/hermetic-cursor.ts` `cursorExecutionRecord`); the runtime's own
+ * tests use the defaults. Ids are fixed so goldens are readable and
+ * byte-stable.
+ */
+import type { WorkspaceEntry } from "@stigmer/protos/ai/stigmer/agentic/session/v1/workspace_pb";
+import { ExecutionRecord, type ExecutionRecordInput } from "./hermetic-activity.js";
+/** The ids a record's four resources carry. */
+export interface ExecutionRecordIds {
+    readonly org: string;
+    readonly executionId: string;
+    readonly sessionId: string;
+    readonly agentInstanceId: string;
+    readonly agentId: string;
+    readonly agentName: string;
+}
+export declare const DEFAULT_RECORD_IDS: ExecutionRecordIds;
+export interface ExecutionRecordOptions {
+    /** The user's message for this execution. */
+    readonly message: string;
+    /** The agent's instructions (system prompt body). */
+    readonly instructions?: string;
+    /** Session workspace entries (a `local_path` entry turns on capture mode). */
+    readonly workspaceEntries?: WorkspaceEntry[];
+    /** The requested model; the pinned fixture model when omitted. */
+    readonly modelName?: string;
+    readonly autoApproveAll?: boolean;
+    /**
+     * `ExecutionConfig.max_cost_usd`: the per-message cost budget the runtime
+     * enforces as a hard stop (cost-guard.ts). Omitted or 0 = no cap, the
+     * proto's default. Priced against the registry fixture's round numbers, so
+     * a scenario can state its overrun exactly (600 000 input tokens = $0.60).
+     */
+    readonly maxCostUsd?: number;
+    /** The control plane's STOP lever; see `ExecutionRecordInput.controlSignal`. */
+    readonly controlSignal?: ExecutionRecordInput["controlSignal"];
+    readonly ids?: ExecutionRecordIds;
+}
+export declare function executionRecordFixture(options: ExecutionRecordOptions): ExecutionRecord;

package/dist/__test-utils__/execution-record-fixture.js

@@ -0,0 +1,68 @@
+/**
+ * The four resources of one execution, wired by id into the chain the turn
+ * runtime resolves (`execution.spec.sessionId` → `session.spec.
+ * agentInstanceId` → `agentInstance.spec.agentId` → the agent), as an
+ * `ExecutionRecord` the hermetic client answers from.
+ *
+ * Harness-agnostic: the record is the control plane's, and the runtime's
+ * phases read it the same way whatever engine runs the turn. A harness's
+ * driver supplies its own fixture ids and model (`execute-cursor/__test-
+ * utils__/hermetic-cursor.ts` `cursorExecutionRecord`); the runtime's own
+ * tests use the defaults. Ids are fixed so goldens are readable and
+ * byte-stable.
+ */
+import { create } from "@bufbuild/protobuf";
+import { AgentExecutionSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { AgentExecutionSpecSchema, ExecutionConfigSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/spec_pb";
+import { SessionSchema } from "@stigmer/protos/ai/stigmer/agentic/session/v1/api_pb";
+import { SessionSpecSchema } from "@stigmer/protos/ai/stigmer/agentic/session/v1/spec_pb";
+import { AgentSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import { AgentSpecSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
+import { AgentInstanceSchema } from "@stigmer/protos/ai/stigmer/agentic/agentinstance/v1/api_pb";
+import { AgentInstanceSpecSchema } from "@stigmer/protos/ai/stigmer/agentic/agentinstance/v1/spec_pb";
+import { ApiResourceMetadataSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/metadata_pb";
+import { ExecutionRecord } from "./hermetic-activity.js";
+import { FIXTURE_MODEL } from "./model-registry-fixture.js";
+export const DEFAULT_RECORD_IDS = {
+    org: "hermetic-org",
+    executionId: "aex_hermetic_0001",
+    sessionId: "ses_hermetic_0001",
+    agentInstanceId: "ain_hermetic_0001",
+    agentId: "agt_hermetic_0001",
+    agentName: "hermetic-agent",
+};
+export function executionRecordFixture(options) {
+    const ids = options.ids ?? DEFAULT_RECORD_IDS;
+    const execution = create(AgentExecutionSchema, {
+        metadata: create(ApiResourceMetadataSchema, { id: ids.executionId, org: ids.org, name: ids.executionId }),
+        spec: create(AgentExecutionSpecSchema, {
+            sessionId: ids.sessionId,
+            message: options.message,
+            autoApproveAll: options.autoApproveAll ?? false,
+            executionConfig: create(ExecutionConfigSchema, {
+                modelName: options.modelName ?? FIXTURE_MODEL,
+                maxCostUsd: options.maxCostUsd ?? 0,
+            }),
+        }),
+    });
+    const session = create(SessionSchema, {
+        metadata: create(ApiResourceMetadataSchema, { id: ids.sessionId, org: ids.org, name: ids.sessionId }),
+        spec: create(SessionSpecSchema, {
+            agentInstanceId: ids.agentInstanceId,
+            workspaceEntries: options.workspaceEntries ?? [],
+        }),
+    });
+    const agentInstance = create(AgentInstanceSchema, {
+        metadata: create(ApiResourceMetadataSchema, { id: ids.agentInstanceId, org: ids.org, name: ids.agentInstanceId }),
+        spec: create(AgentInstanceSpecSchema, { agentId: ids.agentId }),
+    });
+    const agent = create(AgentSchema, {
+        metadata: create(ApiResourceMetadataSchema, { id: ids.agentId, org: ids.org, name: ids.agentName }),
+        spec: create(AgentSpecSchema, {
+            description: "Hermetic fixture agent",
+            instructions: options.instructions ?? "You are the hermetic fixture agent. Answer briefly.",
+        }),
+    });
+    return new ExecutionRecord({ execution, session, agentInstance, agent, controlSignal: options.controlSignal });
+}
+//# sourceMappingURL=execution-record-fixture.js.map

package/dist/__test-utils__/execution-record-fixture.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution-record-fixture.js","sourceRoot":"","sources":["../../src/__test-utils__/execution-record-fixture.ts"],"names":[],"mappings":"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"}

package/dist/__test-utils__/harness-contract/types.d.ts

@@ -0,0 +1,166 @@
+/**
+ * The test-facing seam of the harness contract kit.
+ *
+ * `HarnessAdapter.runTurn(input, sink)` gives a test no way to make the
+ * engine DO anything: propose a gated action, emit usage, hang, fail. The
+ * approval-contract kit met the same problem with `GatewaySubstrate` — a
+ * small interface each real substrate adapts so one invariant catalog can
+ * drive all of them. This is that seam for harnesses: a
+ * {@link HarnessContractSubject} owns the ENGINE (what the next turn will
+ * do), and the kit owns everything the runtime would own (the sink, the
+ * `TurnInput`, the state id threading, the reinvocation).
+ *
+ * The scenario vocabulary is deliberately small and engine-neutral: it says
+ * what the kit needs to PROVOKE, never how an engine behaves. The scripted
+ * fake consumes it directly; a real harness's subject translates it onto that
+ * harness's own double (the Cursor subject onto the scripted `@cursor/sdk`
+ * agent of `execute-cursor/__test-utils__/`). One vocabulary, not one per
+ * engine, so the kit cannot drift from what the fake can do.
+ *
+ * Gated actions reuse `ProposedAction` from `approval-contract/types.ts`, the
+ * taxonomy-free action every enforcement substrate already translates, so the
+ * two kits speak of the same logical side effect and neither restates the
+ * HITL taxonomy.
+ */
+import type { ApprovalAction } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import type { Config } from "../../config.js";
+import type { HarnessName } from "../../harness/registry.js";
+import type { FailureSurface, HarnessAdapter, UsageDelta } from "../../harness/types.js";
+import type { ProposedAction } from "../approval-contract/types.js";
+import type { TurnInputFixtureOverrides } from "../turn-input-fixture.js";
+/**
+ * One thing the engine does during a turn. A turn plays its steps in order
+ * and ends `completed` when none is left, unless a step ends it first.
+ *
+ *  - `say`: the engine emits assistant text (a transcript row).
+ *  - `propose`: the engine reaches a gated side effect identified by
+ *    `toolCallId`. Undecided → the turn ends `awaiting_approval` and later
+ *    steps do not run; APPROVE → the effect runs once and the turn continues;
+ *    REJECT / SKIP → the effect never runs and the turn continues. WHICH
+ *    kinds a harness gates is the harness's policy and the workspace's
+ *    posture: a `shell` is gated by every harness in every posture; a `write`
+ *    is gated only outside apply-then-review capture (a git tree, or artifact
+ *    storage), so an arm that must gate on every subject proposes a `shell`.
+ *  - `read`: the engine performs an UNGATED read of `path` — a tool-call row
+ *    that runs at once, never pauses, and is the discrete event every harness
+ *    flushes a persist on (the lever an arm pulls when it needs the control
+ *    plane to answer a mid-turn persist).
+ *  - `usage`: the engine reports one turn's token counts.
+ *  - `hang`: the engine makes no further progress until told to stop. The
+ *    step that the stop-signal invariants and the runtime's stall watchdog
+ *    are built around; it must be parked on the signal, never on a timer.
+ *  - `fail`: the engine fails with a message the adapter can name; the turn
+ *    ends `failed` on the given surface (`engine` unless the scenario says
+ *    otherwise — the runtime's three failure copies are its own invariant).
+ *  - `cancelled`: the engine ends its own run cancelled with nothing to
+ *    wait for (an SDK-side cancel); the turn ends `cancelled`.
+ */
+export type ScenarioStep = {
+    readonly kind: "say";
+    readonly text: string;
+} | {
+    readonly kind: "propose";
+    readonly toolCallId: string;
+    readonly action: ProposedAction;
+} | {
+    readonly kind: "read";
+    readonly toolCallId: string;
+    readonly path: string;
+} | {
+    readonly kind: "usage";
+    readonly delta: UsageDelta;
+} | {
+    readonly kind: "hang";
+} | {
+    readonly kind: "fail";
+    readonly message: string;
+    readonly surface: FailureSurface;
+} | {
+    readonly kind: "cancelled";
+};
+/** One turn's worth of engine behaviour. */
+export type TurnScenario = readonly ScenarioStep[];
+/** Step builders — the vocabulary a kit invariant reads as. */
+export declare const scenario: {
+    readonly say: (text: string) => ScenarioStep;
+    readonly propose: (toolCallId: string, action: ProposedAction) => ScenarioStep;
+    readonly read: (toolCallId: string, path: string) => ScenarioStep;
+    readonly usage: (delta: UsageDelta) => ScenarioStep;
+    readonly hang: () => ScenarioStep;
+    readonly fail: (message: string, surface?: FailureSurface) => ScenarioStep;
+    readonly cancelled: () => ScenarioStep;
+};
+/**
+ * What the engine can know about the turn it is about to play, handed to the
+ * subject with every {@link HarnessContractSubject.arrange}: which execution
+ * and session it serves (a real engine is per session — its handle is parked
+ * under the session, its workspace and hook state live under the session —
+ * so a subject arranges THAT session's engine, never "the next turn"), and
+ * the approval decisions the prompt will carry (the runtime's
+ * `approvalDecisionsOf` over the persisted status — the one reader both
+ * drivers call). A subject whose engine cannot re-run a settled action, or
+ * whose model is told not to perform a skipped one, reads its decision here
+ * instead of parsing the prompt for it.
+ */
+export interface EngineView {
+    readonly executionId: string;
+    readonly sessionId: string;
+    readonly approvalDecisions: ReadonlyMap<string, ApprovalAction>;
+}
+/**
+ * What a subject may say about the record its engine is handed, laid UNDER
+ * the driver's own facts: the five it threads (`executionId`, `threadId`,
+ * `turnSeq`, `sessionId`, `approvalDecisions`) and the persisted status it
+ * seeds are the kit's bookkeeping and never a subject's to state.
+ */
+export type SubjectInputOverrides = Omit<TurnInputFixtureOverrides, "executionId" | "threadId" | "turnSeq" | "sessionId" | "approvalDecisions" | "persistedStatus">;
+/**
+ * One adapter under test, with the engine controls the kit needs. Adapters
+ * translate scenarios into their own double's drives and report what the
+ * double observed; they never reimplement contract behaviour.
+ *
+ * The kit owns the adapter's lifetime: it boots the adapter before the first
+ * turn and shuts it down after the last (the registry boots every adapter
+ * before the worker polls, and a real adapter refuses a turn before boot).
+ * The exported assertion functions therefore REQUIRE a booted adapter.
+ */
+export interface HarnessContractSubject {
+    /** Stable name, used in suite titles and every assertion message. */
+    readonly name: string;
+    /** The registry row this adapter fills; the runtime half selects the activity by it. */
+    readonly harness: HarnessName;
+    /** The adapter under test — the real implementation of the contract. */
+    readonly adapter: HarnessAdapter;
+    /** What `adapter.boot` needs. The subject knows its adapter's fields; the kit does not. */
+    readonly config: Config;
+    /**
+     * Arrange the engine so that the NEXT `runTurn` for `view.sessionId` plays
+     * `turn` — REPLACING whatever was arranged for that session and not yet
+     * played (a turn interrupted before its engine ran leaves no stale script
+     * behind). Called by the kit before every `runTurn`, including a
+     * reinvocation (the engine re-reaches the same gated call on resume, so the
+     * same proposal is arranged again).
+     */
+    arrange(turn: TurnScenario, view: EngineView): void;
+    /**
+     * What this engine needs the record to say beyond the driver's facts (the
+     * model the adapter validates, the workspace its gate installs into). A
+     * subject whose engine reads nothing of the record omits it.
+     */
+    inputOverrides?(view: EngineView): SubjectInputOverrides;
+    /**
+     * Resolves the next time a turn parks on a `hang` step — the moment the
+     * kit stops a turn from the outside, and the moment the runtime half
+     * delivers a cancellation, a drain or the clock tick that trips the stall
+     * watchdog. A real engine reaches its hang only after real setup (file
+     * writes, catalog fetches); a stop delivered any earlier would land in that
+     * setup and prove nothing about the hang. Never a timer.
+     */
+    whenHanging(): Promise<void>;
+    /**
+     * How many times the side effect behind `toolCallId` actually ran, as the
+     * subject's double observed it. The safety-critical observable; zero for an
+     * id the engine never reached.
+     */
+    executionCount(toolCallId: string): number;
+}

package/dist/__test-utils__/harness-contract/types.js

@@ -0,0 +1,49 @@
+/**
+ * The test-facing seam of the harness contract kit.
+ *
+ * `HarnessAdapter.runTurn(input, sink)` gives a test no way to make the
+ * engine DO anything: propose a gated action, emit usage, hang, fail. The
+ * approval-contract kit met the same problem with `GatewaySubstrate` — a
+ * small interface each real substrate adapts so one invariant catalog can
+ * drive all of them. This is that seam for harnesses: a
+ * {@link HarnessContractSubject} owns the ENGINE (what the next turn will
+ * do), and the kit owns everything the runtime would own (the sink, the
+ * `TurnInput`, the state id threading, the reinvocation).
+ *
+ * The scenario vocabulary is deliberately small and engine-neutral: it says
+ * what the kit needs to PROVOKE, never how an engine behaves. The scripted
+ * fake consumes it directly; a real harness's subject translates it onto that
+ * harness's own double (the Cursor subject onto the scripted `@cursor/sdk`
+ * agent of `execute-cursor/__test-utils__/`). One vocabulary, not one per
+ * engine, so the kit cannot drift from what the fake can do.
+ *
+ * Gated actions reuse `ProposedAction` from `approval-contract/types.ts`, the
+ * taxonomy-free action every enforcement substrate already translates, so the
+ * two kits speak of the same logical side effect and neither restates the
+ * HITL taxonomy.
+ */
+/** Step builders — the vocabulary a kit invariant reads as. */
+export const scenario = {
+    say(text) {
+        return { kind: "say", text };
+    },
+    propose(toolCallId, action) {
+        return { kind: "propose", toolCallId, action };
+    },
+    read(toolCallId, path) {
+        return { kind: "read", toolCallId, path };
+    },
+    usage(delta) {
+        return { kind: "usage", delta };
+    },
+    hang() {
+        return { kind: "hang" };
+    },
+    fail(message, surface = "engine") {
+        return { kind: "fail", message, surface };
+    },
+    cancelled() {
+        return { kind: "cancelled" };
+    },
+};
+//# sourceMappingURL=types.js.map

package/dist/__test-utils__/harness-contract/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/__test-utils__/harness-contract/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAiDH,+DAA+D;AAC/D,MAAM,CAAC,MAAM,QAAQ,GAAG;IACtB,GAAG,CAAC,IAAY;QACd,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IAC/B,CAAC;IACD,OAAO,CAAC,UAAkB,EAAE,MAAsB;QAChD,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC;IACjD,CAAC;IACD,IAAI,CAAC,UAAkB,EAAE,IAAY;QACnC,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC;IAC5C,CAAC;IACD,KAAK,CAAC,KAAiB;QACrB,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAClC,CAAC;IACD,IAAI;QACF,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IAC1B,CAAC;IACD,IAAI,CAAC,OAAe,EAAE,UAA0B,QAAQ;QACtD,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;IAC5C,CAAC;IACD,SAAS;QACP,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC;IAC/B,CAAC;CACO,CAAC"}

package/dist/__test-utils__/hermetic-activity.d.ts

@@ -0,0 +1,268 @@
+/**
+ * Hermetic activity driver — run a REAL runner activity end to end with no
+ * network, no credentials, and no live Temporal worker, and read back every
+ * status it persisted.
+ *
+ * Why this exists: the runner's activities (`ExecuteCursor`, `ExecuteDeepAgent`)
+ * are the wire contract the control plane's workflow keys on — the phases they
+ * persist, the copy they write, whether they RETURN a slim status or THROW
+ * `CancelledFailure`. Refactoring them safely needs goldens recorded through the
+ * activity whole, not through its modules one at a time. The native harness
+ * tests already run their activity hermetically by mocking three modules at the
+ * boundary (`execute-deep-agent/__tests__/{index,hitl-*,sequential-gate-resume}.test.ts`);
+ * this module is that convention made reusable, harness-agnostic, and driven by
+ * the framework's own activity environment instead of a hand-written stand-in.
+ *
+ * What is generic here and what is not: everything an activity touches that is
+ * NOT the vendor SDK — the Temporal `Context`, the control-plane client, the
+ * runner-owned `~/.stigmer` tree, artifact storage, the model registry, the
+ * clock, the worker-shutdown signal — is set up here. The vendor SDK double
+ * belongs to the harness (`activities/execute-cursor/__test-utils__/scripted-*.ts`),
+ * the same split as `approval-contract/` (runner-wide kit) + each harness's
+ * `gateway-substrate.ts`.
+ *
+ * Three substitutions, and why each is shaped the way it is:
+ *
+ *  1. `Context.current()` — `MockActivityEnvironment` from `@temporalio/testing`,
+ *     ONE PER INVOCATION. It gives the activity a real `Context` (real
+ *     `cancellationSignal`, real `heartbeat()` surfaced as events, real
+ *     `CancelledFailure` on throw). The native tests' stand-in mints a fresh
+ *     `AbortController` on every `Context.current()` call and so cannot drive a
+ *     pause; production hands each attempt one `Context`, and so does this. The
+ *     environment's documented caveat — once cancelled it stays cancelled — is
+ *     why it is per invocation and never shared.
+ *
+ *  2. `StigmerClient` — the test file mocks the module (`vi.mock` is hoisted and
+ *     must live in the test file; see {@link hermeticStigmerClientModule}) and
+ *     the constructor hands back whatever client {@link bindHermeticClient} bound
+ *     for the current run. The client is `mockStigmerClient` over an
+ *     {@link ExecutionRecord}: `updateStatus` writes back into the record the way
+ *     the server would, so a REINVOCATION (`threadId` set) reads the transcript
+ *     the first invocation persisted — the resume path runs on real data, not on
+ *     a hand-built status.
+ *
+ *  3. The environment — a temp `HOME` (the runner-owned `~/.stigmer` tree,
+ *     `platform-dir.ts` reads `process.env.HOME`), a temp workspace root, local
+ *     artifact storage in a temp dir, and the HITL fingerprint secret pinned by
+ *     env var (`fingerprint-secret.ts` falls back to `randomBytes` — the ONE
+ *     source of randomness on the activity path — and memoizes on first call, so
+ *     the pin must precede the first invocation in the process).
+ *
+ * Determinism: the clock is faked for `Date` ONLY (`vi.useFakeTimers({ toFake:
+ * ["Date"] })`) and TICKS — the harness double advances it a fixed quantum per
+ * script step through {@link ScriptedClock}. Frozen time would make
+ * `delta-enricher.ts`'s persist debounce (`Date.now() - lastPersistTime`) never
+ * elapse and silently skip the mid-stream persist path production always runs;
+ * a ticking clock runs the same path and lands on the same instants every run.
+ * Timers stay real so the periodic heartbeat and the stall watchdog behave.
+ *
+ * Not in scope: this module never edits a production module and never
+ * normalizes output. If a golden is not byte-stable, the volatile source is
+ * controlled at its origin or the surprise is escalated — never redacted here.
+ */
+import { CancelledFailure } from "@temporalio/activity";
+import { type AgentExecution, type AgentExecutionStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { ApprovalAction, ExecutionControlSignal, ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import type { ToolCall } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import { type Session } from "@stigmer/protos/ai/stigmer/agentic/session/v1/api_pb";
+import type { Agent } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import type { AgentInstance } from "@stigmer/protos/ai/stigmer/agentic/agentinstance/v1/api_pb";
+import type { StigmerClient } from "../client/stigmer-client.js";
+/**
+ * The four resources the activity's blueprint chain reads
+ * (`execution.spec.sessionId -> session.spec.agentInstanceId ->
+ * agentInstance.spec.agentId -> agent`) plus the status the server would hold.
+ */
+export interface ExecutionRecordInput {
+    readonly execution: AgentExecution;
+    readonly session: Session;
+    readonly agentInstance: AgentInstance;
+    readonly agent: Agent;
+    /**
+     * What `UpdateStatus` answers for each FULL status write — the platform's
+     * STOP lever (`ExecutionControlSignal`), decided by the control plane per
+     * write and read by the harness stream loop on its mid-stream persist.
+     * Evaluated AFTER the write lands, on the snapshot just persisted, so a
+     * policy can key on the transcript ("stop once the first assistant message
+     * is in"). Defaults to UNSPECIFIED: keep going.
+     */
+    readonly controlSignal?: (status: AgentExecutionStatus) => ExecutionControlSignal;
+}
+/**
+ * An in-memory stand-in for the server's execution row, with the TWO merge
+ * rules and the ONE control lever the activity depends on, and no others:
+ *
+ *  - A status whose phase is UNSPECIFIED is a setup-progress report
+ *    (`reportSetupProgress`): the server keeps `setup_progress` and leaves the
+ *    phase and transcript alone. Modelled as: record the label, change nothing else.
+ *  - Any other status replaces the held status wholesale (the runner is the
+ *    writer of the transcript; the server's own field-ownership merge — approval
+ *    fields it owns — is exercised by the test SETTING `approvalAction` on the
+ *    record between invocations, exactly as `SubmitApproval` would).
+ *  - Every `UpdateStatus` answers a control signal ({@link ExecutionRecordInput.controlSignal});
+ *    the server's STOP is the one instruction that travels back to the runner
+ *    on this channel, and it is a server decision, so it is modelled here and
+ *    not by the test hand-writing the client.
+ *
+ * Every persisted status is also kept in order (`persisted`) so a test can
+ * assert the phase sequence the activity wrote, independent of the final state.
+ */
+export declare class ExecutionRecord {
+    readonly execution: AgentExecution;
+    readonly session: Session;
+    readonly agentInstance: AgentInstance;
+    readonly agent: Agent;
+    private readonly controlSignal;
+    /** Every `updateStatus` payload, in order, snapshotted at write time. */
+    readonly persisted: AgentExecutionStatus[];
+    /** Setup-progress labels reported before the stream started, in order. */
+    readonly setupProgress: string[];
+    /**
+     * Every `updateSession` payload, in order (the `harness_state_id` write-back),
+     * snapshotted at write time: the activity re-binds the SAME session object on
+     * a fresh-agent recovery, so a live reference would show the second id twice.
+     */
+    readonly sessionUpdates: Session[];
+    constructor(input: ExecutionRecordInput);
+    get executionId(): string;
+    /** The status the server would currently hold (what `getExecution` returns). */
+    get status(): AgentExecutionStatus | undefined;
+    /** The last FULL status written (phase set), or undefined if none yet. */
+    get lastFullStatus(): AgentExecutionStatus | undefined;
+    /**
+     * The ORDERED, DISTINCT phases the activity persisted — the deterministic
+     * shape of the persist cadence. The COUNT of persists depends on the
+     * debounce timer and is deliberately not exposed as an assertion surface.
+     */
+    get persistedPhases(): ExecutionPhase[];
+    /** Every tool call on the held transcript (top-level messages), in order. */
+    toolCalls(): ToolCall[];
+    /** The tool calls currently paused for a decision. */
+    waitingToolCalls(): ToolCall[];
+    /**
+     * What the server's `SubmitApproval` does to the row: record the decision on
+     * the tool call the runner wrote. The runner owns `status`; the server owns
+     * `approval_action` (field ownership, 005 mandate 2) — so this is the ONE
+     * place a test writes it, and the status stays WAITING_APPROVAL until the
+     * resumed turn runs the tool, exactly as in production.
+     */
+    decideWaitingToolCalls(action: ApprovalAction, decidedAt: string): number;
+    /**
+     * Apply one `UpdateStatus` write and answer the control signal the server
+     * would. A setup-progress report never carries a signal (the runner ignores
+     * the response there; the server has nothing to say about a label).
+     */
+    applyStatusUpdate(status: AgentExecutionStatus): ExecutionControlSignal;
+    /**
+     * The control-plane client the activity sees: every read answers from this
+     * record; every write lands in it. Reads the activity makes for optional
+     * facets (execution context, channels, skills) answer the everyday shape —
+     * NOT_FOUND for the execution context (an execution with no env vars), no
+     * channels, no scoped token (the OSS/local posture) — so a scenario opts INTO
+     * a facet by overriding.
+     */
+    client(overrides?: Partial<StigmerClient>): StigmerClient;
+}
+/**
+ * Bind the client the mocked `StigmerClient` constructor hands out for the
+ * current run. Called by the harness driver immediately before invoking the
+ * activity factory (`createCursorActivities(config)` constructs its client
+ * inside the factory, so the bind must precede the factory call).
+ */
+export declare function bindHermeticClient(client: StigmerClient): void;
+/**
+ * The factory a test passes to `vi.mock(".../client/stigmer-client.js", ...)`.
+ * `vi.mock` is hoisted and must appear in the test file itself; the factory can
+ * `await import()` this module. Usage:
+ *
+ * ```ts
+ * vi.mock("../../../../client/stigmer-client.js", async () =>
+ *   (await import("../../../../__test-utils__/hermetic-activity.js")).hermeticStigmerClientModule(),
+ * );
+ * ```
+ */
+export declare function hermeticStigmerClientModule(): {
+    StigmerClient: new () => StigmerClient;
+};
+export interface HermeticEnvironment {
+    /** The temp `HOME` (the runner's `~/.stigmer` lands under it). */
+    readonly home: string;
+    /** The temp workspace root (`config.workspaceRootDir`). */
+    readonly workspaceRootDir: string;
+    /** The temp local artifact store (`LOCAL_ARTIFACT_PATH`). */
+    readonly artifactPath: string;
+    /** Restore every env var and remove the temp tree. Idempotent. */
+    dispose(): void;
+}
+/**
+ * Create the temp tree and pin the env vars. Call once per test FILE (in
+ * `beforeAll`) — the fingerprint secret is memoized per process on first use,
+ * and vitest isolates files in forks, so per-file is the natural unit.
+ */
+export declare function createHermeticEnvironment(): HermeticEnvironment;
+/**
+ * A deterministic, TICKING `Date`. Only `Date` is faked; timers stay real (the
+ * periodic heartbeat, the stall watchdog, `withTimeout` all need them). The
+ * harness double calls {@link ScriptedClock.tick} once per script step, so
+ * every `Date.now()`-based decision on the activity path (status timestamps,
+ * the enricher's persist debounce, cache TTLs) sees the same instants run after
+ * run and runs the same branches production runs.
+ */
+export declare class ScriptedClock {
+    /** A fixed epoch: 2026-01-01T00:00:00.000Z. Chosen for readability in goldens. */
+    static readonly EPOCH_MS: number;
+    /** One second per step — well under any stall or cache horizon. */
+    static readonly STEP_MS = 1000;
+    private nowMs;
+    install(): void;
+    tick(ms?: number): void;
+    /** Back to the epoch — for a second scenario in the same file. */
+    reset(): void;
+    uninstall(): void;
+}
+/** How an activity invocation ended: the return value or the error it threw. */
+export type ActivityOutcome = {
+    readonly kind: "returned";
+    readonly value: unknown;
+} | {
+    readonly kind: "threw";
+    readonly error: unknown;
+};
+export interface ActivityInvocation {
+    readonly outcome: ActivityOutcome;
+    /** Heartbeat details the activity reported, in order. */
+    readonly heartbeats: unknown[];
+    /** The `taskQueue` the invocation ran on (the shutdown signal is keyed by it). */
+    readonly taskQueue: string;
+}
+/**
+ * Handles a scenario uses to interrupt the invocation FROM A SCRIPT STEP —
+ * never from a timer. `cancel()` aborts the activity's `cancellationSignal`
+ * (a user pause, as the workflow delivers it). `signalWorkerShutdown()` aborts
+ * the queue's shutdown signal first, which the activity reads to tell a worker
+ * drain from a user pause (`classifyTurnInterruption`).
+ */
+export interface InvocationControls {
+    cancel(): void;
+    signalWorkerShutdown(): void;
+}
+export interface RunActivityOptions {
+    readonly taskQueue?: string;
+    /**
+     * Receives the invocation's controls before the activity starts, so a
+     * scenario can hand them to the harness double's `effect` steps.
+     */
+    readonly onControls?: (controls: InvocationControls) => void;
+}
+/**
+ * Run one activity function under a fresh `MockActivityEnvironment` and
+ * capture how it ended. `CancelledFailure` is caught like any other throw and
+ * reported as `{ kind: "threw" }` — the throw-vs-return table is the thing
+ * under test, so the driver never interprets it.
+ */
+export declare function runActivityHermetically<A extends unknown[]>(activity: (...args: A) => Promise<unknown>, args: A, options?: RunActivityOptions): Promise<ActivityInvocation>;
+/** True when the outcome is a thrown Temporal `CancelledFailure`. */
+export declare function threwCancelledFailure(outcome: ActivityOutcome): outcome is {
+    kind: "threw";
+    error: CancelledFailure;
+};