sidekick-shared 0.27.6 → 0.28.0

package/dist/esm/analytics/qualityScore.js

@@ -0,0 +1,112 @@
+import { summarizeTokens } from '../tokenSummary';
+function awarded(maximum, ratio) {
+    return Math.round(maximum * Math.max(0, Math.min(1, ratio)) * 10) / 10;
+}
+export function scoreSessionQuality(metrics) {
+    const latencyMs = metrics.latencyStats?.avgFirstTokenLatencyMs ?? 0;
+    const latencyRatio = latencyMs > 0 ? 1 - Math.min(1, latencyMs / 15_000) : 1;
+    const completedCalls = metrics.toolStats.reduce((sum, tool) => sum + tool.completedCount, 0);
+    const errorRate = completedCalls > 0 ? metrics.errorRollup.totalFailures / completedCalls : 0;
+    const contextTokens = Math.max(1, summarizeTokens(metrics.tokens).context);
+    const evicted = metrics.compactionEvents.reduce((sum, event) => sum + event.tokensReclaimed, 0);
+    const contextRatio = 1 - Math.min(1, evicted / contextTokens);
+    const start = metrics.sessionStartTime ? Date.parse(metrics.sessionStartTime) : NaN;
+    const end = metrics.lastEventTime ? Date.parse(metrics.lastEventTime) : NaN;
+    let bypassMs = 0;
+    for (let index = 0; index < metrics.permissionModeHistory.length; index++) {
+        const change = metrics.permissionModeHistory[index];
+        if (change.mode !== 'bypassPermissions')
+            continue;
+        const from = Date.parse(change.timestamp);
+        const to = Date.parse(metrics.permissionModeHistory[index + 1]?.timestamp ?? metrics.lastEventTime ?? '');
+        if (Number.isFinite(from) && Number.isFinite(to))
+            bypassMs += Math.max(0, to - from);
+    }
+    const sessionMs = Number.isFinite(start) && Number.isFinite(end) ? Math.max(1, end - start) : 1;
+    const bypassRatio = Math.min(1, bypassMs / sessionMs);
+    const tasks = Array.from(metrics.taskState.tasks.values()).filter((task) => task.status !== 'deleted');
+    const completedTasks = tasks.filter((task) => task.status === 'completed').length;
+    const goalGates = tasks.filter((task) => task.isGoalGate);
+    const completedGates = goalGates.filter((task) => task.status === 'completed').length;
+    const taskRatio = tasks.length > 0 ? completedTasks / tasks.length : 1;
+    const goalRatio = goalGates.length > 0 ? completedGates / goalGates.length : taskRatio;
+    const outcomeRatio = taskRatio * 0.6 + goalRatio * 0.4;
+    const factors = [
+        {
+            id: 'latency',
+            label: 'Response latency',
+            contribution: awarded(15, latencyRatio),
+            maximum: 15,
+            detail: latencyMs > 0 ? `${Math.round(latencyMs)}ms average first token` : 'No latency penalty',
+        },
+        {
+            id: 'reliability',
+            label: 'Tool reliability',
+            contribution: awarded(30, 1 - Math.min(1, errorRate * 2)),
+            maximum: 30,
+            detail: `${metrics.errorRollup.totalFailures}/${completedCalls} completed tool calls failed`,
+        },
+        {
+            id: 'context',
+            label: 'Context stability',
+            contribution: awarded(15, contextRatio),
+            maximum: 15,
+            detail: `${metrics.compactionCount} compactions, ${evicted} tokens evicted`,
+        },
+        {
+            id: 'permission_safety',
+            label: 'Permission safety',
+            contribution: awarded(10, 1 - bypassRatio),
+            maximum: 10,
+            detail: `${Math.round(bypassRatio * 100)}% of observed time bypassing permissions`,
+        },
+        {
+            id: 'outcomes',
+            label: 'Task outcomes',
+            contribution: awarded(30, outcomeRatio),
+            maximum: 30,
+            detail: `${completedTasks}/${tasks.length} tasks and ${completedGates}/${goalGates.length} goal gates completed`,
+        },
+    ];
+    return {
+        score: Math.round(factors.reduce((sum, factor) => sum + factor.contribution, 0)),
+        beta: true,
+        factors,
+    };
+}
+export function calculateQualityTrend(records, now = new Date()) {
+    const end = now.getTime();
+    const week = 7 * 24 * 60 * 60 * 1000;
+    const eligible = records.filter((record) => record.qualityScore > 0 && Number.isFinite(Date.parse(record.endTime)));
+    const current = eligible.filter((record) => {
+        const at = Date.parse(record.endTime);
+        return at >= end - week && at <= end;
+    });
+    const previous = eligible.filter((record) => {
+        const at = Date.parse(record.endTime);
+        return at >= end - 2 * week && at < end - week;
+    });
+    const average = (items) => items.length > 0
+        ? Math.round((items.reduce((sum, item) => sum + item.qualityScore, 0) / items.length) * 10) /
+            10
+        : null;
+    const currentWeekAverage = average(current);
+    const previousWeekAverage = average(previous);
+    const delta = currentWeekAverage != null && previousWeekAverage != null
+        ? Math.round((currentWeekAverage - previousWeekAverage) * 10) / 10
+        : null;
+    return {
+        currentWeekAverage,
+        previousWeekAverage,
+        delta,
+        direction: delta == null
+            ? 'insufficient'
+            : delta > 0.5
+                ? 'improving'
+                : delta < -0.5
+                    ? 'declining'
+                    : 'flat',
+        currentWeekSessions: current.length,
+        previousWeekSessions: previous.length,
+    };
+}

