@stigmer/runner 3.1.0 → 3.1.2

package/src/runner.ts

@@ -17,7 +17,7 @@ import { join } from "node:path";
 import { homedir, tmpdir } from "node:os";
 import type { PayloadCodec } from "@temporalio/common";
 import type { Config } from "./config.js";
-import { DEFAULT_CURSOR_STREAM_STALL_TIMEOUT_MS } from "./config.js";
+import { DEFAULT_CURSOR_STREAM_STALL_TIMEOUT_MS, DEFAULT_WORKSPACE_LOCK_TIMEOUT_MS } from "./config.js";
 import type { WorkerActivities } from "./worker.js";
 import { resolveRunnerBootstrap } from "./bootstrap.js";
 
@@ -69,6 +69,9 @@ export interface StigmerRunnerOptions {
   /** No-progress bound for the Cursor harness stream (ms). @default 180000 */
   readonly cursorStreamStallTimeoutMs?: number;
 
+  /** Max wait for the per-workspace turn lock (ms). @default 900000 */
+  readonly workspaceLockTimeoutMs?: number;
+
   /** Checkpointer type for LangGraph agent state. @default "memory" (or "http" if proxyEndpoint is set) */
   readonly checkpointerType?: "memory" | "http";
 
@@ -274,6 +277,8 @@ export function mapOptionsToConfig(options: StigmerRunnerOptions): Config {
     primaryModel: options.primaryModel ?? "gpt-4.1",
     cursorStreamStallTimeoutMs:
       options.cursorStreamStallTimeoutMs ?? DEFAULT_CURSOR_STREAM_STALL_TIMEOUT_MS,
+    workspaceLockTimeoutMs:
+      options.workspaceLockTimeoutMs ?? DEFAULT_WORKSPACE_LOCK_TIMEOUT_MS,
   };
 }
 

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

@@ -1,14 +1,16 @@
 import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
