sideby 0.13.1 → 0.14.0

package/dist/src/core/skill-check.js

@@ -1,11 +1,25 @@
 // Doctor's look at an installed sideby Agent Skill (spec §3.11). Read-only: a skill written for another
 // sideby version teaches commands this CLI may not have, so a version mismatch is a warning with the
 // reinstall command. Not installed is not a problem.
-import { readFile, realpath } from 'node:fs/promises';
+import { readFile, realpath, stat } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { mainDirOf } from './accounts.js';
 import { tildify } from './paths.js';
 export 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 async function gitRootOf(dir) {
+    for (let d = dir;; d = dirname(d)) {
+        try {
+            await stat(join(d, '.git'));
+            return d;
+        }
+        catch {
+            // keep looking up
+        }
+        if (dirname(d) === d)
+            return null;
+    }
+}
 /** `metadata.version` from a SKILL.md frontmatter, or null when there is none. */
 export function skillVersionOf(text) {
     const front = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text)?.[1];
@@ -70,13 +84,17 @@ export async function checkInstalledSkills(home, families, version) {
         if (found === version)
             continue;
         const where = tildify(path, home);
+        // `sideby update` brings the skill along, except one a git repository owns (a dotfiles clone, say).
+        const repo = await gitRootOf(dirname(real));
         out.push({
             level: 'warn',
             account: `${family.id}:main`,
             item: where,
             code: 'skill.outdated',
             message: `the sideby skill at ${where} is ${found ? `for sideby ${found}` : 'from before skills had a version'}; this sideby is ${version}`,
-            hint: `update it with \`${SKILL_INSTALL}\`, so agents learn this version's commands`,
+            hint: repo
+                ? `it lives in the git repository ${tildify(repo, home)}: update it where that repository comes from (\`npx skills update sideby -g\` there), so agents learn this version's commands`
+                : `run \`sideby update\`, which updates the skill too (or \`${SKILL_INSTALL}\` by hand), so agents learn this version's commands`,
             source: 'core',
             fixable: false,
         });

package/dist/src/core/update.js

@@ -6,7 +6,7 @@ import { access, constants, mkdir, open, readdir, readFile, realpath, rm, stat }
 import { dirname, join, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { writeFileAtomic } from './fs-safe.js';
-import { installedSkills, SKILL_INSTALL, SKILL_UPDATE } from './skill-check.js';
+import { gitRootOf, installedSkills, SKILL_INSTALL, SKILL_UPDATE } from './skill-check.js';
 import { localBuild, packageVersion, parseLocalBuild } from './version.js';
 export const DEFAULT_REGISTRY = 'https://registry.npmjs.org';
 export const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
@@ -562,20 +562,6 @@ export function shownPlan(plan) {
         ...(plan.skill ? { skillUpdate: plan.skill } : {}),
     };
 }
-/** The folder holding `dir` that is a git work tree, if any: a skill there is managed by that repository. */
-async function gitRootOf(dir) {
-    for (let d = dir;; d = dirname(d)) {
-        try {
-            await stat(join(d, '.git'));
-            return d;
-        }
-        catch {
-            // keep looking up
-        }
-        if (dirname(d) === d)
-            return null;
-    }
-}
 /** The skill part of an Update toward `target`; null when no sideby skill is installed. Reads two files. */
 export async function skillUpdatePlan(home, target) {
     const skills = await installedSkills(home);

package/dist/src/families/grok/handoff-hook.d.ts

@@ -1,4 +1,10 @@
 import { type HookReader } from '../../handoff/reader.ts';
+import type { Env } from '../../types.ts';
+/** The Account the hook runs for, from `GROK_HOME`: unset or `~/.grok` is `main`, `.grok-<name>` is `<name>`. */
+export declare function grokAccountFromEnv(env: Env): {
+    name: string;
+    dir: string;
+} | null;
 /** Substrings that mean the usage pool or credits are used up. `StopFailure.error` has no class of its own for it. */
 export declare const GROK_USED_UP: string[];
 export declare const grokHookReader: HookReader;

package/dist/src/families/grok/handoff-hook.js

@@ -1,6 +1,28 @@
-// Grok Build for the handoff hook (spec §3.17): no public Quota, so only a turn that failed at the limit starts a
-// Handoff. Leaf module. The wording comes from the grok 1.0.50 binary; check it again when Grok changes.
+// Grok Build for the handoff hook (spec §3.17, §3.26): Quota Pressure from the kept answer of its CLI and the billing
+// lines it writes to its log, and a turn that failed at the limit. Leaf module: the hook runs on every tool call. The
+// wording comes from the grok 1.0.50 binary; check it again when Grok changes.
+import { homedir } from 'node:os';
+import { basename, join, resolve } from 'node:path';
+import { ACCOUNT_NAME } from '../../core/account-name.js';
+import { resolvePaths } from '../../core/paths.js';
+import { quotaPressure } from '../../core/quota-levels.js';
+import { quotaStoreFile, readQuotaStore } from '../../core/quota-store.js';
 import { field } from '../../handoff/reader.js';
+import { grokLogFile, HOOK_LOG_READ_BYTES, lastGrokBilling } from './quota-log.js';
+const MAIN_DIR = '.grok';
+const ACCOUNT_PREFIX = '.grok-';
+/** The Account the hook runs for, from `GROK_HOME`: unset or `~/.grok` is `main`, `.grok-<name>` is `<name>`. */
+export function grokAccountFromEnv(env) {
+    const home = env.HOME || homedir();
+    const dir = env.GROK_HOME;
+    if (!dir || resolve(dir) === join(home, MAIN_DIR))
+        return { name: 'main', dir: join(home, MAIN_DIR) };
+    const base = basename(dir);
+    if (!base.startsWith(ACCOUNT_PREFIX))
+        return null;
+    const name = base.slice(ACCOUNT_PREFIX.length);
+    return name !== 'main' && ACCOUNT_NAME.test(name) ? { name, dir } : null;
+}
 /** Substrings that mean the usage pool or credits are used up. `StopFailure.error` has no class of its own for it. */
 export const GROK_USED_UP = [
     'You hit your weekly limit',
@@ -15,6 +37,27 @@ export const GROK_USED_UP = [
     'status 402',
 ];
 export const grokHookReader = {
+    async pressure(_input, env, now) {
+        const account = grokAccountFromEnv(env);
+        if (!account)
+            return null;
+        try {
+            const [log, kept] = await Promise.all([
+                lastGrokBilling(grokLogFile(account.dir), HOOK_LOG_READ_BYTES),
+                readQuotaStore(quotaStoreFile(resolvePaths(env).stateDir, 'grok', account.name)),
+            ]);
+            const fetched = kept?.quota ?? null;
+            const newer = log && fetched
+                ? Date.parse(log.observedAt) > Date.parse(fetched.observedAt)
+                    ? log
+                    : fetched
+                : (log ?? fetched);
+            return newer ? quotaPressure(newer, now) : null;
+        }
+        catch {
+            return null;
+        }
+    },
     limitHit(input) {
         if (field(input, 'subagentType'))
             return false;

package/dist/src/families/grok/handoff.d.ts

@@ -41,7 +41,12 @@ export declare function grokEligibility(policy: ReturnType<typeof grokPolicy>, a
     start: boolean;
     receive: boolean;
 };
-/** The whole file setup writes; teardown removes it only while it is still exactly this. */
+/**
+ * The file sideby 0.13 and earlier wrote: no `PostToolUse`, since Grok had no Quota to prepare a Handoff from then.
+ * Setup replaces it, teardown removes it (spec §3.26).
+ */
+export declare const GROK_HOOK_FILE_V1: string;
+/** The whole file setup writes; teardown removes it only while it is still exactly this (or `GROK_HOOK_FILE_V1`). */
 export declare function grokHookFileText(): string;
 export declare const grokHookSetup: QuotaSetup;
 export declare const grokHandoff: FamilyHandoff;

package/dist/src/families/grok/handoff.js

@@ -1,5 +1,5 @@
-// How Grok Build takes part in a Handoff (spec §3.17). It has no public Quota, so it starts one only after a turn
-// failed at the limit. Interactive `grok` has no launch option for hooks: `sideby handoff setup grok` adds
+// How Grok Build takes part in a Handoff (spec §3.17). Since its Quota comes from its own CLI (spec §3.26), it starts
+// one at the Handoff Threshold, and still after a turn failed at the limit. Interactive `grok` has no launch option for hooks: `sideby handoff setup grok` adds
 // `hooks/sideby-handoff.json` to the Main Account and Doctor copies it to the others (verified 2026-10-09).
 // The hook inherits Grok's sandbox, so the profile decides whether a run may start or receive.
 import { mkdir, readFile, rm, rmdir } from 'node:fs/promises';
@@ -124,10 +124,22 @@ export function grokEligibility(policy, args, home) {
     };
 }
 const hookCommand = (event) => `sideby handoff-hook grok ${event}`;
-/** The whole file setup writes; teardown removes it only while it is still exactly this. */
+/**
+ * The file sideby 0.13 and earlier wrote: no `PostToolUse`, since Grok had no Quota to prepare a Handoff from then.
+ * Setup replaces it, teardown removes it (spec §3.26).
+ */
+export const GROK_HOOK_FILE_V1 = `${JSON.stringify({
+    hooks: {
+        Stop: [{ hooks: [{ type: 'command', command: hookCommand('Stop') }] }],
+        StopFailure: [{ hooks: [{ type: 'command', command: hookCommand('StopFailure'), timeout: 60 }] }],
+    },
+}, null, 2)}\n`;
+/** The whole file setup writes; teardown removes it only while it is still exactly this (or `GROK_HOOK_FILE_V1`). */
 export function grokHookFileText() {
     const hooks = {
         hooks: {
+            // Quota Pressure after each tool call, to prepare and start a Handoff before the limit (spec §3.26).
+            PostToolUse: [{ hooks: [{ type: 'command', command: hookCommand('PostToolUse') }] }],
             Stop: [{ hooks: [{ type: 'command', command: hookCommand('Stop') }] }],
             // Observation hooks get 5 seconds by default; putting a Brief together may take longer.
             StopFailure: [{ hooks: [{ type: 'command', command: hookCommand('StopFailure'), timeout: 60 }] }],
@@ -143,7 +155,8 @@ async function plan(ctx) {
     const have = await textOrNull(file);
     if (have === want)
         return { status: 'enabled', file, diff: '', message: `already set up in ${shown}` };
-    if (have !== null)
+    const upgrade = have === GROK_HOOK_FILE_V1;
+    if (have !== null && !upgrade)
         return {
             status: 'blocked',
             file,
@@ -153,19 +166,22 @@ async function plan(ctx) {
     const problem = await sidebyBinProblem(ctx.env, 'Grok runs `sideby handoff-hook` when a turn ends');
     if (problem)
         return { status: 'blocked', file, diff: '', message: problem };
+    const lines = (text, mark) => text
+        .trimEnd()
+        .split('\n')
+        .map((l) => `${mark}${l}`)
+        .join('\n');
     return {
         status: 'ready',
         file,
-        diff: `--- /dev/null\n+++ ${shown}\n${want
-            .trimEnd()
-            .split('\n')
-            .map((l) => `+${l}`)
-            .join('\n')}\n`,
-        message: `adds ${shown} so Grok tells sideby when a turn hits the usage limit; then run \`sideby doctor grok --fix\` to copy it to every Grok account; undo with \`sideby handoff teardown grok\``,
+        diff: upgrade
+            ? `--- ${shown}\n+++ ${shown}\n${lines(have, '-')}\n${lines(want, '+')}\n`
+            : `--- /dev/null\n+++ ${shown}\n${lines(want, '+')}\n`,
+        message: `${upgrade ? 'updates' : 'adds'} ${shown} so Grok tells sideby how full its quota is after each tool call and when a turn hits the usage limit; then run \`sideby doctor grok --fix\` to copy it to every Grok account; undo with \`sideby handoff teardown grok\``,
     };
 }
 export const grokHookSetup = {
-    summary: 'Adds one sideby hook file to ~/.grok/hooks so a Grok session that hits its usage limit can hand over.',
+    summary: 'Adds one sideby hook file to ~/.grok/hooks so a Grok session can hand over when its quota runs low or hits the limit.',
     plan,
     async apply(ctx) {
         const p = await plan(ctx);
@@ -175,13 +191,14 @@ export const grokHookSetup = {
         await writeFileAtomic(p.file, grokHookFileText(), 0o644);
         return { ...p, status: 'enabled' };
     },
+    earlierTexts: [GROK_HOOK_FILE_V1],
     async teardown(ctx) {
         const file = hookFile(ctx);
         const shown = tildify(file, ctx.home);
         const have = await textOrNull(file);
         if (have === null)
             return { ok: true, message: `${shown} is not there; nothing to undo` };
-        if (sha256(have) !== sha256(grokHookFileText()))
+        if (sha256(have) !== sha256(grokHookFileText()) && have !== GROK_HOOK_FILE_V1)
             return {
                 ok: false,
                 message: `${shown} changed since setup; delete it yourself if you no longer want it`,
@@ -196,7 +213,7 @@ export const grokHookSetup = {
     },
 };
 export const grokHandoff = {
-    starts: ['limit'],
+    starts: ['quota', 'limit'],
     promptArgs: promptAfterDashes,
     continueArgs: (args) => carryArgs(args, GROK_ARGS),
     resumeArgs: (id) => ['--resume', id],

package/dist/src/families/grok/index.js

@@ -5,6 +5,8 @@ import { BUILTIN_LOGOS } from '../logos.js';
 import { groupedEntryWrittenAt, resumeFlagSession } from '../shared/sessions.js';
 import { topLevelTomlString } from '../shared/toml.js';
 import { grokHandoff } from './handoff.js';
+import { grokQuotaFetch } from './quota.js';
+import { readGrokLogQuota } from './quota-log.js';
 // Grok's sandbox rejects these paths when they are symlinks; doctor quotes the Host's own words.
 const HOOKS_DIR_MESSAGE = 'Grok hooks directory has wrong type (expected real directory)';
 const REAL_FILE_MESSAGE = 'Grok hooks-paths registry has wrong type (expected real file)';
@@ -71,6 +73,9 @@ export const grokFamily = {
     },
     model: readModel,
     identity: grokIdentity,
+    // Quota (spec §3.26, ADR-0025): Grok's own billing lines in its log, and its CLI asked at most every 15 minutes.
+    readQuota: (account) => readGrokLogQuota(account.dir),
+    fetchQuota: grokQuotaFetch,
     resumedSession: resumeFlagSession,
     handoff: grokHandoff,
     // One directory per session, grouped by working directory: sessions/<encoded cwd>/<id>/.

package/dist/src/families/grok/quota-log.d.ts

@@ -0,0 +1,30 @@
+import { FileMemo } from '../../core/file-memo.ts';
+import type { QuotaResult, QuotaWindow } from '../../types.ts';
+export type GrokQuota = Extract<QuotaResult, {
+    status: 'ok';
+}>;
+export declare const GROK_BILLING_MSG = "billing: fetched credits config";
+/** How far back the CLI and the Panel look (Grok halves the file at 5 MB) and how far the handoff hook does. */
+export declare const LOG_READ_BYTES: number;
+export declare const HOOK_LOG_READ_BYTES: number;
+export declare function grokLogFile(accountDir: string): string;
+/**
+ * A Quota reading from Grok's billing answer: `{ config, subscription_tier }` from `_x.ai/billing`, or the log line's
+ * `ctx` (`{ config, subscriptionTier }`). Null when it holds no usable window.
+ */
+export declare function grokQuota(answer: unknown, observedAt: string, source: string): GrokQuota | null;
+/** The newest billing line in the last `maxBytes` of `file`, read backwards a chunk at a time; null when none. */
+export declare function lastGrokBilling(file: string, maxBytes: number, source?: string): Promise<GrokQuota | null>;
+/** The log's reading per Account directory; the file is read again only after it changed. */
+export declare const grokQuotaMemo: FileMemo<{
+    status: 'ok';
+    windows: QuotaWindow[];
+    observedAt: string;
+    source: string;
+    plan?: string;
+    from?: string;
+    fetched?: boolean;
+    fetchError?: string;
+} | null>;
+/** Grok's local Quota for one Account directory: its newest billing line. */
+export declare function readGrokLogQuota(accountDir: string): Promise<QuotaResult>;

package/dist/src/families/grok/quota-log.js

@@ -0,0 +1,140 @@
+// Grok Build's Quota (spec §3.26, ADR-0025): how its billing answer becomes a Quota reading, and the local copy Grok
+// writes into `$GROK_HOME/logs/unified.jsonl` at every session start and finished turn. Other lines of that file carry
+// the user id and the end of the bearer token, so only lines whose `msg` is exactly the billing one are parsed, and
+// only the Quota fields and the plan name are kept. Leaf module: the handoff hook reads the log too.
+import { open, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { FileMemo } from '../../core/file-memo.js';
+export const GROK_BILLING_MSG = 'billing: fetched credits config';
+const WEEKLY = 'USAGE_PERIOD_TYPE_WEEKLY';
+const WEEK_MINUTES = 7 * 24 * 60;
+const CHUNK = 64 * 1024;
+/** How far back the CLI and the Panel look (Grok halves the file at 5 MB) and how far the handoff hook does. */
+export const LOG_READ_BYTES = 8 * 1024 * 1024;
+export const HOOK_LOG_READ_BYTES = 512 * 1024;
+export function grokLogFile(accountDir) {
+    return join(accountDir, 'logs', 'unified.jsonl');
+}
+const record = (v) => typeof v === 'object' && v !== null && !Array.isArray(v) ? v : {};
+const num = (v) => {
+    const n = typeof v === 'string' && v.trim() ? Number(v) : v;
+    return typeof n === 'number' && Number.isFinite(n) ? n : undefined;
+};
+const str = (v) => (typeof v === 'string' && v ? v : undefined);
+/**
+ * A Quota reading from Grok's billing answer: `{ config, subscription_tier }` from `_x.ai/billing`, or the log line's
+ * `ctx` (`{ config, subscriptionTier }`). Null when it holds no usable window.
+ */
+export function grokQuota(answer, observedAt, source) {
+    const top = record(answer);
+    const config = record(top.config);
+    const period = record(config.currentPeriod);
+    const weekly = period.type === WEEKLY;
+    const end = Date.parse(str(period.end) ?? str(config.billingPeriodEnd) ?? '');
+    if (!Number.isFinite(end))
+        return null;
+    const start = Date.parse(str(period.start) ?? str(config.billingPeriodStart) ?? '');
+    let used = num(config.creditUsagePercent) ?? num(top.creditUsagePercent);
+    if (used === undefined) {
+        const spent = num(record(config.used).val);
+        const limit = num(record(config.monthlyLimit).val);
+        if (spent !== undefined && limit)
+            used = (spent / limit) * 100;
+        else if (weekly)
+            used = 0;
+    }
+    if (used === undefined)
+        return null;
+    let minutes = Number.isFinite(start) && end > start ? Math.round((end - start) / 60_000) : undefined;
+    if (weekly)
+        minutes = WEEK_MINUTES;
+    if (minutes === undefined)
+        return null;
+    const days = Math.max(1, Math.round(minutes / 1440));
+    const window = {
+        label: minutes === WEEK_MINUTES ? '7d' : `${days}d`,
+        windowMinutes: minutes,
+        usedPercent: Math.max(0, Math.min(100, used)),
+        resetsAt: new Date(end).toISOString(),
+    };
+    const plan = str(top.subscription_tier) ?? str(top.subscriptionTier);
+    return { status: 'ok', windows: [window], observedAt, source, ...(plan ? { plan } : {}) };
+}
+/** The Quota of one log line, or null for every line that is not Grok's billing line. */
+function billingLine(line, source) {
+    // A cheap check first: most lines are never parsed.
+    if (!line.includes(GROK_BILLING_MSG))
+        return null;
+    let data;
+    try {
+        data = record(JSON.parse(line));
+    }
+    catch {
+        return null;
+    }
+    const ts = str(data.ts);
+    if (data.msg !== GROK_BILLING_MSG || !ts || !Number.isFinite(Date.parse(ts)))
+        return null;
+    const ctx = record(data.ctx);
+    return grokQuota({ config: ctx.config, subscriptionTier: ctx.subscriptionTier }, new Date(Date.parse(ts)).toISOString(), source);
+}
+/** The newest billing line in the last `maxBytes` of `file`, read backwards a chunk at a time; null when none. */
+export async function lastGrokBilling(file, maxBytes, source = file) {
+    let fh;
+    try {
+        fh = await open(file, 'r');
+    }
+    catch {
+        return null;
+    }
+    try {
+        const size = (await fh.stat()).size;
+        let pos = size;
+        // The start of the earliest line read so far, which may continue in the chunk before it.
+        let head = Buffer.alloc(0);
+        while (pos > 0 && size - pos < maxBytes) {
+            const len = Math.min(CHUNK, pos);
+            pos -= len;
+            const buf = Buffer.alloc(len);
+            await fh.read(buf, 0, len, pos);
+            const chunk = Buffer.concat([buf, head]);
+            const cut = pos > 0 ? chunk.indexOf(0x0a) : -1;
+            head = cut >= 0 ? chunk.subarray(0, cut) : Buffer.alloc(0);
+            const lines = chunk
+                .subarray(cut + 1)
+                .toString('utf8')
+                .split('\n');
+            for (let i = lines.length - 1; i >= 0; i--) {
+                const q = billingLine(lines[i], source);
+                if (q)
+                    return q;
+            }
+        }
+        return null;
+    }
+    finally {
+        await fh.close();
+    }
+}
+/** The log's reading per Account directory; the file is read again only after it changed. */
+export const grokQuotaMemo = new FileMemo();
+/** Grok's local Quota for one Account directory: its newest billing line. */
+export async function readGrokLogQuota(accountDir) {
+    const file = grokLogFile(accountDir);
+    const none = {
+        status: 'unavailable',
+        reason: 'no-session',
+        detail: 'Grok has not reported the quota of this account yet',
+    };
+    let st;
+    try {
+        st = await stat(file);
+    }
+    catch {
+        return none;
+    }
+    const memo = grokQuotaMemo.pass(accountDir);
+    const q = await memo.get(file, st, () => lastGrokBilling(file, LOG_READ_BYTES, 'logs/unified.jsonl'));
+    memo.done();
+    return q ?? none;
+}

package/dist/src/families/grok/quota.d.ts

@@ -0,0 +1,5 @@
+import type { Account, QuotaFetch, QuotaFetchContext, QuotaResult } from '../../types.ts';
+export declare const GROK_QUOTA_ARGS: readonly ['agent', '--no-leader', 'stdio'];
+export declare const GROK_BILLING_METHOD = "_x.ai/billing";
+export declare function fetchGrokQuota(account: Account, ctx: QuotaFetchContext): Promise<QuotaResult>;
+export declare const grokQuotaFetch: QuotaFetch;

package/dist/src/families/grok/quota.js

@@ -0,0 +1,112 @@
+// Asks the Grok CLI for an Account's Quota (spec §3.26, ADR-0025): `grok agent --no-leader stdio` answers the ACP
+// extension method `_x.ai/billing` with the request it makes itself, using the login of the `GROK_HOME` it runs under.
+// sideby never reads the token and never sends a request of its own; no session is started.
+import { spawn } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import { createInterface } from 'node:readline';
+import { grokQuota } from './quota-log.js';
+export const GROK_QUOTA_ARGS = ['agent', '--no-leader', 'stdio'];
+export const GROK_BILLING_METHOD = '_x.ai/billing';
+/** How long Grok may take to exit after its stdin closes before sideby ends it. */
+const EXIT_GRACE_MS = 10_000;
+/** How long to wait before asking again after a failed answer, while Grok refreshes an expired token. */
+const RETRY_MS = 1500;
+const METHOD_NOT_FOUND = -32601;
+const AUTH_REQUIRED = -32000;
+const failed = (detail) => ({ status: 'unavailable', reason: 'fetch-failed', detail });
+/** Why an error answer gave no Quota, and what to do. Grok's own message is never repeated (only matched). */
+function errorDetail(account, error) {
+    if (error.code === METHOD_NOT_FOUND)
+        return 'this Grok version cannot report the quota; update Grok, then refresh';
+    if (error.code === AUTH_REQUIRED) {
+        const text = `${typeof error.data === 'string' ? error.data : ''} ${typeof error.message === 'string' ? error.message : ''}`;
+        if (text.includes('grok.com'))
+            return 'this account is signed in with an API key, which has no subscription quota';
+        return `Grok is not signed in for this account; run \`sideby login ${account.ref}\``;
+    }
+    return `Grok could not get the quota from xAI (error ${typeof error.code === 'number' ? error.code : 'unknown'}); sideby asks again later, or start Grok in this account once`;
+}
+export async function fetchGrokQuota(account, ctx) {
+    if (ctx.signal.aborted)
+        return failed('the quota check was stopped');
+    const child = spawn('grok', [...GROK_QUOTA_ARGS], {
+        cwd: tmpdir(),
+        env: { ...ctx.hostEnv, GROK_DISABLE_AUTOUPDATER: '1' },
+        stdio: ['pipe', 'pipe', 'ignore'],
+    });
+    const stop = () => {
+        if (child.exitCode === null && child.signalCode === null)
+            child.kill('SIGTERM');
+    };
+    const finish = () => {
+        // Grok exits by itself once its stdin closes; it is ended only when it does not.
+        child.stdin.end();
+        const timer = setTimeout(stop, EXIT_GRACE_MS);
+        timer.unref();
+        child.once('exit', () => clearTimeout(timer));
+        child.unref();
+    };
+    ctx.signal.addEventListener('abort', stop, { once: true });
+    try {
+        return await new Promise((resolve) => {
+            const lines = createInterface({ input: child.stdout });
+            let done = false;
+            const settle = (r) => {
+                if (done)
+                    return;
+                done = true;
+                lines.close();
+                resolve(r);
+            };
+            child.on('error', (err) => settle(failed(err.code === 'ENOENT'
+                ? 'Grok is not installed or not on PATH; install it, then refresh'
+                : `could not start Grok (${err.code ?? 'error'})`)));
+            // `close` comes after the last stdout line, so an answer written just before exiting still counts.
+            child.on('close', () => settle(failed('Grok exited without answering; sideby asks again later')));
+            ctx.signal.addEventListener('abort', () => settle(failed('the quota check was stopped')), {
+                once: true,
+            });
+            child.stdin.on('error', () => { });
+            let id = 1;
+            const ask = () => child.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', id, method: GROK_BILLING_METHOD, params: {} })}\n`);
+            lines.on('line', (line) => {
+                let msg;
+                try {
+                    msg = JSON.parse(line);
+                }
+                catch {
+                    return;
+                }
+                if (msg?.id !== id)
+                    return;
+                if (msg.error && typeof msg.error === 'object') {
+                    const error = msg.error;
+                    // A login whose token just expired fails once: Grok sends the old token and refreshes it as it starts
+                    // (seen 2026-10-17), so the same process is asked once more after a moment.
+                    if (id === 1 && error.code !== METHOD_NOT_FOUND && error.code !== AUTH_REQUIRED) {
+                        id = 2;
+                        setTimeout(() => {
+                            if (!done)
+                                ask();
+                        }, RETRY_MS).unref();
+                        return;
+                    }
+                    settle(failed(errorDetail(account, error)));
+                    return;
+                }
+                const q = grokQuota(msg.result, ctx.now.toISOString(), 'grok agent');
+                settle(q ?? failed('Grok answered in a form sideby does not recognise; update sideby'));
+            });
+            ask();
+        });
+    }
+    finally {
+        ctx.signal.removeEventListener('abort', stop);
+        finish();
+    }
+}
+export const grokQuotaFetch = {
+    everyMinutes: 15,
+    summary: "Grok asks xAI for each account's weekly quota, at most every 15 minutes",
+    fetch: fetchGrokQuota,
+};

package/dist/src/panel/handler.d.ts

@@ -1,11 +1,11 @@
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import { type AppProfileStatus } from '../core/app-profiles.ts';
 import { type BrowserReport } from '../core/browser-profiles.ts';
-import { type HandoffSettings } from '../core/config.ts';
+import { type DisplayConfig, type HandoffSettings } from '../core/config.ts';
 import { type AccountModel } from '../core/model-choice.ts';
 import type { RemoteControlGroup } from '../core/remote-control.ts';
 import * as update from '../core/update.ts';
-import type { AccountStatus, DoctorHistory, FamilyInfo, Runtime } from '../runtime.ts';
+import type { AccountStatus, DoctorHistory, FamilyInfo, QuotaCheckInfo, Runtime } from '../runtime.ts';
 import type { Account, FamilyLogo, QuotaResult, QuotaSetupPlan, UsageResult } from '../types.ts';
 import { type PanelTheme } from './theme.ts';
 export declare const PANEL_VERSION: string;
@@ -140,6 +140,10 @@ export interface PanelState {
      * Absent without Claude, Codex or Grok subscription Accounts. Nothing of the browser is read while `enabled` is false.
      */
     browser?: BrowserReport;
+    /** Display Order (spec §3.25): config `display` as it is, an empty object when the user never dragged. */
+    display: DisplayConfig;
+    /** Families that ask for Quota in a way that costs a request (spec §3.26), with their switch; absent when none. */
+    quotaChecks?: QuotaCheckInfo[];
 }
 /** The `handoff` map of the Panel state, from the statuses and Quota already read for the page. */
 export declare function handoffByFamily(rt: Runtime, accounts: readonly PanelAccount[], now: Date): Record<string, string>;