@manyoars/oars 0.2.0 → 0.4.0

package/dist/cli.js

@@ -1,13 +1,22 @@
 import { randomUUID } from 'node:crypto';
 import { Command, CommanderError, InvalidArgumentError } from 'commander';
 import { resolveApiUrl } from './api.js';
-import { deploy } from './commands/deploy.js';
+import { keysCreate, keysList, keysRevoke, SCOPED_AUTHORITIES } from './commands/keys.js';
 import { login } from './commands/login.js';
 import { logout } from './commands/logout.js';
-import { status } from './commands/status.js';
-import { templates } from './commands/templates.js';
-import { testCharge } from './commands/test-charge.js';
 import { CliError, ExitCode } from './errors.js';
+import { closedQueryOf, formsRefusal, RECALL_FAMILIES } from './sessions/recall-reads.js';
+import { FAMILIES } from './sessions/read.js';
+import { sessionsBooks, sessionsContext, sessionsDeposit, sessionsGoldArms, sessionsGoldSample, sessionsGoldScore, sessionsHookInstall, sessionsHookStatus, sessionsHookUninstall, sessionsMcp, sessionsLineage, sessionsMeasure, sessionsRead, sessionsRecall, sessionsRecallCounts, sessionsVerify } from './sessions/command.js';
+import { gateInstall, gatePolicy, gateReplay, gateReport, gateUninstall } from './gate/command.js';
+import { DEADLINE_MS, gateHook } from './gate/hook.js';
+import { managerReader } from './gate/registry.js';
+import { exclusionPaths, sessionsExclusions } from './sessions/exclusion.js';
+import { poolCoverage, poolDeposit, poolFetch, poolLogin, poolOutbox, poolRaw } from './sessions/pool-command.js';
+import { telemetryOff, telemetryOn, telemetryReport, telemetryShow, telemetryStatus } from './telemetry/command.js';
+import { recordCrash } from './telemetry/crash.js';
+import { emitOf } from './telemetry/emit.js';
+import { finishTelemetry, observeCommand } from './telemetry/observe.js';
 const flag = (options, name) => options[name] === true;
 const text = (options, name) => {
     const value = options[name];
@@ -28,50 +37,46 @@ const positiveInteger = (value) => {
         throw new InvalidArgumentError('it must be a positive whole number.');
     return Number(value);
 };
+/** An ISO time, normalized to the form session timestamps are stored in so the two compare as text. */
+const isoTime = (value) => {
+    const parsed = Date.parse(value);
+    if (Number.isNaN(parsed))
+        throw new InvalidArgumentError('it must be an ISO time such as 2026-11-01T16:00:00Z.');
+    return new Date(parsed).toISOString();
+};
 const emit = (deps, json, outcome) => {
     deps.io.stdout(`${json ? JSON.stringify(outcome.document) : outcome.text}\n`);
 };
-/** The last line of an exit 6: the one thing a person must do, by link when the platform sent one, then to rerun. Stripe onboarding is the step most runs wait on. */
-const needsYouLine = (code, actionUrl) => {
-    const stripe = code === 'ACCOUNT_NOT_READY';
-    if (actionUrl !== undefined && actionUrl !== '') {
-        return `Needs you: ${stripe ? 'finish Stripe onboarding at' : 'open'} ${actionUrl}, then rerun this command.`;
-    }
-    return stripe
-        ? 'Needs you: finish Stripe onboarding (Account, then Payout account, in the Many Oars web app), then rerun this command.'
-        : 'Needs you: a step only a person can do. Do it in the Many Oars web app, then rerun this command.';
-};
 /**
- * `--json` prints `{ok: false, step, problem}` on stdout, plus `workloadId`, `sdkKey` and `rerun` after a deploy that stopped;
- * otherwise the problem's title, detail and URL go to stderr, then the rerun line, and the one-time SDK key goes to stdout.
+ * `--json` prints `{ok: false, step, problem}` on stdout, plus the error's details; otherwise the problem's title, detail,
+ * and URL go to stderr.
  */
 const printFailure = (deps, json, error) => {
-    const { partial } = error;
     if (json) {
-        deps.io.stdout(`${JSON.stringify({ ok: false, step: error.step, problem: error.problem, ...partial })}\n`);
+        deps.io.stdout(`${JSON.stringify({ ok: false, step: error.step, problem: error.problem, ...error.details })}\n`);
         return;
     }
     const { title, detail, actionUrl } = error.problem;
-    const resume = partial === undefined ? [] : [`Workload ${partial.workloadId} is registered; the deploy stopped at ${error.step}.`, `Rerun to resume: ${partial.rerun}`];
-    const needsYou = error.exitCode === ExitCode.HUMAN ? [needsYouLine(error.problem.code, actionUrl)] : [];
-    deps.io.stderr(`${[title ?? error.message, detail, ...(needsYou.length === 0 ? [actionUrl] : []), ...resume, ...needsYou].filter((line) => line !== undefined && line !== '').join('\n')}\n`);
-    if (partial?.sdkKey !== undefined)
-        deps.io.stdout(`SDK key (shown once; save it now): ${partial.sdkKey}\n`);
+    deps.io.stderr(`${[title ?? error.message, detail, actionUrl].filter((line) => line !== undefined && line !== '').join('\n')}\n`);
 };
-const buildProgram = (deps, argv) => {
+const sessionDeps = (deps) => ({ sessions: deps.sessions, install: deps.install, now: deps.now, telemetry: emitOf(deps) });
+const buildProgram = (deps, observed) => {
     const program = new Command('oars')
-        .description('Deploy an agent on Many Oars and set its prices')
+        .description('Many Oars: sign in, manage API keys, and keep a local, searchable record of your own coding-agent sessions')
         .version(deps.version)
         .exitOverride()
         .configureOutput({ writeOut: deps.io.stdout, writeErr: deps.io.stderr })
         .option('--json', 'print one JSON document on stdout instead of text')
         .option('--api-url <url>', 'the platform API (default: OARS_API_URL, else https://api.manyoars.com)')
-        .option('--idempotency-key <key>', "the base of every step's idempotency key (default: a fresh UUID); rerun a failed command with the same key to resume");
+        .option('--idempotency-key <key>', "the base of the idempotency key (default: a fresh UUID); rerun a failed command with the same key to replay it")
+        .hook('preAction', (_program, action) => {
+        observeCommand(observed, action);
+    });
     program
         .command('login')
         .description('sign in with your browser (RFC 8628 device flow)')
         .option('--no-browser', 'print the link and code without opening a browser')
-        .option('--issuer-url <url>', 'the Keycloak realm URL (default: OARS_ISSUER_URL, else Many Oars once it has launched)')
+        .option('--issuer-url <url>', 'the Keycloak realm URL (default: OARS_ISSUER_URL, else the Many Oars issuer)')
         .action(async (_options, command) => {
         const options = command.optsWithGlobals();
         const outcome = await login(deps, {
@@ -88,77 +93,411 @@ const buildProgram = (deps, argv) => {
         const options = command.optsWithGlobals();
         emit(deps, flag(options, 'json'), await logout(deps));
     });
-    program
-        .command('templates')
-        .description('list the starter templates `oars deploy --template` takes')
+    const keys = program.command('keys').description('create, list, and revoke your API keys; a key made with --workload works on that one workload only');
+    keys
+        .command('create')
+        .description('create an API key and print its secret once; --workload limits it to one workload you created')
+        .requiredOption('--name <name>', 'a name to recognize the key by')
+        .option('--workload <id>', 'limit the key to this workload (it may then carry only AGENT_OPERATE and AGENT_READ)')
+        .option('--authority <name>', 'an authority for the key (repeatable; default AGENT_OPERATE and AGENT_READ)', collect)
+        .option('--expires-in-days <n>', 'days until the key expires', positiveInteger)
         .action(async (_options, command) => {
         const options = command.optsWithGlobals();
-        emit(deps, flag(options, 'json'), await templates(deps, { apiUrl: resolveApiUrl(deps, text(options, 'apiUrl')) }));
-    });
-    program
-        .command('deploy')
-        .description('register a workload, create its prices and deploy it; stops at the first failed step (exit 9)')
-        .option('--template <id>', 'a starter template from the catalog (see: oars templates)')
-        .option('--image <ref>', 'an image pinned by digest (name@sha256:...)')
-        .option('--manifest <file>', 'a JSON workload manifest')
-        .option('--name <name>', 'the workload name (--image)')
-        .option('--port <n>', 'the service port (--image; default 8080)', positiveInteger)
-        .option('--public', 'expose the service publicly (--image)')
-        .option('--cpu-millicores <n>', 'CPU in millicores (--image; default 250)', positiveInteger)
-        .option('--memory-mib <n>', 'memory in MiB (--image; default 256)', positiveInteger)
-        .option('--always-on', 'keep the public service running instead of idling')
-        .option('--price <ref>', 'a starter price to create instead of all of them (--template; repeatable)', collect)
-        .option('--no-prices', "create none of the template's starter prices (--template)")
-        .option('--price-file <file>', 'a JSON array of prices to create (--image, --manifest)')
-        .option('--secret <NAME=value>', 'a secret for the workload (repeatable); prefer --secret-from-env', collect)
-        .option('--secret-from-env <NAME>', 'a secret read from the environment variable NAME (repeatable)', collect)
-        .option('--no-start', 'register and price the workload without deploying it')
-        .action(async (_options, command) => {
-        const options = command.optsWithGlobals();
-        const outcome = await deploy(deps, {
+        const authorities = list(options, 'authority');
+        const outcome = await keysCreate(deps, {
             apiUrl: resolveApiUrl(deps, text(options, 'apiUrl')),
-            argv,
-            start: options.start !== false,
-            idempotencyKey: text(options, 'idempotencyKey'),
-            template: text(options, 'template'),
-            image: text(options, 'image'),
-            manifestFile: text(options, 'manifest'),
-            name: text(options, 'name'),
-            port: count(options, 'port'),
-            public: flag(options, 'public') ? true : undefined,
-            cpuMillicores: count(options, 'cpuMillicores'),
-            memoryMib: count(options, 'memoryMib'),
-            alwaysOn: flag(options, 'alwaysOn') ? true : undefined,
-            prices: list(options, 'price'),
-            noPrices: options.prices === false,
-            priceFile: text(options, 'priceFile'),
-            secrets: list(options, 'secret'),
-            secretsFromEnv: list(options, 'secretFromEnv'),
+            name: text(options, 'name') ?? '',
+            authorities: authorities.length === 0 ? SCOPED_AUTHORITIES : authorities,
+            idempotencyKey: text(options, 'idempotencyKey') ?? randomUUID(),
+            ...(text(options, 'workload') === undefined ? {} : { workloadId: text(options, 'workload') }),
+            ...(count(options, 'expiresInDays') === undefined ? {} : { expiresInDays: count(options, 'expiresInDays') }),
         });
         emit(deps, flag(options, 'json'), outcome);
     });
-    program
+    keys
+        .command('list')
+        .description('list your API keys (the secrets are never shown again)')
+        .action(async (_options, command) => {
+        const options = command.optsWithGlobals();
+        emit(deps, flag(options, 'json'), await keysList(deps, { apiUrl: resolveApiUrl(deps, text(options, 'apiUrl')) }));
+    });
+    keys
+        .command('revoke')
+        .description('revoke an API key at once')
+        .argument('<keyId>', 'the key id that `keys list` prints')
+        .action(async (keyId, _options, command) => {
+        const options = command.optsWithGlobals();
+        emit(deps, flag(options, 'json'), await keysRevoke(deps, { apiUrl: resolveApiUrl(deps, text(options, 'apiUrl')), keyId }));
+    });
+    const sessions = program.command('sessions').description("deposit and recall your own coding-agent session logs, locally (these commands make no model call and no network call, except `gold arms`, which asks your own Claude subscription; telemetry is separate: oars telemetry)");
+    sessions
+        .command('deposit')
+        .description('read session logs into the local observation log, from every folder unless --allow names some or --deny keeps some out; idempotent. Subagent transcripts under each session (<project>/<session>/subagents/) are deposited with their parent, and each raw transcript is hard-linked or copied into the oars archive beside the store')
+        .option('--allow <folder>', 'a project folder to read: its path, or its name under ~/.claude/projects (repeatable); `cursor`, `codex`, `copilot`, `gemini`, `grok`, `opencode`, `pi`, `vscode-copilot`, and `otel` name the Cursor, Codex, Copilot CLI, Gemini CLI, Grok Build, OpenCode, Pi, VS Code Copilot Chat, and OpenTelemetry GenAI trace stores. A trailing slash names everything under a folder; * and ? are wildcards', collect)
+        .option('--allow-file <list>', 'a file of --allow entries, one per line (# starts a comment, and !<entry> keeps a folder out); repeatable, combines with --allow', collect)
+        .option('--deny <folder>', 'a folder never to read, in any form --allow takes (repeatable); saved, and it wins over every --allow until that exact entry is named with --allow', collect)
+        .option('--redact-domain <domain>', 'an organization domain to mask in everything written (repeatable)', collect)
+        .action(async (_options, command) => {
+        const options = command.optsWithGlobals();
+        emit(deps, flag(options, 'json'), await sessionsDeposit(sessionDeps(deps), { allow: list(options, 'allow'), allowFiles: list(options, 'allowFile'), deny: list(options, 'deny'), redactDomains: list(options, 'redactDomain') }));
+    });
+    sessions
+        .command('recall')
+        .description('look a tool error, a file, or a prompt class up in the store (--mcp serves the same query to a running agent). Note: an error pasted with a leading <tool_use_error> line does not match a stored signature, because the extractor keeps that markup line as the signature (reference-script behavior); paste the line below it')
+        .option('--error <text>', 'an error as printed; matched by its normalized signature')
+        .option('--path <file>', 'a file path or name that earlier sessions touched')
+        .option('--class <name>', 'a prompt class (edit-verify, edit-only, shell-only, research, orchestration, explore-only, mixed, no-tools)')
+        .option('--since <days>', 'only the last N days', positiveInteger)
+        .option('--pattern <id>', 'what happened from here: a read ID for a step so far (repeatable)', collect)
+        .option('--entity <name>', 'what is known about a public name: a package, a tool, an MCP server, an action, or a model')
+        .option('--family <name>', `one read family (${RECALL_FAMILIES.join(', ')}); only recovery and fit are narrowed by --class and --since`)
+        .option('--text <text>', 'look for text in the local record')
+        .option('--session <id>', 'the session asking, so what it did next can be read for this recall')
+        .option('--counts', 'print counts of recalls by mode, arm, and answer, with what followed, instead of answering (see --day)')
+        .option('--day <yyyy-mm-dd>', 'with --counts: only this UTC day')
+        .option('--mcp', 'serve one recall tool over MCP on stdio instead of answering once')
+        .option('--context', "print the repository's top recurring errors as a short block for injection into a session (see --cwd, --harness, --top, --max-chars)")
+        .option('--cwd <dir>', "with --context: the session's working directory (default: this one)")
+        .option('--harness <version>', 'with --context: only errors seen under this Claude Code version')
+        .option('--top <n>', 'with --context: how many signatures (default 5)', positiveInteger)
+        .option('--max-chars <n>', "with --context: the block's length limit (default 1200)", positiveInteger)
+        .action(async (_options, command) => {
+        const options = command.optsWithGlobals();
+        if (flag(options, 'counts')) {
+            emit(deps, flag(options, 'json'), await sessionsRecallCounts(sessionDeps(deps), text(options, 'day')));
+            return;
+        }
+        if (flag(options, 'context')) {
+            emit(deps, flag(options, 'json'), await sessionsContext(sessionDeps(deps), {
+                cwd: text(options, 'cwd') ?? process.cwd(),
+                ...(text(options, 'harness') === undefined ? {} : { harness: text(options, 'harness') }),
+                top: count(options, 'top') ?? 5,
+                maxChars: count(options, 'maxChars') ?? 1200,
+            }));
+            return;
+        }
+        if (flag(options, 'mcp')) {
+            await sessionsMcp(sessionDeps(deps));
+            return;
+        }
+        const session = text(options, 'session') ?? null;
+        const conflict = formsRefusal([
+            ...(list(options, 'pattern').length > 0 ? ['prefix'] : []),
+            ...(text(options, 'entity') === undefined ? [] : ['entity']),
+            ...(text(options, 'family') === undefined ? [] : ['family']),
+            ...(text(options, 'text') === undefined ? [] : ['text']),
+            ...(text(options, 'error') === undefined && text(options, 'path') === undefined ? [] : ['error or path']),
+        ]);
+        if (conflict !== undefined)
+            throw new CliError(conflict, ExitCode.USAGE, 'usage');
+        const closed = closedQueryOf({ pattern: list(options, 'pattern'), entity: text(options, 'entity'), family: text(options, 'family'), text: text(options, 'text'), cls: text(options, 'class'), sinceDays: count(options, 'since') });
+        if (closed !== undefined) {
+            emit(deps, flag(options, 'json'), await sessionsRecall(sessionDeps(deps), closed, session));
+            return;
+        }
+        const query = {
+            ...(text(options, 'error') === undefined ? {} : { error: text(options, 'error') }),
+            ...(text(options, 'path') === undefined ? {} : { path: text(options, 'path') }),
+            ...(text(options, 'class') === undefined ? {} : { cls: text(options, 'class') }),
+            ...(count(options, 'since') === undefined ? {} : { sinceDays: count(options, 'since') }),
+        };
+        emit(deps, flag(options, 'json'), await sessionsRecall(sessionDeps(deps), query, session));
+    });
+    sessions
+        .command('lineage <id>')
+        .description('walk a recall or read back through its evidence, one line per hop with its frame range and day; refuses evidence newer than the recall')
+        .action(async (id, _options, command) => {
+        emit(deps, flag(command.optsWithGlobals(), 'json'), await sessionsLineage(sessionDeps(deps), id));
+    });
+    sessions
+        .command('read')
+        .description('derived reads of your own sessions at every order, each row stating its order and clusters: rates at order 1, relations between them at order 2, one labeled experiment at order 3, and what this store cannot read')
+        .option('--family <name>', `only this family: ${FAMILIES.join(', ')}`)
+        .option('--slice <axis=value>', 'only reads holding this value on this axis, such as model=claude-opus-5-5 (repeatable; all must match)', collect)
+        .action(async (_options, command) => {
+        const options = command.optsWithGlobals();
+        emit(deps, flag(options, 'json'), await sessionsRead(sessionDeps(deps), { family: text(options, 'family'), slices: list(options, 'slice') }));
+    });
+    sessions
+        .command('books')
+        .description('tokens, wall time, turns, errors, verify-after-edit rate, and the outcome signals (verify passed, stops, redos, commits, and commit survival) per prompt class, model, harness, or pull; with --by package, the public-package counts a field report prints, exclusions applied')
+        .option('--by <key>', 'class, model, harness, pull, or package (default class)', (value) => {
+        if (value !== 'class' && value !== 'model' && value !== 'harness' && value !== 'pull' && value !== 'package')
+            throw new InvalidArgumentError('it must be class, model, harness, pull, or package.');
+        return value;
+    })
+        .option('--since <days>', 'only the last N days', positiveInteger)
+        .option('--repo <root>', "count only this repository's sessions (worktrees and subfolders included); without it, the whole store")
+        .action(async (_options, command) => {
+        const options = command.optsWithGlobals();
+        const picked = text(options, 'by');
+        const by = picked === 'model' || picked === 'harness' || picked === 'pull' || picked === 'package' ? picked : 'class';
+        const termsFile = deps.sessions === undefined ? undefined : exclusionPaths(deps.sessions.projectsRoot, deps.env).terms;
+        emit(deps, flag(options, 'json'), await sessionsBooks(sessionDeps(deps), { by, sinceDays: count(options, 'since'), repo: text(options, 'repo'), termsFile }));
+    });
+    sessions
+        .command('measure')
+        .description('the G1 signals for the last N sessions and the N before, and the pipeline step counters over the whole log')
+        .option('--last <n>', 'sessions per window (default 50)', positiveInteger)
+        .option('--since <iso>', 'pin the current window to the first N sessions started at or after this ISO time (the prior window is the N before it); without it the window is the last N and moves with every deposit', isoTime)
+        .option('--repo <root>', "count only this repository's sessions (worktrees and subfolders included); without it, the whole store")
+        .action(async (_options, command) => {
+        const options = command.optsWithGlobals();
+        emit(deps, flag(options, 'json'), await sessionsMeasure(sessionDeps(deps), { last: count(options, 'last') ?? 50, since: text(options, 'since'), repo: text(options, 'repo') }));
+    });
+    sessions
+        .command('verify')
+        .description('run the consistency invariants on the stored skeletons and capture records, report every session on its own, and audit each against its raw file (Merkle root, counts)')
+        .option('--session <id>', 'one session instead of all')
+        .option('--strict', 'exit non-zero (4) when any invariant has exceptions, a step is stuck, or the raw audit finds a root mismatch or counts that do not bind; by default FAIL lines still exit 0')
+        .action(async (_options, command) => {
+        const options = command.optsWithGlobals();
+        const { failed, report, ...outcome } = await sessionsVerify(sessionDeps(deps), { session: text(options, 'session') });
+        const json = flag(options, 'json');
+        if (flag(options, 'strict') && failed.length > 0) {
+            // One document under --json: the failure carries the invariants, so the success document is not printed first.
+            if (!json)
+                emit(deps, json, outcome);
+            throw new CliError(`${String(failed.length)} ${failed.length === 1 ? 'check' : 'checks'} failed: ${failed.join('; ')}`, ExitCode.INVALID, 'verify', undefined, json ? report : undefined);
+        }
+        emit(deps, json, outcome);
+    });
+    sessions
+        .command('exclusions')
+        .description('scan the local store and transcripts under the exclusion rule, write the excluded sessions to a local file, and print counts only (the term file is named by OARS_EXCLUSION_TERMS)')
+        .option('--out <file>', 'where to write the excluded sessions (default: session-commons/exclusion-list.jsonl beside the claude projects folder)')
+        .action(async (_options, command) => {
+        const options = command.optsWithGlobals();
+        if (deps.sessions === undefined)
+            throw new CliError('The session store is not configured in this run.', ExitCode.UNEXPECTED, 'unexpected');
+        emit(deps, flag(options, 'json'), await sessionsExclusions(deps.sessions, exclusionPaths(deps.sessions.projectsRoot, deps.env, text(options, 'out'))));
+    });
+    const gold = sessions.command('gold').description('a blind, human-judged sample of prompts, and every signal scored against those judgments');
+    gold
+        .command('sample')
+        .description('write about 200 prompts in batches to judge blind, across prompt classes and models, with the signals in a hidden sidecar; it never overwrites a file')
+        .option('--size <n>', 'prompts to draw (default 200)', positiveInteger)
+        .option('--batch <n>', 'prompts per batch (default 50)', positiveInteger)
+        .option('--seed <text>', "the draw's seed (default today's date)")
+        .option('--exclude-term <text>', 'also leave out any session that mentions this, in any case, beyond the local term file (OARS_EXCLUSION_TERMS) that always applies (repeatable)', collect)
+        .option('--out-dir <folder>', 'where to write (default <claude config>/session-commons/review)')
+        .action(async (_options, command) => {
+        const options = command.optsWithGlobals();
+        if (deps.sessions === undefined)
+            throw new CliError('The session store is not configured in this run.', ExitCode.UNEXPECTED, 'unexpected');
+        emit(deps, flag(options, 'json'), await sessionsGoldSample(sessionDeps(deps), {
+            termsFile: exclusionPaths(deps.sessions.projectsRoot, deps.env).terms,
+            size: count(options, 'size') ?? 200,
+            batch: count(options, 'batch') ?? 50,
+            seed: text(options, 'seed'),
+            excludeTerms: list(options, 'excludeTerm'),
+            outDir: text(options, 'outDir'),
+        }));
+    });
+    gold
+        .command('score')
+        .description('per signal and per model, the AUROC with its 95% interval and the base rate, from whatever is judged so far')
+        .argument('<file>', 'the gold file')
+        .action(async (file, _options, command) => {
+        const options = command.optsWithGlobals();
+        emit(deps, flag(options, 'json'), await sessionsGoldScore({ file }));
+    });
+    gold
+        .command('arms')
+        .description('fill the hidden sidecar: the closing claim, its Confidence line, and fresh single-turn readers on your Claude subscription, with fixed, hashed wording. It resumes, and never touches the gold file')
+        .argument('<file>', 'the gold file')
+        .action(async (file, _options, command) => {
+        const options = command.optsWithGlobals();
+        emit(deps, flag(options, 'json'), await sessionsGoldArms(sessionDeps(deps), { file }));
+    });
+    const hook = sessions.command('hook').description('install the recall hooks into a Claude Code settings file, and the nightly deposit task');
+    const scopeOption = (value) => {
+        if (value !== 'user' && value !== 'project' && value !== 'file')
+            throw new InvalidArgumentError('it must be user, project, or file.');
+        return value;
+    };
+    const scopeOf = (options) => {
+        const value = text(options, 'scope');
+        return value === 'user' || value === 'project' || value === 'file' ? value : undefined;
+    };
+    hook
+        .command('install')
+        .description('merge the SessionStart, UserPromptSubmit, PreToolUse, PostToolUseFailure, and SessionEnd hooks into a settings file (existing hooks are kept), raise cleanupPeriodDays to at least 365, and on Windows register the nightly task (which sends telemetry while telemetry is on, and pool batches only after you accept a pool covenant)')
+        .option('--scope <scope>', 'user (~/.claude/settings.json; the default), project (./.claude/settings.json), or file (needs --file; implied by --file)', scopeOption)
+        .option('--file <path>', 'the settings file for --scope file')
+        .option('--keep-retention', 'leave cleanupPeriodDays as it is (the harness deletes raw transcripts older than it)')
+        .option('--schedule <mode>', 'nightly: register a Windows task that runs the full deposit and the recurrence refresh daily (a plain install on Windows does this too); off: remove it', (value) => {
+        if (value !== 'nightly' && value !== 'off')
+            throw new InvalidArgumentError('it must be nightly or off.');
+        return value;
+    })
+        .action(async (_options, command) => {
+        const options = command.optsWithGlobals();
+        const schedule = text(options, 'schedule');
+        emit(deps, flag(options, 'json'), await sessionsHookInstall(sessionDeps(deps), {
+            scope: scopeOf(options),
+            file: text(options, 'file'),
+            keepRetention: flag(options, 'keepRetention'),
+            schedule: schedule === 'nightly' || schedule === 'off' ? schedule : undefined,
+        }));
+    });
+    hook
+        .command('uninstall')
+        .description('remove only the hooks `install` wrote from a settings file (cleanupPeriodDays stays; `install --schedule off` removes the task)')
+        .option('--scope <scope>', 'user (the default), project, or file (needs --file; implied by --file)', scopeOption)
+        .option('--file <path>', 'the settings file for --scope file')
+        .action(async (_options, command) => {
+        const options = command.optsWithGlobals();
+        emit(deps, flag(options, 'json'), await sessionsHookUninstall(sessionDeps(deps), { scope: scopeOf(options), file: text(options, 'file') }));
+    });
+    hook
         .command('status')
-        .description('show a workload and its billing mode')
-        .argument('<workloadId>', 'the workload id')
-        .action(async (workloadId, _options, command) => {
+        .description('what is installed in the user and project settings (and --file), and whether the nightly task is registered')
+        .option('--file <path>', 'one more settings file to report')
+        .action(async (_options, command) => {
         const options = command.optsWithGlobals();
-        emit(deps, flag(options, 'json'), await status(deps, { apiUrl: resolveApiUrl(deps, text(options, 'apiUrl')), workloadId }));
+        emit(deps, flag(options, 'json'), await sessionsHookStatus(sessionDeps(deps), { file: text(options, 'file') }));
     });
-    program
-        .command('test-charge')
-        .description("make a TEST-mode charge against one of a workload's prices")
-        .argument('<workloadId>', 'the workload id')
-        .option('--price <ref>', "the price to charge (default: the workload's only active price)")
-        .action(async (workloadId, _options, command) => {
+    const gate = program.command('gate').description('record the install, fetch-and-run, MCP, and skill picks your agents make, live through a hook or from logs already on disk, without judging them');
+    gate
+        .command('replay')
+        .description('find the crossings in your session logs and write them to crossings.jsonl in the sessions store; reads nothing outside the allowlist, and asks the package manager what the registry holds unless --no-registry-state')
+        .option('--allow <folder>', 'a project folder to read, as for `oars sessions deposit` (repeatable); default: the allowlist a deposit saved, else every folder', collect)
+        .option('--no-registry-state', 'do not ask the package manager what the registry holds for each package named (npm view, pip index versions; asked by default, as the live hook does, and the manager keeps its own cache)')
+        .action(async (_options, command) => {
         const options = command.optsWithGlobals();
-        const outcome = await testCharge(deps, {
-            apiUrl: resolveApiUrl(deps, text(options, 'apiUrl')),
-            workloadId,
-            priceRef: text(options, 'price'),
-            idempotencyKey: text(options, 'idempotencyKey') ?? randomUUID(),
-        });
-        emit(deps, flag(options, 'json'), outcome);
+        emit(deps, flag(options, 'json'), await gateReplay(sessionDeps(deps), { allow: list(options, 'allow'), ...(flag(options, 'registryState') ? { registry: managerReader() } : {}) }));
+    });
+    gate
+        .command('hook')
+        .description('the PreToolUse hook: reads the tool call on stdin, records any crossing in crossings.jsonl, and prints nothing unless the gate policy says to: a note as context, or a deny labeled with the fact for a name the registry does not hold; it never allows or changes a call (bin.js answers this command itself, before the rest of the CLI loads)')
+        .action(async () => {
+        const runtime = sessionDeps(deps).sessions;
+        // No store means no file: an empty store folder would put crossings.jsonl in the working folder.
+        if (runtime === undefined)
+            return;
+        let stdin = '';
+        for await (const chunk of runtime.stdin)
+            stdin += String(chunk);
+        const output = await gateHook(stdin, { storeDir: runtime.storeDir, now: deps.now, clock: () => performance.now(), deadlineMs: DEADLINE_MS });
+        if (output !== '')
+            deps.io.stdout(output);
+    });
+    gate
+        .command('install')
+        .description('wire the gate hook into Claude Code at user scope (PreToolUse for Bash, PowerShell, Skill, and MCP tools); rerunning changes nothing, and every other setting and hook is kept')
+        .action(async (_options, command) => {
+        emit(deps, flag(command.optsWithGlobals(), 'json'), await gateInstall(sessionDeps(deps)));
+    });
+    gate
+        .command('uninstall')
+        .description('remove only the gate hook `install` wrote from the user settings; crossings.jsonl stays')
+        .action(async (_options, command) => {
+        emit(deps, flag(command.optsWithGlobals(), 'json'), await gateUninstall(sessionDeps(deps)));
+    });
+    gate
+        .command('policy')
+        .description('print the gate policy in force: per class warn, block, or off, the day count for a young name, and the holdback share; read from gate-policy.json in the sessions store, whose absence or damage means the defaults')
+        .action(async (_options, command) => {
+        emit(deps, flag(command.optsWithGlobals(), 'json'), await gatePolicy(sessionDeps(deps)));
+    });
+    gate
+        .command('report')
+        .description('count the crossings in crossings.jsonl, by who recorded them, and say what replay cannot see')
+        .action(async (_options, command) => {
+        emit(deps, flag(command.optsWithGlobals(), 'json'), await gateReport(sessionDeps(deps)));
+    });
+    const pool = program.command('pool').description('sign in to a pool server, deposit session skeletons (a closed list of fields, each value redacted first) and, after a yes to the raw prompt, redacted raw copies, and fetch signed reads; local capture, recall, and reads need none of it');
+    const serverOption = '--server <url>';
+    const serverHelp = 'the pool server, https or plain http to localhost (default: OARS_POOL_URL, else https://pool.manyoars.com)';
+    pool
+        .command('login')
+        .description('sign in by GitHub or Google device flow, run here against the provider; prints each request before sending it, and the pool keeps a pseudonym; no harness token is read')
+        .requiredOption('--provider <name>', 'github or google')
+        .option(serverOption, serverHelp)
+        .action(async (_options, command) => {
+        const options = command.optsWithGlobals();
+        emit(deps, flag(options, 'json'), await poolLogin(deps, { server: text(options, 'server'), provider: text(options, 'provider') }));
+    });
+    pool
+        .command('deposit')
+        .description('write a batch to the outbox for each session that passes the folder allowlist and the exclusion check, and stop: nothing is sent, and only counts print. --send <hash> sends one batch that oars pool outbox printed and that is unchanged, once this account has accepted the pool covenant')
+        .option('--accept-covenant <version>', 'accept this version of the pool covenant before sending (with --send)')
+        .option('--send <hash>', 'the SHA-256 of a batch that oars pool outbox printed')
+        .option(serverOption, serverHelp)
+        .action(async (_options, command) => {
+        const options = command.optsWithGlobals();
+        emit(deps, flag(options, 'json'), await poolDeposit(deps, { server: text(options, 'server'), acceptCovenant: text(options, 'acceptCovenant'), send: text(options, 'send') }));
+    });
+    pool
+        .command('raw')
+        .description('the raw prompt: whether a redacted copy of each full transcript may leave besides its skeleton (--consent yes|no), and what one folder may send (--folder <folder> --mode all|skeleton|off); with no option, shows the prompt and your answer')
+        .option('--consent <answer>', 'yes or no; a no, or no answer, sends skeletons only')
+        .option('--folder <entry>', 'a folder, folder prefix, or glob, as --allow takes it')
+        .option('--mode <mode>', 'all, skeleton, or off for that folder: on by default after you accept; skeleton sends no raw; off sends nothing from that folder to the pool from now on')
+        .action(async (_options, command) => {
+        const options = command.optsWithGlobals();
+        emit(deps, flag(options, 'json'), await poolRaw(deps, { consent: text(options, 'consent'), folder: text(options, 'folder'), mode: text(options, 'mode') }));
+    });
+    pool
+        .command('coverage')
+        .description('state whom your deposits cover, kept on this machine and never looked up: --org-size solo, 2-10, 11-100, 101-1000, over-1000, or unknown; --repo-visibility public, private, or unknown. With no flag it prints what is set')
+        .option('--org-size <band>', 'how many people your organization has')
+        .option('--repo-visibility <visibility>', 'whether your repositories are public or private')
+        .action(async (_options, command) => {
+        const options = command.optsWithGlobals();
+        emit(deps, flag(options, 'json'), await poolCoverage(deps, { orgSize: text(options, 'orgSize'), repoVisibility: text(options, 'repoVisibility') }));
+    });
+    pool
+        .command('outbox')
+        .description('print every batch exactly as it would be sent, request line and headers included, with the credential as its size; prints each batch SHA-256 and records that it was shown')
+        .option('--explain', 'print each field of a batch with the rule that admits its values')
+        .option(serverOption, serverHelp)
+        .action(async (_options, command) => {
+        const options = command.optsWithGlobals();
+        emit(deps, flag(options, 'json'), await poolOutbox(deps, { server: text(options, 'server'), explain: flag(options, 'explain') }));
+    });
+    pool
+        .command('fetch')
+        .description('fetch the signed bundle for one harness version, verify it against the key pinned at login, and keep it locally')
+        .option('--harness <name>', 'the harness whose bundle to fetch (default: the one your local store holds the most sessions of, claude-code when none leads)')
+        .requiredOption('--harness-version <version>', 'the public harness version whose bundle to fetch, or unknown for a session that recorded none (Cursor, Gemini, Grok Build, Pi, or a VS Code Copilot Chat session whose requests name no agent version; there is no bundle for otel)')
+        .option(serverOption, serverHelp)
+        .action(async (_options, command) => {
+        const options = command.optsWithGlobals();
+        emit(deps, flag(options, 'json'), await poolFetch(deps, { server: text(options, 'server'), harness: text(options, 'harness'), harnessVersion: text(options, 'harnessVersion') ?? '' }));
+    });
+    const telemetry = program.command('telemetry').description('what oars records about its own use, on this machine (docs/telemetry.md): status, on, off, show, and report');
+    const telemetryJson = (command) => flag(command.optsWithGlobals(), 'json');
+    telemetry
+        .command('status')
+        .description('whether telemetry is on, which switch decided it, whether the notice was shown, and the size of the spool')
+        .action((_options, command) => {
+        emit(deps, telemetryJson(command), telemetryStatus(deps));
+    });
+    telemetry
+        .command('on')
+        .description('turn telemetry on, and print what it records (OARS_TELEMETRY=0 and DO_NOT_TRACK=1 still win)')
+        .action((_options, command) => {
+        emit(deps, telemetryJson(command), telemetryOn(deps));
+    });
+    telemetry
+        .command('off')
+        .description('turn telemetry off: nothing more is recorded or sent')
+        .action((_options, command) => {
+        emit(deps, telemetryJson(command), telemetryOff(deps));
+    });
+    telemetry
+        .command('show')
+        .description('print the spool exactly as stored: every event telemetry has kept, oldest first')
+        .action((_options, command) => {
+        emit(deps, telemetryJson(command), telemetryShow(deps));
+    });
+    telemetry
+        .command('report')
+        .description('your own hook latency, hit rates, and store health over the last 7 and 30 days, from the spool, beside the fleet\'s when OARS_POOL_URL names a pool server that answers')
+        .action(async (_options, command) => {
+        emit(deps, telemetryJson(command), await telemetryReport(deps));
     });
     return program;
 };
@@ -169,16 +508,18 @@ const asCliError = (error) => {
         return new CliError(error.message.replace(/^error: /, ''), ExitCode.USAGE, 'usage');
     return new CliError(`Unexpected error: ${error instanceof Error ? error.message : String(error)}`, ExitCode.UNEXPECTED, 'unexpected');
 };
-/** Runs one invocation (`argv` without the node and script entries) and returns the exit code. */
-export const run = async (argv, deps) => {
+const execute = async (argv, deps, observed) => {
     try {
-        await buildProgram(deps, argv).parseAsync(argv, { from: 'user' });
+        await buildProgram(deps, observed).parseAsync(argv, { from: 'user' });
         return ExitCode.OK;
     }
     catch (error) {
         // --help and --version end the parse through exitOverride with exit code 0; commander has already printed them.
         if (error instanceof CommanderError && error.exitCode === 0)
             return ExitCode.OK;
+        // A failure the program did not mean (not a CliError, not commander's own): its class and a hash of its stack are recorded, then it is handled as before.
+        if (!(error instanceof CliError) && !(error instanceof CommanderError))
+            recordCrash(deps, error);
         const failure = asCliError(error);
         // Commander wrote its own usage message to stderr; a CliError is ours to print.
         if (!(error instanceof CommanderError) || argv.includes('--json'))
@@ -186,3 +527,11 @@ export const run = async (argv, deps) => {
         return failure.exitCode;
     }
 };
+/** Runs one invocation (`argv` without the node and script entries) and returns the exit code. Telemetry records it afterward and cannot change it. */
+export const run = async (argv, deps) => {
+    const observed = { path: [], flags: [] };
+    const startedAt = deps.now();
+    const exit = await execute(argv, deps, observed);
+    finishTelemetry(deps, argv, observed, startedAt, exit);
+    return exit;
+};