@manyoars/oars 0.3.0 → 0.4.1

package/dist/sessions/codex.js

@@ -36,12 +36,16 @@
 //                       `declined` one (exit code -1, events.rs:552-554) settles as a refusal only where its output is the user's refusal text (`exec command rejected by user`), and nothing otherwise. A `failed` one with exit code -1 is a failure with no exit status (a tool
 //                       failure message, events.rs:538-542; a process with none, async_watcher.rs:213, :409), so its text is the error line. So a backgrounded process keeps its failure and its commit sha
 //                       even with no `write_stdin` poll; only a Legacy rollout leaves it unsettled until a poll, and there the poll settles it
+//   response_item custom_tool_call `exec` / function_call `wait`   Codex 0.166+ code mode (the live 0.166/0.167 store, 2026-11-06; upstream rust-v0.167.0 not yet read): `exec`'s input is a JavaScript cell, not a command; its
+//                       output opens `Script completed`, `Script failed` (+ a `Script error:` part), or `Script running with cell ID <id>`, which is the cell's outcome and never its
+//                       commands'. `wait {cell_id}` polls a cell with the same three headers and settles it, in Paginated mode too
+//   event_msg item_completed CommandExecution, id `exec-<uuid>` (no call owns it, 0.166+)   the command a cell ran, as its own Bash call: exit_code, aggregated_output, duration
 //   event_msg mcp_tool_call_end {call_id, result}   an MCP call's outcome: `result.Err`, or `result.Ok.isError` (protocol.rs:3047, :3076); Legacy mode only
 //   event_msg patch_apply_end {call_id, success, stderr, status}   an apply_patch call's outcome (Legacy mode only); a declined one settles as a refusal only where its stderr is the user's refusal text (`patch rejected by user`), and nothing otherwise, and a
 //                       patch with no end event stays unsettled (a rejected patch is only a `RespondToModel` output, tools/handlers/apply_patch.rs)
 //   event_msg exec_command_end                  never persisted at ac558e2 (policy.rs:165) nor at rust-v0.46.0, so it is not read: the CommandExecution item and the call's output are the two sources
 // Older shapes: the JSON `{output, metadata.exit_code}` wrapper of a shell output (rust-v0.46.0 core/src/tools/mod.rs:186-210).
-// What Codex has no equivalent of (cost) stays at the value capture gives an absent field; message ids and duration are persisted and not read.
+// What Codex has no equivalent of (cost) stays at the value capture gives an absent field; message ids and a call reply's wall time are persisted and not read (a code-mode command item's `duration` is).
 import { createReadStream } from 'node:fs';
 import { readdir, readFile, stat } from 'node:fs/promises';
 import { homedir } from 'node:os';
@@ -49,7 +53,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 { SHAPE_INTERRUPT_LINE, SHAPE_TOOLS_LINE } from './session-shape.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()) => {
     const set = env.CODEX_HOME;
@@ -140,14 +144,16 @@ const iso = (value) => {
     return text !== undefined && Date.parse(text) >= Date.parse('2000-01-01T00:00:00Z') ? text : undefined;
 };
 /** The tool vocabulary prompt classes and `files` are computed in; a Codex name with no counterpart keeps its own. */
-const SHELL_CALLS = new Set(['shell', 'shell_command', 'exec_command', 'local_shell', 'container.exec', 'write_stdin']);
+const SHELL_CALLS = new Set(['shell', 'shell_command', 'exec_command', 'local_shell', 'container.exec', 'write_stdin', 'exec', 'wait']);
 const PATCH_CALLS = new Set(['apply_patch']);
 /** The namespace upstream fills in for a top-level function (codex-rs/protocol/src/tool_name.rs:6-7); with none and an empty one, it is the plain tool (:46-50). */
 const DEFAULT_FUNCTION_NAMESPACE = 'functions';
+/** One word of an argv as a POSIX shell reads it back: left alone when it holds only safe characters, else in single quotes, so `bash -lc 'git revert HEAD'` keeps its script as one word. */
+const quotedWord = (word) => (/^[\w@%+=:,./-]+$/.test(word) ? word : `'${word.replaceAll("'", "'\\''")}'`);
 const commandOf = (args) => {
     const command = args.command ?? args.cmd;
     if (Array.isArray(command))
-        return command.filter((part) => typeof part === 'string').join(' ');
+        return command.filter((part) => typeof part === 'string').map(quotedWord).join(' ');
     return str(command);
 };
 /** The paths an `apply_patch` input touches (`*** Add|Update|Delete File: <path>`, the grammar of codex-rs/apply-patch). */
