@quantiya/codevibe-core 2.0.7 → 2.0.9

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

@@ -1,4 +1,19 @@
+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. */
@@ -10,28 +25,141 @@ export interface ShadowDiffFile {
     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' | 'promoted';
-/** Injected for deterministic tests; production uses the real fs/git. */
+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 {
-    /** Sleep between git-op retries. */
+    /** @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;
 }
 /**
- * CP-14 Wave A (`team.execution=worktree_merge`) — make the shadow worktree a
+ * 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). Git-only: a non-git workspace is ineligible.
+ * deterministic merge-train input).
  */
 export interface TrackBranchSpec {
     /** The persistent branch name, e.g. `codevibe/track/<groupId>/<trackIndex>`. */
@@ -51,33 +179,69 @@ export declare class WorkspaceShadow {
     readonly workingDir: string;
     /** The shadow dir the implementor spawns in (its cwd). */
     readonly shadowDir: string;
-    /** True when the shadow is a `git worktree` (vs a non-git file copy). */
-    readonly isGit: boolean;
+    private readonly shadowDirIdentity;
+    private readonly snapshotRootAuthority;
+    private readonly workingDirIdentity;
+    private readonly workspaceRootAuthority;
+    private readonly ownerProcessIdentity;
+    private readonly physicalCopyBytes;
+    private readonly physicalCopyScope;
     /**
-     * CP-14 Wave A — the persistent track branch this shadow worktree sits on
-     * (`worktree_merge` only); undefined on the legacy detached-HEAD path. When
-     * set, the seam commits to this branch (see {@link commitTrack}) instead of
-     * the in-place promote.
+     * Legacy marker retained for recovery compatibility. New shadows are always
+     * CodeVibe-managed filesystem snapshots, so this is always false.
      */
-    readonly trackBranch?: string;
+    readonly isGit: boolean;
     /** Paths (RELATIVE to workingDir) materialized into the shadow — the TRACKED SET. */
     private trackedSet;
     /** Pre-task content hash per tracked path (null = absent at create), #PR-2. */
     private preTaskHashes;
+    /** Pre-task POSIX mode per tracked path (null = absent at create). */
+    private preTaskModes;
     /** The per-task durable state dir (under the app-data dir), survives restarts. */
     private readonly stateDir;
+    /** This snapshot instance's marker; sibling restarts never overwrite it. */
+    private readonly stateFile;
+    /** Original durable state authorities; public pathnames are never re-adopted. */
+    private readonly stateRootAuthority;
+    private readonly stateDirAuthority;
+    private stateFileAuthority?;
+    /**
+     * Same-instance atomic writes that may have published a replacement inode
+     * before their outer promise updates `stateFileAuthority`. A concurrent
+     * reader joins this narrow handoff instead of misclassifying our authenticated
+     * commit as a pathname replacement.
+     */
+    private readonly stateFileWriteAdmissions;
+    private exposureFileAuthority?;
+    private stateResourcesRetiredInProcess;
     private readonly env;
-    private readonly sleep;
+    private readonly maxStateMarkerBytes;
+    private promotedInProcess;
+    private cleanupBlocked;
+    private cleanupOwners;
+    private unresolvedAuthorityRetention?;
     private constructor();
     /** @internal — test introspection of the tracked set. */
     get trackedSetForTests(): ReadonlySet<string>;
+    /** Exact user-root instance authenticated into reviewed team bundles. */
+    rootAuthorityForBundle(): WorkspaceRootAuthority;
+    /** Exact disposable-root incarnation required by every task-scoped consumer. */
+    snapshotAuthorityForDispatch(): WorkspaceRootAuthority;
+    /**
+     * Exact recovery-instance comparator. A task id or pathname alone is not an
+     * ownership token: restart races may leave two UUID snapshots for one task,
+     * and a hostile pathname replacement may reuse the public name. Recovery and
+     * teardown use this full marker/root authority check before installing or
+     * reconciling a durable instance.
+     */
+    matchesRecoveredInstance(recovered: RecoveredShadow): boolean;
     /**
      * Create the shadow BEFORE the round-0 spawn + record the TRACKED SET.
      *
-     * - git repo → `git worktree add` (PRIMARY: cheap, shared object store, real
-     *   `.git` so the agent's own `npm test`/`git diff` work).
-     * - non-git → file-copy of `workingDir` excluding `.git`/secrets/gitignored
-     *   + symlink the real `node_modules` (read-through, never a promote target).
+     * Every workspace, Git repository or not, is materialized through the same
+     * CodeVibe-owned filesystem snapshot. Regular files use copy-on-write clones
+     * where the filesystem supports them and fall back to a normal copy only when
+     * cloning is unavailable. Git is never probed or invoked on this path.
      *
      * Fail-closed (#SR-2): a create failure throws — the caller surfaces it and
      * does NOT spawn against a half-built shadow.
@@ -94,42 +258,32 @@ export declare class WorkspaceShadow {
      *                shadow (NOT merely "absent from shadow", which would falsely
      *                flag every excluded path → catastrophic-delete).
      *
-     * git → `git diff` (already tracked-scoped); non-git → tree-compare bounded to
-     * the tracked set. Across revise rounds the diff is CUMULATIVE shadow-vs-real.
+     * Snapshots use a tree compare bounded to the tracked set. Across revise
+     * rounds the diff is CUMULATIVE shadow-vs-real.
      */
     captureDiff(): Promise<ShadowDiffFile[]>;
-    private captureGitDiff;
-    private captureCopyDiff;
     /**
-     * CP-14 Wave A (`worktree_merge`) — commit the shadow worktree's full content
-     * (the dirty-replay baseline + the implementor's edits + any new untracked
-     * files) onto the persistent track branch, and return the committed tip SHA
-     * (the merge-train input). This REPLACES the legacy in-place {@link promote}
-     * for track shadows: the user tree is NOT touched here — the change lands only
-     * when the merge gate promotes the integration tip.
-     *
-     * Deterministic for recovery-replay stability: pinned bot identity + a pinned
-     * `@0` author/committer date + hooks/gpg disabled, so a re-run over identical
-     * content yields an identical SHA. `--allow-empty` so a no-op track still
-     * produces a real base-rooted tip (no `#EF-1`-style born-halt; the merge-train
-     * fast-forwards it).
-     *
-     * Requires a git track-branch shadow (created with `opts.trackBranch`); throws
-     * otherwise — a missing tip must FAIL CLOSED upstream, never be silently empty.
-     *
-     * REVIEW-INTEGRITY (#598-11 parity, Stage-1 HIGH): the commit is built from the
-     * REVIEWED, drift-checked `diff` content (the in-memory `ShadowDiffFile[]` the
-     * caller already validated against the reviewed snapshot) via a THROWAWAY index
-     * + `git hash-object`/`commit-tree` — the live worktree is NEVER re-read. This
-     * matches the legacy `promote(diff)`, which applies the captured `diff[].content`
-     * (not a re-read), so a detached writer that mutates the worktree after the
-     * drift-check cannot inject UNREVIEWED bytes into the track tip. The branch sits
-     * at the pinned base (its only commit-to-be) and the diff is "everything vs
-     * base", so `read-tree base` + apply-diff reconstructs exactly the reviewed tree.
+     * 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
+     * `base_hash` for the same no-clobber check as single-task promotion.
+     */
+    bindReviewedDiff(diff: readonly ShadowDiffFile[]): ReviewedShadowDiffFile[];
+    /**
+     * Durably bind the exact artifact submitted for review to this snapshot.
+     * The private state marker is fsynced before the caller may submit the
+     * artifact to the engine. A revise round atomically replaces the prior
+     * authority; completion/discard removes the instance marker with the copy.
      */
-    commitTrack(diff: readonly ShadowDiffFile[], opts?: {
-        message?: string;
-    }): Promise<string>;
+    persistReviewedDiff(diff: readonly ShadowDiffFile[]): Promise<void>;
+    /** Read the crash-durable reviewed artifact, or null for an unreviewed snapshot. */
+    readReviewedDiff(): Promise<ShadowDiffFile[] | null>;
+    /**
+     * Apply already-reviewed bytes inside this disposable shadow only. Promotion
+     * 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>;
+    private captureCopyDiff;
     /**
      * Materialize the changed-file SET over the TRACKED SET ONLY (#PM-1/#PM-2):
      * copy the shadow's changed files onto the real tree (create/overwrite) +
@@ -169,15 +323,23 @@ export declare class WorkspaceShadow {
             promoteOrderBase: number;
             persist: (entries: PromoteManifestInput[]) => Promise<void>;
         };
+        /** Refuse to begin a new real-tree mutation after session cancellation. */
+        signal?: AbortSignal;
     }): Promise<{
         /**
-         * Whether this call actually MATERIALIZED files onto the real tree. `false`
-         * means it was an idempotent no-op (a prior promote already landed via the
-         * durable `promoted` marker — a packet + recovery double-fire). The caller
-         * uses this to suppress duplicate `promoting`/`promoted` progress + the
-         * "Applied N files" milestone on a re-delivered TaskAuthorized packet.
+         * Truthful real-tree state at return. `unresolved` means an APPLYING marker
+         * still owns one or more possible post-images; callers must retain/re-drive
+         * recovery authority and must not report an ordinary failure as terminal.
+         */
+        mutationState: 'none' | 'applied' | 'unresolved';
+        /**
+         * On success, whether this call actually materialized files. On failure,
+         * `true` means possible post-images remain under APPLYING authority. Callers
+         * must inspect `mutationState` before using this for progress suppression.
          */
         materialized: boolean;
+        /** True when an `applying` crash marker was fully reconciled this call. */
+        recovered: boolean;
         promoted: string[];
         conflicts: string[];
         errors: Array<{
@@ -198,37 +360,53 @@ export declare class WorkspaceShadow {
      * each Halted reason, parser-empty, session-end, crash). Leaves the real tree
      * byte-identical to its pre-task state (a discard never touched it).
      *
-     * git-worktree → `git worktree remove --force` (+ `git worktree prune`),
-     * NEVER raw `rm -rf` (leaks `.git/worktrees/`, #GC-2). Non-git copy → `rm -rf`
-     * (the symlinked `node_modules` is unlinked, never follow-delete).
+     * Snapshots are ordinary filesystem directories and use recursive removal.
      *
      * Before teardown, terminate task-spawned children rooted in the shadow; if
      * removal still fails (stray watcher), the durable marker is left in place so
      * the next-startup GC retries (#GC-2 lazy cleanup).
      *
-     * `preserveStateDir` (the ORPHAN-teardown mode, restart-race fix 2026-06-11):
-     * tear down ONLY this instance's uuid-suffixed `shadowDir` and NEVER the
-     * per-task SHARED `stateDir`. A restart reuses the SAME taskId, so a fresh
-     * shadow B's durable `pending` marker lives in the same `stateDir`; tearing
-     * down the orphaned old instance A with a full `discard()` would `fs.rm` that
-     * SHARED dir and delete B's authorized-but-pending #PR-4 marker (B becomes
-     * unrecoverable after a crash — a sealed-LOCK violation). The orphan branch in
-     * QuorumLoop.discardShadow passes `{ preserveStateDir: true }` because the
-     * shared `stateDir` belongs to the LIVE mapped shadow B, not the orphan.
+     * Each instance owns a UUID-suffixed marker. Cleanup removes only that marker,
+     * so a replacement instance for the same task remains recoverable. The
+     * `preserveStateDir` option remains for source compatibility only.
      */
     discard(opts?: {
         preserveStateDir?: boolean;
+        /**
+         * The team integration path may retire its per-snapshot APPLYING marker
+         * only after the group-level PREPARED journal durably owns the same exact
+         * pre/post-image authority. Ordinary single-task/session cleanup must never
+         * set this flag.
+         */
+        applyingAuthorityRetired?: boolean;
     }): Promise<void>;
+    private retainExposureWriteAuthority;
+    private runOwnedStateFileWrite;
+    private acceptExposureSnapshot;
     /**
-     * Orphan-teardown shorthand (restart-race fix 2026-06-11): tear down ONLY this
-     * instance's `shadowDir` (worktree-aware per #GC-2) and PRESERVE the SHARED
-     * per-task `stateDir` — used by `QuorumLoop.discardShadow`'s instance-mismatch
-     * branch when a newer shadow (same taskId) has replaced this one in the map.
+     * Prove idempotent terminal cleanup without adopting replacement pathnames.
+     * A present original marker/bridge returns false so ordinary disposal can
+     * continue. A displaced original state directory is retained fail-closed.
      */
+    private exactStateResourcesAreRetired;
+    /** Reclaim a renamed original without ever adopting its public replacement. */
+    private discardDisplacedSnapshot;
+    private refreshRetainedStateAuthorities;
+    /** Orphan teardown is ordinary instance-owned teardown. */
     discardOrphan(): Promise<void>;
-    private removeGitWorktree;
+    /** Fail-closed preflight used before callers alter their in-memory ownership. */
+    assertCanDiscard(): Promise<void>;
+    /** Strict disposal guard: malformed/unreadable authority is retained too. */
+    private assertDiscardable;
+    /**
+     * Atomically retire every promotion/review transition before deleting the
+     * disposable tree. DISPOSING is intentionally terminal and immutable: cleanup
+     * retries may consume it, but no marker writer may replace it.
+     */
+    private beginDisposal;
     private writeStateMarker;
     private readStateMarker;
+    private readStateMarkerSnapshot;
     /**
      * Read the durable promote-state marker WITHOUT mutating the tree (#PR-4). The
      * QuorumLoop checks this BEFORE `captureDiff` so a re-delivered TaskAuthorized
@@ -239,11 +417,20 @@ export declare class WorkspaceShadow {
      * idempotency guard is still the authority).
      */
     readPromoteState(): Promise<ShadowPromoteState | null>;
+    /** Durably prevent cwd deletion after process-tree verification failed. */
+    blockDiscardForUnverifiedChildren(owners?: readonly ProcessCleanupOwner[]): Promise<void>;
+    /** Persistently retain reviewed source bytes while bundle publication is unresolved. */
+    retainForUnresolvedAuthority(retention: UnresolvedBundlePublicationRetention): Promise<void>;
+    unresolvedBundlePublicationForCleanup(): UnresolvedBundlePublicationRetention | null;
+    /** Clear retention only after the durable store proves publication is readable/reconciled. */
+    clearUnresolvedAuthorityRetention(): Promise<void>;
+    /** Retry persisted process-tree quiescence and retire the cleanup block. */
+    retryBlockedCleanup(): Promise<boolean>;
+    /** Write the independent in-snapshot non-disposable recovery surface. */
+    private writeCleanupBlockAnchor;
     /**
-     * Reconstruct a `WorkspaceShadow` from a durable marker (a crash lost the
-     * in-memory tracked set + pre-task hashes). The tracked set is re-derived
-     * from the live shadow + real tree; promote then re-captures the diff. Used
-     * ONLY by the recovery/GC paths (`reopenShadow` / `reapOrphanShadows`).
+     * Reconstruct from the marker's exact immutable baseline. Recovery never
+     * derives overwrite authority from the moving user tree.
      */
     static fromRecovered(recovered: RecoveredShadow, env?: ShadowEnv): Promise<WorkspaceShadow>;
 }
@@ -252,24 +439,69 @@ export interface RecoveredShadow {
     taskId: string;
     shadowDir: string;
     workingDir: string;
-    isGit: boolean;
+    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[]>;
 /**
- * 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.
+ * 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 listRecoverableShadows(env?: ShadowEnv): Promise<RecoveredShadow[]>;
+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;
+}
 /**
- * Reconstruct a `WorkspaceShadow` from a durable marker so the recovery path
- * can re-run promote/discard against an already-created shadow. The tracked set
- * + pre-task hashes are re-derived from the live shadow vs the real tree (a
- * crash lost the in-memory state). For a git worktree this is `git status`; for
- * a copy shadow it is a tree-compare. The promote then re-captures the diff.
+ * 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.
  */
 export declare function reopenShadow(recovered: RecoveredShadow, env?: ShadowEnv): Promise<WorkspaceShadow | null>;
 /**
@@ -287,4 +519,67 @@ 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 {};

package/dist/orchestration-shell/__tests__/advisory-attachment-journal.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/orchestration-shell/__tests__/direct-file-delete.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/orchestration-shell/__tests__/flag-command.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/orchestration-shell/__tests__/halt-message-wire-content.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/orchestration-shell/__tests__/planner-offer-e1.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/orchestration-shell/__tests__/workspace-shutdown.test.d.ts

@@ -0,0 +1 @@
+export {};