@stigmer/runner 3.1.1 → 3.1.3

package/dist/shared/workspace/session-root.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Session workspace-root resolution — shared by both executors (Cursor and
+ * deep-agent) so their placement rules can never drift.
+ *
+ * SessionSpec.workspace_entries promises: "When empty, the session uses an
+ * empty workspace directory." Handing every no-entry session the shared
+ * `config.workspaceRootDir` broke that contract twice over: a "new" session
+ * started amid every prior session's leftovers, and — under the per-workspace
+ * turn lock (workspace-lock.ts) — unrelated no-entry sessions would falsely
+ * serialize against each other. A per-session directory honors the contract,
+ * isolates the default quickstart case, and removes the false contention.
+ *
+ * Sessions WITH entries keep the shared root: their content identity is the
+ * entry source (a git URL clones idempotently, a localPath IS the user's
+ * directory), and cross-session sharing of that content is intentional —
+ * that sharing is exactly what the turn lock serializes.
+ */
+/**
+ * Resolve (and create) the working-tree root for a session.
+ *
+ * - No workspace entries → `{workspaceRootDir}/sessions/{sessionId}`, created
+ *   on demand. Deterministic from sessionId alone, so it is stable across
+ *   turns, HITL reinvocations, and Temporal retries with no persisted state.
+ * - One or more entries → the shared `workspaceRootDir`, where the
+ *   provisioner materializes each entry (in place, or per-entry subdirs).
+ *
+ * The `sessions/` namespace lives under the configured workspace root (the
+ * volume operators size and mount for workspace content), not under $HOME.
+ * It can coexist with a single-entry clone at the root: cloneInPlace
+ * (sources/git.ts) tolerates non-empty targets, colliding only if the repo
+ * itself ships a root-level `sessions` path — a strictly smaller surface
+ * than the old behavior, where any file a no-entry session dropped at the
+ * root could break the checkout.
+ */
+export declare function resolveSessionWorkspaceRoot(workspaceRootDir: string, workspaceEntries: readonly unknown[], sessionId: string): Promise<string>;

package/dist/shared/workspace/session-root.js

@@ -0,0 +1,53 @@
+/**
+ * Session workspace-root resolution — shared by both executors (Cursor and
+ * deep-agent) so their placement rules can never drift.
+ *
+ * SessionSpec.workspace_entries promises: "When empty, the session uses an
+ * empty workspace directory." Handing every no-entry session the shared
+ * `config.workspaceRootDir` broke that contract twice over: a "new" session
+ * started amid every prior session's leftovers, and — under the per-workspace
+ * turn lock (workspace-lock.ts) — unrelated no-entry sessions would falsely
+ * serialize against each other. A per-session directory honors the contract,
+ * isolates the default quickstart case, and removes the false contention.
+ *
+ * Sessions WITH entries keep the shared root: their content identity is the
+ * entry source (a git URL clones idempotently, a localPath IS the user's
+ * directory), and cross-session sharing of that content is intentional —
+ * that sharing is exactly what the turn lock serializes.
+ */
+import { join } from "node:path";
+import { mkdir } from "node:fs/promises";
+/**
+ * Resolve (and create) the working-tree root for a session.
+ *
+ * - No workspace entries → `{workspaceRootDir}/sessions/{sessionId}`, created
+ *   on demand. Deterministic from sessionId alone, so it is stable across
+ *   turns, HITL reinvocations, and Temporal retries with no persisted state.
+ * - One or more entries → the shared `workspaceRootDir`, where the
+ *   provisioner materializes each entry (in place, or per-entry subdirs).
+ *
+ * The `sessions/` namespace lives under the configured workspace root (the
+ * volume operators size and mount for workspace content), not under $HOME.
+ * It can coexist with a single-entry clone at the root: cloneInPlace
+ * (sources/git.ts) tolerates non-empty targets, colliding only if the repo
+ * itself ships a root-level `sessions` path — a strictly smaller surface
+ * than the old behavior, where any file a no-entry session dropped at the
+ * root could break the checkout.
+ */
+export async function resolveSessionWorkspaceRoot(workspaceRootDir, workspaceEntries, sessionId) {
+    if (workspaceEntries.length > 0) {
+        return workspaceRootDir;
+    }
+    if (!sessionId) {
+        // Same invariant as resolvePlatformOptions: an empty sessionId would
+        // collapse every no-entry session onto one directory — the exact leakage
+        // this function exists to prevent.
+        throw new Error("resolveSessionWorkspaceRoot: sessionId is required for a session with " +
+            "no workspace entries; an empty value would collapse every such session " +
+            "onto one shared directory.");
+    }
+    const sessionRoot = join(workspaceRootDir, "sessions", sessionId);
+    await mkdir(sessionRoot, { recursive: true });
+    return sessionRoot;
+}
+//# sourceMappingURL=session-root.js.map

