sideby 0.10.0 → 0.11.0

package/README.md

@@ -16,28 +16,17 @@
 
 <p align="center">English | <a href="README.zh-CN.md">中文</a></p>
 
-## Why not just an alias?
-
-`CLAUDE_CONFIG_DIR` plus a shell alias already starts a second account. It does not keep skills and settings in one place, and it does not show quota for every account. [Does this break a provider's terms?](docs/guide/faq.md#terms)
-
-| | At the same time | Skills, hooks, settings | Quota and usage | Setup |
-|---|---|---|---|---|
-| `CLAUDE_CONFIG_DIR` and an alias | Yes. Each terminal exports the variable. | Each directory is its own copy. They drift unless you symlink by hand. | That session's status line | One alias per account |
-| [cc-switch](https://github.com/farion1231/cc-switch) | Enabling a provider writes the host's live config, so open sessions share that switch. | Plugin settings are copied across providers as a separate step. | The active provider, from its quota endpoint | Install the desktop app |
-| sideby | Yes. `sideby run` selects the directory for that process and leaves your shell alone. | Linked to the main account. `sideby doctor --fix` repairs copies. Sign-in and sessions stay separate. | Every account, from local files. Claude needs `quota setup`. | `npm i -g sideby`, then `sideby new` and sign in |
-
-cc-switch's docs describe that switch: it writes the live settings file ([README](https://github.com/farion1231/cc-switch#readme)). [#1105](https://github.com/farion1231/cc-switch/issues/1105) and [#2908](https://github.com/farion1231/cc-switch/issues/2908) ask for several sessions at once. [#1106](https://github.com/farion1231/cc-switch/issues/1106) is closed; the maintainer says Claude Code's "open terminal" can start one provider without changing the global config.
-
 ## Quick start
 
 Requires Node 22.18+ and at least one Host CLI (Claude Code, Codex, Grok Build or pi) installed. AI agents: follow the setup steps in [`llms.txt`](llms.txt) ("Set up sideby for a user") instead.
 
 ```sh
 npm i -g sideby
-sideby new claude work        # create ~/.claude-work, sharing ~/.claude's skills and hooks
-sideby login claude:work      # sign in once
-sideby run work               # Claude Code on the work account
-sideby ui                     # every account's quota at http://127.0.0.1:17420
+sideby new claude work           # create ~/.claude-work, sharing ~/.claude's skills and hooks
+sideby login claude:work         # sign in once
+sideby run work                  # Claude Code on the work account
+sideby quota setup claude --yes  # Claude quota in the panel; undo: sideby quota teardown claude
+sideby ui                        # every account's quota at http://127.0.0.1:17420
 ```
 
 `sideby run claude:main` keeps using `~/.claude` in another terminal at the same time. Arguments after `--` go to the Host: `sideby run work -- --resume`. To try it without installing, run `npx sideby`.
@@ -55,6 +44,10 @@ The agent checks Node and your Host CLIs, installs sideby and the skill, creates
 
 ## What it looks like
 
+The 25-second story: one account buried in tasks, then accounts side by side sharing one setup, and a task moving on when one runs out.
+
+https://github.com/user-attachments/assets/3a470c03-9009-4f1d-b7f6-8b4625d74958
+
 <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>
@@ -63,6 +56,18 @@ The agent checks Node and your Host CLIs, installs sideby and the skill, creates
   <img alt="sideby panel: every account's 5h and 7d quota, 7-day token usage and health in one page" src="https://raw.githubusercontent.com/Adonis0123/sideby/main/docs/assets/panel.png" width="1280">
 </picture>
 
+## Why not just an alias?
+
+`CLAUDE_CONFIG_DIR` plus a shell alias already starts a second account. It does not keep skills and settings in one place, and it does not show quota for every account. [Does this break a provider's terms?](docs/guide/faq.md#terms)
+
+| | At the same time | Skills, hooks, settings | Quota and usage | Setup |
+|---|---|---|---|---|
+| `CLAUDE_CONFIG_DIR` and an alias | Yes. Each terminal exports the variable. | Each directory is its own copy. They drift unless you symlink by hand. | That session's status line | One alias per account |
+| [cc-switch](https://github.com/farion1231/cc-switch) | Enabling a provider writes the host's live config, so open sessions share that switch. | Plugin settings are copied across providers as a separate step. | The active provider, from its quota endpoint | Install the desktop app |
+| sideby | Yes. `sideby run` selects the directory for that process and leaves your shell alone. | Linked to the main account. `sideby doctor --fix` repairs copies. Sign-in and sessions stay separate. | Every account, from local files. Claude needs `quota setup`. | `npm i -g sideby`, then `sideby new` and sign in |
+
+cc-switch's docs describe that switch: it writes the live settings file ([README](https://github.com/farion1231/cc-switch#readme)). [#1105](https://github.com/farion1231/cc-switch/issues/1105) and [#2908](https://github.com/farion1231/cc-switch/issues/2908) ask for several sessions at once. [#1106](https://github.com/farion1231/cc-switch/issues/1106) is closed; the maintainer says Claude Code's "open terminal" can start one provider without changing the global config.
+
 ## What else it does
 
 | You want to | Run | Guide |
@@ -78,6 +83,7 @@ The agent checks Node and your Host CLIs, installs sideby and the skill, creates
 | 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 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) |
+| Keep several Grok Bot windows open, each signed in to its own account (macOS) | `sideby desktop grok-bot:002` (or the panel) | [Grok Bot windows](docs/guide/usage.md#grok-bot-windows) |
 | 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) |

package/dist/build.json

@@ -1 +1 @@
-{"id":"20261015T150956-8c8f4c"}
+{"id":"20261016T040419-834a8d"}

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

@@ -62,7 +62,10 @@ 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). */
+/**
+ * `sideby desktop <account>`: the Family's Desktop App as that Account (spec §3.20); `sideby desktop grok-bot:<name>`:
+ * a Grok Bot window, new or open, and with `--remove` its removal (ADR-0019).
+ */
 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). */

package/dist/src/cli/commands.js

@@ -1,5 +1,6 @@
 import { fileURLToPath } from 'node:url';
 import { aliasesByAccount } from '../core/accounts.js';
+import { listAppProfiles, openAppProfile, parseProfileRef, removeAppProfile } from '../core/app-profiles.js';
 import { aliasRefs } from '../core/config.js';
 import { openDesktopApp, withDesktopApps } from '../core/desktop-app.js';
 import { UserError } from '../core/errors.js';
@@ -55,11 +56,14 @@ function tilde(text, home) {
 export async function cmdList(a, io) {
     const rt = await createRuntime();
     const accounts = await rt.accounts();
-    const statuses = await withDesktopApps(rt, accounts, Promise.all(accounts.map((x) => rt.status(x))));
+    const [statuses, appProfiles] = await Promise.all([
+        withDesktopApps(rt, accounts, Promise.all(accounts.map((x) => rt.status(x)))),
+        listAppProfiles(rt),
+    ]);
     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] });
