sneakoscope 4.7.3 → 4.8.0

package/README.md

@@ -49,7 +49,7 @@ sks seo-geo-optimizer apply latest --mode seo --apply --json
 sks seo-geo-optimizer audit --mode geo --target package --offline --json
 ```
 
-> 📋 **Current release: `v4.7.3`** — full release history lives in [CHANGELOG.md](CHANGELOG.md). This README documents how Sneakoscope works today, not its version-by-version changes. Release readiness is tracked in [docs/release-readiness.md](docs/release-readiness.md).
+> 📋 **Current release: `v4.8.0`** — full release history lives in [CHANGELOG.md](CHANGELOG.md). This README documents how Sneakoscope works today, not its version-by-version changes. Release readiness is tracked in [docs/release-readiness.md](docs/release-readiness.md).
 
 ## 🍥 Parallelism, UX, And Integrations
 
@@ -74,7 +74,7 @@ sks seo-geo-optimizer audit --mode geo --target package --offline --json
   sks insane-search x "site:x.com product launch"
   ```
 
-- **CLI-only SKS update notices.** Codex App hooks no longer stop normal work to ask for an SKS update. CLI launch surfaces such as `sks --mad` print a non-blocking latest-version notice, `sks update-check` / `sks update check` show the explicit status, and `sks doctor --fix` runs the guarded global SKS update path before repair.
+- **CLI-only SKS update notices.** Codex App hooks no longer stop normal work to ask for an SKS update. CLI launch surfaces such as `sks --mad` print a non-blocking latest-version notice, `sks update-check` / `sks update check` show the explicit status, bare `sks update` checks npm latest and updates the global package, and `sks doctor --fix` runs the guarded repair path.
 
 ## 🧹 Retention And Cleanup
 
@@ -318,7 +318,7 @@ sks deps check --yes
 sks codex-app check
 sks doctor --fix
 sks fix-path
-sks update now
+sks update
 ```
 
 `sks doctor --fix` repairs stale SKS-managed Codex TOML, agent role `config_file` paths, and unsupported managed role fields. It now dedupes repeated TOML tables before repair, keeps the first existing external MCP block such as `context7` or `supabase` unchanged, and only removes/repairs SKS-owned stale MCP blocks such as broken `node_repl`.
@@ -363,7 +363,7 @@ sks codex-app set-openrouter-key --api-key-stdin
 sks codex-app glm-profile install
 ```
 
-This writes the OpenRouter key to the SKS user secret store, writes redacted metadata only, and installs Codex Desktop-compatible `openrouter` provider plus selectable `sks-glm-52-*` reasoning profiles. The npm package does not patch the Codex Desktop macOS menu binary; a top-level `Set OpenRouter Key` menu/modal requires upstream Codex Desktop UI support. The package-owned command surface above is the supported repair path.
+This writes the OpenRouter key to the SKS user secret store, writes redacted metadata only, and installs Codex Desktop-compatible `openrouter` provider plus selectable `sks-glm-52-*` reasoning profiles. The npm package does not patch the Codex Desktop macOS menu binary; a top-level menu between Window and Help requires upstream Codex Desktop UI support. On macOS, `sks doctor --fix` installs or refreshes a right-side SKS menu bar companion that appears as a compact circled `S` status icon with codex-lb, ChatGPT OAuth, OpenRouter/GLM, Fast Check, SKS Version Check, Update SKS Now, settings, and Codex restart actions.
 
 ### Switching auth mode: codex-lb ↔ ChatGPT OAuth
 
@@ -404,7 +404,7 @@ sks --mad --allow-package-install --allow-service-control --allow-network --yes
 
 This syncs existing codex-lb provider auth, creates/uses the `sks-mad-high` xhigh maintenance profile, opens the MAD-SKS permission gate for that Zellij run, starts a same-mission bounded 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 and does not create a MadDB capability. Catastrophic database wipe/all-row/project-management safeguards remain active outside the first-class MadDB route, and the pipeline contract still forbids unrequested fallback implementation code.
 
-Before launching, SKS checks npm for a newer `sneakoscope` and prints a non-blocking update notice when one is available; use `sks update now` or `sks doctor --fix` when you want SKS to update itself. 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.
+Before launching, SKS checks npm for a newer `sneakoscope` and prints a non-blocking update notice when one is available; use `sks update` when you want SKS to update itself from npm. 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
 
@@ -679,12 +679,12 @@ If PATH or npm has duplicate global installs, `sks doctor --fix` keeps one globa
 
 ```sh
 sks update-check --json
-sks update now
+sks update
 npm ls -g sneakoscope --depth=0
 sks doctor --fix
 ```
 
-CLI update checks compare npm latest against the effective installed version from source metadata, PATH `sks --version`, and global npm package metadata. Codex App hooks do not force update choices during ordinary work. `sks update now` installs through npm global mode instead of mutating the current project's dependencies, and `sks doctor --fix` runs that guarded global update path before setup/config repair. If a global update succeeded but an old shim remains earlier on PATH, `sks doctor --fix` can remove duplicate global installs and refresh the managed setup.
+CLI update checks compare npm latest against the effective installed version from source metadata, PATH `sks --version`, and global npm package metadata. Codex App hooks do not force update choices during ordinary work. Bare `sks update` checks npm latest and installs through npm global mode instead of mutating the current project's dependencies; `sks update check` is the status-only form, and `sks update now` remains an explicit alias. Successful/current update runs also install or refresh the macOS right-side `SKS` menu bar companion so it is already visible when Codex App is opened. If a global update succeeded but an old shim remains earlier on PATH, `sks doctor --fix` can remove duplicate global installs and refresh the managed setup.
 
 ### Zellij is missing
 

package/crates/sks-core/Cargo.lock

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

package/crates/sks-core/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "sks-core"
-version = "4.7.3"
+version = "4.8.0"
 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 4.7.3"),
+        Some("--version") => println!("sks-rs 4.8.0"),
         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 = '4.7.3';
