agent-nuvira 3.3.7 → 3.3.9

package/dist/learning/session-store.js

@@ -0,0 +1,424 @@
+/**
+ * WS5 (#27) — Phase 4b/4c: the PERSISTENT SESSION STORE (the L2 layer).
+ *
+ * WHY THIS EXISTS. The resume ledger (`step-checkpoint.ts`) makes a re-run cheap
+ * by replaying unchanged MODEL CALLS, and the task checkpoints
+ * (`agents/checkpoint-store.ts`) skip COMPLETED pipeline tasks. Both are keyed by
+ * what a run FINISHED. Neither survives the one failure a long-running agent
+ * actually hits: the PROCESS dies mid-turn (a closed laptop, a killed terminal,
+ * a quota-killed provider). At that instant the conversation lived only in
+ * memory, and the next process starts cold — it re-derives the whole context and
+ * re-pays for the steps that were already done.
+ *
+ * WHAT IT STORES, AND WHAT IT REFUSES TO STORE. At every step boundary the loop
+ * hands over its live `ToolMessage[]` thread plus a small accumulator (steps,
+ * successful tools, mutated paths). The store keeps a bounded, REDACTED copy on
+ * disk. It is a transcript — nothing more. It does NOT record a completion
+ * state, an outcome, or any verdict: completion is still derived from the
+ * filesystem and the run's own facts (see the Part 1/Part 2 lesson). Re-importing
+ * the transcript gives the next process the CONVERSATION, not a claim that the
+ * work is done.
+ *
+ * WHY THE HEAD IS REPLACED ON REHYDRATION. The first messages of a loop thread
+ * are the system prompt (tool contract) and the `[Project context]` block. Those
+ * are reconstructible, and they DRIFT between runs (the file tree, the git
+ * digest). Persisting them would both age and bloat the record. So the store
+ * counts the leading head messages at save time (`headLength`) and the caller
+ * re-injects a FRESH head over the stored conversation tail on resume: the
+ * contract is current, the history is intact.
+ *
+ * WHY A COMPLETED SESSION IS NOT RESUMABLE. If a turn ran to a clean end, its
+ * transcript is history — re-feeding a finished conversation would have the model
+ * continue a conversation that is over, and risk narrating a stale "done". So
+ * `finish()` marks a snapshot closed, and the resumable lookup skips closed
+ * snapshots. The transcript is still kept (bounded) for a human to read; it is
+ * simply not replayed.
+ *
+ * WHY NOTHING HAPPENS WITHOUT A REQUEST. Opening the store is the ONLY thing that
+ * reads or writes the session directory. An ordinary run never touches it, pays
+ * no filesystem cost, and cannot inherit another run's conversation.
+ *
+ * Everything here is best-effort: a corrupt record is a MISS, never a crash, and
+ * a failed write reports (or stays silent) without breaking the turn that asked.
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { checkpointIdFor, goalsLookSame } from '../agents/checkpoint-store.js';
+import { envBuff, resolveNuviraHome } from '../config/paths.js';
+import { redact } from '../enterprise/secrets.js';
+/** The environment key a deployment uses to turn session persistence OFF. */
+export const SESSION_ENABLE_ENV = 'NUVIRA_SESSION_STORE';
+/** Words a reader treats as OFF (same vocabulary the process-env page uses). */
+const OFF_WORDS = new Set(['0', 'false', 'off', 'no']);
+/**
+ * Is session persistence on? DEFAULT ON — like checkpointing, a fresh install
+ * gets continuity and an operator can turn it off. `0`/`false`/`off`/`no` turn
+ * it off; unset (or any other value) leaves it ON.
+ */
+export function sessionStoreEnabled(env = process.env) {
+    const raw = env[SESSION_ENABLE_ENV];
+    if (typeof raw !== 'string')
+        return true;
+    return !OFF_WORDS.has(raw.trim().toLowerCase());
+}
+/**
+ * Resolve whether session persistence is on, with the repo's precedence: an
+ * explicit FLAG wins, then the environment, then config, then the default (ON).
+ * One place decides, so the CLI, the loop and the dashboard cannot disagree.
+ */
+export function resolveSessionStore(input = {}) {
+    if (input.flag !== undefined)
+        return input.flag;
+    const viaEnv = envBuff('SESSION_STORE');
+    if (typeof viaEnv === 'string')
+        return !OFF_WORDS.has(viaEnv.trim().toLowerCase());
+    return input.configManager?.getAll().memory?.sessionStore !== false;
+}
+/** Bound on stored conversation messages — the most recent N are kept. */
+export const MAX_SESSION_MESSAGES = 48;
+/** Bound on a single stored message's content (the rest is clipped). */
+export const MAX_MESSAGE_CHARS = 8000;
+// ─── Storage ────────────────────────────────────────────────────────────────
+function sessionsDir() {
+    const base = envBuff('MEMORY_DIR') || join(resolveNuviraHome(), 'memory');
+    return join(base, 'sessions');
+}
+function snapshotPath(id) {
+    return join(sessionsDir(), `${id}.json`);
+}
+/** Read a snapshot, best-effort. A corrupt record is a miss, never a crash. */
+export function loadSessionSnapshot(id) {
+    try {
+        const path = snapshotPath(id);
+        if (!existsSync(path))
+            return null;
+        const parsed = JSON.parse(readFileSync(path, 'utf-8'));
+        if (!parsed || typeof parsed !== 'object')
+            return null;
+        if (typeof parsed.id !== 'string' || !Array.isArray(parsed.messages))
+            return null;
+        if (typeof parsed.goal !== 'string' || typeof parsed.cwd !== 'string')
+            return null;
+        return {
+            id: parsed.id,
+            goal: parsed.goal,
+            cwd: parsed.cwd,
+            savedAt: typeof parsed.savedAt === 'number' ? parsed.savedAt : 0,
+            revision: typeof parsed.revision === 'number' ? parsed.revision : 0,
+            open: parsed.open !== false,
+            headLength: typeof parsed.headLength === 'number' ? parsed.headLength : 0,
+            messages: parsed.messages.filter(isToolMessage),
+            accumulators: normalizeAccumulators(parsed.accumulators),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function isToolMessage(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const m = value;
+    return ((m.role === 'system' || m.role === 'user' || m.role === 'assistant' || m.role === 'tool') &&
+        typeof m.content === 'string');
+}
+function normalizeAccumulators(value) {
+    const a = (value ?? {});
+    return {
+        steps: typeof a.steps === 'number' ? a.steps : 0,
+        successfulTools: Array.isArray(a.successfulTools) ? a.successfulTools.filter((t) => typeof t === 'string') : [],
+        mutatedPaths: Array.isArray(a.mutatedPaths) ? a.mutatedPaths.filter((t) => typeof t === 'string') : [],
+        ...(Array.isArray(a.erroredTools)
+            ? { erroredTools: a.erroredTools.filter((t) => typeof t === 'string') }
+            : {}),
+    };
+}
+/** Write a snapshot, best-effort. Returns whether it reached the disk. */
+function writeSnapshot(snapshot) {
+    try {
+        mkdirSync(sessionsDir(), { recursive: true });
+        writeFileSync(snapshotPath(snapshot.id), JSON.stringify(snapshot, null, 2), 'utf-8');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// ─── Bounds ─────────────────────────────────────────────────────────────────
+/**
+ * Bound and redact a thread for storage.
+ *
+ * The TAIL is kept (the last `MAX_SESSION_MESSAGES` messages): the most recent
+ * tool results and the current question are what a resuming model needs, while
+ * the opening context is reconstructible. Every content string is clipped to
+ * `MAX_MESSAGE_CHARS` and run through the shared `redact` — a transcript that
+ * leaks a key is not worth the continuity it buys.
+ *
+ * Tool-call arguments and `providerMeta` are preserved verbatim only when they
+ * survive JSON (they are structured data the provider may need) and are never
+ * trusted to be secret-free, so they are redacted through a JSON round-trip.
+ */
+function boundMessages(messages) {
+    const headLength = countHead(messages);
+    const sliced = messages.length > MAX_SESSION_MESSAGES ? messages.slice(-MAX_SESSION_MESSAGES) : messages.slice();
+    const bounded = sliced.map((message) => boundMessage(message));
+    // If the slice dropped the head, the stored head is gone too (the caller's
+    // `headLength` then refers to a head that is not in the record).
+    return { messages: bounded, headLength: Math.min(headLength, bounded.length) };
+}
+/** Leading system messages, plus a directly-following `[Project context]` block. */
+function countHead(messages) {
+    let head = 0;
+    while (head < messages.length && messages[head].role === 'system')
+        head += 1;
+    if (head < messages.length && messages[head].role === 'user' && messages[head].content.startsWith('[Project context]')) {
+        head += 1;
+    }
+    return head;
+}
+function boundMessage(message) {
+    const out = {
+        role: message.role,
+        content: clip(message.content),
+    };
+    if (message.toolCallId)
+        out.toolCallId = message.toolCallId;
+    if (Array.isArray(message.toolCalls) && message.toolCalls.length > 0) {
+        out.toolCalls = message.toolCalls.map((call) => {
+            const copy = { ...call };
+            if (typeof copy.arguments === 'string')
+                copy.arguments = clip(copy.arguments);
+            return copy;
+        });
+    }
+    return out;
+}
+function clip(text) {
+    if (typeof text !== 'string')
+        return '';
+    const redacted = redact(text);
+    return redacted.length > MAX_MESSAGE_CHARS ? `${redacted.slice(0, MAX_MESSAGE_CHARS)}…[clipped]` : redacted;
+}
+const STORE_STATES = new WeakMap();
+/**
+ * Open (or start) the session for this ask, in this directory.
+ *
+ * An explicit `id` is honoured exactly. With none, the deterministic
+ * `checkpointIdFor(goal, cwd)` is used — the SAME key the resume ledger uses —
+ * so a reworded re-ask resolves to the same session through
+ * {@link resolveSessionIdFor} / {@link findResumableSessionFor}.
+ */
+/** Whether this process has already opportunistically bounded the store. */
+let PRUNED_THIS_PROCESS = false;
+/** Keep the store from growing without bound — run at most once per process. */
+function pruneOnce() {
+    if (PRUNED_THIS_PROCESS)
+        return;
+    PRUNED_THIS_PROCESS = true;
+    try {
+        const entries = listSessionSnapshots();
+        if (entries.length > 100)
+            pruneSessions({ maxCount: 100 });
+    }
+    catch {
+        // Best-effort — a prune failure must never break an open.
+    }
+}
+export function openSession(input) {
+    pruneOnce();
+    const id = input.id?.trim() || checkpointIdFor(input.goal, input.cwd);
+    const prior = loadSessionSnapshot(id);
+    const state = {
+        id,
+        goal: input.goal,
+        cwd: input.cwd,
+        revision: prior?.revision ?? 0,
+        saved: false,
+        lastMessages: prior?.messages ?? [],
+        lastAccumulators: prior?.accumulators ?? { steps: 0, successfulTools: [], mutatedPaths: [] },
+    };
+    const persist = (open) => {
+        const { messages, headLength } = boundMessages(state.lastMessages);
+        const snapshot = {
+            id: state.id,
+            goal: state.goal,
+            cwd: state.cwd,
+            savedAt: Date.now(),
+            revision: state.revision + 1,
+            open,
+            headLength,
+            messages,
+            accumulators: state.lastAccumulators,
+        };
+        state.revision += 1;
+        state.saved = writeSnapshot(snapshot);
+    };
+    const store = {
+        id,
+        save(thread, accumulators) {
+            state.lastMessages = thread.slice();
+            state.lastAccumulators = normalizeAccumulators(accumulators);
+            persist(true);
+        },
+        finish(thread, accumulators) {
+            if (thread)
+                state.lastMessages = thread.slice();
+            if (accumulators)
+                state.lastAccumulators = normalizeAccumulators(accumulators);
+            persist(false);
+        },
+        lastSaved() {
+            return state.saved;
+        },
+    };
+    STORE_STATES.set(store, state);
+    return store;
+}
+/**
+ * The session id for this ask, in this directory, possibly WORDED DIFFERENTLY.
+ *
+ * Same contract as `resolveRecordIdFor` in the resume ledger: the exact id if a
+ * snapshot exists, else the newest OPEN snapshot in this directory whose goal
+ * `goalsLookSame`. A snapshot for a different ask is never returned — the caller
+ * would otherwise rehydrate a conversation it never had.
+ */
+export function resolveSessionIdFor(goal, cwd, options = {}) {
+    const exact = checkpointIdFor(goal, cwd);
+    const onlyOpen = options.onlyOpen ?? true;
+    const exactSnap = loadSessionSnapshot(exact);
+    if (exactSnap && (!onlyOpen || exactSnap.open))
+        return exact;
+    const wanted = normalizeDir(cwd);
+    let best = null;
+    try {
+        for (const file of readdirSync(sessionsDir())) {
+            if (!file.endsWith('.json'))
+                continue;
+            const id = file.slice(0, -'.json'.length);
+            if (id === exact)
+                continue;
+            const snap = loadSessionSnapshot(id);
+            if (!snap)
+                continue;
+            if (onlyOpen && !snap.open)
+                continue;
+            if (normalizeDir(snap.cwd) !== wanted)
+                continue;
+            if (!goalsLookSame(snap.goal, goal))
+                continue;
+            if (!best || snap.savedAt > best.savedAt)
+                best = { id, savedAt: snap.savedAt };
+        }
+    }
+    catch {
+        return exact;
+    }
+    return best?.id ?? exact;
+}
+/**
+ * The resumable snapshot for this ask, or null when there is nothing to resume.
+ *
+ * Only OPEN snapshots qualify (see the module docstring): a transcript from a
+ * turn that ended cleanly is history, and re-feeding it would have the model
+ * continue a finished conversation.
+ */
+export function findResumableSessionFor(goal, cwd) {
+    const id = resolveSessionIdFor(goal, cwd, { onlyOpen: true });
+    const snap = loadSessionSnapshot(id);
+    if (!snap || !snap.open || snap.messages.length === 0)
+        return null;
+    return snap;
+}
+/**
+ * Rebuild a loop thread from a stored snapshot and a FRESH head.
+ *
+ * The fresh head (system prompt, current project context) replaces the stored
+ * head; the stored conversation tail — the goal and everything done after it —
+ * is preserved. The result is what the next process loops over: it already knows
+ * what the dead process did, so those steps are neither re-run nor re-paid.
+ */
+export function rehydrateThread(head, snapshot) {
+    const start = Math.min(snapshot.headLength, snapshot.messages.length);
+    return [...head, ...snapshot.messages.slice(start)];
+}
+/** A bounded, human-facing line describing a resumable snapshot. */
+export function formatSessionResume(snapshot) {
+    const steps = snapshot.accumulators.steps;
+    const tools = snapshot.accumulators.successfulTools.length;
+    const paths = snapshot.accumulators.mutatedPaths.length;
+    return (`↩️  session for this ask is still OPEN — ${steps} step(s), ${tools} successful tool call(s)` +
+        (paths > 0 ? `, ${paths} path(s) changed` : '') +
+        ' — the conversation is restored (this is HISTORY, not a status: verify artifacts on disk)');
+}
+/**
+ * List every stored session snapshot, newest first. Best-effort: a corrupt or
+ * unreadable record is skipped, never thrown.
+ */
+export function listSessionSnapshots() {
+    try {
+        const out = [];
+        for (const file of readdirSync(sessionsDir())) {
+            if (!file.endsWith('.json'))
+                continue;
+            const snap = loadSessionSnapshot(file.slice(0, -'.json'.length));
+            if (snap)
+                out.push(snap);
+        }
+        return out.sort((a, b) => b.savedAt - a.savedAt);
+    }
+    catch {
+        return [];
+    }
+}
+/** Remove one snapshot. Returns whether a file was removed. */
+export function clearSession(id) {
+    try {
+        const path = snapshotPath(id);
+        if (!existsSync(path))
+            return false;
+        rmSync(path, { force: true });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Bound the session directory: drop snapshots older than `maxAgeMs` and keep at
+ * most `maxCount` (newest first). Returns how many files were removed.
+ *
+ * Best-effort and never throws — a prune that fails leaves the records (a disk
+ * full of old transcripts is a smaller problem than a broken turn).
+ */
+export function pruneSessions(options = {}) {
+    const now = options.now ?? Date.now();
+    const maxAgeMs = options.maxAgeMs ?? 30 * 24 * 60 * 60 * 1000;
+    const maxCount = options.maxCount ?? 50;
+    let removed = 0;
+    try {
+        const entries = [];
+        for (const file of readdirSync(sessionsDir())) {
+            if (!file.endsWith('.json'))
+                continue;
+            const id = file.slice(0, -'.json'.length);
+            const snap = loadSessionSnapshot(id);
+            entries.push({ id, savedAt: snap?.savedAt ?? 0 });
+        }
+        entries.sort((a, b) => b.savedAt - a.savedAt);
+        for (let i = 0; i < entries.length; i += 1) {
+            const { id, savedAt } = entries[i];
+            const tooOld = maxAgeMs > 0 && now - savedAt > maxAgeMs;
+            const overCount = i >= maxCount;
+            if ((tooOld || overCount) && clearSession(id))
+                removed += 1;
+        }
+    }
+    catch {
+        return removed;
+    }
+    return removed;
+}
+function normalizeDir(dir) {
+    return (dir || '').replace(/[\\/]+$/, '');
+}
+//# sourceMappingURL=session-store.js.map

package/dist/learning/session-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-store.js","sourceRoot":"","sources":["../../src/learning/session-store.ts"],"names":[],"mappings":"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"}

package/dist/learning/step-checkpoint.d.ts

@@ -68,6 +68,21 @@ export declare function resolveResumeRequest(input: {
  * not a change of input — while a different VALUE anywhere hashes differently.
  */
 export declare function stepDigest(thread: readonly unknown[], schemas: readonly unknown[]): string;
+/**
+ * B3 — the record id for this ask, in this directory, possibly WORDED DIFFERENTLY.
+ *
+ * `checkpointIdFor` hashes the literal goal, so "fix the hotkey" and "hotkey
+ * still not working" are two unrelated ids and the second ask cannot find the
+ * first's record — the reworded-ask miss the pipeline arm already solves with
+ * `findRelatedCheckpointFor` / `goalsLookSame`. The loop's replay ledger had no
+ * equivalent, so a reworded `--resume` replayed nothing.
+ *
+ * Order of preference: the EXACT id (a record we know is this ask), then the
+ * newest record in this directory whose goal `goalsLookSame` (the same ask,
+ * worded differently). A record for a DIFFERENT ask is never returned — the
+ * caller would otherwise replay answers to questions it never asked.
+ */
+export declare function resolveRecordIdFor(goal: string, cwd: string): string;
 /** ─── The ledger ───────────────────────────────────────────────────────────── */
 /**
  * The ledger a loop threads its steps through.
@@ -99,6 +114,12 @@ export declare function openResume(input: {
     goal: string;
     cwd: string;
     resume: ResumeRequest;
+    /**
+     * B4 — reuse recorded steps (default true). `false` = checkpoint-only: write a
+     * resume point without replaying anything, which is what makes default-on
+     * checkpointing safe. A caller that only wants to LEAVE a record passes false.
+     */
+    replay?: boolean;
 }): OpenResume;
 /** What a resumed run replayed, what it paid for, and whether the record survived. */
 export interface ResumeOutcome {
@@ -107,6 +128,13 @@ export interface ResumeOutcome {
     replayed: number;
     /** Model calls the RESUMED run still made (0 = every step came from the record). */
     modelCalls: number;
+    /**
+     * Phase 5 — the CONTINUATION SAVING, stated as a first-class number: each
+     * replayed step is one model call the resumed run did NOT pay for. Equal to
+     * `replayed` by construction, but named so a surface can report the saving
+     * without knowing that identity.
+     */
+    callsAvoided: number;
     /** False when the record could not be written (the run itself still happened). */
     saved: boolean;
     /** The operator-facing line: the counts, and why nothing replayed when it didn't. */

package/dist/learning/step-checkpoint.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"step-checkpoint.d.ts","sourceRoot":"","sources":["../../src/learning/step-checkpoint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAQH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAElE,kEAAkE;AAClE,eAAO,MAAM,iBAAiB,kBAAkB,CAAC;AAOjD,mFAAmF;AAEnF;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,GAAG,aAAa,GAAG,SAAS,CAgBpG;AAED,mFAAmF;AAEnF;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,SAAS,OAAO,EAAE,EAAE,OAAO,EAAE,SAAS,OAAO,EAAE,GAAG,MAAM,CAE1F;AAmED,mFAAmF;AAEnF;;;;;;;GAOG;AACH,MAAM,WAAW,UAAU;IACzB,kFAAkF;IAClF,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CAAC;IAC7D,uEAAuE;IACvE,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,gBAAgB,GAAG,IAAI,CAAC;IACtE,gEAAgE;IAChE,UAAU,IAAI,MAAM,CAAC;CACtB;AA2BD,iFAAiF;AACjF,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,UAAU,CAAC;CACpB;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,aAAa,CAAA;CAAE,GAAG,UAAU,CAgDlG;AAMD,sFAAsF;AACtF,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,qEAAqE;IACrE,QAAQ,EAAE,MAAM,CAAC;IACjB,oFAAoF;IACpF,UAAU,EAAE,MAAM,CAAC;IACnB,kFAAkF;IAClF,KAAK,EAAE,OAAO,CAAC;IACf,qFAAqF;IACrF,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,aAAa,CAuCnG"}
+{"version":3,"file":"step-checkpoint.d.ts","sourceRoot":"","sources":["../../src/learning/step-checkpoint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAQH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAElE,kEAAkE;AAClE,eAAO,MAAM,iBAAiB,kBAAkB,CAAC;AASjD,mFAAmF;AAEnF;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,GAAG,aAAa,GAAG,SAAS,CAgBpG;AAED,mFAAmF;AAEnF;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,SAAS,OAAO,EAAE,EAAE,OAAO,EAAE,SAAS,OAAO,EAAE,GAAG,MAAM,CAE1F;AAgFD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAoBpE;AAED,mFAAmF;AAEnF;;;;;;;GAOG;AACH,MAAM,WAAW,UAAU;IACzB,kFAAkF;IAClF,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CAAC;IAC7D,uEAAuE;IACvE,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,gBAAgB,GAAG,IAAI,CAAC;IACtE,gEAAgE;IAChE,UAAU,IAAI,MAAM,CAAC;CACtB;AAmCD,iFAAiF;AACjF,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,UAAU,CAAC;CACpB;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,aAAa,CAAC;IACtB;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,GAAG,UAAU,CAqEb;AAMD,sFAAsF;AACtF,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,qEAAqE;IACrE,QAAQ,EAAE,MAAM,CAAC;IACjB,oFAAoF;IACpF,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB,kFAAkF;IAClF,KAAK,EAAE,OAAO,CAAC;IACf,qFAAqF;IACrF,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,aAAa,CA4CnG"}

package/dist/learning/step-checkpoint.js

@@ -34,9 +34,9 @@
  * anything — including on runs that then replayed everything.
  */
 import { createHash } from 'node:crypto';
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { checkpointIdFor } from '../agents/checkpoint-store.js';
+import { checkpointIdFor, goalsLookSame } from '../agents/checkpoint-store.js';
 import { envBuff, resolveNuviraHome } from '../config/paths.js';
 /** The environment key a deployment asks for a resume through. */
 export const RESUME_ENABLE_ENV = 'NUVIRA_RESUME';
@@ -44,6 +44,8 @@ export const RESUME_ENABLE_ENV = 'NUVIRA_RESUME';
 const CHANGED_REASON = 'its input changed';
 const EMPTY_REASON = 'the recorded step was an empty provider response';
 const MISSING_REASON = 'not in the record';
+/** B4 — a checkpoint-only run does not replay, so every step reports this. */
+const NOT_REQUESTED_REASON = 'replay was not requested (checkpoint only)';
 /**
  * Resolve a resume request from a caller's option, with the environment as the
  * fallback.
@@ -129,6 +131,64 @@ function writeRecord(file) {
         return false;
     }
 }
+/** Read a record's metadata without trusting its steps (null when missing/corrupt). */
+function readRecordMeta(id) {
+    try {
+        const path = recordPath(id);
+        if (!existsSync(path))
+            return null;
+        const parsed = JSON.parse(readFileSync(path, 'utf-8'));
+        if (!parsed || typeof parsed.goal !== 'string' || typeof parsed.cwd !== 'string')
+            return null;
+        return { goal: parsed.goal, cwd: parsed.cwd, savedAt: typeof parsed.savedAt === 'number' ? parsed.savedAt : 0 };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * B3 — the record id for this ask, in this directory, possibly WORDED DIFFERENTLY.
+ *
+ * `checkpointIdFor` hashes the literal goal, so "fix the hotkey" and "hotkey
+ * still not working" are two unrelated ids and the second ask cannot find the
+ * first's record — the reworded-ask miss the pipeline arm already solves with
+ * `findRelatedCheckpointFor` / `goalsLookSame`. The loop's replay ledger had no
+ * equivalent, so a reworded `--resume` replayed nothing.
+ *
+ * Order of preference: the EXACT id (a record we know is this ask), then the
+ * newest record in this directory whose goal `goalsLookSame` (the same ask,
+ * worded differently). A record for a DIFFERENT ask is never returned — the
+ * caller would otherwise replay answers to questions it never asked.
+ */
+export function resolveRecordIdFor(goal, cwd) {
+    const exact = checkpointIdFor(goal, cwd);
+    if (existsSync(recordPath(exact)))
+        return exact;
+    const wanted = cwd.replace(/[\\/]+$/, '');
+    let best = null;
+    try {
+        for (const file of readdirSync(stepsDir())) {
+            if (!file.endsWith('.json'))
+                continue;
+            const id = file.slice(0, -'.json'.length);
+            if (id === exact)
+                continue;
+            const meta = readRecordMeta(id);
+            if (!meta)
+                continue;
+            if (meta.cwd.replace(/[\\/]+$/, '') !== wanted)
+                continue;
+            if (!goalsLookSame(meta.goal, goal))
+                continue;
+            if (!best || meta.savedAt > best.savedAt)
+                best = { id, savedAt: meta.savedAt };
+        }
+    }
+    catch {
+        return exact;
+    }
+    return best?.id ?? exact;
+}
 /** The ledger instances this module created, so `closeResume` can read its state. */
 const STATES = new WeakMap();
 /** A response with no text and no tool call is a provider failure, not an answer. */
@@ -143,7 +203,13 @@ function isEmptyResponse(response) {
  * Open the record for this ask, reading it once (a record is not re-read per step).
  */
 export function openResume(input) {
-    const id = input.resume.id?.trim() || checkpointIdFor(input.goal, input.cwd);
+    const replayEnabled = input.replay !== false;
+    // B3 — an explicit id is honoured exactly; otherwise resolve the record for
+    // this ask HERE, matching a reworded version of the same ask too. A
+    // checkpoint-only run does NOT go looking for a reworded record: it is
+    // writing forward, not resuming, so it uses this ask's own id.
+    const id = input.resume.id?.trim() ||
+        (replayEnabled ? resolveRecordIdFor(input.goal, input.cwd) : checkpointIdFor(input.goal, input.cwd));
     const prior = readRecord(id);
     const state = {
         id,
@@ -153,11 +219,20 @@ export function openResume(input) {
         replayed: 0,
         modelCalls: 0,
         misses: new Map(),
-        staged: new Map(),
+        replayEnabled,
+        // Checkpoint-only: seed the staged map with what the record already holds so
+        // `closeResume` MERGES this run's steps into it instead of replacing a
+        // usable record with only the latest run's work.
+        staged: replayEnabled ? new Map() : new Map(prior.map((entry) => [entry.key, entry])),
     };
     const byKey = new Map(prior.map((entry) => [entry.key, entry]));
     const ledger = {
         replay(key, digest) {
+            if (!state.replayEnabled) {
+                // Checkpoint-only: nothing is reused this run (see `replayEnabled`).
+                countMiss(state, NOT_REQUESTED_REASON);
+                return null;
+            }
             const entry = byKey.get(key);
             if (!entry) {
                 countMiss(state, MISSING_REASON);
@@ -182,6 +257,11 @@ export function openResume(input) {
             state.staged.set(key, { key, digest, response });
         },
         openNotice() {
+            if (!state.replayEnabled) {
+                return state.loaded > 0
+                    ? `💾 checkpointing this run — the existing record (${state.loaded} step(s)) will be updated`
+                    : '💾 checkpointing this run — a resume point will be written for this ask';
+            }
             return state.loaded > 0
                 ? `↩️  resumed: ${state.loaded} recorded step(s) loaded — a step replays only when its whole input is unchanged`
                 : '↩️ no record for this ask in this directory yet — this run will write one';
@@ -205,7 +285,7 @@ export function closeResume(resume, input) {
     const state = STATES.get(resume.ledger);
     if (!state) {
         const notice = '↩️  resume probe: replayed 0, made 0 model call(s)';
-        return { id: resume.id, replayed: 0, modelCalls: 0, saved: false, notice };
+        return { id: resume.id, replayed: 0, modelCalls: 0, callsAvoided: 0, saved: false, notice };
     }
     const steps = [...state.staged.values()];
     let saved;
@@ -223,8 +303,11 @@ export function closeResume(resume, input) {
             steps,
         });
     }
+    const avoided = state.replayed > 0
+        ? ` — ${state.replayed} model call(s) REUSED from the record (not re-paid)`
+        : '';
     const lines = [
-        `↩️  resume probe: replayed ${state.replayed}, made ${state.modelCalls} model call(s)`,
+        `↩️  resume probe: replayed ${state.replayed}, made ${state.modelCalls} model call(s)${avoided}`,
     ];
     if (state.replayed === 0 && state.misses.size > 0) {
         const reasons = [...state.misses.entries()].map(([reason, count]) => `${reason} (${count})`);
@@ -237,6 +320,7 @@ export function closeResume(resume, input) {
         id: state.id,
         replayed: state.replayed,
         modelCalls: state.modelCalls,
+        callsAvoided: state.replayed,
         saved,
         notice: lines.join('\n'),
     };