@quantiya/codevibe-claude-plugin 2.0.13 → 2.0.15

package/node_modules/@quantiya/codevibe-core/dist/local-executor/anchored-cas.d.ts

@@ -0,0 +1,84 @@
+import { type AnchoredFsIdentity } from './anchored-fs';
+import { type WorkspaceRootAuthority } from './workspace-authority';
+import { CasHelperCrashStage, CasRecoveryAuthority } from './shadow-protocol';
+export declare function casRecoveryAuthorityFor(root: WorkspaceRootAuthority, rel: string, expectedHash: string | null, expectedMode: number | null, postHash: string | null, postMode: number | null): CasRecoveryAuthority;
+export interface AcceptedAlternateImage {
+    hash: string | null;
+    mode: number | null;
+}
+export declare class WorkspaceCasUnresolvedError extends Error {
+    readonly recoveryName?: string;
+    constructor(recoveryName?: string, detail?: string);
+}
+export declare function replacePromotedFile(workingDir: string, rel: string, content: string, mode: number, expectedHash: string | null, expectedMode: number | null, beforeCommit?: () => Promise<void> | undefined, afterValidation?: () => Promise<void> | undefined, afterDisplacement?: (recoveryName: string) => Promise<void> | undefined, beforeTargetQuarantine?: (quarantineName: string) => Promise<void> | undefined, beforeFinalUnlink?: (recoveryName: string) => Promise<void> | undefined, afterPrepared?: () => Promise<void> | undefined, expectedRootIdentity?: AnchoredFsIdentity | WorkspaceRootAuthority, helperOpts?: {
+    helperTimeoutMs?: number;
+    testHangStage?: 'root' | 'parent' | 'target';
+    testCrashStage?: CasHelperCrashStage;
+    allowPostImageRecovery?: boolean;
+    acceptedAlternate?: AcceptedAlternateImage;
+}): Promise<boolean>;
+export declare function removePromotedFile(workingDir: string, rel: string, expectedHash: string | null, expectedMode: number | null, beforeCommit?: () => Promise<void> | undefined, afterValidation?: () => Promise<void> | undefined, afterDisplacement?: (recoveryName: string) => Promise<void> | undefined, beforeTargetQuarantine?: (quarantineName: string) => Promise<void> | undefined, beforeFinalUnlink?: (recoveryName: string) => Promise<void> | undefined, expectedRootIdentity?: AnchoredFsIdentity | WorkspaceRootAuthority, helperOpts?: {
+    helperTimeoutMs?: number;
+    testHangStage?: 'root' | 'parent' | 'target';
+    testCrashStage?: CasHelperCrashStage;
+    allowPostImageRecovery?: boolean;
+    acceptedAlternate?: AcceptedAlternateImage;
+}): Promise<boolean>;
+/** 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>;

package/node_modules/@quantiya/codevibe-core/dist/local-executor/anchored-fs.d.ts

@@ -1,5 +1,5 @@
 import { type WorkspaceRootAuthority } from './workspace-authority.js';
-type PublicationPrivateRetirementStage = 'commit-rename' | 'commit-unlink' | 'commit-sync' | 'pending-rename' | 'pending-unlink' | 'pending-sync' | 'retiring-rename' | 'retiring-unlink' | 'retiring-sync' | 'disposed-rename' | 'disposed-unlink' | 'disposed-sync';
+type PublicationPrivateRetirementStage = 'disposed-publish' | 'commit-rename' | 'commit-unlink' | 'commit-sync' | 'pending-rename' | 'pending-unlink' | 'pending-sync' | 'retiring-rename' | 'retiring-unlink' | 'retiring-sync' | 'disposed-rename' | 'disposed-unlink' | 'disposed-sync';
 export interface AnchoredPublicationAuthorityResidue {
     recordName: string;
     authorityId: string;

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

@@ -0,0 +1,358 @@
+import * as fs from 'node:fs/promises';
+import { type AnchoredFsIdentity, type AnchoredPathIdentity, type AnchoredWritePrecondition } from './anchored-fs';
+import { type ProcessCleanupOwner } from './process-tree';
+import { type ProcessIdentity } from './process-identity';
+import { type WorkspaceRootAuthority } from './workspace-authority';
+import { type MaterializationHangStage } from './workspace-materializer';
+/** Directories never materialized into a new filesystem snapshot. */
+export declare const SHADOW_SKIP_DIRS: ReadonlySet<string>;
+/** IMAGE-ATTACHMENT-DESIGN.md §7 — the in-worktree attachments dir (never in the reviewed diff / promoted). */
+export declare const SHADOW_ATTACHMENTS_DIR = ".codevibe-attachments";
+/**
+ * Non-secret, gitignored BUILD-ENV files the agent's tooling (`npm test`,
+ * compile, format) reads from the workspace root. Copied/symlinked into the
+ * shadow as READ-ENV only (NEVER in the tracked set → never promoted). Each
+ * candidate is still checked against `matchesSecretDenyList` first — a secret
+ * `.env` is excluded even though it appears here. (Stage-2 r2 agy MED.)
+ */
+export declare const BUILD_ENV_FILENAMES: readonly string[];
+/** Marker filename written inside the shadow (#PR-4). */
+export declare const SHADOW_STATE_FILE = "shadow-state.json";
+export declare const SHADOW_OWNER_FILE = ".codevibe-snapshot-owner.json";
+export declare const SHADOW_ROOT_REGISTRY_FILE = ".codevibe-shadow-roots.json";
+export declare const SHADOW_QUOTA_LOCK_DIR = ".codevibe-quota-locks";
+export declare const SHADOW_QUOTA_LOCK_FILE = "physical-copy-quota.lock";
+/** Alternate durable fail-closed anchor when the primary marker cannot be updated. */
+export declare const SHADOW_CLEANUP_BLOCK_FILE = ".codevibe-cleanup-blocked.json";
+export declare const SHADOW_STATE_FILE_RE: RegExp;
+export declare const SHADOW_EXPOSURE_RETENTION_FILE_RE: RegExp;
+export declare const SHADOW_DIR_RE: RegExp;
+/** Private create name: never classified as a runnable/recoverable snapshot. */
+export declare const SHADOW_STAGING_DIR_RE: RegExp;
+export declare const SHADOW_TREE_TOMBSTONE_RE: RegExp;
+export declare const SHADOW_UUID_SUFFIX_RE: RegExp;
+export declare function isStateRootInfrastructureDirectory(name: string): boolean;
+export declare function taskIdFromGeneratedShadowName(name: string): string | null;
+/** Strict lifecycle-lock residue authored by `withAnchoredExclusiveLock`. */
+export declare const SHADOW_LIFECYCLE_LOCK_ARTIFACT_RE: RegExp;
+/** Never silently duplicate one enormous file when reflinks are unavailable. */
+export declare const MAX_NON_COW_FILE_BYTES: number;
+export declare const MAX_NON_COW_WORKSPACE_BYTES: number;
+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;
+export declare function reservePhysicalCopyBytes(scopeId: string, reservationId: string, bytes: number, persistedBytes: number, limit?: number): void;
+export declare function releasePhysicalCopyBytes(scopeId: string, reservationId: string, bytes?: number): void;
+export declare function reservedPhysicalCopyBytes(scopeId: string, reservationId: string): number;
+export declare function movePhysicalCopyReservation(scopeId: string, from: string, to: string): void;
+/** 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). */
+export 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;
+}
+export 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;
+}
+export interface ShadowStateFileV2 {
+    /** Version 3 is the first schema with complete snapshot-incarnation authority. */
+    version: 3;
+    taskId: string;
+    shadowDir: string;
+    workingDir: string;
+    shadowDirIdentity: AnchoredFsIdentity;
+    /** Exact snapshot-root incarnation captured when this snapshot was exposed. */
+    snapshotRootAuthority: WorkspaceRootAuthority;
+    workingDirIdentity: AnchoredFsIdentity;
+    workspaceRootAuthority: WorkspaceRootAuthority;
+    /** OS-authenticated creator lease; TTL never overrides a live process. */
+    ownerProcessIdentity: ProcessIdentity;
+    /** Actual non-COW bytes reserved against this durable session-state aggregate. */
+    physicalCopyBytes: number;
+    isGit: false;
+    promoteState: ShadowPromoteState;
+    createdAtMs: number;
+    /** Owned descendants could not be proven gone; cwd deletion is forbidden. */
+    cleanupBlocked?: boolean;
+    /** Persisted process-tree owners used to retry quiescence after restart. */
+    cleanupOwners?: ProcessCleanupOwner[];
+    /** Explicit recovery authority: cleanup is forbidden until publication is reconciled. */
+    unresolvedAuthorityRetention?: UnresolvedBundlePublicationRetention;
+    /** Exact immutable snapshot baseline, including paths later deleted by an implementor. */
+    baseline: Array<{
+        path: string;
+        hash: string | null;
+        mode?: number | null;
+    }>;
+    /** Exact intended post-images, present while/after promotion for crash reconciliation. */
+    promotePostHashes?: Array<{
+        path: string;
+        hash: string | null;
+        mode?: number | null;
+    }>;
+    /** Names + byte identities needed to resolve any post-COMMIT helper death. */
+    casRecovery?: CasRecoveryAuthority[];
+    /** Full snapshot incarnation claimed by immutable DISPOSING authority. */
+    disposalSnapshotAuthority?: WorkspaceRootAuthority;
+    /** Legacy v3 field: protected fail-closed, never accepted for deletion. */
+    disposalShadowIdentity?: AnchoredFsIdentity;
+    /**
+     * Exact artifact bytes submitted for review. This is persisted before the
+     * submission can resolve, so a restarted desktop never derives promotion
+     * authority from mutable snapshot bytes.
+     */
+    reviewedDiff?: ShadowDiffFile[];
+}
+/**
+ * Non-operational authority published before a private snapshot name becomes
+ * visible. It never authorizes use of `finalShadowDir`; it only prevents that
+ * generated name from being freshly adopted and identifies the original bytes
+ * that CodeVibe may reclaim.
+ */
+export interface ExposureRetentionMarker {
+    version: 1 | 2;
+    taskId: string;
+    finalShadowDir: string;
+    originalSnapshotAuthority: WorkspaceRootAuthority;
+    currentSnapshotAuthority?: WorkspaceRootAuthority;
+    ownerProcessIdentity: ProcessIdentity;
+    physicalCopyScopeHash: string;
+    physicalCopyBytes: number;
+    phase: 'owned' | 'operational' | 'deleting' | 'reclaimed';
+    /** Fsynced authorization for deleting exactly this incarnation. */
+    deleteDisposition?: {
+        version: 1;
+        snapshotAuthority: WorkspaceRootAuthority;
+        nonce: string;
+        createdAtMs: number;
+    };
+    createdAtMs: number;
+}
+export interface ShadowStateSnapshot {
+    marker: ShadowStateFileV2;
+    precondition: Extract<AnchoredWritePrecondition, {
+        kind: 'existing';
+    }>;
+    /** Immediate state-directory inode carried from authority read to publication. */
+    parentIdentity: AnchoredFsIdentity & {
+        birthtimeNs: string;
+        canonicalPath: string;
+    };
+    /** Full marker incarnation used by identity-conditioned retirement. */
+    stateFileIdentity: AnchoredPathIdentity;
+    /** Exact state-root parent carried from the same bounded authority read. */
+    stateRootAuthority: WorkspaceRootAuthority;
+}
+export type RetainedStateFileAuthority = AnchoredFsIdentity & {
+    birthtimeNs: string;
+    canonicalPath: string;
+};
+/**
+ * A schema-valid marker whose snapshot pathname may no longer name the owned
+ * incarnation.  This surface is deliberately cleanup-only: it can transition
+ * to DISPOSING and reclaim the exact persisted incarnation, but can never
+ * reopen, diff, promote, or launch from the pathname now occupying `shadowDir`.
+ */
+export interface StructurallyBoundStateSnapshot extends ShadowStateSnapshot {
+    stateFileIdentity: AnchoredPathIdentity;
+    stateDirAuthority: WorkspaceRootAuthority;
+    shadowRootAuthority: WorkspaceRootAuthority;
+}
+export interface DisplacedShadowMarkerRecord {
+    taskId: string;
+    stateDir: string;
+    stateFile: string;
+}
+export type SnapshotIncarnationIndex = ReadonlyMap<string, WorkspaceRootAuthority>;
+/**
+ * The pre-task content hash of every TRACKED-SET path (#PR-2). `null` is a
+ * first-class state meaning "did not exist at shadow-create" — so a concurrent
+ * CREATE (real now exists, pre-task null) and concurrent DELETE (real now gone,
+ * pre-task hash) are both caught at promote time.
+ */
+export type PreTaskHashes = Map<string, string | null>;
+export type PreTaskModes = Map<string, 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 deterministic replacement seam after a quota-reference task is enumerated. */
+    afterQuotaReferenceTaskEntry?: (stateDir: string) => Promise<void> | void;
+    /** @internal deterministic replacement seam after a quota-reference marker is enumerated. */
+    afterQuotaReferenceMarkerEntry?: (filePath: string) => Promise<void> | void;
+    /** @internal deterministic replacement seam after a quota-reference marker is opened. */
+    afterQuotaReferenceMarkerStat?: (filePath: string) => Promise<void> | 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;
+}
+export declare function defaultStateRoot(): string;
+export declare function hashContent(content: string): string;
+export declare function openAnchoredDirectory(parent: string): Promise<fs.FileHandle>;
+export declare function fsyncDirectory(dir: string): Promise<void>;
+export declare function readShadowTextFile(shadowDir: string, rel: string, snapshotRootAuthority: WorkspaceRootAuthority): Promise<{
+    content: string;
+    hash: string;
+    mode: number;
+}>;
+export declare function assertSafeRelativePath(rel: string): void;
+export declare function isInternalShadowPath(rel: string): boolean;
+export declare function assertNotInternalShadowPath(rel: string): void;
+export declare function normalizeFileMode(mode: number): number;
+/**
+ * PHASE-589/469 W3.1 (C1) — read a real-tree file's CONTENT + hash by RELATIVE
+ * path BEFORE the promote mutates it; `{ content: null, hash: null }` if absent
+ * (a `created` file → an absent pre-image). NEVER logs the content (#589-G).
+ */
+export declare function readRealFileForManifest(workingDir: string, rel: string, expectedRoot: AnchoredFsIdentity | WorkspaceRootAuthority): Promise<{
+    content: string | null;
+    hash: string | null;
+    mode: number | null;
+}>;
+export declare function readRealFileMetadata(workingDir: string, rel: string, expectedRoot: AnchoredFsIdentity | WorkspaceRootAuthority): Promise<{
+    hash: string | null;
+    mode: number | null;
+}>;