sneakoscope 1.21.4 → 1.21.5

package/README.md

@@ -16,7 +16,7 @@ Set up this agent project with Sneakoscope Codex. Use [[mandarange/Sneakoscope-C
 
 ## Current Release
 
-SKS **1.21.4** makes Fast mode state and Naruto clone activity directly visible in SKS Zellij lanes. The lane renderer now resolves the project-local `sks fast-mode on|off` preference even before worker scheduler artifacts arrive, and Naruto launches the right-side Zellij lane stack before clone scheduling starts so each clone slot can show live activity. Naruto's host-capacity model also no longer collapses `codex-exec` concurrency to one slot on capable Macs just because `freemem` is low; use `--concurrency` / `--target-active-slots` or `SKS_NARUTO_MAX_CONCURRENCY` for explicit operator control. SKS-launched interactive Codex panes also use `--no-alt-screen` by default so Mac trackpad/wheel gestures scroll the terminal conversation history instead of the prompt textarea/history; set `SKS_ZELLIJ_CODEX_ALT_SCREEN=1` before launch to opt back into alternate-screen mode. It carries forward the 1.21.3 Zellij clipboard, visual lane count, direct-publish stamp repair, and Codex Fast mode repair fixes.
+SKS **1.21.5** restores Codex App compatibility for Codex CLI 0.135-era routing and readiness checks. User prompts that mix frustration/question marks with explicit implementation or release work now route to `$Team` instead of `$Answer`, bare `context7 mcp` wording no longer falls into the `$DB` route, and Codex App Git Actions readiness now trusts the `codex remote-control` command/version capability instead of the removed `remote_control` feature flag. Active-route follow-up prompts now re-evaluate substantive analysis, research, and code work for fresh Team/Research-style native sessions instead of collapsing into the previous single active context; plain "keep going" continuations still resume the current route, and commit-only prompts stay lightweight. `sks --mad` now starts a same-mission native agent swarm before opening the cockpit lanes, `sks-fast-high` no longer forces `workspace-write` over the Codex App Full Access selector, and `$Goal` official-mode detection also reads `codex features list`. This keeps Commit, Push, Commit and Push, PR, MAD cockpit, Goal bridge, and repeated Team-route hook checks green on modern Codex when the corresponding Codex capabilities are present. It carries forward the 1.21.4 Zellij lane, Naruto, and terminal scrollback improvements.
 
 SKS **1.20.4** is a targeted `sks --mad` / codex-lb Zellij usability patch: when a background MAD Zellij session launches successfully, SKS now prints the exact `Attach with: ZELLIJ_SOCKET_DIR=... zellij attach ...` command so operators can enter the fresh session without manually reconstructing the socket namespace.
 
@@ -89,6 +89,32 @@ npm run release:readiness
 
 Detailed release history lives in [CHANGELOG.md](CHANGELOG.md); every version-facing change should be recorded there before release. Current release gate status lives in [docs/release-readiness.md](docs/release-readiness.md).
 
+## Parallelism, UX, And Integrations
+
+- **Extreme parallel fan-out (`$Naruto` / native agents).** Each clone is a separate CLI worker that spends almost all of its wall-clock awaiting the Codex API, so live concurrency scales by **memory and the provider rate limit, not CPU cores** — a capable host can run up to 100 workers in parallel. The 429/rate-limit backoff is handled by the centralized responses retry policy. Tune it with `SKS_NARUTO_MAX_CONCURRENCY` (hard cap, 1–100), `SKS_NARUTO_GB_PER_WORKER` (memory budget per worker), and `SKS_NARUTO_MIN_CONCURRENCY` (low-free-memory floor).
+
+  ```bash
+  sks naruto run "refactor the data layer" --clones 100 --json
+  SKS_NARUTO_MAX_CONCURRENCY=48 sks naruto run "sweep the test suite" --clones 48
+  ```
+
+- **Zellij trackpad scroll.** SKS-launched Zellij sessions enable `mouse_mode` so the trackpad wheel scrolls the pane under the cursor (the conversation/transcript) instead of the focused prompt input. Copy still works via `copy_command=pbcopy` + `copy_on_select`; set `SKS_ZELLIJ_MOUSE_MODE=0` to opt out.
+
+- **Live MAD / Naruto cockpit lanes.** `sks --mad` starts a same-mission native agent swarm and opens the right-pane cockpit against that ledger, so fan-out work shows up live instead of a permanent "Workers idle". Tune MAD fan-out with `--mad-agents`, `--mad-swarm-work-items`, and `--mad-swarm-backend`; use `--no-mad-swarm` only when you intentionally want the old UI-only launch. Each Zellij lane now has per-slot SKS state, a nonblocking JSONL command bus, dynamic pane-id reconciliation from `zellij action list-panes --json --all`, and `nice`/dispatch-throttle metadata so later lane coordination does not fall back to a single synthetic pane. If a lane's own mission ledger is idle, the renderer can still mirror the most-recent active agent mission; disable that follow behavior with `SKS_LANE_FOLLOW_ACTIVE_MISSION=0`.
+
+- **Image generation under codex-lb.** `gpt-image-2` routes through the same Codex `/responses` backend the load balancer already proxies, so `$imagegen` works when you are authenticated only through codex-lb (no direct `OPENAI_API_KEY`). The official Codex App `$imagegen` surface stays primary; the codex-lb/OpenAI API path is the fallback. Opt out with `SKS_IMAGEGEN_ALLOW_CODEX_LB_API_FALLBACK=0`.
+
+- **xAI / Grok search.** Wire xAI Live Search into source intelligence as an MCP provider:
+
+  ```bash
+  sks xai check
+  sks xai setup --scope project --command "npx" --arg "-y" --arg "<your-grok-search-mcp>"
+  export XAI_API_KEY=xai-...
+  sks xai docs
+  ```
+
+- **Quieter update prompts.** The "update available" choice is shown once per conversation and then stays quiet for a short window (default 8 min, `SKS_UPDATE_OFFER_THROTTLE_MS`) instead of repeating on every prompt.
+
 ## Retention And Cleanup
 
 SKS keeps durable learning context separate from disposable route work files. Durable context includes `.sneakoscope/memory/**`, shared TriWiki records, `.sneakoscope/wiki/context-pack.json`, wrongness memory, image voxels, avoidance rules, route Completion Proof, trust reports, evidence indexes, reflections, and agent proof summaries. These files are treated as the long-term learning and audit chain.
@@ -401,9 +427,9 @@ sks --mad
 sks --mad --allow-package-install --allow-service-control --allow-network --yes
 ```
 
-This syncs existing codex-lb provider auth, creates/uses the `sks-mad-high` high-power maintenance profile, opens the MAD-SKS permission gate for that Zellij run, and launches a Codex CLI layout. Bare `sks --mad` grants target-project file and shell scope only; add explicit `--allow-*` flags for packages, services, network, Computer Use, browser use, generated assets, file permissions, DB writes, or other high-risk scopes. MAD-SKS is not a DB-only unlock: it is explicit user authorization to widen approved target-project scopes. Catastrophic database wipe/all-row/project-management safeguards remain active, and the pipeline contract still forbids unrequested fallback implementation code.
+This syncs existing codex-lb provider auth, creates/uses the `sks-mad-high` high-power maintenance profile, opens the MAD-SKS permission gate for that Zellij run, starts a same-mission read-only native agent swarm, and launches a Codex CLI layout whose right-side lanes read that MAD ledger. Bare `sks --mad` grants target-project file and shell scope only; add explicit `--allow-*` flags for packages, services, network, Computer Use, browser use, generated assets, file permissions, DB writes, or other high-risk scopes. MAD-SKS is not a DB-only unlock: it is explicit user authorization to widen approved target-project scopes. Catastrophic database wipe/all-row/project-management safeguards remain active, and the pipeline contract still forbids unrequested fallback implementation code.
 
-Before launching, SKS checks npm for a newer `sneakoscope`; answer `y` to update or `n` to continue. Use `--yes` to approve missing dependency installs automatically.
+Before launching, SKS checks npm for a newer `sneakoscope`; answer `y` to update or `n` to continue. Use `--yes` to approve missing dependency installs automatically. Tune MAD swarm startup with `--mad-agents <n>`, `--mad-swarm-work-items <n>`, and `--mad-swarm-backend <backend>`; `--no-mad-swarm` keeps only the cockpit UI if you need a temporary fallback.
 
 ### Team Missions
 
@@ -533,7 +559,7 @@ For headless remotely controllable Codex App/server sessions on Codex CLI 0.130.
 sks codex-app remote-control -- --help
 ```
 
-`sks codex-app check` reports whether the installed Codex CLI is new enough, whether the required app flags are visible, whether Fast/speed-selector config is unlocked, whether Codex App Git Actions can use Commit, Push, Commit and Push, and PR flows, whether the Codex Chrome Extension path is ready for web/browser/webapp verification, and whether installed OpenAI default plugins such as Browser, Chrome, Computer Use, Documents, Presentations, Spreadsheets, and LaTeX are enabled. `sks codex-app chrome-extension --json` is the rapid preflight for web QA/UX/browser routes. When codex-lb is configured, SKS keeps it selected as the top-level Codex App provider while still preserving required app flags and plugin settings. Codex CLI 0.130.0+ app-server/remote-control threads can pick up config changes live; older CLI/TUI sessions should still be restarted after `.codex/config.toml` or MCP/plugin changes.
+`sks codex-app check` reports whether the installed Codex CLI is new enough, whether the required app flags are visible, whether Fast/speed-selector config is unlocked, whether Codex App Git Actions can use Commit, Push, Commit and Push, and PR flows, whether the Codex Chrome Extension path is ready for web/browser/webapp verification, and whether installed OpenAI default plugins such as Browser, Chrome, Computer Use, Documents, Presentations, Spreadsheets, and LaTeX are enabled. `sks-fast-high` intentionally does not pin `sandbox_mode`, so the Codex App/IDE permissions selector owns Full Access vs workspace-write while SKS supplies the model, Fast service tier, approval, and reasoning defaults. `sks codex-app chrome-extension --json` is the rapid preflight for web QA/UX/browser routes. When codex-lb is configured, SKS keeps it selected as the top-level Codex App provider while still preserving required app flags and plugin settings. Codex CLI 0.130.0+ app-server/remote-control threads can pick up config changes live; older CLI/TUI sessions should still be restarted after `.codex/config.toml` or MCP/plugin changes.
 
 For web-related verification, SKS follows the official Codex Chrome Extension setup path first: https://developers.openai.com/codex/app/chrome-extension. `$QA-LOOP`, `$UX-Review`, `$Image-UX-Review`, browser smoke, authenticated web checks, localhost checks, and web visual review must halt quickly if that extension is missing or disabled. Only after the user says the extension setup is complete should the pipeline resume. Codex Computer Use is for native Mac/non-web targets only; it must not be used as browser/web-app verification evidence.
 
@@ -694,7 +720,7 @@ sks doctor --fix
 sks codex-app check
 ```
 
-`sks codex-app check` now prints `Git Actions`. It should be `ok` for Codex App Commit, Push, Commit and Push, and PR buttons to bypass SKS route gates. If it is blocked, repair config with `sks doctor --fix`; if the blocker mentions remote-control, update Codex CLI to `0.130.0` or newer and restart older app-server/TUI sessions.
+`sks codex-app check` now prints `Git Actions`. It should be `ok` for Codex App Commit, Push, Commit and Push, and PR buttons to bypass SKS route gates. Recent Codex builds expose remote control through the `codex remote-control` command rather than a `remote_control` feature flag, so SKS checks the command/version capability directly. If it is blocked, repair config with `sks doctor --fix`; if the blocker mentions remote-control, update Codex CLI to `0.130.0` or newer and restart older app-server/TUI sessions.
 
 ### Codex App UI looks stale after codex-lb changes
 

package/crates/sks-core/Cargo.lock

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

package/crates/sks-core/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "sks-core"
-version = "1.21.4"
+version = "1.21.5"
 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.21.4"),
+        Some("--version") => println!("sks-rs 1.21.5"),
         Some("compact-info") => {
             let mut input = String::new();
             let _ = io::stdin().read_to_string(&mut input);

package/dist/.sks-build-stamp.json

@@ -1,8 +1,8 @@
 {
   "schema": "sks.dist-build-stamp.v1",
   "package_name": "sneakoscope",
-  "package_version": "1.21.4",
-  "source_digest": "70780332db02a19044731adecdb06abcf7d9efdc8b128627be712ca33b3c6881",
-  "source_file_count": 1755,
-  "built_at_source_time": 1780318491834
+  "package_version": "1.21.5",
+  "source_digest": "2fb1d498e53bcbf76f7619c1ea8f3fbef564ddf96d97d2b88b743c51f12450e7",
+  "source_file_count": 1765,
+  "built_at_source_time": 1780379909190
 }

package/dist/bin/sks.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-const FAST_PACKAGE_VERSION = '1.21.4';
+const FAST_PACKAGE_VERSION = '1.21.5';
 const args = process.argv.slice(2);
 try {
     if (args[0] === '--agent' && args[1] === 'worker') {

package/dist/build-manifest.json

@@ -1,16 +1,16 @@
 {
   "schema": "sks.dist-build.v2",
-  "version": "1.21.4",
-  "package_version": "1.21.4",
+  "version": "1.21.5",
+  "package_version": "1.21.5",
   "typescript": true,
   "mjs_runtime_files": 0,
-  "compiled_file_count": 1022,
-  "compiled_js_count": 511,
-  "compiled_dts_count": 511,
-  "source_digest": "70780332db02a19044731adecdb06abcf7d9efdc8b128627be712ca33b3c6881",
-  "source_file_count": 1755,
-  "source_files_hash": "e6487058a1a0894c6b8a629b64319d45be1ad9a0658ab422a39969c1e39ad7e3",
-  "source_list_hash": "e6487058a1a0894c6b8a629b64319d45be1ad9a0658ab422a39969c1e39ad7e3",
+  "compiled_file_count": 1028,
+  "compiled_js_count": 514,
+  "compiled_dts_count": 514,
+  "source_digest": "2fb1d498e53bcbf76f7619c1ea8f3fbef564ddf96d97d2b88b743c51f12450e7",
+  "source_file_count": 1765,
+  "source_files_hash": "24cbdb061915eb66608252400a9c6feba71d0fb99480bf683049fe5e59792c89",
+  "source_list_hash": "24cbdb061915eb66608252400a9c6feba71d0fb99480bf683049fe5e59792c89",
   "src_mjs_runtime_files": 0,
   "dist_stamp_schema": "sks.dist-build-stamp.v1",
   "files": [
@@ -42,6 +42,8 @@
     "cli/recallpulse-command.js",
     "cli/router.d.ts",
     "cli/router.js",
+    "cli/xai-command.d.ts",
+    "cli/xai-command.js",
     "commands/aliases.d.ts",
     "commands/aliases.js",
     "commands/all-features.d.ts",
@@ -863,6 +865,8 @@
     "core/safety/requested-scope-contract.js",
     "core/safety/side-effect-runtime-report.d.ts",
     "core/safety/side-effect-runtime-report.js",
+    "core/safety/ssot-guard.d.ts",
+    "core/safety/ssot-guard.js",
     "core/secret-redaction.d.ts",
     "core/secret-redaction.js",
     "core/session/project-namespace.d.ts",
@@ -1027,6 +1031,8 @@
     "core/zellij/zellij-command.js",
     "core/zellij/zellij-lane-renderer.d.ts",
     "core/zellij/zellij-lane-renderer.js",
+    "core/zellij/zellij-lane-runtime.d.ts",
+    "core/zellij/zellij-lane-runtime.js",
     "core/zellij/zellij-launcher.d.ts",
     "core/zellij/zellij-launcher.js",
     "core/zellij/zellij-layout-builder.d.ts",

package/dist/cli/command-registry.d.ts

@@ -76,6 +76,8 @@ export declare const COMMANDS: {
     'computer-use': CommandEntry;
     cu: CommandEntry;
     context7: CommandEntry;
+    xai: CommandEntry;
+    grok: CommandEntry;
     recallpulse: CommandEntry;
     pipeline: CommandEntry;
     guard: CommandEntry;
@@ -165,6 +167,8 @@ export declare const TYPED_COMMANDS: {
     'computer-use': CommandEntry;
     cu: CommandEntry;
     context7: CommandEntry;
+    xai: CommandEntry;
+    grok: CommandEntry;
     recallpulse: CommandEntry;
     pipeline: CommandEntry;
     guard: CommandEntry;

package/dist/cli/command-registry.js

@@ -129,6 +129,8 @@ export const COMMANDS = {
     'computer-use': entry('beta', 'Record native Mac/non-web Computer Use visual evidence', 'dist/core/commands/computer-use-command.js', commandArgsCommand(() => import('../core/commands/computer-use-command.js'), 'computerUseCommand', 'dist/core/commands/computer-use-command.js')),
     cu: entry('beta', 'Alias for native Computer Use', 'dist/core/commands/computer-use-command.js', commandArgsCommand(() => import('../core/commands/computer-use-command.js'), 'computerUseCommand', 'dist/core/commands/computer-use-command.js')),
     context7: entry('beta', 'Context7 checks and docs', 'dist/cli/context7-command.js', subcommand(() => import('./context7-command.js'), 'context7Command', 'dist/cli/context7-command.js', 'check')),
+    xai: entry('beta', 'Set up and check xAI/Grok search MCP integration', 'dist/cli/xai-command.js', subcommand(() => import('./xai-command.js'), 'xaiCommand', 'dist/cli/xai-command.js', 'check')),
+    grok: entry('beta', 'Alias for xAI/Grok search setup', 'dist/cli/xai-command.js', subcommand(() => import('./xai-command.js'), 'xaiCommand', 'dist/cli/xai-command.js', 'check')),
     recallpulse: entry('labs', 'RecallPulse evidence route', 'dist/commands/recallpulse.js', directCommand(() => import('../commands/recallpulse.js'), 'dist/commands/recallpulse.js')),
     pipeline: entry('beta', 'Inspect pipeline missions', 'dist/commands/pipeline.js', directCommand(() => import('../commands/pipeline.js'), 'dist/commands/pipeline.js')),
     guard: entry('beta', 'Check harness guard', 'dist/commands/guard.js', directCommand(() => import('../commands/guard.js'), 'dist/commands/guard.js')),

package/dist/cli/install-helpers.js

@@ -63,6 +63,10 @@ export async function postinstall({ bootstrap, args = [] }) {
             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());
+        // xAI/Grok web search is an optional source-intelligence provider. It needs a
+        // user-chosen MCP server + XAI_API_KEY, so we never auto-configure it — just make
+        // it discoverable (the integration the operator otherwise can't find at install).
+        console.log('xAI/Grok search (optional): add Grok Live Search with `sks xai setup` (then `export XAI_API_KEY=...`); see `sks xai docs`.');
         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})` : ''}.`);
@@ -1544,7 +1548,10 @@ function normalizeCodexFastModeUiConfigOnce(text = '', opts = {}) {
     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"');
-    next = upsertTomlTableKey(next, 'profiles.sks-fast-high', 'sandbox_mode = "workspace-write"');
+    // Do not force a sandbox from the Codex App fast profile. The App/IDE
+    // permissions selector owns full-access vs workspace-write; this profile only
+    // supplies SKS's model, speed, approval, and reasoning defaults.
+    next = removeTomlTableKey(next, 'profiles.sks-fast-high', 'sandbox_mode');
     next = upsertTomlTableKey(next, 'profiles.sks-fast-high', 'model_reasoning_effort = "high"');
     // 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)

package/dist/cli/xai-command.d.ts

@@ -0,0 +1,9 @@
+export declare function xaiCommand(sub?: string, args?: string[]): Promise<void>;
+export declare function xaiMcpToml(opts: {
+    name: string;
+    url?: string | null;
+    command?: string | null;
+    commandArgs?: string[];
+    envKey?: string;
+}): string;
+//# sourceMappingURL=xai-command.d.ts.map

package/dist/cli/xai-command.js

@@ -0,0 +1,175 @@
+import path from 'node:path';
+import { ensureDir, projectRoot, readText, runProcess, sksRoot, writeTextAtomic } from '../core/fsx.js';
+import { getCodexInfo } from '../core/codex-adapter.js';
+import { detectXaiMcp } from '../core/mcp/xai-mcp-detector.js';
+// `sks xai` — wire up xAI/Grok web search (Live Search) as a Codex MCP server so
+// SKS source-intelligence can fan out to Grok alongside Context7 and Codex web
+// search. SKS detects xAI via an MCP server whose name matches xai/grok/x-ai and
+// that exposes a search/web/query tool (see core/mcp/xai-mcp-detector.ts), so
+// `setup` registers that MCP server and points the operator at XAI_API_KEY.
+//
+// xAI reference (https://api.x.ai/v1): OpenAI-compatible Responses API with the
+// `web_search` / `x_search` tools, model family `grok-4.x`, auth via XAI_API_KEY.
+const XAI_DOCS_URL = 'https://docs.x.ai/developers/tools/web-search';
+const XAI_API_BASE = 'https://api.x.ai/v1';
+const DEFAULT_SERVER_NAME = 'grok-search';
+const flag = (args, name) => args.includes(name);
+export async function xaiCommand(sub = 'check', args = []) {
+    const action = sub || 'check';
+    if (action === 'check' || action === 'status')
+        return xaiCheck(args);
+    if (action === 'setup')
+        return xaiSetup(args);
+    if (action === 'docs' || action === 'help' || action === '--help' || action === '-h')
+        return xaiDocs(args);
+    throw new Error(`Unknown xai command: ${action}. Use: sks xai check | setup | status | docs`);
+}
+async function xaiCheck(args) {
+    const root = await projectRoot().catch(() => process.cwd());
+    const detection = await detectXaiMcp({ root });
+    if (flag(args, '--json'))
+        return console.log(JSON.stringify(detection, null, 2));
+    console.log('SKS xAI / Grok search MCP\n');
+    console.log(`Status:    ${describeStatus(detection.status)}`);
+    console.log(`Configured: ${detection.configured ? 'yes' : 'no'}`);
+    console.log(`Search-capable: ${detection.search_capable ? 'yes' : detection.configured_but_unverified ? 'configured (tools unverified at runtime)' : 'no'}`);
+    if (detection.servers.length) {
+        for (const server of detection.servers) {
+            console.log(`  • ${server.raw_name} (${server.source})${server.tools.length ? ` tools: ${server.tools.join(', ')}` : ''}`);
+        }
+    }
+    console.log(`Checked:   ${detection.config_paths_checked.join(', ') || 'none'}`);
+    if (!detection.configured) {
+        console.log('\nNot configured. Run: sks xai setup --scope project --command "<your-xai-mcp-server>"');
+        console.log('Then export your key:    export XAI_API_KEY=xai-...');
+        console.log(`Docs: ${XAI_DOCS_URL}`);
+    }
+    else if (detection.status === 'configured_but_unverified') {
+        console.log('\nServer is registered; tool capability is verified when Codex lists its tools at runtime.');
+    }
+}
+async function xaiSetup(args) {
+    const scope = readOption(args, '--scope', flag(args, '--global') ? 'global' : 'project');
+    if (!['project', 'global'].includes(scope))
+        throw new Error('Invalid xAI scope. Use --scope project or --scope global.');
+    const name = sanitizeServerName(readOption(args, '--name', DEFAULT_SERVER_NAME));
+    const url = readOption(args, '--url', null);
+    const command = readOption(args, '--command', null);
+    const commandArgs = readRepeatedOption(args, '--arg');
+    const envKey = readOption(args, '--api-key-env', 'XAI_API_KEY');
+    if (!url && !command) {
+        // Nothing to install yet: print a ready-to-paste config + the exact next steps
+        // instead of writing a broken/guessed server entry.
+        printSetupGuidance(scope, name, envKey);
+        return;
+    }
+    if (scope === 'global') {
+        const codex = await getCodexInfo();
+        if (!codex.bin)
+            throw new Error('Codex CLI missing. Install @openai/codex or set SKS_CODEX_BIN, then re-run.');
+        const cmdArgs = url
+            ? ['mcp', 'add', name, '--url', url]
+            : ['mcp', 'add', name, '--', command, ...commandArgs];
+        const result = await runProcess(codex.bin, cmdArgs, { timeoutMs: 30000, maxOutputBytes: 64 * 1024 });
+        if (flag(args, '--json'))
+            return console.log(JSON.stringify({ scope, name, command: `${codex.bin} ${cmdArgs.join(' ')}`, result }, null, 2));
+        if (result.code !== 0)
+            throw new Error(result.stderr || result.stdout || 'codex mcp add failed');
+        console.log(`xAI/Grok MCP "${name}" registered globally.`);
+        console.log(`Set your key: export ${envKey}=xai-...   (docs: ${XAI_DOCS_URL})`);
+        return;
+    }
+    const root = await projectRoot().catch(() => sksRoot());
+    const changed = await ensureProjectXaiMcpConfig(root, { name, url, command, commandArgs, envKey });
+    const detection = await detectXaiMcp({ root });
+    if (flag(args, '--json'))
+        return console.log(JSON.stringify({ scope, name, changed, detection }, null, 2));
+    console.log(`xAI/Grok MCP "${name}" ${changed ? 'configured' : 'already configured'} in .codex/config.toml`);
+    console.log(`Detected:  ${detection.configured ? 'yes' : 'no'} (${detection.status})`);
+    console.log(`Set your key: export ${envKey}=xai-...   (docs: ${XAI_DOCS_URL})`);
+}
+async function xaiDocs(_args) {
+    console.log('SKS xAI / Grok search integration\n');
+    console.log(`API base:   ${XAI_API_BASE}`);
+    console.log('Auth:       XAI_API_KEY (Bearer)');
+    console.log('Model:      grok-4.x (OpenAI-compatible Responses API)');
+    console.log('Tools:      web_search, x_search (agentic Live Search)');
+    console.log(`Reference:  ${XAI_DOCS_URL}\n`);
+    console.log('Wire it into SKS source-intelligence with an MCP server:');
+    console.log('  sks xai setup --scope project --command "npx" --arg "-y" --arg "<your-grok-search-mcp>"');
+    console.log('  sks xai setup --scope global  --url "https://<your-grok-mcp-endpoint>"');
+    console.log('  export XAI_API_KEY=xai-...');
+    console.log('  sks xai check');
+}
+function printSetupGuidance(scope, name, envKey) {
+    console.log('SKS xAI / Grok search setup\n');
+    console.log('Specify the MCP server to register. Examples:');
+    console.log(`  sks xai setup --scope ${scope} --command "npx" --arg "-y" --arg "<your-grok-search-mcp>"`);
+    console.log(`  sks xai setup --scope ${scope} --url "https://<your-grok-mcp-endpoint>"`);
+    console.log('\nReady-to-paste .codex/config.toml block (edit command/args for your server):\n');
+    console.log(xaiMcpToml({ name, command: 'npx', commandArgs: ['-y', '<your-grok-search-mcp>'], envKey }).trim());
+    console.log(`\nThen set your key:  export ${envKey}=xai-...`);
+    console.log(`Docs: ${XAI_DOCS_URL}`);
+}
+export function xaiMcpToml(opts) {
+    const name = sanitizeServerName(opts.name || DEFAULT_SERVER_NAME);
+    const envKey = opts.envKey || 'XAI_API_KEY';
+    const lines = [`[mcp_servers.${name}]`];
+    if (opts.url) {
+        lines.push(`url = ${JSON.stringify(opts.url)}`);
+    }
+    else {
+        lines.push(`command = ${JSON.stringify(opts.command || 'npx')}`);
+        const argv = (opts.commandArgs && opts.commandArgs.length) ? opts.commandArgs : ['-y', '<your-grok-search-mcp>'];
+        lines.push(`args = [${argv.map((a) => JSON.stringify(a)).join(', ')}]`);
+    }
+    lines.push(`env = { ${envKey} = ${JSON.stringify(`\${${envKey}}`)} }`);
+    lines.push('');
+    return lines.join('\n');
+}
+async function ensureProjectXaiMcpConfig(root, opts) {
+    const configPath = path.join(root, '.codex', 'config.toml');
+    await ensureDir(path.dirname(configPath));
+    const current = await readText(configPath, '');
+    const block = xaiMcpToml(opts).trim();
+    const existingRe = new RegExp(`(^|\\n)\\[mcp_servers\\.${escapeRegExp(opts.name)}\\]\\n[\\s\\S]*?(?=\\n\\[[^\\]]+\\]|\\s*$)`);
+    if (existingRe.test(current)) {
+        const next = current.replace(existingRe, `$1${block}\n`);
+        if (next === current)
+            return false;
+        await writeTextAtomic(configPath, next.endsWith('\n') ? next : `${next}\n`);
+        return true;
+    }
+    const text = String(current);
+    await writeTextAtomic(configPath, `${text.trimEnd()}${text.trim() ? '\n\n' : ''}${block}\n`);
+    return true;
+}
+function describeStatus(status) {
+    switch (status) {
+        case 'search_capable': return 'search-capable (ready)';
+        case 'configured_but_unverified': return 'configured (verify tools at runtime)';
+        case 'configured_no_search': return 'configured but no search tool detected';
+        case 'missing': return 'not configured';
+        default: return status;
+    }
+}
+function sanitizeServerName(value) {
+    const cleaned = String(value || DEFAULT_SERVER_NAME).trim().replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '');
+    return cleaned || DEFAULT_SERVER_NAME;
+}
+function readOption(args, name, fallback) {
+    const i = args.indexOf(name);
+    return i >= 0 && args[i + 1] && !String(args[i + 1]).startsWith('--') ? args[i + 1] : fallback;
+}
+function readRepeatedOption(args, name) {
+    const out = [];
+    for (let i = 0; i < args.length; i += 1) {
+        if (args[i] === name && args[i + 1])
+            out.push(String(args[i + 1]));
+    }
+    return out;
+}
+function escapeRegExp(value) {
+    return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+//# sourceMappingURL=xai-command.js.map

package/dist/commands/doctor.js

@@ -5,7 +5,7 @@ import { getCodexInfo } from '../core/codex-adapter.js';
 import { rustInfo } from '../core/rust-accelerator.js';
 import { codexAppIntegrationStatus } from '../core/codex-app.js';
 import { codexLbMetrics, readCodexLbCircuit } from '../core/codex-lb-circuit.js';
-import { ensureGlobalCodexSkillsDuringInstall } from '../cli/install-helpers.js';
+import { ensureGlobalCodexSkillsDuringInstall, ensureGlobalCodexFastModeDuringInstall } from '../cli/install-helpers.js';
 import { normalizeInstallScope } from '../core/init.js';
 import { inspectCodexConfigReadability } from '../core/codex/codex-config-readability.js';
 import { repairCodexConfigEperm } from '../core/codex/codex-config-eperm-repair.js';
@@ -36,7 +36,14 @@ export async function run(_command, args = []) {
             config_backup_path: preFixBackup,
             global_skills: installScope === 'global' && !flag(args, '--local-only')
                 ? await ensureGlobalCodexSkillsDuringInstall({ force: true })
-                : { status: 'skipped', reason: 'project or local-only repair' }
+                : { status: 'skipped', reason: 'project or local-only repair' },
+            // Re-seed the Codex App Fast-mode UI table ([user.fast_mode] visible/enabled/
+            // default_profile) in the global ~/.codex/config.toml so existing installs whose
+            // config predates the Fast-mode UI keys get the App speed selector back. Safe:
+            // backs up + parse-validates before writing, no-op when already present.
+            codex_app_fast_mode: flag(args, '--local-only')
+                ? { status: 'skipped', reason: 'local-only repair' }
+                : await ensureGlobalCodexFastModeDuringInstall().catch((err) => ({ status: 'failed', error: err?.message || String(err) }))
         };
     }
     const root = await projectRoot();

package/dist/commands/image-ux-review.d.ts

@@ -131,6 +131,7 @@ export declare function run(command: any, args?: any): Promise<void | {
             planned_reviews: any;
             generated_count: any;
             real_generated_count: any;
+            non_real_generated_count: any;
             required_count: any;
             text_only_count: any;
             generated_image_file_evidence_checked: boolean;
@@ -710,6 +711,13 @@ export declare function run(command: any, args?: any): Promise<void | {
                     zellij_lane_manifest: string;
                     zellij_lane_persistence: {
                         supervisor: string;
+                        runtime_manifest: string | null;
+                        dispatch_mode: "jsonl_nonblocking";
+                        fifo_policy: "disabled_to_avoid_writer_blocking";
+                        resource_throttle_ms: any;
+                        nice_level: number;
+                        runtime_policy_ok: boolean;
+                        pane_id_source_ok: boolean;
                         no_flicker_verified: boolean;
                         pane_survival_checked: boolean;
                         unexpected_close_count: number;
@@ -1007,6 +1015,13 @@ export declare function run(command: any, args?: any): Promise<void | {
                 zellij_lane_manifest_ok: boolean;
                 zellij_lane_supervisor: string;
                 lane_supervisor_integrated: boolean;
+                zellij_lane_runtime_manifest: string | null;
+                zellij_lane_runtime_policy_ok: boolean;
+                zellij_lane_dispatch_mode: "jsonl_nonblocking";
+                zellij_lane_fifo_policy: "disabled_to_avoid_writer_blocking";
+                zellij_lane_resource_throttle_ms: any;
+                zellij_lane_nice_level: number;
+                zellij_lane_pane_id_source_ok: boolean;
                 zellij_lane_no_flicker_verified: boolean;
                 zellij_lane_survival_checked: boolean;
                 zellij_lane_unexpected_close_count: number;
@@ -1204,6 +1219,7 @@ export declare function run(command: any, args?: any): Promise<void | {
             planned_reviews: any;
             generated_count: any;
             real_generated_count: any;
+            non_real_generated_count: any;
             required_count: any;
             text_only_count: any;
             generated_image_file_evidence_checked: boolean;

package/dist/commands/mad-sks.d.ts

@@ -47,6 +47,13 @@ export declare function run(_command: any, args?: any): Promise<void | {
         main_command_ok: boolean;
         lane_count_ok: boolean;
         geometry_distinct: boolean | null;
+        pane_id_reconciliation: {
+            schema: string;
+            ok: boolean;
+            changed: boolean;
+            matched_count: number;
+            lane_count: number;
+        } | null;
         panes: any[];
         command: any[];
         command_result: import("../core/zellij/zellij-command.js").ZellijCommandResult | null;

package/dist/commands/ppt.d.ts

@@ -559,6 +559,13 @@ export declare function run(command: any, args?: any): Promise<void | {
                     zellij_lane_manifest: string;
                     zellij_lane_persistence: {
                         supervisor: string;
+                        runtime_manifest: string | null;
+                        dispatch_mode: "jsonl_nonblocking";
+                        fifo_policy: "disabled_to_avoid_writer_blocking";
+                        resource_throttle_ms: any;
+                        nice_level: number;
+                        runtime_policy_ok: boolean;
+                        pane_id_source_ok: boolean;
                         no_flicker_verified: boolean;
                         pane_survival_checked: boolean;
                         unexpected_close_count: number;
@@ -856,6 +863,13 @@ export declare function run(command: any, args?: any): Promise<void | {
                 zellij_lane_manifest_ok: boolean;
                 zellij_lane_supervisor: string;
                 lane_supervisor_integrated: boolean;
+                zellij_lane_runtime_manifest: string | null;
+                zellij_lane_runtime_policy_ok: boolean;
+                zellij_lane_dispatch_mode: "jsonl_nonblocking";
+                zellij_lane_fifo_policy: "disabled_to_avoid_writer_blocking";
+                zellij_lane_resource_throttle_ms: any;
+                zellij_lane_nice_level: number;
+                zellij_lane_pane_id_source_ok: boolean;
                 zellij_lane_no_flicker_verified: boolean;
                 zellij_lane_survival_checked: boolean;
                 zellij_lane_unexpected_close_count: number;