@giovannijecha/jecode 0.7.0 → 0.7.2

package/dist/config.js

@@ -3,29 +3,24 @@ import * as path from "node:path";
 import { DEFAULT_COMPACTION_PERCENT, MAX_COMPACTION_PERCENT, MIN_COMPACTION_PERCENT, } from "./context/policy.js";
 import { EFFORTS, readSettings } from "./settings.js";
 import { parseOllamaEndpoint } from "./providers/ollama-endpoint.js";
-const FLAGS = [
+const VALUE_FLAGS = [
     "provider",
     "model",
     "ollama-host",
-    "reduced-motion",
     "effort",
     "max-tokens",
     "max-steps",
     "compaction-percent",
     "root",
+];
+const BOOLEAN_FLAGS = [
+    "reduced-motion",
     "auto-approve",
     "ephemeral",
 ];
+const FLAGS = [...VALUE_FLAGS, ...BOOLEAN_FLAGS];
 export function loadConfig(argv, saved = readSettings()) {
     const flags = parseFlags(argv);
-    // A flag nobody declared is a typo. Swallowed in silence it becomes a
-    // setting the user believes is on, and the run that ignores it looks like
-    // the feature is broken rather than misspelled.
-    for (const name of Object.keys(flags)) {
-        if (!FLAGS.includes(name)) {
-            throw new Error(`unknown flag --${name} (known: ${FLAGS.map((f) => `--${f}`).join(", ")})`);
-        }
-    }
     const providerId = pick(flags.provider, process.env.JECODE_PROVIDER, saved.provider ?? "anthropic");
     const ollamaHost = optional(flags["ollama-host"], process.env.OLLAMA_HOST, saved.ollamaHost);
     const effort = pick(flags.effort, process.env.JECODE_EFFORT, saved.effort ?? "high");
@@ -45,7 +40,9 @@ export function loadConfig(argv, saved = readSettings()) {
         maxSteps: toInt(pick(flags["max-steps"], process.env.JECODE_MAX_STEPS, String(saved.maxSteps ?? 40)), "max-steps"),
         compactionPercent: toPercent(pick(flags["compaction-percent"], process.env.JECODE_COMPACTION_PERCENT, String(saved.compactionPercent ?? DEFAULT_COMPACTION_PERCENT))),
         root: path.resolve(pick(flags.root, undefined, process.cwd())),
-        autoApprove: flags["auto-approve"] === "true" || process.env.JECODE_AUTO_APPROVE === "1",
+        autoApprove: flags["auto-approve"] === "true" ||
+            flags["auto-approve"] === "1" ||
+            process.env.JECODE_AUTO_APPROVE === "1",
         ephemeral: bool(flags.ephemeral, process.env.JECODE_EPHEMERAL, false),
     };
 }
@@ -85,27 +82,55 @@ function toPercent(value) {
     }
     return percent;
 }
