@manyoars/oars 0.3.0 → 0.4.1

package/dist/sessions/hooks.js

@@ -4,18 +4,23 @@
 import { join } from 'node:path';
 import { performance } from 'node:perf_hooks';
 import { defaultConfigDir } from '../credentials.js';
+import { noEmit } from '../telemetry/emit.js';
+import { frameWords, HOOK_HARNESS, recallFields } from '../telemetry/fields.js';
 import { cursorRoot } from './cursor.js';
 import { SOURCES, sourceLabel } from './sources.js';
-import { signatureOf } from './extract.js';
+import { ACTION_TABLES, actionOf } from './actions.js';
+import { errorCodeOf, signatureOf } from './extract.js';
 import { appendHookCall } from './hook-calls.js';
 import { contextBlock, readIndex } from './hook-index.js';
-import { pushRecall } from './recall-push.js';
+import { bundleNext, frameKeyOf, lastTable, mergePositions, positionsRecall, recoveryDecision, recoveryRecall, signatureRecall, isSignatureRetry } from './recall-next.js';
+import { pushRecall, tailOf } from './recall-push.js';
+import { statedAt, statedOf } from './transcript-tail.js';
 import { toolShapeId } from './recall-reads.js';
 import { makeRedactor } from './redact.js';
 import { errorLine, inputKey, logStep, newContext, runDeposit, stampKey, tryLog } from './steps.js';
 import { deposit, depositSession, readSaved } from './store.js';
 import { recordSurvival } from './survival.js';
-export const HOOK_EVENTS = ['session-start', 'pre-tool', 'post-tool', 'stop', 'nightly'];
+export const HOOK_EVENTS = ['session-start', 'prompt', 'pre-tool', 'post-tool', 'stop', 'nightly'];
 const TOP = 5;
 const MAX_CHARS = 1200;
 const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
@@ -30,11 +35,53 @@ const parse = (stdin) => {
 };
 const str = (value) => (typeof value === 'string' && value !== '' ? value : undefined);
 const additional = (eventName, context) => `${JSON.stringify({ hookSpecificOutput: { hookEventName: eventName, additionalContext: context } })}\n`;
