@intentius/chant-lexicon-fly 0.49.0 → 0.51.0

package/src/components/run-agent-conformance.test.ts

@@ -0,0 +1,352 @@
+/**
+ * `run-agent` contract/conformance suite (#1944, epic #1564 phase 4 — the
+ * final child of #1564). All offline, against the in-process Sprites fake
+ * (`../op/activities/sprites-fake.ts`, S7) and an injected `ProcessRunner`
+ * mock (`@intentius/chant/components/verbs/__tests__/mock-process-runner`) —
+ * no HTTP/WS to a real endpoint, no `docker`/`cosign`.
+ *
+ * Distinct from `./run-agent.test.ts` (#1942/#1943's own unit tests, which
+ * call the capability directly) in one important way: the tests here run
+ * `run-agent` through the actual *component saga* — core's driver
+ * (`@intentius/chant/components`'s `runComponentDeploy`, ../capability.ts's
+ * `CapabilityRegistry`) — proving the driver-level contract the epic's phase
+ * 4 bar requires, not just the capability's own `run()`/`rollback()` pair
+ * called back to back.
+ *
+ * Three things proved here:
+ *
+ *  1. **Saga-unwind restore.** A composition where `run-agent` succeeds, a
+ *     LATER step throws, and the saga unwinds — the sprite must be restored
+ *     to the pre-run checkpoint, through `driver.ts`'s `rollbackExecuted`, not
+ *     the Op-level `onFailure` path `examples/sprites-agent-task` already
+ *     demonstrates.
+ *  2. **The durable-identity channel (#1944's scope addition, from #1949's
+ *     review).** On the Temporal durable path, `run()` and `rollback()`
+ *     execute as separate Activities, each rebuilding `input` fresh — the
+ *     in-process `WeakMap` `run-agent`'s capability keeps never gets a hit
+ *     there. `Capability.rollback` grew an optional third `output` parameter
+ *     for exactly this (`../../../packages/core/src/components/capability.ts`),
+ *     and `run-agent`'s own rollback prefers it. This file proves the
+ *     capability's own logic honors that channel — simulating the Activity
+ *     boundary directly (a completely different `input` object at rollback
+ *     time, no WeakMap hit possible) — while
+ *     `lexicons/temporal/src/component-op/runtime.test.ts` proves the
+ *     generated *codegen* actually threads it end to end through a real
+ *     Temporal worker.
+ *  3. **Attestation conformance, as a composition.** The
+ *     `run-agent -> sign -> attest-provenance -> verify` chain, run through
+ *     the driver (not called capability-by-capability, which `./run-agent.
+ *     test.ts` already covers) — reusing #1951's helpers
+ *     (`buildRunAgentProvenanceStatement`, `createMockProcessRunner`) rather
+ *     than duplicating them. A tampered/missing attestation makes `verify`
+ *     throw `VerificationFailedError`, and the composition fails before any
+ *     `Apply` phase step runs.
+ */
+import { describe, test, expect, beforeAll, afterAll } from "vitest";
+import { createSpritesFake } from "../op/activities/sprites-fake";
+import { createFlyRunAgentCapability, createFlySpriteActivities } from "./run-agent";
+import type { RunAgentInput, RunAgentOutput } from "@intentius/chant/components/verbs/run-agent";
+import { RUN_AGENT_BUILD_TYPE } from "@intentius/chant/components/verbs/run-agent";
+import { createSignCapability, createAttestProvenanceCapability } from "@intentius/chant/components/verbs/sign";
+import { createVerifyCapability, VerificationFailedError } from "@intentius/chant/components/verbs/verify";
+import { createMockProcessRunner } from "@intentius/chant/components/verbs/__tests__/mock-process-runner";
+import {
+  CapabilityRegistry,
+  runComponentDeploy,
+  type Capability,
+  type DeployContext,
+  type DriverComponent,
+} from "@intentius/chant/components";
+
+const ctx: DeployContext = { env: "dev", component: "agent-turn" };
+
+let fake: { url: string; close(): Promise<void> };
+let prevBaseUrl: string | undefined;
+
+beforeAll(async () => {
+  fake = await createSpritesFake();
+  prevBaseUrl = process.env.SPRITES_BASE_URL;
+  process.env.SPRITES_BASE_URL = fake.url;
+});
+
+afterAll(async () => {
+  if (prevBaseUrl === undefined) delete process.env.SPRITES_BASE_URL;
+  else process.env.SPRITES_BASE_URL = prevBaseUrl;
+  await fake?.close();
+});
+
+/** A fake capability that always fails — stands in for "some later step in the composition breaks," triggering saga rollback. */
+function alwaysFailsCapability(kind: string): Capability<Record<string, unknown>, never> {
+  return {
+    kind,
+    async run(): Promise<never> {
+      throw new Error(`${kind}: forced failure for saga-unwind conformance`);
+    },
+  };
+}
+
+/** A fake capability recording every `run()` call — stands in for an apply-style step that must never run once an earlier gate refuses. */
+function markerCapability(kind: string, calls: unknown[]): Capability<Record<string, unknown>, { ok: true }> {
+  return {
+    kind,
+    async run(_c, input): Promise<{ ok: true }> {
+      calls.push(input);
+      return { ok: true };
+    },
+  };
+}
+
+describe("run-agent — saga-unwind restore through the component driver (#1944)", () => {
+  test("run-agent succeeds, a LATER step throws, and the saga unwinds — the sprite is restored to the pre-run checkpoint", async () => {
+    // A reused (not freshly created) sprite: run-agent never destroys it on
+    // success, so rollback has something real to restore afterward.
+    const sprites = createFlySpriteActivities();
+    const spriteName = `saga-unwind-${Date.now()}`;
+    await sprites.create({ name: spriteName });
+
+    const registry = new CapabilityRegistry();
+    registry.register(createFlyRunAgentCapability());
+    registry.register(alwaysFailsCapability("always-fails"));
+
+    const component: DriverComponent = {
+      name: "agent-turn",
+      dependsOn: [],
+      deploy: [
+        {
+          phase: "Run",
+          steps: [
+            {
+              kind: "run-agent",
+              agent: "echo hi > /work/output",
+              task: { prompt: "irrelevant for this scripted command" },
+              workspace: { spriteName },
+            },
+          ],
+        },
+        { phase: "Verify", steps: [{ kind: "always-fails" }] },
+      ],
+    };
+
+    const result = await runComponentDeploy(component, ctx, registry, {});
+
+    expect(result.ok).toBe(false);
+    const runRecord = result.records.find((r) => r.phase === "Run" && r.kind === "run-agent");
+    expect(runRecord?.status).toBe("ok");
+    const rollbackRecord = result.records.find((r) => r.phase === "Run" && r.kind === "run-agent" && r.status === "rolled-back");
+    expect(rollbackRecord).toBeDefined();
+
+    // Observably restored: /work/output was written during the run, and the
+    // pre-run checkpoint predates that write — a direct read now 404s.
+    await expect(sprites.readFile({ id: spriteName, path: "/work/output" })).rejects.toThrow();
+  });
+
+  test("a step with a native rollback is never reported as rollback-opted-out during the same unwind", async () => {
+    const sprites = createFlySpriteActivities();
+    const spriteName = `saga-unwind-optout-${Date.now()}`;
+    await sprites.create({ name: spriteName });
+
+    const registry = new CapabilityRegistry();
+    registry.register(createFlyRunAgentCapability());
+    registry.register(alwaysFailsCapability("always-fails"));
+
+    const component: DriverComponent = {
+      name: "agent-turn",
+      dependsOn: [],
+      deploy: [
+        {
+          phase: "Run",
+          steps: [
+            {
+              kind: "run-agent",
+              agent: "echo hi > /work/output",
+              task: { prompt: "irrelevant" },
+              workspace: { spriteName },
+            },
+          ],
+        },
+        { phase: "Verify", steps: [{ kind: "always-fails" }] },
+      ],
+    };
+
+    const result = await runComponentDeploy(component, ctx, registry, {});
+    const optedOut = result.records.filter((r) => r.kind === "run-agent" && r.status === "rollback-opted-out");
+    expect(optedOut).toHaveLength(0);
+  });
+});
+
+describe("run-agent — durable identity channel (#1944, scope addition from #1949's review)", () => {
+  test("rollback restores via output.spriteId/checkpointId even when called with a freshly-rebuilt input object (no WeakMap hit) — the Temporal Activity-boundary shape", async () => {
+    // On the Temporal durable path, rollbackCapabilityStep resolves its own
+    // fresh `resolvedInput` from JSON every call
+    // (lexicons/temporal/src/component-op/activities.ts) — never the same
+    // object run() was called with. This test reproduces that exact shape
+    // directly against the real capability, without needing a Temporal
+    // worker: build input, run(), then rollback() with a DIFFERENT (shallow-
+    // cloned) input object, passing run()'s own output as the third
+    // parameter — the durable identity channel.
+    const capability = createFlyRunAgentCapability();
+    const spriteName = `durable-identity-${Date.now()}`;
+    const sprites = createFlySpriteActivities();
+    await sprites.create({ name: spriteName });
+
+    const runInput: RunAgentInput = {
+      agent: "echo hi > /work/output",
+      task: { prompt: "irrelevant for this scripted command" },
+      workspace: { spriteName },
+    };
+    const output = await capability.run(ctx, runInput);
+    expect(output.turn.status).toBe("completed");
+
+    // A structurally-equal but reference-DIFFERENT object — resolveStepInput
+    // (../../../packages/core/src/components/driver.ts) rebuilds exactly this
+    // shape fresh on every Activity call; the WeakMap keyed by runInput's
+    // object identity cannot possibly have a hit for this object.
+    const rebuiltInput: RunAgentInput = JSON.parse(JSON.stringify(runInput));
+    expect(rebuiltInput).not.toBe(runInput);
+
+    await capability.rollback?.(ctx, rebuiltInput, output);
+
+    // Restored despite the fresh input object: the pre-run checkpoint predates
+    // the write, so a direct read now 404s.
+    await expect(sprites.readFile({ id: spriteName, path: "/work/output" })).rejects.toThrow();
+  });
+
+  test("without the output parameter (a caller that never threads it) and no WeakMap hit, rollback degrades to an explicit no-op — the documented pre-#1944 behavior for a caller that doesn't opt in", async () => {
+    const capability = createFlyRunAgentCapability();
+    const spriteName = `no-identity-${Date.now()}`;
+    const sprites = createFlySpriteActivities();
+    await sprites.create({ name: spriteName });
+
+    const runInput: RunAgentInput = {
+      agent: "echo hi > /work/output",
+      task: { prompt: "irrelevant" },
+      workspace: { spriteName },
+    };
+    await capability.run(ctx, runInput);
+
+    const rebuiltInput: RunAgentInput = JSON.parse(JSON.stringify(runInput));
+    // No third argument at all: neither the WeakMap (different object) nor
+    // `output` has anything to restore by for spriteId/checkpointId — but
+    // `workspace.spriteName` is still present, so rollback falls back to
+    // comment-based restore rather than a bare no-op.
+    await capability.rollback?.(ctx, rebuiltInput);
+
+    // Comment-based restore still finds the "pre-run" checkpoint via
+    // workspace.spriteName, so this still restores correctly — the pure
+    // no-op only happens with no spriteId at all (see run-agent.ts's
+    // rollback()), which needs a freshly-created (not spriteName-reused)
+    // sprite to reach; that path stays a no-op by design (nothing to
+    // identify) and isn't newly broken by this change.
+    await expect(sprites.readFile({ id: spriteName, path: "/work/output" })).rejects.toThrow();
+  });
+});
+
+// ── #1944 design point 3: attestation conformance as a composition ─────────
+
+describe("run-agent -> sign -> attest-provenance -> verify, run as a component composition through the driver (#1944)", () => {
+  const POLICY = {
+    expectedIssuer: "https://token.actions.githubusercontent.com",
+    expectedIdentity: "https://github.com/my-org/my-repo/.github/workflows/release.yml@refs/heads/main",
+  };
+
+  function buildChainComponent(): DriverComponent {
+    return {
+      name: "agent-turn",
+      dependsOn: [],
+      deploy: [
+        {
+          phase: "Run",
+          steps: [
+            {
+              kind: "run-agent",
+              agent: "echo hi > /work/output",
+              task: { prompt: "irrelevant for this scripted command" },
+              workspace: {},
+            },
+          ],
+        },
+        { phase: "Sign", steps: [{ kind: "sign", imageRef: "@Run.attestationRef" }] },
+        {
+          phase: "Attest",
+          steps: [
+            {
+              kind: "attest-provenance",
+              imageRef: "@Run.attestationRef",
+              provenance: "@Run.provenance",
+              builderId: "https://github.com/actions/runner",
+              buildType: RUN_AGENT_BUILD_TYPE,
+              externalParameters: { agent: "echo hi > /work/output" },
+              internalParameters: {
+                spriteId: "@Run.spriteId",
+                checkpointId: "@Run.checkpointId",
+                turnStatus: "@Run.turn.status",
+                turnExitCode: "@Run.turn.exitCode",
+              },
+            },
+          ],
+        },
+        { phase: "Verify", steps: [{ kind: "verify", imageRef: "@Run.attestationRef", policy: POLICY }] },
+        { phase: "Apply", steps: [{ kind: "apply-marker" }] },
+      ],
+    };
+  }
+
+  test("the full chain succeeds and the Apply phase runs", async () => {
+    const proc = createMockProcessRunner();
+    const applyCalls: unknown[] = [];
+    const registry = new CapabilityRegistry();
+    registry.register(createFlyRunAgentCapability());
+    registry.register(createSignCapability(proc.runner));
+    registry.register(createAttestProvenanceCapability(proc.runner));
+    registry.register(createVerifyCapability(proc.runner));
+    registry.register(markerCapability("apply-marker", applyCalls));
+
+    const result = await runComponentDeploy(buildChainComponent(), ctx, registry, {});
+
+    expect(result.ok).toBe(true);
+    expect(applyCalls).toHaveLength(1);
+
+    const verifyRecord = result.records.find((r) => r.kind === "verify");
+    expect(verifyRecord?.status).toBe("ok");
+    expect(verifyRecord?.output).toMatchObject({ verified: true, checked: ["signature", "provenance"] });
+
+    // The wiring actually resolved a real, digest-qualified attestationRef —
+    // not a passthrough literal — proving @Run.* references threaded through
+    // sign/attest-provenance/verify exactly as #1943 designed.
+    const runOutput = result.records.find((r) => r.kind === "run-agent")?.output as RunAgentOutput;
+    expect(runOutput.attestationRef).toMatch(/^agent-turn\/run-agent@sha256:[0-9a-f]{64}$/);
+  });
+
+  test("a tampered/missing attestation makes verify throw VerificationFailedError, and the composition fails before the Apply phase ever runs", async () => {
+    const proc = createMockProcessRunner({
+      failures: { "cosign verify-attestation": "Error: no matching attestations found for the given subject digest" },
+    });
+    const applyCalls: unknown[] = [];
+    const registry = new CapabilityRegistry();
+    registry.register(createFlyRunAgentCapability());
+    registry.register(createSignCapability(proc.runner));
+    registry.register(createAttestProvenanceCapability(proc.runner));
+    registry.register(createVerifyCapability(proc.runner));
+    registry.register(markerCapability("apply-marker", applyCalls));
+
+    const result = await runComponentDeploy(buildChainComponent(), ctx, registry, {});
+
+    expect(result.ok).toBe(false);
+    // Apply never ran: runComponentDeploy stops at the first failing phase —
+    // the "Apply" DriverPhase is never entered at all once "Verify" throws.
+    expect(applyCalls).toHaveLength(0);
+
+    const verifyRecord = result.records.find((r) => r.kind === "verify");
+    expect(verifyRecord?.status).toBe("fail");
+    expect(verifyRecord?.error).toContain("verification failed");
+
+    // Confirm the underlying capability really throws VerificationFailedError
+    // (runComponentDeploy's fail record only carries the stringified message,
+    // per driver.ts's runCapabilityStep) — same assertion ./run-agent.test.ts
+    // makes when calling verify directly, reused here rather than re-derived.
+    const verifyCapability = createVerifyCapability(proc.runner);
+    await expect(
+      verifyCapability.run(ctx, { imageRef: "agent-turn/run-agent@sha256:" + "0".repeat(64), policy: POLICY }),
+    ).rejects.toThrow(VerificationFailedError);
+  });
+});

