sidekick-shared 0.27.5 → 0.27.6

package/dist/claudeCredentialDoctor.d.ts

@@ -0,0 +1,50 @@
+import type { ProviderSyncReport } from './accountSyncTypes';
+export type ClaudeCredentialFindingKind = 'orphan' | 'live-duplicate' | 'corrupt' | 'stale-entry';
+export interface ClaudeCredentialFinding {
+    kind: ClaudeCredentialFindingKind;
+    configDir: string;
+    service: string;
+    /** How Sidekick knows it owns this store. */
+    ownership: 'ledger' | 'profile-home' | 'keychain-tag';
+    accountId?: string;
+    email?: string;
+    detail: string;
+    /** What repair does about it. */
+    action: string;
+}
+/** Attributes of one Keychain item (never its secret). */
+export interface KeychainItemSummary {
+    service: string;
+    comment?: string;
+}
+export interface InspectClaudeCredentialStoresOptions {
+    now?: number;
+    /**
+     * Enumerate `Claude Code-credentials-*` Keychain items, attributes only.
+     * Default on macOS: `security dump-keychain` (no `-d`, so no secret is read
+     * and nothing prompts). Elsewhere there is no Keychain to scan.
+     */
+    listKeychainItems?: () => KeychainItemSummary[];
+}
+export interface ClaudeCredentialInspection {
+    findings: ClaudeCredentialFinding[];
+    homesChecked: number;
+    keychainScanned: boolean;
+}
+export interface ClaudeCredentialRepairOutcome {
+    finding: ClaudeCredentialFinding;
+    ok: boolean;
+    error?: string;
+}
+export interface ClaudeCredentialRepairResult extends ClaudeCredentialInspection {
+    dryRun: boolean;
+    repaired: ClaudeCredentialRepairOutcome[];
+    sync?: ProviderSyncReport;
+}
+/** Parse `security dump-keychain` output (attributes only) into item summaries. */
+export declare function parseKeychainDump(output: string): KeychainItemSummary[];
+export declare function inspectClaudeCredentialStores(options?: InspectClaudeCredentialStoresOptions): ClaudeCredentialInspection;
+/** Inspect, then (unless `dryRun`) repair every finding. Dry run by default. */
+export declare function repairClaudeCredentialStores(options?: InspectClaudeCredentialStoresOptions & {
+    dryRun?: boolean;
+}): ClaudeCredentialRepairResult;

package/dist/claudeCredentialDoctor.js

