@quantiya/codevibe-codex-plugin 2.0.6 → 2.0.8

package/node_modules/@quantiya/codevibe-core/dist/keychain/__tests__/keychain-manager.test.d.ts

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

package/node_modules/@quantiya/codevibe-core/dist/keychain/__tests__/keychain-migrate.test.d.ts

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

package/node_modules/@quantiya/codevibe-core/dist/keychain/keychain-backend.d.ts

@@ -1,3 +1,8 @@
+type KeytarApi = {
+    getPassword(service: string, account: string): Promise<string | null>;
+    setPassword(service: string, account: string, password: string): Promise<void>;
+    deletePassword(service: string, account: string): Promise<boolean>;
+};
 type BackendKind = 'keytar' | 'file';
 /**
  * Is the OS-native keyring service STRUCTURALLY UNREACHABLE in THIS process?
@@ -28,6 +33,10 @@ type BackendKind = 'keytar' | 'file';
  * fallback at all.
  */
 export declare function osKeyringStructurallyAbsent(): boolean;
+/** Best-effort: remember that the OS keyring worked here (Linux only — only the
+ *  Linux headless path ever reads it). Never throws. Exported so #642's
+ *  migration can record it after moving credentials onto the keyring. */
+export declare function markKeytarUsed(): void;
 /**
  * Do durable file-backend credentials already exist on this machine? True when
  * ~/.codevibe holds any `<service>.json` credential file (written by a prior
@@ -65,6 +74,23 @@ export declare function wasAutoFileFallback(): boolean;
  * outcome) for tests and diagnostics without triggering initialization.
  */
 export declare function peekActiveBackendKind(): BackendKind | null;
+/**
+ * Run `fn` while holding the per-service FILE-MUTATION lock — the single
+ * cross-process gate that serializes EVERY mutation of `~/.codevibe/<service>.json`
+ * (setPassword / deletePassword) against a concurrent `codevibe keychain migrate`.
+ * The migration CLI holds this SAME lock across the whole migration, so the file
+ * store cannot change mid-migration (the lock IS the freeze — it lets the migration
+ * do a single stable read instead of freeze-then-re-migrate).
+ *
+ * FAIL CLOSED: if the lock cannot be acquired (contention timeout / unwritable lock
+ * root) we THROW `KeychainBackendUnavailableError` and NEVER run `fn` unlocked — an
+ * unserialized read-modify-write could clobber a concurrent migration's
+ * tombstone/retire and re-fork the identity (the fork-incident harm). Reuses the
+ * portable, native-addon-free mkdir-lock from the credential broker (§626 §5 /
+ * AMEND-1) under a DISTINCT lockdir (`keychain-file-<service>`) from the
+ * per-provider vendor-key OAuth locks.
+ */
+export declare function withFileStoreLock<T>(service: string, fn: () => Promise<T> | T): Promise<T>;
 /**
  * The active backend kind (`'keytar'` = OS-native keyring, `'file'` = the
  * plaintext `~/.codevibe/<service>.json` fallback). Initializes the backend if
@@ -79,7 +105,86 @@ export declare function peekActiveBackendKind(): BackendKind | null;
  * backend could be initialized (keytar failed to load AND no file opt-in).
  */
 export declare function getActiveBackendKind(): BackendKind;
+/**
+ * LOCK-FREE read (F5). Identical to `getPassword` — a read never needs the file lock
+ * (atomic writes make a torn read impossible) — but named explicitly so a transaction
+ * already holding `withFileStoreLock` (device get-or-create) can read without any risk
+ * of re-entering the lock.
+ */
+export declare function getPasswordUnlocked(service: string, account: string): Promise<string | null>;
 export declare function getPassword(service: string, account: string): Promise<string | null>;
+/**
+ * LOCK-FREE write (F5) — the file-mutation body of `setPassword` WITHOUT acquiring
+ * `withFileStoreLock`. It STILL runs the fail-closed tombstone guard + unreadable-store
+ * guard + atomic write. For use ONLY by a caller that already holds the file lock (the
+ * device get-or-create transaction); acquiring the lock again would self-deadlock.
+ */
+export declare function setPasswordUnlocked(service: string, account: string, password: string): Promise<void>;
 export declare function setPassword(service: string, account: string, password: string): Promise<void>;
 export declare function deletePassword(service: string, account: string): Promise<boolean>;