-// Accepts --key value, --key=value, and bare --flag (which reads as "true").
+// Value flags accept --key value and --key=value. Boolean flags are bare or
+// take a real boolean value, so an accidental positional argument is never
+// swallowed as configuration.
 function parseFlags(argv) {
     const flags = {};
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
-        if (arg === undefined || !arg.startsWith("--"))
+        if (arg === undefined)
             continue;
+        if (!arg.startsWith("--"))
+            throw new Error(`unexpected argument "${arg}"`);
         const body = arg.slice(2);
         const eq = body.indexOf("=");
-        if (eq !== -1) {
-            flags[body.slice(0, eq)] = body.slice(eq + 1);
+        const name = eq === -1 ? body : body.slice(0, eq);
+        const inline = eq === -1 ? undefined : body.slice(eq + 1);
+        if (!FLAGS.includes(name)) {
+            throw new Error(`unknown flag --${name} (known: ${FLAGS.map((flag) => `--${flag}`).join(", ")})`);
+        }
+        if (BOOLEAN_FLAGS.includes(name)) {
+            if (inline === undefined) {
+                const next = argv[i + 1];
+                if (next !== undefined && ["true", "false", "1", "0"].includes(next)) {
+                    flags[name] = next;
+                    i++;
+                }
+                else {
+                    flags[name] = "true";
+                }
+            }
+            else if (["true", "false", "1", "0"].includes(inline)) {
+                flags[name] = inline;
+            }
+            else {
+                throw new Error(`--${name} must be true or false`);
+            }
             continue;
         }
-        const next = argv[i + 1];
-        if (next !== undefined && !next.startsWith("--")) {
-            flags[body] = next;
-            i++;
+        if (inline !== undefined) {
+            if (inline === "")
+                throw new Error(`--${name} requires a value`);
+            flags[name] = inline;
+            continue;
         }
-        else {
-            flags[body] = "true";
+        const next = argv[i + 1];
+        if (next === undefined || next.startsWith("--")) {
+            throw new Error(`--${name} requires a value`);
         }
+        flags[name] = next;
+        i++;
     }
     return flags;
 }

package/dist/context/manual.js

@@ -62,6 +62,7 @@ export async function compactSession(session, options = {}) {
         messages: active.messages,
         blocks: active.blocks,
         context: result.anchor,
+        ...(active.failure === undefined ? {} : { failure: active.failure }),
     }, active.settlement);
     await session.persistence?.checkpoint(next);
     session.conversation = next;

package/dist/conversation.js

@@ -5,6 +5,7 @@
 // project an older prefix before it is sent to a provider. Provider traffic
 // and live screen blocks remain prospective until a consistent checkpoint.
 import { projectContext, validContextAnchor } from "./context/projection.js";
+import { assertPersistableNode } from "./sessions/codec.js";
 export const CONVERSATION_LIMITS = Object.freeze({
     nodes: 1_024,
     messageCodeUnits: 8_388_608,
@@ -37,6 +38,7 @@ export class ConversationTree {
                 messages: node.messages,
                 blocks: node.blocks,
                 ...(node.context === undefined ? {} : { context: node.context }),
+                ...(node.failure === undefined ? {} : { failure: node.failure }),
             }, node.settlement);
             const restored = tree.activeNode;
             if (restored === undefined || restored.id !== node.id) {
@@ -92,6 +94,19 @@ export class ConversationTree {
         }
         return undefined;
     }
+    /** Select the newest turn that is safe to continue after a restart. */
+    latestResumable() {
+        let id = this.#activeNodeId;
+        while (id !== 0) {
+            const node = this.node(id);
+            if (node === undefined)
+                throw new Error("conversation path is incomplete");
+            if (node.settlement !== "checkpointed")
+                return this.select(id);
+            id = node.parentId;
+        }
+        return undefined;
+    }
     get history() {
         return this.#path().flatMap((node) => clone(node.messages));
     }
@@ -99,7 +114,12 @@ export class ConversationTree {
         return projectContext(this.#path());
     }
     get transcript() {
-        return this.#path().flatMap((node) => clone(node.blocks));
+        return this.#path().flatMap((node) => [
+            ...clone(node.blocks),
+            ...(node.failure === undefined
+                ? []
+                : [{ kind: "notice", text: node.failure.text, tone: node.failure.tone }]),
+        ]);
     }
     #append(draft, settlement) {
         if (this.#nodes.length >= CONVERSATION_LIMITS.nodes) {
@@ -115,8 +135,10 @@ export class ConversationTree {
             messages: draft.messages,
             blocks: settledBlocks(draft.blocks),
             ...(draft.context === undefined ? {} : { context: draft.context }),
+            ...(draft.failure === undefined ? {} : { failure: draft.failure }),
         });
         assertTurn(node);
+        assertPersistableNode(node);
         const nodes = [...this.#nodes, node];
         assertBounds(nodes);
         return new ConversationTree(nodes, node.id);
@@ -135,8 +157,10 @@ export class ConversationTree {
             messages: draft.messages,
             blocks: settledBlocks(draft.blocks),
             context: draft.context ?? current.context,
+            failure: draft.failure,
         });
         assertTurn(node);
+        assertPersistableNode(node);
         const nodes = [...this.#nodes];
         nodes[id - 1] = node;
         assertBounds(nodes);
@@ -163,6 +187,7 @@ function ownedNode(node) {
         messages: Object.freeze(clone(node.messages)),
         blocks: Object.freeze(clone(node.blocks)),
         ...(node.context === undefined ? {} : { context: Object.freeze({ ...node.context }) }),
+        ...(node.failure === undefined ? {} : { failure: Object.freeze({ ...node.failure }) }),
     });
 }
 function settledBlocks(blocks) {
@@ -174,6 +199,8 @@ function settledBlocks(blocks) {
             return [settled];
         }
         if (block.kind === "tool") {
+            if (block.tone === "pending")
+                return [];
             const { startedAt: _startedAt, expanded: _expanded, ...settled } = block;
             return [settled];
         }
@@ -185,16 +212,26 @@ function assertTurn(node) {
         !validNodeId(node.parentId) || node.parentId >= node.id ||
         !Number.isSafeInteger(node.revision) || node.revision < 1 ||
         node.createdAt.length === 0 || node.createdAt.length > 64 ||
-        (node.settlement !== "checkpointed" && node.settlement !== "completed") ||
+        !validSettlement(node.settlement) ||
         node.messages.length < 2 || node.messages[0]?.role !== "user" ||
         node.identity.providerId.length === 0 || node.identity.providerId.length > 128 ||
         node.identity.model.length === 0 || node.identity.model.length > 512 ||
         node.identity.effort.length === 0 || node.identity.effort.length > 32)
         throw new Error("turn checkpoint is invalid");
-    if (node.settlement === "completed" && node.messages.at(-1)?.role !== "assistant") {
-        throw new Error("a completed turn must end with an assistant message");
+    if (node.settlement !== "checkpointed" && node.messages.at(-1)?.role !== "assistant") {
+        throw new Error("a resumable turn must end with an assistant message");
+    }
+    const failed = node.settlement === "failed" || node.settlement === "interrupted";
+    if (failed !== (node.failure !== undefined) ||
+        (node.settlement === "failed" && node.failure?.tone !== "error") ||
+        (node.settlement === "interrupted" && node.failure?.tone !== "warn")) {
+        throw new Error("turn failure state is invalid");
     }
 }
+function validSettlement(value) {
+    return value === "checkpointed" || value === "completed" ||
+        value === "failed" || value === "interrupted";
+}
 function assertBounds(nodes) {
     let messageCodeUnits = 0;
     let transcriptCodeUnits = 0;

package/dist/credential-safety.js

@@ -40,17 +40,21 @@ export function credentialRedactor(source = process.env) {
             const ready = [];
             let at = 0;
             while (at < combined.length) {
+                const rest = combined.slice(at);
+                // A complete shorter credential can also be the prefix of a longer
+                // one. Hold that ambiguous suffix until the next chunk proves which
+                // value arrived, otherwise the longer credential leaks its tail.
+                if (rest.length < longest &&
+                    values.some((value) => value.length > rest.length && value.startsWith(rest))) {
+                    pending = rest;
+                    return ready.join("");
+                }
                 const complete = values.find((value) => combined.startsWith(value, at));
                 if (complete !== undefined) {
                     ready.push(REDACTED);
                     at += complete.length;
                     continue;
                 }
-                const rest = combined.slice(at);
-                if (rest.length < longest && values.some((value) => value.startsWith(rest))) {
-                    pending = rest;
-                    return ready.join("");
-                }
                 ready.push(combined[at]);
                 at++;
             }

package/dist/providers/anthropic-wire.js

@@ -1,5 +1,6 @@
 // Translation between the normalized vocabulary and the Anthropic wire shape.
 // Pure functions, no I/O — which is what makes them testable without a key.
+import { wireTokenCount } from "./wire-usage.js";
 export function toWireTool(tool) {
     return { name: tool.name, description: tool.description, input_schema: tool.input };
 }
@@ -70,10 +71,10 @@ function normalizeUsage(data) {
     if (usage === undefined)
         return undefined;
     return {
-        inputTokens: usage.input_tokens ?? 0,
-        outputTokens: usage.output_tokens ?? 0,
-        cachedInputTokens: usage.cache_read_input_tokens ?? 0,
-        cacheWriteInputTokens: usage.cache_creation_input_tokens ?? 0,
+        inputTokens: wireTokenCount(usage.input_tokens),
+        outputTokens: wireTokenCount(usage.output_tokens),
+        cachedInputTokens: wireTokenCount(usage.cache_read_input_tokens),
+        cacheWriteInputTokens: wireTokenCount(usage.cache_creation_input_tokens),
         reasoningTokens: 0,
     };
 }

package/dist/providers/ollama-wire.js

@@ -6,6 +6,7 @@
 // Chat Completions differs on two points that matter here — a tool result is a
 // message of its own with role "tool", not a block inside a user turn, and tool
 // arguments travel as a JSON string rather than an object.
+import { wireTokenCount } from "./wire-usage.js";
 export function toWireTool(tool) {
     return {
         type: "function",
@@ -83,8 +84,8 @@ function normalizeUsage(reply) {
     if (reply.usage === undefined)
         return undefined;
     return {
-        inputTokens: reply.usage.prompt_tokens ?? 0,
-        outputTokens: reply.usage.completion_tokens ?? 0,
+        inputTokens: wireTokenCount(reply.usage.prompt_tokens),
+        outputTokens: wireTokenCount(reply.usage.completion_tokens),
         cachedInputTokens: 0,
         cacheWriteInputTokens: 0,
         reasoningTokens: 0,

package/dist/providers/openai-wire.js

@@ -1,6 +1,7 @@
 // Translation between the normalized vocabulary and the OpenAI Responses wire
 // shape: a flat `input` list where tool calls and their outputs are top-level
 // items keyed by `call_id`, rather than blocks nested inside a message.
+import { wireTokenCount } from "./wire-usage.js";
 export function toWireTool(tool) {
     return {
         type: "function",
@@ -83,11 +84,11 @@ function normalizeUsage(data) {
     if (usage === undefined || usage === null)
         return undefined;
     return {
-        inputTokens: usage.input_tokens ?? 0,
-        outputTokens: usage.output_tokens ?? 0,
-        cachedInputTokens: usage.input_tokens_details?.cached_tokens ?? 0,
-        cacheWriteInputTokens: usage.input_tokens_details?.cache_write_tokens ?? 0,
-        reasoningTokens: usage.output_tokens_details?.reasoning_tokens ?? 0,
+        inputTokens: wireTokenCount(usage.input_tokens),
+        outputTokens: wireTokenCount(usage.output_tokens),
+        cachedInputTokens: wireTokenCount(usage.input_tokens_details?.cached_tokens),
+        cacheWriteInputTokens: wireTokenCount(usage.input_tokens_details?.cache_write_tokens),
+        reasoningTokens: wireTokenCount(usage.output_tokens_details?.reasoning_tokens),
     };
 }
 // Arguments arrive as a JSON string and models vary in how they escape it, so

package/dist/providers/wire-usage.js

@@ -0,0 +1,6 @@
+// Usage comes from remote JSON and eventually reaches the strict session
+// codec. Normalize it at the wire boundary so one malformed counter cannot
+// make an otherwise valid saved session unreadable.
+export function wireTokenCount(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : 0;
+}

package/dist/sessions/codec.js

@@ -1,17 +1,21 @@
 // Strict codecs for session files. Disk is an untrusted boundary even when
 // the directory is owner-only: every value is bounded and re-owned before it
 // can become conversation or provider input.
+import { Buffer } from "node:buffer";
 import { CONTEXT_LIMITS } from "../context/projection.js";
-export const SESSION_SCHEMA = 2;
+export const SESSION_SCHEMA = 3;
 export const SESSION_FILE_LIMITS = Object.freeze({
     text: 1_048_576,
+    metadataBytes: 64 * 1_024,
+    nodeBytes: 20 * 1_024 * 1_024,
     jsonDepth: 24,
     jsonNodes: 32_768,
     blocks: 8_192,
     details: 8_192,
 });
 export function encodeMeta(meta) {
-    return line(meta);
+    decodeMeta(meta);
+    return boundedLine(meta, SESSION_FILE_LIMITS.metadataBytes);
 }
 export function decodeMeta(value) {
     if (!record(value) || !keys(value, "createdAt,id,version,workspaceDigest,workspaceRoot")) {
@@ -32,7 +36,8 @@ export function decodeMeta(value) {
     });
 }
 export function encodeHead(head) {
-    return line(head);
+    decodeHead(head);
+    return boundedLine(head, SESSION_FILE_LIMITS.metadataBytes);
 }
 export function decodeHead(value) {
     if (!record(value) || !keys(value, "nodeId,parentId,revision,sequence,updatedAt,version")) {
@@ -55,7 +60,16 @@ export function decodeHead(value) {
     });
 }
 export function encodeNode(node, sequence, updatedAt) {
-    return line({
+    const envelope = nodeEnvelope(node, sequence, updatedAt);
+    decodeNode(envelope);
+    return boundedLine(envelope, SESSION_FILE_LIMITS.nodeBytes);
+}
+/** Enforce the exact current-disk boundary before a turn enters the tree. */
+export function assertPersistableNode(node) {
+    encodeNode(node, 1, node.createdAt);
+}
+function nodeEnvelope(node, sequence, updatedAt) {
+    return {
         version: SESSION_SCHEMA,
         sequence,
         updatedAt,
@@ -69,8 +83,9 @@ export function encodeNode(node, sequence, updatedAt) {
             messages: node.messages.map(messageRecord),
             blocks: node.blocks.flatMap(blockRecord),
             context: node.context ?? null,
+            failure: node.failure ?? null,
         },
-    });
+    };
 }
 export function decodeNode(value) {
     if (!record(value) || !keys(value, "node,sequence,updatedAt,version"))
@@ -82,7 +97,9 @@ export function decodeNode(value) {
     const raw = value["node"];
     const nodeKeys = version === 1
         ? "blocks,createdAt,id,identity,messages,parentId,revision,settlement"
-        : "blocks,context,createdAt,id,identity,messages,parentId,revision,settlement";
+        : version === 2
+            ? "blocks,context,createdAt,id,identity,messages,parentId,revision,settlement"
+            : "blocks,context,createdAt,failure,id,identity,messages,parentId,revision,settlement";
     if (!record(raw) || !keys(raw, nodeKeys)) {
         throw invalid();
     }
@@ -93,7 +110,7 @@ export function decodeNode(value) {
         !integer(raw["parentId"], 0) ||
         !integer(raw["revision"], 1) ||
         !timestamp(raw["createdAt"]) ||
-        (raw["settlement"] !== "checkpointed" && raw["settlement"] !== "completed") ||
+        !settlement(raw["settlement"], version) ||
         !record(identity) || !keys(identity, "effort,model,providerId") ||
         !bounded(identity["providerId"], 128) || !bounded(identity["model"], 512) ||
         !bounded(identity["effort"], 32) ||
@@ -103,6 +120,9 @@ export function decodeNode(value) {
     const context = version === 1
         ? undefined
         : contextFromRecord(raw["context"], raw["id"], messages.length);
+    const failure = version < 3
+        ? undefined
+        : failureFromRecord(raw["failure"], raw["settlement"]);
     const node = Object.freeze({
         id: raw["id"],
         parentId: raw["parentId"],
@@ -117,9 +137,25 @@ export function decodeNode(value) {
         messages: Object.freeze(messages.map(messageFromRecord)),
         blocks: Object.freeze(blocks.map(blockFromRecord)),
         ...(context === undefined ? {} : { context: Object.freeze(context) }),
+        ...(failure === undefined ? {} : { failure: Object.freeze(failure) }),
     });
     return Object.freeze({ sequence: value["sequence"], updatedAt: value["updatedAt"], node });
 }
+function failureFromRecord(value, settlement) {
+    const failed = settlement === "failed" || settlement === "interrupted";
+    if (value === null) {
+        if (failed)
+            throw invalid();
+        return undefined;
+    }
+    if (!failed || !record(value) || !keys(value, "text,tone"))
+        throw invalid();
+    if (!bounded(value["text"]) ||
+        (settlement === "failed" && value["tone"] !== "error") ||
+        (settlement === "interrupted" && value["tone"] !== "warn"))
+        throw invalid();
+    return { text: value["text"], tone: value["tone"] };
+}
 function contextFromRecord(value, ownerId, ownerMessages) {
     if (value === null)
         return undefined;
@@ -340,6 +376,12 @@ function jsonValue(value, budget, depth) {
 function line(value) {
     return `${JSON.stringify(value, null, 2)}\n`;
 }
+function boundedLine(value, maxBytes) {
+    const encoded = line(value);
+    if (Buffer.byteLength(encoded, "utf8") > maxBytes)
+        throw invalid();
+    return encoded;
+}
 function keys(value, expected) {
     return Object.keys(value).sort().join(",") === expected;
 }
@@ -356,7 +398,11 @@ function integer(value, minimum) {
     return typeof value === "number" && Number.isSafeInteger(value) && value >= minimum;
 }
 function schema(value) {
-    return value === 1 || value === SESSION_SCHEMA;
+    return value === 1 || value === 2 || value === SESSION_SCHEMA;
+}
+function settlement(value, version) {
+    return value === "checkpointed" || value === "completed" ||
+        (version >= 3 && (value === "failed" || value === "interrupted"));
 }
 function nullableInteger(value, minimum) {
     return value === null || integer(value, minimum);

package/dist/sessions/runtime.js

@@ -21,9 +21,9 @@ export class SessionPersistence {
         const lease = await store.claim(id);
         try {
             const snapshot = await store.load(id);
-            const conversation = snapshot.conversation.latestCompleted();
+            const conversation = snapshot.conversation.latestResumable();
             if (conversation === undefined)
-                throw new Error("session has no completed turn to resume");
+                throw new Error("session has no resumable turn");
             return Object.freeze({
                 conversation,
                 persistence: new SessionPersistence(store, id, lease),

package/dist/sessions/store.js

@@ -4,17 +4,17 @@
 // after that node is durable, so a crash leaves either the prior checkpoint or
 // one strictly recoverable mutation -- never an ambiguous partial history.
 import { createHash, randomUUID } from "node:crypto";
-import { chmod, lstat, mkdir, open, readFile, readdir, realpath, rename, rm, stat, } from "node:fs/promises";
+import { chmod, lstat, mkdir, open, opendir, readFile, readdir, realpath, rename, rm, stat, } from "node:fs/promises";
 import * as path from "node:path";
 import { atomicWrite } from "../atomic.js";
 import { CONVERSATION_LIMITS, ConversationTree } from "../conversation.js";
 import { userDataPath } from "../user-data.js";
-import { decodeHead, decodeMeta, decodeNode, encodeHead, encodeMeta, encodeNode, SESSION_SCHEMA, } from "./codec.js";
+import { decodeHead, decodeMeta, decodeNode, encodeHead, encodeMeta, encodeNode, SESSION_FILE_LIMITS, SESSION_SCHEMA, } from "./codec.js";
 import { leaseOwner, leaseToken, pidIsAlive, removeLease, sessionLease, } from "./lease.js";
 const DIRECTORY_MODE = 0o700;
 const FILE_MODE = 0o600;
-const MAX_CATALOG_SCAN = 128;
-const MAX_JSON_BYTES = 20 * 1024 * 1024;
+const MAX_CATALOG_ENTRIES = 4_096;
+const CATALOG_READ_CONCURRENCY = 8;
 const SESSION_NAME = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/;
 const NODE_NAME = /^(\d{6})\.json$/;
 const ATOMIC_NODE_TEMP = /^\.\d{6}\.json\.\d+\.[a-f0-9-]+\.tmp$/;
@@ -37,45 +37,45 @@ export class DurableSessionStore {
         if (!Number.isSafeInteger(limit) || limit < 1 || limit > 64) {
             throw new Error("session catalogue limit is invalid");
         }
-        const entries = await directoryEntries(this.#bucket);
-        const names = entries
-            .filter((entry) => entry.isDirectory() && SESSION_NAME.test(entry.name))
-            .map((entry) => entry.name)
-            .sort((left, right) => right.localeCompare(left))
-            .slice(0, MAX_CATALOG_SCAN);
+        const names = await catalogNames(this.#bucket);
         const catalog = [];
-        for (const id of names) {
-            try {
-                const snapshot = await this.load(id);
-                const conversation = snapshot.conversation.latestCompleted();
-                if (conversation === undefined)
-                    continue;
-                catalog.push({
-                    id,
-                    createdAt: snapshot.meta.createdAt,
-                    updatedAt: snapshot.head.updatedAt,
-                    turns: selectedTurnCount(conversation),
-                    preview: firstUserText(conversation),
-                    active: await this.#leaseIsActive(id),
-                });
-            }
-            catch {
-                // Corrupt or foreign data never becomes a resume candidate.
-            }
+        for (let start = 0; start < names.length; start += CATALOG_READ_CONCURRENCY) {
+            const batch = await Promise.all(names.slice(start, start + CATALOG_READ_CONCURRENCY)
+                .map(async (id) => {
+                try {
+                    const snapshot = await this.load(id);
+                    const conversation = snapshot.conversation.latestResumable();
+                    if (conversation === undefined)
+                        return undefined;
+                    return {
+                        id,
+                        createdAt: snapshot.meta.createdAt,
+                        updatedAt: snapshot.head.updatedAt,
+                        turns: selectedTurnCount(conversation),
+                        preview: firstUserText(conversation),
+                        active: await this.#leaseIsActive(id),
+                    };
+                }
+                catch {
+                    // Corrupt or foreign data never becomes a resume candidate.
+                    return undefined;
+                }
+            }));
+            catalog.push(...batch.filter((entry) => entry !== undefined));
         }
         return catalog
-            .sort((left, right) => right.updatedAt.localeCompare(left.updatedAt))
+            .sort((left, right) => right.updatedAt.localeCompare(left.updatedAt) || right.id.localeCompare(left.id))
             .slice(0, limit);
     }
     async load(id) {
         assertSessionId(id);
         const directory = this.#sessionDirectory(id);
         await assertDirectory(directory);
-        const meta = decodeMeta(await readJson(path.join(directory, "meta.json"), 64 * 1024));
+        const meta = decodeMeta(await readJson(path.join(directory, "meta.json"), SESSION_FILE_LIMITS.metadataBytes));
         if (meta.id !== id || meta.workspaceDigest !== this.workspaceDigest ||
             workspaceKey(meta.workspaceRoot) !== workspaceKey(this.workspaceRoot))
             throw new Error("session belongs to a different workspace");
-        let head = decodeHead(await readJson(path.join(directory, "head.json"), 64 * 1024));
+        let head = decodeHead(await readJson(path.join(directory, "head.json"), SESSION_FILE_LIMITS.metadataBytes));
         const stored = await readNodes(path.join(directory, "nodes"));
         const ahead = stored.filter((entry) => entry.sequence > head.sequence);
         if (ahead.some((entry) => entry.sequence !== head.sequence + 1) || ahead.length > 1) {
@@ -242,6 +242,28 @@ export class DurableSessionStore {
         return owner !== undefined && pidIsAlive(owner.pid);
     }
 }
+async function catalogNames(directory) {
+    try {
+        await assertDirectory(directory);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+    const names = [];
+    let entries = 0;
+    const handle = await opendir(directory);
+    for await (const entry of handle) {
+        entries++;
+        if (entries > MAX_CATALOG_ENTRIES) {
+            throw new Error(`session catalogue exceeds ${MAX_CATALOG_ENTRIES} entries`);
+        }
+        if (entry.isDirectory() && SESSION_NAME.test(entry.name))
+            names.push(entry.name);
+    }
+    return names.sort((left, right) => right.localeCompare(left));
+}
 function assertSharedNodes(previous, next, replacedId) {
     for (const node of previous.nodes) {
         if (node.id === replacedId)
@@ -278,7 +300,7 @@ async function readNodes(directory) {
         const id = Number(NODE_NAME.exec(name)?.[1]);
         if (id !== index + 1)
             throw new Error("session conversation nodes are not contiguous");
-        const decoded = decodeNode(await readJson(path.join(directory, name), MAX_JSON_BYTES));
+        const decoded = decodeNode(await readJson(path.join(directory, name), SESSION_FILE_LIMITS.nodeBytes));
         if (decoded.node.id !== id || sequences.has(decoded.sequence)) {
             throw new Error("session conversation node identity is invalid");
         }