sidekick-shared 0.27.5 → 0.28.0

package/dist/claudeLiveGuard.d.ts

@@ -0,0 +1,33 @@
+export type LiveClaudeWriteIntent = 'switch' | 'relogin' | 'repair' | 'rollback';
+/** The live store as read just before the write. */
+export type LiveClaudeStoreState = {
+    status: 'ok';
+    blob: unknown;
+} | {
+    status: 'absent';
+} | {
+    status: 'corrupt';
+} | {
+    status: 'error';
+};
+export interface LiveClaudeWriteRequest {
+    intent: LiveClaudeWriteIntent;
+    live: LiveClaudeStoreState;
+    /** Account uuid of the live identity (`oauthAccount`), null when logged out. */
+    liveAccountUuid: string | null;
+    candidate: unknown;
+    candidateAccountUuid: string;
+    /** `switch`: the outgoing live credential was saved and verified. */
+    capturedOutgoing?: boolean;
+    /** `rollback`: the blob the failed switch wrote. */
+    written?: unknown;
+}
+export type LiveClaudeWriteRefusal = 'live-unreadable' | 'invalid-candidate' | 'same-account' | 'different-account' | 'same-link' | 'not-captured' | 'not-newer' | 'live-changed';
+export type LiveClaudeWriteDecision = {
+    allow: true;
+} | {
+    allow: false;
+    code: LiveClaudeWriteRefusal;
+    reason: string;
+};
+export declare function decideLiveClaudeWrite(request: LiveClaudeWriteRequest): LiveClaudeWriteDecision;

package/dist/claudeLiveGuard.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.decideLiveClaudeWrite = decideLiveClaudeWrite;
+/**
+ * The decision every write into the live Claude credential store must pass.
+ * Pure: callers read the stores, this decides.
+ *
+ * Claude Code rotates the refresh token on every refresh, so the live store
+ * always holds the newest link of its chain. Writing an older link over it
+ * destroys a working login, and installing another account without saving the
+ * live one first loses that account's chain. The rules:
+ *
+ * - `switch`: another account replaces live. Allowed only after the outgoing
+ *   live credential was captured (whenever live holds one), and never with a
+ *   candidate that is the same refresh-token link as live.
+ * - `relogin` / `repair`: the same account's credential replaces live. Allowed
+ *   only when the candidate is strictly fresher (a different refresh token
+ *   with a later expiry); otherwise live is kept.
+ * - `rollback`: restore what a failed switch displaced. Allowed only while the
+ *   live store still holds exactly what that switch wrote (or is empty or
+ *   unparseable); a write Claude Code made in between is never clobbered.
+ * - An unreadable live store (`error`: timeout, locked Keychain) refuses all.
+ */
+const liveCredentialGuard_1 = require("./liveCredentialGuard");
+const claudeCredentials_1 = require("./claudeCredentials");
+function decideLiveClaudeWrite(request) {
+    const candidate = (0, claudeCredentials_1.parseClaudeCredentialBlob)(request.candidate);
+    const live = request.live.status === 'ok' ? (0, claudeCredentials_1.parseClaudeCredentialBlob)(request.live.blob) : null;
+    const liveFp = (0, claudeCredentials_1.claudeRefreshFingerprint)(live);
+    return (0, liveCredentialGuard_1.decideLiveCredentialWrite)({
+        provider: 'Claude',
+        intent: request.intent,
+        liveStatus: request.live.status,
+        candidateValid: candidate !== null,
+        liveHasCredential: live !== null,
+        liveAccountId: request.liveAccountUuid,
+        candidateAccountId: request.candidateAccountUuid,
+        sameLink: liveFp !== null && liveFp === (0, claudeCredentials_1.claudeRefreshFingerprint)(candidate),
+        strictlyNewer: (0, claudeCredentials_1.claudeCredentialFreshness)(candidate) > (0, claudeCredentials_1.claudeCredentialFreshness)(live),
+        capturedOutgoing: request.capturedOutgoing,
+        matchesWritten: request.live.status === 'ok' &&
+            JSON.stringify(request.live.blob) === JSON.stringify(request.written),
+        allowNonOkRollback: true,
+        requireDifferentLinkForAdvance: true,
+    });
+}

