sideby 0.3.0 → 0.4.1

package/dist/src/core/tuning-apply.js

@@ -0,0 +1,264 @@
+// Applying a Tuning Suggestion: writes one key, `autoCompactWindow`, of an Account's `settings.json` (spec §3.18,
+// ADR-0012). Everything else in the file is kept, nothing but that key is ever read out of it into an output, an
+// error or the undo record, and the write goes through `writeIfUnchanged`. A symlinked `settings.json` (settings
+// shared with the Main Account) is written at the real file it points to, and the plan names every Account that
+// shares it; a link is never created, replaced or retargeted.
+import { mkdir, readFile, rm, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { UserError } from './errors.js';
+import { fileHash, lstatOrNull, realpathOrNull, sha256, writeFileAtomic, writeIfUnchanged, } from './fs-safe.js';
+import { MAX_COMPACT_WINDOW, MIN_COMPACT_WINDOW } from './tuning.js';
+export const TUNE_KEY = 'autoCompactWindow';
+export const MIN_WINDOW = MIN_COMPACT_WINDOW;
+export const MAX_WINDOW = MAX_COMPACT_WINDOW;
+const MAX_BYTES = 5_000_000;
+const isObj = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+function checkValue(value) {
+    if (value === null)
+        return;
+    if (!Number.isInteger(value) || value < MIN_WINDOW || value > MAX_WINDOW)
+        throw new UserError(`${value} is not a usable size: give a whole number of tokens from ${MIN_WINDOW} to ${MAX_WINDOW}, for example 160000`, { code: 'bad-value' });
+}
+function detectIndent(text) {
+    const m = /^([ \t]+)"/m.exec(text);
+    if (!m)
+        return 2;
+    const lead = m[1];
+    return lead.startsWith('\t') ? '\t' : lead.length;
+}
+function render(obj, original) {
+    const out = JSON.stringify(obj, null, detectIndent(original));
+    return original.endsWith('\n') || original === '' ? `${out}\n` : out;
+}
+async function readObject(file) {
+    const st = await stat(file).catch(() => null);
+    if (!st || !st.isFile())
+        return { error: 'it is not a regular file' };
+    if (st.size > MAX_BYTES)
+        return { error: 'it is too large to be a settings file' };
+    const text = await readFile(file, 'utf8');
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return { error: 'it is not valid JSON' };
+    }
+    if (!isObj(parsed))
+        return { error: 'it is not a JSON object' };
+    return { text, obj: parsed };
+}
+/** The sizes models save for themselves under `modelSettings`: only those `autoCompactWindow` numbers are read. */
+function overridesOf(obj) {
+    const ms = obj.modelSettings;
+    if (!isObj(ms))
+        return [];
+    const out = [];
+    for (const [model, entry] of Object.entries(ms)) {
+        const v = isObj(entry) ? entry[TUNE_KEY] : undefined;
+        if (typeof v === 'number' && Number.isFinite(v))
+            out.push({ model, value: v });
+    }
+    return out;
+}
+/** Where the Account's settings really live, and whether `settings.json` is a link to it. */
+async function locate(account) {
+    const path = join(account.dir, 'settings.json');
+    const lst = await lstatOrNull(path);
+    // Every path is canonical (no link anywhere in it), so two Accounts that share a file compare equal and the undo
+    // record is found from either of them, even when HOME itself sits behind a link.
+    if (!lst) {
+        const dir = (await realpathOrNull(account.dir)) ?? account.dir;
+        return { file: join(dir, 'settings.json'), link: false, exists: false };
+    }
+    const real = await realpathOrNull(path);
+    if (!lst.isSymbolicLink())
+        return { file: real ?? path, link: false, exists: true };
+    return real
+        ? { file: real, link: true, exists: true }
+        : { file: path, link: true, exists: false, broken: true };
+}
+function recordPath(ctx, file) {
+    return join(ctx.stateDir, 'tune', `${sha256(file).slice(0, 16)}.json`);
+}
+async function readRecord(ctx, file) {
+    try {
+        const r = JSON.parse(await readFile(recordPath(ctx, file), 'utf8'));
+        if (r.file === file &&
+            (r.applied === null || typeof r.applied === 'number') &&
+            (r.previous === null || typeof r.previous === 'number'))
+            return r;
+    }
+    catch {
+        // no record
+    }
+    return null;
+}
+/** What applying `value` to the Account would do. Writes nothing. */
+export async function planTuneApply(account, value, accounts) {
+    checkValue(value);
+    const where = await locate(account);
+    const base = {
+        file: where.file,
+        link: where.link,
+        affected: [account.ref],
+        current: null,
+        next: value,
+        creates: false,
+        overrides: [],
+    };
+    if (where.broken)
+        return {
+            ...base,
+            status: 'blocked',
+            reason: 'settings.json is a link to a file that does not exist; fix the link first',
+        };
+    if (!where.exists)
+        return { ...base, status: value === null ? 'unchanged' : 'ready', creates: value !== null };
+    const read = await readObject(where.file);
+    if ('error' in read)
+        return {
+            ...base,
+            status: 'blocked',
+            reason: `settings.json cannot be changed safely: ${read.error}. Fix or move the file, then try again`,
+        };
+    const have = read.obj[TUNE_KEY];
+    const current = typeof have === 'number' && Number.isFinite(have) ? have : null;
+    const affected = [account.ref];
+    for (const other of accounts) {
+        if (other.ref === account.ref)
+            continue;
+        const loc = await locate(other);
+        if (loc.exists && loc.file === where.file)
+            affected.push(other.ref);
+    }
+    return {
+        ...base,
+        affected,
+        current,
+        overrides: overridesOf(read.obj),
+        status: current === value ? 'unchanged' : 'ready',
+    };
+}
+/** Plans, and writes only when the plan is `ready`. */
+export async function applyTune(account, value, accounts, ctx) {
+    const plan = await planTuneApply(account, value, accounts);
+    if (plan.status === 'blocked')
+        return { ok: false, plan, message: plan.reason ?? 'blocked' };
+    if (plan.status === 'unchanged')
+        return { ok: true, plan, message: 'It is already set to that value; nothing changed.' };
+    let before = null;
+    let obj = {};
+    let mode = 0o600;
+    if (!plan.creates) {
+        const read = await readObject(plan.file);
+        if ('error' in read)
+            return { ok: false, plan, message: `settings.json changed: ${read.error}` };
+        before = read.text;
+        obj = read.obj;
+        mode = (await stat(plan.file)).mode & 0o777;
+    }
+    const have = typeof obj[TUNE_KEY] === 'number' ? obj[TUNE_KEY] : null;
+    // Applying again over what sideby itself wrote keeps the original value, so one undo goes all the way back.
+    const earlier = await readRecord(ctx, plan.file);
+    const chained = earlier !== null && (earlier.applied ?? null) === have;
+    const previous = chained ? earlier.previous : have;
+    const changed = { ...obj };
+    if (value === null)
+        delete changed[TUNE_KEY];
+    else
+        changed[TUNE_KEY] = value;
+    const next = render(changed, before ?? '');
+    const wrote = await writeIfUnchanged(plan.file, before === null ? null : sha256(before), next, mode);
+    if (!wrote)
+        return {
+            ok: false,
+            plan,
+            message: 'settings.json changed while sideby was writing, so nothing was changed. Try again.',
+        };
+    const record = {
+        file: plan.file,
+        previous,
+        applied: value,
+        created: chained ? earlier.created : plan.creates,
+        at: new Date().toISOString(),
+    };
+    await mkdir(join(ctx.stateDir, 'tune'), { recursive: true });
+    await writeFileAtomic(recordPath(ctx, plan.file), `${JSON.stringify(record, null, 2)}\n`, 0o600);
+    return {
+        ok: true,
+        plan,
+        message: 'Done. New sessions use it; sessions already running keep the old value.',
+    };
+}
+/** What could be undone for the Account: the record, only while the key still holds the value sideby wrote. */
+export async function tuneUndoInfo(account, ctx) {
+    const where = await locate(account);
+    if (!where.exists)
+        return null;
+    const record = await readRecord(ctx, where.file);
+    if (!record)
+        return null;
+    const read = await readObject(where.file);
+    if ('error' in read || (read.obj[TUNE_KEY] ?? null) !== record.applied)
+        return null;
+    return record;
+}
+/** Puts the key back as it was, only while it still holds what sideby wrote. */
+export async function undoTune(account, ctx) {
+    const where = await locate(account);
+    const record = where.exists ? await readRecord(ctx, where.file) : null;
+    if (!record)
+        return { ok: false, message: 'There is nothing from sideby to undo for this account.' };
+    const read = await readObject(where.file);
+    if ('error' in read)
+        return { ok: false, message: `settings.json cannot be changed safely: ${read.error}.` };
+    if ((read.obj[TUNE_KEY] ?? null) !== record.applied)
+        return { ok: false, message: 'The setting was changed after sideby set it, so it was left alone.' };
+    const obj = { ...read.obj };
+    if (record.previous === null)
+        delete obj[TUNE_KEY];
+    else
+        obj[TUNE_KEY] = record.previous;
+    if (record.created && Object.keys(obj).length === 0) {
+        // Same care as a write: delete only if the file is still what was read.
+        if ((await fileHash(where.file)) !== sha256(read.text))
+            return {
+                ok: false,
+                message: 'settings.json changed while sideby was working, so nothing was changed. Try again.',
+            };
+        await rm(where.file, { force: true });
+    }
+    else {
+        const mode = (await stat(where.file)).mode & 0o777;
+        const wrote = await writeIfUnchanged(where.file, sha256(read.text), render(obj, read.text), mode);
+        if (!wrote)
+            return {
+                ok: false,
+                message: 'settings.json changed while sideby was writing, so nothing was changed. Try again.',
+            };
+    }
+    await rm(recordPath(ctx, where.file), { force: true });
+    return { ok: true, message: 'Undone. New sessions go back to the previous setting.' };
+}
+/** The real file an Account's setting lives in (canonical, so Accounts sharing it get the same answer). */
+export async function settingsFileOf(account) {
+    return (await locate(account)).file;
+}
+/**
+ * The size in the Account's settings file now (null: the default) and the sizes models save for themselves. Reads
+ * only those `autoCompactWindow` numbers.
+ */
+export async function readTuneSettings(account) {
+    const where = await locate(account);
+    if (!where.exists)
+        return { current: null, overrides: [] };
+    const read = await readObject(where.file);
+    if ('error' in read)
+        return { current: null, overrides: [] };
+    const v = read.obj[TUNE_KEY];
+    return {
+        current: typeof v === 'number' && Number.isFinite(v) ? v : null,
+        overrides: overridesOf(read.obj),
+    };
+}

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

