sideby 0.14.0 → 0.16.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) |

package/dist/build.json

@@ -1 +1 @@
-{"id":"20261017T050946-402d73"}
+{"id":"20261017T131419-98017e"}

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

@@ -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;
@@ -69,6 +71,11 @@ export declare function cmdUi(a: ParsedArgs, io: Io): Promise<number>;
 export declare function cmdUpdate(a: ParsedArgs, io: Io): Promise<number>;
 /** The internal `sideby update-check` the CLI starts detached: one Update Check, then Auto Update if it is on. */
 export declare function cmdUpdateCheck(_a: ParsedArgs, _io: Io): Promise<number>;
+/**
+ * `sideby local [on|off]` (ADR-0024): which side the global `sideby` runs, and a switch between the newest Local
+ * Build (`pnpm local` builds it) and the npm package. Shows the change first and exits 10 without `--yes`.
+ */
+export declare function cmdLocal(a: ParsedArgs, io: Io): Promise<number>;
 export declare function cmdApp(a: ParsedArgs, io: Io): Promise<number>;
 /**
  * `sideby desktop <account>`: the Family's Desktop App as that Account (spec §3.20); `sideby desktop grok-bot:<name>`:

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 { inDisplayOrder, 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,18 +74,155 @@ 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. */
+/** 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) => inDisplayOrder(accounts.filter((x) => x.family === id), (x) => x.name, d.accounts?.[id]));
+    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 = inDisplayOrder(await rt.familyInfo(), (f) => f.id, rt.displayOrder().families);
@@ -682,6 +820,22 @@ 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();
@@ -774,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}%)`);
@@ -1065,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');
@@ -1091,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)
@@ -1179,6 +1346,89 @@ export async function cmdUpdateCheck(_a, _io) {
     await backgroundCheck(paths, process.env, config, () => backgroundPanelPort(paths));
     return 0;
 }
+/**
+ * `sideby local [on|off]` (ADR-0024): which side the global `sideby` runs, and a switch between the newest Local
+ * Build (`pnpm local` builds it) and the npm package. Shows the change first and exits 10 without `--yes`.
+ */
+export async function cmdLocal(a, io) {
+    const usage = 'usage: sideby local [on|off] [--yes] [--json]';
+    const sub = a.positionals[0];
+    if (a.positionals.length > 1 || (sub !== undefined && sub !== 'on' && sub !== 'off'))
+        throw new UsageError(usage);
+    const lb = await import('../core/local-build.js');
+    const asJson = a.flags.has('json');
+    const d = await lb.localDirs(process.env);
+    if (!d)
+        throw new UserError('`npm prefix -g` failed; switching needs npm on PATH and an npm global install of sideby');
+    const s = await lb.localStatus(d);
+    const now = new Date();
+    const build = (l) => `${l.version}-dev · ${l.commit || 'no commit'}${l.dirty ? '+' : ''}${l.builtAt ? `, built ${clock(l.builtAt, now)}` : ''}`;
+    if (sub === undefined) {
+        if (asJson)
+            json(io, { ...s, switched: false });
+        else {
+            io.out(s.running === 'local' && s.local
+                ? `The global sideby runs the local build ${build(s.local)}.`
+                : s.running === 'npm'
+                    ? 'The global sideby runs the npm package.'
+                    : 'The global sideby is not an npm global install; switching supports `npm install -g sideby` only.');
+            if (s.running === 'local')
+                io.out(c.dim('Back to the release: sideby local off'));
+            else if (s.running === 'npm' && s.local)
+                io.out(c.dim(`A local build is kept (${build(s.local)}): sideby local on`));
+        }
+        return 0;
+    }
+    const to = sub === 'on' ? 'local' : 'npm';
+    const blocked = lb.switchBlocker(s, to);
+    if (blocked) {
+        if (asJson)
+            json(io, { ...s, to, switched: false, blocked });
+        else
+            io.err(c.yellow(`sideby cannot switch: ${blocked}`));
+        return 1;
+    }
+    if (s.running === to) {
+        if (asJson)
+            json(io, { ...s, to, switched: false });
+        else
+            io.out(`${c.green('✓')} The global sideby already runs the ${to === 'local' ? 'local build' : 'npm package'}.`);
+        return 0;
+    }
+    if (!a.flags.has('yes')) {
+        if (asJson)
+            json(io, { ...s, to, switched: false });
+        else {
+            io.out(to === 'local' && s.local
+                ? `Switching runs the local build ${build(s.local)} instead of the npm package. It is not rebuilt: \`pnpm local\` in the checkout builds a new one.`
+                : `Switching goes back to the npm package: the kept ${s.kept ?? 'copy'} when it is the latest, else \`npm install -g sideby@latest\`.`);
+            io.out(c.cyan(`\nRun it with \`sideby local ${sub} --yes\`.`));
+        }
+        return 10;
+    }
+    const { backgroundPanelPort } = await import('../panel/background.js');
+    const paths = resolvePaths(process.env);
+    const r = await lb.switchLocal(paths, d, to, process.env, {
+        panelPort: () => backgroundPanelPort(paths),
+        ...(asJson ? {} : { onOutput: (t) => process.stderr.write(t) }),
+    });
+    if (asJson)
+        json(io, {
+            ...(await lb.localStatus(d)),
+            to,
+            switched: r.ok,
+            message: r.message,
+            restartedPanel: r.restartedPanel,
+        });
+    else if (r.ok) {
+        io.out(`${c.green('✓')} ${r.message}.`);
+        if (r.restartedPanel)
+            io.out(c.dim('The background panel restarted with it; open panels reload by themselves.'));
+    }
+    else
+        io.err(c.red(`✗ ${r.message}`));
+    return r.ok ? 0 : 1;
+}
 export async function cmdApp(a, io) {
     const sub = a.positionals[0];
     const usage = 'usage: sideby app install [--url <url>] | sideby app uninstall';

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>`.",
@@ -244,12 +249,109 @@ 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() }),
+    local: Type.Object({
+        schemaVersion: Version,
+        running: Type.Union([Type.Literal('local'), Type.Literal('npm'), Type.Null()], {
+            description: 'What the global sideby runs: the Local Build, an npm package, or neither (not an npm global install).',
+        }),
+        local: Type.Union([Type.Object({ commit: Str, dirty: Type.Boolean(), builtAt: Str, version: Str }), Type.Null()], {
+            description: 'The newest Local Build, the one `on` switches to; null when `pnpm local` never ran.',
+        }),
+        kept: Type.Union([Str, Type.Null()], {
+            description: 'The npm package version kept aside while a Local Build runs.',
+        }),
+        to: Type.Optional(Type.Union([Type.Literal('local'), Type.Literal('npm')])),
+        switched: Type.Boolean({
+            description: 'A switch ran and succeeded; false for status, a preview (exit 10) or a failure.',
+        }),
+        blocked: Type.Optional(Type.String({ description: 'Why the switch cannot run, with what to do.' })),
+        message: Type.Optional(Str),
+        restartedPanel: Type.Optional(Type.Boolean()),
+    }, { title: 'sideby local --json' }),
     list: Type.Object({
         schemaVersion: Version,
         families: Type.Array(FamilyInfo),
@@ -396,6 +498,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(),
@@ -582,9 +685,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.',
@@ -614,6 +719,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]
@@ -28,7 +36,7 @@ Usage:
   sideby doctor [target] [--fix] [--force]
                                       check shared items and permissions; --fix repairs safe issues
   sideby quota [account|family] [--refresh]
-                                      quota and 7-day token usage; --refresh asks Grok again now
+                                      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
@@ -64,10 +72,12 @@ Usage:
                                       rewrite the config's shellInitFile with them
   sideby plugins                      list loaded plugins and load errors
   sideby update [--yes]               update sideby to the newest version (shows the command first)
+  sideby local [on|off] [--yes]       for sideby developers: switch the global sideby between the
+                                      last local build (pnpm local) and the npm package
 
 Options:
   --json        machine-readable output (list, new, next, alias, doctor, quota, tune, model, remote-control, handoff,
-                families, plugins, app, desktop, browser, update)
+                families, plugins, app, desktop, browser, update, local)
   -h, --help    show this help; \`sideby <command> --help\` for new, alias, login, doctor, families, desktop, browser
   -v, --version show the version
 
@@ -215,6 +225,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: [] },
@@ -237,7 +250,8 @@ const COMMANDS = {
     'shell-init': { flags: ['write'] },
     plugins: { flags: ['json'] },
     families: { flags: ['json'] },
-    update: { flags: ['json', 'yes'] },
+    update: { flags: ['json', 'yes'], valued: ['auto'] },
+    local: { flags: ['json', 'yes'] },
     'update-check': { flags: [] },
 };
 /** Commands that never print an Update Notice: their output is read by a shell or an agent, or they are internal. */
@@ -261,12 +275,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'], {
@@ -297,7 +312,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));
@@ -414,6 +431,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':
@@ -458,6 +480,8 @@ async function dispatch(cmd, parsed, io, cmds) {
             return await cmds.cmdUpdate(parsed, io);
         case 'update-check':
             return await cmds.cmdUpdateCheck(parsed, io);
+        case 'local':
+            return await cmds.cmdLocal(parsed, io);
     }
     return 2;
 }

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

@@ -72,6 +72,7 @@ export declare const ConfigSchema: Type.TObject<{
     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>>;