sideby 0.13.1 → 0.14.0

package/README.md

@@ -94,7 +94,7 @@ cc-switch's docs describe that switch: it writes the live settings file ([README
 |---|---|---|---|---|
 | Claude Code | `~/.claude`, `~/.claude-<name>` | `claude auth login` | ✓ after `quota setup claude` | ✓ |
 | Codex CLI | `~/.codex`, `~/.codex-<name>` | `codex login` | ✓ | ✓ |
-| Grok Build | `~/.grok`, `~/.grok-<name>` | `grok login` | no public source | no public source |
+| Grok Build | `~/.grok`, `~/.grok-<name>` | `grok login` | weekly, asked from the `grok` CLI | no public source |
 | pi | `~/.pi/agent`, `~/.pi-<name>/agent` | `/login` inside pi | no public source | no public source |
 
 sideby starts the official binary on your `PATH` and never patches it. Tested versions and per-Host notes are in the [guide](docs/guide/usage.md#host-notes).

package/dist/build.json

@@ -1 +1 @@
-{"id":"20261016T161929-77384f"}
+{"id":"20261017T050946-402d73"}

package/dist/src/cli/commands.d.ts

@@ -1,6 +1,6 @@
 import type { DoctorReport } from '../core/doctor.ts';
 import { type HandoffIo } from '../core/handoff-run.ts';
-import type { Finding } from '../types.ts';
+import type { Account, Finding } from '../types.ts';
 import { type ParsedArgs } from './args.ts';
 export interface Io {
     out(s: string): void;
@@ -15,7 +15,7 @@ export declare function serializeDoctor(r: DoctorReport): {
         ref: string;
         family: string;
         name: string;
-        kind: import("../types.ts").Account['kind'];
+        kind: Account['kind'];
         dir: string;
         shared: {
             ok: number;

package/dist/src/cli/commands.js

@@ -14,7 +14,7 @@ import { resolvePaths, tildify } from '../core/paths.js';
 import { USAGE_DAYS } from '../core/quota-levels.js';
 import { groupsToTurnOff, groupsToTurnOn, groupsToUndo, } from '../core/remote-control.js';
 import { SHELLS } from '../core/shell-init.js';
-import { suggestAlias, suggestName } from '../panel/page-logic.js';
+import { inDisplayOrder, suggestAlias, suggestName } from '../panel/page-logic.js';
 import { createRuntime, UnknownFamilyError } from '../runtime.js';
 import { UsageError } from './args.js';
 import { c, clock, compactNumber, quotaText, table, tuningLines, usageText } from './format.js';
@@ -73,15 +73,21 @@ export function serializeDoctor(r) {
 function tilde(text, home) {
     return text.split(`${home}/`).join('~/');
 }
+/** Accounts in the Display Order the user gave them in the Panel (spec §3.25): Families first, then each one's. */
+function displayOrdered(accounts, rt) {
+    const d = rt.displayOrder();
+    const ids = inDisplayOrder([...new Set(accounts.map((x) => x.family))], (id) => id, d.families);
+    return ids.flatMap((id) => inDisplayOrder(accounts.filter((x) => x.family === id), (x) => x.name, d.accounts?.[id]));
+}
 export async function cmdList(a, io) {
     const rt = await createRuntime();
-    const accounts = await rt.accounts();
+    const accounts = displayOrdered(await rt.accounts(), rt);
     const [statuses, appProfiles] = await Promise.all([
         withDesktopApps(rt, accounts, Promise.all(accounts.map((x) => rt.status(x)))),
         listAppProfiles(rt),
     ]);
     const hasDesktop = statuses.some((s) => s.desktopApp);
-    const families = await rt.familyInfo();
+    const families = inDisplayOrder(await rt.familyInfo(), (f) => f.id, rt.displayOrder().families);
     if (a.flags.has('json')) {
         json(io, { families, accounts: statuses, appProfiles, pluginErrors: [...rt.pluginErrors] });
         return 0;
@@ -679,7 +685,14 @@ export async function cmdQuota(a, io) {
     if (sub === 'setup' || sub === 'teardown')
         return cmdQuotaSetup(a, io, sub);
     const rt = await createRuntime();
-    const accounts = sub ? [await rt.resolve(sub)] : await rt.accounts();
+    const accounts = !sub
+        ? displayOrdered(await rt.accounts(), rt)
+        : rt.families.has(sub)
+            ? displayOrdered(await rt.accounts(), rt).filter((x) => x.family === sub)
+            : [await rt.resolve(sub)];
+    // Asks the Families that fetch Quota again now (spec §3.26); a check that is turned off stays off.
+    if (a.flags.has('refresh'))
+        await rt.refreshQuota(accounts);
     const rows = await Promise.all(accounts.map(async (x) => ({
         ref: x.ref,
         kind: x.kind,
@@ -700,9 +713,12 @@ export async function cmdQuota(a, io) {
         `${quotaText(r.quota, now)}${r.quota.status === 'ok' && r.quota.from ? c.dim(` read from ${r.quota.from} (same login)`) : ''}`,
         usageText(r.usage),
     ]), ['ACCOUNT', 'QUOTA', `USAGE (${USAGE_DAYS}d)`]));
-    for (const r of rows)
+    for (const r of rows) {
         if (r.quota.status === 'unavailable' && r.quota.detail)
             io.out(c.dim(`${r.ref}: ${r.quota.detail}`));
+        if (r.quota.status === 'ok' && r.quota.fetchError)
+            io.out(c.dim(`${r.ref}: the latest check failed: ${r.quota.fetchError}`));
+    }
     // Suggest a setup only where it would help: the Family has one and its plan can be applied.
     const off = new Set(rows
         .filter((r) => r.quota.status === 'unavailable' && r.quota.reason === 'not-enabled')

package/dist/src/cli/format.js

@@ -44,12 +44,14 @@ export function clock(iso, now) {
     return sameDay ? hm : `${d.toLocaleDateString(undefined, { month: 'short', day: 'numeric' })} ${hm}`;
 }
 function windowText(w, now) {
+    // A window that covers only some models goes by their name (spec §3.26).
+    const label = w.name ?? w.label;
     if (Date.parse(w.resetsAt) <= now.getTime())
-        return `${w.label} reset`;
+        return `${label} reset`;
     const pct = Math.round(w.usedPercent);
     const level = quotaLevel(pct);
     const color = level === 'fail' ? c.red : level === 'warn' ? c.yellow : c.green;
-    return `${w.label} ${color(`${pct}%`)} ${c.dim(`→ ${clock(w.resetsAt, now)}`)}`;
+    return `${label} ${color(`${pct}%`)} ${c.dim(`→ ${clock(w.resetsAt, now)}`)}`;
 }
 export const QUOTA_REASON = {
     'not-enabled': 'off',
@@ -57,11 +59,13 @@ export const QUOTA_REASON = {
     unrecognized: 'unrecognized format',
     'no-source': 'no public source',
     'api-account': 'API account',
+    'fetch-failed': 'could not get it',
 };
 export function quotaText(q, now) {
     if (q.status === 'unavailable')
         return c.dim(QUOTA_REASON[q.reason] ?? q.reason);
-    return `${q.windows.map((w) => windowText(w, now)).join('  ')}  ${c.dim(ago(q.observedAt, now))}`;
+    const failed = q.fetchError ? c.yellow(' (latest check failed)') : '';
+    return `${q.windows.map((w) => windowText(w, now)).join('  ')}  ${c.dim(ago(q.observedAt, now))}${failed}`;
 }
 export function compactNumber(n) {
     if (n < 1000)

package/dist/src/cli/json-schemas.js

@@ -100,6 +100,9 @@ const Finding = Type.Object({
 });
 const QuotaWindow = Type.Object({
     label: Str,
+    name: Type.Optional(Type.String({
+        description: 'The group of models this limit covers, when it covers only some (spec §3.26); it does not count toward Quota Pressure.',
+    })),
     windowMinutes: Type.Number(),
     usedPercent: Type.Number(),
     resetsAt: Str,
@@ -114,8 +117,18 @@ const Quota = Type.Union([
         from: Type.Optional(Type.String({
             description: 'The account this reading was taken from, when it is another account of the same login (spec §3.21); observedAt is its time.',
         })),
+        fetched: Type.Optional(Type.Boolean({
+            description: 'This reading is the kept answer of a quota check that costs a request (spec §3.26).',
+        })),
+        fetchError: Type.Optional(Type.String({ description: 'Why the latest quota check failed, while this older reading is shown.' })),
+    }),
+    Type.Object({
+        status: Type.Literal('unavailable'),
+        reason: Type.String({
+            description: 'not-enabled, no-session, unrecognized, no-source, api-account or fetch-failed.',
+        }),
+        detail: Type.Optional(Str),
     }),
-    Type.Object({ status: Type.Literal('unavailable'), reason: Str, detail: Type.Optional(Str) }),
 ]);
 const TuningModel = Type.Object({
     model: Str,

package/dist/src/cli/main.js

@@ -23,11 +23,12 @@ Usage:
   sideby resume <family> [-- args]    run the host; a session resumed by id (claude --resume <id>,
                                       codex resume <id>) starts in the account that holds it
   sideby next <family> [--dry-run] [--include-api] [-- args]
-                                      recommend the account with the most quota left (claude, codex)
+                                      recommend the account with the most quota left (claude, codex, grok)
                                       and start it; --dry-run only recommends
   sideby doctor [target] [--fix] [--force]
                                       check shared items and permissions; --fix repairs safe issues
-  sideby quota [account]              quota and 7-day token usage
+  sideby quota [account|family] [--refresh]
+                                      quota and 7-day token usage; --refresh asks Grok again now
   sideby quota setup claude [--yes]   turn on Claude quota (shows the change first)
   sideby quota teardown claude        undo it, restoring the original file
   sideby tune [account|family]        estimate the cheapest auto-compact threshold per model
@@ -221,7 +222,7 @@ const COMMANDS = {
     new: { flags: ['api', 'json', 'next'], valued: ['alias'] },
     alias: { flags: ['json'] },
     doctor: { flags: ['fix', 'force', 'json'] },
-    quota: { flags: ['json', 'yes'] },
+    quota: { flags: ['json', 'yes', 'refresh'] },
     tune: { flags: ['json', 'yes'] },
     model: { flags: ['json', 'yes'], valued: ['effort'] },
     'remote-control': { flags: ['json', 'yes'] },

package/dist/src/core/config.d.ts

@@ -69,6 +69,13 @@ export declare const ConfigSchema: Type.TObject<{
     browser: Type.TOptional<Type.TObject<{
         signIns: Type.TOptional<Type.TBoolean>;
     }>>;
+    display: Type.TOptional<Type.TObject<{
+        families: Type.TOptional<Type.TArray<Type.TString>>;
+        accounts: Type.TOptional<Type.TRecord<"^.*$", Type.TArray<Type.TString>>>;
+    }>>;
+    quota: Type.TOptional<Type.TObject<{
+        check: Type.TOptional<Type.TRecord<"^.*$", Type.TBoolean>>;
+    }>>;
     shellInitFile: Type.TOptional<Type.TObject<{
         zsh: Type.TOptional<Type.TString>;
         bash: Type.TOptional<Type.TString>;
@@ -116,6 +123,26 @@ export declare function editConfigBrowser(file: string, edit: (current: BrowserC
     before: BrowserConfig | undefined;
     after: BrowserConfig | undefined;
 }>;
+export type DisplayConfig = NonNullable<Config['display']>;
+/**
+ * The Panel's drag and drop (spec §3.25): replaces the config `display` key, or removes it when `display` is undefined
+ * or empty (see `editConfigKey` for how the file is written).
+ */
+export declare function editConfigDisplay(file: string, display: DisplayConfig | undefined): Promise<{
+    changed: boolean;
+    before: DisplayConfig | undefined;
+    after: DisplayConfig | undefined;
+}>;
+export type QuotaConfig = NonNullable<Config['quota']>;
+/**
+ * The Panel's Quota check switch (spec §3.26): `false` writes `quota.check.<family>: false`, `true` removes that key
+ * (on is the default), and an empty `quota` goes away with it (see `editConfigKey` for how the file is written).
+ */
+export declare function editConfigQuotaCheck(file: string, family: string, on: boolean): Promise<{
+    changed: boolean;
+    before: QuotaConfig | undefined;
+    after: QuotaConfig | undefined;
+}>;
 export type AccountsConfig = NonNullable<Config['accounts']>;
 /**
  * `sideby model` (spec §3.19): changes the config `accounts` key with `edit` (see `editConfigKey` for how the file is

package/dist/src/core/config.js

@@ -106,6 +106,23 @@ export const ConfigSchema = Type.Object({
             description: "Look in Google Chrome's local data for which browser user signed in to each Account's website (key names only, never cookies or passwords; nothing leaves this computer). Off by default.",
         })),
     }, { additionalProperties: false, description: 'Browser Sign-ins (spec §3.24, ADR-0023).' })),
+    display: Type.Optional(Type.Object({
+        families: Type.Optional(Type.Array(Type.String({ minLength: 1 }), {
+            uniqueItems: true,
+            description: 'Family ids in the order the Panel and `sideby list` show them; families not listed follow in their usual order.',
+        })),
+        accounts: Type.Optional(Type.Record(Type.String(), Type.Array(Type.String({ minLength: 1 }), { uniqueItems: true }), {
+            description: 'Per family, account names (not refs or short commands) in the order they are shown; accounts not listed follow, main first, then by name.',
+        })),
+    }, {
+        additionalProperties: false,
+        description: 'Display Order (spec §3.25): the order you dragged families and accounts into in the Panel. Display only: it never changes which account a Handoff picks.',
+    })),
+    quota: Type.Optional(Type.Object({
+        check: Type.Optional(Type.Record(Type.String(), Type.Boolean(), {
+            description: 'Per family, whether sideby may ask for Quota in a way that costs a request (Grok: its own CLI asks xAI, at most every 15 minutes per account). On by default; `false` turns it off. Off in CI.',
+        })),
+    }, { additionalProperties: false, description: 'Quota that sideby asks for (spec §3.26, ADR-0025).' })),
     shellInitFile: Type.Optional(Type.Object({
         zsh: Type.Optional(Type.String({ minLength: 1 })),
         bash: Type.Optional(Type.String({ minLength: 1 })),
@@ -172,7 +189,7 @@ async function configTarget(file) {
 }
 /**
  * Re-reads the config file, lets `edit` change one top-level `key` (sideby writes only `aliases`, `handoff`,
- * `accounts`, `update` and `browser`, spec §3.10), and writes the result: every other key and their order kept (with `$schema`), 2-space JSON
+ * `accounts`, `update`, `browser`, `display` and `quota`, spec §3.10), and an `edit` that returns undefined removes it, and writes the result: every other key and their order kept (with `$schema`), 2-space JSON
  * with a trailing newline, atomically, keeping the file's mode (0600 for a new file). Refuses, without writing, a
  * file that is not valid JSON or not a valid config, a result that is not a valid config, or a file that changed
  * while sideby wrote it. `edit` returns null to leave the file alone; `dryRun` returns the change without writing.
@@ -211,6 +228,8 @@ async function editConfigKey(file, key, retry, edit, opts = {}) {
     const next = raw === null
         ? { $schema: 'https://unpkg.com/sideby/schemas/config.json', [key]: after }
         : { ...data, [key]: after };
+    if (after === undefined)
+        delete next[key];
     if (!Value.Check(ConfigSchema, next))
         throw new ConfigError(`the new ${key} would not match schemas/config.json`);
     const h = handoffSettings(next);
@@ -251,6 +270,34 @@ export function editConfigUpdate(file, edit, opts = {}) {
 export function editConfigBrowser(file, edit, opts = {}) {
     return editConfigKey(file, 'browser', 'change the setting', (current) => edit(current ?? {}), opts);
 }
+/**
+ * The Panel's drag and drop (spec §3.25): replaces the config `display` key, or removes it when `display` is undefined
+ * or empty (see `editConfigKey` for how the file is written).
+ */
+export function editConfigDisplay(file, display) {
+    const accounts = Object.fromEntries(Object.entries(display?.accounts ?? {}).filter(([, names]) => names.length));
+    const next = {
+        ...(display?.families?.length ? { families: [...display.families] } : {}),
+        ...(Object.keys(accounts).length ? { accounts } : {}),
+    };
+    return editConfigKey(file, 'display', 'move it again', () => (Object.keys(next).length ? next : undefined));
+}
+/**
+ * The Panel's Quota check switch (spec §3.26): `false` writes `quota.check.<family>: false`, `true` removes that key
+ * (on is the default), and an empty `quota` goes away with it (see `editConfigKey` for how the file is written).
+ */
+export function editConfigQuotaCheck(file, family, on) {
+    return editConfigKey(file, 'quota', 'change the setting', (current) => {
+        const check = { ...(current?.check ?? {}) };
+        if (on)
+            delete check[family];
+        else
+            check[family] = false;
+        const { check: _old, ...rest } = current ?? {};
+        const next = { ...rest, ...(Object.keys(check).length ? { check } : {}) };
+        return Object.keys(next).length ? next : undefined;
+    });
+}
 /**
  * `sideby model` (spec §3.19): changes the config `accounts` key with `edit` (see `editConfigKey` for how the file is
  * written). With `dryRun`, shows the change without writing.

package/dist/src/core/handoff-enable.js

@@ -25,11 +25,12 @@ async function throughLink(dir, rel) {
 }
 /**
  * The other Accounts of the Family that lack the hook file `file` (a path in the Main Account) at the same place in
- * their own directory. Only that one file is ever written, and one that is already there is left as it is: an
- * Account's other files are never touched.
+ * their own directory, or hold an earlier version of it that an older sideby wrote (`earlierTexts`). Only that one
+ * file is ever written; one with other content is left as it is, and an Account's other files are never touched.
  */
 async function hookCopies(rt, family, file) {
     const accounts = (await rt.accounts()).filter((a) => a.family === family);
+    const earlier = rt.families.get(family)?.handoff?.hookSetup?.earlierTexts ?? [];
     const main = accounts.find((a) => a.isMain);
     if (!main)
         return [];
@@ -43,9 +44,13 @@ async function hookCopies(rt, family, file) {
             continue;
         const target = join(a.dir, rel);
         // Whether the file is there, not whether it can be read: one that cannot be read is still not ours to replace.
-        const have = await lstat(target).then(() => true, () => false);
-        // A file that is already there is not ours to replace, whatever it says.
-        if (!have)
+        const st = await lstat(target).catch(() => null);
+        // A file that is already there is not ours to replace, unless it is, byte for byte, one an older sideby wrote.
+        if (!st)
+            out.push({ ref: a.ref, target });
+        else if (st.isFile() &&
+            earlier.length &&
+            earlier.includes(await readFile(target, 'utf8').catch(() => '')))
             out.push({ ref: a.ref, target });
     }
     return out;

package/dist/src/core/launch.d.ts

@@ -34,6 +34,11 @@ export declare function sidebyBinProblem(env: Env, why: string): Promise<string
  * copy the current env, clear Hijack Variables, merge the Secret File, set the select variable,
  * then let `launch.before` hooks adjust or abort. Never touches the caller's environment.
  */
+/**
+ * The Account's environment before its Secret File and Plugin hooks: `baseEnv` with the Hijack Variables cleared and
+ * the Family's `selectVar` set for every Account but the Main Account.
+ */
+export declare function accountEnv(family: FamilyDef, account: Account, baseEnv: Env): Env;
 export declare function prepareLaunch(opts: {
     account: Account;
     family: FamilyDef;

package/dist/src/core/launch.js

@@ -59,14 +59,25 @@ export async function sidebyBinProblem(env, why) {
  * copy the current env, clear Hijack Variables, merge the Secret File, set the select variable,
  * then let `launch.before` hooks adjust or abort. Never touches the caller's environment.
  */
-export async function prepareLaunch(opts) {
-    const { account, family } = opts;
-    const env = { ...opts.baseEnv };
+/**
+ * The Account's environment before its Secret File and Plugin hooks: `baseEnv` with the Hijack Variables cleared and
+ * the Family's `selectVar` set for every Account but the Main Account.
+ */
+export function accountEnv(family, account, baseEnv) {
+    const env = { ...baseEnv };
     for (const v of family.hijackVars)
         delete env[v];
     delete env[family.selectVar];
+    if (!account.isMain)
+        env[family.selectVar] = account.dir;
+    return env;
+}
+export async function prepareLaunch(opts) {
+    const { account, family } = opts;
+    const env = accountEnv(family, account, opts.baseEnv);
     if (account.secretFile)
         Object.assign(env, await readSecretFile(account.secretFile, opts.baseEnv));
+    // The Secret File may not move the Account: its directory always wins.
     if (!account.isMain)
         env[family.selectVar] = account.dir;
     // Which Account this is, for a status line, prompt or hook to show (spec §3.5); set for every Launch, so a value

package/dist/src/core/quota-fetch.d.ts

@@ -0,0 +1,22 @@
+import type { Account, Env, QuotaFetch, QuotaResult, ReadContext } from '../types.ts';
+import { type QuotaStoreEntry } from './quota-store.ts';
+/**
+ * `wait`: ask when the kept answer is old, and wait for it (the CLI). `background`: ask when old, but show the kept
+ * answer now (the Panel; with nothing kept it waits a few seconds). `force`: ask now, and wait (a refresh). `never`:
+ * the kept answer only.
+ */
+export type QuotaFetchMode = 'wait' | 'background' | 'force' | 'never';
+export declare const FETCH_TIMEOUT_MS = 20000;
+/** Why fetching is off for `family`, or null when it is on (spec §3.26). */
+export declare function quotaCheckOff(family: string, config: {
+    quota?: {
+        check?: Record<string, boolean>;
+    };
+}, env: Env): string | null;
+/** The kept answer for `account`, after asking again when `mode` and its age say so. */
+export declare function fetchedQuota(fq: QuotaFetch, account: Account, ctx: ReadContext, hostEnv: Env, mode: QuotaFetchMode): Promise<QuotaStoreEntry | null>;
+/**
+ * What sideby shows from a Family that fetches Quota: the newer of the kept answer and the local reading; else why
+ * there is none (`off` is why fetching is off, or null).
+ */
+export declare function shownQuota(local: QuotaResult | null, kept: QuotaStoreEntry | null, off: string | null): QuotaResult;

package/dist/src/core/quota-fetch.js

@@ -0,0 +1,98 @@
+import { keptQuota, quotaStoreFile, readQuotaStore, writeQuotaStore, } from './quota-store.js';
+import { inCi } from './update.js';
+export const FETCH_TIMEOUT_MS = 20_000;
+/** How long a `background` read waits when nothing is kept yet, so a first Panel load still shows Quota. */
+const FIRST_WAIT_MS = 4_000;
+/** One fetch per Account file at a time, shared by every reader in this process. */
+const inFlight = new Map();
+/** Why fetching is off for `family`, or null when it is on (spec §3.26). */
+export function quotaCheckOff(family, config, env) {
+    if (config.quota?.check?.[family] === false)
+        return `Quota checks are turned off for this tool (config quota.check.${family}); turn them on in the Panel's settings`;
+    if (inCi(env))
+        return 'Quota checks are off in CI';
+    return null;
+}
+const sleep = (ms) => new Promise((resolve) => {
+    setTimeout(() => resolve(null), ms).unref();
+});
+async function runFetch(fq, account, ctx, hostEnv, file) {
+    const kept = await readQuotaStore(file);
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), FETCH_TIMEOUT_MS);
+    const aborted = new Promise((_, reject) => {
+        ac.signal.addEventListener('abort', () => reject(new Error('aborted')), { once: true });
+    });
+    aborted.catch(() => { });
+    let answer;
+    let error;
+    try {
+        answer = await Promise.race([fq.fetch(account, { ...ctx, signal: ac.signal, hostEnv }), aborted]);
+    }
+    catch (err) {
+        error = ac.signal.aborted
+            ? `no answer within ${FETCH_TIMEOUT_MS / 1000} seconds; sideby asks again in ${fq.everyMinutes} minutes`
+            : (err?.message ?? String(err));
+    }
+    finally {
+        clearTimeout(timer);
+        if (!ac.signal.aborted)
+            ac.abort();
+    }
+    if (answer?.status === 'unavailable')
+        error = answer.detail ?? answer.reason;
+    const quota = answer?.status === 'ok' ? keptQuota(answer) : kept?.quota;
+    const entry = {
+        version: 1,
+        attemptedAt: new Date().toISOString(),
+        ...(quota ? { quota } : {}),
+        ...(error ? { error } : {}),
+    };
+    await writeQuotaStore(file, entry).catch(() => { });
+    return entry;
+}
+/** The kept answer for `account`, after asking again when `mode` and its age say so. */
+export async function fetchedQuota(fq, account, ctx, hostEnv, mode) {
+    const file = quotaStoreFile(ctx.stateDir, account.family, account.name);
+    const kept = await readQuotaStore(file);
+    if (mode === 'never')
+        return kept;
+    const at = kept ? Date.parse(kept.attemptedAt) : Number.NaN;
+    const age = ctx.now.getTime() - at;
+    // A time in the future (a changed clock) counts as old, so it cannot stop every later fetch.
+    const stale = !kept || !Number.isFinite(at) || age < -60_000 || age >= fq.everyMinutes * 60_000;
+    if (mode !== 'force' && !stale)
+        return kept;
+    let run = inFlight.get(file);
+    if (!run) {
+        run = runFetch(fq, account, ctx, hostEnv, file).finally(() => inFlight.delete(file));
+        inFlight.set(file, run);
+    }
+    if (mode !== 'background')
+        return run;
+    run.catch(() => { });
+    if (kept)
+        return kept;
+    return Promise.race([run, sleep(FIRST_WAIT_MS)]).then((e) => e ?? kept);
+}
+/**
+ * What sideby shows from a Family that fetches Quota: the newer of the kept answer and the local reading; else why
+ * there is none (`off` is why fetching is off, or null).
+ */
+export function shownQuota(local, kept, off) {
+    const fetched = kept?.quota
+        ? { ...kept.quota, fetched: true, ...(kept.error ? { fetchError: kept.error } : {}) }
+        : null;
+    const own = local?.status === 'ok' ? local : null;
+    if (fetched && own)
+        return Date.parse(own.observedAt) > Date.parse(fetched.observedAt) ? own : fetched;
+    if (fetched)
+        return fetched;
+    if (own)
+        return own;
+    if (off)
+        return { status: 'unavailable', reason: 'not-enabled', detail: off };
+    if (kept?.error)
+        return { status: 'unavailable', reason: 'fetch-failed', detail: kept.error };
+    return local ?? { status: 'unavailable', reason: 'no-session' };
+}

package/dist/src/core/quota-levels.d.ts

@@ -13,7 +13,8 @@ export declare function quotaLevel(usedPercent: number): QuotaLevel;
 export declare function windowReset(resetsAt: string, now: Date): boolean;
 /**
  * Quota Pressure: the used percent of the fullest window that has not reset yet (0 when all have reset),
- * or null when the Account has no Quota. The Panel keeps its own copy (`quotaPressure` in page-logic.ts,
- * -1 for null) because page-logic helpers must be self-contained; a test keeps the two equal.
+ * or null when the Account has no Quota. A window with a `name` covers only some models and never counts (spec
+ * §3.26). The Panel keeps its own copy (`quotaPressure` in page-logic.ts, -1 for null) because page-logic helpers
+ * must be self-contained; a test keeps the two equal.
  */
 export declare function quotaPressure(quota: QuotaResult | undefined, now: Date): number | null;

package/dist/src/core/quota-levels.js

@@ -20,14 +20,18 @@ export function windowReset(resetsAt, now) {
 }
 /**
  * Quota Pressure: the used percent of the fullest window that has not reset yet (0 when all have reset),
- * or null when the Account has no Quota. The Panel keeps its own copy (`quotaPressure` in page-logic.ts,
- * -1 for null) because page-logic helpers must be self-contained; a test keeps the two equal.
+ * or null when the Account has no Quota. A window with a `name` covers only some models and never counts (spec
+ * §3.26). The Panel keeps its own copy (`quotaPressure` in page-logic.ts, -1 for null) because page-logic helpers
+ * must be self-contained; a test keeps the two equal.
  */
 export function quotaPressure(quota, now) {
-    if (quota?.status !== 'ok' || quota.windows.length === 0)
+    if (quota?.status !== 'ok')
+        return null;
+    const windows = quota.windows.filter((w) => !w.name);
+    if (windows.length === 0)
         return null;
     let max = 0;
-    for (const w of quota.windows)
+    for (const w of windows)
         if (!windowReset(w.resetsAt, now))
             max = Math.max(max, Math.min(100, Number(w.usedPercent) || 0));
     return max;

package/dist/src/core/quota-store.d.ts

@@ -0,0 +1,19 @@
+import type { QuotaResult } from '../types.ts';
+export type FetchedQuota = Extract<QuotaResult, {
+    status: 'ok';
+}>;
+export interface QuotaStoreEntry {
+    version: 1;
+    /** When the latest fetch finished, good or not; the next one waits `everyMinutes` from here. */
+    attemptedAt: string;
+    /** The latest good answer, kept while later fetches fail. */
+    quota?: FetchedQuota;
+    /** Why the latest fetch failed, when it did. */
+    error?: string;
+}
+export declare function quotaStoreFile(stateDir: string, family: string, name: string): string;
+/** Only the fields a Quota reading may carry, so a plugin's extra fields never reach the file. */
+export declare function keptQuota(q: FetchedQuota): FetchedQuota;
+/** The kept answer, or null when there is none or the file is not one sideby wrote. */
+export declare function readQuotaStore(file: string): Promise<QuotaStoreEntry | null>;
+export declare function writeQuotaStore(file: string, entry: QuotaStoreEntry): Promise<void>;

package/dist/src/core/quota-store.js

@@ -0,0 +1,62 @@
+// The kept answers of `FamilyDef.fetchQuota` (spec §3.26): one file per Account in sideby's state directory, with the
+// Quota numbers, reset times and plan name only. The handoff hook reads it, so this module imports only Node
+// built-ins and leaf modules (never the Runtime, a Family index or core/accounts.ts).
+import { mkdir, readFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { writeFileAtomic } from './fs-safe.js';
+export function quotaStoreFile(stateDir, family, name) {
+    return join(stateDir, 'quota', family, `${name}.fetched.json`);
+}
+const isWindow = (w) => {
+    const v = w;
+    return (typeof v === 'object' &&
+        v !== null &&
+        typeof v.label === 'string' &&
+        (v.name === undefined || typeof v.name === 'string') &&
+        typeof v.windowMinutes === 'number' &&
+        typeof v.usedPercent === 'number' &&
+        typeof v.resetsAt === 'string');
+};
+/** Only the fields a Quota reading may carry, so a plugin's extra fields never reach the file. */
+export function keptQuota(q) {
+    return {
+        status: 'ok',
+        windows: q.windows.filter(isWindow).map((w) => ({
+            label: w.label,
+            ...(w.name ? { name: w.name } : {}),
+            windowMinutes: w.windowMinutes,
+            usedPercent: w.usedPercent,
+            resetsAt: w.resetsAt,
+        })),
+        observedAt: q.observedAt,
+        source: q.source,
+        ...(typeof q.plan === 'string' && q.plan ? { plan: q.plan } : {}),
+    };
+}
+/** The kept answer, or null when there is none or the file is not one sideby wrote. */
+export async function readQuotaStore(file) {
+    let data;
+    try {
+        data = JSON.parse(await readFile(file, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+    const e = data;
+    if (typeof e !== 'object' || e === null || e.version !== 1 || typeof e.attemptedAt !== 'string')
+        return null;
+    const q = e.quota;
+    const quota = q && q.status === 'ok' && Array.isArray(q.windows) && typeof q.observedAt === 'string'
+        ? keptQuota({ ...q, source: typeof q.source === 'string' ? q.source : '' })
+        : undefined;
+    return {
+        version: 1,
+        attemptedAt: e.attemptedAt,
+        ...(quota ? { quota } : {}),
+        ...(typeof e.error === 'string' ? { error: e.error } : {}),
+    };
+}
+export async function writeQuotaStore(file, entry) {
+    await mkdir(dirname(file), { recursive: true, mode: 0o700 });
+    await writeFileAtomic(file, `${JSON.stringify(entry)}\n`, 0o600);
+}

package/dist/src/core/skill-check.d.ts

@@ -1,5 +1,7 @@
 import type { FamilyDef, Finding } from '../types.ts';
 export declare const SKILL_INSTALL = "npx skills add Adonis0123/sideby -g";
+/** The folder holding `dir` that is a git work tree, if any: a skill there is managed by that repository. */
+export declare function gitRootOf(dir: string): Promise<string | null>;
 /** `metadata.version` from a SKILL.md frontmatter, or null when there is none. */
 export declare function skillVersionOf(text: string): string | null;
 /**