package/src/components/run-agent.test.ts

@@ -0,0 +1,302 @@
+/**
+ * Tests the fly lexicon's `run-agent` adapter (#1942, epic #1564 phase 2):
+ * the real `SpriteActivities` implementation (`./run-agent.ts`) against the
+ * offline in-process sprites fake (`../op/activities/sprites-fake.ts`, S7) —
+ * no HTTP/WS to a real endpoint, no Docker, so this runs in CI the same way
+ * `../op/activities/sprites.integration.test.ts` does. Core's own
+ * `run()`/`rollback()` sequencing tests live in
+ * `packages/core/src/components/verbs/run-agent.test.ts` against a
+ * hand-written fake; this file is specifically about the real wire-level
+ * reclassification (the exec-throw finding) and the real activities wired
+ * end to end.
+ */
+import { describe, test, expect, beforeAll, afterAll } from "vitest";
+import { createSpritesFake } from "../op/activities/sprites-fake";
+import { createFlyRunAgentCapability, createFlySpriteActivities, parseSpriteExecFailure } from "./run-agent";
+import {
+  buildRunAgentProvenanceStatement,
+  extractTranscriptDigest,
+  RUN_AGENT_BUILD_TYPE,
+  type RunAgentInput,
+} from "@intentius/chant/components/verbs/run-agent";
+import {
+  createAttestProvenanceCapability,
+  createSignCapability,
+  SignTargetNotDigestError,
+} from "@intentius/chant/components/verbs/sign";
+import {
+  createVerifyCapability,
+  VerificationFailedError,
+} from "@intentius/chant/components/verbs/verify";
+import { createMockProcessRunner } from "@intentius/chant/components/verbs/__tests__/mock-process-runner";
+
+const ctx = { env: "dev", component: "review-agent" };
+
+let fake: { url: string; close(): Promise<void> };
+let prevBaseUrl: string | undefined;
+
+beforeAll(async () => {
+  fake = await createSpritesFake();
+  prevBaseUrl = process.env.SPRITES_BASE_URL;
+  process.env.SPRITES_BASE_URL = fake.url;
+});
+
+afterAll(async () => {
+  if (prevBaseUrl === undefined) delete process.env.SPRITES_BASE_URL;
+  else process.env.SPRITES_BASE_URL = prevBaseUrl;
+  await fake?.close();
+});
+
+describe("parseSpriteExecFailure — the exec-throw reclassification's pure parser", () => {
+  test("parses the exit code and combined output out of spriteExec's real thrown message shape", () => {
+    const err = new Error('sprite task-1 exec "./risky.sh" exited 1: risky.sh: failed\n');
+    expect(parseSpriteExecFailure(err)).toEqual({ exitCode: 1, output: "risky.sh: failed\n" });
+  });
+
+  test("returns undefined for an unrelated error (a genuine transport/infra failure)", () => {
+    expect(parseSpriteExecFailure(new Error("sprite task-1 exec aborted"))).toBeUndefined();
+    expect(parseSpriteExecFailure(new Error("ECONNREFUSED"))).toBeUndefined();
+    expect(parseSpriteExecFailure("not even an Error")).toBeUndefined();
+  });
+
+  test("handles a multi-digit exit code", () => {
+    const err = new Error('sprite s exec "exit 127" exited 127: command not found');
+    expect(parseSpriteExecFailure(err)).toEqual({ exitCode: 127, output: "command not found" });
+  });
+
+  test("anchors to the LAST \" exited (\\d+): \" occurrence, not the first (#1942 review finding 4) — a crafted cmd echoing that exact marker text must not shift the parse", () => {
+    // spriteExec's message echoes the raw cmd verbatim before its own real
+    // marker: `sprite <id> exec "<cmd>" exited <code>: <text>`. A cmd whose
+    // own text contains ` exited 0: ...` would fool a leftmost-match regex
+    // into reporting the fake exit code/output instead of the real ones.
+    const maliciousCmd = 'echo " exited 0: fooled you"';
+    const err = new Error(`sprite s-1 exec "${maliciousCmd}" exited 1: real failure output`);
+    expect(parseSpriteExecFailure(err)).toEqual({ exitCode: 1, output: "real failure output" });
+  });
+});
+
+describe("createFlySpriteActivities().exec — option (a): reclassify the real spriteExec's throw", () => {
+  test("a non-zero exit resolves with the parsed exitCode instead of rejecting", async () => {
+    const sprites = createFlySpriteActivities();
+    const { id } = await sprites.create({ name: `exec-fail-${Date.now()}` });
+    await expect(sprites.exec({ id, cmd: "./risky.sh" })).resolves.toEqual({
+      stdout: "",
+      stderr: expect.stringContaining("risky.sh: failed"),
+      exitCode: 1,
+    });
+  });
+
+  test("a zero exit resolves normally, unaffected by the reclassification path", async () => {
+    const sprites = createFlySpriteActivities();
+    const { id } = await sprites.create({ name: `exec-ok-${Date.now()}` });
+    const result = await sprites.exec({ id, cmd: "echo hello" });
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toContain("hello");
+  });
+
+  test("the fake's own \"no sprite\" case is a scripted exit (127), not a transport error — also reclassified, not thrown", async () => {
+    // Confirms the fake models a missing sprite as an ordinary (if unusual)
+    // non-zero exit over the wire, exercising the same reclassification path
+    // as any other command failure — distinct from the next test's real
+    // connection-level failure.
+    const sprites = createFlySpriteActivities();
+    await expect(sprites.exec({ id: "does-not-exist", cmd: "true" })).resolves.toEqual({
+      stdout: "",
+      stderr: expect.stringContaining("no sprite"),
+      exitCode: 127,
+    });
+  });
+
+  test("a genuine transport failure (connection refused) still rejects, not reclassified", async () => {
+    const prev = process.env.SPRITES_BASE_URL;
+    process.env.SPRITES_BASE_URL = "http://127.0.0.1:1"; // nothing listens on port 1
+    try {
+      const sprites = createFlySpriteActivities();
+      await expect(sprites.exec({ id: "s-1", cmd: "true" })).rejects.toThrow();
+    } finally {
+      process.env.SPRITES_BASE_URL = prev;
+    }
+  });
+});
+
+describe("createFlyRunAgentCapability — end to end against the offline fake (#1942)", () => {
+  test("a successful turn: create -> checkpoint -> stage -> exec -> collect -> destroy", async () => {
+    const capability = createFlyRunAgentCapability();
+    const input: RunAgentInput = {
+      agent: "echo hi > /work/output", // unrecognized "runtime" -> passthrough (see core's buildRuntimeCommand)
+      task: { prompt: "irrelevant for this scripted command" },
+      workspace: {},
+    };
+
+    const output = await capability.run(ctx, input);
+
+    expect(output.turn.status).toBe("completed");
+    expect(output.turn.exitCode).toBe(0);
+    expect(output.artifacts.files).toEqual([
+      { path: "/work/output", digest: expect.stringMatching(/^sha256:[0-9a-f]{64}$/) },
+    ]);
+
+    // Destroyed on success — the sprite is gone, so a direct read 404s.
+    const sprites = createFlySpriteActivities();
+    await expect(sprites.readFile({ id: output.spriteId, path: "/work/output" })).rejects.toThrow();
+  });
+
+  test("a failed turn (real spriteExec throw, reclassified): status \"failed\", no throw, sprite left alive, rollback restores it", async () => {
+    const capability = createFlyRunAgentCapability();
+    const input: RunAgentInput = {
+      agent: "./risky.sh", // the fake's scripted failing job (lexicons/fly/.../sprites-fake.ts): mutates /work/output then exits 1
+      task: { prompt: "irrelevant for this scripted command" },
+      workspace: {},
+    };
+
+    const output = await capability.run(ctx, input);
+
+    expect(output.turn.status).toBe("failed");
+    expect(output.turn.exitCode).toBe(1);
+    expect(output.artifacts.files).toEqual([
+      { path: "/work/output", digest: expect.stringMatching(/^sha256:[0-9a-f]{64}$/) },
+    ]);
+
+    // Left alive: reading it back directly still works (not destroyed).
+    const sprites = createFlySpriteActivities();
+    const { content } = await sprites.readFile({ id: output.spriteId, path: "/work/output" });
+    expect(content).toBe("partial-corrupt");
+
+    // rollback() restores the pre-run checkpoint — /work/output never existed
+    // at that point (the checkpoint predates both staging and exec).
+    await capability.rollback?.(ctx, input);
+    await expect(sprites.readFile({ id: output.spriteId, path: "/work/output" })).rejects.toThrow();
+  });
+
+  test("reuses an existing sprite when workspace.spriteName is given — no create, no destroy", async () => {
+    const sprites = createFlySpriteActivities();
+    const name = `warm-${Date.now()}`;
+    await sprites.create({ name });
+
+    const capability = createFlyRunAgentCapability();
+    const input: RunAgentInput = {
+      agent: "echo warm > /work/output",
+      task: { prompt: "n/a" },
+      workspace: { spriteName: name },
+    };
+    const output = await capability.run(ctx, input);
+
+    expect(output.spriteId).toBe(name);
+    // Still alive post-success (reuse is never destroyed) — a direct read succeeds.
+    const { content } = await sprites.readFile({ id: name, path: "/work/output" });
+    expect(content).toContain("warm");
+  });
+});
+
+// ── #1943: provenance + attestation, verify-gate interop over a real turn ───
+
+describe("run-agent -> sign -> attest-provenance -> verify (#1943), a real turn against the offline sprites-fake", () => {
+  const POLICY = {
+    expectedIssuer: "https://token.actions.githubusercontent.com",
+    expectedIdentity: "https://github.com/my-org/my-repo/.github/workflows/release.yml@refs/heads/main",
+  };
+
+  test("a valid attestation over a real sprite turn's output passes sign/attest-provenance/verify completely unmodified", async () => {
+    const capability = createFlyRunAgentCapability();
+    const input: RunAgentInput = {
+      agent: "echo hi > /work/output",
+      task: { prompt: "irrelevant for this scripted command" },
+      workspace: {},
+    };
+
+    // A real turn against the offline fake — not a hand-rolled SpriteActivities mock.
+    const output = await capability.run(ctx, input);
+    expect(output.turn.status).toBe("completed");
+    expect(output.attestationRef).toMatch(/^review-agent\/run-agent@sha256:[0-9a-f]{64}$/);
+
+    const proc = createMockProcessRunner();
+    const signCapability = createSignCapability(proc.runner);
+    const attestCapability = createAttestProvenanceCapability(proc.runner);
+    const verifyCapability = createVerifyCapability(proc.runner);
+
+    // sign/attest-provenance accept output.attestationRef exactly like any
+    // other digest-qualified imageRef — no new code path, no
+    // SignTargetNotDigestError.
+    const signOutput = await signCapability.run(ctx, { imageRef: output.attestationRef });
+    expect(signOutput).toEqual({ imageRef: output.attestationRef, signed: true, method: "keyless" });
+
+    const statement = buildRunAgentProvenanceStatement(input, output, "https://github.com/actions/runner");
+    expect(statement.predicateType).toBe("https://slsa.dev/provenance/v1");
+    expect(statement.predicate.buildDefinition.buildType).toBe(RUN_AGENT_BUILD_TYPE);
+
+    const attestOutput = await attestCapability.run(ctx, {
+      imageRef: output.attestationRef,
+      provenance: output.provenance,
+      builderId: "https://github.com/actions/runner",
+      buildType: RUN_AGENT_BUILD_TYPE,
+      externalParameters: { agent: input.agent },
+      internalParameters: {
+        spriteId: output.spriteId,
+        checkpointId: output.checkpointId,
+        turnStatus: output.turn.status,
+        turnExitCode: output.turn.exitCode,
+      },
+    });
+    expect(attestOutput.attested).toBe(true);
+
+    // The unmodified verify gate (imageRef: "@RunAgent.attestationRef" in a
+    // real component's step wiring) accepts it — no requireProvenance
+    // override, no predicateType plumbing needed on the verify side (see
+    // packages/core/src/components/verbs/run-agent.ts's doc comment,
+    // "Predicate-type decision, made").
+    const verifyOutput = await verifyCapability.run(ctx, { imageRef: output.attestationRef, policy: POLICY });
+    expect(verifyOutput).toEqual({ verified: true, checked: ["signature", "provenance"] });
+  });
+
+  test("the same unmodified verify gate refuses when the attestation doesn't check out", async () => {
+    const capability = createFlyRunAgentCapability();
+    const input: RunAgentInput = {
+      agent: "echo hi > /work/output",
+      task: { prompt: "irrelevant for this scripted command" },
+      workspace: {},
+    };
+    const output = await capability.run(ctx, input);
+
+    // Simulates a tampered/missing attestation the same way verify.test.ts's
+    // own "FAILS the deploy on missing/invalid provenance" suite does — cosign
+    // itself is the one that would refuse a mismatched digest or a stripped
+    // attestation in reality; this proves `verify` (composed after
+    // `run-agent`, unmodified) propagates that refusal as
+    // VerificationFailedError rather than passing the gate silently.
+    const proc = createMockProcessRunner({
+      failures: { "cosign verify-attestation": "Error: no matching attestations found for the given subject digest" },
+    });
+    const verifyCapability = createVerifyCapability(proc.runner);
+
+    await expect(
+      verifyCapability.run(ctx, { imageRef: output.attestationRef, policy: POLICY }),
+    ).rejects.toThrow(VerificationFailedError);
+  });
+
+  test("a turn whose output differs by one byte produces a different attestationRef — verifying the original digest against the tampered turn's evidence would target the wrong subject", async () => {
+    const capability = createFlyRunAgentCapability();
+    const original = await capability.run(ctx, {
+      agent: "echo original > /work/output",
+      task: { prompt: "irrelevant for this scripted command" },
+      workspace: {},
+    });
+    const tampered = await capability.run(ctx, {
+      agent: "echo tampered > /work/output",
+      task: { prompt: "irrelevant for this scripted command" },
+      workspace: {},
+    });
+
+    expect(original.attestationRef).not.toBe(tampered.attestationRef);
+    expect(extractTranscriptDigest(original.provenance.sourceRef)).not.toBe(
+      extractTranscriptDigest(tampered.provenance.sourceRef),
+    );
+  });
+
+  test("refuses to sign a non-digest-shaped reference the same way it would for any other verb — attestationRef is always digest-qualified by construction", async () => {
+    const proc = createMockProcessRunner();
+    const signCapability = createSignCapability(proc.runner);
+    await expect(signCapability.run(ctx, { imageRef: "review-agent/run-agent:latest" })).rejects.toThrow(
+      SignTargetNotDigestError,
+    );
+  });
+});