sidekick-shared 0.27.5 → 0.28.0

package/dist/accounts.d.ts

@@ -4,10 +4,17 @@
  * Handles saving, listing, switching, syncing, and removing Claude accounts.
  * Both the VS Code extension and CLI consume this module.
  *
- * Model: the live home (`CLAUDE_CONFIG_DIR` or `~/.claude`) is the source of
- * truth for whichever account is logged in right now; every saved profile is a
- * backup that the sync core keeps fresh, because Claude Code rotates the
- * refresh token on every refresh and a stale snapshot is a dead login.
+ * Model: Claude Code rotates the refresh token on every refresh, so every
+ * refresh-token chain may have exactly one copy a `claude` process can use.
+ *
+ * - The live home (`CLAUDE_CONFIG_DIR` or `~/.claude`) is the only CLI-usable
+ *   copy of the account that is logged in right now. Its profile home holds
+ *   identity and health metadata but never a credential; Sidekick mirrors the
+ *   live credential into a private backup Claude Code never reads.
+ * - An inactive account's profile home holds its single CLI-usable copy (the
+ *   Claude login only; MCP tokens follow the live store).
+ * - Writes into the live store go through one guarded installer that refuses
+ *   downgrades, and a switch saves the outgoing login before replacing it.
  */
 import { type ResolvedActiveAccount } from './accountRegistry';
 import { type AccountHealthSource } from './accountHealth';
