sideby 0.4.2 → 0.5.0

package/dist/build.json

@@ -1 +1 @@
-{"id":"20261013T095821-360786"}
+{"id":"20261014T061214-0f7370"}

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/families/claude/quota-cache.d.ts

@@ -12,6 +12,13 @@ export declare function cacheStateDir(env: Env): string;
 export declare function accountNameFromEnv(env: Env): string | null;
 /** Extracts the 5h and 7d windows from status line JSON; null when there is nothing usable. */
 export declare function parseRateLimits(input: string, observedAt: Date): ClaudeQuotaCache | null;
+/**
+ * Merges a status line reading into the cached windows. Each session reports the Quota of its own last request, so an
+ * idle session of the same Account reports older numbers, sometimes of a window that has already reset: within one
+ * window the higher use wins, otherwise the later reset; a window the reading lacks is kept. Null when the reading
+ * only repeats older numbers, so nothing is written and `observedAt` keeps the time of the newer reading.
+ */
+export declare function mergeQuotaCache(cached: readonly QuotaWindow[], next: ClaudeQuotaCache): ClaudeQuotaCache | null;
 /** Writes the cache atomically; creates the private parent directory first (writeFileAtomic does not). */
 export declare function writeQuotaCache(stateDir: string, name: string, cache: ClaudeQuotaCache): Promise<void>;
 export type CacheRead = {

package/dist/src/families/claude/quota-cache.js

@@ -64,6 +64,46 @@ export function parseRateLimits(input, observedAt) {
     }
     return windows.length ? { version: 1, observedAt: observedAt.toISOString(), windows } : null;
 }
+/** Two readings belong to one window when their resets are less than a quarter of the window apart. */
+function sameWindow(a, b) {
+    return Math.abs(Date.parse(a.resetsAt) - Date.parse(b.resetsAt)) < (a.windowMinutes * 60_000) / 4;
+}
+const sameReading = (a, b) => a.label === b.label &&
+    a.windowMinutes === b.windowMinutes &&
+    a.usedPercent === b.usedPercent &&
+    a.resetsAt === b.resetsAt;
+const order = (label) => {
+    const i = WINDOWS.findIndex((w) => w.label === label);
+    return i < 0 ? WINDOWS.length : i;
+};
+/**
+ * Merges a status line reading into the cached windows. Each session reports the Quota of its own last request, so an
+ * idle session of the same Account reports older numbers, sometimes of a window that has already reset: within one
+ * window the higher use wins, otherwise the later reset; a window the reading lacks is kept. Null when the reading
+ * only repeats older numbers, so nothing is written and `observedAt` keeps the time of the newer reading.
+ */
+export function mergeQuotaCache(cached, next) {
+    let older = false;
+    const windows = next.windows.map((w) => {
+        const c = cached.find((x) => x.label === w.label);
+        if (!c)
+            return w;
+        const keep = sameWindow(c, w)
+            ? c.usedPercent > w.usedPercent
+            : Date.parse(c.resetsAt) > Date.parse(w.resetsAt);
+        if (keep)
+            older = true;
+        return keep ? c : w;
+    });
+    for (const c of cached)
+        if (!windows.some((w) => w.label === c.label))
+            windows.push(c);
+    windows.sort((a, b) => order(a.label) - order(b.label));
+    const unchanged = windows.length === cached.length && windows.every((w) => cached.some((c) => sameReading(c, w)));
+    if (older && unchanged)
+        return null;
+    return { ...next, windows };
+}
 /** Writes the cache atomically; creates the private parent directory first (writeFileAtomic does not). */
 export async function writeQuotaCache(stateDir, name, cache) {
     const file = claudeQuotaCacheFile(stateDir, name);

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

@@ -191,7 +191,7 @@ export const grokHookSetup = {
         await rmdir(join(ctx.home, '.grok', 'hooks')).catch(() => { });
         return {
             ok: true,
-            message: `removed ${shown}; run \`sideby doctor grok --fix\` to remove the copies in other Grok accounts`,
+            message: `removed ${shown}; the copies in other Grok accounts (hooks/sideby-handoff.json) stay and do nothing outside a sideby hand-over; delete them yourself if you no longer want them`,
         };
     },
 };

package/dist/src/handoff/messages.js

@@ -9,7 +9,7 @@ const TEMPLATE = [
 ].join('; ');
 const RULES = 'Reference specs, ADRs, commits and diffs by path instead of repeating them, list the skills the next agent should use, and never include keys, passwords or personal data.';
 export function prepareMessage(brief, pressure) {
-    return `sideby: this account's quota is at ${Math.round(pressure)}%, so another account may take over soon. Write a handoff brief to ${brief} now (${TEMPLATE}). ${RULES} Keep it current after each step, then go on with the task.`;
+    return `sideby: this account's quota is at ${Math.round(pressure)}%. Write a handoff brief to ${brief} now (${TEMPLATE}). ${RULES} Keep it current after each step, then go on with the task. Do not tell the user that the work will move to another account: sideby decides that and tells them itself.`;
 }
 export function thresholdMessage(brief, pressure) {
     return `sideby: this account's quota is at ${Math.round(pressure)}%. Finish the current step, update the handoff brief at ${brief} (${TEMPLATE}; ${RULES}), then end your turn. sideby will start the next account from that brief.`;

package/dist/src/panel/handler.js

@@ -4,6 +4,8 @@ import { aliasesByAccount } from '../core/accounts.js';
 import { aliasArgs, aliasRefs } from '../core/config.js';
 import { UserError } from '../core/errors.js';
 import { planHandoff } from '../core/handoff.js';
+import { applyHandoffEnable, planHandoffEnable } from '../core/handoff-enable.js';
+import { handoffOverview } from '../core/handoff-overview.js';
 import { configureHandoff, handoffStatus } from '../core/handoff-status.js';
 import { tildify } from '../core/paths.js';
 import { MIN_CALLS } from '../core/tuning.js';
@@ -393,6 +395,34 @@ export function createPanelHandler(opts) {
                 return { ...r, file: tildify(r.file, rt.paths.home) };
             },
         },
