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

package/CHANGELOG.md

@@ -4,6 +4,14 @@ 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.
+
 ## [0.91.7] - 2026-11-01
 
 - 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,6 +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 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";
@@ -32,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";
@@ -41,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/index.js

@@ -16,6 +16,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, 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, } from "#src/terminal-auth/index";
 export { AuthCancelledError, ambientShadows, anyAmbientCredential, authImportOutcomeLabel, createFileTranscriptStore, createMemoryTranscriptStore, credentialFilePath, DEFAULT_PI_AUTH_PATH, importPiCredentials, listProviderModels, listStoredProviders, loginProviderIds, MAX_RETAINED_TRANSCRIPTS, NATIVE_AGENT, NativeSessionAdapter, NativeSessionUnsupportedError, nativeComplete, nativeTierProviders, naxCredentialStore, newSessionKey, providersWithoutCredentials, pruneRetainedTranscripts, removeStoredProvider, resolveNativeId, runLogin, servedAuth, } from "#src/native/index";
 export { displayToolInput, TOOL_CALL_INPUT_BYTES, TOOL_RESULT_PREVIEW_BYTES, toolResultPreview, } from "#src/native/session/turn-event-emitter";

package/dist/internal/atomic-write.d.ts

@@ -1,16 +1,31 @@
 import { rename, rm } from "node:fs/promises";
-/** The one `writeFile` shape this module uses; narrower than the overloaded node signature so stubs type-check. */
-type WriteText = (path: string, content: string | Uint8Array, options: {
-    encoding: "utf8";
-    mode?: number;
-}) => Promise<void>;
-/** Injectable for tests that simulate a write dying part-way. */
+/** What a file is, independent of the path that names it. */
+interface Identity {
+    readonly dev: number;
+    readonly ino: number;
+}
+/** One created stage: written through its descriptor, identified by it, then closed. */
+interface StagedFile {
+    write(content: string | Uint8Array): Promise<void>;
+    identity(): Promise<Identity>;
+    close(): Promise<void>;
+}
+/** Try removing an empty stage directory, never its contents. Injectable for tests. */
+type DiscardStage = (stageDir: string) => Promise<void>;
+/** Injectable for tests that simulate a write dying part-way, or a stage namespace being taken. */
 export declare const _atomicWriteDeps: {
-    writeFile: WriteText;
+    stage: (dir: string, mode: number) => Promise<void>;
+    open: (path: string, flags: number, mode: number) => Promise<StagedFile>;
     rename: typeof rename;
     rm: typeof rm;
+    discard: DiscardStage;
 };
 export declare function writeFileAtomic(path: string, content: string | Uint8Array, options?: {
     mode?: number;
+    beforePublish?: () => Promise<void>;
+    afterPublish?: (stage: {
+        dev: number;
+        ino: number;
+    }) => Promise<void>;
 }): Promise<void>;
 export {};

package/dist/internal/atomic-write.js

@@ -8,27 +8,122 @@
  * sees the old file or the new one. Same-directory staging keeps the rename on
  * one filesystem, where POSIX makes it atomic. Not fsync'd: this guards against
  * a killed PROCESS, not a power loss.
+ *
+ * The stage is a *directory* (`<path>.<uuid>.tmp`) created exclusively by this
+ * call. Exclusive creation and mode 0700 do not establish continuing ownership:
+ * a writer of its parent can rename it and put a foreign directory or link at
+ * its name. Cleanup therefore NEVER unlinks a payload through that pathname.
+ * It only attempts `rmdir`, which neither follows a final symlink nor removes a
+ * nonempty directory. Failed writes conservatively retain their payloads; even
+ * a replacement between the last check and cleanup cannot lose foreign bytes.
+ * Successful publication normally leaves an empty stage directory to remove.
+ * A retained `.tmp` namespace is ignored by the package's listings. No pathname
+ * identity check is claimed to make cleanup ownership-atomic.
+ *
+ * In a pinned-directory context all stage, publication and cleanup operations
+ * are relative to the verified cwd, and the stage directory is reached as one
+ * deeper operand of it. Ordinary callers retain path-based I/O. The hooks
+ * additionally verify the destination:
+ *
+ * - `beforePublish` runs once the bytes are staged and before the rename, so a
+ *   destination that moved during the write is refused before it receives them;
+ * - `afterPublish` receives the staged file's identity once the rename is done, so a
+ *   caller can check — and take back by identity — a note that landed somewhere the
+ *   rename could not be told apart from.
+ *
+ * A throw from either hook fails the write; cleanup retains any remaining payload.
  */
 import { randomUUID } from "node:crypto";
