@ricsam/r5d-worker 0.0.122 → 0.0.124

package/dist/mjs/workspace-mount-hold-fence.mjs

@@ -0,0 +1,95 @@
+class WorkspaceMountHoldAbortedError extends Error {
+  constructor(reason) {
+    super(reason);
+    this.name = "WorkspaceMountHoldAbortedError";
+  }
+}
+class WorkspaceMountHoldFence {
+  holds = /* @__PURE__ */ new Map();
+  waiters = /* @__PURE__ */ new Set();
+  now;
+  constructor(options = {}) {
+    this.now = options.now ?? (() => Date.now());
+  }
+  /** Take one hold on every listed mount; the returned release is idempotent. */
+  hold(mountIds, description) {
+    const ids = [...new Set(mountIds)];
+    for (const id of ids) {
+      const existing = this.holds.get(id);
+      if (existing) {
+        existing.count += 1;
+        continue;
+      }
+      this.holds.set(id, { count: 1, description, sinceMs: this.now() });
+    }
+    let released = false;
+    return () => {
+      if (released) return;
+      released = true;
+      for (const id of ids) {
+        const existing = this.holds.get(id);
+        if (!existing) continue;
+        existing.count -= 1;
+        if (existing.count === 0) this.holds.delete(id);
+      }
+      this.wake();
+    };
+  }
+  isHeld(mountIds) {
+    return mountIds.some((id) => this.holds.has(id));
+  }
+  /** Human-readable holder of the first held mount among `mountIds`, for diagnostics. */
+  describeHold(mountIds) {
+    for (const id of mountIds) {
+      const hold = this.holds.get(id);
+      if (hold) return `${hold.description} (held for ${Math.round((this.now() - hold.sinceMs) / 1e3)}s)`;
+    }
+    return null;
+  }
+  /** Every held mount id, sorted, for status reporting. */
+  heldMountIds() {
+    return [...this.holds.keys()].sort();
+  }
+  /**
+   * 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, options = {}) {
+    if (options.signal?.aborted) {
+      return Promise.reject(new WorkspaceMountHoldAbortedError(abortReason(options.signal)));
+    }
+    if (!this.isHeld(mountIds)) return Promise.resolve();
+    return new Promise((resolve, reject) => {
+      const waiter = { mountIds, resolve, reject, signal: options.signal };
+      if (options.signal) {
+        const signal = options.signal;
+        waiter.onAbort = () => {
+          this.waiters.delete(waiter);
+          reject(new WorkspaceMountHoldAbortedError(abortReason(signal)));
+        };
+        signal.addEventListener("abort", waiter.onAbort, { once: true });
+      }
+      this.waiters.add(waiter);
+    });
+  }
+  wake() {
+    for (const waiter of [...this.waiters]) {
+      if (this.isHeld(waiter.mountIds)) continue;
+      this.waiters.delete(waiter);
+      if (waiter.signal && waiter.onAbort) waiter.signal.removeEventListener("abort", waiter.onAbort);
+      waiter.resolve();
+    }
+  }
+}
+function abortReason(signal) {
+  const reason = signal.reason;
+  if (reason instanceof Error) return reason.message;
+  if (typeof reason === "string" && reason) return reason;
+  return "Workspace mount reservation was aborted";
+}
+export {
+  WorkspaceMountHoldAbortedError,
+  WorkspaceMountHoldFence
+};

package/dist/types/command-launcher.d.ts

@@ -2,9 +2,42 @@ export type CommandLaunchRequest = {
     id: string;
     kind: "exec" | "exec_start" | "pty_open";
     workspaceEffect?: "none";
+    /** An explicitly classified short coordination command; the launcher keeps a bounded lane for these. */
+    commandClass?: "control";
     sessionId?: string;
     assertAdmission: () => void;
 };
