@stigmer/runner 3.1.0 → 3.1.2

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.0",
+  "version": "3.1.2",
   "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.0",
+    "@stigmer/protos": "3.1.2",
     "@temporalio/activity": "^1.11.0",
     "@temporalio/client": "^1.11.0",
     "@temporalio/common": "^1.11.0",
@@ -96,12 +95,15 @@
     "deepagents": "^1.10.0",
     "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);
+  });
+});

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

@@ -9,12 +9,13 @@
 
 import { describe, it, expect } from "vitest";
 import { create } from "@bufbuild/protobuf";
-import { ApprovalAction } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { ApprovalAction, InteractionMode } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import { PendingApprovalSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/approval_pb";
 
 import { buildPrompt } from "../index.js";
 import type { BuildPromptInput } from "../index.js";
-import { buildReinvocationPrompt, formatToolApprovalProtocol, buildToolApprovalRuleFile } from "../prompt-builder.js";
+import { buildReinvocationPrompt, formatInteractionModePrefix, formatImplementPlanSection, formatToolApprovalProtocol, buildToolApprovalRuleFile } from "../prompt-builder.js";
+import { PLAN_MODE_DIRECTIVE } from "../../../shared/plan-mode-prompt.js";
 import type { AgentResolution, AgentResolutionReason } from "../session-lifecycle.js";
 
 const USER_MESSAGE = "What was the secret token I told you?";
@@ -250,3 +251,125 @@ describe("buildReinvocationPrompt", () => {
     expect(prompt).not.toContain("Carry them out now");
   });
 });
+
+describe("formatInteractionModePrefix", () => {
+  it("wraps the shared plan-mode directive in the interaction_mode section", () => {
+    const prefix = formatInteractionModePrefix(InteractionMode.PLAN);
+
+    expect(prefix).toBeDefined();
+    expect(prefix!.startsWith("<interaction_mode>")).toBe(true);
+    expect(prefix!.endsWith("</interaction_mode>")).toBe(true);
+    expect(prefix).toContain(PLAN_MODE_DIRECTIVE);
+  });
+
+  it.each([
+    ["AGENT", InteractionMode.AGENT],
+    ["UNSPECIFIED", InteractionMode.UNSPECIFIED],
+    ["undefined", undefined],
+  ])("returns undefined for %s", (_label, mode) => {
+    expect(formatInteractionModePrefix(mode)).toBeUndefined();
+  });
+
+  it("injects the directive into a Plan-mode first prompt", () => {
+    const prompt = buildPrompt(
+      input({
+        resolution: resolution("local", "created_first_execution"),
+        interactionMode: InteractionMode.PLAN,
+      }),
+    );
+
+    expect(prompt).toContain("<interaction_mode>");
+    expect(prompt).toContain("your FINAL message IS the plan");
+  });
+
+  it("prefixes the directive on a resumed Plan-mode follow-up (mode is per-execution)", () => {
+    const prompt = buildPrompt(
+      input({
+        resolution: resolution("local", "resumed_successfully"),
+        interactionMode: InteractionMode.PLAN,
+      }),
+    );
+
+    expect(prompt.startsWith("<interaction_mode>")).toBe(true);
+    expect(prompt.endsWith(USER_MESSAGE)).toBe(true);
+  });
+
+  it("keeps a resumed Agent-mode follow-up as the raw user message", () => {
+    const prompt = buildPrompt(
+      input({
+        resolution: resolution("local", "resumed_successfully"),
+        interactionMode: InteractionMode.AGENT,
+      }),
+    );
+
+    expect(prompt).toBe(USER_MESSAGE);
+  });
+});
+
+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"]);
+
+    expect(section).toBeDefined();
+    expect(section!.startsWith("<implement_plan>")).toBe(true);
+    expect(section!.endsWith("</implement_plan>")).toBe(true);
+    expect(section).toContain(`\`${PLAN_PATH}\``);
+    expect(section).toContain("APPROVED");
+  });
+
+  it("falls back to the conversation-plan directive when no plan attachment resolved", () => {
+    const section = formatImplementPlanSection(true, [".stigmer/inputs/data.csv"]);
+
+    expect(section).toBeDefined();
+    expect(section).not.toContain("plan.md");
+    expect(section).toContain("conversation above");
+  });
+
+  it("returns undefined for an ordinary (non-build) execution", () => {
+    expect(formatImplementPlanSection(false, [PLAN_PATH])).toBeUndefined();
+    expect(formatImplementPlanSection(undefined, [PLAN_PATH])).toBeUndefined();
+  });
+
+  it("injects the directive into a build-from-plan first prompt", () => {
+    const prompt = buildPrompt(
+      input({
+        resolution: resolution("local", "created_first_execution"),
+        buildFromPlan: true,
+        attachmentPaths: [PLAN_PATH],
+      }),
+    );
+
+    expect(prompt).toContain("<implement_plan>");
+    expect(prompt).toContain(`\`${PLAN_PATH}\``);
+    expect(prompt).toContain(USER_MESSAGE);
+  });
+
+  it("prefixes the directive on a resumed build turn (build_from_plan is per-execution)", () => {
+    // The common shape: the plan turn ran earlier in the session, so the
+    // build turn resumes the agent — the directive must still arrive.
+    const prompt = buildPrompt(
+      input({
+        resolution: resolution("local", "resumed_successfully"),
+        buildFromPlan: true,
+        attachmentPaths: [PLAN_PATH],
+      }),
+    );
+
+    expect(prompt.startsWith("<implement_plan>")).toBe(true);
+    expect(prompt.endsWith(USER_MESSAGE)).toBe(true);
+  });
+
+  it("keeps a resumed non-build follow-up as the raw user message", () => {
+    const prompt = buildPrompt(
+      input({
+        resolution: resolution("local", "resumed_successfully"),
+        buildFromPlan: false,
+        attachmentPaths: [PLAN_PATH],
+      }),
+    );
+
+    expect(prompt).toBe(USER_MESSAGE);
+  });
+});

