@stigmer/runner 3.1.2 → 3.1.3

package/src/shared/filereview/cas-substrate.ts

@@ -57,6 +57,7 @@ import {
 import type { ArtifactStorage } from "../artifact-storage.js";
 import { bytesLookBinary } from "../file-change.js";
 import { sha256Bytes, sha256Hex } from "./digest.js";
+import { countLineChanges, type LineChangeCounts } from "./line-counts.js";
 
 /**
  * Reads an artifact's raw bytes back by storage key. Injected so this module
@@ -91,6 +92,14 @@ export interface CasCapturedFile {
   readonly after?: CasBlobRef;
   /** False when a side is binary — the change set cannot be approved as complete. */
   readonly diffComplete: boolean;
+  /**
+   * Display `+N −M` counted from the in-memory bytes at capture — the only
+   * moment a CAS change's text exists outside blob storage. Absent for binary
+   * or oversized sides. Carried in memory to the CANDIDATE event only, never
+   * persisted in the manifest: the manifest is the reconcile's source of truth,
+   * and display decoration does not belong in an enforcement record.
+   */
+  readonly lineCounts?: LineChangeCounts;
 }
 
 /** The durable manifest for one change set — the reconcile's source of truth. */
@@ -210,6 +219,7 @@ async function buildCasCapturedFile(
 
   const isCreate = kind === FileChangeKind.ADD;
   const isDelete = kind === FileChangeKind.DELETE;
+  const isBinary = beforeRef?.isBinary || afterRef?.isBinary;
 
   return {
     pathBefore: isCreate ? "" : path,
@@ -220,7 +230,13 @@ async function buildCasCapturedFile(
     after: afterRef,
     // Binary on either side means the diff cannot render as text; the change set
     // then cannot be approved as complete (parity with the git substrate).
-    diffComplete: !(beforeRef?.isBinary || afterRef?.isBinary),
+    diffComplete: !isBinary,
+    // Display counts are taken NOW, while the text bytes are still in memory —
+    // after this they exist only as offloaded blobs. A binary change has no
+    // line diff to count.
+    lineCounts: isBinary
+      ? undefined
+      : countLineChanges(beforeBuf?.toString("utf8"), afterBuf?.toString("utf8")),
   };
 }
 

package/src/shared/filereview/events.ts

@@ -42,6 +42,7 @@ import {
   FileReviewFailureKind,
 } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import { aggregateDigest, fileDigest, sha256Bytes } from "./digest.js";
+import { countLineChanges, type LineChangeCounts } from "./line-counts.js";
 import { looksBinary } from "../file-change.js";
 
 // The runner is the author of capture/reconcile/failure events. "runner" (not
@@ -150,6 +151,15 @@ export interface CapturedChangeInput {
    * this UNSPECIFIED. See {@link FileReviewBlockReason}.
    */
   readonly blockedReason?: FileReviewBlockReason;
+  /**
+   * Display line counts for this change, for producers whose bodies are not
+   * inline here (the CAS substrate counts from the in-memory bytes before
+   * offloading them as blob refs). Omit for inline content —
+   * {@link buildCapturedFileChange} then counts the inline sides itself, with
+   * the same shared {@link countLineChanges}. Informational only, never folded
+   * into the digests.
+   */
+  readonly lineCounts?: LineChangeCounts;
 }
 
 /** Normalize the string-shorthand to a {@link CapturedContent}. */
@@ -175,6 +185,37 @@ export function contentSha256(content: CapturedContent): string {
   }
 }
 
