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

package/dist/session/session-tool-support.js

@@ -4,12 +4,14 @@
  * buildCodingToolSupport takes, picks the embedder default protected-paths
  * policy, and enforces the sandbox floor for "full".
  */
+import { unsandboxedToolOptions } from "#src/coding-tools/coding-tool-extras";
 import { resolveSessionSandbox } from "#src/coding-tools/coding-tool-sandbox";
 import { buildCodingToolSupport } from "#src/coding-tools/coding-tool-support";
 import { UNIVERSAL_CODING_TOOLS } from "#src/coding-tools/universal-coding-tools";
 import { DEFAULT_SANDBOX_CONFIG } from "#src/config/schemas-sandbox";
 import { credentialsConfig } from "#src/infra/credentials-config";
 import { EMPTY_OWNED_PATHS_POLICY } from "#src/tools/owned-paths";
+import { renderProviderInstructions } from "#src/tools/provider-instructions";
 import { AgentSessionError } from "./agent-session-errors.js";
 /** The pipeline stage the facade's tool calls and asks carry. */
 export const SESSION_STAGE = "session";
@@ -59,10 +61,17 @@ export function defaultProtectedPaths(ownCredentials) {
     const credentialDir = ownCredentials ? undefined : configuredCredentialDir();
     return credentialDir === undefined ? base : { ...base, credentialDir };
 }
