sideby 0.3.0 → 0.4.0

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

@@ -0,0 +1,88 @@
+import { planHandoff } from './handoff.js';
+import { windowReset } from './quota-levels.js';
+const domain = (email) => email.slice(email.lastIndexOf('@') + 1).toLowerCase();
+/** Organizations when both have one, else email domains when both have one, else the same. */
+export function sameOrganization(a, b) {
+    if (a?.org && b?.org)
+        return a.org.toLowerCase() === b.org.toLowerCase();
+    if (a?.email && b?.email)
+        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) {
+    if (origin.quota.status !== 'ok' || s.waitIfResetWithinMinutes <= 0)
+        return undefined;
+    let last;
+    for (const w of origin.quota.windows) {
+        if (w.usedPercent < s.threshold || windowReset(w.resetsAt, now))
+            continue;
+        const t = Date.parse(w.resetsAt);
+        if (!Number.isFinite(t))
+            return undefined;
+        last = Math.max(last ?? t, t);
+    }
+    if (last === undefined || last - now.getTime() > s.waitIfResetWithinMinutes * 60_000)
+        return undefined;
+    return new Date(last).toISOString();
+}
+/**
+ * One candidate's §3.13 state; API accounts are pickable here, as the last resort. An Account already at the user's
+ * threshold counts as full even below §3.13's 85%, or it would hand over again on its first tool call.
+ */
+function stateOf(c, s, now) {
+    const e = planHandoff(c.family, [c], now, { includeApi: true }).accounts[0];
+    if (e.state !== 'ready' || e.pressure === null || e.pressure < s.threshold || c.quota.status !== 'ok')
+        return e;
+    const resets = c.quota.windows
+        .filter((w) => w.usedPercent >= s.threshold && !windowReset(w.resetsAt, now))
+        .map((w) => Date.parse(w.resetsAt))
+        .filter(Number.isFinite);
+    return {
+        ...e,
+        state: 'full',
+        ...(resets.length ? { resetsAt: new Date(Math.max(...resets)).toISOString() } : {}),
+    };
+}
+export function selectNext(input) {
+    const { origin, settings: s, now } = input;
+    const until = waitUntil(origin, s, now);
+    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') {
+        list = family.order.map(refOf).flatMap((r) => (byRef.has(r) ? [byRef.get(r)] : []));
+    }
+    else {
+        // The Family by §3.13's ranking, then other Families' API accounts.
+        const own = input.candidates.filter((c) => c.family === origin.family);
+        const ranked = planHandoff(origin.family, own, now, { includeApi: true }).accounts.map((e) => byRef.get(e.ref));
+        list = [...ranked, ...input.candidates.filter((c) => c.family !== origin.family && c.kind === 'api')];
+    }
+    const eligible = list.filter((c) => !used.has(c.ref) &&
+        c.installed &&
+        c.receive &&
+        // An API account pays per request, so it gets past no vendor's limit: sameFamily does not apply to it.
+        (s.sameFamily || c.family !== origin.family || c.kind === 'api') &&
+        (allowed.has(c.ref) || sameOrganization(origin.identity, c.identity)));
+    const states = eligible.map((c) => ({ c, e: stateOf(c, s, now) }));
+    const first = states.find(({ e }) => e.state === 'ready' || e.state === 'unknown') ??
+        states.find(({ e }) => e.state === 'api');
+    if (first)
+        return { kind: 'pick', ref: first.c.ref };
+    const full = states
+        .filter(({ e }) => e.state === 'full' && e.resetsAt)
+        .sort((a, b) => Date.parse(a.e.resetsAt) - Date.parse(b.e.resetsAt))[0];
+    return {
+        kind: 'none',
+        reason: eligible.length
+            ? 'every account that may take over is full or signed out'
+            : 'no account may take over',
+        ...(full ? { earliestReset: { ref: full.c.ref, at: full.e.resetsAt } } : {}),
+    };
+}

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

