opencode-auth-load-balancer 0.5.1 → 0.6.0

package/dist/login-health.d.ts

@@ -0,0 +1,12 @@
+/** A row's login health for the dashboards: what it holds, and what needs a re-login. */
+import type { PoolAccount } from './types';
+/** A setup-token row's credentials, `token` or `token+oauth`; '' for any other row. */
+export declare function credentialTag(account: PoolAccount): string;
+/**
+ * Login trouble on a row still in service: a lost half of a paired row,
+ * or an OAuth login about to expire. A parked row shows none — its state
+ * already reads `re-login` / `disabled`.
+ */
+export declare function loginWarnings(account: PoolAccount, now: number): string[];
+/** Why each lost login stopped working, and when: one dashboard line apiece. */
+export declare function lostLoginNotes(account: PoolAccount, now: number): string[];

package/dist/notify.d.ts

@@ -19,6 +19,12 @@ export interface ToastClient {
  * Best-effort: a failed toast never affects the request.
  */
 export declare function notifyOnSwitch(client: ToastClient, providerID: string, account: PoolAccount): Promise<void>;
+/**
+ * Confirm a login that left a row holding both credentials, either half
+ * having arrived second: organization auto-pairing is a guess, so its result
+ * is shown, never silent.
+ */
+export declare function notifyPaired(client: ToastClient, providerID: string, account: PoolAccount): Promise<void>;
 /**
  * Toast (once per account + source-model + exhaustion window) when a request's
  * model was auto-downgraded to a fallback because its MODEL TIER's weekly cap

package/dist/pairing.d.ts

@@ -0,0 +1,22 @@
+/** Which pool row a fresh login belongs to: the rules `addAccount` lands it by. */
+import { type PoolAccount, type TokenSet } from './types';
+export declare function holdsCredential(row: PoolAccount, tokens: TokenSet): boolean;
+/**
+ * Auto-pairing: the one row of the credential's organization, among those
+ * its usage readings do not rule out, that can take this kind of credential.
+ * A setup-token carries no account identity, so the organization narrows it
+ * — exact for personal Pro/Max accounts (one organization each), shared by
+ * Team/Enterprise seats — and the reset times tell seats apart. A working
+ * credential of the same kind is replaced only when the readings confirm
+ * the same account (a renewed token); an OAuth login never replaces one,
+ * since its account id already failed to match.
+ */
+export declare function orgPartner(rows: readonly PoolAccount[], tokens: TokenSet): PoolAccount | undefined;
+/**
+ * The one row of the token's organization, among those its usage readings do
+ * not rule out, that already serves the account with a working token of its
+ * own. Gist sync uses it to leave such an account alone: a second token for it
+ * adds nothing, and replacing one machine's token with another's would have
+ * two machines trading tokens for ever.
+ */
+export declare function tokenSharer(rows: readonly PoolAccount[], tokens: TokenSet): PoolAccount | undefined;

package/dist/pool/paths.d.ts

@@ -24,4 +24,12 @@ export declare function pendingFilePath(): string;
  * same env-keyed memo as the two files above.
  */
 export declare function versionCacheFilePath(): string;
+/** Path to the gist-sync state (role, gist id, encryption key, imported ids). Holds the key: owner-only. */
+export declare function syncStateFilePath(): string;
+/** Path to this machine's sync origin (random, not secret; outlives "stop syncing"). */
+export declare function syncOriginFilePath(): string;
+/** Path to the one-shot TUI → server sync request (consumed and deleted on read). */
+export declare function syncIntentFilePath(): string;
+/** Path to the latest sync outcome shown by the TUI (no secrets). */
+export declare function syncStatusFilePath(): string;
 export {};

package/dist/providers/anthropic/constants.d.ts

@@ -6,7 +6,28 @@ export declare const TOKEN_URL = "https://platform.claude.com/v1/oauth/token";
 export { OAUTH_HTTP_TIMEOUT_MS, USAGE_HTTP_TIMEOUT_MS } from '../http-timeouts';
 /** Dedicated usage endpoint — returns 5h + 7d utilization without consuming quota. */
 export declare const USAGE_URL = "https://api.anthropic.com/api/oauth/usage";
+/** Default host; `rewriteUrl` applies `ANTHROPIC_BASE_URL` and `?beta=true` like on any request. */
+export declare const MESSAGES_URL = "https://api.anthropic.com/v1/messages";
+export declare const ANTHROPIC_VERSION = "2023-06-01";
+/**
+ * Model for the usage probe that stands in for `USAGE_URL` on a
+ * `claude setup-token` row (see `fetchUsage` in usage.ts): Claude Code's
+ * small, fast model, so the one-token probe costs as little quota as any
+ * request can. An alias, not a dated snapshot, so it follows the model
+ * forward.
+ */
+export declare const USAGE_PROBE_MODEL = "claude-haiku-4-5";
+/** Claude Code's docs for `claude setup-token`, shown with the token login's prompt. */
+export declare const SETUP_TOKEN_DOCS_URL = "https://code.claude.com/docs/en/authentication#generate-a-long-lived-token";
+/** Response header naming the organization a request was served for. */
+export declare const ORGANIZATION_ID_HEADER = "anthropic-organization-id";
 export declare const OAUTH_SCOPES: string[];
+/**
+ * What `claude setup-token` asks for: an inference-only token valid for a
+ * year. `mintInferenceToken` (oauth.ts) asks a refresh grant for the same.
+ */
+export declare const INFERENCE_SCOPE = "user:inference";
+export declare const INFERENCE_TOKEN_LIFETIME_S: number;
 export declare const TOOL_PREFIX = "mcp_";
 /**
  * LAST-RESORT downgrade target when a MODEL-TIER weekly cap is exhausted and

package/dist/providers/anthropic/oauth.d.ts

@@ -6,3 +6,12 @@ export declare function authorize(): Promise<AuthorizeRequest>;
 export declare function exchange(input: string, verifier: string, redirectUri: string, expectedState?: string): Promise<TokenSet | null>;
 /** Refresh an access token. Throws on failure; message includes the HTTP status. */
 export declare function refresh(refreshToken: string): Promise<TokenSet>;
+/**
+ * Mint the token `claude setup-token` prints from an OAuth login, with no
+ * Claude Code and no second browser approval: a refresh grant naming the
+ * scope and lifetime it wants, as Claude Code's own `claude auth login`
+ * mints its one-year token from a refresh token. The grant spends the
+ * refresh token like `refresh`, so the result carries the rotated one;
+ * `access`/`expires` are the minted token. Throws like `refresh`.
+ */
+export declare function mintInferenceToken(refreshToken: string): Promise<TokenSet>;

package/dist/providers/anthropic/setup-token.d.ts

@@ -0,0 +1,14 @@
+import { type TokenSet } from '../../types';
+import type { TokenLogin } from '../types';
+/**
+ * The pasted token, checked before it can join the pool. All whitespace is
+ * dropped first: a terminal wraps the long token, so a copied one routinely
+ * carries line breaks. One probe then decides — only a 401/403 means the
+ * token does not authenticate (a 429 is a valid but exhausted one). Its
+ * response names the organization the token acts for and the account's
+ * usage windows: with no profile scope, that is all that ties the token to
+ * its account's OAuth login, and the usage seeds the row without a second
+ * probe.
+ */
+export declare function exchangeSetupToken(input: string): Promise<TokenSet | null>;
+export declare const setupTokenLogin: TokenLogin;

package/dist/providers/anthropic/usage.d.ts

@@ -6,9 +6,22 @@ import type { PoolAccount, UsageSnapshot } from '../../types';
  * and the fraction scale are Anthropic-specific.
  */
 export declare function parseUsageHeaders(headers: Headers): Partial<UsageSnapshot> | null;
+/**
+ * Claude Code's own quota check: one output token on the small model, shaped
+ * like every other request this plugin sends (identity + billing header,
+ * betas, UA). Any response to it — a 429 included — carries the unified
+ * 5h/7d headers. Rejects only on a network failure; the caller owns the body.
+ */
+export declare function sendUsageProbe(access: string): Promise<Response>;
+/** The usage a probe's response reports, or null when it carries none. */
+export declare function probeSnapshot(headers: Headers, now: number): UsageSnapshot | null;
 /**
  * Poll the dedicated usage endpoint for authoritative 5h + 7d utilization without
  * consuming inference quota. Returns null on any failure — including a 200 whose
  * body is not the usage shape — so the caller keeps the last-known snapshot.
+ *
+ * A row without a refresh token is a `claude setup-token` bearer, scoped to
+ * `user:inference` alone; the endpoint demands `user:profile` and answers it
+ * 403, so such a row is measured with the one-token probe above instead.
  */
 export declare function fetchUsage(account: PoolAccount, now: number): Promise<UsageSnapshot | null>;

package/dist/providers/types.d.ts

@@ -31,6 +31,19 @@ export interface AuthorizeRequest {
     /** Login prompt text; absent = the OAuth default ("Paste the authorization code here:"). */
     instructions?: string;
 }
+/** A paste login for a long-lived token the provider's own CLI mints (see `ProviderAdapter.tokenLogin`). */
+export interface TokenLogin {
+    /**
+     * What the token is called, spliced into the method label. The TUI
+     * re-logs a static row through the method whose label carries it.
+     */
+    readonly label: string;
+    /** Page explaining how to mint the token. */
+    readonly url: string;
+    readonly instructions: string;
+    /** The pasted token, verified; null when malformed or refused. */
+    exchange(input: string): Promise<TokenSet | null>;
+}
 /** A device-code login (RFC 8628) in flight: where to approve it, and the wait for approval. */
 export interface DeviceLogin {
     /** Verification URL to open (the user code rides in it). */
@@ -108,6 +121,20 @@ export interface ProviderAdapter {
      *    instead of cooling it down — no refresh can repair a revoked key.
      */
     tokensFromApiKey?(key: string): TokenSet;
+    /**
+     * Present on providers whose own CLI mints a long-lived bearer (Claude's
+     * `claude setup-token`: one year, inference-only). Registered as a paste
+     * login after the OAuth one; the token joins the pool as a static row —
+     * no refresh token, so it never rotates and a 401 parks it for a re-login.
+     */
+    tokenLogin?: TokenLogin;
+    /**
+     * Present on providers whose OAuth login can mint the bearer `tokenLogin`
+     * takes (Claude): spends `refreshToken` like `refresh`, returning the
+     * minted token as `access`/`expires` beside the rotated refresh token.
+     * Throws on failure.
+     */
+    mintInferenceToken?(refreshToken: string): Promise<TokenSet>;
     /** Set auth + provider headers on an outgoing request for the chosen account. */
     applyAuth(headers: Headers, account: PoolAccount): void;
     /** Optionally rewrite the request URL (e.g. add ?beta=true, swap base URL). */

package/dist/refresh.d.ts

@@ -1,6 +1,18 @@
 import type { ProviderAdapter } from './providers/types';
 import { type PoolAccount } from './types';
+/** The single-use refresh token + the generation it was read at (the CAS key). */
+export interface RefreshAttempt {
+    readonly refresh: string;
+    readonly gen: number;
+}
 export declare function needsRefresh(account: PoolAccount, now: number): boolean;
+export declare function genOf(account: PoolAccount): number;
+export declare function sameGeneration(account: PoolAccount, attempt: RefreshAttempt): boolean;
+/**
+ * Run `fn` holding the account's refresh lock — taken by everything that
+ * spends its single-use refresh token (a refresh, a token mint).
+ */
+export declare function withRefreshLock<T>(providerID: string, accountId: string, fn: () => Promise<T>): Promise<T>;
 /**
  * Ensure the account has a fresh access token, refreshing if needed. The rotated
  * refresh token is persisted immediately. On a genuine invalid_grant (the current

package/dist/status.d.ts

@@ -12,6 +12,12 @@ interface AccountStatus {
     /** tier name → epoch ms until that model tier's cap resets (empty = none). */
     modelCooldownsUntil: Record<string, number>;
     disabledReason: string | null;
+    /** A setup-token row's credentials: `token`, `token+oauth`, or '' for any other row. */
+    login: string;
+    /** `oauth re-login` / `token re-login` / `oauth expires Nd` on a row still in service. */
+    warnings: string[];
+    /** Why each lost login stopped working, printed under the table. */
+    lostNotes: string[];
     /** The account that most recently served a request for this provider. */
     current: boolean;
     /** 1 = next candidate the scheduler would pick. */

package/dist/sync/apply.d.ts

@@ -0,0 +1,66 @@
+import type { ProviderAdapter } from '../providers/types';
+import type { PoolAccount, PoolFile, TokenSet } from '../types';
+import { type ImportJob, type MergeMemory, type MergePlan } from './merge';
+import { type ParsedPayload } from './payload';
+import { type ImportedRef, type SkippedRef } from './state';
+export interface ApplyResult {
+    /** The imported map after this plan. */
+    imported: Record<string, ImportedRef>;
+    /** The skipped map after this plan. */
+    skipped: Record<string, SkippedRef>;
+    added: number;
+    updated: number;
+    removed: number;
+    /** Entries that could not be landed yet (the provider could not be reached, or refused the secret). */
+    deferred: number;
+}
+/** What became of one import: the row it landed on, or left alone because the account already has a credential. */
+export type Landing = {
+    kind: 'placed';
+    row: PoolAccount;
+} | {
+    kind: 'skipped';
+    blocker: string;
+    holds: string;
+};
+/**
+ * Land one verified credential, deciding everything from the pool as it is
+ * under the lock (callers run this inside `mutatePool`):
+ * - a row of this provider that already holds the secret (or, for a key, the
+ *   same account) is the user's own, whatever the plan saw earlier;
+ * - for a Claude token, a row that already serves the same account with a
+ *   working token of its own, minted here, pasted, or imported from another
+ *   entry, is never replaced: two machines that each hold a token for one
+ *   account would otherwise trade them for ever. The entry is skipped;
+ * - in both cases the old imported secret (if the entry is a rotation) is
+ *   taken back, and the row in the way is reported, so the entry is not
+ *   probed again until that row changes;
+ * - an earlier import still held by its row is replaced in place, but only by
+ *   a credential of the same provider; if the entry changed provider the old
+ *   one is taken back and the new one placed on its own;
+ * - anything else is placed by the shared pairing (`placeTokens`), with the
+ *   provider-confirmed identity of the probe only.
+ */
+export declare function land(pool: PoolFile, { entry, previous }: ImportJob, tokens: TokenSet): Landing;
+/**
+ * Carry out a merge plan. Each entry is landed independently: one failing
+ * (a probe that cannot be reached, a pool write that throws) is deferred and
+ * never blocks the rest, and what was already landed stays recorded.
+ */
+export declare function applyPlan(plan: MergePlan, memory: Pick<MergeMemory, 'imported' | 'skipped'>, adapters?: readonly ProviderAdapter[]): Promise<ApplyResult>;
+/** What `applySnapshot` takes besides the snapshot and the memory. */
+export interface SnapshotOptions {
+    adapters?: readonly ProviderAdapter[];
+    /**
+     * Called with the running result after every pass, before the next one: the
+     * pool has changed by then, so the record of what was imported has to be
+     * saved by then too, or a later failure would leave rows nobody tracks.
+     */
+    afterPass?: (soFar: ApplyResult) => Promise<unknown>;
+}
+/**
+ * Bring the pool in line with `snapshot`. After a pass that removed something
+ * the plan is made again, so an entry that was kept out by the credential just
+ * removed is imported in the same cycle instead of the next one.
+ */
+export declare function applySnapshot(snapshot: Pick<ParsedPayload, 'entries' | 'listed'>, memory: MergeMemory, options?: SnapshotOptions): Promise<ApplyResult>;

package/dist/sync/crypto.d.ts

@@ -0,0 +1,19 @@
+/** Blob format version; a reader refuses any other. */
+export declare const BLOB_VERSION = 1;
+/** Largest blob (and gist file) a reader accepts. */
+export declare const MAX_BLOB_BYTES: number;
+/** A fresh random AES-256 key. */
+export declare function generateKey(): Buffer;
+/** The key as it rides in the link's fragment. */
+export declare function encodeKey(key: Buffer): string;
+/** The key of a link fragment, or null when it is not a 32-byte base64url key. */
+export declare function decodeKey(text: string): Buffer | null;
+/** A short stable digest, used to recognize a credential without keeping it. */
+export declare function fingerprint(secret: string): string;
+/** Encrypt `plaintext` into the blob stored in the gist: a fresh nonce on every call. */
+export declare function seal(plaintext: string, key: Buffer): string;
+/**
+ * Decrypt a blob. Every failure is a typed `SyncError` that says nothing
+ * about the content: a wrong key and a tampered blob look the same by design.
+ */
+export declare function open(text: string, key: Buffer): string;

package/dist/sync/cycle.d.ts

@@ -0,0 +1,19 @@
+import type { ProviderAdapter } from '../providers/types';
+import { type GhRunner } from './github-auth';
+export interface CycleDeps {
+    now: () => number;
+    runGh?: GhRunner;
+    adapters?: readonly ProviderAdapter[];
+}
+/** What the cycle tells the scheduler: how soon to try again if it fails. */
+export interface CycleReport {
+    retryMs: number;
+}
+/** After GitHub refuses the account's write, nothing is attempted for this long (downloads go on). */
+export declare const WRITE_BACKOFF_MS = 3600000;
+/**
+ * Run one cycle. `force` is "Upload now": it needs a GitHub token (and says so
+ * if there is none), reads the gist afresh, and tries to write even inside the
+ * back-off after a refusal. Never writes without the lock the caller holds.
+ */
+export declare function runCycle(deps: CycleDeps, force: boolean, report: CycleReport): Promise<string>;

package/dist/sync/engine.d.ts

@@ -0,0 +1,44 @@
+import type { ProviderAdapter } from '../providers/types';
+import { type GhRunner } from './github-auth';
+export interface EngineDeps {
+    now: () => number;
+    runGh?: GhRunner;
+    adapters?: readonly ProviderAdapter[];
+}
+/** What an operation did; `backoffMs` asks the caller to leave GitHub alone that long. */
+export interface Outcome {
+    ok: boolean;
+    message: string;
+    backoffMs?: number;
+}
+export interface SyncEngine {
+    /** One full cycle: download and apply, then upload this machine's own changes when it may. */
+    sync(reqAt?: number): Promise<Outcome>;
+    /**
+     * "Upload now": a cycle that insists on writing (it needs a GitHub token),
+     * or with `fresh` (or when this machine follows nothing) a new gist.
+     */
+    upload(fresh: boolean, reqAt?: number): Promise<Outcome>;
+    /** Start following a gist link, then sync it once. */
+    subscribe(link: string, reqAt?: number): Promise<Outcome>;
+    /** Stop syncing; imported accounts stay. */
+    forget(reqAt?: number): Promise<Outcome>;
+    /**
+     * The digest of this machine's own credentials when the gist may be out of
+     * date and this machine may write, else null.
+     */
+    unpublishedDigest(): Promise<string | null>;
+    /**
+     * The scheduled cycle. Call it with the cycle lock held: it looks at the
+     * persisted state again and returns null (does nothing) unless this machine
+     * still follows gist gistId and a cycle is due.
+     */
+    backgroundPoll(gistId: string): Promise<Outcome | null>;
+    /**
+     * The automatic upload, decided again under the lock: null unless this
+     * machine still follows gist gistId, no back-off is running, and its
+     * credentials still differ from the upload by digest.
+     */
+    backgroundPublish(gistId: string, digest: string): Promise<Outcome | null>;
+}
+export declare function createEngine(deps: EngineDeps): SyncEngine;

package/dist/sync/errors.d.ts

@@ -0,0 +1,9 @@
+export type SyncErrorCode = 'bad-link' | 'not-set-up' | 'bad-blob' | 'bad-version' | 'decrypt' | 'rolled-back' | 'too-large' | 'rate-limited' | 'not-found' | 'network' | 'no-auth' | 'http' | 'write-denied';
+/** A sync failure with a fixed, non-leaky message; `retryAfterMs` accompanies `rate-limited`. */
+export declare class SyncError extends Error {
+    readonly code: SyncErrorCode;
+    readonly retryAfterMs?: number | undefined;
+    constructor(code: SyncErrorCode, retryAfterMs?: number | undefined);
+}
+/** The user-facing line for any thrown value: a sync error's own text, else a generic one. */
+export declare function describeSyncError(error: unknown): string;

package/dist/sync/gist.d.ts

@@ -0,0 +1,33 @@
+/** The one file a sync gist holds. */
+export declare const GIST_FILE = "auth-load-balancer-sync.json";
+export declare const GIST_ID_RE: RegExp;
+export interface GistLink {
+    id: string;
+    key: Buffer;
+}
+/** The id and key of a `https://gist.github.com/<user>/<id>#<key>` link, or null for anything else. */
+export declare function parseGistLink(link: string): GistLink | null;
+/** The link to share: the gist's address plus the key as its fragment. */
+export declare function formatGistLink(owner: string | undefined, id: string, key: Buffer): string;
+export interface CreatedGist {
+    id: string;
+    owner?: string;
+}
+/** Create a secret gist holding `content`. */
+export declare function createGist(token: string, content: string, now?: number): Promise<CreatedGist>;
+/** Replace the sync file of gist `id` with `content`. */
+export declare function updateGist(token: string, id: string, content: string, now?: number): Promise<void>;
+export type GistRead = {
+    changed: false;
+} | {
+    changed: true;
+    content: string;
+    etag?: string;
+};
+/**
+ * Read the sync file of gist `id`; a matching `etag` answers `changed: false`
+ * cheaply. With a `token` the read is authenticated (GitHub's own limit is far
+ * higher than the 60 an hour an anonymous address gets); a token GitHub
+ * refuses is not sent again, and the gist is read without credentials.
+ */
+export declare function readGist(id: string, etag?: string, now?: number, token?: string): Promise<GistRead>;

package/dist/sync/github-auth.d.ts

@@ -0,0 +1,15 @@
+/** Runs `gh auth token`; resolves its stdout, rejects when gh is missing, logged out, or slow. */
+export type GhRunner = () => Promise<string>;
+/** The slice of `execFile` used here, so tests never spawn the real gh. */
+export type ExecFn = (file: string, args: string[], options: {
+    timeout: number;
+    windowsHide: boolean;
+    maxBuffer: number;
+}, callback: (error: Error | null, stdout: string) => void) => unknown;
+/** `execFile` with no shell: nothing to inject into, and the token never touches a command line. */
+export declare function ghAuthToken(exec?: ExecFn): Promise<string>;
+/**
+ * The GitHub token to upload with: `GITHUB_TOKEN`, then `GH_TOKEN`, then the
+ * gh CLI's. Null when none exists. Only uploading needs it.
+ */
+export declare function discoverGithubToken(run?: GhRunner, env?: NodeJS.ProcessEnv): Promise<string | null>;

package/dist/sync/intent.d.ts

@@ -0,0 +1,29 @@
+export type SyncAction = 'upload' | 'upload-new' | 'subscribe' | 'sync' | 'forget';
+/** A TUI request is dead after this long, so an abandoned one cannot fire later. */
+export declare const INTENT_TTL_MS: number;
+/** A request stamped further ahead than this is not from a sane clock; it would otherwise outlive the TTL. */
+export declare const INTENT_SKEW_MS = 60000;
+/**
+ * A request the TUI hands the server through a file beside the pool (the TUI
+ * cannot import the plugin). `link` rides along for `subscribe` and holds the
+ * key, so the file is claimed and deleted the moment the server reads it.
+ */
+export interface SyncIntent {
+    action: SyncAction;
+    at: number;
+    link?: string;
+}
+/** Whether a request is waiting (without claiming it). */
+export declare function intentPending(): Promise<boolean>;
+/**
+ * Claim the pending request, if any. Under a lock the file is renamed to a
+ * name of our own and THAT file is read and deleted, so of several opencode
+ * processes exactly one acts on it, and a newer request the TUI writes while
+ * we read is a different file that is left alone. (A bare rename is not an
+ * exclusive claim on Windows: two concurrent renames of one file can both
+ * succeed, which is why it runs under the lock.) The claimed file is deleted
+ * even when it does not parse. fterClaim is a test seam: it runs once the
+ * request is ours and before it is read, which is where the TUI can write a
+ * newer one.
+ */
+export declare function takeIntent(now: number, waitMs?: number, afterClaim?: () => Promise<void>): Promise<SyncIntent | null>;

package/dist/sync/loop.d.ts

@@ -0,0 +1,40 @@
+import type { SyncEngine } from './engine';
+import { type SyncIntent } from './intent';
+export { POLL_MS, PUBLISH_RETRY_MS } from './timing';
+export declare const TICK_MS = 1000;
+export declare const CHANGE_CHECK_MS = 5000;
+export declare const DEBOUNCE_MS = 10000;
+export interface LoopTimers {
+    set(run: () => void, ms: number): unknown;
+    clear(handle: unknown): void;
+}
+/** Timers that never keep the process alive. */
+export declare const realTimers: LoopTimers;
+/**
+ * Run `fn` unless another opencode process is mid-run; resolves undefined then.
+ * `staleMs` is four heartbeats: a live holder touches the lock every 5 s, so it
+ * is never stale, while a holder that died (a process killed mid-run) stops
+ * blocking the machine after 20 s instead of a minute.
+ */
+export declare function withCycleLock<T>(fn: () => Promise<T>, waitMs: number): Promise<T | undefined>;
+/** Where the TUI's requests come from; the file handshake unless a test replaces it. */
+export interface IntentSource {
+    pending(): Promise<boolean>;
+    take(now: number): Promise<SyncIntent | null>;
+}
+export interface LoopDeps {
+    engine: SyncEngine;
+    now: () => number;
+    timers?: LoopTimers;
+    intents?: IntentSource;
+    lockWaitMs?: number;
+    disposeWaitMs?: number;
+}
+export interface SyncLoop {
+    start(): void;
+    /** Stop ticking and wait (bounded) for the step in flight, so its lock is released. */
+    dispose(): Promise<void>;
+    /** One scheduler step; exposed so tests drive time themselves. */
+    tick(): Promise<void>;
+}
+export declare function createSyncLoop(deps: LoopDeps): SyncLoop;

package/dist/sync/merge.d.ts

@@ -0,0 +1,49 @@
+import type { PoolAccount } from '../types';
+import { type ParsedPayload, type SyncEntry } from './payload';
+import type { ImportedRef, SkippedRef } from './state';
+/** An entry to land locally; `previous` is the row an earlier value of it was imported into. */
+export interface ImportJob {
+    entry: SyncEntry;
+    previous?: ImportedRef;
+}
+/** What sync remembers about earlier cycles, and which machine this is. */
+export interface MergeMemory {
+    origin: string;
+    imported: Readonly<Record<string, ImportedRef>>;
+    skipped: Readonly<Record<string, SkippedRef>>;
+}
+export interface MergePlan {
+    imports: ImportJob[];
+    /** Imported entries the gist no longer lists: entry key and where it landed. */
+    drops: [string, ImportedRef][];
+    /** Skip records of entries the gist no longer lists. */
+    forgets: string[];
+}
+/** Whether `row` carries the credential with this fingerprint as its static one. */
+export declare function holdsFingerprint(row: PoolAccount, digest: string): boolean;
+/** The digest of the static credential a row carries, or '' when it has none. */
+export declare function staticFingerprint(row: PoolAccount): string;
+/** Whether the row that kept an entry out is still in the way. */
+export declare function blockerStands(accounts: readonly PoolAccount[], skip: SkippedRef): boolean;
+/**
+ * Whether a skipped entry should be looked at again because the row that kept
+ * it out is gone, or no longer holds what it held.
+ */
+export declare function hasFreedSkips(accounts: readonly PoolAccount[], skipped: Readonly<Record<string, SkippedRef>>): boolean;
+/**
+ * What to do with the gist's entries, given what was imported before. Pure:
+ * - this machine's own entries (its origin) are never imported back;
+ * - a new entry is imported, unless a local row already holds its secret
+ *   (that row is the user's own and sync never tracks, so never removes, it);
+ * - an entry that was skipped because the account already had a credential is
+ *   not probed again while that credential is still in the way;
+ * - an entry whose secret changed is imported again, onto the row it was in,
+ *   unless a local row already holds the new secret, which stays the user's
+ *   own: the old imported secret is taken back and the entry is forgotten;
+ * - an entry whose secret is unchanged is left alone, so a row the user
+ *   deleted or re-pointed stays that way until the gist changes it;
+ * - an imported entry the gist no longer lists is dropped. An entry that is
+ *   listed but failed validation is NOT "no longer listed": it is left as is.
+ * Rows that were never imported are not reachable from a plan.
+ */
+export declare function planMerge(accounts: readonly PoolAccount[], snapshot: Pick<ParsedPayload, 'entries' | 'listed'>, memory: MergeMemory): MergePlan;

package/dist/sync/origin.d.ts

@@ -0,0 +1,2 @@
+/** This machine's origin; created on first use, under a lock so two windows never make two. */
+export declare function machineOrigin(): Promise<string>;

package/dist/sync/own.d.ts

@@ -0,0 +1,31 @@
+/**
+ * What this machine lists in the gist. A row's static credential is the
+ * machine's own unless sync put it there: a row that still holds a credential
+ * recorded in the imported map is imported, never uploaded, so a token travels
+ * from the machine that has it and never back.
+ */
+import { type PoolAccount, type PoolFile } from '../types';
+import { type SyncEntry } from './payload';
+import type { ImportedRef } from './state';
+/**
+ * The static credential of a row: a Claude `inferenceToken`, or a Kimi API
+ * key. A Kimi row only counts when it carries the static-credential expiry as
+ * well as no refresh token: an OAuth sign-in can also leave a refresh-less row,
+ * with a short-lived access token that must never leave the machine.
+ */
+export declare function staticSecret(row: PoolAccount): string | undefined;
+/**
+ * This machine's own static credentials, sorted by row id so equal pools
+ * produce equal payloads. Every entry goes through the receiver's own
+ * validation (a label too long is trimmed, a row whose id or secret a receiver
+ * would refuse is left out): this machine never produces a snapshot others
+ * would reject.
+ */
+export declare function ownEntries(pool: PoolFile, origin: string, imported: Readonly<Record<string, ImportedRef>>): SyncEntry[];
+/**
+ * What of `own` to list next to `others` (the entries of every other machine,
+ * carried over untouched): not a secret a machine with a smaller origin already
+ * lists (one copy is enough, and two machines never both give theirs up
+ * because the smaller origin keeps it), and no more than the gist can hold.
+ */
+export declare function listable(own: readonly SyncEntry[], others: readonly SyncEntry[], origin: string): SyncEntry[];