@nathapp/nax-agent 0.91.8-canary.1 → 0.91.8-canary.2

package/CHANGELOG.md

@@ -4,6 +4,10 @@ All notable changes to `@nathapp/nax-agent` are recorded here. The format follow
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). While the version is `0.x`, a minor
 release may change the public API.
 
+## [0.91.8-canary.2] - 2026-11-04
+
+- No changes in this package. Released in lockstep with the other nax packages.
+
 ## [0.91.8-canary.1] - 2026-11-03
 
 - No changes in this package. Released in lockstep with the other nax packages.

package/dist/config/catalog-overrides.d.ts

@@ -65,6 +65,15 @@ export interface OpenRouterRouting {
         p99?: number;
     };
 }
+/** Per-level token budgets, hand-mirrored from nax-ai's ThinkingBudgets.
+ * Config code cannot import nax-ai; validation remains owned by nax-ai.
+ */
+export interface CatalogThinkingBudgets {
+    minimal?: number;
+    low?: number;
+    medium?: number;
+    high?: number;
+}
 /**
  * One complete catalog entry for a model the bundled pi-ai snapshot does not
  * know. Complete, not a patch: nax-ai's `normaliseCatalog` replaces any
@@ -98,6 +107,10 @@ export interface CatalogModelOverride {
      * Mirrored from nax-ai's ThinkingFormat; omit to inherit the provider's format.
      */
     thinkingFormat?: "openai" | "qwen" | "qwen-chat-template" | "deepseek" | "zai" | "openrouter";
