@quantiya/codevibe-claude-plugin 2.0.13 → 2.0.15

package/node_modules/@quantiya/codevibe-core/dist/local-executor/shadow-recovery.d.ts

@@ -0,0 +1,273 @@
+import { type AnchoredFsIdentity, type AnchoredCommittedFile, 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 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';
+/** A recovered shadow state (read from the durable per-task marker). */
+export interface RecoveredShadow {
+    taskId: string;
+    shadowDir: string;
+    workingDir: string;
+    shadowDirIdentity: AnchoredFsIdentity;
+    snapshotRootAuthority: WorkspaceRootAuthority;
+    workingDirIdentity: AnchoredFsIdentity;
+    workspaceRootAuthority: WorkspaceRootAuthority;
+    ownerProcessIdentity: ProcessIdentity;
+    physicalCopyBytes: number;
+    isGit: false;
+    promoteState: ShadowPromoteState;
+    createdAtMs: number;
+    /** The durable state dir for this task (for cleanup). */
+    stateDir: string;
+    /** Exact instance marker (sibling restarts use separate files). */
+    stateFile: string;
+    /** Exact durable state container and marker authorities from the scan. */
+    stateRootAuthority: WorkspaceRootAuthority;
+    stateDirAuthority: WorkspaceRootAuthority;
+    stateFileAuthority: AnchoredPathIdentity;
+    /** Scan-time bridge incarnation, when disposal/exposure recovery has one. */
+    exposureFileAuthority?: AnchoredPathIdentity;
+    /** Immutable tracked paths and pre-task hashes, including deleted/absent paths. */
+    baseline: Array<{
+        path: string;
+        hash: string | null;
+        mode?: number | null;
+    }>;
+    promotePostHashes?: Array<{
+        path: string;
+        hash: string | null;
+        mode?: number | null;
+    }>;
+    casRecovery?: CasRecoveryAuthority[];
+    disposalSnapshotAuthority?: WorkspaceRootAuthority;
+    disposalShadowIdentity?: AnchoredFsIdentity;
+    /** Exact reviewed artifact persisted before authorization could resolve. */
+    reviewedDiff?: ShadowDiffFile[];
+    cleanupBlocked?: boolean;
+    cleanupOwners?: ProcessCleanupOwner[];
+    unresolvedAuthorityRetention?: UnresolvedBundlePublicationRetention;
+}
+/**
+ * Read every durable per-task shadow marker under the state root. The reconnect/
+ * startup recovery (#PR-4) reads these to find an authorized-but-pending shadow
+ * to promote; the GC reaper (#GC-1) reads them to delete orphaned shadows.
+ */
+interface ShadowMarkerScan {
+    recovered: RecoveredShadow[];
+    exposureRetentions: Array<{
+        marker: ExposureRetentionMarker;
+        stateDir: string;
+        stateFile: string;
+        stateFileAuthority: AnchoredPathIdentity;
+    }>;
+    /** Schema/placement-valid markers whose persisted snapshot incarnation moved. */
+    displacedSnapshots: DisplacedShadowMarkerRecord[];
+    /** Snapshot names protected by a syntactically instance-owned marker, valid or not. */
+    protectedDirNames: Set<string>;
+    /** Owned-looking authorities that were present but could not become operational. */
+    unresolved: Array<{
+        taskId: string;
+        path: string;
+        kind: 'state-directory' | 'state-marker' | 'exposure-marker';
+        detail: string;
+    }>;
+}
+export declare function scanShadowMarkers(env?: ShadowEnv): Promise<ShadowMarkerScan>;
+export declare function reconcileExposureRetentions(retentions: ShadowMarkerScan['exposureRetentions'], recovered: readonly RecoveredShadow[], physicalCopyScope: string, env: ShadowEnv, retained: string[], snapshotIncarnations: SnapshotIncarnationIndex | null): Promise<void>;
+export declare function reclaimDisplacedShadow(record: DisplacedShadowMarkerRecord, env: ShadowEnv, physicalCopyScope: string, opts: {
+    allowLiveOwner: boolean;
+    allowApplyingDisposal: boolean;
+    preserveStateDir: boolean;
+    expected?: {
+        shadowDir: string;
+        workingDir: string;
+        snapshotRootAuthority: WorkspaceRootAuthority;
+        ownerProcessIdentity: ProcessIdentity;
+        stateRootAuthority: WorkspaceRootAuthority;
+        stateDirAuthority: WorkspaceRootAuthority;
+        stateFileAuthority: RetainedStateFileAuthority;
+        exposureFileAuthority?: RetainedStateFileAuthority;
+    };
+    onStateFileAuthority?: (authority: RetainedStateFileAuthority) => void;
+    onExposureFileAuthority?: (authority: RetainedStateFileAuthority) => void;
+    snapshotIncarnations?: SnapshotIncarnationIndex | null;
+}): Promise<'reaped' | 'retained'>;
+export declare function reconcileDisplacedSnapshots(records: readonly DisplacedShadowMarkerRecord[], keepTaskIds: ReadonlySet<string>, ttlMs: number, now: number, physicalCopyScope: string, env: ShadowEnv, reaped: string[], retained: string[], snapshotIncarnations: SnapshotIncarnationIndex | null): Promise<void>;
+export declare function listRecoverableShadows(env?: ShadowEnv): Promise<RecoveredShadow[]>;
+/**
+ * Join or recover every known atomic writer owned by the supplied task ids
+ * before strict teardown inventory. This is a mutating reconciliation step,
+ * deliberately separate from `listShadowCleanupResidue`'s read-only audit.
+ */
+export declare function reconcileShadowPublicationAuthority(taskIds: ReadonlySet<string>, env?: ShadowEnv): Promise<void>;
+export interface ShadowCleanupResidue {
+    taskId: string;
+    path: string;
+    kind: 'recoverable-marker' | 'displaced-marker' | 'exposure-marker' | 'unresolved-authority' | 'state-directory' | 'snapshot-directory' | 'private-publication-authority';
+    detail?: string;
+}
+/**
+ * Exhaustive post-drain audit for exact task ids owned by one session. Unlike
+ * `listRecoverableShadows`, this intentionally reports non-operational and
+ * malformed authorities, empty owned state directories, snapshot/staging
+ * directories, and private publication records. Cleanup failures may be
+ * suppressed only when this inventory is empty.
+ */
+export declare function listShadowCleanupResidue(taskIds: ReadonlySet<string>, env?: ShadowEnv): Promise<ShadowCleanupResidue[]>;
+export declare function reapCrashedStateArtifacts(env: ShadowEnv): Promise<void>;
+/**
+ * Create a Git-independent filesystem snapshot: walk `workingDir` excluding
+ * repository metadata, secrets, caches, and generated output. Source files and
+ * private dependency inputs use clone-or-bounded-copy materialization; only
+ * source files enter the promotable tracked set.
+ */
+export declare function sealSnapshotTreeDurably(snapshotRoot: string, snapshotRootAuthority: WorkspaceRootAuthority, env: ShadowEnv): Promise<void>;
+export declare function createCopyShadow(workingDir: string, shadowDir: string, sourceRootAuthority: WorkspaceRootAuthority, copyFile: (source: string, destination: string, maxLogicalBytes?: number) => Promise<MaterializedFileMetadata>, excludedRoots?: readonly string[]): Promise<{
+    tracked: Set<string>;
+    metadata: Map<string, MaterializedFileMetadata>;
+}>;
+/** List every regular file under the shadow (RELATIVE), excluding excluded dirs + build-env. */
+export declare function listShadowRegularFiles(shadowDir: string, shadowRootAuthority: WorkspaceRootAuthority): Promise<string[]>;
+type PathBudget = MetadataBudget;
+export declare function createPathBudget(): 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;
+export declare function stateFileNameForShadow(shadowDir: string): string;
+export declare function exposureRetentionFileNameForShadow(shadowDir: string): string;
+export declare function writeExposureRetentionMarker(stateFile: string, marker: ExposureRetentionMarker, expectedStateDir: WorkspaceRootAuthority, onCommitted?: (fileAuthority: RetainedStateFileAuthority, stateDirAuthority: WorkspaceRootAuthority) => void): Promise<void>;
+/** Publish an exact, durable delete decision before recursive removal begins. */
+export declare function publishExposureDeleteDisposition(stateFile: string, marker: ExposureRetentionMarker, authority: WorkspaceRootAuthority, expectedStateDir: WorkspaceRootAuthority, onCommitted?: (fileAuthority: RetainedStateFileAuthority, stateDirAuthority: WorkspaceRootAuthority) => void): Promise<ExposureRetentionMarker>;
+/** Persist that the disposition completed and no physical bytes remain owned. */
+export declare function publishExposureReclaimed(stateFile: string, marker: ExposureRetentionMarker, expectedStateDir: WorkspaceRootAuthority, onCommitted?: (fileAuthority: RetainedStateFileAuthority, stateDirAuthority: WorkspaceRootAuthority) => void): Promise<ExposureRetentionMarker>;
+/** Retire a negative bridge only when its generated public name is absent. */
+export declare function removeExposureRetentionMarkerIfPublicAbsent(stateFile: string, publicShadowDir: string, expected: ExposureRetentionMarker, shadowRoot: string, physicalCopyScope: string, expectedStateDir?: WorkspaceRootAuthority, expectedFileAuthority?: RetainedStateFileAuthority): Promise<boolean>;
+export interface ExposureRetentionSnapshot {
+    marker: ExposureRetentionMarker;
+    stateFileIdentity: AnchoredPathIdentity;
+    stateDirAuthority: WorkspaceRootAuthority;
+}
+export declare function readExposureRetentionMarkerSnapshot(stateFile: string, taskId: string, shadowRoot: string, physicalCopyScope: string, expectedStateDir?: WorkspaceRootAuthority): Promise<ExposureRetentionSnapshot>;
+export declare function shadowLifecycleLockPath(shadowRoot: string, snapshotPath: string): string;
+export declare function buildCasRecoveryAuthority(root: WorkspaceRootAuthority, baseline: readonly {
+    path: string;
+    hash: string | null;
+    mode?: number | null;
+}[], postImages: readonly {
+    path: string;
+    hash: string | null;
+    mode?: number | null;
+}[]): CasRecoveryAuthority[];
+export declare function markerPostHashes(marker: ShadowStateFileV2 | null): Map<string, string | null> | undefined;
+export declare function markerPostModes(marker: ShadowStateFileV2 | null): Map<string, number | null> | undefined;
+export declare function assertExactApplyingAuthority(marker: ShadowStateFileV2, postHashes: ReadonlyMap<string, string | null>, postModes: ReadonlyMap<string, number | null>): void;
+export declare function validateReviewedDiff(files: readonly ShadowDiffFile[], baseline: ReadonlyMap<string, string | null>): void;
+export declare function resolveStateMarkerByteLimit(env: ShadowEnv): number;
+export declare function serializeStateMarker(marker: ShadowStateFileV2, maxBytes: number): string;
+/**
+ * A PENDING marker is accepted only when the same reviewed authority can later
+ * publish its largest ordinary lifecycle shape. Otherwise a byte-valid review
+ * at the limit could become permanently non-disposable merely by adding the
+ * APPLYING post-hash set and DISPOSING inode proof.
+ */
+export declare function assertStateMarkerLifecycleCapacity(marker: ShadowStateFileV2, maxBytes: number): void;
+/** Retire only the exact marker bytes authenticated during failed creation. */
+export declare function retireFailedCreateStateMarker(stateFile: string, taskId: string, stateRootAuthority: WorkspaceRootAuthority, maxBytes: number): Promise<void>;
+export declare function validateMarkerShape(value: unknown, expectedTaskId: string): ShadowStateFileV2;
+export declare function workspaceAuthorityOptions(env: ShadowEnv, target: string, boundary: string): {
+    helperTimeoutMs?: number;
+    testHangStage?: 'realpath' | 'lstat' | 'open' | 'stat' | 'close';
+};
+/** Fresh, bounded cleanup-only read used by live disposal and restart GC. */
+export declare function readStructurallyBoundStateMarker(record: DisplacedShadowMarkerRecord, env: ShadowEnv): Promise<StructurallyBoundStateSnapshot | null>;
+export declare function validateRecoveredPaths(marker: ShadowStateFileV2, stateFile: string, stateDir: string, requestedShadowRoot: string, requestedStateRoot?: string, env?: ShadowEnv, expectedStateAuthorities?: {
+    stateRootAuthority: WorkspaceRootAuthority;
+    stateDirAuthority: WorkspaceRootAuthority;
+    stateFileAuthority: RetainedStateFileAuthority;
+}): Promise<WorkspaceRootAuthority>;
+/**
+ * Validate an immutable DISPOSING marker after its snapshot inode has already
+ * been removed. Every still-existing authority path remains realpath/inode
+ * checked; the absent snapshot is accepted only by its exact owned lexical name.
+ */
+export declare function validateDisposedMarkerPaths(marker: ShadowStateFileV2, stateFile: string, stateDir: string, requestedShadowRoot: string, requestedStateRoot?: string, env?: ShadowEnv): Promise<void>;
+export declare function durableDirectoryAnchor(dir: string): string;
+export declare function ensurePrivateDirectory(dir: string, opts?: {
+    anchorPath?: string;
+    failDirectorySyncStage?: 'target-child' | 'target-parent';
+}): Promise<DurableDirectoryIdentity>;
+export declare function atomicWriteFile(filePath: string, content: string, expected: AnchoredWritePrecondition, beforeCommit?: () => Promise<void> | void, afterValidation?: () => Promise<void> | void, serializeInProcess?: boolean, expectedParent?: AnchoredFsIdentity, maxTargetBytes?: number, failDirectorySync?: boolean, publicationOwnerKey?: string): Promise<AnchoredCommittedFile>;
+export declare function isAnchoredWritePreconditionError(err: unknown): boolean;
+export declare function assertMarkerTransition(from: ShadowPromoteState | null, to: ShadowPromoteState, opts: {
+    allowApplyingDisposal: boolean;
+    cleanupState: 'preserve' | 'set' | 'clear';
+}): void;
+export declare function sameFsIdentity(a: AnchoredFsIdentity | null | undefined, b: AnchoredFsIdentity | null | undefined): boolean;
+export declare function sameWorkspaceIncarnation(left: WorkspaceRootAuthority, right: WorkspaceRootAuthority): boolean;
+/** One bounded root walk shared by every displaced record in a GC sweep. */
+export declare function buildSnapshotIncarnationIndex(shadowRootAuthority: WorkspaceRootAuthority, env?: ShadowEnv): Promise<SnapshotIncarnationIndex>;
+/** Locate one renamed original snapshot without ever adopting its current name. */
+export declare function findSnapshotIncarnation(shadowRootAuthority: WorkspaceRootAuthority, expected: WorkspaceRootAuthority, snapshotIncarnations?: SnapshotIncarnationIndex, env?: ShadowEnv): Promise<WorkspaceRootAuthority | null>;
+export declare function hasCleanupBlockAnchor(shadowDir: string): Promise<boolean>;
+interface SnapshotOwnerAnchor {
+    version: 1 | 2;
+    shadowDirIdentity: AnchoredFsIdentity;
+    /** Present only on v2; v1 is retained but never authorizes deletion. */
+    snapshotRootAuthority?: WorkspaceRootAuthority;
+    ownerProcessIdentity: ProcessIdentity;
+    physicalCopyScopeHash: string;
+    physicalCopyBytes: number;
+}
+export declare function physicalCopyScopeHash(scopeId: string): string;
+/**
+ * Resolve every atomic-publication transaction whose target parent is about
+ * to be recursively removed. Once the parent inode is gone, a crash record can
+ * no longer authenticate its prepared target/temp state, so deletion must
+ * never outrun this reconciliation boundary.
+ */
+export declare function reconcileSnapshotPublicationAuthorityBeforeRemoval(snapshotRootAuthority: WorkspaceRootAuthority): Promise<void>;
+/**
+ * Stable, bounded ownership key for every private publication transaction
+ * created on behalf of one task-state namespace. The private publication store
+ * hashes this value again before encoding its prefix; neither user paths nor
+ * task ids are disclosed in private record names.
+ */
+export declare function workspacePublicationAuthorityOwnerKey(stateRootCanonicalPath: string, taskId: string): string;
+export declare function writeSnapshotOwnerAnchor(ownerFile: string, snapshotRootAuthority: WorkspaceRootAuthority, ownerProcessIdentity: ProcessIdentity, physicalCopyScope: string, physicalCopyBytes: number, publicationOwnerKey: string): Promise<void>;
+export declare function readSnapshotOwnerAnchor(shadowDir: string): Promise<SnapshotOwnerAnchor | null>;
+/**
+ * Sum durable reservations under the cross-process quota fence. Invalid owner
+ * authority consumes the whole limit, so cloning can continue but a physical
+ * fallback cannot allocate unknown additional disk.
+ */
+export declare function scanPersistedPhysicalCopyBytes(shadowRoots: readonly RegisteredShadowRoot[], physicalCopyScope: string, limit: number): Promise<number>;
+interface RegisteredShadowRoot extends AnchoredFsIdentity {
+    path: string;
+    version?: 1;
+    canonicalPath?: string;
+    birthtimeNs?: string;
+}
+/**
+ * Durable quota-scope registry. Every process sharing `stateRoot` registers its
+ * physical shadow root before copying, so the aggregate scan cannot be split by
+ * different temp-root configuration.
+ */
+export declare function registerAndListQuotaShadowRoots(stateRoot: string, stateRootIdentity: WorkspaceRootAuthority, currentShadowRoot: string, currentShadowRootIdentity: WorkspaceRootAuthority, publicationOwnerKey: string, maxStateMarkerBytes: number, afterQuotaReferenceTaskEntry?: (stateDir: string) => Promise<void> | void, afterQuotaReferenceMarkerEntry?: (filePath: string) => Promise<void> | void, afterQuotaReferenceMarkerStat?: (filePath: string) => Promise<void> | void, failDirectorySync?: boolean): Promise<RegisteredShadowRoot[]>;
+interface CleanupBlockAnchorRead {
+    present: boolean;
+    cleanupOwners: ProcessCleanupOwner[];
+    unresolvedAuthorityRetention?: UnresolvedBundlePublicationRetention;
+    /** Exact validated marker incarnation, carried directly to retirement. */
+    fileIdentity?: AnchoredPathIdentity;
+}
+export declare function readCleanupBlockAnchor(shadowDir: string, expected: {
+    taskId: string;
+    shadowDir: string;
+    shadowDirIdentity: AnchoredFsIdentity;
+    snapshotRootAuthority: WorkspaceRootAuthority;
+}): Promise<CleanupBlockAnchorRead>;
+export declare function dedupeCleanupOwners(owners: readonly ProcessCleanupOwner[]): ProcessCleanupOwner[];
+export {};

package/node_modules/@quantiya/codevibe-core/dist/local-executor/workspace-shadow.d.ts

@@ -1,172 +1,14 @@
-import { type AnchoredFsIdentity, type AnchoredPathIdentity } from './anchored-fs';
 import type { PromoteManifestInput } from './durable-store';
 import { type ProcessCleanupOwner } from './process-tree';
-import { type ProcessIdentity } from './process-identity';
 import { type WorkspaceRootAuthority } from './workspace-authority';
-import { type MaterializationHangStage } from './workspace-materializer';
-export declare const MAX_TRACKED_FILE_LOGICAL_BYTES: number;
-export declare const MAX_TRACKED_WORKSPACE_LOGICAL_BYTES: number;
-/** Metadata is bounded independently of content bytes (zero-byte files still cost memory/inodes). */
-export declare const MAX_TRACKED_FILE_COUNT = 100000;
-export declare const MAX_TRACKED_PATH_BYTES: number;
-/** Reviewed text is intentionally bounded before any whole-file decode/read. */
-export declare const MAX_REVIEW_FILE_BYTES: number;
-export declare const MAX_PROMOTION_PREIMAGE_AGGREGATE_BYTES: number;
-/** Exact UTF-8 ceiling shared by every durable state-marker writer and reader. */
-export declare const MAX_STATE_MARKER_BYTES: number;
-/** Default TTL after which an orphaned shadow is GC-eligible (#GC-1). */
-export declare const DEFAULT_SHADOW_TTL_MS: number;
-/** `change_kind` values mirroring the pinned engine `ExecuteFirstFile` contract. */
-export type ShadowChangeKind = 'created' | 'modified' | 'deleted';
-/** One captured changed file in the shadow-vs-real diff (§D3). */
-export interface ShadowDiffFile {
-    /** Path RELATIVE to the workspace root (matches the engine contract). */
-    path: string;
-    change_kind: ShadowChangeKind;
-    /** The captured content (created/modified) or empty for deleted. */
-    content: string;
-    /** POSIX permission bits for the reviewed post-image (omitted by legacy records). */
-    mode?: 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. */
-    base_hash: string | null;
-    /** POSIX permission bits of the pre-task file, or null when absent. */
-    base_mode?: number | null;
-}
-/** Persisted promote-state marker (#PR-4). */
-type ShadowPromoteState = 'pending' | 'applying' | 'promoted' | 'disposing';
-export type CasHelperCrashStage = 'post-link' | 'post-displacement' | 'post-publication' | 'post-fsync' | 'post-close';
-export interface UnresolvedBundlePublicationRetention {
-    taskGroupId: string;
-    trackIndex: number;
-}
-interface CasRecoveryAuthority {
-    path: string;
-    operation: 'replace' | 'delete';
-    /** Deterministic from the persisted root/pre/post authority. */
-    recoveryName: string;
-    /** Deterministic public-entry quarantine used instead of check-then-unlink. */
-    quarantineName: string;
-    /** Deterministic prepared-byte name for replace/create operations. */
-    tempName?: string;
-    expectedHash: string | null;
-    expectedMode: number | null;
-    postHash: string | null;
-    postMode: number | null;
-}
-/** Injected for deterministic tests; production uses the real filesystem. */
-export interface ShadowEnv {
-    /** @deprecated Compatibility-only; filesystem snapshots do not use Git retries. */
-    sleep?: (ms: number) => Promise<void>;
-    /** Override the per-task state dir root (default `~/.codevibe/shadow-state`). */
-    stateRootDir?: string;
-    /** Override the shadow temp-dir root (default `os.tmpdir()`). */
-    shadowRootDir?: string;
-    /** @internal lower deterministic limit for serialized-marker boundary tests. */
-    maxStateMarkerBytes?: number;
-    /** TTL for the GC reaper. */
-    ttlMs?: number;
-    /** @internal lower deterministic workspace-authority helper deadline. */
-    workspaceAuthorityHelperTimeoutMs?: number;
-    /** @internal deterministic root/recovery authority stall seam. */
-    testHangWorkspaceAuthorityStage?: (target: string, boundary: string) => 'realpath' | 'lstat' | 'open' | 'stat' | 'close' | undefined;
-    /** Hook to terminate task-spawned children rooted in the shadow before teardown. */
-    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. */
-    forcePhysicalMaterialization?: boolean;
-    /** @internal lower deterministic materialization-helper deadline for tests. */
-    materializationHelperTimeoutMs?: number;
-    /** @internal deterministic live-workspace helper stall seam. */
-    testHangMaterializationHelperStage?: (source: string) => MaterializationHangStage | undefined;
-    /** Test seam after a tracked hash handle opens and before its bounded read. */
-    beforeTrackedHashRead?: (filePath: string) => Promise<void>;
-    /** Test seam after materialization and before hashing/marker persistence. */
-    afterShadowMaterialized?: (shadowDir: string) => Promise<void>;
-    /** Test seam immediately before each recovery-byte/directory durability sync. */
-    beforeSnapshotDurabilitySync?: (kind: 'file' | 'directory' | 'parent', target: string) => Promise<void> | void;
-    /** Test seam after copy and before the final durability seal + atomic exposure. */
-    beforeSnapshotExpose?: (stagingDir: string, finalDir: string) => Promise<void> | void;
-    /** @internal race seam after rename while the lifecycle fence is still held. */
-    afterSnapshotExposeRename?: (finalDir: string) => Promise<void> | void;
-    /** Test seam while the lifecycle fence is held, immediately before owner publication. */
-    beforeSnapshotOwnerPublish?: (stagingDir: string) => Promise<void> | void;
-    /** @internal failure seam after inode capture but before external authority commits. */
-    beforeExposureRetentionPublish?: (stagingDir: string, retentionFile: string) => Promise<void> | void;
-    /** Test seam after merge planning and before an integration snapshot is created. */
-    beforePromotionWrite?: (path: string) => Promise<void>;
-    /** Test seam before COMMIT; no live-workspace mutation has occurred yet. */
-    beforePromotionCommit?: (path: string) => Promise<void>;
-    /** Test seam after a promote temp file is fsynced, immediately before final CAS checks. */
-    afterPromotionPrepared?: (path: string) => Promise<void>;
-    /** Test seam after final live-parent validation; helper operations stay fd-anchored. */
-    afterPromotionParentValidation?: (path: string) => Promise<void>;
-    /** @internal lower deterministic CAS-helper deadline for tests. */
-    promotionHelperTimeoutMs?: number;
-    /** @internal deterministic CAS-helper target-filesystem stall seam. */
-    testHangPromotionHelperStage?: (path: string) => 'root' | 'parent' | 'target' | 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. */
-    afterPromotionTargetDisplaced?: (path: string, recoveryName: string) => Promise<void>;
-    /** Test seam immediately before the public target is atomically quarantined. */
-    beforePromotionTargetQuarantine?: (path: string, quarantineName: string) => Promise<void>;
-    /** Test seam immediately before identity-conditioned promotion quarantine unlink. */
-    beforePromotionFinalUnlink?: (path: string, quarantineName: string) => Promise<void>;
-    /** Test seam before rollback verifies/reverses a just-promoted path. */
-    beforePromotionRollback?: (path: string) => Promise<void>;
-    /** Test seam after an anchored marker parent is validated but before commit. */
-    beforeMarkerWriteCommit?: (filePath: string) => Promise<void>;
-    /** Test seam after marker CAS validation while the cross-process lock is held. */
-    afterMarkerWriteValidation?: (filePath: string) => Promise<void>;
-    /** @internal inject a post-publication directory-sync failure for a marker write. */
-    failMarkerDirectorySync?: (filePath: string) => boolean;
-    /** @internal inject a post-publication directory-sync failure for the quota registry. */
-    failQuotaRegistryDirectorySync?: boolean;
-    /** @internal pause after quota-lock acquisition and before strict state enumeration. */
-    beforeQuotaFenceScan?: () => Promise<void>;
-    /** @internal fail initial/retry shadow-root durability before acknowledgement. */
-    failShadowRootDirectorySyncStage?: 'target-child' | 'target-parent';
-    /** @internal fail initial/retry state-root durability before acknowledgement. */
-    failStateRootDirectorySyncStage?: 'target-child' | 'target-parent';
-    /** Test seam after disposal reads semantic state but before its CAS transition. */
-    afterDisposalStateRead?: (state: ShadowPromoteState) => Promise<void>;
-    /** Test-only: exercise the cross-process lock without the parent-process queue. */
-    disableMarkerWriteProcessLock?: boolean;
-    /** Test seam after an anchored snapshot parent is validated but before deletion. */
-    beforeShadowDeleteCommit?: (shadowDir: string) => Promise<void>;
-    /** Test seam after the owned snapshot was renamed and inode-verified. */
-    afterShadowTombstoneRename?: (shadowDir: string, tombstoneDir: string) => Promise<void>;
-    /** @internal exact lifecycle-lock release seam after snapshot cleanup. */
-    beforeShadowLifecycleFinalRemove?: (artifactPath: string) => Promise<void> | void;
-    /** Test seam after snapshot removal but before DISPOSING marker retirement. */
-    afterShadowRemovedBeforeMarkerCleanup?: (shadowDir: string) => Promise<void>;
-    /** @internal deterministic state-directory replacement before residue cleanup. */
-    beforeCrashedStateArtifactCleanup?: (stateDir: string) => Promise<void> | void;
-    /** @internal deterministic cleanup-block replacement before exact retirement. */
-    beforeCleanupBlockFinalRemove?: (artifactPath: string) => Promise<void> | void;
-}
-/**
- * Legacy migration contract from the branch-tip implementation. New creates
- * ignore this option and always use a Git-independent snapshot. Historically it made a worktree a
- * PERSISTENT track branch instead of a detached HEAD, so the merge-train can
- * merge the track's committed tip. `baseSha` is the ONE group base pinned BEFORE
- * the first track shadow is created (so every track roots at the same base — a
- * deterministic merge-train input).
- */
-export interface TrackBranchSpec {
-    /** The persistent branch name, e.g. `codevibe/track/<groupId>/<trackIndex>`. */
-    name: string;
-    /** The pinned group base commit the branch is created at. */
-    baseSha: string;
-}
+import { ReviewedShadowDiffFile, ShadowDiffFile, ShadowEnv, ShadowPromoteState, TrackBranchSpec, UnresolvedBundlePublicationRetention } from './shadow-protocol';
+import { RecoveredShadow } from './shadow-recovery';
+export { 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';
+export { listRecoverableShadows, reconcileShadowPublicationAuthority, listShadowCleanupResidue, assertPathCollectionBounds, } from './shadow-recovery';
+export type { RecoveredShadow, ShadowCleanupResidue } from './shadow-recovery';
+export { replaceWorkspaceFileIfMatches, removeWorkspaceFileIfMatches, } from './anchored-cas';
+export type { AcceptedAlternateImage } from './anchored-cas';
 /**
  * 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
@@ -441,71 +283,6 @@ export declare class WorkspaceShadow {
      */
     static fromRecovered(recovered: RecoveredShadow, env?: ShadowEnv): Promise<WorkspaceShadow>;
 }
-/** A recovered shadow state (read from the durable per-task marker). */
-export interface RecoveredShadow {
-    taskId: string;
-    shadowDir: string;
-    workingDir: string;
-    shadowDirIdentity: AnchoredFsIdentity;
-    snapshotRootAuthority: WorkspaceRootAuthority;
-    workingDirIdentity: AnchoredFsIdentity;
-    workspaceRootAuthority: WorkspaceRootAuthority;
-    ownerProcessIdentity: ProcessIdentity;
-    physicalCopyBytes: number;
-    isGit: false;
-    promoteState: ShadowPromoteState;
-    createdAtMs: number;
-    /** The durable state dir for this task (for cleanup). */
-    stateDir: string;
-    /** Exact instance marker (sibling restarts use separate files). */
-    stateFile: string;
-    /** Exact durable state container and marker authorities from the scan. */
-    stateRootAuthority: WorkspaceRootAuthority;
-    stateDirAuthority: WorkspaceRootAuthority;
-    stateFileAuthority: AnchoredPathIdentity;
-    /** Scan-time bridge incarnation, when disposal/exposure recovery has one. */
-    exposureFileAuthority?: AnchoredPathIdentity;
-    /** Immutable tracked paths and pre-task hashes, including deleted/absent paths. */
-    baseline: Array<{
-        path: string;
-        hash: string | null;
-        mode?: number | null;
-    }>;
-    promotePostHashes?: Array<{
-        path: string;
-        hash: string | null;
-        mode?: number | null;
-    }>;
-    casRecovery?: CasRecoveryAuthority[];
-    disposalSnapshotAuthority?: WorkspaceRootAuthority;
-    disposalShadowIdentity?: AnchoredFsIdentity;
-    /** Exact reviewed artifact persisted before authorization could resolve. */
-    reviewedDiff?: ShadowDiffFile[];
-    cleanupBlocked?: boolean;
-    cleanupOwners?: ProcessCleanupOwner[];
-    unresolvedAuthorityRetention?: UnresolvedBundlePublicationRetention;
-}
-export declare function listRecoverableShadows(env?: ShadowEnv): Promise<RecoveredShadow[]>;
-/**
- * Join or recover every known atomic writer owned by the supplied task ids
- * before strict teardown inventory. This is a mutating reconciliation step,
- * deliberately separate from `listShadowCleanupResidue`'s read-only audit.
- */
-export declare function reconcileShadowPublicationAuthority(taskIds: ReadonlySet<string>, env?: ShadowEnv): Promise<void>;
-export interface ShadowCleanupResidue {
-    taskId: string;
-    path: string;
-    kind: 'recoverable-marker' | 'displaced-marker' | 'exposure-marker' | 'unresolved-authority' | 'state-directory' | 'snapshot-directory' | 'private-publication-authority';
-    detail?: string;
-}
-/**
- * Exhaustive post-drain audit for exact task ids owned by one session. Unlike
- * `listRecoverableShadows`, this intentionally reports non-operational and
- * malformed authorities, empty owned state directories, snapshot/staging
- * directories, and private publication records. Cleanup failures may be
- * suppressed only when this inventory is empty.
- */
-export declare function listShadowCleanupResidue(taskIds: ReadonlySet<string>, env?: ShadowEnv): Promise<ShadowCleanupResidue[]>;
 /**
  * Reconstruct from a validated instance marker so recovery can re-run
  * promote/discard against an already-created filesystem snapshot.
@@ -526,67 +303,3 @@ export declare function reapOrphanShadows(keepTaskIds: ReadonlySet<string>, env?
     reaped: string[];
     retained: string[];
 }>;
-export declare function assertPathCollectionBounds(paths: readonly string[], label: string): void;
-export interface AcceptedAlternateImage {
-    hash: string | null;
-    mode: number | null;
-}
-/** Hardened reverse-apply surface shared by promotion and durable revert. */
-export declare function replaceWorkspaceFileIfMatches(args: {
-    workingDir: string;
-    workspaceRootAuthority: WorkspaceRootAuthority;
-    path: string;
-    content: string;
-    mode: number;
-    expectedHash: string | null;
-    expectedMode: number | null;
-    /** @internal deterministic last-commit race seam. */
-    beforeCommit?: () => Promise<void> | undefined;
-    /** @internal deterministic post-validation parent-swap seam. */
-    afterValidation?: () => Promise<void> | undefined;
-    /** @internal deterministic post-displacement recreation seam. */
-    afterDisplacement?: (recoveryName: string) => Promise<void> | undefined;
-    /** @internal deterministic public-target quarantine race seam. */
-    beforeTargetQuarantine?: (quarantineName: string) => Promise<void> | undefined;
-    /** @internal deterministic artifact-retirement race seam. */
-    beforeFinalUnlink?: (recoveryName: string) => Promise<void> | undefined;
-    /** @internal lower deterministic CAS-helper deadline for tests. */
-    helperTimeoutMs?: number;
-    /** @internal deterministic CAS-helper target-filesystem stall seam. */
-    testHangHelperStage?: 'root' | 'parent' | 'target';
-    /** @internal deterministic helper death after COMMIT/mutation. */
-    testCrashHelperStage?: CasHelperCrashStage;
-    /** Re-drive deterministic recovery names owned by an existing durable journal. */
-    allowPostImageRecovery?: boolean;
-    /** Exact terminal image that authorizes cleanup-only replay for same-path chains. */
-    acceptedAlternate?: AcceptedAlternateImage;
-}): Promise<boolean>;
-/** Hardened reverse-delete surface shared by promotion and durable revert. */
-export declare function removeWorkspaceFileIfMatches(args: {
-    workingDir: string;
-    workspaceRootAuthority: WorkspaceRootAuthority;
-    path: string;
-    expectedHash: string | null;
-    expectedMode: number | null;
-    /** @internal deterministic last-commit race seam. */
-    beforeCommit?: () => Promise<void> | undefined;
-    /** @internal deterministic post-validation parent-swap seam. */
-    afterValidation?: () => Promise<void> | undefined;
-    /** @internal deterministic post-displacement recreation seam. */
-    afterDisplacement?: (recoveryName: string) => Promise<void> | undefined;
-    /** @internal deterministic public-target quarantine race seam. */
-    beforeTargetQuarantine?: (quarantineName: string) => Promise<void> | undefined;
-    /** @internal deterministic artifact-retirement race seam. */
-    beforeFinalUnlink?: (recoveryName: string) => Promise<void> | undefined;
-    /** @internal lower deterministic CAS-helper deadline for tests. */
-    helperTimeoutMs?: number;
-    /** @internal deterministic CAS-helper target-filesystem stall seam. */
-    testHangHelperStage?: 'root' | 'parent' | 'target';
-    /** @internal deterministic helper death after COMMIT/mutation. */
-    testCrashHelperStage?: CasHelperCrashStage;
-    /** Re-drive deterministic recovery names owned by an existing durable journal. */
-    allowPostImageRecovery?: boolean;
-    /** Exact terminal image that authorizes cleanup-only replay for same-path chains. */
-    acceptedAlternate?: AcceptedAlternateImage;
-}): Promise<boolean>;
-export {};