@manyoars/oars 0.2.0 → 0.4.0

package/dist/sessions/install.d.ts

@@ -0,0 +1,70 @@
+export declare const RETENTION_FLOOR = 365;
+export declare const DEFAULT_RETENTION = 30;
+export declare const TASK_NAME = "OarsSessionsNightly";
+/** What the install needs from the machine, so a test can stand in for each. */
+export interface InstallRuntime {
+    /** `process.platform`: only `win32` has the nightly task. */
+    platform: NodeJS.Platform;
+    nodePath: string;
+    /** Absolute path of the built `hook-bin.js`. */
+    hookBin: string;
+    /** `<claude config dir>/settings.json`. */
+    userSettings: string;
+    cwd: string;
+    /** Runs `schtasks` with these arguments. */
+    schtasks: (args: string[]) => Promise<{
+        code: number;
+        output: string;
+    }>;
+}
+export type Scope = 'user' | 'project' | 'file';
+/** A settings file is open-ended JSON the harness owns; only the keys named here are read or written. */
+interface Json {
+    [key: string]: unknown;
+}
+/**
+ * The post-tool command reads the event first in the hook shell (Git Bash on Windows, where the harness runs hooks). For a shell tool it starts node only
+ * when the failure text carries `Exit code` (a refusal or an interrupt has none, and a fresh node costs 250 ms to seconds on Windows, the shell builtins a few
+ * milliseconds); any other tool's failure goes straight to node, because its text has no such line and its recovery read does not need one.
+ */
+export declare const commandOf: (runtime: InstallRuntime, arg: string) => string;
+export declare const settingsPath: (runtime: InstallRuntime, scope: Scope, file: string | undefined) => string;
+export declare const readSettings: (path: string) => Promise<Json>;
+/** The retention the file sets: its `cleanupPeriodDays` when a number, else the harness default. */
+export declare const effectiveRetention: (settings: Json) => number;
+export interface InstallResult {
+    file: string;
+    installed: string[];
+    retention: string;
+}
+export declare const installHooks: (runtime: InstallRuntime, path: string, keepRetention: boolean) => Promise<InstallResult>;
+export declare const uninstallHooks: (path: string) => Promise<{
+    file: string;
+    removed: string[];
+}>;
+export interface FileStatus {
+    file: string;
+    scope: Scope;
+    installed: string[];
+    retentionDays: number;
+}
+export declare const hookStatus: (runtime: InstallRuntime, extra: string | undefined) => Promise<FileStatus[]>;
+/** The `schtasks` arguments for the nightly task: the same node and hook-bin the hooks use, at a fixed hour. */
+export declare const scheduleArgs: (runtime: InstallRuntime, hour: number) => string[];
+export declare const SCHEDULE_HOUR = 3;
+export declare const setSchedule: (runtime: InstallRuntime, mode: "nightly" | "off") => Promise<string>;
+/** True once the operator ran `--schedule off` and has not run `--schedule nightly` since. A record that cannot be read or parsed counts as no opt-out. */
+export declare const scheduleOptedOut: (storeDir: string) => Promise<boolean>;
+/** Records the choice of `--schedule`: `off` writes the opt-out; `nightly` clears it. Without a store the choice has nowhere to live and is not recorded. */
+export declare const recordSchedule: (storeDir: string | undefined, mode: "nightly" | "off") => Promise<void>;
+/** What a plain `hook install` says when the operator turned the nightly task off: it is left alone. */
+export declare const SCHEDULE_LEFT_OFF = "Scheduled task OarsSessionsNightly: left off, as you chose with --schedule off. Turn it back on with: oars sessions hook install --schedule nightly";
+/**
+ * What a plain `hook install` does about the nightly task on Windows: register it unless it is already there. Registration is
+ * best effort: the hooks are installed by then, so a machine that refuses the task (policy, no Task Scheduler) is told how to retry
+ * and is not failed. `install --schedule off` removes the task and records the opt-out (`recordSchedule`), which the caller checks
+ * (`scheduleOptedOut`) before calling this; `--schedule nightly` clears it.
+ */
+export declare const ensureSchedule: (runtime: InstallRuntime) => Promise<string>;
+export declare const scheduleStatus: (runtime: InstallRuntime) => Promise<string>;
+export {};

package/dist/sessions/install.js

