@stigmer/runner 3.14.1 → 3.15.0

package/src/harness/__tests__/persist-chokepoint.test.ts

@@ -0,0 +1,146 @@
+/**
+ * The persist chokepoint's two contracts: what one write does (the secret
+ * backstop, the usage summary, the heartbeat, the STOP), and how requests
+ * coalesce (one write in flight, one follow-up at most, every request's
+ * promise resolving only once its state is on the wire).
+ */
+
+import { describe, expect, it, vi } from "vitest";
+import { create } from "@bufbuild/protobuf";
+import { AgentExecutionStatusSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { UpdateStatusResponseSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/io_pb";
+import { AgentMessageSchema, ToolCallSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import { ExecutionControlSignal, MessageType, ServiceTier, ThinkingMode, ToolCallStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+
+import type { StigmerClient } from "../../client/stigmer-client.js";
+import { PersistChokepoint } from "../persist-chokepoint.js";
+import { UsageAccumulator } from "../usage-accumulator.js";
+
+interface Gate {
+  readonly open: () => void;
+  readonly opened: Promise<void>;
+}
+
+function gate(): Gate {
+  let open!: () => void;
+  const opened = new Promise<void>((resolve) => (open = resolve));
+  return { open, opened };
+}
+
+/** A client whose `updateStatus` answers through a gate the test opens, so writes can be held in flight. */
+function heldClient(answers: ExecutionControlSignal[] = []) {
+  const gates: Gate[] = [];
+  const writes: number[] = [];
+  const client = {
+    updateStatus: vi.fn(async (_id: string, status: { messages: unknown[] }) => {
+      const g = gate();
+      gates.push(g);
+      writes.push(status.messages.length);
+      await g.opened;
+      return create(UpdateStatusResponseSchema, { signal: answers.shift() ?? ExecutionControlSignal.UNSPECIFIED });
+    }),
+  } as unknown as StigmerClient;
+  return { client, gates, writes };
+}
+
+function chokepointOver(client: StigmerClient, options: { usage?: UsageAccumulator; onPlatformStop?: () => void } = {}) {
+  const status = create(AgentExecutionStatusSchema, {});
+  const heartbeat = vi.fn();
+  const onPlatformStop = options.onPlatformStop ?? vi.fn();
+  const chokepoint = new PersistChokepoint({
+    client,
+    executionId: "aex_test",
+    status,
+    offload: undefined,
+    usage: () => options.usage,
+    heartbeat,
+    onPlatformStop,
+  });
+  return { chokepoint, status, heartbeat, onPlatformStop };
+}
+
+describe("PersistChokepoint: one write", () => {
+  it("withholds secret content, refreshes streaming_usage, writes, heartbeats, and relays STOP", async () => {
+    const { client, gates } = heldClient([ExecutionControlSignal.STOP]);
+    const usage = new UsageAccumulator(ServiceTier.STANDARD, ThinkingMode.DISABLED);
+    usage.addTurn({ inputTokens: 10, estimatedCostUsd: 0.01, model: "m" });
+    const onPlatformStop = vi.fn();
+    const { chokepoint, status, heartbeat } = chokepointOver(client, { usage, onPlatformStop });
+    status.messages.push(
+      create(AgentMessageSchema, {
+        type: MessageType.MESSAGE_AI,
+        toolCalls: [
+          create(ToolCallSchema, {
+            id: "w1",
+            name: "write",
+            status: ToolCallStatus.TOOL_CALL_COMPLETED,
+            args: { path: ".env", content: "SECRET=1" },
+          }),
+        ],
+      }),
+    );
+
+    const written = chokepoint.write();
+    gates[0]!.open();
+    await written;
+
+    expect(status.messages[0]!.toolCalls[0]!.args, "the secret backstop ran before the write").not.toMatchObject({ content: "SECRET=1" });
+    expect(status.streamingUsage?.estimatedCostUsd).toBe(0.01);
+    expect(heartbeat).toHaveBeenCalledTimes(1);
+    expect(onPlatformStop).toHaveBeenCalledTimes(1);
+  });
+
+  it("writes no streaming_usage when no turn was reported", async () => {
+    const { client, gates } = heldClient();
+    const { chokepoint, status } = chokepointOver(client, { usage: new UsageAccumulator() });
+    const written = chokepoint.write();
+    gates[0]!.open();
+    await written;
+    expect(status.streamingUsage).toBeUndefined();
+  });
+});
+
+describe("PersistChokepoint: coalescing", () => {
+  it("a request while a write is in flight schedules ONE follow-up and resolves only when it lands", async () => {
+    const { client, gates, writes } = heldClient();
+    const { chokepoint, status } = chokepointOver(client);
+
+    status.messages.push(create(AgentMessageSchema, { content: "one" }));
+    const first = chokepoint.request();
+    status.messages.push(create(AgentMessageSchema, { content: "two" }));
+    const second = chokepoint.request();
+    status.messages.push(create(AgentMessageSchema, { content: "three" }));
+    const third = chokepoint.request();
+
+    let secondSettled = false;
+    let thirdSettled = false;
+    void second.then(() => (secondSettled = true));
+    void third.then(() => (thirdSettled = true));
+
+    expect(gates, "one write in flight, the follow-up waits").toHaveLength(1);
+    gates[0]!.open();
+    await first;
+    await Promise.resolve();
+    expect(secondSettled, "the follow-up has not landed yet").toBe(false);
+
+    await vi.waitFor(() => expect(gates).toHaveLength(2));
+    expect(writes, "the follow-up carries the state as of the LAST request").toEqual([1, 3]);
+    gates[1]!.open();
+    await Promise.all([second, third]);
+    expect(secondSettled && thirdSettled).toBe(true);
+    expect(client.updateStatus).toHaveBeenCalledTimes(2);
+  });
+
+  it("sequential awaited requests write once each, in order", async () => {
+    const { client, gates } = heldClient();
+    const { chokepoint } = chokepointOver(client);
+    const first = chokepoint.request();
+    gates[0]!.open();
+    await first;
+    const second = chokepoint.request();
+    await vi.waitFor(() => expect(gates).toHaveLength(2));
+    gates[1]!.open();
+    await second;
+    expect(client.updateStatus).toHaveBeenCalledTimes(2);
+  });
+});

package/src/harness/__tests__/registry.test.ts

@@ -36,6 +36,7 @@ function stubAdapter(name: string, log: string[], behaviour: StubBehaviour = {})
       subAgents: false,
       toolRestriction: true,
       visionProfile: DEEP_AGENT_VISION_PROFILE,
+      fileReview: { harnessId: "stub", excludePaths: [] },
     },
     async boot() {
       log.push(`boot:${name}`);

package/src/harness/__tests__/run-turn.test.ts

@@ -0,0 +1,165 @@
+/**
+ * The turn runtime, proven without any engine: the scripted fake adapter
+ * (`__test-utils__/harness-contract/scripted-adapter.ts`) through the kit's
+ * runtime-side half (`__test-utils__/harness-contract/runtime-contract.ts`)
+ * under `MockActivityEnvironment`, one arm per row of the terminal table.
+ *
+ * The runtime-side contract itself — the throw-vs-return rule end to end, the
+ * single persist chokepoint, the whole-activity heartbeat, the stop
+ * controller's four producers, the reinvocation seam, the byte-pinned copy —
+ * is the kit's and is registered here through `describeHarnessRuntimeContract`
+ * exactly as `activities/execute-cursor/__tests__/hermetic/harness-contract.test.ts`
+ * registers it against the real Cursor adapter. An arm that differs between
+ * the fake and the real engine is an adapter defect, not a runtime one.
+ *
+ * What is asserted HERE and not in the kit are the FAKE's facts: the engine
+ * cadence a real engine has no reason to share. The fake's `say` awaits its
+ * persist and its `propose` persists nothing before returning
+ * `awaiting_approval`, so under the runtime its first full write IS the
+ * WAITING write (`persistedPhases === [WAITING_FOR_APPROVAL]`) where a
+ * streaming engine's IN_PROGRESS writes precede it; the fake has no setup
+ * labels of its own, so the runtime's six are the whole list; the fake states
+ * its own price, so the cost copy reads exactly `~$0.6000`; and the fake's
+ * failure messages reach the status verbatim, where a real engine's
+ * classifier rephrases them.
+ *
+ * The hermetic environment is created at module level because the subject's
+ * `config` is read at collection time; the forks pool keeps it private to
+ * this file.
+ */
+
+import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
+import { ApprovalAction, ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+
+vi.mock("../../client/stigmer-client.js", async () =>
+  (await import("../../__test-utils__/hermetic-activity.js")).hermeticStigmerClientModule(),
+);
+
+import { ScriptedClock, createHermeticEnvironment } from "../../__test-utils__/hermetic-activity.js";
+import { stubRegistryFetch } from "../../__test-utils__/model-registry-fixture.js";
+import { scriptedSubject } from "../../__test-utils__/harness-contract/scripted-adapter.js";
+import {
+  COST_CAP_FAKE_PRICE_USD,
+  FAILURE_MESSAGES,
+  NEVER_SEEN,
+  RUNTIME_SETUP_LABELS,
+  RuntimeExecutionDriver,
+  aiMessages,
+  assertApprovalRoundTrip,
+  assertCompletedTurn,
+  assertCostCapTerminates,
+  assertFailedSurfaceWritesItsCopy,
+  assertRejectedBindFails,
+  describeHarnessRuntimeContract,
+  slimOf,
+  systemMessages,
+  type RuntimeContractHarness,
+} from "../../__test-utils__/harness-contract/runtime-contract.js";
+import { scenario } from "../../__test-utils__/harness-contract/types.js";
+import { TERMINAL_COPY } from "../terminal-table.js";
+
+const TASK_QUEUE = "runtime-test-queue";
+
+const env = createHermeticEnvironment();
+const clock = new ScriptedClock();
+const subject = scriptedSubject({
+  pausePrimitive: "interrupt",
+  stateIdSource: "engine-minted",
+  config: { workspaceRootDir: env.workspaceRootDir, taskQueue: TASK_QUEUE },
+});
+const harness: RuntimeContractHarness = { subject, env, clock };
+
+describe("run-turn: the fake adapter through the real runtime", () => {
+  let registry: ReturnType<typeof stubRegistryFetch>;
+
+  beforeAll(() => {
+    registry = stubRegistryFetch();
+    clock.install();
+  });
+
+  afterAll(() => {
+    clock.uninstall();
+    registry.restore();
+    env.dispose();
+  });
+
+  describeHarnessRuntimeContract(harness);
+
+  describe("the fake's own facts", () => {
+    beforeAll(async () => {
+      await subject.adapter.boot(subject.config);
+    });
+
+    it("a completed turn: the runtime's six labels are the whole list, the phases, the stated price and its basis", async () => {
+      clock.reset();
+      const { driver, final } = await assertCompletedTurn(harness, "fake-completed");
+      expect(driver.record.persistedPhases).toEqual([ExecutionPhase.EXECUTION_IN_PROGRESS, ExecutionPhase.EXECUTION_COMPLETED]);
+      expect(driver.record.setupProgress).toEqual([...RUNTIME_SETUP_LABELS]);
+      expect(final.streamingUsage?.estimatedCostUsd, "the summary is the adapter's stated price, summed").toBeCloseTo(0.00136, 9);
+      expect(final.streamingUsage?.model, "the basis the adapter named").toBe("fixture-model");
+      expect(registry.urls.every((u) => u.includes("/model-registry"))).toBe(true);
+    });
+
+    it("the approval round trip: the WAITING write is the fake's first full persist (M3a finding 3)", async () => {
+      clock.reset();
+      const { driver } = await assertApprovalRoundTrip(harness, "fake-approval");
+      expect(driver.record.persistedPhases).toEqual([
+        ExecutionPhase.EXECUTION_WAITING_FOR_APPROVAL,
+        ExecutionPhase.EXECUTION_IN_PROGRESS,
+        ExecutionPhase.EXECUTION_COMPLETED,
+      ]);
+      expect(driver.record.sessionUpdates, "an engine-minted adapter binds once across the round trip").toHaveLength(1);
+    });
+
+    it("the cost cap: the fake's stated price reads exactly in the copy", async () => {
+      clock.reset();
+      const { final } = await assertCostCapTerminates(harness, "fake-cost-cap");
+      expect(final.error).toBe(`Agent reached the cost limit for this message (~$${COST_CAP_FAKE_PRICE_USD.toFixed(4)} of the $0.50 budget). Send another message to continue.`);
+      expect(final.streamingUsage?.estimatedCostUsd).toBe(COST_CAP_FAKE_PRICE_USD);
+    });
+
+    it.each([
+      ["engine", []],
+      ["actionable", [`Execution failed: ${FAILURE_MESSAGES.actionable}`]],
+      ["internal", [TERMINAL_COPY.internalFailure.row, `Error details: ${FAILURE_MESSAGES.internal}`]],
+    ] as const)("a %s failure: the fake's message reaches the status verbatim, with that surface's rows", async (surface, rows) => {
+      clock.reset();
+      const { driver, final } = await assertFailedSurfaceWritesItsCopy(harness, surface, FAILURE_MESSAGES[surface], `fake-failed-${surface}`);
+      expect(driver.record.persistedPhases).toEqual([ExecutionPhase.EXECUTION_IN_PROGRESS, ExecutionPhase.EXECUTION_FAILED]);
+      expect(final.error).toBe(FAILURE_MESSAGES[surface]);
+      expect(systemMessages(final)).toEqual(rows);
+    });
+
+    it("a rejected bind: the fake names the failure and nothing of the scenario was folded in", async () => {
+      clock.reset();
+      const { final } = await assertRejectedBindFails(harness, "fake-bind-rejects");
+      expect(final.error).toContain("could not bind engine state");
+      expect(aiMessages(final)).toEqual([]);
+    });
+
+    it("REJECT of an irreversible action settles the reinvocation FAILED before any engine runs (today's runtime; see F1)", async () => {
+      // The runtime fails a reinvocation that carries any REJECT
+      // (`decideReinvocation`, moved from Cursor's orchestrator). The proto
+      // contract as of #197 — the enum doc, the conformance suite, the native
+      // harness's `reconcileNonExecutingDecisions` — says REJECT denies the
+      // tool and the run continues with the row SKIPPED. This arm pins the
+      // runtime AS IT IS so the S3 change is a visible diff, and is
+      // deliberately NOT in the kit (S2 M4 finding F1, Q-M4-1).
+      clock.reset();
+      const driver = new RuntimeExecutionDriver(harness, "fake-reject");
+      const propose = scenario.propose("call-runtime-reject", { kind: "shell", resource: "rm -rf build" });
+
+      const first = await driver.turn([propose]);
+      expect(slimOf(subject, first).phase).toBe("EXECUTION_WAITING_FOR_APPROVAL");
+      driver.decide(ApprovalAction.REJECT);
+
+      const second = await driver.turn([scenario.say(NEVER_SEEN)]);
+      expect(slimOf(subject, second).phase).toBe("EXECUTION_FAILED");
+      const final = driver.record.lastFullStatus!;
+      expect(final.error).toBe(TERMINAL_COPY.rejectedByUser.error);
+      expect(systemMessages(final).at(-1)).toBe(TERMINAL_COPY.rejectedByUser.row);
+      expect(final.completedAt).not.toBe("");
+      expect(aiMessages(final)).not.toContain(NEVER_SEEN);
+    });
+  });
+});

package/src/harness/__tests__/stop-controller.test.ts

@@ -0,0 +1,49 @@
+/**
+ * The stop controller: one signal for every cause, every cause recorded,
+ * the first cause the abort's reason. The terminal table's precedence is
+ * decided at settlement from the recorded evidence, not from which cause
+ * aborted first.
+ */
+
+import { describe, expect, it } from "vitest";
+
+import { StallTimeoutError } from "../../shared/stall-watchdog.js";
+import { StopController } from "../stop-controller.js";
+
+describe("StopController", () => {
+  it("starts live with no evidence", () => {
+    const stop = new StopController();
+    expect(stop.signal.aborted).toBe(false);
+    expect(stop.evidence).toEqual({ stall: undefined, costCapExceeded: false, platformStop: false, cancellation: false });
+  });
+
+  it("the first cause aborts the signal and names the abort; later causes are recorded but do not re-abort", () => {
+    const stop = new StopController();
+    stop.stop({ kind: "cost-cap" });
+    expect(stop.signal.aborted).toBe(true);
+    expect(stop.signal.reason).toBe("cost-cap");
+
+    stop.stop({ kind: "cancellation" });
+    stop.stop({ kind: "platform-stop" });
+    expect(stop.signal.reason, "the abort keeps its first reason").toBe("cost-cap");
+    expect(stop.evidence).toMatchObject({ costCapExceeded: true, cancellation: true, platformStop: true });
+  });
+
+  it("keeps the FIRST stall error when the watchdog reports twice", () => {
+    const stop = new StopController();
+    const first = new StallTimeoutError(3_000, "last tool: shell");
+    stop.stop({ kind: "stall", error: first });
+    stop.stop({ kind: "stall", error: new StallTimeoutError(9_000) });
+    expect(stop.evidence.stall).toBe(first);
+  });
+
+  it("fires abort listeners exactly once", () => {
+    const stop = new StopController();
+    let fired = 0;
+    stop.signal.addEventListener("abort", () => fired++);
+    stop.stop({ kind: "cancellation" });
+    stop.stop({ kind: "cancellation" });
+    stop.stop({ kind: "cost-cap" });
+    expect(fired).toBe(1);
+  });
+});

package/src/harness/__tests__/turn-context.test.ts

@@ -0,0 +1,178 @@
+/**
+ * Pins the turn context's pure decisions — the three places `turn-context.ts`
+ * decides something rather than fetching it:
+ *
+ *  - `isReinvocation`: the one reading of "does the engine already hold state
+ *    for this execution", keyed on how the harness mints its state id. The
+ *    engine-minted arm is today's `!!threadId`; the deterministic arm refuses
+ *    until the native adapter lands (S3), and the refusal is pinned so a
+ *    future caller cannot get a silent `false`.
+ *  - `approvalDecisionsOf`: the runtime's reader of adjudicated approvals,
+ *    over a transcript that carries every row shape it must include or
+ *    exclude. Its agreement with the Cursor adapter's own reader
+ *    (`reconstructAdjudicatedApprovals`) is pinned from the adapter's side
+ *    (`activities/execute-cursor/__tests__/approval-state.test.ts`), because
+ *    `src/harness/` never imports `src/activities/`, tests included.
+ *  - `decideReinvocation`: the four ways a resume proceeds (reject fails,
+ *    approvals run, a clean file-review resume completes, a failed or
+ *    partially discarded one completes with its facts carried).
+ *
+ * The phases that fetch and provision are exercised end to end by the
+ * hermetic goldens (`activities/execute-cursor/__tests__/hermetic/`), which
+ * pin their observable behavior byte for byte; nothing here re-drives a
+ * client.
+ */
+
+import { describe, expect, it } from "vitest";
+import { create } from "@bufbuild/protobuf";
+import { AgentExecutionStatusSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { AgentMessageSchema, ToolCallSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import { SubAgentExecutionSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/subagent_pb";
+import { ApprovalAction, MessageType, ToolCallStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+
+import { approvalDecisionsOf, decideReinvocation, isReinvocation, type ReinvocationFacts } from "../turn-context.js";
+
+const INPUT = { executionId: "aex_1", threadId: "", turnSeq: 0 } as const;
+
+describe("isReinvocation", () => {
+  it("engine-minted: an empty state id is a first turn, any id is a resume", () => {
+    expect(isReinvocation("engine-minted", INPUT)).toBe(false);
+    expect(isReinvocation("engine-minted", { ...INPUT, threadId: "agent-42" })).toBe(true);
+  });
+
+  it("engine-minted: turnSeq is NOT the signal (a pure-reconcile turn does not advance it; the legacy wire shape yields 0)", () => {
+    expect(isReinvocation("engine-minted", { ...INPUT, turnSeq: 3 })).toBe(false);
+    expect(isReinvocation("engine-minted", { ...INPUT, threadId: "agent-42", turnSeq: 0 })).toBe(true);
+  });
+
+  it("deterministic: refuses rather than guess until the native adapter lands (S3)", () => {
+    expect(() => isReinvocation("deterministic", { ...INPUT, threadId: "thread-1" })).toThrow(
+      /deterministic arm lands with the native adapter \(S3\)/,
+    );
+  });
+});
+
+/** A transcript carrying every row shape the reader must include or exclude. */
+function transcriptWithEveryRowShape() {
+  const waitingApproved = create(ToolCallSchema, {
+    id: "tc-approved",
+    name: "Shell",
+    status: ToolCallStatus.TOOL_CALL_WAITING_APPROVAL,
+    approvalAction: ApprovalAction.APPROVE,
+    approvalContentDigest: "sha256:approved",
+  });
+  const waitingRejected = create(ToolCallSchema, {
+    id: "tc-rejected",
+    name: "Write",
+    status: ToolCallStatus.TOOL_CALL_WAITING_APPROVAL,
+    approvalAction: ApprovalAction.REJECT,
+  });
+  const waitingUndecided = create(ToolCallSchema, {
+    id: "tc-undecided",
+    name: "Shell",
+    status: ToolCallStatus.TOOL_CALL_WAITING_APPROVAL,
+    approvalAction: ApprovalAction.UNSPECIFIED,
+  });
+  const completedWithStaleAction = create(ToolCallSchema, {
+    id: "tc-completed",
+    name: "Read",
+    status: ToolCallStatus.TOOL_CALL_COMPLETED,
+    approvalAction: ApprovalAction.APPROVE,
+  });
+  const subAgentWaiting = create(ToolCallSchema, {
+    id: "tc-sub",
+    name: "Shell",
+    status: ToolCallStatus.TOOL_CALL_WAITING_APPROVAL,
+    approvalAction: ApprovalAction.APPROVE,
+  });
+  return create(AgentExecutionStatusSchema, {
+    messages: [
+      create(AgentMessageSchema, { type: MessageType.MESSAGE_AI, toolCalls: [waitingApproved, waitingUndecided] }),
+      create(AgentMessageSchema, { type: MessageType.MESSAGE_AI, toolCalls: [completedWithStaleAction, waitingRejected] }),
+    ],
+    subAgentExecutions: [
+      create(SubAgentExecutionSchema, {
+        messages: [create(AgentMessageSchema, { type: MessageType.MESSAGE_AI, toolCalls: [subAgentWaiting] })],
+      }),
+    ],
+  });
+}
+
+describe("approvalDecisionsOf", () => {
+  it("reads every WAITING row with a verdict, in transcript order, and nothing else", () => {
+    const decisions = approvalDecisionsOf(transcriptWithEveryRowShape());
+    expect([...decisions.entries()]).toEqual([
+      ["tc-approved", ApprovalAction.APPROVE],
+      ["tc-rejected", ApprovalAction.REJECT],
+    ]);
+  });
+
+  it("an undecided WAITING row, a COMPLETED row with a stale verdict, and a sub-agent row are all excluded", () => {
+    const decisions = approvalDecisionsOf(transcriptWithEveryRowShape());
+    expect(decisions.has("tc-undecided"), "no verdict yet").toBe(false);
+    expect(decisions.has("tc-completed"), "already executed; the verdict on it is history").toBe(false);
+    expect(decisions.has("tc-sub"), "sub-agent transcripts are not the top-level rows").toBe(false);
+  });
+
+  it("is empty on a fresh status", () => {
+    expect(approvalDecisionsOf(create(AgentExecutionStatusSchema, {})).size).toBe(0);
+  });
+});
+
+function facts(overrides: Partial<ReinvocationFacts> = {}): ReinvocationFacts {
+  return {
+    approvalDecisions: new Map(),
+    reconciledFileReview: false,
+    fileReviewFailed: false,
+    fileReviewFailureDetail: "",
+    discardedPaths: [],
+    ...overrides,
+  };
+}
+
+describe("decideReinvocation", () => {
+  it("a first turn, or a resume that decided nothing and reconciled nothing, runs the agent", () => {
+    expect(decideReinvocation(facts())).toBeUndefined();
+  });
+
+  it("any REJECT among the adjudicated decisions fails the turn, whatever else was decided", () => {
+    const decisions = new Map([
+      ["tc-1", ApprovalAction.APPROVE],
+      ["tc-2", ApprovalAction.REJECT],
+    ]);
+    expect(decideReinvocation(facts({ approvalDecisions: decisions }))).toEqual({ kind: "rejected-by-user" });
+  });
+
+  it("approvals without a reject run the agent, even when file review was also reconciled", () => {
+    const decisions = new Map([["tc-1", ApprovalAction.APPROVE]]);
+    expect(decideReinvocation(facts({ approvalDecisions: decisions, reconciledFileReview: true }))).toBeUndefined();
+    expect(
+      decideReinvocation(facts({ approvalDecisions: new Map([["tc-1", ApprovalAction.SKIP]]) })),
+      "a SKIP is not a reject",
+    ).toBeUndefined();
+  });
+
+  it("a pure file-review resume completes, carrying the reconcile's facts", () => {
+    expect(decideReinvocation(facts({ reconciledFileReview: true }))).toEqual({
+      kind: "file-review-resolved",
+      failed: false,
+      failureDetail: "",
+      discardedPaths: [],
+    });
+    expect(
+      decideReinvocation(
+        facts({
+          reconciledFileReview: true,
+          fileReviewFailed: true,
+          fileReviewFailureDetail: "src/a.ts changed after review",
+          discardedPaths: ["src/b.ts"],
+        }),
+      ),
+    ).toEqual({
+      kind: "file-review-resolved",
+      failed: true,
+      failureDetail: "src/a.ts changed after review",
+      discardedPaths: ["src/b.ts"],
+    });
+  });
+});

package/src/harness/__tests__/usage-accumulator.test.ts

@@ -0,0 +1,83 @@
+/**
+ * The runtime's usage accounting over priced deltas: the token-accounting
+ * convention the Usage widget and the billing parity test depend on, the
+ * audit-trail fields, and the rule that the accumulator adds and never
+ * prices. The pricing half is `execute-cursor/__tests__/usage-pricing.test.ts`.
+ */
+
+import { describe, it, expect } from "vitest";
+import { ServiceTier, ThinkingMode } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+
+import { UsageAccumulator } from "../usage-accumulator.js";
+
+describe("UsageAccumulator", () => {
+  it("reports total_tokens as input + output (cache is a subset of input, not additive)", () => {
+    const acc = new UsageAccumulator();
+
+    // Two turns. cacheRead/cacheWrite are subsets of inputTokens.
+    acc.addTurn({ inputTokens: 100, outputTokens: 50, cacheReadTokens: 30, cacheWriteTokens: 10 });
+    acc.addTurn({ inputTokens: 300, outputTokens: 20, cacheReadTokens: 200, cacheWriteTokens: 0 });
+
+    const snap = acc.snapshot();
+
+    expect(snap.inputTokens).toBe(400n);
+    expect(snap.outputTokens).toBe(70n);
+    expect(snap.cacheReadTokens).toBe(230n);
+    expect(snap.cacheWriteTokens).toBe(10n);
+    // True total = input + output = 470. NOT 470 + 230 + 10 (which would
+    // double-count the cached tokens already inside inputTokens).
+    expect(snap.totalTokens).toBe(470n);
+    expect(snap.turnCount).toBe(2);
+  });
+
+  it("returns an empty snapshot when no turns were observed", () => {
+    const acc = new UsageAccumulator();
+    const snap = acc.snapshot();
+    expect(acc.hasTurns).toBe(false);
+    expect(snap.totalTokens).toBe(0n);
+    expect(snap.turnCount).toBe(0);
+    expect(snap.estimatedCostUsd).toBe(0);
+  });
+
+  it("treats missing token fields as zero", () => {
+    const acc = new UsageAccumulator();
+    acc.addTurn({ inputTokens: 42 });
+    const snap = acc.snapshot();
+    expect(snap.inputTokens).toBe(42n);
+    expect(snap.outputTokens).toBe(0n);
+    expect(snap.totalTokens).toBe(42n);
+  });
+
+  it("sums the adapter's stated cost and never prices on its own", () => {
+    const acc = new UsageAccumulator();
+    acc.addTurn({ inputTokens: 1_000_000, estimatedCostUsd: 0.25 });
+    acc.addTurn({ inputTokens: 1_000_000, estimatedCostUsd: 0.5 });
+    acc.addTurn({ inputTokens: 1_000_000 });
+    expect(acc.snapshot().estimatedCostUsd).toBeCloseTo(0.75, 9);
+  });
+
+  it("records the latest stated price basis; a delta without one inherits it (#357 audit trail)", () => {
+    const acc = new UsageAccumulator(ServiceTier.FAST, ThinkingMode.DISABLED);
+    acc.addTurn({ inputTokens: 10, model: "composer-2.5", requestedModelParams: '[{"id":"fast","value":"true"}]' });
+    acc.addTurn({ inputTokens: 5 });
+    const snap = acc.snapshot();
+    expect(snap.model).toBe("composer-2.5");
+    expect(snap.requestedModelParams).toBe('[{"id":"fast","value":"true"}]');
+    expect(snap.requestedServiceTier).toBe(ServiceTier.FAST);
+  });
+
+  it("records an empty basis when no delta named one", () => {
+    const acc = new UsageAccumulator(ServiceTier.STANDARD, ThinkingMode.DISABLED);
+    acc.addTurn({ inputTokens: 1 });
+    const snap = acc.snapshot();
+    expect(snap.model).toBe("");
+    expect(snap.requestedModelParams).toBe("");
+    expect(snap.requestedServiceTier).toBe(ServiceTier.STANDARD);
+  });
+
+  it("records the requested thinking mode into the snapshot (#772 audit trail)", () => {
+    const acc = new UsageAccumulator(ServiceTier.STANDARD, ThinkingMode.ENABLED);
+    acc.addTurn({ inputTokens: 10, outputTokens: 5 });
+    expect(acc.snapshot().requestedThinkingMode).toBe(ThinkingMode.ENABLED);
+  });
+});

package/src/harness/capabilities.ts

@@ -20,6 +20,7 @@
  * | `subAgents`       | yes (compiled sub-graphs)   | yes (`agents` option)                   | yes (`AgentDefinition`)                       | no                                             |
  * | `toolRestriction` | yes (tool list)             | no (the hook enforces)                  | yes (`disallowedTools`, `tools`)              | per-server config                              |
  * | `visionProfile`   | PNG, JPEG, WebP, GIF        | PNG, JPEG (transport re-sniffs)         | (surveyed later)                              | (surveyed later)                               |
+ * | `fileReview`      | `deep-agent`, no excludes   | `cursor`, `.cursor/hooks.json` excluded | (surveyed later)                              | (surveyed later)                               |
  *
  * Adapter-internal, deliberately NOT flags: how MCP servers are bound, how
  * metering is routed, how the cost cap is applied inside the engine, how a
@@ -61,6 +62,20 @@ export type PausePrimitive = "interrupt" | "deny-and-retry" | "callback" | "none
  */
 export type StateIdSource = "deterministic" | "engine-minted";
 
+/**
+ * The two facts the runtime's file-review reconcile needs from the harness
+ * and cannot know: the id the projection reads from the BASELINE payload
+ * (`shared/filereview/capture.ts` `applyCaptureDecisions`), and the
+ * workspace-relative paths the harness writes into the repo that a turn's
+ * diff must never show (Cursor's transient `.cursor/hooks.json`). Declared
+ * once per adapter, read by `turn-context.ts` (ruled Q-M2-6 as an argument,
+ * homed here at M3).
+ */
+export interface FileReviewIdentity {
+  readonly harnessId: string;
+  readonly excludePaths: readonly string[];
+}
+
 export interface HarnessCapabilities {
   readonly pausePrimitive: PausePrimitive;
   readonly stateIdSource: StateIdSource;
@@ -72,4 +87,6 @@ export interface HarnessCapabilities {
   readonly toolRestriction: boolean;
   /** Which image types the engine can display inline; the runtime degrades the rest before the turn. */
   readonly visionProfile: VisionProfile;
+  /** How the harness's captured file changes are identified and what its own repo writes are excluded from a diff. */
+  readonly fileReview: FileReviewIdentity;
 }