@manyoars/oars 0.4.1 → 0.5.1

package/dist/telemetry/fields.d.ts

@@ -1,4 +1,5 @@
 import type { Recall } from '../sessions/recall-object.js';
+import type { CiWord, SurfaceWord } from './words.js';
 /** The harness every hook oars installs runs under (Claude Code); one spelling for the session hooks and the gate hook, so the two emitters cannot drift. */
 export declare const HOOK_HARNESS = "claude-code";
 /** The harness a hook ran under, as the closed list names it, else `other`. */
@@ -14,3 +15,13 @@ export declare const frameWords: (harness: string | undefined, harnessVersion: s
 };
 /** A recall as counts: how it was asked, which families it served, how many reads and evidence rows, the size of the answer, and its arm. Never the query text, a name, or the rendered answer. */
 export declare const recallFields: (recall: Recall, families: readonly string[], legacy?: boolean) => object;
+/** Whether this run is in CI, as a closed word read from the environment's variable names. Only the name decides the word: the value is tested and dropped, never returned. */
+export declare const ciWord: (env: NodeJS.ProcessEnv) => CiWord;
+/**
+ * How this copy arrived, as a closed word, from the folder oars runs in and `npm_config_user_agent` and from nothing else. A harness store is read first (a plugin can carry its own
+ * `node_modules`), then a package runner, then a global install; a folder that fits none reads `unknown`, never a guess. The agent only confirms a runner: a package manager that started the
+ * process says its name there, and a folder called `dlx` with no such agent is not a runner.
+ */
+export declare const surfaceWord: (installPath: string, userAgent: string | undefined) => SurfaceWord;
+/** The folder this module runs from: inside the package wherever it was installed (a symlinked bin resolves to its real folder). */
+export declare const installFolder: () => string;

package/dist/telemetry/fields.js

@@ -1,4 +1,5 @@
 import { HARNESSES, OTHER } from '../sessions/pool-wire.js';
+import { fileURLToPath } from 'node:url';
 import { modelWord, versionWord } from './schema.js';
 /** The harness every hook oars installs runs under (Claude Code); one spelling for the session hooks and the gate hook, so the two emitters cannot drift. */
 export const HOOK_HARNESS = 'claude-code';
@@ -24,3 +25,58 @@ export const recallFields = (recall, families, legacy = false) => ({
     tokens: recall.answer.tokens,
     arm: recall.arm,
 });
+/** A provider's own variable and the word it is read as. Order is the precedence: most providers also set `CI`, which on its own reads `other`. */
+const CI_PROVIDERS = [
+    ['GITHUB_ACTIONS', 'github-actions'],
+    ['GITLAB_CI', 'gitlab-ci'],
+    ['CIRCLECI', 'circleci'],
+    ['TRAVIS', 'travis-ci'],
+    ['JENKINS_URL', 'jenkins'],
+    ['BUILDKITE', 'buildkite'],
+    ['TF_BUILD', 'azure-pipelines'],
+    ['BITBUCKET_BUILD_NUMBER', 'bitbucket'],
+    ['TEAMCITY_VERSION', 'teamcity'],
+    ['APPVEYOR', 'appveyor'],
+    ['CODEBUILD_BUILD_ID', 'codebuild'],
+];
+/** A variable counts when it holds anything but the words a shell uses for no (an empty value, `0`, `false`, `no`, `off`). */
+const NOT_SET = new Set(['', '0', 'false', 'no', 'off']);
+const isSet = (value) => value !== undefined && !NOT_SET.has(value.toLowerCase());
+/** Whether this run is in CI, as a closed word read from the environment's variable names. Only the name decides the word: the value is tested and dropped, never returned. */
+export const ciWord = (env) => {
+    for (const [variable, word] of CI_PROVIDERS)
+        if (isSet(env[variable]))
+            return word;
+    return isSet(env.CI) ? 'other' : 'none';
+};
+/** The harness stores a plugin or extension lands in, matched on the folder names the harness uses under its home. */
+const HARNESS_STORES = [
+    ['/.claude/plugins/', 'claude-plugin'],
+    ['/.codex/plugins/', 'codex-plugin'],
+    ['/.gemini/extensions/', 'gemini-extension'],
+];
+/** Where a package manager keeps a global install: npm and Node's own prefix (`lib/node_modules`, Windows `npm/node_modules`), pnpm, yarn, and bun. */
+const GLOBAL_FOLDERS = ['/lib/node_modules/', '/npm/node_modules/', '/pnpm/global/', '/yarn/global/node_modules/', '/.bun/install/global/'];
+/** npm's own folder for a package run once (`npx`), which no other tool uses. */
+const NPX_FOLDER = '/_npx/';
+/** The folders pnpm (`dlx`) and bun (`bunx-<id>-<package>`) run a package from: names common enough that only a package manager's own agent makes them count. */
+const RUNNER_FOLDERS = /\/(dlx|bunx-[^/]*)\//;
+const PACKAGE_MANAGER_AGENT = /^(npm|pnpm|yarn|bun)\//;
+/**
+ * How this copy arrived, as a closed word, from the folder oars runs in and `npm_config_user_agent` and from nothing else. A harness store is read first (a plugin can carry its own
+ * `node_modules`), then a package runner, then a global install; a folder that fits none reads `unknown`, never a guess. The agent only confirms a runner: a package manager that started the
+ * process says its name there, and a folder called `dlx` with no such agent is not a runner.
+ */
+export const surfaceWord = (installPath, userAgent) => {
+    const path = `/${installPath.split(String.fromCharCode(92)).join('/').toLowerCase()}`;
+    const store = HARNESS_STORES.find(([folder]) => path.includes(folder));
+    if (store !== undefined)
+        return store[1];
+    if (path.includes(NPX_FOLDER))
+        return 'npx';
+    if (RUNNER_FOLDERS.test(path) && userAgent !== undefined && PACKAGE_MANAGER_AGENT.test(userAgent))
+        return 'npx';
+    return GLOBAL_FOLDERS.some((folder) => path.includes(folder)) ? 'npm-global' : 'unknown';
+};
+/** The folder this module runs from: inside the package wherever it was installed (a symlinked bin resolves to its real folder). */
+export const installFolder = () => fileURLToPath(import.meta.url);