@@ -0,0 +1,277 @@
+"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.parseKeychainDump = parseKeychainDump;
+exports.inspectClaudeCredentialStores = inspectClaudeCredentialStores;
+exports.repairClaudeCredentialStores = repairClaudeCredentialStores;
+/**
+ * Inspect and repair the Claude credential stores Sidekick owns.
+ *
+ * Ownership is proven, never guessed: a store counts only when its directory
+ * is in the ledger (claudeCredentialLedger.ts), is a profile home under
+ * Sidekick's accounts directory, or its Keychain item carries Sidekick's
+ * comment tag naming the directory. Other tools legitimately create
+ * `Claude Code-credentials-<hash>` items for their own `CLAUDE_CONFIG_DIR`, so
+ * nothing is ever matched by name pattern.
+ *
+ * Findings:
+ * - `orphan`: the store's directory is gone, or it belongs to no saved account
+ *   and no login younger than a day. It holds a copy of some login nothing
+ *   will use; repair deletes it.
+ * - `live-duplicate`: the live account's profile home holds a CLI-usable copy
+ *   of its login (a second copy of the live chain); repair runs the sync that
+ *   removes it (repairing live first when the copy is newer).
+ * - `corrupt`: the store does not parse (for example a credential truncated by
+ *   an older build's Keychain write); repair deletes it, and the account needs
+ *   a new sign-in unless its backup is still good.
+ * - `stale-entry`: a ledger entry whose store is already gone; repair forgets it.
+ */
+const child_process_1 = require("child_process");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const accountRegistry_1 = require("./accountRegistry");
+const claudeProfiles_1 = require("./claudeProfiles");
+const claudeCredentialLedger_1 = require("./claudeCredentialLedger");
+const credentialIO_1 = require("./credentialIO");
+const accounts_1 = require("./accounts");
+/** Logins younger than this may still be finalized; the doctor leaves them alone. */
+const PENDING_LOGIN_GRACE_MS = 24 * 60 * 60 * 1000;
+function decodeKeychainValue(raw) {
+    const quoted = raw.match(/^"(.*)"$/);
+    if (quoted)
+        return quoted[1];
+    const hex = raw.match(/^0x([0-9A-Fa-f]+)/);
+    if (hex)
+        return Buffer.from(hex[1], 'hex').toString('utf8').replace(/\0+$/, '');
+    return raw;
+}
+/** Parse `security dump-keychain` output (attributes only) into item summaries. */
+function parseKeychainDump(output) {
+    const items = [];
+    for (const block of output.split(/^keychain: /m)) {
+        const service = block.match(/^\s*"svce"<blob>=(.+)$/m)?.[1];
+        if (!service)
+            continue;
+        const comment = block.match(/^\s*"icmt"<blob>=(.+)$/m)?.[1];
+        const decodedService = decodeKeychainValue(service.trim());
+        const decodedComment = comment && comment.trim() !== '<NULL>' ? decodeKeychainValue(comment.trim()) : undefined;
+        items.push({ service: decodedService, comment: decodedComment });
+    }
+    return items;
+}
+function defaultListKeychainItems() {
+    if (process.platform !== 'darwin')
+        return [];
+    const output = (0, child_process_1.execFileSync)('security', ['dump-keychain'], {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+        timeout: 30_000,
+        killSignal: 'SIGKILL',
+        maxBuffer: 64 * 1024 * 1024,
+    });
+    return parseKeychainDump(String(output)).filter((item) => item.service.startsWith('Claude Code-credentials-'));
+}
+function collectOwnedHomes(keychainItems) {
+    const homes = new Map();
+    const add = (configDir, ownership, inLedger = false) => {
+        const resolved = path.resolve(configDir);
+        const existing = homes.get(resolved);
+        if (existing) {
+            existing.inLedger ||= inLedger;
+            return;
+        }
+        homes.set(resolved, {
+            configDir: resolved,
+            service: (0, claudeProfiles_1.claudeKeychainService)(resolved),
+            ownership,
+            inLedger,
+        });
+    };
+    for (const entry of (0, claudeCredentialLedger_1.readClaudeCredentialLedger)())
+        add(entry.configDir, 'ledger', true);
+    try {
+        for (const id of fs.readdirSync((0, claudeProfiles_1.getClaudeProfilesDir)())) {
+            add((0, claudeProfiles_1.getClaudeProfileHome)(id), 'profile-home');
+        }
+    }
+    catch {
+        /* no profiles yet */
+    }
+    for (const item of keychainItems) {
+        if (!item.comment?.startsWith(credentialIO_1.SIDEKICK_KEYCHAIN_COMMENT_PREFIX))
+            continue;
+        const configDir = item.comment.slice(credentialIO_1.SIDEKICK_KEYCHAIN_COMMENT_PREFIX.length);
+        // The tag must name the directory the service was derived from.
+        if (configDir && (0, claudeProfiles_1.claudeKeychainService)(configDir) === item.service) {
+            add(configDir, 'keychain-tag');
+        }
+    }
+    return [...homes.values()];
+}
+function isRecentPendingLogin(configDir, now) {
+    const profilesDir = path.resolve((0, claudeProfiles_1.getClaudeProfilesDir)());
+    const loginDir = path.dirname(configDir);
+    if (path.dirname(loginDir) !== profilesDir)
+        return false;
+    try {
+        const pending = JSON.parse(fs.readFileSync(path.join((0, claudeProfiles_1.getClaudeProfileDir)(path.basename(loginDir)), 'profile.json'), 'utf8'));
+        const addedAt = pending.addedAt ? Date.parse(pending.addedAt) : NaN;
+        return !Number.isNaN(addedAt) && now - addedAt < PENDING_LOGIN_GRACE_MS;
+    }
+    catch {
+        return false;
+    }
+}
+function inspectClaudeCredentialStores(options = {}) {
+    const now = options.now ?? Date.now();
+    let keychainItems = [];
+    let keychainScanned = false;
+    try {
+        keychainItems = (options.listKeychainItems ?? defaultListKeychainItems)();
+        keychainScanned = Boolean(options.listKeychainItems) || process.platform === 'darwin';
+    }
+    catch {
+        keychainScanned = false;
+    }
+    const profilesByHome = new Map();
+    for (const profile of (0, accountRegistry_1.listSavedAccountProfiles)('claude-code')) {
+        profilesByHome.set(path.resolve((0, claudeProfiles_1.getClaudeProfileHome)(profile.providerAccountId ?? profile.id)), profile);
+    }
+    // Inside a profile-home shell the "live" identity is that profile's own; its
+    // store is not a duplicate of anything.
+    const liveUuid = (0, claudeProfiles_1.isLiveClaudeHomeSidekickProfile)()
+        ? null
+        : ((0, claudeProfiles_1.readLiveClaudeIdentity)()?.uuid ?? null);
+    const findings = [];
+    const homes = collectOwnedHomes(keychainItems);
+    for (const home of homes) {
+        const store = (0, credentialIO_1.readClaudeCredentialStore)(home.configDir);
+        if (store.status === 'error')
+            continue;
+        const profile = profilesByHome.get(home.configDir);
+        const base = {
+            configDir: home.configDir,
+            service: home.service,
+            ownership: home.ownership,
+            accountId: profile?.id,
+            email: profile?.email ?? profile?.metadata?.email,
+        };
+        if (store.status === 'absent') {
+            if (home.inLedger && !profile && !isRecentPendingLogin(home.configDir, now)) {
+                findings.push({
+                    ...base,
+                    kind: 'stale-entry',
+                    detail: 'Ledger entry for a store that no longer exists.',
+                    action: 'Forget the entry.',
+                });
+            }
+            continue;
+        }
+        if (!profile) {
+            if (isRecentPendingLogin(home.configDir, now))
+                continue;
+            findings.push({
+                ...base,
+                kind: 'orphan',
+                detail: fs.existsSync(home.configDir)
+                    ? 'Holds a login but belongs to no saved account.'
+                    : 'Holds a login but its directory no longer exists.',
+                action: 'Delete the stored credential.',
+            });
+            continue;
+        }
+        if (liveUuid && (profile.providerAccountId ?? profile.id) === liveUuid) {
+            findings.push({
+                ...base,
+                kind: 'live-duplicate',
+                detail: "The live account's profile home holds a second usable copy of its login; whichever refreshes first invalidates the other.",
+                action: 'Remove the copy (installing it into live first if it is newer).',
+            });
+            continue;
+        }
+        if (store.status === 'corrupt') {
+            findings.push({
+                ...base,
+                kind: 'corrupt',
+                detail: 'The stored credential is not valid JSON (possibly truncated); it cannot be used.',
+                action: 'Delete the unusable store; sign in to this account again if its backup is expired.',
+            });
+        }
+    }
+    return { findings, homesChecked: homes.length, keychainScanned };
+}
+/** Inspect, then (unless `dryRun`) repair every finding. Dry run by default. */
+function repairClaudeCredentialStores(options = {}) {
+    const dryRun = options.dryRun ?? true;
+    const inspection = inspectClaudeCredentialStores(options);
+    const result = { ...inspection, dryRun, repaired: [] };
+    if (dryRun)
+        return result;
+    if (inspection.findings.some((finding) => finding.kind === 'live-duplicate')) {
+        result.sync = (0, accounts_1.syncClaudeLiveState)();
+    }
+    for (const finding of inspection.findings) {
+        try {
+            if (finding.kind === 'live-duplicate') {
+                const still = (0, credentialIO_1.readClaudeCredentialStore)(finding.configDir).status;
+                result.repaired.push({
+                    finding,
+                    ok: still === 'absent',
+                    error: still === 'absent' ? undefined : result.sync?.warnings.join(' ') || 'still present',
+                });
+                continue;
+            }
+            if (finding.kind === 'stale-entry') {
+                (0, claudeCredentialLedger_1.forgetClaudeCredentialHome)(finding.configDir);
+                result.repaired.push({ finding, ok: true });
+                continue;
+            }
+            const ok = (0, credentialIO_1.deleteStoredCredentials)(finding.configDir);
+            if (ok && finding.kind === 'orphan') {
+                // An abandoned login directory under our profiles dir goes with it.
+                const loginDir = path.dirname(finding.configDir);
+                if (path.dirname(loginDir) === path.resolve((0, claudeProfiles_1.getClaudeProfilesDir)()) &&
+                    fs.existsSync(loginDir)) {
+                    fs.rmSync(loginDir, { recursive: true, force: true });
+                }
+            }
+            result.repaired.push({ finding, ok, error: ok ? undefined : 'could not delete' });
+        }
+        catch (err) {
+            result.repaired.push({ finding, ok: false, error: String(err) });
+        }
+    }
+    return result;
+}

