sideby 0.3.0 → 0.4.0

package/README.md

@@ -1,10 +1,10 @@
 <p align="center">
-  <img alt="sideby: one shared config, every account in its own terminal" src="https://raw.githubusercontent.com/Adonis0123/sideby/main/docs/assets/banner.jpg" width="880">
+  <img alt="sideby: work, personal and API-key accounts, one terminal each, one shared config" src="https://raw.githubusercontent.com/Adonis0123/sideby/main/docs/assets/banner.jpg" width="880">
 </p>
 
 <p align="center">
-  <b>Run every AI coding account side by side.</b><br>
-  Claude Code, Codex, Grok Build and pi: one directory per account, one shared set of skills, hooks and rules, one panel for every quota.
+  <b>Run work, personal and API-key accounts at the same time, without their configs drifting apart.</b><br>
+  Each account is its own directory and its own terminal. Skills, hooks and settings stay linked to your main account. Claude Code, Codex, Grok Build and pi.
 </p>
 
 <p align="center">
@@ -16,13 +16,17 @@
 
 <p align="center">English | <a href="README.zh-CN.md">中文</a></p>
 
-## Why
+## Why not just an alias?
 
-You have a work subscription, a personal one and maybe an API key. Switching tools rewrite the Host's global config, so only one account is live at a time, and your skills and hooks slowly drift apart between accounts.
+`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)
 
-- **Side by side, not switching.** Each account lives in its own directory, and sideby starts the official CLI with that directory selected. Run three accounts in three terminals; your shell is never changed.
-- **One copy of skills, hooks and rules.** Your Main Account (for example `~/.claude`) is the source. Other accounts link or copy its Shared Items ([what is shared](docs/guide/usage.md#what-each-account-shares)), and `sideby doctor --fix` repairs drift without touching real files or credentials.
-- **Every quota on one screen.** 5-hour and 7-day quota, reset times and 7-day token usage for every account. Out of room? `sideby next` starts the account with the most left. All from local files: no network calls, no token reads.
+| | 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
 
@@ -51,7 +55,7 @@ The agent checks Node and your Host CLIs, installs sideby and the skill, creates
 
 ## What it looks like
 
-<img alt="sideby in a terminal: list accounts, check quota, pick the next account, find and fix drift" src="https://raw.githubusercontent.com/Adonis0123/sideby/main/docs/assets/demo.gif" width="1320">
+<img alt="Two terminals: the personal account and the work account running at the same time, then the local quota panel" src="https://raw.githubusercontent.com/Adonis0123/sideby/main/docs/assets/demo.gif" width="1280">
 
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Adonis0123/sideby/main/docs/assets/panel-dark.png">
@@ -66,7 +70,9 @@ The agent checks Node and your Host CLIs, installs sideby and the skill, creates
 | Add an API key account (DeepSeek, a gateway, …) | `sideby new claude deepseek --api` | [API accounts](docs/guide/usage.md#api-accounts) |
 | Find and fix config drift between accounts | `sideby doctor --fix` | [Doctor](docs/guide/usage.md#doctor) |
 | See Claude quota (Codex needs no setup) | `sideby quota setup claude --yes` | [Claude quota](docs/guide/usage.md#claude-quota) |
+| Find the cheapest auto-compact size from your own sessions, and use it in one click | `sideby tune` (or the panel's Context tuning tab) | [Context tuning](docs/guide/usage.md#context-tuning) |
 | Move on when an account hits its limit | `sideby next claude` | [Handoff](docs/guide/usage.md#when-an-account-hits-its-limit) |
+| Let a running task move to the next account by itself when quota runs low (off by default; see the risk) | `sideby handoff enable` (or the panel) | [Auto Handoff](docs/guide/usage.md#auto-handoff) |
 | Short commands such as `ccw` | `sideby alias add ccw claude:work` | [Shell functions](docs/guide/configuration.md#shell-functions) |
 | Reopen a session from Orca and the like in the account that holds it | `"resumeRouting": true` in config | [Resuming from other tools](docs/guide/configuration.md#resuming-from-other-tools) |
 | Open the panel from the Dock or app menu | `sideby app install` | [Desktop app](docs/guide/panel.md#desktop-app) |
@@ -84,14 +90,24 @@ The agent checks Node and your Host CLIs, installs sideby and the skill, creates
 
 sideby starts the official binary on your `PATH` and never patches it. Tested versions and per-Host notes are in the [guide](docs/guide/usage.md#host-notes).
 
+## Platforms
+
+macOS and Linux. CI runs the suite on `ubuntu-latest` and `macos-latest`, Node 22 and 24. **Windows is untested.** `sideby app` only installs a launcher on macOS and Linux. Linked items are symlinks, `sideby shell-init` prints bash and zsh functions, and the Claude quota wrapper runs `/bin/sh`.
+
+## Roadmap
+
+**Gemini CLI.** Gemini can point at another config directory with `GEMINI_CONFIG_DIR`. Older docs use `GEMINI_CLI_HOME`; current builds treat that name as deprecated, and exit on startup if it is set together with an exact directory override. A sideby family still needs a tested Gemini version, a login check that does not read tokens, and a list of which files to link or copy. That is more than a small patch, so it is not in this version.
+
 ## Safe by design
 
-- It never edits a Host's global config to switch accounts, and never rotates accounts by itself.
+- It never edits a Host's global config to switch accounts. It moves a task to another account only when you turn on Auto Handoff, and never proxies requests or pools logins.
 - It never reads, prints or sends a credential value. Nothing leaves your machine: sideby calls no remote service.
 - `doctor --fix` never replaces a real file and never changes where a link points.
 
 Details and the terms-of-service question are in the [FAQ](docs/guide/faq.md).
 
+Usage questions and ideas go in [Discussions](https://github.com/Adonis0123/sideby/discussions).
+
 ## Docs
 
 - [Using sideby](docs/guide/usage.md): accounts, API accounts, Doctor, quota, Handoff, Host notes
@@ -100,6 +116,7 @@ Details and the terms-of-service question are in the [FAQ](docs/guide/faq.md).
 - [Panel](docs/guide/panel.md): the panel, desktop 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)
 
 ## For AI agents
 

package/dist/build.json

@@ -1 +1 @@
-{"id":"20261008T112709-0a27b0"}
+{"id":"20261013T091101-030f9b"}

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

@@ -1,9 +1,12 @@
 import type { DoctorReport } from '../core/doctor.ts';
+import { type HandoffIo } from '../core/handoff-run.ts';
 import type { Finding } from '../types.ts';
 import { type ParsedArgs } from './args.ts';
 export interface Io {
     out(s: string): void;
     err(s: string): void;
+    /** The terminal Auto Handoff counts down on (spec §3.17); `process.stdin` when left out. */
+    stdin?: HandoffIo['stdin'];
 }
 export declare function serializeDoctor(r: DoctorReport): {
     status: "issues" | "ok";
@@ -34,13 +37,17 @@ export declare function cmdNew(a: ParsedArgs, io: Io): Promise<number>;
 export declare function cmdRun(a: ParsedArgs, io: Io, command: 'run' | 'login'): Promise<number>;
 /**
  * `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.