@@ -0,0 +1,66 @@
+import type { Runtime } from '../runtime.ts';
+import { type HandoffSettings } from './config.ts';
+export interface HandoffFamilyStatus {
+    family: string;
+    /** What the Family can start; empty when it can only take over. */
+    starts: ('quota' | 'limit')[];
+    /** Whether sessions of this Family can start a Handoff now. */
+    ready: boolean;
+    /** What keeps it from starting one; each has a matching entry in `nextSteps`. */
+    problems: string[];
+    /** Worth knowing, but not in the way. */
+    notes: string[];
+    order: {
+        policy: 'pressure' | 'order';
+        order: string[];
+        unknown: string[];
+    };
+}
+export interface HandoffStatus {
+    auto: boolean;
+    sameFamily: boolean;
+    prepareAt: number;
+    threshold: number;
+    sideby: {
+        ok: boolean;
+        problem?: string;
+    };
+    families: HandoffFamilyStatus[];
+    /** Commands still to run, in order. Setup commands show their change first (exit 10). */
+    nextSteps: string[];
+}
+export declare function handoffStatus(rt: Runtime): Promise<HandoffStatus>;
+/** One `handoff` change; fields left out keep their value. The Panel and the CLI send the same shape. */
+export interface HandoffChange {
+    auto?: boolean;
+    sameFamily?: boolean;
+    prepareAt?: number;
+    threshold?: number;
+    waitIfResetWithinMinutes?: number;
+    countdownSeconds?: number;
+    /** Handoff Orders by Family; an empty list sends that Family back to ranking by quota. */
+    orders?: {
+        family: string;
+        order: string[];
+    }[];
+}
+/** A line diff of two small texts: unchanged lines start with two spaces, removed with `- `, added with `+ `. */
+export declare function lineDiff(before: string, after: string): string;
+/**
+ * Shows, or with `apply` writes, the `handoff` change (spec §3.17). Every other setting stays. Names in `order`
+ * must resolve to an Account.
+ */
+export declare function configureHandoff(rt: Runtime, change: HandoffChange, opts: {
+    apply: boolean;
+}): Promise<{
+    changed: boolean;
+    applied: boolean;
+    file: string;
+    diff: string;
+    settings: HandoffSettings;
+}>;
+/**
+ * After a session ends with Auto Handoff off: one line pointing at it when the Account's quota passed the threshold
+ * and its Family could start a Handoff; at most once a day. Null when there is nothing to say.
+ */
+export declare function handoffHint(rt: Runtime, ref: string): Promise<string | null>;

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

