@cjhyy/code-shell-core 0.8.8 → 0.8.10

package/dist/protocol/chat-session-manager.d.ts

@@ -95,6 +95,15 @@ export declare class ChatSessionManager {
      * the values so a callback that closes a session can't perturb the walk.
      */
     forEachSession(fn: (s: ChatSession) => void): void;
+    /** First live Engine for legacy fallbacks that genuinely accept any owner. */
+    getAnyLiveEngine(): Engine | undefined;
+    /**
+     * Build a detached Engine for global model/provider/settings queries. Keeping
+     * this seam on the manager avoids protocol code reaching into its private
+     * factory and, importantly, avoids borrowing project-local state from an
+     * arbitrary live session.
+     */
+    createDetachedEngine(slice?: Partial<EngineConfigSlice>): Engine;
     /** Snapshot-safe, read-only source shared by query("sessions") and Pet projection. */
     getLiveSessionSnapshot(): LiveChatSessionSnapshot;
     close(sessionId: string): Promise<void>;

package/dist/protocol/chat-session-manager.js

@@ -164,10 +164,26 @@ export class ChatSessionManager {
         for (const s of [...this.sessions.values()])
             fn(s);
     }
+    /** First live Engine for legacy fallbacks that genuinely accept any owner. */
+    getAnyLiveEngine() {
+        return this.sessions.values().next().value?.engine;
+    }
+    /**
+     * Build a detached Engine for global model/provider/settings queries. Keeping
+     * this seam on the manager avoids protocol code reaching into its private
+     * factory and, importantly, avoids borrowing project-local state from an
+     * arbitrary live session.
+     */
+    createDetachedEngine(slice = {}) {
+        return this.factory(slice);
+    }
     /** Snapshot-safe, read-only source shared by query("sessions") and Pet projection. */
     getLiveSessionSnapshot() {
         const sessions = [];
         this.forEachSession((session) => {
+            const sessionManager = this.engineSessionManager(session.engine);
+            if (sessionManager?.isEphemeralSession?.(session.id))
+                return;
             sessions.push({
                 sessionId: session.id,
                 busy: session.isBusy(),
@@ -280,6 +296,12 @@ export class ChatSessionManager {
     sweepIdle() {
         const cutoff = Date.now() - this.idleTtlMs;
         for (const [id, s] of [...this.sessions]) {
+            // Quick Chat transcripts are process-local by design. Closing one from
+            // the generic idle sweeper destroys its inherited context while the
+            // renderer still owns (and displays) the panel. Its explicit claim/
+            // panel lifecycle is the sole authority that may close it.
+            if (id.startsWith("qchat-"))
+                continue;
             if (s.lastActivityAt >= cutoff)
                 continue;
             if (s.isBusy())

package/dist/protocol/chat-session.d.ts

@@ -33,6 +33,11 @@ export interface TurnOpts {
     injected?: boolean;
     /** Stable id for this user-intent; forwarded to Engine.run for idempotency. */
     clientMessageId?: string;
+    /** Archive history before this turn at the engine's pre-model safe point. */
+    archiveBeforeCurrentTurn?: {
+        fromClientMessageId?: string;
+        segmentId?: string;
+    };
     /** Structured input attachments for this turn. */
     attachments?: InputAttachmentMeta[];
     /** Permission mode snapshot for this queued turn only. */

package/dist/protocol/chat-session.js

@@ -290,6 +290,7 @@ export class ChatSession {
                 goal: next.opts.goal,
                 injected: next.opts.injected,
                 clientMessageId: next.opts.clientMessageId,
+                archiveBeforeCurrentTurn: next.opts.archiveBeforeCurrentTurn,
                 attachments: next.opts.attachments,
                 permissionMode: next.opts.permissionMode,
                 planMode: next.opts.planMode,

package/dist/protocol/server.d.ts

@@ -375,6 +375,8 @@ export declare class AgentServer {
      * selector) can query models/providers without requiring a chat session first.
      */
     private anyEngine;
+    /** Neutral engine for truly global queries; never inherits a live project's cwd or policy. */
+    private detachedQueryEngine;
     close(): void;
     /** Release only this transport's approval ownership. Safe on socket close
      * even when the ChatSessionManager is shared by other TCP connections. */

package/dist/protocol/server.js

@@ -58,10 +58,60 @@ function runInputError(params) {
     if (params.injected !== undefined && typeof params.injected !== "boolean") {
         return "injected must be a boolean";
     }
+    if (params.quickChatClaimId !== undefined &&
+        (typeof params.quickChatClaimId !== "string" || params.quickChatClaimId.length === 0)) {
+        return "quickChatClaimId must be a non-empty string";
+    }
+    if (params.archiveBeforeCurrentTurn !== undefined) {
+        const archive = params.archiveBeforeCurrentTurn;
+        if (!archive || typeof archive !== "object" || Array.isArray(archive)) {
+            return "archiveBeforeCurrentTurn must be an object";
+        }
+        if (typeof params.clientMessageId !== "string" || params.clientMessageId.length === 0) {
+            return "archiveBeforeCurrentTurn requires clientMessageId";
+        }
+        for (const [field, value] of [
+            ["fromClientMessageId", archive.fromClientMessageId],
+            ["segmentId", archive.segmentId],
+        ]) {
+            if (value !== undefined &&
+                (typeof value !== "string" ||
+                    value.length === 0 ||
+                    value.length > 256 ||
+                    /[\r\n]/.test(value))) {
+                return `archiveBeforeCurrentTurn.${field} must be a bounded non-empty string`;
+            }
+        }
+    }
     if (params.behaviorMode !== undefined &&
         (typeof params.behaviorMode !== "string" || params.behaviorMode.length === 0)) {
         return `invalid behavior mode: ${String(params.behaviorMode)}`;
     }
+    for (const [field, value, maxItems] of [
+        ["toolAllowlist", params.toolAllowlist, 32],
+        ["skillAllowlist", params.skillAllowlist, 8],
+    ]) {
+        if (value === undefined)
+            continue;
+        if (!Array.isArray(value) ||
+            value.length > maxItems ||
+            value.some((name) => typeof name !== "string" || name.length === 0 || name.length > 128 || /[\r\n]/.test(name))) {
+            return `${field} must be an array of at most ${maxItems} bounded names`;
+        }
+    }
+    if (params.ephemeral !== undefined && typeof params.ephemeral !== "boolean") {
+        return "ephemeral must be a boolean";
+    }
+    if (params.maxTurns !== undefined &&
+        (!Number.isInteger(params.maxTurns) || params.maxTurns < 1 || params.maxTurns > 30)) {
+        return "maxTurns must be an integer from 1 to 30";
+    }
+    if (params.maxContextTokens !== undefined &&
+        (!Number.isInteger(params.maxContextTokens) ||
+            params.maxContextTokens < 4_096 ||
+            params.maxContextTokens > 131_072)) {
+        return "maxContextTokens must be an integer from 4096 to 131072";
+    }
     if (params.kind !== undefined && (typeof params.kind !== "string" || params.kind.length === 0)) {
         return `invalid session kind: ${String(params.kind)}`;
     }
@@ -75,6 +125,20 @@ function runInputError(params) {
     // extension-owned param shapes) lives in ExtensionModule.validateRunParams.
     return null;
 }
+function goalExtensionInputError(params) {
+    const fields = ["addTurns", "addTokenBudget", "addTimeBudgetMs", "addStopBlocks"];
+    let supplied = false;
+    for (const field of fields) {
+        const value = params[field];
+        if (value === undefined)
+            continue;
+        supplied = true;
+        if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0) {
+            return `${field} must be a positive safe integer`;
+        }
+    }
+    return supplied ? null : "at least one goal extension is required";
+}
 const COMPACT_STREAM_STRATEGIES = new Set([
     "micro",
     "summary",
@@ -1080,6 +1144,8 @@ export class AgentServer {
         const sessionConfig = {
             cwd: params.cwd,
             projectTrusted: params.projectTrusted,
+            maxTurns: params.maxTurns,
+            maxContextTokens: params.maxContextTokens,
             goal: typeof params.goal === "string" || (params.goal != null && typeof params.goal === "object")
                 ? params.goal
                 : undefined,
@@ -1160,9 +1226,13 @@ export class AgentServer {
                     this.notify(Methods.StreamEvent, { sessionId: sid, event });
                 },
                 clientMessageId: typeof params.clientMessageId === "string" ? params.clientMessageId : undefined,
+                archiveBeforeCurrentTurn: params.archiveBeforeCurrentTurn,
                 permissionMode: params.permissionMode,
                 planMode: params.planMode,
                 behaviorMode: params.behaviorMode,
+                toolAllowlist: params.toolAllowlist,
+                skillAllowlist: params.skillAllowlist,
+                ephemeral: params.ephemeral,
                 profileParams: params.profileParams,
                 workspaceProfile: params.workspaceProfile,
                 sessionBrief: params.sessionBrief,
@@ -1290,6 +1360,9 @@ export class AgentServer {
                 permissionMode: params.permissionMode,
                 planMode: params.planMode,
                 behaviorMode: params.behaviorMode,
+                toolAllowlist: params.toolAllowlist,
+                skillAllowlist: params.skillAllowlist,
+                ephemeral: params.ephemeral,
                 profileParams: params.profileParams,
                 workspaceProfile: params.workspaceProfile,
                 sessionBrief: params.sessionBrief,
@@ -1435,7 +1508,17 @@ export class AgentServer {
      * limits, or an error if no session / no active run.
      */
     handleGoalExtend(req) {
-        const params = (req.params ?? {});
+        const rawParams = req.params;
+        if (!rawParams || typeof rawParams !== "object" || Array.isArray(rawParams)) {
+            this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, "goal extension params are required"));
+            return;
+        }
+        const inputError = goalExtensionInputError(rawParams);
+        if (inputError) {
+            this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, inputError));
+            return;
+        }
+        const params = rawParams;
         const ext = {
             addTurns: params.addTurns,
             addTokenBudget: params.addTokenBudget,
@@ -2099,7 +2182,7 @@ export class AgentServer {
                 resolved = session.engine;
             }
             else {
-                resolved = this.anyEngine();
+                resolved ??= this.anyEngine();
             }
         }
         if (!resolved) {
@@ -2110,16 +2193,16 @@ export class AgentServer {
     }
     async handleQuery(req) {
         const params = (req.params ?? {});
-        // For query operations we prefer the legacyEngine; if absent borrow any
-        // session engine from the manager (model pool, settings are shared).
-        const engine = this.legacyEngine ?? this.anyEngine();
+        // Global queries use a detached manager-owned engine. Session-scoped cases
+        // below resolve the exact owner from params.sessionId instead of borrowing
+        // whichever live project's engine happens to be first in a Map.
+        const engine = this.legacyEngine ?? this.detachedQueryEngine();
         switch (params.type) {
             case "tools": {
-                if (!engine) {
-                    this.transport.send(createErrorResponse(req.id, ErrorCodes.InternalError, "No engine available for tools query"));
+                const toolsEngine = await this.resolveEngineForSessionQuery(req, params.sessionId, engine, "tools");
+                if (!toolsEngine)
                     return;
-                }
-                const registry = engine.getToolRegistry();
+                const registry = toolsEngine.getToolRegistry();
                 const tools = typeof registry.listToolsDetailed === "function"
                     ? registry
                         .listToolsDetailed()
@@ -2146,16 +2229,15 @@ export class AgentServer {
                 break;
             }
             case "config": {
-                if (!engine) {
-                    this.transport.send(createErrorResponse(req.id, ErrorCodes.InternalError, "No engine available for config query"));
+                const configEngine = await this.resolveEngineForSessionQuery(req, params.sessionId, engine, "config");
+                if (!configEngine)
                     return;
-                }
-                const config = engine.getConfig();
+                const config = configEngine.getConfig();
                 this.transport.send(createResponse(req.id, {
                     type: "config",
                     data: {
                         permissionMode: config.permissionMode ?? "default",
-                        planMode: engine.planMode ?? false,
+                        planMode: configEngine.planMode ?? false,
                         preset: config.preset,
                         model: config.llm.model,
                         cwd: config.cwd,
@@ -2165,21 +2247,20 @@ export class AgentServer {
                         llm: redactLlmConfig(config.llm),
                         // Resolved feature flags (defaults merged with settings overlay)
                         // so the /features command can list current state.
-                        featureFlags: engine.getFeatureFlags(),
+                        featureFlags: configEngine.getFeatureFlags(),
                         // Effective permission rules so /permissions can list them (TODO 5.1).
-                        permissionRules: engine.getPermissionRules(),
+                        permissionRules: configEngine.getPermissionRules(),
                     },
                 }));
                 break;
             }
             case "session_detail": {
-                if (!engine) {
-                    this.transport.send(createErrorResponse(req.id, ErrorCodes.InternalError, "No engine available for session_detail query"));
-                    return;
-                }
                 if (params.sessionId) {
+                    const detailEngine = await this.resolveEngineForSessionQuery(req, params.sessionId, engine, "session_detail");
+                    if (!detailEngine)
+                        return;
                     try {
-                        const bundle = engine.getSessionManager().resume(params.sessionId);
+                        const bundle = detailEngine.getSessionManager().resume(params.sessionId);
                         const data = {
                             state: bundle.state,
                             transcript: bundle.transcript.getEvents(),
@@ -3127,16 +3208,18 @@ export class AgentServer {
     anyEngine() {
         if (!this.chatManager)
             return null;
-        const sessions = this.chatManager.sessions;
-        const first = sessions.values().next().value;
-        if (first)
-            return first.engine;
+        const live = this.chatManager.getAnyLiveEngine();
+        if (live)
+            return live;
+        return this.detachedQueryEngine();
+    }
+    /** Neutral engine for truly global queries; never inherits a live project's cwd or policy. */
+    detachedQueryEngine() {
+        if (!this.chatManager)
+            return null;
         if (this.globalQueryEngine)
             return this.globalQueryEngine;
-        const factory = this.chatManager.factory;
-        if (typeof factory !== "function")
-            return null;
-        this.globalQueryEngine = factory({});
+        this.globalQueryEngine = this.chatManager.createDetachedEngine();
         return this.globalQueryEngine;
     }
     // ─── Lifecycle ──────────────────────────────────────────────────

package/dist/protocol/types.d.ts

@@ -80,6 +80,16 @@ export interface RunParams {
     attachments?: InputAttachmentMeta[];
     /** Stable id for the user's submit intent; duplicate ids are idempotent. */
     clientMessageId?: string;
+    /**
+     * Archive the preceding history after this message is durably appended and
+     * before its first model call. `clientMessageId` is the exclusive end anchor.
+     */
+    archiveBeforeCurrentTurn?: {
+        fromClientMessageId?: string;
+        segmentId?: string;
+    };
+    /** Desktop host ownership generation for process-local Quick Chat runs. */
+    quickChatClaimId?: string;
     /**
      * Host-generated system reminder. Persisted with an injected marker so disk
      * transcript readers hide it as a user bubble while retaining the assistant reply.
@@ -116,6 +126,16 @@ export interface RunParams {
     planMode?: boolean;
     /** Named behavior profile for a product-specific per-run interaction mode. */
     behaviorMode?: RunBehaviorMode;
+    /** Host-authorized per-run hard tool allowlist. Empty means no tools. */
+    toolAllowlist?: string[];
+    /** Host-authorized per-run hard Skill allowlist. Empty means no Skills. */
+    skillAllowlist?: string[];
+    /** Keep a fresh run Session process-local and out of normal Session pickers. */
+    ephemeral?: boolean;
+    /** Optional fresh-session turn ceiling used by bounded host Tasks. */
+    maxTurns?: number;
+    /** Optional fresh-session context ceiling used by bounded host Tasks. */
+    maxContextTokens?: number;
     /**
      * Generic per-run parameters consumed by the active behavior profile
      * (delivered as non-durable run context; never appended to the task or

package/dist/run/FileRunStore.d.ts

@@ -18,6 +18,8 @@ export declare class FileRunStore implements RunStore {
     private ensureRunDir;
     private writeJson;
     private readJson;
+    private assertRealDirectory;
+    private assertSafeFileTarget;
     /** Serializes concurrent JSONL appends per file path. */
     private readonly appendLocks;
     private appendJsonl;

package/dist/run/FileRunStore.js

@@ -9,34 +9,54 @@
  *     approvals/<id>.json   — approval records
  *     artifacts/refs.jsonl  — artifact reference log
  */
-import { mkdirSync, existsSync, readFileSync, writeFileSync, appendFileSync, readdirSync, renameSync, rmSync, } from "node:fs";
-import { join } from "node:path";
+import { mkdirSync, existsSync, readFileSync, writeFileSync, appendFileSync, closeSync, chmodSync, constants, fchmodSync, readdirSync, fstatSync, openSync, readSync, renameSync, rmSync, lstatSync, } from "node:fs";
+import { dirname, join } from "node:path";
 import { homedir } from "node:os";
 import { randomUUID } from "node:crypto";
 import { assertSafeRunFileId, assertSafeRunId } from "./ids.js";
+const MAX_RUN_JSON_BYTES = 8 * 1024 * 1024;
+const MAX_RUN_JSONL_BYTES = 128 * 1024 * 1024;
+const MAX_RUN_JSONL_RECORD_BYTES = 2 * 1024 * 1024;
+const MAX_RUN_DIRECTORIES = 100_000;
+const MAX_RUN_CHILD_FILES = 100_000;
 export class FileRunStore {
     runsDir;
     constructor(storageDir) {
         this.runsDir = storageDir ?? join(homedir(), ".code-shell", "runs");
-        mkdirSync(this.runsDir, { recursive: true });
+        mkdirSync(this.runsDir, { recursive: true, mode: 0o700 });
+        this.assertRealDirectory(this.runsDir);
+        if (process.platform !== "win32")
+            chmodSync(this.runsDir, 0o700);
     }
     // ─── Helpers ───────────────────────────────────────────────────
     runDir(runId) {
         assertSafeRunId(runId);
-        return join(this.runsDir, runId);
+        const dir = join(this.runsDir, runId);
+        if (existsSync(dir))
+            this.assertRealDirectory(dir);
+        return dir;
     }
     ensureRunDir(runId) {
         const dir = this.runDir(runId);
-        mkdirSync(dir, { recursive: true });
-        mkdirSync(join(dir, "checkpoints"), { recursive: true });
-        mkdirSync(join(dir, "approvals"), { recursive: true });
-        mkdirSync(join(dir, "artifacts"), { recursive: true });
+        const directories = [dir, join(dir, "checkpoints"), join(dir, "approvals"), join(dir, "artifacts")];
+        for (const directory of directories) {
+            mkdirSync(directory, { recursive: true, mode: 0o700 });
+            this.assertRealDirectory(directory);
+            if (process.platform !== "win32")
+                chmodSync(directory, 0o700);
+        }
         return dir;
     }
     writeJson(filePath, data) {
+        this.assertRealDirectory(dirname(filePath));
+        this.assertSafeFileTarget(filePath);
+        const serialized = JSON.stringify(data, null, 2);
+        if (Buffer.byteLength(serialized, "utf8") > MAX_RUN_JSON_BYTES) {
+            throw new Error(`Run JSON exceeds ${MAX_RUN_JSON_BYTES} bytes`);
+        }
         const tmp = `${filePath}.${process.pid}.${randomUUID()}.tmp`;
         try {
-            writeFileSync(tmp, JSON.stringify(data, null, 2), "utf-8");
+            writeFileSync(tmp, serialized, { encoding: "utf-8", mode: 0o600, flag: "wx" });
             // Atomic rename — prevents partial writes on crash
             renameSync(tmp, filePath);
         }
@@ -49,7 +69,42 @@ export class FileRunStore {
     readJson(filePath) {
         if (!existsSync(filePath))
             return null;
-        return JSON.parse(readFileSync(filePath, "utf-8"));
+        this.assertRealDirectory(dirname(filePath));
+        let fd;
+        try {
+            const entry = lstatSync(filePath);
+            if (entry.isSymbolicLink() || !entry.isFile() || entry.size > MAX_RUN_JSON_BYTES) {
+                throw new Error(`Run JSON is not a bounded regular file: ${filePath}`);
+            }
+            fd = openSync(filePath, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+            const opened = fstatSync(fd);
+            if (!opened.isFile() || opened.size > MAX_RUN_JSON_BYTES) {
+                throw new Error(`Run JSON is not a bounded regular file: ${filePath}`);
+            }
+            return JSON.parse(readFileSync(fd, "utf-8"));
+        }
+        finally {
+            if (fd !== undefined)
+                closeSync(fd);
+        }
+    }
+    assertRealDirectory(directory) {
+        const info = lstatSync(directory);
+        if (info.isSymbolicLink() || !info.isDirectory()) {
+            throw new Error(`Run storage path is not a real directory: ${directory}`);
+        }
+    }
+    assertSafeFileTarget(filePath) {
+        try {
+            const info = lstatSync(filePath);
+            if (info.isSymbolicLink() || !info.isFile()) {
+                throw new Error(`Run storage target is not a regular file: ${filePath}`);
+            }
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
     }
     /** Serializes concurrent JSONL appends per file path. */
     appendLocks = new Map();
@@ -68,7 +123,39 @@ export class FileRunStore {
         this.appendLocks.set(filePath, lock);
         try {
             await prev.catch(() => { });
-            appendFileSync(filePath, JSON.stringify(data) + "\n", "utf-8");
+            this.assertRealDirectory(dirname(filePath));
+            this.assertSafeFileTarget(filePath);
+            const record = JSON.stringify(data);
+            if (Buffer.byteLength(record, "utf8") > MAX_RUN_JSONL_RECORD_BYTES) {
+                throw new Error(`Run JSONL record exceeds ${MAX_RUN_JSONL_RECORD_BYTES} bytes`);
+            }
+            // A process crash can leave a partial final JSONL record. Without a
+            // separator, the first append after restart would concatenate a valid
+            // record onto that fragment and lose both records. Inspect and repair
+            // the boundary through the same append-mode descriptor used to write.
+            const fd = openSync(filePath, constants.O_APPEND |
+                constants.O_CREAT |
+                constants.O_RDWR |
+                (constants.O_NOFOLLOW ?? 0), 0o600);
+            try {
+                if (process.platform !== "win32")
+                    fchmodSync(fd, 0o600);
+                const size = fstatSync(fd).size;
+                if (size + Buffer.byteLength(record, "utf8") + 2 > MAX_RUN_JSONL_BYTES) {
+                    throw new Error(`Run JSONL exceeds ${MAX_RUN_JSONL_BYTES} bytes`);
+                }
+                let prefix = "";
+                if (size > 0) {
+                    const lastByte = Buffer.allocUnsafe(1);
+                    readSync(fd, lastByte, 0, 1, size - 1);
+                    if (lastByte[0] !== 0x0a)
+                        prefix = "\n";
+                }
+                appendFileSync(fd, prefix + record + "\n", "utf-8");
+            }
+            finally {
+                closeSync(fd);
+            }
         }
         finally {
             // Release the lock for the next writer regardless of success/failure,
@@ -82,13 +169,41 @@ export class FileRunStore {
     readJsonl(filePath) {
         if (!existsSync(filePath))
             return [];
-        const content = readFileSync(filePath, "utf-8");
+        this.assertRealDirectory(dirname(filePath));
+        let fd;
+        let content;
+        try {
+            const entry = lstatSync(filePath);
+            if (entry.isSymbolicLink() || !entry.isFile() || entry.size > MAX_RUN_JSONL_BYTES) {
+                throw new Error(`Run JSONL is not a bounded regular file: ${filePath}`);
+            }
+            fd = openSync(filePath, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+            const opened = fstatSync(fd);
+            if (!opened.isFile() || opened.size > MAX_RUN_JSONL_BYTES) {
+                throw new Error(`Run JSONL is not a bounded regular file: ${filePath}`);
+            }
+            content = readFileSync(fd, "utf-8");
+        }
+        finally {
+            if (fd !== undefined)
+                closeSync(fd);
+        }
         if (!content)
             return [];
-        return content
-            .split("\n")
-            .filter((line) => line.trim())
-            .map((line) => JSON.parse(line));
+        const records = [];
+        for (const line of content.split("\n")) {
+            if (!line.trim())
+                continue;
+            try {
+                records.push(JSON.parse(line));
+            }
+            catch {
+                // Append-only logs must remain readable after a torn final write. A
+                // malformed record is isolated to its line; later valid records still
+                // carry useful recovery state (same policy as Transcript.loadFromFile).
+            }
+        }
+        return records;
     }
     // ─── Snapshot ──────────────────────────────────────────────────
     async create(snapshot) {
@@ -109,11 +224,24 @@ export class FileRunStore {
         if (!existsSync(this.runsDir))
             return [];
         const entries = readdirSync(this.runsDir, { withFileTypes: true });
+        if (entries.length > MAX_RUN_DIRECTORIES)
+            throw new Error("Run registry has too many entries");
         const snapshots = [];
         for (const entry of entries) {
             if (!entry.isDirectory())
                 continue;
-            const snapshot = this.readJson(join(this.runsDir, entry.name, "run.json"));
+            let snapshot;
+            try {
+                snapshot = this.readJson(join(this.runsDir, entry.name, "run.json"));
+            }
+            catch (error) {
+                // One manually damaged/legacy partial snapshot must not make every
+                // healthy run disappear from the history list. Preserve real I/O
+                // failures, but isolate JSON corruption to the affected directory.
+                if (error instanceof SyntaxError)
+                    continue;
+                throw error;
+            }
             if (!snapshot)
                 continue;
             // Filter by status
@@ -123,8 +251,9 @@ export class FileRunStore {
                     continue;
             }
             // Filter by tag
-            if (query?.tag && !snapshot.tags.includes(query.tag))
+            if (query?.tag && (!Array.isArray(snapshot.tags) || !snapshot.tags.includes(query.tag))) {
                 continue;
+            }
             snapshots.push(snapshot);
         }
         // Sort by createdAt descending (newest first)
@@ -165,7 +294,10 @@ export class FileRunStore {
         const cpDir = join(this.runDir(runId), "checkpoints");
         if (!existsSync(cpDir))
             return null;
+        this.assertRealDirectory(cpDir);
         const files = readdirSync(cpDir).filter((f) => f.endsWith(".json"));
+        if (files.length > MAX_RUN_CHILD_FILES)
+            throw new Error("Run has too many checkpoints");
         if (files.length === 0)
             return null;
         // Find the latest by createdAt
@@ -194,7 +326,10 @@ export class FileRunStore {
         const approvalDir = join(this.runDir(runId), "approvals");
         if (!existsSync(approvalDir))
             return null;
+        this.assertRealDirectory(approvalDir);
         const files = readdirSync(approvalDir).filter((f) => f.endsWith(".json"));
+        if (files.length > MAX_RUN_CHILD_FILES)
+            throw new Error("Run has too many approvals");
         for (const file of files) {
             const approval = this.readJson(join(approvalDir, file));
             if (approval?.status === "pending")