@@ -0,0 +1,246 @@
+// `oars sessions hook install|uninstall|status`: writes the four Claude Code hook entries into one settings file, merging with what is
+// there. An entry is ours when its command ends with `hook-bin.js" <session-start|pre-tool|post-tool|stop>`, so uninstall removes those entries and nothing else. Also the retention floor
+// (the harness deletes raw transcripts after `cleanupPeriodDays`, 30 when unset) and the Windows nightly task.
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { CliError, ExitCode } from '../errors.js';
+import { ACTION_TABLES } from './actions.js';
+export const RETENTION_FLOOR = 365;
+export const DEFAULT_RETENTION = 30;
+export const TASK_NAME = 'OarsSessionsNightly';
+// The tail of a command this module wrote; anything else in a settings file is the operator's, whatever it is called.
+const OWN_COMMAND = /hook-bin\.js" (?:session-start|prompt|pre-tool|post-tool|stop)$/;
+const SPECS = [
+    { event: 'SessionStart', arg: 'session-start', timeout: 5 },
+    // The split-positions table again, only when it changed since this session's last one (`hooks.ts`); a prompt with nothing new costs one node start and prints nothing.
+    { event: 'UserPromptSubmit', arg: 'prompt', timeout: 5 },
+    // Every tool (no matcher): the push is gated by the index's fit floors and lift, not by the tool's name, so a sharp read on any tool can fire. The cost is one node start per call.
+    { event: 'PreToolUse', arg: 'pre-tool', timeout: 5 },
+    // A failed call arrives as PostToolUseFailure (PostToolUse itself fires on success only); a shell tool's `error` starts "Exit code N". Every tool the action table maps can fail into a recovery read, so the matcher is the table's names and the MCP pattern, not the two shells.
+    { event: 'PostToolUseFailure', arg: 'post-tool', timeout: 5, matcher: `${Object.keys(ACTION_TABLES['claude-code'].rows).filter((name) => !name.startsWith('mcp__')).join('|')}|mcp__.*` },
+    // SessionEnd fires once per session; Stop fires after every assistant turn and would re-extract the growing transcript each time.
+    { event: 'SessionEnd', arg: 'stop', timeout: 30 },
+];
+const isObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+/**
+ * The post-tool command reads the event first in the hook shell (Git Bash on Windows, where the harness runs hooks). For a shell tool it starts node only
+ * when the failure text carries `Exit code` (a refusal or an interrupt has none, and a fresh node costs 250 ms to seconds on Windows, the shell builtins a few
+ * milliseconds); any other tool's failure goes straight to node, because its text has no such line and its recovery read does not need one.
+ */
+export const commandOf = (runtime, arg) => {
+    const launch = `"${runtime.nodePath}" "${runtime.hookBin}" ${arg}`;
+    // Fails open: a settings file outlives the build it points at (a cloud worker, a clone with no build), and a hook that cannot start must not fail the session.
+    const present = `[ -f "${runtime.hookBin}" ] || exit 0; `;
+    if (arg !== 'post-tool')
+        return `${present}${launch}`;
+    return `${present}IFS= read -r event; case "$event" in '') exit 0;; *'"tool_name":"Bash"'*|*'"tool_name":"PowerShell"'*) case "$event" in *'Exit code'*) ;; *) exit 0;; esac;; esac; { printf '%s\\n' "$event"; cat; } | ${launch}`;
+};
+const isOwnHook = (hook) => isObject(hook) && typeof hook.command === 'string' && OWN_COMMAND.test(hook.command);
+/** The groups with our entries taken out; a group that held only ours goes, one that held others keeps them. */
+const withoutOwn = (groups) => groups.flatMap((group) => {
+    if (!isObject(group) || !Array.isArray(group.hooks) || !group.hooks.some(isOwnHook))
+        return [group];
+    const rest = group.hooks.filter((hook) => !isOwnHook(hook));
+    return rest.length === 0 ? [] : [{ ...group, hooks: rest }];
+});
+const hasOwn = (groups) => groups.some((group) => isObject(group) && Array.isArray(group.hooks) && group.hooks.some(isOwnHook));
+export const settingsPath = (runtime, scope, file) => {
+    if (scope === 'user')
+        return runtime.userSettings;
+    if (scope === 'project')
+        return join(runtime.cwd, '.claude', 'settings.json');
+    if (file === undefined) {
+        throw new CliError('--scope file needs --file <settings path>; nothing is written to a settings file you have not named.', ExitCode.USAGE, 'usage');
+    }
+    return resolve(runtime.cwd, file);
+};
+export const readSettings = async (path) => {
+    let raw;
+    try {
+        raw = await readFile(path, 'utf8');
+    }
+    catch (error) {
+        if (error instanceof Error && Reflect.get(error, 'code') === 'ENOENT')
+            return {};
+        throw new CliError(`Could not read ${path} (${error instanceof Error ? error.message : String(error)}); nothing was changed.`, ExitCode.USAGE, 'usage');
+    }
+    if (raw.trim() === '')
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new CliError(`${path} is not valid JSON; fix or remove it, nothing was changed.`, ExitCode.USAGE, 'usage');
+    }
+    if (!isObject(parsed))
+        throw new CliError(`${path} is not a JSON object; nothing was changed.`, ExitCode.USAGE, 'usage');
+    return parsed;
+};
+const writeSettings = async (path, settings) => {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, `${JSON.stringify(settings, null, 2)}\n`);
+};
+const hooksOf = (settings) => (isObject(settings.hooks) ? settings.hooks : {});
+const groupsOf = (hooks, event) => {
+    const groups = hooks[event];
+    return Array.isArray(groups) ? groups : [];
+};
+/** The retention the file sets: its `cleanupPeriodDays` when a number, else the harness default. */
+export const effectiveRetention = (settings) => (typeof settings.cleanupPeriodDays === 'number' ? settings.cleanupPeriodDays : DEFAULT_RETENTION);
+/** Events an earlier build registered our entries under; install and uninstall clear them so a stale entry cannot keep running. */
+const LEGACY_EVENTS = ['Stop'];
+/** Takes our entries out of `event`, dropping the key when that empties it. */
+const clearLegacy = (hooks, event) => {
+    const groups = groupsOf(hooks, event);
+    if (!hasOwn(groups))
+        return false;
+    const kept = withoutOwn(groups);
+    if (kept.length === 0)
+        Reflect.deleteProperty(hooks, event);
+    else
+        hooks[event] = kept;
+    return true;
+};
+export const installHooks = async (runtime, path, keepRetention) => {
+    const settings = await readSettings(path);
+    const hooks = hooksOf(settings);
+    for (const event of LEGACY_EVENTS)
+        clearLegacy(hooks, event);
+    for (const spec of SPECS) {
+        const others = withoutOwn(groupsOf(hooks, spec.event));
+        const entry = { type: 'command', command: commandOf(runtime, spec.arg), timeout: spec.timeout };
+        hooks[spec.event] = [...others, spec.matcher === undefined ? { hooks: [entry] } : { matcher: spec.matcher, hooks: [entry] }];
+    }
+    settings.hooks = hooks;
+    // A project or file scope overrides the user's `cleanupPeriodDays`, so a file with no number of its own takes the user's, lower or higher; that is the value reported.
+    const own = effectiveRetention(settings);
+    // Only a value the user file sets counts: its unset default must not outrank a lower value written on purpose here.
+    const userDays = path === runtime.userSettings ? undefined : (await readSettings(runtime.userSettings)).cleanupPeriodDays;
+    const userValue = typeof userDays === 'number' ? userDays : undefined;
+    // A number this file sets overrides the user's, so the user's counts only when the file sets none.
+    const inherited = typeof settings.cleanupPeriodDays === 'number' ? undefined : userValue;
+    // With no number of its own the file takes the user's, lower or higher: that is what the harness deletes by.
+    const before = inherited ?? own;
+    const shown = inherited !== undefined ? `${String(before)} (from ${runtime.userSettings})` : typeof settings.cleanupPeriodDays === 'number' ? String(before) : `${String(before)} (unset, the default)`;
+    let retention;
+    if (keepRetention) {
+        retention = `Left cleanupPeriodDays alone at ${shown} in ${path} (--keep-retention); the harness deletes raw transcripts older than that.`;
+    }
+    else if (before >= RETENTION_FLOOR) {
+        retention = `cleanupPeriodDays is ${shown} in ${path}, at or above the ${String(RETENTION_FLOOR)} floor; left as is.`;
+    }
+    else {
+        // The floor is per target file: a user-scope value never lands in a project file, which can be committed. Without a number of its own the
+        // file reaches this branch only when the user value is below the floor too, so the floor is right there as well.
+        settings.cleanupPeriodDays = RETENTION_FLOOR;
+        retention = `Raised cleanupPeriodDays from ${shown} to ${String(RETENTION_FLOOR)} in ${path}.`;
+    }
+    await writeSettings(path, settings);
+    return { file: path, installed: SPECS.map((spec) => spec.event), retention };
+};
+export const uninstallHooks = async (path) => {
+    const settings = await readSettings(path);
+    const hooks = hooksOf(settings);
+    const removed = [];
+    const cleared = LEGACY_EVENTS.map((event) => clearLegacy(hooks, event)).includes(true);
+    for (const spec of SPECS) {
+        const groups = groupsOf(hooks, spec.event);
+        if (!hasOwn(groups))
+            continue;
+        const kept = withoutOwn(groups);
+        removed.push(spec.event);
+        hooks[spec.event] = kept;
+    }
+    if (removed.length > 0 || cleared) {
+        // An event this call emptied goes; an event that was already an empty list in the file is the operator's and stays.
+        const remaining = Object.entries(hooks).filter(([event, groups]) => !(removed.includes(event) && Array.isArray(groups) && groups.length === 0));
+        // `undefined` is left out of the JSON, so an emptied `hooks` key goes.
+        settings.hooks = remaining.length === 0 ? undefined : Object.fromEntries(remaining);
+        await writeSettings(path, settings);
+    }
+    return { file: path, removed };
+};
+export const hookStatus = async (runtime, extra) => {
+    const targets = [
+        { file: runtime.userSettings, scope: 'user' },
+        { file: join(runtime.cwd, '.claude', 'settings.json'), scope: 'project' },
+        ...(extra === undefined ? [] : [{ file: resolve(runtime.cwd, extra), scope: 'file' }]),
+    ];
+    const statuses = [];
+    for (const target of targets) {
+        const settings = await readSettings(target.file);
+        const hooks = hooksOf(settings);
+        statuses.push({ ...target, installed: SPECS.filter((spec) => hasOwn(groupsOf(hooks, spec.event))).map((spec) => spec.event), retentionDays: effectiveRetention(settings) });
+    }
+    return statuses;
+};
+/** The `schtasks` arguments for the nightly task: the same node and hook-bin the hooks use, at a fixed hour. */
+export const scheduleArgs = (runtime, hour) => [
+    '/Create',
+    '/TN',
+    TASK_NAME,
+    '/TR',
+    `"${runtime.nodePath}" "${runtime.hookBin}" nightly`,
+    '/SC',
+    'DAILY',
+    '/ST',
+    `${String(hour).padStart(2, '0')}:00`,
+    '/F',
+];
+export const SCHEDULE_HOUR = 3;
+const registered = () => `Scheduled task ${TASK_NAME}: the full deposit and the recurrence refresh run daily at ${String(SCHEDULE_HOUR).padStart(2, '0')}:00.`;
+export const setSchedule = async (runtime, mode) => {
+    if (mode === 'nightly') {
+        const created = await runtime.schtasks(scheduleArgs(runtime, SCHEDULE_HOUR));
+        if (created.code !== 0)
+            throw new CliError(`Could not register the scheduled task: ${created.output.trim()}`, ExitCode.UNEXPECTED, 'unexpected');
+        return registered();
+    }
+    const deleted = await runtime.schtasks(['/Delete', '/TN', TASK_NAME, '/F']);
+    return deleted.code === 0 ? `Removed the scheduled task ${TASK_NAME}.` : `No scheduled task ${TASK_NAME} to remove.`;
+};
+/** Where `--schedule off` is remembered: a file of its own in the sessions store, because `state.json` is rewritten whole by every deposit. */
+const scheduleRecord = (storeDir) => join(storeDir, 'schedule.json');
+/** True once the operator ran `--schedule off` and has not run `--schedule nightly` since. A record that cannot be read or parsed counts as no opt-out. */
+export const scheduleOptedOut = async (storeDir) => {
+    try {
+        const parsed = JSON.parse(await readFile(scheduleRecord(storeDir), 'utf8'));
+        return typeof parsed === 'object' && parsed !== null && 'schedule' in parsed && parsed.schedule === 'off';
+    }
+    catch {
+        return false;
+    }
+};
+/** Records the choice of `--schedule`: `off` writes the opt-out; `nightly` clears it. Without a store the choice has nowhere to live and is not recorded. */
+export const recordSchedule = async (storeDir, mode) => {
+    if (storeDir === undefined)
+        return;
+    if (mode === 'nightly') {
+        await rm(scheduleRecord(storeDir), { force: true });
+        return;
+    }
+    await mkdir(storeDir, { recursive: true });
+    await writeFile(scheduleRecord(storeDir), `${JSON.stringify({ schedule: 'off' })}\n`, { mode: 0o600 });
+};
+/** What a plain `hook install` says when the operator turned the nightly task off: it is left alone. */
+export const SCHEDULE_LEFT_OFF = `Scheduled task ${TASK_NAME}: left off, as you chose with --schedule off. Turn it back on with: oars sessions hook install --schedule nightly`;
+/**
+ * What a plain `hook install` does about the nightly task on Windows: register it unless it is already there. Registration is
+ * best effort: the hooks are installed by then, so a machine that refuses the task (policy, no Task Scheduler) is told how to retry
+ * and is not failed. `install --schedule off` removes the task and records the opt-out (`recordSchedule`), which the caller checks
+ * (`scheduleOptedOut`) before calling this; `--schedule nightly` clears it.
+ */
+export const ensureSchedule = async (runtime) => {
+    const queried = await runtime.schtasks(['/Query', '/TN', TASK_NAME]);
+    if (queried.code === 0)
+        return `Scheduled task ${TASK_NAME}: already registered.`;
+    const created = await runtime.schtasks(scheduleArgs(runtime, SCHEDULE_HOUR));
+    if (created.code !== 0)
+        return `Could not register the scheduled task ${TASK_NAME} (${created.output.trim()}); the hooks are installed. Retry with: oars sessions hook install --schedule nightly`;
+    return registered();
+};
+export const scheduleStatus = async (runtime) => {
+    const queried = await runtime.schtasks(['/Query', '/TN', TASK_NAME]);
+    return queried.code === 0 ? `Scheduled task ${TASK_NAME}: registered.` : `Scheduled task ${TASK_NAME}: not registered.`;
+};