-import { rename, rm, writeFile } from "node:fs/promises";
-/** Injectable for tests that simulate a write dying part-way. */
+import { constants } from "node:fs";
+import { mkdir, open, rename, rm, rmdir } from "node:fs/promises";
+import { join } from "node:path";
+import { openPinnedStage, pinnedOperation } from "./pinned-directory.js";
+/** Exclusive creation, and never through a link at the stage's name. */
+const STAGE_FLAGS = constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW;
+/** Restrict access inside the stage, without claiming that its parent cannot replace it. */
+const STAGE_DIR_MODE = 0o700;
+/** The default a plain `writeFile` would apply, so a published note keeps ordinary permissions. */
+const STAGE_MODE = 0o666;
+/** The suffix every stage directory carries; the package's listings ignore those names. */
+const STAGE_SUFFIX = ".tmp";
+/** The payload's name inside the stage directory: the only entry this call ever puts there. */
+const STAGE_NAME = "stage";
+/** Injectable for tests that simulate a write dying part-way, or a stage namespace being taken. */
 export const _atomicWriteDeps = {
-    writeFile: (path, content, options) => writeFile(path, content, options),
-    rename,
-    rm,
+    stage: async (dir, mode) => {
+        const pinned = await pinnedOperation(dir, "stage", [mode]);
+        if (pinned !== null)
+            return await pinned;
+        await mkdir(dir, { mode });
+    },
+    open: async (path, flags, mode) => {
+        const pinned = await openPinnedStage(path, flags, mode);
+        if (pinned)
+            return pinned;
+        const handle = await open(path, flags, mode);
+        return {
+            write: (content) => handle.writeFile(content, { encoding: "utf8" }),
+            identity: async () => {
+                const info = await handle.stat();
+                return { dev: info.dev, ino: info.ino };
+            },
+            close: () => handle.close(),
+        };
+    },
+    rename: (from, to) => pinnedOperation(String(from), "rename", [String(to)]) ?? rename(from, to),
+    rm: (path, options) => pinnedOperation(String(path), "rm") ?? rm(path, options),
+    discard: (dir) => removeStage(dir),
 };
+/** Remove only an empty namespace; a payload's ownership cannot be proved by its pathname. */
+async function removeStage(stageDir) {
+    const pinned = pinnedOperation(stageDir, "discard");
+    if (pinned !== null)
+        return await pinned;
+    await rmdir(stageDir);
+}
+/**
+ * Remove the stage this call created, or leave it in place when it cannot be emptied.
+ *
+ * A removal that fails is not reported: the failure the caller is owed is the one that
+ * brought us here, and a stage left behind is a name every listing in the package ignores.
+ */
+async function discardStage(stageDir, owned) {
+    if (!owned)
+        return;
+    await _atomicWriteDeps.discard(stageDir).catch(() => {
+        // A stage that could not be emptied is retained; the pinned worker reports its own errors.
+    });
+}
 export async function writeFileAtomic(path, content, options = {}) {
     // Ends in `.tmp`, not `.json`, so directory sweeps that match `*.json` never see it.
-    const staged = `${path}.${randomUUID()}.tmp`;
+    const staged = `${path}.${randomUUID()}${STAGE_SUFFIX}`;
+    const payload = join(staged, STAGE_NAME);
+    let stage = null;
+    let owned = false;
+    let identity = null;
     try {
-        await _atomicWriteDeps.writeFile(staged, content, {
-            encoding: "utf8",
-            ...(options.mode !== undefined ? { mode: options.mode } : {}),
-        });
-        await _atomicWriteDeps.rename(staged, path);
+        await _atomicWriteDeps.stage(staged, STAGE_DIR_MODE);
+        // Only a namespace this call created is this call's to remove.
+        owned = true;
+        stage = await _atomicWriteDeps.open(payload, STAGE_FLAGS, options.mode ?? STAGE_MODE);
+        // Capture ownership before writing: a failed write may already have lost its pathname.
+        identity = await stage.identity();
+        await stage.write(content);
+        if (options.beforePublish)
+            await options.beforePublish();
+        await _atomicWriteDeps.rename(payload, path);
+        if (options.afterPublish && identity !== null)
+            await options.afterPublish(identity);
     }
     catch (error) {
-        await _atomicWriteDeps.rm(staged, { force: true });
+        await discardStage(staged, owned);
         throw error;
     }
+    finally {
+        await stage?.close().catch(() => {
+            // A stage whose write already failed cannot be rescued by reporting the close either.
+        });
+    }
+    // The published payload left the namespace empty: the directory is all that remains.
+    await discardStage(staged, owned);
 }