package/dist/shared/workspace/session-root.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-root.js","sourceRoot":"","sources":["../../../src/shared/workspace/session-root.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAEzC;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,KAAK,UAAU,2BAA2B,CAC/C,gBAAwB,EACxB,gBAAoC,EACpC,SAAiB;IAEjB,IAAI,gBAAgB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAChC,OAAO,gBAAgB,CAAC;IAC1B,CAAC;IACD,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,qEAAqE;QACrE,yEAAyE;QACzE,mCAAmC;QACnC,MAAM,IAAI,KAAK,CACb,wEAAwE;YACxE,yEAAyE;YACzE,4BAA4B,CAC7B,CAAC;IACJ,CAAC;IACD,MAAM,WAAW,GAAG,IAAI,CAAC,gBAAgB,EAAE,UAAU,EAAE,SAAS,CAAC,CAAC;IAClE,MAAM,KAAK,CAAC,WAAW,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC9C,OAAO,WAAW,CAAC;AACrB,CAAC"}

package/dist/shared/workspace/workspace-lock.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Per-workspace turn lock — serializes agent-execution turns that share a
+ * working tree.
+ *
+ * Why this exists: the file-review substrate (shared/filereview) computes a
+ * turn's change set as `git diff baselineTree candidateTree`, where both trees
+ * are live snapshots of the working directory at turn start/end. That model is
+ * correct for a single writer, but nothing scopes a working tree to one
+ * execution: sessions declaring the same `localPath` (or sharing the runner's
+ * `workspaceRootDir`) resolve to the SAME directory, and the runner happily
+ * runs activities concurrently. A concurrent turn's write landing between
+ * another turn's baseline and candidate gets misattributed to that other turn
+ * (observed in prod: aex_01kwpzhmvbvwqdez9cb331nekr reviewed a notes.md it
+ * never wrote). The same race lets a reject-reconcile in one session silently
+ * revert a file another session's user just approved.
+ *
+ * Why a FILE lock and not in-process/server-side coordination: the shared
+ * resource is a directory on one host. A `localPath` entry resolves to the
+ * user's literal directory in ANY runner process on the machine — the CLI
+ * daemon and the desktop app's embedded runner can contend on one tree while
+ * answering to DIFFERENT control planes, so no single server can see all
+ * contenders and no in-process mutex can exclude a sibling process. Mutual
+ * exclusion must live where the collision happens: the filesystem.
+ *
+ * Mechanics (proper-lockfile):
+ * - The lock artifact lives under `~/.stigmer/workspace-locks/{key}.lock`,
+ *   NEVER inside the user's workspace (issue #173: attaching a real repo must
+ *   leave no Stigmer droppings). The key is sha256(realpath(workspaceRoot)),
+ *   so symlink aliases of one directory converge on one lock — the same
+ *   keying pattern as getHitlGateDir in platform-dir.ts.
+ * - While held, proper-lockfile refreshes the artifact's mtime on an interval;
+ *   if the holder process dies, refreshing stops and the artifact goes stale,
+ *   so the next waiter simply takes over. A crashed runner can never deadlock
+ *   a workspace, and no human ever has to delete a lock file.
+ * - Deadlock-free by construction: an activity holds at most ONE lock (its
+ *   primary workspace root), and a turn that pauses for human approval ENDS
+ *   its activity — releasing the lock — so a change set sitting unreviewed
+ *   never blocks the workspace.
+ */
+/**
+ * Default bound on how long an execution waits for a contended workspace
+ * before failing with {@link WorkspaceLockTimeoutError}. Generous — an agent
+ * turn legitimately runs for minutes — but finite, so a pathological holder
+ * produces an explicit, actionable failure instead of an invisible hang.
+ */
+export declare const DEFAULT_WORKSPACE_LOCK_TIMEOUT_MS: number;
+/** The acquisition wait exceeded its bound — the workspace stayed busy. */
+export declare class WorkspaceLockTimeoutError extends Error {
+    constructor(workspaceRoot: string, waitedMs: number);
+}
+/** The acquisition wait was cancelled (e.g. the user cancelled the execution). */
+export declare class WorkspaceLockCancelledError extends Error {
+    constructor(workspaceRoot: string);
+}
+export interface AcquireWorkspaceLockOptions {
+    /**
+     * Invoked once, when the first acquisition attempt finds the workspace
+     * held by another turn — the hook for surfacing a visible "waiting for
+     * workspace" state to the user. Never invoked on an uncontended acquire.
+     */
+    readonly onWaiting?: () => void | Promise<void>;
+    /** Invoked on every poll while waiting (Temporal activity liveness). */
+    readonly heartbeat?: () => void;
+    /** Aborts the wait immediately (Temporal activity cancellation). */
+    readonly signal?: AbortSignal;
+    /** Max wait before {@link WorkspaceLockTimeoutError}. */
+    readonly timeoutMs?: number;
+    /** Poll interval override (tests). */
+    readonly pollIntervalMs?: number;
+    /** Staleness bound override (tests). */
+    readonly staleMs?: number;
+    /** Lock-artifact directory override (tests). */
+    readonly lockDir?: string;
+}
+/** Idempotent releaser returned by {@link acquireWorkspaceLock}. */
+export type ReleaseWorkspaceLock = () => Promise<void>;
+/**
+ * Acquire the exclusive turn lock for a workspace working tree, waiting (with
+ * heartbeats and cancellation) while another turn holds it.
+ *
+ * The caller must hold the lock across the turn's ENTIRE tree-mutating window
+ * — decision reconcile, HITL gate install, the agent's own writes, and the
+ * candidate capture — and release it in a `finally` as the last
+ * workspace-touching step.
+ */
+export declare function acquireWorkspaceLock(workspaceRoot: string, options?: AcquireWorkspaceLockOptions): Promise<ReleaseWorkspaceLock>;

