@quantiya/codevibe-core 2.0.82 → 2.0.84

package/dist/local-executor/shadow-protocol.d.ts

@@ -30,19 +30,71 @@ export declare const SHADOW_DIR_RE: RegExp;
 /** Private create name: never classified as a runnable/recoverable snapshot. */
 export declare const SHADOW_STAGING_DIR_RE: RegExp;
 export declare const SHADOW_TREE_TOMBSTONE_RE: RegExp;
+/**
+ * P63 SB-45: materializer helpers per snapshot create. Every lane runs the same per-file checks; lanes only run in
+ * parallel. Chosen from the measured scaling on APFS (`.hard-gate/p63-…/evidence/lanes-bench-*.log`).
+ */
+export declare const DEFAULT_MATERIALIZER_LANES = 4;
 export declare const SHADOW_UUID_SUFFIX_RE: RegExp;
+/** §6.2's per-spawn advisory records live in the v2 state root beside the task folders, never as a task. */
+export declare const SHADOW_STATE_ADVISORY_DIR = "advisory";
 export declare function isStateRootInfrastructureDirectory(name: string): boolean;
 export declare function taskIdFromGeneratedShadowName(name: string): string | null;
 /** Strict lifecycle-lock residue authored by `withAnchoredExclusiveLock`. */
 export declare const SHADOW_LIFECYCLE_LOCK_ARTIFACT_RE: RegExp;
-/** Never silently duplicate one enormous file when reflinks are unavailable. */
+/**
+ * Fixed ceilings on a **physical** (non-reflink) copy — **retired by §5.6** (they were 64 MiB per file and 512 MiB in
+ * total, which made an ordinary ext4 project unusable). Every task now gets a budget from the space that actually
+ * exists (`shadow-free-space.ts` `physicalCopyBudgetBytes`, the materializer's limits), and the watchdog bounds the
+ * running task. These remain only as the largest value the budget and the session ledger accept.
+ *
+ * Lifting them is safe for rollback because Slice 1 tasks live under `shadow-state-v2/`, which the 2.0.77 floor never
+ * reads (§17): no older desktop ever meets a marker above the old 512 MiB.
+ */
 export declare const MAX_NON_COW_FILE_BYTES: number;
 export declare const MAX_NON_COW_WORKSPACE_BYTES: number;
+/**
+ * Sanity bound on a `physicalCopyBytes` value read back from a **persisted** marker or owner anchor.
+ *
+ * Deliberately a separate constant from {@link MAX_NON_COW_WORKSPACE_BYTES}, which it used to be. The runtime
+ * limit decides how much a copy may write; this one decides whether a deserialized accounting value is
+ * plausible. They shared a constant, so raising the runtime limit alone would make recovery reject the marker of
+ * every task that legitimately copied more than the old value — turning a crash during a large task into an
+ * unrecoverable one. This is the same dual-purpose shape as the 100,000-entry ceiling, and is split the same way
+ * (Hendry's split decision for that ceiling, 2026-10-24, applied to its second instance).
+ *
+ * It rose *together with* the runtime limit — raising it alone would have let recovery accept values no task
+ * could write; lowering the runtime limit alone would make recovery reject its own markers. State written under §5.1's
+ * `shadow-state-v2/` root is never read by an older desktop, so lifting both is safe for rollback (§17).
+ */
+export declare const MAX_PERSISTED_PHYSICAL_COPY_BYTES: number;
+/**
+ * Hashing ceilings — **retired by §5.6** (they were 256 MiB per tracked file and 2 GiB per tracked folder, which
+ * refused ordinary media-heavy folders outright). Every reader hashes in streamed chunks of at most 1 MiB with
+ * constant memory and an fd-stable `fstat` check, so these bounded only TIME, never memory. Hendry's SB-15 decision
+ * (2026-10-24, option A) keeps the clone path's three authentication reads; a very large folder therefore starts
+ * slowly instead of being refused. They remain as the largest value the readers accept.
+ */
 export declare const MAX_TRACKED_FILE_LOGICAL_BYTES: number;
 export declare const MAX_TRACKED_WORKSPACE_LOGICAL_BYTES: number;
 /** Metadata is bounded independently of content bytes (zero-byte files still cost memory/inodes). */
