@ricsam/r5d-worker 0.0.81 → 0.0.82

package/dist/mjs/main.mjs

@@ -99,6 +99,10 @@ const DEFAULT_READ_MAX_BYTES = 5e4;
 const MAX_LINE_LENGTH = 2e3;
 const WORKSPACE_GIT_QUIET_MS = 5e3;
 const WORKSPACE_GIT_PERIODIC_MS = 6e4;
+const PTY_INPUT_BUSY_GRACE_MS = 3e3;
+const PTY_FOREGROUND_POLL_MS = 1e3;
+const PTY_FOREGROUND_IDLE_ENABLED = process.env.R5D_PTY_FOREGROUND_IDLE !== "0";
+const PTY_TMP_PATH_PREFIX = "r5d-worker-tmp://";
 const activeProcesses = /* @__PURE__ */ new Map();
 const credentialBearingProcessGroups = /* @__PURE__ */ new Map();
 const credentialBearingProcessGroupTargets = /* @__PURE__ */ new Map();
@@ -156,6 +160,106 @@ function assertWorkerChildAdmission(input) {
     throw new StaleWorkerAdmissionError();
   }
 }
+function pathIsInsideRoot(rootPath, candidatePath) {
+  const relative = path.relative(rootPath, candidatePath);
+  return relative === "" || !relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative);
+}
+function resolvePtyEnvFilePath(requestedPath, temporaryRoot = os.tmpdir()) {
+  const canonicalTemporaryRoot = fs.realpathSync.native(temporaryRoot);
+  if (requestedPath.startsWith(PTY_TMP_PATH_PREFIX)) {
+    const filename = requestedPath.slice(PTY_TMP_PATH_PREFIX.length);
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$/.test(filename)) {
+      throw new Error("PTY environment file temporary token must contain one safe filename");
+    }
+    return path.join(canonicalTemporaryRoot, filename);
+  }
+  if (!path.isAbsolute(requestedPath)) {
+    throw new Error(`PTY environment file path must be absolute or use ${PTY_TMP_PATH_PREFIX}`);
+  }
+  const resolvedPath = path.resolve(requestedPath);
+  const canonicalParent = fs.realpathSync.native(path.dirname(resolvedPath));
+  const canonicalPath = path.join(canonicalParent, path.basename(resolvedPath));
+  if (!pathIsInsideRoot(canonicalTemporaryRoot, canonicalPath) || canonicalPath === canonicalTemporaryRoot) {
+    throw new Error(`PTY environment file path must be inside ${canonicalTemporaryRoot}`);
+  }
+  return canonicalPath;
+}
+function removePtyEnvFiles(paths) {
+  for (const filePath of paths) {
+    try {
+      fs.rmSync(filePath, { force: true });
+    } catch (error) {
+      process.stderr.write(
+        `[r5d-worker] failed to remove PTY environment file ${filePath}: ${error instanceof Error ? error.message : String(error)}
+`
+      );
+    }
+  }
+}
+function stagePtyEnvFiles(envFiles, temporaryRoot = os.tmpdir()) {
+  const staged = { paths: [], resolvedByRequestedPath: /* @__PURE__ */ new Map() };
+  try {
+    for (const envFile of envFiles ?? []) {
+      if (!envFile || typeof envFile.path !== "string" || typeof envFile.content !== "string") {
+        throw new Error("PTY environment files require string path and content values");
+      }
+      if (envFile.mode !== void 0 && envFile.mode !== 384) {
+        throw new Error("PTY environment files must use mode 0600");
+      }
+      const resolvedPath = resolvePtyEnvFilePath(envFile.path, temporaryRoot);
+      if (staged.resolvedByRequestedPath.has(envFile.path) || staged.paths.includes(resolvedPath)) {
+        throw new Error(`Duplicate PTY environment file path: ${envFile.path}`);
+      }
+      const descriptor = fs.openSync(
+        resolvedPath,
+        fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | (typeof fs.constants.O_NOFOLLOW === "number" ? fs.constants.O_NOFOLLOW : 0),
+        384
+      );
+      staged.paths.push(resolvedPath);
+      staged.resolvedByRequestedPath.set(envFile.path, resolvedPath);
+      try {
+        fs.writeFileSync(descriptor, envFile.content, "utf8");
+        fs.fchmodSync(descriptor, 384);
+        fs.fsyncSync(descriptor);
+      } finally {
+        fs.closeSync(descriptor);
+      }
+    }
+    return staged;
+  } catch (error) {
+    removePtyEnvFiles(staged.paths);
+    throw error;
+  }
+}
+function resolvePtyEnvFileReferences(env, staged) {
+  return Object.fromEntries(Object.entries(env).map(([name, value]) => [name, staged.resolvedByRequestedPath.get(value) ?? value]));
+}
+function workerCommandHasWorkspaceEffect(message) {
+  return message.workspaceEffect !== "none";
+}
+function workerPtyIsWorkspaceBusy(pty, now = Date.now(), foregroundIdleEnabled = PTY_FOREGROUND_IDLE_ENABLED) {
+  return !foregroundIdleEnabled || pty.foregroundBusy || now - pty.lastInputAt < PTY_INPUT_BUSY_GRACE_MS;
+}
+function parseLinuxPtyForegroundBusy(stat) {
+  const commandEnd = stat.lastIndexOf(")");
+  if (commandEnd < 0) return null;
+  const fields = stat.slice(commandEnd + 1).trim().split(/\s+/);
+  const processGroup = Number(fields[2]);
+  const foregroundProcessGroup = Number(fields[5]);
+  if (!Number.isSafeInteger(processGroup) || processGroup <= 0 || !Number.isSafeInteger(foregroundProcessGroup)) return null;
+  return foregroundProcessGroup !== processGroup;
+}
+const workerPtyTestHarness = {
+  temporaryPathPrefix: PTY_TMP_PATH_PREFIX,
+  inputBusyGraceMs: PTY_INPUT_BUSY_GRACE_MS,
+  resolveEnvFilePath: resolvePtyEnvFilePath,
+  stageEnvFiles: stagePtyEnvFiles,
+  removeEnvFiles: removePtyEnvFiles,
+  resolveEnvFileReferences: resolvePtyEnvFileReferences,
+  commandHasWorkspaceEffect: workerCommandHasWorkspaceEffect,
+  ptyIsWorkspaceBusy: workerPtyIsWorkspaceBusy,
+  parseLinuxForegroundBusy: parseLinuxPtyForegroundBusy
+};
 function defaultConfigPath() {
   return path.join(os.homedir(), ".config", "r5d", "r5dctl", "config.json");
 }
