@manyoars/oars 0.4.1 → 0.5.2

package/dist/sessions/try-demo.js

@@ -0,0 +1,90 @@
+// The bundled demo behind `oars sessions try`. EVERYTHING HERE IS MADE UP: three invented Claude Code sessions in an invented project
+// (`/work/demo`), written so the same two errors recur. No line comes from a real session, a real person, or a real repository, and no
+// number `try` prints from it describes anyone's work. The sessions are lines of the same shape Claude Code writes, so the demo runs the
+// real deposit, recall, books, and hook code and not a canned answer.
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { slugOf } from './allow.js';
+/** The invented working directory the demo sessions claim; no such folder is read. Resolved, because a folder's name is its path's slug on this platform. */
+export const DEMO_CWD = resolve('/work/demo');
+/** The folder Claude Code would name for `DEMO_CWD` under `~/.claude/projects`. */
+export const DEMO_FOLDER = slugOf(DEMO_CWD);
+/** An error the three demo sessions all hit, as a stranger would paste it. */
+export const DEMO_ERROR = 'unexpected EOF while looking for matching quote';
+const SHELL_ERROR = `Exit code 2\nbash: -c: line 1: ${DEMO_ERROR}\n`;
+const WRITE_ERROR = 'File has not been read yet. Read it first before writing to it.';
+const shell = (command, result, isError = false) => ({ tool: 'Bash', input: { command }, result, isError });
+const read = (file) => ({ tool: 'Read', input: { file_path: file }, result: 'file contents', isError: false });
+const edit = (file, result, isError = false) => ({ tool: 'Write', input: { file_path: file, content: 'echo ok' }, result, isError });
+const SESSIONS = [
+    {
+        id: 'demo-0001',
+        day: '2026-10-06',
+        prompt: 'fix the failing build in /work/demo/src/main.ts',
+        turns: [read('/work/demo/src/main.ts'), shell("echo 'it's broken", SHELL_ERROR, true), edit('/work/demo/fix.sh', WRITE_ERROR, true), read('/work/demo/fix.sh'), edit('/work/demo/fix.sh', 'ok'), shell('npm test', 'all passed')],
+    },
+    {
+        id: 'demo-0002',
+        day: '2026-10-13',
+        prompt: 'add a test for the parser in /work/demo/src/parse.ts',
+        turns: [read('/work/demo/src/parse.ts'), shell("git commit -m 'add parser test", SHELL_ERROR, true), shell('git commit -m "add parser test"', 'committed'), shell('npm test', 'all passed')],
+    },
+    {
+        id: 'demo-0003',
+        day: '2026-10-20',
+        prompt: 'why is the deploy script slow',
+        turns: [read('/work/demo/deploy.sh'), edit('/work/demo/deploy.sh', WRITE_ERROR, true), read('/work/demo/deploy.sh'), shell("echo 'timing", SHELL_ERROR, true)],
+    },
+];
+const stamp = (day, second) => `${day}T10:${String(Math.floor(second / 60)).padStart(2, '0')}:${String(second % 60).padStart(2, '0')}.000Z`;
+/** One session as the JSON lines Claude Code writes: a prompt, then per turn an assistant tool call and the user line that carries its result. */
+const linesOf = (session) => {
+    let at = 0;
+    let parent = null;
+    const next = () => {
+        at += 3;
+        const uuid = `${session.id}-${String(at).padStart(4, '0')}`;
+        const line = { uuid, time: stamp(session.day, at), parentUuid: parent };
+        parent = uuid;
+        return line;
+    };
+    const common = { isSidechain: false, version: '2.1.300' };
+    const first = next();
+    const lines = [{ type: 'user', ...common, uuid: first.uuid, parentUuid: null, timestamp: first.time, cwd: DEMO_CWD, gitBranch: 'main', message: { role: 'user', content: session.prompt } }];
+    session.turns.forEach((turn, index) => {
+        const call = next();
+        const result = next();
+        const id = `t${String(index + 1)}`;
+        lines.push({
+            type: 'assistant',
+            ...common,
+            uuid: call.uuid,
+            parentUuid: call.parentUuid,
+            timestamp: call.time,
+            requestedModel: 'claude-opus-5-5',
+            requestId: `req_${session.id}_${String(index + 1)}`,
+            apiBlockIndex: 0,
+            message: {
+                role: 'assistant',
+                model: 'claude-opus-5-5',
+                content: [{ type: 'tool_use', id, name: turn.tool, input: turn.input }],
+                usage: { input_tokens: 10, cache_creation_input_tokens: 100, cache_read_input_tokens: 9000, output_tokens: 80 },
+            },
+        });
+        lines.push({
+            type: 'user',
+            ...common,
+            uuid: result.uuid,
+            parentUuid: result.parentUuid,
+            timestamp: result.time,
+            message: { role: 'user', content: [{ type: 'tool_result', tool_use_id: id, is_error: turn.isError, content: turn.result }] },
+        });
+    });
+    return lines.map((line) => JSON.stringify(line));
+};
+/** Writes the demo sessions under `<projectsRoot>/<DEMO_FOLDER>/`, the layout Claude Code uses. */
+export const writeDemoSessions = async (projectsRoot) => {
+    const folder = join(projectsRoot, DEMO_FOLDER);
+    await mkdir(folder, { recursive: true });
+    await Promise.all(SESSIONS.map((session) => writeFile(join(folder, `${session.id}.jsonl`), `${linesOf(session).join('\n')}\n`)));
+};

