sideby 0.13.1 → 0.15.0

package/dist/src/core/config.js

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

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

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

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

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

package/dist/src/core/launch.js

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -1,5 +1,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

@@ -1,11 +1,51 @@
 // Doctor's look at an installed sideby Agent Skill (spec §3.11). Read-only: a skill written for another
 // sideby version teaches commands this CLI may not have, so a version mismatch is a warning with the
 // reinstall command. Not installed is not a problem.
-import { readFile, realpath } from 'node:fs/promises';
+import { readFile, realpath, stat } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { mainDirOf } from './accounts.js';
 import { tildify } from './paths.js';
-export const SKILL_INSTALL = 'npx skills add Adonis0123/sideby -g';
+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)) {
+        try {
+            await stat(join(d, '.git'));
+            return d;
+        }
+        catch {
+            // keep looking up
+        }
+        if (dirname(d) === d)
+            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];
@@ -70,13 +110,17 @@ export async function checkInstalledSkills(home, families, version) {
         if (found === version)
             continue;
         const where = tildify(path, home);
+        // `sideby update` brings the skill along, except one a git repository owns (a dotfiles clone, say).
+        const repo = await skillOwnerRepo(dirname(real));
         out.push({
             level: 'warn',
             account: `${family.id}:main`,
             item: where,
             code: 'skill.outdated',
             message: `the sideby skill at ${where} is ${found ? `for sideby ${found}` : 'from before skills had a version'}; this sideby is ${version}`,
-            hint: `update it with \`${SKILL_INSTALL}\`, so agents learn this version's commands`,
+            hint: repo
+                ? `it lives in the git repository ${tildify(repo, home)}: update it where that repository comes from (\`${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,
         });

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

@@ -32,7 +32,25 @@ export interface UpdateCache {
         message: string;
         shown?: boolean;
     };
+    /** The last line the CLI printed about a sideby skill behind this version (`version` is the CLI's). */
+    skillNotified?: {
+        version: string;
+        at: string;
+    };
+    /** The last time Auto Update brought the skill to `to` alone; `shown` once the CLI has said so. */
+    skillAuto?: {
+        to: string;
+        at: string;
+        ok: boolean;
+        message: string;
+        shown?: boolean;
+    };
 }
+/**
+ * Why sideby cannot do something itself, for a Panel to say in the viewer's language; `reason` keeps the English
+ * text the CLI prints. `reasonAt` carries the path a code needs.
+ */
+export type ReasonCode = 'local-build' | 'npx' | 'volta' | 'not-writable' | 'project' | 'source' | 'skill-in-git';
 export type InstallKind = 'npm' | 'pnpm' | 'bun' | 'volta' | 'npx' | 'project' | 'source' | 'local';
 export interface InstallMethod {
     kind: InstallKind;
@@ -42,6 +60,9 @@ export interface InstallMethod {
     canUpdate: boolean;
     /** Why it cannot, in a phrase that follows "sideby cannot update itself: ". */
     reason?: string;
+    reasonCode?: ReasonCode;
+    /** The folders that are not writable (`not-writable`). */
+    reasonAt?: string;
     /** npm only: the prefix whose `lib/node_modules` holds sideby. */
     prefix?: string;
 }
@@ -87,6 +108,12 @@ type UpdateSettings = {
         auto?: boolean;
     };
 };
+export type ChecksOffCode = 'local-build' | 'env' | 'config' | 'ci';
+/** Why Update Checks are off, with a code for the Panel, or null when they are on (spec §3.23). */
+export declare function checksOffWhy(env: Env, config: UpdateSettings, local?: boolean): {
+    code: ChecksOffCode;
+    text: string;
+} | null;
 /** Why Update Checks are off, or null when they are on (spec §3.23). */
 export declare function checksOff(env: Env, config: UpdateSettings, local?: boolean): string | null;
 export declare function readUpdateCache(paths: Paths): Promise<UpdateCache>;
@@ -114,6 +141,29 @@ export declare function refreshUpdateCheck(paths: Paths, env: Env): Promise<Upda
 export declare function noticeLine(cache: UpdateCache, current: string, now: Date): string | null;
 /** What the CLI says once about the last Auto Update, or null. */
 export declare function autoUpdateLine(cache: UpdateCache): string | null;
+/** What the CLI says once about the skill Auto Update brought up to date alone, or null. */
+export declare function skillAutoLine(cache: UpdateCache): string | null;
+/**
+ * The sideby skill an agent reads, as the CLI sees it after a command: the version of the first one behind
+ * `current` (null: one without a version), and whether sideby may update it. Absent when none is behind.
+ */
+export interface SkillBehind {
+    installed: string | null;
+    canRun: boolean;
+}
+/** The skill part of a `SkillUpdatePlan` toward the running version, as `afterCommandPlan` takes it. */
+export declare const skillBehind: (plan: SkillUpdatePlan | null, current: string) => SkillBehind | null;
+/**
+ * The line about a skill behind this version the CLI may print now (spec §3.23), or null: once a day per CLI version,
+ * and never while Auto Update is on (the background check brings the skill along) and sideby may update it.
+ */
+export declare function skillNoticeLine(cache: UpdateCache, current: string, config: UpdateSettings, skill: SkillBehind | null, now: Date): string | null;
+/**
+ * Auto Update is on, the CLI is the newest version the cache knows, and the skill is behind it where sideby may
+ * update it, not tried for this version yet (or a failed try a day ago). A newer CLI waiting is left to the Update
+ * of the CLI: the skills tool fetches the default branch, which would put the skill ahead of this CLI.
+ */
+export declare function skillAutoPending(cache: UpdateCache, current: string, config: UpdateSettings, skill: SkillBehind | null, now: Date): boolean;
 /** The `_notice` of a `--json` output (spec §3.23): what an agent should mention once its task is done. */
 export interface JsonNotice {
     update?: {
@@ -140,7 +190,7 @@ export declare function jsonNotice(cache: UpdateCache, current: string, config:
  * then the Update Notice), the change that records them, and whether to start a background check. The caller prints,
  * writes `record` with `updateUpdateCache` and starts the check; nothing here touches the machine.
  */
-export declare function afterCommandPlan(cache: UpdateCache, current: string, config: UpdateSettings, env: Env, now: Date): {
+export declare function afterCommandPlan(cache: UpdateCache, current: string, config: UpdateSettings, env: Env, now: Date, skill?: SkillBehind | null): {
     lines: string[];
     record: ((cur: UpdateCache) => Partial<UpdateCache>) | null;
     startCheck: boolean;
@@ -183,6 +233,8 @@ export declare const shownMethod: (m: InstallMethod) => {
     kind: InstallKind;
     canUpdate: boolean;
     reason?: string | undefined;
+    reasonCode?: ReasonCode | undefined;
+    reasonAt?: string | undefined;
 };
 /** The plan as `sideby update --json` and the Panel show it (schemas/update.json). */
 export declare function shownPlan(plan: UpdatePlan): {
@@ -193,6 +245,8 @@ export declare function shownPlan(plan: UpdatePlan): {
         kind: InstallKind;
         canUpdate: boolean;
         reason?: string | undefined;
+        reasonCode?: ReasonCode | undefined;
+        reasonAt?: string | undefined;
     };
     command: string;
     canRun: boolean;
@@ -209,6 +263,9 @@ export interface SkillUpdatePlan {
     /** False when sideby must not run it; `reason` says why and the user runs `command` where it belongs. */
     canRun: boolean;
     reason?: string;
+    reasonCode?: ReasonCode;
+    /** The git repository that owns the skill (`skill-in-git`). */
+    reasonAt?: string;
 }
 /** The skill part of an Update toward `target`; null when no sideby skill is installed. Reads two files. */
 export declare function skillUpdatePlan(home: string, target: string): Promise<SkillUpdatePlan | null>;
@@ -219,6 +276,15 @@ export declare function applySkillUpdate(plan: SkillUpdatePlan | undefined, env:
     ok: boolean;
     message: string;
 } | null>;
+/**
+ * Updates only the sideby skill, for a CLI that is already current (`sideby update`, the Panel, Auto Update). Holds
+ * the same lock as an Update, so a skill update never runs beside one; null when there was nothing to do.
+ */
+export declare function applySkillOnly(paths: Paths, plan: SkillUpdatePlan | undefined, env: Env, onOutput?: (text: string) => void): Promise<{
+    ok: boolean;
+    message: string;
+    busy?: boolean;
+} | null>;
 export interface UpdateResult {
     ok: boolean;
     /** Exit code of the install command; absent when it did not run. */