@manyoars/oars 0.4.1 → 0.5.2

package/dist/sessions/harness-files.js

@@ -0,0 +1,109 @@
+// Per harness, how many session files the readers saw, how many yielded records, and how many were in a form the reader could not parse.
+// A harness whose log format moved then shows up as a count an operator can read, not as quietly thinner data. The counts are read from the
+// harness's own store on this machine and sent nowhere. This file is the one place the three counts are defined; `sessions verify` prints them.
+import { readFile, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { compileAllow } from './allow.js';
+import { captureSession } from './extract.js';
+import { holdsOnlyKinds } from './head-only.js';
+import { makeRedactor } from './redact.js';
+import { listDir, mainTranscript, projectFolders, readState, sessionFolders, sourceRoots, sourcesOf, subagentTranscripts } from './store.js';
+/** What the docs and the tests quote: where each kind of file goes, so `seen` is the sum of the outcomes. */
+export const FILE_COUNT_RULES = 'A file counts once. It is seen when the reader opened it and it is not empty; seen files either yielded (at least one user or assistant turn came out) or are unreadable ' +
+    '(the read failed, or the text gave no turn, torn or with a record of a kind the reader does not know). An empty file (nothing in it to parse), a file with no turn whose ' +
+    'records are all head records its own format defines (a session started and quit), and a file skipped by a rule (an id that is not a safe file name, a revert folded into ' +
+    'its thread, a session folded into another) are not seen. An OpenTelemetry session none of whose spans (any span of its trace) holds a `gen_ai.*` attribute or a name leading with a GenAI operation (ordinary HTTP spans) is a known form with no turn and is not seen; one with a renamed `gen_ai.*` attribute on any span stays unreadable. A Codex rollout whose only turn-like records are assistant `response_item` messages stays unreadable. A file a reader dropped before it was a session (a Gemini chat that holds nothing, an OpenTelemetry file with no span found) is seen and unreadable when it held records in a shape the reader does not know. Where a store is a database, a session is the unit.';
+/** `records` is undefined when the read itself failed; `headOnly` is the reader's word that a file with no turn holds only head records. */
+export const outcomeOf = (file) => {
+    if (file.records === undefined)
+        return 'unreadable';
+    if (file.size === 0)
+        return 'empty';
+    if (file.records > 0)
+        return 'yielded';
+    return file.headOnly === true ? 'empty' : 'unreadable';
+};
+/** The Claude Code record types that carry no turn by design: a compaction summary, a file-history snapshot, the permission mode, an attachment, a system notice, and the cost state. A transcript of these alone is a session started and quit. */
+const CLAUDE_HEAD_KINDS = new Set(['summary', 'file-history-snapshot', 'permission-mode', 'attachment', 'system', 'cost-state']);
+export const tally = (outcomes) => {
+    const yielded = outcomes.filter((outcome) => outcome === 'yielded').length;
+    const unreadable = outcomes.filter((outcome) => outcome === 'unreadable').length;
+    return { seen: yielded + unreadable, yielded, unreadable };
+};
+const NO_ONE = makeRedactor([]);
+/** The turns a transcript's text gives once the reader's lines go through the same capture the deposit runs; nothing is stored. */
+const recordsOf = (text, harness, subagent) => {
+    const { session } = captureSession({ text, session: 'count', project: 'count', rev: 0, at: new Date(0).toISOString(), bytes: Buffer.byteLength(text), redact: NO_ONE, harness, ...(subagent === undefined ? {} : { subagent }) });
+    return session.userTurns + session.assistantTurns;
+};
+const claudeOutcomes = async (runtime, allows) => {
+    const outcomes = [];
+    for (const project of (await projectFolders(runtime.projectsRoot)).filter(allows)) {
+        const folder = join(runtime.projectsRoot, project);
+        const mains = (await listDir(folder)).filter((entry) => entry.isFile() && entry.name.endsWith('.jsonl')).map((entry) => mainTranscript(folder, entry.name));
+        for (const transcript of [...mains, ...(await subagentTranscripts(folder, await sessionFolders(folder)))]) {
+            try {
+                const size = (await stat(transcript.file)).size;
+                const text = await readFile(transcript.file, 'utf8');
+                outcomes.push(outcomeOf({ size, records: recordsOf(text, 'claude-code', transcript.subagent), headOnly: holdsOnlyKinds(text, CLAUDE_HEAD_KINDS) }));
+            }
+            catch {
+                outcomes.push('unreadable');
+            }
+        }
+    }
+    return outcomes;
+};
+const sessionOutcome = async (store, session, harness) => {
+    try {
+        const records = recordsOf(await store.transcript(session), harness, session.subagent);
+        // Asked only of a file that gave no turn: the reader is not read twice for a file that yielded.
+        return outcomeOf({ size: session.size, records, headOnly: records === 0 && (await store.headOnly?.(session)) === true });
+    }
+    catch {
+        return 'unreadable';
+    }
+};
+/**
+ * The counts for every harness the store reads that has files on this machine, and that the saved allowlist lets a deposit read. A harness with nothing
+ * to read has no entry. Read-only: it opens each store as the deposit does, reads each transcript, and writes nothing.
+ */
+export const harnessFileCounts = async (runtime) => {
+    const allow = compileAllow((await readState(runtime.storeDir)).allow);
+    const found = {};
+    const claude = await claudeOutcomes(runtime, allow.allows);
+    if (claude.length > 0)
+        found['claude-code'] = tally(claude);
+    const roots = sourceRoots(runtime);
+    for (const source of sourcesOf(runtime)) {
+        const root = roots.get(source.name);
+        if (root === undefined || !allow.allows(source.name))
+            continue;
+        const outcomes = [];
+        try {
+            const store = await source.open(root);
+            if (store === undefined)
+                continue;
+            try {
+                // A session folded into another is no file of its own; an item the store could not inspect is one unreadable file.
+                outcomes.push(...store.unreadable.map(() => 'unreadable'));
+                // Files the reader dropped before they were sessions while they held records in a shape it does not know: seen, and unreadable.
+                for (let dropped = 0; dropped < (store.shapeMoved ?? 0); dropped += 1)
+                    outcomes.push('unreadable');
+                for (const session of store.sessions.filter((one) => one.supersededBy === undefined))
+                    outcomes.push(await sessionOutcome(store, session, source.harness));
+            }
+            finally {
+                store.close();
+            }
+        }
+        catch {
+            // A store that cannot be opened is one unreadable item, as the deposit reports it.
+            outcomes.push('unreadable');
+        }
+        const counts = tally(outcomes);
+        if (counts.seen > 0)
+            found[source.harness] = counts;
+    }
+    return found;
+};

package/dist/sessions/head-only.d.ts

@@ -0,0 +1,7 @@
+/** True when the text has at least one line and every line is a JSON object that `accepts`. */
+export declare const holdsOnlyRecords: (text: string, accepts: (record: {
+    type: string;
+    [key: string]: unknown;
+}) => boolean) => boolean;
+/** True when the text has at least one line and every line is a JSON object whose `type` is one of `kinds`. */
+export declare const holdsOnlyKinds: (text: string, kinds: ReadonlySet<string>) => boolean;

package/dist/sessions/head-only.js

@@ -0,0 +1,21 @@
+// A transcript file whose every record is a head record its harness's own format defines (the session header, the model in force) and that has no turn in
+// it: a session started and quit. `sessions verify` counts such a file as empty, not unreadable. A torn line, a non-object line, or a record of any other
+// type makes the file something else, so a format that moved still shows as unreadable.
+/** True when the text has at least one line and every line is a JSON object that `accepts`. */
+export const holdsOnlyRecords = (text, accepts) => {
+    const lines = text.split('\n').filter((raw) => raw.trim() !== '');
+    if (lines.length === 0)
+        return false;
+    return lines.every((raw) => {
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            return false;
+        }
+        return typeof parsed === 'object' && parsed !== null && 'type' in parsed && typeof parsed.type === 'string' && accepts({ ...parsed, type: parsed.type });
+    });
+};
+/** True when the text has at least one line and every line is a JSON object whose `type` is one of `kinds`. */
+export const holdsOnlyKinds = (text, kinds) => holdsOnlyRecords(text, (record) => kinds.has(record.type));