package/dist/internal/pinned-directory-worker.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The filesystem surface the worker drives: one member per operation it serves.
+ *
+ * Named rather than `typeof import("node:fs/promises")` so a test can answer a single
+ * operation (the real module still satisfies it structurally, so the caller passes it as is).
+ */
+export interface PinnedWorkerFs {
+    stat(path: string): Promise<{
+        readonly dev: number;
+        readonly ino: number;
+    }>;
+    lstat(path: string): Promise<{
+        readonly dev: number;
+        readonly ino: number;
+    }>;
+    open(path: string, flags: number, mode: number): Promise<{
+        readFile(options: {
+            encoding: "utf8";
+        }): Promise<string>;
+        writeFile(content: Uint8Array): Promise<void>;
+        stat(): Promise<{
+            readonly dev: number;
+            readonly ino: number;
+        }>;
+        close(): Promise<void>;
+    }>;
+    realpath(path: string): Promise<string>;
+    mkdir(path: string, options: {
+        readonly mode: number;
+    }): Promise<string | undefined>;
+    rename(from: string, to: string): Promise<void>;
+    rm(path: string, options: {
+        readonly force: true;
+    }): Promise<void>;
+    unlink(path: string): Promise<void>;
+    rmdir(path: string): Promise<void>;
+}
+/**
+ * Runs in a dedicated process whose cwd pins a directory inode on POSIX, including
+ * macOS (where /dev/fd/<dirfd>/name is not traversable). Never chdir in the caller:
+ * its cwd is process-global. Keep this function self-contained for `node -e`.
+ */
+export declare function pinnedDirectoryWorker(fs: PinnedWorkerFs, io: {
+    input: NodeJS.ReadableStream;
+    write(text: string): unknown;
+    createInterface: typeof import("node:readline").createInterface;
+    /**
+     * An absolute path that names this worker's cwd *by inode* (Linux: `/proc/self/cwd`),
+     * or null where the platform has none. See `anchored` below for what it buys.
+     */
+    anchor?: string | null;
+}): Promise<void>;

package/dist/internal/pinned-directory-worker.js

