@stigmer/runner 3.0.9-dev.20260615153829 → 3.1.0

package/src/shared/__tests__/artifact-storage-extended.test.ts

@@ -67,6 +67,20 @@ describe("LocalArtifactStorage", () => {
     });
   });
 
+  describe("download", () => {
+    it("round-trips uploaded content byte-exact", async () => {
+      await storage.upload("exec-1/file.txt", Buffer.from("round-trip"));
+      const got = await storage.download("exec-1/file.txt");
+      expect(got.toString("utf-8")).toBe("round-trip");
+    });
+
+    it("throws a key-scoped error for a missing key", async () => {
+      await expect(storage.download("missing.txt")).rejects.toThrow(
+        /Artifact not found for key 'missing\.txt'/,
+      );
+    });
+  });
+
   describe("exists", () => {
     it("returns true after upload", async () => {
       await storage.upload("present.txt", Buffer.from("data"));
@@ -140,24 +154,62 @@ describe("ProxyArtifactStorage", () => {
     expect(url).toBe("https://r2.example.com/download/key.txt");
   });
 
-  it("exists returns true when presign succeeds", async () => {
+  it("download resolves a presigned URL then fetches the bytes", async () => {
     const storage = new ProxyArtifactStorage("https://proxy.example.com", "tok");
 
-    globalThis.fetch = vi.fn().mockResolvedValueOnce({
-      ok: true,
-      json: async () => ({ url: "https://r2.example.com/dl" }),
-    } as any);
+    globalThis.fetch = vi.fn()
+      .mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({ url: "https://r2.example.com/dl/key.txt" }),
+      } as any)
+      .mockResolvedValueOnce({
+        ok: true,
+        arrayBuffer: async () => new TextEncoder().encode("proxy-bytes").buffer,
+      } as any);
+
+    const got = await storage.download("key.txt");
+    expect(got.toString("utf-8")).toBe("proxy-bytes");
+  });
+
+  it("download throws with HTTP status and key on a failed fetch", async () => {
+    const storage = new ProxyArtifactStorage("https://proxy.example.com", "tok");
+
+    globalThis.fetch = vi.fn()
+      .mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({ url: "https://r2.example.com/dl/missing.txt" }),
+      } as any)
+      .mockResolvedValueOnce({
+        ok: false,
+        status: 404,
+        text: async () => "not found",
+      } as any);
+
+    await expect(storage.download("missing.txt")).rejects.toThrow(
+      /Artifact download failed \(HTTP 404\) for key 'missing\.txt'/,
+    );
+  });
+
+  it("exists returns true when the object is present (presign + ranged GET)", async () => {
+    const storage = new ProxyArtifactStorage("https://proxy.example.com", "tok");
+
+    // Two-step probe: presign mints the URL, then a ranged GET hits the object.
+    // Presign success alone is NOT existence — the object fetch is authoritative.
+    globalThis.fetch = vi.fn(async (input: string | URL | Request) => {
+      const url = typeof input === "string" ? input : input.toString();
+      if (url.includes("presigned-download-url")) {
+        return new Response(JSON.stringify({ url: "https://r2.example.com/dl" }), { status: 200 });
+      }
+      return new Response(Buffer.from("x"), { status: 206 });
+    }) as typeof fetch;
 
     expect(await storage.exists("key.txt")).toBe(true);
   });
 
-  it("exists returns false when presign fails", async () => {
+  it("exists returns false when the presign endpoint fails", async () => {
     const storage = new ProxyArtifactStorage("https://proxy.example.com", "tok");
 
-    globalThis.fetch = vi.fn().mockResolvedValueOnce({
-      ok: false,
-      status: 404,
-    } as any);
+    globalThis.fetch = vi.fn(async () => new Response("nope", { status: 404 })) as typeof fetch;
 
     expect(await storage.exists("missing.txt")).toBe(false);
   });

package/src/shared/__tests__/artifact-storage.test.ts

@@ -65,6 +65,38 @@ describe("LocalArtifactStorage", () => {
     const written = await readFile(join(tempDir, key));
     expect(written.toString()).toBe("v2");
   });
+
+  it("downloads uploaded text bytes byte-exact (inverse of upload)", async () => {
+    const key = "artifacts/exec-1/report.txt";
+    await storage.upload(key, Buffer.from("hello world"));
+    const got = await storage.download(key);
+    expect(got.toString()).toBe("hello world");
+  });
+
+  it("downloads binary bytes (incl. NUL) byte-exact", async () => {
+    const key = "artifacts/exec-1/blob.bin";
+    const bytes = Buffer.from([0x00, 0x01, 0xff, 0xfe, 0x00, 0x89, 0x50]);
+    await storage.upload(key, bytes);
+    const got = await storage.download(key);
+    expect(Buffer.compare(got, bytes)).toBe(0);
+  });
+
+  it("throws a key-scoped error when downloading a missing key", async () => {
+    await expect(storage.download("artifacts/exec-1/missing.bin")).rejects.toThrow(
+      /Artifact not found for key 'artifacts\/exec-1\/missing\.bin'/,
+    );
+  });
+
+  it("reads directly off disk even with an unreachable serve URL (no HTTP dependency)", async () => {
+    // A bogus, unroutable serve base: if `download` fetched over HTTP this would
+    // hang/throw. Reading straight off disk proves the runner's read-back does
+    // not depend on the serve URL being set or reachable.
+    const s = new LocalArtifactStorage(tempDir, "http://127.0.0.1:0");
+    const key = "artifacts/exec-1/offline.txt";
+    await s.upload(key, Buffer.from("served-from-disk"));
+    const got = await s.download(key);
+    expect(got.toString()).toBe("served-from-disk");
+  });
 });
 
 // ── ProxyArtifactStorage ─────────────────────────────────────────────
@@ -126,7 +158,7 @@ describe("ProxyArtifactStorage", () => {
         }
         // Build a real Headers from what the runner passed, so concatenation /
         // case-folding behavior matches a live PUT.
-        resolve(new Headers(init?.headers as HeadersInit));
+        resolve(new Headers(init?.headers as ConstructorParameters<typeof Headers>[0]));
         return new Response(null, { status: 200 });
       }) as typeof fetch;
     });
