@manyoars/oars 0.4.0 → 0.5.1

package/dist/telemetry/consent.js

@@ -1,11 +1,14 @@
 // Whether telemetry records and may send, and the one-time notice. The off switches are `oars telemetry off` (a saved setting), `OARS_TELEMETRY=0`, and
-// `DO_NOT_TRACK=1`; the environment wins over a saved `on`. `telemetrySendAllowed` is the check the sender must call before any byte leaves.
+// `DO_NOT_TRACK=1`, and a machine whose time zone is in the EU, the EEA, or the UK (`region.ts`), which no switch overrides; the environment wins over a saved `on`. `telemetrySendAllowed` is the check the sender must call before any byte leaves.
 import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { isClosedZone, machineZone } from './region.js';
 import { spoolPaths } from './spool.js';
+/** The version of the notice below. `markNoticeShown` stores it and each batch is stamped with the stored version; raise it whenever the notice changes in meaning. */
+export const NOTICE_VERSION = 2;
 /** Printed once on stderr, on the first run that is not a hook; also what `oars telemetry on` prints. */
 export const NOTICE = [
-    'oars records how it is used, on this machine: one event per command with its path, flag names (never their values), how long it took, the exit code, and the class of any error; one per hook fire, recall, deposit, and fetch, as counts and closed words (which hook, how long, hit or miss, how many bytes, how many sessions a deposit counted and how many each gate kept out, never which); each with a random install id, the oars version, the OS, and the time. Once a night it also records counts and sizes of the session store and what the run cost. A crash is recorded as the error\'s class and a hash of its stack (never its message). Each pool deposit records, per batch, which fields it held and how many bytes each took, and each send (a wire-send event) its HTTP status, the pool\'s refusal code, and its size.',
-    'It never records session content, prompts, file paths, URLs, arguments, or anything you typed. oars sends the events in batches to the pool server in OARS_POOL_URL, else to the Many Oars pool (pool.manyoars.com, not deployed yet: until it is, a send fails and the events stay on this machine), and nowhere else.',
+    'oars records how it is used, on this machine: one event per command with its path, flag names (never their values), how long it took, the exit code, and the class of any error; one per hook fire, recall, deposit, and fetch, as counts and closed words (which hook, how long, hit or miss, how many bytes, the harness name and version and the model name, how many sessions a deposit counted and how many each gate kept out, never which); each with a random install id, the oars version, the OS, and the time. Each time the background sender runs, at most about once an hour, it also records counts and sizes of the session store, the lists of harness versions and model names it holds, and what the run cost. Events are sent in a batch at most once a day. A crash is recorded as the error\'s class and a hash of its stack (never its message). Each pool deposit records, per batch, which fields it held and how many bytes each took, and each send (a wire-send event) its HTTP status, the pool\'s refusal code, and its size. It also records one event on the first run with whether it ran in CI and how this copy was installed, as closed words; whether each command ran in CI, as a closed word; and the covenant version each time the covenant screen is shown at a terminal.',
+    'It never records session content, prompts, file paths, URLs, arguments, or anything you typed. oars sends the events in batches to the pool server in OARS_POOL_URL, else to the Many Oars pool (pool.manyoars.com, which is live). Many Oars Co. may license and sell Usage Data. oars sends no telemetry from a machine whose time zone is in the EU, the EEA, or the UK.',
     'See exactly what is kept: oars telemetry show. Turn it off: oars telemetry off, or set OARS_TELEMETRY=0 or DO_NOT_TRACK=1. More: docs/telemetry.md.',
 ].join('\n');
 const readSettings = (dir) => {
@@ -15,7 +18,12 @@ const readSettings = (dir) => {
             return {};
         const enabled = Reflect.get(parsed, 'enabled');
         const shown = Reflect.get(parsed, 'noticeShownAt');
-        return { ...(typeof enabled === 'boolean' ? { enabled } : {}), ...(typeof shown === 'string' ? { noticeShownAt: shown } : {}) };
+        const version = Reflect.get(parsed, 'noticeVersion');
+        return {
+            ...(typeof enabled === 'boolean' ? { enabled } : {}),
+            ...(typeof shown === 'string' ? { noticeShownAt: shown } : {}),
+            ...(typeof version === 'number' ? { noticeVersion: version } : {}),
+        };
     }
     catch {
         return {};
@@ -31,9 +39,13 @@ const writeSettings = (dir, settings) => {
 };
 const OFF_WORDS = new Set(['0', 'false', 'off', 'no']);
 const DO_NOT_TRACK_WORDS = new Set(['1', 'true']);
-export const consentOf = (env, dir) => {
+export const consentOf = (env, dir, zone = machineZone()) => {
     const settings = readSettings(dir);
-    const noticeShown = settings.noticeShownAt !== undefined;
+    // An install that saw an older notice (no stored version, or another one) has not seen this one: it sees it again, and sends nothing until then.
+    const noticeShown = settings.noticeShownAt !== undefined && settings.noticeVersion === NOTICE_VERSION;
+    // First, so that no setting or `oars telemetry on` turns it back on in a closed region.
+    if (isClosedZone(zone))
+        return { enabled: false, reason: 'region', noticeShown };
     if (OFF_WORDS.has((env.OARS_TELEMETRY ?? '').toLowerCase()))
         return { enabled: false, reason: 'OARS_TELEMETRY', noticeShown };
     if (DO_NOT_TRACK_WORDS.has((env.DO_NOT_TRACK ?? '').toLowerCase()))
@@ -49,15 +61,19 @@ export const setEnabled = (dir, enabled) => {
 /** Records that the notice was shown; `false` when it could not be recorded (nothing is recorded or sent from a folder that cannot be written). */
 export const markNoticeShown = (dir, now) => {
     try {
-        writeSettings(dir, { ...readSettings(dir), noticeShownAt: new Date(now()).toISOString() });
+        writeSettings(dir, { ...readSettings(dir), noticeShownAt: new Date(now()).toISOString(), noticeVersion: NOTICE_VERSION });
         return true;
     }
     catch {
         return false;
     }
 };
+/** Whether this install has ever been shown any notice (an older version included). */
+export const everShownNotice = (dir) => readSettings(dir).noticeShownAt !== undefined;
+/** The notice version this install was shown, or `undefined` when none (or an unreadable file). */
+export const shownNoticeVersion = (dir) => readSettings(dir).noticeVersion;
 /** Whether the sender (t875) may send: telemetry on, and the notice shown. Off, or notice not yet shown, means nothing sends. */
-export const telemetrySendAllowed = (env, dir) => {
-    const consent = consentOf(env, dir);
+export const telemetrySendAllowed = (env, dir, zone = machineZone()) => {
+    const consent = consentOf(env, dir, zone);
     return consent.enabled && consent.noticeShown;
 };

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.0",
-  "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",