+ * session the arguments resume by id, a new session where a never-saved one started (ADR-0009), or the Host unchanged.
  */
 export declare function cmdResume(a: ParsedArgs, io: Io): Promise<number>;
 /** `sideby next <family>`: recommend the Account with the most room, then start it (spec §3.13). */
 export declare function cmdNext(a: ParsedArgs, io: Io): Promise<number>;
 export declare function cmdDoctor(a: ParsedArgs, io: Io): Promise<number>;
+/** `sideby tune [account|family]`: estimated Compaction Threshold per model (spec §3.18). */
+export declare function cmdTune(a: ParsedArgs, io: Io): Promise<number>;
 export declare function cmdQuota(a: ParsedArgs, io: Io): Promise<number>;
+/** `sideby handoff ready|setup|teardown` (spec §3.17). */
+export declare function cmdHandoff(a: ParsedArgs, io: Io): Promise<number>;
 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>;

package/dist/src/cli/commands.js

@@ -2,6 +2,9 @@ import { fileURLToPath } from 'node:url';
 import { aliasesByAccount } from '../core/accounts.js';
 import { aliasRefs } from '../core/config.js';
 import { UserError } from '../core/errors.js';
+import { requestHandoff } from '../core/handoff-chain.js';
+import { explain, readyDecision, runWithHandoff } from '../core/handoff-run.js';
+import { configureHandoff, handoffHint, handoffStatus } from '../core/handoff-status.js';
 import { runHost } from '../core/launch.js';
 import { resolvePaths, tildify } from '../core/paths.js';
 import { USAGE_DAYS } from '../core/quota-levels.js';
