@chances-ai/engine 24.0.0

package/dist/core/worktree/paths.d.ts

@@ -0,0 +1,26 @@
+export declare const WORKTREE_DIR_NAME = "worktrees";
+export declare const CHANCES_DIR_NAME = ".chances";
+export declare const ACTIVE_MARKER_FILE = "chances-active.json";
+/** `<canonicalRoot>/.chances/worktrees`. Parent directory for every agent
+ * worktree under this repo. Created lazily on first `createAgentWorktree`. */
+export declare function worktreesDir(canonicalRoot: string): string;
+/** `<canonicalRoot>/.chances/worktrees/<slug>`. The exact path `git worktree
+ * add` is invoked against. */
+export declare function worktreePathFor(canonicalRoot: string, slug: string): string;
+/**
+ * Liveness marker for an active agent worktree. Stored INSIDE the worktree's
+ * git-admin directory (`<repo>/.git/worktrees/<slug>/chances-active.json`),
+ * not inside the worktree's working tree — so `git status` never sees it as
+ * an untracked file (which would otherwise mark the worktree dirty and
+ * defeat the GC). The admin dir is created by `git worktree add` and lives
+ * for the worktree's lifetime; cleanup is handled by `git worktree remove`.
+ *
+ * For a linked worktree, `<worktreePath>/.git` is a pointer file whose first
+ * line reads `gitdir: <admin-dir>`. We resolve it on demand.
+ */
+export declare function activeMarkerPathFor(worktreePath: string): Promise<string>;
+/** Resolves the worktree's git-admin directory. For linked worktrees this is
+ * `<repo>/.git/worktrees/<slug>/`; for the main worktree (rarely the case
+ * for agent worktrees, but supported) it's `<repo>/.git`. */
+export declare function resolveWorktreeGitDir(worktreePath: string): Promise<string>;
+//# sourceMappingURL=paths.d.ts.map

package/dist/core/worktree/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../../src/core/worktree/paths.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,iBAAiB,cAAc,CAAC;AAC7C,eAAO,MAAM,gBAAgB,aAAa,CAAC;AAC3C,eAAO,MAAM,kBAAkB,wBAAwB,CAAC;AAExD;8EAC8E;AAC9E,wBAAgB,YAAY,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED;8BAC8B;AAC9B,wBAAgB,eAAe,CAAC,aAAa,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE3E;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,mBAAmB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAG/E;AAED;;6DAE6D;AAC7D,wBAAsB,qBAAqB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAmBjF"}

package/dist/core/worktree/paths.js

