@stigmer/runner 3.1.4 → 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/attachment-resolver.ts

@@ -34,7 +34,7 @@ import { join, basename } from "node:path";
 import type { Attachment } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/spec_pb";
 import type { ArtifactStorage } from "../../shared/artifact-storage.js";
 import { getPlatformDir } from "../../shared/workspace/platform-dir.js";
-import { ensureStigmerSymlink, STIGMER_LOCAL_STATE_DIR } from "./stigmer-link.js";
+import { ensureStigmerSymlink, STIGMER_LOCAL_STATE_DIR } from "../../shared/workspace/stigmer-link.js";
 
 const INPUTS_SUBDIR = "inputs";
 

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

@@ -61,7 +61,7 @@ import { resolveExecutionEnv } from "./env-resolver.js";
 import { resolveBlueprint } from "./blueprint-resolver.js";
 import { buildCursorSubAgentDefinitions } from "./subagent-config.js";
 import { resolveSkills } from "./skill-resolver.js";
-import { removeStigmerSymlink } from "./stigmer-link.js";
+import { removeStigmerSymlink } from "../../shared/workspace/stigmer-link.js";
 import { resolveAttachments } from "./attachment-resolver.js";
 import { buildEnhancedPrompt, buildReinvocationPrompt, formatInteractionModePrefix, formatImplementPlanSection } from "./prompt-builder.js";
 import { installHitlGate, removeHitlGate } from "./workspace-setup.js";
@@ -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/skill-resolver.ts

@@ -17,7 +17,7 @@ import type { ApiResourceReference } from "@stigmer/protos/ai/stigmer/commons/ap
 import type { SkillMetadata } from "./prompt-builder.js";
 import { getPlatformDir } from "../../shared/workspace/platform-dir.js";
 import { extractZipFileEntries } from "../../shared/zip-extract.js";
-import { ensureStigmerSymlink, STIGMER_LOCAL_STATE_DIR } from "./stigmer-link.js";
+import { ensureStigmerSymlink, STIGMER_LOCAL_STATE_DIR } from "../../shared/workspace/stigmer-link.js";
 
 const SKILLS_SUBDIR = "skills";
 

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

@@ -26,6 +26,10 @@ import {
   WorkspaceLockTimeoutError,
   type ReleaseWorkspaceLock,
 } from "../../shared/workspace/workspace-lock.js";
+import {
+  ensureStigmerSymlink,
+  removeStigmerSymlink,
+} from "../../shared/workspace/stigmer-link.js";
 import type { ToolOutputOffloadContext } from "../../shared/status-offload.js";
 import { publishPlanArtifact } from "../../shared/plan-artifact.js";
 import { classifyTool } from "../../shared/tool-kind.js";
@@ -41,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";
@@ -180,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,
@@ -229,6 +240,22 @@ export function createDeepAgentActivities(config: Config) {
           throw lockErr;
         }
 
+        // Bridge the workspace to the session's platform dir so the agent's
+        // file tools can read platform-mounted content (`.stigmer/inputs/…`
+        // attachments incl. the approved plan, `.stigmer/skills/…`) — the
+        // deepagents FilesystemBackend resolves paths against the workspace
+        // root and knows nothing of the LocalWorkspaceBackend's `.stigmer`
+        // routing. Two ordering invariants (see shared/workspace/stigmer-link.ts):
+        //  - AFTER the lock: the link is a tree mutation; sessions sharing one
+        //    attached directory must not re-point it under a running turn.
+        //  - BEFORE the baseline capture below: present in both the baseline
+        //    and candidate trees, the link cancels out of the file-review diff
+        //    even when the workspace's git excludes do not list `.stigmer`.
+        // Removed in cleanup() (the finally below), before the lock releases.
+        if (setup.workspaceBackend.platformDir) {
+          await ensureStigmerSymlink(gitRoot, setup.workspaceBackend.platformDir);
+        }
+
         // (1) Capture-mode resume — reconcile any DECIDED change set FIRST (this
         // drops the per-execution refs), before the next baseline re-pins them
         // (refs are executionId-keyed). Then (2) short-circuit a pure file-review
@@ -315,8 +342,10 @@ export function createDeepAgentActivities(config: Config) {
         }
 
         // Turn start (capture mode): pin the pre-turn tree + author BASELINE. Taken
-        // AFTER any reconcile above and AFTER performSetup's workspace writes, so
-        // the baseline absorbs the reconciled state and the runner-owned files.
+        // AFTER any reconcile above and AFTER performSetup's workspace writes and
+        // the `.stigmer` symlink above, so the baseline absorbs the reconciled
+        // state and the runner-owned files (the symlink then cancels out of the
+        // baseline→candidate diff).
         let captureBaselineTree = "";
         // Snapshot the sub-agent tool-call ids that exist BEFORE this turn's
         // stream, so the turn-boundary stamp scopes itself to sub-agent rows
@@ -398,9 +427,11 @@ export function createDeepAgentActivities(config: Config) {
           // Mid-run live capture (DD-32 / DD-33): attach file_change_progress
           // before each scheduled persist, throttled by the floor inside
           // captureFileChangeProgress. The substrate (git / non-git CAS / hybrid)
-          // was chosen for this turn above; deep-agent writes no runner-owned gate
-          // files into the tree, so the git slice needs no excludePaths — matching
-          // its turn-boundary candidate capture.
+          // was chosen for this turn above; the deep-agent's only runner-owned
+          // tree entry is the `.stigmer` symlink, created before the baseline
+          // so it appears identically in every capture and cancels out of the
+          // diff — the git slice therefore needs no excludePaths, matching its
+          // turn-boundary candidate capture.
           beforePersist: async (status) => {
             if (!progressSubstrate) return;
             await captureFileChangeProgress({
@@ -928,5 +959,12 @@ async function cleanup(setup: SetupResult | null): Promise<void> {
       console.warn("[ExecuteDeepAgent] MCP connection cleanup failed:", err);
     }
   }
+
+  // Drop the workspace→platform `.stigmer` symlink so an attached repo is
+  // left untouched between turns (issue #173 semantics; a multi-turn session
+  // recreates it next turn). Runs in the activity finally, BEFORE the
+  // workspace lock releases, so the next queued turn baselines a clean tree.
+  // Best-effort and symlink-only: a real `.stigmer` directory is never removed.
+  await removeStigmerSymlink(setup.workspaceBackend.rootDir);
 }
 

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/filereview/git-substrate.ts

@@ -97,6 +97,10 @@ export function captureRef(executionId: string): string {
  * garbage collection — but `git commit-tree` still requires an author/committer,
  * and the repo may have no user.name/email configured. Supplied via env so we
  * never mutate the repo's config.
+ *
+ * Deliberately distinct from the public agent identity in
+ * `../workspace/git-identity.ts`, which authors the write-back commits that
+ * land on real branches and pull requests.
  */
 const SNAPSHOT_IDENTITY_ENV: Record<string, string> = {
   GIT_AUTHOR_NAME: "stigmer-runner",