@cjhyy/code-shell-core 0.7.0 → 0.8.0

package/dist/types.d.ts

@@ -1,7 +1,7 @@
 /**
  * Core type definitions for the code-shell orchestration framework.
  */
-import type { GoalConfig, GoalTerminal } from "./engine/goal.js";
+import type { GoalConfig, GoalLifecycleV1, GoalTerminal } from "./goal/lifecycle.js";
 export interface ContentBlock {
     type: "text" | "tool_use" | "tool_result" | "image" | "reasoning";
     text?: string;
@@ -33,16 +33,22 @@ export interface ToolDefinition {
     name: string;
     description: string;
     inputSchema: Record<string, unknown>;
+    /** Omit this tool's result body from retained Goal-judge evidence. */
+    sensitiveResult?: boolean;
 }
 export interface ToolCall {
     id: string;
     toolName: string;
     serverName?: string;
     args: Record<string, unknown>;
+    /** Host-projected UI visibility. Does not affect execution or transcript retention. */
+    uiVisibility?: "hidden" | "milestones" | "full";
 }
 export interface ToolResult {
     id: string;
     toolName: string;
+    /** Host-projected UI visibility. Does not affect the model-facing result. */
+    uiVisibility?: "hidden" | "milestones" | "full";
     /**
      * Sensitive tool results keep `result` as the model-facing value for the
      * current model round only. Persisted/displayed/streamed observers must use
@@ -86,25 +92,27 @@ export type ToolPathPolicyOperation = "read" | "write" | {
     /** Fallback when the argument is absent or does not match either list. */
     default: "read" | "write";
 };
-export type ToolPathPolicy = {
+export interface ToolPathPolicy {
     kind: "arg";
     /** Argument containing a file or directory path. */
     arg: string;
     operation: ToolPathPolicyOperation;
     /** Use ctx.cwd when the argument is omitted. Useful for Glob/Grep roots. */
     defaultToCwd?: boolean;
-} | {
-    kind: "apply_patch";
-    /** Argument containing the V4A patch text. */
-    arg: string;
-    operation: "write";
-};
+}
+/** Capability-owned resolver for compound inputs that reference multiple paths. */
+export interface ToolPathResolver {
+    operation: "read" | "write";
+    resolve(args: Record<string, unknown>, cwd: string): readonly string[];
+}
 export interface RegisteredTool {
     name: string;
     description: string;
     inputSchema: Record<string, unknown>;
     source: ToolSource;
     serverName?: string;
+    /** Original, unprefixed MCP tool name used by per-server allow/deny policy. */
+    mcpToolName?: string;
     /**
      * Declarative UI/metadata hint for hosts, docs, and capability listings.
      * It is not an execution-policy input: PermissionClassifier does not read
@@ -114,6 +122,10 @@ export interface RegisteredTool {
     permissionDefault: PermissionDecision;
     isConcurrencySafe?: boolean;
     isReadOnly?: boolean;
+    /** Used when file targets cannot be described as one direct schema argument. */
+    pathResolver?: ToolPathResolver;
+    /** Declaratively marks result bodies as sensitive for retained Goal evidence. */
+    sensitiveResult?: boolean;
     /**
      * Declarative file-path safety metadata. ToolExecutor enforces this before
      * dispatching the tool, so file access cannot depend on each tool handler
@@ -133,7 +145,7 @@ export interface RegisteredTool {
      */
     timeoutMs?: number;
 }
-export type TranscriptEventType = "message" | "tool_use" | "tool_result" | "summary" | "content_replace" | "file_history" | "plan_operation" | "session_meta" | "subagent" | "external_file_changes" | "turn_boundary" | "goal_progress" | "turn_stopped" | "error";
+export type TranscriptEventType = "message" | "tool_use" | "tool_result" | "summary" | "context_transfer" | "content_replace" | "file_history" | "plan_operation" | "session_meta" | "subagent" | "external_file_changes" | "turn_boundary" | "run_result" | "goal_progress" | "turn_stopped" | "error";
 export interface TranscriptEvent {
     id: string;
     type: TranscriptEventType;
@@ -150,10 +162,23 @@ export interface TranscriptEvent {
  * error (`"model_error"`, `"prompt_too_long"`, ...).
  */
 export type SessionStatus = "active" | "paused" | TerminalReason;
-/** Which host/context created a session — used by the desktop disk-rebuild to
- *  filter the sidebar (only `desktop` + `automation` are shown). */
-export type SessionOrigin = "desktop" | "tui" | "automation" | "subagent";
+/** Known first-party session origins. Hosts may contribute stable names of their own. */
+export type BuiltinSessionOrigin = "desktop" | "tui" | "automation" | "subagent";
+/**
+ * Which host/context created a session. This is intentionally open: core
+ * persists the provenance label but product hosts decide how to group/filter
+ * it, so extension packages never need to add a literal back into core.
+ */
+export type SessionOrigin = BuiltinSessionOrigin | (string & {});
+/**
+ * Persisted session kind. "work" is the core default; extensions may own
+ * additional kinds (e.g. the pet extension's "pet") — the open string form
+ * keeps literal inference/autocomplete for "work" while allowing extension
+ * kinds without a core enum change.
+ */
+export type SessionKind = "work" | (string & {});
 export interface SessionWorkspace {
+    /** Current execution root used when this session resumes. */
     root: string;
     kind: "main" | "worktree";
     worktree?: {
@@ -171,10 +196,40 @@ export interface ContextUsageAnchor {
     provider?: string;
     model?: string;
 }
+/** Provenance for a user-visible session fork. Optional on legacy sessions. */
+export interface SessionForkLineage {
+    sessionId: string;
+    mode: "full" | "summary";
+    fromEventId?: string;
+    throughEventId?: string;
+    sourceEventCount: number;
+    createdAt: number;
+}
 export interface SessionState {
     sessionId: string;
+    /** Durable local classification. Missing on legacy state and normalized to `work`. */
+    kind?: SessionKind;
+    /** Durable per-session digital-human binding. It overrides the Workspace default profile. */
+    workspaceProfile?: string;
+    /**
+     * Standing brief for this Session, injected as system context on every run.
+     *
+     * Set when a team is summoned: the member's role, its teammates' Session ids
+     * and the lead's playbook. It used to be pre-filled into the composer instead,
+     * which read as if the *user* had typed a specification — and one stray edit or
+     * Enter lost it. This is configuration for the agent, so it belongs in the
+     * prompt, not the input box.
+     */
+    sessionBrief?: string;
+    /**
+     * Monotonic whole-state revision used by SessionManager.saveState as a CAS
+     * token. Absent only on legacy state files; the first successful save
+     * upgrades them. Detached writers with an older revision are rejected.
+     */
+    stateRevision?: number;
+    /** Legacy persisted main-project root. Kept byte-compatible in state.json. */
     cwd: string;
-    /** Current session workspace pointer. Absent only on legacy state.json files. */
+    /** Current main/worktree execution pointer. Absent only on legacy state.json files. */
     workspace?: SessionWorkspace;
     startedAt: number;
     model: string;
@@ -190,6 +245,11 @@ export interface SessionState {
      * before the next provider response.
      */
     contextUsageAnchor?: ContextUsageAnchor;
+    /**
+     * Exceptional boundary for the most recently persisted completed run.
+     * Absent means `status === "completed"` is an ordinary final answer.
+     */
+    lastCompletionKind?: TurnCompletionKind;
     /**
      * Monotonic prompt-cache counters for the whole session. These only increase
      * from session start and are separate from the resettable tokenUsage window.
@@ -207,6 +267,20 @@ export interface SessionState {
      * the last user message changed. Absent on legacy sessions → treated as 0.
      */
     turnSeq?: number;
+    /**
+     * Inclusive transcript cursor for the last naturally completed conversation
+     * turn. It advances only when Engine.run finishes with reason="completed",
+     * so a side fork can exclude a newer user message already persisted by an
+     * in-flight run. Absent on legacy sessions and before the first completion.
+     */
+    completedThroughEventId?: string;
+    /**
+     * Presence distinguishes sessions written by the completed-snapshot cursor
+     * implementation from legacy sessions. Version 1 with no cursor means the
+     * latest completion could not establish a durable snapshot (for example a
+     * transcript flush failure) and must fail closed instead of using the tail.
+     */
+    completedSnapshotVersion?: 1;
     invokedSkills: string[];
     /**
      * Owning parent session for a sub-agent run; `null` explicitly marks a
@@ -215,6 +289,20 @@ export interface SessionState {
      * "key present && null" to tell a new top-level session apart from legacy.
      */
     parentSessionId?: string | null;
+    /**
+     * Durable archival timestamp (ms). Absent = not archived. Generic session
+     * lifecycle marker: list surfaces filter it out by default. Set/cleared via
+     * SessionManager.setSessionArchived.
+     */
+    archivedAt?: number;
+    /** User-fork lineage; deliberately separate from sub-agent ownership. */
+    forkedFrom?: SessionForkLineage;
+    /**
+     * Temporary child sessions are persisted only while their owning surface is
+     * alive. Ordinary resume/session pickers must omit them. Absent on legacy
+     * sessions; desktop also recognizes its historical `qchat-*` namespace.
+     */
+    ephemeral?: boolean;
     /**
      * Which host/context created this session. Desktop disk-rebuild shows only
      * `desktop` + `automation`. Absent on legacy sessions.
@@ -232,7 +320,10 @@ export interface SessionState {
     title?: string;
     /** Persisted cost tracking state (survives process restart). */
     costState?: Record<string, unknown>;
+    /** Canonical persisted and runtime Goal state. */
+    goalLifecycle?: GoalLifecycleV1;
     /**
+     * Legacy persisted input only. Runtime hydration removes this field and new writers omit it.
      * Active persistent goal (CC `/goal` style). Set once, it survives across
      * messages AND manual interrupts until the judge says it's met or the user
      * clears it. Absent → no active goal. When a run supplies a new goal it
@@ -243,11 +334,14 @@ export interface SessionState {
      */
     activeGoal?: GoalConfig;
     /**
-     * Last force-terminated goal instance. Kept separately from activeGoal so an
-     * old whole-state writer cannot make that same exhausted goal armable again.
+     * Legacy persisted input only. Runtime hydration removes this field and new writers omit it.
+     * Latest terminal goal instance (legacy/single-marker view). Kept alongside
+     * the bounded goalTerminals identity set for backward-compatible readers.
      * Optional for backward compatibility with pre-tombstone state.json files.
      */
     goalTerminal?: GoalTerminal;
+    /** Legacy persisted terminal history input; runtime hydration removes it. */
+    goalTerminals?: GoalTerminal[];
 }
 export interface TokenUsage {
     promptTokens: number;
@@ -341,12 +435,23 @@ export interface TaskInfo {
 }
 export type PromptTokenSource = "provider_usage" | "anchor_delta" | "anchor_rescale" | "calibrated_estimate" | "heuristic_estimate" | "session_cumulative";
 export type PromptTokenConfidence = "high" | "medium" | "low";
+/**
+ * Why a syntactically completed engine run did not finish its logical task.
+ * Absent means the model reached an ordinary final response. Consumers that
+ * manage durable work can use this to avoid treating an async handoff or a
+ * Goal-control boundary as objective completion.
+ */
+export type TurnCompletionKind = "background_wait" | "goal_control_stop" | "limit_stop";
 export type StreamEvent = {
     type: "session_started";
     sessionId: string;
     promptTokens: number;
     promptTokensSource?: PromptTokenSource;
     promptTokensConfidence?: PromptTokenConfidence;
+} | {
+    type: "session_user_message";
+    text: string;
+    clientMessageId?: string;
 } | {
     type: "session_title";
     sessionId: string;
@@ -386,9 +491,14 @@ export type StreamEvent = {
 } | {
     type: "turn_complete";
     reason: TerminalReason;
+    completionKind?: TurnCompletionKind;
     agentId?: string;
 } | {
     type: "goal_progress";
+    /** Concrete goal instance; absent only on legacy replayed events. */
+    goalId?: string;
+    /** Edit/pause/resume revision for stale-event fencing. */
+    revision?: number;
     status: "not_met" | "met" | "exhausted" | "approaching_limit";
     round: number;
     gaps?: string;
@@ -401,10 +511,21 @@ export type StreamEvent = {
     agentId?: string;
 } | {
     type: "goal_set";
+    goalId?: string;
+    revision?: number;
     objective: string;
     replaced: boolean;
+    paused?: boolean;
+} | {
+    type: "goal_updated";
+    goalId?: string;
+    revision?: number;
+    objective: string;
+    paused: boolean;
 } | {
     type: "goal_cleared";
+    goalId?: string;
+    revision?: number;
 } | {
     type: "error";
     error: string;
@@ -421,7 +542,7 @@ export type StreamEvent = {
     type: "memory_recalled";
     name: string;
     scope: "user" | "dream";
-    location: "global" | "project";
+    location: "global" | "project" | "profile";
     agentId?: string;
 } | {
     type: "thinking_delta";
@@ -458,10 +579,19 @@ export type StreamEvent = {
     agentId?: string;
 } | {
     type: "context_compact";
-    strategy: "micro" | "summary" | "window" | "snip" | "emergency" | "compacted";
+    strategy: "micro" | "summary" | "window" | "snip" | "emergency" | "compacted" | "range";
     before: number;
     after: number;
     agentId?: string;
+} | {
+    /** Persisted summary-only history transferred into a newly forked session. */
+    type: "context_transfer";
+    summary: string;
+    sourceSessionId: string;
+    fromEventId: string;
+    toEventId: string;
+    sourceEventCount: number;
+    estimatedTokens: number;
 } | {
     type: "usage_update";
     promptTokens: number;
@@ -680,16 +810,28 @@ export interface MCPServerConfig {
      * UI toggle can flip it back on. See connectAll().
      */
     enabled?: boolean;
+    /**
+     * Exact MCP tool-name allowlist. Undefined exposes every discovered tool;
+     * an empty list exposes none. `disabledTools` is applied afterwards.
+     */
+    allowedTools?: string[];
+    /** Exact MCP tool-name denylist, applied after `allowedTools`. */
+    disabledTools?: string[];
 }
 /**
  * User-supplied supplement for a PLUGIN-provided MCP server, keyed by the
  * server's `<plugin>:<server>` name. Stored globally under
  * `settings.mcpServerOverrides` and layered onto the plugin's config at merge
- * time (see mergePluginMcpServers). Only env/credential fields are allowed —
- * command/args/url/transport stay owned by the plugin manifest so a plugin
- * update is never shadowed by a stale user copy.
+ * time (see mergePluginMcpServers). Only user-controlled server/tool policy
+ * and env/credential fields are allowed — command/args/url/transport stay
+ * owned by the plugin manifest so an update is never shadowed by a stale copy.
  */
 export interface MCPServerOverride {
+    /** Per-server user policy. Allows one server to be disabled without disabling its owner plugin. */
+    enabled?: boolean;
+    /** User policy layered over the plugin server's reviewed connection identity. */
+    allowedTools?: string[];
+    disabledTools?: string[];
     env?: Record<string, string>;
     envVars?: string[];
     /** (HTTP) id of a stored token/link/oauth credential used as Bearer auth. */
@@ -761,3 +903,42 @@ export interface Settings {
      */
     hooks?: SettingsHookConfig[];
 }
+export type InputAttachmentKind = "image" | "file" | "directory";
+export type InputAttachmentOrigin = "paste" | "os-drop" | "file-panel" | "picker" | "mention" | "generated" | "mobile" | "im-gateway" | "tool";
+export interface InputAttachmentMeta {
+    id: string;
+    sessionId: string;
+    kind: InputAttachmentKind;
+    origin: InputAttachmentOrigin;
+    path: string;
+    absPath: string;
+    relPath?: string;
+    mime?: string;
+    size: number;
+    sha256: string;
+    originalName?: string;
+    createdAt: number;
+    sourcePath?: string;
+    width?: number;
+    height?: number;
+    vision?: {
+        include: boolean;
+        mediaPath?: string;
+        detail?: "low" | "standard" | "high";
+    };
+    directory?: {
+        treePath?: string;
+        truncated?: boolean;
+        entryCount?: number;
+    };
+}
+export interface LegacyPetWorkspaceOption {
+    id: string;
+    name: string;
+    description?: string;
+}
+export interface LegacyPetWorkDelegation {
+    workspaceId: string;
+    objective: string;
+    reusableSessionId?: string;
+}

package/dist/{cc-orchestrator → utils}/cwd-normalize.d.ts

@@ -1,2 +1,3 @@
+/** Canonicalize a runtime cwd without assuming any product domain. */
 export declare function normalizeCwdPath(cwd: string): string;
 export declare function isExistingDirectory(cwd: string): boolean;

package/dist/{cc-orchestrator → utils}/cwd-normalize.js

@@ -1,5 +1,6 @@
 import { realpathSync, statSync } from "node:fs";
 import { resolve } from "node:path";
+/** Canonicalize a runtime cwd without assuming any product domain. */
 export function normalizeCwdPath(cwd) {
     const resolved = resolve(cwd);
     try {

package/dist/utils/file-mutex.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Cross-process read-modify-write for a single JSON file.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * Several subsystems independently implemented "load → change → save" against a
+ * shared file with NO cross-process lock. Atomic tmp+rename protects against a
+ * torn file, but not against lost updates: two processes both read revision N,
+ * both write N+1, and one change vanishes. Measured on this repo: 48 concurrent
+ * writers each setting a distinct settings key left only 17 keys; 48 concurrent
+ * AutoDream increments recorded 1–2.
+ *
+ * CronStore already had the correct shape (directory lock + reload-inside-lock +
+ * unique tmp + rename). This module extracts exactly that so every writer shares
+ * one implementation instead of re-deriving it — and so the retry/stale tuning
+ * lives in one place.
+ *
+ * The lock is taken on the file's DIRECTORY (proper-lockfile creates
+ * `<dir>.lock`), matching CronStore. Locking the directory rather than the file
+ * means a writer that creates the file for the first time is still serialized.
+ */
+/**
+ * Acquire the directory lock guarding `file`. Returns the release function.
+ *
+ * Retries for LOCK_WAIT_MS because contention here is normal (several hosts can
+ * write the same file), then throws — a caller must never silently proceed
+ * unlocked, since that is precisely the lost-update bug.
+ */
+export declare function acquireFileLock(file: string): () => void;
+/**
+ * Lock one specific path rather than its whole directory.
+ *
+ * Use when several independent resources live side by side and must NOT
+ * serialize against each other — e.g. per-repo clone dirs, where locking the
+ * shared parent would make unrelated installs queue behind one another (and
+ * would deadlock against any directory-scoped lock taken inside).
+ *
+ * `target` must already exist; proper-lockfile creates a sibling `<target>.lock`.
+ * `timeoutMs` can exceed the default when the critical section legitimately
+ * takes a while (network clone + directory swap).
+ */
+export declare function acquireLockOnPath(target: string, timeoutMs?: number): () => void;
+/** Stage to a unique temp file, then rename — never a partially written target. */
+export declare function writeFileAtomic(file: string, contents: string, mode?: number): void;
+/**
+ * Run `mutation` against the file's CURRENT on-disk content while holding the
+ * lock, then persist whatever it returns.
+ *
+ * The reload happens INSIDE the lock, which is the entire point: a caller that
+ * read the file earlier (before contending for the lock) would otherwise write
+ * back a stale snapshot and drop a concurrent writer's change.
+ *
+ * `parse` receives `undefined` when the file is missing or unreadable, so each
+ * caller decides what "empty" means. Returning `undefined` from `mutation`
+ * skips the write entirely (no-op mutations should not rewrite the file).
+ */
+export declare function mutateJsonFile<T, R = void>(file: string, options: {
+    parse: (raw: string | undefined) => T;
+    serialize: (value: T) => string;
+    mutation: (current: T) => {
+        value?: T;
+        result?: R;
+    };
+    mode?: number;
+}): R | undefined;

package/dist/utils/file-mutex.js

@@ -0,0 +1,145 @@
+/**
+ * Cross-process read-modify-write for a single JSON file.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * Several subsystems independently implemented "load → change → save" against a
+ * shared file with NO cross-process lock. Atomic tmp+rename protects against a
+ * torn file, but not against lost updates: two processes both read revision N,
+ * both write N+1, and one change vanishes. Measured on this repo: 48 concurrent
+ * writers each setting a distinct settings key left only 17 keys; 48 concurrent
+ * AutoDream increments recorded 1–2.
+ *
+ * CronStore already had the correct shape (directory lock + reload-inside-lock +
+ * unique tmp + rename). This module extracts exactly that so every writer shares
+ * one implementation instead of re-deriving it — and so the retry/stale tuning
+ * lives in one place.
+ *
+ * The lock is taken on the file's DIRECTORY (proper-lockfile creates
+ * `<dir>.lock`), matching CronStore. Locking the directory rather than the file
+ * means a writer that creates the file for the first time is still serialized.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { randomUUID } from "node:crypto";
+import { lockSync } from "./lockfile.js";
+/**
+ * How long to keep retrying the lock before giving up.
+ *
+ * Sized for real contention, not the happy path. Every holder does a bounded
+ * amount of work (re-read, merge, atomic rename), but with N writers the last
+ * one in line waits for all N-1 ahead of it. Measured here: 48 concurrent
+ * processes saving memories against one index blew through a 2s budget and up to
+ * 46 of them died with ELOCKED. 30s leaves generous headroom while still
+ * failing loudly if a holder is genuinely wedged.
+ */
+const LOCK_WAIT_MS = 30_000;
+/** A lock older than this is treated as abandoned by a crashed holder. */
+const LOCK_STALE_MS = 10_000;
+/** Backoff bounds for the retry loop (see acquireLockOn). */
+const LOCK_RETRY_MIN_MS = 5;
+const LOCK_RETRY_MAX_MS = 50;
+// Atomics.wait only ever reads slot 0, which stays 0, so one shared buffer is
+// safe and avoids allocating per retry.
+const SLEEP_SIGNAL = new Int32Array(new SharedArrayBuffer(4));
+function sleepSync(ms) {
+    Atomics.wait(SLEEP_SIGNAL, 0, 0, ms);
+}
+/**
+ * Acquire the directory lock guarding `file`. Returns the release function.
+ *
+ * Retries for LOCK_WAIT_MS because contention here is normal (several hosts can
+ * write the same file), then throws — a caller must never silently proceed
+ * unlocked, since that is precisely the lost-update bug.
+ */
+export function acquireFileLock(file) {
+    const dir = dirname(file);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    return acquireLockOn(dir, LOCK_WAIT_MS);
+}
+/**
+ * Lock one specific path rather than its whole directory.
+ *
+ * Use when several independent resources live side by side and must NOT
+ * serialize against each other — e.g. per-repo clone dirs, where locking the
+ * shared parent would make unrelated installs queue behind one another (and
+ * would deadlock against any directory-scoped lock taken inside).
+ *
+ * `target` must already exist; proper-lockfile creates a sibling `<target>.lock`.
+ * `timeoutMs` can exceed the default when the critical section legitimately
+ * takes a while (network clone + directory swap).
+ */
+export function acquireLockOnPath(target, timeoutMs = LOCK_WAIT_MS) {
+    return acquireLockOn(target, timeoutMs);
+}
+function acquireLockOn(target, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    let lastError;
+    let attempt = 0;
+    for (;;) {
+        try {
+            return lockSync(target, { stale: LOCK_STALE_MS, retries: 0 });
+        }
+        catch (err) {
+            lastError = err;
+            if (Date.now() > deadline)
+                throw lastError;
+            // Randomized backoff. A fixed delay makes every waiter wake at the same
+            // instant and collide again, so under real contention (dozens of writers)
+            // the same unlucky processes kept losing and eventually timed out.
+            // Jitter spreads the retries out; the cap keeps latency low when only a
+            // couple of writers are competing.
+            const ceiling = Math.min(LOCK_RETRY_MIN_MS * 2 ** attempt, LOCK_RETRY_MAX_MS);
+            attempt += 1;
+            sleepSync(LOCK_RETRY_MIN_MS + Math.floor(Math.random() * ceiling));
+        }
+    }
+}
+/** Stage to a unique temp file, then rename — never a partially written target. */
+export function writeFileAtomic(file, contents, mode) {
+    mkdirSync(dirname(file), { recursive: true });
+    // Unique per writer: a shared `.tmp` name lets two writers clobber each
+    // other's staging file even while both hold different locks.
+    const tmp = `${file}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+        writeFileSync(tmp, contents, mode === undefined ? "utf-8" : { encoding: "utf-8", mode });
+        renameSync(tmp, file);
+    }
+    finally {
+        rmSync(tmp, { force: true });
+    }
+}
+/**
+ * Run `mutation` against the file's CURRENT on-disk content while holding the
+ * lock, then persist whatever it returns.
+ *
+ * The reload happens INSIDE the lock, which is the entire point: a caller that
+ * read the file earlier (before contending for the lock) would otherwise write
+ * back a stale snapshot and drop a concurrent writer's change.
+ *
+ * `parse` receives `undefined` when the file is missing or unreadable, so each
+ * caller decides what "empty" means. Returning `undefined` from `mutation`
+ * skips the write entirely (no-op mutations should not rewrite the file).
+ */
+export function mutateJsonFile(file, options) {
+    const release = acquireFileLock(file);
+    try {
+        let raw;
+        try {
+            raw = readFileSync(file, "utf-8");
+        }
+        catch {
+            raw = undefined;
+        }
+        const current = options.parse(raw);
+        const { value, result } = options.mutation(current);
+        if (value !== undefined) {
+            writeFileAtomic(file, options.serialize(value), options.mode);
+        }
+        return result;
+    }
+    finally {
+        release();
+    }
+}

package/dist/utils/json.d.ts

@@ -1,10 +1,8 @@
 /**
  * Generic JSON extraction from LLM text output — strip markdown fences and
  * pull out the first balanced object/array. These are provider-agnostic and
- * have no Arena dependency; they live here (not in arena/strategies/utils.ts)
- * so non-Arena consumers (e.g. services/memory-orchestrator) can use them
- * without dragging in the Arena subsystem. Arena re-exports them for
- * back-compat.
+ * live in core so any service or extension can consume them without importing
+ * a product capability package.
  */
 /** Extract JSON from text that might have markdown fences or surrounding text. */
 export declare function extractJSON(text: string): string;

package/dist/utils/json.js

@@ -1,10 +1,8 @@
 /**
  * Generic JSON extraction from LLM text output — strip markdown fences and
  * pull out the first balanced object/array. These are provider-agnostic and
- * have no Arena dependency; they live here (not in arena/strategies/utils.ts)
- * so non-Arena consumers (e.g. services/memory-orchestrator) can use them
- * without dragging in the Arena subsystem. Arena re-exports them for
- * back-compat.
+ * live in core so any service or extension can consume them without importing
+ * a product capability package.
  */
 /** Extract JSON from text that might have markdown fences or surrounding text. */
 export function extractJSON(text) {