@andorra-labs/code 0.0.0-stage → 0.1.5

package/dist/src/sessions.js

@@ -0,0 +1,620 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { mkdir, readFile, readdir, rename, rm, writeFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { stripVTControlCharacters } from 'node:util';
+import { setTimeout as delay } from 'node:timers/promises';
+import { decodeDoubleEscapedSummary } from './completion.js';
+/** Extract a short local task label without a model request. */
+export const sessionName = (prompt) => {
+    const clean = stripVTControlCharacters(prompt)
+        .replace(/https?:\/\/\S+/gi, ' ')
+        .replace(/[a-z]:[\\/][^\s"<>|]*/gi, ' ')
+        .replace(/(?:^|\s)[/~][\w./-]+/g, ' ')
+        .replace(/[\x00-\x09\x0b-\x1f\x7f-\x9f\u202a-\u202e\u2066-\u2069]/g, ' ');
+    const first = clean.split(/\n/).map(line => line.replace(/^\s*[#>*-]+\s*/, '').trim()).find(Boolean) ?? '';
+    const focused = first.replace(/^(?:(?:one[- ]shot|build|task|coding|implementation|feature)\s+)*(?:prompt|request|instructions?)\s*[:\u2014\u2013-]+\s*/i, '')
+        .replace(/^(?:hi|hello|hey)[!,.: ]+/i, '');
+    const words = focused.match(/[\p{L}\p{N}][\p{L}\p{N}'-]*/gu) ?? [];
+    const useful = words.filter(word => !/^(please|can|could|you|would|the|a|an|my|me|to|i|want|need|inside)$/i.test(word));
+    return [...(useful.length ? useful : words).slice(0, 5), 'coding', 'task', 'session'].slice(0, Math.max(3, Math.min(5, useful.length || words.length))).map(word => word.slice(0, 32)).join(' ');
+};
+/**
+ * The most ancestors a record may name.
+ *
+ * The lineage is kept with the fork so that the nearest ancestor still on the machine can be
+ * found when a session in the middle is deleted. The bound keeps the record small, and a lineage
+ * deeper than this keeps the nearest entries, which are the ones that lookup needs.
+ */
+export const MAX_LINEAGE_ENTRIES = 64;
+/**
+ * Whether a fork may extend this lineage.
+ *
+ * The chain of ancestors and the fork points that go with it are what make the totals exact, so
+ * they are kept whole: a chain that was cut short would lose the older ancestors, and a session
+ * deleted from beyond the cut would be counted twice. A lineage that has been continued this
+ * many times is not continued again.
+ */
+export function canExtendLineage(ancestors) {
+    return (ancestors?.length ?? 0) < MAX_LINEAGE_ENTRIES;
+}
+/** The lineage a fork records: the chain it came through. */
+export function lineageThrough(ancestors, id) {
+    return [...(ancestors ?? []), id];
+}
+/**
+ * The fork points a fork records: the lineage's state when each ancestor was made, oldest
+ * first, with the point the fork itself was made at.
+ *
+ * The chain of ids says who the ancestors were; the chain of points says what the lineage
+ * looked like at each of those moments, which is what tells the work an ancestor had done by
+ * the time of the fork from the work it did afterwards.
+ */
+export function lineagePoints(parent, parentUsage, parentTurns) {
+    return [...(parent.lineage ?? []), { usage: parentUsage, turns: parentTurns }].slice(-MAX_LINEAGE_ENTRIES);
+}
+// Browser runtime metadata belongs only to browser-history, never the primary record.
+export function savedSessionFields(session) {
+    const { version, id, name, workspace, updatedAt, history, usage, contextHistory, parentId, inheritedUsage, inheritedTurns, ancestors, lineage, projectId, trajectoryId, widgets, context, archived, autoArchived, renamed } = session;
+    return { version, id, name, workspace, updatedAt, history, usage, contextHistory, parentId, projectId, widgets,
+        ...(context === undefined ? {} : { context }),
+        ...(inheritedUsage === undefined ? {} : { inheritedUsage }),
+        ...(inheritedTurns === undefined ? {} : { inheritedTurns }),
+        ...(ancestors === undefined ? {} : { ancestors }),
+        ...(lineage === undefined ? {} : { lineage }),
+        // The log a session's conversation was written to is part of the session: a copy that left it
+        // behind would send the next reader to a file that is not there.
+        ...(trajectoryId === undefined ? {} : { trajectoryId }),
+        ...(archived === undefined ? {} : { archived }), ...(autoArchived === undefined ? {} : { autoArchived }),
+        ...(renamed === undefined ? {} : { renamed }) };
+}
+export const primaryDigest = (session) => createHash('sha256').update(JSON.stringify(savedSessionFields(session))).digest('hex');
+/**
+ * What an account has done on this machine, in totals.
+ *
+ * The counts cover every saved session, not only the ones the rail happens to list, so a portal
+ * can answer "how many sessions were created" without the caller holding the records.
+ */
+/** The usage a run's own record holds, when the record is there and says something. */
+async function readRunUsage(path) {
+    try {
+        const value = JSON.parse(await readFile(path, 'utf8'));
+        const usage = value.usage;
+        if (!usage || typeof usage !== 'object')
+            return undefined;
+        // A damaged record can hold a negative counter, and a saved session's counters are refused
+        // for the same reason: a total that counts one is not a count, and the portal would show the
+        // account's usage as less than nothing.
+        if (![usage.inputTokens, usage.outputTokens, usage.requests].every(number => typeof number === 'number' && Number.isFinite(number) && number >= 0))
+            return undefined;
+        return usage;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function emptySessionStats() {
+    return { total: 0, archived: 0, turns: 0, inputTokens: 0, outputTokens: 0, requests: 0, projects: 0 };
+}
+/**
+ * Carry the rail's own fields onto a record a surface that does not own them is about to save.
+ *
+ * Filing and the rename pin are the rail's changes, written by the app-server under the
+ * per-session mutation lock. A surface that keeps its own copy of the session — the CLI holds
+ * the one it read when the command started — would otherwise save that copy back and silently
+ * undo a change the user made elsewhere: an archive this command returns to the working rail, a
+ * name the user chose replaced by an auto-titled one. While the stored record says the user
+ * chose the name, that name and its pin survive; its filing carries over in both directions,
+ * because for a surface with no live state of its own the stored record is the only answer
+ * there is. The caller holds the mutation lock, so nothing can change the stored record in
+ * between. The browser surface applies the same rule inline, with one exemption: the save that
+ * accepts a prompt clears the flag, because live work belongs on the working rail.
+ */
+export function carryRailOwnedFields(record, stored) {
+    if (stored === undefined || typeof stored !== 'object' || stored.id !== record.id)
+        return;
+    if (stored.renamed === true && typeof stored.name === 'string') {
+        record.name = stored.name;
+        record.renamed = true;
+    }
+    if (stored.archived !== undefined)
+        record.archived = stored.archived;
+    else
+        delete record.archived;
+    if (stored.autoArchived !== undefined)
+        record.autoArchived = stored.autoArchived;
+    else
+        delete record.autoArchived;
+}
+/**
+ * A saved history as a reader displays it. A turn recorded before completion parsing decoded a
+ * twice-escaped summary still holds a backslash and an "n" where its line breaks belong, and its
+ * markdown draws as one literal paragraph; the stored record is left as written.
+ */
+export function displayHistory(history) {
+    return history.map(turn => {
+        const summary = decodeDoubleEscapedSummary(turn.completion.summary);
+        return summary === turn.completion.summary ? turn : { ...turn, completion: { ...turn.completion, summary } };
+    });
+}
+/** Stable opaque grouping key derived from the raw workspace path, before any secret redaction. */
+export const projectIdentity = (workspace) => createHash('sha256').update(workspace).digest('hex').slice(0, 16);
+const validId = (id) => /^[a-f0-9-]{36}$/i.test(id);
+/** Validate retained records before allowing them to become resumable sessions. */
+export function validSavedSession(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const session = value;
+    // A turn's optional `direction` is rendered directly by clients (the desktop leads a continued
+    // turn's row with it): a non-string from a hand-edited or corrupted record must not reach the
+    // typed protocol, where an object would crash the view that reads it.
+    // A turn's attachment refs are rendered by clients (`.map`) and fed to the model-history
+    // builder, so a truthy non-array or a malformed ref must not survive validation into either.
+    const validAttachment = (value) => {
+        if (!value || typeof value !== 'object' || Array.isArray(value))
+            return false;
+        const ref = value;
+        return typeof ref.id === 'string' && (ref.kind === 'text' || ref.kind === 'image' || ref.kind === 'file')
+            && typeof ref.name === 'string' && typeof ref.path === 'string'
+            && typeof ref.bytes === 'number' && Number.isFinite(ref.bytes) && ref.bytes >= 0
+            && (ref.lines === undefined || typeof ref.lines === 'number' && Number.isFinite(ref.lines) && ref.lines >= 0)
+            && (ref.directory === undefined || typeof ref.directory === 'boolean')
+            && (ref.mimeType === undefined || ref.mimeType === 'image/png' || ref.mimeType === 'image/jpeg');
+    };
+    const validHistory = (history) => Array.isArray(history) && history.every(turn => typeof turn?.task === 'string' && typeof turn.completion?.summary === 'string' && Array.isArray(turn.completion.tests) && turn.completion.tests.every((test) => typeof test === 'string')
+        && (turn.direction === undefined || typeof turn.direction === 'string')
+        && (turn.attachments === undefined || Array.isArray(turn.attachments) && turn.attachments.every(validAttachment)));
+    // Optional cache counters come from untrusted saved JSON; absent is valid, but a
+    // present counter must be a finite nonnegative number or resume arithmetic corrupts.
+    const validCounter = (value) => value === undefined || (typeof value === 'number' && Number.isFinite(value) && value >= 0);
+    // A usage block read from untrusted saved JSON: the three counters it must carry, and the
+    // optional cache counters, are all finite nonnegative numbers.
+    const validUsage = (value) => !!value && typeof value === 'object'
+        && ['requests', 'inputTokens', 'outputTokens'].every(key => {
+            const counter = value[key];
+            return typeof counter === 'number' && Number.isFinite(counter) && counter >= 0;
+        })
+        && validCounter(value.cacheRead) && validCounter(value.cacheWrite);
+    // A lineage's points are cumulative snapshots of the work: each one is at least the one before
+    // it, none of them is more than the record's own totals, and none of them counts more turns
+    // than the record has. A record that breaks these would make the totals drop a turn or a
+    // counter without saying so.
+    const validLineage = (lineage, usage, historyLength, baseline) => {
+        // An empty lineage names no fork point, so the record carries no fork at all: it is refused
+        // rather than read as one with a point that is not there.
+        if (!Array.isArray(lineage) || lineage.length === 0 || lineage.length > MAX_LINEAGE_ENTRIES)
+            return false;
+        let previous;
+        let previousTurns = 0;
+        for (const point of lineage) {
+            if (!point || typeof point !== 'object')
+                return false;
+            const turns = point.turns;
+            if (typeof turns !== 'number' || !Number.isSafeInteger(turns) || turns < 0 || turns > historyLength)
+                return false;
+            // The turns do not go backwards either: a point that does would make the totals count a
+            // turn twice.
+            if (turns < previousTurns)
+                return false;
+            previousTurns = turns;
+            if (!validUsage(point.usage))
+                return false;
+            const snapshot = point.usage;
+            if (previous && (snapshot.inputTokens < previous.inputTokens || snapshot.outputTokens < previous.outputTokens
+                || snapshot.requests < previous.requests))
+                return false;
+            if (usage && (snapshot.inputTokens > usage.inputTokens || snapshot.outputTokens > usage.outputTokens
+                || snapshot.requests > usage.requests))
+                return false;
+            previous = snapshot;
+        }
+        // The last point is the point the record was forked with, and the record says so in its own
+        // baseline. The two have to agree: the totals read the last point, and a smaller one would
+        // count the copied work again while a larger one would leave the record's own work out.
+        const last = lineage[lineage.length - 1];
+        if (!baseline.usage || !validUsage(baseline.usage) || baseline.turns === undefined)
+            return false;
+        if (!last.usage || last.usage.inputTokens !== baseline.usage.inputTokens
+            || last.usage.outputTokens !== baseline.usage.outputTokens
+            || last.usage.requests !== baseline.usage.requests || last.turns !== baseline.turns)
+            return false;
+        return true;
+    };
+    return session.version === 1 && typeof session.id === 'string' && validId(session.id) && typeof session.name === 'string' && typeof session.workspace === 'string' && Number.isFinite(Date.parse(session.updatedAt)) &&
+        validHistory(session.history) && (session.contextHistory === undefined || validHistory(session.contextHistory)) &&
+        // Optional identifiers are read by clients that render them: a non-string `parentId` used to pass
+        // validation and then throw while a view sliced it.
+        (session.parentId === undefined || typeof session.parentId === 'string') &&
+        // The lineage is read by the totals to find the surviving ancestor, so every entry has to be
+        // an id: a malformed one would send the lookup somewhere it does not belong.
+        (session.ancestors === undefined || (Array.isArray(session.ancestors) && session.ancestors.length <= MAX_LINEAGE_ENTRIES
+            && session.ancestors.every((entry) => typeof entry === 'string' && validId(entry)))) &&
+        // The fork points are read as the lineage's work at each fork, so a malformed count or a
+        // malformed turn length refuses the record rather than moving the totals.
+        (session.inheritedTurns === undefined || (Number.isSafeInteger(session.inheritedTurns)
+            && session.inheritedTurns >= 0 && session.inheritedTurns <= session.history.length)) &&
+        (session.lineage === undefined || validLineage(session.lineage, session.usage, session.history.length, { usage: session.inheritedUsage, turns: session.inheritedTurns })) &&
+        (session.projectId === undefined || typeof session.projectId === 'string') &&
+        // The log a session names is read as a file stem, so a malformed one has to refuse the record
+        // rather than send the lookup somewhere it does not belong.
+        (session.trajectoryId === undefined || (typeof session.trajectoryId === 'string' && /^[A-Za-z0-9_-]{1,64}$/.test(session.trajectoryId))) &&
+        // Widget sections are rendered verbatim beside the plan, so a malformed entry refuses the
+        // record on the same terms as a malformed turn.
+        (session.widgets === undefined || Array.isArray(session.widgets) && session.widgets.every(widget => !!widget && typeof widget === 'object' && typeof widget.id === 'string' && typeof widget.name === 'string'
+            && typeof widget.description === 'string' && typeof widget.value === 'string')) &&
+        // The context reading is a token count drawn against a window, so either figure out of range
+        // refuses the record on the same terms as a malformed usage block.
+        (session.context === undefined || (!!session.context && typeof session.context === 'object'
+            && Number.isSafeInteger(session.context.usedTokens) && session.context.usedTokens > 0
+            && (session.context.window === undefined || (Number.isSafeInteger(session.context.window) && session.context.window > 0))
+            && (session.context.cacheRead === undefined || (Number.isSafeInteger(session.context.cacheRead) && session.context.cacheRead >= 0)))) &&
+        // The archive flag gates a row off the rail, so a non-boolean in saved JSON must fail closed.
+        (session.archived === undefined || typeof session.archived === 'boolean') &&
+        (session.autoArchived === undefined || typeof session.autoArchived === 'boolean') &&
+        (session.renamed === undefined || typeof session.renamed === 'boolean') &&
+        validUsage(session.usage) &&
+        // The fork's baseline is read as a count of tokens, so a malformed one refuses the record
+        // rather than being counted as a baseline of nothing.
+        (session.inheritedUsage === undefined || (validUsage(session.inheritedUsage)
+            && (!session.usage || (session.inheritedUsage.inputTokens <= session.usage.inputTokens
+                && session.inheritedUsage.outputTokens <= session.usage.outputTokens
+                && session.inheritedUsage.requests <= session.usage.requests))));
+}
+const writeScope = new AsyncLocalStorage();
+/** Fence work not yet submitted; keep ownership for uncancellable OS mutations. */
+export class SessionWriteFence {
+    closed = false;
+    replacements = new Set();
+    assert = () => { if (this.closed)
+        throw new Error('Session persistence is closed'); };
+    guard(check) { return Object.assign(() => { this.assert(); check(); }, { fence: this }); }
+    run(action) { return writeScope.run(this, action); }
+    close() { this.closed = true; }
+    settled() { return Promise.allSettled([...this.replacements]); }
+}
+/** A submitted deletion needs the same ownership drain as an atomic replacement. */
+export async function removeSessionSnapshot(path, assertCanWrite) {
+    const fence = assertCanWrite?.fence ?? writeScope.getStore();
+    fence?.assert();
+    assertCanWrite?.();
+    const removal = rm(path, { force: true });
+    fence?.replacements.add(removal);
+    try {
+        await removal;
+    }
+    finally {
+        fence?.replacements.delete(removal);
+    }
+}
+/** Keep replacement atomic while allowing brief Windows reader/scanner locks to clear. */
+export async function writeSessionSnapshot(path, content, assertCanWrite) {
+    const fence = assertCanWrite?.fence ?? writeScope.getStore();
+    const check = () => { fence?.assert(); assertCanWrite?.(); };
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    try {
+        check();
+        await writeFile(temporary, content, { mode: 0o600 });
+        for (let attempt = 0;; attempt++) {
+            check();
+            try {
+                const replacement = rename(temporary, path);
+                fence?.replacements.add(replacement);
+                try {
+                    await replacement;
+                }
+                finally {
+                    fence?.replacements.delete(replacement);
+                }
+                break;
+            }
+            catch (error) {
+                if (process.platform !== 'win32' || attempt >= 7 || !['EPERM', 'EACCES', 'EBUSY'].includes(error.code ?? ''))
+                    throw error;
+                await delay(10 * 2 ** attempt);
+            }
+        }
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}
+export class SessionStore {
+    directory;
+    constructor(directory) {
+        this.directory = directory;
+    }
+    async save(session, assertCanWrite) {
+        if (!validId(session.id))
+            throw new Error('Invalid session ID');
+        const directory = join(this.directory, 'sessions');
+        await mkdir(directory, { recursive: true, mode: 0o700 });
+        await writeSessionSnapshot(join(directory, `${session.id}.json`), JSON.stringify(session) + '\n', assertCanWrite);
+    }
+    async list(workspace) {
+        const directory = join(this.directory, 'sessions');
+        let names;
+        try {
+            names = await readdir(directory);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return [];
+            throw error;
+        }
+        const sessions = [];
+        for (const name of names) {
+            if (!name.endsWith('.json'))
+                continue;
+            try {
+                const value = JSON.parse(await readFile(join(directory, name), 'utf8'));
+                if (!validSavedSession(value) || name !== `${value.id}.json` || workspace !== undefined && resolve(value.workspace) !== resolve(workspace))
+                    continue;
+                sessions.push(value);
+            }
+            catch { /* One damaged record must not hide other resumable sessions. */ }
+        }
+        return sessions.sort((a, b) => Date.parse(b.updatedAt) - Date.parse(a.updatedAt) || a.id.localeCompare(b.id));
+    }
+    /**
+     * The account's own totals, read without holding the records.
+     *
+     * A portal that wants "how many sessions were created" needs every record, but it does not need
+     * their histories: each file is read, counted, and dropped, so a machine with thousands of
+     * sessions answers with a handful of numbers instead of a copy of every conversation.
+     */
+    async stats() {
+        const directory = join(this.directory, 'sessions');
+        let names;
+        try {
+            names = await readdir(directory);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return emptySessionStats();
+            throw error;
+        }
+        const stats = emptySessionStats();
+        const workspaces = new Set();
+        const records = new Map();
+        const runIds = new Set();
+        for (const name of names) {
+            if (!name.endsWith('.json'))
+                continue;
+            try {
+                const value = JSON.parse(await readFile(join(directory, name), 'utf8'));
+                if (!validSavedSession(value) || name !== `${value.id}.json`)
+                    continue;
+                stats.total += 1;
+                if (value.archived === true)
+                    stats.archived += 1;
+                const keys = [];
+                const named = [];
+                for (const turn of value.history ?? []) {
+                    if (typeof turn.runId === 'string' && /^[A-Za-z0-9_-]{1,64}$/.test(turn.runId)) {
+                        // A turn that names a run belongs to that run, and the run's usage is counted once.
+                        keys.push(`run:${turn.runId}`);
+                        named.push(turn.runId);
+                        runIds.add(turn.runId);
+                    }
+                    else {
+                        // A turn that names no run is identified by its content, so a fork's copy of it is the
+                        // same turn and not a second one.
+                        keys.push(`turn:${createHash('sha1').update(JSON.stringify(turn)).digest('hex')}`);
+                    }
+                }
+                records.set(value.id, { id: value.id, parentId: value.parentId, ancestors: value.ancestors, inheritedUsage: value.inheritedUsage, inheritedTurns: value.inheritedTurns, lineage: value.lineage, keys, named, usage: value.usage });
+                workspaces.add(resolve(value.workspace));
+                const updated = Date.parse(value.updatedAt);
+                if (Number.isFinite(updated)) {
+                    if (stats.firstActivity === undefined || updated < stats.firstActivity)
+                        stats.firstActivity = updated;
+                    if (stats.lastActivity === undefined || updated > stats.lastActivity)
+                        stats.lastActivity = updated;
+                }
+            }
+            catch { /* One damaged record must not hide the rest of the account's sessions. */ }
+        }
+        const runUsage = new Map();
+        for (const runId of runIds) {
+            const usage = await readRunUsage(join(this.directory, 'runs', `${runId}.json`));
+            if (usage)
+                runUsage.set(runId, usage);
+        }
+        for (const usage of runUsage.values()) {
+            stats.inputTokens += usage.inputTokens;
+            stats.outputTokens += usage.outputTokens;
+            stats.requests += usage.requests;
+        }
+        // A session's own total, less the runs it names, is the usage of the turns that name none.
+        const residual = (record) => {
+            let input = 0, output = 0, requests = 0;
+            for (const runId of new Set(record.named)) {
+                const run = runUsage.get(runId);
+                input += run?.inputTokens ?? 0;
+                output += run?.outputTokens ?? 0;
+                requests += run?.requests ?? 0;
+            }
+            return {
+                inputTokens: Math.max(0, record.usage.inputTokens - input),
+                outputTokens: Math.max(0, record.usage.outputTokens - output),
+                requests: Math.max(0, record.usage.requests - requests),
+            };
+        };
+        // The fork points: the lineage's state at each fork, oldest first. The last one is the
+        // point this record was forked with, and the difference between two points is the work the
+        // lineage did between those two forks.
+        const forkPoints = (record) => {
+            const chain = record.lineage ?? [];
+            if (chain.length)
+                return chain;
+            // A fork made before the chain was recorded falls back to the totals it was made with.
+            return [{
+                    usage: record.inheritedUsage ?? { inputTokens: 0, outputTokens: 0, requests: 0 },
+                    turns: record.inheritedTurns ?? 0,
+                }];
+        };
+        // The turns two histories share: a fork made before the lineage was recorded names only its
+        // parent, and the prefix it shares with that record is what it inherited.
+        const sharedPrefix = (left, right) => {
+            let count = 0;
+            while (count < left.length && count < right.length && left[count] === right[count])
+                count += 1;
+            return count;
+        };
+        // The usage the runs a stretch of turns name: those are counted once through their own runs.
+        const runsIn = (record, from, to) => {
+            let input = 0, output = 0, requests = 0;
+            for (let index = Math.max(0, from); index < Math.min(to, record.keys.length); index += 1) {
+                const key = record.keys[index];
+                if (!key.startsWith('run:'))
+                    continue;
+                const run = runUsage.get(key.slice(4));
+                input += run?.inputTokens ?? 0;
+                output += run?.outputTokens ?? 0;
+                requests += run?.requests ?? 0;
+            }
+            return { inputTokens: input, outputTokens: output, requests: requests };
+        };
+        const subtractUsage = (left, right) => ({
+            inputTokens: Math.max(0, left.inputTokens - right.inputTokens),
+            outputTokens: Math.max(0, left.outputTokens - right.outputTokens),
+            requests: Math.max(0, left.requests - right.requests),
+        });
+        const addUsage = (left, right) => ({
+            inputTokens: left.inputTokens + right.inputTokens,
+            outputTokens: left.outputTokens + right.outputTokens,
+            requests: left.requests + right.requests,
+        });
+        // A fork copies its parent's history and its parent's cumulative usage, so the work in the
+        // prefix they share belongs to the parent and is counted there: the machine's totals must not
+        // grow merely by branching a conversation. Each session therefore contributes only what it did
+        // itself.
+        //
+        // The parent is not always there. A session in the middle of a lineage can be deleted, and the
+        // fork below it then has no parent to compare its history with. The fork points it recorded
+        // when it was made say what the lineage looked like at each fork, so the work the missing
+        // ancestors had done is known even when their records are gone: the fork carries it, because
+        // it is the only record that still does. The ancestors that are still on the machine are
+        // counted on their own, and the work they had done by the time of the fork is what the fork
+        // inherits, not what they did afterwards.
+        const countedRuns = new Set();
+        // The work of an ancestor that is gone is carried once across the descendants that hold it.
+        // Sibling forks each hold it, and counting it in each of them would count the same work
+        // twice, so one of them keeps it: the one that saw the most of it.
+        const carriers = new Map();
+        // Whether one snapshot saw more of an ancestor than another: the turns first, then the
+        // requests, then the tokens.
+        const seesMore = (left, right) => {
+            if (!right)
+                return true;
+            for (let index = 0; index < left.length; index += 1) {
+                if (left[index] !== right[index])
+                    return left[index] > right[index];
+            }
+            return false;
+        };
+        for (const [id, record] of records) {
+            const chain = forkPoints(record);
+            // Whether the record carries the lineage snapshot: one point per ancestor. A record
+            // written before the snapshot was recorded, and a record that continued one, are measured
+            // from the prefix they share with the ancestor that is still there.
+            const hasSnapshot = (record.lineage?.length ?? 0) > 0 && record.lineage.length === (record.ancestors?.length ?? 0);
+            const ancestors = record.ancestors ?? [];
+            // The ancestors that are still on the machine are counted on their own, so the fork must
+            // not count their work again. The work of the ancestors that are gone belongs to the fork.
+            const deleted = [];
+            let nearest = -1;
+            for (let index = ancestors.length - 1; index >= 0; index -= 1) {
+                if (records.has(ancestors[index])) {
+                    nearest = index;
+                    break;
+                }
+                deleted.push(index);
+            }
+            // The turns the fork inherited from the ancestors that are still there: the fork's history
+            // opens with the lineage's history, so the survivors' turns end where the nearest of them
+            // ends.
+            const parent = record.parentId === undefined ? undefined : records.get(record.parentId);
+            const survivor = nearest >= 0 ? records.get(ancestors[nearest]) : undefined;
+            // A record with the lineage snapshot measures the inherited turns from it. One without it -
+            // written before the snapshot was recorded - measures them from the prefix it shares with
+            // the ancestor that is still there.
+            const shared = nearest >= 0
+                ? (hasSnapshot
+                    ? Math.min(chain[nearest]?.turns ?? 0, record.keys.length)
+                    : (survivor ? sharedPrefix(record.keys, survivor.keys) : 0))
+                : (parent ? sharedPrefix(record.keys, parent.keys) : 0);
+            // The record's own turns: everything past the lineage's turns at the fork. The turns
+            // of an ancestor that is gone are counted by the descendant that keeps its work.
+            const inheritedRegion = hasSnapshot ? (chain[chain.length - 1]?.turns ?? 0) : shared;
+            for (let index = inheritedRegion; index < record.keys.length; index += 1) {
+                const key = record.keys[index];
+                if (key.startsWith('run:')) {
+                    const runId = key.slice(4);
+                    if (countedRuns.has(runId))
+                        continue;
+                    countedRuns.add(runId);
+                }
+                stats.turns += 1;
+            }
+            // The usage the fork inherited: the lineage's work at the fork, less the runs those turns
+            // name, because those are counted once through their own runs.
+            const inherited = chain[chain.length - 1];
+            // A fork made before the chain was recorded is measured against its parent as it is now:
+            // the older record has no fork-time snapshot to measure against.
+            const inheritedUnnamed = chain.length > 1
+                ? subtractUsage(inherited.usage, runsIn(record, 0, inheritedRegion))
+                : (record.inheritedUsage
+                    ? subtractUsage(inherited.usage, runsIn(record, 0, inheritedRegion))
+                    : (parent ? residual(parent) : inherited.usage));
+            // The work the deleted ancestors did, which the fork now carries: their share of the
+            // lineage's work at the fork, less the runs their own turns name. Each of them is kept by
+            // one of the descendants that hold it, so sibling forks do not count it twice.
+            // The fork points are read by position, so this runs only for a record that has them: a
+            // record written before the snapshot was recorded has no points to line up with its
+            // ancestors, and its inherited work is measured from the prefix it shares instead.
+            for (const index of hasSnapshot ? deleted : []) {
+                const before = chain[index - 1] ?? { usage: { inputTokens: 0, outputTokens: 0, requests: 0 }, turns: 0 };
+                const after = chain[index] ?? inherited;
+                const work = subtractUsage(subtractUsage(after.usage, before.usage), runsIn(record, before.turns, after.turns));
+                const ancestor = ancestors[index];
+                const held = carriers.get(ancestor);
+                // The holder that saw the most of the ancestor keeps its work. The whole snapshot is
+                // compared, not the input tokens alone: an ancestor that made a zero-input attempt
+                // between two forks has the same input in both, and the later one is the one that saw
+                // more of it.
+                const seen = [after.turns, after.usage.requests, after.usage.inputTokens, after.usage.outputTokens];
+                if (seesMore(seen, held?.seen)) {
+                    carriers.set(ancestor, { work, turns: after.turns - before.turns, seen });
+                }
+            }
+            // The usage the session added itself. A session that inherited more than its baseline is
+            // clamped rather than counted twice.
+            // A record written before the snapshot was recorded has no points to line up with its
+            // ancestors, so the work of an ancestor that is gone is left out of the totals rather
+            // than assigned to a descendant: the record cannot say which of them held it. The
+            // turns are still counted, because the record holds them.
+            const own = subtractUsage(residual(record), inheritedUnnamed);
+            stats.inputTokens += own.inputTokens;
+            stats.outputTokens += own.outputTokens;
+            stats.requests += own.requests;
+        }
+        // The work of the ancestors that are gone, counted once each, on the descendant that keeps it.
+        for (const held of carriers.values()) {
+            stats.inputTokens += held.work.inputTokens;
+            stats.outputTokens += held.work.outputTokens;
+            stats.requests += held.work.requests;
+            stats.turns += held.turns;
+        }
+        stats.projects = workspaces.size;
+        // The totals are sums of the stored counters, and a stored counter may be large: two files
+        // that each hold a near-maximal number would add up to a number no client can read. The
+        // totals are capped at the largest number a client can hold, so a counter that overflows is
+        // reported as the maximum rather than as a null the portal would crash on.
+        for (const key of ['inputTokens', 'outputTokens', 'requests']) {
+            if (!Number.isSafeInteger(stats[key]) || stats[key] > Number.MAX_SAFE_INTEGER)
+                stats[key] = Number.MAX_SAFE_INTEGER;
+        }
+        return stats;
+    }
+}

package/dist/src/shell.d.ts

@@ -0,0 +1,40 @@
+import { type ChildProcess } from 'node:child_process';
+import type { ShellExecuteResult } from './qa/types.js';
+export type ShellSandbox = 'read-only' | 'workspace-write';
+/** Cleanup runs in the host: never discover its executable through cwd or PATH. */
+export declare function resolveTrustedTaskkill(workspace: string, env?: NodeJS.ProcessEnv): Promise<string>;
+/** Canonical repository exclusion applies to configured, packaged and PATH candidates. */
+export declare function validateCodexExecutableOutsideWorkspace(workspace: string, candidate: string): Promise<string | undefined>;
+export declare function resolveTrustedCodexExecutable(workspace: string, options?: {
+    env?: NodeJS.ProcessEnv;
+    arch?: string;
+}): Promise<string>;
+export declare function codexSandboxArgs(cwd: string, protectedRoots: string[], sandbox: 'read-only' | 'workspace-write', command: string, kind?: ShellKind): string[];
+export type ShellKind = 'powershell' | 'bash' | 'posix';
+export declare const defaultShellKind: ShellKind;
+/** Terminate a spawned shell tree with the same owned-tree cleanup the shell tool uses. */
+export declare function stopProcessTree(child: ChildProcess, runId: string): Promise<void>;
+/**
+ * The exact environment shell execution inherits: configuration locations, never
+ * credential values. Process managers must build from this so background QA
+ * processes see the same view (and the same ANDORRACODE cleanup marker).
+ */
+export declare function shellBaseEnv(marker?: string): NodeJS.ProcessEnv;
+/** Resolve only the requested interpreter. Never fall back to cmd.exe or WSL. */
+export declare function shellInvocation(command: string, kind?: ShellKind): {
+    executable: string;
+    args: string[];
+};
+/** Formatted legacy observation; rejects on timeout, abort and nonzero exits exactly as before. */
+export declare function runShell(command: string, cwd: string, timeout: number, abortSignal: AbortSignal, kind?: ShellKind, onData?: (data: Buffer) => void, sandbox?: ShellSandbox, launchPolicy?: () => ShellSandbox | undefined): Promise<string>;
+/**
+ * Structured shell execution for the QA layer: exit codes, streams and timeouts
+ * resolve as data so check runners can normalize results; only spawn failures and
+ * explicit cancellation reject, and cancellation keeps the legacy wording so the
+ * runtime still recognizes an aborted tool.
+ */
+export declare function executeShell(command: string, cwd: string, timeout: number, abortSignal: AbortSignal, kind?: ShellKind, sandbox?: ShellSandbox): Promise<ShellExecuteResult>;
+/** Execute an already-selected native program without spawning a command interpreter.
+ * Approval/sandbox enforcement and owned process-tree cleanup are identical to runShell.
+ */
+export declare function runNativeProcess(executable: string, args: string[], cwd: string, timeout: number, abortSignal: AbortSignal, launchPolicy?: () => ShellSandbox | undefined): Promise<string>;