sideby 0.0.0-stage → 0.2.1

package/dist/src/quota/claude-statusline.js

@@ -0,0 +1,301 @@
+// `sideby quota setup|teardown claude` (spec §3.7): wraps the Main Account's status line command with
+// `sideby statusline-tap` so Claude Code's own `rate_limits` get cached, and restores the original bytes
+// exactly on teardown, but only while the file is still what setup wrote.
+import { mkdir, readFile, rm, stat } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { lstatOrNull, realpathOrNull, sha256, writeFileAtomic, writeIfUnchanged } from '../core/fs-safe.js';
+import { which } from '../core/launch.js';
+import { tildify } from '../core/paths.js';
+import { CLAUDE_MAIN_DIR } from '../families/claude/layout.js';
+import { ORIG_FLAG, TAP_COMMAND } from './statusline-tap.js';
+export function backupFile(stateDir) {
+    return join(stateDir, 'statusline', 'claude-settings.backup.json');
+}
+export function mainSettingsFile(home) {
+    return join(home, CLAUDE_MAIN_DIR, 'settings.json');
+}
+export function isWrapped(command) {
+    return typeof command === 'string' && (command === TAP_COMMAND || command.startsWith(`${TAP_COMMAND} `));
+}
+export function wrapCommand(original) {
+    return original?.trim()
+        ? `${TAP_COMMAND} ${ORIG_FLAG} ${Buffer.from(original, 'utf8').toString('base64')}`
+        : TAP_COMMAND;
+}
+function isPlainObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+/** Keeps the file's own indentation so the diff shows only the changed lines. */
+function serializeLike(original, value) {
+    const body = original.trimEnd();
+    const indent = body.includes('\n') ? (/^([ \t]+)\S/m.exec(body)?.[1] ?? 2) : undefined;
+    const out = indent === undefined ? JSON.stringify(value) : JSON.stringify(value, null, indent);
+    return original.endsWith('\n') ? `${out}\n` : out;
+}
+async function analyze(ctx) {
+    const shown = mainSettingsFile(ctx.home);
+    const showName = tildify(shown, ctx.home);
+    const blocked = (message, file = shown) => ({
+        plan: { status: 'blocked', file, diff: '', message },
+    });
+    const lst = await lstatOrNull(shown);
+    if (!lst)
+        return blocked(`${showName} does not exist; start Claude Code once so it creates the file, then retry`);
+    const target = lst.isSymbolicLink() ? await realpathOrNull(shown) : shown;
+    if (!target)
+        return blocked(`${showName} is a link to a missing file; fix the link and retry`);
+    const targetName = tildify(target, ctx.home);
+    const note = target !== shown ? ` (${showName} is a link; its target ${targetName} is changed)` : '';
+    let original;
+    try {
+        original = await readFile(target);
+    }
+    catch (err) {
+        return blocked(`cannot read ${targetName}: ${err.code ?? 'error'}`, target);
+    }
+    const text = original.toString('utf8');
+    let settings;
+    try {
+        settings = JSON.parse(text);
+    }
+    catch {
+        return blocked(`${targetName} is not valid JSON; sideby will not rewrite it`, target);
+    }
+    if (!isPlainObject(settings))
+        return blocked(`${targetName} is not a JSON object`, target);
+    const current = settings.statusLine ?? undefined;
+    if (current !== undefined && !isPlainObject(current))
+        return blocked(`statusLine in ${targetName} is not an object; sideby will not rewrite it`, target);
+    const command = current?.command;
+    if (command !== undefined && typeof command !== 'string')
+        return blocked(`statusLine.command in ${targetName} is not a string`, target);
+    if (isWrapped(command))
+        return {
+            plan: { status: 'enabled', file: target, diff: '', message: `already enabled in ${targetName}${note}` },
+        };
+    const bin = await which('sideby', ctx.env);
+    if (!bin)
+        return blocked(`sideby is not on PATH, and the status line runs \`${TAP_COMMAND}\` on every refresh; install it with \`npm i -g sideby\` and retry`, target);
+    const real = (await realpathOrNull(bin)) ?? bin;
+    if (bin.includes('/_npx/') || real.includes('/_npx/'))
+        return blocked(`sideby on PATH comes from the npx cache (${bin}), which can disappear; install it with \`npm i -g sideby\` and retry`, target);
+    const statusLine = current
+        ? { type: 'command', ...current, command: wrapCommand(command) }
+        : { type: 'command', command: TAP_COMMAND };
+    const wrapped = serializeLike(text, { ...settings, statusLine });
+    return {
+        plan: {
+            status: 'ready',
+            file: target,
+            diff: statusLineDiff(current, statusLine, targetName),
+            message: `wraps statusLine.command in ${targetName} so sideby can record Claude's rate limits${note}; undo with \`sideby quota teardown claude\``,
+        },
+        target,
+        original,
+        wrapped,
+    };
+}
+async function readBackup(file) {
+    try {
+        const b = JSON.parse(await readFile(file, 'utf8'));
+        if (typeof b.file !== 'string' ||
+            typeof b.originalBase64 !== 'string' ||
+            typeof b.originalHash !== 'string' ||
+            typeof b.wrappedHash !== 'string')
+            return null;
+        return b;
+    }
+    catch {
+        return null;
+    }
+}
+export const claudeStatusline = {
+    summary: "Wrap the status line command in ~/.claude/settings.json with `sideby statusline-tap` so sideby can cache Claude's 5h and 7d rate limits. Your status line keeps working; teardown restores the file byte for byte.",
+    async plan(ctx) {
+        return (await analyze(ctx)).plan;
+    },
+    async apply(ctx) {
+        const a = await analyze(ctx);
+        if (a.plan.status !== 'ready' || !a.target || !a.original || a.wrapped === undefined)
+            return a.plan;
+        const mode = (await stat(a.target)).mode & 0o777;
+        const backup = {
+            file: a.target,
+            originalBase64: a.original.toString('base64'),
+            originalHash: sha256(a.original),
+            wrappedHash: sha256(a.wrapped),
+            appliedAt: ctx.now.toISOString(),
+        };
+        const bf = backupFile(ctx.stateDir);
+        await mkdir(dirname(bf), { recursive: true, mode: 0o700 });
+        await writeFileAtomic(bf, `${JSON.stringify(backup, null, 2)}\n`, 0o600);
+        let written = false;
+        try {
+            written = await writeIfUnchanged(a.target, backup.originalHash, a.wrapped, mode);
+        }
+        finally {
+            if (!written)
+                await rm(bf, { force: true });
+        }
+        if (!written)
+            return {
+                ...a.plan,
+                status: 'blocked',
+                message: `${tildify(a.target, ctx.home)} changed while applying; nothing was written, run setup again`,
+            };
+        return { ...a.plan, status: 'enabled', message: `enabled: ${a.plan.message}` };
+    },
+    async teardown(ctx) {
+        const bf = backupFile(ctx.stateDir);
+        const b = await readBackup(bf);
+        if (!b)
+            return {
+                ok: false,
+                message: `the Claude status line wrapper is not enabled by sideby (no backup at ${tildify(bf, ctx.home)})`,
+            };
+        const name = tildify(b.file, ctx.home);
+        const original = Buffer.from(b.originalBase64, 'base64');
+        if (sha256(original) !== b.originalHash)
+            return {
+                ok: false,
+                message: `the backup at ${tildify(bf, ctx.home)} is damaged; ${name} was not changed`,
+            };
+        let current;
+        try {
+            current = await readFile(b.file);
+        }
+        catch {
+            return {
+                ok: false,
+                message: `${name} is missing; nothing restored, the backup stays at ${tildify(bf, ctx.home)}`,
+            };
+        }
+        if (sha256(current) !== b.wrappedHash)
+            return {
+                ok: false,
+                message: `${name} changed after quota setup, so sideby will not overwrite it. Remove the \`${TAP_COMMAND}\` wrapper by hand: set statusLine.command back to your original command (base64 after ${ORIG_FLAG}), or delete statusLine if you had none. The diff shows the statusLine change to make.`,
+                diff: statusLineDiff(statusLineOf(current), statusLineOf(original), name),
+            };
+        try {
+            const mode = (await stat(b.file)).mode & 0o777;
+            if (!(await writeIfUnchanged(b.file, b.wrappedHash, original, mode)))
+                return { ok: false, message: `${name} changed while restoring; nothing was written` };
+        }
+        catch (err) {
+            return { ok: false, message: `could not restore ${name}: ${err.message}` };
+        }
+        await rm(bf, { force: true });
+        return { ok: true, message: `restored ${name} to its original bytes` };
+    },
+};
+function splitLines(a, b) {
+    // Drop one shared trailing newline so files ending in "\n" do not diff an empty last line.
+    if (a.endsWith('\n') && b.endsWith('\n'))
+        return [a.slice(0, -1).split('\n'), b.slice(0, -1).split('\n')];
+    return [a.split('\n'), b.split('\n')];
+}
+function middleOps(a, b) {
+    const n = a.length;
+    const m = b.length;
+    if (n * m > 4_000_000)
+        return [...a.map((line) => ({ t: '-', line })), ...b.map((line) => ({ t: '+', line }))];
+    // lcs[i][j] = longest common subsequence of a[i..] and b[j..]
+    const w = m + 1;
+    const lcs = new Uint32Array((n + 1) * w);
+    for (let i = n - 1; i >= 0; i--)
+        for (let j = m - 1; j >= 0; j--)
+            lcs[i * w + j] =
+                a[i] === b[j] ? lcs[(i + 1) * w + j + 1] + 1 : Math.max(lcs[(i + 1) * w + j], lcs[i * w + j + 1]);
+    const ops = [];
+    let i = 0;
+    let j = 0;
+    while (i < n || j < m) {
+        if (i < n && j < m && a[i] === b[j]) {
+            ops.push({ t: ' ', line: a[i++] });
+            j++;
+        }
+        else if (j >= m || (i < n && lcs[(i + 1) * w + j] >= lcs[i * w + j + 1]))
+            ops.push({ t: '-', line: a[i++] });
+        else
+            ops.push({ t: '+', line: b[j++] });
+    }
+    return ops;
+}
+const SECRET_KEY = /(key|token|secret|password|passwd|auth|credential|cookie)/i;
+/**
+ * Hides values of secret-looking JSON keys in a diff line. settings.json often keeps API keys in `env`,
+ * right next to `statusLine`, so context lines could otherwise print them.
+ */
+export function redactLine(line) {
+    return line.replace(/("([^"\\]*)"\s*:\s*)"(?:[^"\\]|\\.)*"/g, (m, head, key) => SECRET_KEY.test(key) ? `${head}"<redacted>"` : m);
+}
+/**
+ * Diff of the statusLine object only. The rest of settings.json never enters a diff: it often holds API keys
+ * (for example in `env`), in shapes no line-based redaction can reliably catch.
+ */
+export function statusLineDiff(before, after, file) {
+    const show = (v) => v === undefined ? '' : `${JSON.stringify({ statusLine: redactStatusLine(v) }, null, 2)}\n`;
+    return unifiedDiff(show(before), show(after), `${file} (statusLine only)`);
+}
+const SHOWN_STATUSLINE_KEYS = new Set(['type', 'command', 'padding']);
+/** Shows the statusLine fields sideby touches as they are; any other value becomes "<redacted>". */
+export function redactStatusLine(v) {
+    if (typeof v !== 'object' || v === null || Array.isArray(v))
+        return '<redacted>';
+    return Object.fromEntries(Object.entries(v).map(([k, val]) => [
+        k,
+        SHOWN_STATUSLINE_KEYS.has(k) && (typeof val !== 'object' || val === null) ? val : '<redacted>',
+    ]));
+}
+function statusLineOf(bytes) {
+    try {
+        const v = JSON.parse(bytes.toString('utf8'));
+        return v && typeof v === 'object' ? v.statusLine : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Minimal unified diff with 3 lines of context; empty when the texts are equal. Secret-looking values are redacted. */
+export function unifiedDiff(oldText, newText, file, context = 3) {
+    if (oldText === newText)
+        return '';
+    const [a, b] = splitLines(oldText, newText);
+    let pre = 0;
+    while (pre < a.length && pre < b.length && a[pre] === b[pre])
+        pre++;
+    let suf = 0;
+    while (suf < a.length - pre && suf < b.length - pre && a[a.length - 1 - suf] === b[b.length - 1 - suf])
+        suf++;
+    const ops = [
+        ...a.slice(0, pre).map((line) => ({ t: ' ', line })),
+        ...middleOps(a.slice(pre, a.length - suf), b.slice(pre, b.length - suf)),
+        ...a.slice(a.length - suf).map((line) => ({ t: ' ', line })),
+    ];
+    const changes = ops.flatMap((o, i) => (o.t === ' ' ? [] : [i]));
+    if (!changes.length)
+        return `--- a/${file}\n+++ b/${file}\n@@ line endings differ @@\n`;
+    const groups = [];
+    for (const c of changes) {
+        const last = groups[groups.length - 1];
+        if (last && c - last[1] <= 2 * context)
+            last[1] = c;
+        else
+            groups.push([c, c]);
+    }
+    let out = `--- a/${file}\n+++ b/${file}\n`;
+    for (const [first, lastChange] of groups) {
+        const start = Math.max(0, first - context);
+        const end = Math.min(ops.length, lastChange + 1 + context);
+        const before = ops.slice(0, start);
+        const slice = ops.slice(start, end);
+        const oldLen = slice.filter((o) => o.t !== '+').length;
+        const newLen = slice.filter((o) => o.t !== '-').length;
+        const oldStart = before.filter((o) => o.t !== '+').length + (oldLen ? 1 : 0);
+        const newStart = before.filter((o) => o.t !== '-').length + (newLen ? 1 : 0);
+        out += `@@ -${oldStart},${oldLen} +${newStart},${newLen} @@\n`;
+        for (const o of slice)
+            out += `${o.t}${redactLine(o.line)}\n`;
+    }
+    return out;
+}

package/dist/src/quota/statusline-tap.d.ts

@@ -0,0 +1,11 @@
+import { type ClaudeQuotaCache } from '../families/claude/quota-cache.ts';
+import type { Env } from '../types.ts';
+/** Command the wrapper starts with; `quota setup claude` detects an existing wrapper by this prefix. */
+export declare const TAP_COMMAND = "sideby statusline-tap";
+export declare const ORIG_FLAG = "--orig-b64";
+export declare function defaultLine(cache: ClaudeQuotaCache | null): string;
+/**
+ * Runs the tap. `argv` is everything after `statusline-tap`. Returns the original command's exit code,
+ * or 0 when there is no original command and a default line was printed.
+ */
+export declare function runStatuslineTap(argv: string[], env: Env, stdin: AsyncIterable<Uint8Array | string>, stdout: NodeJS.WritableStream, stderr?: NodeJS.WritableStream): Promise<number>;

package/dist/src/quota/statusline-tap.js

@@ -0,0 +1,104 @@
+// Entry for `sideby statusline-tap` (spec §3.7). Claude Code runs it on every status line refresh, so it
+// imports only Node built-ins and leaf modules (the cache module, core/fs-safe, core/paths), never the
+// Runtime or a Family index. It caches `rate_limits` for the Account, then runs the original command.
+// Nothing about the cache may change what the original command receives, prints or returns.
+import { spawn } from 'node:child_process';
+import { constants } from 'node:os';
+import { accountNameFromEnv, cacheStateDir, parseRateLimits, writeQuotaCache, } from '../families/claude/quota-cache.js';
+/** Command the wrapper starts with; `quota setup claude` detects an existing wrapper by this prefix. */
+export const TAP_COMMAND = 'sideby statusline-tap';
+export const ORIG_FLAG = '--orig-b64';
+export function defaultLine(cache) {
+    return (cache?.windows ?? []).map((w) => `${w.label} ${Math.round(w.usedPercent)}%`).join(' · ');
+}
+function originalCommand(argv) {
+    let b64;
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === ORIG_FLAG)
+            b64 = argv[i + 1];
+        else if (a.startsWith(`${ORIG_FLAG}=`))
+            b64 = a.slice(ORIG_FLAG.length + 1);
+    }
+    if (!b64)
+        return null;
+    const cmd = Buffer.from(b64, 'base64').toString('utf8');
+    return cmd.trim() ? cmd : null;
+}
+/** Reads the whole stream; on a read error returns what arrived so far instead of nothing. */
+async function readAll(stream) {
+    const chunks = [];
+    try {
+        for await (const c of stream)
+            chunks.push(typeof c === 'string' ? Buffer.from(c) : Buffer.from(c));
+    }
+    catch {
+        // keep the partial input
+    }
+    return Buffer.concat(chunks);
+}
+function runOriginal(cmd, input, env, stdout, stderr) {
+    return new Promise((done) => {
+        let child;
+        try {
+            child = spawn('/bin/sh', ['-c', cmd], {
+                env: env,
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+        }
+        catch (err) {
+            stderr.write(`sideby statusline-tap: ${err.message}\n`);
+            done(127);
+            return;
+        }
+        child.stdout.pipe(stdout, { end: false });
+        child.stderr.pipe(stderr, { end: false });
+        // The original command may exit without reading stdin; that is not an error.
+        child.stdin.on('error', () => { });
+        child.stdin.end(input);
+        child.on('error', (err) => {
+            stderr.write(`sideby statusline-tap: ${err.message}\n`);
+            done(127);
+        });
+        child.on('close', (code, signal) => {
+            if (code !== null)
+                done(code);
+            else
+                done(128 + ((signal && constants.signals[signal]) || 0));
+        });
+    });
+}
+/**
+ * Runs the tap. `argv` is everything after `statusline-tap`. Returns the original command's exit code,
+ * or 0 when there is no original command and a default line was printed.
+ */
+export async function runStatuslineTap(argv, env, stdin, stdout, stderr = process.stderr) {
+    const cmd = originalCommand(argv);
+    let input = Buffer.alloc(0);
+    try {
+        input = await readAll(stdin);
+    }
+    catch {
+        // Pass through whatever arrived; a broken stdin must not hide the status line.
+    }
+    let cache = null;
+    const record = (async () => {
+        try {
+            cache = parseRateLimits(input.toString('utf8'), new Date());
+            const name = accountNameFromEnv(env);
+            if (!cache || !name)
+                return;
+            await writeQuotaCache(cacheStateDir(env), name, cache);
+        }
+        catch {
+            // Caching is best effort.
+        }
+    })();
+    if (cmd === null) {
+        await record;
+        stdout.write(`${defaultLine(cache)}\n`);
+        return 0;
+    }
+    const [code] = await Promise.all([runOriginal(cmd, input, env, stdout, stderr), record]);
+    return code;
+}

package/dist/src/runtime.d.ts

@@ -0,0 +1,195 @@
+import { type AccountRefError } from './core/accounts.ts';
+import { type Config } from './core/config.ts';
+import { type CreateResult } from './core/create.ts';
+import { type DoctorReport } from './core/doctor.ts';
+import { UserError } from './core/errors.ts';
+import { type HandoffPlan } from './core/handoff.ts';
+import { type DoctorHistory } from './core/last-doctor.ts';
+import { type HostLaunch, type PreparedLaunch } from './core/launch.ts';
+import { type Paths } from './core/paths.ts';
+import { type Shell, type ShellInitWrite } from './core/shell-init.ts';
+import { type BuiltinPlugin, type LoadedPlugin, type PluginLoadError } from './plugins/loader.ts';
+import type { Account, AccountIdentity, Env, FamilyDef, LoginState, QuotaResult, QuotaSetupPlan, ReadContext, ShareMode, UsageResult } from './types.ts';
+export type { AccountIdentity, AccountRefError, DoctorHistory, Shell, ShellInitWrite };
+/** How `sideby resume` starts the Host (spec §3.15). */
+export interface ResumeLaunch {
+    launch: HostLaunch;
+    /** The session the Host arguments resume by id, when they name one. */
+    sessionId?: string;
+    /** Set when the session lives in a non-main Account and `launch` starts that Account as `run` would. */
+    account?: Account;
+}
+/** What happened to the alias asked for with a new Account. */
+export interface AliasResult {
+    name: string;
+    /** True when the config now maps the alias to the new Account (also when it already did). */
+    added: boolean;
+    message?: string;
+}
+/** What `sideby alias add|rm` did; `ok` is false when a shell-init file was not rewritten. */
+export interface AliasEditResult {
+    ok: boolean;
+    alias: string;
+    status: 'added' | 'exists' | 'removed' | 'absent';
+    /** The Account ref the alias starts (for `rm`, started before it was removed). */
+    account?: string;
+    /** Host arguments the alias adds to `sideby run`; absent when there are none. */
+    args?: string[];
+    /** One entry per file in config `shellInitFile`; absent when none is configured. */
+    shellInitFiles?: ShellInitWrite[];
+}
+/** `createAccount` plus the alias and shell-init files it wrote; `ok` is false when either failed. */
+export interface CreateAccountResult extends CreateResult {
+    alias?: AliasResult;
+    /** One entry per file in config `shellInitFile`; absent when none is configured. */
+    shellInitFiles?: ShellInitWrite[];
+}
+export interface FamilyInfo {
+    id: string;
+    title: string;
+    bin: string;
+    installUrl: string;
+    installed: boolean;
+    /** Plugin that provides the Family. */
+    plugin: string;
+}
+/** One Shared Item as `sideby families` reports it (spec §3.16). */
+export interface SharedItemInfo {
+    path: string;
+    mode: ShareMode;
+    key?: string;
+    mainPath?: string;
+    credential?: boolean;
+    noSymlink?: boolean;
+    /** `family` from the FamilyDef, `config` from `extraSharedItems`. */
+    source: 'family' | 'config';
+    /** What the item looks like in an Account, in one fixed sentence. */
+    meaning: string;
+}
+/** A Family's facts for agents and docs: FamilyInfo plus layout, sign-in, sources and Shared Items (spec §3.16). */
+export interface FamilyDetail extends FamilyInfo {
+    /** Relative to HOME: `{ main: '.claude', account: '.claude-<name>' }`. */
+    layout: {
+        main: string;
+        account: string;
+    };
+    selectVar: string;
+    /** `args` is null when sign-in happens inside the Host. */
+    login: {
+        args: string[] | null;
+        hint: string;
+    };
+    quota: boolean;
+    usage: boolean;
+    quotaSetup: boolean;
+    shared: SharedItemInfo[];
+}
+export interface AccountStatus extends Account {
+    familyTitle: string;
+    hostInstalled: boolean;
+    /** `not-needed` for API Accounts, which authenticate with their Secret File. */
+    login: LoginState | 'not-needed';
+    model?: string;
+    /** Who the Account is signed in as (email, organization), when its Family can tell. */
+    identity?: AccountIdentity;
+    /** Plugin errors met while reading this Account (for example an unreadable settings file). */
+    problems?: string[];
+}
+export interface DoctorOptions {
+    /** Family id or Account ref; all Accounts when omitted. */
+    target?: string;
+    fix?: boolean;
+    force?: boolean;
+    /** Record this run as the last Doctor run (default true). A read-only Panel passes false. */
+    persist?: boolean;
+}
+/** A Family's one-time quota setup, bound to this Runtime's context. */
+export interface BoundQuotaSetup {
+    family: string;
+    summary: string;
+    plan(): Promise<QuotaSetupPlan>;
+    apply(): Promise<QuotaSetupPlan>;
+    teardown(): Promise<{
+        ok: boolean;
+        message: string;
+        diff?: string;
+    }>;
+}
+export interface Runtime {
+    paths: Paths;
+    config: Config;
+    env: Env;
+    families: ReadonlyMap<string, FamilyDef>;
+    plugins: readonly LoadedPlugin[];
+    pluginErrors: readonly PluginLoadError[];
+    familyInfo(): Promise<FamilyInfo[]>;
+    /** Every loaded Family with its layout, sign-in, quota support and Shared Items (config extras included). */
+    familyDetails(): Promise<FamilyDetail[]>;
+    accounts(): Promise<Account[]>;
+    resolve(ref: string): Promise<Account>;
+    status(account: Account): Promise<AccountStatus>;
+    doctor(opts?: DoctorOptions): Promise<DoctorReport>;
+    /**
+     * Doctor plus the merged history it produces (written unless `persist: false`), so a read-only caller
+     * still sees the result in context.
+     */
+    doctorWithHistory(opts?: DoctorOptions): Promise<{
+        report: DoctorReport;
+        history: DoctorHistory;
+    }>;
+    /** Latest Doctor result per Account and per Family, if any check was recorded. */
+    doctorHistory(): Promise<DoctorHistory | undefined>;
+    /** Every Family's quota setup with its current plan; a plan that throws is reported as `blocked`. */
+    quotaSetups(): Promise<{
+        family: string;
+        summary: string;
+        plan: QuotaSetupPlan;
+    }[]>;
+    /** One Family's quota setup; throws UnknownFamilyError or a UserError when the Family has none. */
+    quotaSetup(familyId: string): BoundQuotaSetup;
+    /**
+     * Creates the Account, then (when `alias` is given) adds it to the config `aliases`, then rewrites every
+     * `shellInitFile`. An alias that is invalid or taken is refused before anything is created; a failure to write
+     * it afterwards leaves the Account in place and is reported in `alias`.
+     */
+    createAccount(family: string, name: string, opts?: {
+        api?: boolean;
+        alias?: string;
+    }): Promise<CreateAccountResult>;
+    /**
+     * Adds a short command for an existing Account (`target` is a ref, a unique name or an alias, saved as the ref),
+     * with Host arguments for `sideby run`, then rewrites every `shellInitFile`. Refuses a taken name.
+     */
+    addAlias(alias: string, target: string, args?: readonly string[]): Promise<AliasEditResult>;
+    /** Removes a short command from the config, then rewrites every `shellInitFile`. */
+    removeAlias(alias: string): Promise<AliasEditResult>;
+    /** Why `alias` cannot start `ref` (shell-safe, not reserved, not taken by another Account), or null. */
+    aliasProblem(alias: string, ref: string): string | null;
+    /** What `sideby shell-init <shell>` prints, from the Accounts on disk and the config aliases. */
+    shellInitScript(shell: Shell): Promise<string>;
+    /** Rewrites the configured `shellInitFile` of each shell (all configured ones by default). */
+    writeShellInitFiles(shells?: readonly Shell[]): Promise<ShellInitWrite[]>;
+    prepareLaunch(ref: string, userArgs: readonly string[], command: 'run' | 'login'): Promise<PreparedLaunch>;
+    /**
+     * Starts the non-main Account that holds the session the Host arguments resume, or else the Host unchanged
+     * (spec §3.15). Throws UnknownFamilyError, or a UserError when the Family cannot route sessions.
+     */
+    resumeLaunch(familyId: string, userArgs: readonly string[]): Promise<ResumeLaunch>;
+    quota(account: Account): Promise<QuotaResult>;
+    usage(account: Account): Promise<UsageResult>;
+    /**
+     * Which Account of a Family to move on to (spec §3.13). Throws a UserError with code `no-quota-source`
+     * when the Family cannot tell, `no-accounts` when it has none.
+     */
+    handoff(familyId: string, opts?: {
+        includeApi?: boolean;
+    }): Promise<HandoffPlan>;
+    readContext(): ReadContext;
+}
+export declare class UnknownFamilyError extends UserError {
+}
+export declare function createRuntime(opts?: {
+    env?: Env;
+    builtins?: BuiltinPlugin[];
+    now?: () => Date;
+}): Promise<Runtime>;