@@ -0,0 +1,113 @@
+import type { TuningModel, TuningResult } from '../types.ts';
+/** Relative cost of a token, input = 1. These are Anthropic's published multipliers, not prices (spec §3.18). */
+export declare const WEIGHT: {
+    readonly input: 1;
+    readonly cacheRead: 0.1;
+    readonly write5m: 1.25;
+    readonly write1h: 2;
+    readonly output: 5;
+};
+/**
+ * The sizes Claude Code accepts for the auto-compact window: 100K to 1M tokens, never above the model's context
+ * window (https://code.claude.com/docs/en/model-config#set-the-auto-compact-window).
+ */
+export declare const MIN_COMPACT_WINDOW = 100000;
+export declare const MAX_COMPACT_WINDOW = 1000000;
+/** A model with fewer turns than this in the window gets no suggestion. */
+export declare const MIN_CALLS = 200;
+/** Candidate thresholds as a share of the model's context window. */
+export declare const CANDIDATE_PERCENTS: readonly [4, 5, 6, 7, 8, 9, 10, 12, 15, 20, 25, 30, 35, 40, 50, 60, 70, 80, 90, 95];
+/** One assistant turn: the whole context it ran with, what it wrote, and what it added to the prompt cache. */
+export interface Turn {
+    ts: number;
+    /** `input + cache read + cache write` tokens of the turn. */
+    ctx: number;
+    out: number;
+    write5m: number;
+    write1h: number;
+}
+/** One compaction the Host recorded. */
+export interface Compaction {
+    ts: number;
+    trigger: 'auto' | 'manual' | 'unknown';
+    pre: number;
+    post: number;
+}
+export interface ModelRecords {
+    model: string;
+    /** Turns of this model per session, each in time order. */
+    sessions: Turn[][];
+    compactions: Compaction[];
+    contextWindow: number;
+    /** Where the Host compacts when nothing is set (documented), or null when that is not known. */
+    defaultThreshold?: number | null;
+}
+export interface SummarizeOptions {
+    /** The Account's configured threshold in tokens; null is the Host default. */
+    configured: number | null;
+    /** The model's cost weights are known (a Claude model), so a suggestion is possible. */
+    known: boolean;
+    /** The Family may suggest at all (Codex only observes). */
+    mayRecommend: boolean;
+}
+export declare function summarizeModel(rec: ModelRecords, o: SummarizeOptions): TuningModel;
+/** The value stored under `key`, creating and storing `make()` first when there is none. */
+export declare function getOrCreate<K, V>(map: Map<K, V>, key: K, make: () => V): V;
+export interface TuningOptions {
+    /** The Account's configured threshold in tokens; null is the Host default. */
+    configured: number | null;
+    /** Whether a model's cost weights are known (spec §3.18); an unknown model gets no suggestion. */
+    known: (model: string) => boolean;
+    /** The Family may suggest at all (Codex only observes). */
+    mayRecommend: boolean;
+}
+/** The whole result for an Account: every model summarized, the busiest first. */
+export declare function tuningResult(days: number, records: ModelRecords[], o: TuningOptions): TuningResult;
+/**
+ * The one suggestion for Accounts that share a settings file: the busiest model across them that has one, with the
+ * Account it was seen on. Their other numbers stay as information.
+ */
+export declare function groupSuggestion(entries: readonly {
+    ref: string;
+    tuning: TuningResult;
+}[]): {
+    ref: string;
+    model: string;
+    threshold: number;
+    savedPercent: number | null;
+    calls: number;
+} | null;
+/** One Account's result, as the Panel and `sideby tune` list it. */
+export interface TuneEntry {
+    ref: string;
+    family: string;
+    tuning: TuningResult;
+}
+/** The Accounts that share one settings file: they get one suggestion and one thing to apply. */
+export interface TuneGroup {
+    /** The size in the file is outside what Claude Code accepts, so it cannot be offered again. */
+    outOfRange: boolean;
+    /** Models that save an auto-compact size of their own, which wins over the file's size for them. */
+    overrides: {
+        model: string;
+        value: number;
+    }[];
+    /** The real settings file. */
+    file: string;
+    members: string[];
+    /** The member to ask for the change and the undo (the one the suggestion came from). */
+    target: string;
+    /** The size in the file now, or null for the default. */
+    current: number | null;
+    pick: {
+        ref: string;
+        model: string;
+        threshold: number;
+        savedPercent: number | null;
+        calls: number;
+    } | null;
+    undo: {
+        value: number | null;
+        previous: number | null;
+    } | null;
+}

