@cjhyy/code-shell-core 0.8.9 → 0.8.10

package/dist/goal/lifecycle.js

@@ -11,6 +11,25 @@
  * so an unattended goal run can't burn tokens or wall time without bound.
  */
 import { createHash, randomUUID } from "node:crypto";
+function positiveSafeNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) && value > 0 && value <= Number.MAX_SAFE_INTEGER;
+}
+function positiveSafeInteger(value) {
+    if (!positiveSafeNumber(value))
+        return undefined;
+    const integer = Math.floor(value);
+    return integer >= 1 ? integer : undefined;
+}
+/** Add a user-controlled positive integer delta without producing Infinity or an unsafe integer. */
+export function extendGoalLimit(current, addition) {
+    const delta = positiveSafeInteger(addition);
+    if (delta === undefined)
+        return current;
+    const safeCurrent = typeof current === "number" && Number.isFinite(current) && current >= 0
+        ? Math.min(Number.MAX_SAFE_INTEGER, Math.floor(current))
+        : Number.MAX_SAFE_INTEGER;
+    return Math.min(Number.MAX_SAFE_INTEGER, safeCurrent + delta);
+}
 function goalLifecycleConfig(goal) {
     const { goalId: _goalId, revision: _revision, paused: _paused, ...config } = goal;
     return config;
@@ -22,7 +41,7 @@ export function createGoalLifecycle(goal, phase = goal.paused === true
     const base = {
         version: 1,
         goalId: goal.goalId ?? randomUUID(),
-        revision: Math.max(1, Math.floor(goal.revision ?? 1)),
+        revision: positiveSafeInteger(goal.revision) ?? 1,
         config: goalLifecycleConfig(goal),
         updatedAtMs: nowMs,
     };
@@ -53,7 +72,7 @@ export function decodeGoalLifecycle(value) {
     if (typeof candidate.goalId !== "string" || candidate.goalId.length === 0)
         return undefined;
     if (typeof candidate.revision !== "number" ||
-        !Number.isInteger(candidate.revision) ||
+        !Number.isSafeInteger(candidate.revision) ||
         candidate.revision < 1) {
         return undefined;
     }
@@ -80,17 +99,19 @@ export function decodeGoalLifecycle(value) {
     for (const key of ["tokenBudget", "timeBudgetMs", "maxTurns", "maxStopBlocks"]) {
         const field = config[key];
         if (field !== undefined &&
-            (typeof field !== "number" || !Number.isFinite(field) || field <= 0)) {
+            !positiveSafeNumber(field)) {
             return undefined;
         }
     }
     for (const key of ["maxTurns", "maxStopBlocks"]) {
         const field = config[key];
-        if (field !== undefined && !Number.isInteger(field))
+        if (field !== undefined && !Number.isSafeInteger(field))
             return undefined;
     }
     if (config.setAtMs !== undefined &&
-        (typeof config.setAtMs !== "number" || !Number.isFinite(config.setAtMs) || config.setAtMs < 0)) {
+        (typeof config.setAtMs !== "number" ||
+            !Number.isSafeInteger(config.setAtMs) ||
+            config.setAtMs < 0)) {
         return undefined;
     }
     const phase = candidate.phase;
@@ -309,11 +330,12 @@ export const INTERACTIVE_DEFAULT_MAX_STOP_BLOCKS = 8;
  * Pure + injectable so engine and tests agree.
  */
 export function resolveMaxStopBlocks(configMaxStopBlocks, goal) {
-    if (typeof configMaxStopBlocks === "number" && configMaxStopBlocks > 0) {
-        return Math.floor(configMaxStopBlocks);
-    }
-    if (goal?.maxStopBlocks && goal.maxStopBlocks > 0)
-        return goal.maxStopBlocks;
+    const configLimit = positiveSafeInteger(configMaxStopBlocks);
+    if (configLimit !== undefined)
+        return configLimit;
+    const goalLimit = positiveSafeInteger(goal?.maxStopBlocks);
+    if (goalLimit !== undefined)
+        return goalLimit;
     return goal ? GOAL_DEFAULT_MAX_STOP_BLOCKS : INTERACTIVE_DEFAULT_MAX_STOP_BLOCKS;
 }
 /**
@@ -340,24 +362,25 @@ export function normalizeGoal(raw) {
     const out = { objective };
     if (typeof obj.goalId === "string" && obj.goalId.trim())
         out.goalId = obj.goalId;
-    if (typeof obj.revision === "number" && obj.revision > 0) {
-        out.revision = Math.floor(obj.revision);
-    }
+    const revision = positiveSafeInteger(obj.revision);
+    if (revision !== undefined)
+        out.revision = revision;
     if (obj.paused === true)
         out.paused = true;
-    if (typeof obj.tokenBudget === "number" && obj.tokenBudget > 0)
+    if (positiveSafeNumber(obj.tokenBudget))
         out.tokenBudget = obj.tokenBudget;
-    if (typeof obj.timeBudgetMs === "number" && obj.timeBudgetMs > 0)
+    if (positiveSafeNumber(obj.timeBudgetMs))
         out.timeBudgetMs = obj.timeBudgetMs;
-    if (typeof obj.maxTurns === "number" && obj.maxTurns > 0)
-        out.maxTurns = Math.floor(obj.maxTurns);
-    if (typeof obj.maxStopBlocks === "number" && obj.maxStopBlocks > 0) {
-        out.maxStopBlocks = Math.floor(obj.maxStopBlocks);
-    }
+    const maxTurns = positiveSafeInteger(obj.maxTurns);
+    if (maxTurns !== undefined)
+        out.maxTurns = maxTurns;
+    const maxStopBlocks = positiveSafeInteger(obj.maxStopBlocks);
+    if (maxStopBlocks !== undefined)
+        out.maxStopBlocks = maxStopBlocks;
     // Preserve a positive goal-set timestamp so a resumed/inherited goal keeps
     // the anchor for relative deadlines. Non-positive/junk is dropped, matching
     // the budget fields (a bogus anchor is worse than none).
-    if (typeof obj.setAtMs === "number" && obj.setAtMs > 0)
+    if (positiveSafeInteger(obj.setAtMs) !== undefined)
         out.setAtMs = obj.setAtMs;
     return out;
 }
@@ -391,10 +414,11 @@ export const INTERACTIVE_DEFAULT_MAX_TURNS = 100;
  * Pure + injectable so the engine and tests agree on the rule.
  */
 export function resolveMaxTurns(configMaxTurns, goal) {
-    if (typeof configMaxTurns === "number" && configMaxTurns > 0)
-        return configMaxTurns;
+    const configLimit = positiveSafeInteger(configMaxTurns);
+    if (configLimit !== undefined)
+        return configLimit;
     if (goal)
-        return goal.maxTurns ?? GOAL_DEFAULT_MAX_TURNS;
+        return positiveSafeInteger(goal.maxTurns) ?? GOAL_DEFAULT_MAX_TURNS;
     return INTERACTIVE_DEFAULT_MAX_TURNS;
 }
 /** Warn when this many turns (or fewer) remain before maxTurns. */
@@ -436,19 +460,17 @@ export function limitProximity(turnCount, maxTurns, stopBlockCount, maxStopBlock
  */
 export function applyGoalExtension(currentMaxTurns, goal, tokensUsed, elapsedMs, ext) {
     let maxTurns = currentMaxTurns;
-    if (typeof ext.addTurns === "number" && ext.addTurns > 0) {
-        maxTurns += Math.floor(ext.addTurns);
-    }
+    maxTurns = extendGoalLimit(maxTurns, ext.addTurns);
     let tokenBudget = goal?.tokenBudget;
     let timeBudgetMs = goal?.timeBudgetMs;
     if (goal) {
-        if (typeof ext.addTokenBudget === "number" && ext.addTokenBudget > 0) {
-            tokenBudget = (tokenBudget ?? tokensUsed) + Math.floor(ext.addTokenBudget);
+        if (positiveSafeInteger(ext.addTokenBudget) !== undefined) {
+            tokenBudget = extendGoalLimit(tokenBudget ?? tokensUsed, ext.addTokenBudget);
         }
-        if (typeof ext.addTimeBudgetMs === "number" && ext.addTimeBudgetMs > 0) {
+        if (positiveSafeInteger(ext.addTimeBudgetMs) !== undefined) {
             // Seed an unset cap from elapsed time (not 0), mirroring the token branch,
             // so the new cap lands above current usage. Fixes B1.
-            timeBudgetMs = (timeBudgetMs ?? elapsedMs) + Math.floor(ext.addTimeBudgetMs);
+            timeBudgetMs = extendGoalLimit(timeBudgetMs ?? elapsedMs, ext.addTimeBudgetMs);
         }
     }
     return { maxTurns, tokenBudget, timeBudgetMs };
@@ -459,8 +481,9 @@ export function createGoalBudgetTracker(goal, nowMs) {
 }
 /** Add this turn's token usage to the running total. */
 export function recordGoalUsage(tracker, turnTokens) {
-    if (turnTokens > 0)
-        tracker.tokensUsed += turnTokens;
+    if (positiveSafeInteger(turnTokens) !== undefined) {
+        tracker.tokensUsed = extendGoalLimit(tracker.tokensUsed, turnTokens);
+    }
 }
 /**
  * Has the run exceeded any configured budget? `nowMs` is injected so callers

package/dist/index.d.ts

@@ -3,7 +3,7 @@
  *
  * Public API exports.
  */
-export declare const VERSION = "0.8.9";
+export declare const VERSION = "0.8.10";
 export type { Message, ContentBlock, ToolDefinition, ToolCall, ToolResult, RegisteredTool, TranscriptEvent, TranscriptEventType, SessionState, SessionKind, SessionWorkspace, SessionForkLineage, ContextUsageAnchor, SessionStatus, TokenUsage, CompiledInput, PermissionDecision, PermissionMode, PermissionRule, TurnPhase, TurnResult, TerminalReason, TurnCompletionKind, StreamEvent, StreamCallback, LLMConfig, ClientDefaults, LLMResponse, Settings, MCPServerConfig, } from "./types.js";
 export type { GoalConfig, GoalLifecycleConfig, GoalLifecyclePhase, GoalLifecycleTerminalReason, GoalLifecycleV1, } from "./goal/lifecycle.js";
 export { FrameworkError, LLMError, LLMRateLimitError, ContextLimitError, ToolError, ToolNotFoundError, ToolExecutionError, ToolTimeoutError, PermissionDeniedError, SessionError, TranscriptError, ConfigError, SandboxUnavailableError, } from "./exceptions.js";
@@ -66,7 +66,7 @@ export { Methods, ErrorCodes, type RpcMessage, type RunResult, type ForkSessionP
 export type * from "./protocol/mobile-remote-types.js";
 export { Transcript } from "./session/transcript.js";
 export { SessionManager, sessionMainRoot, codeShellHome, sessionsRoot, buildForkState, buildForkTranscript, type ForkSessionOptions, type ForkSessionResult, } from "./session/session-manager.js";
-export { FileHistory } from "./session/file-history.js";
+export { FileHistory, type FileSnapshot, type RedoRecord, type TurnUndoPlan, } from "./session/file-history.js";
 export { latestUndoTarget, earliestSnapshotsPerFile, latestTurnUndoTargets, latestRedoTargets, } from "./session/undo-target.js";
 export { diffLines, renderDiffPreview, type DiffLine } from "./session/simple-diff.js";
 export { MemoryManager } from "./session/memory.js";
@@ -74,7 +74,6 @@ export type { MemoryEntry, MemoryOrigin, MemoryScope } from "./session/memory.js
 export type { RouteSessionMessageInput, SessionMessageRouter, SessionMessageTarget, SessionMessageToolService, } from "./session/session-message.js";
 export { runDreamConsolidation, type DreamConsolidationInput, type DreamConsolidationResult, } from "./services/dream-consolidation.js";
 export { authorize, refreshToken, generatePKCE, createHardenedOAuthFetch, type OAuthConfig, type OAuthTokens, type OAuthAuthorizeOptions, type OAuthRefreshOptions, type HardenedOAuthFetchOptions, } from "./services/oauth.js";
-export type { FileSnapshot, RedoRecord } from "./session/file-history.js";
 export { PromptComposer } from "./prompt/composer.js";
 export { SectionCache } from "./prompt/section-cache.js";
 export { scanInstructions, combineInstructions } from "./prompt/instruction-scanner.js";

package/dist/index.internal.d.ts

@@ -12,6 +12,7 @@ export { execFileNoThrow } from "./utils/execFileNoThrow.js";
 export { findExecutable, resolveExecutable, setGitPathOverride, resolveGit, isGitAvailable, resolveGitPath, } from "./utils/exec.js";
 export { gte } from "./utils/semver.js";
 export { lock, lockSync, unlock, check } from "./utils/lockfile.js";
+export { acquireFileLock, acquireLockOnPath, mutateJsonFile } from "./utils/file-mutex.js";
 export { logForDebugging } from "./utils/debug.js";
 export { isEnvTruthy, isEnvDefinedFalsy, getClaudeConfigHomeDir, isBareMode, parseEnvVars, shouldMaintainProjectWorkingDir, getAWSRegion, getDefaultVertexRegion, getVertexRegionForModel, } from "./utils/envUtils.js";
 export { startCapturingEarlyInput, stopCapturingEarlyInput, consumeEarlyInput, hasEarlyInput, seedEarlyInput, isCapturingEarlyInput, } from "./utils/earlyInput.js";

package/dist/index.internal.js

@@ -13,6 +13,7 @@ export { execFileNoThrow } from "./utils/execFileNoThrow.js";
 export { findExecutable, resolveExecutable, setGitPathOverride, resolveGit, isGitAvailable, resolveGitPath, } from "./utils/exec.js";
 export { gte } from "./utils/semver.js";
 export { lock, lockSync, unlock, check } from "./utils/lockfile.js";
+export { acquireFileLock, acquireLockOnPath, mutateJsonFile } from "./utils/file-mutex.js";
 export { logForDebugging } from "./utils/debug.js";
 export { isEnvTruthy, isEnvDefinedFalsy, getClaudeConfigHomeDir, isBareMode, parseEnvVars, shouldMaintainProjectWorkingDir, getAWSRegion, getDefaultVertexRegion, getVertexRegionForModel, } from "./utils/envUtils.js";
 export { startCapturingEarlyInput, stopCapturingEarlyInput, consumeEarlyInput, hasEarlyInput, seedEarlyInput, isCapturingEarlyInput, } from "./utils/earlyInput.js";

package/dist/index.js

@@ -3,7 +3,7 @@
  *
  * Public API exports.
  */
-export const VERSION = "0.8.9";
+export const VERSION = "0.8.10";
 // ─── Exceptions ──────────────────────────────────────────────────
 export { FrameworkError, LLMError, LLMRateLimitError, ContextLimitError, ToolError, ToolNotFoundError, ToolExecutionError, ToolTimeoutError, PermissionDeniedError, SessionError, TranscriptError, ConfigError, SandboxUnavailableError, } from "./exceptions.js";
 // ─── Engine (primary API) ────────────────────────────────────────
@@ -55,7 +55,7 @@ export { Methods, ErrorCodes, } from "./protocol/types.js";
 // ─── Session ─────────────────────────────────────────────────────
 export { Transcript } from "./session/transcript.js";
 export { SessionManager, sessionMainRoot, codeShellHome, sessionsRoot, buildForkState, buildForkTranscript, } from "./session/session-manager.js";
-export { FileHistory } from "./session/file-history.js";
+export { FileHistory, } from "./session/file-history.js";
 export { latestUndoTarget, earliestSnapshotsPerFile, latestTurnUndoTargets, latestRedoTargets, } from "./session/undo-target.js";
 export { diffLines, renderDiffPreview } from "./session/simple-diff.js";
 export { MemoryManager } from "./session/memory.js";

package/dist/links/cli.d.ts

@@ -17,6 +17,8 @@ export interface CliLinkRunOptions {
     signal?: AbortSignal;
     timeoutMs: number;
     input?: string;
+    /** Keep the pipe alive for browser/device login CLIs that inspect stdin. */
+    keepStdinOpen?: boolean;
 }
 export type CliLinkCommandRunner = (providerId: CliLinkProviderId, command: string, args: string[], options: CliLinkRunOptions) => Promise<CliLinkCommandResult>;
 /** App-private CLI location. It never mutates the user's system PATH. */

package/dist/links/cli.js

@@ -103,10 +103,15 @@ export const runCliLinkCommand = (providerId, command, args, options) => new Pro
         }
         resolve({ stdout: String(stdout), stderr: String(stderr) });
     });
-    // All supported flows are deliberately non-interactive (browser/device
-    // authorization or machine-readable API calls). Always close stdin so a
-    // CLI cannot mistake the Electron pipe for pending JSON or a hidden prompt.
-    child.stdin?.end(options.input ?? "");
+    if (options.input !== undefined)
+        child.stdin?.write(options.input);
+    // API calls consume a complete JSON body and must see EOF. Browser/device
+    // login is different: gh/glab prompt before opening the browser and some
+    // versions of Vercel first present a default login method. Feed one Enter
+    // below, but keep the pipe alive so those CLIs do not fail immediately with
+    // EOF while the browser authorization is still in progress.
+    if (!options.keepStdinOpen)
+        child.stdin?.end();
 });
 function parseJson(result, providerId) {
     try {
@@ -289,6 +294,8 @@ export async function connectCliLink(providerId, options, run = runCliLinkComman
                 cwd: options.cwd,
                 signal: options.signal,
                 timeoutMs: 15 * 60_000,
+                input: "\n",
+                keepStdinOpen: true,
             });
         }
         catch (error) {

package/dist/model-catalog/index.js

@@ -8,7 +8,7 @@
  *
  * No remote source this version (design doc §5).
  */
-import { readFileSync, existsSync } from "node:fs";
+import { closeSync, constants, fstatSync, lstatSync, openSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { userHome } from "../settings/manager.js";
 import { logger } from "../logging/logger.js";
@@ -16,6 +16,7 @@ import { BUILTIN_CATALOG } from "./builtin.js";
 import { userCatalogFileSchema } from "./types.js";
 export { BUILTIN_CATALOG } from "./builtin.js";
 export { saveCatalogEntry, deleteUserCatalogEntry } from "./save-entry.js";
+const MAX_USER_CATALOG_BYTES = 4 * 1024 * 1024;
 /** Path to the user catalog file (source B). */
 export function userCatalogPath() {
     return join(userHome(), ".code-shell", "model-catalog.user.json");
@@ -26,10 +27,18 @@ export function userCatalogPath() {
  */
 export function loadUserCatalog() {
     const path = userCatalogPath();
-    if (!existsSync(path))
-        return [];
+    let descriptor;
     try {
-        const parsed = JSON.parse(readFileSync(path, "utf-8"));
+        const metadata = lstatSync(path);
+        if (metadata.isSymbolicLink() || !metadata.isFile() || metadata.size > MAX_USER_CATALOG_BYTES) {
+            throw new Error("model catalog must be a bounded regular file");
+        }
+        descriptor = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+        const opened = fstatSync(descriptor);
+        if (!opened.isFile() || opened.size > MAX_USER_CATALOG_BYTES) {
+            throw new Error("model catalog must be a bounded regular file");
+        }
+        const parsed = JSON.parse(readFileSync(descriptor, "utf-8"));
         const result = userCatalogFileSchema.safeParse(parsed);
         if (!result.success) {
             logger.warn("model_catalog_user_invalid", { path, issues: result.error.issues.length });
@@ -38,9 +47,15 @@ export function loadUserCatalog() {
         return result.data;
     }
     catch (err) {
+        if (err.code === "ENOENT")
+            return [];
         logger.warn("model_catalog_user_read_failed", { path, error: err.message });
         return [];
     }
+    finally {
+        if (descriptor !== undefined)
+            closeSync(descriptor);
+    }
 }
 /**
  * Merged catalog: built-in (A) ∪ user (B), deduped by `id` with user winning.

package/dist/model-catalog/save-entry.js

@@ -6,10 +6,91 @@
  * here (those go through the user's own Edit, by design).
  * See docs/superpowers/specs/2026-06-15-unified-model-catalog-design.md §7.
  */
-import { readFileSync, writeFileSync, existsSync, copyFileSync, mkdirSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { chmodSync, closeSync, constants, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeFileSync, } from "node:fs";
 import { dirname } from "node:path";
 import { catalogEntrySchema, userCatalogFileSchema } from "./types.js";
 import { upsertCatalogEntry } from "./upsert.js";
+import { acquireFileLock } from "../utils/file-mutex.js";
+const MAX_USER_CATALOG_BYTES = 4 * 1024 * 1024;
+const BACKUP_STAMP_RE = /^[A-Za-z0-9._-]{1,128}$/;
+function pathEntry(path) {
+    try {
+        return lstatSync(path);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+}
+function readExistingCatalog(path) {
+    const metadata = pathEntry(path);
+    if (!metadata)
+        return undefined;
+    if (metadata.isSymbolicLink() ||
+        !metadata.isFile() ||
+        metadata.size > MAX_USER_CATALOG_BYTES) {
+        throw new Error("catalog must be a bounded regular file");
+    }
+    const descriptor = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    try {
+        const opened = fstatSync(descriptor);
+        if (!opened.isFile() || opened.size > MAX_USER_CATALOG_BYTES) {
+            throw new Error("catalog must be a bounded regular file");
+        }
+        const raw = readFileSync(descriptor, "utf8");
+        try {
+            const parsed = userCatalogFileSchema.safeParse(JSON.parse(raw));
+            return { raw, entries: parsed.success ? parsed.data : [] };
+        }
+        catch {
+            return { raw, entries: [] };
+        }
+    }
+    finally {
+        closeSync(descriptor);
+    }
+}
+function writeBackup(path, raw) {
+    try {
+        writeFileSync(path, raw, { encoding: "utf8", mode: 0o600, flag: "wx" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function writeCatalogAtomic(path, entries) {
+    const serialized = `${JSON.stringify(userCatalogFileSchema.parse(entries), null, 2)}\n`;
+    if (Buffer.byteLength(serialized, "utf8") > MAX_USER_CATALOG_BYTES) {
+        throw new Error("catalog exceeds its size limit");
+    }
+    const parent = dirname(path);
+    mkdirSync(parent, { recursive: true, mode: 0o700 });
+    const parentInfo = lstatSync(parent);
+    if (parentInfo.isSymbolicLink() || !parentInfo.isDirectory()) {
+        throw new Error("catalog parent must be a real directory");
+    }
+    const target = pathEntry(path);
+    if (target && (target.isSymbolicLink() || !target.isFile())) {
+        throw new Error("catalog target must be a regular file");
+    }
+    const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+        writeFileSync(temporary, serialized, {
+            encoding: "utf8",
+            mode: 0o600,
+            flag: "wx",
+        });
+        renameSync(temporary, path);
+        if (process.platform !== "win32")
+            chmodSync(path, 0o600);
+    }
+    finally {
+        rmSync(temporary, { force: true });
+    }
+}
 /**
  * @param stamp caller-supplied unique suffix for the backup filename. Pass a
  *   timestamp/counter from the caller — core forbids Date.now() in some paths
@@ -22,47 +103,27 @@ export function saveCatalogEntry(entry, opts) {
         return { ok: false, error: `invalid catalog entry: ${parsed.error.issues.map((i) => i.message).join("; ")}` };
     }
     const valid = parsed.data;
-    // Read + back up any existing file (even if corrupt — never silently lose it).
-    let current = [];
-    let backup;
-    if (existsSync(opts.path)) {
-        backup = `${opts.path}.bak-${opts.stamp}`;
-        try {
-            copyFileSync(opts.path, backup);
-        }
-        catch {
-            backup = undefined; // best-effort; don't abort the write on backup failure
-        }
-        try {
-            const raw = JSON.parse(readFileSync(opts.path, "utf-8"));
-            const safe = userCatalogFileSchema.safeParse(raw);
-            current = safe.success ? safe.data : [];
-        }
-        catch {
-            current = []; // corrupt → start fresh (original preserved in backup)
-        }
-    }
-    const action = current.some((e) => e.id === valid.id) ? "updated" : "added";
-    const next = upsertCatalogEntry(current, valid);
-    // Ensure the parent dir exists — a first-ever catalog write on a machine
-    // whose ~/.code-shell hasn't been created yet would otherwise throw ENOENT
-    // (the agent-facing tool wants a clean {ok:false} or a real write, not a crash).
+    if (!BACKUP_STAMP_RE.test(opts.stamp))
+        return { ok: false, error: "invalid backup stamp" };
+    let release;
     try {
-        mkdirSync(dirname(opts.path), { recursive: true });
+        release = acquireFileLock(opts.path);
+        const existing = readExistingCatalog(opts.path);
+        let backup = existing ? `${opts.path}.bak-${opts.stamp}` : undefined;
+        if (existing && !writeBackup(backup, existing.raw))
+            backup = undefined;
+        const action = existing?.entries.some((e) => e.id === valid.id)
+            ? "updated"
+            : "added";
+        writeCatalogAtomic(opts.path, upsertCatalogEntry(existing?.entries ?? [], valid));
+        return { ok: true, action, backup };
     }
     catch (e) {
-        return { ok: false, error: `could not create catalog directory: ${e instanceof Error ? e.message : String(e)}`, backup };
+        return { ok: false, error: `could not write catalog: ${e instanceof Error ? e.message : String(e)}` };
     }
-    try {
-        writeFileSync(opts.path, JSON.stringify(next, null, 2));
-    }
-    catch (e) {
-        // IO error (perms / disk full / bad path): return a clean {ok:false} with the
-        // backup filename preserved, never let the throw escape past the tool's
-        // expected result shape (the original file is intact — we only upsert-wrote).
-        return { ok: false, error: `could not write catalog: ${e instanceof Error ? e.message : String(e)}`, backup };
+    finally {
+        release?.();
     }
-    return { ok: true, action, backup };
 }
 /**
  * Remove the entry with `id` from the user catalog file. Mirrors saveCatalogEntry's
@@ -72,33 +133,33 @@ export function saveCatalogEntry(entry, opts) {
  * built-in version ("reset" semantics).
  */
 export function deleteUserCatalogEntry(id, opts) {
-    if (!existsSync(opts.path))
-        return { ok: true, removed: false };
-    let backup = `${opts.path}.bak-${opts.stamp}`;
-    try {
-        copyFileSync(opts.path, backup);
-    }
-    catch {
-        backup = undefined;
+    if (!BACKUP_STAMP_RE.test(opts.stamp)) {
+        return { ok: false, removed: false, error: "invalid backup stamp" };
     }
-    let current = [];
+    let release;
     try {
-        const raw = JSON.parse(readFileSync(opts.path, "utf-8"));
-        const safe = userCatalogFileSchema.safeParse(raw);
-        current = safe.success ? safe.data : [];
-    }
-    catch {
-        current = [];
-    }
-    const next = current.filter((e) => e.id !== id);
-    const removed = next.length !== current.length;
-    if (!removed)
-        return { ok: true, removed: false, backup };
-    try {
-        writeFileSync(opts.path, JSON.stringify(next, null, 2));
+        release = acquireFileLock(opts.path);
+        const existing = readExistingCatalog(opts.path);
+        if (!existing)
+            return { ok: true, removed: false };
+        let backup = `${opts.path}.bak-${opts.stamp}`;
+        if (!writeBackup(backup, existing.raw))
+            backup = undefined;
+        const next = existing.entries.filter((e) => e.id !== id);
+        const removed = next.length !== existing.entries.length;
+        if (!removed)
+            return { ok: true, removed: false, backup };
+        writeCatalogAtomic(opts.path, next);
+        return { ok: true, removed: true, backup };
     }
     catch (e) {
-        return { ok: false, removed: false, error: `could not write catalog: ${e instanceof Error ? e.message : String(e)}`, backup };
+        return {
+            ok: false,
+            removed: false,
+            error: `could not write catalog: ${e instanceof Error ? e.message : String(e)}`,
+        };
+    }
+    finally {
+        release?.();
     }
-    return { ok: true, removed: true, backup };
 }