@stigmer/runner 3.15.1 → 3.15.2-dev.20260913223433

package/src/shared/workspace/__tests__/writeback-coordinator.test.ts

@@ -22,7 +22,7 @@ const SESSION_ID = "ses-01test";
 const SESSION_BRANCH = `stigmer/${SESSION_ID}`;
 
 // The shared proto-backed writer — the same implementation the Cursor harness
-// wires in, and upsert-compatible with the deep-agent StatusBuilder.
+// wires in, and upsert-compatible with the deep-agent V3StatusBuilder.
 function makeStatusBuilder(): ExecutionStatusWriter {
   return statusProtoWriter(create(AgentExecutionStatusSchema, {}));
 }
@@ -185,11 +185,14 @@ describe("WriteBackCoordinator", () => {
 
   // ── Full cycle ──────────────────────────────────────────────────────
 
+  // Every cycle below runs through `finalize()`, the coordinator's one entry
+  // point since S3 M2b (Q-M1-1; the per-file `onFileModified` went with the
+  // native stream loop that called it). The mechanics it pins are the same.
   it("performs full cycle on the SESSION branch: branch -> commit -> push -> PR", async () => {
     const backend = mockWorkspaceBackend();
     const coord = makeCoordinator({ sb, backend });
 
-    await coord.onFileModified("src/main.ts");
+    await coord.finalize();
 
     const wbs = sb.currentStatus.workspaceWriteBacks;
     expect(wbs).toHaveLength(1);
@@ -213,7 +216,7 @@ describe("WriteBackCoordinator", () => {
     const backend = mockWorkspaceBackend();
     const coord = makeCoordinator({ sb, backend, executionId: "exec-12345678rest" });
 
-    await coord.onFileModified("src/main.ts");
+    await coord.finalize();
 
     const commands = (backend.execute as ReturnType<typeof vi.fn>).mock.calls
       .map((c: any) => c[0] as string);
@@ -233,19 +236,19 @@ describe("WriteBackCoordinator", () => {
     });
     const coord = makeCoordinator({ sb, backend });
 
-    await coord.onFileModified("src/main.ts");
+    await coord.finalize();
 
     expect(sb.currentStatus.workspaceWriteBacks).toHaveLength(0);
   });
 
   // ── Session-branch idempotency ──────────────────────────────────────
 
-  it("on second call, commits to the existing branch without re-creating", async () => {
+  it("a second finalize commits to the existing branch without re-creating it", async () => {
     const backend = mockWorkspaceBackend();
     const coord = makeCoordinator({ sb, backend });
 
-    await coord.onFileModified("first.ts");
-    await coord.onFileModified("second.ts");
+    await coord.finalize();
+    await coord.finalize();
 
     const commands = (backend.execute as ReturnType<typeof vi.fn>).mock.calls
       .map((c: any) => c[0] as string);
@@ -263,7 +266,7 @@ describe("WriteBackCoordinator", () => {
     });
     const coord = makeCoordinator({ sb, backend, executionId: "exec-turn2" });
 
-    await coord.onFileModified("src/more.ts");
+    await coord.finalize();
 
     const commands = (backend.execute as ReturnType<typeof vi.fn>).mock.calls
       .map((c: any) => c[0] as string);
@@ -278,7 +281,7 @@ describe("WriteBackCoordinator", () => {
     });
     const coord = makeCoordinator({ sb, backend });
 
-    await coord.onFileModified("src/main.ts");
+    await coord.finalize();
 
     const commands = (backend.execute as ReturnType<typeof vi.fn>).mock.calls
       .map((c: any) => c[0] as string);
@@ -296,7 +299,7 @@ describe("WriteBackCoordinator", () => {
     });
     const coord = makeCoordinator({ sb, backend });
 
-    await coord.onFileModified("src/main.ts");
+    await coord.finalize();
 
     const commands = (backend.execute as ReturnType<typeof vi.fn>).mock.calls
       .map((c: any) => c[0] as string);
@@ -312,7 +315,7 @@ describe("WriteBackCoordinator", () => {
     });
     const coord = makeCoordinator({ sb });
 
-    await coord.onFileModified("src/main.ts");
+    await coord.finalize();
 
     const wbs = sb.currentStatus.workspaceWriteBacks;
     expect(wbs[0].pullRequestNumber).toBe(7);
@@ -328,7 +331,7 @@ describe("WriteBackCoordinator", () => {
     const calls = mockGithubApi();
     const coord = makeCoordinator({ sb, githubToken: "ghp_plumbed_token" });
 
-    await coord.onFileModified("src/main.ts");
+    await coord.finalize();
 
     expect(calls.length).toBeGreaterThan(0);
     for (const call of calls) {
@@ -350,7 +353,7 @@ describe("WriteBackCoordinator", () => {
     });
     const coord = makeCoordinator({ sb, backend });
 
-    await coord.onFileModified("src/main.ts");
+    await coord.finalize();
 
     const wbs = sb.currentStatus.workspaceWriteBacks;
     expect(wbs).toHaveLength(1);
@@ -364,7 +367,7 @@ describe("WriteBackCoordinator", () => {
     mockGithubApi({ createStatus: 403 });
     const coord = makeCoordinator({ sb });
 
-    await coord.onFileModified("src/main.ts");
+    await coord.finalize();
 
     const wbs = sb.currentStatus.workspaceWriteBacks;
     expect(wbs).toHaveLength(1);
@@ -381,7 +384,7 @@ describe("WriteBackCoordinator", () => {
     const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
     const coord = makeCoordinator({ sb, githubToken: "" });
 
-    await coord.onFileModified("src/main.ts");
+    await coord.finalize();
 
     const wbs = sb.currentStatus.workspaceWriteBacks;
     expect(wbs).toHaveLength(1);
@@ -391,9 +394,9 @@ describe("WriteBackCoordinator", () => {
     warnSpy.mockRestore();
   });
 
-  // ── finalize / path resolution ──────────────────────────────────────
+  // ── finalize on a fresh coordinator ─────────────────────────────────
 
-  it("finalize catches remaining uncommitted changes", async () => {
+  it("finalize commits, pushes and opens the PR for the entry's uncommitted changes", async () => {
     const coord = makeCoordinator({ sb });
 
     await coord.finalize();
@@ -403,50 +406,6 @@ describe("WriteBackCoordinator", () => {
       WorkspaceWriteBackPhase.WORKSPACE_WRITE_BACK_PR_CREATED,
     );
   });
-
-  it("resolves path to single entry without prefix matching", async () => {
-    const coord = makeCoordinator({ sb });
-
-    await coord.onFileModified("any/path/file.ts");
-
-    expect(sb.currentStatus.workspaceWriteBacks).toHaveLength(1);
-  });
-
-  it("resolves path to correct entry in multi-entry workspace", async () => {
-    const coord = makeCoordinator({
-      sb,
-      provisionResults: [
-        makeProvisionResult({ entryName: "frontend", rootDir: "/workspace/frontend" }),
-        makeProvisionResult({ entryName: "backend", rootDir: "/workspace/backend" }),
-      ],
-      workspaceEntries: [
-        makeWorkspaceEntry("frontend"),
-        makeWorkspaceEntry("backend"),
-      ],
-    });
-
-    await coord.onFileModified("frontend/src/app.tsx");
-
-    const wbs = sb.currentStatus.workspaceWriteBacks;
-    expect(wbs).toHaveLength(1);
-    expect(wbs[0].workspaceEntryName).toBe("frontend");
-  });
-
-  it("ignores paths outside eligible entries in multi-entry mode", async () => {
-    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
-    const coord = makeCoordinator({
-      sb,
-      provisionResults: [
-        makeProvisionResult({ entryName: "fe", rootDir: "/workspace/fe" }),
-        makeProvisionResult({ entryName: "be", rootDir: "/workspace/be" }),
-      ],
-      workspaceEntries: [makeWorkspaceEntry("fe"), makeWorkspaceEntry("be")],
-    });
-
-    await coord.onFileModified("unknown/file.ts");
-    expect(sb.currentStatus.workspaceWriteBacks).toHaveLength(0);
-    warnSpy.mockRestore();
-  });
 });
 
 describe("parseGithubRepo", () => {

package/src/shared/workspace/session-provision.ts

@@ -1,9 +1,9 @@
 /**
  * Local workspace provisioning for a harness turn.
  *
- * Harness-agnostic: the Cursor activity is today's only caller, the turn
- * runtime takes it over in S2 M3, and S3 retires the native twin
- * (execute-deep-agent/setup.ts `provisionWorkspace`). Agents run LOCAL
+ * Harness-agnostic: the turn runtime's workspace phase, serving both
+ * adapters (the native orchestrator's twin, `provisionWorkspace`, retired
+ * with it at S3 M2b; Q-S3-8 carried its one difference). Agents run LOCAL
  * (cloud is disabled — see execute-cursor/cursor-mode.ts), so the runner
  * must clone git-repo workspace entries itself and mount local-path entries
  * before the agent runs. Cloud agents previously cloned git repos

package/src/shared/workspace/stigmer-link.ts

@@ -16,9 +16,9 @@
  * - Created per turn, under the workspace turn lock — the link is a
  *   working-tree mutation, and re-pointing it while another session's turn is
  *   running on a shared tree would redirect that turn's reads mid-flight.
- *   Cursor creates it in its skill/attachment resolvers (which run after lock
- *   acquisition); the native harness creates it right after acquiring the
- *   lock (execute-deep-agent/index.ts).
+ *   the turn runtime creates it in its skill and attachment phases (which
+ *   run after lock acquisition), for both harnesses; until S3 M2a the native
+ *   orchestrator created it unconditionally right after the lock.
  * - Removed at turn end ({@link removeStigmerSymlink} in the activity's
  *   cleanup), so a real repo is left untouched once the turn ends; a
  *   multi-turn session recreates the link on the next turn.

package/src/shared/workspace/writeback-coordinator.ts

@@ -14,16 +14,18 @@
  * already exists (locally, or on the remote after a sandbox re-provision), and
  * an already-open PR for the branch is adopted instead of re-created.
  *
- * When this runs depends on the harness's file-review mode:
- *  - Capture mode (apply-then-review — every git workspace): the streaming
- *    trigger is suppressed and `finalize()` runs exactly once on the APPROVED
- *    tree, after review decisions reconcile (see processCaptureWriteback in
- *    index.ts). Speculative mid-turn edits never reach GitHub.
- *  - Legacy non-capture turns: `onFileModified(path)` triggers an incremental
- *    commit/push per file-modifying tool call (DD-5), with `finalize()` as the
- *    post-stream safety net.
+ * It runs ONCE per turn, at the end: the turn runtime calls `finalize()`
+ * (`harness/run-turn.ts`) — in capture mode on the APPROVED tree after the
+ * review decisions reconcile, so speculative mid-turn edits never reach
+ * GitHub; on a non-capture git turn on whatever the turn left in the tree.
+ * Until S3 M2b (Q-M1-1) an incremental path also existed — `onFileModified`,
+ * a commit-and-push per file-modifying tool call on non-capture turns — and
+ * was reachable in no supported posture (every git workspace with artifact
+ * storage is a capture workspace, `shared/filereview/capture.ts`
+ * `deriveCaptureMode`); it went with the native stream loop that called it.
  *
- * Concurrency: one mutex per workspace entry serializes git operations.
+ * Entries are written back in sequence, one cycle each; nothing here runs
+ * concurrently with itself.
  */
 
 import { create } from "@bufbuild/protobuf";
@@ -81,7 +83,6 @@ export class WriteBackCoordinator {
 
   private readonly eligible = new Map<string, EligibleEntry>();
   private readonly state = new Map<string, EntryState>();
-  private readonly locks = new Map<string, Promise<void>>();
 
   constructor(opts: {
     statusWriter: ExecutionStatusWriter;
@@ -109,38 +110,15 @@ export class WriteBackCoordinator {
   }
 
   /**
-   * Called after a file-modifying tool completes (legacy non-capture turns
-   * only). Resolves the path to a workspace entry and runs an incremental
-   * commit/push cycle. Fire-and-forget: errors are logged, never thrown.
-   */
-  async onFileModified(path: string): Promise<void> {
-    try {
-      const entryName = this.resolveEntry(path);
-      if (!entryName) return;
-
-      await this.withLock(entryName, () =>
-        this.writeBackEntry(entryName),
-      );
-    } catch (err) {
-      console.warn(
-        `[WriteBack] execution=${this.executionId} — ` +
-        `onFileModified error for '${path}': ${err}`,
-      );
-    }
-  }
-
-  /**
-   * Commits and pushes every eligible workspace entry's remaining uncommitted
-   * changes. In capture mode this is THE write-back — invoked once on the
-   * approved tree after review reconcile; on legacy turns it is the
-   * post-stream safety net.
+   * Commits and pushes every eligible workspace entry's uncommitted changes —
+   * THE write-back, once per turn (see the header). An entry's failure is
+   * recorded on its own write-back row and logged; it never throws, and it
+   * never stops the next entry.
    */
   async finalize(): Promise<void> {
     for (const entryName of this.eligible.keys()) {
       try {
-        await this.withLock(entryName, () =>
-          this.writeBackEntry(entryName),
-        );
+        await this.writeBackEntry(entryName);
       } catch (err) {
         console.warn(
           `[WriteBack] execution=${this.executionId} entry=${entryName} — ` +
@@ -199,21 +177,6 @@ export class WriteBackCoordinator {
     }
   }
 
-  // ── Path Resolution ─────────────────────────────────────────────────
-
-  private resolveEntry(path: string): string | null {
-    if (this.eligible.size === 0) return null;
-    if (this.eligible.size === 1) return this.eligible.keys().next().value!;
-
-    const normalized = path.replace(/^\/+/, "");
-    for (const entryName of this.eligible.keys()) {
-      if (normalized.startsWith(entryName + "/") || normalized === entryName) {
-        return entryName;
-      }
-    }
-    return null;
-  }
-
   // ── Core Write-Back Cycle ───────────────────────────────────────────
 
   /**
@@ -506,17 +469,6 @@ export class WriteBackCoordinator {
     this.statusWriter.addWriteBack(wb);
   }
 
-  // ── Concurrency ─────────────────────────────────────────────────────
-
-  private async withLock(
-    entryName: string,
-    fn: () => Promise<void>,
-  ): Promise<void> {
-    const existing = this.locks.get(entryName) ?? Promise.resolve();
-    const next = existing.then(fn, fn);
-    this.locks.set(entryName, next);
-    await next;
-  }
 }
 
 // ── Helpers ───────────────────────────────────────────────────────────

package/src/tools/index.ts

@@ -2,7 +2,7 @@
  * Native built-in tools for the deep-agent harness.
  *
  * These are Stigmer-authored capabilities appended to the agent's tool list
- * in execute-deep-agent/setup.ts (and mirrored for sub-agents in
+ * in execute-deep-agent/turn-setup.ts (and mirrored for sub-agents in
  * subagent-transformer.ts) — distinct from deepagents' backend tools
  * (ls/read_file/execute/…) and from MCP tools, which arrive via the
  * connection layer.

package/dist/activities/execute-cursor/capture-flow.d.ts

@@ -1,142 +0,0 @@
-/**
- * Cursor adapter over the harness-agnostic capture-mode orchestration
- * ({@link ../../shared/filereview/capture.js}).
- *
- * The substrate (git snapshot/restore) and the orchestration (baseline/candidate/
- * reconcile authoring) live in `shared/filereview/` so the Cursor and deep-agent
- * harnesses author IDENTICAL ledger entries. This adapter binds the Cursor
- * specifics:
- *  - `harnessId = "cursor"` (stamped on the BASELINE payload the projection reads);
- *  - the Cursor gate files written into the workspace, excluded from the captured
- *    diff (`CURSOR_RUNNER_OWNED_PATHS`);
- *  - stamping the streamed file-edit transcript rows that flowed this turn with
- *    the change set id (`stampFlowedFileEditRows`) — the rows stay visible as
- *    observational/audit records at their transcript positions, while
- *    `file_change_sets` remains the single DECISION surface.
- *
- * The resume-time reconcile is NOT here since S2 M2: the turn runtime's
- * `reconcileReinvocation` (`harness/turn-context.ts`) calls the shared
- * reconcile directly under {@link CURSOR_FILE_REVIEW_IDENTITY}, the one
- * export that carries the two Cursor facts it needs. The two capture
- * functions keep their original signatures so the activity wiring (index.ts)
- * and the cutover tests are unchanged.
- */
-import type { AgentMessage } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
-import type { AgentExecutionStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
-import type { TurnCommandProvenance } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/filereview_pb";
-import { type ProgressSubstrate } from "../../shared/filereview/progress.js";
-import type { GitSubstrateChange as GitCapturedChange } from "../../shared/filereview/git-substrate.js";
-import type { ArtifactStorage } from "../../shared/artifact-storage.js";
-import type { FileReviewIdentity } from "../../harness/capabilities.js";
-/**
- * The two facts the runtime's resume-time reconcile needs from this harness
- * (`harness/turn-context.ts` `reconcileReinvocation`): the same id and
- * exclude list the capture functions below stamp and apply, so the baseline a
- * turn authors and the reconcile a resume runs agree by construction.
- */
-export declare const CURSOR_FILE_REVIEW_IDENTITY: FileReviewIdentity;
-export { deriveCaptureMode } from "../../shared/filereview/capture.js";
-/**
- * Turn start: pin the pre-turn working tree behind the baseline ref and author
- * BASELINE_CAPTURED (harnessId "cursor"). Returns the baseline tree sha for the
- * turn-end diff.
- */
-export declare function captureBaselineToLedger(opts: {
-    readonly status: AgentExecutionStatus;
-    readonly gitRoot: string;
-    readonly executionId: string;
-    readonly changeSetId: string;
-    /** True (default) for a git work tree; false for a CAS-only non-git workspace. */
-    readonly gitWorkspace?: boolean;
-}): Promise<string>;
-/**
- * Turn end: capture the change set + author CANDIDATE_CAPTURED, then stamp the
- * streamed file-edit rows that flowed this turn with the change set id — the
- * rows stay visible in place as observational records while `file_change_sets`
- * remains the single decision surface. The working tree is LEFT applied
- * (Cursor parity).
- *
- * The change set is HYBRID (git tree) or CAS-only (non-git): the hook-staged
- * writes from the cas-observations sidecar this turn ({@link readCasObservations})
- * — the Cursor analog of deep-agent's `buildCasTurnCaptures` — composed with the
- * git-tracked diff when `gitWorkspace`. Non-secret staged paths become
- * `GIT_IGNORED_CAPTURED` (git tree) or `NON_GIT_CAS` (non-git) CAS captures
- * (before-bytes from the sidecar, after-bytes re-read from disk);
- * secret-blocked paths become content-less `DIFF_UNREVIEWABLE` entries. The
- * boundary re-runs {@link partitionIgnoredPathsBySecret} as a fail-closed
- * backstop, so a secret that ever slipped into the captured set still has its
- * bytes withheld from durable storage.
- *
- * `deniedTokens` are the identities the hook gated this turn (shell/MCP, or a
- * secret-like delete — non-secret CAS deletes flow since issue #303). A streamed
- * file-edit row whose identity is in that set is left for the deny-gate
- * reconcile path — it did NOT flow. A flowed gitignored write or delete is NOT
- * in that set (the hook allowed it), so it is stamped like any other flowed
- * edit and its captured delta surfaces as a CAS entry in the set.
- *
- * `hitlDir`/`storage` are omitted only by callers with no artifact storage
- * (captureIgnored off); the CAS half is then skipped and this is a git-only
- * capture exactly as before.
- *
- * Mutates `messages` and `status` in place. Returns the captured git changes.
- */
-export declare function captureTurnToLedger(opts: {
-    readonly status: AgentExecutionStatus;
-    readonly gitRoot: string;
-    readonly executionId: string;
-    readonly changeSetId: string;
-    readonly baselineTree: string;
-    readonly messages: AgentMessage[];
-    readonly deniedTokens: ReadonlySet<string>;
-    readonly hitlDir?: string;
-    readonly storage?: ArtifactStorage;
-    /**
-     * Sub-agent tool-call ids that existed BEFORE this turn's stream (the seeded
-     * prior sub-agents). Sub-agent edit rows created this turn are stamped with the
-     * parent change set id; rows in this set are skipped so a resume never
-     * re-stamps a prior turn's sub-agent rows. Omit when there are no prior
-     * sub-agents.
-     */
-    readonly priorSubAgentToolCallIds?: ReadonlySet<string>;
-    /**
-     * True (default) for a git work tree — the candidate is the git diff composed
-     * with the gitignored CAS captures (`GIT_IGNORED_CAPTURED`). False for a non-git
-     * workspace (Slice 2c): there is no git diff, so the whole change set is the CAS
-     * captures the hook staged for EVERY touched path (`NON_GIT_CAS`).
-     */
-    readonly gitWorkspace?: boolean;
-    /**
-     * The approved-command turn facts (DD-28), derived by the caller from the
-     * turn's tool calls ({@link ../command-provenance.js}). Present only when the
-     * turn qualifies; carried verbatim to the CANDIDATE event.
-     */
-    readonly commandProvenance?: TurnCommandProvenance;
-}): Promise<readonly GitCapturedChange[]>;
-/**
- * Choose the mid-run progress substrate for this turn's workspace shape (DD-32 /
- * DD-33), returning `undefined` when there is nothing to observe (not capture
- * mode, or no workspace). Built ONCE per turn — the substrate owns its own
- * short-circuit cache across the loop's persists; the floor lives in the caller's
- * `ProgressCaptureState`. The live count and the turn-boundary reviewed set agree
- * by construction: the git slice binds the SAME `CURSOR_RUNNER_OWNED_PATHS`
- * exclusion {@link captureTurnToLedger} uses, and the CAS slice reads the SAME
- * hook sidecar ({@link readCasObservations}) the boundary reads.
- *
- *  - git tree, no storage      -> git substrate only (tracked-file `--numstat`);
- *  - git tree, storage (HYBRID) -> git + CAS (the gitignored writes the hook staged);
- *  - non-git workspace          -> CAS only (every tool-mediated write is CAS-staged).
- *
- * The CAS slice needs the hook sidecar, which exists only when `captureIgnored`
- * is on (storage configured). A non-git capture already required storage
- * (`deriveCaptureMode`), so its sidecar is always present; a git tree with no
- * storage simply gets the git-only substrate (parity with the pre-DD-33 behavior).
- */
-export declare function buildCursorProgressSubstrate(opts: {
-    readonly captureMode: boolean;
-    readonly gitWorkspace: boolean;
-    readonly workspaceRoot: string | undefined;
-    readonly baselineTree: string | undefined;
-    readonly executionId: string;
-    readonly hitlDir: string | undefined;
-    readonly storage: ArtifactStorage | undefined;
-}): ProgressSubstrate | undefined;