@manyoars/oars 0.2.0 → 0.4.0

package/dist/sessions/actions.js

@@ -0,0 +1,429 @@
+// The canonical action of a tool call (recall spec Section 2.2). Every harness names its tools differently, so one table per adapter
+// maps its native names onto one closed list, and a step reads alike in any harness. A new adapter adds a table here and changes nothing in the
+// extractor. A native name no table lists becomes `other`, and its name stays out of class P (`LITERAL`): the tool record keeps it, class A.
+import { LITERAL } from './public-vocabulary.js';
+export const CANONICAL_ACTIONS = [
+    'file.read',
+    'file.edit',
+    'file.write',
+    'file.search',
+    'shell.exec',
+    'web.search',
+    'web.fetch',
+    'mcp.call',
+    'skill.run',
+    'agent.spawn',
+    'plan.update',
+    'ask.user',
+    'recall.pull',
+    'recall.push',
+    'other',
+];
+export const ACTION_TABLES = {
+    'claude-code': {
+        rows: {
+            Read: 'file.read',
+            Edit: 'file.edit',
+            MultiEdit: 'file.edit',
+            NotebookEdit: 'file.edit',
+            Write: 'file.write',
+            Grep: 'file.search',
+            Glob: 'file.search',
+            LSP: 'file.search',
+            Bash: 'shell.exec',
+            PowerShell: 'shell.exec',
+            WebSearch: 'web.search',
+            WebFetch: 'web.fetch',
+            Skill: 'skill.run',
+            Agent: 'agent.spawn',
+            Task: 'agent.spawn',
+            TodoWrite: 'plan.update',
+            TaskCreate: 'plan.update',
+            TaskUpdate: 'plan.update',
+            TaskList: 'plan.update',
+            TaskGet: 'plan.update',
+            EnterPlanMode: 'plan.update',
+            ExitPlanMode: 'plan.update',
+            AskUserQuestion: 'ask.user',
+            mcp__oars__oars_recall: 'recall.pull',
+            'mcp__oars-sessions__oars_recall': 'recall.pull',
+            StructuredOutput: 'other',
+            ToolSearch: 'other',
+            SendMessage: 'other',
+            ListAgents: 'other',
+            Monitor: 'other',
+            TaskStop: 'other',
+            TaskOutput: 'other',
+            BashOutput: 'other',
+            KillShell: 'other',
+            ScheduleWakeup: 'other',
+            Workflow: 'other',
+            EnterWorktree: 'other',
+            ExitWorktree: 'other',
+        },
+        mcp: /^mcp__(?<server>.+?)__(?<tool>.+)$/,
+        toolDelimited: true,
+        shells: { Bash: 'bash', PowerShell: 'powershell' },
+    },
+    cursor: {
+        rows: {
+            read_file: 'file.read',
+            read_file_v2: 'file.read',
+            edit_file: 'file.edit',
+            edit_file_v2: 'file.edit',
+            search_replace: 'file.edit',
+            reapply: 'file.edit',
+            write: 'file.write',
+            grep_search: 'file.search',
+            grep: 'file.search',
+            codebase_search: 'file.search',
+            file_search: 'file.search',
+            glob_file_search: 'file.search',
+            list_dir: 'file.search',
+            list_dir_v2: 'file.search',
+            run_terminal_cmd: 'shell.exec',
+            web_search: 'web.search',
+            web_fetch: 'web.fetch',
+            mcp_oars_oars_recall: 'recall.pull',
+            todo_write: 'plan.update',
+            create_plan: 'plan.update',
+            ask_question: 'ask.user',
+            task_v2: 'agent.spawn',
+            delete_file: 'other',
+            read_lints: 'other',
+        },
+        mcp: /^mcp_(?<server>[^_]+)_(?<tool>.+)$/,
+        toolDelimited: false,
+        shells: {},
+    },
+    // Codex's own names: its adapter names a shell and a patch call in the Claude Code vocabulary for the extractor and keeps the Codex name in `native`.
+    // `write_stdin` feeds a running process (it runs no command), so it is `other`, as Claude Code's `BashOutput` is; `web_search` is the adapter's name for a
+    // persisted `web_search_call`.
+    codex: {
+        rows: {
+            shell: 'shell.exec',
+            shell_command: 'shell.exec',
+            exec_command: 'shell.exec',
+            local_shell: 'shell.exec',
+            'container.exec': 'shell.exec',
+            write_stdin: 'other',
+            apply_patch: 'file.edit',
+            read_file: 'file.read',
+            web_search: 'web.search',
+            update_plan: 'plan.update',
+        },
+        mcp: /^mcp__(?<server>.+?)__(?<tool>.+)$/,
+        toolDelimited: true,
+        shells: {},
+    },
+    // Copilot CLI's names are not listed by its event schema; these are the ones the SDK's own hook docs use (docs/hooks/*.md). A shell call and an edit are
+    // also found by shape (`shellToolInfo`, `shellExecution`, `fileEdits`) or by name and arrive in the transcript as `Bash` and `Edit` with the original name
+    // in `native`, which is what this table looks up; so a name this table lacks still reads as a shell call or an edit in the tool log, but its step is `other`.
+    copilot: {
+        rows: {
+            shell: 'shell.exec',
+            bash: 'shell.exec',
+            powershell: 'shell.exec',
+            local_shell: 'shell.exec',
+            read_file: 'file.read',
+            view: 'file.read',
+            glob: 'file.search',
+            grep: 'file.search',
+            edit: 'file.edit',
+            str_replace_editor: 'file.edit',
+            apply_patch: 'file.edit',
+            write_file: 'file.write',
+            delete_file: 'other',
+            task: 'agent.spawn',
+            web_fetch: 'web.fetch',
+        },
+        mcp: /^mcp__(?<server>.+?)__(?<tool>.+)$/,
+        toolDelimited: true,
+        shells: { bash: 'bash', powershell: 'powershell' },
+    },
+    // VS Code Copilot Chat's tools (microsoft/vscode @ f92b8f3, extensions/copilot/src/extension/tools/common/toolNames.ts): a tool call's `toolId` is the bare name or the
+    // contributed `copilot_` one, so both spellings are rows. The adapter names a terminal call `Bash`, an edit `Edit`, and a file creation `Write`, and keeps the toolId in `native`.
+    'vscode-copilot': {
+        rows: {
+            run_in_terminal: 'shell.exec',
+            create_and_run_task: 'shell.exec',
+            run_task: 'shell.exec',
+            read_file: 'file.read',
+            copilot_readFile: 'file.read',
+            list_dir: 'file.search',
+            copilot_listDirectory: 'file.search',
+            file_search: 'file.search',
+            copilot_findFiles: 'file.search',
+            grep_search: 'file.search',
+            copilot_findTextInFiles: 'file.search',
+            semantic_search: 'file.search',
+            copilot_searchCodebase: 'file.search',
+            search_workspace_symbols: 'file.search',
+            copilot_searchWorkspaceSymbols: 'file.search',
+            test_search: 'file.search',
+            copilot_findTestFiles: 'file.search',
+            apply_patch: 'file.edit',
+            copilot_applyPatch: 'file.edit',
+            replace_string_in_file: 'file.edit',
+            copilot_replaceString: 'file.edit',
+            multi_replace_string_in_file: 'file.edit',
+            copilot_multiReplaceString: 'file.edit',
+            insert_edit_into_file: 'file.edit',
+            copilot_insertEdit: 'file.edit',
+            create_file: 'file.write',
+            copilot_createFile: 'file.write',
+            runSubagent: 'agent.spawn',
+            search_subagent: 'agent.spawn',
+            explore_subagent: 'agent.spawn',
+            execution_subagent: 'agent.spawn',
+            fetch_webpage: 'web.fetch',
+            copilot_fetchWebPage: 'web.fetch',
+            manage_todo_list: 'plan.update',
+            // The rest of toolNames.ts, so no public name reads as an unlisted one with its name withheld. Notebook edits are edits, a directory or a new notebook is a write,
+            // the tools that drive a terminal or a kernel feed a running process and run no command of their own (as `write_stdin` is `other`), and a skill is a skill.
+            edit_notebook_file: 'file.edit',
+            copilot_editNotebook: 'file.edit',
+            create_new_jupyter_notebook: 'file.write',
+            copilot_createNewJupyterNotebook: 'file.write',
+            create_directory: 'file.write',
+            copilot_createDirectory: 'file.write',
+            read_notebook_cell_output: 'file.read',
+            copilot_readNotebookCellOutput: 'file.read',
+            copilot_getNotebookSummary: 'file.read',
+            view_image: 'file.read',
+            copilot_viewImage: 'file.read',
+            read_project_structure: 'file.search',
+            copilot_readProjectStructure: 'file.search',
+            skill: 'skill.run',
+            send_to_terminal: 'other',
+            get_terminal_output: 'other',
+            kill_terminal: 'other',
+            terminal_selection: 'other',
+            terminal_last_command: 'other',
+            get_task_output: 'other',
+            run_notebook_cell: 'other',
+            copilot_runNotebookCell: 'other',
+            runTests: 'other',
+            testFailure: 'other',
+            edit_files: 'other',
+            copilot_editFiles: 'other',
+            get_vscode_api: 'other',
+            copilot_getVSCodeAPI: 'other',
+            get_errors: 'other',
+            copilot_getErrors: 'other',
+            get_changed_files: 'other',
+            copilot_getChangedFiles: 'other',
+            memory: 'other',
+            copilot_memory: 'other',
+            resolve_memory_file_uri: 'other',
+            copilot_resolveMemoryFileUri: 'other',
+            github_repo: 'other',
+            copilot_githubRepo: 'other',
+            github_text_search: 'other',
+            copilot_githubTextSearch: 'other',
+            session_store_sql: 'other',
+            copilot_sessionStoreSql: 'other',
+            switch_agent: 'other',
+            copilot_switchAgent: 'other',
+            tool_search: 'other',
+            vscode_get_confirmation: 'other',
+            vscode_get_confirmation_with_options: 'other',
+            vscode_reviewPlan: 'other',
+            vscode_get_terminal_confirmation: 'other',
+            vscode_askQuestions: 'ask.user',
+            open_browser_page: 'other',
+            click_element: 'other',
+            screenshot_page: 'other',
+            navigate_page: 'other',
+            read_page: 'other',
+            hover_element: 'other',
+            drag_element: 'other',
+            type_in_page: 'other',
+            handle_dialog: 'other',
+            run_playwright_code: 'other',
+        },
+        // No pattern: VS Code's spelling of an MCP tool id has not been seen in a real file, so an MCP call reads as `other` with its name withheld until the hand run shows it.
+        mcp: null,
+        toolDelimited: false,
+        shells: {},
+    },
+    // Gemini CLI's tool names (google-gemini/gemini-cli @ 89e9d25d, packages/core/src/tools/tool-names.ts). Its adapter names the shell, edit, read, and search
+    // calls in the Claude Code vocabulary for the extractor and keeps the Gemini name in `native`, which is what this table looks up. An MCP tool is
+    // `mcp_<server>_<tool>`, a spelling that does not mark where the server name ends, so its tool stays out of class P.
+    gemini: {
+        rows: {
+            read_file: 'file.read',
+            read_many_files: 'file.read',
+            glob: 'file.search',
+            grep_search: 'file.search',
+            search_file_content: 'file.search',
+            list_directory: 'file.search',
+            replace: 'file.edit',
+            write_file: 'file.write',
+            run_shell_command: 'shell.exec',
+            PowerShell: 'shell.exec',
+            google_web_search: 'web.search',
+            web_fetch: 'web.fetch',
+            activate_skill: 'skill.run',
+            invoke_agent: 'agent.spawn',
+            write_todos: 'plan.update',
+            enter_plan_mode: 'plan.update',
+            exit_plan_mode: 'plan.update',
+            tracker_create_task: 'plan.update',
+            tracker_update_task: 'plan.update',
+            tracker_get_task: 'plan.update',
+            tracker_list_tasks: 'plan.update',
+            tracker_add_dependency: 'plan.update',
+            tracker_visualize: 'plan.update',
+            ask_user: 'ask.user',
+            mcp_oars_oars_recall: 'recall.pull',
+            'mcp_oars-sessions_oars_recall': 'recall.pull',
+            get_internal_docs: 'other',
+            update_topic: 'other',
+            complete_task: 'other',
+            read_mcp_resource: 'other',
+            list_mcp_resources: 'other',
+        },
+        mcp: /^mcp_(?<server>[^_]+)_(?<tool>.+)$/,
+        toolDelimited: false,
+        shells: { run_shell_command: 'bash', PowerShell: 'powershell' },
+    },
+    // Grok Build's own names (xai-org/grok-build @ 2bdd1d6, crates/codegen/xai-grok-tools): a tool's `title` is its name. A shell call and an edit reach the
+    // transcript as `Bash` and `Edit` with the original name in `native`, which is what this table looks up. A name the table lacks keeps its own and its step
+    // is `other`. An MCP call is `<server>__<tool>` in Grok Build; the reader spells it `mcp__<server>__<tool>`.
+    grok: {
+        rows: {
+            run_terminal_cmd: 'shell.exec',
+            run_terminal_command: 'shell.exec',
+            bash: 'shell.exec',
+            search_replace: 'file.edit',
+            apply_patch: 'file.edit',
+            edit: 'file.edit',
+            hashline_edit: 'file.edit',
+            write: 'file.write',
+            read_file: 'file.read',
+            read: 'file.read',
+            hashline_read: 'file.read',
+            list_dir: 'file.search',
+            grep: 'file.search',
+            grep_files: 'file.search',
+            glob: 'file.search',
+            hashline_grep: 'file.search',
+            web_search: 'web.search',
+            // The backend-hosted X search, named from its `variant` by the grok reader (acp_session_impl/tool_dispatch.rs:94-105).
+            x_search: 'web.search',
+            web_fetch: 'web.fetch',
+            ask_user_question: 'ask.user',
+            enter_plan_mode: 'plan.update',
+            exit_plan_mode: 'plan.update',
+            task: 'agent.spawn',
+            // The spawn tool also arrives under these wire names (grok_build/task/mod.rs:193-196).
+            Task: 'agent.spawn',
+            spawn_subagent: 'agent.spawn',
+            todo_write: 'plan.update',
+            todowrite: 'plan.update',
+            skill: 'skill.run',
+        },
+        mcp: /^mcp__(?<server>.+?)__(?<tool>.+)$/,
+        toolDelimited: true,
+        shells: { bash: 'bash', run_terminal_cmd: 'bash', run_terminal_command: 'bash' },
+    },
+    // OpenCode's own names (sst/opencode @ 21bf6b4, packages/core/src/tool/plugin/*.ts, each file's `export const name`): a tool part's `name`. The reader keeps that name in
+    // `native`, which is what this table looks up, and writes `Bash`, `Edit`, `Write`, `Read`, `Grep`, and `Glob` for the extractor. An MCP tool is `<server>_<tool>`
+    // (tool/runtime.ts:290-293), the same spelling as a built-in's, so it cannot be told apart and reads as an unknown tool with its name withheld.
+    opencode: {
+        rows: {
+            shell: 'shell.exec',
+            edit: 'file.edit',
+            patch: 'file.edit',
+            write: 'file.write',
+            read: 'file.read',
+            grep: 'file.search',
+            glob: 'file.search',
+            websearch: 'web.search',
+            webfetch: 'web.fetch',
+            question: 'ask.user',
+            subagent: 'agent.spawn',
+            skill: 'skill.run',
+            todowrite: 'plan.update',
+            // Known public names with no canonical action.
+            experimental_image_generate: 'other',
+            artifact_create: 'other',
+            artifact_read: 'other',
+            artifact_update: 'other',
+            artifact_delete: 'other',
+            schedule_create: 'other',
+            schedule_list: 'other',
+            schedule_pause: 'other',
+            schedule_resume: 'other',
+            schedule_delete: 'other',
+        },
+        mcp: null,
+        toolDelimited: false,
+        shells: { shell: 'bash' },
+    },
+    // Pi's own names (badlogic/pi-mono @ 085c84e, packages/coding-agent, docs/cli.md:144-158): `read`, `bash`, `powershell` (Windows), `edit`, `write`, `grep`, `find`, `ls`,
+    // `codemode`, and `tool_search`. A shell call and an edit reach the transcript as `Bash` and `Edit` with the original name in `native`, which is what this table looks up.
+    // Pi registers an MCP tool as `mcp__<server>__<tool>` (docs/mcp.md:77). It has no sub-agent, skill, plan, or ask tool of its own (README.md:19).
+    pi: {
+        rows: {
+            read: 'file.read',
+            bash: 'shell.exec',
+            powershell: 'shell.exec',
+            edit: 'file.edit',
+            write: 'file.write',
+            grep: 'file.search',
+            find: 'file.search',
+            ls: 'file.search',
+            codemode: 'other',
+            tool_search: 'other',
+        },
+        mcp: /^mcp__(?<server>.+?)__(?<tool>.+)$/,
+        toolDelimited: true,
+        shells: { bash: 'bash', powershell: 'powershell' },
+    },
+    // OpenTelemetry GenAI traces (open-telemetry/semantic-conventions-genai @ e6658f1, docs/gen-ai/execute-tool.md): `gen_ai.tool.name` is whatever the instrumented agent calls its
+    // tool, so no name is guaranteed. These are the names the conventions use in their own examples and refinements (the command, skill, and agent-as-tool sections); a span the
+    // reader recognizes by attributes alone (a nonzero `process.exit.code`, a `gen_ai.skill.name`) is renamed before this table is read. An MCP call is spelled `mcp__<server>__<tool>`.
+    otel: {
+        rows: {
+            exec_command: 'shell.exec',
+            execute: 'shell.exec',
+            shell: 'shell.exec',
+            bash: 'shell.exec',
+            command: 'shell.exec',
+            run_skill_script: 'shell.exec',
+            load_skill: 'skill.run',
+            skills: 'skill.run',
+            get_skill_instructions: 'skill.run',
+            load_skill_resource: 'file.read',
+            read_skill_resource: 'file.read',
+            get_skill_reference: 'file.read',
+            transfer_to_agent: 'agent.spawn',
+            invoke_agent: 'agent.spawn',
+        },
+        mcp: /^mcp__(?<server>.+?)__(?<tool>.+)$/,
+        toolDelimited: true,
+        shells: { bash: 'bash', shell: 'bash', exec_command: 'bash' },
+    },
+};
+/** The MCP call a native name spells, in full, as the transcript wrote it; undefined for any other name. */
+export const mcpOf = (table, native) => {
+    const groups = table.mcp?.exec(native)?.groups;
+    const server = groups?.server;
+    const tool = groups?.tool;
+    return server === undefined || tool === undefined ? undefined : { server, tool };
+};
+/**
+ * What a native name becomes on a step. Rows win over the MCP pattern, so a harness can name a recall that travels over MCP. `native` is the
+ * name itself only when a row lists it; an MCP name holds a server name, so `callIdentity` decides whether it is shown.
+ */
+export const actionOf = (table, native) => {
+    // `hasOwn`: a tool named `constructor` must not read the object's prototype.
+    const listed = Object.hasOwn(table.rows, native) ? table.rows[native] : undefined;
+    if (listed !== undefined)
+        return { action: listed, native };
+    return { action: mcpOf(table, native) === undefined ? 'other' : 'mcp.call', native: LITERAL };
+};
+/** The shell a native tool runs, or null when the table does not say. */
+export const shellOf = (table, native) => (Object.hasOwn(table.shells, native) ? (table.shells[native] ?? null) : null);

