@phnx-labs/agents-cli 1.22.104 → 1.22.106

package/dist/lib/exec-account-home.js

@@ -173,13 +173,13 @@ async function matchLegacyIdentityHome(agent, account, meta) {
  * Existing slot, then a provisionable worker slot, then a leftover `homes`
  * label, then identity match across installed homes, then fail loud.
  */
-export async function resolveNativeSpawnHome(agent, account, meta = { accounts: undefined, deviceAccounts: undefined }) {
+export async function resolveNativeSpawnHome(agent, account, meta = { accounts: undefined, deviceAccounts: undefined }, options = {}) {
     const slot = readSlots(meta)[account.id];
     if (slot && fs.existsSync(slot.slotDir)) {
         return { execHome: slot.slotDir, source: 'slot', slot };
     }
     const row = nativeRow(account.id, meta);
-    if (row && isProvisionableWorker(row)) {
+    if (!options.readOnly && row && isProvisionableWorker(row)) {
         const provisioned = provisionWorkerSlot(row);
         return { execHome: provisioned.slotDir, source: 'provisioned', slot: provisioned };
     }

package/dist/lib/exec.d.ts

@@ -244,6 +244,17 @@ export interface ExecOptions {
     launchSignedIn?: boolean | null;
     /** Precomputed account email companion to {@link launchSignedIn}. */
     launchEmail?: string | null;
+    /**
+     * Stable native-account registry id this run authenticates as (the same
+     * identity `candidateAccountKey`/`modelRefusalAccountKey` key on) —
+     * independent of `version`, which is the binary rather than the account
+     * identity for a slot launch (PHNX-3940 T5). Exported to
+     * `AGENTS_RUN_ACCOUNT_ID` and stamped on the session-actor sidecar so a
+     * later model-refusal lookup or recovery pick can resolve the exact account
+     * a session ran under, not just the version home it launched from. Absent
+     * for a run whose account identity isn't resolved at launch time.
+     */
+    accountId?: string;
 }
 /**
  * Identity a custom-harness run stamps on env / pid-registry / sidecars.
@@ -656,12 +667,27 @@ export type ClaudeRefusalAction = {
     resetsAt: Date;
 } | {
     action: 'note_out_of_credits';
+} | {
+    action: 'note_model_limit';
+    model: string;
+    family: string;
 } | {
     action: 'clear';
 } | {
     action: 'none';
 };
-export declare function classifyClaudeRunRefusal(output: string, exitCode: number): ClaudeRefusalAction;
+/**
+ * Classify a Claude run's output + exit code, model-limit refusal included.
+ * Precedence: a session-limit reset first (it carries a clock), then a
+ * clock-less billing exhaustion, then a MODEL-specific refusal ("You've
+ * reached your Fable limit…") — checked BEFORE the exit-0 clear so a model
+ * refusal that ends the run with exit 0 is never misread as a clean success
+ * that clears every other stale marker on the account. A model refusal never
+ * maps to `note_out_of_credits`/`note_session`: those are account-wide, this
+ * names one model. Only a clean run with NO refusal text clears stale
+ * markers; anything else leaves them untouched.
+ */
+export declare function classifyClaudeRunRefusal(output: string, exitCode: number, model?: string): ClaudeRefusalAction;
 /**
  * Parse Codex's usage-limit refusal reset. Codex prints
  * `ERROR: You've hit your usage limit. … try again at Sep 12th, 2026 8:32 AM.`

package/dist/lib/exec.js

@@ -44,7 +44,8 @@ import { resolveHarnessAdapter, stripForeignConfigDir } from './harness/index.js
 import { claudeWorkerLoginTrapPreflight } from './harness/adapters/claude.js';
 import { resolveConfigVersion } from './harness/exec-config-version.js';
 import { getAccountInfo } from './agents.js';
-import { getUsageLookupKey, noteClaudeSessionLimit, noteClaudeOutOfCredits, clearClaudeAccountRefusal, parseClaudeSessionLimitReset } from './accounting/usage.js';
+import { getUsageLookupKey, noteClaudeSessionLimit, noteClaudeOutOfCredits, clearClaudeAccountRefusal, parseClaudeSessionLimitReset, noteClaudeModelRefusal, clearClaudeModelRefusal, parseClaudeModelRefusal, claudeModelRefusalKey, } from './accounting/usage.js';
+import { claudeProjectDirName } from './project-key.js';
 import { bootMark, flushBootProfile } from './boot-profile.js';
 /**
  * Map a raw mode string (CLI flag, YAML field, env var) to the canonical Mode.
@@ -445,6 +446,15 @@ export function buildExecEnv(options) {
     else {
         delete result.AGENTS_EXEC_HOME;
     }
+    // Durable account identity for this run (PHNX-3940 model-refusal tracking).
+    // Cleared when absent so a run spawned from inside an account-scoped session
+    // never inherits its parent's account id.
+    if (options.accountId) {
+        result.AGENTS_RUN_ACCOUNT_ID = options.accountId;
+    }
+    else {
+        delete result.AGENTS_RUN_ACCOUNT_ID;
+    }
     // Export the run's durable name (companion to AGENT_SESSION_ID) so a
     // SessionStart hook / the agent can associate its transcript with the handle
     // the user gave the run. Only set when --name was passed.
@@ -471,7 +481,7 @@ export function ensureVendorHomeDir(agent, versionHome) {
 }
 function resolveExecConfigHome(options) {
     if (options.execHome) {
-        const resolved = options.version
+        const resolved = options.configVersion ?? options.version
             ?? resolveConfigVersion(options.agent, options.cwd || process.cwd(), options.version).version;
         return { version: resolved ?? null, versionHome: options.execHome };
     }
@@ -1430,22 +1440,31 @@ async function runInTmux(options, executable, args) {
     const name = slugifyName(`ag-${options.agent}-${idSeed}`);
     const RED = '\x1b[31m', GRAY = '\x1b[90m', OFF = '\x1b[0m';
     const NO_TMUX_TIP = `${GRAY}  This run used the opt-in tmux wrap. Re-run with --no-tmux for a direct launch, or turn the wrap off: agents config set devices.${machineId()}.tmux off${OFF}\n\n`;
+    // Read a dead pane's scrollback. Must run BEFORE killSession — capture-pane
+    // needs the session still alive (remain-on-exit keeps the dead pane readable
+    // until we tear it down). Best-effort: a missing/gone pane just yields ''.
+    // Callers thread this into SpawnResult.stdout for a GENUINELY dead pane only
+    // (positive proof from paneExitStatus) — never for the "still alive, user
+    // detached" or "outcome unknown" paths below, so an interactive detach or an
+    // unresolved tmux race can never masquerade as refusal evidence.
+    const capturePaneTail = async (pane) => {
+        if (!pane)
+            return '';
+        try {
+            const r = await runTmux({ socket, args: ['capture-pane', '-p', '-t', pane, '-S', '-200'], throwOnError: false });
+            return r.code === 0 ? formatPaneTail(r.stdout) : '';
+        }
+        catch {
+            return '';
+        }
+    };
     // Recap a dead pane's tail into THIS shell's stderr. The pane-died hook
     // detaches the client the instant the agent exits, so a fast failure (a
     // gutted install that dies with ENOENT, a bad flag, a crash on startup) would
-    // otherwise leave only a bare `[detached]` with no clue why. Must run BEFORE
-    // killSession — capture-pane needs the session still alive (remain-on-exit
-    // keeps the dead pane readable until we tear it down). Best-effort throughout.
-    const surfacePaneFailure = async (pane, status, headline) => {
+    // otherwise leave only a bare `[detached]` with no clue why.
+    const surfacePaneFailure = async (pane, status, headline, tail) => {
         if (!pane)
             return;
-        let tail = '';
-        try {
-            const r = await runTmux({ socket, args: ['capture-pane', '-p', '-t', pane, '-S', '-200'], throwOnError: false });
-            if (r.code === 0)
-                tail = formatPaneTail(r.stdout);
-        }
-        catch { /* best-effort — a missing pane just means no recap */ }
         process.stderr.write(`\n${RED}agents: ${headline} (exit ${status ?? UNKNOWN_OUTCOME_EXIT_CODE}).${OFF}\n`);
         if (tail) {
             process.stderr.write(`${GRAY}  ── last output from ${options.agent} ──${OFF}\n`);
@@ -1477,18 +1496,25 @@ async function runInTmux(options, executable, args) {
     const resolveAfterAttach = async (pane) => {
         const after = pane ? await paneExitStatus(pane, socket) : { found: false, dead: false, status: undefined };
         if (after.dead) {
+            // Positive proof of a genuinely completed pane (paneExitStatus confirmed
+            // dead) — capture its scrollback as refusal evidence for the caller
+            // (classifyClaudeRunRefusal etc.) BEFORE tearing the session down.
+            // Deliberately not done for the "alive" (detach) or "unknown" branches
+            // below: neither is a demonstrated completion, so neither may carry
+            // evidence a caller could mistake for a real refusal or success.
+            const tail = await capturePaneTail(pane);
             // Nonzero exit after attach → the agent crashed rather than the user
             // detaching cleanly (a clean detach leaves the pane ALIVE, handled below).
             // F2: for interactive runs, also recap a clean exit-0 — the harness exited
             // without error but without starting a REPL, which is still a failure.
             if (shouldRecapDeadPane(after.status, resolveInteractive(options))) {
-                await surfacePaneFailure(pane, after.status, `${options.agent} exited`);
+                await surfacePaneFailure(pane, after.status, `${options.agent} exited`, tail);
             }
             await killSession(name, socket).catch(() => { });
             // A dead pane whose status tmux never reported is UNKNOWN, not success —
             // and surfacePaneFailure already printed `exit 1` for it, so the old
             // `?? 0` made the message and the returned code disagree (EXEC-23b).
-            return { exitCode: tmuxRunExitCode(after, false), stderr: '', stdout: '' };
+            return { exitCode: tmuxRunExitCode(after, false), stderr: '', stdout: tail };
         }
         // after.dead===false, but that could be a stale/unreadable-pane result.
         // Require positive proof before keeping the session as "user detached".
@@ -1618,6 +1644,7 @@ async function runInTmux(options, executable, args) {
                 initiatedBy: resolveActor().kind,
                 phoenixId: resolveActor().phoenixId,
                 harness: customHarnessName(options),
+                accountId: options.accountId,
                 startedAtMs: Date.now(),
             });
         }
@@ -1626,18 +1653,22 @@ async function runInTmux(options, executable, args) {
     // already-dead pane — surface its output + status directly and tear down.
     const before = pane ? await paneExitStatus(pane, socket) : { found: false, dead: false, status: undefined };
     if (before.dead) {
+        // Positive proof of a genuinely completed pane — capture scrollback as
+        // refusal evidence before tearing the session down (see the matching
+        // comment in resolveAfterAttach).
+        const tail = await capturePaneTail(pane);
         // F2 (RUSH-2185 / EXEC-23a): for interactive runs, ALWAYS recap — a clean
         // exit-0 before attach means the harness has no interactive REPL and the
         // user would see only a bare `[detached]` with no clue why. For headless
         // runs the old quiet behaviour stands: exit-0 is a successful quick run.
         if (shouldRecapDeadPane(before.status, resolveInteractive(options))) {
-            await surfacePaneFailure(pane, before.status, `${options.agent} exited before it could start`);
+            await surfacePaneFailure(pane, before.status, `${options.agent} exited before it could start`, tail);
         }
         await killSession(name, socket).catch(() => { });
         // A dead pane whose status tmux never reported is an UNKNOWN outcome, not a
         // success — and the banner one line up already printed `exit 1` for it, so
         // the old `?? 0` also made the message and the returned code disagree.
-        return { exitCode: tmuxRunExitCode(before, false), stderr: '', stdout: '' };
+        return { exitCode: tmuxRunExitCode(before, false), stderr: '', stdout: tail };
     }
     await attachTmux({ socket, args: ['attach-session', '-t', name] });
     return resolveAfterAttach(pane);
@@ -1756,10 +1787,74 @@ async function emitRunLaunch(ctx) {
     }
 }
 async function spawnAgent(options) {
+    if (options.agent === 'claude' && !options.resume && !options.sessionId)
+        options = { ...options, sessionId: randomUUID() };
     const version = options.version ?? resolveVersion(options.agent, options.cwd || process.cwd());
-    if (!version || !isVersionInstalled(options.agent, version))
-        return spawnAgentLeased(options);
-    return withInstallationLease(options.agent, version, () => spawnAgentLeased(options));
+    const home = resolveExecConfigHome(options).versionHome;
+    const modelKey = claudeModelRefusalKey(options.accountId, home);
+    const transcript = options.agent === 'claude' && home && options.sessionId
+        ? path.join(home, '.claude', 'projects', claudeProjectDirName(options.cwd || process.cwd()), `${options.sessionId}.jsonl`)
+        : undefined;
+    let offset = transcript && fs.existsSync(transcript) ? fs.statSync(transcript).size : 0;
+    const observeTranscript = () => {
+        if (!transcript || !modelKey)
+            return;
+        try {
+            const size = fs.statSync(transcript).size;
+            if (size <= offset)
+                return;
+            const start = Math.max(offset, size - 64 * 1024);
+            const fd = fs.openSync(transcript, 'r');
+            const bytes = Buffer.alloc(size - start);
+            try {
+                fs.readSync(fd, bytes, 0, bytes.length, start);
+            }
+            finally {
+                fs.closeSync(fd);
+            }
+            const text = bytes.toString('utf8');
+            const lastNewline = text.lastIndexOf('\n');
+            if (lastNewline < 0)
+                return;
+            offset = start + Buffer.byteLength(text.slice(0, lastNewline + 1));
+            for (const line of text.slice(0, lastNewline).split('\n')) {
+                try {
+                    const row = JSON.parse(line);
+                    if (row.type !== 'assistant')
+                        continue;
+                    const content = Array.isArray(row.message?.content) ? row.message.content.filter((block) => block.type === 'text').map((block) => block.text ?? '').join('\n') : '';
+                    const refusal = row.isApiErrorMessage ? parseClaudeModelRefusal(content) : null;
+                    if (refusal)
+                        noteClaudeModelRefusal(modelKey, refusal.family, { family: refusal.family });
+                    else if (!row.isApiErrorMessage && row.message?.model && content.trim())
+                        clearClaudeModelRefusal(modelKey, row.message.model);
+                }
+                catch { /* Partial or non-message transcript rows provide no evidence. */ }
+            }
+        }
+        catch { /* Transcript observation must not interrupt the harness. */ }
+    };
+    const observer = transcript ? setInterval(observeTranscript, 2_000) : undefined;
+    observer?.unref();
+    try {
+        const observedOptions = options.agent === 'claude' ? { ...options, captureStdoutTail: true } : options;
+        const result = !version || !isVersionInstalled(options.agent, version)
+            ? await spawnAgentLeased(observedOptions)
+            : await withInstallationLease(options.agent, version, () => spawnAgentLeased(observedOptions));
+        observeTranscript();
+        if (options.agent === 'claude' && modelKey) {
+            const refusal = parseClaudeModelRefusal(`${result.stderr}\n${result.stdout}`);
+            if (refusal) {
+                noteClaudeModelRefusal(modelKey, refusal.family, { family: refusal.family });
+                return { ...result, exitCode: result.exitCode || 1 };
+            }
+        }
+        return result;
+    }
+    finally {
+        if (observer)
+            clearInterval(observer);
+    }
 }
 async function spawnAgentLeased(options) {
     bootMark('spawn-agent:enter');
@@ -1987,6 +2082,7 @@ async function spawnAgentLeased(options) {
                 initiatedBy: resolveActor().kind,
                 phoenixId: resolveActor().phoenixId,
                 harness: customHarnessName(options),
+                accountId: options.accountId,
                 startedAtMs: Date.now(),
             });
         }
@@ -2193,12 +2289,27 @@ const OUT_OF_CREDITS_PATTERNS = [
 export function detectOutOfCredits(text) {
     return OUT_OF_CREDITS_PATTERNS.some(pattern => pattern.test(text));
 }
-export function classifyClaudeRunRefusal(output, exitCode) {
+/**
+ * Classify a Claude run's output + exit code, model-limit refusal included.
+ * Precedence: a session-limit reset first (it carries a clock), then a
+ * clock-less billing exhaustion, then a MODEL-specific refusal ("You've
+ * reached your Fable limit…") — checked BEFORE the exit-0 clear so a model
+ * refusal that ends the run with exit 0 is never misread as a clean success
+ * that clears every other stale marker on the account. A model refusal never
+ * maps to `note_out_of_credits`/`note_session`: those are account-wide, this
+ * names one model. Only a clean run with NO refusal text clears stale
+ * markers; anything else leaves them untouched.
+ */
+export function classifyClaudeRunRefusal(output, exitCode, model) {
     const sessionLimitReset = parseClaudeSessionLimitReset(output);
     if (sessionLimitReset)
         return { action: 'note_session', resetsAt: sessionLimitReset };
     if (detectOutOfCredits(output))
         return { action: 'note_out_of_credits' };
+    const modelRefusal = parseClaudeModelRefusal(output);
+    if (modelRefusal) {
+        return { action: 'note_model_limit', model: model ?? modelRefusal.family, family: modelRefusal.family };
+    }
     if (exitCode === 0)
         return { action: 'clear' };
     return { action: 'none' };
@@ -2500,29 +2611,41 @@ export async function runWithFallback(options) {
         // harnesses), so one path notes either. Decisions extracted + unit-tested in
         // classify{Claude,Codex}RunRefusal.
         const refusal = agent === 'claude'
-            ? classifyClaudeRunRefusal(output, result.exitCode ?? 1)
+            ? classifyClaudeRunRefusal(output, result.exitCode ?? 1, execOpts.model)
             : agent === 'codex'
                 ? classifyCodexRunRefusal(output, result.exitCode ?? 1)
                 : null;
         const sessionLimitReset = refusal?.action === 'note_session' ? refusal.resetsAt : null;
         if (refusal && version && refusal.action !== 'none') {
-            const account = await getAccountInfo(agent, getVersionHomePath(agent, version));
+            // Resolve the account from the HOME this attempt actually authenticated
+            // from — execHome (a slot dir, PHNX-3940 T5) or configVersion wins over
+            // the bare managed-binary version home. Reading `getVersionHomePath(agent,
+            // version)` unconditionally attributed a refusal to the wrong account for
+            // every account-slot / configVersion launch, since `version` there is the
+            // BINARY, not the credential's home.
+            const { versionHome: refusalHome } = resolveExecConfigHome(execOpts);
+            const account = await getAccountInfo(agent, refusalHome ?? getVersionHomePath(agent, version));
             const usageKey = getUsageLookupKey(account);
-            if (usageKey) {
+            if (usageKey && refusal.action !== 'note_model_limit') {
                 if (refusal.action === 'note_session')
                     noteClaudeSessionLimit(usageKey, refusal.resetsAt);
                 else if (refusal.action === 'note_out_of_credits')
                     noteClaudeOutOfCredits(usageKey);
-                else if (refusal.action === 'clear')
+                else if (refusal.action === 'clear' && !resolveInteractive(execOpts))
                     clearClaudeAccountRefusal(usageKey);
             }
         }
-        if (result.exitCode === 0 && !sessionLimitReset)
+        // A model-limit refusal commonly ends the CLI turn with exit 0 (Claude
+        // just refuses to keep going on that model rather than crashing) — so,
+        // like a session-limit reset, it must not be read as a clean success that
+        // short-circuits the cascade before the fallback chain ever runs.
+        const modelLimited = refusal?.action === 'note_model_limit';
+        if (result.exitCode === 0 && !sessionLimitReset && !modelLimited)
             return 0;
         const isLast = i === chain.length - 1;
         if (isLast)
             return result.exitCode || 1;
-        if (!sessionLimitReset && !detectRateLimit(result.stderr) && !detectRateLimit(result.stdout)) {
+        if (!sessionLimitReset && !modelLimited && !detectRateLimit(result.stderr) && !detectRateLimit(result.stdout)) {
             return result.exitCode;
         }
         const next = chain[i + 1];

package/dist/lib/models.d.ts

@@ -187,7 +187,7 @@ export interface ConfiguredModel {
  * Each layer is a real source the agent consults; `version` must be concrete.
  * Returns null only when the agent exposes no model catalog at all.
  */
-export declare function resolveConfiguredModel(agent: AgentId, version: string): ConfiguredModel | null;
+export declare function resolveConfiguredModel(agent: AgentId, version: string, home?: string): ConfiguredModel | null;
 /**
  * Join the identity cluster — `agent@version · model · account` — with a dim
  * separator, dropping empty pieces. Pieces are pre-colored by the caller so the

package/dist/lib/models.js

@@ -1007,11 +1007,11 @@ export function resolveEffectiveModel(agent, version, requested) {
  * Each layer is a real source the agent consults; `version` must be concrete.
  * Returns null only when the agent exposes no model catalog at all.
  */
-export function resolveConfiguredModel(agent, version) {
+export function resolveConfiguredModel(agent, version, home) {
     const runModel = resolveRunDefaults(agent, version).model;
     if (runModel && runModel.trim() !== '')
         return { model: runModel, source: 'run-default' };
-    const nativeModel = readNativeConfigModel(agent, version);
+    const nativeModel = readNativeConfigModel(agent, version, home);
     if (nativeModel)
         return { model: nativeModel, source: 'config' };
     const catalog = getModelCatalog(agent, version);
@@ -1026,9 +1026,9 @@ export function resolveConfiguredModel(agent, version) {
  * (e.g. `~/.agents/.history/versions/claude/<ver>/home/.claude/settings.json`).
  * A missing/malformed file is a fall-through, not an error.
  */
-function readNativeConfigModel(agent, version) {
+function readNativeConfigModel(agent, version, home) {
     try {
-        const settingsPath = path.join(getVersionHomePath(agent, version), agentConfigDirName(agent), 'settings.json');
+        const settingsPath = path.join(home ?? getVersionHomePath(agent, version), agentConfigDirName(agent), 'settings.json');
         const parsed = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
         return typeof parsed.model === 'string' && parsed.model.trim() !== '' ? parsed.model : null;
     }

package/dist/lib/session/actor-sidecar.d.ts

@@ -14,18 +14,10 @@ export interface SessionActorRecord {
     phoenixId?: string;
     /** Effective permissions mode used by the launcher. */
     mode?: SessionRunMode;
-    /**
-     * The agents-cli version-home id this session launched under (e.g. `2.1.207`,
-     * codex `0.146.0`) — the same namespace `listInstalledVersions` /
-     * `collectRunCandidates` use, so a native resume can pin the exact origin
-     * version. Recorded at launch by the SessionStart hook (from `AGENTS_RUN_VERSION`),
-     * because a harness coins its real session id only AFTER spawn — the same reason
-     * `mode` rides the hook rather than a spawn-time `writeSessionActorRecord`. Joined
-     * onto the session index at scan time so a session whose transcript carries no
-     * embedded/derivable version (codex's `.codex-homes/<version>/` layout) no longer
-     * degrades native resume to `/continue` for lack of a recorded origin (PHNX-3626).
-     */
+    /** Installed executable label at launch; provenance only, never account identity. */
     version?: string;
+    /** Credential account used at launch, independent of the installed executable. */
+    accountId?: string;
     /**
      * Custom harness / profile name when launched via `agents run <profile>`
      * (e.g. `deepseek`). Joined onto the session index at scan time so a

package/dist/lib/session/actor-sidecar.js

@@ -42,6 +42,7 @@ function hasRecordData(record) {
         || typeof record.phoenixId === 'string'
         || typeof record.mode === 'string'
         || typeof record.version === 'string'
+        || typeof record.accountId === 'string'
         || typeof record.harness === 'string'
         || (Array.isArray(record.aliases) && record.aliases.some(alias => typeof alias === 'string'));
 }
@@ -69,6 +70,7 @@ export function writeSessionActorRecord(record) {
         writeRecord({
             ...previous,
             ...record,
+            accountId: previous?.accountId ?? record.accountId,
             aliases: normalizedAliases([...(previous?.aliases ?? []), ...(record.aliases ?? [])]),
         });
     }
@@ -88,6 +90,7 @@ export function writeSessionAliasRecord(sessionId, alias) {
             phoenixId: previous?.phoenixId,
             mode: previous?.mode,
             version: previous?.version,
+            accountId: previous?.accountId,
             harness: previous?.harness,
             aliases: normalizedAliases([...(previous?.aliases ?? []), alias]),
             startedAtMs: previous?.startedAtMs ?? Date.now(),

package/dist/lib/session/claude-accounts.d.ts

@@ -1,63 +1,3 @@
-/**
- * Which Claude account produced a transcript.
- *
- * A Claude `.jsonl` records `sessionId`, `cwd`, `version`, `gitBranch` and per-message
- * `usage`, but carries **no account identity** — no `accountUuid`, no
- * `organizationUuid`, no email. What agents-cli does have is the version layout: every
- * installed version gets its own home with its own `.claude.json` (`CLAUDE_CONFIG_DIR`
- * is swapped per version, see lib/exec.ts), so a home identifies an account.
- *
- * This matters because the default run strategy is `balanced` (lib/rotate.ts), which
- * sprays sessions across every signed-in account. Before this module the scanner
- * resolved ONE email process-globally and stamped it on every Claude session, so a
- * machine with several accounts reported all of its history under whichever one
- * happened to resolve first.
- *
- * Grouping is keyed on the **org** (`usageKey`), never the email: two orgs under one
- * email (a Team seat and a personal Max plan) are separate quota buckets and must stay
- * distinct — the same invariant `candidateIdentity` enforces in lib/rotate.ts.
- *
- * ## Evidence tiers
- *
- * Attribution is a pure function of (path, recorded version). It performs no per-file
- * I/O and does not need the transcript to still exist, which is what lets the v33
- * migration backfill already-indexed rows without re-parsing anything.
- *
- * 1. **The path names a home we can identify.** Strongest: the file physically lives in
- *    that home, including a retired `trash/` snapshot, which keeps its `.claude.json`.
- * 1b. **The path names a home that exists but is signed out.** Dark, named after that
- *    home. The location proves which config dir Claude used, so this deliberately beats
- *    a recorded version — attributing it to some other version's account would be a
- *    guess dressed as evidence.
- * 2. **The path is outside every known home, and the row records a version.** Resolve
- *    that version's own home. Covers the mutable `~/.claude` symlink and the routine
- *    archives under `<historyDir>/runs` that `readRoutineArchiveMeta` feeds in. The
- *    symlink's target moves with `agents use`, so "whatever it points at now" is weak
- *    evidence for old rows: on the machine this was developed against only 684 of 1,334
- *    such rows came from the version the symlink currently names, and 322 came from
- *    versions belonging to a *different* org.
- * 3. **Under the symlink with no recorded version at all.** Its current target is the
- *    only evidence there is, and the bucket says so via `evidence`. A version that IS
- *    recorded but resolves to no home stops at tier 2 and stays dark — it never
- *    reaches here.
- * 4. **None of the above.** An explicitly dark bucket, labelled with why. Never folded
- *    into a real account and never dropped.
- *
- * ## Harness scope: Claude only, deliberately
- *
- * Attribution is implemented for Claude and no other harness. It depends on the
- * per-version home carrying an `oauthAccount` in `.claude.json`, which is what makes a
- * home equal an account. The other harnesses do have per-version credential files
- * (`CREDENTIAL_FILE_SEGMENTS` in lib/agents.ts), so the mechanism generalizes — codex
- * stores an `auth.json` JWT, gemini a `google_accounts.json` — but each needs its own
- * identity extractor and its own notion of a quota bucket, and none of them has the
- * two-orgs-one-email problem that motivated keying on the org here.
- *
- * Until that lands, a non-Claude session has a NULL `account_key` and rolls up under
- * `unattributed:<agent>` — named after its harness rather than implying we tried and
- * failed. `--by account` on `agents insights cost` / `agents insights output` therefore reports Claude
- * accounts plus one bucket per other harness.
- */
 /** The account a transcript is attributed to. */
 export interface ClaudeAccountBucket {
     /**
@@ -84,7 +24,7 @@ interface HomeEntry {
 }
 /** Resolver over the Claude homes present on this machine. */
 export interface ClaudeAccountIndex {
-    /** Version- and trash-home prefixes, longest first. Excludes the `~/.claude` symlink. */
+    /** Version-, account-slot-, and trash-home prefixes, longest first. Excludes the `~/.claude` symlink. */
     entries: HomeEntry[];
     /**
      * Config-dir prefixes of homes that exist but carry no `oauthAccount`. Kept
@@ -102,6 +42,15 @@ export interface ClaudeAccountIndex {
      * as dark rather than guessed.
      */
     byVersion: Map<string, ClaudeAccountBucket | 'ambiguous'>;
+    /**
+     * Account-slot id (`<historyDir>/accounts/claude/<accountId>/`, PHNX-3940) →
+     * the identity read from that slot's own `.claude.json`. A slot's identity is
+     * proven the same way a version home's is — tier 1 evidence, see
+     * {@link resolveClaudeAccount} — so this map exists only to let a launch-
+     * recorded accountId (once the actor sidecar carries one) resolve straight to
+     * a bucket without re-deriving it from a path.
+     */
+    byAccountId: Map<string, ClaudeAccountBucket>;
     /** Whatever `~/.claude` points at right now; tier-3 evidence only. */
     symlinkBucket: ClaudeAccountBucket | null;
     /** Literal prefix of the live symlinked config dir. */
@@ -113,16 +62,6 @@ export interface ClaudeAccountIndex {
  * its version was rotated out stays attributable.
  */
 export declare function buildClaudeAccountIndex(): ClaudeAccountIndex;
-/**
- * The account bucket a transcript belongs to. `recordedVersion` is the Claude CLI
- * version stored on the session row (`sessions.version`), which is what disambiguates
- * rows sitting under the mutable `~/.claude` symlink.
- *
- * Never returns null: a transcript that matches no known home resolves to an
- * explicitly dark bucket rather than being dropped or folded into a real account.
- * Backup mirrors (`<historyDir>/backups/claude/<stamp>/projects/…`) carry no
- * `.claude.json` of their own, so they resolve by recorded version like any other
- * out-of-home path, and go dark only when that version names no home.
- */
-export declare function resolveClaudeAccount(index: ClaudeAccountIndex, filePath: string, recordedVersion?: string | null): ClaudeAccountBucket;
+/** Resolve a quota bucket without replacing recorded login provenance. */
+export declare function resolveClaudeAccount(index: ClaudeAccountIndex, filePath: string, recordedVersion?: string | null, launchAccountId?: string | null): ClaudeAccountBucket;
 export {};