@ricsam/r5d-worker 0.0.46 → 0.0.48

package/README.md

@@ -37,3 +37,5 @@ The agent runs commands through the virtual shell command:
 worker exec macos docker compose up -d
 worker exec macos bun test
 ```
+
+When the connected `r5d-browser` requests a port forward, the worker opens each relayed connection only to `127.0.0.1` on the requested worker port. Browser-side and worker-side ports may differ. The worker never opens a public listener, and a disconnected worker leaves the browser's long-lived mapping unavailable until the same worker label reconnects.

package/dist/cjs/main.cjs

@@ -43,6 +43,9 @@ __export(main_exports, {
   resolveHostShell: () => resolveHostShell,
   resolveWorkerFilePath: () => resolveWorkerFilePath,
   syncSessionArtifacts: () => syncSessionArtifacts,
+  visibleCheckoutGitTestHarness: () => visibleCheckoutGitTestHarness,
+  visibleCheckoutRemoteFor: () => visibleCheckoutRemoteFor,
+  workspaceSyncCheckoutTargets: () => workspaceSyncCheckoutTargets,
   writeWorkerTextFile: () => writeWorkerTextFile
 });
 module.exports = __toCommonJS(main_exports);
@@ -55,6 +58,7 @@ var import_cli_update = require("./cli-update.cjs");
 var import_git_identity = require("./git-identity.cjs");
 var import_heartbeat = require("./heartbeat.cjs");
 var import_process_tree = require("./process-tree.cjs");
+var import_port_forward_client = require("./port-forward-client.cjs");
 var import_supervisor = require("./supervisor.cjs");
 var import_managed_paths = require("./managed-paths.cjs");
 var import_workspace_sync = require("./workspace-sync.cjs");
@@ -614,6 +618,14 @@ function validatePlanId(planId) {
     throw new Error(`Invalid plan id from server: ${planId}`);
   }
 }
+const NON_RECURSIVE_GIT_CONFIG_ARGS = [
+  "-c",
+  "submodule.recurse=false",
+  "-c",
+  "fetch.recurseSubmodules=false",
+  "-c",
+  "push.recurseSubmodules=false"
+];
 function gitExtraHeaderConfigKey(extraHeaderUrl) {
   return `http.${normalizeBaseUrl(extraHeaderUrl)}/.extraHeader`;
 }
@@ -621,10 +633,23 @@ function gitAuthArgs(auth) {
   if (!auth) {
     return [];
   }
-  return ["-c", `${gitExtraHeaderConfigKey(auth.extraHeaderUrl)}=${auth.header}`];
+  const scopedKey = gitExtraHeaderConfigKey(auth.extraHeaderUrl);
+  return ["-c", "http.extraHeader=", "-c", `${scopedKey}=`, "-c", `${scopedKey}=${auth.header}`];
+}
+const visibleCheckoutGitTestHarness = {
+  gitAuthArgs,
+  commandArgs: (args, auth) => ["git", ...NON_RECURSIVE_GIT_CONFIG_ARGS, ...gitAuthArgs(auth), ...args],
+  cloneArgs: (remoteUrl, branchPath) => ["clone", "--no-recurse-submodules", "--origin", "origin", remoteUrl, branchPath],
+  fetchArgs: (...args) => ["fetch", "--no-recurse-submodules", ...args]
+};
+function visibleCheckoutCloneArgs(remoteUrl, branchPath) {
+  return visibleCheckoutGitTestHarness.cloneArgs(remoteUrl, branchPath);
+}
+function visibleCheckoutFetchArgs(...args) {
+  return visibleCheckoutGitTestHarness.fetchArgs(...args);
 }
 function runGit(args, options = {}) {
-  const command = ["git", ...gitAuthArgs(options.auth), ...args];
+  const command = visibleCheckoutGitTestHarness.commandArgs(args, options.auth);
   const result = Bun.spawnSync(command, {
     cwd: options.cwd,
     stdout: "pipe",
@@ -768,8 +793,28 @@ function resolveWorkerFilePath(branchPath, inputPath, builtInPaths) {
 function fallbackInternalRemoteUrl(baseUrl, projectId) {
   return new URL(`/git/${projectId}.git`, baseUrl).toString();
 }
-function githubRemoteUrlFor(baseUrl, projectId, manifest) {
-  return manifest?.repoHttpUrl ?? fallbackInternalRemoteUrl(baseUrl, projectId);
+function visibleCheckoutRemoteFor(input) {
+  const canonicalCheckout = input.manifest?.canonicalCheckouts?.find((checkout) => checkout.branchName === input.branchName);
+  const isCanonicalManifestBranch = Boolean(canonicalCheckout);
+  const usesCanonicalRemote = isCanonicalManifestBranch || !input.manifest?.repoHttpUrl;
+  if (usesCanonicalRemote) {
+    return {
+      remoteUrl: fallbackInternalRemoteUrl(input.baseUrl, input.projectId),
+      authHeader: `Authorization: Bearer ${input.token}`,
+      persistAuth: false,
+      reconcileExistingOrigin: isCanonicalManifestBranch,
+      requireRemoteBranch: isCanonicalManifestBranch,
+      requiredBaseCommit: canonicalCheckout?.scaffoldCommitHash ?? null
+    };
+  }
+  return {
+    remoteUrl: input.manifest?.repoHttpUrl ?? fallbackInternalRemoteUrl(input.baseUrl, input.projectId),
+    authHeader: input.manifest?.repoAuthHeader ?? null,
+    persistAuth: true,
+    reconcileExistingOrigin: Boolean(input.manifest?.repoHttpUrl),
+    requireRemoteBranch: false,
+    requiredBaseCommit: null
+  };
 }
 function gitExtraHeaderUrlForRemote(remoteUrl) {
   try {
@@ -798,6 +843,10 @@ function ensureOriginRemote(branchPath, remoteUrl) {
     runGit(["remote", "add", "origin", remoteUrl], { cwd: branchPath });
   }
 }
+function originRemoteUrl(branchPath) {
+  if (!tryGit(["remote", "get-url", "origin"], { cwd: branchPath })) return null;
+  return runGit(["remote", "get-url", "origin"], { cwd: branchPath });
+}
 function shellQuote(value) {
   return `'${value.replace(/'/g, "'\\''")}'`;
 }