package/dist/claudePaths.d.ts

@@ -0,0 +1,11 @@
+export declare function getDefaultClaudeHome(): string;
+/** True when this process runs against the default `~/.claude` home. */
+export declare function isDefaultClaudeHome(): boolean;
+/**
+ * The home the `claude` CLI reads and writes for this process: `CLAUDE_CONFIG_DIR`
+ * when set, else `~/.claude`. Every "live" credential or identity read goes
+ * through this so sidekick follows the same home the CLI does.
+ */
+export declare function getLiveClaudeHome(): string;
+/** Where the `claude` CLI writes session transcripts for this process. */
+export declare function getClaudeProjectsDir(): string;

package/dist/claudePaths.js

@@ -0,0 +1,61 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getDefaultClaudeHome = getDefaultClaudeHome;
+exports.isDefaultClaudeHome = isDefaultClaudeHome;
+exports.getLiveClaudeHome = getLiveClaudeHome;
+exports.getClaudeProjectsDir = getClaudeProjectsDir;
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+function getDefaultClaudeHome() {
+    return path.join(os.homedir(), '.claude');
+}
+/** True when this process runs against the default `~/.claude` home. */
+function isDefaultClaudeHome() {
+    return !process.env.CLAUDE_CONFIG_DIR?.trim();
+}
+/**
+ * The home the `claude` CLI reads and writes for this process: `CLAUDE_CONFIG_DIR`
+ * when set, else `~/.claude`. Every "live" credential or identity read goes
+ * through this so sidekick follows the same home the CLI does.
+ */
+function getLiveClaudeHome() {
+    const explicit = process.env.CLAUDE_CONFIG_DIR?.trim();
+    return explicit ? explicit : getDefaultClaudeHome();
+}
+/** Where the `claude` CLI writes session transcripts for this process. */
+function getClaudeProjectsDir() {
+    return path.join(getLiveClaudeHome(), 'projects');
+}

package/dist/claudeProfiles.d.ts

@@ -1,3 +1,5 @@
+import { getDefaultClaudeHome, getLiveClaudeHome, isDefaultClaudeHome } from './claudePaths';
+export { getDefaultClaudeHome, getLiveClaudeHome, isDefaultClaudeHome };
 /**
  * Claude Code honours this variable ahead of `CLAUDE_CONFIG_DIR` when it
  * derives the keychain item name. Any `claude` child sidekick spawns must not
@@ -8,18 +10,23 @@ export interface ClaudeProfileIdentity {
     email: string;
     uuid: string;
 }
-export declare function getDefaultClaudeHome(): string;
-/** True when this process runs against the default `~/.claude` home. */
-export declare function isDefaultClaudeHome(): boolean;
+export declare function getClaudeProfilesDir(): string;
 /**
- * The home the `claude` CLI reads and writes for this process: `CLAUDE_CONFIG_DIR`
- * when set, else `~/.claude`. Every "live" credential or identity read goes
- * through this so sidekick follows the same home the CLI does.
+ * True when the live home is one of sidekick's own profile homes: a shell
+ * that eval'd `sidekick accounts env` or runs inside `sidekick accounts shell`.
+ * That profile's store then reads as the live store, so sync, re-login, and
+ * switching must not treat it as live: they would delete the shell's only
+ * usable copy and re-point the active account at it.
  */
-export declare function getLiveClaudeHome(): string;
-export declare function getClaudeProfilesDir(): string;
+export declare function isLiveClaudeHomeSidekickProfile(): boolean;
 export declare function getClaudeProfileDir(uuid: string): string;
 export declare function getClaudeProfileHome(uuid: string): string;