package/dist/shared/workspace/workspace-lock.js

@@ -0,0 +1,187 @@
+/**
+ * Per-workspace turn lock — serializes agent-execution turns that share a
+ * working tree.
+ *
+ * Why this exists: the file-review substrate (shared/filereview) computes a
+ * turn's change set as `git diff baselineTree candidateTree`, where both trees
+ * are live snapshots of the working directory at turn start/end. That model is
+ * correct for a single writer, but nothing scopes a working tree to one
+ * execution: sessions declaring the same `localPath` (or sharing the runner's
+ * `workspaceRootDir`) resolve to the SAME directory, and the runner happily
+ * runs activities concurrently. A concurrent turn's write landing between
+ * another turn's baseline and candidate gets misattributed to that other turn
+ * (observed in prod: aex_01kwpzhmvbvwqdez9cb331nekr reviewed a notes.md it
+ * never wrote). The same race lets a reject-reconcile in one session silently
+ * revert a file another session's user just approved.
+ *
+ * Why a FILE lock and not in-process/server-side coordination: the shared
+ * resource is a directory on one host. A `localPath` entry resolves to the
+ * user's literal directory in ANY runner process on the machine — the CLI
+ * daemon and the desktop app's embedded runner can contend on one tree while
+ * answering to DIFFERENT control planes, so no single server can see all
+ * contenders and no in-process mutex can exclude a sibling process. Mutual
+ * exclusion must live where the collision happens: the filesystem.
+ *
+ * Mechanics (proper-lockfile):
+ * - The lock artifact lives under `~/.stigmer/workspace-locks/{key}.lock`,
+ *   NEVER inside the user's workspace (issue #173: attaching a real repo must
+ *   leave no Stigmer droppings). The key is sha256(realpath(workspaceRoot)),
+ *   so symlink aliases of one directory converge on one lock — the same
+ *   keying pattern as getHitlGateDir in platform-dir.ts.
+ * - While held, proper-lockfile refreshes the artifact's mtime on an interval;
+ *   if the holder process dies, refreshing stops and the artifact goes stale,
+ *   so the next waiter simply takes over. A crashed runner can never deadlock
+ *   a workspace, and no human ever has to delete a lock file.
+ * - Deadlock-free by construction: an activity holds at most ONE lock (its
+ *   primary workspace root), and a turn that pauses for human approval ENDS
+ *   its activity — releasing the lock — so a change set sitting unreviewed
+ *   never blocks the workspace.
+ */
+import { join, resolve } from "node:path";
+import { homedir } from "node:os";
+import { createHash } from "node:crypto";
+import { mkdir, realpath } from "node:fs/promises";
+import lockfile from "proper-lockfile";
+/** How long a waiter polls between acquisition attempts. */
+const DEFAULT_POLL_INTERVAL_MS = 1_000;
+/**
+ * Default bound on how long an execution waits for a contended workspace
+ * before failing with {@link WorkspaceLockTimeoutError}. Generous — an agent
+ * turn legitimately runs for minutes — but finite, so a pathological holder
+ * produces an explicit, actionable failure instead of an invisible hang.
+ */
+export const DEFAULT_WORKSPACE_LOCK_TIMEOUT_MS = 15 * 60 * 1_000;
+/**
+ * How long a lock artifact may go un-refreshed before waiters treat the
+ * holder as dead and take over. proper-lockfile refreshes at stale/2, so a
+ * live holder can never be usurped; only a crashed process trips this.
+ */
+const DEFAULT_STALE_MS = 10_000;
+/** The acquisition wait exceeded its bound — the workspace stayed busy. */
+export class WorkspaceLockTimeoutError extends Error {
+    constructor(workspaceRoot, waitedMs) {
+        super(`Workspace is in use by another session: ${workspaceRoot} ` +
+            `(waited ${Math.round(waitedMs / 1000)}s). Another agent execution is ` +
+            `operating on this workspace directory; retry after it finishes.`);
+        this.name = "WorkspaceLockTimeoutError";
+    }
+}
+/** The acquisition wait was cancelled (e.g. the user cancelled the execution). */
+export class WorkspaceLockCancelledError extends Error {
+    constructor(workspaceRoot) {
+        super(`Workspace lock wait cancelled for ${workspaceRoot}`);
+        this.name = "WorkspaceLockCancelledError";
+    }
+}
+/** Runner-owned home for lock artifacts (HOME override honored, as in platform-dir.ts). */
+function defaultLockDir() {
+    const home = process.env.HOME || process.env.USERPROFILE || homedir();
+    return join(home, ".stigmer", "workspace-locks");
+}
+/**
+ * Acquire the exclusive turn lock for a workspace working tree, waiting (with
+ * heartbeats and cancellation) while another turn holds it.
+ *
+ * The caller must hold the lock across the turn's ENTIRE tree-mutating window
+ * — decision reconcile, HITL gate install, the agent's own writes, and the
+ * candidate capture — and release it in a `finally` as the last
+ * workspace-touching step.
+ */
+export async function acquireWorkspaceLock(workspaceRoot, options = {}) {
+    const { onWaiting, heartbeat, signal, timeoutMs = DEFAULT_WORKSPACE_LOCK_TIMEOUT_MS, pollIntervalMs = DEFAULT_POLL_INTERVAL_MS, staleMs = DEFAULT_STALE_MS, lockDir = defaultLockDir(), } = options;
+    // Resolve symlink aliases so every path spelling of one directory contends
+    // on one lock. The resolved path is also what we hand proper-lockfile as
+    // the target (with realpath:false — already resolved here). A root that
+    // does not exist yet cannot be realpath'd, so it locks on its canonical
+    // absolute spelling instead — proper-lockfile never touches the target
+    // itself (the artifact lives at lockfilePath), so the lock still works.
+    const resolvedRoot = await realpath(workspaceRoot).catch(() => resolve(workspaceRoot));
+    const key = createHash("sha256").update(resolvedRoot).digest("hex").slice(0, 16);
+    await mkdir(lockDir, { recursive: true });
+    const lockfilePath = join(lockDir, `${key}.lock`);
+    const startedAt = Date.now();
+    let waitingReported = false;
+    for (;;) {
+        if (signal?.aborted) {
+            throw new WorkspaceLockCancelledError(resolvedRoot);
+        }
+        try {
+            const release = await lockfile.lock(resolvedRoot, {
+                lockfilePath,
+                realpath: false,
+                stale: staleMs,
+                // No library-side retries: the wait loop below owns retry policy so it
+                // can heartbeat, report waiting, honor cancellation, and bound the wait.
+                retries: 0,
+                // A compromised lock (artifact vanished / refresh missed its staleness
+                // window under extreme event-loop stall) must not crash the worker
+                // process — the default behavior throws uncaught. Log loudly and let
+                // the turn finish: the exposure is bounded to pre-lock semantics.
+                onCompromised: (err) => {
+                    console.error(`[workspace-lock] lock on ${resolvedRoot} compromised mid-turn ` +
+                        `(continuing unlocked): ${err}`);
+                },
+            });
+            if (waitingReported) {
+                console.log(`[workspace-lock] acquired ${resolvedRoot} after waiting ` +
+                    `${Date.now() - startedAt}ms`);
+            }
+            // Idempotent wrapper: the executors release in a `finally` that also
+            // runs on paths where an earlier error may already have torn the lock
+            // down; a double release (or a release racing staleness takeover) must
+            // never mask the turn's real outcome.
+            let released = false;
+            return async () => {
+                if (released)
+                    return;
+                released = true;
+                try {
+                    await release();
+                }
+                catch (err) {
+                    console.warn(`[workspace-lock] release of ${resolvedRoot} failed (ignored): ${err}`);
+                }
+            };
+        }
+        catch (err) {
+            if (!isLockHeldError(err))
+                throw err;
+        }
+        if (!waitingReported) {
+            waitingReported = true;
+            console.log(`[workspace-lock] ${resolvedRoot} is held by another turn; waiting`);
+            try {
+                await onWaiting?.();
+            }
+            catch (err) {
+                console.warn(`[workspace-lock] onWaiting callback failed (non-fatal): ${err}`);
+            }
+        }
+        const waitedMs = Date.now() - startedAt;
+        if (waitedMs + pollIntervalMs > timeoutMs) {
+            throw new WorkspaceLockTimeoutError(resolvedRoot, waitedMs);
+        }
+        heartbeat?.();
+        await sleepAbortable(pollIntervalMs, signal);
+    }
+}
+/** proper-lockfile signals "already held" with code ELOCKED. */
+function isLockHeldError(err) {
+    return typeof err === "object" && err !== null &&
+        err.code === "ELOCKED";
+}
+/** Sleep that wakes immediately when the signal aborts (wait stays responsive). */
+function sleepAbortable(ms, signal) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            resolve();
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+//# sourceMappingURL=workspace-lock.js.map

