@nathapp/nax-agent 0.3.0 → 0.84.0

package/dist/native/session/repository-instructions.js

@@ -0,0 +1,155 @@
+/** Bounded, repository-local instruction discovery. Each instance belongs to one session. */
+import { createHash } from "node:crypto";
+import { realpath } from "node:fs/promises";
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import { readPrefix } from "#src/internal/bounded-io";
+import { credentialReadRefusal } from "#src/tools/credential-read-deny";
+import { matchesDenyPaths } from "#src/tools/deny-paths";
+import { DEFAULT_INSTRUCTION_FILE_NAME, instructionFileNameFor } from "./instruction-file-name.js";
+import { MIN_INSTRUCTION_NOTICE_BYTES, renderRepositoryInstructions } from "./instruction-render.js";
+export const _repositoryInstructionDeps = { realpath, readPrefix };
+const MAX_FILE_BYTES = 32_768;
+const MAX_TOTAL_BYTES = 131_072;
+const MAX_FILES = 64;
+const MAX_DEPTH = 8;
+function contained(root, path) {
+    const rel = relative(root, path);
+    return rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+}
+function safeMarkdown(root, path) {
+    const rel = relative(root, path);
+    return (contained(root, path) &&
+        /\.md$/i.test(path) &&
+        !rel.split(sep).some((part) => part.startsWith(".") || /(?:credential|secret|trust[-_]?store)/i.test(part)));
+}
+export class RepositoryInstructions {
+    workdir;
+    protectedPaths;
+    denyPaths;
+    loaded = new Map();
+    visited = new Set();
+    scopes = new Set();
+    bytes = 0;
+    root;
+    limited = false;
+    pending = Promise.resolve();
+    renderMaxBytes = Number.POSITIVE_INFINITY;
+    fileNames;
+    constructor(workdir, protectedPaths, denyPaths, fileName) {
+        this.workdir = workdir;
+        this.protectedPaths = protectedPaths;
+        this.denyPaths = denyPaths;
+        const selected = instructionFileNameFor(fileName);
+        this.fileNames =
+            selected === DEFAULT_INSTRUCTION_FILE_NAME
+                ? ["AGENTS.override.md", DEFAULT_INSTRUCTION_FILE_NAME, "CLAUDE.md"]
+                : [selected];
+    }
+    get directories() {
+        return [...this.scopes];
+    }
+    get sources() {
+        return [...this.loaded.values()].map(({ path, scope, hash }) => ({
+            path,
+            scope,
+            hash,
+        }));
+    }
+    /** Bytes conservatively upper-bound token count; host instructions consume the same system reserve. */
+    setContextBudget(contextWindow, hostPrompt) {
+        const reserve = Math.floor((contextWindow ?? 16_384) / 4);
+        const hostBytes = Buffer.byteLength(hostPrompt ?? "", "utf8") + 2;
+        // The caller owns its host prompt. When that already consumes the reserve,
+        // retain only the explicit omission notice rather than silently losing guides.
+        this.renderMaxBytes = Math.max(MIN_INSTRUCTION_NOTICE_BYTES, reserve - hostBytes);
+    }
+    render() {
+        return renderRepositoryInstructions([...this.loaded.values()], this.limited, this.renderMaxBytes);
+    }
+    discover(directory, canRead = () => true, protectedPaths = this.protectedPaths) {
+        const next = this.pending.then(() => this.discoverScope(directory, canRead, protectedPaths));
+        this.pending = next.catch(() => { });
+        return next;
+    }
+    async discoverScope(directory, canRead, protectedPaths) {
+        this.root ??= await _repositoryInstructionDeps.realpath(this.workdir).catch(() => resolve(this.workdir));
+        const lexical = resolve(this.workdir, directory);
+        if (!contained(resolve(this.workdir), lexical) && !contained(this.root, lexical))
+            return;
+        const target = await _repositoryInstructionDeps.realpath(lexical).catch(() => lexical);
+        if (!contained(this.root, target))
+            return;
+        const rel = relative(this.root, target);
+        if (rel.split(sep).some((part) => part.startsWith(".") && part !== ""))
+            return;
+        const parts = rel === "" ? [] : rel.split(sep);
+        if (parts.length > 32) {
+            this.limited = true;
+            return;
+        }
+        this.scopes.add(rel || ".");
+        let dir = this.root;
+        for (const part of ["", ...parts]) {
+            if (part !== "")
+                dir = resolve(dir, part);
+            for (const name of this.fileNames) {
+                const found = await this.load(resolve(dir, name), relative(this.root, dir) || ".", 0, canRead, protectedPaths);
+                if (found)
+                    break;
+            }
+        }
+    }
+    async load(path, scope, depth, canRead, protectedPaths) {
+        if (this.root === undefined)
+            return false;
+        if (depth > MAX_DEPTH || this.visited.size >= MAX_FILES || this.bytes >= MAX_TOTAL_BYTES) {
+            this.limited = true;
+            return false;
+        }
+        if (!safeMarkdown(this.root, path) ||
+            credentialReadRefusal(protectedPaths, path) !== undefined ||
+            credentialReadRefusal(this.protectedPaths, path) !== undefined ||
+            !canRead(path) ||
+            matchesDenyPaths(relative(this.root, path).split(sep).join("/"), this.denyPaths))
+            return false;
+        const canonical = await _repositoryInstructionDeps.realpath(path).catch(() => undefined);
+        if (canonical === undefined ||
+            !safeMarkdown(this.root, canonical) ||
+            credentialReadRefusal(protectedPaths, canonical) !== undefined ||
+            credentialReadRefusal(this.protectedPaths, canonical) !== undefined ||
+            !canRead(canonical) ||
+            matchesDenyPaths(relative(this.root, canonical).split(sep).join("/"), this.denyPaths))
+            return false;
+        if (this.visited.has(canonical))
+            return true;
+        this.visited.add(canonical);
+        const text = await _repositoryInstructionDeps
+            .readPrefix(canonical, Math.min(MAX_FILE_BYTES, MAX_TOTAL_BYTES - this.bytes))
+            .catch(() => undefined);
+        if (text === undefined)
+            return false;
+        const bytes = Buffer.byteLength(text, "utf8");
+        if (bytes > MAX_FILE_BYTES || this.bytes + bytes > MAX_TOTAL_BYTES) {
+            this.limited = true;
+            return true;
+        }
+        this.bytes += bytes;
+        if (text.trim() === "")
+            return true;
+        const hash = createHash("sha256").update(text).digest("hex");
+        this.loaded.set(canonical, {
+            path: relative(this.root, canonical),
+            scope,
+            hash,
+            text,
+        });
+        // Claude-style @path imports: local markdown only, never URLs or home paths.
+        for (const match of text.matchAll(/(?:^|\s)@([^\s`<>]+\.md)(?=\s|$)/gm)) {
+            const imported = match[1];
+            if (imported === undefined || isAbsolute(imported) || imported.startsWith("~") || imported.includes(":"))
+                continue;
+            await this.load(resolve(dirname(canonical), imported), scope, depth + 1, canRead, protectedPaths);
+        }
+        return true;
+    }
+}

package/dist/native/session/session.d.ts

@@ -10,6 +10,7 @@ import { type SpinBreaker } from "#src/infra/spin-breaker/index";
 import type { AgentStreamEvent } from "#src/session/agent-stream-events";
 import type { OpenSessionOpts, SessionHandle } from "#src/session/session-types";
 import type { ResolvedCompaction } from "./compaction.ts";
+import type { RepositoryInstructions } from "./repository-instructions.ts";
 import type { TranscriptStore } from "./transcript-types.ts";
 import type { TurnRetryConfig } from "./turn-retry.ts";
 /** The runtime hooks handed to openSession. */
@@ -96,6 +97,12 @@ export interface NativeSessionState {
      * maps above: set on open, cleared on close.
      */
     readonly transcriptOwners: Map<string, string>;
+    /**
+     * Sessions that keep history written by another model (S5-3), set at open from
+     * `OpenSessionOpts.carryHistoryAcrossModels`. Same lifecycle as the maps above:
+     * set on open, cleared on close.
+     */
+    readonly carryHistoryAcrossModels: Set<string>;
     /** Session name -> resolved compaction settings. Same lifecycle as the maps above. */
     readonly compaction: Map<string, ResolvedCompaction>;
     /**
@@ -130,6 +137,7 @@ export interface NativeSessionState {
      * lifecycle as the maps above: set on open, cleared on close.
      */
     readonly systemPrompts: Map<string, string>;
+    readonly repositoryInstructions: Map<string, RepositoryInstructions>;
 }
 export declare function createNativeSessionState(): NativeSessionState;
 export interface SessionAnchor {

package/dist/native/session/session.js

@@ -10,6 +10,9 @@ import { NaxError } from "#src/infra/index";
 import { createSpinBreaker } from "#src/infra/spin-breaker/index";
 import { NATIVE_AGENT } from "../models.js";
 import { nativeSessionId } from "../session-affinity.js";
+import { instructionFileNameFor } from "./instruction-file-name.js";
+import { openRepositoryInstructions } from "./instruction-session.js";
+import { instructionTranscriptStore } from "./instruction-transcript.js";
 import { createFileTranscriptStore } from "./transcript-store.js";
 export function createNativeSessionState() {
     return {
@@ -20,11 +23,13 @@ export function createNativeSessionState() {
         streamHooks: new Map(),
         failed: new Set(),
         transcriptOwners: new Map(),
+        carryHistoryAcrossModels: new Set(),
         compaction: new Map(),
         transportRetry: new Map(),
         spinBreakers: new Map(),
         lastUsage: new Map(),
         systemPrompts: new Map(),
+        repositoryInstructions: new Map(),
     };
 }
 /**
@@ -86,23 +91,39 @@ function recordSystemPrompt(state, name, systemPrompt) {
 }
 /** The request field for the session's system prompt: `{ system }`, or `{}` when it has none. */
 export function systemFieldFor(state, sessionName) {
-    const system = state.systemPrompts.get(sessionName);
+    const base = state.systemPrompts.get(sessionName);
+    const repository = state.repositoryInstructions.get(sessionName)?.render();
+    const system = [base, repository].filter(Boolean).join("\n\n") || undefined;
     return system === undefined ? {} : { system };
 }
 export async function openNativeSession(state, name, opts) {
+    instructionFileNameFor(opts.instructionFileName);
     const store = openTranscriptStore(name, opts);
     if (opts.transcriptDir)
         state.transcriptDirs.set(name, opts.transcriptDir);
     else
         state.transcriptDirs.delete(name);
-    state.transcripts.set(name, { store, retainOnClose: opts.retainOnClose === true });
+    state.transcripts.set(name, {
+        store,
+        retainOnClose: opts.retainOnClose === true,
+    });
     state.timeouts.set(name, opts.timeoutSeconds);
     state.scratchpadRoots.set(name, opts.workdir);
     if (opts.transcriptOwner !== undefined)
         state.transcriptOwners.set(name, opts.transcriptOwner);
     else
         state.transcriptOwners.delete(name);
+    if (opts.carryHistoryAcrossModels === true)
+        state.carryHistoryAcrossModels.add(name);
+    else
+        state.carryHistoryAcrossModels.delete(name);
     recordSystemPrompt(state, name, opts.systemPrompt);
+    const instructions = await openRepositoryInstructions(name, opts, store);
+    state.repositoryInstructions.set(name, instructions);
+    state.transcripts.set(name, {
+        store: instructionTranscriptStore(store, instructions),
+        retainOnClose: opts.retainOnClose === true,
+    });
     // `resume` is SessionManager's "this name already has a descriptor in this
     // process" signal, and it had no consumer on this transport (nax#1877) — a
     // native session resumed whatever transcript happened to be on disk. Honouring
@@ -129,7 +150,10 @@ export async function openNativeSession(state, name, opts) {
         // native has no reconnect, so its logical and physical identity genuinely
         // coincide. `nativeSessionId` is a pure hash of the name and deliberately
         // not memoised, so this is exactly the id `sendTurn` later puts on the wire.
-        protocolIds: { recordId: nativeSessionId(name), sessionId: nativeSessionId(name) },
+        protocolIds: {
+            recordId: nativeSessionId(name),
+            sessionId: nativeSessionId(name),
+        },
         ...(opts.modelDef !== undefined ? { modelDef: opts.modelDef } : {}),
         ...(opts.modelTier !== undefined ? { modelTier: opts.modelTier } : {}),
     };
@@ -150,6 +174,7 @@ export function clearNativeSessionState(state, sessionName) {
     state.timeouts.delete(sessionName);
     state.scratchpadRoots.delete(sessionName);
     state.transcriptOwners.delete(sessionName);
+    state.carryHistoryAcrossModels.delete(sessionName);
     state.streamHooks.delete(sessionName);
     state.failed.delete(sessionName);
     state.compaction.delete(sessionName);
@@ -157,6 +182,7 @@ export function clearNativeSessionState(state, sessionName) {
     state.spinBreakers.delete(sessionName);
     state.lastUsage.delete(sessionName);
     state.systemPrompts.delete(sessionName);
+    state.repositoryInstructions.delete(sessionName);
 }
 /**
  * Kept on failure, deleted on success. Every Phase B op is lifetime "fresh", so

package/dist/native/session/transcript-identity.d.ts

@@ -14,6 +14,8 @@ import type { TranscriptDoc } from "./transcript-types.ts";
 export interface TranscriptIdentity {
     readonly owner?: string;
     readonly model?: string;
+    /** Keep a document written by another model (S5-3); `model` still names the current one. */
+    readonly carryAcrossModels?: boolean;
 }
 /**
  * The model half of `TranscriptIdentity`: the native `provider/model` id with

package/dist/native/session/transcript-identity.js

@@ -35,7 +35,7 @@ function isForeignTranscript(doc, identity, sessionName) {
         });
         return true;
     }
-    if (model !== undefined && doc.model !== undefined && doc.model !== model) {
+    if (identity.carryAcrossModels !== true && model !== undefined && doc.model !== undefined && doc.model !== model) {
         getLogger().debug("native-session", "Ignoring a transcript written by another model", {
             sessionName,
             storedModel: doc.model,

package/dist/native/session/transcript-store.js

@@ -6,9 +6,10 @@
  * nax stored nothing; SessionDescriptor still has no message field, and gains
  * none. See ADR-028 sections 2 and 3.
  */
-import { mkdir, readdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { mkdir, readdir, readFile, rename, rm, stat } from "node:fs/promises";
 import { join } from "node:path";
 import { getLogger, NaxError } from "#src/infra/index";
+import { writeFileAtomic } from "#src/internal/atomic-write";
 import { historyFromTranscript, transcriptDocFor } from "./transcript-identity.js";
 export { transcriptModelIdentity } from "./transcript-identity.js";
 export function transcriptPath(dir, sessionName) {
@@ -60,7 +61,8 @@ export async function readTranscriptDoc(dir, sessionName) {
 }
 async function writeTranscriptDoc(dir, sessionName, doc) {
     await mkdir(dir, { recursive: true });
-    await writeFile(transcriptPath(dir, sessionName), JSON.stringify(doc, null, 2), "utf8");
+    // Atomic (#3): a torn transcript is unrecoverable — every later load throws TRANSCRIPT_CORRUPT.
+    await writeFileAtomic(transcriptPath(dir, sessionName), JSON.stringify(doc, null, 2));
 }
 /**
  * The file store: `<dir>/<name>.transcript.json`, written as given (the loop's

package/dist/native/session/transcript-types.d.ts

@@ -39,6 +39,9 @@ export interface TranscriptDoc {
      * (S3 spec 5.5 write order: markTurn(running), turn, markTurn(ended)).
      */
     readonly turn?: TurnMarker;
+    /** Native instruction discovery audit, independent of compacted message history. */
+    readonly instructionSources?: readonly import("./repository-instructions.ts").InstructionSource[];
+    readonly instructionDirectories?: readonly string[];
 }
 export interface TranscriptStore {
     /** `null` when the session has no document yet. */

package/dist/native/session/turn-complete-step.js

@@ -65,8 +65,10 @@ export async function completeWithRecovery(args) {
         // caller's array, the one the turn-end transcript save persists — is returned untouched,
         // so the transcript stays the true record. `boundary` is this step's
         // overflow fact (`compacted`): true only on the post-compaction retry,
-        // where a prefix rewrite is free. A model change never reaches this step:
-        // the transcript store refuses another model's history (spec 8.3).
+        // where a prefix rewrite is free. A model change CAN reach this step under
+        // carryHistoryAcrossModels (S5-3): the transcript store no longer refuses
+        // another model's history, but the per-model compaction anchor is dropped
+        // on that mismatch, so applyHistoryPatch honours an undefined anchor.
         const transformed = await loopEvents.dispatch("transform_context", {
             messages: msgs,
             tools,

package/dist/native/session/turn-event-emitter.d.ts

@@ -45,4 +45,8 @@ export interface TurnEventEmitter {
     flushUnanswered(): void;
 }
 export declare function usageEvent(round: number, usage: TokenUsage, costUsd: number): TurnEvent;
+/** The masking and cap live `tool_call.input` gets; exported for ACP replay (S5-1). */
+export declare function displayToolInput(input: unknown): unknown;
+/** The masking and cap live `tool_result.preview` gets; exported for ACP replay (S5-1). */
+export declare function toolResultPreview(content: string): string;
 export declare function createTurnEventEmitter(sink: TurnEventSink | undefined): TurnEventEmitter;

package/dist/native/session/turn-event-emitter.js

@@ -43,7 +43,8 @@ export function usageEvent(round, usage, costUsd) {
         costUsd,
     };
 }
-function cappedInput(input) {
+/** The masking and cap live `tool_call.input` gets; exported for ACP replay (S5-1). */
+export function displayToolInput(input) {
     const redacted = redactSecrets(capStrings(input, REDACTION_SCAN_BYTES));
     let json;
     try {
@@ -56,7 +57,8 @@ function cappedInput(input) {
         return redacted;
     return { truncated: true, preview: cutToByteCap(json, TOOL_CALL_INPUT_BYTES) };
 }
-function previewOf(content) {
+/** The masking and cap live `tool_result.preview` gets; exported for ACP replay (S5-1). */
+export function toolResultPreview(content) {
     return cutToByteCap(redactSecrets(cutToByteCap(content, REDACTION_SCAN_BYTES)), TOOL_RESULT_PREVIEW_BYTES);
 }
 const NOOP_EMITTER = {
@@ -103,7 +105,7 @@ export function createTurnEventEmitter(sink) {
             // Capped BEFORE the count moves: a throwing input (a hostile getter or
             // proxy) must not leave an outstanding call the matching toolResult then
             // answers with no preceding tool_call.
-            const input = cappedInput(recordedInput ?? call.input);
+            const input = displayToolInput(recordedInput ?? call.input);
             outstanding.set(call.id, (outstanding.get(call.id) ?? 0) + 1);
             emit({ type: "tool_call", callId: call.id, name: call.name, input });
         },
@@ -119,7 +121,7 @@ export function createTurnEventEmitter(sink) {
                 type: "tool_result",
                 callId: result.toolCallId,
                 isError: result.isError === true,
-                preview: previewOf(result.content),
+                preview: toolResultPreview(result.content),
             });
         },
         flushUnanswered() {

package/dist/native/session/turn-loop-round-trip.js

@@ -33,6 +33,7 @@
  */
 import { inputClassTokens } from "#src/cost/core/index";
 import { getSafeLogger } from "#src/infra/index";
+import { parseModelSpec } from "../models.js";
 import { estimateContextTokens, shouldCompact, } from "./compaction.js";
 import { usageBeat } from "./turn-accumulator.js";
 import { runProactiveCompaction } from "./turn-compaction-step.js";
@@ -96,6 +97,21 @@ async function maybeCompact(state, params) {
     }
     return { summarizeFailed: step.summarizeFailed };
 }
+/**
+ * The catalog provider and model that answer for this handle: the
+ * "provider/model[effort]" string, effort stripped, split on the first "/".
+ * The same pair parseNativeModel hands client.model(); undefined, never a
+ * throw, when there is no usable model.
+ */
+function originOf(raw) {
+    if (raw === undefined)
+        return undefined;
+    const spec = parseModelSpec(raw).model;
+    const slash = spec.indexOf("/");
+    if (slash <= 0 || slash === spec.length - 1)
+        return undefined;
+    return { provider: spec.slice(0, slash), model: spec.slice(slash + 1) };
+}
 /**
  * One model call and its bookkeeping: `completeWithRecovery`, the usage/anchor
  * updates, the activity beats, `after_response`, and pushing the settled
@@ -140,7 +156,6 @@ async function runModelRoundTrip(state, params, summarizeFailed) {
     }
     state.roundTrips += 1;
     params.usage.add(res.usage, res.costUsd, res.rates);
-    state.output = res.text;
     // nax#1852: the anchor is the whole prompt the provider charged for, not
     // just its uncached portion. Under prompt caching (which the round trip
     // above always requests) the cached prefix arrives in the cache fields,
@@ -184,15 +199,19 @@ async function runModelRoundTrip(state, params, summarizeFailed) {
     // what it records: answering the ORIGINAL calls while recording patched
     // ones would desync the transcript from what actually executed.
     const assistantText = afterResponse.text ?? res.text;
+    // The recorded answer IS the patched one: transcript and TurnResult.output must agree (turn-event.ts).
+    state.output = assistantText;
     const assistantToolCalls = afterResponse.toolCalls ?? res.toolCalls;
     const assistantThinking = afterResponse.thinking ?? res.thinking;
     // Thinking blocks are appended, not merely representable: Anthropic needs
     // the exact block back to continue a thinking conversation (ADR-028 s8).
+    const origin = originOf(handle.modelDef?.model);
     state.messages.push({
         role: "assistant",
         content: assistantText,
         ...(assistantToolCalls !== undefined ? { toolCalls: assistantToolCalls } : {}),
         ...(assistantThinking !== undefined ? { thinking: assistantThinking } : {}),
+        ...(origin !== undefined ? { origin } : {}),
     });
     if (assistantToolCalls === undefined || assistantToolCalls.length === 0) {
         state.completedNormally = true;

package/dist/native/session/turn-loop.js

@@ -65,6 +65,7 @@ export async function runNativeTurn(handle, prompt, opts, deps) {
     const transcriptIdentity = {
         owner: deps.sessionState.transcriptOwners.get(handle.id),
         model: transcriptModelIdentity(handle.modelDef?.model),
+        ...(deps.sessionState.carryHistoryAcrossModels.has(handle.id) ? { carryAcrossModels: true } : {}),
     };
     let messages = [
         ...historyFromTranscript(await store.load(handle.id), transcriptIdentity, handle.id),

package/dist/native/session/turn-types.d.ts

@@ -6,11 +6,10 @@
  * algorithm and the file under the 600-line hard limit (see
  * .nax/rules/project-conventions.md).
  *
- * The failure-usage ledger (`failureUsageByError` WeakMap +
- * `recordNativeTurnFailureUsage` / `readNativeTurnFailureUsage`) also lives
- * here: it is module-level state with a process-lifetime scope, and the
- * loop's catch block only ever calls the write side through this file's
- * public API. Adapter.ts reads through `readNativeTurnFailureUsage` to
+ * The failure-usage ledger's native API (`recordNativeTurnFailureUsage` /
+ * `readNativeTurnFailureUsage`) also lives here; the WeakMap itself lives in
+ * `#src/session/turn-spend`, shared with ACP backends (#2367). The loop's
+ * catch block only ever calls the write side through this file's public API. Adapter.ts reads through `readNativeTurnFailureUsage` to
  * attribute round-trip spend to the error a failed turn threw (nax#1840).
  */
 import type { ConversationMessage, ThinkingBlock, ToolCall } from "@nathapp/nax-ai";

package/dist/native/session/turn-types.js

@@ -6,21 +6,21 @@
  * algorithm and the file under the 600-line hard limit (see
  * .nax/rules/project-conventions.md).
  *
- * The failure-usage ledger (`failureUsageByError` WeakMap +
- * `recordNativeTurnFailureUsage` / `readNativeTurnFailureUsage`) also lives
- * here: it is module-level state with a process-lifetime scope, and the
- * loop's catch block only ever calls the write side through this file's
- * public API. Adapter.ts reads through `readNativeTurnFailureUsage` to
+ * The failure-usage ledger's native API (`recordNativeTurnFailureUsage` /
+ * `readNativeTurnFailureUsage`) also lives here; the WeakMap itself lives in
+ * `#src/session/turn-spend`, shared with ACP backends (#2367). The loop's
+ * catch block only ever calls the write side through this file's public API. Adapter.ts reads through `readNativeTurnFailureUsage` to
  * attribute round-trip spend to the error a failed turn threw (nax#1840).
  */
-const failureUsageByError = new WeakMap();
+import { attachTurnSpend, readTurnSpend } from "#src/session/turn-spend";
 /** Writes the spend a failed turn accumulated, keyed on the error's own identity. */
 export function recordNativeTurnFailureUsage(err, usage) {
-    failureUsageByError.set(err, usage);
+    attachTurnSpend(err, usage);
 }
 /** Reads back what the catch block recorded, if anything did. */
 export function readNativeTurnFailureUsage(err) {
-    return typeof err === "object" && err !== null ? failureUsageByError.get(err) : undefined;
+    const spend = readTurnSpend(err);
+    return spend === undefined ? undefined : { tokenUsage: spend.tokenUsage, costUsd: spend.costUsd };
 }
 /**
  * Translate a `TokenUsage`'s cache fields into the spread that the

package/dist/native/session-adapter.js

@@ -16,6 +16,7 @@ import { _clientDeps, getNativeClient } from "./client.js";
 import { createSessionCredentialStore } from "./credentials/session-source.js";
 import { toAdapterFailure } from "./errors.js";
 import { buildRateCard, NATIVE_AGENT, parseNativeModel, resolveContextWindow, toThinkingLevel } from "./models.js";
+import { createInstructionInteraction } from "./session/instruction-interaction.js";
 import { closeNativeSession, createNativeSessionState, markNativeTurnOutcome, openNativeSession, systemFieldFor, } from "./session/session.js";
 import { buildNativeStreamEvent } from "./session/turn-events.js";
 import { runNativeTurn } from "./session/turn-loop.js";
@@ -140,6 +141,10 @@ export class NativeSessionAdapter {
         const thinking = toThinkingLevel(effort);
         const client = await this.client();
         const resolved = await client.model(provider, model);
+        const contextWindow = resolveContextWindow(handle.modelDef?.contextWindow, resolved.contextWindow);
+        this.state.repositoryInstructions
+            .get(handle.id)
+            ?.setContextBudget(contextWindow, this.state.systemPrompts.get(handle.id));
         const catalog = client.pricing(resolved);
         const { rates, source: pricingSource } = buildRateCard(catalog, handle.modelDef?.pricing);
         const storedTimeoutSeconds = this.state.timeouts.get(handle.id);
@@ -155,7 +160,7 @@ export class NativeSessionAdapter {
         const sessionId = nativeSessionId(handle.id);
         // S3-4: the session's system prompt (facade `instructions`), or `{}`.
         // Resolved here so the `complete` closure spreads it without a branch.
-        const systemField = systemFieldFor(this.state, handle.id);
+        const instructionInteraction = createInstructionInteraction(this.state.repositoryInstructions.get(handle.id), opts.interactionHandler);
         // One budget for the whole turn, not one per round-trip. Created here
         // because this is where `timeoutSeconds` is known; consulted by the loop.
         const deadline = createTurnDeadline(timeoutSeconds);
@@ -204,6 +209,7 @@ export class NativeSessionAdapter {
         if (opts.signal !== undefined)
             turnSignals.unshift(opts.signal);
         const turnSignal = AbortSignal.any(turnSignals);
+        const turnOpts = { ...opts, interactionHandler: instructionInteraction.handler };
         let result;
         try {
             // US-002: clear the deadline timer at turn settlement, no matter how
@@ -211,10 +217,10 @@ export class NativeSessionAdapter {
             // `AbortSignal.any` above holds a reference to `deadlineController.signal`,
             // so a settled turn must drop its timer to avoid keeping it armed past
             // the turn boundary.
-            result = await runNativeTurn(handle, prompt, opts, {
+            result = await runNativeTurn(handle, prompt, turnOpts, {
                 sessionState: this.state,
                 deadline,
-                contextWindow: resolveContextWindow(handle.modelDef?.contextWindow, resolved.contextWindow),
+                contextWindow,
                 ...(this.state.compaction.get(handle.id) !== undefined
                     ? { compaction: this.state.compaction.get(handle.id) }
                     : {}),
@@ -267,7 +273,12 @@ export class NativeSessionAdapter {
                         });
                         const summaryUsage = res.usage;
                         const { costUsd, resolvedRates } = priceCall(summaryUsage, rates);
-                        return { text: res.text, usage: summaryUsage, costUsd, rates: resolvedRates };
+                        return {
+                            text: res.text,
+                            usage: summaryUsage,
+                            costUsd,
+                            rates: resolvedRates,
+                        };
                     }
                     finally {
                         if (timer !== undefined)
@@ -293,11 +304,12 @@ export class NativeSessionAdapter {
                     // thinking LEVEL rather than a boolean, so normalize at this boundary.
                     const requestThinking = requestOptions?.thinking === false ? undefined : thinking;
                     try {
+                        instructionInteraction.acknowledge();
                         const res = await streamComplete(client, resolved, {
                             messages,
                             ...(tools.length > 0 ? { tools } : {}),
                             sessionId,
-                            ...systemField,
+                            ...systemFieldFor(this.state, handle.id),
                             signal,
                             ...(requestThinking !== undefined ? { thinking: requestThinking } : {}),
                             ...(requestOptions?.temperature !== undefined ? { temperature: requestOptions.temperature } : {}),
@@ -408,6 +420,9 @@ export class NativeSessionAdapter {
      * both carry, so clear by name rather than synthesising a handle.
      */
     async closePhysicalSession(handle, _workdir, _options) {
-        return closeNativeSession(this.state, { id: handle, agentName: NATIVE_AGENT });
+        return closeNativeSession(this.state, {
+            id: handle,
+            agentName: NATIVE_AGENT,
+        });
     }
 }

package/dist/permissions/approvals-store.d.ts

@@ -85,7 +85,7 @@ export declare function readApprovalsFileDetailed(path: string): Promise<Approva
  */
 export declare function readApprovalsFile(path: string): Promise<ApprovalsFile>;
 export declare function readApprovals(path: string): Promise<readonly ApprovalEntry[]>;
-/** Serialize the whole store. Callers hold the path lock. */
+/** Serialize the whole store, atomically (#16): a torn store would lose every remembered approval. Callers hold the path lock. */
 export declare function writeApprovalsFile(path: string, file: ApprovalsFile): Promise<void>;
 /**
  * Lock the read-modify-write. Worktree-isolated parallel stories share one
@@ -96,6 +96,8 @@ export declare function writeApprovalsFile(path: string, file: ApprovalsFile): P
  *
  * The taint marker is PRESERVED: a "remember" tapped during a forge-capable run
  * lands in a store that stays untrusted.
+ *
+ * An unparseable store is refused, never replaced (the removal path does the same).
  */
 export declare function appendApproval(path: string, entry: ApprovalEntry): Promise<void>;
 /**