package/dist/esm/autoSwitch.js

@@ -0,0 +1,185 @@
+import { getActiveAccount, listAccounts, } from './accounts';
+import { switchAccountAsync as defaultSwitchAccount } from './accountManager';
+import { getActiveCodexAccount, listCodexAccounts } from './codexProfiles';
+import { readQuotaSnapshot } from './quotaSnapshots';
+export const DEFAULT_AUTO_SWITCH_CONFIG = {
+    enabled: false,
+    thresholdPct: 90,
+};
+const MATERIAL_REMAINING_IMPROVEMENT_PCT = 5;
+const MAX_STALE_SNAPSHOT_AGE_MS = 5 * 60 * 60 * 1000;
+function mergedConfig(config) {
+    return {
+        ...DEFAULT_AUTO_SWITCH_CONFIG,
+        ...config,
+    };
+}
+function quotaUtilization(quota) {
+    if (!quota?.available)
+        return 0;
+    return Math.max(quota.fiveHour.utilization, quota.sevenDay.utilization);
+}
+function quotaRemaining(quota) {
+    if (!quota?.available)
+        return 0;
+    return Math.max(0, 100 - quotaUtilization(quota));
+}
+function isUsableCandidateQuota(quota, nowMs) {
+    if (!quota?.available)
+        return false;
+    if (quota.stale !== true)
+        return true;
+    const capturedAt = Date.parse(quota.capturedAt ?? '');
+    if (!Number.isFinite(capturedAt) || capturedAt > nowMs)
+        return false;
+    return nowMs - capturedAt <= MAX_STALE_SNAPSHOT_AGE_MS;
+}
+export function decideAutoSwitch(_provider, active, candidates, config, nowMs = Date.now()) {
+    const cfg = mergedConfig(config);
+    if (!cfg.enabled)
+        return null;
+    if (!active.quota?.available)
+        return null;
+    const activeUtilization = quotaUtilization(active.quota);
+    if (activeUtilization < cfg.thresholdPct)
+        return null;
+    const activeRemaining = quotaRemaining(active.quota);
+    const best = candidates
+        .filter((candidate) => candidate.accountId !== active.accountId &&
+        candidate.switchable !== false &&
+        isUsableCandidateQuota(candidate.quota, nowMs))
+        .sort((a, b) => quotaRemaining(b.quota) - quotaRemaining(a.quota))[0];
+    if (!best)
+        return null;
+    if (quotaRemaining(best.quota) < activeRemaining + MATERIAL_REMAINING_IMPROVEMENT_PCT)
+        return null;
+    return { switchTo: best.accountId };
+}
+function runtimeStateToProvider(provider) {
+    return provider === 'claude' ? 'claude-code' : 'codex';
+}
+function accountIdFor(provider, account) {
+    return provider === 'claude-code'
+        ? account.uuid
+        : account.id;
+}
+export class AutoSwitchController {
+    quotaService;
+    getClaudeAccounts;
+    getActiveClaudeAccount;
+    getCodexAccounts;
+    getActiveCodexAccount;
+    readSnapshot;
+    switchAccount;
+    onTransition;
+    log;
+    cooldownMs;
+    now;
+    config;
+    subscription = null;
+    switchedDuringCrossing = new Set();
+    lastSwitchAt = {};
+    switchInFlight = new Set();
+    constructor(options) {
+        this.quotaService = options.quotaService;
+        this.config = mergedConfig(options.config);
+        this.getClaudeAccounts = options.getClaudeAccounts ?? listAccounts;
+        this.getActiveClaudeAccount = options.getActiveClaudeAccount ?? getActiveAccount;
+        this.getCodexAccounts = options.getCodexAccounts ?? listCodexAccounts;
+        this.getActiveCodexAccount = options.getActiveCodexAccount ?? getActiveCodexAccount;
+        this.readSnapshot = options.readSnapshot ?? readQuotaSnapshot;
+        this.switchAccount = options.switchAccount ?? defaultSwitchAccount;
+        this.onTransition = options.onTransition;
+        this.log = options.log;
+        this.cooldownMs = options.cooldownMs ?? 0;
+        this.now = options.now ?? Date.now;
+    }
+    start() {
+        if (this.subscription)
+            return;
+        this.subscription = this.quotaService.onUpdate((state) => this.handleUpdate(state));
+    }
+    stop() {
+        this.subscription?.dispose();
+        this.subscription = null;
+    }
+    dispose() {
+        this.stop();
+    }
+    setConfig(config) {
+        this.config = mergedConfig(config);
+        if (!this.config.enabled) {
+            this.switchedDuringCrossing.clear();
+        }
+    }
+    handleUpdate(state) {
+        // Fire-and-forget, but the registry/snapshot reads and the consumer's
+        // onTransition can all throw — a rejection here would escape the quota
+        // service's per-listener guard as an unhandled promise rejection.
+        if (state.claude) {
+            this.handleProviderUpdate('claude', state.claude).catch((error) => this.log?.('[AutoSwitch] Update failed for claude.', error));
+        }
+        if (state.codex) {
+            this.handleProviderUpdate('codex', state.codex).catch((error) => this.log?.('[AutoSwitch] Update failed for codex.', error));
+        }
+    }
+    async handleProviderUpdate(runtimeProvider, activeQuota) {
+        const providerId = runtimeStateToProvider(runtimeProvider);
+        // While a switch is mid-flight the registry's active account is
+        // indeterminate, so skip the whole update until it settles.
+        if (this.switchInFlight.has(providerId))
+            return;
+        const activeAccount = providerId === 'claude-code' ? this.getActiveClaudeAccount() : this.getActiveCodexAccount();
+        if (!activeAccount)
+            return;
+        const activeAccountId = accountIdFor(providerId, activeAccount);
+        if (quotaUtilization(activeQuota) < this.config.thresholdPct) {
+            this.switchedDuringCrossing.delete(providerId);
+        }
+        const accounts = providerId === 'claude-code' ? this.getClaudeAccounts() : this.getCodexAccounts();
+        if (accounts.length <= 1)
+            return;
+        const candidates = accounts.map((account) => {
+            const accountId = accountIdFor(providerId, account);
+            return {
+                accountId,
+                quota: accountId === activeAccountId ? activeQuota : this.readSnapshot(providerId, accountId),
+            };
+        });
+        const decision = decideAutoSwitch(providerId, { accountId: activeAccountId, quota: activeQuota }, candidates, this.config, this.now());
+        if (!decision)
+            return;
+        if (this.switchedDuringCrossing.has(providerId))
+            return;
+        const previousSwitchAt = this.lastSwitchAt[providerId] ?? 0;
+        if (this.cooldownMs > 0 && this.now() - previousSwitchAt < this.cooldownMs)
+            return;
+        this.switchInFlight.add(providerId);
+        let result;
+        try {
+            result = await this.switchAccount(providerId, decision.switchTo);
+        }
+        catch (error) {
+            this.log?.(`[AutoSwitch] Switch threw for ${providerId} to ${decision.switchTo}.`, error);
+            return;
+        }
+        finally {
+            this.switchInFlight.delete(providerId);
+        }
+        if (!result.success) {
+            this.log?.(`[AutoSwitch] Could not switch ${providerId} to ${decision.switchTo}.`, result.error);
+            return;
+        }
+        this.lastSwitchAt[providerId] = this.now();
+        this.switchedDuringCrossing.add(providerId);
+        // A switch that completes after stop()/dispose() still records its
+        // state, but must not fire a transition into a stopped consumer.
+        if (!this.subscription)
+            return;
+        this.onTransition?.({
+            provider: providerId,
+            from: activeAccountId,
+            to: decision.switchTo,
+        });
+    }
+}