@@ -0,0 +1,105 @@
+/**
+ * Runs in a dedicated process whose cwd pins a directory inode on POSIX, including
+ * macOS (where /dev/fd/<dirfd>/name is not traversable). Never chdir in the caller:
+ * its cwd is process-global. Keep this function self-contained for `node -e`.
+ */
+export async function pinnedDirectoryWorker(fs, io) {
+    /**
+     * Absolute spellings, for the one operation that cannot be spelled relatively.
+     *
+     * Every other operation hands the kernel a relative name, which it resolves against the
+     * cwd inode: renaming the directory afterwards cannot redirect `open`, `rename` or `stat`.
+     * `realpath` is the exception — it takes an absolute path, and a runtime that builds one
+     * from a *cached* cwd string (Bun on Linux caches the spelling, not the inode) hands the
+     * kernel the name the directory used to have, which a replacement can own. The anchor is
+     * a magic link the kernel resolves to the inode itself, so the answer still describes the
+     * directory this worker pinned.
+     *
+     * The anchor is checked against `.` before first use: an anchor the host does not have
+     * (no `/proc`, or a foreign one) is dropped and the bare name used instead.
+     */
+    let anchor = io.anchor ?? null;
+    if (anchor !== null) {
+        try {
+            const [at, dot] = [await fs.stat(anchor), await fs.stat(".")];
+            if (at.dev !== dot.dev || at.ino !== dot.ino)
+                anchor = null;
+        }
+        catch {
+            // This host offers no such anchor; the relative name is all there is.
+            anchor = null;
+        }
+    }
+    const anchored = (name) => (anchor === null ? name : `${anchor}/${name}`);
+    const files = new Map();
+    let next = 0;
+    const identity = (info) => ({ dev: info.dev, ino: info.ino });
+    const fileAt = (id) => {
+        const file = files.get(Number(id));
+        if (!file)
+            throw new Error(`Unknown pinned descriptor: ${id}`); // nax-lint-allow: plain-error — isolated wire protocol, reconstructed as NaxError by caller
+        return file;
+    };
+    const lines = io.createInterface({ input: io.input });
+    for await (const line of lines) {
+        try {
+            const { op, args } = JSON.parse(line);
+            let value;
+            switch (op) {
+                case "directory":
+                    value = identity(await fs.stat("."));
+                    break;
+                case "open": {
+                    const handle = await fs.open(args[0], Number(args[1]), args[2]);
+                    files.set(++next, handle);
+                    value = next;
+                    break;
+                }
+                case "read":
+                    value = await fileAt(args[0]).readFile({ encoding: "utf8" });
+                    break;
+                case "write":
+                    await fileAt(args[0]).writeFile(Buffer.from(args[1], "base64"));
+                    break;
+                case "identity":
+                    value = identity(await fileAt(args[0]).stat());
+                    break;
+                case "resolve":
+                    value = await fs.realpath(anchored(args[0]));
+                    break;
+                case "stage":
+                    await fs.mkdir(args[0], { mode: Number(args[1]) });
+                    break;
+                case "close": {
+                    await fileAt(args[0]).close();
+                    files.delete(Number(args[0]));
+                    break;
+                }
+                case "stat":
+                    value = identity(await fs.lstat(args[0]));
+                    break;
+                case "rename":
+                    await fs.rename(args[0], args[1]);
+                    break;
+                case "rm":
+                    await fs.rm(args[0], { force: true });
+                    break;
+                case "discard": {
+                    // The pinned parent does not pin a stage's own namespace: a writer of that
+                    // parent can replace it. Never unlink through it. rmdir removes only empty
+                    // directories and refuses final symlinks; nonempty stages are retained.
+                    await fs.rmdir(args[0]);
+                    break;
+                }
+                default:
+                    throw new Error(`Unknown pinned operation: ${op}`); // nax-lint-allow: plain-error — isolated wire protocol, reconstructed as NaxError by caller
+            }
+            io.write(`${JSON.stringify({ value })}\n`);
+        }
+        catch (error) {
+            const failure = error;
+            io.write(`${JSON.stringify({ error: failure.message, code: failure.code })}\n`);
+        }
+    }
+    await Promise.all([...files.values()].map((file) => file.close()));
+}

package/dist/internal/pinned-directory.d.ts

@@ -0,0 +1,48 @@
+interface Identity {
+    readonly dev: number;
+    readonly ino: number;
+}
+/** Resolve one operand to a request: the same check for a single path and for a rename pair. */
+export declare function pinnedOperation<T>(path: string, op: string, args?: unknown[]): Promise<T> | null;
+/**
+ * Spawn first, then verify the child's cwd identity before sending any mutation.
+ * A swap during spawn therefore fails closed. Later swaps cannot redirect cwd-relative
+ * operations. AsyncLocalStorage keeps concurrent stores/seam wrappers isolated without
+ * changing the existing `_atomicWriteDeps` call signatures.
+ */
+export declare function withPinnedDirectory<T>(input: {
+    path: string;
+    identity: Identity;
+    changed: () => Error;
+}, action: () => Promise<T>): Promise<T>;
+/** Opened stage RPCs use the worker's descriptor table, never a staging pathname. */
+export declare function openPinnedStage(path: string, flags: number, mode: number): Promise<{
+    write(content: string | Uint8Array): Promise<void>;
+    identity(): Promise<Identity>;
+    close(): Promise<void>;
+} | null>;
+/** One entry of the pinned directory, open for reading; `null` outside a pinned session. */
+export interface PinnedRead {
+    readText(): Promise<string>;
+    close(): Promise<void>;
+}
+/**
+ * Open one entry of the pinned directory and read it through the descriptor.
+ *
+ * `path` names an entry *of the pinned directory itself*: the worker resolves it against the
+ * cwd it pinned, so no later rename of the directory on disk can redirect the read. The flags
+ * the caller passes are the ones the worker opens with — `O_NOFOLLOW` included, so a link at
+ * the name is refused rather than followed.
+ */
+export declare function openPinnedRead(path: string, flags: number): Promise<PinnedRead | null>;
+/**
+ * The real path of one entry of the pinned directory, resolved from the pinned inode.
+ *
+ * The answer is what the entry is *inside the pinned directory*: the caller learns whether the
+ * name is a plain file (the answer names the pinned path itself) or a link, and where that link
+ * goes, without resolving the mutable parent a second time in this process. The worker spells
+ * the resolution through `CWD_ANCHOR`, so the directory being renamed on disk changes the name
+ * in the answer without changing what it describes.
+ */
+export declare function resolvePinned(path: string): Promise<string | null>;
+export {};

