sideby 0.3.0 → 0.4.1

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

@@ -0,0 +1,74 @@
+/** Environment sideby sets for a Host run that may start a Handoff. The hook does nothing without all three. */
+export declare const HANDOFF_ENV: {
+    readonly run: 'SIDEBY_HANDOFF_RUN';
+    readonly family: 'SIDEBY_HANDOFF_FAMILY';
+    readonly dir: 'SIDEBY_HANDOFF_DIR';
+};
+export type HandoffTrigger = 'threshold' | 'limit' | 'manual';
+/** What the parent decided the next Handoff would do, refreshed while the Host runs. */
+export interface PlanFile {
+    /** The run this plan is for; a plan left by an earlier hop of the chain is ignored. */
+    runId: string;
+    /** Where this run's session writes its Handoff Brief. */
+    brief: string;
+    at: string;
+    decision: 'pick' | 'wait' | 'none';
+    pick?: string;
+    prepareAt: number;
+    threshold: number;
+    /** False when the session cannot write its Brief: no preparing step, and the threshold only ends the turn. */
+    agentBrief?: boolean;
+}
+/** What the hook already did in one run. */
+export interface RunState {
+    prepareSentAt?: string;
+    thresholdSentAt?: string;
+    stopBlocked?: boolean;
+    sessionId?: string;
+    transcriptPath?: string;
+}
+/** The run is ready to hand off; written by the hook (`ready.json`), or asked for by `sideby handoff ready`. */
+export interface ReadyFile {
+    runId: string;
+    at: string;
+    trigger: HandoffTrigger;
+    /** The Brief file, when the session or the user wrote one. */
+    brief?: string;
+    briefSource?: 'agent' | 'user';
+    sessionId?: string;
+    transcriptPath?: string;
+}
+export interface ChainHop {
+    ref: string;
+    startedAt: string;
+    /** How this hop ended, when it handed off. */
+    trigger?: HandoffTrigger;
+    briefSource?: 'agent' | 'sideby' | 'user';
+    brief?: string;
+}
+export interface ChainFile {
+    hops: ChainHop[];
+}
+export declare const FILES: {
+    readonly plan: 'plan.json';
+    readonly ready: 'ready.json';
+    readonly request: 'request.json';
+    readonly chain: 'chain.json';
+    readonly run: (runId: string) => string;
+};
+/** A short random id for a chain or a run: safe in file names and environment values. */
+export declare function newId(): string;
+export declare function chainDir(stateDir: string, chain: string): string;
+/** Creates the chain directory (and its parents) and makes sure it is mode 700. */
+export declare function ensureChainDir(dir: string): Promise<void>;
+/** `<dir>/<n>-<ref>.md`, with the ref's `:` made safe for file names (`claude:001` → `claude-001`). */
+export declare function briefPath(dir: string, n: number, ref: string): string;
+/** The parsed JSON object in `path`, or null when it is missing, unreadable or not a JSON object. */
+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).
+ * Returns the request, or null outside such a run.
+ */
+export declare function requestHandoff(env: Readonly<Record<string, string | undefined>>, briefFile?: string): Promise<ReadyFile | null>;

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