package/dist/esm/browser.js

@@ -0,0 +1,34 @@
+/**
+ * Browser / webview entry.
+ *
+ * Pure, synchronous, filesystem-free helpers. Safe to bundle for browser
+ * runtimes (VS Code webviews, web apps, etc.). Does NOT pull in node:fs,
+ * node:path, or any Node-only module.
+ *
+ * For pricing hydration (LiteLLM catalog refresh), use `sidekick-shared/node`.
+ */
+export { getModelContextWindowSize, resolveModelContextWindow, DEFAULT_CONTEXT_WINDOW, } from './modelContext';
+export { normalizeProviderUsage, extractNormalizedUsage, calculateNormalizedUsageCost, } from './usageNormalization';
+export { formatTokenBreakdown, summarizeTokens, sumTokenTotals, TOKEN_CONTEXT_LABEL, TOKEN_MAIN_THREAD_LABEL, TOKEN_SESSION_TOTAL_LABEL, TOKEN_SUBAGENTS_LABEL, TOKEN_TOTAL_LABEL, } from './tokenSummary';
+export { ClaudeUsageDeduper, SYNTHETIC_MODEL } from './usage/claudeUsageDedupe';
+export { ASCII_CHARS_PER_TOKEN, estimateTextTokens, estimateSerializedTokens, } from './tokenEstimation';
+export { projectSessionTranscript } from './transcript';
+export { addLocalDays, formatDurationMs, formatLocalDateKey, formatTokenCount, parseLocalDateKey, } from './formatting';
+export { parseMcpToolName } from './parsers/mcpToolName';
+export { buildSessionContextSnapshot, calculateSessionContextPressure, createSessionContextProjector, } from './context/sessionContext';
+export { ACCOUNT_PROVIDER_IDS, MODEL_PROVIDER_IDS, QUOTA_PROVIDER_IDS, RUNTIME_QUOTA_PROVIDER_IDS, SESSION_PROVIDER_IDS, } from './providerIds';
+export { assistantTurnEventsFromSessionEvents, extractTurnSubagents, isAssistantTurnSubagentTool, reasoningSummary, segmentAssistantTurn, } from './turns/assistantTurn';
+export { parseModelId, getModelPricing, resolveModelPricing, getModelInfo, calculateCost, calculateCostWithPricing, calculateCostWithProvenance, mergeCostSources, shortModelName, getModelDisplayInfo, compareModelIds, sortModelIds, formatCost, } from './modelInfo';
+export { exportResolvedModelCatalog, importResolvedModelCatalog, registerModelAlias, resolveModelAlias, RESOLVED_MODEL_CATALOG_SCHEMA_VERSION, } from './modelCatalog';
+export { BILLING_BLOCK_DURATION_MS, computeBillingBlocks, findActiveBillingBlock, } from './usage/billingBlocks';
+export { bucketUsage, summarizeUsageRows, usageBucketKey, weekKey } from './usage/usageReports';
+export { applySessionSummary, isFileImported, markFileImported, removeSessionSummary, sessionSummaryFromStats, } from './historicalStore';
+export { FAILING_TOOL_TREND_ARROWS, failingToolTrend, mergeFailingToolWindows, } from './failingTools';
+export { diagnoseProviderFailure, PROVIDER_AUTHENTICATION_SOURCES, PROVIDER_AUTHENTICATION_STATES, PROVIDER_CREDENTIAL_KINDS, PROVIDER_FAILURE_CODES, PROVIDER_FAILURE_EVIDENCE_SOURCES, PROVIDER_RECOVERY_ACTIONS, } from './providerFailure';
+export { isAggregateCodexLimit } from './types/codex';
+// Codex rollout parsing (pure: no filesystem access)
+export { CodexRolloutParser, DEFAULT_MAX_TRACKED_TOOL_CALLS, extractPatchFilePaths, normalizeCodexToolName, normalizeCodexToolInput, resolveCodexCallUsage, } from './parsers/codexParser';
+export { HUMAN_CLAUDE_ENTRYPOINTS, HUMAN_CODEX_SOURCES, humanPromptText, isHumanPrompt, } from './humanPrompt';
+export { renderHandoffUrlTemplate } from './handoffUrl';
+// Tool categories across providers
+export { classifyTool, TOOL_CATEGORIES } from './toolCategory';

