@cjhyy/code-shell-core 0.5.0-rc.0 → 0.5.0-rc.2

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

@@ -7,6 +7,28 @@ export interface SessionBundle {
     state: SessionState;
     transcript: Transcript;
 }
+/**
+ * Validate a session ID before it is joined into a filesystem path.
+ *
+ * Internally generated IDs use `nanoid(16)` and are trusted by construction.
+ * But every public entry point (`create`'s explicitSessionId, `resume`,
+ * `exists`, `saveState`'s state.sessionId, `fork`'s sourceSessionId) accepts
+ * an ID from an outside caller — protocol clients, ChatSessionManager-driven
+ * cold starts, persisted state files — and join()'s it into `sessionsDir`.
+ * Without this check a value like "../etc/passwd" or "/tmp/x" would let the
+ * caller escape the sessions directory.
+ *
+ * Exported for direct unit testing.
+ */
+export declare function assertSafeSessionId(sessionId: unknown): asserts sessionId is string;
+/**
+ * Resolve the `.code-shell` home dir. `CODE_SHELL_HOME` overrides the default
+ * `~/.code-shell` — mirrors Codex's `CODEX_HOME`. Tests set it to a temp dir
+ * (see bunfig.toml preload) so a `new Engine()` / `new SessionManager()` with
+ * no explicit storageDir doesn't pollute the user's real ~/.code-shell/sessions
+ * with throwaway test sessions (the rm-usage/test-model sidebar junk).
+ */
+export declare function codeShellHome(): string;
 export declare class SessionManager {
     private readonly sessionsDir;
     constructor(storageDir?: string);
@@ -17,7 +39,7 @@ export declare class SessionManager {
      * nanoid. Either way the on-disk directory is materialized and the
      * state.json + transcript.jsonl files are written before return.
      */
-    create(cwd: string, model: string, provider: string, explicitSessionId?: string): SessionBundle;
+    create(cwd: string, model: string, provider: string, explicitSessionId?: string, parentSessionId?: string | null, origin?: import("../types.js").SessionOrigin): SessionBundle;
     /**
      * Whether a session directory exists on disk. Used by ChatSession-driven
      * cold starts to decide between resume vs create-with-explicit-sid

package/dist/session/session-manager.js

@@ -7,10 +7,57 @@ import { homedir } from "node:os";
 import { nanoid } from "nanoid";
 import { Transcript } from "./transcript.js";
 import { SessionError } from "../exceptions.js";
+/**
+ * Validate a session ID before it is joined into a filesystem path.
+ *
+ * Internally generated IDs use `nanoid(16)` and are trusted by construction.
+ * But every public entry point (`create`'s explicitSessionId, `resume`,
+ * `exists`, `saveState`'s state.sessionId, `fork`'s sourceSessionId) accepts
+ * an ID from an outside caller — protocol clients, ChatSessionManager-driven
+ * cold starts, persisted state files — and join()'s it into `sessionsDir`.
+ * Without this check a value like "../etc/passwd" or "/tmp/x" would let the
+ * caller escape the sessions directory.
+ *
+ * Exported for direct unit testing.
+ */
+export function assertSafeSessionId(sessionId) {
+    if (typeof sessionId !== "string" || sessionId.length === 0) {
+        throw new SessionError(`invalid session id: must be a non-empty string`);
+    }
+    // basename check: reject any path-shaped value. Covers absolute paths,
+    // POSIX and Windows separators, parent-dir tokens, and the lone "..".
+    if (sessionId.includes("/") || sessionId.includes("\\")) {
+        throw new SessionError(`invalid session id: contains path separator: ${sessionId}`);
+    }
+    if (sessionId === "." || sessionId === ".." || sessionId.includes("..")) {
+        throw new SessionError(`invalid session id: contains parent-dir token: ${sessionId}`);
+    }
+    // Conservative character allow-list: letters, digits, and `-_.` only.
+    // This matches what nanoid emits plus the dotted variants in-house code
+    // already uses (e.g. "tui-main", "agent.foo"). Anything else (NUL,
+    // newline, control chars, shell metacharacters, glob chars) is rejected.
+    if (!/^[A-Za-z0-9_.-]+$/.test(sessionId)) {
+        throw new SessionError(`invalid session id: unexpected characters: ${sessionId}`);
+    }
+    // Cap the length to keep filesystem APIs happy and avoid disk-name DoS.
+    if (sessionId.length > 128) {
+        throw new SessionError(`invalid session id: too long (max 128 chars)`);
+    }
+}
+/**
+ * Resolve the `.code-shell` home dir. `CODE_SHELL_HOME` overrides the default
+ * `~/.code-shell` — mirrors Codex's `CODEX_HOME`. Tests set it to a temp dir
+ * (see bunfig.toml preload) so a `new Engine()` / `new SessionManager()` with
+ * no explicit storageDir doesn't pollute the user's real ~/.code-shell/sessions
+ * with throwaway test sessions (the rm-usage/test-model sidebar junk).
+ */
+export function codeShellHome() {
+    return process.env.CODE_SHELL_HOME || join(homedir(), ".code-shell");
+}
 export class SessionManager {
     sessionsDir;
     constructor(storageDir) {
-        this.sessionsDir = storageDir ?? join(homedir(), ".code-shell", "sessions");
+        this.sessionsDir = storageDir ?? join(codeShellHome(), "sessions");
         mkdirSync(this.sessionsDir, { recursive: true });
     }
     /**
@@ -20,7 +67,12 @@ export class SessionManager {
      * nanoid. Either way the on-disk directory is materialized and the
      * state.json + transcript.jsonl files are written before return.
      */
-    create(cwd, model, provider, explicitSessionId) {
+    create(cwd, model, provider, explicitSessionId, parentSessionId, origin) {
+        // External callers may pass any string; nanoid output is trusted. Either
+        // way the ID gets joined into a filesystem path, so the public entry
+        // point validates before that join.
+        if (explicitSessionId !== undefined)
+            assertSafeSessionId(explicitSessionId);
         const sessionId = explicitSessionId ?? nanoid(16);
         const sessionDir = join(this.sessionsDir, sessionId);
         mkdirSync(sessionDir, { recursive: true });
@@ -34,6 +86,12 @@ export class SessionManager {
             turnCount: 0,
             invokedSkills: [],
             status: "active",
+            // Always write the key: a sub-agent gets its parent sid; a top-level
+            // session gets explicit null. This lets the desktop disk-rebuild tell a
+            // new top-level session (key present, null) apart from a legacy session
+            // (key absent) and from a sub-agent (key present, non-empty string).
+            parentSessionId: parentSessionId ?? null,
+            ...(origin ? { origin } : {}),
         };
         writeFileSync(join(sessionDir, "state.json"), JSON.stringify(state, null, 2), "utf-8");
         const transcript = new Transcript(join(sessionDir, "transcript.jsonl"));
@@ -52,9 +110,19 @@ export class SessionManager {
      * without catching SessionError.
      */
     exists(sessionId) {
+        // exists() is a probe — callers use it to decide between resume and
+        // create-with-explicit-sid. Treat an invalid id as "not present"
+        // rather than letting the traversal-shaped string reach existsSync.
+        try {
+            assertSafeSessionId(sessionId);
+        }
+        catch {
+            return false;
+        }
         return existsSync(join(this.sessionsDir, sessionId));
     }
     resume(sessionId) {
+        assertSafeSessionId(sessionId);
         const sessionDir = join(this.sessionsDir, sessionId);
         if (!existsSync(sessionDir)) {
             throw new SessionError(`Session not found: ${sessionId}`);
@@ -70,6 +138,9 @@ export class SessionManager {
         return { state, transcript };
     }
     saveState(state) {
+        // state.sessionId could come from a deserialized state.json that was
+        // tampered with on disk. Validate before joining.
+        assertSafeSessionId(state.sessionId);
         const sessionDir = join(this.sessionsDir, state.sessionId);
         mkdirSync(sessionDir, { recursive: true });
         // Atomic write: stage to .tmp, then rename. Protects against two processes

package/dist/settings/disk-defaults.d.ts

@@ -0,0 +1,35 @@
+import type { ValidatedSettings } from "./schema.js";
+import type { EngineConfig } from "../engine/engine.js";
+/**
+ * The subset of EngineConfig the config hot-reload ("layer 2") pushes onto an
+ * already-running session's `this.config`. These are the "disk-default" fields:
+ * read from settings.json at construction, otherwise frozen for the session's
+ * life. Request-override fields (permissionMode / goal / maxTurns /
+ * maxContextTokens / cwd) are intentionally excluded — those are per-request
+ * and handled by handleConfigure / run() options, not by disk hot-push.
+ *
+ * Reload semantics per field (see Engine.refreshRuntimeConfig):
+ *   - preset: system-prompt / behavior hot-reloads (next-turn PromptComposer
+ *     re-resolves it); the builtin TOOL SET it implies needs a session restart
+ *     (registry is ctor-frozen, possibly shared via runtime).
+ *   - customSystemPrompt / appendSystemPrompt / responseLanguage / userProfile:
+ *     hot — re-read by the next-turn PromptComposer.
+ *
+ * IMPORTANT (#8): every field here is pushed as a PURE DISK value and will
+ * OVERRIDE any per-request slice override of the same field on the running
+ * session. Safe for the desktop host today (its slice carries only
+ * permissionMode+cwd, both excluded above). A future host that sets any of
+ * these per-request MUST exclude that field from the reload patch — or track
+ * per-request overrides separately — to avoid the reload clobbering it.
+ */
+export type DiskDefaultPatch = Pick<EngineConfig, "preset" | "customSystemPrompt" | "appendSystemPrompt" | "responseLanguage" | "userProfile" | "instructions" | "mcpServers">;
+/**
+ * Derive the disk-default config patch from freshly-read settings.
+ *
+ * This MUST mirror how `agent-server-stdio.ts`'s engineFactory builds these
+ * same fields from `settings.agent` + `mergePluginMcpServers(...)`, so a
+ * reloaded running session and a newly-created session converge on identical
+ * config (no divergence). It reuses `personalizationFrom` for the three
+ * personalization fields rather than duplicating the mapping.
+ */
+export declare function diskDefaultsFrom(settings: ValidatedSettings): DiskDefaultPatch;

package/dist/settings/disk-defaults.js

@@ -0,0 +1,24 @@
+import { personalizationFrom } from "./personalization.js";
+import { mergePluginMcpServers } from "../plugins/installer/loadPluginMcp.js";
+/**
+ * Derive the disk-default config patch from freshly-read settings.
+ *
+ * This MUST mirror how `agent-server-stdio.ts`'s engineFactory builds these
+ * same fields from `settings.agent` + `mergePluginMcpServers(...)`, so a
+ * reloaded running session and a newly-created session converge on identical
+ * config (no divergence). It reuses `personalizationFrom` for the three
+ * personalization fields rather than duplicating the mapping.
+ */
+export function diskDefaultsFrom(settings) {
+    const agent = settings.agent ?? {};
+    return {
+        preset: agent.preset,
+        customSystemPrompt: agent.customSystemPrompt,
+        appendSystemPrompt: agent.appendSystemPrompt,
+        ...personalizationFrom(agent),
+        // Same merge engineFactory uses: user-configured servers + enabled
+        // plugins' servers. Plugin servers a disabled plugin would contribute are
+        // skipped, matching new-session construction.
+        mcpServers: mergePluginMcpServers(settings.mcpServers ?? {}, settings.disabledPlugins ?? []),
+    };
+}

package/dist/settings/manager.d.ts

@@ -4,12 +4,31 @@
  * Priority: CLI flags > local > project > user > managed
  */
 import { type ValidatedSettings } from "./schema.js";
+/**
+ * Resolve the user's home directory. Prefers `process.env.HOME` so that
+ * runtime env overrides (set after process start, e.g. in tests) actually
+ * take effect — on some runtimes (e.g. Bun on macOS) `os.homedir()` is
+ * cached from the user database at process startup and ignores later
+ * `process.env.HOME` mutations.
+ */
+export declare function userHome(): string;
 export type SettingsSourceName = "managed" | "user" | "project" | "local" | "flag";
+/**
+ * Which disk layers a SettingsManager is allowed to read.
+ *   'full'     — managed + user (~/.code-shell) + project + local (host terminal entrypoints)
+ *   'project'  — project + local only (${cwd}/.code-shell); never the host user dir. [default]
+ *   'isolated' — no disk layers at all; only explicit flag overrides.
+ * Flag overrides always apply regardless of scope. Default is 'project' so a
+ * codeshell library/SDK embedding never silently inherits the host user's
+ * personal ~/.code-shell config (keys, models, MCP servers, hooks).
+ */
+export type SettingsScope = "isolated" | "project" | "full";
 export declare class SettingsManager {
     private readonly cwd;
+    private readonly scope;
     private sources;
     private merged;
-    constructor(cwd?: string);
+    constructor(cwd?: string, scope?: SettingsScope);
     /**
      * Load settings from all sources.
      */
@@ -31,6 +50,31 @@ export declare class SettingsManager {
      * The merged cache is invalidated so the next get() picks up the change.
      */
     saveUserSetting(key: string, value: unknown): void;
+    /**
+     * Persist a single setting (dotted key path) to the PROJECT-level config
+     * file at ${cwd}/.code-shell/settings.json. This is where capabilityOverrides
+     * live — project overlays never touch the global user file. Atomic write +
+     * cache invalidation mirror saveUserSetting.
+     */
+    saveProjectSetting(key: string, value: unknown, cwd: string): void;
+    /**
+     * Delete a single dotted key from the PROJECT-level config file. Used to
+     * express "inherit" — we don't persist the literal "inherit"; we remove the
+     * override key. No-ops if the file or any intermediate segment is absent.
+     */
+    deleteProjectSetting(key: string, cwd: string): void;
+    /**
+     * Read ONE scope's raw settings file, validated but UNMERGED. Capability
+     * overlay math needs the project overlay and the user/global baseline
+     * separately — the merged get() collapses provenance and can't express
+     * tri-state inheritance. user → ~/.code-shell/settings.json, project →
+     * ${cwd}/.code-shell/settings.json. Only keys actually present in the file
+     * are returned (defaults are not synthesized), so an absent file → {}.
+     */
+    getForScope(scope: "user" | "project", cwd?: string): Partial<ValidatedSettings>;
+    private projectSettingsPath;
+    private readJsonObject;
+    private atomicWriteJson;
     private loadJsonFile;
     private deepMerge;
 }

package/dist/settings/manager.js

@@ -15,34 +15,44 @@ import { migrateModels } from "../migrate-models.js";
  * cached from the user database at process startup and ignores later
  * `process.env.HOME` mutations.
  */
-function userHome() {
+export function userHome() {
     return process.env.HOME ?? homedir();
 }
 export class SettingsManager {
     cwd;
+    scope;
     sources = [];
     merged = null;
-    constructor(cwd = process.cwd()) {
+    constructor(cwd = process.cwd(), scope = "project") {
         this.cwd = cwd;
+        this.scope = scope;
     }
     /**
      * Load settings from all sources.
      */
     load(flagOverrides) {
         this.sources = [];
-        // 1. Managed (lowest priority)
-        this.loadJsonFile(join(userHome(), ".code-shell", "settings.managed.json"), "managed", 0);
-        // 2. User — only ~/.code-shell/. We used to also read ~/.claude/settings.json
-        // for "zero-migration from Claude Code", but Claude Code's schema diverges
-        // (e.g. `model` is a string there, an object here). Merging caused boot
-        // crashes on machines that had Claude Code installed but never ran us.
-        // File-level compat (CLAUDE.md, .claude/skills/) is kept elsewhere — only
-        // the settings.json read is dropped.
-        this.loadJsonFile(join(userHome(), ".code-shell", "settings.json"), "user", 1);
-        // 3. Project
-        this.loadJsonFile(join(this.cwd, ".code-shell", "settings.json"), "project", 2);
-        // 4. Local
-        this.loadJsonFile(join(this.cwd, ".code-shell", "settings.local.json"), "local", 3);
+        // Scope gates which disk layers we read. 'full' reads the host user dir
+        // (~/.code-shell); 'project' and 'isolated' never do. See SettingsScope.
+        const readUser = this.scope === "full";
+        const readProject = this.scope !== "isolated";
+        if (readUser) {
+            // 1. Managed (lowest priority)
+            this.loadJsonFile(join(userHome(), ".code-shell", "settings.managed.json"), "managed", 0);
+            // 2. User — only ~/.code-shell/. We used to also read ~/.claude/settings.json
+            // for "zero-migration from Claude Code", but Claude Code's schema diverges
+            // (e.g. `model` is a string there, an object here). Merging caused boot
+            // crashes on machines that had Claude Code installed but never ran us.
+            // File-level compat (CLAUDE.md, .claude/skills/) is kept elsewhere — only
+            // the settings.json read is dropped.
+            this.loadJsonFile(join(userHome(), ".code-shell", "settings.json"), "user", 1);
+        }
+        if (readProject) {
+            // 3. Project
+            this.loadJsonFile(join(this.cwd, ".code-shell", "settings.json"), "project", 2);
+            // 4. Local
+            this.loadJsonFile(join(this.cwd, ".code-shell", "settings.local.json"), "local", 3);
+        }
         // 5. CLI flags (highest priority)
         if (flagOverrides && Object.keys(flagOverrides).length > 0) {
             this.sources.push({ name: "flag", priority: 4, data: flagOverrides });
@@ -54,9 +64,10 @@ export class SettingsManager {
         // Auto-migrate legacy models[] in the user settings file. Runs directly
         // on the user-scope file (not the merged result), because the merge
         // collapses provenance and the migration needs to write back to a
-        // single physical file.
+        // single physical file. Gated on readUser: under non-full scope we must
+        // not read — let alone rewrite — the host's ~/.code-shell/settings.json.
         const userPath = join(userHome(), ".code-shell", "settings.json");
-        if (existsSync(userPath)) {
+        if (readUser && existsSync(userPath)) {
             try {
                 const userRaw = JSON.parse(readFileSync(userPath, "utf-8"));
                 const result = migrateModels({
@@ -144,6 +155,99 @@ export class SettingsManager {
         renameSync(tmp, path);
         this.invalidate();
     }
+    /**
+     * Persist a single setting (dotted key path) to the PROJECT-level config
+     * file at ${cwd}/.code-shell/settings.json. This is where capabilityOverrides
+     * live — project overlays never touch the global user file. Atomic write +
+     * cache invalidation mirror saveUserSetting.
+     */
+    saveProjectSetting(key, value, cwd) {
+        const path = this.projectSettingsPath(cwd);
+        const current = this.readJsonObject(path);
+        const parts = key.split(".");
+        let target = current;
+        for (let i = 0; i < parts.length - 1; i++) {
+            const seg = parts[i];
+            const next = target[seg];
+            if (!next || typeof next !== "object" || Array.isArray(next)) {
+                target[seg] = {};
+            }
+            target = target[seg];
+        }
+        target[parts[parts.length - 1]] = value;
+        this.atomicWriteJson(path, current);
+        this.invalidate();
+    }
+    /**
+     * Delete a single dotted key from the PROJECT-level config file. Used to
+     * express "inherit" — we don't persist the literal "inherit"; we remove the
+     * override key. No-ops if the file or any intermediate segment is absent.
+     */
+    deleteProjectSetting(key, cwd) {
+        const path = this.projectSettingsPath(cwd);
+        if (!existsSync(path))
+            return;
+        const current = this.readJsonObject(path);
+        const parts = key.split(".");
+        let target = current;
+        for (let i = 0; i < parts.length - 1; i++) {
+            const next = target?.[parts[i]];
+            if (!next || typeof next !== "object" || Array.isArray(next))
+                return;
+            target = next;
+        }
+        if (target)
+            delete target[parts[parts.length - 1]];
+        this.atomicWriteJson(path, current);
+        this.invalidate();
+    }
+    /**
+     * Read ONE scope's raw settings file, validated but UNMERGED. Capability
+     * overlay math needs the project overlay and the user/global baseline
+     * separately — the merged get() collapses provenance and can't express
+     * tri-state inheritance. user → ~/.code-shell/settings.json, project →
+     * ${cwd}/.code-shell/settings.json. Only keys actually present in the file
+     * are returned (defaults are not synthesized), so an absent file → {}.
+     */
+    getForScope(scope, cwd) {
+        const path = scope === "user"
+            ? join(userHome(), ".code-shell", "settings.json")
+            : this.projectSettingsPath(cwd ?? this.cwd);
+        const raw = this.readJsonObject(path);
+        // validateSettings applies defaults; for a scope view we want only the
+        // file's own keys, so validate then project back the present keys.
+        const validated = validateSettings(raw);
+        const out = {};
+        for (const k of Object.keys(raw))
+            out[k] = validated[k];
+        return out;
+    }
+    projectSettingsPath(cwd) {
+        if (!cwd || cwd.trim().length === 0) {
+            throw new Error("project setting write requires a non-empty cwd");
+        }
+        return join(cwd, ".code-shell", "settings.json");
+    }
+    readJsonObject(path) {
+        if (!existsSync(path))
+            return {};
+        try {
+            const parsed = JSON.parse(readFileSync(path, "utf-8"));
+            if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                return parsed;
+            }
+        }
+        catch {
+            // Corrupt file — overwrite rather than crash.
+        }
+        return {};
+    }
+    atomicWriteJson(path, data) {
+        mkdirSync(dirname(path), { recursive: true });
+        const tmp = `${path}.${process.pid}.${Date.now()}.tmp`;
+        writeFileSync(tmp, JSON.stringify(data, null, 2), "utf-8");
+        renameSync(tmp, path);
+    }
     loadJsonFile(path, name, priority) {
         if (!existsSync(path))
             return;

package/dist/settings/manager.test.d.ts

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

package/dist/settings/manager.test.js

@@ -0,0 +1,73 @@
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { SettingsManager } from "./manager.js";
+/**
+ * Scope isolation tests. We point HOME at a temp dir (userHome() reads
+ * process.env.HOME first) and use a separate temp cwd, then seed each of the
+ * four disk layers with a uniquely-named mcpServers entry. mcpServers is a
+ * record merged key-by-key, so every layer that was actually read leaves its
+ * own key in the merged result — letting us detect which layers were read
+ * (unlike arrays, which deep-merge replaces wholesale).
+ */
+describe("SettingsManager scope", () => {
+    let home;
+    let cwd;
+    let prevHome;
+    function serverFor(tag) {
+        return { [tag]: { name: tag, command: "echo", transport: "stdio" } };
+    }
+    function writeSettings(dir, file, tag) {
+        mkdirSync(join(dir, ".code-shell"), { recursive: true });
+        writeFileSync(join(dir, ".code-shell", file), JSON.stringify({ mcpServers: serverFor(tag) }), "utf-8");
+    }
+    function layersIn(sm) {
+        return Object.keys(sm.get().mcpServers ?? {}).sort();
+    }
+    beforeEach(() => {
+        prevHome = process.env.HOME;
+        home = mkdtempSync(join(tmpdir(), "cs-home-"));
+        cwd = mkdtempSync(join(tmpdir(), "cs-cwd-"));
+        process.env.HOME = home;
+        writeSettings(home, "settings.managed.json", "MANAGED");
+        writeSettings(home, "settings.json", "USER");
+        writeSettings(cwd, "settings.json", "PROJECT");
+        writeSettings(cwd, "settings.local.json", "LOCAL");
+    });
+    afterEach(() => {
+        process.env.HOME = prevHome;
+        rmSync(home, { recursive: true, force: true });
+        rmSync(cwd, { recursive: true, force: true });
+    });
+    test("full reads all four disk layers", () => {
+        expect(layersIn(new SettingsManager(cwd, "full"))).toEqual([
+            "LOCAL",
+            "MANAGED",
+            "PROJECT",
+            "USER",
+        ]);
+    });
+    test("project (default) reads project+local, never user/managed", () => {
+        expect(layersIn(new SettingsManager(cwd, "project"))).toEqual(["LOCAL", "PROJECT"]);
+    });
+    test("default scope is project", () => {
+        expect(layersIn(new SettingsManager(cwd))).toEqual(["LOCAL", "PROJECT"]);
+    });
+    test("isolated reads no disk layers", () => {
+        expect(layersIn(new SettingsManager(cwd, "isolated"))).toEqual([]);
+    });
+    test("flag overrides apply even under isolated", () => {
+        const sm = new SettingsManager(cwd, "isolated");
+        sm.load({ mcpServers: serverFor("FLAG") });
+        expect(layersIn(sm)).toEqual(["FLAG"]);
+    });
+    test("non-full scope never triggers user-file model migration write-back", () => {
+        // Legacy models[] in the user file would normally be migrated (and the
+        // file rewritten with a .bak). Under project/isolated we must not touch
+        // the user file at all.
+        writeFileSync(join(home, ".code-shell", "settings.json"), JSON.stringify({ models: [{ id: "legacy", provider: "x" }] }), "utf-8");
+        new SettingsManager(cwd, "project").get();
+        expect(existsSync(join(home, ".code-shell", "settings.json.bak"))).toBe(false);
+    });
+});

package/dist/settings/personalization.d.ts

@@ -0,0 +1,19 @@
+/** The agent.* subset of settings the Engine needs for personalization +
+ * instruction-file compat. Hosts spread this into EngineConfig so the three
+ * fields stay wired identically across desktop / TUI / TCP (avoids per-host drift). */
+export interface PersonalizationConfig {
+    responseLanguage?: string;
+    userProfile?: string;
+    instructions?: {
+        compatClaude?: boolean;
+        compatCodex?: boolean;
+    };
+}
+export declare function personalizationFrom(agent: {
+    responseLanguage?: string;
+    userProfile?: string;
+    instructions?: {
+        compatClaude?: boolean;
+        compatCodex?: boolean;
+    };
+}): PersonalizationConfig;

package/dist/settings/personalization.js

@@ -0,0 +1,7 @@
+export function personalizationFrom(agent) {
+    return {
+        responseLanguage: agent.responseLanguage,
+        userProfile: agent.userProfile,
+        instructions: agent.instructions,
+    };
+}