package/dist/claudeCredentialLedger.d.ts

@@ -0,0 +1,15 @@
+export type ClaudeCredentialHomePurpose = 'profile' | 'login';
+export interface ClaudeCredentialLedgerEntry {
+    configDir: string;
+    /** The Keychain service Claude Code derives for this directory (used on macOS). */
+    service: string;
+    purpose: ClaudeCredentialHomePurpose;
+    createdAt: string;
+    lastWrittenAt: string;
+}
+export declare function getClaudeCredentialLedgerPath(): string;
+export declare function readClaudeCredentialLedger(): ClaudeCredentialLedgerEntry[];
+/** Record (or refresh) a home Sidekick is about to hold a Claude credential in. */
+export declare function recordClaudeCredentialHome(configDir: string, purpose: ClaudeCredentialHomePurpose, now?: Date): void;
+/** Drop a home whose credential store has been deleted. */
+export declare function forgetClaudeCredentialHome(configDir: string): void;

package/dist/claudeCredentialLedger.js

@@ -0,0 +1,130 @@
+"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.getClaudeCredentialLedgerPath = getClaudeCredentialLedgerPath;
+exports.readClaudeCredentialLedger = readClaudeCredentialLedger;
+exports.recordClaudeCredentialHome = recordClaudeCredentialHome;
+exports.forgetClaudeCredentialHome = forgetClaudeCredentialHome;
+/**
+ * Ledger of the Claude credential homes Sidekick created.
+ *
+ * Claude Code names a config directory's Keychain item after a hash of the
+ * directory, so once the directory is gone nothing ties the item back to it.
+ * Every home Sidekick writes a credential into (a saved profile) or points a
+ * `claude` login at is recorded here first, which is how `accounts doctor`
+ * proves an item is Sidekick's before it deletes anything. Items are never
+ * matched by name pattern: other tools legitimately use `CLAUDE_CONFIG_DIR`.
+ *
+ * Best effort by design: a ledger write failure must never fail the credential
+ * operation it describes. The lock is a leaf lock (callers may hold the swap
+ * or registry lock; nothing is acquired inside it).
+ */
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const accountRegistry_1 = require("./accountRegistry");
+const claudeProfiles_1 = require("./claudeProfiles");
+const atomic_1 = require("./writers/atomic");
+function emptyLedger() {
+    return { version: 1, entries: [] };
+}
+function normalizeLedger(raw) {
+    const entries = raw?.entries;
+    if (!Array.isArray(entries))
+        return emptyLedger();
+    return {
+        version: 1,
+        entries: entries.filter((entry) => !!entry &&
+            typeof entry === 'object' &&
+            typeof entry.configDir === 'string' &&
+            typeof entry.service === 'string'),
+    };
+}
+function getClaudeCredentialLedgerPath() {
+    return path.join((0, accountRegistry_1.getAccountsDir)(), 'claude', 'credential-homes.json');
+}
+function readClaudeCredentialLedger() {
+    try {
+        return normalizeLedger(JSON.parse(fs.readFileSync(getClaudeCredentialLedgerPath(), 'utf8')))
+            .entries;
+    }
+    catch {
+        return [];
+    }
+}
+/** Record (or refresh) a home Sidekick is about to hold a Claude credential in. */
+function recordClaudeCredentialHome(configDir, purpose, now = new Date()) {
+    const resolved = path.resolve(configDir);
+    const stamp = now.toISOString();
+    try {
+        (0, atomic_1.updateJsonStoreAtomicSync)(getClaudeCredentialLedgerPath(), emptyLedger, (latest) => {
+            const ledger = normalizeLedger(latest);
+            const existing = ledger.entries.find((entry) => entry.configDir === resolved);
+            if (existing) {
+                existing.lastWrittenAt = stamp;
+                // A login home that became a profile keeps the stronger purpose.
+                if (purpose === 'profile')
+                    existing.purpose = 'profile';
+                return ledger;
+            }
+            ledger.entries.push({
+                configDir: resolved,
+                service: (0, claudeProfiles_1.claudeKeychainService)(resolved),
+                purpose,
+                createdAt: stamp,
+                lastWrittenAt: stamp,
+            });
+            return ledger;
+        });
+    }
+    catch {
+        /* best effort: the doctor still scans the profile homes on disk */
+    }
+}
+/** Drop a home whose credential store has been deleted. */
+function forgetClaudeCredentialHome(configDir) {
+    const resolved = path.resolve(configDir);
+    try {
+        if (!fs.existsSync(getClaudeCredentialLedgerPath()))
+            return;
+        (0, atomic_1.updateJsonStoreAtomicSync)(getClaudeCredentialLedgerPath(), emptyLedger, (latest) => {
+            const ledger = normalizeLedger(latest);
+            ledger.entries = ledger.entries.filter((entry) => entry.configDir !== resolved);
+            return ledger;
+        });
+    }
+    catch {
+        /* best effort */
+    }
+}