package/dist/sessions/try.d.ts

@@ -0,0 +1,13 @@
+import type { Outcome } from '../cli.js';
+import { type SessionsDeps } from './command.js';
+/** Printed once at the top and under every heading, so no line of the output can be mistaken for the reader's own history. */
+export declare const SYNTHETIC_LABEL = "SYNTHETIC DATA: made-up sessions bundled with oars, not your history";
+/** A prefix the throwaway folder carries, so a leftover one is recognizable in the temp folder. */
+export declare const TRY_PREFIX = "oars-try-";
+/**
+ * Builds the demo store under the OS temp folder, runs the three commands over it with the same code `oars sessions` runs, and removes the
+ * folder on the way out, success or failure (a thrown step included). A SIGINT or SIGTERM during the run skips `finally` and leaves the
+ * folder in the temp folder for the OS to clear; the run is about a second long. The runtime is its own: it never takes the caller's store, projects folder, or other sources,
+ * and no command here reaches the network or a model.
+ */
+export declare const sessionsTry: (deps: Pick<SessionsDeps, "now">) => Promise<Outcome>;

package/dist/sessions/try.js

@@ -0,0 +1,50 @@
+// `oars sessions try`: recall, books, and the hook line over a throwaway store of made-up sessions, for someone with no history of their own.
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { PassThrough } from 'node:stream';
+import { sessionsBooks, sessionsContext, sessionsDeposit, sessionsRecall } from './command.js';
+import { DEMO_CWD, DEMO_ERROR, writeDemoSessions } from './try-demo.js';
+/** Printed once at the top and under every heading, so no line of the output can be mistaken for the reader's own history. */
+export const SYNTHETIC_LABEL = 'SYNTHETIC DATA: made-up sessions bundled with oars, not your history';
+/** A prefix the throwaway folder carries, so a leftover one is recognizable in the temp folder. */
+export const TRY_PREFIX = 'oars-try-';
+const heading = (title, command) => ['', `== ${title} (${SYNTHETIC_LABEL}) ==`, `$ ${command}`];
+/**
+ * Builds the demo store under the OS temp folder, runs the three commands over it with the same code `oars sessions` runs, and removes the
+ * folder on the way out, success or failure (a thrown step included). A SIGINT or SIGTERM during the run skips `finally` and leaves the
+ * folder in the temp folder for the OS to clear; the run is about a second long. The runtime is its own: it never takes the caller's store, projects folder, or other sources,
+ * and no command here reaches the network or a model.
+ */
+export const sessionsTry = async (deps) => {
+    const root = await mkdtemp(join(tmpdir(), TRY_PREFIX));
+    try {
+        const projectsRoot = join(root, 'projects');
+        await writeDemoSessions(projectsRoot);
+        const runtime = { storeDir: join(root, 'store'), projectsRoot, sources: [], stdin: new PassThrough(), stdout: { write: () => true } };
+        const own = { sessions: runtime, install: undefined, now: deps.now };
+        const deposited = await sessionsDeposit(own, { allow: [], allowFiles: [], redactDomains: [] });
+        const recalled = await sessionsRecall(own, { error: DEMO_ERROR });
+        const booked = await sessionsBooks(own, { by: 'class', sinceDays: undefined });
+        const hooked = await sessionsContext(own, { cwd: DEMO_CWD, top: 5, maxChars: 1200 });
+        const text = [
+            `${SYNTHETIC_LABEL}.`,
+            'oars read three invented Claude Code sessions into a throwaway store, ran the commands below over it, and deletes that store when it exits.',
+            'Your own store and session folders were not read or written, and nothing left this machine.',
+            ...heading('Deposit', 'oars sessions deposit'),
+            deposited.text,
+            ...heading('Recall', `oars sessions recall --error "${DEMO_ERROR}"`),
+            recalled.text,
+            ...heading('Books', 'oars sessions books --by class'),
+            booked.text,
+            ...heading('Hook line', `oars sessions recall --context --cwd ${DEMO_CWD}`),
+            hooked.text,
+            '',
+            'To use oars on your own sessions: oars sessions deposit',
+        ].join('\n');
+        return { document: { ok: true, synthetic: true, label: SYNTHETIC_LABEL, deposit: deposited.document, recall: recalled.document, books: booked.document, hook: hooked.document }, text };
+    }
+    finally {
+        await rm(root, { recursive: true, force: true });
+    }
+};

