@stigmer/runner 3.14.0-dev.20260910084630 → 3.14.1

package/dist/.build-fingerprint

@@ -1 +1 @@
-{"hash":"7c856383e6ad237f","builtAt":"2026-09-10T08:50:47.176Z","fileCount":293}
+{"hash":"4056de20de2c1bdd","builtAt":"2026-09-11T16:01:46.462Z","fileCount":305}

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

@@ -0,0 +1,245 @@
+/**
+ * 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, 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;
+}
+/**
+ * An in-memory stand-in for the server's execution row, with the TWO merge
+ * rules 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 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;
+    /** 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). */
+    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;
+    applyStatusUpdate(status: AgentExecutionStatus): void;
+    /**
+     * 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;
+};

package/dist/__test-utils__/hermetic-activity.js

@@ -0,0 +1,369 @@
+/**
+ * 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 { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { vi } from "vitest";
+import { MockActivityEnvironment } from "@temporalio/testing";
+import { CancelledFailure } from "@temporalio/activity";
+import { Code, ConnectError } from "@connectrpc/connect";
+import { clone, create } from "@bufbuild/protobuf";
+import { AgentExecutionSchema, AgentExecutionStatusSchema, } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { ExecutionPhase, ToolCallStatus, } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { UpdateStatusResponseSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/io_pb";
+import { registerWorkerShutdownSignal, signalWorkerShutdown, unregisterWorkerShutdownSignal, } from "../shared/worker-shutdown.js";
+import { mockStigmerClient } from "./mock-client.js";
+/**
+ * An in-memory stand-in for the server's execution row, with the TWO merge
+ * rules 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 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 class ExecutionRecord {
+    execution;
+    session;
+    agentInstance;
+    agent;
+    /** Every `updateStatus` payload, in order, snapshotted at write time. */
+    persisted = [];
+    /** Setup-progress labels reported before the stream started, in order. */
+    setupProgress = [];
+    /** Every `updateSession` payload, in order (the `harness_state_id` write-back). */
+    sessionUpdates = [];
+    constructor(input) {
+        this.execution = clone(AgentExecutionSchema, input.execution);
+        this.session = input.session;
+        this.agentInstance = input.agentInstance;
+        this.agent = input.agent;
+    }
+    get executionId() {
+        return this.execution.metadata?.id ?? "";
+    }
+    /** The status the server would currently hold (what `getExecution` returns). */
+    get status() {
+        return this.execution.status;
+    }
+    /** The last FULL status written (phase set), or undefined if none yet. */
+    get lastFullStatus() {
+        for (let i = this.persisted.length - 1; i >= 0; i--) {
+            const s = this.persisted[i];
+            if (s.phase !== ExecutionPhase.EXECUTION_PHASE_UNSPECIFIED)
+                return s;
+        }
+        return 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() {
+        const out = [];
+        for (const s of this.persisted) {
+            if (s.phase === ExecutionPhase.EXECUTION_PHASE_UNSPECIFIED)
+                continue;
+            if (out[out.length - 1] !== s.phase)
+                out.push(s.phase);
+        }
+        return out;
+    }
+    /** Every tool call on the held transcript (top-level messages), in order. */
+    toolCalls() {
+        return this.execution.status?.messages.flatMap((m) => m.toolCalls) ?? [];
+    }
+    /** The tool calls currently paused for a decision. */
+    waitingToolCalls() {
+        return this.toolCalls().filter((tc) => tc.status === ToolCallStatus.TOOL_CALL_WAITING_APPROVAL);
+    }
+    /**
+     * 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, decidedAt) {
+        const waiting = this.waitingToolCalls();
+        for (const tc of waiting) {
+            tc.approvalAction = action;
+            tc.approvalDecidedAt = decidedAt;
+        }
+        return waiting.length;
+    }
+    applyStatusUpdate(status) {
+        const snapshot = clone(AgentExecutionStatusSchema, status);
+        this.persisted.push(snapshot);
+        if (snapshot.phase === ExecutionPhase.EXECUTION_PHASE_UNSPECIFIED) {
+            if (snapshot.setupProgress?.currentPhase) {
+                this.setupProgress.push(snapshot.setupProgress.currentPhase);
+            }
+            return;
+        }
+        this.execution.status = clone(AgentExecutionStatusSchema, snapshot);
+    }
+    /**
+     * 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 = {}) {
+        return mockStigmerClient({
+            getExecution: vi.fn(async () => clone(AgentExecutionSchema, this.execution)),
+            getSession: vi.fn(async () => this.session),
+            getAgentInstance: vi.fn(async () => this.agentInstance),
+            getAgent: vi.fn(async () => this.agent),
+            updateStatus: vi.fn(async (_id, status) => {
+                this.applyStatusUpdate(status);
+                // The activity reads only `.signal`; UNSPECIFIED means "keep going".
+                return create(UpdateStatusResponseSchema, {});
+            }),
+            updateSession: vi.fn(async (session) => {
+                this.sessionUpdates.push(session);
+                return session;
+            }),
+            getExecutionContextByExecutionId: vi.fn(async () => {
+                throw new ConnectError("execution context not found", Code.NotFound);
+            }),
+            ...overrides,
+        });
+    }
+}
+// ---------------------------------------------------------------------------
+// The module-boundary seam for StigmerClient
+// ---------------------------------------------------------------------------
+let boundClient;
+/**
+ * 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 function bindHermeticClient(client) {
+    boundClient = client;
+}
+/**
+ * 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 function hermeticStigmerClientModule() {
+    return {
+        StigmerClient: class {
+            constructor() {
+                if (!boundClient) {
+                    throw new Error("hermetic-activity: no StigmerClient bound — call bindHermeticClient(record.client()) " +
+                        "before constructing the activities");
+                }
+                return boundClient;
+            }
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// The environment: temp HOME, temp workspace root, local artifact storage
+// ---------------------------------------------------------------------------
+/**
+ * The env-var pins a hermetic run needs, and the reason for each:
+ *  - `HOME`: `platform-dir.ts` roots the runner-owned `~/.stigmer` tree (HITL
+ *    gate dir, session dirs, denial ledger) on it.
+ *  - `ARTIFACT_STORAGE_TYPE=local` + `LOCAL_ARTIFACT_PATH`: a writable local
+ *    store so capture mode and tool-output offload run the production path
+ *    (an absent store flips capture off — a different code path).
+ *  - `STIGMER_RUNNER_HITL_SECRET`: the one randomness source on the activity
+ *    path, pinned so grant tokens and fingerprints are byte-stable.
+ *  - `CURSOR_EVENT_RECORD_DIR` cleared: never write recordings from a test.
+ */
+const PINNED_ENV = {
+    ARTIFACT_STORAGE_TYPE: "local",
+    STIGMER_RUNNER_HITL_SECRET: "hermetic-fixture-secret-do-not-use-in-production",
+};
+const CLEARED_ENV = ["CURSOR_EVENT_RECORD_DIR", "STIGMER_PROXY_ENDPOINT", "STIGMER_CLOUD_API_URL"];
+/**
+ * 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 function createHermeticEnvironment() {
+    const root = mkdtempSync(join(tmpdir(), "stigmer-hermetic-"));
+    const home = join(root, "home");
+    const workspaceRootDir = join(root, "workspaces");
+    const artifactPath = join(root, "artifacts");
+    const saved = new Map();
+    const set = (key, value) => {
+        if (!saved.has(key))
+            saved.set(key, process.env[key]);
+        if (value === undefined)
+            delete process.env[key];
+        else
+            process.env[key] = value;
+    };
+    set("HOME", home);
+    set("LOCAL_ARTIFACT_PATH", artifactPath);
+    for (const [k, v] of Object.entries(PINNED_ENV))
+        set(k, v);
+    for (const k of CLEARED_ENV)
+        set(k, undefined);
+    let disposed = false;
+    return {
+        home,
+        workspaceRootDir,
+        artifactPath,
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            for (const [k, v] of saved) {
+                if (v === undefined)
+                    delete process.env[k];
+                else
+                    process.env[k] = v;
+            }
+            rmSync(root, { recursive: true, force: true });
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// The clock
+// ---------------------------------------------------------------------------
+/**
+ * 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 class ScriptedClock {
+    /** A fixed epoch: 2026-01-01T00:00:00.000Z. Chosen for readability in goldens. */
+    static EPOCH_MS = Date.UTC(2026, 0, 1, 0, 0, 0, 0);
+    /** One second per step — well under any stall or cache horizon. */
+    static STEP_MS = 1_000;
+    nowMs = ScriptedClock.EPOCH_MS;
+    install() {
+        vi.useFakeTimers({ toFake: ["Date"], now: this.nowMs });
+    }
+    tick(ms = ScriptedClock.STEP_MS) {
+        this.nowMs += ms;
+        vi.setSystemTime(this.nowMs);
+    }
+    /** Back to the epoch — for a second scenario in the same file. */
+    reset() {
+        this.nowMs = ScriptedClock.EPOCH_MS;
+        vi.setSystemTime(this.nowMs);
+    }
+    uninstall() {
+        vi.useRealTimers();
+    }
+}
+/**
+ * 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 async function runActivityHermetically(activity, args, options = {}) {
+    const taskQueue = options.taskQueue ?? "hermetic-test-queue";
+    const env = new MockActivityEnvironment({ taskQueue });
+    const heartbeats = [];
+    env.on("heartbeat", (details) => heartbeats.push(details));
+    // The worker-shutdown signal is process-global per queue; register for this
+    // invocation and always unregister so no state leaks into the next one.
+    registerWorkerShutdownSignal(taskQueue);
+    options.onControls?.({
+        cancel: () => env.cancel(),
+        signalWorkerShutdown: () => signalWorkerShutdown(taskQueue),
+    });
+    try {
+        const value = await env.run(activity, ...args);
+        return { outcome: { kind: "returned", value }, heartbeats, taskQueue };
+    }
+    catch (error) {
+        return { outcome: { kind: "threw", error }, heartbeats, taskQueue };
+    }
+    finally {
+        unregisterWorkerShutdownSignal(taskQueue);
+    }
+}
+/** True when the outcome is a thrown Temporal `CancelledFailure`. */
+export function threwCancelledFailure(outcome) {
+    return outcome.kind === "threw" && outcome.error instanceof CancelledFailure;
+}
+//# sourceMappingURL=hermetic-activity.js.map

package/dist/__test-utils__/hermetic-activity.js.map

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

package/dist/__test-utils__/mock-client.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Shared mock factory for StigmerClient used across test suites.
+ *
+ * StigmerClient is a class (not an interface), so mocks use
+ * `as unknown as StigmerClient` — matching the established pattern
+ * in grpc-retry.test.ts and connect-backfill.test.ts.
+ */
+import type { StigmerClient } from "../client/stigmer-client.js";
+type MockMethods = {
+    [K in keyof StigmerClient]?: StigmerClient[K];
+};
+export declare function mockStigmerClient(overrides?: MockMethods): StigmerClient;
+export {};