sideby 0.2.2 → 0.4.0

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

@@ -4,7 +4,7 @@
 import { mkdir, readFile, rm, stat } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { lstatOrNull, realpathOrNull, sha256, writeFileAtomic, writeIfUnchanged } from '../core/fs-safe.js';
-import { which } from '../core/launch.js';
+import { sidebyBinProblem } from '../core/launch.js';
 import { tildify } from '../core/paths.js';
 import { CLAUDE_MAIN_DIR } from '../families/claude/layout.js';
 import { ORIG_FLAG, TAP_COMMAND } from './statusline-tap.js';
@@ -73,12 +73,9 @@ async function analyze(ctx) {
         return {
             plan: { status: 'enabled', file: target, diff: '', message: `already enabled in ${targetName}${note}` },
         };
-    const bin = await which('sideby', ctx.env);
-    if (!bin)
-        return blocked(`sideby is not on PATH, and the status line runs \`${TAP_COMMAND}\` on every refresh; install it with \`npm i -g sideby\` and retry`, target);
-    const real = (await realpathOrNull(bin)) ?? bin;
-    if (bin.includes('/_npx/') || real.includes('/_npx/'))
-        return blocked(`sideby on PATH comes from the npx cache (${bin}), which can disappear; install it with \`npm i -g sideby\` and retry`, target);
+    const problem = await sidebyBinProblem(ctx.env, `the status line runs \`${TAP_COMMAND}\` on every refresh`);
+    if (problem)
+        return blocked(problem, target);
     const statusLine = current
         ? { type: 'command', ...current, command: wrapCommand(command) }
         : { type: 'command', command: TAP_COMMAND };

package/dist/src/runtime.d.ts

@@ -1,23 +1,31 @@
 import { type AccountRefError } from './core/accounts.ts';
-import { type Config } from './core/config.ts';
+import { type Config, type HandoffSettings } from './core/config.ts';
 import { type CreateResult } from './core/create.ts';
 import { type DoctorReport } from './core/doctor.ts';
 import { UserError } from './core/errors.ts';
 import { type HandoffPlan } from './core/handoff.ts';
+import { type HandoffDecision } from './core/handoff-select.ts';
 import { type DoctorHistory } from './core/last-doctor.ts';
 import { type HostLaunch, type PreparedLaunch } from './core/launch.ts';
 import { type Paths } from './core/paths.ts';
 import { type Shell, type ShellInitWrite } from './core/shell-init.ts';
+import { type TuneEntry, type TuneGroup } from './core/tuning.ts';
+import { type TuneApplyPlan, type TuneChange, type TuneUndoRecord } from './core/tuning-apply.ts';
 import { type BuiltinPlugin, type LoadedPlugin, type PluginLoadError } from './plugins/loader.ts';
-import type { Account, AccountIdentity, Env, FamilyDef, LoginState, QuotaResult, QuotaSetupPlan, ReadContext, ShareMode, UsageResult } from './types.ts';
+import type { Account, AccountIdentity, Env, FamilyDef, LoginState, QuotaResult, QuotaSetupPlan, ReadContext, ShareMode, TuningResult, UsageResult } from './types.ts';
 export type { AccountIdentity, AccountRefError, DoctorHistory, Shell, ShellInitWrite };
 /** How `sideby resume` starts the Host (spec §3.15). */
 export interface ResumeLaunch {
     launch: HostLaunch;
     /** The session the Host arguments resume by id, when they name one. */
     sessionId?: string;
-    /** Set when the session lives in a non-main Account and `launch` starts that Account as `run` would. */
+    /**
+     * Set when the session lives in a non-main Account and `launch` starts that Account as `run` would, or with
+     * `newSession` the Account (main included) that started a session the Host never saved.
+     */
     account?: Account;
+    /** Set when the session was never saved: `launch` starts a new session in `account` without the resume (ADR-0009). */
+    newSession?: true;
 }
 /** What happened to the alias asked for with a new Account. */
 export interface AliasResult {
@@ -52,6 +60,8 @@ export interface FamilyInfo {
     installed: boolean;
     /** Plugin that provides the Family. */
     plugin: string;
+    /** The Family can estimate a Compaction Threshold (spec §3.18). */
+    tuning: boolean;
 }
 /** One Shared Item as `sideby families` reports it (spec §3.16). */
 export interface SharedItemInfo {
@@ -147,6 +157,8 @@ export interface Runtime {
     }[]>;
     /** One Family's quota setup; throws UnknownFamilyError or a UserError when the Family has none. */
     quotaSetup(familyId: string): BoundQuotaSetup;
+    /** One Family's handoff hook setup (spec §3.17, Grok); throws a UserError when the Family needs none. */
+    handoffSetup(familyId: string): BoundQuotaSetup;
     /**
      * Creates the Account, then (when `alias` is given) adds it to the config `aliases`, then rewrites every
      * `shellInitFile`. An alias that is invalid or taken is refused before anything is created; a failure to write
@@ -177,6 +189,24 @@ export interface Runtime {
     resumeLaunch(familyId: string, userArgs: readonly string[]): Promise<ResumeLaunch>;
     quota(account: Account): Promise<QuotaResult>;
     usage(account: Account): Promise<UsageResult>;
+    /** Estimated Compaction Threshold per model for one Account (spec §3.18); read-only. */
+    tuning(account: Account): Promise<TuningResult>;
+    /** Suggestions grouped by settings file (Accounts sharing a file share one), with every listed Account's details. */
+    tuneGroups(only?: Account): Promise<{
+        accounts: TuneEntry[];
+        groups: TuneGroup[];
+    }>;
+    /** What using a suggested size would change in the Account's settings; writes nothing (spec §3.18, ADR-0012). */
+    tuneApplyPlan(account: Account, value: number | null): Promise<TuneApplyPlan>;
+    /** Writes the size into the Account's settings (one key; null goes back to the default), and remembers how to undo it. */
+    tuneApply(account: Account, value: number | null): Promise<TuneChange>;
+    /** Puts the setting back as it was, only while it still holds what sideby wrote. */
+    tuneUndo(account: Account): Promise<{
+        ok: boolean;
+        message: string;
+    }>;
+    /** What could be undone for the Account, or null. */
+    tuneUndoInfo(account: Account): Promise<TuneUndoRecord | null>;
     /**
      * Which Account of a Family to move on to (spec §3.13). Throws a UserError with code `no-quota-source`
      * when the Family cannot tell, `no-accounts` when it has none.
@@ -184,6 +214,13 @@ export interface Runtime {
     handoff(familyId: string, opts?: {
         includeApi?: boolean;
     }): Promise<HandoffPlan>;
+    /** The config `handoff` settings with every default filled in (spec §3.17). */
+    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.
+     */
+    handoffDecision(origin: Account, used: readonly string[]): Promise<HandoffDecision>;
     readContext(): ReadContext;
 }
 export declare class UnknownFamilyError extends UserError {

package/dist/src/runtime.js

@@ -1,17 +1,22 @@
 // The one service layer the CLI and the Panel share. Frozen contract for v0.1 (plan: 审核修订).
-import { discoverAccounts, resolveRef } from './core/accounts.js';
-import { addConfigAlias, aliasAccount, aliasArgs, aliasProblem, aliasRefs, loadConfig, removeConfigAlias, } from './core/config.js';
+import { aliasesByAccount, discoverAccounts, resolveRef } from './core/accounts.js';
+import { addConfigAlias, aliasAccount, aliasArgs, aliasProblem, aliasRefs, handoffSettings, loadConfig, removeConfigAlias, } from './core/config.js';
 import { createAccount } from './core/create.js';
 import { applyFixes, runDoctor } from './core/doctor.js';
 import { UserError } from './core/errors.js';
 import { planHandoff } from './core/handoff.js';
+import { handoffFindings } from './core/handoff-doctor.js';
+import { selectNext } from './core/handoff-select.js';
 import { identityOf } from './core/identity.js';
 import { mergeDoctorHistory, readDoctorHistory, writeDoctorHistory, } from './core/last-doctor.js';
 import { prepareLaunch, which } from './core/launch.js';
+import { memoStore } from './core/memo-store.js';
 import { resolvePaths } from './core/paths.js';
 import { findResumeRoute } from './core/resume.js';
 import { shareMeaning } from './core/share-meaning.js';
 import { SHELLS, shellInitScript, writeShellInitFile, } from './core/shell-init.js';
+import { groupSuggestion } from './core/tuning.js';
+import { applyTune, currentTuneValue, planTuneApply, settingsFileOf, tuneUndoInfo, undoTune, } from './core/tuning-apply.js';
 import { packageVersion } from './core/version.js';
 import { BUILTIN_PLUGINS } from './families/index.js';
 import { HookBus } from './plugins/bus.js';
@@ -36,6 +41,7 @@ async function readIdentity(f, account) {
 export async function createRuntime(opts = {}) {
     const env = opts.env ?? process.env;
     const paths = resolvePaths(env);
+    const memos = memoStore(paths.stateDir);
     const config = await loadConfig(paths.configFile);
     const bus = new HookBus();
     const loaded = await loadPlugins({
@@ -60,12 +66,62 @@ export async function createRuntime(opts = {}) {
         if (f)
             families.set(id, { ...f, sharedItems: [...f.sharedItems, ...extra] });
     }
+    /**
+     * `SIDEBY_LABEL` for a Launch: the alias it was started through; else the Account's aliases, those without Host
+     * arguments first, then by name; else the ref.
+     */
+    const launchLabel = (ref, account, all) => {
+        if (!ref.includes(':') && ownAlias(ref) !== undefined)
+            return ref;
+        const names = aliasesByAccount(aliasRefs(config.aliases), all).get(account.ref) ?? [];
+        const plain = names.filter((n) => aliasArgs(ownAlias(n)).length === 0);
+        return plain[0] ?? names[0] ?? account.ref;
+    };
     const accounts = async () => {
         const out = [];
         for (const f of families.values())
             out.push(...(await discoverAccounts(f, paths.home, ignore)));
         return out;
     };
+    const loginOf = async (a) => {
+        if (a.kind === 'api')
+            return 'not-needed';
+        try {
+            return (await familyOf(a.family).loginState?.(a)) ?? 'unknown';
+        }
+        catch {
+            return 'unknown';
+        }
+    };
+    /** A Family's one-time setup bound to this Runtime; a setup that throws is reported, never crashes the caller. */
+    const bindSetup = (f, setup) => {
+        // The message is the error's own text; setup implementations must not put file contents into it.
+        const blocked = (err) => ({
+            status: 'blocked',
+            file: '',
+            diff: '',
+            message: err?.message ?? String(err),
+        });
+        return {
+            family: f.id,
+            summary: setup.summary,
+            // Promise.resolve().then also catches a setup that throws synchronously.
+            plan: () => Promise.resolve()
+                .then(() => setup.plan(readContext()))
+                .catch(blocked),
+            apply: () => Promise.resolve()
+                .then(() => setup.apply(readContext()))
+                .catch(blocked),
+            teardown: () => Promise.resolve()
+                .then(() => setup.teardown(readContext()))
+                .catch((err) => ({ ok: false, message: err?.message ?? String(err) })),
+        };
+    };
+    // Only Claude Code has a suggestion to use; Codex only observes (spec §3.18).
+    const onlyClaude = (account) => {
+        if (account.family !== 'claude')
+            throw new UserError(`${account.ref} has no suggested size to use yet: only Claude Code accounts do. Run \`sideby tune ${account.ref}\` to see what is observed`, { code: 'no-suggestion' });
+    };
     const readContext = () => ({
         home: paths.home,
         now: now(),
@@ -103,6 +159,7 @@ export async function createRuntime(opts = {}) {
                 installUrl: f.installUrl,
                 installed: (await which(f.bin, env)) !== null,
                 plugin: loaded.familyOwner.get(f.id) ?? 'unknown',
+                tuning: Boolean(f.readTuning),
             })));
         },
         async familyDetails() {
@@ -198,10 +255,26 @@ export async function createRuntime(opts = {}) {
                 // of that Family keeps its skill warning.
                 skillVersion: packageVersion(),
             };
-            let report = await runDoctor(input);
+            // Auto Handoff warnings (spec §3.17) join the general Findings; they never fail Doctor.
+            const all = await accounts();
+            const withHandoff = async (r) => {
+                const claude = fams.get('claude');
+                const extra = await handoffFindings({
+                    settings: handoffSettings(config),
+                    families: [...fams.keys()],
+                    accounts: all,
+                    aliases: aliasRefs(config.aliases),
+                    ...(claude?.quotaSetup
+                        ? { claudeTap: (await bindSetup(claude, claude.quotaSetup).plan()).status === 'enabled' }
+                        : {}),
+                    home: paths.home,
+                });
+                return extra.length ? { ...r, general: [...r.general, ...extra] } : r;
+            };
+            let report = await withHandoff(await runDoctor(input));
             if (o.fix) {
                 const fixes = await applyFixes(report);
-                report = { ...(await runDoctor(input)), fixes };
+                report = { ...(await withHandoff(await runDoctor(input))), fixes };
             }
             const history = mergeDoctorHistory(await readDoctorHistory(paths.stateDir), report, scope, now());
             if (o.persist !== false)
@@ -221,34 +294,15 @@ export async function createRuntime(opts = {}) {
         },
         quotaSetup(familyId) {
             const f = familyOf(familyId);
-            const setup = f.quotaSetup;
-            if (!setup)
+            if (!f.quotaSetup)
                 throw new UserError(`${f.title} needs no quota setup`);
-            // One rule for every adapter: a setup that throws is reported, never crashes the caller. The message
-            // is the error's own text; setup implementations must not put file contents into it.
-            const blocked = (err) => ({
-                status: 'blocked',
-                file: '',
-                diff: '',
-                message: err?.message ?? String(err),
-            });
-            return {
-                family: f.id,
-                summary: setup.summary,
-                // Promise.resolve().then also catches a setup that throws synchronously.
-                plan: () => Promise.resolve()
-                    .then(() => setup.plan(readContext()))
-                    .catch(blocked),
-                apply: () => Promise.resolve()
-                    .then(() => setup.apply(readContext()))
-                    .catch(blocked),
-                teardown: () => Promise.resolve()
-                    .then(() => setup.teardown(readContext()))
-                    .catch((err) => ({
-                    ok: false,
-                    message: err?.message ?? String(err),
-                })),
-            };
+            return bindSetup(f, f.quotaSetup);
+        },
+        handoffSetup(familyId) {
+            const f = familyOf(familyId);
+            if (!f.handoff?.hookSetup)
+                throw new UserError(`${f.title} needs no handoff setup: ${f.handoff?.starts.length ? 'sideby adds its hooks when it starts the account' : 'it cannot start a handoff, only take one over'}`);
+            return bindSetup(f, f.handoff.hookSetup);
         },
         async createAccount(familyId, name, o = {}) {
             const family = familyOf(familyId);
@@ -338,8 +392,11 @@ export async function createRuntime(opts = {}) {
             return out;
         },
         async prepareLaunch(ref, userArgs, command) {
-            const account = resolveRef(ref, await accounts(), aliasRefs(config.aliases));
+            const all = await accounts();
+            const account = resolveRef(ref, all, aliasRefs(config.aliases));
             return prepareLaunch({
+                label: launchLabel(ref, account, all),
+                title: config.accountTitle === true,
                 account,
                 family: familyOf(account.family),
                 baseEnv: env,
@@ -360,7 +417,14 @@ export async function createRuntime(opts = {}) {
                 return { launch: host };
             const route = await findResumeRoute(family, await accounts(), userArgs);
             const id = route.sessionId ? { sessionId: route.sessionId } : {};
-            if (!route.account || route.account.isMain)
+            if (route.neverSaved && route.account && family.withoutResume) {
+                const args = family.withoutResume(userArgs);
+                const launch = route.account.isMain
+                    ? { ...host, args }
+                    : await rt.prepareLaunch(route.account.ref, args, 'run');
+                return { launch, ...id, account: route.account, newSession: true };
+            }
+            if (!route.account || route.account.isMain || route.neverSaved)
                 return { launch: host, ...id };
             return {
                 launch: await rt.prepareLaunch(route.account.ref, userArgs, 'run'),
@@ -374,23 +438,109 @@ export async function createRuntime(opts = {}) {
             const f = familyOf(account.family);
             if (!f.readQuota)
                 return { status: 'unavailable', reason: 'no-source' };
+            await memos.ready();
             try {
                 return await f.readQuota(account, readContext());
             }
             catch (err) {
                 return { status: 'unavailable', reason: 'unrecognized', detail: err.message };
             }
+            finally {
+                memos.saveSoon();
+            }
         },
         async usage(account) {
             const f = familyOf(account.family);
             if (!f.readUsage)
                 return { status: 'unavailable', reason: 'no-source' };
+            await memos.ready();
             try {
                 return await f.readUsage(account, readContext());
             }
             catch (err) {
                 return { status: 'unavailable', reason: 'unrecognized', detail: err.message };
             }
+            finally {
+                memos.saveSoon();
+            }
+        },
+        async tuneGroups(only) {
+            const tunable = new Set((await rt.familyInfo()).filter((f) => f.tuning).map((f) => f.id));
+            const all = (await accounts()).filter((a) => tunable.has(a.family));
+            const files = new Map();
+            for (const a of all) {
+                if (a.family !== 'claude')
+                    continue;
+                const file = await settingsFileOf(a);
+                files.set(file, [...(files.get(file) ?? []), a]);
+            }
+            const wanted = only
+                ? [...files.entries()].filter(([, m]) => m.some((a) => a.ref === only.ref))
+                : [...files.entries()];
+            const entries = new Map();
+            const entryOf = async (a) => {
+                const have = entries.get(a.ref);
+                if (have)
+                    return have;
+                const made = { ref: a.ref, family: a.family, tuning: await rt.tuning(a) };
+                entries.set(a.ref, made);
+                return made;
+            };
+            const groups = [];
+            for (const [file, members] of wanted) {
+                const list = [];
+                for (const m of members)
+                    list.push(await entryOf(m));
+                const pick = groupSuggestion(list);
+                const current = await currentTuneValue(members[0]);
+                const target = members.find((m) => m.ref === pick?.ref) ?? members[0];
+                const undo = await tuneUndoInfo(target, readContext());
+                groups.push({
+                    file,
+                    members: members.map((m) => m.ref),
+                    target: target.ref,
+                    current,
+                    pick,
+                    undo: undo ? { value: undo.applied, previous: undo.previous } : null,
+                });
+            }
+            const shown = [];
+            // Asking about one Account also lists the others that share its file: the suggestion is for the whole group.
+            const refs = only ? new Set([only.ref, ...wanted.flatMap(([, m]) => m.map((a) => a.ref))]) : null;
+            for (const a of all)
+                if (!refs || refs.has(a.ref))
+                    shown.push(await entryOf(a));
+            return { accounts: shown, groups };
+        },
+        async tuneApplyPlan(account, value) {
+            onlyClaude(account);
+            return planTuneApply(account, value, await accounts());
+        },
+        async tuneApply(account, value) {
+            onlyClaude(account);
+            return applyTune(account, value, await accounts(), readContext());
+        },
+        async tuneUndo(account) {
+            onlyClaude(account);
+            return undoTune(account, readContext());
+        },
+        async tuneUndoInfo(account) {
+            return account.family === 'claude' ? tuneUndoInfo(account, readContext()) : null;
+        },
+        async tuning(account) {
+            const f = familyOf(account.family);
+            if (!f.readTuning)
+                return { status: 'unavailable', reason: 'no-source' };
+            await memos.ready();
+            try {
+                return await f.readTuning(account, readContext());
+            }
+            catch (err) {
+                return { status: 'unavailable', reason: 'unrecognized', detail: err.message };
+            }
+            finally {
+                memos.saveSoon();
+            }
         },
         async handoff(familyId, o = {}) {
             const f = familyOf(familyId);
@@ -402,22 +552,55 @@ export async function createRuntime(opts = {}) {
                     code: 'no-accounts',
                 });
             // Only the login state and Quota: no identity, model or Host lookups are needed to rank.
-            const loginOf = async (a) => {
-                if (a.kind === 'api')
-                    return 'not-needed';
-                try {
-                    return (await f.loginState?.(a)) ?? 'unknown';
-                }
-                catch {
-                    return 'unknown';
-                }
-            };
             const candidates = await Promise.all(list.map(async (a) => {
                 const [login, quota] = await Promise.all([loginOf(a), rt.quota(a)]);
                 return { ref: a.ref, name: a.name, isMain: a.isMain, kind: a.kind, login, quota };
             }));
             return planHandoff(f.id, candidates, readContext().now, o);
         },
+        handoffSettings: () => handoffSettings(config),
+        async handoffDecision(origin, used) {
+            const candidates = await Promise.all((await accounts()).map(async (a) => {
+                const f = familyOf(a.family);
+                const [installed, login, quota, identity] = await Promise.all([
+                    which(f.bin, env),
+                    loginOf(a),
+                    rt.quota(a),
+                    readIdentity(f, a),
+                ]);
+                let receive = false;
+                try {
+                    receive = Boolean(f.handoff &&
+                        (await f.handoff.eligibility(config.accounts?.[a.ref]?.args ?? [], a, env)).receive);
+                }
+                catch {
+                    // a Family that cannot tell does not take over
+                }
+                return {
+                    ref: a.ref,
+                    family: a.family,
+                    name: a.name,
+                    isMain: a.isMain,
+                    kind: a.kind,
+                    login,
+                    quota,
+                    ...(identity ? { identity } : {}),
+                    installed: installed !== null,
+                    receive,
+                };
+            }));
+            const self = candidates.find((c) => c.ref === origin.ref);
+            if (!self)
+                throw new UserError(`${origin.ref} is not an account sideby can find; run \`sideby list\``);
+            return selectNext({
+                origin: self,
+                candidates,
+                settings: handoffSettings(config),
+                aliases: aliasRefs(config.aliases),
+                used,
+                now: now(),
+            });
+        },
         readContext,
     };
     return rt;

package/dist/src/types.d.ts

@@ -67,6 +67,14 @@ export interface FamilyDef {
     };
     /** Arguments sideby adds before the Account's and the user's arguments. */
     defaultArgs?(account: Account, userArgs: readonly string[]): string[];
+    /**
+     * Host arguments that stop the Host from setting the terminal title for this run, so the title sideby sets with
+     * config `accountTitle` (`[<SIDEBY_LABEL>]`) stays. Added after `defaultArgs`, unless a user argument contains `key`.
+     */
+    keepTitle?: {
+        args: string[];
+        key: string;
+    };
     loginState?(account: Account): Promise<LoginState>;
     model?(account: Account): Promise<string | undefined>;
     /**
@@ -77,6 +85,11 @@ export interface FamilyDef {
     identity?(account: Account): Promise<AccountIdentity | undefined>;
     readQuota?(account: Account, ctx: ReadContext): Promise<QuotaResult>;
     readUsage?(account: Account, ctx: ReadContext): Promise<UsageResult>;
+    /**
+     * Estimates the best Compaction Threshold per model from the Account's recent local session records
+     * (spec §3.18). Read-only: it never writes a Host directory, and reads one named key of the Host's config at most.
+     */
+    readTuning?(account: Account, ctx: ReadContext): Promise<TuningResult>;
     /** One-time, reversible change that lets the Host report Quota (Claude: status line wrapper). */
     quotaSetup?: QuotaSetup;
     /**
@@ -86,6 +99,55 @@ export interface FamilyDef {
     resumedSession?(args: readonly string[]): string | undefined;
     /** When the Account holds the session, the last write time of its file in ms; otherwise undefined. */
     sessionWrittenAt?(account: Account, sessionId: string): Promise<number | undefined>;
+    /**
+     * When the Account started the session, even one the Host never saved, the time in ms; otherwise undefined.
+     * With `withoutResume` it lets `sideby resume` start a new session there instead of a resume that fails (ADR-0009).
+     */
+    sessionStartedAt?(account: Account, sessionId: string): Promise<number | undefined>;
+    /** The Host arguments without the by-id resume `resumedSession` reads; the others keep their order. */
+    withoutResume?(args: readonly string[]): string[];
+    /** How this Family takes part in a Handoff (spec §3.17); without it the Family neither starts nor receives one. */
+    handoff?: FamilyHandoff;
+}
+/** A Host hook event sideby's handoff hook listens to. */
+export type HandoffHookEvent = 'PostToolUse' | 'Stop' | 'StopFailure';
+/** Whether one run may start a Handoff, or start as the next Account of one, and why not. */
+export interface HandoffEligibility {
+    start: boolean;
+    receive: boolean;
+    /** Shown before the Host starts when `start` or `receive` is false. */
+    reason?: string;
+    /** Host arguments this run needs to take part, such as Grok's per-Account leader socket. */
+    args?: string[];
+    /** False when the session cannot write its Brief (Codex read-only sandbox): sideby puts one together instead. */
+    agentBrief?: boolean;
+}
+export interface FamilyHandoff {
+    /**
+     * What this Family can start: `quota` before the limit (prepare and threshold, from its Quota), `limit` after a
+     * turn failed at the limit. Empty: it can only receive. Plugin Families can only receive for now: the hook entry
+     * loads built-in readers only.
+     */
+    starts: readonly ('quota' | 'limit')[];
+    /** Host arguments that load sideby's hooks for one run; omitted when the hooks come from `hookSetup`. */
+    hookArgs?(command: (event: HandoffHookEvent) => string, stateDir: string): Promise<string[]>;
+    /** Host arguments that let the session read and write the chain directory. */
+    dirArgs?(dir: string): string[];
+    /** Host arguments that start a new interactive session with this first prompt. */
+    promptArgs(prompt: string): string[];
+    /** The user's Host arguments for the next session of this Family: no resume, continue or old first prompt. */
+    continueArgs(args: readonly string[]): string[];
+    /** Host arguments that resume this session in the same Account. */
+    resumeArgs(sessionId: string): string[];
+    /** Whether this run may start or receive a Handoff (headless runs, Codex `--remote`, Grok sandbox profiles). */
+    eligibility(args: readonly string[], account: Account, env: Env): Promise<HandoffEligibility>;
+    /** A Brief from the session's local records, without a model; undefined when nothing could be read. */
+    briefFromSession?(account: Account, session: {
+        id?: string;
+        transcriptPath?: string;
+    }): Promise<string | undefined>;
+    /** One-time hook installation for a Host without a launch option (Grok); the same contract as `quotaSetup`. */
+    hookSetup?: QuotaSetup;
 }
 /** Identity fields of a signed-in Account. */
 export interface AccountIdentity {
@@ -182,6 +244,45 @@ export type UsageResult = ({
     reason: 'no-source' | 'no-session' | 'unrecognized';
     detail?: string;
 };
+/** Why a model has no Tuning Suggestion, or `suggested` / `already-best` when it has an answer (spec §3.18). */
+export type TuningReason = 'suggested' | 'already-best' | 'insufficient-calls' | 'no-compactions' | 'no-optimum' | 'unknown-model' | 'observe-only';
+/** What one model's Compaction Threshold looks like in an Account's recent sessions. */
+export interface TuningModel {
+    model: string;
+    /** Assistant turns of this model in the window. */
+    calls: number;
+    /** Context window in tokens, inferred from the records (spec §3.18). */
+    contextWindow: number;
+    /** The Account's configured Compaction Threshold in tokens, or null for the Host default. */
+    configured: number | null;
+    /** The threshold in effect (configured, capped by the window), or null when unknown. */
+    effective: number | null;
+    compactions: {
+        total: number;
+        auto: number;
+        manual: number;
+        preTokensP50: number | null;
+        preTokensMax: number | null;
+    };
+    /** The estimated cheapest threshold; savings are null when there is no baseline to compare with. */
+    suggestion: {
+        threshold: number;
+        savedPercent: number | null;
+        savedWeighted: number | null;
+    } | null;
+    reason: TuningReason;
+}
+export type TuningResult = {
+    status: 'ok';
+    days: number;
+    /** Always true: the whole result is an estimate from replaying local records, not a measurement. */
+    estimate: true;
+    models: TuningModel[];
+} | {
+    status: 'unavailable';
+    reason: 'no-source' | 'no-session' | 'unrecognized';
+    detail?: string;
+};
 export type FindingLevel = 'ok' | 'warn' | 'fail';
 export interface FixResult {
     ok: boolean;

package/dist/testing/index.d.ts

@@ -17,6 +17,11 @@ export interface FakeHostOptions {
     selfSignal?: string;
     /** Seconds to sleep before exiting, so tests can signal it. */
     sleep?: number;
+    /**
+     * JavaScript run right after the start record, with `fs`, `path` and `process` in scope; for example to write
+     * the file a Host hook would write. It may call `process.exit`.
+     */
+    onStart?: string;
 }
 /**
  * Installs a fake Host executable named `name` that appends its argv, selected env and received signals

package/dist/testing/index.js

@@ -58,6 +58,7 @@ const rec = (o) => fs.appendFileSync(log, JSON.stringify(o) + '\\n')
 // Handlers first: tests signal the Host as soon as the start record appears.
 for (const s of ['SIGINT', 'SIGTERM', 'SIGHUP', 'SIGQUIT']) process.on(s, () => { rec({ signal: s }); process.exit(${opts.sleep ? 100 : 0}) })
 rec({ argv: process.argv.slice(2), env: process.env, pid: process.pid })
+${opts.onStart ? `{ const path = require('node:path'); ${opts.onStart} }` : ''}
 const finish = () => {
   ${opts.selfSignal ? `process.removeAllListeners(${JSON.stringify(opts.selfSignal)}); process.kill(process.pid, ${JSON.stringify(opts.selfSignal)})` : `process.exit(${opts.exitCode ?? 0})`}
 }