package/dist/telemetry/measures.d.ts

@@ -15,6 +15,19 @@ export declare const WINDOWS: readonly number[];
 export declare const HOOK_NAMES: readonly string[];
 export declare const OTHER = "other";
 export declare const UNRECORDED = "unrecorded";
+/**
+ * The cell of a `first-run` event: one yes (the first run was in CI) or no under the oars version, in a metric named for the listing surface (`first-run.npx`), so the pool's rollup holds each install's
+ * first-run day, its surface, and whether it ran in CI. `measuresOf` leaves it out on purpose: a rate over one event is no measure of the program, so the user's own report has no use for it, and the pool's fleet read skips it for the same reason. A word off
+ * the closed lists reads as `unknown` or not-CI, and the install is still counted.
+ */
+export declare const firstRunMeasures: (event: unknown) => Measure[];
+/**
+ * The cell of a `covenant-shown` event: one yes under the oars version, in a metric named for the covenant version the CLI told the operator to read (`covenant-shown.2026-11-10`), so the pool's rollup counts shows by version and
+ * day. Raw batches are swept at 90 days and a cell added later cannot count older shows, so the cell is kept from the first event. `measuresOf` leaves it out and the fleet read skips it (`isRecordOnlyMetric`): a count of shows is
+ * for the operator's query, not a measure of the program. A version that is not a word reads `other`, and a missing one `unrecorded`; the show is still counted.
+ */
+export declare const covenantShownMeasures: (event: unknown) => Measure[];
+export declare const isRecordOnlyMetric: (metric: string) => boolean;
 /** What one event measures; an event of a type nothing measures, or that is not an object, measures nothing. */
 export declare const measuresOf: (event: unknown) => Measure[];
 /** Every cell is named by these three together. */

package/dist/telemetry/measures.js

@@ -2,6 +2,7 @@
 // A measure is one observation in a cell: a latency in milliseconds, or a yes/no that rates are made from. The cell is (metric, dimension, value): `hook.pre-tool.latency` at harness
 // `claude-code`, version `2.1.5`. The reader is tolerant on purpose: the pool reads batches kept whole from any client, so a value that does not fit is skipped, never trusted.
 import { isHarness } from '../sessions/pool-wire.js';
+import { CI_WORDS, SURFACE_WORDS } from './words.js';
 /** The windows the report shows and the pool serves, in days. */
 export const WINDOWS = [7, 30];
 const DAY_MS = 86_400_000;
@@ -73,6 +74,35 @@ const storeMeasures = (event, data) => {
         found.push(rate('store.verifyFailure', 'cli', version, failed > 0));
     return found;
 };