package/dist/claudeCredentials.d.ts

@@ -1,6 +1,3 @@
-/**
- * Pure helpers over the Claude Code credential blob (`claudeAiOauth`). No I/O.
- */
 export interface ClaudeOauthCredentials {
     accessToken: string;
     refreshToken?: string;
@@ -36,3 +33,23 @@ export declare function resolveClaudeRefreshExpiry(credentials: ClaudeOauthCrede
     refreshExpiresAt: number;
     estimated: boolean;
 } | null;
+/**
+ * Short, non-reversible fingerprint of the refresh token. Claude Code rotates
+ * the refresh token on every refresh, so equal fingerprints mean two stores
+ * hold the same link of one chain. Safe to persist and log; tokens never are.
+ */
+export declare function claudeRefreshFingerprint(credentials: ClaudeOauthCredentials | null): string | null;
+/**
+ * The part of a blob a profile home keeps: the Claude login only. MCP OAuth
+ * tokens (`mcpOAuth`) rotate too and follow the live store, so a profile copy
+ * never duplicates one of their chains (and stays far below the Keychain
+ * line limit).
+ */
+export declare function claudeLoginOnly(blob: unknown): Record<string, unknown> | null;
+/**
+ * The blob to install into the live store when `candidate`'s login replaces
+ * the live one: everything live holds (its MCP tokens are the freshest links
+ * of their chains) with the candidate's `claudeAiOauth`, plus any MCP server
+ * only the candidate knows. Mirrors what Claude Code's own `/login` keeps.
+ */
+export declare function mergeClaudeLoginIntoLive(live: unknown, candidate: unknown): Record<string, unknown>;

package/dist/claudeCredentials.js

@@ -1,13 +1,17 @@
 "use strict";
-/**
- * Pure helpers over the Claude Code credential blob (`claudeAiOauth`). No I/O.
- */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CLAUDE_REFRESH_TOKEN_LIFETIME_ESTIMATE_MS = exports.CLAUDE_ACCESS_TOKEN_LIFETIME_MS = void 0;
 exports.parseClaudeCredentialBlob = parseClaudeCredentialBlob;
 exports.claudeCredentialFreshness = claudeCredentialFreshness;
 exports.isNewerClaudeCredential = isNewerClaudeCredential;
 exports.resolveClaudeRefreshExpiry = resolveClaudeRefreshExpiry;
+exports.claudeRefreshFingerprint = claudeRefreshFingerprint;
+exports.claudeLoginOnly = claudeLoginOnly;
+exports.mergeClaudeLoginIntoLive = mergeClaudeLoginIntoLive;
+/**
+ * Pure helpers over the Claude Code credential blob (`claudeAiOauth`). No I/O.
+ */
+const crypto_1 = require("crypto");
 /** Lifetime of a Claude Code access token. */
 exports.CLAUDE_ACCESS_TOKEN_LIFETIME_MS = 8 * 60 * 60 * 1000;
 /**
@@ -72,3 +76,46 @@ function resolveClaudeRefreshExpiry(credentials) {
     }
     return null;
 }
+/**
+ * Short, non-reversible fingerprint of the refresh token. Claude Code rotates
+ * the refresh token on every refresh, so equal fingerprints mean two stores
+ * hold the same link of one chain. Safe to persist and log; tokens never are.
+ */
+function claudeRefreshFingerprint(credentials) {
+    const token = credentials?.refreshToken;
+    return token ? (0, crypto_1.createHash)('sha256').update(token).digest('hex').slice(0, 16) : null;
+}
+function recordOrUndefined(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+/**
+ * The part of a blob a profile home keeps: the Claude login only. MCP OAuth
+ * tokens (`mcpOAuth`) rotate too and follow the live store, so a profile copy
+ * never duplicates one of their chains (and stays far below the Keychain
+ * line limit).
+ */
+function claudeLoginOnly(blob) {
+    const oauth = recordOrUndefined(recordOrUndefined(blob)?.claudeAiOauth);
+    return oauth ? { claudeAiOauth: oauth } : null;
+}
+/**
+ * The blob to install into the live store when `candidate`'s login replaces
+ * the live one: everything live holds (its MCP tokens are the freshest links
+ * of their chains) with the candidate's `claudeAiOauth`, plus any MCP server
+ * only the candidate knows. Mirrors what Claude Code's own `/login` keeps.
+ */
+function mergeClaudeLoginIntoLive(live, candidate) {
+    const liveRecord = recordOrUndefined(live) ?? {};
+    const candidateRecord = recordOrUndefined(candidate) ?? {};
+    const merged = {
+        ...liveRecord,
+        claudeAiOauth: candidateRecord.claudeAiOauth,
+    };
+    const liveMcp = recordOrUndefined(liveRecord.mcpOAuth);
+    const candidateMcp = recordOrUndefined(candidateRecord.mcpOAuth);
+    if (liveMcp || candidateMcp)
+        merged.mcpOAuth = { ...candidateMcp, ...liveMcp };
+    return merged;
+}

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/claudeProfiles.d.ts

@@ -18,8 +18,22 @@ export declare function isDefaultClaudeHome(): boolean;
  */
 export declare function getLiveClaudeHome(): string;
 export declare function getClaudeProfilesDir(): string;
+/**
+ * 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 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