@manyoars/oars 0.4.1 → 0.5.1

package/dist/sessions/reversion.js

@@ -0,0 +1,114 @@
+// A later reversion of the work a prompt did, read from the calls alone. Three ties: a clean `git revert <word>` whose word is a prefix of a commit sha the capture kept (or the other way round); an edit whose old and new text
+// are the swap of an earlier edit's on the same path, or a Write that sets the text an earlier Write of that path set after a different Write changed it (both from the digests of the exact text); and a clean `git restore` or
+// `git checkout --` that names a path an earlier edit changed. The result is descriptive: it says the work was undone later, never that it was wrong or that undoing it was the reason. The original outcome stays as it was and this sits beside it.
+import { EDITS, SHELL } from './extract.js';
+const NEAREST_FIRST = ['same-prompt', 'later-prompt', 'later-session'];
+/** The shortest abbreviation git prints, and a full sha. Anything else a revert names (`HEAD`, a branch, a range, a short guess) is not a sha, so it ties to nothing. */
+const SHA = /^[0-9a-f]{7,40}$/;
+/**
+ * The sha-shaped words of a segment that is `git revert <words>`. A bare `git revert` is `--abort`, `--continue`, or `--quit` with the flag dropped, and names nothing. A `--no-commit` revert reads the same as a committed one,
+ * because the flag is not kept.
+ */
+const revertWords = (run) => (run.startsWith('git revert ') ? run.slice('git revert '.length).split(' ').map((word) => word.toLowerCase()).filter((word) => SHA.test(word)) : []);
+const tied = (commit, word) => commit.startsWith(word) || word.startsWith(commit);
+/** Adds to the list a key holds, making it once, so a hot path costs one push per call and not a copy of the list. */
+const append = (lists, key, items) => {
+    const held = lists.get(key);
+    if (held === undefined)
+        lists.set(key, [...items]);
+    else
+        held.push(...items);
+};
+/** Where `later` ran against `earlier`, or null when it is not later. Across sessions the calls are ordered by their time, so a call with none cannot be placed, and both sessions must sit in one known repository. */
+const whereOf = (earlier, later, repos) => {
+    if (earlier.session === later.session) {
+        if (later.n < earlier.n || (later.n === earlier.n && later.k <= earlier.k))
+            return null;
+        return later.prompt === earlier.prompt ? 'same-prompt' : 'later-prompt';
+    }
+    const repo = repos.get(earlier.session) ?? null;
+    const sameRepo = repo !== null && repo === (repos.get(later.session) ?? null);
+    return sameRepo && earlier.ts !== null && later.ts !== null && later.ts > earlier.ts ? 'later-session' : null;
+};
+/**
+ * Whether a commit kept the edit before the restore ran: a `git restore` returns the file to the last commit, so an edit committed since is what it returns to, not what it undoes. A commit in the restore's own call counts, since
+ * the order inside a call is not kept. Across sessions a commit of the edit's session after it counts, and so does a commit of the restore's session before the restore unless both stamps are known and the commit is stamped before the
+ * edit; with a stamp missing the position alone decides.
+ */
+const keptBy = (committed, edit, restore) => {
+    const before = committed.get(edit.session) ?? [];
+    if (edit.session === restore.session)
+        return before.some((commit) => commit.n > edit.n && commit.n <= restore.n);
+    return before.some((commit) => commit.n > edit.n) || (committed.get(restore.session) ?? []).some((commit) => commit.n <= restore.n && !(commit.ts !== null && edit.ts !== null && commit.ts < edit.ts));
+};
+/**
+ * Reads every main-line call once: the clean shell calls' commits, revert words (read segments only, since a segment whose result the call's status does not report (`read` false) could have failed behind another command), and
+ * restored paths; and every edit that did not fail, with its digests. A subagent's call is not on the main line, so it is not read. Returns the nearest reversion of a prompt's work, or null for none found.
+ */
+export const reversionsOf = (store) => {
+    const repos = new Map(store.sessions.map((session) => [session.session, session.repo]));
+    const commits = [];
+    const reverts = [];
+    const committed = new Map();
+    const edited = new Map();
+    const written = new Map();
+    const restored = [];
+    for (const tool of store.tools) {
+        if (tool.side || tool.prompt === null)
+            continue;
+        const at = { session: tool.session, n: tool.n, k: 0, ts: tool.ts, prompt: tool.prompt };
+        if (EDITS.has(tool.tool) && tool.status !== 'error' && tool.target !== null) {
+            append(edited, tool.target, [at]);
+            append(written, tool.target, (tool.digests ?? []).map((held, k) => ({ ...at, k, old: held.old ?? null, now: held.new })));
+        }
+        if (tool.status !== 'ok' || !SHELL.has(tool.tool))
+            continue;
+        for (const sha of tool.commits ?? [])
+            if (sha !== null && SHA.test(sha))
+                commits.push({ ...at, sha });
+        if ((tool.commits ?? []).length > 0)
+            append(committed, tool.session, [{ n: tool.n, ts: tool.ts }]);
+        for (const target of tool.restores ?? [])
+            restored.push({ ...at, target });
+        for (const segment of tool.segments ?? [])
+            if (segment.read)
+                for (const word of revertWords(segment.run))
+                    reverts.push({ ...at, sha: word });
+    }
+    const found = new Map();
+    const note = (earlier, later) => {
+        const where = whereOf(earlier, later, repos);
+        if (where === null)
+            return;
+        const key = `${earlier.session}#${String(earlier.prompt)}`;
+        const held = found.get(key);
+        if (held === undefined || NEAREST_FIRST.indexOf(where) < NEAREST_FIRST.indexOf(held))
+            found.set(key, where);
+    };
+    for (const commit of commits)
+        for (const revert of reverts)
+            if (tied(commit.sha, revert.sha))
+                note(commit, revert);
+    for (const pairs of written.values()) {
+        for (const later of pairs) {
+            for (const earlier of pairs) {
+                // An edit that changed nothing (old equals new) is its own swap, so it undoes nothing.
+                if (earlier.old !== null && earlier.old !== earlier.now && later.old === earlier.now && later.now === earlier.old)
+                    note(earlier, later);
+                if (earlier.old !== null || later.old !== null || earlier.now !== later.now)
+                    continue;
+                // A Write that sets the text an earlier Write set undoes the different Writes between them, not the earlier one.
+                for (const between of pairs) {
+                    if (between.old === null && between.now !== later.now && whereOf(earlier, between, repos) !== null && whereOf(between, later, repos) !== null)
+                        note(between, later);
+                }
+            }
+        }
+    }
+    for (const restore of restored) {
+        for (const edit of edited.get(restore.target) ?? [])
+            if (!keptBy(committed, edit, restore))
+                note(edit, restore);
+    }
+    return (session, index) => found.get(`${session}#${String(index)}`) ?? null;
+};

