sneakoscope 7.0.2 → 7.0.5

package/dist/core/zellij/zellij-slot-telemetry.js

@@ -4,6 +4,8 @@ import { appendJsonlBounded, ensureDir, nowIso, readJson, readText, writeTextAto
 import { withFileLock } from '../locks/file-lock.js';
 export const ZELLIJ_SLOT_TELEMETRY_EVENT_SCHEMA = 'sks.zellij-slot-telemetry-event.v1';
 export const ZELLIJ_SLOT_TELEMETRY_SNAPSHOT_SCHEMA = 'sks.zellij-slot-telemetry-snapshot.v1';
+export const ZELLIJ_SLOT_TELEMETRY_LOCK_TIMEOUT_MS = 2_000;
+export const ZELLIJ_SLOT_TELEMETRY_LOCK_STALE_MS = 15_000;
 const telemetrySnapshotCache = new Map();
 const telemetrySnapshotWriteCounts = new Map();
 const telemetrySnapshotFlushCounts = new Map();
@@ -24,8 +26,8 @@ export async function appendZellijSlotTelemetry(root, event) {
     await ensureDir(path.dirname(file));
     await withFileLock({
         lockPath: `${file}.append.lock`,
-        timeoutMs: 30_000,
-        staleMs: 2 * 60 * 1000
+        timeoutMs: ZELLIJ_SLOT_TELEMETRY_LOCK_TIMEOUT_MS,
+        staleMs: ZELLIJ_SLOT_TELEMETRY_LOCK_STALE_MS
     }, async () => appendJsonlBounded(file, normalized));
     const previous = await readZellijSlotTelemetrySnapshotNoRebuild(root, missionId);
     if (previous) {
@@ -50,10 +52,6 @@ export async function readZellijSlotTelemetrySnapshotNoRebuild(root, missionId)
     const stat = await statTelemetryFile(snapshotPath);
     const recorded = telemetrySnapshotDiskStat.get(snapshotPath);
     const diskChanged = Boolean(stat) && (!recorded || recorded.mtimeMs !== stat.mtimeMs || recorded.size !== stat.size);
-    // CRITICAL: never serve a process-local cache forever. Long-lived reader
-    // processes (zellij slot pane renderers in --watch mode) must observe
-    // snapshot flushes performed by the orchestrator and worker processes,
-    // otherwise the pane renders the same frame for the entire mission.
     if (!diskChanged && cached?.schema === ZELLIJ_SLOT_TELEMETRY_SNAPSHOT_SCHEMA)
         return cached;
     const existing = await readJson(snapshotPath, null);
@@ -63,11 +61,6 @@ export async function readZellijSlotTelemetrySnapshotNoRebuild(root, missionId)
         return cached?.schema === ZELLIJ_SLOT_TELEMETRY_SNAPSHOT_SCHEMA ? cached : null;
     }
     const disk = existing;
-    // Merge with any locally cached (possibly not-yet-flushed) slot state so a
-    // writer process does not lose its pending events when another process
-    // flushed the snapshot file in the meantime. The DISK updated_at stays
-    // authoritative on the read path: it reflects the last real flush, which is
-    // what stale-telemetry detection must measure.
     const merged = cached?.schema === ZELLIJ_SLOT_TELEMETRY_SNAPSHOT_SCHEMA ? mergeTelemetrySnapshots(disk, cached, { updatedAt: 'base' }) : disk;
     telemetrySnapshotCache.set(snapshotPath, merged);
     return merged;
@@ -328,15 +321,12 @@ async function writeTelemetrySnapshotFast(file, snapshot) {
     await ensureDir(path.dirname(file));
     await withFileLock({
         lockPath: `${file}.lock`,
-        timeoutMs: 30000,
-        staleMs: 2 * 60 * 1000
+        timeoutMs: ZELLIJ_SLOT_TELEMETRY_LOCK_TIMEOUT_MS,
+        staleMs: ZELLIJ_SLOT_TELEMETRY_LOCK_STALE_MS
     }, async () => {
         const flushCount = Number(telemetrySnapshotFlushCounts.get(file) || 0) + 1;
         telemetrySnapshotFlushCounts.set(file, flushCount);
         telemetrySnapshotLastFlushMs.set(file, Date.now());
-        // Multiple processes (orchestrator + worker children) flush this file.
-        // Serialize the read/merge/write critical section so a slower writer
-        // cannot overwrite a newer slot observed by a different process.
         const disk = await readJson(file, null);
         const merged = disk?.schema === ZELLIJ_SLOT_TELEMETRY_SNAPSHOT_SCHEMA ? mergeTelemetrySnapshots(disk, snapshot) : snapshot;
         const next = { ...merged, flush_count: Math.max(flushCount, Number(merged.flush_count || 0)) };

package/dist/core/zellij/zellij-ui-mode.js

@@ -13,13 +13,6 @@ export function resolveZellijUiMode(args = [], env = process.env) {
     return resolveExplicitZellijUiMode(args, env) || 'compact-slots';
 }
 export function resolveZellijWorkerPaneUiMode(args = [], env = process.env) {
-    // Default worker panes to the live slot renderer (compact-slots). In
-    // 'full-debug' the pane runs the worker process itself, but the worker is
-    // invoked with --json and the codex SDK streams events to JSONL files — so
-    // the pane stays blank until the worker exits. The slot renderer re-reads
-    // heartbeat/event/stdout artifacts every second and actually shows what each
-    // parallel worker is doing in real time. 'full-debug' remains available via
-    // --zellij-full-debug or SKS_ZELLIJ_UI_MODE=full-debug.
     return resolveExplicitZellijUiMode(args, env) || 'compact-slots';
 }
 function resolveExplicitZellijUiMode(args = [], env = process.env) {

package/dist/core/zellij/zellij-update.js

@@ -28,13 +28,6 @@ export function zellijUpgradeCommandHint(missing = false) {
         return 'cargo install --locked zellij   # or your distro package manager';
     return 'See https://zellij.dev/documentation/installation';
 }
-/**
- * Resolve the latest STABLE zellij version. GitHub's /releases/latest endpoint
- * already excludes prereleases and drafts. Results are cached on disk
- * (default TTL 6h, override with SKS_ZELLIJ_UPDATE_TTL_MS) so command launches
- * stay fast and offline-safe. SKS_ZELLIJ_LATEST_VERSION pins the value for
- * tests and air-gapped environments.
- */
 export async function fetchLatestZellijVersion(input = {}) {
     const env = input.env || process.env;
     const pinned = stripVersionPrefix(String(env.SKS_ZELLIJ_LATEST_VERSION || '').trim());
@@ -48,8 +41,6 @@ export async function fetchLatestZellijVersion(input = {}) {
     }
     try {
         const tag = await githubLatestTag(input.timeoutMs || normalizePositiveInt(env.SKS_ZELLIJ_UPDATE_TIMEOUT_MS, 2500));
-        // GitHub release tags carry a leading "v" (v0.44.3); \b-based version
-        // parsing cannot start inside "v0", so strip the prefix first.
         const version = parseZellijVersionText(stripVersionPrefix(tag));
         if (!version)
             throw new Error(`zellij_latest_tag_unparsed:${tag}`);
@@ -111,11 +102,6 @@ export async function checkZellijUpdateNotice(input = {}) {
     }
     return persistNotice(input.missionDir, notice);
 }
-/**
- * Upgrade zellij to the latest stable release. Only Homebrew automation is
- * attempted (macOS / Linuxbrew); everything else returns manual_required with
- * the exact operator command, mirroring how the Codex CLI update flow behaves.
- */
 export async function upgradeZellijToLatest(input = {}) {
     const before = await checkZellijCapability({ require: false, writeReport: false, env: input.env || process.env }).catch(() => null);
     const beforeVersion = before?.version || null;
@@ -133,11 +119,6 @@ export async function upgradeZellijToLatest(input = {}) {
         };
     }
     const upgradeArgs = missing ? ['install', 'zellij'] : ['upgrade', 'zellij'];
-    // Package installs go through the mutation guard with an explicit
-    // zellij_install scope contract (same path ensureZellijCliTool uses), so the
-    // mutation ledger records the install and safety gates can audit it. The
-    // upgrade only runs after the operator confirmed the [Y/n] prompt or passed
-    // --yes / `sks zellij update --yes`.
     const guardRoot = globalSksRoot();
     const guardCommand = `brew ${upgradeArgs.join(' ')}`;
     const contract = createRequestedScopeContract({
@@ -155,8 +136,6 @@ export async function upgradeZellijToLatest(input = {}) {
         maxOutputBytes: 256 * 1024
     }).catch((err) => ({ code: 1, stdout: '', stderr: String(err?.message || err) }));
     if (run.code !== 0 && !missing && /No such keg|No available formula|not installed/i.test(`${run.stderr}\n${run.stdout}`)) {
-        // zellij exists on PATH but was not installed through Homebrew (e.g. cargo
-        // or a manual binary). Installing the brew formula gives a managed copy.
         run = await guardedPackageInstall(guardCtx, 'zellij', {
             confirmed: true,
             command: 'brew',
@@ -195,14 +174,6 @@ export async function upgradeZellijToLatest(input = {}) {
         error: null
     };
 }
-/**
- * Launch-time prompt, mirroring maybePromptCodexUpdateForLaunch: check the
- * installed zellij version against the latest stable release and offer an
- * upgrade before opening the live session. Never blocks the launch.
- *
- * Skips: --json, --skip-cli-tools, --skip-zellij-update, SKS_SKIP_ZELLIJ_UPDATE=1.
- * Auto-approves: --yes / -y.
- */
 export async function maybePromptZellijUpdateForLaunch(args = [], opts = {}) {
     const env = opts.env || process.env;
     const list = (args || []).map((arg) => String(arg));

package/dist/core/zellij/zellij-worker-pane-manager.js

@@ -15,11 +15,6 @@ export function buildWorkerPaneName(slotId, generationIndex) {
     return `${slotId}/gen-${Math.max(1, Math.floor(Number(generationIndex) || 1))}`;
 }
 export function buildWorkerPaneTitle(slotId, generationIndex, context, serviceTier, backend, status, worktree, taskTitle) {
-    // When a task label is available, the pane title is JUST the label + status:
-    // users identify panes by what they are doing, not by slot ids. Slot/gen,
-    // backend, provider, and worktree details stay inside the pane body and the
-    // SLOTS anchor rows. The verbose format remains the fallback for callers
-    // that have no task context.
     const task = shortWorkerTaskLabel(taskTitle);
     if (task)
         return `${task} · ${workerBackendTag(backend, context?.provider)} · ${status || 'launching'}`;
@@ -28,9 +23,6 @@ export function buildWorkerPaneTitle(slotId, generationIndex, context, serviceTi
     const wt = worktree ? ` · WT:${worktree.id} · branch:${worktree.branch}` : '';
     return `${base}${wt} · ${backend || 'codex-sdk'} · ${providerPaneLabel(normalized)} · ${status || 'launching'}`;
 }
-// Local-LLM workers must be visually distinguishable from GPT/codex workers:
-// only trivial long-running edits belong on local models, while web research
-// and code review must run on GPT. The tag makes a misrouted task obvious.
 export function workerBackendTag(backend, provider) {
     const text = `${String(backend || '')} ${String(provider || '')}`.toLowerCase();
     if (/ollama|local/.test(text))
@@ -39,8 +31,6 @@ export function workerBackendTag(backend, provider) {
         return 'fixture';
     return 'GPT';
 }
-// Lead the pane title with a 1-3 word task label so users can tell WHAT each
-// slot is doing at a glance instead of an anonymous "slot-002/gen-1".
 export function shortWorkerTaskLabel(value, maxChars = 24) {
     const text = String(value || '').replace(/\s+/g, ' ').trim();
     if (!text)
@@ -233,15 +223,7 @@ export async function openWorkerPane(input) {
         return record;
     }
     const paneName = buildWorkerPaneTitle(input.slotId, input.generationIndex, providerContext, input.serviceTier, input.backend, input.statusLabel || 'running', input.worktree || null, input.taskTitle || null);
-    // CRITICAL: serialize anchor + worker pane creation per session. Workers
-    // launch concurrently, and without this lock every worker raced past the
-    // "does the SLOTS anchor exist yet?" check and created its OWN anchor with
-    // --direction right — splitting the screen into N side-by-side columns
-    // (observed in agent-zellij-pane-launch-ledger: terminal_1..terminal_5 all
-    // recorded as separate slot_column_anchor_pane_id values in one mission).
     return withZellijPaneCreationLock(input, async () => {
-        // Re-read the right-column state now that we hold the lock: a previously
-        // serialized worker may have created the anchor and/or its own pane.
         const freshState = rightColumn
             ? await readRightColumnState(root, input.missionId, input.projectRoot).catch(() => null)
             : null;
@@ -259,18 +241,10 @@ export async function openWorkerPane(input) {
         let columnCreationDirectionRequested = null;
         let columnCreationDirectionApplied = null;
         if (rightColumn && !freshFocusCandidate) {
-            // Single right-column invariant: if this zellij session was reused (stable
-            // per-cwd name) and already carries a SLOTS anchor from a prior mission, adopt
-            // it and stack workers underneath instead of splitting ANOTHER `--direction
-            // right` column — repeated right-splits are exactly what fragments the screen
-            // into side-by-side columns. A fresh column is only split when none exists yet.
             const adoptedAnchorPaneId = createSession.ok
                 ? await findExistingSlotsAnchorPaneId(input.sessionName, cwd).catch(() => null)
                 : null;
             if (adoptedAnchorPaneId) {
-                // Adopted an existing column: no creation was requested, so leave the
-                // column-creation direction fields null (avoids a false
-                // `zellij_worker_slot_column_anchor_not_created` blocker).
                 slotColumnAnchorPaneId = adoptedAnchorPaneId;
                 await recordSlotColumnAnchorInRightColumn({
                     root,
@@ -314,11 +288,6 @@ export async function openWorkerPane(input) {
         const focus = focusPaneId
             ? await focusZellijPaneById(input.sessionName, focusPaneId, cwd)
             : null;
-        // Vertical stack policy: the first worker splits DOWN from the SLOTS anchor;
-        // every following worker joins a zellij stacked-pane group with the previous
-        // worker (`new-pane --stacked`, zellij >= 0.43) so the right column stays a
-        // clean vertical stack instead of fragmenting the screen. Opt out with
-        // SKS_ZELLIJ_WORKER_STACKED=0.
         const stackIntent = process.env.SKS_ZELLIJ_WORKER_STACKED !== '0'
             && Boolean(lastVisibleWorkerPaneId)
             && focus?.ok === true;
@@ -651,9 +620,6 @@ async function reconcileZellijWorkerPaneId(sessionName, paneName, resultPath, cw
         blockers: paneId == null ? ['zellij_worker_pane_id_not_reconciled'] : []
     };
 }
-// Look up an already-open SLOTS anchor pane in a (possibly reused) session so a
-// new mission can stack its workers under the existing right column instead of
-// splitting another one. Returns the live pane id (terminal_<n>) or null.
 async function findExistingSlotsAnchorPaneId(sessionName, cwd) {
     const listed = await runZellij(['--session', sessionName, 'action', 'list-panes', '--json', '--all'], {
         cwd,
@@ -775,11 +741,6 @@ async function focusZellijPaneById(sessionName, paneId, cwd) {
         last = focus;
         if (focus.ok)
             return focus;
-        // zellij exits non-zero with "Pane Terminal(N) is already focused" when the
-        // target pane already holds focus (common: new-pane auto-focuses the pane
-        // it created, so the previous worker pane is usually still focused). That
-        // is a success for our purposes — without this, stacked placement would
-        // silently fall back to a plain down-split on every consecutive worker.
         if (/already focused/i.test(`${focus.stdout_tail || ''} ${focus.stderr_tail || ''}`)) {
             return { ...focus, ok: true, blockers: [], warnings: [...focus.warnings, 'zellij_pane_already_focused'] };
         }

package/dist/native/sks-menubar/Sources/DiagnosticsViewController.swift

@@ -4,6 +4,7 @@ final class DiagnosticsViewController: NSViewController, ControlCenterPage {
     private let processClient: ProcessClient
     private let operations: OperationCoordinator
     private let status = NativeView.detail("Diagnostics are idle.")
+    private let codexGuidance = NativeView.detail("Codex CLI: prefer the latest channel. Use Updates → Update Codex CLI when status reports an update.")
     private var busy = false
 
     init(processClient: ProcessClient, operations: OperationCoordinator) {
@@ -16,14 +17,15 @@ final class DiagnosticsViewController: NSViewController, ControlCenterPage {
     override func loadView() {
         let buttons = NSStackView(views: [
             NativeView.button("Run Doctor", target: self, action: #selector(doctor)),
+            NativeView.button("Update Codex CLI", target: self, action: #selector(updateCodexCLI)),
             NativeView.button("Open Last Log", target: self, action: #selector(openLog)),
             NativeView.button("Restart Menu Bar", target: self, action: #selector(restart))
         ])
         buttons.orientation = .horizontal; buttons.spacing = 8
         view = NativeView.stack([
             NativeView.title("Diagnostics"),
-            NativeView.detail("Diagnostic output is bounded, redacted, and written with owner-only permissions. Use this page when another Center action reports a blocker."),
-            status, buttons
+            NativeView.detail("Diagnostic output is bounded, redacted, and written with owner-only permissions. Use this page when another Center action reports a blocker. Feature routes that need newer Codex fail with an update CTA instead of locking all of SKS."),
+            status, codexGuidance, buttons
         ])
         refreshOnAppear()
     }
@@ -37,6 +39,22 @@ final class DiagnosticsViewController: NSViewController, ControlCenterPage {
         } else {
             status.stringValue = "Diagnostics are idle. No operation log exists yet."
         }
+        refreshCodexGuidance()
+    }
+
+    private func refreshCodexGuidance() {
+        let update = readJson(path: FileManager.default.homeDirectoryForCurrentUser
+            .appendingPathComponent(".sneakoscope-global/cache/update-status.json").path)
+        let codex = update?["codex_cli"] as? [String: Any]
+        if codex?["update_available"] as? Bool == true {
+            let current = codex?["current"] as? String ?? "installed"
+            let latest = codex?["latest"] as? String ?? "preferred latest"
+            codexGuidance.stringValue = "Codex CLI update available: \(current) → \(latest). Prefer latest via Update Codex CLI, or run sks codex update."
+        } else if let current = codex?["current"] as? String {
+            codexGuidance.stringValue = "Codex CLI \(current) looks current in the shared snapshot. Prefer latest continuously; Naruto and other capability routes still probe features before use."
+        } else {
+            codexGuidance.stringValue = "Codex CLI: prefer the latest channel. Use Updates → Update Codex CLI when status reports an update, or run sks codex update."
+        }
     }
 
     @objc private func doctor() {
@@ -47,6 +65,7 @@ final class DiagnosticsViewController: NSViewController, ControlCenterPage {
             self.busy = false
             if result.code == 0 {
                 self.status.stringValue = "Doctor completed with no blocking issue."
+                self.refreshCodexGuidance()
                 return
             }
             if let json = self.json(result.output) {
@@ -54,14 +73,49 @@ final class DiagnosticsViewController: NSViewController, ControlCenterPage {
                 let blockers = (json["blockers"] as? [String])?.count ?? (json["issues"] as? [Any])?.count
                 if let blockers = blockers {
                     self.status.stringValue = "Doctor reported \(blockers) issue\(blockers == 1 ? "" : "s"). Open Last Log for redacted detail."
+                    self.refreshCodexGuidance()
                     return
                 }
                 if ok == false {
                     self.status.stringValue = "Doctor reported a blocker. Open Last Log for redacted detail."
+                    self.refreshCodexGuidance()
                     return
                 }
             }
             self.status.stringValue = "Doctor reported a blocker · \(NativeView.redactPreview(result.output))"
+            self.refreshCodexGuidance()
+        }
+    }
+
+    @objc private func updateCodexCLI() {
+        guard let operation = operations.begin(kind: "codex-cli-update", mutationGroup: "update", summary: "Update Codex CLI") else {
+            status.stringValue = "Another update or MCP mutation is already running."
+            return
+        }
+        busy = true
+        status.stringValue = "Updating Codex CLI…"
+        _ = operations.update(operation, state: .running, stage: "running", progress: nil, summary: status.stringValue)
+        processClient.run(["codex", "update", "--json"], timeout: nil) { [weak self] result in
+            guard let self = self else { return }
+            self.busy = false
+            let payload = self.json(result.output)
+            let ok = result.code == 0
+                && !result.truncated
+                && payload?["schema"] as? String == "sks.codex-cli-update-result.v1"
+                && payload?["ok"] as? Bool == true
+            _ = self.operations.update(
+                operation,
+                state: ok ? .succeeded : .failed,
+                stage: "complete",
+                progress: 1,
+                summary: ok ? "Codex CLI update completed" : "Codex CLI update failed"
+            )
+            if ok {
+                self.status.stringValue = "Codex CLI update completed. Shared update status will refresh on the next Overview/Updates load."
+            } else {
+                self.status.stringValue = "Codex CLI update needs attention. Open Updates for structured guidance, or run sks codex update."
+            }
+            self.refreshCodexGuidance()
         }
     }
 
@@ -90,4 +144,9 @@ final class DiagnosticsViewController: NSViewController, ControlCenterPage {
         guard let data = text.data(using: .utf8) else { return nil }
         return try? JSONSerialization.jsonObject(with: data) as? [String: Any]
     }
+
+    private func readJson(path: String) -> [String: Any]? {
+        guard let data = FileManager.default.contents(atPath: path) else { return nil }
+        return try? JSONSerialization.jsonObject(with: data) as? [String: Any]
+    }
 }

package/dist/native/sks-menubar/Sources/MCPServersViewController.swift

@@ -140,7 +140,7 @@ final class MCPServersViewController: NSViewController, NSTableViewDataSource, N
 
     @objc private func refresh() {
         let scope = selectedScope(); status.stringValue = "Loading \(scope) MCP configuration…"
-        processClient.run(["mcp", "config", "list", "--scope", scope] + scopeContext(scope, mutation: false) + ["--json"]) { [weak self] result in
+        processClient.run(["mcp", "config", "list", "--scope", scope] + scopeContext(scope, mutation: false) + ["--json"], timeout: NativeView.statusTimeout) { [weak self] result in
             guard let self = self else { return }
             guard let json = self.json(result.output), let servers = json["servers"] as? [[String: Any]] else {
                 self.rows = []; self.table.reloadData(); self.status.stringValue = "MCP inventory unavailable. No configuration was changed."
@@ -293,7 +293,7 @@ final class MCPServersViewController: NSViewController, NSTableViewDataSource, N
     private func mutate(_ args: [String], stdin: String? = nil) {
         guard !mutating, let operation = operations.begin(kind: "mcp-config", mutationGroup: "mcp", summary: "MCP configuration change") else { status.stringValue = "An update or MCP mutation is already running."; return }
         mutating = true; updateButtons(); _ = operations.update(operation, state: .running, stage: "apply", progress: nil, summary: "Applying scoped MCP change")
-        processClient.run(args, stdin: stdin) { [weak self] result in
+        processClient.run(args, stdin: stdin, timeout: NativeView.mutationTimeout) { [weak self] result in
             guard let self = self else { return }
             self.mutating = false
             _ = self.operations.update(operation, state: result.code == 0 ? .succeeded : .failed, stage: "complete", progress: 1, summary: result.code == 0 ? "MCP change complete" : "MCP change failed")
@@ -310,7 +310,14 @@ final class MCPServersViewController: NSViewController, NSTableViewDataSource, N
     private func writableScopeForBackup() -> String? { let scope = selectedScope(); return scope == "global" || scope == "project" ? scope : nil }
     private func scopeContext(_ scope: String, mutation: Bool) -> [String] { scope == "project" ? projectContext(mutation: mutation) : [] }
     private func projectContext(mutation: Bool) -> [String] { var args = ["--project-root", AppRuntime.projectRoot, "--trusted-project"]; if mutation { args.append("--confirm-project") }; return args }
-    private func json(_ text: String) -> [String: Any]? { guard let data = text.data(using: .utf8) else { return nil }; return try? JSONSerialization.jsonObject(with: data) as? [String: Any] }
+    private func json(_ text: String) -> [String: Any]? {
+        guard let data = text.data(using: .utf8) else { return nil }
+        if let object = try? JSONSerialization.jsonObject(with: data) as? [String: Any] { return object }
+        guard let start = text.range(of: "{", options: [.backwards])?.lowerBound else { return nil }
+        let slice = String(text[start...])
+        guard let sliced = slice.data(using: .utf8) else { return nil }
+        return try? JSONSerialization.jsonObject(with: sliced) as? [String: Any]
+    }
     private func jsonText(_ payload: [String: Any]) -> String? { guard let data = try? JSONSerialization.data(withJSONObject: payload) else { return nil }; return String(data: data, encoding: .utf8).map { $0 + "\n" } }
     private func actionButton(_ title: String, _ action: Selector) -> NSButton { NativeView.button(title, target: self, action: action) }
     private func updateButtons() {

package/dist/native/sks-menubar/Sources/OverviewViewController.swift

@@ -89,6 +89,9 @@ enum OverviewSummary {
             let menu = update["menubar"] as? [String: Any]
             lines.append("SKS install: \(versionSummary(sks))")
             lines.append("Codex CLI: \(versionSummary(codex)) · Codex app: \(codexAppState)")
+            if let inducement = codexUpdateInducement(codex) {
+                lines.append(inducement)
+            }
 
             var menuParts = ["running build \(menuBarBuild)"]
             if let expected = menu?["expected_version"] as? String { menuParts.append("expected \(expected)") }
@@ -185,6 +188,13 @@ enum OverviewSummary {
         return "\(current) · latest \(latest)"
     }
 
+    private static func codexUpdateInducement(_ value: [String: Any]?) -> String? {
+        guard value?["update_available"] as? Bool == true else { return nil }
+        let current = nonEmpty(value?["current"] as? String) ?? "installed"
+        let latest = nonEmpty(value?["latest"] as? String) ?? "preferred latest"
+        return "Action: update Codex CLI (\(current) → \(latest)) from Updates, or choose Update Codex CLI Now in the menu bar."
+    }
+
     private static func verificationState(_ value: Any?) -> String {
         guard let value = value as? Bool else { return "unknown" }
         return value ? "verified" : "needs attention"
@@ -227,6 +237,7 @@ final class OverviewViewController: NSViewController, ControlCenterPage {
     private var generation = 0
     private var doctorButton: NSButton!
     private var refreshButton: NSButton!
+    private var updateCodexButton: NSButton!
 
     init(processClient: ProcessClient, operations: OperationCoordinator) {
         self.processClient = processClient
@@ -238,12 +249,14 @@ final class OverviewViewController: NSViewController, ControlCenterPage {
     override func loadView() {
         doctorButton = NativeView.button("Run Doctor", target: self, action: #selector(doctor))
         refreshButton = NativeView.button("Refresh", target: self, action: #selector(refreshStatus))
-        let buttons = NSStackView(views: [doctorButton, refreshButton])
+        updateCodexButton = NativeView.button("Update Codex CLI", target: self, action: #selector(updateCodexCLI))
+        updateCodexButton.setAccessibilityHelp("Update the operator Codex CLI to the preferred latest channel.")
+        let buttons = NSStackView(views: [doctorButton, refreshButton, updateCodexButton])
         buttons.orientation = .horizontal
         buttons.spacing = 8
         view = NativeView.stack([
             NativeView.title("Overview"),
-            NativeView.detail("Menu Bar build \(AppRuntime.packageVersion) · Local health for SKS, Codex CLI, MCP, Remote, and operations."),
+            NativeView.detail("Menu Bar build \(AppRuntime.packageVersion) · Local health for SKS, Codex CLI, MCP, Remote, and operations. Prefer the latest Codex CLI; SKS stays version-agnostic and capability-gates features."),
             status,
             notificationInbox,
             buttons
@@ -265,6 +278,39 @@ final class OverviewViewController: NSViewController, ControlCenterPage {
         loadStatus(forceUpdateRefresh: true)
     }
 
+    @objc private func updateCodexCLI() {
+        guard let operation = operations.begin(kind: "codex-cli-update", mutationGroup: "update", summary: "Update Codex CLI") else {
+            status.stringValue = "Another update or MCP mutation is already running. Open Updates to review it."
+            return
+        }
+        updateCodexButton?.isEnabled = false
+        doctorButton?.isEnabled = false
+        refreshButton?.isEnabled = false
+        status.stringValue = "Updating Codex CLI to the preferred latest…"
+        _ = operations.update(operation, state: .running, stage: "running", progress: nil, summary: status.stringValue)
+        processClient.run(["codex", "update", "--json"], timeout: nil) { [weak self] result in
+            guard let self = self else { return }
+            let ok = result.code == 0
+                && !result.truncated
+                && (self.json(result.output)?["ok"] as? Bool == true)
+                && (self.json(result.output)?["schema"] as? String == "sks.codex-cli-update-result.v1")
+            _ = self.operations.update(
+                operation,
+                state: ok ? .succeeded : .failed,
+                stage: "complete",
+                progress: 1,
+                summary: ok ? "Codex CLI update completed" : "Codex CLI update failed"
+            )
+            self.updateCodexButton?.isEnabled = true
+            self.doctorButton?.isEnabled = true
+            self.refreshButton?.isEnabled = true
+            self.status.stringValue = ok
+                ? "Codex CLI update completed. Refreshing shared update status…"
+                : "Codex CLI update needs attention. Open Updates or Diagnostics for structured guidance."
+            self.loadStatus(forceUpdateRefresh: true)
+        }
+    }
+
     private func loadStatus(forceUpdateRefresh: Bool) {
         generation += 1
         let requestGeneration = generation
@@ -353,6 +399,12 @@ final class OverviewViewController: NSViewController, ControlCenterPage {
 
     private func json(_ text: String) -> [String: Any]? {
         guard let data = text.data(using: .utf8) else { return nil }
-        return try? JSONSerialization.jsonObject(with: data) as? [String: Any]
+        if let object = try? JSONSerialization.jsonObject(with: data) as? [String: Any] { return object }
+        // Child processes may print banner lines before JSON (for example a
+        // migration gate message). Prefer the last top-level object payload.
+        guard let start = text.range(of: "{", options: [.backwards])?.lowerBound else { return nil }
+        let slice = String(text[start...])
+        guard let sliced = slice.data(using: .utf8) else { return nil }
+        return try? JSONSerialization.jsonObject(with: sliced) as? [String: Any]
     }
 }

package/dist/native/sks-menubar/Sources/ProvidersOpenRouter.swift

@@ -0,0 +1,76 @@
+import Cocoa
+
+extension ProvidersViewController {
+    func refreshOpenRouterStatus() {
+        processClient.run(["codex-app", "openrouter-status", "--json"], timeout: NativeView.statusTimeout) { [weak self] result in
+            guard let self = self else { return }
+            guard result.code == 0, let json = self.json(result.output) else {
+                if !self.busy { self.openRouterStatus.stringValue = "OpenRouter: status unavailable." }
+                return
+            }
+            let current = self.openRouterModelField.stringValue.trimmingCharacters(in: .whitespacesAndNewlines)
+            if let model = json["model"] as? String, !model.isEmpty, current.isEmpty || current == "z-ai/glm-5.2" {
+                self.openRouterModelField.stringValue = model
+            }
+            if !self.busy { self.openRouterStatus.stringValue = self.describeOpenRouterStatus(json) }
+        }
+    }
+
+    func describeOpenRouterStatus(_ json: [String: Any]) -> String {
+        let keyPresent = json["key_present"] as? Bool == true
+        let providerPresent = json["provider_present"] as? Bool == true
+        let selected = json["selected"] as? Bool == true
+        let model = json["model"] as? String ?? "unset"
+        if !keyPresent { return "OpenRouter: key missing. Save OpenRouter key, then Use OpenRouter." }
+        if !providerPresent { return "OpenRouter: provider missing. Save OpenRouter key to install the provider block." }
+        if selected { return "OpenRouter: active · model \(model). Restore Chat / Pro or Use codex-lb to switch away." }
+        return "OpenRouter: key stored · model \(model) · not selected. Click Use OpenRouter."
+    }
+
+    @objc func saveOpenRouterKey() {
+        guard let window = view.window else { return }
+        promptForSecretKey(
+            window: window,
+            sheetTitle: "OpenRouter API Key",
+            sheetMessage: "Paste your OpenRouter API key. It is sent through stdin and never logged. Saving does not switch the active provider.",
+            placeholder: "sk-or-…",
+            args: ["codex-app", "set-openrouter-key", "--api-key-stdin", "--json"],
+            kind: "openrouter-set-key",
+            title: "Save OpenRouter key",
+            statusLabel: openRouterStatus,
+            successSummary: "OpenRouter key saved",
+            failSummary: "OpenRouter key save failed"
+        )
+    }
+
+    @objc func useOpenRouter() {
+        let model = openRouterModelField.stringValue.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !model.isEmpty else {
+            openRouterStatus.stringValue = "Enter an OpenRouter model id, then click Use OpenRouter."
+            return
+        }
+        guard !busy else {
+            openRouterStatus.stringValue = "Another provider action is already running."
+            return
+        }
+        guard let snapshot = operations.begin(kind: "openrouter-use", mutationGroup: "codex-config", summary: "Use OpenRouter") else {
+            openRouterStatus.stringValue = "Another guarded mutation is already running. Wait or open Diagnostics."
+            return
+        }
+        setBusy(true)
+        openRouterStatus.stringValue = "Activating OpenRouter (\(model)) and restarting Codex App…"
+        _ = operations.update(snapshot, state: .running, stage: "activating", progress: nil, summary: "Use OpenRouter")
+        processClient.run(["codex-app", "use-openrouter", "--model", model, "--restart-app", "--json"], timeout: NativeView.mutationTimeout) { [weak self] result in
+            guard let self = self else { return }
+            self.setBusy(false)
+            let json = self.json(result.output)
+            let ok = result.code == 0 && json?["ok"] as? Bool == true
+            let activeModel = (json?["model"] as? String) ?? model
+            _ = self.operations.update(snapshot, state: ok ? .succeeded : .failed, stage: "complete", progress: 1, summary: ok ? "OpenRouter active after restart" : "OpenRouter activation needs action")
+            self.openRouterStatus.stringValue = ok
+                ? "OpenRouter: active · model \(activeModel)."
+                : "Use OpenRouter failed · \(NativeView.redactPreview(result.output))"
+            self.refresh()
+        }
+    }
+}