@bridge4dev/runner 0.65.1 → 0.67.0

package/dist/claude-homes.d.ts

@@ -0,0 +1,433 @@
+import { type ClaudeIdentity } from './agent-auth.js';
+import { type UsageReading, type UsageRow, type UsageSignature } from './adapters/claude-usage.js';
+import { AccountError, isAccountId } from './login-marks.js';
+/**
+ * Several Claude logins on one machine – one HOME per account (#422, D1).
+ *
+ * An account is a small directory of its own: its login (`.credentials.json`)
+ * and the CLI's working files (`.claude.json` – where the last measured limits
+ * live – `sessions/`, `backups/`). Everything else is a link into the machine's
+ * `~/.claude`: the transcripts (without them no conversation resumes across
+ * accounts), settings, plugins, agents, commands, hooks, skills. Switching is
+ * choosing which home the NEXT session starts with – `CLAUDE_CONFIG_DIR` in the
+ * session's own environment, never in the daemon's (risk К1 of the plan).
+ *
+ * The login of this machine is the default home, `~/.claude`. It is the first
+ * row, it cannot be forgotten, and while it is active nothing here sets any
+ * variable – the behaviour is exactly the pre-#422 one. No code in this module
+ * writes, moves or deletes the machine's own login file: the one legitimate way
+ * to touch it stays the person's «Log in again» on that row, which is the old
+ * sign-in path in `auth-relay.ts`, not this file.
+ *
+ * NOT ONE COPY of a login file, by construction rather than by agreement. The
+ * CLI's token-refresh lock is taken by the PATH of the file, so a copy in a
+ * second home is a second holder of a one-time refresh token – the copy that
+ * signed out 47 agents and four sessions on 08.09.2026 (gotcha 460). Every
+ * login here exists in exactly one place; a login is only ever moved into its
+ * home by `rename`, and a `rename` that would have to cross filesystems is
+ * refused instead of falling back to a copy.
+ *
+ * Proven live on this machine before a line of it was written (S1 item 1,
+ * 17.09.2026, CLI 2.1.273, SDK 0.3.226): a session started through the Agent
+ * SDK with `CLAUDE_CONFIG_DIR` in `env` ran under that home's subscription, its
+ * transcript landed in the machine's `projects/` through the link, and the
+ * same session resumed under the machine login – a different subscription –
+ * and back again, with its context.
+ */
+/** Where the saved homes live – next to the runner's other private state. */
+export declare function claudeHomesDir(): string;
+/**
+ * The machine's own Claude home. `os.homedir()` rather than anything cleverer:
+ * it is what the CLI itself uses when no `CLAUDE_CONFIG_DIR` is set, which is
+ * exactly the definition of «the machine login».
+ */
+export declare function machineHome(homedir?: string): string;
+/** The id format and the refusal live beside the machine row's id – shared by both agents. */
+export { AccountError, isAccountId };
+/** The home of a saved account. Throws on anything that is not an account id. */
+export declare function accountHome(id: string): string;
+/**
+ * What a saved home reaches through a link rather than owning (R20).
+ *
+ * `projects` is the one that must never be missing: it is where transcripts
+ * live, and a session resumes only from the home it can see them in. The rest
+ * is parity with the terminal – the machine's settings (hooks, the search
+ * guard, enabled plugins), its plugins, agents, commands, hooks and skills.
+ * Deliberately NOT here: `.credentials.json` and `.claude.json` (they are the
+ * account), and the CLI's per-process scratch (`sessions`, `session-env`,
+ * `shell-snapshots`, `backups`, …), which it recreates on its own.
+ */
+export declare const SHARED_ENTRIES: readonly ["projects", "settings.json", "settings.local.json", "CLAUDE.md", "plugins", "agents", "commands", "hooks", "skills"];
+export interface SharedLinkChange {
+    name: string;
+    action: 'linked' | 'relinked' | 'displaced' | 'dropped';
+    /** Where a file that stood in place of the link was moved to. */
+    displacedTo?: string;
+}
+/**
+ * Create and repair the links of a saved home into the machine's `~/.claude`.
+ *
+ * A link is set only where its target exists; `projects` is the exception and
+ * gets its target created, because a home without it would quietly start a
+ * transcript directory of its own and every later resume across accounts would
+ * fail to find the conversation.
+ *
+ * A link the CLI replaced with a real file or directory (an atomic write of
+ * `settings.json` does exactly that) is NOT silently re-linked: the thing in
+ * its place may be the only copy of what was written through it. It is moved
+ * aside under a dated name and logged, and the link is put back.
+ *
+ * Never follows a link to remove anything, never writes into the machine home
+ * beyond creating its empty `projects/`.
+ */
+export declare function ensureSharedLinks(home: string, machine?: string): SharedLinkChange[];
+/**
+ * Seed a home's `.claude.json` with the machine's configuration (R20).
+ *
+ * A home without the file gets one. A home WITH one (a login moved in from
+ * elsewhere) gets only the keys it does not have yet, project by project – its
+ * own identity and anything it configured for itself stay as they are.
+ *
+ * Only for a home no CLI is running in: the CLI rewrites this file on its own
+ * schedule, and a write racing it would lose one side. That is why it runs when
+ * a home is created or moved in, and not at every session start.
+ */
+export declare function ensureHomeConfig(home: string, machineConfig?: string): 'created' | 'merged' | 'unchanged';
+/** What `claude auth status` says about a home – without a verdict on the login. */
+export interface AccountIdentity {
+    email?: string;
+    orgId?: string;
+    orgName?: string;
+    plan?: string;
+}
+/** Runs `claude auth status` in a home. Replaced only by tests. */
+export type IdentityRunner = (home: string | null) => Promise<AccountIdentity | null>;
+/**
+ * The environment `claude auth status` runs with (R14) – and, since S2, every
+ * CLI run that works in a home as that home's own account: the sign-in through
+ * `agent_account_login_start` uses it too (§8), for the reason below.
+ *
+ * `CLAUDE_CONFIG_DIR` of the home, or none for the machine, and never the
+ * operator's `CLAUDE_CODE_OAUTH_TOKEN`: the CLI puts that variable above every
+ * login file, so on a machine that has one every home would answer with the
+ * token's blind identity – no e-mail, no plan, the same for all of them.
+ */
+export declare function identityProbeEnv(home: string | null, base?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+/** `claude auth status --json` → identity. `loggedIn: false` is no identity at all. */
+export declare function parseAuthStatus(output: string): AccountIdentity | null;
+export declare function setIdentityRunner(run: IdentityRunner | null): void;
+/** Ask a home who it is. Only the four callers R14 names reach this. */
+export declare function readAccountIdentity(home: string | null): Promise<AccountIdentity | null>;
+/** Forget remembered misses – tests. */
+export declare function resetIdentityMisses(): void;
+/**
+ * Who a row is, from the cache or – when that is unknown, old, or contradicted by
+ * the home – from `claude auth status` in its home, persisted (R14).
+ *
+ * A probe that answers nothing keeps what was known: a CLI that timed out once
+ * must not turn a named account into «card not filled». And it is remembered for
+ * a while, so a home with no identity to give is not asked at every session start.
+ */
+export declare function refreshAccountIdentity(id: string, options?: {
+    force?: boolean;
+}): Promise<ClaudeIdentity | null>;
+/** What one credentials file says, before any fallback is consulted. */
+export interface CredentialVerdict {
+    status: 'ok' | 'expired' | 'missing' | 'unknown';
+    expiresAt?: string;
+    detail?: string;
+    /**
+     * May a token this runner captured answer instead? Only where the pre-#422
+     * verdict consulted it: no file, nothing recognisable in it, or a dead login.
+     * Never over a file we could not parse or could not read.
+     */
+    fallbackEligible: boolean;
+}
+/**
+ * Judge a Claude credentials file – moved here unchanged from `claudeAuthStatus`
+ * so a saved home and the machine are judged by the same lines (#422 R14).
+ *
+ * `expiresAt` is NOT the login. It is the expiry of a short-lived access token
+ * (~8 hours on a live file), and next to it sits `refreshToken` with
+ * `refreshTokenExpiresAt` ~26 days out, which the CLI spends silently on its
+ * next run. Judging the login by `expiresAt` alone is why every server nobody
+ * had touched since the morning reported "login expired — re-login needed"
+ * over a login that was good for another three weeks (#121). Codex has carried
+ * exactly this guard since day one (`readCodexCredential`); Claude did not.
+ *
+ * Deliberately NOT asking the CLI. `claude auth status --json` looks like an
+ * arbiter and is not one: measured live (SDK binary 2.1.218), it answers
+ * `loggedIn: true` for a credential whose access token has expired AND which
+ * carries no refresh token at all — i.e. for a genuinely dead login. It never
+ * leaves the machine, so it cannot see a server-side revocation either. It
+ * would have cost a ~800 ms / ~300 MB subprocess per poll under `MemoryMax=2G`
+ * (gotcha #100) and echoed the account's e-mail and org name to every member of
+ * the organization, in exchange for no truth at all. A revoked login is caught
+ * instead by the refusal marks — from a real refusal, not a guess.
+ */
+export declare function judgeCredentialFile(file: string): CredentialVerdict;
+/** The verdict on one row, as the panel and the list both read it. */
+export interface ClaudeLoginStatus {
+    status: 'ok' | 'expired' | 'missing' | 'unknown';
+    expiresAt?: string;
+    detail?: string;
+}
+/**
+ * The machine row: the pre-#422 verdict, word for word.
+ *
+ * The operator's variable first, then the credentials file, then a token this
+ * runner captured – the LAST word, never the first. Read from disk rather than
+ * from the environment, so `doctor` (a different process, which never applied
+ * it) gives the same verdict as the daemon.
+ *
+ * One change, from S1 item 3: a refusal no longer DISCARDS the captured token
+ * (the old discard erased the whole file, and with it every saved account). The
+ * refusal is kept as a mark instead, and a token captured after it outranks it.
+ */
+export declare function machineLoginStatus(homedir?: string): ClaudeLoginStatus;
+/**
+ * Do the machine's Claude settings – which every saved home reads through its
+ * link – carry a credential that outranks a home's own login?
+ *
+ * `withAccountHome` takes the operator's token out of the PROCESS environment,
+ * but a settings file with `env: { CLAUDE_CODE_OAUTH_TOKEN }`, an API key or an
+ * `apiKeyHelper` puts one back inside the CLI, and a switch of account would
+ * then be a silent no-op under a green verdict – #121 once more (К14, found by
+ * the independent check of S1).
+ */
+export declare function machineSettingsOverrideLogin(machine?: string): boolean;
+/**
+ * A saved row: its own file and nothing else (R14).
+ *
+ * No operator variable and no captured token – a session under a saved account
+ * has both taken out of its environment, so neither can make this row green.
+ * Anything short of a live login in the file is `expired`: the row stays in the
+ * list with that mark (D2), and «missing» would read as «never added».
+ */
+export declare function savedLoginStatus(id: string): ClaudeLoginStatus;
+/**
+ * A session under this account was refused (D2): mark the row, remove nothing.
+ *
+ * By the id of the account the SESSION ran under, not «whatever is active now»
+ * (R14): a session started under A and refused after the machine was switched to
+ * B says nothing about B.
+ */
+export declare function markLoginExpired(id: string): void;
+/** The account worked again. Writes only when there was a mark to clear. */
+export declare function clearLoginExpired(id: string): void;
+/**
+ * The account the next session starts under. Absent pointer: the machine login,
+ * which is how a pre-#422 file reads.
+ *
+ * A pointer to a row or a home that is gone reads as the machine too, and says
+ * so once – sessions and the verdict then agree on the same login instead of
+ * one of them running under a home the other cannot see.
+ */
+export declare function activeAccountId(): string;
+/** Make a row active. `activate` leaves the usage cache alone: keys keep accounts apart (R16). */
+export declare function setActiveAccount(id: string): string;
+/** The account a session runs under – captured at its start and kept to its end (R14, R16). */
+export interface SessionAccount {
+    id: string;
+    kind: 'machine' | 'saved';
+    /** `CLAUDE_CONFIG_DIR`; null for the machine login. */
+    home: string | null;
+    email?: string;
+    orgId?: string;
+    orgName?: string;
+    plan?: string;
+}
+/** Who a row is, for the verdict's `activeAccount` (§8) – from what is known, no CLI. */
+export declare function readActiveAccountSummary(id: string): {
+    id: string;
+    email?: string;
+    orgId?: string;
+};
+/**
+ * Which home a one-shot run of the agent should use – the active account, read
+ * only: no link repair, no identity. For the commit-message run, which is
+ * Claude working as the machine's active account too (found by the independent
+ * check of S1: it kept running as the machine login after a switch).
+ */
+export declare function activeAccountHome(): Pick<SessionAccount, 'kind' | 'home'>;
+/**
+ * The active account, ready for a session to start under.
+ *
+ * A saved home has its links re-asserted first: a link the CLI replaced with a
+ * file since the last session is repaired before this session can write through
+ * the gap (it would otherwise resume nothing and share nothing).
+ */
+export declare function resolveSessionAccount(): SessionAccount;
+/**
+ * The environment of a process that works AS this account.
+ *
+ * For a saved account: its home, and nothing that outranks the home. The CLI
+ * puts `CLAUDE_CODE_OAUTH_TOKEN` above every login file, so with the operator's
+ * token left in, switching would be a silent no-op under a green verdict – #121
+ * again (К14). The API keys go for the same reason.
+ *
+ * For the machine login: the input as it was, minus a `CLAUDE_CONFIG_DIR` that
+ * would point it elsewhere – the pre-#422 environment.
+ */
+export declare function withAccountHome<T extends Record<string, string | undefined>>(env: T, account: Pick<SessionAccount, 'kind' | 'home'>): T;
+/**
+ * Who a home's `/usage` reading belongs to, read right after the probe (S1 item 5).
+ *
+ * `accountUuid` is where the CLI itself signs its figures; `organizationUuid` is
+ * the same key `claude auth status` calls `orgId` (checked on both homes of this
+ * machine, 17.09.2026). An internal file, so best-effort: nothing read, nothing
+ * signed.
+ */
+export declare function usageSignature(account: Pick<SessionAccount, 'home'>): UsageSignature;
+/**
+ * The subscription a home's own file names at this moment (S2, found by the
+ * independent check): a live session signs its limits with the subscription it
+ * STARTED under, and has to notice when somebody signed the home in to another
+ * one – the CLI moves the running process onto the new login by path (gotcha
+ * 531). Cheap enough for every frame: a `stat`, and a parse only after a write.
+ */
+export declare function currentHomeOrgId(home: string | null): string | undefined;
+/**
+ * The limits the CLI last measured in a home, from its own `.claude.json` (R19).
+ *
+ * Only for the line «when measured»: an internal file, rewritten by any update
+ * of the CLI (§11). Accepted only when it is signed by the account the same file
+ * says it belongs to – half-way through a re-login the two can disagree, and a
+ * number under the wrong name is worse than none.
+ */
+export declare function readLastUsage(home: string | null): UsageReading | null;
+/** A session's process is starting under this account. */
+export declare function noteSessionAccount(sessionId: string, accountId: string): void;
+/** That process is gone. */
+export declare function releaseSessionAccount(sessionId: string): void;
+/** Accounts some live session process is running under right now. */
+export declare function liveAccountIds(): Set<string>;
+/**
+ * Finish a swap of homes the previous daemon did not finish (R15).
+ *
+ * A replacement moves the old home to `<id>.retired-<ts>` for the length of one
+ * call: long enough to put it back if the new login cannot take its place. A
+ * daemon that died inside that call leaves the name behind. If `<id>` is there,
+ * the swap went through and the retired home is the replaced login – removed. If
+ * `<id>` is missing, the swap did not happen – the retired home is put back,
+ * because it is the row's only login. Run at daemon start, when nothing runs.
+ */
+export declare function recoverInterruptedSwaps(): string[];
+/** One row of the list, without a secret or a path to one (§8 `Card`). */
+export interface AccountCard {
+    id: string;
+    kind: 'machine' | 'saved';
+    email?: string;
+    orgId?: string;
+    orgName?: string;
+    plan?: string;
+    /** Best-effort, from the home's `.claude.json` – e.g. `default_claude_max_20x`. */
+    tier?: string;
+    /** Always on a saved row; the machine login was never «added». */
+    addedAt?: string;
+    active: boolean;
+    login: 'ok' | 'expired' | 'unknown';
+    loginUntil?: string;
+    usage?: UsageRow[];
+    usageMeasuredAt?: string;
+    /** A saved row of the same subscription as the machine login (§2, scenarios). */
+    sameAsMachine?: true;
+}
+export interface AccountList {
+    accounts: AccountCard[];
+    active: string;
+}
+/**
+ * The list, from what is already known – no subprocess (§8 `agent_accounts`
+ * reads this after `listAccounts` refreshed the identities).
+ */
+export declare function buildAccountList(homedir?: string): AccountList;
+/**
+ * The list of Claude accounts on this machine (§8 `agent_accounts`).
+ *
+ * `probeIdentity` is the one place in the product where `claude auth status`
+ * runs on request (R14 a): home by home, one at a time, and only for a row whose
+ * known identity is older than its login file or than a few hours. Never from
+ * the minute poll – that reads the panel verdict, which asks no CLI.
+ */
+export declare function listAccounts(options?: {
+    probeIdentity?: boolean;
+}): Promise<AccountList>;
+/**
+ * A fresh home for a sign-in that has not happened yet (§8 `target: 'saved'`).
+ *
+ * Links and config first, so the CLI that signs in here writes its identity
+ * into a file that already has the machine's configuration. Hidden by its name:
+ * the list never shows a staging home, and an abandoned one older than an hour
+ * is removed the next time somebody starts a sign-in.
+ */
+export declare function prepareStagingHome(): string;
+/**
+ * Remove every staging home, whatever its age – at daemon start, and only there.
+ *
+ * A sign-in whose code was accepted leaves the relay before its home is adopted
+ * (the identity is asked first, and waits in the machine-wide queue). A daemon
+ * that stops in that moment – «Update runner», a restart, an OOM – leaves a live
+ * login in a hidden home nobody lists, forgets or adopts; the hourly sweep in
+ * `prepareStagingHome` reaches it only when somebody next signs in (found by the
+ * independent check of S2). At start nothing can be adopting yet, so all of them go.
+ */
+export declare function discardAbandonedStagingHomes(): string[];
+/** Throw a sign-in away, whatever state it reached – it may hold a login nobody adopted. */
+export declare function discardStagingHome(dir: string): void;
+export interface AdoptResult {
+    account: AccountCard;
+    active: string;
+    /** The saved row whose login this sign-in replaced – same subscription (D19). */
+    replaced?: string;
+}
+/**
+ * A sign-in in a staging home succeeded: make it a saved account (§8
+ * `agent_account_login_code`).
+ *
+ * One subscription – one row (D19, R1). Identity is asked once, in the staging
+ * home, BEFORE anything moves (R14 b). A known `orgId` that a saved row already
+ * has REPLACES that row: the new login takes the row's id and `addedAt` (marks
+ * and a live session's reading are keyed by the id, R15) and the old login is
+ * deleted. An unknown `orgId` merges with nothing («card not filled»). The
+ * machine row takes no part: it is a different file, and a saved row of the same
+ * subscription is marked `sameAsMachine` instead of merged.
+ *
+ * A session running under the replaced row moves onto the new login at its next
+ * token refresh – the CLI finds its home by PATH, and the path now holds the new
+ * login. The plan (R15) asked to keep the old home renamed while such a session
+ * lives, «because the CLI writes its refreshed token into it»; the independent
+ * check of S1 read the CLI and showed it does not – a renamed home is never
+ * touched again, and keeping it would only keep an unused grant on disk. Both
+ * logins are of ONE subscription (that is what made them the same row), so the
+ * session keeps its account.
+ *
+ * Every move is a `rename`; the login is never in two places. A swap that cannot
+ * finish is undone – the old login goes back where it was. The row is recorded
+ * BEFORE a new home is moved into place, so a failed write never leaves a login
+ * nobody can list or forget. The signed-in row becomes active (R15).
+ */
+export declare function adoptLoginResult(stagingDir: string): Promise<AdoptResult>;
+/**
+ * Bring a home that already holds a login into the store – by rename (D17, R7).
+ *
+ * For the one login this plan names: the probe's `/root/.probe-422/login/home`.
+ * Refused, rather than done by copy, when the rename would cross filesystems.
+ * Refused for the machine home and for anything already in the store, whatever
+ * the spelling of the path. Refused when a saved row of the same subscription
+ * exists (one subscription – one row, and nothing here is allowed to delete a
+ * login to make room). Recorded before it moves; never activates.
+ */
+export declare function importLoginHome(source: string): Promise<AccountCard>;
+/**
+ * Forget a saved account: its home goes, its record goes (§8 `agent_account_forget`).
+ *
+ * The machine row cannot be forgotten. A row a live session runs under is
+ * refused – its process writes into that home until it ends. `rmSync` removes
+ * the links of the home as links: nothing in `~/.claude` is followed or touched.
+ * Forgetting the active row makes the machine login active.
+ */
+export declare function forgetAccount(id: string): {
+    active: string;
+};
+//# sourceMappingURL=claude-homes.d.ts.map