instar 1.3.523 → 1.3.525

package/dist/core/CredentialIdentityOracle.js

@@ -0,0 +1,89 @@
+/**
+ * CredentialIdentityOracle — Step 3 of live credential re-pointing (spec §2.3 verify, §2.11).
+ *
+ * The ONLY oracle that reads credential REALITY: given a config-home slot, it reads the slot's
+ * current credential blob, takes its OAuth access token, and asks the Anthropic OAuth profile
+ * endpoint (`GET /api/oauth/profile`) which account that token belongs to. `claude auth status`
+ * is disqualified (E4a — it reads a metadata file, not the live credential, and lies during the
+ * keychain-first/config-second swap window); the config `oauthAccount` record is metadata, not
+ * truth. The profile endpoint is the truth-oracle the convergence experiments (E4b) adopted.
+ *
+ * It implements the `IdentityOracle` interface the `CredentialLocationLedger` (Step 2) seeds and
+ * recovers from. Separation of concerns: this oracle returns the RAW probed email (or an
+ * `unavailable` result); the LEDGER maps email → accountId through the pool and decides what to
+ * do on an ambiguous/unknown match. That keeps the pool-mapping policy in one place (§2.2).
+ *
+ * §2.11 classification CONTRACT — `email` set IFF the profile returned a non-empty string email;
+ * EVERY other outcome (no token / fetch error / non-2xx (incl. 401/403/429/5xx) / unparseable /
+ * missing-or-empty-or-nonstring email) → `unavailable` with a reason. NEVER a "mismatch": an
+ * unverifiable slot is quarantine-never-repair upstream, never a guess.
+ *
+ * Reuses `readClaudeOauth` (OAuthRefresher) for the per-slot blob read — no hand-rolled keychain
+ * access. The profile fetch lives here behind a bounded timeout; this file is allowlisted in
+ * `scripts/lint-no-direct-llm-http.js` for the SAME reason QuotaCollector is — an OAuth profile
+ * call is identity bookkeeping, not an LLM message call.
+ *
+ * NOTE (tracked to Step 4/5): when the slot's access token is EXPIRED, the spec's optimization is
+ * one refresh exchange (through the credential write funnel) before the profile call to avoid a
+ * spurious `unavailable`. That refresh WRITES a rotated token, so it must go through the Step-4
+ * write funnel — until that lands, an expired token classifies as `unavailable` (the safe
+ * direction: the slot is quarantined and re-probed, never guessed). The profile call here writes
+ * nothing.
+ */
+import { readClaudeOauth } from './OAuthRefresher.js';
+const OAUTH_PROFILE_URL = 'https://api.anthropic.com/api/oauth/profile';
+const DEFAULT_TIMEOUT_MS = 10_000;
+export class CredentialIdentityOracle {
+    store;
+    fetchImpl;
+    timeoutMs;
+    constructor(deps = {}) {
+        this.store = deps.store;
+        this.fetchImpl =
+            deps.fetchImpl ??
+                ((url, init) => fetch(url, init));
+        this.timeoutMs = deps.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    }
+    async resolveSlotTenant(slot) {
+        // 1. Read the slot's current credential blob → access token. (No write; reuses OAuthRefresher.)
+        const oauth = this.store ? readClaudeOauth(slot, this.store) : readClaudeOauth(slot);
+        const token = oauth?.accessToken;
+        if (!token || typeof token !== 'string') {
+            return { unavailable: true, reason: 'no access token in slot credential store' };
+        }
+        // 2. Probe the profile endpoint with the slot's token. Bounded; any failure → unavailable.
+        let resp;
+        try {
+            resp = await this.fetchImpl(OAUTH_PROFILE_URL, {
+                headers: {
+                    Authorization: `Bearer ${token}`,
+                    Accept: 'application/json',
+                    'Content-Type': 'application/json',
+                    'anthropic-beta': 'oauth-2025-04-20',
+                },
+                signal: AbortSignal.timeout(this.timeoutMs),
+            });
+        }
+        catch (err) {
+            return { unavailable: true, reason: `profile fetch error: ${err?.message ?? 'unknown'}` };
+        }
+        if (!resp.ok) {
+            // 401/403/429/5xx all land here — never a mismatch, always unavailable (§2.11).
+            return { unavailable: true, reason: `profile endpoint returned ${resp.status}` };
+        }
+        // 3. Parse + extract the owning email.
+        let data;
+        try {
+            data = await resp.json();
+        }
+        catch {
+            return { unavailable: true, reason: 'unparseable profile response' };
+        }
+        const email = data?.account?.email;
+        if (typeof email !== 'string' || email.length === 0) {
+            return { unavailable: true, reason: 'profile response carried no usable email' };
+        }
+        return { email };
+    }
+}
+//# sourceMappingURL=CredentialIdentityOracle.js.map