package/dist/sessions/allow.d.ts

@@ -0,0 +1,23 @@
+/** A leading `~` is the home folder, expanded here because a quoted entry or one read from a list file reaches us unexpanded by any shell. */
+export declare const expandHome: (entry: string) => string;
+/** Claude Code names a project folder after its working directory with every non-alphanumeric character as `-`. */
+export declare const slugOf: (folder: string) => string;
+export interface Allow {
+    /** Whether a project folder name is on the allowlist. */
+    allows: (name: string) => boolean;
+    /** The entries that matched none of `names`. */
+    unmatched: (names: readonly string[]) => string[];
+}
+/** The prefix `--deny` saves an entry under. */
+export declare const DENY = "!";
+export declare const denialOf: (entry: string) => string;
+export declare const compileAllow: (entries: readonly string[]) => Allow;
+/**
+ * The list a deposit saves: the saved entries and the given ones, where naming a folder again with `--allow` lifts the denial of exactly
+ * that entry. A denial is kept until then, so a later `--allow` of a wider prefix cannot read a denied folder.
+ */
+export declare const mergeAllow: (saved: readonly string[], given: readonly string[]) => string[];
+/** What one deposit reads: the folders it names, else the saved list (empty is every folder), less every denial saved or given. */
+export declare const runAllow: (saved: readonly string[], given: readonly string[]) => string[];
+/** One entry per line; blank lines and lines starting with `#` are skipped. */
+export declare const parseAllowList: (text: string) => string[];

