@cjhyy/code-shell-core 0.7.0 → 0.8.0

package/dist/session/session-message.d.ts

@@ -0,0 +1,22 @@
+/** A host-authorized project Session that may receive a model-sent message. */
+export interface SessionMessageTarget {
+    sessionId: string;
+    title: string;
+    workspaceRoot: string;
+    workspaceProfile?: string;
+}
+export interface RouteSessionMessageInput {
+    sourceSessionId: string;
+    target: SessionMessageTarget;
+    message: string;
+    /** Full same-project catalog so the target can send a later message onward. */
+    catalog: readonly SessionMessageTarget[];
+}
+export type SessionMessageRouter = (input: RouteSessionMessageInput) => Promise<void>;
+export interface SessionMessageToolService {
+    targets: readonly SessionMessageTarget[];
+    send(input: {
+        targetSessionId: string;
+        message: string;
+    }): Promise<SessionMessageTarget>;
+}

package/dist/session/session-message.js

@@ -0,0 +1 @@
+export {};

package/dist/session/transcript.d.ts

@@ -3,12 +3,55 @@
  * toMessages() derives Message[] from events for sending to LLM.
  */
 import type { TranscriptEvent, TranscriptEventType, Message, ContentBlock } from "../types.js";
+import type { EngineResult } from "../engine/types.js";
+type TranscriptWriter = (filePath: string, data: string, encoding: "utf-8") => void;
+type ParsedEvents = {
+    events: TranscriptEvent[];
+    malformedLineCount: number;
+};
+export interface TranscriptFlushFailure {
+    errno: string | number;
+    code?: string;
+    message: string;
+    timestamp: number;
+    attempts: 2;
+    recoverable: false;
+    filePath: string;
+}
+export interface ContextEventRange {
+    fromEventId: string;
+    toEventId: string;
+}
+export interface SelectedContextRange {
+    events: TranscriptEvent[];
+    messages: Message[];
+    sourceEventCount: number;
+}
+export type SummaryAppendMetadata = {
+    fromTurn: number;
+    toTurn: number;
+    eventCount: number;
+} | {
+    trigger: "context_transfer";
+    sourceRange: {
+        sessionId: string;
+        fromEventId: string;
+        toEventId: string;
+    };
+    sourceEventCount: number;
+    estimatedTokens: number;
+    summaryVersion: number;
+    summaryHash: string;
+};
 export declare class Transcript {
     private events;
     private filePath;
     private currentTurn;
+    private readonly writer;
+    private dirty;
+    private lastFlushFailure;
     getFilePath(): string;
-    constructor(filePath: string);
+    constructor(filePath: string, writer?: TranscriptWriter);
     append(type: TranscriptEventType, data: Record<string, unknown>): TranscriptEvent;
     /**
      * Append a chat message to the transcript.
@@ -24,8 +67,21 @@ export declare class Transcript {
         injected?: boolean;
         steerId?: string;
         clientMessageId?: string;
+        displayText?: string;
+        authority?: "user" | "agent" | "system" | "policy";
+        source?: "agent-direction" | "goal-control";
+        envelopeIds?: string[];
+        correlationIds?: string[];
     }): TranscriptEvent;
     hasClientMessageId(clientMessageId: string): boolean;
+    /**
+     * Persist the exact response associated with one idempotent submit. The
+     * receipt stays outside toMessages(), so replay support does not change the
+     * model's conversation history.
+     */
+    appendRunResult(clientMessageId: string, result: EngineResult): TranscriptEvent;
+    /** Return the newest valid durable response for an idempotent submit. */
+    findRunResultByClientMessageId(clientMessageId: string): EngineResult | undefined;
     appendToolUse(toolName: string, toolCallId: string, args: Record<string, unknown>): TranscriptEvent;
     appendToolResult(toolCallId: string, toolName: string, result?: string, error?: string, contentBlocks?: ContentBlock[]): TranscriptEvent;
     /** Anchor for a spawned sub-agent (see TranscriptEventType "subagent").
@@ -41,11 +97,7 @@ export declare class Transcript {
      * can hit more than one abort return for a single Stop).
      */
     appendTurnStopped(): TranscriptEvent | undefined;
-    appendSummary(summary: string, compactedRange: {
-        fromTurn: number;
-        toTurn: number;
-        eventCount: number;
-    }): TranscriptEvent;
+    appendSummary(summary: string, metadata: SummaryAppendMetadata): TranscriptEvent;
     appendError(error: string, details?: Record<string, unknown>): TranscriptEvent;
     /**
      * Derive Message[] from transcript events for sending to the LLM.
@@ -55,13 +107,31 @@ export declare class Transcript {
     getEvents(type?: TranscriptEventType): TranscriptEvent[];
     get turnNumber(): number;
     get eventCount(): number;
+    /** True once any event failed both persistence attempts. Sticky by design. */
+    flushFailed(): boolean;
+    /** Structured details for the most recent unrecoverable flush failure. */
+    getFlushFailure(): TranscriptFlushFailure | undefined;
     private findMessageByClientId;
     private flush;
+    private errorErrno;
+    private errorMessage;
     /**
      * Repair tool_result pairing issues:
      * - Orphaned tool_results (no matching tool_use) get removed
      * - Missing tool_results (tool_use with no result) get synthetic error results
      */
     repairToolResultPairs(): void;
+    static readEvents(filePath: string): ParsedEvents;
+    static eventsToMessages(events: readonly TranscriptEvent[]): Array<{
+        role: string;
+        content: string | ContentBlock[];
+    }>;
+    /**
+     * Select one inclusive, stable event-id range and project only LLM-context
+     * events from it. Audit/UI events remain part of sourceEventCount but never
+     * enter the package prompt.
+     */
+    static selectContextRange(events: readonly TranscriptEvent[], range: ContextEventRange): SelectedContextRange;
     static loadFromFile(filePath: string): Transcript;
 }
