@stigmer/runner 3.1.2 → 3.1.3

package/dist/shared/filereview/progress.js

@@ -0,0 +1,134 @@
+/**
+ * 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 { FileChangeProgressEntrySchema, FileChangeProgressSchema, } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/filereview_pb";
+import { utcTimestamp } from "../status.js";
+import { toFileChangeKind } from "./capture.js";
+import { captureProgressDelta } 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() {
+    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, nowMs, minIntervalMs = PROGRESS_CAPTURE_MIN_INTERVAL_MS) {
+    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, changeSetId) {
+    let filesChanged = 0;
+    let totalAdded = 0;
+    let totalRemoved = 0;
+    const entries = [];
+    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(),
+    });
+}
+/** A fresh per-turn progress state. */
+export function newProgressCaptureState() {
+    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) {
+    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);
+}
+//# sourceMappingURL=progress.js.map

package/dist/shared/filereview/progress.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress.js","sourceRoot":"","sources":["../../../src/shared/filereview/progress.ts"],"names":[],"mappings":"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"}

package/dist/shared/implement-plan-prompt.d.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
@@ -25,8 +26,9 @@
  */
 /**
  * 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.

package/dist/shared/implement-plan-prompt.js

@@ -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
@@ -23,17 +24,44 @@
  * framing (XML-tag section for Cursor, markdown heading for the native
  * 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.
  */
 export function findApprovedPlanPath(attachmentPaths) {
-    return attachmentPaths.find((p) => p.split("/").pop() === PLAN_ARTIFACT_NAME);
+    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.
@@ -54,6 +82,8 @@ export function buildImplementPlanDirective(planPath) {
             "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 [
@@ -61,6 +91,8 @@ export function buildImplementPlanDirective(planPath) {
             "APPROVED.",
         "",
         "Implement the plan proposed in the conversation above, step by step.",
+        "",
+        TRACK_PROGRESS_INSTRUCTION,
     ].join("\n");
 }
 //# sourceMappingURL=implement-plan-prompt.js.map

package/dist/shared/implement-plan-prompt.js.map

@@ -1 +1 @@
-{"version":3,"file":"implement-plan-prompt.js","sourceRoot":"","sources":["../../src/shared/implement-plan-prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAExD;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB,CAClC,eAAkC;IAElC,OAAO,eAAe,CAAC,IAAI,CACzB,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,KAAK,kBAAkB,CACjD,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,2BAA2B,CAAC,QAAiB;IAC3D,IAAI,QAAQ,EAAE,CAAC;QACb,OAAO;YACL,mEAAmE;gBACjE,WAAW;YACb,EAAE;YACF,+CAA+C,QAAQ,cAAc;gBACnE,wCAAwC;YAC1C,EAAE;YACF,wEAAwE;gBACtE,qEAAqE;gBACrE,0CAA0C;SAC7C,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACf,CAAC;IAED,OAAO;QACL,mEAAmE;YACjE,WAAW;QACb,EAAE;QACF,sEAAsE;KACvE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC"}
+{"version":3,"file":"implement-plan-prompt.js","sourceRoot":"","sources":["../../src/shared/implement-plan-prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAExD;;;;;;;;;;;;;;GAcG;AACH,MAAM,0BAA0B,GAAG;IACjC,sEAAsE;QACpE,QAAQ;IACV,2EAA2E;QACzE,2CAA2C;IAC7C,sEAAsE;QACpE,yCAAyC;CAC5C,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAEb;;;;;;;;GAQG;AACH,MAAM,UAAU,oBAAoB,CAClC,eAAkC;IAElC,OAAO,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE;QAChC,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC;QAChC,OAAO,IAAI,KAAK,SAAS,IAAI,kBAAkB,CAAC,IAAI,CAAC,CAAC;IACxD,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,2BAA2B,CAAC,QAAiB;IAC3D,IAAI,QAAQ,EAAE,CAAC;QACb,OAAO;YACL,mEAAmE;gBACjE,WAAW;YACb,EAAE;YACF,+CAA+C,QAAQ,cAAc;gBACnE,wCAAwC;YAC1C,EAAE;YACF,wEAAwE;gBACtE,qEAAqE;gBACrE,0CAA0C;YAC5C,EAAE;YACF,0BAA0B;SAC3B,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACf,CAAC;IAED,OAAO;QACL,mEAAmE;YACjE,WAAW;QACb,EAAE;QACF,sEAAsE;QACtE,EAAE;QACF,0BAA0B;KAC3B,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC"}

package/dist/shared/plan-artifact.d.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,19 +40,46 @@
  *
  * 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 type { AgentExecutionStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
 import type { ArtifactStorage } from "./artifact-storage.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 declare 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 declare const PLAN_ARTIFACT_SUFFIX = ".plan.md";
+/**
+ * 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 declare function isPlanArtifactName(name: string): boolean;
+/**
+ * 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 declare function planArtifactName(planText: string): string;
+/**
+ * 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 declare const PLAN_ARTIFACT_SANDBOX_PATH = ".stigmer/plans/plan.md";
+export declare function planArtifactSandboxPath(name: string): string;
 /**
  * Returns the text of the last AI message in a completed status, trimmed.
  * Returns `undefined` when there is no AI message with content — the plan was
@@ -41,9 +87,11 @@ export declare const PLAN_ARTIFACT_SANDBOX_PATH = ".stigmer/plans/plan.md";
  */
 export declare function extractFinalPlanText(status: AgentExecutionStatus): string | undefined;
 /**
- * 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.

package/dist/shared/plan-artifact.js

@@ -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,22 +40,128 @@
  *
  * 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";
 import { create } from "@bufbuild/protobuf";
 import { ExecutionArtifactSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/artifact_pb";
 import { ExecutionArtifactKind, MessageType, } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 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_SANDBOX_PATH = ".stigmer/plans/plan.md";
+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 function isPlanArtifactName(name) {
+    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) {
+    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) {
+    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) {
+    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) {
+    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) {
+    return `.stigmer/plans/${name}`;
+}
 /**
  * Returns the text of the last AI message in a completed status, trimmed.
  * Returns `undefined` when there is no AI message with content — the plan was
@@ -52,9 +177,11 @@ export function extractFinalPlanText(status) {
     return undefined;
 }
 /**
- * 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.
@@ -67,25 +194,26 @@ 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,
             createdAt: utcTimestamp(),
             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 {
             status.artifacts.push(artifact);
         }
-        console.log(`[plan-artifact] execution=${executionId} — published ${PLAN_ARTIFACT_NAME} ` +
+        console.log(`[plan-artifact] execution=${executionId} — published ${name} ` +
             `(${content.length} bytes, hash=${contentHash.slice(0, 12)})`);
     }
     catch (err) {

package/dist/shared/plan-artifact.js.map

@@ -1 +1 @@
-{"version":3,"file":"plan-artifact.js","sourceRoot":"","sources":["../../src/shared/plan-artifact.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"plan-artifact.js","sourceRoot":"","sources":["../../src/shared/plan-artifact.ts"],"names":[],"mappings":"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"}

package/dist/shared/plan-mode-prompt.d.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".
  *
@@ -24,7 +25,8 @@
 /**
  * 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.
  */
 export declare const PLAN_MODE_DIRECTIVE: string;