-import { mkdtemp, rm, readFile } from "node:fs/promises";
+import { mkdtemp, rm, readFile, readdir, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import {
   LocalArtifactStorage,
   ProxyArtifactStorage,
   createArtifactStorage,
+  resolveUsableArtifactStorage,
   loadArtifactStorageConfig,
   type ArtifactStorageConfig,
 } from "../artifact-storage.js";
+import { deriveCaptureMode } from "../filereview/capture.js";
 
 // ── LocalArtifactStorage ─────────────────────────────────────────────
 
@@ -428,6 +430,7 @@ describe("loadArtifactStorageConfig", () => {
     checkpointerProxyEndpoint: null,
     primaryModel: "gpt-4.1",
     cursorStreamStallTimeoutMs: 180000,
+    workspaceLockTimeoutMs: 900000,
   };
 
   afterEach(() => {
@@ -476,3 +479,110 @@ describe("loadArtifactStorageConfig", () => {
     expect(cfg.type).toBe("proxy");
   });
 });
+
+// ── resolveUsableArtifactStorage (DD-26 follow-up #1) ─────────────────
+//
+// The shared construct-or-degrade seam: it must return `undefined` (never throw)
+// for every "no working substrate" condition so both harnesses fall to the
+// deny-gate up front, instead of flowing file writes then crashing at the
+// turn-boundary upload.
+
+describe("resolveUsableArtifactStorage", () => {
+  const ctx = { executionId: "exec-test" };
+  let tempDir: string;
+
+  beforeEach(async () => {
+    tempDir = await mkdtemp(join(tmpdir(), "resolve-artifact-test-"));
+  });
+
+  afterEach(async () => {
+    await rm(tempDir, { recursive: true, force: true });
+    vi.restoreAllMocks();
+  });
+
+  const localCfg = (localPath: string): ArtifactStorageConfig => ({
+    type: "local",
+    localPath,
+    localServeUrl: "http://localhost:7235",
+    proxyEndpoint: null,
+    proxyAuthToken: null,
+  });
+
+  it("returns a LocalArtifactStorage for a writable path and leaves no residue", async () => {
+    const base = join(tempDir, "artifacts");
+    const storage = await resolveUsableArtifactStorage(localCfg(base), ctx);
+
+    expect(storage).toBeInstanceOf(LocalArtifactStorage);
+    // The write-probe file must be cleaned up; the base dir may be created.
+    const entries = await readdir(base);
+    expect(entries).toEqual([]);
+  });
+
+  it("returns undefined for an unwritable local path (mkdir ENOTDIR)", async () => {
+    // Deterministic, cross-platform: point localPath at a child of a regular
+    // FILE, so the resolver's recursive mkdir fails with ENOTDIR.
+    const filePath = join(tempDir, "not-a-dir");
+    await writeFile(filePath, "");
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => undefined);
+
+    const storage = await resolveUsableArtifactStorage(
+      localCfg(join(filePath, "sub")),
+      ctx,
+    );
+
+    expect(storage).toBeUndefined();
+    expect(warn).toHaveBeenCalledWith(
+      expect.stringContaining("local path not writable"),
+    );
+  });
+
+  it("returns undefined when proxy config is a misconfig (construct throws)", async () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => undefined);
+    const cfg: ArtifactStorageConfig = {
+      type: "proxy",
+      localPath: "/tmp/artifacts",
+      localServeUrl: "http://localhost:7235",
+      proxyEndpoint: "https://proxy.example.com",
+      proxyAuthToken: null, // missing token
+    };
+
+    const storage = await resolveUsableArtifactStorage(cfg, ctx);
+
+    expect(storage).toBeUndefined();
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining("unavailable"));
+  });
+
+  it("returns a ProxyArtifactStorage for a valid proxy config without any network call", async () => {
+    // Proxy is never probed at the network layer — assert no fetch happens.
+    const fetchSpy = vi.spyOn(globalThis, "fetch");
+    const cfg: ArtifactStorageConfig = {
+      type: "proxy",
+      localPath: "/tmp/artifacts",
+      localServeUrl: "http://localhost:7235",
+      proxyEndpoint: "https://proxy.example.com",
+      proxyAuthToken: "token-123",
+    };
+
+    const storage = await resolveUsableArtifactStorage(cfg, ctx);
+
+    expect(storage).toBeInstanceOf(ProxyArtifactStorage);
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+
+  it("wires through to deriveCaptureMode: an unwritable local store degrades a non-git turn to the deny-gate", async () => {
+    const filePath = join(tempDir, "not-a-dir");
+    await writeFile(filePath, "");
+    vi.spyOn(console, "warn").mockImplementation(() => undefined);
+
+    const storage = await resolveUsableArtifactStorage(
+      localCfg(join(filePath, "sub")),
+      ctx,
+    );
+
+    // Non-git workspace + no usable storage => no capture substrate => deny-gate.
+    expect(deriveCaptureMode("/some/workspace", false, !!storage)).toBe(false);
+    // A git workspace still captures (git substrate needs no storage), but its
+    // gitignored->CAS edits and offload are off because the store is absent.
+    expect(deriveCaptureMode("/some/workspace", true, !!storage)).toBe(true);
+  });
+});

package/src/shared/__tests__/implement-plan-prompt.test.ts

@@ -0,0 +1,48 @@
+import { describe, it, expect } from "vitest";
+import {
+  buildImplementPlanDirective,
+  findApprovedPlanPath,
+} from "../implement-plan-prompt.js";
+
+describe("findApprovedPlanPath", () => {
+  it("finds the plan by its canonical filename among attachment paths", () => {
+    expect(
+      findApprovedPlanPath([
+        ".stigmer/inputs/data.csv",
+        ".stigmer/inputs/plan.md",
+      ]),
+    ).toBe(".stigmer/inputs/plan.md");
+  });
+
+  it("returns undefined when no plan attachment resolved", () => {
+    expect(findApprovedPlanPath([".stigmer/inputs/data.csv"])).toBeUndefined();
+    expect(findApprovedPlanPath([])).toBeUndefined();
+  });
+
+  it("matches the basename exactly — a plan-adjacent filename is not the plan", () => {
+    expect(
+      findApprovedPlanPath([".stigmer/inputs/my-plan.md.bak"]),
+    ).toBeUndefined();
+  });
+});
+
+describe("buildImplementPlanDirective", () => {
+  it("points the model at the attached plan and names it authoritative", () => {
+    const directive = buildImplementPlanDirective(".stigmer/inputs/plan.md");
+
+    expect(directive).toContain("APPROVED");
+    expect(directive).toContain("`.stigmer/inputs/plan.md`");
+    expect(directive).toContain("Read it FIRST");
+    // The user may have edited the document after the plan turn — the file,
+    // not the conversation, is the approved text.
+    expect(directive).toContain("authoritative");
+  });
+
+  it("falls back to the conversation's plan when nothing is attached", () => {
+    const directive = buildImplementPlanDirective(undefined);
+
+    expect(directive).toContain("APPROVED");
+    expect(directive).toContain("conversation above");
+    expect(directive).not.toContain("plan.md");
+  });
+});