+/** Absolute path of the file-backend credential store for `service`. */
+export declare function fileStorePathForService(service: string): string;
+/**
+ * A DISCRIMINATED read of the file store — migration must distinguish "no file"
+ * (nothing to do) from "exists but I can't read it right now" (EACCES / transient
+ * I/O / mid-write) from "readable but corrupt JSON" from "readable credential map".
+ * Retiring a file we merely FAILED to read would lose a valid identity, so the
+ * migration never retires on `unreadable`. `raw` is the exact bytes, for a
+ * byte-exact concurrency compare (parsed-object equality would miss whitespace /
+ * duplicate-key rewrites).
+ */
+export type FileStoreRead = {
+    kind: 'absent';
+} | {
+    kind: 'unreadable';
+    error: string;
+} | {
+    kind: 'corrupt';
+    raw: string;
+} | {
+    kind: 'store';
+    data: Record<string, string>;
+    raw: string;
+};
+export declare function readFileStoreState(service: string): FileStoreRead;
+/**
+ * Rename the file store out of the way (`…/<service>.json.migrated-backup-<ts>`)
+ * so the NEXT process selects the OS keyring (fileStoreHasCredentials() → false).
+ * Reversible — the backup is kept, 0600. Returns the backup path, or null if
+ * there was no file store to retire. Only ever called AFTER the migration has
+ * written + verified every credential into the keyring (never loses the identity).
+ *
+ * R4-4: NO fail-open `existsSync` pre-probe (an EACCES there returned null → the CLI
+ * would exit 0 while the plaintext file remained). Attempt the atomic rename directly:
+ * an ENOENT/ENOTDIR means there was genuinely nothing to retire → null; ANY other
+ * error (EACCES/EIO/…) PROPAGATES so the caller surfaces the failure (non-zero exit /
+ * verify_failed) instead of silently leaving the file behind.
+ */
+export declare function retireFileStore(service: string): string | null;
+/**
+ * Load the keytar native module directly (bypassing the pinned backend), or null
+ * if it cannot load. Used ONLY by the migration command to write into the OS
+ * keyring from a process otherwise committed to the file backend. Same indirect
+ * `eval('require')` as initBackends so esbuild does not resolve keytar statically.
+ */
+export declare function loadKeytarModule(): KeytarApi | null;
+/** True iff this machine has migrated `service`'s credentials onto the OS keyring.
+ *  Routed through `pathPresence` (F1); a probe 'error' reads as false here (the
+ *  fail-closed callers use `migratedTombstoneStatus`, not this boolean). */
+export declare function migratedTombstoneExists(service: string): boolean;
+/**
+ * Tri-state probe of the per-service migration tombstone via `pathPresence` (F1) —
+ * `fs.statSync`, NOT `fs.existsSync` (which fails OPEN on EACCES/EIO). DISTINGUISHES a
+ * genuine probe error from a clean absence so `initBackends` / the in-lock mutation
+ * guard / the CLI resume gate all fail CLOSED on 'error' rather than treating an
+ * unreadable ~/.codevibe as "not migrated" (which could re-fork the device identity).
+ */
+export declare function migratedTombstoneStatus(service: string): 'present' | 'absent' | 'error';
+/**
+ * Atomically create the per-service migration tombstone (temp-write + fsync +
+ * rename + best-effort dir fsync, 0600). Idempotent. Throws on failure — the
+ * migration MUST know the tombstone is durable before it retires the file (the
+ * tombstone is what makes stragglers fail closed).
+ */
+export declare function writeMigratedTombstone(service: string): void;
 export {};

package/node_modules/@quantiya/codevibe-core/dist/keychain/keychain-manager.d.ts

@@ -5,6 +5,7 @@ import { DeviceIdentity, TokenData, EncryptedSessionKey } from '../types';
 export declare class KeychainError extends Error {
     constructor(message: string);
 }
+export declare const DEVICE_IDENTITY_ACCOUNT = "device-identity";
 /**
  * Manages device identity and OAuth tokens using native keychain
  */
