@manyoars/oars 0.2.0 → 0.3.0

package/dist/cli.js

@@ -1,13 +1,18 @@
 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 { poolDeposit, poolFetch, poolLogin, poolOutbox } from './sessions/pool-command.js';
 const flag = (options, name) => options[name] === true;
 const text = (options, name) => {
     const value = options[name];
@@ -28,45 +33,38 @@ 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 });
+const buildProgram = (deps) => {
     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 Claude Code 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");
     program
         .command('login')
         .description('sign in with your browser (RFC 8628 device flow)')
@@ -88,77 +86,358 @@ 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 Claude Code session logs, locally (no model calls, no network, except `gold arms`, which asks your own Claude subscription)");
+    sessions
+        .command('deposit')
+        .description('read session logs from the folders you name into the local observation log; idempotent. Subagent transcripts under each session (<project>/<session>/subagents/) are deposited with their parent, and each raw transcript is hard-linked 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`, and `vscode-copilot` name the Cursor, Codex, Copilot CLI, Gemini CLI, Grok Build, and VS Code Copilot Chat 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); repeatable, combines 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'), 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')
+        .option('--by <key>', 'class, model, harness, or pull (default class)', (value) => {
+        if (value !== 'class' && value !== 'model' && value !== 'harness' && value !== 'pull')
+            throw new InvalidArgumentError('it must be class, model, harness, or pull.');
+        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 : 'class';
+        emit(deps, flag(options, 'json'), await sessionsBooks(sessionDeps(deps), { by, sinceDays: count(options, 'since'), repo: text(options, 'repo') }));
+    });
+    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, PostToolUseFailure, and SessionEnd hooks into a settings file (existing hooks are kept) and raise cleanupPeriodDays to at least 365')
+        .option('--scope <scope>', 'user (~/.claude/settings.json), project (./.claude/settings.json), or file (needs --file; the default)', 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; 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, project, or file (needs --file; the default)', 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 folders you name, and no network unless --registry-state')
+        .option('--allow <folder>', 'a project folder to read, as for `oars sessions deposit` (repeatable); default: the allowlist a deposit saved', collect)
+        .option('--registry-state', 'ask the package manager what the registry holds for each package named (npm view, pip index versions); off by default, 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 closed-vocabulary session skeletons, 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 (or OARS_POOL_URL; there is no default)';
+    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> runs the checks that a batch was printed and is unchanged, then stops: sending is disabled in this release')
+        .option('--accept-covenant <version>', 'accept this version of the pool covenant before sending (with --send, which is disabled in this release)')
+        .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('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')
+        .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') ?? '' }));
     });
     return program;
 };