@@ -0,0 +1,198 @@
+// `sideby handoff status|enable|disable` (spec §3.17 "交给 AI 开启"): what Auto Handoff still needs on this machine,
+// and the one config change that turns it on or off. Status only reads; enable and disable write the `handoff` key.
+import { join } from 'node:path';
+import { HOOK_FAMILIES } from '../handoff/hook.js';
+import { editConfigHandoff, handoffSettings } from './config.js';
+import { UserError } from './errors.js';
+import { ensureChainDir, readJsonFile, writeJsonFile } from './handoff-chain.js';
+import { hookEntryWorks } from './handoff-run.js';
+import { sidebyBinProblem } from './launch.js';
+import { quotaPressure } from './quota-levels.js';
+export async function handoffStatus(rt) {
+    const s = rt.handoffSettings();
+    const accounts = await rt.accounts();
+    const aliases = Object.fromEntries(Object.entries(rt.config.aliases ?? {}).map(([k, v]) => [k, typeof v === 'string' ? v : v.account]));
+    const refs = new Set(accounts.map((a) => a.ref));
+    const binProblem = (await sidebyBinProblem(rt.env, 'the Host runs `sideby handoff-hook` for Auto Handoff')) ??
+        ((await hookEntryWorks(rt.env))
+            ? undefined
+            : 'the sideby on PATH is older than this one and has no `handoff-hook`; upgrade it with `npm i -g sideby`');
+    const steps = [];
+    if (!s.auto)
+        steps.push('sideby handoff enable');
+    if (binProblem)
+        steps.push('npm i -g sideby');
+    const families = [];
+    for (const f of rt.families.values()) {
+        if (!accounts.some((a) => a.family === f.id))
+            continue;
+        const builtIn = HOOK_FAMILIES.includes(f.id);
+        const starts = f.handoff && builtIn ? [...f.handoff.starts] : [];
+        const problems = [];
+        const notes = [];
+        if (!f.handoff)
+            notes.push(`${f.title} takes no part in Auto Handoff`);
+        else if (!starts.length)
+            notes.push(builtIn || !f.handoff.starts.length
+                ? `${f.title} can only take over, never start a handoff`
+                : `${f.title} comes from a plugin, so it can only take over for now`);
+        if (starts.includes('quota') && f.quotaSetup) {
+            const plan = await rt
+                .quotaSetup(f.id)
+                .plan()
+                .catch(() => null);
+            if (plan?.status !== 'enabled') {
+                problems.push(`${f.title} reports no quota to sideby yet`);
+                steps.push(`sideby quota setup ${f.id}`);
+            }
+        }
+        if (starts.length && f.handoff?.hookSetup) {
+            const plan = await rt
+                .handoffSetup(f.id)
+                .plan()
+                .catch(() => null);
+            if (plan?.status !== 'enabled') {
+                problems.push(`${f.title} has no sideby hook file yet`);
+                steps.push(`sideby handoff setup ${f.id}`, `sideby doctor ${f.id} --fix`);
+            }
+        }
+        if (f.id === 'codex' && starts.length)
+            notes.push('each Codex account asks once to trust sideby’s hooks: type /hooks in Codex and trust them');
+        if (f.id === 'grok' && starts.length)
+            notes.push('the `workspace` and `read-only` sandboxes can only take over; `strict` and custom ones take no part');
+        const fam = s.families[f.id] ?? { policy: 'pressure', order: [] };
+        const unknown = fam.order.filter((n) => !refs.has(aliases[n] ?? n));
+        if (fam.policy === 'order' && fam.order.length === 0) {
+            problems.push(`handoff.families.${f.id} has policy "order" but lists no account`);
+            steps.push(`sideby handoff enable --order ${f.id}=<account,account>`);
+        }
+        if (unknown.length)
+            notes.push(`order names ${unknown.join(', ')}, which sideby cannot find; they are skipped`);
+        families.push({
+            family: f.id,
+            starts,
+            ready: s.auto && !binProblem && starts.length > 0 && problems.length === 0,
+            problems,
+            notes,
+            order: { policy: fam.policy, order: fam.order, unknown },
+        });
+    }
+    return {
+        auto: s.auto,
+        sameFamily: s.sameFamily,
+        prepareAt: s.prepareAt,
+        threshold: s.threshold,
+        sideby: binProblem ? { ok: false, problem: binProblem } : { ok: true },
+        families,
+        nextSteps: steps,
+    };
+}
+/** A line diff of two small texts: unchanged lines start with two spaces, removed with `- `, added with `+ `. */
+export function lineDiff(before, after) {
+    const a = before.split('\n');
+    const b = after.split('\n');
+    // Longest common subsequence table; the settings block is a few dozen lines at most.
+    const lcs = a.map(() => new Array(b.length + 1).fill(0));
+    lcs.push(new Array(b.length + 1).fill(0));
+    for (let i = a.length - 1; i >= 0; i--)
+        for (let j = b.length - 1; j >= 0; j--)
+            lcs[i][j] = a[i] === b[j] ? lcs[i + 1][j + 1] + 1 : Math.max(lcs[i + 1][j], lcs[i][j + 1]);
+    const out = [];
+    let i = 0;
+    let j = 0;
+    while (i < a.length || j < b.length) {
+        if (i < a.length && j < b.length && a[i] === b[j]) {
+            out.push(`  ${a[i]}`);
+            i++;
+            j++;
+        }
+        else if (i < a.length && (j === b.length || lcs[i + 1][j] >= lcs[i][j + 1])) {
+            out.push(`- ${a[i]}`);
+            i++;
+        }
+        else {
+            out.push(`+ ${b[j]}`);
+            j++;
+        }
+    }
+    return out.join('\n');
+}
+const pretty = (v) => JSON.stringify(v ?? {}, null, 2);
+/**
+ * Shows, or with `apply` writes, the `handoff` change (spec §3.17). Every other setting stays. Names in `order`
+ * must resolve to an Account.
+ */
+export async function configureHandoff(rt, change, opts) {
+    const known = [...(await rt.accounts()).map((a) => a.ref), ...Object.keys(rt.config.aliases ?? {})];
+    for (const { family, order } of change.orders ?? []) {
+        if (!rt.families.has(family))
+            throw new UserError(`unknown family "${family}"; available: ${[...rt.families.keys()].join(', ')}`);
+        const missing = [];
+        for (const name of order)
+            await rt.resolve(name).catch(() => missing.push(name));
+        if (missing.length)
+            throw new UserError(`${missing.join(', ')} ${missing.length === 1 ? 'is' : 'are'} not an account or short command; use one of: ${known.join(', ')}`, { code: 'unknown-account' });
+    }
+    const edit = (current) => {
+        const next = { ...current };
+        for (const k of [
+            'auto',
+            'sameFamily',
+            'prepareAt',
+            'threshold',
+            'waitIfResetWithinMinutes',
+            'countdownSeconds',
+        ])
+            if (change[k] !== undefined)
+                next[k] = change[k];
+        if (change.orders?.length) {
+            const families = { ...(current.families ?? {}) };
+            for (const { family, order } of change.orders)
+                if (order.length)
+                    families[family] = { policy: 'order', order: [...order] };
+                else
+                    delete families[family];
+            next.families = families;
+        }
+        return next;
+    };
+    const file = rt.paths.configFile;
+    const r = await editConfigHandoff(file, edit, { dryRun: !opts.apply });
+    return {
+        changed: r.changed,
+        applied: r.changed && opts.apply,
+        file,
+        diff: r.changed
+            ? `--- ${join('sideby', 'config.json')} (handoff)\n${lineDiff(pretty(r.before), pretty(r.after))}\n`
+            : '',
+        settings: handoffSettings({ handoff: r.after }),
+    };
+}
+const HINT_EVERY_MS = 24 * 60 * 60 * 1000;
+/**
+ * After a session ends with Auto Handoff off: one line pointing at it when the Account's quota passed the threshold
+ * and its Family could start a Handoff; at most once a day. Null when there is nothing to say.
+ */
+export async function handoffHint(rt, ref) {
+    const s = rt.handoffSettings();
+    if (s.auto)
+        return null;
+    try {
+        const account = await rt.resolve(ref);
+        if (!rt.families.get(account.family)?.handoff?.starts.length || !HOOK_FAMILIES.includes(account.family))
+            return null;
+        const pressure = quotaPressure(await rt.quota(account), new Date());
+        if (pressure === null || pressure < s.threshold)
+            return null;
+        const file = join(rt.paths.stateDir, 'handoff', 'hint.json');
+        const last = (await readJsonFile(file))?.at;
+        if (last && Date.now() - Date.parse(last) < HINT_EVERY_MS)
+            return null;
+        await ensureChainDir(join(rt.paths.stateDir, 'handoff'));
+        await writeJsonFile(file, { at: new Date().toISOString() });
+        return `${account.ref} is at ${Math.round(pressure)}%. Sessions can hand their task to another account by themselves when quota runs low (off by default): see \`sideby handoff status\`.`;
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -1,3 +1,4 @@
+import { type ChildProcess } from 'node:child_process';
 import type { HookBus } from '../plugins/bus.ts';
 import type { Account, Env, FamilyDef } from '../types.ts';
 export interface PreparedLaunch {
@@ -15,6 +16,12 @@ export interface PreparedLaunch {
 export type HostLaunch = Pick<PreparedLaunch, 'family' | 'bin' | 'args' | 'env' | 'title'>;
 /** Finds an executable on PATH; returns null when the Host is not installed. */
 export declare function which(bin: string, env: Env): Promise<string | null>;
+/**
+ * Why a Host could not run `sideby` by name, or null when it can: something the Host runs on its own (the status line
+ * tap, the handoff hook) needs sideby installed on PATH, not the npx cache, which can disappear. `why` completes
+ * "sideby is not on PATH, and …".
+ */
+export declare function sidebyBinProblem(env: Env, why: string): Promise<string | null>;
 /**
  * Builds the Host's environment and arguments (spec §3.5):
  * copy the current env, clear Hijack Variables, merge the Secret File, set the select variable,
@@ -41,3 +48,11 @@ export declare function prepareLaunch(opts: {
  * default action so Ctrl-Z suspends sideby together with the Host and `fg` resumes both.
  */
 export declare function runHost(p: HostLaunch): Promise<number>;
+/**
+ * `runHost` with the child process exposed, so the Auto Handoff (spec §3.17) can end the Host and start the next
+ * Account in the same terminal. Same signal handling, exit codes and title as `runHost`.
+ */
+export declare function spawnHost(p: HostLaunch): {
+    child: ChildProcess;
+    exited: Promise<number>;
+};

package/dist/src/core/launch.js

@@ -2,6 +2,7 @@ import { spawn } from 'node:child_process';
 import { access, constants } from 'node:fs/promises';
 import { constants as osConstants } from 'node:os';
 import { delimiter, join } from 'node:path';
+import { realpathOrNull } from './fs-safe.js';
 import { readSecretFile } from './secret-file.js';
 /** Finds an executable on PATH; returns null when the Host is not installed. */
 export async function which(bin, env) {
@@ -19,6 +20,20 @@ export async function which(bin, env) {
     }
     return null;
 }
+/**
+ * Why a Host could not run `sideby` by name, or null when it can: something the Host runs on its own (the status line
+ * tap, the handoff hook) needs sideby installed on PATH, not the npx cache, which can disappear. `why` completes
+ * "sideby is not on PATH, and …".
+ */
+export async function sidebyBinProblem(env, why) {
+    const bin = await which('sideby', env);
+    if (!bin)
+        return `sideby is not on PATH, and ${why}; install it with \`npm i -g sideby\` and retry`;
+    const real = (await realpathOrNull(bin)) ?? bin;
+    if (bin.includes('/_npx/') || real.includes('/_npx/'))
+        return `sideby on PATH comes from the npx cache (${bin}), which can disappear; install it with \`npm i -g sideby\` and retry`;
+    return null;
+}
 /**
  * Builds the Host's environment and arguments (spec §3.5):
  * copy the current env, clear Hijack Variables, merge the Secret File, set the select variable,
@@ -91,11 +106,18 @@ export async function prepareLaunch(opts) {
  * default action so Ctrl-Z suspends sideby together with the Host and `fg` resumes both.
  */
 export function runHost(p) {
+    return spawnHost(p).exited;
+}
+/**
+ * `runHost` with the child process exposed, so the Auto Handoff (spec §3.17) can end the Host and start the next
+ * Account in the same terminal. Same signal handling, exit codes and title as `runHost`.
+ */
+export function spawnHost(p) {
     // OSC 0 sets the terminal's tab and window title; only on a terminal, never into a pipe.
     if (p.title && process.stdout.isTTY)
         process.stdout.write(`\x1b]0;${p.title}\x07`);
-    return new Promise((resolve) => {
-        const child = spawn(p.bin, p.args, { stdio: 'inherit', env: p.env });
+    const child = spawn(p.bin, p.args, { stdio: 'inherit', env: p.env });
+    const exited = new Promise((resolve) => {
         const ignore = () => { };
         const forwarded = new Set();
         const forward = (sig) => () => {
@@ -132,4 +154,5 @@ export function runHost(p) {
                 resolve(code ?? 1);
         });
     });
+    return { child, exited };
 }

package/dist/src/core/memo-store.d.ts

@@ -0,0 +1,20 @@
+/** At most one write per this many milliseconds; a cache a minute old only means re-parsing the newest logs. */
+export declare const SAVE_INTERVAL_MS = 60000;
+/** A write waits this long after the last read, so one Panel refresh over every Account is written as a whole. */
+export declare const SAVE_DELAY_MS = 2000;
+export declare function memoCachePath(stateDir: string): string;
+export interface MemoStore {
+    /** Loads the cache file once; later calls return the same promise. Never rejects. */
+    ready(): Promise<void>;
+    /**
+     * Schedules a write SAVE_DELAY_MS after the last call, and no sooner than SAVE_INTERVAL_MS after the previous
+     * write. The timer does not keep the process alive, so a short CLI run simply exits without writing.
+     */
+    saveSoon(): void;
+    /** Writes the cache now if a memo changed. Never rejects. */
+    save(): Promise<void>;
+}
+/** One store per state directory and process. */
+export declare function memoStore(stateDir: string, now?: () => number, delayMs?: number): MemoStore;
+/** Forgets the per-directory stores (for tests). */
+export declare function resetMemoStores(): void;

package/dist/src/core/memo-store.js

@@ -0,0 +1,92 @@
+// Keeps the persisted FileMemos (core/file-memo.ts) in `<stateDir>/cache/file-memo.json`, so a new process does not
+// parse every session log again: the Panel worker starts cold after each restart, reinstall or language switch,
+// and parsing the logs of a busy HOME takes seconds, while reading this file back takes milliseconds.
+//
+// The file holds token counts, session ids and log paths, never a credential; it is written atomically with mode
+// 600. Anything unexpected in it (another format, a parse error, a memo version that changed) is ignored and the
+// logs are parsed again, which gives the same results.
+import { mkdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { persistedMemos } from './file-memo.js';
+import { writeFileAtomic } from './fs-safe.js';
+const FORMAT = 1;
+/** At most one write per this many milliseconds; a cache a minute old only means re-parsing the newest logs. */
+export const SAVE_INTERVAL_MS = 60_000;
+/** A write waits this long after the last read, so one Panel refresh over every Account is written as a whole. */
+export const SAVE_DELAY_MS = 2_000;
+export function memoCachePath(stateDir) {
+    return join(stateDir, 'cache', 'file-memo.json');
+}
+const stores = new Map();
+/** One store per state directory and process. */
+export function memoStore(stateDir, now = Date.now, delayMs = SAVE_DELAY_MS) {
+    const known = stores.get(stateDir);
+    if (known)
+        return known;
+    const file = memoCachePath(stateDir);
+    let loading;
+    let writing;
+    let lastWrite = Number.NEGATIVE_INFINITY;
+    let timer;
+    const load = async () => {
+        try {
+            const data = JSON.parse(await readFile(file, 'utf8'));
+            if (data?.format !== FORMAT || !data.memos || typeof data.memos !== 'object')
+                return;
+            for (const [name, memo] of persistedMemos) {
+                const saved = data.memos[name];
+                if (saved && saved.version === memo.persist?.version && saved.data && typeof saved.data === 'object')
+                    memo.restore(saved.data);
+            }
+        }
+        catch {
+            // No cache yet, or an unreadable one: the logs are parsed as before.
+        }
+    };
+    const write = async () => {
+        if (![...persistedMemos.values()].some((m) => m.dirty))
+            return;
+        lastWrite = now();
+        const out = { format: FORMAT, memos: {} };
+        for (const [name, memo] of persistedMemos)
+            out.memos[name] = { version: memo.persist?.version ?? 0, data: memo.dump() };
+        try {
+            await mkdir(join(stateDir, 'cache'), { recursive: true, mode: 0o700 });
+            await writeFileAtomic(file, JSON.stringify(out));
+        }
+        catch {
+            // Best effort: a cache that could not be written only means a slower next start.
+        }
+    };
+    const store = {
+        ready: () => {
+            loading ??= load();
+            return loading;
+        },
+        async save() {
+            await store.ready();
+            while (writing)
+                await writing;
+            writing = write().finally(() => {
+                writing = undefined;
+            });
+            await writing;
+        },
+        saveSoon() {
+            if (timer)
+                clearTimeout(timer);
+            const wait = Math.max(delayMs, lastWrite + SAVE_INTERVAL_MS - now());
+            timer = setTimeout(() => {
+                timer = undefined;
+                void store.save();
+            }, wait);
+            timer.unref?.();
+        },
+    };
+    stores.set(stateDir, store);
+    return store;
+}
+/** Forgets the per-directory stores (for tests). */
+export function resetMemoStores() {
+    stores.clear();
+}

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

@@ -2,8 +2,13 @@ import type { Account, FamilyDef } from '../types.ts';
 export interface ResumeRoute {
     /** The session the Host arguments resume by id; absent when they resume none. */
     sessionId?: string;
-    /** The Account that last wrote that session; absent when no Account holds it. */
+    /** The Account that last wrote that session, or else the newest that started it; absent when none did. */
     account?: Account;
+    /** Set when `account` only started the session: the Host never saved it, so there is nothing to resume. */
+    neverSaved?: true;
 }
-/** Asks every Account of the Family for the session and picks the one that wrote it last. */
+/**
+ * Asks every Account of the Family for the session and picks the one that wrote it last. When none holds it, picks
+ * the one that started it last, if the Family can tell (ADR-0009).
+ */
 export declare function findResumeRoute(family: FamilyDef, accounts: readonly Account[], args: readonly string[]): Promise<ResumeRoute>;

package/dist/src/core/resume.js

@@ -1,15 +1,28 @@
-/** Asks every Account of the Family for the session and picks the one that wrote it last. */
+/** The Account whose `at` is newest, skipping those without one. */
+async function newest(accounts, at) {
+    const times = await Promise.all(accounts.map((a) => at(a).catch(() => undefined)));
+    let best;
+    accounts.forEach((account, i) => {
+        const t = times[i];
+        if (t !== undefined && (!best || t > best.at))
+            best = { account, at: t };
+    });
+    return best?.account;
+}
+/**
+ * Asks every Account of the Family for the session and picks the one that wrote it last. When none holds it, picks
+ * the one that started it last, if the Family can tell (ADR-0009).
+ */
 export async function findResumeRoute(family, accounts, args) {
     const sessionId = family.resumedSession?.(args);
     if (!sessionId || !family.sessionWrittenAt)
         return {};
     const own = accounts.filter((a) => a.family === family.id);
-    const written = await Promise.all(own.map((a) => family.sessionWrittenAt(a, sessionId).catch(() => undefined)));
-    let best;
-    own.forEach((account, i) => {
-        const at = written[i];
-        if (at !== undefined && (!best || at > best.at))
-            best = { account, at };
-    });
-    return best ? { sessionId, account: best.account } : { sessionId };
+    const holder = await newest(own, (a) => family.sessionWrittenAt(a, sessionId));
+    if (holder)
+        return { sessionId, account: holder };
+    const starter = family.sessionStartedAt
+        ? await newest(own, (a) => family.sessionStartedAt(a, sessionId))
+        : undefined;
+    return starter ? { sessionId, account: starter, neverSaved: true } : { sessionId };
 }

package/dist/src/core/tuning-apply.d.ts

@@ -0,0 +1,51 @@
+import type { Account, ReadContext } from '../types.ts';
+export declare const TUNE_KEY = "autoCompactWindow";
+export declare const MIN_WINDOW = 10000;
+export declare const MAX_WINDOW = 2000000;
+export interface TuneApplyPlan {
+    /** `ready`: will write; `unchanged`: already that value; `blocked`: `reason` says why and what to do. */
+    status: 'ready' | 'unchanged' | 'blocked';
+    /** The real file that will be written. */
+    file: string;
+    /** The Account's `settings.json` is a link to `file`. */
+    link: boolean;
+    /** Refs of the Accounts whose `settings.json` is `file`, the planned Account first. */
+    affected: string[];
+    /** The value in the file now, or null when the key is not there. */
+    current: number | null;
+    /** The size to set, or null to go back to the default (the key is removed). */
+    next: number | null;
+    /** The file does not exist yet and will be created. */
+    creates: boolean;
+    reason?: string;
+}
+export interface TuneUndoRecord {
+    file: string;
+    /** The value before sideby wrote, or null when the key was not there. */
+    previous: number | null;
+    /** The value written; null when the default was restored (the key removed). */
+    applied: number | null;
+    /** sideby created the file. */
+    created: boolean;
+    at: string;
+}
+/** What applying `value` to the Account would do. Writes nothing. */
+export declare function planTuneApply(account: Account, value: number | null, accounts: readonly Account[]): Promise<TuneApplyPlan>;
+export interface TuneChange {
+    ok: boolean;
+    message: string;
+    plan: TuneApplyPlan;
+}
+/** Plans, and writes only when the plan is `ready`. */
+export declare function applyTune(account: Account, value: number | null, accounts: readonly Account[], ctx: ReadContext): Promise<TuneChange>;
+/** What could be undone for the Account: the record, only while the key still holds the value sideby wrote. */
+export declare function tuneUndoInfo(account: Account, ctx: ReadContext): Promise<TuneUndoRecord | null>;
+/** Puts the key back as it was, only while it still holds what sideby wrote. */
+export declare function undoTune(account: Account, ctx: ReadContext): Promise<{
+    ok: boolean;
+    message: string;
+}>;
+/** The real file an Account's setting lives in (canonical, so Accounts sharing it get the same answer). */
+export declare function settingsFileOf(account: Account): Promise<string>;
+/** The size in the Account's settings file now, or null when there is none (the default). Reads only that key. */
+export declare function currentTuneValue(account: Account): Promise<number | null>;