@manyoars/oars 0.3.0 → 0.4.1

package/README.md

@@ -1,8 +1,8 @@
 # @manyoars/oars
 
-The `oars` command line for Many Oars: sign in, manage API keys, and keep a local memory of your own Claude Code sessions (`oars sessions`).
+The `oars` command line for Many Oars: sign in, manage API keys, and keep a local memory of your own coding-agent sessions (`oars sessions`).
 
-Accounts are not open yet; `oars login` says so until launch.
+Accounts are not open yet: `oars login` uses the Many Oars issuer by default, and until Many Oars sign-in at `login.manyoars.com` is deployed it exits 2 with an error that names `login.manyoars.com`.
 
 Node 24 or later. ESM only.
 
@@ -34,7 +34,7 @@ These flags work on every command:
 Signs in with your browser (RFC 8628 device flow) and stores the login.
 
 - `--no-browser` prints the link and code without opening a browser.
-- `--issuer-url <url>` is the Keycloak realm URL. The default is `OARS_ISSUER_URL`. With neither, `login` uses the built-in Many Oars issuer once Many Oars has launched, which it learns from `https://manyoars.com/.well-known/oars.json` (`{"launched": true}`). The flag only switches the built-in issuer on; it never supplies a URL. Before launch, or when the built-in issuer does not answer discovery, with no `--issuer-url` or `OARS_ISSUER_URL`, the command prints "Many Oars has not launched yet: pass --issuer-url or set OARS_ISSUER_URL." and exits 2.
+- `--issuer-url <url>` is the Keycloak realm URL. The default is `OARS_ISSUER_URL`. With neither, `login` uses the built-in Many Oars issuer, `https://login.manyoars.com/realms/aor`; nothing has to be switched on first. When the built-in issuer does not answer discovery (it may not be deployed yet), with no `--issuer-url` or `OARS_ISSUER_URL`, the command prints "Cannot reach Many Oars sign-in at login.manyoars.com (it may not be deployed yet). Pass --issuer-url or set OARS_ISSUER_URL to use another issuer." and exits 2.
 
 ### logout
 
@@ -44,24 +44,37 @@ Revokes the stored login and deletes it.
 
 `oars keys` manages the API keys of your account.
 
-- `oars keys create --name <name>` creates a key and prints its secret once; the platform keeps no copy. The default authorities are `AGENT_OPERATE` and `AGENT_READ`; `--authority <name>` (repeatable) sets others, and `--expires-in-days <n>` sets an expiry. A key expires after 90 days unless `--expires-in-days <n>` (at most 365) says otherwise; replace it before then.
+- `oars keys create --name <name>` creates a key and prints its secret once; the platform keeps no copy. The default authorities are `AGENT_OPERATE` and `AGENT_READ`; `--authority <name>` (repeatable) sets others, and `--expires-in-days <n>` sets an expiry. `--expires-in-days` takes 1 to 365; without it the platform sets the expiry, and `oars keys list` shows it. Replace a key before it expires.
 - `--workload <id>` limits the key to one workload you created. Such a key may carry only `AGENT_OPERATE` and `AGENT_READ` (more is a 400, `API_KEY_WORKLOAD_SCOPE_EXCEEDS_CAP`), and it works on that workload only.
 - A retry with the same `--idempotency-key` returns no secret: the command exits 5 and names the key, and you revoke it and create another.
 - Creating or revoking a key needs a signed-in person. With `OARS_API_KEY` set, any API key gets 403 `HUMAN_SESSION_REQUIRED` (exit 3) and logging in again does not help: unset it and use the `oars login` session.
 - `oars keys list` lists the keys with their prefix, scope, and expiry. A secret never comes back.
 - `oars keys revoke <keyId>` ends a key at once. There is no `rotate`: revoke the key and create another.
 
