@manyoars/oars 0.3.0 → 0.4.0

package/dist/gate/hook-process.js

@@ -8,6 +8,17 @@ import { parseRows } from './record.js';
 const unprinted = (text) => parseRows(text)
     .map((row) => `${JSON.stringify(row.kind === 'crossing' ? { ...row, arm: 'none', lineShown: 'none', lineHeld: 'none' } : row)}\n`)
     .join('');
+/** The transcript path the harness put in the hook input, when there is one; anything else, including input that is not JSON, names none. */
+const transcriptOf = (input) => {
+    try {
+        const parsed = JSON.parse(input);
+        const path = typeof parsed === 'object' && parsed !== null ? Reflect.get(parsed, 'transcript_path') : undefined;
+        return typeof path === 'string' && path !== '' ? path : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
 const sizeOf = (file) => {
     try {
         return statSync(file).size;
@@ -26,7 +37,33 @@ const landed = (file, text, size) => {
     }
 };
 /** Resolves once `exit(0)` has been called, or never when the deadline timer is what ended the process. */
-export const runHookProcess = async ({ stdin, deps, exit, write, deadlineMs }) => {
+export const runHookProcess = async ({ stdin, deps, exit, write, deadlineMs, record, clock = Date.now }) => {
+    const started = clock();
+    // `held` and `error` are what the output cannot say; the callback reaches the hook through `deps`.
+    const how = { ended: null };
+    let fired;
+    let transcript;
+    // Telemetry hears of a fire once: the deadline timer records the fire it cuts short (the slowest ones), and the main path skips a fire the timer has already told.
+    let recorded = false;
+    // Set once the main path's `record` has resolved. While it is false after `recorded`, the main path is still reading the transcript, and a stalled read would otherwise lose the fire at the deadline.
+    let settled = false;
+    let told;
+    const send = async (result, transcript) => {
+        try {
+            await record?.({ latencyMs: Math.max(0, Math.round(clock() - started)), ...result }, transcript);
+        }
+        catch {
+            // Telemetry never changes what the hook did.
+        }
+    };
+    const tell = async (result, transcript) => {
+        if (recorded)
+            return;
+        recorded = true;
+        told = result;
+        await send(result, transcript);
+        settled = true;
+    };
     // `size` is the file's length when the record was staged: an append that wrote and then stalled has put the record's own bytes past it, and the deadline must not write it again.
     let staged = null;
     // The last resort when the process is stuck past its grace: keep the staged record, then go. A write that fails here has nowhere to report, so it is dropped.
@@ -39,6 +76,12 @@ export const runHookProcess = async ({ stdin, deps, exit, write, deadlineMs }) =
         catch {
             // Fail-open.
         }
+        // The fire the deadline cut short is still a fire: recorded as an error with nothing printed, after the row and before the stop so a slow stop cannot lose it.
+        // When the main path had told it first and its transcript read is still going, the fire it settled on goes now, with no transcript, so the read cannot cost the event.
+        if (!recorded)
+            void tell({ outcome: 'error', bytes: 0 });
+        else if (!settled && told !== undefined)
+            void send(told);
         // A registry ask still running is then stopped, so the manager the hook started does not outlive it; a stop that throws must not cost the exit.
         try {
             staged?.stop?.();
@@ -52,13 +95,18 @@ export const runHookProcess = async ({ stdin, deps, exit, write, deadlineMs }) =
         const built = deps((pending) => {
             staged = pending === null ? null : { ...pending, size: sizeOf(pending.file) };
         });
-        const output = await gateHook(await stdin(), built);
+        const input = await stdin();
+        transcript = transcriptOf(input);
+        const output = await gateHook(input, { ...built, ended: (result) => { how.ended = result; built.ended?.(result); } });
         if (output !== '')
             await write?.(output);
+        fired = { outcome: how.ended ?? (output === '' ? 'miss' : 'hit'), bytes: Buffer.byteLength(output) };
     }
     catch {
         // Fail-open: a throw anywhere above is a record not written, never an exit code.
+        fired = { outcome: 'error', bytes: 0 };
     }
+    await tell(fired, transcript);
     // A manager the registry ask started can outlive the ask; leaving by `exit` rather than waiting for it is what keeps the call under a second.
     exit(0);
 };

package/dist/gate/hook-record.d.ts

@@ -0,0 +1,3 @@
+import type { Emit } from '../telemetry/emit.js';
+import type { HookProcess } from './hook-process.js';
+export declare const fireRecorder: (emit: Emit) => NonNullable<HookProcess["record"]>;

package/dist/gate/hook-record.js

@@ -0,0 +1,8 @@
+// What `oars gate hook` tells telemetry about one fire: the fire itself, plus the harness version and model its transcript states. Apart from `hook-main.ts` so a test drives the same line the process runs.
+import { statedAt } from '../sessions/transcript-tail.js';
+import { frameWords, HOOK_HARNESS } from '../telemetry/fields.js';
+export const fireRecorder = (emit) => async (fire, transcript) => {
+    // No await before this on the deadline path (no transcript), so that fire is written before the timer's `exit`.
+    const stated = transcript === undefined ? undefined : await statedAt(transcript);
+    emit('hook', { name: 'gate', ...fire, ...frameWords(HOOK_HARNESS, stated?.harnessVersion, stated?.model) });
+};

package/dist/gate/hook.d.ts

@@ -36,6 +36,8 @@ export interface GateHookDeps {
         text: string;
         stop?: () => void;
     } | null) => void;
+    /** Told how a call ended when its output alone does not say: `held` when a note was kept from the agent (the unexposed arm), `error` when the hook failed open. For telemetry; it changes nothing. */
+    ended?: (how: 'held' | 'error') => void;
 }
 /**
  * Records the crossings of one tool call. Resolves with the JSON to print: a note as context, or a deny labeled with the fact; never an allow or a changed call.

package/dist/gate/hook.js

@@ -239,6 +239,8 @@ export const runGateHook = async (stdin, deps) => {
     finally {
         deps.stage?.(null);
     }
+    if (blocks.length === 0 && notes.length === 0 && written.some((row) => row.arm === 'held'))
+        deps.ended?.('held');
     await keepIndex(deps.storeDir, index, [...lines]).catch(() => undefined);
     if (answered.length > 0)
         await append(registryCachePath(deps.storeDir), answered.map((row) => `${JSON.stringify(row)}\n`).join('')).catch(() => undefined);
@@ -251,6 +253,7 @@ export const gateHook = async (stdin, deps) => {
     }
     catch {
         // Fail-open: a recorder that cannot record must not cost a session its tool call.
+        deps.ended?.('error');
     }
     return '';
 };

package/dist/gate/replay.js

@@ -2,8 +2,7 @@
 // It never calls `localSalt` or the step log, both of which write, and it holds no store lock, since a replay touches nothing a deposit reads.
 import { readFile, stat } from 'node:fs/promises';
 import { join } from 'node:path';
-import { CliError, ExitCode } from '../errors.js';
-import { compileAllow } from '../sessions/allow.js';
+import { compileAllow, runAllow } from '../sessions/allow.js';
 import { makeRedactor } from '../sessions/redact.js';
 import { paths, readState, writeAtomic } from '../sessions/store.js';
 import { GATE_VERSION, liveCrossings, mergeCrossings, parseRows } from './record.js';
@@ -209,9 +208,7 @@ const readAll = async (runtime, entries, domains) => {
 };
 export const replay = async (runtime, options) => {
     const state = await readState(runtime.storeDir);
-    const entries = options.allow.length > 0 ? options.allow : state.allow;
-    if (entries.length === 0)
-        throw new CliError('Name a folder with --allow: nothing is read from a folder you have not named, and no deposit has saved an allowlist.', ExitCode.USAGE, 'usage');
+    const entries = runAllow(state.allow, options.allow);
     const { reads, transcripts, unreadable } = await readAll(runtime, entries, state.redactDomains);
     const held = [];
     for (const { transcript, read } of reads) {

package/dist/gate/report.js

@@ -9,7 +9,7 @@ export const LIMITS = [
     'what a person saw or approved on screen; the permission mode is what the log kept',
     'an MCP server that was started and never called',
     'folders off the allowlist, and logs the harness has already cleaned up',
-    'a session in Codex, Cursor, Copilot, Gemini CLI, Grok Build, or VS Code Copilot Chat, which replay does not read (`--allow codex`, `--allow cursor`, `--allow copilot`, `--allow gemini`, `--allow grok`, and `--allow vscode-copilot` add nothing to it): they keep sessions in their own formats, not as transcript files',
+    'a session in Codex, Cursor, Copilot, Gemini CLI, Grok Build, OpenCode, Pi, VS Code Copilot Chat, or an OpenTelemetry GenAI trace, which replay does not read (`--allow codex`, `--allow cursor`, `--allow copilot`, `--allow gemini`, `--allow grok`, `--allow opencode`, `--allow pi`, `--allow vscode-copilot`, and `--allow otel` add nothing to it): they keep sessions in their own formats, not as transcript files',
     'pool reads, sign-in, and deposit prompts; this release reads none of them',
 ];
 const tally = (vocabulary, rows, pick) => vocabulary.map((value) => ({ value, count: rows.filter((row) => pick(row) === value).length }));

package/dist/gate/transcripts.js

@@ -28,7 +28,7 @@ export const discover = async (roots, allow) => {
     const files = [];
     let unreadable = 0;
     for (const root of roots) {
-        // Replay reads only the harness's transcript format: a source-table folder (Cursor, Codex, Copilot, Gemini CLI, Grok Build, VS Code Copilot Chat) is not that format, and a project folder is never named for one.
+        // Replay reads only the harness's transcript format: a source-table folder (Cursor, Codex, Copilot, Gemini CLI, Grok Build, OpenCode, Pi, VS Code Copilot Chat) is not that format, and a project folder is never named for one.
         const projects = (await listDir(root)).filter((entry) => entry.isDirectory() && !SOURCES.some((source) => source.name === entry.name) && allow.allows(entry.name));
         for (const project of projects) {
             try {

package/dist/hook-bin.js

@@ -1,8 +1,11 @@
 // The one entry file the installed hooks and the nightly task run: `node hook-bin.js <session-start|pre-tool|post-tool|stop|nightly>`, with the
 // hook event JSON on stdin. It imports only the store modules (not the CLI), so a call costs little more than the node start, and it
 // always exits 0 with no output on any failure: a hook must never fail or block a session.
+import { readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { HOOK_EVENTS, hookRuntime, runHook } from './sessions/hooks.js';
+import { hookEmitter } from './telemetry/hook-emit.js';
+import { sendNightly } from './telemetry/send.js';
+import { HOOK_EVENTS, hookRuntime, nightlyTelemetry, runHook } from './sessions/hooks.js';
 const readStdin = async () => {
     process.stdin.setEncoding('utf8');
     let text = '';
@@ -10,13 +13,35 @@ const readStdin = async () => {
         text += String(chunk);
     return text;
 };
+/** The version in this package's package.json (one folder up from dist/), or `0.0.0` when it cannot be read. */
+const versionOf = () => {
+    try {
+        const manifest = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+        const version = typeof manifest === 'object' && manifest !== null ? Reflect.get(manifest, 'version') : undefined;
+        return typeof version === 'string' ? version : '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+};
+/** After the covenant is accepted, the nightly task sends what the pool outbox holds; with no server, sign-in, or acceptance it sends nothing. Loaded only here so the per-tool hooks never pay for it. It never throws. */
+const nightlyPool = async (event) => {
+    const { nightlyPoolDeps } = await import('./sessions/pool-nightly-deps.js');
+    const { nightlyPoolSend } = await import('./sessions/pool-nightly.js');
+    await nightlyPoolSend(nightlyPoolDeps(process.env, hookRuntime(event, process.env, process.platform, homedir(), { stdin: process.stdin, stdout: process.stdout }), versionOf(), Date.now));
+};
 const eventOf = (name) => HOOK_EVENTS.find((event) => event === name);
 try {
     const event = eventOf(process.argv[2]);
     if (event !== undefined) {
-        const output = await runHook(event, event === 'nightly' ? '' : await readStdin(), hookRuntime(event, process.env, process.platform, homedir(), { stdin: process.stdin, stdout: process.stdout }), Date.now);
+        const output = await runHook(event, event === 'nightly' ? '' : await readStdin(), hookRuntime(event, process.env, process.platform, homedir(), { stdin: process.stdin, stdout: process.stdout }), Date.now, nightlyTelemetry(event, process.env, process.platform, homedir(), versionOf, Date.now), hookEmitter(process.env, process.platform, homedir(), new URL('../package.json', import.meta.url), Date.now));
         if (output !== undefined)
             process.stdout.write(output);
+        // The nightly task is where telemetry is sent from; it never throws, and it sends nothing unless telemetry is on and the notice was shown (the server is OARS_POOL_URL, else the Many Oars pool).
+        if (event === 'nightly') {
+            await sendNightly(process.env, process.platform, homedir(), Date.now);
+            await nightlyPool(event);
+        }
     }
 }
 catch {

package/dist/issuer.d.ts

@@ -1,16 +1,14 @@
 import type { RunDeps } from './cli.js';
 /**
- * The production Keycloak realm (the platform's k8s/configmap.yaml: KEYCLOAK_ISSUER_URI). It ships in the CLI, reviewed with it:
- * the launch flag below only switches it on, so a compromised site cannot send logins anywhere else.
+ * The production Keycloak realm (the platform's k8s/configmap.yaml: KEYCLOAK_ISSUER_URI). It ships in the CLI, reviewed with it,
+ * and is the default for `oars login`: no site or file can send a login anywhere else.
  */
 export declare const PRODUCTION_ISSUER_URL = "https://login.manyoars.com/realms/aor";
-/** The marketing site serves `{"launched": true}` here from launch day. */
-export declare const LAUNCH_FLAG_URL = "https://manyoars.com/.well-known/oars.json";
 /**
- * The built-in issuer is in use only when neither `--issuer-url` nor `OARS_ISSUER_URL` named one. If the flag is on but that
- * issuer does not answer discovery (no answer, an error status, or a body that is not discovery JSON), the platform is not
- * really open yet, so say what `login` says before launch (exit 2). An issuer the developer named keeps its own error.
+ * The built-in issuer is in use only when neither `--issuer-url` nor `OARS_ISSUER_URL` named one. If that issuer does not answer
+ * discovery (no answer, an error status, or a body that is not discovery JSON), the platform is not up yet, so say so (exit 2) and
+ * name the pool. An issuer the developer named keeps its own error.
  */
 export declare const discoverIssuer: <T>(deps: RunDeps, flag: string | undefined, discover: () => Promise<T>) => Promise<T>;
-/** `--issuer-url`, else `OARS_ISSUER_URL`, else the built-in production issuer once the launch flag is on. */
-export declare const resolveIssuerUrl: (deps: RunDeps, flag?: string) => Promise<string>;
+/** `--issuer-url`, else `OARS_ISSUER_URL`, else the built-in production issuer. */
+export declare const resolveIssuerUrl: (deps: RunDeps, flag?: string) => string;

package/dist/issuer.js

@@ -1,34 +1,14 @@
 import { CliError, ExitCode } from './errors.js';
 /**
- * The production Keycloak realm (the platform's k8s/configmap.yaml: KEYCLOAK_ISSUER_URI). It ships in the CLI, reviewed with it:
- * the launch flag below only switches it on, so a compromised site cannot send logins anywhere else.
+ * The production Keycloak realm (the platform's k8s/configmap.yaml: KEYCLOAK_ISSUER_URI). It ships in the CLI, reviewed with it,
+ * and is the default for `oars login`: no site or file can send a login anywhere else.
  */
 export const PRODUCTION_ISSUER_URL = 'https://login.manyoars.com/realms/aor';
-/** The marketing site serves `{"launched": true}` here from launch day. */
-export const LAUNCH_FLAG_URL = 'https://manyoars.com/.well-known/oars.json';
-const FLAG_TIMEOUT_MS = 5000;
-const NOT_LAUNCHED = 'Many Oars has not launched yet: pass --issuer-url or set OARS_ISSUER_URL.';
-/** True only for a 200 answer whose JSON is an object with `launched: true`; every other answer, or none, means not launched. */
-const hasLaunched = async (deps) => {
-    try {
-        const response = await fetch(LAUNCH_FLAG_URL, {
-            headers: { 'User-Agent': `oars/${deps.version}`, Accept: 'application/json' },
-            redirect: 'error',
-            signal: AbortSignal.timeout(FLAG_TIMEOUT_MS),
-        });
-        if (!response.ok)
-            return false;
-        const body = await response.json();
-        return typeof body === 'object' && body !== null && Reflect.get(body, 'launched') === true;
-    }
-    catch {
-        return false;
-    }
-};
+const UNAVAILABLE = 'Cannot reach Many Oars sign-in at login.manyoars.com (Many Oars and its pool at pool.manyoars.com may not be deployed yet). Pass --issuer-url or set OARS_ISSUER_URL to use another issuer.';
 /**
- * The built-in issuer is in use only when neither `--issuer-url` nor `OARS_ISSUER_URL` named one. If the flag is on but that
- * issuer does not answer discovery (no answer, an error status, or a body that is not discovery JSON), the platform is not
- * really open yet, so say what `login` says before launch (exit 2). An issuer the developer named keeps its own error.
+ * The built-in issuer is in use only when neither `--issuer-url` nor `OARS_ISSUER_URL` named one. If that issuer does not answer
+ * discovery (no answer, an error status, or a body that is not discovery JSON), the platform is not up yet, so say so (exit 2) and
+ * name the pool. An issuer the developer named keeps its own error.
  */
 export const discoverIssuer = async (deps, flag, discover) => {
     try {
@@ -38,18 +18,16 @@ export const discoverIssuer = async (deps, flag, discover) => {
         const named = flag !== undefined || (deps.env.OARS_ISSUER_URL !== undefined && deps.env.OARS_ISSUER_URL !== '');
         const unanswered = error instanceof CliError && (error.exitCode === ExitCode.UNREACHABLE || error.exitCode === ExitCode.UNEXPECTED);
         if (!named && unanswered)
-            throw new CliError(NOT_LAUNCHED, ExitCode.USAGE, 'usage');
+            throw new CliError(UNAVAILABLE, ExitCode.USAGE, 'usage');
         throw error;
     }
 };
-/** `--issuer-url`, else `OARS_ISSUER_URL`, else the built-in production issuer once the launch flag is on. */
-export const resolveIssuerUrl = async (deps, flag) => {
+/** `--issuer-url`, else `OARS_ISSUER_URL`, else the built-in production issuer. */
+export const resolveIssuerUrl = (deps, flag) => {
     if (flag !== undefined)
         return flag;
     const fromEnv = deps.env.OARS_ISSUER_URL;
     if (fromEnv !== undefined && fromEnv !== '')
         return fromEnv;
-    if (await hasLaunched(deps))
-        return PRODUCTION_ISSUER_URL;
-    throw new CliError(NOT_LAUNCHED, ExitCode.USAGE, 'usage');
+    return PRODUCTION_ISSUER_URL;
 };

package/dist/main.js

@@ -10,6 +10,7 @@ import { defaultConfigDir, fileCredentialStore } from './credentials.js';
 import { cursorRoot } from './sessions/cursor.js';
 import { claudeEvaluator, runClaude } from './sessions/gold-arms.js';
 import { SOURCES } from './sessions/sources.js';
+import { spawnDetachedSend } from './telemetry/send.js';
 /** The version in this package's package.json (one folder up from dist/). */
 const readVersion = () => {
     const manifest = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
@@ -25,12 +26,14 @@ process.exitCode = await run(process.argv.slice(2), {
         stderr: (text) => process.stderr.write(text),
     },
     store: fileCredentialStore(configDir),
+    telemetry: { dir: join(configDir, 'oars', 'telemetry'), platform: process.platform, spawnSend: spawnDetachedSend },
     version: readVersion(),
     sleep: (ms) => sleep(ms),
     random: Math.random,
     now: Date.now,
     openBrowser,
     install: {
+        platform: process.platform,
         nodePath: process.execPath,
         hookBin: fileURLToPath(new URL('./hook-bin.js', import.meta.url)),
         userSettings: join(process.env.CLAUDE_CONFIG_DIR ?? join(homedir(), '.claude'), 'settings.json'),

package/dist/sessions/actions.js

@@ -328,6 +328,84 @@ export const ACTION_TABLES = {
         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) => {

package/dist/sessions/allow.d.ts

@@ -8,7 +8,16 @@ export interface Allow {
     /** 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[];
-export declare const requireEntries: (entries: readonly string[]) => void;

package/dist/sessions/allow.js

@@ -3,10 +3,10 @@
 //   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 `-`.
+// 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';
-import { CliError, ExitCode } from '../errors.js';
 /** 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 `-`. */
@@ -32,20 +32,40 @@ const matcherOf = (entry) => {
     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.map((entry) => ({ entry, matches: matcherOf(expandHome(entry)) }));
+    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.some((item) => item.matches(name)),
+        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('#'));
-export const requireEntries = (entries) => {
-    if (entries.length === 0) {
-        throw new CliError('Nothing to read: pass at least one --allow <folder> or --allow-file <list>. Nothing is read from a folder you have not named.', ExitCode.USAGE, 'usage');
-    }
-};

package/dist/sessions/baseline.d.ts

@@ -19,7 +19,7 @@ export type Dimension = (typeof DIMENSIONS)[number];
 /** The fields each record needs, so a caller passes the store's records and a test passes small ones. */
 export type BaselineSession = Pick<SessionObservation, 'session' | 'tsFirst' | 'tools' | 'harness'>;
 export type BaselineTool = Pick<ToolObservation, 'session' | 'status' | 'durationMs'>;
-export type BaselinePrompt = Pick<PromptObservation, 'session' | 'wallSec' | 'cls' | 'turns' | 'usage'>;
+export type BaselinePrompt = Pick<PromptObservation, 'session' | 'wallSec' | 'cls' | 'turns' | 'usage' | 'usageObserved'>;
 export interface DimensionDistance {
     dimension: Dimension;
     distance: number;

package/dist/sessions/baseline.js

@@ -1,6 +1,6 @@
 // Layer 2's self-baseline (spec 2.2): a session's week against the operator's own other weeks on the same harness. Local only: no pooled field,
 // no network, no account step. The peer baseline waits for T2.
-import { harnessOf } from './schema.js';
+import { harnessOf, observesUsage } from './schema.js';
 /** A week needs this many tool calls to be a unit or a baseline week (spec 5.4 item 1). */
 export const BASELINE_MIN_CALLS = 1000;
 /** A baseline needs this many other qualifying weeks (spec 5.4 item 1). */
@@ -137,10 +137,12 @@ export const selfBaseline = (sessions, tools, prompts, asOf) => {
             add(histogramOf(group.histograms, 'prompt class'), prompt.cls);
             if (prompt.wallSec !== null)
                 add(histogramOf(group.histograms, 'wallSec'), binOf(prompt.wallSec, WALL_EDGES_SEC));
-            const input = prompt.usage.input + prompt.usage.cacheWrite + prompt.usage.cacheRead;
-            if (input > 0)
+            // A category the source never recorded is a placeholder zero, not a measurement: the share needs input and cacheRead, and counts only the input-side categories recorded;
+            // output per turn needs output. A prompt missing what a dimension needs adds no count to it, so its denominator holds only the prompts that recorded the category.
+            const input = ['input', 'cacheWrite', 'cacheRead'].reduce((sum, field) => sum + (observesUsage(prompt, field) ? prompt.usage[field] : 0), 0);
+            if (observesUsage(prompt, 'input') && observesUsage(prompt, 'cacheRead') && input > 0)
                 add(histogramOf(group.histograms, 'cache-read share'), binOf(prompt.usage.cacheRead * 10, CACHE_SHARE_TENTHS, input));
-            if (prompt.turns > 0)
+            if (observesUsage(prompt, 'output') && prompt.turns > 0)
                 add(histogramOf(group.histograms, 'output per turn'), binOf(prompt.usage.output, OUTPUT_PER_TURN_EDGES, prompt.turns));
         }
     }

package/dist/sessions/call-shape.d.ts

@@ -0,0 +1,19 @@
+import type { TargetBase } from './schema.js';
+/** Where a path target sits in the project, as a closed list. `none` is a call with no path target (a shell call, a search, a fetch). */
+export declare const TARGET_CLASSES: readonly ["source", "test", "config", "doc", "lockfile", "generated", "data", "none", "other"];
+export type TargetClass = (typeof TARGET_CLASSES)[number];
+/** What an argument holds, as a closed list: a call's arguments are the sorted set of these. `none` is a call with no arguments. */
+export declare const ARG_CLASSES: readonly ["path", "url", "pattern", "command", "number", "flag", "text", "none"];
+export type ArgClass = (typeof ARG_CLASSES)[number];
+/**
+ * The class of a path target, from the base that hashed it and the path's own suffix. A call with no path target (`base` null) is `none`; the order below is the order a path is asked,
+ * so a lockfile is never `config` and a `tests/data.json` is `test`. The mapping is pinned in `call-shape.test.ts`. `path` is the key the target is hashed on (relative to the repository or the cwd, never the absolute path), so the folders above a repository do not decide the class; it is read here and goes no further.
+ */
+export declare const targetClassOf: (path: string | undefined, base: TargetBase | null) => TargetClass;
+/**
+ * The classes of a call's arguments, as a sorted set: which of path, URL, pattern, command, number, flag, and text its input holds, or just `none` when it holds no value. A key name
+ * gives the class of a string (`file_path` is a path, `pattern` a pattern, `command` a command), a number or a boolean gives its own, and any other value is text. The values are read here and go no further.
+ */
+export declare const argClassOf: (input: {
+    readonly [key: string]: unknown;
+}) => ArgClass[];