@quantiya/codevibe-core 2.0.91 → 2.0.93

package/dist/local-executor/sharded-list.d.ts

@@ -0,0 +1,32 @@
+export declare const SHARDED_LIST_VERSION = 1;
+export declare const SHARDED_LIST_SHARD_ITEMS = 10000;
+/** A shard holds at most 10,000 items of a few hundred bytes each; anything far larger is not a shard. */
+export declare const MAX_SHARDED_LIST_SHARD_BYTES: number;
+/** One record's list namespace in a content store: names `<prefix>-<sha256>`. */
+export interface ListStore {
+    dir: string;
+    prefix: string;
+}
+/** What a record holds in place of a list. `kind` names the list, so a record can never borrow another list's shards. */
+export interface ShardedListRecord {
+    shardedList: typeof SHARDED_LIST_VERSION;
+    kind: string;
+    entries: number;
+    shards: Array<{
+        sha256: string;
+        entries: number;
+    }>;
+    rootHash: string;
+}
+/** Canonical JSON of one item: object keys in sorted order at every depth, so equal items serialize to equal bytes. */
+export declare function canonicalJson(value: unknown): string;
+/**
+ * Write `items` as shards (each once; an existing name must already hold exactly those bytes) and return the record.
+ * The store directory is fsynced before returning, so a record written afterwards never names a shard a crash lost.
+ */
+export declare function writeShardedList(store: ListStore, kind: string, items: readonly unknown[], itemsPerShard?: number): Promise<ShardedListRecord>;
+/** Validate a record's shape and root hash (no file access). */
+export declare function isShardedListRecord(value: unknown): value is ShardedListRecord;
+export declare function assertShardedListRecord(value: unknown, kind: string): asserts value is ShardedListRecord;
+/** Read every item a record names, verifying each shard and the record. */
+export declare function readShardedList(store: ListStore, record: unknown, kind: string): Promise<unknown[]>;

package/dist/local-executor/snapshot-merge.d.ts

@@ -3,6 +3,7 @@ import type { GateRunResult } from './verification-runner';
 import { type MetadataBudget } from './bounded-directory';
 import type { PromoteManifestInput, RevertManifestEntry, RevertManifestStore, SnapshotPromotionJournalV1 } from './durable-store';
 import { WorkspaceShadow, type ReviewedShadowDiffFile, type ShadowEnv } from './workspace-shadow';