package/dist/core/CredentialIdentityOracle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CredentialIdentityOracle.js","sourceRoot":"","sources":["../../src/core/CredentialIdentityOracle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,EAAE,eAAe,EAAwB,MAAM,qBAAqB,CAAC;AAG5E,MAAM,iBAAiB,GAAG,6CAA6C,CAAC;AACxE,MAAM,kBAAkB,GAAG,MAAM,CAAC;AAiBlC,MAAM,OAAO,wBAAwB;IAClB,KAAK,CAAmB;IACxB,SAAS,CAAc;IACvB,SAAS,CAAS;IAEnC,YAAY,OAAqC,EAAE;QACjD,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;QACxB,IAAI,CAAC,SAAS;YACZ,IAAI,CAAC,SAAS;gBACd,CAAC,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,IAAmB,CAAuC,CAAC,CAAC;QACzF,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,kBAAkB,CAAC;IACxD,CAAC;IAED,KAAK,CAAC,iBAAiB,CAAC,IAAY;QAClC,gGAAgG;QAChG,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,eAAe,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC;QACrF,MAAM,KAAK,GAAG,KAAK,EAAE,WAAW,CAAC;QACjC,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YACxC,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,0CAA0C,EAAE,CAAC;QACnF,CAAC;QAED,2FAA2F;QAC3F,IAAI,IAAmE,CAAC;QACxE,IAAI,CAAC;YACH,IAAI,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,iBAAiB,EAAE;gBAC7C,OAAO,EAAE;oBACP,aAAa,EAAE,UAAU,KAAK,EAAE;oBAChC,MAAM,EAAE,kBAAkB;oBAC1B,cAAc,EAAE,kBAAkB;oBAClC,gBAAgB,EAAE,kBAAkB;iBACrC;gBACD,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC;aAC5C,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,wBAAyB,GAAa,EAAE,OAAO,IAAI,SAAS,EAAE,EAAE,CAAC;QACvG,CAAC;QAED,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC;YACb,gFAAgF;YAChF,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,6BAA6B,IAAI,CAAC,MAAM,EAAE,EAAE,CAAC;QACnF,CAAC;QAED,uCAAuC;QACvC,IAAI,IAAa,CAAC;QAClB,IAAI,CAAC;YACH,IAAI,GAAG,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;QAC3B,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,8BAA8B,EAAE,CAAC;QACvE,CAAC;QACD,MAAM,KAAK,GAAI,IAA0C,EAAE,OAAO,EAAE,KAAK,CAAC;QAC1E,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACpD,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,0CAA0C,EAAE,CAAC;QACnF,CAAC;QACD,OAAO,EAAE,KAAK,EAAE,CAAC;IACnB,CAAC;CACF"}

package/dist/core/CredentialLocationLedger.d.ts

