@ricsam/r5d-worker 0.0.80 → 0.0.82

package/dist/cjs/main.cjs

@@ -50,6 +50,8 @@ __export(main_exports, {
   syncSessionArtifacts: () => syncSessionArtifacts,
   workerChildProcessEnvironment: () => workerChildProcessEnvironment,
   workerGitSecurityTestHarness: () => workerGitSecurityTestHarness,
+  workerPtyBridgeTestHarness: () => workerPtyBridgeTestHarness,
+  workerPtyTestHarness: () => workerPtyTestHarness,
   writeWorkerTextFile: () => writeWorkerTextFile
 });
 module.exports = __toCommonJS(main_exports);
@@ -95,6 +97,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();
@@ -152,6 +158,106 @@ function assertWorkerChildAdmission(input) {
     throw new StaleWorkerAdmissionError();
   }
 }
+function pathIsInsideRoot(rootPath, candidatePath) {
+  const relative = import_node_path.default.relative(rootPath, candidatePath);
+  return relative === "" || !relative.startsWith(`..${import_node_path.default.sep}`) && relative !== ".." && !import_node_path.default.isAbsolute(relative);
+}
+function resolvePtyEnvFilePath(requestedPath, temporaryRoot = import_node_os.default.tmpdir()) {
+  const canonicalTemporaryRoot = import_node_fs.default.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 import_node_path.default.join(canonicalTemporaryRoot, filename);
+  }
+  if (!import_node_path.default.isAbsolute(requestedPath)) {
+    throw new Error(`PTY environment file path must be absolute or use ${PTY_TMP_PATH_PREFIX}`);
+  }
+  const resolvedPath = import_node_path.default.resolve(requestedPath);
+  const canonicalParent = import_node_fs.default.realpathSync.native(import_node_path.default.dirname(resolvedPath));
+  const canonicalPath = import_node_path.default.join(canonicalParent, import_node_path.default.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 {
+      import_node_fs.default.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 = import_node_os.default.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 = import_node_fs.default.openSync(
+        resolvedPath,
+        import_node_fs.default.constants.O_WRONLY | import_node_fs.default.constants.O_CREAT | import_node_fs.default.constants.O_EXCL | (typeof import_node_fs.default.constants.O_NOFOLLOW === "number" ? import_node_fs.default.constants.O_NOFOLLOW : 0),
+        384
+      );
+      staged.paths.push(resolvedPath);
+      staged.resolvedByRequestedPath.set(envFile.path, resolvedPath);
+      try {
+        import_node_fs.default.writeFileSync(descriptor, envFile.content, "utf8");
+        import_node_fs.default.fchmodSync(descriptor, 384);
+        import_node_fs.default.fsyncSync(descriptor);
+      } finally {
+        import_node_fs.default.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 import_node_path.default.join(import_node_os.default.homedir(), ".config", "r5d", "r5dctl", "config.json");
 }
@@ -629,7 +735,7 @@ function preparePlanEnvForShell(input) {
   import_node_fs.default.mkdirSync(plansDir, { recursive: true });
   return planEnv(input.planRoot, input.target, input.activePlanId);
 }
-async function verifyR5dctlAuth(baseUrl, token) {
+async function verifyR5dctlAuth(baseUrl, token, workerLabel) {
   const statusUrl = new URL("/api/r5dctl/auth/status", baseUrl);
   let response;
   try {
@@ -658,13 +764,16 @@ async function verifyR5dctlAuth(baseUrl, token) {
     throw new WorkerServerUnavailableError(`Server unavailable at ${baseUrl} (${response.status})${detail}`);
   }
   throw new Error(
-    `Authentication failed against ${baseUrl} (${response.status})${detail}. Run \`r5dctl auth login --base-url ${baseUrl}\` or pass --token/--api-key for this server.`
+    `Authentication failed against ${baseUrl} (${response.status})${detail}. Run \`r5dctl auth login --base-url ${baseUrl} --worker-label ${workerLabel}\` or pass that exact label-bound worker token.`
   );
 }
 function resolveCredentials(options, config) {
   const token = options.token ?? process.env.R5D_WORKER_TOKEN ?? process.env.R5D_TOKEN ?? process.env.R5DCTL_TOKEN ?? config.token ?? options.apiKey ?? process.env.R5D_API_KEY ?? process.env.R5DCTL_API_KEY ?? config.apiKey;
   if (!token) {
-    throw new Error("Authentication required. Run `r5dctl auth login` or set R5D_WORKER_TOKEN/R5D_API_KEY.");
+    const workerLabel = options.label ?? "<label>";
+    throw new Error(
+      `Authentication required. Run \`r5dctl auth login --worker-label ${workerLabel}\` or set R5D_WORKER_TOKEN to that label-bound token.`
+    );
   }
   return {
     baseUrl: normalizeBaseUrl(
@@ -2330,7 +2439,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,
@@ -2341,7 +2452,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(() => {
@@ -2427,7 +2539,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,
@@ -2440,7 +2554,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, {
@@ -2487,7 +2602,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);
@@ -2499,7 +2615,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);
@@ -2580,7 +2697,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) {
@@ -2592,8 +2710,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);
@@ -2603,6 +2726,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) => {
@@ -2621,9 +2784,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;
     }
 
@@ -2716,7 +2884,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") {
@@ -2797,6 +2969,9 @@ function createNodePtyBridge(options) {
     }
   };
 }
+const workerPtyBridgeTestHarness = {
+  create: createNodePtyBridge
+};
 function resolveHostShell(command, platform = process.platform) {
   if (platform === "win32") {
     const file2 = process.env.COMSPEC || "powershell.exe";
@@ -2832,64 +3007,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);
@@ -2901,6 +3102,7 @@ function writePty(ws, message) {
     });
     return;
   }
+  ptyProcess.lastInputAt = Date.now();
   ptyProcess.write(message.data);
 }
 function resizePty(message) {
@@ -3021,7 +3223,7 @@ async function startWorker(options) {
   process.stdout.write(`[r5d-worker] server: ${baseUrl}
 `);
   runGit(["--version"]);
-  await verifyR5dctlAuth(baseUrl, token);
+  await verifyR5dctlAuth(baseUrl, token, label);
   const initializedWorkspaceState = await workspaceSyncSingleFlight.runExclusive(() => {
     if (!startupProjectSnapshotRecoveryCompleted) {
       const snapshotRecovery = (0, import_project_worktrees.recoverStaleProjectWorktreeSnapshots)({
@@ -3338,13 +3540,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();
@@ -3381,6 +3594,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({
@@ -3394,6 +3608,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)
         });
       }
@@ -3414,6 +3629,7 @@ async function startWorker(options) {
         const activeTargets = activeWorkspaceMutationTargets();
         return canonicalWorkspaceMutationIsActive(activeTargets) || (0, import_workspace_automatic_sync_policy.hasActiveVisibleProjectsWorkspaceTarget)(activeTargets);
       },
+      mutationToken: () => String(visibleWorkspaceMutationEpoch),
       busyForRecovery: () => {
         const activeTargets = activeWorkspaceMutationTargets();
         return canonicalWorkspaceMutationIsActive(activeTargets) || (0, import_workspace_automatic_sync_policy.hasActiveVisibleProjectsWorkspaceTarget)(activeTargets);
@@ -3771,6 +3987,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 } : {}
     };
   };
@@ -3837,10 +4054,7 @@ async function startWorker(options) {
       };
     }
     const outerRemediation = input.trigger.type === "remediation" || input.trigger.type === "remediation_confirm";
-    const ordinaryCycleHasBusyLiveMount = mounts.some(
-      (mount) => !(mount.deleteWhenSourceMissing && !import_node_fs.default.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))
@@ -3996,7 +4210,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";
@@ -4257,7 +4472,7 @@ async function startWorker(options) {
           sourcePath: recoverySourceOverrides.get(mount.id) ?? mount.sourcePath,
           busy: mount.busyForRecovery ?? mount.busy
         }));
-        (0, import_workspace_git_sync.recoverWorkspaceGitHydration)(workspaceShadowRoot, recoveryMounts);
+        (0, import_workspace_git_sync.recoverWorkspaceGitHydration)(workspaceShadowRoot, recoveryMounts, { preserveStaleBases: true });
         for (const project of message.projects) {
           for (const { branchName } of project.preserveOnlyBranches) {
             if (stillPendingCreatedBranches.has((0, import_workspace_automatic_sync_policy.pendingCreatedBranchKey)(project.projectId, branchName))) {
@@ -4433,7 +4648,8 @@ async function startWorker(options) {
         capabilities: {
           updateClis: true,
           browserPortForwarding: true,
-          execStdinV1: true
+          execStdinV1: true,
+          ptyEnvFilesV1: true
         },
         projectRoot: projectsRoot,
         artifactRoot,
@@ -4808,6 +5024,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) {
@@ -4818,8 +5037,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: {
@@ -4846,6 +5065,7 @@ async function startWorker(options) {
         }
         await (0, import_workspace_command_sync_policy.reserveWorkspaceCommandAfterCurrentSync)(message.target, workspaceSyncSingleFlight, () => {
           workspaceSyncPriorityPtyTargets.set(message.ptyId, message.target);
+          if (targetMayMutateVisibleWorkspace(message.target)) recordVisibleWorkspaceMutation(message.target);
         });
         let releaseWorkspaceMutation;
         let mutationLeaseTransferred = false;
@@ -4863,7 +5083,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);
               }
             } : {}
           });
@@ -4884,7 +5104,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;
@@ -4897,7 +5117,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;
       }
@@ -4914,11 +5134,15 @@ async function startWorker(options) {
         }
         let result;
         let targetReserved = false;
+        const hasWorkspaceEffect = workerCommandHasWorkspaceEffect(message);
         try {
-          await (0, import_workspace_command_sync_policy.reserveWorkspaceCommandAfterCurrentSync)(message.target, workspaceSyncSingleFlight, () => {
-            workspaceSyncPriorityProcessTargets.set(message.runId, message.target);
-            targetReserved = true;
-          });
+          if (hasWorkspaceEffect) {
+            await (0, import_workspace_command_sync_policy.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(" ")}
@@ -4948,10 +5172,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;
@@ -4971,6 +5196,7 @@ async function startWorker(options) {
           requestId: message.requestId,
           runId: message.runId
         });
+        const hasWorkspaceEffect = workerCommandHasWorkspaceEffect(message);
         const runCommand = async () => {
           try {
             const resolvedTarget = resolveMessageTarget(message.target);
@@ -4987,7 +5213,7 @@ async function startWorker(options) {
               assertAdmission: assertMessageAdmission
             });
           } finally {
-            if (targetMayMutateVisibleWorkspace(message.target)) {
+            if (hasWorkspaceEffect && targetMayMutateVisibleWorkspace(message.target)) {
               markWorkspaceDirty(
                 {
                   type: "process_terminal",
@@ -4995,7 +5221,8 @@ async function startWorker(options) {
                   processRunId: message.runId,
                   detail: "process completed"
                 },
-                true
+                true,
+                message.target
               );
             }
           }
@@ -5003,10 +5230,13 @@ async function startWorker(options) {
         const execution = (async () => {
           let targetReserved = false;
           try {
-            await (0, import_workspace_command_sync_policy.reserveWorkspaceCommandAfterCurrentSync)(message.target, workspaceSyncSingleFlight, () => {
-              workspaceSyncPriorityProcessTargets.set(message.runId, message.target);
-              targetReserved = true;
-            });
+            if (hasWorkspaceEffect) {
+              await (0, import_workspace_command_sync_policy.reserveWorkspaceCommandAfterCurrentSync)(message.target, workspaceSyncSingleFlight, () => {
+                workspaceSyncPriorityProcessTargets.set(message.runId, message.target);
+                targetReserved = true;
+                if (targetMayMutateVisibleWorkspace(message.target)) recordVisibleWorkspaceMutation(message.target);
+              });
+            }
             await (0, import_workspace_command_sync_policy.runWorkspaceCommand)(message.target, workspaceSyncSingleFlight, runCommand);
           } finally {
             if (targetReserved) workspaceSyncPriorityProcessTargets.delete(message.runId);
@@ -5029,6 +5259,7 @@ async function startWorker(options) {
         if (reservesVisibleWorkspace) {
           await (0, import_workspace_command_sync_policy.reserveWorkspaceCommandAfterCurrentSync)(message.target, workspaceSyncSingleFlight, () => {
             workspaceSyncPriorityOperationTargets.set(message.requestId, message.target);
+            if (mutatesVisibleWorkspace) recordVisibleWorkspaceMutation(message.target);
           });
         }
         let dirtyTrigger;
@@ -5058,7 +5289,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(
@@ -5219,5 +5450,7 @@ if (isCliEntrypoint()) {
   syncSessionArtifacts,
   workerChildProcessEnvironment,
   workerGitSecurityTestHarness,
+  workerPtyBridgeTestHarness,
+  workerPtyTestHarness,
   writeWorkerTextFile
 });