@stigmer/runner 3.1.5 → 3.1.6

package/src/activities/execute-cursor/__tests__/workspace-provision.test.ts

@@ -138,12 +138,13 @@ describe("provisionCursorWorkspace", () => {
     const workspaceRoot = join(tmpRoot, "workspace");
     mkdirSync(workspaceRoot, { recursive: true });
 
-    const dirs = await provisionCursorWorkspace(
-      makeConfig(workspaceRoot),
-      gitRepoSession(source),
-      {},
-      "test-session-clone",
-    );
+    const { workspaceDirs: dirs, provisionResults, workspaceBackend } =
+      await provisionCursorWorkspace(
+        makeConfig(workspaceRoot),
+        gitRepoSession(source),
+        {},
+        "test-session-clone",
+      );
 
     expect(dirs).toHaveLength(1);
     const clonedFile = join(dirs[0], MARKER_FILE);
@@ -151,6 +152,12 @@ describe("provisionCursorWorkspace", () => {
     expect(readFileSync(clonedFile, "utf-8")).toBe(MARKER_CONTENT);
     // The clone must be a real git repo (so the agent can run git in it).
     expect(existsSync(join(dirs[0], ".git"))).toBe(true);
+
+    // The provision results carry the git metadata the write-back
+    // coordinator consumes (repo URL, base branch), through the same backend.
+    expect(provisionResults).toHaveLength(1);
+    expect(provisionResults[0].gitMetadata?.branch).toBe("main");
+    expect(workspaceBackend).toBeDefined();
   }, GIT_TEST_TIMEOUT_MS);
 
   it("clones into a workspace root that already contains lost+found (PVC simulation)", async () => {
@@ -161,7 +168,7 @@ describe("provisionCursorWorkspace", () => {
     mkdirSync(join(workspaceRoot, "lost+found"), { recursive: true });
     writeFileSync(join(workspaceRoot, "lost+found", "stray"), "fsck-artifact");
 
-    const dirs = await provisionCursorWorkspace(
+    const { workspaceDirs: dirs } = await provisionCursorWorkspace(
       makeConfig(workspaceRoot),
       gitRepoSession(source),
       {},
@@ -196,7 +203,7 @@ describe("provisionCursorWorkspace", () => {
     const workspaceRoot = join(tmpRoot, "default-branch-workspace");
     mkdirSync(workspaceRoot, { recursive: true });
 
-    const dirs = await provisionCursorWorkspace(
+    const { workspaceDirs: dirs } = await provisionCursorWorkspace(
       makeConfig(workspaceRoot),
       gitRepoSessionNoBranch(source),
       {},
@@ -221,7 +228,7 @@ describe("provisionCursorWorkspace", () => {
     // a worktree here, so it must be left untouched.
     mkdirSync(join(workspaceRoot, "lost+found"), { recursive: true });
 
-    const dirs = await provisionCursorWorkspace(
+    const { workspaceDirs: dirs } = await provisionCursorWorkspace(
       makeConfig(workspaceRoot),
       multiGitRepoSession([
         { name: "frontend", url: frontend },
@@ -259,13 +266,14 @@ describe("provisionCursorWorkspace", () => {
     // Leftovers from other sessions at the shared root must not be visible.
     writeFileSync(join(workspaceRoot, "other-session-leftover.md"), "not yours");
 
-    const dirs = await provisionCursorWorkspace(
+    const { workspaceDirs: dirs, provisionResults } = await provisionCursorWorkspace(
       makeConfig(workspaceRoot),
       emptySession(),
       {},
       "test-session-empty",
     );
 
+    expect(provisionResults).toEqual([]);
     expect(dirs).toEqual([join(workspaceRoot, "sessions", "test-session-empty")]);
     expect(existsSync(dirs[0])).toBe(true);
     expect(existsSync(join(dirs[0], "other-session-leftover.md"))).toBe(false);
@@ -276,9 +284,9 @@ describe("provisionCursorWorkspace", () => {
     mkdirSync(workspaceRoot, { recursive: true });
     const config = makeConfig(workspaceRoot);
 
-    const turn1 = await provisionCursorWorkspace(config, emptySession(), {}, "stable-session");
+    const turn1 = (await provisionCursorWorkspace(config, emptySession(), {}, "stable-session")).workspaceDirs;
     writeFileSync(join(turn1[0], "notes.md"), "turn 1 output");
-    const turn2 = await provisionCursorWorkspace(config, emptySession(), {}, "stable-session");
+    const turn2 = (await provisionCursorWorkspace(config, emptySession(), {}, "stable-session")).workspaceDirs;
 
     expect(turn2).toEqual(turn1);
     expect(readFileSync(join(turn2[0], "notes.md"), "utf-8")).toBe("turn 1 output");
@@ -289,8 +297,8 @@ describe("provisionCursorWorkspace", () => {
     mkdirSync(workspaceRoot, { recursive: true });
     const config = makeConfig(workspaceRoot);
 
-    const [dirA] = await provisionCursorWorkspace(config, emptySession(), {}, "session-a");
-    const [dirB] = await provisionCursorWorkspace(config, emptySession(), {}, "session-b");
+    const [dirA] = (await provisionCursorWorkspace(config, emptySession(), {}, "session-a")).workspaceDirs;
+    const [dirB] = (await provisionCursorWorkspace(config, emptySession(), {}, "session-b")).workspaceDirs;
 
     expect(dirA).not.toBe(dirB);
     writeFileSync(join(dirA, "a.md"), "session a");
@@ -304,7 +312,7 @@ describe("provisionCursorWorkspace", () => {
     const workspaceRoot = join(tmpRoot, "workspace-local");
     mkdirSync(workspaceRoot, { recursive: true });
 
-    const dirs = await provisionCursorWorkspace(
+    const { workspaceDirs: dirs } = await provisionCursorWorkspace(
       makeConfig(workspaceRoot),
       localPathSession(projectDir),
       {},

package/src/activities/execute-cursor/index.ts

@@ -99,6 +99,8 @@ import {
 import { deriveExecutionFingerprintKey } from "../../shared/approval-fingerprint.js";
 import { getRunnerHitlMasterSecret } from "../../shared/fingerprint-secret.js";
 import { provisionCursorWorkspace } from "./workspace-provision.js";
+import { WriteBackCoordinator } from "../../shared/workspace/writeback-coordinator.js";
+import { statusProtoWriter } from "../../shared/execution-status-writer.js";
 import { setInterceptorExecutionId, runWithExecutionContext } from "./fetch-interceptor.js";
 import { closeProxySessions } from "./http2-interceptor.js";
 import { resolveModelId, ensureLoaded as ensurePricingLoaded } from "./model-pricing.js";
@@ -277,11 +279,32 @@ async function executeCursorInner(
     // native harness. Git provisioning is idempotent across multi-turn and
     // HITL reinvocations.
     await reportSetupProgress(client, executionId, "Provisioning workspace");
-    blueprint.workspaceDirs = await provisionCursorWorkspace(
+    const workspaceProvision = await provisionCursorWorkspace(
       config, session, envVars, sessionId ?? "",
     );
+    blueprint.workspaceDirs = workspaceProvision.workspaceDirs;
     heartbeat();
 
+    // Git write-back: pushes the session's APPROVED tree to the session
+    // branch (stigmer/<session-id>) and keeps one PR open — the same
+    // approval-gated model as the deep-agent harness (its
+    // processCaptureWriteback). Finalize runs at exactly two seams below:
+    // the pure-file-review resume (after decisions reconcile) and terminal
+    // completion. Never mid-turn: the working tree is speculative until
+    // reviewed. Non-eligible workspaces (local paths, no credentials) make
+    // this a no-op coordinator.
+    const writebackCoordinator = workspaceProvision.provisionResults.length > 0
+      ? new WriteBackCoordinator({
+          statusWriter: statusProtoWriter(status),
+          executionId,
+          sessionId: sessionId ?? "",
+          githubToken: envVars.GITHUB_TOKEN ?? "",
+          provisionResults: workspaceProvision.provisionResults,
+          workspaceEntries: session.spec?.workspaceEntries ?? [],
+          workspaceBackend: workspaceProvision.workspaceBackend,
+        })
+      : null;
+
     // Apply-then-review is the universal file-review model (Slice 2c). When the
     // primary workspace is a real git work tree, file edits flow during the turn
     // and are captured per-file from the git diff at the turn boundary
@@ -478,6 +501,14 @@ async function executeCursorInner(
         // (Cursor-like). The reconcile is done; the execution is complete.
         status.phase = ExecutionPhase.EXECUTION_COMPLETED;
         status.completedAt = utcTimestamp();
+        // Push the APPROVED tree — reconcile snapped rejected files back to
+        // baseline, so what finalize commits is exactly what the user kept.
+        // Mirrors the deep-agent's processCaptureWriteback: after reconcile,
+        // before persist, never on a failed reconcile (diverged bytes must
+        // not reach the remote).
+        if (!fileReviewFailed && writebackCoordinator) {
+          await writebackCoordinator.finalize();
+        }
         if (fileReviewFailed) {
           // What-you-approve-is-what-applies could not be honored (on-disk bytes
           // diverged from the approved digest). Surface it to the human; the
@@ -1566,6 +1597,15 @@ async function executeCursorInner(
       );
     }
 
+    // Write-back safety net on terminal completion. A capture-mode turn with
+    // captured changes always paused above (boundary.waiting), so reaching
+    // here means no reviewable delta this turn and this is normally a no-op —
+    // it exists for the same reason the deep-agent finalizes on completion:
+    // stragglers outside the capture (and it never runs mid-turn).
+    if (status.phase === ExecutionPhase.EXECUTION_COMPLETED && writebackCoordinator) {
+      await writebackCoordinator.finalize();
+    }
+
     // NOW persist — subscriber sees COMPLETED + structured_output atomically
     await persist(status);
 

package/src/activities/execute-cursor/workspace-provision.ts

@@ -10,18 +10,38 @@
 import type { Config } from "../../config.js";
 import type { Session } from "@stigmer/protos/ai/stigmer/agentic/session/v1/api_pb";
 import { WorkspaceProvisioner } from "../../shared/workspace/provisioner.js";
+import type { ProvisionResult, WorkspaceBackend } from "../../shared/workspace/types.js";
 import { LocalWorkspaceBackend } from "../../shared/workspace/local-backend.js";
 import { ensurePlatformDir } from "../../shared/workspace/platform-dir.js";
 import { resolveSessionWorkspaceRoot } from "../../shared/workspace/session-root.js";
 
+/** What {@link provisionCursorWorkspace} hands back to the harness. */
+export interface CursorWorkspaceProvision {
+  /** The directories the agent should operate in (never empty). */
+  readonly workspaceDirs: string[];
+  /**
+   * Per-entry provision outcomes — carries the git metadata (repo URL, base
+   * branch, credential state) the write-back coordinator needs. Empty for a
+   * session with no workspace entries.
+   */
+  readonly provisionResults: ProvisionResult[];
+  /**
+   * The backend the entries were provisioned through — the write-back
+   * coordinator executes its git commands through it.
+   */
+  readonly workspaceBackend: WorkspaceBackend;
+}
+
 /**
  * Provision the session's workspace entries for a LOCAL Cursor agent.
  *
  * Clones git-repo entries (using the user's GITHUB_TOKEN from the resolved
  * execution environment) and mounts local-path entries, then returns the
- * directories the agent should operate in. A session with no workspace
- * entries gets its own empty per-session directory (see session-root.ts) —
- * never the shared root, which would leak other sessions' files into it.
+ * directories the agent should operate in — along with the provision results
+ * and backend the git write-back coordinator needs. A session with no
+ * workspace entries gets its own empty per-session directory (see
+ * session-root.ts) — never the shared root, which would leak other sessions'
+ * files into it.
  *
  * provisionGit is idempotent (it reuses an existing clone), so this is safe
  * to call on every execution, including multi-turn and HITL reinvocations.
@@ -31,13 +51,21 @@ export async function provisionCursorWorkspace(
   session: Session,
   envVars: Record<string, string>,
   sessionId: string,
-): Promise<string[]> {
+): Promise<CursorWorkspaceProvision> {
   const entries = session.spec?.workspaceEntries ?? [];
+  const platformDir = await ensurePlatformDir(sessionId);
+
   if (entries.length === 0) {
-    return [await resolveSessionWorkspaceRoot(config.workspaceRootDir, entries, sessionId)];
+    const sessionRoot = await resolveSessionWorkspaceRoot(
+      config.workspaceRootDir, entries, sessionId,
+    );
+    return {
+      workspaceDirs: [sessionRoot],
+      provisionResults: [],
+      workspaceBackend: new LocalWorkspaceBackend(sessionRoot, platformDir),
+    };
   }
 
-  const platformDir = await ensurePlatformDir(sessionId);
   const backend = new LocalWorkspaceBackend(config.workspaceRootDir, platformDir);
 
   const provisioner = new WorkspaceProvisioner();
@@ -53,5 +81,9 @@ export async function provisionCursorWorkspace(
     .map((result) => result.rootDir)
     .filter((dir): dir is string => Boolean(dir));
 
-  return dirs.length > 0 ? dirs : [config.workspaceRootDir];
+  return {
+    workspaceDirs: dirs.length > 0 ? dirs : [config.workspaceRootDir],
+    provisionResults: results,
+    workspaceBackend: backend,
+  };
 }

package/src/activities/execute-deep-agent/__tests__/post-stream.test.ts

@@ -3,7 +3,7 @@ import { create } from "@bufbuild/protobuf";
 import { AgentExecutionStatusSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
 import { processPostStream } from "../post-stream.js";
 import type { InlinePublisher } from "../inline-publisher.js";
-import type { WriteBackCoordinator } from "../writeback-coordinator.js";
+import type { WriteBackCoordinator } from "../../../shared/workspace/writeback-coordinator.js";
 
 function mockInlinePublisher(): InlinePublisher {
   return {

package/src/activities/execute-deep-agent/index.ts

@@ -45,7 +45,7 @@ import { streamExecution, type StreamResult } from "./streaming.js";
 import { loadStreamingConfig } from "../../shared/streaming-scheduler.js";
 import { StatusBuilder } from "./status-builder.js";
 import { InlinePublisher } from "./inline-publisher.js";
-import { WriteBackCoordinator } from "./writeback-coordinator.js";
+import { WriteBackCoordinator } from "../../shared/workspace/writeback-coordinator.js";
 import { processPostStream } from "./post-stream.js";
 import { resolveResumeInput, type GraphStateSnapshot } from "./hitl.js";
 import { captureApprovalArtifacts } from "./approval-file-change.js";
@@ -184,6 +184,13 @@ export function createDeepAgentActivities(config: Config) {
           ? new WriteBackCoordinator({
               statusWriter: statusBuilder,
               executionId,
+              // Branch/PR are session-scoped: every turn of this session
+              // appends commits to the same stigmer/<session-id> branch.
+              sessionId: setup.session.metadata?.id ?? "",
+              // The PR API token, plumbed from the resolved execution env —
+              // gitMetadata.repoUrl is token-stripped by construction, so the
+              // coordinator can never recover it from provisioning state.
+              githubToken: setup.mergedEnvVars.GITHUB_TOKEN ?? "",
               provisionResults: setup.provisionResults,
               workspaceEntries: workspaceEntries as any,
               workspaceBackend: setup.workspaceBackend,

package/src/activities/execute-deep-agent/inline-publisher.ts

@@ -20,7 +20,7 @@ import {
 } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import type { ArtifactStorage } from "../../shared/artifact-storage.js";
 import type { WorkspaceBackend } from "../../shared/workspace/types.js";
-import type { ExecutionStatusWriter } from "./execution-status-writer.js";
+import type { ExecutionStatusWriter } from "../../shared/execution-status-writer.js";
 import { utcTimestamp } from "../../shared/status.js";
 import { isSecretLikePath } from "../../shared/filereview/secret-paths.js";
 

package/src/activities/execute-deep-agent/post-stream.ts

@@ -13,7 +13,7 @@
 import type { AgentExecutionStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
 import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import type { InlinePublisher } from "./inline-publisher.js";
-import type { WriteBackCoordinator } from "./writeback-coordinator.js";
+import type { WriteBackCoordinator } from "../../shared/workspace/writeback-coordinator.js";
 import { autoPublishWrittenFiles } from "./auto-publish.js";
 
 export interface PostStreamOptions {

package/src/activities/execute-deep-agent/status-builder.ts

@@ -31,7 +31,7 @@ import { classifyTool } from "../../shared/tool-kind.js";
 import { applyTodoUpdate } from "../../shared/todos.js";
 import { ExecutionState } from "./execution-state.js";
 import { utcTimestamp } from "../../shared/status.js";
-import type { ExecutionStatusWriter } from "./execution-status-writer.js";
+import type { ExecutionStatusWriter } from "../../shared/execution-status-writer.js";
 import {
   UsageAccumulator,
   extractToolResult,

package/src/activities/execute-deep-agent/streaming-side-effects.ts

@@ -8,7 +8,7 @@
 
 import type { V3ProtocolEvent } from "./v3-event-recorder.js";
 import type { InlinePublisher } from "./inline-publisher.js";
-import type { WriteBackCoordinator } from "./writeback-coordinator.js";
+import type { WriteBackCoordinator } from "../../shared/workspace/writeback-coordinator.js";
 import { extractFilePath, isFileModifyingTool } from "../../shared/file-tools.js";
 
 interface CachedToolInput {

package/src/activities/execute-deep-agent/streaming-terminal.ts

@@ -8,7 +8,7 @@
 import { create } from "@bufbuild/protobuf";
 import { AgentMessageSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
 import { ExecutionPhase, MessageType } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
-import type { ExecutionStatusWriter } from "./execution-status-writer.js";
+import type { ExecutionStatusWriter } from "../../shared/execution-status-writer.js";
 import type { StreamResult } from "./streaming.js";
 import { slimStatus, utcTimestamp } from "../../shared/status.js";
 

package/src/activities/execute-deep-agent/streaming.ts

@@ -39,7 +39,7 @@ import type { ToolOutputOffloadContext } from "../../shared/status-offload.js";
 import type { StigmerClient } from "../../client/stigmer-client.js";
 import type { GracefulStopMiddleware } from "../../middleware/index.js";
 import type { InlinePublisher } from "./inline-publisher.js";
-import type { WriteBackCoordinator } from "./writeback-coordinator.js";
+import type { WriteBackCoordinator } from "../../shared/workspace/writeback-coordinator.js";
 import { createV2EventRecorder } from "./event-recorder.js";
 import { streamExecutionV3 } from "./streaming-v3.js";
 import { extractFilePath, isFileModifyingTool } from "../../shared/file-tools.js";

package/src/activities/execute-deep-agent/v3-status-builder.ts

@@ -30,7 +30,7 @@ import { classifyTool } from "../../shared/tool-kind.js";
 import { applyTodoUpdate } from "../../shared/todos.js";
 import { ExecutionState } from "./execution-state.js";
 import { utcTimestamp } from "../../shared/status.js";
-import type { ExecutionStatusWriter } from "./execution-status-writer.js";
+import type { ExecutionStatusWriter } from "../../shared/execution-status-writer.js";
 import type { ApprovalPolicyProvider } from "./status-builder.js";
 import type { StigmerRunEvent, V3UsagePayload } from "./v3-events.js";
 import { namespaceDepth } from "./v3-events.js";

package/src/shared/execution-status-writer.ts

@@ -0,0 +1,56 @@
+/**
+ * Shared interface for proto mutation consumed by side-effect classes
+ * (InlinePublisher, WriteBackCoordinator) and streaming loops.
+ *
+ * The deep-agent harness implements it on its v2 StatusBuilder and
+ * V3StatusBuilder; the Cursor harness — which mutates a bare status proto
+ * with no builder — uses {@link statusProtoWriter}. Side-effect classes
+ * depend only on this interface, never on a specific implementation.
+ */
+
+import type { AgentExecutionStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import type { ExecutionArtifact } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/artifact_pb";
+import type { WorkspaceWriteBack } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/writeback_pb";
+
+export interface ExecutionStatusWriter {
+  readonly currentStatus: AgentExecutionStatus;
+  readonly forceNextUpdate: boolean;
+  clearForceFlag(): void;
+  addArtifact(artifact: ExecutionArtifact): void;
+  addWriteBack(wb: WorkspaceWriteBack): void;
+}
+
+/**
+ * An {@link ExecutionStatusWriter} over a bare status proto, for harnesses
+ * that mutate the status directly instead of through a builder (the Cursor
+ * harness). Mutations apply synchronously to the given proto; the caller's
+ * own persist points pick them up — the force flag is a streaming-loop
+ * concern the direct-mutation style has no use for, so it stays `false`.
+ *
+ * Write-backs upsert by `workspaceEntryName` — the same contract as the
+ * deep-agent `StatusBuilder.addWriteBack`: each git-backed workspace entry
+ * carries at most one record, progressing through phases.
+ */
+export function statusProtoWriter(status: AgentExecutionStatus): ExecutionStatusWriter {
+  return {
+    get currentStatus() {
+      return status;
+    },
+    forceNextUpdate: false,
+    clearForceFlag() {},
+    addArtifact(artifact: ExecutionArtifact) {
+      status.artifacts.push(artifact);
+    },
+    addWriteBack(wb: WorkspaceWriteBack) {
+      const backs = status.workspaceWriteBacks;
+      const idx = backs.findIndex(
+        (b) => b.workspaceEntryName === wb.workspaceEntryName,
+      );
+      if (idx >= 0) {
+        backs[idx] = wb;
+      } else {
+        backs.push(wb);
+      }
+    },
+  };
+}

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

@@ -0,0 +1,230 @@
+/**
+ * Real-git integration tests for the session-scoped write-back lifecycle.
+ *
+ * A hermetic origin (local bare repo) and a working clone stand in for
+ * GitHub + the session workspace; only the PR API is mocked. These prove the
+ * behaviors the mocked unit suite cannot: that `ensureBranch`'s checkout
+ * cases and the always-`-u` push compose correctly against real git across
+ * SEQUENTIAL COORDINATOR INSTANCES (turn 1 and turn 2 of one session), and
+ * that only the tree's content at finalize — the post-reconcile, approved
+ * content — reaches the session branch.
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { create } from "@bufbuild/protobuf";
+import { AgentExecutionStatusSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { WorkspaceWriteBackPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/writeback_pb";
+import { GitWriteBackMode } from "@stigmer/protos/ai/stigmer/agentic/session/v1/enum_pb";
+import { WriteBackCoordinator } from "../writeback-coordinator.js";
+import { LocalWorkspaceBackend } from "../local-backend.js";
+import { statusProtoWriter, type ExecutionStatusWriter } from "../../execution-status-writer.js";
+import type { ProvisionResult } from "../types.js";
+import { SourceType } from "../types.js";
+import { AGENT_GIT_AUTHOR_EMAIL } from "../git-identity.js";
+
+const SESSION_ID = "ses-int-01";
+const SESSION_BRANCH = `stigmer/${SESSION_ID}`;
+
+// Real git spawns (init/clone/commit/push, ~a dozen per test) are slow under
+// full-suite parallel load — observed >40s wall clock at ~4s of actual work.
+const GIT_TEST_TIMEOUT_MS = 120_000;
+
+let tmpRoot: string;
+let originDir: string;
+let workDir: string;
+
+function git(cwd: string, args: string[]): string {
+  return execFileSync("git", args, {
+    cwd,
+    encoding: "utf-8",
+    env: {
+      ...process.env,
+      GIT_AUTHOR_NAME: "human",
+      GIT_AUTHOR_EMAIL: "human@example.com",
+      GIT_COMMITTER_NAME: "human",
+      GIT_COMMITTER_EMAIL: "human@example.com",
+    },
+  });
+}
+
+function makeCoordinator(
+  executionId: string,
+  writer: ExecutionStatusWriter,
+): WriteBackCoordinator {
+  const provisionResult: ProvisionResult = {
+    rootDir: workDir,
+    sourceType: SourceType.GIT_REPO,
+    consumedKeys: [],
+    workspaceDescription: "integration",
+    entryName: "repo",
+    gitMetadata: {
+      repoUrl: "https://github.com/acme/repo.git",
+      branch: "main",
+      baseCommit: git(workDir, ["rev-parse", "main"]).trim(),
+      gitCredentialsConfigured: true,
+    },
+  };
+  return new WriteBackCoordinator({
+    statusWriter: writer,
+    executionId,
+    sessionId: SESSION_ID,
+    githubToken: "ghp_test",
+    provisionResults: [provisionResult],
+    workspaceEntries: [
+      {
+        name: "repo",
+        source: {
+          source: {
+            case: "gitRepo" as const,
+            value: { writeBackMode: GitWriteBackMode.GIT_WRITE_BACK_BRANCH_AND_PR },
+          },
+        },
+      } as any,
+    ],
+    workspaceBackend: new LocalWorkspaceBackend(workDir),
+  });
+}
+
+/** The PR API mock: no open PR on first list, then created; adopted after. */
+function mockGithubApi(): Array<{ method: string; url: string }> {
+  const calls: Array<{ method: string; url: string }> = [];
+  let created = false;
+  globalThis.fetch = vi.fn(async (url: any, init?: any) => {
+    const method = init?.method ?? "GET";
+    calls.push({ method, url: String(url) });
+    if (method === "GET") {
+      const body = created
+        ? [{ html_url: "https://github.com/acme/repo/pull/5", number: 5 }]
+        : [];
+      return new Response(JSON.stringify(body), { status: 200 });
+    }
+    created = true;
+    return new Response(
+      JSON.stringify({ html_url: "https://github.com/acme/repo/pull/5", number: 5 }),
+      { status: 201 },
+    );
+  }) as typeof fetch;
+  return calls;
+}
+
+const originalFetch = globalThis.fetch;
+
+beforeEach(() => {
+  tmpRoot = mkdtempSync(join(tmpdir(), "wb-int-"));
+  originDir = join(tmpRoot, "origin.git");
+  workDir = join(tmpRoot, "work");
+
+  execFileSync("git", ["init", "--bare", "-b", "main", originDir], { stdio: "pipe" });
+  execFileSync("git", ["clone", originDir, workDir], { stdio: "pipe" });
+  writeFileSync(join(workDir, "README.md"), "# seed\n");
+  git(workDir, ["add", "-A"]);
+  git(workDir, ["commit", "-m", "seed"]);
+  git(workDir, ["push", "-u", "origin", "main"]);
+});
+
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+  rmSync(tmpRoot, { recursive: true, force: true });
+});
+
+describe("WriteBackCoordinator against real git", () => {
+  it(
+    "pushes turn 1 to the session branch, then turn 2 (new instance) appends to it and adopts the PR",
+    async () => {
+      const apiCalls = mockGithubApi();
+
+      // ── Turn 1: the agent created a file; the review kept it. ──
+      writeFileSync(join(workDir, "notes.md"), "approved content\n");
+      const status1 = create(AgentExecutionStatusSchema, {});
+      const coord1 = makeCoordinator("exec-turn-1", statusProtoWriter(status1));
+      await coord1.finalize();
+
+      const wb1 = status1.workspaceWriteBacks[0];
+      expect(wb1.phase).toBe(WorkspaceWriteBackPhase.WORKSPACE_WRITE_BACK_PR_CREATED);
+      expect(wb1.branchName).toBe(SESSION_BRANCH);
+      expect(wb1.pullRequestNumber).toBe(5);
+
+      // The commit is on origin's session branch, authored as the agent, and
+      // main is untouched.
+      const tip1 = git(originDir, ["rev-parse", SESSION_BRANCH]).trim();
+      expect(git(originDir, ["show", `${tip1}:notes.md`])).toBe("approved content\n");
+      expect(git(originDir, ["log", "-1", "--format=%ae", SESSION_BRANCH]).trim())
+        .toBe(AGENT_GIT_AUTHOR_EMAIL);
+      expect(() => git(originDir, ["show", "main:notes.md"])).toThrow();
+
+      // ── Turn 2: a NEW coordinator (new execution, same session). The agent
+      // edited two files; the review discarded one — the reconcile snapped it
+      // back BEFORE finalize, so only the kept edit is in the tree. ──
+      writeFileSync(join(workDir, "notes.md"), "approved content\nkept edit\n");
+      writeFileSync(join(workDir, "rejected.md"), "discarded content\n");
+      rmSync(join(workDir, "rejected.md")); // the reconcile's snap-back
+
+      const status2 = create(AgentExecutionStatusSchema, {});
+      const coord2 = makeCoordinator("exec-turn-2", statusProtoWriter(status2));
+      await coord2.finalize();
+
+      const wb2 = status2.workspaceWriteBacks[0];
+      expect(wb2.phase).toBe(WorkspaceWriteBackPhase.WORKSPACE_WRITE_BACK_PR_CREATED);
+      expect(wb2.branchName, "same session branch across executions").toBe(SESSION_BRANCH);
+      expect(wb2.pullRequestNumber, "adopted, not re-created").toBe(5);
+      expect(apiCalls.filter((c) => c.method === "POST"), "exactly one PR ever created")
+        .toHaveLength(1);
+
+      // Both turns' commits are on the ONE session branch; the discarded file
+      // never reached the remote.
+      const tip2 = git(originDir, ["rev-parse", SESSION_BRANCH]).trim();
+      expect(git(originDir, ["show", `${tip2}:notes.md`])).toBe("approved content\nkept edit\n");
+      expect(() => git(originDir, ["show", `${tip2}:rejected.md`])).toThrow();
+      expect(
+        git(originDir, ["rev-list", "--count", `main..${SESSION_BRANCH}`]).trim(),
+        "one commit per approved turn",
+      ).toBe("2");
+
+      // Each commit message carries its execution id for traceability.
+      const messages = git(originDir, ["log", "--format=%s", SESSION_BRANCH]);
+      expect(messages).toContain("agent changes (exec-turn-1)");
+      expect(messages).toContain("agent changes (exec-turn-2)");
+    },
+    GIT_TEST_TIMEOUT_MS,
+  );
+
+  it(
+    "recovers the session branch from the remote after a workspace re-provision",
+    async () => {
+      mockGithubApi();
+
+      // Turn 1 establishes the branch on origin.
+      writeFileSync(join(workDir, "notes.md"), "turn one\n");
+      const coord1 = makeCoordinator(
+        "exec-a",
+        statusProtoWriter(create(AgentExecutionStatusSchema, {})),
+      );
+      await coord1.finalize();
+
+      // The sandbox is torn down; a fresh clone knows nothing of the local
+      // branch (only origin has it).
+      rmSync(workDir, { recursive: true, force: true });
+      execFileSync("git", ["clone", originDir, workDir], { stdio: "pipe" });
+      expect(git(workDir, ["branch", "--show-current"]).trim()).toBe("main");
+
+      // Turn 2 in the fresh clone must continue the SAME branch, not fork a
+      // new one from main (which would orphan turn 1's commit).
+      writeFileSync(join(workDir, "more.md"), "turn two\n");
+      const status2 = create(AgentExecutionStatusSchema, {});
+      const coord2 = makeCoordinator("exec-b", statusProtoWriter(status2));
+      await coord2.finalize();
+
+      expect(status2.workspaceWriteBacks[0].branchName).toBe(SESSION_BRANCH);
+      const tip = git(originDir, ["rev-parse", SESSION_BRANCH]).trim();
+      expect(git(originDir, ["show", `${tip}:notes.md`]), "turn 1's commit is an ancestor")
+        .toBe("turn one\n");
+      expect(git(originDir, ["show", `${tip}:more.md`])).toBe("turn two\n");
+      expect(git(originDir, ["rev-list", "--count", `main..${SESSION_BRANCH}`]).trim())
+        .toBe("2");
+    },
+    GIT_TEST_TIMEOUT_MS,
+  );
+});