package/dist/shared/workspace/workspace-lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-lock.js","sourceRoot":"","sources":["../../../src/shared/workspace/workspace-lock.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stigmer/runner",
-  "version": "3.1.1",
+  "version": "3.1.3",
   "description": "Embeddable Temporal worker for the Stigmer AI agent platform — handles agent execution, workflow orchestration, and MCP server management",
   "license": "Apache-2.0",
   "type": "module",
@@ -77,16 +77,15 @@
     "@langchain/langgraph": "^1.3.0",
     "@langchain/mcp-adapters": "^1.1.3",
     "@langchain/openai": "^1.4.0",
-    "zod-to-json-schema": "^3.24.0",
     "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/core": "^2.0.0",
     "@opentelemetry/exporter-metrics-otlp-grpc": "^0.218.0",
-    "@opentelemetry/sdk-metrics": "^2.0.0",
     "@opentelemetry/exporter-trace-otlp-grpc": "^0.218.0",
     "@opentelemetry/resources": "^2.0.0",
+    "@opentelemetry/sdk-metrics": "^2.0.0",
     "@opentelemetry/sdk-trace-base": "^2.0.0",
     "@opentelemetry/sdk-trace-node": "^2.0.0",
-    "@stigmer/protos": "3.1.1",
+    "@stigmer/protos": "3.1.3",
     "@temporalio/activity": "^1.11.0",
     "@temporalio/client": "^1.11.0",
     "@temporalio/common": "^1.11.0",