package/dist/sessions/schema.d.ts

@@ -1,9 +1,9 @@
 import type { CanonicalAction } from './actions.js';
-import type { ArgClass, TargetClass } from './call-shape.js';
+import type { ArgClass, ArgFeature, ArgName, ArgValue, ChangeKind, DiffShape, TargetClass } from './call-shape.js';
 import type { RepoSize } from './public-vocabulary.js';
 import type { SessionFunnel, SessionSetup, SessionTrust } from './session-shape.js';
 /** 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 declare const CAPTURE_VERSION = "25";
+export declare 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 declare const OLDEST_READABLE_CAPTURE = 3;
 /** Stamped `v` on every derived record. A bump re-derives from the log; no transcript is read. */
@@ -39,6 +39,36 @@ export interface Usage {
     output: number;
     thinking: number;
 }
+/**
+ * One model message's token counts (class L: numbers and ids only, never content). Claude Code writes a message over several content-block lines that each repeat the same `usage`, so
+ * a message is counted once, keyed by its `message.id` (else the line's `requestId`); a Codex response is keyed by the response id the reader gives it. The counts belong to the
+ * message and are never split across its tool calls: `calls` lists the tool-use ids the message made, and a later read can allocate. A category the source did not report is absent,
+ * never a zero. Summing these over a session record gives the deduplicated total for the file, `side` entries included.
+ */
+export interface MessageUsage {
+    /** The message id, else the request id; null when the line holds neither (each such line is its own message). */
+    id: string | null;
+    /** The tool-use ids of the calls this message made, in order; empty when it made none. */
+    calls: string[];
+    /** True for a message on a sidechain line of a main transcript, which the session's `usage` total leaves out. */
+    side?: true;
+    input?: number;
+    cacheWrite?: number;
+    cacheRead?: number;
+    output?: number;
+    /** From `output_tokens_details.thinking_tokens` (Codex: the reasoning output tokens); absent when the source did not report it. */
+    thinking?: number;
+    /** Codex only: the plan share used as the response's event reported it. Absent when the event held no rate-limit block, never a zero. */
+    plan?: {
+        primary?: PlanWindow;
+        secondary?: PlanWindow;
+    };
+}
+/** One plan window a Codex event reports (`rate_limits.primary` or `.secondary`): the percent used and the window's length in minutes when given. */
+export interface PlanWindow {
+    usedPercent: number;
+    windowMinutes?: number;
+}
 /** The five usage categories, in the order a record lists the ones it observed. */
 export declare const USAGE_FIELDS: readonly ["input", "cacheWrite", "cacheRead", "output", "thinking"];
 export type UsageField = (typeof USAGE_FIELDS)[number];
