sideby 0.13.1 → 0.15.0

package/README.md

@@ -78,6 +78,7 @@ cc-switch's docs describe that switch: it writes the live settings file ([README
 | Find the cheapest auto-compact size from your own sessions, and use it in one click | `sideby tune` (or the panel's Context tuning tab) | [Context tuning](docs/guide/usage.md#context-tuning) |
 | See each account's model and effort, and set them per account | `sideby model <account>` (or click the model in the panel) | [Model and effort](docs/guide/usage.md#model-and-effort) |
 | Choose whether Claude sessions connect to claude.ai by themselves (Remote Control), for every account at once | `sideby remote-control off` or `on` (or the panel's Settings) | [Remote Control](docs/guide/usage.md#remote-control) |
+| Pin the accounts you use most and put tools and accounts in your own order | `sideby pin claude:work`, `sideby order` (or the panel's Settings) | [Your own order](docs/guide/usage.md#your-own-order) |
 | Move on when an account hits its limit | `sideby next claude` | [Handoff](docs/guide/usage.md#when-an-account-hits-its-limit) |
 | Let a running task move to the next account by itself when quota runs low (off by default; see the risk) | `sideby handoff enable` (or the panel) | [Auto Handoff](docs/guide/usage.md#auto-handoff) |
 | Short commands such as `ccw` | `sideby alias add ccw claude:work` | [Shell functions](docs/guide/configuration.md#shell-functions) |
@@ -94,7 +95,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":"20261017T115526-c6b039"}

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;
@@ -27,6 +27,8 @@ export declare function serializeDoctor(r: DoctorReport): {
     general: Omit<Finding, "fix">[];
     fixes: import("../core/doctor.ts").FixOutcome[];
 };
+export declare function cmdPin(a: ParsedArgs, io: Io, pin: boolean): Promise<number>;
+export declare function cmdOrder(a: ParsedArgs, io: Io): Promise<number>;
 export declare function cmdList(a: ParsedArgs, io: Io): Promise<number>;
 export interface NewSuggestion {
     name: string;

package/dist/src/cli/commands.js

@@ -2,10 +2,11 @@ import { fileURLToPath } from 'node:url';
 import { aliasesByAccount } from '../core/accounts.js';
 import { listAppProfiles, openAppProfile, parseProfileRef, removeAppProfile } from '../core/app-profiles.js';
 import { browserReport, openInBrowser, setBrowserSignIns } from '../core/browser-profiles.js';
-import { aliasRefs } from '../core/config.js';
+import { aliasRefs, editConfigUpdate } from '../core/config.js';
 import { openDesktopApp, withDesktopApps } from '../core/desktop-app.js';
 import { UserError } from '../core/errors.js';
 import { requestHandoff } from '../core/handoff-chain.js';
+import { handoffOverview } from '../core/handoff-overview.js';
 import { explain, readyDecision, runWithHandoff } from '../core/handoff-run.js';
 import { configureHandoff, handoffHint, handoffStatus } from '../core/handoff-status.js';
 import { installHint, runHost } from '../core/launch.js';
@@ -14,7 +15,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, pinnedIn, suggestAlias, suggestName, withPinned } 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 +74,158 @@ export function serializeDoctor(r) {
 function tilde(text, home) {
     return text.split(`${home}/`).join('~/');
 }
-export async function cmdList(a, io) {
+/** Accounts in the Display Order the user gave them in the Panel (spec §3.25): Families first, then each one's, Pinned Accounts leading. */
+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) => withPinned(inDisplayOrder(accounts.filter((x) => x.family === id), (x) => x.name, d.accounts?.[id]), d.pinned?.[id]));
+}
+/** Drop deleted accounts and unloaded Families only when saving a display change. */
+/**
+ * Groups the Display Order may name (spec §3.25): every Family, and every desktop app with windows of its own (Grok
+ * Bot, `grok-bot`), each with the names it holds.
+ */
+async function orderGroups(rt, accounts) {
+    const out = new Map();
+    for (const id of rt.families.keys())
+        out.set(id, accounts.filter((a) => a.family === id).map((a) => a.name));
+    for (const p of await listAppProfiles(rt)) {
+        const [id, name] = [p.ref.slice(0, p.ref.indexOf(':')), p.ref.slice(p.ref.indexOf(':') + 1)];
+        out.set(id, [...(out.get(id) ?? []), name]);
+    }
+    return out;
+}
+function cleanDisplay(rt, groups) {
+    const d = rt.displayOrder();
+    const clean = (lists) => Object.fromEntries(Object.entries(lists ?? {})
+        .filter(([id]) => groups.has(id))
+        .map(([id, names]) => [id, names.filter((name) => groups.get(id)?.includes(name))]));
+    return {
+        families: d.families?.filter((id) => groups.has(id)),
+        accounts: clean(d.accounts),
+        pinned: clean(d.pinned),
+    };
+}
+export async function cmdPin(a, io, pin) {
+    if (a.positionals.length !== 1 || a.rest.length)
+        throw new UsageError('usage: sideby pin|unpin <account|short command> [--json]');
     const rt = await createRuntime();
+    const account = await rt.resolve(a.positionals[0]);
     const accounts = await rt.accounts();
+    const d = cleanDisplay(rt, await orderGroups(rt, accounts));
+    const peers = new Set([account.ref, ...(await rt.sameLogin(account))]);
+    const names = accounts.filter((x) => peers.has(x.ref)).map((x) => x.name);
+    const pins = d.pinned?.[account.family] ?? [];
+    const already = names.some((name) => pins.includes(name));
+    if (pin && !already) {
+        const units = new Set();
+        for (const x of accounts.filter((x) => x.family === account.family && pins.includes(x.name))) {
+            units.add([x.ref, ...(await rt.sameLogin(x))].sort().join('|'));
+        }
+        if (units.size >= 3)
+            throw new UserError('At most 3 pinned logins per family; unpin one first with sideby unpin <account>.');
+    }
+    const next = pin
+        ? [...pins, ...names.filter((name) => !pins.includes(name))]
+        : pins.filter((name) => !names.includes(name));
+    d.pinned = { ...d.pinned, [account.family]: next };
+    const before = JSON.stringify(rt.displayOrder());
+    const display = await rt.setDisplayOrder(d);
+    const changed = before !== JSON.stringify(display);
+    const message = pin
+        ? already
+            ? 'Already pinned.'
+            : 'Pinned.'
+        : already
+            ? 'Unpinned.'
+            : 'Account is not pinned; nothing to change.';
+    if (a.flags.has('json'))
+        json(io, { ref: account.ref, pinned: pin, changed, message, display });
+    else
+        io.out(`${account.ref}: ${message}`);
+    return 0;
+}
+export async function cmdOrder(a, io) {
+    const reset = a.flags.has('reset');
+    const families = a.flags.has('families');
+    if (a.rest.length ||
+        (reset && (families || a.positionals.length)) ||
+        (families && !a.positionals.length) ||
+        (!reset && !families && a.positionals.length === 1))
+        throw new UsageError('usage: sideby order [--json] | <family> <name>... | --families <id>... | --reset');
+    const rt = await createRuntime();
+    const accounts = await rt.accounts();
+    if (reset || families || a.positionals.length) {
+        const groups = await orderGroups(rt, accounts);
+        let d = cleanDisplay(rt, groups);
+        if (reset)
+            d = { pinned: d.pinned };
+        else {
+            const [id, ...names] = a.positionals;
+            const requested = families ? a.positionals : names;
+            const unknown = families
+                ? requested.filter((x) => !groups.has(x))
+                : !groups.has(id)
+                    ? [id]
+                    : names.filter((name) => !groups.get(id)?.includes(name));
+            if (unknown.length)
+                throw new UserError(`Unknown ${families || !groups.has(id) ? 'families' : 'account names'}: ${unknown.join(', ')}; run sideby families or sideby list to choose existing names.`);
+            if (new Set(requested).size !== requested.length)
+                throw new UsageError('Names must not repeat; list each name once.');
+            if (families)
+                d.families = requested;
+            else
+                d.accounts = { ...d.accounts, [id]: names };
+        }
+        await rt.setDisplayOrder(d);
+    }
+    const display = rt.displayOrder();
+    const ordered = displayOrdered(accounts, rt);
+    const groups = await orderGroups(rt, accounts);
+    const rows = inDisplayOrder([...groups.keys()], (id) => id, display.families).map((family) => ({
+        family,
+        accounts: rt.families.has(family)
+            ? ordered
+                .filter((x) => x.family === family)
+                .map((x) => ({
+                name: x.name,
+                ref: x.ref,
+                pinned: display.pinned?.[family]?.includes(x.name) ?? false,
+            }))
+            : inDisplayOrder(groups.get(family) ?? [], (n) => n, display.accounts?.[family]).map((name) => ({
+                name,
+                ref: `${family}:${name}`,
+                pinned: false,
+            })),
+    }));
+    if (a.flags.has('json'))
+        json(io, { display, families: rows });
+    else
+        for (const row of rows)
+            io.out(`${row.family}: ${row.accounts.map((x) => `${x.name}${x.pinned ? ' (pinned)' : ''}`).join(', ') || '(no accounts)'}`);
+    return 0;
+}
+function onOff(value, usage) {
+    if (value !== 'on' && value !== 'off')
+        throw new UsageError(usage);
+    return value === 'on';
+}
+export async function cmdList(a, io) {
+    const rt = await createRuntime();
+    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),
+        withDesktopApps(rt, accounts, Promise.all(accounts.map((x) => rt.status(x)))).then((list) => list.map((s) => pinnedIn(s, rt.displayOrder().pinned?.[s.family] ?? []) ? { ...s, pinned: true } : s)),
+        // Desktop app windows in the Display Order too (spec §3.25), the main window first by default.
+        listAppProfiles(rt).then((list) => {
+            const d = rt.displayOrder();
+            const appOf = (ref) => ref.slice(0, ref.indexOf(':'));
+            const nameOf = (ref) => ref.slice(ref.indexOf(':') + 1);
+            const apps = inDisplayOrder([...new Set(list.map((p) => appOf(p.ref)))], (id) => id, d.families);
+            return apps.flatMap((app) => inDisplayOrder(list.filter((p) => appOf(p.ref) === app), (p) => nameOf(p.ref), d.accounts?.[app]));
+        }),
     ]);
     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;
@@ -676,10 +820,33 @@ export async function cmdTune(a, io) {
 }
 export async function cmdQuota(a, io) {
     const sub = a.positionals[0];
+    if (sub === 'check') {
+        const usage = 'usage: sideby quota check <family> on|off [--json]';
+        if (a.positionals.length !== 3 || a.rest.length || a.flags.has('refresh') || a.flags.has('yes'))
+            throw new UsageError(usage);
+        const on = onOff(a.positionals[2], usage);
+        const family = a.positionals[1];
+        const rt = await createRuntime();
+        if (!rt.quotaChecks().some((x) => x.family === family))
+            throw new UserError(`${family} has no quota fetcher; run sideby families to choose a family that fetches quota.`);
+        const r = await rt.setQuotaCheck(family, on);
+        if (a.flags.has('json'))
+            json(io, { family, on, ...r });
+        else
+            io.out(`${family}: quota checks ${on ? 'on' : 'off'}.`);
+        return 0;
+    }
     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 +867,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')
@@ -758,9 +928,10 @@ async function runSetup(a, io, rt, command, sub, familyId, setup) {
 }
 /** `sideby handoff status` (spec §3.17): what Auto Handoff still needs, with the commands to run. */
 async function cmdHandoffStatus(a, io) {
-    const st = await handoffStatus(await createRuntime());
+    const rt = await createRuntime();
+    const st = await handoffStatus(rt);
     if (a.flags.has('json')) {
-        json(io, st);
+        json(io, { ...st, overview: await handoffOverview(rt) });
         return 0;
     }
     io.out(`Auto Handoff: ${st.auto ? c.green('on') : c.yellow('off')} (same family ${st.sameFamily ? 'on' : 'off'}; brief at ${st.prepareAt}%, hand over at ${st.threshold}%)`);
@@ -1049,6 +1220,18 @@ export async function cmdUi(a, io) {
 export async function cmdUpdate(a, io) {
     if (a.positionals.length)
         throw new UsageError('usage: sideby update [--yes] [--json]');
+    if (a.flags.has('auto')) {
+        if (a.rest.length)
+            throw new UsageError('usage: sideby update --auto on|off [--json]');
+        const auto = onOff(a.flags.get('auto'), 'usage: sideby update --auto on|off [--json]');
+        const paths = resolvePaths(process.env);
+        const r = await editConfigUpdate(paths.configFile, (cur) => ({ ...cur, auto }));
+        if (a.flags.has('json'))
+            json(io, { auto, changed: r.changed });
+        else
+            io.out(`Auto Update ${auto ? 'on' : 'off'}${r.changed ? '.' : ' (unchanged).'}`);
+        return 0;
+    }
     const u = await import('../core/update.js');
     const { SKILL_INSTALL } = await import('../core/skill-check.js');
     const { backgroundPanelPort } = await import('../panel/background.js');
@@ -1075,7 +1258,7 @@ export async function cmdUpdate(a, io) {
             }
             if (!asJson)
                 io.out(c.dim(`$ ${sk.command}`));
-            const r = await u.applySkillUpdate(sk, process.env, asJson ? undefined : (t) => process.stderr.write(t));
+            const r = await u.applySkillOnly(paths, sk, process.env, asJson ? undefined : (t) => process.stderr.write(t));
             if (asJson)
                 json(io, { ...shown, updated: false, skillUpdated: r?.ok ?? false, message: r?.message ?? '' });
             else if (r?.ok)

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

@@ -3,6 +3,8 @@
 import { Type } from 'typebox';
 import { ConfigSchema } from '../core/config.js';
 const Str = Type.String();
+/** Why sideby cannot do something itself (spec §3.23); `reason` keeps the English text. */
+const ReasonCode = Type.Union(['local-build', 'npx', 'volta', 'not-writable', 'project', 'source', 'skill-in-git'].map((k) => Type.Literal(k)), { description: 'Why, as a code a page can say in its own language.' });
 const Level = Type.Union([Type.Literal('ok'), Type.Literal('warn'), Type.Literal('fail')]);
 const Kind = Type.Union([Type.Literal('subscription'), Type.Literal('api')]);
 const Version = Type.Literal(1);
@@ -39,6 +41,9 @@ const AccountStatus = Type.Intersect([
         sameLogin: Type.Optional(Type.Array(Str, {
             description: 'The other accounts signed in as the same login (same family, email and organization), which share one quota (spec §3.21). Absent when there are none.',
         })),
+        pinned: Type.Optional(Type.Literal(true, {
+            description: 'Pinned to the top of its family in the Panel and `sideby list` (spec §3.25). Display only; absent when not pinned.',
+        })),
         problems: Type.Optional(Type.Array(Str)),
         desktopApp: Type.Optional(Type.Object({ app: Str, installed: Type.Boolean(), running: Type.Boolean() }, {
             description: "The family's desktop app for this account (macOS, subscription accounts of claude and codex): whether it is installed and whether this account's own window runs now. Open it with `sideby desktop <account>`.",
@@ -100,6 +105,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 +122,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,
@@ -231,12 +249,90 @@ const Notice = Type.Object({
         }),
         current: Str,
         command: Type.String({
-            description: 'Updates the installed sideby skill (run it after the user agrees).',
+            description: '`sideby update`, which updates the skill with sideby: run it after the user agrees; it shows the plan and exits 10, then --yes.',
         }),
         message: Str,
     })),
 }, { description: 'Not the answer to the task: mention it briefly afterwards and offer to update.' });
+const Display = Type.Object({
+    families: Type.Optional(Type.Array(Str)),
+    accounts: Type.Optional(Type.Record(Str, Type.Array(Str))),
+    pinned: Type.Optional(Type.Record(Str, Type.Array(Str))),
+});
+const PinResult = Type.Object({
+    schemaVersion: Version,
+    ref: Str,
+    pinned: Type.Boolean(),
+    changed: Type.Boolean(),
+    message: Str,
+    display: Display,
+});
+const Skipped = Type.Optional(Type.Array(Type.Object({ ref: Str, reason: Str })));
+const Overview = Type.Object({
+    settings: Type.Object({
+        auto: Type.Boolean(),
+        sameFamily: Type.Boolean(),
+        prepareAt: Type.Number(),
+        threshold: Type.Number(),
+        waitIfResetWithinMinutes: Type.Number(),
+        countdownSeconds: Type.Number(),
+        crossOrganization: Type.Array(Str),
+        families: Type.Record(Str, Type.Object({
+            policy: Type.Union([Type.Literal('pressure'), Type.Literal('order')]),
+            order: Type.Array(Str),
+        })),
+    }),
+    takeover: Type.Array(Type.Object({
+        ref: Str,
+        family: Str,
+        starts: Type.Array(Type.Union([Type.Literal('quota'), Type.Literal('limit')])),
+        decision: Type.Union([
+            Type.Object({ kind: Type.Literal('pick'), ref: Str, skipped: Skipped }),
+            Type.Object({ kind: Type.Literal('wait'), until: Str }),
+            Type.Object({
+                kind: Type.Literal('none'),
+                reason: Str,
+                earliestReset: Type.Optional(Type.Object({ ref: Str, at: Str })),
+                skipped: Skipped,
+            }),
+        ]),
+    })),
+    recent: Type.Array(Type.Object({
+        from: Str,
+        to: Str,
+        at: Str,
+        trigger: Type.Union([
+            Type.Literal('threshold'),
+            Type.Literal('limit'),
+            Type.Literal('manual'),
+            Type.Null(),
+        ]),
+        briefSource: Type.Union([
+            Type.Literal('agent'),
+            Type.Literal('sideby'),
+            Type.Literal('user'),
+            Type.Null(),
+        ]),
+    })),
+});
 export const OUTPUT_SCHEMAS = {
+    pin: PinResult,
+    unpin: PinResult,
+    order: Type.Object({
+        schemaVersion: Version,
+        display: Display,
+        families: Type.Array(Type.Object({
+            family: Str,
+            accounts: Type.Array(Type.Object({ name: Str, ref: Str, pinned: Type.Boolean() })),
+        })),
+    }),
+    'quota-check': Type.Object({
+        schemaVersion: Version,
+        family: Str,
+        on: Type.Boolean(),
+        changed: Type.Boolean(),
+    }),
+    'update-auto': Type.Object({ schemaVersion: Version, auto: Type.Boolean(), changed: Type.Boolean() }),
     list: Type.Object({
         schemaVersion: Version,
         families: Type.Array(FamilyInfo),
@@ -383,6 +479,7 @@ export const OUTPUT_SCHEMAS = {
     'quota-setup': Type.Object({ schemaVersion: Version, family: Str, applied: Type.Boolean(), plan: QuotaSetupPlan }, { title: 'sideby quota setup --json' }),
     'handoff-status': Type.Object({
         schemaVersion: Version,
+        overview: Type.Optional(Overview),
         auto: Type.Boolean(),
         sameFamily: Type.Boolean(),
         prepareAt: Type.Number(),
@@ -569,9 +666,11 @@ export const OUTPUT_SCHEMAS = {
         latest: Type.String({ description: 'The `latest` version on the npm registry.' }),
         available: Type.Boolean({ description: '`latest` is newer than `current`.' }),
         method: Type.Object({
-            kind: Type.Union(['npm', 'pnpm', 'bun', 'volta', 'npx', 'project', 'source'].map((k) => Type.Literal(k)), { description: 'How this copy was installed.' }),
+            kind: Type.Union(['npm', 'pnpm', 'bun', 'volta', 'npx', 'project', 'source', 'local'].map((k) => Type.Literal(k)), { description: 'How this copy was installed.' }),
             canUpdate: Type.Boolean({ description: 'sideby can run the Update itself.' }),
             reason: Type.Optional(Type.String({ description: 'Why it cannot.' })),
+            reasonCode: Type.Optional(ReasonCode),
+            reasonAt: Type.Optional(Type.String({ description: 'The folders that are not writable (`not-writable`).' })),
         }),
         command: Type.String({
             description: 'What an Update runs, or what to run by hand when `canRun` is false.',
@@ -601,6 +700,8 @@ export const OUTPUT_SCHEMAS = {
                 description: 'False when sideby leaves the skill alone (see reason): give the user command.',
             }),
             reason: Type.Optional(Str),
+            reasonCode: Type.Optional(ReasonCode),
+            reasonAt: Type.Optional(Type.String({ description: 'The git repository that owns the skill (`skill-in-git`).' })),
         }, {
             description: 'The installed sideby skill, which the Update brings along; absent when none is installed.',
         })),

package/dist/src/cli/main.js

@@ -13,6 +13,14 @@ Usage:
                                       create an account (families: claude, codex, grok, pi);
                                       --next picks the next name and short command (cc008);
                                       --alias also adds a short command such as cc008
+  sideby pin|unpin <account|short command> [--json]
+                                      pin or unpin a Same Login (at most 3 per family)
+  sideby order [--json]               show display order, with pinned accounts marked
+  sideby order <family> <name>...     set account order within a family
+  sideby order --families <id>...     set family order
+  sideby order --reset               restore default order, keeping pins
+  sideby quota check <family> on|off  turn quota fetching on or off
+  sideby update --auto on|off         set Auto Update without running an update
   sideby families [family]            what each host's accounts share with the main account,
                                       where they live and how they sign in
   sideby alias add <short> <account> [-- args]
@@ -23,11 +31,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 every fetching family 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
@@ -214,6 +223,9 @@ export function nodeTooOld(version = process.versions.node) {
 }
 const COMMANDS = {
     list: { flags: ['json'] },
+    pin: { flags: ['json'] },
+    unpin: { flags: ['json'] },
+    order: { flags: ['json', 'families', 'reset'] },
     run: { flags: [] },
     resume: { flags: [] },
     login: { flags: [] },
@@ -221,7 +233,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'] },
@@ -236,7 +248,7 @@ const COMMANDS = {
     'shell-init': { flags: ['write'] },
     plugins: { flags: ['json'] },
     families: { flags: ['json'] },
-    update: { flags: ['json', 'yes'] },
+    update: { flags: ['json', 'yes'], valued: ['auto'] },
     'update-check': { flags: [] },
 };
 /** Commands that never print an Update Notice: their output is read by a shell or an agent, or they are internal. */
@@ -260,12 +272,13 @@ async function jsonNoticeFor() {
         const { resolvePaths } = await import('../core/paths.js');
         const { loadConfig } = await import('../core/config.js');
         const { packageVersion } = await import('../core/version.js');
-        const { installedSkillVersions, SKILL_INSTALL } = await import('../core/skill-check.js');
+        const { installedSkillVersions } = await import('../core/skill-check.js');
         const paths = resolvePaths(process.env);
         const config = await loadConfig(paths.configFile).catch(() => ({}));
         const cache = await u.readUpdateCache(paths);
         const skills = await installedSkillVersions(paths.home);
-        const n = u.jsonNotice(cache, packageVersion(), config, process.env, skills, SKILL_INSTALL);
+        // `sideby update` brings the skill along, so it is the one command for both (spec §3.23).
+        const n = u.jsonNotice(cache, packageVersion(), config, process.env, skills, 'sideby update');
         if (!u.checksOff(process.env, config) && u.checkDue(cache, new Date())) {
             const { spawn } = await import('node:child_process');
             const child = spawn(process.execPath, [fileURLToPath(import.meta.url), 'update-check'], {
@@ -296,7 +309,9 @@ async function afterCommand() {
         const paths = resolvePaths(process.env);
         const config = await loadConfig(paths.configFile).catch(() => ({}));
         const cache = await u.readUpdateCache(paths);
-        const plan = u.afterCommandPlan(cache, packageVersion(), config, process.env, new Date());
+        const current = packageVersion();
+        const skill = u.skillBehind(await u.skillUpdatePlan(paths.home, current).catch(() => null), current);
+        const plan = u.afterCommandPlan(cache, current, config, process.env, new Date(), skill);
         const dim = process.env.NO_COLOR ? (t) => t : (t) => `\x1b[2m${t}\x1b[22m`;
         for (const l of plan.lines)
             console.error(dim(l));
@@ -413,6 +428,11 @@ export async function main(argv) {
 }
 async function dispatch(cmd, parsed, io, cmds) {
     switch (cmd) {
+        case 'pin':
+        case 'unpin':
+            return await cmds.cmdPin(parsed, io, cmd === 'pin');
+        case 'order':
+            return await cmds.cmdOrder(parsed, io);
         case 'list':
             return await cmds.cmdList(parsed, io);
         case 'run':

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

@@ -69,6 +69,14 @@ 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>>>;
+        pinned: 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 +124,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