@manyoars/oars 0.4.1 → 0.5.1

package/dist/sessions/codex.d.ts

@@ -36,6 +36,8 @@ export interface CodexStore {
     sessions: CodexSession[];
     /** The session as transcript text for `captureSession`; throws when the file cannot be read. */
     transcript: (session: CodexSession) => Promise<string>;
+    /** True when the rollout holds only head records (`rolloutHeadOnly`); `sessions verify` counts such a file as empty, not unreadable. */
+    headOnly: (session: CodexSession) => Promise<boolean>;
     /** Files skipped because their id is not a safe file name (it names a skeleton), counted so the skip is never silent. */
     rejected: number;
     /** Files that could not be inspected, reported once each and never fatal; the reason names no path, so a log line built from it leaks none. */
@@ -46,6 +48,13 @@ export interface CodexStore {
 }
 /** The non-blank lines of a rollout that are not JSON (a torn write), kept so `captureSession` counts them and the deposit line reports them. */
 export declare const rolloutBadLines: (text: string) => string[];
+export declare const rolloutHeadOnly: (text: string) => boolean;
+/**
+ * The rollout with the history it inherited removed (the records below a subagent's `subagent_history_start_ordinal`, and a Copied fork's leading
+ * copy of its parent), by the same two rules `rolloutLines` applies, so the head-only test sees only what the session itself wrote. Lines that are not
+ * a JSON object with a payload stay, as a torn line must still count.
+ */
+export declare const rolloutOwnText: (text: string, parentText?: string) => string;
 /** One rollout as the lines `captureSession` reads. */
 export declare const rolloutLines: (text: string, fallbackId: string, parentText?: string) => Obj[];
 /** Opens the Codex store under `root`; undefined when it holds no `sessions` folder, so a machine without Codex is skipped silently. */

package/dist/sessions/codex.js

@@ -23,7 +23,8 @@
 //                       That these records are persisted into the rollout is rollout/src/policy.rs:83, :91, and :137 at ac558e2.
 //   event_msg user_message {message}            a prompt (the `response_item` user messages also hold injected context, so they are not read)
 //   event_msg agent_message {message}           the assistant's text
-//   event_msg token_count {info.last_token_usage}  one model response's usage, closing the lines since the last one
+//   event_msg token_count {info.last_token_usage, rate_limits.primary/.secondary {used_percent, window_minutes}}  one model response's usage, closing the lines since the last one, and the plan share used when the event holds it
+//                       (read in preference to `token_usage_record`: it is the event already read for usage, it is the one that carries `rate_limits`, and it is on more responses)
 //   response_item function_call / local_shell_call / custom_tool_call   a tool call
 //   response_item function_call_output {call_id, output}   a shell call's outcome: the text `Exit code: N` / `Process exited with code N` then `Output:`
 //                       (the unified-exec emitter's own text, core/src/tools/events.rs:400, :416, :423; context.rs:556), the real exit code; `execution error: ...` (core/src/tools/events.rs:438) is a
@@ -53,6 +54,7 @@ import { basename, join } from 'node:path';
 import { createInterface } from 'node:readline';
 import { PassThrough, pipeline } from 'node:stream';
 import { createZstdDecompress, zstdDecompressSync } from 'node:zlib';
+import { holdsOnlyRecords } from './head-only.js';
 import { INTERRUPT_MARKER, SHAPE_TOOLS_LINE } from './session-shape.js';
 /** The Codex home for an environment; a test passes its own so it never reads the real one. */
 export const codexRoot = (env, home = homedir()) => {
@@ -230,30 +232,68 @@ const outcomeOf = (raw) => {
  * an `Exit code -1` line would be the error line and the message lost. The message stands alone then, and a code is the line capture skips.
  */
 const failureOf = (exit, text) => exit === undefined || exit === 0 ? undefined : exit < 0 && text.trim() !== '' ? text : `Exit code ${String(exit)}\n${text}`;
+/** One `rate_limits` window: the plan share used and the window's length. Absent when the event holds no number for it, never a zero. */
+const windowOf = (raw) => {
+    if (!isObj(raw))
+        return undefined;
+    const usedPercent = num(raw.used_percent);
+    if (usedPercent === undefined)
+        return undefined;
+    const windowMinutes = num(raw.window_minutes);
+    return { usedPercent, ...(windowMinutes === undefined ? {} : { windowMinutes }) };
+};
+/** The event's `rate_limits.primary` and `.secondary`, or undefined when it holds neither (older rollouts and local models write none). */
+const rateLimitsOf = (payload) => {
+    const limits = isObj(payload.rate_limits) ? payload.rate_limits : undefined;
+    const primary = windowOf(limits?.primary);
+    const secondary = windowOf(limits?.secondary);
+    return primary === undefined && secondary === undefined ? undefined : { ...(primary === undefined ? {} : { primary }), ...(secondary === undefined ? {} : { secondary }) };
+};
 const usageOf = (info) => {
     const last = isObj(info) && isObj(info.last_token_usage) ? info.last_token_usage : undefined;
     if (last === undefined)
         return undefined;
-    const input = num(last.input_tokens) ?? 0;
-    const cached = Math.min(num(last.cached_input_tokens) ?? 0, input);
-    const output = num(last.output_tokens) ?? 0;
+    const reportedInput = num(last.input_tokens);
+    const input = reportedInput ?? 0;
+    const reportedCached = num(last.cached_input_tokens);
+    const cached = Math.min(reportedCached ?? 0, input);
+    const reportedOutput = num(last.output_tokens);
+    const output = reportedOutput ?? 0;
     // A zero total means Codex recorded none, so no usage is written rather than a measured zero.
     if (input === 0 && output === 0)
         return undefined;
     const reasoning = num(last.reasoning_output_tokens);
-    const written = num(last.cache_write_input_tokens) ?? 0;
+    const reportedWritten = num(last.cache_write_input_tokens);
+    const written = reportedWritten ?? 0;
     // Codex counts cached and written tokens both inside `input_tokens` (input 100 = cached 40 + write 60, codex-api/src/sse/responses.rs:889-911); capture's
     // `input` excludes cache reads and creation, as the Claude Code path's does, so each token is counted once.
     return {
-        input_tokens: Math.max(input - cached - written, 0),
-        cache_read_input_tokens: cached,
-        cache_creation_input_tokens: written,
-        output_tokens: output,
+        // A category the event left out stays out (a partial event, or an older rollout with no cache keys), so it is neither a zero entry nor an observed field.
+        ...(reportedInput === undefined ? {} : { input_tokens: Math.max(input - cached - written, 0) }),
+        ...(reportedCached === undefined ? {} : { cache_read_input_tokens: cached }),
+        ...(reportedWritten === undefined ? {} : { cache_creation_input_tokens: written }),
+        ...(reportedOutput === undefined ? {} : { output_tokens: output }),
         ...(reasoning === undefined ? {} : { output_tokens_details: { thinking_tokens: reasoning } }),
     };
 };
 /** The non-blank lines of a rollout that are not JSON (a torn write), kept so `captureSession` counts them and the deposit line reports them. */
 export const rolloutBadLines = (text) => text.split('\n').filter((raw) => raw.trim() !== '' && parse(raw) === undefined);
+/** Rollout record types that carry no turn by design: the header and the per-turn context. A rollout of these alone is a session started and quit. */
+const ROLLOUT_HEAD_KINDS = new Set(['session_meta', 'turn_context']);
+/** Payload types the reader reads as carrying no turn: the usage event, an aborted turn (one the operator interrupted gives a prompt record, so it is no longer head-only), and the `response_item` messages of injected context (a prompt is the `event_msg` user_message). */
+const ROLLOUT_HEAD_EVENTS = new Set(['token_count', 'turn_aborted']);
+const ROLLOUT_HEAD_ITEMS = new Set(['message']);
+/** An assistant `response_item` message is a turn, which the reader reads from `event_msg` only: a rollout whose turns moved to it is a moved form, not an empty one. */
+const isAssistantItem = (record) => typeof record.payload === 'object' && record.payload !== null && 'role' in record.payload && record.payload.role === 'assistant';
+export const rolloutHeadOnly = (text) => holdsOnlyRecords(text, (record) => {
+    if (ROLLOUT_HEAD_KINDS.has(record.type))
+        return true;
+    const payload = record.payload;
+    const kind = typeof payload === 'object' && payload !== null && 'type' in payload ? payload.type : undefined;
+    if (typeof kind !== 'string')
+        return false;
+    return (record.type === 'event_msg' && ROLLOUT_HEAD_EVENTS.has(kind)) || (record.type === 'response_item' && ROLLOUT_HEAD_ITEMS.has(kind) && !isAssistantItem(record));
+});
 /**
  * The names in a list of tool declarations: each entry's `name` (a `DynamicToolSpec` function, dynamic_tools.rs; an `additional_tools` or
  * `tool_search_output` entry is an untyped value, models.rs:1076, :1257), and the names of a namespace's own `tools`; a namespace's own name is a grouping, not a tool. Nothing else is read: a
@@ -264,6 +304,49 @@ const toolNames = (list) => (Array.isArray(list) ? list : [])
     .filter((name) => name !== undefined && name !== '');
 /** The approval policy as the permission mode: a string, or the tag of an externally tagged object (`{granular: {...}}`, protocol.rs:1181), which `mode()` keeps if documented and stores as `other` if not. */
 const approvalMode = (policy) => (isObj(policy) ? Object.keys(policy)[0] : str(policy));
+/** The parent's records (not its `session_meta`) as the keys a copied fork's leading records are matched against. */
+const parentKeys = (parent) => parent
+    .split('\n')
+    .map((raw) => parse(raw))
+    .filter((parsed) => isObj(parsed) && isObj(parsed.payload) && parsed.type !== 'session_meta')
+    .map((parsed) => JSON.stringify([parsed.type, parsed.payload]));
+/** True for a `session_meta` of a Copied fork whose parent text is known: the leading records equal to the parent's are its copied history, in either mode. */
+const copiesParent = (payload, parentText) => parentText !== undefined && str(payload.forked_from_id) !== undefined && !isObj(payload.history_base);
+/**
+ * The rollout with the history it inherited removed (the records below a subagent's `subagent_history_start_ordinal`, and a Copied fork's leading
+ * copy of its parent), by the same two rules `rolloutLines` applies, so the head-only test sees only what the session itself wrote. Lines that are not
+ * a JSON object with a payload stay, as a torn line must still count.
+ */
+export const rolloutOwnText = (text, parentText) => {
+    let inherited;
+    let copied = null;
+    let seenMeta = false;
+    return text
+        .split('\n')
+        .filter((raw) => {
+        const entry = parse(raw);
+        if (!isObj(entry) || !isObj(entry.payload))
+            return true;
+        const ordinal = num(entry.ordinal);
+        if (inherited !== undefined && ordinal !== undefined && ordinal < inherited)
+            return false;
+        if (entry.type !== 'session_meta' && copied !== null) {
+            if (copied.keys[copied.at] === JSON.stringify([entry.type, entry.payload])) {
+                copied.at += 1;
+                return false;
+            }
+            copied = null;
+        }
+        if (entry.type === 'session_meta' && !seenMeta) {
+            seenMeta = true;
+            inherited = num(entry.payload.subagent_history_start_ordinal);
+            if (inherited === undefined && copiesParent(entry.payload, parentText))
+                copied = { keys: parentKeys(parentText), at: 0 };
+        }
+        return true;
+    })
+        .join('\n');
+};
 /** One rollout as the lines `captureSession` reads. */
 export const rolloutLines = (text, fallbackId, parentText) => {
     const nonblank = text.split('\n').filter((raw) => raw.trim() !== '');
@@ -439,11 +522,6 @@ export const rolloutLines = (text, fallbackId, parentText) => {
             settleMcp(id, failed ? (text === '' ? 'dynamic tool call failed' : text) : undefined, when);
         }
     };
-    const parentKeys = (parent) => parent
-        .split('\n')
-        .map((raw) => parse(raw))
-        .filter((parsed) => isObj(parsed) && isObj(parsed.payload) && parsed.type !== 'session_meta')
-        .map((parsed) => JSON.stringify([parsed.type, parsed.payload]));
     for (const raw of text.split('\n')) {
         const entry = parse(raw);
         if (!isObj(entry) || !isObj(entry.payload))
@@ -482,7 +560,7 @@ export const rolloutLines = (text, fallbackId, parentText) => {
                 dynamicNames.add(name);
             inherited = num(payload.subagent_history_start_ordinal);
             paginated = payload.history_mode === 'paginated';
-            if (inherited === undefined && parentText !== undefined && str(payload.forked_from_id) !== undefined && !isObj(payload.history_base))
+            if (inherited === undefined && copiesParent(payload, parentText))
                 copied = { keys: parentKeys(parentText), at: 0 };
         }
         else if (type === 'turn_context') {
@@ -527,6 +605,10 @@ export const rolloutLines = (text, fallbackId, parentText) => {
                     const first = open.message;
                     if (isObj(first))
                         first.usage = usage;
+                    // The plan reading rides the response's first line beside its usage, so a repeated event adds neither.
+                    const rateLimits = rateLimitsOf(payload);
+                    if (rateLimits !== undefined)
+                        open.rateLimits = rateLimits;
                     lastTotal = total;
                     response += 1;
                     open = undefined;
@@ -727,6 +809,11 @@ export const openCodexStore = async (root) => {
         origin.mtimeMs = Math.max(origin.mtimeMs, own.mtimeMs);
         sessions.delete(id);
     }
+    // A Copied fork's history is found by matching it against the parent's lineage as of the fork's start; a parent outside the store (or unreadable) leaves it whole.
+    const parentTextOf = async (session) => {
+        const parent = session.forkedFrom === null ? undefined : sessions.get(session.forkedFrom);
+        return parent === undefined ? undefined : lineageText(parent, session.started).catch(() => undefined);
+    };
     const ordered = [...sessions.values()].sort((a, b) => a.mtimeMs - b.mtimeMs || a.id.localeCompare(b.id));
     return {
         sessions: ordered,
@@ -735,11 +822,10 @@ export const openCodexStore = async (root) => {
         transcript: async (session) => {
             // A rollout that vanished after it was listed (Codex compresses an old one) fails with its reason, which names no path.
             const text = await lineageText(session);
-            // A Copied fork's history is found by matching it against the parent's lineage as of the fork's start; a parent outside the store (or unreadable) leaves it whole.
-            const parent = session.forkedFrom === null ? undefined : sessions.get(session.forkedFrom);
-            const parentText = parent === undefined ? undefined : await lineageText(parent, session.started).catch(() => undefined);
+            const parentText = await parentTextOf(session);
             const lines = [...rolloutLines(text, session.id, parentText).map((line) => JSON.stringify(line)), ...rolloutBadLines(text)];
             return lines.join('\n') + (lines.length === 0 ? '' : '\n');
         },
+        headOnly: async (session) => rolloutHeadOnly(rolloutOwnText(await lineageText(session), await parentTextOf(session))),
     };
 };

package/dist/sessions/command.d.ts

@@ -4,6 +4,7 @@ import type { Emit } from '../telemetry/emit.js';
 import { type PullInput } from './recall-reads.js';
 import { type ContextOptions } from './hook-index.js';
 import { type InstallRuntime, type Scope } from './install.js';
+import { type HarnessFiles } from './harness-files.js';
 import { type SessionsRuntime, type SkippedScope } from './store.js';
 import { type StuckStep } from './steps.js';
 import { type SelfBaselineResult } from './baseline.js';
@@ -27,6 +28,11 @@ export declare const sessionsDeposit: (deps: SessionsDeps, options: {
  * this command answers an operator, so the `--error`, `--path`, and `--class` forms keep the signature text they have always printed; the MCP tool, which answers an agent, does not.
  */
 export declare const sessionsRecall: (deps: SessionsDeps, query: PullInput, sid?: string | null) => Promise<Outcome>;
+/**
+ * `recall --error <text> --receipt`: the same pull, recorded as any recall is, printed as a paste-ready block for an issue. Only `--error` asks about one error;
+ * every other form refuses, because a receipt states one signature.
+ */
+export declare const sessionsReceipt: (deps: SessionsDeps, query: PullInput, sid?: string | null) => Promise<Outcome>;
 /** `recall --counts`: push and pull, shown and held, as counts only. */
 export declare const sessionsRecallCounts: (deps: SessionsDeps, day: string | undefined) => Promise<Outcome>;
 /** `lineage`: a walk over files the derive already wrote. It computes nothing, so it logs no step. */
@@ -69,6 +75,8 @@ export interface VerifyReport {
     scope: SkippedScope;
     /** Every session's rows 1 to 10 with a status each (spec 5.4 item 5): `pass`, `fail`, or `not run` when the row had nothing to check. */
     sessionResults: SessionVerification[];
+    /** Per harness, the session files seen, how many yielded records, and how many were unreadable (`harness-files.ts` defines them). Read from the harness's own store on this machine; nothing is sent. */
+    harnessFiles: HarnessFiles;
     /** Layer 4 at T0, local (spec 2.4): each session's raw-file match, recomputed root, and count bindings, with the count of each row of the result table. */
     audit: {
         counts: T0Counts;
@@ -119,9 +127,16 @@ export interface HookTarget {
 }
 export declare const sessionsHookInstall: (deps: SessionsDeps, options: HookTarget & {
     keepRetention: boolean;
-    schedule: "nightly" | "off" | undefined;
+    schedule: "nightly" | "off" | "on" | undefined;
+    harness?: "codex" | undefined;
+    machine?: boolean | undefined;
+    env?: readonly string[] | undefined;
+    termsFile?: string | undefined;
+}) => Promise<Outcome>;
+export declare const sessionsHookUninstall: (deps: SessionsDeps, options: HookTarget & {
+    harness?: "codex" | undefined;
 }) => Promise<Outcome>;
-export declare const sessionsHookUninstall: (deps: SessionsDeps, options: HookTarget) => Promise<Outcome>;
 export declare const sessionsHookStatus: (deps: SessionsDeps, options: {
     file: string | undefined;
+    harness?: "codex" | undefined;
 }) => Promise<Outcome>;

package/dist/sessions/command.js

@@ -7,7 +7,7 @@ import { CliError, ExitCode } from '../errors.js';
 import { loadTerms } from './exclusion.js';
 import { EVALUATOR_MODEL, fillArms, sidecarSaver } from './gold-arms.js';
 import { armsPath, coverageLines, formatScore, isGoldDocument, parseGold, plural, renderGold, sampleGold, scoreGold } from './gold.js';
-import { makeRedactor } from './redact.js';
+import { localNames, makeRedactor } from './redact.js';
 import { books, BOOKS_CAVEAT, formatBooks, formatMeasure, formatRecall, measure } from './query.js';
 import { formatLineage, loadLineage, walkLineage } from './lineage.js';
 import { recallFields } from '../telemetry/fields.js';
@@ -15,9 +15,14 @@ import { appendRecall, readRecalls } from './recall-object.js';
 import { deriveConsequences, formatRecallCounts, recallCounts } from './recall-consequence.js';
 import { pull, pullRefusal } from './recall-reads.js';
 import { MISS_TEXT } from './recall-render.js';
+import { receiptOf, RECEIPT_MISS } from './receipt.js';
+import { EMPTY_RECALL, emptyBooks, nothingFoundLines, savedListNote } from './empty-state.js';
 import { readHookCalls } from './hook-calls.js';
 import { buildIndex, contextBlock, inRepository, readIndex } from './hook-index.js';
-import { ensureSchedule, hookStatus, installHooks, recordSchedule, SCHEDULE_LEFT_OFF, scheduleOptedOut, scheduleStatus, setSchedule, settingsPath, uninstallHooks } from './install.js';
+import { CODEX_TRUST_NOTICE, codexHookStatus, installCodexHook, uninstallCodexHook } from './codex-hook-install.js';
+import { enrollmentOf } from './machine.js';
+import { hookStatus, installHooks, installMachineHooks, readSettings, removeSchedule, SCHEDULE_REFUSED, scheduleStatus, settingsPath, uninstallHooks } from './install.js';
+import { recordSchedule } from './pool-due.js';
 import { serve } from './mcp.js';
 import { refreshPool, servedPool } from './pool.js';
 import { recallPool } from './recall-bundle.js';
@@ -29,7 +34,8 @@ import { FAMILIES } from './read.js';
 import { formatNotReadable, notReadable } from './read-readable.js';
 import { formatReads, isFamily, parseSlice, selectReads } from './read-rows.js';
 import { CAPTURE_VERSION, OLDEST_READABLE_CAPTURE } from './schema.js';
-import { deposit, frozenSessions, loadStore, readCalls, readRedactDomains, readSaved, readSkeletons, skippedFolders, slugOf } from './store.js';
+import { harnessFileCounts } from './harness-files.js';
+import { deposit, frozenSessions, loadStore, paths, readCalls, readRedactDomains, readSaved, readSkeletons, skippedFolders, slugOf } from './store.js';
 import { formatStepCounters, inputKey, newContext, readSteps, stampKey, runDeposit, runStep, stepCounters, stuckSteps, tryLog } from './steps.js';
 import { formatSelfBaseline, selfBaseline as selfBaselineOf } from './baseline.js';
 import { staleBatchesAnywhere } from './pool-outbox.js';
@@ -70,6 +76,8 @@ export const sessionsDeposit = async (deps, options) => {
     const lines = [
         `Deposited ${String(result.sessions)} sessions and ${String(result.subagents)} subagent transcripts (${String(result.lines)} lines, ${String(result.badLines)} unparseable) as ${String(result.observations)} observations; ${String(result.unchanged)} files unchanged.`,
         `Read ${String(result.folders.length)} folders; skipped ${String(result.skippedFolders)} not on the allowlist.`,
+        // The list an earlier run saved decides what a plain deposit reads; the run says so instead of looking like "every source".
+        ...savedListNote(read, allow, paths(runtime.storeDir).state),
         ...Object.entries(result.sources).flatMap(([name, counts]) => [
             ...(counts.read === 0 ? [] : [`Read ${String(counts.read)} ${sourceLabel(name, table)} sessions.`]),
             ...counts.unreadable.map((reason) => `${sourceLabel(name, table)} store not read: ${reason}`),
@@ -79,6 +87,8 @@ export const sessionsDeposit = async (deps, options) => {
         survival === null
             ? 'Commit survival not read this run.'
             : `Commits older than ${String(SURVIVAL_DAYS)} days: ${String(survival.survived)} survived, ${String(survival.reverted)} reverted, ${String(survival.unreachable)} unreachable, ${String(survival.unknown)} unknown.`,
+        // Nothing parsed and nothing already deposited: say where it looked, so an empty result is not a silent one.
+        ...(result.sessions + result.subagents + result.unchanged === 0 ? nothingFoundLines(result, runtime, table, read) : []),
     ];
     return { document: { ok: true, ...result, survival }, text: lines.join('\n') };
 };
@@ -97,18 +107,32 @@ export const sessionsRecall = async (deps, query, sid = null) => {
     const { storeDir } = runtimeOf(deps);
     // The key is the query and `ev`, known before the work, so a recall that keeps failing is the same key each time.
     const key = stampKey(JSON.stringify(query));
-    const result = await runStep(newContext(storeDir, deps.now, 'manual'), 'recall', async () => {
+    const { found: result, empty } = await runStep(newContext(storeDir, deps.now, 'manual'), 'recall', async () => {
         const store = await loadStore(storeDir);
         const found = pull(store, query, { sid, now: deps.now(), frame: null, redactDomains: await readRedactDomains(storeDir), current: await recallPool(storeDir, store, servedPool) });
-        return { value: found, report: { in: { query: 1 }, out: { matches: found.legacy?.matches.length ?? found.reads.length }, key } };
+        return { value: { found, empty: store.sessions.length === 0 }, report: { in: { query: 1 }, out: { matches: found.legacy?.matches.length ?? found.reads.length }, key } };
     }, key);
     await tryLog(() => appendRecall(storeDir, result.recall));
     // Counts and closed words only: how it was asked, the families it served, how many reads, and its arm. Never the query or the answer.
     deps.telemetry?.('recall', recallFields(result.recall, result.reads.map((read) => read.family), result.legacy !== undefined));
+    // A miss over a store with no sessions is not "no match": the store has nothing to match, and the text names the command that fills it.
     if (result.legacy !== undefined)
-        return { document: { ok: true, ...result.legacy, recall: result.recall }, text: formatRecall(result.legacy) };
+        return { document: { ok: true, ...result.legacy, recall: result.recall }, text: empty && result.legacy.matches.length === 0 ? EMPTY_RECALL : formatRecall(result.legacy) };
     // The document states the recall and not the raw reads: a read's tool, keys, and versions are store strings that can carry text, and `recall.evidence` already states them closed.
-    return { document: { ok: true, recall: result.recall }, text: result.recall.answer.rendered === '' ? MISS_TEXT : result.recall.answer.rendered };
+    return { document: { ok: true, recall: result.recall }, text: result.recall.answer.rendered === '' ? (empty ? EMPTY_RECALL : MISS_TEXT) : result.recall.answer.rendered };
+};
+/**
+ * `recall --error <text> --receipt`: the same pull, recorded as any recall is, printed as a paste-ready block for an issue. Only `--error` asks about one error;
+ * every other form refuses, because a receipt states one signature.
+ */
+export const sessionsReceipt = async (deps, query, sid = null) => {
+    if ('form' in query || query.error === undefined || query.path !== undefined || query.cls !== undefined || query.sinceDays !== undefined) {
+        throw new CliError('--receipt answers one error: pass --error "<text>" and no other form.', ExitCode.USAGE, 'usage');
+    }
+    await sessionsRecall(deps, query, sid);
+    const { storeDir } = runtimeOf(deps);
+    const block = receiptOf(await loadStore(storeDir), query, deps.now(), await readRedactDomains(storeDir), localNames());
+    return { document: { ok: true, receipt: block }, text: block ?? RECEIPT_MISS };
 };
 /** `recall --counts`: push and pull, shown and held, as counts only. */
 export const sessionsRecallCounts = async (deps, day) => {
@@ -149,12 +173,16 @@ export const sessionsContext = async (deps, options) => {
     const { storeDir } = runtimeOf(deps);
     // The manual recall verb (spec 4.1): its key is what it looks up, the repository's cwd and the harness, known before the work.
     const key = stampKey('context', options.cwd, options.harness ?? '');
-    const block = await runStep(newContext(storeDir, deps.now, 'manual'), 'recall', async () => {
+    const step = await runStep(newContext(storeDir, deps.now, 'manual'), 'recall', async () => {
         const index = (await readIndex(storeDir)) ?? buildIndex(await loadStore(storeDir), await readRedactDomains(storeDir), new Date(deps.now()).toISOString());
         const found = contextBlock(index, options);
-        return { value: found, report: { in: { query: 1 }, out: { matches: found === undefined ? 0 : 1 }, key } };
+        return { value: { found, noProjects: Object.keys(index.projects).length === 0 }, report: { in: { query: 1 }, out: { matches: found === undefined ? 0 : 1 }, key } };
     }, key);
-    return { document: { ok: true, context: block ?? null }, text: block ?? 'Nothing recurs in this repository yet.' };
+    // Nothing to inject because the store holds no sessions at all is an empty store, not a quiet repository: say so and name the command that fills it.
+    // An index that names projects answers alone; the store is loaded only when the index is empty, to tell an empty store from an index with nothing to say.
+    const block = step.found;
+    const text = block ?? (step.noProjects && (await loadStore(storeDir)).sessions.length === 0 ? EMPTY_RECALL : 'Nothing recurs in this repository yet.');
+    return { document: { ok: true, context: block ?? null }, text };
 };
 export const sessionsMcp = async (deps) => {
     await serve(runtimeOf(deps), deps.now, deps.telemetry);
@@ -173,6 +201,11 @@ const skippedNotice = (scope) => {
     const transcripts = scope.transcripts === 0 ? 'no main transcript' : scope.transcripts === 1 ? '1 main transcript' : `${String(scope.transcripts)} main transcripts`;
     return [`${folders} ${transcripts}; ${one ? 'it is' : 'they are'} never read: not on the allowlist. Not captured: ${shown}${more}.`];
 };
+/** The three counts per harness, as numbers only: no cause, no path, no verdict. */
+const harnessFilesLines = (files, table) => {
+    const rows = Object.entries(files).map(([harness, counts]) => `  ${harness === 'claude-code' ? 'Claude Code' : sourceLabel(harness, table)}: seen ${String(counts.seen)}, yielded ${String(counts.yielded)}, unreadable ${String(counts.unreadable)}`);
+    return rows.length === 0 ? [] : ['Session files per harness:', ...rows];
+};
 /** Scope is an extra, like the step log: a projects root this process cannot list reports an empty scope and fails neither `verify` nor `books`. */
 const scopeOf = (runtime) => skippedFolders(runtime).catch(() => ({ folders: 0, transcripts: 0, names: [] }));
 /** One line for a store a newer oars wrote into (spec state-on-open row for a newer `cv`: read known fields, warn). */
@@ -205,7 +238,9 @@ const packageBooksOutcome = async (deps, options) => {
     const [{ excluded }, store] = await Promise.all([scanStore(runtime, options.termsFile), loadStore(runtime.storeDir)]);
     const cutoff = options.sinceDays === undefined ? undefined : new Date(deps.now() - options.sinceDays * 86_400_000).toISOString();
     const result = packageBooks(store, new Set(excluded.map((entry) => entry.session)), vocabulary(), cutoff);
-    return { document: { ok: true, by: 'package', ...result, newerCaptures: store.newerCaptures }, text: [formatPackageBooks(result), ...newerNotice(store)].join('\n') };
+    // The same empty-store text the other `books` forms print, so it names the command that fills the store.
+    const table = store.sessions.length === 0 && store.prompts.length === 0 ? emptyBooks('public package pulls') : formatPackageBooks(result);
+    return { document: { ok: true, by: 'package', ...result, newerCaptures: store.newerCaptures }, text: [table, ...newerNotice(store)].join('\n') };
 };
 export const sessionsBooks = async (deps, options) => {
     if (options.by === 'package') {
@@ -220,11 +255,13 @@ export const sessionsBooks = async (deps, options) => {
     const rows = books(store, options.by, deps.now(), options.sinceDays, await readSurvival(storeDir));
     // A mistyped root, or a --since window nothing falls in, over a populated store must not read as an empty store.
     const emptyWindow = rows.length === 0 && options.sinceDays !== undefined && store.prompts.length > 0;
-    const table = store.prompts.length === 0 && options.repo !== undefined
-        ? `No prompts for ${options.repo} in the store (${String(loaded.prompts.length)} prompts across all repositories).`
-        : emptyWindow
-            ? `No ${options.by === 'pull' ? 'pulls' : 'prompts'} in the --since window.`
-            : formatBooks(rows, options.by);
+    const table = loaded.sessions.length === 0 && loaded.prompts.length === 0
+        ? emptyBooks(options.by === 'pull' ? 'pulls' : 'prompts')
+        : store.prompts.length === 0 && options.repo !== undefined
+            ? `No prompts for ${options.repo} in the store (${String(loaded.prompts.length)} prompts across all repositories).`
+            : emptyWindow
+                ? `No ${options.by === 'pull' ? 'pulls' : 'prompts'} in the --since window.`
+                : formatBooks(rows, options.by);
     const scope = await scopeOf(runtime);
     const bundle = await lastFetchedBundle(storeDir);
     return { document: { ok: true, by: options.by, rows, newerCaptures: store.newerCaptures, scope, pool: bundle?.books ?? null }, text: [table, ...skippedNotice(scope), ...newerNotice(store), '', ...booksLines(bundle), ...(rows.length === 0 ? [] : ['', BOOKS_CAVEAT])].join('\n') };
@@ -271,10 +308,12 @@ export const sessionsVerify = async (deps, options) => {
         // A verify that got here has succeeded, so a verify streak is the one this run ends and is not listed.
         const stuck = stuckSteps(await readSteps(storeDir).catch(() => [])).filter((entry) => entry.step !== 'verify');
         const scope = await scopeOf(runtime);
+        // Like the scope, an extra: a store that cannot be read is an unreadable count inside it, and a failure outside it leaves the section out.
+        const harnessFiles = await harnessFileCounts(runtime).catch(() => ({}));
         // A local count like the scope: an outbox folder that cannot be read is no reason for `verify` to fail.
         const staleBatches = await staleBatchesAnywhere(storeDir).catch(() => 0);
         const totals = await outboxTotals(storeDir).catch(() => ({ sentBatches: 0, sentRaw: 0, rawCopies: 0, rawMasked: 0 }));
-        const report = { sessions: skeletons.length, unreadable, cvFrozen: frozen.size, scope, invariants: results.map((result) => ({ ...result, pass: result.violations === 0 })), stuck, sessionResults, audit, selfBaseline, staleBatches, ...totals };
+        const report = { sessions: skeletons.length, unreadable, cvFrozen: frozen.size, scope, harnessFiles, invariants: results.map((result) => ({ ...result, pass: result.violations === 0 })), stuck, sessionResults, audit, selfBaseline, staleBatches, ...totals };
         const failed = [...results.filter((result) => result.violations > 0).map((result) => result.name), ...(unreadable > 0 ? ['unreadable skeletons'] : []), ...merkleFailed, ...stuck.map((entry) => `stuck: ${entry.step}`)];
         const stuckLines = stuck.map((entry) => `FAIL  ${entry.step} is stuck: key ${entry.key} failed ${String(entry.runs)} runs in a row: ${entry.error}`);
         const highWater = mine([...store.sessions, ...store.subagents]).map((session) => `${session.session}:${String(session.rev)}:${session.cv}`).sort();
@@ -283,7 +322,7 @@ export const sessionsVerify = async (deps, options) => {
             failed,
             report,
             document: { ok: true, ...report, newerCaptures: store.newerCaptures },
-            text: [formatVerify(results, skeletons.length), formatAudit(audits), formatSelfBaseline(selfBaseline), ...(resultLines === '' ? [] : [resultLines]), ...(frozen.size > 0 ? [`${String(frozen.size)} cv-frozen sessions: behind the current capture version, but the transcript is gone from the harness and raw/ (or, for a Cursor session, the composer is gone from Cursor), so they cannot be captured again`] : []), ...skippedNotice(scope), ...(staleBatches > 0 ? [`${String(staleBatches)} outbox batches were built under an older vocabulary, field list, or skeleton format; they will never be sent, and oars pool deposit removes them`] : []), ...(totals.sentBatches + totals.sentRaw > 0 ? [`${String(totals.sentBatches)} outbox ${totals.sentBatches === 1 ? 'batch' : 'batches'} and ${String(totals.sentRaw)} raw ${totals.sentRaw === 1 ? 'copy were' : 'copies were'} already sent`] : []), ...(totals.rawCopies > 0 ? [`${String(totals.rawCopies)} queued raw ${totals.rawCopies === 1 ? 'copy holds' : 'copies hold'} ${String(totals.rawMasked)} placeholders (masked values, plus any a transcript already held as text)`] : []), ...newerNotice(store), ...(unreadable > 0 ? [`FAIL  ${String(unreadable)} unreadable skeleton files (torn or corrupted); redeposit to rebuild them`] : []), ...stuckLines].join('\n'),
+            text: [formatVerify(results, skeletons.length), formatAudit(audits), formatSelfBaseline(selfBaseline), ...(resultLines === '' ? [] : [resultLines]), ...(frozen.size > 0 ? [`${String(frozen.size)} cv-frozen sessions: behind the current capture version, but the transcript is gone from the harness and raw/ (or, for a Cursor session, the composer is gone from Cursor), so they cannot be captured again`] : []), ...harnessFilesLines(harnessFiles, runtime.sources ?? SOURCES), ...skippedNotice(scope), ...(staleBatches > 0 ? [`${String(staleBatches)} outbox batches were built under an older vocabulary, field list, or skeleton format; they will never be sent, and oars pool deposit removes them`] : []), ...(totals.sentBatches + totals.sentRaw > 0 ? [`${String(totals.sentBatches)} outbox ${totals.sentBatches === 1 ? 'batch' : 'batches'} and ${String(totals.sentRaw)} raw ${totals.sentRaw === 1 ? 'copy were' : 'copies were'} already sent`] : []), ...(totals.rawCopies > 0 ? [`${String(totals.rawCopies)} queued raw ${totals.rawCopies === 1 ? 'copy holds' : 'copies hold'} ${String(totals.rawMasked)} placeholders (masked values, plus any a transcript already held as text)`] : []), ...newerNotice(store), ...(unreadable > 0 ? [`FAIL  ${String(unreadable)} unreadable skeleton files (torn or corrupted); redeposit to rebuild them`] : []), ...stuckLines].join('\n'),
         };
         const cvBehind = results.find((result) => result.name === CAPTURE_INVARIANTS[0])?.violations ?? 0;
         // The key is the sessions checked, each at its rev and cv, and the code's ev (spec 4.2).
@@ -373,47 +412,120 @@ const installOf = (deps) => {
         throw new CliError('Hook install is not configured in this run.', ExitCode.UNEXPECTED, 'unexpected');
     return deps.install;
 };
+const codexOf = (deps) => {
+    const codex = installOf(deps).codex;
+    if (codex === undefined)
+        throw new CliError('The Codex hook is not configured in this run.', ExitCode.UNEXPECTED, 'unexpected');
+    return codex;
+};
+/** `--harness codex` writes to the Codex home, so a settings-file flag beside it names a target that does not apply. */
+const refuseSettingsFlags = (options) => {
+    if (options.scope !== undefined || options.file !== undefined)
+        throw new CliError('--harness codex writes hooks.json in the Codex home; --scope and --file apply to Claude Code settings only.', ExitCode.USAGE, 'usage');
+};
 /** `--scope`, else `file` when `--file` names one, else the user settings. */
 const hookScope = (options) => options.scope ?? (options.file === undefined ? 'user' : 'file');
+/** What `--schedule off` and `--schedule on` say: the recorded choice about the background sweep and send that the session-end hook and every command start. */
+const SENDS_OFF = 'The background sweep and the pool send are off, as you chose with --schedule off (telemetry has its own switch: oars telemetry off). Turn them back on with: oars sessions hook install --schedule on';
+const SENDS_ON = 'Background sweeps and sends are on: a due sweep and send starts from the session-end hook and from any oars command, at most about hourly.';
+/** `--machine`: the Stop and SessionEnd entries for a cloud VM, a VPS, or a runner, and for a user-scope file the enrollment block too. Refused beside every flag it does not take, before anything is written. */
+const installMachine = async (deps, options) => {
+    const refuse = (message) => new CliError(message, ExitCode.USAGE, 'usage');
+    if (options.harness !== undefined || options.schedule !== undefined)
+        throw refuse('--machine writes the Stop and SessionEnd entries of a machine; --harness and --schedule do not apply to it.');
+    if (options.keepRetention === true)
+        throw refuse('--keep-retention does not apply to --machine: a machine install leaves cleanupPeriodDays alone.');
+    const scope = hookScope(options);
+    if (scope === 'file')
+        throw refuse('--machine takes --scope project (the .claude/settings.json of a repository, committed) or --scope user (the ~/.claude/settings.json of a VPS or runner).');
+    if (options.file !== undefined)
+        throw refuse('--file does not apply to --machine: it writes the user or project settings file named by --scope.');
+    const runtime = installOf(deps);
+    const file = settingsPath(runtime, scope, undefined);
+    const lines = [];
+    let result;
+    if (scope === 'project') {
+        if ((options.env ?? []).length > 0 || options.termsFile !== undefined)
+            throw refuse('--env and --terms-file belong to --scope user: a project settings file is committed, and the enrollment block holds salts and terms.');
+        result = await installMachineHooks(file, undefined);
+        lines.push(`Installed ${result.installed.join(' and ')} machine hooks in ${file}. They run only where OARS_HOST_CLASS is set to a class other than local; set it, and the rest of the enrollment block, in the environment that runs the session.`);
+    }
+    else {
+        // A file that cannot be read is refused before the terms file is written.
+        await readSettings(file);
+        const enrollment = await enrollmentOf(options.env ?? [], options.termsFile, runtime.cwd);
+        result = await installMachineHooks(file, enrollment.env);
+        lines.push(`Installed ${result.installed.join(' and ')} machine hooks and the enrollment block in ${file}, which is now readable by its owner only.`);
+        if (enrollment.termsPath !== undefined)
+            lines.push(`The exclusion terms are in ${enrollment.termsPath} (owner-only), named by OARS_EXCLUSION_TERMS.`);
+        if (enrollment.env.OARS_EXCLUSION_TERMS === undefined && enrollment.env.OARS_EXCLUSION_TERMS_INLINE === undefined)
+            lines.push('No exclusion terms were given: with no term file every session is excluded (fail-closed), so nothing will be built.');
+    }
+    return { document: { ok: true, machine: true, install: result }, text: lines.join('\n') };
+};
 export const sessionsHookInstall = async (deps, options) => {
+    if (options.machine === true)
+        return installMachine(deps, options);
+    if ((options.env ?? []).length > 0 || options.termsFile !== undefined)
+        throw new CliError('--env and --terms-file belong to --machine.', ExitCode.USAGE, 'usage');
+    if (options.harness === 'codex') {
+        refuseSettingsFlags(options);
+        if (options.schedule !== undefined)
+            throw new CliError('--schedule applies to the Claude Code hooks, not --harness codex.', ExitCode.USAGE, 'usage');
+        const result = await installCodexHook(codexOf(deps));
+        return { document: { ok: true, harness: 'codex', ...result, trust: 'asked by codex' }, text: `Installed ${result.installed.join(', ')} hooks in ${result.file}.\n${CODEX_TRUST_NOTICE}` };
+    }
     const runtime = installOf(deps);
+    // `--schedule nightly` asked for the task this version no longer registers: refused before anything is written.
+    if (options.schedule === 'nightly')
+        throw new CliError(SCHEDULE_REFUSED, ExitCode.USAGE, 'usage');
     const lines = [];
     const document = { ok: true };
-    // `--schedule` alone touches no settings file: it names the task, not the hooks.
+    // `--schedule off` or `on` alone touches no settings file; it removes the old task and records the choice.
     if (options.schedule === undefined || options.scope !== undefined || options.file !== undefined) {
         const file = settingsPath(runtime, hookScope(options), options.file);
         const result = await installHooks(runtime, file, options.keepRetention);
         document.install = result;
         lines.push(`Installed ${result.installed.join(', ')} hooks in ${file}.`, result.retention);
     }
-    // Without `--schedule`, Windows gets the nightly task too; `--schedule off` is the opt-out, and it sticks until `--schedule nightly`.
-    if (options.schedule !== undefined || runtime.platform === 'win32') {
+    const removed = await removeSchedule(runtime);
+    if (removed !== undefined) {
+        document.schedule = removed;
+        lines.push(removed);
+    }
+    if (options.schedule !== undefined) {
         const storeDir = deps.sessions?.storeDir;
-        const optedOut = options.schedule === undefined && storeDir !== undefined && (await scheduleOptedOut(storeDir));
-        let line = SCHEDULE_LEFT_OFF;
-        if (options.schedule !== undefined) {
-            line = await setSchedule(runtime, options.schedule);
+        if (storeDir !== undefined)
             await recordSchedule(storeDir, options.schedule);
-        }
-        else if (!optedOut) {
-            line = await ensureSchedule(runtime);
-        }
-        document.schedule = line;
-        lines.push(line);
+        document.sends = options.schedule;
+        // An explicit `off` that found no task still says why nothing was removed, so the output is never empty.
+        if (options.schedule === 'off' && removed === undefined)
+            lines.push(`No scheduled task to remove${runtime.platform === 'win32' ? '' : ' (only Windows ever had one)'}.`);
+        lines.push(options.schedule === 'off' ? SENDS_OFF : SENDS_ON);
     }
     return { document, text: lines.join('\n') };
 };
 export const sessionsHookUninstall = async (deps, options) => {
+    if (options.harness === 'codex') {
+        refuseSettingsFlags(options);
+        const result = await uninstallCodexHook(codexOf(deps));
+        return { document: { ok: true, harness: 'codex', ...result }, text: result.removed.length === 0 ? `No Many Oars hooks in ${result.file}.` : `Removed ${result.removed.join(', ')} hooks from ${result.file}; other hooks are untouched.` };
+    }
     const runtime = installOf(deps);
     const file = settingsPath(runtime, hookScope(options), options.file);
     const result = await uninstallHooks(file);
+    const removed = await removeSchedule(runtime);
     const text = result.removed.length === 0 ? `No Many Oars hooks in ${file}.` : `Removed ${result.removed.join(', ')} hooks from ${file}; other settings and hooks are untouched (cleanupPeriodDays is left as it is).`;
-    return { document: { ok: true, ...result }, text };
+    return { document: { ok: true, ...result, ...(removed === undefined ? {} : { schedule: removed }) }, text: removed === undefined ? text : `${text}\n${removed}` };
 };
 export const sessionsHookStatus = async (deps, options) => {
+    if (options.harness === 'codex') {
+        const result = await codexHookStatus(codexOf(deps));
+        return { document: { ok: true, harness: 'codex', ...result }, text: `codex: ${result.file}: ${result.installed.length === 0 ? 'no hooks' : result.installed.join(', ')}` };
+    }
     const runtime = installOf(deps);
     const files = await hookStatus(runtime, options.file);
     const schedule = await scheduleStatus(runtime);
     const lines = files.map((item) => `${item.scope}: ${item.file}: ${item.installed.length === 0 ? 'no hooks' : item.installed.join(', ')} (cleanupPeriodDays ${String(item.retentionDays)})`);
-    return { document: { ok: true, files, schedule }, text: [...lines, schedule].join('\n') };
+    return { document: { ok: true, files, ...(schedule === undefined ? {} : { schedule }) }, text: (schedule === undefined ? lines : [...lines, schedule]).join('\n') };
 };

package/dist/sessions/copilot.d.ts

@@ -24,6 +24,8 @@ export interface CopilotStore {
     sessions: CopilotSession[];
     /** The session as transcript text for `captureSession`; throws when the file cannot be read or holds no parseable line. */
     transcript: (session: CopilotSession) => Promise<string>;
+    /** True when the log holds only head records (`eventHeadOnly`); `sessions verify` counts such a file as empty, not unreadable. */
+    headOnly: (session: CopilotSession) => Promise<boolean>;
     /** Folders skipped because their name is not a safe file name (it names a skeleton), counted so the skip is never silent. */
     rejected: number;
     /** Sessions that could not be inspected, reported once each and never fatal; the reason names no path. */
@@ -34,6 +36,7 @@ export interface CopilotStore {
 }
 /** The non-blank lines that are not JSON (a torn write), kept so `captureSession` counts them and the deposit line reports them. */
 export declare const eventBadLines: (text: string) => string[];
+export declare const eventHeadOnly: (text: string) => boolean;
 /** One session as the lines `captureSession` reads. */
 export declare const eventLines: (text: string, fallbackId: string) => Obj[];
 export declare const openCopilotStore: (root: string) => Promise<CopilotStore | undefined>;