@ricsam/r5d-worker 0.0.135 → 0.0.137

package/dist/types/runtime/protocol.d.ts

@@ -0,0 +1,372 @@
+import { z } from "zod";
+export declare const EXECUTOR_CAPABILITY = "host-executor-v1";
+export declare const MAX_FRAME_BYTES: number;
+export declare const Lane: z.ZodEnum<{
+    control: "control";
+    general: "general";
+    utility: "utility";
+}>;
+export declare const ShellPayload: z.ZodObject<{
+    argv: z.ZodArray<z.ZodString>;
+    cwd: z.ZodString;
+    env: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    lane: z.ZodDefault<z.ZodEnum<{
+        control: "control";
+        general: "general";
+        utility: "utility";
+    }>>;
+    interactive: z.ZodDefault<z.ZodBoolean>;
+    pty: z.ZodOptional<z.ZodObject<{
+        cols: z.ZodNumber;
+        rows: z.ZodNumber;
+    }, z.core.$strict>>;
+    credentials: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        generation: z.ZodNumber;
+    }, z.core.$strict>>>;
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export type ShellPayload = z.input<typeof ShellPayload>;
+export declare const RunIdentity: z.ZodObject<{
+    operationId: z.ZodString;
+    userId: z.ZodString;
+    sessionId: z.ZodOptional<z.ZodString>;
+    fence: z.ZodObject<{
+        installationId: z.ZodString;
+        resourceType: z.ZodString;
+        resourceId: z.ZodString;
+        ownerId: z.ZodString;
+        epoch: z.ZodNumber;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type RunIdentity = z.infer<typeof RunIdentity>;
+export declare const ExecutorCommand: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    method: z.ZodLiteral<"status">;
+}, z.core.$strict>, z.ZodObject<{
+    method: z.ZodLiteral<"authority">;
+    fence: z.ZodObject<{
+        installationId: z.ZodString;
+        resourceType: z.ZodString;
+        resourceId: z.ZodString;
+        ownerId: z.ZodString;
+        epoch: z.ZodNumber;
+    }, z.core.$strict>;
+    validUntil: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    method: z.ZodLiteral<"start">;
+    operation: z.ZodObject<{
+        protocol: z.ZodLiteral<1>;
+        installationId: z.ZodString;
+        operationId: z.ZodString;
+        userId: z.ZodString;
+        sessionId: z.ZodOptional<z.ZodString>;
+        kind: z.ZodString;
+        fence: z.ZodObject<{
+            installationId: z.ZodString;
+            resourceType: z.ZodString;
+            resourceId: z.ZodString;
+            ownerId: z.ZodString;
+            epoch: z.ZodNumber;
+        }, z.core.$strict>;
+        payload: z.ZodUnknown;
+    }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    method: z.ZodLiteral<"poll">;
+    run: z.ZodObject<{
+        operationId: z.ZodString;
+        userId: z.ZodString;
+        sessionId: z.ZodOptional<z.ZodString>;
+        fence: z.ZodObject<{
+            installationId: z.ZodString;
+            resourceType: z.ZodString;
+            resourceId: z.ZodString;
+            ownerId: z.ZodString;
+            epoch: z.ZodNumber;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+    stdoutOffset: z.ZodDefault<z.ZodNumber>;
+    stderrOffset: z.ZodDefault<z.ZodNumber>;
+    maxBytes: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>, z.ZodObject<{
+    method: z.ZodLiteral<"write">;
+    run: z.ZodObject<{
+        operationId: z.ZodString;
+        userId: z.ZodString;
+        sessionId: z.ZodOptional<z.ZodString>;
+        fence: z.ZodObject<{
+            installationId: z.ZodString;
+            resourceType: z.ZodString;
+            resourceId: z.ZodString;
+            ownerId: z.ZodString;
+            epoch: z.ZodNumber;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+    actionId: z.ZodString;
+    data: z.ZodString;
+    eof: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strict>, z.ZodObject<{
+    method: z.ZodLiteral<"resize">;
+    run: z.ZodObject<{
+        operationId: z.ZodString;
+        userId: z.ZodString;
+        sessionId: z.ZodOptional<z.ZodString>;
+        fence: z.ZodObject<{
+            installationId: z.ZodString;
+            resourceType: z.ZodString;
+            resourceId: z.ZodString;
+            ownerId: z.ZodString;
+            epoch: z.ZodNumber;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+    actionId: z.ZodString;
+    cols: z.ZodNumber;
+    rows: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    method: z.ZodLiteral<"cancel">;
+    run: z.ZodObject<{
+        operationId: z.ZodString;
+        userId: z.ZodString;
+        sessionId: z.ZodOptional<z.ZodString>;
+        fence: z.ZodObject<{
+            installationId: z.ZodString;
+            resourceType: z.ZodString;
+            resourceId: z.ZodString;
+            ownerId: z.ZodString;
+            epoch: z.ZodNumber;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+    actionId: z.ZodString;
+}, z.core.$strict>], "method">;
+export type ExecutorCommand = z.input<typeof ExecutorCommand>;
+export declare const ExecutorRequest: z.ZodObject<{
+    protocol: z.ZodLiteral<1>;
+    requestId: z.ZodString;
+    auth: z.ZodObject<{
+        principalId: z.ZodString;
+        token: z.ZodString;
+    }, z.core.$strict>;
+    hello: z.ZodObject<{
+        installationId: z.ZodString;
+        instanceId: z.ZodString;
+        releaseId: z.ZodString;
+        role: z.ZodEnum<{
+            web: "web";
+            scheduler: "scheduler";
+            runner: "runner";
+            gateway: "gateway";
+            "worker-adapter": "worker-adapter";
+            "browser-adapter": "browser-adapter";
+            executor: "executor";
+            keeper: "keeper";
+            storage: "storage";
+        }>;
+        protocol: z.ZodObject<{
+            min: z.ZodNumber;
+            max: z.ZodNumber;
+        }, z.core.$strict>;
+        capabilities: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>;
+    command: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        method: z.ZodLiteral<"status">;
+    }, z.core.$strict>, z.ZodObject<{
+        method: z.ZodLiteral<"authority">;
+        fence: z.ZodObject<{
+            installationId: z.ZodString;
+            resourceType: z.ZodString;
+            resourceId: z.ZodString;
+            ownerId: z.ZodString;
+            epoch: z.ZodNumber;
+        }, z.core.$strict>;
+        validUntil: z.ZodNumber;
+    }, z.core.$strict>, z.ZodObject<{
+        method: z.ZodLiteral<"start">;
+        operation: z.ZodObject<{
+            protocol: z.ZodLiteral<1>;
+            installationId: z.ZodString;
+            operationId: z.ZodString;
+            userId: z.ZodString;
+            sessionId: z.ZodOptional<z.ZodString>;
+            kind: z.ZodString;
+            fence: z.ZodObject<{
+                installationId: z.ZodString;
+                resourceType: z.ZodString;
+                resourceId: z.ZodString;
+                ownerId: z.ZodString;
+                epoch: z.ZodNumber;
+            }, z.core.$strict>;
+            payload: z.ZodUnknown;
+        }, z.core.$strict>;
+    }, z.core.$strict>, z.ZodObject<{
+        method: z.ZodLiteral<"poll">;
+        run: z.ZodObject<{
+            operationId: z.ZodString;
+            userId: z.ZodString;
+            sessionId: z.ZodOptional<z.ZodString>;
+            fence: z.ZodObject<{
+                installationId: z.ZodString;
+                resourceType: z.ZodString;
+                resourceId: z.ZodString;
+                ownerId: z.ZodString;
+                epoch: z.ZodNumber;
+            }, z.core.$strict>;
+        }, z.core.$strict>;
+        stdoutOffset: z.ZodDefault<z.ZodNumber>;
+        stderrOffset: z.ZodDefault<z.ZodNumber>;
+        maxBytes: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>, z.ZodObject<{
+        method: z.ZodLiteral<"write">;
+        run: z.ZodObject<{
+            operationId: z.ZodString;
+            userId: z.ZodString;
+            sessionId: z.ZodOptional<z.ZodString>;
+            fence: z.ZodObject<{
+                installationId: z.ZodString;
+                resourceType: z.ZodString;
+                resourceId: z.ZodString;
+                ownerId: z.ZodString;
+                epoch: z.ZodNumber;
+            }, z.core.$strict>;
+        }, z.core.$strict>;
+        actionId: z.ZodString;
+        data: z.ZodString;
+        eof: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strict>, z.ZodObject<{
+        method: z.ZodLiteral<"resize">;
+        run: z.ZodObject<{
+            operationId: z.ZodString;
+            userId: z.ZodString;
+            sessionId: z.ZodOptional<z.ZodString>;
+            fence: z.ZodObject<{
+                installationId: z.ZodString;
+                resourceType: z.ZodString;
+                resourceId: z.ZodString;
+                ownerId: z.ZodString;
+                epoch: z.ZodNumber;
+            }, z.core.$strict>;
+        }, z.core.$strict>;
+        actionId: z.ZodString;
+        cols: z.ZodNumber;
+        rows: z.ZodNumber;
+    }, z.core.$strict>, z.ZodObject<{
+        method: z.ZodLiteral<"cancel">;
+        run: z.ZodObject<{
+            operationId: z.ZodString;
+            userId: z.ZodString;
+            sessionId: z.ZodOptional<z.ZodString>;
+            fence: z.ZodObject<{
+                installationId: z.ZodString;
+                resourceType: z.ZodString;
+                resourceId: z.ZodString;
+                ownerId: z.ZodString;
+                epoch: z.ZodNumber;
+            }, z.core.$strict>;
+        }, z.core.$strict>;
+        actionId: z.ZodString;
+    }, z.core.$strict>], "method">;
+}, z.core.$strict>;
+export declare const ExecutorConfig: z.ZodObject<{
+    installationId: z.ZodString;
+    workerId: z.ZodString;
+    instanceId: z.ZodString;
+    releaseId: z.ZodString;
+    stateDir: z.ZodString;
+    capacity: z.ZodObject<{
+        general: z.ZodNumber;
+        utility: z.ZodNumber;
+        control: z.ZodNumber;
+    }, z.core.$strict>;
+    maxLeaseMs: z.ZodDefault<z.ZodNumber>;
+    maxRunMs: z.ZodDefault<z.ZodNumber>;
+    maxLogBytes: z.ZodDefault<z.ZodNumber>;
+    principals: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        tokenHash: z.ZodString;
+        role: z.ZodEnum<{
+            controller: "controller";
+            adapter: "adapter";
+        }>;
+        ownerId: z.ZodString;
+        userIds: z.ZodArray<z.ZodString>;
+        cwdRoots: z.ZodArray<z.ZodString>;
+        lanes: z.ZodArray<z.ZodEnum<{
+            control: "control";
+            general: "general";
+            utility: "utility";
+        }>>;
+        credentialIds: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>;
+    credentials: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        installationId: z.ZodString;
+        userId: z.ZodString;
+        generation: z.ZodNumber;
+        env: z.ZodRecord<z.ZodString, z.ZodString>;
+        files: z.ZodRecord<z.ZodString, z.ZodString>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export type ExecutorConfig = z.input<typeof ExecutorConfig>;
+export type ResolvedConfig = z.output<typeof ExecutorConfig>;
+export type Principal = ResolvedConfig["principals"][number];
+export declare const AdapterConfig: z.ZodObject<{
+    socketPath: z.ZodString;
+    principalId: z.ZodString;
+    token: z.ZodString;
+    hello: z.ZodObject<{
+        installationId: z.ZodString;
+        instanceId: z.ZodString;
+        releaseId: z.ZodString;
+        role: z.ZodEnum<{
+            web: "web";
+            scheduler: "scheduler";
+            runner: "runner";
+            gateway: "gateway";
+            "worker-adapter": "worker-adapter";
+            "browser-adapter": "browser-adapter";
+            executor: "executor";
+            keeper: "keeper";
+            storage: "storage";
+        }>;
+        protocol: z.ZodObject<{
+            min: z.ZodNumber;
+            max: z.ZodNumber;
+        }, z.core.$strict>;
+        capabilities: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>;
+    timeoutMs: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>;
+export type AdapterConfig = z.input<typeof AdapterConfig>;
+export type RunReceipt = {
+    operationId: string;
+    userId: string;
+    sessionId: string | null;
+    payloadHash: string;
+    state: "accepted" | "running" | "completed" | "cancelled" | "unknown";
+    pid: number | null;
+    pty: boolean;
+    lane: z.infer<typeof Lane>;
+    stdoutBytes: number;
+    stderrBytes: number;
+    stdinClosed: boolean;
+    exitCode: number | null;
+    signal: string | null;
+    reason: string | null;
+};
+export type ActionReceipt = {
+    actionId: string;
+    state: "accepted" | "completed" | "unknown";
+};
+export type PollResult = {
+    receipt: RunReceipt;
+    stdout: {
+        base64: string;
+        nextOffset: number;
+    };
+    stderr: {
+        base64: string;
+        nextOffset: number;
+    };
+};
+export declare class ExecutorError extends Error {
+    readonly code: string;
+    constructor(code: string, message?: string);
+}

package/dist/types/runtime/pty.d.ts

@@ -0,0 +1,29 @@
+/** Node native FD keeper is a daemon child; replacing adapters cannot signal it. */
+export declare class PtySession {
+    pid: number;
+    private sequence;
+    private readonly pending;
+    private readonly child;
+    private onDataCallback?;
+    private onExitCallback?;
+    private readonly buffered;
+    private exit?;
+    readonly ready: Promise<void>;
+    constructor(input: {
+        argv: string[];
+        cwd: string;
+        env: Record<string, string>;
+        cols: number;
+        rows: number;
+    });
+    private deliverExit;
+    onData(callback: (data: Buffer) => void): void;
+    onExit(callback: (event: {
+        exitCode: number;
+        signal: number;
+    }) => void): void;
+    private request;
+    write(data: string): Promise<void>;
+    resize(cols: number, rows: number): Promise<void>;
+    kill(signal?: string): void;
+}

package/dist/types/runtime/storage.d.ts

@@ -0,0 +1,21 @@
+import { Database } from "bun:sqlite";
+import { type RunReceipt } from "./protocol";
+export declare function privateDirectory(path: string): void;
+export declare function readPrivateJson(path: string): unknown;
+/** Single host authority: a separate rollback-mode SQLite exclusive lock survives no process death. */
+export declare class ExecutorStore {
+    readonly root: string;
+    readonly db: Database;
+    private readonly lock;
+    constructor(root: string, installationId: string, workerId: string);
+    all(): RunReceipt[];
+    get(id: string): RunReceipt | null;
+    put(receipt: RunReceipt): void;
+    outputPath(id: string, stream: "stdout" | "stderr"): string;
+    append(id: string, stream: "stdout" | "stderr", data: Buffer): void;
+    read(id: string, stream: "stdout" | "stderr", offset: number, end: number, max: number): {
+        base64: string;
+        nextOffset: number;
+    };
+    close(): void;
+}

package/dist/types/runtime/test-harness.d.ts

@@ -0,0 +1,53 @@
+import { type ChildProcessWithoutNullStreams } from "node:child_process";
+import { HostExecutorClient } from "./client";
+import { type ExecutorCommand, type ExecutorConfig } from "./protocol";
+import type { OperationEnvelope, OwnershipFence } from "@ricsam/r5d-api/runtime-protocol";
+export declare const testEnvironment: {
+    PATH: string;
+    HOME: string;
+    LANG: string;
+};
+export declare const delay: (ms: number) => Promise<void>;
+export declare function eventually<T>(read: () => Promise<T>, accept: (value: T) => boolean, timeoutMs?: number): Promise<T>;
+export declare function stop(child: ChildProcessWithoutNullStreams, signal?: NodeJS.Signals): Promise<void>;
+export declare class AdapterProcess {
+    readonly process: ChildProcessWithoutNullStreams;
+    private pending;
+    constructor(configPath: string);
+    request<T = {
+        state: string;
+    }>(command: ExecutorCommand): Promise<T>;
+}
+export declare class Harness {
+    readonly root: string;
+    readonly cwd: string;
+    readonly stateDir: string;
+    readonly daemonPath: string;
+    readonly tokens: {
+        [k: string]: string;
+    };
+    readonly config: ExecutorConfig;
+    readonly clients: Record<string, HostExecutorClient>;
+    readonly adapterPaths: Record<string, string>;
+    readonly adapters: AdapterProcess[];
+    daemon?: ChildProcessWithoutNullStreams;
+    constructor(options?: Partial<ExecutorConfig>);
+    startDaemon(): Promise<void>;
+    adapter(id: "blue" | "green" | "third"): AdapterProcess;
+    fence(ownerId?: string, epoch?: number): OwnershipFence;
+    promote(ownerId?: string, epoch?: number, leaseMs?: number): Promise<unknown>;
+    operation(operationId?: string, argv?: string[], ownerId?: string, epoch?: number): OperationEnvelope;
+    run(operationId: string, ownerId?: string, epoch?: number): {
+        operationId: string;
+        userId: string;
+        sessionId: string;
+        fence: {
+            installationId: string;
+            resourceType: string;
+            resourceId: string;
+            ownerId: string;
+            epoch: number;
+        };
+    };
+    close(): Promise<void>;
+}

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

@@ -1,5 +1,6 @@
 import type { ProjectWorktreeBranch, ProjectWorktreeSnapshot, ProjectWorktreeSnapshotProgress, ProjectWorktreeSnapshotScope, ProjectWorktreeWorkingTreeMode } from "./project-worktrees";
 import type { ProjectedWorkingTreeEntry, WorkingTreeGitlink } from "./working-tree-mirror";
+import type { WorkspaceHydrationLedgerEntry } from "./workspace-hydration-ledger";
 import type { WorkspaceGitMountData, WorkspaceHydrationReceipt, WorkspaceHydrationRecoveryRequired, WorkspaceHydrationPreservationResult, WorkspaceHydrationMountSkip } from "./workspace-git-sync";
 import type { WorkspaceHydrationMergeBasis } from "./workspace-hydration-merge";
 import type { WorkspaceMergeProjectionMount, WorkspaceMergeProjectionResult } from "./workspace-merge-projection";
@@ -64,8 +65,13 @@ export type WorkspaceFilesystemJobTable = {
         result: {
             hydratedMountIds: string[];
             skippedMounts: WorkspaceHydrationMountSkip[];
-            /** Per merge-hydrated mount, the blob each replaced path held before hydration (the stale-rewrite detector's input). */
-            hydratedPreBlobs: Record<string, Record<string, string>>;
+            /**
+             * Per merge-hydrated mount, what hydration replaced at each path: the
+             * previous and written blobs and the `lstat` it left behind (the
+             * hydration ledger's record, minus the process-liveness flag the
+             * control thread adds).
+             */
+            hydratedEntries: Record<string, Record<string, Omit<WorkspaceHydrationLedgerEntry, "processLiveAcrossHydration">>>;
         };
     };
     /** Pre-clone hydration of visible mounts without a transaction (no outer Git directory yet). */
@@ -107,8 +113,8 @@ export type WorkspaceFilesystemJobTable = {
             basisHead: string;
             currentHead: string;
             attemptId: string;
-            /** Blob ids the last merge hydration replaced, by mount-relative path; a changed file hashing to one is a stale rewrite. */
-            staleRewriteBlobs?: Record<string, string>;
+            /** What the last merge hydration replaced, by mount-relative path (see WorkspaceHydrationLedger). */
+            hydrationLedger?: Record<string, WorkspaceHydrationLedgerEntry>;
         };
         result: WorkspaceMergeProjectionResult;
     };
@@ -121,7 +127,9 @@ export type WorkspaceFilesystemJobTable = {
         input: {
             workspacePath: string;
             mount: WorkspaceGitMountData;
-            staleRewriteBlobs?: Record<string, string>;
+            hydrationLedger?: Record<string, WorkspaceHydrationLedgerEntry>;
+            /** Stop after the ledger pass; mirror nothing. */
+            checkOnly?: boolean;
         };
         result: {
             gitlinks: WorkingTreeGitlink[];
@@ -129,6 +137,12 @@ export type WorkspaceFilesystemJobTable = {
             /** Wall-clock time the mirror finished reading; projected stats younger than this minus a window are not trusted. */
             readAtMs: number;
             staleRewritePaths: string[];
+            /**
+             * Ledger paths a process alive across their hydration rewrote: nothing
+             * was mirrored, and the mount must be projected through the merge path
+             * with those paths merged against what the process read.
+             */
+            ledgerMergePaths: string[];
             /** Ledger paths whose checkout content moved on from both the replaced and the hydrated bytes. */
             staleRewriteCleared: string[];
         };

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

@@ -1,6 +1,6 @@
 import { type PreparedWorkingTreeMirror, type ProjectedWorkingTreeEntry, type WorkingTreeGitlink, type WorkingTreeMirrorPlan, type WorkingTreeMirrorScope, type WorkingTreeSourceMode } from "./working-tree-mirror";
 import { type WorkspaceHydrationMergeBasis, type WorkspaceHydrationMergeDecision, type WorkspaceHydrationMountSkip as WorkspaceHydrationMountSkipBase } from "./workspace-hydration-merge";
-import { WorkspaceHydrationPreBlobLedger } from "./workspace-hydration-ledger";
+import { WorkspaceHydrationLedger, type WorkspaceHydrationLedgerEntry } from "./workspace-hydration-ledger";
 export declare const WORKSPACE_GIT_BRANCH = "main";
 export declare const MAX_WORKSPACE_GIT_DIFF_BYTES: number;
 export declare const WORKSPACE_GIT_CONFIRMED_LARGE_DIFF_PUSH_OPTION = "r5d-confirm-large-diff-v1";
@@ -10,11 +10,13 @@ export declare const WORKSPACE_GIT_HYDRATION_RECOVERIES = "r5d/workspace-hydrati
 export declare const WORKSPACE_GIT_CHECKOUT_DURABILITY = "r5d/workspace-checkout-durability";
 /** `R5D_MERGE_HYDRATION=0` restores the plain byte mirror for post-publication hydration (docs/merge-hydration-design.md §4). */
 export declare const WORKSPACE_MERGE_HYDRATION_SWITCH = "R5D_MERGE_HYDRATION";
-declare function hydrationPreBlobLedger(workspacePath: string): WorkspaceHydrationPreBlobLedger;
+/** `R5D_PROCESS_BUSY_FENCE=1` makes a live process or PTY skip its mount again, as every cycle did before merge hydration. */
+export declare const WORKSPACE_PROCESS_BUSY_FENCE_SWITCH = "R5D_PROCESS_BUSY_FENCE";
+declare function hydrationPreBlobLedger(workspacePath: string): WorkspaceHydrationLedger;
 export type WorkspaceHydrationMountSkip = WorkspaceHydrationMountSkipBase & {
     retainedPaths?: string[];
 };
-export type WorkspaceMountSkipReason = WorkspaceHydrationMountSkip["reason"] | "stale_rewrite_detected";
+export type WorkspaceMountSkipReason = WorkspaceHydrationMountSkip["reason"] | "stale_rewrite_detected" | "projection_conflict_deferred";
 /** Why a mount was left at its recorded basis this cycle, with the paths involved; a diagnostic beside `skippedMountIds`. */
 export type WorkspaceMountSkipReasons = Record<string, {
     reason: WorkspaceMountSkipReason;
@@ -124,6 +126,16 @@ export type WorkspaceGitMount = {
     /** Remove the outer-workspace subtree when the mounted source was intentionally deleted. */
     deleteWhenSourceMissing?: boolean;
     busy?: () => boolean;
+    /**
+     * True while a worker-tracked process or PTY targets this mount. Not a
+     * fence (a busy checkout is still projected and hydrated; merge hydration
+     * folds the inbound change into it): a conflict found on a mount with a
+     * live process is deferred instead of reported, and the hydration ledger
+     * records the liveness so a stale-read rewrite by that process is merged
+     * at the next projection. `R5D_PROCESS_BUSY_FENCE=1` folds it back into
+     * `busy` (see `mountBusy`).
+     */
+    processLive?: () => boolean;
     /** Control-thread diagnostics only; never sent to a filesystem job. */
     describeHolders?: () => string;
     /** Monotonic/opaque visible-mutation token used to catch short writes that begin and end between busy checks. */
@@ -359,7 +371,7 @@ export declare function runHydrationTransactionJob(input: {
 }): {
     hydratedMountIds: string[];
     skippedMounts: WorkspaceHydrationMountSkip[];
-    hydratedPreBlobs: Record<string, Record<string, string>>;
+    hydratedEntries: Record<string, Record<string, Omit<WorkspaceHydrationLedgerEntry, "processLiveAcrossHydration">>>;
 };
 /** Executor job body: hydrate visible mounts before an outer clone exists (no transaction to record). */
 export declare function runHydrationRawJob(input: {
@@ -454,16 +466,23 @@ 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, recording what it read. */
+/**
+ * Executor job body: byte-mirror one visible mount into the outer checkout,
+ * recording what it read. With `checkOnly` it stops after the ledger pass:
+ * the cycle decides the mount's route (mirror, merge, or a stale-rewrite
+ * refusal) before any outer write.
+ */
 export declare function runProjectionMirrorJob(input: {
     workspacePath: string;
     mount: WorkspaceGitMountData;
-    staleRewriteBlobs?: Record<string, string>;
+    hydrationLedger?: Record<string, WorkspaceHydrationLedgerEntry>;
+    checkOnly?: boolean;
 }): {
     gitlinks: WorkingTreeGitlink[];
     projectedFiles: Record<string, ProjectedWorkingTreeEntry>;
     readAtMs: number;
     staleRewritePaths: string[];
+    ledgerMergePaths: string[];
     staleRewriteCleared: string[];
 };
 /** Executor job body: outer-tree edits that follow the mirrors, in the cycle's order. */