@stigmer/runner 3.14.1 → 3.15.0

package/src/activities/execute-cursor/__tests__/hermetic/thrown-error-arms.test.ts

@@ -0,0 +1,193 @@
+/**
+ * Hermetic goldens: the THROWN-ERROR ARMS of the outer catch — an error that
+ * escapes a setup phase, before any stream ran, becomes EXECUTION_FAILED with
+ * two system messages and the activity RETURNS.
+ *
+ * The outer `catch` of the activity has two arms for an error that is not a
+ * Temporal cancellation and not a pause: a thrown `CursorSdkError` (routed
+ * through the SAME classifier as the `run.wait()` error path, so its
+ * category and diagnostics survive) and everything else (formatted by
+ * `describeExecutionError` as `[<ErrorType>] <message>`). Both write the same
+ * pair of system messages — the generic "Internal system error occurred..."
+ * and an "Error details: ..." carrying the classified or formatted text — and
+ * both RETURN the failed status rather than throwing: a Temporal retry would
+ * replay the same setup against the same fault.
+ *
+ * Two scenarios, one per arm, each failing at a DIFFERENT setup phase:
+ *
+ *  1. `Agent.create` throws a `CursorSdkError` (Phase 8: the SDK refuses the
+ *     key). The error propagates unretried — `resolveAgentWithTransportRecovery`
+ *     retries only a TimeoutError — and the SDK arm classifies it `auth`.
+ *     Golden `goldens/sdk-error-at-create.status.json`.
+ *
+ *  2. `client.getAgent` rejects with a plain `Error` (Phase 2: a control-plane
+ *     fault while resolving the blueprint). The generic arm formats it with
+ *     the error's constructor name. Golden `goldens/resolution-error.status.json`.
+ *
+ * Both fail BEFORE the first status persist, so the ONLY phase the control
+ * plane ever sees for these executions is EXECUTION_FAILED — `persistedPhases`
+ * is `[FAILED]`, not `[IN_PROGRESS, FAILED]`.
+ *
+ * Regenerate ONLY after a deliberate behavior change:
+ *   npx vitest run src/activities/execute-cursor/__tests__/hermetic -u
+ */
+
+import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
+import { toJson } from "@bufbuild/protobuf";
+import { AgentExecutionStatusSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { ExecutionPhase, MessageType } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+
+vi.mock("@cursor/sdk", async () =>
+  (await import("../../__test-utils__/scripted-sdk.js")).scriptedCursorSdkModule(),
+);
+vi.mock("../../../../client/stigmer-client.js", async () =>
+  (await import("../../../../__test-utils__/hermetic-activity.js")).hermeticStigmerClientModule(),
+);
+
+import {
+  ScriptedClock,
+  createHermeticEnvironment,
+  type HermeticEnvironment,
+} from "../../../../__test-utils__/hermetic-activity.js";
+import { _parkedAgentCountForTests } from "../../agent-session-cache.js";
+import { ScriptedCursorAgent } from "../../__test-utils__/scripted-agent.js";
+import { ScriptedCursorSdkError } from "../../__test-utils__/scripted-sdk.js";
+import {
+  SDK_CATALOG,
+  beginCursorScenario,
+  cursorExecutionRecord,
+  runCursorTurn,
+} from "../../__test-utils__/hermetic-cursor.js";
+import { stubRegistryFetch } from "../../../../__test-utils__/model-registry-fixture.js";
+
+const USER_MESSAGE = "Draft the release notes.";
+const GENERIC_SYSTEM_MESSAGE = "Internal system error occurred. Please contact support if this issue persists.";
+// The SDK refusing the key: the shape the real CursorSdkError carries for a 401.
+const SDK_ERROR_MESSAGE = "Cursor API rejected the request: invalid API key";
+// A control-plane fault with deliberately neutral text — no provider, network
+// or billing word in it — so the GENERIC arm is what the golden pins, not a
+// specific diagnosis (`describeExecutionError` classifies known prose first).
+const CONTROL_PLANE_FAULT = "hermetic fault injected at getAgent";
+
+function systemMessages(status: { messages: { type: MessageType; content: string }[] }): string[] {
+  return status.messages.filter((m) => m.type === MessageType.MESSAGE_SYSTEM).map((m) => m.content);
+}
+
+describe("ExecuteCursor hermetic — thrown-error arms of the outer catch", () => {
+  let env: HermeticEnvironment;
+  let registry: ReturnType<typeof stubRegistryFetch>;
+  const clock = new ScriptedClock();
+
+  beforeAll(() => {
+    env = createHermeticEnvironment();
+    registry = stubRegistryFetch();
+    clock.install();
+  });
+
+  afterAll(() => {
+    clock.uninstall();
+    registry.restore();
+    env.dispose();
+  });
+
+  it("a CursorSdkError thrown by Agent.create is classified and fails the turn", async () => {
+    // ── Arrange ──────────────────────────────────────────────────────────────
+    clock.reset(); // both goldens read from :00
+    // Declared so a create that unexpectedly SUCCEEDS is a loud test failure
+    // (its script has no result step) rather than a quiet pass.
+    const neverUsed = new ScriptedCursorAgent({ agentId: "agent-hermetic-never-created", turns: [] });
+    const record = cursorExecutionRecord({ message: USER_MESSAGE });
+    const scenario = beginCursorScenario({
+      env,
+      clock,
+      record,
+      sdk: {
+        agents: [neverUsed],
+        createFailure: new ScriptedCursorSdkError(SDK_ERROR_MESSAGE, {
+          code: "unauthenticated",
+          status: 401,
+          operation: "Agent.create",
+        }),
+        catalog: SDK_CATALOG,
+      },
+    });
+
+    // ── Act ──────────────────────────────────────────────────────────────────
+    const invocation = await runCursorTurn(scenario);
+
+    // ── Assert: outcome and phases ───────────────────────────────────────────
+    expect(invocation.outcome.kind, "the SDK arm RETURNS the failed status").toBe("returned");
+    const slim = (invocation.outcome as { value: Record<string, unknown> }).value;
+    expect(slim.phase).toBe("EXECUTION_FAILED");
+    expect(record.persistedPhases, "nothing was persisted before the failure").toEqual([
+      ExecutionPhase.EXECUTION_FAILED,
+    ]);
+    const final = record.lastFullStatus!;
+    expect(final.error).toBe(`${SDK_ERROR_MESSAGE} [category=auth, source=sdk, retryable=false]`);
+    expect(final.completedAt).not.toBe("");
+    expect(systemMessages(final)).toEqual([GENERIC_SYSTEM_MESSAGE, `Error details: ${final.error}`]);
+
+    // ── Assert: where it stopped ─────────────────────────────────────────────
+    expect(scenario.sdk.resolutions.map((r) => r.kind), "one create attempt, unretried").toEqual(["create"]);
+    expect(neverUsed.sends, "no agent ever ran").toHaveLength(0);
+    expect(record.sessionUpdates, "no harness_state_id to bind").toHaveLength(0);
+    expect(_parkedAgentCountForTests()).toBe(0);
+
+    // ── Assert: hermeticity ──────────────────────────────────────────────────
+    expect(registry.urls.every((u) => u.includes("/model-registry"))).toBe(true);
+    expect(invocation.heartbeats.length).toBeGreaterThan(0);
+
+    // ── Assert: the golden ───────────────────────────────────────────────────
+    const json = JSON.stringify(toJson(AgentExecutionStatusSchema, final), null, 2) + "\n";
+    await expect(json).toMatchFileSnapshot("./goldens/sdk-error-at-create.status.json");
+  });
+
+  it("a plain Error during blueprint resolution fails the turn through the generic arm", async () => {
+    // ── Arrange ──────────────────────────────────────────────────────────────
+    clock.reset();
+    const neverUsed = new ScriptedCursorAgent({ agentId: "agent-hermetic-never-resolved", turns: [] });
+    const record = cursorExecutionRecord({ message: USER_MESSAGE });
+    const scenario = beginCursorScenario({
+      env,
+      clock,
+      record,
+      sdk: { agents: [neverUsed], catalog: SDK_CATALOG },
+      clientOverrides: {
+        getAgent: vi.fn(async () => {
+          throw new Error(CONTROL_PLANE_FAULT);
+        }),
+      },
+    });
+
+    // ── Act ──────────────────────────────────────────────────────────────────
+    const invocation = await runCursorTurn(scenario);
+
+    // ── Assert: outcome and phases ───────────────────────────────────────────
+    expect(invocation.outcome.kind, "the generic arm RETURNS the failed status").toBe("returned");
+    const slim = (invocation.outcome as { value: Record<string, unknown> }).value;
+    expect(slim.phase).toBe("EXECUTION_FAILED");
+    expect(record.persistedPhases).toEqual([ExecutionPhase.EXECUTION_FAILED]);
+    const final = record.lastFullStatus!;
+    expect(final.error).toBe(`Execution failed: [Error] ${CONTROL_PLANE_FAULT}`);
+    expect(final.completedAt).not.toBe("");
+    expect(systemMessages(final)).toEqual([
+      GENERIC_SYSTEM_MESSAGE,
+      `Error details: [Error] ${CONTROL_PLANE_FAULT}`,
+    ]);
+
+    // ── Assert: where it stopped ─────────────────────────────────────────────
+    expect(record.setupProgress, "Phase 2 was reported, nothing after it").toEqual([
+      "Fetching execution",
+      "Resolving agent blueprint",
+    ]);
+    expect(scenario.sdk.resolutions, "the SDK was never reached").toHaveLength(0);
+    expect(record.sessionUpdates).toHaveLength(0);
+
+    // ── Assert: hermeticity ──────────────────────────────────────────────────
+    expect(registry.urls.every((u) => u.includes("/model-registry"))).toBe(true);
+
+    // ── Assert: the golden ───────────────────────────────────────────────────
+    const json = JSON.stringify(toJson(AgentExecutionStatusSchema, final), null, 2) + "\n";
+    await expect(json).toMatchFileSnapshot("./goldens/resolution-error.status.json");
+  });
+});

package/src/activities/execute-cursor/__tests__/hermetic/tool-call.test.ts

@@ -44,8 +44,8 @@ import {
   beginCursorScenario,
   cursorExecutionRecord,
   runCursorTurn,
-  stubRegistryFetch,
 } from "../../__test-utils__/hermetic-cursor.js";
+import { stubRegistryFetch } from "../../../../__test-utils__/model-registry-fixture.js";
 
 const AGENT_ID = "agent-hermetic-tool-0001";
 const RUN_ID = "run-hermetic-tool-0001";

package/src/activities/execute-cursor/__tests__/hermetic/unattributed-hook-block.test.ts

@@ -0,0 +1,185 @@
+/**
+ * Hermetic golden: UNATTRIBUTED HOOK BLOCK (issue #205) — a tool blocked by a
+ * hook Stigmer does not own fails the turn with a diagnosable reason, never a
+ * silent completion.
+ *
+ * Invariant pinned: Cursor runs EVERY hook in the workspace's `.cursor/hooks.json`
+ * and a deny from any of them blocks the tool. Stigmer's own hook records every
+ * deny it issues to the denial ledger, so a FAILED tool call carrying Cursor's
+ * hook-block error text with NO ledger entry was blocked by a FOREIGN hook. No
+ * approval can unblock it (an approval grants a token only OUR hook reads), so
+ * the turn boundary reports it and the activity RETURNS EXECUTION_FAILED with an
+ * error that names the blocked tool and the foreign hook command the gate
+ * install found beside ours. The golden (`goldens/unattributed-hook-block.status.json`)
+ * pins that copy.
+ *
+ * What the scenario ALSO pins, because it is the point of #173 and the reason
+ * #205 exists at all: the gate MERGES into the user's `hooks.json` (their hook
+ * survives the turn and is reported as the culprit) and the teardown restores
+ * their file byte for byte.
+ *
+ * Engine disposition on this arm, today: the handle is `close()`d, not parked
+ * (index.ts `enterUnattributedHookBlockFailure`).
+ *
+ * Parent phase rows exercised beyond the earlier scenarios: the gate install's
+ * foreign-hook detection (`workspace-setup.ts` `mergeHooks`); the FAILED
+ * tool-call row built from a single `status: "error"` event; the boundary's
+ * `detectUnattributedHookBlocks` pass over an EMPTY ledger; the
+ * `enterUnattributedHookBlockFailure` terminal; the `finally`'s hooks.json restore.
+ *
+ * Regenerate ONLY after a deliberate behavior change:
+ *   npx vitest run src/activities/execute-cursor/__tests__/hermetic -u
+ */
+
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
+import { toJson } from "@bufbuild/protobuf";
+import { AgentExecutionStatusSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import {
+  ExecutionPhase,
+  MessageType,
+  ToolCallStatus,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+
+vi.mock("@cursor/sdk", async () =>
+  (await import("../../__test-utils__/scripted-sdk.js")).scriptedCursorSdkModule(),
+);
+vi.mock("../../../../client/stigmer-client.js", async () =>
+  (await import("../../../../__test-utils__/hermetic-activity.js")).hermeticStigmerClientModule(),
+);
+
+import {
+  ScriptedClock,
+  createHermeticEnvironment,
+  type HermeticEnvironment,
+} from "../../../../__test-utils__/hermetic-activity.js";
+import { _parkedAgentCountForTests } from "../../agent-session-cache.js";
+import { ScriptedCursorAgent, sdkEvents, step } from "../../__test-utils__/scripted-agent.js";
+import {
+  SDK_CATALOG,
+  beginCursorScenario,
+  cursorExecutionRecord,
+  runCursorTurn,
+  sessionWorkspaceDir,
+} from "../../__test-utils__/hermetic-cursor.js";
+import { stubRegistryFetch } from "../../../../__test-utils__/model-registry-fixture.js";
+
+const AGENT_ID = "agent-hermetic-hookblock-0001";
+const RUN_ID = "run-hermetic-hookblock-0001";
+const CALL_ID = "call-hermetic-hookblock-0001";
+const USER_MESSAGE = "Clean the build directory.";
+const SHELL_ARGS = { command: "rm -rf build" };
+/** The user's own gating hook — a team policy script the merge must preserve. */
+const FOREIGN_HOOK_COMMAND = "./scripts/team-policy-hook.sh";
+/**
+ * The user's hooks.json exactly as they wrote it (formatting included): the
+ * teardown must hand back these bytes, not a re-serialization.
+ */
+const USER_HOOKS_JSON =
+  JSON.stringify({ version: 1, hooks: { preToolUse: [{ command: FOREIGN_HOOK_COMMAND }] } }, null, 2) + "\n";
+/**
+ * The error text Cursor stamps on a hook-blocked tool call
+ * (`message-translator.ts` HOOK_BLOCK_ERROR_MARKERS). The SDK has no structured
+ * "denied by hook" signal; this text is the only stream-side trace.
+ */
+const HOOK_BLOCK_ERROR = "blocked by a hook";
+const FINAL_TEXT = "I could not clean the build directory: the shell command was blocked.";
+
+describe("ExecuteCursor hermetic — unattributed hook block (#205)", () => {
+  let env: HermeticEnvironment;
+  let registry: ReturnType<typeof stubRegistryFetch>;
+  const clock = new ScriptedClock();
+
+  beforeAll(() => {
+    env = createHermeticEnvironment();
+    registry = stubRegistryFetch();
+    clock.install();
+  });
+
+  afterAll(() => {
+    clock.uninstall();
+    registry.restore();
+    env.dispose();
+  });
+
+  it("fails the turn naming the blocked tool and the foreign hook, and restores the user's hooks.json", async () => {
+    // ── Arrange: the user's own gating hook is already in the workspace ─────
+    const workspaceDir = sessionWorkspaceDir(env);
+    const hooksJsonPath = join(workspaceDir, ".cursor", "hooks.json");
+    mkdirSync(join(workspaceDir, ".cursor"), { recursive: true });
+    writeFileSync(hooksJsonPath, USER_HOOKS_JSON, "utf-8");
+
+    const ev = sdkEvents(AGENT_ID, RUN_ID);
+    const agent = new ScriptedCursorAgent({
+      agentId: AGENT_ID,
+      runIds: [RUN_ID],
+      observeStep: () => clock.tick(),
+      turns: [
+        [
+          step.event(ev.init()),
+          step.event(ev.assistant("Removing the build directory.")),
+          // The foreign hook denied the shell; Cursor reports the call as
+          // failed with its generic hook-block text. Our ledger never saw it.
+          step.event(ev.toolCall(CALL_ID, "shell", "error", SHELL_ARGS, HOOK_BLOCK_ERROR)),
+          step.event(ev.assistant(FINAL_TEXT)),
+          step.turnEnded({ inputTokens: 1_500, outputTokens: 40 }),
+          step.finished({ result: FINAL_TEXT }),
+        ],
+      ],
+    });
+    const record = cursorExecutionRecord({ message: USER_MESSAGE });
+    const scenario = beginCursorScenario({ env, clock, record, sdk: { agents: [agent], catalog: SDK_CATALOG } });
+
+    // ── Act ──────────────────────────────────────────────────────────────────
+    const invocation = await runCursorTurn(scenario);
+
+    // ── Assert: outcome and phases ───────────────────────────────────────────
+    expect(invocation.outcome.kind, "an unattributed block RETURNS a terminal status").toBe("returned");
+    const slim = (invocation.outcome as { value: Record<string, unknown> }).value;
+    expect(slim.phase).toBe("EXECUTION_FAILED");
+    expect(record.persistedPhases).toEqual([
+      ExecutionPhase.EXECUTION_IN_PROGRESS,
+      ExecutionPhase.EXECUTION_FAILED,
+    ]);
+
+    // ── Assert: the diagnosable reason ───────────────────────────────────────
+    const final = record.lastFullStatus!;
+    expect(final.error).toBe(
+      `A Cursor hook outside Stigmer's approval gate blocked tool(s): shell.` +
+        ` The workspace's .cursor/hooks.json registers hook(s) outside Stigmer's control ` +
+        `[${FOREIGN_HOOK_COMMAND}], which most likely denied it.` +
+        ` Stigmer cannot request approval on a foreign hook's behalf — remove or adjust ` +
+        `the hook in .cursor/hooks.json and retry.`,
+    );
+    expect(final.completedAt, "a failed turn is complete").not.toBe("");
+    expect(
+      final.messages.filter((m) => m.type === MessageType.MESSAGE_SYSTEM).map((m) => m.content),
+    ).toEqual([`Execution failed: ${final.error}`]);
+
+    // The blocked row stays FAILED with Cursor's text — never silently
+    // completed, never collapsed into a Stigmer gate row.
+    const rows = record.toolCalls();
+    expect(rows).toHaveLength(1);
+    expect(rows[0].status).toBe(ToolCallStatus.TOOL_CALL_FAILED);
+    expect(rows[0].error).toBe(HOOK_BLOCK_ERROR);
+    expect(record.waitingToolCalls(), "no approval is pending — none could unblock it").toHaveLength(0);
+
+    // ── Assert: engine disposition (today's) ─────────────────────────────────
+    expect(agent.closeCalls, "the handle is closed on this failure").toBe(1);
+    expect(_parkedAgentCountForTests(), "and not parked").toBe(0);
+    expect(agent.runs[0].cancelCalls, "the run completed on its own — nothing cancelled it").toHaveLength(0);
+    expect(record.sessionUpdates, "the one harness_state_id bind").toHaveLength(1);
+
+    // ── Assert: the user's hooks.json survived the turn byte for byte (#173) ─
+    expect(readFileSync(hooksJsonPath, "utf-8")).toBe(USER_HOOKS_JSON);
+
+    // ── Assert: hermeticity ──────────────────────────────────────────────────
+    expect(registry.urls.every((u) => u.includes("/model-registry"))).toBe(true);
+    expect(invocation.heartbeats.length).toBeGreaterThan(0);
+
+    // ── Assert: the golden ───────────────────────────────────────────────────
+    const json = JSON.stringify(toJson(AgentExecutionStatusSchema, final), null, 2) + "\n";
+    await expect(json).toMatchFileSnapshot("./goldens/unattributed-hook-block.status.json");
+  });
+});

package/src/activities/execute-cursor/__tests__/hermetic/workspace-lock-timeout.test.ts

@@ -0,0 +1,151 @@
+/**
+ * Hermetic scenario: WORKSPACE LOCK TIMEOUT — a turn that cannot acquire its
+ * workspace within the configured wait fails with an actionable reason and
+ * RETURNS, before any agent exists.
+ *
+ * Invariant pinned: every turn serializes on its primary workspace directory
+ * (shared/workspace/workspace-lock.ts) before the first tree mutation. While
+ * another turn holds the lock the activity reports a visible waiting state and
+ * heartbeats; past `Config.workspaceLockTimeoutMs` it maps
+ * `WorkspaceLockTimeoutError` to EXECUTION_FAILED with the lock's own message
+ * (which names the directory) and one system message, persists ONCE, and
+ * returns — a Temporal retry would only queue behind the same holder. No
+ * `Agent.create`, no `harness_state_id` bind, nothing streamed.
+ *
+ * Why this is the one terminal arm WITHOUT a file golden (owner ruling,
+ * 2026-09-11, entry 20260911.03 M0): the wire copy embeds the absolute
+ * workspace path, which is a per-run temp directory and differs between macOS
+ * and CI. The S0 driver's rule is to control a volatile source at its origin
+ * or escalate — never redact — so this scenario pins every byte the path does
+ * not touch with explicit assertions and builds the expected message with the
+ * SAME error class over the real resolved path.
+ *
+ * Determinism: the lock wait is `waitedMs + pollIntervalMs > timeoutMs`, so a
+ * timeout below the 1 s poll interval fails on the FIRST contended attempt with
+ * no sleep; `waitedMs` is measured on the scripted clock, so it is 0.
+ *
+ * Regenerate: nothing to regenerate — no snapshot.
+ */
+
+import { mkdirSync } from "node:fs";
+import { realpath } from "node:fs/promises";
+import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
+import { ExecutionPhase, MessageType } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+
+vi.mock("@cursor/sdk", async () =>
+  (await import("../../__test-utils__/scripted-sdk.js")).scriptedCursorSdkModule(),
+);
+vi.mock("../../../../client/stigmer-client.js", async () =>
+  (await import("../../../../__test-utils__/hermetic-activity.js")).hermeticStigmerClientModule(),
+);
+
+import {
+  ScriptedClock,
+  createHermeticEnvironment,
+  type HermeticEnvironment,
+} from "../../../../__test-utils__/hermetic-activity.js";
+import {
+  WorkspaceLockTimeoutError,
+  acquireWorkspaceLock,
+  type ReleaseWorkspaceLock,
+} from "../../../../shared/workspace/workspace-lock.js";
+import { _parkedAgentCountForTests } from "../../agent-session-cache.js";
+import { ScriptedCursorAgent } from "../../__test-utils__/scripted-agent.js";
+import {
+  SDK_CATALOG,
+  beginCursorScenario,
+  cursorExecutionRecord,
+  runCursorTurn,
+  sessionWorkspaceDir,
+} from "../../__test-utils__/hermetic-cursor.js";
+import { stubRegistryFetch } from "../../../../__test-utils__/model-registry-fixture.js";
+
+const USER_MESSAGE = "Rename the config module.";
+/** Below the lock's 1 s poll interval, so the first contended attempt times out. */
+const LOCK_TIMEOUT_MS = 500;
+
+describe("ExecuteCursor hermetic — workspace lock timeout", () => {
+  let env: HermeticEnvironment;
+  let registry: ReturnType<typeof stubRegistryFetch>;
+  const clock = new ScriptedClock();
+
+  beforeAll(() => {
+    env = createHermeticEnvironment();
+    registry = stubRegistryFetch();
+    clock.install();
+  });
+
+  afterAll(() => {
+    clock.uninstall();
+    registry.restore();
+    env.dispose();
+  });
+
+  it("fails the turn with the lock's message when another turn holds the workspace", async () => {
+    // ── Arrange: another turn already holds this session's workspace ─────────
+    // The directory is created BEFORE either side locks it so both resolve the
+    // same realpath (macOS's /var -> /private/var) and contend on ONE key.
+    const workspaceDir = sessionWorkspaceDir(env);
+    mkdirSync(workspaceDir, { recursive: true });
+    const resolvedDir = await realpath(workspaceDir);
+    let releaseHeldLock: ReleaseWorkspaceLock | undefined = await acquireWorkspaceLock(workspaceDir);
+
+    const neverUsed = new ScriptedCursorAgent({ agentId: "agent-hermetic-never-locked", turns: [] });
+    const record = cursorExecutionRecord({ message: USER_MESSAGE });
+    const scenario = beginCursorScenario({
+      env,
+      clock,
+      record,
+      sdk: { agents: [neverUsed], catalog: SDK_CATALOG },
+      config: { workspaceLockTimeoutMs: LOCK_TIMEOUT_MS },
+    });
+
+    try {
+      // ── Act ────────────────────────────────────────────────────────────────
+      const invocation = await runCursorTurn(scenario);
+
+      // ── Assert: outcome and phases ─────────────────────────────────────────
+      expect(invocation.outcome.kind, "a lock timeout RETURNS — a retry would queue behind the same holder").toBe(
+        "returned",
+      );
+      const slim = (invocation.outcome as { value: Record<string, unknown> }).value;
+      expect(slim.phase).toBe("EXECUTION_FAILED");
+      expect(record.persistedPhases, "the one and only full persist").toEqual([ExecutionPhase.EXECUTION_FAILED]);
+
+      // ── Assert: the copy, built with the same class over the real path ─────
+      const expectedMessage = new WorkspaceLockTimeoutError(resolvedDir, 0).message;
+      expect(expectedMessage).toBe(
+        `Workspace is in use by another session: ${resolvedDir} (waited 0s). ` +
+          `Another agent execution is operating on this workspace directory; retry after it finishes.`,
+      );
+      const final = record.lastFullStatus!;
+      expect(final.error).toBe(expectedMessage);
+      expect(final.completedAt).not.toBe("");
+      expect(final.startedAt).not.toBe("");
+      expect(
+        final.messages.filter((m) => m.type === MessageType.MESSAGE_SYSTEM).map((m) => m.content),
+      ).toEqual([`Execution failed: ${expectedMessage}`]);
+      expect(final.messages, "the system message is the whole transcript").toHaveLength(1);
+
+      // ── Assert: the visible waiting state, then nothing past the lock ──────
+      expect(record.setupProgress).toEqual([
+        "Fetching execution",
+        "Resolving agent blueprint",
+        "Resolving environment",
+        "Provisioning workspace",
+        "Waiting for workspace — in use by another session",
+      ]);
+      expect(scenario.sdk.resolutions, "no agent was created").toHaveLength(0);
+      expect(neverUsed.sends).toHaveLength(0);
+      expect(record.sessionUpdates, "no harness_state_id to bind").toHaveLength(0);
+      expect(_parkedAgentCountForTests()).toBe(0);
+
+      // ── Assert: hermeticity ────────────────────────────────────────────────
+      expect(registry.urls.every((u) => u.includes("/model-registry"))).toBe(true);
+      expect(invocation.heartbeats.length, "the activity heartbeat before the lock").toBeGreaterThan(0);
+    } finally {
+      await releaseHeldLock?.();
+      releaseHeldLock = undefined;
+    }
+  });
+});