@ricsam/r5d-worker 0.0.132 → 0.0.134

package/dist/mjs/workspace-project-config-policy.mjs

@@ -1,21 +1,27 @@
 function deferredProjectConfigurationPendingBranches(projects) {
-  return projects.flatMap((project) => project.branches.map(({ branchName }) => ({ projectId: project.projectId, branchName }))).sort((left, right) => left.projectId.localeCompare(right.projectId) || left.branchName.localeCompare(right.branchName));
+  return projects.filter((project) => !project.executionDisabled).flatMap((project) => project.branches.map(({ branchName }) => ({ projectId: project.projectId, branchName }))).sort((left, right) => left.projectId.localeCompare(right.projectId) || left.branchName.localeCompare(right.branchName));
 }
-function busyProjectConfigurationChangeIds(input) {
+function busyProjectConfigurationChanges(input) {
   const currentById = new Map(input.currentProjects.map((project) => [project.projectId, project]));
   const incomingById = new Map(input.incomingProjects.map((project) => [project.projectId, project]));
   const targets = [...input.activeTargets];
   const busyProjectIds = targets.some((target) => target.type === "workspace" && target.rootProfile === "visible_projects") ? /* @__PURE__ */ new Set([...currentById.keys(), ...incomingById.keys()]) : new Set(targets.flatMap((target) => target.type === "project" ? [target.projectId] : []));
-  return [...busyProjectIds].filter((projectId) => {
+  return [...busyProjectIds].flatMap((projectId) => {
     const current = currentById.get(projectId);
     const incoming = incomingById.get(projectId);
-    if (!current && !incoming) return false;
-    if (!current || !incoming) return true;
-    if (!input.currentProjectReady(current)) return true;
-    return input.currentFingerprint(current) !== input.incomingFingerprint(incoming);
-  }).sort();
+    if (!current && !incoming) return [];
+    if (!current) return [{ projectId, reason: "added" }];
+    if (!incoming) return [{ projectId, reason: "removed" }];
+    if (!input.currentProjectReady(current)) return [{ projectId, reason: "initializing" }];
+    if (input.currentFingerprint(current) !== input.incomingFingerprint(incoming)) return [{ projectId, reason: "changed" }];
+    return [];
+  }).sort((left, right) => left.projectId.localeCompare(right.projectId));
+}
+function describeBusyProjectConfigurationChanges(changes) {
+  return changes.map(({ projectId, reason }) => `${projectId} (${reason})`).join(", ");
 }
 export {
-  busyProjectConfigurationChangeIds,
-  deferredProjectConfigurationPendingBranches
+  busyProjectConfigurationChanges,
+  deferredProjectConfigurationPendingBranches,
+  describeBusyProjectConfigurationChanges
 };

package/dist/types/atomic-rename.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Atomic directory-entry primitives the working-tree mirror needs beyond
+ * `rename(2)`:
+ *
+ * - exchange: swap two existing entries in one step
+ *   (`renameat2(RENAME_EXCHANGE)` on Linux, `renamex_np(RENAME_SWAP)` on
+ *   macOS). After the swap the first path names what the second held and
+ *   vice versa, so a replacement can inspect exactly the entry it displaced
+ *   instead of guessing from a stat taken before the rename.
+ * - no-replace rename: move an entry only while nothing is at the
+ *   destination (`RENAME_NOREPLACE` / `RENAME_EXCL`, or `link(2)` plus
+ *   `unlink(2)` for a regular file where the flag is unavailable).
+ *
+ * Both are reached through `bun:ffi` against the C library already loaded in
+ * the process; nothing is spawned and nothing is compiled. Availability is
+ * never assumed: a filesystem can reject a flag (`EINVAL` on NFS), a runtime
+ * can lack FFI, and some filesystems accept the exchange flag and then
+ * perform a plain replacing rename (observed on a Docker Desktop virtiofs
+ * bind mount), which would lose the displaced entry. `atomicRenamePrimitivesFor`
+ * therefore probes each filesystem once with two scratch files and hands out
+ * primitives whose flags were seen to work there; the caller falls back to a
+ * protocol built from plain POSIX calls for anything that was not.
+ */
+export type AtomicExchangeBackend = "renameat2" | "renamex_np" | "syscall" | "unavailable";
+export type AtomicNoReplaceBackend = "renameat2" | "renamex_np" | "syscall" | "link";
+export type AtomicRenameSupport = {
+    platform: NodeJS.Platform;
+    exchange: AtomicExchangeBackend;
+    noReplace: AtomicNoReplaceBackend;
+    /** Why a native primitive is not used, when it is not. */
+    detail?: string;
+};
+/** Failure of one primitive, carrying the POSIX error name the way `fs` errors do. */
+export declare class AtomicRenameError extends Error {
+    readonly syscall: string;
+    readonly code: string;
+    readonly errno: number;
+    readonly path: string;
+    readonly dest: string;
+    constructor(syscall: string, code: string, errno: number, path: string, dest: string);
+}
+export declare function isAtomicRenameUnsupported(error: unknown): boolean;
+/** What this process can do natively, before any filesystem probe. */
+export declare function atomicRenameSupport(): AtomicRenameSupport;
+/**
+ * Test seam: pretend a primitive is unavailable so the portable fallback
+ * protocols run on a platform that has the native ones. Pass null to clear.
+ */
+export declare function overrideAtomicRenameSupportForTests(value: Partial<Pick<AtomicRenameSupport, "exchange" | "noReplace">> | null): void;
+/** Test seam: forget probe results so the next `atomicRenamePrimitivesFor` probes again. */
+export declare function resetAtomicRenameProbesForTests(): void;
+/**
+ * Atomically exchange the directory entries `a` and `b` (any kinds, same
+ * filesystem) with the process-level primitive, unprobed. Throws
+ * AtomicRenameError `ENOENT` when either is missing and an unsupported code
+ * (see `isAtomicRenameUnsupported`) when the kernel or filesystem cannot
+ * exchange. Prefer `atomicRenamePrimitivesFor` for anything that matters.
+ */
+export declare function exchangePaths(a: string, b: string): void;
+/** Move `from` to `to` only if nothing is at `to` (`EEXIST` otherwise), with the process-level primitive, unprobed. */
+export declare function renameNoReplace(from: string, to: string): void;
+/** Primitives bound to what a probe of one filesystem showed to work there. */
+export type AtomicRenamePrimitives = {
+    support: AtomicRenameSupport;
+    exchange: (a: string, b: string) => void;
+    renameNoReplace: (from: string, to: string) => void;
+};
+/**
+ * Probe the filesystem holding `directory` (which must be writable) once per
+ * device: the exchange flag must actually swap two scratch files (inode
+ * numbers exchanged, both still present), and the native no-replace flag
+ * must actually refuse an existing destination. A flag that fails, or that
+ * succeeds without doing what it promises, is reported as unavailable and
+ * the returned primitives use the fallbacks instead.
+ */
+export declare function probeAtomicRenameSupport(directory: string): AtomicRenameSupport;
+/** Primitives for the filesystem holding `directory`, probed on first use per device (see `probeAtomicRenameSupport`). */
+export declare function atomicRenamePrimitivesFor(directory: string): AtomicRenamePrimitives;

package/dist/types/git-blob-hash.d.ts

@@ -0,0 +1,10 @@
+export type GitObjectHashAlgorithm = "sha1" | "sha256";
+/** The object format an object id of this length belongs to, or null for anything that is not an object id. */
+export declare function gitObjectHashAlgorithmFor(objectId: string): GitObjectHashAlgorithm | null;
+/**
+ * The id `git hash-object` gives `content` as a blob: the hash of the
+ * `blob <size>\0` header followed by the bytes, with no filter applied. The
+ * sync engine hashes checkout bytes with it to ask whether a file still holds
+ * what a commit records without spawning git.
+ */
+export declare function gitBlobHash(content: Buffer, algorithm: GitObjectHashAlgorithm): string;

package/dist/types/main.d.ts

@@ -6,7 +6,9 @@ import { Database } from "bun:sqlite";
 import type { WorkerGitIdentity } from "./git-identity";
 import { configureGitHubRegistryAuthFiles, type PreparedPrivateAuthFileGeneration } from "./registry-auth";
 import { WorkspaceMountHoldFence } from "./workspace-mount-hold-fence";
-import { type WorkspaceHydrationTransactionHooks } from "./workspace-git-sync";
+import { type WorkspaceCommandProjectTarget } from "./workspace-command-targets";
+import { type WorkerHydrationRecovery } from "./workspace-hydration-recovery-state";
+import { type WorkspaceHydrationTransactionHooks, type WorkspaceGitSyncResult } from "./workspace-git-sync";
 type WorkerProjectConfig = {
     projectId: string;
     checkoutPathSegments: [namespace: string, project: string];
@@ -86,6 +88,8 @@ type WorkspaceSyncTrigger = {
     detail?: string;
 };
 type WorkspaceSyncResult = {
+    hydrationRecovery?: WorkerHydrationRecovery;
+    mountSkipReasons?: WorkspaceGitSyncResult["mountSkipReasons"];
     type: "workspace_sync";
     attemptId: string;
     workerLabel: string;
@@ -129,7 +133,7 @@ type WorkspaceSyncResult = {
     };
     error?: string;
     /** Typed reason for a failed outcome the server should surface loudly. */
-    failureReason?: "unsafe_hydration";
+    failureReason?: "unsafe_hydration" | "hydration_recovery_required";
     /** Consecutive in-process recovery bounces taken for unsafe hydration failures. */
     recoveryAttempt?: number;
 };
@@ -284,6 +288,12 @@ type WorkerClientMessage = WorkerRecoveryClientMessage | {
     }>;
     aheadOfOriginBranches: WorkerAheadOfOriginBranch[];
     deferredWorkspaceSyncForIncidentId?: string;
+    /**
+     * The configuration was not applied because these projects have visible
+     * checkout activity; every executable checkout above is pending and the
+     * previous generation stays on disk until a retry lands on idle checkouts.
+     */
+    deferredForBusyProjectIds?: string[];
 } | {
     type: "workspace_sync_started";
     attemptId: string;
@@ -309,6 +319,7 @@ type WorkerServerMessage = WorkerRecoveryServerMessage | {
     workerId: string;
 } | {
     type: "workspace_config";
+    recoverHydrationTransactionId?: string;
     requestId: string;
     projects: WorkerProjectConfig[];
     workspaceRemoteUrl: string;
@@ -403,6 +414,8 @@ type WorkerServerMessage = WorkerRecoveryServerMessage | {
     requestId: string;
     runId: string;
     target: WorkerSessionTarget;
+    /** Sibling checkouts fenced for the command's lifetime alongside `target`; project branches only. */
+    additionalTargets?: WorkspaceCommandProjectTarget[];
     sessionId?: string;
     argv: string[];
     cwd?: string;
@@ -414,6 +427,8 @@ type WorkerServerMessage = WorkerRecoveryServerMessage | {
     requestId: string;
     runId: string;
     target: WorkerSessionTarget;
+    /** Fixed at admission; kept until the process exits, whatever happens to the claim that produced it. */
+    additionalTargets?: WorkspaceCommandProjectTarget[];
     sessionId: string;
     argv: string[];
     command: string;
@@ -442,6 +457,8 @@ type WorkerServerMessage = WorkerRecoveryServerMessage | {
     requestId: string;
     ptyId: string;
     target: WorkerSessionTarget;
+    /** Fixed when the shell opens; kept until the PTY exits. */
+    additionalTargets?: WorkspaceCommandProjectTarget[];
     cols: number;
     rows: number;
     command?: string;
@@ -680,6 +697,8 @@ type WorkerPty = {
 };
 type ActiveWorkerPty = WorkerPty & {
     target: WorkerSessionTarget;
+    /** Declared sibling checkouts, fenced like `target` while the PTY is busy. */
+    additionalTargets: readonly WorkerSessionTarget[];
     foregroundBusy: boolean;
     lastInputAt: number;
     releaseWorkspaceMutation?: () => void;

package/dist/types/three-way-merge.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Pure three-way line merge (classic diff3) for merge hydration.
+ *
+ * The verdict is deliberately conservative: a false conflict only pins a
+ * mount for a cycle, while a false clean silently loses one side's edit. Git
+ * picks one of possibly many minimal diffs per side and its verdict depends on
+ * which, so instead of trusting one alignment this merge only treats a base
+ * line as stable when every minimal diff agrees on it, and only accepts an
+ * identical change from both sides when its alignment is unique. That keeps
+ * the clean verdict a subset of `git merge-file`'s for every minimal diff Git
+ * could choose, and clean output byte-identical to `git merge-file -p ours
+ * base theirs`; the differential test enforces both.
+ */
+export type ThreeWayMergeOptions = {
+    /** Sides with more lines than this are not merged (conflict). */
+    maxLines?: number;
+    /** Two-way diffs with more line edits than this are not merged (conflict); bounds the O((N+M)D) diff. */
+    maxEditDistance?: number;
+    /** Bound on the banded (lines × edits) alignment analysis per side; beyond it the merge conflicts. */
+    maxAlignmentCells?: number;
+    /** Bound on the diagonal visits one two-way diff may spend; beyond it the merge conflicts. */
+    maxDiffWork?: number;
+};
+export type ThreeWayMergeResult = {
+    kind: "clean";
+    content: Buffer;
+} | {
+    kind: "conflict";
+    conflicts: number;
+};
+/** A changed region of a two-way diff: `a[aStart, aEnd)` was replaced by `b[bStart, bEnd)`. */
+export type DiffHunk = {
+    aStart: number;
+    aEnd: number;
+    bStart: number;
+    bEnd: number;
+};
+/** What every minimal diff of a side against the base agrees on, per base line. */
+export type SideAlignment = {
+    /** Base line -> the side line it is matched to in every minimal diff, or -1. */
+    certain: Int32Array;
+    /** 1 where minimal diffs disagree: matched to different side lines, or matched in some and deleted in others. */
+    ambiguous: Uint8Array;
+};
+type LineSequence = ArrayLike<number>;
+/** Git's `buffer_is_binary`: a NUL byte within the first 8000 bytes. */
+export declare function isBinaryContent(content: Buffer): boolean;
+/**
+ * Minimal line diff `a` -> `b` as ordered, non-touching hunks, or null when
+ * the edit distance exceeds `maxEditDistance`. Divide and conquer on the
+ * middle snake keeps memory linear; the explicit stack keeps deep, lopsided
+ * splits off the call stack. The merge only needs the edit distance from it,
+ * the hunks are one of the minimal diffs.
+ */
+export declare function diffLines(a: LineSequence, b: LineSequence, options?: {
+    maxEditDistance?: number;
+    maxWork?: number;
+}): DiffHunk[] | null;
+/**
+ * Classifies every base line by what all minimal diffs `a` -> `b` agree on,
+ * given the length of their common subsequence.
+ *
+ * A minimal diff crosses from base line i to i + 1 either by deleting line i
+ * or by matching it to some b[j]; the crossing is on a minimal diff exactly
+ * when prefix LCS + suffix LCS (+ 1 for a match) reaches `lcsLength`. Both
+ * tables are only needed on the diagonal band any minimal diff stays within,
+ * so the cost is (lines × edits): suffix rows are checkpointed every √N rows
+ * and recomputed per block, prefix rows roll forward. Returns null once the
+ * band exceeds `maxCells`, which the caller treats as a conflict.
+ */
+export declare function analyzeAlignment(a: LineSequence, b: LineSequence, lcsLength: number, maxCells: number): SideAlignment | null;
+export declare function mergeThreeWay(base: Buffer, ours: Buffer, theirs: Buffer, options?: ThreeWayMergeOptions): ThreeWayMergeResult;
+export declare const threeWayMergeTestHarness: {
+    diffLines: typeof diffLines;
+    analyzeAlignment: typeof analyzeAlignment;
+};
+export {};

package/dist/types/working-tree-mirror.d.ts

@@ -1,3 +1,5 @@
+import fs from "node:fs";
+import { type AtomicRenamePrimitives } from "./atomic-rename";
 export type WorkingTreeSourceMode = "all" | "git";
 export type WorkingTreeDeletionMode = "all" | "git";
 export type WorkingTreeMirrorDurability = "per_entry" | "deferred_private_staging";
@@ -50,7 +52,164 @@ export type WorkingTreeInspectionOptions = {
      * disk at that path. Ignored in Git mode, where the index is read directly.
      */
     gitlinks?: ReadonlyMap<string, string>;
+    /**
+     * Receives the `lstat` of every inspected entry, keyed by relative path.
+     * Merge hydration compares these against the stats a later mutation finds
+     * on disk, so a write that lands between inspection and mutation is seen.
+     */
+    stats?: Map<string, fs.Stats>;
+};
+/**
+ * What a projection read for one source entry: enough of the `lstat` to tell
+ * later whether the same path changed since (a rewrite moves ctime, and a
+ * rename-over changes the inode), or the symlink target, or the gitlink
+ * pointer. Recorded by the projection mirror and by merge projection and
+ * consumed by merge hydration.
+ */
+export type ProjectedWorkingTreeEntry = {
+    kind: "file";
+    size: number;
+    mode: number;
+    mtimeMs: number;
+    ctimeMs: number;
+    ino: number;
+} | {
+    kind: "symlink";
+    target: string;
+} | {
+    kind: "gitlink";
+    objectId: string;
+};
+/** The stat fields a projection records, from an `lstat` or `fstat` of a regular file. */
+export declare function projectedFileEntry(stat: fs.Stats): Extract<ProjectedWorkingTreeEntry, {
+    kind: "file";
+}>;
+/** True when a current `lstat` still describes the projected regular file: same inode, size, mode and timestamps. */
+export declare function projectedFileEntryMatches(entry: Extract<ProjectedWorkingTreeEntry, {
+    kind: "file";
+}>, stat: fs.Stats): boolean;
+/** True when two `lstat` results describe the same unchanged entry (kind, inode, size, mode, timestamps). */
+export declare function workingTreeStatsMatch(left: fs.Stats, right: fs.Stats): boolean;
+/** True when two `lstat` results name the same inode. */
+export declare function sameWorkingTreeInode(left: fs.Stats, right: fs.Stats): boolean;
+/**
+ * True when the entry a switch displaced is the very inode its expectation
+ * described, still holding what that expectation saw: same identity, kind,
+ * mode, size and mtime. Its ctime is not compared, because the exchange or
+ * rename that moved it aside set the ctime itself; the expectation's ctime
+ * was already checked immediately before the switch.
+ */
+export declare function displacedEntryMatches(expected: fs.Stats, displaced: fs.Stats): boolean;
+/**
+ * An entry a guarded pass displaced and kept, by absolute path, with the
+ * `lstat` it had the moment it was displaced. It is the exact inode that was
+ * at the path (not a copy), so a rollback can put it back without touching
+ * its bytes and so a write through a descriptor opened before the switch is
+ * still visible on it when the pass settles.
+ */
+export type WorkingTreeRetainedEntry = {
+    path: string;
+    stat: fs.Stats;
+    content?: string;
+};
+/**
+ * Another writer's entry a guarded pass displaced and could not put back at
+ * its path without displacing yet another write: it is kept where it is and
+ * reported instead of being removed. `later_writer`: a newer entry took the
+ * path while this one was being restored. `reappeared`: while the path was
+ * momentarily empty during a fallback replacement, something was created
+ * there; the displaced entry is kept because that creator may have meant to
+ * modify it. `unrestorable`: no primitive could restore it (a directory on a
+ * filesystem without a native no-replace rename).
+ */
+export type WorkingTreeRetainedForeignEntry = {
+    relativePath: string;
+    path: string;
+    reason: "later_writer" | "reappeared" | "unrestorable";
+};
+/**
+ * Thrown by a guarded mirror when the target entry it is about to replace,
+ * remove or create no longer matches the state observed when the mirror was
+ * prepared: something else wrote there in between. The caller rolls the
+ * mount back through the journal instead of finishing over the writer. When
+ * the pass had to keep a displaced writer's entry aside (see
+ * `WorkingTreeRetainedForeignEntry`) the error lists it.
+ */
+export declare class WorkingTreeTargetChangedError extends Error {
+    readonly relativePath: string;
+    readonly retained: WorkingTreeRetainedForeignEntry[];
+    constructor(relativePath: string, options?: {
+        detail?: string;
+        retained?: WorkingTreeRetainedForeignEntry[];
+    });
+}
+/**
+ * One mutation a guarded mirror made, in order. `replaced` is the entry that
+ * was there before (null when the path was created) and `after` the `lstat`
+ * of the entry the mirror left behind (null when it removed the path); it is
+ * the mirror's own entry, identified by inode, never a later writer's.
+ * `displaced` is the replaced or removed entry itself, retained until the
+ * pass settles or its rollback finishes. A rollback undoes an entry only
+ * while the path still shows `after`; anything else means another writer
+ * came later and keeps what it wrote.
+ */
+export type WorkingTreeMirrorJournalEntry = {
+    relativePath: string;
+    replaced: TreeEntry | null;
+    after: fs.Stats | null;
+    /** Immutable bytes owned by the pass, never inferred from the visible path after publication. */
+    afterContent?: string;
+    displaced?: WorkingTreeRetainedEntry;
+};
+export type WorkingTreeMirrorJournal = {
+    entries: WorkingTreeMirrorJournalEntry[];
+    /** The Git index changes the pass applied (its last step); a rollback puts them back. */
+    indexApplied?: WorkingTreeIndexChanges;
+    /** Writers' entries the pass or its rollback displaced and kept aside; never removed by the mirror. */
+    retained?: WorkingTreeRetainedForeignEntry[];
+};
+/** Content a guarded mirror writes at a path instead of copying the source entry (a merged file). */
+export type WorkingTreeMirrorOverride = {
+    content: Buffer;
+    mode: number;
+};
+export type WorkingTreeMirrorGuards = {
+    /**
+     * The target `lstat` each path must still show immediately before it is
+     * mutated (null: the path must still be absent). Paths not listed are
+     * switched against whatever they hold at that moment. A mismatch throws
+     * WorkingTreeTargetChangedError before anything is written at that path.
+     * The pass updates an entry once it has satisfied it (a removal it made
+     * itself leaves the path expected absent), so a path mutated in two steps
+     * is checked against the pass's own intermediate state.
+     */
+    expectations?: Map<string, fs.Stats | null>;
+    /** Known pre-hydration Git blob IDs, when the merge decision already read the bytes. */
+    preBlobs?: ReadonlyMap<string, string>;
+    /** Merged bytes written in place of the source entry's bytes. */
+    overrides?: ReadonlyMap<string, WorkingTreeMirrorOverride>;
+    /** Every mutation is appended here for `rollbackWorkingTreeMirrorJournal`. */
+    journal?: WorkingTreeMirrorJournal;
+};
+/**
+ * Points in a guarded pass at which another writer could interleave, exposed
+ * so tests can place a deterministic write there. `before_switch` and
+ * `before_remove` fire after the path's expectation was verified and
+ * immediately before the exchange, rename or unlink; `after_switch` and
+ * `after_remove` immediately after it, before the displaced entry is
+ * inspected; `before_yield` before a mismatched displaced entry is put back;
+ * `before_settle` before the pass re-inspects its retained entries; the
+ * rollback variants bracket the rollback's own switches. Never set in
+ * production.
+ */
+export type WorkingTreeMirrorRacePhase = "before_switch" | "after_switch" | "before_yield" | "before_remove" | "after_remove" | "before_settle" | "before_rollback_switch" | "before_rollback_remove";
+export type WorkingTreeMirrorRaceEvent = {
+    phase: WorkingTreeMirrorRacePhase;
+    relativePath: string;
+    targetPath: string;
 };
+/** Test seam for deterministic race regressions; pass null to clear. */
+export declare function setWorkingTreeMirrorRaceHook(hook: ((event: WorkingTreeMirrorRaceEvent) => void) | null): void;
 /**
  * Destructive native-tree moves cannot silently apply the Git-target filter:
  * doing so would delete legitimate case-sensitive POSIX filenames after the
@@ -58,20 +217,97 @@ export type WorkingTreeInspectionOptions = {
  * every portable alias must be remediated before the old tree is retired.
  */
 export declare function assertWorkingTreeHasNoPortableGitMetadataAliases(root: string): void;
+type RelativePathInspection = {
+    kind: "entry";
+    absolutePath: string;
+    stat: fs.Stats;
+} | {
+    kind: "missing";
+} | {
+    kind: "blocked";
+    blockingPath: string;
+};
+export type WorkingTreePathInspection = RelativePathInspection;
+/** `lstat` a target-relative path without following any ancestor symlink; see the mirror's own traversal rules. */
+export declare function inspectWorkingTreePath(root: string, relativePath: string): WorkingTreePathInspection;
 export declare function inspectWorkingTree(root: string, mode: WorkingTreeSourceMode, options?: WorkingTreeInspectionOptions): Map<string, TreeEntry>;
-export declare function mirrorWorkingTree(input: {
+/** The primitives a guarded pass or rollback on `targetRoot` would use, after probing its filesystem. */
+export declare function workingTreeAtomicRenameSupport(targetRoot: string): AtomicRenamePrimitives["support"];
+/**
+ * Where a guarded pass on `targetRoot` keeps staged and displaced entries.
+ * Entries left there after a crash are evidence for recovery: each name ends
+ * with the percent-encoded target-relative path of the entry it held.
+ */
+export declare function workingTreeDisplacedRetentionDirectory(targetRoot: string): string | null;
+type MirrorTarget = {
+    existing: Map<string, TreeEntry>;
+    /** Present for Git targets: their index and the submodule directories a mirror must leave alone. */
+    git: {
+        indexRecords: WorkingTreeIndexRecord[];
+        submodules: Map<string, string | null>;
+        /** Submodule directories that hold anything at all; never removed, and their index entries stay. */
+        occupied: Set<string>;
+    } | null;
+};
+export type WorkingTreeMirrorInput = {
     sourceRoot: string;
     targetRoot: string;
     sourceMode: WorkingTreeSourceMode;
     deletionMode: WorkingTreeDeletionMode;
     /** Gitlinks the enclosing repository records for an all-mode source (see `inspectWorkingTree`). */
     sourceGitlinks?: ReadonlyMap<string, string>;
+};
+/**
+ * Both trees of a mirror, inspected once. `desired` is every source entry
+ * (shielded ones included), `existing` the target's deletion-mode entry set,
+ * and `existingStats` the `lstat` of each existing entry as it was seen.
+ * Merge hydration decides per path from this and applies through
+ * `applyWorkingTreeMirror` with guards that compare against those stats.
+ */
+export type PreparedWorkingTreeMirror = {
+    sourceRoot: string;
+    targetRoot: string;
+    deletionMode: WorkingTreeDeletionMode;
+    desired: Map<string, TreeEntry>;
+    existing: Map<string, TreeEntry>;
+    existingStats: Map<string, fs.Stats>;
+    git: MirrorTarget["git"];
+    shielded: Set<string>;
+};
+export declare function prepareWorkingTreeMirror(input: WorkingTreeMirrorInput): PreparedWorkingTreeMirror;
+/**
+ * Restrict what an apply pass touches. Without a selection the mirror makes
+ * the target equal to the source (every desired path written, every existing
+ * path outside the desired set removed). With one, only `write` paths are
+ * copied (or replaced by an override), only `remove` paths are removed, and
+ * `desiredForIndex` is the tree the Git index is reconciled to; every other
+ * path is left exactly as it is. Desired directories are still ensured.
+ */
+export type WorkingTreeMirrorSelection = {
+    write: ReadonlySet<string>;
+    remove: ReadonlySet<string>;
+    desiredForIndex: ReadonlyMap<string, TreeEntry>;
+};
+export type WorkingTreeMirrorApplyOptions = {
+    durability?: WorkingTreeMirrorDurability;
+    guards?: WorkingTreeMirrorGuards;
+    selection?: WorkingTreeMirrorSelection;
+    /** Collect the projection record of every copied or verified source entry. */
+    projected?: Map<string, ProjectedWorkingTreeEntry>;
+};
+export declare function applyWorkingTreeMirror(prepared: PreparedWorkingTreeMirror, options?: WorkingTreeMirrorApplyOptions): {
+    paths: string[];
+    gitlinks: WorkingTreeGitlink[];
+};
+export declare function mirrorWorkingTree(input: WorkingTreeMirrorInput & {
     /**
      * Defer destination fsync only while building an unpublished private tree.
      * The caller must durably fsync that complete tree before publishing it or
      * mutating the source authority.
      */
     durability?: WorkingTreeMirrorDurability;
+    /** Collect the projection record of every copied or verified source entry. */
+    projected?: Map<string, ProjectedWorkingTreeEntry>;
 }): {
     paths: string[];
     gitlinks: WorkingTreeGitlink[];
@@ -107,13 +343,39 @@ export type WorkingTreeMirrorPlan = {
  * target's ignored trees appear only where a desired path lands on them, and
  * its submodule directories only as index changes.
  */
-export declare function planWorkingTreeMirror(input: {
-    sourceRoot: string;
-    targetRoot: string;
-    sourceMode: WorkingTreeSourceMode;
-    deletionMode: WorkingTreeDeletionMode;
-    sourceGitlinks?: ReadonlyMap<string, string>;
+export declare function planWorkingTreeMirror(input: WorkingTreeMirrorInput): WorkingTreeMirrorPlan;
+/**
+ * The plan for an apply pass over `prepared`, optionally restricted to a
+ * selection (see `applyWorkingTreeMirror`): with one, only the selected
+ * removals and writes count, an override always replaces its target entry,
+ * and `desired` lists the selected writes plus the desired directories.
+ */
+export declare function planPreparedWorkingTreeMirror(prepared: PreparedWorkingTreeMirror, options?: {
+    selection?: WorkingTreeMirrorSelection;
+    overrides?: ReadonlyMap<string, WorkingTreeMirrorOverride>;
 }): WorkingTreeMirrorPlan;
+/**
+ * Undo the mutations a guarded apply pass journaled, in reverse order. A
+ * replaced or removed entry the pass still retains (its very inode) is
+ * switched back into place; one already released is rebuilt from the
+ * snapshot `captureWorkingTreeMirrorPlan` took of the plan's replaced
+ * entries. Every restore is itself a guarded switch: an entry is undone only
+ * while the path still shows exactly what the mirror left there (or is still
+ * absent where the mirror removed it), verified by the switch as it happens;
+ * a path that another writer has touched since is left alone and reported in
+ * `abandoned`. Directories the mirror created are removed only when empty.
+ * Returns the target-relative paths it touched for the durability barrier,
+ * and, when there are any, the writer's entries it had to keep aside.
+ */
+export declare function rollbackWorkingTreeMirrorJournal(input: {
+    journal: WorkingTreeMirrorJournal;
+    targetRoot: string;
+    snapshotRoot: string;
+}): {
+    paths: string[];
+    abandoned: string[];
+    retained?: WorkingTreeRetainedForeignEntry[];
+};
 export type WorkingTreeMirrorScope = {
     /** Desired paths that did not exist before the mirror ran; a restore removes them. */
     absent: string[];
@@ -159,3 +421,4 @@ export declare function restoreWorkingTreeMirrorScope(input: {
  * symlinks. Nothing outside the listed paths is read.
  */
 export declare function fsyncWorkingTreePaths(root: string, relativePaths: Iterable<string>): void;
+export {};

package/dist/types/workspace-command-sync-policy.d.ts

@@ -13,12 +13,12 @@ type WorkspaceCommandMutationCoordinator = {
 export type WorkspaceSyncCompletionBarrier = {
     afterCurrent(): Promise<void>;
     /**
-     * Null when no workspace filesystem job holds the target's mount right now;
-     * otherwise a promise that settles once the current holders released it
-     * (rejecting with WorkspaceMountHoldAbortedError when `signal` aborts
-     * first). Workspace targets have no mount and always get null.
+     * Null when no workspace filesystem job holds any of the targets' mounts
+     * right now; otherwise a promise that settles once every current holder
+     * released them (rejecting with WorkspaceMountHoldAbortedError when
+     * `signal` aborts first). Workspace targets have no mount and never hold.
      */
-    mountHold(target: WorkspaceCommandTarget, signal?: AbortSignal): Promise<void> | null;
+    mountHold(targets: readonly WorkspaceCommandTarget[], signal?: AbortSignal): Promise<void> | null;
 };
 /**
  * A project command may reserve as soon as no workspace filesystem job holds
@@ -29,8 +29,14 @@ export type WorkspaceSyncCompletionBarrier = {
  * whole-cycle barrier. Canonical remediation is serialized separately by the
  * mutation gate. Commands without a workspace effect (incident-9 control
  * commands among them) never come here and never wait.
+ *
+ * A command may declare several targets (its own checkout plus the sibling
+ * checkouts its session claimed). Every listed mount is reserved together:
+ * the reservation happens only in a synchronous stretch in which none of
+ * them is held, so a claimed mount that is mid-hydration delays the command
+ * exactly as its own mount would.
  */
-export declare function reserveWorkspaceCommandAfterCurrentSync(target: WorkspaceCommandTarget, coordinator: WorkspaceSyncCompletionBarrier, reserve: () => void, options?: {
+export declare function reserveWorkspaceCommandAfterCurrentSync(target: WorkspaceCommandTarget | readonly WorkspaceCommandTarget[], coordinator: WorkspaceSyncCompletionBarrier, reserve: () => void, options?: {
     signal?: AbortSignal;
 }): Promise<void>;
 /**