@quantiya/codevibe-core 2.0.7 → 2.0.9

package/dist/keychain/__tests__/keychain-manager.test.d.ts

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

package/dist/keychain/__tests__/keychain-migrate.test.d.ts

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

package/dist/keychain/__tests__/migrate-nudge.test.d.ts

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

package/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/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>;
     /**
@@ -103,8 +115,10 @@ export declare class KeychainManager {
      *
      * When `encryptedKeys` are NOT provided (cache-only callers — e.g. the
      * orchestration QuorumLoop's `getSessionKey(sessionId)`), the cached key is
-     * returned regardless of generation. This preserves the shipped cache-only
-     * behavior; those callers do not participate in the generation-binding.
+     * 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[], sessionKeyGen?: string | null): Promise<string | null>;
     /**

package/dist/keychain/keychain-migrate.d.ts

@@ -0,0 +1,63 @@
+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;
+}
+interface ParsedIdentity {
+    deviceId: string;
+    publicKey: string;
+}
+/**
+ * Parse a stored device-identity blob into a VALIDATED identity: a canonical-UUID
+ * `deviceId`, a non-empty `publicKey`, AND a non-empty `privateKey`. Anything else
+ * (missing fields, non-UUID deviceId, keyless, unparseable) → null = "not a
+ * recognized identity". Returning null here makes the fork guard treat a
+ * parseable-but-invalid blob as a CONFLICT, not a match — so a file identity missing
+ * its private key can never `--force`-replace a good keyring identity with a keyless
+ * one. (Full ECDH derive-validation is deliberately NOT done: identities come from
+ * our own P-256 keygen, and the NO-CLOBBER invariant already protects the keyring's
+ * copy in the sameIdentity path — a non-empty privateKey field is a sufficient
+ * structural check.)
+ */
+export declare function parseIdentity(raw: string | null | undefined): ParsedIdentity | null;
+export declare function migrateKeychain(deps: MigrateDeps, opts: MigrateOptions): Promise<MigrateResult>;

package/dist/keychain/migrate-nudge.d.ts

@@ -0,0 +1,38 @@
+export interface FileStoreSnapshot {
+    kind: 'absent' | 'unreadable' | 'corrupt' | 'store';
+    /** Account count when kind === 'store'; 0 otherwise. */
+    accountCount: number;
+    /** True when kind === 'store' and the device-identity account parses as a valid identity. */
+    identityValid: boolean;
+    /**
+     * True when any account NAME or VALUE is not a non-empty string (Stage-2
+     * Codex r1+r2): migrate copies EVERY account via keytar.setPassword, whose
+     * checkRequired rejects empty accounts and empty passwords → verify_failed
+     * refusal (possibly after earlier accounts were written). Non-secret check —
+     * length/type only, never content.
+     */
+    hasEmptyAccountEntry: boolean;
+}
+export interface NudgeDeps {
+    /** CODEVIBE_ALLOW_FILE_KEYCHAIN === '1' — the user explicitly chose file storage. */
+    fileKeychainOptIn(): boolean;
+    /** Tri-state migration-tombstone probe (statSync-based). */
+    tombstoneStatus(): 'present' | 'absent' | 'error';
+    /** ONE discriminated read of the file store for the active service. */
+    fileStoreSnapshot(): FileStoreSnapshot;
+    /** Platform-structural "no keyring here" (e.g. headless Linux, no keytar module). */
+    keyringStructurallyAbsent(): boolean;
+    /**
+     * One live keytar read of the keyring's device-identity account. Resolves to
+     * the stored value or null; MAY THROW / reject (locked or denied keyring).
+     * The caller compares the result against null and nothing else (invariant 4).
+     */
+    keytarProbe(): Promise<unknown>;
+}
+/**
+ * True when `login`/`status` should print the keychain-migration suggestion.
+ * Never throws.
+ */
+export declare function shouldSuggestKeychainMigration(deps: NudgeDeps): Promise<boolean>;
+/** The advisory text, single-sourced so login/status/tests render identically. */
+export declare const MIGRATION_NUDGE_LINES: readonly string[];

package/dist/local-executor/__tests__/anchored-fs.test.d.ts

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

package/dist/local-executor/__tests__/bounded-directory.test.d.ts

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

package/dist/local-executor/__tests__/bounded-output.test.d.ts

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

package/dist/local-executor/__tests__/durable-directory.test.d.ts

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

package/dist/local-executor/__tests__/hosted-class-a-sink.test.d.ts

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

package/dist/local-executor/__tests__/process-identity.test.d.ts

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

package/dist/local-executor/__tests__/process-tree.test.d.ts

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

package/dist/local-executor/__tests__/protocol-backlog-wiring.test.d.ts

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

package/dist/local-executor/__tests__/protocol-backlog.test.d.ts

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

package/dist/local-executor/__tests__/publication-authority-capability.test.d.ts

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

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

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

package/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/dist/local-executor/__tests__/workspace-authority.test.d.ts

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

package/dist/local-executor/__tests__/workspace-cleanup-audit.test.d.ts

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

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

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

package/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/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';