@@ -0,0 +1,57 @@
+import { readFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+export const WORKTREE_DIR_NAME = "worktrees";
+export const CHANCES_DIR_NAME = ".chances";
+export const ACTIVE_MARKER_FILE = "chances-active.json";
+/** `<canonicalRoot>/.chances/worktrees`. Parent directory for every agent
+ * worktree under this repo. Created lazily on first `createAgentWorktree`. */
+export function worktreesDir(canonicalRoot) {
+    return join(canonicalRoot, CHANCES_DIR_NAME, WORKTREE_DIR_NAME);
+}
+/** `<canonicalRoot>/.chances/worktrees/<slug>`. The exact path `git worktree
+ * add` is invoked against. */
+export function worktreePathFor(canonicalRoot, slug) {
+    return join(worktreesDir(canonicalRoot), slug);
+}
+/**
+ * Liveness marker for an active agent worktree. Stored INSIDE the worktree's
+ * git-admin directory (`<repo>/.git/worktrees/<slug>/chances-active.json`),
+ * not inside the worktree's working tree — so `git status` never sees it as
+ * an untracked file (which would otherwise mark the worktree dirty and
+ * defeat the GC). The admin dir is created by `git worktree add` and lives
+ * for the worktree's lifetime; cleanup is handled by `git worktree remove`.
+ *
+ * For a linked worktree, `<worktreePath>/.git` is a pointer file whose first
+ * line reads `gitdir: <admin-dir>`. We resolve it on demand.
+ */
+export async function activeMarkerPathFor(worktreePath) {
+    const adminDir = await resolveWorktreeGitDir(worktreePath);
+    return join(adminDir, ACTIVE_MARKER_FILE);
+}
+/** Resolves the worktree's git-admin directory. For linked worktrees this is
+ * `<repo>/.git/worktrees/<slug>/`; for the main worktree (rarely the case
+ * for agent worktrees, but supported) it's `<repo>/.git`. */
+export async function resolveWorktreeGitDir(worktreePath) {
+    const dotGit = join(worktreePath, ".git");
+    let body;
+    try {
+        body = await readFile(dotGit, "utf8");
+    }
+    catch (e) {
+        // `.git` may be a directory in the (unusual) main-worktree case; fall
+        // back to using that directory as the admin dir.
+        if (e.code === "EISDIR")
+            return dotGit;
+        throw e;
+    }
+    const m = body.match(/^gitdir:\s*(.+?)\s*$/m);
+    if (!m)
+        return dotGit;
+    // (Round-2 SHOULD-FIX #6) Older Git or special configs can write a
+    // RELATIVE `gitdir:` path; the standard resolution rule is "relative
+    // to the directory containing the `.git` pointer file" (i.e. the
+    // worktree dir).
+    const target = m[1];
+    return isAbsolute(target) ? target : resolve(dirname(dotGit), target);
+}
+//# sourceMappingURL=paths.js.map

package/dist/core/worktree/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../../src/core/worktree/paths.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAE/D,MAAM,CAAC,MAAM,iBAAiB,GAAG,WAAW,CAAC;AAC7C,MAAM,CAAC,MAAM,gBAAgB,GAAG,UAAU,CAAC;AAC3C,MAAM,CAAC,MAAM,kBAAkB,GAAG,qBAAqB,CAAC;AAExD;8EAC8E;AAC9E,MAAM,UAAU,YAAY,CAAC,aAAqB;IAChD,OAAO,IAAI,CAAC,aAAa,EAAE,gBAAgB,EAAE,iBAAiB,CAAC,CAAC;AAClE,CAAC;AAED;8BAC8B;AAC9B,MAAM,UAAU,eAAe,CAAC,aAAqB,EAAE,IAAY;IACjE,OAAO,IAAI,CAAC,YAAY,CAAC,aAAa,CAAC,EAAE,IAAI,CAAC,CAAC;AACjD,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,YAAoB;IAC5D,MAAM,QAAQ,GAAG,MAAM,qBAAqB,CAAC,YAAY,CAAC,CAAC;IAC3D,OAAO,IAAI,CAAC,QAAQ,EAAE,kBAAkB,CAAC,CAAC;AAC5C,CAAC;AAED;;6DAE6D;AAC7D,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAC,YAAoB;IAC9D,MAAM,MAAM,GAAG,IAAI,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;IAC1C,IAAI,IAAY,CAAC;IACjB,IAAI,CAAC;QACH,IAAI,GAAG,MAAM,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,sEAAsE;QACtE,iDAAiD;QACjD,IAAK,CAA2B,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,MAAM,CAAC;QAClE,MAAM,CAAC,CAAC;IACV,CAAC;IACD,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,uBAAuB,CAAC,CAAC;IAC9C,IAAI,CAAC,CAAC;QAAE,OAAO,MAAM,CAAC;IACtB,mEAAmE;IACnE,qEAAqE;IACrE,iEAAiE;IACjE,iBAAiB;IACjB,MAAM,MAAM,GAAG,CAAC,CAAC,CAAC,CAAE,CAAC;IACrB,OAAO,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC;AACxE,CAAC"}

package/dist/core/worktree/slug.d.ts

@@ -0,0 +1,6 @@
+export declare function newAgentSlug(): string;
+export declare function isAgentSlug(s: string): boolean;
+/** Slug → branch name. The `chances/` namespace is ours; users can `git
+ * branch -D chances/*` to reclaim. */
+export declare function branchNameFor(slug: string): string;
+//# sourceMappingURL=slug.d.ts.map

package/dist/core/worktree/slug.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slug.d.ts","sourceRoot":"","sources":["../../../src/core/worktree/slug.ts"],"names":[],"mappings":"AAQA,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAE9C;AAED;sCACsC;AACtC,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKlD"}

package/dist/core/worktree/slug.js

@@ -0,0 +1,21 @@
+import { randomBytes } from "node:crypto";
+/** Slug format: `agent-` followed by exactly 8 lowercase hex chars. Matches
+ * claude-code's per-subagent slug shape. Branch-name-safe (no `/`), short
+ * enough to read, ~4 billion-space entropy so birthday collisions are
+ * negligible at any realistic concurrent-subagent count. */
+const SLUG_RE = /^agent-[0-9a-f]{8}$/;
+export function newAgentSlug() {
+    return `agent-${randomBytes(4).toString("hex")}`;
+}
+export function isAgentSlug(s) {
+    return SLUG_RE.test(s);
+}
+/** Slug → branch name. The `chances/` namespace is ours; users can `git
+ * branch -D chances/*` to reclaim. */
+export function branchNameFor(slug) {
+    if (!isAgentSlug(slug)) {
+        throw new Error(`invalid slug for branch name: ${slug}`);
+    }
+    return `chances/worktree-${slug}`;
+}
+//# sourceMappingURL=slug.js.map

package/dist/core/worktree/slug.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"slug.js","sourceRoot":"","sources":["../../../src/core/worktree/slug.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C;;;4DAG4D;AAC5D,MAAM,OAAO,GAAG,qBAAqB,CAAC;AAEtC,MAAM,UAAU,YAAY;IAC1B,OAAO,SAAS,WAAW,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;AACnD,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,CAAS;IACnC,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AACzB,CAAC;AAED;sCACsC;AACtC,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CAAC,iCAAiC,IAAI,EAAE,CAAC,CAAC;IAC3D,CAAC;IACD,OAAO,oBAAoB,IAAI,EAAE,CAAC;AACpC,CAAC"}

package/dist/local-vault/file-store.d.ts

@@ -0,0 +1,64 @@
+/**
+ * (3.7) AES-256-GCM encrypted JSON file backend with scrypt KDF.
+ *
+ * On-disk format (versioned for forward-compat):
+ *   { v: 1, salt: base64, iv: base64, ciphertext: base64, tag: base64 }
+ *
+ * - Salt: 16 random bytes generated on first write; persisted unchanged
+ *   thereafter so the derived key stays stable across writes.
+ * - IV: 12 random bytes ROTATED on every write (GCM requires unique
+ *   IV per key/plaintext pair).
+ * - KDF: scryptSync (N=16384, r=8, p=1). Matches claude-code's LocalVault
+ *   parameters. Cached per-passphrase+salt to amortise the ~80–150 ms
+ *   derivation cost across writes within one process.
+ *
+ * **(codex Round-1 MUST-FIX #1)** All mutations go through `mergeMutate`
+ * which serialises per-key via the KeyedMutex and preserves unrelated
+ * fields. Atomic-rename alone is insufficient — concurrent partial
+ * updates would clobber each other.
+ */
+export interface FileStoreOptions {
+    filePath: string;
+    passphrase: string;
+    /** Test seam — defaults to `randomBytes`. */
+    generateBytes?: (n: number) => Buffer;
+}
+export declare class FileStore {
+    private readonly mutex;
+    private readonly opts;
+    private cachedKey?;
+    constructor(opts: FileStoreOptions);
+    /** Returns the JSON value at `key`, or `undefined` when absent. */
+    read<T = unknown>(key: string): Promise<T | undefined>;
+    /** Returns every top-level key. */
+    list(): Promise<readonly string[]>;
+    /** Removes a key. No-op when absent. */
+    remove(key: string): Promise<void>;
+    /**
+     * The cornerstone API. Serialises per-key R-W-CAS:
+     *   1. Decrypt the whole on-disk blob.
+     *   2. Call `mutator(currentValueAtKey)`.
+     *   3. If mutator returns a value, replace; if it returns undefined AND
+     *      `allowDelete` is true, delete the entry.
+     *   4. Encrypt + atomic-write.
+     *
+     * **(3.7 codex Round-2 MUST-FIX #1)** Uses a SINGLE file-wide mutex
+     * (constant `FILE_LOCK_KEY`), not a per-key mutex. The on-disk format
+     * is one encrypted JSON blob — read-modify-write of `key=A` and
+     * `key=B` both decrypt the SAME ciphertext, mutate different slots,
+     * and the last writer's `encryptAndWrite()` clobbers the other's
+     * mutation. Per-key locking only protects same-key writes; cross-key
+     * concurrency loses data. Serialising every file write behind one
+     * lock costs concurrency that file-vault setups don't have (write
+     * volume is "every few minutes when a token refreshes") and buys
+     * correctness on the only invariant that matters.
+     */
+    mergeMutate<T>(key: string, mutator: (current: T | undefined) => T | undefined | Promise<T | undefined>, allowDelete?: boolean): Promise<void>;
+    /** Decrypts the whole file. Returns `{}` when the file doesn't exist. */
+    private decryptAll;
+    /** Encrypts a payload and atomically writes the file. */
+    private encryptAndWrite;
+    /** Cached scrypt derivation. */
+    private deriveKey;
+}
+//# sourceMappingURL=file-store.d.ts.map

package/dist/local-vault/file-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-store.d.ts","sourceRoot":"","sources":["../../src/local-vault/file-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAOH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,6CAA6C;IAC7C,aAAa,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;CACvC;AAyBD,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoB;IAC1C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAmB;IACxC,OAAO,CAAC,SAAS,CAAC,CAAgC;gBAEtC,IAAI,EAAE,gBAAgB;IAIlC,mEAAmE;IAC7D,IAAI,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IAU5D,mCAAmC;IAC7B,IAAI,IAAI,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC;IAYxC,wCAAwC;IAClC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOxC;;;;;;;;;;;;;;;;;;OAkBG;IACG,WAAW,CAAC,CAAC,EACjB,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,SAAS,KAAK,CAAC,GAAG,SAAS,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,EAC3E,WAAW,UAAQ,GAClB,OAAO,CAAC,IAAI,CAAC;IAiChB,yEAAyE;IACzE,OAAO,CAAC,UAAU;IAsClB,yDAAyD;IACzD,OAAO,CAAC,eAAe;IA0CvB,gCAAgC;IAChC,OAAO,CAAC,SAAS;CAYlB"}

package/dist/local-vault/file-store.js

@@ -0,0 +1,225 @@
+/**
+ * (3.7) AES-256-GCM encrypted JSON file backend with scrypt KDF.
+ *
+ * On-disk format (versioned for forward-compat):
+ *   { v: 1, salt: base64, iv: base64, ciphertext: base64, tag: base64 }
+ *
+ * - Salt: 16 random bytes generated on first write; persisted unchanged
+ *   thereafter so the derived key stays stable across writes.
+ * - IV: 12 random bytes ROTATED on every write (GCM requires unique
+ *   IV per key/plaintext pair).
+ * - KDF: scryptSync (N=16384, r=8, p=1). Matches claude-code's LocalVault
+ *   parameters. Cached per-passphrase+salt to amortise the ~80–150 ms
+ *   derivation cost across writes within one process.
+ *
+ * **(codex Round-1 MUST-FIX #1)** All mutations go through `mergeMutate`
+ * which serialises per-key via the KeyedMutex and preserves unrelated
+ * fields. Atomic-rename alone is insufficient — concurrent partial
+ * updates would clobber each other.
+ */
+import { createCipheriv, createDecipheriv, randomBytes, scryptSync } from "node:crypto";
+import { existsSync, readFileSync, renameSync, statSync, writeFileSync, chmodSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { KeyedMutex } from "./mutex.js";
+const SALT_LEN = 16;
+const IV_LEN = 12;
+const KEY_LEN = 32;
+const SCRYPT_N = 16384;
+const SCRYPT_R = 8;
+const SCRYPT_P = 1;
+/** (codex Round-2 MUST-FIX #1) Single file-wide lock key — every
+ *  `mergeMutate` rewrites the whole encrypted blob, so cross-key
+ *  concurrency is unsafe with per-key granularity. See class docstring. */
+const FILE_LOCK_KEY = "__file_lock__";
+export class FileStore {
+    mutex = new KeyedMutex();
+    opts;
+    cachedKey;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    /** Returns the JSON value at `key`, or `undefined` when absent. */
+    async read(key) {
+        const release = await this.mutex.acquire(key);
+        try {
+            const payload = this.decryptAll();
+            return payload[key];
+        }
+        finally {
+            release();
+        }
+    }
+    /** Returns every top-level key. */
+    async list() {
+        // Global lock — we read every key. Mutate ops do per-key locking; this
+        // is the lone exception that competes with EVERY pending write.
+        const release = await this.mutex.acquire("__list__");
+        try {
+            const payload = this.decryptAll();
+            return Object.keys(payload);
+        }
+        finally {
+            release();
+        }
+    }
+    /** Removes a key. No-op when absent. */
+    async remove(key) {
+        await this.mergeMutate(key, (current) => {
+            if (current === undefined)
+                return undefined;
+            return undefined; // Marker for delete (vs no-change)
+        }, /*allowDelete=*/ true);
+    }
+    /**
+     * The cornerstone API. Serialises per-key R-W-CAS:
+     *   1. Decrypt the whole on-disk blob.
+     *   2. Call `mutator(currentValueAtKey)`.
+     *   3. If mutator returns a value, replace; if it returns undefined AND
+     *      `allowDelete` is true, delete the entry.
+     *   4. Encrypt + atomic-write.
+     *
+     * **(3.7 codex Round-2 MUST-FIX #1)** Uses a SINGLE file-wide mutex
+     * (constant `FILE_LOCK_KEY`), not a per-key mutex. The on-disk format
+     * is one encrypted JSON blob — read-modify-write of `key=A` and
+     * `key=B` both decrypt the SAME ciphertext, mutate different slots,
+     * and the last writer's `encryptAndWrite()` clobbers the other's
+     * mutation. Per-key locking only protects same-key writes; cross-key
+     * concurrency loses data. Serialising every file write behind one
+     * lock costs concurrency that file-vault setups don't have (write
+     * volume is "every few minutes when a token refreshes") and buys
+     * correctness on the only invariant that matters.
+     */
+    async mergeMutate(key, mutator, allowDelete = false) {
+        const release = await this.mutex.acquire(FILE_LOCK_KEY);
+        try {
+            // Re-read inside the lock so we always see the latest state, even if
+            // another tab/process raced us between the mutex-acquire and our read.
+            // (Cross-process is still out of scope — see § 1 of the design doc —
+            // but in-process correctness is locked down here.)
+            const payload = this.decryptAll();
+            const previous = payload[key];
+            const next = await mutator(previous);
+            if (next === undefined) {
+                if (!allowDelete && previous === undefined) {
+                    // Mutator declined to set, and nothing was there — write a no-op.
+                    // Returning here skips the disk write to avoid pointless IV churn.
+                    return;
+                }
+                if (allowDelete) {
+                    delete payload[key];
+                }
+                else if (previous !== undefined) {
+                    // Mutator returned undefined but allowDelete is false — interpret
+                    // as "no change," not delete. Defensive — keeps the API
+                    // explicit about the destructive intent of `remove`.
+                    return;
+                }
+            }
+            else {
+                payload[key] = next;
+            }
+            this.encryptAndWrite(payload);
+        }
+        finally {
+            release();
+        }
+    }
+    /** Decrypts the whole file. Returns `{}` when the file doesn't exist. */
+    decryptAll() {
+        if (!existsSync(this.opts.filePath))
+            return {};
+        const raw = readFileSync(this.opts.filePath, "utf8");
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch (e) {
+            throw new Error(`local-vault: failed to parse ${this.opts.filePath}: ${e.message}. ` +
+                `The file may be corrupted; back it up and delete to start fresh.`);
+        }
+        if (parsed.v !== 1) {
+            throw new Error(`local-vault: unsupported on-disk version ${parsed.v} (this build supports v1)`);
+        }
+        const salt = Buffer.from(parsed.salt, "base64");
+        const iv = Buffer.from(parsed.iv, "base64");
+        const ciphertext = Buffer.from(parsed.ciphertext, "base64");
+        const tag = Buffer.from(parsed.tag, "base64");
+        const key = this.deriveKey(salt);
+        const decipher = createDecipheriv("aes-256-gcm", key, iv);
+        decipher.setAuthTag(tag);
+        let plaintext;
+        try {
+            plaintext = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+        }
+        catch (e) {
+            throw new Error(`local-vault: decryption failed — wrong passphrase OR corrupted file. ` +
+                `Underlying: ${e.message}`);
+        }
+        try {
+            return JSON.parse(plaintext.toString("utf8"));
+        }
+        catch (e) {
+            throw new Error(`local-vault: decrypted JSON is malformed: ${e.message}`);
+        }
+    }
+    /** Encrypts a payload and atomically writes the file. */
+    encryptAndWrite(payload) {
+        // Reuse the existing salt when present, else mint a new one.
+        let salt;
+        if (this.cachedKey) {
+            salt = this.cachedKey.salt;
+        }
+        else if (existsSync(this.opts.filePath)) {
+            // Edge: cache empty but file exists. Read the salt from disk.
+            const existing = JSON.parse(readFileSync(this.opts.filePath, "utf8"));
+            salt = Buffer.from(existing.salt, "base64");
+        }
+        else {
+            salt = (this.opts.generateBytes ?? randomBytes)(SALT_LEN);
+        }
+        const key = this.deriveKey(salt);
+        const iv = (this.opts.generateBytes ?? randomBytes)(IV_LEN);
+        const cipher = createCipheriv("aes-256-gcm", key, iv);
+        const plaintext = Buffer.from(JSON.stringify(payload), "utf8");
+        const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+        const tag = cipher.getAuthTag();
+        const wire = {
+            v: 1,
+            salt: salt.toString("base64"),
+            iv: iv.toString("base64"),
+            ciphertext: ciphertext.toString("base64"),
+            tag: tag.toString("base64"),
+        };
+        // Ensure parent dir exists. Atomic write via tmp + rename.
+        mkdirSync(dirname(this.opts.filePath), { recursive: true });
+        const tmp = `${this.opts.filePath}.tmp.${process.pid}.${Date.now()}`;
+        writeFileSync(tmp, JSON.stringify(wire), { mode: 0o600 });
+        renameSync(tmp, this.opts.filePath);
+        if (process.platform !== "win32") {
+            // Re-assert 0600 — atomic rename preserves source mode, but a tmp
+            // file created with umask interference could land at 0644.
+            try {
+                const stat = statSync(this.opts.filePath);
+                if ((stat.mode & 0o777) !== 0o600)
+                    chmodSync(this.opts.filePath, 0o600);
+            }
+            catch {
+                /* race; fall through */
+            }
+        }
+    }
+    /** Cached scrypt derivation. */
+    deriveKey(salt) {
+        if (this.cachedKey && this.cachedKey.salt.equals(salt)) {
+            return this.cachedKey.key;
+        }
+        const key = scryptSync(this.opts.passphrase, salt, KEY_LEN, {
+            N: SCRYPT_N,
+            r: SCRYPT_R,
+            p: SCRYPT_P,
+        });
+        this.cachedKey = { salt, key };
+        return key;
+    }
+}
+//# sourceMappingURL=file-store.js.map

package/dist/local-vault/file-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-store.js","sourceRoot":"","sources":["../../src/local-vault/file-store.ts"],"names":[],"mappings":"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"}

package/dist/local-vault/index.d.ts

@@ -0,0 +1,57 @@
+/**
+ * (3.7) `@chances-ai/local-vault` — encrypted credential store.
+ *
+ * Public surface: `createLocalVault(opts?) -> Promise<LocalVault>`.
+ *
+ * Backend selection at boot:
+ *   1. Probe `@napi-rs/keyring` — if it loads AND a set/get round-trip
+ *      against a probe key succeeds, backend = keychain.
+ *   2. Otherwise, backend = AES-256-GCM file at
+ *      `<rootDir>/local-vault.enc.json`, with passphrase resolved per
+ *      `passphrase.ts` (env > sibling file > generated).
+ *
+ * Both backends share the same `LocalVault` surface: read/list/remove/
+ * mergeMutate/diagnostics. The mergeMutate primitive (per-key serialised
+ * read-modify-write) is the codex Round-1 MUST-FIX #1 fix — atomic
+ * rename alone doesn't prevent partial-update clobber.
+ */
+import { type KeyringLoader } from "./keychain.js";
+export interface LocalVault {
+    read<T = unknown>(key: string): Promise<T | undefined>;
+    list(): Promise<readonly string[]>;
+    remove(key: string): Promise<void>;
+    /** Per-key serialised read-modify-write. Mutator receives the current
+     *  value (or undefined). Returning a value writes it. Returning
+     *  undefined is a no-op UNLESS `allowDelete=true`. */
+    mergeMutate<T>(key: string, mutator: (current: T | undefined) => T | undefined | Promise<T | undefined>, allowDelete?: boolean): Promise<void>;
+    diagnostics(): VaultDiagnostics;
+}
+export interface VaultDiagnostics {
+    backend: "keychain" | "file";
+    /** Human-readable reasons explaining why the keychain backend was
+     *  bypassed, when applicable. */
+    warnings: readonly string[];
+}
+export interface CreateLocalVaultOptions {
+    /** Where vault data lives. Defaults to `~/.chances/`. */
+    rootDir?: string;
+    /** Where the passphrase file lives. Defaults to
+     *  `<dirname(homedir)>/.chances-vault-passphrase` — OUTSIDE the
+     *  vault tree so a backup of `rootDir` alone doesn't leak the key
+     *  (codex Round-1 SHOULD-FIX). */
+    passphraseFile?: string;
+    /** Test seam — swap the keyring loader. Defaults to the real loader. */
+    keyringLoader?: KeyringLoader;
+    /** Force the file backend even when keychain is available. Used for
+     *  smoke tests of the fallback path; users shouldn't set this. */
+    forceFileBackend?: boolean;
+    /** Test seam — override the passphrase resolution entirely. */
+    fixedPassphrase?: string;
+}
+export declare const VAULT_FILE_NAME = "local-vault.enc.json";
+export declare function createLocalVault(opts?: CreateLocalVaultOptions): Promise<LocalVault>;
+export { FileStore } from "./file-store.js";
+export { KeychainStore, type KeyringLoader, type KeyringModule } from "./keychain.js";
+export { resolvePassphrase, ENV_VAR as VAULT_ENV_VAR } from "./passphrase.js";
+export { KeyedMutex } from "./mutex.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/local-vault/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/local-vault/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAKH,OAAO,EAAiB,KAAK,aAAa,EAAE,MAAM,eAAe,CAAC;AAGlE,MAAM,WAAW,UAAU;IACzB,IAAI,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IACvD,IAAI,IAAI,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CAAC;IACnC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC;;0DAEsD;IACtD,WAAW,CAAC,CAAC,EACX,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,SAAS,KAAK,CAAC,GAAG,SAAS,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,EAC3E,WAAW,CAAC,EAAE,OAAO,GACpB,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB,WAAW,IAAI,gBAAgB,CAAC;CACjC;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,UAAU,GAAG,MAAM,CAAC;IAC7B;qCACiC;IACjC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B;AAED,MAAM,WAAW,uBAAuB;IACtC,yDAAyD;IACzD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;sCAGkC;IAClC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,wEAAwE;IACxE,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B;sEACkE;IAClE,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,+DAA+D;IAC/D,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,eAAO,MAAM,eAAe,yBAAyB,CAAC;AAEtD,wBAAsB,gBAAgB,CAAC,IAAI,GAAE,uBAA4B,GAAG,OAAO,CAAC,UAAU,CAAC,CAqB9F;AAuBD,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,KAAK,aAAa,EAAE,KAAK,aAAa,EAAE,MAAM,eAAe,CAAC;AACtF,OAAO,EAAE,iBAAiB,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAC9E,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC"}

package/dist/local-vault/index.js

@@ -0,0 +1,68 @@
+/**
+ * (3.7) `@chances-ai/local-vault` — encrypted credential store.
+ *
+ * Public surface: `createLocalVault(opts?) -> Promise<LocalVault>`.
+ *
+ * Backend selection at boot:
+ *   1. Probe `@napi-rs/keyring` — if it loads AND a set/get round-trip
+ *      against a probe key succeeds, backend = keychain.
+ *   2. Otherwise, backend = AES-256-GCM file at
+ *      `<rootDir>/local-vault.enc.json`, with passphrase resolved per
+ *      `passphrase.ts` (env > sibling file > generated).
+ *
+ * Both backends share the same `LocalVault` surface: read/list/remove/
+ * mergeMutate/diagnostics. The mergeMutate primitive (per-key serialised
+ * read-modify-write) is the codex Round-1 MUST-FIX #1 fix — atomic
+ * rename alone doesn't prevent partial-update clobber.
+ */
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { FileStore } from "./file-store.js";
+import { KeychainStore } from "./keychain.js";
+import { resolvePassphrase } from "./passphrase.js";
+export const VAULT_FILE_NAME = "local-vault.enc.json";
+export async function createLocalVault(opts = {}) {
+    const rootDir = opts.rootDir ?? join(homedir(), ".chances");
+    const passphraseFile = opts.passphraseFile ?? join(homedir(), ".chances-vault-passphrase");
+    const warnings = [];
+    // 1. Try keychain first, unless explicitly forced to file.
+    if (!opts.forceFileBackend) {
+        const probe = await KeychainStore.tryCreate(opts.keyringLoader);
+        if (probe.store) {
+            return wrapKeychain(probe.store);
+        }
+        warnings.push(probe.reason);
+    }
+    else {
+        warnings.push("forceFileBackend=true (test/diagnostic mode)");
+    }
+    // 2. Fall back to file backend.
+    const filePath = join(rootDir, VAULT_FILE_NAME);
+    const passphrase = opts.fixedPassphrase ?? resolvePassphrase({ passphraseFile }).passphrase;
+    const file = new FileStore({ filePath, passphrase });
+    return wrapFile(file, warnings);
+}
+function wrapKeychain(store) {
+    return {
+        read: (k) => store.read(k),
+        list: () => store.list(),
+        remove: (k) => store.remove(k),
+        mergeMutate: (k, m, allowDelete) => store.mergeMutate(k, m, allowDelete),
+        diagnostics: () => ({ backend: "keychain", warnings: [] }),
+    };
+}
+function wrapFile(store, warnings) {
+    const frozen = Object.freeze([...warnings]);
+    return {
+        read: (k) => store.read(k),
+        list: () => store.list(),
+        remove: (k) => store.remove(k),
+        mergeMutate: (k, m, allowDelete) => store.mergeMutate(k, m, allowDelete),
+        diagnostics: () => ({ backend: "file", warnings: frozen }),
+    };
+}
+export { FileStore } from "./file-store.js";
+export { KeychainStore } from "./keychain.js";
+export { resolvePassphrase, ENV_VAR as VAULT_ENV_VAR } from "./passphrase.js";
+export { KeyedMutex } from "./mutex.js";
+//# sourceMappingURL=index.js.map

package/dist/local-vault/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/local-vault/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAsB,MAAM,eAAe,CAAC;AAClE,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAyCpD,MAAM,CAAC,MAAM,eAAe,GAAG,sBAAsB,CAAC;AAEtD,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,OAAgC,EAAE;IACvE,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,OAAO,EAAE,EAAE,UAAU,CAAC,CAAC;IAC5D,MAAM,cAAc,GAAG,IAAI,CAAC,cAAc,IAAI,IAAI,CAAC,OAAO,EAAE,EAAE,2BAA2B,CAAC,CAAC;IAC3F,MAAM,QAAQ,GAAa,EAAE,CAAC;IAE9B,2DAA2D;IAC3D,IAAI,CAAC,IAAI,CAAC,gBAAgB,EAAE,CAAC;QAC3B,MAAM,KAAK,GAAG,MAAM,aAAa,CAAC,SAAS,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;QAChE,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;YAChB,OAAO,YAAY,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QACnC,CAAC;QACD,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAC9B,CAAC;SAAM,CAAC;QACN,QAAQ,CAAC,IAAI,CAAC,8CAA8C,CAAC,CAAC;IAChE,CAAC;IAED,gCAAgC;IAChC,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC;IAChD,MAAM,UAAU,GAAG,IAAI,CAAC,eAAe,IAAI,iBAAiB,CAAC,EAAE,cAAc,EAAE,CAAC,CAAC,UAAU,CAAC;IAC5F,MAAM,IAAI,GAAG,IAAI,SAAS,CAAC,EAAE,QAAQ,EAAE,UAAU,EAAE,CAAC,CAAC;IACrD,OAAO,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;AAClC,CAAC;AAED,SAAS,YAAY,CAAC,KAAoB;IACxC,OAAO;QACL,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;QAC1B,IAAI,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE;QACxB,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;QAC9B,WAAW,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,WAAW,EAAE,EAAE,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,EAAE,CAAC,EAAE,WAAW,CAAC;QACxE,WAAW,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;KAC3D,CAAC;AACJ,CAAC;AAED,SAAS,QAAQ,CAAC,KAAgB,EAAE,QAAkB;IACpD,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC;IAC5C,OAAO;QACL,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;QAC1B,IAAI,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE;QACxB,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;QAC9B,WAAW,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,WAAW,EAAE,EAAE,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,EAAE,CAAC,EAAE,WAAW,CAAC;QACxE,WAAW,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;KAC3D,CAAC;AACJ,CAAC;AAED,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,aAAa,EAA0C,MAAM,eAAe,CAAC;AACtF,OAAO,EAAE,iBAAiB,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAC9E,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC"}

package/dist/local-vault/keychain.d.ts

@@ -0,0 +1,58 @@
+/**
+ * (3.7) OS keychain adapter wrapping `@napi-rs/keyring`.
+ *
+ * Loaded via a computed-specifier dynamic import (same `bun build
+ * --compile` reason as 3.6 OTel) so the binary still compiles when the
+ * optional peer is absent. A consumer that didn't install the keyring
+ * package falls back to the file backend (`./file-store.ts`) — same
+ * graceful degradation as before, no opaque "module not found" crash
+ * at boot.
+ *
+ * Layout: service name `chances-cli` (fixed), account name = vault key.
+ * Values are JSON-stringified before storage; parsed on read.
+ *
+ * **(claude-code anti-pattern noted)** Don't store full RFC 8414 metadata
+ * here — Windows Credential Manager has a 4096-byte limit on stored
+ * values. § 4.2 of the design doc enforces "URLs only" at the higher
+ * (provider) layer; this adapter doesn't try to enforce shape.
+ */
+export interface KeyringEntry {
+    setPassword(password: string): void | Promise<void>;
+    getPassword(): string | null | Promise<string | null>;
+    deletePassword(): boolean | Promise<boolean>;
+}
+export interface KeyringModule {
+    Entry: new (service: string, account: string) => KeyringEntry;
+}
+export type KeyringLoader = () => Promise<KeyringModule | null>;
+export declare class KeychainStore {
+    private readonly mod;
+    private readonly mutex;
+    private constructor();
+    /**
+     * Loads the keyring module + runs an access probe. Returns:
+     *   - the store, when the module loaded AND the probe succeeded;
+     *   - `null` with a reason string, otherwise.
+     *
+     * The probe is critical on macOS — the module loads fine, but the FIRST
+     * keychain op can throw with a user-denied dialog. We catch that here so
+     * the fallback path runs without hanging the consumer.
+     */
+    static tryCreate(loader?: KeyringLoader): Promise<{
+        store: KeychainStore;
+    } | {
+        store: null;
+        reason: string;
+    }>;
+    read<T = unknown>(key: string): Promise<T | undefined>;
+    list(): Promise<readonly string[]>;
+    remove(key: string): Promise<void>;
+    mergeMutate<T>(key: string, mutator: (current: T | undefined) => T | undefined | Promise<T | undefined>, allowDelete?: boolean): Promise<void>;
+    /** (codex Round-2 NICE #3) Update the index under its OWN mutex so
+     *  concurrent `mergeMutate("a")` / `mergeMutate("b")` can't race on
+     *  the shared `__chances_keys__` entry. Each holds its per-key lock
+     *  for the value write, then queues behind the index mutex for the
+     *  list update. `list()` could otherwise drop entries. */
+    private recordKey;
+}
+//# sourceMappingURL=keychain.d.ts.map

package/dist/local-vault/keychain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keychain.d.ts","sourceRoot":"","sources":["../../src/local-vault/keychain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAUH,MAAM,WAAW,YAAY;IAC3B,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpD,WAAW,IAAI,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACtD,cAAc,IAAI,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC9C;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,KAAK,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,YAAY,CAAC;CAC/D;AAED,MAAM,MAAM,aAAa,GAAG,MAAM,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAAC;AAehE,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAgB;IACpC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoB;IAE1C,OAAO;IAIP;;;;;;;;OAQG;WACU,SAAS,CACpB,MAAM,GAAE,aAA6B,GACpC,OAAO,CAAC;QAAE,KAAK,EAAE,aAAa,CAAA;KAAE,GAAG;QAAE,KAAK,EAAE,IAAI,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAwBhE,IAAI,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IAgBtD,IAAI,IAAI,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC;IAWlC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAgClC,WAAW,CAAC,CAAC,EACjB,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,SAAS,KAAK,CAAC,GAAG,SAAS,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,EAC3E,WAAW,UAAQ,GAClB,OAAO,CAAC,IAAI,CAAC;IA6BhB;;;;8DAI0D;YAC5C,SAAS;CAsBxB"}