@ricsam/r5d-worker 0.0.162 → 0.0.163

package/dist/mjs/runtime/workspace/files.mjs

@@ -17,6 +17,7 @@ const WORKBENCH_OPERATION_MARKERS = [
 ];
 const WORKBENCH_CONFLICT_CODES = /* @__PURE__ */ new Set([
   "conflict",
+  "sync_conflict",
   "workbench_conflict",
   "workbench_operation_in_progress"
 ]);
@@ -99,7 +100,23 @@ async function durableJson(file, value) {
     await dir.close();
   }
 }
-function git(cwd, args, input, indexFile, transport) {
+const PLATFORM_COMMIT_EMAIL = "workspace@invalid";
+const PROJECT_COMMIT_IDENTITY = {
+  GIT_AUTHOR_NAME: "r5d",
+  GIT_AUTHOR_EMAIL: "workspace@r5d.dev",
+  GIT_COMMITTER_NAME: "r5d",
+  GIT_COMMITTER_EMAIL: "workspace@r5d.dev"
+};
+function git(cwd, args, input, indexFile, transport, options = {}) {
+  return runGit(cwd, args, input, indexFile, transport, options).then(({ code, stdout }) => {
+    if (code !== 0) throw new WorkspaceError("git_failed", "Bounded private Git operation failed; preserve state for inspection");
+    return stdout;
+  });
+}
+function gitResult(cwd, args, input, options = {}) {
+  return runGit(cwd, args, input, void 0, void 0, options);
+}
+function runGit(cwd, args, input, indexFile, transport, options = {}) {
   if (indexFile && path.dirname(indexFile) !== cwd) throw new WorkspaceError("unsafe_path", "Index override must be authority-owned");
   return new Promise((resolve, reject) => {
     const child = spawn(
@@ -142,7 +159,8 @@ function git(cwd, args, input, indexFile, transport) {
           // Only the reviewed GitHub import/push boundary supplies this option.
           // Tokens are process-private environment values, never argv, URLs or diagnostics.
           ...transport ? { GIT_CONFIG_COUNT: "3", GIT_CONFIG_KEY_0: "http.https://github.com/.extraheader", GIT_CONFIG_VALUE_0: `AUTHORIZATION: basic ${Buffer.from(`x-access-token:${transport.token}`).toString("base64")}`, GIT_CONFIG_KEY_1: "http.followRedirects", GIT_CONFIG_VALUE_1: "false", GIT_CONFIG_KEY_2: "credential.helper", GIT_CONFIG_VALUE_2: "" } : {},
-          ...indexFile ? { GIT_INDEX_FILE: indexFile } : {}
+          ...indexFile ? { GIT_INDEX_FILE: indexFile } : {},
+          ...options.env ?? {}
         },
         stdio: ["pipe", "pipe", "pipe"]
       }
@@ -152,7 +170,7 @@ function git(cwd, args, input, indexFile, transport) {
     const timer = setTimeout(() => {
       failed = true;
       child.kill("SIGKILL");
-    }, 3e4);
+    }, options.timeoutMs ?? 3e4);
     child.stdout.on("data", (b) => {
       bytes += b.length;
       if (bytes > 32 * 1024 * 1024) {
@@ -173,9 +191,9 @@ function git(cwd, args, input, indexFile, transport) {
     });
     child.on("close", (code) => {
       clearTimeout(timer);
-      if (failed || code !== 0)
+      if (failed || code === null)
         reject(new WorkspaceError("git_failed", "Bounded private Git operation failed; preserve state for inspection"));
-      else resolve(Buffer.concat(output));
+      else resolve({ code, stdout: Buffer.concat(output) });
     });
     child.stdin.on("error", () => {
     });
@@ -420,11 +438,14 @@ async function snapshotTree(repo, cwd, canonicalHead, maxBytes = 128 * 1024 * 10
   return (await git(repo, ["write-tree"])).toString().trim();
 }
 export {
+  PLATFORM_COMMIT_EMAIL,
+  PROJECT_COMMIT_IDENTITY,
   WORKBENCH_CONFLICT_CODES,
   WORKBENCH_OPERATION_MARKERS,
   durableJson,
   ensureAuthorityGitRepositoryLayout,
   git,
+  gitResult,
   materializeTree,
   noSymlinkAncestors,
   privateRoot,

package/dist/mjs/runtime/workspace/outer.mjs

@@ -0,0 +1,286 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { GitOid, STORAGE_LIMITS, safeTreePath } from "./storage-wire.mjs";
+import { WorkspaceError } from "./contracts.mjs";
+import { git, gitResult, readRegular, sourceBytes } from "./files.mjs";
+const OUTER_BRANCH = "main";
+const OUTER_REF = `refs/heads/${OUTER_BRANCH}`;
+const OUTER_SNAPSHOT_LIMIT_BYTES = 5 * 1024 * 1024;
+const OUTER_GIT_TIMEOUT_MS = 10 * 6e4;
+const OUTER_CONFLICT_CODE = "sync_conflict";
+const LEGACY_ACCOUNT_README = "# Account workspace\n";
+const OUTER_EXCLUDES = [
+  "/artifacts/",
+  "/.incoming/",
+  ".r5d/",
+  ".r5d-next/",
+  ".env",
+  ".env.*",
+  "!.env.example",
+  "*.pem",
+  "*.key",
+  "*.p12",
+  "*.pfx",
+  "id_rsa",
+  "id_ed25519",
+  "kubeconfig",
+  ".ssh/",
+  ".aws/",
+  ".kube/",
+  ".git-credentials",
+  ".netrc",
+  ".pypirc"
+];
+class OuterSnapshotRefusal extends WorkspaceError {
+  constructor(code, message, paths) {
+    super(code, message);
+    this.paths = paths;
+    this.name = "OuterSnapshotRefusal";
+  }
+  paths;
+}
+const nulSplit = (output) => {
+  if (!Buffer.from(output.toString("utf8")).equals(output)) throw new WorkspaceError("unsafe_path", "Non-UTF8 names unsupported");
+  return output.toString("utf8").split("\0").filter(Boolean);
+};
+const withinRoot = (file, root) => file === root || file.startsWith(`${root}/`);
+const MAX_REPORTED_PATHS = 50;
+class OuterRepository {
+  constructor(gitDir, workTree) {
+    this.gitDir = gitDir;
+    this.workTree = workTree;
+  }
+  gitDir;
+  workTree;
+  static async open(gitDir, workTree) {
+    const exists = await fs.lstat(gitDir).then(
+      (stat) => stat.isDirectory(),
+      (error) => {
+        if (error.code === "ENOENT") return false;
+        throw error;
+      }
+    );
+    if (!exists) {
+      await fs.mkdir(gitDir, { recursive: true, mode: 448 });
+      await git(gitDir, ["init", "--bare", "--template=", "--object-format=sha1", "."]);
+    }
+    const repository = new OuterRepository(gitDir, workTree);
+    await fs.mkdir(path.join(gitDir, "info"), { recursive: true, mode: 448 });
+    await fs.writeFile(path.join(gitDir, "info", "exclude"), `${OUTER_EXCLUDES.join("\n")}
+`, { mode: 384 });
+    await repository.run(["config", "core.bare", "false"]);
+    return repository;
+  }
+  run(args, input, options = {}) {
+    return git(this.gitDir, ["--git-dir", this.gitDir, "--work-tree", this.workTree, ...args], input, void 0, void 0, {
+      timeoutMs: options.timeoutMs ?? OUTER_GIT_TIMEOUT_MS
+    });
+  }
+  result(args, input) {
+    return gitResult(this.gitDir, ["--git-dir", this.gitDir, "--work-tree", this.workTree, ...args], input, {
+      timeoutMs: OUTER_GIT_TIMEOUT_MS
+    });
+  }
+  async head() {
+    const { code, stdout } = await this.result(["rev-parse", "--verify", "--quiet", OUTER_REF]);
+    if (code === 1) return null;
+    if (code !== 0) throw new WorkspaceError("git_failed", "Outer repository head is unreadable");
+    return GitOid.parse(stdout.toString("utf8").trim());
+  }
+  async setHead(commit) {
+    await this.run(["update-ref", OUTER_REF, GitOid.parse(commit)]);
+  }
+  async has(object) {
+    return (await this.result(["cat-file", "-e", `${GitOid.parse(object)}^{commit}`])).code === 0;
+  }
+  async treeOf(commit) {
+    return GitOid.parse((await this.run(["rev-parse", `${GitOid.parse(commit)}^{tree}`])).toString("utf8").trim());
+  }
+  async emptyTree() {
+    return GitOid.parse((await this.run(["hash-object", "-t", "tree", "--stdin"], "")).toString("utf8").trim());
+  }
+  async isAncestor(ancestor, descendant) {
+    const { code } = await this.result(["merge-base", "--is-ancestor", GitOid.parse(ancestor), GitOid.parse(descendant)]);
+    if (code !== 0 && code !== 1) throw new WorkspaceError("git_failed", "Outer repository ancestry is unreadable");
+    return code === 0;
+  }
+  async listTree(tree) {
+    const records = nulSplit(await this.run(["ls-tree", "-r", "-z", "--full-tree", tree]));
+    if (records.length > STORAGE_LIMITS.treeEntries) throw new WorkspaceError("too_large", "Too many workspace entries");
+    return records.map((record) => {
+      const match = /^(\d{6}) (blob|commit|tree) ([0-9a-f]{40})\t(.+)$/.exec(record);
+      if (!match) throw new WorkspaceError("unsafe_tree", "Malformed workspace tree entry");
+      safeTreePath(match[4]);
+      return { mode: match[1], oid: match[3], file: match[4], ...match[2] === "blob" ? {} : { type: match[2] } };
+    });
+  }
+  /** Git refuses to walk into a nested repository until the outer index holds
+   * at least one path beneath it. That entry is written directly, bypassing the
+   * walk; afterwards the checkout is an ordinary directory to every command. A
+   * checkout whose tracked count drops to zero silently disappears again, so
+   * this runs before every snapshot rather than once. */
+  async seed(inners) {
+    for (const inner of inners) {
+      if ((await this.run(["ls-files", "-z", "--", `${inner.root}/`])).length) continue;
+      const seed = await this.seedCandidate(inner);
+      if (seed) await this.run(["update-index", "--add", "--", seed]);
+    }
+  }
+  async seedCandidate(inner) {
+    const directory = path.join(this.workTree, inner.root);
+    const present = async (file) => fs.lstat(path.join(directory, file)).then((stat) => stat.isFile() && !stat.isSymbolicLink(), () => false);
+    for (const file of [...await inner.tracked()].sort()) if (await present(file)) return `${inner.root}/${file}`;
+    const entries = await fs.readdir(directory, { withFileTypes: true }).catch((error) => {
+      if (error.code === "ENOENT" || error.code === "ENOTDIR") return [];
+      throw error;
+    });
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name)))
+      if (entry.isFile() && !entry.isSymbolicLink() && entry.name.toLowerCase() !== ".git") return `${inner.root}/${entry.name}`;
+    return null;
+  }
+  /** Stage the whole workspace and measure what no inner repository explains.
+   * Inside a checkout, a path its HEAD tracks was asked for by whoever imported
+   * or committed it and costs nothing; a path it ignores never reaches the walk.
+   * Everything else, and everything outside every checkout, counts in full. */
+  async snapshot(inners, options = {}) {
+    const limit = options.limitBytes ?? OUTER_SNAPSHOT_LIMIT_BYTES;
+    await this.seed(inners);
+    const dependencies = nulSplit(
+      await this.run(["ls-files", "--others", "--exclude-standard", "--directory", "-z", "--", ":(glob)**/node_modules/**"])
+    );
+    if (dependencies.length && !options.allowLargeDiff)
+      throw new OuterSnapshotRefusal("too_large", "An unignored dependency tree exceeds the automatic publication limit", dependencies.slice(0, MAX_REPORTED_PATHS));
+    const others = nulSplit(await this.run(["ls-files", "--others", "--exclude-standard", "-z"]));
+    const foreign = others.filter((file) => file.endsWith("/")).map((file) => file.slice(0, -1));
+    const tracked = /* @__PURE__ */ new Map();
+    let unexplainedBytes = 0;
+    const unexplainedPaths = [];
+    for (const file of others) {
+      if (file.endsWith("/")) continue;
+      const inner = inners.find((candidate) => withinRoot(file, candidate.root));
+      if (inner) {
+        let set = tracked.get(inner.root);
+        if (!set) tracked.set(inner.root, set = await inner.tracked());
+        if (set.has(file.slice(inner.root.length + 1))) continue;
+      }
+      const stat = await fs.lstat(path.join(this.workTree, file)).catch((error) => {
+        if (error.code === "ENOENT" || error.code === "ENOTDIR") return null;
+        throw error;
+      });
+      if (!stat?.isFile()) continue;
+      unexplainedBytes += stat.size;
+      unexplainedPaths.push(file);
+      if (unexplainedBytes > limit && !options.allowLargeDiff)
+        throw new OuterSnapshotRefusal(
+          "too_large",
+          `Unexplained workspace content exceeds the ${limit}-byte automatic publication limit`,
+          unexplainedPaths.slice(0, MAX_REPORTED_PATHS)
+        );
+    }
+    for (const file of unexplainedPaths) {
+      const bytes = await readRegular(path.join(this.workTree, file)).catch((error) => {
+        if (error instanceof WorkspaceError) throw new OuterSnapshotRefusal(error.code, error.message, [file]);
+        throw error;
+      });
+      try {
+        sourceBytes(bytes, file);
+      } catch (error) {
+        if (error instanceof WorkspaceError) throw new OuterSnapshotRefusal(error.code, error.message, [file]);
+        throw error;
+      }
+    }
+    await this.run(["add", "-A", "--", ".", ...foreign.map((directory) => `:(exclude,literal)${directory}`)]);
+    await this.stripUnsupported();
+    const tree = GitOid.parse((await this.run(["write-tree"])).toString("utf8").trim());
+    return { tree, unexplainedBytes, unexplainedPaths };
+  }
+  /** Staging records a symlink as a link entry, and a nested repository that
+   * appeared between the walk and the add as a gitlink. Neither can be
+   * materialized on another host; both are dropped from the index without
+   * touching the working tree. */
+  async stripUnsupported() {
+    const unsupported = nulSplit(await this.run(["ls-files", "--stage", "-z"])).map((record) => /^(\d{6}) [0-9a-f]{40} \d\t(.+)$/.exec(record)).filter((match) => !!match && (match[1] === "160000" || match[1] === "120000")).map((match) => match[2]);
+    if (unsupported.length) await this.run(["update-index", "--force-remove", "-z", "--stdin"], `${unsupported.join("\0")}\0`);
+  }
+  async commit(tree, parents, message) {
+    const args = ["commit-tree", GitOid.parse(tree)];
+    for (const parent of parents) args.push("-p", GitOid.parse(parent));
+    return GitOid.parse((await this.run(args, `${message}
+`)).toString("utf8").trim());
+  }
+  /** A three-way merge computed entirely in the object store. The result tree
+   * of a conflicted merge carries ordinary conflict markers in the files named. */
+  async merge(ours, theirs) {
+    const { code, stdout } = await this.result(["merge-tree", "--write-tree", "-z", "--name-only", "--no-messages", GitOid.parse(ours), GitOid.parse(theirs)]);
+    if (code !== 0 && code !== 1) throw new WorkspaceError("git_failed", "Outer repository merge failed");
+    const tokens = stdout.toString("utf8").split("\0");
+    const tree = GitOid.parse(tokens[0].trim());
+    const conflicts = [];
+    if (code === 1) for (const token of tokens.slice(1)) {
+      if (!token) break;
+      safeTreePath(token);
+      conflicts.push(token);
+    }
+    return { tree, conflicts };
+  }
+  /** Move the working tree from one tree to another without clobbering anything
+   * edited since the index last saw it. Git refuses the whole update when any
+   * path it would change is locally modified, so a refusal is transient by
+   * construction: the next snapshot picks that edit up and the merge recurs. */
+  async apply(fromTree, toTree) {
+    const { code } = await this.result(["read-tree", "-m", "-u", GitOid.parse(fromTree), GitOid.parse(toTree)]);
+    if (code !== 0) throw new WorkspaceError("apply_refused", "Concurrent edits kept the workspace from taking the merged tree; retried next cycle");
+  }
+  /** Materialize a commit into a working tree that holds none of its paths yet. */
+  async checkout(commit) {
+    await this.run(["read-tree", GitOid.parse(commit)]);
+    await this.run(["checkout-index", "-a"]);
+  }
+  /** Reset index and working tree to a commit, deleting tracked paths it lacks.
+   * Never `clean`: the second `-f` that would reach nested repositories is the
+   * one switch this repository must never pass. */
+  async reset(commit) {
+    await this.run(["reset", "--hard", GitOid.parse(commit)]);
+  }
+  async diffPaths(fromTree, toTree) {
+    return nulSplit(await this.run(["diff-tree", "-r", "--name-only", "-z", "--no-renames", GitOid.parse(fromTree), GitOid.parse(toTree)]));
+  }
+  /** Objects reachable from the head that the mirror lacks. The bundle names the
+   * branch, which the storage side verifies before it accepts the head. */
+  async bundle(exclude) {
+    const file = path.join(this.gitDir, `${randomUUID()}.bundle`);
+    try {
+      await this.run(["bundle", "create", file, OUTER_REF, ...exclude ? [`^${GitOid.parse(exclude)}`] : []]);
+      return await readRegular(file, STORAGE_LIMITS.blobBytes);
+    } finally {
+      await fs.rm(file, { force: true });
+    }
+  }
+  async unbundle(bytes) {
+    const file = path.join(this.gitDir, `${randomUUID()}.bundle`);
+    try {
+      await fs.writeFile(file, bytes, { mode: 384, flag: "wx" });
+      await this.run(["bundle", "unbundle", file]);
+    } finally {
+      await fs.rm(file, { force: true });
+    }
+  }
+  /** Whether a commit's tree is exactly the legacy account bootstrap. */
+  async isLegacyBootstrap(commit) {
+    const entries = await this.listTree(await this.treeOf(commit));
+    if (entries.length !== 1 || entries[0].file !== "README.md" || entries[0].mode !== "100644") return false;
+    return (await this.run(["cat-file", "blob", entries[0].oid])).toString("utf8") === LEGACY_ACCOUNT_README;
+  }
+}
+export {
+  LEGACY_ACCOUNT_README,
+  OUTER_BRANCH,
+  OUTER_CONFLICT_CODE,
+  OUTER_EXCLUDES,
+  OUTER_GIT_TIMEOUT_MS,
+  OUTER_REF,
+  OUTER_SNAPSHOT_LIMIT_BYTES,
+  OuterRepository,
+  OuterSnapshotRefusal
+};

package/dist/mjs/runtime/workspace/storage-wire.mjs

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { OwnershipFence, RuntimeId } from "@ricsam/r5d-api/runtime-protocol";
-const STORAGE_LIMITS = { chunkBytes: 64 * 1024, blobBytes: 128 * 1024 * 1024, requestBytes: 96 * 1024, treeEntries: 1e4 };
+const STORAGE_LIMITS = { chunkBytes: 64 * 1024, blobBytes: 128 * 1024 * 1024, requestBytes: 96 * 1024, treeEntries: 2e5 };
 const StorageId = z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,99}$/);
 const GitOid = z.string().regex(/^[0-9a-f]{40}$/);
 const BranchName = z.string().min(1).max(150).refine((value) => value.split("/").every((part) => /^[a-zA-Z0-9][a-zA-Z0-9_-]*$/.test(part)));
@@ -27,7 +27,10 @@ const StorageRequest = z.discriminatedUnion("method", [
     branch: BranchName,
     expectedHead: GitOid.nullable(),
     commit: GitOid,
-    bundleId: StorageId
+    bundleId: StorageId,
+    /** A mirror publishes whatever head the checkout has, rewinds included;
+     * the head compare-and-set still applies. */
+    force: z.boolean().optional()
   }).strict(),
   z.object({
     method: z.literal("blob.append"),

package/dist/types/personal/publication-refusal.d.ts

@@ -7,6 +7,10 @@
  * command before it counts as evidence of a stuck checkout. */
 /** Leaves the checkout holding unpublished conflict state. */
 export declare const CONFLICT_PUBLICATION_CODES: ReadonlySet<string>;
+/** Refusals that clear themselves: a concurrent edit kept a merged tree from
+ * landing, or the mirror moved between read and publish. The next cycle
+ * repeats the work; nothing durable happened and nothing is reported. */
+export declare const TRANSIENT_PUBLICATION_CODES: ReadonlySet<string>;
 /** Refused because the source candidate itself is unsafe or oversized. */
 export declare const BLOCKED_PUBLICATION_CODES: ReadonlySet<string>;
 /** Consecutive identical observations required before electing an incident.

package/dist/types/personal/runtime.d.ts

@@ -104,7 +104,8 @@ export type PersonalWorkerRuntime = Awaited<ReturnType<typeof openPersonalWorker
 export declare function openPersonalWorkerRuntime(options: {
     root: string;
     grant: z.infer<typeof PersonalWorkerGrant>;
-    storage: (sessionId: string) => StorageTransport;
+    /** A null session is the account scope: the outer repository is bound to no conversation. */
+    storage: (sessionId: string | null) => StorageTransport;
     cliEntrypoint?: string;
     /** Internal test/embedding override. Personal workers publish every minute. */
     publicationIntervalMs?: number;
@@ -144,7 +145,7 @@ export declare function openPersonalWorkerRuntime(options: {
     authority: WorkspaceAuthority;
     synchronize: () => Promise<{
         workbenchId: string;
-        head?: string;
+        head?: string | null;
         unchanged?: boolean;
         error?: string;
     }[]>;

package/dist/types/runtime/workspace/authority.d.ts

@@ -1,6 +1,6 @@
 import { OperationEnvelope } from "@ricsam/r5d-api/runtime-protocol";
 import { type PollResult, type RunIdentity } from "../protocol";
-import { WorkspaceConfig, type ExecutorRoute, type WorkspaceIdentity, type ApprovedWorkbench as ApprovedWorkbenchInput } from "./contracts";
+import { WorkspaceConfig, type ExecutorRoute, type WorkspaceIdentity, type OuterState, type ApprovedWorkbench as ApprovedWorkbenchInput } from "./contracts";
 import { SessionArtifactChunk } from "./artifacts";
 import { WorkspaceFileWrite } from "./file-write";
 import { WorkspaceStorageClient } from "./storage-client";
@@ -10,6 +10,12 @@ export interface WorkspaceAuthorityOptions {
     executor: (identity: WorkspaceIdentity) => Promise<ExecutorRoute>;
     /** Trusted catalog authorization; never a client-supplied filesystem path. */
     resolveWorkbench?: (identity: WorkspaceIdentity) => Promise<ApprovedWorkbenchInput | null>;
+    /** Storage for the account's outer repository, bound to no session. Its
+     * presence selects the outer-repository model: the workspace root is one
+     * repository whose files synchronize as a unit and whose project checkouts
+     * are mirrored, not published, per branch. Without it linked checkouts keep
+     * publishing per project, which the server workspace service relies on. */
+    accountStorage?: (userId: string) => Promise<WorkspaceStorageClient>;
 }
 /** Independent resource owner. Run receipts and workbench never live in replaceable adapters/gateways.
  * Private root is exclusively owned; a crash leaves lock+intent for explicit maintenance.
@@ -25,6 +31,7 @@ export declare class WorkspaceAuthority {
     private closeTask?;
     private readonly actions;
     private readonly repositoryInitializations;
+    private outerRepository?;
     private pending;
     private constructor();
     private expectedCwd;
@@ -178,6 +185,7 @@ export declare class WorkspaceAuthority {
     private save;
     private owned;
     private serial;
+    private serialKey;
     private route;
     private storage;
     private refresh;
@@ -191,6 +199,7 @@ export declare class WorkspaceAuthority {
      * run, so publication defers to it instead of electing an incident over it. */
     workbenchHasLiveRun(identity: WorkspaceIdentity): Promise<boolean>;
     status(identity: WorkspaceIdentity): Promise<{
+        outer?: OuterState | undefined;
         files: string[] | null;
         initialized: boolean;
         head: string | null;
@@ -204,6 +213,7 @@ export declare class WorkspaceAuthority {
             operationId?: string;
             commit?: string;
         };
+        mirroredHead?: string | null;
         runs: Record<string, {
             sessionId?: string;
             artifactEnvironment?: boolean;
@@ -235,10 +245,11 @@ export declare class WorkspaceAuthority {
     /** No-argument hydration is initial-only. Explicit expectedBase permits a
      * clean workbench refresh; process/PTY liveness never gates synchronization. */
     hydrate(identity: WorkspaceIdentity, expectedBase?: string): Promise<{
-        head: string;
+        head: string | null;
+        unchanged: boolean;
+        integrated?: string;
     } | {
         head: string;
-        unchanged: boolean;
     }>;
     private hydrateIdle;
     private assertFreshAccountWorkbench;
@@ -250,6 +261,11 @@ export declare class WorkspaceAuthority {
         unchanged?: boolean;
     }>;
     private installGitPolicy;
+    /** This repository is also the common Git directory for the visible project
+     * worktrees. Keep their ordinary Git topology pointed at GitHub; mirroring is
+     * performed by WorkspaceAuthority directly and must never be exposed as the
+     * checkout's origin. */
+    private configureLinkedRemote;
     /** Scoped receipt lookup never repeats a file effect; completion can clear its own crash marker. */
     fileWriteResult(identity: WorkspaceIdentity, input: {
         id: string;
@@ -309,7 +325,7 @@ export declare class WorkspaceAuthority {
             expectedHead?: string | null;
         };
     }): Promise<{
-        head: string | null;
+        head: string;
         pushed: boolean;
     }>;
     archiveBranch(identity: WorkspaceIdentity, input: {
@@ -327,10 +343,72 @@ export declare class WorkspaceAuthority {
         retained: boolean;
         head: string;
     }>;
+    private outerEnabled;
+    private outerStateFile;
+    private outer;
+    private saveOuter;
+    outerStatus(userId: string): Promise<OuterState>;
+    private accountRepositoryId;
+    private provisionId;
+    private hasCommit;
+    private innerHead;
+    private headMatches;
+    private innerTracked;
+    /** Platform snapshot commits from the per-project model sit on top of the
+     * GitHub tip. Hydration peels them so a checkout's history is its own. */
+    private platformSnapshot;
+    private firstParent;
+    /** Every initialized project checkout beneath the workspace root, for the
+     * outer walk and the measure. */
+    private innerCheckouts;
+    /** The mirror's head for a branch, or null when it has none. Only a caller
+     * that owns the repository's existence provisions it: a project repository
+     * is provisioned by its seed or import under that action's own identity. */
+    private remoteHead;
+    private downloadBundle;
+    private uploadBundle;
+    private unbundleInto;
+    private forcePublishSupported;
+    /** One synchronization cycle of the outer repository: snapshot the workspace,
+     * integrate what the mirror gained, publish what changed. Serialized on its
+     * own queue; project checkouts stay ordinary concurrent writers whose later
+     * edits the next cycle observes. */
+    synchronizeOuter(userId: string, options?: {
+        allowLargeDiff?: boolean;
+        resolveConflict?: boolean;
+        requireHead?: string;
+        bootstrapOnly?: boolean;
+    }): Promise<{
+        head: string | null;
+        unchanged: boolean;
+        integrated?: string;
+    }>;
+    private synchronizeOuterIdle;
+    /** Push a project checkout's own HEAD to its mirror. Last push wins: no merge
+     * is attempted, and a rewind or rewrite replaces the mirror as readily as a
+     * fast-forward. A lost acknowledgement needs no reconciliation because the
+     * next cycle simply observes the mirror already holds the head. */
+    private mirrorInnerIdle;
+    /** Mirror one project checkout now, outside the periodic cycle. */
+    mirror(identity: WorkspaceIdentity): Promise<{
+        head: string | null;
+        unchanged: boolean;
+    }>;
+    /** Commit the checkout's working tree to its own history on the user's behalf. */
+    private commitInnerIdle;
+    /** Install a project checkout from its mirror. Files may already be present
+     * because the outer repository delivered them first; the worktree is then
+     * created around them and they show as ordinary dirty content. */
+    private hydrateLinkedIdle;
+    private installLinkedWorktree;
     publish(identity: WorkspaceIdentity, options?: {
         allowLargeDiff?: boolean;
         allowBlockedConflict?: boolean;
     }): Promise<{
+        head: string | null;
+        unchanged: boolean;
+        integrated?: string;
+    } | {
         head: string;
         unchanged?: boolean;
     }>;

package/dist/types/runtime/workspace/contracts.d.ts

@@ -74,6 +74,8 @@ export type WorkspaceState = {
         operationId?: string;
         commit?: string;
     };
+    /** Inner HEAD the mirror is known to hold, for linked project checkouts. */
+    mirroredHead?: string | null;
     runs: Record<string, {
         sessionId?: string;
         artifactEnvironment?: boolean;
@@ -87,3 +89,27 @@ export type WorkspaceState = {
         completedAt?: string;
     }>;
 };
+/** Durable state of the account's outer repository on this worker. */
+export type OuterState = {
+    userId: string;
+    initialized: boolean;
+    /** Head the mirror is known to hold; the parent of the next snapshot. */
+    publishedHead: string | null;
+    /** publishedHead, or the one unpublished snapshot or merge on top of it. */
+    head: string | null;
+    blocked: null | {
+        code: string;
+        message: string;
+        paths?: string[];
+        operationId?: string;
+        commit?: string;
+    };
+    /** A merge that conflicted: the markers are in the working tree and the next
+     * snapshot is the resolution, committed with both sides as parents. */
+    conflict: null | {
+        ours: string;
+        theirs: string;
+        tree: string;
+        paths: string[];
+    };
+};

package/dist/types/runtime/workspace/files.d.ts

@@ -19,9 +19,32 @@ export declare function durableJson(file: string, value: unknown): Promise<void>
 /** All Git operates in authority-created repos; NEVER workbench .git/config/index.
  * hash-object --no-filters and update-index --index-info replace git add/checkout.
  */
+export type GitOptions = {
+    /** One project's publication fits the default; a whole-workspace walk does not. */
+    timeoutMs?: number;
+    /** Commits that belong to the project's own history carry its identity, not
+     * the platform's: the platform identity marks snapshots that hydration peels. */
+    env?: Record<string, string>;
+};
+/** Committer of platform-authored snapshot commits, recognised by hydration. */
+export declare const PLATFORM_COMMIT_EMAIL = "workspace@invalid";
+/** Identity of commits made in a project's own history on the user's behalf. */
+export declare const PROJECT_COMMIT_IDENTITY: {
+    readonly GIT_AUTHOR_NAME: "r5d";
+    readonly GIT_AUTHOR_EMAIL: "workspace@r5d.dev";
+    readonly GIT_COMMITTER_NAME: "r5d";
+    readonly GIT_COMMITTER_EMAIL: "workspace@r5d.dev";
+};
 export declare function git(cwd: string, args: string[], input?: Buffer | string, indexFile?: string, transport?: {
     token: string;
-}): Promise<Buffer>;
+}, options?: GitOptions): Promise<Buffer>;
+/** Some Git commands answer with their exit code (`merge-base --is-ancestor`,
+ * `merge-tree`, `rev-parse --verify --quiet`). Only a killed or overflowing
+ * process is a failure here; the caller interprets the code. */
+export declare function gitResult(cwd: string, args: string[], input?: Buffer | string, options?: GitOptions): Promise<{
+    code: number;
+    stdout: Buffer;
+}>;
 export declare function sourcePath(file: string): void;
 export declare function sourceBytes(bytes: Buffer, file?: string): void;
 export type TreeEntry = {