@@ -36,7 +37,18 @@ export declare class KeychainManager {
      */
     setDeviceIdentity(identity: DeviceIdentity): Promise<void>;
     /**
-     * Get or create device identity
+     * Get or create device identity — ATOMIC across processes (#642 F5).
+     *
+     * A plain read-then-create is a cross-process race: two fresh processes both read
+     * "no identity" outside any lock, generate distinct identities A and B, then each
+     * writes under its own lock — last-writer-wins, and the loser keeps using an
+     * identity that is NOT the one persisted (forking E2E state). The WHOLE
+     * read→validate→generate→write transaction is therefore serialized under the
+     * per-service file lock (`withFileStoreLock`), using the LOCK-FREE backend helpers
+     * (`getPasswordUnlocked`/`setPasswordUnlocked`) so the transaction never re-enters
+     * the lock and self-deadlocks. The lock serializes regardless of backend (keytar or
+     * file). The lock is taken ONLY on the slow path (no cached/persisted identity yet),
+     * so steady-state reads stay lock-free.
      */
     getOrCreateDeviceIdentity(): Promise<DeviceIdentity>;
     /**
@@ -87,9 +99,28 @@ export declare class KeychainManager {
      */
     isTokenExpired(tokens: TokenData): boolean;
     /**
-     * Get session key for a session, decrypting from encryptedKeys if needed
+     * Get the session key for a session.
+     *
+     * When `encryptedKeys` are provided they are the AUTHORITATIVE source and the
+     * cache is trusted ONLY if its stored generation matches `sessionKeyGen`
+     * (tool-event consolidation §4.5 / Stage-2 Codex H2 / #230 Finding 1). A
+     * generation mismatch — the session was RECREATED under a new key (K2) while
+     * the cache still holds the prior generation's key (K1) — forces a fresh
+     * derive from `encryptedKeys`, so `getSessionKey` can never hand back a stale
+     * K1 for a K2 session. On a cache hit at the matching generation the cached
+     * key is returned (a re-derive per event would be a needless ECDH cost, and
+     * the ONLY writers of a generation's entry are this method's own derive and
+     * `cacheSessionKey`-with-the-derived-key, so the entry is always authoritative
+     * for its generation).
+     *
+     * When `encryptedKeys` are NOT provided (cache-only callers — e.g. the
+     * orchestration QuorumLoop's `getSessionKey(sessionId)`), the cached key is
+     * returned as before. An explicitly supplied empty authoritative envelope is
+     * different: a generation-bearing row is non-decryptable and may never fall
+     * through to a stale cache. Empty-envelope fallback is permitted only for a
+     * genuinely generation-absent legacy row/cache.
      */
-    getSessionKey(sessionId: string, encryptedKeys?: EncryptedSessionKey[]): Promise<string | null>;
+    getSessionKey(sessionId: string, encryptedKeys?: EncryptedSessionKey[], sessionKeyGen?: string | null): Promise<string | null>;
     /**
      * Generate and encrypt a new session key for all devices.
      *
@@ -115,9 +146,13 @@ export declare class KeychainManager {
         skippedDeviceIds: string[];
     };
     /**
-     * Cache a session key
+     * Cache a session key, optionally bound to the session GENERATION it was
+     * derived under (§4.5). Callers that hold the authoritative key + generation
+     * (the session create/resume path) pass `sessionKeyGen` so a later
+     * `getSessionKey(..., encryptedKeys, gen)` trusts the entry only at the
+     * matching generation. Legacy cache-only callers omit it (stored as `null`).
      */
-    cacheSessionKey(sessionId: string, sessionKey: string): void;
+    cacheSessionKey(sessionId: string, sessionKey: string, sessionKeyGen?: string | null): void;
     /**
      * Get a cached session key without touching the backend or attempting
      * to decrypt from encryptedKeys. Returns null if the session key is not

package/node_modules/@quantiya/codevibe-core/dist/keychain/keychain-migrate.d.ts

@@ -0,0 +1,46 @@
+import { DEVICE_IDENTITY_ACCOUNT } from './keychain-manager';
+import type { FileStoreRead } from './keychain-backend';
+export { DEVICE_IDENTITY_ACCOUNT };
+export type { FileStoreRead };
+export interface MigrateIO {
+    print(line: string): void;
+    printErr(line: string): void;
+}
+export interface MigrateDeps {
+    /** Discriminated read of the file store (absent / unreadable / corrupt / store+raw). */
+    readFileState(): FileStoreRead;
+    /** Read an account from the OS keyring directly. MAY THROW (locked/denied keyring). */
+    keytarGet(account: string): Promise<string | null>;
+    /** Write an account to the OS keyring directly. */
+    keytarSet(account: string, password: string): Promise<void>;
+    /** Atomically create the durable "migrated to keyring" tombstone (throws on failure). */
+    writeTombstone(): void;
+    /** Retire the file store → backup path (or null if nothing to retire). */
+    retireFileStore(): string | null;
+    /** Record the Linux `.keyring-used` anti-fork marker (no-op off Linux). */
+    markKeyringChosen(): void;
+    io: MigrateIO;
+}
+export interface MigrateOptions {
+    discardFile: boolean;
+    force: boolean;
+    /**
+     * Crash-recovery RESUME (the CLI sets this when the migration tombstone already
+     * existed at entry). Post-tombstone the KEYRING is authoritative and a keyring-ABSENT
+     * account is an authoritative DELETION, NOT an incomplete copy — so a resume must
+     * copy ZERO accounts from the stale file (F3). It only verifies the keyring still
+     * holds a VALID identity and, if so, retires the leftover file (copying nothing); if
+     * the keyring lost its identity it REFUSES (never re-runs the copy/replace fork path,
+     * never strands the file). First-run (false) keeps the file-authoritative copy.
+     */
+    resume: boolean;
+}
+export type MigrateOutcome = 'nothing_to_do' | 'file_unreadable' | 'keyring_unreachable' | 'retired_empty' | 'discarded' | 'discard_refused' | 'already_present' | 'migrated' | 'replaced' | 'fork_refused' | 'invalid_source_identity' | 'resume_keyring_lost' | 'verify_failed';
+export interface MigrateResult {
+    outcome: MigrateOutcome;
+    backupPath?: string | null;
+    accountsMigrated?: string[];
+    fileDeviceId?: string | null;
+    keychainDeviceId?: string | null;
+}
+export declare function migrateKeychain(deps: MigrateDeps, opts: MigrateOptions): Promise<MigrateResult>;

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

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