package/src/shared/__tests__/secret-leak-scan.test.ts

@@ -0,0 +1,105 @@
+/**
+ * Deny-gate secret leak-scan (DD-26 follow-up #2) — the load-bearing guarantee.
+ *
+ * The runner-level analog of the offline Go `TestOffline_FileReview_
+ * SecretUnderGlobalBypass_NeverPersisted`: assemble a realistic deny-gate status
+ * whose transcript carries a secret-like write with its content, run the
+ * Invariant-A backstop that BOTH harnesses call before persisting, then serialize
+ * the whole status and assert none of the secret bytes survive.
+ *
+ * An offline end-to-end test is structurally infeasible for this path (DD-23 /
+ * DD-26 F3: the offline harness always runs a git workspace with LocalArtifactDir,
+ * so deriveCaptureMode is always true and the no-storage deny-gate is unreachable).
+ * This test exercises the exact function both `execute-deep-agent/index.ts` and the
+ * Cursor `persist` wrapper invoke, over a full AgentExecutionStatus.
+ */
+
+import { describe, it, expect } from "vitest";
+import { create, toJsonString } from "@bufbuild/protobuf";
+import {
+  AgentMessageSchema,
+  ToolCallSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import { SubAgentExecutionSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/subagent_pb";
+import { AgentExecutionStatusSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { ToolCallStatus, MessageType } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { withholdSecretContentFromMessages } from "../tool-row.js";
+
+const SECRET = "API_KEY=SUPER_SECRET_LEAK_TOKEN_9f3a";
+
+function secretWriteRow(id: string, path: string) {
+  return create(ToolCallSchema, {
+    id,
+    name: "write",
+    status: ToolCallStatus.TOOL_CALL_COMPLETED,
+    result: "wrote file",
+    argsPreview: JSON.stringify({ path, content: SECRET }),
+    args: { path, content: SECRET },
+  });
+}
+
+describe("deny-gate secret leak-scan", () => {
+  it("no secret bytes survive in the serialized status (top-level + sub-agent), non-secret content preserved", () => {
+    const status = create(AgentExecutionStatusSchema, {
+      messages: [
+        create(AgentMessageSchema, {
+          type: MessageType.MESSAGE_AI,
+          toolCalls: [
+            secretWriteRow("tc-secret", ".env"),
+            // A non-secret write in the same turn must keep its content (the
+            // backstop is scoped to secret-like paths only).
+            create(ToolCallSchema, {
+              id: "tc-ok",
+              name: "write",
+              status: ToolCallStatus.TOOL_CALL_COMPLETED,
+              argsPreview: JSON.stringify({ path: "notes.md" }),
+              args: { path: "notes.md", content: "PUBLIC_NOTES_BODY" },
+            }),
+          ],
+        }),
+      ],
+      subAgentExecutions: [
+        create(SubAgentExecutionSchema, {
+          id: "sa-1",
+          messages: [
+            create(AgentMessageSchema, {
+              type: MessageType.MESSAGE_AI,
+              toolCalls: [secretWriteRow("tc-sa-secret", "config/credentials.json")],
+            }),
+          ],
+        }),
+      ],
+    });
+
+    // The mechanism both harnesses call before every persist.
+    withholdSecretContentFromMessages(status.messages, status.subAgentExecutions);
+
+    const serialized = toJsonString(AgentExecutionStatusSchema, status);
+    expect(serialized).not.toContain(SECRET);
+    // The paths remain (a filename is not the secret); non-secret content survives.
+    expect(serialized).toContain(".env");
+    expect(serialized).toContain("config/credentials.json");
+    expect(serialized).toContain("PUBLIC_NOTES_BODY");
+  });
+
+  it("global bypass: the backstop is the sole guarantee when no gate scrubbed the row", () => {
+    // Under auto_approve_all neither harness installs a gate, so a secret write
+    // flows and its content lands on the streamed row unscrubbed. The backstop —
+    // called unconditionally before persist — is the only thing standing between
+    // that row and durable storage.
+    const status = create(AgentExecutionStatusSchema, {
+      messages: [
+        create(AgentMessageSchema, {
+          type: MessageType.MESSAGE_AI,
+          toolCalls: [secretWriteRow("tc-flowed", ".aws/credentials")],
+        }),
+      ],
+    });
+
+    withholdSecretContentFromMessages(status.messages, status.subAgentExecutions);
+
+    const serialized = toJsonString(AgentExecutionStatusSchema, status);
+    expect(serialized).not.toContain(SECRET);
+    expect(serialized).toContain(".aws/credentials"); // path kept, honest record
+  });
+});

package/src/shared/__tests__/status.test.ts

@@ -324,7 +324,7 @@ describe("persistStatus — transient retry", () => {
 });
 
 describe("reportSetupProgress", () => {
-  it("persists a status with the given phase name", async () => {
+  it("persists the label WITHOUT forcing a phase transition", async () => {
     const mockClient = {
       updateStatus: vi.fn().mockResolvedValue({
         signal: ExecutionControlSignal.UNSPECIFIED,
@@ -334,7 +334,12 @@ describe("reportSetupProgress", () => {
     expect(mockClient.updateStatus).toHaveBeenCalledOnce();
     const [id, status] = mockClient.updateStatus.mock.calls[0];
     expect(id).toBe("exec-3");
-    expect(status.phase).toBe(ExecutionPhase.EXECUTION_IN_PROGRESS);
+    // UNSPECIFIED = "leave the phase unchanged". The server keeps
+    // setup_progress only while the merged phase is still PENDING, so a
+    // setup report must never flip the phase itself — sending IN_PROGRESS
+    // here made every setup label (and the workspace-lock waiting state)
+    // self-destruct on arrival.
+    expect(status.phase).toBe(ExecutionPhase.EXECUTION_PHASE_UNSPECIFIED);
     expect(status.setupProgress?.currentPhase).toBe("Resolving MCP servers");
   });
 });

package/src/shared/__tests__/tool-row.test.ts

@@ -10,7 +10,14 @@ import { create } from "@bufbuild/protobuf";
 import { AgentMessageSchema, ToolCallSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
 import { SubAgentExecutionSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/subagent_pb";
 import { ToolCallStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
-import { collectSubAgentToolCallIds, hideToolCallRow, isToolCallRowHidden, stampFileEditRow } from "../tool-row.js";
+import {
+  collectSubAgentToolCallIds,
+  hideToolCallRow,
+  isToolCallRowHidden,
+  stampFileEditRow,
+  withholdSecretContentFromMessages,
+  withholdSecretFileContent,
+} from "../tool-row.js";
 
 describe("stampFileEditRow", () => {
   it("stamps additively: content, status, and identity all survive", () => {
@@ -90,6 +97,134 @@ describe("stampFileEditRow", () => {
   });
 });
 
+describe("withholdSecretFileContent", () => {
+  it("reduces a secret-like row's args to { path } and clears args_preview, keeping result", () => {
+    const tc = create(ToolCallSchema, {
+      id: "tc-1",
+      name: "write",
+      status: ToolCallStatus.TOOL_CALL_COMPLETED,
+      result: "Tool 'write' was blocked for security: '.env' matches a secret-like path. Nothing was written.",
+      argsPreview: '{"path":".env"}',
+      args: { path: ".env", content: "API_KEY=super-secret" },
+    });
+
+    expect(withholdSecretFileContent(tc)).toBe(true);
+    expect(tc.args).toEqual({ path: ".env" });
+    expect(tc.argsPreview).toBe("");
+    // result is left intact — the deny-gate uses it for the safe "blocked" message.
+    expect(tc.result).toContain("blocked for security");
+  });
+
+  it("leaves a non-secret row untouched and returns false", () => {
+    const tc = create(ToolCallSchema, {
+      id: "tc-2",
+      name: "write",
+      status: ToolCallStatus.TOOL_CALL_COMPLETED,
+      argsPreview: '{"path":"src/app.ts"}',
+      args: { path: "src/app.ts", content: "console.log('hi')" },
+    });
+
+    expect(withholdSecretFileContent(tc)).toBe(false);
+    expect(tc.args).toEqual({ path: "src/app.ts", content: "console.log('hi')" });
+    expect(tc.argsPreview).toBe('{"path":"src/app.ts"}');
+  });
+
+  it("fail-closes when the path cannot be determined (args → undefined)", () => {
+    const tc = create(ToolCallSchema, {
+      id: "tc-3",
+      name: "write",
+      status: ToolCallStatus.TOOL_CALL_COMPLETED,
+      args: { unrecognized_shape: "payload" },
+    });
+
+    expect(withholdSecretFileContent(tc)).toBe(true);
+    expect(tc.args).toBeUndefined();
+  });
+});
+
+describe("withholdSecretContentFromMessages", () => {
+  function writeRow(id: string, path: string, content = "SECRET_BODY"): ReturnType<typeof create<typeof ToolCallSchema>> {
+    return create(ToolCallSchema, {
+      id,
+      name: "write",
+      status: ToolCallStatus.TOOL_CALL_COMPLETED,
+      argsPreview: JSON.stringify({ path }),
+      args: { path, content },
+    });
+  }
+
+  it("withholds content from a secret write row but leaves a non-secret one intact", () => {
+    const msg = create(AgentMessageSchema, {
+      type: 1,
+      toolCalls: [writeRow("tc-secret", ".env"), writeRow("tc-ok", "src/app.ts")],
+    });
+
+    withholdSecretContentFromMessages([msg]);
+
+    expect(msg.toolCalls[0].args).toEqual({ path: ".env" });
+    expect(msg.toolCalls[0].argsPreview).toBe("");
+    expect(msg.toolCalls[1].args).toEqual({ path: "src/app.ts", content: "SECRET_BODY" });
+  });
+
+  it("covers edit-family rows (category write) too", () => {
+    const editRow = create(ToolCallSchema, {
+      id: "tc-edit",
+      name: "StrReplace",
+      status: ToolCallStatus.TOOL_CALL_COMPLETED,
+      args: { path: ".ssh/id_rsa", old_string: "a", new_string: "b" },
+    });
+    const msg = create(AgentMessageSchema, { type: 1, toolCalls: [editRow] });
+
+    withholdSecretContentFromMessages([msg]);
+
+    expect(editRow.args).toEqual({ path: ".ssh/id_rsa" });
+  });
+
+  it("does NOT touch a delete row (deletes carry no content)", () => {
+    const deleteRow = create(ToolCallSchema, {
+      id: "tc-del",
+      name: "delete",
+      status: ToolCallStatus.TOOL_CALL_COMPLETED,
+      args: { path: ".env" },
+    });
+    const msg = create(AgentMessageSchema, { type: 1, toolCalls: [deleteRow] });
+
+    withholdSecretContentFromMessages([msg]);
+
+    // A delete's args are path-only already; the write-scoped pass leaves it alone.
+    expect(deleteRow.args).toEqual({ path: ".env" });
+  });
+
+  it("walks sub-agent transcripts", () => {
+    const topMsg = create(AgentMessageSchema, { type: 1, toolCalls: [writeRow("tc-top", "notes.md")] });
+    const sa = create(SubAgentExecutionSchema, {
+      id: "sa-1",
+      messages: [create(AgentMessageSchema, { type: 1, toolCalls: [writeRow("tc-sa", "credentials.json")] })],
+    });
+
+    withholdSecretContentFromMessages([topMsg], [sa]);
+
+    expect(topMsg.toolCalls[0].args).toEqual({ path: "notes.md", content: "SECRET_BODY" }); // non-secret untouched
+    expect(sa.messages[0].toolCalls[0].args).toEqual({ path: "credentials.json" }); // sub-agent secret scrubbed
+  });
+
+  it("is idempotent and agrees with stampFileEditRow's content-less shape", () => {
+    const row = writeRow("tc-secret", ".env");
+    const msg = create(AgentMessageSchema, { type: 1, toolCalls: [row] });
+
+    withholdSecretContentFromMessages([msg]);
+    const afterFirst = { args: row.args, argsPreview: row.argsPreview };
+    withholdSecretContentFromMessages([msg]);
+    expect(row.args).toEqual(afterFirst.args);
+    expect(row.argsPreview).toBe(afterFirst.argsPreview);
+
+    // stampFileEditRow on the already-scrubbed row yields the same content-less shape.
+    stampFileEditRow(row, "exec-1:0");
+    expect(row.args).toEqual({ path: ".env" });
+    expect(row.argsPreview).toBe("");
+  });
+});
+
 describe("hideToolCallRow", () => {
   it("collapses a completed file-edit row to the hidden shape", () => {
     const tc = create(ToolCallSchema, {

package/src/shared/artifact-storage.ts

@@ -16,7 +16,7 @@
  * DD-6: No direct R2 backend. Local + Proxy only.
  */
 
-import { mkdir, writeFile, readFile, access } from "node:fs/promises";
+import { mkdir, writeFile, readFile, access, rm } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import type { Config } from "../config.js";
 
@@ -256,3 +256,85 @@ export function createArtifactStorage(cfg: ArtifactStorageConfig): ArtifactStora
 
   return new LocalArtifactStorage(cfg.localPath, cfg.localServeUrl);
 }
+
+/**
+ * Prove that `basePath` can actually be written to, the way {@link
+ * LocalArtifactStorage.upload} writes: create the directory tree, write a
+ * throwaway file, then remove it. Returns `false` on any failure.
+ *
+ * We do an actual write rather than `access(basePath, W_OK)` deliberately:
+ * `access` can lie under root / ACLs / overlay filesystems (it checks the
+ * permission bits, not the real outcome), it does not exercise the recursive
+ * `mkdir` + `writeFile` that `upload` performs (so it misses a `basePath` whose
+ * parent is a file, an ENOTDIR), and it cannot catch a full disk. The scratch
+ * file is uniquely named so concurrent runners never collide, and is removed
+ * even though `basePath` (which we want to exist anyway) is left in place.
+ */
+async function isLocalPathWritable(basePath: string): Promise<boolean> {
+  const probePath = join(basePath, `.write-probe-${process.pid}-${Date.now()}`);
+  try {
+    await mkdir(basePath, { recursive: true });
+    await writeFile(probePath, "");
+    await rm(probePath, { force: true });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Resolve a *usable* artifact store for the file-review capture / status-offload
+ * path, degrading to `undefined` instead of crashing when there is no working
+ * substrate. This is the single construct-or-degrade seam shared by both
+ * harnesses (the deep-agent and Cursor activities) so they degrade identically.
+ *
+ * Two degrade paths:
+ *  - **Proxy misconfig** — {@link createArtifactStorage} throws for a missing
+ *    endpoint/token; caught here and reported absent.
+ *  - **Unwritable local path** — {@link LocalArtifactStorage} constructs around a
+ *    path string and never throws, so an unwritable base path (bad mount, EPERM,
+ *    full disk) would otherwise let file writes FLOW during the turn and only
+ *    crash at the turn-boundary upload, with the workspace already mutated and no
+ *    review authored. We probe writability up front and report absent instead.
+ *
+ * Proxy is intentionally NOT probed at the network layer: a live-endpoint check
+ * would add a round-trip to every cloud setup and risk falsely degrading on a
+ * transient blip; construction already validates its config.
+ *
+ * An absent store is a first-class, already-supported state (DD-26): capture
+ * degrades to the deny-gate (via {@link deriveCaptureMode}'s `hasArtifactStorage`
+ * argument), tool-output offload is disabled (the aggregate size guard still
+ * applies), and attachment / plan-artifact publishing surface a clear error.
+ * This is the fail-safe realization of DD-26 follow-up #1.
+ *
+ * NOTE: this resolver is for the capture/offload path only. Claimcheck (Temporal
+ * payload offload) MUST have storage and has no deny-gate to fall back to, so it
+ * deliberately keeps calling {@link createArtifactStorage} directly (fail-hard).
+ */
+export async function resolveUsableArtifactStorage(
+  cfg: ArtifactStorageConfig,
+  ctx: { executionId: string },
+): Promise<ArtifactStorage | undefined> {
+  let storage: ArtifactStorage;
+  try {
+    storage = createArtifactStorage(cfg);
+  } catch (err) {
+    console.warn(
+      `[artifact-storage] unavailable — file capture degrades to the deny-gate ` +
+      `and tool-output offload is disabled: execution=${ctx.executionId}, ` +
+      `type=${cfg.type}, error=${err}`,
+    );
+    return undefined;
+  }
+
+  if (cfg.type === "local" && !(await isLocalPathWritable(cfg.localPath))) {
+    console.warn(
+      `[artifact-storage] local path not writable — file capture degrades to the ` +
+      `deny-gate and tool-output offload is disabled: execution=${ctx.executionId}, ` +
+      `path=${cfg.localPath}`,
+    );
+    return undefined;
+  }
+
+  return storage;
+}

package/src/shared/implement-plan-prompt.ts

@@ -0,0 +1,73 @@
+/**
+ * The Build-from-plan prompt directive, shared by both harnesses.
+ *
+ * When the user approves a plan and clicks "Build from plan", the client
+ * submits an execution with `spec.execution_config.build_from_plan` set and a
+ * short human-readable message ("Build from plan") — it does NOT embed
+ * implement instructions in the message text. The runner owns the agent-facing
+ * instruction, injected from this module, so the chat thread can render the
+ * turn as a compact chip while the model still receives the full contract.
+ *
+ * The directive has two variants, chosen by whether the approved plan document
+ * actually materialized in the workspace:
+ * - Attached (the normal case): the client uploaded the approved plan text
+ *   (edited or not) and attached it, mounted at `.stigmer/inputs/plan.md`.
+ *   The directive points the model at that file and names it authoritative —
+ *   the user may have refined the document after the plan turn, so the
+ *   conversation's version can be stale.
+ * - Conversation-only (the client's upload failed): the directive falls back
+ *   to the plan as proposed in the conversation.
+ *
+ * Like `PLAN_MODE_DIRECTIVE` (plan-mode-prompt.ts), this module is the single
+ * source of truth for the words; each harness wraps them in its own prompt
+ * framing (XML-tag section for Cursor, markdown heading for the native
+ * harness).
+ */
+
+import { PLAN_ARTIFACT_NAME } from "./plan-artifact.js";
+
+/**
+ * Find the approved plan document among the workspace paths the harness
+ * injected for this execution's attachments. Detection keys on the canonical
+ * plan filename — the same convention the UI uses to detect the plan artifact.
+ * Returns `undefined` when no plan attachment landed (upload failed, or the
+ * attachment itself failed to inject), which selects the conversation-only
+ * directive variant.
+ */
+export function findApprovedPlanPath(
+  attachmentPaths: readonly string[],
+): string | undefined {
+  return attachmentPaths.find(
+    (p) => p.split("/").pop() === PLAN_ARTIFACT_NAME,
+  );
+}
+
+/**
+ * Build the implement-plan directive body for a Build-from-plan execution.
+ *
+ * @param planPath - Workspace-relative path of the attached approved plan
+ *   (from {@link findApprovedPlanPath}), or `undefined` when the plan exists
+ *   only in the conversation.
+ */
+export function buildImplementPlanDirective(planPath?: string): string {
+  if (planPath) {
+    return [
+      "IMPORTANT: This turn implements a plan the user has reviewed and " +
+        "APPROVED.",
+      "",
+      `The approved plan document is attached at \`${planPath}\`. Read it ` +
+        "FIRST, then implement it step by step.",
+      "",
+      "That document is the authoritative version of the plan — the user may " +
+        "have edited it after it was proposed, so where it differs from the " +
+        "conversation above, follow the document.",
+    ].join("\n");
+  }
+
+  return [
+    "IMPORTANT: This turn implements a plan the user has reviewed and " +
+      "APPROVED.",
+    "",
+    "Implement the plan proposed in the conversation above, step by step.",
+  ].join("\n");
+}