+        json(io, { families, accounts: statuses, appProfiles, pluginErrors: [...rt.pluginErrors] });
         return 0;
     }
     const home = rt.paths.home;
@@ -94,6 +98,25 @@ export async function cmdList(a, io) {
             io.out(c.dim('\n= <account>: signed in as the same login as that account, so they share one quota.'));
         io.out(c.dim('\nsideby run <account>  ·  sideby new <family> <name>  ·  sideby quota  ·  sideby ui'));
     }
+    // App Profiles (ADR-0019): windows of an app that signs in apart from the Accounts above.
+    for (const app of new Set(appProfiles.map((p) => p.app))) {
+        const list = appProfiles.filter((p) => p.app === app);
+        io.out(`\n${c.bold(app)} ${c.dim('(signs in on its own, not with the accounts above)')}`);
+        io.out(table(list.map((p) => [
+            c.bold(p.ref),
+            p.running ? c.green('open') : c.dim('—'),
+            p.signedIn === true
+                ? c.green('signed in')
+                : p.signedIn === false
+                    ? c.yellow('not signed in')
+                    : c.dim('?'),
+            p.appData ? tildify(p.appData, home) : c.dim('default'),
+        ]), ['WINDOW', 'STATE', 'SIGN-IN', 'DATA']));
+        if (!list[0]?.installed)
+            io.out(c.yellow(`${app} is not installed; these windows open again once it is`));
+        const id = list[0]?.ref.slice(0, list[0].ref.indexOf(':'));
+        io.out(c.dim(`sideby desktop ${id}:<name> opens one (a new name makes a new window)`));
+    }
     for (const s of statuses)
         for (const p of s.problems ?? [])
             io.err(c.yellow(`${s.ref}: ${p}`));
