cli-jaw 2.2.16 → 2.2.17

package/dist/src/core/config.js

@@ -3,10 +3,12 @@ import os from 'os';
 import fs from 'fs';
 import path from 'path';
 import { join } from 'path';
-import { DEFAULT_CLI, buildDefaultPerCli } from '../cli/registry.js';
+import { DEFAULT_CLI, CLI_KEYS, buildDefaultPerCli } from '../cli/registry.js';
 import { pickFirstReadyCli } from '../cli/readiness.js';
 import { migrateLegacyClaudeValue } from '../cli/claude-models.js';
 import { resolveHomePath } from './path-expand.js';
+import { SETUP_STATE_FILE } from './install-integrity.js';
+import { sanitizeSettingsInput, } from './settings-merge.js';
 export { detectAllCli, detectCli, getClaudeExecHelperCandidates, getClaudeIHelperCandidates } from './cli-detection.js';
 // ─── Version (single source of truth: package.json) ──
 import { dirname } from 'path';
@@ -164,8 +166,23 @@ export function runMigration(projectDir) {
     fs.writeFileSync(MIGRATION_MARKER, JSON.stringify({ migratedAt: new Date().toISOString() }));
 }
 // ─── Settings ────────────────────────────────────────
+export const SETTINGS_SCHEMA_VERSION = 3;
+export const RUNTIME_DEFAULT_MIGRATION_ID = 'codex-app-default-v2';
+export const MULTI_SESSION_DEFAULT_MIGRATION_ID = 'multi-session-default-v3';
+// What multiSession meant before this flip. A document written by a schema that predates
+// the new defaults must resolve absent keys to these, not to the new ones — otherwise the
+// upgrade turns sessions on for someone who never asked (110 §4b-1).
+export const LEGACY_MULTI_SESSION_BASELINE = {
+    enabled: false,
+    maxConcurrent: 1,
+    midRunPolicy: 'steer',
+    channels: { telegram: false, discord: false, slack: true },
+};
 function createDefaultSettings() {
     return {
+        settingsSchemaVersion: SETTINGS_SCHEMA_VERSION,
+        runtimeDefaultMigration: null,
+        multiSessionDefaultMigration: null,
         port: '', // persisted by server on startup; CLI commands use as fallback
         cli: DEFAULT_CLI,
         fallbackOrder: [],
@@ -226,12 +243,35 @@ function createDefaultSettings() {
             // Slack bots typically live in shared team channels, where
             // answering every message is antisocial. DMs bypass this gate.
             mentionOnly: true,
+            // But a thread the bot participates in keeps flowing without
+            // re-mention (true = strict, mention required even in threads).
+            threadRequireMention: false,
             replyInThread: true,
+            inboundDownloadConcurrency: 6,
         },
         messaging: {
             latestSeen: { telegram: null, discord: null, slack: null },
             lastActive: { telegram: null, discord: null, slack: null },
         },
+        multiSession: {
+            // Sessions are on by default as of schema v3. An existing install does not
+            // get this silently: the merge substitutes the legacy baseline for its
+            // cohort and asks (110 §4b).
+            enabled: true,
+            // Two, not more: the observable unit is that a second tab does not wait for
+            // the first. Beyond that is the user's CPU and token budget to spend.
+            maxConcurrent: 2,
+            midRunPolicy: 'steer',
+            channels: { telegram: false, discord: false, slack: true },
+        },
+        // Opt-in Markdown vault (devlog 040). Default OFF and nothing is created on
+        // disk until it is explicitly enabled, so a user who never turns it on sees no
+        // new directory and no change in behaviour.
+        wiki: {
+            enabled: false,
+            root: '~/jaw-wiki',
+            promptDigest: false,
+        },
         memory: {
             enabled: true,
             flushEvery: 10,
@@ -242,10 +282,16 @@ function createDefaultSettings() {
             autoReflectAfterFlush: false,
             flushMessageWindow: 0,
         },
+        search: { engine: 'like' },
         trace: {
             retentionDays: 7,
             maxRows: 50000,
         },
+        runtime: {
+            codexApp: {
+                multiplex: false,
+            },
+        },
         code: {
             maxConcurrentSessions: 4,
             idleReapMs: 30_000,
@@ -298,6 +344,74 @@ function createDefaultSettings() {
     };
 }
 export const DEFAULT_SETTINGS = createDefaultSettings();
+/**
+ * The keys a document must carry to legitimately claim the current schema.
+ *
+ * `cli-jaw init` writes a settings file, so a new install is not the ENOENT case the
+ * cohort rules were written around. Left unstamped, its document reads as v1 and the
+ * person who just installed is offered a migration away from a state they never had.
+ * Stamping the version alone is not enough either — the loader holds a document claiming
+ * this schema to what this schema writes — so the writer takes the whole set from here
+ * rather than assembling it from memory (110 §4b-3).
+ */
+export function freshInstallSchemaFields() {
+    // Same question as the loader asks, answered the same way: `init` running against a
+    // home that already has a database is re-initialising, not installing.
+    const defaults = settingsForHomeWithoutSettingsFile();
+    return {
+        settingsSchemaVersion: SETTINGS_SCHEMA_VERSION,
+        multiSession: defaults.multiSession,
+        // Null only for a home with no history — there is nothing to migrate from and
+        // nothing to ask about. An established home carries the pending marker instead.
+        multiSessionDefaultMigration: defaults.multiSessionDefaultMigration,
+    };
+}
+// Things a home only has once someone has set it up or used it. A settings file can be
+// deleted, lost to a failed write, or restored from a backup that omitted it — none of
+// which makes the install new. These do not come back on their own.
+//
+// The list errs toward "established" on purpose. Calling a new home established costs a
+// question the user did not need to answer; calling an established home new turns a
+// feature on for someone who was never asked. Those are not the same mistake. That is
+// also why the postinstall-created directories stay in the list even though they can
+// precede a first boot.
+const ESTABLISHED_HOME_ARTIFACTS = [
+    DB_PATH,
+    MIGRATION_MARKER,
+    PROMPTS_DIR,
+    UPLOADS_DIR,
+    // `jaw init` leaves all three, and an init-only home whose settings file was then
+    // lost is exactly the case that must not read as new.
+    join(JAW_HOME, SETUP_STATE_FILE),
+    HEARTBEAT_JOBS_PATH,
+    SKILLS_DIR,
+    WIDGETS_DIR,
+];
+/**
+ * An absent settings file is not proof of a new install, and the difference decides
+ * whether sessions start on. Getting it wrong turns a feature on for someone who was
+ * never asked, which is the one outcome the whole migration exists to prevent — so the
+ * question is answered from the home directory rather than from one file in it.
+ */
+export function isEstablishedHome() {
+    return ESTABLISHED_HOME_ARTIFACTS.some(path => fs.existsSync(path));
+}
+/**
+ * What a home with no readable settings should start with. A home that has been used
+ * before gets the previous meaning plus a pending marker, so it is asked like any other
+ * upgrade; only a home with no history at all gets the new defaults.
+ */
+export function settingsForHomeWithoutSettingsFile() {
+    const next = createDefaultSettings();
+    if (!isEstablishedHome())
+        return next;
+    next.multiSession = { ...next.multiSession, ...LEGACY_MULTI_SESSION_BASELINE };
+    next.multiSessionDefaultMigration = {
+        id: MULTI_SESSION_DEFAULT_MIGRATION_ID,
+        state: 'pending',
+    };
+    return next;
+}
 export function normalizeModelForCli(cli, model) {
     if (typeof model !== 'string')
         return model;
@@ -336,7 +450,7 @@ function normalizeActiveOverrides(activeOverrides = {}, perCli = {}) {
     return next;
 }
 /** @internal — exported for unit testing */
-export function migrateSettings(s) {
+export function migrateSettings(s, sourceVersion = readSettingsSchemaVersion(s)) {
     if (s["planning"]) {
         if (s["planning"].cli && s["planning"].cli !== s["cli"])
             s["cli"] = s["planning"].cli;
@@ -352,6 +466,51 @@ export function migrateSettings(s) {
         }
         delete s["planning"];
     }
+    if (sourceVersion === 1) {
+        const fromCli = CLI_KEYS.includes(s["cli"]) ? s["cli"] : 'claude';
+        s["cli"] = fromCli;
+        s["settingsSchemaVersion"] = SETTINGS_SCHEMA_VERSION;
+        s["runtimeDefaultMigration"] = {
+            id: RUNTIME_DEFAULT_MIGRATION_ID,
+            state: fromCli === 'codex-app' ? 'already-codex-app' : 'pending',
+            fromCli,
+            toCli: 'codex-app',
+        };
+    }
+    else {
+        validateRuntimeDefaultMigration(s["runtimeDefaultMigration"]);
+    }
+    // The session-default flip is its own migration with its own marker. It is NOT
+    // folded into the runtime one: the two flips can be rolled back at different times
+    // for different reasons, and a shared marker would make that impossible to express.
+    // A v1 document crosses both boundaries and so gets both markers in this one pass.
+    if (sourceVersion < SETTINGS_SCHEMA_VERSION) {
+        s["settingsSchemaVersion"] = SETTINGS_SCHEMA_VERSION;
+        s["multiSessionDefaultMigration"] = {
+            id: MULTI_SESSION_DEFAULT_MIGRATION_ID,
+            // Someone who already turned sessions on made this decision before we asked.
+            // Offering it again would be noise, and accepting for them would change a
+            // concurrency they chose.
+            state: s["multiSession"]?.enabled === true ? 'already-enabled' : 'pending',
+        };
+    }
+    else {
+        validateMultiSessionDefaultMigration(s["multiSessionDefaultMigration"]);
+    }
+    // A pending marker means the user has not answered yet, so sessions being on
+    // contradicts it. The dedicated accept route moves both together, but it is not the
+    // only way in: the settings watcher merges an external file write, and a generic
+    // settings patch can set `multiSession.enabled` directly. Both strip the marker as
+    // server-owned and then leave this pair inconsistent — enabled, and still pending.
+    //
+    // Resolved by treating an enable while pending AS the answer rather than by refusing
+    // it. Someone who reaches in and turns it on has decided; what must not survive is a
+    // marker that still claims to be waiting, because the next boot would ask again and
+    // the record would no longer mean anything.
+    const sessionMigration = s["multiSessionDefaultMigration"];
+    if (sessionMigration?.state === 'pending' && s["multiSession"]?.enabled === true) {
+        s["multiSessionDefaultMigration"] = { ...sessionMigration, state: 'accepted' };
+    }
     // Claude model alias migration
     s["perCli"] = normalizePerCliModels(s["perCli"] || {});
     s["activeOverrides"] = normalizeActiveOverrides(s["activeOverrides"] || {}, s["perCli"] || {});
@@ -394,8 +553,14 @@ export function migrateSettings(s) {
             allowBots: false,
             mentionOnly: true,
             replyInThread: true,
+            inboundDownloadConcurrency: 6,
         };
     }
+    if (!Number.isInteger(s["slack"].inboundDownloadConcurrency)
+        || s["slack"].inboundDownloadConcurrency < 1
+        || s["slack"].inboundDownloadConcurrency > 32) {
+        s["slack"].inboundDownloadConcurrency = 6;
+    }
     if (!s["messaging"]) {
         s["messaging"] = {
             latestSeen: { telegram: null, discord: null, slack: null },
@@ -412,6 +577,44 @@ export function migrateSettings(s) {
             s["messaging"].lastActive.slack = null;
         }
     }
+    if (!s["multiSession"]) {
+        s["multiSession"] = createDefaultSettings().multiSession;
+    }
+    else {
+        // Deliberately the OLD defaults, not createDefaultSettings(). This function takes
+        // an already-merged object and cannot tell which cohort it came from, so handing
+        // out the new defaults here would enable sessions for a legacy document that
+        // reached this line by some path other than the boot merge. The boot merge fills
+        // both keys from the cohort baseline, which makes these two lines unreachable on
+        // the normal path — they are the net under it, and a net set to the new defaults
+        // is not a net (110 §4b-2).
+        if (s["multiSession"].enabled === undefined) {
+            s["multiSession"].enabled = LEGACY_MULTI_SESSION_BASELINE.enabled;
+        }
+        if (s["multiSession"].maxConcurrent === undefined) {
+            s["multiSession"].maxConcurrent = LEGACY_MULTI_SESSION_BASELINE.maxConcurrent;
+        }
+        if (s["multiSession"].midRunPolicy === undefined)
+            s["multiSession"].midRunPolicy = 'steer';
+        if (s["multiSession"].channels === undefined) {
+            s["multiSession"].channels = { telegram: false, discord: false, slack: true };
+        }
+        else {
+            if (s["multiSession"].channels.telegram === undefined)
+                s["multiSession"].channels.telegram = false;
+            if (s["multiSession"].channels.discord === undefined)
+                s["multiSession"].channels.discord = false;
+            if (s["multiSession"].channels.slack === undefined)
+                s["multiSession"].channels.slack = true;
+        }
+    }
+    const maxConcurrent = Number(s["multiSession"].maxConcurrent);
+    s["multiSession"].maxConcurrent = Number.isInteger(maxConcurrent) && maxConcurrent > 0
+        ? maxConcurrent
+        : 1;
+    if (!['steer', 'followup', 'collect', 'interrupt'].includes(s["multiSession"].midRunPolicy)) {
+        s["multiSession"].midRunPolicy = 'steer';
+    }
     if (!s["jawCeo"]) {
         s["jawCeo"] = { openaiApiKey: '' };
     }
@@ -471,10 +674,145 @@ function applyEnvOverrides(s) {
 }
 /** Mutable settings object — shared across all modules via ESM live binding */
 export let settings = createDefaultSettings();
+let settingsPersistenceShape = 'absent';
+function readSettingsSchemaVersion(raw) {
+    if (!("settingsSchemaVersion" in raw))
+        return 1;
+    const version = raw["settingsSchemaVersion"];
+    if (!Number.isInteger(version) || version < 1 || version > SETTINGS_SCHEMA_VERSION) {
+        throw new Error(`unsupported_settings_schema_version:${String(version)}`);
+    }
+    return version;
+}
+function validateRuntimeDefaultMigration(value) {
+    if (value === null || value === undefined)
+        return;
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error('invalid_runtime_default_migration');
+    }
+    const migration = value;
+    const keys = Object.keys(migration).sort();
+    const expectedKeys = ['fromCli', 'id', 'state', 'toCli'];
+    const validState = ['pending', 'accepted', 'kept', 'already-codex-app'].includes(String(migration["state"]));
+    if (JSON.stringify(keys) !== JSON.stringify(expectedKeys)
+        || migration["id"] !== RUNTIME_DEFAULT_MIGRATION_ID
+        || !validState
+        || typeof migration["fromCli"] !== 'string'
+        || migration["toCli"] !== 'codex-app') {
+        throw new Error('invalid_runtime_default_migration');
+    }
+}
+function validateMultiSessionDefaultMigration(value) {
+    if (value === null || value === undefined)
+        return;
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error('invalid_multi_session_default_migration');
+    }
+    const migration = value;
+    const keys = Object.keys(migration).sort();
+    const validState = ['pending', 'accepted', 'kept', 'already-enabled'].includes(String(migration["state"]));
+    if (JSON.stringify(keys) !== JSON.stringify(['id', 'state'])
+        || migration["id"] !== MULTI_SESSION_DEFAULT_MIGRATION_ID
+        || !validState) {
+        throw new Error('invalid_multi_session_default_migration');
+    }
+}
+function isPlainRecord(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+// ─── Clobber-protection latch (260806) ───────────────
+// When settings.json existed but could not be read at boot (corrupt JSON, an
+// unsupported/future schema version, a permission error), the in-memory state is
+// defaults — and any later save (messaging.latestSeen, a UI write) would flush those
+// defaults over the user's real file, tokens included. That actually happened: a v2
+// packaged app read a v3 file and wiped a Slack config. While latched, saves commit
+// to memory only and the file on disk is left exactly as it was.
+let settingsPersistenceBlockedReason = null;
+let settingsPersistenceBlockedWarned = false;
+export function isSettingsPersistenceBlocked() {
+    return settingsPersistenceBlockedReason !== null;
+}
+/**
+ * A v3 document was written by this schema, and this schema always writes both the
+ * multiSession block and its migration marker. If either is missing or malformed, the
+ * document is not what it claims to be — and the consequence of guessing is specific:
+ * an absent block would inherit the new defaults and start running sessions while the
+ * marker still said the user had not consented (110 §4b-3). Older documents are held to
+ * no such rule: their schema did not know these keys, so absent is normal there and the
+ * legacy baseline covers it.
+ */
+function assertCurrentSchemaSessionShape(raw) {
+    const block = raw["multiSession"];
+    if (!isPlainRecord(block))
+        throw new Error('invalid_multi_session_block');
+    if (typeof block["enabled"] !== 'boolean')
+        throw new Error('invalid_multi_session_enabled');
+    const maxConcurrent = block["maxConcurrent"];
+    if (!Number.isInteger(maxConcurrent) || maxConcurrent < 1) {
+        throw new Error('invalid_multi_session_max_concurrent');
+    }
+    if ('channels' in block && !isPlainRecord(block["channels"])) {
+        throw new Error('invalid_multi_session_channels');
+    }
+    if (!('multiSessionDefaultMigration' in raw)) {
+        throw new Error('missing_multi_session_default_migration');
+    }
+    validateMultiSessionDefaultMigration(raw["multiSessionDefaultMigration"]);
+}
 export function loadSettings() {
+    // A fresh load is a fresh verdict: a successful parse (or a genuinely absent
+    // file) below re-enables persistence; only the unreadable-existing-file catch
+    // re-arms the latch.
+    settingsPersistenceBlockedReason = null;
+    settingsPersistenceBlockedWarned = false;
     try {
-        const raw = JSON.parse(fs.readFileSync(SETTINGS_PATH, 'utf8'));
+        let raw = JSON.parse(fs.readFileSync(SETTINGS_PATH, 'utf8'));
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+            throw new Error('invalid_settings_document');
+        }
+        const sanitized = sanitizeSettingsInput(raw, 'boot');
+        raw = sanitized.value;
+        const nextShape = sanitized.persistenceShape;
+        if (sanitized.rejectedPaths.length > 0) {
+            console.warn(`[jaw:settings] ignored server-owned settings fields: ${sanitized.rejectedPaths.join(', ')}`);
+        }
+        if (sanitized.invalidPaths.length > 0) {
+            console.warn(`[jaw:settings] ignored invalid settings fields: ${sanitized.invalidPaths.join(', ')}`);
+        }
+        const sourceVersion = readSettingsSchemaVersion(raw);
+        // Dropping a malformed field and carrying on is right for a patch arriving over
+        // the API — the rest of the patch is still what the caller meant. It is wrong for
+        // a document claiming the current schema at boot: this schema wrote that block,
+        // so a malformed one means the file is not what it says, and silently replacing
+        // it with defaults is how a pending consent turns into a running feature.
+        if (sourceVersion >= 3 && sanitized.invalidPaths.some(path => path.startsWith('multiSession'))) {
+            throw new Error(`invalid_multi_session_block:${sanitized.invalidPaths.join(',')}`);
+        }
+        // A v1 document predates the codex-app default, so an absent or unknown
+        // cli is normalised to the historical fallback rather than inheriting
+        // the new default. A v2 document was written by this schema and must
+        // already name a known runtime; if it does not, the file is not
+        // trustworthy enough to silently supply one, so it closes the same way
+        // a corrupt or future-versioned document does.
+        if (sourceVersion >= 2 && !CLI_KEYS.includes(raw["cli"])) {
+            throw new Error(`invalid_settings_cli:${String(raw["cli"])}`);
+        }
+        // A document claiming the current schema must actually carry what this schema
+        // writes. Checked before the merge, because after it the absence is gone.
+        if (sourceVersion >= 3)
+            assertCurrentSchemaSessionShape(raw);
+        const legacyCli = sourceVersion === 1 && !CLI_KEYS.includes(raw["cli"])
+            ? 'claude'
+            : raw["cli"];
+        const hadPlanning = !!raw.planning;
         const defaults = createDefaultSettings();
+        // Everything below the current schema predates the session defaults, so absent
+        // keys resolve to what they used to mean rather than to the new defaults. The
+        // merge runs before migrateSettings, so this is the only place that still knows
+        // whether a key was in the document or is about to be invented (110 §4b-1).
+        const multiSessionBaseline = sourceVersion < SETTINGS_SCHEMA_VERSION
+            ? LEGACY_MULTI_SESSION_BASELINE
+            : defaults.multiSession;
         // Deep merge perCli so new CLI defaults (e.g. copilot) are preserved
         const mergedPerCli = buildDefaultPerCli();
         if (raw.perCli) {
@@ -485,12 +823,18 @@ export function loadSettings() {
         const merged = migrateSettings({
             ...defaults,
             ...raw,
+            ...(sourceVersion === 1 ? { cli: legacyCli } : {}),
             perCli: mergedPerCli,
             tui: { ...defaults.tui, ...(raw.tui || {}) },
             telegram: { ...defaults.telegram, ...(raw.telegram || {}) },
             discord: { ...defaults.discord, ...(raw.discord || {}) },
             slack: { ...defaults.slack, ...(raw.slack || {}) },
             memory: { ...defaults.memory, ...(raw.memory || {}) },
+            search: {
+                ...defaults.search,
+                ...(raw.search || {}),
+                engine: raw.search?.engine === 'fts5' ? 'fts5' : 'like',
+            },
             trace: { ...defaults.trace, ...(raw.trace || {}) },
             avatar: {
                 agent: { ...defaults.avatar.agent, ...(raw.avatar?.agent || {}) },
@@ -503,17 +847,39 @@ export function loadSettings() {
             jawCeo: { ...defaults.jawCeo, ...(raw.jawCeo || {}) },
             pi: { ...defaults.pi, ...(raw.pi || {}) },
             network: { ...defaults.network, ...(raw.network || {}) },
+            runtime: {
+                ...defaults.runtime,
+                ...(raw.runtime || {}),
+                codexApp: {
+                    ...defaults.runtime.codexApp,
+                    ...(raw.runtime?.codexApp || {}),
+                },
+            },
             code: { ...defaults.code, ...(raw.code || {}) },
-        });
+            multiSession: {
+                ...multiSessionBaseline,
+                ...(raw.multiSession || {}),
+                channels: { ...multiSessionBaseline.channels, ...(raw.multiSession?.channels || {}) },
+            },
+            wiki: { ...defaults.wiki, ...(raw.wiki || {}) },
+        }, sourceVersion);
         // #64 safety: auto-correct stale workingDir (e.g. copied instance)
         // but allow valid paths to persist (dynamic project targeting)
+        // Any document below the current schema was rewritten by the migration above, so
+        // it has to reach disk. Leaving it unsaved would keep memory at v3 while the file
+        // stayed older, and the next boot would run the migration again — including
+        // recreating a marker the user had already resolved.
+        let needsSave = sourceVersion < SETTINGS_SCHEMA_VERSION || hadPlanning;
         if (typeof merged["workingDir"] === 'string' && merged["workingDir"] !== JAW_HOME && !fs.existsSync(merged["workingDir"])) {
             console.warn(`[jaw:workingDir] stale path ${merged["workingDir"]}, resetting to JAW_HOME`);
             merged["workingDir"] = JAW_HOME;
-            saveSettings(merged);
+            needsSave = true;
         }
-        if (raw.planning)
-            saveSettings(merged);
+        const candidate = { value: merged, shape: nextShape };
+        if (needsSave)
+            persistAndCommit(candidate);
+        else
+            commitCandidate(candidate);
         // normalize projectDirs on load (reject corrupted/injected values)
         merged["projectDirs"] = normalizeProjectDirs(merged["projectDirs"]);
         // env overrides
@@ -531,22 +897,43 @@ export function loadSettings() {
             }
             catch { /* best-effort */ }
         }
-        settings = merged;
         return merged;
     }
     catch (error) {
-        const next = createDefaultSettings();
-        next.cli = pickFirstReadyCli();
-        applyEnvOverrides(next);
-        settings = next;
         const err = error;
         if (err?.code === 'ENOENT') {
-            saveSettings(next);
+            // ENOENT means no settings file, not necessarily no install. A home that has
+            // a database or an uploads directory has been used, so it is treated as an
+            // upgrade and asked rather than switched on.
+            const next = settingsForHomeWithoutSettingsFile();
+            next.cli = pickFirstReadyCli();
+            applyEnvOverrides(next);
+            persistAndCommit({ value: next, shape: 'absent' });
             return next;
         }
+        const next = createDefaultSettings();
+        next.cli = 'claude';
+        // This branch stands in for a state we could not read — corrupt JSON, an
+        // unsupported version, a permission error. The new-install defaults are the wrong
+        // thing to borrow here: they would turn sessions on for someone whose real
+        // settings might have had them off, and who was never asked. Pinned to what the
+        // previous schema meant (110 §4c). The ENOENT branch above is genuinely new and
+        // keeps the new defaults.
+        next.multiSession = { ...next.multiSession, ...LEGACY_MULTI_SESSION_BASELINE };
+        applyEnvOverrides(next);
+        commitCandidate({ value: next, shape: 'absent' });
         console.warn(`[jaw:settings] failed to load ${SETTINGS_PATH}: ${err?.message || String(error)}`);
         if (fs.existsSync(SETTINGS_PATH)) {
-            const backupPath = `${SETTINGS_PATH}.corrupt-${Date.now()}.bak`;
+            // The file is real and we could not read it, so what is in memory now is
+            // NOT the user's settings. Latch persistence so no later save clobbers
+            // the file; the backup below is a copy, not a license to overwrite.
+            settingsPersistenceBlockedReason = err?.message || String(error);
+            let backupTimestamp = Date.now();
+            let backupPath = `${SETTINGS_PATH}.corrupt-${backupTimestamp}.bak`;
+            while (fs.existsSync(backupPath)) {
+                backupTimestamp += 1;
+                backupPath = `${SETTINGS_PATH}.corrupt-${backupTimestamp}.bak`;
+            }
             try {
                 fs.copyFileSync(SETTINGS_PATH, backupPath);
                 console.warn(`[jaw:settings] backed up unreadable settings to ${backupPath}`);
@@ -561,10 +948,19 @@ export function loadSettings() {
 // Self-write fingerprint for the settings watcher: external writers (a separate
 // `cli-jaw project set` process) produce content that won't match this string.
 let lastSavedSettingsRaw = null;
-export function saveSettings(s) {
-    settings = s;
-    const raw = JSON.stringify(s, null, 2);
-    lastSavedSettingsRaw = raw;
+export function serializeSettingsForSave(candidate) {
+    const value = structuredClone(candidate.value);
+    const runtime = value["runtime"];
+    if (candidate.shape === 'absent' && runtime?.codexApp?.multiplex === false) {
+        delete runtime.codexApp.multiplex;
+        if (Object.keys(runtime.codexApp).length === 0)
+            delete runtime.codexApp;
+        if (Object.keys(runtime).length === 0)
+            delete value["runtime"];
+    }
+    return JSON.stringify(value, null, 2);
+}
+function writeSettingsRaw(raw) {
     // settings.json carries live channel tokens (xoxb-/xapp-/bot tokens), so
     // it must never be group/other-readable. writeFileSync's mode applies
     // only at creation — chmod covers the existing-file path.
@@ -576,12 +972,45 @@ export function saveSettings(s) {
         catch { /* best-effort */ }
     }
 }
+export function commitCandidate(candidate) {
+    settings = candidate.value;
+    settingsPersistenceShape = candidate.shape;
+}
+export function persistAndCommit(candidate, write = writeSettingsRaw) {
+    if (settingsPersistenceBlockedReason !== null) {
+        // Memory-only: the file on disk holds the user's real settings in a shape
+        // this binary could not read, and writing would destroy them.
+        if (!settingsPersistenceBlockedWarned) {
+            settingsPersistenceBlockedWarned = true;
+            console.warn(`[jaw:settings] persistence disabled: settings.json was unreadable at boot (${settingsPersistenceBlockedReason}); refusing to overwrite it`);
+        }
+        commitCandidate(candidate);
+        return;
+    }
+    const raw = serializeSettingsForSave(candidate);
+    write(raw);
+    lastSavedSettingsRaw = raw;
+    commitCandidate(candidate);
+}
+/** Re-save the current settings pair for legacy callers that mutate settings in place. */
+export function saveSettings(s) {
+    persistAndCommit({ value: s, shape: settingsPersistenceShape });
+}
+export function snapshotSettingsState() {
+    return {
+        value: structuredClone(settings),
+        shape: settingsPersistenceShape,
+    };
+}
+export function getSettingsPersistenceShape() {
+    return settingsPersistenceShape;
+}
 export function getLastSavedSettingsRaw() {
     return lastSavedSettingsRaw;
 }
 /** Replace settings object (for API PUT /api/settings deep merge) */
-export function replaceSettings(s) {
-    settings = s;
+export function replaceSettings(s, shape) {
+    commitCandidate({ value: s, shape });
 }
 export function loadHeartbeatFile() {
     try {