@stigmer/runner 3.9.0 → 3.11.0

package/src/activities/discover-mcp-server.ts

@@ -22,7 +22,7 @@ import { createHash } from "node:crypto";
 import { MultiServerMCPClient } from "@langchain/mcp-adapters";
 import { activityStarted, activityFinished } from "../idle-watchdog.js";
 import { StigmerClient } from "../client/stigmer-client.js";
-import { mcpServerToResolved } from "../shared/mcp-resolver.js";
+import { mcpServerToResolved, type ResolvedMcpServer } from "../shared/mcp-resolver.js";
 import { toMcpClientConfig } from "../shared/mcp-manager.js";
 import {
   assertTransportAllowed,
@@ -31,11 +31,44 @@ import {
 } from "../shared/mcp-transport-guard.js";
 import { detectOAuthChallenge } from "../shared/mcp-oauth-detect.js";
 import { injectAnonymousCallerIdentityForDiscovery } from "../shared/caller-identity.js";
+import { startHeartbeat } from "../shared/heartbeat.js";
 import { withTimeout } from "../shared/with-timeout.js";
 import type { McpServer } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
+import type { EnvVarDeclaration } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/spec_pb";
 import type { Config } from "../config.js";
 
-const SESSION_INIT_TIMEOUT_MS = 270_000;
+/**
+ * MCP session-init bounds, per transport (issue #239).
+ *
+ * A remote endpoint that accepts a connection but never completes the MCP
+ * handshake would otherwise hang initialization forever: the MCP SDK's SSE
+ * transport resolves only on the server's `endpoint` event, with no timer of
+ * its own, and mcp-adapters silently falls back to SSE whenever the
+ * streamable-HTTP POST is answered with a 4xx (monday.com's endpoint did
+ * exactly this — 4xx on POST, then a silently-open SSE stream).
+ *
+ * HTTP endpoints get a short bound: there is nothing to install or compile,
+ * so a healthy endpoint completes the handshake in seconds — a short bound is
+ * what converts the silent hang into a fast, actionable failure (with room for
+ * the 10s OAuth re-probe on the failure path). stdio servers keep the generous
+ * bound because their first run may compile or install packages (`go run`,
+ * `npx`) — the cold-start case (issue #243). The OSS server's connect-workflow
+ * run timeout (connectTimeout, controller/connect.go) is derived from the
+ * stdio bound + the classification floor, so both errors stay reachable.
+ */
+const HTTP_INIT_TIMEOUT_MS = 30_000;
+const STDIO_INIT_TIMEOUT_MS = 270_000;
+
+/**
+ * The server-side secret-redaction sentinel. Byte-for-byte the value both
+ * editions substitute for secret values a caller may not decrypt
+ * (`SecretEncryptionService.REDACTED_MARKER` in stigmer-cloud,
+ * `RedactedMarker` in the OSS Go server). Discovery dialing an
+ * endpoint with a redacted credential is guaranteed to fail confusingly
+ * (e.g. `Authorization: Bearer ***REDACTED***` → 401 → SSE-fallback limbo),
+ * so it is refused up front with an actionable error instead.
+ */
+const REDACTED_MARKER = "***REDACTED***";
 
 const PLATFORM_INJECTABLE_MAP: Record<string, string> = {
   STIGMER_SERVER_ADDRESS: "STIGMER_MCP_PUBLIC_ENDPOINT",
@@ -95,6 +128,28 @@ export interface ToolApprovalDict {
   message: string;
 }
 
+/**
+ * Raised when the credentials a server declares could not be delivered to
+ * discovery — the ExecutionContext read failed, came back empty, or returned
+ * redacted values (issue #239).
+ *
+ * Exists because the alternative is strictly worse: proceeding without the
+ * declared credentials either dies later as an opaque
+ * PlaceholderResolutionError (when a header/arg templates the missing var) or
+ * dials the endpoint with a garbage credential and strands the connect in the
+ * 4xx → SSE-fallback limbo this file's init bounds exist to contain. Failing
+ * here names the ROOT cause — credential delivery — instead of its downstream
+ * symptom. The message is user-facing and self-contained: it survives the
+ * Temporal boundary and the Go/Java connect wrappers include it in the
+ * user-facing failure text.
+ */
+export class CredentialResolutionError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "CredentialResolutionError";
+  }
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Tools Fingerprint (pure, deterministic, safe in workflow code)
 // ─────────────────────────────────────────────────────────────────────────────
@@ -242,14 +297,15 @@ export async function discoverMcpServer(
   const slug = mcpServer.metadata?.slug || mcpServerId;
   const previousState = extractPreviousState(mcpServer);
 
+  const declaredEnv = mcpServer.spec.env ?? {};
   const envVars = await resolveEnvVarsForDiscovery(
     stigmerClient,
     executionContextId ?? null,
+    slug,
+    declaredEnv,
   );
 
-  const declaredEnvKeys = mcpServer.spec.env
-    ? new Set(Object.keys(mcpServer.spec.env))
-    : new Set<string>();
+  const declaredEnvKeys = new Set(Object.keys(declaredEnv));
   const platformEnv = injectPlatformEnv(declaredEnvKeys, envVars);
 
   // Discovery runs with no session, so every declared caller-identity key
@@ -277,6 +333,7 @@ export async function discoverMcpServer(
   const { tools, resourceTemplates } = await connectAndDiscover(
     slug,
     connectionConfig,
+    resolved,
   );
 
   const newFp = toolsFingerprint(tools);
@@ -300,51 +357,144 @@ export async function discoverMcpServer(
 // Env Var Resolution
 // ─────────────────────────────────────────────────────────────────────────────
 
+/**
+ * Resolve the discovery env from the connect flow's ExecutionContext,
+ * failing CLOSED when a server's declared credentials cannot be delivered.
+ *
+ * The strictness is keyed on whether the server declares any NON-OPTIONAL
+ * env var ("credentials expected"):
+ *
+ * - Credentials expected + the EC read errors, or the EC is missing/empty →
+ *   {@link CredentialResolutionError}. The backend only creates a connect EC
+ *   when it resolved credentials to deliver, so an unreadable or empty EC is
+ *   a delivery failure (auth/scope refusal, transient backend error), never a
+ *   normal state. Limping ahead was issue #239's failure mode: discovery died
+ *   later as an opaque PlaceholderResolutionError or a doomed dial.
+ * - Any delivered value equal to the redaction sentinel →
+ *   {@link CredentialResolutionError}, regardless of optionality. A redacted
+ *   value means the server-side decrypt gate refused THIS runner's credential
+ *   class/scope and fell closed to redaction — dialing with the literal
+ *   sentinel can only produce a misleading 401.
+ * - No non-optional declarations → the old lenient path (warn and continue):
+ *   servers declaring nothing (or only optional/injected keys like the
+ *   caller-identity family) legitimately discover without an EC.
+ */
 async function resolveEnvVarsForDiscovery(
   client: StigmerClient,
   executionContextId: string | null,
+  slug: string,
+  declaredEnv: Record<string, EnvVarDeclaration>,
 ): Promise<Record<string, string>> {
+  const requiredKeys = Object.entries(declaredEnv)
+    .filter(([, decl]) => !decl.optional)
+    .map(([key]) => key);
+  const credentialsExpected = requiredKeys.length > 0;
+
   if (!executionContextId) return {};
 
+  let execCtx: Awaited<ReturnType<typeof client.getExecutionContextByExecutionId>>;
   try {
-    const execCtx = await client.getExecutionContextByExecutionId(
-      executionContextId,
-    );
-
-    if (!execCtx?.spec?.data || Object.keys(execCtx.spec.data).length === 0) {
-      console.warn(
-        `[DiscoverMcpServer] ExecutionContext '${executionContextId}' not found ` +
-        `or empty — MCP server may not require environment variables`,
+    execCtx = await client.getExecutionContextByExecutionId(executionContextId);
+  } catch (err) {
+    const cause = err instanceof Error ? err.message : String(err);
+    if (credentialsExpected) {
+      throw new CredentialResolutionError(
+        `Could not resolve the credentials MCP server '${slug}' requires ` +
+        `(${requiredKeys.join(", ")}): the connect credential store was ` +
+        `unreadable (${cause}). This is a platform-side delivery failure, ` +
+        `not a problem with your credentials — retry the connect, and if it ` +
+        `persists, re-run the OAuth sign-in or re-enter the credentials.`,
       );
-      return {};
     }
+    console.warn(
+      `[DiscoverMcpServer] Failed to resolve ExecutionContext '${executionContextId}': ` +
+      `${cause}`,
+    );
+    return {};
+  }
 
-    const envVars: Record<string, string> = {};
-    for (const [key, execValue] of Object.entries(execCtx.spec.data)) {
-      envVars[key] = execValue.value;
+  const data = execCtx?.spec?.data ?? {};
+  if (Object.keys(data).length === 0) {
+    if (credentialsExpected) {
+      throw new CredentialResolutionError(
+        `MCP server '${slug}' requires ${requiredKeys.join(", ")}, but the ` +
+        `connect flow delivered no credentials. Re-run the OAuth sign-in ` +
+        `(or re-enter the credentials) and connect again.`,
+      );
     }
-
-    console.log(
-      `[DiscoverMcpServer] Resolved ${Object.keys(envVars).length} env var(s) ` +
-      `from ExecutionContext '${executionContextId}'`,
-    );
-    return envVars;
-  } catch (err) {
     console.warn(
-      `[DiscoverMcpServer] Failed to resolve ExecutionContext '${executionContextId}': ` +
-      `${err instanceof Error ? err.message : err}`,
+      `[DiscoverMcpServer] ExecutionContext '${executionContextId}' not found ` +
+      `or empty — MCP server may not require environment variables`,
     );
     return {};
   }
+
+  const redactedKeys = Object.entries(data)
+    .filter(([, execValue]) => execValue.value === REDACTED_MARKER)
+    .map(([key]) => key);
+  if (redactedKeys.length > 0) {
+    throw new CredentialResolutionError(
+      `The credentials for MCP server '${slug}' were delivered redacted ` +
+      `(${redactedKeys.join(", ")}): the platform refused to decrypt them ` +
+      `for this runner. This is a platform-side authorization failure — ` +
+      `retry the connect, and report it if it persists.`,
+    );
+  }
+
+  const envVars: Record<string, string> = {};
+  for (const [key, execValue] of Object.entries(data)) {
+    envVars[key] = execValue.value;
+  }
+
+  console.log(
+    `[DiscoverMcpServer] Resolved ${Object.keys(envVars).length} env var(s) ` +
+    `from ExecutionContext '${executionContextId}'`,
+  );
+  return envVars;
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
 // MCP Connection + Enumeration
 // ─────────────────────────────────────────────────────────────────────────────
 
+/**
+ * Pick the session-init bound for a resolved server's transport.
+ *
+ * Exported for tests; pure so the timeout choice (the load-bearing half of
+ * the issue-#239 fix) can be pinned without wiring a slow clock.
+ */
+export function initTimeoutMsFor(connectionType: ResolvedMcpServer["connectionType"]): number {
+  return connectionType === "stdio" ? STDIO_INIT_TIMEOUT_MS : HTTP_INIT_TIMEOUT_MS;
+}
+
+/**
+ * The user-facing message for a session-init timeout. Names the endpoint (or
+ * command) so the failure is diagnosable from the message alone, and explains
+ * the known silent-hang shape for HTTP endpoints — issue #239's mechanism.
+ */
+export function initTimeoutMessageFor(slug: string, resolved: ResolvedMcpServer): string {
+  const seconds = Math.round(initTimeoutMsFor(resolved.connectionType) / 1000);
+  if (resolved.connectionType === "stdio") {
+    return (
+      `MCP server '${slug}' (command: ${resolved.command}) did not complete ` +
+      `MCP initialization within ${seconds}s. If this server requires ` +
+      `compilation or package installation on first run (e.g. go run, npx), ` +
+      `the cold start may have exceeded the discovery timeout.`
+    );
+  }
+  return (
+    `MCP server '${slug}' at ${resolved.url} did not complete MCP ` +
+    `initialization within ${seconds}s. The endpoint accepted the connection ` +
+    `but never finished the handshake — commonly an endpoint that rejects ` +
+    `streamable HTTP while leaving its SSE fallback stream silently open. ` +
+    `Verify the URL points at a live streamable-HTTP MCP endpoint.`
+  );
+}
+
 async function connectAndDiscover(
   slug: string,
   connectionConfig: ReturnType<typeof toMcpClientConfig>,
+  resolved: ResolvedMcpServer,
 ): Promise<{
   tools: DiscoveredToolResult[];
   resourceTemplates: DiscoveredResourceTemplateResult[];
@@ -354,12 +504,10 @@ async function connectAndDiscover(
   const resourceTemplates: DiscoveredResourceTemplateResult[] = [];
 
   try {
-    const timeoutMessage =
-      `MCP server '${slug}' did not respond within ` +
-      `${Math.round(SESSION_INIT_TIMEOUT_MS / 1000)}s. If this server requires compilation or ` +
-      `package installation on first run (e.g. go run, npx), the cold ` +
-      `start may have exceeded the discovery timeout.`;
-    await withTimeout(SESSION_INIT_TIMEOUT_MS, timeoutMessage, async () => {
+    await withTimeout(
+      initTimeoutMsFor(resolved.connectionType),
+      () => initTimeoutMessageFor(slug, resolved),
+      async () => {
       await client.initializeConnections();
 
       const mcpClient = await client.getClient(slug);
@@ -461,12 +609,22 @@ export function createDiscoverMcpServerActivities(config: Config) {
       input: DiscoverMcpServerInput,
     ): Promise<DiscoverMcpServerOutput> => {
       activityStarted();
+      // The connect workflow proxies this activity with a 60s heartbeatTimeout,
+      // so it MUST heartbeat: before this loop existed, any discovery slower
+      // than 60s (stdio cold start — issue #243) or wedged on a silent remote
+      // (issue #239) was killed by Temporal with an opaque heartbeat timeout
+      // instead of reaching this file's actionable init-timeout errors.
+      const hb = startHeartbeat(15_000, () => ({
+        phase: "discovering_mcp_server",
+        mcpServerId: input.mcpServerId,
+      }));
       try {
         return await discoverMcpServer(input, {
           stigmerClient,
           transportPosture: resolveMcpTransportPosture(config.mode),
         });
       } finally {
+        hb.stop();
         activityFinished();
       }
     },

package/src/activities/execute-cursor/__test-utils__/cursor-hook-harness.ts

@@ -108,6 +108,14 @@ export interface CursorHookHarnessOptions {
    * non-pausing "unattended" kind and the adapt-and-explain agent message.
    */
   unattendedSkip?: boolean;
+  /**
+   * Per-server enabled_tools allow-lists (issue #350) — restricted servers
+   * only. The hook's manifest arm denies a beforeMCPExecution call whose
+   * mcp_server_name is listed here with a tool name outside its list (kind
+   * "disabled", ahead of every approval bypass). hookMcp payloads carry
+   * mcp_server_name "srv".
+   */
+  mcpServerEnabledTools?: Record<string, string[]>;
 }
 
 /**
@@ -170,6 +178,7 @@ export function setupCursorHookHarness(opts: CursorHookHarnessOptions = {}): Cur
       opts.captureIgnored ?? false,
       opts.gitWorkspace ?? true,
       opts.unattendedSkip ?? false,
+      opts.mcpServerEnabledTools ?? {},
     );
     writeFileSync(statePath, JSON.stringify(state), "utf-8");
   }

package/src/activities/execute-cursor/__tests__/approval-gate.test.ts

@@ -219,6 +219,20 @@ describe("buildApprovalState", () => {
     expect((state as unknown as Record<string, unknown>).builtInGatedList).toBeUndefined();
   });
 
+  it("carries the enabled_tools manifest (issue #350) and defaults it to empty", () => {
+    // Default: no restriction — the hook's disabled arm is inert.
+    const bare = buildApprovalState(mcpPolicies, false, new Set());
+    expect(bare.mcpServerEnabledTools).toEqual({});
+
+    // Restricted servers ride through verbatim for the hook's server-scoped
+    // membership check.
+    const restricted = buildApprovalState(
+      mcpPolicies, false, new Set(), undefined, false, false, true, false,
+      { planton: ["get_cloud_resource"] },
+    );
+    expect(restricted.mcpServerEnabledTools).toEqual({ planton: ["get_cloud_resource"] });
+  });
+
   it("emits the CONTENT token when a grant carries a content digest", () => {
     const grants = [{ toolName: "edit", mcpServerSlug: "", key: "write", salient: "/x/gated.txt", contentDigest: "deadbeef", sourceToolCallId: "consent-1" }];
     const state = buildApprovalState(mcpPolicies, false, new Set(), grants);

package/src/activities/execute-cursor/__tests__/attachment-resolver.test.ts

@@ -114,6 +114,59 @@ describe("resolveAttachments", () => {
     expect(readFileSync(join(platformDir, "inputs", "data.csv"), "utf-8")).toBe("a,b,c");
   });
 
+  it("uniquifies duplicate filenames on the storage branch — neither file's bytes are lost (issue #364)", async () => {
+    // Before the fix this branch had no collision check and the second write
+    // silently overwrote the first.
+    const { storage } = makeInMemoryArtifactStorage();
+    await storage.upload("attachments/01AAA/report.pdf", Buffer.from("first bytes"), "application/pdf");
+    await storage.upload("attachments/01BBB/report.pdf", Buffer.from("second bytes"), "application/pdf");
+
+    const result = await resolveAttachments(
+      [
+        makeAttachment({ filename: "report.pdf", storageKey: "attachments/01AAA/report.pdf" }),
+        makeAttachment({ filename: "report.pdf", storageKey: "attachments/01BBB/report.pdf" }),
+      ],
+      options({ storage }),
+    );
+
+    expect(result).toEqual([
+      { filename: "report.pdf", relativePath: ".stigmer/inputs/report.pdf" },
+      {
+        filename: "report-2.pdf",
+        relativePath: ".stigmer/inputs/report-2.pdf",
+        renamedFrom: "report.pdf",
+      },
+    ]);
+    expect(readFileSync(join(platformDir, "inputs", "report.pdf"), "utf-8")).toBe("first bytes");
+    expect(readFileSync(join(platformDir, "inputs", "report-2.pdf"), "utf-8")).toBe("second bytes");
+  });
+
+  it("uniquifies duplicate filenames across the local and storage branches (one shared taken-set)", async () => {
+    const srcPath = join(workspaceDir, "notes.md");
+    writeFileSync(srcPath, "local copy");
+    const { storage } = makeInMemoryArtifactStorage();
+    await storage.upload("attachments/01ABC/notes.md", Buffer.from("uploaded copy"), "text/markdown");
+
+    const result = await resolveAttachments(
+      [
+        makeAttachment({ filename: "notes.md", storageKey: "", localPath: srcPath }),
+        makeAttachment({ filename: "notes.md", storageKey: "attachments/01ABC/notes.md" }),
+      ],
+      options({ storage }),
+    );
+
+    expect(result).toEqual([
+      { filename: "notes.md", relativePath: ".stigmer/inputs/notes.md" },
+      {
+        filename: "notes-2.md",
+        relativePath: ".stigmer/inputs/notes-2.md",
+        renamedFrom: "notes.md",
+      },
+    ]);
+    expect(readFileSync(join(platformDir, "inputs", "notes.md"), "utf-8")).toBe("local copy");
+    expect(readFileSync(join(platformDir, "inputs", "notes-2.md"), "utf-8")).toBe("uploaded copy");
+  });
+
   it("ignores localPath in cloud mode and downloads by storage key", async () => {
     const { storage } = makeInMemoryArtifactStorage();
     await storage.upload("attachments/01ABC/plan.md", Buffer.from("from storage"), "text/markdown");
@@ -313,6 +366,45 @@ describe("resolveAttachments", () => {
       expect(readFileSync(join(platformDir, "inputs", "notes.txt"), "utf-8")).toBe("plain text");
     });
 
+    it("degrades a storage-key image with model_no_vision on a blind model, file intact", async () => {
+      const { storage } = makeInMemoryArtifactStorage();
+      await storage.upload("attachments/01ABC/photo.png", PNG_BYTES, "image/png");
+
+      const [resolved] = await resolveAttachments(
+        [makeAttachment({ filename: "photo.png", storageKey: "attachments/01ABC/photo.png", contentType: "image/png" })],
+        options({
+          storage,
+          visionBudget: new VisionBudget(CURSOR_VISION_PROFILE, { modelVision: false }),
+        }),
+      );
+
+      expect(resolved.vision).toBeUndefined();
+      expect(resolved.visionDegraded).toBe("model_no_vision");
+      expect(readFileSync(join(platformDir, "inputs", "photo.png")).equals(PNG_BYTES)).toBe(true);
+    });
+
+    it("reports model_no_vision (never too_large) for an oversized localPath image on a blind model", async () => {
+      // The blind check must pre-empt the stat-based oversize fast path:
+      // too_large's "resend smaller" advice would be wrong for a model that
+      // cannot see any image.
+      const srcPath = join(workspaceDir, "big.png");
+      writeFileSync(srcPath, PNG_BYTES);
+
+      const [resolved] = await resolveAttachments(
+        [makeAttachment({ filename: "big.png", storageKey: "", localPath: srcPath, contentType: "image/png" })],
+        options({
+          visionBudget: new VisionBudget(CURSOR_VISION_PROFILE, {
+            maxImageBytes: PNG_BYTES.length - 1,
+            modelVision: false,
+          }),
+        }),
+      );
+
+      expect(resolved.vision).toBeUndefined();
+      expect(resolved.visionDegraded).toBe("model_no_vision");
+      expect(readFileSync(join(platformDir, "inputs", "big.png")).equals(PNG_BYTES)).toBe(true);
+    });
+
     it("selects greedily in attachment order when the total budget cuts off", async () => {
       const { storage } = makeInMemoryArtifactStorage();
       await storage.upload("attachments/01A/a.png", PNG_BYTES, "image/png");

package/src/activities/execute-cursor/__tests__/build-prompt.test.ts

@@ -47,7 +47,7 @@ function input(overrides: Partial<BuildPromptInput>): BuildPromptInput {
     subAgents: [],
     workspaceDirs: ["/tmp/ws"],
     workspaceFileRefs: [],
-    attachmentPaths: [],
+    attachments: [],
     pendingApprovals: [],
     ...overrides,
   };
@@ -103,6 +103,10 @@ describe("buildPrompt", () => {
     expect(prompt).toContain("<available_datastores>");
     expect(prompt).toContain("- clinic");
     expect(prompt).toContain("describe_datastore");
+    // The standing failure-disclosure instruction (issue #325) is this
+    // harness's ONLY outage coverage: the Cursor SDK connects MCP itself,
+    // so the runner can never reconcile the live roster here.
+    expect(prompt).toContain("do not answer from memory");
   });
 
   it("omits the datastores section when the agent uses no datastores", () => {
@@ -269,7 +273,7 @@ describe("attachments on a resumed turn (T04 — the mid-session WhatsApp case)"
 
   it("announces this turn's attachments to a resumed agent (per-execution value, never inherited)", () => {
     const prompt = buildPrompt(
-      input({ ...RESUMED, attachmentPaths: [".stigmer/inputs/lease.pdf"] }),
+      input({ ...RESUMED, attachments: [{ path: ".stigmer/inputs/lease.pdf" }] }),
     );
     expect(prompt).toContain("<input_files>");
     expect(prompt).toContain("`.stigmer/inputs/lease.pdf`");
@@ -277,6 +281,23 @@ describe("attachments on a resumed turn (T04 — the mid-session WhatsApp case)"
     expect(prompt.endsWith(USER_MESSAGE)).toBe(true);
   });
 
+  it("discloses a duplicate-renamed attachment's original name (issue #364)", () => {
+    const prompt = buildPrompt(
+      input({
+        ...RESUMED,
+        attachments: [
+          { path: ".stigmer/inputs/report.pdf" },
+          { path: ".stigmer/inputs/report-2.pdf", renamedFrom: "report.pdf" },
+        ],
+      }),
+    );
+    expect(prompt).toContain(
+      "- `.stigmer/inputs/report-2.pdf` (renamed from duplicate 'report.pdf')",
+    );
+    // The first file keeps a clean entry — no disclosure noise.
+    expect(prompt).toContain("- `.stigmer/inputs/report.pdf`\n");
+  });
+
   it("keeps a resumed turn WITHOUT attachments byte-identical to the raw message (regression guard)", () => {
     const prompt = buildPrompt(input({ ...RESUMED }));
     expect(prompt).toBe(USER_MESSAGE);
@@ -286,7 +307,7 @@ describe("attachments on a resumed turn (T04 — the mid-session WhatsApp case)"
     const prompt = buildPrompt(
       input({
         ...RESUMED,
-        attachmentPaths: [".stigmer/inputs/photo.jpg"],
+        attachments: [{ path: ".stigmer/inputs/photo.jpg" }],
         conversationCatchup: "User also said hello on the channel.",
       }),
     );
@@ -300,7 +321,7 @@ describe("attachments on a resumed turn (T04 — the mid-session WhatsApp case)"
     const prompt = buildPrompt(
       input({
         ...RESUMED,
-        attachmentPaths: [".stigmer/inputs/a.jpg", ".stigmer/inputs/big.png"],
+        attachments: [{ path: ".stigmer/inputs/a.jpg" }, { path: ".stigmer/inputs/big.png" }],
         vision: {
           inlineFilenames: ["a.jpg"],
           notViewable: [{ path: ".stigmer/inputs/big.png", reason: "too_large" }],
@@ -316,7 +337,7 @@ describe("attachments on a resumed turn (T04 — the mid-session WhatsApp case)"
     const prompt = buildPrompt(
       input({
         resolution: resolution("local", "created_first_execution"),
-        attachmentPaths: [".stigmer/inputs/a.jpg"],
+        attachments: [{ path: ".stigmer/inputs/a.jpg" }],
         vision: { inlineFilenames: ["a.jpg"], notViewable: [] },
       }),
     );
@@ -336,7 +357,7 @@ describe("attachments on a resumed turn (T04 — the mid-session WhatsApp case)"
             message: "Write file: gated.txt",
           }),
         ],
-        attachmentPaths: [".stigmer/inputs/photo.jpg"],
+        attachments: [{ path: ".stigmer/inputs/photo.jpg" }],
         vision: { inlineFilenames: ["photo.jpg"], notViewable: [] },
       }),
     );
@@ -543,7 +564,10 @@ describe("formatImplementPlanSection", () => {
   const PLAN_PATH = ".stigmer/inputs/plan.md";
 
   it("wraps the attached-plan directive when the plan is among the attachments", () => {
-    const section = formatImplementPlanSection(true, [PLAN_PATH, ".stigmer/inputs/data.csv"]);
+    const section = formatImplementPlanSection(true, [
+      { path: PLAN_PATH },
+      { path: ".stigmer/inputs/data.csv" },
+    ]);
 
     expect(section).toBeDefined();
     expect(section!.startsWith("<implement_plan>")).toBe(true);
@@ -553,7 +577,9 @@ describe("formatImplementPlanSection", () => {
   });
 
   it("falls back to the conversation-plan directive when no plan attachment resolved", () => {
-    const section = formatImplementPlanSection(true, [".stigmer/inputs/data.csv"]);
+    const section = formatImplementPlanSection(true, [
+      { path: ".stigmer/inputs/data.csv" },
+    ]);
 
     expect(section).toBeDefined();
     expect(section).not.toContain("plan.md");
@@ -561,12 +587,12 @@ describe("formatImplementPlanSection", () => {
   });
 
   it("returns undefined for an ordinary (non-build) execution", () => {
-    expect(formatImplementPlanSection(false, [PLAN_PATH])).toBeUndefined();
-    expect(formatImplementPlanSection(undefined, [PLAN_PATH])).toBeUndefined();
+    expect(formatImplementPlanSection(false, [{ path: PLAN_PATH }])).toBeUndefined();
+    expect(formatImplementPlanSection(undefined, [{ path: PLAN_PATH }])).toBeUndefined();
   });
 
   it("carries the plan-derived progress-tracking instruction (Tier 3)", () => {
-    const section = formatImplementPlanSection(true, [PLAN_PATH]);
+    const section = formatImplementPlanSection(true, [{ path: PLAN_PATH }]);
 
     expect(section).toContain("to-do list");
     expect(section).toContain("break the plan into");
@@ -577,7 +603,7 @@ describe("formatImplementPlanSection", () => {
       input({
         resolution: resolution("local", "created_first_execution"),
         buildFromPlan: true,
-        attachmentPaths: [PLAN_PATH],
+        attachments: [{ path: PLAN_PATH }],
       }),
     );
 
@@ -593,7 +619,7 @@ describe("formatImplementPlanSection", () => {
       input({
         resolution: resolution("local", "resumed_successfully"),
         buildFromPlan: true,
-        attachmentPaths: [PLAN_PATH],
+        attachments: [{ path: PLAN_PATH }],
       }),
     );
 
@@ -611,7 +637,7 @@ describe("formatImplementPlanSection", () => {
       input({
         resolution: resolution("local", "resumed_successfully"),
         buildFromPlan: false,
-        attachmentPaths: [PLAN_PATH],
+        attachments: [{ path: PLAN_PATH }],
       }),
     );