package/src/activities/execute-cursor/__tests__/cas-observations.test.ts

@@ -26,6 +26,7 @@ import {
   resetCasObservations,
   casObservationsDir,
   buildObservationStagingScript,
+  buildSecretClassifyScript,
 } from "../cas-observations.js";
 import { isSecretLikePath } from "../../../shared/filereview/secret-paths.js";
 
@@ -184,4 +185,58 @@ describe("cas-observations sidecar", () => {
       }
     });
   });
+
+  // The deny-gate (no-capture-substrate) classify-only script. It shares the
+  // classifier fragment with the staging script, so its verdict must equal
+  // isSecretLikePath byte-for-byte — a secret must never fall through the hook's
+  // deny-gate secret hard-block (DD-26 #2).
+  describe("buildSecretClassifyScript (deny-gate classify-only)", () => {
+    function runClassify(salient: string): string {
+      return execFileSync(process.execPath, ["-e", buildSecretClassifyScript()], {
+        input: salient,
+      })
+        .toString()
+        .trim();
+    }
+
+    it("classifies secrets byte-for-byte identically to isSecretLikePath (no staging)", () => {
+      const paths = [
+        ".env",
+        ".env.local",
+        "config/.env.production",
+        "id_rsa",
+        "server.pem",
+        "certs/key.pfx",
+        "terraform.tfstate",
+        ".aws/credentials",
+        "home/.ssh/known_hosts",
+        ".npmrc",
+        "secrets.yaml",
+        "/abs/path/.env",
+        "id_rsa.pub",
+        "app.log",
+        "src/index.ts",
+        "docs/notes.md",
+        "build/out.js",
+        "environment.ts",
+      ];
+      for (const p of paths) {
+        const expected = isSecretLikePath(p) ? "secret" : "ok";
+        expect(runClassify(p), `classification for ${p}`).toBe(expected);
+      }
+    });
+
+    it("fail-closes on empty input (classifies as secret), matching isSecretLikePath('')", () => {
+      expect(runClassify("")).toBe("secret");
+      expect(isSecretLikePath("")).toBe(true);
+    });
+
+    it("does not stage anything (pure classifier)", async () => {
+      const ws = tmp("obs-classify-nostage-");
+      writeFileSync(join(ws, ".env"), "API_KEY=xyz", "utf-8");
+      expect(runClassify(".env")).toBe("secret");
+      // No sidecar dir is created or written by the classify-only script.
+      expect(await readCasObservations(ws)).toEqual({ captured: [], secretPaths: [] });
+    });
+  });
 });