+/**
+ * Sidekick's private backup of a profile's credential. Claude Code never reads
+ * it, so it is not a CLI-usable copy: this is where the live account's
+ * credential is mirrored while its profile home stays empty.
+ */
+export declare function getClaudeCredentialBackupPath(uuid: string): string;
 export declare function ensureClaudeProfileDirs(uuid: string): void;
 /**
  * Claude Code hashes the NFC-normalised config directory; macOS hands paths

package/dist/claudeProfiles.js

@@ -33,13 +33,12 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CLAUDE_SECURESTORAGE_CONFIG_DIR_ENV = void 0;
-exports.getDefaultClaudeHome = getDefaultClaudeHome;
-exports.isDefaultClaudeHome = isDefaultClaudeHome;
-exports.getLiveClaudeHome = getLiveClaudeHome;
+exports.CLAUDE_SECURESTORAGE_CONFIG_DIR_ENV = exports.isDefaultClaudeHome = exports.getLiveClaudeHome = exports.getDefaultClaudeHome = void 0;
 exports.getClaudeProfilesDir = getClaudeProfilesDir;
+exports.isLiveClaudeHomeSidekickProfile = isLiveClaudeHomeSidekickProfile;
 exports.getClaudeProfileDir = getClaudeProfileDir;
 exports.getClaudeProfileHome = getClaudeProfileHome;
+exports.getClaudeCredentialBackupPath = getClaudeCredentialBackupPath;
 exports.ensureClaudeProfileDirs = ensureClaudeProfileDirs;
 exports.claudeKeychainSuffix = claudeKeychainSuffix;
 exports.claudeKeychainService = claudeKeychainService;
@@ -56,6 +55,10 @@ const fs = __importStar(require("fs"));
 const os = __importStar(require("os"));
 const path = __importStar(require("path"));
 const accountRegistry_1 = require("./accountRegistry");
+const claudePaths_1 = require("./claudePaths");
+Object.defineProperty(exports, "getDefaultClaudeHome", { enumerable: true, get: function () { return claudePaths_1.getDefaultClaudeHome; } });
+Object.defineProperty(exports, "getLiveClaudeHome", { enumerable: true, get: function () { return claudePaths_1.getLiveClaudeHome; } });
+Object.defineProperty(exports, "isDefaultClaudeHome", { enumerable: true, get: function () { return claudePaths_1.isDefaultClaudeHome; } });
 const DEFAULT_CLAUDE_KEYCHAIN_SERVICE = 'Claude Code-credentials';
 const KEYCHAIN_ACCOUNT_PATTERN = /^[a-zA-Z0-9._-]+$/;
 const KEYCHAIN_FALLBACK_ACCOUNT = 'claude-code-user';
@@ -65,24 +68,20 @@ const KEYCHAIN_FALLBACK_ACCOUNT = 'claude-code-user';
  * inherit it, or the login would land in an item nobody else reads.
  */
 exports.CLAUDE_SECURESTORAGE_CONFIG_DIR_ENV = 'CLAUDE_SECURESTORAGE_CONFIG_DIR';
