sideby 0.2.2 → 0.4.0

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

@@ -41,6 +41,7 @@ const FamilyInfo = Type.Object({
     installUrl: Str,
     installed: Type.Boolean(),
     plugin: Str,
+    tuning: Type.Boolean(),
 });
 const ShareModeSchema = Type.Union(['link', 'copy', 'link-or-copy', 'link-or-local', 'local', 'local-if-api', 'info', 'json-key'].map((m) => Type.Literal(m)));
 const FamilyDetail = Type.Intersect([
@@ -100,6 +101,50 @@ const Quota = Type.Union([
     }),
     Type.Object({ status: Type.Literal('unavailable'), reason: Str, detail: Type.Optional(Str) }),
 ]);
+const TuningModel = Type.Object({
+    model: Str,
+    calls: Type.Number(),
+    contextWindow: Type.Number(),
+    configured: Type.Union([Type.Number(), Type.Null()], {
+        description: 'Configured threshold in tokens; null is the Host default.',
+    }),
+    effective: Type.Union([Type.Number(), Type.Null()]),
+    compactions: Type.Object({
+        total: Type.Number({
+            description: 'All compactions, including those whose trigger the Host does not record.',
+        }),
+        auto: Type.Number(),
+        manual: Type.Number(),
+        preTokensP50: Type.Union([Type.Number(), Type.Null()]),
+        preTokensMax: Type.Union([Type.Number(), Type.Null()]),
+    }),
+    suggestion: Type.Union([
+        Type.Object({
+            threshold: Type.Number(),
+            savedPercent: Type.Union([Type.Number(), Type.Null()]),
+            savedWeighted: Type.Union([Type.Number(), Type.Null()]),
+        }),
+        Type.Null(),
+    ], { description: 'The estimated cheapest threshold; null when `reason` says why there is none.' }),
+    reason: Type.Union([
+        Type.Literal('suggested'),
+        Type.Literal('already-best'),
+        Type.Literal('insufficient-calls'),
+        Type.Literal('no-compactions'),
+        Type.Literal('no-optimum'),
+        Type.Literal('unknown-model'),
+        Type.Literal('observe-only'),
+    ]),
+});
+const Tuning = Type.Union([
+    Type.Object({
+        status: Type.Literal('ok'),
+        days: Type.Number(),
+        estimate: Type.Literal(true),
+        models: Type.Array(TuningModel),
+    }),
+    Type.Object({ status: Type.Literal('unavailable'), reason: Str, detail: Type.Optional(Str) }),
+]);
 const Usage = Type.Union([
     Type.Object({
         status: Type.Literal('ok'),
@@ -153,6 +198,27 @@ export const OUTPUT_SCHEMAS = {
         general: Type.Array(Finding),
         fixes: Type.Array(Type.Object({ account: Str, item: Str, code: Str, ok: Type.Boolean(), message: Str })),
     }, { title: 'sideby doctor --json' }),
+    'tune-change': Type.Object({
+        schemaVersion: Version,
+        account: Str,
+        action: Type.Union([Type.Literal('apply'), Type.Literal('undo')]),
+        applied: Type.Boolean({ description: 'True once the change was written (or undone).' }),
+        plan: Type.Optional(Type.Object({
+            status: Type.Union([Type.Literal('ready'), Type.Literal('unchanged'), Type.Literal('blocked')]),
+            file: Str,
+            link: Type.Boolean(),
+            affected: Type.Array(Str),
+            current: Type.Union([Type.Number(), Type.Null()]),
+            next: Type.Union([Type.Number(), Type.Null()]),
+            creates: Type.Boolean(),
+            reason: Type.Optional(Str),
+        })),
+        message: Type.Optional(Str),
+    }, { title: 'sideby tune apply|undo --json' }),
+    tune: Type.Object({
+        schemaVersion: Version,
+        accounts: Type.Array(Type.Object({ ref: Str, family: Str, tuning: Tuning })),
+    }, { title: 'sideby tune --json' }),
     quota: Type.Object({
         schemaVersion: Version,
         accounts: Type.Array(Type.Object({ ref: Str, kind: Kind, quota: Quota, usage: Usage })),
@@ -189,6 +255,53 @@ export const OUTPUT_SCHEMAS = {
         })),
     }, { title: 'sideby next --json' }),
     'quota-setup': Type.Object({ schemaVersion: Version, family: Str, applied: Type.Boolean(), plan: QuotaSetupPlan }, { title: 'sideby quota setup --json' }),
+    'handoff-status': Type.Object({
+        schemaVersion: Version,
+        auto: Type.Boolean(),
+        sameFamily: Type.Boolean(),
+        prepareAt: Type.Number(),
+        threshold: Type.Number(),
+        sideby: Type.Object({ ok: Type.Boolean(), problem: Type.Optional(Str) }),
+        families: Type.Array(Type.Object({
+            family: Str,
+            starts: Type.Array(Type.Union([Type.Literal('quota'), Type.Literal('limit')])),
+            ready: Type.Boolean(),
+            problems: Type.Array(Str),
+            notes: Type.Array(Str),
+            order: Type.Object({
+                policy: Type.Union([Type.Literal('pressure'), Type.Literal('order')]),
+                order: Type.Array(Str),
+                unknown: Type.Array(Str),
+            }),
+        })),
+        nextSteps: Type.Array(Str),
+    }, { title: 'sideby handoff status --json' }),
+    ...Object.fromEntries(['enable', 'disable'].map((sub) => [
+        `handoff-${sub}`,
+        Type.Object({
+            schemaVersion: Version,
+            applied: Type.Boolean(),
+            file: Str,
+            diff: Str,
+            settings: Type.Object({
+                auto: Type.Boolean(),
+                sameFamily: Type.Boolean(),
+                prepareAt: Type.Number(),
+                threshold: Type.Number(),
+                waitIfResetWithinMinutes: Type.Number(),
+                countdownSeconds: Type.Number(),
+                crossOrganization: Type.Array(Str),
+                families: Type.Record(Str, Type.Object({
+                    policy: Type.Union([Type.Literal('pressure'), Type.Literal('order')]),
+                    order: Type.Array(Str),
+                })),
+            }),
+            nextSteps: Type.Array(Str),
+        }, { title: `sideby handoff ${sub} --json` }),
+    ])),
+    'handoff-ready': Type.Object({ schemaVersion: Version, requested: Type.Literal(true), brief: Type.Optional(Str) }, { title: 'sideby handoff ready --json' }),
+    'handoff-setup': Type.Object({ schemaVersion: Version, family: Str, applied: Type.Boolean(), plan: QuotaSetupPlan }, { title: 'sideby handoff setup --json' }),
+    'handoff-teardown': Type.Object({ schemaVersion: Version, family: Str, ok: Type.Boolean(), message: Str, diff: Type.Optional(Str) }, { title: 'sideby handoff teardown --json' }),
     'quota-teardown': Type.Object({ schemaVersion: Version, family: Str, ok: Type.Boolean(), message: Str, diff: Type.Optional(Str) }, { title: 'sideby quota teardown --json' }),
     new: Type.Object({
         schemaVersion: Version,

package/dist/src/cli/main.d.ts

@@ -1,2 +1,7 @@
 #!/usr/bin/env node
+/**
+ * True below Node 22.18. npm's `engines` field only warns (`EBADENGINE`); this is the check that exits.
+ * `version` defaults to the running Node so tests can pass a string.
+ */
+export declare function nodeTooOld(version?: string): boolean;
 export declare function main(argv: string[]): Promise<number>;

package/dist/src/cli/main.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
-// Entry point. Keeps imports lazy so `statusline-tap`, which Claude Code runs on every refresh, starts fast.
+// Entry point. Keeps imports lazy so `statusline-tap` (run on every status line refresh) and `handoff-hook` (run on
+// every tool call while Auto Handoff is on) start fast.
 import { realpathSync } from 'node:fs';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 const MIN_NODE = [22, 18];
@@ -29,6 +30,16 @@ Usage:
   sideby quota [account]              quota and 7-day token usage
   sideby quota setup claude [--yes]   turn on Claude quota (shows the change first)
   sideby quota teardown claude        undo it, restoring the original file
+  sideby tune [account|family]        estimate the cheapest auto-compact threshold per model
+                                      from your last 7 days of sessions (read-only)
+  sideby handoff status               what Auto Handoff still needs on this machine
+  sideby handoff enable [--yes]       turn it on (shows the config change first); --same-family,
+                                      --order claude=codex001,cc002, --threshold n, --prepare-at n
+  sideby handoff disable [--yes]      turn it off, keeping the other settings
+  sideby handoff ready [--brief <f>]  inside a session sideby started with Auto Handoff: hand over to
+                                      the next account when this turn ends (config \`handoff\`)
+  sideby handoff setup grok [--yes]   add sideby's hook file so Grok can hand over at its limit
+  sideby handoff teardown grok        remove it
   sideby ui [--port n] [--no-open]    open the local panel
   sideby ui --background              same, without a terminal: keeps running after this command exits
   sideby ui --stop                    stop the background panel
@@ -40,7 +51,7 @@ Usage:
   sideby plugins                      list loaded plugins and load errors
 
 Options:
-  --json        machine-readable output (list, new, next, alias, doctor, quota, families, plugins, app)
+  --json        machine-readable output (list, new, next, alias, doctor, quota, tune, handoff, families, plugins, app)
   -h, --help    show this help; \`sideby <command> --help\` for new, alias, login, doctor, families
   -v, --version show the version
 
@@ -124,8 +135,12 @@ Examples:
   sideby families claude --json
 Exit: 0; 1 unknown family; 2 malformed command line.`,
 };
-function nodeTooOld() {
-    const [maj = 0, min = 0] = process.versions.node.split('.').map(Number);
+/**
+ * True below Node 22.18. npm's `engines` field only warns (`EBADENGINE`); this is the check that exits.
+ * `version` defaults to the running Node so tests can pass a string.
+ */
+export function nodeTooOld(version = process.versions.node) {
+    const [maj = 0, min = 0] = version.split('.').map(Number);
     return maj < MIN_NODE[0] || (maj === MIN_NODE[0] && min < MIN_NODE[1]);
 }
 const COMMANDS = {
@@ -138,6 +153,11 @@ const COMMANDS = {
     alias: { flags: ['json'] },
     doctor: { flags: ['fix', 'force', 'json'] },
     quota: { flags: ['json', 'yes'] },
+    tune: { flags: ['json', 'yes'] },
+    handoff: {
+        flags: ['json', 'yes', 'same-family', 'no-same-family'],
+        valued: ['brief', 'order', 'prepare-at', 'threshold', 'wait-minutes', 'countdown'],
+    },
     ui: { flags: ['no-open', 'background', 'stop', 'serve-detached'], valued: ['port'] },
     app: { flags: ['json'], valued: ['url'] },
     'shell-init': { flags: ['write'] },
@@ -146,10 +166,22 @@ const COMMANDS = {
 };
 export async function main(argv) {
     const [first, ...rest] = argv;
+    // Claude Code runs this on every status-line refresh. It must still launch the original command when Node is
+    // older than 22.18, so the check below does not apply here (spec §3.1).
     if (first === 'statusline-tap') {
         const { runStatuslineTap } = await import('../quota/statusline-tap.js');
         return runStatuslineTap(rest, process.env, process.stdin, process.stdout);
     }
+    // The handoff hook runs on every tool call while Auto Handoff is on; like the tap it comes before the Node check,
+    // so a Host never gets a version error from its own hook (spec §3.17).
+    if (first === 'handoff-hook') {
+        const { runHandoffHook } = await import('../handoff/hook.js');
+        return runHandoffHook(rest, process.env, process.stdin, process.stdout);
+    }
+    if (nodeTooOld()) {
+        console.error(`sideby needs Node ${MIN_NODE.join('.')} or newer (you have ${process.versions.node}). Upgrade: https://nodejs.org`);
+        return 1;
+    }
     if (first === '-v' || first === '--version' || first === 'version') {
         const { packageVersion } = await import('../core/version.js');
         console.log(packageVersion());
@@ -159,10 +191,6 @@ export async function main(argv) {
         console.log((rest[0] !== undefined && first === 'help' && COMMAND_HELP[rest[0]]) || HELP);
         return 0;
     }
-    if (nodeTooOld()) {
-        console.error(`sideby needs Node ${MIN_NODE.join('.')} or newer (you have ${process.versions.node}). Upgrade: https://nodejs.org`);
-        return 1;
-    }
     const cmd = first === undefined || first.startsWith('--') ? 'list' : first;
     const args = first === undefined || first.startsWith('--') ? argv : rest;
     const spec = COMMANDS[cmd];
@@ -225,6 +253,10 @@ export async function main(argv) {
                 return await cmds.cmdDoctor(parsed, io);
             case 'quota':
                 return await cmds.cmdQuota(parsed, io);
+            case 'tune':
+                return await cmds.cmdTune(parsed, io);
+            case 'handoff':
+                return await cmds.cmdHandoff(parsed, io);
             case 'ui':
                 return await cmds.cmdUi(parsed, io);
             case 'app':

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

@@ -16,6 +16,19 @@ export declare const aliasAccount: (value: AliasValue) => string;
 export declare const aliasArgs: (value: AliasValue | undefined) => string[];
 /** `aliases` as alias → Account ref, for lookups that ignore the arguments. */
 export declare function aliasRefs(aliases: Readonly<Record<string, AliasValue>> | undefined): Record<string, string>;
+export interface HandoffSettings {
+    auto: boolean;
+    sameFamily: boolean;
+    prepareAt: number;
+    threshold: number;
+    waitIfResetWithinMinutes: number;
+    countdownSeconds: number;
+    crossOrganization: string[];
+    families: Record<string, {
+        policy: 'pressure' | 'order';
+        order: string[];
+    }>;
+}
 export declare const ConfigSchema: Type.TObject<{
     $schema: Type.TOptional<Type.TString>;
     accounts: Type.TOptional<Type.TRecord<"^.*$", Type.TObject<{
@@ -34,16 +47,44 @@ export declare const ConfigSchema: Type.TObject<{
         noSymlink: Type.TOptional<Type.TBoolean>;
         credential: Type.TOptional<Type.TBoolean>;
     }>>>>;
+    accountTitle: Type.TOptional<Type.TBoolean>;
     resumeRouting: Type.TOptional<Type.TBoolean>;
+    handoff: Type.TOptional<Type.TObject<{
+        auto: Type.TOptional<Type.TBoolean>;
+        sameFamily: Type.TOptional<Type.TBoolean>;
+        prepareAt: Type.TOptional<Type.TInteger>;
+        threshold: Type.TOptional<Type.TInteger>;
+        waitIfResetWithinMinutes: Type.TOptional<Type.TInteger>;
+        countdownSeconds: Type.TOptional<Type.TInteger>;
+        crossOrganization: Type.TOptional<Type.TArray<Type.TString>>;
+        families: Type.TOptional<Type.TRecord<"^.*$", Type.TObject<{
+            policy: Type.TOptional<Type.TUnion<[Type.TLiteral<"pressure">, Type.TLiteral<"order">]>>;
+            order: Type.TOptional<Type.TArray<Type.TString>>;
+        }>>>;
+    }>>;
     shellInitFile: Type.TOptional<Type.TObject<{
         zsh: Type.TOptional<Type.TString>;
         bash: Type.TOptional<Type.TString>;
     }>>;
 }>;
 export type Config = Static<typeof ConfigSchema>;
+/** The `handoff` settings with every default filled in. */
+export declare function handoffSettings(config: Config): HandoffSettings;
 export declare class ConfigError extends UserError {
 }
 export declare function loadConfig(file: string): Promise<Config>;
+export type HandoffConfig = NonNullable<Config['handoff']>;
+/**
+ * `sideby handoff enable|disable` (spec §3.17): changes the config `handoff` key with `edit` (see `editConfigKey`
+ * for how the file is written). With `dryRun`, shows the change without writing.
+ */
+export declare function editConfigHandoff(file: string, edit: (current: HandoffConfig) => HandoffConfig, opts?: {
+    dryRun?: boolean;
+}): Promise<{
+    changed: boolean;
+    before: HandoffConfig | undefined;
+    after: HandoffConfig | undefined;
+}>;
 /**
  * Adds `alias → ref` to the config file's `aliases`, as `{ account, args }` when `args` is not empty (see
  * `editConfigAliases` for how the file is written). Refuses an invalid alias, or one that already starts another

package/dist/src/core/config.js

@@ -45,6 +45,35 @@ const describeAlias = (v) => {
     const args = aliasArgs(v);
     return args.length ? `${aliasAccount(v)} with ${args.join(' ')}` : aliasAccount(v);
 };
+const Percent = (description) => Type.Optional(Type.Integer({ minimum: 1, maximum: 100, description }));
+/** Auto Handoff (spec §3.17, ADR-0010). Every key is optional; `handoffSettings` fills the defaults. */
+const HandoffSchema = Type.Object({
+    auto: Type.Optional(Type.Boolean({
+        description: 'Hand a running session to the next account when its Quota runs low: only to other families and API accounts unless `sameFamily` is on. Off by default.',
+    })),
+    sameFamily: Type.Optional(Type.Boolean({
+        description: 'Also hand off to an account of the same family (cc001 → cc002). The kind vendors are most likely to act on. Off by default.',
+    })),
+    prepareAt: Percent('Quota Pressure at which the session starts keeping a Handoff Brief (default 80).'),
+    threshold: Percent('Quota Pressure at which the Handoff begins (default 95).'),
+    waitIfResetWithinMinutes: Type.Optional(Type.Integer({
+        minimum: 0,
+        description: 'Stay and wait when the full window resets within this many minutes (default 30; 0 never waits).',
+    })),
+    countdownSeconds: Type.Optional(Type.Integer({
+        minimum: 0,
+        description: 'Countdown before the next account starts; Enter cancels (default 10; 0 skips it).',
+    })),
+    crossOrganization: Type.Optional(Type.Array(Type.String(), {
+        description: 'Accounts (ref or short command) that may take over from an account of another organization.',
+    })),
+    families: Type.Optional(Type.Record(Type.String(), Type.Object({
+        policy: Type.Optional(Type.Union([Type.Literal('pressure'), Type.Literal('order')])),
+        order: Type.Optional(Type.Array(Type.String())),
+    }, { additionalProperties: false }), {
+        description: 'Handoff Order per family the session starts in: `pressure` (default) or an `order` list.',
+    })),
+}, { additionalProperties: false });
 export const ConfigSchema = Type.Object({
     $schema: Type.Optional(Type.String()),
     accounts: Type.Optional(Type.Record(Type.String(), Type.Object({ args: Type.Optional(Type.Array(Type.String())) }, { additionalProperties: false }), { description: 'Per-Account settings keyed by `<family>:<name>`.' })),
@@ -57,9 +86,13 @@ export const ConfigSchema = Type.Object({
         description: 'Per-Plugin settings; `enabled: false` turns a Plugin off.',
     })),
     extraSharedItems: Type.Optional(Type.Record(Type.String(), Type.Array(SharedItemSchema))),
+    accountTitle: Type.Optional(Type.Boolean({
+        description: 'Set the terminal title to `[<short command or account>]` when sideby starts an Account, and keep Hosts that allow it (Codex) from replacing it. Off by default.',
+    })),
     resumeRouting: Type.Optional(Type.Boolean({
         description: 'Make `sideby shell-init` also define Host-named functions (`claude`, `codex`, `grok`) that resume a session by id in the Account that holds it. Off by default.',
     })),
+    handoff: Type.Optional(HandoffSchema),
     shellInitFile: Type.Optional(Type.Object({
         zsh: Type.Optional(Type.String({ minLength: 1 })),
         bash: Type.Optional(Type.String({ minLength: 1 })),
@@ -68,6 +101,23 @@ export const ConfigSchema = Type.Object({
         description: 'Absolute or `~/` paths of files sideby rewrites with the `sideby shell-init <shell>` output whenever it adds an Account or an alias; source the file from your shell rc.',
     })),
 }, { additionalProperties: false, title: 'sideby config' });
+/** The `handoff` settings with every default filled in. */
+export function handoffSettings(config) {
+    const h = config.handoff ?? {};
+    return {
+        auto: h.auto ?? false,
+        sameFamily: h.sameFamily ?? false,
+        prepareAt: h.prepareAt ?? 80,
+        threshold: h.threshold ?? 95,
+        waitIfResetWithinMinutes: h.waitIfResetWithinMinutes ?? 30,
+        countdownSeconds: h.countdownSeconds ?? 10,
+        crossOrganization: [...(h.crossOrganization ?? [])],
+        families: Object.fromEntries(Object.entries(h.families ?? {}).map(([f, v]) => [
+            f,
+            { policy: v.policy ?? 'pressure', order: [...(v.order ?? [])] },
+        ])),
+    };
+}
 export class ConfigError extends UserError {
 }
 export async function loadConfig(file) {
@@ -92,6 +142,9 @@ export async function loadConfig(file) {
         const where = first?.instancePath || '/';
         throw new ConfigError(`${file}: ${where} ${first?.message ?? 'is invalid'}; see schemas/config.json`);
     }
+    const handoff = handoffSettings(data);
+    if (handoff.prepareAt >= handoff.threshold)
+        throw new ConfigError(`${file}: handoff.prepareAt (${handoff.prepareAt}) must be lower than handoff.threshold (${handoff.threshold}); lower prepareAt or raise threshold`);
     // TypeBox does not enforce key patterns on records; alias names become shell function names.
     for (const alias of Object.keys(data.aliases ?? {})) {
         const problem = aliasProblem(alias);
@@ -105,12 +158,14 @@ async function configTarget(file) {
     return (await lstatOrNull(file))?.isSymbolicLink() ? ((await realpathOrNull(file)) ?? file) : file;
 }
 /**
- * Re-reads the config file, lets `edit` change its `aliases`, and writes the result: every other key and their
- * order kept (with `$schema`), 2-space JSON with a trailing newline, atomically, keeping the file's mode (0600 for
- * a new file). Refuses, without writing, a file that is not valid JSON or not a valid config, or one that changed
- * while sideby wrote it. `edit` returns null to leave the file alone. `retry` names what to do again after a fix.
+ * Re-reads the config file, lets `edit` change one top-level `key` (the only two sideby writes are `aliases` and
+ * `handoff`, spec §3.10), and writes the result: every other key and their order kept (with `$schema`), 2-space JSON
+ * with a trailing newline, atomically, keeping the file's mode (0600 for a new file). Refuses, without writing, a
+ * file that is not valid JSON or not a valid config, a result that is not a valid config, or a file that changed
+ * while sideby wrote it. `edit` returns null to leave the file alone; `dryRun` returns the change without writing.
+ * `retry` names what to do again after a fix.
  */
-async function editConfigAliases(file, retry, edit) {
+async function editConfigKey(file, key, retry, edit, opts = {}) {
     const target = await configTarget(file);
     let raw = null;
     try {
@@ -135,19 +190,39 @@ async function editConfigAliases(file, retry, edit) {
             throw new ConfigError(`${file} does not match schemas/config.json; nothing was changed. Run \`sideby list\` to see why`);
         data = parsed;
     }
-    const current = (data.aliases ?? {});
-    const aliases = edit(current);
-    if (!aliases)
-        return current;
+    const before = data[key];
+    const after = edit(before);
+    if (after === null || JSON.stringify(after) === JSON.stringify(before))
+        return { changed: false, before, after: before };
     // A new file gets the schema link editors use for completion; an existing file keeps its keys in order.
-    const next = raw === null ? { $schema: 'https://unpkg.com/sideby/schemas/config.json', aliases } : { ...data, aliases };
+    const next = raw === null
+        ? { $schema: 'https://unpkg.com/sideby/schemas/config.json', [key]: after }
+        : { ...data, [key]: after };
+    if (!Value.Check(ConfigSchema, next))
+        throw new ConfigError(`the new ${key} would not match schemas/config.json`);
+    const h = handoffSettings(next);
+    if (h.prepareAt >= h.threshold)
+        throw new ConfigError(`handoff.prepareAt must be lower than handoff.threshold; fix them in ${file} and ${retry} again`);
+    if (opts.dryRun)
+        return { changed: true, before, after };
     const st = raw === null ? null : await lstatOrNull(target);
     if (raw === null)
         await mkdir(dirname(target), { recursive: true, mode: 0o700 });
     const written = await writeIfUnchanged(target, raw === null ? null : sha256(raw), `${JSON.stringify(next, null, 2)}\n`, st ? st.mode & 0o777 : 0o600);
     if (!written)
         throw new ConfigError(`${file} changed while sideby was writing it; nothing was changed. Try again`);
-    return aliases;
+    return { changed: true, before, after };
+}
+async function editConfigAliases(file, retry, edit) {
+    const r = await editConfigKey(file, 'aliases', retry, (current) => edit(current ?? {}));
+    return r.after ?? {};
+}
+/**
+ * `sideby handoff enable|disable` (spec §3.17): changes the config `handoff` key with `edit` (see `editConfigKey`
+ * for how the file is written). With `dryRun`, shows the change without writing.
+ */
+export function editConfigHandoff(file, edit, opts = {}) {
+    return editConfigKey(file, 'handoff', 'run the command', (current) => edit(current ?? {}), opts);
 }
 /**
  * Adds `alias → ref` to the config file's `aliases`, as `{ account, args }` when `args` is not empty (see

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

@@ -9,6 +9,18 @@ export interface MemoPass<T> {
     /** Ends the pass: the scope now holds only the files this pass asked for. */
     done(): void;
 }
+/**
+ * How a memo is kept on disk. `name` is its key in the cache file; bump `version` whenever the parsed value's shape
+ * or meaning changes, so a cache written by an older sideby is dropped instead of misread.
+ */
+export interface MemoPersist {
+    name: string;
+    version: number;
+}
+/** A memo as stored on disk: per scope, per file, the signature and the parsed value. */
+export type MemoDump = Record<string, Record<string, [sig: string, value: unknown]>>;
+/** Every memo created with `persist`, by name. */
+export declare const persistedMemos: Map<string, FileMemo<unknown>>;
 export declare class FileMemo<T> {
     #private;
     /** Counters for tests and timing. */
@@ -16,8 +28,19 @@ export declare class FileMemo<T> {
         hits: number;
         misses: number;
     };
+    /** True when a pass changed what is remembered since the last `dump`. */
+    dirty: boolean;
+    readonly persist?: MemoPersist;
+    constructor(persist?: MemoPersist);
     /** Starts a pass over `scope`, such as one Account's directory. */
     pass(scope: string): MemoPass<T>;
+    /** What is remembered, for the cache file; clears `dirty`. */
+    dump(): MemoDump;
+    /**
+     * Takes remembered parses from the cache file for scopes this process has not read yet. The values are trusted
+     * to have the shape `persist.version` stands for; a stale one never matches, because its signature differs.
+     */
+    restore(data: MemoDump): void;
     /** Files remembered for a scope (for tests). */
     size(scope: string): number;
     clear(): void;

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

@@ -1,10 +1,21 @@
 export function fileSignature(st) {
     return `${st.size}:${st.mtimeMs}:${st.ctimeMs}:${st.ino}`;
 }
+/** Every memo created with `persist`, by name. */
+export const persistedMemos = new Map();
 export class FileMemo {
     #scopes = new Map();
     /** Counters for tests and timing. */
     stats = { hits: 0, misses: 0 };
+    /** True when a pass changed what is remembered since the last `dump`. */
+    dirty = false;
+    persist;
+    constructor(persist) {
+        if (!persist)
+            return;
+        this.persist = persist;
+        persistedMemos.set(persist.name, this);
+    }
     /** Starts a pass over `scope`, such as one Account's directory. */
     pass(scope) {
         const before = this.#scopes.get(scope);
@@ -25,16 +36,42 @@ export class FileMemo {
                 return value;
             },
             done: () => {
+                if (!before || before.size !== seen.size || [...seen].some(([k, v]) => before.get(k) !== v))
+                    this.dirty = true;
                 this.#scopes.set(scope, seen);
             },
         };
     }
+    /** What is remembered, for the cache file; clears `dirty`. */
+    dump() {
+        this.dirty = false;
+        const out = {};
+        for (const [scope, files] of this.#scopes)
+            out[scope] = Object.fromEntries([...files].map(([path, e]) => [path, [e.sig, e.value]]));
+        return out;
+    }
+    /**
+     * Takes remembered parses from the cache file for scopes this process has not read yet. The values are trusted
+     * to have the shape `persist.version` stands for; a stale one never matches, because its signature differs.
+     */
+    restore(data) {
+        for (const [scope, files] of Object.entries(data)) {
+            if (this.#scopes.has(scope) || !files || typeof files !== 'object')
+                continue;
+            const map = new Map();
+            for (const [path, entry] of Object.entries(files))
+                if (Array.isArray(entry) && typeof entry[0] === 'string')
+                    map.set(path, { sig: entry[0], value: entry[1] });
+            this.#scopes.set(scope, map);
+        }
+    }
     /** Files remembered for a scope (for tests). */
     size(scope) {
         return this.#scopes.get(scope)?.size ?? 0;
     }
     clear() {
         this.#scopes.clear();
+        this.dirty = false;
         this.stats.hits = 0;
         this.stats.misses = 0;
     }

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

@@ -0,0 +1,17 @@
+import type { ReadyFile } from './handoff-chain.ts';
+/** Branch, uncommitted files and `git diff --stat`, as Markdown; '' outside a git work tree. Never commits or stashes. */
+export declare function gitSection(cwd: string): Promise<string>;
+export declare const ASSEMBLED_NOTE = "> Put together by sideby from the previous session\u2019s records, without a model; it may be incomplete. Check the repository before continuing.";
+/**
+ * Writes the final Brief to `target` (mode 600) and says where it came from: the user's or the session's Brief
+ * named in `ready`, the session's Brief already at `target`, else `assembled`, plus the repository state.
+ */
+export declare function finishBrief(opts: {
+    target: string;
+    ready: Pick<ReadyFile, 'brief' | 'briefSource'>;
+    assembled?: string;
+    cwd: string;
+}): Promise<{
+    path: string;
+    source: 'agent' | 'sideby' | 'user';
+}>;

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

@@ -0,0 +1,75 @@
+// Finishing a Handoff Brief before the next Account starts (spec §3.17 "Handoff Brief"): keep what the session or
+// the user wrote, else what sideby put together from the session's records, and add the repository state. No model.
+import { execFile } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import { promisify } from 'node:util';
+import { writeFileAtomic } from './fs-safe.js';
+const run = promisify(execFile);
+const GIT_TIMEOUT_MS = 3000;
+const MAX_STATUS_LINES = 50;
+async function git(cwd, args) {
+    const { stdout } = await run('git', args, { cwd, timeout: GIT_TIMEOUT_MS, maxBuffer: 1 << 20 });
+    return stdout.trimEnd();
+}
+/** Branch, uncommitted files and `git diff --stat`, as Markdown; '' outside a git work tree. Never commits or stashes. */
+export async function gitSection(cwd) {
+    try {
+        if ((await git(cwd, ['rev-parse', '--is-inside-work-tree'])) !== 'true')
+            return '';
+    }
+    catch {
+        return '';
+    }
+    const out = ['## Repository state (added by sideby)', '', `Working directory: ${cwd}`];
+    try {
+        out.push(`Branch: ${(await git(cwd, ['rev-parse', '--abbrev-ref', 'HEAD'])) || '(detached)'}`);
+    }
+    catch {
+        // a repository without commits
+    }
+    try {
+        const status = (await git(cwd, ['status', '--porcelain'])).split('\n').filter(Boolean);
+        out.push('', 'Uncommitted files:', '');
+        out.push(...(status.length ? status.slice(0, MAX_STATUS_LINES).map((l) => `    ${l}`) : ['    (none)']));
+        if (status.length > MAX_STATUS_LINES)
+            out.push(`    … and ${status.length - MAX_STATUS_LINES} more`);
+        const stat = await git(cwd, ['diff', '--stat']);
+        if (stat)
+            out.push('', 'Diff stat:', '', ...stat.split('\n').map((l) => `    ${l}`));
+    }
+    catch {
+        // git refused; the branch line is still useful
+    }
+    return `${out.join('\n')}\n`;
+}
+async function nonEmpty(path) {
+    if (!path)
+        return null;
+    try {
+        const text = await readFile(path, 'utf8');
+        return text.trim() ? text : null;
+    }
+    catch {
+        return null;
+    }
+}
+export const ASSEMBLED_NOTE = '> Put together by sideby from the previous session’s records, without a model; it may be incomplete. Check the repository before continuing.';
+/**
+ * Writes the final Brief to `target` (mode 600) and says where it came from: the user's or the session's Brief
+ * named in `ready`, the session's Brief already at `target`, else `assembled`, plus the repository state.
+ */
+export async function finishBrief(opts) {
+    let body = await nonEmpty(opts.ready.brief);
+    let source = opts.ready.briefSource ?? 'agent';
+    if (!body) {
+        body = await nonEmpty(opts.target);
+        source = 'agent';
+    }
+    if (!body) {
+        source = 'sideby';
+        body = `${ASSEMBLED_NOTE}\n\n${opts.assembled ?? 'sideby could not read the previous session’s records.\n'}`;
+    }
+    const repo = await gitSection(opts.cwd);
+    await writeFileAtomic(opts.target, `${body.trimEnd()}\n${repo ? `\n${repo}` : ''}`, 0o600);
+    return { path: opts.target, source };
+}