-/** The sandbox floor (spec 6.3): "ask", "full" and "review" need a usable sandbox unless gated + allowUnsandboxed. */
+/**
+ * The sandbox floor (spec 6.3): "ask", "full" and "review" need a usable sandbox,
+ * unless the session explicitly allows running without one — under `gated` (every
+ * call still goes to the person) or under `raw` (the person's own standing choice).
+ * The resolved state rides back beside the launcher, so the session can report
+ * what its commands actually run under.
+ */
 export async function resolveSessionLauncher(args) {
-    if (args.profile !== "full" && args.profile !== "ask" && args.profile !== "review")
-        return undefined;
+    if (args.profile !== "full" && args.profile !== "ask" && args.profile !== "review") {
+        return { launcher: undefined, sandbox: { kind: "disabled" } };
+    }
     const launcher = await resolveSessionSandbox({
         config: DEFAULT_SANDBOX_CONFIG,
         root: args.root,
@@ -71,16 +80,43 @@ export async function resolveSessionLauncher(args) {
         ownedPaths: EMPTY_OWNED_PATHS_POLICY,
     });
     if (launcher.state.kind === "available")
-        return launcher;
-    if (args.bashApproval === "gated" && args.allowUnsandboxed)
-        return undefined;
+        return { launcher, sandbox: launcher.state };
+    if (args.allowUnsandboxed)
+        return { launcher: undefined, sandbox: launcher.state };
     const reason = launcher.state.kind === "unavailable" ? launcher.state.reason : "the sandbox is disabled";
-    throw new AgentSessionError(`Profile "${args.profile}" needs a usable sandbox (${reason}). Pass bashApproval "gated" with allowUnsandboxed: true to run without one.`, "AGENT_SESSION_SANDBOX_UNAVAILABLE", { reason });
+    throw new AgentSessionError(`Profile "${args.profile}" needs a usable sandbox (${reason}). Pass allowUnsandboxed: true to run without one.`, "AGENT_SESSION_SANDBOX_UNAVAILABLE", { reason });
+}
+/**
+ * The `admits` predicate for `resolveProviderTools`: a tool `<id>__<local>` is
+ * admitted when `allowedTools` names it exactly or names `<id>__*`.
+ */
+export function providerAdmits(allowedTools) {
+    const allowed = new Set(allowedTools);
+    return (providerId, localName) => allowed.has(`${providerId}__${localName}`) || allowed.has(`${providerId}__*`);
+}
+/** The profile's built-ins narrowed by `allowedTools`; the scratchpad trio always survives. */
+function narrowBuiltIns(profileTools, allowedTools) {
+    if (allowedTools === undefined)
+        return profileTools;
+    const allowed = new Set(allowedTools);
+    return profileTools.filter((tool) => UNIVERSAL_CODING_TOOLS.includes(tool) || allowed.has(tool));
 }
 export function buildSessionToolSupport(args) {
-    const declared = declaredToolsFor(args.profile, args.protectedPaths);
-    const grants = grantsFor(declared);
-    const askRules = askRulesFor(declared, args.bashApproval, args.profile);
+    const profileTools = narrowBuiltIns(declaredToolsFor(args.profile, args.protectedPaths), args.allowedTools);
+    // CodingToolName enumerates built-ins, but the runtime also accepts provider names.
+    const declared = [
+        ...new Set([...profileTools, ...(args.providerTools?.tools.map((tool) => tool.name) ?? [])]),
+    ];
+    const grants = [...grantsFor(profileTools), ...(args.providerTools?.grants ?? [])];
+    // Only the "ask" profile puts a discovered, non-read-only tool to the person; "full" never asks.
+    const askRules = [
+        ...askRulesFor(profileTools, args.bashApproval, args.profile),
+        ...(args.profile === "ask" ? (args.providerTools?.askTools ?? []) : []).map((tool) => ({
+            tool: tool,
+            patterns: ["*"],
+        })),
+    ];
+    const providerInstructions = renderProviderInstructions(args.providerTools?.instructions ?? []);
     const support = buildCodingToolSupport({
         root: args.root,
         commandCwd: args.root,
@@ -88,6 +124,13 @@ export function buildSessionToolSupport(args) {
         sessionName: args.sessionName,
         declared,
         grants,
+        ...(args.providerTools !== undefined
+            ? {
+                extraTools: args.providerTools.tools,
+                providerIdByTool: args.providerTools.providerIdByTool,
+            }
+            : {}),
+        ...(providerInstructions !== undefined ? { providerInstructions } : {}),
         bashApproval: args.bashApproval,
         protectedPaths: args.protectedPaths,
         ownedPaths: EMPTY_OWNED_PATHS_POLICY,
@@ -95,6 +138,7 @@ export function buildSessionToolSupport(args) {
         ...(askRules.length > 0 ? { askRules } : {}),
         ...(args.interceptor !== undefined ? { interceptor: args.interceptor } : {}),
         ...(args.launcher !== undefined ? { launcher: args.launcher } : {}),
+        ...unsandboxedToolOptions(args),
     });
     // Unreachable while the scratchpad trio is always declared and granted; kept for the type.
     if (support === undefined) {

package/dist/session-store/index.d.ts

@@ -0,0 +1,3 @@
+export { LOCK_HEARTBEAT_MS, LOCK_STALE_MS } from "./session-lock.ts";
+export { defaultSessionsDir, SESSION_ID_PATTERN, SESSION_META_MODES, type SessionMeta, type SessionMetaMode, } from "./session-meta.ts";
+export { createSessionStorage, LIST_PAGE_SIZE, processAlive, type SessionListEntry, type SessionListPage, type SessionLockHolder, type SessionLockHolderState, type SessionStorage, type SessionStorageDeps, } from "./storage.ts";

package/dist/session-store/index.js

@@ -0,0 +1,3 @@
+export { LOCK_HEARTBEAT_MS, LOCK_STALE_MS } from "./session-lock.js";
+export { defaultSessionsDir, SESSION_ID_PATTERN, SESSION_META_MODES, } from "./session-meta.js";
+export { createSessionStorage, LIST_PAGE_SIZE, processAlive, } from "./storage.js";

package/dist/session-store/session-lock-guard.d.ts

@@ -0,0 +1,6 @@
+import { NaxError } from "#src/infra/nax-error";
+/** Distinguishes retryable mutex contention from mutation and filesystem failures. */
+export declare class SessionLockGuardBusy extends NaxError {
+    constructor();
+}
+export declare function withSessionLockGuard(path: string, mutate: () => void): void;

package/dist/session-store/session-lock-guard.js

@@ -0,0 +1,85 @@
+/** Short interprocess mutex for lock-file mutations, never stolen from a live process. */
+import { randomUUID } from "node:crypto";
+import { mkdirSync, readdirSync, renameSync, rmdirSync, unlinkSync, writeFileSync } from "node:fs";
+import { NaxError } from "#src/infra/nax-error";
+/** Distinguishes retryable mutex contention from mutation and filesystem failures. */
+export class SessionLockGuardBusy extends NaxError {
+    constructor() {
+        super("session in use by another process", "SESSION_LOCKED", { stage: "session-store" });
+    }
+}
+function codeOf(error) {
+    return typeof error === "object" && error !== null && "code" in error ? error.code : undefined;
+}
+function removeMarker(guard, marker) {
+    try {
+        unlinkSync(`${guard}/${marker}`);
+    }
+    catch (error) {
+        if (codeOf(error) !== "ENOENT")
+            throw error;
+    }
+    try {
+        // A contender can replace the now-empty directory. rmdir cannot remove its
+        // non-empty replacement; never recursively delete the shared guard path.
+        rmdirSync(guard);
+    }
+    catch (error) {
+        if (!["ENOENT", "ENOTEMPTY", "EEXIST"].includes(String(codeOf(error))))
+            throw error;
+    }
+}
+function reapDeadGuard(guard) {
+    let markers;
+    try {
+        markers = readdirSync(guard);
+    }
+    catch (error) {
+        if (codeOf(error) === "ENOENT")
+            return;
+        throw error;
+    }
+    for (const marker of markers) {
+        const pid = /^(\d+)\.[0-9a-f-]+$/.exec(marker)?.[1];
+        if (pid === undefined)
+            continue; // Unrecognized guards fail closed.
+        try {
+            process.kill(Number(pid), 0);
+        }
+        catch (error) {
+            // Only proven death permits recovery, never heartbeat age or EPERM.
+            // The unique marker path prevents two reapers from deleting a new owner.
+            if (codeOf(error) === "ESRCH")
+                removeMarker(guard, marker);
+        }
+    }
+}
+export function withSessionLockGuard(path, mutate) {
+    const guard = `${path}.guard`;
+    const marker = `${process.pid}.${randomUUID()}`;
+    const prepared = `${guard}.${marker}.tmp`;
+    mkdirSync(prepared);
+    try {
+        writeFileSync(`${prepared}/${marker}`, "", { flag: "wx" });
+        reapDeadGuard(guard);
+        try {
+            // Publish an already non-empty directory atomically. rename can replace
+            // an empty (released/reaped) guard, but never a live non-empty guard.
+            renameSync(prepared, guard);
+        }
+        catch (error) {
+            if (["ENOTEMPTY", "EEXIST"].includes(String(codeOf(error))))
+                throw new SessionLockGuardBusy();
+            throw error;
+        }
+        try {
+            mutate();
+        }
+        finally {
+            removeMarker(guard, marker);
+        }
+    }
+    finally {
+        removeMarker(prepared, marker);
+    }
+}

package/dist/session-store/session-lock.d.ts

@@ -0,0 +1,39 @@
+import { linkSync, renameSync, rmSync } from "node:fs";
+import { z } from "zod";
+import type { AgentLogger } from "#src/infra/index";
+export interface SessionStorageDeps {
+    readonly dir: string;
+    readonly pid: number;
+    readonly now: () => Date;
+    readonly logger: AgentLogger;
+    readonly setInterval?: (callback: () => void, ms: number) => ReturnType<typeof setInterval>;
+    readonly isAlive?: (pid: number) => boolean;
+}
+export type SessionLockHolderState = "live" | "stale" | "own";
+export declare const LOCK_HEARTBEAT_MS = 30000;
+export declare const LOCK_STALE_MS = 120000;
+declare const LockSchema: z.ZodUnion<readonly [z.ZodObject<{
+    pid: z.ZodNumber;
+    startedAt: z.ZodString;
+    nonce: z.ZodString;
+    heartbeatAt: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    pid: z.ZodNumber;
+    startedAt: z.ZodString;
+    nonce: z.ZodUndefined;
+    heartbeatAt: z.ZodUndefined;
+}, z.core.$strip>]>;
+type Body = z.infer<typeof LockSchema>;
+export declare const _lockDeps: {
+    rename: typeof renameSync;
+    link: typeof linkSync;
+    remove: typeof rmSync;
+};
+declare function read(path: string): {
+    text?: string;
+    body?: Body;
+};
+export { read as readSessionLock };
+/** Shared snapshot classification; ownership takes precedence over liveness. */
+export declare function holderState(body: Body, deps: SessionStorageDeps, isAlive: (pid: number) => boolean): SessionLockHolderState;
+export declare function acquireSessionLock(path: string, deps: SessionStorageDeps, isAlive: (pid: number) => boolean): () => Promise<void>;

package/dist/session-store/session-lock.js

@@ -0,0 +1,175 @@
+/** Local-filesystem ownership protocol. All lock mutations share an exclusive directory guard. */
+import { randomUUID } from "node:crypto";
+import { linkSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { setTimeout as sleep } from "node:timers/promises";
+import { z } from "zod";
+import { NaxError } from "#src/infra/nax-error";
+import { withSessionLockGuard as guarded, SessionLockGuardBusy } from "./session-lock-guard.js";
+export const LOCK_HEARTBEAT_MS = 30_000;
+export const LOCK_STALE_MS = 120_000;
+const LockSchema = z.union([
+    z.object({
+        pid: z.number().int().positive(),
+        startedAt: z.string(),
+        nonce: z.string(),
+        heartbeatAt: z.string().datetime(),
+    }),
+    z.object({
+        pid: z.number().int().positive(),
+        startedAt: z.string(),
+        nonce: z.undefined(),
+        heartbeatAt: z.undefined(),
+    }),
+]);
+export const _lockDeps = { rename: renameSync, link: linkSync, remove: rmSync };
+function codeOf(error) {
+    return typeof error === "object" && error !== null && "code" in error ? error.code : undefined;
+}
+function read(path) {
+    let text;
+    try {
+        text = readFileSync(path, "utf8");
+        const parsed = LockSchema.safeParse(JSON.parse(text));
+        return parsed.success ? { text, body: parsed.data } : { text };
+    }
+    catch {
+        return text === undefined ? {} : { text };
+    }
+}
+// Internal shared reader: snapshots and mutation decisions accept the same lock bodies.
+export { read as readSessionLock };
+function same(a, b) {
+    if (a.body?.nonce !== undefined)
+        return a.body.nonce === b.body?.nonce;
+    if (a.body !== undefined)
+        return b.body?.nonce === undefined && a.body.pid === b.body?.pid && a.body.startedAt === b.body.startedAt;
+    return a.text === b.text;
+}
+const refused = (pid) => new NaxError(`session in use by ${pid === undefined ? "another process" : `pid ${pid}`}`, "SESSION_LOCKED", {
+    stage: "session-store",
+    ...(pid !== undefined ? { pid } : {}),
+});
+function create(path, body) {
+    const temp = `${path}.${body.nonce}.tmp`;
+    try {
+        writeFileSync(temp, JSON.stringify(body), { flag: "wx" });
+        _lockDeps.link(temp, path);
+        return true;
+    }
+    catch (error) {
+        if (codeOf(error) === "EEXIST")
+            return false;
+        throw error;
+    }
+    finally {
+        rmSync(temp, { force: true });
+    }
+}
+/** Shared snapshot classification; ownership takes precedence over liveness. */
+export function holderState(body, deps, isAlive) {
+    if (body.pid === deps.pid)
+        return "own";
+    if (isAlive(body.pid) &&
+        (body.heartbeatAt === undefined || deps.now().getTime() - Date.parse(body.heartbeatAt) <= LOCK_STALE_MS)) {
+        return "live";
+    }
+    return "stale";
+}
+function takeover(path, body, deps, isAlive) {
+    const old = read(path);
+    const holder = old.body;
+    if (holder !== undefined && holderState(holder, deps, isAlive) === "live")
+        throw refused(holder.pid);
+    const stale = `${path}.${body.nonce}.stale`;
+    try {
+        _lockDeps.rename(path, stale);
+    }
+    catch (error) {
+        if (codeOf(error) !== "ENOENT")
+            throw error;
+        // A failed rename is not permission to overwrite the winner.
+        const raced = read(path);
+        if (raced.body !== undefined || !create(path, body))
+            throw refused(raced.body?.pid);
+        return;
+    }
+    if (!same(old, read(stale))) {
+        // Never discard another owner's renamed file if restoration is blocked.
+        try {
+            _lockDeps.link(stale, path);
+        }
+        catch (error) {
+            if (codeOf(error) !== "EEXIST")
+                throw error;
+            throw refused();
+        }
+        rmSync(stale, { force: true });
+        throw refused();
+    }
+    try {
+        deps.logger.info("session", "taking over a stale session lock", { pid: holder?.pid });
+        if (!create(path, body))
+            throw refused();
+    }
+    finally {
+        rmSync(stale, { force: true });
+    }
+}
+async function releaseOwnedLock(path, nonce) {
+    for (;;) {
+        try {
+            guarded(path, () => {
+                if (read(path).body?.nonce === nonce)
+                    _lockDeps.remove(path, { force: true });
+            });
+            return;
+        }
+        catch (error) {
+            if (!(error instanceof SessionLockGuardBusy))
+                throw error;
+            // Release owns cleanup until it can check the nonce under the guard.
+            // Yield to the holder rather than abandoning a fresh lock on contention.
+            // Unref'd: a deferred release after bounded shutdown never keeps the process alive.
+            await sleep(10, undefined, { ref: false });
+        }
+    }
+}
+export function acquireSessionLock(path, deps, isAlive) {
+    const stamp = deps.now().toISOString();
+    const body = { pid: deps.pid, startedAt: stamp, nonce: randomUUID(), heartbeatAt: stamp };
+    guarded(path, () => {
+        if (!create(path, body))
+            takeover(path, body, deps, isAlive);
+    });
+    const timer = (deps.setInterval ?? setInterval)(() => {
+        const temp = `${path}.${body.nonce}.tmp`;
+        try {
+            guarded(path, () => {
+                if (read(path).body?.nonce !== body.nonce) {
+                    clearInterval(timer);
+                    return;
+                }
+                body.heartbeatAt = deps.now().toISOString();
+                writeFileSync(temp, JSON.stringify(body));
+                _lockDeps.rename(temp, path);
+            });
+        }
+        catch (error) {
+            deps.logger.warn("session", "lock heartbeat failed", { path, error: String(error) });
+        }
+        finally {
+            rmSync(temp, { force: true });
+        }
+    }, LOCK_HEARTBEAT_MS);
+    timer.unref();
+    return async () => {
+        try {
+            // The heartbeat stays live while release waits out contention.
+            await releaseOwnedLock(path, body.nonce);
+        }
+        finally {
+            // A terminal release failure must let the lock age into stale recovery.
+            clearInterval(timer);
+        }
+    };
+}

package/dist/session-store/session-meta.d.ts

@@ -0,0 +1,27 @@
+import { z } from "zod";
+export declare const SESSION_META_MODES: readonly ["none", "read", "ask", "full"];
+export type SessionMetaMode = (typeof SESSION_META_MODES)[number];
+export declare const SESSION_ID_PATTERN: RegExp;
+export declare function defaultSessionsDir(configDir: string): string;
+export declare const MetaSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    sessionId: z.ZodString;
+    cwd: z.ZodString;
+    mode: z.ZodEnum<{
+        ask: "ask";
+        full: "full";
+        none: "none";
+        read: "read";
+    }>;
+    model: z.ZodString;
+    bashApproval: z.ZodEnum<{
+        escalate: "escalate";
+        gated: "gated";
+        raw: "raw";
+    }>;
+    title: z.ZodNullable<z.ZodString>;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodNullable<z.ZodString>;
+    costUsd: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type SessionMeta = Readonly<z.infer<typeof MetaSchema>>;

package/dist/session-store/session-meta.js

@@ -0,0 +1,20 @@
+import { join } from "node:path";
+import { z } from "zod";
+import { BashApprovalModeSchema } from "#src/config/bash-approval";
+export const SESSION_META_MODES = ["none", "read", "ask", "full"];
+export const SESSION_ID_PATTERN = /^[A-Za-z0-9_-]{1,128}$/;
+export function defaultSessionsDir(configDir) {
+    return join(configDir, ".agent-server", "sessions");
+}
+export const MetaSchema = z.object({
+    schemaVersion: z.literal(1),
+    sessionId: z.string().min(1),
+    cwd: z.string().min(1),
+    mode: z.enum(SESSION_META_MODES),
+    model: z.string().min(1),
+    bashApproval: BashApprovalModeSchema,
+    title: z.string().nullable(),
+    createdAt: z.string(),
+    updatedAt: z.string().nullable(),
+    costUsd: z.number().optional(),
+});

package/dist/session-store/storage.d.ts

@@ -0,0 +1,39 @@
+import { type SessionLockHolderState, type SessionStorageDeps } from "./session-lock.ts";
+import { type SessionMeta } from "./session-meta.ts";
+export type { SessionLockHolderState, SessionStorageDeps } from "./session-lock.ts";
+export interface SessionLockHolder {
+    readonly pid: number;
+    readonly startedAt: string;
+    readonly heartbeatAt: string | null;
+    readonly state: SessionLockHolderState;
+}
+export { LOCK_HEARTBEAT_MS, LOCK_STALE_MS } from "./session-lock.ts";
+export declare const LIST_PAGE_SIZE = 50;
+export interface SessionListEntry {
+    readonly sessionId: string;
+    readonly cwd: string;
+    readonly title: string | null;
+    readonly updatedAt: string;
+}
+export interface SessionListPage {
+    sessions: SessionListEntry[];
+    nextCursor?: string;
+}
+export interface SessionStorage {
+    readonly dir: string;
+    readMeta(sessionId: string): Promise<SessionMeta | null>;
+    writeMeta(meta: SessionMeta): Promise<void>;
+    hasMeta(sessionId: string): Promise<boolean>;
+    removeMeta(sessionId: string): Promise<void>;
+    /** Resolves to the release function; refuses with SESSION_LOCKED when another live process holds it. */
+    acquireLock(sessionId: string): Promise<() => Promise<void>>;
+    /** Unguarded, read-only snapshot; only acquireLock decides ownership. A concurrent rename may yield null. */
+    readLockHolder(sessionId: string): Promise<SessionLockHolder | null>;
+    list(query: {
+        readonly cwd?: string | null;
+        readonly cursor?: string | null;
+    }): Promise<SessionListPage>;
+}
+/** Signal 0 checks existence only. EPERM means the process exists under another user. */
+export declare function processAlive(pid: number): boolean;
+export declare function createSessionStorage(deps: SessionStorageDeps): SessionStorage;

package/dist/session-store/storage.js

@@ -0,0 +1,164 @@
+/**
+ * Session files beside the S3 transcript (S5 spec §5.1): `<id>.session.json`
+ * metadata, written as a temp file then renamed, and `<id>.lock`, created
+ * exclusively. Nonce-owned locks use heartbeats to detect stale live pids;
+ * legacy locks remain pid-based. Listing scans the metadata files.
+ * Files that cannot be read are never rewritten or deleted here.
+ */
+import { mkdir, mkdtemp, readdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { errorMessage } from "#src/infra/errors";
+import { NaxError } from "#src/infra/nax-error";
+import { acquireSessionLock, holderState, readSessionLock, } from "./session-lock.js";
+import { MetaSchema } from "./session-meta.js";
+export { LOCK_HEARTBEAT_MS, LOCK_STALE_MS } from "./session-lock.js";
+export const LIST_PAGE_SIZE = 50;
+const META_SUFFIX = ".session.json";
+function codeOf(error) {
+    return typeof error === "object" && error !== null && "code" in error && typeof error.code === "string"
+        ? error.code
+        : undefined;
+}
+/** Signal 0 checks existence only. EPERM means the process exists under another user. */
+export function processAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return codeOf(error) === "EPERM";
+    }
+}
+function unreadable(sessionId, reason) {
+    return new NaxError(`session metadata for "${sessionId}" is unreadable: ${reason}`, "SESSION_META_UNREADABLE", {
+        stage: "session-store",
+        sessionId,
+    });
+}
+function encodeCursor(offset) {
+    return Buffer.from(String(offset), "utf8").toString("base64");
+}
+function decodeCursor(cursor) {
+    if (cursor === undefined || cursor === null || cursor === "")
+        return 0;
+    const text = Buffer.from(cursor, "base64").toString("utf8");
+    const offset = Number(text);
+    if (!/^\d+$/.test(text) || !Number.isSafeInteger(offset))
+        throw new NaxError("invalid cursor", "SESSION_LIST_CURSOR_INVALID", { stage: "session-store" });
+    return offset;
+}
+const sortKey = (meta) => meta.updatedAt ?? meta.createdAt;
+function infoOf(meta) {
+    return { sessionId: meta.sessionId, cwd: meta.cwd, title: meta.title, updatedAt: sortKey(meta) };
+}
+export function createSessionStorage(deps) {
+    const isAlive = deps.isAlive ?? processAlive;
+    const metaPath = (id) => join(deps.dir, `${id}${META_SUFFIX}`);
+    const lockPath = (id) => join(deps.dir, `${id}.lock`);
+    async function readMeta(sessionId) {
+        let text;
+        try {
+            text = await readFile(metaPath(sessionId), "utf8");
+        }
+        catch (error) {
+            if (codeOf(error) === "ENOENT")
+                return null;
+            throw unreadable(sessionId, errorMessage(error));
+        }
+        let json;
+        try {
+            json = JSON.parse(text);
+        }
+        catch {
+            throw unreadable(sessionId, "invalid JSON");
+        }
+        const version = typeof json === "object" && json !== null && "schemaVersion" in json ? json.schemaVersion : undefined;
+        if (version !== 1)
+            throw unreadable(sessionId, `schemaVersion ${String(version)}; this build reads 1`);
+        const parsed = MetaSchema.safeParse(json);
+        if (!parsed.success)
+            throw unreadable(sessionId, parsed.error.issues[0]?.message ?? "bad shape");
+        return parsed.data;
+    }
+    async function acquireLock(sessionId) {
+        await mkdir(deps.dir, { recursive: true });
+        return acquireSessionLock(lockPath(sessionId), deps, isAlive);
+    }
+    async function list(query) {
+        const offset = decodeCursor(query.cursor);
+        let names;
+        try {
+            names = await readdir(deps.dir);
+        }
+        catch (error) {
+            if (codeOf(error) === "ENOENT")
+                return { sessions: [] };
+            throw error;
+        }
+        const metas = [];
+        for (const name of names.filter((n) => n.endsWith(META_SUFFIX))) {
+            try {
+                const meta = await readMeta(name.slice(0, -META_SUFFIX.length));
+                if (meta !== null)
+                    metas.push(meta);
+            }
+            catch (error) {
+                deps.logger.warn("session", "skipping unreadable session metadata", { file: name, error: errorMessage(error) });
+            }
+        }
+        const matching = metas
+            .filter((meta) => query.cwd === undefined || query.cwd === null || meta.cwd === query.cwd)
+            .sort((a, b) => sortKey(b).localeCompare(sortKey(a)));
+        const end = offset + LIST_PAGE_SIZE;
+        return {
+            sessions: matching.slice(offset, end).map(infoOf),
+            ...(end < matching.length ? { nextCursor: encodeCursor(end) } : {}),
+        };
+    }
+    return {
+        dir: deps.dir,
+        readMeta,
+        async writeMeta(meta) {
+            await mkdir(deps.dir, { recursive: true });
+            const path = metaPath(meta.sessionId);
+            // An exclusively created directory owns this write's temp file, even when
+            // another storage instance in the same process writes the same session.
+            const tempDir = await mkdtemp(`${path}.${deps.pid}.`);
+            try {
+                const temp = join(tempDir, "metadata.tmp");
+                await writeFile(temp, `${JSON.stringify(meta, null, 2)}\n`);
+                await rename(temp, path);
+            }
+            finally {
+                await rm(tempDir, { recursive: true, force: true });
+            }
+        },
+        async hasMeta(sessionId) {
+            try {
+                await stat(metaPath(sessionId));
+                return true;
+            }
+            catch (error) {
+                if (codeOf(error) === "ENOENT")
+                    return false;
+                throw error;
+            }
+        },
+        async removeMeta(sessionId) {
+            await rm(metaPath(sessionId), { force: true });
+        },
+        acquireLock,
+        async readLockHolder(sessionId) {
+            const { body } = readSessionLock(lockPath(sessionId));
+            if (body === undefined)
+                return null;
+            return {
+                pid: body.pid,
+                startedAt: body.startedAt,
+                heartbeatAt: body.heartbeatAt ?? null,
+                state: holderState(body, deps, isAlive),
+            };
+        },
+        list,
+    };
+}