@@ -0,0 +1,187 @@
+/**
+ * CredentialLocationLedger — the bookkeeping core of live credential re-pointing.
+ *
+ * Spec: docs/specs/live-credential-repointing-rebalancer.md §2.2.
+ *
+ * A machine-local durable ledger (`<stateDir>/credential-locations.json`) that records,
+ * for each config-home SLOT, which pool account's credential currently lives there. It is
+ * the single source of truth for "which account is in which home" once live re-pointing is
+ * enabled — every consumer that today treats a pool account's enrollment `configHome` as its
+ * live location instead resolves through `slotOf(accountId)` / `tenantOf(slot)` here.
+ *
+ * This module is Step 2 of Increment A: the bookkeeping + durability + seeding/recovery core.
+ * It performs NO keychain writes itself — the staged swap executor (§2.3, Step 5) and the
+ * write funnel (§2.2, Step 4) are separate. The identity oracle it seeds/recovers from is the
+ * `IdentityOracle` interface (Step 3 implements it against the Anthropic OAuth profile endpoint,
+ * `/api/oauth/profile`, routed through the existing intelligence-provider chokepoint).
+ *
+ * Durability posture (the §2.2 contract — NOT SubscriptionPool's posture):
+ *   - missing file        → NEVER-SEEDED (mode 'ok', empty assignments). Reads return null →
+ *                           consumers fall back to today's enrollment-home behavior. This is
+ *                           normal, not a degradation.
+ *   - corrupt/unparseable → UNKNOWN MODE (fail-closed for moves: every mutation refuses;
+ *                           fail-open-LOUD for reads: reads return null AND one HIGH attention
+ *                           item names the degradation). Recovery is a fresh `seedFromOracle()`.
+ *                           This is deliberately NOT a silent fresh-start (No Silent Degradation):
+ *                           a quiet reset here could place a session onto the wrong account.
+ */
+/** The on-disk schema version this module writes. Bumped only on a breaking shape change. */
+export declare const CREDENTIAL_LEDGER_SCHEMA_VERSION = 1;
+/** Which account's credential currently lives in a given config-home slot. */
+export interface CredentialAssignment {
+    /** Config-home path acting as the slot, e.g. `~/.claude` or an enrollment home. */
+    slot: string;
+    /** Pool account id whose credential currently sits in this slot. */
+    accountId: string;
+    /** ISO — when this assignment was last recorded (a swap/seed into this slot). */
+    since: string;
+    /** ISO — last identity-oracle confirmation of this slot's tenant; null = never verified. */
+    lastVerifiedAt: string | null;
+    /** Excluded from balancing — oracle was unavailable, or a divergence was detected. */
+    quarantined: boolean;
+}
+/** One journal entry — in-flight swap phases + the last N completed (pruned at commit). */
+export interface CredentialLedgerJournalEntry {
+    /** Monotonic sequence within the ledger (== the version at write time). */
+    seq: number;
+    /** The operation this entry belongs to. */
+    op: 'seed' | 'swap' | 'set-default' | 'quarantine' | 'unquarantine' | 'restore';
+    /** The phase of that operation (swap is multi-phase per §2.3; others are single-shot). */
+    phase: 'begin' | 'staged' | 'exchanged' | 'verified' | 'done' | 'aborted';
+    /** Slots this entry touched (ordered). */
+    slots: string[];
+    /** Free-text detail (never a credential — names/ids/reasons only). */
+    detail?: string;
+    /** ISO timestamp. */
+    at: string;
+}
+export interface CredentialLocationLedgerStore {
+    version: number;
+    assignments: CredentialAssignment[];
+    journal: CredentialLedgerJournalEntry[];
+}
+/**
+ * Result of probing a slot's CURRENT credential blob for its owning account.
+ * Implemented in Step 3 against `GET /api/oauth/profile` (the Anthropic OAuth profile endpoint).
+ *
+ * CONTRACT (§2.11): `email` set === identity-confirmed; `unavailable:true` for EVERY other
+ * outcome (timeout/401/403/429/5xx/missing-or-empty-or-nonstring email/unparseable). The
+ * oracle NEVER reports a "mismatch" — an unverifiable slot is quarantine-never-repair, never
+ * a guess.
+ */
+export interface IdentityOracleResult {
+    email?: string;
+    unavailable?: boolean;
+    reason?: string;
+}
+export interface IdentityOracle {
+    /** Resolve which account email the credential blob currently in `slot` belongs to. */
+    resolveSlotTenant(slot: string): Promise<IdentityOracleResult>;
+}
+/** Narrow view of the subscription pool the ledger needs (satisfied by SubscriptionPool). */
+export interface LedgerPoolAccount {
+    id: string;
+    email?: string;
+    configHome: string;
+    framework?: string;
+}
+export interface LedgerPoolView {
+    list(): LedgerPoolAccount[];
+}
+/** Attention-item shape (mirrors AgentWorktreeDetector.AttentionItemInput). */
+export interface CredentialLedgerAttentionInput {
+    id: string;
+    title: string;
+    summary: string;
+    description?: string;
+    category: string;
+    priority: 'URGENT' | 'HIGH' | 'NORMAL' | 'LOW';
+    sourceContext?: string;
+}
+export interface CredentialLocationLedgerDeps {
+    /** Agent stateDir (e.g. `.instar`). The ledger lives at `<stateDir>/credential-locations.json`. */
+    stateDir: string;
+    /** The subscription pool — used to map a probed email → accountId during seed/recovery. */
+    pool: LedgerPoolView;
+    /** Identity oracle for seeding/recovery (Step 3 implementation). */
+    oracle: IdentityOracle;
+    /** Emit a HIGH attention item (typically telegramAdapter.createAttentionItem). */
+    emitAttention?: (item: CredentialLedgerAttentionInput) => void | Promise<void>;
+    /** Injectable clock for deterministic tests. */
+    now?: () => string;
+}
+/** Thrown when a mutation is attempted while the ledger is in UNKNOWN mode (fail-closed). */
+export declare class CredentialLedgerUnknownModeError extends Error {
+    constructor(message: string);
+}
+/** Outcome of a seed/recovery probe for one slot (returned for caller observability + tests). */
+export interface SeedSlotOutcome {
+    slot: string;
+    result: 'assigned' | 'unavailable' | 'ambiguous' | 'unknown-email';
+    accountId?: string;
+    email?: string;
+    reason?: string;
+}
+export declare class CredentialLocationLedger {
+    private readonly storePath;
+    private readonly pool;
+    private readonly oracle;
+    private readonly emitAttention?;
+    private readonly now;
+    private store;
+    /** UNKNOWN mode — set when the on-disk ledger was present but corrupt. Fail-closed for moves. */
+    private unknownMode;
+    /** Dedupe the UNKNOWN-mode attention item so a re-read storm raises it once. */
+    private unknownAttentionRaised;
+    /** In-memory index: accountId → slot (rebuilt on every mutation/load). */
+    private slotByAccount;
+    /** In-memory index: slot → accountId. */
+    private accountBySlot;
+    constructor(deps: CredentialLocationLedgerDeps);
+    private load;
+    private save;
+    private reindex;
+    /** Current slot holding `accountId`'s credential, or null (UNKNOWN mode / never-seeded). */
+    slotOf(accountId: string): string | null;
+    /** Account currently tenanting `slot`, or null (UNKNOWN mode / never-seeded). */
+    tenantOf(slot: string): string | null;
+    isUnknownMode(): boolean;
+    /** True when the ledger has at least one assignment (has been seeded). */
+    isSeeded(): boolean;
+    getAssignments(): readonly CredentialAssignment[];
+    getAssignment(slot: string): CredentialAssignment | null;
+    getJournal(): readonly CredentialLedgerJournalEntry[];
+    get version(): number;
+    private assertMutable;
+    /** Record (or re-point) `slot`'s tenant to `accountId`. Single-writer; bumps version. */
+    recordAssignment(slot: string, accountId: string, opts?: {
+        verifiedAt?: string | null;
+        op?: CredentialLedgerJournalEntry['op'];
+    }): CredentialAssignment;
+    /** Mark a slot quarantined (excluded from balancing) — oracle unavailable / divergence. */
+    quarantineSlot(slot: string, reason: string): void;
+    /** Lift a quarantine after a clean re-probe. */
+    unquarantineSlot(slot: string): void;
+    /** Stamp a slot's lastVerifiedAt after an identity-oracle confirmation. */
+    markVerified(slot: string, at?: string): void;
+    /** Append a journal entry for an in-flight swap phase (used by the executor in Step 5). */
+    appendJournal(entry: Omit<CredentialLedgerJournalEntry, 'seq' | 'at'> & {
+        at?: string;
+    }): CredentialLedgerJournalEntry;
+    private bumpAndJournal;
+    /** Keep all non-terminal (in-flight) entries + the last MAX_COMPLETED_JOURNAL terminal ones. */
+    private pruneJournal;
+    /**
+     * Derive each slot's tenant by probing its CURRENT credential via the oracle, then mapping
+     * email → accountId through the pool. Clears UNKNOWN mode on a clean pass. Per §2.2:
+     *   - oracle unavailable for a slot → quarantine that slot (never guess), continue.
+     *   - email maps to exactly one claude-code account → record the assignment (verified now).
+     *   - ambiguous (≥2 accounts share the email) or unknown email → REFUSE auto-assign for that
+     *     slot + raise an attention item; never guess.
+     * Slots = the distinct enrollment `configHome`s of claude-code pool accounts.
+     */
+    seedFromOracle(): Promise<SeedSlotOutcome[]>;
+    private raiseUnknownModeAttention;
+    private raiseSeedRefusalAttention;
+}
+//# sourceMappingURL=CredentialLocationLedger.d.ts.map

