@stigmer/runner 3.15.1 → 3.15.2-dev.20260913223433

package/src/runner-manager.ts

@@ -226,11 +226,6 @@ export async function createStigmerRunnerManager(
   // in-process embedders like the desktop never execute main.ts.
   captureRunnerSecrets();
 
-  const { registerStigmerDeepagentsProfiles } = await import(
-    "./activities/execute-deep-agent/deepagents-profiles.js"
-  );
-  registerStigmerDeepagentsProfiles();
-
   // `tokenRef` holds the control-plane token (the host's durable credential,
   // e.g. the desktop's Auth0 token) and is shared with activity clients via
   // config.stigmerTokenRef. The proxy credential (x-stigmer-auth) is managed
@@ -745,7 +740,6 @@ async function createAllActivities(config: Config): Promise<WorkerActivities> {
   const [
     { HARNESS_ADAPTERS },
     { createHarnessActivities },
-    { createDeepAgentActivities },
     { createEnsureThreadActivities },
     { createGenerateSessionSubjectActivities },
     { createClassifyToolApprovalsActivities },
@@ -765,7 +759,6 @@ async function createAllActivities(config: Config): Promise<WorkerActivities> {
   ] = await Promise.all([
     import("./harness-adapters.js"),
     import("./harness/registry.js"),
-    import("./activities/execute-deep-agent/index.js"),
     import("./activities/ensure-thread.js"),
     import("./activities/generate-session-subject.js"),
     import("./activities/classify-tool-approvals.js"),
@@ -786,7 +779,6 @@ async function createAllActivities(config: Config): Promise<WorkerActivities> {
 
   return {
     ...(await createHarnessActivities(HARNESS_ADAPTERS, config)),
-    ...createDeepAgentActivities(config),
     ...createEnsureThreadActivities(),
     ...createGenerateSessionSubjectActivities(config),
     ...createClassifyToolApprovalsActivities(config),

package/src/runner.ts

@@ -201,11 +201,6 @@ export async function createStigmerRunner(
   // for in-process embedders.
   captureRunnerSecrets();
 
-  const { registerStigmerDeepagentsProfiles } = await import(
-    "./activities/execute-deep-agent/deepagents-profiles.js"
-  );
-  registerStigmerDeepagentsProfiles();
-
   const baseConfig = mapOptionsToConfig(options);
 
   assertLlmBackendsPreflight(baseConfig.proxyEndpoint);
@@ -462,7 +457,6 @@ async function createAllActivities(config: Config): Promise<WorkerActivities> {
   const [
     { HARNESS_ADAPTERS },
     { createHarnessActivities },
-    { createDeepAgentActivities },
     { createEnsureThreadActivities },
     { createGenerateSessionSubjectActivities },
     { createClassifyToolApprovalsActivities },
@@ -482,7 +476,6 @@ async function createAllActivities(config: Config): Promise<WorkerActivities> {
   ] = await Promise.all([
     import("./harness-adapters.js"),
     import("./harness/registry.js"),
-    import("./activities/execute-deep-agent/index.js"),
     import("./activities/ensure-thread.js"),
     import("./activities/generate-session-subject.js"),
     import("./activities/classify-tool-approvals.js"),
@@ -503,7 +496,6 @@ async function createAllActivities(config: Config): Promise<WorkerActivities> {
 
   return {
     ...(await createHarnessActivities(HARNESS_ADAPTERS, config)),
-    ...createDeepAgentActivities(config),
     ...createEnsureThreadActivities(),
     ...createGenerateSessionSubjectActivities(config),
     ...createClassifyToolApprovalsActivities(config),

package/src/shared/__tests__/attachment-naming.test.ts

@@ -1,13 +1,11 @@
-import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
 import { mkdtempSync, readFileSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { uniquifyFilename, allocateUniqueName } from "../attachment-naming.js";
-import { injectAttachments } from "../../activities/execute-deep-agent/attachment-injector.js";
 import { resolveAttachments } from "../attachment-resolver.js";
 import { getPlatformDir } from "../workspace/platform-dir.js";
 import { makeInMemoryArtifactStorage } from "../../__test-utils__/fake-artifact-storage.js";
-import type { WorkspaceBackend } from "../workspace/types.js";
 
 describe("uniquifyFilename", () => {
   // This table is the byte-for-byte twin of the React SDK suite
@@ -118,7 +116,7 @@ describe("cross-harness naming parity", () => {
     } as any;
   }
 
-  it("both harnesses produce identical final basenames for the same duplicate-heavy list", async () => {
+  it("the resolver produces the React SDK's basenames for the same duplicate-heavy list", async () => {
     const { storage } = makeInMemoryArtifactStorage();
     await storage.upload("attachments/01A/data.csv", Buffer.from("a"), "text/plain");
     await storage.upload("attachments/01B/data.csv", Buffer.from("b"), "text/plain");
@@ -131,14 +129,8 @@ describe("cross-harness naming parity", () => {
       makeAttachment("Makefile", "attachments/01D/Makefile"),
     ];
 
-    const backend = { writeFileBuffer: vi.fn() } as unknown as WorkspaceBackend;
-    const injected = await injectAttachments({
-      backend,
-      attachments,
-      storage,
-      isLocalMode: false,
-    });
-
+    // One attachment pipeline serves both harnesses since S3 M2b (Q-S3-14);
+    // the names it lands are the ones the React SDK's table above predicts.
     const resolved = await resolveAttachments(attachments, {
       sessionId,
       primaryWorkspaceDir: workspaceDir,
@@ -146,13 +138,8 @@ describe("cross-harness naming parity", () => {
       storage,
     });
 
-    const injectedNames = injected.map((f) => f.filename);
-    const resolvedNames = resolved.map((r) => r.filename);
-    expect(injectedNames).toEqual(["data.csv", "data-2.csv", "Makefile", "Makefile-2"]);
-    expect(resolvedNames).toEqual(injectedNames);
-    expect(injected.map((f) => f.renamedFrom)).toEqual(
-      resolved.map((r) => r.renamedFrom),
-    );
+    expect(resolved.map((r) => r.filename)).toEqual(["data.csv", "data-2.csv", "Makefile", "Makefile-2"]);
+    expect(resolved.map((r) => r.renamedFrom)).toEqual([undefined, "data.csv", undefined, "Makefile"]);
     // The resolver's files really land under the renamed paths.
     expect(readFileSync(join(platformDir, "inputs", "data-2.csv"), "utf-8")).toBe("b");
   });

package/src/shared/__tests__/attachment-resolver.test.ts

@@ -1,14 +1,19 @@
 /**
- * Tests for the attachment resolver, which the Cursor activity calls today
- * and the turn runtime takes over in S2 M3 (S3 retires the native twin,
- * execute-deep-agent/attachment-injector.ts).
+ * Tests for the attachment resolver — the turn runtime's attachment phase,
+ * the one pipeline for both harnesses since S3 M2b (the native twin,
+ * `attachment-injector.ts`, retired then; its ZIP guards moved to
+ * `attachment-zip.ts` at S3 M1).
  *
  * The load-bearing behaviors: storage-key attachments materialize under the
  * platform inputs dir (the universal path — every server-created attachment
  * carries a storage key), the workspace `.stigmer` symlink exists even when
  * the agent has no skills, and any attachment that cannot be materialized
  * fails the resolution loudly (the silent-skip regression behind "plan file
- * wasn't found").
+ * wasn't found"). Since S3 M1 (Q-S3-14, Q-M1-2) the resolver is the one
+ * attachment pipeline for every harness, so it also pins the two behaviors
+ * lifted from the native injector: `extract` archives land under their mount
+ * directory through the shared #567 guards, and an explicit `mountPath` is
+ * honoured inside the `inputs/` namespace and refused outside it.
  */
 
 import { describe, it, expect, beforeEach, afterEach } from "vitest";
@@ -16,6 +21,8 @@ import { mkdtempSync, writeFileSync, readFileSync, rmSync, lstatSync, readlinkSy
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { resolveAttachments, AttachmentResolutionError } from "../attachment-resolver.js";
+import { AttachmentValidationError } from "../attachment-zip.js";
+import { buildZip } from "@stigmer/zip-structure/testing";
 import { getPlatformDir } from "../workspace/platform-dir.js";
 import { makeInMemoryArtifactStorage } from "../../__test-utils__/fake-artifact-storage.js";
 import { CURSOR_VISION_PROFILE, VisionBudget } from "../attachment-vision.js";
@@ -83,6 +90,7 @@ describe("resolveAttachments", () => {
       {
         filename: "plan.md",
         relativePath: ".stigmer/inputs/plan.md",
+        sizeBytes: 10,
         downloadUrl: "mem://attachments/01ABC/plan.md",
       },
     ]);
@@ -115,7 +123,7 @@ describe("resolveAttachments", () => {
     );
 
     expect(result).toEqual([
-      { filename: "data.csv", relativePath: ".stigmer/inputs/data.csv" },
+      { filename: "data.csv", relativePath: ".stigmer/inputs/data.csv", sizeBytes: 5 },
     ]);
     expect(readFileSync(join(platformDir, "inputs", "data.csv"), "utf-8")).toBe("a,b,c");
   });
@@ -139,11 +147,13 @@ describe("resolveAttachments", () => {
       {
         filename: "report.pdf",
         relativePath: ".stigmer/inputs/report.pdf",
+        sizeBytes: 11,
         downloadUrl: "mem://attachments/01AAA/report.pdf",
       },
       {
         filename: "report-2.pdf",
         relativePath: ".stigmer/inputs/report-2.pdf",
+        sizeBytes: 12,
         renamedFrom: "report.pdf",
         downloadUrl: "mem://attachments/01BBB/report.pdf",
       },
@@ -169,10 +179,11 @@ describe("resolveAttachments", () => {
     // The key-less local file lists no URL; the storage twin does — the
     // per-file split the prompt renders.
     expect(result).toEqual([
-      { filename: "notes.md", relativePath: ".stigmer/inputs/notes.md" },
+      { filename: "notes.md", relativePath: ".stigmer/inputs/notes.md", sizeBytes: 10 },
       {
         filename: "notes-2.md",
         relativePath: ".stigmer/inputs/notes-2.md",
+        sizeBytes: 13,
         renamedFrom: "notes.md",
         downloadUrl: "mem://attachments/01ABC/notes.md",
       },
@@ -242,6 +253,7 @@ describe("resolveAttachments", () => {
       {
         filename: "evil.md",
         relativePath: ".stigmer/inputs/evil.md",
+        sizeBytes: 9,
         downloadUrl: "mem://attachments/01ABC/x",
       },
     ]);
@@ -260,11 +272,148 @@ describe("resolveAttachments", () => {
     );
 
     expect(result).toEqual([
-      { filename: "evil.txt", relativePath: ".stigmer/inputs/evil.txt" },
+      { filename: "evil.txt", relativePath: ".stigmer/inputs/evil.txt", sizeBytes: 15 },
     ]);
     expect(readFileSync(join(platformDir, "inputs", "evil.txt"), "utf-8")).toBe("local-contained");
   });
 
+  // ── Explicit mountPath: honoured inside the inputs namespace, refused outside ──
+
+  describe("mountPath (S3 M1, Q-M1-2)", () => {
+    it("places a file at its explicit `inputs/…` path, in every spelling the producers use", async () => {
+      const { storage } = makeInMemoryArtifactStorage();
+      await storage.upload("k/a", Buffer.from("A"), "text/plain");
+      await storage.upload("k/b", Buffer.from("B"), "text/plain");
+      await storage.upload("k/c", Buffer.from("C"), "text/plain");
+
+      const result = await resolveAttachments(
+        [
+          makeAttachment({ filename: "a.txt", storageKey: "k/a", mountPath: "inputs/data/a.txt" }),
+          makeAttachment({ filename: "b.txt", storageKey: "k/b", mountPath: ".stigmer/inputs/b-renamed.txt" }),
+          makeAttachment({ filename: "c.txt", storageKey: "k/c", mountPath: "/inputs/c.txt" }),
+        ],
+        options({ storage }),
+      );
+
+      expect(result.map((r) => r.relativePath)).toEqual([
+        ".stigmer/inputs/data/a.txt",
+        ".stigmer/inputs/b-renamed.txt",
+        ".stigmer/inputs/c.txt",
+      ]);
+      expect(result.map((r) => r.filename), "the on-disk basename, not the attachment's").toEqual(["a.txt", "b-renamed.txt", "c.txt"]);
+      expect(readFileSync(join(platformDir, "inputs", "data", "a.txt"), "utf-8")).toBe("A");
+      expect(readFileSync(join(platformDir, "inputs", "b-renamed.txt"), "utf-8")).toBe("B");
+    });
+
+    it("a default-named attachment uniquifies around a name an explicit path claims directly under inputs/", async () => {
+      const { storage } = makeInMemoryArtifactStorage();
+      await storage.upload("k/explicit", Buffer.from("explicit"), "text/plain");
+      await storage.upload("k/default", Buffer.from("default"), "text/plain");
+
+      const result = await resolveAttachments(
+        [
+          makeAttachment({ filename: "other.txt", storageKey: "k/explicit", mountPath: "inputs/plan.md" }),
+          makeAttachment({ filename: "plan.md", storageKey: "k/default" }),
+        ],
+        options({ storage }),
+      );
+
+      expect(result.map(({ filename, relativePath, renamedFrom }) => ({ filename, relativePath, renamedFrom }))).toEqual([
+        { filename: "plan.md", relativePath: ".stigmer/inputs/plan.md", renamedFrom: undefined },
+        { filename: "plan-2.md", relativePath: ".stigmer/inputs/plan-2.md", renamedFrom: "plan.md" },
+      ]);
+      expect(readFileSync(join(platformDir, "inputs", "plan.md"), "utf-8")).toBe("explicit");
+      expect(readFileSync(join(platformDir, "inputs", "plan-2.md"), "utf-8")).toBe("default");
+    });
+
+    it("refuses two attachments explicitly pinning the same path (a contradiction no rename resolves), before any bytes move", async () => {
+      const { storage } = makeInMemoryArtifactStorage();
+      await expect(
+        resolveAttachments(
+          [
+            makeAttachment({ filename: "a.csv", storageKey: "k/a", mountPath: "inputs/data.csv" }),
+            makeAttachment({ filename: "b.csv", storageKey: "k/b", mountPath: "inputs/data.csv" }),
+          ],
+          options({ storage }),
+        ),
+      ).rejects.toThrow(/mount path 'inputs\/data\.csv' collides with attachment 'a\.csv'/);
+      expect(storage.download).not.toHaveBeenCalled();
+    });
+
+    it("refuses a mountPath outside the inputs namespace with the namespace named (a file in the user's tree would ride the write-back commit)", async () => {
+      const { storage } = makeInMemoryArtifactStorage();
+      const attempt = resolveAttachments(
+        [makeAttachment({ filename: "data.yaml", storageKey: "k/d", mountPath: "/workspace/data/data.yaml" })],
+        options({ storage }),
+      );
+      await expect(attempt).rejects.toBeInstanceOf(AttachmentResolutionError);
+      await expect(attempt).rejects.toThrow(/outside the attachment namespace.*set mountPath to 'inputs\/<name>'/);
+      expect(storage.download).not.toHaveBeenCalled();
+    });
+
+    it("refuses a mountPath that climbs out of the namespace, and one that names the inputs directory itself", async () => {
+      const { storage } = makeInMemoryArtifactStorage();
+      await expect(
+        resolveAttachments([makeAttachment({ storageKey: "k/e", mountPath: "inputs/../../evil.md" })], options({ storage })),
+      ).rejects.toThrow(/escapes the attachment namespace/);
+      await expect(
+        resolveAttachments([makeAttachment({ storageKey: "k/e", mountPath: "inputs/" })], options({ storage })),
+      ).rejects.toThrow(/names the inputs directory itself/);
+    });
+  });
+
+  // ── Archives: `extract` lands the entries under the mount directory ──────
+
+  describe("extract (S3 M1, Q-S3-14)", () => {
+    const archive = () =>
+      Buffer.from(
+        buildZip([
+          { name: "notes/readme.md", content: "# notes" },
+          { name: "data.csv", content: "a,b\n1,2" },
+        ]),
+      );
+
+    it("extracts a storage-backed archive under `inputs/<archive filename>/`, one resolved attachment per entry, with no vision, rename or URL", async () => {
+      const { storage } = makeInMemoryArtifactStorage();
+      await storage.upload("k/bundle", archive(), "application/zip");
+
+      const result = await resolveAttachments(
+        [makeAttachment({ filename: "bundle.zip", storageKey: "k/bundle", extract: true, contentType: "application/zip" })],
+        options({ storage, visionBudget: new VisionBudget(CURSOR_VISION_PROFILE, { modelVision: true }) }),
+      );
+
+      expect(result).toEqual([
+        { filename: "data.csv", relativePath: ".stigmer/inputs/bundle.zip/data.csv", sizeBytes: 7 },
+        { filename: "readme.md", relativePath: ".stigmer/inputs/bundle.zip/notes/readme.md", sizeBytes: 7 },
+      ]);
+      expect(readFileSync(join(platformDir, "inputs", "bundle.zip", "notes", "readme.md"), "utf-8")).toBe("# notes");
+      expect(storage.getDownloadUrl, "no URL for entries: the stored object is the ZIP, not any listed file").not.toHaveBeenCalled();
+    });
+
+    it("extracts a local archive at the CLI's `inputs/<dirname>/` mount (the directory-attachment shape)", async () => {
+      const srcPath = join(workspaceDir, "docs.zip");
+      writeFileSync(srcPath, archive());
+
+      const result = await resolveAttachments(
+        [makeAttachment({ filename: "docs.zip", storageKey: "", localPath: srcPath, extract: true, mountPath: "inputs/docs/" })],
+        options(),
+      );
+
+      expect(result.map((r) => r.relativePath)).toEqual([".stigmer/inputs/docs/data.csv", ".stigmer/inputs/docs/notes/readme.md"]);
+      expect(readFileSync(join(platformDir, "inputs", "docs", "data.csv"), "utf-8")).toBe("a,b\n1,2");
+    });
+
+    it("an archive that fails the shared guards aborts the resolution with the guard's own error", async () => {
+      const srcPath = join(workspaceDir, "evil.zip");
+      writeFileSync(srcPath, Buffer.from(buildZip([{ name: "../escape.txt", content: "x" }])));
+
+      await expect(
+        resolveAttachments([makeAttachment({ filename: "evil.zip", storageKey: "", localPath: srcPath, extract: true })], options()),
+      ).rejects.toBeInstanceOf(AttachmentValidationError);
+      expect(() => readFileSync(join(platformDir, "inputs", "evil.zip"))).toThrow();
+    });
+  });
+
   // ── Download-URL hand-off (issue #532) ───────────────────────────────────
   // The URL is strictly additive (shared/attachment-download-urls.ts): every
   // case below also asserts the file materialized exactly as it would
@@ -279,7 +428,7 @@ describe("resolveAttachments", () => {
       const result = await resolveAttachments([makeAttachment()], options({ storage }));
 
       expect(result).toEqual([
-        { filename: "plan.md", relativePath: ".stigmer/inputs/plan.md" },
+        { filename: "plan.md", relativePath: ".stigmer/inputs/plan.md", sizeBytes: 10 },
       ]);
       expect(readFileSync(join(platformDir, "inputs", "plan.md"), "utf-8")).toBe("# The Plan");
     });
@@ -300,6 +449,7 @@ describe("resolveAttachments", () => {
         {
           filename: "data.csv",
           relativePath: ".stigmer/inputs/data.csv",
+          sizeBytes: 5,
           downloadUrl: "mem://attachments/01ABC/data.csv",
         },
       ]);

package/src/shared/__tests__/attachment-zip.test.ts

@@ -0,0 +1,236 @@
+/**
+ * The ZIP guards an `extract` attachment passes before a byte is written
+ * (`shared/attachment-zip.ts`): the manifest checks (paths, traversal, null
+ * bytes, duplicates, methods, emptiness, count and declared-size caps) and
+ * the central-directory parsing that issue #567 made authoritative. Moved
+ * from the native injector's test file at S3 M1 with the code; every
+ * archive comes from the shared real-shape builder
+ * (@stigmer/zip-structure/testing). The write of an admitted entry is each
+ * caller's and is pinned in that caller's tests (`attachment-resolver.test.ts`).
+ */
+
+import { describe, it, expect } from "vitest";
+import { buildZip, type ZipFixtureFile } from "@stigmer/zip-structure/testing";
+import {
+  AttachmentValidationError,
+  MAX_ZIP_EXTRACTED_SIZE,
+  MAX_ZIP_FILES,
+  validateZipForExtraction,
+} from "../attachment-zip.js";
+
+function makeZip(entries: Record<string, string | Buffer>): Buffer {
+  return makeZipWith(entries, { method: "deflated" });
+}
+
+function makeStoredZip(entries: Record<string, Buffer>): Buffer {
+  return makeZipWith(entries, { method: "stored" });
+}
+
+function makeZipWith(
+  entries: Record<string, string | Buffer>,
+  shape: Pick<ZipFixtureFile, "method" | "streaming">,
+): Buffer {
+  const files: ZipFixtureFile[] = Object.entries(entries).map(([name, content]) => ({
+    name,
+    content: typeof content === "string" ? content : new Uint8Array(content),
+    ...shape,
+  }));
+  return Buffer.from(buildZip(files));
+}
+
+function makeDirectoryOnlyZip(): Buffer {
+  return Buffer.from(buildZip([{ name: "empty_dir/", content: "" }]));
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// validateZipForExtraction
+// ═══════════════════════════════════════════════════════════════════════
+
+describe("validateZipForExtraction", () => {
+  it("returns sorted manifest for valid ZIP with multiple files", () => {
+    const zip = makeZip({ "b.txt": "beta", "a.txt": "alpha", "c.txt": "charlie" });
+    const result = validateZipForExtraction(zip, "test.zip");
+
+    expect(result).toHaveLength(3);
+    expect(result.map(e => e.relativePath)).toEqual(["a.txt", "b.txt", "c.txt"]);
+  });
+
+  it("preserves nested directory paths in entries", () => {
+    const zip = makeZip({
+      "src/main.py": "print('hi')",
+      "README.md": "# Hello",
+      "src/lib/util.py": "pass",
+    });
+    const result = validateZipForExtraction(zip, "project.zip");
+    const paths = result.map(e => e.relativePath);
+
+    expect(paths).toContain("src/main.py");
+    expect(paths).toContain("src/lib/util.py");
+    expect(paths).toContain("README.md");
+  });
+
+  it("reports correct uncompressed sizes", () => {
+    const contentA = "hello world";
+    const contentB = "x".repeat(500);
+    const zip = makeZip({ "a.txt": contentA, "b.txt": contentB });
+
+    const result = validateZipForExtraction(zip, "test.zip");
+    const sizeMap = new Map(result.map(e => [e.relativePath, e.uncompressedSize]));
+
+    expect(sizeMap.get("a.txt")).toBe(Buffer.from(contentA).length);
+    expect(sizeMap.get("b.txt")).toBe(Buffer.from(contentB).length);
+  });
+
+  it("excludes directory-only entries", () => {
+    const zip = makeDirectoryOnlyZip();
+    expect(() => validateZipForExtraction(zip, "dirs.zip")).toThrow(
+      AttachmentValidationError,
+    );
+  });
+
+  it("rejects invalid ZIP format (random bytes)", () => {
+    expect(() => validateZipForExtraction(Buffer.from("not-a-zip"), "bad.zip"))
+      .toThrow(AttachmentValidationError);
+    expect(() => validateZipForExtraction(Buffer.from("not-a-zip"), "bad.zip"))
+      .toThrow(/not a valid ZIP archive/);
+  });
+
+  it("rejects file too small to be a ZIP", () => {
+    expect(() => validateZipForExtraction(Buffer.from([0x50, 0x4b]), "tiny.zip"))
+      .toThrow(/too small/);
+  });
+
+  it("rejects absolute path entries (forward slash)", () => {
+    const zip = makeZip({ "/etc/passwd": "root:x:0:0" });
+    expect(() => validateZipForExtraction(zip, "evil.zip"))
+      .toThrow(/absolute path/);
+  });
+
+  it("rejects absolute path entries (backslash)", () => {
+    const zip = makeZip({ "\\windows\\system32\\evil.dll": "payload" });
+    expect(() => validateZipForExtraction(zip, "evil.zip"))
+      .toThrow(/absolute path/);
+  });
+
+  it("rejects path traversal with leading ..", () => {
+    const zip = makeZip({ "../../etc/passwd": "root:x:0:0" });
+    expect(() => validateZipForExtraction(zip, "evil.zip"))
+      .toThrow(/path traversal/);
+  });
+
+  it("rejects path traversal with embedded ..", () => {
+    const zip = makeZip({ "foo/../../etc/passwd": "root:x:0:0" });
+    expect(() => validateZipForExtraction(zip, "evil.zip"))
+      .toThrow(/path traversal/);
+  });
+
+  it("rejects null bytes in filenames", () => {
+    const zip = makeZip({ "file\u0000.txt": "test" });
+    expect(() => validateZipForExtraction(zip, "null.zip"))
+      .toThrow(/null bytes/);
+  });
+
+  it("rejects empty archive (valid ZIP, zero file entries)", () => {
+    const zip = makeDirectoryOnlyZip();
+    expect(() => validateZipForExtraction(zip, "empty.zip"))
+      .toThrow(/empty ZIP archive/);
+  });
+
+  it("rejects file count exceeding limit", () => {
+    const entries: Record<string, Buffer> = {};
+    for (let i = 0; i < MAX_ZIP_FILES + 1; i++) {
+      entries[`file_${String(i).padStart(4, "0")}.txt`] = Buffer.from("x");
+    }
+    const zip = makeStoredZip(entries);
+    expect(() => validateZipForExtraction(zip, "bomb.zip"))
+      .toThrow(new RegExp(`limit: ${MAX_ZIP_FILES}`));
+  });
+
+  it("rejects total uncompressed size exceeding limit", () => {
+    const overLimit = MAX_ZIP_EXTRACTED_SIZE + 1;
+    const zip = makeStoredZip({ "big.bin": Buffer.alloc(overLimit, 0) });
+    expect(() => validateZipForExtraction(zip, "bomb.zip"))
+      .toThrow(/limit: 100 MB/);
+  });
+
+  it("accepts ZIP at exactly the file count limit", () => {
+    const entries: Record<string, Buffer> = {};
+    for (let i = 0; i < MAX_ZIP_FILES; i++) {
+      entries[`f${i}.txt`] = Buffer.from("x");
+    }
+    const zip = makeStoredZip(entries);
+    const result = validateZipForExtraction(zip, "ok.zip");
+    expect(result).toHaveLength(MAX_ZIP_FILES);
+  });
+});
+
+// ═══════════════════════════════════════════════════════════════════════
+// Central-directory parsing (issue #567)
+// ═══════════════════════════════════════════════════════════════════════
+// The archive shapes the old local-header walk corrupted or rejected:
+// stored streaming entries (silent manifest truncation) and Go-default
+// deflated streaming entries (rejected outright). Sizes come from the
+// central directory — the format's authoritative index — and structural
+// failures are fail-hard, unlike the skill-artifact reader's non-fatal
+// empty return: nothing upstream vouches for an attachment.
+
+describe("validateZipForExtraction — central-directory parsing (issue #567)", () => {
+  it("validates every entry of a stored streaming archive (no silent truncation)", () => {
+    // Method 0 + flag bit 3 + zeroed local sizes: the old walk admitted the
+    // first entry with size 0, landed mid-payload, and quietly dropped the
+    // rest of the manifest.
+    const zip = Buffer.from(buildZip([
+      { name: "first.txt", content: "first file content", streaming: true },
+      { name: "second.txt", content: "second file content", streaming: true },
+    ]));
+
+    const result = validateZipForExtraction(zip, "streamed.zip");
+    expect(result.map((e) => e.relativePath)).toEqual(["first.txt", "second.txt"]);
+    expect(result.map((e) => e.uncompressedSize)).toEqual([
+      "first file content".length,
+      "second file content".length,
+    ]);
+  });
+
+  it("accepts a Go-default archive (deflated streaming entries)", () => {
+    const zip = Buffer.from(buildZip([
+      { name: "main.go", content: "package main", method: "deflated", streaming: true },
+      { name: "go.mod", content: "module example", method: "deflated", streaming: true },
+    ]));
+
+    const result = validateZipForExtraction(zip, "go-built.zip");
+    expect(result.map((e) => e.relativePath)).toEqual(["go.mod", "main.go"]);
+  });
+
+  it("rejects an archive with no central directory (fail-hard, unlike skill extraction)", () => {
+    const zip = Buffer.from(buildZip(
+      [{ name: "a.txt", content: "aaa" }],
+      { omitCentralDirectory: true },
+    ));
+
+    expect(() => validateZipForExtraction(zip, "truncated.zip"))
+      .toThrow(AttachmentValidationError);
+    expect(() => validateZipForExtraction(zip, "truncated.zip"))
+      .toThrow(/not a valid ZIP archive/);
+  });
+
+  it("rejects duplicate entry paths (a contradictory manifest)", () => {
+    const zip = Buffer.from(buildZip([
+      { name: "dup.txt", content: "one" },
+      { name: "dup.txt", content: "two" },
+    ]));
+
+    expect(() => validateZipForExtraction(zip, "dup.zip"))
+      .toThrow(/duplicate entry/);
+  });
+
+  it("locates the central directory behind a trailing archive comment", () => {
+    const zip = Buffer.from(buildZip(
+      [{ name: "a.txt", content: "aaa" }],
+      { comment: "release archive — built by tooling" },
+    ));
+
+    const result = validateZipForExtraction(zip, "commented.zip");
+    expect(result.map((e) => e.relativePath)).toEqual(["a.txt"]);
+  });
+});

package/src/shared/__tests__/bedrock-adapter.test.ts

@@ -152,7 +152,7 @@ describe("buildChatModel bedrock adapter", () => {
   it("injects the CANONICAL id's default maxTokens when the caller omits it (the 4096 landmine)", async () => {
     // LangChain's per-model default table prefix-matches the model string.
     // `anthropic.…` ids match nothing and silently fall back to 4096 —
-    // setup.ts omits maxTokens, so every deep-agent call would be capped.
+    // turn-setup.ts omits maxTokens, so every deep-agent call would be capped.
     // The adapter must inject what the canonical id would have received on
     // the public API or vertex, whatever that is at the installed LangChain
     // version (16384 for 4.5/4.6-generation ids at 1.4.0).

package/src/shared/__tests__/blueprint-resolver.test.ts

@@ -0,0 +1,43 @@
+/**
+ * `shared/blueprint-resolver.ts` `mergeSkillRefs`: the one merge of the
+ * agent's and the session's skill refs the turn runtime resolves from
+ * (`resolveAgentBlueprint`). Union, deduplicated by slug, the session's ref
+ * winning a collision (it may pin a different version).
+ *
+ * Carried from `skill-writer.test.ts` at S3 M2b, when the native
+ * orchestrator's byte-twin of this function was deleted with its module;
+ * until then the runtime's copy was tested only through the twin.
+ */
+
+import { describe, it, expect } from "vitest";
+import type { ApiResourceReference } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
+import { mergeSkillRefs } from "../blueprint-resolver.js";
+
+function makeRef(slug: string, org = "test-org"): ApiResourceReference {
+  return { slug, org, $typeName: "ai.stigmer.commons.apiresource.ApiResourceReference" } as ApiResourceReference;
+}
+
+describe("mergeSkillRefs", () => {
+  it("returns empty for no refs", () => {
+    expect(mergeSkillRefs([], [])).toEqual([]);
+  });
+
+  it("returns the agent's refs when the session names none", () => {
+    const result = mergeSkillRefs([makeRef("skill-a"), makeRef("skill-b")], []);
+    expect(result.map((r) => r.slug)).toEqual(["skill-a", "skill-b"]);
+  });
+
+  it("deduplicates by slug with the session's ref winning", () => {
+    const result = mergeSkillRefs([makeRef("skill-a", "org1")], [makeRef("skill-a", "org2")]);
+    expect(result).toHaveLength(1);
+    expect(result[0].org).toBe("org2");
+  });
+
+  it("unions distinct skills from both sources", () => {
+    expect(mergeSkillRefs([makeRef("skill-a")], [makeRef("skill-b")])).toHaveLength(2);
+  });
+
+  it("ignores a ref with no slug (nothing to key it by)", () => {
+    expect(mergeSkillRefs([makeRef("")], [])).toEqual([]);
+  });
+});