@@ -0,0 +1,74 @@
+// The files one Handoff chain keeps under `<state>/handoffs/<chain>/` (spec §3.17). The handoff hook runs on every
+// tool call, so this module imports only Node built-ins and leaf modules (never the Runtime or a Family index).
+// The parent `sideby run` writes `plan.json` and `chain.json`; the hook writes `run-<id>.json` and `ready.json`;
+// `sideby handoff ready` writes `request.json`. Every file is mode 600 in a mode 700 directory.
+import { randomBytes } from 'node:crypto';
+import { chmod, mkdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { writeFileAtomic } from './fs-safe.js';
+/** Environment sideby sets for a Host run that may start a Handoff. The hook does nothing without all three. */
+export const HANDOFF_ENV = {
+    run: 'SIDEBY_HANDOFF_RUN',
+    family: 'SIDEBY_HANDOFF_FAMILY',
+    dir: 'SIDEBY_HANDOFF_DIR',
+};
+export const FILES = {
+    plan: 'plan.json',
+    ready: 'ready.json',
+    request: 'request.json',
+    chain: 'chain.json',
+    run: (runId) => `run-${runId}.json`,
+};
+/** A short random id for a chain or a run: safe in file names and environment values. */
+export function newId() {
+    return `${Date.now().toString(36)}-${randomBytes(4).toString('hex')}`;
+}
+export function chainDir(stateDir, chain) {
+    return join(stateDir, 'handoffs', chain);
+}
+/** Creates the chain directory (and its parents) and makes sure it is mode 700. */
+export async function ensureChainDir(dir) {
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    await chmod(dir, 0o700);
+}
+/** `<dir>/<n>-<ref>.md`, with the ref's `:` made safe for file names (`claude:001` → `claude-001`). */
+export function briefPath(dir, n, ref) {
+    return join(dir, `${n}-${ref.replace(/[^A-Za-z0-9._-]/g, '-')}.md`);
+}
+/** The parsed JSON object in `path`, or null when it is missing, unreadable or not a JSON object. */
+export async function readJsonFile(path) {
+    try {
+        const v = JSON.parse(await readFile(path, 'utf8'));
+        return v !== null && typeof v === 'object' && !Array.isArray(v) ? v : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeJsonFile(path, value) {
+    await writeFileAtomic(path, `${JSON.stringify(value, null, 2)}\n`, 0o600);
+}
+/**
+ * `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).
+ * Returns the request, or null outside such a run.
+ */
+export async function requestHandoff(env, briefFile) {
+    const runId = env[HANDOFF_ENV.run];
+    const dir = env[HANDOFF_ENV.dir];
+    if (!runId || !dir)
+        return null;
+    let brief;
+    if (briefFile) {
+        brief = join(dir, `user-${runId}.md`);
+        await writeFileAtomic(brief, await readFile(briefFile), 0o600);
+    }
+    const request = {
+        runId,
+        at: new Date().toISOString(),
+        trigger: 'manual',
+        ...(brief ? { brief, briefSource: 'user' } : {}),
+    };
+    await writeJsonFile(join(dir, FILES.request), request);
+    return request;
+}

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

@@ -0,0 +1,13 @@
+import type { Account, Finding } from '../types.ts';
+import type { HandoffSettings } from './config.ts';
+export declare function handoffFindings(input: {
+    settings: HandoffSettings;
+    /** Family ids this Doctor run checks. */
+    families: readonly string[];
+    /** Every Account on disk, to resolve `order` entries in any Family. */
+    accounts: readonly Account[];
+    aliases: Readonly<Record<string, string>>;
+    /** Whether Claude's quota tap is on; undefined when Claude is not part of the run. */
+    claudeTap?: boolean;
+    home: string;
+}): Promise<Finding[]>;

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

@@ -0,0 +1,35 @@
+// Doctor warnings for Auto Handoff (spec §3.17): only when `handoff.auto` is on, never a failure, never fixed.
+import { join } from 'node:path';
+import { statOrNull } from './fs-safe.js';
+export async function handoffFindings(input) {
+    const { settings: s } = input;
+    if (!s.auto)
+        return [];
+    const out = [];
+    const warn = (account, code, message, hint) => ({
+        level: 'warn',
+        account,
+        item: 'handoff',
+        code,
+        message,
+        hint,
+        source: 'core',
+        fixable: false,
+    });
+    const has = (family) => input.families.includes(family) && input.accounts.some((a) => a.family === family);
+    if (has('claude') && input.claudeTap === false)
+        out.push(warn('claude:main', 'handoff.no-quota-tap', 'Auto Handoff is on, but Claude Code reports no quota to sideby, so Claude sessions never hand over', 'run `sideby quota setup claude` (it shows the change first)'));
+    if (has('grok') && !(await statOrNull(join(input.home, '.grok', 'hooks', 'sideby-handoff.json'))))
+        out.push(warn('grok:main', 'handoff.setup-missing', 'Auto Handoff is on, but Grok has no sideby hook file, so a Grok session that hits its limit cannot hand over', 'run `sideby handoff setup grok`, then `sideby doctor grok --fix` to copy it to every Grok account'));
+    const refs = new Set(input.accounts.map((a) => a.ref));
+    for (const [family, f] of Object.entries(s.families)) {
+        if (!input.families.includes(family))
+            continue;
+        if (f.policy === 'order' && f.order.length === 0)
+            out.push(warn(`${family}:main`, 'handoff.order-empty', `handoff.families.${family} has policy "order" but no order, so ${family} sessions never hand over`, `list the accounts in handoff.families.${family}.order, or drop the policy to rank by quota`));
+        const unknown = f.order.filter((name) => !refs.has(input.aliases[name] ?? name));
+        if (unknown.length)
+            out.push(warn(`${family}:main`, 'handoff.order-unknown', `handoff.families.${family}.order names ${unknown.join(', ')}, which sideby cannot find; they are skipped`, 'fix the names in the config, or create the account with `sideby new`'));
+    }
+    return out;
+}

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

@@ -0,0 +1,31 @@
+import type { Runtime } from '../runtime.ts';
+import type { Env } from '../types.ts';
+import type { HandoffDecision } from './handoff-select.ts';
+export interface HandoffIo {
+    err(line: string): void;
+    stdin: NodeJS.ReadableStream & {
+        isTTY?: boolean;
+        setRawMode?: (on: boolean) => unknown;
+    };
+}
+/** How long the Host gets to exit after SIGTERM (time for its SessionEnd hooks) before sideby gives up. */
+export declare const EXIT_GRACE_MS = 10000;
+export declare function explain(d: HandoffDecision): string;
+/** `args` with `extra` before the first `--`, so a user's own `--` cannot turn sideby's options into prompt text. */
+export declare function beforeDashes(args: readonly string[], extra: readonly string[]): string[];
+/** Whether the `sideby` on PATH has the hook entry: an older install would fail every hook call. */
+export declare function hookEntryWorks(env: Env): Promise<boolean>;
+/**
+ * Runs `ref` with Auto Handoff when the config, the Family, the run and the terminal allow it, and returns the exit
+ * code of the last Host; null when Auto Handoff does not apply and the caller should run the Host as usual.
+ */
+export declare function runWithHandoff(rt: Runtime, ref: string, userArgs: readonly string[], io: HandoffIo, 
+/** For tests: how long the Host gets to exit after SIGTERM. */
+opts?: {
+    exitGraceMs?: number;
+}): 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.
+ */
+export declare function readyDecision(rt: Runtime, env: Env): Promise<HandoffDecision | null>;

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

@@ -0,0 +1,346 @@
+// Auto Handoff (spec §3.17, ADR-0010): `sideby run` stays the Host's parent. The Host's hooks write `ready.json`
+// when the session should hand over; then sideby ends the Host, finishes the Brief, counts down, and starts the next
+// Account in the same terminal with a new session that reads the Brief. Nothing here reads a credential.
+import { execFile } from 'node:child_process';
+import { watch } from 'node:fs';
+import { rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { HOOK_FAMILIES } from '../handoff/hook.js';
+import { firstPrompt } from '../handoff/messages.js';
+import { aliasArgs } from './config.js';
+import { finishBrief } from './handoff-brief.js';
+import { briefPath, chainDir, ensureChainDir, FILES, HANDOFF_ENV, newId, readJsonFile, writeJsonFile, } from './handoff-chain.js';
+import { runHost, sidebyBinProblem, spawnHost } from './launch.js';
+import { quotaPressure } from './quota-levels.js';
+/** How long the Host gets to exit after SIGTERM (time for its SessionEnd hooks) before sideby gives up. */
+export const EXIT_GRACE_MS = 10_000;
+const PLAN_REFRESH_MS = 60_000;
+const READY_POLL_MS = 1000;
+const hookCommand = (family) => (event) => `sideby handoff-hook ${family} ${event}`;
+const clock = (iso) => new Date(iso).toLocaleTimeString(undefined, { hour: '2-digit', minute: '2-digit' });
+export function explain(d) {
+    if (d.kind === 'wait')
+        return `the full window resets at ${clock(d.until)}, so waiting beats moving on`;
+    if (d.kind === 'none')
+        return d.earliestReset
+            ? `${d.reason}; ${d.earliestReset.ref} is back first, at ${clock(d.earliestReset.at)}`
+            : d.reason;
+    return `next: ${d.ref}`;
+}
+/** Resolves with the ready file once the hook writes one for `runId`; `stop()` ends the watch. */
+function watchReady(dir, runId) {
+    let stop = () => { };
+    const ready = new Promise((resolve) => {
+        const check = async () => {
+            const r = await readJsonFile(join(dir, FILES.ready));
+            if (r && r.runId === runId) {
+                stop();
+                resolve(r);
+            }
+        };
+        const timer = setInterval(() => void check(), READY_POLL_MS);
+        let watcher;
+        try {
+            watcher = watch(dir, () => void check());
+        }
+        catch {
+            // polling alone still works
+        }
+        stop = () => {
+            clearInterval(timer);
+            watcher?.close();
+        };
+        void check();
+    });
+    return { ready, stop: () => stop() };
+}
+const WHY = {
+    threshold: 'its quota reached the hand-over level',
+    limit: 'it hit its usage limit',
+    manual: 'you asked to hand over',
+};
+/**
+ * Counts down; resolves true when the person pressed Enter to cancel. On a terminal the line is rewritten in place,
+ * elsewhere each second is a line of its own.
+ */
+function countdown(io, seconds, to, from) {
+    return new Promise((resolve) => {
+        let left = seconds;
+        const raw = typeof io.stdin.setRawMode === 'function';
+        const inPlace = process.stderr.isTTY === true;
+        const done = (cancelled) => {
+            clearInterval(timer);
+            io.stdin.off('data', onData);
+            if (raw)
+                io.stdin.setRawMode(false);
+            io.stdin.pause();
+            if (inPlace)
+                process.stderr.write('\n');
+            resolve(cancelled);
+        };
+        const onData = (chunk) => {
+            const s = chunk.toString();
+            if (s.includes('\r') || s.includes('\n'))
+                done(true);
+            // Ctrl-C while counting down cancels as well.
+            else if (s.includes('\u0003'))
+                done(true);
+        };
+        const tick = () => {
+            const line = `sideby: starting ${to} in ${left}s; press Enter to stay in ${from}`;
+            if (inPlace)
+                process.stderr.write(`\r${line}\x1b[K`);
+            else
+                io.err(line);
+            if (left-- <= 0)
+                done(false);
+        };
+        if (raw)
+            io.stdin.setRawMode(true);
+        io.stdin.resume();
+        io.stdin.on('data', onData);
+        const timer = setInterval(tick, 1000);
+        tick();
+    });
+}
+/** Codex runs a hook only after the person trusted it in `/hooks`, once per Account; say so the first time. */
+async function codexTrustNotice(rt, account, io) {
+    const file = join(rt.paths.stateDir, 'handoff', 'codex-trust-notices.json');
+    const seen = (await readJsonFile(file))?.refs ?? [];
+    if (seen.includes(account.ref))
+        return;
+    io.err(`sideby: Codex runs sideby's handoff hooks only after you trust them: in ${account.ref}, type /hooks and trust \`sideby handoff-hook\`. Until then this account will not hand over.`);
+    await ensureChainDir(join(rt.paths.stateDir, 'handoff'));
+    await writeJsonFile(file, { refs: [...seen, account.ref] });
+}
+/** `args` with `extra` before the first `--`, so a user's own `--` cannot turn sideby's options into prompt text. */
+export function beforeDashes(args, extra) {
+    const at = args.indexOf('--');
+    return at === -1 ? [...args, ...extra] : [...args.slice(0, at), ...extra, ...args.slice(at)];
+}
+/** Whether the `sideby` on PATH has the hook entry: an older install would fail every hook call. */
+export function hookEntryWorks(env) {
+    return new Promise((resolve) => {
+        execFile('sideby', ['handoff-hook', '--check'], { env: env, timeout: 5000 }, (err, out) => resolve(!err && String(out).trim() === 'ok'));
+    });
+}
+/** The decision, or `none` with the reason when sideby cannot tell (an account removed mid-chain, say). */
+async function decide(rt, account, used) {
+    try {
+        return await rt.handoffDecision(account, used);
+    }
+    catch (err) {
+        return { kind: 'none', reason: err.message };
+    }
+}
+/**
+ * Runs `ref` with Auto Handoff when the config, the Family, the run and the terminal allow it, and returns the exit
+ * code of the last Host; null when Auto Handoff does not apply and the caller should run the Host as usual.
+ */
+export async function runWithHandoff(rt, ref, userArgs, io, 
+/** For tests: how long the Host gets to exit after SIGTERM. */
+opts = {}) {
+    const grace = opts.exitGraceMs ?? EXIT_GRACE_MS;
+    const settings = rt.handoffSettings();
+    if (!settings.auto || !io.stdin.isTTY)
+        return null;
+    const firstLaunch = await rt.prepareLaunch(ref, userArgs, 'run');
+    const firstHandoff = firstLaunch.family.handoff;
+    // Only built-in Families have a hook reader (spec §3.17); a Plugin Family can only take over.
+    if (!firstHandoff?.starts.length || !HOOK_FAMILIES.includes(firstLaunch.family.id))
+        return null;
+    const firstElig = await firstHandoff.eligibility(firstLaunch.args, firstLaunch.account, firstLaunch.env);
+    if (!firstElig.start) {
+        // A headless run is simply not part of it; an interactive one that cannot start says why.
+        if (firstElig.receive && firstElig.reason)
+            io.err(`sideby: ${firstLaunch.account.ref} will not hand over: ${firstElig.reason}`);
+        return null;
+    }
+    const binProblem = (await sidebyBinProblem(rt.env, 'the Host runs `sideby handoff-hook` for Auto Handoff')) ??
+        ((await hookEntryWorks(rt.env))
+            ? null
+            : 'the sideby on PATH is older than this one and has no `handoff-hook`; upgrade it with `npm i -g sideby`');
+    if (binProblem) {
+        io.err(`sideby: Auto Handoff is off for this run: ${binProblem}`);
+        return null;
+    }
+    const chain = newId();
+    const dir = chainDir(rt.paths.stateDir, chain);
+    await ensureChainDir(dir);
+    const hops = { hops: [] };
+    const used = [];
+    const own = rt.config.aliases?.[ref];
+    let hop = { ref, args: [...aliasArgs(own), ...userArgs] };
+    let n = 1;
+    for (;;) {
+        const launch = n === 1 ? firstLaunch : await rt.prepareLaunch(hop.ref, hop.args, 'run');
+        const account = launch.account;
+        const h = launch.family.handoff;
+        if (!h)
+            return runHost(launch);
+        const elig = n === 1 ? firstElig : await h.eligibility(launch.args, account, launch.env);
+        const canStart = h.starts.length > 0 && elig.start && HOOK_FAMILIES.includes(account.family);
+        if (!canStart && elig.reason)
+            io.err(`sideby: ${account.ref} will not hand over: ${elig.reason}`);
+        const runId = newId();
+        const brief = briefPath(dir, n, account.ref);
+        const extra = [...(elig.args ?? [])];
+        const env = { ...launch.env };
+        if (canStart) {
+            extra.push(...((await h.hookArgs?.(hookCommand(account.family), rt.paths.stateDir)) ?? []));
+            env[HANDOFF_ENV.run] = runId;
+            env[HANDOFF_ENV.family] = account.family;
+            env[HANDOFF_ENV.dir] = dir;
+            if (account.family === 'codex')
+                await codexTrustNotice(rt, account, io);
+        }
+        extra.push(...(h.dirArgs?.(dir) ?? []));
+        const args = beforeDashes(launch.args, extra);
+        // Later hops carry no `--` of their own (continueArgs drops it), so the prompt goes after a fresh one.
+        if (hop.prompt)
+            args.push(...h.promptArgs(hop.prompt));
+        used.push(account.ref);
+        hops.hops.push({ ref: account.ref, startedAt: new Date().toISOString() });
+        await writeJsonFile(join(dir, FILES.chain), hops);
+        if (launch.notice)
+            io.err(launch.notice);
+        if (!canStart)
+            return runHost({ ...launch, args, env });
+        // Plan writes run one after another, and none lands after this hop is over: a late one would carry this
+        // run's id into the next hop's plan.json and silence its hook.
+        let stopped = false;
+        let pending = Promise.resolve();
+        const writePlan = () => {
+            pending = pending.then(async () => {
+                try {
+                    const d = await rt.handoffDecision(account, used);
+                    if (stopped)
+                        return;
+                    const plan = {
+                        runId,
+                        brief,
+                        at: new Date().toISOString(),
+                        decision: d.kind,
+                        ...(d.kind === 'pick' ? { pick: d.ref } : {}),
+                        prepareAt: settings.prepareAt,
+                        threshold: settings.threshold,
+                        ...(elig.agentBrief === false ? { agentBrief: false } : {}),
+                    };
+                    await writeJsonFile(join(dir, FILES.plan), plan);
+                }
+                catch {
+                    // the hook treats a missing plan as "do not interrupt"
+                }
+            });
+            return pending;
+        };
+        await writePlan();
+        const refresh = setInterval(() => void writePlan(), PLAN_REFRESH_MS);
+        const host = spawnHost({ ...launch, args, env });
+        const watcher = watchReady(dir, runId);
+        const outcome = await Promise.race([
+            host.exited.then((code) => ({ kind: 'exit', code })),
+            watcher.ready.then((ready) => ({ kind: 'ready', ready })),
+        ]);
+        clearInterval(refresh);
+        watcher.stop();
+        stopped = true;
+        await pending;
+        if (outcome.kind === 'exit') {
+            await noteUnhandedHighQuota(rt, account, used, settings.threshold, io);
+            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);
+        if (decision.kind !== 'pick') {
+            await rm(join(dir, FILES.ready), { force: true });
+            const code = await host.exited;
+            io.err(`sideby: ${account.ref} did not hand over: ${explain(decision)}`);
+            return code;
+        }
+        // The session is ready: end the Host, give it time to save, never kill it.
+        host.child.kill('SIGTERM');
+        const ended = await Promise.race([
+            host.exited.then((code) => ({ code })),
+            new Promise((r) => setTimeout(() => r(null), grace).unref()),
+        ]);
+        if (!ended) {
+            io.err(`sideby: ${account.ref} did not exit within ${grace / 1000}s, so nothing was handed over; exit it yourself, then start the next account with \`sideby run ${decision.ref}\``);
+            return host.exited;
+        }
+        const ready = outcome.ready;
+        const assembled = await h
+            .briefFromSession?.(account, {
+            ...(ready.sessionId ? { id: ready.sessionId } : {}),
+            ...(ready.transcriptPath ? { transcriptPath: ready.transcriptPath } : {}),
+        })
+            .catch(() => undefined);
+        const done = await finishBrief({
+            target: brief,
+            ready,
+            ...(assembled ? { assembled } : {}),
+            cwd: process.cwd(),
+        });
+        const last = hops.hops[hops.hops.length - 1];
+        Object.assign(last, { trigger: ready.trigger, briefSource: done.source, brief: done.path });
+        await writeJsonFile(join(dir, FILES.chain), hops);
+        await rm(join(dir, FILES.ready), { force: true });
+        await rm(join(dir, FILES.request), { force: true });
+        io.err(`sideby: ${account.ref} saved its session and is handing over because ${WHY[ready.trigger]}; next is ${decision.ref}. Brief: ${done.path}`);
+        if (settings.countdownSeconds > 0 &&
+            (await countdown(io, settings.countdownSeconds, decision.ref, account.ref))) {
+            io.err(`sideby: staying in ${account.ref}`);
+            if (!ready.sessionId) {
+                io.err(`sideby: the session id is unknown, so start ${account.ref} yourself; the Brief is at ${done.path}`);
+                return ended.code;
+            }
+            const backArgs = [...h.continueArgs(hop.args), ...h.resumeArgs(ready.sessionId)];
+            const back = await rt.prepareLaunch(account.ref, backArgs, 'run');
+            // The same per-Account arguments as before (Grok's leader socket), without sideby's hooks.
+            const backElig = await h.eligibility(back.args, account, back.env);
+            return runHost({ ...back, args: beforeDashes(back.args, backElig.args ?? []) });
+        }
+        let next;
+        try {
+            next = await rt.resolve(decision.ref);
+        }
+        catch (err) {
+            io.err(`sideby: cannot start ${decision.ref}: ${err.message}; the Brief is at ${done.path}`);
+            return ended.code;
+        }
+        io.err(`sideby: handing over from ${account.ref} to ${next.ref}`);
+        hop = {
+            ref: next.ref,
+            args: next.family === account.family ? h.continueArgs(hop.args) : [],
+            prompt: firstPrompt(account.ref, done.path),
+        };
+        n++;
+    }
+}
+/** After a session ended on its own: when its Quota passed the threshold but nothing could take over, say why. */
+async function noteUnhandedHighQuota(rt, account, used, threshold, io) {
+    try {
+        const pressure = quotaPressure(await rt.quota(account), new Date());
+        if (pressure === null || pressure < threshold)
+            return;
+        const d = await rt.handoffDecision(account, used);
+        if (d.kind !== 'pick')
+            io.err(`sideby: ${account.ref} is at ${Math.round(pressure)}%; no Auto Handoff: ${explain(d)}`);
+    }
+    catch {
+        // a note only
+    }
+}
+/**
+ * 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.
+ */
+export async function readyDecision(rt, env) {
+    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]);
+}

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

@@ -0,0 +1,42 @@
+import type { Account, AccountIdentity, LoginState, QuotaResult } from '../types.ts';
+import type { HandoffSettings } from './config.ts';
+export interface SelectCandidate {
+    ref: string;
+    family: string;
+    name: string;
+    isMain: boolean;
+    kind: Account['kind'];
+    login: LoginState | 'not-needed';
+    quota: QuotaResult;
+    identity?: AccountIdentity;
+    /** Whether the Account's Host is on PATH. */
+    installed: boolean;
+    /** Whether its Family can start as the next Account (has `handoff`, and the run would be eligible). */
+    receive: boolean;
+}
+export type HandoffDecision = {
+    kind: 'pick';
+    ref: string;
+} | {
+    kind: 'wait';
+    until: string;
+} | {
+    kind: 'none';
+    reason: string;
+    earliestReset?: {
+        ref: string;
+        at: string;
+    };
+};
+/** Organizations when both have one, else email domains when both have one, else the same. */
+export declare function sameOrganization(a?: AccountIdentity, b?: AccountIdentity): boolean;
+export declare function selectNext(input: {
+    origin: SelectCandidate;
+    candidates: readonly SelectCandidate[];
+    settings: HandoffSettings;
+    /** Short command → Account ref, so lists may name either. */
+    aliases: Readonly<Record<string, string>>;
+    /** Accounts this chain already used, the origin included. */
+    used: readonly string[];
+    now: Date;
+}): HandoffDecision;