+/**
+ * Count the display `+N −M` from a change's inline sides, or `undefined` when
+ * counting is not honest here: a side that exists without inline text (a `ref`
+ * whose bytes were already offloaded, or a `binary` side with no body), or
+ * inline text that would render as binary (the UI shows "Binary file changed"
+ * for it, never a line diff — a count would describe a diff nobody sees).
+ * An absent side is fine — it is the empty document of an ADD/DELETE.
+ */
+function countInlineSides(
+  before: CapturedContent | undefined,
+  after: CapturedContent | undefined,
+): LineChangeCounts | undefined {
+  const beforeText = inlineTextOrNull(before);
+  const afterText = inlineTextOrNull(after);
+  if (beforeText === null || afterText === null) return undefined;
+  return countLineChanges(beforeText, afterText);
+}
+
+/**
+ * A side's countable inline text: the text for a non-binary inline side,
+ * `undefined` for an absent side (countable as the empty document), and `null`
+ * when the side exists but cannot be counted (ref / binary / binary-looking).
+ */
+function inlineTextOrNull(
+  content: CapturedContent | undefined,
+): string | undefined | null {
+  if (content === undefined) return undefined;
+  if (content.kind !== "inline" || looksBinary(content.text)) return null;
+  return content.text;
+}
+
 /** Build the proto {@link FileContent} for one content side (inline, ref, or binary). */
 function toFileContent(content: CapturedContent): FileContent {
   if (content.kind === "inline") {
@@ -212,12 +253,19 @@ function toFileContent(content: CapturedContent): FileContent {
  * `file_digest`) over the captured bytes. Content may be inline (git) or a blob
  * ref (CAS) — the digests are identical either way, so the aggregate digest and
  * the reconcile enforcement compose across both substrates.
+ *
+ * Display line counts are stamped here too — the single seam every substrate
+ * flows through — from `input.lineCounts` when the producer counted at its own
+ * source (CAS), else counted from the inline sides. Counting happens BEFORE any
+ * persist-time offload, so the counts survive a body being elided later. They
+ * never enter `fileDigest` (informational, not enforcement).
  */
 export function buildCapturedFileChange(input: CapturedChangeInput): CapturedFileChange {
   const before = normalizeContent(input.before);
   const after = normalizeContent(input.after);
   const beforeSha256 = before ? contentSha256(before) : "";
   const afterSha256 = after ? contentSha256(after) : "";
+  const counts = input.lineCounts ?? countInlineSides(before, after);
 
   const fc = create(CapturedFileChangeSchema, {
     id: input.id,
@@ -229,6 +277,8 @@ export function buildCapturedFileChange(input: CapturedChangeInput): CapturedFil
     afterSha256,
     diffComplete: input.diffComplete ?? true,
     blockedReason: input.blockedReason ?? FileReviewBlockReason.UNSPECIFIED,
+    linesAdded: counts?.linesAdded ?? 0,
+    linesRemoved: counts?.linesRemoved ?? 0,
     fileDigest: fileDigest({
       pathBefore: input.pathBefore,
       pathAfter: input.pathAfter,

package/src/shared/filereview/git-substrate.ts

@@ -308,6 +308,81 @@ export async function captureChangeSet(
   return { baselineTree, afterTree, changes };
 }
 
+/**
+ * One file's slim, content-free progress delta: paths + kind + line counts, NO
+ * bytes. The mid-run analogue of {@link GitSubstrateChange} (which carries the
+ * before/after {@link CapturedContent}); this deliberately carries neither side,
+ * so it can never leak content. `linesAdded`/`linesRemoved` are 0 when
+ * uncountable (a binary file — numstat reports `-`).
+ */
+export interface GitProgressEntry {
+  /** Path before the change (repo-relative). Empty for a CREATE. */
+  readonly pathBefore: string;
+  /** Path after the change (repo-relative). Empty for a DELETE. */
+  readonly pathAfter: string;
+  readonly changeType: FileChangeType;
+  readonly linesAdded: number;
+  readonly linesRemoved: number;
+}
+
+/** Result of {@link captureProgressDelta}. */
+export interface ProgressDelta {
+  /** The post-diff working-tree sha, for the caller's short-circuit cache. */
+  readonly afterTree: string;
+  /** One count-only entry per changed file (no content). */
+  readonly entries: readonly GitProgressEntry[];
+}
+
+/**
+ * Capture a NON-AUTHORITATIVE, content-free snapshot of the working-tree delta
+ * against `baselineTree` — the substrate for the live "N files changed so far"
+ * surface (mid-run live capture). Unlike {@link captureChangeSet} this reads NO
+ * file bytes: it stages the working tree into a temp index, writes its tree, and
+ * asks git for `--numstat` + `--name-status` only. Cheap enough to run on a
+ * debounce during the turn.
+ *
+ * Short-circuit: returns `undefined` when the working tree is unchanged since
+ * `lastTreeSha` (the caller passes back the previous result's `afterTree`), so a
+ * quiet turn pays only one `write-tree`, never a diff.
+ *
+ * Uses a dedicated temp-index label ("progress") so it never collides with the
+ * `baseline`/`capture`/`approved` indexes. `--no-renames` matches
+ * {@link captureChangeSet} (a rename surfaces as delete + create). A torn read of
+ * a file being written mid-turn is acceptable — the snapshot is non-authoritative
+ * and self-corrects on the next capture.
+ */
+export async function captureProgressDelta(
+  gitRoot: string,
+  executionId: string,
+  baselineTree: string,
+  excludePaths: readonly string[] = [],
+  lastTreeSha?: string,
+): Promise<ProgressDelta | undefined> {
+  const gitDir = await resolveGitDir(gitRoot);
+  const afterTree = await writeWorkingTree(gitRoot, gitDir, "progress", executionId, excludePaths);
+  if (lastTreeSha !== undefined && afterTree === lastTreeSha) return undefined;
+
+  const [nameStatusRaw, numstatRaw] = await Promise.all([
+    git(gitRoot, ["diff", "--no-renames", "--name-status", "-z", baselineTree, afterTree]),
+    git(gitRoot, ["diff", "--no-renames", "--numstat", "-z", baselineTree, afterTree]),
+  ]);
+
+  const counts = parseNumstatZ(numstatRaw);
+  const entries: GitProgressEntry[] = [];
+  for (const { status, path } of parseNameStatusZ(nameStatusRaw)) {
+    const changeType = nameStatusToChangeType(status);
+    const count = counts.get(path);
+    entries.push({
+      pathBefore: changeType === FileChangeType.CREATE ? "" : path,
+      pathAfter: changeType === FileChangeType.DELETE ? "" : path,
+      changeType,
+      linesAdded: count?.added ?? 0,
+      linesRemoved: count?.removed ?? 0,
+    });
+  }
+  return { afterTree, entries };
+}
+
 /**
  * Restore the given files to their `baselineTree` (pre-turn) bytes. On resume
  * this reverts the REJECTED/undecided subset so a discarded change snaps back
@@ -462,6 +537,39 @@ function parseNameStatusZ(raw: string): NameStatusEntry[] {
   return entries;
 }
 
+/**
+ * Parse `git diff --numstat -z` into a path -> {added, removed} map. Each record
+ * is a NUL-terminated `<added>\t<removed>\t<path>` triple; a binary file reports
+ * `-` for both counts, which we surface as 0 (no count) per the display contract.
+ */
+function parseNumstatZ(raw: string): Map<string, { added: number; removed: number }> {
+  const counts = new Map<string, { added: number; removed: number }>();
+  for (const record of raw.split("\u0000")) {
+    if (!record) continue;
+    const tab = record.indexOf("\t");
+    const tab2 = record.indexOf("\t", tab + 1);
+    if (tab < 0 || tab2 < 0) continue;
+    const addedStr = record.slice(0, tab);
+    const removedStr = record.slice(tab + 1, tab2);
+    const path = record.slice(tab2 + 1);
+    if (!path) continue;
+    const added = addedStr === "-" ? 0 : Number.parseInt(addedStr, 10) || 0;
+    const removed = removedStr === "-" ? 0 : Number.parseInt(removedStr, 10) || 0;
+    counts.set(path, { added, removed });
+  }
+  return counts;
+}
+
+/**
+ * Map a `--name-status` status letter to a {@link FileChangeType} — the same
+ * A -> CREATE, D -> DELETE, else MODIFY rule {@link buildCapturedChange} uses.
+ */
+function nameStatusToChangeType(status: string): FileChangeType {
+  if (status === "A") return FileChangeType.CREATE;
+  if (status === "D") return FileChangeType.DELETE;
+  return FileChangeType.MODIFY;
+}
+
 /** Read a blob's exact BYTES from a tree, or `undefined` when absent. */
 async function readBlobBytes(
   gitRoot: string,

package/src/shared/filereview/index.ts

@@ -33,7 +33,28 @@ export {
   type CaptureResumeResult,
 } from "./capture.js";
 
-export { isGitWorkTree } from "./git-substrate.js";
+export {
+  captureProgressDelta,
+  isGitWorkTree,
+  type GitProgressEntry,
+  type ProgressDelta,
+} from "./git-substrate.js";
+
+export {
+  buildFileChangeProgress,
+  captureFileChangeProgress,
+  newProgressCaptureState,
+  PROGRESS_CAPTURE_MIN_INTERVAL_MS,
+  PROGRESS_MAX_ENTRIES,
+  shouldCaptureProgress,
+  type ProgressCaptureState,
+} from "./progress.js";
+
+export {
+  countLineChanges,
+  LINE_COUNT_MAX_BYTES,
+  type LineChangeCounts,
+} from "./line-counts.js";
 
 export {
   applyCasApproved,

package/src/shared/filereview/line-counts.ts

@@ -0,0 +1,83 @@
+/**
+ * Capture-time line counting for the file-review subsystem: the `+N −M` stamped
+ * onto each {@link CapturedFileChange} so review surfaces can decorate file
+ * lists without the file bodies.
+ *
+ * WHY THE RUNNER COUNTS, AND WHY WITH JSDIFF. The counts exist because the
+ * review UI's compact file lists must show per-file magnitude, but by the time
+ * the UI renders, large before/after bodies may have been offloaded to artifact
+ * storage (status-offload) — a client cannot count what it would first have to
+ * download. So the counts are computed once, at capture, where the bytes are
+ * always in hand. They are computed with the SAME `diff` (jsdiff) Myers
+ * algorithm the SDK's diff renderer uses (`computeDiff` → `structuredPatch`),
+ * NOT with `git diff --numstat`: two counting authorities can disagree on edge
+ * cases (trailing newlines being the classic), and a list that says `+37 −1`
+ * beside a rendered diff showing `+37 −0` is a self-contradicting UI. One
+ * algorithm, consistent by construction.
+ *
+ * The counts are INFORMATIONAL display data only — never an enforcement input,
+ * never folded into `file_digest`/`aggregate_digest` (the same contract as
+ * `blocked_reason`).
+ */
+
+import { structuredPatch } from "diff";
+
+/**
+ * Per-side byte ceiling above which counting is skipped. Myers is O(ND) and a
+ * pathological many-MB text pair must never stall the capture activity just to
+ * decorate a list; above this the counts stay absent and the UI hides the stat.
+ * Generous relative to the 128 KiB per-side inline-persist cap — a file can be
+ * several times that and still count quickly — while bounding the worst case.
+ */
+export const LINE_COUNT_MAX_BYTES = 1024 * 1024;
+
+/** The `+N −M` pair for one file change. */
+export interface LineChangeCounts {
+  readonly linesAdded: number;
+  readonly linesRemoved: number;
+}
+
+/**
+ * Count the added/removed lines between two text sides, exactly as the SDK's
+ * diff renderer would show them.
+ *
+ * An absent side is the empty document — an ADD counts every `after` line as
+ * added, a DELETE every `before` line as removed — mirroring how the renderer
+ * diffs a create/delete. `` markers are metadata,
+ * not content, and are excluded (the same rule as the SDK's `mapPatchHunks`).
+ *
+ * Returns `undefined` when counting is not possible or meaningful: both sides
+ * absent, or either side over {@link LINE_COUNT_MAX_BYTES}. Callers leave the
+ * proto counts at zero in that case, which consumers render as "no stat".
+ */
+export function countLineChanges(
+  before: string | undefined,
+  after: string | undefined,
+): LineChangeCounts | undefined {
+  if (before === undefined && after === undefined) return undefined;
+  const beforeText = before ?? "";
+  const afterText = after ?? "";
+  if (
+    Buffer.byteLength(beforeText, "utf8") > LINE_COUNT_MAX_BYTES ||
+    Buffer.byteLength(afterText, "utf8") > LINE_COUNT_MAX_BYTES
+  ) {
+    return undefined;
+  }
+
+  // Zero context: the +/- line population is independent of context width, and
+  // omitting context lines keeps the walk (and the patch object) minimal.
+  const patch = structuredPatch("a", "b", beforeText, afterText, "", "", {
+    context: 0,
+  });
+
+  let linesAdded = 0;
+  let linesRemoved = 0;
+  for (const hunk of patch.hunks) {
+    for (const line of hunk.lines) {
+      if (line.startsWith("\\")) continue;
+      if (line[0] === "+") linesAdded++;
+      else if (line[0] === "-") linesRemoved++;
+    }
+  }
+  return { linesAdded, linesRemoved };
+}

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

@@ -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");
 }