@manyoars/oars 0.4.1 → 0.5.1

package/dist/sessions/store.js

@@ -1,3 +1,4 @@
+import { derivedSalt } from './machine-ids.js';
 import { createHash, randomBytes, randomUUID } from 'node:crypto';
 import { createReadStream } from 'node:fs';
 import { performance } from 'node:perf_hooks';
@@ -15,6 +16,7 @@ import { callPositions, captureSession } from './extract.js';
 import { foldToolRows, withoutReplays } from './fold.js';
 import { asRepoSize } from './public-vocabulary.js';
 import { makeRepoIdentity, makeRepoRoot } from './repo-root.js';
+import { mkdirOwnerOnly } from './owner-only.js';
 import { makeRedactor } from './redact.js';
 import { CAPTURE_VERSION, EXTRACTOR_VERSION, OLDEST_READABLE_CAPTURE, } from './schema.js';
 const isMissing = (error) => error instanceof Error && 'code' in error && error.code === 'ENOENT';
@@ -25,6 +27,7 @@ export const paths = (storeDir) => ({
     skeletons: join(storeDir, 'skeletons'),
     calls: join(storeDir, 'mcp-calls.jsonl'),
     hookCalls: join(storeDir, 'hook-calls.jsonl'),
+    hookRows: join(storeDir, 'hook-rows.jsonl'),
     pipelineRuns: join(storeDir, 'pipeline-runs.jsonl'),
     salt: join(storeDir, 'salt'),
     raw: join(storeDir, 'raw'),
@@ -80,14 +83,16 @@ export const readState = async (storeDir) => {
                 for (const [entry, mode] of Object.entries(pool.folders))
                     if (mode === 'skeleton' || mode === 'off')
                         folders[entry] = mode;
-            return { files, redactDomains: domains, allow, pool: { rawConsent: pool.rawConsent === 'granted' || pool.rawConsent === 'declined' ? pool.rawConsent : null, folders } };
+            const yesVersion = typeof pool.rawConsentVersion === 'string' && pool.rawConsentVersion !== '' ? pool.rawConsentVersion : null;
+            const granted = pool.rawConsent === 'granted' && yesVersion !== null;
+            return { files, redactDomains: domains, allow, pool: { rawConsent: granted ? 'granted' : pool.rawConsent === 'declined' ? 'declined' : null, rawConsentVersion: granted ? yesVersion : null, withdrawalPending: pool.withdrawalPending === true && !granted, folders } };
         }
     }
     catch (error) {
         if (!isMissing(error) && !(error instanceof SyntaxError))
             throw error;
     }
-    return { files: {}, redactDomains: [], allow: [], pool: { rawConsent: null, folders: {} } };
+    return { files: {}, redactDomains: [], allow: [], pool: { rawConsent: null, rawConsentVersion: null, withdrawalPending: false, folders: {} } };
 };
 /** Changes the pool choices under the store lock, so a deposit running at the same time keeps them (it writes the state it read). */
 export const updatePoolChoices = (storeDir, change) => withLock(storeDir, async (held) => {
@@ -111,7 +116,7 @@ export const writeAtomic = async (file, text) => {
     await rename(temp, file);
 };
 export { slugOf };
-const projectFolders = async (projectsRoot) => {
+export const projectFolders = async (projectsRoot) => {
     try {
         return (await readdir(projectsRoot, { withFileTypes: true })).filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort();
     }
@@ -164,6 +169,7 @@ const contextFor = async (runtime, state, now, held) => {
         domains: [...state.redactDomains].sort(),
         redact: makeRedactor(state.redactDomains),
         salt,
+        repoSalt: runtime.repoSalt ?? derivedSalt(salt.salt, 'repoKey/1'),
         repoRoot: makeRepoRoot(),
         repoIdentity: makeRepoIdentity(),
         captureRuntime: captureRuntime(),
@@ -175,7 +181,7 @@ const contextFor = async (runtime, state, now, held) => {
         now,
     };
 };
-const mainTranscript = (folder, name) => ({ file: join(folder, name), session: name.slice(0, -'.jsonl'.length), relative: name });
+export const mainTranscript = (folder, name) => ({ file: join(folder, name), session: name.slice(0, -'.jsonl'.length), relative: name });
 export const listDir = async (dir) => {
     try {
         return (await readdir(dir, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name));
@@ -221,7 +227,7 @@ export const subagentFiles = async (folder, sessions) => {
     return found;
 };
 // The subagent transcripts of the given sessions, each with its `.meta.json` read.
-const subagentTranscripts = async (folder, sessions) => {
+export const subagentTranscripts = async (folder, sessions) => {
     const found = [];
     for (const { dir, path, parent, name } of await subagentFiles(folder, sessions)) {
         const agent = name.slice(0, -'.jsonl'.length);
@@ -340,6 +346,7 @@ const depositFile = async (context, project, transcript) => {
         bytes: info.size,
         redact: context.redact,
         salt: context.salt.salt,
+        repoSalt: context.repoSalt,
         sid: context.salt.sid,
         repoRoot: context.repoRoot,
         repoIdentity: context.repoIdentity,
@@ -439,6 +446,24 @@ const commitCapture = async (context, key, extract, cursor) => {
     await writeAtomic(join(files.skeletons, `${extract.session.session}.json`), JSON.stringify(extract.skeleton));
     context.state.files[key] = { ...cursor, v: CAPTURE_VERSION, s: context.salt.sid, d: context.domains, repoSize: extract.session.frame?.stack.size ?? null };
 };
+/**
+ * Records that a session is superseded: its capture of no turns, marked with the session that holds them now, appended as the next rev (the log is never edited), and its
+ * skeleton removed, since a skeleton is derived and a reader of skeletons would count the session. The cursor records it, so a repeat deposit adds nothing. The nested agents of the
+ * session are read again, since their parent is now the merged session.
+ */
+const commitSupersede = async (context, key, extract, by, cursor) => {
+    const files = paths(context.runtime.storeDir);
+    extract.session.supersededBy = by;
+    await requireHold(context.held);
+    await appendFile(files.observations, `${JSON.stringify(extract.session)}\n`, { mode: 0o600 });
+    await requireHold(context.held);
+    await rm(join(files.skeletons, `${extract.session.session}.json`), { force: true });
+    context.state.files[key] = { ...cursor, v: CAPTURE_VERSION, s: context.salt.sid, d: context.domains, repoSize: null };
+    // A nested agent's id is `<trace>-<span>`, so it stays when its parent moves to the merged session, and its spans may not change: stale its cursor so the next read names the new parent.
+    for (const [other, entry] of Object.entries(context.state.files))
+        if (other.startsWith(`${key}-`))
+            entry.v = '';
+};
 /** Another deposit holds the store lock and the wait ran out: the one failure the Stop hook defers instead of counting as a failed run. */
 export class StoreLockedError extends CliError {
     constructor() {
@@ -496,13 +521,19 @@ const breakStale = async (lock, staleMs) => {
         await rm(guard, { force: true });
     }
 };
+/**
+ * What a command a person typed waits for the store lock (`deposit --deny`, the pool choices). The background sweep starts after any command and its deposit
+ * holds the lock for the whole run, which a full re-capture stretches past 10 minutes, so a short wait made `--deny` fail right when the hold window
+ * wants it to work; two minutes is the wait the send lock gives. The hook path keeps `HOOK_LOCK`: a hook must not block a session.
+ */
+const FOREGROUND_LOCK = { waitMs: 120_000, staleMs: 600_000 };
 /**
  * Runs `work` as the only writer of `state.json` and the observations file. The SessionEnd hooks of parallel sessions and the nightly
  * run each read, extract, and rewrite `state.json`; without this one's `files` and `allow` entries are lost to another's write.
  */
-export const withLock = async (storeDir, work, options = { waitMs: 10_000, staleMs: 600_000 }) => {
+export const withLock = async (storeDir, work, options = FOREGROUND_LOCK) => {
     const lock = join(storeDir, 'store.lock');
-    await mkdir(storeDir, { recursive: true });
+    await mkdirOwnerOnly(storeDir);
     const started = Date.now();
     // The token names this claim, so a holder whose lock was broken cannot delete the next holder's lock when it ends.
     const token = `${String(process.pid)} ${randomUUID()}`;
@@ -654,11 +685,11 @@ const depositLocked = async (runtime, options, holds, trace) => {
     return result;
 };
 /** The table in force: the runtime's own (a test's), else every source. */
-const sourcesOf = (runtime) => runtime.sources ?? SOURCES;
+export const sourcesOf = (runtime) => runtime.sources ?? SOURCES;
 /** A source's name is the first `state.json` key segment, and no project folder uses it, so the Claude Code walk skips it. */
 const isSource = (table, name) => table.some((source) => source.name === name);
 /** The roots the runtime names, by source name; `cursorRoot` stays the alias of the Cursor entry. */
-const sourceRoots = (runtime) => new Map(Object.entries({ ...(runtime.cursorRoot === undefined ? {} : { cursor: runtime.cursorRoot }), ...runtime.sourceRoots }));
+export const sourceRoots = (runtime) => new Map(Object.entries({ ...(runtime.cursorRoot === undefined ? {} : { cursor: runtime.cursorRoot }), ...runtime.sourceRoots }));
 /** Reports an unreadable source store or file, once per reason: the full path for the terminal, the base name for the hook-call record. */
 const noteReason = (counts, file, reason) => {
     const line = `${file}: ${reason}`;
@@ -696,16 +727,23 @@ const readSource = async (context, source, root, result, trace) => {
     for (const entry of store.unreadable)
         noteReason(counts, entry.file, entry.reason);
     try {
-        for (const session of store.sessions) {
+        // The superseded sessions first: committing one stales the cursors of its nested agents, which are then read in this same deposit.
+        const ordered = [...store.sessions.filter((session) => session.supersededBy !== undefined), ...store.sessions.filter((session) => session.supersededBy === undefined)];
+        for (const session of ordered) {
             const key = `${source.name}/${session.id}`;
             const previous = context.state.files[key];
+            // A session this store never held has nothing to supersede.
+            if (session.supersededBy !== undefined && previous === undefined)
+                continue;
             if (previous !== undefined &&
                 previous.size === session.size &&
                 previous.mtimeMs === session.mtimeMs &&
                 previous.v === CAPTURE_VERSION &&
                 previous.s === context.salt.sid &&
                 sameSet(previous.d, context.domains)) {
-                result.unchanged += 1;
+                // A superseded session is recorded once and is no file of its own, so it is not one more file left unchanged.
+                if (session.supersededBy === undefined)
+                    result.unchanged += 1;
                 continue;
             }
             let text;
@@ -729,6 +767,7 @@ const readSource = async (context, source, root, result, trace) => {
                 bytes: Buffer.byteLength(text),
                 redact: context.redact,
                 salt: context.salt.salt,
+                repoSalt: context.repoSalt,
                 sid: context.salt.sid,
                 repoRoot: context.repoRoot,
                 repoIdentity: context.repoIdentity,
@@ -739,6 +778,10 @@ const readSource = async (context, source, root, result, trace) => {
             });
             // The input names the frame and the action table; the session record carries the harness for `harnessOf`, `books --by harness`, and `measure`.
             extract.session.harness = source.harness;
+            if (session.supersededBy !== undefined) {
+                await commitSupersede(context, key, extract, `${source.name}-${session.supersededBy}`, { size: session.size, mtimeMs: session.mtimeMs, rev });
+                continue;
+            }
             await commitCapture(context, key, extract, { size: session.size, mtimeMs: session.mtimeMs, rev });
             tally(trace, extract, session.subagent !== undefined);
             if (session.subagent === undefined) {
@@ -918,7 +961,7 @@ const rawRelatives = async (dir, path) => {
     }
     return found.sort();
 };
-const HOOK_LOCK = { waitMs: 3_000, staleMs: 600_000 };
+export const HOOK_LOCK = { waitMs: 500, staleMs: 600_000 };
 /**
  * Deposits one transcript, as the SessionEnd hook does: only from a folder that earlier `--allow` entries name, and idempotent by size and
  * mtime. It does not rebuild `derived.json` or the hook index (that is a whole-store pass; the nightly run does it), so it stays fast.
@@ -927,7 +970,7 @@ const HOOK_LOCK = { waitMs: 3_000, staleMs: 600_000 };
  */
 export const depositSession = async (runtime, transcript, now, trace) => {
     try {
-        // The hook path waits 3 s for the lock, well under the harness's 30 s ceiling on the hook (install.ts), so a SessionEnd behind the nightly deposit cannot hold session exit.
+        // The hook path waits under a second for the lock, well under the harness's 30 s ceiling on the hook (install.ts), so a SessionEnd behind the sender's sweep cannot hold session exit; `deferSession` covers a lock still held.
         return await withLock(runtime.storeDir, (held) => depositSessionLocked(runtime, transcript, now, held, trace), HOOK_LOCK);
     }
     catch (error) {
@@ -1091,12 +1134,20 @@ const internTool = (tool, intern) => ({
     target: tool.target === null ? null : intern(tool.target),
     ...(tool.segments === undefined ? {} : { segments: tool.segments.map((segment) => ({ ...segment, run: intern(segment.run) })) }),
 });
+const withoutMessageUsage = (session) => {
+    if (session.messageUsage === undefined)
+        return session;
+    const rest = { ...session };
+    Reflect.deleteProperty(rest, 'messageUsage');
+    return rest;
+};
 /**
  * The store as a reader sees it: for each session only the highest `rev`. A version-3 or later session is derived here from its capture records
  * (EXTRACTOR_VERSION rules); a session whose last deposit was version 2 keeps the prompt and error lines that deposit wrote.
  * `afterFirstPass` runs between the two passes over the log: a seam for the test that compacts the log there.
+ * `options.messageUsage` keeps the per-message usage entries on each session record; without it they are dropped as the record is read.
  */
-export const loadStore = async (storeDir, afterFirstPass) => {
+export const loadStore = async (storeDir, afterFirstPass, options = {}) => {
     // Two passes, so a superseded record is never held: the first keeps one number per session, the second keeps only the records at that rev.
     // A re-capture leaves the old copies in the log until a compaction, and holding them as well doubled the heap of every read.
     // Both passes read one open file: a lock-free reader can meet a compaction between them, and a second open would see the compacted log, where
@@ -1119,7 +1170,7 @@ export const loadStore = async (storeDir, afterFirstPass) => {
             if (observation === undefined || observation.rev !== latest.get(observation.session))
                 continue;
             if (observation.kind === 'session')
-                of(observation.session).session = observation;
+                of(observation.session).session = options.messageUsage === true ? observation : withoutMessageUsage(observation);
             else if (observation.kind === 'user-prompt')
                 of(observation.session).prompts.push(observation);
             else if (observation.kind === 'tool')
@@ -1138,7 +1189,8 @@ export const loadStore = async (storeDir, afterFirstPass) => {
     const redact = makeRedactor((await readState(storeDir)).redactDomains);
     const agents = [];
     for (const { session: written, prompts, tools: writtenTools, errorLines: writtenErrorLines } of captured.values()) {
-        if (written === undefined)
+        // A superseded session holds no turns: the session that folded it in holds them.
+        if (written === undefined || written.supersededBy !== undefined)
             continue;
         // One tool call is one record: a replay an older capture wrote beside the call is folded here.
         const folded = foldToolRows(writtenTools, writtenErrorLines);

package/dist/sessions/try-demo.d.ts

@@ -0,0 +1,8 @@
+/** 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 declare const DEMO_CWD: string;
+/** The folder Claude Code would name for `DEMO_CWD` under `~/.claude/projects`. */
+export declare const DEMO_FOLDER: string;
+/** An error the three demo sessions all hit, as a stranger would paste it. */
+export declare const DEMO_ERROR = "unexpected EOF while looking for matching quote";
+/** Writes the demo sessions under `<projectsRoot>/<DEMO_FOLDER>/`, the layout Claude Code uses. */
+export declare const writeDemoSessions: (projectsRoot: string) => Promise<void>;

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;
 };