package/node_modules/@quantiya/codevibe-core/dist/local-executor/__tests__/bounded-directory.test.d.ts

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

package/node_modules/@quantiya/codevibe-core/dist/local-executor/__tests__/bounded-output.test.d.ts

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

package/node_modules/@quantiya/codevibe-core/dist/local-executor/__tests__/durable-directory.test.d.ts

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

package/node_modules/@quantiya/codevibe-core/dist/local-executor/__tests__/hosted-class-a-sink.test.d.ts

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

package/node_modules/@quantiya/codevibe-core/dist/local-executor/__tests__/process-identity.test.d.ts

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

package/node_modules/@quantiya/codevibe-core/dist/local-executor/__tests__/process-tree.test.d.ts

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

package/node_modules/@quantiya/codevibe-core/dist/local-executor/__tests__/publication-authority-capability.test.d.ts

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

package/node_modules/@quantiya/codevibe-core/dist/local-executor/__tests__/reviewer-rationale-flag.test.d.ts

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

package/node_modules/@quantiya/codevibe-core/dist/local-executor/__tests__/snapshot-merge.test.d.ts

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

package/node_modules/@quantiya/codevibe-core/dist/local-executor/__tests__/workspace-authority-fixture.d.ts

@@ -0,0 +1,3 @@
+import type { WorkspaceRootAuthority } from '../workspace-authority';
+/** Schema-valid authority for storage-only tests that never touch a user tree. */
+export declare const TEST_WORKSPACE_ROOT_AUTHORITY: WorkspaceRootAuthority;

package/node_modules/@quantiya/codevibe-core/dist/local-executor/__tests__/workspace-authority.test.d.ts

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

package/node_modules/@quantiya/codevibe-core/dist/local-executor/__tests__/workspace-materializer.test.d.ts

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

package/node_modules/@quantiya/codevibe-core/dist/local-executor/agentic-disposable-repo.d.ts