@@ -94,14 +93,18 @@
     "@temporalio/worker": "^1.11.0",
     "@temporalio/workflow": "^1.16.2",
     "deepagents": "^1.10.0",
+    "diff": "^8.0.4",
     "jq-wasm": "^1.1.0-jq-1.8.1",
     "js-yaml": "^4.1.1",
+    "proper-lockfile": "^4.1.2",
     "semver": "^7.8.0",
-    "zod": "^3.25.0"
+    "zod": "^3.25.0",
+    "zod-to-json-schema": "^3.24.0"
   },
   "devDependencies": {
     "@temporalio/testing": "^1.16.2",
     "@types/js-yaml": "^4.0.9",
+    "@types/proper-lockfile": "^4.1.4",
     "@types/semver": "^7.7.1",
     "esbuild": "^0.28.0",
     "tsx": "^4.21.0",

package/src/__tests__/config.test.ts

@@ -33,6 +33,7 @@ describe("loadConfig", () => {
     expect(config.proxyEndpoint).toBeNull();
     expect(config.maxConcurrentActivities).toBe(5);
     expect(config.cursorStreamStallTimeoutMs).toBe(180000);
+    expect(config.workspaceLockTimeoutMs).toBe(900000);
   });
 
   it("respects CURSOR_STREAM_STALL_TIMEOUT_MS", () => {
@@ -42,6 +43,13 @@ describe("loadConfig", () => {
     expect(config.cursorStreamStallTimeoutMs).toBe(90000);
   });
 
+  it("respects WORKSPACE_LOCK_TIMEOUT_MS", () => {
+    process.env.CURSOR_API_KEY = "test-key";
+    process.env.WORKSPACE_LOCK_TIMEOUT_MS = "60000";
+    const config = loadConfig();
+    expect(config.workspaceLockTimeoutMs).toBe(60000);
+  });
+
   it("respects STIGMER_TASK_QUEUE", () => {
     process.env.STIGMER_TASK_QUEUE = "runner:abc123";
     process.env.CURSOR_API_KEY = "test-key";

package/src/activities/__tests__/classify-tool-approvals.test.ts

@@ -622,6 +622,7 @@ function makeConfig() {
     checkpointerProxyEndpoint: null,
     primaryModel: "gpt-4.1",
     cursorStreamStallTimeoutMs: 180000,
+    workspaceLockTimeoutMs: 900000,
   };
 }
 

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

@@ -601,6 +601,7 @@ function makeConfig() {
     checkpointerProxyEndpoint: null,
     primaryModel: "gpt-4.1",
     cursorStreamStallTimeoutMs: 180000,
+    workspaceLockTimeoutMs: 900000,
   };
 }
 

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

@@ -0,0 +1,161 @@
+/**
+ * Tests for the Cursor harness's attachment resolver.
+ *
+ * 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").
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, writeFileSync, readFileSync, rmSync, lstatSync, readlinkSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { resolveAttachments, AttachmentResolutionError } from "../attachment-resolver.js";
+import { getPlatformDir } from "../../../shared/workspace/platform-dir.js";
+import { makeInMemoryArtifactStorage } from "../../../__test-utils__/fake-artifact-storage.js";
+
+function makeAttachment(overrides: Partial<{
+  filename: string;
+  storageKey: string;
+  mountPath: string;
+  contentType: string;
+  extract: boolean;
+  localPath: string;
+}> = {}) {
+  return {
+    filename: overrides.filename ?? "plan.md",
+    storageKey: overrides.storageKey ?? "attachments/01ABC/plan.md",
+    mountPath: overrides.mountPath ?? "",
+    contentType: overrides.contentType ?? "text/markdown",
+    extract: overrides.extract ?? false,
+    localPath: overrides.localPath ?? "",
+    $typeName: "ai.stigmer.agentic.agentexecution.v1.Attachment" as const,
+    $unknown: undefined,
+  } as any;
+}
+
+describe("resolveAttachments", () => {
+  let workspaceDir: string;
+  let sessionId: string;
+  let platformDir: string;
+
+  beforeEach(() => {
+    workspaceDir = mkdtempSync(join(tmpdir(), "attach-ws-"));
+    sessionId = `test-session-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+    platformDir = getPlatformDir(sessionId);
+  });
+
+  afterEach(() => {
+    rmSync(platformDir, { recursive: true, force: true });
+    rmSync(workspaceDir, { recursive: true, force: true });
+  });
+
+  function options(overrides: Partial<Parameters<typeof resolveAttachments>[1]> = {}) {
+    return {
+      sessionId,
+      primaryWorkspaceDir: workspaceDir,
+      mode: "local" as const,
+      storage: undefined,
+      ...overrides,
+    };
+  }
+
+  it("returns [] and touches nothing for an execution without attachments", async () => {
+    const result = await resolveAttachments([], options());
+
+    expect(result).toEqual([]);
+    expect(() => lstatSync(join(workspaceDir, ".stigmer"))).toThrow();
+  });
+
+  it("downloads a storage-key attachment into .stigmer/inputs (the uploadAttachment path)", async () => {
+    const { storage } = makeInMemoryArtifactStorage();
+    await storage.upload("attachments/01ABC/plan.md", Buffer.from("# The Plan"), "text/markdown");
+
+    const result = await resolveAttachments([makeAttachment()], options({ storage }));
+
+    expect(result).toEqual([
+      { filename: "plan.md", relativePath: ".stigmer/inputs/plan.md" },
+    ]);
+    expect(readFileSync(join(platformDir, "inputs", "plan.md"), "utf-8")).toBe("# The Plan");
+  });
+
+  it("ensures the workspace .stigmer symlink even when the agent has no skills", async () => {
+    // The regression this guards: only the skill resolver created the link,
+    // so a skill-less agent's attachments were written but unreachable.
+    const { storage } = makeInMemoryArtifactStorage();
+    await storage.upload("attachments/01ABC/plan.md", Buffer.from("# The Plan"), "text/markdown");
+
+    await resolveAttachments([makeAttachment()], options({ storage }));
+
+    const linkPath = join(workspaceDir, ".stigmer");
+    expect(lstatSync(linkPath).isSymbolicLink()).toBe(true);
+    expect(readlinkSync(linkPath)).toBe(platformDir);
+    // The resolved relative path actually dangles nowhere: it reads through
+    // the link to the platform dir.
+    expect(readFileSync(join(workspaceDir, ".stigmer", "inputs", "plan.md"), "utf-8")).toBe("# The Plan");
+  });
+
+  it("copies a localPath attachment directly in local mode (no storage round-trip)", async () => {
+    const srcPath = join(workspaceDir, "src.csv");
+    writeFileSync(srcPath, "a,b,c");
+
+    const result = await resolveAttachments(
+      [makeAttachment({ filename: "data.csv", storageKey: "", localPath: srcPath })],
+      options(),
+    );
+
+    expect(result).toEqual([
+      { filename: "data.csv", relativePath: ".stigmer/inputs/data.csv" },
+    ]);
+    expect(readFileSync(join(platformDir, "inputs", "data.csv"), "utf-8")).toBe("a,b,c");
+  });
+
+  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");
+
+    const result = await resolveAttachments(
+      [makeAttachment({ localPath: "/nonexistent/host/path.md" })],
+      options({ mode: "cloud", storage }),
+    );
+
+    expect(result).toHaveLength(1);
+    expect(readFileSync(join(platformDir, "inputs", "plan.md"), "utf-8")).toBe("from storage");
+  });
+
+  it("fails loudly when the storage download fails (no silent skip)", async () => {
+    const { storage } = makeInMemoryArtifactStorage();
+    // Nothing uploaded — the download will throw.
+
+    await expect(
+      resolveAttachments([makeAttachment()], options({ storage })),
+    ).rejects.toThrow(AttachmentResolutionError);
+  });
+
+  it("fails loudly when a storage-backed attachment arrives with no usable storage", async () => {
+    await expect(
+      resolveAttachments([makeAttachment()], options({ storage: undefined })),
+    ).rejects.toThrow(/artifact storage is unavailable/);
+  });
+
+  it("fails loudly on an attachment with neither localPath nor storageKey", async () => {
+    await expect(
+      resolveAttachments(
+        [makeAttachment({ storageKey: "", localPath: "" })],
+        options(),
+      ),
+    ).rejects.toThrow(/missing storageKey/);
+  });
+
+  it("fails loudly when the local file cannot be read", async () => {
+    await expect(
+      resolveAttachments(
+        [makeAttachment({ storageKey: "", localPath: join(workspaceDir, "missing.md") })],
+        options(),
+      ),
+    ).rejects.toThrow(AttachmentResolutionError);
+  });
+});