@@ -39,11 +46,21 @@ export interface AccountManagerResult {
 /** Store a profile's identity (`oauthAccount`) in its home and the flat backup. */
 export declare function storeClaudeProfileIdentity(uuid: string, oauthAccount: unknown): void;
 /**
- * The single chokepoint for storing a Claude credential in a profile: profile
- * home store (suffixed Keychain item on macOS, file elsewhere), the flat
- * backup, and the secret-free health sidecar.
+ * The single chokepoint for storing a Claude credential in a profile. Always
+ * writes the private backup and the secret-free health sidecar. Writes the
+ * profile-home store (suffixed Keychain item on macOS, file elsewhere) only
+ * when the account is NOT the live login: the live store is that account's one
+ * CLI-usable copy, and a second one would fight it over the refresh token.
+ * Caller holds the swap lock.
  */
+export declare function storeClaudeProfileCredentialsUnlocked(uuid: string, credentials: unknown, source: AccountHealthSource): void;
+/** {@link storeClaudeProfileCredentialsUnlocked} under the swap lock. */
 export declare function storeClaudeProfileCredentials(uuid: string, credentials: unknown, source: AccountHealthSource): void;
+/**
+ * The saved credential and identity of a profile: the fresher of its
+ * profile-home store and its private backup. Read-only — it never
+ * re-materialises a backup into a CLI-visible place.
+ */
 export declare function readStoredClaudeAccount(uuid: string): {
     credentials: unknown;
     oauthAccount: unknown;
@@ -54,37 +71,77 @@ export declare function readActiveClaudeAccount(): ActiveAccountInfo | null;
 export declare function addCurrentAccount(label?: string): AccountManagerResult;
 /**
  * Serializes live Claude credential swaps across processes so two concurrent
- * switchers cannot interleave their backup/write/rollback sequences. It cannot
- * exclude Claude Code's own writes to the live home — only our switchers. Lock
- * ordering: this lock first, the registry lock (inside setActiveSavedAccount)
- * inside it — never the reverse. Never spawn a child process while holding it.
+ * switchers cannot interleave their backup/write/rollback sequences. Claude
+ * Code's own refreshes are kept out separately by borrowing its refresh lock
+ * (claudeRefreshLock.ts). Lock ordering: this lock first, then the refresh
+ * locks, the registry lock (inside setActiveSavedAccount), and the ledger
+ * lock — never the reverse. Never spawn a `claude` process while holding it.
  */
 export declare function withClaudeAuthSwapLock<T>(operation: () => T): T;
 /**
- * Fold the live login into the saved profiles: register an unknown login
- * (label = email), refresh the matching profile's backup when the live
- * credential is newer, and re-point the active pointer at it. Caller holds the
- * swap lock. Never throws; problems land in `warnings`.
+ * Reconcile the live login with the saved profiles: finish an interrupted
+ * switch, register an unknown login (label = email), refresh the matching
+ * profile's backup when the live credential is newer, remove any CLI-usable
+ * copy of the live account from its profile home, and re-point the active
+ * pointer. Caller holds the swap lock. Never throws; problems land in
+ * `warnings`.
  */
 export declare function syncClaudeLiveStateUnlocked(source?: AccountHealthSource): ProviderSyncReport;
 /** {@link syncClaudeLiveStateUnlocked} under the swap lock. */
 export declare function syncClaudeLiveState(source?: AccountHealthSource): ProviderSyncReport;
 /**
- * Remove isolated login homes that never authenticated (the user closed the
- * browser, the login timed out) once they are older than `olderThanMs`.
+ * Remove isolated login homes that never finished: ones that never
+ * authenticated (the user closed the browser, the login timed out) once they
+ * are older than `olderThanMs`, and ones that authenticated but were never
+ * finalized (the host quit) after a day. Their Keychain item goes with them.
  * Returns the removed login ids.
  */
 export declare function cleanupAbandonedClaudeLogins(olderThanMs?: number, now?: number): string[];
+/** {@link beginClaudeKeepAlive} without taking the lease (dry runs). */
+export declare function getClaudeKeepAliveBlocker(accountId: string): string | null;
+/**
+ * Check a Claude profile for keep-alive and take its lease, both under the
+ * swap lock, so no switch can make it live (or copy it into live) while the
+ * CLI refreshes it. Pair with {@link finishClaudeKeepAlive}.
+ */
+export declare function beginClaudeKeepAlive(accountId: string, leaseMs: number): {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+/** Record what the CLI refreshed (backup + sidecar) and release the lease. */
+export declare function finishClaudeKeepAlive(accountId: string): void;
+/**
+ * Give an inactive profile a CLI-usable copy from its backup when its profile
+ * home has none (it was live when it was last seen, or a switch could not
+ * write it). User-initiated launches only; keep-alive never does this.
+ */
+export declare function restoreClaudeProfileFromBackup(accountId: string): 'restored' | 'present' | 'live' | 'none';
 export declare function switchToAccount(uuid: string, options?: SwitchAccountOptions): SwitchAccountResult;
 /** {@link switchToAccount} with the process probe off the event loop. */
 export declare function switchToAccountAsync(uuid: string, options?: SwitchAccountOptions): Promise<SwitchAccountResult>;
 /**
  * Install a saved profile's credentials into the live home without changing
  * which account is active: used right after a re-login of the live account,
- * whose freshly minted token must replace the (possibly dead) live one.
+ * whose freshly minted token must replace the (possibly dead) live one. The
+ * guard only lets a strictly fresher credential of the same account through;
+ * when live is already at least as new, nothing is written.
  */
 export declare function applyClaudeProfileToLiveHome(uuid: string): AccountManagerResult;
+/**
+ * @deprecated The home `claude` should use for the active account. The live
+ * account's profile home holds no credential, so this is the live home for the
+ * live account; kept for API compatibility.
+ */
 export declare function resolveActiveClaudeHome(): string;
+/**
+ * @deprecated Re-install the active profile's credential into the live home.
+ * It never follows the registry pointer across accounts (after a native
+ * `claude /login` the pointer can be stale): when the live login is another
+ * account it refuses — use {@link switchToAccount}. For the same account it is
+ * a guarded re-login that writes only a strictly fresher credential.
+ */
 export declare function applyActiveClaudeToLiveHome(): AccountManagerResult;
 export declare function reconcileClaudeAuthState(): void;
 export declare function removeAccount(uuid: string): AccountManagerResult;