@@ -9,7 +12,26 @@ import { SHELLS } from '../core/shell-init.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';
+import { c, clock, compactNumber, quotaText, table, tuningLines, usageText } from './format.js';
+/** Runs the Account with Auto Handoff when it applies (spec §3.17), else the Host as usual. */
+async function runAccount(rt, ref, args, io) {
+    const handed = await runWithHandoff(rt, ref, args, {
+        err: (l) => io.err(c.dim(l)),
+        stdin: io.stdin ?? process.stdin,
+    });
+    if (handed !== null)
+        return handed;
+    const prepared = await rt.prepareLaunch(ref, args, 'run');
+    if (prepared.notice)
+        io.err(c.cyan(prepared.notice));
+    const code = await runHost(prepared);
+    if ((io.stdin ?? process.stdin).isTTY) {
+        const hint = await handoffHint(rt, ref);
+        if (hint)
+            io.err(c.dim(`sideby: ${hint}`));
+    }
+    return code;
+}
 const json = (io, data) => io.out(JSON.stringify({ schemaVersion: 1, ...data }, null, 2));
 function stripFix(f) {
     const { fix: _fix, ...rest } = f;
@@ -149,6 +171,8 @@ export async function cmdRun(a, io, command) {
     if (command === 'login' && (extra.length || a.rest.length))
         throw new UsageError('login takes no extra arguments');
     const rt = await createRuntime();
+    if (command === 'run')
+        return runAccount(rt, ref, [...extra, ...a.rest], io);
     const prepared = await rt.prepareLaunch(ref, [...extra, ...a.rest], command);
     if (prepared.notice)
         io.err(c.cyan(prepared.notice));
@@ -156,7 +180,7 @@ export async function cmdRun(a, io, command) {
 }
 /**
  * `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.
+ * session the arguments resume by id, a new session where a never-saved one started (ADR-0009), or the Host unchanged.
  */
 export async function cmdResume(a, io) {
     const [family, ...extra] = a.positionals;
@@ -164,7 +188,9 @@ export async function cmdResume(a, io) {
         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)
+    if (route.newSession)
+        io.err(c.dim(`sideby: session ${route.sessionId} was never saved; starting a new session in ${route.account.ref}`));
+    else if (route.account)
         io.err(c.dim(`sideby: session ${route.sessionId} is in ${route.account.ref}; starting it there`));
     return runHost(route.launch);
 }
@@ -236,10 +262,9 @@ export async function cmdNext(a, io) {
     }
     // The old session stays in the old Account (spec §3.13); a short note carries the context over.
     io.out(c.dim('Tip: ask your old session for a short handoff note and paste it into the new one.'));
-    const prepared = await rt.prepareLaunch(plan.pick, a.rest, 'run');
-    if (prepared.notice)
-        io.err(c.cyan(prepared.notice));
-    return runHost(prepared);
+    if (!rt.handoffSettings().auto)
+        io.out(c.dim('Sessions can also hand over by themselves when quota runs low: see `sideby handoff status`.'));
+    return runAccount(rt, plan.pick, a.rest, io);
 }
 export async function cmdDoctor(a, io) {
     const rt = await createRuntime();
@@ -278,6 +303,140 @@ export async function cmdDoctor(a, io) {
         io.out(c.cyan(`\n${fixable} issue(s) can be fixed with \`sideby doctor --fix\`.`));
     return report.status === 'ok' ? 0 : 1;
 }
+/** The words a person reads before agreeing to a change: where, from what to what, and who else it reaches. */
+function tuneChangeLines(plan, home) {
+    const from = plan.current === null ? 'the default' : compactNumber(plan.current);
+    const lines = [
+        `  File:    ${tilde(plan.file, home)}${plan.creates ? ' (will be created)' : ''}`,
+        `  Change:  auto-compact size ${from} -> ${plan.next === null ? 'the default' : compactNumber(plan.next)}`,
+    ];
+    if (plan.affected.length > 1)
+        lines.push(`  Careful: this file is shared, so it also changes ${plan.affected.slice(1).join(', ')}`);
+    lines.push('  Sessions already running keep the old value; new ones use the new one. You can undo it.');
+    return lines;
+}
+/** `160000`, `160k` or `1m` as a number of tokens, `default` as null (go back to the default); NaN when it is none of those. */
+function parseTokens(text) {
+    if (text.trim().toLowerCase() === 'default')
+        return null;
+    const m = /^(\d+(?:\.\d+)?)([kKmM]?)$/.exec(text.trim());
+    if (!m)
+        return Number.NaN;
+    return Math.round(Number(m[1]) * (m[2] === '' ? 1 : m[2]?.toLowerCase() === 'k' ? 1_000 : 1_000_000));
+}
+/** `sideby tune apply <account> [tokens]` and `sideby tune undo <account>` (spec §3.18, ADR-0012). */
+async function cmdTuneChange(a, io, action) {
+    const [, ref, tokens] = a.positionals;
+    if (!ref || a.positionals.length > (action === 'apply' ? 3 : 2))
+        throw new UsageError(`usage: sideby tune ${action} <account>${action === 'apply' ? ' [tokens]' : ''} [--yes] [--json]`);
+    const wantJson = a.flags.has('json');
+    const yes = a.flags.has('yes');
+    const rt = await createRuntime();
+    const account = await rt.resolve(ref);
+    const home = rt.paths.home;
+    const out = (data) => json(io, { account: account.ref, action, ...data });
+    if (action === 'undo') {
+        const info = await rt.tuneUndoInfo(account);
+        if (!info) {
+            if (wantJson)
+                out({ applied: false, message: 'There is nothing from sideby to undo for this account.' });
+            else
+                io.out('There is nothing from sideby to undo for this account.');
+            return 1;
+        }
+        if (!yes) {
+            if (wantJson)
+                out({ applied: false, message: 'Run again with --yes to undo.' });
+            else
+                io.out(`Undo: auto-compact size ${info.applied === null ? 'the default' : compactNumber(info.applied)} -> ${info.previous === null ? 'the default' : compactNumber(info.previous)} in ${tilde(info.file, home)}\nRun again with --yes to undo.`);
+            return 10;
+        }
+        const r = await rt.tuneUndo(account);
+        if (wantJson)
+            out({ applied: r.ok, message: r.message });
+        else
+            io.out(r.message);
+        return r.ok ? 0 : 1;
+    }
+    let value = tokens === undefined ? undefined : parseTokens(tokens);
+    if (value === undefined) {
+        const pick = (await rt.tuneGroups(account)).groups[0]?.pick ?? null;
+        if (!pick)
+            throw new UserError(`no suggested size for ${account.ref} to use: give one, for example \`sideby tune apply ${account.ref} 160000\`, or run \`sideby tune ${account.ref}\` to see why`, { code: 'no-suggestion' });
+        value = pick.threshold;
+    }
+    const plan = await rt.tuneApplyPlan(account, value);
+    const planJson = { ...plan, file: tilde(plan.file, home) };
+    if (plan.status === 'blocked') {
+        if (wantJson)
+            out({ applied: false, plan: planJson, message: plan.reason });
+        else
+            io.out(plan.reason ?? 'blocked');
+        return 1;
+    }
+    if (plan.status === 'unchanged') {
+        if (wantJson)
+            out({ applied: false, plan: planJson, message: 'It is already set to that value; nothing changed.' });
+        else
+            io.out('It is already set to that value; nothing changed.');
+        return 0;
+    }
+    if (!yes) {
+        if (wantJson)
+            out({ applied: false, plan: planJson, message: 'Run again with --yes to apply.' });
+        else
+            io.out([
+                `${plan.next === null ? 'Go back to the default' : `Use ${compactNumber(plan.next)}`} for ${account.ref}?`,
+                ...tuneChangeLines(plan, home),
+                'Run again with --yes to apply.',
+            ].join('\n'));
+        return 10;
+    }
+    const r = await rt.tuneApply(account, value);
+    if (wantJson)
+        out({ applied: r.ok, plan: { ...r.plan, file: tilde(r.plan.file, home) }, message: r.message });
+    else
+        io.out(r.message);
+    return r.ok ? 0 : 1;
+}
+/** `sideby tune [account|family]`: estimated Compaction Threshold per model (spec §3.18). */
+export async function cmdTune(a, io) {
+    if (a.positionals[0] === 'apply' || a.positionals[0] === 'undo')
+        return cmdTuneChange(a, io, a.positionals[0]);
+    if (a.positionals.length > 1 || a.flags.has('yes'))
+        throw new UsageError('usage: sideby tune [account|family] [--json]  (--yes belongs to `tune apply` and `tune undo`)');
+    const rt = await createRuntime();
+    const target = a.positionals[0];
+    const all = await rt.accounts();
+    let accounts = all;
+    if (target) {
+        const ofFamily = all.filter((x) => x.family === target);
+        if (ofFamily.length)
+            accounts = ofFamily;
+        else if ((await rt.familyInfo()).some((f) => f.id === target))
+            accounts = [];
+        else
+            accounts = [await rt.resolve(target)];
+    }
+    const rows = await Promise.all(accounts.map(async (x) => ({ ref: x.ref, family: x.family, tuning: await rt.tuning(x) })));
+    if (a.flags.has('json')) {
+        json(io, { accounts: rows });
+        return 0;
+    }
+    if (rows.length === 0) {
+        io.out(target
+            ? `No ${target} accounts yet. Run \`sideby new ${target} <name>\` to add one.`
+            : 'No accounts found yet. Run `sideby` for how to start.');
+        return 0;
+    }
+    for (const r of rows) {
+        io.out(c.bold(r.ref));
+        for (const line of tuningLines(r.tuning))
+            io.out(`  ${line}`);
+    }
+    io.out(c.dim(`\nEstimates from your last ${USAGE_DAYS} days of local sessions; sideby does not change any setting.`));
+    return 0;
+}
 export async function cmdQuota(a, io) {
     const sub = a.positionals[0];
     if (sub === 'setup' || sub === 'teardown')
@@ -318,7 +477,10 @@ async function cmdQuotaSetup(a, io, sub) {
     if (!familyId)
         throw new UsageError(`usage: sideby quota ${sub} <family>${sub === 'setup' ? ' [--yes]' : ''}`);
     const rt = await createRuntime();
-    const setup = rt.quotaSetup(familyId);
+    return runSetup(a, io, rt, 'quota', sub, familyId, rt.quotaSetup(familyId));
+}
+/** `sideby quota|handoff setup|teardown <family>`: show the change, apply it only with --yes (exit 10 before). */
+async function runSetup(a, io, rt, command, sub, familyId, setup) {
     if (sub === 'teardown') {
         const r = await setup.teardown();
         if (a.flags.has('json'))
@@ -340,7 +502,7 @@ async function cmdQuotaSetup(a, io, sub) {
             if (plan.status === 'ready') {
                 io.out(`\n${setup.summary}\nChange to ${tildify(plan.file, rt.paths.home)}:\n`);
                 io.out(plan.diff);
-                io.out(c.cyan(`\nApply it with \`sideby quota setup ${familyId} --yes\`; undo any time with \`sideby quota teardown ${familyId}\`.`));
+                io.out(c.cyan(`\nApply it with \`sideby ${command} setup ${familyId} --yes\`; undo any time with \`sideby ${command} teardown ${familyId}\`.`));
             }
         }
         // 10: the change is shown and waits for the user's yes (spec §3.9); agents ask before adding --yes.
@@ -353,6 +515,165 @@ async function cmdQuotaSetup(a, io, sub) {
         io.out(`${after.status === 'enabled' ? c.green('✓') : c.red('✗')} ${after.message}`);
     return after.status === 'enabled' ? 0 : 1;
 }
+/** `sideby handoff status` (spec §3.17): what Auto Handoff still needs, with the commands to run. */
+async function cmdHandoffStatus(a, io) {
+    const st = await handoffStatus(await createRuntime());
+    if (a.flags.has('json')) {
+        json(io, st);
+        return 0;
+    }
+    io.out(`Auto Handoff: ${st.auto ? c.green('on') : c.yellow('off')} (same family ${st.sameFamily ? 'on' : 'off'}; brief at ${st.prepareAt}%, hand over at ${st.threshold}%)`);
+    if (st.sideby.problem)
+        io.out(c.red(`sideby on PATH: ${st.sideby.problem}`));
+    if (st.families.length)
+        io.out(`\n${table(st.families.map((f) => [
+            c.bold(f.family),
+            f.starts.length ? f.starts.join(', ') : c.dim('takes over only'),
+            f.ready ? c.green('ready') : f.starts.length ? c.yellow('not yet') : c.dim('—'),
+            f.order.policy === 'order' ? f.order.order.join(' → ') : c.dim('by quota'),
+        ]), ['FAMILY', 'STARTS', 'STATE', 'ORDER'])}`);
+    for (const f of st.families) {
+        for (const p of f.problems)
+            io.out(c.yellow(`${f.family}: ${p}`));
+        for (const n of f.notes)
+            io.out(c.dim(`${f.family}: ${n}`));
+    }
+    if (st.nextSteps.length) {
+        io.out('\nNext:');
+        for (const [i, step] of st.nextSteps.entries())
+            io.out(`  ${i + 1}. ${step}`);
+    }
+    return 0;
+}
+function intFlag(a, name) {
+    const v = a.flags.get(name);
+    if (v === undefined)
+        return undefined;
+    const n = Number(v);
+    if (typeof v !== 'string' || !Number.isInteger(n) || n < 0)
+        throw new UsageError(`--${name} takes a whole number, for example --${name} 95`);
+    return n;
+}
+/** The `enable`/`disable` command line for `change`, to repeat with --yes. */
+function switchCommand(sub, change) {
+    const parts = [`sideby handoff ${sub}`];
+    if (change.sameFamily === true)
+        parts.push('--same-family');
+    if (change.sameFamily === false)
+        parts.push('--no-same-family');
+    for (const o of change.orders ?? [])
+        parts.push(`--order ${o.family}=${o.order.join(',')}`);
+    if (change.prepareAt !== undefined)
+        parts.push(`--prepare-at ${change.prepareAt}`);
+    if (change.threshold !== undefined)
+        parts.push(`--threshold ${change.threshold}`);
+    if (change.waitIfResetWithinMinutes !== undefined)
+        parts.push(`--wait-minutes ${change.waitIfResetWithinMinutes}`);
+    if (change.countdownSeconds !== undefined)
+        parts.push(`--countdown ${change.countdownSeconds}`);
+    return parts.join(' ');
+}
+/** `sideby handoff enable|disable` (spec §3.17): show the config change (exit 10), write it with --yes. */
+async function cmdHandoffSwitch(a, io, sub) {
+    const change = { auto: sub === 'enable' };
+    if (sub === 'enable') {
+        if (a.flags.has('same-family'))
+            change.sameFamily = true;
+        if (a.flags.has('no-same-family'))
+            change.sameFamily = false;
+        const order = a.flags.get('order');
+        if (typeof order === 'string') {
+            const eq = order.indexOf('=');
+            if (eq <= 0)
+                throw new UsageError('--order takes <family>=<account,account>, for example --order claude=codex001,cc002');
+            change.orders = [
+                {
+                    family: order.slice(0, eq),
+                    order: order
+                        .slice(eq + 1)
+                        .split(',')
+                        .map((x) => x.trim())
+                        .filter(Boolean),
+                },
+            ];
+        }
+        const nums = {
+            prepareAt: 'prepare-at',
+            threshold: 'threshold',
+            waitIfResetWithinMinutes: 'wait-minutes',
+            countdownSeconds: 'countdown',
+        };
+        for (const [key, flag] of Object.entries(nums)) {
+            const n = intFlag(a, flag);
+            if (n !== undefined)
+                change[key] = n;
+        }
+    }
+    const rt = await createRuntime();
+    const r = await configureHandoff(rt, change, { apply: a.flags.has('yes') });
+    const nextSteps = r.applied && sub === 'enable' ? (await handoffStatus(await createRuntime())).nextSteps : [];
+    if (a.flags.has('json')) {
+        json(io, { applied: r.applied, file: r.file, diff: r.diff, settings: r.settings, nextSteps });
+    }
+    else if (!r.changed)
+        io.out(`Auto Handoff is already ${sub === 'enable' ? 'set that way' : 'off'}; nothing to change.`);
+    else if (!r.applied) {
+        io.out(`Change to ${tildify(r.file, rt.paths.home)}:\n\n${r.diff}`);
+        if (sub === 'enable' && r.settings.sameFamily)
+            io.out(c.yellow('Same-family hand-over moves work between subscriptions of one vendor; vendors may act on that.'));
+        io.out(c.cyan(`\nApply it with \`${switchCommand(sub, change)} --yes\`.`));
+    }
+    else {
+        io.out(`${c.green('✓')} Auto Handoff is ${sub === 'enable' ? 'on' : 'off'}.`);
+        if (nextSteps.length) {
+            io.out('Still to do:');
+            for (const [i, step] of nextSteps.entries())
+                io.out(`  ${i + 1}. ${step}`);
+        }
+    }
+    // 10: the change is shown and waits for the user's yes, as for `quota setup`.
+    return r.changed && !r.applied ? 10 : 0;
+}
+/** `sideby handoff ready|setup|teardown` (spec §3.17). */
+export async function cmdHandoff(a, io) {
+    const sub = a.positionals[0];
+    if (sub === 'setup' || sub === 'teardown') {
+        const familyId = a.positionals[1];
+        if (!familyId)
+            throw new UsageError(`usage: sideby handoff ${sub} <family>${sub === 'setup' ? ' [--yes]' : ''}`);
+        const rt = await createRuntime();
+        return runSetup(a, io, rt, 'handoff', sub, familyId, rt.handoffSetup(familyId));
+    }
+    if (sub === 'status')
+        return cmdHandoffStatus(a, io);
+    if (sub === 'enable' || sub === 'disable')
+        return cmdHandoffSwitch(a, io, sub);
+    if (sub !== 'ready')
+        throw new UsageError('usage: sideby handoff status | enable [--same-family] [--order <family>=<acct,…>] [--threshold n] [--prepare-at n] [--yes] | disable [--yes] | ready [--brief <file>] | setup|teardown <family> [--yes]');
+    const flag = a.flags.get('brief');
+    const brief = typeof flag === 'string' ? flag : undefined;
+    const decision = await readyDecision(await createRuntime(), process.env);
+    if (decision && decision.kind !== 'pick')
+        throw new UserError(`nothing can take over now: ${explain(decision)}; keep working in this account`, {
+            code: 'no-pick',
+        });
+    let request;
+    try {
+        request = await requestHandoff(process.env, brief);
+    }
+    catch (err) {
+        throw new UserError(`cannot read the brief ${brief}: ${err.message}; check the path and retry`, {
+            code: 'brief-unreadable',
+        });
+    }
+    if (!request)
+        throw new UserError('not inside a session sideby started with Auto Handoff; set `handoff.auto` in the config and start the account with sideby (`sideby run`, a short command), or use `sideby next <family>`', { code: 'not-in-handoff-run' });
+    if (a.flags.has('json'))
+        json(io, { requested: true, ...(request.brief ? { brief: request.brief } : {}) });
+    else
+        io.out('The next account starts when this turn ends; finish the turn now.');
+    return 0;
+}
 export async function cmdPlugins(a, io) {
     const rt = await createRuntime();
     if (a.flags.has('json'))

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

@@ -1,4 +1,4 @@
-import type { QuotaResult, UsageResult } from '../types.ts';
+import type { QuotaResult, TuningResult, UsageResult } from '../types.ts';
 export declare const c: {
     dim: (s: string) => string;
     bold: (s: string) => string;
@@ -14,3 +14,5 @@ export declare const QUOTA_REASON: Record<string, string>;
 export declare function quotaText(q: QuotaResult, now: Date): string;
 export declare function compactNumber(n: number): string;
 export declare function usageText(u: UsageResult): string;
+/** One line per model of a tuning result, or the reason there is none. */
+export declare function tuningLines(t: TuningResult): string[];

package/dist/src/cli/format.js

@@ -1,4 +1,5 @@
 import { quotaLevel } from '../core/quota-levels.js';
+import { MIN_CALLS } from '../core/tuning.js';
 const useColor = () => !process.env.NO_COLOR && Boolean(process.stdout.isTTY);
 const paint = (code) => (s) => (useColor() ? `\x1b[${code}m${s}\x1b[0m` : s);
 export const c = {
@@ -78,3 +79,27 @@ export function usageText(u) {
         return c.dim('none');
     return `${compactNumber(u.totalTokens)} tok / ${u.days}d`;
 }
+const TUNING_REASON = {
+    'already-best': 'already the cheapest setting we can estimate',
+    'insufficient-calls': `too few calls to estimate (needs ${MIN_CALLS})`,
+    'no-compactions': 'no compaction recorded to estimate from',
+    'no-optimum': 'the cheapest point is at the bottom of the range tried, so there is no clear best value',
+    'unknown-model': 'not a Claude model, so the cost weights do not apply',
+    'observe-only': 'observation only (no public default for this host)',
+};
+/** One line per model of a tuning result, or the reason there is none. */
+export function tuningLines(t) {
+    if (t.status === 'unavailable')
+        return [t.reason === 'no-source' ? 'no public source for this host' : (t.detail ?? t.reason)];
+    return t.models.map((m) => {
+        const now = m.configured === null ? 'Host default' : `${compactNumber(m.configured)}`;
+        const head = `${m.model}  ${m.calls} calls  now ${now}  ${m.compactions.total} compactions`;
+        if (m.suggestion) {
+            const saved = m.suggestion.savedPercent === null
+                ? ''
+                : ` (about ${m.suggestion.savedPercent}% fewer weighted tokens)`;
+            return `${head}  suggest ${compactNumber(m.suggestion.threshold)}${saved}`;
+        }
+        return `${head}  ${m.reason === 'suggested' ? '' : TUNING_REASON[m.reason]}`;
+    });
+}