sideby 0.9.0 → 0.9.2

package/dist/build.json

@@ -1 +1 @@
-{"id":"20261015T030631-4ed31c"}
+{"id":"20261015T120149-abb6bb"}

package/dist/src/cli/commands.js

@@ -733,17 +733,23 @@ export async function cmdHandoff(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]');
+        throw new UsageError('usage: sideby handoff status | enable [--same-family] [--order <family>=<acct,…>] [--threshold n] [--prepare-at n] [--yes] | disable [--yes] | ready [--to <account>] [--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);
+    const toFlag = a.flags.get('to');
+    if (toFlag === true)
+        throw new UsageError('usage: sideby handoff ready --to <account> [--brief <file>]');
+    const rt = await createRuntime();
+    // An Account or a short command; resolve() says what to do when there is no such Account.
+    const to = toFlag === undefined ? undefined : (await rt.resolve(toFlag)).ref;
+    const decision = await readyDecision(rt, process.env, to);
     if (decision && decision.kind !== 'pick')
-        throw new UserError(`nothing can take over now: ${explain(decision)}; keep working in this account`, {
-            code: 'no-pick',
-        });
+        throw new UserError(to
+            ? `cannot hand over to ${to}: ${explain(decision)}; keep working in this account or pick another with --to`
+            : `nothing can take over now: ${explain(decision)}; keep working in this account`, { code: 'no-pick' });
     let request;
     try {
-        request = await requestHandoff(process.env, brief);
+        request = await requestHandoff(process.env, brief, to);
     }
     catch (err) {
         throw new UserError(`cannot read the brief ${brief}: ${err.message}; check the path and retry`, {
@@ -752,10 +758,16 @@ export async function cmdHandoff(a, io) {
     }
     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' });
+    // The account that will really take over; `sideby next` cannot tell, it does not know the chain.
+    const next = decision?.kind === 'pick' ? decision.ref : undefined;
     if (a.flags.has('json'))
-        json(io, { requested: true, ...(request.brief ? { brief: request.brief } : {}) });
+        json(io, {
+            requested: true,
+            ...(next ? { next } : {}),
+            ...(request.brief ? { brief: request.brief } : {}),
+        });
     else
-        io.out('The next account starts when this turn ends; finish the turn now.');
+        io.out(`${next ? `${next} takes over` : 'The next account starts'} when this turn ends; finish the turn now.`);
     return 0;
 }
 export async function cmdPlugins(a, io) {

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

@@ -351,7 +351,12 @@ export const OUTPUT_SCHEMAS = {
             nextSteps: Type.Array(Str),
         }, { title: `sideby handoff ${sub} --json` }),
     ])),
-    'handoff-ready': Type.Object({ schemaVersion: Version, requested: Type.Literal(true), brief: Type.Optional(Str) }, { title: 'sideby handoff ready --json' }),
+    'handoff-ready': Type.Object({
+        schemaVersion: Version,
+        requested: Type.Literal(true),
+        next: Type.Optional(Str),
+        brief: Type.Optional(Str),
+    }, { title: 'sideby handoff ready --json' }),
     'handoff-setup': Type.Object({ schemaVersion: Version, family: Str, applied: Type.Boolean(), plan: QuotaSetupPlan }, { title: 'sideby handoff setup --json' }),
     'handoff-teardown': Type.Object({ schemaVersion: Version, family: Str, ok: Type.Boolean(), message: Str, diff: Type.Optional(Str) }, { title: 'sideby handoff teardown --json' }),
     'quota-teardown': Type.Object({ schemaVersion: Version, family: Str, ok: Type.Boolean(), message: Str, diff: Type.Optional(Str) }, { title: 'sideby quota teardown --json' }),

package/dist/src/cli/main.js

@@ -39,7 +39,8 @@ Usage:
                                       --order claude=codex001,cc002, --threshold n, --prepare-at n
   sideby handoff disable [--yes]      turn it off, keeping the other settings
   sideby handoff ready [--brief <f>]  inside a session sideby started with Auto Handoff: hand over to