-function getDefaultClaudeHome() {
-    return path.join(os.homedir(), '.claude');
-}
-/** True when this process runs against the default `~/.claude` home. */
-function isDefaultClaudeHome() {
-    return !process.env.CLAUDE_CONFIG_DIR?.trim();
+function getClaudeProfilesDir() {
+    return path.join((0, accountRegistry_1.getAccountsDir)(), 'claude', 'profiles');
 }
 /**
- * The home the `claude` CLI reads and writes for this process: `CLAUDE_CONFIG_DIR`
- * when set, else `~/.claude`. Every "live" credential or identity read goes
- * through this so sidekick follows the same home the CLI does.
+ * True when the live home is one of sidekick's own profile homes: a shell
+ * that eval'd `sidekick accounts env` or runs inside `sidekick accounts shell`.
+ * That profile's store then reads as the live store, so sync, re-login, and
+ * switching must not treat it as live: they would delete the shell's only
+ * usable copy and re-point the active account at it.
  */
-function getLiveClaudeHome() {
-    const explicit = process.env.CLAUDE_CONFIG_DIR?.trim();
-    return explicit ? explicit : getDefaultClaudeHome();
-}
-function getClaudeProfilesDir() {
-    return path.join((0, accountRegistry_1.getAccountsDir)(), 'claude', 'profiles');
+function isLiveClaudeHomeSidekickProfile() {
+    const liveHome = path.resolve((0, claudePaths_1.getLiveClaudeHome)());
+    const profilesDir = path.resolve(getClaudeProfilesDir());
+    return liveHome === profilesDir || liveHome.startsWith(profilesDir + path.sep);
 }
 function getClaudeProfileDir(uuid) {
     return path.join(getClaudeProfilesDir(), uuid);
@@ -90,6 +89,14 @@ function getClaudeProfileDir(uuid) {
 function getClaudeProfileHome(uuid) {
     return path.join(getClaudeProfileDir(uuid), 'home');
 }
+/**
+ * Sidekick's private backup of a profile's credential. Claude Code never reads
+ * it, so it is not a CLI-usable copy: this is where the live account's
+ * credential is mirrored while its profile home stays empty.
+ */
+function getClaudeCredentialBackupPath(uuid) {
+    return path.join((0, accountRegistry_1.getAccountsDir)(), 'credentials', `${uuid}.credentials.json`);
+}
 function ensureClaudeProfileDirs(uuid) {
     fs.mkdirSync(getClaudeProfileHome(uuid), { recursive: true, mode: 0o700 });
 }
@@ -107,7 +114,7 @@ function claudeKeychainSuffix(configDir) {
  * `~/.claude` — so the no-argument form follows the process environment.
  */
 function claudeKeychainService(configDir) {
-    const dir = configDir ?? (isDefaultClaudeHome() ? undefined : getLiveClaudeHome());
+    const dir = configDir ?? ((0, claudePaths_1.isDefaultClaudeHome)() ? undefined : (0, claudePaths_1.getLiveClaudeHome)());
     return dir
         ? `${DEFAULT_CLAUDE_KEYCHAIN_SERVICE}-${claudeKeychainSuffix(dir)}`
         : DEFAULT_CLAUDE_KEYCHAIN_SERVICE;
@@ -145,11 +152,11 @@ function readOauthAccount(configPath) {
  * when it carries an identity, otherwise fall back to the legacy location for
  * the default home only.
  */
-function getClaudeConfigPath(home = getLiveClaudeHome()) {
+function getClaudeConfigPath(home = (0, claudePaths_1.getLiveClaudeHome)()) {
     const primary = path.join(home, '.claude.json');
     if (readOauthAccount(primary))
         return primary;
-    if (path.resolve(home) === path.resolve(getDefaultClaudeHome())) {
+    if (path.resolve(home) === path.resolve((0, claudePaths_1.getDefaultClaudeHome)())) {
         return path.join(os.homedir(), '.claude.json');
     }
     return primary;
@@ -160,7 +167,7 @@ function identityFromOauthAccount(oauthAccount) {
     return typeof email === 'string' && typeof uuid === 'string' ? { email, uuid } : null;
 }
 /** Identity of the account currently logged in to a Claude home (default: the live home). */
-function readLiveClaudeIdentity(home = getLiveClaudeHome()) {
+function readLiveClaudeIdentity(home = (0, claudePaths_1.getLiveClaudeHome)()) {
     return identityFromOauthAccount(readOauthAccount(getClaudeConfigPath(home)));
 }
 function readClaudeProfileIdentity(home) {

package/dist/claudeRefreshLock.d.ts

@@ -0,0 +1,15 @@
+/** Claude Code treats a lock older than this as abandoned (proper-lockfile `stale`). */
+export declare const CLAUDE_REFRESH_LOCK_STALE_MS = 60000;
+/** Claude Code is refreshing a login in one of the homes; retry shortly. */
+export declare class ClaudeRefreshLockBusyError extends Error {
+    constructor(lockPath: string);
+}
+export declare function claudeRefreshLockPaths(home: string): string[];
+/**
+ * Run `operation` holding the refresh locks of every existing home (a home
+ * that does not exist has no CLI using it). Throws
+ * {@link ClaudeRefreshLockBusyError} when a lock stays held past `waitMs`.
+ */
+export declare function withClaudeRefreshLocksSync<T>(homes: string[], operation: () => T, options?: {
+    waitMs?: number;
+}): T;

package/dist/claudeRefreshLock.js

@@ -0,0 +1,145 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ClaudeRefreshLockBusyError = exports.CLAUDE_REFRESH_LOCK_STALE_MS = void 0;
+exports.claudeRefreshLockPaths = claudeRefreshLockPaths;
+exports.withClaudeRefreshLocksSync = withClaudeRefreshLocksSync;
+/**
+ * Borrow Claude Code's own token-refresh lock while Sidekick reads and
+ * replaces a home's credential.
+ *
+ * Claude Code 2.1.x serialises refreshes per config directory with a
+ * proper-lockfile directory lock at `<configDir>/.oauth_refresh.lock` (stale
+ * after 60 s) plus a legacy `<realpath(configDir)>.lock`. Under that lock it
+ * re-reads the store before refreshing and adopts a token someone else wrote,
+ * so holding both locks keeps a refresh (which rotates the refresh token) out
+ * of the window between Sidekick's read and its write.
+ *
+ * Best effort by construction: this layers on Claude Code internals. If they
+ * change we lose only the exclusion; the callers' fingerprint re-checks still
+ * catch a store that moved. Held briefly (a few `security` calls), well under
+ * the 60 s stale window, and released on every exit.
+ */
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/** Claude Code treats a lock older than this as abandoned (proper-lockfile `stale`). */
+exports.CLAUDE_REFRESH_LOCK_STALE_MS = 60_000;
+const DEFAULT_WAIT_MS = 5_000;
+const POLL_MS = 50;
+const sleepView = new Int32Array(new SharedArrayBuffer(4));
+/** Claude Code is refreshing a login in one of the homes; retry shortly. */
+class ClaudeRefreshLockBusyError extends Error {
+    constructor(lockPath) {
+        super(`Claude Code is refreshing a login (${lockPath} is held); try again in a few seconds.`);
+        this.name = 'ClaudeRefreshLockBusyError';
+    }
+}
+exports.ClaudeRefreshLockBusyError = ClaudeRefreshLockBusyError;
+function claudeRefreshLockPaths(home) {
+    let real = path.resolve(home);
+    try {
+        real = fs.realpathSync(home);
+    }
+    catch {
+        /* keep the resolved path */
+    }
+    return [path.join(home, '.oauth_refresh.lock'), `${real}.lock`];
+}
+function tryAcquire(lockPath, now) {
+    try {
+        fs.mkdirSync(lockPath);
+        return true;
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+    }
+    try {
+        const stat = fs.statSync(lockPath);
+        if (now - stat.mtimeMs > exports.CLAUDE_REFRESH_LOCK_STALE_MS) {
+            // proper-lockfile's own recovery: an abandoned lock is removed and retaken.
+            fs.rmSync(lockPath, { recursive: true, force: true });
+            fs.mkdirSync(lockPath);
+            return true;
+        }
+    }
+    catch {
+        /* released or retaken between checks; poll again */
+    }
+    return false;
+}
+/**
+ * Run `operation` holding the refresh locks of every existing home (a home
+ * that does not exist has no CLI using it). Throws
+ * {@link ClaudeRefreshLockBusyError} when a lock stays held past `waitMs`.
+ */
+function withClaudeRefreshLocksSync(homes, operation, options = {}) {
+    const waitMs = options.waitMs ?? DEFAULT_WAIT_MS;
+    const lockPaths = [
+        ...new Set(homes
+            .filter((home) => {
+            try {
+                return fs.statSync(home).isDirectory();
+            }
+            catch {
+                return false;
+            }
+        })
+            .flatMap(claudeRefreshLockPaths)),
+    ];
+    const held = [];
+    try {
+        const deadline = Date.now() + waitMs;
+        for (const lockPath of lockPaths) {
+            while (!tryAcquire(lockPath, Date.now())) {
+                if (Date.now() >= deadline)
+                    throw new ClaudeRefreshLockBusyError(lockPath);
+                Atomics.wait(sleepView, 0, 0, POLL_MS);
+            }
+            held.push(lockPath);
+        }
+        return operation();
+    }
+    finally {
+        for (const lockPath of held.reverse()) {
+            try {
+                fs.rmSync(lockPath, { recursive: true, force: true });
+            }
+            catch {
+                /* Claude Code recovers a stale lock after 60 s */
+            }
+        }
+    }
+}

package/dist/codexAuth.d.ts

@@ -30,3 +30,7 @@ export declare function identitiesMatch(a: {
     email?: string;
     workspaceId?: string;
 } | null | undefined): boolean;
+/** Non-secret chain-link identifier; raw token values never belong in diagnostics. */
+export declare function codexRefreshFingerprint(raw: string | null): string | null;
+/** Compare evidence, never filesystem timestamps. Incomparable credentials tie. */
+export declare function compareCodexAuthFreshness(a: string | null, b: string | null): number;

package/dist/codexAuth.js

@@ -40,11 +40,14 @@ exports.readAuthIdentityFromRaw = readAuthIdentityFromRaw;
 exports.readLastRefresh = readLastRefresh;
 exports.readAccessTokenExpiry = readAccessTokenExpiry;
 exports.identitiesMatch = identitiesMatch;
+exports.codexRefreshFingerprint = codexRefreshFingerprint;
+exports.compareCodexAuthFreshness = compareCodexAuthFreshness;
 /**
  * Pure helpers over the Codex CLI `auth.json` payload. No filesystem access
  * beyond an optional mtime fallback, no child processes.
  */
 const fs = __importStar(require("fs"));
+const crypto_1 = require("crypto");
 // Codex refreshes OAuth tokens at most every 8 days; a stored refresh token
 // older than that may already be rejected by the auth server.
 exports.STALE_AUTH_THRESHOLD_MS = 8 * 24 * 60 * 60 * 1000;
@@ -125,3 +128,18 @@ function identitiesMatch(a, b) {
         return a.workspaceId === b.workspaceId;
     return Boolean(a.email && b.email && a.email === b.email);
 }
+/** Non-secret chain-link identifier; raw token values never belong in diagnostics. */
+function codexRefreshFingerprint(raw) {
+    const token = parseAuthJson(raw)?.tokens?.refresh_token;
+    return typeof token === 'string' && token
+        ? (0, crypto_1.createHash)('sha256').update(token).digest('hex').slice(0, 16)
+        : null;
+}
+/** Compare evidence, never filesystem timestamps. Incomparable credentials tie. */
+function compareCodexAuthFreshness(a, b) {
+    const ar = readLastRefresh(a), br = readLastRefresh(b);
+    if (ar !== null && br !== null && ar !== br)
+        return ar > br ? 1 : -1;
+    const ae = readAccessTokenExpiry(a), be = readAccessTokenExpiry(b);
+    return ae !== null && be !== null && ae !== be ? (ae > be ? 1 : -1) : 0;
+}

package/dist/codexCredentialDoctor.d.ts

@@ -0,0 +1,33 @@
+import type { ProviderSyncReport } from './accountSyncTypes';
+export interface CodexCredentialFinding {
+    kind: 'live-duplicate' | 'stale-stash' | 'orphan' | 'corrupt' | 'unreadable' | 'pending-switch';
+    configDir: string;
+    /** Present for old timestamped stash files. */
+    file?: string;
+    ownership: 'profile-home' | 'login-home' | 'stash' | 'live' | 'journal' | 'backup';
+    accountId?: string;
+    email?: string;
+    fingerprint?: string;
+    detail: string;
+    action: string;
+}
+export interface CodexCredentialInspection {
+    findings: CodexCredentialFinding[];
+    homesChecked: number;
+}
+export interface CodexCredentialRepairResult extends CodexCredentialInspection {
+    dryRun: boolean;
+    repaired: Array<{
+        finding: CodexCredentialFinding;
+        ok: boolean;
+        error?: string;
+    }>;
+    sync?: ProviderSyncReport;
+}
+export declare function inspectCodexCredentialStores(options?: {
+    now?: number;
+}): CodexCredentialInspection;
+export declare function repairCodexCredentialStores(options?: {
+    now?: number;
+    dryRun?: boolean;
+}): CodexCredentialRepairResult;