+import { type BlobStore } from './blob-store';
 import { type WorkspaceRootAuthority } from './workspace-authority';
 export declare const SNAPSHOT_TRACK_BUNDLE_VERSION: 2;
 export interface SnapshotTrackBundle {
@@ -43,9 +44,15 @@ export type SnapshotMergePlan = {
     status: 'conflict';
     paths: string[];
     reason: string;
+    workLimit?: true;
 };
 export interface SnapshotMergePlanOptions {
     signal?: AbortSignal;
+    /**
+     * §9.4 — the group's content store: every bundle's reference post-images were copied there at publication, and a
+     * line-merged result is written there and carried as a reference. Required when any bundle has reference files.
+     */
+    contentStore?: BlobStore;
     /** @internal deterministic aggregate-work ceiling for tests. */
     maxWork?: number;
     /** @internal deterministic planning deadline for tests. */
@@ -59,10 +66,16 @@ export declare function verifySnapshotTrackBundle(bundle: SnapshotTrackBundle, e
     files?: MetadataBudget;
     testSurfaces?: MetadataBudget;
 }): void;
+/** §9.4 — the content address of a file list: canonical JSON, so a list read back from content-store shards verifies. */
+export declare function filesContentHash(files: readonly unknown[]): string;
+/** A recorded file-list hash: canonical, or the `JSON.stringify` form of a record written before §9.4 shards. */
+export declare function filesHashMatches(files: readonly unknown[], hash: string): boolean;
 export declare function snapshotPromotionOperationHash(taskGroupId: string, bundles: readonly SnapshotTrackBundle[], gateKinds: readonly VerificationGateKind[]): string;
 export interface RunSnapshotMergeGateArgs {
     workingDir: string;
     taskGroupId: string;
+    /** §9.4 — the group's content store (bundle post-images, merge results); see {@link SnapshotMergePlanOptions}. */
+    contentStore?: BlobStore;
     ownerTrackIndex: number;
     bundles: readonly SnapshotTrackBundle[];
     gateKinds: readonly VerificationGateKind[];
@@ -101,6 +114,11 @@ export interface RunSnapshotMergeGateArgs {
         conflicts: readonly string[];
         writeErrors: readonly string[];
     }) => void;
+    /** The tracks' changes could not be merged, before anything was applied. Paths are workspace-relative. */
+    onMergeConflict?: (info: {
+        paths: readonly string[];
+        workLimit: boolean;
+    }) => void;
 }
 /**
  * `UNRESOLVED` is deliberately not a wire-level MergeResult. It means durable

package/dist/local-executor/spawn-sweep-binary.d.ts

@@ -0,0 +1,33 @@
+export declare const SPAWN_SWEEP_MANIFEST = "spawn-sweep.json";
+export declare const SPAWN_SWEEP_BINARY = "codevibe-spawn-sweep";
+export type SpawnSweepTarget = 'linux-x64' | 'linux-arm64';
+export interface SpawnSweepManifest {
+    version: 1;
+    /** The core-rs commit whose pipeline built the bytes. */
+    coreRsSha: string;
+    targets: Record<SpawnSweepTarget, {
+        sha256: string;
+        versionId: string | null;
+    }>;
+}
+export type SpawnSweepHelperResolution = {
+    ok: true;
+    path: string;
+    sha256: string;
+    target: SpawnSweepTarget;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function spawnSweepTarget(platform?: NodeJS.Platform, arch?: string): SpawnSweepTarget | null;
+export declare function parseSpawnSweepManifest(text: string): SpawnSweepManifest | null;
+export interface ResolveSpawnSweepOptions {
+    platform?: NodeJS.Platform;
+    arch?: string;
+    /** Overrides the package `native/` directories searched (tests). */
+    nativeDirs?: string[];
+    uid?: number;
+}
+export declare function resolveSpawnSweepHelper(opts?: ResolveSpawnSweepOptions): SpawnSweepHelperResolution;
+/** @internal tests */
+export declare function _resetSpawnSweepHelperCache(): void;

package/dist/local-executor/spawn-sweep.d.ts

@@ -1,4 +1,5 @@
 import cp from 'node:child_process';
+import { resolveSpawnSweepHelper } from './spawn-sweep-binary';
 export interface SpawnSweepRecord {
     version: 1;
     bootId: string;
@@ -49,6 +50,8 @@ export interface SpawnSweepOptions {
     readProcStat?: (pid: number) => ProcStatOutcome;
     /** Injectable spawner for unit tests */
     spawnHelper?: typeof cp.spawn;
+    /** Injectable packaged-helper resolution (tests; default `resolveSpawnSweepHelper`). */
+    resolveHelper?: typeof resolveSpawnSweepHelper;
 }
 /** Reset active spawn sweeps map (for test isolation) */
 export declare function _resetActiveSpawnSweeps(): void;

package/dist/local-executor/store-dir-anchor.d.ts

@@ -0,0 +1,48 @@
+export interface StoreDirIdentity {
+    dev: number;
+    ino: number;
+}
+/** One held store directory. `close()` belongs in a `finally`. */
+export interface StoreAnchor {
+    /** The canonical directory path (no symlink in it when the anchor was opened). */
+    readonly dir: string;
+    readonly identity: StoreDirIdentity;
+    /** The path that names `name` inside the HELD directory (Linux: through its descriptor). */
+    at(name: string): string;
+    /**
+     * The no-follow flag for every open through {@link at}: `O_NOFOLLOW` (Linux), `O_NOFOLLOW_ANY` (macOS — it also refuses
+     * a final symlink, and the kernel rejects the two together with EINVAL).
+     */
+    readonly noFollow: number;
+    /** Whether names resolve through the held descriptor (exact), not through the path. */
+    readonly pinned: boolean;
+    /** The held directory still has the identity it was opened with, and the path still names it. */
+    assertStill(label: string): Promise<void>;
+    /** fsync the held directory. */
+    sync(): Promise<void>;
+    /** List the held directory. */
+    list(): Promise<string[]>;
+    close(): Promise<void>;
+}
+/**
+ * Open (and with `create`, first create 0700 inside its existing parent, whose entry is fsynced) a store directory and
+ * hold it. A store path that is a symlink or anything but a real directory is refused, never followed; null when
+ * nothing is there and `create` is false.
+ */
+export declare function openStoreAnchor(dir: string, opts: {
+    create: boolean;
+}): Promise<StoreAnchor | null>;
+/**
+ * Remove exactly the regular files whose names start with one of `prefixes` from the store directory `dir`, then the
+ * directory if that left it empty. Every unlink happens in a helper whose working directory was checked to be the
+ * store's inode, so a store replaced at any point is refused (`instance content store was replaced during its
+ * retirement`) and nothing in the replacement is touched. Anything else inside keeps the directory.
+ */
+export declare function removeStoreEntriesAnchored(dir: string, prefixes: readonly string[], opts?: {
+    helperTimeoutMs?: number; /** @internal test seam: after the identity is taken, before the helper starts. */
+    beforeHelper?: () => Promise<void>;
+}): Promise<{
+    removed: number;
+    kept: number;
+    directoryRemoved: boolean;
+}>;

package/dist/local-executor/tier-self-test.d.ts

@@ -0,0 +1,57 @@
+import type { AgentKind, ImplementorHandle, SpawnArgs } from './types';
+export type SelfTestMode = 'execute' | 'plan';
+export type SelfTestTier = 'docker' | 'sandbox_exec' | 'bubblewrap';
+export type AgyCommandTool = 'works' | 'no-command-tool' | 'unknown';
+export interface TierSelfTestKeyInput {
+    agentKind: AgentKind;
+    agentVersion: string;
+    tier: SelfTestTier;
+    /** `review` = the reviewer-seat read-only argv (`orchestration-shell/reviewer-seat-self-test.ts`). */
+    mode: SelfTestMode | 'review';
+    /** The mode's argv template (built for the placeholder view). */
+    argvTemplate: readonly string[];
+    /** Linux bubblewrap tier: the seccomp program's SHA-256, `bwrap --version`, and `setpriv` / `bash` paths. */
+    filterSha256?: string;
+    bwrapVersion?: string;
+    setprivPath?: string;
+    bashPath?: string;
+    /** Linux open-egress mode: the pasta binary's SHA-256. */
+    pastaSha256?: string;
+}
+export declare const SELF_TEST_VIEW_PLACEHOLDER = "/codevibe-self-test-view";
+export declare function tierSelfTestKey(k: TierSelfTestKeyInput): string;
+export interface TierSelfTestResult {
+    key: string;
+    agentKind: AgentKind;
+    agentVersion: string;
+    tier: SelfTestTier;
+    mode: SelfTestMode | 'review';
+    pass: boolean;
+    reason?: string;
+    agyCommandTool?: AgyCommandTool;
+    checkedAt: string;
+}
+export declare function readTierSelfTest(cacheDir: string, key: string): TierSelfTestResult | null;
+export declare function writeTierSelfTest(cacheDir: string, result: TierSelfTestResult): void;
+/** `<agent> --version`, first line, bounded; '' when it cannot be read (a version change still re-keys). */
+export declare function readAgentVersion(binary: string): Promise<string>;
+export interface RunTierSelfTestInput {
+    agentKind: AgentKind;
+    mode: SelfTestMode;
+    /** Where the throwaway view goes (the real copy location, so the test sees the same filesystem and grants). */
+    viewParent: string;
+    /** The mode's real argv for a view (`buildImplementorArgv(agent, mode, view).argv`). */
+    argvFor: (view: string) => string[];
+    /** One implementor spawn through the same engage path as a real task (the LE's own `spawnImplementor`). */
+    spawn: (args: SpawnArgs) => Promise<ImplementorHandle>;
+    timeoutMs?: number;
+    /** Removes the folders the spawns made under the self-test's own task ids (capture, private homes). */
+    removeTaskFolder?: (taskId: string) => Promise<void>;
+}
+/** Runs the §6.4 self-test once; never throws for a failing agent (the verdict says why). */
+export declare function runTierSelfTest(input: RunTierSelfTestInput): Promise<{
+    pass: boolean;
+    reason?: string;
+    agyCommandTool?: AgyCommandTool;
+    transient?: boolean;
+}>;

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

@@ -19,6 +19,20 @@ export interface SpawnArgs {
     signal?: AbortSignal;
     taskId?: string;
     webTurnActive?: boolean;
+    /**
+     * P63 §6.1 / §6.2 — the user's real project folder this spawn's copy was made from. The Linux bubblewrap tier needs
+     * it (with the copy roots) for the grant rule: a granted toolchain root may never contain it, and a project lying
+     * inside a bound system folder is hidden with `--tmpfs`. A task spawn without it cannot engage that tier.
+     */
+    projectRoot?: string;
+    /**
+     * P63 §6.4 — the user opted in, for THIS task, to running its implementor unconfined when no confining tier can be
+     * established. Without it a `reduced_trust` engage refuses the spawn (`SpawnConfinementUnavailable`) — CodeVibe never
+     * runs an implementor unconfined on its own.
+     */
+    allowUnconfined?: boolean;
+    /** P63 §6.4 — this spawn IS a tier self-test (never itself self-tested). Set only by the LE. */
+    tierSelfTest?: boolean;
     processTreeId?: string;
     taskPrivateWorkingDir?: boolean;
     lifecycleAudit?: 'active_task' | 'none';
@@ -30,6 +44,12 @@ export interface SpawnArgs {
     onCleanupOwnerRetired?: (owner: import('./process-tree').ProcessCleanupOwner) => Promise<void>;
     substrate?: SubstrateHandle;
     requireConfined?: boolean;
+    /**
+     * P63 Slice 2 (§8.2) — the implementor mode this argv was built for. `'plan'` engages the substrate with a READ-ONLY
+     * view (`writableWorkdir: false`). The LE also reads plan mode from the argv itself
+     * (`isPlanModeImplementorArgv`), so omitting or contradicting this cannot widen a plan run to a writable view.
+     */
+    implementorMode?: 'plan' | 'execute';
 }
 export interface ProcessSpawnedInfo {
     pid: number;
@@ -65,6 +85,12 @@ export interface SpawnHandleBase {
 }
 export interface ImplementorHandle extends SpawnHandleBase {
     kind: 'implementor';
+    /**
+     * P63 Slice 2 (§8.2) — when this spawn ran with a read-only view and a capture dir, the HOST path of the Codex
+     * `--output-last-message` file inside it; plan readers pass it to `readImplementorLastMessage` (read first; the
+     * capture dir is removed once read). Absent on every other spawn.
+     */
+    lastMessageCapturePath?: string;
 }
 export interface ReviewerHandle extends SpawnHandleBase {
     kind: 'reviewer';

package/dist/local-executor/verification-gates/diff-sanity.d.ts

@@ -1,10 +1,16 @@
 import { type ShadowDiffFile } from '../workspace-shadow';
+import { type BlobStore } from '../blob-store';
 import type { GateRunResult } from '../verification-runner';
 import { type WorkspaceRootAuthority } from '../workspace-authority';
 export interface DiffSanityGateArgs {
     cwd: string;
     timeoutMs: number;
     files?: readonly ShadowDiffFile[];
+    /**
+     * §9.4 — where `files`' reference entries (no inline text) live: each is checked by streaming its verified blob, so
+     * the gate reads exactly the reviewed bytes at any size. Required when `files` has reference entries.
+     */
+    contentStore?: BlobStore;
     workingDirAuthority?: WorkspaceRootAuthority;
     /** @internal deterministic root-replacement seam. */
     afterAuthorityCheck?: () => Promise<void> | void;

package/dist/local-executor/workspace-materializer.d.ts

@@ -5,9 +5,18 @@ export interface MaterializedFileMetadata {
     size: number;
     mode: number;
 }
+/**
+ * P63 Slice 2 (§9.4) — the largest file whose bytes a hash session returns with its hash (`readFile`): the base64
+ * reply stays inside the helper protocol's 128 KiB line limit. Larger files are copied by the streaming helper.
+ */
+export declare const SESSION_READ_MAX_BYTES: number;
 export interface WorkspaceMaterializerSession {
     copyFile(source: string, destination: string, maxLogicalBytes?: number): Promise<MaterializedFileMetadata>;
-    hashDestinationFile(destination: string, maxBytes: number): Promise<MaterializedFileMetadata>;
+    hashDestinationFile(destination: string, maxBytes: number, 
+    /** P63 Slice 2: also return the bytes when the file is at most this size (≤ {@link SESSION_READ_MAX_BYTES}). */
+    contentMaxBytes?: number): Promise<MaterializedFileMetadata & {
+        content?: Buffer;
+    }>;
     relocateDestinationRoot(authority: WorkspaceRootAuthority): Promise<void>;
     /**
      * §5.3 (macOS): clone every listed regular file of one directory with a single `cp -c`, so each later
@@ -21,6 +30,13 @@ export interface WorkspaceMaterializerSession {
 }
 export interface WorkspaceFileHashSession {
     hashFile(file: string): Promise<MaterializedFileMetadata>;
+    /**
+     * P63 Slice 2 (§9.4 capture): the same identity-bound read as `hashFile`, also returning the bytes when the file is
+     * at most {@link SESSION_READ_MAX_BYTES} (verified against the reported hash and size); `content` is absent above that.
+     */
+    readFile(file: string): Promise<MaterializedFileMetadata & {
+        content?: Buffer;
+    }>;
     close(): Promise<void>;
 }
 export interface WorkspaceFileHashOptions {

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

@@ -2,6 +2,11 @@ import type { PromoteManifestInput } from './durable-store';
 import { type ProcessCleanupOwner } from './process-tree';
 import { type WorkspaceRootAuthority } from './workspace-authority';
 import { ReviewedShadowDiffFile, ShadowDiffFile, ShadowEnv, ShadowPromoteState, TrackBranchSpec, UnresolvedBundlePublicationRetention } from './shadow-protocol';
+import { type CopySpaceVerdict } from './shadow-free-space';
+import { type TaskIntent } from './shadow-task-intent';
+import { type BlobStore } from './blob-store';
+import type { BlobRef } from './change-manifest';
+import type { CasRecoveryAuthority } from './shadow-protocol';
 import { RecoveredShadow } from './shadow-recovery';
 export { MAX_CHANGE_SET_FILE_COUNT, MAX_CHANGE_SET_PATH_BYTES, MAX_TRACKED_FILE_LOGICAL_BYTES, MAX_TRACKED_WORKSPACE_LOGICAL_BYTES, MAX_TRACKED_FILE_COUNT, MAX_TRACKED_PATH_BYTES, MAX_REVIEW_FILE_BYTES, MAX_PROMOTION_PREIMAGE_AGGREGATE_BYTES, MAX_STATE_MARKER_BYTES, DEFAULT_SHADOW_TTL_MS, } from './shadow-protocol';
 export type { ShadowChangeKind, ShadowDiffFile, ReviewedShadowDiffFile, CasHelperCrashStage, UnresolvedBundlePublicationRetention, ShadowEnv, TrackBranchSpec, } from './shadow-protocol';
@@ -9,13 +14,25 @@ export { listRecoverableShadows, reconcileShadowPublicationAuthority, listShadow
 export type { RecoveredShadow, ShadowCleanupResidue } from './shadow-recovery';
 export { replaceWorkspaceFileIfMatches, removeWorkspaceFileIfMatches, } from './anchored-cas';
 export type { AcceptedAlternateImage } from './anchored-cas';
+export declare function treeRemovalTimeoutMs(entries: number): number;
 /**
- * The desktop's per-task shadow workspace. ONE instance per active task; the
- * QuorumLoop creates it before the round-0 spawn, points the implementor cwd at
- * `shadowDir`, captures the diff after the implementor exits, and the class-B
- * consumer promotes (TaskAuthorized) or discards (every other terminal).
+ * F-EXIT-WAITS-CAPTURE (tick): a capture asked to stop past `maxFiles` (the progress tick's count) found a larger
+ * copy. Nothing was hashed, stored or recorded; it is not a capture failure.
  */
+export declare class ShadowCaptureTooLargeError extends Error {
+    constructor();
+}
+/**
+ * F-APPLY-RETRY: a helper that stopped answering or ended is transient — the next helper re-proves the file's exact
+ * state. A conflict, a second writer, an abort or any other error is definite.
+ */
+export declare function isTransientPlacementFailure(err: unknown, reason: string): boolean;
+/** An in-flight capture ended by session exit (`WorkspaceShadow.cancelCapture`), not a capture failure. */
+export declare class ShadowCaptureCancelledError extends Error {
+    constructor();
+}
 export declare class WorkspaceShadow {
+    private captureCancelled;
     readonly taskId: string;
     /** The real workspace root (canonical). */
     readonly workingDir: string;
@@ -67,6 +84,17 @@ export declare class WorkspaceShadow {
     private copyStatTable?;
     /** §7.4: the user's own changes to their folder since the start record, from the last capture. */
     userFolderChanges?: import('./shadow-start-record').FolderChangesSinceStart;
+    /** R1-F10: bytes copied into this instance's content store since its last free-space check. */
+    private pendingStoreCopyBytes;
+    /**
+     * P63 Slice 2 R1-F10 (§5.5, §9.4) — a copy into this instance's content store (a captured post-image, a base version)
+     * is admitted by free space like the task's own copy: before a file of COPY_SPACE_CHECK_BYTES or more, and whenever
+     * smaller copies since the last check add up to that much, with §5.5's headroom. Refused → the capture stops with the
+     * reason; nothing is applied, the user's folder is untouched.
+     */
+    private admitStoreCopy;
+    /** P63 Slice 2 R1-F6 (§5.7): the private folders and not-applicable entries of the copy, from the last capture. */
+    privateEntries?: import('./shadow-recovery').ShadowPrivateEntries;
     /**
      * §7.4: count the user's own edits to their folder since the task started. Reviewers see this in Slice 2's review
      * INDEX; Slice 1 records it and writes it to the task log. Never fails a capture: the count is information.
@@ -75,6 +103,8 @@ export declare class WorkspaceShadow {
     private readonly env;
     private readonly maxStateMarkerBytes;
     private promotedInProcess;
+    /** §9.3 "What can stay in the user's folder": kept files, until the caller names them to the user. */
+    private readonly keptBesideApply;
     private cleanupBlocked;
     private cleanupOwners;
     private unresolvedAuthorityRetention?;
@@ -111,6 +141,17 @@ export declare class WorkspaceShadow {
      * Fail-closed (#SR-2): a create failure throws — the caller surfaces it and
      * does NOT spawn against a half-built shadow.
      */
+    /**
+     * §5.5 before the task starts (N4, Stage 1 R2): "Not enough space → the task does not start". The same copy-location
+     * choice and the same {@link assertCopySpaceForTask} decision `create` makes, run before the task is created, so a
+     * folder that cannot be copied is refused before "Started task". Returns the refusal, or null when the copy fits or
+     * the decision cannot be made here (an unreadable folder): `create` keeps the authoritative check inside the quota
+     * lock, so space that changes in between is still caught. Writes nothing except an absent copy root (created as
+     * `create` creates it, S2-C6) and the clone probe's own temporary entry, as `create` does.
+     */
+    static precheckCopySpace(workingDir: string, env?: ShadowEnv): Promise<Extract<CopySpaceVerdict, {
+        ok: false;
+    }> | null>;
     static create(taskId: string, workingDir: string, env?: ShadowEnv, opts?: {
         trackBranch?: TrackBranchSpec;
     }): Promise<WorkspaceShadow>;
@@ -126,7 +167,27 @@ export declare class WorkspaceShadow {
      * Snapshots use a tree compare bounded to the tracked set. Across revise
      * rounds the diff is CUMULATIVE shadow-vs-real.
      */
-    captureDiff(): Promise<ShadowDiffFile[]>;
+    captureDiff(opts?: {
+        cancellable?: boolean;
+        maxFiles?: number;
+    }): Promise<ShadowDiffFile[]>;
+    /** F-RESTART-NOT-RESUMED (§17): durable before the agent starts, so a later resume can reopen this task. */
+    writeTaskIntent(intent: TaskIntent): Promise<void>;
+    /**
+     * F-APPLY-RETRY: one file's placement with bounded retries of a TRANSIENT helper failure. Attempt 0 is the normal
+     * placement; each retry runs on a fresh helper through the crash-recovery proof. Only the failures below are
+     * transient; everything else (a conflict result, a second writer, an abort, a plain error) returns or throws at once.
+     */
+    private placeWithRetry;
+    /** The test fault for this file on this attempt (tests may inject only on the first attempt), or undefined. */
+    private injectedPromotionFault;
+    /**
+     * F-EXIT-WAITS-CAPTURE: session exit ends an in-flight capture of an agent's round at the next file, so teardown does
+     * not wait for the rest of it. The blobs captured so far leave with the task's state. Only a capture that asked for
+     * this stops: the capture inside an approved apply always finishes, because exit must not lose an approved change.
+     */
+    cancelCapture(): void;
+    private assertCaptureNotCancelled;
     /**
      * Bind a reviewed diff to this shadow's pre-task hashes. Team execution stores
      * these immutable bundles instead of Git commits; the integration gate uses
@@ -163,7 +224,104 @@ export declare class WorkspaceShadow {
      * remains bound to the bundle's reviewed base hash, never to whatever bytes
      * happened to exist when the integration snapshot was created.
      */
-    applyDiffToShadow(diff: readonly ReviewedShadowDiffFile[]): Promise<void>;
+    applyDiffToShadow(diff: readonly ReviewedShadowDiffFile[], 
+    /** §9.4 — where reference entries live (a team merge plan: the group's content store); streamed from there. */
+    sourceStore?: BlobStore): Promise<void>;
+    private applyDiffToShadowWith;
+    /**
+     * P63 Slice 2 (§9.4) — capture one changed file: copied into this instance's blob store through the anchored helper
+     * (the same chain anchoring as `readShadowTextFile`) first, checked as strict UTF-8 text and carried as the
+     * reference only (`content: ''`, §9.4: in-memory structures hold references only) whatever its size.
+     * `expectedSha256` (a modified file's hash from the stat pass) must match too.
+     */
+    private captureFile;
+    /**
+     * §9.4 — the text of a reference entry, read from this instance's blob store and verified (hash, size, strict UTF-8)
+     * for the one consumer that needs it now; never kept. Inline (legacy) entries return their text. A large entry is
+     * never read whole: callers excerpt it (`readPostImageHead`) or treat it whole-file.
+     */
+    readDiffText(file: ShadowDiffFile): Promise<string>;
+    /** P63 Slice 2 R1-F6 — the §5.7 / §7.4 lists and counts of the review INDEX, from the last capture. */
+    reviewIndexContext(): {
+        privateFolders: Array<{
+            path: string;
+            group: 'hidden' | 'dependencies' | 'rebuild-output' | 'codevibe';
+        }>;
+        notApplicable: string[];
+        folderChanges?: {
+            changed: number;
+            created: number;
+            deleted: number;
+        };
+    };
+    /**
+     * P63 Slice 2 R1-F1 — the user's file a change modifies or deletes is text: its current bytes are streamed through the
+     * anchored copy into this task's blob store and checked as strict UTF-8, so a binary original (a deleted `clip.mp4`, a
+     * `logo.png` overwritten with text) stops the task with the binary reason before any review, as the strict decode of
+     * the promote preflight did before Slice 2 — and its bytes never reach a review bundle. `required`: the file must
+     * exist (a deletion); for a modification a file the user removed meanwhile is left to the conflict check.
+     */
+    private assertRealBaseIsText;
+    /**
+     * P63 Slice 2 (§8.1) — the verified blob sources of a review bundle for `files`: each new version from this instance's
+     * blob store (`ownPostImageBlob`), each base version copied from the real file through the anchored helper and kept
+     * only when it is still exactly the recorded base (a base the user changed since the task started is `null` — the
+     * reviewers then see the new version and the diff is against nothing, never against bytes that were not the base).
+     */
+    reviewBundleSources(files: readonly ShadowDiffFile[]): Promise<Array<{
+        path: string;
+        change_kind: ShadowDiffFile['change_kind'];
+        after: {
+            store: BlobStore;
+            ref: BlobRef;
+        } | null;
+        before: {
+            store: BlobStore;
+            ref: BlobRef;
+        } | null;
+        modes: {
+            before: number | null;
+            after: number | null;
+        };
+        base?: {
+            sha256: string;
+            size: number | null;
+            changed: boolean;
+        };
+    }>>;
+    /** §9.4 — this instance's blob store (a team bundle's source when it is published to the group's content store). */
+    contentBlobStore(): BlobStore;
+    /**
+     * P63 Slice 2 (§9.4 W3d) — the first `maxBytes` of a post-image in this instance's blob store (excerpts of large
+     * files for the engine projection; never the whole file).
+     */
+    readPostImageHead(ref: BlobRef, maxBytes: number): Promise<Buffer>;
+    /**
+     * P63 Slice 2 (§9.4 W3c) — the reference of `file`'s post-image in this instance's blob store: its capture blob when
+     * that blob is here (same size, bound to the content's hash), else the content stored now (deduplicated by hash).
+     */
+    private ownPostImageBlob;
+    /**
+     * P63 Slice 2 (S2-9) — the APPLYING marker's promotion authority as post-images plus the CAS recovery authority, read
+     * from whichever form the marker holds: the shard-backed promote manifest (every shard read and verified, every
+     * entry's base hash checked against this instance's baseline, the CAS authority recomputed with
+     * `buildCasRecoveryAuthority` exactly as marker parsing does for the inline form) or the legacy inline lists. Null when
+     * the marker is not APPLYING.
+     */
+    readPromotionAuthority(): Promise<{
+        postImages: Array<{
+            path: string;
+            hash: string | null;
+            mode: number | null;
+        }>;
+        casRecovery: CasRecoveryAuthority[];
+    } | null>;
+    /**
+     * P63 Slice 2 (S2-9) — the change manifest of a promoted set: per path its kind, post-mode, pre-task base hash and
+     * post-image blob reference (the post-hash promotion computed; size from the content). Pure: equal promoted sets
+     * build equal roots, so promotion re-entry compares roots instead of inline lists.
+     */
+    private promoteManifestFor;
     private captureCopyDiff;
     /**
      * Materialize the changed-file SET over the TRACKED SET ONLY (#PM-1/#PM-2):
@@ -183,7 +341,24 @@ export declare class WorkspaceShadow {
      * "could not promote — N files at <paths>". Returns the conflicts/errors so
      * the caller renders them; throws only on a marker-write failure.
      */
+    private recordKept;
+    /**
+     * §9.3: the files the last promote left in the user's folder, relative to it, each returned once. The caller lists
+     * them in the task summary and on the phone, whatever the promote's outcome.
+     */
+    /**
+     * §9.3: `pending-restore` entries are retried every 10 seconds while the desktop runs. One pass over this snapshot's
+     * open entries; the paths still pending. Nothing new is applied here: once none is pending the ordinary promotion
+     * finishes the task, exactly as at a start.
+     */
+    retryPendingNoLinkRestores(): Promise<string[]>;
+    takeKeptFiles(): string[];
     promote(diff: ShadowDiffFile[], opts?: {
+        /**
+         * §9.4 — where reference entries of `diff` that are not in this instance's store live (a team merge plan: the
+         * group's content store). Each is stream-copied into this instance's store before APPLYING.
+         */
+        sourceStore?: BlobStore;
         /**
          * PHASE-589/469 W3.1 (C1) — capture a durable revert manifest for a TEAM
          * track. For each in-scope, hash-matched file the promote is about to
@@ -223,9 +398,12 @@ export declare class WorkspaceShadow {
         recovered: boolean;
         promoted: string[];
         conflicts: string[];
+        /** `noLinkPending`: a §9.3 step to retry while the desktop runs; `temporarilyAt`: where its original is meanwhile. */
         errors: Array<{
             path: string;
             error: string;
+            noLinkPending?: true;
+            temporarilyAt?: string;
         }>;
         /**
          * PHASE-589/469 W3.1 (C1) — the captured pre-image manifest entries (only
@@ -235,7 +413,18 @@ export declare class WorkspaceShadow {
          * entry per file that the promote actually applied.
          */
         manifestEntries: PromoteManifestInput[];
+        /**
+         * P63 Slice 2 (F-S2-6c) — on `applied`, the exact post-image (hash, mode) of every diff path, as this call verified
+         * it in the real tree (the same values the PROMOTED marker records). Absent where the volume does not track modes
+         * (the real mode is then the volume's, not the post-image's) and on every other outcome; callers then read the real
+         * tree themselves.
+         */
+        postImages?: ReadonlyMap<string, {
+            hash: string | null;
+            mode: number | null;
+        }>;
     }>;
+    private promoteWith;
     /**
      * Tear down the shadow on every non-`TaskAuthorized` terminal (reject/abort,
      * each Halted reason, parser-empty, session-end, crash). Leaves the real tree
@@ -263,6 +452,8 @@ export declare class WorkspaceShadow {
         helperTimeoutMs?: number;
         signal?: AbortSignal;
     }): Promise<boolean>;
+    /** Sized from the tree when it is still at its name; a tombstone being finished has only the baseline to go by. */
+    private treeRemovalBudgetMs;
     private retirePhysicalCopyRootIfUnused;
     private retainExposureWriteAuthority;
     private runOwnedStateFileWrite;
@@ -339,7 +530,18 @@ export declare function reopenShadow(recovered: RecoveredShadow, env?: ShadowEnv
  * intends to recover). A `promoted` shadow whose code already landed is GC'd
  * (its real tree is done) regardless of TTL.
  */
+/**
+ * F-RESTART-NOT-RESUMED: a reopened task runs under a new id while its copy keeps its first one, so the reviewer records
+ * made under the new id have no instance to retire their folders. `rmdir` only: anything still inside stays and the exit
+ * audit reports it.
+ */
+export declare function removeEmptyTaskFolders(taskId: string, env?: ShadowEnv): Promise<void>;
+/** §6.2: what the spawn sweep could not clear. A task listed here, or any task after a failed sweep, is not captured yet. */
+interface SpawnSweepReport {
+    spawnBlockedTaskIds?: ReadonlySet<string>;
+    spawnSweepFailed?: boolean;
+}
 export declare function reapOrphanShadows(keepTaskIds: ReadonlySet<string>, env?: ShadowEnv): Promise<{
     reaped: string[];
     retained: string[];
-}>;
+} & SpawnSweepReport>;