-                                      the next account when this turn ends (config \`handoff\`)
+                                      the next account when this turn ends (config \`handoff\`);
+                                      --to <account> names it, also one this chain already used
   sideby handoff setup grok [--yes]   add sideby's hook file so Grok can hand over at its limit
   sideby handoff teardown grok        remove it
   sideby ui [--port n] [--no-open]    open the local panel
@@ -180,7 +181,7 @@ const COMMANDS = {
     model: { flags: ['json', 'yes'], valued: ['effort'] },
     handoff: {
         flags: ['json', 'yes', 'same-family', 'no-same-family'],
-        valued: ['brief', 'order', 'prepare-at', 'threshold', 'wait-minutes', 'countdown'],
+        valued: ['brief', 'to', 'order', 'prepare-at', 'threshold', 'wait-minutes', 'countdown'],
     },
     ui: { flags: ['no-open', 'background', 'stop', 'serve-detached'], valued: ['port'] },
     app: { flags: ['json'], valued: ['url'] },

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

@@ -35,6 +35,8 @@ export interface ReadyFile {
     /** The Brief file, when the session or the user wrote one. */
     brief?: string;
     briefSource?: 'agent' | 'user';
+    /** `sideby handoff ready --to`: the Account ref to hand over to. */
+    to?: string;
     sessionId?: string;
     transcriptPath?: string;
 }
@@ -68,7 +70,8 @@ export declare function readJsonFile<T>(path: string): Promise<T | null>;
 export declare function writeJsonFile(path: string, value: unknown): Promise<void>;
 /**
  * `sideby handoff ready` (spec §3.17): asks the parent to hand over after this turn. Works only inside a run sideby
- * started with Auto Handoff; `briefFile`, when given, is copied into the chain directory (mode 600).
+ * started with Auto Handoff; `briefFile`, when given, is copied into the chain directory (mode 600); `to` is the
+ * Account ref to hand over to.
  * Returns the request, or null outside such a run.
  */
-export declare function requestHandoff(env: Readonly<Record<string, string | undefined>>, briefFile?: string): Promise<ReadyFile | null>;
+export declare function requestHandoff(env: Readonly<Record<string, string | undefined>>, briefFile?: string, to?: string): Promise<ReadyFile | null>;

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

@@ -50,10 +50,11 @@ export async function writeJsonFile(path, value) {
 }
 /**
  * `sideby handoff ready` (spec §3.17): asks the parent to hand over after this turn. Works only inside a run sideby
- * started with Auto Handoff; `briefFile`, when given, is copied into the chain directory (mode 600).
+ * started with Auto Handoff; `briefFile`, when given, is copied into the chain directory (mode 600); `to` is the
+ * Account ref to hand over to.
  * Returns the request, or null outside such a run.
  */
-export async function requestHandoff(env, briefFile) {
+export async function requestHandoff(env, briefFile, to) {
     const runId = env[HANDOFF_ENV.run];
     const dir = env[HANDOFF_ENV.dir];
     if (!runId || !dir)
@@ -68,6 +69,7 @@ export async function requestHandoff(env, briefFile) {
         at: new Date().toISOString(),
         trigger: 'manual',
         ...(brief ? { brief, briefSource: 'user' } : {}),
+        ...(to ? { to } : {}),
     };
     await writeJsonFile(join(dir, FILES.request), request);
     return request;

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

@@ -28,6 +28,6 @@ opts?: {
 }): Promise<number | null>;
 /**
  * For `sideby handoff ready`: where a Handoff from the session running under `env` would go now, using the chain's
- * Accounts so far; null when `env` is not a run sideby started with Auto Handoff.
+ * Accounts so far (or to `to` only); null when `env` is not a run sideby started with Auto Handoff.
  */
-export declare function readyDecision(rt: Runtime, env: Env): Promise<HandoffDecision | null>;
+export declare function readyDecision(rt: Runtime, env: Env, to?: string): Promise<HandoffDecision | null>;

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

@@ -131,9 +131,9 @@ export function hookEntryWorks(env) {
     });
 }
 /** The decision, or `none` with the reason when sideby cannot tell (an account removed mid-chain, say). */
-async function decide(rt, account, used) {
+async function decide(rt, account, used, to) {
     try {
-        return await rt.handoffDecision(account, used);
+        return await rt.handoffDecision(account, used, to !== undefined ? { to } : {});
     }
     catch (err) {
         return { kind: 'none', reason: err.message };
@@ -258,7 +258,7 @@ opts = {}) {
             return outcome.code;
         }
         // Nothing to move on to (or better to wait): leave the session alone and say why once it ends.
-        const decision = await decide(rt, account, used);
+        const decision = await decide(rt, account, used, outcome.ready.to);
         if (decision.kind !== 'pick') {
             await rm(join(dir, FILES.ready), { force: true });
             const code = await host.exited;
@@ -319,7 +319,7 @@ opts = {}) {
         hop = {
             ref: next.ref,
             args: next.family === account.family ? h.continueArgs(hop.args) : [],
-            prompt: firstPrompt(account.ref, done.path),
+            prompt: firstPrompt(account.ref, done.path, ready.trigger),
         };
         n++;
     }
@@ -340,14 +340,14 @@ async function noteUnhandedHighQuota(rt, account, used, threshold, io) {
 }
 /**
  * For `sideby handoff ready`: where a Handoff from the session running under `env` would go now, using the chain's
- * Accounts so far; null when `env` is not a run sideby started with Auto Handoff.
+ * Accounts so far (or to `to` only); null when `env` is not a run sideby started with Auto Handoff.
  */
-export async function readyDecision(rt, env) {
+export async function readyDecision(rt, env, to) {
     const dir = env[HANDOFF_ENV.dir];
     const ref = env.SIDEBY_ACCOUNT;
     if (!env[HANDOFF_ENV.run] || !dir || !ref)
         return null;
     const account = await rt.resolve(ref);
     const chain = await readJsonFile(join(dir, FILES.chain));
-    return decide(rt, account, chain?.hops.map((h) => h.ref) ?? [account.ref]);
+    return decide(rt, account, chain?.hops.map((h) => h.ref) ?? [account.ref], to);
 }

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

@@ -50,4 +50,9 @@ export declare function selectNext(input: {
     now: Date;
     /** Decide now what happens when the origin's fullest window reaches the threshold (see `waitUntil`). */
     ahead?: boolean;
+    /**
+     * `sideby handoff ready --to`: the only candidate, which may be an Account this chain already used (handing back to
+     * an Account whose Quota came back); every other rule still applies.
+     */
+    to?: string;
 }): HandoffDecision;

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

@@ -52,13 +52,19 @@ function stateOf(c, s, now) {
 }
 export function selectNext(input) {
     const { origin, settings: s, now } = input;
+    const refOf = (name) => input.aliases[name] ?? name;
+    const byRef = new Map(input.candidates.map((c) => [c.ref, c]));
+    if (input.to !== undefined) {
+        const target = byRef.get(refOf(input.to));
+        if (!target)
+            return { kind: 'none', reason: `${input.to} is not an account sideby can find` };
+        return toTarget(origin, target, s, new Set(s.crossOrganization.map(refOf)), now);
+    }
     const until = waitUntil(origin, s, now, input.ahead === true);
     if (until)
         return { kind: 'wait', until };
-    const refOf = (name) => input.aliases[name] ?? name;
     const allowed = new Set(s.crossOrganization.map(refOf));
     const used = new Set([origin.ref, ...input.used]);
-    const byRef = new Map(input.candidates.map((c) => [c.ref, c]));
     const family = s.families[origin.family];
     let list;
     if (family?.policy === 'order') {
@@ -100,3 +106,32 @@ export function selectNext(input) {
         ...withSkipped,
     };
 }
+/** Why `target` may not take over from `origin`, or null when it may; the same rules as `selectNext` but `used`. */
+function refusal(origin, target, s, allowed) {
+    if (target.ref === origin.ref)
+        return 'it is the account this session runs in';
+    if (origin.sameLogin?.includes(target.ref))
+        return `it is the same login as ${origin.ref}, so it shares the same quota`;
+    if (!target.installed)
+        return 'its host is not installed';
+    if (!target.receive)
+        return 'it cannot take over a task';
+    if (!s.sameFamily && target.family === origin.family && target.kind !== 'api')
+        return 'handing over within one host is off; turn on `handoff.sameFamily`';
+    if (!allowed.has(target.ref) && !sameOrganization(origin.identity, target.identity))
+        return `it is signed in to another organization; add it to \`handoff.crossOrganization\` to allow it`;
+    return null;
+}
+function toTarget(origin, target, s, allowed, now) {
+    const why = refusal(origin, target, s, allowed);
+    if (why)
+        return { kind: 'none', reason: `${target.ref} may not take over: ${why}` };
+    const e = stateOf(target, s, now);
+    if (e.state === 'ready' || e.state === 'unknown' || e.state === 'api')
+        return { kind: 'pick', ref: target.ref };
+    return {
+        kind: 'none',
+        reason: `${target.ref} cannot take over now: ${e.state === 'full' ? 'its quota is full' : 'it is signed out'}`,
+        ...(e.state === 'full' && e.resetsAt ? { earliestReset: { ref: target.ref, at: e.resetsAt } } : {}),
+    };
+}