package/dist/src/core/tuning.js

@@ -0,0 +1,192 @@
+/** Relative cost of a token, input = 1. These are Anthropic's published multipliers, not prices (spec §3.18). */
+export const WEIGHT = { input: 1, cacheRead: 0.1, write5m: 1.25, write1h: 2, output: 5 };
+/**
+ * The sizes Claude Code accepts for the auto-compact window: 100K to 1M tokens, never above the model's context
+ * window (https://code.claude.com/docs/en/model-config#set-the-auto-compact-window).
+ */
+export const MIN_COMPACT_WINDOW = 100_000;
+export const MAX_COMPACT_WINDOW = 1_000_000;
+/** A model with fewer turns than this in the window gets no suggestion. */
+export const MIN_CALLS = 200;
+/** Candidate thresholds as a share of the model's context window. */
+export const CANDIDATE_PERCENTS = [
+    4, 5, 6, 7, 8, 9, 10, 12, 15, 20, 25, 30, 35, 40, 50, 60, 70, 80, 90, 95,
+];
+/** A suggestion must save at least this share against the current threshold; otherwise it is already the best. */
+const MIN_SAVING_PERCENT = 1;
+function median(values) {
+    if (!values.length)
+        return null;
+    const v = [...values].sort((a, b) => a - b);
+    const mid = v.length >> 1;
+    return v.length % 2 ? (v[mid] ?? 0) : ((v[mid - 1] ?? 0) + (v[mid] ?? 0)) / 2;
+}
+function writeWeight(t) {
+    const n = t.write5m + t.write1h;
+    return n > 0 ? (t.write5m * WEIGHT.write5m + t.write1h * WEIGHT.write1h) / n : WEIGHT.write5m;
+}
+/** Weighted cost of one session's turns if the Host compacted whenever the context reached `threshold`. */
+function replaySession(turns, threshold, post) {
+    const first = turns[0];
+    if (!first)
+        return 0;
+    const growth = [];
+    for (let i = 1; i < turns.length; i++) {
+        const d = (turns[i]?.ctx ?? 0) - (turns[i - 1]?.ctx ?? 0);
+        if (d >= 0)
+            growth.push(d);
+    }
+    // A recorded drop means the Host compacted there; what the turn then added is unknown, so use the usual growth.
+    const usual = median(growth) ?? 0;
+    let ctx = first.ctx;
+    let cost = ctx * writeWeight(first) + first.out * WEIGHT.output;
+    for (let i = 1; i < turns.length; i++) {
+        const t = turns[i];
+        const prev = turns[i - 1];
+        if (!t || !prev)
+            continue;
+        const d = t.ctx - prev.ctx;
+        const g = d >= 0 ? d : usual;
+        if (ctx + g >= threshold) {
+            // The whole context goes in as input, a summary of about `post` tokens comes out, and the next turn
+            // writes that summary to the cache again.
+            cost += ctx * WEIGHT.input + post * WEIGHT.output + post * WEIGHT.write5m;
+            ctx = post + g;
+        }
+        else {
+            cost += ctx * WEIGHT.cacheRead;
+            ctx += g;
+        }
+        cost += g * writeWeight(t) + t.out * WEIGHT.output;
+    }
+    return cost;
+}
+function replay(sessions, threshold, post) {
+    let total = 0;
+    for (const s of sessions)
+        total += replaySession(s, threshold, post);
+    return total;
+}
+const roundTokens = (n) => Math.round(n / 1000) * 1000;
+export function summarizeModel(rec, o) {
+    const calls = rec.sessions.reduce((n, s) => n + s.length, 0);
+    const auto = rec.compactions.filter((c) => c.trigger === 'auto');
+    const pre = rec.compactions.map((c) => c.pre).filter((n) => n > 0);
+    const posts = rec.compactions.map((c) => c.post).filter((n) => n > 0);
+    const autoPre = auto.map((c) => c.pre).filter((n) => n > 0);
+    // What is in effect: the configured size, else what the Host did, else where it compacts by default.
+    // A size outside 100K-1M is not one Claude Code runs with (the documentation does not say what it does with it),
+    // so it is not taken as the baseline.
+    const usable = o.configured !== null && o.configured >= MIN_COMPACT_WINDOW && o.configured <= MAX_COMPACT_WINDOW;
+    const effective = usable && o.configured !== null
+        ? Math.min(o.configured, rec.contextWindow)
+        : (median(autoPre) ?? rec.defaultThreshold ?? null);
+    const base = {
+        model: rec.model,
+        calls,
+        contextWindow: rec.contextWindow,
+        configured: o.configured,
+        effective: effective === null ? null : Math.round(effective),
+        compactions: {
+            total: rec.compactions.length,
+            auto: auto.length,
+            manual: rec.compactions.filter((c) => c.trigger === 'manual').length,
+            preTokensP50: pre.length ? Math.round(median(pre)) : null,
+            preTokensMax: pre.length ? Math.max(...pre) : null,
+        },
+        suggestion: null,
+        reason: 'observe-only',
+    };
+    const stop = (reason) => ({ ...base, reason });
+    if (!o.mayRecommend)
+        return stop('observe-only');
+    if (!o.known)
+        return stop('unknown-model');
+    if (calls < MIN_CALLS)
+        return stop('insufficient-calls');
+    // What is left after a compaction can only be read from compactions the Host recorded.
+    const post = median(posts);
+    if (post === null)
+        return stop('no-compactions');
+    // Only sizes Claude Code accepts: the lowest allowed one is always a candidate.
+    const top = Math.min(rec.contextWindow, MAX_COMPACT_WINDOW);
+    const candidates = new Set([MIN_COMPACT_WINDOW]);
+    for (const pct of CANDIDATE_PERCENTS)
+        candidates.add(roundTokens((rec.contextWindow * pct) / 100));
+    const sizes = [...candidates].filter((t) => t >= MIN_COMPACT_WINDOW && t <= top).sort((x, y) => x - y);
+    if (!sizes.length)
+        return stop('no-optimum');
+    let best = null;
+    for (const threshold of sizes) {
+        const cost = replay(rec.sessions, threshold, post);
+        // On a tie the larger threshold wins: fewer compactions for the same cost.
+        if (!best || cost < best.cost || (cost === best.cost && threshold > best.threshold))
+            best = { threshold, cost };
+    }
+    if (!best)
+        return stop('insufficient-calls');
+    // The lowest allowed size can still be the cheapest: that is a real answer, "as low as Claude Code lets you".
+    if (effective === null)
+        return {
+            ...base,
+            reason: 'suggested',
+            suggestion: { threshold: best.threshold, savedPercent: null, savedWeighted: null },
+        };
+    const current = replay(rec.sessions, effective, post);
+    const saved = current - best.cost;
+    const percent = current > 0 ? (saved / current) * 100 : 0;
+    if (percent < MIN_SAVING_PERCENT)
+        return stop('already-best');
+    return {
+        ...base,
+        reason: 'suggested',
+        suggestion: {
+            threshold: best.threshold,
+            savedPercent: Math.round(percent * 10) / 10,
+            savedWeighted: Math.round(saved),
+        },
+    };
+}
+/** The value stored under `key`, creating and storing `make()` first when there is none. */
+export function getOrCreate(map, key, make) {
+    const have = map.get(key);
+    if (have !== undefined)
+        return have;
+    const made = make();
+    map.set(key, made);
+    return made;
+}
+/** The whole result for an Account: every model summarized, the busiest first. */
+export function tuningResult(days, records, o) {
+    const models = records.map((rec) => summarizeModel(rec, {
+        configured: o.configured,
+        known: o.known(rec.model),
+        mayRecommend: o.mayRecommend,
+    }));
+    models.sort((a, b) => b.calls - a.calls);
+    return { status: 'ok', days, estimate: true, models };
+}
+/**
+ * The one suggestion for Accounts that share a settings file: the busiest model across them that has one, with the
+ * Account it was seen on. Their other numbers stay as information.
+ */
+export function groupSuggestion(entries) {
+    let best = null;
+    for (const e of entries) {
+        if (e.tuning.status !== 'ok')
+            continue;
+        for (const m of e.tuning.models) {
+            if (!m.suggestion)
+                continue;
+            if (!best || m.calls > best.calls)
+                best = {
+                    ref: e.ref,
+                    model: m.model,
+                    threshold: m.suggestion.threshold,
+                    savedPercent: m.suggestion.savedPercent,
+                    calls: m.calls,
+                };
+        }
+    }
+    return best;
+}