@@ -155,13 +161,21 @@ const patchFiles = (input) => [...input.matchAll(/^\*\*\* (?:Add|Update|Delete)
 const EXIT_LINE = /^(?:Exit code: |Process exited with code )(-?\d+)\s*$/m;
 const OUTPUT_MARK = /(?:^|\n)Output:\n?/;
 const RUNNING_LINE = /^Process running with session ID (\S+)\s*$/m;
+/**
+ * A code-mode cell's outcome is its output's first line (the live 0.166/0.167 store, 2026-11-06; upstream rust-v0.167.0 not yet read): `Script completed`, `Script failed` (a second part
+ * `Script error:\n<message>` follows), or `Script running with cell ID <id>`. It is the cell's outcome, never its commands': a completed cell can hold
+ * commands that exited nonzero, and those are CommandExecution items of their own.
+ */
+const SCRIPT_HEAD = /^Script (completed|failed|running with cell ID (\S+))[ \t]*(?:\n|$)/;
+const SCRIPT_ERROR = /(?:^|\n)Script error:\n?/;
 /**
  * The message of a call that failed before it produced an exit code, written as the whole output (no `Output:` header): `execution error: ` for a
  * shell call (core/src/tools/events.rs:438), and for the default unified-exec tool (ConfigShellToolType is only `UnifiedExec | Disabled`,
  * protocol/src/openai_models.rs:330-333) `exec_command failed: ` (core/src/tools/handlers/unified_exec/exec_command.rs:270), `write_stdin failed: `
- * (write_stdin.rs:123), and `write_stdin approval failed: ` (:121). `write_stdin rejected: ` (:118) stays unsettled: its reason is the approval policy's.
+ * (write_stdin.rs:123), and `write_stdin approval failed: ` (:121). `wait failed: ` is assumed by analogy with `write_stdin failed: ` (write_stdin.rs:123) and has not
+ * been seen in the live store. `write_stdin rejected: ` (:118) stays unsettled: its reason is the approval policy's.
  */
-const SPAWN_ERROR = /^(?:execution error|exec_command failed|write_stdin(?: approval)? failed): /;
+const SPAWN_ERROR = /^(?:execution error|exec_command failed|wait failed|write_stdin(?: approval)? failed): /;
 /**
  * A declined call is the user's refusal only where its message says so. Codex reports `ToolError::Rejected` as `declined` for a user's refusal and for some
  * runtime rejections, and normalizes only the literal text `rejected by user` (events.rs:448-458): `exec command rejected by user` for a shell call (:456) and
@@ -189,15 +203,26 @@ const bodyText = (raw) => {
  */
 const outcomeOf = (raw) => {
     const body = bodyText(raw);
+    const printed = OUTPUT_MARK.exec(body);
+    const script = SCRIPT_HEAD.exec(printed === null ? body : body.slice(0, printed.index));
+    if (script !== null) {
+        const error = SCRIPT_ERROR.exec(body);
+        const output = printed === null ? '' : body.slice(printed.index + printed[0].length, error === null || error.index < printed.index ? undefined : error.index);
+        if (script[1] === 'failed') {
+            const message = error === null ? output : body.slice(error.index + error[0].length);
+            return { text: message.trim() === '' ? 'Script failed' : message, exit: undefined, spawnError: true, running: undefined, script: true };
+        }
+        return { text: output, exit: script[2] === undefined ? 0 : undefined, spawnError: false, running: script[2], script: true };
+    }
     const wrapped = parse(body);
     if (isObj(wrapped) && typeof wrapped.output === 'string')
-        return { text: wrapped.output, exit: isObj(wrapped.metadata) ? num(wrapped.metadata.exit_code) : undefined, spawnError: false, running: undefined };
+        return { text: wrapped.output, exit: isObj(wrapped.metadata) ? num(wrapped.metadata.exit_code) : undefined, spawnError: false, running: undefined, script: false };
     const mark = OUTPUT_MARK.exec(body);
     if (mark === null)
-        return { text: body, exit: undefined, spawnError: SPAWN_ERROR.test(body), running: undefined };
+        return { text: body, exit: undefined, spawnError: SPAWN_ERROR.test(body), running: undefined, script: false };
     const head = body.slice(0, mark.index);
     const code = EXIT_LINE.exec(head)?.[1];
-    return { text: body.slice(mark.index + mark[0].length), exit: code === undefined ? undefined : Number(code), spawnError: false, running: RUNNING_LINE.exec(head)?.[1] };
+    return { text: body.slice(mark.index + mark[0].length), exit: code === undefined ? undefined : Number(code), spawnError: false, running: RUNNING_LINE.exec(head)?.[1], script: false };
 };
 /**
  * A failed call's error text. A negative code is no exit status: upstream writes -1 for a tool failure message (core/src/tools/events.rs:538-542) and for a
@@ -254,6 +279,8 @@ export const rolloutLines = (text, fallbackId, parentText) => {
     let open;
     let lastTotal;
     const calls = new Map();
+    // The tools the session declared as dynamic (`dynamic_tools`): their output carries no failure signal, only their DynamicToolCall item does.
+    const dynamicNames = new Set();
     // A unified-exec process still running, by its session id, to the exec_command that started it: in a Legacy rollout the `write_stdin` that sees it exit settles both.
     const running = new Map();
     // Records below this ordinal are the parent prefix a subagent's rollout copied (ordinal.rs:86-89), not the session's own. Only a Paginated rollout
@@ -267,7 +294,10 @@ export const rolloutLines = (text, fallbackId, parentText) => {
     // one has none), so the leading records equal to the parent's, in order, are its copied history, in either mode. Null once it stops matching.
     let copied = null;
     const resolved = new Set();
+    // The stamp before the record being read, so an item's start (its stamp less its duration) is never earlier than the line before it.
+    let before;
     const stamp = (value) => {
+        before = at;
         const candidate = iso(value);
         if (candidate !== undefined && (at === undefined || Date.parse(candidate) >= Date.parse(at)))
             at = candidate;
@@ -286,15 +316,15 @@ export const rolloutLines = (text, fallbackId, parentText) => {
     // path: a shell call's `[branch sha]` line is how a commit's sha is found. The output follows an `Exit code 0` line, the shape a Claude Code Bash
     // result has (fixtures/proj/errors-a.jsonl:15): capture marks a result whose text starts `Exit code <nonzero>` as failed (`isErrorResult` in extract.ts), and a
     // call that exited 0 may print such a line (`cat ci.log`). The commit patterns read every line (`COMMIT_LINE` and `HASH_LINE` in extract.ts, both `gm`), so the sha is still found.
-    const result = (id, failure, when, output = '') => {
+    const result = (id, failure, when, output = '', timed = false) => {
         sequence += 1;
         lines.push({
             ...base,
             type: 'user',
             uuid: `${fallbackId}-r${String(sequence)}`,
             timestamp: when,
-            // Codex stamps a result with its own time, but the call's start is not paired to it, so no duration is claimed.
-            noDuration: true,
+            // Codex stamps a result with its own time, but the call's start is not paired to it, so no duration is claimed; a CommandExecution item's own `duration` is the exception.
+            ...(timed ? {} : { noDuration: true }),
             message: { role: 'user', content: [{ type: 'tool_result', tool_use_id: id, is_error: failure !== undefined, content: failure ?? (output === '' ? '' : `Exit code 0\n${output}`) }] },
         });
     };
@@ -323,7 +353,8 @@ export const rolloutLines = (text, fallbackId, parentText) => {
     };
     // A shell call settles on its exit code, or on a failure to spawn, whether that comes from its own output or from a CommandExecution item. A
     // process still running was remembered by its session id, so in a Legacy rollout the `write_stdin` that polled it and read its exit
-    // code settles both calls (in a Paginated one an item settles only its own exec_command). A poll that failed instead (`write_stdin failed: ...`, `exited` false) says nothing about the process: a
+    // code settles both calls (in a Paginated one an item settles only its own exec_command; a `wait` on a code-mode cell settles the cell in either mode, because
+    // the cell's outcome is its own header and no item carries it). A poll that failed instead (`write_stdin failed: ...`, `exited` false) says nothing about the process: a
     // non-empty write to one with no tty is `StdinClosed` (unified_exec/process_manager.rs:1021-1026) and it runs on, so only the poll is the error.
     const settleShell = (id, failure, output, when, exited = true) => {
         const known = calls.get(id);
@@ -332,7 +363,7 @@ export const rolloutLines = (text, fallbackId, parentText) => {
         resolved.add(id);
         result(id, failure, when, output);
         const pending = known.session === undefined ? undefined : running.get(known.session);
-        if (exited && !paginated && pending !== undefined && !resolved.has(pending)) {
+        if (exited && (!paginated || known.cell === true) && pending !== undefined && !resolved.has(pending)) {
             resolved.add(pending);
             result(pending, failure, when, output);
         }
@@ -357,9 +388,35 @@ export const rolloutLines = (text, fallbackId, parentText) => {
         else if (kind === 'FileChange' && id !== undefined && (item.status === 'completed' || item.status === 'failed' || (item.status === 'declined' && DECLINED_PATCH_TEXT.test(str(item.stderr) ?? '')))) {
             settlePatch(id, item.status === 'declined' ? DECLINED_PATCH : item.status === 'failed' ? (str(item.stderr) ?? 'patch failed') : undefined, when);
         }
-        else if (kind === 'CommandExecution' && id !== undefined && item.status === 'declined' && DECLINED_OUTPUT.test(str(item.aggregated_output) ?? '')) {
+        else if (kind === 'CommandExecution' && id !== undefined && item.status === 'declined' && calls.has(id)) {
             // A `declined` one has exit code -1 (events.rs:552-554); only the user's refusal text settles it, as a refusal.
-            settleShell(id, DECLINED_SHELL, '', when);
+            if (DECLINED_OUTPUT.test(str(item.aggregated_output) ?? ''))
+                settleShell(id, DECLINED_SHELL, '', when);
+        }
+        else if (kind === 'CommandExecution' && id !== undefined && (item.status === 'completed' || item.status === 'failed' || item.status === 'declined') && !calls.has(id)) {
+            // A code-mode cell's `exec_command` (Codex 0.166+) is run by the cell's JavaScript, so no call carries the item's `exec-<uuid>` id: the item is the
+            // command's only record, and it is its own Bash call. Binding it to its cell by position would hold for 191 of 193 items in a live 0.167.0 store and fail
+            // for 2, so it is not attempted.
+            const exit = num(item.exit_code);
+            if (resolved.has(id))
+                return;
+            resolved.add(id);
+            const output = str(item.aggregated_output) ?? '';
+            const spent = isObj(item.duration) ? Math.round((num(item.duration.secs) ?? 0) * 1000 + (num(item.duration.nanos) ?? 0) / 1e6) : undefined;
+            const parsed = Array.isArray(item.parsed_cmd) && item.parsed_cmd.length === 1 && isObj(item.parsed_cmd[0]) ? str(item.parsed_cmd[0].cmd) : undefined;
+            const joined = commandOf(item);
+            // The command array is the launcher then its flags then the text (`pwsh.exe -Command <text>`); a single parsed command is that text alone.
+            const command = parsed !== undefined && (joined === undefined || parsed.length < joined.length) ? parsed : joined;
+            const began = spent === undefined ? when : new Date(Math.max(Date.parse(when) - spent, Date.parse(before ?? when))).toISOString();
+            assistant([{ type: 'tool_use', id, name: 'Bash', native: 'exec_command', input: command === undefined ? {} : { command } }], began);
+            // An item with no exit_code (an Option, skipped when None, items.rs:284-286) keeps its command and has no outcome, as an owned one does.
+            // A refused one (exit code -1) is the user's refusal only where its output says so; any other declined text leaves no outcome.
+            if (item.status === 'declined') {
+                if (DECLINED_OUTPUT.test(output))
+                    result(id, DECLINED_SHELL, when, '');
+            }
+            else if (exit !== undefined)
+                result(id, failureOf(exit, output), when, output, spent !== undefined);
         }
         else if (kind === 'CommandExecution' && id !== undefined && (item.status === 'completed' || item.status === 'failed')) {
             // The exec_command's own item: `id` is its call id, written when the process exits, even one the model never polled (header). It carries the
@@ -375,6 +432,12 @@ export const rolloutLines = (text, fallbackId, parentText) => {
             const text = isObj(item.error) ? (str(item.error.message) ?? '') : isObj(item.result) ? bodyText(item.result.content) : '';
             settleMcp(id, failed ? (text === '' ? 'mcp tool call failed' : text) : undefined, when);
         }
+        else if (kind === 'DynamicToolCall' && id !== undefined && (item.status === 'completed' || item.status === 'failed')) {
+            // The item's `success` and `error` (items.rs:301-322; dynamic.rs:246-262): a call with no item stays unsettled, since its output text says nothing of failure.
+            const failed = item.status === 'failed' || item.success === false;
+            const text = isObj(item.error) ? (str(item.error.message) ?? '') : '';
+            settleMcp(id, failed ? (text === '' ? 'dynamic tool call failed' : text) : undefined, when);
+        }
     };
     const parentKeys = (parent) => parent
         .split('\n')
@@ -415,6 +478,8 @@ export const rolloutLines = (text, fallbackId, parentText) => {
             const declared = toolNames(payload.dynamic_tools);
             if (declared.length > 0)
                 tools({ offered: declared });
+            for (const name of declared)
+                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))
@@ -443,10 +508,9 @@ export const rolloutLines = (text, fallbackId, parentText) => {
             }
             else if (kind === 'turn_aborted') {
                 // Only `interrupted` is the operator cutting a turn short: `replaced`, `review_ended`, and `budget_limited` are the harness's own (protocol.rs:4580-4585).
-                if (payload.reason === 'interrupted') {
-                    sequence += 1;
-                    lines.push({ ...base, type: SHAPE_INTERRUPT_LINE, uuid: `${fallbackId}-i${String(sequence)}` });
-                }
+                // It is written as the marker line Claude Code writes, so capture keeps it as a prompt record and the shape counts one interrupt (CAPTURE 23).
+                if (payload.reason === 'interrupted')
+                    prompted(`${INTERRUPT_MARKER}]`, when);
             }
             else if (kind === 'agent_message') {
                 const message = str(payload.message);
@@ -527,9 +591,11 @@ export const rolloutLines = (text, fallbackId, parentText) => {
                 if (id === undefined)
                     continue;
                 if (kind === 'local_shell_call' || (namespace === undefined && SHELL_CALLS.has(name))) {
-                    const command = commandOf(kind === 'local_shell_call' ? action : input);
-                    const polled = name === 'write_stdin' ? (str(input.session_id) ?? (num(input.session_id) === undefined ? undefined : String(num(input.session_id)))) : undefined;
-                    calls.set(id, { kind: 'shell', ids: [id], ...(polled === undefined ? {} : { session: polled }) });
+                    // A code-mode `exec` call's input is a JavaScript cell, not a command, so it has none.
+                    const command = name === 'exec' ? undefined : commandOf(kind === 'local_shell_call' ? action : input);
+                    const poll = name === 'wait' ? input.cell_id : input.session_id;
+                    const polled = name === 'write_stdin' || name === 'wait' ? (str(poll) ?? (num(poll) === undefined ? undefined : String(num(poll)))) : undefined;
+                    calls.set(id, { kind: 'shell', ids: [id], ...(polled === undefined ? {} : { session: name === 'wait' ? `cell:${polled}` : polled }), ...(name === 'exec' || name === 'wait' ? { cell: true } : {}) });
                     // `native` keeps Codex's own name for the action table (the contract at extract.ts, as cursor.ts does); a `local_shell_call` has no name field.
                     assistant([{ type: 'tool_use', id, name: 'Bash', native: kind === 'local_shell_call' ? 'local_shell' : name, input: command === undefined ? {} : { command } }], when);
                 }
@@ -540,7 +606,7 @@ export const rolloutLines = (text, fallbackId, parentText) => {
                     assistant(ids.map((part, index) => ({ type: 'tool_use', id: part, name: 'Edit', native: name, input: files[index] === undefined ? {} : { file_path: files[index] } })), when);
                 }
                 else {
-                    calls.set(id, { kind: 'other', ids: [id] });
+                    calls.set(id, { kind: 'other', ids: [id], ...(dynamicNames.has(name) ? { dynamic: true } : {}) });
                     const file = str(input.path) ?? str(input.file_path);
                     const query = str(input.query);
                     assistant([{ type: 'tool_use', id, name, input: { ...(file === undefined ? {} : { file_path: file }), ...(query === undefined ? {} : { query }) } }], when);
@@ -557,11 +623,11 @@ export const rolloutLines = (text, fallbackId, parentText) => {
                         if (out.exit === undefined && DECLINED_OUTPUT.test(out.text))
                             settleShell(id, DECLINED_SHELL, '', when, false);
                         else if (out.exit !== undefined || out.spawnError)
-                            settleShell(id, out.spawnError ? out.text : failureOf(out.exit, out.text), out.text, when, out.exit !== undefined);
+                            settleShell(id, out.spawnError ? out.text : failureOf(out.exit, out.text), out.text, when, out.exit !== undefined || out.script);
                         else if (out.running !== undefined && known.session === undefined)
-                            running.set(out.running, id);
+                            running.set(known.cell === true ? `cell:${out.running}` : out.running, id);
                     }
-                    else if (known.kind === 'other') {
+                    else if (known.kind === 'other' && known.dynamic !== true) {
                         // Another call's output carries no failure signal (an MCP call's comes from its mcp_tool_call_end), and a patch settles only from its
                         // patch_apply_end, because a rejected patch comes back as plain output text (tools/handlers/apply_patch.rs).
                         resolved.add(id);

package/dist/sessions/command.d.ts

@@ -1,5 +1,6 @@
 import type { Outcome } from '../cli.js';
 import { type BooksBy } from './query.js';
+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';
@@ -12,10 +13,13 @@ export interface SessionsDeps {
     sessions: SessionsRuntime | undefined;
     install: InstallRuntime | undefined;
     now: () => number;
+    /** Records a telemetry event; absent in a run that has none. */
+    telemetry?: Emit | undefined;
 }
 export declare const sessionsDeposit: (deps: SessionsDeps, options: {
     allow: string[];
     allowFiles: string[];
+    deny?: string[];
     redactDomains: string[];
 }) => Promise<Outcome>;
 /**
@@ -40,9 +44,10 @@ export declare const sessionsRead: (deps: SessionsDeps, options: {
 export declare const sessionsContext: (deps: SessionsDeps, options: ContextOptions) => Promise<Outcome>;
 export declare const sessionsMcp: (deps: SessionsDeps) => Promise<void>;
 export declare const sessionsBooks: (deps: SessionsDeps, options: {
-    by: BooksBy;
+    by: BooksBy | "package";
     sinceDays: number | undefined;
     repo?: string;
+    termsFile?: string;
 }) => Promise<Outcome>;
 export declare const sessionsMeasure: (deps: SessionsDeps, options: {
     last: number;
@@ -73,6 +78,11 @@ export interface VerifyReport {
     selfBaseline: SelfBaselineResult[];
     /** Batches in any server's outbox built under an older vocabulary, field list, or skeleton format: never printed, never sent, and removed by the next `pool deposit`. Counted from local folders; nothing is sent. */
     staleBatches: number;
+    /** The outboxes' sent and masked counts (`pool-totals.ts`). */
+    sentBatches: number;
+    sentRaw: number;
+    rawCopies: number;
+    rawMasked: number;
 }
 /** With `strict`, any violated invariant, stuck step, `merkle: root mismatch`, or `merkle: counts do not bind` also fails the command (exit 4) after the full report is printed; the report is built first so callers can emit it. */
 export declare const sessionsVerify: (deps: SessionsDeps, options: {

package/dist/sessions/command.js

@@ -1,7 +1,7 @@
 // The `oars sessions` command group's bodies: each returns the `--json` document and the text a human sees.
 import { mkdir, readFile, stat, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
-import { parseAllowList } from './allow.js';
+import { denialOf, parseAllowList, runAllow } from './allow.js';
 import { SOURCES, sourceLabel } from './sources.js';
 import { CliError, ExitCode } from '../errors.js';
 import { loadTerms } from './exclusion.js';
@@ -10,23 +10,30 @@ import { armsPath, coverageLines, formatScore, isGoldDocument, parseGold, plural
 import { 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';
 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 { readHookCalls } from './hook-calls.js';
 import { buildIndex, contextBlock, inRepository, readIndex } from './hook-index.js';
-import { hookStatus, installHooks, scheduleStatus, setSchedule, settingsPath, uninstallHooks } from './install.js';
+import { ensureSchedule, hookStatus, installHooks, recordSchedule, SCHEDULE_LEFT_OFF, scheduleOptedOut, scheduleStatus, setSchedule, settingsPath, uninstallHooks } from './install.js';
 import { serve } from './mcp.js';
 import { refreshPool, servedPool } from './pool.js';
+import { recallPool } from './recall-bundle.js';
+import { booksLines, lastFetchedBundle } from './pool-books.js';
+import { formatPackageBooks, packageBooks } from './package-books.js';
+import { scanStore } from './exclusion.js';
+import { vocabulary } from './vocab-load.js';
 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, readSkeletons, skippedFolders, slugOf } from './store.js';
+import { deposit, frozenSessions, loadStore, 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';
+import { outboxTotals } from './pool-totals.js';
 import { auditCounts, auditStore, formatAudit } from './audit.js';
 import { readSurvival, recordSurvival, SURVIVAL_DAYS } from './survival.js';
 import { CAPTURE_INVARIANTS, formatSessionResults, formatVerify, verifyAll, verifyCaptured, verifySessions } from './verify.js';
@@ -35,24 +42,31 @@ const runtimeOf = (deps) => {
         throw new CliError('The session store is not configured in this run.', ExitCode.UNEXPECTED, 'unexpected');
     return deps.sessions;
 };
+/** A list that names nothing is a mistake, not a request for the default (every folder): it is refused. */
 const readAllowFile = async (file) => {
+    let entries;
     try {
-        return parseAllowList(await readFile(file, 'utf8'));
+        entries = parseAllowList(await readFile(file, 'utf8'));
     }
     catch {
         throw new CliError(`Cannot read the --allow-file ${file}.`, ExitCode.USAGE, 'usage');
     }
+    if (entries.length === 0)
+        throw new CliError(`The --allow-file ${file} names no folder. Without --allow or --allow-file, deposit reads every folder.`, ExitCode.USAGE, 'usage');
+    return entries;
 };
 export const sessionsDeposit = async (deps, options) => {
     const fromFiles = await Promise.all(options.allowFiles.map((file) => readAllowFile(file)));
     const runtime = runtimeOf(deps);
     const table = runtime.sources ?? SOURCES;
-    const allow = [...options.allow, ...fromFiles.flat()];
-    const result = await runDeposit(newContext(runtime.storeDir, deps.now, 'manual'), true, inputKey('manual', allow, options.redactDomains), async (trace) => {
+    const allow = [...options.allow, ...fromFiles.flat(), ...(options.deny ?? []).map(denialOf)];
+    const { result, read } = await runDeposit(newContext(runtime.storeDir, deps.now, 'manual'), true, inputKey('manual', allow, options.redactDomains), async (trace) => {
+        // Survival reads the folders this deposit reads, from the list saved before the deposit merges this run's entries into it.
+        const scope = runAllow((await readSaved(runtime.storeDir)).allow, allow);
         const done = await deposit(runtime, { allow, redactDomains: options.redactDomains, now: deps.now }, trace);
-        return { value: done, in: { transcript: done.sessions + done.subagents + done.unchanged } };
+        return { value: { result: done, read: scope }, in: { transcript: done.sessions + done.subagents + done.unchanged } };
     });
-    const survival = await recordSurvival(runtime, allow, deps.now);
+    const survival = await recordSurvival(runtime, read, deps.now);
     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.`,
@@ -85,10 +99,12 @@ export const sessionsRecall = async (deps, query, sid = null) => {
     const key = stampKey(JSON.stringify(query));
     const result = 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 servedPool(storeDir, store) });
+        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 } };
     }, 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));
     if (result.legacy !== undefined)
         return { document: { ok: true, ...result.legacy, recall: result.recall }, text: 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.
@@ -141,7 +157,7 @@ export const sessionsContext = async (deps, options) => {
     return { document: { ok: true, context: block ?? null }, text: block ?? 'Nothing recurs in this repository yet.' };
 };
 export const sessionsMcp = async (deps) => {
-    await serve(runtimeOf(deps), deps.now);
+    await serve(runtimeOf(deps), deps.now, deps.telemetry);
 };
 /** Names shown in the `verify` and `books` text; each `--json` document carries them all. */
 const SKIPPED_NAMES_SHOWN = 10;
@@ -180,7 +196,23 @@ const inRepositoryStore = (store, repo) => {
         newerCaptures: [...sessions, ...subagents].filter((record) => newer(record.cv)).length,
     };
 };
+/**
+ * `books --by package`: the store's tool calls per public package, after the A38 scan `oars sessions exclusions` runs (a missing term file excludes everything).
+ * The scan reads the transcripts and writes nothing; the store is only read.
+ */
+const packageBooksOutcome = async (deps, options) => {
+    const runtime = runtimeOf(deps);
+    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') };
+};
 export const sessionsBooks = async (deps, options) => {
+    if (options.by === 'package') {
+        if (options.repo !== undefined)
+            throw new CliError('--repo does not apply to --by package: its rows are public package names across the whole store.', ExitCode.USAGE, 'usage');
+        return packageBooksOutcome(deps, { sinceDays: options.sinceDays, termsFile: options.termsFile ?? '' });
+    }
     const runtime = runtimeOf(deps);
     const { storeDir } = runtime;
     const loaded = await loadStore(storeDir);
@@ -194,7 +226,8 @@ export const sessionsBooks = async (deps, options) => {
             ? `No ${options.by === 'pull' ? 'pulls' : 'prompts'} in the --since window.`
             : formatBooks(rows, options.by);
     const scope = await scopeOf(runtime);
-    return { document: { ok: true, by: options.by, rows, newerCaptures: store.newerCaptures, scope }, text: [table, ...skippedNotice(scope), ...newerNotice(store), ...(rows.length === 0 ? [] : [BOOKS_CAVEAT])].join('\n') };
+    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') };
 };
 export const sessionsMeasure = async (deps, options) => {
     const runtime = runtimeOf(deps);
@@ -240,7 +273,8 @@ export const sessionsVerify = async (deps, options) => {
         const scope = await scopeOf(runtime);
         // 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 report = { sessions: skeletons.length, unreadable, cvFrozen: frozen.size, scope, invariants: results.map((result) => ({ ...result, pass: result.violations === 0 })), stuck, sessionResults, audit, selfBaseline, staleBatches };
+        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 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();
@@ -249,7 +283,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`] : []), ...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`] : []), ...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).
@@ -339,19 +373,31 @@ const installOf = (deps) => {
         throw new CliError('Hook install is not configured in this run.', ExitCode.UNEXPECTED, 'unexpected');
     return deps.install;
 };
+/** `--scope`, else `file` when `--file` names one, else the user settings. */
+const hookScope = (options) => options.scope ?? (options.file === undefined ? 'user' : 'file');
 export const sessionsHookInstall = async (deps, options) => {
     const runtime = installOf(deps);
     const lines = [];
     const document = { ok: true };
-    // `--schedule` alone touches no settings file: nothing is written to one the operator has not named.
+    // `--schedule` alone touches no settings file: it names the task, not the hooks.
     if (options.schedule === undefined || options.scope !== undefined || options.file !== undefined) {
-        const file = settingsPath(runtime, options.scope ?? 'file', options.file);
+        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);
     }
-    if (options.schedule !== undefined) {
-        const line = await setSchedule(runtime, options.schedule);
+    // 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 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);
+            await recordSchedule(storeDir, options.schedule);
+        }
+        else if (!optedOut) {
+            line = await ensureSchedule(runtime);
+        }
         document.schedule = line;
         lines.push(line);
     }
@@ -359,7 +405,7 @@ export const sessionsHookInstall = async (deps, options) => {
 };
 export const sessionsHookUninstall = async (deps, options) => {
     const runtime = installOf(deps);
-    const file = settingsPath(runtime, options.scope ?? 'file', options.file);
+    const file = settingsPath(runtime, hookScope(options), options.file);
     const result = await uninstallHooks(file);
     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 };

package/dist/sessions/coverage.d.ts

@@ -0,0 +1,19 @@
+import { type Coverage, type OrgSize, type RepoVisibility, type Team } from './pool-wire.js';
+import type { SessionObservation } from './schema.js';
+import { type SessionsRuntime } from './store.js';
+import { type Git } from './survival.js';
+/** The two bands only the operator can state. */
+export interface CoverageSetting {
+    orgSize: OrgSize;
+    repoVisibility: RepoVisibility;
+}
+export declare const coverageFile: (storeDir: string) => string;
+/** The saved setting. A missing, damaged, or out-of-list file reads as `unknown`, which states nothing. */
+export declare const readCoverageSetting: (storeDir: string) => Promise<CoverageSetting>;
+export declare const writeCoverageSetting: (storeDir: string, setting: CoverageSetting) => Promise<void>;
+/** The band for a count of distinct authors: one is `solo`, more is `team`, and none or an unread log is `unknown`. */
+export declare const teamOf: (authors: number | null) => Team;
+/** How many distinct commit authors the repository's local log shows (the author address, mailmap applied); null when git cannot read it or it holds no commit. Only the count leaves. */
+export declare const authorsIn: (git: Git, root: string) => Promise<number | null>;
+/** The coverage of a session, for one deposit pass: each repository's log is read once. */
+export declare const makeCoverage: (runtime: Pick<SessionsRuntime, "projectsRoot" | "storeDir">, setting: CoverageSetting, git: Git) => ((main: SessionObservation) => Promise<Coverage>);

package/dist/sessions/coverage.js

@@ -0,0 +1,56 @@
+// What a deposit says about whom it covers (t871). Two of the bands are the operator's word, kept in one file on this machine and never looked up; the third, `team`, is a count of the distinct commit
+// authors in the local git log of the repository the session sat in. The count is made here and dropped: the log is read, the authors are counted, and no name or address leaves this function. No call goes
+// over a network, and anything that cannot be read goes as `unknown`.
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { makeRepoRoot } from './repo-root.js';
+import { NO_COVERAGE, ORG_SIZES, REPO_VISIBILITIES } from './pool-wire.js';
+import { writeAtomic } from './store.js';
+import { cwdOfProject } from './survival.js';
+/** A history this long is read at most, so a very large repository costs a bounded read; the band needs to tell one author from several, not to count them all. */
+const LOG_COMMITS_MAX = 5000;
+export const coverageFile = (storeDir) => join(storeDir, 'pool-coverage.json');
+const held = (list, value, otherwise) => list.find((entry) => entry === value) ?? otherwise;
+/** The saved setting. A missing, damaged, or out-of-list file reads as `unknown`, which states nothing. */
+export const readCoverageSetting = async (storeDir) => {
+    const unset = { orgSize: NO_COVERAGE.orgSize, repoVisibility: NO_COVERAGE.repoVisibility };
+    try {
+        const parsed = JSON.parse(await readFile(coverageFile(storeDir), 'utf8'));
+        if (typeof parsed !== 'object' || parsed === null)
+            return unset;
+        return { orgSize: held(ORG_SIZES, Reflect.get(parsed, 'orgSize'), unset.orgSize), repoVisibility: held(REPO_VISIBILITIES, Reflect.get(parsed, 'repoVisibility'), unset.repoVisibility) };
+    }
+    catch {
+        return unset;
+    }
+};
+export const writeCoverageSetting = (storeDir, setting) => writeAtomic(coverageFile(storeDir), `${JSON.stringify(setting)}\n`);
+/** The band for a count of distinct authors: one is `solo`, more is `team`, and none or an unread log is `unknown`. */
+export const teamOf = (authors) => (authors === null || authors === 0 ? 'unknown' : authors === 1 ? 'solo' : 'team');
+/** How many distinct commit authors the repository's local log shows (the author address, mailmap applied); null when git cannot read it or it holds no commit. Only the count leaves. */
+export const authorsIn = async (git, root) => {
+    try {
+        const lines = (await git(root, ['log', '--format=%aE', `--max-count=${String(LOG_COMMITS_MAX)}`])).split(/\r?\n/).filter((line) => line !== '');
+        return lines.length === 0 ? null : new Set(lines.map((line) => line.toLowerCase())).size;
+    }
+    catch {
+        return null;
+    }
+};
+/** The coverage of a session, for one deposit pass: each repository's log is read once. */
+export const makeCoverage = (runtime, setting, git) => {
+    const rootOf = makeRepoRoot();
+    const teams = new Map();
+    return async ({ project, session }) => {
+        const cwd = await cwdOfProject(runtime, project, new Set([session]));
+        const root = cwd === undefined ? null : rootOf(cwd);
+        if (root === null)
+            return { ...setting, team: 'unknown' };
+        const known = teams.get(root);
+        if (known !== undefined)
+            return { ...setting, team: known };
+        const team = teamOf(await authorsIn(git, root));
+        teams.set(root, team);
+        return { ...setting, team };
+    };
+};

package/dist/sessions/cursor.js

@@ -217,9 +217,9 @@ const linesOf = (bubble, base, at, model) => {
     const input = num(tokens.inputTokens) ?? 0;
     const output = num(tokens.outputTokens) ?? 0;
     const message = { role: 'assistant', id: bubble.id, content };
-    // A zero count means Cursor did not record one, so no usage is written rather than a measured zero.
+    // A zero count means Cursor did not record one, so that category is left out rather than written as a measured zero (and with neither, no usage is written).
     if (input > 0 || output > 0)
-        message.usage = { input_tokens: input, output_tokens: output };
+        message.usage = { ...(input > 0 ? { input_tokens: input } : {}), ...(output > 0 ? { output_tokens: output } : {}) };
     const lines = [{ ...base, type: 'assistant', uuid: bubble.id, requestId: bubble.id, timestamp: at, ...(model === undefined ? {} : { requestedModel: model }), message }];
     if (call !== undefined && name !== undefined && (call.userDecision === 'rejected' || ((call.status === 'error' || call.status === 'completed') && !aborted(call, name)))) {
         const failure = failureOf(call, name);