@@ -2337,7 +2441,9 @@ async function executeCommand(input) {
     });
     spawnedProcess = subprocess;
     credentialBearingProcessGroups.set(subprocess.pid, subprocess);
-    credentialBearingProcessGroupTargets.set(subprocess.pid, input.resolvedTarget.target);
+    if (workerCommandHasWorkspaceEffect(input.message)) {
+      credentialBearingProcessGroupTargets.set(subprocess.pid, input.resolvedTarget.target);
+    }
     activeProcesses.set(input.message.runId, {
       process: subprocess,
       target: input.resolvedTarget.target,
@@ -2348,7 +2454,8 @@ async function executeCommand(input) {
       argv: input.message.argv,
       command: input.message.argv.join(" "),
       cwd,
-      startedAt: (/* @__PURE__ */ new Date()).toISOString()
+      startedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      ...input.message.workspaceEffect === "none" ? { workspaceEffect: "none" } : {}
     });
     if (input.message.timeoutMs) {
       timeout = setTimeout(() => {
@@ -2434,7 +2541,9 @@ async function executeStreamingCommand(input) {
     });
     spawnedProcess = subprocess;
     credentialBearingProcessGroups.set(subprocess.pid, subprocess);
-    credentialBearingProcessGroupTargets.set(subprocess.pid, input.resolvedTarget.target);
+    if (workerCommandHasWorkspaceEffect(input.message)) {
+      credentialBearingProcessGroupTargets.set(subprocess.pid, input.resolvedTarget.target);
+    }
     activeProcesses.set(input.message.runId, {
       process: subprocess,
       target: input.resolvedTarget.target,
@@ -2447,7 +2556,8 @@ async function executeStreamingCommand(input) {
       command: input.message.command,
       cwd,
       startedAt: (/* @__PURE__ */ new Date()).toISOString(),
-      ...interactive ? { interactive: true, stdin: subprocess.stdin } : {}
+      ...interactive ? { interactive: true, stdin: subprocess.stdin } : {},
+      ...input.message.workspaceEffect === "none" ? { workspaceEffect: "none" } : {}
     });
     started = true;
     sendWorkerMessage(input.ws, {
@@ -2494,7 +2604,8 @@ async function executeStreamingCommand(input) {
       runId: input.message.runId,
       exitCode,
       durationMs: Date.now() - startedAt,
-      ...timedOut ? { timedOut: true } : {}
+      ...timedOut ? { timedOut: true } : {},
+      ...input.message.workspaceEffect === "none" ? { workspaceEffect: "none" } : {}
     };
     pendingProcessTerminals.set(input.message.runId, terminal);
     sendWorkerMessage(input.ws, terminal);
@@ -2506,7 +2617,8 @@ async function executeStreamingCommand(input) {
         type: "exec_error",
         runId: input.message.runId,
         error: message,
-        durationMs: Date.now() - startedAt
+        durationMs: Date.now() - startedAt,
+        ...input.message.workspaceEffect === "none" ? { workspaceEffect: "none" } : {}
       };
       pendingProcessTerminals.set(input.message.runId, terminal);
       sendWorkerMessage(input.ws, terminal);
@@ -2587,7 +2699,8 @@ function buildActiveProcessReports() {
     command: active.command,
     ...active.cwd ? { cwd: active.cwd } : {},
     startedAt: active.startedAt,
-    ...active.interactive ? { interactive: true } : {}
+    ...active.interactive ? { interactive: true } : {},
+    ...active.workspaceEffect === "none" ? { workspaceEffect: "none" } : {}
   }));
 }
 function sendActiveProcessReport(ws) {
@@ -2599,8 +2712,13 @@ function sendActiveProcessReport(ws) {
 const PTY_BRIDGE_SCRIPT = String.raw`
 const readline = require("node:readline");
 const nodePty = require("node-pty");
+const fs = require("node:fs");
+const { execFile } = require("node:child_process");
 
 let ptyProcess = null;
+let foregroundTimer = null;
+let foregroundPollInFlight = false;
+let lastForegroundBusy = null;
 
 function send(message, callback) {
   process.stdout.write(JSON.stringify(message) + "\n", callback);
@@ -2610,6 +2728,46 @@ function decode(data) {
   return Buffer.from(data, "base64").toString("utf8");
 }
 
+function emitForeground(busy) {
+  if (busy === lastForegroundBusy) return;
+  lastForegroundBusy = busy;
+  send({ type: "foreground", busy });
+}
+
+function linuxForegroundBusy(pid) {
+  const stat = fs.readFileSync("/proc/" + pid + "/stat", "utf8");
+  const commandEnd = stat.lastIndexOf(")");
+  if (commandEnd < 0) throw new Error("invalid /proc stat");
+  const fields = stat.slice(commandEnd + 1).trim().split(/\s+/);
+  const processGroup = Number(fields[2]);
+  const foregroundProcessGroup = Number(fields[5]);
+  if (!Number.isSafeInteger(processGroup) || processGroup <= 0 || !Number.isSafeInteger(foregroundProcessGroup)) {
+    throw new Error("invalid process group fields");
+  }
+  return foregroundProcessGroup !== processGroup;
+}
+
+function pollForeground() {
+  if (!ptyProcess || !Number.isSafeInteger(ptyProcess.pid) || ptyProcess.pid <= 0) return;
+  if (process.platform === "linux") {
+    try {
+      emitForeground(linuxForegroundBusy(ptyProcess.pid));
+    } catch {
+      emitForeground(true);
+    }
+    return;
+  }
+  if (process.platform !== "darwin" || foregroundPollInFlight) return;
+  foregroundPollInFlight = true;
+  const pid = ptyProcess.pid;
+  execFile("/bin/ps", ["-o", "tpgid=", "-p", String(pid)], (error, stdout) => {
+    foregroundPollInFlight = false;
+    if (!ptyProcess || ptyProcess.pid !== pid) return;
+    const foregroundProcessGroup = Number(String(stdout).trim());
+    emitForeground(Boolean(error) || !Number.isSafeInteger(foregroundProcessGroup) || foregroundProcessGroup !== pid);
+  });
+}
+
 const rl = readline.createInterface({ input: process.stdin });
 
 rl.on("line", (line) => {
@@ -2628,9 +2786,14 @@ rl.on("line", (line) => {
         send({ type: "output", data: Buffer.from(data, "utf8").toString("base64") });
       });
       ptyProcess.onExit((event) => {
+        if (foregroundTimer) clearInterval(foregroundTimer);
+        foregroundTimer = null;
         send({ type: "exit", exitCode: event.exitCode, signal: event.signal }, () => process.exit(0));
       });
-      send({ type: "opened" });
+      send({ type: "opened", pid: ptyProcess.pid });
+      pollForeground();
+      foregroundTimer = setInterval(pollForeground, ${PTY_FOREGROUND_POLL_MS});
+      foregroundTimer.unref();
       return;
     }
 
@@ -2723,7 +2886,11 @@ function createNodePtyBridge(options) {
   };
   const handleEvent = (event) => {
     if (event.type === "opened") {
-      options.onOpened();
+      options.onOpened(event.pid);
+      return;
+    }
+    if (event.type === "foreground") {
+      options.onForeground(event.busy);
       return;
     }
     if (event.type === "output") {
@@ -2804,6 +2971,9 @@ function createNodePtyBridge(options) {
     }
   };
 }
+const workerPtyBridgeTestHarness = {
+  create: createNodePtyBridge
+};
 function resolveHostShell(command, platform = process.platform) {
   if (platform === "win32") {
     const file2 = process.env.COMSPEC || "powershell.exe";
@@ -2839,64 +3009,90 @@ async function openPty(input) {
     }
   });
   input.assertAdmission();
-  const ptyProcess = createNodePtyBridge({
-    file: shell.file,
-    args: shell.args,
-    ptyOptions: {
-      name: "xterm-256color",
-      cols: Math.max(1, Math.min(Math.floor(input.message.cols || 80), 500)),
-      rows: Math.max(1, Math.min(Math.floor(input.message.rows || 24), 500)),
-      cwd: input.resolvedTarget.rootPath,
-      env: workerChildProcessEnvironment([githubProcessEnv(), input.message.env ?? {}, planProcessEnv, targetProcessEnv, shell.env ?? {}])
-    },
-    onOpened: () => {
-      sendWorkerMessage(input.ws, {
-        type: "pty_opened",
-        requestId: input.message.requestId,
-        ptyId: input.message.ptyId
-      });
-    },
-    onOutput: (data) => {
-      outputCoalescer.push(data);
-    },
-    onExit: (event) => {
-      outputCoalescer.flush();
-      input.releaseWorkspaceMutation?.();
-      activePtys.delete(input.message.ptyId);
-      input.onTerminal?.();
-      sendWorkerMessage(input.ws, {
-        type: "pty_exit",
-        ptyId: input.message.ptyId,
-        exitCode: event.exitCode,
-        signal: event.signal
-      });
-    },
-    onError: (error) => {
-      outputCoalescer.flush();
-      input.releaseWorkspaceMutation?.();
-      activePtys.delete(input.message.ptyId);
-      input.onTerminal?.();
-      sendWorkerMessage(input.ws, {
-        type: "pty_error",
-        requestId: input.message.requestId,
-        ptyId: input.message.ptyId,
-        error: error.message
-      });
-    },
-    onTerminationError: (error) => {
-      sendWorkerMessage(input.ws, {
-        type: "pty_error",
-        requestId: input.message.requestId,
-        ptyId: input.message.ptyId,
-        error: error.message
-      });
-    }
-  });
-  activePtys.set(input.message.ptyId, {
-    ...ptyProcess,
-    target: input.resolvedTarget.target,
-    ...input.releaseWorkspaceMutation ? { releaseWorkspaceMutation: input.releaseWorkspaceMutation } : {}
-  });
+  const stagedEnvFiles = stagePtyEnvFiles(input.message.envFiles);
+  let envFilesRemoved = false;
+  const cleanupEnvFiles = () => {
+    if (envFilesRemoved) return;
+    envFilesRemoved = true;
+    removePtyEnvFiles(stagedEnvFiles.paths);
+  };
+  try {
+    const ptyProcess = createNodePtyBridge({
+      file: shell.file,
+      args: shell.args,
+      ptyOptions: {
+        name: "xterm-256color",
+        cols: Math.max(1, Math.min(Math.floor(input.message.cols || 80), 500)),
+        rows: Math.max(1, Math.min(Math.floor(input.message.rows || 24), 500)),
+        cwd: input.resolvedTarget.rootPath,
+        env: workerChildProcessEnvironment([
+          githubProcessEnv(),
+          resolvePtyEnvFileReferences(input.message.env ?? {}, stagedEnvFiles),
+          planProcessEnv,
+          targetProcessEnv,
+          shell.env ?? {}
+        ])
+      },
+      onOpened: () => {
+        sendWorkerMessage(input.ws, {
+          type: "pty_opened",
+          requestId: input.message.requestId,
+          ptyId: input.message.ptyId
+        });
+      },
+      onForeground: (busy) => {
+        const activePty = activePtys.get(input.message.ptyId);
+        if (activePty && (busy || input.message.command === void 0)) activePty.foregroundBusy = busy;
+      },
+      onOutput: (data) => {
+        outputCoalescer.push(data);
+      },
+      onExit: (event) => {
+        outputCoalescer.flush();
+        input.releaseWorkspaceMutation?.();
+        activePtys.delete(input.message.ptyId);
+        cleanupEnvFiles();
+        input.onTerminal?.();
+        sendWorkerMessage(input.ws, {
+          type: "pty_exit",
+          ptyId: input.message.ptyId,
+          exitCode: event.exitCode,
+          signal: event.signal
+        });
+      },
+      onError: (error) => {
+        outputCoalescer.flush();
+        input.releaseWorkspaceMutation?.();
+        activePtys.delete(input.message.ptyId);
+        cleanupEnvFiles();
+        input.onTerminal?.();
+        sendWorkerMessage(input.ws, {
+          type: "pty_error",
+          requestId: input.message.requestId,
+          ptyId: input.message.ptyId,
+          error: error.message
+        });
+      },
+      onTerminationError: (error) => {
+        sendWorkerMessage(input.ws, {
+          type: "pty_error",
+          requestId: input.message.requestId,
+          ptyId: input.message.ptyId,
+          error: error.message
+        });
+      }
+    });
+    activePtys.set(input.message.ptyId, {
+      ...ptyProcess,
+      target: input.resolvedTarget.target,
+      foregroundBusy: true,
+      lastInputAt: 0,
+      ...input.releaseWorkspaceMutation ? { releaseWorkspaceMutation: input.releaseWorkspaceMutation } : {}
+    });
+  } catch (error) {
+    cleanupEnvFiles();
+    throw error;
+  }
 }
 function writePty(ws, message) {
   const ptyProcess = activePtys.get(message.ptyId);
@@ -2908,6 +3104,7 @@ function writePty(ws, message) {
     });
     return;
   }
+  ptyProcess.lastInputAt = Date.now();
   ptyProcess.write(message.data);
 }
 function resizePty(message) {
@@ -3345,13 +3542,24 @@ async function startWorker(options) {
     });
   };
   const activeWorkspaceMutationTargets = () => [
-    ...Array.from(activeProcesses.values(), ({ target }) => target),
+    ...Array.from(activeProcesses.values()).filter(workerCommandHasWorkspaceEffect).map(({ target }) => target),
     ...credentialBearingProcessGroupTargets.values(),
     ...workspaceSyncPriorityProcessTargets.values(),
     ...workspaceSyncPriorityOperationTargets.values(),
-    ...Array.from(activePtys.values(), ({ target }) => target),
+    ...Array.from(activePtys.values()).filter((pty) => workerPtyIsWorkspaceBusy(pty)).map(({ target }) => target),
     ...workspaceSyncPriorityPtyTargets.values()
   ];
+  let visibleWorkspaceMutationEpoch = 0;
+  const projectWorkspaceMutationEpochs = /* @__PURE__ */ new Map();
+  const recordVisibleWorkspaceMutation = (target) => {
+    if (target.type === "workspace") {
+      if (target.rootProfile === "visible_projects") visibleWorkspaceMutationEpoch += 1;
+      return;
+    }
+    const key = projectBranchKey(target.projectId, target.branchName);
+    projectWorkspaceMutationEpochs.set(key, (projectWorkspaceMutationEpochs.get(key) ?? 0) + 1);
+  };
+  const projectWorkspaceMutationToken = (projectId, branchName) => `${visibleWorkspaceMutationEpoch}:${projectWorkspaceMutationEpochs.get(projectBranchKey(projectId, branchName)) ?? 0}`;
   const canonicalWorkspaceMutationIsActive = (targets) => targets.some((target) => target.type === "workspace" && target.rootProfile === "canonical_sync");
   const projectBranchMountActivityBusy = (projectId, branchName, branchPath) => {
     const activeTargets = activeWorkspaceMutationTargets();
@@ -3388,6 +3596,7 @@ async function startWorker(options) {
           preserveLocalOnInitialOuterAbsence: creatorLocalIncarnation,
           preserveLocalOnHydrationBasisChange: preservesCheckoutPathMove,
           busy: () => projectBranchMountBusy(project.projectId, branch.branchName, branchPath),
+          mutationToken: () => projectWorkspaceMutationToken(project.projectId, branch.branchName),
           busyForRecovery: () => projectBranchMountActivityBusy(project.projectId, branch.branchName, branchPath)
         });
         mounts.push({
@@ -3401,6 +3610,7 @@ async function startWorker(options) {
           preserveLocalOnInitialOuterAbsence: creatorLocalIncarnation,
           preserveLocalOnHydrationBasisChange: preservesCheckoutPathMove,
           busy: () => projectBranchMountBusy(project.projectId, branch.branchName, branchPath),
+          mutationToken: () => projectWorkspaceMutationToken(project.projectId, branch.branchName),
           busyForRecovery: () => projectBranchMountActivityBusy(project.projectId, branch.branchName, branchPath)
         });
       }
@@ -3421,6 +3631,7 @@ async function startWorker(options) {
         const activeTargets = activeWorkspaceMutationTargets();
         return canonicalWorkspaceMutationIsActive(activeTargets) || hasActiveVisibleProjectsWorkspaceTarget(activeTargets);
       },
+      mutationToken: () => String(visibleWorkspaceMutationEpoch),
       busyForRecovery: () => {
         const activeTargets = activeWorkspaceMutationTargets();
         return canonicalWorkspaceMutationIsActive(activeTargets) || hasActiveVisibleProjectsWorkspaceTarget(activeTargets);
@@ -3778,6 +3989,7 @@ async function startWorker(options) {
       localChangesDiscarded: false,
       ...result.conflictPaths ? { conflictPaths: result.conflictPaths } : {},
       ...result.conflictSnapshotRefs ? { conflictSnapshotRefs: result.conflictSnapshotRefs } : {},
+      ...result.conflictKind ? { conflictKind: result.conflictKind } : {},
       ...result.error ? { error: result.error } : {}
     };
   };
@@ -3844,10 +4056,7 @@ async function startWorker(options) {
       };
     }
     const outerRemediation = input.trigger.type === "remediation" || input.trigger.type === "remediation_confirm";
-    const ordinaryCycleHasBusyLiveMount = mounts.some(
-      (mount) => !(mount.deleteWhenSourceMissing && !fs.existsSync(mount.sourcePath)) && mount.busy?.()
-    );
-    const observedProjectHeads = outerRemediation || ordinaryCycleHasBusyLiveMount ? [] : observeProjectHeadsBeforeOuterWorkspace({ allowNonFastForward: false, failClosed: false });
+    const observedProjectHeads = outerRemediation ? [] : observeProjectHeadsBeforeOuterWorkspace({ allowNonFastForward: false, failClosed: false });
     const inboundMoveMountIds = new Set(
       observedProjectHeads.flatMap(
         ({ projectId, observations }) => observations.filter(({ shouldMove }) => shouldMove).map(({ branchName }) => projectMountId(projectId, branchName))
@@ -4003,7 +4212,8 @@ async function startWorker(options) {
     );
     workspaceAutomaticTimer.unref();
   };
-  const markWorkspaceDirty = (trigger, force = false) => {
+  const markWorkspaceDirty = (trigger, force = false, target) => {
+    if (target) recordVisibleWorkspaceMutation(target);
     scheduleAutomaticWorkspaceSync(trigger, force ? 0 : WORKSPACE_GIT_QUIET_MS);
   };
   const targetMayMutateVisibleWorkspace = (target) => target.type === "project" || target.rootProfile === "visible_projects";
@@ -4264,7 +4474,7 @@ async function startWorker(options) {
           sourcePath: recoverySourceOverrides.get(mount.id) ?? mount.sourcePath,
           busy: mount.busyForRecovery ?? mount.busy
         }));
-        recoverWorkspaceGitHydration(workspaceShadowRoot, recoveryMounts);
+        recoverWorkspaceGitHydration(workspaceShadowRoot, recoveryMounts, { preserveStaleBases: true });
         for (const project of message.projects) {
           for (const { branchName } of project.preserveOnlyBranches) {
             if (stillPendingCreatedBranches.has(pendingCreatedBranchKey(project.projectId, branchName))) {
@@ -4440,7 +4650,8 @@ async function startWorker(options) {
         capabilities: {
           updateClis: true,
           browserPortForwarding: true,
-          execStdinV1: true
+          execStdinV1: true,
+          ptyEnvFilesV1: true
         },
         projectRoot: projectsRoot,
         artifactRoot,
@@ -4815,6 +5026,9 @@ async function startWorker(options) {
           });
           return;
         }
+        if (active.workspaceEffect !== "none" && targetMayMutateVisibleWorkspace(active.target)) {
+          recordVisibleWorkspaceMutation(active.target);
+        }
         try {
           let bytesWritten = 0;
           if (message.data !== void 0 && message.data.length > 0) {
@@ -4825,8 +5039,8 @@ async function startWorker(options) {
             await active.stdin.end();
             active.stdin = void 0;
           }
-          if (targetMayMutateVisibleWorkspace(active.target)) {
-            markWorkspaceDirty({ type: "shell_inline", detail: `exec stdin ${message.runId}` });
+          if (active.workspaceEffect !== "none" && targetMayMutateVisibleWorkspace(active.target)) {
+            markWorkspaceDirty({ type: "shell_inline", detail: `exec stdin ${message.runId}` }, false, active.target);
           }
           sendAck({
             result: {
@@ -4853,6 +5067,7 @@ async function startWorker(options) {
         }
         await reserveWorkspaceCommandAfterCurrentSync(message.target, workspaceSyncSingleFlight, () => {
           workspaceSyncPriorityPtyTargets.set(message.ptyId, message.target);
+          if (targetMayMutateVisibleWorkspace(message.target)) recordVisibleWorkspaceMutation(message.target);
         });
         let releaseWorkspaceMutation;
         let mutationLeaseTransferred = false;
@@ -4870,7 +5085,7 @@ async function startWorker(options) {
             ...releaseWorkspaceMutation ? { releaseWorkspaceMutation } : {},
             ...targetMayMutateVisibleWorkspace(message.target) ? {
               onTerminal: () => {
-                markWorkspaceDirty({ type: "process_terminal", detail: `pty ${message.ptyId} completed` }, true);
+                markWorkspaceDirty({ type: "process_terminal", detail: `pty ${message.ptyId} completed` }, true, message.target);
               }
             } : {}
           });
@@ -4891,7 +5106,7 @@ async function startWorker(options) {
       if (message.type === "pty_input") {
         const activePty = activePtys.get(message.ptyId);
         if (activePty && targetMayMutateVisibleWorkspace(activePty.target)) {
-          markWorkspaceDirty({ type: "shell_inline", detail: `pty ${message.ptyId}` });
+          markWorkspaceDirty({ type: "shell_inline", detail: `pty ${message.ptyId}` }, false, activePty.target);
         }
         writePty(ws, message);
         return;
@@ -4904,7 +5119,7 @@ async function startWorker(options) {
         const activePty = activePtys.get(message.ptyId);
         closePty(message);
         if (activePty && targetMayMutateVisibleWorkspace(activePty.target)) {
-          markWorkspaceDirty({ type: "process_terminal", detail: `pty ${message.ptyId} closed` }, true);
+          markWorkspaceDirty({ type: "process_terminal", detail: `pty ${message.ptyId} closed` }, true, activePty.target);
         }
         return;
       }
@@ -4921,11 +5136,15 @@ async function startWorker(options) {
         }
         let result;
         let targetReserved = false;
+        const hasWorkspaceEffect = workerCommandHasWorkspaceEffect(message);
         try {
-          await reserveWorkspaceCommandAfterCurrentSync(message.target, workspaceSyncSingleFlight, () => {
-            workspaceSyncPriorityProcessTargets.set(message.runId, message.target);
-            targetReserved = true;
-          });
+          if (hasWorkspaceEffect) {
+            await reserveWorkspaceCommandAfterCurrentSync(message.target, workspaceSyncSingleFlight, () => {
+              workspaceSyncPriorityProcessTargets.set(message.runId, message.target);
+              targetReserved = true;
+              if (targetMayMutateVisibleWorkspace(message.target)) recordVisibleWorkspaceMutation(message.target);
+            });
+          }
           const runCommand = async () => {
             const resolvedTarget = resolveMessageTarget(message.target);
             process.stdout.write(`[r5d-worker] exec ${message.runId}: ${message.argv.join(" ")}
@@ -4955,10 +5174,11 @@ async function startWorker(options) {
           if (targetReserved) workspaceSyncPriorityProcessTargets.delete(message.runId);
         }
         ws.send(JSON.stringify(result));
-        if (targetMayMutateVisibleWorkspace(message.target)) {
+        if (hasWorkspaceEffect && targetMayMutateVisibleWorkspace(message.target)) {
           markWorkspaceDirty(
             { type: "shell_inline", sessionId: message.sessionId, processRunId: message.runId, detail: "foreground command completed" },
-            true
+            true,
+            message.target
           );
         }
         return;
@@ -4978,6 +5198,7 @@ async function startWorker(options) {
           requestId: message.requestId,
           runId: message.runId
         });
+        const hasWorkspaceEffect = workerCommandHasWorkspaceEffect(message);
         const runCommand = async () => {
           try {
             const resolvedTarget = resolveMessageTarget(message.target);
@@ -4994,7 +5215,7 @@ async function startWorker(options) {
               assertAdmission: assertMessageAdmission
             });
           } finally {
-            if (targetMayMutateVisibleWorkspace(message.target)) {
+            if (hasWorkspaceEffect && targetMayMutateVisibleWorkspace(message.target)) {
               markWorkspaceDirty(
                 {
                   type: "process_terminal",
@@ -5002,7 +5223,8 @@ async function startWorker(options) {
                   processRunId: message.runId,
                   detail: "process completed"
                 },
-                true
+                true,
+                message.target
               );
             }
           }
@@ -5010,10 +5232,13 @@ async function startWorker(options) {
         const execution = (async () => {
           let targetReserved = false;
           try {
-            await reserveWorkspaceCommandAfterCurrentSync(message.target, workspaceSyncSingleFlight, () => {
-              workspaceSyncPriorityProcessTargets.set(message.runId, message.target);
-              targetReserved = true;
-            });
+            if (hasWorkspaceEffect) {
+              await reserveWorkspaceCommandAfterCurrentSync(message.target, workspaceSyncSingleFlight, () => {
+                workspaceSyncPriorityProcessTargets.set(message.runId, message.target);
+                targetReserved = true;
+                if (targetMayMutateVisibleWorkspace(message.target)) recordVisibleWorkspaceMutation(message.target);
+              });
+            }
             await runWorkspaceCommand(message.target, workspaceSyncSingleFlight, runCommand);
           } finally {
             if (targetReserved) workspaceSyncPriorityProcessTargets.delete(message.runId);
@@ -5036,6 +5261,7 @@ async function startWorker(options) {
         if (reservesVisibleWorkspace) {
           await reserveWorkspaceCommandAfterCurrentSync(message.target, workspaceSyncSingleFlight, () => {
             workspaceSyncPriorityOperationTargets.set(message.requestId, message.target);
+            if (mutatesVisibleWorkspace) recordVisibleWorkspaceMutation(message.target);
           });
         }
         let dirtyTrigger;
@@ -5065,7 +5291,7 @@ async function startWorker(options) {
               toolCallId: message.requestId,
               ...message.target.type === "project" ? { projectId: message.target.projectId, branchName: message.target.branchName } : {}
             };
-            markWorkspaceDirty(dirtyTrigger);
+            markWorkspaceDirty(dirtyTrigger, false, message.target);
           }
         } catch (error) {
           ws.send(
@@ -5225,5 +5451,7 @@ export {
   syncSessionArtifacts,
   workerChildProcessEnvironment,
   workerGitSecurityTestHarness,
+  workerPtyBridgeTestHarness,
+  workerPtyTestHarness,
   writeWorkerTextFile
 };