@stigmer/runner 3.1.2 → 3.1.4

package/src/shared/filereview/progress.ts

@@ -0,0 +1,310 @@
+/**
+ * Mid-run live capture — the harness-agnostic glue that turns a per-turn
+ * workspace delta into the transient `AgentExecutionStatus.file_change_progress`
+ * snapshot the "N files changed so far" strip renders (DD-32 / DD-33).
+ *
+ * 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.
+ *
+ * THE SUBSTRATE ABSTRACTION (DD-33)
+ * ---------------------------------
+ * Where the delta comes from differs by workspace: a git tree diffs cheaply with
+ * `git --numstat` (the git substrate), a non-git / gitignored workspace reads the
+ * CAS observer (the cas substrate, {@link ./cas-progress.js}), and a git tree
+ * with gitignored writes composes both (the hybrid substrate). A
+ * {@link ProgressSubstrate} hides that behind one `capture()` so the floor + attach
+ * logic below is written once. Each substrate is a per-turn object owning its own
+ * short-circuit cache; `capture()` always returns the FULL cumulative turn delta
+ * plus a `changed` flag, so the hybrid can merge both slices even when only one
+ * moved (a `ProgressDelta | undefined` would drop the unchanged slice).
+ *
+ * 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). The cas
+ * substrate additionally excludes gate-blocked secrets up front
+ * ({@link partitionIgnoredPathsBySecret}); this zeroing is the belt-and-suspenders
+ * backstop. Nothing new can leak through this field.
+ *
+ * @since File-Change HITL Redesign (mid-run live capture / DD-32; non-git + hybrid / DD-33)
+ */
+
+import { create } from "@bufbuild/protobuf";
+import type { AgentExecutionStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import type { FileChangeKind } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_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 GitProgressEntry,
+} from "./git-substrate.js";
+import { isSecretLikePath } from "./secret-paths.js";
+
+/**
+ * One file's slim, content-free progress row — the substrate-neutral input to
+ * {@link buildFileChangeProgress}. Carries the proto {@link FileChangeKind}
+ * directly (git and cas substrates both normalize to it), so no side re-maps.
+ * `linesAdded`/`linesRemoved` are 0 when uncountable (binary / oversized /
+ * secret-withheld).
+ */
+export interface ProgressEntry {
+  /** Path before the change (workspace-relative). Empty for ADD. */
+  readonly pathBefore: string;
+  /** Path after the change (workspace-relative). Empty for DELETE. */
+  readonly pathAfter: string;
+  readonly kind: FileChangeKind;
+  readonly linesAdded: number;
+  readonly linesRemoved: number;
+}
+
+/**
+ * The substrate-neutral progress delta the git/cas/hybrid substrates emit.
+ *
+ * `totalFilesChanged` is the honest count of changed files this turn, which may
+ * EXCEED `entries.length` when a substrate caps how many files it reads (the cas
+ * substrate reads only a bounded prefix — DD-33). Undefined means "the entries
+ * ARE every changed file" (the git substrate, whose numstat is free), so
+ * {@link buildFileChangeProgress} falls back to `entries.length`.
+ */
+export interface ProgressDelta {
+  readonly entries: readonly ProgressEntry[];
+  readonly totalFilesChanged?: number;
+}
+
+/** One mid-run capture: the FULL cumulative turn delta + whether it changed. */
+export interface ProgressCapture {
+  readonly delta: ProgressDelta;
+  /** False ⇒ nothing moved since the last capture; the caller skips re-attach. */
+  readonly changed: boolean;
+}
+
+/**
+ * A per-turn source of the mid-run delta. Implementations own their own
+ * short-circuit cache and ALWAYS return the full cumulative delta (never a
+ * bare "unchanged" sentinel), so {@link createHybridProgressSubstrate} can merge
+ * a changed slice with an unchanged one without losing the latter.
+ */
+export interface ProgressSubstrate {
+  capture(): Promise<ProgressCapture>;
+}
+
+/**
+ * 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. Also the cas substrate's read budget — it reads
+ * after-bytes for at most this many files per capture (DD-33).
+ */
+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 (git) or reads the touched set (cas), so
+ * we bound how often that runs regardless of persist frequency. Env-tunable for
+ * large-repo deployments; defaults to 2s (feels live without hammering the disk).
+ */
+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 substrate-neutral
+ * delta. Zeroes counts for secret-like paths (path visible, magnitude withheld),
+ * caps the entry list at {@link PROGRESS_MAX_ENTRIES}, and reports the honest
+ * `files_changed` (`delta.totalFilesChanged` when a substrate capped its reads,
+ * else the entry count). Aggregate counts sum over the emitted entries. Pure and
+ * exported for direct testing.
+ */
+export function buildFileChangeProgress(
+  delta: ProgressDelta,
+  changeSetId: string,
+): FileChangeProgress {
+  let totalAdded = 0;
+  let totalRemoved = 0;
+  const entries: FileChangeProgressEntry[] = [];
+
+  for (const entry of delta.entries) {
+    // 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: entry.kind,
+          linesAdded,
+          linesRemoved,
+        }),
+      );
+    }
+  }
+
+  return create(FileChangeProgressSchema, {
+    changeSetId,
+    filesChanged: delta.totalFilesChanged ?? delta.entries.length,
+    linesAdded: totalAdded,
+    linesRemoved: totalRemoved,
+    entries,
+    capturedAt: utcTimestamp(),
+  });
+}
+
+/**
+ * Mutable per-turn state the caller threads across persists: the last capture
+ * time (the floor). Substrate-specific short-circuit state (git tree sha, cas
+ * signature) lives inside the {@link ProgressSubstrate}, not here. A fresh turn
+ * starts a fresh state (`{ lastAtMs: 0 }`).
+ */
+export interface ProgressCaptureState {
+  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. Mutates `status` and `state` in place; a no-op when the
+ * floor has not elapsed or the substrate reports nothing changed. Content-free and
+ * secret-safe (see {@link buildFileChangeProgress}). Called by both harnesses from
+ * their per-persist loop, each passing a substrate built for its workspace shape.
+ *
+ * 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 changeSetId: string;
+  readonly substrate: ProgressSubstrate;
+  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, changed } = await opts.substrate.capture();
+  if (!changed) return;
+
+  opts.status.fileChangeProgress = buildFileChangeProgress(delta, opts.changeSetId);
+}
+
+// ---------------------------------------------------------------------------
+// Substrates
+// ---------------------------------------------------------------------------
+
+function gitEntryToProgressEntry(e: GitProgressEntry): ProgressEntry {
+  return {
+    pathBefore: e.pathBefore,
+    pathAfter: e.pathAfter,
+    kind: toFileChangeKind(e.changeType),
+    linesAdded: e.linesAdded,
+    linesRemoved: e.linesRemoved,
+  };
+}
+
+/**
+ * The git substrate: the working-tree `--numstat` delta against the pinned
+ * baseline. `git add -A` honors `.gitignore`, so this covers exactly the
+ * git-TRACKED changes (from any source — tool or shell), disjoint from the cas
+ * substrate's gitignored set. Preserves the tree-sha short-circuit: on an
+ * unchanged tree it returns the cached full delta with `changed:false` (the
+ * caller skips the re-attach), byte-identical to the pre-DD-33 behavior.
+ */
+export function createGitProgressSubstrate(opts: {
+  readonly workspaceRoot: string;
+  readonly executionId: string;
+  readonly baselineTree: string;
+  readonly excludePaths?: readonly string[];
+}): ProgressSubstrate {
+  let lastTreeSha: string | undefined;
+  let cachedFull: ProgressDelta = { entries: [] };
+  return {
+    async capture(): Promise<ProgressCapture> {
+      const gitDelta = await captureProgressDelta(
+        opts.workspaceRoot,
+        opts.executionId,
+        opts.baselineTree,
+        opts.excludePaths,
+        lastTreeSha,
+      );
+      if (gitDelta === undefined) {
+        // Working tree unchanged since the last capture — reuse the cache so the
+        // hybrid can still merge this (unchanged) slice with a changed cas slice.
+        return { delta: cachedFull, changed: false };
+      }
+      lastTreeSha = gitDelta.afterTree;
+      cachedFull = { entries: gitDelta.entries.map(gitEntryToProgressEntry) };
+      return { delta: cachedFull, changed: true };
+    },
+  };
+}
+
+/**
+ * The hybrid substrate: a git tree whose gitignored writes are captured via CAS.
+ * Concatenates both slices (disjoint by the `.gitignore` boundary — numstat sees
+ * only tracked paths, the observer only gitignored ones) and sums the honest
+ * totals. `changed` is true when EITHER slice moved; because each child returns
+ * its full cumulative delta, the merged delta always carries both slices.
+ */
+export function createHybridProgressSubstrate(
+  git: ProgressSubstrate,
+  cas: ProgressSubstrate,
+): ProgressSubstrate {
+  return {
+    async capture(): Promise<ProgressCapture> {
+      const [g, c] = await Promise.all([git.capture(), cas.capture()]);
+      const delta: ProgressDelta = {
+        entries: [...g.delta.entries, ...c.delta.entries],
+        totalFilesChanged:
+          (g.delta.totalFilesChanged ?? g.delta.entries.length) +
+          (c.delta.totalFilesChanged ?? c.delta.entries.length),
+      };
+      return { delta, changed: g.changed || c.changed };
+    },
+  };
+}

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

