@quantiya/codevibe-core 2.0.91 → 2.0.93

package/dist/local-executor/local-executor-impl.d.ts

@@ -15,6 +15,7 @@ import type { ConflictResolverContext } from './merge-conflict-resolve';
 import { type ContentCipher } from './conflict-resolution-durable-store';
 import type { PromoteManifestInput, SnapshotPromotionJournalV1, TrackTipsView } from './durable-store';
 import { type ReviewedShadowDiffFile, type ShadowEnv } from './workspace-shadow';
+import type { BlobStore } from './blob-store';
 /**
  * CP-7 W2 Stage-2 HIGH (Finding 2) — STRICT delivery sink for the
  * `tier:'none'` (moat-OFF) reduced-trust badge.
@@ -74,7 +75,7 @@ export interface MergeGateContentEncryptor {
  */
 export type SubstrateEngageResult = {
     mode: 'substrate';
-    tier: 'docker' | 'sandbox_exec';
+    tier: 'docker' | 'sandbox_exec' | 'bubblewrap';
     reducedTrust: boolean;
     reducedTrustReason?: string;
     substrateHandle: SubstrateHandle;
@@ -113,9 +114,13 @@ export type SubstrateEngager = (input: {
      */
     requireConfined?: boolean;
     writableWorkdir?: boolean;
+    /** P63 Slice 2 (§8.2) — the spawn's task-owned capture dir, granted read-write beside a read-only view. */
+    captureDir?: string;
     webBrowsingActive?: boolean;
     /** F-P46a-4 — the spawn's process-tree id, folded into the sandbox environment. */
     processTreeId?: string;
+    /** P63 §6.1 / §6.2 — the user's real project folder (`SpawnArgs.projectRoot`). */
+    projectRoot?: string;
 }) => Promise<SubstrateEngageResult>;
 /** Backend lease is 15 minutes; three renewal opportunities fit inside it. */
 export declare const TEAM_TRACK_HEARTBEAT_INTERVAL_MS: number;
@@ -253,6 +258,27 @@ export interface LocalExecutorImplDeps {
      * + the GEMINI reduced-trust case.
      */
     substrateEngager?: SubstrateEngager;
+    /**
+     * P63 Slice 2 (§8.2) — the per-task folder (`taskFolderFor`, Stream A's layout): a read-only-view Codex spawn's
+     * capture dir is created at `<task folder>/capture/<spawn>/`. Absent (tests, embedders) → a fresh `os.tmpdir()`
+     * folder, so no test writes the real cache.
+     */
+    taskFolder?: (taskId: string) => string;
+    /**
+     * P63 §6.4 — the per-mode tier self-test: before the first real implementor of an agent version runs in a tier in a
+     * mode, the same engage runs it against a throwaway one-file view; a failure refuses the spawn (§6.4). Production
+     * wires it (`cli.ts`); absent → no self-test (tests and embedders with fake substrates).
+     */
+    tierSelfTest?: {
+        /** Where results are cached (`~/.codevibe/substrate-checks`). */
+        cacheDir: string;
+        /** Where the throwaway view is made (the real copy location). */
+        viewParent: () => Promise<string>;
+        /** `<agent> --version` (default: runs the binary; tests inject it). */
+        readAgentVersion?: (binary: string) => Promise<string>;
+        /** The Linux bubblewrap tier's key parts (filter SHA, bwrap version, setpriv/bash paths, pasta SHA). */
+        linuxKeyParts?: (open: boolean) => Promise<Pick<import('./tier-self-test').TierSelfTestKeyInput, 'filterSha256' | 'bwrapVersion' | 'setprivPath' | 'bashPath' | 'pastaSha256'>>;
+    };
     /**
      * CP-7 W2 Stage-2 HIGH (Finding 2) — STRICT delivery sink for the
      * `tier:'none'` (moat-OFF) reduced-trust badge. When supplied (production
@@ -319,6 +345,8 @@ export interface LocalExecutorImplDeps {
     readTrackTips?: (taskGroupId: string) => Promise<TrackTipsView>;
     /** Git-independent reviewed track bundles (the default team merge inputs). */
     readTrackBundles?: (taskGroupId: string) => Promise<SnapshotBundlesView>;
+    /** §9.4 — the group's content store (bundle post-images and merge results as blobs; see `runSnapshotMergeGate`). */
+    snapshotContentStore?: (taskGroupId: string) => BlobStore;
     /** Durable all-generation/cross-process fence around gate + hosted submission. */
     withSnapshotMergeGateFence?: <T>(taskGroupId: string, operation: () => Promise<T>, signal?: AbortSignal) => Promise<T>;
     /** Persist merged pre-images before the one group promotion mutates user files. */
@@ -364,6 +392,16 @@ export interface LocalExecutorImplDeps {
         conflicts: readonly string[];
         writeErrors: readonly string[];
     }) => void;
+    /** The tracks' changes could not be merged, before anything was applied. */
+    onTeamMergeConflict?: (info: {
+        taskGroupId: string;
+        paths: readonly string[];
+        workLimit: boolean;
+    }) => void;
+    /** The merge could not be finished and its verdict is withheld: some of its files may already be in the folder. */
+    onTeamMergeUnresolved?: (info: {
+        taskGroupId: string;
+    }) => void;
     /**
      * Legacy-named TEST SEAM around the merge-gate body. Production defaults to
      * the reviewed-bundle filesystem snapshot implementation.
@@ -525,6 +563,11 @@ export declare class LocalExecutorImpl implements LocalExecutor {
     private readonly logger;
     private readonly teamModeEnabled;
     private readonly substrateEngager?;
+    private readonly taskFolder?;
+    private readonly tierSelfTestConfig?;
+    /** One self-test per key at a time; concurrent spawns of the same key share it. */
+    private readonly tierSelfTestsInFlight;
+    private readonly agentVersions;
     private readonly strictBadgeSink?;
     constructor(deps: LocalExecutorImplDeps);
     /**
@@ -596,6 +639,19 @@ export declare class LocalExecutorImpl implements LocalExecutor {
      * takes the legacy path.
      */
     private engageSubstrateForSpawn;
+    /**
+     * P63 §6.4 — the reason this agent FAILED its cached execute-mode self-test in this tier, or null (no result yet, or
+     * a pass). The pre-start preflight consults it, so a task whose agent failed its self-test is refused before it
+     * starts and the user is offered the unconfined run.
+     */
+    tierSelfTestFailure(agentKind: AgentKind, tier: 'docker' | 'sandbox_exec' | 'bubblewrap'): Promise<string | null>;
+    /** P63 §6.4 — the cached tier self-test for (agent, version, tier, mode, argv template, tier binaries). */
+    private ensureTierSelfTest;
+    /**
+     * P63 Slice 2 (§8.2) — create a spawn's capture dir exclusively: `<task folder>/capture/<spawn>/` (0700), or a fresh
+     * `os.tmpdir()` folder when no task folder is wired. Returned canonical (Seatbelt grants match canonical paths).
+     */
+    private createCaptureDir;
     /**
      * CP-7 PART F — surface the PROMINENT reduced-trust badge (§6 Q2). The moat
      * being OFF (or coarse) MUST be visible + auditable, never silent: a

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

@@ -3,6 +3,8 @@ 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;
+    /** §17: the versioned no-link journal form. Absent on an entry a released desktop left open; any other value is refused. */
+    casMode?: 'nolink';
     token: string;
     op: NoLinkOperation;
     /** The target's path relative to the workspace root, for reporting; the helper uses only its basename. */
@@ -43,6 +45,16 @@ interface NoLinkHelperSpec {
     name: string;
     token: string;
     content?: string;
+    /**
+     * P63 Slice 2 (§9.4): the intended post-image as a blob in the instance's content store (`store-<uuid>/` in the
+     * journal's directory, F-S2-4) — replaces `content`. The parent opens it on apply only (recovery restores or completes
+     * renames and never needs it) and passes it as the helper's fd 3; the helper hashes it while writing and writes nothing
+     * on a mismatch.
+     */
+    blob?: {
+        name: string;
+        size: number;
+    };
     mode?: number;
     baseHash: string | null;
     intendedHash: string | null;
@@ -108,8 +120,8 @@ export declare class NoLinkJournalStore {
     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).
+     * Every entry not yet `done`. They are recovered at every `promote()` — each retry and the startup reconcile (R1-F1)
+     * — and, for a step left pending, every 10 seconds while the desktop runs (§9.3, `retryPendingNoLinkRestores`).
      */
     open(): Promise<NoLinkJournalEntry[]>;
 }
@@ -117,6 +129,8 @@ export declare class NoLinkJournalStore {
 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;
+/** §9.3: where a pending step's original is, relative to the workspace root — the name the user is told. */
+export declare function noLinkMovedPath(rel: string, token: string): string;
 /** 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 {
@@ -138,6 +152,12 @@ export interface NoLinkRunOptions {
 export declare function applyNoLink(opts: NoLinkRunOptions & {
     op: NoLinkOperation;
     content?: string;
+    /** P63 Slice 2 (§9.4): the post-image as a blob in the journal's directory, instead of `content`. */
+    blob?: {
+        name: string;
+        size: number;
+        sha256: string;
+    };
     mode?: number;
     /** Stage 2 R2-F3: the name's base mode, compared by the helper where modes are tracked. */
     baseMode?: number | null;

package/dist/local-executor/revert-runner.d.ts

@@ -1,5 +1,6 @@
 import { RevertManifestStore } from './durable-store';
 import { type CasHelperCrashStage } from './workspace-shadow';
+import { applyFileNoLink } from './shadow-apply-capabilities';
 /** The outcome of a group revert (Fork A: clean-where-safe + surface). */
 export interface RevertResult {
     /** Paths reverted (created→deleted, modified/deleted→restored) THIS pass. */
@@ -20,6 +21,8 @@ export interface RevertRunnerEnv {
     testCrashHelperStage?: (path: string) => CasHelperCrashStage | undefined;
     /** @internal swap/race seam before each manifest/journal filesystem proof. */
     beforeJournalFileRead?: (path: string) => Promise<void> | void;
+    /** @internal F-S2-5: the §9.3 helper's crash/fault controls for one no-link reverse step (interruption tests). */
+    noLinkTest?: (path: string) => Parameters<typeof applyFileNoLink>[0]['test'] | undefined;
 }
 /**
  * Revert the whole group's applied tree off its durable manifest + journal.

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

@@ -1,4 +1,4 @@
-import { applyNoLink, type NoLinkResult } from './nolink-apply';
+import { applyNoLink, type NoLinkOperation, type NoLinkResult } from './nolink-apply';
 import type { WorkspaceRootAuthority } from './workspace-authority';
 import { type VolumeCapabilities } from './shadow-volume-probe';
 export interface ApplyArtifactNames {
@@ -11,6 +11,24 @@ export interface ApplyArtifactNames {
 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;
+/**
+ * P63 Slice 2 (§9.4, F-S2-4) — this instance's content store: a directory of its own inside the task state directory
+ * (`store-<uuid>/`), holding its blobs and change-manifest shards. Not flat beside the markers: capture writes hundreds
+ * of blobs a second, and every task start and recovery sweep on this machine enumerates each task state directory and
+ * fails closed if it changes during the read — so a capturing task must leave its state directory itself untouched.
+ */
+export declare function instanceStoreDir(stateDir: string, shadowDir: string): string;
+/** P63 Slice 2 (§9.4) — this instance's blob namespace in its content store (`blob-store.ts`). */
+export declare function blobStoreFor(stateDir: string, shadowDir: string): {
+    dir: string;
+    prefix: string;
+};
+/** P63 Slice 2 (§9.4) — this instance's change-manifest shard namespace in its content store (`change-manifest-store.ts`). */
+export declare function manifestStoreFor(stateDir: string, shadowDir: string): {
+    dir: string;
+    prefix: string;
+};
+export declare function _setStoreRetireSeamForTests(seam: (() => Promise<void>) | undefined): void;
 /** 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';
@@ -22,6 +40,7 @@ export interface ForcedApplyCapabilities {
 export type ResolvedApplyCapabilities = VolumeCapabilities & {
     linkVolume: boolean;
 };
+export declare function writeDurable(file: string, body: string): Promise<void>;
 /**
  * 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).
@@ -31,7 +50,9 @@ export declare class NoLinkPendingError extends Error {
     readonly rel: string;
     readonly result: NoLinkResult;
     readonly code = "ENOLINKPENDING";
-    constructor(rel: string, result: NoLinkResult);
+    /** Where the original is now, relative to the workspace root; absent for a create, which moved nothing. */
+    readonly temporarilyAt?: string;
+    constructor(rel: string, result: NoLinkResult, op: NoLinkOperation, token: string);
 }
 /**
  * Apply one reviewed file on a no-link volume. Returns true when the name now holds the post-image (applied, or
@@ -47,6 +68,12 @@ export declare function applyFileNoLink(args: {
     rel: string;
     /** null = delete. */
     content: string | null;
+    /** P63 Slice 2 (§9.4): the post-image as a blob in `stateDir`; the journal names it instead of carrying `content`. */
+    blob?: {
+        name: string;
+        size: number;
+        sha256: string;
+    };
     /**
      * 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).
@@ -83,6 +110,8 @@ export declare function recoverOpenNoLinkEntries(args: {
     onKept?: (rel: string, kept: string[]) => void;
     onClosed?: (rel: string, result: NoLinkResult) => void;
     onError?: (rel: string, err: Error) => void;
+    /** §9.3: a step still pending whose original sits at `movedPath` (never called for a create, which moved nothing). */
+    onMoved?: (rel: string, movedPath: string) => 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[]>;

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

@@ -25,7 +25,24 @@ export type CopySpaceVerdict = {
     short: FilesystemSpace;
     requiredBytes: number;
     reservedBytes: number;
+    /** The bytes the copy needs, and what they are for — the structured fields `reason` is built from. */
+    bytesToCopy: number;
+    purpose: string;
 };
+/**
+ * §5.5 refusal text, built only from the verdict's structured fields (sizes, the short filesystem's path, the
+ * purpose), so a caller that relays it — the implementor-round failure label shown on the desktop and the phone —
+ * never forwards free-form error text.
+ */
+export declare function copySpaceRefusalText(v: Extract<CopySpaceVerdict, {
+    ok: false;
+}>, 
+/**
+ * How the short filesystem is named (default: its path). A message that crosses the start-error sanitizer names it in
+ * words instead: the sanitizer redacts an absolute path and its scan runs on past the path's end (lfree4: "… and
+ * [path] MiB free."), which would drop the free space §5.5 requires the message to name.
+ */
+location?: string): string;
 export interface CopySpaceRequest {
     /** The copy location (§5.1). The space test runs here. */
     copyLocation: string;
@@ -42,6 +59,8 @@ export interface CopySpaceRequest {
      */
     alsoRequireOn?: string[];
     statfs?: StatfsFn;
+    /** What the bytes are for, in the refusal ("copy this folder" by default; capture and review copies say so). */
+    purpose?: string;
 }
 /** §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>;
@@ -62,6 +81,12 @@ export type WatchdogVerdict = {
  * virtual disk can look roomy while the drive that backs it is nearly full.
  */
 export declare function watchdogTick(paths: string[], statfs?: StatfsFn): Promise<WatchdogVerdict>;
+/**
+ * P63 Slice 2 R1-F10 (§8.1 "counted in the free-space check", §5.5) — the same condition for a copy a running task
+ * makes after its start (captured post-images and base versions into its content store, a review bundle), on the
+ * filesystem that receives it and, on WSL2, the Windows drive too. Throws {@link InsufficientCopySpaceError}.
+ */
+export declare function assertCopySpace(copyLocation: string, bytesToCopy: number, purpose: string, statfs?: StatfsFn): Promise<void>;
 /** 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, {

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

@@ -1,7 +1,10 @@
 import * as fs from 'node:fs/promises';
-import { type AnchoredFsIdentity, type AnchoredPathIdentity, type AnchoredWritePrecondition } from './anchored-fs';
+import type { BlobRef } from './change-manifest';
+import type { ChangeManifestRecord } from './change-manifest-store';
+import { type AnchoredReadSession, type AnchoredFsIdentity, type AnchoredPathIdentity, type AnchoredWritePrecondition } from './anchored-fs';
 import { type ProcessCleanupOwner } from './process-tree';
 import { type ProcessIdentity } from './process-identity';
+import { type MetadataBudget } from './bounded-directory';
 import { type WorkspaceRootAuthority } from './workspace-authority';
 import { type MaterializationHangStage } from './workspace-materializer';
 /** Directories never materialized into a new filesystem snapshot. */
@@ -88,13 +91,17 @@ export declare const MAX_TRACKED_WORKSPACE_LOGICAL_BYTES: number;
 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).
+ * The bound on a CHANGE SET — the captured and reviewed diff, the promoted set, recovery authority, declared-test
+ * drift, merge plans and diff-sanity budgets. §5.6 lifts the historical 100,000-entry / 16 MiB-path cap in Slice 2:
+ * persisted change sets live in the sharded change manifest (§9.4) and markers hold only its shard hashes, so what
+ * remains is the in-memory sanity bound. A change set is a subset of the walked folder, so it shares the traversal
+ * ceiling above rather than carrying a product limit of its own (P63 Slice 2, E2E-4b: 300,000 changed paths).
+ * Persisted durable-store records keep the orchestration default (`createMetadataBudget()`, SB-37).
  */
-export declare const MAX_CHANGE_SET_FILE_COUNT = 100000;
+export declare const MAX_CHANGE_SET_FILE_COUNT = 5000000;
 export declare const MAX_CHANGE_SET_PATH_BYTES: number;
+/** Budget for validating one in-memory change set (see {@link MAX_CHANGE_SET_FILE_COUNT}). */
+export declare function createChangeSetBudget(): MetadataBudget;
 /** 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;
@@ -117,7 +124,67 @@ export interface ShadowDiffFile {
     content: string;
     /** POSIX permission bits for the reviewed post-image (omitted by legacy records). */
     mode?: number;
+    /**
+     * P63 Slice 2 (§9.4) — the captured post-image in the task's blob store (`blobStoreFor`), written through the
+     * anchored copy. Absent for deletions and for records written before Slice 2.
+     */
+    blob?: BlobRef;
 }
+/**
+ * P63 Slice 2 (§9.4) — a diff entry's optional blob reference is well formed and agrees with its inline content:
+ * never on a deletion, a 64-hex SHA-256 and a byte size equal to the content's UTF-8 length.
+ */
+export declare function assertDiffBlobRef(file: {
+    change_kind: unknown;
+    content: unknown;
+    blob?: unknown;
+}, label: string): void;
+/**
+ * P63 Slice 2 (§9.4) — text above this many bytes is carried as a blob reference only (`content: ''`): it is never
+ * held in memory whole, never 3-way line-merged (whole-file, like a binary — §10.3), and only excerpted for review.
+ */
+export declare const LARGE_TEXT_BYTES: number;
+/**
+ * P63 Slice 2 (§5.6, §9.4) — no per-file size limit on a captured, deleted or promoted file: §5.6 replaces the 16 MiB cap
+ * with the blob store, so a file is bounded by disk (the §5.5 free-space check and watchdog), never by a fixed number.
+ * Content above LARGE_TEXT_BYTES is streamed in 1 MiB chunks and never held in memory. The value is the largest byte
+ * count the anchored helpers' integer checks accept (S2-C8, Stage 2 R1: a 4 GiB cap here contradicted §5.6).
+ */
+export declare const MAX_CAPTURE_FILE_BYTES: number;
+/**
+ * §9.4 — a diff entry whose post-image lives only in the blob store: the desktop's records and in-memory structures
+ * hold references only. Its text is read from the blob when a consumer needs it — the ≤ LARGE_TEXT_BYTES 3-way merge,
+ * a projection excerpt, a revise brief — one file at a time, never kept.
+ */
+export declare function isReferenceDiffFile(file: {
+    change_kind: string;
+    content: string;
+    blob?: unknown;
+}): boolean;
+/** A reference entry above LARGE_TEXT_BYTES: never read whole, never line-merged (whole-file, §10.3), only excerpted. */
+export declare function isLargeDiffFile(file: {
+    change_kind: string;
+    content: string;
+    blob?: {
+        size: number;
+    };
+}): boolean;
+/** The post-image SHA-256 of a diff entry (null for a deletion) — from its blob reference when it has one. */
+export declare function diffPostHash(file: {
+    change_kind: string;
+    content: string;
+    blob?: {
+        blob: string;
+    };
+}): string | null;
+/** The post-image byte size of a diff entry (0 for a deletion). */
+export declare function diffPostSize(file: {
+    change_kind: string;
+    content: string;
+    blob?: {
+        size: number;
+    };
+}): number;
 /** A reviewed change plus the exact real-tree pre-image expected at promotion. */
 export interface ReviewedShadowDiffFile extends ShadowDiffFile {
     /** SHA-256 of the pre-task file, or null when the path was absent. */
@@ -146,9 +213,18 @@ export interface CasRecoveryAuthority {
     postHash: string | null;
     postMode: number | null;
 }
+/**
+ * P63 Slice 2 (§17 versioned state, R1-F11) — the marker version this desktop writes. Version 3 is the first schema
+ * with complete snapshot-incarnation authority (Slice 1); version 4 is Slice 2's — reviewed and promoted sets as
+ * shard-backed manifests in the instance's content store (`store-<uuid>/`), post-images as blob references. A Slice 1
+ * desktop accepts only 3 and protects a marker it cannot read. With {@link EXPOSURE_RETENTION_MARKER_VERSION}, which
+ * keeps it from reclaiming the copy through the exposure record, it leaves a Slice 2 task alone. This desktop reads both;
+ * every marker it writes is 4.
+ */
+export declare const SHADOW_STATE_MARKER_VERSION = 4;
 export interface ShadowStateFileV2 {
-    /** Version 3 is the first schema with complete snapshot-incarnation authority. */
-    version: 3;
+    /** 3: Slice 1 (read only); 4: Slice 2 — see {@link SHADOW_STATE_MARKER_VERSION}. */
+    version: 3 | 4;
     taskId: string;
     shadowDir: string;
     workingDir: string;
@@ -199,6 +275,12 @@ export interface ShadowStateFileV2 {
     }>;
     /** Names + byte identities needed to resolve any post-COMMIT helper death. */
     casRecovery?: CasRecoveryAuthority[];
+    /**
+     * P63 Slice 2 (§9.4, S2-9) — the promoted set as a shard-backed change manifest (shard hashes + root), written
+     * before the APPLYING marker. Replaces `promotePostHashes` + `casRecovery` (never both): post-images are the
+     * entries' blob references and the CAS authority is recomputed from them, so the marker stays O(shards).
+     */
+    promoteManifest?: ChangeManifestRecord;
     /** Full snapshot incarnation claimed by immutable DISPOSING authority. */
     disposalSnapshotAuthority?: WorkspaceRootAuthority;
     /** Legacy v3 field: protected fail-closed, never accepted for deletion. */
@@ -209,7 +291,19 @@ export interface ShadowStateFileV2 {
      * authority from mutable snapshot bytes.
      */
     reviewedDiff?: ShadowDiffFile[];
+    /**
+     * P63 Slice 2 (§9.4) — the reviewed artifact as a shard-backed change manifest (shard hashes + root); its content
+     * lives in the instance's blob store. Replaces `reviewedDiff` for new markers (never both), so the marker no longer
+     * grows with the size or number of reviewed files.
+     */
+    reviewedManifest?: ChangeManifestRecord;
 }
+/**
+ * P63 Slice 2 (§16 C4, §17, F-ROLLBACK-EXPOSURE-REAP) — the exposure retention version this desktop writes. A Slice 1
+ * desktop accepts 1 and 2, and with the owner dead it removes the copy such a record names; it retains a record of any
+ * other version and keeps its name protected. Version 3 has version 2's fields. This desktop reads all three.
+ */
+export declare const EXPOSURE_RETENTION_MARKER_VERSION = 3;
 /**
  * Non-operational authority published before a private snapshot name becomes
  * visible. It never authorizes use of `finalShadowDir`; it only prevents that
@@ -217,7 +311,8 @@ export interface ShadowStateFileV2 {
  * that CodeVibe may reclaim.
  */
 export interface ExposureRetentionMarker {
-    version: 1 | 2;
+    /** 1 and 2: Slice 1 (read only); 3: Slice 2 — see {@link EXPOSURE_RETENTION_MARKER_VERSION}. */
+    version: 1 | 2 | 3;
     taskId: string;
     finalShadowDir: string;
     originalSnapshotAuthority: WorkspaceRootAuthority;
@@ -321,11 +416,6 @@ export interface ShadowEnv {
         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;
     /**
@@ -335,6 +425,8 @@ export interface ShadowEnv {
     materializerLanes?: number;
     /** @internal Lower the inline-baseline threshold so tests exercise sharded markers (default 8 MiB). */
     baselineInlineMaxBytes?: number;
+    /** @internal R1-F10: a lower check interval for copies into the content store (tests). */
+    copySpaceCheckBytes?: number;
     /** @internal Test injection for §5.5's free-space check (`statfs` of the copy location). */
     copySpaceStatfs?: (path: string) => Promise<{
         bavail: number | bigint;
@@ -368,8 +460,6 @@ export interface ShadowEnv {
     killChildrenInShadow?: (shadowDir: string) => Promise<void>;
     /** @internal lower deterministic aggregate quota for tests. */
     maxSessionPhysicalCopyBytes?: number;
-    /** @internal lower deterministic aggregate pre-image quota for tests. */
-    maxPromotionPreImageAggregateBytes?: number;
     /** Test seam after the stable source handle is opened but before physical streaming. */
     beforePhysicalCopy?: (source: string) => Promise<void>;
     /** @internal force the production helper's bounded physical-copy branch. */
@@ -402,8 +492,14 @@ export interface ShadowEnv {
     afterPromotionParentValidation?: (path: string) => Promise<void>;
     /** @internal lower deterministic CAS-helper deadline for tests. */
     promotionHelperTimeoutMs?: number;
+    /** F-APPLY-RETRY: delays before each retry of a transiently failed placement; absent = 1 s, 5 s, 15 s; [] = no retry. */
+    promotionRetryDelaysMs?: readonly number[];
+    /** Test-only: retry even after a fault the test injected (hang/crash stage). */
+    retryInjectedPromotionFaults?: boolean;
+    /** Test-only: inject the hang/crash stage on the first placement attempt only. */
+    injectPromotionFaultOnFirstAttemptOnly?: boolean;
     /** @internal deterministic CAS-helper target-filesystem stall seam. */
-    testHangPromotionHelperStage?: (path: string) => 'root' | 'parent' | 'target' | undefined;
+    testHangPromotionHelperStage?: (path: string) => 'root' | 'parent' | 'target' | 'prepared' | undefined;
     /** @internal deterministic helper-death seam after COMMIT/mutation. */
     testCrashPromotionHelperStage?: (path: string) => CasHelperCrashStage | undefined;
     /** Test seam after the exact target is displaced but before replacement/deletion. */
@@ -488,6 +584,7 @@ export declare function assertSafeRelativePath(rel: string): void;
 export declare function isInternalShadowPath(rel: string): boolean;
 export declare function assertNotInternalShadowPath(rel: string): void;
 export declare function normalizeFileMode(mode: number): number;
+export declare function decodeStrictUtf8(bytes: Buffer, rel: string): string;
 /**
  * PHASE-589/469 W3.1 (C1) — read a real-tree file's CONTENT + hash by RELATIVE
  * path BEFORE the promote mutates it; `{ content: null, hash: null }` if absent
@@ -498,7 +595,9 @@ export declare function readRealFileForManifest(workingDir: string, rel: string,
     hash: string | null;
     mode: number | null;
 }>;
-export declare function readRealFileMetadata(workingDir: string, rel: string, expectedRoot: AnchoredFsIdentity | WorkspaceRootAuthority): Promise<{
+export declare function readRealFileMetadata(workingDir: string, rel: string, expectedRoot: AnchoredFsIdentity | WorkspaceRootAuthority, 
+/** F-CAS-BATCH: read through this pass's one helper. */
+session?: AnchoredReadSession): Promise<{
     hash: string | null;
     mode: number | null;
 }>;

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

@@ -7,6 +7,7 @@ import { type WorkspaceRootAuthority } from './workspace-authority';
 import { type MaterializedFileMetadata } from './workspace-materializer';
 import { type DurableDirectoryIdentity } from './durable-directory';
 import { CasRecoveryAuthority, DisplacedShadowMarkerRecord, ExposureRetentionMarker, RetainedStateFileAuthority, ShadowDiffFile, ShadowEnv, ShadowPromoteState, ShadowStateFileV2, SnapshotIncarnationIndex, StructurallyBoundStateSnapshot, UnresolvedBundlePublicationRetention } from './shadow-protocol';
+import { type ChangeManifestRecord } from './change-manifest-store';
 /** A recovered shadow state (read from the durable per-task marker). */
 export interface RecoveredShadow {
     taskId: string;
@@ -43,10 +44,14 @@ export interface RecoveredShadow {
         mode?: number | null;
     }>;
     casRecovery?: CasRecoveryAuthority[];
+    /** P63 Slice 2 (S2-9) — shard-backed promotion authority (replaces the two inline lists above). */
+    promoteManifest?: ChangeManifestRecord;
     disposalSnapshotAuthority?: WorkspaceRootAuthority;
     disposalShadowIdentity?: AnchoredFsIdentity;
     /** Exact reviewed artifact persisted before authorization could resolve. */
     reviewedDiff?: ShadowDiffFile[];
+    /** P63 Slice 2 (§9.4) — the reviewed artifact as a shard-backed manifest (replaces `reviewedDiff`). */
+    reviewedManifest?: ChangeManifestRecord;
     cleanupBlocked?: boolean;
     cleanupOwners?: ProcessCleanupOwner[];
     unresolvedAuthorityRetention?: UnresolvedBundlePublicationRetention;
@@ -175,11 +180,31 @@ export declare function copyStatTuple(stat: {
     ino: string;
     mode: string;
 }): string;
+/** P63 Slice 2 R1-F6 — what a snapshot walk leaves out, for the review INDEX (§5.7). */
+export interface ShadowPrivateEntries {
+    folders: Array<{
+        path: string;
+        group: 'hidden' | 'dependencies' | 'rebuild-output' | 'codevibe';
+    }>;
+    notApplicable: string[];
+}
+/** The §5.7 group of a skipped folder name. */
+export declare function privateFolderGroup(name: string): ShadowPrivateEntries['folders'][number]['group'];
 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;
+statsOut?: Map<string, string>, 
+/**
+ * P63 Slice 2 R1-F6 (§5.7): when given, receives the private folders the walk skips (with their group) and every
+ * entry that is neither a file nor a directory — the review INDEX lists both as never applied.
+ */
+privateOut?: ShadowPrivateEntries, 
+/**
+ * F-EXIT-WAITS-CAPTURE (tick): a caller-owned budget. A listing larger than it stops at the first folder past the
+ * limit, and the caller reads `budget.entries > budget.maxEntries` to tell that apart from any other failure.
+ */
+callerBudget?: PathBudget): Promise<string[]>;
+export type PathBudget = MetadataBudget;
+export declare function createPathBudget(maxEntries?: number): PathBudget;
 export declare function assertPathCollectionBounds(paths: readonly string[], label: string): void;
 export declare function isWithinRoot(root: string, candidate: string): boolean;
 export declare function assertSafeStateComponent(value: string): void;

package/dist/local-executor/shadow-task-intent.d.ts

@@ -0,0 +1,29 @@
+export declare const TASK_INTENT_VERSION = 1;
+/** How long a stopped task's copy waits for a resume: the session resume window, not the 24 h orphan TTL. */
+export declare const INTERRUPTED_TASK_RETENTION_MS: number;
+export interface TaskIntent {
+    version: typeof TASK_INTENT_VERSION;
+    sessionId: string;
+    brief: string;
+    request?: string;
+    agent: string;
+    decision: unknown;
+    /**
+     * S2-C3 (Stage 2 R1): the task was started opted in to run UNCONFINED (§6.4). History, not permission: a reopened
+     * task keeps the after-run check of the user's folder and the summary's disclosure, and is never itself allowed to
+     * run an agent unconfined because of it.
+     */
+    ranUnconfined?: true;
+}
+export type ReadTaskIntent = {
+    kind: 'none';
+}
+/** §17: a version this desktop does not know is listed and never acted on. */
+ | {
+    kind: 'newer';
+} | {
+    kind: 'intent';
+    intent: TaskIntent;
+};
+export declare function writeTaskIntent(stateDir: string, shadowDir: string, intent: TaskIntent): Promise<void>;
+export declare function readTaskIntent(stateDir: string, shadowDir: string): Promise<ReadTaskIntent>;

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

@@ -26,17 +26,3 @@ export declare function probeVolumeCapabilities(projectRoot: string, journalProb
 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>;