@stigmer/runner 3.1.1 → 3.1.3

package/src/shared/filereview/progress.ts

@@ -0,0 +1,186 @@
+/**
+ * Mid-run live capture — the harness-agnostic glue that turns a content-free git
+ * delta ({@link ./git-substrate.js} `captureProgressDelta`) into the transient
+ * `AgentExecutionStatus.file_change_progress` snapshot the "N files changed so
+ * far" strip renders (DD-32).
+ *
+ * THE MODEL
+ * ---------
+ * This is category 2 of the two status patterns: a runner-owned, latest-snapshot
+ * DISPLAY field, NOT the event-sourced file-review ledger. It is deliberately NOT
+ * a `FileChangeSet` — progress is never in the ledger, carries NO file bytes or
+ * digests, and is NEVER decidable. The turn-boundary CANDIDATE_CAPTURED (in
+ * `file_change_sets`) remains the single authoritative, reviewable diff; a mid-run
+ * snapshot is no more authoritative than a streamed tool-call arg.
+ *
+ * Both harnesses drive this through {@link captureFileChangeProgress} from their
+ * per-persist loop, each passing its OWN `excludePaths` (the runner-owned gate
+ * files it writes into the workspace), so progress and the turn-boundary candidate
+ * agree on what is "the agent's change". Capture is throttled by a floor +
+ * tree-sha short-circuit so a quiet turn is nearly free.
+ *
+ * SECRET SAFETY
+ * -------------
+ * No file bodies are ever carried. A secret-like path ({@link isSecretLikePath})
+ * is still surfaced (path visible) but with its line counts ZEROED — the same
+ * "path visible, content withheld" rule the ledger uses (DD-12). Nothing new can
+ * leak through this field.
+ *
+ * @since File-Change HITL Redesign (mid-run live capture / DD-32)
+ */
+
+import { create } from "@bufbuild/protobuf";
+import type { AgentExecutionStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import type {
+  FileChangeProgress,
+  FileChangeProgressEntry,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/filereview_pb";
+import {
+  FileChangeProgressEntrySchema,
+  FileChangeProgressSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/filereview_pb";
+import { utcTimestamp } from "../status.js";
+import { toFileChangeKind } from "./capture.js";
+import { captureProgressDelta, type ProgressDelta } from "./git-substrate.js";
+import { isSecretLikePath } from "./secret-paths.js";
+
+/**
+ * Cap the per-file entry list so a turn touching thousands of files does not
+ * bloat the persisted status (which rides Temporal / the store). `files_changed`
+ * and the aggregate counts stay honest over ALL files; the strip shows "… and K
+ * more" when the list is capped.
+ */
+export const PROGRESS_MAX_ENTRIES = 200;
+
+/**
+ * Minimum wall-clock gap between two mid-run captures, in ms. A floor on cost:
+ * every capture stages the working tree (`write-tree`), so we bound how often
+ * that runs regardless of persist frequency. Env-tunable for large-repo
+ * deployments; defaults to 2s (feels live without hammering git).
+ */
+export const PROGRESS_CAPTURE_MIN_INTERVAL_MS = readMinIntervalMs();
+
+function readMinIntervalMs(): number {
+  const raw = process.env.STIGMER_PROGRESS_CAPTURE_MIN_INTERVAL_MS;
+  if (!raw) return 2000;
+  const n = Number.parseInt(raw, 10);
+  return Number.isFinite(n) && n >= 0 ? n : 2000;
+}
+
+/**
+ * Whether enough wall-clock has elapsed since the last capture to take another.
+ * Pure and separated for direct testing (mirrors `persist-decision.ts`). A
+ * `lastAtMs` of 0 (never captured) always passes.
+ */
+export function shouldCaptureProgress(
+  lastAtMs: number,
+  nowMs: number,
+  minIntervalMs: number = PROGRESS_CAPTURE_MIN_INTERVAL_MS,
+): boolean {
+  return nowMs - lastAtMs >= minIntervalMs;
+}
+
+/**
+ * Build the transient {@link FileChangeProgress} message from a content-free git
+ * delta. Zeroes counts for secret-like paths (path visible, magnitude withheld),
+ * caps the entry list at {@link PROGRESS_MAX_ENTRIES} while keeping
+ * `files_changed`/aggregate counts honest over every file, and stamps
+ * `captured_at`. Pure and exported for direct testing.
+ */
+export function buildFileChangeProgress(
+  delta: ProgressDelta,
+  changeSetId: string,
+): FileChangeProgress {
+  let filesChanged = 0;
+  let totalAdded = 0;
+  let totalRemoved = 0;
+  const entries: FileChangeProgressEntry[] = [];
+
+  for (const entry of delta.entries) {
+    filesChanged += 1;
+    // A secret-like path is surfaced (path visible) but its magnitude is withheld
+    // — counts zeroed, mirroring the ledger's "path visible, content withheld".
+    const secret = isSecretLikePath(entry.pathAfter || entry.pathBefore);
+    const linesAdded = secret ? 0 : entry.linesAdded;
+    const linesRemoved = secret ? 0 : entry.linesRemoved;
+    totalAdded += linesAdded;
+    totalRemoved += linesRemoved;
+
+    if (entries.length < PROGRESS_MAX_ENTRIES) {
+      entries.push(
+        create(FileChangeProgressEntrySchema, {
+          pathBefore: entry.pathBefore,
+          pathAfter: entry.pathAfter,
+          kind: toFileChangeKind(entry.changeType),
+          linesAdded,
+          linesRemoved,
+        }),
+      );
+    }
+  }
+
+  return create(FileChangeProgressSchema, {
+    changeSetId,
+    filesChanged,
+    linesAdded: totalAdded,
+    linesRemoved: totalRemoved,
+    entries,
+    capturedAt: utcTimestamp(),
+  });
+}
+
+/**
+ * Mutable per-turn state the caller threads across persists: the last captured
+ * tree sha (for the short-circuit) and the last capture time (for the floor).
+ * A fresh turn starts a fresh state (`{ lastAtMs: 0 }`).
+ */
+export interface ProgressCaptureState {
+  lastTreeSha?: string;
+  lastAtMs: number;
+}
+
+/** A fresh per-turn progress state. */
+export function newProgressCaptureState(): ProgressCaptureState {
+  return { lastAtMs: 0 };
+}
+
+/**
+ * Capture-and-attach the live progress snapshot onto `status.file_change_progress`,
+ * throttled by the floor + tree-sha short-circuit. Mutates `status` and `state`
+ * in place; a no-op when the floor has not elapsed or the working tree is
+ * unchanged since the last capture. Content-free and secret-safe (see
+ * {@link buildFileChangeProgress}). Called by both harnesses from their per-persist
+ * loop; each passes its own `excludePaths`.
+ *
+ * The field is set even when the delta is now EMPTY (the agent reverted its own
+ * edits) so the strip reflects the reversion (it hides at zero) rather than
+ * showing a stale count — the server's presence-guarded merge would keep the
+ * stale value if the runner omitted the field.
+ */
+export async function captureFileChangeProgress(opts: {
+  readonly status: AgentExecutionStatus;
+  readonly gitRoot: string;
+  readonly executionId: string;
+  readonly changeSetId: string;
+  readonly baselineTree: string;
+  readonly excludePaths?: readonly string[];
+  readonly state: ProgressCaptureState;
+  /** Injectable clock for tests; defaults to `Date.now()`. */
+  readonly nowMs?: number;
+}): Promise<void> {
+  const now = opts.nowMs ?? Date.now();
+  if (!shouldCaptureProgress(opts.state.lastAtMs, now)) return;
+  opts.state.lastAtMs = now;
+
+  const delta = await captureProgressDelta(
+    opts.gitRoot,
+    opts.executionId,
+    opts.baselineTree,
+    opts.excludePaths,
+    opts.state.lastTreeSha,
+  );
+  if (!delta) return; // working tree unchanged since the last capture
+
+  opts.state.lastTreeSha = delta.afterTree;
+  opts.status.fileChangeProgress = buildFileChangeProgress(delta, opts.changeSetId);
+}

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

@@ -0,0 +1,104 @@
+/**
+ * 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 under `.stigmer/inputs/` as the
+ *   plan's own file (`<slug>_<id>.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 { isPlanArtifactName } from "./plan-artifact.js";
+
+/**
+ * Progress-tracking instruction shared by both directive variants (Tier 3 of
+ * Plan mode — plan-driven build progress). The agent's own to-do tool is the
+ * single writer of `status.todos`, so instructing it to derive the list from
+ * the approved plan is the entire plan→progress linkage: the runner's todo
+ * extraction and the clients' todo renderers light up unchanged.
+ *
+ * Deliberately tool-agnostic ("your to-do list"): the Cursor harness exposes
+ * TodoWrite/updateTodos, the native harness write_todos, and each runtime
+ * already teaches the model its own tool.
+ *
+ * Wording constraint: this block rides BOTH variants, and the conversation-only
+ * variant is pinned by tests to never contain "plan.md" (it has no plan file
+ * to reference) — so say "the plan", never name the file.
+ */
+const TRACK_PROGRESS_INSTRUCTION = [
+  "Track your progress with your to-do list so the user can follow the " +
+    "build:",
+  "- Before you start, break the plan into a concrete, ordered to-do list — " +
+    "roughly one item per implementation step.",
+  "- As you work, keep it current: mark each item in progress when you " +
+    "begin it and completed when it is done.",
+].join("\n");
+
+/**
+ * Find the approved plan document among the workspace paths the harness
+ * injected for this execution's attachments. Detection keys on the plan
+ * filename convention ({@link isPlanArtifactName} — the legacy `plan.md` or any
+ * `*.plan.md`), 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) => {
+    const name = p.split("/").pop();
+    return name !== undefined && isPlanArtifactName(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.",
+      "",
+      TRACK_PROGRESS_INSTRUCTION,
+    ].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.",
+    "",
+    TRACK_PROGRESS_INSTRUCTION,
+  ].join("\n");
+}

package/src/shared/plan-artifact.ts

@@ -2,11 +2,30 @@
  * Plan-mode artifact publishing.
  *
  * When an execution runs in Plan mode (InteractionMode.PLAN), the agent's final
- * message IS the plan. We publish that text as a first-class `plan.md`
+ * message IS the plan. We publish that text as a first-class plan markdown
  * ExecutionArtifact so the UI can render a reviewable Plan card with
  * copy/download, and a follow-up "Implement" execution can reference it
  * deterministically.
  *
+ * The artifact is named from the plan's own title — a hyphenated slug of its
+ * leading `# H1`, a `_<hash>` discriminator, and a `.plan.md` suffix (e.g.
+ * `plan-card-ux-cleanup_a1b2c3d4.plan.md`), so a downloaded plan lands as a
+ * recognizable file and the card, plan tab, and saved file all agree on one
+ * name. A plan with no derivable title falls back to a bare `<hash>.plan.md`.
+ *
+ * The `_<hash>` discriminator (first 8 hex of the plan content's SHA-256) is
+ * NOT for storage uniqueness — storage keys are already execution-scoped
+ * (`artifacts/{execId}/<name>`). It exists because the artifact BASENAME is a
+ * user-facing shared namespace: downloads save under it (see the artifact
+ * download disposition) and the artifact list surfaces it, so two same-titled
+ * plans would otherwise collide in the user's Downloads folder and read
+ * identically in the list. Deriving it from content (not a random or
+ * execution-scoped value) keeps naming honestly idempotent — identical content
+ * yields an identical name, so a finalize retry re-uploads to the same key,
+ * while any real edit yields a distinct one. This refines DD-23 §D3 ("no
+ * uniqueness hash"), which was correct about storage but overlooked the
+ * download/list basename namespace introduced by DD-23 §D1.
+ *
  * This is deliberately a single, harness-agnostic helper:
  * - The native (deepagents) harness already auto-publishes files an agent
  *   writes (InlinePublisher), but Plan mode is read-only, so there is no file to
@@ -21,8 +40,8 @@
  *
  * The plan content is NOT duplicated as a separate stored blob beyond this
  * artifact — the chat message remains the live/streamed view; the artifact is
- * the durable/exportable view, detected by convention (a FILE artifact named
- * `plan.md`).
+ * the durable/exportable view, detected by convention (a FILE artifact whose
+ * name satisfies {@link isPlanArtifactName}).
  */
 
 import { createHash } from "node:crypto";
@@ -36,15 +55,129 @@ import {
 import type { ArtifactStorage } from "./artifact-storage.js";
 import { utcTimestamp } from "./status.js";
 
-/** Canonical filename for a plan artifact. UI detection keys on this name. */
+/**
+ * Legacy plan filename. Detection-only: {@link isPlanArtifactName} still
+ * accepts this exact name so plans published before named artifacts existed
+ * keep working. It is NEVER freshly emitted — a titleless plan now falls back
+ * to a bare `<hash>.plan.md` (see {@link planArtifactName}).
+ */
 export const PLAN_ARTIFACT_NAME = "plan.md";
 
 /**
- * Sandbox path recorded on the artifact. Routes under `.stigmer/` (the
- * session platform dir), so it never pollutes the user's workspace, and a
- * follow-up execution can reference it via workspace file refs if desired.
+ * Suffix every named plan artifact carries. The UI keys plan detection on this
+ * suffix, so it must stay in sync with the SDK's `PLAN_ARTIFACT_SUFFIX`
+ * (`sdk/react/src/library/detect-plan-artifact.ts`). The two cannot share a
+ * module — the runner and the browser SDK have disjoint module graphs — so the
+ * constant is duplicated by design, mirroring {@link PLAN_ARTIFACT_NAME}.
+ */
+export const PLAN_ARTIFACT_SUFFIX = ".plan.md";
+
+/** Longest slug we derive from a plan title before the `_<id>.plan.md` tail. */
+const MAX_PLAN_SLUG_LENGTH = 60;
+
+/** Hex length of the content-hash discriminator appended to named plans. */
+const PLAN_ID_LENGTH = 8;
+
+/**
+ * Reports whether an artifact filename is a plan: the legacy exact name, or any
+ * `*.plan.md`. Kept in sync with the SDK's `isPlanArtifactName`.
  */
-export const PLAN_ARTIFACT_SANDBOX_PATH = ".stigmer/plans/plan.md";
+export function isPlanArtifactName(name: string): boolean {
+  return name === PLAN_ARTIFACT_NAME || name.endsWith(PLAN_ARTIFACT_SUFFIX);
+}
+
+// Plan-title extraction, mirrored from the SDK so the runner's derived filename
+// and the card's displayed title agree on one title from one source (the plan's
+// leading `# H1`). These three patterns are a verbatim copy of
+// `sdk/react/src/internal/markdown-components.tsx`
+// (`ENCLOSING_MARKDOWN_FENCE_RE`, `ENCLOSING_BARE_FENCE_RE`, `LEADING_H1_RE`)
+// and MUST stay in sync with it — a fence-wrapped plan whose title the card
+// unwraps must slug to that same title here, never to the fallback.
+const ENCLOSING_MARKDOWN_FENCE_RE =
+  /^(`{3,})[ \t]*(?:markdown|md)[ \t]*\r?\n([\s\S]*?)\r?\n\1[ \t]*$/i;
+const ENCLOSING_BARE_FENCE_RE = /^(`{3,})[ \t]*\r?\n([\s\S]*?)\r?\n\1[ \t]*$/;
+const LEADING_H1_RE = /^#[ \t]+(.+?)[ \t]*(?:\r?\n+|$)/;
+
+/**
+ * The plan's title: the leading `# H1` of the plan text, after the same
+ * plan-scoped enclosing-fence unwrap (tagged ```markdown``` or a bare ``` `)
+ * the document renderers apply. `undefined` when the plan has no leading H1.
+ */
+function extractPlanTitle(planText: string): string | undefined {
+  const trimmed = planText.trim();
+  let body = trimmed;
+  const tagged = ENCLOSING_MARKDOWN_FENCE_RE.exec(trimmed);
+  if (tagged) {
+    body = tagged[2];
+  } else {
+    const bare = ENCLOSING_BARE_FENCE_RE.exec(trimmed);
+    if (bare) body = bare[2];
+  }
+  const h1 = LEADING_H1_RE.exec(body.trim());
+  return h1 ? h1[1] : undefined;
+}
+
+/**
+ * Strips a leading "Plan" LABEL from a title, e.g. `Plan: Create X` -> `Create
+ * X`. The separator (`:` or a dash) is REQUIRED: this removes a redundant label
+ * (a plan document already announces itself via the `.plan.md` suffix and the
+ * Plan card framing) without ever clipping a real title word — a bare `\bplan\b`
+ * would wrongly turn "Plan card UX cleanup" into "card UX cleanup".
+ *
+ * Deliberately runner/filename-only and NOT mirrored into the SDK's title
+ * extraction: display surfaces render the message's own `# H1` faithfully
+ * (`extractLeadingH1` is general-purpose and render-time-only), so the clean
+ * title is fixed at the source — the plan-mode prompt tells the model not to
+ * prefix titles with "Plan:". This strip is the durable-artifact safety net for
+ * when the model (or the enforcement-less Cursor harness) drifts.
+ */
+function stripPlanLabel(title: string): string {
+  return title.replace(/^plan\s*[:\u2013\u2014-]\s*/i, "");
+}
+
+/**
+ * Slugifies a plan title into a filename-safe stem: lowercase, every run of
+ * non-alphanumerics collapsed to `-`, trimmed of leading/trailing `-`, and
+ * capped at {@link MAX_PLAN_SLUG_LENGTH}. Returns `""` for a title with no
+ * alphanumerics (e.g. only punctuation), which selects the fallback name.
+ */
+function slugifyPlanTitle(title: string): string {
+  return title
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, MAX_PLAN_SLUG_LENGTH)
+    .replace(/-+$/g, "");
+}
+
+/**
+ * Derives the plan artifact's filename from its text: `<slug>_<id>.plan.md`
+ * when the plan opens with a titled `# H1`, else a bare `<id>.plan.md`. The
+ * `<id>` is the first {@link PLAN_ID_LENGTH} hex of the content's SHA-256 — a
+ * user-facing discriminator for the shared download/list basename namespace,
+ * not a storage-uniqueness device (see the module doc).
+ */
+export function planArtifactName(planText: string): string {
+  const id = createHash("sha256")
+    .update(planText, "utf-8")
+    .digest("hex")
+    .slice(0, PLAN_ID_LENGTH);
+  const title = extractPlanTitle(planText);
+  const slug = title ? slugifyPlanTitle(stripPlanLabel(title)) : "";
+  return slug.length > 0
+    ? `${slug}_${id}${PLAN_ARTIFACT_SUFFIX}`
+    : `${id}${PLAN_ARTIFACT_SUFFIX}`;
+}
+
+/**
+ * Sandbox path recorded on the artifact for a given filename. Routes under
+ * `.stigmer/` (the session platform dir), so it never pollutes the user's
+ * workspace, and a follow-up execution can reference it via workspace file
+ * refs if desired.
+ */
+export function planArtifactSandboxPath(name: string): string {
+  return `.stigmer/plans/${name}`;
+}
 
 /**
  * Returns the text of the last AI message in a completed status, trimmed.
@@ -62,9 +195,11 @@ export function extractFinalPlanText(status: AgentExecutionStatus): string | und
 }
 
 /**
- * Publishes `planText` as a `plan.md` ExecutionArtifact and registers it on
- * `status.artifacts`. Idempotent: re-publishing replaces any existing `plan.md`
- * rather than appending a duplicate, preserving a single source of truth.
+ * Publishes `planText` as a plan ExecutionArtifact (named from its title —
+ * see {@link planArtifactName}) and registers it on `status.artifacts`.
+ * Idempotent: re-publishing replaces any existing plan artifact — matched by
+ * {@link isPlanArtifactName}, not exact name, so a re-plan whose title changed
+ * still supersedes rather than appends — preserving a single source of truth.
  *
  * Fire-and-forget by contract: a plan that fails to upload must never fail the
  * execution. Errors are logged and swallowed.
@@ -84,13 +219,14 @@ export async function publishPlanArtifact(opts: {
   try {
     const content = Buffer.from(planText, "utf-8");
     const contentHash = createHash("sha256").update(content).digest("hex");
-    const storageKey = `artifacts/${executionId}/${PLAN_ARTIFACT_NAME}`;
+    const name = planArtifactName(planText);
+    const storageKey = `artifacts/${executionId}/${name}`;
 
     await artifactStorage.upload(storageKey, content, "text/markdown");
 
     const artifact = create(ExecutionArtifactSchema, {
-      name: PLAN_ARTIFACT_NAME,
-      sandboxPath: PLAN_ARTIFACT_SANDBOX_PATH,
+      name,
+      sandboxPath: planArtifactSandboxPath(name),
       kind: ExecutionArtifactKind.FILE,
       sizeBytes: BigInt(content.length),
       storageKey,
@@ -98,7 +234,7 @@ export async function publishPlanArtifact(opts: {
       contentHash,
     });
 
-    const existingIdx = status.artifacts.findIndex((a) => a.name === PLAN_ARTIFACT_NAME);
+    const existingIdx = status.artifacts.findIndex((a) => isPlanArtifactName(a.name));
     if (existingIdx >= 0) {
       status.artifacts[existingIdx] = artifact;
     } else {
@@ -106,7 +242,7 @@ export async function publishPlanArtifact(opts: {
     }
 
     console.log(
-      `[plan-artifact] execution=${executionId} — published ${PLAN_ARTIFACT_NAME} ` +
+      `[plan-artifact] execution=${executionId} — published ${name} ` +
       `(${content.length} bytes, hash=${contentHash.slice(0, 12)})`,
     );
   } catch (err) {

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

@@ -0,0 +1,56 @@
+/**
+ * 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 markdown
+ *   artifact, named from the plan's title (`plan-artifact.ts` —
+ *   `extractFinalPlanText`, `planArtifactName`),
+ * - 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 a plan document (whose filename is derived
+ * from the leading `#` title), 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 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.",
+  '- Give the `#` title a concise, descriptive name for the work itself; do ' +
+    'NOT prefix it with "Plan:" (this document is already a plan — the ' +
+    "prefix is redundant and leaks into the plan's filename).",
+  "- 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);