@@ -172,7 +451,7 @@ const asCliError = (error) => {
 /** Runs one invocation (`argv` without the node and script entries) and returns the exit code. */
 export const run = async (argv, deps) => {
     try {
-        await buildProgram(deps, argv).parseAsync(argv, { from: 'user' });
+        await buildProgram(deps).parseAsync(argv, { from: 'user' });
         return ExitCode.OK;
     }
     catch (error) {

package/dist/commands/keys.d.ts

@@ -0,0 +1,31 @@
+import type { Outcome, RunDeps } from '../cli.js';
+/** One step's `Idempotency-Key`: the lowercase SHA-256 hex of `<base>:<step>`, the 64-hex form every platform interceptor accepts. */
+export declare const stepKey: (base: string, step: string) => string;
+/** The only authorities a key scoped to one workload may carry; the platform answers 400 API_KEY_WORKLOAD_SCOPE_EXCEEDS_CAP for more. */
+export declare const SCOPED_AUTHORITIES: string[];
+export interface KeysCreateOptions {
+    apiUrl: string;
+    name: string;
+    /** Scopes the key to this one workload; absent for an ordinary key. */
+    workloadId?: string;
+    authorities: string[];
+    expiresInDays?: number;
+    /** The base of the step key, so a retry of this command replays the same answer (and, by design, no secret). */
+    idempotencyKey: string;
+}
+export interface KeysListOptions {
+    apiUrl: string;
+}
+export interface KeysRevokeOptions {
+    apiUrl: string;
+    keyId: string;
+}
+/**
+ * `POST /me/api-keys`: with `--workload` the key works on that one workload only. The secret prints once, here; the platform never
+ * stores it, and a replay of the same request returns no secret.
+ */
+export declare const keysCreate: (deps: RunDeps, options: KeysCreateOptions) => Promise<Outcome>;
+/** `GET /me/api-keys`: the secrets never come back, only the prefix. */
+export declare const keysList: (deps: RunDeps, options: KeysListOptions) => Promise<Outcome>;
+/** `DELETE /me/api-keys/{keyId}`: a bodyless 204; the key stops working at once. */
+export declare const keysRevoke: (deps: RunDeps, options: KeysRevokeOptions) => Promise<Outcome>;

package/dist/commands/keys.js

@@ -0,0 +1,65 @@
+import { createHash } from 'node:crypto';
+import { apiClient, unwrap } from '../api.js';
+import { CliError, ExitCode } from '../errors.js';
+import { resolveAuthToken } from '../session.js';
+/** One step's `Idempotency-Key`: the lowercase SHA-256 hex of `<base>:<step>`, the 64-hex form every platform interceptor accepts. */
+export const stepKey = (base, step) => createHash('sha256').update(`${base}:${step}`).digest('hex');
+const CREATE_STEP = 'keys-create';
+const LIST_STEP = 'keys-list';
+const REVOKE_STEP = 'keys-revoke';
+// A developer's keys fit one request nearly always; the loop below only covers one that outgrows it.
+const PAGE_SIZE = 100;
+/** The only authorities a key scoped to one workload may carry; the platform answers 400 API_KEY_WORKLOAD_SCOPE_EXCEEDS_CAP for more. */
+export const SCOPED_AUTHORITIES = ['AGENT_OPERATE', 'AGENT_READ'];
+const describeKey = (key) => [
+    key.keyId,
+    key.name,
+    key.status,
+    `${key.prefix}...`,
+    key.workloadId === undefined ? 'all workloads' : `workload ${key.workloadId}`,
+    key.authorities.join(','),
+    key.expiresAt === undefined ? 'no expiry' : `expires ${key.expiresAt}`,
+].join('  ');
+/**
+ * `POST /me/api-keys`: with `--workload` the key works on that one workload only. The secret prints once, here; the platform never
+ * stores it, and a replay of the same request returns no secret.
+ */
+export const keysCreate = async (deps, options) => {
+    const client = apiClient(deps, { apiUrl: options.apiUrl, step: CREATE_STEP, token: await resolveAuthToken(deps, options.apiUrl) });
+    const issued = unwrap(CREATE_STEP, await client.POST('/me/api-keys', {
+        params: { header: { 'Idempotency-Key': stepKey(options.idempotencyKey, CREATE_STEP) } },
+        body: {
+            name: options.name,
+            authorities: options.authorities,
+            ...(options.workloadId === undefined ? {} : { workloadId: options.workloadId }),
+            ...(options.expiresInDays === undefined ? {} : { expiresInDays: options.expiresInDays }),
+        },
+    }));
+    if (issued.secret === undefined) {
+        throw new CliError(`Key ${issued.key.keyId} was already created and its secret was shown once; the platform keeps no copy. Revoke it and create another.`, ExitCode.CONFLICT, CREATE_STEP);
+    }
+    return {
+        document: { ok: true, key: issued.key, secret: issued.secret },
+        text: [`Created key: ${describeKey(issued.key)}.`, `Secret (shown once; save it now): ${issued.secret}`].join('\n'),
+    };
+};
+/** `GET /me/api-keys`: the secrets never come back, only the prefix. */
+export const keysList = async (deps, options) => {
+    const client = apiClient(deps, { apiUrl: options.apiUrl, step: LIST_STEP, token: await resolveAuthToken(deps, options.apiUrl) });
+    const keys = [];
+    for (let page = 0;; page += 1) {
+        const result = unwrap(LIST_STEP, await client.GET('/me/api-keys', { params: { query: { page, size: PAGE_SIZE } } }));
+        keys.push(...result.content);
+        if (result.last)
+            break;
+    }
+    return { document: { ok: true, keys }, text: keys.length === 0 ? 'You have no API keys.' : keys.map(describeKey).join('\n') };
+};
+/** `DELETE /me/api-keys/{keyId}`: a bodyless 204; the key stops working at once. */
+export const keysRevoke = async (deps, options) => {
+    const client = apiClient(deps, { apiUrl: options.apiUrl, step: REVOKE_STEP, token: await resolveAuthToken(deps, options.apiUrl) });
+    const { response, error } = await client.DELETE('/me/api-keys/{keyId}', { params: { path: { keyId: options.keyId } } });
+    if (!response.ok)
+        unwrap(REVOKE_STEP, { error, response });
+    return { document: { ok: true, keyId: options.keyId, revoked: true }, text: `Revoked key ${options.keyId}.` };
+};

package/dist/commands/login.js

@@ -1,12 +1,12 @@
 import { CliError, ExitCode } from '../errors.js';
-import { resolveIssuerUrl } from '../issuer.js';
+import { discoverIssuer, resolveIssuerUrl } from '../issuer.js';
 import { awaitDeviceTokens, discover, startDeviceAuthorization } from '../oidc.js';
 import { exchangeKeycloakToken } from '../session.js';
 const STEP = 'login';
 /** RFC 8628 device flow on Keycloak, then the exchange; stores the credentials. */
 export const login = async (deps, options) => {
     const issuerUrl = await resolveIssuerUrl(deps, options.issuerUrl);
-    const config = await discover(issuerUrl, { ...deps, step: STEP });
+    const config = await discoverIssuer(deps, options.issuerUrl, () => discover(issuerUrl, { ...deps, step: STEP }));
     const device = await startDeviceAuthorization(config, STEP);
     const url = device.verification_uri_complete ?? device.verification_uri;
     deps.io.stderr(`To sign in, open ${url}\nand confirm the code ${device.user_code}\n`);