-export declare const MAX_TRACKED_FILE_COUNT = 100000;
+/**
+ * The shadow path's tracked-entry ceilings point at the **traversal** constant, not the orchestration one
+ * (Hendry's split decision, 2026-10-24; see `bounded-directory.ts`). The value is unchanged, so every current
+ * consumer — including `snapshot-merge.ts` and `verification-gates/diff-sanity.ts`, whose own caps are Slice 2
+ * — keeps exactly the bound it has today. What changes is which constant retires when §5.2's walk supplies the
+ * count: the traversal one, leaving `durable-store.ts`'s guards on persisted records untouched.
+ */
+export declare const MAX_TRACKED_FILE_COUNT = 5000000;
 export declare const MAX_TRACKED_PATH_BYTES: number;
+/**
+ * The bound on a CHANGE SET — reviewed bundles, merge plans and diff-sanity budgets (`snapshot-merge.ts`,
+ * `verification-gates/diff-sanity.ts`). §5.6 lifts these in Slice 2 ("replaced by streaming iteration over the
+ * sharded change manifest"), so they keep the historical value here, under their own name, while the traversal
+ * ceiling above rises in Slice 1 (P63 SB-33).
+ */
+export declare const MAX_CHANGE_SET_FILE_COUNT = 100000;
+export declare const MAX_CHANGE_SET_PATH_BYTES: number;
 /** Reviewed text is intentionally bounded before any whole-file decode/read. */
 export declare const MAX_REVIEW_FILE_BYTES: number;
 export declare const MAX_PROMOTION_PREIMAGE_AGGREGATE_BYTES: number;
@@ -124,6 +176,21 @@ export interface ShadowStateFileV2 {
         hash: string | null;
         mode?: number | null;
     }>;