package/dist/internal/pinned-directory.js

@@ -0,0 +1,168 @@
+/** Filesystem mutations relative to a process-pinned parent, not a re-resolved path. */
+import { AsyncLocalStorage } from "node:async_hooks";
+import { basename, dirname } from "node:path";
+import { NaxError } from "#src/infra/nax-error";
+import { runtimeSpawn } from "#src/runtime/index";
+import { pinnedDirectoryWorker } from "./pinned-directory-worker.js";
+const activeDirectory = new AsyncLocalStorage();
+function protocolError(message) {
+    return new NaxError(message, "MEMORY_IO_FAILED", { stage: "memory" });
+}
+/** The suffix of a staging directory: the one two-level operand a request may name. */
+const STAGE_SUFFIX = ".tmp";
+/**
+ * The path a pinned worker resolves entries through, when the platform has one.
+ *
+ * The worker's operations are relative, so the kernel resolves them against the cwd *inode* —
+ * a rename of the directory cannot redirect them. Resolution to a real path needs an absolute
+ * spelling, and a runtime may build one from a cached cwd string (Bun on Linux keeps the
+ * spelling after the directory is renamed), which would resolve the name the directory left
+ * behind. `/proc/self/cwd` is the magic link to the same inode and is Linux-only; macOS has no
+ * traversable equivalent and needs none, because its `realpath` already answers from the inode.
+ */
+const CWD_ANCHOR = process.platform === "linux" ? "/proc/self/cwd" : null;
+/**
+ * The operand a request carries, relative to the pinned directory.
+ *
+ * A name in the pinned directory is one component; the only deeper operand is a name inside
+ * one of its staging directories (`<name>.tmp/<name>`), which is how a write reaches the
+ * namespace it created for itself. Nothing else is accepted: no `..`, no absolute path and
+ * no further nesting.
+ */
+function operandIn(pinnedPath, path) {
+    if (dirname(path) === pinnedPath)
+        return basename(path);
+    const stage = dirname(path);
+    if (dirname(stage) === pinnedPath && basename(stage).endsWith(STAGE_SUFFIX)) {
+        return `${basename(stage)}/${basename(path)}`;
+    }
+    throw protocolError(`Path is not in the pinned directory: ${path}`);
+}
+/** Resolve one operand to a request: the same check for a single path and for a rename pair. */
+export function pinnedOperation(path, op, args = []) {
+    const directory = activeDirectory.getStore();
+    if (!directory)
+        return null;
+    if (op === "rename") {
+        return directory.request(op, [operandIn(directory.path, path), operandIn(directory.path, String(args[0]))]);
+    }
+    return directory.request(op, [operandIn(directory.path, path), ...args]);
+}
+async function* responses(stream) {
+    const reader = stream.getReader();
+    const decoder = new TextDecoder();
+    let pending = "";
+    try {
+        while (true) {
+            const chunk = await reader.read();
+            if (chunk.done)
+                return;
+            pending += decoder.decode(chunk.value, { stream: true });
+            let end = pending.indexOf("\n");
+            while (end !== -1) {
+                yield pending.slice(0, end);
+                pending = pending.slice(end + 1);
+                end = pending.indexOf("\n");
+            }
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+/**
+ * Spawn first, then verify the child's cwd identity before sending any mutation.
+ * A swap during spawn therefore fails closed. Later swaps cannot redirect cwd-relative
+ * operations. AsyncLocalStorage keeps concurrent stores/seam wrappers isolated without
+ * changing the existing `_atomicWriteDeps` call signatures.
+ */
+export async function withPinnedDirectory(input, action) {
+    // Builtins are supplied in the script, not imported inside the serialized function:
+    // bundlers/test transforms may otherwise rewrite import() into closure-bound helpers.
+    const script = `(${pinnedDirectoryWorker.toString()})(require("node:fs/promises"), {
+    createInterface: require("node:readline").createInterface,
+    input: process.stdin, write: (text) => process.stdout.write(text),
+    anchor: ${JSON.stringify(CWD_ANCHOR)}
+  })`;
+    const child = runtimeSpawn([process.execPath, "-e", script], {
+        cwd: input.path,
+        stdin: "pipe",
+        stdout: "pipe",
+        stderr: "pipe",
+    });
+    const stderr = new Response(child.stderr).text();
+    const lines = responses(child.stdout);
+    let queue = Promise.resolve();
+    const directory = {
+        path: input.path,
+        request(op, args) {
+            const result = queue.then(async () => {
+                child.stdin?.write(`${JSON.stringify({ op, args })}\n`);
+                child.stdin?.flush();
+                const reply = await lines.next();
+                if (reply.done)
+                    throw protocolError(`Pinned directory worker exited: ${await stderr}`);
+                const response = JSON.parse(reply.value);
+                if (response.error)
+                    throw new NaxError(response.error, response.code ?? "MEMORY_IO_FAILED", { stage: "memory", op });
+                return response.value;
+            });
+            queue = result.then(() => undefined, () => undefined);
+            return result;
+        },
+    };
+    try {
+        const actual = await directory.request("directory", []);
+        if (actual.dev !== input.identity.dev || actual.ino !== input.identity.ino)
+            throw input.changed();
+        return await activeDirectory.run(directory, action);
+    }
+    finally {
+        child.stdin?.end();
+        await Promise.all([child.exited, stderr]);
+        await lines.return(undefined);
+    }
+}
+/** Opened stage RPCs use the worker's descriptor table, never a staging pathname. */
+export async function openPinnedStage(path, flags, mode) {
+    const directory = activeDirectory.getStore();
+    if (!directory)
+        return null;
+    const descriptor = await pinnedOperation(path, "open", [flags, mode]);
+    return {
+        write: (content) => directory.request("write", [descriptor, Buffer.from(content).toString("base64")]),
+        identity: () => directory.request("identity", [descriptor]),
+        close: () => directory.request("close", [descriptor]),
+    };
+}
+/**
+ * Open one entry of the pinned directory and read it through the descriptor.
+ *
+ * `path` names an entry *of the pinned directory itself*: the worker resolves it against the
+ * cwd it pinned, so no later rename of the directory on disk can redirect the read. The flags
+ * the caller passes are the ones the worker opens with — `O_NOFOLLOW` included, so a link at
+ * the name is refused rather than followed.
+ */
+export async function openPinnedRead(path, flags) {
+    const directory = activeDirectory.getStore();
+    if (!directory)
+        return null;
+    const descriptor = await pinnedOperation(path, "open", [flags, 0o666]);
+    return {
+        readText: () => directory.request("read", [descriptor]),
+        close: () => directory.request("close", [descriptor]),
+    };
+}
+/**
+ * The real path of one entry of the pinned directory, resolved from the pinned inode.
+ *
+ * The answer is what the entry is *inside the pinned directory*: the caller learns whether the
+ * name is a plain file (the answer names the pinned path itself) or a link, and where that link
+ * goes, without resolving the mutable parent a second time in this process. The worker spells
+ * the resolution through `CWD_ANCHOR`, so the directory being renamed on disk changes the name
+ * in the answer without changing what it describes.
+ */
+export async function resolvePinned(path) {
+    const resolved = await pinnedOperation(path, "resolve");
+    return resolved === null ? null : await resolved;
+}

package/dist/internal.d.ts

@@ -46,6 +46,8 @@ 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";
 export * from "#src/native/client";

package/dist/internal.js

@@ -46,6 +46,8 @@ 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";
 export * from "#src/native/client";