@@ -11,8 +11,9 @@
  * The directive has two variants, chosen by whether the approved plan document
  * actually materialized in the workspace:
  * - Attached (the normal case): the client uploaded the approved plan text
- *   (edited or not) and attached it, mounted at `.stigmer/inputs/plan.md`.
- *   The directive points the model at that file and names it authoritative —
+ *   (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
@@ -24,12 +25,37 @@
  * harness).
  */
 
-import { PLAN_ARTIFACT_NAME } from "./plan-artifact.js";
+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 canonical
- * plan filename — the same convention the UI uses to detect the plan artifact.
+ * 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.
@@ -37,9 +63,10 @@ import { PLAN_ARTIFACT_NAME } from "./plan-artifact.js";
 export function findApprovedPlanPath(
   attachmentPaths: readonly string[],
 ): string | undefined {
-  return attachmentPaths.find(
-    (p) => p.split("/").pop() === PLAN_ARTIFACT_NAME,
-  );
+  return attachmentPaths.find((p) => {
+    const name = p.split("/").pop();
+    return name !== undefined && isPlanArtifactName(name);
+  });
 }
 
 /**
@@ -61,6 +88,8 @@ export function buildImplementPlanDirective(planPath?: string): string {
       "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");
   }
 
@@ -69,5 +98,7 @@ export function buildImplementPlanDirective(planPath?: string): string {
       "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

@@ -3,8 +3,9 @@
  *
  * 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 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".
  *
@@ -25,8 +26,18 @@
 /**
  * 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.
+ * 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.
+ *
+ * Fence hygiene inside the document is part of the same contract. A plan
+ * frequently quotes file content that itself contains fenced code blocks
+ * ("insert this section into README.md"); with a same-length outer fence the
+ * inner block's closer terminates the outer fence early and corrupts the
+ * rendered document — on every client (the react SDK and the terminal
+ * renderer alike). And because the plan viewers render top-level ```mermaid
+ * fences as diagrams, the directive steers diagrams into the plan body proper
+ * rather than leaving them buried, unrendered, inside quoted file content.
  */
 export const PLAN_MODE_DIRECTIVE = [
   "IMPORTANT: You are in Plan mode — a read-only analysis turn whose " +
@@ -38,13 +49,25 @@ export const PLAN_MODE_DIRECTIVE = [
   "- 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:",
+    "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.",
+  "- When quoting content that itself contains fenced code blocks (e.g. a " +
+    "proposed file section with a code sample inside), open the outer fence " +
+    "with MORE backticks than any inner fence (four or more) — a same-length " +
+    "inner closer would terminate the outer fence early and corrupt the " +
+    "rendered document.",
+  "- Fenced ```mermaid blocks at the top level of the document render as " +
+    "diagrams in the plan viewer. When a diagram helps communicate the " +
+    "design (architecture, flows), include it directly in the plan body — " +
+    "not only inside quoted file content, where it stays unrendered source.",
   '- 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.",