@@ -219,32 +251,112 @@ describe("ProxyArtifactStorage", () => {
     expect(url).toBe("https://r2.example.com/dl");
   });
 
-  it("exists returns true on 200", async () => {
-    globalThis.fetch = vi.fn(async () =>
-      new Response(JSON.stringify({ url: "https://r2.example.com/dl" }), { status: 200 }),
-    ) as typeof fetch;
+  it("downloads by resolving a presigned URL then fetching it", async () => {
+    globalThis.fetch = vi.fn(async (input: string | URL | Request) => {
+      const url = typeof input === "string" ? input : input.toString();
+      if (url.includes("presigned-download-url")) {
+        return new Response(JSON.stringify({ url: "https://r2.example.com/dl" }), { status: 200 });
+      }
+      if (url === "https://r2.example.com/dl") {
+        return new Response(Buffer.from("payload-bytes"), { status: 200 });
+      }
+      return new Response("not found", { status: 404 });
+    }) as typeof fetch;
+
+    const storage = new ProxyArtifactStorage("https://proxy.example.com", "tok");
+    const got = await storage.download("artifacts/exec-1/f.txt");
+    expect(got.toString()).toBe("payload-bytes");
+  });
+
+  it("throws with the HTTP status and key when the download fetch fails", async () => {
+    globalThis.fetch = vi.fn(async (input: string | URL | Request) => {
+      const url = typeof input === "string" ? input : input.toString();
+      if (url.includes("presigned-download-url")) {
+        return new Response(JSON.stringify({ url: "https://r2.example.com/dl" }), { status: 200 });
+      }
+      return new Response("gone", { status: 404 });
+    }) as typeof fetch;
+
+    const storage = new ProxyArtifactStorage("https://proxy.example.com", "tok");
+    await expect(storage.download("artifacts/exec-1/missing.txt")).rejects.toThrow(
+      /Artifact download failed \(HTTP 404\) for key 'artifacts\/exec-1\/missing\.txt'/,
+    );
+  });
+
+  // exists() is a TWO-step probe: presign the download URL, then a 1-byte ranged
+  // GET against the object. The presign endpoint mints a URL for ANY key, so the
+  // OBJECT fetch — not the presign — is the source of truth for existence.
+  function mockProxyFetch(objectResponse: () => Response) {
+    globalThis.fetch = vi.fn(async (input: string | URL | Request) => {
+      const url = typeof input === "string" ? input : input.toString();
+      if (url.includes("presigned-download-url")) {
+        return new Response(JSON.stringify({ url: "https://r2.example.com/obj" }), { status: 200 });
+      }
+      return objectResponse();
+    }) as typeof fetch;
+  }
 
+  it("exists returns true when the object GET is 200", async () => {
+    mockProxyFetch(() => new Response(Buffer.from("x"), { status: 200 }));
     const storage = new ProxyArtifactStorage("https://proxy.example.com", "tok");
     expect(await storage.exists("key")).toBe(true);
   });
 
-  it("exists returns false on 404", async () => {
-    globalThis.fetch = vi.fn(async () =>
-      new Response("not found", { status: 404 }),
-    ) as typeof fetch;
+  it("exists returns true when the object GET is 206 (ranged)", async () => {
+    mockProxyFetch(() => new Response(Buffer.from("x"), { status: 206 }));
+    const storage = new ProxyArtifactStorage("https://proxy.example.com", "tok");
+    expect(await storage.exists("key")).toBe(true);
+  });
 
+  it("exists returns true on 416 (0-byte object, range unsatisfiable but present)", async () => {
+    mockProxyFetch(() => new Response("", { status: 416 }));
+    const storage = new ProxyArtifactStorage("https://proxy.example.com", "tok");
+    expect(await storage.exists("key")).toBe(true);
+  });
+
+  it("exists returns false when presign succeeds but the object 404s (regression: presign != existence)", async () => {
+    // The exact proxy bug: the presign endpoint mints a URL for a nonexistent key;
+    // only the object fetch reveals it is absent. The old exists() returned true
+    // here (presign.ok), which crashed the file-review reconcile on the R2 404.
+    mockProxyFetch(() => new Response("<Error><Code>NoSuchKey</Code></Error>", { status: 404 }));
     const storage = new ProxyArtifactStorage("https://proxy.example.com", "tok");
     expect(await storage.exists("key")).toBe(false);
   });
 
-  it("exists returns false on network error", async () => {
+  it("exists probes the object with a 1-byte ranged GET (never a HEAD, which breaks the presign signature)", async () => {
+    const seen: Array<{ url: string; range: string | null; method: string }> = [];
+    globalThis.fetch = vi.fn(async (input: string | URL | Request, init?: RequestInit) => {
+      const url = typeof input === "string" ? input : input.toString();
+      if (url.includes("presigned-download-url")) {
+        return new Response(JSON.stringify({ url: "https://r2.example.com/obj" }), { status: 200 });
+      }
+      seen.push({
+        url,
+        range: new Headers(init?.headers).get("range"),
+        method: (init?.method ?? "GET").toUpperCase(),
+      });
+      return new Response(Buffer.from("x"), { status: 206 });
+    }) as typeof fetch;
+    const storage = new ProxyArtifactStorage("https://proxy.example.com", "tok");
+    await storage.exists("key");
+    expect(seen).toEqual([{ url: "https://r2.example.com/obj", range: "bytes=0-0", method: "GET" }]);
+  });
+
+  it("exists returns false when the presign endpoint is unreachable", async () => {
     globalThis.fetch = vi.fn(async () => {
       throw new Error("network unreachable");
     }) as typeof fetch;
-
     const storage = new ProxyArtifactStorage("https://proxy.example.com", "tok");
     expect(await storage.exists("key")).toBe(false);
   });
+
+  it("exists throws on an unexpected object status (a fault, not an existence answer)", async () => {
+    mockProxyFetch(() => new Response("boom", { status: 500 }));
+    const storage = new ProxyArtifactStorage("https://proxy.example.com", "tok");
+    await expect(storage.exists("key")).rejects.toThrow(
+      /Artifact existence check failed \(HTTP 500\) for key 'key'/,
+    );
+  });
 });
 
 // ── Factory ──────────────────────────────────────────────────────────

package/src/shared/__tests__/file-change.test.ts

@@ -0,0 +1,85 @@
+import { describe, it, expect } from "vitest";
+import {
+  looksBinary,
+  bytesLookBinary,
+  resolveWorkspacePath,
+} from "../file-change.js";
+
+describe("looksBinary", () => {
+  it("flags content containing a NUL byte", () => {
+    expect(looksBinary("PNG\u0000\u0000IHDR")).toBe(true);
+  });
+
+  it("does not flag plain UTF-8 text, including unicode and empty", () => {
+    expect(looksBinary("hello world")).toBe(false);
+    expect(looksBinary("héllo — 世界 \n\t")).toBe(false);
+    expect(looksBinary("")).toBe(false);
+  });
+});
+
+describe("bytesLookBinary", () => {
+  it("flags raw bytes containing a NUL", () => {
+    expect(bytesLookBinary(Buffer.from([0x89, 0x50, 0x00, 0x4e]))).toBe(true);
+    expect(bytesLookBinary(new Uint8Array([0x00]))).toBe(true);
+  });
+
+  it("does not flag NUL-free bytes (text, or high bytes without a NUL)", () => {
+    expect(bytesLookBinary(Buffer.from("hello world", "utf8"))).toBe(false);
+    expect(bytesLookBinary(Buffer.from("héllo — 世界", "utf8"))).toBe(false);
+    expect(bytesLookBinary(Buffer.from([0xff, 0xfe, 0x80]))).toBe(false);
+    expect(bytesLookBinary(Buffer.alloc(0))).toBe(false);
+  });
+});
+
+describe("resolveWorkspacePath", () => {
+  const root = "/work/space";
+
+  describe("native (virtualRoot=true)", () => {
+    it("strips a leading slash and joins under the root", () => {
+      // "/src/app.ts" is the deepagents virtual-root convention; the display
+      // path drops the leading slash and the absolute path lives under root.
+      expect(resolveWorkspacePath("/src/app.ts", root, true)).toEqual({
+        path: "src/app.ts",
+        absolutePath: "/work/space/src/app.ts",
+      });
+    });
+
+    it("passes a bare relative path through and joins it", () => {
+      expect(resolveWorkspacePath("src/app.ts", root, true)).toEqual({
+        path: "src/app.ts",
+        absolutePath: "/work/space/src/app.ts",
+      });
+    });
+
+    it("normalizes a leading ./ segment", () => {
+      expect(resolveWorkspacePath("./README.md", root, true)).toEqual({
+        path: "README.md",
+        absolutePath: "/work/space/README.md",
+      });
+    });
+  });
+
+  describe("cursor (virtualRoot=false)", () => {
+    it("makes an absolute path under the root relative for display", () => {
+      expect(resolveWorkspacePath("/work/space/src/app.ts", root, false)).toEqual({
+        path: "src/app.ts",
+        absolutePath: "/work/space/src/app.ts",
+      });
+    });
+
+    it("displays an absolute path outside the root as-is (never an escaping ../)", () => {
+      const outside = "/etc/hosts";
+      expect(resolveWorkspacePath(outside, root, false)).toEqual({
+        path: outside,
+        absolutePath: outside,
+      });
+    });
+
+    it("treats a relative path the same as the virtual case", () => {
+      expect(resolveWorkspacePath("src/app.ts", root, false)).toEqual({
+        path: "src/app.ts",
+        absolutePath: "/work/space/src/app.ts",
+      });
+    });
+  });
+});

package/src/shared/__tests__/file-tools.test.ts

@@ -0,0 +1,90 @@
+/**
+ * Unit tests for the unified file-modifying-tool introspection.
+ *
+ * This module is the single source of truth both harnesses' gate capture now
+ * shares, so these pin the cross-taxonomy field coverage AND the load-bearing
+ * guardrail: whole-file content (`content`/`contents`/`file_content`) must stay
+ * strictly separate from an edit's replacement (`new_string`/…). Conflating them
+ * would make an edit look like a whole-file capture and read the wrong `before`.
+ */
+
+import { describe, it, expect } from "vitest";
+import {
+  isFileModifyingTool,
+  extractFilePath,
+  extractWriteContent,
+  extractEditOldString,
+  extractEditNewString,
+} from "../file-tools.js";
+
+describe("isFileModifyingTool", () => {
+  it("recognizes the native (deepagents) taxonomy", () => {
+    for (const name of ["write_file", "edit_file", "create_file", "write", "edit", "create", "str_replace_editor"]) {
+      expect(isFileModifyingTool(name), name).toBe(true);
+    }
+  });
+
+  it("recognizes the Cursor taxonomy (hook + SDK names)", () => {
+    for (const name of ["Write", "StrReplace", "EditNotebook"]) {
+      expect(isFileModifyingTool(name), name).toBe(true);
+    }
+  });
+
+  it("excludes read-only, delete, and unknown tools (no content/hunk to preview)", () => {
+    for (const name of ["read", "Read", "delete", "Delete", "shell", "Shell", "grep", "mystery"]) {
+      expect(isFileModifyingTool(name), name).toBe(false);
+    }
+  });
+});
+
+describe("extractFilePath", () => {
+  it("spans both taxonomies' path fields, including notebook target", () => {
+    expect(extractFilePath({ path: "a.ts" })).toBe("a.ts");
+    expect(extractFilePath({ file_path: "b.ts" })).toBe("b.ts");
+    expect(extractFilePath({ target_notebook: "nb.ipynb" })).toBe("nb.ipynb");
+  });
+
+  it("returns null when no recognized path key is present", () => {
+    expect(extractFilePath({ content: "no path here" })).toBeNull();
+    expect(extractFilePath({})).toBeNull();
+  });
+});
+
+describe("extractWriteContent (whole-file body)", () => {
+  it("reads the whole-file content fields and preserves an empty file", () => {
+    expect(extractWriteContent({ content: "x" })).toBe("x");
+    expect(extractWriteContent({ contents: "y" })).toBe("y");
+    expect(extractWriteContent({ file_content: "z" })).toBe("z");
+    expect(extractWriteContent({ content: "" })).toBe(""); // empty file is real
+  });
+
+  it("GUARDRAIL: never treats an edit's new_string as whole-file content", () => {
+    // An edit fragment must NOT be picked up here, or the gate would read the
+    // wrong before and mislabel an edit as a whole-file rewrite.
+    expect(extractWriteContent({ new_string: "frag" })).toBeNull();
+    expect(extractWriteContent({ old_string: "a", new_string: "b" })).toBeNull();
+    expect(extractWriteContent({ replacement: "r" })).toBeNull();
+  });
+});
+
+describe("extractEditOldString / extractEditNewString (edit fragments)", () => {
+  it("reads the old/new replacement fields across variants", () => {
+    expect(extractEditOldString({ old_string: "a" })).toBe("a");
+    expect(extractEditOldString({ old_text: "a" })).toBe("a");
+    expect(extractEditOldString({ oldText: "a" })).toBe("a");
+    expect(extractEditNewString({ new_string: "b" })).toBe("b");
+    expect(extractEditNewString({ new_text: "b" })).toBe("b");
+    expect(extractEditNewString({ newText: "b" })).toBe("b");
+    expect(extractEditNewString({ replacement: "b" })).toBe("b");
+  });
+
+  it("preserves an empty string (insertion / deletion fragments)", () => {
+    expect(extractEditOldString({ old_string: "" })).toBe(""); // insertion
+    expect(extractEditNewString({ new_string: "" })).toBe(""); // deletion
+  });
+
+  it("returns null when the fragment is absent", () => {
+    expect(extractEditOldString({ content: "whole" })).toBeNull();
+    expect(extractEditNewString({ content: "whole" })).toBeNull();
+  });
+});

package/src/shared/__tests__/fingerprint-secret.test.ts

@@ -0,0 +1,51 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+
+const ENV_VAR = "STIGMER_RUNNER_HITL_SECRET";
+
+// The module memoizes its secret, so each test re-imports a fresh module copy via
+// vi.resetModules() to exercise the source-precedence + fallback paths cleanly.
+async function freshSecretModule() {
+  vi.resetModules();
+  return import("../fingerprint-secret.js");
+}
+
+describe("getRunnerHitlMasterSecret", () => {
+  const original = process.env[ENV_VAR];
+
+  beforeEach(() => {
+    delete process.env[ENV_VAR];
+  });
+
+  afterEach(() => {
+    if (original === undefined) delete process.env[ENV_VAR];
+    else process.env[ENV_VAR] = original;
+    vi.restoreAllMocks();
+  });
+
+  it("uses the env var (UTF-8) when set", async () => {
+    process.env[ENV_VAR] = "my-stable-secret";
+    const { getRunnerHitlMasterSecret } = await freshSecretModule();
+    expect(Buffer.from(getRunnerHitlMasterSecret() as Buffer).toString("utf-8")).toBe("my-stable-secret");
+  });
+
+  it("falls back to a per-process random secret and warns once when unset", async () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const { getRunnerHitlMasterSecret } = await freshSecretModule();
+
+    const a = Buffer.from(getRunnerHitlMasterSecret() as Buffer);
+    const b = Buffer.from(getRunnerHitlMasterSecret() as Buffer);
+
+    expect(a.length).toBe(32);
+    expect(a.equals(b)).toBe(true); // memoized: stable within the process
+    expect(warn).toHaveBeenCalledTimes(1); // warned once, not per call
+  });
+
+  it("two separate processes (module loads) get different random fallbacks", async () => {
+    vi.spyOn(console, "warn").mockImplementation(() => {});
+    const m1 = await freshSecretModule();
+    const s1 = Buffer.from(m1.getRunnerHitlMasterSecret() as Buffer);
+    const m2 = await freshSecretModule();
+    const s2 = Buffer.from(m2.getRunnerHitlMasterSecret() as Buffer);
+    expect(s1.equals(s2)).toBe(false);
+  });
+});

package/src/shared/__tests__/lease-scope-corpus.test.ts

@@ -0,0 +1,56 @@
+/**
+ * Cross-edition lease-scope derivation parity.
+ *
+ * Loads the shared corpus (apis/testdata/hitl/lease-scope/vectors.json) and
+ * asserts the TS {@link deriveLeaseScope} agrees with it. The Go
+ * (lease_scope_corpus_test.go) and Java (LeaseScopeFixtureTest) editions load
+ * the same file, so a drift in any edition fails one of the three suites — the
+ * guarantee that an APPROVE_ALL clicked in one edition leases the same class
+ * everywhere.
+ */
+
+import { describe, it, expect } from "vitest";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { deriveLeaseScope } from "../approval-policy.js";
+
+interface LeaseScopeVector {
+  name: string;
+  input: { toolName: string; mcpServerSlug?: string };
+  expected: { category: string } | { server: string } | null;
+}
+
+const vectorsPath = fileURLToPath(
+  new URL(
+    "../../../../../../apis/testdata/hitl/lease-scope/vectors.json",
+    import.meta.url,
+  ),
+);
+const corpus = JSON.parse(readFileSync(vectorsPath, "utf-8")) as {
+  vectors: LeaseScopeVector[];
+};
+
+/** Normalize the discriminated union to the corpus's plain JSON shape. */
+function asExpected(
+  scope: ReturnType<typeof deriveLeaseScope>,
+): { category: string } | { server: string } | null {
+  if (!scope) return null;
+  return scope.kind === "server"
+    ? { server: scope.server }
+    : { category: scope.category };
+}
+
+describe("lease-scope derivation vector corpus", () => {
+  it("loads a non-trivial corpus", () => {
+    expect(corpus.vectors.length).toBeGreaterThanOrEqual(10);
+  });
+
+  for (const v of corpus.vectors) {
+    it(`vector: ${v.name}`, () => {
+      const actual = asExpected(
+        deriveLeaseScope(v.input.toolName, v.input.mcpServerSlug ?? ""),
+      );
+      expect(actual).toEqual(v.expected);
+    });
+  }
+});