sideby 0.16.0 → 0.17.0

package/dist/src/core/config.js

@@ -68,15 +68,45 @@ const HandoffSchema = Type.Object({
         description: 'Accounts (ref or short command) that may take over from an account of another organization.',
     })),
     families: Type.Optional(Type.Record(Type.String(), Type.Object({
-        policy: Type.Optional(Type.Union([Type.Literal('pressure'), Type.Literal('order')])),
-        order: Type.Optional(Type.Array(Type.String())),
+        policy: Type.Optional(Type.Union([Type.Literal('pressure'), Type.Literal('order')], {
+            description: '`pressure` picks the account with the most Quota left; `order` follows `order`.',
+        })),
+        order: Type.Optional(Type.Array(Type.String(), { description: 'Accounts (ref or short command) to try, in order.' })),
     }, { additionalProperties: false }), {
         description: 'Handoff Order per family the session starts in: `pressure` (default) or an `order` list.',
     })),
 }, { additionalProperties: false });
 export const ConfigSchema = Type.Object({
     $schema: Type.Optional(Type.String()),
-    accounts: Type.Optional(Type.Record(Type.String(), Type.Object({ args: Type.Optional(Type.Array(Type.String())) }, { additionalProperties: false }), { description: 'Per-Account settings keyed by `<family>:<name>`.' })),
+    panel: Type.Optional(Type.Object({
+        theme: Type.Optional(Type.String({
+            enum: ['system', 'light', 'dark'],
+            description: 'Panel colours: follow the system (default), always light, or always dark.',
+        })),
+        language: Type.Optional(Type.String({
+            enum: ['auto', 'en', 'zh'],
+            description: "Panel language: the browser's (default), English, or Chinese.",
+        })),
+    }, { additionalProperties: false, description: 'How the Panel looks (spec §3.29).' })),
+    terminal: Type.Optional(Type.Object({
+        preferred: Type.Optional(Type.String({
+            enum: ['terminal', 'iterm2', 'ghostty', 'orca', 'wezterm', 'kitty', 'alacritty', 'custom'],
+            description: 'The terminal sideby opens for AI Tasks; without it sideby picks the one you use.',
+        })),
+        custom: Type.Optional(Type.String({
+            description: 'Your own launch command for `preferred: custom`, with `{cwd}` and `{cmd}` placeholders.',
+        })),
+    }, { additionalProperties: false, description: 'The terminal AI Tasks open in (spec §3.28).' })),
+    ask: Type.Optional(Type.Object({
+        account: Type.Optional(Type.String({
+            description: 'The account AI Tasks start (`<family>:<name>` or a short command); sideby picks one without it.',
+        })),
+    }, { additionalProperties: false, description: 'AI Tasks (spec §3.28).' })),
+    accounts: Type.Optional(Type.Record(Type.String(), Type.Object({
+        args: Type.Optional(Type.Array(Type.String(), {
+            description: 'Host arguments sideby starts the account with; `sideby config` and `sideby model` set only the model and effort ones.',
+        })),
+    }, { additionalProperties: false }), { description: 'Per-Account settings keyed by `<family>:<name>`.' })),
     aliases: Type.Optional(Type.Record(Type.String({ pattern: '^[A-Za-z_][A-Za-z0-9_-]*$' }), AliasSchema, {
         description: 'Short shell function names created by `sideby shell-init`, mapped to an Account ref or to `{ account, args }`.',
     })),
@@ -85,7 +115,9 @@ export const ConfigSchema = Type.Object({
     plugins: Type.Optional(Type.Record(Type.String(), Type.Record(Type.String(), Type.Unknown()), {
         description: 'Per-Plugin settings; `enabled: false` turns a Plugin off.',
     })),
-    extraSharedItems: Type.Optional(Type.Record(Type.String(), Type.Array(SharedItemSchema))),
+    extraSharedItems: Type.Optional(Type.Record(Type.String(), Type.Array(SharedItemSchema), {
+        description: 'Per family, more items each account shares with the main account: `{ path, mode }` with a relative path.',
+    })),
     accountTitle: Type.Optional(Type.Boolean({
         description: 'Set the terminal title to `[<short command or account>]` when sideby starts an Account, and keep Hosts that allow it (Codex) from replacing it. Off by default.',
     })),
@@ -127,8 +159,8 @@ export const ConfigSchema = Type.Object({
         })),
     }, { 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 })),