package/dist/esm/claudeCredentialDoctor.js

@@ -0,0 +1,239 @@
+/**
+ * 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.
+ */
+import { execFileSync } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+import { listSavedAccountProfiles } from './accountRegistry';
+import { claudeKeychainService, getClaudeProfileDir, getClaudeProfileHome, getClaudeProfilesDir, isLiveClaudeHomeSidekickProfile, readLiveClaudeIdentity, } from './claudeProfiles';
+import { forgetClaudeCredentialHome, readClaudeCredentialLedger } from './claudeCredentialLedger';
+import { deleteStoredCredentials, readClaudeCredentialStore, SIDEKICK_KEYCHAIN_COMMENT_PREFIX, } from './credentialIO';
+import { syncClaudeLiveState } from './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. */
+export 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 = 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: claudeKeychainService(resolved),
+            ownership,
+            inLedger,
+        });
+    };
+    for (const entry of readClaudeCredentialLedger())
+        add(entry.configDir, 'ledger', true);
+    try {
+        for (const id of fs.readdirSync(getClaudeProfilesDir())) {
+            add(getClaudeProfileHome(id), 'profile-home');
+        }
+    }
+    catch {
+        /* no profiles yet */
+    }
+    for (const item of keychainItems) {
+        if (!item.comment?.startsWith(SIDEKICK_KEYCHAIN_COMMENT_PREFIX))
+            continue;
+        const configDir = item.comment.slice(SIDEKICK_KEYCHAIN_COMMENT_PREFIX.length);
+        // The tag must name the directory the service was derived from.
+        if (configDir && claudeKeychainService(configDir) === item.service) {
+            add(configDir, 'keychain-tag');
+        }
+    }
+    return [...homes.values()];
+}
+function isRecentPendingLogin(configDir, now) {
+    const profilesDir = path.resolve(getClaudeProfilesDir());
+    const loginDir = path.dirname(configDir);
+    if (path.dirname(loginDir) !== profilesDir)
+        return false;
+    try {
+        const pending = JSON.parse(fs.readFileSync(path.join(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;
+    }
+}
+export 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 listSavedAccountProfiles('claude-code')) {
+        profilesByHome.set(path.resolve(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 = isLiveClaudeHomeSidekickProfile()
+        ? null
+        : (readLiveClaudeIdentity()?.uuid ?? null);
+    const findings = [];
+    const homes = collectOwnedHomes(keychainItems);
+    for (const home of homes) {
+        const store = 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. */
+export 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 = syncClaudeLiveState();
+    }
+    for (const finding of inspection.findings) {
+        try {
+            if (finding.kind === 'live-duplicate') {
+                const still = 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') {
+                forgetClaudeCredentialHome(finding.configDir);
+                result.repaired.push({ finding, ok: true });
+                continue;
+            }
+            const ok = 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(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/esm/claudeCredentialLedger.js

@@ -0,0 +1,91 @@
+/**
+ * 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).
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { getAccountsDir } from './accountRegistry';
+import { claudeKeychainService } from './claudeProfiles';
+import { updateJsonStoreAtomicSync } from './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'),
+    };
+}
+export function getClaudeCredentialLedgerPath() {
+    return path.join(getAccountsDir(), 'claude', 'credential-homes.json');
+}
+export 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. */
+export function recordClaudeCredentialHome(configDir, purpose, now = new Date()) {
+    const resolved = path.resolve(configDir);
+    const stamp = now.toISOString();
+    try {
+        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: 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. */
+export function forgetClaudeCredentialHome(configDir) {
+    const resolved = path.resolve(configDir);
+    try {
+        if (!fs.existsSync(getClaudeCredentialLedgerPath()))
+            return;
+        updateJsonStoreAtomicSync(getClaudeCredentialLedgerPath(), emptyLedger, (latest) => {
+            const ledger = normalizeLedger(latest);
+            ledger.entries = ledger.entries.filter((entry) => entry.configDir !== resolved);
+            return ledger;
+        });
+    }
+    catch {
+        /* best effort */
+    }
+}