@stigmer/runner 3.1.1 → 3.1.2

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

@@ -0,0 +1,51 @@
+/**
+ * The Plan-mode prompt directive, shared by both harnesses.
+ *
+ * Plan mode's output contract spans three components that must agree:
+ * - the model produces the plan as its FINAL message (this directive),
+ * - the runner publishes that final message verbatim as a `plan.md` artifact
+ *   (`plan-artifact.ts` — `extractFinalPlanText`),
+ * - the SDK promotes the same message to a first-class plan document in the
+ *   thread and offers "Build from plan".
+ *
+ * This module is the single source of truth for how the model is told to
+ * behave, so the two harnesses can never drift apart on the contract. Each
+ * harness wraps the directive in its own prompt framing (the Cursor harness
+ * uses XML-tag sections, the native harness markdown headings) — the framing
+ * is house style; the words are shared.
+ *
+ * Enforcement is separate from instruction: the native harness ALSO denies
+ * filesystem writes at the tool layer (see execute-deep-agent/setup.ts), so
+ * for it this directive is guidance toward a well-formed plan, not the
+ * enforcement mechanism. The Cursor harness has no tool-level lever (the
+ * Cursor SDK exposes no mode parameter), so there this directive is the
+ * enforcement — a documented stopgap.
+ */
+
+/**
+ * Directive body injected into the system prompt of every Plan-mode
+ * execution. Deliberately explicit about the deliverable's shape: the final
+ * message is published verbatim as `plan.md`, so a fenced or chat-suffixed
+ * plan degrades the reviewable document the user sees.
+ */
+export const PLAN_MODE_DIRECTIVE = [
+  "IMPORTANT: You are in Plan mode — a read-only analysis turn whose " +
+    "deliverable is an implementation plan.",
+  "",
+  "Constraints:",
+  "- Do NOT create, edit, or delete any files.",
+  "- Do NOT run commands that modify the filesystem or any external state.",
+  "- Only read, search, and analyze.",
+  "",
+  "Deliverable — your FINAL message IS the plan. It is published verbatim " +
+    "as a `plan.md` document that the user reviews and builds from, so:",
+  "- Write it as a complete, well-structured markdown document: start with " +
+    "a single `#` title and organize the work under `##` section headings. " +
+    "Use lists and tables where they aid scanning.",
+  "- Reference concrete file paths and describe the specific changes " +
+    "planned for each.",
+  "- Do NOT wrap the document in a code fence.",
+  '- Do NOT end with conversational closers ("Let me know...", "Shall I ' +
+    'proceed?") — the next step is the user\'s Build action, and trailing ' +
+    "chat would be published as part of the document.",
+].join("\n");

package/src/shared/status.ts

