sneakoscope 1.18.13 → 1.19.0

package/dist/cli/install-helpers.js

@@ -25,7 +25,7 @@ const DEFAULT_CODEX_APP_PLUGINS = [
 function packagedSksEntrypoint() {
     return path.join(packageRoot(), 'dist', 'bin', 'sks.js');
 }
-export async function postinstall({ bootstrap }) {
+export async function postinstall({ bootstrap, args = [] }) {
     const installRoot = path.resolve(process.env.INIT_CWD || process.cwd());
     const conflictScan = await scanHarnessConflicts(installRoot);
     if (conflictScan.hard_block) {
@@ -33,88 +33,104 @@ export async function postinstall({ bootstrap }) {
         return;
     }
     const codexLbConfigSnapshot = await capturePostinstallCodexLbConfigSnapshot();
-    console.log('\nSKS installed.');
-    const shim = await ensureSksCommandDuringInstall();
-    if (shim.status === 'present')
-        console.log(`SKS command: available (${shim.command ?? 'unknown'}).`);
-    else if (shim.status === 'repaired')
-        console.log(`SKS command: stale PATH shim repaired (${shim.command ?? 'unknown'}).`);
-    else if (shim.status === 'created')
-        console.log(`SKS command: shim created at ${shim.command ?? 'unknown'}.`);
-    else if (shim.status === 'created_not_on_path')
-        console.log(`SKS command: shim created at ${shim.command ?? 'unknown'}. Add ${path.dirname(shim.command ?? '')} to PATH, or run npx -y -p sneakoscope sks.`);
-    else if (shim.status === 'skipped')
-        console.log(`SKS command: skipped (${shim.reason}).`);
-    else
-        console.log(`SKS command: shim unavailable. Use npx -y -p sneakoscope sks. ${shim.error || ''}`.trim());
-    const context7Install = await ensureGlobalContext7DuringInstall();
-    if (context7Install.status === 'present')
-        console.log('Context7 MCP: already configured for Codex.');
-    else if (context7Install.status === 'installed')
-        console.log('Context7 MCP: configured for Codex.');
-    else if (context7Install.status === 'codex_missing')
-        console.log('Context7 MCP: Codex CLI missing. Install @openai/codex or set SKS_CODEX_BIN, then run `sks context7 setup --scope global` or `sks setup` in a project.');
-    else if (context7Install.status === 'skipped')
-        console.log(`Context7 MCP: skipped (${context7Install.reason}).`);
-    else if (context7Install.status === 'failed')
-        console.log(`Context7 MCP: auto setup failed. Run \`sks context7 setup --scope global\` or \`sks setup\`. ${context7Install.error || ''}`.trim());
-    const fastModeRepair = await ensureGlobalCodexFastModeDuringInstall();
-    if (fastModeRepair.status === 'updated')
-        console.log(`Codex App Fast mode: restored in ${fastModeRepair.config_path}.`);
-    else if (fastModeRepair.status === 'present')
-        console.log('Codex App Fast mode: config already compatible.');
-    else if (fastModeRepair.status === 'skipped')
-        console.log(`Codex App Fast mode: skipped (${fastModeRepair.reason}).`);
-    else if (fastModeRepair.status === 'failed')
-        console.log(`Codex App Fast mode: auto repair failed. Run \`sks setup\`. ${fastModeRepair.error || ''}`.trim());
-    const appProcessRepair = await reconcileCodexAppUpgradeProcesses();
-    if (appProcessRepair.status === 'repaired')
-        console.log(`Codex App reconnect repair: stopped ${appProcessRepair.killed.length} stale orphan app-server process(es). Restart Codex App to reconnect cleanly.`);
-    else if (appProcessRepair.status === 'partial')
-        console.log(`Codex App reconnect repair: stopped ${appProcessRepair.killed.length} stale orphan app-server process(es); ${(appProcessRepair.failed ?? []).length} could not be stopped. Restart Codex App if reconnecting continues.`);
-    else if (appProcessRepair.status === 'skipped' && appProcessRepair.reason !== 'platform')
-        console.log(`Codex App reconnect repair: skipped (${appProcessRepair.reason}).`);
-    else if (appProcessRepair.status === 'failed')
-        console.log(`Codex App reconnect repair: skipped (${appProcessRepair.error || appProcessRepair.reason || 'process check failed'}).`);
-    const globalSkills = await ensureGlobalCodexSkillsDuringInstall();
-    if (globalSkills.status === 'installed') {
-        const removed = globalSkills.removed_stale_generated_skills || [];
-        const cleanup = removed.length ? ` Removed stale generated skill shadow(s): ${removed.join(', ')}.` : '';
-        console.log(`Codex App global $ skills: installed in ${globalSkills.root} (${globalSkills.installed_count} skills).${cleanup}`);
-    }
-    else if (globalSkills.status === 'partial')
-        console.log(`Codex App global $ skills: partial in ${globalSkills.root}; missing ${(globalSkills.missing_skills ?? []).join(', ')}. Run \`sks doctor --fix\`.`);
-    else if (globalSkills.status === 'skipped')
-        console.log(`Codex App global $ skills: skipped (${globalSkills.reason}).`);
-    else if (globalSkills.status === 'failed')
-        console.log(`Codex App global $ skills: auto setup failed. Run \`sks doctor --fix\`. ${globalSkills.error || ''}`.trim());
-    const getdesignSkill = await ensureGlobalGetdesignSkillDuringInstall();
-    if (getdesignSkill.status === 'installed')
-        console.log('getdesign Codex skill: installed.');
-    else if (getdesignSkill.status === 'present')
-        console.log('getdesign Codex skill: already available.');
-    else if (getdesignSkill.status === 'skills_cli_missing')
-        console.log(`getdesign Codex skill: skills CLI missing; generated getdesign-reference skill is installed. Later run \`${getdesignSkill.install}\` if the skills CLI is available.`);
-    else if (getdesignSkill.status === 'skipped')
-        console.log(`getdesign Codex skill: skipped (${getdesignSkill.reason}).`);
-    else if (getdesignSkill.status === 'failed')
-        console.log(`getdesign Codex skill: auto setup failed; generated getdesign-reference skill remains available. ${getdesignSkill.error || ''}`.trim());
-    const bootstrapDecision = await postinstallBootstrapDecision(installRoot);
-    if (bootstrapDecision.run) {
-        console.log(`SKS bootstrap: ${bootstrapDecision.reason}.`);
-        await runPostinstallBootstrap(installRoot, bootstrap);
-        await restorePostinstallCodexLbConfigSnapshot(codexLbConfigSnapshot);
-        await reportPostinstallCodexLbAuth();
-        return;
+    // A failed setup side-effect must never fail `npm i`. Wrap the whole flow; always
+    // restore the codex-lb snapshot in finally (even on the early bootstrap return / on throw).
+    try {
+        console.log('\nSKS installed.');
+        const shim = await ensureSksCommandDuringInstall();
+        if (shim.status === 'present')
+            console.log(`SKS command: available (${shim.command ?? 'unknown'}).`);
+        else if (shim.status === 'repaired')
+            console.log(`SKS command: stale PATH shim repaired (${shim.command ?? 'unknown'}).`);
+        else if (shim.status === 'created')
+            console.log(`SKS command: shim created at ${shim.command ?? 'unknown'}.`);
+        else if (shim.status === 'created_not_on_path')
+            console.log(`SKS command: shim created at ${shim.command ?? 'unknown'}. Add ${path.dirname(shim.command ?? '')} to PATH, or run npx -y -p sneakoscope sks.`);
+        else if (shim.status === 'skipped')
+            console.log(`SKS command: skipped (${shim.reason}).`);
+        else
+            console.log(`SKS command: shim unavailable. Use npx -y -p sneakoscope sks. ${shim.error || ''}`.trim());
+        const context7Install = await ensureGlobalContext7DuringInstall();
+        if (context7Install.status === 'present')
+            console.log('Context7 MCP: already configured for Codex.');
+        else if (context7Install.status === 'installed')
+            console.log('Context7 MCP: configured for Codex.');
+        else if (context7Install.status === 'codex_missing')
+            console.log('Context7 MCP: Codex CLI missing. Install @openai/codex or set SKS_CODEX_BIN, then run `sks context7 setup --scope global` or `sks setup` in a project.');
+        else if (context7Install.status === 'skipped')
+            console.log(`Context7 MCP: skipped (${context7Install.reason}).`);
+        else if (context7Install.status === 'failed')
+            console.log(`Context7 MCP: auto setup failed. Run \`sks context7 setup --scope global\` or \`sks setup\`. ${context7Install.error || ''}`.trim());
+        const fastModeRepair = await ensureGlobalCodexFastModeDuringInstall();
+        if (fastModeRepair.status === 'updated')
+            console.log(`Codex App Fast mode: updated ${fastModeRepair.config_path}${fastModeRepair.backup_path ? ` (backup ${fastModeRepair.backup_path})` : ''}.`);
+        else if (fastModeRepair.status === 'present')
+            console.log('Codex App Fast mode: config already compatible.');
+        else if (fastModeRepair.status === 'unparseable_config_preserved')
+            console.log(`Codex App Fast mode: existing ${fastModeRepair.config_path} is not valid TOML — left untouched, backed up to ${fastModeRepair.backup_path}. Run \`sks doctor --fix\` to recover it.`);
+        else if (fastModeRepair.status === 'skipped_unsafe_rewrite')
+            console.log(`Codex App Fast mode: skipped (managed rewrite would not parse; ${fastModeRepair.config_path} left untouched).`);
+        else if (fastModeRepair.status === 'skipped')
+            console.log(`Codex App Fast mode: skipped (${fastModeRepair.reason}).`);
+        else if (fastModeRepair.status === 'failed')
+            console.log(`Codex App Fast mode: auto repair failed. Run \`sks setup\`. ${fastModeRepair.error || ''}`.trim());
+        // Terminating a third-party app's processes during `npm i` is unsafe by default; opt-in only.
+        const appProcessRepair = process.env.SKS_POSTINSTALL_RECONCILE_APP_PROCESSES === '1'
+            ? await reconcileCodexAppUpgradeProcesses()
+            : { status: 'skipped', reason: 'opt_in_required', killed: [] };
+        if (appProcessRepair.status === 'repaired')
+            console.log(`Codex App reconnect repair: stopped ${appProcessRepair.killed.length} stale orphan app-server process(es). Restart Codex App to reconnect cleanly.`);
+        else if (appProcessRepair.status === 'partial')
+            console.log(`Codex App reconnect repair: stopped ${appProcessRepair.killed.length} stale orphan app-server process(es); ${(appProcessRepair.failed ?? []).length} could not be stopped. Restart Codex App if reconnecting continues.`);
+        else if (appProcessRepair.status === 'skipped' && appProcessRepair.reason === 'opt_in_required')
+            console.log('Codex App reconnect repair: not run (set SKS_POSTINSTALL_RECONCILE_APP_PROCESSES=1 to allow postinstall to stop stale orphan app-server processes; otherwise run `sks doctor --fix`).');
+        else if (appProcessRepair.status === 'skipped' && appProcessRepair.reason !== 'platform')
+            console.log(`Codex App reconnect repair: skipped (${appProcessRepair.reason}).`);
+        else if (appProcessRepair.status === 'failed')
+            console.log(`Codex App reconnect repair: skipped (${appProcessRepair.error || appProcessRepair.reason || 'process check failed'}).`);
+        const globalSkills = await ensureGlobalCodexSkillsDuringInstall();
+        if (globalSkills.status === 'installed') {
+            const removed = globalSkills.removed_stale_generated_skills || [];
+            const cleanup = removed.length ? ` Removed stale generated skill shadow(s): ${removed.join(', ')}.` : '';
+            console.log(`Codex App global $ skills: installed in ${globalSkills.root} (${globalSkills.installed_count} skills).${cleanup}`);
+        }
+        else if (globalSkills.status === 'partial')
+            console.log(`Codex App global $ skills: partial in ${globalSkills.root}; missing ${(globalSkills.missing_skills ?? []).join(', ')}. Run \`sks doctor --fix\`.`);
+        else if (globalSkills.status === 'skipped')
+            console.log(`Codex App global $ skills: skipped (${globalSkills.reason}).`);
+        else if (globalSkills.status === 'failed')
+            console.log(`Codex App global $ skills: auto setup failed. Run \`sks doctor --fix\`. ${globalSkills.error || ''}`.trim());
+        const getdesignSkill = await ensureGlobalGetdesignSkillDuringInstall();
+        if (getdesignSkill.status === 'installed')
+            console.log('getdesign Codex skill: installed.');
+        else if (getdesignSkill.status === 'present')
+            console.log('getdesign Codex skill: already available.');
+        else if (getdesignSkill.status === 'skills_cli_missing')
+            console.log(`getdesign Codex skill: skills CLI missing; generated getdesign-reference skill is installed. Later run \`${getdesignSkill.install}\` if the skills CLI is available.`);
+        else if (getdesignSkill.status === 'skipped')
+            console.log(`getdesign Codex skill: skipped (${getdesignSkill.reason}).`);
+        else if (getdesignSkill.status === 'failed')
+            console.log(`getdesign Codex skill: auto setup failed; generated getdesign-reference skill remains available. ${getdesignSkill.error || ''}`.trim());
+        const bootstrapDecision = await postinstallBootstrapDecision(installRoot);
+        if (bootstrapDecision.run) {
+            console.log(`SKS bootstrap: ${bootstrapDecision.reason}.`);
+            await runPostinstallBootstrap(installRoot, bootstrap);
+            return;
+        }
+        console.log('\nNext:');
+        console.log('  sks bootstrap');
+        console.log(`\nSKS bootstrap was not run automatically: ${bootstrapDecision.reason}.`);
+        console.log('This initializes the current project, installs SKS Codex App skills, verifies Codex App/Context7 readiness, and checks Zellij runtime dependencies.');
+        console.log('Dependency repair: sks bootstrap --yes, sks deps check --yes, or sks --mad --yes. Postinstall reports missing CLI tools but does not mutate Homebrew/npm globals unless SKS_POSTINSTALL_AUTO_INSTALL_CLI_TOOLS=1 is set.');
+        console.log('Open runtime after readiness is green: sks\n');
+    }
+    catch (err) {
+        console.log(`\nSKS postinstall: a setup step did not complete; installation continues. Run \`sks doctor --fix\` afterward. (${err?.message || err})`);
+    }
+    finally {
+        await restorePostinstallCodexLbConfigSnapshot(codexLbConfigSnapshot).catch(() => { });
+        await reportPostinstallCodexLbAuth().catch(() => { });
     }
-    await restorePostinstallCodexLbConfigSnapshot(codexLbConfigSnapshot);
-    await reportPostinstallCodexLbAuth();
-    console.log('\nNext:');
-    console.log('  sks bootstrap');
-    console.log(`\nSKS bootstrap was not run automatically: ${bootstrapDecision.reason}.`);
-    console.log('This initializes the current project, installs SKS Codex App skills, verifies Codex App/Context7 readiness, and checks Zellij runtime dependencies.');
-    console.log('Dependency repair: sks deps check; install Zellij with brew install zellij when needed.');
-    console.log('Open runtime after readiness is green: sks\n');
 }
 async function reportPostinstallCodexLbAuth() {
     const codexLbAuth = await ensureCodexLbAuthDuringInstall();
@@ -128,6 +144,8 @@ async function reportPostinstallCodexLbAuth() {
         console.log('codex-lb auth: stored key missing. Run `sks codex-lb setup --host <domain> --api-key <key>` to repair.');
     else if (codexLbAuth.status === 'missing_base_url')
         console.log('codex-lb auth: stored key has no recoverable base URL. Run `sks codex-lb reconfigure --host <domain> --api-key <key>` once.');
+    else if (codexLbAuth.status === 'not_configured')
+        console.log('codex-lb (optional multi-account load balancer): not configured — opt in anytime with `sks codex-lb setup` (your choice; never applied automatically, never edits your Codex config without it). Swap key later: `sks codex-lb set-key`; switch auth: `sks codex-lb use-oauth` / `use-codex-lb`.');
     else if (codexLbAuth.status && codexLbAuth.status !== 'not_configured')
         console.log(`codex-lb auth: repair skipped (${codexLbAuth.status}${codexLbAuth.error ? `: ${codexLbAuth.error}` : ''}).`);
     const reconcile = codexLbAuth.auth_reconcile;
@@ -197,6 +215,12 @@ export async function postinstallBootstrapDecision(root) {
     const target = candidate ? installRoot : globalSksRoot();
     if (process.env.SKS_POSTINSTALL_BOOTSTRAP === '1')
         return { run: true, target, reason: 'forced by SKS_POSTINSTALL_BOOTSTRAP=1' };
+    // A global `npm i -g sneakoscope` must NOT initialize whatever project the user's shell
+    // happened to be in (that would scribble AGENTS.md/.codex/.agents into an unrelated repo).
+    // Only bootstrap the global runtime root; the user runs `sks setup` inside a project explicitly.
+    if (process.env.npm_config_global === 'true' && candidate) {
+        return { run: true, target: globalSksRoot(), reason: 'global install: bootstrapping global SKS runtime only (run `sks setup` inside a project to initialize it)' };
+    }
     if (candidate)
         return { run: true, target, reason: 'auto-running sks setup --bootstrap --install-scope global --force' };
     return { run: true, target, reason: 'no project marker found; auto-running global SKS runtime bootstrap' };
@@ -267,8 +291,8 @@ async function restorePostinstallCodexLbConfigSnapshot(snapshot) {
         const next = normalizeCodexFastModeUiConfig(upsertCodexLbConfig(current, snapshot.base_url));
         const alreadyOk = next === ensureTrailingNewline(current) && codexLbProviderBaseUrl(current);
         if (!alreadyOk) {
-            await writeTextAtomic(snapshot.config_path, next);
-            configRestored = true;
+            const safeWrite = await safeWriteCodexConfigToml(snapshot.config_path, current, next, 'codex-lb-restore');
+            configRestored = safeWrite.ok && safeWrite.changed === true;
         }
     }
     // Restore auth.json only if bootstrap accidentally wiped or emptied a pre-existing auth.json.
@@ -347,8 +371,10 @@ export async function configureCodexLb(opts = {}) {
     await ensureDir(path.dirname(configPath));
     const current = await readText(configPath, '');
     const next = normalizeCodexFastModeUiConfig(upsertCodexLbConfig(current, baseUrl, useDefaultProvider));
-    await writeTextAtomic(configPath, next);
-    appliedActions.push({ type: 'write_config_provider', target: configPath, ok: true });
+    const safeWrite = await safeWriteCodexConfigToml(configPath, current, next, 'codex-lb');
+    if (!safeWrite.ok)
+        return { ok: false, status: safeWrite.status, config_path: configPath, env_path: envPath, backup_path: safeWrite.backup_path };
+    appliedActions.push({ type: 'write_config_provider', target: configPath, ok: true, backup_path: safeWrite.backup_path });
     if (useDefaultProvider)
         appliedActions.push({ type: 'select_default_provider', target: configPath, ok: true });
     if (writeEnvFile) {
@@ -789,8 +815,8 @@ export async function repairCodexLbAuth(opts = {}) {
     if (status.env_key_configured && status.base_url && (!status.ok || !status.selected || !status.provider_uses_codex_lb_env_auth || legacyAuthMigrated || hasTopLevelCodexModeLock(currentConfig))) {
         await ensureDir(path.dirname(status.config_path));
         const next = normalizeCodexFastModeUiConfig(upsertCodexLbConfig(currentConfig, status.base_url));
-        await writeTextAtomic(status.config_path, next);
-        configRepaired = true;
+        const safeWrite = await safeWriteCodexConfigToml(status.config_path, currentConfig, next, 'codex-lb-repair');
+        configRepaired = safeWrite.ok && safeWrite.changed === true;
         status = await codexLbStatus(opts);
     }
     if (!status.ok) {
@@ -1352,7 +1378,7 @@ async function syncCodexApiKeyLogin(apiKey, opts = {}) {
         return { ok: true, status: 'synced' };
     return { ok: false, status: 'login_failed', error: redactSecretText(login.stderr || login.stdout || 'codex login failed', [apiKey]).trim() };
 }
-function upsertCodexLbConfig(text = '', baseUrl, selectDefault = true) {
+export function upsertCodexLbConfig(text = '', baseUrl, selectDefault = true) {
     let next = selectDefault
         ? upsertTopLevelTomlString(text, 'model_provider', 'codex-lb')
         : removeTopLevelTomlKeyIfValue(text, 'model_provider', 'codex-lb');
@@ -1442,41 +1468,61 @@ export async function ensureGlobalCodexFastModeDuringInstall(opts = {}) {
     try {
         await ensureDir(path.dirname(configPath));
         const current = await readText(configPath, '');
+        // Safety gate 1: never blind-overwrite an unparseable user config — that would
+        // entrench corruption on the file Codex actually loads. Back it up and bail.
+        if (current.trim()) {
+            const currentSmoke = codexConfigParseSmoke(current);
+            if (!currentSmoke.ok) {
+                const backupPath = await backupCodexConfig(configPath, current, 'unparseable');
+                return { status: 'unparseable_config_preserved', config_path: configPath, backup_path: backupPath, parse_smoke: currentSmoke };
+            }
+        }
         const next = normalizeCodexFastModeUiConfig(current);
         if (next === ensureTrailingNewline(current))
             return { status: 'present', config_path: configPath };
+        // Safety gate 2: never WRITE a config that would not parse.
+        const nextSmoke = codexConfigParseSmoke(next);
+        if (!nextSmoke.ok)
+            return { status: 'skipped_unsafe_rewrite', config_path: configPath, parse_smoke: nextSmoke };
+        // Safety gate 3: back up the user's good config before mutating it.
+        const backupPath = current.trim() ? await backupCodexConfig(configPath, current, 'pre-update') : null;
         await writeTextAtomic(configPath, next);
-        return { status: 'updated', config_path: configPath };
+        return { status: 'updated', config_path: configPath, backup_path: backupPath };
     }
     catch (err) {
         return { status: 'failed', config_path: configPath, error: err.message };
     }
 }
 export function normalizeCodexFastModeUiConfig(text = '') {
-    let next = removeLegacyTopLevelCodexModeLocks(text);
+    // Run to a fixed point so a second install is a true no-op (idempotent). The per-pass
+    // table/whitespace normalization converges within one extra pass.
+    return normalizeCodexFastModeUiConfigOnce(normalizeCodexFastModeUiConfigOnce(text));
+}
+function normalizeCodexFastModeUiConfigOnce(text = '') {
+    // Preserve user-owned top-level scalars (model / service_tier / model_reasoning_effort):
+    // SKS only supplies a default when the user has not chosen one, and never strips the
+    // user's own reasoning effort. SKS continues to manage its own namespaced tables below
+    // ([features], [profiles.sks-*], [user.fast_mode], [plugins]).
+    let next = String(text || '');
     next = removeTomlTableKey(next, 'notice', 'fast_default_opt_out');
     next = removeTomlTableKey(next, 'features', 'codex_hooks');
-    next = upsertTopLevelTomlString(next, 'model', 'gpt-5.5');
-    next = upsertTopLevelTomlString(next, 'service_tier', 'fast');
-    next = upsertTopLevelTomlBoolean(next, 'suppress_unstable_features_warning', true);
-    next = upsertTomlTableKey(next, 'features', 'hooks = true');
-    next = upsertTomlTableKey(next, 'features', 'remote_control = true');
-    next = upsertTomlTableKey(next, 'features', 'multi_agent = true');
-    next = upsertTomlTableKey(next, 'features', 'fast_mode = true');
-    next = upsertTomlTableKey(next, 'features', 'fast_mode_ui = true');
-    next = upsertTomlTableKey(next, 'features', 'codex_git_commit = true');
-    next = upsertTomlTableKey(next, 'features', 'computer_use = true');
-    next = upsertTomlTableKey(next, 'features', 'browser_use = true');
-    next = upsertTomlTableKey(next, 'features', 'browser_use_external = true');
-    next = upsertTomlTableKey(next, 'features', 'image_generation = true');
-    next = upsertTomlTableKey(next, 'features', 'in_app_browser = true');
-    next = upsertTomlTableKey(next, 'features', 'guardian_approval = true');
-    next = upsertTomlTableKey(next, 'features', 'tool_suggest = true');
-    next = upsertTomlTableKey(next, 'features', 'apps = true');
-    next = upsertTomlTableKey(next, 'features', 'plugins = true');
-    next = upsertTomlTableKey(next, 'user.fast_mode', 'visible = true');
-    next = upsertTomlTableKey(next, 'user.fast_mode', 'enabled = true');
-    next = upsertTomlTableKey(next, 'user.fast_mode', 'default_profile = "sks-fast-high"');
+    next = upsertTopLevelTomlStringIfAbsent(next, 'model', 'gpt-5.5');
+    next = upsertTopLevelTomlStringIfAbsent(next, 'service_tier', 'fast');
+    // Codex App feature flags / fast-mode UI / suppress-warning are SET-IF-ABSENT: a fresh
+    // config still gets SKS's defaults, but SKS NEVER overrides (re-enables) a feature the
+    // user disabled in the App, and never rejects-then-hides UI by forcing an unrecognized
+    // flag on an older App build. This is what stops SKS from "removing/blocking" the App UI.
+    next = upsertTopLevelTomlBooleanIfAbsent(next, 'suppress_unstable_features_warning', true);
+    for (const featureLine of [
+        'hooks = true', 'remote_control = true', 'multi_agent = true', 'fast_mode = true',
+        'fast_mode_ui = true', 'codex_git_commit = true', 'computer_use = true', 'browser_use = true',
+        'browser_use_external = true', 'image_generation = true', 'in_app_browser = true',
+        'guardian_approval = true', 'tool_suggest = true', 'apps = true', 'plugins = true'
+    ])
+        next = upsertTomlTableKeyIfAbsent(next, 'features', featureLine);
+    next = upsertTomlTableKeyIfAbsent(next, 'user.fast_mode', 'visible = true');
+    next = upsertTomlTableKeyIfAbsent(next, 'user.fast_mode', 'enabled = true');
+    next = upsertTomlTableKeyIfAbsent(next, 'user.fast_mode', 'default_profile = "sks-fast-high"');
     next = upsertTomlTableKey(next, 'profiles.sks-fast-high', 'model = "gpt-5.5"');
     next = upsertTomlTableKey(next, 'profiles.sks-fast-high', 'service_tier = "fast"');
     next = upsertTomlTableKey(next, 'profiles.sks-fast-high', 'approval_policy = "on-request"');
@@ -1492,9 +1538,17 @@ export function normalizeCodexFastModeUiConfig(text = '') {
     next = upsertTomlTableKey(next, 'profiles.sks-research', 'approval_policy = "never"');
     next = upsertTomlTableKey(next, 'profiles.sks-research', 'sandbox_mode = "workspace-write"');
     next = upsertTomlTableKey(next, 'profiles.sks-research', 'model_reasoning_effort = "xhigh"');
-    for (const [name, marketplace] of DEFAULT_CODEX_APP_PLUGINS) {
-        const table = `plugins."${name}@${marketplace}"`;
-        next = upsertTomlTable(next, table, `[${table}]\nenabled = true`);
+    // Plugin auto-enable is OPT-IN only. Force-writing `[plugins."name@marketplace"] enabled =
+    // true` for marketplace plugins the App may not have installed (different build/channel)
+    // makes the App reference plugins it cannot load -> broken/blocked plugin UI. It also
+    // replaced the user's whole plugin table, reverting any `enabled = false` they set. By
+    // default SKS leaves the user's [plugins] alone; opt in with SKS_MANAGE_CODEX_APP_PLUGINS=1.
+    if (process.env.SKS_MANAGE_CODEX_APP_PLUGINS === '1') {
+        for (const [name, marketplace] of DEFAULT_CODEX_APP_PLUGINS) {
+            const table = `plugins."${name}@${marketplace}"`;
+            if (!hasTomlTable(next, table))
+                next = upsertTomlTable(next, table, `[${table}]\nenabled = true`);
+        }
     }
     return ensureTrailingNewline(next);
 }
@@ -1568,6 +1622,35 @@ function upsertTomlTableKey(text, table, line) {
     lines.splice(end, 0, line);
     return lines.join('\n').replace(/\n{3,}/g, '\n\n');
 }
+// True if [table] already declares `key` (so we never override a user's explicit value).
+function hasTomlTableKey(text, table, key) {
+    const lines = String(text || '').split('\n');
+    const header = `[${table}]`;
+    const start = lines.findIndex((x) => x.trim() === header);
+    if (start === -1)
+        return false;
+    const keyRe = new RegExp(`^\\s*${escapeRegExp(key)}\\s*=`);
+    for (let i = start + 1; i < lines.length; i += 1) {
+        const ln = lines[i];
+        if (ln === undefined)
+            continue;
+        if (/^\s*\[.+\]\s*$/.test(ln))
+            break;
+        if (keyRe.test(ln))
+            return true;
+    }
+    return false;
+}
+// Set a [table] key only when absent — preserves a Codex App feature the user toggled off
+// (so SKS never re-enables / re-surfaces UI the user hid). On a fresh config the key/table
+// is still created, preserving fresh-install enablement.
+function upsertTomlTableKeyIfAbsent(text, table, line) {
+    const key = String(line).split('=')[0]?.trim() ?? '';
+    return hasTomlTableKey(text, table, key) ? String(text || '') : upsertTomlTableKey(text, table, line);
+}
+function upsertTopLevelTomlBooleanIfAbsent(text, key, value) {
+    return hasTopLevelTomlKey(text, key) ? String(text || '') : upsertTopLevelTomlBoolean(text, key, value);
+}
 function ensureTrailingNewline(text = '') {
     const value = String(text || '').trimEnd();
     return value ? `${value}\n` : '';
@@ -1589,6 +1672,65 @@ function upsertTopLevelTomlString(text, key, value) {
     lines.splice(end, 0, line);
     return lines.join('\n').replace(/^\n+/, '').replace(/\n{3,}/g, '\n\n');
 }
+function hasTopLevelTomlKey(text, key) {
+    const lines = String(text || '').split('\n');
+    const firstTable = lines.findIndex((x) => /^\s*\[.+\]\s*$/.test(x));
+    const end = firstTable === -1 ? lines.length : firstTable;
+    const pattern = new RegExp(`^\\s*${escapeRegExp(key)}\\s*=`);
+    for (let i = 0; i < end; i += 1) {
+        if (typeof lines[i] === 'string' && pattern.test(lines[i]))
+            return true;
+    }
+    return false;
+}
+// Preserve a user's deliberate top-level scalar (model/service_tier/reasoning); only set
+// the SKS default when the key is ABSENT. This is what stops `npm i -g` from clobbering
+// a user's global Codex config on every update.
+function upsertTopLevelTomlStringIfAbsent(text, key, value) {
+    return hasTopLevelTomlKey(text, key) ? String(text || '') : upsertTopLevelTomlString(text, key, value);
+}
+// Lightweight safety gate: detect clearly-broken TOML so we never overwrite (or produce)
+// an unparseable config that Codex itself would reject. Mirrors the project-config smoke.
+function codexConfigParseSmoke(text = '') {
+    const str = String(text || '');
+    const tripleTokens = (str.match(/"""|'''/g) || []).length;
+    const unterminatedTriple = tripleTokens % 2 !== 0;
+    const invalidHeader = str.split('\n').find((line) => /^\s*\[/.test(line) && !/^\s*\[\[?[^\]]+\]\]?\s*(?:#.*)?$/.test(line)) || null;
+    return { ok: !unterminatedTriple && !invalidHeader, unterminated_multiline_string: unterminatedTriple, invalid_table_header: invalidHeader };
+}
+async function backupCodexConfig(configPath, text, tag) {
+    try {
+        const stamp = `${PACKAGE_VERSION}-${Date.now().toString(36)}`;
+        const backupPath = `${configPath}.sks-${tag}-${stamp}.bak`;
+        await writeTextAtomic(backupPath, text);
+        return backupPath;
+    }
+    catch {
+        return null;
+    }
+}
+// Single TOML-safe gate for every codex-lb config write. Mirrors the fast-mode safety so the
+// codex-lb path can NEVER corrupt ~/.codex/config.toml on install (esp. a fresh/initial one):
+//   - refuse to overwrite an existing config that is already unparseable (back it up, bail),
+//   - refuse to WRITE a result that would not parse (e.g. a regex helper mangled a multiline
+//     string), leaving the existing config untouched,
+//   - otherwise back up the prior config before mutating.
+export async function safeWriteCodexConfigToml(configPath, current, next, tag = 'codex-lb') {
+    const cur = String(current || '');
+    if (cur.trim() && !codexConfigParseSmoke(cur).ok) {
+        const backupPath = await backupCodexConfig(configPath, cur, `${tag}-unparseable`);
+        return { ok: false, status: 'unparseable_config_preserved', config_path: configPath, backup_path: backupPath };
+    }
+    if (!codexConfigParseSmoke(next).ok) {
+        return { ok: false, status: 'skipped_unsafe_rewrite', config_path: configPath, backup_path: null };
+    }
+    if (next === ensureTrailingNewline(cur)) {
+        return { ok: true, status: 'present', config_path: configPath, backup_path: null, changed: false };
+    }
+    const backupPath = cur.trim() ? await backupCodexConfig(configPath, cur, tag) : null;
+    await writeTextAtomic(configPath, next);
+    return { ok: true, status: 'written', config_path: configPath, backup_path: backupPath, changed: true };
+}
 function upsertTopLevelTomlBoolean(text, key, value) {
     const line = `${key} = ${value ? 'true' : 'false'}`;
     const lines = String(text || '').split('\n');
@@ -1606,6 +1748,10 @@ function upsertTopLevelTomlBoolean(text, key, value) {
     lines.splice(end, 0, line);
     return lines.join('\n').replace(/^\n+/, '').replace(/\n{3,}/g, '\n\n');
 }
+function hasTomlTable(text, table) {
+    const header = `[${table}]`;
+    return String(text || '').split('\n').some((line) => String(line).trim() === header);
+}
 function upsertTomlTable(text, table, block) {
     let lines = String(text || '').trimEnd().split('\n');
     if (lines.length === 1 && lines[0] === '')
@@ -1915,7 +2061,7 @@ async function ensureGlobalGetdesignSkillDuringInstall() {
 }
 export async function ensureRelatedCliTools(args = []) {
     const skip = args.includes('--skip-cli-tools') || process.env.SKS_SKIP_CLI_TOOLS === '1';
-    const codex = await ensureCodexCliTool({ skip });
+    const codex = await ensureCodexCliTool({ skip, args });
     const zellijRepair = skip ? { status: 'skipped', reason: 'SKS_SKIP_CLI_TOOLS=1 or --skip-cli-tools' } : await ensureZellijCliTool(args);
     const zellij = await checkZellijCapability({ require: false, writeReport: false });
     return {
@@ -1928,11 +2074,42 @@ export async function ensureRelatedCliTools(args = []) {
             current_session: false,
             repair: zellijRepair,
             install_hint: zellij.status === 'ok' ? null : zellijInstallHint(),
-            error: zellij.blockers[0] || zellij.warnings[0] || null
+            error: zellijRepair.error || zellij.blockers[0] || zellij.warnings[0] || null
+        }
+    };
+}
+export async function ensureMadLaunchDependencies(args = []) {
+    const skip = args.includes('--skip-cli-tools') || process.env.SKS_SKIP_CLI_TOOLS === '1';
+    const zellijRepair = skip ? { target: 'zellij', status: 'skipped', reason: 'SKS_SKIP_CLI_TOOLS=1 or --skip-cli-tools' } : await ensureZellijCliTool(args);
+    const zellij = await checkZellijCapability({ require: false, writeReport: false });
+    const ready = zellij.status === 'ok';
+    return {
+        ready,
+        actions: ready ? [] : [{
+                target: 'zellij',
+                status: zellijRepair.status,
+                command: zellijRepair.command || zellijInstallHint(),
+                error: zellijRepair.error || zellij.blockers[0] || zellij.warnings[0] || null,
+                repair: zellijRepair
+            }],
+        status: {
+            zellij: {
+                ok: ready,
+                status: zellij.status,
+                version: zellij.version,
+                min_version: zellij.min_version,
+                repair: zellijRepair,
+                install_hint: ready ? null : zellijInstallHint()
+            }
         }
     };
 }
-export async function ensureCodexCliTool({ skip = false } = {}) {
+export function formatMadLaunchDependencyAction(action = {}) {
+    const command = action.command ? ` Run: ${action.command}.` : '';
+    const error = action.error ? ` ${action.error}` : '';
+    return `${action.target || 'dependency'} ${action.status || 'blocked'}.${command}${error}`.trim();
+}
+export async function ensureCodexCliTool({ skip = false, args = [] } = {}) {
     if (skip)
         return { status: 'skipped', reason: 'SKS_SKIP_CLI_TOOLS=1 or --skip-cli-tools' };
     const before = await getCodexInfo().catch(() => EMPTY_CODEX_INFO);
@@ -1941,6 +2118,12 @@ export async function ensureCodexCliTool({ skip = false } = {}) {
     const npmBin = await which('npm');
     if (!npmBin)
         return { status: 'failed', error: 'npm not found on PATH; install Codex CLI manually with npm i -g @openai/codex@latest.' };
+    const command = 'npm i -g @openai/codex@latest';
+    if (args.includes('--dry-run'))
+        return { status: 'dry_run', command, error: 'Codex CLI not found on PATH.' };
+    if (!await confirmInstallYesDefault(`Codex CLI is missing. Install latest Codex CLI with ${command}?`, args)) {
+        return { status: 'needs_approval', command, error: 'Codex CLI not found on PATH.' };
+    }
     const install = await runProcess(npmBin, ['i', '-g', '@openai/codex@latest'], {
         timeoutMs: 120000,
         maxOutputBytes: 128 * 1024
@@ -1969,24 +2152,27 @@ export async function ensureZellijCliTool(args = [], opts = {}) {
     const repairCommand = command;
     if (args.includes('--dry-run') || opts.dryRun)
         return { target: 'zellij', status: 'dry_run', command: repairCommand, error: before.blockers[0] || before.warnings[0] || null };
-    const question = before.bin
+    const hasInstalledZellij = Boolean(before.version);
+    const question = hasInstalledZellij
         ? `Homebrew Zellij ${before.version || 'unknown'} is not ready. Upgrade to latest Zellij with ${repairCommand}?`
         : `Zellij is missing. Install latest Zellij with ${repairCommand}?`;
     if (!await confirmInstallYesDefault(question, args))
         return { target: 'zellij', status: 'needs_approval', command: repairCommand, error: before.blockers[0] || before.warnings[0] || null };
-    const brewArgs = before.bin ? ['upgrade', 'zellij'] : ['install', 'zellij'];
+    const brewArgs = hasInstalledZellij ? ['upgrade', 'zellij'] : ['install', 'zellij'];
     const install = await runProcess(brew, brewArgs, { timeoutMs: 180000, maxOutputBytes: 128 * 1024 }).catch((err) => ({ code: 1, stdout: '', stderr: err.message }));
     if (install.code !== 0)
         return { target: 'zellij', status: 'failed', command: repairCommand, error: `${install.stderr || install.stdout || repairCommand + ' failed'}`.trim() };
     const after = await checkZellijCapability({ require: false, writeReport: false });
     if (after.status !== 'ok')
         return { target: 'zellij', status: 'installed_not_ready', command: repairCommand, error: after.blockers[0] || after.warnings[0] || 'zellij installed but not ready' };
-    return { target: 'zellij', status: before.version ? 'upgraded' : 'installed', command: repairCommand, bin: after.bin, version: after.version || null };
+    return { target: 'zellij', status: hasInstalledZellij ? 'upgraded' : 'installed', command: repairCommand, bin: after.bin, version: after.version || null };
 }
 function zellijInstallHint() {
     return process.platform === 'darwin' ? 'brew install zellij' : 'Install Zellij from https://zellij.dev/documentation/installation.html';
 }
 async function confirmInstallYesDefault(question, args = []) {
+    if (hasFlag(args, '--from-postinstall') && process.env.SKS_POSTINSTALL_AUTO_INSTALL_CLI_TOOLS !== '1')
+        return false;
     if (shouldAutoApproveInstall(args))
         return true;
     if (!canAskYesNo())
@@ -2023,6 +2209,10 @@ export async function maybePromptCodexUpdateForLaunch(args = [], opts = {}) {
     return installCodexLatest(command, latest.version, current);
 }
 export function shouldAutoApproveInstall(args = [], env = process.env) {
+    if (hasFlag(args, '--from-postinstall') && env.SKS_POSTINSTALL_AUTO_INSTALL_CLI_TOOLS !== '1')
+        return false;
+    if (hasFlag(args, '--from-postinstall') && env.SKS_POSTINSTALL_AUTO_INSTALL_CLI_TOOLS === '1')
+        return true;
     return hasFlag(args, '--yes') || hasFlag(args, '-y') || isAgentRuntime(env);
 }
 function canAskYesNo() {