package/dist/src/core/model-choice.js

@@ -6,12 +6,14 @@ import { editConfigAccounts } from './config.js';
 import { UserError } from './errors.js';
 import { lineDiff } from './handoff-status.js';
 function pick(key, sideby, host, last) {
+    // What the Account really ran last beats the Host's default: subscription Accounts often share one settings.json,
+    // so its value would show the same for all of them.
     if (sideby[key])
         return { value: sideby[key], from: 'sideby' };
-    if (host[key])
-        return { value: host[key], from: 'host' };
     if (last[key])
         return { value: last[key], from: 'last' };
+    if (host[key])
+        return { value: host[key], from: 'host' };
     return undefined;
 }
 /** `last` is the model and effort of the newest session, from the usage reader when the caller already has it. */

package/dist/src/handoff/messages.d.ts

@@ -3,5 +3,11 @@ export declare function thresholdMessage(brief: string, pressure: number): strin
 /** At the threshold when the session cannot write a Brief: sideby puts one together from its records. */
 export declare function endTurnMessage(pressure: number): string;
 export declare function stopMessage(brief: string): string;
+declare const WHY: {
+    readonly threshold: 'its quota ran low';
+    readonly limit: 'its quota ran out';
+    readonly manual: 'the user asked to hand over';
+};
 /** The next session's first prompt: the Brief's path only, never its text (it would show in a process list). */
