@manyoars/oars 0.4.1 → 0.5.1

package/dist/sessions/read-call-shape.js

@@ -1,15 +1,21 @@
 // Call shape (the fit family's other method): one tool and its input key names, over the floors a shape needs before a hook may push it. A shape is what a pre-tool hook can
-// compute from the call it is about to run, so this read is what a push cites. A failure is not in a cell by shape, so its evidence is the failed one-step cells of the
-// tool's action on the days the shape failed. Same confounders as `read-fit.ts`: a failure is not a misfit, and prompt class is not adjusted for.
-import { shapeMotif } from './motif.js';
+// compute from the call it is about to run, so this read is what a push cites. Its evidence is the shape cells that count the action's calls by those key names (`shape:<action>/keys/<names>`, a week
+// cell per version bucket, `shapeClass`), in the weeks the shape failed. Same confounders as `read-fit.ts`: a failure is not a misfit, and prompt class is not adjusted for. A bundle holds no store, so the
+// pool serves the same cells as `fit-shape` (`deriveFitShape`), by every facet of shape and not this one tool's.
+import { lastDayOfCell, parseShapeClass, UNKNOWN } from './cells.js';
+import { OPEN_GATE, wireKeys } from './pool-wire.js';
 import { CALL_SHAPE_METHOD } from './read.js';
 import { actionOfShape, fitReads, toolShapeId } from './recall-reads.js';
 import { body, atGrain, rate, wilson } from './read-support.js';
 export const deriveCallShape = ({ pool, store }) => fitReads(store).flatMap((read) => {
     const action = actionOfShape(read.tool, read.harnesses);
-    const motifId = shapeMotif([{ action, identity: null }]).motifId;
-    const within = (day) => read.firstDay !== null && read.lastDay !== null && day >= read.firstDay && day <= read.lastDay;
-    const cells = atGrain(pool, 'day').filter((cell) => cell.motifId === motifId && cell.failed > 0 && within(cell.day));
+    // The cell names the keys as the wire sends them (`projectedStore`); a record captured before steps was never projected, so its raw names are the other spelling.
+    const names = new Set([wireKeys(read.keys, read.tool, OPEN_GATE).keys.join(','), read.keys.join(',')]);
+    const within = (cell) => read.firstDay !== null && read.lastDay !== null && cell.day <= read.lastDay && lastDayOfCell(cell) >= read.firstDay;
+    const cells = atGrain(pool, 'week').filter((cell) => {
+        const shape = cell.day === UNKNOWN ? null : parseShapeClass(pool.motifs.get(cell.motifId)?.cls ?? '');
+        return shape !== null && shape.action === action && shape.facet === 'keys' && names.has(shape.value) && cell.failed > 0 && within(cell);
+    });
     // A shape whose failures are in no cell has nothing to cite, so it is not a read: its answers keep their stand-in.
     if (cells.length === 0)
         return [];

package/dist/sessions/read-fit.d.ts

@@ -5,3 +5,8 @@ export declare const deriveFit: DeriveFamily;
  * this read is its own, and a read of the version cells does not see these cells (`atGrain`). A shell the frame does not name reads as `unknown`, as a missing model does.
  */
 export declare const deriveFitEnvironment: DeriveFamily;
+/**
+ * Fit by call shape: how often calls of an action fail when they hold one facet of shape (a target class, an argument class, a count of unsent key names, a set of key names, or a value feature, closed value, or change kind of a sent key), by harness version bucket, from the
+ * shape cells (`shapeClass`). A cell counts each call once per facet it holds, so the facets of one action are never summed into one rate. Same confounders as the reads above, and a facet is not the failure's cause.
+ */
+export declare const deriveFitShape: DeriveFamily;

package/dist/sessions/read-fit.js

@@ -1,8 +1,8 @@
 // Fit (rank 2): how often a tool fails on this frame, by harness version bucket and model. Effort is not in a cell (rule 3), so it is not a slice. Confounders it does not remove: a failure is not a
 // misfit, red tests can be the method, effort, and prompt class is not adjusted for.
-import { bucketFields, environmentFieldsOf } from './cells.js';
+import { bucketFields, environmentFieldsOf, parseShapeClass } from './cells.js';
 import { motifName } from './motif.js';
-import { body, environmentCells, groupBy, rate, settled, total, unitCells, wilson } from './read-support.js';
+import { atGrain, body, environmentCells, groupBy, rate, settled, total, unitCells, wilson } from './read-support.js';
 export const deriveFit = ({ pool }) => [...groupBy(unitCells(pool, 'week'), ({ cell }) => `${cell.motifId}/${cell.frameBucket}`).values()].flatMap((group) => {
     const [first] = group;
     const cells = group.map(({ cell }) => cell);
@@ -39,3 +39,24 @@ export const deriveFitEnvironment = ({ pool }) => [...groupBy(environmentCells(p
         }),
     ];
 });
+/**
+ * Fit by call shape: how often calls of an action fail when they hold one facet of shape (a target class, an argument class, a count of unsent key names, a set of key names, or a value feature, closed value, or change kind of a sent key), by harness version bucket, from the
+ * shape cells (`shapeClass`). A cell counts each call once per facet it holds, so the facets of one action are never summed into one rate. Same confounders as the reads above, and a facet is not the failure's cause.
+ */
+export const deriveFitShape = ({ pool }) => [...groupBy(atGrain(pool, 'week'), (cell) => `${cell.motifId}/${cell.frameBucket}`).values()].flatMap((group) => {
+    const [first] = group;
+    const shape = first === undefined ? null : parseShapeClass(pool.motifs.get(first.motifId)?.cls ?? '');
+    const n = total(group, settled);
+    if (first === undefined || shape === null || n === 0)
+        return [];
+    const failed = total(group, (cell) => cell.failed);
+    const { harness, harnessBucket } = bucketFields(first.frameBucket);
+    return [
+        body('fit', group, {
+            slice: { action: shape.action, facet: shape.facet, value: shape.value, harness, harnessBucket },
+            value: { failureRate: rate(failed, n), failed, ok: n - failed },
+            n,
+            interval: wilson(failed, n),
+        }),
+    ];
+});

package/dist/sessions/read.d.ts

@@ -69,7 +69,7 @@ export interface Read {
     interval: ReadInterval | null;
     asOf: ReadAsOf;
     basis: ReadBasis;
-    /** The floor this read cleared (its family's, which is the public floor unless `floors.families` names the family): every cell it counts had at least this many clusters. Stated by a pool that serves the read, and absent from a read computed on one operator's own store, which applies no public floor. */
+    /** The lowest floor among the cells it cites, each cell's being the floor of its class in the read's family (`cellFloor`): every cell it counts had at least this many clusters. Stated by a pool that serves the read, and absent from a read computed on one operator's own store, which applies no public floor. */
     floor?: number;
 }
 /** A read before its inputs are checked and its ID and order are computed. */

package/dist/sessions/recall-consequence.d.ts

@@ -31,9 +31,9 @@ export interface RecallCountRow {
     sessions: number;
     /** The size of what was injected, or for a held recall would have been. */
     tokens: number;
-    /** Recalls with a consequence window, and of those how many followed. */
+    /** Recalls with a consequence window, and of those how many have a call whose action name is one the recall carried. */
     windows: number;
-    followed: number;
+    nameMatched: number;
     windowCalls: number;
     /** Null when no window in the row measured any tokens. */
     windowTokens: number | null;

package/dist/sessions/recall-consequence.js

@@ -3,6 +3,7 @@
 // shown recall touches the graph, because a held one reached nobody: it adds no `recall.*` step and exposes no cell.
 import { motifsOf, stepsOfCall } from './motif.js';
 import { bucketOf, floorOf } from './pool-wire.js';
+import { reversionsOf } from './reversion.js';
 import { harnessOf } from './schema.js';
 /** A consequence window ends at the prompt's end or after this many calls (spec Section 2.7). */
 export const WINDOW_CALLS = 20;
@@ -35,14 +36,16 @@ const positionOf = (line, at) => {
     const next = line.findIndex((tool) => tool.ts !== null && tool.ts > at);
     return next < 0 ? line.length : next;
 };
-const outcomeOf = (prompt) => ({
+/** The values the prompt first showed, and beside them, never in place of them, the nearest later revert of a commit the prompt made (null when none is tied). */
+const outcomeOf = (prompt, reverted) => ({
     errors: prompt?.errors ?? null,
     verify: prompt?.verify ?? null,
     stopped: prompt?.stopped ?? null,
     commits: prompt?.commits ?? null,
     redo: prompt?.redo ?? null,
+    reverted: prompt === undefined ? null : reverted,
 });
-const consequenceOf = (recall, session, line, position, harness, prompts) => {
+const consequenceOf = (recall, session, line, position, harness, prompts, reverted) => {
     const prompt = (line[position - 1] ?? line[position])?.prompt ?? null;
     const calls = [];
     let end = 'session';
@@ -64,9 +67,10 @@ const consequenceOf = (recall, session, line, position, harness, prompts) => {
         window: { from: position, to: position + calls.length, calls: calls.length, end },
         // Shape level only: it is the ID that joins across accounts, and named windows would multiply a row that exists per recall.
         motifs: [...new Set(motifsOf(steps).flatMap(({ motif }) => (motif.level === 'shape' ? [motif.motifId] : [])))],
-        followed: steps.some((step) => names.has(step.action)),
+        // The action name is the whole basis: a call of the shown action that failed, or did something else with it, still matches. The record holds no stronger evidence yet, so none is implied.
+        nameMatched: steps.some((step) => names.has(step.action)),
         cost: { tokens: measured.length === 0 ? null : measured.reduce((sum, tokens) => sum + tokens, 0), durationMs: steps.reduce((sum, step) => sum + step.durationMs, 0) },
-        outcome: outcomeOf(prompts.get(promptKey(session, prompt))),
+        outcome: outcomeOf(prompts.get(promptKey(session, prompt)), reverted(session, prompt)),
     };
 };
 /** Fills `n` and `consequence`. A recall with no session, or from a session this store does not hold, has nothing to read and comes back as it was. */
@@ -74,13 +78,14 @@ export const deriveConsequences = (store, recalls) => {
     const lines = mainLines(store);
     const prompts = new Map(store.prompts.map((prompt) => [promptKey(prompt.session, prompt.index), prompt]));
     const sessions = new Map(store.sessions.map((session) => [session.session, session]));
+    const reverted = reversionsOf(store);
     return recalls.map((recall) => {
         const session = recall.sid === null ? undefined : sessions.get(recall.sid);
         if (session === undefined)
             return recall;
         const line = lines.get(session.session) ?? [];
         const position = positionOf(line, recall.at);
-        return { ...recall, n: position, consequence: consequenceOf(recall, session.session, line, position, harnessOf(session), prompts) };
+        return { ...recall, n: position, consequence: consequenceOf(recall, session.session, line, position, harnessOf(session), prompts, reverted) };
     });
 };
 export const NO_RECALLS = {
@@ -150,7 +155,7 @@ export const recallCounts = (recalls, day) => {
         if (day !== undefined && !recall.at.startsWith(day))
             continue;
         const key = [recall.mode, recall.arm, recall.answer.kind].join(' ');
-        const held = rows.get(key) ?? { row: { mode: recall.mode, arm: recall.arm, kind: recall.answer.kind, recalls: 0, sessions: 0, tokens: 0, windows: 0, followed: 0, windowCalls: 0, windowTokens: null, overlapped: 0 }, sessions: new Set() };
+        const held = rows.get(key) ?? { row: { mode: recall.mode, arm: recall.arm, kind: recall.answer.kind, recalls: 0, sessions: 0, tokens: 0, windows: 0, nameMatched: 0, windowCalls: 0, windowTokens: null, overlapped: 0 }, sessions: new Set() };
         rows.set(key, held);
         const { row, sessions } = held;
         row.recalls += 1;
@@ -162,8 +167,8 @@ export const recallCounts = (recalls, day) => {
         if (consequence === undefined)
             continue;
         row.windows += 1;
-        if (consequence.followed)
-            row.followed += 1;
+        if (consequence.nameMatched)
+            row.nameMatched += 1;
         row.windowCalls += consequence.window.calls;
         if (consequence.cost.tokens !== null)
             row.windowTokens = (row.windowTokens ?? 0) + consequence.cost.tokens;
@@ -175,5 +180,5 @@ export const recallCounts = (recalls, day) => {
 export const formatRecallCounts = (rows) => rows.length === 0
     ? 'No recalls in that span.'
     : rows
-        .map((row) => `${row.mode} ${row.arm} ${row.kind} | ${String(row.recalls)} recalls, ${String(row.sessions)} sessions, ${String(row.tokens)} tokens | ${String(row.windows)} windows, ${String(row.followed)} followed, ${String(row.windowCalls)} calls, ${row.windowTokens === null ? 'window tokens unmeasured' : `${String(row.windowTokens)} window tokens`}, ${String(row.overlapped)} overlapped`)
+        .map((row) => `${row.mode} ${row.arm} ${row.kind} | ${String(row.recalls)} recalls, ${String(row.sessions)} sessions, ${String(row.tokens)} tokens | ${String(row.windows)} windows, ${String(row.nameMatched)} name-matched, ${String(row.windowCalls)} calls, ${row.windowTokens === null ? 'window tokens unmeasured' : `${String(row.windowTokens)} window tokens`}, ${String(row.overlapped)} overlapped`)
         .join('\n');

package/dist/sessions/recall-object.d.ts

@@ -1,3 +1,4 @@
+import type { Reversion } from './reversion.js';
 import type { Frame } from './schema.js';
 export declare const recallsPath: (storeDir: string) => string;
 /** The share of pushes held back (spec Section 8, open parameter). */
@@ -38,7 +39,7 @@ export interface RecallAnswer {
     bytes?: number;
     /** What the asker saw, or for a held recall would have seen. It holds structured fields only (`recall-render.ts`). */
     rendered: string;
-    /** The closed names a follow can match: canonical actions, in the order shown. */
+    /** The closed names a name match can find: canonical actions, in the order shown. */
     names: string[];
 }
 export type DeltaAxis = 'same' | 'differs' | 'unknown';
@@ -79,6 +80,11 @@ export interface RecallOutcome {
     stopped: string | null;
     commits: number | null;
     redo: boolean | null;
+    /**
+     * Where the nearest later clean `git revert <sha>` of a commit this prompt made ran, beside the values above and never in place of them. The sha is the whole tie, so null says none was found, not that
+     * none happened: an edit undone any other way, or a commit with no sha, is not read.
+     */
+    reverted: Reversion | null;
 }
 /** Derived from the capture records, never captured live. */
 export interface RecallConsequence {
@@ -90,7 +96,8 @@ export interface RecallConsequence {
         end: 'prompt' | 'calls' | 'session';
     };
     motifs: string[];
-    followed: boolean;
+    /** Whether an action name the recall carried appears among the window's actions. A match on the name alone: it does not say the call took the advice, was the same use of that action, or went well. */
+    nameMatched: boolean;
     /** `tokens` is null when no call in the window measured any: an older capture has no step costs, and zero would read as a free window. */
     cost: {
         tokens: number | null;

package/dist/sessions/receipt.d.ts

@@ -0,0 +1,8 @@
+import { type RecallQuery } from './query.js';
+import type { Store } from './store.js';
+export declare const RECEIPT_FOOTER = "from my local oars record, manyoars.com";
+export declare const RECEIPT_MISS = "No earlier session in the local record hit this error, so there is no receipt.";
+/** ISO 8601 week of a timestamp, as `2026-W45`; the week holds the Thursday, which fixes the year. */
+export declare const isoWeek: (ts: string) => string | undefined;
+/** The receipt for the best-matching signature of an error text, or null when no earlier session hit it. */
+export declare const receiptOf: (store: Store, query: RecallQuery, now: number, redactDomains?: readonly string[], names?: readonly string[]) => string | null;

package/dist/sessions/receipt.js

@@ -0,0 +1,78 @@
+// `oars sessions recall --error <text> --receipt`: a fenced Markdown block a person pastes into an issue on the failing tool. It states the tool and
+// harness by listed name, the error's normalized signature, how many earlier sessions hit it and in which weeks, and what those sessions did next. It
+// reads the same match recall does and the same redactor, so nothing here is a second path to a stored string.
+import { ACTION_TABLES } from './actions.js';
+import { redactTranscript } from './redact.js';
+import { recall } from './query.js';
+import { LITERAL } from './public-vocabulary.js';
+import { closedName } from './recall-render.js';
+import { harnessOf } from './schema.js';
+export const RECEIPT_FOOTER = 'from my local oars record, manyoars.com';
+export const RECEIPT_MISS = 'No earlier session in the local record hit this error, so there is no receipt.';
+const OTHER = 'other';
+const SIGNATURE_LIMIT = 120;
+const NEXT_SHOWN = 3;
+const MCP_WORD = /mcp__[A-Za-z0-9_-]+/g;
+const DAY_MS = 86_400_000;
+/** A tool as a person may name it in an issue: a listed name as it stands, anything else `other`. */
+const listedTool = (name) => {
+    const listed = closedName(name);
+    return listed === LITERAL ? OTHER : listed;
+};
+const listedHarness = (name) => (Object.hasOwn(ACTION_TABLES, name) ? name : OTHER);
+/** ISO 8601 week of a timestamp, as `2026-W45`; the week holds the Thursday, which fixes the year. */
+export const isoWeek = (ts) => {
+    const at = Date.parse(ts);
+    if (Number.isNaN(at))
+        return undefined;
+    const day = new Date(Math.floor(at / DAY_MS) * DAY_MS);
+    const weekday = day.getUTCDay() === 0 ? 7 : day.getUTCDay();
+    const thursday = new Date(day.getTime() + (4 - weekday) * DAY_MS);
+    const jan1 = Date.UTC(thursday.getUTCFullYear(), 0, 1);
+    const week = Math.floor((thursday.getTime() - jan1) / DAY_MS / 7) + 1;
+    return `${String(thursday.getUTCFullYear())}-W${String(week).padStart(2, '0')}`;
+};
+const times = (count) => `${String(count)} ${count === 1 ? 'time' : 'times'}`;
+/** The receipt for the best-matching signature of an error text, or null when no earlier session hit it. */
+export const receiptOf = (store, query, now, redactDomains = [], names = []) => {
+    const [top] = recall(store, query, now, 1, redactDomains).matches;
+    if (top === undefined)
+        return null;
+    const rows = store.errors.filter((error) => error.sig === top.sig);
+    const sessionIds = new Set(rows.map((error) => error.session));
+    const harnesses = [...new Set(store.sessions.filter((session) => sessionIds.has(session.session)).map((session) => listedHarness(harnessOf(session))))].sort();
+    const weeks = [...new Set(rows.flatMap((error) => { const week = error.ts === null ? undefined : isoWeek(error.ts); return week === undefined ? [] : [week]; }))].sort().reverse();
+    // Listed tool names folded together: two unlisted tools are both `other`, once.
+    const next = new Map();
+    for (const { tool, count } of top.followedBy)
+        next.set(listedTool(tool), (next.get(listedTool(tool)) ?? 0) + count);
+    const followed = [...next.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).slice(0, NEXT_SHOWN).map(([tool, count]) => `${tool} x${String(count)}`);
+    // The key is `<tool> | <text>`; the tool is stated by its listed name. The text first loses the literals the store records for the matched sessions
+    // (branches, project slugs; the transcript rules have no rule for either), then runs through the transcript rules (home paths, encoded folder slugs,
+    // local names, secrets), and only the redacted result is cut. Every unlisted `mcp__` word becomes `other`, with backticks out so the fence holds.
+    const recorded = store.sessions.filter((entry) => sessionIds.has(entry.session));
+    const labels = new Map();
+    for (const entry of recorded) {
+        for (const branch of entry.branches)
+            labels.set(branch, '<branch>');
+        labels.set(entry.project, '<project>');
+    }
+    // A literal goes only where it stands as a whole token, so a branch named `main` leaves `domain` and `./main.js` alone.
+    const literals = [...labels.entries()].filter(([literal]) => literal.length > 0).sort((a, b) => b[0].length - a[0].length || a[0].localeCompare(b[0]));
+    const scrubbed = literals.reduce((text, [literal, label]) => text.replace(new RegExp(`(?<![A-Za-z0-9_-])${literal.replaceAll(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?![A-Za-z0-9_-])`, 'g'), label), top.sig.slice(top.sig.indexOf(' | ') + 3));
+    const text = redactTranscript(scrubbed, redactDomains, names).text.slice(0, SIGNATURE_LIMIT).replace(MCP_WORD, (word) => listedTool(word)).replaceAll('`', "'");
+    return [
+        '```markdown',
+        '**Error receipt**',
+        '',
+        `- Tool: ${listedTool(top.tool)}`,
+        `- Harness: ${harnesses.join(', ') || OTHER}`,
+        `- Error: \`${text}\``,
+        `- Earlier sessions that hit it: ${String(top.sessions)} (${times(top.count)})`,
+        `- Weeks: ${weeks.join(', ') || 'unknown'}`,
+        `- What they did next: ${followed.join(', ') || 'nothing recorded'}; an edit followed ${times(top.editFollowed)}`,
+        '',
+        RECEIPT_FOOTER,
+        '```',
+    ].join('\n');
+};

package/dist/sessions/recovery-calls.d.ts

@@ -9,7 +9,7 @@ export type Followed = Pick<ToolObservation, 'side' | 'prompt'> & {
 };
 /** How many following calls a failed call lists. */
 export declare const RECOVERY_CALLS = 5;
-/** What followed one failed call: the actions of the next calls, and whether any of them wrote a file. */
+/** What followed one failed call: the actions of the next calls, and whether any of them wrote a file without failing. A write that came back as an error stays in `next` and does not set `editFollowed`. */
 export interface RecoveryCalls {
     next: CanonicalAction[];
     editFollowed: boolean;
@@ -17,5 +17,6 @@ export interface RecoveryCalls {
 /**
  * What followed the call at `at` of a transcript's calls in the order they ran: null for a call that did not fail. The calls that followed are the later ones of the same prompt and the same run (a
  * subagent's call is not what the main run did next), up to 5. The scan ends at the first later call of that run that belongs to another prompt.
+ * `failedEditsCount` is the rule of the wire formats before 6, where any later edit counted whether or not its own result was an error; the ingest checks a batch of those formats with it, so a client already released is not refused for a failed edit.
  */
-export declare const recoveryCallsOf: (calls: readonly Followed[], at: number) => RecoveryCalls | null;
+export declare const recoveryCallsOf: (calls: readonly Followed[], at: number, failedEditsCount?: boolean) => RecoveryCalls | null;

package/dist/sessions/recovery-calls.js

@@ -7,19 +7,25 @@ const actionOf = ({ steps }) => steps?.[0]?.action ?? 'other';
 /**
  * What followed the call at `at` of a transcript's calls in the order they ran: null for a call that did not fail. The calls that followed are the later ones of the same prompt and the same run (a
  * subagent's call is not what the main run did next), up to 5. The scan ends at the first later call of that run that belongs to another prompt.
+ * `failedEditsCount` is the rule of the wire formats before 6, where any later edit counted whether or not its own result was an error; the ingest checks a batch of those formats with it, so a client already released is not refused for a failed edit.
  */
-export const recoveryCallsOf = (calls, at) => {
+export const recoveryCallsOf = (calls, at, failedEditsCount = false) => {
     const failed = calls[at];
     if (failed === undefined || failed.status !== 'error')
         return null;
     const next = [];
+    let editFollowed = false;
     for (let index = at + 1; index < calls.length && next.length < RECOVERY_CALLS; index += 1) {
         const call = calls[index];
         if (call === undefined || call.side !== failed.side)
             continue;
         if (call.prompt !== failed.prompt)
             break;
-        next.push(actionOf(call));
+        const action = actionOf(call);
+        next.push(action);
+        // An edit whose own result is an error wrote nothing, so it is not an edit that followed. A call with no recorded result is not known to have failed, and still counts.
+        if (WRITES.has(action) && (failedEditsCount || call.status !== 'error'))
+            editFollowed = true;
     }
-    return { next, editFollowed: next.some((action) => WRITES.has(action)) };
+    return { next, editFollowed };
 };

package/dist/sessions/redact.d.ts

@@ -9,9 +9,9 @@ export declare const placeholders: (text: string) => number;
 /** The names this machine's person goes by in a transcript: the account's and the home folder's. A name under three characters would mask ordinary words, so it is left to the path rules. */
 export declare const localNames: (home?: string, account?: () => string) => string[];
 /** 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 declare const redactTranscript: (body: string, domains?: readonly string[], names?: readonly string[]) => {
+export declare const redactTranscript: (body: string, domains?: readonly string[], names?: readonly string[], injectedKey?: string) => {
     text: string;
     masked: number;
 };
 /** The version of the rules above, stated to the pool with every raw part; a change to any rule of `redactTranscript` raises it. */
-export declare const REDACTION_VERSION = "1";
+export declare const REDACTION_VERSION = "3";

package/dist/sessions/redact.js

@@ -1,5 +1,7 @@
+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.
@@ -70,6 +72,95 @@ const PROMPT = /(?:<user>|\b[A-Za-z0-9._-]+)@[A-Za-z0-9-]+(?=:[~/.])/g;
 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;
+// 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) => {
+    // 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) => {
+        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)}`;
+    };
+    // `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);
+        if (whole !== undefined)
+            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(redactText(run.join('\n')));
+            run = [];
+            out.push(rewrite(line, parsed, top));
+        }
+        if (run.length > 0)
+            out.push(redactText(run.join('\n')));
+        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. */
@@ -93,21 +184,32 @@ const nameRule = (names) => {
     return forms.length === 0 ? undefined : new RegExp(`(?<![A-Za-z0-9<])(?:${forms.map(escapeRegExp).join('|')})(?![A-Za-z0-9>])`, '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')) => {
     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 known = makeRedactor(domains);
+    const redactText = (text) => {
+        // 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));
+        return (named === undefined ? masked : masked.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>')
+            .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 redacted = redactDecoded(body, redactText, injectedRule(injectedKey, repeated));
     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 = '3';

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