sideby 0.14.0 → 0.16.0

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/local-build.d.ts

@@ -0,0 +1,63 @@
+import type { Env } from '../types.ts';
+import type { Paths } from './paths.ts';
+import { type LocalBuild } from './version.ts';
+export interface LocalDirs {
+    /** `$XDG_DATA_HOME/sideby-dev`: `pkg` (the running build), `old/<id>`, `npm` (the package it replaced). */
+    dev: string;
+    /** npm's global prefix: `<prefix>/lib/node_modules/sideby` and `<prefix>/bin/sideby`. */
+    prefix: string;
+}
+export declare const pkgDir: (d: LocalDirs) => string;
+export declare const globalPkg: (d: LocalDirs) => string;
+export declare const devDir: (env: Env) => string;
+/** Where the switch works, with npm's global prefix from `npm prefix -g`; null when npm cannot be asked. */
+export declare function localDirs(env: Env): Promise<LocalDirs | null>;
+export declare function kind(p: string): Promise<'link' | 'dir' | 'file' | null>;
+/**
+ * Points the global npm package at `pkg`. A real npm install moves to `<dev>/npm` first, so going back needs no
+ * network; a link elsewhere (npm link) is replaced. Returns what it did, for the summary.
+ */
+export declare function linkGlobal(d: LocalDirs): Promise<string>;
+/** Undoes linkGlobal: the npm package it moved comes back; false when there is none to restore (install it). */
+export declare function unlinkGlobal(d: LocalDirs): Promise<boolean>;
+/** The version of the npm package kept aside by linkGlobal, or null when none was kept or it cannot be read. */
+export declare const keptVersion: (d: LocalDirs) => Promise<string | null>;
+/**
+ * Going back to npm: put the kept package back when it is the newest published one (or the registry cannot be
+ * asked), else install `latest`. After a release the kept copy is the version before it.
+ */
+export declare function offPlan(kept: string | null, latest: string | null): 'restore' | 'install';
+export interface LocalStatus {
+    /** What the global `sideby` runs: the Local Build in `pkg`, an npm package, or neither (not installed, a link elsewhere). */
+    running: 'local' | 'npm' | null;
+    /** The newest Local Build, the one `on` switches to; null when `pnpm local` never ran here. */
+    local: (LocalBuild & {
+        version: string;
+    }) | null;
+    /** The npm package kept aside while a Local Build runs; null when none is. */
+    kept: string | null;
+}
+export declare function localStatus(d: LocalDirs): Promise<LocalStatus>;
+export type LocalTarget = 'local' | 'npm';
+/** Why `to` cannot run from this status, or null when it can. Every reason says what to do. */
+export declare function switchBlocker(s: LocalStatus, to: LocalTarget): string | null;
+export interface SwitchResult {
+    ok: boolean;
+    message: string;
+    /** What the global `sideby` runs afterwards. */
+    running: LocalStatus['running'];
+    /** True when it already ran `to`, and nothing changed. */
+    unchanged?: boolean;
+    restartedPanel: boolean;
+    /** Another install held the lock; nothing ran. */
+    busy?: boolean;
+}
+/**
+ * Puts `to` behind the global `sideby`. `local` links the newest Local Build; `npm` restores the kept package or
+ * installs `latest` (a failed install links the Local Build back, so `sideby` never goes missing). Afterwards a
+ * background Panel on `panelPort` starts again from the new code. One install at a time (the Update lock).
+ */
+export declare function switchLocal(paths: Paths, d: LocalDirs, to: LocalTarget, env: Env, opts?: {
+    panelPort?: () => Promise<number | null>;
+    onOutput?: (text: string) => void;
+}): Promise<SwitchResult>;

package/dist/src/core/local-build.js