package/dist/sessions/vscode-copilot.d.ts

@@ -20,6 +20,8 @@ export interface VscodeStore {
     sessions: VscodeSession[];
     /** The session as transcript text for `captureSession`; throws when no file of it can be read or holds no parseable entry. */
     transcript: (session: VscodeSession) => Promise<string>;
+    /** True when the session's chat data holds an empty request list (`chatHeadOnly`); `sessions verify` counts such a file as empty, not unreadable. */
+    headOnly: (session: VscodeSession) => Promise<boolean>;
     /** Files skipped because their name is not a safe file name (it names a skeleton), counted so the skip is never silent. */
     rejected: number;
     /** Folders and files that could not be inspected, reported once each and never fatal; the reason names no path. */
@@ -34,5 +36,7 @@ export declare const chatBadLines: (text: string) => string[];
 export declare const chatData: (text: string, jsonl: boolean) => Obj;
 /** One chat session as the lines `captureSession` reads. */
 export declare const chatLines: (data: Obj, fallbackId: string, folder: string | null) => Obj[];
+/** A session object whose request list is empty: the chat was opened and nothing was asked. Anything else with no turn (a renamed list, say) is not head-only. */
+export declare const chatHeadOnly: (data: Obj) => boolean;
 export declare const openVscodeCopilotStore: (root: string) => Promise<VscodeStore | undefined>;
 export {};

package/dist/sessions/vscode-copilot.js

@@ -378,6 +378,26 @@ export const chatLines = (data, fallbackId, folder) => {
     }
     return lines;
 };
+/** The first of the session's files that reads, handed to `use`; the failure of the last one when none does. */
+const firstReadable = async (session, use) => {
+    let failure = new Error('no file');
+    for (const file of session.files) {
+        try {
+            const text = await readFile(file, 'utf8');
+            const jsonl = file.endsWith('.jsonl');
+            // VS Code throws on an empty log ("Empty log file", objectMutationLog.ts:393) and falls back to the `.json`; the last file alone may read as an empty session.
+            if (jsonl && text.trim() === '' && file !== session.files[session.files.length - 1])
+                throw new Error('empty log file');
+            return use(chatData(text, jsonl), text, jsonl);
+        }
+        catch (error) {
+            failure = error;
+        }
+    }
+    throw failure;
+};
+/** A session object whose request list is empty: the chat was opened and nothing was asked. Anything else with no turn (a renamed list, say) is not head-only. */
+export const chatHeadOnly = (data) => Array.isArray(data.requests) && data.requests.length === 0;
 export const openVscodeCopilotStore = async (root) => {
     const unreadable = [];
     const found = new Map();
@@ -472,23 +492,10 @@ export const openVscodeCopilotStore = async (root) => {
         sessions,
         rejected,
         unreadable,
-        transcript: async (session) => {
-            let failure = new Error('no file');
-            for (const file of session.files) {
-                try {
-                    const text = await readFile(file, 'utf8');
-                    const jsonl = file.endsWith('.jsonl');
-                    // VS Code throws on an empty log ("Empty log file", objectMutationLog.ts:393) and falls back to the `.json`; the last file alone may read as an empty session.
-                    if (jsonl && text.trim() === '' && file !== session.files[session.files.length - 1])
-                        throw new Error('empty log file');
-                    const lines = [...chatLines(chatData(text, jsonl), session.id, session.folder).map((line) => JSON.stringify(line)), ...(jsonl ? chatBadLines(text) : [])];
-                    return lines.join('\n') + (lines.length === 0 ? '' : '\n');
-                }
-                catch (error) {
-                    failure = error;
-                }
-            }
-            throw failure;
-        },
+        headOnly: async (session) => await firstReadable(session, (data) => chatHeadOnly(data)),
+        transcript: async (session) => await firstReadable(session, (data, text, jsonl) => {
+            const lines = [...chatLines(data, session.id, session.folder).map((line) => JSON.stringify(line)), ...(jsonl ? chatBadLines(text) : [])];
+            return lines.join('\n') + (lines.length === 0 ? '' : '\n');
+        }),
     };
 };

package/dist/telemetry/command.js

@@ -1,7 +1,8 @@
 // `oars telemetry status|on|off|show`.
 import { statSync } from 'node:fs';
 import { CliError, ExitCode } from '../errors.js';
