sideby 0.1.0 → 0.2.1

package/dist/src/cli/commands.js

@@ -1,10 +1,13 @@
 import { fileURLToPath } from 'node:url';
+import { aliasesByAccount } from '../core/accounts.js';
+import { aliasRefs } from '../core/config.js';
 import { UserError } from '../core/errors.js';
 import { runHost } from '../core/launch.js';
 import { resolvePaths, tildify } from '../core/paths.js';
 import { USAGE_DAYS } from '../core/quota-levels.js';
 import { SHELLS } from '../core/shell-init.js';
-import { createRuntime } from '../runtime.js';
+import { suggestAlias, suggestName } from '../panel/page-logic.js';
+import { createRuntime, UnknownFamilyError } from '../runtime.js';
 import { UsageError } from './args.js';
 import { c, clock, quotaText, table, usageText } from './format.js';
 const json = (io, data) => io.out(JSON.stringify({ schemaVersion: 1, ...data }, null, 2));
@@ -67,20 +70,49 @@ export async function cmdList(a, io) {
         io.err(c.yellow(`plugin ${e.where}: ${e.message}`));
     return 0;
 }
+/**
+ * `new --next`: the next name of a Family, and a short command following the pattern of its existing aliases,
+ * from the same helpers the Panel uses (spec §3.16).
+ */
+async function suggestNew(rt, family, alias) {
+    if (!(await rt.familyInfo()).some((f) => f.id === family))
+        throw new UnknownFamilyError(`unknown family "${family}"; run \`sideby families\` to see them`);
+    const all = await rt.accounts();
+    const mine = all.filter((x) => x.family === family);
+    const name = suggestName(mine.map((x) => x.name));
+    if (alias !== undefined)
+        return { name };
+    const byRef = aliasesByAccount(aliasRefs(rt.config.aliases), all);
+    const offer = suggestAlias(mine.map((x) => ({ family: x.family, name: x.name, ref: x.ref, aliases: byRef.get(x.ref) ?? [] })), family, name);
+    if (!offer)
+        return { name };
+    const problem = rt.aliasProblem(offer, `${family}:${name}`);
+    return problem ? { name, aliasProblem: `${offer}: ${problem}` } : { name, alias: offer };
+}
 export async function cmdNew(a, io) {
-    const [family, name] = a.positionals;
-    if (!family || !name || a.positionals.length > 2)
-        throw new UsageError('usage: sideby new <family> <name> [--api] [--alias <short-command>]');
-    const alias = a.flags.get('alias');
+    const [family, given] = a.positionals;
+    const next = a.flags.has('next');
+    if (!family || (next ? given !== undefined : !given) || a.positionals.length > 2)
+        throw new UsageError(next
+            ? 'usage: sideby new <family> --next [--api] [--alias <short-command>]; --next picks the name, so leave it out'
+            : 'usage: sideby new <family> <name> [--api] [--alias <short-command>], or `--next` instead of <name>');
+    const givenAlias = a.flags.get('alias');
     const rt = await createRuntime();
+    const suggestion = next
+        ? await suggestNew(rt, family, typeof givenAlias === 'string' ? givenAlias : undefined)
+        : undefined;
+    const name = suggestion?.name ?? given;
+    const alias = typeof givenAlias === 'string' ? givenAlias : suggestion?.alias;
     const res = await rt.createAccount(family, name, {
         api: a.flags.has('api'),
-        ...(typeof alias === 'string' ? { alias } : {}),
+        ...(alias !== undefined ? { alias } : {}),
     });
     if (a.flags.has('json')) {
-        json(io, res);
+        json(io, suggestion ? { ...res, suggestion } : res);
         return res.ok ? 0 : 1;
     }
+    if (suggestion?.aliasProblem)
+        io.out(`${c.yellow('!')} no short command: the pattern suggests ${suggestion.aliasProblem}`);
     const home = rt.paths.home;
     const where = tildify(res.account.dir, home);
     if (res.ok)
@@ -122,6 +154,20 @@ export async function cmdRun(a, io, command) {
         io.err(c.cyan(prepared.notice));
     return runHost(prepared);
 }
+/**
+ * `sideby resume <family>`: what the Host-named shell function calls (spec §3.15). Starts the Account that holds the
+ * session the arguments resume by id, or runs the Host unchanged.
+ */
+export async function cmdResume(a, io) {
+    const [family, ...extra] = a.positionals;
+    if (!family)
+        throw new UsageError('usage: sideby resume <family> [-- host args]');
+    const rt = await createRuntime();
+    const route = await rt.resumeLaunch(family, [...extra, ...a.rest]);
+    if (route.account)
+        io.err(c.dim(`sideby: session ${route.sessionId} is in ${route.account.ref}; starting it there`));
+    return runHost(route.launch);
+}
 /** Quotes a Host argument for a command line the user may paste; plain words stay as they are. */
 function shellQuote(arg) {
     return /^[\w@%+=:,./-]+$/.test(arg) ? arg : `'${arg.replace(/'/g, `'\\''`)}'`;
@@ -485,3 +531,36 @@ export async function cmdAlias(a, io) {
     printShellInitWrites(io, res.shellInitFiles ?? [], rt.paths.home);
     return res.ok ? 0 : 1;
 }
+/** `sideby families [family]`: each Family's layout, sign-in and Shared Items, from its FamilyDef (spec §3.16). */
+export async function cmdFamilies(a, io) {
+    const [only, ...extra] = a.positionals;
+    if (extra.length)
+        throw new UsageError('usage: sideby families [family] [--json]');
+    const rt = await createRuntime();
+    const all = await rt.familyDetails();
+    const families = only === undefined ? all : all.filter((f) => f.id === only);
+    if (only !== undefined && families.length === 0)
+        throw new UnknownFamilyError(`unknown family "${only}"; available: ${all.map((f) => f.id).join(', ') || 'none (check `sideby plugins`)'}`);
+    if (a.flags.has('json')) {
+        json(io, { families });
+        return 0;
+    }
+    families.forEach((f, i) => {
+        if (i)
+            io.out('');
+        io.out(`${c.bold(f.title)} (${f.id})  ${f.installed ? c.green('installed') : c.yellow(`not installed: ${f.installUrl}`)}`);
+        io.out(`  Accounts   ~/${f.layout.main} (main), ~/${f.layout.account}; selected with ${f.selectVar}`);
+        io.out(`  Sign in    sideby login ${f.id}:<name>  ${c.dim(f.login.args ? `(runs ${[f.bin, ...f.login.args].join(' ')})` : `(${f.login.hint})`)}`);
+        const yes = (b) => (b ? c.green('yes') : c.dim('no public source'));
+        io.out(`  Quota      ${yes(f.quota)}${f.quotaSetup ? c.dim(`, after \`sideby quota setup ${f.id}\``) : ''}   Usage ${yes(f.usage)}`);
+        io.out('  Shared items, and how each account holds them:');
+        const rows = f.shared.map((s) => [
+            `    ${s.path}${s.key ? `#${s.key}` : ''}`,
+            s.source === 'config' ? `${s.mode} ${c.dim('(config)')}` : s.mode,
+            s.meaning,
+        ]);
+        io.out(table(rows, ['    ITEM', 'MODE', 'IN EACH ACCOUNT']));
+        io.out(c.dim('  Everything else in an account directory is its own: sign-in, sessions and history.'));
+    });
+    return 0;
+}

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

@@ -42,6 +42,37 @@ const FamilyInfo = Type.Object({
     installed: Type.Boolean(),
     plugin: Str,
 });
+const ShareModeSchema = Type.Union(['link', 'copy', 'link-or-copy', 'link-or-local', 'local', 'local-if-api', 'info', 'json-key'].map((m) => Type.Literal(m)));
+const FamilyDetail = Type.Intersect([
+    FamilyInfo,
+    Type.Object({
+        layout: Type.Object({ main: Str, account: Str }, { description: 'Relative to HOME, for example `.claude` and `.claude-<name>`.' }),
+        selectVar: Type.String({
+            description: 'Environment variable that selects a non-main Account directory.',
+        }),
+        login: Type.Object({
+            args: Type.Union([Type.Array(Str), Type.Null()], {
+                description: "Arguments of the Host's sign-in command; null when sign-in happens inside the Host.",
+            }),
+            hint: Str,
+        }),
+        quota: Type.Boolean(),
+        usage: Type.Boolean(),
+        quotaSetup: Type.Boolean({ description: 'Quota needs `sideby quota setup <family>` once.' }),
+        shared: Type.Array(Type.Object({
+            path: Str,
+            mode: ShareModeSchema,
+            key: Type.Optional(Str),
+            mainPath: Type.Optional(Str),
+            credential: Type.Optional(Type.Boolean()),
+            noSymlink: Type.Optional(Type.Boolean()),
+            source: Type.Union([Type.Literal('family'), Type.Literal('config')]),
+            meaning: Type.String({
+                description: 'What the item looks like in each Account, in one fixed sentence.',
+            }),
+        })),
+    }),
+]);
 const PluginError = Type.Object({ where: Str, message: Str });
 const Finding = Type.Object({
     level: Level,
@@ -168,6 +199,9 @@ export const OUTPUT_SCHEMAS = {
         nextSteps: Type.Array(Str),
         alias: Type.Optional(Type.Object({ name: Str, added: Type.Boolean(), message: Type.Optional(Str) }, { description: 'The `--alias` short command; `added: false` means the Account exists without it.' })),
         shellInitFiles: Type.Optional(ShellInitFiles),
+        suggestion: Type.Optional(Type.Object({ name: Str, alias: Type.Optional(Str), aliasProblem: Type.Optional(Str) }, {
+            description: 'Only with `--next`: the picked name, the short command that follows the existing pattern, or why that short command was left out.',
+        })),
     }, { title: 'sideby new --json' }),
     alias: Type.Object({
         schemaVersion: Version,
@@ -195,6 +229,7 @@ export const OUTPUT_SCHEMAS = {
         })),
         errors: Type.Array(PluginError),
     }, { title: 'sideby plugins --json' }),
+    families: Type.Object({ schemaVersion: Version, families: Type.Array(FamilyDetail) }, { title: 'sideby families --json' }),
     'app-install': Type.Object({
         schemaVersion: Version,
         platform: AppPlatform,

package/dist/src/cli/main.js

@@ -8,14 +8,19 @@ const HELP = `sideby — run every AI coding account side by side
 Usage:
   sideby                              list accounts (same as \`sideby list\`)
   sideby run <account> [-- args]      start the host CLI for one account
-  sideby new <family> <name> [--api] [--alias <short>]
+  sideby new <family> <name>|--next [--api] [--alias <short>]
                                       create an account (families: claude, codex, grok, pi);
+                                      --next picks the next name and short command (cc008);
                                       --alias also adds a short command such as cc008
+  sideby families [family]            what each host's accounts share with the main account,
+                                      where they live and how they sign in
   sideby alias add <short> <account> [-- args]
                                       add a short command, optionally with host arguments
                                       (sideby alias add pi-kimi pi:main -- --model kimi-coding/k3)
   sideby alias rm <short>             remove a short command
   sideby login <account>              sign in to an account
+  sideby resume <family> [-- args]    run the host; a session resumed by id (claude --resume <id>,
+                                      codex resume <id>) starts in the account that holds it
   sideby next <family> [--dry-run] [--include-api] [-- args]
                                       recommend the account with the most quota left (claude, codex)
                                       and start it; --dry-run only recommends
@@ -35,11 +40,90 @@ Usage:
   sideby plugins                      list loaded plugins and load errors
 
 Options:
-  --json        machine-readable output (list, new, next, alias, doctor, quota, plugins, app)
-  -h, --help    show this help
+  --json        machine-readable output (list, new, next, alias, doctor, quota, families, plugins, app)
+  -h, --help    show this help; \`sideby <command> --help\` for new, alias, login, doctor, families
   -v, --version show the version
 
-An <account> is <family>:<name> (claude:work) or just <name> when it is unique.`;
+An <account> is <family>:<name> (claude:work) or just <name> when it is unique.
+
+For AI agents:
+  Add --json and read the result; JSON Schemas ship in the package under schemas/.
+  Install the skill: npx skills add Adonis0123/sideby -g
+  Setup steps and the full contract: https://github.com/Adonis0123/sideby/blob/main/llms.txt
+  Run everything else yourself, but hand the user these as one line each: \`sideby login <account>\`
+  (browser sign-in), filling in proxy.env, and \`sideby run\` or \`sideby next\` (interactive sessions).
+  Exit 10 means a change was shown: ask the user, then run it again with --yes.`;
+/** `sideby <command> --help` for the commands agents use to set up and repair accounts (spec §3.16). */
+const COMMAND_HELP = {
+    new: `sideby new <family> <name> [--api] [--alias <short>] [--json]
+sideby new <family> --next [--api] [--alias <short>] [--json]
+
+Create an account directory (~/.claude-<name>, ~/.codex-<name>, ~/.grok-<name>, ~/.pi-<name>/agent) and link or
+copy the main account's shared items into it. \`sideby families <family>\` lists them.
+
+  --next          pick the name: the next number after the highest numbered account (001…007 → 008), else work;
+                  without --alias, also add a short command that follows your existing ones (cc007 → cc008)
+  --api           API account: also writes an empty proxy.env template (mode 600) for the user to fill in
+  --alias <short> add a short command for it to the config (it becomes a shell function)
+
+Examples:
+  sideby new claude --next --json        # ~/.claude-008 plus cc008 when cc001…cc007 exist
+  sideby new claude work                 # ~/.claude-work
+  sideby new claude deepseek --api       # then the user fills in ~/.claude-deepseek/proxy.env
+
+Writes: the account directory; the config \`aliases\` and every \`shellInitFile\` when a short command is added.
+Next: the user signs in with \`sideby login <account>\` (subscription) or fills in proxy.env (API).
+Exit: 0 done; 1 invalid name or alias, directory exists, or partly failed; 2 malformed command line.`,
+    alias: `sideby alias add <short> <account> [-- host args] [--json]
+sideby alias rm <short> [--json]
+
+A short command starts one account: \`sideby run <short>\`, or just \`<short>\` once your shell loads
+\`sideby shell-init\`. Host arguments after -- are added only when it starts through the short command; it is
+the same account (same sign-in, same sessions), so do not create an account per model.
+
+Examples:
+  sideby alias add cc008 claude:008
+  sideby alias add pi-kimi pi:main -- --model kimi-coding/k3
+  sideby alias rm cc008
+
+Writes: the config \`aliases\` and every \`shellInitFile\`. New shell functions work in a new shell, or after
+eval "$(sideby shell-init zsh)" (put that line in ~/.zshrc once).
+Exit: 0 done (also when it already exists or is absent); 1 invalid, reserved or taken; 2 malformed.`,
+    login: `sideby login <account>
+
+Run the host's own sign-in for one account: claude auth login, codex login, grok login. For pi it starts pi;
+then type /login. It opens a browser and needs the person who owns the account, so an agent hands this
+line to the user instead of running it (in Claude Code: ! sideby login claude:008).
+
+sideby never reads, copies or stores the credentials the host writes.
+Exit: the host's exit code.`,
+    doctor: `sideby doctor [account|family] [--fix] [--force] [--json]
+
+Check every account's shared items against the main account, credential file modes (600), backup leftovers,
+and whether the installed sideby skill matches this version.
+
+  --fix     repair what is safe: add missing links, refresh copies, chmod 600, sync MCP servers
+  --force   with --fix, also let a synced MCP list (json-key) drop entries the account has
+
+--fix never replaces a real file with a link and never changes where an existing link points; those are
+reported with the command to run.
+
+Examples:
+  sideby doctor --json
+  sideby doctor claude:008 --fix
+Exit: 0 when nothing fails (warnings allowed); 1 when a check fails.`,
+    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
+in, whether quota and usage can be read, and every shared item with what it looks like in each account
+(a link to the main account's, a copy, or the account's own file). Everything else in an account directory
+(sign-in, sessions, history) belongs to that account.
+
+Examples:
+  sideby families
+  sideby families claude --json
+Exit: 0; 1 unknown family; 2 malformed command line.`,
+};
 function nodeTooOld() {
     const [maj = 0, min = 0] = process.versions.node.split('.').map(Number);
     return maj < MIN_NODE[0] || (maj === MIN_NODE[0] && min < MIN_NODE[1]);
@@ -47,9 +131,10 @@ function nodeTooOld() {
 const COMMANDS = {
     list: { flags: ['json'] },
     run: { flags: [] },
+    resume: { flags: [] },
     login: { flags: [] },
     next: { flags: ['dry-run', 'include-api', 'json'] },
-    new: { flags: ['api', 'json'], valued: ['alias'] },
+    new: { flags: ['api', 'json', 'next'], valued: ['alias'] },
     alias: { flags: ['json'] },
     doctor: { flags: ['fix', 'force', 'json'] },
     quota: { flags: ['json', 'yes'] },
@@ -57,6 +142,7 @@ const COMMANDS = {
     app: { flags: ['json'], valued: ['url'] },
     'shell-init': { flags: ['write'] },
     plugins: { flags: ['json'] },
+    families: { flags: ['json'] },
 };
 export async function main(argv) {
     const [first, ...rest] = argv;
@@ -70,7 +156,7 @@ export async function main(argv) {
         return 0;
     }
     if (first === '-h' || first === '--help' || first === 'help') {
-        console.log(HELP);
+        console.log((rest[0] !== undefined && first === 'help' && COMMAND_HELP[rest[0]]) || HELP);
         return 0;
     }
     if (nodeTooOld()) {
@@ -88,9 +174,9 @@ export async function main(argv) {
     try {
         if (!spec)
             throw new UsageError(`unknown command "${cmd}"; run \`sideby --help\``);
-        // `run` passes everything after the account through to the host, with or without `--`.
+        // `run` and `resume` pass everything after the account or family through to the host, with or without `--`.
         let parsed;
-        if (cmd === 'run') {
+        if (cmd === 'run' || cmd === 'resume') {
             const sep = args.indexOf('--');
             const head = sep === -1 ? args : args.slice(0, sep);
             const [ref, ...more] = head;
@@ -116,7 +202,7 @@ export async function main(argv) {
             }
         }
         if (parsed.flags.has('help')) {
-            console.log(HELP);
+            console.log(COMMAND_HELP[cmd] ?? HELP);
             return 0;
         }
         const cmds = await import('./commands.js');
@@ -127,6 +213,8 @@ export async function main(argv) {
                 return await cmds.cmdRun(parsed, io, 'run');
             case 'login':
                 return await cmds.cmdRun(parsed, io, 'login');
+            case 'resume':
+                return await cmds.cmdResume(parsed, io);
             case 'next':
                 return await cmds.cmdNext(parsed, io);
             case 'new':
@@ -145,6 +233,8 @@ export async function main(argv) {
                 return await cmds.cmdShellInit(parsed, io);
             case 'plugins':
                 return await cmds.cmdPlugins(parsed, io);
+            case 'families':
+                return await cmds.cmdFamilies(parsed, io);
         }
         return 2;
     }

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

@@ -16,3 +16,5 @@ export declare class AccountRefError extends UserError {
 }
 /** Resolves `<family>:<name>`, an alias from the config, or a name unique across Families. */
 export declare function resolveRef(ref: string, accounts: readonly Account[], aliases?: Readonly<Record<string, string>>): Account;
+/** Alias names per Account ref, sorted. An alias whose target matches no Account is left out. */
+export declare function aliasesByAccount(aliases: Readonly<Record<string, string>> | undefined, accounts: readonly Account[]): Map<string, string[]>;

package/dist/src/core/accounts.js

@@ -114,3 +114,18 @@ export function resolveRef(ref, accounts, aliases = {}) {
         throw new AccountRefError(`no account named ${ref}; run \`sideby list\` to see accounts`);
     throw new AccountRefError(`${ref} is ambiguous; use one of: ${hits.map((a) => a.ref).join(', ')}`);
 }
+/** Alias names per Account ref, sorted. An alias whose target matches no Account is left out. */
+export function aliasesByAccount(aliases, accounts) {
+    const out = new Map();
+    for (const [alias, target] of Object.entries(aliases ?? {})) {
+        let ref;
+        try {
+            ref = resolveRef(target, accounts).ref;
+        }
+        catch {
+            continue;
+        }
+        out.set(ref, [...(out.get(ref) ?? []), alias].sort());
+    }
+    return out;
+}

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

@@ -34,6 +34,7 @@ export declare const ConfigSchema: Type.TObject<{
         noSymlink: Type.TOptional<Type.TBoolean>;
         credential: Type.TOptional<Type.TBoolean>;
     }>>>>;
+    resumeRouting: Type.TOptional<Type.TBoolean>;
     shellInitFile: Type.TOptional<Type.TObject<{
         zsh: Type.TOptional<Type.TString>;
         bash: Type.TOptional<Type.TString>;

package/dist/src/core/config.js

@@ -57,6 +57,9 @@ export const ConfigSchema = Type.Object({
         description: 'Per-Plugin settings; `enabled: false` turns a Plugin off.',
     })),
     extraSharedItems: Type.Optional(Type.Record(Type.String(), Type.Array(SharedItemSchema))),
+    resumeRouting: Type.Optional(Type.Boolean({
+        description: 'Make `sideby shell-init` also define Host-named functions (`claude`, `codex`, `grok`) that resume a session by id in the Account that holds it. Off by default.',
+    })),
     shellInitFile: Type.Optional(Type.Object({
         zsh: Type.Optional(Type.String({ minLength: 1 })),
         bash: Type.Optional(Type.String({ minLength: 1 })),

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

@@ -9,6 +9,8 @@ export interface PreparedLaunch {
     /** Printed before launching when sign-in happens inside the Host. */
     notice?: string;
 }
+/** What `runHost` needs: a prepared Account launch, or the Host run unchanged (`sideby resume`). */
+export type HostLaunch = Pick<PreparedLaunch, 'family' | 'bin' | 'args' | 'env'>;
 /** Finds an executable on PATH; returns null when the Host is not installed. */
 export declare function which(bin: string, env: Env): Promise<string | null>;
 /**
@@ -32,4 +34,4 @@ export declare function prepareLaunch(opts: {
  * process group, so the Host receives them directly) and forwards SIGTERM/SIGHUP once. SIGTSTP keeps its
  * default action so Ctrl-Z suspends sideby together with the Host and `fg` resumes both.
  */
-export declare function runHost(p: PreparedLaunch): Promise<number>;
+export declare function runHost(p: HostLaunch): Promise<number>;

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

@@ -0,0 +1,9 @@
+import type { Account, FamilyDef } from '../types.ts';
+export interface ResumeRoute {
+    /** The session the Host arguments resume by id; absent when they resume none. */
+    sessionId?: string;
+    /** The Account that last wrote that session; absent when no Account holds it. */
+    account?: Account;
+}
+/** Asks every Account of the Family for the session and picks the one that wrote it last. */
+export declare function findResumeRoute(family: FamilyDef, accounts: readonly Account[], args: readonly string[]): Promise<ResumeRoute>;

package/dist/src/core/resume.js

@@ -0,0 +1,15 @@
+/** Asks every Account of the Family for the session and picks the one that wrote it last. */
+export async function findResumeRoute(family, accounts, args) {
+    const sessionId = family.resumedSession?.(args);
+    if (!sessionId || !family.sessionWrittenAt)
+        return {};
+    const own = accounts.filter((a) => a.family === family.id);
+    const written = await Promise.all(own.map((a) => family.sessionWrittenAt(a, sessionId).catch(() => undefined)));
+    let best;
+    own.forEach((account, i) => {
+        const at = written[i];
+        if (at !== undefined && (!best || at > best.at))
+            best = { account, at };
+    });
+    return best ? { sessionId, account: best.account } : { sessionId };
+}

package/dist/src/core/share-meaning.d.ts

@@ -0,0 +1,6 @@
+import type { SharedItemDef } from '../types.ts';
+/**
+ * What one Shared Item looks like in an Account, in one fixed English sentence for `sideby families` (spec §3.16).
+ * Agents quote it to users, so it follows the Share Mode rules of spec §3.3 and never promises more.
+ */
+export declare function shareMeaning(item: SharedItemDef): string;

package/dist/src/core/share-meaning.js

@@ -0,0 +1,32 @@
+/**
+ * What one Shared Item looks like in an Account, in one fixed English sentence for `sideby families` (spec §3.16).
+ * Agents quote it to users, so it follows the Share Mode rules of spec §3.3 and never promises more.
+ */
+export function shareMeaning(item) {
+    const main = item.mainPath ? `~/${item.mainPath}` : "the Main Account's";
+    const base = (() => {
+        switch (item.mode) {
+            case 'link':
+                return "A link to the Main Account's: one copy for every Account.";
+            case 'copy':
+                return "A copy of the Main Account's, kept equal by `doctor --fix`; the Host does not accept a link here.";
+            case 'link-or-copy':
+                return "A link to the Main Account's, or a copy kept equal by `doctor --fix`.";
+            case 'link-or-local':
+                return "A link to the Main Account's, unless the Account keeps its own file.";
+            case 'local':
+                return "The Account's own file, first copied from the Main Account and never synced.";
+            case 'local-if-api':
+                return item.noSymlink
+                    ? "Subscription Accounts: a copy of the Main Account's, kept equal by `doctor --fix`. API Accounts: their own file."
+                    : "Subscription Accounts: a link to the Main Account's, or a copy kept equal. API Accounts: their own file.";
+            case 'info':
+                return item.credential
+                    ? "The Account's own sign-in: never shared and never read; sideby checks only that it is mode 600."
+                    : "The Account's own; sideby only reports it.";
+            case 'json-key':
+                return `The Account's own file; only its \`${item.key}\` entry is kept equal to ${main}${item.credential ? ', and sideby reads no other part of it' : ''}.`;
+        }
+    })();
+    return item.noSymlink && item.mode !== 'copy' ? `${base} Never a link: the Host refuses one.` : base;
+}

package/dist/src/core/shell-init.d.ts

@@ -3,11 +3,17 @@ export declare const SHELLS: readonly ['zsh', 'bash'];
 export type Shell = (typeof SHELLS)[number];
 /** First line of every generated script; an existing file without it is never overwritten. */
 export declare const SHELL_INIT_HEADER = "# sideby shell-init: one function per account, plus aliases from the sideby config";
+/** A Family whose bare Host command `shell-init` routes through `sideby resume` (config `resumeRouting`). */
+export interface ResumeRouteFunction {
+    family: string;
+    bin: string;
+    selectVar: string;
+}
 /**
  * The script for one shell, ending in a newline: exactly what `sideby shell-init <shell>` prints. zsh and bash
  * read the same function syntax, so the shell only names the file it goes to.
  */
-export declare function shellInitScript(accounts: readonly Account[], aliases: Readonly<Record<string, unknown>> | undefined): string;
+export declare function shellInitScript(accounts: readonly Account[], aliases: Readonly<Record<string, unknown>> | undefined, routes?: readonly ResumeRouteFunction[]): string;
 export interface ShellInitWrite {
     shell: Shell;
     /** The configured path, as written in the config (`~/…` kept). */

package/dist/src/core/shell-init.js

@@ -2,18 +2,35 @@
 // in sync with them whenever it adds an Account or an alias.
 import { mkdir, readFile } from 'node:fs/promises';
 import { dirname } from 'node:path';
-import { aliasProblem } from './config.js';
+import { ALIAS_NAME, aliasProblem, RESERVED_ALIASES } from './config.js';
 import { realpathOrNull, statOrNull, writeFileAtomic } from './fs-safe.js';
 import { expandUserPath } from './paths.js';
 export const SHELLS = ['zsh', 'bash'];
 /** First line of every generated script; an existing file without it is never overwritten. */
 export const SHELL_INIT_HEADER = '# sideby shell-init: one function per account, plus aliases from the sideby config';
 const quote = (s) => `'${s.replace(/'/g, `'\\''`)}'`;
+const SHELL_VAR = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** A shell `case` pattern for a session id: 36 characters with dashes where a UUID has them. */
+const SESSION_ID_GLOB = '????????-????-????-????-????????????';
+/**
+ * The Host-named function for one routed Family, or null when its names are not safe in a shell (spec §3.15). It
+ * starts sideby only when an argument looks like a session id, so a plain Host command costs nothing extra.
+ * `function name {` because zsh expands an alias of the same name in `name() {`.
+ */
+function resumeRouteFunction(r) {
+    if (!ALIAS_NAME.test(r.bin) || RESERVED_ALIASES.has(r.bin) || !SHELL_VAR.test(r.selectVar))
+        return null;
+    const id = SESSION_ID_GLOB;
+    return [
+        `function ${r.bin} { local a; if [ -z "\${${r.selectVar}-}" ]; then for a in "$@"; do case $a in ${id}|--resume=${id})`,
+        ` command sideby resume ${quote(r.family)} -- "$@"; return;; esac; done; fi; command ${r.bin} "$@"; }`,
+    ].join('');
+}
 /**
  * The script for one shell, ending in a newline: exactly what `sideby shell-init <shell>` prints. zsh and bash
  * read the same function syntax, so the shell only names the file it goes to.
  */
-export function shellInitScript(accounts, aliases) {
+export function shellInitScript(accounts, aliases, routes = []) {
     const lines = [SHELL_INIT_HEADER];
     for (const acc of accounts)
         lines.push(`sideby-${acc.family}-${acc.name}() { command sideby run ${quote(acc.ref)} -- "$@"; }`);
@@ -21,6 +38,12 @@ export function shellInitScript(accounts, aliases) {
     for (const alias of Object.keys(aliases ?? {}))
         if (!aliasProblem(alias))
             lines.push(`${alias}() { command sideby run ${quote(alias)} -- "$@"; }`);
+    // An Alias with the Host's name wins: it already starts a chosen Account.
+    for (const r of routes) {
+        const fn = aliases && Object.hasOwn(aliases, r.bin) ? null : resumeRouteFunction(r);
+        if (fn)
+            lines.push(fn);
+    }
     return `${lines.join('\n')}\n`;
 }
 /**

package/dist/src/families/claude/index.js

@@ -5,6 +5,7 @@ import { identityFromJsonFile, identityOf } from '../../core/identity.js';
 import { readSecretFile } from '../../core/secret-file.js';
 import { claudeStatusline } from '../../quota/claude-statusline.js';
 import { BUILTIN_LOGOS } from '../logos.js';
+import { groupedEntryWrittenAt, resumeFlagSession } from '../shared/sessions.js';
 import { CLAUDE_LAYOUT } from './layout.js';
 import { readClaudeQuota } from './quota.js';
 import { readClaudeUsage } from './usage.js';
@@ -115,6 +116,8 @@ export const claudeFamily = {
     readQuota: readClaudeQuota,
     readUsage: readClaudeUsage,
     quotaSetup: claudeStatusline,
+    resumedSession: resumeFlagSession,
+    sessionWrittenAt: (account, id) => groupedEntryWrittenAt(join(account.dir, 'projects'), `${id}.jsonl`, 'file'),
 };
 export const claudePlugin = {
     name: 'claude',

package/dist/src/families/codex/index.js

@@ -2,6 +2,7 @@ import { readFile, stat } from 'node:fs/promises';
 import { join } from 'node:path';
 import { identityFromJsonFile, identityOf, jwtEmail } from '../../core/identity.js';
 import { BUILTIN_LOGOS } from '../logos.js';
+import { nestedFileWrittenAt, resumeSubcommandSession } from '../shared/sessions.js';
 import { topLevelTomlString } from '../shared/toml.js';
 import { readCodexQuota, readCodexUsage } from './rollout.js';
 const FILE_STORE_KEY = 'cli_auth_credentials_store';
@@ -58,6 +59,8 @@ export const codexFamily = {
     identity: codexIdentity,
     readQuota: (account) => readCodexQuota(account.dir),
     readUsage: (account, ctx) => readCodexUsage(account.dir, ctx.now),
+    resumedSession: resumeSubcommandSession,
+    sessionWrittenAt: (account, id) => nestedFileWrittenAt(join(account.dir, 'sessions'), `-${id}.jsonl`),
 };
 export const codexPlugin = {
     name: 'codex',

package/dist/src/families/grok/index.js

@@ -2,6 +2,7 @@ import { lstat, readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { identityFromJsonFile, identityOf } from '../../core/identity.js';
 import { BUILTIN_LOGOS } from '../logos.js';
+import { groupedEntryWrittenAt, resumeFlagSession } from '../shared/sessions.js';
 import { topLevelTomlString } from '../shared/toml.js';
 // Grok's sandbox rejects these paths when they are symlinks; doctor quotes the Host's own words.
 const HOOKS_DIR_MESSAGE = 'Grok hooks directory has wrong type (expected real directory)';
@@ -69,6 +70,9 @@ export const grokFamily = {
     },
     model: readModel,
     identity: grokIdentity,
+    resumedSession: resumeFlagSession,
+    // One directory per session, grouped by working directory: sessions/<encoded cwd>/<id>/.
+    sessionWrittenAt: (account, id) => groupedEntryWrittenAt(join(account.dir, 'sessions'), id, 'dir'),
 };
 export const grokPlugin = {
     name: 'grok',

package/dist/src/families/shared/sessions.d.ts

@@ -0,0 +1,9 @@
+export declare const isSessionId: (s: string | undefined) => s is string;
+/** The id after `--resume <id>`, `--resume=<id>` or `-r <id>`; Claude Code and Grok Build share this form. */
+export declare function resumeFlagSession(args: readonly string[]): string | undefined;
+/** The first UUID after the `resume` subcommand (`codex resume [options] <id>`). */
+export declare function resumeSubcommandSession(args: readonly string[]): string | undefined;
+/** `<dir>/*` + `/<entry>`: one level of grouping directories (Claude projects, Grok working directories). */
+export declare function groupedEntryWrittenAt(dir: string, entry: string, type: 'file' | 'dir'): Promise<number | undefined>;
+/** A file anywhere under `dir` whose name ends with `suffix` (Codex `sessions/YYYY/MM/DD/rollout-…-<id>.jsonl`). */
+export declare function nestedFileWrittenAt(dir: string, suffix: string): Promise<number | undefined>;