+/**
+ * The cell of a `first-run` event: one yes (the first run was in CI) or no under the oars version, in a metric named for the listing surface (`first-run.npx`), so the pool's rollup holds each install's
+ * first-run day, its surface, and whether it ran in CI. `measuresOf` leaves it out on purpose: a rate over one event is no measure of the program, so the user's own report has no use for it, and the pool's fleet read skips it for the same reason. A word off
+ * the closed lists reads as `unknown` or not-CI, and the install is still counted.
+ */
+export const firstRunMeasures = (event) => {
+    if (fieldOf(event, 'type') !== 'first-run')
+        return [];
+    const data = fieldOf(event, 'data');
+    const surface = fieldOf(data, 'surface');
+    const ci = fieldOf(data, 'ci');
+    const known = typeof surface === 'string' && SURFACE_WORDS.some((word) => word === surface) ? surface : 'unknown';
+    const inCi = typeof ci === 'string' && ci !== 'none' && CI_WORDS.some((word) => word === ci);
+    return [rate(`first-run.${known}`, 'cli', valueOf(fieldOf(event, 'cli')), inCi)];
+};
+/**
+ * The cell of a `covenant-shown` event: one yes under the oars version, in a metric named for the covenant version the CLI told the operator to read (`covenant-shown.2026-11-10`), so the pool's rollup counts shows by version and
+ * day. Raw batches are swept at 90 days and a cell added later cannot count older shows, so the cell is kept from the first event. `measuresOf` leaves it out and the fleet read skips it (`isRecordOnlyMetric`): a count of shows is
+ * for the operator's query, not a measure of the program. A version that is not a word reads `other`, and a missing one `unrecorded`; the show is still counted.
+ */
+export const covenantShownMeasures = (event) => {
+    if (fieldOf(event, 'type') !== 'covenant-shown')
+        return [];
+    const version = valueOf(fieldOf(fieldOf(event, 'data'), 'version'));
+    return [rate(`covenant-shown.${version}`, 'cli', valueOf(fieldOf(event, 'cli')), true)];
+};
+/** The metrics the rollup records for the operator's queries and the fleet read never serves: a cell of one event or one count per install measures nothing across installs. */
+const RECORD_ONLY_PREFIXES = ['first-run.', 'covenant-shown.'];
+export const isRecordOnlyMetric = (metric) => RECORD_ONLY_PREFIXES.some((prefix) => metric.startsWith(prefix));
 /** What one event measures; an event of a type nothing measures, or that is not an object, measures nothing. */
 export const measuresOf = (event) => {
     const type = fieldOf(event, 'type');

package/dist/telemetry/observe.d.ts

@@ -1,13 +1,26 @@
 import type { Command } from 'commander';
 import type { RunDeps } from '../cli.js';
 import type { ExitCode } from '../errors.js';
+import type { CardLineArm } from './schema.js';
+import { type TelemetryRuntime } from './record.js';
 export interface Observed {
     /** The command path, such as `['pool', 'fetch']`; empty when no command ran (`--help`, `--version`, a usage error). */
     path: string[];
     /** The long names (as commander keys them) of the options given on the command line. */
     flags: string[];
+    /** What the weekly card line did on this command (`sessions/card-line.ts`); absent when it was never asked. */
+    cardLine?: CardLineArm;
 }
 /** Called by commander just before an action runs. */
 export declare const observeCommand: (observed: Observed, action: Command) => void;
-/** Prints the notice on the first run that is not a hook, then records the event. Never throws and never changes what the command did. */
-export declare const finishTelemetry: (deps: RunDeps, argv: string[], observed: Observed, startedAt: number, exit: ExitCode) => void;
+export declare const isHook: (argv: string[], observed: Observed) => boolean;
+/**
+ * The `first-run` event, from the one place that shows the notice. `installPath` is where this copy runs from; only a test names it, and it is read here because it is needed on a first run only.
+ * Never throws: `oars telemetry on`, which shows the notice itself, calls it outside `finishTelemetry`'s guard.
+ */
+export declare const recordFirstRun: (deps: RunDeps, runtime: TelemetryRuntime, installPath?: string) => void;
+/**
+ * Prints the notice on the first run that is not a hook, then records the event. Never throws and never changes what the command did. `installPath` is where this copy runs from; only a test names it,
+ * and it is read inside the guard because it is needed on a first run only.
+ */
+export declare const finishTelemetry: (deps: RunDeps, argv: string[], observed: Observed, startedAt: number, exit: ExitCode, installPath?: string) => void;

package/dist/telemetry/observe.js

@@ -1,6 +1,7 @@
-import { consentOf, markNoticeShown, NOTICE } from './consent.js';
+import { consentOf, everShownNotice, markNoticeShown, NOTICE } from './consent.js';
 import { recordEvent } from './record.js';
 import { startDailySend } from './send.js';
+import { ciWord, installFolder, surfaceWord } from './fields.js';
 import { errorClassOf } from './schema.js';
 const pathOf = (command) => {
     const names = [];
@@ -18,12 +19,29 @@ export const observeCommand = (observed, action) => {
     const given = action.optsWithGlobals();
     observed.flags = Object.keys(given).filter((key) => action.getOptionValueSourceWithGlobals(key) === 'cli');
 };
-const isHook = (argv, observed) => {
+export const isHook = (argv, observed) => {
     const gateHook = (words) => words[0] === 'gate' && words[1] === 'hook';
     return gateHook(observed.path) || gateHook(argv);
 };
-/** Prints the notice on the first run that is not a hook, then records the event. Never throws and never changes what the command did. */
-export const finishTelemetry = (deps, argv, observed, startedAt, exit) => {
+/**
+ * The `first-run` event, from the one place that shows the notice. `installPath` is where this copy runs from; only a test names it, and it is read here because it is needed on a first run only.
+ * Never throws: `oars telemetry on`, which shows the notice itself, calls it outside `finishTelemetry`'s guard.
+ */
+export const recordFirstRun = (deps, runtime, installPath) => {
+    try {
+        recordEvent({ ...runtime, version: deps.version, now: deps.now }, 'first-run', { ci: ciWord(deps.env), surface: surfaceWord(installPath ?? installFolder(), deps.env.npm_config_user_agent) });
+    }
+    catch {
+        // Telemetry is never allowed to change what a command does.
+    }
+};
+/** `--version` and `--help` end the parse before any action runs (so the path is empty); they stay a plain answer and leave the notice for the next command. */
+const isInfoOnly = (argv, observed) => observed.path.length === 0 && argv.some((word) => ['--version', '-V', '--help', '-h'].includes(word));
+/**
+ * Prints the notice on the first run that is not a hook, then records the event. Never throws and never changes what the command did. `installPath` is where this copy runs from; only a test names it,
+ * and it is read inside the guard because it is needed on a first run only.
+ */
+export const finishTelemetry = (deps, argv, observed, startedAt, exit, installPath) => {
     try {
         const runtime = deps.telemetry;
         if (runtime === undefined)
@@ -31,17 +49,26 @@ export const finishTelemetry = (deps, argv, observed, startedAt, exit) => {
         const consent = consentOf(deps.env, runtime.dir);
         if (!consent.enabled)
             return;
-        if (!consent.noticeShown && !isHook(argv, observed) && markNoticeShown(runtime.dir, deps.now))
-            deps.io.stderr(`${NOTICE}\n`);
+        if (!consent.noticeShown && !isHook(argv, observed) && !isInfoOnly(argv, observed)) {
+            const seenBefore = everShownNotice(runtime.dir);
+            if (markNoticeShown(runtime.dir, deps.now)) {
+                deps.io.stderr(`${NOTICE}\n`);
+                // Once per install: an install that saw an older notice sees this one but records no second first-run; nothing is recorded or sent from a folder that could not claim it.
+                if (!seenBefore)
+                    recordFirstRun(deps, runtime, installPath);
+            }
+        }
         const errorClass = errorClassOf(exit);
         recordEvent({ ...runtime, version: deps.version, now: deps.now }, 'command', {
             path: observed.path,
             flags: observed.flags,
             durationMs: Math.max(0, deps.now() - startedAt),
             exitCode: exit,
+            ci: ciWord(deps.env),
+            ...(observed.cardLine === undefined ? {} : { cardLine: observed.cardLine }),
             ...(errorClass === undefined ? {} : { errorClass }),
         });
-        // Never from a hook: a hook has a time budget, and the send is for the nightly task and the commands a person runs.
+        // Never from a hook: a hook has a time budget, and the send is for the detached sender and the commands a person runs.
         if (!isHook(argv, observed))
             startDailySend(runtime, deps.env, deps.now());
     }

package/dist/telemetry/region.d.ts

@@ -0,0 +1,6 @@
+/** IANA zones of the EU, the EEA (Iceland, Liechtenstein, Norway), and the UK, with the outermost regions that sit outside `Europe/*` and `Europe/Mariehamn` (Åland). */
+export declare const CLOSED_ZONES: ReadonlySet<string>;
+/** True when the zone is on the closed list or cannot be read (absent or blank). */
+export declare const isClosedZone: (zone: string | undefined) => boolean;
+/** The machine's resolved IANA zone, or `undefined` when the runtime cannot say. */
+export declare const machineZone: () => string | undefined;

package/dist/telemetry/region.js

@@ -0,0 +1,28 @@
+// Where telemetry is off: a machine whose time zone is in the EU, the EEA, or the UK records and sends nothing, with no prompt (P97). The zone is the machine's own fact, so no network call
+// is made. An unresolvable zone counts as closed: the rule fails toward sending nothing.
+/** IANA zones of the EU, the EEA (Iceland, Liechtenstein, Norway), and the UK, with the outermost regions that sit outside `Europe/*` and `Europe/Mariehamn` (Åland). */
+export const CLOSED_ZONES = new Set([
+    // EU member states
+    'Europe/Vienna', 'Europe/Brussels', 'Europe/Sofia', 'Europe/Zagreb', 'Asia/Nicosia', 'Asia/Famagusta', 'Europe/Nicosia', 'Europe/Prague', 'Europe/Copenhagen',
+    'Europe/Tallinn', 'Europe/Helsinki', 'Europe/Mariehamn', 'Europe/Paris', 'Europe/Berlin', 'Europe/Busingen', 'Europe/Athens', 'Europe/Budapest', 'Europe/Dublin',
+    'Europe/Rome', 'Europe/Riga', 'Europe/Vilnius', 'Europe/Luxembourg', 'Europe/Malta', 'Europe/Amsterdam', 'Europe/Warsaw', 'Europe/Lisbon', 'Europe/Bucharest',
+    'Europe/Bratislava', 'Europe/Ljubljana', 'Europe/Madrid', 'Europe/Stockholm',
+    // EEA outside the EU, and the UK (with its legacy aliases). Europe/Jersey, Europe/Guernsey, and Europe/Isle_of_Man (Crown dependencies) and
+    // America/St_Barthelemy (outside the EU since 2012) are kept on purpose, to fail closed.
+    'Atlantic/Reykjavik', 'Iceland', 'Europe/Vaduz', 'Europe/Oslo', 'Arctic/Longyearbyen', 'Atlantic/Jan_Mayen', 'WET', 'CET', 'MET', 'EET', 'Europe/London', 'Europe/Belfast', 'Europe/Jersey', 'Europe/Guernsey', 'Europe/Isle_of_Man',
+    'GB', 'GB-Eire', 'Eire', 'Portugal', 'Poland',
+    // Outermost regions and island zones of member states
+    'Atlantic/Canary', 'Atlantic/Madeira', 'Atlantic/Azores', 'Africa/Ceuta', 'America/Martinique', 'America/Guadeloupe', 'America/Cayenne', 'Indian/Reunion', 'Indian/Mayotte',
+    'America/St_Barthelemy', 'America/Marigot',
+]);
+/** True when the zone is on the closed list or cannot be read (absent or blank). */
+export const isClosedZone = (zone) => zone === undefined || zone.trim() === '' || zone.trim() === 'Etc/Unknown' || CLOSED_ZONES.has(zone.trim());
+/** The machine's resolved IANA zone, or `undefined` when the runtime cannot say. */
+export const machineZone = () => {
+    try {
+        return Intl.DateTimeFormat().resolvedOptions().timeZone;
+    }
+    catch {
+        return undefined;
+    }
+};

package/dist/telemetry/report.js

@@ -167,7 +167,7 @@ export const textOf = (report, dir) => {
     const floor = fleet.status === 'answered' ? fleet.floor : 0;
     const out = [`Your telemetry, from the spool in ${dir}.`];
     if (report.windows.every((window) => window.cells.length === 0) && report.store === undefined)
-        out.push('Nothing is measured in the spool yet: the hooks and nightly task record as they run.');
+        out.push('Nothing is measured in the spool yet: the hooks and the detached sender record as they run.');
     for (const window of report.windows) {
         if (window.cells.length === 0)
             continue;

package/dist/telemetry/schema.d.ts

@@ -18,6 +18,9 @@ export declare const HOOK_OUTCOMES: readonly ["hit", "miss", "held", "error"];
 export declare const RECALL_FORMS: readonly ["pattern", "entity", "question", "text", "legacy"];
 export declare const RECALL_MODES: readonly ["pull", "push"];
 export declare const RECALL_ARMS: readonly ["shown", "held"];
+/** What the weekly card line did on a command: printed, held back by the holdback, or not due. */
+export declare const CARD_LINE_ARMS: readonly ["shown", "held", "not_due"];
+export type CardLineArm = (typeof CARD_LINE_ARMS)[number];
 /** The read families a recall can serve, as the program names them. */
 export declare const RECALL_FAMILY_NAMES: readonly ["recovery", "fit", "cost", "change", "live", "adoption", "method", "next-step", "tool-day", "version-boundary", "substitution", "interaction", "day-move", "entity"];
 export declare const FETCH_HARNESSES: readonly ["claude-code", "cursor", "codex", "copilot", "gemini", "grok", "opencode", "pi", "vscode-copilot", "otel", "other"];

package/dist/telemetry/schema.js

@@ -6,6 +6,7 @@ import { ExitCode } from '../errors.js';
 import { FIELD_ROWS } from '../sessions/pool-outbox.js';
 import { OTHER, HARNESSES } from '../sessions/pool-wire.js';
 import { LITERAL, publicModel, publicVersion } from '../sessions/public-vocabulary.js';
+import { CI_WORDS, SURFACE_WORDS } from './words.js';
 /** Bumped when an event type or field changes meaning; every spooled event carries it. */
 export const SCHEMA_VERSION = 1;
 /** A command or option name as the program defines it: letters, digits, and hyphens. No space, slash, dot, colon, or quote. */
@@ -36,6 +37,9 @@ const hex = (digits) => (value) => typeof value === 'string' && new RegExp(`^[0-
 /** A problem code as a server names it: lowercase words joined with underscores. No space, slash, dot, colon, or quote, so no path, URL, or sentence fits. */
 const CODE = /^[a-z][a-z0-9_]{0,39}$/;
 const code = (value) => (typeof value === 'string' && CODE.test(value) ? value : undefined);
+/** A covenant version as the pool names it: a short word of letters, digits, dots, underscores, and hyphens. A text off that shape (the pool is any server the operator names) is dropped, not trimmed. */
+const COVENANT_VERSION = /^[A-Za-z0-9][A-Za-z0-9._-]{0,31}$/;
+const covenantVersion = (value) => (typeof value === 'string' && COVENANT_VERSION.test(value) ? value : undefined);
 const rules = (fields) => new Map(Object.entries(fields));
 const DAY_MS = 86_400_000;
 /** What went wrong, as a closed word chosen from the exit code; the error's own text never comes here. */
@@ -48,6 +52,8 @@ export const HOOK_OUTCOMES = ['hit', 'miss', 'held', 'error'];
 export const RECALL_FORMS = ['pattern', 'entity', 'question', 'text', 'legacy'];
 export const RECALL_MODES = ['pull', 'push'];
 export const RECALL_ARMS = ['shown', 'held'];
+/** What the weekly card line did on a command: printed, held back by the holdback, or not due. */
+export const CARD_LINE_ARMS = ['shown', 'held', 'not_due'];
 /** The read families a recall can serve, as the program names them. */
 export const RECALL_FAMILY_NAMES = ['recovery', 'fit', 'cost', 'change', 'live', 'adoption', 'method', 'next-step', 'tool-day', 'version-boundary', 'substitution', 'interaction', 'day-move', 'entity'];
 export const FETCH_HARNESSES = ['claude-code', 'cursor', 'codex', 'copilot', 'gemini', 'grok', 'opencode', 'pi', 'vscode-copilot', 'otel', 'other'];
@@ -63,7 +69,7 @@ const WIRE_HARNESSES = [...HARNESSES, OTHER];
 const WIRE_LENGTH = WIRE_NAMES.size;
 /** One line per event type. */
 const EVENTS = new Map([
-    ['command', rules({ path: tokens(4), flags: tokens(40), durationMs: whole(DAY_MS), exitCode: whole(255), errorClass: oneOf(ERROR_CLASSES) })],
+    ['command', rules({ path: tokens(4), flags: tokens(40), durationMs: whole(DAY_MS), exitCode: whole(255), errorClass: oneOf(ERROR_CLASSES), ci: oneOf(CI_WORDS), cardLine: oneOf(CARD_LINE_ARMS) })],
     ['hook', rules({ name: oneOf(HOOK_NAMES), latencyMs: whole(DAY_MS), outcome: oneOf(HOOK_OUTCOMES), bytes: whole(BYTES), harness: oneOf(WIRE_HARNESSES), harnessVersion: MODEL_OR_VERSION(versionWord), model: MODEL_OR_VERSION(modelWord) })],
     [
         'recall',
@@ -128,6 +134,10 @@ const EVENTS = new Map([
     ],
     // One send of one batch: whether the pool took it, the HTTP status, and the code of its refusal.
     ['wire-send', rules({ sent: whole(1), status: whole(599), code, bytes: whole(HUGE) })],
+    // The install's first run, sent once where the first-run notice is shown (docs/telemetry.md).
+    ['first-run', rules({ ci: oneOf(CI_WORDS), surface: oneOf(SURFACE_WORDS) })],
+    // The CLI told the operator which covenant to read and accept: the version and nothing else.
+    ['covenant-shown', rules({ version: covenantVersion })],
 ]);
 export const EVENT_TYPES = [...EVENTS.keys()];
 /** The field names a type admits, so a test can feed every one. */

package/dist/telemetry/send.d.ts

@@ -14,7 +14,7 @@ export interface SendDeps {
     timeoutMs?: number;
 }
 export interface SendResult {
-    outcome: 'sent' | 'failed' | 'empty' | 'not-allowed' | 'no-server';
+    outcome: 'sent' | 'failed' | 'empty' | 'not-allowed' | 'no-server' | 'not-due';
     /** Events the server took (and that were cleared from the spool). */
     sent: number;
     /** Requests made, including one that failed. */
@@ -25,7 +25,10 @@ export declare const writeMark: (dir: string, now: number) => void;
 export declare const dueForSend: (dir: string, now: number) => boolean;
 /** Sends what the spool holds. Never throws. */
 export declare const sendSpool: (deps: SendDeps) => Promise<SendResult>;
-/** The nightly task's send, in the telemetry folder under the config folder. */
+/**
+ * The detached sender's telemetry send, in the telemetry folder under the config folder. The sender runs up to about hourly, but telemetry goes at most once a
+ * day, on the same mark a command's daily send uses; events recorded by the runs in between wait in the spool for the next day's batch.
+ */
 export declare const sendNightly: (env: NodeJS.ProcessEnv, platform: NodeJS.Platform, home: string, now: () => number) => Promise<SendResult>;
 /**
  * Called after an interactive command: starts one detached send, at most once a day, when sending is allowed. The mark is written first, so two commands at

package/dist/telemetry/send.js

@@ -1,4 +1,4 @@
-// The sender: the only code that sends telemetry. It runs from the nightly task, and at most once a day from an interactive command as a detached process; never on a hook path, and
+// The sender: the only code that sends telemetry. It runs from the detached sender (hook-bin.js nightly), and at most once a day from an interactive command as a detached process; never on a hook path, and
 // nothing waits for it. Before any byte leaves it calls `telemetrySendAllowed` (telemetry on, notice shown) and sends to the pool server in `OARS_POOL_URL`, else the Many Oars pool, the same default `oars pool`
 // reads and with the same rules (https, or http to this machine).
 //
@@ -9,7 +9,7 @@ import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { defaultConfigDir } from '../credentials.js';
-import { telemetrySendAllowed } from './consent.js';
+import { shownNoticeVersion, telemetrySendAllowed } from './consent.js';
 import { installId, readSpool, spoolPaths } from './spool.js';
 /** The pool route takes at most this many events (Analytics Engine's per-request write limit). */
 export const BATCH_EVENTS = 250;
@@ -41,12 +41,12 @@ const eventOf = (line) => {
     }
 };
 /** True only for a 2xx. A redirect is not followed: a pool never redirects a POST, and a 3xx from anything else is not the pool. */
-const post = async (url, install, events, deps) => {
+const post = async (url, install, notice, events, deps) => {
     try {
         const response = await (deps.fetch ?? fetch)(url, {
             method: 'POST',
             headers: { 'content-type': 'application/json' },
-            body: JSON.stringify({ install, events }),
+            body: JSON.stringify({ install, notice, events }),
             redirect: 'manual',
             signal: AbortSignal.timeout(deps.timeoutMs ?? SEND_TIMEOUT_MS),
         });
@@ -129,7 +129,7 @@ export const sendSpool = async (deps) => {
         for (let at = 0; at < events.length && !failed; at += BATCH_EVENTS) {
             const batch = events.slice(at, at + BATCH_EVENTS);
             tally.requests += 1;
-            if (await post(`${server}/v1/telemetry`, install, batch.map(({ event }) => event), deps)) {
+            if (await post(`${server}/v1/telemetry`, install, shownNoticeVersion(deps.dir), batch.map(({ event }) => event), deps)) {
                 tally.sent += batch.length;
                 sent.push(...batch.map(({ line }) => line));
             }
@@ -145,8 +145,16 @@ export const sendSpool = async (deps) => {
         return finish('failed');
     }
 };
-/** The nightly task's send, in the telemetry folder under the config folder. */
-export const sendNightly = (env, platform, home, now) => sendSpool({ env, dir: join(defaultConfigDir(env, platform, home), 'oars', 'telemetry'), now });
+/**
+ * The detached sender's telemetry send, in the telemetry folder under the config folder. The sender runs up to about hourly, but telemetry goes at most once a
+ * day, on the same mark a command's daily send uses; events recorded by the runs in between wait in the spool for the next day's batch.
+ */
+export const sendNightly = async (env, platform, home, now) => {
+    const dir = join(defaultConfigDir(env, platform, home), 'oars', 'telemetry');
+    if (!dueForSend(dir, now()))
+        return { outcome: 'not-due', sent: 0, requests: 0 };
+    return sendSpool({ env, dir, now });
+};
 /**
  * Called after an interactive command: starts one detached send, at most once a day, when sending is allowed. The mark is written first, so two commands at
  * once start one. Nothing here throws or waits, and the run has no way to start a send unless `main.ts` gave it one.

package/dist/telemetry/words.d.ts

@@ -0,0 +1,6 @@
+/** Whether a run was in CI and by which provider: the word is chosen from the provider's own variable (`ciWord` in `fields.ts`), so the variable's value never reaches the spool. `other` is a bare `CI`. */
+export declare const CI_WORDS: readonly ["none", "github-actions", "gitlab-ci", "circleci", "travis-ci", "jenkins", "buildkite", "azure-pipelines", "bitbucket", "teamcity", "appveyor", "codebuild", "other"];
+export type CiWord = (typeof CI_WORDS)[number];
+/** How this copy of oars arrived, from the folder it runs in and the package manager that started it (`surfaceWord` in `fields.ts`); the path itself never reaches the spool. A folder it cannot place is `unknown`. */
+export declare const SURFACE_WORDS: readonly ["npm-global", "npx", "claude-plugin", "codex-plugin", "gemini-extension", "unknown"];
+export type SurfaceWord = (typeof SURFACE_WORDS)[number];

package/dist/telemetry/words.js

@@ -0,0 +1,6 @@
+// The two closed word lists the pool's rollup reads (`measures.ts`) beside the schema that checks them (`schema.ts`). A leaf on purpose: it imports nothing, so a Worker that imports it takes no
+// file-system module along (`schema.ts` reaches `node:fs/promises` through the session outbox).
+/** Whether a run was in CI and by which provider: the word is chosen from the provider's own variable (`ciWord` in `fields.ts`), so the variable's value never reaches the spool. `other` is a bare `CI`. */
+export const CI_WORDS = ['none', 'github-actions', 'gitlab-ci', 'circleci', 'travis-ci', 'jenkins', 'buildkite', 'azure-pipelines', 'bitbucket', 'teamcity', 'appveyor', 'codebuild', 'other'];
+/** How this copy of oars arrived, from the folder it runs in and the package manager that started it (`surfaceWord` in `fields.ts`); the path itself never reaches the spool. A folder it cannot place is `unknown`. */
+export const SURFACE_WORDS = ['npm-global', 'npx', 'claude-plugin', 'codex-plugin', 'gemini-extension', 'unknown'];

package/package.json

@@ -1,7 +1,25 @@
 {
   "name": "@manyoars/oars",
-  "version": "0.4.1",
-  "description": "The oars CLI: sign in, manage API keys, and keep a local memory of your own coding-agent sessions on your machine. The session commands upload nothing except what `gold arms` sends through your own Claude subscription; telemetry (on by default) and the nightly pool send after you accept a pool covenant are described in the README",
+  "version": "0.5.1",
+  "mcpName": "io.github.manyoars/oars",
+  "description": "A local, searchable record of your coding agent sessions. Reads Claude Code, Cursor, Codex, Copilot CLI, Gemini CLI, and more, and keeps the record on your machine.",
+  "homepage": "https://manyoars.com/",
+  "keywords": [
+    "claude-code",
+    "codex",
+    "cursor",
+    "gemini-cli",
+    "coding-agents",
+    "agent-memory",
+    "session-history",
+    "mcp",
+    "mcp-server",
+    "claude-code-plugin",
+    "codex-plugin",
+    "gemini-cli-extension",
+    "coding-agent",
+    "cli"
+  ],
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -10,10 +28,11 @@
   },
   "type": "module",
   "engines": {
-    "node": ">=24"
+    "node": ">=22.23.4"
   },
   "bin": {
-    "oars": "./dist/bin.js"
+    "oars": "./dist/bin.js",
+    "oars-hook": "./dist/oars-hook.js"
   },
   "files": [
     "dist",