@stigmer/runner 3.1.1 → 3.1.3

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

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import { describe, it, expect } from "vitest";
 import { create } from "@bufbuild/protobuf";
 import { AgentExecutionStatusSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
@@ -11,8 +12,9 @@ import { makeInMemoryArtifactStorage } from "../../__test-utils__/fake-artifact-
 import {
   extractFinalPlanText,
   publishPlanArtifact,
+  planArtifactName,
+  isPlanArtifactName,
   PLAN_ARTIFACT_NAME,
-  PLAN_ARTIFACT_SANDBOX_PATH,
 } from "../plan-artifact.js";
 
 /** Records uploads and returns deterministic download URLs (canonical double + shim). */
@@ -27,6 +29,11 @@ function fakeStorage(): ArtifactStorage & { uploads: { key: string; content: Buf
   return Object.assign(storage, { uploads });
 }
 
+/** Mirrors the runner's content-hash discriminator so tests can assert exact names. */
+function planId(text: string): string {
+  return createHash("sha256").update(text, "utf-8").digest("hex").slice(0, 8);
+}
+
 function statusWith(...messages: { type: MessageType; content: string }[]) {
   return create(AgentExecutionStatusSchema, {
     messages: messages.map((m) =>
@@ -59,30 +66,129 @@ describe("extractFinalPlanText", () => {
   });
 });
 
+describe("planArtifactName", () => {
+  it("derives a hyphenated <slug>_<id>.plan.md name from the plan's leading # H1", () => {
+    const text = "# Plan Card UX Cleanup\n\nBody";
+    // "Plan Card…" has no label separator, so the genuine word "plan" survives.
+    expect(planArtifactName(text)).toBe(`plan-card-ux-cleanup_${planId(text)}.plan.md`);
+  });
+
+  it("strips a leading 'Plan:' LABEL (colon/dash-anchored) from the slug", () => {
+    const text = "# Plan: Fix the download UX\n\nbody";
+    expect(planArtifactName(text)).toBe(`fix-the-download-ux_${planId(text)}.plan.md`);
+  });
+
+  it("collapses runs of punctuation/whitespace and trims edge hyphens", () => {
+    const text = "#  Fix: the (download) UX!! \nx";
+    expect(planArtifactName(text)).toBe(`fix-the-download-ux_${planId(text)}.plan.md`);
+  });
+
+  it("unwraps a ```markdown fenced plan before reading the title (SDK parity)", () => {
+    const text = "```markdown\n# Named Plan\n\nbody\n```";
+    expect(planArtifactName(text)).toBe(`named-plan_${planId(text)}.plan.md`);
+  });
+
+  it("unwraps a bare ``` fenced plan before reading the title (SDK parity)", () => {
+    const text = "```\n# Bare Fenced Plan\n\nbody\n```";
+    expect(planArtifactName(text)).toBe(`bare-fenced-plan_${planId(text)}.plan.md`);
+  });
+
+  it("caps the slug length so filenames stay bounded", () => {
+    const longTitle = "# " + "word ".repeat(40); // ~200 chars of words
+    const name = planArtifactName(longTitle);
+    const match = /^(.+)_[0-9a-f]{8}\.plan\.md$/.exec(name);
+    expect(match).not.toBeNull();
+    const slug = match![1];
+    expect(slug.length).toBeLessThanOrEqual(60);
+    expect(slug.endsWith("-")).toBe(false);
+  });
+
+  it("falls back to a bare <id>.plan.md when there is no leading H1", () => {
+    const noTitle = "No title here\n\nbody";
+    expect(planArtifactName(noTitle)).toBe(`${planId(noTitle)}.plan.md`);
+    // An H1 further down is body content, not the title.
+    const later = "intro\n\n# Later Heading";
+    expect(planArtifactName(later)).toBe(`${planId(later)}.plan.md`);
+  });
+
+  it("falls back to a bare <id>.plan.md when the title is only the 'Plan:' label", () => {
+    const text = "# Plan:\n\nbody";
+    expect(planArtifactName(text)).toBe(`${planId(text)}.plan.md`);
+  });
+
+  it("falls back to a bare <id>.plan.md when the title has no alphanumerics", () => {
+    const text = "# ---\n\nbody";
+    expect(planArtifactName(text)).toBe(`${planId(text)}.plan.md`);
+  });
+
+  it("never freshly emits the legacy plan.md name", () => {
+    for (const text of ["# A Title\n\nbody", "no heading", "# Plan:\n\nx"]) {
+      expect(planArtifactName(text)).not.toBe(PLAN_ARTIFACT_NAME);
+    }
+  });
+});
+
+describe("isPlanArtifactName", () => {
+  it("accepts the legacy exact name and any *.plan.md", () => {
+    expect(isPlanArtifactName("plan.md")).toBe(true);
+    expect(isPlanArtifactName("feature_x.plan.md")).toBe(true);
+    expect(isPlanArtifactName("fix-the-download-ux_a1b2c3d4.plan.md")).toBe(true);
+    expect(isPlanArtifactName("a1b2c3d4.plan.md")).toBe(true);
+  });
+
+  it("rejects non-plan filenames", () => {
+    expect(isPlanArtifactName("notes.md")).toBe(false);
+    expect(isPlanArtifactName("plan.md.bak")).toBe(false);
+    expect(isPlanArtifactName("myplan.md")).toBe(false);
+  });
+});
+
 describe("publishPlanArtifact", () => {
-  it("uploads plan.md and registers a FILE artifact on the status", async () => {
+  it("uploads the named plan and registers a FILE artifact on the status", async () => {
     const status = create(AgentExecutionStatusSchema, {});
     const storage = fakeStorage();
 
+    const planText = "# Plan Card UX Cleanup\n1. step one\n2. step two\n";
+    const name = `plan-card-ux-cleanup_${planId(planText)}.plan.md`;
     await publishPlanArtifact({
       status,
       executionId: "aex_123",
-      planText: "# Plan\n1. step one\n2. step two\n",
+      planText,
       artifactStorage: storage,
     });
 
     expect(storage.uploads).toHaveLength(1);
-    expect(storage.uploads[0].key).toBe("artifacts/aex_123/plan.md");
+    expect(storage.uploads[0].key).toBe(`artifacts/aex_123/${name}`);
     expect(storage.uploads[0].contentType).toBe("text/markdown");
 
     expect(status.artifacts).toHaveLength(1);
     const artifact = status.artifacts[0];
-    expect(artifact.name).toBe(PLAN_ARTIFACT_NAME);
-    expect(artifact.sandboxPath).toBe(PLAN_ARTIFACT_SANDBOX_PATH);
+    expect(artifact.name).toBe(name);
+    expect(artifact.sandboxPath).toBe(`.stigmer/plans/${name}`);
     expect(artifact.kind).toBe(ExecutionArtifactKind.FILE);
-    expect(artifact.storageKey).toBe("artifacts/aex_123/plan.md");
+    expect(artifact.storageKey).toBe(`artifacts/aex_123/${name}`);
     expect(artifact.sizeBytes).toBeGreaterThan(0n);
     expect(artifact.contentHash).toHaveLength(64);
+    // The filename's <id> is the leading 8 hex of the full content hash.
+    expect(artifact.contentHash.startsWith(planId(planText))).toBe(true);
+  });
+
+  it("uses a bare <id>.plan.md name for a titleless plan (never the legacy plan.md)", async () => {
+    const status = create(AgentExecutionStatusSchema, {});
+    const storage = fakeStorage();
+
+    const planText = "just a paragraph, no heading";
+    const name = `${planId(planText)}.plan.md`;
+    await publishPlanArtifact({
+      status,
+      executionId: "aex_notitle",
+      planText,
+      artifactStorage: storage,
+    });
+
+    expect(status.artifacts[0].name).toBe(name);
+    expect(status.artifacts[0].name).not.toBe(PLAN_ARTIFACT_NAME);
+    expect(storage.uploads[0].key).toBe(`artifacts/aex_notitle/${name}`);
   });
 
   it("is a no-op for empty plan text (nothing to publish)", async () => {
@@ -100,20 +206,47 @@ describe("publishPlanArtifact", () => {
     expect(status.artifacts).toHaveLength(0);
   });
 
-  it("replaces an existing plan.md rather than appending a duplicate", async () => {
+  it("replaces an existing plan rather than appending a duplicate", async () => {
     const status = create(AgentExecutionStatusSchema, {});
     const storage = fakeStorage();
 
     await publishPlanArtifact({ status, executionId: "aex_re", planText: "v1", artifactStorage: storage });
     await publishPlanArtifact({ status, executionId: "aex_re", planText: "v2 longer plan", artifactStorage: storage });
 
+    // Replacement is at the STATUS level, matched by the *.plan.md predicate:
+    // exactly one plan artifact survives. Because names are content-derived,
+    // the two differing-content writes land under DIFFERENT keys (the first is
+    // an orphan blob) — but this synthetic double-publish never happens in
+    // production, where publishPlanArtifact runs once per execution finalization
+    // and a same-content retry re-writes the same key.
     expect(status.artifacts).toHaveLength(1);
     expect(storage.uploads).toHaveLength(2);
-    // The surviving artifact reflects the latest content hash.
     const latestHash = storage.uploads[1].content;
     expect(status.artifacts[0].sizeBytes).toBe(BigInt(latestHash.length));
   });
 
+  it("replaces a prior plan even when the derived name changed (predicate match)", async () => {
+    const status = create(AgentExecutionStatusSchema, {});
+    const storage = fakeStorage();
+
+    await publishPlanArtifact({
+      status,
+      executionId: "aex_rename",
+      planText: "# First Title\n\nbody",
+      artifactStorage: storage,
+    });
+    const secondText = "# Second Title\n\nbody";
+    await publishPlanArtifact({
+      status,
+      executionId: "aex_rename",
+      planText: secondText,
+      artifactStorage: storage,
+    });
+
+    expect(status.artifacts).toHaveLength(1);
+    expect(status.artifacts[0].name).toBe(`second-title_${planId(secondText)}.plan.md`);
+  });
+
   it("never throws when the upload fails (publish is non-fatal)", async () => {
     const status = create(AgentExecutionStatusSchema, {});
     const { storage: failing } = makeInMemoryArtifactStorage();

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;
+}