+export {};

package/dist/session/transcript.js

@@ -6,15 +6,26 @@ import { appendFileSync, readFileSync, existsSync, mkdirSync, writeFileSync } fr
 import { dirname } from "node:path";
 import { nanoid } from "nanoid";
 import { logger } from "../logging/logger.js";
+const CONTEXT_EVENT_TYPES = new Set([
+    "message",
+    "tool_use",
+    "tool_result",
+    "summary",
+    "context_transfer",
+]);
 export class Transcript {
     events = [];
     filePath;
     currentTurn = 0;
+    writer;
+    dirty = false;
+    lastFlushFailure;
     getFilePath() {
         return this.filePath;
     }
-    constructor(filePath) {
+    constructor(filePath, writer = appendFileSync) {
         this.filePath = filePath;
+        this.writer = writer;
         mkdirSync(dirname(filePath), { recursive: true });
         if (!existsSync(filePath)) {
             writeFileSync(filePath, "", "utf-8");
@@ -60,11 +71,37 @@ export class Transcript {
             ...(opts?.injected ? { injected: true } : {}),
             ...(opts?.steerId ? { steerId: opts.steerId } : {}),
             ...(opts?.clientMessageId ? { clientMessageId: opts.clientMessageId } : {}),
+            ...(opts?.displayText ? { displayText: opts.displayText } : {}),
+            ...(opts?.authority ? { authority: opts.authority } : {}),
+            ...(opts?.source ? { source: opts.source } : {}),
+            ...(opts?.envelopeIds ? { envelopeIds: opts.envelopeIds } : {}),
+            ...(opts?.correlationIds ? { correlationIds: opts.correlationIds } : {}),
         });
     }
     hasClientMessageId(clientMessageId) {
         return this.findMessageByClientId(clientMessageId) !== undefined;
     }
+    /**
+     * Persist the exact response associated with one idempotent submit. The
+     * receipt stays outside toMessages(), so replay support does not change the
+     * model's conversation history.
+     */
+    appendRunResult(clientMessageId, result) {
+        return this.append("run_result", { clientMessageId, result });
+    }
+    /** Return the newest valid durable response for an idempotent submit. */
+    findRunResultByClientMessageId(clientMessageId) {
+        for (let index = this.events.length - 1; index >= 0; index -= 1) {
+            const event = this.events[index];
+            if (event.type !== "run_result" || event.data.clientMessageId !== clientMessageId)
+                continue;
+            const result = event.data.result;
+            if (!isEngineResultReceipt(result))
+                return undefined;
+            return result;
+        }
+        return undefined;
+    }
     appendToolUse(toolName, toolCallId, args) {
         return this.append("tool_use", { toolName, toolCallId, args });
     }
@@ -100,11 +137,15 @@ export class Transcript {
             return undefined;
         return this.append("turn_stopped", {});
     }
-    appendSummary(summary, compactedRange) {
+    appendSummary(summary, metadata) {
+        if ("trigger" in metadata) {
+            const { trigger: _trigger, ...provenance } = metadata;
+            return this.append("context_transfer", { summary, ...provenance });
+        }
         return this.append("summary", {
             summary,
             trigger: "auto",
-            compactedRange,
+            compactedRange: metadata,
             preservedSegment: {
                 headEventId: this.events[0]?.id,
                 tailEventId: this.events[this.events.length - 1]?.id,
@@ -162,7 +203,17 @@ export class Transcript {
                     });
                     break;
                 }
-                // turn_boundary, session_meta, file_history, plan_operation, error
+                case "context_transfer": {
+                    const { summary, handoffId } = event.data;
+                    messages.push({
+                        role: "user",
+                        content: handoffId
+                            ? `<system-reminder>Session handoff received:\n${summary}</system-reminder>`
+                            : `<system-reminder>Background context transferred from a selected conversation range:\n${summary}</system-reminder>`,
+                    });
+                    break;
+                }
+                // turn_boundary, run_result, session_meta, file_history, plan_operation, error
                 // are not included in LLM messages
             }
         }
@@ -179,18 +230,65 @@ export class Transcript {
     get eventCount() {
         return this.events.length;
     }
+    /** True once any event failed both persistence attempts. Sticky by design. */
+    flushFailed() {
+        return this.dirty;
+    }
+    /** Structured details for the most recent unrecoverable flush failure. */
+    getFlushFailure() {
+        return this.lastFlushFailure ? { ...this.lastFlushFailure } : undefined;
+    }
     findMessageByClientId(clientMessageId) {
         return this.events.find((event) => event.type === "message" &&
             event.data.clientMessageId === clientMessageId);
     }
     flush(event) {
+        const line = JSON.stringify(event) + "\n";
         try {
-            appendFileSync(this.filePath, JSON.stringify(event) + "\n", "utf-8");
+            this.writer(this.filePath, line, "utf-8");
+            return true;
         }
-        catch {
-            // Silently fail on flush errors — events are still in memory
+        catch (firstError) {
+            try {
+                this.writer(this.filePath, line, "utf-8");
+                logger.warn("transcript.flush_retry_recovered", {
+                    filePath: this.filePath,
+                    errno: this.errorErrno(firstError),
+                    message: this.errorMessage(firstError),
+                });
+                return true;
+            }
+            catch (retryError) {
+                const err = retryError;
+                const failure = {
+                    errno: this.errorErrno(retryError),
+                    ...(typeof err?.code === "string" ? { code: err.code } : {}),
+                    message: this.errorMessage(retryError),
+                    timestamp: Date.now(),
+                    attempts: 2,
+                    recoverable: false,
+                    filePath: this.filePath,
+                };
+                // Sticky: a later successful append cannot restore an earlier missing
+                // JSONL event, so the transcript remains degraded for this instance.
+                this.dirty = true;
+                this.lastFlushFailure = failure;
+                logger.error("transcript.flush_failed", { ...failure });
+                return false;
+            }
         }
     }
+    errorErrno(error) {
+        const err = error;
+        if (typeof err?.errno === "number" || typeof err?.errno === "string")
+            return err.errno;
+        if (typeof err?.code === "string")
+            return err.code;
+        return "UNKNOWN";
+    }
+    errorMessage(error) {
+        return error instanceof Error ? error.message : String(error);
+    }
     /**
      * Repair tool_result pairing issues:
      * - Orphaned tool_results (no matching tool_use) get removed
@@ -227,6 +325,111 @@ export class Transcript {
             return true;
         });
     }
+    static readEvents(filePath) {
+        let raw;
+        try {
+            raw = readFileSync(filePath, "utf-8");
+        }
+        catch {
+            return { events: [], malformedLineCount: 0 };
+        }
+        const lines = raw.split("\n").filter((line) => line.trim().length > 0);
+        const events = [];
+        let malformedLineCount = 0;
+        for (const line of lines) {
+            try {
+                events.push(JSON.parse(line));
+            }
+            catch {
+                malformedLineCount++;
+            }
+        }
+        return { events, malformedLineCount };
+    }
+    static eventsToMessages(events) {
+        const messages = [];
+        for (const event of events) {
+            switch (event.type) {
+                case "message": {
+                    const { role, content } = event.data;
+                    messages.push({ role, content });
+                    break;
+                }
+                case "tool_use":
+                    break;
+                case "tool_result": {
+                    const { toolCallId, result, error, contentBlocks } = event.data;
+                    const block = {
+                        type: "tool_result",
+                        tool_use_id: toolCallId,
+                        content: error
+                            ? `Error: ${error}`
+                            : Array.isArray(contentBlocks) && contentBlocks.length > 0
+                                ? contentBlocks
+                                : (result ?? "(no output)"),
+                    };
+                    const last = messages[messages.length - 1];
+                    if (last?.role === "user" && Array.isArray(last.content)) {
+                        last.content.push(block);
+                    }
+                    else {
+                        messages.push({ role: "user", content: [block] });
+                    }
+                    break;
+                }
+                case "summary": {
+                    const { summary } = event.data;
+                    messages.push({
+                        role: "user",
+                        content: `<system-reminder>Previous conversation was summarized:\n${summary}</system-reminder>`,
+                    });
+                    break;
+                }
+                case "context_transfer": {
+                    const { summary, handoffId } = event.data;
+                    messages.push({
+                        role: "user",
+                        content: handoffId
+                            ? `<system-reminder>Session handoff received:\n${summary}</system-reminder>`
+                            : `<system-reminder>Background context transferred from a selected conversation range:\n${summary}</system-reminder>`,
+                    });
+                    break;
+                }
+            }
+        }
+        return messages;
+    }
+    /**
+     * Select one inclusive, stable event-id range and project only LLM-context
+     * events from it. Audit/UI events remain part of sourceEventCount but never
+     * enter the package prompt.
+     */
+    static selectContextRange(events, range) {
+        const fromMatches = events
+            .map((event, index) => (event.id === range.fromEventId ? index : -1))
+            .filter((index) => index >= 0);
+        const toMatches = events
+            .map((event, index) => (event.id === range.toEventId ? index : -1))
+            .filter((index) => index >= 0);
+        if (fromMatches.length !== 1 || toMatches.length !== 1) {
+            throw new Error("Context range endpoints must each identify exactly one source event");
+        }
+        const fromIndex = fromMatches[0];
+        const toIndex = toMatches[0];
+        if (fromIndex > toIndex)
+            throw new Error("Context range endpoints are out of order");
+        const frozen = structuredClone(events.slice(fromIndex, toIndex + 1));
+        if (frozen[0]?.type === "session_meta" || frozen.at(-1)?.type === "session_meta") {
+            throw new Error("Context range cannot use session metadata as a boundary");
+        }
+        const selected = frozen.filter((event) => CONTEXT_EVENT_TYPES.has(event.type));
+        validateSelectedToolPairs(selected);
+        return {
+            events: selected,
+            messages: Transcript.eventsToMessages(selected),
+            sourceEventCount: frozen.length,
+        };
+    }
     static loadFromFile(filePath) {
         const transcript = new Transcript(filePath);
         if (!existsSync(filePath))
@@ -250,3 +453,71 @@ export class Transcript {
         return transcript;
     }
 }
+function isEngineResultReceipt(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const result = value;
+    const usage = result.usage;
+    return (typeof result.text === "string" &&
+        typeof result.reason === "string" &&
+        typeof result.sessionId === "string" &&
+        typeof result.turnCount === "number" &&
+        Number.isSafeInteger(result.turnCount) &&
+        Boolean(usage) &&
+        typeof usage?.promptTokens === "number" &&
+        typeof usage?.completionTokens === "number" &&
+        typeof usage?.totalTokens === "number");
+}
+function validateSelectedToolPairs(events) {
+    const providerUses = [];
+    const metadataUses = [];
+    const results = [];
+    for (const event of events) {
+        if (event.type === "message") {
+            const content = event.data.content;
+            if (!Array.isArray(content))
+                continue;
+            for (const block of content) {
+                if (block.type === "tool_use" && typeof block.id === "string")
+                    providerUses.push(block.id);
+            }
+        }
+        else if (event.type === "tool_use") {
+            if (typeof event.data.toolCallId === "string")
+                metadataUses.push(event.data.toolCallId);
+        }
+        else if (event.type === "tool_result") {
+            if (typeof event.data.toolCallId === "string")
+                results.push(event.data.toolCallId);
+        }
+    }
+    if (new Set(providerUses).size !== providerUses.length) {
+        throw new Error("Context range contains duplicate provider tool metadata");
+    }
+    if (new Set(metadataUses).size !== metadataUses.length) {
+        throw new Error("Context range contains duplicate tool metadata");
+    }
+    if (new Set(results).size !== results.length) {
+        throw new Error("Context range contains duplicate tool results");
+    }
+    if (providerUses.length !== metadataUses.length ||
+        providerUses.some((id, index) => metadataUses[index] !== id)) {
+        throw new Error("Context range has orphaned or mismatched tool metadata");
+    }
+    const pending = new Set();
+    for (const event of events) {
+        if (event.type === "tool_use") {
+            const id = event.data.toolCallId;
+            if (typeof id === "string")
+                pending.add(id);
+        }
+        else if (event.type === "tool_result") {
+            const id = event.data.toolCallId;
+            if (typeof id !== "string" || !pending.delete(id)) {
+                throw new Error("Context range contains an orphaned or out-of-order tool result");
+            }
+        }
+    }
+    if (pending.size > 0)
+        throw new Error("Context range ends with an unfinished tool round");
+}

package/dist/settings/feature-flags.d.ts

@@ -43,6 +43,46 @@ export declare const FEATURE_FLAGS: {
         readonly default: false;
         readonly description: "Capture full command stdout/stderr snapshots";
     };
+    /**
+     * Run a session on an EXTERNAL Agent Runtime (Codex / Claude Code) instead of
+     * the native Engine.
+     *
+     * Default ON, which reverses the original §20 decision. The reasoning behind
+     * "off" was that the native path must not depend on an external binary — that
+     * still holds, and is now enforced by a better mechanism than a flag: the
+     * picker only lists a runtime whose binary is actually installed
+     * (external-runtime-availability.ts), and every non-prefixed model key still
+     * routes to the native Engine. A machine without `codex` sees exactly what it
+     * saw before.
+     *
+     * What the flag actually did in practice was hide the feature from everyone,
+     * including the people who installed Codex on purpose: the entries never
+     * appeared, with no hint that a setting was responsible. An opt-in nobody can
+     * discover is indistinguishable from a missing feature.
+     *
+     * Turning it off remains the escape hatch — it hides the entries outright.
+     */
+    readonly external_agent_runtime: {
+        readonly default: true;
+        readonly description: "Allow a session to run on Codex or Claude Code instead of the native engine";
+    };
+    /**
+     * Expose CodeShell Host Tools to an external runtime. Separate from the flag
+     * above so the runtime can be trialled with NO tool surface at all — §20 asks
+     * for exactly that split, because the tool bridge is the part that carries the
+     * security burden.
+     *
+     * Also default ON now, for a blunt reason: with it off the runtime has an
+     * EMPTY tool surface — no skills, no memory, no file access — which is not a
+     * usable Agent Runtime, so shipping that as the default just means the
+     * feature appears broken. Every exposed tool still executes through
+     * ToolExecutor, so the user's permission rules and the approval dialog apply
+     * exactly as they do on the native path.
+     */
+    readonly external_host_tools: {
+        readonly default: true;
+        readonly description: "Expose allowlisted CodeShell tools to an external Agent Runtime";
+    };
 };
 export type FeatureFlagName = keyof typeof FEATURE_FLAGS;
 /** The settings overlay shape: a partial map of known flags → boolean. */

package/dist/settings/feature-flags.js

@@ -28,6 +28,46 @@ export const FEATURE_FLAGS = {
     undo: { default: false, description: "Per-session file undo (/undo)" },
     /** Shell snapshot: capture full stdout/stderr of commands. */
     shell_snapshot: { default: false, description: "Capture full command stdout/stderr snapshots" },
+    /**
+     * Run a session on an EXTERNAL Agent Runtime (Codex / Claude Code) instead of
+     * the native Engine.
+     *
+     * Default ON, which reverses the original §20 decision. The reasoning behind
+     * "off" was that the native path must not depend on an external binary — that
+     * still holds, and is now enforced by a better mechanism than a flag: the
+     * picker only lists a runtime whose binary is actually installed
+     * (external-runtime-availability.ts), and every non-prefixed model key still
+     * routes to the native Engine. A machine without `codex` sees exactly what it
+     * saw before.
+     *
+     * What the flag actually did in practice was hide the feature from everyone,
+     * including the people who installed Codex on purpose: the entries never
+     * appeared, with no hint that a setting was responsible. An opt-in nobody can
+     * discover is indistinguishable from a missing feature.
+     *
+     * Turning it off remains the escape hatch — it hides the entries outright.
+     */
+    external_agent_runtime: {
+        default: true,
+        description: "Allow a session to run on Codex or Claude Code instead of the native engine",
+    },
+    /**
+     * Expose CodeShell Host Tools to an external runtime. Separate from the flag
+     * above so the runtime can be trialled with NO tool surface at all — §20 asks
+     * for exactly that split, because the tool bridge is the part that carries the
+     * security burden.
+     *
+     * Also default ON now, for a blunt reason: with it off the runtime has an
+     * EMPTY tool surface — no skills, no memory, no file access — which is not a
+     * usable Agent Runtime, so shipping that as the default just means the
+     * feature appears broken. Every exposed tool still executes through
+     * ToolExecutor, so the user's permission rules and the approval dialog apply
+     * exactly as they do on the native path.
+     */
+    external_host_tools: {
+        default: true,
+        description: "Expose allowlisted CodeShell tools to an external Agent Runtime",
+    },
 };
 /** All known flag names, for iteration (e.g. the /features listing). */
 export function featureFlagNames() {

package/dist/settings/manager.d.ts

@@ -71,6 +71,15 @@ export declare class SettingsManager {
      * host (desktop) passes the real trust decision from its trust-store.
      */
     private readonly projectTrusted;
+    /**
+     * Override the user-level config directory (the `~/.code-shell` layer:
+     * settings.managed.json / settings.json live directly inside it). When
+     * absent the manager keeps today's behavior — `join(userHome(),
+     * ".code-shell")` resolved per call so `$HOME` overrides still work.
+     * Injection point for identity-scoped server deployments (a per-user
+     * worker passes `<dataRoot>` here instead of relocating `$HOME`).
+     */
+    private readonly userConfigDirOverride?;
     private sources;
     private merged;
     constructor(cwd?: string, scope?: SettingsScope, 
@@ -86,7 +95,18 @@ export declare class SettingsManager {
      * Defaults to `true` so existing embedders/tests keep their behavior; the
      * host (desktop) passes the real trust decision from its trust-store.
      */
-    projectTrusted?: boolean);
+    projectTrusted?: boolean, 
+    /**
+     * Override the user-level config directory (the `~/.code-shell` layer:
+     * settings.managed.json / settings.json live directly inside it). When
+     * absent the manager keeps today's behavior — `join(userHome(),
+     * ".code-shell")` resolved per call so `$HOME` overrides still work.
+     * Injection point for identity-scoped server deployments (a per-user
+     * worker passes `<dataRoot>` here instead of relocating `$HOME`).
+     */
+    userConfigDirOverride?: string | undefined);
+    /** User-layer config dir: explicit override wins, else `~/.code-shell`. */
+    private userConfigDir;
     /**
      * Load settings from all sources.
      */
@@ -143,6 +163,24 @@ export declare class SettingsManager {
     private projectSettingsPath;
     private readJsonObject;
     private atomicWriteJson;
+    /**
+     * Read-modify-write a settings file under a cross-process lock.
+     *
+     * Atomic rename alone only prevents a half-written file; it does NOT prevent a
+     * lost update. Every writer here used to read its own snapshot outside any
+     * lock, so two processes changing DIFFERENT keys still clobbered each other:
+     * 48 concurrent writers each setting a distinct key left only 17 keys on disk.
+     *
+     * Real multi-writer paths, not a theoretical concern: the desktop settings
+     * page, the Agent `Config` tool, an automation worker, the TUI and a second
+     * desktop instance all write the same files. The desktop settings service
+     * already locked correctly; this brings Core's own writers onto the same
+     * protocol so they interlock rather than race past one another.
+     *
+     * `mutate` receives the CURRENT on-disk object (re-read inside the lock) and
+     * mutates it in place; returning false skips the write.
+     */
+    private mutateSettingsFile;
     private loadJsonFile;
     private deepMerge;
 }