@stigmer/runner 3.1.5 → 3.1.7

package/dist/shared/workspace/writeback-coordinator.js

@@ -0,0 +1,393 @@
+/**
+ * Git write-back coordinator for workspace entries.
+ *
+ * Commits the workspace's changes to the session's write-back branch, pushes,
+ * and keeps one pull request open per session. The branch and PR are
+ * SESSION-scoped (`stigmer/<session-id>`): a session is one workstream, so
+ * every approved turn appends commits to the same branch and the same PR —
+ * mirroring how Cursor cloud agents and Codex present a session's deliverable.
+ * Execution-scoped branches were a modeling bug: each turn branched off the
+ * previous turn's branch, leaving a trail of superseded PRs.
+ *
+ * Because the branch outlives any single execution, every git/GitHub step is
+ * idempotent across coordinator instances: the branch is checked out if it
+ * 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.
+ *
+ * Concurrency: one mutex per workspace entry serializes git operations.
+ */
+import { create } from "@bufbuild/protobuf";
+import { WorkspaceWriteBackSchema, } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/writeback_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 { SourceType } from "./types.js";
+import { gitCommitAsAgent } from "./git-identity.js";
+const WRITE_BACK_ENABLED_MODES = new Set([
+    GitWriteBackMode.GIT_WRITE_BACK_MODE_UNSPECIFIED,
+    GitWriteBackMode.GIT_WRITE_BACK_BRANCH_AND_PR,
+]);
+const GITHUB_API = "https://api.github.com";
+export class WriteBackCoordinator {
+    statusWriter;
+    executionId;
+    workspaceBackend;
+    branchName;
+    /**
+     * Token for the GitHub PR API, plumbed explicitly from the resolved
+     * execution env (the same GITHUB_TOKEN that credentials the clone/push).
+     * Empty when the session has none — commit/push may still succeed via the
+     * repo-local credential store, so an empty token degrades to PUSHED with an
+     * actionable error rather than blocking the write-back.
+     */
+    githubToken;
+    eligible = new Map();
+    state = new Map();
+    locks = new Map();
+    constructor(opts) {
+        this.statusWriter = opts.statusWriter;
+        this.executionId = opts.executionId;
+        this.workspaceBackend = opts.workspaceBackend;
+        this.githubToken = opts.githubToken;
+        // The FULL session id: a truncated ULID is timestamp-dominated, so two
+        // sessions created near-simultaneously would collide on a short prefix.
+        this.branchName = `stigmer/${opts.sessionId}`;
+        this.initEligibleEntries(opts.provisionResults, opts.workspaceEntries);
+    }
+    get hasEligibleEntries() {
+        return this.eligible.size > 0;
+    }
+    /**
+     * 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) {
+        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.
+     */
+    async finalize() {
+        for (const entryName of this.eligible.keys()) {
+            try {
+                await this.withLock(entryName, () => this.writeBackEntry(entryName));
+            }
+            catch (err) {
+                console.warn(`[WriteBack] execution=${this.executionId} entry=${entryName} — ` +
+                    `finalize error: ${err}`);
+            }
+        }
+    }
+    // ── Initialization ──────────────────────────────────────────────────
+    initEligibleEntries(provisionResults, workspaceEntries) {
+        const modeMap = new Map();
+        for (const entry of workspaceEntries) {
+            const source = entry.source;
+            if (source?.source.case === "gitRepo") {
+                modeMap.set(entry.name, source.source.value.writeBackMode);
+            }
+        }
+        for (const pr of provisionResults) {
+            if (pr.sourceType !== SourceType.GIT_REPO)
+                continue;
+            if (!pr.gitMetadata)
+                continue;
+            if (!pr.gitMetadata.gitCredentialsConfigured)
+                continue;
+            const mode = modeMap.get(pr.entryName) ?? GitWriteBackMode.GIT_WRITE_BACK_MODE_UNSPECIFIED;
+            if (!WRITE_BACK_ENABLED_MODES.has(mode))
+                continue;
+            this.eligible.set(pr.entryName, {
+                provisionResult: pr,
+                baseBranch: pr.gitMetadata.branch,
+                rootDir: pr.rootDir,
+                entryName: pr.entryName,
+            });
+            this.state.set(pr.entryName, {
+                branchReady: false,
+                prCreated: false,
+                prUrl: "",
+                prNumber: 0,
+                commitCount: 0,
+                lastCommitSha: "",
+                githubOwner: "",
+                githubRepo: "",
+            });
+        }
+        if (this.eligible.size > 0) {
+            console.log(`[WriteBack] execution=${this.executionId} — coordinator initialized with ` +
+                `${this.eligible.size} eligible workspace(s): ${[...this.eligible.keys()].join(", ")}`);
+        }
+    }
+    // ── Path Resolution ─────────────────────────────────────────────────
+    resolveEntry(path) {
+        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 ───────────────────────────────────────────
+    /**
+     * One write-back cycle for an entry: branch → commit → push → PR → status.
+     *
+     * Failure semantics are split by what actually succeeded (the phases are
+     * facts, not a single verdict):
+     *  - branch/commit/push failure → FAILED (the work did not reach GitHub);
+     *  - PR failure after a successful push → PUSHED with the PR error carried
+     *    in `error` — the branch is live and usable, and saying "failed" for a
+     *    pushed branch would be dishonest (the original cloud regression).
+     */
+    async writeBackEntry(entryName) {
+        const entry = this.eligible.get(entryName);
+        const entryState = this.state.get(entryName);
+        const rootDir = entry.rootDir;
+        const exec = async (cmd) => {
+            return this.workspaceBackend.execute(`cd ${rootDir} && ${cmd}`);
+        };
+        try {
+            const hasChanges = await this.hasChanges(exec);
+            if (!hasChanges)
+                return;
+            if (!entryState.branchReady) {
+                await this.ensureBranch(entryName, entryState, exec);
+            }
+            await this.commitAndPush(entryName, entryState, exec);
+        }
+        catch (err) {
+            console.warn(`[WriteBack] execution=${this.executionId} entry=${entryName} — ` +
+                `commit/push error: ${err}`);
+            const wb = create(WorkspaceWriteBackSchema, {
+                workspaceEntryName: entryName,
+                baseBranch: entry.baseBranch,
+                branchName: entryState.branchReady ? this.branchName : "",
+                phase: WorkspaceWriteBackPhase.WORKSPACE_WRITE_BACK_FAILED,
+                error: String(err),
+            });
+            if (entryState.prCreated) {
+                wb.pullRequestUrl = entryState.prUrl;
+                wb.pullRequestNumber = entryState.prNumber;
+            }
+            this.statusWriter.addWriteBack(wb);
+            return;
+        }
+        let prError = "";
+        if (!entryState.prCreated) {
+            try {
+                await this.ensurePr(entryName, entryState, entry);
+            }
+            catch (err) {
+                console.warn(`[WriteBack] execution=${this.executionId} entry=${entryName} — ` +
+                    `PR error (branch is pushed): ${err}`);
+                prError = String(err);
+            }
+        }
+        await this.updateStatus(entryName, entryState, entry, exec, prError);
+    }
+    // ── Git Operations ──────────────────────────────────────────────────
+    async hasChanges(exec) {
+        const diff = await exec("git diff --stat").catch(() => "");
+        const staged = await exec("git diff --cached --stat").catch(() => "");
+        if (diff.trim() || staged.trim())
+            return true;
+        const untracked = await exec("git ls-files --others --exclude-standard").catch(() => "");
+        return untracked.trim().length > 0;
+    }
+    /**
+     * Put the working tree on the session branch, wherever the branch already
+     * lives. Three cases, in order:
+     *  1. HEAD is already on it — a later turn in the same workspace (the common
+     *     multi-turn path; the previous turn's cycle left HEAD there).
+     *  2. It exists locally or on the remote — a re-provisioned workspace whose
+     *     clone lost the local branch. Checked out (tracking the remote ref when
+     *     that is the only copy). The checkout carries this turn's uncommitted
+     *     changes along; if they collide with the branch's prior commits git
+     *     refuses, and the error surfaces as an honest FAILED record — we never
+     *     force (-B) over the session's pushed history.
+     *  3. Neither — the session's first write-back creates it.
+     */
+    async ensureBranch(entryName, entryState, exec) {
+        const current = (await exec("git branch --show-current").catch(() => "")).trim();
+        if (current === this.branchName) {
+            entryState.branchReady = true;
+            return;
+        }
+        const localRef = await exec(`git rev-parse --verify --quiet refs/heads/${this.branchName}`).then((out) => out.trim(), () => "");
+        if (localRef) {
+            await exec(`git checkout ${this.branchName}`);
+        }
+        else {
+            const remoteRef = (await exec(`git ls-remote --heads origin ${this.branchName}`).catch(() => "")).trim();
+            if (remoteRef) {
+                await exec(`git fetch origin ${this.branchName}`);
+                await exec(`git checkout -b ${this.branchName} origin/${this.branchName}`);
+            }
+            else {
+                await exec(`git checkout -b ${this.branchName}`);
+            }
+        }
+        entryState.branchReady = true;
+        console.log(`[WriteBack] execution=${this.executionId} entry=${entryName} — ` +
+            `on branch ${this.branchName}`);
+    }
+    async commitAndPush(entryName, entryState, exec) {
+        await exec("git add -A");
+        // Committed as the agent identity: the cloud sandbox has no git identity
+        // configured (a bare commit fails with "Author identity unknown"), and in
+        // local mode the agent's work should not be attributed to the host user.
+        // The execution id in the message links each commit back to its turn.
+        await exec(gitCommitAsAgent(`agent changes (${this.executionId})`));
+        entryState.commitCount++;
+        const shaOutput = await exec("git rev-parse HEAD");
+        entryState.lastCommitSha = shaOutput.trim();
+        // Always -u: idempotent whether this push creates the remote branch or
+        // appends to it, and it (re-)establishes tracking after a re-provision.
+        await exec(`git push -u origin ${this.branchName}`);
+        console.log(`[WriteBack] execution=${this.executionId} entry=${entryName} — ` +
+            `commit pushed to ${this.branchName} (sha=${entryState.lastCommitSha.slice(0, 12)})`);
+    }
+    // ── GitHub PR ───────────────────────────────────────────────────────
+    /**
+     * Ensure one open PR exists for the session branch: adopt an already-open
+     * one (a prior turn — possibly a prior coordinator instance — created it),
+     * else create it. Runs only after a successful push; a thrown error here is
+     * reported as PUSHED + error, never FAILED.
+     */
+    async ensurePr(entryName, entryState, entry) {
+        const meta = entry.provisionResult.gitMetadata;
+        if (!entryState.githubOwner) {
+            const { owner, repo } = parseGithubRepo(meta.repoUrl);
+            entryState.githubOwner = owner;
+            entryState.githubRepo = repo;
+        }
+        if (!this.githubToken) {
+            throw new Error("No GitHub token available to open a pull request. The branch " +
+                `'${this.branchName}' was pushed — open the PR manually, or configure ` +
+                "GITHUB_TOKEN for the session so PRs are created automatically.");
+        }
+        const existing = await this.findOpenPr(entryState);
+        if (existing) {
+            entryState.prCreated = true;
+            entryState.prUrl = existing.url;
+            entryState.prNumber = existing.number;
+            console.log(`[WriteBack] execution=${this.executionId} entry=${entryName} — ` +
+                `adopted open PR #${existing.number}: ${existing.url}`);
+            return;
+        }
+        const shortSessionId = this.branchName.replace(/^stigmer\//, "");
+        const prBody = `Automated pull request from a Stigmer agent session.\n\n` +
+            `**Session:** \`${shortSessionId}\`\n` +
+            `**Workspace:** \`${entryName}\`\n\n` +
+            `Each approved turn appends its commits to this pull request.\n`;
+        const resp = await fetch(`${GITHUB_API}/repos/${entryState.githubOwner}/${entryState.githubRepo}/pulls`, {
+            method: "POST",
+            headers: this.githubHeaders(),
+            body: JSON.stringify({
+                title: `Stigmer agent changes (${shortSessionId})`,
+                body: prBody,
+                head: this.branchName,
+                base: entry.baseBranch,
+            }),
+        });
+        if (!resp.ok) {
+            const body = await resp.text();
+            throw new Error(`GitHub API error (HTTP ${resp.status}): ${body}`);
+        }
+        const data = await resp.json();
+        entryState.prCreated = true;
+        entryState.prUrl = data.html_url ?? "";
+        entryState.prNumber = data.number ?? 0;
+        console.log(`[WriteBack] execution=${this.executionId} entry=${entryName} — ` +
+            `PR #${entryState.prNumber} created: ${entryState.prUrl}`);
+    }
+    /** The open PR whose head is the session branch, if one exists. */
+    async findOpenPr(entryState) {
+        const head = `${entryState.githubOwner}:${this.branchName}`;
+        const resp = await fetch(`${GITHUB_API}/repos/${entryState.githubOwner}/${entryState.githubRepo}` +
+            `/pulls?head=${encodeURIComponent(head)}&state=open`, { headers: this.githubHeaders() });
+        if (!resp.ok) {
+            const body = await resp.text();
+            throw new Error(`GitHub API error listing PRs (HTTP ${resp.status}): ${body}`);
+        }
+        const data = await resp.json();
+        const pr = data[0];
+        if (!pr)
+            return null;
+        return { url: pr.html_url ?? "", number: pr.number ?? 0 };
+    }
+    githubHeaders() {
+        return {
+            "Authorization": `Bearer ${this.githubToken}`,
+            "Accept": "application/vnd.github+json",
+            "Content-Type": "application/json",
+        };
+    }
+    // ── Status Reporting ────────────────────────────────────────────────
+    async updateStatus(entryName, entryState, entry, exec, prError) {
+        const summaryOutput = await exec(`git diff --stat ${entry.baseBranch}...HEAD`).catch(() => "");
+        const phase = entryState.prCreated
+            ? WorkspaceWriteBackPhase.WORKSPACE_WRITE_BACK_PR_CREATED
+            : WorkspaceWriteBackPhase.WORKSPACE_WRITE_BACK_PUSHED;
+        const wb = create(WorkspaceWriteBackSchema, {
+            workspaceEntryName: entryName,
+            branchName: this.branchName,
+            baseBranch: entry.baseBranch,
+            commitSha: entryState.lastCommitSha,
+            pullRequestUrl: entryState.prUrl,
+            pullRequestNumber: entryState.prNumber,
+            diffSummary: summaryOutput.trim(),
+            phase,
+            // Non-empty only for a PUSHED record whose PR step failed: the branch
+            // is live, and the error tells the user why there is no PR link yet.
+            error: prError,
+        });
+        this.statusWriter.addWriteBack(wb);
+    }
+    // ── Concurrency ─────────────────────────────────────────────────────
+    async withLock(entryName, fn) {
+        const existing = this.locks.get(entryName) ?? Promise.resolve();
+        const next = existing.then(fn, fn);
+        this.locks.set(entryName, next);
+        await next;
+    }
+}
+// ── Helpers ───────────────────────────────────────────────────────────
+/**
+ * Extract GitHub owner and repo from a clone URL.
+ * Supports HTTPS (with or without .git) and SSH formats.
+ */
+export function parseGithubRepo(repoUrl) {
+    const httpsMatch = repoUrl.match(/github\.com[/:]([^/]+)\/([^/.]+?)(?:\.git)?$/);
+    if (httpsMatch) {
+        return { owner: httpsMatch[1], repo: httpsMatch[2] };
+    }
+    throw new Error(`Cannot parse GitHub owner/repo from URL: ${repoUrl}`);
+}
+//# sourceMappingURL=writeback-coordinator.js.map

package/dist/shared/workspace/writeback-coordinator.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stigmer/runner",
-  "version": "3.1.5",
+  "version": "3.1.7",
   "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.5",
+    "@stigmer/protos": "3.1.7",
     "@temporalio/activity": "^1.11.0",
     "@temporalio/client": "^1.11.0",
     "@temporalio/common": "^1.11.0",

package/src/activities/discover-mcp-server.ts

@@ -24,6 +24,7 @@ import { activityStarted, activityFinished } from "../idle-watchdog.js";
 import { StigmerClient } from "../client/stigmer-client.js";
 import { mcpServerToResolved } from "../shared/mcp-resolver.js";
 import { toMcpClientConfig } from "../shared/mcp-manager.js";
+import { detectOAuthChallenge } from "../shared/mcp-oauth-detect.js";
 import type { McpServer } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
 import type { Config } from "../config.js";
 
@@ -374,6 +375,14 @@ async function connectAndDiscover(
         );
       }
     });