@@ -866,6 +915,18 @@ function configureVisibleGitHubAuth(branchPath, remoteUrl, authHeader) {
   }
   runGit(["config", `${gitExtraHeaderConfigKey(gitExtraHeaderUrlForRemote(remoteUrl))}`, authHeader], { cwd: branchPath });
 }
+function clearVisibleGitAuthentication(branchPath) {
+  let extraHeaderKeys = [];
+  try {
+    extraHeaderKeys = runGit(["config", "--local", "--name-only", "--get-regexp", "^http\\..*extraheader$"], { cwd: branchPath }).split(/\r?\n/).filter(Boolean);
+  } catch {
+  }
+  for (const key of extraHeaderKeys) {
+    tryGit(["config", "--local", "--unset-all", key], { cwd: branchPath });
+  }
+  runGit(["config", "--local", "--replace-all", "credential.helper", ""], { cwd: branchPath });
+  tryGit(["config", "--local", "--unset-all", "credential.useHttpPath"], { cwd: branchPath });
+}
 function dockerConfigPath() {
   return import_node_path.default.join(import_node_os.default.homedir(), ".docker", "config.json");
 }
@@ -954,18 +1015,58 @@ function checkoutVisibleBranch(input) {
   });
   const clean = !hasWorktreeChanges(input.branchPath);
   if (remoteBranchExists && clean) {
-    runGit(["checkout", "-B", input.branchName, `origin/${input.branchName}`], { cwd: input.branchPath });
+    runGit(["checkout", "--no-recurse-submodules", "-B", input.branchName, `origin/${input.branchName}`], {
+      cwd: input.branchPath
+    });
     return;
   }
   if (branchExists) {
-    runGit(["checkout", input.branchName], { cwd: input.branchPath });
+    runGit(["checkout", "--no-recurse-submodules", input.branchName], { cwd: input.branchPath });
     return;
   }
   if (defaultRemoteExists) {
-    runGit(["checkout", "-B", input.branchName, `origin/${input.defaultBranch}`], { cwd: input.branchPath });
+    runGit(["checkout", "--no-recurse-submodules", "-B", input.branchName, `origin/${input.defaultBranch}`], {
+      cwd: input.branchPath
+    });
     return;
   }