+export type CommandLaunchLane = "general" | "utility" | "control";
+export type CommandLaunchCapacity = {
+    generalSlots: number;
+    utilitySlots: number;
+    controlSlots: number;
+    controlRuntimeMs: number;
+    queueTimeoutMs: number;
+};
+export type CommandLaunchLaneReport = {
+    /** Null when no launcher bounds this lane (direct execution). */
+    slots: number | null;
+    active: Array<{
+        id: string;
+        sessionId?: string;
+        since: string;
+    }>;
+    queued: Array<{
+        id: string;
+        sessionId?: string;
+        since: string;
+    }>;
+};
+/** Who holds and who waits for each lane, as the worker sees its own admissions. */
+export type CommandLaunchCapacityReport = {
+    /** False for a direct worker: nothing is bounded and nothing can be starved. */
+    bounded: boolean;
+    controlRuntimeMs: number | null;
+    lanes: Record<CommandLaunchLane, CommandLaunchLaneReport>;
+};
+/** The same lane rule the managed launcher applies; kept here so reports match admissions. */
+export declare function commandLaunchLane(request: Pick<CommandLaunchRequest, "kind" | "workspaceEffect" | "commandClass">): CommandLaunchLane;
 export type CommandLaunchLease = {
     wrap(argv: string[]): string[];
     cancel(): Promise<void>;
@@ -33,6 +66,7 @@ export declare class WorkerCommandLauncher {
     private initialized;
     private closePromise?;
     private sequence;
+    private capacity?;
     constructor(options?: {
         argv?: string[];
         env?: NodeJS.ProcessEnv;
@@ -40,9 +74,17 @@ export declare class WorkerCommandLauncher {
         onStderr?: (text: string) => void;
         requestTimeoutMs?: number;
         acquisitionTimeoutMs?: number;
+        /** Called after any admission changes lane, phase, or is released. */
+        onCapacityChange?: () => void;
     });
     initialize(): Promise<void>;
     get activeIds(): string[];
+    /** The lane totals the launcher declared at initialization; undefined for a direct worker or an older launcher. */
+    get declaredCapacity(): CommandLaunchCapacity | undefined;
+    get supportsControlLane(): boolean;
+    /** Current admissions per lane, for the worker's capacity report. */
+    capacityReport(): CommandLaunchCapacityReport;
+    private notifyCapacityChange;
     acquire(request: CommandLaunchRequest): Promise<CommandLaunchLease>;
     cancel(id: string): Promise<void>;
     cancelSession(sessionId: string): Promise<void>;

package/dist/types/control-command-policy.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Which agent shell invocations may run in the managed launcher's bounded
+ * `control` lane: exactly one plain `r5dctl` coordination/diagnosis command.
+ *
+ * The lane exists so an agent can inspect capacity, message another session,
+ * or stop its own runs while every general slot is held by long work
+ * (incident 9). It is bounded (small memory, few PIDs, a runtime limit), so
+ * only commands that are short HTTP calls to the platform qualify. The
+ * classifier fails closed: anything the shell would interpret (operators,
+ * substitutions, expansions, quoting the tokenizer cannot prove literal,
+ * environment assignments, wrapper programs, paths) is refused and keeps its
+ * ordinary general-lane shell semantics. The resulting argv is validated a
+ * second time by the worker before it is spawned without a shell.
+ */
+export declare const CONTROL_COMMAND_PROGRAM = "r5dctl";
+/** Worker-side runtime bound for a control run; the launcher enforces its own limit as a backstop. */
+export declare const CONTROL_COMMAND_RUNTIME_MS = 120000;
+export declare const CONTROL_COMMAND_MAX_ARGV = 64;
+export declare const CONTROL_COMMAND_MAX_LENGTH = 4096;
+export type ControlCommandClassification = {
+    control: true;
+    argv: string[];
+} | {
+    control: false;
+    reason: string;
+};
+/**
+ * Validate an argv as an allowed r5dctl coordination invocation. Used on the
+ * server after tokenizing, and again on the worker before spawning.
+ */
+export declare function assertControlCommandArgv(argv: readonly string[]): void;
+/**
+ * Locate the installed CLI through the worker's own, operator-controlled
+ * search path. The command's cwd, its environment, and any checkout-local
+ * shim play no part, so a project cannot substitute the executable the
+ * reserved lane runs.
+ */
+export declare function resolveControlCommandExecutable(trustedPath: string | undefined, which: (program: string, options: {
+    PATH: string;
+}) => string | null, program?: string): string;
+/**
+ * The environment a control spawn receives: everything the platform sets for
+ * the run (credentials, session identity, declared project values) minus any
+ * variable that could load code into the CLI process or redirect which
+ * executable runs, with the worker's own PATH restored.
+ */
+export declare function controlCommandEnvironment(environment: NodeJS.ProcessEnv, trustedPath: string | undefined): Record<string, string>;
+/**
+ * Classify an agent shell command. Only a plain `r5dctl` coordination
+ * invocation becomes a control command; the returned argv is spawned without a
+ * shell. Everything else keeps its ordinary shell semantics and lane.
+ */
+export declare function classifyControlCommand(command: string): ControlCommandClassification;

package/dist/types/main.d.ts

@@ -4,6 +4,7 @@ import { WORKER_RESUMABLE_PROTOCOL, type WorkerRecoveryClientMessage, type Worke
 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";
 type WorkerProjectConfig = {
     projectId: string;
@@ -48,19 +49,22 @@ declare function workerServerHeartbeatAction(input: {
     watchdogSweepDelayed: boolean;
 }): "wait" | "start_probe" | "terminate";
 /**
- * A hydration transaction blocks this event loop until it ends, so no pong,
- * progress, or result can leave the process while it runs; on a slow disk
- * that is hours. Declare a hydration heartbeat lease first: the server keeps
- * the control socket open and defers the affected request deadlines while the
- * lease is active instead of reading the silence as a dead worker, which is
- * what turned one slow hydration into a mandatory canonical reset (incident
- * 3bccab03). Bun writes the frame to the socket synchronously; the extra
- * event-loop turn lets control messages that were already queued run before
- * the busy observation that precedes the transaction body.
+ * A hydration transaction runs on the workspace filesystem executor thread
+ * and on a stalled disk it can run for a long time; the server bounds its
+ * deadlines by a hydration heartbeat lease rather than by the ordinary
+ * request timeout. Declare that lease first: the server keeps the control
+ * socket open and defers the affected request deadlines while the lease is
+ * active, which is what turned one slow hydration into a mandatory canonical
+ * reset before the lease existed (incident 3bccab03). The extra event-loop
+ * turn lets control messages that were already queued run before the busy
+ * observation that precedes the transaction. The hooks also hold every mount
+ * a job reads or writes on the process-wide fence, so command admission for
+ * those mounts waits until the job ended (incident 10).
  */
 declare function createWorkspaceHydrationLeaseHooks(send: (message: Extract<WorkerClientMessage, {
     type: "heartbeat_lease";
-}>) => void, options?: {
+}>) => void, options: {
+    fence: WorkspaceMountHoldFence;
     yieldToEventLoop?: () => Promise<void>;
     log?: (line: string) => void;
     now?: () => number;
@@ -69,6 +73,7 @@ export declare const workerLifecycleTestHarness: {
     boundedWorkerLifecycleProgress: typeof boundedWorkerLifecycleProgress;
     workerServerHeartbeatAction: typeof workerServerHeartbeatAction;
     createWorkspaceHydrationLeaseHooks: typeof createWorkspaceHydrationLeaseHooks;
+    workerCommandHasWorkspaceEffect: typeof workerCommandHasWorkspaceEffect;
 };
 type WorkspaceSyncTrigger = {
     type: "connect" | "inbound_head" | "write" | "edit" | "shell_inline" | "process_terminal" | "process_cancel" | "periodic" | "manual" | "remediation" | "remediation_confirm" | "remediation_reset";
@@ -137,6 +142,11 @@ export type WorkerSessionTarget = {
     rootProfile: "visible_projects" | "canonical_sync";
 };
 type WorkerClientMessage = WorkerRecoveryClientMessage | {
+    type: "capacity_report";
+    capacity: import("./command-launcher").CommandLaunchCapacityReport & {
+        reportedAt: string;
+    };
+} | {
     type: "hello";
     resumableProtocol: typeof WORKER_RESUMABLE_PROTOCOL;
     runtimeId: string;
@@ -172,6 +182,7 @@ type WorkerClientMessage = WorkerRecoveryClientMessage | {
         startedAt: string;
         interactive?: boolean;
         workspaceEffect?: "none";
+        commandClass?: "control";
     }>;
 } | {
     type: "pty_opened";
@@ -397,6 +408,7 @@ type WorkerServerMessage = WorkerRecoveryServerMessage | {
     timeoutMs?: number;
     interactive?: boolean;
     workspaceEffect?: "none";
+    commandClass?: "control";
 } | {
     type: "exec_stdin";
     requestId: string;
@@ -1010,12 +1022,12 @@ export declare function prepareBuiltInToolPathsForTarget(input: {
     rootDir: string;
     access: "read" | "write";
 }): Promise<WorkerBuiltInToolPaths | undefined>;
-export declare function readWorkerTextFile(branchPath: string, filePath: string, offset?: number, limit?: number, builtInPaths?: WorkerBuiltInToolPaths): WorkerReadFileResult;
-export declare function writeWorkerTextFile(branchPath: string, filePath: string, content: string, builtInPaths?: WorkerBuiltInToolPaths): WorkerWriteFileResult;
+export declare function readWorkerTextFile(branchPath: string, filePath: string, offset?: number, limit?: number, builtInPaths?: WorkerBuiltInToolPaths): Promise<WorkerReadFileResult>;
+export declare function writeWorkerTextFile(branchPath: string, filePath: string, content: string, builtInPaths?: WorkerBuiltInToolPaths): Promise<WorkerWriteFileResult>;
 export declare function editWorkerTextFile(branchPath: string, filePath: string, edits: Array<{
     oldText: string;
     newText: string;
-}>, builtInPaths?: WorkerBuiltInToolPaths): WorkerEditFileResult;
+}>, builtInPaths?: WorkerBuiltInToolPaths): Promise<WorkerEditFileResult>;
 declare function executeWriteFileOperation(input: {
     message: Extract<WorkerServerMessage, {
         type: "write";
@@ -1042,17 +1054,17 @@ export declare function grepWorkerFiles(branchPath: string, input: {
     glob?: string;
     caseSensitive?: boolean;
     limit?: number;
-}, builtInPaths?: WorkerBuiltInToolPaths): WorkerGrepResult;
+}, builtInPaths?: WorkerBuiltInToolPaths): Promise<WorkerGrepResult>;
 export declare function findWorkerFiles(branchPath: string, input: {
     pattern?: string;
     path?: string;
     entryType?: string;
     limit?: number;
-}, builtInPaths?: WorkerBuiltInToolPaths): WorkerFindResult;
-export declare function listWorkerDirectory(branchPath: string, inputPath?: string, inputLimit?: number, builtInPaths?: WorkerBuiltInToolPaths): WorkerLsResult;
-export declare function listWorkerCodeDirectory(branchPath: string, inputPath: string): WorkerCodeListResult;
-export declare function readWorkerCodeFile(branchPath: string, inputPath: string): WorkerCodeReadResult;
-export declare function readWorkerImageFile(branchPath: string, filePath: string, builtInPaths?: WorkerBuiltInToolPaths): WorkerViewFileBytesResult;
+}, builtInPaths?: WorkerBuiltInToolPaths): Promise<WorkerFindResult>;
+export declare function listWorkerDirectory(branchPath: string, inputPath?: string, inputLimit?: number, builtInPaths?: WorkerBuiltInToolPaths): Promise<WorkerLsResult>;
+export declare function listWorkerCodeDirectory(branchPath: string, inputPath: string): Promise<WorkerCodeListResult>;
+export declare function readWorkerCodeFile(branchPath: string, inputPath: string): Promise<WorkerCodeReadResult>;
+export declare function readWorkerImageFile(branchPath: string, filePath: string, builtInPaths?: WorkerBuiltInToolPaths): Promise<WorkerViewFileBytesResult>;
 declare function executeOperation(input: {
     message: WorkerOperationServerMessage;
     resolvedTarget: ResolvedWorkerSessionTarget;

package/dist/types/project-checkout-garbage.d.ts

@@ -18,7 +18,20 @@ export declare const PROJECT_DELETED_CHECKOUTS_DIRECTORY = ".r5d-deleted";
  * later collection walk through it, so staging refuses rather than continue.
  */
 export declare function stageProjectCheckoutForDeletion(projectRoot: string, branchName: string, checkoutPath: string): string;
-/** True when `candidate` is lexically a direct entry of some project's garbage directory under `projectsRoot`. */
+/**
+ * Rename a whole project root out of the active namespace, into the
+ * namespace's garbage directory, so removing a deleted project never walks
+ * its checkouts on the worker event loop. Same guarantees as
+ * stageProjectCheckoutForDeletion: one same-filesystem rename, a real garbage
+ * directory, collection by the garbage collector later.
+ */
+export declare function stageProjectForDeletion(projectsRoot: string, projectRoot: string): string;
+/**
+ * True when `candidate` is lexically a direct entry of a project's garbage
+ * directory (`<namespace>/<project>/.r5d-deleted/<entry>`, a staged checkout)
+ * or of a namespace's garbage directory (`<namespace>/.r5d-deleted/<entry>`,
+ * a staged whole project) under `projectsRoot`.
+ */
 export declare function isStagedProjectCheckoutPath(projectsRoot: string, candidate: string): boolean;
 /**
  * Whether a lexically staged path is safe to remove right now: every ancestor
@@ -30,7 +43,11 @@ export declare function isStagedProjectCheckoutPath(projectsRoot: string, candid
 export declare function ownedStagedPath(projectsRoot: string, candidate: string): {
     kind: "directory" | "link";
 } | null;
-/** Every owned staged checkout under `<projectsRoot>/<namespace>/<project>/.r5d-deleted/`; linked ancestors are not followed. */
+/**
+ * Every owned staged checkout under `<projectsRoot>/<namespace>/<project>/.r5d-deleted/`
+ * and every owned staged project under `<projectsRoot>/<namespace>/.r5d-deleted/`;
+ * linked ancestors are not followed.
+ */
 export declare function discoverStagedProjectCheckouts(projectsRoot: string): string[];
 /**
  * Delete a staged tree in a child process so a large recursive removal never

package/dist/types/project-workspace-state.d.ts

@@ -160,29 +160,29 @@ export declare class ProjectWorkspaceStateStore {
         desiredProjects: readonly ProjectWorkspaceDesiredProjectInput[];
         locallyPendingCreatedBranches?: readonly LocallyPendingCreatedProjectBranch[];
         preserveOnlyBranches?: readonly PreserveOnlyProjectBranch[];
-    }): ProjectWorkspaceStateView;
+    }): Promise<ProjectWorkspaceStateView>;
     /** Record a successful enabled reseed without letting disabled config consume it. */
-    recordEnabledRepositoryTransition(input: EnabledRepositoryTransition): ProjectWorkspaceStateView;
+    recordEnabledRepositoryTransition(input: EnabledRepositoryTransition): Promise<ProjectWorkspaceStateView>;
     /** Persist the create intent before invoking Git so a crash cannot orphan an untracked worktree. */
     recordPendingCreatedBranch(input: LocallyPendingCreatedProjectBranch & {
         branchId: string;
-    }): ProjectWorkspaceStateView;
+    }): Promise<ProjectWorkspaceStateView>;
     /** Roll back an intent only when Git failed before creating its branch. */
-    rollbackPendingCreatedBranch(input: LocallyPendingCreatedProjectBranch): ProjectWorkspaceStateView;
+    rollbackPendingCreatedBranch(input: LocallyPendingCreatedProjectBranch): Promise<ProjectWorkspaceStateView>;
     /** Clear a create intent after an authoritative desired config contains it. */
-    clearPendingCreatedBranch(input: LocallyPendingCreatedProjectBranch): ProjectWorkspaceStateView;
+    clearPendingCreatedBranch(input: LocallyPendingCreatedProjectBranch): Promise<ProjectWorkspaceStateView>;
     /** Persist a branch tombstone before mutating its linked worktree or local ref. */
-    beginBranchDeletion(input: LocallyPendingCreatedProjectBranch): ProjectWorkspaceStateView;
+    beginBranchDeletion(input: LocallyPendingCreatedProjectBranch): Promise<ProjectWorkspaceStateView>;
     recordTreePublication(input: {
         tombstoneIds: readonly string[];
         publishedHead: string;
-    }): ProjectWorkspaceStateView;
+    }): Promise<ProjectWorkspaceStateView>;
     recordMirrorRefDeletion(input: {
         tombstoneId: string;
         branchName: string;
-    }): ProjectWorkspaceStateView;
+    }): Promise<ProjectWorkspaceStateView>;
 }
 export declare const projectWorkspaceStateTestHarness: {
-    writeEmptyStateAtDurableRootBoundary(stateRoot: string, afterStateRootFsync: () => void): void;
+    writeEmptyStateAtDurableRootBoundary(stateRoot: string, afterStateRootFsync: () => void): Promise<void>;
 };
 export {};

package/dist/types/project-worktrees.d.ts

@@ -1,14 +1,21 @@
 import { type ProjectMirrorMount, type ProjectMirrorRefsTokens } from "./project-mirror-refs-token";
+import type { WorkspaceFilesystemJobContext } from "./workspace-filesystem-job-types";
 export declare const PROJECT_WORKTREE_SNAPSHOT_PREFIX = "r5d-project-worktrees-";
 declare const PROJECT_WORKTREE_SNAPSHOT_MANIFEST_VERSION: 1;
+/**
+ * Distinguishes this control thread's live snapshots from stale ones left by
+ * an earlier process that reused the PID. The control thread passes it to
+ * every snapshot job, so the executor thread never invents its own.
+ */
+export declare const PROJECT_WORKTREE_SNAPSHOT_OWNER_SESSION_ID: `${string}-${string}-${string}-${string}-${string}`;
 /**
  * `project` snapshots cover every configured branch and restore by replacing
  * the whole project root. `branches` snapshots cover only the checkouts one
  * reconciliation rewrites and restore those paths individually, so a rollback
  * never touches a checkout the transaction did not.
  */
-type ProjectWorktreeSnapshotScope = "project" | "branches";
-type ProjectWorktreeSnapshotManifest = {
+export type ProjectWorktreeSnapshotScope = "project" | "branches";
+export type ProjectWorktreeSnapshotManifest = {
     version: typeof PROJECT_WORKTREE_SNAPSHOT_MANIFEST_VERSION;
     state: "building" | "prepared" | "restoring" | "consumed";
     scope: ProjectWorktreeSnapshotScope;
@@ -21,6 +28,11 @@ type ProjectWorktreeSnapshotManifest = {
     }>;
     createdAt: string;
 };
+export type ProjectWorktreeSnapshot = {
+    root: string;
+    manifest: ProjectWorktreeSnapshotManifest;
+    paths: Map<string, string>;
+};
 export type ProjectWorktreeSnapshotProgress = {
     operation: "snapshot" | "restore";
     phase: "scanning" | "copying" | "moving" | "syncing" | "cleaning";
@@ -161,10 +173,10 @@ export declare function createOrRetryLinkedProjectBranch(input: {
     branchName: string;
     workingTree: ProjectWorktreeWorkingTreeMode;
     pendingRetry: boolean;
-}): {
+}): Promise<{
     branchPath: string;
     baseCommitHash: string;
-};
+}>;
 export type ProjectCheckoutState = "linked" | "missing" | "not_a_worktree";
 export type ProjectCheckoutInventory = {
     /** Branches whose checkout is this project's primary clone or one of its linked worktrees. */
@@ -216,10 +228,18 @@ export declare function deleteLinkedProjectBranch(input: {
      */
     stagedForCollectionPath?: string;
 };
+/**
+ * Retire a whole project: one rename into the namespace garbage directory
+ * (the tree, primary Git objects included, is removed by the collector
+ * outside every lease), or nothing when the root is already gone.
+ */
 export declare function removeProjectWorktrees(input: {
+    projectsRoot: string;
     projectRoot: string;
     branchNames: readonly string[];
-}): void;
+}): {
+    stagedForCollectionPath?: string;
+};
 export declare function deleteProjectMirrorBranch(input: {
     gitDirectory: string;
     branchName: string;
@@ -335,6 +355,30 @@ export declare function reseedProjectHeadsFromMirror(input: ProjectMirrorHeadUpd
     mirrorHead: string | null;
     reseeded: boolean;
 }>>;
+/** Executor job body: `snapshotBranchTrees` with progress relayed to the control thread. */
+export declare function runProjectSnapshotCreateJob(input: {
+    projectRoot: string;
+    branches: ProjectWorktreeBranch[];
+    temporaryRoot: string;
+    scope: ProjectWorktreeSnapshotScope;
+    ownerSessionId: string;
+}, context: WorkspaceFilesystemJobContext): ProjectWorktreeSnapshot;
+/** Executor job body: mirror captured checkouts back over reconciled worktrees. */
+export declare function runProjectSnapshotApplyJob(input: {
+    mirrors: Array<{
+        snapshotPath: string;
+        targetPath: string;
+    }>;
+}): null;
+/** Executor job body: `persistReconciledProjectAndConsumeSnapshot`. */
+export declare function runProjectSnapshotPersistJob(input: {
+    snapshot: ProjectWorktreeSnapshot;
+    durabilityPaths: string[] | null;
+}): null;
+/** Executor job body: `rollbackProjectWorktreeSnapshot`. */
+export declare function runProjectSnapshotRollbackJob(input: {
+    snapshot: ProjectWorktreeSnapshot;
+}): null;
 export declare const projectWorktreesTestHarness: {
     commandArgs: typeof gitCommandArgs;
     configureRepository: typeof configureRepository;

package/dist/types/recovery-journal-protocol.d.ts

@@ -0,0 +1,35 @@
+/** Messages between the control thread and the recovery journal thread. */
+export declare const WORKER_RECOVERY_JOURNAL_OPS: readonly ["admit", "readmitUnknownBranchDeletion", "record", "unknown", "unknownRun", "acknowledgeResult", "acknowledgeOutput", "acknowledgeTerminal", "cancelSession", "isRequestCancelled", "operations", "recoveryState", "terminals", "outputReplayBegin", "outputReplayNext", "outputReplayEnd"];
+export type WorkerRecoveryJournalOp = (typeof WORKER_RECOVERY_JOURNAL_OPS)[number];
+export declare function isWorkerRecoveryJournalOp(value: unknown): value is WorkerRecoveryJournalOp;
+export type WorkerRecoveryJournalEntry = {
+    seq: number;
+    op: WorkerRecoveryJournalOp;
+    args: unknown[];
+};
+export type WorkerRecoveryJournalBatchRequest = {
+    type: "batch";
+    id: number;
+    entries: WorkerRecoveryJournalEntry[];
+};
+export type WorkerRecoveryJournalSerializedError = {
+    name: string;
+    message: string;
+    stack?: string;
+};
+export type WorkerRecoveryJournalThreadReply = {
+    type: "ready";
+    ledgerId: string;
+} | {
+    type: "batch_result";
+    id: number;
+    results: Array<{
+        seq: number;
+        value: unknown;
+    }>;
+} | {
+    type: "batch_failure";
+    id: number;
+    error: WorkerRecoveryJournalSerializedError;
+};
+export declare function serializeWorkerRecoveryJournalError(error: unknown): WorkerRecoveryJournalSerializedError;

package/dist/types/recovery-journal-runtime.d.ts

@@ -0,0 +1,12 @@
+import type { MessagePort } from "node:worker_threads";
+/**
+ * The recovery journal thread's loop. It owns the one WorkerRecoveryStore
+ * handle of the process and applies the control thread's entries strictly in
+ * sequence, one durable commit per batch. Everything the store guarantees
+ * (acceptance before effects, offsets, terminal lengths, unknown gating,
+ * acknowledgement retention, cancel snapshots) is unchanged; only the thread
+ * running it moved. `beforeBatch` exists for the stall fixture used by tests.
+ */
+export declare function serveRecoveryJournal(port: MessagePort, filename: string, hooks?: {
+    beforeBatch?: () => void;
+}): void;

package/dist/types/recovery-journal-stall-fixture.d.ts

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

package/dist/types/recovery-journal-thread.d.ts

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