package/dist/sessions/allow.js

@@ -0,0 +1,71 @@
+// What `--allow` accepts. An entry names project folders by one of:
+//   a folder or slug       `~/work/app` or `-home-me-work-app`: that one project folder
+//   a folder prefix        `~/work/` (trailing slash): that folder and everything under it
+//   a glob                 `*-work-*`, `C:\work\app-*`: `*` any run of characters, `?` one character
+// A path is matched through its slug, because Claude Code names a project folder after its working directory with every
+// non-alphanumeric character as `-`. An entry that starts with `!` (what `--deny` saves) keeps the folders it names out, whatever
+// else names them. With no entry that is not a denial, every folder is on the list: the default is every folder.
+import { homedir } from 'node:os';
+import { resolve } from 'node:path';
+/** A leading `~` is the home folder, expanded here because a quoted entry or one read from a list file reaches us unexpanded by any shell. */
+export const expandHome = (entry) => (/^~(?:[\\/]|$)/.test(entry) ? homedir() + entry.slice(1) : entry);
+/** Claude Code names a project folder after its working directory with every non-alphanumeric character as `-`. */
+export const slugOf = (folder) => resolve(expandHome(folder)).replace(/[^A-Za-z0-9]/g, '-');
+const GLOB = /[*?]/;
+/** A glob over a path or slug, as an anchored expression over slugs: separators become `-`, wildcards stay wildcards. */
+const globPattern = (entry) => {
+    // Every character that is neither alphanumeric nor a wildcard becomes the slug's `-`; then the wildcards become expressions.
+    const body = entry.replace(/[^A-Za-z0-9*?]/g, '-').replace(/\*/g, '.*').replace(/\?/g, '.');
+    return new RegExp(`^${body}$`);
+};
+/** The test a project folder name must pass for one entry. */
+const matcherOf = (entry) => {
+    if (GLOB.test(entry)) {
+        const pattern = globPattern(entry);
+        return (name) => pattern.test(name);
+    }
+    if (/[\\/]$/.test(entry)) {
+        const prefix = slugOf(entry);
+        // `resolve` drops the trailing separator, so the prefix is the folder itself; a project under it extends the slug with `-`.
+        return (name) => name === prefix || name.startsWith(`${prefix}-`);
+    }
+    const slug = slugOf(entry);
+    return (name) => name === entry || name === slug;
+};
+/** The prefix `--deny` saves an entry under. */
+export const DENY = '!';
+const isDenial = (entry) => entry.startsWith(DENY);
+export const denialOf = (entry) => `${DENY}${entry}`;
+export const compileAllow = (entries) => {
+    const compiled = entries.filter((entry) => !isDenial(entry)).map((entry) => ({ entry, matches: matcherOf(expandHome(entry)) }));
+    const denied = entries.filter(isDenial).map((entry) => matcherOf(expandHome(entry.slice(DENY.length))));
+    return {
+        allows: (name) => (compiled.length === 0 || compiled.some((item) => item.matches(name))) && !denied.some((matches) => matches(name)),
+        unmatched: (names) => compiled.filter((item) => !names.some((name) => item.matches(name))).map((item) => item.entry),
+    };
+};
+/**
+ * Whether the named entries only lift saved denials: each is denied in `saved`, and `saved` names no folder. On every-folder scope such
+ * an `--allow` drops the denial and adds nothing, because adding the entry would narrow every later run to it.
+ */
+const liftsOnly = (saved, named) => named.length > 0 && saved.every(isDenial) && named.every((entry) => saved.includes(denialOf(entry)));
+/**
+ * The list a deposit saves: the saved entries and the given ones, where naming a folder again with `--allow` lifts the denial of exactly
+ * that entry. A denial is kept until then, so a later `--allow` of a wider prefix cannot read a denied folder.
+ */
+export const mergeAllow = (saved, given) => {
+    const kept = saved.filter((entry) => !(isDenial(entry) && given.includes(entry.slice(DENY.length))));
+    const added = liftsOnly(saved, given.filter((entry) => !isDenial(entry))) ? given.filter(isDenial) : given;
+    return [...new Set([...kept, ...added])];
+};
+/** What one deposit reads: the folders it names, else the saved list (empty is every folder), less every denial saved or given. */
+export const runAllow = (saved, given) => {
+    const merged = mergeAllow(saved, given);
+    const named = given.filter((entry) => !isDenial(entry));
+    return named.length === 0 || liftsOnly(saved, named) ? merged : [...named, ...merged.filter(isDenial)];
+};
+/** One entry per line; blank lines and lines starting with `#` are skipped. */
+export const parseAllowList = (text) => text
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter((line) => line !== '' && !line.startsWith('#'));