-  runGit(["checkout", "-B", input.branchName], { cwd: input.branchPath });
+  runGit(["checkout", "--no-recurse-submodules", "-B", input.branchName], { cwd: input.branchPath });
+}
+function migrateExistingCheckoutToRequiredRemote(input) {
+  if (originRemoteUrl(input.branchPath) === input.remoteUrl) return;
+  if (hasWorktreeChanges(input.branchPath)) {
+    throw new Error(`Cannot migrate dirty checkout for ${input.branchName} to its canonical remote`);
+  }
+  runGit(
+    visibleCheckoutFetchArgs("--no-tags", input.remoteUrl, `+refs/heads/${input.branchName}:refs/remotes/origin/${input.branchName}`),
+    {
+      cwd: input.branchPath,
+      auth: input.remoteAuth
+    }
+  );
+  const canonicalRemoteRef = `refs/remotes/origin/${input.branchName}`;
+  if (!tryGit(["show-ref", "--verify", "--quiet", canonicalRemoteRef], { cwd: input.branchPath })) {
+    throw new Error(`Canonical branch ${input.branchName} is unavailable during checkout migration`);
+  }
+  if (input.requiredBaseCommit && (!tryGit(["cat-file", "-e", `${input.requiredBaseCommit}^{commit}`], { cwd: input.branchPath }) || !tryGit(["merge-base", "--is-ancestor", input.requiredBaseCommit, canonicalRemoteRef], { cwd: input.branchPath }))) {
+    throw new Error(`Canonical branch ${input.branchName} is not derived from required scaffold ${input.requiredBaseCommit}`);
+  }
+  if (tryGit(["rev-parse", "--verify", "HEAD"], { cwd: input.branchPath })) {
+    const previousHead = runGit(["rev-parse", "HEAD"], { cwd: input.branchPath });
+    runGit(["update-ref", `refs/r5d/pre-canonical-checkout/${previousHead}`, previousHead], { cwd: input.branchPath });
+  }
+  ensureOriginRemote(input.branchPath, input.remoteUrl);
+  runGit(["checkout", "--no-recurse-submodules", "-B", input.branchName, `origin/${input.branchName}`], {
+    cwd: input.branchPath
+  });
+}
+function assertCheckoutDerivedFromRequiredBase(input) {
+  const remoteRevision = `refs/remotes/origin/${input.branchName}`;
+  for (const revision of [remoteRevision, "HEAD"]) {
+    if (!tryGit(["cat-file", "-e", `${input.requiredBaseCommit}^{commit}`], { cwd: input.branchPath }) || !tryGit(["merge-base", "--is-ancestor", input.requiredBaseCommit, revision], { cwd: input.branchPath })) {
+      throw new Error(`Canonical checkout ${input.branchName} is not derived from required scaffold ${input.requiredBaseCommit}`);
+    }
+  }
 }
 function ensureVisibleGitCheckout(input) {
   validateBranchName(input.branchName);
@@ -975,40 +1076,114 @@ function ensureVisibleGitCheckout(input) {
   if (createdCheckout) {
     import_node_fs.default.rmSync(branchPath, { recursive: true, force: true });
     import_node_fs.default.mkdirSync(import_node_path.default.dirname(branchPath), { recursive: true });
-    if (!tryGit(["clone", "--origin", "origin", input.githubRemoteUrl, branchPath], { auth: input.githubAuth })) {
+    const cloned = tryGit(visibleCheckoutCloneArgs(input.remoteUrl, branchPath), {
+      auth: input.remoteAuth
+    });
+    if (!cloned && input.requireRemoteBranch) {
+      import_node_fs.default.rmSync(branchPath, { recursive: true, force: true });
+      throw new Error(`Failed to clone canonical checkout for branch ${input.branchName}`);
+    }
+    if (!cloned) {
       import_node_fs.default.mkdirSync(branchPath, { recursive: true });
       runGit(["init"], { cwd: branchPath });
     }
-    ensureOriginRemote(branchPath, input.githubRemoteUrl);
-    configureVisibleGitHubAuth(branchPath, input.githubRemoteUrl, input.githubAuthHeader);
+    ensureOriginRemote(branchPath, input.remoteUrl);
+    if (input.clearPersistentAuth) clearVisibleGitAuthentication(branchPath);
+    else configureVisibleGitHubAuth(branchPath, input.remoteUrl, input.persistentAuthHeader);
     (0, import_git_identity.configureVisibleGitIdentity)(branchPath, visibleGitIdentity, runGit);
-    tryGit(["fetch", "origin", "--prune"], { cwd: branchPath, auth: input.githubAuth });
+    tryGit(visibleCheckoutFetchArgs("origin", "--prune"), { cwd: branchPath, auth: input.remoteAuth });
+    if (input.requireRemoteBranch && !tryGit(["show-ref", "--verify", "--quiet", `refs/remotes/origin/${input.branchName}`], { cwd: branchPath })) {
+      import_node_fs.default.rmSync(branchPath, { recursive: true, force: true });
+      throw new Error(`Canonical branch ${input.branchName} is unavailable after clone`);
+    }
     checkoutVisibleBranch({ branchPath, branchName: input.branchName, defaultBranch: input.defaultBranch });
+    if (input.requiredBaseCommit) {
+      try {
+        assertCheckoutDerivedFromRequiredBase({
+          branchPath,
+          branchName: input.branchName,
+          requiredBaseCommit: input.requiredBaseCommit
+        });
+      } catch (error) {
+        import_node_fs.default.rmSync(branchPath, { recursive: true, force: true });
+        throw error;
+      }
+    }
     return branchPath;
   }
+  if (input.requireRemoteBranch) {
+    if (input.allowRequiredRemoteMigration === false && originRemoteUrl(branchPath) !== input.remoteUrl) {
+      throw new Error(`Canonical checkout ${input.branchName} no longer uses its required remote`);
+    }
+    migrateExistingCheckoutToRequiredRemote({
+      branchPath,
+      branchName: input.branchName,
+      remoteUrl: input.remoteUrl,
+      remoteAuth: input.remoteAuth,
+      requiredBaseCommit: input.requiredBaseCommit
+    });
+    runGit(
+      visibleCheckoutFetchArgs("--no-tags", input.remoteUrl, `+refs/heads/${input.branchName}:refs/remotes/origin/${input.branchName}`),
+      {
+        cwd: branchPath,
+        auth: input.remoteAuth
+      }
+    );
+  }
   if (input.reconcileExistingOrigin) {
-    ensureOriginRemote(branchPath, input.githubRemoteUrl);
+    ensureOriginRemote(branchPath, input.remoteUrl);
   }
-  configureVisibleGitHubAuth(branchPath, input.githubRemoteUrl, input.githubAuthHeader);
+  if (input.requireRemoteBranch && !tryGit(["show-ref", "--verify", "--quiet", `refs/remotes/origin/${input.branchName}`], { cwd: branchPath })) {
+    throw new Error(`Existing checkout for ${input.branchName} does not contain its canonical remote branch`);
+  }
+  if (input.requiredBaseCommit) {
+    assertCheckoutDerivedFromRequiredBase({
+      branchPath,
+      branchName: input.branchName,
+      requiredBaseCommit: input.requiredBaseCommit
+    });
+  }
+  if (input.clearPersistentAuth) clearVisibleGitAuthentication(branchPath);
+  else configureVisibleGitHubAuth(branchPath, input.remoteUrl, input.persistentAuthHeader);
   (0, import_git_identity.configureVisibleGitIdentity)(branchPath, visibleGitIdentity, runGit);
   return branchPath;
 }
 function ensureBranchWorkspace(input) {
   const defaultBranch = input.manifest?.defaultBranch || "main";
-  const githubRemoteUrl = githubRemoteUrlFor(input.baseUrl, input.projectId, input.manifest);
-  const githubAuth = gitAuthForRemote(githubRemoteUrl, input.manifest?.repoAuthHeader);
+  const remote = visibleCheckoutRemoteFor(input);
   return {
     branchPath: ensureVisibleGitCheckout({
       projectRoot: input.projectRoot,
       branchName: input.branchName,
-      githubRemoteUrl,
-      githubAuth,
-      githubAuthHeader: input.manifest?.repoAuthHeader ?? null,
+      remoteUrl: remote.remoteUrl,
+      remoteAuth: gitAuthForRemote(remote.remoteUrl, remote.authHeader),
+      persistentAuthHeader: remote.persistAuth ? remote.authHeader : null,
       defaultBranch,
-      reconcileExistingOrigin: Boolean(input.manifest?.repoHttpUrl)
+      reconcileExistingOrigin: remote.reconcileExistingOrigin,
+      requireRemoteBranch: remote.requireRemoteBranch,
+      requiredBaseCommit: remote.requiredBaseCommit,
+      clearPersistentAuth: !remote.persistAuth
     })
   };
 }
+function workspaceSyncCheckoutTargets(input) {
+  const selected = /* @__PURE__ */ new Map();
+  const add = (target) => {
+    selected.set(`${target.projectId}\0${target.branchName}`, target);
+  };
+  if (input.canonicalCheckoutOnly) {
+    add(input.canonicalCheckoutOnly);
+  } else if (input.includeAllManifestCheckouts) {
+    for (const project of input.projects) {
+      for (const branchName of project.branches) add({ projectId: project.projectId, branchName });
+    }
+  } else {
+    for (const target of input.pendingTargets) add(target);
+  }
+  return [...selected.values()].sort(
+    (left, right) => left.projectId.localeCompare(right.projectId) || left.branchName.localeCompare(right.branchName)
+  );
+}
 function resolveCommandCwd(branchPath, cwd) {
   if (!cwd) {
     return branchPath;
@@ -2232,6 +2407,7 @@ async function startWorker(options) {
   let reloadAfterClose = false;
   const workspaceSyncInput = (trigger, overrides = {}) => {
     if (!workspaceRemoteUrl) throw new Error("Worker workspace manifest has not been received");
+    const projects = (0, import_workspace_sync.workspaceProjectsForSync)([...manifestByProjectId.values()], trigger);
     return {
       workerLabel: label,
       remoteUrl: workspaceRemoteUrl,
@@ -2239,7 +2415,7 @@ async function startWorker(options) {
       projectsRoot,
       plansRoot: planRoot,
       shadowRoot: workspaceShadowRoot,
-      projects: [...manifestByProjectId.values()],
+      projects,
       trigger,
       ...overrides
     };
@@ -2251,7 +2427,7 @@ async function startWorker(options) {
   const allManifestCheckouts = () => [...manifestByProjectId.values()].flatMap(
     (manifest) => manifest.branches.map((branchName) => ({ projectId: manifest.projectId, branchName }))
   );
-  const ensureVisibleWorkspaceCheckouts = (targets) => {
+  const ensureVisibleWorkspaceCheckouts = (targets, options2 = {}) => {
     const created = [];
     for (const target of targets) {
       const manifest = manifestByProjectId.get(target.projectId);
@@ -2263,15 +2439,25 @@ async function startWorker(options) {
       const projectRoot = projectRootFor(projectsRoot, manifest.projectId, manifestByProjectId);
       const branchPath = import_node_path.default.join(projectRoot, target.branchName);
       const existed = hasNormalVisibleGitDir(branchPath);
-      const githubRemoteUrl = githubRemoteUrlFor(baseUrl, manifest.projectId, manifest);
+      const remote = visibleCheckoutRemoteFor({
+        baseUrl,
+        token,
+        projectId: manifest.projectId,
+        branchName: target.branchName,
+        manifest
+      });
       ensureVisibleGitCheckout({
         projectRoot,
         branchName: target.branchName,
-        githubRemoteUrl,
-        githubAuth: gitAuthForRemote(githubRemoteUrl, manifest.repoAuthHeader),
-        githubAuthHeader: manifest.repoAuthHeader,
+        remoteUrl: remote.remoteUrl,
+        remoteAuth: gitAuthForRemote(remote.remoteUrl, remote.authHeader),
+        persistentAuthHeader: remote.persistAuth ? remote.authHeader : null,
         defaultBranch: manifest.defaultBranch || "main",
-        reconcileExistingOrigin: Boolean(manifest.repoHttpUrl)
+        reconcileExistingOrigin: remote.reconcileExistingOrigin,
+        requireRemoteBranch: remote.requireRemoteBranch,
+        requiredBaseCommit: remote.requiredBaseCommit,
+        allowRequiredRemoteMigration: !(options2.strictCanonicalRevalidation && remote.requireRemoteBranch),
+        clearPersistentAuth: !remote.persistAuth
       });
       if (!existed) created.push(target);
     }
@@ -2283,15 +2469,30 @@ async function startWorker(options) {
       let pendingTargets = [];
       const result = await workspaceSyncSingleFlight.runPrepared(() => {
         const shouldEnsureCheckouts = !overrides.skipVisibleMirror && !overrides.resetToCanonical;
+        const syncProjects = (0, import_workspace_sync.workspaceProjectsForSync)([...manifestByProjectId.values()], trigger);
+        const allowedCheckoutKeys = new Set(
+          syncProjects.flatMap((project) => project.branches.map((branchName) => manifestCheckoutKey(project.projectId, branchName)))
+        );
+        const scopedPendingTargets = [...pendingManifestCheckouts.values()].filter(
+          (target) => allowedCheckoutKeys.has(manifestCheckoutKey(target.projectId, target.branchName))
+        );
         let checkoutTargets = [];
         if (shouldEnsureCheckouts) {
-          checkoutTargets = trigger.type === "connect" ? allManifestCheckouts() : [...pendingManifestCheckouts.values()];
+          checkoutTargets = workspaceSyncCheckoutTargets({
+            projects: syncProjects,
+            pendingTargets: scopedPendingTargets,
+            includeAllManifestCheckouts: trigger.type === "connect",
+            ...trigger.canonicalCheckoutOnly && trigger.projectId && trigger.branchName ? { canonicalCheckoutOnly: { projectId: trigger.projectId, branchName: trigger.branchName } } : {}
+          });
         }
-        pendingTargets = shouldEnsureCheckouts ? [...pendingManifestCheckouts.values()] : [];
-        const createdCheckouts = ensureVisibleWorkspaceCheckouts(checkoutTargets);
+        pendingTargets = shouldEnsureCheckouts ? scopedPendingTargets : [];
+        const createdCheckouts = ensureVisibleWorkspaceCheckouts(checkoutTargets, {
+          strictCanonicalRevalidation: true
+        });
         const newVisibleCheckoutByKey = /* @__PURE__ */ new Map();
         for (const target of [...overrides.newVisibleCheckouts ?? [], ...createdCheckouts, ...pendingTargets]) {
-          newVisibleCheckoutByKey.set(manifestCheckoutKey(target.projectId, target.branchName), target);
+          const key = manifestCheckoutKey(target.projectId, target.branchName);
+          if (allowedCheckoutKeys.has(key)) newVisibleCheckoutByKey.set(key, target);
         }
         const newVisibleCheckouts = [...newVisibleCheckoutByKey.values()];
         return workspaceSyncInput(trigger, {
@@ -2367,7 +2568,9 @@ async function startWorker(options) {
         version: getWorkerVersion(),
         r5dctlVersion: (0, import_cli_update.readInstalledCliVersion)("r5dctl"),
         capabilities: {
-          updateClis: true
+          updateClis: true,
+          canonicalResolverCheckout: true,
+          browserPortForwarding: true
         },
         projectRoot: projectsRoot,
         artifactRoot,
@@ -2427,7 +2630,15 @@ async function startWorker(options) {
             if (!workspaceRemoteUrl || activeWorkspaceIncidentId || cliUpdateInProgress || periodicWorkspaceScanInFlight) return;
             periodicWorkspaceScanInFlight = true;
             void (async () => {
-              if (pendingManifestCheckouts.size > 0) {
+              const genericCheckoutKeys = new Set(
+                (0, import_workspace_sync.workspaceProjectsForSync)([...manifestByProjectId.values()], { type: "periodic" }).flatMap(
+                  (project) => project.branches.map((branchName) => manifestCheckoutKey(project.projectId, branchName))
+                )
+              );
+              const hasPendingGenericCheckout = [...pendingManifestCheckouts.values()].some(
+                (target) => genericCheckoutKeys.has(manifestCheckoutKey(target.projectId, target.branchName))
+              );
+              if (hasPendingGenericCheckout) {
                 previousPeriodicFingerprint = null;
                 await runRequestedWorkspaceSync(crypto.randomUUID(), {
                   type: "periodic",
@@ -2512,6 +2723,17 @@ async function startWorker(options) {
         pendingProcessTerminals.delete(message.runId);
         return;
       }
+      if (message.type === "port_forward_connect") {
+        (0, import_port_forward_client.openWorkerPortForwardRelay)({
+          baseUrl,
+          token,
+          label,
+          forwardId: message.forwardId,
+          relayConnectionId: message.relayConnectionId,
+          workerPort: message.workerPort
+        });
+        return;
+      }
       if (message.type === "update_clis") {
         if (cliUpdateInProgress) {
           sendWorkerMessage(ws, {
@@ -2845,5 +3067,8 @@ if (isCliEntrypoint()) {
   resolveHostShell,
   resolveWorkerFilePath,
   syncSessionArtifacts,
+  visibleCheckoutGitTestHarness,
+  visibleCheckoutRemoteFor,
+  workspaceSyncCheckoutTargets,
   writeWorkerTextFile
 });

package/dist/cjs/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@ricsam/r5d-worker",
-  "version": "0.0.46",
+  "version": "0.0.48",
   "type": "commonjs"
 }

package/dist/cjs/port-forward-client.cjs

@@ -0,0 +1,148 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var port_forward_client_exports = {};
+__export(port_forward_client_exports, {
+  openWorkerPortForwardRelay: () => openWorkerPortForwardRelay
+});
+module.exports = __toCommonJS(port_forward_client_exports);
+var import_node_net = __toESM(require("node:net"), 1);
+var import_ws = __toESM(require("ws"), 1);
+const RELAY_FRAME_BYTES = 64 * 1024;
+const RELAY_PAUSE_BYTES = 1024 * 1024;
+const RELAY_RESUME_BYTES = 256 * 1024;
+function relayUrl(baseUrl, label, forwardId, relayConnectionId) {
+  const url = new URL("/worker/port-forward/ws", baseUrl);
+  url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+  url.searchParams.set("label", label);
+  url.searchParams.set("forward", forwardId);
+  url.searchParams.set("connection", relayConnectionId);
+  return url.toString();
+}
+function rawDataBuffer(data) {
+  if (Buffer.isBuffer(data)) return data;
+  if (Array.isArray(data)) return Buffer.concat(data);
+  return Buffer.from(data);
+}
+function openWorkerPortForwardRelay(options) {
+  const socket = import_node_net.default.createConnection({ host: "127.0.0.1", port: options.workerPort, allowHalfOpen: true });
+  socket.pause();
+  socket.setNoDelay(true);
+  const relay = new import_ws.default(relayUrl(options.baseUrl, options.label, options.forwardId, options.relayConnectionId), {
+    headers: { Authorization: `Bearer ${options.token}` },
+    perMessageDeflate: false
+  });
+  let relayReady = false;
+  let targetReady = false;
+  const pendingChunks = [];
+  let pendingBytes = 0;
+  let closing = false;
+  let resumeTimer;
+  const maybeResume = () => {
+    if (relayReady && targetReady && !resumeTimer) socket.resume();
+  };
+  const cleanup = () => {
+    if (closing) return;
+    closing = true;
+    if (resumeTimer) clearInterval(resumeTimer);
+    socket.destroy();
+    if (relay.readyState === import_ws.default.OPEN || relay.readyState === import_ws.default.CONNECTING) relay.close();
+  };
+  const sendError = (message) => {
+    if (relay.readyState === import_ws.default.OPEN) relay.send(JSON.stringify({ type: "error", error: message }));
+    cleanup();
+  };
+  const waitForRelayDrain = () => {
+    if (resumeTimer || relay.bufferedAmount <= RELAY_PAUSE_BYTES) return;
+    socket.pause();
+    resumeTimer = setInterval(() => {
+      if (relay.readyState !== import_ws.default.OPEN) return cleanup();
+      if (relay.bufferedAmount > RELAY_RESUME_BYTES) return;
+      clearInterval(resumeTimer);
+      resumeTimer = void 0;
+      maybeResume();
+    }, 10);
+  };
+  const sendChunk = (chunk) => {
+    for (let offset = 0; offset < chunk.byteLength; offset += RELAY_FRAME_BYTES) {
+      relay.send(chunk.subarray(offset, Math.min(chunk.byteLength, offset + RELAY_FRAME_BYTES)), { binary: true });
+    }
+    waitForRelayDrain();
+  };
+  socket.once("connect", () => {
+    targetReady = true;
+    maybeResume();
+  });
+  socket.on("data", (chunk) => {
+    if (!relayReady || relay.readyState !== import_ws.default.OPEN) {
+      pendingBytes += chunk.byteLength;
+      if (pendingBytes > RELAY_PAUSE_BYTES) return cleanup();
+      pendingChunks.push(Buffer.from(chunk));
+      socket.pause();
+      return;
+    }
+    sendChunk(chunk);
+  });
+  socket.on("end", () => {
+    if (relay.readyState === import_ws.default.OPEN) relay.send(JSON.stringify({ type: "end" }));
+  });
+  socket.on("error", (error) => sendError(`Could not connect to 127.0.0.1:${options.workerPort}: ${error.message}`));
+  socket.on("close", cleanup);
+  relay.on("message", (data, isBinary) => {
+    if (!isBinary) {
+      let control;
+      try {
+        control = JSON.parse(rawDataBuffer(data).toString("utf8"));
+      } catch {
+        return cleanup();
+      }
+      if (control.type === "ready") {
+        relayReady = true;
+        for (const chunk of pendingChunks.splice(0)) sendChunk(chunk);
+        pendingBytes = 0;
+        maybeResume();
+      } else if (control.type === "end") {
+        socket.end();
+      } else if (control.type === "error") {
+        socket.destroy(new Error(control.error || "Port-forward relay failed."));
+      }
+      return;
+    }
+    if (!socket.write(rawDataBuffer(data))) {
+      relay.pause();
+      socket.once("drain", () => relay.resume());
+    }
+  });
+  relay.once("error", cleanup);
+  relay.once("close", cleanup);
+  socket.pause();
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  openWorkerPortForwardRelay
+});