@manyoars/oars 0.4.1 → 0.5.2

package/dist/sessions/redact.js

@@ -1,30 +1,37 @@
+import { randomBytes } from 'node:crypto';
 import { homedir, userInfo } from 'node:os';
 import { basename } from 'node:path';
+import { injectedRule, learnInjected } from './injected.js';
 // Redaction before anything is written to the session store. Deterministic and conservative: it would rather over-mask a
 // long random-looking token than let a secret through. Pattern rules first, then emails, the organization domains the
 // operator names, and last an entropy rule for long mixed-case tokens no pattern knew.
 export const PATTERNS = [
     [/-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?(?:-----END [A-Z ]*PRIVATE KEY-----|$)/g, '<secret>'],
     [/\b(?:AKIA|ASIA)[A-Z0-9]{16}\b/g, '<secret>'],
-    [/\bgh[pousr]_[A-Za-z0-9]{20,}\b/g, '<secret>'],
-    [/\bgithub_pat_[A-Za-z0-9_]{20,}\b/g, '<secret>'],
+    // A synthetic fixture quoted in a session is masked like a real token (a secret scanner flags the prefix, not the value), so the minimums are short and the
+    // left guard is a non-alphanumeric: `FAKE_ghp_...` still starts a token where `\b` would miss it.
+    [/(?<![A-Za-z0-9])gh[pousr]_[A-Za-z0-9]{8,}(?![A-Za-z0-9])/g, '<secret>'],
+    [/(?<![A-Za-z0-9])github_pat_[A-Za-z0-9_]{8,}(?![A-Za-z0-9])/g, '<secret>'],
     [/\bsk-(?:ant-)?[A-Za-z0-9_-]{16,}\b/g, '<secret>'],
-    [/\b(?:sk|rk|pk)_(?:live|test)_[A-Za-z0-9]{10,}\b/g, '<secret>'],
-    [/\bwhsec_[A-Za-z0-9]{10,}\b/g, '<secret>'],
-    [/\bxox[abprs]-[A-Za-z0-9-]{10,}\b/g, '<secret>'],
+    [/(?<![A-Za-z0-9])(?:sk|rk|pk)_(?:live|test)_[A-Za-z0-9]{6,}(?![A-Za-z0-9])/g, '<secret>'],
+    [/(?<![A-Za-z0-9])whsec_[A-Za-z0-9]{6,}(?![A-Za-z0-9])/g, '<secret>'],
+    [/(?<![A-Za-z0-9])xox[abprs]-[A-Za-z0-9-]{6,}(?![A-Za-z0-9])/g, '<secret>'],
     [/\bAIza[0-9A-Za-z_-]{30,}\b/g, '<secret>'],
     [/\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/g, '<secret>'],
     [/\b(Bearer|Basic)\s+[A-Za-z0-9._~+/=-]{12,}/gi, '$1 <secret>'],
     // user:password@host inside a URL
     [/(\b[a-z][a-z0-9+.-]*:\/\/)[^\s/:@]+:[^\s/@]+@/gi, '$1<secret>@'],
-    // NAME=value and "name": "value" where the name says it is a secret
-    [/\b([A-Za-z0-9_-]*(?:password|passwd|secret|token|api[_-]?key|private[_-]?key|credential)[A-Za-z0-9_-]*)(["']?\s*[=:]\s*)(["']?)[^\s"'&,;]{4,}\3/gi, '$1$2$3<secret>$3'],
+    // NAME=value and "name": "value" where the name says it is a secret. A vendor name before a colon (`1password: ...` in prose) is no key. A plural
+    // `tokens` name (`tokens`, `max_tokens`, `inputTokens`) is a count and keeps a bare number, as the JSON walk does; any other `token` name masks a number too.
+    [/\b(?!1password(?![A-Za-z0-9_-])["']?\s*:\s)([A-Za-z0-9_-]*(?:password|passwd|secret|api[_-]?key|private[_-]?key|credential)[A-Za-z0-9_-]*)(["']?\s*[=:]\s*)(["']?)[^\s"'&,;]{4,}\3/gi, '$1$2$3<secret>$3'],
+    [/\b((?![A-Za-z0-9_-]*tokens(?![A-Za-z0-9_-]))[A-Za-z0-9_-]*token[A-Za-z0-9_-]*)(["']?\s*[=:]\s*)(["']?)[^\s"'&,;]{4,}\3/gi, '$1$2$3<secret>$3'],
+    [/\b([A-Za-z0-9_-]*tokens)(["']?\s*[=:]\s*)(["']?)(?!\d+(?![^\s"'&,;]))[^\s"'&,;]{4,}\3/gi, '$1$2$3<secret>$3'],
 ];
 const EMAIL = /[A-Za-z0-9._%+-]+@[A-Za-z0-9-]+(?:\.[A-Za-z0-9-]+)+/g;
 // A pinned alias, `foo@npm:bar@1.0.0` or `jsr:@scope/bar@1.0.0`, ends in `bar@1.0.0`, which EMAIL reads as an address. Digits and dots after
 // the `@` are a version, never a domain, so that one shape right after `npm:` or `jsr:` (and an optional scope) is kept. An all-numeric four-part tail is an
 // IP address, a real host, so it stays masked (as in `extract.ts` `VERSIONED`); any other address stays masked too.
-const ALIAS_PREFIX = /(?<![A-Za-z0-9])(?:npm|jsr):(?:@[A-Za-z0-9._~-]+\/)?$/;
+const ALIAS_PREFIX = /(?<![A-Za-z0-9])(?:npm|jsr):(?:@[A-Za-z0-9._~-]+\/)?$|(?<![A-Za-z0-9._%+-])@[A-Za-z0-9._~-]+\/$/;
 const DOTTED_VERSION = /@(?!\d+\.\d+\.\d+\.\d+$)\d+(?:\.\d+)+$/;
 const TOKEN = /[A-Za-z0-9+_=-]{24,}/g;
 const escapeRegExp = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
@@ -69,7 +76,108 @@ const PROMPT = /(?:<user>|\b[A-Za-z0-9._-]+)@[A-Za-z0-9-]+(?=:[~/.])/g;
 // Full, compressed, and loopback forms. A clock time (`10:20:30`) has no `::`, so it is never one.
 const IPV6 = /(?<![0-9A-Za-z:])(?:(?:[0-9a-f]{1,4}:){7}[0-9a-f]{1,4}|(?:[0-9a-f]{1,4}:){1,7}:(?:[0-9a-f]{1,4}(?::[0-9a-f]{1,4}){0,6})?|::[0-9a-f]{1,4}(?::[0-9a-f]{1,4}){0,6})(?![0-9A-Za-z:])/gi;
 const MIN_NAME = 3;
-const PLACEHOLDER = /<(?:secret|email|org-domain|host|user|env)>/g;
+const PLACEHOLDER = /<(?:secret|email|org-domain|host|user|env|owner)>/g;
+// A `.env` line whose name is lower case (`mapbox=q8z7...`): only a whole line of that shape, so `--flag=value` and `?page=2` are left alone.
+const LOWER_ENVIRONMENT = /^([ \t]*(?:export[ \t]+)?[a-z][a-z0-9_]{2,}=)(?!<)(?:(["'])[^"'\n]*\2|[^\s"']+)[ \t]*$/gm;
+// Shapes `makeRedactor` does not know (t955, census S3). They run only on a raw copy, and before the shared rules, because the entropy rule would
+// split a key at its `/` first. A bare 40-character secret key needs a `/` or `+` and a random look, so a git sha (hex) and the front of a
+// base64 image (longer than 40) stay. A password flag is masked only when the value looks like one: four characters with a digit or a symbol, and not a
+// port, so `-p 8080` and `-p3000:3000` stay and `-pthread` is not read as a password.
+const AWS_SECRET_KEY = /(?<![A-Za-z0-9/+=_-])[A-Za-z0-9/+]{40}(?![A-Za-z0-9/+=_-])/g;
+const PORT = /^[\d.:]+(?:\/[a-z]+)?$/i;
+const passwordLike = (value) => value.length >= 4 && /[\d!@#$%^&*]/.test(value) && !PORT.test(value);
+const rawRules = (text) => text
+    .replace(/-----BEGIN PGP PRIVATE KEY BLOCK-----[\s\S]*?(?:-----END PGP PRIVATE KEY BLOCK-----|$)/g, '<secret>')
+    .replace(/PuTTY-User-Key-File-\d+:[\s\S]*?Private-Lines:[\s\S]*?(?:Private-MAC:[ \t]*\w*|$)/g, '<secret>')
+    .replace(/\bdop_v1_[a-f0-9]{64}\b/g, '<secret>')
+    .replace(AWS_SECRET_KEY, (key) => (/[/+]/.test(key) && looksRandom(key) ? '<secret>' : key))
+    .replace(/((?<!\S)(?:-u\s*|--user\s+)["']?(?!\d+:)[^\s:"']+:)[^\s"']{4,}/g, '$1<secret>')
+    .replace(/(?<!\S)-p(["'])[^"'\n]{4,}\1/g, '-p$1<secret>$1')
+    .replace(/(?<!\S)-p([^\s"'-][^\s"']{3,})/g, (flag, value) => (passwordLike(value) ? '-p<secret>' : flag))
+    .replace(/(\bsshpass\s+-p\s*)(?:"[^"]*"|'[^']*'|[^\s"']+)/g, '$1<secret>')
+    .replace(/((?<!\S)-W\s+)(?:(["'])[^"']+\2|([^\s"'/:-][^\s"'/:]{3,}))/g, (flag, lead, quote, bare) => quote !== undefined || passwordLike(bare ?? '') ? `${lead}<secret>` : flag)
+    .replace(/(--(?:password|passwd|pwd)\s+)(?:(["'])[^"']*\2|[^\s"'-][^\s"']*)/g, '$1<secret>');
+// A raw copy is JSONL, so a tool's output sits inside a JSON string where a newline is `\n` and a quote is `\"`: a rule written for plain text
+// misses `\nAKIA...` (no word boundary), cannot cross `\"`, and can eat the `n` of `\n` (t955, census S1, S2, S22). So a line that parses is
+// walked and every string in it redacted decoded (a string that itself holds JSON, in turn); the line is written again only if a value changed,
+// and any other text keeps the plain-text path with its bytes as they were.
+const SECRET_NAME = /password|passwd|secret|token|api[_-]?key|private[_-]?key|credential/i;
+// A count of tokens is a number under a `token` name, so a number is masked only under the names that are always a secret.
+const SECRET_NUMBER_NAME = /password|passwd|secret|api[_-]?key|private[_-]?key|credential/i;
+const CONTAINER = /^\s*[{[]/;
+const isContainer = (value) => typeof value === 'object' && value !== null;
+const parseContainer = (text) => {
+    if (!CONTAINER.test(text))
+        return undefined;
+    try {
+        const parsed = JSON.parse(text);
+        return isContainer(parsed) ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+const redactDecoded = (body, redactText, injected, enter) => {
+    // A name reaches the strings of an array under it (`"tokens": ["..."]`); an object's own keys name their values.
+    const walk = (value, name) => {
+        if (typeof value === 'string')
+            return SECRET_NAME.test(name) && value.length >= 4 ? '<secret>' : redactBlock(value);
+        if (typeof value === 'number')
+            return SECRET_NUMBER_NAME.test(name) && String(value).length >= 4 ? '<secret>' : value;
+        if (Array.isArray(value)) {
+            const items = value.map((item) => walk(item, name));
+            return items.some((item, at) => item !== value[at]) ? items : value;
+        }
+        if (typeof value === 'object' && value !== null) {
+            const before = Object.entries(value);
+            const after = before.map(([key, item]) => [redactBlock(key), walk(item, key)]);
+            return after.some(([key, item], at) => key !== before[at]?.[0] || item !== before[at][1]) ? Object.fromEntries(after) : value;
+        }
+        return value;
+    };
+    // The text as it was when nothing in it changed; otherwise the value written again, inside the whitespace (a `\r`, a newline) it had around it.
+    // A transcript line is a top-level object: the harness's own blocks in it are marked first (their hash is of the text as written), then the rest is walked.
+    const rewrite = (text, parsed, top) => {
+        if (top && !Array.isArray(parsed))
+            enter(parsed);
+        const marked = top && !Array.isArray(parsed) ? injected(parsed) : parsed;
+        const next = walk(marked, '');
+        return next === parsed ? text : `${text.slice(0, text.length - text.trimStart().length)}${JSON.stringify(next)}${text.slice(text.trimEnd().length)}`;
+    };
+    // A top-level plain-text run follows no tool result: a host a fetch named is kept in that result's line only (a string inside the line is not top level).
+    const redactPlain = (run, top) => {
+        if (top)
+            enter();
+        return redactText(run.join('\n'));
+    };
+    // `text` is a whole document, or lines of which some are JSON: the JSON ones are walked, the runs between them take the plain-text path.
+    const redactBlock = (text, top = false) => {
+        const whole = parseContainer(text);
+        // A top-level array line is no tool-result line: it keeps no fetched host.
+        if (whole !== undefined) {
+            if (top && Array.isArray(whole))
+                enter();
+            return rewrite(text, whole, top);
+        }
+        const out = [];
+        let run = [];
+        for (const line of text.split('\n')) {
+            const parsed = parseContainer(line);
+            if (parsed === undefined) {
+                run.push(line);
+                continue;
+            }
+            if (run.length > 0)
+                out.push(redactPlain(run, top));
+            run = [];
+            out.push(rewrite(line, parsed, top));
+        }
+        if (run.length > 0)
+            out.push(redactPlain(run, top));
+        return out.join('\n');
+    };
+    return redactBlock(body, true);
+};
 /** How many values of a redacted text were masked: each placeholder is one. */
 export const placeholders = (text) => text.match(PLACEHOLDER)?.length ?? 0;
 /** The account name; `userInfo()` throws when the uid has no passwd entry (a container run with `--user <uid>`), so the environment stands in. */
@@ -92,22 +200,92 @@ const nameRule = (names) => {
     const forms = [...new Set(usable.flatMap((name) => [name, name.replace(/[^A-Za-z0-9]/g, '-')]))].sort((a, b) => b.length - a.length);
     return forms.length === 0 ? undefined : new RegExp(`(?<![A-Za-z0-9<])(?:${forms.map(escapeRegExp).join('|')})(?![A-Za-z0-9>])`, 'gi');
 };
+const TOOL_ID = /(?<![A-Za-z0-9])(?:srv)?tool(?:u|use)_(?:bdrk_|vrtx_)?[A-Za-z0-9_-]{8,}/g;
+const FETCH_TOOLS = new Set(['WebFetch', 'WebSearch']);
+const HOST_OF_URL = /^[a-z][a-z0-9+.-]*:\/\/([A-Za-z0-9.-]+)/i;
+const URLS = /\b[a-z][a-z0-9+.-]*:\/\/[^\s/@"'\\]*@?[A-Za-z0-9.-]+/gi;
+// Loopback, an IP literal, a bare name, and the internal suffixes of INTERNAL_NAME are never a public host.
+const INTERNAL_SUFFIX = /\.(?:internal|local|lan|corp|intranet|home|localdomain)$/;
+const publicHost = (host) => host.includes('.') && !/^[\d.]+$/.test(host) && !INTERNAL_SUFFIX.test(host) && host !== 'localhost';
+const hostsIn = (value, found, listed = false) => {
+    if (typeof value === 'string') {
+        for (const url of value.match(URLS) ?? [])
+            if (!url.includes('@'))
+                found.add((HOST_OF_URL.exec(url)?.[1] ?? '').toLowerCase());
+        // `allowed_domains` lists bare domains.
+        if (listed)
+            found.add(value.toLowerCase().replace(/^[a-z][a-z0-9+.-]*:\/\//, '').replace(/[/:].*$/, ''));
+    }
+    else if (Array.isArray(value))
+        for (const item of value)
+            hostsIn(item, found, listed);
+    else if (typeof value === 'object' && value !== null)
+        for (const [key, item] of Object.entries(value))
+            hostsIn(item, found, key === 'allowed_domains');
+};
+/** The blocks of a transcript line's message content, when it has any. */
+const blocksOf = (line) => {
+    const message = line['message'];
+    const content = typeof message === 'object' && message !== null && !Array.isArray(message) ? message['content'] : undefined;
+    return Array.isArray(content) ? content.filter((block) => typeof block === 'object' && block !== null && !Array.isArray(block)) : [];
+};
+/** The public hosts each WebFetch or WebSearch call of a transcript named, by the call's tool use id. */
+const fetchedBy = (lines) => {
+    const byId = new Map();
+    for (const line of lines) {
+        for (const block of blocksOf(line)) {
+            const { type, id, name, input } = block;
+            if (type !== 'tool_use' || typeof id !== 'string' || typeof name !== 'string' || !FETCH_TOOLS.has(name) || input === undefined)
+                continue;
+            const found = new Set();
+            hostsIn(input, found);
+            byId.set(id, new Set([...found].filter(publicHost)));
+        }
+    }
+    return byId;
+};
+// A handle is a whole path segment (`/acme/app`, `\acme\app`, `git@host:acme/app.git`) or a hyphen-bounded word of an encoded project folder (`-repos-acme-app`).
+const handleRule = (handles) => {
+    const usable = [...new Set(handles.filter((handle) => handle.length >= MIN_NAME))].sort((a, b) => b.length - a.length);
+    return usable.length === 0 ? undefined : new RegExp(String.raw `(?<=[\\/:-])(?:${usable.map(escapeRegExp).join('|')})(?=[\\/.-]|["'\s]|$)`, 'gi');
+};
 /** A whole transcript body redacted for upload, and how many values were masked (placeholders added, a count and nothing else). `names` are the local usernames to mask wherever they stand as a whole word. */
-export const redactTranscript = (body, domains = [], names = []) => {
+export const redactTranscript = (body, domains = [], names = [], injectedKey = randomBytes(16).toString('hex'), pack = {}) => {
     const named = nameRule(names);
-    // The names go first: a hyphenated or spaced name must be masked whole before the path rules take its first word.
-    const known = makeRedactor(domains)(body);
-    const redacted = (named === undefined ? known : known.replace(named, '<user>'))
-        .replace(URL_HOST, '$1<host>')
-        .replace(INTERNAL_NAME, '<host>')
-        .replace(IPV4, '<host>')
-        .replace(IPV6, '<host>')
-        .replace(UNIX_HOME, '$1<user>')
-        .replace(WINDOWS_HOME, '$1<user>')
-        .replace(ENCODED_HOME, '$1<user>')
-        .replace(PROMPT, '<user>@<host>')
-        .replace(ENVIRONMENT, '$1<env>');
+    const owner = handleRule(pack.handles ?? []);
+    const known = makeRedactor(domains);
+    // The hosts the line being redacted may keep: those its tool results' calls fetched.
+    let kept = new Set();
+    const keepHost = (match, scheme) => (!match.includes('@') && kept.has((HOST_OF_URL.exec(match)?.[1] ?? '').toLowerCase()) ? match : `${scheme}<host>`);
+    const redactText = (original) => {
+        const text = pack.toolId === undefined ? original : original.replace(TOOL_ID, pack.toolId);
+        // The names go first: a hyphenated or spaced name must be masked whole before the path rules take its first word.
+        const masked = known(rawRules(text));
+        const mine = named === undefined ? masked : masked.replace(named, '<user>');
+        return (owner === undefined ? mine : mine.replace(owner, '<owner>'))
+            .replace(URL_HOST, keepHost)
+            .replace(INTERNAL_NAME, '<host>')
+            .replace(IPV4, '<host>')
+            .replace(IPV6, '<host>')
+            .replace(UNIX_HOME, '$1<user>')
+            .replace(WINDOWS_HOME, '$1<user>')
+            .replace(ENCODED_HOME, '$1<user>')
+            .replace(PROMPT, '<user>@<host>')
+            .replace(ENVIRONMENT, '$1<env>')
+            .replace(LOWER_ENVIRONMENT, '$1<env>');
+    };
+    // A request blob repeats messages other lines hold, so what those lines carry is collected before any line is marked.
+    const repeated = new Set();
+    const whole = parseContainer(body);
+    for (const parsed of whole !== undefined ? [whole] : body.split('\n').map(parseContainer))
+        if (parsed !== undefined && !Array.isArray(parsed))
+            learnInjected(parsed, repeated);
+    const calls = pack.fetchedHosts === true ? fetchedBy([...(whole !== undefined ? [whole] : body.split('\n').map(parseContainer))].filter((parsed) => parsed !== undefined && !Array.isArray(parsed))) : new Map();
+    const enter = (line) => {
+        kept = new Set(line === undefined ? [] : blocksOf(line).flatMap((block) => (block['type'] === 'tool_result' && typeof block['tool_use_id'] === 'string' ? [...(calls.get(block['tool_use_id']) ?? [])] : [])));
+    };
+    const redacted = redactDecoded(body, redactText, injectedRule(injectedKey, repeated), enter);
     return { text: redacted, masked: Math.max(0, placeholders(redacted) - placeholders(body)) };
 };
 /** The version of the rules above, stated to the pool with every raw part; a change to any rule of `redactTranscript` raises it. */
-export const REDACTION_VERSION = '1';
+export const REDACTION_VERSION = '4';

package/dist/sessions/repo-root.d.ts

@@ -2,6 +2,13 @@
 export declare const makeRepoRoot: (exists?: (path: string) => boolean) => ((cwd: string) => string | null);
 /** `https://User:pw@GitHub.com/org/repo.git`, `git@github.com:org/repo.git`, and `ssh://git@github.com/org/repo/` all read `github.com/org/repo`. */
 export declare const normalizeRemote: (url: string) => string;
+/** The `url` of `[remote "origin"]` in a git `config`, or null. */
+export declare const originUrl: (config: string) => string | null;
+/**
+ * The git `config` text of a repository root, or null: `<root>/.git/config`, or for a linked worktree or submodule (`.git` is a file)
+ * the common directory's, reached through the file's `gitdir:` line and that directory's `commondir` file.
+ */
+export declare const configOf: (root: string, read?: (path: string) => string | null) => string | null;
 /**
  * A resolver from a repository root to its identity string: `origin:<normalized remote>` when the repository's `config` names an
  * `origin`, else `path:<root>`. The `config` is `<root>/.git/config`, or for a linked worktree (`.git` is a file) the common

package/dist/sessions/repo-root.js

@@ -46,7 +46,7 @@ export const normalizeRemote = (url) => {
     return slash < 0 ? bare.toLowerCase() : `${bare.slice(0, slash).toLowerCase()}${bare.slice(slash)}`;
 };
 /** The `url` of `[remote "origin"]` in a git `config`, or null. */
-const originUrl = (config) => {
+export const originUrl = (config) => {
     let inOrigin = false;
     for (const line of config.split(/\r?\n/)) {
         const section = /^\s*\[(.*)\]\s*$/.exec(line);
@@ -71,6 +71,21 @@ const readOrNull = (path) => {
         return null;
     }
 };
+/**
+ * The git `config` text of a repository root, or null: `<root>/.git/config`, or for a linked worktree or submodule (`.git` is a file)
+ * the common directory's, reached through the file's `gitdir:` line and that directory's `commondir` file.
+ */
+export const configOf = (root, read = readOrNull) => {
+    const direct = read(`${root}/.git/config`);
+    if (direct !== null)
+        return direct;
+    const pointer = /^gitdir:\s*(.+?)\s*$/m.exec(read(`${root}/.git`) ?? '')?.[1];
+    if (pointer === undefined)
+        return null;
+    const gitdir = resolveFrom(root, pointer);
+    const common = read(`${gitdir}/commondir`)?.trim();
+    return read(`${common === undefined || common === '' ? gitdir : resolveFrom(gitdir, common)}/config`);
+};
 /**
  * A resolver from a repository root to its identity string: `origin:<normalized remote>` when the repository's `config` names an
  * `origin`, else `path:<root>`. The `config` is `<root>/.git/config`, or for a linked worktree (`.git` is a file) the common
@@ -78,22 +93,11 @@ const readOrNull = (path) => {
  */
 export const makeRepoIdentity = (read = readOrNull) => {
     const cache = new Map();
-    const configOf = (root) => {
-        const direct = read(`${root}/.git/config`);
-        if (direct !== null)
-            return direct;
-        const pointer = /^gitdir:\s*(.+?)\s*$/m.exec(read(`${root}/.git`) ?? '')?.[1];
-        if (pointer === undefined)
-            return null;
-        const gitdir = resolveFrom(root, pointer);
-        const common = read(`${gitdir}/commondir`)?.trim();
-        return read(`${common === undefined || common === '' ? gitdir : resolveFrom(gitdir, common)}/config`);
-    };
     return (root) => {
         const known = cache.get(root);
         if (known !== undefined)
             return known;
-        const url = originUrl(configOf(root) ?? '');
+        const url = originUrl(configOf(root, read) ?? '');
         const identity = url === null ? `path:${root.toLowerCase()}` : `origin:${normalizeRemote(url)}`;
         cache.set(root, identity);
         return identity;

package/dist/sessions/reversion.d.ts

@@ -0,0 +1,8 @@
+import type { Store } from './store.js';
+/** Where the nearest later reversion ran: in the prompt that did the work, in a later prompt of that session, or in a later session of the same repository. */
+export type Reversion = 'same-prompt' | 'later-prompt' | 'later-session';
+/**
+ * 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 declare const reversionsOf: (store: Store) => ((session: string, index: number | null) => Reversion | null);

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). */