+const FAST_PACKAGE_VERSION = '4.8.0';
 const args = process.argv.slice(2);
 try {
     if (args[0] === '--agent' && args[1] === 'worker') {

package/dist/cli/command-registry.js

@@ -85,7 +85,7 @@ export const COMMANDS = {
     run: entry('beta', 'Classify and execute a task through the SKS trust kernel', 'dist/core/commands/run-command.js', argsCommand(() => import('../core/commands/run-command.js'), 'runCommand', 'dist/core/commands/run-command.js')),
     status: entry('stable', 'Show concise active mission and trust status', 'dist/core/commands/status-command.js', argsCommand(() => import('../core/commands/status-command.js'), 'statusCommand', 'dist/core/commands/status-command.js')),
     root: entry('stable', 'Show active SKS root', 'dist/commands/root.js', directCommand(() => import('../commands/root.js'), 'dist/commands/root.js')),
-    update: entry('stable', 'Update the global SKS npm package', 'dist/core/commands/basic-cli.js', subcommand(() => import(basicModule), 'updateCommand', 'dist/core/commands/basic-cli.js', 'check')),
+    update: entry('stable', 'Update the global SKS npm package', 'dist/core/commands/basic-cli.js', subcommand(() => import(basicModule), 'updateCommand', 'dist/core/commands/basic-cli.js', 'now')),
     'update-check': entry('stable', 'Check npm package freshness', 'dist/core/commands/basic-cli.js', basicArgs('updateCheckCommand')),
     wizard: entry('stable', 'Open setup wizard help', 'dist/core/commands/basic-cli.js', basicNoArgs('quickstartCommand')),
     usage: entry('stable', 'Show focused usage topic', 'dist/core/commands/basic-cli.js', basicArgs('usageCommand')),

package/dist/commands/doctor.js

@@ -39,6 +39,7 @@ import { planDoctorDirtyRepair } from '../core/doctor/doctor-dirty-planner.js';
 import { doctorRepairPostcheck } from '../core/doctor/doctor-repair-postcheck.js';
 import { withSecretPreservationGuard } from '../core/config/config-migration-journal.js';
 import { writeProjectUpdateMigrationReceipt } from '../core/update/update-migration-state.js';
+import { installSksMenuBar } from '../core/codex-app/sks-menubar.js';
 export async function run(_command, args = []) {
     const root = await projectRoot();
     const doctorFix = flag(args, '--fix');
@@ -274,6 +275,27 @@ async function runDoctor(args = [], root, doctorFix) {
             blockers: [err?.message || String(err)]
         }))
         : codexAppUiPlan;
+    const sksMenuBar = await installSksMenuBar({
+        root,
+        apply: doctorFix,
+        launch: doctorFix
+    }).catch((err) => ({
+        schema: 'sks.codex-app-sks-menubar.v1',
+        ok: false,
+        apply: doctorFix,
+        status: 'blocked',
+        platform: process.platform,
+        app_path: null,
+        executable_path: null,
+        launch_agent_path: null,
+        action_script_path: null,
+        report_path: `${root}/.sneakoscope/reports/sks-menubar.json`,
+        menu_items: [],
+        actions: [],
+        launch: { requested: doctorFix, method: 'none', ok: false, error: err?.message || String(err) },
+        blockers: [err?.message || String(err)],
+        warnings: []
+    }));
     const zellijRepair = shouldRunZellijRepair
         ? await runDoctorZellijRepair({ root, args, doctorFix }).catch((err) => ({
             schema: 'sks.zellij-self-heal.v1',
@@ -434,6 +456,20 @@ async function runDoctor(args = [], root, doctorFix) {
                         rollback_evidence: 'optional_supabase_no_ready_mutation_required'
                     })
                 },
+                {
+                    id: 'sks_menubar',
+                    required_for_ready: false,
+                    run: async () => ({
+                        id: 'sks_menubar',
+                        ok: sksMenuBar?.ok !== false,
+                        repaired: doctorFix && Array.isArray(sksMenuBar?.actions) && sksMenuBar.actions.length > 0,
+                        required_for_ready: false,
+                        blockers: sksMenuBar?.blockers || [],
+                        warnings: sksMenuBar?.warnings || [],
+                        artifact_path: sksMenuBar?.report_path || null,
+                        rollback_evidence: sksMenuBar?.launch_agent_path || sksMenuBar?.report_path || 'sks_menubar_optional_no_core_mutation'
+                    })
+                },
                 {
                     id: 'command_alias_cleanup',
                     run: async () => ({
@@ -621,6 +657,7 @@ async function runDoctor(args = [], root, doctorFix) {
         agent_role_config: agentRoleConfigRepair,
         repair: configRepair,
         codex_app_ui: codexAppUi,
+        sks_menubar: sksMenuBar,
         codex_0138_doctor: codex0138Doctor,
         codex_plugin_inventory: pluginInventory?.report || null,
         codex_plugin_app_template_policy: pluginPolicy,
@@ -658,6 +695,7 @@ async function runDoctor(args = [], root, doctorFix) {
         rust,
         codex_app: codexApp,
         codex_app_ui: codexAppUi,
+        sks_menubar: sksMenuBar,
         provider_context: providerContext,
         codex_lb: codexLb,
         codex_doctor: authoritativeCodexDoctor,
@@ -697,7 +735,7 @@ async function runDoctor(args = [], root, doctorFix) {
         ready,
         sneakoscope: { ok: await exists(`${root}/.sneakoscope`) },
         package: { bytes: pkgBytes, human: formatBytes(pkgBytes) },
-        repair: { sks_update: sksUpdate, setup: setupRepair, codex_config: configRepair, migration_journal: migrationJournal, global_sks_installs: globalSksInstallCleanup, agent_role_config: agentRoleConfigRepair, zellij: zellijRepair, context7: context7Repair, codex_startup: codexStartupRepair, startup_config: startupConfigRepair, context7_mcp: context7McpRepair, supabase_mcp: supabaseMcpRepair, doctor_transaction: doctorFixTransaction, doctor_dirty_plan: doctorDirtyPlan, doctor_postcheck: doctorFixPostcheck, codex_native: codexNativeRepair, doctor_native_capability: doctorNativeCapabilityRepair, command_aliases: commandAliasCleanup }
+        repair: { sks_update: sksUpdate, setup: setupRepair, codex_config: configRepair, migration_journal: migrationJournal, global_sks_installs: globalSksInstallCleanup, agent_role_config: agentRoleConfigRepair, zellij: zellijRepair, context7: context7Repair, codex_startup: codexStartupRepair, startup_config: startupConfigRepair, context7_mcp: context7McpRepair, supabase_mcp: supabaseMcpRepair, sks_menubar: sksMenuBar, doctor_transaction: doctorFixTransaction, doctor_dirty_plan: doctorDirtyPlan, doctor_postcheck: doctorFixPostcheck, codex_native: codexNativeRepair, doctor_native_capability: doctorNativeCapabilityRepair, command_aliases: commandAliasCleanup }
     };
     if (reportFile)
         await writeJsonReportFile(reportFile, result);
@@ -821,6 +859,16 @@ async function runDoctor(args = [], root, doctorFix) {
     }
     if (codexAppUi.next_action)
         console.log(`  next action: ${codexAppUi.next_action}`);
+    console.log('SKS Menu Bar:');
+    console.log(`  status: ${sksMenuBar.status || (sksMenuBar.ok ? 'ok' : 'blocked')}`);
+    if (sksMenuBar.app_path)
+        console.log(`  app: ${sksMenuBar.app_path}`);
+    if (sksMenuBar.launch_agent_path)
+        console.log(`  launch agent: ${sksMenuBar.launch_agent_path}`);
+    if (Array.isArray(sksMenuBar.blockers) && sksMenuBar.blockers.length)
+        console.log(`  blockers: ${sksMenuBar.blockers.join(', ')}`);
+    if (Array.isArray(sksMenuBar.warnings) && sksMenuBar.warnings.length)
+        console.log(`  warnings: ${sksMenuBar.warnings.join(', ')}`);
     console.log(`Provider: ${providerContext.provider || 'unknown'} ${providerContext.service_tier || ''} (${providerContext.source || 'unknown'}, ${providerContext.confidence || 'low'})`);
     const imagegenReady = imagegen.auth_readiness;
     if (imagegenReady) {
@@ -989,7 +1037,7 @@ function doctorPhaseIdsForProfile(profile) {
     ];
     if (profile === 'migration')
         return required;
-    const optional = ['supabase_mcp_repair', 'native_capability_repair'];
+    const optional = ['supabase_mcp_repair', 'native_capability_repair', 'sks_menubar'];
     if (profile === 'full' || profile === 'capabilities')
         return ['setup', ...required, ...optional];
     return [...required, ...optional];

package/dist/core/codex-app/sks-menubar.js

@@ -0,0 +1,458 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { ensureDir, exists, runProcess, which, writeJsonAtomic, writeTextAtomic } from '../fsx.js';
+const LABEL = 'com.sneakoscope.sks-menubar';
+const MENU_ITEMS = [
+    'Use codex-lb',
+    'Use ChatGPT OAuth',
+    'Set OpenRouter Key and GLM Profiles',
+    'Fast Check',
+    'SKS Version Check',
+    'Update SKS Now',
+    'Open Codex Settings',
+    'Restart Codex',
+    'Quit SKS Menu'
+];
+export async function installSksMenuBar(opts = {}) {
+    const apply = opts.apply === true;
+    const env = opts.env || process.env;
+    const home = path.resolve(opts.home || env.HOME || os.homedir());
+    const root = path.resolve(opts.root || process.cwd());
+    const installDir = path.join(home, '.codex', 'sks-menubar');
+    const appPath = path.join(installDir, 'SKSMenuBar.app');
+    const contentsPath = path.join(appPath, 'Contents');
+    const macosPath = path.join(contentsPath, 'MacOS');
+    const executablePath = path.join(macosPath, 'SKSMenuBar');
+    const sourcePath = path.join(installDir, 'SKSMenuBar.swift');
+    const infoPlistPath = path.join(contentsPath, 'Info.plist');
+    const actionScriptPath = path.join(installDir, 'sks-menubar-action.sh');
+    const launchAgentPath = path.join(home, 'Library', 'LaunchAgents', `${LABEL}.plist`);
+    const reportPath = path.join(root, '.sneakoscope', 'reports', 'sks-menubar.json');
+    const actions = [];
+    const warnings = [];
+    if (process.platform !== 'darwin') {
+        const result = {
+            schema: 'sks.codex-app-sks-menubar.v1',
+            ok: true,
+            apply,
+            status: 'unsupported_platform',
+            platform: process.platform,
+            app_path: null,
+            executable_path: null,
+            launch_agent_path: null,
+            action_script_path: null,
+            report_path: apply ? reportPath : null,
+            menu_items: MENU_ITEMS,
+            actions: [],
+            launch: { requested: false, method: 'none', ok: true },
+            blockers: [],
+            warnings: ['sks_menubar_requires_macos']
+        };
+        if (apply)
+            await writeJsonAtomic(reportPath, result).catch(() => undefined);
+        return result;
+    }
+    if (!apply) {
+        const installed = await exists(executablePath);
+        const launchAgent = await exists(launchAgentPath);
+        return {
+            schema: 'sks.codex-app-sks-menubar.v1',
+            ok: true,
+            apply,
+            status: 'planned',
+            platform: process.platform,
+            app_path: appPath,
+            executable_path: executablePath,
+            launch_agent_path: launchAgentPath,
+            action_script_path: actionScriptPath,
+            report_path: reportPath,
+            menu_items: MENU_ITEMS,
+            actions: installed ? ['menubar_app_present'] : ['menubar_app_install_available'],
+            launch: {
+                requested: false,
+                method: 'skipped',
+                ok: true
+            },
+            blockers: [],
+            warnings: launchAgent ? [] : ['launch_agent_not_installed_yet']
+        };
+    }
+    const swiftc = env.SKS_MENUBAR_SWIFTC || await which('swiftc').catch(() => null) || await fallbackTool('/usr/bin/swiftc');
+    const launchctl = env.SKS_MENUBAR_LAUNCHCTL || await which('launchctl').catch(() => null) || await fallbackTool('/bin/launchctl');
+    const open = env.SKS_MENUBAR_OPEN || await which('open').catch(() => null) || await fallbackTool('/usr/bin/open');
+    if (!swiftc)
+        return await blockedResult('swiftc_missing');
+    await ensureDir(installDir);
+    await ensureDir(macosPath);
+    await ensureDir(path.dirname(launchAgentPath));
+    const sksEntry = resolveSksEntry(opts.sksEntry);
+    await writeTextAtomic(actionScriptPath, actionScriptSource({ nodeBin: process.execPath, sksEntry }));
+    await fs.chmod(actionScriptPath, 0o755);
+    actions.push(`wrote ${actionScriptPath}`);
+    await writeTextAtomic(sourcePath, swiftMenuSource(actionScriptPath));
+    actions.push(`wrote ${sourcePath}`);
+    await writeTextAtomic(infoPlistPath, infoPlistSource());
+    actions.push(`wrote ${infoPlistPath}`);
+    const compile = await runProcess(swiftc, ['-framework', 'Cocoa', sourcePath, '-o', executablePath], {
+        timeoutMs: 60_000,
+        maxOutputBytes: 64 * 1024
+    }).catch((err) => ({ code: 1, stdout: '', stderr: err?.message || String(err) }));
+    if (compile.code !== 0) {
+        return await blockedResult('swift_compile_failed', String(compile.stderr || compile.stdout || '').trim());
+    }
+    await fs.chmod(executablePath, 0o755).catch(() => undefined);
+    actions.push(`compiled ${executablePath}`);
+    await writeTextAtomic(launchAgentPath, launchAgentSource(executablePath, installDir));
+    actions.push(`wrote ${launchAgentPath}`);
+    const launchRequested = opts.launch !== false && env.SKS_SKIP_SKS_MENUBAR_LAUNCH !== '1';
+    const launch = launchRequested && launchctl
+        ? await launchWithLaunchctl({ launchctl, open, appPath, executablePath, launchAgentPath })
+        : {
+            requested: launchRequested,
+            method: 'skipped',
+            ok: !launchRequested,
+            error: launchRequested ? 'launchctl_missing' : null
+        };
+    if (launchRequested && !launchctl)
+        warnings.push('launchctl_missing');
+    if (launch.method === 'open-fallback')
+        warnings.push('launchctl_bootstrap_failed_open_fallback_used');
+    const ok = launch.ok === true;
+    const result = {
+        schema: 'sks.codex-app-sks-menubar.v1',
+        ok,
+        apply,
+        status: ok
+            ? launch.requested === false || launch.method === 'skipped'
+                ? 'installed_launch_skipped'
+                : launch.method === 'open-fallback'
+                    ? 'installed_open_fallback'
+                    : 'installed'
+            : 'blocked',
+        platform: process.platform,
+        app_path: appPath,
+        executable_path: executablePath,
+        launch_agent_path: launchAgentPath,
+        action_script_path: actionScriptPath,
+        report_path: reportPath,
+        menu_items: MENU_ITEMS,
+        actions,
+        launch,
+        blockers: ok ? [] : [launch.error || 'sks_menubar_launch_failed'],
+        warnings
+    };
+    await writeJsonAtomic(reportPath, result).catch(() => undefined);
+    return result;
+    async function blockedResult(reason, detail) {
+        const result = {
+            schema: 'sks.codex-app-sks-menubar.v1',
+            ok: false,
+            apply,
+            status: 'blocked',
+            platform: process.platform,
+            app_path: appPath,
+            executable_path: executablePath,
+            launch_agent_path: launchAgentPath,
+            action_script_path: actionScriptPath,
+            report_path: reportPath,
+            menu_items: MENU_ITEMS,
+            actions,
+            launch: { requested: false, method: 'none', ok: false, error: detail || reason },
+            blockers: [reason],
+            warnings: detail ? [detail] : []
+        };
+        await writeJsonAtomic(reportPath, result).catch(() => undefined);
+        return result;
+    }
+}
+async function fallbackTool(candidate) {
+    return await exists(candidate).then((ok) => ok ? candidate : null).catch(() => null);
+}
+function resolveSksEntry(explicit) {
+    if (explicit)
+        return path.resolve(explicit);
+    const argvEntry = process.argv[1] ? path.resolve(process.argv[1]) : '';
+    return argvEntry || path.join(process.cwd(), 'dist', 'bin', 'sks.js');
+}
+function actionScriptSource(input) {
+    return `#!/bin/zsh
+set -e
+export PATH="/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:$PATH"
+NODE_BIN=${shellQuote(input.nodeBin)}
+SKS_ENTRY=${shellQuote(input.sksEntry)}
+if [ -x "$NODE_BIN" ] && [ -f "$SKS_ENTRY" ]; then
+  exec "$NODE_BIN" "$SKS_ENTRY" "$@"
+fi
+if command -v sks >/dev/null 2>&1; then
+  exec sks "$@"
+fi
+echo "SKS command not found. Run npm link or install Sneakoscope Codex, then run sks doctor --fix again." >&2
+exit 127
+`;
+}
+function swiftMenuSource(actionScriptPath) {
+    return `import Cocoa
+import Foundation
+
+let actionScript = ${swiftString(actionScriptPath)}
+
+func shellQuote(_ value: String) -> String {
+    return "'" + value.replacingOccurrences(of: "'", with: "'\\\\''") + "'"
+}
+
+func runDetached(_ executable: String, _ args: [String] = []) {
+    let process = Process()
+    process.executableURL = URL(fileURLWithPath: executable)
+    process.arguments = args
+    try? process.run()
+}
+
+func runInTerminal(_ command: String) {
+    let escaped = command
+        .replacingOccurrences(of: "\\\\", with: "\\\\\\\\")
+        .replacingOccurrences(of: "\\\"", with: "\\\\\\\"")
+    let script = "tell application \\"Terminal\\" to activate\\n" +
+        "tell application \\"Terminal\\" to do script \\"\(escaped)\\""
+    runDetached("/usr/bin/osascript", ["-e", script])
+}
+
+final class AppDelegate: NSObject, NSApplicationDelegate {
+    var statusItem: NSStatusItem!
+
+    func applicationDidFinishLaunching(_ notification: Notification) {
+        NSApp.setActivationPolicy(.accessory)
+        statusItem = NSStatusBar.system.statusItem(withLength: NSStatusItem.squareLength)
+        if let button = statusItem.button {
+            configureStatusButton(button)
+        }
+
+        let menu = NSMenu()
+        add(menu, "Use codex-lb", #selector(useCodexLb))
+        add(menu, "Use ChatGPT OAuth", #selector(useChatGptOAuth))
+        menu.addItem(NSMenuItem.separator())
+        add(menu, "Set OpenRouter Key and GLM Profiles", #selector(setOpenRouterKey))
+        add(menu, "Fast Check", #selector(fastCheck))
+        add(menu, "SKS Version Check", #selector(sksVersionCheck))
+        add(menu, "Update SKS Now", #selector(updateSksNow))
+        menu.addItem(NSMenuItem.separator())
+        add(menu, "Open Codex Settings", #selector(openCodexSettings))
+        add(menu, "Restart Codex", #selector(restartCodex))
+        menu.addItem(NSMenuItem.separator())
+        add(menu, "Quit SKS Menu", #selector(quit))
+        statusItem.menu = menu
+    }
+
+    func configureStatusButton(_ button: NSStatusBarButton) {
+        if #available(macOS 11.0, *), let image = NSImage(systemSymbolName: "s.circle.fill", accessibilityDescription: "SKS") {
+            image.isTemplate = true
+            button.image = image
+            button.imagePosition = .imageOnly
+            button.title = ""
+        } else {
+            button.title = "S"
+        }
+        button.toolTip = "SKS - Sneakoscope Codex settings"
+        button.setAccessibilityLabel("SKS")
+        button.setAccessibilityHelp("Open SKS menu")
+    }
+
+    func add(_ menu: NSMenu, _ title: String, _ selector: Selector) {
+        let item = NSMenuItem(title: title, action: selector, keyEquivalent: "")
+        item.target = self
+        menu.addItem(item)
+    }
+
+    func runSks(_ args: [String], tail: String = "echo; echo 'SKS command finished. Close this window when ready.'") {
+        let quoted = args.map(shellQuote).joined(separator: " ")
+        runInTerminal("\\(shellQuote(actionScript)) \\(quoted); \\(tail)")
+    }
+
+    @objc func useCodexLb() {
+        runSks(["codex-lb", "use-codex-lb"])
+    }
+
+    @objc func useChatGptOAuth() {
+        runSks(["codex-lb", "use-oauth"])
+    }
+
+    @objc func setOpenRouterKey() {
+        let command = "printf 'Paste OpenRouter key, then press Return: '; read -r key; printf '%s\\\\n' \\"$key\\" | \\(shellQuote(actionScript)) codex-app set-openrouter-key --api-key-stdin; \\(shellQuote(actionScript)) codex-app glm-profile install; echo; echo 'OpenRouter/GLM update finished. Restart Codex if the model picker was already open.'"
+        runInTerminal(command)
+    }
+
+    @objc func fastCheck() {
+        runSks(["codex-lb", "fast-check"])
+    }
+
+    @objc func sksVersionCheck() {
+        let sks = shellQuote(actionScript)
+        runInTerminal("echo 'SKS version'; \\(sks) --version; echo; echo 'Checking npm latest'; \\(sks) update check; echo; echo 'SKS version check finished. Close this window when ready.'")
+    }
+
+    @objc func updateSksNow() {
+        runSks(["update"], tail: "echo; echo 'SKS update finished. Close this window when ready.'")
+    }
+
+    @objc func openCodexSettings() {
+        runDetached("/usr/bin/open", ["codex://settings"])
+    }
+
+    @objc func restartCodex() {
+        runInTerminal("/usr/bin/osascript -e 'tell application \\"Codex\\" to quit'; sleep 1; /usr/bin/open -a Codex; echo 'Codex restart requested.'")
+    }
+
+    @objc func quit() {
+        NSApplication.shared.terminate(nil)
+    }
+}
+
+let app = NSApplication.shared
+let delegate = AppDelegate()
+app.delegate = delegate
+app.run()
+`;
+}
+function infoPlistSource() {
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>CFBundleExecutable</key>
+  <string>SKSMenuBar</string>
+  <key>CFBundleIdentifier</key>
+  <string>${LABEL}</string>
+  <key>CFBundleName</key>
+  <string>SKS Menu Bar</string>
+  <key>CFBundlePackageType</key>
+  <string>APPL</string>
+  <key>CFBundleVersion</key>
+  <string>1</string>
+  <key>LSUIElement</key>
+  <true/>
+</dict>
+</plist>
+`;
+}
+function launchAgentSource(executablePath, installDir) {
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${escapeXml(executablePath)}</string>
+  </array>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>StandardOutPath</key>
+  <string>${escapeXml(path.join(installDir, 'menubar.out.log'))}</string>
+  <key>StandardErrorPath</key>
+  <string>${escapeXml(path.join(installDir, 'menubar.err.log'))}</string>
+</dict>
+</plist>
+`;
+}
+async function launchWithLaunchctl(input) {
+    const uid = typeof process.getuid === 'function' ? process.getuid() : null;
+    const domain = uid === null ? 'gui' : `gui/${uid}`;
+    await runProcess(input.launchctl, ['bootout', `${domain}/${LABEL}`], { timeoutMs: 5_000, maxOutputBytes: 16 * 1024 }).catch(() => undefined);
+    await runProcess(input.launchctl, ['bootout', domain, input.launchAgentPath], { timeoutMs: 5_000, maxOutputBytes: 16 * 1024 }).catch(() => undefined);
+    await terminateExistingMenuBarProcess(input.executablePath);
+    const bootstrap = await runProcess(input.launchctl, ['bootstrap', domain, input.launchAgentPath], {
+        timeoutMs: 10_000,
+        maxOutputBytes: 32 * 1024
+    }).catch((err) => ({ code: 1, stdout: '', stderr: err?.message || String(err) }));
+    if (bootstrap.code === 0) {
+        const kickstart = await runProcess(input.launchctl, ['kickstart', '-k', `${domain}/${LABEL}`], {
+            timeoutMs: 5_000,
+            maxOutputBytes: 32 * 1024
+        }).catch((err) => ({ code: 1, stdout: '', stderr: err?.message || String(err) }));
+        if (kickstart.code !== 0) {
+            const printed = await waitForLaunchctlRunning(input.launchctl, `${domain}/${LABEL}`);
+            if (printed.running) {
+                return {
+                    requested: true,
+                    method: 'launchctl',
+                    ok: true,
+                    bootstrap_code: bootstrap.code,
+                    kickstart_code: kickstart.code,
+                    print_code: printed.code,
+                    error: null
+                };
+            }
+        }
+        return {
+            requested: true,
+            method: 'launchctl',
+            ok: kickstart.code === 0,
+            bootstrap_code: bootstrap.code,
+            kickstart_code: kickstart.code,
+            error: kickstart.code === 0 ? null : String(kickstart.stderr || kickstart.stdout || '').trim() || 'launchctl_kickstart_failed'
+        };
+    }
+    if (input.open) {
+        const opened = await runProcess(input.open, [input.appPath], {
+            timeoutMs: 10_000,
+            maxOutputBytes: 32 * 1024
+        }).catch((err) => ({ code: 1, stdout: '', stderr: err?.message || String(err) }));
+        return {
+            requested: true,
+            method: 'open-fallback',
+            ok: opened.code === 0,
+            bootstrap_code: bootstrap.code,
+            open_code: opened.code,
+            error: opened.code === 0
+                ? null
+                : String(opened.stderr || opened.stdout || bootstrap.stderr || bootstrap.stdout || '').trim() || 'sks_menubar_launch_failed'
+        };
+    }
+    return {
+        requested: true,
+        method: 'launchctl',
+        ok: false,
+        bootstrap_code: bootstrap.code,
+        error: String(bootstrap.stderr || bootstrap.stdout || '').trim() || 'launchctl_bootstrap_failed'
+    };
+}
+async function waitForLaunchctlRunning(launchctl, service) {
+    let lastCode = null;
+    for (let attempt = 0; attempt < 30; attempt += 1) {
+        const printed = await runProcess(launchctl, ['print', service], {
+            timeoutMs: 2_000,
+            maxOutputBytes: 64 * 1024
+        }).catch(() => ({ code: 1, stdout: '', stderr: '' }));
+        lastCode = printed.code;
+        if (printed.code === 0 && /\bstate = running\b|\bpid = \d+\b/.test(`${printed.stdout || ''}\n${printed.stderr || ''}`)) {
+            return { code: printed.code, running: true };
+        }
+        await new Promise((resolve) => setTimeout(resolve, 500));
+    }
+    return { code: lastCode, running: false };
+}
+async function terminateExistingMenuBarProcess(executablePath) {
+    const pkill = await which('pkill').catch(() => null) || await fallbackTool('/usr/bin/pkill');
+    if (!pkill)
+        return;
+    await runProcess(pkill, ['-f', executablePath], { timeoutMs: 5_000, maxOutputBytes: 8 * 1024 }).catch(() => undefined);
+    await new Promise((resolve) => setTimeout(resolve, 250));
+}
+function swiftString(value) {
+    return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+function shellQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function escapeXml(value) {
+    return value
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&apos;');
+}
+//# sourceMappingURL=sks-menubar.js.map

package/dist/core/codex-app.js

@@ -457,7 +457,11 @@ function codexNativeSksMenuStatus() {
         status: 'unsupported_official_api',
         requested_label: 'SKS',
         requested_position: 'between Window and Help',
+        companion_supported: process.platform === 'darwin',
+        companion_position: 'right macOS menu bar status item',
+        companion_install_command: 'sks doctor --fix',
         alternatives: [
+            'sks doctor --fix',
             'sks codex-lb use-codex-lb',
             'sks codex-lb use-oauth',
             'sks codex-app set-openrouter-key --api-key-stdin',
@@ -559,7 +563,7 @@ export function codexAppGuidance({ appInstalled, codex, mcpList, featureList, re
         lines.push('Codex App git actions are enabled for Commit, Push, Commit and Push, and PR flows; SKS hooks treat those app metadata actions as lightweight git UI actions.');
     }
     if (nativeSksMenu?.supported === false) {
-        lines.push('Native macOS SKS menu is not installed because Codex App does not expose a documented third-party native menu extension API; use `sks codex-lb use-codex-lb`, `sks codex-lb use-oauth`, and `sks codex-app set-openrouter-key --api-key-stdin` instead.');
+        lines.push('Codex App does not expose a documented third-party API for inserting SKS between Window and Help, so SKS uses a right-side macOS menu bar companion instead. Run `sks doctor --fix` to install or refresh it.');
     }
     if (appInstalled && (!computerUseReady || !browserToolReady)) {
         lines.push('Open Codex App settings and enable recommended MCP/plugin tools. Codex CLI 0.130.0+ remote-control/app-server sessions can pick up config changes live; restart older CLI/TUI sessions.');

package/dist/core/commands/basic-cli.js

@@ -113,24 +113,29 @@ export async function updateCheckCommand(args = []) {
         return printJson(result);
     console.log(`${sksTextLogo()}\n\n${formatSksUpdateCheckText(result)}`);
 }
-export async function updateCommand(sub = 'check', args = []) {
-    const action = String(sub || 'check').toLowerCase();
+export async function updateCommand(sub = 'now', args = []) {
+    let action = String(sub || 'now').toLowerCase();
+    let effectiveArgs = args;
+    if (action.startsWith('-')) {
+        effectiveArgs = [String(sub), ...args];
+        action = 'now';
+    }
     if (action === 'check' || action === 'status')
-        return updateCheckCommand(args);
+        return updateCheckCommand(effectiveArgs);
     if (action !== 'now') {
-        console.error('Usage: sks update check|now [--version <version>] [--json] [--dry-run]');
+        console.error('Usage: sks update [check|now] [--version <version>] [--json] [--dry-run]');
         process.exitCode = 1;
         return;
     }
     const root = await projectRoot();
     const result = await withSecretPreservationGuard(root, 'update-now', async () => runSksUpdateNow({
-        version: valueAfter(args, '--version') || valueAfter(args, '-v'),
-        dryRun: flag(args, '--dry-run'),
+        version: valueAfter(effectiveArgs, '--version') || valueAfter(effectiveArgs, '-v'),
+        dryRun: flag(effectiveArgs, '--dry-run'),
         projectRoot: root,
         timeoutMs: 10 * 60 * 1000,
         maxOutputBytes: 128 * 1024
     }));
-    if (flag(args, '--json'))
+    if (flag(effectiveArgs, '--json'))
         return printJson(result);
     console.log(`${sksTextLogo()}\n`);
     console.log(`SKS update ${result.status}`);
@@ -144,6 +149,8 @@ export async function updateCommand(sub = 'check', args = []) {
         console.log(`New version: ${result.new_version}`);
     if (result.project_receipt)
         console.log(`Migration receipt: ${result.project_receipt.root} (${result.migration_current ? 'current' : 'not current'})`);
+    if (result.sks_menubar)
+        console.log(`SKS menu bar: ${result.sks_menubar.status}${result.sks_menubar.app_path ? ` (${result.sks_menubar.app_path})` : ''}`);
     for (const stage of result.stages || [])
         console.log(`Stage ${stage.id}: ${stage.ok ? 'ok' : 'failed'} ${stage.status}`);
     if (result.error)

package/dist/core/doctor/doctor-dirty-planner.js

@@ -89,6 +89,8 @@ function phaseInputFiles(id) {
         return ['src/core/doctor/codex-startup-config-repair.ts', '.codex/config.toml'];
     if (id.includes('supabase'))
         return ['src/core/doctor/supabase-mcp-repair.ts', '.codex/config.toml'];
+    if (id.includes('menubar'))
+        return ['src/core/codex-app/sks-menubar.ts', 'src/commands/doctor.ts', 'package.json'];
     if (id.includes('skill'))
         return ['.agents/skills', 'src/scripts/skill-registry-ledger-check.ts'];
     if (id.includes('native'))

package/dist/core/doctor/doctor-readiness-matrix.js

@@ -60,6 +60,8 @@ export function buildDoctorReadinessMatrix(input = {}) {
         blockers.add('codex_app_fast_ui_repair_requires_confirmation');
     if (input.codex_app_ui?.fast_selector === 'repaired')
         warnings.add('codex_app_fast_selector_repaired_restart_app_if_needed');
+    if (input.sks_menubar?.ok === false)
+        warnings.add(`sks_menubar_${input.sks_menubar?.status || 'blocked'}`);
     const codex0138Doctor = input.codex_0138_doctor || null;
     if (codex0138Doctor?.ok === false)
         for (const blocker of normalizeList(codex0138Doctor.blockers))
@@ -148,6 +150,7 @@ export function buildDoctorReadinessMatrix(input = {}) {
         codex_app_harness_matrix: codexAppHarness,
         fast_mode_ready: input.fast_mode_ready !== false,
         codex_app_ui: input.codex_app_ui || null,
+        sks_menubar: input.sks_menubar || null,
         hooks_ready: input.hooks_ready !== false,
         codex_app_ready: input.codex_app?.ok === true,
         codex_app_required_for_cli: false,
@@ -205,6 +208,7 @@ function buildRepairReadiness(input = {}) {
     add('context7_repair', input.context7_repair, true);
     add('context7_mcp_repair', input.context7_mcp_repair, true);
     add('supabase_mcp_repair', input.supabase_mcp_repair, input.supabase_mcp_repair?.ready_blocking === true);
+    add('sks_menubar', input.sks_menubar, false);
     add('command_alias_cleanup', input.command_aliases, true);
     add('native_capability_repair', input.doctor_native_capability, false);
     if (input.doctor_fix_transaction) {

package/dist/core/fsx.js

@@ -5,7 +5,7 @@ import os from 'node:os';
 import crypto from 'node:crypto';
 import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
-export const PACKAGE_VERSION = '4.7.3';
+export const PACKAGE_VERSION = '4.8.0';
 export const DEFAULT_PROCESS_TAIL_BYTES = 256 * 1024;
 export const DEFAULT_PROCESS_TIMEOUT_MS = 30 * 60 * 1000;
 export function nowIso() {

package/dist/core/managed-assets/managed-assets-manifest.js

@@ -1,6 +1,6 @@
 import { REQUIRED_CODEX_MODEL } from '../codex-model-guard.js';
 export const MANAGED_ASSET_SCHEMA_VERSION = 1;
-export const MANAGED_ASSET_VERSION = '4.7.3';
+export const MANAGED_ASSET_VERSION = '4.8.0';
 export const MANAGED_ASSET_MARKER = 'SKS-MANAGED-ASSET';
 export const MANAGED_AGENT_ROLES = Object.freeze([
     role('sks-explorer', 'analysis-scout.toml', 'analysis_scout', 'SKS analysis scout for bounded read/write slices retained for stale Codex agent-role config repair.', 'workspace-write', ['analysis-scout', 'analysis_scout']),

package/dist/core/routes.js

@@ -699,7 +699,7 @@ export const COMMAND_CATALOG = [
     { name: 'quickstart', usage: 'sks quickstart', description: 'Show the shortest safe setup and verification flow.' },
     { name: 'bootstrap', usage: 'sks bootstrap [--install-scope global|project] [--local-only] [--json]', description: 'Initialize the current project, install SKS Codex App files/skills, check Context7/Codex App/Zellij, and print ready true/false.' },
     { name: 'root', usage: 'sks root [--json]', description: 'Show whether SKS is using a project root or the per-user global SKS runtime root.' },
-    { name: 'update', usage: 'sks update check|now [--version <version>] [--json] [--dry-run]', description: 'Check for SKS updates or install the requested package version through npm global mode.' },
+    { name: 'update', usage: 'sks update [check|now] [--version <version>] [--json] [--dry-run]', description: 'Check npm for the latest SKS release and update the global package by default; use `check` for status-only.' },
     { name: 'deps', usage: 'sks deps check [--json] [--yes]', description: 'Check Node/npm, Codex CLI, and Zellij readiness; pass --yes to repair missing Codex CLI/Zellij tooling when supported.' },
     { name: 'codex', usage: 'sks codex compatibility|version|doctor|schema|0.142 [--json]', description: 'Check Codex CLI rust-v0.142.0 compatibility, installed version, 0.142 manifest/capability evidence, inherited legacy baselines, and vendored hook schema snapshot freshness.' },
     { name: 'codex-app', usage: 'sks codex-app [check|glm-profile install|set-openrouter-key --api-key-stdin|product-design|chrome-extension|pat status|remote-control]', description: 'Check Codex App install, GLM/OpenRouter model profile visibility, codex-lb key-entry guidance, Product Design plugin readiness, Codex Chrome Extension web verification readiness, PAT-safe status, first-party MCP/plugin readiness, and Codex CLI 0.130.0+ remote-control availability.' },

package/dist/core/update-check.js

@@ -4,6 +4,7 @@ import { PACKAGE_VERSION, packageRoot, readJson, runProcess, which } from './fsx
 import { createRequestedScopeContract } from './safety/requested-scope-contract.js';
 import { guardedPackageInstall, guardContextForRoute } from './safety/mutation-guard.js';
 import { isUpdateMigrationReceiptCurrent, resolveInstalledSksEntrypoint, runPackageLocalDoctor, writeProjectUpdateMigrationReceipt } from './update/update-migration-state.js';
+import { installSksMenuBar } from './codex-app/sks-menubar.js';
 const DEFAULT_REGISTRY = 'https://registry.npmjs.org/';
 export async function runSksUpdateCheck(options = {}) {
     const packageName = options.packageName || 'sneakoscope';
@@ -164,6 +165,9 @@ export async function runSksUpdateNow(options = {}) {
         }).catch(() => null);
         const migrationCurrent = isUpdateMigrationReceiptCurrent(receipt);
         stage('project_receipt', migrationCurrent, migrationCurrent ? 'current' : 'failed', { root: projectReceiptRoot });
+        const sksMenuBar = migrationCurrent
+            ? await installUpdateSksMenuBar({ root: projectReceiptRoot, env, stage })
+            : null;
         return buildUpdateNowResult({
             packageName,
             from: check.current,
@@ -185,19 +189,14 @@ export async function runSksUpdateNow(options = {}) {
             newVersionDoctor: null,
             projectReceipt: receipt,
             migrationCurrent,
+            sksMenuBar,
             stages,
             error: null
         });
     }
-    const oldVersionDoctor = await runPackageLocalDoctor({
-        root: projectReceiptRoot,
-        args: ['doctor', '--fix', '--yes', '--profile', 'migration', '--machine-only', '--report-file', path.join(projectReceiptRoot, '.sneakoscope', 'update', `old-version-doctor-${Date.now()}.json`)],
-        env,
-        timeoutMs: 15_000,
-        maxOutputBytes: 32 * 1024
-    });
-    stage('old_version_doctor_preflight', oldVersionDoctor.ok, oldVersionDoctor.status, { entrypoint: oldVersionDoctor.entrypoint, exit_code: oldVersionDoctor.exit_code });
-    if (!oldVersionDoctor.ok && env.SKS_UPDATE_SKIP_OLD_DOCTOR_PREFLIGHT !== '1') {
+    if (options.dryRun) {
+        stage('old_version_doctor_preflight', true, 'skipped_dry_run', { reason: 'dry_run_does_not_run_doctor_fix' });
+        stage('npm_install', true, 'dry_run', { command });
         return buildUpdateNowResult({
             packageName,
             from: check.current,
@@ -210,21 +209,32 @@ export async function runSksUpdateNow(options = {}) {
             cwd,
             registry,
             globalRoot,
-            status: 'failed',
-            ok: false,
+            status: 'dry_run',
+            ok: true,
             installCode: null,
-            oldVersionDoctor,
+            oldVersionDoctor: null,
             newBinary: null,
             newVersion: null,
             newVersionDoctor: null,
             projectReceipt: null,
             migrationCurrent: false,
             stages,
-            error: oldVersionDoctor.error || 'old-version Doctor preflight failed'
+            error: null
         });
     }
-    if (options.dryRun) {
-        stage('npm_install', true, 'dry_run', { command });
+    const oldDoctorTimeoutOverride = Number.parseInt(env.SKS_UPDATE_OLD_DOCTOR_TIMEOUT_MS || '', 10);
+    const oldDoctorTimeoutMs = Number.isFinite(oldDoctorTimeoutOverride) && oldDoctorTimeoutOverride > 0
+        ? oldDoctorTimeoutOverride
+        : 60_000;
+    const oldVersionDoctor = await runPackageLocalDoctor({
+        root: projectReceiptRoot,
+        args: ['doctor', '--fix', '--yes', '--profile', 'migration', '--machine-only', '--report-file', path.join(projectReceiptRoot, '.sneakoscope', 'update', `old-version-doctor-${Date.now()}.json`)],
+        env,
+        timeoutMs: oldDoctorTimeoutMs,
+        maxOutputBytes: 32 * 1024
+    });
+    stage('old_version_doctor_preflight', oldVersionDoctor.ok, oldVersionDoctor.status, { entrypoint: oldVersionDoctor.entrypoint, exit_code: oldVersionDoctor.exit_code, timeout_ms: oldDoctorTimeoutMs });
+    if (!oldVersionDoctor.ok && env.SKS_UPDATE_SKIP_OLD_DOCTOR_PREFLIGHT !== '1') {
         return buildUpdateNowResult({
             packageName,
             from: check.current,
@@ -237,8 +247,8 @@ export async function runSksUpdateNow(options = {}) {
             cwd,
             registry,
             globalRoot,
-            status: 'dry_run',
-            ok: true,
+            status: 'failed',
+            ok: false,
             installCode: null,
             oldVersionDoctor,
             newBinary: null,
@@ -247,7 +257,7 @@ export async function runSksUpdateNow(options = {}) {
             projectReceipt: null,
             migrationCurrent: false,
             stages,
-            error: null
+            error: oldVersionDoctor.error || 'old-version Doctor preflight failed'
         });
     }
     const mutationLedgerRoot = env.SKS_MUTATION_LEDGER_ROOT || packageRoot();
@@ -277,6 +287,7 @@ export async function runSksUpdateNow(options = {}) {
     let newVersionDoctor = null;
     let projectReceipt = null;
     let migrationCurrent = false;
+    let sksMenuBar = null;
     if (installOk) {
         newBinary = await resolveInstalledSksEntrypoint({ packageName, globalRoot, env });
         stage('resolve_new_package_local_binary', Boolean(newBinary), newBinary ? 'resolved' : 'missing', { new_binary: newBinary });
@@ -310,6 +321,8 @@ export async function runSksUpdateNow(options = {}) {
             }).catch(() => null);
             migrationCurrent = isUpdateMigrationReceiptCurrent(projectReceipt);
             stage('project_receipt', migrationCurrent, migrationCurrent ? 'current' : 'failed', { root: projectReceiptRoot });
+            if (migrationCurrent)
+                sksMenuBar = await installUpdateSksMenuBar({ root: projectReceiptRoot, env, stage });
         }
     }
     const ok = installOk && Boolean(newBinary) && newVersionDoctor?.ok === true && migrationCurrent;
@@ -334,6 +347,7 @@ export async function runSksUpdateNow(options = {}) {
         newVersionDoctor,
         projectReceipt,
         migrationCurrent,
+        sksMenuBar,
         stages,
         error: ok ? null : updateNowError(install, newBinary, newVersionDoctor, migrationCurrent)
     });
@@ -500,10 +514,45 @@ function buildUpdateNowResult(input) {
         new_version_doctor: input.newVersionDoctor,
         project_receipt: input.projectReceipt,
         migration_current: input.migrationCurrent,
+        sks_menubar: input.sksMenuBar || null,
         stages: input.stages,
         error: input.error
     };
 }
+async function installUpdateSksMenuBar(input) {
+    if (input.env.SKS_UPDATE_SKIP_SKS_MENUBAR === '1') {
+        input.stage('sks_menubar', true, 'skipped', { reason: 'SKS_UPDATE_SKIP_SKS_MENUBAR=1' });
+        return null;
+    }
+    const result = await installSksMenuBar({
+        root: input.root,
+        apply: true,
+        launch: true,
+        env: input.env
+    }).catch((err) => ({
+        schema: 'sks.codex-app-sks-menubar.v1',
+        ok: false,
+        apply: true,
+        status: 'blocked',
+        platform: process.platform,
+        app_path: null,
+        executable_path: null,
+        launch_agent_path: null,
+        action_script_path: null,
+        report_path: path.join(input.root, '.sneakoscope', 'reports', 'sks-menubar.json'),
+        menu_items: [],
+        actions: [],
+        launch: { requested: true, method: 'none', ok: false, error: err?.message || String(err) },
+        blockers: [err?.message || String(err)],
+        warnings: []
+    }));
+    input.stage('sks_menubar', result.ok !== false, result.status, {
+        app_path: result.app_path,
+        launch_agent_path: result.launch_agent_path,
+        launch: result.launch
+    });
+    return result;
+}
 async function detectNpmGlobalRoot(npmBin, env, opts = {}) {
     const result = await runProcess(npmBin, ['root', '--global', '--silent'], {
         env,

package/dist/core/version.js

@@ -1,2 +1,2 @@
-export const PACKAGE_VERSION = '4.7.3';
+export const PACKAGE_VERSION = '4.8.0';
 //# sourceMappingURL=version.js.map

package/dist/scripts/sks-menubar-install-check.js

@@ -0,0 +1,67 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { installSksMenuBar } from '../core/codex-app/sks-menubar.js';
+const temp = await fs.mkdtemp(path.join(os.tmpdir(), 'sks-menubar-check-'));
+const result = await installSksMenuBar({
+    apply: true,
+    launch: false,
+    home: temp,
+    root: temp,
+    sksEntry: path.join(process.cwd(), 'dist', 'bin', 'sks.js')
+});
+const executableExists = result.executable_path ? await exists(result.executable_path) : false;
+const launchAgentExists = result.launch_agent_path ? await exists(result.launch_agent_path) : false;
+const actionScriptExists = result.action_script_path ? await exists(result.action_script_path) : false;
+const generatedSourcePath = result.app_path ? path.join(path.dirname(result.app_path), 'SKSMenuBar.swift') : null;
+const generatedSource = generatedSourcePath ? await fs.readFile(generatedSourcePath, 'utf8').catch(() => '') : '';
+const hasVisibleIconSource = generatedSource.includes('NSStatusItem.squareLength')
+    && generatedSource.includes('s.circle.fill')
+    && generatedSource.includes('configureStatusButton');
+const expectedMenuItems = [
+    'Use codex-lb',
+    'Use ChatGPT OAuth',
+    'Set OpenRouter Key and GLM Profiles',
+    'Fast Check',
+    'SKS Version Check',
+    'Update SKS Now'
+];
+const missingExpectedItems = expectedMenuItems.filter((item) => !result.menu_items.includes(item));
+const hasExpectedItems = missingExpectedItems.length === 0;
+const ok = process.platform === 'darwin'
+    ? result.ok === true
+        && result.status === 'installed_launch_skipped'
+        && executableExists
+        && launchAgentExists
+        && actionScriptExists
+        && hasExpectedItems
+        && hasVisibleIconSource
+    : result.ok === true && result.status === 'unsupported_platform';
+const report = {
+    schema: 'sks.sks-menubar-install-check.v1',
+    ok,
+    temp,
+    result,
+    executable_exists: executableExists,
+    launch_agent_exists: launchAgentExists,
+    action_script_exists: actionScriptExists,
+    generated_source_path: generatedSourcePath,
+    has_visible_icon_source: hasVisibleIconSource,
+    expected_menu_items: expectedMenuItems,
+    missing_expected_items: missingExpectedItems,
+    has_expected_items: hasExpectedItems,
+    blockers: ok ? [] : ['sks_menubar_install_check_failed']
+};
+console.log(JSON.stringify(report, null, 2));
+if (!ok)
+    process.exit(1);
+async function exists(file) {
+    try {
+        await fs.access(file);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=sks-menubar-install-check.js.map

package/dist/scripts/update-default-command-check.js

@@ -0,0 +1,28 @@
+import fs from 'node:fs';
+function assertGate(ok, message, detail) {
+    if (!ok) {
+        console.error(JSON.stringify({ schema: 'sks.update-default-command-check.v1', ok: false, message, detail }, null, 2));
+        process.exit(1);
+    }
+}
+const registry = fs.readFileSync('src/cli/command-registry.ts', 'utf8');
+const basicCli = fs.readFileSync('src/core/commands/basic-cli.ts', 'utf8');
+const update = fs.readFileSync('src/core/update-check.ts', 'utf8');
+const routes = fs.readFileSync('src/core/routes.ts', 'utf8');
+assertGate(registry.includes("subcommand(() => import(basicModule), 'updateCommand', 'dist/core/commands/basic-cli.js', 'now')"), 'bare sks update must default to update now');
+assertGate(basicCli.includes("export async function updateCommand(sub: any = 'now'"), 'updateCommand default must be now');
+assertGate(basicCli.includes("action.startsWith('-')") && basicCli.includes('effectiveArgs = [String(sub), ...args]'), 'sks update --json/--dry-run must be treated as update now with flags');
+assertGate(update.includes('installSksMenuBar') && update.includes('sks_menubar'), 'update now must refresh the SKS menu bar companion stage');
+assertGate(routes.includes('sks update [check|now]'), 'command catalog must document bare sks update as the default update path');
+console.log(JSON.stringify({
+    schema: 'sks.update-default-command-check.v1',
+    ok: true,
+    checks: [
+        'registry_default_now',
+        'basic_cli_default_now',
+        'flag_first_default_now',
+        'update_menubar_stage',
+        'command_catalog_usage'
+    ]
+}, null, 2));
+//# sourceMappingURL=update-default-command-check.js.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sneakoscope",
   "displayName": "ㅅㅋㅅ",
-  "version": "4.7.3",
+  "version": "4.8.0",
   "description": "Sneakoscope Codex: fast proof-first Codex trust layer with image-based Voxel TriWiki.",
   "type": "module",
   "homepage": "https://github.com/mandarange/Sneakoscope-Codex#readme",
@@ -168,6 +168,8 @@
     "codex:0.135-compat:require-real": "node ./dist/scripts/codex-0-135-compat-check.js --require-real",
     "doctor:codex-doctor-parity": "node ./dist/scripts/doctor-codex-doctor-parity-check.js",
     "doctor:codex-doctor-parity:actual": "node ./dist/scripts/doctor-codex-doctor-parity-check.js --actual-codex",
+    "doctor:sks-menubar": "node ./dist/scripts/sks-menubar-install-check.js",
+    "update:default-command": "node ./dist/scripts/update-default-command-check.js",
     "codex:permission-profiles": "node ./dist/scripts/codex-permission-profiles-check.js",
     "codex:legacy-profile-consumers-removed": "node ./dist/scripts/codex-legacy-profile-consumers-removed-check.js",
     "terminal:keyboard-enhancement-safety": "node ./dist/scripts/terminal-keyboard-enhancement-safety-check.js",