+        // The Auto Handoff page (spec §3.17): where work would go next and the last hand-overs. Reads only.
+        '/api/handoff/overview': {
+            writes: () => false,
+            async run() {
+                return handoffOverview(await getRuntime());
+            },
+        },
+        // Turning it on in one step (ADR-0013): without `confirm` only the plan; with it, every step in order.
+        '/api/handoff/enable': {
+            writes: (body) => body.confirm === true,
+            async run(body) {
+                // Left out keeps the current setting; true or false sets it.
+                const sameFamily = body.sameFamily === undefined ? undefined : optBool(body, 'sameFamily');
+                const rt = await getRuntime();
+                const home = rt.paths.home;
+                const show = (p) => ({
+                    ...p,
+                    steps: p.steps.map((s) => (s.file ? { ...s, file: tildify(s.file, home) } : s)),
+                });
+                const opts = sameFamily === undefined ? {} : { sameFamily };
+                if (!optBool(body, 'confirm'))
+                    return show(await planHandoffEnable(rt, opts));
+                // `expect`: the key of the plan the person saw; a different plan now is shown again, not applied.
+                const expect = optString(body, 'expect');
+                const r = await applyHandoffEnable(rt, expect === undefined ? opts : { ...opts, expect });
+                return { ...r, plan: show(r.plan) };
+            },
+        },
         // Undo for the setup above; the Runtime turns a teardown that throws into `{ ok: false, message }`.
         '/api/quota/teardown': {
             async run(body) {

package/dist/src/panel/i18n.d.ts

@@ -233,6 +233,54 @@ declare const en: {
     'menu.check': string;
     'menu.like': string;
     'menu.tune': string;
+    'page.handoff': string;
+    'hp.title': string;
+    'hp.advanced': string;
+    'hp.loading': string;
+    'hp.intro': string;
+    'hp.how1': string;
+    'hp.how2': string;
+    'hp.how3': string;
+    'hp.noStarters': string;
+    'hp.sameFamily': string;
+    'hp.turnOn': string;
+    'hp.turnOff': string;
+    'hp.willDo': string;
+    'hp.step.config': string;
+    'hp.step.quota': string;
+    'hp.step.hook': string;
+    'hp.step.copy': string;
+    'hp.showChange': string;
+    'hp.sameFamilyOffNote': string;
+    'hp.manual.codexTrust': string;
+    'hp.blocked': string;
+    'hp.confirmOn': string;
+    'hp.applying': string;
+    'hp.stepFailed': string;
+    'hp.tryAgain': string;
+    'hp.onNote': string;
+    'hp.takeover': string;
+    'hp.used': string;
+    'hp.noQuota': string;
+    'hp.goesTo': string;
+    'hp.goesToLimit': string;
+    'hp.waits': string;
+    'hp.waitRule': string;
+    'hp.planChanged': string;
+    'hp.none': string;
+    'hp.noneBack': string;
+    'hp.noAccounts': string;
+    'hp.recent': string;
+    'hp.noneYet': string;
+    'hp.why.threshold': string;
+    'hp.why.limit': string;
+    'hp.why.manual': string;
+    'hp.missing': string;
+    'hp.complete': string;
+    'hp.onlySideby': string;
+    'hp.sameConfirm': string;
+    'hp.sameOn': string;
+    'hp.sameOff': string;
     'page.accounts': string;
     'page.tuning': string;
     'tune.title': string;

package/dist/src/panel/i18n.js

@@ -235,6 +235,54 @@ const en = {
     'menu.check': 'Check this account',
     'menu.like': 'New account like this',
     'menu.tune': 'Context tuning',
+    'page.handoff': 'Auto Handoff',
+    'hp.title': 'Auto Handoff',
+    'hp.advanced': 'Advanced settings',
+    'hp.loading': 'Checking…',
+    'hp.intro': 'When an account is about to run out of quota, your work moves to the next account by itself. You do not have to do anything.',
+    'hp.how1': 'You keep working in a session you started with sideby (a short command such as cc001, or sideby run).',
+    'hp.how2': 'When that account reaches {p}% of its quota, sideby has the AI write a short note about the task and ends the session.',
+    'hp.how3': 'After a {s}-second countdown (Enter cancels), the next account starts in the same terminal and carries on from the note.',
+    'hp.noStarters': 'None of your accounts can start a hand-over yet. Add a Claude, Codex or Grok account first.',
+    'hp.sameFamily': 'Also switch between accounts of the same tool (for example cc001 to cc002)',
+    'hp.turnOn': 'Turn on',
+    'hp.turnOff': 'Turn off',
+    'hp.willDo': 'To turn it on, sideby will:',
+    'hp.step.config': 'Switch Auto Handoff on in sideby’s settings',
+    'hp.step.quota': 'Turn on {host} quota display (hand-over needs it to know how much is used)',
+    'hp.step.hook': 'Add sideby’s hand-over hook to {host}',
+    'hp.step.copy': 'Copy the hook file into your other {host} accounts ({accounts}); nothing else in them changes',
+    'hp.showChange': 'Show the change',
+    'hp.sameFamilyOffNote': 'Accounts of the same tool will not switch between each other. You can turn that on later on this page.',
+    'hp.manual.codexTrust': 'Codex asks once per account to trust sideby’s hooks. Type /hooks in Codex the first time and trust them; sideby reminds you then.',
+    'hp.blocked': 'It cannot be turned on yet: {why}',
+    'hp.confirmOn': 'Confirm and turn on',
+    'hp.applying': 'Turning on…',
+    'hp.stepFailed': 'Stopped at: {step}. {why}',
+    'hp.tryAgain': 'Nothing after it was changed. Try again, or ask for help.',
+    'hp.onNote': 'When an account reaches {p}% of its quota, its session moves to the next account by itself.',
+    'hp.takeover': 'Where work goes next',
+    'hp.used': '{p}% used',
+    'hp.noQuota': 'quota unknown',
+    'hp.goesTo': 'at {p}% it moves to {to}',
+    'hp.goesToLimit': 'when it hits its usage limit it moves to {to}',
+    'hp.waits': 'at the limit it waits: quota is back at {at}',
+    'hp.waitRule': 'If its quota comes back within {w} minutes at that point, it waits instead of switching.',
+    'hp.planChanged': 'Something changed since you looked, so sideby has not changed anything yet. This is what it would do now; confirm again.',
+    'hp.none': 'no account can take over right now',
+    'hp.noneBack': 'no account can take over now; {ref} is back at {at}',
+    'hp.noAccounts': 'No subscription account can start a hand-over.',
+    'hp.recent': 'Recent hand-overs',
+    'hp.noneYet': 'None yet. The next time an account runs low you will see it here.',
+    'hp.why.threshold': 'quota reached the hand-over level',
+    'hp.why.limit': 'it hit its usage limit',
+    'hp.why.manual': 'handed over on request',
+    'hp.missing': 'One step left',
+    'hp.complete': 'Finish setting up',
+    'hp.onlySideby': 'Only sessions started with sideby hand over (a short command such as cc001, or sideby run). Typing claude directly does not.',
+    'hp.sameConfirm': 'Switch it on',
+    'hp.sameOn': 'Same-tool hand-over is on.',
+    'hp.sameOff': 'Same-tool hand-over is off.',
     'page.accounts': 'Accounts',
     'page.tuning': 'Context tuning',
     'tune.title': 'Context tuning',
@@ -617,6 +665,54 @@ const zh = {
     'menu.check': '检查这个账号',
     'menu.like': '照此新建账号',
     'menu.tune': '上下文调优',
+    'page.handoff': '自动交接',
+    'hp.title': '自动交接',
+    'hp.advanced': '高级设置',
+    'hp.loading': '检查中…',
+    'hp.intro': '账号额度快用完时，你的工作会自动换到下一个账号接着做，不用你操心。',
+    'hp.how1': '你照常在用 sideby 启动的会话里工作（短命令如 cc001，或 sideby run）。',
+    'hp.how2': '这个账号用到 {p}% 时，sideby 让 AI 写一份任务小结，然后结束这个会话。',
+    'hp.how3': '倒计时 {s} 秒后（按回车可取消），下一个账号在同一个终端里按小结接着做。',
+    'hp.noStarters': '你的账号里还没有能发起交接的。先添加一个 Claude、Codex 或 Grok 账号。',
+    'hp.sameFamily': '同一个工具的账号之间也切换（例如 cc001 到 cc002）',
+    'hp.turnOn': '一键开启',
+    'hp.turnOff': '关闭',
+    'hp.willDo': '开启时 sideby 会：',
+    'hp.step.config': '在 sideby 的设置里打开自动交接',
+    'hp.step.quota': '打开 {host} 的额度显示（交接要靠它知道用了多少）',
+    'hp.step.hook': '给 {host} 装上 sideby 的交接钩子',
+    'hp.step.copy': '把钩子文件复制到你的其他 {host} 账号（{accounts}），它们的其他文件不动',
+    'hp.showChange': '查看改动',
+    'hp.sameFamilyOffNote': '同一个工具的账号之间不会互相切换，之后可以在本页打开。',
+    'hp.manual.codexTrust': 'Codex 每个账号第一次要信任 sideby 的钩子：第一次启动时在 Codex 里输入 /hooks 并信任，到时 sideby 会提醒你。',
+    'hp.blocked': '暂时不能开启：{why}',
+    'hp.confirmOn': '确认开启',
+    'hp.applying': '正在开启…',
+    'hp.stepFailed': '停在这一步：{step}。{why}',
+    'hp.tryAgain': '它之后的步骤没有执行。可以重试，或找人帮忙。',
+    'hp.onNote': '任一账号用到 {p}% 时，它的会话会自动换到下一个账号。',
+    'hp.takeover': '接下来会交给谁',
+    'hp.used': '已用 {p}%',
+    'hp.noQuota': '额度未知',
+    'hp.goesTo': '到 {p}% 时交给 {to}',
+    'hp.goesToLimit': '撞到用量上限时交给 {to}',
+    'hp.waits': '到上限时会等待：{at} 额度恢复',
+    'hp.waitRule': '如果那时离额度恢复不到 {w} 分钟，就原地等，不换号。',
+    'hp.planChanged': '你查看之后设置有了变化，所以还没有改任何东西。下面是现在要做的改动，请再确认一次。',
+    'hp.none': '现在没有能接手的账号',
+    'hp.noneBack': '现在没有能接手的账号；{ref} 在 {at} 恢复',
+    'hp.noAccounts': '没有能发起交接的订阅账号。',
+    'hp.recent': '最近的交接',
+    'hp.noneYet': '还没有。下次有账号额度快用完时，这里会出现记录。',
+    'hp.why.threshold': '额度到了交接线',
+    'hp.why.limit': '撞到了用量上限',
+    'hp.why.manual': '按你的要求交接',
+    'hp.missing': '还差一步',
+    'hp.complete': '补全设置',
+    'hp.onlySideby': '只有用 sideby 启动的会话才会交接（短命令如 cc001，或 sideby run）。直接敲 claude 启动的不会。',
+    'hp.sameConfirm': '确认打开',
+    'hp.sameOn': '已开启同工具交接。',
+    'hp.sameOff': '已关闭同工具交接。',
     'page.accounts': '账号',
     'page.tuning': '上下文调优',
     'tune.title': '上下文调优',

package/dist/src/panel/page-script.js

@@ -227,6 +227,8 @@ const MAIN = String.raw `
   // tooltip, a focused field, or a text selection in the account list.
   function uiBusy() {
     if (menu.el || (dlg.el && dlg.el.open) || document.querySelector('.tip.is-open')) return true
+    // A plan on the Auto Handoff page, and the change a person opened to read, stay as they are.
+    if (!$('handoff-page').hidden && (hp.preview || hp.askSame || document.querySelector('#handoff-page details[open]'))) return true
     const el = document.activeElement
     if (el && (el.tagName === 'INPUT' || el.tagName === 'TEXTAREA' || el.tagName === 'SELECT' || el.isContentEditable)) return true
     const sel = window.getSelection && window.getSelection()
@@ -894,7 +896,7 @@ const MAIN = String.raw `
     if (!id || (!id.email && !id.org)) return null
     const email = id.email ? emailText(id.email) : ''
     return h('div', { class: 'ident-email', title: [email, id.org].filter(Boolean).join(' · ') },
-      dots([email ? h('span', { class: 'email' }, email) : null, id.org ? h('span', { class: 'org' }, id.org) : null]))
+      dots([email ? h('button', { class: 'email email-btn', type: 'button', title: t('menu.copyEmail'), 'aria-label': t('menu.copyEmail') + ' ' + email, onclick: (e) => { e.stopPropagation(); copyText(id.email) } }, email) : null, id.org ? h('span', { class: 'org' }, id.org) : null]))
   }
   function subLine(a) {
     const plan = a.quota && a.quota.status === 'ok' && a.quota.plan
@@ -1249,7 +1251,8 @@ const MAIN = String.raw `
   // What each card's size menu shows while the user is choosing, by group id; dropped once a change is made.
   const tuneSel = {}
   const tp = { data: null, loading: false, error: null, at: 0 }
-  let curPage = location.hash === '#tuning' ? 'tuning' : 'accounts'
+  function pageFromHash() { return location.hash === '#tuning' ? 'tuning' : location.hash === '#handoff' ? 'handoff' : 'accounts' }
+  let curPage = pageFromHash()
   function tuneSize(n) { return n === null || n === undefined ? t('tune.hostDefault') : tokens(n) }
   function tuneRedraw() {
     if (dlg.kind === 'tune') renderTune()
@@ -1442,25 +1445,37 @@ const MAIN = String.raw `
   function tuningAvailable() { return Boolean(S.state && S.state.families.some((f) => f.tuning)) }
   function setPage(next) {
     curPage = next
-    try { history.replaceState(null, '', next === 'tuning' ? '#tuning' : location.pathname + location.search) } catch {}
+    try { history.replaceState(null, '', next === 'accounts' ? location.pathname + location.search : '#' + next) } catch {}
     renderPageChrome()
   }
   // The page tabs, and which sections show; runs with every render, so a reload or a language switch keeps them.
   function renderPageChrome() {
     const nav = $('pages')
-    const can = tuningAvailable()
-    if (!can && curPage === 'tuning' && S.state) curPage = 'accounts'
-    nav.hidden = !can
-    const tabs = [['accounts', t('page.accounts')], ['tuning', t('page.tuning')]]
+    const canTune = tuningAvailable()
+    const canHandoff = Boolean(ahState())
+    if (S.state && ((curPage === 'tuning' && !canTune) || (curPage === 'handoff' && !canHandoff))) curPage = 'accounts'
+    const tabs = [['accounts', t('page.accounts')]]
+    if (canTune) tabs.push(['tuning', t('page.tuning')])
+    if (canHandoff) tabs.push(['handoff', t('page.handoff')])
+    nav.hidden = tabs.length < 2
     setKids(nav, h('div', { class: 'seg', role: 'presentation' }, tabs.map(([id, label]) =>
       h('button', { class: 'seg-btn', type: 'button', role: 'tab', 'aria-selected': curPage === id ? 'true' : 'false', onclick: () => setPage(id) }, label))))
-    const on = can && curPage === 'tuning'
-    for (const id of ['summary', 'accounts-page', 'checkup']) $(id).hidden = on
-    $('tuning-page').hidden = !on
-    if (on) {
+    const away = curPage !== 'accounts' && tabs.some(([id]) => id === curPage)
+    for (const id of ['summary', 'accounts-page', 'checkup']) $(id).hidden = away
+    const onTune = away && curPage === 'tuning'
+    const onHandoff = away && curPage === 'handoff'
+    $('tuning-page').hidden = !onTune
+    $('handoff-page').hidden = !onHandoff
+    if (onTune) {
       if (!tp.data && !tp.loading && !tp.error) loadTuningPage()
       else renderTuningPage()
     }
+    if (onHandoff) {
+      // A change made elsewhere (Advanced settings, the CLI) makes what the page loaded out of date.
+      const stale = hp.data && (hp.data.settings.auto !== ahState().settings.auto || hp.data.settings.sameFamily !== ahState().settings.sameFamily)
+      if ((!hp.data || stale) && !hp.loading && !hp.error) loadHandoffPage()
+      else renderHandoffPage()
+    }
   }
   async function loadTuningPage() {
     tp.loading = true
@@ -1491,7 +1506,7 @@ const MAIN = String.raw `
     }
     setKids(box, kids)
   }
-  window.addEventListener('hashchange', () => { curPage = location.hash === '#tuning' ? 'tuning' : 'accounts'; renderPageChrome() })
+  window.addEventListener('hashchange', () => { curPage = pageFromHash(); renderPageChrome() })
 
   // New account. The form is built once per opening so typing keeps focus; only its derived parts re-render.
   let nf = null
@@ -1964,6 +1979,192 @@ const MAIN = String.raw `
     if (ah.loading) loadHandoffStatus()
   }
 
+  // ---------- the Auto Handoff page ----------
+  // Off: one sentence and one button. On: where each account's work would go next, the last hand-overs and what is
+  // still missing. Turning on is one plan shown first (hp.preview) and one confirmation; no commands to copy.
+  const hp = { data: null, plan: null, loading: false, error: null, preview: null, previewing: false, applying: false, failed: null, changed: false, sameFamily: false, sameTouched: false, busyOff: false, askSame: false }
+  async function loadHandoffPage() {
+    hp.loading = true
+    hp.error = null
+    renderHandoffPage()
+    try {
+      // What is missing is only worth the check once it is on; while off the button shows the whole plan.
+      const [data, plan] = await Promise.all([api('/api/handoff/overview', {}), ahState().settings.auto ? api('/api/handoff/enable', {}) : Promise.resolve(null)])
+      hp.data = data
+      hp.plan = plan
+    } catch (e) { hp.error = e }
+    hp.loading = false
+    renderHandoffPage()
+  }
+  // Off, the box on this page decides; on, "finish setting up" keeps whatever is set.
+  function hpBody() { return ahState().settings.auto ? {} : { sameFamily: hp.sameFamily } }
+  async function hpPreview() {
+    hp.previewing = true
+    hp.failed = null
+    hp.changed = false
+    renderHandoffPage()
+    try { hp.preview = await api('/api/handoff/enable', hpBody()) } catch (e) { hp.failed = { error: e } }
+    hp.previewing = false
+    renderHandoffPage()
+  }
+  async function hpApply() {
+    hp.applying = true
+    hp.failed = null
+    renderHandoffPage()
+    try {
+      const r = await api('/api/handoff/enable', Object.assign(hpBody(), { confirm: true, expect: hp.preview && hp.preview.key }))
+      const bad = r.results.find((x) => !x.ok)
+      // A plan that changed since it was shown is shown again; one with nothing left to do means it is already on.
+      hp.changed = Boolean(r.changed) && !r.plan.alreadyOn
+      if (hp.changed || r.plan.blocked) hp.preview = r.plan
+      else if (bad) hp.failed = { step: bad, plan: r.plan }
+      else { hp.preview = null; toast(t('toast.ahOn')) }
+      await load({ silent: true })
+      await loadHandoffPage()
+    } catch (e) { hp.failed = { error: e } }
+    hp.applying = false
+    renderHandoffPage()
+  }
+  async function hpChange(change, message) {
+    hp.busyOff = true
+    renderHandoffPage()
+    try {
+      await api('/api/handoff/configure', { change, confirm: true })
+      hp.preview = null
+      hp.askSame = false
+      toast(message)
+      await load({ silent: true })
+      await loadHandoffPage()
+    } catch (e) { hp.failed = { error: e } }
+    hp.busyOff = false
+    renderHandoffPage()
+  }
+  function hpStepTitle(step) {
+    const host = step.family ? family(step.family).title : ''
+    return t('hp.step.' + step.id, { host, accounts: (step.accounts || []).join(', ') })
+  }
+  function hpSteps(plan) {
+    return h('ul', { class: 'hp-steps' }, plan.steps.map((step) => h('li', null, h('div', null,
+      h('div', null, hpStepTitle(step)),
+      step.diff ? h('details', { class: 'small' }, h('summary', null, t('hp.showChange')), h('p', { class: 'muted small' }, tx('ah.changes', { file: h('code', null, step.file) })), diffView(step.diff)) : null))))
+  }
+  function hpManual(plan) {
+    return plan.manual.map((m) => h('p', { class: 'note' }, m.id === 'codex-trust' ? t('hp.manual.codexTrust') : (family(m.family).title + ': ' + (m.message || ''))))
+  }
+  function hpPreviewCard() {
+    const p = hp.preview
+    const kids = [h('h3', { class: 'small' }, t('hp.willDo'))]
+    if (hp.changed) kids.push(h('p', { class: 'note note-warn', role: 'status' }, t('hp.planChanged')))
+    if (p.blocked) kids.push(h('p', { class: 'note note-fail' }, t('hp.blocked', { why: p.blocked })), codeCopy('npm i -g sideby'))
+    else {
+      kids.push(hpSteps(p), ...hpManual(p))
+      kids.push(p.sameFamily ? h('p', { class: 'note note-warn' }, t('ah.sameFamilyWarn')) : h('p', { class: 'muted small' }, t('hp.sameFamilyOffNote')))
+    }
+    const foot = [h('button', { class: 'btn', type: 'button', disabled: hp.applying, onclick: () => { hp.preview = null; hp.failed = null; hp.changed = false; renderHandoffPage() } }, t('btn.cancel'))]
+    if (!p.blocked) foot.push(h('button', { class: 'btn btn-primary', type: 'button', disabled: hp.applying, 'aria-busy': hp.applying ? 'true' : null, onclick: hpApply }, hp.applying ? spinner() : null, hp.applying ? t('hp.applying') : t('hp.confirmOn')))
+    kids.push(h('div', { class: 'row-actions' }, foot))
+    return h('div', { class: 'ah-fam' }, kids)
+  }
+  function hpFailed() {
+    const f = hp.failed
+    if (!f) return null
+    if (f.error) return errorNote(f.error, null)
+    return h('p', { class: 'note note-fail', role: 'alert' }, t('hp.stepFailed', { step: hpStepTitle(f.step), why: f.step.message || '' }) + ' ' + t('hp.tryAgain'))
+  }
+  function hpDecision(d, starts) {
+    const thr = ahState().settings.threshold
+    if (d.kind === 'pick') return starts.includes('quota') ? t('hp.goesTo', { to: accountLabel(d.ref), p: thr }) : t('hp.goesToLimit', { to: accountLabel(d.ref) })
+    if (d.kind === 'wait') return t('hp.waits', { at: clock(d.until) })
+    return d.earliestReset ? t('hp.noneBack', { ref: accountLabel(d.earliestReset.ref), at: clock(d.earliestReset.at) }) : t('hp.none')
+  }
+  // The one case where reaching the threshold does not switch (spec §3.17 "选号" 1); none when waiting is off.
+  function hpWaitRule(st) {
+    const w = st.settings.waitIfResetWithinMinutes
+    return w > 0 ? ' ' + t('hp.waitRule', { w }) : null
+  }
+  function hpRows(d) {
+    if (!d.takeover.length) return h('p', { class: 'muted small' }, t('hp.noAccounts'))
+    return h('ul', { class: 'hp-rows' }, d.takeover.map((r) => {
+      const a = S.state.accounts.find((x) => x.ref === r.ref)
+      const p = a ? quotaPressure(a, Date.now()) : -1
+      return h('li', null,
+        h('span', { class: 'title-logo' }, badge(r.family, 'sm'), h('b', { class: 'mono' }, accountLabel(r.ref))),
+        h('span', { class: 'muted' }, p >= 0 ? t('hp.used', { p: Math.round(p) }) : t('hp.noQuota')),
+        h('span', null, hpDecision(r.decision, r.starts)))
+    }))
+  }
+  function hpRecent(d) {
+    if (!d.recent.length) return h('p', { class: 'muted small' }, t('hp.noneYet'))
+    return h('ul', { class: 'hp-rows' }, d.recent.map((r) => h('li', null,
+      h('span', { class: 'mono' }, accountLabel(r.from) + ' → ' + accountLabel(r.to)),
+      h('span', { class: 'muted' }, clock(r.at) + ' · ' + ago(r.at)),
+      h('span', { class: 'muted' }, r.trigger ? t('hp.why.' + r.trigger) : ''))))
+  }
+  function hpSameFamilyBox(checked, onchange) {
+    const input = h('input', { type: 'checkbox', disabled: BOOT.readOnly || hp.busyOff || hp.applying })
+    input.checked = checked
+    input.addEventListener('change', () => onchange(input.checked))
+    return h('div', { class: 'check-row' }, h('label', { class: 'check' }, input, h('span', null, h('b', null, t('hp.sameFamily')), h('span', { class: 'muted small' }, t('ah.sameFamilyWarn')))))
+  }
+  function renderHandoffPage() {
+    const box = $('handoff-page')
+    if (box.hidden || !S.state) return
+    const st = ahState()
+    if (!st) return
+    const kids = [h('div', { class: 'section-head' },
+      h('h2', { id: 'h-handoff' }, t('hp.title')),
+      h('div', { class: 'row-actions' },
+        h('button', { class: 'btn btn-sm', type: 'button', onclick: openHandoff }, t('hp.advanced')),
+        h('button', { class: 'btn btn-sm', type: 'button', disabled: hp.loading, onclick: loadHandoffPage }, hp.loading ? spinner() : icon('refresh'), t('top.refresh'))))]
+    const on = st.settings.auto
+    if (hp.loading && !hp.data) kids.push(h('p', { class: 'muted' }, spinner(), ' ', t('hp.loading')))
+    if (hp.error) kids.push(errorNote(hp.error, loadHandoffPage))
+    if (BOOT.readOnly) kids.push(h('p', { class: 'note' }, t('banner.readOnly')))
+    if (!on) {
+      kids.push(h('p', null, t('hp.intro')))
+      kids.push(h('ol', { class: 'hp-how' }, h('li', null, t('hp.how1')), h('li', null, t('hp.how2', { p: st.settings.threshold }), hpWaitRule(st)), h('li', null, t('hp.how3', { s: st.settings.countdownSeconds }))))
+      if (!S.state.accounts.some((a) => a.kind !== 'api' && st.starters.includes(a.family))) kids.push(h('p', { class: 'note' }, t('hp.noStarters')))
+      else {
+        if (!hp.preview) {
+          // Until the person touches the box it shows what is set now, so turning on again keeps an earlier choice.
+          if (!hp.sameTouched) hp.sameFamily = st.settings.sameFamily
+          kids.push(hpSameFamilyBox(hp.sameFamily, (v) => { hp.sameFamily = v; hp.sameTouched = true }))
+          kids.push(h('div', { class: 'row-actions' }, h('button', { class: 'btn btn-primary', type: 'button', disabled: BOOT.readOnly || hp.previewing, 'aria-busy': hp.previewing ? 'true' : null, onclick: hpPreview }, hp.previewing ? spinner() : null, t('hp.turnOn'))))
+        } else kids.push(hpPreviewCard())
+      }
+    } else {
+      kids.push(h('p', null, h('span', { class: 'chip chip-ok' }, t('ah.on')), ' ', t('hp.onNote', { p: st.settings.threshold }), hpWaitRule(st)))
+      const d = hp.data
+      if (d) {
+        kids.push(h('h3', { class: 'small' }, t('hp.takeover')), hpRows(d))
+        kids.push(h('h3', { class: 'small' }, t('hp.recent')), hpRecent(d))
+      }
+      const plan = hp.plan
+      if (plan && (plan.blocked || plan.steps.length)) {
+        kids.push(h('h3', { class: 'small' }, t('hp.missing')))
+        if (!hp.preview) {
+          if (plan.blocked) kids.push(h('p', { class: 'note note-fail' }, t('hp.blocked', { why: plan.blocked })), codeCopy('npm i -g sideby'))
+          else {
+            kids.push(hpSteps(plan))
+            kids.push(h('div', { class: 'row-actions' }, h('button', { class: 'btn btn-primary', type: 'button', disabled: BOOT.readOnly || hp.previewing, onclick: hpPreview }, hp.previewing ? spinner() : null, t('hp.complete'))))
+          }
+        } else kids.push(hpPreviewCard())
+      } else if (plan) kids.push(...hpManual(plan))
+      kids.push(h('p', { class: 'muted small' }, t('hp.onlySideby')))
+      kids.push(hpSameFamilyBox(st.settings.sameFamily, (v) => {
+        if (v) { hp.askSame = true; renderHandoffPage() } else { hp.askSame = false; hpChange({ sameFamily: false }, t('hp.sameOff')) }
+      }))
+      if (hp.askSame && !st.settings.sameFamily) kids.push(h('div', { class: 'ah-fam' },
+        h('p', { class: 'note note-warn' }, t('ah.sameFamilyWarn')),
+        h('div', { class: 'row-actions' },
+          h('button', { class: 'btn', type: 'button', disabled: hp.busyOff, onclick: () => { hp.askSame = false; renderHandoffPage() } }, t('btn.cancel')),
+          h('button', { class: 'btn btn-primary', type: 'button', disabled: BOOT.readOnly || hp.busyOff, onclick: () => { hp.askSame = false; hpChange({ sameFamily: true }, t('hp.sameOn')) } }, t('hp.sameConfirm')))))
+      kids.push(h('div', { class: 'row-actions' }, h('button', { class: 'btn', type: 'button', disabled: BOOT.readOnly || hp.busyOff, onclick: () => hpChange({ auto: false }, t('toast.ahOff')) }, hp.busyOff ? spinner() : null, t('hp.turnOff'))))
+    }
+    kids.push(hpFailed())
+    setKids(box, kids)
+  }
+
   // ---------- banners ----------
   function renderBanners() {
     const out = []
@@ -1976,7 +2177,7 @@ const MAIN = String.raw `
       if (hint) out.push(h('div', { class: 'banner', role: 'status' },
         h('div', null, t('ah.hint', { ref: hint.ref, p: hint.pressure })),
         h('div', { class: 'banner-actions' },
-          h('button', { class: 'btn btn-sm btn-primary', type: 'button', onclick: openHandoff }, t('ah.setUp')),
+          h('button', { class: 'btn btn-sm btn-primary', type: 'button', onclick: () => setPage('handoff') }, t('ah.setUp')),
           h('button', { class: 'btn btn-sm', type: 'button', onclick: () => { prefs.ahHintAt = Date.now(); savePrefs(); renderBanners() } }, t('ah.dismiss')))))
       const errs = S.state.pluginErrors
       if (errs.length) out.push(h('div', { class: 'banner banner-warn', role: 'status' }, h('div', null,
@@ -2061,7 +2262,7 @@ const MAIN = String.raw `
   // ---------- start ----------
   $('ver').textContent = BOOT.version ? 'v' + BOOT.version : ''
   $('refresh').addEventListener('click', () => load({ check: true, announce: true }))
-  $('handoff').addEventListener('click', openHandoff)
+  $('handoff').addEventListener('click', () => setPage('handoff'))
   $('lang').addEventListener('click', () => {
     if (LANG_FIXED) return
     lang = lang === 'zh' ? 'en' : 'zh'

package/dist/src/panel/page-styles.js

@@ -167,6 +167,9 @@ code, .mono { font-family: var(--mono); font-size: 0.92em; }
 .ident-name { display: flex; align-items: center; gap: 6px; min-width: 0; flex-wrap: wrap; row-gap: 3px; }
 .ident-name .name { font-weight: var(--strong-weight); font-size: var(--font-size); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; max-width: 100%; }
 .ident-email { color: var(--muted); font-size: 12px; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; margin-top: 1px; }
+.email-btn { all: unset; cursor: pointer; border-radius: 4px; }
+.email-btn:hover { color: var(--text); text-decoration: underline dotted; }
+.email-btn:focus-visible { outline: var(--focus-outline); outline-offset: 2px; }
 .ident-email + .ident-sub { color: var(--faint); margin-top: 0; }
 .tools .tb-icon { width: var(--ctl-h); height: var(--ctl-h); border-color: var(--border-strong); background: var(--surface); }
 .tools .tb-icon:hover { background: var(--hover); }
@@ -335,6 +338,15 @@ a.btn:hover { text-decoration: none; }
 .banner-warn { background: var(--warn-soft); border-color: transparent; color: var(--warn); }
 .banner ul { margin: 6px 0 0; padding-left: 18px; }
 .banner-actions { display: flex; gap: 8px; flex: none; }
+.hp-how { margin: 0; padding-left: 20px; display: flex; flex-direction: column; gap: 4px; }
+.hp-steps { list-style: none; margin: 0; padding: 0; display: flex; flex-direction: column; gap: 8px; }
+.hp-steps li { display: flex; gap: 8px; }
+.hp-steps li::before { content: '•'; color: var(--muted); }
+.hp-steps li > div { flex: 1; min-width: 0; }
+.hp-rows { list-style: none; margin: 0; padding: 0; display: flex; flex-direction: column; }
+.hp-rows li { display: flex; flex-wrap: wrap; align-items: center; gap: 4px 14px; padding: 8px 0; border-bottom: 1px solid var(--border); }
+.hp-rows li:last-child { border-bottom: 0; }
+#handoff-page > * + * { margin-top: 12px; }
 .ah-grid { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 12px; align-items: end; }
 .tune-model { border: 1px solid var(--border); border-radius: calc(var(--radius) - 4px); padding: 10px 12px; display: flex; flex-direction: column; gap: 8px; }
 .tune-head { display: flex; align-items: baseline; justify-content: space-between; gap: 8px; flex-wrap: wrap; }

package/dist/src/panel/page.js

@@ -76,6 +76,7 @@ export function renderPage(opts) {
   <div id="banners"></div>
   <nav id="pages" class="pages" role="tablist" hidden></nav>
   <section id="summary" class="summary" aria-busy="true">${SKELETON_STAT.repeat(4)}</section>
+  <section id="handoff-page" class="block" aria-labelledby="h-handoff" hidden></section>
   <section id="tuning-page" class="block" aria-labelledby="h-tuning" hidden></section>
   <section id="accounts-page" class="block" aria-labelledby="h-accounts">
     <div class="section-head acct-head"><h2 id="h-accounts"><span data-i18n="acct.title">Accounts</span><span id="acct-count" class="muted small"></span></h2></div>

package/dist/src/quota/statusline-tap.js

@@ -4,7 +4,7 @@
 // Nothing about the cache may change what the original command receives, prints or returns.
 import { spawn } from 'node:child_process';
 import { constants } from 'node:os';
-import { accountNameFromEnv, cacheStateDir, parseRateLimits, writeQuotaCache, } from '../families/claude/quota-cache.js';
+import { accountNameFromEnv, cacheStateDir, mergeQuotaCache, parseRateLimits, readQuotaCache, writeQuotaCache, } from '../families/claude/quota-cache.js';
 /** Command the wrapper starts with; `quota setup claude` detects an existing wrapper by this prefix. */
 export const TAP_COMMAND = 'sideby statusline-tap';
 export const ORIG_FLAG = '--orig-b64';
@@ -88,7 +88,18 @@ export async function runStatuslineTap(argv, env, stdin, stdout, stderr = proces
             const name = accountNameFromEnv(env);
             if (!cache || !name)
                 return;
-            await writeQuotaCache(cacheStateDir(env), name, cache);
+            // Several sessions of one Account share this cache; an idle one must not put back older numbers.
+            const stateDir = cacheStateDir(env);
+            const prev = await readQuotaCache(stateDir, name).catch(() => null);
+            const merged = prev?.status === 'ok' ? mergeQuotaCache(prev.windows, cache) : cache;
+            if (!merged) {
+                // Older numbers: write nothing, and show what the cache already knows.
+                if (prev?.status === 'ok')
+                    cache = { ...cache, observedAt: prev.observedAt, windows: prev.windows };
+                return;
+            }
+            cache = merged;
+            await writeQuotaCache(stateDir, name, merged);
         }
         catch {
             // Caching is best effort.

package/dist/src/runtime.d.ts

@@ -218,9 +218,12 @@ export interface Runtime {
     handoffSettings(): HandoffSettings;
     /**
      * Where an Auto Handoff from `origin` would go now (spec §3.17 "选号"): every Account of every Family is a
-     * candidate; `used` lists the chain's Accounts so far.
+     * candidate; `used` lists the chain's Accounts so far. `ahead` decides early what happens once the origin's fullest
+     * window reaches the threshold, as plan.json and the Panel need.
      */
-    handoffDecision(origin: Account, used: readonly string[]): Promise<HandoffDecision>;
+    handoffDecision(origin: Account, used: readonly string[], opts?: {
+        ahead?: boolean;
+    }): Promise<HandoffDecision>;
     readContext(): ReadContext;
 }
 export declare class UnknownFamilyError extends UserError {

package/dist/src/runtime.js

@@ -561,7 +561,7 @@ export async function createRuntime(opts = {}) {
             return planHandoff(f.id, candidates, readContext().now, o);
         },
         handoffSettings: () => handoffSettings(config),
-        async handoffDecision(origin, used) {
+        async handoffDecision(origin, used, opts = {}) {
             const candidates = await Promise.all((await accounts()).map(async (a) => {
                 const f = familyOf(a.family);
                 const [installed, login, quota, identity] = await Promise.all([
@@ -601,6 +601,7 @@ export async function createRuntime(opts = {}) {
                 aliases: aliasRefs(config.aliases),
                 used,
                 now: now(),
+                ...(opts.ahead ? { ahead: true } : {}),
             });
         },
         readContext,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sideby",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "Run work, personal and API-key accounts at the same time, without their configs drifting apart.",
   "license": "MIT",
   "author": "Adonis0123 (https://github.com/Adonis0123)",

package/skills/sideby/SKILL.md

@@ -2,7 +2,7 @@
 name: sideby
 description: Use when the user runs, or wants to run, several AI coding accounts (Claude Code, Codex, Grok Build, pi) side by side. Covers installing sideby and setting up a new account ("install sideby", "set up another Claude account", "add cc008", "配置一个 cc00x", "再加一个 Codex 账号"), explaining what accounts share and what stays separate ("what do my accounts share?", "这些账号共享了什么"), showing which account a session is ("show [cc001] in the status line", "加上账号标识"), seeing accounts, quota and usage, moving on when one hits its 5-hour or weekly limit, adding a short command (alias), and repairing drifted account directories (skills, hooks, rules or settings not shared, wrong symlinks, credential file permissions). Drives the `sideby` CLI with `--json`; the agent does every step except browser sign-in, filling in secrets and starting interactive sessions, which it hands to the user as one command.
 metadata:
-  version: "0.4.2"
+  version: "0.5.0"
   requires:
     bins: [sideby, node]
   cliHelp: sideby --help

package/skills/sideby/references/handoff.md

@@ -39,7 +39,7 @@ Use this when the user says an account hit its 5-hour or weekly limit ("usage li
 
 With config `"handoff": { "auto": true }`, a session sideby started hands its task to the next account when quota runs low; see the guide's Auto Handoff section for the settings. If you are in such a session (the environment has `SIDEBY_HANDOFF_RUN`):
 
-- When sideby tells you the quota is at 80%, write the handoff brief at the path it names and keep it current: the goal, what is done, the remaining steps, key decisions and why, the files that matter. Reference specs, ADRs, commits and diffs by path; list the skills the next agent should use; never include keys, passwords or personal data.
+- When sideby tells you the quota is at 80%, write the handoff brief at the path it names and keep it current (do not tell the user that another account will take over; sideby decides that and says so itself): the goal, what is done, the remaining steps, key decisions and why, the files that matter. Reference specs, ADRs, commits and diffs by path; list the skills the next agent should use; never include keys, passwords or personal data.
 - When it says the quota is at 95%, finish the current step, update the brief, and end your turn. sideby starts the next account from it.
 - When the user asks to hand over now, update the brief, run `sideby handoff ready` (add `--brief <file>` when the user's own handoff tool wrote one), and end your turn.
 
@@ -51,7 +51,7 @@ With config `"handoff": { "auto": true }`, a session sideby started hands its ta
 4. Work through `nextSteps` in order. `sideby quota setup claude` and `sideby handoff setup grok` also exit 10 first: ask before adding `--yes`. `npm i -g sideby` installs or upgrades sideby on PATH; ask first. Codex needs the user to trust sideby's hooks once per account (`/hooks` in Codex); you cannot do that for them.
 5. Run `sideby handoff status --json` again and report which families are `ready`.
 
-To turn it off: `sideby handoff disable --json`, then `--yes` after the user agrees; the other settings stay. The panel has the same settings under **Auto Handoff** in its top bar.
+To turn it off: `sideby handoff disable --json`, then `--yes` after the user agrees; the other settings stay. The panel's **Auto Handoff** page does all of this in one click (turn on, with one confirmation; turn off) and shows where each account's work goes next; for a user who is not in a terminal, point them there instead of walking through the commands.
 
 ## Picking an account for a subtask