sideby 0.10.0 → 0.12.0

package/dist/src/core/app-profiles.d.ts

@@ -0,0 +1,50 @@
+import { type ProfileAppDef } from '../families/desktop.ts';
+import type { Runtime } from '../runtime.ts';
+import { type DesktopOpenResult } from './desktop-app.ts';
+export interface AppProfileStatus {
+    /** `grok-bot:<name>`; the Main Profile is `grok-bot:main`. */
+    ref: string;
+    /** The app as messages name it, for example `Grok Bot`. */
+    app: string;
+    name: string;
+    isMain: boolean;
+    /** The Profile's app data folder; absent for the Main Profile, which uses the app's default. */
+    appData?: string;
+    installed: boolean;
+    /** That Profile's own window runs now. */
+    running: boolean;
+    /** What the app last wrote about its sign-in; absent when unknown. */
+    signedIn?: boolean;
+}
+export interface AppProfileRemoveResult {
+    ref: string;
+    app: string;
+    appData: string;
+    /** False when only the plan was shown (no `--yes`). */
+    removed: boolean;
+}
+/** The app and Profile name a ref names, or undefined when it is not an App Profile ref. */
+export declare function parseProfileRef(ref: string): {
+    def: ProfileAppDef;
+    name: string;
+} | undefined;
+/** Where the App Profiles of an app live: `~/Library/Application Support/sideby/<app>`. */
+export declare function profilesRoot(home: string, def: ProfileAppDef): string;
+/**
+ * Every App Profile with its state, for `sideby list` and the Panel: only on macOS, and per app only when it is
+ * installed or has Profiles. The Main Profile first. Never throws.
+ */
+export declare function listAppProfiles(rt: Runtime): Promise<AppProfileStatus[]>;
+/**
+ * Opens an App Profile's window, creating its folder first when it is new, or brings its running window to the front.
+ * Never starts a second window for the same Profile and never ends a process.
+ */
+export declare function openAppProfile(rt: Runtime, ref: string): Promise<DesktopOpenResult>;
+/**
+ * Removes a non-main App Profile's folder, which signs that window out and deletes its local data. Without `yes` it
+ * only returns what would go. Refuses the Main Profile, a running window, a missing folder and anything that is not a
+ * real folder inside sideby's own; never follows a link.
+ */
+export declare function removeAppProfile(rt: Runtime, ref: string, opts: {
+    yes: boolean;
+}): Promise<AppProfileRemoveResult>;

package/dist/src/core/app-profiles.js

