sideby 0.5.0 → 0.7.0

package/README.md

@@ -55,7 +55,7 @@ The agent checks Node and your Host CLIs, installs sideby and the skill, creates
 
 ## What it looks like
 
-<img alt="Two terminals: the personal account and the work account running at the same time, then the local quota panel" src="https://raw.githubusercontent.com/Adonis0123/sideby/main/docs/assets/demo.gif" width="1280">
+<img alt="Two terminals: the personal account and the work account running at the same time, both linked to the main account's skills and settings, then the local quota panel, and at 95% Auto Handoff moving work's session to the next account" src="https://raw.githubusercontent.com/Adonis0123/sideby/main/docs/assets/demo.gif" width="1280">
 
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Adonis0123/sideby/main/docs/assets/panel-dark.png">
@@ -71,11 +71,13 @@ The agent checks Node and your Host CLIs, installs sideby and the skill, creates
 | Find and fix config drift between accounts | `sideby doctor --fix` | [Doctor](docs/guide/usage.md#doctor) |
 | See Claude quota (Codex needs no setup) | `sideby quota setup claude --yes` | [Claude quota](docs/guide/usage.md#claude-quota) |
 | Find the cheapest auto-compact size from your own sessions, and use it in one click | `sideby tune` (or the panel's Context tuning tab) | [Context tuning](docs/guide/usage.md#context-tuning) |
+| See each account's model and effort, and set them per account | `sideby model <account>` (or click the model in the panel) | [Model and effort](docs/guide/usage.md#model-and-effort) |
 | Move on when an account hits its limit | `sideby next claude` | [Handoff](docs/guide/usage.md#when-an-account-hits-its-limit) |
 | Let a running task move to the next account by itself when quota runs low (off by default; see the risk) | `sideby handoff enable` (or the panel) | [Auto Handoff](docs/guide/usage.md#auto-handoff) |
 | Short commands such as `ccw` | `sideby alias add ccw claude:work` | [Shell functions](docs/guide/configuration.md#shell-functions) |
 | Reopen a session from Orca and the like in the account that holds it | `"resumeRouting": true` in config | [Resuming from other tools](docs/guide/configuration.md#resuming-from-other-tools) |
-| Open the panel from the Dock or app menu | `sideby app install` | [Desktop app](docs/guide/panel.md#desktop-app) |
+| Open Claude Desktop or the Codex app as one account, several side by side (macOS) | `sideby desktop claude:work` (or the panel) | [Desktop apps](docs/guide/usage.md#desktop-apps) |
+| Open the panel from the Dock or app menu | `sideby app install` | [Panel app](docs/guide/panel.md#panel-app) |
 | Show the panel inside your own local page | `createPanelHandler()` | [Embed the panel](docs/guide/panel.md#embed-the-panel) |
 | Add a Host or a pre-launch check | a local plugin | [Plugins](docs/guide/plugins.md) |
 
@@ -113,7 +115,7 @@ Usage questions and ideas go in [Discussions](https://github.com/Adonis0123/side
 - [Using sideby](docs/guide/usage.md): accounts, API accounts, Doctor, quota, Handoff, Host notes
 - [Commands](docs/guide/commands.md): every command, exit codes and `--json`
 - [Configuration](docs/guide/configuration.md): `config.json`, aliases, shell functions
-- [Panel](docs/guide/panel.md): the panel, desktop app and embedding
+- [Panel](docs/guide/panel.md): the panel, panel app and embedding
 - [Plugins](docs/guide/plugins.md): write your own Family or launch hook
 - [FAQ](docs/guide/faq.md): terms of service, data locations, alternatives, uninstall
 - [Changelog](https://github.com/Adonis0123/sideby/releases)

package/dist/build.json

@@ -1 +1 @@
-{"id":"20261014T061214-0f7370"}
+{"id":"20261014T084812-64e992"}

package/dist/src/cli/commands.d.ts

@@ -43,6 +43,11 @@ export declare function cmdResume(a: ParsedArgs, io: Io): Promise<number>;
 /** `sideby next <family>`: recommend the Account with the most room, then start it (spec §3.13). */
 export declare function cmdNext(a: ParsedArgs, io: Io): Promise<number>;
 export declare function cmdDoctor(a: ParsedArgs, io: Io): Promise<number>;
+/**
+ * `sideby model <account> [<model>|default] [--effort <level>|default] [--yes]` (spec §3.19, ADR-0014): shows the
+ * Account's model and effort; with a change, shows it (exit 10) and writes it with --yes.
+ */
+export declare function cmdModel(a: ParsedArgs, io: Io): Promise<number>;
 /** `sideby tune [account|family]`: estimated Compaction Threshold per model (spec §3.18). */
 export declare function cmdTune(a: ParsedArgs, io: Io): Promise<number>;
 export declare function cmdQuota(a: ParsedArgs, io: Io): Promise<number>;
@@ -52,6 +57,8 @@ export declare function cmdPlugins(a: ParsedArgs, io: Io): Promise<number>;
 export declare function cmdShellInit(a: ParsedArgs, io: Io): Promise<number>;
 export declare function cmdUi(a: ParsedArgs, io: Io): Promise<number>;
 export declare function cmdApp(a: ParsedArgs, io: Io): Promise<number>;
+/** `sideby desktop <account>`: the Family's Desktop App as that Account (spec §3.20). */
+export declare function cmdDesktop(a: ParsedArgs, io: Io): Promise<number>;
 export declare function cmdAlias(a: ParsedArgs, io: Io): Promise<number>;
 /** `sideby families [family]`: each Family's layout, sign-in and Shared Items, from its FamilyDef (spec §3.16). */
 export declare function cmdFamilies(a: ParsedArgs, io: Io): Promise<number>;

package/dist/src/cli/commands.js

@@ -1,11 +1,13 @@
 import { fileURLToPath } from 'node:url';
 import { aliasesByAccount } from '../core/accounts.js';
 import { aliasRefs } from '../core/config.js';
+import { openDesktopApp, withDesktopApps } from '../core/desktop-app.js';
 import { UserError } from '../core/errors.js';
 import { requestHandoff } from '../core/handoff-chain.js';
 import { explain, readyDecision, runWithHandoff } from '../core/handoff-run.js';
 import { configureHandoff, handoffHint, handoffStatus } from '../core/handoff-status.js';
 import { runHost } from '../core/launch.js';
+import { accountModel, setAccountModel } from '../core/model-choice.js';
 import { resolvePaths, tildify } from '../core/paths.js';
 import { USAGE_DAYS } from '../core/quota-levels.js';
 import { SHELLS } from '../core/shell-init.js';
@@ -52,7 +54,8 @@ function tilde(text, home) {
 export async function cmdList(a, io) {
     const rt = await createRuntime();
     const accounts = await rt.accounts();
-    const statuses = await Promise.all(accounts.map((x) => rt.status(x)));
+    const statuses = await withDesktopApps(rt, accounts, Promise.all(accounts.map((x) => rt.status(x))));
+    const hasDesktop = statuses.some((s) => s.desktopApp);
     const families = await rt.familyInfo();
     if (a.flags.has('json')) {
         json(io, { families, accounts: statuses, pluginErrors: [...rt.pluginErrors] });
@@ -81,8 +84,9 @@ export async function cmdList(a, io) {
             s.identity?.email ?? c.dim('—'),
             s.model ?? c.dim('—'),
             s.hostInstalled ? tildify(s.dir, home) : `${tildify(s.dir, home)} ${c.yellow('(host not installed)')}`,
+            ...(hasDesktop ? [s.desktopApp?.running ? c.green('open') : c.dim('—')] : []),
         ]);
-        io.out(table(rows, ['ACCOUNT', 'TYPE', 'LOGIN', 'EMAIL', 'MODEL', 'DIR']));
+        io.out(table(rows, ['ACCOUNT', 'TYPE', 'LOGIN', 'EMAIL', 'MODEL', 'DIR', ...(hasDesktop ? ['DESKTOP'] : [])]));
         io.out(c.dim('\nsideby run <account>  ·  sideby new <family> <name>  ·  sideby quota  ·  sideby ui'));
     }
     for (const s of statuses)
@@ -401,6 +405,72 @@ async function cmdTuneChange(a, io, action) {
         io.out(r.message);
     return r.ok ? 0 : 1;
 }
+const FROM = {
+    sideby: 'set by sideby',
+    host: 'from the host config',
+    last: 'last session',
+};
+/**
+ * `sideby model <account> [<model>|default] [--effort <level>|default] [--yes]` (spec §3.19, ADR-0014): shows the
+ * Account's model and effort; with a change, shows it (exit 10) and writes it with --yes.
+ */
+export async function cmdModel(a, io) {
+    const [ref, model] = a.positionals;
+    if (!ref || a.positionals.length > 2 || a.flags.get('effort') === true)
+        throw new UsageError('usage: sideby model <account> [<model>|default] [--effort <level>|default] [--yes] [--json]');
+    const wantJson = a.flags.has('json');
+    const rt = await createRuntime();
+    const account = await rt.resolve(ref);
+    const effort = a.flags.get('effort');
+    const view = await accountModel(rt, account);
+    const shown = {
+        account: account.ref,
+        family: account.family,
+        settable: view.settable,
+        ...(view.reason ? { reason: view.reason } : {}),
+        efforts: view.efforts,
+        models: view.models,
+        sideby: view.sideby,
+        host: view.host,
+        last: view.last,
+        ...(view.model ? { model: view.model } : {}),
+        ...(view.effort ? { effort: view.effort } : {}),
+    };
+    if (model === undefined && effort === undefined) {
+        if (a.flags.has('yes'))
+            throw new UsageError('--yes needs a change: sideby model <account> <model> or --effort <level>');
+        if (wantJson)
+            json(io, shown);
+        else {
+            io.out(account.ref);
+            io.out(`  model   ${view.model ? `${view.model.value}  (${FROM[view.model.from]})` : 'the host default'}`);
+            io.out(`  effort  ${view.effort ? `${view.effort.value}  (${FROM[view.effort.from]})` : 'the host default'}`);
+            if (view.settable)
+                io.out(c.dim(`Change it: sideby model ${account.ref} <model|default> --effort <${view.efforts.join('|')}|default>`));
+            else if (view.reason)
+                io.out(c.dim(view.reason));
+        }
+        return 0;
+    }
+    const asChange = (v) => (v === undefined ? undefined : v === 'default' ? null : v);
+    const change = {
+        ...(model !== undefined ? { model: asChange(model) } : {}),
+        ...(typeof effort === 'string' ? { effort: asChange(effort) } : {}),
+    };
+    const yes = a.flags.has('yes');
+    const r = await setAccountModel(rt, account, change, { apply: yes });
+    const home = rt.paths.home;
+    const result = { ...r, file: tilde(r.file, home) };
+    if (wantJson)
+        json(io, { ...shown, change: result });
+    else if (!r.changed)
+        io.out('Nothing to change.');
+    else if (!yes)
+        io.out(`${r.diff}Run again with --yes to apply. It affects sessions started with sideby from now on.`);
+    else
+        io.out(`Saved. New sessions of ${account.ref} started with sideby use: ${r.args.join(' ') || 'the host defaults'}`);
+    return r.changed && !yes ? 10 : 0;
+}
 /** `sideby tune [account|family]`: estimated Compaction Threshold per model (spec §3.18). */
 export async function cmdTune(a, io) {
     if (a.positionals[0] === 'apply' || a.positionals[0] === 'undo')
@@ -830,6 +900,30 @@ export async function cmdApp(a, io) {
     }
     return r.skipped.length ? 1 : 0;
 }
+/** `sideby desktop <account>`: the Family's Desktop App as that Account (spec §3.20). */
+export async function cmdDesktop(a, io) {
+    const [ref, ...extra] = a.positionals;
+    if (!ref || extra.length || a.rest.length)
+        throw new UsageError('usage: sideby desktop <account>');
+    const rt = await createRuntime();
+    const r = await openDesktopApp(rt, ref);
+    if (a.flags.has('json')) {
+        json(io, r);
+        return 0;
+    }
+    const home = rt.paths.home;
+    if (r.action === 'started')
+        io.out(`${c.green('✓')} opened ${r.app} as ${c.bold(r.ref)}`);
+    else if (r.action === 'focused')
+        io.out(`${c.green('✓')} ${r.app} is already open as ${c.bold(r.ref)}; brought it to the front`);
+    if (r.appData)
+        io.out(c.dim(`  its data: ${tildify(r.appData, home)}`));
+    for (const f of r.linked)
+        io.out(c.dim(`  linked ${f} to the main account's`));
+    for (const n of r.notices)
+        io.err(c.cyan(n));
+    return 0;
+}
 export async function cmdAlias(a, io) {
     const [sub, alias, target, ...more] = a.positionals;
     const usage = 'usage: sideby alias add <short-command> <account> [-- host args]  |  sideby alias rm <short-command>';

package/dist/src/cli/json-schemas.js

@@ -6,6 +6,11 @@ const Str = Type.String();
 const Level = Type.Union([Type.Literal('ok'), Type.Literal('warn'), Type.Literal('fail')]);
 const Kind = Type.Union([Type.Literal('subscription'), Type.Literal('api')]);
 const Version = Type.Literal(1);
+const Choice = Type.Object({ model: Type.Optional(Str), effort: Type.Optional(Str) });
+const Shown = Type.Object({
+    value: Str,
+    from: Type.Union([Type.Literal('sideby'), Type.Literal('host'), Type.Literal('last')]),
+});
 const AppPlatform = Type.Union([Type.Literal('darwin'), Type.Literal('linux')]);
 const Account = Type.Object({
     family: Str,
@@ -32,6 +37,9 @@ const AccountStatus = Type.Intersect([
             description: "Who the account is signed in as, from the host's login file: identity fields only, never a token (ADR-0003).",
         })),
         problems: Type.Optional(Type.Array(Str)),
+        desktopApp: Type.Optional(Type.Object({ app: Str, installed: Type.Boolean(), running: Type.Boolean() }, {
+            description: "The family's desktop app for this account (macOS, subscription accounts of claude and codex): whether it is installed and whether this account's own window runs now. Open it with `sideby desktop <account>`.",
+        })),
     }),
 ]);
 const FamilyInfo = Type.Object({
@@ -162,6 +170,8 @@ const Usage = Type.Union([
             description: 'Tokens per local day (YYYY-MM-DD), oldest first, days without records as 0.',
         })),
         lastActivityAt: Type.Optional(Str),
+        lastModel: Type.Optional(Str),
+        lastEffort: Type.Optional(Str),
     }),
     Type.Object({ status: Type.Literal('unavailable'), reason: Str, detail: Type.Optional(Str) }),
 ]);
@@ -219,6 +229,29 @@ export const OUTPUT_SCHEMAS = {
         })),
         message: Type.Optional(Str),
     }, { title: 'sideby tune apply|undo --json' }),
+    model: Type.Object({
+        schemaVersion: Version,
+        account: Str,
+        family: Str,
+        settable: Type.Boolean({
+            description: 'Whether sideby can set the model and effort for this account.',
+        }),
+        reason: Type.Optional(Str),
+        efforts: Type.Array(Str),
+        models: Type.Array(Str, { description: 'Model names to offer; any other name may be given.' }),
+        sideby: Choice,
+        host: Choice,
+        last: Choice,
+        model: Type.Optional(Shown),
+        effort: Type.Optional(Shown),
+        change: Type.Optional(Type.Object({
+            changed: Type.Boolean(),
+            applied: Type.Boolean(),
+            file: Str,
+            diff: Str,
+            args: Type.Array(Str, { description: 'The account arguments in the config after the change.' }),
+        })),
+    }, { title: 'sideby model --json' }),
     tune: Type.Object({
         schemaVersion: Version,
         accounts: Type.Array(Type.Object({ ref: Str, family: Str, tuning: Tuning })),
@@ -365,6 +398,25 @@ export const OUTPUT_SCHEMAS = {
         removed: Type.Array(Str),
         skipped: Type.Array(Type.Object({ path: Str, reason: Str })),
     }, { title: 'sideby app uninstall --json' }),
+    desktop: Type.Object({
+        schemaVersion: Version,
+        ref: Str,
+        family: Str,
+        app: Type.String({ description: 'The desktop app, for example `Claude Desktop`.' }),
+        appPath: Str,
+        action: Type.Union([Type.Literal('started'), Type.Literal('focused'), Type.Literal('already-running')], {
+            description: '`started`: a new window for this account; `focused`: its running window was brought to the front; `already-running`: it runs but could not be brought to the front.',
+        }),
+        appData: Type.Optional(Type.String({
+            description: "This account's app data folder; absent for the main account, which uses the app's default.",
+        })),
+        createdAppData: Type.Boolean(),
+        linked: Type.Array(Str, {
+            description: "Files linked into a new app data folder from the main account's (claude_desktop_config.json).",
+        }),
+        command: Type.Optional(Type.Array(Str, { description: 'The `open` command sideby ran.' })),
+        notices: Type.Array(Str),
+    }, { title: 'sideby desktop --json' }),
     error: Type.Object({
         schemaVersion: Version,
         error: Type.String({ description: 'What went wrong and what to do next.' }),

package/dist/src/cli/main.js

@@ -32,6 +32,8 @@ Usage:
   sideby quota teardown claude        undo it, restoring the original file
   sideby tune [account|family]        estimate the cheapest auto-compact threshold per model
                                       from your last 7 days of sessions (read-only)
+  sideby model <account> [<model>|default] [--effort <level>|default] [--yes]
+                                      show or set the model and effort sideby starts this account with
   sideby handoff status               what Auto Handoff still needs on this machine
   sideby handoff enable [--yes]       turn it on (shows the config change first); --same-family,
                                       --order claude=codex001,cc002, --threshold n, --prepare-at n
@@ -43,6 +45,8 @@ Usage:
   sideby ui [--port n] [--no-open]    open the local panel
   sideby ui --background              same, without a terminal: keeps running after this command exits
   sideby ui --stop                    stop the background panel
+  sideby desktop <account>            open the desktop app (Claude Desktop, the Codex app) as this
+                                      account, next to the others (macOS)
   sideby app install [--url <url>]    add a sideby app that opens the panel (macOS, Linux)
   sideby app uninstall                remove that app
   sideby shell-init zsh|bash          print shell functions, e.g. eval "$(sideby shell-init zsh)"
@@ -51,8 +55,9 @@ Usage:
   sideby plugins                      list loaded plugins and load errors
 
 Options:
-  --json        machine-readable output (list, new, next, alias, doctor, quota, tune, handoff, families, plugins, app)
-  -h, --help    show this help; \`sideby <command> --help\` for new, alias, login, doctor, families
+  --json        machine-readable output (list, new, next, alias, doctor, quota, tune, handoff, families, plugins, app,
+                desktop)
+  -h, --help    show this help; \`sideby <command> --help\` for new, alias, login, doctor, families, desktop
   -v, --version show the version
 
 An <account> is <family>:<name> (claude:work) or just <name> when it is unique.
@@ -123,6 +128,24 @@ Examples:
   sideby doctor --json
   sideby doctor claude:008 --fix
 Exit: 0 when nothing fails (warnings allowed); 1 when a check fails.`,
+    desktop: `sideby desktop <account> [--json]
+
+Open the host's desktop app as one account: Claude Desktop for claude accounts, the Codex app (ChatGPT.app) for codex
+accounts. Each account gets its own window, side by side with the others; macOS only for now.
+
+The main account opens the app as usual. Any other subscription account opens a new window with that account's
+directory (CLAUDE_CONFIG_DIR, CODEX_HOME) and its own app data folder,
+~/Library/Application Support/sideby/<family>/<name>/. When that account's window is already open, sideby brings it
+to the front instead of starting another one. API accounts are refused: the apps sign in with a subscription only.
+
+sideby never copies or changes the app, and never closes a window. The first time, sign in inside Claude Desktop;
+close other Claude Desktop windows while you do, because the sign-in may come back to one of them.
+
+Examples:
+  sideby desktop claude:work
+  sideby desktop cc008 --json
+Exit: 0 opened or brought to the front; 1 not macOS, no desktop app for that host, API account, app not installed,
+or the app did not open; 2 malformed command line.`,
     families: `sideby families [family] [--json]
 
 For each host (built in or from a plugin): where its accounts live, the variable that selects one, how to sign
@@ -154,12 +177,14 @@ const COMMANDS = {
     doctor: { flags: ['fix', 'force', 'json'] },
     quota: { flags: ['json', 'yes'] },
     tune: { flags: ['json', 'yes'] },
+    model: { flags: ['json', 'yes'], valued: ['effort'] },
     handoff: {
         flags: ['json', 'yes', 'same-family', 'no-same-family'],
         valued: ['brief', 'order', 'prepare-at', 'threshold', 'wait-minutes', 'countdown'],
     },
     ui: { flags: ['no-open', 'background', 'stop', 'serve-detached'], valued: ['port'] },
     app: { flags: ['json'], valued: ['url'] },
+    desktop: { flags: ['json'] },
     'shell-init': { flags: ['write'] },
     plugins: { flags: ['json'] },
     families: { flags: ['json'] },
@@ -255,12 +280,16 @@ export async function main(argv) {
                 return await cmds.cmdQuota(parsed, io);
             case 'tune':
                 return await cmds.cmdTune(parsed, io);
+            case 'model':
+                return await cmds.cmdModel(parsed, io);
             case 'handoff':
                 return await cmds.cmdHandoff(parsed, io);
             case 'ui':
                 return await cmds.cmdUi(parsed, io);
             case 'app':
                 return await cmds.cmdApp(parsed, io);
+            case 'desktop':
+                return await cmds.cmdDesktop(parsed, io);
             case 'shell-init':
                 return await cmds.cmdShellInit(parsed, io);
             case 'plugins':

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

@@ -85,6 +85,20 @@ export declare function editConfigHandoff(file: string, edit: (current: HandoffC
     before: HandoffConfig | undefined;
     after: HandoffConfig | 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
+ * written). With `dryRun`, shows the change without writing.
+ */
+export declare function editConfigAccounts(file: string, 
+/** Returns null to leave the file as it is. */
+edit: (current: AccountsConfig) => AccountsConfig | null, opts?: {
+    dryRun?: boolean;
+}): Promise<{
+    changed: boolean;
+    before: AccountsConfig | undefined;
+    after: AccountsConfig | undefined;
+}>;
 /**
  * Adds `alias → ref` to the config file's `aliases`, as `{ account, args }` when `args` is not empty (see
  * `editConfigAliases` for how the file is written). Refuses an invalid alias, or one that already starts another

package/dist/src/core/config.js

@@ -224,6 +224,15 @@ async function editConfigAliases(file, retry, edit) {
 export function editConfigHandoff(file, edit, opts = {}) {
     return editConfigKey(file, 'handoff', 'run the command', (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.
+ */
+export function editConfigAccounts(file, 
+/** Returns null to leave the file as it is. */
+edit, opts = {}) {
+    return editConfigKey(file, 'accounts', 'run the command', (current) => edit(current ?? {}), opts);
+}
 /**
  * Adds `alias → ref` to the config file's `aliases`, as `{ account, args }` when `args` is not empty (see
  * `editConfigAliases` for how the file is written). Refuses an invalid alias, or one that already starts another

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

@@ -0,0 +1,96 @@
+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';
+export interface ExecResult {
+    code: number;
+    stdout: string;
+    stderr: string;
+}
+/** What opening a Desktop App needs from the machine; tests replace all of it. */
+export interface DesktopDeps {
+    platform: NodeJS.Platform;
+    /** Folders searched for the app, in order (normally /Applications and ~/Applications). */
+    appDirs: readonly string[];
+    /** Runs a program and resolves with its exit code and output; never rejects. */
+    exec(cmd: string, args: readonly string[], env?: Env): Promise<ExecResult>;
+}
+/**
+ * Internal: makes every Desktop App call made with this Runtime use `deps` instead of the machine. Only
+ * `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;
+/** 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>`. */
+export declare function appDataDir(home: string, account: Pick<Account, 'family' | 'name'>): string;
+export interface FoundApp {
+    path: string;
+    /** `Contents/MacOS/<executable>`: the app's main process runs this. */
+    executable: string;
+}
+/**
+ * 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?: {
+    spotlight?: boolean;
+}): Promise<FoundApp | null>;
+export interface Proc {
+    pid: number;
+    command: string;
+}
+/** 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;
+export interface DesktopOpenResult {
+    ref: string;
+    family: string;
+    /** The app as messages name it, for example `Claude Desktop`. */
+    app: string;
+    appPath: string;
+    /** `started`: a new instance; `focused`: the running one is in front; `already-running`: it runs but stayed behind. */
+    action: 'started' | 'focused' | 'already-running';
+    /** The Account's App Data; absent for the Main Account, which uses the app's default. */
+    appData?: string;
+    /** True when this call created the App Data folder. */
+    createdAppData: boolean;
+    /** Files linked into a new App Data from the Main Account's default one. */
+    linked: string[];
+    /** The `open` arguments, when sideby started the app. */
+    command?: string[];
+    /** What the user should know: sign in first, close other windows while signing in. */
+    notices: string[];
+}
+/**
+ * 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.
+ */
+export declare function openDesktopApp(rt: Runtime, ref: string): Promise<DesktopOpenResult>;
+export interface DesktopAppStatus {
+    /** The app as messages name it. */
+    app: string;
+    installed: boolean;
+    /** That Account's own instance runs now. */
+    running: boolean;
+}
+/**
+ * Desktop App state per Account ref for `sideby list` and the Panel: only on macOS, only Subscription Accounts of a
+ * Family that has one. One process listing for all of them; never throws.
+ */
+export declare function desktopStatuses(rt: Runtime, accounts: readonly Account[]): Promise<Map<string, DesktopAppStatus>>;
+/**
+ * Adds `desktopApp` to each status whose Account has one, for `sideby list` and the Panel. The process listing runs
+ * while `statuses` is still being built; the order of the statuses is kept.
+ */
+export declare function withDesktopApps<T extends {
+    ref: string;
+}>(rt: Runtime, accounts: readonly Account[], statuses: Promise<readonly T[]>): Promise<(T & {
+    desktopApp?: DesktopAppStatus;
+})[]>;
+/**
+ * Doctor's extra checks for an Account's App Data (spec §3.20): the Desktop App's shared files under `link` rules,
+ * only when that Account's App Data folder exists, never for the Main Account (it uses the app's default) or an API
+ * Account. Results are named `app-data/<path>` and are not counted in `shared`. The App Data is the repair boundary:
+ * a fix may only add a missing link inside it, never replace a real file.
+ */
+export declare function checkAppData(plugins: readonly LoadedPlugin[], home: string, account: Account): Promise<CheckResult[]>;