sideby 0.4.3 → 0.6.0

package/README.md

@@ -55,7 +55,7 @@ The agent checks Node and your Host CLIs, installs sideby and the skill, creates
 
 ## What it looks like
 
-<img alt="Two terminals: the personal account and the work account running at the same time, then the local quota panel" src="https://raw.githubusercontent.com/Adonis0123/sideby/main/docs/assets/demo.gif" width="1280">
+<img alt="Two terminals: the personal account and the work account running at the same time, both linked to the main account's skills and settings, then the local quota panel, and at 95% Auto Handoff moving work's session to the next account" src="https://raw.githubusercontent.com/Adonis0123/sideby/main/docs/assets/demo.gif" width="1280">
 
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Adonis0123/sideby/main/docs/assets/panel-dark.png">
@@ -71,6 +71,7 @@ The agent checks Node and your Host CLIs, installs sideby and the skill, creates
 | Find and fix config drift between accounts | `sideby doctor --fix` | [Doctor](docs/guide/usage.md#doctor) |
 | See Claude quota (Codex needs no setup) | `sideby quota setup claude --yes` | [Claude quota](docs/guide/usage.md#claude-quota) |
 | Find the cheapest auto-compact size from your own sessions, and use it in one click | `sideby tune` (or the panel's Context tuning tab) | [Context tuning](docs/guide/usage.md#context-tuning) |
+| See each account's model and effort, and set them per account | `sideby model <account>` (or click the model in the panel) | [Model and effort](docs/guide/usage.md#model-and-effort) |
 | Move on when an account hits its limit | `sideby next claude` | [Handoff](docs/guide/usage.md#when-an-account-hits-its-limit) |
 | Let a running task move to the next account by itself when quota runs low (off by default; see the risk) | `sideby handoff enable` (or the panel) | [Auto Handoff](docs/guide/usage.md#auto-handoff) |
 | Short commands such as `ccw` | `sideby alias add ccw claude:work` | [Shell functions](docs/guide/configuration.md#shell-functions) |

package/dist/build.json

@@ -1 +1 @@
-{"id":"20261014T033619-9eb027"}
+{"id":"20261014T070544-66900c"}

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

@@ -43,6 +43,11 @@ export declare function cmdResume(a: ParsedArgs, io: Io): Promise<number>;
 /** `sideby next <family>`: recommend the Account with the most room, then start it (spec §3.13). */
 export declare function cmdNext(a: ParsedArgs, io: Io): Promise<number>;
 export declare function cmdDoctor(a: ParsedArgs, io: Io): Promise<number>;
+/**
+ * `sideby model <account> [<model>|default] [--effort <level>|default] [--yes]` (spec §3.19, ADR-0014): shows the
+ * Account's model and effort; with a change, shows it (exit 10) and writes it with --yes.
+ */
+export declare function cmdModel(a: ParsedArgs, io: Io): Promise<number>;
 /** `sideby tune [account|family]`: estimated Compaction Threshold per model (spec §3.18). */
 export declare function cmdTune(a: ParsedArgs, io: Io): Promise<number>;
 export declare function cmdQuota(a: ParsedArgs, io: Io): Promise<number>;

package/dist/src/cli/commands.js

@@ -6,6 +6,7 @@ import { requestHandoff } from '../core/handoff-chain.js';
 import { explain, readyDecision, runWithHandoff } from '../core/handoff-run.js';
 import { configureHandoff, handoffHint, handoffStatus } from '../core/handoff-status.js';
 import { runHost } from '../core/launch.js';
+import { accountModel, setAccountModel } from '../core/model-choice.js';
 import { resolvePaths, tildify } from '../core/paths.js';
 import { USAGE_DAYS } from '../core/quota-levels.js';
 import { SHELLS } from '../core/shell-init.js';
@@ -401,6 +402,72 @@ async function cmdTuneChange(a, io, action) {
         io.out(r.message);
     return r.ok ? 0 : 1;
 }
+const FROM = {
+    sideby: 'set by sideby',
+    host: 'from the host config',
+    last: 'last session',
+};
+/**
+ * `sideby model <account> [<model>|default] [--effort <level>|default] [--yes]` (spec §3.19, ADR-0014): shows the
+ * Account's model and effort; with a change, shows it (exit 10) and writes it with --yes.
+ */
+export async function cmdModel(a, io) {
+    const [ref, model] = a.positionals;
+    if (!ref || a.positionals.length > 2 || a.flags.get('effort') === true)
+        throw new UsageError('usage: sideby model <account> [<model>|default] [--effort <level>|default] [--yes] [--json]');
+    const wantJson = a.flags.has('json');
+    const rt = await createRuntime();
+    const account = await rt.resolve(ref);
+    const effort = a.flags.get('effort');
+    const view = await accountModel(rt, account);
+    const shown = {
+        account: account.ref,
+        family: account.family,
+        settable: view.settable,
+        ...(view.reason ? { reason: view.reason } : {}),
+        efforts: view.efforts,
+        models: view.models,
+        sideby: view.sideby,
+        host: view.host,
+        last: view.last,
+        ...(view.model ? { model: view.model } : {}),
+        ...(view.effort ? { effort: view.effort } : {}),
+    };
+    if (model === undefined && effort === undefined) {
+        if (a.flags.has('yes'))
+            throw new UsageError('--yes needs a change: sideby model <account> <model> or --effort <level>');
+        if (wantJson)
+            json(io, shown);
+        else {
+            io.out(account.ref);
+            io.out(`  model   ${view.model ? `${view.model.value}  (${FROM[view.model.from]})` : 'the host default'}`);
+            io.out(`  effort  ${view.effort ? `${view.effort.value}  (${FROM[view.effort.from]})` : 'the host default'}`);
+            if (view.settable)
+                io.out(c.dim(`Change it: sideby model ${account.ref} <model|default> --effort <${view.efforts.join('|')}|default>`));
+            else if (view.reason)
+                io.out(c.dim(view.reason));
+        }
+        return 0;
+    }
+    const asChange = (v) => (v === undefined ? undefined : v === 'default' ? null : v);
+    const change = {
+        ...(model !== undefined ? { model: asChange(model) } : {}),
+        ...(typeof effort === 'string' ? { effort: asChange(effort) } : {}),
+    };
+    const yes = a.flags.has('yes');
+    const r = await setAccountModel(rt, account, change, { apply: yes });
+    const home = rt.paths.home;
+    const result = { ...r, file: tilde(r.file, home) };
+    if (wantJson)
+        json(io, { ...shown, change: result });
+    else if (!r.changed)
+        io.out('Nothing to change.');
+    else if (!yes)
+        io.out(`${r.diff}Run again with --yes to apply. It affects sessions started with sideby from now on.`);
+    else
+        io.out(`Saved. New sessions of ${account.ref} started with sideby use: ${r.args.join(' ') || 'the host defaults'}`);
+    return r.changed && !yes ? 10 : 0;
+}
 /** `sideby tune [account|family]`: estimated Compaction Threshold per model (spec §3.18). */
 export async function cmdTune(a, io) {
     if (a.positionals[0] === 'apply' || a.positionals[0] === 'undo')

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

@@ -6,6 +6,11 @@ const Str = Type.String();
 const Level = Type.Union([Type.Literal('ok'), Type.Literal('warn'), Type.Literal('fail')]);
 const Kind = Type.Union([Type.Literal('subscription'), Type.Literal('api')]);
 const Version = Type.Literal(1);
+const Choice = Type.Object({ model: Type.Optional(Str), effort: Type.Optional(Str) });
+const Shown = Type.Object({
+    value: Str,
+    from: Type.Union([Type.Literal('sideby'), Type.Literal('host'), Type.Literal('last')]),
+});
 const AppPlatform = Type.Union([Type.Literal('darwin'), Type.Literal('linux')]);
 const Account = Type.Object({
     family: Str,
@@ -162,6 +167,8 @@ const Usage = Type.Union([
             description: 'Tokens per local day (YYYY-MM-DD), oldest first, days without records as 0.',
         })),
         lastActivityAt: Type.Optional(Str),
+        lastModel: Type.Optional(Str),
+        lastEffort: Type.Optional(Str),
     }),
     Type.Object({ status: Type.Literal('unavailable'), reason: Str, detail: Type.Optional(Str) }),
 ]);
@@ -219,6 +226,29 @@ export const OUTPUT_SCHEMAS = {
         })),
         message: Type.Optional(Str),
     }, { title: 'sideby tune apply|undo --json' }),
