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

package/dist/build.json

@@ -1 +1 @@
-{"id":"20261017T050946-402d73"}
+{"id":"20261017T115526-c6b039"}

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;

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)

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,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),
@@ -396,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(),
@@ -582,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.',
@@ -614,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]
@@ -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
@@ -215,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: [] },
@@ -237,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. */
@@ -261,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'], {
@@ -297,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));
@@ -414,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

@@ -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>>;

package/dist/src/core/config.js

@@ -114,9 +114,12 @@ export const ConfigSchema = Type.Object({
         accounts: Type.Optional(Type.Record(Type.String(), Type.Array(Type.String({ minLength: 1 }), { uniqueItems: true }), {
             description: 'Per family, account names (not refs or short commands) in the order they are shown; accounts not listed follow, main first, then by name.',
         })),
+        pinned: Type.Optional(Type.Record(Type.String(), Type.Array(Type.String({ minLength: 1 }), { uniqueItems: true }), {
+            description: 'Per family, the names of the accounts pinned to the top of their group, in the order they are shown; they lead the group in every sort. Resetting the order keeps them.',
+        })),
     }, {
         additionalProperties: false,
-        description: 'Display Order (spec §3.25): the order you dragged families and accounts into in the Panel. Display only: it never changes which account a Handoff picks.',
+        description: 'Display Order (spec §3.25): the order you gave families and accounts in the Panel, and the accounts you pinned. Display only: it never changes which account a Handoff picks.',
     })),
     quota: Type.Optional(Type.Object({
         check: Type.Optional(Type.Record(Type.String(), Type.Boolean(), {
@@ -275,10 +278,13 @@ export function editConfigBrowser(file, edit, opts = {}) {
  * or empty (see `editConfigKey` for how the file is written).
  */
 export function editConfigDisplay(file, display) {
-    const accounts = Object.fromEntries(Object.entries(display?.accounts ?? {}).filter(([, names]) => names.length));
+    const lists = (r) => Object.fromEntries(Object.entries(r ?? {}).filter(([, names]) => names.length));
+    const accounts = lists(display?.accounts);
+    const pinned = lists(display?.pinned);
     const next = {
         ...(display?.families?.length ? { families: [...display.families] } : {}),
         ...(Object.keys(accounts).length ? { accounts } : {}),
+        ...(Object.keys(pinned).length ? { pinned } : {}),
     };
     return editConfigKey(file, 'display', 'move it again', () => (Object.keys(next).length ? next : undefined));
 }

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

@@ -1,7 +1,21 @@
 import type { FamilyDef, Finding } from '../types.ts';
+export declare const SKILL_SOURCE = "Adonis0123/sideby";
 export declare const SKILL_INSTALL = "npx skills add Adonis0123/sideby -g";
+/** The command a person runs to update the skill where sideby leaves it alone. */
+export declare const SKILL_UPDATE_SHOWN = "npx skills update sideby -g";
 /** The folder holding `dir` that is a git work tree, if any: a skill there is managed by that repository. */
 export declare function gitRootOf(dir: string): Promise<string | null>;
+/**
+ * Whether the skills tool's install record (`.skill-lock.json` beside the `skills` folder holding `dir`) names this
+ * repository as the source of `sideby`: then `npx skills update` owns the skill, even inside a git repository (a
+ * dotfiles clone of `~/.agents`, say). Reads only that one entry's `source`.
+ */
+export declare function installedBySkillsTool(dir: string): Promise<boolean>;
+/**
+ * The git repository that owns the sideby skill in `dir`, or null when sideby may update it: not in a repository, or
+ * the skills tool installed it there.
+ */
+export declare function skillOwnerRepo(dir: string): Promise<string | null>;
 /** `metadata.version` from a SKILL.md frontmatter, or null when there is none. */
 export declare function skillVersionOf(text: string): string | null;
 /**

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

@@ -5,7 +5,10 @@ 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';
+export const SKILL_SOURCE = 'Adonis0123/sideby';
+export const SKILL_INSTALL = `npx skills add ${SKILL_SOURCE} -g`;
+/** The command a person runs to update the skill where sideby leaves it alone. */
+export const SKILL_UPDATE_SHOWN = 'npx skills update 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)) {
@@ -20,6 +23,29 @@ export async function gitRootOf(dir) {
             return null;
     }
 }
+/**
+ * Whether the skills tool's install record (`.skill-lock.json` beside the `skills` folder holding `dir`) names this
+ * repository as the source of `sideby`: then `npx skills update` owns the skill, even inside a git repository (a
+ * dotfiles clone of `~/.agents`, say). Reads only that one entry's `source`.
+ */
+export async function installedBySkillsTool(dir) {
+    try {
+        const lock = JSON.parse(await readFile(join(dirname(dirname(dir)), '.skill-lock.json'), 'utf8'));
+        const source = lock.skills?.sideby?.source;
+        return typeof source === 'string' && source.toLowerCase() === SKILL_SOURCE.toLowerCase();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The git repository that owns the sideby skill in `dir`, or null when sideby may update it: not in a repository, or
+ * the skills tool installed it there.
+ */
+export async function skillOwnerRepo(dir) {
+    const repo = await gitRootOf(dir);
+    return repo && !(await installedBySkillsTool(dir)) ? repo : 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];
@@ -85,7 +111,7 @@ export async function checkInstalledSkills(home, families, 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));
+        const repo = await skillOwnerRepo(dirname(real));
         out.push({
             level: 'warn',
             account: `${family.id}:main`,
@@ -93,7 +119,7 @@ export async function checkInstalledSkills(home, families, version) {
             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: 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`
+                ? `it lives in the git repository ${tildify(repo, home)}: update it where that repository comes from (\`${SKILL_UPDATE_SHOWN}\` 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,