package/dist/sessions/archive.d.ts

@@ -0,0 +1,11 @@
+export type Archived = 'linked' | 'copied' | 'present';
+/** The file operations, injectable so a test can force the cross-volume fallback. */
+export interface ArchiveOps {
+    link: (source: string, target: string) => Promise<void>;
+    copyFile: (source: string, target: string) => Promise<void>;
+}
+/**
+ * Archives `source` at `target`, idempotently. A target that is the same file (a hard link) or a copy at least as new and the same size
+ * is left alone; one the harness has since rewritten or grown past is replaced.
+ */
+export declare const archiveRaw: (source: string, target: string, ops?: ArchiveOps) => Promise<Archived>;

package/dist/sessions/archive.js

@@ -0,0 +1,38 @@
+// oars' own raw archive (Matt 2026-11-01, retention point 4c): every deposited transcript is hard-linked under `<store>/raw/`, so the
+// raw behind the log outlives the harness's cleanup without a second copy on disk while both exist. Across volumes, where a hard link
+// cannot reach, it is copied. Local only: nothing here is ever shared.
+import { copyFile, link, mkdir, rm, stat } from 'node:fs/promises';
+import { dirname } from 'node:path';
+const NODE_OPS = { link, copyFile };
+const isCode = (error, ...codes) => error instanceof Error && 'code' in error && typeof error.code === 'string' && codes.includes(error.code);
+// EXDEV: another volume. EPERM, ENOTSUP: a file system without hard links. EMLINK: the source's link count is at its limit.
+const CANNOT_LINK = ['EXDEV', 'EPERM', 'ENOTSUP', 'EMLINK'];
+/**
+ * Archives `source` at `target`, idempotently. A target that is the same file (a hard link) or a copy at least as new and the same size
+ * is left alone; one the harness has since rewritten or grown past is replaced.
+ */
+export const archiveRaw = async (source, target, ops = NODE_OPS) => {
+    const from = await stat(source, { bigint: true });
+    const to = await stat(target, { bigint: true }).catch((error) => {
+        if (isCode(error, 'ENOENT'))
+            return undefined;
+        throw error;
+    });
+    if (to !== undefined) {
+        const sameFile = to.ino === from.ino && to.dev === from.dev;
+        if (sameFile || (to.size === from.size && to.mtimeMs >= from.mtimeMs))
+            return 'present';
+        await rm(target, { force: true });
+    }
+    await mkdir(dirname(target), { recursive: true });
+    try {
+        await ops.link(source, target);
+        return 'linked';
+    }
+    catch (error) {
+        if (!isCode(error, ...CANNOT_LINK))
+            throw error;
+    }
+    await ops.copyFile(source, target);
+    return 'copied';
+};