-const sessionStart = async (runtime, input) => {
+/** What a next-node read needs of the hook's input: the session, the transcript's tail (version, model), and the clock; undefined when the harness gave no session, since the holdback arm is the session's. */
+const nextInputOf = async (runtime, input, now) => {
+    const sid = str(input.session_id);
+    if (sid === undefined)
+        return undefined;
+    const transcript = str(input.transcript_path);
+    const tail = transcript === undefined ? '' : await tailOf(transcript);
+    const { harnessVersion } = statedOf(tail);
+    return { next: { storeDir: runtime.storeDir, sid, tail, platform: process.platform, at: new Date(now()).toISOString() }, asker: { harness: HOOK_HARNESS, harnessVersion } };
+};
+/**
+ * The split-positions table (Item 3): the kept bundle's positions first, the local pool's second. A `repeat` read (UserPromptSubmit) goes out only when the table differs from
+ * the one this session was last sent, shown or held, so a held session and a shown one hear the same number of times.
+ */
+const positionsTable = async (runtime, input, now, index, repeat) => {
+    const prepared = await nextInputOf(runtime, input, now);
+    if (prepared === undefined)
+        return undefined;
+    const bundle = await bundleNext(runtime.storeDir, prepared.asker);
+    const positions = mergePositions(bundle?.positions ?? [], index?.positionsByFrame?.[frameKeyOf(prepared.asker)] ?? []);
+    if (positions.length === 0)
+        return undefined;
+    const previous = repeat ? await lastTable(runtime.storeDir, prepared.next.sid) : undefined;
+    return positionsRecall(prepared.next, prepared.asker, positions, bundle?.poolVersion ?? index?.at ?? '', previous);
+};
+const sessionStart = async (runtime, input, now) => {
     const cwd = str(input.cwd);
-    const index = cwd === undefined ? undefined : await readIndex(runtime.storeDir);
+    const index = await readIndex(runtime.storeDir);
     const block = index === undefined || cwd === undefined ? undefined : contextBlock(index, { cwd, top: TOP, maxChars: MAX_CHARS });
-    return block === undefined ? { hit: false, queried: index !== undefined } : { output: additional('SessionStart', block), hit: true, queried: true };
+    const recall = await positionsTable(runtime, input, now, index, false);
+    const model = str(input.model);
+    const shown = recall?.arm === 'shown' ? recall.answer.rendered : undefined;
+    const text = [block, shown].filter((part) => part !== undefined).join('\n\n');
+    return {
+        hit: text !== '' || recall !== undefined,
+        queried: index !== undefined || recall !== undefined,
+        ...(text === '' ? {} : { output: additional('SessionStart', text) }),
+        ...(recall === undefined ? {} : { recall }),
+        ...(model === undefined ? {} : { model }),
+    };
+};
+/** UserPromptSubmit: the positions table again, only when it changed since this session's last one. */
+const prompt = async (runtime, input, now) => {
+    const recall = await positionsTable(runtime, input, now, await readIndex(runtime.storeDir), true);
+    if (recall === undefined)
+        return { hit: false, queried: false };
+    return recall.arm === 'shown' ? { output: additional('UserPromptSubmit', recall.answer.rendered), hit: true, queried: true, recall } : { hit: true, queried: true, recall };
 };
 const inputKeys = (input) => (isRecord(input.tool_input) ? Object.keys(input.tool_input) : []);
 /**
@@ -52,7 +99,7 @@ const preTool = async (runtime, input, now) => {
     const recall = await pushRecall({ storeDir: runtime.storeDir, sid, tool, keys: inputKeys(input), transcript: str(input.transcript_path), platform: process.platform, at: new Date(now()).toISOString(), index });
     if (recall === undefined)
         return { hit: false, queried: false };
-    return recall.arm === 'shown' ? { output: additional('PreToolUse', recall.answer.rendered), hit: true, queried: true } : { hit: true, queried: true };
+    return recall.arm === 'shown' ? { output: additional('PreToolUse', recall.answer.rendered), hit: true, queried: true, recall } : { hit: true, queried: true, recall };
 };
 /** A failed tool arrives as PostToolUseFailure with the text in `error` (Bash and PowerShell start it with `Exit code N`); a PostToolUse response that starts that way is read too. */
 const failureText = (input) => {
@@ -62,20 +109,37 @@ const failureText = (input) => {
     const response = str(input.tool_response);
     return response !== undefined && /^Exit code \d+/.test(response) ? response : undefined;
 };
-const postTool = async (runtime, input) => {
+/**
+ * The recovery edge (Item 2): what followed a failure of this action and error class, from the kept bundle for the session's setup and then the local pool, held to A33's
+ * holdback like every next-node read. A same-step retry or a local edge under the floor says nothing, signature line included; the signature line answers only a failure no cell covers.
+ */
+const postTool = async (runtime, input, now) => {
     const tool = str(input.tool_name);
     const text = failureText(input);
-    if (tool === undefined || text === undefined)
+    const prepared = tool === undefined || text === undefined ? undefined : await nextInputOf(runtime, input, now);
+    if (tool === undefined || text === undefined || prepared === undefined)
         return { hit: false, queried: false };
     const index = await readIndex(runtime.storeDir);
-    if (index === undefined)
+    const bundle = await bundleNext(runtime.storeDir, prepared.asker);
+    if (index === undefined && bundle === undefined)
         return { hit: false, queried: false };
-    const found = index.signatures[signatureOf(tool, text, makeRedactor(index.redactDomains))];
-    if (found === undefined)
+    const action = actionOf(ACTION_TABLES['claude-code'], tool).action;
+    const code = errorCodeOf(text);
+    const decision = recoveryDecision(bundle, index === undefined ? undefined : { recovery: index.recoveryByFrame?.[frameKeyOf(prepared.asker)] ?? {}, poolVersion: index.at }, action, code);
+    const event = str(input.hook_event_name) ?? 'PostToolUseFailure';
+    if (decision.kind === 'serve') {
+        const recall = await recoveryRecall(prepared.next, prepared.asker, action, code, decision);
+        return recall.arm === 'shown' ? { output: additional(event, recall.answer.rendered), hit: true, queried: true, recall } : { hit: true, queried: true, recall };
+    }
+    // A same-step retry, a local cell too thin to serve, and a cell whose top is that nothing followed all end the lookup: a cell that exists but says nothing is not a reason to fall back to a signature count.
+    if (decision.kind === 'retry' || decision.kind === 'floor' || decision.kind === 'ended')
         return { hit: false, queried: true };
-    const followed = found.followed.map(([next]) => next).join(', ');
-    const context = `oars recall: seen in ${String(found.sessions)} sessions; what followed: ${followed === '' ? 'nothing recorded' : followed}`;
-    return { output: additional(str(input.hook_event_name) ?? 'PostToolUseFailure', context), hit: true, queried: true };
+    const sig = signatureOf(tool, text, makeRedactor(index?.redactDomains ?? []));
+    const found = index?.signatures[sig];
+    if (index === undefined || found === undefined || isSignatureRetry(tool, found))
+        return { hit: false, queried: true };
+    const recall = await signatureRecall(prepared.next, prepared.asker, tool, sig, found, index.at);
+    return recall.arm === 'shown' ? { output: additional(event, recall.answer.rendered), hit: true, queried: true, recall } : { hit: true, queried: true, recall };
 };
 const stop = async (runtime, input, now) => {
     const transcript = str(input.transcript_path);
@@ -85,13 +149,13 @@ const stop = async (runtime, input, now) => {
     const deposited = await runDeposit(newContext(runtime.storeDir, now, 'stop'), false, inputKey('stop', [transcript], []), async (trace) => ({ value: await depositSession(runtime, transcript, now, trace), in: { transcript: 1 } }));
     return { hit: deposited === 'deposited', queried: false };
 };
-const nightly = async (runtime, now) => {
+const nightlyRun = async (runtime, now, timing) => {
     // A state.json that cannot be read is a failed deposit run like any other: its error row and the skipped derive row (spec 4.4) are logged.
     const saved = await readSaved(runtime.storeDir).catch((failure) => runDeposit(newContext(runtime.storeDir, now, 'nightly'), true, inputKey('nightly', [], []), () => Promise.reject(failure instanceof Error ? failure : new Error(String(failure)))));
-    if (saved.allow.length === 0)
-        return { hit: false, queried: false };
     const result = await runDeposit(newContext(runtime.storeDir, now, 'nightly'), true, inputKey('nightly', saved.allow, saved.redactDomains), async (trace) => {
+        const parseStart = timing.clock();
         const done = await deposit(runtime, { allow: saved.allow, redactDomains: saved.redactDomains, now }, trace);
+        timing.parseMs = timing.clock() - parseStart;
         return { value: done, in: { transcript: done.sessions + done.subagents + done.unchanged } };
     });
     const survival = await recordSurvival(runtime, saved.allow, now);
@@ -107,12 +171,38 @@ const nightly = async (runtime, now) => {
     // A survival read that fails every night is otherwise invisible, for the same reason; it comes last because the run itself did not lose a session.
     return survival === null ? { hit: true, queried: false, error: await errorLine(runtime.storeDir, 'Commit survival not read this run.') } : { hit: true, queried: false };
 };
+/** The nightly run, then (when telemetry is given) the store-health snapshot and the run's cost. Recording happens after the run and cannot change its outcome or its error. */
+const nightly = async (runtime, now, telemetry) => {
+    const timing = { clock: telemetry?.now ?? now, parseMs: 0 };
+    const started = timing.clock();
+    let outcome;
+    let failure;
+    let failed = false;
+    try {
+        outcome = await nightlyRun(runtime, now, timing);
+    }
+    catch (thrown) {
+        failure = thrown;
+        failed = true;
+    }
+    if (telemetry !== undefined) {
+        // Loaded here so the hooks that run before every tool call never pay for the telemetry modules.
+        const { recordRunCost, recordStoreHealth } = await import('../telemetry/health.js');
+        await recordStoreHealth(telemetry, runtime);
+        recordRunCost(telemetry, { totalMs: timing.clock() - started, parseMs: timing.parseMs, failed: failed || outcome?.error !== undefined });
+    }
+    if (failed)
+        throw failure;
+    return outcome ?? { hit: false, queried: false };
+};
 /** What a lookup hook looks up, as its recall key (spec 4.2 names none for a lookup): the cwd for session-start, the failure's signature for post-tool, the call's shape for pre-tool; null when it had nothing to look up. */
 const lookupKey = (event, input) => {
     if (event === 'session-start') {
         const cwd = str(input.cwd);
         return cwd === undefined ? null : stampKey(event, cwd);
     }
+    if (event === 'prompt')
+        return stampKey(event, 'positions');
     const tool = str(input.tool_name);
     if (event === 'pre-tool')
         return tool === undefined ? null : stampKey(event, toolShapeId(tool, inputKeys(input)));
@@ -126,31 +216,37 @@ export const hookRuntime = (event, env, platform, home, io) => ({
     ...(event === 'nightly' ? { cursorRoot: cursorRoot(platform, env, home), sourceRoots: Object.fromEntries(SOURCES.map((source) => [source.name, source.root(platform, env, home)])) } : {}),
     ...io,
 });
+/** What the nightly run records with, and nothing for any other hook: the telemetry folder sits beside the session store under the config directory, so `oars telemetry` and the nightly run read and write the same one. The version is read only for the nightly run, so the per-tool hooks never touch the manifest. */
+export const nightlyTelemetry = (event, env, platform, home, version, now) => event === 'nightly' ? { env, telemetry: { dir: join(defaultConfigDir(env, platform, home), 'oars', 'telemetry'), platform }, version: version(), now } : undefined;
 /**
  * Runs one hook. It never fails or blocks the session it runs in: whatever happens, it resolves (the process exits 0), and the
  * hook-call line records the outcome, with the failure's first line when there was one, so the record is evidence, not a claim.
  */
-export const runHook = async (event, stdin, runtime, now) => {
+export const runHook = async (event, stdin, runtime, now, telemetry, emit = noEmit) => {
     const started = performance.now();
     let session = null;
     let outcome = { hit: false, queried: false };
     let failed = false;
     let failure;
     let key = null;
+    let transcript;
     try {
         const input = parse(stdin);
+        transcript = str(input.transcript_path);
         key = lookupKey(event, input);
         session = str(input.session_id) ?? null;
         if (event === 'session-start')
-            outcome = await sessionStart(runtime, input);
+            outcome = await sessionStart(runtime, input, now);
+        else if (event === 'prompt')
+            outcome = await prompt(runtime, input, now);
         else if (event === 'pre-tool')
             outcome = await preTool(runtime, input, now);
         else if (event === 'post-tool')
-            outcome = await postTool(runtime, input);
+            outcome = await postTool(runtime, input, now);
         else if (event === 'stop')
             outcome = await stop(runtime, input, now);
         else
-            outcome = await nightly(runtime, now);
+            outcome = await nightly(runtime, now, telemetry);
     }
     catch (thrown) {
         failure = thrown;
@@ -166,5 +262,20 @@ export const runHook = async (event, stdin, runtime, now) => {
         const report = { in: { query: 1 }, out: failed ? {} : { matches: outcome.hit ? 1 : 0 }, key };
         await tryLog(() => logStep(newContext(runtime.storeDir, now, event), 'recall', failed ? 'error' : 'ok', ms, report, line));
     }
+    // After the answer is settled and the local rows are written; it runs before hook-bin prints, at the cost measured in t876 item 5. `emit` never throws. A push states its own frame;
+    // every other fire reads the transcript's tail the way a push does, so the version and model are there on a miss, a post-tool, and a stop. (A nightly run has no hook input, so it has no transcript to read.)
+    const { recall } = outcome;
+    const stated = recall?.frame !== undefined || transcript === undefined ? undefined : await statedAt(transcript);
+    emit('hook', {
+        name: event,
+        latencyMs: ms,
+        outcome: failed ? 'error' : recall?.arm === 'held' ? 'held' : outcome.hit ? 'hit' : 'miss',
+        bytes: Buffer.byteLength(outcome.output ?? ''),
+        // The nightly is the scheduled task, not a harness's hook: it names no harness.
+        ...frameWords(event === 'nightly' ? undefined : recall?.frame?.harness ?? HOOK_HARNESS, recall?.frame?.harnessVersion ?? stated?.harnessVersion, recall?.frame?.model ?? outcome.model ?? stated?.model),
+    });
+    // A push is a recall: its read is the family its query names (the `fit` push names none), and its arm is the exposure record, as a count of one.
+    if (recall !== undefined)
+        emit('recall', recallFields(recall, [recall.query.family ?? 'fit']));
     return outcome.output;
 };

package/dist/sessions/identity.d.ts

@@ -1,4 +1,5 @@
 import { type ActionTable, type CanonicalAction } from './actions.js';
+import type { Redactor } from './redact.js';
 import type { PullIdentity, ShellIdentity, StepIdentity, ToolPull } from './schema.js';
 /** A word of a shell command, as the tokenizer read it. */
 export interface WordOfCommand {
@@ -7,15 +8,19 @@ export interface WordOfCommand {
 }
 export declare const NUMBER_FLAG = "-N";
 export declare const isPositional: ({ text, quoted }: WordOfCommand) => boolean;
-/** A pull in public names. A private package's version can still identify it, so it is masked with the name; a stated version stays stated. */
-export declare const pullIdentity: (pull: ToolPull) => PullIdentity;
+/**
+ * A pull with its package name as written (the command was redacted before it was read, and the name is checked once more part by part, as a host and a skill-run name are). A package off the public list can be identified by its version, so the version is masked beside it; a stated version of a listed package stays stated.
+ * A name that is not one (a URL, a path, a mask) is `<literal>`.
+ */
+export declare const pullIdentity: (pull: ToolPull, redact: Redactor) => PullIdentity;
 /** A shell step whose program is private or unreadable: its flags are its own, so none are kept. */
 export declare const UNREAD_SHELL: ShellIdentity;
-export declare const shellIdentity: (program: string, args: readonly WordOfCommand[], pulls: readonly ToolPull[]) => ShellIdentity;
+export declare const shellIdentity: (program: string, args: readonly WordOfCommand[], pulls: readonly ToolPull[], redact: Redactor) => ShellIdentity;
 /** What a non-shell call's step reads as. `native` comes back masked unless every name it holds is public, since an MCP name spells out its server. */
 export declare const callIdentity: (table: ActionTable, action: CanonicalAction, native: string, shown: string, input: {
     skill: string | undefined;
     url: string | undefined;
+    redact: Redactor;
 }) => {
     native: string;
     identity: StepIdentity;

package/dist/sessions/identity.js

@@ -1,8 +1,18 @@
-// A step's `identity` (recall spec Section 2.2): what the step acted on, by action, in public names only. Every name passes through
-// `public-vocabulary.ts`, so what may leave the machine is decided in that one file; anything it does not list becomes `<literal>`.
+// A step's `identity` (recall spec Section 2.2): what the step acted on, by action. A program, subcommand, flag, MCP server and tool pass through
+// `public-vocabulary.ts` and become `<literal>` when it does not list them; a skill-run name, a host, and a pull name are kept as they are after the
+// operator's redaction (CAPTURE 24), and what leaves the machine is decided at the deposit's one gate and by the pool.
 import { mcpOf } from './actions.js';
-import { BUNDLING_PROGRAMS, isPublicMcpTool, isRegistryVersion, LITERAL, PUBLIC_FLAGS, PUBLIC_HOSTS, PUBLIC_MCP_SERVERS, PUBLIC_PACKAGES, PUBLIC_PROGRAMS, PUBLIC_SKILLS, PUBLIC_SUBCOMMANDS } from './public-vocabulary.js';
+import { isWireName, isWirePullName, wireName } from './pool-wire.js';
+import { BUNDLING_PROGRAMS, isPublicMcpTool, isRegistryVersion, LITERAL, PRIVATE, PUBLIC_FLAGS, PUBLIC_MCP_SERVERS, PUBLIC_PACKAGES, PUBLIC_PROGRAMS, PUBLIC_SUBCOMMANDS } from './public-vocabulary.js';
 const orLiteral = (name, allowed) => (allowed.has(name) ? name : LITERAL);
+/**
+ * A long-tail name (a skill run, a host, a pull) as the store keeps it: the name itself, or `<literal>` when it is not a name or the operator's redaction would change it. The test is the wire's own (`wireName`), so a name stored here is a
+ * name the deposit sends, and a list never decides it: the pool does, by deploy. The operator's exclusion terms are the deposit's, since they change after the capture.
+ */
+const keptName = (name, redact, hasShape = isWireName) => {
+    const kept = wireName({ redact, terms: [] }, name, hasShape);
+    return kept === PRIVATE ? LITERAL : kept;
+};
 const SHORT_CLUSTER = /^-[a-z]{1,4}$/;
 const SHORT_LETTER = /^-[A-Za-z]$/;
 // A short flag with a value joined after a non-letter, as in `-c1-200`: the first capture is the name and the rest is the value, which is dropped.
@@ -63,33 +73,53 @@ const REGISTRY_OF = {
     plugin: 'plugin',
     mcp: 'mcp',
 };
-/** A pull in public names. A private package's version can still identify it, so it is masked with the name; a stated version stays stated. */
-export const pullIdentity = (pull) => {
-    const name = orLiteral(pull.name, PUBLIC_PACKAGES);
-    const showsVersion = name !== LITERAL && pull.version !== null && isRegistryVersion(pull.version);
+/**
+ * A pull with its package name as written (the command was redacted before it was read, and the name is checked once more part by part, as a host and a skill-run name are). A package off the public list can be identified by its version, so the version is masked beside it; a stated version of a listed package stays stated.
+ * A name that is not one (a URL, a path, a mask) is `<literal>`.
+ */
+export const pullIdentity = (pull, redact) => {
+    const name = keptName(pull.name, redact, isWirePullName);
+    const showsVersion = PUBLIC_PACKAGES.has(name) && pull.version !== null && isRegistryVersion(pull.version);
     return { registry: REGISTRY_OF[pull.ecosystem], name, version: pull.version === null ? null : showsVersion ? pull.version : LITERAL };
 };
 /** A shell step whose program is private or unreadable: its flags are its own, so none are kept. */
 export const UNREAD_SHELL = { program: LITERAL, sub: null, flags: [] };
-export const shellIdentity = (program, args, pulls) => {
+/** Flags of `git checkout` that take only paths: a checkout with one of them acts on a path, never on a branch. */
+const PATH_ONLY_FLAGS = new Set(['--ours', '--theirs', '--patch', '-p', '--pathspec-from-file']);
+/**
+ * The class of what a `git checkout` acts on, from the line alone and never the target's text. A `--` marker or a path-only flag proves a path; a target word the segment drops (the same
+ * words `isPositional` refuses: quoted, or holding a slash, a backslash, or `$`) with neither proof could be a branch (`feature/x`) or a path (`src/a.ts`), so it is `word`; no such word is absent.
+ */
+const checkoutTarget = (all) => {
+    // Words before `checkout` are the global options of `git` (`-C <dir>`), not what the checkout acts on.
+    const args = all.slice(all.findIndex(({ text, quoted }) => !quoted && text === 'checkout') + 1);
+    const dashes = args.findIndex(({ text, quoted }) => !quoted && text === '--');
+    const flagWords = (dashes < 0 ? args : args.slice(0, dashes)).filter(({ text, quoted }) => !quoted && text.startsWith('-')).map(({ text }) => text.split('=')[0] ?? text);
+    if (dashes >= 0 || flagWords.some((flag) => PATH_ONLY_FLAGS.has(flag)))
+        return 'path';
+    return args.some((word) => (word.quoted || !word.text.startsWith('-')) && !isPositional(word)) ? 'word' : undefined;
+};
+export const shellIdentity = (program, args, pulls, redact) => {
     if (!PUBLIC_PROGRAMS.has(program))
         return UNREAD_SHELL;
-    const identity = { program, sub: subOf(program, args), flags: flagsOf(program, args) };
-    return pulls.length === 0 ? identity : { ...identity, pulls: pulls.map(pullIdentity) };
+    const sub = subOf(program, args);
+    const target = program === 'git' && sub === 'checkout' ? checkoutTarget(args) : undefined;
+    const identity = { program, sub, flags: flagsOf(program, args), ...(target === undefined ? {} : { target }) };
+    return pulls.length === 0 ? identity : { ...identity, pulls: pulls.map((pull) => pullIdentity(pull, redact)) };
 };
-const hostOf = (url) => {
+const hostOf = (url, redact) => {
     if (url === undefined || url === '')
         return { host: null };
-    // The parser drops credentials, the path, and the query, and lower-cases the host; the list then decides.
+    // The parser drops credentials, the path, and the query, and lower-cases the host; the redactor and the name shape then decide, and the pool hashes it on arrival.
     const parsed = URL.canParse(url) ? new URL(url).hostname : '';
-    return { host: orLiteral(parsed, PUBLIC_HOSTS) };
+    return { host: keptName(parsed, redact) };
 };
 /** What a non-shell call's step reads as. `native` comes back masked unless every name it holds is public, since an MCP name spells out its server. */
 export const callIdentity = (table, action, native, shown, input) => {
     if (action === 'web.fetch' || action === 'web.search')
-        return { native: shown, identity: hostOf(input.url) };
+        return { native: shown, identity: hostOf(input.url, input.redact) };
     if (action === 'skill.run')
-        return { native: shown, identity: { skill: orLiteral(input.skill ?? '', PUBLIC_SKILLS) } };
+        return { native: shown, identity: { skill: keptName(input.skill ?? '', input.redact) } };
     const mcp = action === 'mcp.call' ? mcpOf(table, native) : undefined;
     if (mcp === undefined)
         return { native: shown, identity: null };

package/dist/sessions/install.d.ts

@@ -3,6 +3,8 @@ 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;
@@ -21,8 +23,9 @@ 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) and starts node only
- * when the failure text carries `Exit code`: a fresh node costs 250 ms to seconds on Windows, the shell builtins a few milliseconds.
+ * 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;
@@ -50,5 +53,18 @@ export declare const hookStatus: (runtime: InstallRuntime, extra: string | undef
 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

@@ -1,27 +1,31 @@
 // `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, writeFile } from 'node:fs/promises';
+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|pre-tool|post-tool|stop)$/;
+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 Bash call arrives as PostToolUseFailure with `error` = "Exit code N ...": PostToolUse itself fires on success only.
-    { event: 'PostToolUseFailure', arg: 'post-tool', timeout: 5, matcher: 'Bash|PowerShell' },
+    // 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) and starts node only
- * when the failure text carries `Exit code`: a fresh node costs 250 ms to seconds on Windows, the shell builtins a few milliseconds.
+ * 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}`;
@@ -29,7 +33,7 @@ export const commandOf = (runtime, arg) => {
     const present = `[ -f "${runtime.hookBin}" ] || exit 0; `;
     if (arg !== 'post-tool')
         return `${present}${launch}`;
-    return `${present}IFS= read -r event; case "$event" in *'Exit code'*) ;; *) exit 0;; esac; { printf '%s\\n' "$event"; cat; } | ${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. */
@@ -185,16 +189,57 @@ export const scheduleArgs = (runtime, hour) => [
     '/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 `Scheduled task ${TASK_NAME}: the full deposit and the recurrence refresh run daily at ${String(SCHEDULE_HOUR).padStart(2, '0')}:00.`;
+        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/mcp.d.ts

@@ -1,6 +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) => Promise<object | undefined>;
+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) => Promise<void>;
+export declare const serve: (runtime: SessionsRuntime, now: () => number, emit?: Emit) => Promise<void>;

package/dist/sessions/mcp.js

@@ -5,6 +5,9 @@
 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';
@@ -79,7 +82,7 @@ const toQuery = (args) => {
 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) => {
+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;
@@ -110,7 +113,7 @@ export const handleMessage = async (runtime, now, message) => {
             // 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 servedPool(runtime.storeDir, store) });
+            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));
@@ -121,6 +124,7 @@ export const handleMessage = async (runtime, now, message) => {
                 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 } });
@@ -133,7 +137,7 @@ export const handleMessage = async (runtime, now, message) => {
     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) => {
+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() === '')
@@ -146,7 +150,7 @@ export const serve = async (runtime, now) => {
             runtime.stdout.write(`${JSON.stringify(failure(null, -32700, 'Parse error'))}\n`);
             continue;
         }
-        const answer = await handleMessage(runtime, now, parsed);
+        const answer = await handleMessage(runtime, now, parsed, emit);
         if (answer !== undefined)
             runtime.stdout.write(`${JSON.stringify(answer)}\n`);
     }

package/dist/sessions/motif.d.ts

@@ -15,7 +15,8 @@ export interface WindowStep {
 /** A step as a cell counts it. */
 export interface CountedStep extends WindowStep {
     status: ToolStatus;
-    tokens: number;
+    /** Null when the step recorded no cost (a source that never reported one, or a call captured before steps): a cell leaves it out of its sum and coverage, never reading it as 0. */
+    tokens: number | null;
     durationMs: number;
 }
 export interface Motif {

package/dist/sessions/motif.js

@@ -27,8 +27,8 @@ export const shapeMotif = (steps) => motifOf('shape', steps, null);
 /** The steps of one call. A record captured before steps existed reads through the same action table capture uses, so old data joins new. */
 export const stepsOfCall = (tool, harness) => {
     if (tool.steps === undefined)
-        return [{ action: actionOf(ACTION_TABLES[harness], tool.tool).action, identity: null, status: tool.status, tokens: 0, durationMs: tool.durationMs ?? 0 }];
-    return tool.steps.map((step) => ({ action: step.action, identity: step.identity, status: step.status, tokens: step.cost.tokens ?? 0, durationMs: step.cost.durationMs ?? 0 }));
+        return [{ action: actionOf(ACTION_TABLES[harness], tool.tool).action, identity: null, status: tool.status, tokens: null, durationMs: tool.durationMs ?? 0 }];
+    return tool.steps.map((step) => ({ action: step.action, identity: step.identity, status: step.status, tokens: step.cost.tokens, durationMs: step.cost.durationMs ?? 0 }));
 };
 /** Every window of a line of work, at both levels, shortest first at each position. */
 export const motifsOf = (line) => {