sneakoscope 1.0.5 → 1.0.7

package/README.md

@@ -4,7 +4,11 @@ Fast legacy-free proof-first Codex trust layer with image-based Voxel TriWiki.
 
 Sneakoscope Codex (`sks`) is a Codex CLI/App harness that makes repeatable Codex work auditable.
 
-SKS **1.0.5** seals the Codex trust harness: hook outputs are validated against both vendored OpenAI Codex CLI `rust-v0.131.0` schemas and runtime semantic parser rules, codex-lb setup survives macOS user-session launches through env-file/Keychain/launchctl-aware repair surfaces, and Computer Use is the preferred macOS visual evidence capability when available.
+SKS **1.0.7** is the Ultimate Final Completion seal for the Codex trust harness: Computer Use live evidence is an opt-in, local-only macOS evidence path with explicit `probe_only`, `live_capture_attempted`, `live_capture_success`, and `live_capture_blocked` modes; `codex-lb setup` reports durable persistence versus `process_only_ephemeral` honestly; and docs/release readiness checks block mock/probe/live overclaims.
+
+SKS **1.0.6** is the final precision polish for the Codex trust harness: hook compatibility is classified as upstream schema plus an SKS zero-warning strict subset, `sks codex-lb setup` previews and applies the exact choices the user selected, and Computer Use has an optional live smoke surface for macOS capability/evidence status.
+
+SKS **1.0.5** sealed the prior trust harness: hook outputs were validated against both vendored OpenAI Codex CLI `rust-v0.131.0` schemas and runtime semantic parser rules, codex-lb setup survived macOS user-session launches through env-file/Keychain/launchctl-aware repair surfaces, and Computer Use became the preferred macOS visual evidence capability when available.
 
 SKS **1.0.4** introduced the `rust-v0.131.0` schema snapshot, guided codex-lb setup path, and Computer Use/MAD-SKS separation that 1.0.5 now hardens into release gates.
 
@@ -18,8 +22,62 @@ Hybrid-free **`1.0.1`** already delivered the CLI entrypoint/router/registry/Tru
 
 SKS does not try to clone every other harness. It focuses on one thing: making Codex work auditable, visual-evidence-bound, safety-gated, and reproducible through Completion Proof.
 
