sideby 0.6.0 → 0.7.0

package/README.md

@@ -76,7 +76,8 @@ The agent checks Node and your Host CLIs, installs sideby and the skill, creates
 | 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) |
 
@@ -114,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":"20261014T070544-66900c"}
+{"id":"20261014T084812-64e992"}

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

@@ -57,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,6 +1,7 @@
 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';
@@ -53,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] });
@@ -82,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)
@@ -897,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

@@ -37,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({
@@ -395,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

@@ -45,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)"
@@ -53,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.
@@ -125,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
@@ -163,6 +184,7 @@ const COMMANDS = {
     },
     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'] },
@@ -266,6 +288,8 @@ export async function main(argv) {
                 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/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[]>;

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

@@ -0,0 +1,371 @@
+// Opens a Family's Desktop App for one Account (spec §3.20, ADR-0015): macOS only, built-in claude and codex only.
+// The app bundle is started unchanged with `open`; another Account's instance gets its own App Data folder. Every
+// program sideby runs here (`open`, `ps`, `osascript`, `plutil`, `mdfind`) goes through `DesktopDeps.exec`, so
+// tests never start a real app.
+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 { UserError } from './errors.js';
+import { lstatOrNull, statOrNull } from './fs-safe.js';
+import { checkItem } from './share-modes.js';
+const OPEN = '/usr/bin/open';
+const PS = '/bin/ps';
+const OSASCRIPT = '/usr/bin/osascript';
+const PLUTIL = '/usr/bin/plutil';
+const MDFIND = '/usr/bin/mdfind';
+function defaultExec(cmd, args, env) {
+    return new Promise((resolve) => execFile(cmd, [...args], { timeout: 15_000, maxBuffer: 16 * 1024 * 1024, ...(env ? { env: env } : {}) }, (err, stdout, stderr) => {
+        const code = err ? (typeof err.code === 'number' ? err.code : 1) : 0;
+        resolve({ code, stdout: String(stdout ?? ''), stderr: String(stderr ?? '') });
+    }));
+}
+const overrides = new WeakMap();
+/**
+ * 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 function bindDesktopDeps(rt, deps) {
+    overrides.set(rt, deps);
+}
+function depsFor(rt) {
+    const o = overrides.get(rt) ?? {};
+    return {
+        platform: o.platform ?? process.platform,
+        appDirs: o.appDirs ?? ['/Applications', join(rt.paths.home, 'Applications')],
+        exec: o.exec ?? defaultExec,
+    };
+}
+/** The Desktop App of a Family, only when a built-in Plugin provides that Family (a plugin may not claim one). */
+export function desktopAppOf(plugins, familyId) {
+    const builtin = plugins.some((p) => p.source === 'builtin' && p.families.includes(familyId));
+    return builtin ? desktopDef(familyId) : undefined;
+}
+/** Where a non-main Account's App Data lives: `~/Library/Application Support/sideby/<family>/<name>`. */
+export function appDataDir(home, account) {
+    return join(home, 'Library', 'Application Support', 'sideby', account.family, account.name);
+}
+const plistString = (xml, key) => {
+    const m = new RegExp(`<key>${key}</key>\\s*<string>([^<]*)</string>`).exec(xml);
+    return m?.[1];
+};
+/** Reads string keys of an app's Info.plist: XML directly, a binary plist through `plutil`. */
+async function bundleInfo(deps, app) {
+    const file = join(app, 'Contents', 'Info.plist');
+    let text;
+    try {
+        text = await readFile(file, 'utf8');
+    }
+    catch {
+        return {};
+    }
+    if (text.startsWith('<?xml') || text.includes('<plist'))
+        return { id: plistString(text, 'CFBundleIdentifier'), exe: plistString(text, 'CFBundleExecutable') };
+    const read = async (key) => {
+        const r = await deps.exec(PLUTIL, ['-extract', key, 'raw', '-o', '-', file]);
+        return r.code === 0 ? r.stdout.trim() || undefined : undefined;
+    };
+    return { id: await read('CFBundleIdentifier'), exe: await read('CFBundleExecutable') };
+}
+/**
+ * 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 async function findApp(def, deps, opts = {}) {
+    const check = async (path) => {
+        if (!(await statOrNull(path))?.isDirectory())
+            return null;
+        const info = await bundleInfo(deps, path);
+        if (info.id !== def.bundleId)
+            return null;
+        return { path, executable: info.exe || basename(path, '.app') };
+    };
+    for (const dir of deps.appDirs)
+        for (const name of def.bundleNames) {
+            const found = await check(join(dir, name));
+            if (found)
+                return found;
+        }
+    if (!opts.spotlight)
+        return null;
+    const r = await deps.exec(MDFIND, [`kMDItemCFBundleIdentifier == "${def.bundleId}"`]);
+    if (r.code !== 0)
+        return null;
+    for (const line of r.stdout.split('\n')) {
+        const p = line.trim();
+        if (!p.endsWith('.app') || p.includes('/.Trash/'))
+            continue;
+        const found = await check(p);
+        if (found)
+            return found;
+    }
+    return null;
+}
+/** Every process with its command line, or null when `ps` failed (then nothing is known to run). */
+async function processes(deps) {
+    const r = await deps.exec(PS, ['-axo', 'pid=,command=']);
+    if (r.code !== 0)
+        return null;
+    const out = [];
+    for (const line of r.stdout.split('\n')) {
+        const m = /^\s*(\d+)\s+(.*)$/.exec(line);
+        if (m)
+            out.push({ pid: Number(m[1]), command: m[2].trimEnd() });
+    }
+    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) {
+    const exe = `/${basename(app.path)}/Contents/MacOS/${app.executable}`;
+    const at = p.command.indexOf(exe);
+    if (at === -1)
+        return null;
+    const rest = p.command.slice(at + exe.length);
+    return rest === '' || rest.startsWith(' ') ? rest : null;
+}
+/** The running instance of this Account: the one with its App Data, or for the Main Account the one without any. */
+export function instanceOf(app, appData, procs) {
+    return procs.find((p) => {
+        const args = mainArgs(app, p);
+        if (args === null)
+            return false;
+        if (appData === null)
+            return !args.includes('--user-data-dir=');
+        const flag = ` --user-data-dir=${appData}`;
+        const at = args.indexOf(flag);
+        if (at === -1)
+            return false;
+        const after = args.slice(at + flag.length);
+        return after === '' || after.startsWith(' ') || after === '/' || after.startsWith('/ ');
+    });
+}
+/** Brings a running app to the front through NSRunningApplication (no Automation permission needed). */
+async function activate(deps, pid) {
+    const script = [
+        "ObjC.import('AppKit');",
+        `const app = $.NSRunningApplication.runningApplicationWithProcessIdentifier(${Math.trunc(pid)});`,
+        "app.isNil() ? 'missing' : (app.activateWithOptions($.NSApplicationActivateAllWindows | $.NSApplicationActivateIgnoringOtherApps) ? 'ok' : 'refused')",
+    ].join(' ');
+    const r = await deps.exec(OSASCRIPT, ['-l', 'JavaScript', '-e', script]);
+    return r.code === 0 && r.stdout.trim() === 'ok';
+}
+/** The environment `open` runs with: the caller's, without anything that would pick another Account (spec §3.5). */
+function openEnv(base, family, def) {
+    const env = { ...base };
+    for (const v of family.hijackVars)
+        delete env[v];
+    delete env[family.selectVar];
+    for (const v of def.clearVars)
+        delete env[v];
+    for (const k of Object.keys(env))
+        if (k.startsWith('SIDEBY_') || isSessionVar(k))
+            delete env[k];
+    return env;
+}
+/**
+ * Variables an agent session sets for its own children; a Desktop App started from that session must not inherit
+ * them. Named one by one, so a user setting such as `CLAUDE_CODE_USE_BEDROCK` still reaches the app.
+ */
+const SESSION_PREFIXES = ['CODEX_COMPANION_', 'CODEX_SANDBOX'];
+const SESSION_VARS = new Set([
+    'CLAUDE_CODE_SESSION_ID',
+    'CLAUDE_CODE_MESSAGING_TOKEN',
+    'CLAUDE_CODE_ENTRYPOINT',
+    'CLAUDE_CODE_CHILD_SESSION',
+    'CLAUDE_PID',
+    'CLAUDE_PLUGIN_DATA',
+    'CLAUDECODE',
+    'CODEX_THREAD_ID',
+]);
+function isSessionVar(k) {
+    return SESSION_VARS.has(k) || SESSION_PREFIXES.some((p) => k.startsWith(p));
+}
+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) {
+    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' });
+}
+/**
+ * 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 async function openDesktopApp(rt, ref) {
+    const deps = depsFor(rt);
+    const account = await rt.resolve(ref);
+    const family = rt.families.get(account.family);
+    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' });
+    }
+    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' });
+    if (deps.platform !== 'darwin')
+        throw notMac(deps.platform);
+    const app = await findApp(def, deps, { spotlight: true });
+    if (!app)
+        throw notInstalled(def, deps);
+    const home = rt.paths.home;
+    const appData = account.isMain ? null : appDataDir(home, account);
+    const listed = await processes(deps);
+    const procs = listed ?? [];
+    const base = {
+        ref: account.ref,
+        family: account.family,
+        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 for ${account.ref}; switch to it from the Dock (sideby does not start a second one)`,
+                ],
+        };
+    }
+    let created = false;
+    let fresh = false;
+    const linked = [];
+    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 ${def.title}'s data for ${account.ref} there)`, { code: 'app-data-invalid' });
+        if (!st) {
+            await mkdir(appData, { recursive: true, mode: 0o700 });
+            await chmod(appData, 0o700);
+            created = true;
+        }
+        const shared = new Set(def.sharedFiles.map((f) => f.path));
+        fresh = created || (await readdir(appData)).every((e) => shared.has(e));
+        if (fresh)
+            for (const f of def.sharedFiles) {
+                const target = join(appData, f.path);
+                const main = join(home, f.mainPath);
+                // Never replace anything: link only where nothing is, and only to a file the Main Account has.
+                if ((await lstatOrNull(target)) || !(await statOrNull(main))?.isFile())
+                    continue;
+                await symlink(main, target);
+                linked.push(f.path);
+            }
+    }
+    const notices = [];
+    if (!account.isMain && def.signInInApp && fresh) {
+        const others = procs.some((p) => mainArgs(app, p) !== null);
+        notices.push(others
+            ? `First time for ${account.ref}: sign in inside ${def.title} with the account you use for ${account.ref}, not one it suggests from another window. Close the other ${def.title} windows while you sign in, because the browser may send the sign-in back to one of them`
+            : `First time for ${account.ref}: sign in inside ${def.title} with the account you use for ${account.ref}, not one it suggests from another window`);
+    }
+    if (!def.signInInApp) {
+        const login = await Promise.resolve()
+            .then(() => family.loginState?.(account))
+            .catch(() => undefined);
+        if (login === 'logged-out')
+            notices.push(`${account.ref} is not signed in yet; run \`sideby login ${account.ref}\` first. If ${def.title} offers "Welcome back" with your main account's email, do not pick it: that signs this account in as the main one. Choose to use another account`);
+    }
+    // The Main Account needs `-n` too: without it, `open` brings forward whichever instance runs, often another
+    // Account's window. A second Main instance cannot start here, since a running one was found above.
+    // Without a process list a running Main instance cannot be ruled out, so plain `open -a` (no second instance).
+    const mainArgsList = listed ? ['-n', '-a', app.path] : ['-a', app.path];
+    const args = appData ? def.openArgs(app.path, account.dir, appData) : mainArgsList;
+    const r = await deps.exec(OPEN, args, openEnv(rt.env, family, def));
+    if (r.code !== 0)
+        throw new UserError(`could not open ${def.title} for ${account.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, linked, command: [OPEN, ...args], notices };
+}
+/**
+ * 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 async function desktopStatuses(rt, accounts) {
+    const out = new Map();
+    const deps = depsFor(rt);
+    if (deps.platform !== 'darwin')
+        return out;
+    try {
+        const eligible = accounts.filter((a) => a.kind !== 'api' && desktopAppOf(rt.plugins, a.family));
+        if (!eligible.length)
+            return out;
+        const apps = new Map();
+        for (const id of new Set(eligible.map((a) => a.family)))
+            apps.set(id, await findApp(desktopDef(id), deps));
+        const procs = [...apps.values()].some(Boolean) ? ((await processes(deps)) ?? []) : [];
+        for (const a of eligible) {
+            const app = apps.get(a.family) ?? null;
+            out.set(a.ref, {
+                app: desktopDef(a.family).title,
+                installed: app !== null,
+                running: app
+                    ? Boolean(instanceOf(app, a.isMain ? null : appDataDir(rt.paths.home, a), procs))
+                    : false,
+            });
+        }
+    }
+    catch {
+        // A display nicety: a failure leaves the field out.
+    }
+    return out;
+}
+/**
+ * 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 async function withDesktopApps(rt, accounts, statuses) {
+    const [list, desktop] = await Promise.all([statuses, desktopStatuses(rt, accounts)]);
+    return list.map((s) => {
+        const d = desktop.get(s.ref);
+        return d ? { ...s, desktopApp: d } : s;
+    });
+}
+/**
+ * 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 async function checkAppData(plugins, home, account) {
+    if (account.isMain || account.kind === 'api')
+        return [];
+    const def = desktopAppOf(plugins, account.family);
+    if (!def?.sharedFiles.length)
+        return [];
+    const dir = appDataDir(home, account);
+    if (!(await lstatOrNull(dir))?.isDirectory())
+        return [];
+    const out = [];
+    for (const f of def.sharedFiles) {
+        const item = { path: f.path, mode: 'link' };
+        const mainPath = join(home, f.mainPath);
+        const p = join(dir, item.path);
+        const res = await checkItem({ account, item, mainPath, accountPath: p, accountDir: dir, force: false });
+        for (const r of res.results) {
+            if (r.level === 'ok')
+                continue;
+            // The Desktop App writes its own file when the Main Account had none at first open, and may replace the link
+            // later: not the user's doing, so a warning with the way to share, never a failure and never replaced.
+            const own = r.code === 'link.real-file'
+                ? {
+                    level: 'warn',
+                    message: `${item.path} is ${def.title}'s own copy for this account, not a link to the main account's`,
+                    hint: `${def.title} made it itself; that is fine. To share the main account's instead, quit that window, then: mv "${p}" "${p}.local" && ln -s "${mainPath}" "${p}"`,
+                }
+                : {};
+            out.push({
+                ...r,
+                ...own,
+                item: `app-data/${item.path}`,
+                message: `${def.title} data: ${own.message ?? r.message}`,
+            });
+        }
+    }
+    return out;
+}