sneakoscope 1.0.4 → 1.0.6

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.4** targets OpenAI Codex CLI `rust-v0.131.0`: hook outputs are validated against vendored upstream schemas, `sks codex-lb setup` is a guided/redacted setup path, and macOS Computer Use is treated as a Codex App visual evidence capability independent from MAD-SKS.
+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.
 
 SKS **1.0.3** adds git-collaboration hygiene for shared TriWiki memory: `sks git ...`, tracked shared shards under `.sneakoscope/wiki/**`, runtime-only ignores, shared wrongness publish/sync, and Codex App hook trust-state generation for current hook trust syntax.
 
@@ -19,6 +23,51 @@ SKS does not try to clone every other harness. It focuses on one thing: making C
 ![Sneakoscope Codex architecture and pipeline](https://raw.githubusercontent.com/mandarange/Sneakoscope-Codex/dev/docs/assets/sneakoscope-architecture-pipeline.jpg)
 
 
+## 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
+
+SKS 1.0.5 treats Codex hook semantic compatibility as stricter than schema compatibility. `sks hooks warning-check --json` and `npm run hooks:semantic-check` fail if an output uses `permissionDecision:"ask"`, PreToolUse `allow` without `updatedInput`, Stop `continue:false`, `stopReason`, `suppressOutput`, snake_case keys, unknown fields, or legacy top-level hook decisions.
+
+codex-lb setup now has a durable setup/repair path:
+
+```bash
+sks codex-lb setup --host lb.example.com --api-key-stdin --yes --json
+sks codex-lb status --json
+sks codex-lb doctor --deep --json
+npm run codex-lb:missing-env-regression
+```
+
+The API key is written only to redacted status surfaces. The env file is `~/.codex/sks-codex-lb.env`, metadata is `~/.codex/sks-codex-lb.json`, and reports expose only a redacted presence state plus a fingerprint. Raw `CODEX_LB_API_KEY` missing-env errors are release failures.
+
+Computer Use is a Codex App/macOS capability, not a MAD-SKS or DB permission. Visual routes use:
+
+```bash
+sks computer-use status --json
+sks computer-use require --route '$QA-LOOP' --json
+npm run computer-use:visual-route-fixture
+```
+
+If Codex App or macOS blocks the capability, SKS records `external_capability_blocked`, `codex_app_missing`, `macos_permission_missing`, or the closest structured status and does not fabricate UI evidence.
+
 ## 1.0.4 Codex CLI Compatibility
 
 SKS 1.0.4 targets OpenAI Codex CLI `rust-v0.131.0`. Hook outputs are validated against vendored upstream schemas, so SKS fails release checks if it emits deprecated hook shapes or unknown fields. `sks codex-lb setup` now guides users through domain/base URL and API key setup, stores secrets securely, and prevents raw `CODEX_LB_API_KEY` missing messages. On macOS, Computer Use is treated as a first-class Codex App visual evidence capability and is never blocked by MAD-SKS or a generic SKS safety policy.

package/crates/sks-core/Cargo.lock

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

package/crates/sks-core/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "sks-core"
-version = "1.0.4"
+version = "1.0.6"
 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.4"),
+        Some("--version") => println!("sks-rs 1.0.6"),
         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.4';
+const FAST_PACKAGE_VERSION = '1.0.6';
 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.4",
+  "version": "1.0.6",
   "typescript": true,
   "mjs_runtime_files": 0,
   "files": [
@@ -188,10 +188,16 @@
     "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",
     "core/codex-compat/codex-hook-output-normalizer.js",
     "core/codex-compat/codex-hook-schema.d.ts",
     "core/codex-compat/codex-hook-schema.js",
+    "core/codex-compat/codex-hook-semantic-validator.d.ts",
+    "core/codex-compat/codex-hook-semantic-validator.js",
     "core/codex-compat/codex-hook-warning-detector.d.ts",
     "core/codex-compat/codex-hook-warning-detector.js",
     "core/codex-compat/codex-schema-snapshot.d.ts",
@@ -202,6 +208,10 @@
     "core/codex-compat/codex-version.js",
     "core/codex-lb-circuit.d.ts",
     "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",

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

@@ -56,10 +56,16 @@ export type CodexLbAuthInstallResult = {
 export type ConfigureCodexLbResult = {
     ok?: boolean;
     status: string;
+    plan?: Record<string, unknown>;
+    applied_actions?: Array<Record<string, unknown>>;
+    drift?: string[];
     config_path?: string;
     env_path?: string;
+    metadata_path?: string;
     base_url?: string;
     env_key?: string;
+    keychain?: Record<string, unknown>;
+    warnings?: string[];
     auth_reconcile?: CodexLbAuthReconcileResult;
     codex_lb?: CodexLbStatusSnapshot;
     codex_environment?: CodexLbEnvSyncResult;
@@ -97,6 +103,24 @@ export declare function codexLbStatus(opts?: any): Promise<{
     env_file: boolean;
     env_key_configured: boolean;
     env_base_url_configured: boolean;
+    env_loader: {
+        configured: boolean;
+        missing: string[];
+        source: import("../core/codex-lb/codex-lb-env.js").CodexLbEnvSource;
+        source_priority: import("../core/codex-lb/codex-lb-env.js").CodexLbEnvSource[];
+        api_key: {
+            present: boolean;
+            source: import("../core/codex-lb/codex-lb-env.js").CodexLbEnvSource | null;
+            redacted: true;
+            fingerprint: string | null;
+        };
+        keychain: {
+            checked: boolean;
+            available: boolean;
+            status: string;
+        };
+        env_paths: string[];
+    };
     base_url: string | null;
     auth_path: any;
     auth_mode: string;
@@ -185,6 +209,24 @@ export declare function maybePromptCodexLbSetupForLaunch(args?: any, opts?: any)
     env_file: boolean;
     env_key_configured: boolean;
     env_base_url_configured: boolean;
+    env_loader: {
+        configured: boolean;
+        missing: string[];
+        source: import("../core/codex-lb/codex-lb-env.js").CodexLbEnvSource;
+        source_priority: import("../core/codex-lb/codex-lb-env.js").CodexLbEnvSource[];
+        api_key: {
+            present: boolean;
+            source: import("../core/codex-lb/codex-lb-env.js").CodexLbEnvSource | null;
+            redacted: true;
+            fingerprint: string | null;
+        };
+        keychain: {
+            checked: boolean;
+            available: boolean;
+            status: string;
+        };
+        env_paths: string[];
+    };
     base_url: string | null;
     auth_path: any;
     auth_mode: string;
@@ -205,6 +247,24 @@ export declare function maybePromptCodexLbSetupForLaunch(args?: any, opts?: any)
     env_file: boolean;
     env_key_configured: boolean;
     env_base_url_configured: boolean;
+    env_loader: {
+        configured: boolean;
+        missing: string[];
+        source: import("../core/codex-lb/codex-lb-env.js").CodexLbEnvSource;
+        source_priority: import("../core/codex-lb/codex-lb-env.js").CodexLbEnvSource[];
+        api_key: {
+            present: boolean;
+            source: import("../core/codex-lb/codex-lb-env.js").CodexLbEnvSource | null;
+            redacted: true;
+            fingerprint: string | null;
+        };
+        keychain: {
+            checked: boolean;
+            available: boolean;
+            status: string;
+        };
+        env_paths: string[];
+    };
     base_url: string | null;
     auth_path: any;
     auth_mode: string;

package/dist/cli/install-helpers.js

@@ -11,6 +11,8 @@ import { context7ConfigToml, DOLLAR_SKILL_NAMES, GETDESIGN_REFERENCE, hasContext
 import { codexLaunchCommand, platformTmuxInstallHint, tmuxReadiness, tmuxReadinessCatchFallback } from '../core/tmux-ui.js';
 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, installCodexLbShellProfileSnippet } from '../core/codex-lb/codex-lb-setup.js';
 const DEFAULT_CODEX_APP_PLUGINS = [
     ['browser', 'openai-bundled'],
     ['chrome', 'openai-bundled'],
@@ -293,7 +295,7 @@ async function restorePostinstallCodexLbConfigSnapshot(snapshot) {
 export function normalizeCodexLbBaseUrl(input = '') {
     let host = String(input || '').trim();
     if (!host)
-        host = 'http://127.0.0.1:2455';
+        return '';
     if (!/^[a-z][a-z0-9+.-]*:\/\//i.test(host))
         host = `https://${host}`;
     host = host.replace(/\/+$/, '');
@@ -303,29 +305,107 @@ export async function configureCodexLb(opts = {}) {
     const home = opts.home || process.env.HOME || os.homedir();
     const configPath = opts.configPath || codexLbConfigPath(home);
     const envPath = opts.envPath || codexLbEnvPath(home);
-    const baseUrl = normalizeCodexLbBaseUrl(opts.host || opts.baseUrl);
+    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 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)
         return { ok: false, status: 'missing_api_key', config_path: configPath, env_path: envPath };
+    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 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(() => { });
-    const codexEnvironment = await syncCodexLbProviderEnvironment({ env_path: envPath, base_url: baseUrl }, { ...opts, home });
+    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({
+        schema: 'sks.codex-lb-metadata.v1',
+        base_url: baseUrl,
+        updated_at: new Date().toISOString(),
+        source: opts.source || 'setup',
+        api_key: { redacted: true, sha256: keyFingerprint }
+    }, null, 2)}\n`);
+    await fsp.chmod(metadataPath, 0o600).catch(() => { });
+    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 drift = detectCodexLbSetupDrift({
+        useDefaultProvider,
+        writeEnvFile,
+        storeKeychain,
+        syncLaunchctl,
+        shellProfile,
+        selected: finalCodexLb.selected,
+        envFile: finalCodexLb.env_file,
+        keychain,
+        codexEnvironment,
+        shellProfileResult
+    });
     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,
         config_path: configPath,
         env_path: envPath,
+        metadata_path: metadataPath,
         base_url: baseUrl,
         env_key: 'CODEX_LB_API_KEY',
+        keychain,
+        warnings: insecureLocalWarning,
         auth_reconcile: authReconcile,
         codex_lb: finalCodexLb,
         codex_environment: codexEnvironment,
@@ -340,13 +420,14 @@ export async function codexLbStatus(opts = {}) {
     const config = await readText(configPath, '');
     const envExists = await exists(envPath);
     const envText = envExists ? await readText(envPath, '') : '';
+    const envLoad = await loadCodexLbEnv({ ...opts, home, envPath });
     const authPath = opts.authPath || codexAuthPath(home);
     const authText = await readText(authPath, '');
     const authMode = codexAuthModeSummary(authText);
-    const envKeyConfigured = Boolean(parseCodexLbEnvKey(envText));
+    const envKeyConfigured = Boolean(envLoad.api_key.present);
     const providerConfigured = /\[model_providers\.codex-lb\]/.test(config);
     const selected = hasTopLevelCodexLbSelected(config);
-    const baseUrl = codexLbProviderBaseUrl(config) || parseCodexLbEnvBaseUrl(envText) || null;
+    const baseUrl = codexLbProviderBaseUrl(config) || envLoad.base_url || null;
     const providerRequiresOpenAiAuth = codexLbProviderRequiresOpenAiAuth(config);
     return {
         ok: providerConfigured && envKeyConfigured && Boolean(baseUrl) && providerRequiresOpenAiAuth,
@@ -357,7 +438,16 @@ export async function codexLbStatus(opts = {}) {
         selected,
         env_file: envExists,
         env_key_configured: envKeyConfigured,
-        env_base_url_configured: Boolean(parseCodexLbEnvBaseUrl(envText)),
+        env_base_url_configured: Boolean(envLoad.base_url),
+        env_loader: {
+            configured: envLoad.configured,
+            missing: envLoad.missing,
+            source: envLoad.source,
+            source_priority: envLoad.source_priority,
+            api_key: envLoad.api_key,
+            keychain: envLoad.keychain,
+            env_paths: envLoad.env_paths
+        },
         base_url: baseUrl,
         auth_path: authPath,
         auth_mode: authMode.mode,
@@ -1155,10 +1245,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;
@@ -1225,8 +1315,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"',
@@ -1239,6 +1331,24 @@ 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.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');
+    return drift;
+}
 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' };
@@ -1482,6 +1592,10 @@ function redactSecretText(text = '', secrets = []) {
     }
     return out;
 }
+async function sha256Text(value = '') {
+    const { createHash } = await import('node:crypto');
+    return createHash('sha256').update(String(value || '')).digest('hex');
+}
 function escapeRegExp(value) {
     return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }

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, renderCodexLbSetupPlan } from '../core/codex-lb/codex-lb-setup.js';
 export async function run(command, args = []) {
     const root = await projectRoot();
     const action = args[0] || 'status';
@@ -39,7 +40,8 @@ export async function run(command, args = []) {
     }
     if (action === 'health' || action === 'verify-chain' || action === 'chain') {
         const status = await codexLbStatus();
-        const result = status.ok ? await checkCodexLbResponseChain(status, { force: true, root }) : { ok: false, status: 'not_configured', codex_lb: status };
+        const blocker = !status.env_key_configured ? 'missing_env_key' : !status.base_url ? 'missing_base_url' : 'not_configured';
+        const result = status.ok ? await checkCodexLbResponseChain(status, { force: true, root }) : { ok: false, status: blocker, codex_lb: status };
         if (flag(args, '--json'))
             return printJson(result);
         console.log(`codex-lb response chain: ${result.ok ? 'ok' : `failed (${result.status})`}`);
@@ -76,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',
@@ -97,8 +110,43 @@ export async function run(command, args = []) {
             process.exitCode = 1;
             return;
         }
-        const result = await configureCodexLb({ host: options.host, apiKey: options.apiKey });
+        if (flag(args, '--plan')) {
+            const result = { schema: 'sks.codex-lb-setup-plan-result.v1', ok: plan.blockers.length === 0, plan, writes: false };
+            if (flag(args, '--json'))
+                return printJson(result);
+            process.stdout.write(renderCodexLbSetupPlan(plan));
+            if (!result.ok)
+                process.exitCode = 1;
+            return;
+        }
+        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;
+            }
+        }
+        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'))
@@ -147,11 +195,13 @@ function shapeCodexLbStatus(status = {}) {
         ...status,
         configured: Boolean(status.ok),
         setup_needed: !status.ok,
+        repair_available: !status.ok,
         api_key: {
             present: Boolean(status.env_key_configured),
-            source: status.env_key_configured ? 'env-file' : null,
+            source: status.env_loader?.api_key?.source || null,
             redacted: true
         },
+        env_loader: status.env_loader || null,
         env_auto_load: Boolean(status.env_file && status.env_key_configured),
         guidance: status.ok ? [] : [
             'codex-lb API key is not configured.',
@@ -164,19 +214,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] ');
-        const runHealth = (await ask('5. Run health check now? [Y/n] ')).trim();
+        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');
+        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 };
+    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" | "codex_lb_health_misread" | "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;