@@ -193,6 +193,17 @@ export async function persistStatus(
 /**
  * Report a setup progress phase (e.g. "Resolving MCP servers") so the
  * frontend can display a spinner with context.
+ *
+ * Deliberately carries NO execution phase (UNSPECIFIED = "leave unchanged"):
+ * the server keeps `setup_progress` only while the merged phase is still
+ * PENDING (update_status.go / AgentExecutionUpdateStatusHandler clear it the
+ * moment the phase leaves PENDING), and the UI renders the label only in
+ * that window (SetupProgress.tsx: "Server-driven — preferred during
+ * PENDING"). Sending IN_PROGRESS here flipped the phase on the very first
+ * setup report, so every label self-destructed on arrival and the user saw
+ * a generic spinner instead. The genuine PENDING→IN_PROGRESS transition
+ * belongs to the streaming path, which persists it when the agent actually
+ * starts producing output.
  */
 export async function reportSetupProgress(
   client: StigmerClient,
@@ -200,7 +211,6 @@ export async function reportSetupProgress(
   phase: string,
 ): Promise<void> {
   const status = create(AgentExecutionStatusSchema, {
-    phase: ExecutionPhase.EXECUTION_IN_PROGRESS,
     setupProgress: create(SetupProgressSchema, { currentPhase: phase }),
   });
   await persistStatus(client, executionId, status);

package/src/shared/tool-row.ts

@@ -18,10 +18,11 @@
  */
 
 import { ToolCallStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
-import type { ToolCall } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import type { AgentMessage, ToolCall } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
 import type { SubAgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/subagent_pb";
 import { extractFilePath } from "./file-tools.js";
 import { isSecretLikePath } from "./filereview/secret-paths.js";
+import { toolApprovalCategory } from "./tool-kind.js";
 import { utcTimestamp } from "./status.js";
 
 /**
@@ -52,11 +53,63 @@ export function stampFileEditRow(tc: ToolCall, changeSetId: string): void {
   if (tc.fileChangeSetId) return;
   tc.fileChangeSetId = changeSetId;
 
-  const path = extractFilePath((tc.args ?? {}) as Record<string, unknown>) ?? "";
-  if (isSecretLikePath(path)) {
-    tc.args = path ? { path } : undefined;
+  if (withholdSecretFileContent(tc)) {
+    // A FLOWED row's `result` is the tool's own output — for an edit that can
+    // echo the changed lines — so drop it too. withholdSecretFileContent keeps
+    // `result` intact because the deny-gate path (below) uses it for the safe
+    // "blocked for security" message; here the row actually ran, so clear it.
     tc.result = "";
-    tc.argsPreview = "";
+  }
+}
+
+/**
+ * Withhold a file-mutating row's CONTENT while keeping its path visible: reduce
+ * `args` to `{ path }` (or `undefined` when the path cannot be determined) and
+ * clear `args_preview`. `result` and `status` are left untouched — a caller that
+ * needs the diff dropped clears it explicitly (see {@link stampFileEditRow}).
+ * Returns whether the row was secret-like (and therefore withheld).
+ *
+ * The single primitive behind the never-persist-secret-contents contract (design
+ * doc 12, D4): a file-mutating tool's `args` holds the full write body, which for
+ * a secret-like path must never reach the transcript / Temporal history. A
+ * filename is not itself the secret, so the path is kept. Fail-closed: an
+ * undeterminable path is treated as secret-like ({@link isSecretLikePath} of "").
+ */
+export function withholdSecretFileContent(tc: ToolCall): boolean {
+  const path = extractFilePath((tc.args ?? {}) as Record<string, unknown>) ?? "";
+  if (!isSecretLikePath(path)) return false;
+  tc.args = path ? { path } : undefined;
+  tc.argsPreview = "";
+  return true;
+}
+
+/**
+ * Universal backstop (DD-26 follow-up #2): withhold secret content from every
+ * built-in file-WRITE row in a transcript (top-level + each sub-agent's), across
+ * BOTH harnesses, right before the status is persisted.
+ *
+ * This is the ONLY guarantee that survives `spec.auto_approve_all`, where the
+ * approval gate / deny-gate is never installed, so no per-harness hard-block runs
+ * — yet a secret write still flows and its content lands on the streamed row. It
+ * is a no-op in capture mode (the flowed rows are already content-less after
+ * {@link stampFileEditRow}, which shares {@link withholdSecretFileContent}), and
+ * is the deny-gate analog of the capture-mode stamping pass, which does not run
+ * when there is no change set. Scoped to `write` (FILE_WRITE/FILE_EDIT) because a
+ * delete carries no content.
+ */
+export function withholdSecretContentFromMessages(
+  messages: readonly AgentMessage[],
+  subAgents?: readonly SubAgentExecution[],
+): void {
+  for (const msg of messages) {
+    for (const tc of msg.toolCalls) {
+      if (toolApprovalCategory(tc.name) === "write") {
+        withholdSecretFileContent(tc);
+      }
+    }
+  }
+  for (const sa of subAgents ?? []) {
+    withholdSecretContentFromMessages(sa.messages);
   }
 }
 

package/src/shared/workspace/__tests__/session-root.test.ts

@@ -0,0 +1,42 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtemp, rm, stat } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { resolveSessionWorkspaceRoot } from "../session-root.js";
+
+let rootDir: string;
+
+beforeEach(async () => {
+  rootDir = await mkdtemp(join(tmpdir(), "stigmer-session-root-"));
+});
+
+afterEach(async () => {
+  await rm(rootDir, { recursive: true, force: true });
+});
+
+describe("resolveSessionWorkspaceRoot", () => {
+  it("returns the shared root untouched when the session has workspace entries", async () => {
+    const resolved = await resolveSessionWorkspaceRoot(rootDir, [{}], "ses_1");
+    expect(resolved).toBe(rootDir);
+  });
+
+  it("creates and returns a per-session directory when the session has no entries", async () => {
+    const resolved = await resolveSessionWorkspaceRoot(rootDir, [], "ses_1");
+    expect(resolved).toBe(join(rootDir, "sessions", "ses_1"));
+    expect((await stat(resolved)).isDirectory()).toBe(true);
+  });
+
+  it("is deterministic across calls (stable across turns and retries)", async () => {
+    const first = await resolveSessionWorkspaceRoot(rootDir, [], "ses_1");
+    const second = await resolveSessionWorkspaceRoot(rootDir, [], "ses_1");
+    expect(second).toBe(first);
+  });
+
+  it("rejects an empty sessionId for a no-entry session", async () => {
+    // An empty id would collapse every no-entry session onto one directory —
+    // the exact cross-session leakage this helper exists to prevent.
+    await expect(resolveSessionWorkspaceRoot(rootDir, [], "")).rejects.toThrow(
+      /sessionId is required/,
+    );
+  });
+});

package/src/shared/workspace/__tests__/workspace-lock.test.ts

@@ -0,0 +1,200 @@
+/**
+ * Tests for the per-workspace turn lock (workspace-lock.ts).
+ *
+ * These run against the real proper-lockfile substrate on tmp directories —
+ * the lock's correctness IS its filesystem behavior, so mocking it would
+ * test nothing.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtemp, mkdir, readdir, rm, symlink, utimes } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  acquireWorkspaceLock,
+  WorkspaceLockTimeoutError,
+  WorkspaceLockCancelledError,
+} from "../workspace-lock.js";
+
+let baseDir: string;
+let workspaceDir: string;
+let lockDir: string;
+
+beforeEach(async () => {
+  baseDir = await mkdtemp(join(tmpdir(), "stigmer-workspace-lock-"));
+  workspaceDir = join(baseDir, "workspace");
+  lockDir = join(baseDir, "locks");
+  await mkdir(workspaceDir, { recursive: true });
+});
+
+afterEach(async () => {
+  await rm(baseDir, { recursive: true, force: true });
+});
+
+/** Resolves true once `promise` settles; used to assert "still pending". */
+function settled(promise: Promise<unknown>): { get: () => boolean } {
+  let done = false;
+  promise.then(() => { done = true; }, () => { done = true; });
+  return { get: () => done };
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+describe("acquireWorkspaceLock", () => {
+  it("serializes two concurrent acquires on the same workspace", async () => {
+    const release1 = await acquireWorkspaceLock(workspaceDir, { lockDir });
+
+    const second = acquireWorkspaceLock(workspaceDir, {
+      lockDir,
+      pollIntervalMs: 25,
+    });
+    const secondSettled = settled(second);
+
+    await sleep(120);
+    expect(secondSettled.get()).toBe(false);
+
+    await release1();
+    const release2 = await second;
+    expect(secondSettled.get()).toBe(true);
+    await release2();
+  });
+
+  it("converges symlink aliases of one directory onto one lock", async () => {
+    const alias = join(baseDir, "workspace-alias");
+    await symlink(workspaceDir, alias);
+
+    const release = await acquireWorkspaceLock(workspaceDir, { lockDir });
+    await expect(
+      acquireWorkspaceLock(alias, {
+        lockDir,
+        pollIntervalMs: 20,
+        timeoutMs: 100,
+      }),
+    ).rejects.toBeInstanceOf(WorkspaceLockTimeoutError);
+    await release();
+  });
+
+  it("does not contend across distinct workspaces", async () => {
+    const otherDir = join(baseDir, "other-workspace");
+    await mkdir(otherDir, { recursive: true });
+
+    const release1 = await acquireWorkspaceLock(workspaceDir, { lockDir });
+    const release2 = await acquireWorkspaceLock(otherDir, {
+      lockDir,
+      timeoutMs: 200,
+      pollIntervalMs: 20,
+    });
+    await release1();
+    await release2();
+  });
+
+  it("recovers a stale lock left by a crashed holder", async () => {
+    const release = await acquireWorkspaceLock(workspaceDir, {
+      lockDir,
+      staleMs: 5_000,
+    });
+    // Simulate a crashed holder: the artifact exists but its mtime refresh
+    // has stopped. Backdate it past the staleness bound.
+    const [artifact] = await readdir(lockDir);
+    const past = new Date(Date.now() - 60_000);
+    await utimes(join(lockDir, artifact), past, past);
+
+    const release2 = await acquireWorkspaceLock(workspaceDir, {
+      lockDir,
+      staleMs: 5_000,
+      timeoutMs: 2_000,
+      pollIntervalMs: 20,
+    });
+    await release2();
+    await release(); // original holder's release must not throw (idempotent wrapper)
+  });
+
+  it("times out with a typed, actionable error when the workspace stays busy", async () => {
+    const release = await acquireWorkspaceLock(workspaceDir, { lockDir });
+    const err = await acquireWorkspaceLock(workspaceDir, {
+      lockDir,
+      timeoutMs: 120,
+      pollIntervalMs: 25,
+    }).catch((e: unknown) => e);
+
+    expect(err).toBeInstanceOf(WorkspaceLockTimeoutError);
+    expect(String(err)).toContain("in use by another session");
+    await release();
+  });
+
+  it("aborts the wait immediately on cancellation", async () => {
+    const release = await acquireWorkspaceLock(workspaceDir, { lockDir });
+    const controller = new AbortController();
+
+    const waiting = acquireWorkspaceLock(workspaceDir, {
+      lockDir,
+      pollIntervalMs: 5_000, // long poll: proves abort wakes the sleep early
+      timeoutMs: 60_000,
+      signal: controller.signal,
+    });
+
+    await sleep(50);
+    const before = Date.now();
+    controller.abort();
+    await expect(waiting).rejects.toBeInstanceOf(WorkspaceLockCancelledError);
+    expect(Date.now() - before).toBeLessThan(1_000);
+    await release();
+  });
+
+  it("invokes onWaiting exactly once and heartbeats on every poll", async () => {
+    const release1 = await acquireWorkspaceLock(workspaceDir, { lockDir });
+
+    let waitingCalls = 0;
+    let heartbeats = 0;
+    const second = acquireWorkspaceLock(workspaceDir, {
+      lockDir,
+      pollIntervalMs: 25,
+      onWaiting: () => { waitingCalls += 1; },
+      heartbeat: () => { heartbeats += 1; },
+    });
+
+    // Deterministic under load: hold the lock until the waiter has provably
+    // polled at least twice, rather than sleeping a fixed wall-clock time.
+    while (heartbeats < 2) {
+      await sleep(20);
+    }
+    await release1();
+    const release2 = await second;
+
+    expect(waitingCalls).toBe(1);
+    expect(heartbeats).toBeGreaterThanOrEqual(2);
+    await release2();
+  });
+
+  it("never invokes onWaiting on an uncontended acquire", async () => {
+    let waitingCalls = 0;
+    const release = await acquireWorkspaceLock(workspaceDir, {
+      lockDir,
+      onWaiting: () => { waitingCalls += 1; },
+    });
+    expect(waitingCalls).toBe(0);
+    await release();
+  });
+
+  it("release is idempotent", async () => {
+    const release = await acquireWorkspaceLock(workspaceDir, { lockDir });
+    await release();
+    await expect(release()).resolves.toBeUndefined();
+    // Lock is actually free again.
+    const release2 = await acquireWorkspaceLock(workspaceDir, {
+      lockDir,
+      timeoutMs: 200,
+      pollIntervalMs: 20,
+    });
+    await release2();
+  });
+
+  it("keeps every lock artifact outside the workspace (issue #173)", async () => {
+    const release = await acquireWorkspaceLock(workspaceDir, { lockDir });
+    expect(await readdir(workspaceDir)).toEqual([]);
+    expect((await readdir(lockDir)).length).toBeGreaterThan(0);
+    await release();
+  });
+});

package/src/shared/workspace/session-root.ts

@@ -0,0 +1,60 @@
+/**
+ * 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: string,
+  workspaceEntries: readonly unknown[],
+  sessionId: string,
+): Promise<string> {
+  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;
+}