+    /**
+     * §5.2/§5.6: when present, `baseline` is stored in these attested shards and written to disk as `[]`; every
+     * reader expands it before validation (`shadow-baseline-shards.ts`). v2 state root only.
+     */
+    baselineRecord?: import('./shadow-baseline-shards').BaselineRecord;
+    /**
+     * Stage 2 R1-F1: baseline entries added or changed AFTER `baselineRecord` was written (capture adds every new
+     * path with a null baseline). The shards are immutable, so these travel inline; expansion lays them over the
+     * shards. Present only with `baselineRecord`.
+     */
+    baselineDelta?: Array<{
+        path: string;
+        hash: string | null;
+        mode?: number | null;
+    }>;
     /** Exact intended post-images, present while/after promotion for crash reconciliation. */
     promotePostHashes?: Array<{
         path: string;
@@ -216,12 +283,75 @@ export type PreTaskModes = Map<string, number | null>;
 export interface ShadowEnv {
     /** @deprecated Compatibility-only; filesystem snapshots do not use Git retries. */
     sleep?: (ms: number) => Promise<void>;
-    /** Override the per-task state dir root (default `~/.codevibe/shadow-state`). */
+    /** Override the per-task state dir root (default `~/.codevibe/shadow-state-v2`, §5.1). */
     stateRootDir?: string;
     /** Override the process owner root (default `~/.codevibe/process-owners`). */
     ownerRootDir?: string;
-    /** Override the shadow temp-dir root (default `os.tmpdir()`). */
+    /**
+     * Override the copy root. The default is paired with the state root (`shadow-roots.ts`): the §5.1 platform copy
+     * location for the v2 state root, `os.tmpdir()` for the legacy root and for any caller-chosen state root.
+     */
     shadowRootDir?: string;
+    /**
+     * @internal Replaces the legacy (2.0.77) root pair that production enumerators scan as their second pass
+     * (`shadow-roots.ts`), so tests can exercise that pass with temporary directories instead of `os.tmpdir()`.
+     */
+    legacyRoots?: {
+        stateRootDir: string;
+        shadowRootDir: string;
+    };
+    /**
+     * @internal The other copy roots sharing this pass's state root (`shadow-roots.ts` SB-22). Set only by a v2 pass;
+     * a marker naming one of them is left to that root's pass.
+     */
+    siblingShadowRoots?: string[];
+    /** @internal Run promotion through §9.3's no-link engine on a volume that has links (SP-C's "forced copy"). */
+    forceNoLinkApply?: {
+        mode: 'nolink';
+        modesTracked?: boolean;
+        inodeStable?: boolean;
+        linkVolume?: boolean;
+    };
+    /** @internal Per-path deterministic controls for the no-link engine (crash points, seams). */
+    noLinkApplyTest?: (rel: string) => {
+        crashAt?: string;
+        crashAfter?: 'prepared' | 'moved' | 'placing' | 'restoring' | 'restoring-link' | 'pending-restore' | 'create-conflict' | 'done';
+        seams?: string[];
+        failAfterReservation?: number;
+        failReservationCleanup?: number;
+        onSeam?: (name: string, parentDir: string) => Promise<void>;
+    } | undefined;
+    /** @internal Test injection: `/proc/self/mountinfo` text for the drvfs apply refusal (SB-51), and its platform. */
+    applyMountinfo?: {
+        mountinfo: string;
+        platform: NodeJS.Platform;
+    };
+    /** @internal Control runs only: clone file by file, as before §5.3 batching (SB-36). */
+    disableDarwinBatchClones?: boolean;
+    /**
+     * @internal Materializer helpers per snapshot create (P63 SB-45, 1–16). Default
+     * {@link DEFAULT_MATERIALIZER_LANES}; 1 is the sequential copy exactly as shipped.
+     */
+    materializerLanes?: number;
+    /** @internal Lower the inline-baseline threshold so tests exercise sharded markers (default 8 MiB). */
+    baselineInlineMaxBytes?: number;
+    /** @internal Test injection for §5.5's free-space check (`statfs` of the copy location). */
+    copySpaceStatfs?: (path: string) => Promise<{
+        bavail: number | bigint;
+        bsize: number | bigint;
+        blocks: number | bigint;
+    }>;
+    /** @internal Test injection for §5.1's copy-location probes (`shadow-roots.ts` `CopyLocationChoiceProbe`). */
+    copyRootProbe?: {
+        platform?: NodeJS.Platform;
+        home?: string;
+        xdgCacheHome?: string | undefined;
+        isMemoryBacked?: (existingPath: string) => Promise<boolean>;
+        uid?: number;
+        statfsType?: (p: string) => Promise<number>;
+        devOf?: (p: string) => Promise<number>;
+        volumesDir?: string;
+    };
     /** Optional cancellation signal to bound sweep execution. */
     signal?: AbortSignal;
     /** Optional helper timeout in milliseconds for subprocess operations. */
@@ -337,7 +467,15 @@ export interface TrackBranchSpec {
     /** The pinned group base commit the branch is created at. */
     baseSha: string;
 }
+/**
+ * §5.1: Slice 1+ task state lives in `~/.codevibe/shadow-state-v2/`, a root the 2.0.77 compatibility floor never
+ * reads (§17). Tasks created by 2.0.77 and earlier stay in {@link legacyStateRoot} and are still recovered from it.
+ */
 export declare function defaultStateRoot(): string;
+/** The state root of 2.0.77 and earlier. Read for recovery of those tasks only; new tasks never write here. */
+export declare function legacyStateRoot(): string;
+/** The home directory every default root is derived from (test-overridable through `CODEVIBE_HOME_OVERRIDE`). */
+export declare function shadowHomeDir(): string;
 export declare function hashContent(content: string): string;
 export declare function openAnchoredDirectory(parent: string): Promise<fs.FileHandle>;
 export declare function fsyncDirectory(dir: string): Promise<void>;

package/dist/local-executor/shadow-recovery.d.ts

@@ -50,6 +50,14 @@ export interface RecoveredShadow {
     cleanupBlocked?: boolean;
     cleanupOwners?: ProcessCleanupOwner[];
     unresolvedAuthorityRetention?: UnresolvedBundlePublicationRetention;
+    /**
+     * The root pair whose scan found this shadow (§17: v2 or 2.0.77). Reopening uses it, so a legacy task is
+     * revalidated against the legacy roots rather than against the caller's defaults.
+     */
+    rootPair?: {
+        stateRootDir: string;
+        shadowRootDir: string;
+    };
 }
 /**
  * Read every durable per-task shadow marker under the state root. The reconnect/
@@ -97,7 +105,18 @@ export declare function reclaimDisplacedShadow(record: DisplacedShadowMarkerReco
     snapshotIncarnations?: SnapshotIncarnationIndex | null;
 }): Promise<'reaped' | 'retained'>;
 export declare function reconcileDisplacedSnapshots(records: readonly DisplacedShadowMarkerRecord[], keepTaskIds: ReadonlySet<string>, ttlMs: number, now: number, physicalCopyScope: string, env: ShadowEnv, reaped: string[], retained: string[], snapshotIncarnations: SnapshotIncarnationIndex | null): Promise<void>;
+/**
+ * Every recoverable shadow on this machine: the v2 roots, then the 2.0.77 roots (§17), each scanned as its own
+ * self-consistent pair. A v2 root of a format this desktop does not know is list-only, so it is not offered for
+ * recovery at all — recovery acts on what it is given.
+ */
 export declare function listRecoverableShadows(env?: ShadowEnv): Promise<RecoveredShadow[]>;
+/** `env` pinned to one root pair, so every default inside a pass resolves to that pair and nothing else. */
+export declare function pairEnv(env: ShadowEnv, pass: {
+    stateRootDir: string;
+    shadowRootDir: string;
+    siblingShadowRoots?: string[];
+}): ShadowEnv;
 /**
  * Join or recover every known atomic writer owned by the supplied task ids
  * before strict teardown inventory. This is a mutating reconciliation step,
@@ -119,19 +138,46 @@ export interface ShadowCleanupResidue {
  */
 export declare function listShadowCleanupResidue(taskIds: ReadonlySet<string>, env?: ShadowEnv): Promise<ShadowCleanupResidue[]>;
 export declare function reapCrashedStateArtifacts(env: ShadowEnv): Promise<void>;
+export declare function sealSnapshotTreeDurably(snapshotRoot: string, snapshotRootAuthority: WorkspaceRootAuthority, env: ShadowEnv): Promise<void>;
+export declare function createCopyShadow(workingDir: string, shadowDir: string, sourceRootAuthority: WorkspaceRootAuthority, copyFile: (source: string, destination: string, maxLogicalBytes?: number) => Promise<MaterializedFileMetadata>, excludedRoots?: readonly string[], batchClones?: DarwinBatchClones, 
 /**
- * Create a Git-independent filesystem snapshot: walk `workingDir` excluding
- * repository metadata, secrets, caches, and generated output. Source files and
- * private dependency inputs use clone-or-bounded-copy materialization; only
- * source files enter the promotable tracked set.
+ * P63 SB-45: several materializer lanes (a {@link WorkspaceMaterializerPool}'s) to copy directories in parallel.
+ * Each lane brings its own batch clones. Absent, `copyFile` / `batchClones` are the single lane.
  */
-export declare function sealSnapshotTreeDurably(snapshotRoot: string, snapshotRootAuthority: WorkspaceRootAuthority, env: ShadowEnv): Promise<void>;
-export declare function createCopyShadow(workingDir: string, shadowDir: string, sourceRootAuthority: WorkspaceRootAuthority, copyFile: (source: string, destination: string, maxLogicalBytes?: number) => Promise<MaterializedFileMetadata>, excludedRoots?: readonly string[]): Promise<{
+lanes?: readonly CopyLane[]): Promise<{
     tracked: Set<string>;
     metadata: Map<string, MaterializedFileMetadata>;
 }>;
+/**
+ * Recursively copy regular files from `srcRoot/relDir` into `dstRoot/relDir`,
+ * excluding `.git`/`node_modules` directories + secret-deny-list files.
+ * Populates `tracked` with the RELATIVE path of every copied regular file.
+ * `excludedRoots` must be subtrees reachable FROM the walk — an ancestor of
+ * `srcRoot` would exclude everything (`createCopyShadow` filters those out).
+ */
+type CopyFileFn = (source: string, destination: string, maxLogicalBytes?: number) => Promise<MaterializedFileMetadata>;
+/** P63 SB-45: one materializer lane — its copy and, on macOS, the batch clones that must use the same helper. */
+export interface CopyLane {
+    copyFile: CopyFileFn;
+    batchClones?: DarwinBatchClones;
+}
+/** §5.3 batch-clone hooks a materializer session provides on macOS (`WorkspaceMaterializerSession`). */
+export interface DarwinBatchClones {
+    prepare(relativeDir: string, names: readonly string[]): Promise<unknown>;
+    finish(relativeDir: string): Promise<void>;
+}
 /** List every regular file under the shadow (RELATIVE), excluding excluded dirs + build-env. */
-export declare function listShadowRegularFiles(shadowDir: string, shadowRootAuthority: WorkspaceRootAuthority): Promise<string[]>;
+/** §7.1: a copy file's stat tuple, as one comparable string. ctime cannot be set by an unprivileged process. */
+export declare function copyStatTuple(stat: {
+    size: bigint;
+    mtimeNs: string;
+    ctimeNs: string;
+    ino: string;
+    mode: string;
+}): string;
+export declare function listShadowRegularFiles(shadowDir: string, shadowRootAuthority: WorkspaceRootAuthority, 
+/** §7.1: when given, receives every listed file's stat tuple (from the same isolated enumeration — no extra I/O). */
+statsOut?: Map<string, string>): Promise<string[]>;
 type PathBudget = MetadataBudget;
 export declare function createPathBudget(): PathBudget;
 export declare function assertPathCollectionBounds(paths: readonly string[], label: string): void;
@@ -282,6 +328,11 @@ interface RegisteredShadowRoot extends AnchoredFsIdentity {
     version?: 1;
     canonicalPath?: string;
     birthtimeNs?: string;
+    /**
+     * Stage 1 R1-F2: the root is provably gone (FU-1's inode proof) but is kept because one of its markers is
+     * recovery authority. Its bytes count as reclaimed; the entry retires once no marker is authority any more.
+     */
+    vanished?: true;
 }
 /**
  * FU-1 — a registered physical-copy root whose pathname is gone and whose bytes could NOT be proven reclaimed.
@@ -293,6 +344,20 @@ interface RegisteredShadowRoot extends AnchoredFsIdentity {
  * two paths in full — desktop, hosted events and durable diagnostics — is FU1-D2, an owner decision made with the
  * trade-off stated: they are CodeVibe-registered root paths, never raw error text and never user content.
  */
+/**
+ * Stage 1 R1-F2: a per-volume copy root (`<volume root>/.codevibe-shadows-<uid>`, SB-22) that is missing because its
+ * drive is not mounted. Only that exact name shape counts, so a vanished temporary or configured root keeps the
+ * shipped FU-1 reconcile. The drive is away when the volume root is missing, or (Stage 1 R2-N1) when it is still
+ * there as a plain folder on the same device as the folder holding it — a mount point left behind empty, which is
+ * what an unmount under a folder that is not `/Volumes` (or a stale `/Volumes` entry) leaves — or (Stage 1 R3-N5)
+ * when a DIFFERENT drive is mounted under the same name: its device is not the registered root's device.
+ */
+export declare function isOnUnmountedVolume(copyRoot: string, registeredDev?: string): Promise<boolean>;
+/**
+ * Stage 1 R1-F2: whether a state marker is recovery authority that a reconcile must never delete — APPLYING, or an
+ * instance with an open §9.3 journal entry. Unreadable counts as authority (fail closed).
+ */
+export declare function markerIsRecoveryAuthority(markerFile: string): Promise<boolean>;
 export declare class StaleShadowRootError extends Error {
     readonly stalePath: string;
     readonly registryPath: string;

package/dist/local-executor/shadow-roots.d.ts

@@ -0,0 +1,126 @@
+import { type ShadowEnv } from './shadow-protocol';
+/** §5.1: the v2 root's format file. */
+export declare const SHADOW_STATE_FORMAT_FILE = "FORMAT";
+export declare const SHADOW_STATE_FORMAT_VERSION = 2;
+export declare const SHADOW_STATE_FORMAT_BODY: string;
+export type ShadowRootGeneration = 'v2' | 'legacy' | 'configured';
+export interface ShadowRootPair {
+    stateRootDir: string;
+    shadowRootDir: string;
+    generation: ShadowRootGeneration;
+    /**
+     * The other copy roots sharing this pass's state root. A marker naming one of them belongs to that root's pass,
+     * so this pass skips it instead of reporting it as broken (SB-22).
+     */
+    siblingShadowRoots?: string[];
+}
+/** A copy location §5.1 refuses: every candidate is memory-backed, so a copy there would vanish at reboot. */
+export declare class CopyLocationRefusedError extends Error {
+    readonly candidates: string[];
+    readonly code = "ECOPYLOCATION";
+    constructor(candidates: string[]);
+}
+export interface CopyLocationProbe {
+    platform?: NodeJS.Platform;
+    home?: string;
+    xdgCacheHome?: string | undefined;
+    /** Injected in tests; production asks `statfs`. */
+    isMemoryBacked?: (existingPath: string) => Promise<boolean>;
+}
+/**
+ * §5.1's copy location for a project on the home data volume.
+ *
+ * - macOS: `~/Library/Caches/CodeVibe/shadows/` — every shipped Seatbelt profile works there, and Time Machine
+ *   excludes it [SP-A].
+ * - Linux / WSL2: `${XDG_CACHE_HOME:-~/.cache}/codevibe/shadows/` when that is a disk filesystem, otherwise
+ *   `~/.local/state/codevibe/shadows/`, otherwise refused. Fedora's `/tmp` is tmpfs [A1-L], which is why
+ *   `os.tmpdir()` is never used.
+ *
+ * Other platforms keep the shipped `os.tmpdir()`: CodeVibe supports macOS, Linux and WSL2 only.
+ */
+export declare function defaultCopyLocation(probe?: CopyLocationProbe): Promise<string>;
+/** The mount point holding `p`: its highest ancestor still on `p`'s device. */
+export declare function mountPointOf(p: string, devOf?: (p: string) => Promise<number>): Promise<string>;
+/** §5.1: a macOS project on another APFS volume is copied beside it, so clones work [A1c]. */
+export declare function projectVolumeCopyRoot(volumeRoot: string, uid: number): string;
+export interface CopyLocationChoice {
+    copyRoot: string;
+    /** Why — for the task log, so a full copy into the home location is explained rather than mysterious. */
+    basis: 'home-volume' | 'project-volume' | 'no-clone-volume' | 'linux-same-fs' | 'linux-default' | 'other-platform';
+}
+export interface CopyLocationChoiceProbe extends CopyLocationProbe {
+    uid?: number;
+    /** Injected in tests; production asks `statfs`. */
+    statfsType?: (p: string) => Promise<number>;
+    /** Injected in tests to place a folder on "another volume"; production asks `stat`. */
+    devOf?: (p: string) => Promise<number>;
+    /** Where macOS mounts other volumes; injected in tests. */
+    volumesDir?: string;
+}
+/**
+ * §5.1, chosen per task before copying.
+ *
+ * macOS — a project on the home data volume uses `~/Library/Caches/CodeVibe/shadows/`. A project on another APFS
+ * volume uses `<volume root>/.codevibe-shadows-<uid>/`, so clones work [A1c]. A project on a no-clone volume (exFAT,
+ * FAT, HFS+, …) uses the home location with a full copy (§5.5). Either way the project volume never hosts locks or
+ * state [A1d]: state is always the v2 root on the home filesystem.
+ *
+ * Linux / WSL2 — the first disk-backed candidate (`defaultCopyLocation`), except that a btrfs/XFS project prefers a
+ * candidate on its own filesystem, so clones work. When neither candidate shares that filesystem the task takes the
+ * first disk-backed one with a free-space-gated full copy (§5.5) rather than being refused (ASSUMPTIONS SB-24).
+ */
+export declare function chooseCopyLocation(workingDir: string, probe?: CopyLocationChoiceProbe): Promise<CopyLocationChoice>;
+/**
+ * Every copy root a task under the v2 state root can be in: the home location(s), plus — on macOS — each
+ * `/Volumes/<volume>/.codevibe-shadows-<uid>/` present. A project-volume root exists only while it holds tasks,
+ * so it is found by listing what is mounted rather than by a registry that a crash could leave stale.
+ */
+export declare function v2CopyRoots(probe?: CopyLocationChoiceProbe): Promise<string[]>;
+/** The copy root paired with `stateRootDir` (module comment: Pairing). */
+export declare function pairedShadowRoot(stateRootDir: string, probe?: CopyLocationProbe): Promise<string>;
+/** The one pair a per-task operation uses. Explicit roots always win. */
+export declare function resolveShadowRoots(env?: Pick<ShadowEnv, 'stateRootDir' | 'shadowRootDir' | 'copyRootProbe'>, probe?: CopyLocationProbe | undefined): Promise<{
+    stateRootDir: string;
+    shadowRootDir: string;
+}>;
+/**
+ * The pairs an enumerator scans (module comment: Two passes).
+ *
+ * The legacy pass is added only when the caller asked for the production state root and left the copy root to
+ * its default — the two conditions under which "every task on this machine" is meant. A caller that pinned either
+ * root gets exactly the pair it pinned, which keeps every test and custom configuration single-pass.
+ *
+ * `legacyRoots` exists for tests: it replaces the legacy pair so a test can exercise the second pass with
+ * temporary directories instead of the real `os.tmpdir()`.
+ */
+export declare function shadowRootPasses(env?: Pick<ShadowEnv, 'stateRootDir' | 'shadowRootDir' | 'legacyRoots' | 'copyRootProbe'>, probe?: CopyLocationChoiceProbe | undefined): Promise<ShadowRootPair[]>;
+export type StateRootFormat = 
+/** No format file yet: this desktop may create it. */
+{
+    kind: 'absent';
+}
+/** A zero-length FORMAT — only a crash of the pre-R1-F5 writer leaves one; this desktop rewrites it atomically. */
+ | {
+    kind: 'empty';
+}
+/** The format this desktop writes. */
+ | {
+    kind: 'current';
+}
+/**
+ * A format this desktop does not know — written by a newer CodeVibe, or damaged. §17: the whole v2 root is
+ * list-only, so nothing in it is resumed, applied or removed.
+ */
+ | {
+    kind: 'unknown';
+    detail: string;
+};
+/** Read a v2 state root's `FORMAT` without following a symlink. */
+export declare function readStateRootFormat(stateRootDir: string): Promise<StateRootFormat>;
+/**
+ * Write the v2 root's `FORMAT` before the first task state, durably, or confirm the one there is ours.
+ * Throws when the root holds a format this desktop does not know: a task must not be created into it.
+ */
+export declare function ensureStateRootFormat(stateRootDir: string): Promise<void>;
+/** Whether an enumerator may act on a pass. A v2 root of unknown format is list-only (§17). */
+export declare function passIsActionable(pass: ShadowRootPair): Promise<boolean>;

package/dist/local-executor/shadow-start-record.d.ts

@@ -0,0 +1,116 @@
+import { type MetadataBudget } from './bounded-directory';
+import { type StartRecordMargin } from './shadow-fs-margins';
+/** §5.2: "Records are written as sharded JSON-lines files (50,000 entries per shard …)". */
+export declare const START_RECORD_SHARD_ENTRIES = 50000;
+/** The on-disk format version, so an older desktop refuses a record it does not know (§17). */
+export declare const START_RECORD_VERSION = 1;
+export type StartRecordEntryType = 'file' | 'dir' | 'symlink' | 'fifo' | 'socket' | 'blockDevice' | 'charDevice' | 'unknown';
+export interface StartRecordEntry {
+    path: string;
+    type: StartRecordEntryType;
+    size: string;
+    mtimeNs: string;
+    ctimeNs: string;
+    ino: string;
+    dev: string;
+    uid: string;
+    gid: string;
+    mode: string;
+    /** True when `mtime >= T0 - margin`: this entry must be fingerprinted now, not deferred to §7.3. */
+    racy?: true;
+}
+export interface StartRecordShard {
+    name: string;
+    sha256: string;
+    entries: number;
+    /** Stage 2 R1-F8: the exact size, checked before the shard is read. */
+    bytes?: number;
+}
+export interface StartRecordManifest {
+    startRecord: typeof START_RECORD_VERSION;
+    /** Taken when the walk starts (§5.2). */
+    t0Ns: string;
+    marginMs: number;
+    marginBasis: StartRecordMargin['basis'];
+    /**
+     * Whether `ino` may be used as a file's identity later. False on FAT, exFAT and drvfs — §9.3 uses inode
+     * identity only where the apply-time probe found it stable, and only within the same boot and mount.
+     */
+    inodeIsIdentity: boolean;
+    entryCount: number;
+    racyCount: number;
+    shards: StartRecordShard[];
+}
+export interface WriteStartRecordOptions {
+    /** The user's folder. Walked, never written. */
+    sourceRoot: string;
+    /** The task's state directory (§5.1: `~/.codevibe/shadow-state-v2/<task>/`). Shards are written here. */
+    stateDir: string;
+    budget?: MetadataBudget;
+    /** Supplied by `probeTimestampGranularityMs` on the copy location; omitted means the fail-closed margin. */
+    probedGranularityMs?: number;
+    signal?: AbortSignal;
+    /**
+     * Directory NAMES never descended into (recorded as entries, not walked) — the same dependency/repository trees
+     * the copy skips (`SHADOW_SKIP_DIRS`), so the record never costs more than the copy it describes.
+     */
+    skipDirNames?: ReadonlySet<string>;
+    /** Absolute directories never descended into — CodeVibe's own copy/state roots when they sit inside the folder. */
+    skipAbsoluteDirs?: readonly string[];
+}
+export interface WalkedStartRecord {
+    t0Ns: bigint;
+    margin: StartRecordMargin;
+    entries: StartRecordEntry[];
+    racyCount: number;
+}
+/**
+ * Walk `sourceRoot` once with `lstat` only and return the record IN MEMORY. T0 is taken before a single directory
+ * is read. Persisting is separate ({@link persistStartRecord}), so a caller can take T0 before a copy and write the
+ * record only once the task's marker exists — a failed create then leaves no record behind (P63 SB-41).
+ */
+export declare function walkStartRecord(opts: Omit<WriteStartRecordOptions, 'stateDir'>): Promise<WalkedStartRecord>;
+/**
+ * Persist a walked record as FLAT files in `stateDir`: `<prefix>-NNNNN.jsonl` shards (each `O_EXCL`, fsynced) and
+ * `<prefix>.manifest.json`. Flat because a task's state container must be — a directory there could conceal a
+ * relocated marker, so strict audits reject one (P63 SB-41).
+ */
+export declare function persistStartRecord(stateDir: string, walked: WalkedStartRecord, filePrefix?: string): Promise<StartRecordManifest>;
+/** Walk `sourceRoot` once and write the sharded start record into `stateDir` (walk + persist). */
+export declare function writeStartRecord(opts: WriteStartRecordOptions): Promise<StartRecordManifest>;
+/**
+ * Total bytes of regular files under `sourceRoot`, by the same `lstat`-only walk as the start record, reading
+ * no contents and following no symlinks.
+ *
+ * This is §5.5's `bytesToCopy`. It deliberately does NOT apply §5.7's exclusions (hidden paths, dependency trees,
+ * rebuild outputs), so it can only over-count what a full copy will write — which makes the free-space check
+ * demand more headroom, never less. Under-counting is the direction that would admit a copy that then fails with
+ * ENOSPC partway through.
+ */
+export declare function measureRegularFileBytes(sourceRoot: string, opts?: {
+    budget?: MetadataBudget;
+    signal?: AbortSignal;
+}): Promise<{
+    bytes: number;
+    files: number;
+}>;
+export interface FolderChangesSinceStart {
+    changed: number;
+    created: number;
+    deleted: number;
+    /** Up to 20 example paths, for the task log (Slice 2's review INDEX lists them all). */
+    examples: string[];
+}
+/**
+ * §7.4: re-walk the user's folder with the start record's own rules and count every entry that differs from it —
+ * the user's own edits during the task, which reviewers should know about ("your folder changed during the task:
+ * N files"). Compares `type, size, mtimeNs, ctimeNs` and, where the record says inodes are identity, `ino`.
+ */
+export declare function folderChangesSinceStart(opts: {
+    sourceRoot: string;
+    /** The state directory holding the flat record, and the record's file prefix. */
+    stateDir: string;
+    filePrefix: string;
+    skipDirNames?: ReadonlySet<string>;
+    skipAbsoluteDirs?: readonly string[];
+}): Promise<FolderChangesSinceStart>;

package/dist/local-executor/shadow-volume-probe.d.ts

@@ -0,0 +1,42 @@
+export type ApplyMode = 'link' | 'nolink';
+export interface VolumeCapabilities {
+    version: 1;
+    mode: ApplyMode;
+    modesTracked: boolean;
+    inodeStable: boolean;
+    bootId: string;
+    dev: string;
+    /** What each step returned, for the task log and the reviewer packet. */
+    steps: Record<'exclusiveCreate' | 'link' | 'chmod' | 'rename' | 'dirFsync' | 'inodes', string>;
+}
+/** Probe entry names are CodeVibe's and token-bearing, so recovery can never mistake a user file for one. */
+export declare const PROBE_ENTRY_RE: RegExp;
+export declare function newProbeEntryName(): string;
+/** Linux `/proc/sys/kernel/random/boot_id`; macOS `kern.boottime`. */
+export declare function bootIdentity(platform?: NodeJS.Platform): Promise<string>;
+/**
+ * Probe `projectRoot`. `journalProbeEntry` must durably record the name before this function creates anything.
+ * Never throws for an unsupported capability — that is a result. Throws only when the probe cannot run at all
+ * (the root is not writable), which the caller reports as an apply error before any user file is touched.
+ */
+export declare function probeVolumeCapabilities(projectRoot: string, journalProbeEntry: (name: string) => Promise<void>, opts?: {
+    platform?: NodeJS.Platform;
+}): Promise<VolumeCapabilities>;
+/** Remove the probe entry `name` and its two derived names — exactly those, and only if they are CodeVibe's. */
+export declare function removeJournaledProbeEntry(projectRoot: string, name: string): Promise<void>;
+/** §9.1: inodes count as identity only with the flag, in the same boot, on the same device. */
+export declare function inodesTrustedNow(journaled: Pick<VolumeCapabilities, 'inodeStable' | 'bootId' | 'dev'>, projectRoot: string, platform?: NodeJS.Platform): Promise<boolean>;
+/**
+ * P63 SB-51 (Hendry, 2026-10-24: "fail closed on drvfs"): applying into a Windows drive from WSL2 is refused in
+ * Slice 1 — no WSL2 host was available to qualify §9.3 on a real drvfs volume. Nothing is applied; the copy is kept.
+ */
+export declare const DRVFS_APPLY_REFUSAL = "Applying into a Windows drive from WSL2 (drvfs) isn't supported yet \u2014 nothing was applied; the task's copy is kept.";
+/**
+ * True when `target` lives on a WSL drvfs mount: the longest `/proc/self/mountinfo` mount point containing its
+ * real path has filesystem type `drvfs` (WSL1, some WSL2 builds) or `9p` with `aname=drvfs` (WSL2). Only Linux
+ * has drvfs; elsewhere this is false without reading anything.
+ */
+export declare function isDrvfsPath(target: string, opts?: {
+    mountinfo?: string;
+    platform?: NodeJS.Platform;
+}): Promise<boolean>;