@@ -115,7 +145,7 @@ export interface CaptureEnv {
 /**
  * One per transcript, captured: the `parse_sessions.py` record, minus anything that is raw content. Classes (spec Section 1.2):
  * `L` local-only: `project`, `files`. `A` account store: `session`, `parent`, `spawnedBy`, `spawnedIn`, `branches`, `urls`, `searches`, `tldrs`,
- * `confidences`, `promptFingerprint`, `repo`, `fileHashes`, `tools`, `setup`, `funnel`, `trust`, `at`, `tsFirst`, `tsLast`. `P` pooled: `kind`, `cv`, `rev`, `sid`,
+ * `confidences`, `promptFingerprint`, `repo`, `fileHashes`, `tools`, `setup`, `funnel`, `trust`, `loadedInstructions`, `at`, `tsFirst`, `tsLast`. `P` pooled: `kind`, `cv`, `rev`, `sid`,
  * the counts, `versions`, `models`, `env`, `costUsd`, `usage` (`at`, `tsFirst`, and `tsLast` at UTC day). `agentType`, `frame`, and `frameId` moved to `A` at EXTRACTOR 11:
  * a custom agent's name is private, and the joined frame is one value that links rows.
  */
@@ -126,6 +156,11 @@ export interface SessionObservation {
      * the Claude Code path's records and CAPTURE_VERSION are unchanged and an older oars reads a Cursor session as a session with no harness version.
      */
     harness?: Harness;
+    /**
+     * Set on a session a later read of its source folded into another (an OpenTelemetry trace deposited before its `gen_ai.conversation.id` arrived): the id of the session that
+     * holds its turns now. The record is a later rev of the early session with no turns, so the log stays append-only; a reader skips a session that carries it. Class P.
+     */
+    supersededBy?: string;
     /** CAPTURE_VERSION (a version-2 line has `v` instead). Class P. */
     cv: string;
     /** The first 8 hex characters of SHA-256 of the salt this record's hashes used; null on a record captured before version 4. Class P. */
@@ -193,12 +228,28 @@ export interface SessionObservation {
     usageObserved?: UsageField[];
     /** How many responses reported any usage (class P); compare with `assistantTurns` or `turns` for the share a sum covers. Same absence rule as `usageObserved`. */
     usageResponses?: number;
+    /** One entry per distinct model message that reported usage, in file order (CAPTURE 28); see `MessageUsage`. Absent when the file reports no usage, and on a record captured before version 28. */
+    messageUsage?: MessageUsage[];
     /** What the transcript shows of the setup the session ran with (class A); absent when it shows none, and on a record captured before version 12. */
     setup?: SessionSetup;
     /** The tool names at each funnel stage the transcript shows (class A); same absence rules. */
     funnel?: SessionFunnel;
     /** How often a human or a policy stopped the session and how long it ran alone (class A); same absence rules. */
     trust?: SessionTrust;
+    /**
+     * The instruction files the transcript shows loaded, as counts and levels, never a path (class A; `load-status.ts` joins it with the session-start snapshot). Absent when the
+     * transcript holds no such record. Added at CAPTURE 29.
+     */
+    loadedInstructions?: LoadedInstructions;
+}
+/** What a transcript shows loaded. `levels` is folders above the working folder, one entry per project file. */
+export interface LoadedInstructions {
+    user: number;
+    levels: number[];
+    /** Files loaded from the working folder, by kind; absent on a record captured before version 30. */
+    local?: number;
+    dotClaude?: number;
+    rules?: number;
 }
 /**
  * What the last build or test runner after a prompt's last edit returned: `passed` and `failed` when the call's status reads that runner,
@@ -395,10 +446,28 @@ export interface ToolObservation {
     targetBase: TargetBase | null;
     /** The input's key names, sorted. Class A (EXTRACTOR 11). */
     keys: string[];
+    /** How many key names the wire did not send (off a public tool's pinned list, or kept `private` by the gate). Never captured: set only on a record the wire projection made (`projectedStore`) or read back from a skeleton, so a local read and the pool count one `dropped` cell. */
+    keysDropped?: number;
     /** The class of the call's path target (`targetClassOf`): a member of `TARGET_CLASSES`, `none` for a call with no path target. Absent on a record captured before CAPTURE 22. Class P: a closed list, never the path or its base name. */
     targetClass?: TargetClass;
     /** The classes of the call's arguments (`argClassOf`), a sorted set of `ARG_CLASSES` members, `['none']` for a call with no argument value. Absent on a record captured before CAPTURE 22. Class P: never a value. */
     argClass?: ArgClass[];
+    /** Each argument's features (`argFeaturesOf`), sorted by key: closed-list facts about its value (size, a path's depth, extension class, and folder kind, a pattern's features), never the value. Absent on a record captured before CAPTURE 27. Class A, as `keys` is: a private tool's key names are private. */
+    argFeatures?: ArgFeature[];
+    /** Each argument's closed value (`argValuesOf`): a boolean, or a string on its tool's list in `CLOSED_ARG_VALUES`; a value off the list is not stored. Absent on a record captured before CAPTURE 27, and when the call held none. Class A, as `argFeatures`. */
+    argValues?: ArgValue[];
+    /** The name tokens of the call's values (`argNamesOf`), sorted by kind and name: a file's name, a folder's name below the root, a variable's name, a flag value that is a name, a custom agent's name; never a value. Absent when it holds none and on a record captured before CAPTURE 33. Class A. */
+    names?: ArgName[];
+    /** The old and new text of an Edit (one pair), a MultiEdit (one pair per edit, in order), or a Write (a new digest only), as a digest of the exact text (`editDigestsOf`); a line ending is a difference. Absent on any other call and on a record captured before CAPTURE 35. Class A, as `target`: the digest is plain, so the same text matches across sessions and accounts. */
+    digests?: EditDigest[];
+    /** The files a `git restore` or `git checkout --` in a command whose status the call reports names, hashed as `target` is, so a restore reads against an earlier edit of the same path. Absent when the call restores none and on a record captured before CAPTURE 35. Class A. */
+    restores?: string[];
+    /** One template per command of a shell call (`templatesOf`): its program, subcommand, and flags, as written and masked by the redactor, and every literal argument as a slot of `TEMPLATE_SLOTS`; never an argument. Absent when the call holds no command and on a record captured before CAPTURE 34. Class A. */
+    templates?: string[];
+    /** What an edit did (`diffShapeOf`), a sorted set of `DIFF_SHAPES` members: `file-written` for a write, else the shapes of the old and new text; never the text. Absent on a call that is no edit, an edit that changes nothing, and a record captured before CAPTURE 34. Class A. */
+    diffShape?: DiffShape[];
+    /** What changed from the previous call of the same tool in the same prompt (`changeKindOf`), a sorted set of `CHANGE_KINDS` members. Absent on the first such call and on a record captured before CAPTURE 27. Class P. */
+    changeKind?: ChangeKind[];
     /** The class of a failed call (`errorCodeOf`): a member of `ERROR_CODES`, never result text. Absent on a call that did not fail and on a record captured before CAPTURE 14. Class P. */
     errorCode?: string;
     /** From the call's line to its first result's line; null when either timestamp is missing or no result is in the file. */
@@ -426,6 +495,11 @@ export interface ToolObservation {
     /** One entry per commit a clean shell call made, in order: the sha its result names, or null when it names none (CAPTURE 6). Absent when it made none. */
     commits?: Array<string | null>;
 }
+/** The digest of one edit's text: the first 32 hex digits of the SHA-256 of the exact UTF-8 text. A Write has `new` only, never the digest of an empty string for `old`. */
+export interface EditDigest {
+    old?: string;
+    new: string;
+}
 /** One command of a shell call. */
 export interface ShellSegment {
     /** The program's basename and its plain words: no flags, paths, variables, or quoted text; redacted. */
@@ -640,7 +714,7 @@ export interface RecallCall {
 /** One hook invocation, appended to `hook-calls.jsonl` by the hook itself; `measure` counts these per session. Class A: `session`, `at`, `error`; P: `event`, `hit`, `ms`, `startMs`. */
 export interface HookCall {
     at: string;
-    event: 'session-start' | 'prompt' | 'pre-tool' | 'post-tool' | 'stop' | 'nightly';
+    event: 'session-start' | 'prompt' | 'pre-tool' | 'post-tool' | 'stop' | 'nightly' | 'codex-record';
     /** The Claude Code session the hook ran in; null for the nightly run. */
     session: string | null;
     /** Whether the hook had something to say (an injected block, a recall hit, or a session deposited). */

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