package/dist/sessions/hook-calls.js

@@ -1,14 +1,15 @@
 // The hook counters: `hook-calls.jsonl`, one line per hook invocation, appended by the hook and read by `measure`.
-import { appendFile, mkdir, readFile } from 'node:fs/promises';
+import { appendFile, readFile } from 'node:fs/promises';
+import { mkdirOwnerOnly } from './owner-only.js';
 import { paths } from './store.js';
 const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
 const eventOf = (value) => {
-    if (value === 'session-start' || value === 'prompt' || value === 'pre-tool' || value === 'post-tool' || value === 'stop' || value === 'nightly')
+    if (value === 'session-start' || value === 'prompt' || value === 'pre-tool' || value === 'post-tool' || value === 'stop' || value === 'nightly' || value === 'codex-record')
         return value;
     return undefined;
 };
 export const appendHookCall = async (storeDir, call) => {
-    await mkdir(storeDir, { recursive: true });
+    await mkdirOwnerOnly(storeDir);
     await appendFile(paths(storeDir).hookCalls, `${JSON.stringify(call)}\n`, { mode: 0o600 });
 };
 export const readHookCalls = async (storeDir) => {

package/dist/sessions/hooks.d.ts

@@ -2,7 +2,7 @@ import { type Emit } from '../telemetry/emit.js';
 import type { HookCall } from './schema.js';
 import { type SessionsRuntime } from './store.js';
 import type { NightlyTelemetry } from '../telemetry/health.js';
-export type HookEvent = HookCall['event'];
+export type HookEvent = Exclude<HookCall['event'], 'codex-record'>;
 export declare const HOOK_EVENTS: readonly HookEvent[];
 /** The runtime a hook process runs with. Only `nightly` reads the non-Claude stores (a saved `--allow cursor` or `--allow codex`); the Stop path stays free of it. */
 export declare const hookRuntime: (event: HookEvent, env: {

package/dist/sessions/hooks.js

@@ -1,7 +1,7 @@
 // The hook entry points. Each takes the hook's stdin and returns the text for stdout (or undefined for none). They are fail-open:
 // any error inside one is swallowed, so a hook can never fail or block a Claude Code session. Each call is counted in
 // `hook-calls.jsonl` with its own duration, so `measure` can count recall calls per session and the timings can be checked.
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
 import { performance } from 'node:perf_hooks';
 import { defaultConfigDir } from '../credentials.js';
 import { noEmit } from '../telemetry/emit.js';
@@ -10,6 +10,7 @@ import { cursorRoot } from './cursor.js';
 import { SOURCES, sourceLabel } from './sources.js';
 import { ACTION_TABLES, actionOf } from './actions.js';
 import { errorCodeOf, signatureOf } from './extract.js';
+import { recordCandidates } from './candidates.js';
 import { appendHookCall } from './hook-calls.js';
 import { contextBlock, readIndex } from './hook-index.js';
 import { bundleNext, frameKeyOf, lastTable, mergePositions, positionsRecall, recoveryDecision, recoveryRecall, signatureRecall, isSignatureRetry } from './recall-next.js';
@@ -62,6 +63,9 @@ const positionsTable = async (runtime, input, now, index, repeat) => {
 };
 const sessionStart = async (runtime, input, now) => {
     const cwd = str(input.cwd);
+    const session = str(input.session_id);
+    if (session !== undefined && cwd !== undefined)
+        await recordCandidates(runtime.storeDir, { session, cwd, claudeDir: dirname(runtime.projectsRoot), at: new Date(now()).toISOString() });
     const index = await readIndex(runtime.storeDir);
     const block = index === undefined || cwd === undefined ? undefined : contextBlock(index, { cwd, top: TOP, maxChars: MAX_CHARS });
     const recall = await positionsTable(runtime, input, now, index, false);
@@ -271,7 +275,7 @@ export const runHook = async (event, stdin, runtime, now, telemetry, emit = noEm
         latencyMs: ms,
         outcome: failed ? 'error' : recall?.arm === 'held' ? 'held' : outcome.hit ? 'hit' : 'miss',
         bytes: Buffer.byteLength(outcome.output ?? ''),
-        // The nightly is the scheduled task, not a harness's hook: it names no harness.
+        // The nightly is the detached sender (hook-bin.js nightly), not a harness's hook: it names no harness.
         ...frameWords(event === 'nightly' ? undefined : recall?.frame?.harness ?? HOOK_HARNESS, recall?.frame?.harnessVersion ?? stated?.harnessVersion, recall?.frame?.model ?? outcome.model ?? stated?.model),
     });
     // A push is a recall: its read is the family its query names (the `fit` push names none), and its arm is the exposure record, as a count of one.

package/dist/sessions/identity.d.ts

@@ -5,6 +5,12 @@ import type { PullIdentity, ShellIdentity, StepIdentity, ToolPull } from './sche
 export interface WordOfCommand {
     text: string;
     quoted: boolean;
+    /** The variable the whole word references, set only when its raw source is exactly one reference (`$NAME`, `"${NAME}"`); a `$` anywhere else in a word is text. */
+    variable?: string;
+    /** The word starts at or after the command's opaque point (`tokenize`), where a misread quote can turn literal text into words: the name read takes no variable, assignment, or flag value from it. */
+    opaque?: true;
+    /** The word's raw source starts with an unquoted `NAME=` or `--flag=` and holds a double quote after it (`API_REGION="eu"`, `--region="eu"`): `quoted` is true, but the text up to the `=` is as written, so the name and the joined value are read as for an unquoted word. Never set on a word that holds a single quote or a substitution after the `=`, since those are where literal text begins. */
+    joined?: true;
 }
 export declare const NUMBER_FLAG = "-N";
 export declare const isPositional: ({ text, quoted }: WordOfCommand) => boolean;

package/dist/sessions/injected.d.ts

@@ -0,0 +1,13 @@
+export type Json = string | number | boolean | null | Json[] | JsonObject;
+export interface JsonObject {
+    [key: string]: Json;
+}
+/** One transcript line, decoded; the same object back when nothing in it was an injected block. */
+export type InjectedRule = (line: JsonObject) => JsonObject;
+/**
+ * Adds to `known` the normalized text of what `line` holds that a request blob repeats without the flag that marked it: the text of a meta message
+ * and the rendered copy of an injected attachment. The redactor runs this over a whole transcript before it marks any line.
+ */
+export declare const learnInjected: (line: JsonObject, known: Set<string>) => Set<string>;
+/** The rule for one machine: every injected block of a decoded transcript line becomes `[injected <kind> <hash>]`, hashed under `key`; `known` is what `learnInjected` collected from the transcript. */
+export declare const injectedRule: (key: string, known?: ReadonlySet<string>) => InjectedRule;

package/dist/sessions/injected.js

@@ -0,0 +1,260 @@
+// The blocks a harness writes into a transcript on its own account: instruction files (`CLAUDE.md`, `AGENTS.md`), the memory index, skill and
+// tool lists, hook-added context, environment and session context, and the system prompt of a request. Every transcript carries them, and
+// they are the operator's standing instructions rather than anything typed in a session, so a raw copy holds a marker in their place:
+// `[injected <kind> <hash>]`, the hash a keyed hash of the block's whitespace-normalized text. The same block gives the same hash in every
+// session of a machine (books can still count which instruction set a session ran under), and the key stays on the machine.
+//
+// A block is replaced only where the harness puts one: a record type or attachment type it owns, a leading `<system-reminder>` of a user
+// message, a `<system-reminder>` in a tool result, or the text of a meta message. What an operator typed is left to the other rules. A block the
+// harness writes in a shape not listed here is not replaced until a rule covers it (docs/sessions-store.md, "What it cannot catch").
+import { createHmac } from 'node:crypto';
+const isObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const MARKER = /^\[injected [a-z0-9_-]+ [0-9a-f]{12}\]$/;
+// A string shorter than this is a label or a flag (`Project`, `user`), not a block.
+const MIN_BLOCK = 8;
+// Keys that name the record rather than hold its text: they stay readable.
+const STRUCTURAL = new Set(['type', 'name', 'hookName', 'hookEvent', 'toolUseID', 'path', 'displayPath']);
+const normalize = (text) => text.replace(/\s+/g, ' ').trim();
+const markerOf = (key, kind, text) => `[injected ${kind} ${createHmac('sha256', key).update(normalize(text)).digest('hex').slice(0, 12)}]`;
+/** Applies `change` to every string under `value`, with the key the string sits under; the same value back when nothing changed. */
+const mapStrings = (value, name, change) => {
+    if (typeof value === 'string')
+        return change(value, name);
+    if (Array.isArray(value)) {
+        const items = value.map((item) => mapStrings(item, name, change));
+        return items.some((item, at) => item !== value[at]) ? items : value;
+    }
+    if (isObject(value)) {
+        const before = Object.entries(value);
+        const after = before.map(([key, item]) => [key, mapStrings(item, key, change)]);
+        return after.some(([, item], at) => item !== before[at]?.[1]) ? Object.fromEntries(after) : value;
+    }
+    return value;
+};
+// Attachment types the harness writes to carry context or instructions to the model. A type outside this list (a queued prompt, a file the
+// operator mentioned, a task status) holds what a person or a tool produced and keeps the other rules.
+// Left out on purpose: the harness's fixed notices (`silent_turn_reminder`, `batching_reminder_sent`, `bash_output_audience_note`,
+// `read_truncation_notice`, `date`), which are the same wording on every machine or a bare date and hold nothing the operator wrote, and agent
+// output (`<task-notification>`, `<teammate-message>`), which is what an agent said and not an instruction.
+// Known misses, left to the other rules: the `content` of an `away_summary` system record, the `rendered` copy of a `compact_file_reference`
+// attachment (a file's text), and `<local-command-*>` blocks (the echo of a command the operator ran); `slug` and `cwd` stay readable.
+const INJECTED_ATTACHMENTS = new Set([
+    'instructions', 'nested_memory', 'skill_listing', 'invoked_skills', 'dynamic_skill', 'agent_listing_delta', 'deferred_tools_record', 'deferred_tools_delta',
+    'mcp_instructions_delta', 'prompt_snapshot', 'hook_success', 'hook_additional_context', 'hook_blocking_error', 'hook_non_blocking_error', 'hook_cancelled',
+    'environment', 'session_context', 'context_sections', 'credential_org', 'model', 'output_style', 'output_style_instructions', 'command_permissions',
+    'auto_mode', 'plan_mode', 'team_context',
+]);
+const blocksIn = (key, kind) => (text, name) => (text.length < MIN_BLOCK || STRUCTURAL.has(name) || MARKER.test(text) ? text : markerOf(key, kind, text));
+const REMINDER = /<system-reminder>[\s\S]*?<\/system-reminder>/g;
+const LEADING_REMINDERS = /^\s*(?:<system-reminder>[\s\S]*?<\/system-reminder>\s*)+/;
+/** The descriptions of a tool, its schema's included, become blocks; its name and the schema's keys and types stay. */
+const toolDescriptions = (key) => (value) => mapStrings(value, 'tool', (text, name) => (name === 'description' ? blocksIn(key, 'tool-definition')(text, name) : text));
+/** The text blocks of a message's content: `text` runs on the message's own text, `result` on the text of a tool result. */
+const mapContent = (content, text, result, definition) => {
+    if (typeof content === 'string')
+        return text(content);
+    if (!Array.isArray(content))
+        return content;
+    const items = content.map((block) => {
+        if (!isObject(block))
+            return block;
+        if (block['type'] === 'text' && typeof block['text'] === 'string') {
+            const next = text(block['text']);
+            return next === block['text'] ? block : { ...block, text: next };
+        }
+        if (block['type'] === 'tool_result') {
+            const inner = mapContent(block['content'], result, result, definition);
+            return inner === block['content'] || inner === undefined ? block : { ...block, content: inner };
+        }
+        // A request blob also carries the loaded definition of one tool, the text its request shape holds as `shape.tools`.
+        const tool = block['tool'];
+        if (isObject(tool) && isObject(tool['definition'])) {
+            const next = definition(tool['definition']);
+            return next === tool['definition'] ? block : { ...block, tool: { ...tool, definition: next } };
+        }
+        return block;
+    });
+    return items.some((item, at) => item !== content[at]) ? items : content;
+};
+// Harness text a request blob of the system role carries, by what it opens with or names. The whole block is marked, under the kind (and so the hash) its
+// attachment record gets, because it is the same text. First match wins. A system text with none of these forms is left to the other rules.
+const SYSTEM_FORMS = [
+    [/\bSessionStart(?::[\w-]+)? hook\b|\bhook additional context\b/, 'hook-additional-context'],
+    [/following skills are available for use with the Skill tool/i, 'skill-listing'],
+    [/Available agent types/i, 'agent-listing-delta'],
+    [/^\s*#{1,3} MCP Server Instructions\b|following MCP servers have provided instructions/m, 'mcp-instructions-delta'],
+    [/^\s*#{1,3} Environment\s*$|^\s*You have been invoked in the following environment/m, 'environment'],
+    [/Contents of [^\n]*?[\\/]\.claude[\\/]rules[\\/][^\n]*\.md\b|Contents of [^\n]*?(?:CLAUDE|AGENTS|MEMORY)(?:\.local)?\.md\b/, 'instructions'],
+];
+// A memory file: an instruction file, the memory index, a note under a `memory` folder, or a rules file.
+const MEMORY_PATH = /(?:^|[\\/])(?:CLAUDE|AGENTS|MEMORY)(?:\.local)?\.md$|[\\/]memory[\\/][^\\/]+\.md$|[\\/]\.claude[\\/]rules[\\/][^\\/]+\.md$/i;
+const MEMORY_MENTION = /(?:CLAUDE|AGENTS|MEMORY)(?:\.local)?\.md\b|[\\/]memory[\\/][^\s"'`\\/]+\.md\b/i;
+const CHANGED = /changed on disk|was modified/i;
+/** The kind of harness text a system-role string is, or undefined: one of the forms above, or a note that a memory file changed. */
+const systemKindOf = (text) => {
+    const form = SYSTEM_FORMS.find(([shape]) => shape.test(text));
+    if (form !== undefined)
+        return form[1];
+    return MEMORY_MENTION.test(text) && CHANGED.test(text) ? 'memory-file' : undefined;
+};
+const systemText = (key) => (text) => {
+    const kind = text.trim() === '' || MARKER.test(text.trim()) ? undefined : systemKindOf(text);
+    return kind === undefined ? text : markerOf(key, kind, text);
+};
+const messageRule = (key, position, known) => {
+    const whole = (text) => (text.trim() === '' || MARKER.test(text.trim()) ? text : markerOf(key, 'meta', text));
+    const leading = (text) => {
+        const run = LEADING_REMINDERS.exec(text);
+        return run === null ? text : `${run[0].replace(REMINDER, (block) => markerOf(key, 'system-reminder', block))}${text.slice(run[0].length)}`;
+    };
+    // A request blob repeats earlier messages and carries no `isMeta`: a text block that is the text of a meta message or an injected attachment
+    // is marked `meta`, whatever kind its first line carries; the hash is the same, so the two lines still match on the hash.
+    const repeated = (text) => (known.has(normalize(text)) ? markerOf(key, 'meta', text) : leading(text));
+    const anywhere = (text) => text.replace(REMINDER, (block) => markerOf(key, 'system-reminder', block));
+    return (message) => {
+        const content = mapContent(message['content'], position === 'meta' ? whole : position === 'blob' ? repeated : leading, anywhere, toolDescriptions(key));
+        return content === message['content'] || content === undefined ? message : { ...message, content };
+    };
+};
+const withMessage = (line, field, rule, role = 'user') => {
+    const message = line[field];
+    if (!isObject(message) || message['role'] !== role)
+        return line;
+    const next = rule(message);
+    return next === message ? line : { ...line, [field]: next };
+};
+/** The rule for a request blob of the system role: the harness's own forms first, then the text other lines repeat. */
+const systemMessage = (key, known) => {
+    const mark = systemText(key);
+    const text = (value) => {
+        const next = mark(value);
+        return next !== value || !known.has(normalize(value)) ? next : markerOf(key, 'meta', value);
+    };
+    return (message) => {
+        const content = mapContent(message['content'], text, text, (tool) => tool);
+        return content === message['content'] || content === undefined ? message : { ...message, content };
+    };
+};
+const withField = (line, field, change) => {
+    const value = line[field];
+    if (value === undefined)
+        return line;
+    const next = change(value);
+    return next === value ? line : { ...line, [field]: next };
+};
+// Codex: a developer message is the harness talking, and a user message that opens with one of these tags is context it added. What a person typed has no tag.
+const CODEX_USER_TAGS = /^\s*(<environment_context>|<user_instructions>|<guardian_tool_descriptions>|# AGENTS\.md instructions)/;
+const CODEX_FIELDS = ['base_instructions', 'instructions', 'user_instructions', 'developer_instructions'];
+const codexKind = (text, fallback) => {
+    const tag = /^\s*<([a-z_]+)[ >]/.exec(text);
+    return tag?.[1]?.replaceAll('_', '-') ?? fallback;
+};
+const codexMessage = (key, payload) => {
+    const role = payload['role'];
+    if (role !== 'developer' && role !== 'user')
+        return payload;
+    const content = payload['content'];
+    if (!Array.isArray(content))
+        return payload;
+    const items = content.map((block) => {
+        if (!isObject(block) || typeof block['text'] !== 'string')
+            return block;
+        const text = block['text'];
+        const injected = role === 'developer' ? text.trim() !== '' : CODEX_USER_TAGS.test(text);
+        if (!injected || MARKER.test(text.trim()))
+            return block;
+        return { ...block, text: markerOf(key, role === 'developer' ? codexKind(text, 'developer') : codexKind(text, 'agents-md'), text) };
+    });
+    return items.some((item, at) => item !== content[at]) ? { ...payload, content: items } : payload;
+};
+const codexFields = (key, payload) => CODEX_FIELDS.reduce((acc, name) => withField(acc, name, (value) => mapStrings(value, name, blocksIn(key, name.replaceAll('_', '-')))), payload);
+const ORIGIN_TEXT = ['body', 'handback'];
+const HOOK_SUMMARY_FIELDS = ['hookAdditionalContext', 'hookErrors', 'hookInfos'];
+const textsOf = (content) => {
+    if (typeof content === 'string')
+        return [content];
+    if (!Array.isArray(content))
+        return [];
+    return content.flatMap((block) => (isObject(block) && block['type'] === 'text' && typeof block['text'] === 'string' ? [block['text']] : []));
+};
+/**
+ * Adds to `known` the normalized text of what `line` holds that a request blob repeats without the flag that marked it: the text of a meta message
+ * and the rendered copy of an injected attachment. The redactor runs this over a whole transcript before it marks any line.
+ */
+export const learnInjected = (line, known) => {
+    const add = (text) => {
+        if (text.trim() !== '' && !MARKER.test(text.trim()))
+            known.add(normalize(text));
+    };
+    const message = line['message'];
+    if (line['type'] === 'user' && line['isMeta'] === true && isObject(message) && message['role'] === 'user')
+        textsOf(message['content']).forEach(add);
+    const attachment = line['attachment'];
+    const kind = isObject(attachment) ? attachment['type'] : undefined;
+    if (line['type'] === 'attachment' && typeof kind === 'string' && INJECTED_ATTACHMENTS.has(kind) && line['rendered'] !== undefined) {
+        mapStrings(line['rendered'], 'rendered', (text, name) => {
+            if (text.length >= MIN_BLOCK && !STRUCTURAL.has(name))
+                add(text);
+            return text;
+        });
+    }
+    return known;
+};
+/** The rule for one machine: every injected block of a decoded transcript line becomes `[injected <kind> <hash>]`, hashed under `key`; `known` is what `learnInjected` collected from the transcript. */
+export const injectedRule = (key, known = new Set()) => {
+    const userMessage = messageRule(key, 'typed', known);
+    const metaMessage = messageRule(key, 'meta', known);
+    const blobMessage = messageRule(key, 'blob', known);
+    const systemBlob = systemMessage(key, known);
+    const memory = blocksIn(key, 'memory-file');
+    // A meta line's `origin` says where the injected text came from; its `body` and `handback` are that text again, while `kind` stays readable.
+    const originText = (origin) => {
+        if (!isObject(origin))
+            return origin;
+        return ORIGIN_TEXT.reduce((acc, name) => withField(acc, name, (value) => mapStrings(value, name, blocksIn(key, 'meta'))), origin);
+    };
+    return (line) => {
+        switch (line['type']) {
+            case 'user':
+                return line['isMeta'] === true ? withField(withMessage(line, 'message', metaMessage), 'origin', originText) : withMessage(line, 'message', userMessage);
+            case 'api-request-blob':
+                return withMessage(withMessage(line, 'message', blobMessage), 'message', systemBlob, 'system');
+            case 'attachment': {
+                const attachment = line['attachment'];
+                const kind = isObject(attachment) ? attachment['type'] : undefined;
+                // A memory file the model edited or that changed on disk: the snippet (and the message it was shown in) is the file's text.
+                const file = isObject(attachment) ? attachment['filename'] : undefined;
+                if (kind === 'edited_text_file' && typeof file === 'string' && MEMORY_PATH.test(file)) {
+                    const snippet = (value) => (isObject(value) ? withField(value, 'snippet', (text) => mapStrings(text, 'snippet', memory)) : value);
+                    return withField(withField(line, 'attachment', snippet), 'rendered', (value) => mapStrings(value, 'rendered', memory));
+                }
+                if (typeof kind !== 'string' || !INJECTED_ATTACHMENTS.has(kind))
+                    return line;
+                // The record repeats its text as the message the model was shown (`rendered`), so that is the same block again.
+                const marked = (value) => mapStrings(value, 'attachment', blocksIn(key, kind.replaceAll('_', '-')));
+                return withField(withField(line, 'attachment', marked), 'rendered', marked);
+            }
+            case 'api-request-shape':
+                return withField(line, 'shape', (shape) => {
+                    if (!isObject(shape))
+                        return shape;
+                    return withField(withField(shape, 'system', (system) => mapStrings(system, 'system', blocksIn(key, 'system-prompt'))), 'tools', toolDescriptions(key));
+                });
+            case 'system':
+                // The hook output a stop-hook summary carries: what a hook printed, its error text, and the command line it ran.
+                if (line['subtype'] === 'stop_hook_summary')
+                    return HOOK_SUMMARY_FIELDS.reduce((acc, name) => withField(acc, name, (value) => mapStrings(value, name, blocksIn(key, 'hook-summary'))), line);
+                // Any other system text is the harness speaking (a changed memory file, a notice), except the echo of a command the operator ran: that is operator output, not an instruction.
+                if (line['subtype'] === 'local_command')
+                    return line;
+                return withField(line, 'content', (value) => (typeof value === 'string' ? systemText(key)(value) : value));
+            case 'session_meta':
+            case 'turn_context':
+                return withField(line, 'payload', (payload) => (isObject(payload) ? codexFields(key, payload) : payload));
+            case 'response_item':
+                return withField(line, 'payload', (payload) => (isObject(payload) && payload['type'] === 'message' ? codexMessage(key, payload) : payload));
+            default:
+                return line;
+        }
+    };
+};

package/dist/sessions/install.d.ts

@@ -1,9 +1,15 @@
+import type { CodexInstall } from './codex-hook-install.js';
 export declare const RETENTION_FLOOR = 365;
 export declare const DEFAULT_RETENTION = 30;
 export declare const TASK_NAME = "OarsSessionsNightly";
+/**
+ * What `--machine` writes for Stop and SessionEnd. A settings file committed from one machine is read on another (a cloud VM, a runner), where the installing machine's node and `hook-bin.js` paths do not exist, so this names no path:
+ * it resolves the `oars-hook` bin on PATH, and exits 0 when there is none (a hook that cannot start must not fail the session).
+ */
+export declare const MACHINE_COMMAND = "command -v oars-hook >/dev/null || exit 0; oars-hook stop --machine";
 /** What the install needs from the machine, so a test can stand in for each. */
 export interface InstallRuntime {
-    /** `process.platform`: only `win32` has the nightly task. */
+    /** `process.platform`: only `win32` ever had the nightly task. */
     platform: NodeJS.Platform;
     nodePath: string;
     /** Absolute path of the built `hook-bin.js`. */
@@ -11,7 +17,9 @@ export interface InstallRuntime {
     /** `<claude config dir>/settings.json`. */
     userSettings: string;
     cwd: string;
-    /** Runs `schtasks` with these arguments. */
+    /** Where the Codex recording hook goes (`--harness codex`); absent in a run that has none. */
+    codex?: CodexInstall;
+    /** Runs `schtasks` with these arguments; used only to remove the task an earlier version registered. */
     schtasks: (args: string[]) => Promise<{
         code: number;
         output: string;
@@ -19,7 +27,7 @@ export interface InstallRuntime {
 }
 export type Scope = 'user' | 'project' | 'file';
 /** A settings file is open-ended JSON the harness owns; only the keys named here are read or written. */
-interface Json {
+export interface Json {
     [key: string]: unknown;
 }
 /**
@@ -28,8 +36,14 @@ interface Json {
  * milliseconds); any other tool's failure goes straight to node, because its text has no such line and its recovery read does not need one.
  */
 export declare const commandOf: (runtime: InstallRuntime, arg: string) => string;
+/** The groups with our entries taken out; a group that held only ours goes, one that held others keeps them. `own` tells ours by the command's tail. */
+export declare const withoutOwn: (groups: unknown[], own?: RegExp) => unknown[];
+export declare const hasOwn: (groups: unknown[], own?: RegExp) => boolean;
 export declare const settingsPath: (runtime: InstallRuntime, scope: Scope, file: string | undefined) => string;
 export declare const readSettings: (path: string) => Promise<Json>;
+export declare const writeSettings: (path: string, settings: Json) => Promise<void>;
+export declare const hooksOf: (settings: Json) => Json;
+export declare const groupsOf: (hooks: Json, event: string) => unknown[];
 /** The retention the file sets: its `cleanupPeriodDays` when a number, else the harness default. */
 export declare const effectiveRetention: (settings: Json) => number;
 export interface InstallResult {
@@ -38,6 +52,13 @@ export interface InstallResult {
     retention: string;
 }
 export declare const installHooks: (runtime: InstallRuntime, path: string, keepRetention: boolean) => Promise<InstallResult>;
+/**
+ * `hook install --machine`: the Stop and SessionEnd entries that run `oars-hook stop --machine`, merged with what is there (only entries of ours are replaced). With `env`, the enrollment block goes to this file's `env`
+ * block, merged with the operator's own entries, and the file is made owner-only, because it then holds the salts and the terms. A project file gets no `env`: it is committed.
+ */
+export declare const installMachineHooks: (path: string, env: {
+    [name: string]: string;
+} | undefined) => Promise<InstallResult>;
 export declare const uninstallHooks: (path: string) => Promise<{
     file: string;
     removed: string[];
@@ -49,22 +70,12 @@ export interface FileStatus {
     retentionDays: number;
 }
 export declare const hookStatus: (runtime: InstallRuntime, extra: string | undefined) => Promise<FileStatus[]>;
-/** The `schtasks` arguments for the nightly task: the same node and hook-bin the hooks use, at a fixed hour. */
-export declare const scheduleArgs: (runtime: InstallRuntime, hour: number) => string[];
-export declare const SCHEDULE_HOUR = 3;
-export declare const setSchedule: (runtime: InstallRuntime, mode: "nightly" | "off") => Promise<string>;
-/** True once the operator ran `--schedule off` and has not run `--schedule nightly` since. A record that cannot be read or parsed counts as no opt-out. */
-export declare const scheduleOptedOut: (storeDir: string) => Promise<boolean>;
-/** Records the choice of `--schedule`: `off` writes the opt-out; `nightly` clears it. Without a store the choice has nowhere to live and is not recorded. */
-export declare const recordSchedule: (storeDir: string | undefined, mode: "nightly" | "off") => Promise<void>;
-/** What a plain `hook install` says when the operator turned the nightly task off: it is left alone. */
-export declare const SCHEDULE_LEFT_OFF = "Scheduled task OarsSessionsNightly: left off, as you chose with --schedule off. Turn it back on with: oars sessions hook install --schedule nightly";
+/** What `hook install` says to someone who asks for the task that earlier versions registered: sends ride the hook and the commands now. */
+export declare const SCHEDULE_REFUSED = "oars no longer registers a scheduled task: sends now ride the session-end hook and any oars command (at most about hourly). Run: oars sessions hook install";
 /**
- * What a plain `hook install` does about the nightly task on Windows: register it unless it is already there. Registration is
- * best effort: the hooks are installed by then, so a machine that refuses the task (policy, no Task Scheduler) is told how to retry
- * and is not failed. `install --schedule off` removes the task and records the opt-out (`recordSchedule`), which the caller checks
- * (`scheduleOptedOut`) before calling this; `--schedule nightly` clears it.
+ * Removes the nightly task an earlier version registered, and says so in one line; nothing when it is not there. Only Windows ever had one, so any other platform makes no call. Install and uninstall both
+ * call this, so a machine that upgrades loses the task the first time either runs. A task that is there but refuses to go (policy) is reported, never failed: the hooks are the work of the command.
  */
-export declare const ensureSchedule: (runtime: InstallRuntime) => Promise<string>;
-export declare const scheduleStatus: (runtime: InstallRuntime) => Promise<string>;
-export {};
+export declare const removeSchedule: (runtime: InstallRuntime) => Promise<string | undefined>;
+/** The status line for a task left over from an earlier version; nothing when there is none. */
+export declare const scheduleStatus: (runtime: InstallRuntime) => Promise<string | undefined>;