@quantiya/codevibe-core 2.0.83 → 2.0.85

package/dist/local-executor/bounded-directory.d.ts

@@ -1,8 +1,29 @@
 import type { Dirent } from 'node:fs';
 import type { WorkspaceRootAuthority } from './workspace-authority.js';
-/** Shared metadata ceilings for every CodeVibe-owned filesystem traversal. */
+/**
+ * Ceiling for **orchestration records** — a retained team specification's work items, briefs and attachments,
+ * and a track-bundles record (`durable-store.ts`). It is a memory guard on persisted input and has nothing to
+ * do with walking a folder, despite the name it has carried.
+ *
+ * §5.6 of the workspace-hardening design lists "100,000 entries | `bounded-directory.ts:17` | removed" as a
+ * Slice 1 item, which reads as though this constant were traversal-only. It is not: removing it would delete
+ * the orchestration guards too. Hendry's decision, 2026-10-24, was to **split the constant** —
+ * {@link MAX_TRAVERSAL_ENTRY_COUNT} now carries the traversal meaning and this one keeps its original value
+ * and its orchestration consumers.
+ */
 export declare const MAX_METADATA_ENTRY_COUNT = 100000;
 export declare const MAX_METADATA_PATH_BYTES: number;
+/**
+ * Ceiling for a CodeVibe-owned **filesystem traversal**.
+ *
+ * §5.6 retires the historical 100,000-entry / 16 MiB-path cap: a folder's size is computed by the walk and the
+ * marker no longer holds every path inline once it is large (`shadow-baseline-shards.ts`). What remains is a
+ * memory sanity bound, not a product limit: every walked path is held in memory (≈ 200 bytes each), so 5,000,000
+ * entries / 1 GiB of path bytes keeps a pathological tree from exhausting the desktop. A folder past it is refused
+ * with this reason rather than silently truncated (P63 SB-33).
+ */
+export declare const MAX_TRAVERSAL_ENTRY_COUNT = 5000000;
+export declare const MAX_TRAVERSAL_PATH_BYTES: number;
 export interface MetadataBudget {
     entries: number;
     utf8PathBytes: number;
@@ -40,6 +61,15 @@ export interface BoundedDirectoryStat {
     mtimeNs: string;
     ctimeNs: string;
     nlink: string;
+    /**
+     * Ownership and mode, carried in the same isolated enumeration request as the rest of the tuple so the §5.2
+     * start record needs no second `lstat` per entry. The record's fields are
+     * `type, size, mtimeNs, ctimeNs, ino, dev, uid, gid, mode`, and these three completed that set.
+     * Decimal strings, like `dev`/`ino`/`nlink`, because the helper reads them from a `bigint` `lstat`.
+     */
+    uid: string;
+    gid: string;
+    mode: string;
 }
 /** Metadata captured in the same isolated enumeration request, when requested. */
 export declare function boundedDirectoryStat(entry: Dirent): BoundedDirectoryStat | undefined;

package/dist/local-executor/nolink-apply.d.ts

@@ -0,0 +1,154 @@
+import { type WorkspaceRootAuthority } from './workspace-authority';
+export type NoLinkOperation = 'replace' | 'create' | 'delete';
+export type NoLinkState = 'prepared' | 'moved' | 'placing' | 'restoring' | 'restoring-link' | 'pending-restore' | 'create-conflict' | 'done';
+export interface NoLinkJournalEntry {
+    version: 1;
+    token: string;
+    op: NoLinkOperation;
+    /** The target's path relative to the workspace root, for reporting; the helper uses only its basename. */
+    path: string;
+    /**
+     * Stage 1 R1-F2: the workspace root the entry belongs to — a record of which folder the step touched. Slice 1
+     * reads entries only through their own task (which knows its folder); no recovery path consumes this field yet
+     * (Stage 1 R2-N2, a recorded Slice 1 deviation). Absent on entries written before this field existed.
+     */
+    workspaceRoot?: string;
+    state?: NoLinkState;
+    reservation?: {
+        ino: string;
+    };
+    rreservation?: {
+        ino: string;
+    };
+    restoreHash?: string;
+    /** Stage 2 R4-F1: the restore copy's mode, checked when a restore is recognised as complete. */
+    restoreMode?: number;
+    oldIdentity?: {
+        dev: string;
+        ino: string;
+    } | null;
+    baseIdentity?: {
+        ino: string;
+        size: string;
+        mtimeNs: string;
+    };
+    kept?: string[];
+    report?: string;
+    timesNotKept?: true;
+    /** Fixed at the first write so recovery replays the same request. */
+    spec: Omit<NoLinkHelperSpec, 'name' | 'token' | 'crashAt' | 'crashAfter' | 'seams' | 'failAfterReservation' | 'failReservationCleanup' | 'failKeptRename' | 'disableFinalGuard'>;
+}
+interface NoLinkHelperSpec {
+    op: NoLinkOperation;
+    name: string;
+    token: string;
+    content?: string;
+    mode?: number;
+    baseHash: string | null;
+    intendedHash: string | null;
+    linkVolume: boolean;
+    inodesTrusted: boolean;
+    modesTracked: boolean;
+    crashAt?: string;
+    crashAfter?: NoLinkState;
+    seams?: string[];
+    failAfterReservation?: number;
+    /** @internal test only: the next N reservation clean-ups after a failed placement fail (the reservation is left). */
+    failReservationCleanup?: number;
+    /** @internal test only: the next N kept-file renames fail AND leave their reservation (§9.3 T30b). */
+    failKeptRename?: number;
+    /** Stage 2 R2-F3: where modes are tracked, the mode the name must still have (the base); null/absent = unchecked. */
+    baseMode?: number | null;
+    /** @internal control-test only: skip the final guard to show what it prevents. */
+    disableFinalGuard?: boolean;
+}
+export interface NoLinkResult {
+    outcome: 'applied' | 'applied-kept' | 'deleted' | 'conflict' | 'pending' | 'error' | 'restored' | 'kept-original' | 'nothing-moved' | 'nothing-placed' | 'original-kept' | 'gone' | 'closed' | 'name-holds-another-file' | 'original-gone';
+    kept: string[];
+    reason?: string;
+    error?: string;
+    putBack?: string;
+    report?: string;
+}
+/**
+ * Durable per-operation journal: one FLAT file per token, `<prefix>-<token>.json`, in `dir` (the task's state
+ * directory, which must stay flat — P63 SB-41).
+ */
+/**
+ * Stage 1 N8: read one of this task's own state files (journal entry, capabilities, probe journal, start-record
+ * manifest) the way the shipped markers are read — never through a symlink, never blocking on a FIFO, and only a
+ * regular file within `maxBytes`. A missing file rejects with its ENOENT, so callers keep their absent-file paths.
+ */
+export declare function readStateFile(file: string, maxBytes?: number): Promise<string>;
+/**
+ * Stage 2 R1-F8: the same read, returning the exact bytes (a shard's hash covers bytes). With `exactBytes` (what the
+ * writer recorded), any other size is refused before a byte is read.
+ */
+export declare function readStateFileBytes(file: string, maxBytes: number, exactBytes?: number, 
+/** @internal test only (R2-F4): runs between the size check and the read. */
+afterStatForTest?: () => Promise<void>): Promise<Buffer>;
+/**
+ * Stage 2 R1-F8: the largest serialized line one shard entry can take — a 4 KiB path JSON-escaped at worst 6× plus
+ * the fixed fields. A shard of N entries is never read past N times this.
+ */
+export declare const MAX_SHARD_LINE_BYTES: number;
+export declare function shardByteBound(entries: number): number;
+/**
+ * Stage 1 R2-F1: the largest journal entry the engine can write. An entry carries the new file's content as base64
+ * (`spec.content`), and a reviewed file may be up to {@link MAX_REVIEW_FILE_BYTES}; the remainder is JSON. Every
+ * journal read uses this bound — a smaller one (the 1 MiB of N8(a)) made an applied file over ~768 KiB unreadable,
+ * so discard failed and a pending step could never be recovered.
+ */
+export declare const NOLINK_JOURNAL_MAX_BYTES: number;
+export declare class NoLinkJournalStore {
+    readonly dir: string;
+    readonly prefix: string;
+    constructor(dir: string, prefix?: string);
+    fileFor(token: string): string;
+    write(entry: NoLinkJournalEntry): Promise<void>;
+    read(token: string): Promise<NoLinkJournalEntry | null>;
+    /**
+     * Every entry not yet `done`. Slice 1 recovers them at every `promote()` — each retry and the startup reconcile
+     * (R1-F1); §9.3's 10-second retry while the desktop runs is not implemented (Stage 1 R2-N2, a recorded deviation).
+     */
+    open(): Promise<NoLinkJournalEntry[]>;
+}
+/** Stage 2 R3-F1: parse + validate one persisted entry; throws `EJOURNAL` for anything that is not exactly one. */
+export declare function parseNoLinkJournalEntry(text: string, token: string): NoLinkJournalEntry;
+/** The token of a `<prefix>-<token>.json` journal file name, or null when the name is not one. */
+export declare function journalTokenOf(name: string, prefix: string): string | null;
+/** The CodeVibe token for one operation: the same 48-hex shape as the link-based helper's `.codevibe-cas-<token>`. */
+export declare function noLinkToken(rootCanonicalPath: string, rel: string, op: NoLinkOperation, baseHash: string | null, intendedHash: string | null): string;
+export interface NoLinkRunOptions {
+    workspaceRoot: string;
+    /**
+     * Stage 1 R1-F3: the workspace root's recorded identity. When given, it is re-checked before the target's parent
+     * is bound, exactly as the link-based helper requires it.
+     */
+    workspaceRootAuthority?: WorkspaceRootAuthority;
+    rel: string;
+    journal: NoLinkJournalStore;
+    helperTimeoutMs?: number;
+    /** @internal deterministic test controls, forwarded to the helper. */
+    test?: Pick<NoLinkHelperSpec, 'crashAt' | 'crashAfter' | 'seams' | 'failAfterReservation' | 'failReservationCleanup' | 'failKeptRename' | 'disableFinalGuard'> & {
+        onSeam?: (name: string, parentDir: string) => Promise<void>;
+    };
+}
+/** Apply one change on a no-link volume. */
+export declare function applyNoLink(opts: NoLinkRunOptions & {
+    op: NoLinkOperation;
+    content?: string;
+    mode?: number;
+    /** Stage 2 R2-F3: the name's base mode, compared by the helper where modes are tracked. */
+    baseMode?: number | null;
+    baseHash: string | null;
+    linkVolume: boolean;
+    inodesTrusted: boolean;
+    modesTracked: boolean;
+}): Promise<NoLinkResult>;
+/** Recover one journaled operation from its last durable state (§9.3 "Crash recovery"). */
+export declare function recoverNoLink(opts: NoLinkRunOptions & {
+    entry: NoLinkJournalEntry;
+    inodesTrusted: boolean;
+}): Promise<NoLinkResult>;
+export {};

package/dist/local-executor/shadow-apply-capabilities.d.ts

@@ -0,0 +1,114 @@
+import { applyNoLink, type NoLinkResult } from './nolink-apply';
+import type { WorkspaceRootAuthority } from './workspace-authority';
+import { type VolumeCapabilities } from './shadow-volume-probe';
+export interface ApplyArtifactNames {
+    probeJournal: string;
+    capabilities: string;
+    /** The §9.3 journal lives FLAT in the state dir, as `nolink-<uuid>-<token>.json` (state containers are flat). */
+    nolinkDir: string;
+    nolinkPrefix: string;
+}
+export declare function applyArtifactNames(stateDir: string, shadowDir: string): ApplyArtifactNames;
+/** §5.2/§7.4: this instance's flat start-record file prefix (`start-record-<uuid>`). */
+export declare function startRecordPrefix(shadowDir: string): string;
+/** Test override: run the no-link path on a volume that has links, as SP-C's "APFS forced copy" did. */
+export interface ForcedApplyCapabilities {
+    mode: 'nolink';
+    modesTracked?: boolean;
+    inodeStable?: boolean;
+    /** drvfs-shaped: no-link state machine with link-based placement. */
+    linkVolume?: boolean;
+}
+export type ResolvedApplyCapabilities = VolumeCapabilities & {
+    linkVolume: boolean;
+};
+/**
+ * The volume's capabilities for this snapshot's apply: read back if this snapshot already probed (a resumed or
+ * recovered promotion never probes twice), otherwise probed now — after approval, never at task start (§9.1).
+ */
+export declare function ensureApplyCapabilities(stateDir: string, shadowDir: string, workspaceRoot: string, forced?: ForcedApplyCapabilities): Promise<ResolvedApplyCapabilities>;
+export declare class NoLinkPendingError extends Error {
+    readonly rel: string;
+    readonly result: NoLinkResult;
+    readonly code = "ENOLINKPENDING";
+    constructor(rel: string, result: NoLinkResult);
+}
+/**
+ * Apply one reviewed file on a no-link volume. Returns true when the name now holds the post-image (applied, or
+ * already applied by an interrupted earlier run), false for a conflict — the link-based helper's contract.
+ */
+export declare function applyFileNoLink(args: {
+    caps: ResolvedApplyCapabilities;
+    stateDir: string;
+    shadowDir: string;
+    workspaceRoot: string;
+    /** R1-F3: re-checked before every no-link step, as the link-based helper does. */
+    workspaceRootAuthority?: WorkspaceRootAuthority;
+    rel: string;
+    /** null = delete. */
+    content: string | null;
+    /**
+     * Stage 1 R1-F4: the mode the placed file must carry where the volume tracks modes (§9.1 `modesTracked`); the
+     * helper sets it on the file it writes. Ignored where modes are untracked (exFAT, FAT, drvfs).
+     */
+    mode?: number | null;
+    expectedHash: string | null;
+    postHash: string | null;
+    currentHash: () => Promise<string | null>;
+    /**
+     * Stage 2 R1-F7: where modes are tracked, the name's current mode and the mode it must have before this step. A
+     * mode-only change has equal content hashes, so "already landed" must also compare the mode.
+     */
+    currentMode?: () => Promise<number | null>;
+    expectedMode?: number | null;
+    onKept?: (rel: string, kept: string[]) => void;
+    test?: Parameters<typeof applyNoLink>[0]['test'];
+}): Promise<boolean>;
+/**
+ * Stage 1 R1-F1: recover EVERY open §9.3 journal entry of this snapshot, whatever its token — before a promotion
+ * attempts anything new. `applyFileNoLink` recovers only the entry of the operation it is about to retry, but a
+ * rollback runs the REVERSE operation (pre- and post-image swapped, so a different token): a reverse step left
+ * `pending-restore` by a failure or a crash would otherwise never be recovered, the user's name would stay empty and
+ * the task would sit in APPLYING for good. This is what every retry and the startup reconcile reach, because both
+ * call `promote()`. Returns the paths still pending (their originals are at a CodeVibe name; APPLYING must stay).
+ * Stage 1 R2-F2: an entry whose recovery throws is reported pending for that path (APPLYING stays, the next attempt
+ * retries it) rather than failing the whole pass; an entry closed without a result to apply goes to `onClosed`.
+ */
+export declare function recoverOpenNoLinkEntries(args: {
+    caps: ResolvedApplyCapabilities;
+    stateDir: string;
+    shadowDir: string;
+    workspaceRoot: string;
+    workspaceRootAuthority?: WorkspaceRootAuthority;
+    onKept?: (rel: string, kept: string[]) => void;
+    onClosed?: (rel: string, result: NoLinkResult) => void;
+    onError?: (rel: string, err: Error) => void;
+}): Promise<string[]>;
+/** Open (not `done`) §9.3 journal entries of this snapshot — non-empty blocks discard. */
+export declare function openNoLinkEntries(stateDir: string, shadowDir: string): Promise<import("./nolink-apply").NoLinkJournalEntry[]>;
+/**
+ * Remove this snapshot's apply artefacts at discard. Refuses while any journal entry is open: that entry may be
+ * the only record of where the user's original is.
+ */
+export declare function retireApplyArtifacts(stateDir: string, shadowDir: string, workspaceRoot?: string): Promise<void>;
+/**
+ * The cleanup paths other than {@link WorkspaceShadow.discard} (a retried DISPOSING discard whose tree is gone, GC,
+ * displaced-snapshot recovery) retire the instance marker themselves. They call this once the marker is gone, just
+ * before removing the task state directory, so the instance's flat records do not keep that directory alive.
+ * Best effort and fail-closed: an open §9.3 journal entry (impossible here — it keeps the marker APPLYING, and no
+ * path disposes an APPLYING marker) or an unreadable record is kept, and the directory removal then simply fails.
+ */
+export declare function retireInstanceRecords(stateDir: string, shadowDir: string): Promise<void>;
+/**
+ * {@link retireInstanceRecords} for a path that knows only the instance's MARKER file (the vanished-root
+ * reconcile, which retires markers naming bytes that cannot exist). The instance UUID comes from the marker name.
+ */
+export declare function retireInstanceRecordsForMarker(markerFile: string): Promise<void>;
+/** Old enough that no create or discard of that instance can still be between its two writes. */
+export declare const ORPHAN_ARTEFACT_MIN_AGE_MS: number;
+/**
+ * Remove instance artefacts whose marker (`shadow-state<uuid>.json`) is gone and that are older than
+ * {@link ORPHAN_ARTEFACT_MIN_AGE_MS}. A `nolink<uuid>/` journal with an OPEN entry is never removed: it may be the
+ * only record of where the user's original is. Returns the names removed.
+ */
+export declare function reapOrphanedInstanceArtefacts(stateDir: string, now?: number): Promise<string[]>;

package/dist/local-executor/shadow-base-hash.d.ts

@@ -0,0 +1,81 @@
+import type { WorkspaceRootAuthority } from './workspace-authority';
+import type { StartRecordEntry, StartRecordManifest } from './shadow-start-record';
+/** Why a base hash could not be established. Every one of these is a conflict, never a silent null. */
+export type BaseHashConflict = 
+/** The start record's tuple no longer matches the file: the user wrote during the task. */
+{
+    kind: 'changed-since-start-record';
+    path: string;
+    field: 'ino' | 'size' | 'mtimeNs' | 'ctimeNs';
+}
+/** The tuple changed across the read itself — a write landed while we were hashing. */
+ | {
+    kind: 'changed-during-read';
+    path: string;
+}
+/** The path is gone from the user's folder. */
+ | {
+    kind: 'absent';
+    path: string;
+}
+/** Present in the record but not a regular file, so it has no content hash (§5.7). */
+ | {
+    kind: 'not-a-regular-file';
+    path: string;
+    type: StartRecordEntry['type'];
+};
+export type BaseHashResult = {
+    ok: true;
+    path: string;
+    sha256: string;
+    mode: number;
+    size: number;
+    fromRacyPrehash?: true;
+} | {
+    ok: false;
+    conflict: BaseHashConflict;
+};
+export interface BaseHashResolverOptions {
+    /** The user's folder. Read-only here. */
+    sourceRoot: string;
+    manifest: StartRecordManifest;
+    /** Every entry of the start record, keyed by its relative path. */
+    entries: Map<string, StartRecordEntry>;
+    workspaceRootAuthority?: WorkspaceRootAuthority;
+    maxBytes: number;
+    /**
+     * Hashes computed at start for *racy* entries (§5.2). Those files were already fd-stable-hashed because a
+     * same-size rewrite inside one timestamp tick is invisible to `stat`, so re-deriving them here would be both
+     * wasteful and wrong — their pre-task bytes may no longer be on disk.
+     */
+    racyPrehashes?: Map<string, string>;
+}
+/**
+ * Resolves and caches §7.3 base hashes.
+ *
+ * Caching matters for correctness as much as speed: a second resolution of the same path could observe a
+ * different file, and two different `base_hash` values for one path inside a single task would make the later
+ * compare-and-swap non-deterministic.
+ */
+export declare class BaseHashResolver {
+    private readonly opts;
+    private readonly cache;
+    constructor(opts: BaseHashResolverOptions);
+    /** Paths come from the START RECORD, so callers never iterate a partially-filled hash map (SB-13). */
+    allPaths(): IterableIterator<string>;
+    entry(path: string): StartRecordEntry | undefined;
+    /** How many paths the record holds, which is the count §5.6 shows as progress instead of capping. */
+    get recordedEntryCount(): number;
+    resolve(path: string): Promise<BaseHashResult>;
+    private compute;
+    /**
+     * Compare the recorded tuple with what the read observed.
+     *
+     * The inode is compared **only where the record says it is an identity** — §5.2 does not use it on FAT,
+     * exFAT or drvfs, because a truncate-and-rewrite gets a new inode there and an exFAT inode read back after
+     * close can differ from the one seen at create time.
+     */
+    private tupleDrift;
+}
+/** Load a start record's shards back into the path-keyed map the resolver walks. */
+export declare function readStartRecordEntries(stateDir: string, manifest: StartRecordManifest): Promise<Map<string, StartRecordEntry>>;

package/dist/local-executor/shadow-baseline-shards.d.ts

@@ -0,0 +1,34 @@
+import { type ShadowStateFileV2 } from './shadow-protocol';
+/** Inline baselines up to this many serialized bytes stay in the marker, so every shipped-size marker is unchanged. */
+export declare const BASELINE_INLINE_MAX_BYTES: number;
+export declare const BASELINE_SHARD_ENTRIES = 50000;
+export declare const BASELINE_RECORD_VERSION = 1;
+type BaselineEntry = ShadowStateFileV2['baseline'][number];
+export interface BaselineRecord {
+    version: typeof BASELINE_RECORD_VERSION;
+    entries: number;
+    /** `bytes` (Stage 2 R1-F8): the shard's exact size, checked before it is read. */
+    shards: Array<{
+        name: string;
+        sha256: string;
+        entries: number;
+        bytes?: number;
+    }>;
+}
+export declare const BASELINE_SHARD_RE: RegExp;
+/** `baseline-<instance uuid>-NNNNN.jsonl` — the instance UUID ties every shard to exactly one marker. */
+export declare function baselineShardName(shadowDir: string, index: number): string;
+export declare function inlineBaselineBytes(baseline: readonly BaselineEntry[]): number;
+/** Write the immutable shards (each `O_EXCL`, fsynced; then the directory) and return the record naming them. */
+export declare function writeBaselineShards(stateDir: string, shadowDir: string, baseline: readonly BaselineEntry[], entriesPerShard?: number): Promise<BaselineRecord>;
+/** The form written to disk: a recorded baseline is never serialized inline. */
+export declare function compactMarkerForSerialization(marker: ShadowStateFileV2): ShadowStateFileV2;
+/**
+ * Expand a parsed marker's `baselineRecord` into `baseline`, verifying every shard against its recorded hash and
+ * the record's counts. Shard names must be exactly the ones this marker's own instance would write — a record cannot
+ * point a reader anywhere else. A marker without a record is returned unchanged.
+ */
+export declare function expandMarkerBaseline(stateDir: string, raw: unknown): Promise<unknown>;
+/** This instance's shard files, for retirement at discard. */
+export declare function listBaselineShards(stateDir: string, shadowDir: string): Promise<string[]>;
+export {};

package/dist/local-executor/shadow-copy-strategy.d.ts

@@ -0,0 +1,20 @@
+export type CopyStrategy = 'clone' | 'full-copy';
+export interface CopyStrategyDecision {
+    strategy: CopyStrategy;
+    /** Why — recorded in the task log so a slow full copy is explained rather than mysterious. */
+    reason: 'clone-supported' | 'forced-physical' | 'different-device' | 'clone-unsupported' | 'probe-failed';
+}
+/** Probe whether `dir`'s filesystem can clone, using a CodeVibe-owned file it creates and always removes. */
+export declare function probeCloneCapability(dir: string): Promise<boolean>;
+/**
+ * Choose the task's strategy. `full-copy` is the conservative answer for every uncertain case, because the §5.5
+ * free-space check then runs — whereas wrongly choosing `clone` would skip the check for a copy that then
+ * writes the whole folder.
+ */
+export declare function chooseCopyStrategy(opts: {
+    sourceRoot: string;
+    copyLocation: string;
+    forcePhysical?: boolean;
+    /** Injected in tests. */
+    probe?: (dir: string) => Promise<boolean>;
+}): Promise<CopyStrategyDecision>;

package/dist/local-executor/shadow-free-space.d.ts

@@ -0,0 +1,124 @@
+/** §5.5: "`available ≥ bytesToCopy + max(1 GiB, 10% of bytesToCopy)`". */
+export declare function requiredBytesForCopy(bytesToCopy: number): number;
+/** §5.5 watchdog: "Below `max(1 GiB, 2% of the filesystem)` it sends SIGTERM to the agent's process group". */
+export declare function watchdogFloorBytes(filesystemTotalBytes: number): number;
+export interface FilesystemSpace {
+    path: string;
+    availableBytes: number;
+    totalBytes: number;
+}
+type StatfsFn = (path: string) => Promise<{
+    bavail: number | bigint;
+    bsize: number | bigint;
+    blocks: number | bigint;
+}>;
+/** Read what a filesystem can actually give an unprivileged writer. */
+export declare function readFilesystemSpace(path: string, statfs?: StatfsFn): Promise<FilesystemSpace>;
+export type CopySpaceVerdict = {
+    ok: true;
+    checked: FilesystemSpace[];
+    requiredBytes: number;
+} | {
+    ok: false;
+    /** Names the folder size and the free space, as §5.5 requires of the refusal message. */
+    reason: string;
+    short: FilesystemSpace;
+    requiredBytes: number;
+    reservedBytes: number;
+};
+export interface CopySpaceRequest {
+    /** The copy location (§5.1). The space test runs here. */
+    copyLocation: string;
+    bytesToCopy: number;
+    /**
+     * Bytes concurrent tracks have already reserved on the same device, from the quota registry. Two tracks that
+     * each pass the check alone must not both start into space only one of them fits.
+     */
+    reservedBytes?: number;
+    /**
+     * Further filesystems the same condition must hold on. On WSL2 the copy location sits in an ext4 virtual disk
+     * that grows into the Windows drive, and the two report very different free space (1007 GB disk with 953 GB
+     * free vs a 50 GB `C:` with 23 GB free [SP-B]) — so `/mnt/c` is checked too, and the smaller wins.
+     */
+    alsoRequireOn?: string[];
+    statfs?: StatfsFn;
+}
+/** §5.5's pre-copy check. A refusal means the task does not start, with this message. */
+export declare function checkCopySpace(req: CopySpaceRequest): Promise<CopySpaceVerdict>;
+export type WatchdogVerdict = {
+    trip: false;
+    checked: FilesystemSpace[];
+} | {
+    trip: true;
+    reason: string;
+    low: FilesystemSpace;
+    floorBytes: number;
+};
+/**
+ * One watchdog tick (§5.5 runs it every 5 s). When it trips, the caller sends SIGTERM to the agent's process
+ * group, SIGKILL after 10 s, halts the task with "disk nearly full", applies nothing, and keeps the copy.
+ *
+ * The floor is per filesystem because each has its own total. On WSL2 the Windows drive is checked too: the
+ * virtual disk can look roomy while the drive that backs it is nearly full.
+ */
+export declare function watchdogTick(paths: string[], statfs?: StatfsFn): Promise<WatchdogVerdict>;
+/** A task that §5.5 refuses to start. The message names the folder size and the free space. */
+export declare class InsufficientCopySpaceError extends Error {
+    readonly verdict: Extract<CopySpaceVerdict, {
+        ok: false;
+    }>;
+    readonly code = "ECOPYSPACE";
+    constructor(verdict: Extract<CopySpaceVerdict, {
+        ok: false;
+    }>);
+}
+/** The task-start gate's answer: the strategy, and how many bytes this task may write as physical copies. */
+export type CopySpaceDecision = import('./shadow-copy-strategy').CopyStrategyDecision & {
+    /**
+     * §5.6: the fixed 64 MiB / 512 MiB caps are gone, and this budget replaces them for every physical byte the task
+     * writes — the materializer's `maxFileBytes`/`maxTotalBytes`. A full copy may use the free space less §5.5's
+     * headroom (at least the folder's size, or the task was refused). A clone writes physical bytes only when single
+     * files cannot be cloned; those may use the free space down to the watchdog floor, so a fallback can never drive
+     * the disk below the level at which a running task is stopped. Always ≥ 1, as the materializer requires.
+     */
+    physicalCopyBudgetBytes: number;
+};
+/**
+ * The task-start gate: choose the copy strategy and, for a full copy only, refuse to start when the copy would
+ * not fit with §5.5's headroom. Throws {@link InsufficientCopySpaceError}. A clone is never refused here.
+ */
+export declare function assertCopySpaceForTask(opts: {
+    sourceRoot: string;
+    copyLocation: string;
+    forcePhysical: boolean;
+    reservedBytes?: number;
+    /** Injected in tests to simulate a full disk. */
+    statfs?: StatfsFn;
+}): Promise<CopySpaceDecision>;
+export interface CopySpaceWatchdog {
+    /** Stop the timer. Idempotent. */
+    stop(): void;
+    /** Resolves with the trip verdict the first time it trips; never resolves if it never trips. */
+    tripped: Promise<Extract<WatchdogVerdict, {
+        trip: true;
+    }>>;
+}
+/**
+ * §5.5's running-task watchdog: every `intervalMs` (5 s by default) it checks `paths` — the copy location, and on
+ * WSL2 the Windows drive too — and calls `onTrip` ONCE, then stops, when any falls below its floor.
+ *
+ * Deliberately only the timer and the decision: what `onTrip` does — SIGTERM to the agent's process group, SIGKILL
+ * after 10 s, halt the task with "disk nearly full", apply nothing, keep the copy — belongs to the process layer
+ * (Stream A's `process-tree.ts` / `local-executor-impl.ts`). A failed `statfs` is not a trip: a watchdog that
+ * stopped tasks on its own errors would be worse than none; the failure is reported to `onError`.
+ */
+export declare function startCopySpaceWatchdog(opts: {
+    paths: string[];
+    onTrip: (verdict: Extract<WatchdogVerdict, {
+        trip: true;
+    }>) => void | Promise<void>;
+    onError?: (err: unknown) => void;
+    intervalMs?: number;
+    statfs?: StatfsFn;
+}): CopySpaceWatchdog;
+export {};

package/dist/local-executor/shadow-fs-margins.d.ts

@@ -0,0 +1,59 @@
+/** Margins from §5.2's measured table. */
+export declare const FS_MARGIN_MS: {
+    readonly apfsNs: 1;
+    readonly linuxNs: 20;
+    readonly exfat: 20;
+    readonly hfsPlus: 1000;
+    readonly fat: 2000;
+    /** 9p/drvfs, NFS, SMB, FUSE — and the design's "anything else" row. */
+    readonly foreignClock: 3000;
+};
+/**
+ * The fail-closed margin. §5.2's table ends with "anything else → 3 s", so an unrecognised filesystem
+ * fingerprints more files rather than fewer. Every lookup below falls back here.
+ */
+export declare const DEFAULT_MARGIN_MS: 3000;
+export interface StartRecordMargin {
+    marginMs: number;
+    /** How the margin was reached, so a task log can say why a folder was treated as coarse. */
+    basis: 'linux-magic' | 'darwin-measured' | 'probe' | 'fail-closed-default';
+    /** The raw `statfs` type, for the task log and for diagnosing an unrecognised filesystem. */
+    fsType?: number;
+}
+/**
+ * Resolve the margin for a path.
+ *
+ * On Linux the documented magic number decides. On darwin a measured index decides **only when a granularity
+ * probe agrees** — pass `probedGranularityMs` from {@link probeTimestampGranularityMs}. Without a probe, darwin
+ * takes the fail-closed default even for a recognised index, because the index alone is not evidence (SB-9).
+ */
+export declare function resolveStartRecordMargin(path: string, opts?: {
+    probedGranularityMs?: number;
+}): Promise<StartRecordMargin>;
+/**
+ * Measure how long a same-size rewrite takes to become visible to `lstat` on this volume.
+ *
+ * This is the direct evidence the margin wants, and it is how §5.2's table was produced in the first place
+ * ("40/40 rapid same-size rewrites distinct" on APFS; "40 rapid rewrites → 1 distinct stat tuple" on HFS+).
+ * It answers one question — *after how long does a same-size rewrite change `mtimeNs`?* — which is exactly the
+ * quantity the racy-file rule needs, rather than inferring it from a filesystem's name.
+ *
+ * Runs in a **CodeVibe-named** temp entry in `dir`, which must be the copy location and never the user's folder:
+ * it writes. The entry is created `O_EXCL` and always removed.
+ *
+ * Returns the observed granularity in milliseconds, or `undefined` if it could not be measured — in which case
+ * the caller keeps the fail-closed default rather than guessing.
+ */
+/** Probe entries older than this cannot belong to a probe still running (each lasts well under a minute). */
+export declare const STALE_PROBE_AGE_MS: number;
+/**
+ * Stage 1 N8: remove probe entries a crash left in a shared copy root — only the two exact probe name shapes, only
+ * a regular file (granularity) or a real directory (clone, from `mkdtemp`), and only once older than
+ * {@link STALE_PROBE_AGE_MS}. Never a symlink, never anything else. Best effort: a failure leaves the entry.
+ */
+export declare function reapStaleProbeEntries(dir: string, now?: number): Promise<string[]>;
+export declare function probeTimestampGranularityMs(dir: string, opts?: {
+    capMs?: number;
+}): Promise<number | undefined>;
+/** §5.1: a copy location must be a disk filesystem. Fedora's `/tmp` is tmpfs, which is why `os.tmpdir()` is never used. */
+export declare function isMemoryBackedFilesystem(path: string): Promise<boolean>;