-![Sneakoscope Codex architecture and pipeline](https://raw.githubusercontent.com/mandarange/Sneakoscope-Codex/dev/docs/assets/sneakoscope-architecture-pipeline.jpg)
+![Sneakoscope Codex Trust Layer](docs/assets/sneakoscope-architecture-pipeline.jpg)
+
+
+## 1.0.7 Ultimate Final Completion
+
+1.0.7 does not add a new route, skill, or competing harness. It closes the last trust gaps around live visual evidence, persistence truth, and release documentation.
+
+Computer Use live evidence stays optional and explicit:
+
+```bash
+sks computer-use smoke --json
+sks computer-use smoke --real --capture-screenshot --json
+sks computer-use smoke --real --require-real --json
+npm run computer-use:live-evidence
+```
+
+Default smoke is `probe_only` and never attempts screen capture. Real mode records `live_capture_attempted`, `live_capture_success`, or `live_capture_blocked`; if Codex App, macOS permission, or the official Computer Use capture surface is unavailable, SKS writes a structured blocker instead of fabricated evidence. Browser Use evidence and manual screenshots remain separate sources. Computer Use screenshots are local-only by default, carry SHA-256 metadata, and link to Image Voxel only when a mission-local anchor can be made.
+
+codex-lb setup now reports the exact persistence truth:
+
+```bash
+sks codex-lb setup --host lb.example.com --api-key-stdin --plan --json
+sks codex-lb setup --host lb.example.com --api-key-stdin --yes --no-env-file --no-keychain --no-launchctl --shell-profile skip --json
+npm run codex-lb:persistence-truth
+```
+
+Durable modes are `durable_env_file`, `durable_keychain`, `durable_launchctl`, and `shell_profile`. If all durable modes are disabled, setup is classified as `process_only_ephemeral`, emits `next_shell_requires_setup_or_env`, and warns that Codex App GUI launches may not see credentials. Use `sks codex-lb setup --write-env-file --keychain --launchctl` to recover durable persistence.
 
+Documentation truthfulness is now a release invariant:
+
+```bash
+npm run docs:truthfulness
+npm run release:readiness
+```
+
+The hook compatibility surface remains the upstream schema plus the SKS zero-warning strict subset; SKS does not claim to mirror every upstream runtime parser rule or guarantee universal Computer Use availability.
+
+## 1.0.6 Final Precision Polish
+
+SKS validates Codex hooks against the OpenAI Codex `rust-v0.131.0` schema and enforces a stricter SKS zero-warning subset. Some fields may be accepted by upstream but are intentionally disallowed by SKS to avoid user-facing hook warnings and release drift. `sks hooks warning-check --json` now reports `schema_violation`, `upstream_semantic_unsupported`, `sks_zero_warning_disallowed`, `legacy_shape`, and `policy_disallowed` category counts.
+
+`sks codex-lb setup` is now a two-phase plan/apply wizard. Every question maps to an actual action: provider selection, env file writing, Keychain storage, launchctl sync, shell profile snippets, and health checks.
+
+```bash
+sks codex-lb setup --host lb.example.com --api-key-stdin --plan --json
+sks codex-lb setup --host lb.example.com --api-key-stdin --yes --no-default-provider --no-env-file --json
+npm run codex-lb:setup-truthfulness
+```
+
+Computer Use live validation is optional and opt-in. On macOS, `SKS_TEST_REAL_COMPUTER_USE=1 sks computer-use smoke --real --json` attempts a non-destructive capability/evidence check. If Codex App or macOS denies the capability, SKS records a structured blocker and does not fabricate visual evidence.
+
+```bash
+sks computer-use smoke --json
+SKS_TEST_REAL_COMPUTER_USE=1 sks computer-use smoke --real --json
+npm run computer-use:live-optional
+```
 
 ## 1.0.5 Ultimate Harness Seal
 

package/crates/sks-core/Cargo.lock

@@ -76,7 +76,7 @@ dependencies = [
 
 [[package]]
 name = "sks-core"
-version = "1.0.5"
+version = "1.0.7"
 dependencies = [
  "serde_json",
 ]

package/crates/sks-core/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "sks-core"
-version = "1.0.5"
+version = "1.0.7"
 edition = "2021"
 
 [dependencies]

package/crates/sks-core/src/main.rs

@@ -4,7 +4,7 @@ use std::io::{self, Read, Seek, SeekFrom};
 fn main() {
     let mut args = std::env::args().skip(1);
     match args.next().as_deref() {
-        Some("--version") => println!("sks-rs 1.0.5"),
+        Some("--version") => println!("sks-rs 1.0.7"),
         Some("compact-info") => {
             let mut input = String::new();
             let _ = io::stdin().read_to_string(&mut input);

package/dist/bin/sks.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-const FAST_PACKAGE_VERSION = '1.0.5';
+const FAST_PACKAGE_VERSION = '1.0.7';
 const args = process.argv.slice(2);
 try {
     if (args[0] === '--version' || args[0] === '-v' || args[0] === 'version') {

package/dist/build-manifest.json

@@ -1,6 +1,6 @@
 {
   "schema": "sks.dist-build.v2",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "typescript": true,
   "mjs_runtime_files": 0,
   "files": [
@@ -188,6 +188,8 @@
     "core/codex-compat/codex-compat-report.js",
     "core/codex-compat/codex-config-policy.d.ts",
     "core/codex-compat/codex-config-policy.js",
+    "core/codex-compat/codex-hook-issues.d.ts",
+    "core/codex-compat/codex-hook-issues.js",
     "core/codex-compat/codex-hook-output-builders.d.ts",
     "core/codex-compat/codex-hook-output-builders.js",
     "core/codex-compat/codex-hook-output-normalizer.d.ts",
@@ -208,6 +210,8 @@
     "core/codex-lb-circuit.js",
     "core/codex-lb/codex-lb-env.d.ts",
     "core/codex-lb/codex-lb-env.js",
+    "core/codex-lb/codex-lb-setup.d.ts",
+    "core/codex-lb/codex-lb-setup.js",
     "core/codex-model-guard.d.ts",
     "core/codex-model-guard.js",
     "core/commands/autoresearch-command.d.ts",
@@ -282,6 +286,8 @@
     "core/commands/wiki-command.js",
     "core/commands/wrongness-command.d.ts",
     "core/commands/wrongness-command.js",
+    "core/computer-use-live-evidence.d.ts",
+    "core/computer-use-live-evidence.js",
     "core/computer-use-status.d.ts",
     "core/computer-use-status.js",
     "core/context7-client.d.ts",

package/dist/cli/install-helpers.d.ts

@@ -1,3 +1,4 @@
+import { type CodexLbPersistenceSummary } from '../core/codex-lb/codex-lb-setup.js';
 type CodexLbStatusSnapshot = Awaited<ReturnType<typeof codexLbStatus>>;
 /** Install-time shim reconciliation; fields vary by `status`. */
 export type SksPostinstallShimResult = {
@@ -56,6 +57,10 @@ export type CodexLbAuthInstallResult = {
 export type ConfigureCodexLbResult = {
     ok?: boolean;
     status: string;
+    plan?: Record<string, unknown>;
+    applied_actions?: Array<Record<string, unknown>>;
+    drift?: string[];
+    persistence?: CodexLbPersistenceSummary;
     config_path?: string;
     env_path?: string;
     metadata_path?: string;

package/dist/cli/install-helpers.js

@@ -12,6 +12,7 @@ import { codexLaunchCommand, platformTmuxInstallHint, tmuxReadiness, tmuxReadine
 import { reconcileCodexAppUpgradeProcesses } from '../core/codex-app.js';
 import { recordCodexLbHealthEvent } from '../core/codex-lb-circuit.js';
 import { loadCodexLbEnv, writeCodexLbKeychain, codexLbMetadataPath } from '../core/codex-lb/codex-lb-env.js';
+import { buildCodexLbSetupPlan, codexLbPersistenceSummary, installCodexLbShellProfileSnippet, selectedCodexLbPersistenceModes } from '../core/codex-lb/codex-lb-setup.js';
 const DEFAULT_CODEX_APP_PLUGINS = [
     ['browser', 'openai-bundled'],
     ['chrome', 'openai-bundled'],
@@ -307,8 +308,33 @@ export async function configureCodexLb(opts = {}) {
     const rawHost = String(opts.host || opts.baseUrl || '');
     const baseUrl = normalizeCodexLbBaseUrl(rawHost);
     const apiKey = String(opts.apiKey || '').trim();
+    const useDefaultProvider = opts.useDefaultProvider !== false;
+    const writeEnvFile = opts.writeEnvFile !== false;
+    const storeKeychain = opts.storeKeychain === true || opts.keychain === true;
+    const syncLaunchctl = opts.syncLaunchctl !== false && opts.syncLaunchEnv !== false;
+    const shellProfile = opts.shellProfile || 'skip';
+    const setupAnswers = {
+        host_or_base_url: rawHost,
+        api_key_source: opts.apiKeySource || 'cli_option',
+        use_as_default_provider: useDefaultProvider,
+        write_env_file: writeEnvFile,
+        store_keychain: storeKeychain,
+        sync_launchctl: syncLaunchctl,
+        install_shell_profile: shellProfile,
+        run_health_check: opts.runHealth === true,
+        allow_insecure_localhost: opts.allowInsecureHttp === true || opts.allowInsecureLocalhost === true
+    };
+    const selectedPersistenceModes = selectedCodexLbPersistenceModes(setupAnswers);
+    const plan = buildCodexLbSetupPlan(setupAnswers, {
+        home,
+        configPath,
+        envPath,
+        metadataPath: opts.metadataPath || codexLbMetadataPath(home)
+    });
     if (!baseUrl)
         return { ok: false, status: 'missing_host_or_base_url', config_path: configPath, env_path: envPath };
+    if (plan.blockers.length)
+        return { ok: false, status: 'plan_blocked', plan: plan, drift: plan.blockers, config_path: configPath, env_path: envPath };
     if (/[\u0000-\u001f\u007f\s]/.test(rawHost.trim()))
         return { ok: false, status: 'invalid_host_or_base_url', config_path: configPath, env_path: envPath, error: 'host_or_base_url_contains_whitespace_or_control_character' };
     if (!apiKey)
@@ -316,12 +342,22 @@ export async function configureCodexLb(opts = {}) {
     const insecureLocalWarning = /^http:\/\//i.test(baseUrl) && !/^http:\/\/(?:localhost|127\.0\.0\.1|\[::1\])(?::|\/|$)/i.test(baseUrl) && !opts.allowInsecureHttp
         ? ['codex-lb base URL uses http outside localhost; prefer https or pass an explicit allow flag in the calling surface.']
         : [];
+    const beforeState = await captureCodexLbSetupWriteState({ home, configPath, envPath, shellProfile });
+    const appliedActions = [];
     await ensureDir(path.dirname(configPath));
     const current = await readText(configPath, '');
-    const next = normalizeCodexFastModeUiConfig(upsertCodexLbConfig(current, baseUrl));
+    const next = normalizeCodexFastModeUiConfig(upsertCodexLbConfig(current, baseUrl, useDefaultProvider));
     await writeTextAtomic(configPath, next);
-    await writeTextAtomic(envPath, `export CODEX_LB_BASE_URL=${shellSingleQuote(baseUrl)}\nexport CODEX_LB_API_KEY=${shellSingleQuote(apiKey)}\n`);
-    await fsp.chmod(envPath, 0o600).catch(() => { });
+    appliedActions.push({ type: 'write_config_provider', target: configPath, ok: true });
+    if (useDefaultProvider)
+        appliedActions.push({ type: 'select_default_provider', target: configPath, ok: true });
+    if (writeEnvFile) {
+        await writeTextAtomic(envPath, `export CODEX_LB_BASE_URL=${shellSingleQuote(baseUrl)}\nexport CODEX_LB_API_KEY=${shellSingleQuote(apiKey)}\n`);
+        await fsp.chmod(envPath, 0o600).catch(() => { });
+        appliedActions.push({ type: 'write_env_file', target: envPath, ok: true });
+    }
+    process.env.CODEX_LB_BASE_URL = baseUrl;
+    process.env.CODEX_LB_API_KEY = apiKey;
     const keyFingerprint = await sha256Text(apiKey);
     const metadataPath = opts.metadataPath || codexLbMetadataPath(home);
     await writeTextAtomic(metadataPath, `${JSON.stringify({
@@ -332,23 +368,67 @@ export async function configureCodexLb(opts = {}) {
         api_key: { redacted: true, sha256: keyFingerprint }
     }, null, 2)}\n`);
     await fsp.chmod(metadataPath, 0o600).catch(() => { });
-    const keychain = opts.keychain ? await writeCodexLbKeychain(apiKey, opts).catch((err) => ({ ok: false, status: 'keychain_store_failed', error: err.message })) : { ok: false, status: 'skipped' };
-    const codexEnvironment = await syncCodexLbProviderEnvironment({ env_path: envPath, base_url: baseUrl }, { ...opts, home });
+    appliedActions.push({ type: 'write_metadata', target: metadataPath, ok: true });
+    const keychain = storeKeychain ? await writeCodexLbKeychain(apiKey, opts).catch((err) => ({ ok: false, status: 'keychain_store_failed', error: err.message })) : { ok: false, status: 'skipped' };
+    if (storeKeychain)
+        appliedActions.push({ type: 'store_keychain', target: 'macOS Keychain service sks-codex-lb', ok: keychain.ok === true, status: keychain.status });
+    const codexEnvironment = await syncCodexLbProviderEnvironment({ env_path: envPath, base_url: baseUrl }, { ...opts, home, apiKey, baseUrl, syncLaunchEnv: syncLaunchctl });
+    if (syncLaunchctl)
+        appliedActions.push({ type: 'sync_launchctl', target: 'macOS launchctl user environment', ok: codexEnvironment.ok === true, status: codexEnvironment.status });
+    const shellProfileResult = await installCodexLbShellProfileSnippet({ home, envPath, shellProfile }).catch((err) => ({ ok: false, status: 'failed', files: [], error: err.message }));
+    if (shellProfile !== 'skip')
+        appliedActions.push({ type: 'install_shell_profile_snippet', target: shellProfileResult.files?.join(', ') || shellProfile, ok: shellProfileResult.ok === true, status: shellProfileResult.status });
     const codexLogin = await maybeSyncCodexLbSharedLogin(apiKey, { ...opts, home, force: true });
     const codexLb = await codexLbStatus({ ...opts, home, configPath, envPath });
     const authReconcile = await reconcileCodexLbAuthConflict({ ...opts, home, status: codexLb }).catch((err) => ({ status: 'failed', reason: 'exception', error: err.message }));
     const finalCodexLb = await codexLbStatus({ ...opts, home, configPath, envPath });
     const ok = Boolean(codexEnvironment.ok && codexLogin.ok);
+    const afterState = await captureCodexLbSetupWriteState({ home, configPath, envPath, shellProfile });
+    const drift = detectCodexLbSetupDrift({
+        useDefaultProvider,
+        writeEnvFile,
+        storeKeychain,
+        syncLaunchctl,
+        shellProfile,
+        selected: finalCodexLb.selected,
+        envFile: finalCodexLb.env_file,
+        keychain,
+        codexEnvironment,
+        shellProfileResult,
+        beforeState,
+        afterState
+    });
+    const appliedPersistenceModes = appliedCodexLbPersistenceModes({
+        writeEnvFile,
+        storeKeychain,
+        syncLaunchctl,
+        shellProfile,
+        envFile: finalCodexLb.env_file,
+        keychain,
+        codexEnvironment,
+        shellProfileResult,
+        apiKeySource: finalCodexLb.env_loader?.api_key?.source || null
+    });
+    const persistence = codexLbPersistenceSummary({
+        selectedModes: selectedPersistenceModes,
+        appliedModes: appliedPersistenceModes,
+        processOnly: appliedPersistenceModes.includes('process_only_ephemeral')
+    });
+    const warnings = [...insecureLocalWarning, ...persistence.warnings];
     return {
-        ok,
-        status: ok ? 'configured' : (codexEnvironment.status || codexLogin.status),
+        ok: ok && drift.length === 0,
+        status: ok && drift.length === 0 ? 'configured' : drift.length ? 'setup_choice_drift' : (codexEnvironment.status || codexLogin.status),
+        plan: plan,
+        applied_actions: appliedActions,
+        drift,
+        persistence,
         config_path: configPath,
         env_path: envPath,
         metadata_path: metadataPath,
         base_url: baseUrl,
         env_key: 'CODEX_LB_API_KEY',
         keychain,
-        warnings: insecureLocalWarning,
+        warnings,
         auth_reconcile: authReconcile,
         codex_lb: finalCodexLb,
         codex_environment: codexEnvironment,
@@ -1188,10 +1268,10 @@ async function syncCodexLbProviderEnvironment(status = {}, opts = {}) {
     const home = opts.home || process.env.HOME || os.homedir();
     const envPath = opts.envPath || status.env_path || codexLbEnvPath(home);
     const envText = await readText(envPath, '');
-    const apiKey = parseCodexLbEnvKey(envText);
+    const apiKey = String(opts.apiKey || '').trim() || parseCodexLbEnvKey(envText);
     if (!apiKey)
         return { ok: false, status: 'missing_env_key' };
-    const baseUrl = status.base_url || parseCodexLbEnvBaseUrl(envText);
+    const baseUrl = status.base_url || opts.baseUrl || parseCodexLbEnvBaseUrl(envText);
     process.env.CODEX_LB_API_KEY = apiKey;
     if (baseUrl)
         process.env.CODEX_LB_BASE_URL = baseUrl;
@@ -1258,8 +1338,10 @@ 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) {
-    let next = upsertTopLevelTomlString(text, 'model_provider', 'codex-lb');
+function upsertCodexLbConfig(text = '', baseUrl, selectDefault = true) {
+    let next = selectDefault
+        ? upsertTopLevelTomlString(text, 'model_provider', 'codex-lb')
+        : removeTopLevelTomlKeyIfValue(text, 'model_provider', 'codex-lb');
     const block = [
         '[model_providers.codex-lb]',
         'name = "OpenAI"',
@@ -1272,6 +1354,72 @@ function upsertCodexLbConfig(text = '', baseUrl) {
     next = upsertTomlTable(next, 'model_providers.codex-lb', block);
     return `${next.trim()}\n`;
 }
+function detectCodexLbSetupDrift(state = {}) {
+    const drift = [];
+    if (state.useDefaultProvider && state.selected !== true)
+        drift.push('default_provider_not_selected');
+    if (!state.useDefaultProvider && state.selected === true)
+        drift.push('default_provider_selected_despite_no_default_provider');
+    if (state.writeEnvFile && state.envFile !== true)
+        drift.push('env_file_not_written');
+    if (!state.writeEnvFile && state.beforeState && state.afterState && state.beforeState.envHash !== state.afterState.envHash)
+        drift.push('env_file_changed_despite_no_env_file');
+    if (!state.writeEnvFile && !state.beforeState && state.envFile === true)
+        drift.push('env_file_written_despite_no_env_file');
+    if (!state.storeKeychain && state.keychain?.status && state.keychain.status !== 'skipped')
+        drift.push('keychain_touched_despite_no_keychain');
+    if (!state.syncLaunchctl && state.codexEnvironment?.launch_environment?.status === 'synced')
+        drift.push('launchctl_synced_despite_no_launchctl');
+    if (state.shellProfile === 'skip' && state.shellProfileResult?.status === 'installed')
+        drift.push('shell_profile_written_despite_skip');
+    if (state.shellProfile === 'skip' && state.beforeState && state.afterState && state.beforeState.profileHash !== state.afterState.profileHash)
+        drift.push('shell_profile_changed_despite_skip');
+    return drift;
+}
+async function captureCodexLbSetupWriteState({ home, configPath, envPath, shellProfile } = {}) {
+    const profileFiles = profileFilesForDrift(home, shellProfile);
+    return {
+        configHash: await fileHashOrMissing(configPath),
+        envHash: await fileHashOrMissing(envPath),
+        profileHash: (await Promise.all(profileFiles.map((file) => fileHashOrMissing(file)))).join('|')
+    };
+}
+async function fileHashOrMissing(file) {
+    const text = await readText(file, null).catch(() => null);
+    return text === null ? 'missing' : await sha256Text(String(text));
+}
+function profileFilesForDrift(home, shellProfile) {
+    const targets = {
+        zsh: path.join(home, '.zshrc'),
+        bash: path.join(home, '.bashrc'),
+        fish: path.join(home, '.config', 'fish', 'config.fish')
+    };
+    if (shellProfile === 'zsh')
+        return [targets.zsh];
+    if (shellProfile === 'bash')
+        return [targets.bash];
+    if (shellProfile === 'fish')
+        return [targets.fish];
+    if (shellProfile === 'all')
+        return [targets.zsh, targets.bash, targets.fish];
+    return [targets.zsh, targets.bash, targets.fish];
+}
+function appliedCodexLbPersistenceModes(state = {}) {
+    const modes = [];
+    if (state.writeEnvFile && state.envFile === true)
+        modes.push('durable_env_file');
+    if (state.storeKeychain && state.keychain?.ok === true)
+        modes.push('durable_keychain');
+    if (state.syncLaunchctl && state.codexEnvironment?.launch_environment?.status === 'synced')
+        modes.push('durable_launchctl');
+    if (state.shellProfile !== 'skip' && state.shellProfileResult?.status === 'installed')
+        modes.push('shell_profile');
+    if (!modes.length && state.apiKeySource === 'process.env')
+        modes.push('process_only_ephemeral');
+    if (!modes.length)
+        modes.push('none');
+    return modes;
+}
 export async function ensureGlobalCodexFastModeDuringInstall(opts = {}) {
     if (process.env.SKS_SKIP_CODEX_FAST_MODE_REPAIR === '1')
         return { status: 'skipped', reason: 'SKS_SKIP_CODEX_FAST_MODE_REPAIR=1' };

package/dist/commands/codex-lb.js

@@ -6,6 +6,7 @@ import { flag, readOption } from '../cli/args.js';
 import { printJson } from '../cli/output.js';
 import { codexLbMetrics, readCodexLbCircuit, recordCodexLbHealthEvent, resetCodexLbCircuit, codexLbProofEvidence } from '../core/codex-lb-circuit.js';
 import { checkCodexLbResponseChain, codexLbStatus, configureCodexLb, formatCodexLbStatusText, releaseCodexLbAuthHold, repairCodexLbAuth, unselectCodexLbProvider } from '../cli/install-helpers.js';
+import { buildCodexLbSetupPlan, codexLbPersistenceSummary, renderCodexLbSetupPlan } from '../core/codex-lb/codex-lb-setup.js';
 export async function run(command, args = []) {
     const root = await projectRoot();
     const action = args[0] || 'status';
@@ -77,6 +78,17 @@ export async function run(command, args = []) {
     }
     if (action === 'setup' || action === 'reconfigure') {
         const options = await codexLbSetupOptions(args);
+        const plan = buildCodexLbSetupPlan({
+            host_or_base_url: options.host || '',
+            api_key_source: options.apiKeySource,
+            use_as_default_provider: options.useDefaultProvider,
+            write_env_file: options.writeEnvFile,
+            store_keychain: options.keychain,
+            sync_launchctl: options.syncLaunchctl,
+            install_shell_profile: options.shellProfile,
+            run_health_check: options.health,
+            allow_insecure_localhost: options.allowInsecureLocalhost
+        });
         if (!options.host || !options.apiKey) {
             const result = {
                 schema: 'sks.codex-lb-setup.v1',
@@ -98,13 +110,84 @@ export async function run(command, args = []) {
             process.exitCode = 1;
             return;
         }
-        const result = await configureCodexLb({ host: options.host, apiKey: options.apiKey, keychain: options.keychain });
+        if (flag(args, '--plan')) {
+            const result = { schema: 'sks.codex-lb-setup-plan-result.v1', ok: plan.blockers.length === 0, plan, writes: false, expected_actions: plan.expected_actions, persistence: plan.persistence };
+            if (flag(args, '--json'))
+                return printJson(result);
+            process.stdout.write(renderCodexLbSetupPlan(plan));
+            if (!result.ok)
+                process.exitCode = 1;
+            return;
+        }
+        const processOnly = plan.persistence.effective_mode === 'process_only_ephemeral';
+        if (options.interactive && !options.yes) {
+            process.stdout.write(renderCodexLbSetupPlan(plan));
+            const confirm = (await ask('Apply this codex-lb setup plan? [y/N] ')).trim();
+            if (!/^(y|yes|예|네|응)$/i.test(confirm)) {
+                const result = { schema: 'sks.codex-lb-setup.v1', ok: false, status: 'cancelled', plan, applied_actions: [] };
+                if (flag(args, '--json'))
+                    return printJson(result);
+                console.log('codex-lb setup cancelled.');
+                process.exitCode = 1;
+                return;
+            }
+            if (processOnly) {
+                const confirmProcessOnly = (await ask('This setup keeps credentials only in the current process. Type process-only to continue: ')).trim();
+                if (confirmProcessOnly !== 'process-only') {
+                    const result = { schema: 'sks.codex-lb-setup.v1', ok: false, status: 'process_only_cancelled', plan, applied_actions: [], persistence: plan.persistence };
+                    if (flag(args, '--json')) {
+                        printJson(result);
+                        process.exitCode = 1;
+                        return;
+                    }
+                    console.log('codex-lb setup cancelled: process-only ephemeral setup was not confirmed.');
+                    process.exitCode = 1;
+                    return;
+                }
+            }
+        }
+        else if (processOnly && !options.yes) {
+            const result = {
+                schema: 'sks.codex-lb-setup.v1',
+                ok: false,
+                status: 'process_only_requires_yes',
+                plan,
+                applied_actions: [],
+                persistence: plan.persistence,
+                guidance: ['Pass --yes to acknowledge process_only_ephemeral setup, or enable --write-env-file, --keychain, --launchctl, or --shell-profile.']
+            };
+            if (flag(args, '--json')) {
+                printJson(result);
+                process.exitCode = 1;
+                return;
+            }
+            console.error('codex-lb setup would be process-only ephemeral. Pass --yes to acknowledge, or enable a durable persistence mode.');
+            process.exitCode = 1;
+            return;
+        }
+        const result = await configureCodexLb({
+            host: options.host,
+            apiKey: options.apiKey,
+            keychain: options.keychain,
+            storeKeychain: options.keychain,
+            useDefaultProvider: options.useDefaultProvider,
+            writeEnvFile: options.writeEnvFile,
+            syncLaunchctl: options.syncLaunchctl,
+            shellProfile: options.shellProfile,
+            runHealth: options.health,
+            apiKeySource: options.apiKeySource,
+            allowInsecureHttp: options.allowInsecureLocalhost
+        });
         const shaped = { schema: 'sks.codex-lb-setup.v1', ...result, api_key: { present: Boolean(options.apiKey), redacted: true }, env_file_chmod: '0600' };
+        if (options.health)
+            shaped.applied_actions = [...(shaped.applied_actions || []), { type: 'run_health_check', target: 'codex-lb response chain', ok: true }];
         if (options.health)
             shaped.chain_health = result.ok ? await checkCodexLbResponseChain(result, { force: true, root }) : null;
         if (flag(args, '--json'))
             return printJson(shaped);
         console.log(`codex-lb configured: ${result.base_url || result.status}`);
+        if (shaped.persistence?.warning)
+            console.log(`warning: ${shaped.persistence.warning}`);
         if (!result.ok)
             process.exitCode = 1;
         return;
@@ -143,6 +226,18 @@ export async function run(command, args = []) {
     process.exitCode = 1;
 }
 function shapeCodexLbStatus(status = {}) {
+    const mode = status.env_loader?.api_key?.source === 'env-file'
+        ? 'durable_env_file'
+        : status.env_loader?.api_key?.source === 'keychain'
+            ? 'durable_keychain'
+            : status.env_loader?.api_key?.source === 'process.env'
+                ? 'process_only_ephemeral'
+                : 'none';
+    const persistence = codexLbPersistenceSummary({
+        selectedModes: mode === 'none' ? [] : [mode],
+        appliedModes: mode === 'none' ? ['none'] : [mode],
+        processOnly: mode === 'process_only_ephemeral'
+    });
     return {
         schema: 'sks.codex-lb-status.v1',
         ...status,
@@ -154,6 +249,7 @@ function shapeCodexLbStatus(status = {}) {
             source: status.env_loader?.api_key?.source || null,
             redacted: true
         },
+        persistence,
         env_loader: status.env_loader || null,
         env_auto_load: Boolean(status.env_file && status.env_key_configured),
         guidance: status.ok ? [] : [
@@ -167,22 +263,58 @@ async function codexLbSetupOptions(args = []) {
     const baseUrl = readOption(args, '--base-url', null);
     let host = baseUrl || readOption(args, '--host', readOption(args, '--domain', null));
     let apiKey = readOption(args, '--api-key', readOption(args, '--key', null));
+    let apiKeySource = apiKey ? 'cli_option' : 'hidden_prompt';
     let keychain = flag(args, '--keychain');
     if (flag(args, '--api-key-stdin'))
         apiKey = (await readStdin()).trim();
-    let health = flag(args, '--health') || flag(args, '--check');
+    if (flag(args, '--api-key-stdin'))
+        apiKeySource = 'stdin';
+    let health = (flag(args, '--health') || flag(args, '--check')) && !flag(args, '--no-health');
+    let useDefaultProvider = flag(args, '--no-default-provider') ? false : true;
+    if (flag(args, '--use-default-provider'))
+        useDefaultProvider = true;
+    let writeEnvFile = flag(args, '--no-env-file') ? false : true;
+    if (flag(args, '--write-env-file'))
+        writeEnvFile = true;
+    if (flag(args, '--no-keychain'))
+        keychain = false;
+    let syncLaunchctl = flag(args, '--no-launchctl') ? false : true;
+    if (flag(args, '--launchctl'))
+        syncLaunchctl = true;
+    const shellProfile = normalizeShellProfile(readOption(args, '--shell-profile', 'skip'));
+    const allowInsecureLocalhost = flag(args, '--allow-insecure-localhost') || flag(args, '--allow-insecure-http');
+    const interactive = (!host || !apiKey || canAskInteractive(args)) && canAskInteractive(args);
     if ((!host || !apiKey) && canAskInteractive(args)) {
         console.log('SKS codex-lb setup\n');
         host ||= (await ask('1. codex-lb domain or base URL?\n   Example: lb.example.com or https://lb.example.com/backend-api/codex\n> ')).trim();
         apiKey ||= (await askHidden('2. API key?\n   Input hidden. Value will be stored securely and never printed.\n> ')).trim();
-        await ask('3. Use this codex-lb as default for Codex launches? [Y/n] ');
-        await ask('4. Write shell env loader to ~/.codex/sks-codex-lb.env? [Y/n] ');
+        apiKeySource = 'hidden_prompt';
+        useDefaultProvider = parseYesNo(await ask('3. Use this codex-lb as default for Codex launches? [Y/n] '), true);
+        writeEnvFile = parseYesNo(await ask('4. Write shell env loader to ~/.codex/sks-codex-lb.env? [Y/n] '), true);
         const storeKeychain = (await ask('5. Store the key in macOS Keychain when available? [Y/n] ')).trim();
         keychain = !/^(n|no|아니|아니요|ㄴ)$/i.test(storeKeychain || 'y');
-        const runHealth = (await ask('6. Run health check now? [Y/n] ')).trim();
+        syncLaunchctl = parseYesNo(await ask('6. Sync macOS launchctl environment when available? [Y/n] '), true);
+        const profile = (await ask('7. Install shell profile snippet? [zsh/bash/fish/all/skip] ')).trim();
+        const interactiveShellProfile = normalizeShellProfile(profile || 'skip');
+        const runHealth = (await ask('8. Run health check now? [Y/n] ')).trim();
         health = !/^(n|no|아니|아니요|ㄴ)$/i.test(runHealth || 'y');
+        return { host, apiKey, health, keychain, useDefaultProvider, writeEnvFile, syncLaunchctl, shellProfile: interactiveShellProfile, allowInsecureLocalhost, apiKeySource, interactive: true, yes: flag(args, '--yes') };
     }
-    return { host, apiKey, health, keychain };
+    return { host, apiKey, health, keychain, useDefaultProvider, writeEnvFile, syncLaunchctl, shellProfile, allowInsecureLocalhost, apiKeySource, interactive, yes: flag(args, '--yes') };
+}
+function normalizeShellProfile(value) {
+    const raw = String(value || 'skip').toLowerCase();
+    return raw === 'zsh' || raw === 'bash' || raw === 'fish' || raw === 'all' ? raw : 'skip';
+}
+function parseYesNo(value, fallback) {
+    const raw = String(value || '').trim();
+    if (!raw)
+        return fallback;
+    if (/^(y|yes|예|네|응)$/i.test(raw))
+        return true;
+    if (/^(n|no|아니|아니요|ㄴ)$/i.test(raw))
+        return false;
+    return fallback;
 }
 function canAskInteractive(args = []) {
     return !flag(args, '--json') && !flag(args, '--yes') && Boolean(input.isTTY && output.isTTY && process.env.CI !== 'true');

package/dist/commands/wiki.d.ts

@@ -15,7 +15,7 @@ export declare function run(_command: any, args?: any): Promise<void | {
     };
     active_records: {
         id: string;
-        kind: "incorrect_claim" | "overconfident_claim" | "stale_evidence" | "missing_evidence" | "test_failure" | "route_misclassification" | "scout_error" | "visual_anchor_error" | "image_bbox_error" | "db_safety_false_positive" | "db_safety_false_negative" | "hook_policy_mismatch" | "hook_semantic_mismatch" | "codex_lb_health_misread" | "codex_lb_missing_env_raw_message" | "computer_use_policy_misclassification" | "mock_real_confusion" | "user_intent_misread" | "artifact_schema_error" | "trust_status_overclaim";
+        kind: "incorrect_claim" | "overconfident_claim" | "stale_evidence" | "missing_evidence" | "test_failure" | "route_misclassification" | "scout_error" | "visual_anchor_error" | "image_bbox_error" | "db_safety_false_positive" | "db_safety_false_negative" | "hook_policy_mismatch" | "hook_semantic_mismatch" | "hook_strict_subset_misclassified" | "codex_lb_health_misread" | "codex_lb_missing_env_raw_message" | "codex_lb_setup_choice_drift" | "codex_lb_env_persistence_failure" | "computer_use_policy_misclassification" | "computer_use_live_smoke_mismatch" | "computer_use_external_block_overclaimed" | "mock_real_confusion" | "user_intent_misread" | "artifact_schema_error" | "trust_status_overclaim";
         severity: "high" | "low" | "medium" | "critical";
         route: string | null;
         claim: string;