package/dist/sessions/lineage.d.ts

@@ -0,0 +1,19 @@
+import { type Cell } from './cells.js';
+import type { Read } from './read.js';
+import { type Recall } from './recall-object.js';
+export interface LineageSources {
+    recalls: readonly Recall[];
+    reads: readonly Read[];
+    cells: readonly Cell[];
+}
+export interface LineageHop {
+    depth: number;
+    kind: 'recall' | 'read' | 'cell' | 'evidence' | 'missing';
+    ref: string;
+    frames: string[];
+    day: string | null;
+    detail: string;
+}
+export declare const walkLineage: (sources: LineageSources, start: string) => LineageHop[];
+export declare const formatLineage: (hops: readonly LineageHop[]) => string;
+export declare const loadLineage: (storeDir: string) => Promise<LineageSources>;

package/dist/sessions/lineage.js

@@ -0,0 +1,118 @@
+// `oars sessions lineage` (recall spec Section 3): walks a recall or read back through its evidence, one line per hop with its frame range and day. Evidence must come from
+// before the recall that cites it, which is what keeps the commons acyclic; a store whose records say otherwise is refused here, not printed as if it held. The walk also keeps
+// a visited set, so a hand-edited file cannot loop it.
+import { readdir, readFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { CliError, ExitCode } from '../errors.js';
+import { cellIdOf, UNKNOWN } from './cells.js';
+import { poolFiles } from './pool.js';
+import { evidencePredates, readRecalls } from './recall-object.js';
+import { count } from './recall-render.js';
+const FRAMES_SHOWN = 3;
+const dayOf = (at) => at.slice(0, 10);
+const refuse = (ref, day, limit) => new CliError(`Refused: ${ref} is from ${String(day)}, newer than the recall citing it (${limit}).`, ExitCode.INVALID, 'lineage');
+const framesOfRecall = (recall) => (recall.frame === null ? [] : [[recall.frame.harness, recall.frame.harnessVersion ?? UNKNOWN, recall.frame.model ?? UNKNOWN].join(' ')]);
+const framesOfEvidence = (evidence) => [...evidence.frameRange.harnesses, ...evidence.frameRange.harnessVersions, ...evidence.frameRange.models];
+const framesOfRead = (read, cells) => {
+    const buckets = [...new Set(read.inputs.flatMap((input) => cells.get(input)?.frameBucket ?? []))].sort();
+    return buckets.length <= FRAMES_SHOWN ? buckets : [...buckets.slice(0, FRAMES_SHOWN), `+${String(buckets.length - FRAMES_SHOWN)}`];
+};
+const tighter = (limit, day) => (limit === null || day < limit ? day : limit);
+export const walkLineage = (sources, start) => {
+    const recalls = new Map(sources.recalls.map((recall) => [recall.id, recall]));
+    const reads = new Map(sources.reads.map((read) => [read.readId, read]));
+    const cells = new Map(sources.cells.map((cell) => [cellIdOf(cell), cell]));
+    const known = (ref) => recalls.has(ref) || reads.has(ref) || cells.has(ref);
+    if (!known(start))
+        throw new CliError(`No recall, read, or cell in this store has the ID ${start}.`, ExitCode.INVALID, 'lineage');
+    const hops = [];
+    const seen = new Set();
+    const walkRecall = (recall, depth, limit) => {
+        const day = dayOf(recall.at);
+        if (limit !== null && day > limit)
+            throw refuse(recall.id, day, limit);
+        if (!evidencePredates(recall))
+            throw refuse(`the evidence of recall ${recall.id}`, recall.evidence.flatMap((item) => item.lastDay ?? []).sort().at(-1) ?? recall.poolVersion, day);
+        hops.push({ depth, kind: 'recall', ref: recall.id, frames: framesOfRecall(recall), day, detail: `${recall.mode} ${recall.arm} ${recall.answer.kind}` });
+        for (const evidence of recall.evidence) {
+            if (known(evidence.ref)) {
+                walk(evidence.ref, depth + 1, tighter(limit, day));
+            }
+            else if (!seen.has(evidence.ref)) {
+                // A stand-in: the shape or signature hash a recall cites where no read was stored. The recall holds all there is to say of it.
+                seen.add(evidence.ref);
+                hops.push({ depth: depth + 1, kind: 'evidence', ref: evidence.ref, frames: framesOfEvidence(evidence), day: evidence.lastDay, detail: `${count(evidence.n, 'session')}, ${count(evidence.clusters, 'cluster')}, from ${String(evidence.firstDay)}` });
+            }
+        }
+    };
+    const walk = (ref, depth, limit) => {
+        if (seen.has(ref))
+            return;
+        seen.add(ref);
+        const recall = recalls.get(ref);
+        if (recall !== undefined) {
+            walkRecall(recall, depth, limit);
+            return;
+        }
+        const read = reads.get(ref);
+        if (read !== undefined) {
+            if (limit !== null && read.asOf.day !== null && read.asOf.day > limit)
+                throw refuse(ref, read.asOf.day, limit);
+            hops.push({ depth, kind: 'read', ref, frames: framesOfRead(read, cells), day: read.asOf.day, detail: `${read.family}, order ${String(read.order)}, n ${String(read.n)}, ${count(read.clusters, 'cluster')}, basis ${read.basis}` });
+            for (const input of read.inputs)
+                walk(input, depth + 1, limit);
+            return;
+        }
+        const cell = cells.get(ref);
+        if (cell !== undefined) {
+            // A week cell is named by its Monday, so only a week that opens after the recall is newer than it; a week that straddles the recall is checked by the read's own day, above.
+            if (limit !== null && cell.day !== UNKNOWN && cell.day > limit)
+                throw refuse(ref, cell.day, limit);
+            hops.push({ depth, kind: 'cell', ref, frames: [cell.frameBucket], day: cell.day, detail: `${String(cell.sessions)} sessions, ${String(cell.ok)} ok, ${String(cell.failed)} failed${cell.exposed ? ', exposed' : ''}` });
+            return;
+        }
+        // `cells.jsonl` holds the current pool only, so a read kept from an older pool can cite a cell since rewritten.
+        hops.push({ depth, kind: 'missing', ref, frames: [], day: null, detail: 'not in the current pool' });
+    };
+    walk(start, 0, null);
+    return hops;
+};
+export const formatLineage = (hops) => hops.map((hop) => `${'  '.repeat(hop.depth)}${hop.kind} ${hop.ref} | ${hop.frames.join(', ') || 'frames unknown'} | ${hop.day ?? 'day unknown'} | ${hop.detail}`).join('\n');
+const rowsOf = async (file, isRow) => {
+    let text = '';
+    try {
+        text = await readFile(file, 'utf8');
+    }
+    catch (error) {
+        if (!(error instanceof Error && 'code' in error && error.code === 'ENOENT'))
+            throw error;
+    }
+    return text.split('\n').flatMap((line) => {
+        if (line === '')
+            return [];
+        try {
+            const parsed = JSON.parse(line);
+            return isRow(parsed) ? [parsed] : [];
+        }
+        catch {
+            return [];
+        }
+    });
+};
+const isRead = (value) => typeof value === 'object' && value !== null && 'readId' in value && 'inputs' in value;
+const isCell = (value) => typeof value === 'object' && value !== null && 'motifId' in value && 'frameBucket' in value && 'grain' in value;
+const readFiles = async (dir) => {
+    try {
+        return (await readdir(dir)).flatMap((name) => (name.endsWith('.jsonl') ? [join(dir, name)] : []));
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+};
+export const loadLineage = async (storeDir) => {
+    const files = poolFiles(storeDir);
+    const lists = await Promise.all((await readFiles(dirname(files.reads('any')))).map((file) => rowsOf(file, isRead)));
+    return { recalls: await readRecalls(storeDir), reads: lists.flat(), cells: await rowsOf(files.cells, isCell) };
+};

package/dist/sessions/mcp.d.ts

@@ -0,0 +1,7 @@
+import { type Emit } from '../telemetry/emit.js';
+import { type SessionsRuntime } from './store.js';
+export declare const TOOL_NAME = "oars_recall";
+/** Answers one JSON-RPC message; a notification (no `id`) gets no answer. */
+export declare const handleMessage: (runtime: SessionsRuntime, now: () => number, message: unknown, emit?: Emit) => Promise<object | undefined>;
+/** Reads requests from `runtime.stdin` until it ends, writing one response line per request to `runtime.stdout`. */
+export declare const serve: (runtime: SessionsRuntime, now: () => number, emit?: Emit) => Promise<void>;

package/dist/sessions/mcp.js

@@ -0,0 +1,157 @@
+// `oars sessions recall --mcp`: a Model Context Protocol server over stdio (newline-delimited JSON-RPC 2.0) exposing the same
+// query as one tool, so a running agent can look a failure up before re-solving it. Hand-rolled because the surface is three
+// methods and the package takes no new dependency for it. Every answered call is appended to `mcp-calls.jsonl`, which is what
+// `oars sessions measure` reads for recall calls per session.
+import { appendFile, mkdir } from 'node:fs/promises';
+import { createInterface } from 'node:readline';
+import { servedPool } from './pool.js';
+import { recallPool } from './recall-bundle.js';
+import { noEmit } from '../telemetry/emit.js';
+import { recallFields } from '../telemetry/fields.js';
+import { appendRecall } from './recall-object.js';
+import { formsRefusal, pull, pullRefusal, RECALL_FAMILIES } from './recall-reads.js';
+import { MISS_TEXT } from './recall-render.js';
+import { makeRedactor } from './redact.js';
+import { tryLog } from './steps.js';
+import { loadStore, paths, readRedactDomains } from './store.js';
+const PROTOCOL = '2025-06-18';
+export const TOOL_NAME = 'oars_recall';
+const TOOL = {
+    name: TOOL_NAME,
+    description: "Look up a tool error, a file, or a prompt class in this operator's own past agent sessions before solving it again. Returns counts per read: sessions, days, harness versions, how far the evidence sits from you, and the actions that followed. Local; each call is recorded as a recall.",
+    inputSchema: {
+        type: 'object',
+        properties: {
+            error: { type: 'string', description: 'The error text, as printed.' },
+            path: { type: 'string', description: 'A file path or file name an earlier session touched.' },
+            class: { type: 'string', description: 'A prompt class: edit-verify, edit-only, shell-only, research, orchestration, explore-only, mixed, no-tools. Recovery and fit questions and the error, path, and class inputs only; any other form refuses it.' },
+            sinceDays: { type: 'integer', minimum: 1, description: 'Only errors from the last N days. Recovery and fit questions and the error, path, and class inputs only; any other form refuses it.' },
+            prefix: { type: 'array', items: { type: 'string' }, description: 'Read IDs for your steps so far: what happened from here?' },
+            entity: { type: 'string', description: 'A public name: a package, a tool, an MCP server, an action, or a model.' },
+            family: { type: 'string', description: `A read family to answer: ${RECALL_FAMILIES.join(', ')}. Only recovery and fit can be narrowed by class or sinceDays; any other family, and the prefix, entity, and text forms, count all time and refuse both. Name one form per call.` },
+            text: { type: 'string', description: 'Text to look for in the local record.' },
+        },
+    },
+};
+const isObj = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+/** The forms an MCP call names, by the same tests `toQuery` reads them with. */
+const namedForms = (args) => {
+    const source = isObj(args) ? args : {};
+    const prefix = Array.isArray(source.prefix) ? source.prefix.filter((id) => typeof id === 'string') : [];
+    return [
+        ...(prefix.length > 0 ? ['prefix'] : []),
+        ...(typeof source.entity === 'string' ? ['entity'] : []),
+        ...(typeof source.family === 'string' ? ['family'] : []),
+        ...(typeof source.text === 'string' ? ['text'] : []),
+        ...(typeof source.error === 'string' || typeof source.path === 'string' ? ['error or path'] : []),
+    ];
+};
+/** A `sinceDays` or `class` that is present but outside the schema is refused, not dropped: dropping it answers all time under a count that looks narrowed. */
+const narrowingRefusal = (args) => {
+    const source = isObj(args) ? args : {};
+    if (Object.hasOwn(source, 'class') && typeof source.class !== 'string')
+        return 'class must be a string.';
+    const days = source.sinceDays;
+    if (Object.hasOwn(source, 'sinceDays') && !(typeof days === 'number' && Number.isInteger(days) && days > 0))
+        return 'sinceDays must be a positive integer.';
+    return undefined;
+};
+const toQuery = (args) => {
+    const source = isObj(args) ? args : {};
+    const narrowing = {};
+    if (typeof source.class === 'string')
+        narrowing.cls = source.class;
+    if (typeof source.sinceDays === 'number' && Number.isInteger(source.sinceDays) && source.sinceDays > 0)
+        narrowing.sinceDays = source.sinceDays;
+    const prefix = Array.isArray(source.prefix) ? source.prefix.filter((id) => typeof id === 'string') : [];
+    if (prefix.length > 0)
+        return { form: 'pattern', prefix, slice: narrowing };
+    if (typeof source.entity === 'string')
+        return { form: 'entity', entity: source.entity, slice: narrowing };
+    if (typeof source.family === 'string')
+        return { form: 'question', family: source.family, slice: narrowing };
+    if (typeof source.text === 'string')
+        return { form: 'text', text: source.text, slice: narrowing };
+    const query = {};
+    if (typeof source.error === 'string')
+        query.error = source.error;
+    if (typeof source.path === 'string')
+        query.path = source.path;
+    return { ...query, ...narrowing };
+};
+const reply = (id, result) => ({ jsonrpc: '2.0', id, result });
+const failure = (id, code, message) => ({ jsonrpc: '2.0', id, error: { code, message } });
+/** Answers one JSON-RPC message; a notification (no `id`) gets no answer. */
+export const handleMessage = async (runtime, now, message, emit = noEmit) => {
+    if (!isObj(message) || typeof message.method !== 'string')
+        return failure(isObj(message) ? message.id : null, -32600, 'Invalid request');
+    const { id, method } = message;
+    if (id === undefined)
+        return undefined;
+    if (method === 'initialize') {
+        return reply(id, { protocolVersion: PROTOCOL, capabilities: { tools: {} }, serverInfo: { name: 'oars-sessions', version: '1' } });
+    }
+    if (method === 'ping')
+        return reply(id, {});
+    if (method === 'tools/list')
+        return reply(id, { tools: [TOOL] });
+    if (method === 'tools/call') {
+        const params = isObj(message.params) ? message.params : {};
+        if (params.name !== TOOL_NAME)
+            return failure(id, -32602, `Unknown tool: ${typeof params.name === 'string' ? params.name : ''}`);
+        const invalid = narrowingRefusal(params.arguments);
+        if (invalid !== undefined)
+            return failure(id, -32602, invalid);
+        const conflict = formsRefusal(namedForms(params.arguments));
+        if (conflict !== undefined)
+            return failure(id, -32602, conflict);
+        const query = toQuery(params.arguments);
+        const refusal = pullRefusal(query);
+        if (refusal !== undefined)
+            return failure(id, -32602, refusal);
+        try {
+            // The server is not told which session it serves, so `sid` is null: naming it is what a consequence for an MCP pull still needs.
+            const store = await loadStore(runtime.storeDir);
+            const redactDomains = await readRedactDomains(runtime.storeDir);
+            const result = pull(store, query, { sid: null, now: now(), frame: null, redactDomains, current: await recallPool(runtime.storeDir, store, servedPool) });
+            // What an asker typed is class A: the call log masks each string with the redactor `pull` applies to the recall row, before it is serialized, because JSON escaping of a quote or newline hides a secret from the rules.
+            const redact = makeRedactor(redactDomains);
+            const masked = JSON.stringify(query, (_key, value) => (typeof value === 'string' ? redact(value) : value));
+            const call = { at: new Date(now()).toISOString(), query: masked, matches: result.legacy?.matches.length ?? result.reads.length, cwd: process.cwd() };
+            // A pull always answers: a log or recall row that cannot be written costs the record, never the agent's answer.
+            await tryLog(async () => {
+                await mkdir(runtime.storeDir, { recursive: true });
+                await appendFile(paths(runtime.storeDir).calls, `${JSON.stringify(call)}\n`, { mode: 0o600 });
+            });
+            await tryLog(() => appendRecall(runtime.storeDir, result.recall));
+            emit('recall', recallFields(result.recall, result.reads.map((read) => read.family), result.legacy !== undefined));
+            // An agent reads this, so it gets the rendered counts and the structured recall, and no signature text.
+            const { answer, id: recallId, evidence } = result.recall;
+            return reply(id, { content: [{ type: 'text', text: answer.rendered === '' ? MISS_TEXT : answer.rendered }], structuredContent: { recallId, kind: answer.kind, reads: answer.reads, evidence } });
+        }
+        catch (error) {
+            // A store read failure must not end the server mid-session: the agent gets an error for this call and can carry on.
+            return failure(id, -32603, `Internal error: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    return failure(id, -32601, `Method not found: ${method}`);
+};
+/** Reads requests from `runtime.stdin` until it ends, writing one response line per request to `runtime.stdout`. */
+export const serve = async (runtime, now, emit = noEmit) => {
+    const lines = createInterface({ input: runtime.stdin, crlfDelay: Infinity });
+    for await (const line of lines) {
+        if (line.trim() === '')
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            runtime.stdout.write(`${JSON.stringify(failure(null, -32700, 'Parse error'))}\n`);
+            continue;
+        }
+        const answer = await handleMessage(runtime, now, parsed, emit);
+        if (answer !== undefined)
+            runtime.stdout.write(`${JSON.stringify(answer)}\n`);
+    }
+};

package/dist/sessions/merkle.d.ts

@@ -0,0 +1,7 @@
+export declare const sha256: (text: string) => string;
+/** A root over fewer lines than this joins no cluster and counts toward no `n` (spec 2.5, open question 5.4 item 3). */
+export declare const MIN_ROOT_LEAVES = 10;
+/** The lines capture hashes: split on any line ending, and a final empty piece (the trailing newline) is no line. */
+export declare const rawLinesOf: (text: string) => string[];
+/** SHA-256 over the SHA-256 of every line, an odd node paired with itself; no lines is `sha256('')`. */
+export declare const merkleRootOf: (lines: readonly string[]) => string;