@@ -0,0 +1,206 @@
+// App Profiles (spec §3.20 "Grok Bot 窗口", ADR-0019): named windows of a desktop app that signs in apart from every
+// Account, each with its own App Data under ~/Library/Application Support/sideby/<app>/<name>/. Opening and focusing
+// work as for a Family's Desktop App (core/desktop-app.ts); every program still goes through `DesktopDeps.exec`.
+import { chmod, mkdir, readdir, readFile, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { PROFILE_APPS } from '../families/desktop.js';
+import { ACCOUNT_NAME } from './account-name.js';
+import { activate, cleanEnv, depsFor, findApp, instanceOf, mainArgs, notInstalled, notMac, processes, } from './desktop-app.js';
+import { UserError } from './errors.js';
+import { lstatOrNull } from './fs-safe.js';
+const MAIN = 'main';
+/** The app and Profile name a ref names, or undefined when it is not an App Profile ref. */
+export function parseProfileRef(ref) {
+    for (const def of PROFILE_APPS) {
+        if (ref === def.id)
+            return { def, name: MAIN };
+        if (ref.startsWith(`${def.id}:`))
+            return { def, name: ref.slice(def.id.length + 1) };
+    }
+    return undefined;
+}
+/** Where the App Profiles of an app live: `~/Library/Application Support/sideby/<app>`. */
+export function profilesRoot(home, def) {
+    return join(home, 'Library', 'Application Support', 'sideby', def.id);
+}
+function appDataOf(home, def, name) {
+    return name === MAIN ? null : join(profilesRoot(home, def), name);
+}
+/** `signedIn` from the app's own status file: a boolean next to a version, a pid and a start time, not a credential. */
+async function signedIn(file) {
+    try {
+        const v = JSON.parse(await readFile(file, 'utf8'));
+        const s = v && typeof v === 'object' ? v.signedIn : undefined;
+        return typeof s === 'boolean' ? s : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Profile names: the real folders under the app's root with a valid name, sorted. Links and files are skipped. */
+async function profileNames(root) {
+    let entries;
+    try {
+        entries = await readdir(root);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const e of entries)
+        if (e !== MAIN && ACCOUNT_NAME.test(e) && (await lstatOrNull(join(root, e)))?.isDirectory())
+            out.push(e);
+    return out.sort();
+}
+function checkName(def, name) {
+    if (name !== MAIN && !ACCOUNT_NAME.test(name))
+        throw new UserError(`"${name}" is not a valid ${def.title} window name; use lowercase letters, digits and dashes, starting with a letter or digit (for example \`sideby desktop ${def.id}:work\`)`, { code: 'invalid-name' });
+}
+/**
+ * Every App Profile with its state, for `sideby list` and the Panel: only on macOS, and per app only when it is
+ * installed or has Profiles. The Main Profile first. Never throws.
+ */
+export async function listAppProfiles(rt) {
+    const deps = depsFor(rt);
+    if (deps.platform !== 'darwin')
+        return [];
+    const home = rt.paths.home;
+    const out = [];
+    try {
+        let procs = null;
+        for (const def of PROFILE_APPS) {
+            const app = await findApp(def, deps);
+            const names = await profileNames(profilesRoot(home, def));
+            if (!app && !names.length)
+                continue;
+            if (app && !procs)
+                procs = (await processes(deps)) ?? [];
+            for (const name of [MAIN, ...names]) {
+                const appData = appDataOf(home, def, name);
+                const status = join(appData ?? join(home, def.mainUserData), def.statusFile);
+                const s = await signedIn(status);
+                out.push({
+                    ref: `${def.id}:${name}`,
+                    app: def.title,
+                    name,
+                    isMain: name === MAIN,
+                    ...(appData ? { appData } : {}),
+                    installed: app !== null,
+                    running: app ? Boolean(instanceOf(app, appData, procs ?? [])) : false,
+                    ...(s === undefined ? {} : { signedIn: s }),
+                });
+            }
+        }
+    }
+    catch {
+        // A display nicety: a failure shows no Profiles.
+    }
+    return out;
+}
+async function located(rt, ref) {
+    const parsed = parseProfileRef(ref);
+    if (!parsed)
+        throw new UserError(`${ref} is not an app window; use \`sideby desktop grok-bot:<name>\``);
+    const { def, name } = parsed;
+    checkName(def, name);
+    const deps = depsFor(rt);
+    if (deps.platform !== 'darwin')
+        throw notMac(deps.platform);
+    const app = await findApp(def, deps, { spotlight: true });
+    if (!app)
+        throw notInstalled(def, deps);
+    return { deps, def, name, app, appData: appDataOf(rt.paths.home, def, name) };
+}
+/**
+ * Opens an App Profile's window, creating its folder first when it is new, or brings its running window to the front.
+ * Never starts a second window for the same Profile and never ends a process.
+ */
+export async function openAppProfile(rt, ref) {
+    const { deps, def, name, app, appData } = await located(rt, ref);
+    const listed = await processes(deps);
+    const procs = listed ?? [];
+    const base = {
+        ref: `${def.id}:${name}`,
+        family: def.id,
+        app: def.title,
+        appPath: app.path,
+        ...(appData ? { appData } : {}),
+        createdAppData: false,
+        linked: [],
+        notices: [],
+    };
+    const running = instanceOf(app, appData, procs);
+    if (running) {
+        const focused = await activate(deps, running.pid);
+        return {
+            ...base,
+            action: focused ? 'focused' : 'already-running',
+            notices: focused
+                ? []
+                : [
+                    `${def.title} is already open as ${base.ref}; switch to it from the Dock (sideby does not start a second one)`,
+                ],
+        };
+    }
+    let created = false;
+    const notices = [];
+    if (appData) {
+        const st = await lstatOrNull(appData);
+        if (st && !st.isDirectory())
+            throw new UserError(`${appData} is not a folder; move it away, then try again (sideby keeps the ${def.title} window ${base.ref} there)`, { code: 'app-data-invalid' });
+        if (!st) {
+            await mkdir(appData, { recursive: true, mode: 0o700 });
+            await chmod(appData, 0o700);
+            created = true;
+        }
+        if (created || !(await readdir(appData)).length) {
+            const others = procs.some((p) => mainArgs(app, p) !== null);
+            notices.push(`New ${def.title} window ${base.ref}: sign in inside it with the account you want for this window.${others ? ` Close the other ${def.title} windows while you sign in, because the browser may send the sign-in back to one of them.` : ''}`);
+        }
+    }
+    // As for a Desktop App: `-n` also for the Main Profile, unless a running one cannot be ruled out.
+    const args = appData ? def.openArgs(app.path, appData) : listed ? ['-n', '-a', app.path] : ['-a', app.path];
+    const r = await deps.exec('/usr/bin/open', args, cleanEnv(rt.env, def.clearVars));
+    if (r.code !== 0)
+        throw new UserError(`could not open ${def.title} as ${base.ref}: ${r.stderr.trim() || `open exited with ${r.code}`}; try opening ${app.path} once by hand, then try again`, { code: 'open-failed' });
+    return { ...base, action: 'started', createdAppData: created, command: ['/usr/bin/open', ...args], notices };
+}
+/**
+ * Removes a non-main App Profile's folder, which signs that window out and deletes its local data. Without `yes` it
+ * only returns what would go. Refuses the Main Profile, a running window, a missing folder and anything that is not a
+ * real folder inside sideby's own; never follows a link.
+ */
+export async function removeAppProfile(rt, ref, opts) {
+    const parsed = parseProfileRef(ref);
+    if (!parsed)
+        throw new UserError(`${ref} is not an app window; use \`sideby desktop grok-bot:<name> --remove\``);
+    const { def, name } = parsed;
+    checkName(def, name);
+    const full = `${def.id}:${name}`;
+    if (name === MAIN)
+        throw new UserError(`${full} is ${def.title}'s own data, which sideby does not remove; sign out inside ${def.title} instead`, { code: 'main-profile' });
+    const deps = depsFor(rt);
+    if (deps.platform !== 'darwin')
+        throw notMac(deps.platform);
+    const appData = appDataOf(rt.paths.home, def, name);
+    const st = await lstatOrNull(appData);
+    if (!st)
+        throw new UserError(`there is no ${def.title} window ${full}; \`sideby list\` shows the ones there are`, {
+            code: 'no-profile',
+        });
+    if (!st.isDirectory())
+        throw new UserError(`${appData} is not a folder sideby made; it was left alone, move it away by hand`, {
+            code: 'app-data-invalid',
+        });
+    const app = await findApp(def, deps, { spotlight: true });
+    // Without a process list an open window cannot be ruled out, and deleting under a running app breaks it.
+    const procs = app ? await processes(deps) : [];
+    if (procs === null || (app && instanceOf(app, appData, procs)))
+        throw new UserError(procs === null
+            ? `could not check whether ${def.title} is open as ${full}; quit that window, then try again`
+            : `${def.title} is open as ${full}; quit that window first, then remove it`, { code: 'app-running' });
+    if (!opts.yes)
+        return { ref: full, app: def.title, appData, removed: false };
+    await rm(appData, { recursive: true, force: true });
+    return { ref: full, app: def.title, appData, removed: true };
+}

package/dist/src/core/brand-mark.d.ts

@@ -0,0 +1,83 @@
+/** An outlined shape of one buddy, as SVG path data on its 64-unit grid. */
+export interface BuddyPath {
+    d: string;
+    /** `body`, `shade`: the buddy's own colours; `none`: an open line. */
+    fill: 'body' | 'shade' | 'none';
+    /** Line colour; `chevron` is the buddy's accent colour. Default ink. */
+    stroke?: 'ink' | 'chevron';
+    /** Line width on the 64-unit grid, before the buddy's scale. Default: the outline width. */
+    width?: number;
+}
+/** A filled ellipse without outline: the eyes and their highlights. */
+export interface BuddyDot {
+    cx: number;
+    cy: number;
+    rx: number;
+    ry: number;
+    fill: 'ink' | 'light';
+}
+/** Back to front: feet, arms, body, then the face. */
+export declare const BUDDY: {
+    paths: readonly BuddyPath[];
+    eyes: readonly BuddyDot[];
+};
+/** The eye highlights sit towards where the buddy looks: `1` right, `-1` left. */
+export declare function highlights(look: 1 | -1): BuddyDot[];
+export interface BuddyColors {
+    body: string;
+    shade: string;
+    chevron: string;
+}
+export declare const MARK_COLORS: {
+    readonly blue: {
+        readonly body: '#3f8fc4';
+        readonly shade: '#29658e';
+        readonly chevron: '#f2b35e';
+    };
+    readonly amber: {
+        readonly body: '#f2b35e';
+        readonly shade: '#c98a35';
+        readonly chevron: '#3f8fc4';
+    };
+    readonly ink: '#1e2a44';
+    readonly light: '#f6f0e5';
+};
+export interface PlacedBuddy {
+    colors: BuddyColors;
+    /** Where the buddy looks (and which way its eye highlights sit). */
+    look: 1 | -1;
+    /** 64-unit grid → mark units: translate by (x, y), then scale. */
+    x: number;
+    y: number;
+    scale: number;
+}
+/** The two buddies in mark units, back first. The blue one in front is the one a Portal's `logoColor` recolours. */
+export declare const MARK: {
+    line: number;
+    placedLine: number;
+    back: PlacedBuddy;
+    front: PlacedBuddy;
+};
+/** The square the pair is drawn in, in mark units (the Panel's 40 px tile and the app icon tile). */
+export declare const MARK_VIEWBOX: {
+    readonly x: -2.5;
+    readonly y: 3;
+    readonly size: 69;
+};
+/** The square around one buddy at full size, for the small cut (favicon). */
+export declare const BUDDY_VIEWBOX: {
+    readonly x: 3;
+    readonly y: 10.5;
+    readonly size: 58;
+};
+/**
+ * The mark as SVG children (no outer <svg>). With `front` omitted the blue buddy's body has no fill of its own, so it
+ * takes the surrounding `fill` (the Panel's `--logo-fg`, which Portals set with `logoColor`); everything else is fixed.
+ */
+export declare function markSvgBody(front?: string): string;
+/** The Panel's header logo: the mark sized for its 40 px tile. */
+export declare const MARK_SVG: string;
+/** `<basePath>/icon.svg`: the whole mark on a transparent square, for a Portal's tab or menu (ADR-0006 amendment). */
+export declare const ICON_SVG: string;
+/** `<basePath>/favicon.svg`: the small cut, the blue buddy alone, for sizes below about 24 px (ADR-0022). */
+export declare const FAVICON_SVG: string;

package/dist/src/core/brand-mark.js

@@ -0,0 +1,88 @@
+// The sideby mark: two buddies side by side, the amber one behind on the left and the blue one in front on the right,
+// looking at each other (ADR-0022, the characters of the intro film). One source for the Panel header, the empty
+// state, the Portal icon, the favicon and the app icon.
+// One buddy is drawn on a 64-unit grid; the mark places two of them with a translate and a scale.
+/** Back to front: feet, arms, body, then the face. */
+export const BUDDY = {
+    paths: [
+        { d: 'M17 48 Q15 58 22 57 Q27 57 27 50 M37 50 Q37 57 42 57 Q49 58 47 48', fill: 'shade' },
+        { d: 'M14 37 C4 32 4 41 14 43 M50 37 C60 32 60 41 50 43', fill: 'body' },
+        {
+            d: 'M12 37 C12 27 17 23 25 23 H39 C47 23 52 27 52 37 C52 48 45 53 32 53 C19 53 12 48 12 37 Z',
+            fill: 'body',
+        },
+        { d: 'M30 27 L34 29.31 L30 31.62', fill: 'none', stroke: 'chevron', width: 2.5 },
+        { d: 'M29 46 Q32 49 35 46', fill: 'none', width: 2.5 },
+    ],
+    eyes: [
+        { cx: 22, cy: 38.5, rx: 4.5, ry: 6, fill: 'ink' },
+        { cx: 42, cy: 38.5, rx: 4.5, ry: 6, fill: 'ink' },
+    ],
+};
+/** The eye highlights sit towards where the buddy looks: `1` right, `-1` left. */
+export function highlights(look) {
+    return BUDDY.eyes.map((e) => ({
+        cx: e.cx + 1.5 * look,
+        cy: e.cy + (look > 0 ? 0.5 : -2),
+        rx: 1.65,
+        ry: 2.1,
+        fill: 'light',
+    }));
+}
+export const MARK_COLORS = {
+    blue: { body: '#3f8fc4', shade: '#29658e', chevron: '#f2b35e' },
+    amber: { body: '#f2b35e', shade: '#c98a35', chevron: '#3f8fc4' },
+    ink: '#1e2a44',
+    light: '#f6f0e5',
+};
+/** The two buddies in mark units, back first. The blue one in front is the one a Portal's `logoColor` recolours. */
+export const MARK = {
+    /** Outline width of a buddy drawn alone, on its 64-unit grid. */
+    line: 2.75,
+    /** Outline width of a placed buddy before its scale, so the outline stays about 2.5 mark units. */
+    placedLine: 3.6,
+    back: { colors: MARK_COLORS.amber, look: 1, x: -2, y: 2, scale: 0.7 },
+    front: { colors: MARK_COLORS.blue, look: -1, x: 22, y: 16, scale: 0.7 },
+};
+/** The square the pair is drawn in, in mark units (the Panel's 40 px tile and the app icon tile). */
+export const MARK_VIEWBOX = { x: -2.5, y: 3, size: 69 };
+/** The square around one buddy at full size, for the small cut (favicon). */
+export const BUDDY_VIEWBOX = { x: 3, y: 10.5, size: 58 };
+function buddySvg(b, line, bodyFill) {
+    const color = (fill) => {
+        if (fill === 'none')
+            return ' fill="none"';
+        if (fill === 'shade')
+            return ` fill="${b.colors.shade}"`;
+        return bodyFill === null ? '' : ` fill="${bodyFill ?? b.colors.body}"`;
+    };
+    const paths = BUDDY.paths
+        .map((p) => {
+        const stroke = p.stroke === 'chevron' ? ` stroke="${b.colors.chevron}"` : '';
+        const width = p.width ? ` stroke-width="${p.width}"` : '';
+        return `<path d="${p.d}"${color(p.fill)}${stroke}${width}/>`;
+    })
+        .join('');
+    const dots = [...BUDDY.eyes, ...highlights(b.look)]
+        .map((e) => `<ellipse cx="${e.cx}" cy="${e.cy}" rx="${e.rx}" ry="${e.ry}" fill="${e.fill === 'ink' ? MARK_COLORS.ink : MARK_COLORS.light}"/>`)
+        .join('');
+    const transform = b.scale === 1 && b.x === 0 && b.y === 0 ? '' : ` transform="translate(${b.x} ${b.y}) scale(${b.scale})"`;
+    return `<g${transform} stroke-width="${line}">${paths}<g stroke="none">${dots}</g></g>`;
+}
+const OUTLINE = `stroke="${MARK_COLORS.ink}" stroke-linecap="round" stroke-linejoin="round"`;
+/**
+ * The mark as SVG children (no outer <svg>). With `front` omitted the blue buddy's body has no fill of its own, so it
+ * takes the surrounding `fill` (the Panel's `--logo-fg`, which Portals set with `logoColor`); everything else is fixed.
+ */
+export function markSvgBody(front) {
+    return `<g ${OUTLINE}>${buddySvg(MARK.back, MARK.placedLine)}${buddySvg(MARK.front, MARK.placedLine, front ?? null)}</g>`;
+}
+const viewBox = (v) => `${v.x} ${v.y} ${v.size} ${v.size}`;
+/** The Panel's header logo: the mark sized for its 40 px tile. */
+export const MARK_SVG = `<svg viewBox="${viewBox(MARK_VIEWBOX)}">${markSvgBody()}</svg>`;
+/** `<basePath>/icon.svg`: the whole mark on a transparent square, for a Portal's tab or menu (ADR-0006 amendment). */
+export const ICON_SVG = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="${viewBox(MARK_VIEWBOX)}" role="img" aria-label="sideby">` +
+    `${markSvgBody(MARK_COLORS.blue.body)}</svg>`;
+/** `<basePath>/favicon.svg`: the small cut, the blue buddy alone, for sizes below about 24 px (ADR-0022). */
+export const FAVICON_SVG = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="${viewBox(BUDDY_VIEWBOX)}">` +
+    `<g ${OUTLINE}>${buddySvg({ ...MARK.front, x: 0, y: 0, scale: 1 }, MARK.line)}</g></svg>`;

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

@@ -62,6 +62,10 @@ export declare const ConfigSchema: Type.TObject<{
             order: Type.TOptional<Type.TArray<Type.TString>>;
         }>>>;
     }>>;
+    update: Type.TOptional<Type.TObject<{
+        check: Type.TOptional<Type.TBoolean>;
+        auto: Type.TOptional<Type.TBoolean>;
+    }>>;
     shellInitFile: Type.TOptional<Type.TObject<{
         zsh: Type.TOptional<Type.TString>;
         bash: Type.TOptional<Type.TString>;
@@ -85,6 +89,18 @@ export declare function editConfigHandoff(file: string, edit: (current: HandoffC
     before: HandoffConfig | undefined;
     after: HandoffConfig | undefined;
 }>;
+export type UpdateConfig = NonNullable<Config['update']>;
+/**
+ * The Panel's Auto Update switch (spec §3.23): changes the config `update` key with `edit` (see `editConfigKey` for
+ * how the file is written). With `dryRun`, shows the change without writing.
+ */
+export declare function editConfigUpdate(file: string, edit: (current: UpdateConfig) => UpdateConfig, opts?: {
+    dryRun?: boolean;
+}): Promise<{
+    changed: boolean;
+    before: UpdateConfig | undefined;
+    after: UpdateConfig | undefined;
+}>;
 export type AccountsConfig = NonNullable<Config['accounts']>;
 /**
  * `sideby model` (spec §3.19): changes the config `accounts` key with `edit` (see `editConfigKey` for how the file is

package/dist/src/core/config.js

@@ -93,6 +93,14 @@ export const ConfigSchema = Type.Object({
         description: 'Make `sideby shell-init` also define Host-named functions (`claude`, `codex`, `grok`) that resume a session by id in the Account that holds it. Off by default.',
     })),
     handoff: Type.Optional(HandoffSchema),
+    update: Type.Optional(Type.Object({
+        check: Type.Optional(Type.Boolean({
+            description: 'Ask the npm registry once a day whether a newer sideby exists, and say so after a command and in the Panel. On by default; `NO_UPDATE_NOTIFIER` or `SIDEBY_NO_UPDATE_NOTIFIER` also turn it off.',
+        })),
+        auto: Type.Optional(Type.Boolean({
+            description: 'Install a newer version by itself after a check, when no `sideby run` is running and the version is not a major one. Off by default.',
+        })),
+    }, { additionalProperties: false, description: 'Update Check and Auto Update (ADR-0021).' })),
     shellInitFile: Type.Optional(Type.Object({
         zsh: Type.Optional(Type.String({ minLength: 1 })),
         bash: Type.Optional(Type.String({ minLength: 1 })),
@@ -158,8 +166,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` (the only two sideby writes are `aliases` and
- * `handoff`, spec §3.10), 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` (sideby writes only `aliases`, `handoff`,
+ * `accounts` and `update`, spec §3.10), 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.
@@ -224,6 +232,13 @@ async function editConfigAliases(file, retry, edit) {
 export function editConfigHandoff(file, edit, opts = {}) {
     return editConfigKey(file, 'handoff', 'run the command', (current) => edit(current ?? {}), opts);
 }
+/**
+ * The Panel's Auto Update switch (spec §3.23): changes the config `update` key with `edit` (see `editConfigKey` for
+ * how the file is written). With `dryRun`, shows the change without writing.
+ */
+export function editConfigUpdate(file, edit, opts = {}) {
+    return editConfigKey(file, 'update', 'change the setting', (current) => edit(current ?? {}), opts);
+}
 /**
  * `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/desktop-app.d.ts

@@ -2,6 +2,7 @@ import { type DesktopAppDef } from '../families/desktop.ts';
 import type { LoadedPlugin } from '../plugins/loader.ts';
 import type { Runtime } from '../runtime.ts';
 import type { Account, CheckResult, Env } from '../types.ts';
+import { UserError } from './errors.ts';
 export interface ExecResult {
     code: number;
     stdout: string;
@@ -20,6 +21,7 @@ export interface DesktopDeps {
  * `createRuntime` calls it, from its `desktop` option, which is the one way to replace the machine (tests).
  */
 export declare function bindDesktopDeps(rt: Runtime, deps: Partial<DesktopDeps>): void;
+export declare function depsFor(rt: Runtime): DesktopDeps;
 /** The Desktop App of a Family, only when a built-in Plugin provides that Family (a plugin may not claim one). */
 export declare function desktopAppOf(plugins: readonly LoadedPlugin[], familyId: string): DesktopAppDef | undefined;
 /** Where a non-main Account's App Data lives: `~/Library/Application Support/sideby/<family>/<name>`. */
@@ -33,15 +35,28 @@ export interface FoundApp {
  * Finds the app by bundle id: the usual names in the app folders first, then (with `spotlight`) Spotlight. Listing
  * Accounts leaves Spotlight out to stay fast; opening one asks it too.
  */
-export declare function findApp(def: DesktopAppDef, deps: DesktopDeps, opts?: {
+export declare function findApp(def: Pick<DesktopAppDef, 'bundleId' | 'bundleNames'>, deps: DesktopDeps, opts?: {
     spotlight?: boolean;
 }): Promise<FoundApp | null>;
 export interface Proc {
     pid: number;
     command: string;
 }
+/** Every process with its command line, or null when `ps` failed (then nothing is known to run). */
+export declare function processes(deps: DesktopDeps): Promise<Proc[] | null>;
+/** The arguments after the app's own executable, when `p` is the app's main process (not a helper). */
+export declare function mainArgs(app: FoundApp, p: Proc): string | null;
 /** The running instance of this Account: the one with its App Data, or for the Main Account the one without any. */
 export declare function instanceOf(app: FoundApp, appData: string | null, procs: readonly Proc[]): Proc | undefined;
+/**
+ * Brings a running app to the front as a Dock click does: a reopen event (`aevt/rapp`) to that one process, so an
+ * app whose windows were all closed opens one again, then NSRunningApplication activation. Activation alone makes
+ * such an app frontmost with nothing on screen (seen 2026-10-14 with the Codex app). Neither needs the Automation
+ * permission.
+ */
+export declare function activate(deps: DesktopDeps, pid: number): Promise<boolean>;
+/** The caller's environment without `clear`, `SIDEBY_*` and the variables of the agent session it may run in. */
+export declare function cleanEnv(base: Env, clear: readonly string[]): Env;
 export interface DesktopOpenResult {
     ref: string;
     family: string;
@@ -61,6 +76,8 @@ export interface DesktopOpenResult {
     /** What the user should know: sign in first, close other windows while signing in. */
     notices: string[];
 }
+export declare function notMac(platform: string): UserError;
+export declare function notInstalled(def: Pick<DesktopAppDef, 'title' | 'installUrl'>, deps: DesktopDeps): UserError;
 /**
  * Opens the Account's Desktop App, or brings its running instance to the front. Never starts a second instance of the
  * same Account, never ends a process, never touches the app bundle or the Host account directory.

package/dist/src/core/desktop-app.js

@@ -5,7 +5,7 @@
 import { execFile } from 'node:child_process';
 import { chmod, mkdir, readdir, readFile, symlink } from 'node:fs/promises';
 import { basename, join } from 'node:path';
-import { desktopDef } from '../families/desktop.js';
+import { desktopDef, profileAppFor } from '../families/desktop.js';
 import { UserError } from './errors.js';
 import { lstatOrNull, statOrNull } from './fs-safe.js';
 import { checkItem } from './share-modes.js';
@@ -28,7 +28,7 @@ const overrides = new WeakMap();
 export function bindDesktopDeps(rt, deps) {
     overrides.set(rt, deps);
 }
-function depsFor(rt) {
+export function depsFor(rt) {
     const o = overrides.get(rt) ?? {};
     return {
         platform: o.platform ?? process.platform,
@@ -102,7 +102,7 @@ export async function findApp(def, deps, opts = {}) {
     return null;
 }
 /** Every process with its command line, or null when `ps` failed (then nothing is known to run). */
-async function processes(deps) {
+export async function processes(deps) {
     const r = await deps.exec(PS, ['-axo', 'pid=,command=']);
     if (r.code !== 0)
         return null;
@@ -115,7 +115,7 @@ async function processes(deps) {
     return out;
 }
 /** The arguments after the app's own executable, when `p` is the app's main process (not a helper). */
-function mainArgs(app, p) {
+export function mainArgs(app, p) {
     const exe = `/${basename(app.path)}/Contents/MacOS/${app.executable}`;
     const at = p.command.indexOf(exe);
     if (at === -1)
@@ -145,7 +145,7 @@ export function instanceOf(app, appData, procs) {
  * such an app frontmost with nothing on screen (seen 2026-10-14 with the Codex app). Neither needs the Automation
  * permission.
  */
-async function activate(deps, pid) {
+export async function activate(deps, pid) {
     const p = Math.trunc(pid);
     const script = [
         "ObjC.import('AppKit');",
@@ -162,11 +162,12 @@ async function activate(deps, pid) {
 }
 /** The environment `open` runs with: the caller's, without anything that would pick another Account (spec §3.5). */
 function openEnv(base, family, def) {
+    return cleanEnv(base, [...family.hijackVars, family.selectVar, ...def.clearVars]);
+}
+/** The caller's environment without `clear`, `SIDEBY_*` and the variables of the agent session it may run in. */
+export function cleanEnv(base, clear) {
     const env = { ...base };
-    for (const v of family.hijackVars)
-        delete env[v];
-    delete env[family.selectVar];
-    for (const v of def.clearVars)
+    for (const v of clear)
         delete env[v];
     for (const k of Object.keys(env))
         if (k.startsWith('SIDEBY_') || isSessionVar(k))
@@ -191,10 +192,19 @@ const SESSION_VARS = new Set([
 function isSessionVar(k) {
     return SESSION_VARS.has(k) || SESSION_PREFIXES.some((p) => k.startsWith(p));
 }
-function notMac(platform) {
+/** `a`, `a and b`, `a, b and c`. */
+function joinNames(ids) {
+    return ids.length < 2 ? ids.join('') : `${ids.slice(0, -1).join(', ')} and ${ids.at(-1)}`;
+}
+/** For a Family whose people use a separate app with App Profiles (grok: Grok Bot), how to open that instead. */
+function profileHint(familyId) {
+    const p = profileAppFor(familyId);
+    return p ? `; for ${p.title}, which signs in on its own, use \`sideby desktop ${p.id}:<name>\`` : '';
+}
+export function notMac(platform) {
     return new UserError(`opening a desktop app per account works on macOS only for now (this is ${platform}); use \`sideby run <account>\` for the terminal`, { code: 'not-macos' });
 }
-function notInstalled(def, deps) {
+export function notInstalled(def, deps) {
     return new UserError(`${def.title} is not installed (looked in ${deps.appDirs.join(' and ')}); install it from ${def.installUrl}, then try again`, { code: 'app-not-installed' });
 }
 /**
@@ -208,7 +218,7 @@ export async function openDesktopApp(rt, ref) {
     const def = family ? desktopAppOf(rt.plugins, account.family) : undefined;
     if (!family || !def) {
         const have = [...rt.families.keys()].filter((id) => desktopAppOf(rt.plugins, id));
-        throw new UserError(`${account.ref}: ${family?.title ?? account.family} has no desktop app sideby can open${have.length ? ` (only ${have.join(' and ')} accounts do)` : ''}; use \`sideby run ${account.ref}\``, { code: 'no-desktop-app' });
+        throw new UserError(`${account.ref}: ${family?.title ?? account.family} has no desktop app sideby can open${have.length ? ` (only ${joinNames(have)} accounts do)` : ''}; use \`sideby run ${account.ref}\`${profileHint(account.family)}`, { code: 'no-desktop-app' });
     }
     if (account.kind === 'api')
         throw new UserError(`${account.ref} is an API account; ${def.title} signs in with a subscription only, so open it for a subscription account, or use \`sideby run ${account.ref}\``, { code: 'api-account' });