-export declare function firstPrompt(fromRef: string, brief: string): string;
+export declare function firstPrompt(fromRef: string, brief: string, trigger: keyof typeof WHY): string;
+export {};

package/dist/src/handoff/messages.js

@@ -21,7 +21,12 @@ export function endTurnMessage(pressure) {
 export function stopMessage(brief) {
     return `sideby: before you stop, update the handoff brief at ${brief} (${TEMPLATE}; ${RULES}), then end your turn.`;
 }
+const WHY = {
+    threshold: 'its quota ran low',
+    limit: 'its quota ran out',
+    manual: 'the user asked to hand over',
+};
 /** The next session's first prompt: the Brief's path only, never its text (it would show in a process list). */
-export function firstPrompt(fromRef, brief) {
-    return `This task was handed over from ${fromRef} by sideby because its quota ran low. Read ${brief} first, then continue the task it describes.`;
+export function firstPrompt(fromRef, brief, trigger) {
+    return `This task was handed over from ${fromRef} by sideby because ${WHY[trigger]}. Read ${brief} first, then continue the task it describes. If the user asks to move the task to another account (back to ${fromRef}, say), run \`sideby handoff ready --to <account>\` and end your turn.`;
 }

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

@@ -256,6 +256,7 @@ declare const en: {
     'md.from.sideby': string;
     'md.from.host': string;
     'md.from.last': string;
+    'md.newDefault': string;
     'md.none': string;
     'md.click': string;
     'md.envNote': string;

package/dist/src/panel/i18n.js

@@ -258,6 +258,7 @@ const en = {
     'md.from.sideby': 'set by sideby for this account',
     'md.from.host': 'from {host}’s settings',
     'md.from.last': 'used in the last session',
+    'md.newDefault': 'new sessions start with {value} ({from})',
     'md.none': 'not known yet',
     'md.click': 'Click to change.',
     'md.envNote': 'ANTHROPIC_MODEL or CLAUDE_CODE_EFFORT_LEVEL in your shell, and settings from your organization, override this; sideby cannot see them.',
@@ -720,6 +721,7 @@ const zh = {
     'md.from.sideby': 'sideby 为这个账号设置',
     'md.from.host': '来自 {host} 的设置',
     'md.from.last': '最近一次会话用的',
+    'md.newDefault': '新会话默认是 {value}（{from}）',
     'md.none': '暂时不知道',
     'md.click': '点击修改。',
     'md.envNote': 'shell 里的 ANTHROPIC_MODEL、CLAUDE_CODE_EFFORT_LEVEL 和组织下发的设置会覆盖这里，sideby 看不到它们。',

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

@@ -2079,10 +2079,21 @@ const MAIN = String.raw `
   function modelChip(a) {
     const mi = a.modelInfo
     if (!mi || (!mi.model && !mi.effort)) return null
-    const text = [mi.model && mi.model.value, mi.effort && mi.effort.value].filter(Boolean).join(' · ')
+    // The row has little room; the hover text keeps the full model id.
+    const text = [mi.model && mi.model.value.replace(/^claude-/, ''), mi.effort && mi.effort.value].filter(Boolean).join(' · ')
+    // A value from the last session may differ from what a new session starts with; say both.
+    const line = (label, v, key) => {
+      if (!v) return null
+      const out = label + ': ' + v.value + ' (' + modelFrom(a, v.from) + ')'
+      const host = mi.host && mi.host[key]
+      // 'opus' and 'claude-opus-5-5' name the same model: only a real difference is worth a line.
+      return v.from === 'last' && host && !v.value.includes(host)
+        ? out + '; ' + t('md.newDefault', { value: host, from: modelFrom(a, 'host') })
+        : out
+    }
     const title = [
-      mi.model ? t('md.model') + ': ' + mi.model.value + ' (' + modelFrom(a, mi.model.from) + ')' : null,
-      mi.effort ? t('md.effort') + ': ' + mi.effort.value + ' (' + modelFrom(a, mi.effort.from) + ')' : null,
+      line(t('md.model'), mi.model, 'model'),
+      line(t('md.effort'), mi.effort, 'effort'),
       mi.settable ? t('md.click') : null,
     ].filter(Boolean).join('\n')
     if (!mi.settable) return h('span', { class: 'mono', title }, text)

package/dist/src/runtime.d.ts

@@ -239,10 +239,11 @@ export interface Runtime {
     /**
      * 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. `ahead` decides early what happens once the origin's fullest
-     * window reaches the threshold, as plan.json and the Panel need.
+     * window reaches the threshold, as plan.json and the Panel need. `to` names the only candidate (`handoff ready --to`).
      */
     handoffDecision(origin: Account, used: readonly string[], opts?: {
         ahead?: boolean;
+        to?: string;
     }): Promise<HandoffDecision>;
     readContext(): ReadContext;
 }

package/dist/src/runtime.js

@@ -666,6 +666,7 @@ export async function createRuntime(opts = {}) {
                 used,
                 now: now(),
                 ...(opts.ahead ? { ahead: true } : {}),
+                ...(opts.to !== undefined ? { to: opts.to } : {}),
             });
         },
         readContext,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sideby",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "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/schemas/handoff-ready.json

@@ -15,6 +15,9 @@
       "type": "boolean",
       "const": true
     },
+    "next": {
+      "type": "string"
+    },
     "brief": {
       "type": "string"
     }

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.9.0"
+  version: "0.9.2"
   requires:
     bins: [sideby, node]
   cliHelp: sideby --help

package/skills/sideby/references/handoff.md

@@ -41,7 +41,7 @@ With config `"handoff": { "auto": true }`, a session sideby started hands its ta
 
 - 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.
+- 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. Tell the user the account it prints, not what `sideby next` says: the chain never goes back to an account it already used. When the user names an account ("go back to cc008"), run `sideby handoff ready --to <account>`; it works for an account this chain already used.
 
 ### Turning it on for the user