@@ -0,0 +1,189 @@
+// Switching the global `sideby` between a Local Build and the npm package (ADR-0024). `pnpm local` builds and calls
+// these; `sideby local` and the Panel's version popover switch between the newest Local Build and npm without the
+// checkout. Only an npm global install is handled: `<prefix>/lib/node_modules/sideby` is the folder every caller
+// resolves, a link to `<dev>/pkg` while a Local Build runs.
+import { lstat, mkdir, readFile, readlink, rename, rm, symlink } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join, relative } from 'node:path';
+import { compareVersions, fetchLatest, restartPanelByName, runProgram, takeInstallLock } from './update.js';
+import { parseLocalBuild } from './version.js';
+const BIN = 'dist/src/cli/main.js';
+export const pkgDir = (d) => join(d.dev, 'pkg');
+export const globalPkg = (d) => join(d.prefix, 'lib', 'node_modules', 'sideby');
+const globalBin = (d) => join(d.prefix, 'bin', 'sideby');
+export const devDir = (env) => join(env.XDG_DATA_HOME || join(env.HOME || homedir(), '.local', 'share'), 'sideby-dev');
+/** Where the switch works, with npm's global prefix from `npm prefix -g`; null when npm cannot be asked. */
+export async function localDirs(env) {
+    const r = await runProgram('npm', ['prefix', '-g'], { env }).catch(() => null);
+    const prefix = r && r.code === 0 ? r.output.trim().split('\n').at(-1)?.trim() : '';
+    return prefix ? { dev: devDir(env), prefix } : null;
+}
+export async function kind(p) {
+    try {
+        const s = await lstat(p);
+        return s.isSymbolicLink() ? 'link' : s.isDirectory() ? 'dir' : 'file';
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Points the global npm package at `pkg`. A real npm install moves to `<dev>/npm` first, so going back needs no
+ * network; a link elsewhere (npm link) is replaced. Returns what it did, for the summary.
+ */
+export async function linkGlobal(d) {
+    const target = globalPkg(d);
+    const pkg = pkgDir(d);
+    let did = 'the global sideby already runs the local build';
+    const k = await kind(target);
+    if (k !== 'link' || (await readlink(target)) !== pkg) {
+        if (k === 'dir') {
+            await rm(join(d.dev, 'npm'), { recursive: true, force: true });
+            await rename(target, join(d.dev, 'npm'));
+            did = `the npm package moved to ${join(d.dev, 'npm')}; the global sideby now runs the local build`;
+        }
+        else {
+            if (k)
+                await rm(target, { force: true });
+            did = 'the global sideby now runs the local build';
+        }
+        await mkdir(dirname(target), { recursive: true });
+        await symlink(pkg, target, 'dir');
+    }
+    const bin = globalBin(d);
+    const want = relative(dirname(bin), join(target, BIN));
+    if ((await kind(bin)) !== 'link' || (await readlink(bin)) !== want) {
+        await rm(bin, { force: true });
+        await mkdir(dirname(bin), { recursive: true });
+        await symlink(want, bin);
+    }
+    return did;
+}
+/** Undoes linkGlobal: the npm package it moved comes back; false when there is none to restore (install it). */
+export async function unlinkGlobal(d) {
+    const target = globalPkg(d);
+    if ((await kind(target)) === 'link')
+        await rm(target, { force: true });
+    else if (await kind(target))
+        return true; // a real package is already there
+    if (!(await kind(join(d.dev, 'npm'))))
+        return false;
+    await rename(join(d.dev, 'npm'), target);
+    return true;
+}
+async function versionOf(dir) {
+    try {
+        const v = JSON.parse(await readFile(join(dir, 'package.json'), 'utf8')).version;
+        return typeof v === 'string' ? v : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The version of the npm package kept aside by linkGlobal, or null when none was kept or it cannot be read. */
+export const keptVersion = (d) => versionOf(join(d.dev, 'npm'));
+/**
+ * Going back to npm: put the kept package back when it is the newest published one (or the registry cannot be
+ * asked), else install `latest`. After a release the kept copy is the version before it.
+ */
+export function offPlan(kept, latest) {
+    if (!kept)
+        return 'install';
+    if (!latest)
+        return 'restore';
+    return (compareVersions(kept, latest) ?? -1) >= 0 ? 'restore' : 'install';
+}
+export async function localStatus(d) {
+    const k = await kind(globalPkg(d));
+    const running = k === 'link'
+        ? (await readlink(globalPkg(d))) === pkgDir(d)
+            ? 'local'
+            : null
+        : k === 'dir'
+            ? 'npm'
+            : null;
+    let local = null;
+    try {
+        const b = parseLocalBuild(JSON.parse(await readFile(join(pkgDir(d), 'dist', 'build.json'), 'utf8')));
+        const version = await versionOf(pkgDir(d));
+        if (b && version)
+            local = { ...b, version };
+    }
+    catch {
+        // no Local Build here
+    }
+    return { running, local, kept: await keptVersion(d) };
+}
+/** Why `to` cannot run from this status, or null when it can. Every reason says what to do. */
+export function switchBlocker(s, to) {
+    if (s.running === null)
+        return 'the global sideby is not an npm global install; switching supports `npm install -g sideby` only';
+    if (to === 'local' && !s.local)
+        return 'there is no local build yet; run `pnpm local` in the sideby checkout';
+    return null;
+}
+/**
+ * Puts `to` behind the global `sideby`. `local` links the newest Local Build; `npm` restores the kept package or
+ * installs `latest` (a failed install links the Local Build back, so `sideby` never goes missing). Afterwards a
+ * background Panel on `panelPort` starts again from the new code. One install at a time (the Update lock).
+ */
+export async function switchLocal(paths, d, to, env, opts = {}) {
+    const before = await localStatus(d);
+    const fail = (message, extra = {}) => ({
+        ok: false,
+        message,
+        running: before.running,
+        restartedPanel: false,
+        ...extra,
+    });
+    const blocked = switchBlocker(before, to);
+    if (blocked)
+        return fail(blocked);
+    if (before.running === to)
+        return {
+            ok: true,
+            unchanged: true,
+            message: to === 'local'
+                ? 'the global sideby already runs the local build'
+                : 'the global sideby already runs the npm package',
+            running: to,
+            restartedPanel: false,
+        };
+    const release = await takeInstallLock(paths);
+    if (!release)
+        return fail('a sideby update is running; wait for it to finish, then switch again', { busy: true });
+    let message;
+    try {
+        if (to === 'local') {
+            await linkGlobal(d);
+            message = `the global sideby runs the local build ${before.local?.commit ?? ''}`.trim();
+        }
+        else {
+            const latest = await fetchLatest(env).catch(() => null);
+            if (offPlan(before.kept, latest) === 'restore') {
+                await unlinkGlobal(d);
+                message = `the global sideby runs the npm package ${before.kept} again`;
+            }
+            else {
+                const want = latest ?? 'latest';
+                await rm(globalPkg(d), { force: true });
+                const r = await runProgram('npm', ['install', '-g', `sideby@${want}`], {
+                    env,
+                    ...(opts.onOutput ? { onOutput: opts.onOutput } : {}),
+                });
+                if (r.code !== 0) {
+                    await linkGlobal(d);
+                    return fail(`\`npm install -g sideby@${want}\` failed (exit ${r.code}); the local build stays. Run it yourself to see why`);
+                }
+                await rm(join(d.dev, 'npm'), { recursive: true, force: true });
+                message = `the global sideby runs the npm package ${want}`;
+            }
+        }
+    }
+    finally {
+        await release().catch(() => { });
+    }
+    const port = opts.panelPort ? await opts.panelPort().catch(() => null) : null;
+    const restartedPanel = port !== null && (await restartPanelByName(env, port));
+    return { ok: true, message, running: to, restartedPanel };
+}

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,

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;
 }
@@ -70,6 +91,12 @@ export interface UpdateDeps {
 }
 /** Internal, for tests: replaces parts of the machine. Not part of the plugin or Portal contract. */
 export declare function bindUpdateDeps(deps: Partial<UpdateDeps>): () => void;
+/** Runs a program through the swappable machine (tests bind `exec`); a Local Build switch installs with it. */
+export declare const runProgram: UpdateDeps['exec'];
+/** Starts the background Panel again from the code `sideby` now names; see `UpdateDeps.restartPanel`. */
+export declare const restartPanelByName: (env: Env, port: number) => Promise<boolean>;
+/** The lock every install shares (`update-install.lock`), so a Local Build switch never races an Update. */
+export declare const takeInstallLock: (paths: Paths) => Promise<(() => Promise<void>) | null>;
 /** -1, 0 or 1 like a sort comparator; a prerelease sorts before its release. Null when either is not a version. */
 export declare function compareVersions(a: string, b: string): number | null;
 /** `latest` is newer than `current`. */
@@ -87,6 +114,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 +147,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 +196,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 +239,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 +251,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 +269,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 +282,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. */