@stigmer/runner 3.1.2 → 3.1.3

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

@@ -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,8 +25,9 @@
 /**
  * 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 const PLAN_MODE_DIRECTIVE = [
     "IMPORTANT: You are in Plan mode — a read-only analysis turn whose " +
@@ -37,10 +39,13 @@ 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.",

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

@@ -1 +1 @@
-{"version":3,"file":"plan-mode-prompt.js","sourceRoot":"","sources":["../../src/shared/plan-mode-prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,oEAAoE;QAClE,wCAAwC;IAC1C,EAAE;IACF,cAAc;IACd,6CAA6C;IAC7C,yEAAyE;IACzE,mCAAmC;IACnC,EAAE;IACF,yEAAyE;QACvE,oEAAoE;IACtE,0EAA0E;QACxE,wEAAwE;QACxE,+CAA+C;IACjD,oEAAoE;QAClE,mBAAmB;IACrB,6CAA6C;IAC7C,uEAAuE;QACrE,uEAAuE;QACvE,kDAAkD;CACrD,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC"}
+{"version":3,"file":"plan-mode-prompt.js","sourceRoot":"","sources":["../../src/shared/plan-mode-prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,oEAAoE;QAClE,wCAAwC;IAC1C,EAAE;IACF,cAAc;IACd,6CAA6C;IAC7C,yEAAyE;IACzE,mCAAmC;IACnC,EAAE;IACF,yEAAyE;QACvE,+DAA+D;IACjE,0EAA0E;QACxE,wEAAwE;QACxE,+CAA+C;IACjD,2EAA2E;QACzE,oEAAoE;QACpE,0DAA0D;IAC5D,oEAAoE;QAClE,mBAAmB;IACrB,6CAA6C;IAC7C,uEAAuE;QACrE,uEAAuE;QACvE,kDAAkD;CACrD,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stigmer/runner",
-  "version": "3.1.2",
+  "version": "3.1.3",
   "description": "Embeddable Temporal worker for the Stigmer AI agent platform — handles agent execution, workflow orchestration, and MCP server management",
   "license": "Apache-2.0",
   "type": "module",
@@ -85,7 +85,7 @@
     "@opentelemetry/sdk-metrics": "^2.0.0",
     "@opentelemetry/sdk-trace-base": "^2.0.0",
     "@opentelemetry/sdk-trace-node": "^2.0.0",
-    "@stigmer/protos": "3.1.2",
+    "@stigmer/protos": "3.1.3",
     "@temporalio/activity": "^1.11.0",
     "@temporalio/client": "^1.11.0",
     "@temporalio/common": "^1.11.0",
@@ -93,6 +93,7 @@
     "@temporalio/worker": "^1.11.0",
     "@temporalio/workflow": "^1.16.2",
     "deepagents": "^1.10.0",
+    "diff": "^8.0.4",
     "jq-wasm": "^1.1.0-jq-1.8.1",
     "js-yaml": "^4.1.1",
     "proper-lockfile": "^4.1.2",

package/src/activities/execute-cursor/__tests__/build-prompt.test.ts

@@ -332,6 +332,13 @@ describe("formatImplementPlanSection", () => {
     expect(formatImplementPlanSection(undefined, [PLAN_PATH])).toBeUndefined();
   });
 
+  it("carries the plan-derived progress-tracking instruction (Tier 3)", () => {
+    const section = formatImplementPlanSection(true, [PLAN_PATH]);
+
+    expect(section).toContain("to-do list");
+    expect(section).toContain("break the plan into");
+  });
+
   it("injects the directive into a build-from-plan first prompt", () => {
     const prompt = buildPrompt(
       input({

package/src/activities/execute-cursor/__tests__/delta-enricher.test.ts

@@ -240,3 +240,71 @@ describe("DeltaEnricher finalize reconciliation", () => {
     expect(messages[1].toolCalls[0].status).toBe(ToolCallStatus.TOOL_CALL_COMPLETED);
   });
 });
+
+describe("DeltaEnricher recovery-retry stream epilogue", () => {
+  // Regression for the zombie RUNNING row of aex_01kws27q1e2esvkqjpvectttxf:
+  // the recovery retry's bare stream loop buffered the tool-call-completed
+  // delta but never flushed it, so the row lacked the completedAt evidence
+  // finalize's sweep requires and persisted as RUNNING forever. The epilogue
+  // must applyEnrichments (flush the buffered evidence) BEFORE finalize.
+  it("applyEnrichments + finalize promotes a retry's buffered-completion RUNNING row", () => {
+    vi.spyOn(console, "log").mockImplementation(() => {});
+
+    const enricher = new DeltaEnricher();
+    const messages: AgentMessage[] = [
+      makeMessage([{ id: "tc-retry", name: "Shell", status: ToolCallStatus.TOOL_CALL_RUNNING }]),
+    ];
+
+    // The retry's onDelta buffered the completion, but the bare retry loop
+    // never applied it to the transcript.
+    enricher.processDelta({
+      type: "tool-call-completed",
+      callId: "tc-retry",
+      toolCall: { type: "shell" },
+    } as unknown as InteractionUpdate);
+
+    // Without the flush, finalize alone cannot promote (no evidence on the row).
+    const unflushed = makeMessage([
+      { id: "tc-retry", name: "Shell", status: ToolCallStatus.TOOL_CALL_RUNNING },
+    ]);
+    new DeltaEnricher().finalize([unflushed]);
+    expect(unflushed.toolCalls[0].status).toBe(ToolCallStatus.TOOL_CALL_RUNNING);
+
+    // The epilogue sequence: flush the buffered evidence, then finalize.
+    enricher.applyEnrichments(messages);
+    enricher.finalize(messages);
+
+    const tc = messages[0].toolCalls[0];
+    expect(tc.status).toBe(ToolCallStatus.TOOL_CALL_COMPLETED);
+    expect(tc.completedAt).toBeTruthy();
+  });
+
+  it("re-running applyEnrichments and finalize is idempotent", () => {
+    vi.spyOn(console, "log").mockImplementation(() => {});
+
+    const enricher = new DeltaEnricher();
+    const messages: AgentMessage[] = [
+      makeMessage([{ id: "tc-1", name: "Shell", status: ToolCallStatus.TOOL_CALL_RUNNING }]),
+    ];
+
+    enricher.processDelta({
+      type: "tool-call-completed",
+      callId: "tc-1",
+      toolCall: { type: "shell" },
+    } as unknown as InteractionUpdate);
+
+    // Primary epilogue ...
+    enricher.applyEnrichments(messages);
+    enricher.finalize(messages);
+    const stamped = messages[0].toolCalls[0].completedAt;
+
+    // ... and the retry epilogue re-runs both. The row must keep its original
+    // completion evidence and terminal status.
+    enricher.applyEnrichments(messages);
+    enricher.finalize(messages);
+
+    const tc = messages[0].toolCalls[0];
+    expect(tc.status).toBe(ToolCallStatus.TOOL_CALL_COMPLETED);
+    expect(tc.completedAt).toBe(stamped);
+  });
+});

package/src/activities/execute-cursor/__tests__/turn-boundary.test.ts

@@ -0,0 +1,280 @@
+/**
+ * Tests for the extracted turn boundary (turn-boundary.ts) — the post-run
+ * pipeline shared by the primary path and the recovery retries.
+ *
+ * The load-bearing scenario is the recovery-retry sequence that motivated the
+ * extraction (production case aex_01kws27q1e2esvkqjpvectttxf): the primary
+ * boundary runs against an untouched tree (the resumed agent errored before
+ * doing anything), the retry agent then edits files, and the boundary is
+ * re-entered — the candidate must be authored exactly once and the turn must
+ * pause for review. Runs against a REAL temp git repo with in-memory
+ * transcript + status protos, mirroring capture-flow.test.ts.
+ */
+
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { execFile } from "node:child_process";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { create } from "@bufbuild/protobuf";
+import {
+  AgentMessageSchema,
+  ToolCallSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import type { AgentMessage } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import { AgentExecutionStatusSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import type { AgentExecutionStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import {
+  FileReviewEventType,
+  MessageType,
+  ToolCallStatus,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { captureBaselineToLedger } from "../capture-flow.js";
+import { denialLedgerPath } from "../approval-state.js";
+import { toolCallIdentityToken } from "../message-translator.js";
+import { runTurnBoundary, type TurnBoundaryOptions } from "../turn-boundary.js";
+
+const execFileAsync = promisify(execFile);
+const EXEC_ID = "exec-boundary-1";
+const CHANGE_SET_ID = `${EXEC_ID}:0`;
+
+let repo: string;
+let hitlDir: string;
+
+async function git(args: string[]): Promise<void> {
+  await execFileAsync("git", args, { cwd: repo });
+}
+async function write(rel: string, content: string): Promise<void> {
+  await writeFile(join(repo, rel), content, "utf-8");
+}
+
+function newStatus(): AgentExecutionStatus {
+  return create(AgentExecutionStatusSchema, {});
+}
+
+/** A streamed (COMPLETED) file-edit tool call, as the SDK would have recorded. */
+function streamedEdit(id: string, path: string, content: string): AgentMessage {
+  return create(AgentMessageSchema, {
+    type: MessageType.MESSAGE_AI,
+    toolCalls: [
+      create(ToolCallSchema, {
+        id,
+        name: "edit",
+        status: ToolCallStatus.TOOL_CALL_COMPLETED,
+        args: { path, content },
+      }),
+    ],
+  });
+}
+
+/** Boundary options for this repo's turn; overrides layer the per-test shape. */
+function boundaryOpts(
+  status: AgentExecutionStatus,
+  baselineTree: string,
+  overrides?: Partial<TurnBoundaryOptions>,
+): TurnBoundaryOptions {
+  return {
+    status,
+    executionId: EXEC_ID,
+    changeSetId: CHANGE_SET_ID,
+    hitlDir,
+    captureMode: true,
+    baselineTree,
+    primaryWorkspaceDir: repo,
+    gitWorkspace: true,
+    turnStartMessageIndex: 0,
+    approvalGrants: undefined,
+    globalBypass: false,
+    seededSubAgents: [],
+    artifactStorage: undefined,
+    mergedPolicies: new Map(),
+    ...overrides,
+  };
+}
+
+function candidateEvents(status: AgentExecutionStatus) {
+  return (status.fileReviewEventStream?.events ?? []).filter(
+    (e) => e.eventType === FileReviewEventType.CANDIDATE_CAPTURED,
+  );
+}
+
+beforeEach(async () => {
+  repo = await mkdtemp(join(tmpdir(), "stigmer-boundary-repo-"));
+  hitlDir = await mkdtemp(join(tmpdir(), "stigmer-boundary-hitl-"));
+  await git(["init", "-q"]);
+  await git(["config", "user.email", "t@t.local"]);
+  await git(["config", "user.name", "t"]);
+  await write("notes.md", "original notes\n");
+  await git(["add", "-A"]);
+  await git(["commit", "-q", "-m", "initial"]);
+});
+
+afterEach(async () => {
+  await rm(repo, { recursive: true, force: true });
+  await rm(hitlDir, { recursive: true, force: true });
+});
+
+describe("runTurnBoundary", () => {
+  it("authors a candidate, stamps the row, and pauses when the turn edited files", async () => {
+    const status = newStatus();
+    const baseline = await captureBaselineToLedger({
+      status,
+      gitRoot: repo,
+      executionId: EXEC_ID,
+      changeSetId: CHANGE_SET_ID,
+    });
+
+    await write("notes.md", "original notes\n\n## TODO\n- ship\n");
+    status.messages.push(
+      streamedEdit("tc-1", "notes.md", "original notes\n\n## TODO\n- ship\n"),
+    );
+
+    const result = await runTurnBoundary(boundaryOpts(status, baseline));
+
+    expect(result.waiting).toBe(true);
+    expect(result.capturedChangeCount).toBe(1);
+    expect(result.deniedToolCallCount).toBe(0);
+    expect(candidateEvents(status)).toHaveLength(1);
+    // The streamed row is stamped with the change set id (observational record
+    // anchoring the decision surface).
+    expect(status.messages[0].toolCalls[0].fileChangeSetId).toBe(CHANGE_SET_ID);
+  });
+
+  it("reports a clean turn when nothing changed (no candidate, no pause)", async () => {
+    const status = newStatus();
+    const baseline = await captureBaselineToLedger({
+      status,
+      gitRoot: repo,
+      executionId: EXEC_ID,
+      changeSetId: CHANGE_SET_ID,
+    });
+
+    const result = await runTurnBoundary(boundaryOpts(status, baseline));
+
+    expect(result.waiting).toBe(false);
+    expect(result.capturedChangeCount).toBe(0);
+    expect(result.deniedToolCallCount).toBe(0);
+    expect(candidateEvents(status)).toHaveLength(0);
+  });
+
+  it("skips capture when no baseline was authored this turn", async () => {
+    const status = newStatus();
+    await write("notes.md", "edited without a baseline\n");
+
+    const result = await runTurnBoundary(
+      boundaryOpts(status, "", { baselineTree: undefined }),
+    );
+
+    expect(result.waiting).toBe(false);
+    expect(result.capturedChangeCount).toBe(0);
+    expect(candidateEvents(status)).toHaveLength(0);
+  });
+
+  it("re-entered after a no-op primary call, authors the candidate exactly once (recovery-retry sequence)", async () => {
+    const status = newStatus();
+    const baseline = await captureBaselineToLedger({
+      status,
+      gitRoot: repo,
+      executionId: EXEC_ID,
+      changeSetId: CHANGE_SET_ID,
+    });
+
+    // Primary boundary: the resumed agent errored before touching anything —
+    // the tree is at baseline, no candidate is authored, the turn looks clean.
+    const primary = await runTurnBoundary(boundaryOpts(status, baseline));
+    expect(primary.waiting).toBe(false);
+    expect(candidateEvents(status)).toHaveLength(0);
+
+    // Recovery retry: a fresh agent re-ran the prompt and created the file.
+    await write("notes.md", "original notes\n\nretry made this edit\n");
+    status.messages.push(
+      streamedEdit("tc-retry", "notes.md", "original notes\n\nretry made this edit\n"),
+    );
+
+    // Boundary re-entry: the retry's edit reaches the ledger and arms the gate.
+    const retry = await runTurnBoundary(boundaryOpts(status, baseline));
+    expect(retry.waiting).toBe(true);
+    expect(retry.capturedChangeCount).toBe(1);
+    expect(candidateEvents(status)).toHaveLength(1);
+    expect(status.messages[0].toolCalls[0].fileChangeSetId).toBe(CHANGE_SET_ID);
+  });
+
+  it("surfaces a hook denial as a WAITING_APPROVAL gate and pauses", async () => {
+    const status = newStatus();
+    const baseline = await captureBaselineToLedger({
+      status,
+      gitRoot: repo,
+      executionId: EXEC_ID,
+      changeSetId: CHANGE_SET_ID,
+    });
+
+    // The hook gated a shell command mid-turn; the streamed call is still
+    // RUNNING (Cursor reported the deny to the model, not a completion).
+    const shellCall = create(ToolCallSchema, {
+      id: "tc-shell",
+      name: "shell",
+      status: ToolCallStatus.TOOL_CALL_RUNNING,
+      args: { command: "rm -rf build" },
+    });
+    status.messages.push(
+      create(AgentMessageSchema, {
+        type: MessageType.MESSAGE_AI,
+        content: "cleaning the build dir",
+        toolCalls: [shellCall],
+      }),
+    );
+    await writeFile(
+      denialLedgerPath(hitlDir),
+      JSON.stringify({ toolName: "shell", token: toolCallIdentityToken(shellCall) }) + "\n",
+      "utf-8",
+    );
+
+    const result = await runTurnBoundary(boundaryOpts(status, baseline));
+
+    expect(result.waiting).toBe(true);
+    expect(result.deniedToolCallCount).toBe(1);
+    expect(result.capturedChangeCount).toBe(0);
+    expect(shellCall.status).toBe(ToolCallStatus.TOOL_CALL_WAITING_APPROVAL);
+  });
+
+  it("waits for the denial-stop cancel to settle before reading the ledger", async () => {
+    const status = newStatus();
+    const baseline = await captureBaselineToLedger({
+      status,
+      gitRoot: repo,
+      executionId: EXEC_ID,
+      changeSetId: CHANGE_SET_ID,
+    });
+
+    const shellCall = create(ToolCallSchema, {
+      id: "tc-late",
+      name: "shell",
+      status: ToolCallStatus.TOOL_CALL_RUNNING,
+      args: { command: "curl example.com" },
+    });
+    status.messages.push(
+      create(AgentMessageSchema, {
+        type: MessageType.MESSAGE_AI,
+        toolCalls: [shellCall],
+      }),
+    );
+
+    // The denial lands only while the cancel is settling — a premature ledger
+    // read would miss it and leave the row RUNNING forever.
+    const denialCancelSettled = (async () => {
+      await writeFile(
+        denialLedgerPath(hitlDir),
+        JSON.stringify({ toolName: "shell", token: toolCallIdentityToken(shellCall) }) + "\n",
+        "utf-8",
+      );
+    })();
+
+    const result = await runTurnBoundary(
+      boundaryOpts(status, baseline, { denialCancelSettled }),
+    );
+
+    expect(result.deniedToolCallCount).toBe(1);
+    expect(shellCall.status).toBe(ToolCallStatus.TOOL_CALL_WAITING_APPROVAL);
+  });
+});

package/src/activities/execute-cursor/attachment-resolver.ts

@@ -17,7 +17,7 @@
  * Placement is always `inputs/{filename}` — the platform namespace this
  * harness can surface in the workspace. An attachment's `mountPath` is
  * honored by convention, not mechanism: the standard mounts (e.g. the
- * approved plan at `.stigmer/inputs/plan.md`) resolve to exactly this
+ * approved plan at `.stigmer/inputs/<slug>_<id>.plan.md`) resolve to exactly this
  * placement, and the prompt's `<input_files>` section plus any path-derived
  * directives are built from the RESOLVED paths, so prompt and filesystem can
  * never disagree.

package/src/activities/execute-cursor/capture-flow.ts

@@ -35,6 +35,10 @@ import {
   captureCandidateToLedger as sharedCaptureCandidateToLedger,
   type CaptureResumeResult,
 } from "../../shared/filereview/capture.js";
+import {
+  captureFileChangeProgress,
+  type ProgressCaptureState,
+} from "../../shared/filereview/progress.js";
 import { hasCandidateCaptured } from "../../shared/filereview/events.js";
 import { partitionIgnoredPathsBySecret } from "../../shared/filereview/secret-paths.js";
 import { casBlobReader, type CasPathCapture } from "../../shared/filereview/cas-substrate.js";
@@ -197,6 +201,34 @@ export async function captureTurnToLedger(opts: {
   return changes;
 }
 
+/**
+ * Mid-run: attach the live "N files changed so far" snapshot onto
+ * `status.file_change_progress` (DD-32), throttled by the floor + tree-sha
+ * short-circuit inside {@link captureFileChangeProgress}. The Cursor adapter binds
+ * `CURSOR_RUNNER_OWNED_PATHS` so the progress diff excludes the gate's own files —
+ * the SAME exclusion {@link captureTurnToLedger} uses for the turn-boundary
+ * candidate, so the live count and the reviewed set agree. Content-free and
+ * secret-safe; a no-op when nothing changed since the last capture.
+ */
+export async function captureProgressToStatus(opts: {
+  readonly status: AgentExecutionStatus;
+  readonly gitRoot: string;
+  readonly executionId: string;
+  readonly changeSetId: string;
+  readonly baselineTree: string;
+  readonly state: ProgressCaptureState;
+}): Promise<void> {
+  await captureFileChangeProgress({
+    status: opts.status,
+    gitRoot: opts.gitRoot,
+    executionId: opts.executionId,
+    changeSetId: opts.changeSetId,
+    baselineTree: opts.baselineTree,
+    excludePaths: CURSOR_RUNNER_OWNED_PATHS,
+    state: opts.state,
+  });
+}
+
 /**
  * Compose this turn's CAS captures from the sidecar the hook staged, mirroring
  * deep-agent's `buildCasTurnCaptures`: for each non-secret observed path, the