+  } catch (err) {
+    // The MCP client surfaces a 401 OAuth challenge as an opaque aggregate
+    // ("unhandled errors in a TaskGroup"). For HTTP servers, re-probe once to
+    // see if the endpoint is actually asking for OAuth and, if so, replace the
+    // useless error with an actionable one. Non-OAuth failures rethrow as-is.
+    const oauthError = await classifyHttpOAuthFailure(slug, connectionConfig);
+    if (oauthError) throw oauthError;
+    throw err;
   } finally {
     await client.close().catch((err: unknown) => {
       console.warn(
@@ -386,6 +395,22 @@ async function connectAndDiscover(
   return { tools, resourceTemplates };
 }
 
+/**
+ * If the server uses HTTP transport, probe its endpoint to classify a discovery
+ * failure as an OAuth challenge. Returns the actionable error to throw, or
+ * `null` for stdio servers and non-OAuth failures (caller rethrows original).
+ */
+async function classifyHttpOAuthFailure(
+  slug: string,
+  connectionConfig: ReturnType<typeof toMcpClientConfig>,
+): Promise<Error | null> {
+  const connection = connectionConfig[slug];
+  if (!connection || connection.transport !== "http" || !connection.url) {
+    return null;
+  }
+  return detectOAuthChallenge(connection.url, connection.headers, slug);
+}
+
 async function withTimeout<T>(
   ms: number,
   serverSlug: string,

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);