@@ -1,3 +1,4 @@
+import { type WorkspaceRootAuthority } from './workspace-authority';
 /** A structured failure in disposable-repo materialization or fd-safe import. */
 export declare class DisposableRepoError extends Error {
     readonly reason: 'init' | 'ls-tree' | 'pack-objects' | 'dangerous-attributes' | 'read-tree' | 'checkout';
@@ -5,13 +6,27 @@ export declare class DisposableRepoError extends Error {
 }
 /** A structured rejection from {@link fdSafeReadFile} (fail-closed → human-gate). */
 export declare class FdSafeImportError extends Error {
-    readonly reason: 'empty' | 'nul' | 'absolute' | 'traversal' | 'missing' | 'symlink-component' | 'not-regular' | 'hardlink';
-    constructor(reason: 'empty' | 'nul' | 'absolute' | 'traversal' | 'missing' | 'symlink-component' | 'not-regular' | 'hardlink', message: string);
+    readonly reason: 'empty' | 'nul' | 'absolute' | 'traversal' | 'missing' | 'symlink-component' | 'not-regular' | 'hardlink' | 'root-incarnation';
+    constructor(reason: 'empty' | 'nul' | 'absolute' | 'traversal' | 'missing' | 'symlink-component' | 'not-regular' | 'hardlink' | 'root-incarnation', message: string);
+}
+/** Exact post-rename authority returned by {@link stageDirForRead}. */
+export interface StagedDirectory {
+    path: string;
+    identity: WorkspaceRootAuthority;
+}
+/** Staging failed after rename; retains the exact authority needed for cleanup. */
+export declare class StageDirForReadError extends Error {
+    readonly retained?: StagedDirectory | undefined;
+    constructor(message: string, retained?: StagedDirectory | undefined);
+    get retainedPath(): string | undefined;
+    get retainedIdentity(): WorkspaceRootAuthority | undefined;
 }
 /** A materialized disposable repo + its cleanup. */
 export interface DisposableRepo {
     /** The working-tree root the agent resolves in (its own `.git` lives under it). */
     repoDir: string;
+    /** Exact directory created by CodeVibe; cleanup never recaptures a replacement. */
+    repoAuthority: WorkspaceRootAuthority;
     /** Remove the disposable repo (try/finally — even on timeout/crash). */
     cleanup(): Promise<void>;
 }
@@ -38,10 +53,12 @@ export declare function materializeDisposableRepo(opts: MaterializeOpts): Promis
  * Atomically rename `dir` to a fresh RANDOM sibling path before reading it back —
  * the exited agent / any disowned background process does NOT know the new path,
  * so it cannot pre-place symlinks to win a TOCTOU race. The caller reads from the
- * returned staged path (and is responsible for removing it). Same-filesystem
- * rename → atomic.
+ * returned staged path plus relocated cleanup identity (and is responsible for
+ * removing that exact authority). Same-filesystem rename → atomic.
  */
-export declare function stageDirForRead(dir: string): Promise<string>;
+export declare function stageDirForRead(dir: string, expectedAuthority: WorkspaceRootAuthority, seams?: {
+    afterRename?: (staged: string) => Promise<void>;
+}): Promise<StagedDirectory>;
 /**
  * fd-safe read of ONE conflicted file at `relPath` under `rootDir` (CP-14 WB2 §2.1).
  * `rootDir` SHOULD be a {@link stageDirForRead} staging path. Closes leaf+parent
@@ -49,4 +66,4 @@ export declare function stageDirForRead(dir: string): Promise<string>;
  * dir/FIFO/device (`isFile`), and the read race (read-from-the-verified-fd). Any
  * violation throws {@link FdSafeImportError} → the caller fails closed (human-gate).
  */
-export declare function fdSafeReadFile(rootDir: string, relPath: string): Promise<Buffer>;
+export declare function fdSafeReadFile(staged: StagedDirectory, relPath: string): Promise<Buffer>;

package/node_modules/@quantiya/codevibe-core/dist/local-executor/agentic-resolve.d.ts

@@ -1,3 +1,5 @@
+import { stageDirForRead, type StagedDirectory } from './agentic-disposable-repo';
+import { type WorkspaceRootAuthority } from './workspace-authority';
 /**
  * CP-14 WB2 §2.1 path C (dispatch-time fail-closed, D3-A) — the live
  * {@link DispatchImplementor} closure THROWS this when the per-resolve confinement
@@ -14,6 +16,8 @@ export declare class AgenticDispatchUnconfinedError extends Error {
 export type DispatchImplementor = (args: {
     /** The disposable repo working-tree root (its own `.git`). */
     repoDir: string;
+    /** Original full incarnation authority; dispatch must bind launch to it. */
+    repoAuthority: WorkspaceRootAuthority;
     /** The class-2 conflicted files the agent must resolve (markers removed). */
     conflictedPaths: readonly string[];
     /** The implementor agent kind + its per-spawn task identity. */
@@ -30,10 +34,22 @@ export interface AgenticResolveArgs {
     implementorTaskId: string;
     /** Under the task's writable workspace area. */
     parentDir: string;
+    /**
+     * The caller created `parentDir` solely for this resolve and transfers
+     * cleanup ownership here.  Direct/library callers may omit this when the
+     * parent contains other state.
+     */
+    cleanupParentDir?: boolean;
     /** scan-before-checkout (the live caller passes `scanIntegrationTreeAttributes`). */
     scanTree: (repoDir: string, tree: string) => Promise<string[]>;
     /** Real implementor spawn (LE seam); tests stub it. */
     dispatchImplementor: DispatchImplementor;
+    /** @internal deterministic post-stage cleanup regression seam. */
+    stageDirectory?: typeof stageDirForRead;
+    /** @internal deterministic pathname-replacement seam before dispatch. */
+    beforeDispatch?: (repoDir: string, authority: WorkspaceRootAuthority) => Promise<void>;
+    /** @internal deterministic pathname-replacement seam after staging. */
+    beforeStagedRead?: (staged: StagedDirectory) => Promise<void>;
 }
 export interface AgenticResolveResolved {
     status: 'resolved';

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

@@ -0,0 +1,243 @@
+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';
+export interface AnchoredPublicationAuthorityResidue {
+    recordName: string;
+    authorityId: string;
+    targetParentCanonicalPath?: string;
+    targetName?: string;
+    /** Caller label for an authority-id owner-prefix match. */
+    ownerLabel?: string;
+    /** Read/schema failure retained for a scoped, therefore attributable, record. */
+    unresolvedDetail?: string;
+}
+/**
+ * Fresh bounded inventory of private publication records targeting exact
+ * durable parent paths or carrying exact caller-owner fingerprints. Teardown
+ * uses this only after all owned writers have drained; any remaining record is
+ * therefore retained authority, not a cache. Owner fingerprints are encoded in
+ * the record name before its body is written, so partial/non-JSON staging
+ * remains visible without adopting unrelated private records.
+ */
+export declare function listAnchoredPublicationAuthorityResidueForParents(parentCanonicalPaths: readonly string[], owners?: readonly {
+    ownerKey: string;
+    label: string;
+}[]): Promise<AnchoredPublicationAuthorityResidue[]>;
+export interface AnchoredFsIdentity {
+    dev: string;
+    ino: string;
+    /** Optional inode-reuse fence. Snapshot-root deletion always supplies it. */
+    birthtimeNs?: string;
+    /** Optional canonical-name binding, checked immediately before tree rename. */
+    canonicalPath?: string;
+}
+export interface AnchoredPathIdentity extends AnchoredFsIdentity {
+    birthtimeNs: string;
+    canonicalPath: string;
+    mtimeMs: number;
+    kind: 'file' | 'directory';
+}
+export interface AnchoredCommittedFile extends AnchoredFsIdentity {
+    birthtimeNs: string;
+    canonicalPath: string;
+    mode: number;
+    mtimeMs: number;
+    sha256: string;
+}
+export interface AnchoredReadFile extends AnchoredFsIdentity {
+    birthtimeNs: string;
+    canonicalPath: string;
+    bytes: Buffer;
+    mode: number;
+    mtimeMs: number;
+    /** Exact immediate parent inode that owned the file throughout the read. */
+    parent: AnchoredFsIdentity & {
+        birthtimeNs: string;
+        canonicalPath: string;
+    };
+}
+export interface AnchoredHashedFile extends AnchoredFsIdentity {
+    birthtimeNs: string;
+    canonicalPath: string;
+    sha256: string;
+    size: number;
+    mode: number;
+    mtimeMs: number;
+    parent: AnchoredFsIdentity & {
+        birthtimeNs: string;
+        canonicalPath: string;
+    };
+}
+/** Complete same-request witness required when opening an enumerated file. */
+export interface AnchoredFileWitness extends AnchoredFsIdentity {
+    birthtimeNs: string;
+    canonicalPath: string;
+    size: bigint;
+    mtimeNs: string;
+    ctimeNs: string;
+    nlink: string;
+}
+/** True only when a failed atomic write deliberately left fail-closed recovery authority. */
+export declare function isUnresolvedAnchoredPublicationError(err: unknown): boolean;
+/** Read one bounded file through the deadline helper and return its bytes. */
+export declare function anchoredReadFileWithinRoot(root: string, relativePath: string, opts: {
+    maxBytes: number;
+    expectedRoot?: AnchoredFsIdentity | WorkspaceRootAuthority;
+    /** Exact enumerated leaf incarnation that must be opened. */
+    expectedFile?: AnchoredFileWitness;
+    /** Reject a multiply-linked leaf throughout the complete read. */
+    requireSingleLink?: boolean;
+    beforeOpen?: () => Promise<void> | void;
+    beforeAbsent?: () => Promise<void> | void;
+    afterStat?: () => Promise<void> | void;
+    afterRead?: () => Promise<void> | void;
+    helperTimeoutMs?: number;
+    testHangBeforeRead?: boolean;
+    testHangStage?: 'open' | 'read' | 'close';
+}): Promise<AnchoredReadFile | null>;
+/** Stream and hash one bounded file entirely in the deadline helper. */
+export declare function anchoredHashFileWithinRoot(root: string, relativePath: string, opts: {
+    maxBytes: number;
+    expectedRoot?: AnchoredFsIdentity | WorkspaceRootAuthority;
+    beforeOpen?: () => Promise<void> | void;
+    afterStat?: () => Promise<void> | void;
+    afterRead?: () => Promise<void> | void;
+    helperTimeoutMs?: number;
+    testHangStage?: 'open' | 'read' | 'close';
+}): Promise<AnchoredHashedFile | null>;
+export type AnchoredWritePrecondition = {
+    kind: 'absent';
+} | {
+    kind: 'existing';
+    dev: string;
+    ino: string;
+    mode: number;
+    sha256: string;
+};
+export declare function captureAnchoredIdentity(target: string, opts?: {
+    /** @internal lower deterministic helper deadline for tests. */
+    helperTimeoutMs?: number;
+    /** @internal deterministic parent-preflight stall seam. */
+    testHangBeforeReady?: boolean;
+    expectedType?: 'file' | 'directory';
+    /** Full parent incarnation for root-relative stat consumers. */
+    expectedParent?: AnchoredFsIdentity | WorkspaceRootAuthority;
+    /** @internal after missing child, before public-parent re-authentication. */
+    beforeAbsent?: () => Promise<void> | void;
+}): Promise<AnchoredPathIdentity>;
+/** Create or reopen one real direct-child directory under an exact parent. */
+export declare function anchoredEnsureDirectory(parent: WorkspaceRootAuthority, name: string, mode?: number): Promise<WorkspaceRootAuthority>;
+export interface AnchoredEnsuredDirectory {
+    authority: WorkspaceRootAuthority;
+    /** True only when this exact anchored helper invocation won the mkdir. */
+    created: boolean;
+}
+/**
+ * Create or reopen one real direct-child directory while reporting mkdir
+ * ownership from inside the anchored helper, not from a caller-side stat.
+ */
+export declare function anchoredEnsureDirectoryWithOwnership(parent: WorkspaceRootAuthority, name: string, mode?: number): Promise<AnchoredEnsuredDirectory>;
+/** Create one new direct-child directory without adopting a pre-existing name. */
+export declare function anchoredCreateDirectory(parent: WorkspaceRootAuthority, name: string, mode?: number): Promise<WorkspaceRootAuthority>;
+export declare function captureAnchoredWritePrecondition(filePath: string, maxBytes: number, afterStat?: () => Promise<void> | void, expectedParent?: AnchoredFsIdentity | WorkspaceRootAuthority): Promise<AnchoredWritePrecondition>;
+export declare function anchoredAtomicWrite(filePath: string, data: string | Buffer, opts: {
+    expected: AnchoredWritePrecondition;
+    mode?: number;
+    beforeCommit?: () => Promise<void> | void;
+    /** @internal deterministic seam after exact-state validation while the cross-process lock is held. */
+    afterValidation?: () => Promise<void> | void;
+    /** @internal bypass only for cross-process lock regression tests. */
+    serializeInProcess?: boolean;
+    /** @internal deterministic helper-crash seam for stale-temp recovery tests. */
+    crashAfterTempStage?: 'create' | 'write' | 'fsync';
+    /** @internal simulate disagreement from a repeated native owner probe. */
+    testMismatchedCurrentTempOwnerHash?: boolean;
+    /** @internal deterministic seam once an independent helper is waiting on the writer fence. */
+    afterLockContention?: () => Promise<void> | void;
+    /** @internal deterministic independent commit-authority crash seam. */
+    crashPublicationCommitStage?: 'create' | 'partial-write' | 'fsync';
+    /** @internal deterministic committed-cleanup crash seam. */
+    crashPublicationRetirementStage?: 'temp' | 'recovery' | 'quarantine' | 'marker' | 'commit';
+    /** @internal deterministic private transaction crash seam. */
+    crashPublicationPrivateRetirementStage?: PublicationPrivateRetirementStage;
+    /** @internal deterministic seam before committed prepared-temp disposition. */
+    beforePreparedTempRetirement?: (tempPath: string) => Promise<void> | void;
+    /** @internal deterministic seam at the final temp-name disposition boundary. */
+    beforePreparedTempFinalization?: (tempPath: string) => Promise<void> | void;
+    /** @internal after desktop proof is durable, immediately before guard unlink. */
+    beforePublicationAuthorityFinalization?: (tempPath: string) => Promise<void> | void;
+    /** Exact parent directory that must own the mutation. */
+    expectedParent?: AnchoredFsIdentity | WorkspaceRootAuthority;
+    /** Maximum existing/temp target bytes the helper may read or hash. */
+    maxTargetBytes: number;
+    /**
+     * Stable task/session ownership key for private crash authority. It is
+     * hashed before crossing the helper boundary and never written verbatim.
+     */
+    publicationOwnerKey?: string;
+    /** @internal deterministic post-publication directory-fsync failure seam. */
+    failDirectorySync?: boolean;
+    /** @internal deterministic seam immediately before an exact final unlink. */
+    beforeFinalRemove?: (quarantinePath: string) => Promise<void> | void;
+    /** @internal exact syscall seam before an existing target is quarantined. */
+    beforeTargetQuarantine?: (targetPath: string, quarantinePath: string) => Promise<void> | void;
+    /** @internal lower deterministic helper deadline for tests. */
+    helperTimeoutMs?: number;
+    /** @internal deterministic blocked-helper seam. */
+    testHangBeforeReady?: boolean;
+}): Promise<AnchoredCommittedFile>;
+/**
+ * Hold one crash-reclaimable, inode-anchored cross-process lock for the full
+ * lifetime of `operation`. The callback process and its OS creation identity
+ * own the lock; the helper merely performs anchored acquisition/release. A
+ * helper crash cannot split the fence, and PID reuse cannot inherit it.
+ * The lock file itself carries no application authority.
+ */
+export declare function withAnchoredExclusiveLock<T>(lockPath: string, operation: () => Promise<T>, opts?: {
+    /** Maximum time to wait for another live owner; ownership itself has no lease. */
+    acquireTimeoutMs?: number;
+    /** Exact parent directory that must contain the lock. */
+    expectedParent?: AnchoredFsIdentity | WorkspaceRootAuthority;
+    /** Cancel only while waiting to acquire; once entered, `operation` owns shutdown semantics. */
+    signal?: AbortSignal;
+    /** @internal deterministic seam immediately before exact lock-artifact removal. */
+    beforeFinalRemove?: (quarantinePath: string) => Promise<void> | void;
+    /** @internal kill the acquisition helper after LOCKED to prove owner continuity. */
+    crashHelperAfterAcquire?: boolean;
+    /** @internal lower deterministic helper deadline for tests. */
+    helperTimeoutMs?: number;
+}): Promise<T>;
+export declare function anchoredRemoveTree(target: string, identity: WorkspaceRootAuthority, opts?: {
+    beforeCommit?: () => Promise<void> | void;
+    afterRename?: (tombstonePath: string) => Promise<void> | void;
+    /** @internal lower deterministic helper/tree-cleaner deadline for tests. */
+    helperTimeoutMs?: number;
+    /** @internal deterministic blocked-helper seam. */
+    testHangBeforeReady?: boolean;
+    /** @internal deterministic blocked recursive tree-cleaner seam. */
+    testHangTreeCleaner?: boolean;
+}): Promise<void>;
+export declare function anchoredRemoveFile(filePath: string, expectedIdentity?: AnchoredFsIdentity, opts?: {
+    beforeFinalRemove?: (quarantinePath: string) => Promise<void> | void;
+    expectedParent?: AnchoredFsIdentity | WorkspaceRootAuthority;
+    /** @internal deterministic post-unlink directory-fsync failure seam. */
+    failDirectorySync?: boolean;
+}): Promise<void>;
+/** Reclaim dead helper temp/lock/release/token residue for one anchored marker path. */
+export declare function anchoredCleanupWriteArtifacts(filePath: string, opts?: {
+    waitForLive?: boolean;
+    beforeFinalRemove?: (quarantinePath: string) => Promise<void> | void;
+    helperTimeoutMs?: number;
+    /** Exact parent directory that must own every recovered artifact. */
+    expectedParent?: AnchoredFsIdentity | WorkspaceRootAuthority;
+    /** @internal deterministic restart-disposition race seam. */
+    beforePreparedTempFinalization?: (tempPath: string) => Promise<void> | void;
+    /** @internal deterministic final guard-link race seam. */
+    beforePublicationAuthorityFinalization?: (tempPath: string) => Promise<void> | void;
+    /** @internal deterministic private transaction crash seam. */
+    crashPublicationPrivateRetirementStage?: PublicationPrivateRetirementStage;
+}): Promise<void>;
+export declare function anchoredRemoveEmptyDirectory(dir: string, expectedIdentity?: AnchoredFsIdentity, opts?: {
+    /** Exact parent directory that must own the retiring child. */
+    expectedParent?: AnchoredFsIdentity | WorkspaceRootAuthority;
+}): Promise<void>;
+export {};