@manyoars/oars 0.4.1 → 0.5.2

package/dist/sessions/schema.js

@@ -30,6 +30,36 @@
 // reads, not moved ones. A Copilot CLI session with rotated `events.N.jsonl` archives is now read as one session, so its `prompts`, `tools`, `lines`, and skeleton move; one
 // with no archives is unchanged. EXTRACTOR stays 11. A version-16 store's next deposit captures every transcript again from the harness or `raw/`.
 //
+// Version 32 (CAPTURE 32) is the machine repoKey salt: `repoKey` is derived from the machine's own salt, so every stored repoKey moves and an older store's next deposit captures every transcript again.
+//
+// Version 35 (CAPTURE 35) adds two optional fields to a tool call: `digests` (an Edit, MultiEdit, or Write call's old and new text, each as a digest) and `restores` (the files a `git restore` or `git checkout --` names, hashed as `target` is), and a
+// `git restore` path also gives its file and folder names to `names`. It changes no value captured before; an older store's next deposit captures every transcript again, and a call of an older record has none.
+//
+// Version 33 (CAPTURE 33) adds the optional `names` to a tool call (`argNamesOf`, `call-shape.ts`): the name tokens its values hold, each with its kind, never a value. It changes no value captured before; an older store's next deposit captures every transcript again,
+// and a call of an older record has none.
+//
+// Version 34 (CAPTURE 34) adds the optional `templates` to a shell call (`templatesOf`, `call-shape.ts`): one template per command, its program, subcommand, and flags with every literal argument as a typed slot, never an argument; and the optional `diffShape` to an
+// edit (`diffShapeOf`): the shapes of the change from a closed list, never its text. It changes no value captured
+// before; an older store's next deposit captures every transcript again, and a call of an older record has none.
+//
+// Version 31 (CAPTURE 31) writes a Codex `token_count` event's `input` and `output` only when the event reported them, as the cache categories already were, so a partial event leaves the other
+// unobserved and not a measured zero (`usageObserved`). It changes a stored value of a Codex session; an older store's next deposit captures every transcript again.
+//
+// Version 30 (CAPTURE 30) adds the optional `local`, `dotClaude`, and `rules` counts to `loadedInstructions`: how many `CLAUDE.local.md`, `.claude/CLAUDE.md`, and `.claude/rules/` files the transcript shows
+// loaded from the working folder. It changes no other value; an older store's next deposit captures every transcript again, and a record from before then reads those three as unknown.
+//
+// Version 29 (CAPTURE 29) adds the optional `loadedInstructions` to the session record: counts of the instruction files the transcript shows loaded, by level, never a path. It changes no value captured
+// before; an older store's next deposit captures every transcript again, and a session recorded before then has none until it is.
+//
+// Version 28 (CAPTURE 28) adds the optional `messageUsage` to the session record: one entry per distinct model message (a Claude Code `message.id`, a Codex response), holding that message's token counts,
+// the ids of the tool calls it made, and, for Codex, the plan percent used and window length when the event held a rate-limit block (`MessageUsage`). Numbers and ids only; the counts are never split across the
+// message's calls. For a Codex event that did not report a cache category, that category is no longer observed, so `usageObserved` omits it and the skeleton and pool wire send null where they sent a zero bucket; no other value changes and EXTRACTOR stays as it is. A version-27 store's next deposit captures every transcript again, and a session recorded before then has no `messageUsage`
+// until it is: nothing reads the field back into the older record. A file that reports no usage gets none either way.
+//
+// Version 27 (CAPTURE 27) adds three optional fields to a tool call (`call-shape.ts`), each computed from the input at capture and stored as closed-list members, never a value: `argFeatures` (per key, the value's size and,
+// for a path, its depth, extension class, and folder kind, for a pattern what it uses), `argValues` (a boolean, or a string its tool's closed list holds), and `changeKind` (what changed from the previous call of the
+// same tool in the prompt). It changes no value captured before, so EXTRACTOR stays as it is; a version-26 store's next deposit captures every transcript again, and a call of an older record has none of them.
+//
 // Version 24 (CAPTURE 24, t903) changes three stored values and no field name: a step identity's skill-run name, host, and pull's package name are kept as they are after the operator's redaction (`redactDomains`, the secret and email patterns, the name shape, and the 128-character cap still apply; the operator's exclusion terms are applied at the deposit's gate, not at capture), where before each was `<literal>` unless a public list held it. A store opened at version 23 or older keeps its `<literal>` values until its next deposit captures every transcript again from the harness or `raw/`; the tool record's `steps` moves from class P to class A because those names can be private.
 //
 // Version 23 (CAPTURE 23) keeps a `git checkout` step's target class, `target` `path` or `word` (never the target's text), so the `revert` rule can tell `git checkout -- src/a.ts` and `git checkout --ours src/a.ts` (a
