@ricsam/r5d-worker 0.0.123 → 0.0.124

package/dist/types/recovery-store.d.ts

@@ -11,6 +11,12 @@ export declare class WorkerRecoveryStore {
     readonly ledgerId: string;
     constructor(filename: string);
     close(): void;
+    /**
+     * Run several store operations as one durable commit (one FULL fsync).
+     * Operations that open their own transaction nest as savepoints. A throw
+     * rolls the whole group back; callers treat that as a journal failure.
+     */
+    batch<T>(operations: () => T): T;
     private row;
     admit(message: Message & {
         requestId: string;

package/dist/types/session-file-mutations.d.ts

@@ -0,0 +1,22 @@
+/**
+ * File mutations (write, edit, plan updates) run on the asynchronous
+ * filesystem API, so a write can still be in flight when a session is
+ * stopped. A Stop acknowledges cleanup only after every mutation that had
+ * already started for the session has actually settled; mutations that were
+ * still queued re-check the session's cancellation immediately before their
+ * first write and never start. The tracker records the former; the admission
+ * fence inside each mutation's queue callback provides the latter.
+ */
+export declare class SessionFileMutationTracker {
+    private readonly inFlight;
+    /** Register a started mutation; it is forgotten when it settles, however it settles. */
+    track<T>(sessionId: string, mutation: Promise<T>): Promise<T>;
+    count(sessionId: string): number;
+    /**
+     * Resolves once every mutation tracked for the session at the time of the
+     * call has settled. Mutations started later are not joined: the session's
+     * cancellation marker, recorded before this is awaited, makes their
+     * admission recheck refuse them.
+     */
+    settled(sessionId: string): Promise<void>;
+}

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

@@ -1,5 +1,7 @@
-type WorkspaceCommandTarget = {
+export type WorkspaceCommandTarget = {
     type: "project";
+    projectId: string;
+    branchName: string;
 } | {
     type: "workspace";
     rootProfile: "visible_projects" | "canonical_sync";
@@ -8,16 +10,29 @@ type WorkspaceCommandMutationCoordinator = {
     runMutation<T>(operation: () => Promise<T> | T): Promise<T>;
     acquireMutation(): Promise<() => void>;
 };
-type WorkspaceSyncCompletionBarrier = {
+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.
+     */
+    mountHold(target: WorkspaceCommandTarget, signal?: AbortSignal): Promise<void> | null;
 };
 /**
- * A project command may reserve immediately: per-mount hydration rechecks its
- * busy predicate immediately before touching visible bytes. A visible-projects
- * workspace command spans every project, so it keeps the whole-cycle barrier.
- * Canonical remediation is serialized separately by the mutation gate.
+ * A project command may reserve as soon as no workspace filesystem job holds
+ * its mount: per-mount hydration and projection observe busy-ness before they
+ * dispatch a job and hold the mount until the job ended, so a reservation
+ * taken here is never interleaved with a job reading or writing the mount. A
+ * visible-projects workspace command spans every project, so it keeps the
+ * 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.
  */
-export declare function reserveWorkspaceCommandAfterCurrentSync(target: WorkspaceCommandTarget, coordinator: WorkspaceSyncCompletionBarrier, reserve: () => void): Promise<void>;
+export declare function reserveWorkspaceCommandAfterCurrentSync(target: WorkspaceCommandTarget, coordinator: WorkspaceSyncCompletionBarrier, reserve: () => void, options?: {
+    signal?: AbortSignal;
+}): Promise<void>;
 /**
  * Commands in visible checkouts behave like independent Git clients and may
  * overlap periodic synchronization. Canonical remediation commands mutate the

package/dist/types/workspace-filesystem-executor-thread.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/workspace-filesystem-executor.d.ts

@@ -0,0 +1,123 @@
+import { type WorkspaceFilesystemJobInput, type WorkspaceFilesystemJobKind, type WorkspaceFilesystemJobProgress, type WorkspaceFilesystemJobResult } from "./workspace-filesystem-job-types";
+/**
+ * Bounded executor for the worker's workspace filesystem transactions.
+ *
+ * One thread runs one job at a time; the control thread only ever awaits.
+ * The point is the incident this was written for: a single `pread64` or
+ * `pwrite64` blocked in the kernel on a stalled network disk used to freeze
+ * the worker's only event loop for minutes, so no heartbeat, cancel or Stop
+ * could run. On the executor thread that same blocked syscall stalls exactly
+ * one job while the control thread keeps serving the socket.
+ *
+ * A thread rather than a helper process because a thread cannot outlive the
+ * process: when the worker dies, its in-flight syscall completes and nothing
+ * else is written afterwards, which is the crash model every recovery path
+ * already handles. Nothing is ever abandoned: a running job's promise settles
+ * only with the thread's reply or the thread's exit, so the gate its caller
+ * holds is held for the job's true duration. Only jobs that have not started
+ * can fail on the queue-wait bound.
+ *
+ * A thread that exits while a job is running leaves an unknown partial
+ * mutation behind. The executor then fails closed: the job and everything
+ * queued fail, no further job is accepted, and `onFailure` lets the worker
+ * take its established restart path, whose startup recovery (manifests,
+ * receipts, snapshot recovery) runs before any ordinary mutation. No
+ * replacement thread is started over that state in this process.
+ */
+export declare const WORKSPACE_FILESYSTEM_EXECUTOR_MAX_QUEUED = 32;
+export declare const WORKSPACE_FILESYSTEM_EXECUTOR_QUEUE_TIMEOUT_MS: number;
+export declare const WORKSPACE_FILESYSTEM_EXECUTOR_STALL_LOG_INTERVAL_MS = 30000;
+export declare class WorkspaceFilesystemExecutorError extends Error {
+    readonly name = "WorkspaceFilesystemExecutorError";
+}
+/** The executor thread exited (crashed or was terminated) while a job was running. */
+export declare class WorkspaceFilesystemExecutorThreadExitedError extends WorkspaceFilesystemExecutorError {
+    readonly exitCode: number | null;
+    readonly description: string;
+    constructor(exitCode: number | null, description: string, cause?: unknown);
+}
+export type WorkspaceFilesystemExecutorStatus = {
+    running: {
+        kind: WorkspaceFilesystemJobKind;
+        description: string;
+        startedAtMs: number;
+        ageMs: number;
+    } | null;
+    queued: number;
+    /** Set once the thread exited under a running job; every job is then rejected until the worker restarts. */
+    failed: string | null;
+};
+export type WorkspaceFilesystemExecutorOptions = {
+    /** Module the thread executes; must resolve next to the packaged executor module. */
+    threadModulePath: string;
+    log?: (line: string) => void;
+    now?: () => number;
+    maxQueued?: number;
+    queueTimeoutMs?: number;
+    stallLogIntervalMs?: number;
+};
+export declare class WorkspaceFilesystemExecutor {
+    private readonly threadModulePath;
+    private readonly log;
+    private readonly now;
+    private readonly maxQueued;
+    private readonly queueTimeoutMs;
+    private readonly stallLogIntervalMs;
+    private worker;
+    private readonly queue;
+    private running;
+    private nextJobId;
+    private failed;
+    private closed;
+    /** Invoked once when the executor fails closed (thread exit under a running job). */
+    onFailure: ((error: WorkspaceFilesystemExecutorThreadExitedError) => void) | undefined;
+    constructor(options: WorkspaceFilesystemExecutorOptions);
+    /**
+     * Run one job to completion on the executor thread. Resolves with the
+     * job's result; rejects with the job's own error (properties preserved),
+     * with a queue-wait or capacity error when the job never started, or with
+     * WorkspaceFilesystemExecutorThreadExitedError when the thread died under it.
+     */
+    run<K extends WorkspaceFilesystemJobKind>(kind: K, input: WorkspaceFilesystemJobInput<K>, options?: {
+        onProgress?: (progress: WorkspaceFilesystemJobProgress) => void;
+    }): Promise<WorkspaceFilesystemJobResult<K>>;
+    status(): WorkspaceFilesystemExecutorStatus;
+    /**
+     * Stop accepting jobs, fail everything still queued and ask the thread to
+     * stop. A running job settles when the thread actually exits; a thread
+     * blocked in the kernel only exits with the process, which is the point.
+     */
+    close(): void;
+    private describeRunning;
+    private expireQueued;
+    private dispatch;
+    private settleRunning;
+    private ensureWorker;
+    private lastThreadError;
+    private onReply;
+    private onExit;
+}
+/** The packaged thread module lives next to this module with the same extension (.ts in source, .cjs/.mjs in the package). */
+export declare function workspaceFilesystemExecutorThreadModulePath(): string;
+/** What the engine modules dispatch through; the thread executor in production. */
+export type WorkspaceFilesystemJobRunner = Pick<WorkspaceFilesystemExecutor, "run">;
+/**
+ * The worker process's executor. Like the workspace mutation gate it is
+ * process-global: in-process reconnects share it, so a job started by a
+ * previous connection generation is still the one running when the next
+ * generation's configuration queues behind it.
+ */
+export declare function workspaceFilesystemExecutor(): WorkspaceFilesystemJobRunner;
+/** The worker runtime's fail-closed hook: installed once on the process executor (created if needed). */
+export declare function installWorkspaceFilesystemExecutorFailureHandler(handler: (error: WorkspaceFilesystemExecutorThreadExitedError) => void): void;
+/**
+ * Test seam. Engine tests that inject faults or count syscalls by replacing
+ * `node:fs` functions in their own thread cannot observe a body running on
+ * the executor thread; inside `runJobsInline` the same operation table runs
+ * on the calling thread instead. The boundary itself is tested with the real
+ * thread in workspace-filesystem-executor.test.ts. Never used in production.
+ */
+export declare const workspaceFilesystemExecutorTestHarness: {
+    runJobsInline<T>(body: () => Promise<T>): Promise<T>;
+    processExecutor(): WorkspaceFilesystemExecutor | null;
+};

package/dist/types/workspace-filesystem-job-types.d.ts

@@ -0,0 +1,246 @@
+import type { ProjectWorktreeBranch, ProjectWorktreeSnapshot, ProjectWorktreeSnapshotProgress, ProjectWorktreeSnapshotScope, ProjectWorktreeWorkingTreeMode } from "./project-worktrees";
+import type { WorkingTreeGitlink } from "./working-tree-mirror";
+import type { WorkspaceGitMountData, WorkspaceHydrationReceipt } from "./workspace-git-sync";
+import type { WorkspaceMergeProjectionMount, WorkspaceMergeProjectionResult } from "./workspace-merge-projection";
+import type { ProjectCheckoutPathMoveBranch } from "./workspace-path-move";
+/**
+ * The closed set of filesystem transactions the worker runs on its executor
+ * thread. Every input is plain data (paths, mount descriptors, receipts); the
+ * busy predicates, mutation tokens, hooks and gates that decide *whether* a
+ * job may run stay on the control thread. Every body is the synchronous code
+ * that used to run on the control thread, unchanged in its write and fsync
+ * ordering. A job kind outside this table is rejected by both threads.
+ */
+export type WorkspaceFilesystemJobTable = {
+    /** `recoverWorkspaceCheckoutDurability`: rebuild an interrupted outer checkout boundary. */
+    checkout_durability_recovery: {
+        input: {
+            workspacePath: string;
+            preserveResolutionInProgress: boolean;
+        };
+        result: null;
+    };
+    /** Checkout durability recovery, pending hydration transaction restore/completion, basis-ref repair. */
+    hydration_recovery: {
+        input: {
+            workspacePath: string;
+            preserveResolutionInProgress: boolean;
+        };
+        result: null;
+    };
+    /** The complete hydration transaction: snapshot, hydrate, fsync, commit marker, receipt; restore on failure. */
+    hydration_transaction: {
+        input: {
+            workspacePath: string;
+            hydrationMounts: WorkspaceGitMountData[];
+            advancedDurabilityMounts: WorkspaceGitMountData[];
+            targetReceipt: WorkspaceHydrationReceipt | null;
+        };
+        result: {
+            hydratedMountIds: string[];
+        };
+    };
+    /** Pre-clone hydration of visible mounts without a transaction (no outer Git directory yet). */
+    hydration_raw: {
+        input: {
+            workspacePath: string;
+            mounts: WorkspaceGitMountData[];
+        };
+        result: {
+            hydratedMountIds: string[];
+        };
+    };
+    /** Recover the durable checkout boundary and record the transition that follows. */
+    checkout_transition_begin: {
+        input: {
+            workspacePath: string;
+        };
+        result: null;
+    };
+    /** Make the outer checkout durable and record its head as the durable boundary. */
+    checkout_transition_complete: {
+        input: {
+            workspacePath: string;
+        };
+        result: null;
+    };
+    /** Durability barrier over the outer checkout tree without changing the record. */
+    outer_checkout_fsync: {
+        input: {
+            workspacePath: string;
+        };
+        result: null;
+    };
+    /** Three-way merge projection of one stale mount (ours snapshot + merge-tree). */
+    projection_merge: {
+        input: {
+            workspacePath: string;
+            mount: WorkspaceMergeProjectionMount;
+            basisHead: string;
+            currentHead: string;
+            attemptId: string;
+        };
+        result: WorkspaceMergeProjectionResult;
+    };
+    /** Byte mirror of one visible mount into the outer checkout. */
+    projection_mirror: {
+        input: {
+            workspacePath: string;
+            mount: WorkspaceGitMountData;
+        };
+        result: {
+            gitlinks: WorkingTreeGitlink[];
+        };
+    };
+    /** Outer-tree edits after the mirrors: tombstone removal, merged subtree materialization, deferred restores. */
+    projection_outer_apply: {
+        input: {
+            workspacePath: string;
+            removeMounts: WorkspaceGitMountData[];
+            materialize: Array<{
+                workspaceRelativePath: string;
+                resultTree: string;
+            }>;
+            restoreFromHead: WorkspaceGitMountData[];
+        };
+        result: null;
+    };
+    /** Persist projected visible mounts and publish the projection receipt. */
+    projection_receipt: {
+        input: {
+            workspacePath: string;
+            fsyncMounts: WorkspaceGitMountData[];
+            receipt: WorkspaceHydrationReceipt;
+        };
+        result: null;
+    };
+    /** `snapshotBranchTrees`: copy every checkout a reconciliation may rewrite. */
+    project_snapshot_create: {
+        input: {
+            projectRoot: string;
+            branches: ProjectWorktreeBranch[];
+            temporaryRoot: string;
+            scope: ProjectWorktreeSnapshotScope;
+            ownerSessionId: string;
+        };
+        result: ProjectWorktreeSnapshot;
+    };
+    /** Mirror captured checkouts back over the reconciled worktrees. */
+    project_snapshot_apply: {
+        input: {
+            mirrors: Array<{
+                snapshotPath: string;
+                targetPath: string;
+            }>;
+        };
+        result: null;
+    };
+    /** `persistReconciledProjectAndConsumeSnapshot`. */
+    project_snapshot_persist: {
+        input: {
+            snapshot: ProjectWorktreeSnapshot;
+            durabilityPaths: string[] | null;
+        };
+        result: null;
+    };
+    /** `rollbackProjectWorktreeSnapshot`. */
+    project_snapshot_rollback: {
+        input: {
+            snapshot: ProjectWorktreeSnapshot;
+        };
+        result: null;
+    };
+    /** `recoverStaleProjectWorktreeSnapshots` at startup. */
+    project_snapshots_recover: {
+        input: {
+            projectsRoot: string;
+            temporaryRoot: string;
+            currentProcessId: number;
+            currentOwnerSessionId: string;
+        };
+        result: {
+            restored: string[];
+            removed: string[];
+            failed: Array<{
+                path: string;
+                error: string;
+            }>;
+        };
+    };
+    /** `createLinkedProjectBranch`: branch ref, linked worktree, index seed and working-tree copy. */
+    project_branch_create: {
+        input: {
+            projectRoot: string;
+            sourceBranchName: string;
+            branchName: string;
+            workingTree: ProjectWorktreeWorkingTreeMode;
+        };
+        result: {
+            branchPath: string;
+            baseCommitHash: string;
+        };
+    };
+    /** `preserveProjectCheckoutPathMove`. */
+    project_checkout_path_move: {
+        input: {
+            oldProjectRoot: string;
+            newProjectRoot: string;
+            projectsDurabilityRoot: string;
+            outerWorkspaceRoot: string;
+            branches: ProjectCheckoutPathMoveBranch[];
+        };
+        result: {
+            preservedBranchNames: string[];
+        };
+    };
+};
+export type WorkspaceFilesystemJobKind = keyof WorkspaceFilesystemJobTable;
+export type WorkspaceFilesystemJobInput<K extends WorkspaceFilesystemJobKind> = WorkspaceFilesystemJobTable[K]["input"];
+export type WorkspaceFilesystemJobResult<K extends WorkspaceFilesystemJobKind> = WorkspaceFilesystemJobTable[K]["result"];
+export type WorkspaceFilesystemJobProgress = ProjectWorktreeSnapshotProgress;
+export type WorkspaceFilesystemJobContext = {
+    progress: (progress: WorkspaceFilesystemJobProgress) => void;
+};
+export type WorkspaceFilesystemJobOperations = {
+    [K in WorkspaceFilesystemJobKind]: (input: WorkspaceFilesystemJobInput<K>, context: WorkspaceFilesystemJobContext) => WorkspaceFilesystemJobResult<K>;
+};
+export declare const WORKSPACE_FILESYSTEM_JOB_KINDS: readonly WorkspaceFilesystemJobKind[];
+export declare function isWorkspaceFilesystemJobKind(value: unknown): value is WorkspaceFilesystemJobKind;
+/** Short, path-bearing description used in stall diagnostics and errors. */
+export declare function describeWorkspaceFilesystemJob<K extends WorkspaceFilesystemJobKind>(kind: K, input: WorkspaceFilesystemJobInput<K>): string;
+/** Errors cross the thread boundary as data; the properties callers inspect are preserved. */
+export type WorkspaceFilesystemSerializedError = {
+    name: string;
+    message: string;
+    stack?: string;
+    code?: string;
+    branchMayExist?: true;
+    cleanupFailures?: string[];
+    errors?: WorkspaceFilesystemSerializedError[];
+    cause?: WorkspaceFilesystemSerializedError;
+};
+export declare function serializeWorkspaceFilesystemError(error: unknown, depth?: number): WorkspaceFilesystemSerializedError;
+export declare function restoreWorkspaceFilesystemError(serialized: WorkspaceFilesystemSerializedError): Error;
+/** Control thread → executor thread. */
+export type WorkspaceFilesystemThreadRequest = {
+    type: "run";
+    id: number;
+    kind: WorkspaceFilesystemJobKind;
+    input: unknown;
+    /** The control thread's environment at dispatch; the thread runs the job under exactly this. */
+    environment: Record<string, string>;
+};
+/** Executor thread → control thread. */
+export type WorkspaceFilesystemThreadReply = {
+    type: "progress";
+    id: number;
+    progress: WorkspaceFilesystemJobProgress;
+} | {
+    type: "result";
+    id: number;
+    result: unknown;
+} | {
+    type: "failure";
+    id: number;
+    error: WorkspaceFilesystemSerializedError;
+};

package/dist/types/workspace-filesystem-jobs.d.ts

@@ -0,0 +1,7 @@
+import type { WorkspaceFilesystemJobOperations } from "./workspace-filesystem-job-types";
+/**
+ * The operation table of the workspace filesystem executor thread. It is the
+ * only thing the thread can run; every entry is an existing synchronous
+ * transaction body. Imported by the thread entry module only.
+ */
+export declare const workspaceFilesystemJobOperations: WorkspaceFilesystemJobOperations;

package/dist/types/workspace-git-sync.d.ts

@@ -5,6 +5,27 @@ export declare const WORKSPACE_GIT_CONFIRMED_LARGE_DIFF_PUSH_OPTION = "r5d-confi
 export declare const WORKSPACE_GIT_HYDRATED_RECEIPT = "r5d/workspace-hydrated-head";
 export declare const WORKSPACE_GIT_HYDRATION_TRANSACTION = "r5d/workspace-hydration-transaction";
 export declare const WORKSPACE_GIT_CHECKOUT_DURABILITY = "r5d/workspace-checkout-durability";
+type WorkspaceHydrationMountBasis = {
+    id: string;
+    incarnationKey: string;
+    sourcePath: string;
+    durabilityRootPath: string;
+    workspaceRelativePath: string;
+    sourceMode: WorkingTreeSourceMode;
+    hydrateDeletionMode: "all" | "git";
+    preserveLocalOnInitialOuterAbsence: boolean;
+    preserveLocalOnHydrationBasisChange: boolean;
+    deleteWhenSourceMissing: boolean;
+};
+type WorkspaceHydrationMountReceipt = WorkspaceHydrationMountBasis & {
+    head: string;
+};
+export type WorkspaceHydrationReceipt = {
+    version: 3;
+    mounts: WorkspaceHydrationMountReceipt[];
+    /** Non-enumerable read-compat marker used only to finish a v1/v2 crash transition. */
+    legacyHead?: string;
+};
 export type WorkspaceGitMount = {
     id: string;
     /** Durable logical incarnation (for example the project-branch row id). */
@@ -49,6 +70,15 @@ export type WorkspaceGitMount = {
     /** Activity-only fence used before checkout readiness is established on reconnect. */
     busyForRecovery?: () => boolean;
 };
+/**
+ * The data of a mount, without its control-thread predicates. This is what a
+ * workspace filesystem job receives: a job never evaluates `busy()` or
+ * `mutationToken()`; the control thread evaluated them before dispatch and
+ * holds the mount (see WorkspaceHydrationTransactionHooks.holdMounts) until
+ * the job ends.
+ */
+export type WorkspaceGitMountData = Pick<WorkspaceGitMount, "id" | "hydrationIncarnationKey" | "sourcePath" | "durabilityRootPath" | "workspaceRelativePath" | "sourceMode" | "hydrateDeletionMode" | "preserveLocalOnInitialOuterAbsence" | "preserveLocalOnHydrationBasisChange" | "initialPublicationSourceRelativePath" | "deleteWhenSourceMissing" | "lastProjectedMutationToken">;
+export declare function workspaceGitMountData(mount: WorkspaceGitMount): WorkspaceGitMountData;
 /**
  * Incident-bound configuration keeps project checkouts unready while the
  * canonical remediation owns the workspace. The guarded remediation sync is
@@ -65,17 +95,23 @@ export type WorkspaceHydrationTransactionContext = {
     mountIds: string[];
 };
 /**
- * Observes the synchronous body of a hydration transaction (snapshot,
- * hydration pass, durability barrier, receipt). That body deliberately never
- * yields, so the worker cannot answer control-socket messages while it runs,
- * and on a slow disk it can run for hours. `beforeTransaction` is awaited
- * after the last asynchronous precheck and before the final busy observation,
- * so it may announce the operation and yield once; `afterTransaction` runs
- * after the body committed or rolled back.
+ * Observes a hydration transaction (snapshot, hydration pass, durability
+ * barrier, receipt) and fences the mounts any workspace filesystem job reads
+ * or writes. The body runs on the executor thread and on a stalled disk it
+ * can run for a long time. `beforeTransaction` is awaited after the last
+ * asynchronous precheck and before the final busy observation, so it may
+ * announce the operation and yield once; `afterTransaction` runs after the
+ * body committed or rolled back. `holdMounts` is called synchronously right
+ * after the busy observation that selected the mounts, before the job is
+ * dispatched, and its release is called when the job's result or failure
+ * arrived: while held, command admission for those mounts waits (see
+ * WorkspaceMountHoldFence), which replaces the guarantee the un-yielding body
+ * used to give.
  */
 export type WorkspaceHydrationTransactionHooks = {
     beforeTransaction: (context: WorkspaceHydrationTransactionContext) => Promise<void> | void;
     afterTransaction: (context: WorkspaceHydrationTransactionContext) => void;
+    holdMounts: (mountIds: readonly string[], description: string) => () => void;
 };
 export type WorkspaceGitSyncOutcome = "no_change" | "updated" | "pushed" | "large_diff_blocked" | "conflict_blocked";
 export type WorkspaceGitSyncResult = {
@@ -126,6 +162,23 @@ export declare function workspaceGitHydrationIsCurrent(workspacePath: string, mo
  * Configuration-time recovery keeps the strict predicate.
  */
 export declare function workspaceGitHydrationIsRecoverable(workspacePath: string, mounts?: readonly WorkspaceGitMount[]): boolean;
+/** Executor job body: recover the durable boundary, then record the transition that follows. */
+export declare function runCheckoutTransitionBeginJob(input: {
+    workspacePath: string;
+}): null;
+/** Executor job body: make the outer checkout durable and record its head as the durable boundary. */
+export declare function runCheckoutTransitionCompleteJob(input: {
+    workspacePath: string;
+}): null;
+/** Executor job body: `recoverWorkspaceCheckoutDurability`. */
+export declare function runCheckoutDurabilityRecoveryJob(input: {
+    workspacePath: string;
+    preserveResolutionInProgress: boolean;
+}): null;
+/** Executor job body: the outer-tree durability barrier alone. */
+export declare function runOuterCheckoutFsyncJob(input: {
+    workspacePath: string;
+}): null;
 declare function configureWorkspaceRepository(input: {
     workspacePath: string;
     remoteUrl: string;
@@ -179,6 +232,36 @@ type ProjectedMountGitlinks = {
  * `stageWorkspaceGitlinks` before `git add -A`, which can never create one.
  */
 declare function mirrorMountsToWorkspace(workspacePath: string, mounts: readonly WorkspaceGitMount[]): ProjectedMountGitlinks[];
+/**
+ * Executor job body: the complete hydration transaction. Snapshot exactly
+ * what hydration replaces, hydrate, cross the durability barrier, write the
+ * commit marker, publish the receipt, remove the transaction; on failure
+ * restore the snapshot unless the visible tree is already durable. The write
+ * and fsync ordering is the one the control thread used to run inline.
+ */
+export declare function runHydrationTransactionJob(input: {
+    workspacePath: string;
+    hydrationMounts: readonly WorkspaceGitMountData[];
+    advancedDurabilityMounts: readonly WorkspaceGitMountData[];
+    targetReceipt: WorkspaceHydrationReceipt | null;
+}): {
+    hydratedMountIds: string[];
+};
+/** Executor job body: hydrate visible mounts before an outer clone exists (no transaction to record). */
+export declare function runHydrationRawJob(input: {
+    workspacePath: string;
+    mounts: readonly WorkspaceGitMountData[];
+}): {
+    hydratedMountIds: string[];
+};
+/**
+ * Executor job body: checkout durability recovery, pending hydration
+ * transaction restore or completion, and basis-ref repair, in that order.
+ */
+export declare function runHydrationRecoveryJob(input: {
+    workspacePath: string;
+    preserveResolutionInProgress: boolean;
+}): null;
 export declare function hydrateWorkspaceGitMounts(workspacePath: string, mounts: readonly WorkspaceGitMount[], options?: {
     ignoreBusy?: boolean;
     hydrationHooks?: WorkspaceHydrationTransactionHooks;
@@ -257,6 +340,29 @@ export type SynchronizeWorkspaceGitInput = {
     hydrationHooks?: WorkspaceHydrationTransactionHooks;
 };
 export declare function synchronizeWorkspaceGit(input: SynchronizeWorkspaceGitInput): Promise<WorkspaceGitSyncResult>;
+/** Executor job body: byte-mirror one visible mount into the outer checkout. */
+export declare function runProjectionMirrorJob(input: {
+    workspacePath: string;
+    mount: WorkspaceGitMountData;
+}): {
+    gitlinks: WorkingTreeGitlink[];
+};
+/** Executor job body: outer-tree edits that follow the mirrors, in the cycle's order. */
+export declare function runProjectionOuterApplyJob(input: {
+    workspacePath: string;
+    removeMounts: readonly WorkspaceGitMountData[];
+    materialize: ReadonlyArray<{
+        workspaceRelativePath: string;
+        resultTree: string;
+    }>;
+    restoreFromHead: readonly WorkspaceGitMountData[];
+}): null;
+/** Executor job body: persist projected visible mounts, then publish the projection receipt. */
+export declare function runProjectionReceiptJob(input: {
+    workspacePath: string;
+    fsyncMounts: readonly WorkspaceGitMountData[];
+    receipt: WorkspaceHydrationReceipt;
+}): null;
 export declare const workspaceGitSyncTestHarness: {
     commandArgs: typeof gitCommandArgs;
     workspaceCloneCommandArgs: typeof workspaceCloneCommandArgs;

package/dist/types/workspace-mount-hold-fence.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Tracks the mounts whose bytes a workspace filesystem job is reading or
+ * writing on the executor thread. The sync engine takes a hold immediately
+ * after the busy observation that selected a mount, in the same synchronous
+ * stretch, and releases it when the job's result or failure arrives. Command
+ * admission waits on the fence before reserving a mount, so no tracked
+ * process, PTY or file operation can start in a mount while a job owns it,
+ * and no job can start on a mount a command already reserved (that mount was
+ * busy at the observation). Holds are counted per mount; overlapping holds
+ * (a recovery pass and a projection of the same mount cannot overlap under the
+ * mutation gate, but counting keeps the fence correct regardless) release in
+ * any order.
+ */
+export type WorkspaceMountHoldRelease = () => void;
+export declare class WorkspaceMountHoldAbortedError extends Error {
+    constructor(reason: string);
+}
+export declare class WorkspaceMountHoldFence {
+    private readonly holds;
+    private readonly waiters;
+    private readonly now;
+    constructor(options?: {
+        now?: () => number;
+    });
+    /** Take one hold on every listed mount; the returned release is idempotent. */
+    hold(mountIds: readonly string[], description: string): WorkspaceMountHoldRelease;
+    isHeld(mountIds: readonly string[]): boolean;
+    /** Human-readable holder of the first held mount among `mountIds`, for diagnostics. */
+    describeHold(mountIds: readonly string[]): string | null;
+    /** Every held mount id, sorted, for status reporting. */
+    heldMountIds(): string[];
+    /**
+     * Resolves in the same turn as the release that leaves none of `mountIds`
+     * held, so the caller can re-check and reserve without an interleaving
+     * hold. Resolves immediately when nothing is held. Rejects with
+     * WorkspaceMountHoldAbortedError when `signal` aborts first.
+     */
+    waitForRelease(mountIds: readonly string[], options?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+    private wake;
+}