+    model: Type.Object({
+        schemaVersion: Version,
+        account: Str,
+        family: Str,
+        settable: Type.Boolean({
+            description: 'Whether sideby can set the model and effort for this account.',
+        }),
+        reason: Type.Optional(Str),
+        efforts: Type.Array(Str),
+        models: Type.Array(Str, { description: 'Model names to offer; any other name may be given.' }),
+        sideby: Choice,
+        host: Choice,
+        last: Choice,
+        model: Type.Optional(Shown),
+        effort: Type.Optional(Shown),
+        change: Type.Optional(Type.Object({
+            changed: Type.Boolean(),
+            applied: Type.Boolean(),
+            file: Str,
+            diff: Str,
+            args: Type.Array(Str, { description: 'The account arguments in the config after the change.' }),
+        })),
+    }, { title: 'sideby model --json' }),
     tune: Type.Object({
         schemaVersion: Version,
         accounts: Type.Array(Type.Object({ ref: Str, family: Str, tuning: Tuning })),

package/dist/src/cli/main.js

@@ -32,6 +32,8 @@ Usage:
   sideby quota teardown claude        undo it, restoring the original file
   sideby tune [account|family]        estimate the cheapest auto-compact threshold per model
                                       from your last 7 days of sessions (read-only)
+  sideby model <account> [<model>|default] [--effort <level>|default] [--yes]
+                                      show or set the model and effort sideby starts this account with
   sideby handoff status               what Auto Handoff still needs on this machine
   sideby handoff enable [--yes]       turn it on (shows the config change first); --same-family,
                                       --order claude=codex001,cc002, --threshold n, --prepare-at n
@@ -154,6 +156,7 @@ const COMMANDS = {
     doctor: { flags: ['fix', 'force', 'json'] },
     quota: { flags: ['json', 'yes'] },
     tune: { flags: ['json', 'yes'] },
+    model: { flags: ['json', 'yes'], valued: ['effort'] },
     handoff: {
         flags: ['json', 'yes', 'same-family', 'no-same-family'],
         valued: ['brief', 'order', 'prepare-at', 'threshold', 'wait-minutes', 'countdown'],
@@ -255,6 +258,8 @@ export async function main(argv) {
                 return await cmds.cmdQuota(parsed, io);
             case 'tune':
                 return await cmds.cmdTune(parsed, io);
+            case 'model':
+                return await cmds.cmdModel(parsed, io);
             case 'handoff':
                 return await cmds.cmdHandoff(parsed, io);
             case 'ui':

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

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

package/dist/src/core/config.js

@@ -224,6 +224,15 @@ async function editConfigAliases(file, retry, edit) {
 export function editConfigHandoff(file, edit, opts = {}) {
     return editConfigKey(file, 'handoff', 'run the command', (current) => edit(current ?? {}), opts);
 }
+/**
+ * `sideby model` (spec §3.19): changes the config `accounts` key with `edit` (see `editConfigKey` for how the file is
+ * written). With `dryRun`, shows the change without writing.
+ */
+export function editConfigAccounts(file, 
+/** Returns null to leave the file as it is. */
+edit, opts = {}) {
+    return editConfigKey(file, 'accounts', 'run the command', (current) => edit(current ?? {}), opts);
+}
 /**
  * Adds `alias → ref` to the config file's `aliases`, as `{ account, args }` when `args` is not empty (see
  * `editConfigAliases` for how the file is written). Refuses an invalid alias, or one that already starts another

package/dist/src/core/handoff-enable.d.ts

@@ -0,0 +1,52 @@
+import type { Runtime } from '../runtime.ts';
+export interface EnableStep {
+    /** `config`: the `handoff` key; `quota`: the Family's quota display; `hook`: its hook file; `copy`: only that hook file, into the other Accounts of the Family. */
+    id: 'config' | 'quota' | 'hook' | 'copy';
+    family?: string;
+    /** The file the step changes; for `copy`, the file that is copied. */
+    file?: string;
+    diff?: string;
+    /** For `copy`: the Accounts that get the file. */
+    accounts?: string[];
+}
+export interface EnableManual {
+    /** `codex-trust`: each Codex account trusts the hooks once, in `/hooks`; `setup-blocked`: a setup that cannot be applied. */
+    id: 'codex-trust' | 'setup-blocked';
+    family?: string;
+    message?: string;
+}
+export interface EnablePlan {
+    /** Everything is already in place; nothing would be written. */
+    alreadyOn: boolean;
+    /** Why nothing can be done from here (the sideby on PATH does not answer hooks); a person has to fix it first. */
+    blocked?: string;
+    steps: EnableStep[];
+    manual: EnableManual[];
+    /** Same-Family hand-over as it will be once the plan is applied. */
+    sameFamily: boolean;
+    /** Names this plan; a confirmation that sends it back as `expect` applies only this plan. */
+    key: string;
+}
+export interface EnableResult {
+    plan: EnablePlan;
+    results: {
+        id: EnableStep['id'];
+        family?: string;
+        accounts?: string[];
+        ok: boolean;
+        message: string;
+    }[];
+    /** The plan is no longer the one that was shown (`expect`), so nothing was written; `plan` is the new one. */
+    changed?: boolean;
+}
+export declare function planHandoffEnable(rt: Runtime, opts?: {
+    sameFamily?: boolean;
+}): Promise<EnablePlan>;
+/**
+ * Applies the plan in an order where "on" means "working": the setups first, the config key last. Stops at the first
+ * failure. With `expect`, writes nothing unless the plan is still the one that was shown.
+ */
+export declare function applyHandoffEnable(rt: Runtime, opts?: {
+    sameFamily?: boolean;
+    expect?: string;
+}): Promise<EnableResult>;

package/dist/src/core/handoff-enable.js

@@ -0,0 +1,169 @@
+// Turning Auto Handoff on in one step (spec §3.17 "页面与一键开启", ADR-0013): the Panel's button does what the CLI's
+// `handoff enable`, `quota setup` and `handoff setup` do, shown first as one plan and applied together after one
+// confirmation. Every step is an existing, reversible setup; nothing new is written.
+import { createHash } from 'node:crypto';
+import { lstat, mkdir, readFile, stat } from 'node:fs/promises';
+import { dirname, isAbsolute, join, relative } from 'node:path';
+import { realpathOrNull, writeFileAtomic } from './fs-safe.js';
+import { configureHandoff, handoffStatus } from './handoff-status.js';
+const keyOf = (p) => createHash('sha256')
+    .update(JSON.stringify([p.blocked ?? null, p.sameFamily, p.steps]))
+    .digest('hex')
+    .slice(0, 16);
+/** Whether `rel` below `dir` goes through a link: a file seen through one is already there, or is not ours to change. */
+async function throughLink(dir, rel) {
+    let at = dir;
+    for (const part of rel.split('/')) {
+        at = join(at, part);
+        const st = await lstat(at).catch(() => null);
+        if (!st)
+            return false;
+        if (st.isSymbolicLink())
+            return true;
+    }
+    return false;
+}
+/**
+ * The other Accounts of the Family that lack the hook file `file` (a path in the Main Account) at the same place in
+ * their own directory. Only that one file is ever written, and one that is already there is left as it is: an
+ * Account's other files are never touched.
+ */
+async function hookCopies(rt, family, file) {
+    const accounts = (await rt.accounts()).filter((a) => a.family === family);
+    const main = accounts.find((a) => a.isMain);
+    if (!main)
+        return [];
+    const rel = relative(main.dir, file);
+    if (!rel || rel.startsWith('..') || isAbsolute(rel))
+        return [];
+    const mainReal = await realpathOrNull(main.dir);
+    const out = [];
+    for (const a of accounts) {
+        if (a.isMain || (await realpathOrNull(a.dir)) === mainReal || (await throughLink(a.dir, rel)))
+            continue;
+        const target = join(a.dir, rel);
+        // Whether the file is there, not whether it can be read: one that cannot be read is still not ours to replace.
+        const have = await lstat(target).then(() => true, () => false);
+        // A file that is already there is not ours to replace, whatever it says.
+        if (!have)
+            out.push({ ref: a.ref, target });
+    }
+    return out;
+}
+/** `sameFamily` left out keeps the current setting; Turn on from the Panel says it either way. */
+const changeOf = (opts) => ({
+    auto: true,
+    ...(opts.sameFamily === undefined ? {} : { sameFamily: opts.sameFamily }),
+});
+export async function planHandoffEnable(rt, opts = {}) {
+    const st = await handoffStatus(rt);
+    if (st.sideby.problem) {
+        const plan = {
+            alreadyOn: false,
+            blocked: st.sideby.problem,
+            steps: [],
+            manual: [],
+            sameFamily: st.sameFamily,
+        };
+        return { ...plan, key: keyOf(plan) };
+    }
+    const steps = [];
+    const manual = [];
+    const cfg = await configureHandoff(rt, changeOf(opts), { apply: false });
+    if (cfg.changed)
+        steps.push({ id: 'config', file: cfg.file, diff: cfg.diff });
+    for (const f of st.families) {
+        if (!f.starts.length)
+            continue;
+        const def = rt.families.get(f.family);
+        if (def?.quotaSetup && f.starts.includes('quota')) {
+            const plan = await rt
+                .quotaSetup(f.family)
+                .plan()
+                .catch(() => null);
+            if (plan?.status === 'ready')
+                steps.push({ id: 'quota', family: f.family, file: plan.file, diff: plan.diff });
+            else if (plan?.status === 'blocked')
+                manual.push({ id: 'setup-blocked', family: f.family, message: plan.message });
+        }
+        if (def?.handoff?.hookSetup) {
+            const plan = await rt
+                .handoffSetup(f.family)
+                .plan()
+                .catch(() => null);
+            if (plan?.status === 'ready')
+                steps.push({ id: 'hook', family: f.family, file: plan.file, diff: plan.diff });
+            else if (plan?.status === 'blocked')
+                manual.push({ id: 'setup-blocked', family: f.family, message: plan.message });
+            if (plan?.status === 'ready' || plan?.status === 'enabled') {
+                const copies = await hookCopies(rt, f.family, plan.file);
+                if (copies.length)
+                    steps.push({ id: 'copy', family: f.family, file: plan.file, accounts: copies.map((c) => c.ref) });
+            }
+        }
+        if (f.family === 'codex')
+            manual.push({ id: 'codex-trust', family: 'codex' });
+    }
+    const plan = { alreadyOn: steps.length === 0, steps, manual, sameFamily: cfg.settings.sameFamily };
+    return { ...plan, key: keyOf(plan) };
+}
+/**
+ * Applies the plan in an order where "on" means "working": the setups first, the config key last. Stops at the first
+ * failure. With `expect`, writes nothing unless the plan is still the one that was shown.
+ */
+export async function applyHandoffEnable(rt, opts = {}) {
+    const plan = await planHandoffEnable(rt, opts);
+    if (opts.expect !== undefined && opts.expect !== plan.key)
+        return { plan, results: [], changed: true };
+    const results = [];
+    if (!plan.blocked) {
+        const order = ['quota', 'hook', 'copy', 'config'];
+        const todo = [...plan.steps].sort((a, b) => order.indexOf(a.id) - order.indexOf(b.id));
+        for (const step of todo) {
+            let ok = true;
+            let message = '';
+            try {
+                if (step.id === 'quota' || step.id === 'hook') {
+                    const setup = step.id === 'quota' ? rt.quotaSetup(step.family) : rt.handoffSetup(step.family);
+                    const r = await setup.apply();
+                    ok = r.status === 'enabled';
+                    message = r.message;
+                }
+                else if (step.id === 'copy') {
+                    const file = step.file;
+                    const want = await readFile(file, 'utf8');
+                    const mode = (await stat(file)).mode & 0o777;
+                    const listed = new Set(step.accounts);
+                    const copies = (await hookCopies(rt, step.family, file)).filter((c) => listed.has(c.ref));
+                    for (const c of copies) {
+                        await mkdir(dirname(c.target), { recursive: true });
+                        await writeFileAtomic(c.target, want, mode);
+                    }
+                    const left = await hookCopies(rt, step.family, file);
+                    ok = left.length === 0;
+                    message = left.length
+                        ? `${left.map((c) => c.ref).join(', ')} still lack ${file}; try again, and if it keeps failing, check that you may write to their hooks folder`
+                        : '';
+                }
+                else {
+                    const r = await configureHandoff(rt, changeOf(opts), { apply: true });
+                    ok = r.applied || !r.changed;
+                }
+            }
+            catch (err) {
+                ok = false;
+                message = err.message;
+            }
+            results.push({
+                id: step.id,
+                ...(step.family ? { family: step.family } : {}),
+                ...(step.accounts ? { accounts: step.accounts } : {}),
+                ok,
+                message,
+            });
+            if (!ok)
+                break;
+        }
+    }
+    return { plan, results };
+}

package/dist/src/core/handoff-overview.d.ts

@@ -0,0 +1,26 @@
+import type { Runtime } from '../runtime.ts';
+import type { HandoffSettings } from './config.ts';
+import { type HandoffTrigger } from './handoff-chain.ts';
+import type { HandoffDecision } from './handoff-select.ts';
+export interface RecentHandoff {
+    from: string;
+    to: string;
+    /** When the next account started. */
+    at: string;
+    trigger: HandoffTrigger | null;
+    briefSource: 'agent' | 'sideby' | 'user' | null;
+}
+export interface HandoffOverview {
+    settings: HandoffSettings;
+    /** Where each subscription account of a Family that can start a hand-over would send its work; empty while off. */
+    takeover: {
+        ref: string;
+        family: string;
+        starts: ('quota' | 'limit')[];
+        decision: HandoffDecision;
+    }[];
+    recent: RecentHandoff[];
+}
+/** The latest hand-overs, newest first: a hop that ended with a trigger and was followed by another hop. */
+export declare function readRecentHandoffs(stateDir: string, limit?: number): Promise<RecentHandoff[]>;
+export declare function handoffOverview(rt: Runtime): Promise<HandoffOverview>;

package/dist/src/core/handoff-overview.js

@@ -0,0 +1,63 @@
+// What the Panel's Auto Handoff page shows (spec §3.17 "页面与一键开启"): where each account's work would go next and
+// the last hand-overs. Reads only; from the chain files it takes the accounts, times and triggers, never a Brief.
+import { readdir, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { HOOK_FAMILIES } from '../handoff/hook.js';
+import { FILES, readJsonFile } from './handoff-chain.js';
+const SCAN_CHAINS = 40;
+const RECENT = 5;
+/** The latest hand-overs, newest first: a hop that ended with a trigger and was followed by another hop. */
+export async function readRecentHandoffs(stateDir, limit = RECENT) {
+    const root = join(stateDir, 'handoffs');
+    const names = await readdir(root).catch(() => []);
+    const dirs = (await Promise.all(names.map(async (n) => ({ n, t: (await stat(join(root, n)).catch(() => null))?.mtimeMs ?? 0 }))))
+        .sort((a, b) => b.t - a.t)
+        .slice(0, SCAN_CHAINS);
+    const out = [];
+    for (const { n } of dirs) {
+        const chain = await readJsonFile(join(root, n, FILES.chain));
+        const hops = Array.isArray(chain?.hops) ? chain.hops : [];
+        for (let i = 0; i + 1 < hops.length; i++) {
+            const from = hops[i];
+            const to = hops[i + 1];
+            if (typeof from.ref !== 'string' ||
+                typeof to.ref !== 'string' ||
+                !Number.isFinite(Date.parse(to.startedAt)))
+                continue;
+            out.push({
+                from: from.ref,
+                to: to.ref,
+                at: to.startedAt,
+                trigger: from.trigger ?? null,
+                briefSource: from.briefSource ?? null,
+            });
+        }
+    }
+    return out.sort((a, b) => Date.parse(b.at) - Date.parse(a.at)).slice(0, limit);
+}
+export async function handoffOverview(rt) {
+    const settings = rt.handoffSettings();
+    const recent = await readRecentHandoffs(rt.paths.stateDir);
+    if (!settings.auto)
+        return { settings, takeover: [], recent };
+    const starters = new Set([...rt.families.values()]
+        .filter((f) => f.handoff?.starts.length && HOOK_FAMILIES.includes(f.id))
+        .map((f) => f.id));
+    const subs = (await rt.accounts()).filter((a) => starters.has(a.family) && a.kind === 'subscription');
+    const takeover = await Promise.all(subs.map(async (a) => {
+        let decision;
+        try {
+            decision = await rt.handoffDecision(a, [a.ref], { ahead: true });
+        }
+        catch (err) {
+            decision = { kind: 'none', reason: err.message };
+        }
+        return {
+            ref: a.ref,
+            family: a.family,
+            starts: [...(rt.families.get(a.family)?.handoff?.starts ?? [])],
+            decision,
+        };
+    }));
+    return { settings, takeover, recent };
+}

package/dist/src/core/handoff-run.js

@@ -213,7 +213,8 @@ opts = {}) {
         const writePlan = () => {
             pending = pending.then(async () => {
                 try {
-                    const d = await rt.handoffDecision(account, used);
+                    // Read by the hook once the threshold is crossed, so it answers for that moment (spec §3.17 "选号" 1).
+                    const d = await rt.handoffDecision(account, used, { ahead: true });
                     if (stopped)
                         return;
                     const plan = {

package/dist/src/core/handoff-select.d.ts

@@ -39,4 +39,6 @@ export declare function selectNext(input: {
     /** Accounts this chain already used, the origin included. */
     used: readonly string[];
     now: Date;
+    /** Decide now what happens when the origin's fullest window reaches the threshold (see `waitUntil`). */
+    ahead?: boolean;
 }): HandoffDecision;

package/dist/src/core/handoff-select.js

@@ -9,13 +9,19 @@ export function sameOrganization(a, b) {
         return domain(a.email) === domain(b.email);
     return true;
 }
-/** The latest reset of the origin's windows at or above the threshold, when they all reset in time to wait. */
-function waitUntil(origin, s, now) {
+/**
+ * The latest reset of the origin's full windows, when they all reset in time to wait. Full means at the threshold;
+ * `ahead` also counts the fullest window once it is past `prepareAt`, since it answers what happens when that window
+ * reaches the threshold (spec §3.17 "选号" 1: plan.json and the Panel, decided before the moment comes).
+ */
+function waitUntil(origin, s, now, ahead) {
     if (origin.quota.status !== 'ok' || s.waitIfResetWithinMinutes <= 0)
         return undefined;
+    const open = origin.quota.windows.filter((w) => !windowReset(w.resetsAt, now));
+    const top = Math.max(0, ...open.map((w) => w.usedPercent));
     let last;
-    for (const w of origin.quota.windows) {
-        if (w.usedPercent < s.threshold || windowReset(w.resetsAt, now))
+    for (const w of open) {
+        if (w.usedPercent < s.threshold && !(ahead && w.usedPercent === top && top >= s.prepareAt))
             continue;
         const t = Date.parse(w.resetsAt);
         if (!Number.isFinite(t))
@@ -46,7 +52,7 @@ function stateOf(c, s, now) {
 }
 export function selectNext(input) {
     const { origin, settings: s, now } = input;
-    const until = waitUntil(origin, s, now);
+    const until = waitUntil(origin, s, now, input.ahead === true);
     if (until)
         return { kind: 'wait', until };
     const refOf = (name) => input.aliases[name] ?? name;

package/dist/src/core/model-choice.d.ts

@@ -0,0 +1,41 @@
+import type { Runtime } from '../runtime.ts';
+import type { Account, ModelChoice } from '../types.ts';
+/** Where a shown value comes from: sideby's own argument, the Host's config, or the last session. */
+export type ChoiceSource = 'sideby' | 'host' | 'last';
+export interface AccountModel {
+    ref: string;
+    family: string;
+    /** Whether sideby can set it for this Account; when not, `reason` says why. */
+    settable: boolean;
+    reason?: string;
+    efforts: string[];
+    models: string[];
+    sideby: ModelChoice;
+    host: ModelChoice;
+    last: ModelChoice;
+    model?: {
+        value: string;
+        from: ChoiceSource;
+    };
+    effort?: {
+        value: string;
+        from: ChoiceSource;
+    };
+}
+/** `last` is the model and effort of the newest session, from the usage reader when the caller already has it. */
+export declare function accountModel(rt: Runtime, account: Account, last?: ModelChoice): Promise<AccountModel>;
+/** A change: `undefined` keeps what sideby sets now, `null` goes back to the Host's default. */
+export interface ModelChange {
+    model?: string | null;
+    effort?: string | null;
+}
+/** Shows, or with `apply` writes, the change to the Account's model and effort arguments. */
+export declare function setAccountModel(rt: Runtime, account: Account, change: ModelChange, opts: {
+    apply: boolean;
+}): Promise<{
+    changed: boolean;
+    applied: boolean;
+    file: string;
+    diff: string;
+    args: string[];
+}>;