+### telemetry
+
+oars records how it is used, on this machine, and says so: on the first run that is not a hook it prints a notice on stderr, once. Each command leaves an event in a local spool under `<config>/oars/telemetry/`: the command path, the names of the flags given (never their values), the duration, the exit code, a closed error class, the oars version, the OS, and the time. So does each fire of a hook (the bare `oars gate hook` included, written after its answer is printed: which hook, how long, hit, miss, held, or error, the bytes it printed, and the harness name and version and the model name when the hook saw them), each recall (how it was asked and which read families it served, as counts), each deposit pass or sent batch (sessions counted, batches, bytes, and how many sessions each gate kept out, never which), and each fetch (an ETag hit, a cap hit). Five more kinds of event are recorded, each only counts, sizes, and closed words: once a night, a `store-health` snapshot of the session store (counts and sizes, and the lists of harness versions and model names it holds) and a `run-cost` event (time and peak memory); a `crash` event when oars fails in a way it did not plan for (the error's class and a hash of its stack, never its message); and, for each `oars pool deposit` pass, one `wire` event per harness (which fields its batches held and how many bytes each took) and, with `--send`, a `wire-send` event (the HTTP status, the pool's refusal code, and the size). Nothing else is recorded: no session content, prompt text, file path, URL, or argument. Every field of every event, with an example, is in [docs/telemetry.md](https://github.com/manyoars/oars/blob/main/docs/telemetry.md). oars sends the events in batches to the pool server in `OARS_POOL_URL` if you set one, else to the Many Oars pool (`https://pool.manyoars.com`), which is live. A per-install random id (not derived from your machine or account) is in each event.
+
+- `oars telemetry status` says whether it is on, which switch decided that, whether the notice was shown, and how large the spool is.
+- `oars telemetry off` stops recording and sending; `oars telemetry on` resumes it and prints the notice again.
+- `oars telemetry show` prints the spool exactly as stored, oldest first.
+- `oars telemetry report` prints your own numbers from the spool (hook latency percentiles, hit rates, and store health over the last 7 and 30 days) with no server and no account, and the fleet's percentile beside each when `OARS_POOL_URL` names a server that serves it.
+- `OARS_TELEMETRY=0` or `DO_NOT_TRACK=1` turns it off for the process, and wins over `oars telemetry on`.
+
+Every event type, with an example, is in [docs/telemetry.md](https://github.com/manyoars/oars/blob/main/docs/telemetry.md).
+
 ### sessions
 
-`oars sessions` keeps a local, deterministic memory of your own Claude Code sessions. oars makes no model call and no network call, except `gold arms`, which sends redacted text through your own Claude subscription.
+`oars sessions` keeps a local, deterministic memory of your own coding-agent sessions. The session commands make no model call and no network call, except `gold arms`, which sends redacted text through your own Claude subscription. oars also records telemetry events (a command's path, its flag names, how long it took, its exit code, and its error class, with a random install id, the oars version, the OS, and the time; never session content, prompts, paths, URLs, or argument values), which oars sends in batches to the pool server in `OARS_POOL_URL`, else to the Many Oars pool (live) ([what telemetry records and how to turn it off](https://github.com/manyoars/oars/blob/main/docs/telemetry.md)).
 
-What it captures: the Claude Code sessions in the folders you name with `--allow`, and, by name, the sessions of Cursor, Codex, Copilot CLI, Gemini CLI, Grok Build, and VS Code Copilot Chat (`--allow cursor`, `codex`, `copilot`, `gemini`, `grok`, `vscode-copilot`). Where it stores them: `<config>/oars/sessions/` on your machine (`<config>` is `%APPDATA%` on Windows, `$XDG_CONFIG_HOME` or `~/.config` elsewhere). The `raw/` folder in it is on by default and holds raw transcripts (a hard link or copy of each deposited one). Secret masking applies to the log, not to `raw/`: those files are unredacted and keep whatever the transcript held, secrets included. They stay on your machine and, apart from `gold arms`, nothing is uploaded. To remove them, see [Remove everything](#remove-everything).
+What it captures: by default, the sessions of every Claude Code project folder and the sessions of Cursor, Codex, Copilot CLI, Gemini CLI, Grok Build, OpenCode, Pi, and VS Code Copilot Chat, plus OpenTelemetry GenAI agent traces (OTLP JSON files) from the folder `OARS_OTEL_TRACES` names (else `<config>/oars/otel-traces`), when there is one. `--allow` narrows that to the folders and stores you name (`--allow cursor`, `codex`, `copilot`, `gemini`, `grok`, `opencode`, `pi`, `vscode-copilot`, `otel` name the stores), and `--deny` keeps one out. Where it stores them: `<config>/oars/sessions/` on your machine (`<config>` is `%APPDATA%` on Windows, `$XDG_CONFIG_HOME` or `~/.config` elsewhere). The `raw/` folder in it is on by default and holds raw transcripts (a hard link or copy of each deposited one). Secret masking applies to the log, not to `raw/`: those files are unredacted and keep whatever the transcript held, secrets included. They stay on your machine: apart from `gold arms`, no session command uploads them, telemetry carries nothing from them, and after a yes to the raw prompt (`oars pool raw`) and covenant acceptance, the nightly task uploads a redacted copy of each (never the file itself), except from a folder set to skeleton only or off. To remove them, see [Remove everything](#remove-everything).
 
-Apart from that, oars itself sends nothing; the hooks and the MCP tool add recall text to the running session, and your harness sends that to its model like any other context.
+Apart from that and telemetry (on by default, off with `oars telemetry off`, `OARS_TELEMETRY=0`, or `DO_NOT_TRACK=1`; it sends to the pool server in `OARS_POOL_URL`, else to the Many Oars pool at `pool.manyoars.com`, which is live), oars itself sends nothing, except what you opted into with a pool server: after you accept its covenant, the nightly task (registered on Windows only) sends closed-vocabulary session skeletons, and, only after a separate yes to the raw prompt, a locally redacted (best-effort) copy of each full transcript; `oars pool outbox` prints what is queued when you run it, but the nightly task builds new batches and sends them in the same run without printing them first, and a folder can be switched to skeleton only or off; the hooks and the MCP tool add recall text to the running session, and your harness sends that to its model like any other context.
 
 ```bash
-# Read the folders you name (a path, or its name under ~/.claude/projects). At least one --allow is required; there is no "all".
-oars sessions deposit --allow ~/work/app --allow ~/work/tools --redact-domain corp.example
+# Read every folder; or only the ones you name (a path, or its name under ~/.claude/projects); --deny keeps one out.
+oars sessions deposit --redact-domain corp.example
+oars sessions deposit --allow ~/work/app --allow ~/work/tools --deny ~/work/tools/secret
 
 # Look up an error as printed, a file, or a prompt class.
 oars sessions recall --error "unexpected EOF while looking for matching \`''"
@@ -83,7 +96,7 @@ oars sessions read --family lead-lag         # order 3: a labeled experiment beh
 oars sessions read --family fit --slice model=claude-opus-5-5 --json
 oars sessions books --by class --since 30   # tokens, wall time, turns, errors, verify-after-edit rate, and the outcome signals
 oars sessions books --by pull               # the same per package, MCP server, plugin, or skill a prompt pulled
-oars sessions books --by harness            # the same, grouped by Claude Code, Cursor, Codex, Copilot, Gemini, Grok Build, and VS Code Copilot Chat (deposit the others with --allow cursor, --allow codex, --allow copilot, --allow gemini, --allow grok, or --allow vscode-copilot)
+oars sessions books --by harness            # the same, grouped by Claude Code, Cursor, Codex, Copilot, Gemini, Grok Build, OpenCode, Pi, and VS Code Copilot Chat (deposit the others with --allow cursor, --allow codex, --allow copilot, --allow gemini, --allow grok, --allow opencode, --allow pi, --allow vscode-copilot, or --allow otel)
 oars sessions measure --last 50             # recurring errors per 100 sessions, cache-write per session, recall calls per session
 oars sessions measure --last 50 --repo <root>  # the same, for one repository's sessions
 oars sessions verify                        # consistency invariants on the stored skeletons and capture records
@@ -99,7 +112,7 @@ before a line is written (redaction runs on the full text, then the text is cut)
 text, never raw content. It keeps these text fields and no others: the first 300 characters of each prompt, the first informative line of a
 tool error (cut to 1,000 characters in the error-line record, 160 characters in a derived example), TLDR lines (400) and Confidence lines (120) from assistant text, WebSearch queries, fetched URLs, file
 paths, and git branch names (the last four have no length limit), all redacted first; plus the project folder slug (not redacted, so it
-carries your username and directory names; the log stays local), skill names, effort values, model names, harness versions, tool names (including MCP server names), a shell call's program and subcommand, and tool-input key names. A tool call's file target is a salted hash, never the path. Apart from `gold arms`, nothing is uploaded.
+carries your username and directory names; the log stays local), skill names, effort values, model names, harness versions, tool names (including MCP server names), a shell call's program and subcommand, and tool-input key names. A tool call's file target is a salted hash, never the path. Apart from `gold arms`, no `oars sessions` command uploads anything, and telemetry carries none of these fields; `oars pool` and the nightly task send skeletons that carry some of these names after redaction (skill, effort, model, harness version, tool, and MCP server names, a shell call's program, subcommand, and flag names, tool-input key names, a pulled package's name (and its version only when a public list holds it), and a web host (sent as it is after redaction; the pool hashes it on arrival), each after redaction; see `docs/pool.md`, "Wire field register").
 Subagent transcripts (`<project>/<session>/subagents/`) are deposited with their parent session and subagent type; `books --by class`
 shows their tokens as the `delegated` column, and their errors are in the signatures, `measure`, and recall under the session that
 spawned them, so per-session counts still count main sessions. Every deposited transcript is also
@@ -109,25 +122,26 @@ field, and a Merkle root over the raw lines) that `verify` checks; the skeleton
 per hundred sessions and, on a second line, the distinct recurring signatures in the window.
 #### Many folders: `--allow` prefixes, globs, and `--allow-file`
 
-An `--allow` entry is a folder (or its slug), a folder prefix with a trailing slash (`~/work/` reads that folder and every project under it), or a glob (`*` any run of characters, `?` one character, matched against the project-folder name Claude Code derives from the path). `--allow-file <list>` reads entries from a file, one per line (blank lines and `#` comments skipped), so hundreds of folders need no batching and no long command line. A leading `~` is expanded to your home folder, in a list file or quoted entry too. Both repeat and combine. Entries a deposit saves are what the SessionEnd hook and the nightly task reuse; a folder you have never named is never read.
+An `--allow` entry is a folder (or its slug), a folder prefix with a trailing slash (`~/work/` reads that folder and every project under it), or a glob (`*` any run of characters, `?` one character, matched against the project-folder name Claude Code derives from the path). `--allow-file <list>` reads entries from a file, one per line (blank lines and `#` comments skipped), so hundreds of folders need no batching and no long command line. A leading `~` is expanded to your home folder, in a list file or quoted entry too. Both repeat and combine. With neither, a deposit reads every folder. `--deny <entry>` (or `!<entry>` in a list file) keeps the folders it names out, in any of those forms; it is saved, and it wins over every `--allow` until that exact entry is named with `--allow` again. Naming it again lifts the denial and nothing else when the saved list names no folder (every folder stays in scope); when the saved list names folders, the entry joins them. Entries a deposit saves are what the SessionEnd hook, the nightly task, `oars pool deposit`, and `oars gate replay` reuse; with none saved, they read every folder. An `--allow-file` that names nothing is refused.
 
 #### Recall in a running session: hooks
 
-`oars sessions hook install` writes four entries into one Claude Code settings file. Each is a deterministic, local, fail-open call into the store (no model, no network); an error inside a hook exits 0 with no output, so a hook never blocks or fails a session.
+`oars sessions hook install` writes five entries into one Claude Code settings file. Each is a deterministic, local, fail-open call into the store (no model, no network); an error inside a hook exits 0 with no output, so a hook never blocks or fails a session.
 
-| Event | Does | Budget |
+| Event | Does | Timeout written at install |
 |---|---|---|
-| `SessionStart` | injects `oars sessions recall --context` for the session's cwd as additional context: the top 5 errors by sessions within the latest 300 sessions of the repository (the `measure --last 300 --repo` window) and what usually followed | under 500 ms |
-| `PreToolUse` (no matcher: every tool) | for a call whose tool and input key names match a shape the store has seen fail often enough, and at least twice as often as its action does, injects its counts as additional context, once per session and shape (the check reads the last 64 KB of the recall log, about 44 rows, so a very long session can be told again, and the arm redraws when the nightly index moves), and records the recall. 10 percent of those sessions and shapes are held back: a held arm records what it would have shown and injects nothing. Starts node per call | under 500 ms |
-| `PostToolUseFailure` (matcher `Bash\|PowerShell`) | for a failed tool call whose error starts with `Exit code N` normalizes the first informative line as `deposit` does and, on a hit, adds "seen in N sessions; what followed: X". A shell pre-filter in the registered command reads the event first and starts node only when it carries `Exit code` | pre-filter: shell builtins only, no node start; whole path under 1 s |
-| `SessionEnd` | deposits that one transcript (idempotent by size and mtime), only from a folder an earlier `--allow` named. Once per session: `Stop` fires after every turn and would append a new revision of the growing transcript each time. A session the harness ends without `SessionEnd` is picked up by the nightly deposit | under 5 s |
+| `SessionStart` | injects `oars sessions recall --context` for the session's cwd as additional context: the top 5 errors by sessions within the latest 300 sessions of the repository (the `measure --last 300 --repo` window) and what usually followed. Then, when any position qualifies, a table of the positions where earlier sessions split on the next step (a leading step at 20 to 80 percent of at least 20 observations; names and counts only, at most 600 bytes), from the kept pool bundle for the session's harness and version first and this store's pool second (the local half is derived over that harness and version bucket only, or over the harness's versions when the transcript states none). The table is one `recalls.jsonl` row and falls under the 10 percent holdback | under 500 ms |
+| `UserPromptSubmit` | the same table again, only when it differs from the one this session was last sent (shown or held), so an unchanged table costs a prompt nothing (the check reads the last 64 KB of the recall log, shared by every session, so in a long or parallel session the last table row can fall out of the window and an unchanged table is sent again) | under 500 ms |
+| `PreToolUse` (no matcher: every tool) | the gate hook's role: it fires after the call is decided, so it is a warning and does not claim to move the next step. For a call whose tool and input key names match a shape that fails at least half its calls (of at least 20 calls in at least 3 sessions), and at least twice as often as its action does, injects its counts as additional context, once per session and shape (the check reads the last 64 KB of the recall log, about 44 rows, so a very long session can be told again, and the arm redraws when the nightly index moves), and records the recall. 10 percent of those sessions and shapes are held back: a held arm records what it would have shown and injects nothing. Starts node per call | under 500 ms |
+| `PostToolUseFailure` (matcher: every tool the action table maps, and `mcp__.*`) | the recovery edge: for a failed call it reads what followed this failure (same action and error class) in the kept pool bundle, else in this store, and adds "after a failed X (code), the next step was Y xN". It stays silent when the top next step is the failed action again (a retry), when a local edge has fewer than 5 followed steps, and when nothing followed. A call the cells do not cover keeps the older line, "seen in N sessions; what followed: X", under the same holdback, silent on a strict retry lead. Every served or held line is a `recalls.jsonl` row; 10 percent of sessions are held. For Bash and PowerShell a shell pre-filter in the registered command reads the event first and starts node only when it carries `Exit code` | pre-filter: shell builtins only, no node start; whole path under 1 s |
+| `SessionEnd` | deposits that one transcript (idempotent by size and mtime), only from a folder the saved allowlist holds (every folder until a deposit names some, less any `--deny`). Once per session: `Stop` fires after every turn and would append a new revision of the growing transcript each time. A session the harness ends without `SessionEnd` is picked up by the nightly deposit | under 5 s |
 
-Claude Code fires `PostToolUse` on success only; a failed Bash call arrives as `PostToolUseFailure`, so that is the event registered. The pre-filter is a `read`, a `case`, and a `printf | node` in the shell the harness runs hooks in (Git Bash on Windows, where a fresh `node` alone costs 250 ms or more), so it needs no `findstr` and no extra dependency. Writers of the store (`SessionEnd`, the nightly run, `deposit`) take `store.lock`, so parallel sessions cannot lose each other's `state.json` entries; a lock older than ten minutes is broken.
+Claude Code fires `PostToolUse` on success only; a failed Bash call arrives as `PostToolUseFailure`, so that is the event registered. The pre-filter is a `read`, a `case`, and a `printf | node` in the shell the harness runs hooks in (Git Bash on Windows), so it needs no `findstr` and no extra dependency. Writers of the store (`SessionEnd`, the nightly run, `deposit`) take `store.lock`, so parallel sessions cannot lose each other's `state.json` entries; a lock older than ten minutes is broken.
 
 ```bash
-# Nothing is written unless you name the file (default --scope file), or say --scope user|project.
+# The default is the user settings file; --scope project or --file names another.
+oars sessions hook install                              # ~/.claude/settings.json (or $CLAUDE_CONFIG_DIR)
 oars sessions hook install --scope file --file ./.claude/settings.local.json
-oars sessions hook install --scope user                 # ~/.claude/settings.json (or $CLAUDE_CONFIG_DIR)
 oars sessions hook install --scope project              # ./.claude/settings.json
 oars sessions hook install --file my-settings.json --keep-retention
 oars sessions hook status                               # user, project, and the nightly task
@@ -138,7 +152,7 @@ Install merges: existing hooks (a Stop hook that rotates sessions, say) stay, ev
 
 #### Nightly schedule (Windows)
 
-`oars sessions hook install --schedule nightly` registers the Task Scheduler task `OarsSessionsNightly` (daily, 03:00) that runs the full deposit over the saved `--allow` and `--redact-domain` entries and refreshes the recurrence index the hooks read. `--schedule off` removes it; `hook status` shows whether it is registered. Alone, `--schedule` writes no settings file.
+On Windows, `oars sessions hook install` registers the Task Scheduler task `OarsSessionsNightly` (daily, 03:00) unless it is already there; `--schedule nightly` registers it by itself, with no settings file. The task runs the full deposit over the saved `--allow` and `--redact-domain` entries and refreshes the recurrence index the hooks read. `--schedule off` removes it and records the choice in the store (`<config>/oars/sessions/schedule.json`), so a later plain install leaves it off until `--schedule nightly` registers it again and clears the record; `hook status` shows whether it is registered. A machine that refuses the task still gets the hooks, and the install says how to retry. Alone, `--schedule` writes no settings file.
 
 #### Reading `measure` before and after
 
@@ -146,30 +160,31 @@ Install merges: existing hooks (a Stop hook that rotates sessions, say) stay, ev
 
 #### Remove everything
 
-`oars sessions hook uninstall --scope user` (or the scope you installed); `oars sessions hook install --schedule off`; delete the store folder `<config>/oars/sessions/` (observations, skeletons, state, the hook index, `hook-calls.jsonl`, and `raw/`, which holds the unredacted transcripts). `gold sample` also writes its prompt file and sidecar to `~/.claude/session-commons/review/` (or `$CLAUDE_CONFIG_DIR/session-commons/review/`, or your `--out-dir`); delete those too. Nothing else is created. `cleanupPeriodDays` stays at the value install set unless you change it.
+`oars sessions hook uninstall --scope user` (or the scope you installed); `oars sessions hook install --schedule off`; delete the store folder `<config>/oars/sessions/` (observations, skeletons, state, the hook index, `hook-calls.jsonl`, and `raw/`, which holds the unredacted transcripts). `gold sample` also writes its prompt file and sidecar to `~/.claude/session-commons/review/` (or `$CLAUDE_CONFIG_DIR/session-commons/review/`, or your `--out-dir`); delete those too. oars also writes `<config>/oars/telemetry/` (the telemetry spool and install id; delete it too) and, after `oars login`, `<config>/oars/credentials.json` (`oars logout` deletes it). `cleanupPeriodDays` stays at the value install set unless you change it.
 
 ### Gate: what your agents picked
 
 ```
-oars gate replay --allow ~/work/app    # find installs, fetch-and-runs, MCP servers, and skills in logs on disk
-oars gate replay --registry-state      # also ask npm or pip what the registry holds (off by default)
+oars gate replay                       # find installs, fetch-and-runs, MCP servers, and skills in logs on disk, and ask npm or pip what the registry holds
+oars gate replay --no-registry-state   # the same, without asking the registry
 oars gate report                       # counts over crossings.jsonl, by who recorded each, and what replay cannot see
 oars gate install                      # add the hook to Claude Code at user scope, so crossings are recorded as they happen
 oars gate uninstall                    # remove only that hook entry
 oars gate policy                       # print the policy in force (warn, block, or off per class)
 ```
 
-Replay is local and read-only on your transcripts; it writes `crossings.jsonl` and the novelty index `gate-index.txt` into the sessions store and nothing else (with `--registry-state`, npm and pip also keep their own caches). The hook (`oars gate hook`, run by Claude Code, not by you) appends to `crossings.jsonl` as each crossing happens, plus `gate-index.txt`, `gate-registry.jsonl`, and the empty `gate-ask-*.lock` files in the same store (a registry ask the hook had to cut is finished by a helper process that ends on its own timeouts, and the package manager keeps its own cache outside the store), and always exits 0. With no policy file it adds a note about a name first published in the last 30 days or an npm name the registry does not hold; `gate-policy.json` changes that per class, and a block needs `block` written by you. A block is a labeled deny, and a crossing goes nowhere unless you opt in (no opt-in exists yet). `report` reads only `crossings.jsonl`. Both record picks and neither judges them; a note or label states a fact about the registry and nothing else. See `docs/gate.md` in the repository.
+Replay is local and read-only on your transcripts; it writes `crossings.jsonl` and the novelty index `gate-index.txt` into the sessions store and nothing else (npm and pip also keep their own caches, unless `--no-registry-state`). The hook (`oars gate hook`, run by Claude Code, not by you) appends to `crossings.jsonl` as each crossing happens, plus `gate-index.txt`, `gate-registry.jsonl`, and the empty `gate-ask-*.lock` files in the same store (a registry ask the hook had to cut is finished by a helper process that ends on its own timeouts, and the package manager keeps its own cache outside the store), and always exits 0. With no policy file it adds a note about a name first published in the last 30 days or an npm name the registry does not hold; `gate-policy.json` changes that per class, and a block needs `block` written by you. A block is a labeled deny, and a crossing goes nowhere unless you opt in (no opt-in exists yet). `report` reads only `crossings.jsonl`. Both record picks and neither judges them; a note or label states a fact about the registry and nothing else. See `docs/gate.md` in the repository.
 
 ### pool
 
-`oars pool` talks to a pool server that you name with `--server <url>` or `OARS_POOL_URL`; there is no default server. Every other command works without it.
+`oars pool` uses the Many Oars pool, `https://pool.manyoars.com`, which is live (deposits there are closed until its covenant is published), or a pool server you name with `--server <url>` or `OARS_POOL_URL`. Every other command works without it.
 
 - `oars pool login --provider github|google` signs in by the provider's device flow, run here, and prints every request before it sends it. `OARS_GITHUB_CLIENT_ID` (or `OARS_GOOGLE_CLIENT_ID` and `OARS_GOOGLE_CLIENT_SECRET`) must be set; an unset one stops the command before anything is sent and names the variable.
-- `oars pool deposit` writes a batch of closed-vocabulary session skeletons to an outbox for each session that passes your folder allowlist and the exclusion check, and stops. Nothing is sent: `--send <hash>` sends no request. A batch that was shown and is unchanged stops with `sending_disabled` (exit 5), and any other hash stops with its own refusal.
+- `oars pool deposit` writes a batch of session skeletons (a closed list of fields, each value redacted first; a host is hashed by the pool on arrival) to an outbox for each session that passes your folder allowlist and the exclusion check, and stops: it sends nothing itself. `--send <hash>` sends one batch that `outbox` printed and that is unchanged on disk, once this account has accepted the pool covenant (`--accept-covenant <version>`, or an earlier acceptance); before that it reads the covenant, sends no batch, and exits 3 with `covenant_not_accepted`. A hash that was never shown, or a batch that changed, is refused before any request. The nightly task is the other sender: after the pool says your account accepted its covenant, it sends new batches, and raw copies only if you said yes to the raw prompt (`oars pool raw --consent yes`). With no sign-in, no acceptance, or an unreachable server it sends nothing.
 - `deposit`, `outbox`, and `fetch` need `oars pool login` first; without it they exit 3 and name the server.
+- `oars pool coverage [--org-size <band>] [--repo-visibility public|private|unknown]` sets the two coverage bands only you can state, read locally and never from the network; an unset band goes on the wire as `unknown`.
 - `oars pool outbox` prints each batch exactly as it would be sent, with its SHA-256, and `--explain` adds each field's rule.
-- `oars pool fetch --harness-version <version>` fetches that version's signed bundle, verifies it against the key pinned at login, and keeps it locally.
+- `oars pool fetch --harness-version <version>` fetches that version's signed bundle, verifies it against the key pinned at login, and keeps it locally. It prints the public and disclosure floors the bundle states (and any read family on a floor of its own) and holds no floor of its own: the pool sets them, so a change is a deploy and never a new release of oars.
 
 ## The `--json` contract
 

package/dist/cli.d.ts

@@ -2,6 +2,7 @@ import type { CredentialStore } from './credentials.js';
 import { ExitCode } from './errors.js';
 import type { InstallRuntime } from './sessions/install.js';
 import type { SessionsRuntime } from './sessions/store.js';
+import type { TelemetryRuntime } from './telemetry/record.js';
 /** Everything the CLI takes from its process, so the tests can stand in for each. */
 export interface RunDeps {
     env: NodeJS.ProcessEnv;
@@ -22,11 +23,13 @@ export interface RunDeps {
     sessions?: SessionsRuntime;
     /** Where `oars sessions hook` finds the hook script, the settings files, and schtasks; absent in a run that has none. */
     install?: InstallRuntime;
+    /** Where telemetry keeps its id, settings, and spool; absent in a run that has none, which records nothing. */
+    telemetry?: TelemetryRuntime | undefined;
 }
 /** What a command produced: the `--json` document, and the line a human sees instead. */
 export interface Outcome {
     document: object;
     text: string;
 }
-/** Runs one invocation (`argv` without the node and script entries) and returns the exit code. */
+/** Runs one invocation (`argv` without the node and script entries) and returns the exit code. Telemetry records it afterward and cannot change it. */
 export declare const run: (argv: string[], deps: RunDeps) => Promise<ExitCode>;

package/dist/cli.js

@@ -12,7 +12,11 @@ import { gateInstall, gatePolicy, gateReplay, gateReport, gateUninstall } from '
 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';
+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];
@@ -55,21 +59,24 @@ const printFailure = (deps, json, error) => {
     const { title, detail, actionUrl } = error.problem;
     deps.io.stderr(`${[title ?? error.message, detail, actionUrl].filter((line) => line !== undefined && line !== '').join('\n')}\n`);
 };
-const sessionDeps = (deps) => ({ sessions: deps.sessions, install: deps.install, now: deps.now });
-const buildProgram = (deps) => {
+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('Many Oars: sign in, manage API keys, and keep a local, searchable record of your own Claude Code sessions')
+        .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 the idempotency key (default: a fresh UUID); rerun a failed command with the same key to replay it");
+        .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, {
@@ -122,16 +129,17 @@ const buildProgram = (deps) => {
         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)");
+    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 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)
+        .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'), redactDomains: list(options, 'redactDomain') }));
+        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')
@@ -212,10 +220,10 @@ const buildProgram = (deps) => {
     });
     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.');
+        .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)
@@ -223,8 +231,9 @@ const buildProgram = (deps) => {
         .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') }));
+        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')
@@ -313,11 +322,11 @@ const buildProgram = (deps) => {
     };
     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)
+        .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; off: remove it', (value) => {
+        .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;
@@ -335,7 +344,7 @@ const buildProgram = (deps) => {
     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('--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();
@@ -352,9 +361,9 @@ const buildProgram = (deps) => {
     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')
+        .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();
         emit(deps, flag(options, 'json'), await gateReplay(sessionDeps(deps), { allow: list(options, 'allow'), ...(flag(options, 'registryState') ? { registry: managerReader() } : {}) }));
@@ -398,9 +407,9 @@ const buildProgram = (deps) => {
         .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 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 (or OARS_POOL_URL; there is no default)';
+    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')
@@ -412,14 +421,33 @@ const buildProgram = (deps) => {
     });
     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)')
+        .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')
@@ -433,12 +461,44 @@ const buildProgram = (deps) => {
         .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')
+        .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;
 };
 const asCliError = (error) => {
@@ -448,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).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'))
@@ -465,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;
+};

package/dist/commands/login.d.ts

@@ -1,7 +1,7 @@
 import type { Outcome, RunDeps } from '../cli.js';
 export interface LoginOptions {
     apiUrl: string;
-    /** `--issuer-url`; `OARS_ISSUER_URL` when absent, then the built-in production issuer once Many Oars has launched (issuer.ts). */
+    /** `--issuer-url`; `OARS_ISSUER_URL` when absent, then the built-in production issuer (issuer.ts). */
     issuerUrl?: string;
     /** False for `--no-browser`. */
     browser: boolean;

package/dist/commands/login.js

@@ -5,7 +5,7 @@ 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 issuerUrl = resolveIssuerUrl(deps, options.issuerUrl);
     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;

package/dist/gate/hook-main.js

@@ -7,8 +7,10 @@ import { performance } from 'node:perf_hooks';
 import { defaultConfigDir } from '../credentials.js';
 import { DEADLINE_MS } from './hook.js';
 import { isLocked, startFill, startHelper } from './hook-fill.js';
+import { fireRecorder } from './hook-record.js';
 import { runHookProcess } from './hook-process.js';
 import { managerReader } from './registry.js';
+import { hookEmitter } from '../telemetry/hook-emit.js';
 /** The process itself ends this long after `DEADLINE_MS`. */
 const GRACE_MS = 100;
 const readStdin = async () => {
@@ -32,4 +34,14 @@ const depsFor = (stage) => {
         stage,
     };
 };
-await runHookProcess({ stdin: readStdin, deps: depsFor, exit: (code) => process.exit(code), write: (text) => new Promise((done) => process.stdout.write(text, () => { done(); })), deadlineMs: DEADLINE_MS + GRACE_MS - performance.now() });
+// One event per fire, recorded after the answer is written (`runHookProcess`), so it is never in front of the tool call. The version is read from `dist/gate/../../package.json`.
+const emit = hookEmitter(process.env, process.platform, homedir(), new URL('../../package.json', import.meta.url), Date.now);
+await runHookProcess({
+    stdin: readStdin,
+    deps: depsFor,
+    exit: (code) => process.exit(code),
+    write: (text) => new Promise((done) => process.stdout.write(text, () => { done(); })),
+    deadlineMs: DEADLINE_MS + GRACE_MS - performance.now(),
+    clock: () => performance.now(),
+    record: fireRecorder(emit),
+});

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

@@ -1,4 +1,10 @@
 import { type GateHookDeps } from './hook.js';
+/** What telemetry is told of one fire of `oars gate hook`: how long the handler took, how it ended, and the bytes it printed. */
+export interface HookFire {
+    latencyMs: number;
+    outcome: 'hit' | 'miss' | 'held' | 'error';
+    bytes: number;
+}
 export interface HookProcess {
     /** Reads the whole of stdin. Called inside the guard, so a stream that cannot be set up is a failed read, not a crash. */
     stdin: () => Promise<string>;
@@ -9,6 +15,10 @@ export interface HookProcess {
     write?: (text: string) => Promise<void>;
     /** Milliseconds from now until the process ends itself. */
     deadlineMs: number;
+    /** Told once how the fire went, with the transcript path the harness named (to read the frame from, never to record), after its output is written so recording is never in front of the answer. A throw here is swallowed: the exit code and stdout do not depend on it. */
+    record?: (fire: HookFire, transcript: string | undefined) => void | Promise<void>;
+    /** Milliseconds, only compared with itself: the latency in a fire is the difference across the handler. Absent: `Date.now`. */
+    clock?: () => number;
 }
 /** Resolves once `exit(0)` has been called, or never when the deadline timer is what ended the process. */
-export declare const runHookProcess: ({ stdin, deps, exit, write, deadlineMs }: HookProcess) => Promise<void>;
+export declare const runHookProcess: ({ stdin, deps, exit, write, deadlineMs, record, clock }: HookProcess) => Promise<void>;