package/dist/src/families/claude/brief.d.ts

@@ -0,0 +1,5 @@
+import type { Account } from '../../types.ts';
+export declare function claudeBrief(account: Account, session: {
+    id?: string;
+    transcriptPath?: string;
+}): Promise<string | undefined>;

package/dist/src/families/claude/brief.js

@@ -0,0 +1,63 @@
+// A Brief from a Claude Code session file (`projects/<dir>/<id>.jsonl`), for when the session could not write one.
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { DigestBuilder, formatDigest } from '../shared/brief.js';
+const EDITS = new Set(['Edit', 'Write', 'MultiEdit', 'NotebookEdit']);
+async function findSession(dir, id) {
+    try {
+        for (const d of await readdir(join(dir, 'projects'), { withFileTypes: true })) {
+            if (!d.isDirectory())
+                continue;
+            const p = join(dir, 'projects', d.name, `${id}.jsonl`);
+            try {
+                await stat(p);
+                return p;
+            }
+            catch {
+                // not in this project
+            }
+        }
+    }
+    catch {
+        // no projects yet
+    }
+    return undefined;
+}
+export async function claudeBrief(account, session) {
+    const file = session.transcriptPath ?? (session.id ? await findSession(account.dir, session.id) : undefined);
+    if (!file)
+        return undefined;
+    let text;
+    try {
+        text = await readFile(file, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+    const b = new DigestBuilder();
+    for (const line of text.split('\n')) {
+        let o;
+        try {
+            o = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if ((o.type !== 'user' && o.type !== 'assistant') || o.isMeta === true)
+            continue;
+        const content = o.message?.content;
+        const blocks = typeof content === 'string' ? [{ type: 'text', text: content }] : Array.isArray(content) ? content : [];
+        for (const blk of blocks) {
+            if (blk.type === 'text' && typeof blk.text === 'string') {
+                if (o.type === 'user')
+                    b.user(blk.text);
+                else
+                    b.assistant(blk.text);
+            }
+            else if (blk.type === 'tool_use' && typeof blk.name === 'string' && EDITS.has(blk.name))
+                b.file(blk.input?.file_path ?? blk.input?.notebook_path);
+        }
+    }
+    const d = b.result();
+    return d ? formatDigest(d) : undefined;
+}

package/dist/src/families/claude/handoff-hook.d.ts

@@ -0,0 +1,2 @@
+import { type HookReader } from '../../handoff/reader.ts';
+export declare const claudeHookReader: HookReader;

package/dist/src/families/claude/handoff-hook.js

@@ -0,0 +1,31 @@
+// Claude Code for the handoff hook (spec §3.17): Quota Pressure from the status line tap's cache, and a used-up
+// Quota told apart from a transient rate limit. Leaf module: the hook runs on every tool call.
+import { quotaPressure } from '../../core/quota-levels.js';
+import { field } from '../../handoff/reader.js';
+import { accountNameFromEnv, cacheStateDir, readQuotaCache } from './quota-cache.js';
+/** Claude Code's wording when a subscription window is used up (as opposed to an overloaded server). */
+const USED_UP = /usage limit|limit reached|out of (extra )?usage/i;
+export const claudeHookReader = {
+    async pressure(_input, env, now) {
+        const name = accountNameFromEnv(env);
+        if (!name)
+            return null;
+        try {
+            const cache = await readQuotaCache(cacheStateDir(env), name);
+            if (cache.status !== 'ok')
+                return null;
+            return quotaPressure({ ...cache, source: 'statusline' }, now);
+        }
+        catch {
+            return null;
+        }
+    },
+    limitHit(input, pressure, threshold) {
+        if (field(input, 'error') !== 'rate_limit')
+            return false;
+        if (pressure !== null && pressure >= threshold)
+            return true;
+        const text = `${field(input, 'error_details', 'errorDetails') ?? ''} ${field(input, 'last_assistant_message', 'lastAssistantMessage') ?? ''}`;
+        return USED_UP.test(text);
+    },
+};

package/dist/src/families/claude/handoff.d.ts

@@ -0,0 +1,5 @@
+import type { FamilyHandoff } from '../../types.ts';
+import { type ArgRules } from '../shared/handoff-args.ts';
+/** From `claude --help`: options that take a value, so it is never mistaken for the old prompt. */
+export declare const CLAUDE_ARGS: ArgRules;
+export declare const claudeHandoff: FamilyHandoff;