@inthedark/wb 0.0.7 → 0.0.9

package/README.md

@@ -21,34 +21,63 @@ npx @inthedark/wb
 npx @inthedark/wb connect
 ```
 
+## philosophies
+
+- what the human says goes
+- harnesses should own agent mistake prevention via mechanical tools. make mistakes impossible or difficult to walk into
+- for projects sandboxes are the right approach
+- allow the user to do anything in minimal clicks
+- reinventing the wheel is worth it way more than in the past
+
 ## features
 
-key features:
-- fully customisable agent instructions with support for comments & imports
-- strong thread transcript UX for when you need to keep an eye on a thread (command matching + html elements for agents)
-- strong thread management UX for when you're managing LOTS of threads (thread status-sorted sidebar)
-- better shared workspace support than any other agentic ide, because a lot of work is not worktree->pr shaped; agents claim the files they need and other agents don't freak out about unclaimed dirt
-- near-identical agent behaviour across providers (codex, opencode 2, claude code) as if they're the same harness
-- agents can orchestrate subagents working in threads across providers and projects
-- customisable voice to text ("what if voice to text was like working in a rich text editor")
-- git UI for doing your own work at the same time as other agents, allowing easy commits while agents have other files claimed
-- quickly switch between saved profiles for harness/model/effort/window/fast mode/agent identity
-- automatic compaction on turn start past configurable time & token thresholds (reduce cache write costs)
-- agents can search repos with shell tools like they're on disk via vfs
+selling points first:
+
+#### first class shared workspace support
+a lot of work is not worktree->pr shaped; agents claim the files they need and other agents don't freak out about workspace dirt, they don't *see* it. they queue up behind each other for their claims. even has a git view that helps you easily commit unclaimed dirt
+
+#### fully customisable instructions
+base instructions get improved constantly; but YOUR CONTROL is important. you can override it piecemeal or in entirety, *with* support for comments & imports
+
+#### consolidated tool & sandbox behaviour across harnesses
+codex, opencode 2, and claude code agents all have workbench tools and only the most basic of their native tools left like edit tools
+
+#### customisable voice to text
+what if voice to text was like telling someone what to do in a rich text editor
 
-setup/meta:
+#### webdev mockups using real project components & css
+configure build+css scripts to handle the agent's created tsx
+
+#### .env secrets
+store secrets in ui, reference from .env, see dedicated docs below
+
+#### agents can search repos with comfy shell fs tools
+vfs-powered, so doesn't require the repo being on disk entirely
+
+### ux
+- thread status inbox, snooze threads while working to make them hide until done
+- human readable displays for common shell commands
+- near-instant loads
+- smooth per-token animations, or animate in whole blocks if you prefer
+
+### obligatory
 - built on top of other harnesses (codex, opencode 2, claude code) so you can use subscriptions
+- cross-harness subagents
+- browser use
+- saved profiles for harness/model/effort/window/fast mode/agent identity
+- mcp servers (agents must ask to enable tools by default)
+
+### misc
+- automatic compaction on turn start past configurable time & token thresholds (reduce cache write costs)
 - tailscale integration
 - daemon sleeps when idle, leaving only a light http wake service up
 
-unpolished/unfinished/broken stuff (coming soon tm!!!!!):
+### unpolished/unfinished/broken stuff (coming soon tm!!!!!)
 - soon, autocomplete/suggestions extension for vscode & similar (highly configurable, able to be FAST)
 - worktree->pr workflow is unsupported (gonna be honest i have been in a cave working solo on wb for so long that i have not needed this yet)
-- browse AX & UX
 - search UX
 - i'd like more git ui
-- many places around the app could use a UI polish pass
-- the codebase itself could use a polish pass, esp. the react & tailwind
+- the codebase's refactors from its (very) humble beginnings are not complete
 
 ## tech
 
@@ -58,7 +87,8 @@ note: have tried to keep dependencies minimal for the most part
 `/daemon/host` — wake service  
 `/daemon/server` — workbench harness  
 `/daemon/voice` — vtt service (rust)  
-`/daemon/repo` — vfs service (go)
+`/daemon/repo` — vfs service (go)  
+`/daemon/relay` — linux sandbox loopback relay (go)  
 `/integration` — integrations in third party software
 `/instructions` — instructions for agents, copied into the user's `~/.workbench` folder whenever read  
 `/app/server` — server for frontend app  

package/WorkbenchArcTree.d.mts

@@ -0,0 +1,71 @@
+/*
+ * Exports:
+ * - WorkbenchArcTreeOptions: cwd, hold-own, environment, fetch, cancellation and warning boundaries for loading.
+ * - WorkbenchArcTreeRepository: one repository's daemon view: tree, HEAD and other threads' held paths.
+ * - WorkbenchArcTreeNodeEnvironmentOptions: base environment and manifest parent directory for Node children.
+ * - default WorkbenchArcTree: the worktree as the calling agent thread builds it, readable in process and by Node
+ *   children; the plain filesystem outside agent threads or when the daemon view fails.
+ */
+export interface WorkbenchArcTreeOptions {
+  /** Directory whose repositories to view; relative reads resolve from it. Defaults to `process.cwd()`. */
+  cwd?: string;
+  /** Hold the caller's own dirty claims back too, for a matched "before" build. */
+  holdOwn?: boolean;
+  /** Agent identity and data root come from here. Defaults to `process.env`. */
+  env?: NodeJS.ProcessEnv;
+  fetch?: typeof globalThis.fetch;
+  /** Aborting stops the daemon request and Git reads, and rejects instead of falling back. */
+  signal?: AbortSignal;
+  /** Fallback and dropped-entry notices. Silent by default. */
+  warn?: (message: string) => void;
+}
+
+export interface WorkbenchArcTreeRepository {
+  /** Absolute repository root. */
+  root: string;
+  head: string | null;
+  /** Git tree of the worktree as the caller builds it. */
+  tree: string;
+  /** Repository-relative paths each other thread holds. */
+  held: ReadonlyArray<{ threadId: string; paths: readonly string[] }>;
+}
+
+export interface WorkbenchArcTreeNodeEnvironmentOptions {
+  /** `NODE_OPTIONS` is appended to, not replaced. Defaults to `process.env`. */
+  env?: NodeJS.ProcessEnv;
+  /** Parent of the manifest directory, relative to `cwd`. Defaults to `node_modules/.cache/wb-arc-tree`. Only the first call's value applies. */
+  directory?: string;
+}
+
+export default class WorkbenchArcTree implements AsyncDisposable {
+  private constructor();
+  /**
+   * Outside agent threads, the plain filesystem without asking the daemon. A daemon or Git failure warns and also
+   * yields the plain filesystem, so callers still run, visibly against the live worktree. Never rejects for
+   * unavailability; only `signal` aborts reject.
+   */
+  static load(options?: WorkbenchArcTreeOptions): Promise<WorkbenchArcTree>;
+  /** A tree holding `files` (paths relative to `cwd`; null where the tree lacks them) without asking the daemon. */
+  static fromFiles(cwd: string, files: ReadonlyMap<string, Buffer | null>, repositories?: readonly WorkbenchArcTreeRepository[]): WorkbenchArcTree;
+
+  readonly source: "arc" | "filesystem";
+  readonly cwd: string;
+  /** Absolute held paths mapped to arc tree bytes, or null where the arc tree lacks them. Unlisted paths read from disk. */
+  readonly files: ReadonlyMap<string, Buffer | null>;
+  readonly repositories: readonly WorkbenchArcTreeRepository[];
+  readonly isEmpty: boolean;
+
+  /** Held bytes, ENOENT where the arc tree lacks the path, otherwise disk. */
+  readFile(path: string): Promise<Buffer>;
+  readFile(path: string, encoding: BufferEncoding): Promise<string>;
+  exists(path: string): boolean;
+  /** Absolute held paths this tree has but disk lacks; in-process reads see them, Node children cannot. */
+  readonly deletedOnDisk: string[];
+  /**
+   * Variables to merge into a Node child's environment so it and its Node descendants read this tree. Empty when
+   * nothing is held. Writes a manifest that `dispose` removes.
+   */
+  nodeEnvironment(options?: WorkbenchArcTreeNodeEnvironmentOptions): Promise<Record<string, string>>;
+  dispose(): Promise<void>;
+  [Symbol.asyncDispose](): Promise<void>;
+}

package/WorkbenchArcTree.mjs

@@ -0,0 +1,185 @@
+/*
+ * Exports:
+ * - default WorkbenchArcTree: the worktree as the calling agent thread builds it (other threads' held paths at the
+ *   caller's arc baseline, everything else from disk), with in-process reads and a Node child-process environment.
+ *   Falls back to the plain filesystem outside agent threads or when the daemon view fails.
+ */
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { ARC_TREE_MANIFEST_ENV, arcTreePathKey, writeArcTreeManifest } from "./arc-tree-manifest.mjs";
+import { daemonGitArcIdentity, requestDaemonGitArc } from "./workbench-daemon.mjs";
+
+const TREE_SHA = /^[0-9a-f]{40}(?:[0-9a-f]{24})?$/u;
+
+function nonEmptyString(value) {
+  return typeof value === "string" && value.length > 0;
+}
+
+/** Keep every well-formed repository and held entry; each malformed one drops only itself. */
+function conformRepositories(body, warn) {
+  if (!body || typeof body !== "object" || !Array.isArray(body.repositories)) {
+    throw new Error("the daemon's arc tree response lacks repositories");
+  }
+  let dropped = 0;
+  const repositories = body.repositories.flatMap((repository) => {
+    if (!repository || typeof repository !== "object" || !nonEmptyString(repository.repoRoot) || !TREE_SHA.test(String(repository.tree))) {
+      dropped++;
+      return [];
+    }
+    const held = (Array.isArray(repository.held) ? repository.held : []).flatMap((entry) => {
+      if (!entry || typeof entry !== "object" || !nonEmptyString(entry.threadId) || !Array.isArray(entry.paths)) {
+        dropped++;
+        return [];
+      }
+      const paths = entry.paths.filter(nonEmptyString);
+      dropped += entry.paths.length - paths.length;
+      return [{ threadId: entry.threadId, paths }];
+    });
+    const head = typeof repository.head === "string" && TREE_SHA.test(repository.head) ? repository.head : null;
+    return [{ root: path.resolve(repository.repoRoot), head, tree: repository.tree, held }];
+  });
+  if (dropped) warn(`Workbench arc tree dropped ${dropped} malformed daemon entr${dropped === 1 ? "y" : "ies"}; their paths read from disk.`);
+  return repositories;
+}
+
+async function git(root, args, { input = "", signal } = {}) {
+  const child = spawn("git", args, { cwd: root, signal, stdio: ["pipe", "pipe", "pipe"], windowsHide: true });
+  const stdout = [];
+  const stderr = [];
+  child.stdout.on("data", (chunk) => stdout.push(chunk));
+  child.stderr.on("data", (chunk) => stderr.push(chunk));
+  const exit = new Promise((resolve, reject) => {
+    child.once("error", reject);
+    child.once("close", resolve);
+  });
+  child.stdin.end(input);
+  if (await exit !== 0) throw new Error(`git ${args[0]} failed: ${Buffer.concat(stderr).toString().trim()}`);
+  return Buffer.concat(stdout);
+}
+
+/**
+ * Each path's bytes in `tree` as a checkout would write them, or null where the tree lacks it. Batch reads skip
+ * checkout filters, so only the existence check is batched.
+ */
+async function readTreeFiles(root, tree, paths, signal) {
+  if (paths.some((relative) => relative.includes("\n"))) throw new Error("held paths containing newlines cannot be read from Git");
+  const checks = paths.length
+    ? (await git(root, ["cat-file", "--batch-check"], { input: paths.map((relative) => `${tree}:${relative}\n`).join(""), signal })).toString().split("\n")
+    : [];
+  return await Promise.all(paths.map(async (relative, index) => {
+    const target = path.resolve(root, relative);
+    if (checks[index].endsWith(" missing")) return [target, null];
+    const [, type] = checks[index].split(" ");
+    if (type !== "blob") throw new Error(`${relative} is a ${type} in the arc tree, not a file`);
+    return [target, await git(root, ["cat-file", "--filters", `${tree}:${relative}`], { signal })];
+  }));
+}
+
+function missing(target) {
+  return Object.assign(new Error(`ENOENT: no such file or directory, open '${target}'`), {
+    code: "ENOENT", errno: -os.constants.errno.ENOENT, path: target, syscall: "open",
+  });
+}
+
+export default class WorkbenchArcTree {
+  #held;
+  #manifest = null;
+
+  constructor(source, cwd, files, repositories) {
+    this.source = source;
+    this.cwd = cwd;
+    this.files = files;
+    this.repositories = repositories;
+    this.#held = new Map([...files].map(([target, content]) => [arcTreePathKey(target), content]));
+  }
+
+  static async load({ cwd = process.cwd(), holdOwn = false, env = process.env, fetch, signal, warn = () => {} } = {}) {
+    const root = path.resolve(cwd);
+    signal?.throwIfAborted();
+    if (!daemonGitArcIdentity(env)) return new WorkbenchArcTree("filesystem", root, new Map(), []);
+    try {
+      const repositories = conformRepositories(
+        await requestDaemonGitArc({ action: "arcTree", cwd: root, holdOwn, paths: [] }, { env, fetch, signal }),
+        warn,
+      );
+      if (!repositories.length) throw new Error(`no Workbench arc covers ${root}`);
+      const files = new Map();
+      for (const repository of repositories) {
+        const held = [...new Set(repository.held.flatMap(({ paths }) => paths))];
+        for (const [target, content] of await readTreeFiles(repository.root, repository.tree, held, signal)) files.set(target, content);
+      }
+      return new WorkbenchArcTree("arc", root, files, repositories);
+    } catch (error) {
+      signal?.throwIfAborted();
+      warn(`Workbench arc tree unavailable (${error instanceof Error ? error.message : String(error)}); reading the filesystem, including other threads' live edits.`);
+      return new WorkbenchArcTree("filesystem", root, new Map(), []);
+    }
+  }
+
+  static fromFiles(cwd, files, repositories = []) {
+    const root = path.resolve(cwd);
+    return new WorkbenchArcTree("arc", root, new Map([...files].map(([relative, content]) => [path.resolve(root, relative), content])), repositories);
+  }
+
+  get isEmpty() {
+    return !this.files.size;
+  }
+
+  async readFile(target, encoding) {
+    const resolved = path.resolve(this.cwd, target);
+    const content = this.#held.get(arcTreePathKey(resolved));
+    if (content === undefined) return await fs.promises.readFile(resolved, encoding ? { encoding } : undefined);
+    if (content === null) throw missing(resolved);
+    return encoding ? content.toString(encoding) : Buffer.from(content);
+  }
+
+  exists(target) {
+    const resolved = path.resolve(this.cwd, target);
+    const content = this.#held.get(arcTreePathKey(resolved));
+    return content === undefined ? fs.existsSync(resolved) : content !== null;
+  }
+
+  get deletedOnDisk() {
+    return [...this.files].flatMap(([target, content]) => content !== null && !fs.existsSync(target) ? [target] : []);
+  }
+
+  async nodeEnvironment({ env = process.env, directory } = {}) {
+    if (this.isEmpty) return {};
+    this.#manifest ??= this.#writeManifest(path.resolve(this.cwd, directory ?? path.join("node_modules", ".cache", "wb-arc-tree")));
+    let file;
+    try {
+      ({ file } = await this.#manifest);
+    } catch (error) {
+      this.#manifest = null;
+      throw error;
+    }
+    const preload = `--import ${new URL("./arc-tree-preload.mjs", import.meta.url).href}`;
+    return { [ARC_TREE_MANIFEST_ENV]: file, NODE_OPTIONS: env.NODE_OPTIONS ? `${env.NODE_OPTIONS} ${preload}` : preload };
+  }
+
+  async #writeManifest(parent) {
+    await fs.promises.mkdir(parent, { recursive: true });
+    const directory = await fs.promises.mkdtemp(path.join(parent, "manifest-"));
+    const file = path.join(directory, "manifest.json");
+    try {
+      await writeArcTreeManifest(file, this.files);
+    } catch (error) {
+      await fs.promises.rm(directory, { force: true, recursive: true });
+      throw error;
+    }
+    return { directory, file };
+  }
+
+  async dispose() {
+    const manifest = this.#manifest;
+    this.#manifest = null;
+    const written = await manifest?.catch(() => null);
+    if (written) await fs.promises.rm(written.directory, { force: true, maxRetries: 5, recursive: true, retryDelay: 50 });
+  }
+
+  async [Symbol.asyncDispose]() {
+    await this.dispose();
+  }
+}