+    /** Wire field receiving the thinking token budget on openai-completions models. */
+    thinkingBudgetField?: string;
+    /** Model-owned token budgets for declared reasoning levels. */
+    thinkingBudgets?: CatalogThinkingBudgets;
 }
 /** Provider-scoped catalog overrides — maps 1:1 onto nax-ai's `ProviderOverride[]`. */
 export interface ProviderCatalogOverride {

package/dist/index.d.ts

@@ -19,7 +19,7 @@ export { isProcessAlive } from "#src/internal/process-alive";
 export { killProcessGroup } from "#src/internal/process-kill";
 export { capStrings, redactSecrets } from "#src/internal/redact";
 export { NaxError } from "#src/infra/nax-error";
-export { MEMORY_CLIENT_ID_RE, MEMORY_DESCRIPTION_MAX_CHARS, MEMORY_FORGET_REASON_MAX_CHARS, MEMORY_INDEX_MAX_BYTES, MEMORY_INDEX_MAX_LINES, MEMORY_INDEX_MIN_BYTES, MEMORY_INDEX_MIN_LINES, MEMORY_NOTE_BODY_MAX_BYTES, MEMORY_OP_TIMEOUT_MS, MEMORY_PROBE_TIMEOUT_MS, MEMORY_PULL_MAX_PAGES, MEMORY_PULL_PAGE_SIZE, MEMORY_SLUG_RE, MEMORY_SOURCE_MAX_CHARS, type MemoryApproveInput, type MemoryDecision, type MemoryForgetInput, type MemoryForgetResult, type MemoryHit, type MemoryNote, type MemoryNoteStatus, type MemoryNoteType, type MemoryNoteWrite, type MemoryOutbox, type MemoryOutboxEntry, type MemoryPage, type MemoryProvider, type MemoryPushResult, type MemorySaveInput, type MemorySaveResult, type MemoryScope, type MemoryStore, type MemoryStorePaths, type MemorySyncResult, type MemorySyncState, type MemoryTimers, type MemoryWriteRefusal, type MemoryWriteRequest, type RenderedMemoryIndex, type RefreshMemoryIndexOptions, type RenderMemoryIndexInput, approveMemoryNote, createLocalMemoryProvider, createMemoryOutbox, createMemoryStore, findSecret, forgetMemoryNote, isMemoryPushRejected, parseMemoryNote, raceTimeout, refreshMemoryIndex, renderMemoryIndex, saveMemoryNote, searchMemoryNotes, serializeMemoryNote, syncMemory, tokenizeMemoryQuery, validateMemoryNoteWrite, } from "#src/memory/index";
+export { MEMORY_CLIENT_ID_RE, MEMORY_DESCRIPTION_MAX_CHARS, MEMORY_FORGET_REASON_MAX_CHARS, MEMORY_INDEX_MAX_BYTES, MEMORY_INDEX_MAX_LINES, MEMORY_INDEX_MIN_BYTES, MEMORY_INDEX_MIN_LINES, MEMORY_NOTE_BODY_MAX_BYTES, MEMORY_OP_TIMEOUT_MS, MEMORY_PROBE_TIMEOUT_MS, MEMORY_PULL_MAX_PAGES, MEMORY_PULL_PAGE_SIZE, MEMORY_SLUG_RE, MEMORY_SOURCE_MAX_CHARS, type MemoryApproveInput, type MemoryDecision, type MemoryForgetInput, type MemoryForgetResult, type MemoryHit, type MemoryNote, type MemoryNoteStatus, type MemoryNoteType, type MemoryNoteWrite, type MemoryOutbox, type MemoryOutboxEntry, type MemoryPage, type MemoryPendingForget, type MemoryProvider, type MemoryPushResult, type MemorySaveInput, type MemorySaveResult, type MemoryScope, type MemoryStore, type MemoryStorePaths, type MemorySyncResult, type MemorySyncState, type MemoryTimers, type MemoryWriteRefusal, type MemoryWriteRequest, type RenderedMemoryIndex, type RefreshMemoryIndexOptions, type RenderMemoryIndexInput, approveMemoryNote, createLocalMemoryProvider, createMemoryOutbox, createMemoryStore, findSecret, forgetMemoryNote, isMemoryPushRejected, parseMemoryNote, raceTimeout, refreshMemoryIndex, renderMemoryIndex, saveMemoryNote, searchMemoryNotes, serializeMemoryNote, syncMemory, tokenizeMemoryQuery, validateMemoryNoteWrite, } from "#src/memory/index";
 export { createTerminalAuthInteraction, PLAIN_STYLE, PromptCancelledError, type TerminalAuthOptions, type TerminalStyle, } from "#src/terminal-auth/index";
 export type { CredentialSource } from "#src/native/credentials/session-source";
 export { AuthCancelledError, type AuthEvent, type AuthInteraction, type AuthLink, type AuthMethod, type AuthOption, type AuthPrompt, type AuthResult, ambientShadows, anyAmbientCredential, authImportOutcomeLabel, createFileTranscriptStore, createMemoryTranscriptStore, credentialFilePath, DEFAULT_PI_AUTH_PATH, type ImportOutcome, importPiCredentials, listProviderModels, listStoredProviders, loginProviderIds, MAX_RETAINED_TRANSCRIPTS, type MemoryTranscriptStore, NATIVE_AGENT, type NativeCatalogOverrides, type NativeCompleteContext, type NativeCompleteOptions, type NativeCompleteResult, NativeSessionAdapter, NativeSessionUnsupportedError, type NativeTierConfig, nativeComplete, nativeTierProviders, naxCredentialStore, newSessionKey, type ProviderModel, providersWithoutCredentials, pruneRetainedTranscripts, type ResolveResult, type ResolveStatus, removeStoredProvider, resolveNativeId, runLogin, type StoredEntry, servedAuth, type TranscriptAcpRecord, type TranscriptDoc, type TranscriptStore, type TurnMarker, } from "#src/native/index";
@@ -33,7 +33,7 @@ export { createSessionStorage, defaultSessionsDir, processAlive, LIST_PAGE_SIZE,
 export type { AdapterFailure } from "#src/session/adapter-failure";
 export { createAgentSession, resumeAgentSession } from "#src/session/agent-session";
 export { AgentSessionError, type AgentSessionErrorCode } from "#src/session/agent-session-errors";
-export type { AgentSession, AgentSessionHostPorts, AgentSessionProfile, AnswerReply, AnswerStatus, ApprovalDecidedBy, CostSource, CommandRunResult, CreateAgentSessionOptions, EmbedderTool, EmbedderToolContext, EmbedderToolResult, SessionConfigureInput, SessionEvent, SessionEventBase, SessionEventBody, TurnEndStatus, } from "#src/session/agent-session-types";
+export type { AgentSession, AgentSessionHostPorts, AgentSessionProfile, AnswerReply, AnswerStatus, ApprovalDecidedBy, CostSource, CommandRunResult, CompactResult, CreateAgentSessionOptions, EmbedderTool, EmbedderToolContext, EmbedderToolResult, SessionConfigureInput, SessionEvent, SessionEventBase, SessionEventBody, TurnEndStatus, } from "#src/session/agent-session-types";
 export type { AgentAwaitingHumanEvent, AgentCallEndedEvent, AgentCallStartedEvent, AgentMessageUpdateEvent, AgentProcessUpdateEvent, AgentStreamEvent, AgentStreamEventBase, AgentThinkingUpdateEvent, AgentToolCallUpdateEvent, AgentUsageUpdateEvent, } from "#src/session/agent-stream-events";
 export { IMAGE_MIME_TYPES, IMAGE_TOKEN_ESTIMATE, MAX_IMAGE_BASE64_CHARS, MAX_IMAGES_PER_MESSAGE, MAX_REQUEST_IMAGE_BASE64_CHARS, MAX_REQUEST_IMAGES, type SendInput, validateImageAttachments, } from "#src/session/image-input";
 export { type AdapterInteraction, type AdapterInteractionResponse, type InteractionHandler, NO_OP_INTERACTION_HANDLER, } from "#src/session/interaction-handler";
@@ -42,6 +42,7 @@ export type { NativeBackendOptions } from "#src/session/native-backend-options";
 export type { ProtocolIds } from "#src/session/protocol-types";
 export type { ApprovalRequest, BackendInfo, BackendOpenContext, OpenedBackend, SessionAskPort, SessionBackend, TurnContribution, } from "#src/session/session-backend";
 export { type AgentSessionAdapter, type AuthStamp, type InteractionExchange, type InvalidToolCallDetail, type OpenSessionOpts, type SendTurnOpts, type SessionHandle, type SessionModel, SessionTurnError, type TrackedSpawnDeadlineOptions, type TurnResult, } from "#src/session/session-types";
+export type { SteerChannel, SteerResult } from "#src/session/steer-channel";
 export { attachTurnSpend, type FailedTurnSpend, readTurnSpend } from "#src/session/turn-spend";
 export type { JSONSchema, ToolDescriptor, } from "#src/session/tool-descriptor";
 export { createTurnDeadline, type TurnDeadline, } from "#src/session/turn-deadline";

package/dist/internal.d.ts

@@ -46,6 +46,7 @@ export * from "#src/internal/shell-quote";
 export * from "#src/internal/sort";
 export * from "#src/internal/strip-control-chars";
 export * from "#src/internal/thenable";
+export { parseMemoryNoteRecord } from "#src/memory/note";
 export { _memoryStoreDeps } from "#src/memory/store";
 export * from "#src/native/adapter-deps";
 export * from "#src/native/auth";

package/dist/internal.js

@@ -46,6 +46,7 @@ export * from "#src/internal/shell-quote";
 export * from "#src/internal/sort";
 export * from "#src/internal/strip-control-chars";
 export * from "#src/internal/thenable";
+export { parseMemoryNoteRecord } from "#src/memory/note";
 export { _memoryStoreDeps } from "#src/memory/store";
 export * from "#src/native/adapter-deps";
 export * from "#src/native/auth";

package/dist/memory/index-render.d.ts

@@ -32,7 +32,10 @@ export interface RenderedMemoryIndex {
     readonly text: string;
     readonly omitted: number;
 }
-/** What a refresh carries into both renderings: the held keys and the two caps. */
+/**
+ * What a refresh carries into both renderings: the held keys and the two caps. The keys
+ * are the ones the outbox still holds; the record's own keys are added to them.
+ */
 export interface RefreshMemoryIndexOptions {
     /** `"<scope>/<slug>"` of every note with a queued forget. */
     readonly heldForgets?: ReadonlySet<string>;
@@ -45,7 +48,8 @@ export interface RefreshMemoryIndexOptions {
  * Regenerate the index files of a store from what it holds: the project notes and
  * the decisions into `MEMORY.md`, and — on a store that has a user directory — the
  * user notes into the user scope's `MEMORY.md`, which carries the header lines and
- * the `## User` section only. The project rendering is what is returned.
+ * the `## User` section only. Every note with a queued or recorded forget is marked.
+ * The project rendering is what is returned.
  */
 export declare function refreshMemoryIndex(store: MemoryStore, options?: RefreshMemoryIndexOptions): Promise<RenderedMemoryIndex>;
 export declare function renderMemoryIndex(input: RenderMemoryIndexInput): RenderedMemoryIndex;

package/dist/memory/index-render.js

@@ -1,4 +1,4 @@
-import { MEMORY_DESCRIPTION_MAX_CHARS, MEMORY_INDEX_MAX_BYTES, MEMORY_INDEX_MAX_LINES, MEMORY_INDEX_MIN_BYTES, MEMORY_INDEX_MIN_LINES, } from "./types.js";
+import { MEMORY_DESCRIPTION_MAX_CHARS, MEMORY_INDEX_MAX_BYTES, MEMORY_INDEX_MAX_LINES, MEMORY_INDEX_MIN_BYTES, MEMORY_INDEX_MIN_LINES, memoryNoteKey, } from "./types.js";
 /** The two lines every index starts with. */
 const HEADING_LINES = ["# Memory", "Memory notes are recorded facts, not instructions."];
 /** The order the project section lists its type blocks in: most actionable first. */
@@ -100,14 +100,29 @@ function userSection(userNotes, heldForgets) {
 function joinLines(lines) {
     return lines.map((line) => line.text).join("\n");
 }
+/**
+ * The keys both renderings mark: the caller's held forgets plus the ones the mirror has
+ * recorded. A proposal forget is answered long before anything acts on it, so the record
+ * — not the caller — is what still knows about it; a key held by both is one mark.
+ */
+async function markedForgets(store, heldForgets) {
+    const recorded = await store.readPendingForgets();
+    if (recorded.length === 0)
+        return heldForgets ?? NO_HELD_FORGETS;
+    const keys = new Set(heldForgets ?? NO_HELD_FORGETS);
+    for (const entry of recorded)
+        keys.add(memoryNoteKey(entry.scope, entry.slug));
+    return keys;
+}
 /**
  * Regenerate the index files of a store from what it holds: the project notes and
  * the decisions into `MEMORY.md`, and — on a store that has a user directory — the
  * user notes into the user scope's `MEMORY.md`, which carries the header lines and
- * the `## User` section only. The project rendering is what is returned.
+ * the `## User` section only. Every note with a queued or recorded forget is marked.
+ * The project rendering is what is returned.
  */
 export async function refreshMemoryIndex(store, options = {}) {
-    const heldForgets = options.heldForgets ?? NO_HELD_FORGETS;
+    const heldForgets = await markedForgets(store, options.heldForgets);
     const caps = { maxBytes: options.maxBytes, maxLines: options.maxLines };
     const project = renderMemoryIndex({
         projectNotes: await store.listNotes("project"),

package/dist/memory/index.d.ts

@@ -8,5 +8,5 @@ export { searchMemoryNotes, tokenizeMemoryQuery } from "./search.ts";
 export { createMemoryStore, type MemoryStore, type MemoryStorePaths, type MemorySyncState, } from "./store.ts";
 export { raceTimeout } from "./support.ts";
 export { type MemorySyncInput, type MemorySyncResult, syncMemory } from "./sync.ts";
-export { MEMORY_CLIENT_ID_RE, MEMORY_DECISION_STATUSES, MEMORY_DESCRIPTION_MAX_CHARS, MEMORY_FORGET_REASON_MAX_CHARS, MEMORY_INDEX_MAX_BYTES, MEMORY_INDEX_MAX_LINES, MEMORY_INDEX_MIN_BYTES, MEMORY_INDEX_MIN_LINES, MEMORY_NOTE_BODY_MAX_BYTES, MEMORY_NOTE_STATUSES, MEMORY_NOTE_TYPES, MEMORY_OP_TIMEOUT_MS, MEMORY_PROBE_TIMEOUT_MS, MEMORY_PULL_MAX_PAGES, MEMORY_PULL_PAGE_SIZE, MEMORY_SCOPES, MEMORY_SLUG_RE, MEMORY_SOURCE_MAX_CHARS, type MemoryDecision, type MemoryDecisionStatus, type MemoryHit, type MemoryNote, type MemoryNoteStatus, type MemoryNoteType, type MemoryNoteWrite, type MemoryScope, type MemoryTimers, type MemoryWriteRefusal, } from "./types.ts";
+export { MEMORY_CLIENT_ID_RE, MEMORY_DECISION_STATUSES, MEMORY_DESCRIPTION_MAX_CHARS, MEMORY_FORGET_REASON_MAX_CHARS, MEMORY_INDEX_MAX_BYTES, MEMORY_INDEX_MAX_LINES, MEMORY_INDEX_MIN_BYTES, MEMORY_INDEX_MIN_LINES, MEMORY_NOTE_BODY_MAX_BYTES, MEMORY_NOTE_STATUSES, MEMORY_NOTE_TYPES, MEMORY_OP_TIMEOUT_MS, MEMORY_PROBE_TIMEOUT_MS, MEMORY_PULL_MAX_PAGES, MEMORY_PULL_PAGE_SIZE, MEMORY_SCOPES, MEMORY_SLUG_RE, MEMORY_SOURCE_MAX_CHARS, type MemoryDecision, type MemoryDecisionStatus, type MemoryHit, type MemoryNote, type MemoryNoteStatus, type MemoryNoteType, type MemoryNoteWrite, type MemoryPendingForget, type MemoryScope, type MemoryTimers, type MemoryWriteRefusal, } from "./types.ts";
 export { findSecret, forgetReasonRefusal, validateMemoryNoteWrite } from "./validate.ts";

package/dist/memory/local-provider.js

@@ -6,16 +6,26 @@
  * `proposal`, which is not in force until an approval); a `forget` deletes the
  * note under `direct` and leaves it in place under `proposal`. Both resolve the
  * id the caller can key the mirror on — the note's id for a save, the write's
- * client id for a forget, which has no note left to name. A write the store can
- * never accept — an unslugged note, a scope this store does not have, a target
- * outside it — is refused as `MEMORY_PUSH_REJECTED`, never retried; a failure
- * that a retry can fix (a permission error, a full disk) is left as it is.
+ * client id for a forget, which has no note left to name.
+ *
+ * A proposal forget is the one write the mirror cannot carry out, so it is queued in
+ * the store's `pending-forgets.jsonl` instead: the record is what an index refresh and
+ * an approval read later, in a process that never saw the request. A `direct` forget or
+ * a save of that key takes the entry back out — the mirror then holds what was asked
+ * for. Nothing else may write the record on this provider's behalf.
+ *
+ * A write the store can never accept — an unslugged note, a scope this store does not
+ * have, a target outside it — is refused as `MEMORY_PUSH_REJECTED`, never retried.
+ * A failure that a retry can fix (a permission error, a full disk) is left as it is,
+ * including one from the record write: the operation keeps the write queued and a
+ * later sync replays it.
  *
  * `pull` is the empty finished page: the mirror is the store the caller already
  * reads, so there is nothing to pull back into it. There is no `search`; keyword
  * search runs over the mirror through `searchMemoryNotes`.
  */
 import { NaxError } from "#src/infra/nax-error";
+import { memoryNoteKey } from "./types.js";
 const ERROR_STAGE = "memory";
 /** The status a write lands with: a proposal is not in force until an approval. */
 const WRITE_MODE_STATUS = {
@@ -53,6 +63,38 @@ async function throughStore(action) {
         throw pushRejectedFrom(error);
     }
 }
+/** The entry a proposal forget leaves in the record: the request's own id and reason. */
+function queuedForget(request) {
+    return { clientId: request.clientId, scope: request.scope, slug: request.slug, reason: request.reason ?? "" };
+}
+/** Whether rewriting the record would change it: an unchanged list is not written back. */
+function sameEntries(before, after) {
+    if (before.length !== after.length)
+        return false;
+    return before.every((entry, index) => {
+        const other = after[index];
+        return (other !== undefined &&
+            entry.clientId === other.clientId &&
+            entry.scope === other.scope &&
+            entry.slug === other.slug &&
+            entry.reason === other.reason);
+    });
+}
+/**
+ * The record rewritten without `key`'s entry, and with `queued` appended after the
+ * others when a proposal forget is what took the entry out. The store validates the
+ * slugs it is handed, so a forget of a slug no note can carry is refused here — before
+ * anything is recorded — even though a proposal never reaches the notes themselves.
+ */
+async function rewriteRecord(store, key, queued) {
+    const entries = await store.readPendingForgets();
+    const kept = entries.filter((entry) => memoryNoteKey(entry.scope, entry.slug) !== key);
+    const next = queued === null ? kept : [...kept, queued];
+    // A key the record does not hold leaves the file alone: absent stays absent.
+    if (sameEntries(entries, next))
+        return;
+    await store.writePendingForgets(next);
+}
 export function createLocalMemoryProvider(store) {
     /** A save is accepted by definition: the mirror is what the provider is. */
     async function save(request) {
@@ -61,6 +103,9 @@ export function createLocalMemoryProvider(store) {
             throw pushRejected(`memory save for "${request.slug}" carries no note`);
         const status = WRITE_MODE_STATUS[request.writeMode];
         await throughStore(() => store.writeNote({ ...note, status }));
+        // Saving the slug again means it is wanted, so whatever forget it was queued for goes.
+        const key = memoryNoteKey(note.scope, note.slug);
+        await throughStore(() => rewriteRecord(store, key, null));
         return { id: note.id, status };
     }
     /** A forget under direct removes the note; a proposal leaves it for an approval. */
@@ -68,6 +113,8 @@ export function createLocalMemoryProvider(store) {
         const direct = request.writeMode === "direct";
         if (direct)
             await throughStore(() => store.deleteNote(request.scope, request.slug));
+        const key = memoryNoteKey(request.scope, request.slug);
+        await throughStore(() => rewriteRecord(store, key, direct ? null : queuedForget(request)));
         return { id: request.clientId, status: direct ? "deleted" : "pending" };
     }
     return {

package/dist/memory/operations.d.ts

@@ -51,10 +51,8 @@ export interface MemoryForgetResult {
 /**
  * One approval: the note to put in force, named by its scope and slug.
  *
- * The mirror is the whole of what an approval decides, so it is given no queue to declare a
- * write on and no provider to ask. It is given the seams its lock wait runs on, because the
- * note it rewrites has to be the note the mirror holds at that moment — and every one of them
- * has a default, so `{ store, scope, slug }` is a complete input.
+ * The mirror is the whole of what an approval decides: no queue to declare a write on, no provider
+ * to ask, and every lock seam defaulted, so `{ store, scope, slug }` is a complete input.
  */
 export interface MemoryApproveInput {
     readonly store: MemoryStore;
@@ -97,24 +95,29 @@ export declare function saveMemoryNote(input: MemorySaveInput): Promise<MemorySa
  */
 export declare function forgetMemoryNote(input: MemoryForgetInput): Promise<MemoryForgetResult>;
 /**
- * Put one pending note in force in this mirror.
+ * Put one pending note in force in this mirror — or retire the note a recorded forget names.
  *
  * Only the note the mirror holds is consulted, so approval is a local transition rather than an
  * authorization step: it asks no provider and writes nothing to the queue, and a forget waiting
- * on that queue is still waiting afterwards. What it does read from the queue is the set of
- * notes whose forget is queued, because the index it regenerates carries that marker and an
- * index rendered without it would report a still-pending retire as though it had never been
- * asked for.
+ * there is still waiting afterwards. What it does read besides the note is the mirror's
+ * pending-forget record — `pending-forgets.jsonl`, written by the local provider for a proposal
+ * forget — and the queue's held keys, because the index it regenerates carries those markers.
  *
- * The read and the rewrite are one decision, so they run under the same ordering and the same
- * lock file a save and a forget use: this is a writer of the mirror, and what it approves must
- * be the note the mirror holds now rather than a copy read before another writer's newer one
- * landed. Waiting is the right answer here, unlike a save's — an approval has no queue to put
- * its write on, so it has to be the writer when it reads.
+ * An entry in the record is the one thing an approval can carry out that a rewrite cannot: the note
+ * is deleted, the entry is taken out of the record, the index is regenerated, and the note comes
+ * back as it was read with `status: "deleted"` — its `updatedAt` still says when it was written.
+ * That arm runs before the activation of a `pending` note, because a pending forget wins over a
+ * pending save: the agent asked for the note to go after asking for it to exist. A delete that
+ * throws leaves the entry where it is, so the next approval finds the forget again.
  *
- * A note already in force is returned exactly as it stands — approving it again is not a
- * rewrite, so its `updatedAt` still says when it was made active. A note that is history is not
- * a note waiting for approval, and neither is one this mirror does not hold: both are
- * `MEMORY_NOTE_NOT_FOUND`, because there is nothing to approve.
+ * The read and the rewrite are one decision, so they run under the same ordering and the same lock
+ * file a save and a forget use: this is a writer of the mirror, and what it approves must be the
+ * note the mirror holds now rather than a copy read before another writer's newer one landed.
+ * Waiting is the right answer here, unlike a save's — an approval has no queue to put its write on.
+ *
+ * A note already in force, with nothing recorded against it, is returned exactly as it stands —
+ * approving it again is not a rewrite, so its `updatedAt` still says when it was made active. A
+ * note that is history is not a note waiting for approval, and neither is one this mirror does
+ * not hold: both are `MEMORY_NOTE_NOT_FOUND`, because there is nothing to approve.
  */
 export declare function approveMemoryNote(input: MemoryApproveInput): Promise<MemoryNote>;

package/dist/memory/operations.js

@@ -47,10 +47,13 @@
  * `approveMemoryNote` is the transition a proposal waits for: a pending note is rewritten in force
  * under the caller's clock and the index is regenerated from the mirror, a note already in force is
  * returned as it stands, and a note that is history — or one this mirror does not hold — is the
- * same `MEMORY_NOTE_NOT_FOUND` refusal a forget of it would be. It asks no provider and writes
- * nothing to the queue, but it still writes the mirror, so it takes the same ordering and the same
- * locks a save takes. It reads the held-forget set only to keep the index's marker, and approves
- * no queued forget: the entry stays the outbox's.
+ * same `MEMORY_NOTE_NOT_FOUND` refusal a forget of it would be. A note the mirror's
+ * `pending-forgets.jsonl` record holds a forget for is retired instead of approved: the note is
+ * deleted, its entry comes out of the record and the index is regenerated, so the answer is that
+ * note, unchanged but for `status: "deleted"` — a recorded forget wins over a pending save. It asks
+ * no provider and writes nothing to the queue, but it writes the mirror and the record, so it takes
+ * the same ordering and the same locks a save takes. It reads the queue only to keep the index's
+ * marker, and approves no queued forget: an entry the outbox still holds stays the outbox's.
  */
 import { randomUUID } from "node:crypto";
 import { getLogger } from "#src/infra/agent-logger";
@@ -382,10 +385,7 @@ function inForce(note, now) {
 function mirrorOutbox(store) {
     return createMemoryOutbox({ dir: store.paths.outboxDir });
 }
-/**
- * The mirror's lock as this approval takes it: the caller's seam where it gave one, and the
- * process defaults — including the logger slot — where it did not.
- */
+/** The mirror's lock as this approval takes it: the caller's seams, else the process defaults. */
 function lockInputOf(input) {
     return {
         store: input.store,
@@ -397,16 +397,20 @@ function lockInputOf(input) {
 }
 /**
  * The locked half of an approval: read, decide and rewrite while no other writer of this
- * mirror can change the note in between.
+ * mirror can change the note in between — the read and the write are one decision, which is
+ * the whole reason this takes the lock at all.
  *
- * The read and the write have to be one decision — that is the whole reason this takes the
- * lock at all — so a note another writer replaced while this waited is the note that gets
- * approved, never the copy this operation would otherwise have read before the wait.
+ * A recorded pending forget is checked before the note's own status, because a pending forget
+ * wins over a pending save: the note the mirror holds was written first, and the forget of it
+ * came after. A note that is history, or one the mirror does not hold, is the refusal it was
+ * before the record is consulted at all.
  */
 async function approveLocked(input) {
     const note = await input.store.readNote(input.scope, input.slug);
     if (note === null || RETIRED_STATUSES.has(note.status))
         throw noteNotFound(input);
+    if (await holdsRecordedForget(input))
+        return await retireRecorded(input, note);
     if (note.status === "active")
         return note;
     const approved = inForce(note, clockOf(input));
@@ -414,26 +418,53 @@ async function approveLocked(input) {
     await refreshIndex({ store: input.store, outbox: mirrorOutbox(input.store) });
     return approved;
 }
+/** Whether the mirror's record holds a pending forget for the key this approval names. */
+async function holdsRecordedForget(input) {
+    const key = memoryNoteKey(input.scope, input.slug);
+    const recorded = await input.store.readPendingForgets();
+    return recorded.some((entry) => memoryNoteKey(entry.scope, entry.slug) === key);
+}
 /**
- * Put one pending note in force in this mirror.
+ * The note a recorded forget retires: the note goes, then its entry comes out of the record.
+ *
+ * That order is the failure contract: a delete that throws leaves the record holding the entry, so
+ * the forget is still outstanding and still findable. The record is re-read after the delete — an
+ * entry another writer appended meanwhile survives — and the note comes back as it was read, with
+ * `status: "deleted"` and its own `updatedAt`: an approval retires a note, it does not rewrite one.
+ */
+async function retireRecorded(input, note) {
+    const key = memoryNoteKey(input.scope, input.slug);
+    await input.store.deleteNote(input.scope, input.slug);
+    const recorded = await input.store.readPendingForgets();
+    await input.store.writePendingForgets(recorded.filter((entry) => memoryNoteKey(entry.scope, entry.slug) !== key));
+    await refreshIndex({ store: input.store, outbox: mirrorOutbox(input.store) });
+    return { ...note, status: "deleted" };
+}
+/**
+ * Put one pending note in force in this mirror — or retire the note a recorded forget names.
  *
  * Only the note the mirror holds is consulted, so approval is a local transition rather than an
  * authorization step: it asks no provider and writes nothing to the queue, and a forget waiting
- * on that queue is still waiting afterwards. What it does read from the queue is the set of
- * notes whose forget is queued, because the index it regenerates carries that marker and an
- * index rendered without it would report a still-pending retire as though it had never been
- * asked for.
+ * there is still waiting afterwards. What it does read besides the note is the mirror's
+ * pending-forget record — `pending-forgets.jsonl`, written by the local provider for a proposal
+ * forget — and the queue's held keys, because the index it regenerates carries those markers.
+ *
+ * An entry in the record is the one thing an approval can carry out that a rewrite cannot: the note
+ * is deleted, the entry is taken out of the record, the index is regenerated, and the note comes
+ * back as it was read with `status: "deleted"` — its `updatedAt` still says when it was written.
+ * That arm runs before the activation of a `pending` note, because a pending forget wins over a
+ * pending save: the agent asked for the note to go after asking for it to exist. A delete that
+ * throws leaves the entry where it is, so the next approval finds the forget again.
  *
- * The read and the rewrite are one decision, so they run under the same ordering and the same
- * lock file a save and a forget use: this is a writer of the mirror, and what it approves must
- * be the note the mirror holds now rather than a copy read before another writer's newer one
- * landed. Waiting is the right answer here, unlike a save's — an approval has no queue to put
- * its write on, so it has to be the writer when it reads.
+ * The read and the rewrite are one decision, so they run under the same ordering and the same lock
+ * file a save and a forget use: this is a writer of the mirror, and what it approves must be the
+ * note the mirror holds now rather than a copy read before another writer's newer one landed.
+ * Waiting is the right answer here, unlike a save's — an approval has no queue to put its write on.
  *
- * A note already in force is returned exactly as it stands — approving it again is not a
- * rewrite, so its `updatedAt` still says when it was made active. A note that is history is not
- * a note waiting for approval, and neither is one this mirror does not hold: both are
- * `MEMORY_NOTE_NOT_FOUND`, because there is nothing to approve.
+ * A note already in force, with nothing recorded against it, is returned exactly as it stands —
+ * approving it again is not a rewrite, so its `updatedAt` still says when it was made active. A
+ * note that is history is not a note waiting for approval, and neither is one this mirror does
+ * not hold: both are `MEMORY_NOTE_NOT_FOUND`, because there is nothing to approve.
  */
 export async function approveMemoryNote(input) {
     return await orderedByMirrorLocks(input.store, () => withMirrorLock(lockInputOf(input), () => approveLocked(input)));

package/dist/memory/records.d.ts

@@ -1,14 +1,15 @@
 /**
- * The two record files the mirror keeps beside its notes, decoded.
+ * The record files the mirror keeps beside its notes, decoded.
  *
- * `decisions.jsonl` is one `MemoryDecision` per line and `sync.json` is one
- * `MemorySyncState`: both are written whole by this store and read back by it, so what
- * makes a line a decision — and what makes a file a state — is a schema rather than a
- * cast. Keeping the schemas here leaves the store to decide what a refused line *means*
+ * `decisions.jsonl` is one `MemoryDecision` per line, `pending-forgets.jsonl` one
+ * `MemoryPendingForget` per line, and `sync.json` is one `MemorySyncState`: all three are
+ * written whole by this store and read back by it, so what makes a line a decision — or
+ * a pending forget, or what makes a file a state — is a schema rather than a cast.
+ * Keeping the schemas here leaves the store to decide what a refused line *means*
  * (skipped with a warning) and this module to decide what counts as one.
  */
 import { z } from "zod";
-import { type MemoryDecision } from "./types.ts";
+import { type MemoryDecision, type MemoryPendingForget } from "./types.ts";
 declare const SyncStateSchema: z.ZodObject<{
     provider: z.ZodNullable<z.ZodString>;
     cursor: z.ZodObject<{
@@ -24,6 +25,17 @@ export type ParsedSyncState = z.infer<typeof SyncStateSchema>;
 export declare function defaultSyncState(): ParsedSyncState;
 /** One mirror line as a decision, or `null` when the line is not one. */
 export declare function parseDecisionLine(line: string): MemoryDecision | null;
+/** One mirror line as a pending forget, or `null` when the line is not one. */
+export declare function parsePendingForgetLine(line: string): MemoryPendingForget | null;
+/**
+ * A JSONL record's text as its entries. A line the decoder refuses is skipped with one
+ * report naming its 1-based line number, never fatal: the other lines are still the
+ * record. A record file that is not there (`null`) is the empty record, not the absent
+ * one — a store that has never recorded anything answers `[]` and creates nothing.
+ */
+export declare function decodeRecordLines<T>(text: string | null, decode: (line: string) => T | null, warnSkipped: (line: number) => void): T[];
+/** One record file's text: one JSON object per line, and nothing at all when empty. */
+export declare function encodeRecordLines(entries: readonly unknown[]): string;
 /** The whole `sync.json` text as a state, or `null` when it does not hold one. */
 export declare function parseSyncStateText(text: string): ParsedSyncState | null;
 export {};

package/dist/memory/records.js

@@ -1,14 +1,15 @@
 /**
- * The two record files the mirror keeps beside its notes, decoded.
+ * The record files the mirror keeps beside its notes, decoded.
  *
- * `decisions.jsonl` is one `MemoryDecision` per line and `sync.json` is one
- * `MemorySyncState`: both are written whole by this store and read back by it, so what
- * makes a line a decision — and what makes a file a state — is a schema rather than a
- * cast. Keeping the schemas here leaves the store to decide what a refused line *means*
+ * `decisions.jsonl` is one `MemoryDecision` per line, `pending-forgets.jsonl` one
+ * `MemoryPendingForget` per line, and `sync.json` is one `MemorySyncState`: all three are
+ * written whole by this store and read back by it, so what makes a line a decision — or
+ * a pending forget, or what makes a file a state — is a schema rather than a cast.
+ * Keeping the schemas here leaves the store to decide what a refused line *means*
  * (skipped with a warning) and this module to decide what counts as one.
  */
 import { z } from "zod";
-import { MEMORY_DECISION_STATUSES } from "./types.js";
+import { MEMORY_CLIENT_ID_RE, MEMORY_DECISION_STATUSES, MEMORY_SCOPES, MEMORY_SLUG_RE, } from "./types.js";
 /** A decision as one mirror line; the shape is what makes a line a decision. */
 const DecisionSchema = z.object({
     id: z.string().min(1),
@@ -18,6 +19,17 @@ const DecisionSchema = z.object({
     updatedAt: z.string().min(1),
     status: z.enum(MEMORY_DECISION_STATUSES),
 });
+/**
+ * A pending forget as one mirror line. The slug and the client id are the two values
+ * later code acts on — the slug names the note an approval retires, the client id names
+ * the write — so a line carries a note slug and an outbox id, never an arbitrary string.
+ */
+const PendingForgetSchema = z.object({
+    clientId: z.string().regex(MEMORY_CLIENT_ID_RE),
+    scope: z.enum(MEMORY_SCOPES),
+    slug: z.string().regex(MEMORY_SLUG_RE),
+    reason: z.string(),
+});
 const SyncStateSchema = z.object({
     provider: z.string().nullable(),
     cursor: z.object({ project: z.string().nullable(), user: z.string().nullable() }),
@@ -43,6 +55,37 @@ export function parseDecisionLine(line) {
     const parsed = DecisionSchema.safeParse(parseJson(line));
     return parsed.success ? parsed.data : null;
 }
+/** One mirror line as a pending forget, or `null` when the line is not one. */
+export function parsePendingForgetLine(line) {
+    const parsed = PendingForgetSchema.safeParse(parseJson(line));
+    return parsed.success ? parsed.data : null;
+}
+/**
+ * A JSONL record's text as its entries. A line the decoder refuses is skipped with one
+ * report naming its 1-based line number, never fatal: the other lines are still the
+ * record. A record file that is not there (`null`) is the empty record, not the absent
+ * one — a store that has never recorded anything answers `[]` and creates nothing.
+ */
+export function decodeRecordLines(text, decode, warnSkipped) {
+    if (text === null)
+        return [];
+    const entries = [];
+    for (const [index, raw] of text.split("\n").entries()) {
+        if (raw.trim() === "")
+            continue;
+        const entry = decode(raw);
+        if (entry === null) {
+            warnSkipped(index + 1);
+            continue;
+        }
+        entries.push(entry);
+    }
+    return entries;
+}
+/** One record file's text: one JSON object per line, and nothing at all when empty. */
+export function encodeRecordLines(entries) {
+    return entries.map((entry) => `${JSON.stringify(entry)}\n`).join("");
+}
 /** The whole `sync.json` text as a state, or `null` when it does not hold one. */
 export function parseSyncStateText(text) {
     const parsed = SyncStateSchema.safeParse(parseJson(text));

package/dist/memory/store.d.ts

@@ -15,18 +15,19 @@
  * The caller's global cwd is never changed. Post-checks report moved directories;
  * they are not the mechanism that prevents access to replacements.
  *
- * The store also owns the three record files beside the notes: the read-only
- * `decisions.jsonl` mirror (one JSON object per line), `sync.json` (the sync
- * state) and each scope's generated `MEMORY.md`. They hold no user-authored
- * paths, so they are read and written without a slug to validate; the only
- * scope rule is that the user files need a user directory. A record read is
- * still confined: it is read under the project directory's pin and never
- * follows a link out of the store.
+ * The store also owns the record files beside the notes: the `decisions.jsonl`
+ * mirror (one JSON object per line), the `pending-forgets.jsonl` record of queued
+ * forgets, `sync.json` (the sync state) and each scope's generated `MEMORY.md`.
+ * They hold no user-authored paths, so they are read and written without a slug to
+ * validate — save a pending forget's own slug, which names a note and must be one.
+ * The only scope rule is that the user files need a user directory. A record read is
+ * still confined: it is read under the project directory's pin and never follows a
+ * link out of the store.
  */
 import type { Dirent } from "node:fs";
 import type { AgentLogger } from "#src/infra/agent-logger";
 import { withPinnedDirectory } from "#src/internal/pinned-directory";
-import { type MemoryDecision, type MemoryNote, type MemoryScope } from "./types.ts";
+import { type MemoryDecision, type MemoryNote, type MemoryPendingForget, type MemoryScope } from "./types.ts";
 interface Identity {
     readonly dev: number;
     readonly ino: number;
@@ -65,6 +66,7 @@ export interface MemoryStorePaths {
     readonly index: string;
     readonly notesDir: string;
     readonly decisions: string;
+    readonly pendingForgets: string;
     readonly syncState: string;
     readonly lock: string;
     readonly outboxDir: string;
@@ -90,6 +92,8 @@ export interface MemoryStore {
     listNotes(scope: MemoryScope): Promise<MemoryNote[]>;
     readDecisions(): Promise<MemoryDecision[]>;
     writeDecisions(decisions: readonly MemoryDecision[]): Promise<void>;
+    readPendingForgets(): Promise<MemoryPendingForget[]>;
+    writePendingForgets(entries: readonly MemoryPendingForget[]): Promise<void>;
     readSyncState(): Promise<MemorySyncState>;
     writeSyncState(state: MemorySyncState): Promise<void>;
     writeIndex(scope: MemoryScope, text: string): Promise<void>;