-import { consentOf, markNoticeShown, NOTICE, setEnabled } from './consent.js';
+import { consentOf, everShownNotice, markNoticeShown, NOTICE, setEnabled } from './consent.js';
+import { recordFirstRun } from './observe.js';
 import { readFleet, reportOf, textOf } from './report.js';
 import { readSpool, spoolPaths } from './spool.js';
 const STEP = 'telemetry';
@@ -15,6 +16,7 @@ const REASONS = {
     setting: 'by `oars telemetry on` or `off`',
     OARS_TELEMETRY: 'by OARS_TELEMETRY',
     DO_NOT_TRACK: 'by DO_NOT_TRACK',
+    region: "because this machine's time zone is in the EU, the EEA, or the UK",
 };
 const sizeOf = (path) => {
     try {
@@ -34,7 +36,7 @@ export const telemetryStatus = (deps) => {
         describe(consent),
         `The notice has ${consent.noticeShown ? '' : 'not '}been shown.`,
         `${String(events)} events (${String(bytes)} bytes) in ${dir}.`,
-        'Events are sent to the pool server in OARS_POOL_URL, else to the Many Oars pool (pool.manyoars.com, which is live), and only while telemetry is on and the notice has been shown.',
+        'Events are sent to the pool server in OARS_POOL_URL, else to the Many Oars pool (pool.manyoars.com, which is live), and only while telemetry is on and the notice has been shown, and never from a machine whose time zone is in the EU, the EEA, or the UK.',
     ];
     return { document: { ok: true, step: STEP, enabled: consent.enabled, reason: consent.reason, noticeShown: consent.noticeShown, events, bytes, dir }, text: lines.join('\n') };
 };
@@ -47,12 +49,16 @@ const save = (dir, enabled) => {
     }
 };
 export const telemetryOn = (deps) => {
-    const { dir } = runtimeOf(deps);
+    const runtime = runtimeOf(deps);
+    const { dir } = runtime;
+    const first = !everShownNotice(dir);
     save(dir, true);
-    // Running `on` is the notice: it is printed here and recorded as shown.
-    markNoticeShown(dir, deps.now);
+    // Running `on` is the notice: it is printed here and recorded as shown, so the run's own check finds it shown and sends the `first-run` event from here.
+    const marked = markNoticeShown(dir, deps.now);
     const consent = consentOf(deps.env, dir);
-    const override = consent.enabled ? '' : `\nIt stays off in this shell: ${consent.reason} is set.`;
+    if (first && marked && consent.enabled)
+        recordFirstRun(deps, runtime);
+    const override = consent.enabled ? '' : consent.reason === 'region' ? `\nIt stays off: this machine's time zone is in the EU, the EEA, or the UK.` : `\nIt stays off in this shell: ${consent.reason} is set.`;
     return { document: { ok: true, step: STEP, enabled: consent.enabled, reason: consent.reason, notice: NOTICE }, text: `Telemetry is on.\n${NOTICE}${override}` };
 };
 export const telemetryOff = (deps) => {

package/dist/telemetry/consent.d.ts

@@ -1,6 +1,8 @@
+/** 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 declare const NOTICE_VERSION = 2;
 /** Printed once on stderr, on the first run that is not a hook; also what `oars telemetry on` prints. */
 export declare const NOTICE: string;
-export type Reason = 'default' | 'setting' | 'OARS_TELEMETRY' | 'DO_NOT_TRACK';
+export type Reason = 'default' | 'setting' | 'OARS_TELEMETRY' | 'DO_NOT_TRACK' | 'region';
 export interface Consent {
     enabled: boolean;
     /** Which switch decided `enabled`. */
@@ -8,10 +10,14 @@ export interface Consent {
     /** The notice was printed (or `on` was run) on this install. */
     noticeShown: boolean;
 }
-export declare const consentOf: (env: NodeJS.ProcessEnv, dir: string) => Consent;
+export declare const consentOf: (env: NodeJS.ProcessEnv, dir: string, zone?: string | undefined) => Consent;
 /** Saves `on` or `off`. Throws when the folder cannot be written: the command that asked reports it. */
 export declare const setEnabled: (dir: string, enabled: boolean) => void;
 /** 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 declare const markNoticeShown: (dir: string, now: () => number) => boolean;
+/** Whether this install has ever been shown any notice (an older version included). */
+export declare const everShownNotice: (dir: string) => boolean;
+/** The notice version this install was shown, or `undefined` when none (or an unreadable file). */
+export declare const shownNoticeVersion: (dir: string) => number | undefined;
 /** Whether the sender (t875) may send: telemetry on, and the notice shown. Off, or notice not yet shown, means nothing sends. */
-export declare const telemetrySendAllowed: (env: NodeJS.ProcessEnv, dir: string) => boolean;
+export declare const telemetrySendAllowed: (env: NodeJS.ProcessEnv, dir: string, zone?: string | undefined) => boolean;

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, 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. Once a night 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. 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, which is live), 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;