package/dist/sessions/audit.d.ts

@@ -0,0 +1,42 @@
+import type { SessionObservation, Skeleton } from './schema.js';
+import { type SessionsRuntime, type State } from './store.js';
+/** The T0 result table of spec 2.4, one name per row. */
+export declare const T0_RESULTS: readonly ["root matches and the counts bind", "changed since deposit", "root mismatch", "counts do not bind", "not run"];
+export type T0Result = (typeof T0_RESULTS)[number];
+export interface SessionAudit {
+    session: string;
+    result: T0Result;
+    /** `none` means `W` is 0 until a new capture writes a new root; every other T0 result holds the tier at `skeleton`. */
+    tier: 'skeleton' | 'none';
+    /** How `raw/` holds the file: a hard link to the harness's transcript, or a copy (cross-volume, or a link whose source is gone). Null when there is no raw file or the counts failed first. */
+    mode: 'link' | 'copy' | null;
+    leaves: number;
+    /** Under {@link MIN_ROOT_LEAVES}: the root joins no cluster and the session counts toward no `n` (spec 2.5). */
+    belowMinLeaves: boolean;
+    changedSinceDeposit: boolean;
+    /** A copy whose size differs from `state.json`'s: a copy changes only when `archiveRaw` refreshes it, so growth is not an honest explanation (spec 2.4). */
+    possibleTampering: boolean;
+    bindings: {
+        leaves: number;
+        sessionLines: number;
+        skeletonLines: number;
+        badLines: number;
+        bind: boolean;
+    };
+}
+/**
+ * One session's T0 result. The count bindings come first and need no raw file: a record set that disagrees with itself is `none` whatever `raw/`
+ * holds. `state` is `state.json`, read once by {@link auditStore}.
+ */
+export declare const auditSession: (runtime: SessionsRuntime, session: SessionObservation, skeleton: Skeleton | undefined, state?: State) => Promise<SessionAudit>;
+/**
+ * Every session's T0 result, in the order given, then one `not run` for each skeleton with no capture record (a torn or removed observations line), so
+ * the table never shrinks without a signal. A session with no skeleton, or whose raw file cannot be read, is also `not run`.
+ */
+export declare const auditStore: (runtime: SessionsRuntime, sessions: readonly SessionObservation[], skeletons: readonly Skeleton[]) => Promise<SessionAudit[]>;
+export type T0Counts = {
+    [result in T0Result]: number;
+};
+export declare const auditCounts: (audits: readonly SessionAudit[]) => T0Counts;
+/** A count line for every row of the T0 table, then one FAIL line per session at tier `none` and one note per session that changed. */
+export declare const formatAudit: (audits: readonly SessionAudit[]) => string;