@ricsam/r5d-worker 0.0.137 → 0.0.138

package/dist/mjs/runtime/workspace/authority.mjs

@@ -0,0 +1,1355 @@
+import fs from "node:fs/promises";
+import { constants } from "node:fs";
+import path from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { canonicalJson, OperationEnvelope, operationPayloadHash } from "@ricsam/r5d-api/runtime-protocol";
+import { STORAGE_LIMITS, GitOid, BranchName, safeTreePath } from "./storage-wire.mjs";
+import { ExecutorError, isDefiniteStartRejection, ShellPayload } from "../protocol.mjs";
+import {
+  ApprovedWorkbench,
+  WorkspaceConfig,
+  WorkspaceError,
+  WorkspacePublicationNotAdmitted,
+  DEFAULT_WORKSPACE_IGNORE
+} from "./contracts.mjs";
+import { SessionArtifactStore, SessionArtifactChunk, RESERVED_ARTIFACT_ENV } from "./artifacts.mjs";
+import { WorkspaceFileWrite, WorkspaceFileWriteLookup } from "./file-write.mjs";
+import { WorkspaceStorageClient } from "./storage-client.mjs";
+import {
+  durableJson,
+  git,
+  noSymlinkAncestors,
+  privateRoot,
+  readRegular,
+  selectedTree,
+  sha256,
+  snapshotTree,
+  sourceBytes,
+  verifyIgnore
+} from "./files.mjs";
+class WorkspaceAuthority {
+  constructor(options) {
+    this.options = options;
+    this.config = WorkspaceConfig.parse(options.config);
+  }
+  options;
+  config;
+  benches = /* @__PURE__ */ new Map();
+  queues = /* @__PURE__ */ new Map();
+  lockId = randomUUID();
+  closing = false;
+  closed = false;
+  closeTask;
+  actions = /* @__PURE__ */ new Set();
+  pending = 0;
+  static async open(options) {
+    const authority = new WorkspaceAuthority(options);
+    const { config } = authority;
+    await privateRoot(config.root, config.installationId);
+    const contents = await fs.readdir(config.root);
+    const binding = { installationId: config.installationId, workbenches: config.workbenches, ...config.dynamicWorkbenches ? { dynamicWorkbenches: true } : {} };
+    if (Boolean(config.dynamicWorkbenches) !== Boolean(options.resolveWorkbench)) throw new WorkspaceError("invalid_config", "Dynamic workspace requires catalog authorization");
+    if (new Set(config.workbenches.map((b) => b.id)).size !== config.workbenches.length || new Set(config.workbenches.map((b) => `${b.userId}:${b.sessionId}`)).size !== config.workbenches.length)
+      throw new WorkspaceError("invalid_config", "Duplicate workbench or session route");
+    for (const b of config.workbenches) {
+      if (b.cwd !== path.join(config.root, "workbenches", b.id))
+        throw new WorkspaceError("unsafe_root", "Approved cwd must equal root/workbenches/id; arbitrary and legacy roots are forbidden");
+    }
+    if (contents.length) {
+      const existing = JSON.parse((await readRegular(path.join(config.root, "installation.json"), 128 * 1024)).toString());
+      if (canonicalJson(existing) !== canonicalJson(binding))
+        throw new WorkspaceError("wrong_binding", "Existing root binding cannot be changed");
+    }
+    await fs.mkdir(path.join(config.root, ".sync-lock"), { mode: 448 }).catch(() => {
+      throw new WorkspaceError(
+        "authority_busy",
+        "Sync lock exists; stop old authority/executor and review preserved state before maintenance"
+      );
+    });
+    await durableJson(path.join(config.root, ".sync-lock", "owner.json"), { lockId: authority.lockId });
+    if (!contents.length) {
+      await durableJson(path.join(config.root, "installation.json"), binding);
+      await fs.mkdir(path.join(config.root, "workbenches"), { mode: 448 });
+      await fs.mkdir(path.join(config.root, "state"), { mode: 448 });
+      for (const b of config.workbenches) {
+        await fs.mkdir(b.cwd, { mode: 448 });
+        const directory = path.join(config.root, "state", b.id);
+        await fs.mkdir(directory, { mode: 448 });
+        await fs.mkdir(path.join(directory, "repo"), { mode: 448 });
+        await git(path.join(directory, "repo"), ["init", "--bare", "--template=", "."]);
+        await durableJson(path.join(directory, "state.json"), { initialized: false, head: null, blocked: null, runs: {} });
+      }
+    }
+    for (const b of config.workbenches) {
+      await noSymlinkAncestors(b.cwd);
+      const directory = path.join(config.root, "state", b.id);
+      const state = JSON.parse((await readRegular(path.join(directory, "state.json"), 1024 * 1024)).toString());
+      if (typeof state.initialized !== "boolean" || !state.runs || !(state.head === null || GitOid.safeParse(state.head).success))
+        throw new WorkspaceError("invalid_state", "Invalid durable workspace state; maintenance required");
+      authority.benches.set(b.id, { config: b, state, directory, repo: path.join(directory, "repo") });
+    }
+    if (config.dynamicWorkbenches) {
+      for (const id of await fs.readdir(path.join(config.root, "state"))) {
+        if (authority.benches.has(id)) continue;
+        const directory = path.join(config.root, "state", id);
+        await noSymlinkAncestors(directory);
+        const b = ApprovedWorkbench.parse(JSON.parse((await readRegular(path.join(directory, "workbench.json"), 128 * 1024)).toString()));
+        if (b.id !== id || b.cwd !== path.join(config.root, "workbenches", id)) throw new WorkspaceError("wrong_binding", "Invalid durable dynamic workbench");
+        await noSymlinkAncestors(b.cwd);
+        const state = JSON.parse((await readRegular(path.join(directory, "state.json"), 1024 * 1024)).toString());
+        if (typeof state.initialized !== "boolean" || !state.runs || !(state.head === null || GitOid.safeParse(state.head).success)) throw new WorkspaceError("invalid_state", "Invalid dynamic workspace state");
+        authority.benches.set(id, { config: b, state, directory, repo: path.join(directory, "repo") });
+      }
+    }
+    return authority;
+  }
+  registrations = /* @__PURE__ */ new Map();
+  async bench(identity, visited = /* @__PURE__ */ new Set()) {
+    if (visited.has(identity.sessionId) || visited.size >= 16) throw new WorkspaceError("wrong_binding", "Shared workspace cycle or depth exceeded");
+    const fixed = this.config.workbenches.find((b) => b.userId === identity.userId && b.sessionId === identity.sessionId);
+    const approved = fixed ?? await this.options.resolveWorkbench?.(identity);
+    if (!approved) throw new WorkspaceError("forbidden", "No approved workbench for authenticated user/session");
+    const config = ApprovedWorkbench.parse(approved);
+    if (config.userId !== identity.userId || config.sessionId !== identity.sessionId || config.cwd !== path.join(this.config.root, "workbenches", config.id))
+      throw new WorkspaceError("unsafe_root", "Catalog returned an invalid workspace identity");
+    if (config.sharedSessionId) {
+      const parent = await this.bench({ userId: identity.userId, sessionId: config.sharedSessionId }, /* @__PURE__ */ new Set([...visited, identity.sessionId]));
+      if (parent.config.userId !== config.userId || parent.config.id !== config.id || parent.config.repositoryId !== config.repositoryId || parent.config.branch !== config.branch || parent.config.cwd !== config.cwd) throw new WorkspaceError("wrong_binding", "Shared workspace does not match its authorized parent");
+      return parent;
+    }
+    const existing = this.benches.get(config.id);
+    if (existing) {
+      if (canonicalJson(existing.config) !== canonicalJson(config)) throw new WorkspaceError("wrong_binding", "Workbench identity is immutable");
+      return existing;
+    }
+    let task = this.registrations.get(config.id);
+    if (!task) {
+      task = (async () => {
+        await this.owned();
+        const directory = path.join(this.config.root, "state", config.id);
+        const manifest = path.join(directory, "workbench.json");
+        const stored = await fs.readFile(manifest, "utf8").catch((error) => {
+          if (error.code === "ENOENT") return null;
+          throw error;
+        });
+        if (stored) {
+          if (canonicalJson(JSON.parse(stored)) !== canonicalJson(config)) throw new WorkspaceError("wrong_binding", "Persisted workbench identity changed");
+        } else {
+          await fs.mkdir(directory, { mode: 448 });
+          await durableJson(manifest, config);
+          await fs.mkdir(config.cwd, { mode: 448 });
+          await fs.mkdir(path.join(directory, "repo"), { mode: 448 });
+          await git(path.join(directory, "repo"), ["init", "--bare", "--template=", "."]);
+          await durableJson(path.join(directory, "state.json"), { initialized: false, head: null, blocked: null, runs: {} });
+        }
+        await noSymlinkAncestors(config.cwd);
+        const state = JSON.parse((await readRegular(path.join(directory, "state.json"), 1024 * 1024)).toString());
+        if (typeof state.initialized !== "boolean" || !state.runs || !(state.head === null || GitOid.safeParse(state.head).success)) throw new WorkspaceError("invalid_state", "Invalid workspace state");
+        const bench = { config, state, directory, repo: path.join(directory, "repo") };
+        this.benches.set(config.id, bench);
+        return bench;
+      })();
+      this.registrations.set(config.id, task);
+      void task.finally(() => this.registrations.delete(config.id)).catch(() => {
+      });
+    }
+    return task;
+  }
+  hydrations = /* @__PURE__ */ new Map();
+  async ensureHydrated(identity) {
+    const b = await this.bench(identity);
+    if (b.state.initialized) return;
+    let task = this.hydrations.get(b.config.id);
+    if (!task) {
+      task = this.hydrate(identity).then(() => {
+      });
+      this.hydrations.set(b.config.id, task);
+      void task.finally(() => this.hydrations.delete(b.config.id)).catch(() => {
+      });
+    }
+    await task;
+  }
+  async readFile(identity, file) {
+    const b = await this.bench(identity);
+    if (!file || file.length > 4096 || file.includes("\\") || file.split("/").some((part) => !part || part === "." || part === ".." || part === ".git"))
+      throw new WorkspaceError("unsafe_path", "Invalid file path");
+    const target = path.join(b.config.cwd, file);
+    await noSymlinkAncestors(target);
+    const bytes = await readRegular(target, 1024 * 1024);
+    return { path: file, content: bytes.toString("utf8"), bytes: bytes.length };
+  }
+  async processes(identity) {
+    const b = await this.bench(identity), route = await this.route(b);
+    const result = [];
+    for (const [operationId, metadata] of Object.entries(b.state.runs)) {
+      if (metadata.state === "rejected_capacity" || (metadata.sessionId ?? b.config.sessionId) !== identity.sessionId) continue;
+      const poll = await this.poll(identity, { userId: identity.userId, sessionId: identity.sessionId, operationId, fence: route.workerFence }, 0, 0, 1);
+      result.push({ ...metadata, ...poll.receipt, workerLabel: route.workerFence.resourceId });
+    }
+    return result;
+  }
+  async fileHistoryDates(identity, file) {
+    safeTreePath(file);
+    const b = await this.bench(identity);
+    return this.serial(b, async () => {
+      if (!b.state.initialized || !b.state.head) throw new WorkspaceError("not_initialized", "Initialize workspace first");
+      const target = path.join(b.config.cwd, file);
+      await noSymlinkAncestors(target);
+      const stat = await fs.stat(target);
+      if (!stat.isFile() || stat.nlink !== 1) throw new WorkspaceError("unsafe_file", "Expected a single-link regular file");
+      const dates = (await git(b.repo, ["log", "--max-count=10000", "--format=%cI", b.state.head, "--", file])).toString().trim().split("\n").filter(Boolean);
+      if (dates.length >= 1e4) throw new WorkspaceError("too_large", "File history exceeds date inspection budget");
+      if (dates.some((value) => !Number.isFinite(Date.parse(value)))) throw new WorkspaceError("invalid_state", "Invalid file history timestamp");
+      if (dates.length) return { createdAt: new Date(dates.at(-1)).toISOString(), updatedAt: new Date(dates[0]).toISOString() };
+      return { createdAt: stat.birthtimeMs > 0 ? stat.birthtime.toISOString() : null, updatedAt: stat.mtime.toISOString() };
+    });
+  }
+  /** Bounded file browsing through the same catalog-authorized workbench as tools. */
+  async inspectFiles(identity, command) {
+    const b = await this.bench(identity);
+    const relative = command.path.replace(/^\/+/, "").replace(/\/+$/, "");
+    if (relative) safeTreePath(relative);
+    if (!relative && command.method === "raw") throw new WorkspaceError("unsafe_path", "A file path is required");
+    const target = path.join(b.config.cwd, relative);
+    await noSymlinkAncestors(target).catch((error) => {
+      if (error.code === "ENOENT" || error.code === "ENOTDIR") throw new WorkspaceError("not_found", "File or directory not found");
+      throw error;
+    });
+    const stat = await fs.stat(target);
+    if (command.method === "raw") {
+      const bytes = await readRegular(target, 8 * 1024 * 1024);
+      return { path: `/${relative}`, base64: bytes.toString("base64"), size: bytes.length, modifiedAt: stat.mtime.toISOString() };
+    }
+    if (!stat.isDirectory()) throw new WorkspaceError("not_found", "Directory not found");
+    const names = await fs.readdir(target, { withFileTypes: true });
+    if (names.length > STORAGE_LIMITS.treeEntries) throw new WorkspaceError("too_large", "Directory exceeds entry budget");
+    const entries = await Promise.all(names.filter((entry) => entry.name !== ".git" && !entry.isSymbolicLink() && (entry.isFile() || entry.isDirectory())).map(async (entry) => {
+      const nested = await fs.stat(path.join(target, entry.name));
+      return {
+        name: entry.name,
+        path: `/${path.posix.join(relative, entry.name)}`,
+        type: entry.isDirectory() ? "directory" : "file",
+        size: entry.isDirectory() ? null : nested.size,
+        modifiedAt: nested.mtime.toISOString()
+      };
+    }));
+    return { directory: `/${relative}`, entries };
+  }
+  async inspectGit(identity, command) {
+    const b = await this.bench(identity);
+    return this.serial(b, async () => {
+      if (!b.state.initialized || !b.state.head) throw new WorkspaceError("not_initialized", "Initialize workspace first");
+      const head = b.state.head;
+      const base = command.base ? GitOid.parse(command.base) : head;
+      const treeHash = await snapshotTree(b.repo, b.config.cwd, head);
+      if (command.method === "history") {
+        const history = (await git(b.repo, ["log", "-100", "--format=%H%x00%P%x00%s%x00%an%x00%ae%x00%aI%x00%cI", head])).toString();
+        return { head, treeHash, commits: history.trimEnd().split("\n").filter(Boolean).map((line) => {
+          const [hash, parents, subject, authorName, authorEmail, authoredAt, committedAt] = line.split("\0");
+          return { hash, parents: parents?.split(" ").filter(Boolean) ?? [], subject, authorName, authorEmail, authoredAt, committedAt };
+        }) };
+      }
+      if (command.method === "fileDiff") {
+        safeTreePath(command.path);
+        const side = async (tree) => {
+          const listing = (await git(b.repo, ["ls-tree", "-z", tree, "--", command.path])).toString().replace(/\0$/, "");
+          if (!listing) return { kind: "missing", objectType: null, mode: null, byteSize: null, content: null };
+          const [mode, objectType, oid] = listing.split(/[\s\t]/);
+          if (objectType !== "blob") return { kind: "unsupported", objectType, mode, byteSize: null, content: null };
+          const size = Number((await git(b.repo, ["cat-file", "-s", oid])).toString());
+          if (size > 1024 * 1024) return { kind: "oversized", objectType, mode, byteSize: size, content: null };
+          const bytes = await git(b.repo, ["cat-file", "blob", oid]);
+          const binary = bytes.includes(0);
+          return { kind: binary ? "binary" : "text", objectType, mode, byteSize: size, content: binary ? null : bytes.toString("utf8") };
+        };
+        return { head, treeHash, original: await side(base), modified: await side(treeHash) };
+      }
+      const statuses = (await git(b.repo, ["diff", "--no-renames", "--name-status", "-z", base, treeHash])).toString().split("\0");
+      const changes = [];
+      for (let index = 0; index + 1 < statuses.length; index += 2) {
+        const status = { A: "added", M: "modified", D: "deleted", T: "type_changed", U: "unmerged" }[statuses[index]] ?? "unknown";
+        changes.push({ path: statuses[index + 1], status, additions: null, deletions: null, binary: false });
+      }
+      const nums = (await git(b.repo, ["diff", "--no-renames", "--numstat", "-z", base, treeHash])).toString().split("\0");
+      for (const line of nums.filter(Boolean)) {
+        const [added, removed, ...name] = line.split("	");
+        const file = changes.find((item) => item.path === name.join("	"));
+        if (file) Object.assign(file, { additions: added === "-" ? null : Number(added), deletions: removed === "-" ? null : Number(removed), binary: added === "-" });
+      }
+      const patch = command.method === "diff" ? (await git(b.repo, ["diff", "--no-ext-diff", "--no-textconv", "--no-renames", base, treeHash])).toString() : void 0;
+      return { head, treeHash, files: changes, ...patch === void 0 ? {} : { patch } };
+    });
+  }
+  save(b) {
+    return durableJson(path.join(b.directory, "state.json"), b.state);
+  }
+  async owned(admitted = false) {
+    if (this.closing && !admitted) throw new WorkspaceError("authority_closed", "Workspace authority is closing");
+    const owner = JSON.parse((await readRegular(path.join(this.config.root, ".sync-lock", "owner.json"), 1024)).toString());
+    if (owner.lockId !== this.lockId) throw new WorkspaceError("authority_lost", "Workspace authority lock changed");
+  }
+  serial(b, fn, admitted = false) {
+    if (this.closing && !admitted) return Promise.reject(new WorkspaceError("authority_closed", "Workspace authority is closing"));
+    if (this.pending >= 32) return Promise.reject(new WorkspaceError("busy", "Workspace request budget reached"));
+    this.pending++;
+    const task = (this.queues.get(b.config.id) ?? Promise.resolve()).catch(() => {
+    }).then(async () => {
+      await this.owned(admitted);
+      return fn();
+    });
+    this.queues.set(b.config.id, task);
+    void task.finally(() => {
+      this.pending--;
+      if (this.queues.get(b.config.id) === task) this.queues.delete(b.config.id);
+    }).catch(() => {
+    });
+    return task;
+  }
+  async route(b, identity = b.config) {
+    const route = await this.options.executor(identity);
+    if (route.workerFence.installationId !== this.config.installationId)
+      throw new WorkspaceError("wrong_installation", "Executor route is for another installation");
+    return route;
+  }
+  async storage(b) {
+    const storage = await this.options.storage(b.config);
+    if (storage.installationId !== this.config.installationId)
+      throw new WorkspaceError("wrong_installation", "Storage client is for another installation");
+    return storage;
+  }
+  async refresh(b) {
+    if (!Object.values(b.state.runs).some((r) => !["completed", "cancelled", "rejected_capacity"].includes(r.state))) return;
+    for (const [operationId, run] of Object.entries(b.state.runs)) {
+      if (["completed", "cancelled", "rejected_capacity"].includes(run.state)) continue;
+      try {
+        const route = await this.route(b, { userId: b.config.userId, sessionId: run.sessionId ?? b.config.sessionId });
+        const result = await route.client.poll(
+          { operationId, userId: b.config.userId, sessionId: run.sessionId ?? b.config.sessionId, fence: route.workerFence },
+          0,
+          0,
+          1
+        );
+        run.state = result.receipt.state;
+      } catch {
+        run.state = "unknown";
+      }
+    }
+    await this.save(b);
+  }
+  async idle(b, allowBlocked = false) {
+    await this.refresh(b);
+    if (Object.values(b.state.runs).some((r) => r.mutating && !["completed", "cancelled", "rejected_capacity"].includes(r.state)))
+      throw new WorkspaceError(
+        "workbench_busy",
+        "A mutating command is active/unknown; poll original executor run to terminal before syncing"
+      );
+    if (b.state.blocked && !allowBlocked) throw new WorkspaceError(b.state.blocked.code, b.state.blocked.message);
+  }
+  async status(identity) {
+    const b = await this.bench(identity);
+    return this.serial(b, async () => {
+      await this.refresh(b);
+      let files = null;
+      if (b.state.initialized) {
+        try {
+          const output = await git(b.config.cwd, ["ls-files", "--cached", "--others", "--exclude-standard", "-z"]);
+          const names = output.toString("utf8").split("\0").filter(Boolean);
+          if (names.length <= 1e4) files = [...new Set(names)].sort();
+        } catch {
+        }
+      }
+      return { workbench: b.config, ...structuredClone(b.state), files };
+    });
+  }
+  async cleanRefreshBase(b, expectedBase) {
+    if (!b.state.initialized || b.state.head !== expectedBase)
+      throw new WorkspaceError("conflict", "Workbench base changed; inspect before refreshing");
+    const expectedTree = (await git(b.repo, ["rev-parse", `${expectedBase}^{tree}`])).toString().trim();
+    if (await snapshotTree(b.repo, b.config.cwd, expectedBase) !== expectedTree)
+      throw new WorkspaceError("dirty_workbench", "Source differs from its canonical base; preserve and publish or reconcile edits first");
+    const metadata = path.join(b.config.cwd, ".git");
+    const ref = `refs/heads/${b.config.branch}`;
+    const indexBytes = await readRegular(path.join(metadata, "index"), 8 * 1024 * 1024);
+    const localHead = (await readRegular(path.join(metadata, ref), 1024)).toString().trim();
+    const retained = b.state.publishedMetadata;
+    const unchangedPublishedMetadata = retained && retained.head === localHead && retained.indexHash === sha256(indexBytes);
+    if ((await readRegular(path.join(metadata, "HEAD"), 1024)).toString() !== `ref: ${ref}
+` || localHead !== expectedBase && !unchangedPublishedMetadata)
+      throw new WorkspaceError("dirty_workbench", "Local branch changed; preserve and reconcile it before refreshing");
+    const index = path.join(b.repo, "refresh-inspection-index");
+    await fs.writeFile(index, indexBytes, { mode: 384 });
+    if (!unchangedPublishedMetadata && (await git(b.repo, ["write-tree"], void 0, index)).toString().trim() !== expectedTree)
+      throw new WorkspaceError("dirty_workbench", "Staged changes are retained; resolve them before refreshing");
+  }
+  /** No-argument hydration is initial-only. Explicit expectedBase permits a clean,
+   * idle workbench refresh; all replaced source/index/ref bytes are retained. */
+  async hydrate(identity, expectedBase) {
+    const b = await this.bench(identity);
+    return this.serial(b, () => this.hydrateIdle(b, expectedBase));
+  }
+  async hydrateIdle(b, expectedBase) {
+    if (b.state.blocked?.code === "account_initialization_unknown") {
+      await this.idle(b, true);
+      await this.assertFreshAccountWorkbench(b, expectedBase);
+      const operationId = `account-initialize-${sha256(b.config.userId)}`;
+      if (b.state.blocked.operationId !== operationId) throw new WorkspaceError("wrong_binding", "Account initialization receipt identity changed");
+      const storage2 = await this.storage(b);
+      const receipt = await storage2.read({ method: "operation.get", lookupId: operationId });
+      if (receipt.state !== "completed" || receipt.result?.repositoryId !== b.config.repositoryId || !GitOid.safeParse(receipt.result?.head).success)
+        throw new WorkspaceError("account_initialization_unknown", "Original account initialization is not proven complete; preserve its receipt");
+      b.state.blocked = null;
+      await this.save(b);
+    }
+    await this.idle(b);
+    if (expectedBase !== void 0) {
+      GitOid.parse(expectedBase);
+      await this.cleanRefreshBase(b, expectedBase);
+    } else if (b.state.initialized || (await fs.readdir(b.config.cwd)).length)
+      throw new WorkspaceError(
+        "nonempty_workbench",
+        "Hydration requires initially empty approved workbench; preserve/import existing work explicitly"
+      );
+    const storage = await this.storage(b);
+    const readHead = () => storage.read({ method: "repository.get", repositoryId: b.config.repositoryId, branch: b.config.branch });
+    let canonical;
+    const account = b.config.repositoryId === `user-workspace-${sha256(b.config.userId).slice(0, 40)}` && b.config.branch === "main";
+    try {
+      canonical = await readHead();
+    } catch (error) {
+      if (!(error instanceof WorkspaceError) || error.code !== "not_found" || !account) throw error;
+      canonical = { head: null };
+    }
+    if (account && canonical.head === null) {
+      await this.assertFreshAccountWorkbench(b, expectedBase);
+      const operationId = `account-initialize-${sha256(b.config.userId)}`;
+      b.state.blocked = { code: "account_initialization_unknown", operationId, message: "Inspect the original account initialization receipt; do not replace or reset the workbench" };
+      await this.save(b);
+      await this.initializeAccountCanonical(b, storage);
+      b.state.blocked = null;
+      await this.save(b);
+      canonical = await readHead();
+    }
+    const { head } = canonical;
+    if (!head) throw new WorkspaceError("empty_repository", "Seed README explicitly for an empty canonical branch");
+    GitOid.parse(head);
+    if (expectedBase === head) return { head };
+    b.state.blocked = {
+      code: expectedBase === void 0 ? "hydration_incomplete" : "refresh_incomplete",
+      message: "Source synchronization interrupted; preserve workbench and inspect staged tree/retained originals before maintenance"
+    };
+    await this.save(b);
+    const chunks = [];
+    let offset = 0, snapshot = null, size = -1, hash = "";
+    do {
+      const chunk = await storage.read({
+        method: "repository.bundle",
+        repositoryId: b.config.repositoryId,
+        snapshot,
+        offset,
+        limit: STORAGE_LIMITS.chunkBytes
+      });
+      const bytes = Buffer.from(chunk.data, "base64");
+      if (chunk.data !== bytes.toString("base64") || bytes.length > STORAGE_LIMITS.chunkBytes || chunk.offset !== offset || chunk.nextOffset !== offset + bytes.length || !bytes.length || chunk.size > STORAGE_LIMITS.blobBytes || chunk.nextOffset > chunk.size || snapshot && (snapshot !== chunk.snapshot || size !== chunk.size || hash !== chunk.sha256))
+        throw new WorkspaceError("invalid_bundle", "Chunk identity/size/offset changed; no checkout performed");
+      snapshot = chunk.snapshot;
+      size = chunk.size;
+      hash = chunk.sha256;
+      offset = chunk.nextOffset;
+      chunks.push(bytes);
+    } while (offset < size);
+    const bundle = Buffer.concat(chunks);
+    if (sha256(bundle) !== hash) throw new WorkspaceError("invalid_bundle", "Bundle SHA256 mismatch");
+    const file = path.join(b.directory, `${randomUUID()}.bundle`);
+    await fs.writeFile(file, bundle, { mode: 384, flag: "wx" });
+    await git(b.repo, ["bundle", "unbundle", file]);
+    const entries = await selectedTree(b.repo, head);
+    const staged = path.join(b.directory, `hydrate-${randomUUID()}`);
+    await fs.mkdir(staged, { mode: 448 });
+    let total = 0;
+    for (const entry of entries) {
+      const bytes = await git(b.repo, ["cat-file", "blob", entry.oid]);
+      sourceBytes(bytes, entry.file);
+      if ((total += bytes.length) > 128 * 1024 * 1024) throw new WorkspaceError("too_large", "Hydrated tree exceeds limit");
+      const target = path.join(staged, entry.file);
+      await fs.mkdir(path.dirname(target), { recursive: true, mode: 448 });
+      await fs.writeFile(target, bytes, { mode: entry.mode === "100755" ? 448 : 384, flag: "wx" });
+    }
+    await verifyIgnore(b.repo, staged);
+    const latest = await storage.read({
+      method: "repository.get",
+      repositoryId: b.config.repositoryId,
+      branch: b.config.branch
+    });
+    if (latest.head !== head)
+      throw new WorkspaceError("conflict", "Canonical head changed during hydration; staged tree retained for review");
+    if (expectedBase === void 0) {
+      if ((await fs.readdir(b.config.cwd)).length)
+        throw new WorkspaceError("nonempty_workbench", "Workbench changed during hydration; no overwrite");
+      for (const name of await fs.readdir(staged)) await fs.rename(path.join(staged, name), path.join(b.config.cwd, name));
+      await this.installGitPolicy(b, head);
+    } else {
+      await this.cleanRefreshBase(b, expectedBase);
+      const original = await selectedTree(b.repo, expectedBase);
+      const originalPaths = new Set(original.map((entry) => entry.file));
+      for (const entry of entries) {
+        const target = path.join(b.config.cwd, entry.file);
+        const existing = await fs.lstat(target).catch((error) => {
+          if (error.code === "ENOENT") return null;
+          throw error;
+        });
+        if (existing && (!originalPaths.has(entry.file) || !existing.isFile() || existing.isSymbolicLink()))
+          throw new WorkspaceError("refresh_collision", "Canonical source would replace retained local content");
+        let parent = path.dirname(target);
+        while (parent !== b.config.cwd) {
+          const current = await fs.lstat(parent).catch((error) => {
+            if (error.code === "ENOENT") return null;
+            throw error;
+          });
+          if (current && (!current.isDirectory() || current.isSymbolicLink()))
+            throw new WorkspaceError("refresh_collision", "Canonical source has a conflicting local ancestor");
+          parent = path.dirname(parent);
+        }
+      }
+      const retained = path.join(b.directory, `refresh-retained-${randomUUID()}`);
+      await fs.mkdir(retained, { mode: 448 });
+      const changedDirectories = /* @__PURE__ */ new Set([b.directory, retained]);
+      const changed = (directory, root) => {
+        while (true) {
+          changedDirectories.add(directory);
+          if (directory === root) break;
+          directory = path.dirname(directory);
+        }
+      };
+      const persistFile = async (filename) => {
+        const file2 = await fs.open(filename, constants.O_RDONLY | constants.O_NOFOLLOW);
+        try {
+          await file2.sync();
+        } finally {
+          await file2.close();
+        }
+      };
+      await durableJson(path.join(retained, "recovery.json"), {
+        previousHead: expectedBase,
+        head,
+        paths: original.map((entry) => entry.file)
+      });
+      const metadata = path.join(b.config.cwd, ".git");
+      const ref = `refs/heads/${b.config.branch}`;
+      for (const name of ["index", "HEAD", ref]) {
+        const destination = path.join(retained, "git", name);
+        await fs.mkdir(path.dirname(destination), { recursive: true, mode: 448 });
+        await this.replaceFile(destination, await readRegular(path.join(metadata, name), 8 * 1024 * 1024));
+        changed(path.dirname(destination), retained);
+      }
+      for (const entry of original) {
+        const destination = path.join(retained, "source", entry.file);
+        await fs.mkdir(path.dirname(destination), { recursive: true, mode: 448 });
+        await persistFile(path.join(b.config.cwd, entry.file));
+        await fs.rename(path.join(b.config.cwd, entry.file), destination);
+        changed(path.dirname(destination), retained);
+        changed(path.dirname(path.join(b.config.cwd, entry.file)), b.config.cwd);
+      }
+      for (const entry of entries) {
+        const destination = path.join(b.config.cwd, entry.file);
+        await fs.mkdir(path.dirname(destination), { recursive: true, mode: 448 });
+        await persistFile(path.join(staged, entry.file));
+        await fs.rename(path.join(staged, entry.file), destination);
+        changed(path.dirname(destination), b.config.cwd);
+        changed(path.dirname(path.join(staged, entry.file)), staged);
+      }
+      const copyObjects = async (relative = "") => {
+        const source = path.join(b.repo, "objects", relative), destination = path.join(metadata, "objects", relative);
+        await fs.mkdir(destination, { recursive: true, mode: 448 });
+        await noSymlinkAncestors(destination);
+        changed(destination, b.config.cwd);
+        for (const entry of await fs.readdir(source, { withFileTypes: true })) {
+          const nested = path.join(relative, entry.name);
+          if (entry.isDirectory()) await copyObjects(nested);
+          else if (entry.isFile()) {
+            const bytes = await readRegular(path.join(source, entry.name));
+            const target = path.join(destination, entry.name);
+            const old = await readRegular(target).catch((error) => {
+              if (error.code === "ENOENT") return null;
+              throw error;
+            });
+            if (old && !old.equals(bytes))
+              throw new WorkspaceError("unsafe_git", "Existing Git object differs; preserve both for review");
+            if (!old) {
+              await fs.copyFile(path.join(source, entry.name), target, constants.COPYFILE_EXCL);
+              await persistFile(target);
+            }
+          } else throw new WorkspaceError("unsafe_git", "Authority Git object is not a regular file");
+        }
+      };
+      await copyObjects();
+      await git(b.repo, ["read-tree", head]);
+      await this.replaceFile(path.join(metadata, "index"), await readRegular(path.join(b.repo, "index"), 8 * 1024 * 1024));
+      await this.replaceFile(path.join(metadata, ref), Buffer.from(`${head}
+`));
+      for (const directory of [...changedDirectories].sort((a, b2) => b2.length - a.length)) {
+        const handle = await fs.open(directory, constants.O_RDONLY | constants.O_NOFOLLOW);
+        try {
+          await handle.sync();
+        } finally {
+          await handle.close();
+        }
+      }
+    }
+    if (expectedBase !== void 0) {
+      const latest2 = await storage.read({
+        method: "repository.get",
+        repositoryId: b.config.repositoryId,
+        branch: b.config.branch
+      });
+      if (latest2.head !== head)
+        throw new WorkspaceError("conflict", "Canonical changed during refresh; both source trees retained for review");
+    }
+    b.state.initialized = true;
+    b.state.head = head;
+    delete b.state.publishedMetadata;
+    b.state.blocked = null;
+    await this.save(b);
+    return { head };
+  }
+  async assertFreshAccountWorkbench(b, expectedBase) {
+    if (expectedBase !== void 0 || b.state.initialized || b.state.head !== null || Object.keys(b.state.runs).length || b.config.repositoryId !== `user-workspace-${sha256(b.config.userId).slice(0, 40)}` || b.config.branch !== "main" || (await fs.readdir(b.config.cwd)).length)
+      throw new WorkspaceError("nonempty_workbench", "Account initialization requires its original empty uninitialized workbench; preserve existing files and history");
+  }
+  async initializeAccountCanonical(b, storage) {
+    const operationId = `account-initialize-${sha256(b.config.userId)}`;
+    let receipt;
+    try {
+      receipt = await storage.mutate({ method: "repository.initializeAccount", operationId, repositoryId: b.config.repositoryId });
+    } catch (error) {
+      if (error instanceof WorkspaceError && error.rejectedBeforeAdmission && b.state.blocked?.code === "account_initialization_unknown" && b.state.blocked.operationId === operationId) {
+        b.state.blocked = null;
+        await this.save(b);
+      }
+      throw error;
+    }
+    if (receipt.repositoryId !== b.config.repositoryId || !GitOid.safeParse(receipt.head).success)
+      throw new WorkspaceError("invalid_response", "Account initialization receipt mismatch; preserve the original operation");
+    return receipt;
+  }
+  async replaceFile(destination, bytes) {
+    const temporary = `${destination}.${randomUUID()}.next`;
+    const file = await fs.open(temporary, "wx", 384);
+    try {
+      await file.writeFile(bytes);
+      await file.sync();
+    } finally {
+      await file.close();
+    }
+    await fs.rename(temporary, destination);
+    const directory = await fs.open(path.dirname(destination), "r");
+    try {
+      await directory.sync();
+    } finally {
+      await directory.close();
+    }
+  }
+  /** Explicit trusted import boundary for the first isolated README seed, not legacy tree import. */
+  async seedReadme(identity, readme) {
+    const b = await this.bench(identity);
+    return this.serial(b, async () => {
+      await this.idle(b);
+      if (Buffer.byteLength(readme) > 1024 * 1024) throw new WorkspaceError("too_large", "README seed exceeds limit");
+      sourceBytes(Buffer.from(readme));
+      if (b.state.initialized || (await fs.readdir(b.config.cwd)).length)
+        throw new WorkspaceError("nonempty_workbench", "Seed only an initially empty approved workbench");
+      const storage = await this.storage(b);
+      const operationId = `ws-${randomUUID()}`;
+      b.state.blocked = {
+        code: "seed_unknown",
+        operationId,
+        message: "Inspect original provision/seed receipt; do not automatically rerun import"
+      };
+      await this.save(b);
+      await storage.mutate({ method: "repository.provision", operationId, repositoryId: b.config.repositoryId });
+      const existing = await storage.read({
+        method: "repository.get",
+        repositoryId: b.config.repositoryId,
+        branch: b.config.branch
+      });
+      if (existing.head) throw new WorkspaceError("conflict", "Canonical branch already has a head; hydrate instead");
+      await fs.writeFile(path.join(b.config.cwd, ".gitignore"), DEFAULT_WORKSPACE_IGNORE, { mode: 384, flag: "wx" });
+      await fs.writeFile(path.join(b.config.cwd, "README.md"), readme, { mode: 384, flag: "wx" });
+      b.state.initialized = true;
+      b.state.blocked = null;
+      await this.save(b);
+      const result = await this.publishIdle(b);
+      await this.installGitPolicy(b, result.head);
+      return result;
+    });
+  }
+  async installGitPolicy(b, head) {
+    delete b.state.publishedMetadata;
+    const destination = path.join(b.config.cwd, ".git");
+    await git(b.repo, ["read-tree", head]);
+    await fs.mkdir(destination, { mode: 448 });
+    await fs.cp(b.repo, destination, { recursive: true, errorOnExist: true });
+    const remote = `r5d-canonical://${this.config.installationId}/${b.config.userId}/${b.config.repositoryId}`;
+    await fs.writeFile(
+      path.join(destination, "config"),
+      `[core]
+	repositoryformatversion = 0
+	bare = false
+	hooksPath = /dev/null
+[protocol]
+	allow = never
+[remote "canonical"]
+	url = ${remote}
+	pushurl = ${remote}
+`,
+      { mode: 384 }
+    );
+    await fs.writeFile(path.join(destination, "HEAD"), `ref: refs/heads/${b.config.branch}
+`, { mode: 384 });
+    const ref = path.join(destination, "refs", "heads", b.config.branch);
+    await fs.mkdir(path.dirname(ref), { recursive: true, mode: 448 });
+    await fs.writeFile(ref, `${head}
+`, { mode: 384 });
+  }
+  /** Scoped receipt lookup never repeats a file effect; completion can clear its own crash marker. */
+  async fileWriteResult(identity, input) {
+    WorkspaceFileWriteLookup.parse({ method: "fileWriteResult", ...input });
+    const b = await this.bench(identity);
+    return this.serial(b, async () => {
+      const bytes = await readRegular(path.join(b.directory, `product-${sha256(input.id)}.json`), 1024 * 1024).catch((error) => {
+        if (error.code === "ENOENT") return null;
+        throw error;
+      });
+      if (!bytes) return { state: "absent" };
+      const receipt = JSON.parse(bytes.toString());
+      if (receipt.state !== "completed") throw new WorkspaceError("product_action_unknown", "The original file mutation outcome is not proven");
+      if (receipt.result?.method !== "fileWrite" || receipt.result.userId !== identity.userId || receipt.result.sessionId !== identity.sessionId)
+        throw new WorkspaceError("operation_payload_mismatch", "This action belongs to another operation or conversation");
+      if (b.state.blocked?.code === "file_write_unknown" && b.state.blocked.operationId === input.id) {
+        b.state.blocked = null;
+        await this.save(b);
+      }
+      return { state: "completed", result: receipt.result };
+    });
+  }
+  async fileWrite(identity, raw) {
+    const input = WorkspaceFileWrite.parse(raw), bytes = Buffer.from(input.base64, "base64");
+    if (bytes.toString("base64") !== input.base64 || bytes.length > 768 * 1024)
+      throw new WorkspaceError("invalid_input", "Expected canonical base64 for at most 768 KiB", true);
+    const b = await this.bench(identity), target = path.join(b.config.cwd, input.path);
+    const fingerprint = { ...input, userId: identity.userId, sessionId: identity.sessionId };
+    let mode = 420;
+    const check = async () => {
+      await this.idle(b);
+      if (!b.state.initialized) throw new WorkspaceError("uninitialized", "Hydrate this workspace before writing files");
+      let current = b.config.cwd;
+      for (const part of input.path.split("/").slice(0, -1)) {
+        current = path.join(current, part);
+        const stat = await fs.lstat(current).catch((error) => {
+          if (error.code === "ENOENT") return null;
+          throw error;
+        });
+        if (stat && (!stat.isDirectory() || stat.isSymbolicLink())) throw new WorkspaceError("unsafe_path", "File parent is not a real directory");
+      }
+      const previous = await readRegular(target, 8 * 1024 * 1024).catch((error) => {
+        if (error.code === "ENOENT") return null;
+        throw error;
+      });
+      if ((previous === null ? null : sha256(previous)) !== input.expectedSha256)
+        throw new WorkspaceError("file_changed", "File changed since it was read; read it again before editing");
+      if (previous !== null) mode = (await fs.lstat(target)).mode & 511;
+    };
+    return this.serial(b, async () => {
+      const result = await this.productAction(b, input.id, fingerprint, async () => {
+        b.state.blocked = { code: "file_write_unknown", operationId: input.id, message: "Inspect the original file write receipt before changing this workbench" };
+        await this.save(b);
+        await fs.mkdir(path.dirname(target), { recursive: true, mode: 493 });
+        await noSymlinkAncestors(path.dirname(target));
+        const temporary = path.join(path.dirname(target), `.r5d-file-${randomUUID()}`);
+        const file = await fs.open(temporary, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, mode);
+        try {
+          await file.writeFile(bytes);
+          await file.sync();
+        } finally {
+          await file.close();
+        }
+        const current = await readRegular(target, 8 * 1024 * 1024).catch((error) => {
+          if (error.code === "ENOENT") return null;
+          throw error;
+        });
+        if ((current === null ? null : sha256(current)) !== input.expectedSha256)
+          throw new WorkspaceError("product_action_unknown", "External file change raced an admitted write; preserve the original receipt");
+        await fs.rename(temporary, target);
+        const directory = await fs.open(path.dirname(target), constants.O_RDONLY);
+        try {
+          await directory.sync();
+        } finally {
+          await directory.close();
+        }
+        return {
+          method: "fileWrite",
+          id: input.id,
+          userId: identity.userId,
+          sessionId: identity.sessionId,
+          path: input.path,
+          sha256: sha256(bytes),
+          gitBlobHash: createHash("sha1").update(`blob ${bytes.length}\0`).update(bytes).digest("hex"),
+          size: bytes.length,
+          modifiedAt: (await fs.stat(target)).mtime.toISOString(),
+          requestHash: sha256(canonicalJson(fingerprint)),
+          ...input.intentHash ? { intentHash: input.intentHash } : {}
+        };
+      }, check);
+      if (b.state.blocked?.code === "file_write_unknown" && b.state.blocked.operationId === input.id) {
+        b.state.blocked = null;
+        await this.save(b);
+      }
+      return result;
+    });
+  }
+  async productAction(b, id, input, action, prepare) {
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$/.test(id)) throw new WorkspaceError("invalid_input", "Invalid product action ID");
+    const hash = sha256(canonicalJson(input));
+    const file = path.join(b.directory, `product-${sha256(id)}.json`);
+    const previous = await readRegular(file, 1024 * 1024).catch((error) => {
+      if (error.code === "ENOENT") return null;
+      throw error;
+    });
+    if (previous) {
+      const receipt = JSON.parse(previous.toString());
+      if (receipt.hash !== hash) throw new WorkspaceError("operation_payload_mismatch", "Action ID already bound to different input");
+      if (receipt.state === "completed") return receipt.result;
+      throw new WorkspaceError("product_action_unknown", "Inspect the original product action; its outcome is not yet proven");
+    }
+    try {
+      await prepare?.();
+    } catch (error) {
+      if (error instanceof WorkspaceError) throw new WorkspaceError(error.code, error.message, true);
+      throw error;
+    }
+    await durableJson(file, { id, hash, state: "pending" });
+    const result = await action();
+    await durableJson(file, { id, hash, state: "completed", result });
+    return result;
+  }
+  validateGithubRemote(remote) {
+    const url = new URL(remote.url);
+    if (url.protocol !== "https:" || url.hostname !== "github.com" || url.port || url.username || url.password || url.search || url.hash || !/^\/[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+(?:\.git)?$/.test(url.pathname) || !remote.token || remote.token.length > 8192)
+      throw new WorkspaceError("invalid_remote", "Expected an authorized GitHub repository");
+    BranchName.parse(remote.branch);
+  }
+  /** Import only a selected exact GitHub tree into canonical storage; never execute its Git configuration. */
+  async importRepository(identity, input) {
+    const b = await this.bench(identity);
+    this.validateGithubRemote({ ...input, branch: input.defaultBranch });
+    return this.serial(b, () => this.productAction(b, input.id, { method: "import", url: input.url, branch: input.defaultBranch }, async () => {
+      await git(b.repo, ["-c", "protocol.https.allow=always", "fetch", "--no-tags", "--no-recurse-submodules", "--", input.url, `refs/heads/${input.defaultBranch}`], void 0, void 0, { token: input.token });
+      const head = GitOid.parse((await git(b.repo, ["rev-parse", "FETCH_HEAD"])).toString().trim());
+      return this.importCommit(b, head, input.id);
+    }, async () => {
+      await this.idle(b);
+      if (b.state.initialized || (await fs.readdir(b.config.cwd)).length) throw new WorkspaceError("nonempty_workbench", "Import requires a new empty workbench");
+    }));
+  }
+  async cloneBranch(identity, sourceIdentity, input) {
+    if (identity.userId !== sourceIdentity.userId || identity.sessionId === sourceIdentity.sessionId) throw new WorkspaceError("forbidden", "Invalid branch source");
+    const target = await this.bench(identity);
+    const fingerprint = { method: "clone", sourceSessionId: sourceIdentity.sessionId, workingTree: input.workingTree };
+    const completed = await this.serial(target, async () => {
+      const bytes = await readRegular(path.join(target.directory, `product-${sha256(input.id)}.json`), 1024 * 1024).catch((error) => {
+        if (error.code === "ENOENT") return null;
+        throw error;
+      });
+      if (!bytes) return null;
+      const receipt = JSON.parse(bytes.toString());
+      if (receipt.hash !== sha256(canonicalJson(fingerprint))) throw new WorkspaceError("operation_payload_mismatch", "Branch action identity changed");
+      if (receipt.state !== "completed") throw new WorkspaceError("product_action_unknown", "Inspect original branch operation");
+      return receipt.result;
+    });
+    if (completed) return completed;
+    const source = await this.bench(sourceIdentity);
+    if (source.config.repositoryId !== target.config.repositoryId || source.config.branch === target.config.branch) throw new WorkspaceError("forbidden", "Branch source must belong to the same project");
+    await this.ensureHydrated(sourceIdentity);
+    const prepared = await this.serial(source, async () => {
+      await this.idle(source);
+      let head = source.state.head;
+      if (input.workingTree === "carry") {
+        const tree = await snapshotTree(source.repo, source.config.cwd, head);
+        if (tree !== (await git(source.repo, ["rev-parse", `${head}^{tree}`])).toString().trim()) head = (await git(source.repo, ["commit-tree", tree, "-p", head], "Branch working tree\n")).toString().trim();
+      }
+      const ref = `refs/r5d/product-${sha256(input.id)}`;
+      await git(source.repo, ["update-ref", ref, head]);
+      const file = path.join(source.directory, `branch-${randomUUID()}.bundle`);
+      await git(source.repo, ["bundle", "create", file, ref]);
+      return { head, bytes: await readRegular(file, STORAGE_LIMITS.blobBytes) };
+    });
+    return this.serial(target, () => this.productAction(target, input.id, fingerprint, async () => {
+      const file = path.join(target.directory, `clone-${randomUUID()}.bundle`);
+      await fs.writeFile(file, prepared.bytes, { mode: 384, flag: "wx" });
+      await git(target.repo, ["bundle", "unbundle", file]);
+      return this.importCommit(target, prepared.head, input.id);
+    }, async () => {
+      await this.idle(target);
+      if (target.state.initialized || (await fs.readdir(target.config.cwd)).length) throw new WorkspaceError("nonempty_workbench", "Branch already has a workbench");
+    }));
+  }
+  async importCommit(b, head, id) {
+    const entries = await selectedTree(b.repo, head);
+    const staged = path.join(b.directory, `import-${randomUUID()}`);
+    await fs.mkdir(staged, { mode: 448 });
+    let total = 0;
+    for (const entry of entries) {
+      const bytes2 = await git(b.repo, ["cat-file", "blob", entry.oid]);
+      sourceBytes(bytes2, entry.file);
+      if ((total += bytes2.length) > STORAGE_LIMITS.blobBytes) throw new WorkspaceError("too_large", "Imported tree exceeds limit");
+      const destination = path.join(staged, entry.file);
+      await fs.mkdir(path.dirname(destination), { recursive: true, mode: 448 });
+      await fs.writeFile(destination, bytes2, { mode: entry.mode === "100755" ? 448 : 384, flag: "wx" });
+    }
+    const ignore = path.join(staged, ".gitignore");
+    try {
+      await verifyIgnore(b.repo, staged);
+    } catch (error) {
+      if (!(error instanceof WorkspaceError) && error.code !== "ENOENT") throw error;
+      const oldIgnore = await fs.readFile(ignore, "utf8").catch((error2) => {
+        if (error2.code === "ENOENT") return "";
+        throw error2;
+      });
+      await fs.writeFile(ignore, `${oldIgnore}
+${DEFAULT_WORKSPACE_IGNORE}`, { mode: 384 });
+      await verifyIgnore(b.repo, staged);
+    }
+    const tree = await snapshotTree(b.repo, staged, head);
+    if (tree !== (await git(b.repo, ["rev-parse", `${head}^{tree}`])).toString().trim()) head = (await git(b.repo, ["commit-tree", tree, "-p", head], "Configure workspace exclusions\n")).toString().trim();
+    const storage = await this.storage(b), operationId = `product-${sha256(id).slice(0, 48)}`;
+    let existing;
+    try {
+      existing = await storage.read({ method: "repository.get", repositoryId: b.config.repositoryId, branch: b.config.branch });
+    } catch (error) {
+      if (!(error instanceof WorkspaceError) || error.code !== "not_found") throw error;
+      await storage.mutate({ method: "repository.provision", operationId: `${operationId}-provision`, repositoryId: b.config.repositoryId });
+      existing = { head: null };
+    }
+    if (existing.head) throw new WorkspaceError("conflict", "Branch already exists in canonical storage");
+    await git(b.repo, ["update-ref", `refs/heads/${b.config.branch}`, head]);
+    const file = path.join(b.directory, `publish-${randomUUID()}.bundle`);
+    await git(b.repo, ["bundle", "create", file, `refs/heads/${b.config.branch}`]);
+    const bytes = await readRegular(file, STORAGE_LIMITS.blobBytes), blobId = operationId;
+    b.state.blocked = { code: "publication_unknown", operationId, commit: head, message: "Inspect the original import publication receipt" };
+    await this.save(b);
+    for (let offset = 0; offset < bytes.length; offset += STORAGE_LIMITS.chunkBytes) {
+      const end = Math.min(bytes.length, offset + STORAGE_LIMITS.chunkBytes);
+      await storage.mutate({ method: "blob.append", operationId: `${operationId}-chunk-${offset}`, blobId, kind: "blob", offset, data: bytes.subarray(offset, end).toString("base64"), seal: end === bytes.length });
+    }
+    const result = await storage.mutate({ method: "repository.publish", operationId, repositoryId: b.config.repositoryId, branch: b.config.branch, expectedHead: null, commit: head, bundleId: blobId });
+    if (result.head !== head) throw new WorkspaceError("invalid_receipt", "Import receipt does not match selected commit");
+    for (const name of await fs.readdir(staged)) await fs.rename(path.join(staged, name), path.join(b.config.cwd, name));
+    await this.installGitPolicy(b, head);
+    b.state.initialized = true;
+    b.state.head = head;
+    b.state.blocked = null;
+    await this.save(b);
+    return { head, workspaceHead: head };
+  }
+  async commit(identity, input) {
+    const b = await this.bench(identity);
+    if (!input.message.trim() || input.message.length > 1e4) throw new WorkspaceError("invalid_input", "Commit message is required");
+    return this.serial(b, () => this.productAction(b, input.id, { method: "commit", expectedHead: input.expectedHead, message: input.message }, async () => {
+      const result = await this.publishIdle(b, input.message);
+      const metadata = path.join(b.config.cwd, ".git");
+      await noSymlinkAncestors(metadata);
+      const retained = path.join(b.directory, `commit-retained-${randomUUID()}`);
+      await fs.mkdir(retained, { mode: 448 });
+      await fs.rename(metadata, path.join(retained, "git"));
+      await this.installGitPolicy(b, result.head);
+      return { ...result, treeHash: (await git(b.repo, ["rev-parse", `${result.head}^{tree}`])).toString().trim() };
+    }, async () => {
+      await this.idle(b);
+      if (input.expectedHead !== void 0 && input.expectedHead !== b.state.head) throw new WorkspaceError("conflict", "Workbench head changed");
+    }));
+  }
+  async push(identity, input) {
+    const b = await this.bench(identity);
+    this.validateGithubRemote(input.remote);
+    return this.serial(b, () => this.productAction(b, input.id, { method: "push", expectedHead: input.expectedHead, url: input.remote.url, branch: input.remote.branch, expectedRemoteHead: input.remote.expectedHead }, async () => {
+      if (input.remote.expectedHead) {
+        GitOid.parse(input.remote.expectedHead);
+        await git(b.repo, ["merge-base", "--is-ancestor", input.remote.expectedHead, b.state.head]);
+      }
+      await git(b.repo, ["-c", "protocol.https.allow=always", "push", "--porcelain", ...input.remote.expectedHead !== void 0 ? [`--force-with-lease=refs/heads/${input.remote.branch}:${input.remote.expectedHead ?? ""}`] : [], "--", input.remote.url, `${b.state.head}:refs/heads/${input.remote.branch}`], void 0, void 0, { token: input.remote.token });
+      return { head: b.state.head, pushed: true };
+    }, async () => {
+      await this.idle(b);
+      if (!b.state.head || input.expectedHead !== void 0 && input.expectedHead !== b.state.head) throw new WorkspaceError("conflict", "Workbench head changed");
+    }));
+  }
+  async archiveBranch(identity, input) {
+    const b = await this.bench(identity);
+    return this.serial(b, () => this.productAction(b, input.id, { method: "archive" }, async () => {
+      const storage = await this.storage(b);
+      const current = await storage.read({ method: "repository.get", repositoryId: b.config.repositoryId, branch: b.config.branch });
+      const result = await storage.mutate({ method: "repository.archive", operationId: `archive-${sha256(input.id).slice(0, 48)}`, repositoryId: b.config.repositoryId, branch: b.config.branch, expectedHead: current.head });
+      b.state.blocked = { code: "archived", message: "This branch incarnation is archived; its workbench and source are retained" };
+      await this.save(b);
+      return { removed: true, receipt: result };
+    }, () => this.idle(b)));
+  }
+  /** An explicit user reset retains the complete old tree/index before hydration. */
+  async reset(identity, input) {
+    const b = await this.bench(identity);
+    return this.serial(b, () => this.productAction(b, input.id, { method: "reset", expectedHead: input.expectedHead }, async () => {
+      await this.idle(b, true);
+      if (input.expectedHead !== void 0 && input.expectedHead !== b.state.head) throw new WorkspaceError("conflict", "Workbench base changed before reset");
+      if (b.state.blocked?.code === "archived") throw new WorkspaceError("archived", "A deleted branch cannot be reset");
+      const storage = await this.storage(b);
+      if (b.state.blocked?.operationId) {
+        const receipt = await storage.read({ method: "operation.get", lookupId: b.state.blocked.operationId });
+        if (receipt.state !== "completed" || b.state.blocked.commit && receipt.result?.head !== b.state.blocked.commit) throw new WorkspaceError("publication_unknown", "Reconcile the original publication before resetting");
+      }
+      const canonical = await storage.read({ method: "repository.get", repositoryId: b.config.repositoryId, branch: b.config.branch });
+      if (!canonical.head) throw new WorkspaceError("empty_repository", "No canonical source exists to restore");
+      const retained = path.join(b.directory, `reset-retained-${randomUUID()}`);
+      await fs.mkdir(retained, { mode: 448 });
+      await durableJson(path.join(retained, "recovery.json"), { workbench: b.config, previousState: b.state, resetId: input.id, targetHead: canonical.head });
+      b.state.blocked = { code: "reset_incomplete", message: "Reset source retained; complete hydration after inspection" };
+      await this.save(b);
+      await noSymlinkAncestors(b.config.cwd);
+      await fs.rename(b.config.cwd, path.join(retained, "source"));
+      await fs.mkdir(b.config.cwd, { mode: 448 });
+      b.state.initialized = false;
+      b.state.head = null;
+      b.state.blocked = null;
+      await this.save(b);
+      const result = await this.hydrateIdle(b);
+      return { ...result, reset: true, retained: true };
+    }));
+  }
+  async publish(identity) {
+    const b = await this.bench(identity);
+    return this.serial(b, async () => {
+      try {
+        await this.idle(b);
+      } catch (error) {
+        if (!(error instanceof WorkspaceError) || error.code !== "workbench_busy") throw error;
+        throw new WorkspacePublicationNotAdmitted("workbench_busy", error.message);
+      }
+      return this.publishIdle(b);
+    });
+  }
+  async publishIdle(b, message = "Destination workspace snapshot") {
+    if (!b.state.initialized) throw new WorkspaceError("not_initialized", "Hydrate or explicitly seed first");
+    const storage = await this.storage(b);
+    const latest = await storage.read({
+      method: "repository.get",
+      repositoryId: b.config.repositoryId,
+      branch: b.config.branch
+    });
+    if (latest.head !== b.state.head) {
+      b.state.blocked = {
+        code: "conflict",
+        message: `Canonical head differs from workbench base ${b.state.head ?? "empty"}; dirty files/index retained. Review and reconcile manually.`
+      };
+      await this.save(b);
+      throw new WorkspaceError("conflict", b.state.blocked.message);
+    }
+    const tree = await snapshotTree(b.repo, b.config.cwd, b.state.head);
+    if (b.state.head && tree === (await git(b.repo, ["rev-parse", `${b.state.head}^{tree}`])).toString().trim())
+      return { head: b.state.head, unchanged: true };
+    const commit = (await git(b.repo, ["commit-tree", tree, ...b.state.head ? ["-p", b.state.head] : []], `${message}
+`)).toString().trim();
+    await git(b.repo, ["update-ref", `refs/heads/${b.config.branch}`, commit]);
+    const bundleFile = path.join(b.directory, `${randomUUID()}.bundle`);
+    await git(b.repo, ["bundle", "create", bundleFile, `refs/heads/${b.config.branch}`]);
+    const bytes = await readRegular(bundleFile, STORAGE_LIMITS.blobBytes);
+    const operationId = `ws-${randomUUID()}`, blobId = `ws-${randomUUID()}`;
+    try {
+      const metadata = path.join(b.config.cwd, ".git"), ref = `refs/heads/${b.config.branch}`;
+      const localHead = (await readRegular(path.join(metadata, ref), 1024)).toString().trim();
+      const index = await readRegular(path.join(metadata, "index"), 8 * 1024 * 1024);
+      if ((await readRegular(path.join(metadata, "HEAD"), 1024)).toString() !== `ref: ${ref}
+`) throw new Error("modified_head");
+      const previous = b.state.publishedMetadata;
+      if (!previous || previous.head !== localHead || previous.indexHash !== sha256(index)) {
+        if (!b.state.head || localHead !== b.state.head) throw new Error("modified_ref");
+        const inspect = path.join(b.repo, "publication-inspection-index");
+        await fs.writeFile(inspect, index, { mode: 384 });
+        if ((await git(b.repo, ["write-tree"], void 0, inspect)).toString().trim() !== (await git(b.repo, ["rev-parse", `${localHead}^{tree}`])).toString().trim()) throw new Error("staged_changes");
+        b.state.publishedMetadata = { head: localHead, indexHash: sha256(index) };
+      }
+    } catch {
+      delete b.state.publishedMetadata;
+    }
+    b.state.blocked = {
+      code: "publication_unknown",
+      operationId,
+      commit,
+      message: "Publication attempt is in progress/unknown. Inspect original storage operation; NEVER retry under a new ID. Workbench and prepared commit retained."
+    };
+    await this.save(b);
+    for (let offset = 0; offset < bytes.length; offset += STORAGE_LIMITS.chunkBytes) {
+      const end = Math.min(bytes.length, offset + STORAGE_LIMITS.chunkBytes);
+      await storage.mutate({
+        method: "blob.append",
+        operationId: `${operationId}-chunk-${offset}`,
+        blobId,
+        kind: "blob",
+        offset,
+        data: bytes.subarray(offset, end).toString("base64"),
+        seal: end === bytes.length
+      });
+    }
+    const result = await storage.mutate({
+      method: "repository.publish",
+      operationId,
+      repositoryId: b.config.repositoryId,
+      branch: b.config.branch,
+      expectedHead: b.state.head,
+      commit,
+      bundleId: blobId
+    });
+    if (result.head !== commit)
+      throw new WorkspaceError("invalid_response", "Publication receipt head mismatch; inspect original operation");
+    b.state.head = commit;
+    b.state.blocked = null;
+    await this.save(b);
+    return { head: commit };
+  }
+  /** Read-only resolution of a lost publication ACK; no mutation retry, rebase, reset, or file overwrite. */
+  async reconcilePublication(identity) {
+    const b = await this.bench(identity);
+    return this.serial(b, async () => {
+      const blocked = b.state.blocked;
+      if (blocked?.code !== "publication_unknown" || !blocked.operationId || !blocked.commit)
+        throw new WorkspaceError("not_reconcilable", "Only a verified completed publication receipt can resolve automatically");
+      const storage = await this.storage(b);
+      const receipt = await storage.read({
+        method: "operation.get",
+        lookupId: blocked.operationId
+      });
+      if (receipt.state !== "completed" || receipt.result?.head !== blocked.commit)
+        throw new WorkspaceError("publication_unknown", "Original publication not proven completed; preserve state for operator review");
+      b.state.head = blocked.commit;
+      b.state.blocked = null;
+      await this.save(b);
+      return { head: b.state.head };
+    });
+  }
+  /** Resolve mutable account settings once, before the first terminal admission.
+   * A lost ACK must recover the same command and credential generations even if
+   * settings change before redelivery or the workspace service restarts. */
+  async startWithCredentials(identity, input, resolve) {
+    const operation = OperationEnvelope.parse(JSON.parse(canonicalJson(input)));
+    const payload = ShellPayload.parse(operation.payload);
+    if (payload.credentials.length || operation.kind !== "host.shell" || operation.installationId !== this.config.installationId || operation.userId !== identity.userId || operation.sessionId !== identity.sessionId)
+      throw new WorkspaceError("forbidden", "Credential binding requires an authenticated shell identity");
+    operation.payload = payload;
+    const requestHash = await operationPayloadHash(operation);
+    const b = await this.bench(identity);
+    if (payload.cwd !== b.config.cwd) throw new WorkspaceError("forbidden_cwd", "Shell cwd must be exact approved workbench");
+    const credentials = await this.serial(b, async () => {
+      const file = path.join(b.directory, `terminal-credentials-${sha256(operation.operationId)}.json`);
+      const previous = await readRegular(file, 128e3).catch((error) => {
+        if (error.code === "ENOENT") return null;
+        throw error;
+      });
+      if (previous) {
+        const binding = JSON.parse(previous.toString());
+        if (binding.requestHash !== requestHash) throw new WorkspaceError("operation_payload_mismatch", "Terminal ID is bound to another command or size");
+        return ShellPayload.shape.credentials.parse(binding.credentials);
+      }
+      if (b.state.runs[operation.operationId]) throw new WorkspaceError("credential_binding_missing", "Preserve the original terminal receipt for review");
+      const selected = ShellPayload.shape.credentials.parse(await resolve());
+      await durableJson(file, { requestHash, credentials: selected });
+      return selected;
+    });
+    return this.start({ userId: identity.userId, sessionId: identity.sessionId }, { ...operation, payload: { ...payload, credentials } });
+  }
+  async materializeArtifact(identity, input) {
+    const b = await this.bench(identity);
+    return this.serial(b, () => new SessionArtifactStore(this.config.root).materialize(identity, input));
+  }
+  /** Default arbitrary shell is mutating. Exact trusted config approval is the sole exemption. */
+  async start(identity, input) {
+    const b = await this.bench(identity);
+    const operation = OperationEnvelope.parse(JSON.parse(canonicalJson(input)));
+    return this.serial(b, async () => {
+      if (!b.state.initialized || b.state.blocked)
+        throw new WorkspaceError("workbench_blocked", b.state.blocked?.message ?? "Initialize workbench first");
+      if (operation.installationId !== this.config.installationId || operation.userId !== identity.userId || operation.sessionId !== identity.sessionId || operation.kind !== "host.shell")
+        throw new WorkspaceError("forbidden", "Shell identity does not match approved workbench");
+      const payload = ShellPayload.parse(operation.payload);
+      if (RESERVED_ARTIFACT_ENV.some((name) => name in payload.env)) throw new WorkspaceError("reserved_environment", "R5D_ROOT and R5D_SESSION_ID are set by the workspace authority");
+      const requestedEnv = payload.env, prior = b.state.runs[operation.operationId];
+      if (!prior || prior.artifactEnvironment) {
+        payload.env = { ...payload.env, ...await new SessionArtifactStore(this.config.root).environment(identity) };
+        operation.payload = payload;
+      }
+      if (payload.cwd !== b.config.cwd) throw new WorkspaceError("forbidden_cwd", "Shell cwd must be exact approved workbench");
+      let route = await this.route(b, identity);
+      if (operation.fence.installationId !== this.config.installationId || operation.fence.resourceType !== route.workerFence.resourceType || operation.fence.resourceId !== route.workerFence.resourceId)
+        throw new WorkspaceError("wrong_resource", "Wrong worker resource");
+      operation.fence = route.workerFence;
+      const hash = await operationPayloadHash(operation);
+      const previous = b.state.runs[operation.operationId];
+      if (previous) {
+        if (previous.payloadHash !== hash)
+          throw new WorkspaceError("operation_payload_mismatch", "Run ID is already bound to another command");
+        if (previous.state === "rejected_capacity")
+          throw new ExecutorError(
+            "capacity_busy",
+            "Original attempt definitively rejected before admission; choose a new operation ID",
+            true
+          );
+        const receipt = (await route.client.poll({ operationId: operation.operationId, userId: identity.userId, sessionId: identity.sessionId, fence: route.workerFence }, 0, 0, 1)).receipt;
+        previous.state = receipt.state;
+        await this.save(b);
+        return receipt;
+      }
+      try {
+        await this.idle(b);
+      } catch (error) {
+        if (!(error instanceof WorkspaceError) || error.code !== "workbench_busy") throw error;
+        b.state.runs[operation.operationId] = { artifactEnvironment: true, sessionId: identity.sessionId, payloadHash: hash, mutating: false, state: "rejected_capacity" };
+        await this.save(b);
+        throw new ExecutorError(
+          "capacity_busy",
+          "Workspace is busy; poll the original command until terminal before choosing new work",
+          true
+        );
+      }
+      const nonmutating = Object.keys(requestedEnv).length === 0 && payload.credentials.length === 0 && b.config.nonmutatingArgv.some((argv) => canonicalJson(argv) === canonicalJson(payload.argv));
+      b.state.runs[operation.operationId] = { artifactEnvironment: true, sessionId: identity.sessionId, payloadHash: hash, mutating: !nonmutating, state: "unknown", argv: payload.argv, cwd: payload.cwd, startedAt: (/* @__PURE__ */ new Date()).toISOString(), updatedAt: (/* @__PURE__ */ new Date()).toISOString() };
+      await this.save(b);
+      for (let attempt = 0; ; attempt++) {
+        try {
+          const receipt = await route.client.start(operation);
+          b.state.runs[operation.operationId].state = receipt.state;
+          await this.save(b);
+          return receipt;
+        } catch (error) {
+          if (!isDefiniteStartRejection(error)) throw error;
+          if (error.code === "capacity_busy") {
+            b.state.runs[operation.operationId].state = "rejected_capacity";
+            await this.save(b);
+            throw error;
+          }
+          if (attempt === 2) {
+            delete b.state.runs[operation.operationId];
+            await this.save(b);
+            throw error;
+          }
+          route = await this.route(b, identity);
+          operation.fence = route.workerFence;
+        }
+      }
+    });
+  }
+  async runRoute(identity, run) {
+    const b = await this.bench(identity);
+    if (run.userId !== identity.userId || run.sessionId !== identity.sessionId || !b.state.runs[run.operationId] || (b.state.runs[run.operationId].sessionId ?? b.config.sessionId) !== identity.sessionId)
+      throw new WorkspaceError("forbidden", "Run does not belong to this workbench");
+    if (b.state.runs[run.operationId].state === "rejected_capacity")
+      throw new WorkspaceError("run_not_admitted", "This operation was definitively rejected; no executor run exists");
+    await this.owned();
+    const route = await this.route(b, identity);
+    if (run.fence.installationId !== this.config.installationId || run.fence.resourceType !== route.workerFence.resourceType || run.fence.resourceId !== route.workerFence.resourceId)
+      throw new WorkspaceError("wrong_resource", "Wrong worker resource");
+    return { b, route };
+  }
+  action(fn) {
+    if (this.closing) return Promise.reject(new WorkspaceError("authority_closed", "Workspace authority is closing"));
+    if (this.actions.size >= 32) return Promise.reject(new WorkspaceError("busy", "Workspace action budget reached"));
+    const task = Promise.resolve().then(fn);
+    this.actions.add(task);
+    void task.finally(() => this.actions.delete(task)).catch(() => {
+    });
+    return task;
+  }
+  async poll(identity, run, stdoutOffset = 0, stderrOffset = 0, maxBytes = 32768) {
+    return this.action(async () => {
+      const { b, route } = await this.runRoute(identity, run);
+      const result = await route.client.poll({ ...run, fence: route.workerFence }, stdoutOffset, stderrOffset, maxBytes);
+      await this.serial(
+        b,
+        async () => {
+          b.state.runs[run.operationId].state = result.receipt.state;
+          b.state.runs[run.operationId].updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+          if (["completed", "cancelled"].includes(result.receipt.state)) b.state.runs[run.operationId].completedAt ??= (/* @__PURE__ */ new Date()).toISOString();
+          await this.save(b);
+        },
+        true
+      );
+      return result;
+    });
+  }
+  async actionOutcome(b, actionId, invoke) {
+    try {
+      const result = await invoke();
+      if (result.state !== "completed") throw new WorkspaceError("action_unknown", "Executor action receipt is unsettled");
+      return result;
+    } catch (error) {
+      await this.serial(
+        b,
+        async () => {
+          b.state.blocked ??= {
+            code: "action_unknown",
+            operationId: actionId,
+            message: "Inspect original executor action receipt before maintenance; never replay input/cancellation automatically"
+          };
+          await this.save(b);
+        },
+        true
+      );
+      throw error;
+    }
+  }
+  async write(identity, run, actionId, data, eof = false) {
+    return this.action(async () => {
+      const { b, route } = await this.runRoute(identity, run);
+      return this.actionOutcome(b, actionId, () => route.client.write({ ...run, fence: route.workerFence }, actionId, data, eof));
+    });
+  }
+  async resize(identity, run, actionId, cols, rows) {
+    return this.action(async () => {
+      const { b, route } = await this.runRoute(identity, run);
+      if (!route.client.resize) throw new WorkspaceError("pty_unavailable", "Executor does not advertise terminal resizing");
+      return this.actionOutcome(b, actionId, () => route.client.resize({ ...run, fence: route.workerFence }, actionId, cols, rows));
+    });
+  }
+  async cancel(identity, run, actionId) {
+    return this.action(async () => {
+      const { b, route } = await this.runRoute(identity, run);
+      return this.actionOutcome(b, actionId, () => route.client.cancel({ ...run, fence: route.workerFence }, actionId));
+    });
+  }
+  close() {
+    if (this.closed) return Promise.resolve();
+    if (this.closeTask) return this.closeTask;
+    this.closing = true;
+    const task = this.finishClose();
+    this.closeTask = task;
+    void task.finally(() => {
+      if (!this.closed) this.closeTask = void 0;
+    }).catch(() => {
+    });
+    return task;
+  }
+  async finishClose() {
+    await Promise.allSettled([...this.actions]);
+    await Promise.allSettled([...this.queues.values()]);
+    for (const b of this.benches.values()) await this.refresh(b);
+    if ([...this.benches.values()].some(
+      (b) => b.state.blocked || Object.values(b.state.runs).some((r) => !["completed", "cancelled", "rejected_capacity"].includes(r.state))
+    ))
+      throw new WorkspaceError(
+        "maintenance_required",
+        "Active/unknown runs or sync intents remain; authority lock retained. Drain and review before restart"
+      );
+    const owner = JSON.parse((await readRegular(path.join(this.config.root, ".sync-lock", "owner.json"), 1024)).toString());
+    if (owner.lockId !== this.lockId) throw new WorkspaceError("authority_lost", "Never release a successor's lock");
+    await fs.rm(path.join(this.config.root, ".sync-lock"), { recursive: true });
+    this.closed = true;
+  }
+}
+export {
+  WorkspaceAuthority
+};