@ricsam/r5d-worker 0.0.123 → 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/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";
@@ -1017,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";
@@ -1049,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 {};

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

@@ -0,0 +1,246 @@
+import type { WorkerOperationRecovery, WorkerOutputOffsets } from "./recovery-protocol";
+/**
+ * The control-thread side of the worker's durable recovery journal.
+ *
+ * The SQLite store (WAL, `synchronous=FULL`) lives on the journal thread;
+ * this facade owns one ordered channel of store operations and the ordered
+ * delivery of the messages those operations make durable. Its invariants:
+ *
+ * - order: every entry is applied in append order, one durable commit per
+ *   batch, so an `unknown` appended after a `record` applies after it, and an
+ *   `admit` of a later request commits after the `record` of an earlier one;
+ * - commit before send: a keyed message is written to the socket only after
+ *   the batch holding its `record` committed, in append order, so a terminal
+ *   never leaves before the output recorded ahead of it and a response is
+ *   never acknowledged before it is durable;
+ * - commit before effects: `admit` resolves after its commit; handlers run
+ *   after it;
+ * - bounded: everything the facade retains (entries waiting for the thread,
+ *   entries in the batch being committed, and committed messages not yet
+ *   drained to the socket) is charged to one general budget of entries and
+ *   bytes, reserved atomically before anything is queued and released only
+ *   when the item is actually done; unknown marks, acknowledgements and
+ *   handshake reads use a separate reserved control budget. Output producers
+ *   and admissions wait for budget in bounded waiting rooms; a result that
+ *   cannot be buffered is never sent early: its operation is marked unknown,
+ *   which is exactly what a crash would have left;
+ * - fail closed: a thread exit, a failed batch, or an exhausted control budget
+ *   fails every pending and future entry and reports once; the store is never
+ *   re-opened in-process.
+ */
+type Message = {
+    type: string;
+    [key: string]: unknown;
+};
+export declare const WORKER_RECOVERY_JOURNAL_MAX_BATCH_ENTRIES = 256;
+export declare const WORKER_RECOVERY_JOURNAL_MAX_PENDING_ENTRIES = 4096;
+export declare const WORKER_RECOVERY_JOURNAL_MAX_PENDING_BYTES: number;
+export declare const WORKER_RECOVERY_JOURNAL_MAX_CONTROL_ENTRIES = 2048;
+export declare const WORKER_RECOVERY_JOURNAL_MAX_CONTROL_BYTES: number;
+export declare const WORKER_RECOVERY_JOURNAL_MAX_ENTRY_BYTES: number;
+export declare const WORKER_RECOVERY_JOURNAL_OUTPUT_CHUNK_CHARACTERS: number;
+export declare const WORKER_RECOVERY_JOURNAL_MAX_WAITING_ADMISSIONS = 512;
+export declare const WORKER_RECOVERY_JOURNAL_MAX_WAITING_OUTPUT = 1024;
+export declare const WORKER_RECOVERY_JOURNAL_MAX_WAITING_BYTES: number;
+export declare const WORKER_RECOVERY_JOURNAL_REPLAY_PAGE_FRAMES = 32;
+export declare class WorkerRecoveryJournalError extends Error {
+    readonly name: string;
+}
+/** The journal is intact but its bounded waiting room is full; the caller must not queue more. */
+export declare class WorkerRecoveryJournalBusyError extends WorkerRecoveryJournalError {
+    readonly name = "WorkerRecoveryJournalBusyError";
+}
+export type WorkerRecoveryJournalAdmission = {
+    admission: "new" | "duplicate" | "unknown" | "conflict";
+    response: Message | undefined;
+    cancelled: boolean;
+};
+export type WorkerRecoveryJournalRecoveryState = {
+    operations: WorkerOperationRecovery[];
+    cursors: WorkerOutputOffsets[];
+    responses: Message[];
+    terminals: Message[];
+};
+export type WorkerRecoveryJournalStatus = {
+    /** Entries waiting for the thread plus entries in the batch being committed. */
+    pendingEntries: number;
+    /** General budget in use: pending entries and undelivered messages, in entries and bytes. */
+    retainedEntries: number;
+    retainedBytes: number;
+    controlEntries: number;
+    controlBytes: number;
+    waitingAdmissions: number;
+    waitingOutput: number;
+    /** Payload bytes held by requests and output chunks waiting for budget. */
+    waitingBytes: number;
+    /** Bytes of store replies (handshake state, output pages) the caller has not consumed yet. */
+    retainedReplyBytes: number;
+    committedSeq: number;
+    appendedSeq: number;
+    undelivered: number;
+    failed: string | null;
+};
+export type WorkerRecoveryJournalOptions = {
+    filename: string;
+    threadModulePath?: string;
+    /** Extra `workerData` for the thread module (test fixtures only). */
+    threadWorkerData?: Record<string, unknown>;
+    log?: (line: string) => void;
+    maxBatchEntries?: number;
+    maxPendingEntries?: number;
+    maxPendingBytes?: number;
+    maxControlEntries?: number;
+    maxControlBytes?: number;
+    maxEntryBytes?: number;
+    maxWaitingAdmissions?: number;
+    maxWaitingOutput?: number;
+    maxWaitingBytes?: number;
+};
+export declare class WorkerRecoveryJournal {
+    readonly ledgerId: string;
+    private readonly worker;
+    private readonly log;
+    private readonly maxBatchEntries;
+    private readonly maxEntryBytes;
+    private readonly maxWaitingAdmissions;
+    private readonly maxWaitingOutput;
+    private readonly maxWaitingBytes;
+    private waitingBytes;
+    private retainedReplyBytes;
+    private readonly general;
+    private readonly control;
+    private nextSeq;
+    private committedSeq;
+    private readonly pending;
+    private inFlight;
+    private nextBatchId;
+    private readonly waiters;
+    private readonly outbound;
+    private deliveryPaused;
+    private replayCoveredSeq;
+    private failure;
+    private closed;
+    private readonly pendingAdmissions;
+    private readonly activeOperations;
+    private readonly cancelledRequestIds;
+    private readonly unknownRequestIds;
+    private readonly unknownRunIds;
+    private readonly coalescedControl;
+    private readonly flushWaiters;
+    /** Delivers one committed message in order; returns false when the transport declined it (the pumps re-send). */
+    deliver: ((message: Message) => boolean) | undefined;
+    /** Invoked once when the journal fails closed. */
+    onFailure: ((error: Error) => void) | undefined;
+    private constructor();
+    /** Start the journal thread, open the store there (its crash recovery runs there) and return once it is ready. */
+    static open(options: WorkerRecoveryJournalOptions): Promise<WorkerRecoveryJournal>;
+    status(): WorkerRecoveryJournalStatus;
+    /**
+     * Durably admit an inbound operation; resolves after the commit. Waits for
+     * general budget in a bounded waiting room; when that room is full the
+     * admission is refused at once (WorkerRecoveryJournalBusyError) so the
+     * message is neither acknowledged nor retained.
+     */
+    admit(message: Message & {
+        requestId: string;
+    }): Promise<WorkerRecoveryJournalAdmission>;
+    /**
+     * Re-admit an unknown branch deletion. Like `admit`, the request is a
+     * pending admission from before the await, so a session cancellation that
+     * lands while the disk is slow snapshots it and the handler's recheck after
+     * the await refuses to rerun the deletion.
+     */
+    readmitUnknownBranchDeletion(requestId: string, sessionId: string | undefined): Promise<boolean>;
+    /**
+     * Queue an outbound message. Keyed messages are recorded (when the store
+     * records their type) and delivered in order after their commit; other
+     * messages are delivered at once. Returns false when the message was not
+     * queued: its operation is already unknown, or the budget cannot hold it,
+     * in which case the operation is marked unknown so it is neither
+     * acknowledged early nor sent later.
+     */
+    send(message: Message): boolean;
+    /**
+     * Queue an output frame, split into bounded records, waiting for budget so
+     * a stalled journal throttles the producer (and through the pipe, the
+     * child) instead of growing memory.
+     */
+    sendOutput(frame: Message & {
+        type: "exec_output";
+        runId: string;
+        stream: "stdout" | "stderr";
+        data: string;
+    }): Promise<void>;
+    /**
+     * Reserve general budget atomically, waiting in the bounded room of `kind`
+     * when it does not fit now. The waiting room is bounded in count and in
+     * payload bytes (the message a waiting admission holds is charged before it
+     * waits), and an entry that could never fit the general budget is refused
+     * at once rather than parked at the head of the queue.
+     */
+    private reserveGeneral;
+    /** Reserve for the head waiter inside this synchronous call, so no continuation can outrun the accounting. */
+    private wakeWaiters;
+    private enqueueRecord;
+    private refuse;
+    private trackRecorded;
+    /**
+     * Mark an operation unknown: never sent again (undelivered messages for it
+     * are dropped now, and the durable mark keeps replay from resurrecting it).
+     * Coalesced per id; uses the reserved control budget.
+     */
+    unknown(requestId: string): void;
+    unknownRun(runId: string): void;
+    acknowledgeResult(requestId: string): void;
+    /** Monotonic per stream: a later acknowledgement replaces a pending earlier one. */
+    acknowledgeOutput(runId: string, stream: "stdout" | "stderr", offset: number): void;
+    acknowledgeTerminal(runId: string): void;
+    /**
+     * Snapshot every admitted and pending operation of the session as cancelled
+     * (the handlers check `isRequestCancelled` at their fences) and append the
+     * durable cancellation, which the thread applies after every admission
+     * appended before it. Resolves after the commit.
+     */
+    cancelSession(sessionId: string): Promise<void>;
+    isRequestCancelled(requestId: string): boolean;
+    /** Every operation admitted or awaiting admission in this process that has not completed, for the runtime fence and lease expiry. */
+    activeAndPendingOperations(): WorkerOperationRecovery[];
+    /**
+     * The handshake read. One entry, so it sees exactly the entries appended
+     * before it and none after: the replay boundary. Callers pause delivery
+     * before appending it and resume after the handshake, so every keyed
+     * message committed before the mark is replayed once (from the store) and
+     * nothing committed after it can enter the replay of responses, operations
+     * or terminals; output pages that follow may re-send frames the pump would
+     * re-send anyway, which the server's offset cursors absorb.
+     */
+    recoveryState(requests: string[]): Promise<WorkerRecoveryJournalRecoveryState>;
+    private retainedStateBytes;
+    /** Output replay, one bounded page at a time; a page is accounted until the consumer asks for the next one. */
+    outputReplay(offsets: WorkerOutputOffsets[] | undefined, pageFrames?: number): AsyncGenerator<Message[]>;
+    terminals(): Promise<Message[]>;
+    /** Delivery of committed keyed messages is held (in order) while a handshake replays from the store. */
+    pauseDelivery(): void;
+    resumeDelivery(): void;
+    /** Resolves once every entry appended so far is committed (or the journal failed). */
+    flush(): Promise<void>;
+    close(): void;
+    private assertOpen;
+    /** Control entries are tiny and idempotent per key: a pending one is updated in place instead of queued again. */
+    private appendControl;
+    /** A control-budget entry whose result the caller awaits; rejects when the budget is exhausted. */
+    private appendControlOrThrow;
+    private lastAppended;
+    /** Queue an entry whose budget was already reserved from `budget`. */
+    private append;
+    private dispatch;
+    private onReply;
+    private dropOutbound;
+    private releaseOutbound;
+    private deliverReady;
+    private fail;
+    private failEntries;
+}
+/** The packaged thread module lives next to this module with the same extension (.ts in source, .cjs/.mjs in the package). */
+export declare function workerRecoveryJournalThreadModulePath(): string;
+export {};