+        zsh: Type.Optional(Type.String({ minLength: 1, description: 'The file for zsh.' })),
+        bash: Type.Optional(Type.String({ minLength: 1, description: 'The file for bash.' })),
     }, {
         additionalProperties: false,
         description: 'Absolute or `~/` paths of files sideby rewrites with the `sideby shell-init <shell>` output whenever it adds an Account or an alias; source the file from your shell rc.',
@@ -191,8 +223,8 @@ async function configTarget(file) {
     return (await lstatOrNull(file))?.isSymbolicLink() ? ((await realpathOrNull(file)) ?? file) : file;
 }
 /**
- * Re-reads the config file, lets `edit` change one top-level `key` (sideby writes only `aliases`, `handoff`,
- * `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
+ * Re-reads the config file, lets `edit` change one top-level `key` (the keys sideby writes are listed in spec §3.10;
+ * `sideby config set|unset` may change any but plugin settings, §3.29), 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.
@@ -233,8 +265,18 @@ async function editConfigKey(file, key, retry, edit, opts = {}) {
         : { ...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`);
+    if (!Value.Check(ConfigSchema, next)) {
+        const first = [...Value.Errors(ConfigSchema, next)][0];
+        const where = (first?.instancePath ?? '').replace(/^\//, '').split('/').join('.') || key;
+        throw new ConfigError(`${where} ${first?.message ?? 'is invalid'}, so nothing was changed; \`sideby config get\` lists the keys and the values they take`, { code: 'bad-value' });
+    }
+    for (const alias of Object.keys(next.aliases ?? {})) {
+        const problem = aliasProblem(alias);
+        if (problem)
+            throw new ConfigError(`alias "${alias}" ${problem} (it becomes a shell function name); pick another name`, {
+                code: 'bad-value',
+            });
+    }
     const h = handoffSettings(next);
     if (h.prepareAt >= h.threshold)
         throw new ConfigError(`handoff.prepareAt must be lower than handoff.threshold; fix them in ${file} and ${retry} again`);
@@ -346,3 +388,229 @@ export async function removeConfigAlias(file, alias) {
     });
     return { status, aliases };
 }
+export function editConfigTerminal(file, patch) {
+    return editConfigKey(file, 'terminal', 'run `sideby terminal`', (current) => {
+        const next = { ...current, ...patch };
+        for (const key of ['preferred', 'custom'])
+            if (next[key] === undefined)
+                delete next[key];
+        return Object.keys(next).length ? next : undefined;
+    });
+}
+export function editConfigAsk(file, account) {
+    return editConfigKey(file, 'ask', 'run `sideby ask`', () => (account ? { account } : undefined));
+}
+/**
+ * The Panel's theme and language (spec §3.29): a value sets the key, null removes it (back to the default), and an
+ * empty `panel` goes away with it (see `editConfigKey` for how the file is written).
+ */
+export function editConfigPanel(file, patch, opts = {}) {
+    return editConfigKey(file, 'panel', 'change the setting', (current) => {
+        const next = { ...current };
+        for (const k of ['theme', 'language'])
+            if (patch[k] === null)
+                delete next[k];
+            else if (patch[k] !== undefined)
+                next[k] = patch[k];
+        return Object.keys(next).length ? next : undefined;
+    }, opts);
+}
+/** The name shown for a key the user picks, per record in the schema. */
+const PLACEHOLDERS = {
+    accounts: '<family>:<name>',
+    aliases: '<short>',
+    plugins: '<plugin>',
+    extraSharedItems: '<family>',
+    'handoff.families': '<family>',
+    'display.accounts': '<family>',
+    'display.pinned': '<family>',
+    'quota.check': '<family>',
+};
+const BAD_SEGMENT = new Set(['__proto__', 'constructor', 'prototype']);
+function takes(node) {
+    if (node.anyOf) {
+        const consts = node.anyOf.filter((n) => n.const !== undefined).map((n) => String(n.const));
+        if (consts.length === node.anyOf.length)
+            return `one of: ${consts.join(', ')}`;
+        return 'an account ref (`<family>:<name>`), or JSON {"account": …, "args": […]}';
+    }
+    if (node.enum)
+        return `one of: ${node.enum.join(', ')}`;
+    if (node.type === 'boolean')
+        return 'true or false';
+    if (node.type === 'integer')
+        return node.maximum !== undefined
+            ? `a whole number from ${node.minimum ?? 0} to ${node.maximum}`
+            : `a whole number, ${node.minimum ?? 0} or more`;
+    if (node.type === 'array')
+        return node.items?.type === 'string' ? 'a JSON list of text, such as ["a","b"]' : 'a JSON list';
+    if (node.type === 'string')
+        return 'text';
+    return 'a JSON object';
+}
+/** Every key `sideby config set` takes, with its meaning and current value, in schema order. */
+export function settableKeys(config) {
+    const out = [];
+    const walk = (node, path, meaning) => {
+        const key = path.join('.');
+        const here = node.description ?? meaning;
+        if (node.properties) {
+            for (const [name, child] of Object.entries(node.properties))
+                if (name !== '$schema')
+                    walk(child, [...path, name], here);
+            return;
+        }
+        const pattern = node.patternProperties && Object.values(node.patternProperties)[0];
+        if (pattern) {
+            const holder = PLACEHOLDERS[key] ?? '<name>';
+            if (key === 'plugins') {
+                walk({
+                    type: 'boolean',
+                    description: 'false turns the plugin off; its own settings are not changed here.',
+                }, [...path, holder, 'enabled'], here);
+                return;
+            }
+            if (pattern.properties)
+                return walk(pattern, [...path, holder], here);
+            return leaf(pattern, [...path, holder], here);
+        }
+        leaf(node, path, here);
+    };
+    const leaf = (node, path, meaning) => {
+        const key = path.join('.');
+        const item = { key, meaning: node.description ?? meaning, takes: takes(node) };
+        const holder = path.findIndex((p) => p.startsWith('<'));
+        if (holder < 0) {
+            const v = getIn(config, path);
+            if (v !== undefined)
+                item.value = v;
+        }
+        else {
+            const entries = [];
+            const parent = getIn(config, path.slice(0, holder));
+            if (parent && typeof parent === 'object')
+                for (const name of Object.keys(parent)) {
+                    const concrete = [...path.slice(0, holder), name, ...path.slice(holder + 1)];
+                    const v = getIn(config, concrete);
+                    if (v !== undefined)
+                        entries.push({ key: concrete.join('.'), value: v });
+                }
+            if (entries.length)
+                item.entries = entries;
+        }
+        out.push(item);
+    };
+    walk(ConfigSchema, [], '');
+    return out;
+}
+function getIn(value, path) {
+    let at = value;
+    for (const seg of path) {
+        if (!at || typeof at !== 'object' || Array.isArray(at) || !Object.hasOwn(at, seg))
+            return undefined;
+        at = at[seg];
+    }
+    return at;
+}
+/** Splits and checks a dot path; refuses what `config` may not read or change. */
+export function configKeyPath(key) {
+    return describeConfigKey(key).path;
+}
+/** The path of `key`, what it does and the values it takes; refuses what `config` may not read or change. */
+export function describeConfigKey(key) {
+    const path = key.split('.');
+    const list = '`sideby config get` lists the keys you can use';
+    if (!key || path.some((p) => !p || BAD_SEGMENT.has(p)))
+        throw new ConfigError(`"${key}" is not a config key; ${list}`, { code: 'bad-key' });
+    if (path[0] === '$schema')
+        throw new ConfigError(`$schema is for editors and is not a setting; ${list}`, { code: 'bad-key' });
+    if (path[0] === 'plugins' && !(path.length === 3 && path[2] === 'enabled'))
+        throw new ConfigError(`a plugin's own settings may hold secrets, so \`sideby config\` does not read or change them (only plugins.<plugin>.enabled); edit them in the config file`, { code: 'plugin-config' });
+    let node = ConfigSchema;
+    let meaning = '';
+    for (const seg of path) {
+        const n = node;
+        if (!n)
+            break;
+        const holder = n.anyOf ?? [n];
+        node = undefined;
+        for (const h of holder) {
+            if (h.properties?.[seg])
+                node = h.properties[seg];
+            else if (h.patternProperties) {
+                const [re, child] = Object.entries(h.patternProperties)[0];
+                if (new RegExp(re).test(seg))
+                    node = child;
+            }
+            if (node)
+                break;
+        }
+        if (node?.description)
+            meaning = node.description;
+    }
+    if (!node)
+        throw new ConfigError(`"${key}" is not a config key; ${list}`, { code: 'bad-key' });
+    if (path[0] === 'plugins')
+        return { path, meaning: 'false turns the plugin off.', takes: 'true or false' };
+    return { path, meaning, takes: takes(node) };
+}
+/** A value from the command line: JSON when it parses (90, true, ["a"]), else the text itself. */
+export function parseConfigValue(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+/** `sideby config get [key]`: the value at `key` (undefined when not set). */
+export async function configGet(file, key) {
+    const path = configKeyPath(key);
+    return { key, value: getIn(await loadConfig(file), path) };
+}
+function setIn(value, path, next, key) {
+    const [seg, ...rest] = path;
+    if (seg === undefined)
+        return next;
+    if (value !== undefined && (typeof value !== 'object' || value === null || Array.isArray(value)))
+        throw new ConfigError(`${key} cannot be set inside a value that is not an object; set the part before it as a whole (JSON), or unset it first`, { code: 'bad-key' });
+    const obj = { ...value };
+    const child = setIn(obj[seg], rest, next, key);
+    if (child === undefined || (rest.length && isEmptyObject(child) && next === undefined))
+        delete obj[seg];
+    else
+        obj[seg] = child;
+    return obj;
+}
+const isEmptyObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v) && Object.keys(v).length === 0;
+/**
+ * `sideby config set|unset` (spec §3.29): sets `key` to `value`, or removes it when `value` is undefined (and parents
+ * left empty with it). The whole result must match the schema; `accounts.<ref>.args` takes only what `argsProblem`
+ * accepts (the model and effort arguments, as `sideby model`), and without `argsProblem` it is refused. Written as
+ * every other config change (see `editConfigKey`); `dryRun` shows the change without writing.
+ */
+export async function editConfigPath(file, key, value, opts = {}) {
+    const path = configKeyPath(key);
+    if (path[0] === 'plugins' && value !== undefined && typeof value !== 'boolean')
+        throw new ConfigError(`${key} takes true or false`, { code: 'bad-value' });
+    const top = path[0];
+    const r = await editConfigKey(file, top, 'run the command', (current) => {
+        const next = setIn(current, path.slice(1), value, key);
+        const result = path.length === 1 ? next : isEmptyObject(next) ? undefined : next;
+        if (top === 'accounts')
+            checkAccountArgs(current, result, opts.argsProblem);
+        return result;
+    }, opts);
+    const inner = path.slice(1);
+    return { key, before: getIn(r.before, inner), after: getIn(r.after, inner), changed: r.changed };
+}
+function checkAccountArgs(before, after, argsProblem) {
+    for (const [ref, entry] of Object.entries(after ?? {})) {
+        const args = entry.args;
+        if (!args || JSON.stringify(args) === JSON.stringify(before?.[ref]?.args))
+            continue;
+        const problem = argsProblem ? argsProblem(ref, args) : 'sideby cannot check these arguments here';
+        if (problem)
+            throw new ConfigError(`accounts.${ref}.args: ${problem}. \`sideby config\` sets only the model and effort arguments, as \`sideby model ${ref}\` does; other host arguments go in a short command (\`sideby alias add <short> ${ref} -- <args>\`)`, { code: 'bad-value' });
+    }
+}

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

@@ -39,18 +39,29 @@ export declare function sidebyBinProblem(env: Env, why: string): Promise<string
  * 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: {
+export interface LaunchCommandOptions {
     account: Account;
     family: FamilyDef;
-    baseEnv: Env;
     accountArgs: readonly string[];
     userArgs: readonly string[];
     command: 'run' | 'login';
+    /** Config `accountTitle`: set the terminal title to `[<label>]` and keep the Host from replacing it. */
+    title?: boolean;
+}
+/**
+ * The Host and its arguments for a Launch before any `launch.before` hook: Family defaults, the title arguments, the
+ * Account's config arguments, then the user's. Pure: reads no file and runs no Plugin, so a preview can show it.
+ */
+export declare function launchCommand(opts: LaunchCommandOptions): {
+    bin: string;
+    args: string[];
+    notice?: string;
+};
+export declare function prepareLaunch(opts: LaunchCommandOptions & {
+    baseEnv: Env;
     bus: HookBus;
     /** What the Host may show as the Account (`SIDEBY_LABEL`): the short command, else the ref. */
     label?: string;
-    /** Config `accountTitle`: set the terminal title to `[<label>]` and keep the Host from replacing it. */
-    title?: boolean;
 }): Promise<PreparedLaunch>;
 /**
  * Runs the Host with the terminal attached and returns sideby's exit code (spec §3.5):

package/dist/src/core/launch.js

@@ -72,6 +72,32 @@ export function accountEnv(family, account, baseEnv) {
         env[family.selectVar] = account.dir;
     return env;
 }
+/**
+ * The Host and its arguments for a Launch before any `launch.before` hook: Family defaults, the title arguments, the
+ * Account's config arguments, then the user's. Pure: reads no file and runs no Plugin, so a preview can show it.
+ */
+export function launchCommand(opts) {
+    const { account, family } = opts;
+    if (opts.command === 'login') {
+        // Family arguments still apply: Codex must store a non-main login in the Account's own file.
+        const base = family.defaultArgs?.(account, []) ?? [];
+        return family.login.args
+            ? { bin: family.bin, args: [...base, ...family.login.args] }
+            : { bin: family.bin, args: base, notice: family.login.hint };
+    }
+    const keep = opts.title && family.keepTitle && !opts.userArgs.some((a) => a.includes(family.keepTitle.key))
+        ? family.keepTitle.args
+        : [];
+    return {
+        bin: family.bin,
+        args: [
+            ...(family.defaultArgs?.(account, opts.userArgs) ?? []),
+            ...keep,
+            ...opts.accountArgs,
+            ...opts.userArgs,
+        ],
+    };
+}
 export async function prepareLaunch(opts) {
     const { account, family } = opts;
     const env = accountEnv(family, account, opts.baseEnv);
@@ -84,29 +110,7 @@ export async function prepareLaunch(opts) {
     // inherited from another sideby Launch never leaks through.
     env.SIDEBY_ACCOUNT = account.ref;
     env.SIDEBY_LABEL = opts.label || account.ref;
-    let args;
-    let notice;
-    if (opts.command === 'login') {
-        // Family arguments still apply: Codex must store a non-main login in the Account's own file.
-        const base = family.defaultArgs?.(account, []) ?? [];
-        if (family.login.args)
-            args = [...base, ...family.login.args];
-        else {
-            args = base;
-            notice = family.login.hint;
-        }
-    }
-    else {
-        const keep = opts.title && family.keepTitle && !opts.userArgs.some((a) => a.includes(family.keepTitle.key))
-            ? family.keepTitle.args
-            : [];
-        args = [
-            ...(family.defaultArgs?.(account, opts.userArgs) ?? []),
-            ...keep,
-            ...opts.accountArgs,
-            ...opts.userArgs,
-        ];
-    }
+    const { args, notice } = launchCommand(opts);
     await opts.bus.run('launch.before', family.id, {
         account,
         family,

package/dist/src/core/local-build.d.ts

@@ -1,4 +1,5 @@
 import type { Env } from '../types.ts';
+import { type AutostartContext } from './autostart.ts';
 import type { Paths } from './paths.ts';
 import { type LocalBuild } from './version.ts';
 export interface LocalDirs {
@@ -49,8 +50,17 @@ export interface SwitchResult {
     /** True when it already ran `to`, and nothing changed. */
     unchanged?: boolean;
     restartedPanel: boolean;
+    /**
+     * Back on npm, `sideby update --yes` of the npm code brought the skill agents read to its version (true), or that
+     * failed (false); absent for a switch to the Local Build, which has no skill of its own to bring.
+     */
+    skillSynced?: boolean;
+    /** With `skillSync: 'background'`: that `sideby update --yes` started on its own and is not waited for. */
+    skillSyncStarted?: boolean;
     /** Another install held the lock; nothing ran. */
     busy?: boolean;
+    /** An existing login item (ADR-0029) now starts the sideby switched to; absent when there was none to change. */
+    refreshedAutostart?: boolean;
 }
 /**
  * Puts `to` behind the global `sideby`. `local` links the newest Local Build; `npm` restores the kept package or
@@ -60,4 +70,11 @@ export interface SwitchResult {
 export declare function switchLocal(paths: Paths, d: LocalDirs, to: LocalTarget, env: Env, opts?: {
     panelPort?: () => Promise<number | null>;
     onOutput?: (text: string) => void;
+    /**
+     * Back on npm, wait for the skill (a terminal shows its progress) or start it on its own: it fetches from the
+     * network and can take minutes, longer than a Portal waits for an answer (`background`, the Panel).
+     */
+    skillSync?: 'wait' | 'background';
+    /** Internal, for tests: parts of the machine the login item refresh uses. */
+    autostart?: Partial<AutostartContext>;
 }): Promise<SwitchResult>;

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

@@ -2,10 +2,11 @@
 // 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 { lstat, mkdir, readFile, readlink, realpath, 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 { refreshAutostart } from './autostart.js';
+import { compareVersions, fetchLatest, restartPanelByName, runProgram, startDetached, takeInstallLock, } from './update.js';
 import { parseLocalBuild } from './version.js';
 const BIN = 'dist/src/cli/main.js';
 export const pkgDir = (d) => join(d.dev, 'pkg');
@@ -122,6 +123,21 @@ export function switchBlocker(s, to) {
         return 'there is no local build yet; run `pnpm local` in the sideby checkout';
     return null;
 }
+/**
+ * Points an existing login item at the sideby now behind the global command (spec §3.29): its entry, with this Node.
+ * Never creates one and never throws; undefined when there is no login item of sideby's, or the entry is missing.
+ */
+async function refreshLoginItem(paths, d, ctx = {}) {
+    const entry = await realpath(join(globalPkg(d), BIN)).catch(() => null);
+    if (!entry)
+        return undefined;
+    const r = await refreshAutostart({
+        home: paths.home,
+        launcher: { node: process.execPath, entry },
+        ...ctx,
+    });
+    return r.state === 'on' || r.state === 'stale' ? r.rewritten : undefined;
+}
 /**
  * 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
@@ -183,7 +199,27 @@ export async function switchLocal(paths, d, to, env, opts = {}) {
     finally {
         await release().catch(() => { });
     }
+    // The login item records the sideby it starts, like `sideby update` keeps it pointing at the one in use.
+    const refreshed = await refreshLoginItem(paths, d, opts.autostart);
+    const login = refreshed === undefined ? {} : { refreshedAutostart: refreshed };
     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 };
+    if (to === 'local')
+        return { ok: true, message, running: to, restartedPanel, ...login };
+    // The skill is part of the version (spec §3.23): the npm code updates it as `sideby update --yes` does for anyone,
+    // by name so the new code runs, after the lock above is free. A failure keeps the switch.
+    if (opts.skillSync === 'background')
+        return {
+            ok: true,
+            message,
+            running: to,
+            restartedPanel,
+            ...login,
+            skillSyncStarted: await startDetached('sideby', ['update', '--yes'], env),
+        };
+    const u = await runProgram('sideby', ['update', '--yes'], {
+        env,
+        ...(opts.onOutput ? { onOutput: opts.onOutput } : {}),
+    }).catch(() => ({ code: 1, output: '' }));
+    return { ok: true, message, running: to, restartedPanel, ...login, skillSynced: u.code === 0 };
 }

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

@@ -0,0 +1,78 @@
+import { HookBus } from '../plugins/bus.ts';
+import type { Account, Env, FamilyDef } from '../types.ts';
+import { type PreparedLaunch } from './launch.ts';
+/** How long `sideby try` waits for the Host (spec §3.28). The spawner enforces it. */
+export declare const PROBE_TIMEOUT_MS = 60000;
+/** Combined stdout and stderr kept after redaction, in bytes. */
+export declare const PROBE_OUTPUT_MAX_BYTES = 2048;
+/**
+ * What the injected spawner receives. It must start `bin` with `args` only, in `cwd`, with `env`,
+ * and with stdin ignored (not a terminal and not a pipe the Host can wait on). When `timeoutMs`
+ * elapses it stops the process and resolves with `timedOut: true`. Errors must not include `env`
+ * or anything read from a Secret File.
+ */
+export interface ProbeSpawnRequest {
+    bin: string;
+    args: readonly string[];
+    env: Env;
+    cwd: string;
+    timeoutMs: number;
+    /** Always `ignore`: the probe is not interactive. */
+    stdin: 'ignore';
+}
+export interface ProbeSpawnResult {
+    /** Process exit code, or null when it timed out or the code could not be read. */
+    exitCode: number | null;
+    stdout: string;
+    stderr: string;
+    /** True when the spawner stopped the process because `timeoutMs` elapsed. */
+    timedOut: boolean;
+}
+export interface ProbeDeps {
+    family: FamilyDef;
+    /** The environment sideby itself is running in: the same `baseEnv` Launch copies. */
+    baseEnv: Env;
+    /** Working directory for the Host. The caller creates this temp directory. */
+    cwd: string;
+    spawn: (req: ProbeSpawnRequest) => Promise<ProbeSpawnResult>;
+    /** Account arguments from config, passed through Launch the same way `sideby run` does. */
+    accountArgs?: readonly string[];
+    /** What Launch would set as `SIDEBY_LABEL`. Defaults to the account ref. */
+    label?: string;
+    /** `launch.before` hooks. Pass the runtime bus so the probe sees the same environment as Launch. */
+    bus?: HookBus;
+    /**
+     * The Launch already prepared with `probe.args` as the user's arguments (the runtime's `prepareLaunch`), so its
+     * hooks and config arguments are applied once; `accountArgs`, `label` and `bus` are then unused.
+     */
+    launch?: PreparedLaunch;
+    /** Defaults to {@link PROBE_TIMEOUT_MS}. */
+    timeoutMs?: number;
+}
+export interface ProbeResult {
+    /** True when the Host exited 0 before the timeout. */
+    ok: boolean;
+    exitCode: number | null;
+    /**
+     * The first 2 KiB of stdout followed by stderr. Secret File values of length 4 or more are
+     * replaced with `***` before this cut, so a value that straddles the cut cannot leak.
+     */
+    output: string;
+    /** True when the spawner stopped the Host at the timeout. `ok` is then false. */
+    timedOut: boolean;
+}
+/**
+ * Runs the Family's probe the way Launch would start the Host: `prepareLaunch`'s environment and
+ * arguments (with `probe.args` as the user's arguments), the caller's temp directory as cwd, stdin ignored, and a 60s
+ * timeout the spawner enforces. Returns the exit code and the redacted output.
+ * Throws a UserError when the Family has no probe; the message says this tool cannot be tried
+ * and to start the account with `sideby run` instead.
+ */
+export declare function runProbe(account: Account, deps: ProbeDeps): Promise<ProbeResult>;
+/**
+ * The real spawner for {@link ProbeDeps.spawn}. The Host leads its own process group, so the timeout stops it and
+ * any child it started; the result comes at once, even while a child still holds the output pipes open.
+ */
+export declare function spawnProbe(request: ProbeSpawnRequest): Promise<ProbeSpawnResult>;
+/** Replaces each secret of length 4 or more. Longer values go first so one cannot hide inside another. */
+export declare function redactSecrets(text: string, values: readonly string[]): string;