sneakoscope 0.6.62 → 0.6.64

package/README.md

@@ -2,120 +2,397 @@
 
 ![](https://github.com/mandarange/Sneakoscope-Codex/raw/dev/docs/assets/sneakoscope-codex-logo.png)
 
-Codex CLI/App harness for `$` routes, cmux-native CLI workspaces, Team/Ralph/QA/Research, Context7, Honest Mode, DB safety, TriWiki, Codex App skills, and release readiness.
+Sneakoscope Codex (`sks`, displayed as `ㅅㅋㅅ`) is a Codex CLI/App harness for repeatable agent workflows. It adds terminal commands, Codex App `$` prompt commands, cmux-native CLI workspaces, Team/Ralph/QA/Research routes, Context7 evidence checks, DB safety, TriWiki context tracking, Honest Mode, and release-readiness gates.
 
-Install: `npm i -g sneakoscope && sks bootstrap`
-Fallback: `npx -y -p sneakoscope sks bootstrap`
-Project: `npm i -D sneakoscope && npx sks setup --install-scope project`
+## Quick Start
 
-Discover: `sks commands`, `sks dollar-commands`, `sks usage <topic>`
-Check: `sks deps check`, `sks doctor --fix`, `sks selftest --mock`
+Install globally, initialize the current project, then open the cmux runtime:
 
-## What It Adds
+```sh
+npm i -g sneakoscope
+sks bootstrap
+sks
+```
+
+If you only want a one-shot run without keeping `sks` installed globally:
+
+```sh
+npx -y -p sneakoscope sks bootstrap
+```
 
-Sneakoscope (`sks`, displayed as `ㅅㅋㅅ`) wraps Codex with a repeatable control surface:
+For a repo-local install:
+
+```sh
+npm i -D sneakoscope
+npx sks setup --install-scope project
+```
+
+Check that the install is usable:
+
+```sh
+sks deps check
+sks codex-app check
+sks dollar-commands
+sks selftest --mock
+```
+
+## What Sneakoscope Adds
 
 | Area | What it does |
 | --- | --- |
-| Codex App commands | Installs generated skills so `$Team`, `$DFix`, `$QA-LOOP`, `$Ralph`, `$DB`, `$Wiki`, `$Help`, and related routes are discoverable in prompt workflows. |
-| CLI commands | Provides `sks commands`, `sks dollar-commands`, `sks usage <topic>`, bootstrap, setup, doctor, deps, selftest, wiki, team, QA, Ralph, DB, and GX commands. |
-| cmux runtime | Opens Codex CLI through `sks`/`sks cmux`, exposes one-shot full-access high mode with `sks --mad --high`, and opens Team missions with cmux multi-line agent lanes when cmux is available. |
-| Team orchestration | Routes substantial code work through ambiguity removal, scouts, TriWiki refresh, debate, consensus, concrete runtime task graph/inboxes, implementation, review, integration, reflection, and Honest Mode. |
-| Ralph | Seals a decision contract up front, then continues without more user questions by using the agreed decision ladder. |
-| QA loop | Dogfoods UI/API behavior with safety boundaries, evidence capture, safe remediation, and focused rechecks. |
-| TriWiki | Keeps `.sneakoscope/wiki/context-pack.json` as the context SSOT, with refresh, pack, prune, validate, active attention ranking, and hydratable source-backed claims. |
-| Context7 | Requires current external library/API/framework docs for routes whose correctness depends on live package or platform behavior. |
-| DB safety | Treats SQL, migrations, Supabase, RLS, and destructive operations as high risk; defaults to inspection and guarded local/branch-safe migration work. |
-| Honest Mode | Finishes work with a claim/evidence pass that separates verified facts, unsupported claims, blocked checks, and not-applicable items. |
-| GX visual context | Generates deterministic visual context cartridges for structured visual review and drift checks. |
-| Research loops | Supports Research and AutoResearch workflows with hypotheses, experiments, falsification, novelty ledgers, SEO/GEO, and evidence-backed conclusions. |
-| Release hygiene | Checks versioning, changelog, package contents, tarball size, syntax, selftests, and dry-run packaging before publish. |
+| CLI runtime | `sks`, `sks cmux`, and `sks --mad --high` open Codex CLI in a cmux workspace. |
+| Codex App commands | Installs generated skills so `$Team`, `$DFix`, `$QA-LOOP`, `$Ralph`, `$DB`, `$Wiki`, `$Help`, and related routes are visible in prompt workflows. |
+| Team orchestration | Runs substantial work through ambiguity handling, scouts, TriWiki refresh, debate, runtime task graphs, worker inboxes, implementation, review, cleanup, reflection, and Honest Mode. |
+| QA loop | Dogfoods UI/API behavior with safety gates, Browser/Computer evidence, safe fixes, and rechecks. |
+| Ralph | Clarifies once, seals a decision contract, then continues without repeatedly asking the user. |
+| TriWiki | Maintains `.sneakoscope/wiki/context-pack.json` as the context SSOT with `attention.use_first` and `attention.hydrate_first`. |
+| Context7 | Requires current docs for external packages, APIs, MCPs, SDKs, and framework/runtime behavior when correctness depends on current guidance. |
+| DB safety | Treats SQL, migrations, Supabase, RLS, and destructive operations as high risk. |
+| Release hygiene | Checks versioning, changelog, package contents, tarball size, syntax, selftests, and dry-run publishing. |
 
-## Prompt `$` Commands
+## Requirements
 
-Use these inside Codex App or another agent prompt. They are prompt commands, not terminal commands.
+- Node.js `>=20.11`
+- npm
+- Codex CLI for terminal workflows
+- Codex App for app-facing workflows and first-party Browser Use / Computer Use parity
+- cmux for the CLI-first runtime
+- Context7 MCP for current-docs-gated routes
 
-| Prompt | Purpose |
-| --- | --- |
-| `$Team` | Default route for code-changing work and substantial implementation. |
-| `$From-Chat-IMG` | Team alias for chat screenshot plus original attachment intake. |
-| `$DFix` | Tiny design/content fixes: labels, copy, colors, spacing, translation. |
-| `$Answer` | Answer-only route when no implementation should start. |
-| `$SKS` | Setup, status, usage, and Sneakoscope workflow help. |
-| `$QA-LOOP` | UI/API dogfooding, safe fixes, and rechecks. |
-| `$Ralph` | Clarify once, seal a decision contract, then execute. |
-| `$Research` | Frontier-style research with hypotheses and falsification. |
-| `$AutoResearch` | Iterative improve-test-keep/discard optimization loop. |
-| `$DB` | Database and Supabase safety checks. |
-| `$MAD-SKS` | Explicit scoped DB authorization modifier; combine it with another `$` route when needed, widened Supabase MCP permissions last only for that invocation, and table deletion requires a short user confirmation timeout. |
-| `$GX` | Deterministic visual context generation and validation. |
-| `$Wiki` | TriWiki refresh, pack, prune, validate, and maintenance. |
-| `$Help` | Installed command and workflow explanation. |
-
-Run `sks dollar-commands` to verify the terminal and Codex App command surfaces agree.
-
-## Terminal Examples
+On macOS, `sks --mad --high` can install cmux through Homebrew when cmux is missing. You can also install it manually:
+
+```sh
+brew tap manaflow-ai/cmux
+brew install --cask cmux
+```
+
+If the CLI is not on `PATH`, SKS also checks the app bundle path:
+
+```sh
+/Applications/cmux.app/Contents/Resources/bin/cmux
+```
+
+## Installation
+
+### Global Install
+
+Use this when you want `sks` available from any repo:
+
+```sh
+npm i -g sneakoscope
+sks bootstrap
+```
+
+`sks bootstrap` initializes the current project, installs Codex App skills/hooks/config, checks Context7/Codex App/cmux readiness, and prints a ready status.
+
+### One-Shot Install
+
+Use this when you do not want to keep a global install:
 
 ```sh
+npx -y -p sneakoscope sks bootstrap
+```
+
+`npx` fetches the package into npm's cache and runs the binary for that command. This is useful for first-time setup or CI-style verification.
+
+### Project Install
+
+Use this when a repo should pin Sneakoscope as a development dependency:
+
+```sh
+npm i -D sneakoscope
+npx sks setup --install-scope project
+```
+
+Project installs are useful when a team wants a repeatable harness version checked through `package-lock.json`.
+
+### Source Checkout
+
+Use this when developing Sneakoscope itself:
+
+```sh
+git clone https://github.com/mandarange/Sneakoscope-Codex.git
+cd Sneakoscope-Codex
+npm install
+npm install -g .
+sks --version
+```
+
+## Terminal CLI Usage
+
+Use terminal commands when you want to inspect, set up, verify, or start a CLI-first workspace.
+
+### Discovery
+
+```sh
+sks commands
 sks usage install
 sks usage team
-sks usage qa-loop
 sks usage codex-app
+sks dollar-commands
+sks --version
+```
+
+### Setup And Repair
+
+```sh
+sks bootstrap
+sks deps check
+sks deps install cmux
+sks codex-app check
+sks doctor --fix
+sks fix-path
+```
+
+### Open Codex CLI With cmux
+
+```sh
+sks
 sks cmux check
+sks cmux status --once
+```
+
+`sks` opens a cmux workspace for Codex CLI when running in an interactive terminal. `sks cmux check` is diagnostic and prints readiness without starting a workspace.
+
+### MAD High cmux Workspace
+
+```sh
 sks --mad --high
-sks setup --install-scope project
+```
+
+This creates/uses the `sks-mad-high` Codex profile for a one-shot full-access, high-reasoning cmux workspace. It is scoped to that explicit command and does not change normal SKS/DB safety defaults.
+
+### Team Missions
+
+```sh
+sks team "implement this feature" executor:3 reviewer:1
+sks team watch latest
+sks team status latest
+sks team log latest
+```
+
+Team mode prepares the mission, records live events, compiles runtime tasks and worker inboxes, and opens cmux live lanes when cmux is available.
+
+### QA, Ralph, Research, DB, Wiki, GX
+
+```sh
+sks qa-loop prepare "http://localhost:3000"
+sks qa-loop run latest --max-cycles 2
+sks ralph prepare "migrate this workflow without asking after prepare"
+sks research prepare "evaluate this approach"
+sks db scan --json
 sks wiki refresh
 sks wiki validate .sneakoscope/wiki/context-pack.json
-sks versioning status
+sks gx init homepage
+sks gx render homepage --format html
 ```
 
-Route examples:
+## Codex App Usage
+
+Sneakoscope has two surfaces:
+
+- Terminal commands such as `sks deps check`, `sks team "task"`, and `sks --mad --high`
+- Codex App prompt commands such as `$Team`, `$DFix`, `$QA-LOOP`, and `$Wiki`
+
+After installing, run:
 
 ```sh
-sks team "implement this" executor:3 reviewer:1
-sks team watch <mission-id>
-sks qa-loop prepare
-sks qa-loop run
-sks ralph prepare
-sks ralph run
-sks db scan
-sks gx init
+sks bootstrap
+sks codex-app check
+sks dollar-commands
 ```
 
-## Workflow Rules
+Then open Codex App and use prompt commands directly in the chat. Examples:
 
-For code work, Sneakoscope defaults to Team. The normal flow is: remove ambiguity that can change scope or safety, read/validate TriWiki, consume `attention.use_first` for compact high-trust context, hydrate `attention.hydrate_first` from source before risky decisions, gather current source evidence, synthesize consensus, compile a concrete runtime task graph plus worker inboxes, implement bounded changes, refresh/validate context after meaningful findings, run relevant checks, then finish with reflection and Honest Mode.
+```text
+$Team implement the checkout fix and verify it
+$DFix change this label and spacing only
+$QA-LOOP dogfood localhost:3000 and fix safe issues
+$Ralph clarify once, then finish the migration without more questions
+$Wiki refresh and validate the context pack
+$DB inspect this migration for destructive risk
+```
+
+Generated app files include:
 
-For tiny text/design edits use `$DFix`. For questions that should not change files use `$Answer`.
+| Path | Purpose |
+| --- | --- |
+| `.codex/SNEAKOSCOPE.md` | Codex App quick reference and route guidance. |
+| `.agents/skills/` | Generated skill instructions for `$` commands. |
+| `.codex/hooks.json` | Stop/finalization hooks for Honest Mode and completion summaries. |
+| `.codex/config.toml` | Codex profiles, agents, and MCP configuration. |
+| `.sneakoscope/` | Runtime state, missions, wiki packs, policies, and artifacts. |
 
-## Codex App Surface
+Use `sks dollar-commands` to confirm that terminal discovery and Codex App prompt commands agree.
 
-`sks bootstrap` and `sks setup` install `.codex/SNEAKOSCOPE.md`, generated `.agents/skills`, `.codex/hooks.json`, route instructions for `$` commands, and user-home skill state for first-install discoverability.
+## Prompt `$` Commands
+
+Use these inside Codex App or another agent prompt. They are prompt commands, not terminal commands.
+
+| Prompt | Use when |
+| --- | --- |
+| `$Team` | You want implementation, code changes, or substantial repo work. |
+| `$From-Chat-IMG` | You have a chat screenshot plus original attachments and want each visible request mapped to work. |
+| `$DFix` | You need a tiny design/content edit such as copy, label, color, spacing, or translation. |
+| `$Answer` | You want an answer only and no implementation should start. |
+| `$SKS` | You need setup, status, usage, or workflow help. |
+| `$QA-LOOP` | You want UI/API dogfooding, safe fixes, and rechecks. |
+| `$Ralph` | You want one prepare-time clarification pass, then no more user questions. |
+| `$Research` | You need frontier-style research with hypotheses and falsification. |
+| `$AutoResearch` | You want iterative improve/test/keep-or-discard optimization. |
+| `$DB` | You need database, Supabase, migration, SQL, or MCP safety checks. |
+| `$MAD-SKS` | You explicitly authorize a scoped high-risk DB permission modifier for the active invocation only. |
+| `$GX` | You need deterministic visual context cartridges. |
+| `$Wiki` | You want TriWiki refresh, pack, prune, validate, or maintenance. |
+| `$Help` | You want installed command and workflow explanation. |
 
-After install, check:
+## Common Workflows
+
+### First Install Checklist
 
 ```sh
+npm i -g sneakoscope
+sks bootstrap
+sks deps check
+sks codex-app check
 sks dollar-commands
-sks usage codex-app
+sks selftest --mock
 ```
 
-## Release Checks
+### Start A CLI Workspace
+
+```sh
+sks cmux check
+sks
+```
 
-Before publish:
+For the high-reasoning full-access profile:
+
+```sh
+sks --mad --high
+```
+
+### Use Codex App `$Team`
+
+```text
+$Team implement the requested change, update docs if needed, and verify with the relevant tests
+```
+
+Team mode records a mission under `.sneakoscope/missions/`, keeps a live transcript, uses TriWiki context, and finishes with evidence and Honest Mode.
+
+### Dogfood A UI Or API
+
+```sh
+sks qa-loop prepare "http://localhost:3000"
+sks qa-loop run latest --max-cycles 2
+sks qa-loop status latest
+```
+
+Use `$QA-LOOP` in Codex App when Browser Use or Computer Use evidence should be part of the workflow.
+
+### Refresh Context Before Risky Work
+
+```sh
+sks wiki refresh
+sks wiki validate .sneakoscope/wiki/context-pack.json
+```
+
+TriWiki is the long-running context source of truth. It keeps compact high-trust recall in `attention.use_first` and source-hydration targets in `attention.hydrate_first`.
+
+## Safety Model
+
+Sneakoscope intentionally treats these as high-risk:
+
+- SQL and migrations
+- Supabase MCP and RLS changes
+- destructive filesystem operations
+- user-global harness config
+- published package/release state
+
+By default, SKS favors inspection, local files, branch-safe changes, explicit confirmation for destructive DB operations, and completion claims backed by tests or artifacts.
+
+## Troubleshooting
+
+### `sks` points to an old version
+
+```sh
+which sks
+sks --version
+node ./bin/sks.mjs --version
+npm install -g .
+```
+
+If the global command is stale, reinstall globally from the repo or from npm.
+
+### cmux is missing
+
+```sh
+sks deps install cmux
+sks cmux check
+```
+
+`sks --mad --high` also attempts Homebrew installation automatically on macOS when cmux is missing.
+
+### Codex App tools are missing
+
+```sh
+sks codex-app check
+codex mcp list
+```
+
+Codex App workflows need the app installed and the first-party Browser Use / Computer Use tools available for parity with QA and visual workflows.
+
+### Setup is blocked by another harness
+
+```sh
+sks conflicts check
+sks conflicts prompt
+```
+
+OMX/DCodex conflicts intentionally block setup/doctor until the user approves cleanup.
+
+### The route is stuck or a final hook keeps reopening
+
+```sh
+sks pipeline status --json
+sks team watch latest
+sks wiki validate .sneakoscope/wiki/context-pack.json
+```
+
+Finalization requires real evidence, no unsupported critical claims, valid Team cleanup artifacts, reflection when required, and Honest Mode.
+
+## Development And Release
+
+Run local checks:
+
+```sh
+npm run repo-audit
+npm run changelog:check
+npm run packcheck
+npm run selftest
+npm run sizecheck
+npm run release:check
+```
+
+Dry-run publish:
 
 ```sh
 npm run publish:dry
 ```
 
-This runs repo audit, changelog check, syntax packcheck, mock selftest, sizecheck, and `npm pack --dry-run`. A dry run proves the local package is packable; npm account ownership or OTP can still block the real registry upload.
+`publish:dry` proves the local package is packable. It does not prove npm ownership, OTP, or registry publish permission.
 
-## Requirements
+## Documentation Style
 
-- Node.js `>=20.11`
-- npm
-- Codex CLI/App for app-facing workflows
-- cmux for the CLI-first runtime (`sks deps install cmux`)
-- Context7 MCP for current-docs-gated routes
+This README follows a common open-source CLI shape:
+
+- quick start first
+- explicit install paths
+- separate CLI and app/plugin usage
+- command examples before internal architecture
+- troubleshooting and release checks near the end
+
+That shape mirrors how projects such as `rdme` and Vite separate quick start, setup/configuration, and CLI usage while keeping copy-ready commands visible.
 
 ## License
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sneakoscope",
   "displayName": "ㅅㅋㅅ",
-  "version": "0.6.62",
+  "version": "0.6.64",
   "description": "Sneakoscope Codex: database-safe Codex CLI/App harness with Team, Ralph, AutoResearch, TriWiki, and Honest Mode.",
   "type": "module",
   "homepage": "https://github.com/mandarange/Sneakoscope-Codex#readme",

package/src/cli/main.mjs

@@ -30,7 +30,7 @@ import { context7Evidence, evaluateStop, recordContext7Evidence, recordSubagentE
 import { TEAM_DECOMPOSITION_ARTIFACT, TEAM_GRAPH_ARTIFACT, TEAM_INBOX_DIR, TEAM_RUNTIME_TASKS_ARTIFACT, teamRuntimePlanMetadata, teamRuntimeRequiredArtifacts, validateTeamRuntimeArtifacts, writeTeamRuntimeArtifacts } from '../core/team-dag.mjs';
 import { appendTeamEvent, formatRoleCounts, initTeamLive, normalizeTeamSpec, parseTeamSpecArgs, parseTeamSpecText, readTeamDashboard, readTeamLive, readTeamTranscriptTail } from '../core/team-live.mjs';
 import { CODEX_APP_DOCS_URL, codexAppIntegrationStatus, formatCodexAppStatus } from '../core/codex-app.mjs';
-import { buildCmuxLaunchPlan, defaultCmuxWorkspaceName, formatCmuxBanner, launchCmuxTeamView, launchCmuxUi, platformCmuxInstallHint, runCmuxStatus, sanitizeCmuxWorkspaceName, cmuxAvailable } from '../core/cmux-ui.mjs';
+import { buildCmuxLaunchPlan, defaultCmuxWorkspaceName, ensureCmuxInstalled, formatCmuxBanner, launchCmuxTeamView, launchCmuxUi, platformCmuxInstallHint, runCmuxStatus, sanitizeCmuxWorkspaceName, cmuxAvailable } from '../core/cmux-ui.mjs';
 import { autoReviewProfileName, autoReviewStatus, autoReviewSummary, enableAutoReview, disableAutoReview, enableMadHighProfile, madHighProfileName } from '../core/auto-review.mjs';
 
 const flag = (args, name) => args.includes(name);
@@ -1044,13 +1044,17 @@ async function cmuxCommand(sub = 'start', args = []) {
 }
 
 async function madHighCommand(args = []) {
-  const cleanArgs = args.filter((arg) => !['--mad', '--MAD', '--mad-sks', '--high'].includes(arg));
+  const cleanArgs = args.filter((arg) => !['--mad', '--MAD', '--mad-sks', '--high', '--no-auto-install-cmux'].includes(arg));
   const profile = await enableMadHighProfile();
   if (flag(args, '--json')) return console.log(JSON.stringify(profile, null, 2));
   console.log(`SKS MAD high profile ready: ${madHighProfileName()}`);
   console.log('Scope: explicit cmux launch only; normal SKS/DB safety returns after this command.');
   const workspace = readOption(cleanArgs, '--workspace', readOption(cleanArgs, '--session', `sks-mad-${defaultCmuxWorkspaceName(process.cwd())}`));
-  return launchCmuxUi([...cleanArgs, '--workspace', workspace], { codexArgs: ['--profile', profile.profile_name] });
+  return launchCmuxUi([...cleanArgs, '--workspace', workspace], {
+    codexArgs: ['--profile', profile.profile_name],
+    autoInstallCmux: !flag(args, '--no-auto-install-cmux'),
+    conciseBlockers: true
+  });
 }
 
 async function deps(sub = 'check', args = []) {
@@ -1172,11 +1176,15 @@ async function installCmuxDependency(args = []) {
     if (!brew) return { target: 'cmux', status: 'homebrew_missing', command: `/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" && ${command}` };
     if (flag(args, '--dry-run')) return { target: 'cmux', status: 'dry_run', command };
     if (!await confirmInstall(`Install cmux with Homebrew (${command})?`, args)) return { target: 'cmux', status: 'needs_approval', command };
-    const tap = await runProcess(brew, ['tap', 'manaflow-ai/cmux'], { timeoutMs: 180000, maxOutputBytes: 128 * 1024 });
-    const run = tap.code === 0
-      ? await runProcess(brew, ['install', '--cask', 'cmux'], { timeoutMs: 180000, maxOutputBytes: 128 * 1024 })
-      : tap;
-    return { target: 'cmux', status: run.code === 0 ? 'installed' : 'failed', command, code: run.code, error: run.code === 0 ? null : `${run.stderr || run.stdout || 'brew install --cask cmux failed'}`.trim() };
+    const installed = await ensureCmuxInstalled({ autoInstall: true });
+    return {
+      target: 'cmux',
+      status: installed.status,
+      version: installed.cmux?.version || null,
+      command,
+      code: installed.code,
+      error: installed.error || null
+    };
   }
   return { target: 'cmux', status: 'manual_required', command: platformCmuxInstallHint() };
 }

package/src/core/cmux-ui.mjs

@@ -5,12 +5,16 @@ import { getCodexInfo } from './codex-adapter.mjs';
 import { codexAppIntegrationStatus, formatCodexAppStatus } from './codex-app.mjs';
 
 export const SKS_CMUX_LOGO = [
-  '+----------------------+',
-  '|        ㅅㅋㅅ         |',
-  '|       SKS cmux       |',
-  '+----------------------+'
+  '   _____ __ __ _____',
+  '  / ___// //_// ___/',
+  '  \\__ \\/ ,<   \\__ \\   ㅅㅋㅅ',
+  ' ___/ / /| | ___/ /',
+  '/____/_/ |_|/____/',
+  'Sneakoscope Codex cmux'
 ].join('\n');
 
+export const CMUX_BREW_COMMAND = 'brew tap manaflow-ai/cmux && brew install --cask cmux';
+
 export function sanitizeCmuxWorkspaceName(input) {
   const base = String(input || 'sks').trim().replace(/[^A-Za-z0-9_.-]+/g, '-').replace(/^-+|-+$/g, '');
   return (base || 'sks').slice(0, 80);
@@ -29,7 +33,7 @@ export function shellEscape(value) {
 export function platformCmuxInstallHint() {
   if (process.platform !== 'darwin') return 'cmux is a native macOS app; install it on macOS 14+ from https://cmux.com or https://github.com/manaflow-ai/cmux.';
   return [
-    'brew tap manaflow-ai/cmux && brew install --cask cmux',
+    CMUX_BREW_COMMAND,
     'then expose the CLI if needed:',
     'sudo ln -sf "/Applications/cmux.app/Contents/Resources/bin/cmux" /usr/local/bin/cmux'
   ].join(' ');
@@ -53,6 +57,31 @@ export async function cmuxAvailable() {
   return { ok: probe.code === 0, bin, version: text || 'cmux CLI', error: probe.code === 0 ? null : text || 'cmux workspace probe failed' };
 }
 
+export async function ensureCmuxInstalled(opts = {}) {
+  const before = await cmuxAvailable().catch((err) => ({ ok: false, error: err.message || 'cmux probe failed' }));
+  if (before.ok) return { target: 'cmux', status: 'present', cmux: before, command: null };
+  if (opts.autoInstall === false || process.env.SKS_NO_CMUX_AUTO_INSTALL === '1') {
+    return { target: 'cmux', status: 'missing', cmux: before, command: CMUX_BREW_COMMAND, error: before.error || 'cmux CLI not found' };
+  }
+  if (process.platform !== 'darwin') {
+    return { target: 'cmux', status: 'manual_required', cmux: before, command: platformCmuxInstallHint(), error: before.error || 'cmux is macOS-only' };
+  }
+  const brew = await which('brew').catch(() => null);
+  if (!brew) {
+    return { target: 'cmux', status: 'homebrew_missing', cmux: before, command: CMUX_BREW_COMMAND, error: 'Homebrew is required for automatic cmux install' };
+  }
+  if (!opts.quiet) console.log('cmux CLI missing; installing cmux with Homebrew...');
+  const tap = await runProcess(brew, ['tap', 'manaflow-ai/cmux'], { timeoutMs: 180000, maxOutputBytes: 128 * 1024 }).catch((err) => ({ code: 1, stdout: '', stderr: err.message }));
+  const install = tap.code === 0
+    ? await runProcess(brew, ['install', '--cask', 'cmux'], { timeoutMs: 300000, maxOutputBytes: 256 * 1024 }).catch((err) => ({ code: 1, stdout: '', stderr: err.message }))
+    : tap;
+  let after = await cmuxAvailable().catch((err) => ({ ok: false, error: err.message || 'cmux probe failed after install' }));
+  if (!after.ok && after.bin) after = await wakeCmuxAndReprobe(after);
+  if (after.ok) return { target: 'cmux', status: 'installed', cmux: after, command: CMUX_BREW_COMMAND };
+  const rawError = `${install.stderr || install.stdout || after.error || 'brew install --cask cmux failed'}`.trim();
+  return { target: 'cmux', status: 'failed', cmux: after, command: CMUX_BREW_COMMAND, code: install.code, error: rawError };
+}
+
 export function codexLaunchCommand(root, codexBin, codexArgs = []) {
   const extraArgs = Array.isArray(codexArgs) ? codexArgs : [];
   return [
@@ -126,12 +155,19 @@ export function formatCmuxBanner(status = null) {
 export async function launchCmuxUi(args = [], opts = {}) {
   const rootArg = readOption(args, '--root', opts.root);
   const workspaceArg = readOption(args, '--workspace', readOption(args, '--session', opts.workspace || opts.session));
-  const plan = await buildCmuxLaunchPlan({ ...opts, root: rootArg, workspace: workspaceArg });
+  let plan = await buildCmuxLaunchPlan({ ...opts, root: rootArg, workspace: workspaceArg });
+  let cmuxRepair = null;
+  if (!plan.ready && plan.cmux.bin && !plan.cmux.ok && !args.includes('--json')) {
+    const warmed = await wakeCmuxAndReprobe(plan.cmux);
+    if (warmed.ok) plan = await buildCmuxLaunchPlan({ ...opts, root: rootArg, workspace: workspaceArg, cmux: warmed });
+  }
+  if (!plan.ready && !plan.cmux.ok && opts.autoInstallCmux && !args.includes('--json')) {
+    cmuxRepair = await ensureCmuxInstalled({ autoInstall: true, quiet: Boolean(opts.quietAutoInstall || args.includes('--quiet')) });
+    if (cmuxRepair.cmux?.ok) plan = await buildCmuxLaunchPlan({ ...opts, root: rootArg, workspace: workspaceArg, cmux: cmuxRepair.cmux });
+  }
   if (args.includes('--json')) return { plan };
   if (!plan.ready && !args.includes('--status-only')) {
-    console.log(formatCmuxBanner(plan.app));
-    console.log('\nLaunch blocked:\n');
-    for (const blocker of Array.from(new Set(plan.blockers))) console.log(`- ${blocker}`);
+    printCmuxLaunchBlocked(plan, { concise: opts.conciseBlockers, cmuxRepair });
     process.exitCode = 1;
     return { plan };
   }
@@ -149,12 +185,37 @@ export async function launchCmuxUi(args = [], opts = {}) {
   return { plan, created: true };
 }
 
+function printCmuxLaunchBlocked(plan, opts = {}) {
+  if (opts.concise) {
+    console.error('SKS cmux launch blocked.');
+    if (!plan.cmux.ok) {
+      const repair = opts.cmuxRepair;
+      const prefix = repair?.status ? `cmux ${repair.status}` : 'cmux missing';
+      console.error(`- ${prefix}: ${repair?.error || plan.cmux.error || 'cmux CLI not found'}`);
+      console.error(`- Install command: ${repair?.command || CMUX_BREW_COMMAND}`);
+    }
+    if (!plan.codex.bin) console.error('- Codex CLI missing. Install: npm i -g @openai/codex, or set SKS_CODEX_BIN.');
+    return;
+  }
+  console.log(formatCmuxBanner(plan.app));
+  console.log('\nLaunch blocked:\n');
+  for (const blocker of Array.from(new Set(plan.blockers))) console.log(`- ${blocker}`);
+}
+
 export async function openCmuxApp() {
   if (process.platform !== 'darwin') return { ok: false, reason: 'not_macos' };
   const run = await runProcess('open', ['-a', 'cmux'], { timeoutMs: 5000, maxOutputBytes: 16 * 1024 }).catch((err) => ({ code: 1, stderr: err.message, stdout: '' }));
   return { ok: run.code === 0, stdout: run.stdout || '', stderr: run.stderr || '' };
 }
 
+async function wakeCmuxAndReprobe(fallback = {}) {
+  if (process.platform !== 'darwin') return fallback;
+  const opened = await openCmuxApp().catch(() => null);
+  if (!opened?.ok) return fallback;
+  await new Promise((resolve) => setTimeout(resolve, 1500));
+  return cmuxAvailable().catch(() => fallback);
+}
+
 export async function launchCmuxTeamView({ root, missionId, plan = {}, promptFile = null, json = false } = {}) {
   const launch = await buildCmuxLaunchPlan({ root, workspace: `sks-team-${missionId}` });
   const agents = [

package/src/core/fsx.mjs

@@ -5,7 +5,7 @@ import os from 'node:os';
 import crypto from 'node:crypto';
 import { spawn } from 'node:child_process';
 
-export const PACKAGE_VERSION = '0.6.62';
+export const PACKAGE_VERSION = '0.6.64';
 export const DEFAULT_PROCESS_TAIL_BYTES = 256 * 1024;
 export const DEFAULT_PROCESS_TIMEOUT_MS = 30 * 60 * 1000;