package/dist/core/CredentialLocationLedger.d.ts.map

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

package/dist/core/CredentialLocationLedger.js

@@ -0,0 +1,351 @@
+/**
+ * CredentialLocationLedger — the bookkeeping core of live credential re-pointing.
+ *
+ * Spec: docs/specs/live-credential-repointing-rebalancer.md §2.2.
+ *
+ * A machine-local durable ledger (`<stateDir>/credential-locations.json`) that records,
+ * for each config-home SLOT, which pool account's credential currently lives there. It is
+ * the single source of truth for "which account is in which home" once live re-pointing is
+ * enabled — every consumer that today treats a pool account's enrollment `configHome` as its
+ * live location instead resolves through `slotOf(accountId)` / `tenantOf(slot)` here.
+ *
+ * This module is Step 2 of Increment A: the bookkeeping + durability + seeding/recovery core.
+ * It performs NO keychain writes itself — the staged swap executor (§2.3, Step 5) and the
+ * write funnel (§2.2, Step 4) are separate. The identity oracle it seeds/recovers from is the
+ * `IdentityOracle` interface (Step 3 implements it against the Anthropic OAuth profile endpoint,
+ * `/api/oauth/profile`, routed through the existing intelligence-provider chokepoint).
+ *
+ * Durability posture (the §2.2 contract — NOT SubscriptionPool's posture):
+ *   - missing file        → NEVER-SEEDED (mode 'ok', empty assignments). Reads return null →
+ *                           consumers fall back to today's enrollment-home behavior. This is
+ *                           normal, not a degradation.
+ *   - corrupt/unparseable → UNKNOWN MODE (fail-closed for moves: every mutation refuses;
+ *                           fail-open-LOUD for reads: reads return null AND one HIGH attention
+ *                           item names the degradation). Recovery is a fresh `seedFromOracle()`.
+ *                           This is deliberately NOT a silent fresh-start (No Silent Degradation):
+ *                           a quiet reset here could place a session onto the wrong account.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+/** The on-disk schema version this module writes. Bumped only on a breaking shape change. */
+export const CREDENTIAL_LEDGER_SCHEMA_VERSION = 1;
+/** Thrown when a mutation is attempted while the ledger is in UNKNOWN mode (fail-closed). */
+export class CredentialLedgerUnknownModeError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'CredentialLedgerUnknownModeError';
+    }
+}
+const MAX_COMPLETED_JOURNAL = 50;
+const NON_CLAUDE_FRAMEWORKS = new Set(['codex-cli', 'gemini-cli', 'pi-cli']);
+/** A claude-code account is the implicit default (framework undefined or 'claude-code'). */
+function isClaudeCodeAccount(a) {
+    return !a.framework || a.framework === 'claude-code';
+}
+export class CredentialLocationLedger {
+    storePath;
+    pool;
+    oracle;
+    emitAttention;
+    now;
+    store;
+    /** UNKNOWN mode — set when the on-disk ledger was present but corrupt. Fail-closed for moves. */
+    unknownMode = false;
+    /** Dedupe the UNKNOWN-mode attention item so a re-read storm raises it once. */
+    unknownAttentionRaised = false;
+    /** In-memory index: accountId → slot (rebuilt on every mutation/load). */
+    slotByAccount = new Map();
+    /** In-memory index: slot → accountId. */
+    accountBySlot = new Map();
+    constructor(deps) {
+        this.storePath = path.join(deps.stateDir, 'credential-locations.json');
+        this.pool = deps.pool;
+        this.oracle = deps.oracle;
+        this.emitAttention = deps.emitAttention;
+        this.now = deps.now ?? (() => new Date().toISOString());
+        this.store = this.load();
+        this.reindex();
+        if (this.unknownMode)
+            void this.raiseUnknownModeAttention();
+    }
+    // ─── Load / save (atomic tmp+rename — the SubscriptionPool.save pattern) ──────────
+    load() {
+        if (!fs.existsSync(this.storePath)) {
+            // NEVER-SEEDED — not corrupt. Empty ledger; reads fall back to enrollment homes.
+            return { version: 0, assignments: [], journal: [] };
+        }
+        try {
+            const data = JSON.parse(fs.readFileSync(this.storePath, 'utf-8'));
+            if (data &&
+                typeof data.version === 'number' &&
+                Array.isArray(data.assignments) &&
+                Array.isArray(data.journal)) {
+                return data;
+            }
+            // Present but wrong shape → corrupt.
+            this.unknownMode = true;
+        }
+        catch {
+            // Present but unparseable → corrupt. NOT a silent fresh-start: UNKNOWN mode is entered
+            // and a HIGH attention item is raised by the constructor. (No Silent Degradation.)
+            this.unknownMode = true;
+        }
+        return { version: 0, assignments: [], journal: [] };
+    }
+    save() {
+        try {
+            const dir = path.dirname(this.storePath);
+            fs.mkdirSync(dir, { recursive: true });
+            const tmpPath = `${this.storePath}.${process.pid}.tmp`;
+            fs.writeFileSync(tmpPath, JSON.stringify(this.store, null, 2) + '\n');
+            fs.renameSync(tmpPath, this.storePath);
+        }
+        catch {
+            // @silent-fallback-ok — a persistence failure leaves the in-memory store authoritative
+            // for this process; the next mutation retries the write. The ledger is bookkeeping, not
+            // a credential, so an unwritten entry never strands a login — at worst a recovery probe
+            // re-derives it. Surfacing every transient fs hiccup would be noise, not signal.
+        }
+    }
+    reindex() {
+        this.slotByAccount.clear();
+        this.accountBySlot.clear();
+        for (const a of this.store.assignments) {
+            // Tenant-less quarantine markers (accountId === '') carry no resolvable tenant — a
+            // seed refusal / unavailable probe records the slot as quarantined-unknown, and a read
+            // of it must be null (caller falls back), never the empty string.
+            if (!a.accountId)
+                continue;
+            this.slotByAccount.set(a.accountId, a.slot);
+            this.accountBySlot.set(a.slot, a.accountId);
+        }
+    }
+    // ─── Sync in-memory reads (never disk/parse per spawn; never throw) ───────────────
+    /** Current slot holding `accountId`'s credential, or null (UNKNOWN mode / never-seeded). */
+    slotOf(accountId) {
+        if (this.unknownMode)
+            return null;
+        return this.slotByAccount.get(accountId) ?? null;
+    }
+    /** Account currently tenanting `slot`, or null (UNKNOWN mode / never-seeded). */
+    tenantOf(slot) {
+        if (this.unknownMode)
+            return null;
+        return this.accountBySlot.get(slot) ?? null;
+    }
+    isUnknownMode() {
+        return this.unknownMode;
+    }
+    /** True when the ledger has at least one assignment (has been seeded). */
+    isSeeded() {
+        return !this.unknownMode && this.store.assignments.length > 0;
+    }
+    getAssignments() {
+        return this.store.assignments.slice();
+    }
+    getAssignment(slot) {
+        return this.store.assignments.find((a) => a.slot === slot) ?? null;
+    }
+    getJournal() {
+        return this.store.journal.slice();
+    }
+    get version() {
+        return this.store.version;
+    }
+    // ─── Mutations (single-writer; refuse in UNKNOWN mode — fail-closed for moves) ─────
+    assertMutable(op) {
+        if (this.unknownMode) {
+            throw new CredentialLedgerUnknownModeError(`ledger is in UNKNOWN mode (corrupt on-disk state) — ${op} refused; recover via seedFromOracle()`);
+        }
+    }
+    /** Record (or re-point) `slot`'s tenant to `accountId`. Single-writer; bumps version. */
+    recordAssignment(slot, accountId, opts) {
+        this.assertMutable('recordAssignment');
+        const at = this.now();
+        const existing = this.store.assignments.find((a) => a.slot === slot);
+        // A slot's tenant changing means the previous tenant is no longer here — drop any stale
+        // assignment that claimed the SAME accountId in a different slot (one home per credential).
+        this.store.assignments = this.store.assignments.filter((a) => a.slot !== slot && a.accountId !== accountId);
+        const assignment = {
+            slot,
+            accountId,
+            since: existing && existing.accountId === accountId ? existing.since : at,
+            lastVerifiedAt: opts?.verifiedAt !== undefined ? opts.verifiedAt : (existing?.lastVerifiedAt ?? null),
+            quarantined: false,
+        };
+        this.store.assignments.push(assignment);
+        this.bumpAndJournal({ op: opts?.op ?? 'swap', phase: 'done', slots: [slot], detail: `tenant=${accountId}` });
+        this.reindex();
+        this.save();
+        return assignment;
+    }
+    /** Mark a slot quarantined (excluded from balancing) — oracle unavailable / divergence. */
+    quarantineSlot(slot, reason) {
+        this.assertMutable('quarantineSlot');
+        const a = this.store.assignments.find((x) => x.slot === slot);
+        if (a) {
+            a.quarantined = true;
+        }
+        else {
+            // Quarantine a slot we have no confirmed tenant for: record a tenant-less quarantine
+            // marker so the slot is durably excluded until a clean probe clears it.
+            this.store.assignments.push({ slot, accountId: '', since: this.now(), lastVerifiedAt: null, quarantined: true });
+        }
+        this.bumpAndJournal({ op: 'quarantine', phase: 'done', slots: [slot], detail: reason });
+        this.reindex();
+        this.save();
+    }
+    /** Lift a quarantine after a clean re-probe. */
+    unquarantineSlot(slot) {
+        this.assertMutable('unquarantineSlot');
+        const a = this.store.assignments.find((x) => x.slot === slot);
+        if (a) {
+            a.quarantined = false;
+            this.bumpAndJournal({ op: 'unquarantine', phase: 'done', slots: [slot] });
+            this.reindex();
+            this.save();
+        }
+    }
+    /** Stamp a slot's lastVerifiedAt after an identity-oracle confirmation. */
+    markVerified(slot, at) {
+        this.assertMutable('markVerified');
+        const a = this.store.assignments.find((x) => x.slot === slot);
+        if (a) {
+            a.lastVerifiedAt = at ?? this.now();
+            this.save();
+        }
+    }
+    /** Append a journal entry for an in-flight swap phase (used by the executor in Step 5). */
+    appendJournal(entry) {
+        this.assertMutable('appendJournal');
+        return this.bumpAndJournal(entry);
+    }
+    bumpAndJournal(entry) {
+        this.store.version += 1;
+        const full = {
+            seq: this.store.version,
+            op: entry.op,
+            phase: entry.phase,
+            slots: entry.slots ?? [],
+            ...(entry.detail !== undefined ? { detail: entry.detail } : {}),
+            at: entry.at ?? this.now(),
+        };
+        this.store.journal.push(full);
+        this.pruneJournal();
+        return full;
+    }
+    /** Keep all non-terminal (in-flight) entries + the last MAX_COMPLETED_JOURNAL terminal ones. */
+    pruneJournal() {
+        const terminal = (p) => p === 'done' || p === 'aborted';
+        const inFlight = this.store.journal.filter((e) => !terminal(e.phase));
+        const completed = this.store.journal.filter((e) => terminal(e.phase));
+        const keptCompleted = completed.slice(-MAX_COMPLETED_JOURNAL);
+        this.store.journal = [...inFlight, ...keptCompleted].sort((a, b) => a.seq - b.seq);
+    }
+    // ─── Seeding / recovery via the identity oracle (§2.2) ────────────────────────────
+    /**
+     * Derive each slot's tenant by probing its CURRENT credential via the oracle, then mapping
+     * email → accountId through the pool. Clears UNKNOWN mode on a clean pass. Per §2.2:
+     *   - oracle unavailable for a slot → quarantine that slot (never guess), continue.
+     *   - email maps to exactly one claude-code account → record the assignment (verified now).
+     *   - ambiguous (≥2 accounts share the email) or unknown email → REFUSE auto-assign for that
+     *     slot + raise an attention item; never guess.
+     * Slots = the distinct enrollment `configHome`s of claude-code pool accounts.
+     */
+    async seedFromOracle() {
+        const claudeAccounts = this.pool.list().filter(isClaudeCodeAccount);
+        const slots = Array.from(new Set(claudeAccounts.map((a) => a.configHome))).filter(Boolean);
+        const outcomes = [];
+        // A clean slate for the rebuild; UNKNOWN mode is cleared as soon as we begin a real probe
+        // pass (the rebuild is the recovery path the spec names).
+        this.store = { version: this.store.version, assignments: [], journal: this.store.journal };
+        this.unknownMode = false;
+        this.unknownAttentionRaised = false;
+        this.bumpAndJournal({ op: 'seed', phase: 'begin', slots, detail: `${slots.length} slot(s)` });
+        for (const slot of slots) {
+            let result;
+            try {
+                result = await this.oracle.resolveSlotTenant(slot);
+            }
+            catch (err) {
+                // An oracle that THROWS is treated identically to unavailable (§2.11 — never a guess,
+                // never a mismatch). This is loud at the slot level (quarantine), not a silent swallow.
+                result = { unavailable: true, reason: `oracle threw: ${err?.message ?? 'unknown'}` };
+            }
+            if (result.unavailable || !result.email) {
+                this.store.assignments.push({ slot, accountId: '', since: this.now(), lastVerifiedAt: null, quarantined: true });
+                outcomes.push({ slot, result: 'unavailable', reason: result.reason ?? 'oracle unavailable' });
+                continue;
+            }
+            const matches = claudeAccounts.filter((a) => a.email && a.email === result.email);
+            if (matches.length === 1) {
+                this.store.assignments.push({
+                    slot,
+                    accountId: matches[0].id,
+                    since: this.now(),
+                    lastVerifiedAt: this.now(),
+                    quarantined: false,
+                });
+                outcomes.push({ slot, result: 'assigned', accountId: matches[0].id, email: result.email });
+            }
+            else if (matches.length > 1) {
+                // Ambiguous — two pool records, one email (legal under multi-grant). Never guess.
+                this.store.assignments.push({ slot, accountId: '', since: this.now(), lastVerifiedAt: null, quarantined: true });
+                outcomes.push({ slot, result: 'ambiguous', email: result.email, reason: `${matches.length} pool accounts share ${result.email}` });
+                await this.raiseSeedRefusalAttention(slot, 'ambiguous', `${matches.length} accounts share ${result.email}`);
+            }
+            else {
+                // Probed email matches no pool account.
+                this.store.assignments.push({ slot, accountId: '', since: this.now(), lastVerifiedAt: null, quarantined: true });
+                outcomes.push({ slot, result: 'unknown-email', email: result.email, reason: `no pool account for ${result.email}` });
+                await this.raiseSeedRefusalAttention(slot, 'unknown-email', `no pool account for ${result.email}`);
+            }
+        }
+        this.bumpAndJournal({ op: 'seed', phase: 'done', slots, detail: `${outcomes.filter((o) => o.result === 'assigned').length} assigned` });
+        this.reindex();
+        this.save();
+        return outcomes;
+    }
+    // ─── Attention (LOUD degradation surfaces) ───────────────────────────────────────
+    async raiseUnknownModeAttention() {
+        if (this.unknownAttentionRaised || !this.emitAttention)
+            return;
+        this.unknownAttentionRaised = true;
+        try {
+            await this.emitAttention({
+                id: 'credential-ledger-unknown-mode',
+                title: 'Credential location ledger is in UNKNOWN mode',
+                summary: 'The credential-locations ledger on disk was unreadable. Credential swaps are refused (fail-closed) and credential reads fall back to enrollment homes until a fresh identity-oracle probe rebuilds it.',
+                description: 'Recovery: re-seed via the identity oracle (POST /credentials/locations re-probe, or seedFromOracle()). No credential was moved while in this state.',
+                category: 'credential-repointing',
+                priority: 'HIGH',
+                sourceContext: 'credential-location-ledger',
+            });
+        }
+        catch {
+            // @silent-fallback-ok — the attention emitter is best-effort; a delivery failure must
+            // not throw out of the ledger constructor and crash boot. The UNKNOWN-mode posture
+            // (reads-null + mutations-refuse) is still in force regardless of whether the notice
+            // was delivered, so the safety behavior does not depend on this emit.
+        }
+    }
+    async raiseSeedRefusalAttention(slot, kind, detail) {
+        if (!this.emitAttention)
+            return;
+        try {
+            await this.emitAttention({
+                id: `credential-ledger-seed-refusal:${kind}:${slot}`,
+                title: `Credential ledger could not auto-assign a slot (${kind})`,
+                summary: `Seeding refused to guess the tenant of ${slot}: ${detail}. The slot is quarantined (excluded from balancing) until resolved.`,
+                category: 'credential-repointing',
+                priority: 'HIGH',
+                sourceContext: 'credential-location-ledger',
+            });
+        }
+        catch {
+            // @silent-fallback-ok — best-effort notice; the quarantine (the actual safety action) is
+            // already durably recorded in the ledger whether or not the notice is delivered.
+        }
+    }
+}
+//# sourceMappingURL=CredentialLocationLedger.js.map