@@ -860,7 +883,10 @@ export async function cmdHandoff(a, io) {
             requested: true,
             ...(next ? { next } : {}),
             ...(request.brief ? { brief: request.brief } : {}),
+            ...(request.now ? { now: true } : {}),
         });
+    else if (request.now)
+        io.out(`This session was waiting for its quota; ${next ?? 'the next account'} takes over now.`);
     else
         io.out(`${next ? `${next} takes over` : 'The next account starts'} when this turn ends; finish the turn now.`);
     return 0;
@@ -1019,13 +1045,32 @@ 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). */
+/**
+ * `sideby desktop <account>`: the Family's Desktop App as that Account (spec §3.20); `sideby desktop grok-bot:<name>`:
+ * a Grok Bot window, new or open, and with `--remove` its removal (ADR-0019).
+ */
 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>');
+        throw new UsageError('usage: sideby desktop <account> | sideby desktop grok-bot:<name> [--remove [--yes]]');
     const rt = await createRuntime();
-    const r = await openDesktopApp(rt, ref);
+    const profile = parseProfileRef(ref) !== undefined;
+    if (a.flags.has('remove')) {
+        if (!profile)
+            throw new UsageError('--remove works on Grok Bot windows only: sideby desktop grok-bot:<name> --remove');
+        const r = await removeAppProfile(rt, ref, { yes: a.flags.has('yes') });
+        if (a.flags.has('json'))
+            json(io, r);
+        else if (r.removed)
+            io.out(`${c.green('✓')} removed the ${r.app} window ${c.bold(r.ref)} and its data`);
+        else {
+            io.out(`Remove the ${r.app} window ${c.bold(r.ref)}?`);
+            io.out(`  deletes ${tildify(r.appData, rt.paths.home)}: its sign-in, bots and local data on this Mac`);
+            io.out('Run again with --yes to remove it.');
+        }
+        return r.removed ? 0 : 10;
+    }
+    const r = profile ? await openAppProfile(rt, ref) : await openDesktopApp(rt, ref);
     if (a.flags.has('json')) {
         json(io, r);
         return 0;

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

@@ -194,11 +194,30 @@ const ShellInitFiles = Type.Array(Type.Object({
     action: Type.Optional(Type.Union([Type.Literal('written'), Type.Literal('unchanged')])),
     message: Type.Optional(Str),
 }), { description: 'One entry per config `shellInitFile`, rewritten after the change.' });
+const AppProfile = Type.Object({
+    ref: Type.String({ description: "`grok-bot:<name>`; `grok-bot:main` is the app's own default data." }),
+    app: Type.String({ description: 'The app, for example `Grok Bot`.' }),
+    name: Str,
+    isMain: Type.Boolean(),
+    appData: Type.Optional(Type.String({
+        description: "This window's data folder; absent for the main one, which uses the app's default.",
+    })),
+    installed: Type.Boolean(),
+    running: Type.Boolean({ description: "This window's own instance runs now." }),
+    signedIn: Type.Optional(Type.Boolean({
+        description: 'What the app last wrote about its sign-in (it keeps the last value after the app quits); absent when unknown. Which account is signed in is not known.',
+    })),
+}, {
+    description: 'A window of a desktop app that signs in apart from every account (Grok Bot, ADR-0019). Open or create one with `sideby desktop grok-bot:<name>`.',
+});
 export const OUTPUT_SCHEMAS = {
     list: Type.Object({
         schemaVersion: Version,
         families: Type.Array(FamilyInfo),
         accounts: Type.Array(AccountStatus),
+        appProfiles: Type.Optional(Type.Array(AppProfile, {
+            description: 'Grok Bot windows (macOS, when Grok Bot is installed or has windows), the main one first. Not accounts.',
+        })),
         pluginErrors: Type.Array(PluginError),
     }, { title: 'sideby list --json' }),
     doctor: Type.Object({
@@ -380,6 +399,8 @@ export const OUTPUT_SCHEMAS = {
         requested: Type.Literal(true),
         next: Type.Optional(Str),
         brief: Type.Optional(Str),
+        /** The session was waiting for its quota, so the handoff starts now instead of after a turn (ADR-0018). */
+        now: Type.Optional(Type.Literal(true)),
     }, { title: 'sideby handoff ready --json' }),
     'handoff-setup': Type.Object({ schemaVersion: Version, family: Str, applied: Type.Boolean(), plan: QuotaSetupPlan }, { title: 'sideby handoff setup --json' }),
     'handoff-teardown': Type.Object({ schemaVersion: Version, family: Str, ok: Type.Boolean(), message: Str, diff: Type.Optional(Str) }, { title: 'sideby handoff teardown --json' }),
@@ -445,7 +466,7 @@ export const OUTPUT_SCHEMAS = {
     desktop: Type.Object({
         schemaVersion: Version,
         ref: Str,
-        family: Str,
+        family: Type.String({ description: 'The family, or `grok-bot` for a Grok Bot window.' }),
         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')], {
@@ -461,6 +482,15 @@ export const OUTPUT_SCHEMAS = {
         command: Type.Optional(Type.Array(Str, { description: 'The `open` command sideby ran.' })),
         notices: Type.Array(Str),
     }, { title: 'sideby desktop --json' }),
+    'desktop-remove': Type.Object({
+        schemaVersion: Version,
+        ref: Str,
+        app: Str,
+        appData: Type.String({ description: 'The folder that is (or would be) deleted.' }),
+        removed: Type.Boolean({
+            description: 'False when only the plan was shown; run again with --yes (exit 10).',
+        }),
+    }, { title: 'sideby desktop grok-bot:<name> --remove --json' }),
     error: Type.Object({
         schemaVersion: Version,
         error: Type.String({ description: 'What went wrong and what to do next.' }),

package/dist/src/cli/main.js

@@ -51,6 +51,7 @@ Usage:
   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 desktop grok-bot:<name>      open a Grok Bot window, a new one for a new name (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)"
@@ -133,6 +134,7 @@ Examples:
   sideby doctor claude:008 --fix
 Exit: 0 when nothing fails (warnings allowed); 1 when a check fails.`,
     desktop: `sideby desktop <account> [--json]
+       sideby desktop grok-bot:<name> [--remove [--yes]] [--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.
@@ -142,14 +144,22 @@ 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.
+Grok Bot signs in with a Cursor account, apart from every account above, so its windows have names of their own:
+grok-bot:<name> opens that window, and makes it first when the name is new (a new window, signed out). grok-bot or
+grok-bot:main is Grok Bot's own default window. --remove deletes a window you made, which signs it out and deletes
+its data on this Mac; it asks for --yes first (exit 10) and refuses while that window is open. \`sideby list\` shows
+the Grok Bot windows.
+
+sideby never copies or changes the app, and never closes a window. The first time, sign in inside the new window;
+close the app's other 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.`,
+  sideby desktop grok-bot:002
+  sideby desktop grok-bot:002 --remove --yes
+Exit: 0 opened, brought to the front or removed; 1 not macOS, no desktop app for that host, API account, app not
+installed, a bad window name, or the app did not open; 10 --remove without --yes; 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
@@ -189,7 +199,7 @@ const COMMANDS = {
     },
     ui: { flags: ['no-open', 'background', 'stop', 'serve-detached'], valued: ['port'] },
     app: { flags: ['json'], valued: ['url'] },
-    desktop: { flags: ['json'] },
+    desktop: { flags: ['json', 'remove', 'yes'] },
     'shell-init': { flags: ['write'] },
     plugins: { flags: ['json'] },
     families: { flags: ['json'] },

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,29 @@
+export type RoundedRect = readonly [x: number, y: number, w: number, h: number, r: number];
+export declare const MARK: {
+    readonly back: readonly [12, 82, 128, 104, 44];
+    readonly front: readonly [116, 70, 128, 116, 46];
+    /** Cut out of the back face (and its eyes) so the two faces never touch. */
+    readonly gap: readonly [104, 58, 152, 140, 58];
+    readonly backEyes: readonly [readonly [45, 119, 14, 26, 7], readonly [83, 119, 14, 26, 7]];
+    readonly frontEyes: readonly [readonly [155, 111, 14, 26, 7], readonly [193, 111, 14, 26, 7]];
+};
+export declare const MARK_COLORS: {
+    readonly front: '#3f8fc4';
+    readonly back: '#f2b35e';
+    readonly eye: '#1e2a44';
+};
+/** The square the mark is drawn in when it sits on a tile (about 78% of the tile is mark). */
+export declare const MARK_TILE_VIEWBOX: {
+    readonly x: -20.5;
+    readonly y: -20.5;
+    readonly size: 297;
+};
+export declare function roundedRectPath([x, y, w, h, r]: RoundedRect): string;
+/**
+ * The mark as SVG children (no outer <svg>). The front face has no fill of its own, so it takes the surrounding
+ * `fill` (the Panel's `--logo-fg`, which Portals can set with `logoColor`); the back face and the eyes are fixed.
+ * `id` names the gap mask; keep it unique per document.
+ */
+export declare function markSvgBody(id: string, front?: string): string;
+/** The Panel's header logo: the mark sized for its 40 px tile. */
+export declare const MARK_SVG: string;

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

@@ -0,0 +1,42 @@
+// The sideby mark: two friendly faces side by side, the amber one behind and the blue one in front, cut apart by a
+// gap that follows the front face (ADR-0020). One source for the Panel header, the empty state and the app icon.
+// Geometry is on a 256-unit grid centred on (128, 128); rounded rectangles are [x, y, width, height, radius].
+export const MARK = {
+    back: [12, 82, 128, 104, 44],
+    front: [116, 70, 128, 116, 46],
+    /** Cut out of the back face (and its eyes) so the two faces never touch. */
+    gap: [104, 58, 152, 140, 58],
+    backEyes: [
+        [45, 119, 14, 26, 7],
+        [83, 119, 14, 26, 7],
+    ],
+    frontEyes: [
+        [155, 111, 14, 26, 7],
+        [193, 111, 14, 26, 7],
+    ],
+};
+export const MARK_COLORS = { front: '#3f8fc4', back: '#f2b35e', eye: '#1e2a44' };
+/** The square the mark is drawn in when it sits on a tile (about 78% of the tile is mark). */
+export const MARK_TILE_VIEWBOX = { x: -20.5, y: -20.5, size: 297 };
+export function roundedRectPath([x, y, w, h, r]) {
+    return (`M${x + r} ${y}H${x + w - r}A${r} ${r} 0 0 1 ${x + w} ${y + r}V${y + h - r}A${r} ${r} 0 0 1 ${x + w - r} ${y + h}` +
+        `H${x + r}A${r} ${r} 0 0 1 ${x} ${y + h - r}V${y + r}A${r} ${r} 0 0 1 ${x + r} ${y}Z`);
+}
+/**
+ * The mark as SVG children (no outer <svg>). The front face has no fill of its own, so it takes the surrounding
+ * `fill` (the Panel's `--logo-fg`, which Portals can set with `logoColor`); the back face and the eyes are fixed.
+ * `id` names the gap mask; keep it unique per document.
+ */
+export function markSvgBody(id, front) {
+    const eyes = (list) => list.map(roundedRectPath).join('');
+    const frontFill = front ? ` fill="${front}"` : '';
+    return (`<mask id="${id}" maskUnits="userSpaceOnUse" x="0" y="0" width="256" height="256">` +
+        `<rect width="256" height="256" fill="#fff"/><path fill="#000" d="${roundedRectPath(MARK.gap)}"/></mask>` +
+        `<g mask="url(#${id})"><path fill="${MARK_COLORS.back}" d="${roundedRectPath(MARK.back)}"/>` +
+        `<path fill="${MARK_COLORS.eye}" d="${eyes(MARK.backEyes)}"/></g>` +
+        `<path${frontFill} d="${roundedRectPath(MARK.front)}"/>` +
+        `<path fill="${MARK_COLORS.eye}" d="${eyes(MARK.frontEyes)}"/>`);
+}
+const V = MARK_TILE_VIEWBOX;
+/** The Panel's header logo: the mark sized for its 40 px tile. */
+export const MARK_SVG = `<svg viewBox="${V.x} ${V.y} ${V.size} ${V.size}">${markSvgBody('sideby-mark-gap')}</svg>`;