package/WorkbenchBootstrap.mjs

@@ -1,18 +1,18 @@
 /*
  * Exports:
- * - WorkbenchBootstrap (default): locates or installs an editable checkout and delegates to it.
+ * - WorkbenchBootstrap (default): locates or installs an editable checkout and delegates to it; `run` resolves a delegated exit code.
  */
 import fs from "node:fs/promises";
 import { constants } from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { randomUUID } from "node:crypto";
 import { fileURLToPath } from "node:url";
-import { DatabaseSync } from "node:sqlite";
+import WorkbenchInstallationRecord from "./WorkbenchInstallationRecord.mjs";
 import WorkbenchInstallPrompt from "./WorkbenchInstallPrompt.mjs";
-import WorkbenchBootstrapCommand from "./WorkbenchBootstrapCommand.mjs";
+import WorkbenchBootstrapCommand, { WorkbenchChildExitError } from "./WorkbenchBootstrapCommand.mjs";
 import WorkbenchToolchain from "./WorkbenchToolchain.mjs";
 import WorkbenchPackageRegistration from "./WorkbenchPackageRegistration.mjs";
+import resolveWorkbenchDataRoot from "./workbench-data-root.mjs";
 
 export default class WorkbenchBootstrap {
   constructor({
@@ -35,7 +35,9 @@ export default class WorkbenchBootstrap {
     this.toolchain = toolchain;
     this.registration = registration;
     this.write = write;
-    this.registry = path.join(home, ".workbench", "installation.json");
+    this.installation = new WorkbenchInstallationRecord({
+      dataRoot: resolveWorkbenchDataRoot({ environment, homeDirectory: home, platform }),
+    });
   }
 
   async checkoutExists(root) {
@@ -63,26 +65,6 @@ export default class WorkbenchBootstrap {
     }
   }
 
-  async readInstallation() {
-    try {
-      const record = JSON.parse(await fs.readFile(this.registry, "utf8"));
-      if (record.version !== 1 || typeof record.root !== "string" || !path.isAbsolute(record.root)
-        || !["cloning", "setup", "ready"].includes(record.phase)) {
-        throw new Error(`Invalid Workbench installation record: ${this.registry}. Existing files were not changed.`);
-      }
-      return record;
-    } catch (error) {
-      if (error.code === "ENOENT") return null;
-      throw error;
-    }
-  }
-
-  async writeInstallation(record) {
-    const candidate = `${this.registry}.${randomUUID()}.tmp`;
-    await fs.writeFile(candidate, `${JSON.stringify(record, null, 2)}\n`, { flag: "wx", mode: 0o600 });
-    await fs.rename(candidate, this.registry);
-  }
-
   async requireTool(command, cwd) {
     try {
       await this.commands.run(command, ["--version"], {
@@ -105,7 +87,7 @@ export default class WorkbenchBootstrap {
     if (await this.checkoutExists(linked)) {
       return await this.delegate(linked, args);
     }
-    const installed = await this.readInstallation();
+    const installed = await this.installation.read();
     if (installed?.phase === "ready") {
       const state = await this.checkoutState(installed.root);
       if (state === "usable") return await this.delegate(installed.root, args);
@@ -130,21 +112,10 @@ export default class WorkbenchBootstrap {
       ? path.join(this.environment.LOCALAPPDATA || path.join(this.home, "AppData", "Local"), "Programs", "inthedark", "wb")
       : path.join(this.home, ".local", "lib", "inthedark", "wb"));
     const root = path.resolve(await this.prompt.location("Install location", defaultRoot));
-    await fs.mkdir(path.dirname(this.registry), { recursive: true });
-    const lockPath = `${this.registry}.lock.sqlite3`;
-    const lock = new DatabaseSync(lockPath);
-    try {
-      lock.exec("PRAGMA busy_timeout = 0; BEGIN EXCLUSIVE");
-    } catch (error) {
-      lock.close();
-      if (error.errcode === 5 || error.errcode === 6) {
-        throw new Error("Another Workbench installation is running. Let it finish before trying again.");
-      }
-      throw error;
-    }
+    const lock = await this.installation.lock();
     try {
       // Another invocation may have finished while this one was accepting input.
-      const latest = await this.readInstallation();
+      const latest = await this.installation.read();
       if (latest?.phase === "ready") {
         const state = await this.checkoutState(latest.root);
         if (state === "usable") return await this.delegate(latest.root, args);
@@ -158,7 +129,7 @@ export default class WorkbenchBootstrap {
       const resume = latest?.root === root && await this.checkoutExists(root);
       if (!resume) await this.requireEmptyDestination(root);
       // Recording before provisioning keeps the chosen location as the next default if anything fails.
-      await this.writeInstallation({ version: 1, root, phase: resume ? "setup" : "cloning" });
+      await this.installation.write({ version: 1, root, phase: resume ? "setup" : "cloning" });
       await this.registration.prepare();
       await this.toolchain.ensure();
       await this.prompt.withHeader(async () => {
@@ -168,15 +139,13 @@ export default class WorkbenchBootstrap {
           const repository = this.environment.WORKBENCH_INSTALL_REPOSITORY || "https://github.com/ErisInTheDark/workbench.git";
           await this.commands.run("git", ["clone", "--progress", "--branch", "main", "--single-branch", repository, root]);
           if (!await this.checkoutExists(root)) throw new Error("Clone did not produce a Workbench checkout.");
-          await this.writeInstallation({ version: 1, root, phase: "setup" });
+          await this.installation.write({ version: 1, root, phase: "setup" });
         }
         await this.commands.run(process.execPath, [path.join(root, "scripts", "install.mjs"), "--prepare"], { cwd: root });
         await this.registration.register(root);
       });
-      await this.writeInstallation({ version: 1, root, phase: "ready" });
+      await this.installation.write({ version: 1, root, phase: "ready" });
     } finally {
-      // Closing the connection also releases the OS lock after normal completion;
-      // process death releases it without a stale PID or lock-file recovery path.
       lock.close();
     }
     // Persist readiness before optional platform actions: missing native artifacts
@@ -185,8 +154,15 @@ export default class WorkbenchBootstrap {
       args[0] === "connect" ? "--connect" : "--welcome"], { cwd: root, interactive: true });
   }
 
+  /** Resolves the checkout CLI's exit code; it already reported its own failure. */
   async delegate(root, args) {
-    return await this.commands.run(process.execPath, [path.join(root, "cli", "dispatch.mjs"), ...args], { interactive: true });
+    try {
+      await this.commands.run(process.execPath, [path.join(root, "cli", "dispatch.mjs"), ...args], { interactive: true });
+      return 0;
+    } catch (error) {
+      if (error instanceof WorkbenchChildExitError) return error.exitCode;
+      throw error;
+    }
   }
 
   async requireEmptyDestination(root) {

package/WorkbenchBootstrapCommand.mjs

@@ -1,11 +1,33 @@
 /*
  * Exports:
- * - WorkbenchBootstrapCommand (default): owns bootstrap child commands, Windows executable lookup (including Git Bash), and failures.
+ * - WorkbenchBootstrapCommand (default): owns bootstrap child commands, Windows executable lookup (including Git Bash), process-tree cancellation, and failures.
+ * - WorkbenchChildExitError: a child exited with a non-zero status after reporting its own failure; delegators propagate `exitCode` silently.
  */
 import { spawn } from "node:child_process";
 import fs from "node:fs/promises";
 import path from "node:path";
 
+function stopTree(child) {
+  if (child.exitCode !== null || child.signalCode !== null || !child.pid) return;
+  if (process.platform === "win32") {
+    // A denied or failed tree kill still stops the direct child.
+    const killer = spawn("taskkill", ["/PID", String(child.pid), "/T", "/F"], { windowsHide: true, stdio: "ignore" });
+    killer.once("error", () => { child.kill(); });
+    killer.once("exit", code => { if (code !== 0) child.kill(); });
+    return;
+  }
+  try { process.kill(-child.pid, "SIGTERM"); }
+  catch (error) { if (error.code !== "ESRCH") child.kill("SIGTERM"); }
+}
+
+export class WorkbenchChildExitError extends Error {
+  constructor(command, exitCode) {
+    super(`${command} failed with status ${exitCode}.`);
+    this.name = "WorkbenchChildExitError";
+    this.exitCode = exitCode;
+  }
+}
+
 export default class WorkbenchBootstrapCommand {
   constructor({ output = process.stdout, errorOutput = process.stderr, environment = process.env } = {}) {
     this.output = output;
@@ -115,19 +137,28 @@ export default class WorkbenchBootstrapCommand {
     throw new Error(`Workbench needs Git Bash on Windows.${sawLauncher ? " The bash on PATH is WSL's, which cannot run Workbench." : ""} Install Git for Windows, then retry.`);
   }
 
+  /** Cancelling a non-interactive run stops the child's whole process tree; wrappers like vp otherwise orphan their workers. */
   async run(command, args, { cwd, signal, onOutput, environment = {}, output = this.output, errorOutput = this.errorOutput, interactive = false } = {}) {
     signal?.throwIfAborted();
     const [executable, ...prefix] = await this.resolve(command);
     signal?.throwIfAborted();
+    const tree = Boolean(signal) && !interactive;
     return await new Promise((resolve, reject) => {
       const child = spawn(executable, [...prefix, ...args], {
         cwd,
         env: this.environmentFor(environment),
         windowsHide: true,
         stdio: interactive ? "inherit" : ["ignore", "pipe", "pipe"],
-        signal,
+        // A POSIX process group lets one signal reach every descendant.
+        ...(tree ? { detached: process.platform !== "win32" } : { signal }),
       });
       let failure;
+      let cancelled = false;
+      const cancel = () => {
+        cancelled = true;
+        stopTree(child);
+      };
+      if (tree) signal.addEventListener("abort", cancel, { once: true });
       const relay = signal => { child.kill(signal); };
       const interrupt = () => relay("SIGINT");
       const terminate = () => relay("SIGTERM");
@@ -157,13 +188,17 @@ export default class WorkbenchBootstrapCommand {
           process.off("SIGTERM", terminate);
           process.off("SIGHUP", hangup);
         }
-        if (failure?.code === "ENOENT") {
+        if (tree) signal.removeEventListener("abort", cancel);
+        if (cancelled) {
+          reject(Object.assign(new Error(`${command} was cancelled.`, { cause: signal.reason }), { name: "AbortError", code: "ABORT_ERR" }));
+        } else if (failure?.code === "ENOENT") {
           reject(Object.assign(new Error(`Cannot start ${command}: executable not found. Install it and make it available on PATH, then retry.`, { cause: failure }), {
             code: "ENOENT",
           }));
         } else if (failure) reject(failure);
         else if (code === 0) resolve();
-        else reject(Object.assign(new Error(`${command} failed with ${exitSignal ? `signal ${exitSignal}` : `status ${code ?? "unknown"}`}.`), { exitCode: code ?? 1 }));
+        else if (code !== null) reject(new WorkbenchChildExitError(command, code));
+        else reject(Object.assign(new Error(`${command} failed with signal ${exitSignal ?? "unknown"}.`), { exitCode: 1 }));
       });
     });
   }

package/WorkbenchInstallationRecord.d.mts

@@ -0,0 +1,18 @@
+/*
+ * Exports:
+ * - WorkbenchInstallationPhase/WorkbenchInstallationRecordValue: one recorded installation.
+ * - default WorkbenchInstallationRecord: read, write and exclusively lock the data root's installation record.
+ */
+export type WorkbenchInstallationPhase = "cloning" | "setup" | "ready";
+export interface WorkbenchInstallationRecordValue {
+  version: 1;
+  root: string;
+  phase: WorkbenchInstallationPhase;
+}
+export default class WorkbenchInstallationRecord {
+  constructor(options: { dataRoot: string });
+  readonly path: string;
+  read(): Promise<WorkbenchInstallationRecordValue | null>;
+  write(record: WorkbenchInstallationRecordValue): Promise<void>;
+  lock(): Promise<{ close(): void }>;
+}

package/WorkbenchInstallationRecord.mjs

@@ -0,0 +1,57 @@
+/*
+ * Exports:
+ * - default WorkbenchInstallationRecord: read, write and exclusively lock the data root's record of which checkout is installed.
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { DatabaseSync } from "node:sqlite";
+
+const PHASES = ["cloning", "setup", "ready"];
+
+export default class WorkbenchInstallationRecord {
+  constructor({ dataRoot }) {
+    this.path = path.join(dataRoot, "installation", "installation.json");
+  }
+
+  /** The record, or null when none exists; malformed records reject without being changed. */
+  async read() {
+    try {
+      const record = JSON.parse(await fs.readFile(this.path, "utf8"));
+      if (record.version !== 1 || typeof record.root !== "string" || !path.isAbsolute(record.root)
+        || !PHASES.includes(record.phase)) {
+        throw new Error(`Invalid Workbench installation record: ${this.path}. Existing files were not changed.`);
+      }
+      return record;
+    } catch (error) {
+      if (error.code === "ENOENT") return null;
+      throw error;
+    }
+  }
+
+  async write(record) {
+    await fs.mkdir(path.dirname(this.path), { recursive: true });
+    const candidate = `${this.path}.${randomUUID()}.tmp`;
+    await fs.writeFile(candidate, `${JSON.stringify(record, null, 2)}\n`, { flag: "wx", mode: 0o600 });
+    await fs.rename(candidate, this.path);
+  }
+
+  /**
+   * Holds the installation lock until `close()`. Closing the connection, or process death, releases the OS lock
+   * without a stale PID or lock-file recovery path.
+   */
+  async lock() {
+    await fs.mkdir(path.dirname(this.path), { recursive: true });
+    const lock = new DatabaseSync(`${this.path}.lock.sqlite3`);
+    try {
+      lock.exec("PRAGMA busy_timeout = 0; BEGIN EXCLUSIVE");
+    } catch (error) {
+      lock.close();
+      if (error.errcode === 5 || error.errcode === 6) {
+        throw new Error("Another Workbench installation is running. Let it finish before trying again.");
+      }
+      throw error;
+    }
+    return { close: () => lock.close() };
+  }
+}

package/arc-tree-manifest.mjs

@@ -0,0 +1,41 @@
+// @ts-check
+/*
+ * Exports:
+ * - ARC_TREE_MANIFEST_ENV: environment variable naming the manifest Node processes preload.
+ * - arcTreePathKey: comparable key for an absolute path on this platform's file system.
+ * - writeArcTreeManifest: write held paths and their arc tree bytes for ./arc-tree-preload.mjs.
+ * - readArcTreeManifest: read a manifest into path keys mapped to bytes, or null where the arc tree lacks the path.
+ */
+import fs from "node:fs";
+import path from "node:path";
+
+export const ARC_TREE_MANIFEST_ENV = "WORKBENCH_ARC_OVERLAY_MANIFEST";
+const MANIFEST_VERSION = 1;
+
+/** @param {string} target */
+export function arcTreePathKey(target) {
+  const resolved = path.resolve(target);
+  return process.platform === "win32" || process.platform === "darwin" ? resolved.toLowerCase() : resolved;
+}
+
+/** @param {string} file @param {ReadonlyMap<string, Buffer | null>} files absolute paths */
+export async function writeArcTreeManifest(file, files) {
+  const encoded = Object.fromEntries([...files].map(([target, content]) => [target, content?.toString("base64") ?? null]));
+  await fs.promises.writeFile(file, JSON.stringify({ version: MANIFEST_VERSION, files: encoded }), { flag: "wx" });
+}
+
+/**
+ * @param {string} file
+ * @returns {Map<string, Buffer | null>}
+ */
+export function readArcTreeManifest(file) {
+  /** @type {{ files?: unknown; version?: unknown }} */
+  const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+  if (parsed.version !== MANIFEST_VERSION || !parsed.files || typeof parsed.files !== "object") {
+    throw new Error(`Arc tree manifest ${file} is invalid.`);
+  }
+  return new Map(Object.entries(parsed.files).map(([target, content]) => {
+    if (content !== null && typeof content !== "string") throw new Error(`Arc tree manifest ${file} is invalid.`);
+    return [arcTreePathKey(target), content === null ? null : Buffer.from(content, "base64")];
+  }));
+}

package/arc-tree-preload.mjs

@@ -0,0 +1,160 @@
+// @ts-check
+/*
+ * No exports. Node `--import` preload, plain JavaScript so it loads before any TypeScript loader exists: answer reads of
+ * other threads' held paths from the arc tree manifest, and make paths the caller's arc tree lacks look absent.
+ * Node's module resolver stats files internally, so it still finds hidden files; reading them then fails as missing.
+ */
+import fs from "node:fs";
+import { syncBuiltinESMExports } from "node:module";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { ARC_TREE_MANIFEST_ENV, arcTreePathKey, readArcTreeManifest } from "./arc-tree-manifest.mjs";
+
+/** @typedef {(error: NodeJS.ErrnoException | null, value?: unknown) => void} Callback */
+/** @typedef {(...values: unknown[]) => unknown} LooseFunction */
+
+/** @param {Map<string, Buffer | null>} overlay */
+function install(overlay) {
+  /** @param {unknown} target */
+  const keyOf = (target) => {
+    if (typeof target === "string") return arcTreePathKey(target);
+    if (target instanceof URL) return target.protocol === "file:" ? arcTreePathKey(fileURLToPath(target)) : null;
+    if (Buffer.isBuffer(target)) return arcTreePathKey(target.toString());
+    return null;
+  };
+  /**
+   * @param {unknown} target
+   * @returns {Buffer | null | undefined} undefined when no other thread holds the path
+   */
+  const held = (target) => {
+    const key = keyOf(target);
+    return key === null ? undefined : overlay.get(key);
+  };
+  /** @param {string} syscall @param {unknown} target */
+  const missing = (syscall, target) => Object.assign(
+    new Error(`ENOENT: no such file or directory, ${syscall} '${String(target)}'`),
+    { code: "ENOENT", errno: -os.constants.errno.ENOENT, path: String(target), syscall },
+  );
+  /** @param {Buffer} content @param {unknown} options */
+  const encoded = (content, options) => {
+    const encoding = typeof options === "string"
+      ? /** @type {BufferEncoding} */ (options)
+      : /** @type {{ encoding?: BufferEncoding | null } | undefined} */ (options)?.encoding;
+    return encoding ? content.toString(encoding) : Buffer.from(content);
+  };
+  /** @param {unknown} directory @param {unknown[]} entries */
+  const visible = (directory, entries) => entries.filter((entry) => {
+    const dirent = entry instanceof fs.Dirent ? entry : null;
+    const name = dirent ? dirent.name : entry;
+    if (typeof name !== "string") return true;
+    const parent = dirent ? dirent.parentPath : directory instanceof URL ? fileURLToPath(directory) : String(directory);
+    return overlay.get(arcTreePathKey(path.join(parent, name))) !== null;
+  });
+  /** @param {unknown[]} args */
+  const callbackOf = (args) => /** @type {Callback} */ (args.at(-1));
+  /** @param {Callback} callback @param {NodeJS.ErrnoException | null} error @param {unknown} [value] */
+  const later = (callback, error, value) => process.nextTick(() => callback(error, value));
+
+  const { promises } = fs;
+  const original = {
+    access: /** @type {LooseFunction} */ (fs.access),
+    accessSync: fs.accessSync,
+    existsSync: fs.existsSync,
+    lstat: /** @type {LooseFunction} */ (fs.lstat),
+    lstatSync: /** @type {LooseFunction} */ (fs.lstatSync),
+    promisesAccess: promises.access,
+    promisesLstat: /** @type {LooseFunction} */ (promises.lstat),
+    promisesReadFile: /** @type {LooseFunction} */ (promises.readFile),
+    promisesReaddir: /** @type {LooseFunction} */ (promises.readdir),
+    promisesStat: /** @type {LooseFunction} */ (promises.stat),
+    readFile: /** @type {LooseFunction} */ (fs.readFile),
+    readFileSync: /** @type {LooseFunction} */ (fs.readFileSync),
+    readdir: /** @type {LooseFunction} */ (fs.readdir),
+    readdirSync: /** @type {LooseFunction} */ (fs.readdirSync),
+    stat: /** @type {LooseFunction} */ (fs.stat),
+    statSync: /** @type {LooseFunction} */ (fs.statSync),
+  };
+  /** @param {string} syscall @param {LooseFunction} sync */
+  const statSync = (syscall, sync) => (/** @type {unknown} */ target, /** @type {fs.StatSyncOptions | undefined} */ options) => {
+    if (held(target) !== null) return sync.call(fs, target, options);
+    if (options?.throwIfNoEntry === false) return undefined;
+    throw missing(syscall, target);
+  };
+  /** @param {string} syscall @param {LooseFunction} callbackStat */
+  const statCallback = (syscall, callbackStat) => (/** @type {unknown} */ target, /** @type {unknown[]} */ ...args) => {
+    if (held(target) !== null) return callbackStat.call(fs, target, ...args);
+    later(callbackOf(args), missing(syscall, target));
+  };
+  /** @param {string} syscall @param {LooseFunction} promiseStat */
+  const statPromise = (syscall, promiseStat) => async (/** @type {unknown} */ target, /** @type {unknown} */ options) => {
+    if (held(target) === null) throw missing(syscall, target);
+    return await promiseStat.call(promises, target, options);
+  };
+
+  Object.assign(fs, {
+    /** @param {unknown} target @param {unknown} [options] */
+    readFileSync(target, options) {
+      const content = held(target);
+      if (content === undefined) return original.readFileSync.call(fs, target, options);
+      if (content === null) throw missing("open", target);
+      return encoded(content, options);
+    },
+    /** @param {unknown} target @param {unknown[]} args */
+    readFile(target, ...args) {
+      const content = held(target);
+      if (content === undefined) return original.readFile.call(fs, target, ...args);
+      if (content === null) later(callbackOf(args), missing("open", target));
+      else later(callbackOf(args), null, encoded(content, args.length > 1 ? args[0] : undefined));
+    },
+    /** @param {fs.PathLike} target */
+    existsSync(target) {
+      return held(target) === null ? false : original.existsSync(target);
+    },
+    /** @param {fs.PathLike} target @param {number} [mode] */
+    accessSync(target, mode) {
+      if (held(target) === null) throw missing("access", target);
+      original.accessSync(target, mode);
+    },
+    access: statCallback("access", original.access),
+    statSync: statSync("stat", original.statSync),
+    lstatSync: statSync("lstat", original.lstatSync),
+    stat: statCallback("stat", original.stat),
+    lstat: statCallback("lstat", original.lstat),
+    /** @param {unknown} directory @param {unknown} [options] */
+    readdirSync(directory, options) {
+      return visible(directory, /** @type {unknown[]} */ (original.readdirSync.call(fs, directory, options)));
+    },
+    /** @param {unknown} directory @param {unknown[]} args */
+    readdir(directory, ...args) {
+      const callback = callbackOf(args);
+      original.readdir.call(fs, directory, ...args.slice(0, -1), /** @type {Callback} */ ((error, entries) => {
+        callback(error, error ? undefined : visible(directory, /** @type {unknown[]} */ (entries ?? [])));
+      }));
+    },
+  });
+  Object.assign(promises, {
+    /** @param {unknown} target @param {unknown} [options] */
+    async readFile(target, options) {
+      const content = held(target);
+      if (content === undefined) return await original.promisesReadFile.call(promises, target, options);
+      if (content === null) throw missing("open", target);
+      return encoded(content, options);
+    },
+    /** @param {fs.PathLike} target @param {number} [mode] */
+    async access(target, mode) {
+      if (held(target) === null) throw missing("access", target);
+      await original.promisesAccess(target, mode);
+    },
+    stat: statPromise("stat", original.promisesStat),
+    lstat: statPromise("lstat", original.promisesLstat),
+    /** @param {unknown} directory @param {unknown} [options] */
+    async readdir(directory, options) {
+      return visible(directory, /** @type {unknown[]} */ (await original.promisesReaddir.call(promises, directory, options)));
+    },
+  });
+  syncBuiltinESMExports();
+}
+
+const manifest = process.env[ARC_TREE_MANIFEST_ENV];
+if (manifest) install(readArcTreeManifest(manifest));

package/index.d.ts

@@ -1,9 +1,18 @@
 /*
  * Exports:
- * - WorkbenchConfigOptions: dotenv loading, mutually exclusive missing-value policies, cancellation and warning hooks.
- * - WorkbenchConfigOutput: parsed values after store replacement, with the first file read error.
- * - config: load dotenv and store values; reject missing required names before writing the environment.
+ * - WorkbenchConfigOptions: dotenv mapping, missing-value policies, cancellation and warning hooks.
+ * - WorkbenchConfigOutput: mapped values after store replacement and policy checks, with the first file read error.
+ * - config: load and map dotenv values; resolve stores and check required names before environment writes.
+ * - WorkbenchArcTree/WorkbenchArcTreeOptions/WorkbenchArcTreeRepository/WorkbenchArcTreeNodeEnvironmentOptions: arc tree types.
+ * - arcTree: the worktree as the calling agent thread builds it, or the plain filesystem outside agent threads.
  */
+import type WorkbenchArcTree from "./WorkbenchArcTree.mjs";
+import type { WorkbenchArcTreeOptions } from "./WorkbenchArcTree.mjs";
+
+export type { WorkbenchArcTree };
+export type {
+  WorkbenchArcTreeNodeEnvironmentOptions, WorkbenchArcTreeOptions, WorkbenchArcTreeRepository,
+} from "./WorkbenchArcTree.mjs";
 export type WorkbenchConfigOptions = {
   /** One file or several; earlier files win unless `override` is set. Defaults to `.env`. */
   path?: string | readonly string[];
@@ -11,6 +20,8 @@ export type WorkbenchConfigOptions = {
   /** Replace variables already present in `processEnv`, as dotenv does. */
   override?: boolean;
   processEnv?: Record<string, string | undefined>;
+  /** Map merged parsed values before store resolution and policy checks. Rejection prevents environment writes. */
+  map?: (env: Record<string, string>) => Record<string, string> | Promise<Record<string, string>>;
   /** Aborting kills running store commands and rejects. */
   signal?: AbortSignal;
   /** Opt into bounded lookup warnings that never contain command output. Silent by default. */
@@ -36,3 +47,9 @@ export interface WorkbenchConfigOutput {
  * before any environment writes. Existing environment values win unless override is set.
  */
 export function config(options?: WorkbenchConfigOptions): Promise<WorkbenchConfigOutput>;
+
+/**
+ * Other threads' held paths read at the caller's arc baseline; everything else reads from disk. Outside agent
+ * threads, or when the daemon view fails (reported through `warn`), the plain filesystem. Only `signal` aborts reject.
+ */
+export function arcTree(options?: WorkbenchArcTreeOptions): Promise<WorkbenchArcTree>;

package/index.mjs

@@ -1,11 +1,13 @@
 /*
  * Exports:
- * - config: load dotenv files, resolve named store references, and enforce an optional missing-variable policy.
+ * - config: load and map dotenv values, resolve store references, and enforce an optional missing-variable policy.
+ * - arcTree: load the worktree as the calling agent thread builds it, or the plain filesystem without one.
  */
 import fs from "node:fs/promises";
 import path from "node:path";
 import dotenv from "dotenv";
 import StoreCommandRunner from "./StoreCommandRunner.mjs";
+import WorkbenchArcTree from "./WorkbenchArcTree.mjs";
 import {
   DEFAULT_STORE_DEFINITIONS,
   expandStoreCommand,
@@ -109,10 +111,13 @@ export async function config({
   runner = new StoreCommandRunner(),
   required,
   optional,
+  map,
 } = {}) {
   signal?.throwIfAborted();
   const policy = missingPolicy(required, optional);
-  const { parsed: raw, error } = await readParsed(Array.isArray(paths) ? paths : [paths], encoding, override);
+  const { parsed: input, error } = await readParsed(Array.isArray(paths) ? paths : [paths], encoding, override);
+  const raw = map ? await map(input) : input;
+  signal?.throwIfAborted();
   const definitions = raw.WB_STORES?.trim() || processEnv.WB_STORES?.trim() || DEFAULT_STORE_DEFINITIONS;
   const { parsed, unresolved } = await resolveReferences(raw, definitions, { runner, signal, warn, policy });
   applyMissingPolicy(parsed, unresolved, policy, processEnv, override);
@@ -122,3 +127,7 @@ export async function config({
   dotenv.populate(processEnv, values, { override: policy ? true : override });
   return error ? { parsed, error } : { parsed };
 }
+
+export async function arcTree(options) {
+  return await WorkbenchArcTree.load(options);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inthedark/wb",
-  "version": "0.0.7",
+  "version": "0.0.9",
   "type": "module",
   "repository": {
     "type": "git",
@@ -25,6 +25,8 @@
   "files": [
     "wb",
     "WorkbenchBootstrap.mjs",
+    "WorkbenchInstallationRecord.mjs",
+    "WorkbenchInstallationRecord.d.mts",
     "WorkbenchBootstrapCommand.mjs",
     "WorkbenchToolchain.mjs",
     "WorkbenchPackageRegistration.mjs",
@@ -37,10 +39,16 @@
     "index.d.ts",
     "store-definitions.mjs",
     "StoreCommandRunner.mjs",
+    "WorkbenchArcTree.mjs",
+    "WorkbenchArcTree.d.mts",
+    "arc-tree-manifest.mjs",
+    "arc-tree-preload.mjs",
+    "workbench-daemon.mjs",
+    "workbench-daemon.d.mts",
     "wb.schema.json",
     "README.md"
   ],
   "dependencies": {
-    "dotenv": "^18.0.4"
+    "dotenv": "18.0.4"
   }
 }

package/wb

@@ -4,7 +4,10 @@
  */
 import WorkbenchBootstrap from "./WorkbenchBootstrap.mjs";
 
-try { await new WorkbenchBootstrap().run(process.argv.slice(2)); }
+try {
+  const exitCode = await new WorkbenchBootstrap().run(process.argv.slice(2));
+  if (Number.isInteger(exitCode)) process.exitCode = exitCode;
+}
 catch (error) {
   process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
   process.exitCode = Number.isInteger(error?.exitCode) ? error.exitCode : 1;

package/workbench-daemon.d.mts

@@ -0,0 +1,38 @@
+/*
+ * Exports:
+ * - WorkbenchDaemonEndpoint: validated loopback publication of the running local daemon.
+ * - DaemonGitArcIdentity: harness and thread a Git arc request acts as.
+ * - DaemonGitArcRequest: one Git arc action body, without identity.
+ * - DaemonGitArcRequestOptions: environment, fetch and cancellation boundaries.
+ * - daemonGitArcIdentity: the invoking agent thread's Git arc identity, or null outside agent threads.
+ * - readDaemonEndpoint: read the bounded, loopback-only local daemon publication, or null when none is published.
+ * - requestDaemonGitArc: send one Git arc request as the invoking thread; resolves the raw JSON body for the caller to conform.
+ */
+export interface WorkbenchDaemonEndpoint {
+  version: 1;
+  instanceId: string;
+  pid: number;
+  origin: string;
+}
+
+export interface DaemonGitArcIdentity {
+  harness: string;
+  threadId: string;
+}
+
+export interface DaemonGitArcRequest {
+  action: string;
+  cwd: string;
+  [field: string]: unknown;
+}
+
+export interface DaemonGitArcRequestOptions {
+  env?: NodeJS.ProcessEnv;
+  fetch?: typeof globalThis.fetch;
+  signal?: AbortSignal;
+}
+
+export function daemonGitArcIdentity(env?: NodeJS.ProcessEnv): DaemonGitArcIdentity | null;
+/** Rejects oversized, malformed or non-loopback publications so they never become a daemon address. */
+export function readDaemonEndpoint(file: string): Promise<WorkbenchDaemonEndpoint | null>;
+export function requestDaemonGitArc(request: DaemonGitArcRequest, options?: DaemonGitArcRequestOptions): Promise<unknown>;

package/workbench-daemon.mjs

@@ -0,0 +1,76 @@
+/*
+ * Exports:
+ * - daemonGitArcIdentity: the invoking agent thread's Git arc identity, or null outside agent threads.
+ * - readDaemonEndpoint: read the bounded, loopback-only local daemon publication, or null when none is published.
+ * - requestDaemonGitArc: send one Git arc request as the invoking thread to the published local daemon.
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+import resolveWorkbenchDataRoot from "./workbench-data-root.mjs";
+
+const ENDPOINT_SIZE_LIMIT = 16_384;
+const ENDPOINT_KEYS = ["instanceId", "origin", "pid", "version"];
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu;
+
+export function daemonGitArcIdentity(env = process.env) {
+  const threadId = env.WORKBENCH_THREAD_ID || env.CODEX_THREAD_ID;
+  return threadId ? { harness: env.WORKBENCH_HARNESS || "codex", threadId } : null;
+}
+
+function isLoopbackOrigin(value) {
+  if (typeof value !== "string") return false;
+  try {
+    const url = new URL(value);
+    return url.origin === value && url.protocol === "http:" && url.hostname === "127.0.0.1" && Number(url.port) > 0;
+  } catch {
+    return false;
+  }
+}
+
+function isEndpoint(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  return Object.keys(value).sort().join() === ENDPOINT_KEYS.join()
+    && value.version === 1
+    && typeof value.instanceId === "string" && UUID.test(value.instanceId)
+    && Number.isInteger(value.pid) && value.pid >= 1
+    && isLoopbackOrigin(value.origin);
+}
+
+export async function readDaemonEndpoint(file) {
+  let handle;
+  try {
+    handle = await fs.open(file, "r");
+  } catch (error) {
+    if (error?.code === "ENOENT") return null;
+    throw new Error("Local daemon endpoint could not be opened.", { cause: error });
+  }
+  try {
+    const buffer = Buffer.alloc(ENDPOINT_SIZE_LIMIT + 1);
+    let size = 0;
+    while (size < buffer.length) {
+      const { bytesRead } = await handle.read(buffer, size, buffer.length - size, null);
+      if (!bytesRead) break;
+      size += bytesRead;
+    }
+    if (size === buffer.length) throw new Error("Local daemon endpoint exceeds its size limit.");
+    const parsed = JSON.parse(buffer.toString("utf8", 0, size));
+    if (!isEndpoint(parsed)) throw new Error("Local daemon endpoint is invalid.");
+    return parsed;
+  } finally {
+    await handle.close();
+  }
+}
+
+export async function requestDaemonGitArc(request, { env = process.env, fetch = globalThis.fetch, signal } = {}) {
+  const endpoint = await readDaemonEndpoint(path.join(resolveWorkbenchDataRoot({ environment: env }), "daemon", "runtime.json"));
+  if (!endpoint) throw new Error("The Workbench daemon has not published an endpoint.");
+  const response = await fetch(new URL("/daemon/git-arc", endpoint.origin), {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ ...request, ...daemonGitArcIdentity(env) }),
+    redirect: "error",
+    signal,
+  });
+  if (!response.ok) throw new Error(`Git arc ${request.action} request failed (HTTP ${response.status}).`);
+  return await response.json();
+}