@ricsam/r5d-worker 0.0.123 → 0.0.125

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

@@ -86,7 +86,8 @@ export declare class WorkerCommandLauncher {
     capacityReport(): CommandLaunchCapacityReport;
     private notifyCapacityChange;
     acquire(request: CommandLaunchRequest): Promise<CommandLaunchLease>;
-    cancel(id: string): Promise<void>;
+    /** Revoke a launch. Returns whether this launcher still held it (queued or acquired, not yet released). */
+    cancel(id: string): Promise<boolean>;
     cancelSession(sessionId: string): Promise<void>;
     cancelMatching(matches: (id: string, sessionId?: string) => boolean): Promise<void>;
     close(): Promise<void>;

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";
@@ -136,6 +141,8 @@ export type WorkerSessionTarget = {
     ownerUserId: string;
     rootProfile: "visible_projects" | "canonical_sync";
 };
+type WorkerCancelScope = "unstarted";
+type WorkerCancelOutcome = "unstarted" | "started" | "stopped" | "unknown";
 type WorkerClientMessage = WorkerRecoveryClientMessage | {
     type: "capacity_report";
     capacity: import("./command-launcher").CommandLaunchCapacityReport & {
@@ -257,6 +264,8 @@ type WorkerClientMessage = WorkerRecoveryClientMessage | {
     runId: string;
     cancelled: boolean;
     message?: string;
+    /** `unstarted`: a launch that had not spawned was revoked; `started`: a spawned process was left alone; `stopped`; `unknown`: no record, cancellation recorded. */
+    outcome?: WorkerCancelOutcome;
 } | {
     type: "pong";
 } | {
@@ -528,6 +537,8 @@ type WorkerServerMessage = WorkerRecoveryServerMessage | {
     type: "cancel";
     requestId: string;
     runId: string;
+    /** `unstarted`: the server's start-deadline abandonment; never touch a spawned process. */
+    scope?: WorkerCancelScope;
 } | {
     type: "ping";
 };
@@ -1017,12 +1028,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 +1060,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 {};