@@ -88,7 +118,7 @@
 // harness versions, and tool names (an MCP name's part after its prefix is redacted). `redact` masks secrets by pattern and entropy, emails, and the
 // organization domains the operator names. The skeleton holds hashes only.
 /** Stamped `cv` on every captured record. Bump it when the captured field list changes or a stored value of an existing captured record or skeleton changes: a bump re-reads every transcript. */
-export const CAPTURE_VERSION = '25';
+export const CAPTURE_VERSION = '35';
 /** Capture versions the reader derives from. A version-3 record is upgraded on read; a newer one is read for the fields this code knows. */
 export const OLDEST_READABLE_CAPTURE = 3;
 /** Stamped `v` on every derived record. A bump re-derives from the log; no transcript is read. */

package/dist/sessions/session-shape.d.ts

@@ -1,4 +1,4 @@
-import type { Harness } from './schema.js';
+import type { Harness, LoadedInstructions } from './schema.js';
 type Obj = {
     [key: string]: unknown;
 };
@@ -52,6 +52,7 @@ export interface SessionTrust {
     unattendedRun?: number[];
 }
 export interface SessionShape {
+    loadedInstructions?: LoadedInstructions;
     setup?: SessionSetup;
     funnel?: SessionFunnel;
     trust?: SessionTrust;

package/dist/sessions/session-shape.js

@@ -5,6 +5,7 @@
 //
 // One collector per transcript, fed line by line by `captureSession`. It reads the Claude Code line shapes (a census of 2.1.312 to 2.1.318) and
 // one neutral line an adapter may write for a harness whose records are not Claude-shaped (`oars-tools`).
+import { loadedInstructionsOf } from './load-status.js';
 const isObj = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
 const str = (value) => (typeof value === 'string' ? value : undefined);
 const names = (value) => (Array.isArray(value) ? value.filter((item) => typeof item === 'string' && item !== '') : []);
@@ -90,6 +91,8 @@ export const createShape = (harness, stored, options) => {
     const stopCommands = new Set();
     let stopSeen = false;
     const memory = new Map();
+    let instructionFiles;
+    let cwd;
     const plugins = new Set();
     /** Every name offered or removed, in order: the last event on a name decides which side it ends on. */
     const standing = new Map();
@@ -201,6 +204,15 @@ export const createShape = (harness, stored, options) => {
                     stopSeen = true;
             }
         }
+        else if (kind === 'instructions' && instructionFiles === undefined && Array.isArray(a.files)) {
+            // The first record only: a resumed session logs the set again, and the snapshot it joins with is that session's first.
+            instructionFiles = a.files.flatMap((file) => {
+                if (!isObj(file))
+                    return [];
+                const path = str(file.path);
+                return path === undefined ? [] : [{ path, type: str(file.type) ?? '' }];
+            });
+        }
         else if (kind === 'nested_memory' && isObj(a.content) && typeof a.content.content === 'string') {
             // The same file comes again when the harness reloads it, so one path counts once.
             const key = str(a.path) ?? str(a.content.path) ?? `#${String(memory.size)}`;
@@ -219,6 +231,7 @@ export const createShape = (harness, stored, options) => {
             // A sidechain line is a subagent's own, not the main session's setup.
             if (at.side)
                 return;
+            cwd ??= str(line.cwd);
             const type = str(line.type);
             if (type === 'permission-mode')
                 mode(line.permissionMode);
@@ -322,6 +335,8 @@ export const createShape = (harness, stored, options) => {
                 setup.instructionBytes = [...memory.values()].reduce((sum, bytes) => sum + bytes, 0);
             if (Object.keys(setup).length > 0)
                 out.setup = setup;
+            if (instructionFiles !== undefined && cwd !== undefined)
+                out.loadedInstructions = loadedInstructionsOf(instructionFiles, cwd);
             const funnel = {};
             // Two names that redact to one form are one tool, as `tools` keys it.
             const sideOf = (which) => [...new Set([...standing].filter(([, side]) => side === which).map(([name]) => stored(name)))].sort();

package/dist/sessions/sources.d.ts

@@ -11,13 +11,22 @@ export interface SourceSession {
     mtimeMs: number;
     /** Set when the session is a spawned agent's: it is deposited as a subagent of its parent, so session counts stay main sessions. */
     subagent?: SubagentOrigin;
+    /**
+     * Set when a later read folded this session into another (`<id>` of that one): the deposit records the supersede for a session it already holds, with no transcript,
+     * and records nothing for one it never held. `size` and `mtimeMs` are 0, a cursor no read session has.
+     */
+    supersededBy?: string;
 }
 export interface SourceStore {
     sessions: SourceSession[];
     /** The session as transcript text for `captureSession`; throws when it cannot be read. */
     transcript: (session: SourceSession) => string | Promise<string>;
+    /** True when the session's file holds only the harness's own head records and no turn, so `sessions verify` counts it as empty, not unreadable; absent when the format has no such form. */
+    headOnly?: (session: SourceSession) => boolean | Promise<boolean>;
     /** Sessions skipped because their id is not a safe file name, counted so the skip is never silent. */
     rejected: number;
+    /** Files the reader dropped before they were sessions that held records in a shape it does not know; only `sessions verify` reads it, as seen and unreadable. Absent when the format has no such drop. */
+    shapeMoved?: number;
     /** Items that could not be inspected, warned about once each and never fatal; `reason` names no path. */
     unreadable: readonly {
         file: string;

package/dist/sessions/sources.js

@@ -7,7 +7,7 @@ import { copilotRoot, openCopilotStore } from './copilot.js';
 import { cursorRoot, openCursorStore } from './cursor.js';
 import { grokRoot, openGrokStore } from './grok.js';
 import { geminiRoot, openGeminiStore } from './gemini.js';
-import { openPiStore, piRoot } from './pi.js';
+import { openPiStore, piSessionsDir } from './pi.js';
 import { openOtelStore, otelRoot } from './otel.js';
 import { opencodeRoot, openOpencodeStore } from './opencode.js';
 import { openVscodeCopilotStore, vscodeAppData } from './vscode-copilot.js';
@@ -59,6 +59,7 @@ const codex = {
                 ...(session.parent === null ? {} : { subagent: { parent: `codex-${session.parent}`, agentType: session.agentRole, spawnedBy: null } }),
             })),
             transcript: async (session) => await store.transcript(need(byId.get(session.id))),
+            headOnly: async (session) => await store.headOnly(need(byId.get(session.id))),
             rejected: store.rejected,
             unreadable: store.unreadable,
             where: (session) => byId.get(session.id)?.file ?? root,
@@ -80,6 +81,7 @@ const copilot = {
         return {
             sessions: store.sessions.map((session) => ({ id: session.id, folder: session.folder, size: session.size, mtimeMs: session.mtimeMs })),
             transcript: async (session) => await store.transcript(need(byId.get(session.id))),
+            headOnly: async (session) => await store.headOnly(need(byId.get(session.id))),
             rejected: store.rejected,
             unreadable: store.unreadable,
             where: (session) => byId.get(session.id)?.file ?? root,
@@ -108,6 +110,7 @@ const gemini = {
             })),
             transcript: async (session) => await store.transcript(need(byId.get(session.id))),
             rejected: store.rejected,
+            shapeMoved: store.shapeMoved,
             unreadable: store.unreadable,
             where: (session) => byId.get(session.id)?.file ?? root,
             close: () => undefined,
@@ -155,6 +158,7 @@ const opencode = {
                 ...(session.parent === null ? {} : { subagent: { parent: `opencode-${session.parent}`, agentType: session.agent, spawnedBy: null } }),
             })),
             transcript: (session) => store.transcript(need(byId.get(session.id))),
+            headOnly: (session) => store.headOnly(need(byId.get(session.id))),
             rejected: store.rejected,
             unreadable: [],
             where: () => join(root, 'opencode.db'),
@@ -166,8 +170,8 @@ const pi = {
     name: 'pi',
     harness: 'pi',
     label: 'Pi',
-    root: (_platform, env, home) => piRoot(env, home),
-    storeFile: (root) => join(root, 'sessions'),
+    root: (_platform, env, home) => piSessionsDir(env, home),
+    storeFile: (root) => root,
     open: async (root) => {
         const store = await openPiStore(root);
         if (store === undefined)
@@ -176,6 +180,7 @@ const pi = {
         return {
             sessions: store.sessions.map((session) => ({ id: session.id, folder: session.folder, size: session.size, mtimeMs: session.mtimeMs })),
             transcript: async (session) => await store.transcript(need(byId.get(session.id))),
+            headOnly: async (session) => await store.headOnly(need(byId.get(session.id))),
             rejected: store.rejected,
             unreadable: store.unreadable,
             where: (session) => byId.get(session.id)?.file ?? root,
@@ -197,6 +202,7 @@ const vscodeCopilot = {
         return {
             sessions: store.sessions.map((session) => ({ id: session.id, folder: session.folder, size: session.size, mtimeMs: session.mtimeMs })),
             transcript: async (session) => await store.transcript(need(byId.get(session.id))),
+            headOnly: async (session) => await store.headOnly(need(byId.get(session.id))),
             rejected: store.rejected,
             unreadable: store.unreadable,
             where: (session) => byId.get(session.id)?.files[0] ?? root,
@@ -218,9 +224,14 @@ const otel = {
             return undefined;
         const byId = new Map(store.sessions.map((session) => [session.id, session]));
         return {
-            sessions: store.sessions.map((session) => ({ id: session.id, folder: session.folder, size: session.size, mtimeMs: session.mtimeMs, ...(session.subagent === undefined ? {} : { subagent: session.subagent }) })),
-            transcript: (session) => store.transcript(need(byId.get(session.id))),
+            sessions: [
+                ...store.sessions.map((session) => ({ id: session.id, folder: session.folder, size: session.size, mtimeMs: session.mtimeMs, ...(session.subagent === undefined ? {} : { subagent: session.subagent }) })),
+                ...store.superseded.map((entry) => ({ id: entry.id, folder: null, size: 0, mtimeMs: 0, supersededBy: entry.by })),
+            ],
+            transcript: (session) => (session.supersededBy === undefined ? store.transcript(need(byId.get(session.id))) : ''),
+            headOnly: (session) => session.supersededBy === undefined && store.headOnly(need(byId.get(session.id))),
             rejected: store.rejected,
+            shapeMoved: store.shapeMoved,
             unreadable: store.unreadable,
             where: (session) => byId.get(session.id)?.file ?? root,
             close: () => undefined,

package/dist/sessions/steps.js

@@ -1,16 +1,17 @@
 // The step log: `pipeline-runs.jsonl`, one row per run of a pipeline step, appended when the step ends (runtime-commons pipeline spec 3.1).
 // Local only: it sits in the store directory beside `hook-calls.jsonl`, and `measure` prints the spec 3.2 counters from it.
 import { randomUUID } from 'node:crypto';
-import { appendFile, mkdir, readFile } from 'node:fs/promises';
+import { appendFile, readFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { performance } from 'node:perf_hooks';
 import { CliError, ExitCode } from '../errors.js';
+import { mkdirOwnerOnly } from './owner-only.js';
 import { makeRedactor } from './redact.js';
 import { CAPTURE_VERSION, EXTRACTOR_VERSION, parseStepRow } from './schema.js';
 import { digest, newTrace, paths, readRedactDomains } from './store.js';
 export const newContext = (storeDir, now, trigger) => ({ storeDir, now, run: randomUUID(), trigger });
 export const appendStep = async (storeDir, row) => {
-    await mkdir(storeDir, { recursive: true });
+    await mkdirOwnerOnly(storeDir);
     await appendFile(paths(storeDir).pipelineRuns, `${JSON.stringify(row)}\n`, { mode: 0o600 });
 };
 export const readSteps = async (storeDir) => {

package/dist/sessions/store.d.ts

@@ -3,6 +3,7 @@ import { type FileHandle } from 'node:fs/promises';
 import { CliError } from '../errors.js';
 import { slugOf } from './allow.js';
 import { type Source } from './sources.js';
+import { type SubagentOrigin } from './extract.js';
 import { type RepoSize } from './public-vocabulary.js';
 import { type DerivedRecords, type ErrorObservation, type PromptObservation, type RecallCall, type SessionObservation, type SignatureRecord, type StepCounts, type Skeleton, type ToolObservation } from './schema.js';
 /** Where the store and the operator's Claude Code logs are; `bin.ts` fills it from the environment. */
@@ -21,12 +22,18 @@ export interface SessionsRuntime {
     sources?: readonly Source[];
     /** Where the account's salt comes from; absent means this machine's own (`localSalt`). The seam an account identity replaces (M4). */
     accountSalt?: (storeDir: string) => Promise<AccountSalt>;
+    /** The salt repository keys are hashed under; a machine takes it from its enrollment (`OARS_REPO_SALT`). Absent means the one derived from the account salt, as the trusted machine computes it. */
+    repoSalt?: string;
     /** The fresh single-turn reader behind `gold arms`; absent in a run that has none. */
     evaluator?: GoldEvaluator | undefined;
     stdin: NodeJS.ReadableStream;
     stdout: {
         write: (text: string) => unknown;
     };
+    /** Only its `isTTY` is read: the covenant screen is written to stderr, so a person is at a terminal only when stderr is one too. */
+    stderr?: {
+        isTTY?: boolean | undefined;
+    } | undefined;
 }
 interface FileState {
     size: number;
@@ -55,9 +62,15 @@ export interface State {
     /** What the person chose about sending to a pool: the raw-copy consent and the folders switched down. Never read by capture. */
     pool: PoolChoices;
 }
-/** The answer to the raw-copy prompt (`granted`, `declined`, or not asked yet) and the per-folder switches (an `--allow`-style entry mapped to what it may send). */
+/**
+ * The answer to the raw-copy prompt (`granted`, `declined`, or not asked yet) and the per-folder switches (an `--allow`-style entry mapped to what it may send).
+ * A yes carries the covenant version in force when it was given, because the prompt names the sale and training use that covenant states. A yes with no version predates that wording and reads as not asked.
+ */
 export interface PoolChoices {
     rawConsent: 'granted' | 'declined' | null;
+    rawConsentVersion: string | null;
+    /** True from a typed no that the pool was not told, while this machine held a yes, until the pool hears the withdrawal or a new yes is typed: the pool may still hold the yes, so a rerun of the no must not read the local `declined` as nothing to tell. */
+    withdrawalPending: boolean;
     folders: {
         [entry: string]: FolderSend;
     };
@@ -70,6 +83,7 @@ export declare const paths: (storeDir: string) => {
     skeletons: string;
     calls: string;
     hookCalls: string;
+    hookRows: string;
     pipelineRuns: string;
     salt: string;
     raw: string;
@@ -142,6 +156,7 @@ export interface DepositResult {
     /** Allowed names that matched no project folder. */
     missing: string[];
 }
+export declare const projectFolders: (projectsRoot: string) => Promise<string[]>;
 /** What a deposit never reads: project folders that hold transcripts but that no `--allow` entry names. */
 export interface SkippedScope {
     folders: number;
@@ -156,6 +171,18 @@ export interface SkippedScope {
  * only, never a transcript, so `verify` and `books` can say what the store does not hold.
  */
 export declare const skippedFolders: (runtime: SessionsRuntime) => Promise<SkippedScope>;
+/** A transcript to deposit: a main session file, or a subagent's under `<session>/subagents/` (register A24). */
+export interface Transcript {
+    file: string;
+    /** `<session>`, or `<parent>~agent-x` / `<parent>~wf_y~agent-x` for a subagent. */
+    session: string;
+    /** The path under the project folder, the key in `state.json`. */
+    relative: string;
+    subagent?: SubagentOrigin;
+    /** Read from the store's own archive because the harness no longer has the transcript; it is not archived again. */
+    fromRaw?: boolean;
+}
+export declare const mainTranscript: (folder: string, name: string) => Transcript;
 export declare const listDir: (dir: string) => Promise<import("fs").Dirent<string>[]>;
 interface SubagentFile {
     dir: string;
@@ -165,6 +192,7 @@ interface SubagentFile {
     name: string;
 }
 export declare const subagentFiles: (folder: string, sessions: readonly string[]) => Promise<SubagentFile[]>;
+export declare const subagentTranscripts: (folder: string, sessions: readonly string[]) => Promise<Transcript[]>;
 /** The session folders under a project folder: each may hold subagent transcripts, even when its main transcript is gone. */
 export declare const sessionFolders: (folder: string) => Promise<string[]>;
 /** What a derive pass read and wrote, for the step log (spec 3.1 `in` and `out`, 4.2 `key`). */
@@ -234,6 +262,10 @@ export declare class StoreLockLostError extends CliError {
  */
 export declare const withLock: <T>(storeDir: string, work: (held: LockHold) => Promise<T>, options?: LockOptions) => Promise<T>;
 export declare const deposit: (runtime: SessionsRuntime, options: DepositOptions, trace?: DepositTrace) => Promise<DepositResult>;
+/** The table in force: the runtime's own (a test's), else every source. */
+export declare const sourcesOf: (runtime: SessionsRuntime) => readonly Source[];
+/** The roots the runtime names, by source name; `cursorRoot` stays the alias of the Cursor entry. */
+export declare const sourceRoots: (runtime: SessionsRuntime) => Map<string, string>;
 /**
  * The log's lines, a chunk at a time: the log can pass the longest string Node can hold (536,870,888 characters), so it is never one string.
  * It splits on the newline alone, not through `readline`, which also ends a line at U+2028 and U+2029: `JSON.stringify` leaves those raw inside a
@@ -250,6 +282,7 @@ export declare const frozenSessions: (runtime: SessionsRuntime, behind: readonly
     project: string;
     session: string;
 }[]) => Promise<Set<string>>;
+export declare const HOOK_LOCK: LockOptions;
 export type SessionDeposit = 'deposited' | 'unchanged' | 'not-allowed' | 'missing' | 'deferred';
 /**
  * Deposits one transcript, as the SessionEnd hook does: only from a folder that earlier `--allow` entries name, and idempotent by size and
@@ -280,12 +313,18 @@ interface LogScan {
     newerCaptures: number;
 }
 export declare const scanLog: (file: string, held?: FileHandle) => Promise<LogScan>;
+/** What a read keeps beyond the default. */
+export type LoadOptions = {
+    /** Keep each session's `messageUsage` entries. Nothing in the store reads them yet, and on a large store they are a third more heap, so a read holds them only when asked. */
+    messageUsage?: boolean;
+};
 /**
  * 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 declare const loadStore: (storeDir: string, afterFirstPass?: () => Promise<void>) => Promise<Store>;
+export declare const loadStore: (storeDir: string, afterFirstPass?: () => Promise<void>, options?: LoadOptions) => Promise<Store>;
 /**
  * Drops the superseded revs from the log, so a re-capture does not leave a full copy of every session behind. The caller holds the store lock,
  * the same one every append takes. Only a line a higher rev of its session replaces goes: a line this version cannot read stays, since a later

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