sneakoscope 0.7.11 → 0.7.13

package/src/core/routes.mjs

@@ -7,7 +7,7 @@ export const FROM_CHAT_IMG_CHECKLIST_ARTIFACT = 'from-chat-img-checklist.md';
 export const FROM_CHAT_IMG_TEMP_TRIWIKI_ARTIFACT = 'from-chat-img-temp-triwiki.json';
 export const FROM_CHAT_IMG_QA_LOOP_ARTIFACT = 'from-chat-img-qa-loop.json';
 export const FROM_CHAT_IMG_TEMP_TRIWIKI_SESSIONS = 5;
-export const USAGE_TOPICS = 'install|setup|bootstrap|root|deps|warp|auto-review|team|qa-loop|ppt|goal|research|db|codex-app|dfix|design|imagegen|dollar|context7|pipeline|reasoning|guard|conflicts|versioning|eval|harness|hproof|gx|wiki|code-structure|proof-field|skill-dream';
+export const USAGE_TOPICS = 'install|setup|bootstrap|root|deps|tmux|auto-review|team|qa-loop|ppt|goal|research|db|codex-app|dfix|design|imagegen|dollar|context7|pipeline|reasoning|guard|conflicts|versioning|eval|harness|hproof|gx|wiki|code-structure|proof-field|skill-dream';
 export const CODEX_COMPUTER_USE_EVIDENCE_SOURCE = 'codex_computer_use';
 export const CODEX_APP_IMAGE_GENERATION_DOC_URL = 'https://developers.openai.com/codex/app/features#image-generation';
 export const CODEX_COMPUTER_USE_ONLY_POLICY = 'Pipeline UI/browser verification and visual inspection must use Codex Computer Use only. Do not use Playwright, Chrome MCP, Browser Use, Selenium, Puppeteer, or any other browser automation substitute; if Codex Computer Use is unavailable, mark the UI/browser evidence unverified instead of substituting another tool.';
@@ -231,7 +231,7 @@ export const ROUTES = [
     context7Policy: 'optional',
     reasoningPolicy: 'high',
     stopGate: 'team-gate.json',
-    cliEntrypoint: 'sks team "task" [executor:5 reviewer:2 user:1] | sks team log|tail|watch|lane|status|event|message|cleanup-warp',
+    cliEntrypoint: 'sks team "task" [executor:5 reviewer:2 user:1] | sks team log|tail|watch|lane|status|event|message|cleanup-tmux',
     examples: ['$Team executor:5 agree on the best plan and implement it', '$From-Chat-IMG 채팅+첨부 이미지 작업 지시서']
   },
   {
@@ -413,13 +413,13 @@ export const COMMAND_CATALOG = [
   { name: 'commands', usage: 'sks commands [--json]', description: 'List every user-facing command with a short description.' },
   { name: 'usage', usage: `sks usage [${USAGE_TOPICS}]`, description: 'Print copy-ready workflows for common tasks.' },
   { 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/warp, and print ready true/false.' },
+  { 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/tmux, 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: 'deps', usage: 'sks deps check|install [warp|codex|context7|all] [--yes]', description: 'Check or guided-install Node/npm PATH, Codex CLI/App, Context7, Browser Use, Computer Use, warp, and Homebrew on macOS.' },
+  { name: 'deps', usage: 'sks deps check|install [tmux|codex|context7|all] [--yes]', description: 'Check or guided-install Node/npm PATH, Codex CLI/App, Context7, Browser Use, Computer Use, tmux, and Homebrew on macOS.' },
   { name: 'codex-app', usage: 'sks codex-app [check|open]', description: 'Check Codex App install and first-party MCP/plugin readiness, then show app setup files and examples.' },
-  { name: 'warp', usage: 'sks warp open|check|status [--workspace name]', description: 'Explicitly open the SKS warp runtime, or check/status without launching Warp.' },
-  { name: 'mad', usage: 'sks --mad [--high]', description: 'Open a one-shot warp Codex CLI workspace with the SKS MAD full-access auto-review profile.' },
-  { name: 'auto-review', usage: 'sks auto-review status|enable|start [--high] | sks --Auto-review --high', description: 'Enable Codex automatic approval review and launch SKS warp with the auto-review profile.' },
+  { name: 'tmux', usage: 'sks tmux open|check|status [--workspace name]', description: 'Explicitly open the SKS tmux runtime, or check/status without launching tmux.' },
+  { name: 'mad', usage: 'sks --mad [--high]', description: 'Open a one-shot tmux Codex CLI workspace with the SKS MAD full-access auto-review profile.' },
+  { name: 'auto-review', usage: 'sks auto-review status|enable|start [--high] | sks --Auto-review --high', description: 'Enable Codex automatic approval review and launch SKS tmux with the auto-review profile.' },
   { name: 'dollar-commands', usage: 'sks dollar-commands [--json]', description: 'List Codex App $ commands such as $DFix and $Team.' },
   { name: 'dfix', usage: 'sks dfix', description: 'Explain $DFix ultralight design/content fix mode.' },
   { name: 'qa-loop', usage: 'sks qa-loop prepare|answer|run|status ...', description: 'Dogfood UI/API as human proxy with safety gates, safe fixes, rechecks, Codex Computer Use-only UI evidence, report.' },
@@ -439,7 +439,7 @@ export const COMMAND_CATALOG = [
   { name: 'research', usage: 'sks research prepare|run|status ...', description: 'Run frontier-style research missions with novelty and falsification gates.' },
   { name: 'db', usage: 'sks db policy|scan|mcp-config|classify|check ...', description: 'Inspect and enforce database/Supabase safety policy.' },
   { name: 'eval', usage: 'sks eval run|compare|thresholds ...', description: 'Run deterministic context-quality and performance evidence checks.' },
-  { name: 'harness', usage: 'sks harness fixture|review [--json]', description: 'Run Harness Growth Factory fixtures for forgetting, skills, experiments, tool taxonomy, permissions, MultiAgentV2, and Warp views.' },
+  { name: 'harness', usage: 'sks harness fixture|review [--json]', description: 'Run Harness Growth Factory fixtures for forgetting, skills, experiments, tool taxonomy, permissions, MultiAgentV2, and tmux views.' },
   { name: 'perf', usage: 'sks perf run|workflow [--json] [--iterations N] [--intent "task"] [--changed file1,file2]', description: 'Measure structured GPT-5.5/SKS performance budgets, including Proof Field workflow decisions and fast-lane evidence.' },
   { name: 'proof-field', usage: 'sks proof-field scan [--json] [--intent "task"] [--changed file1,file2]', description: 'Analyze Potential Proof Field cones, negative-work cache, and fast-lane eligibility for a change set.' },
   { name: 'skill-dream', usage: 'sks skill-dream status|run|record [--json]', description: 'Track generated-skill usage in lightweight JSON and periodically report keep, merge, prune, and improvement candidates without deleting skills automatically.' },
@@ -447,7 +447,7 @@ export const COMMAND_CATALOG = [
   { name: 'validate-artifacts', usage: 'sks validate-artifacts [mission-id|latest] [--json]', description: 'Validate schema-backed mission artifacts for work orders, effort decisions, visual maps, dogfood reports, skills, mistake memory, Team dashboard state, and Honest Mode.' },
   { name: 'wiki', usage: 'sks wiki coords|pack|refresh|prune|validate ...', description: 'Build, refresh, prune, and validate RGBA/trig LLM Wiki context packs with attention.use_first and attention.hydrate_first for compact recall plus source hydration.' },
   { name: 'hproof', usage: 'sks hproof check [mission-id|latest]', description: 'Evaluate the H-Proof done gate for a mission.' },
-  { name: 'team', usage: 'sks team "task" [executor:5 reviewer:2 user:1]|log|tail|watch|lane|status|dashboard|event|message|cleanup-warp ...', description: 'Create and observe a scout-first Team mission with color-coded Warp lanes, transcript messages, and cleanup-aware follow panes.' },
+  { name: 'team', usage: 'sks team "task" [executor:5 reviewer:2 user:1]|log|tail|watch|lane|status|dashboard|event|message|cleanup-tmux ...', description: 'Create and observe a scout-first Team mission with color-coded tmux lanes, transcript messages, and cleanup-aware follow panes.' },
   { name: 'reasoning', usage: 'sks reasoning ["prompt"] [--json]', description: 'Show SKS temporary reasoning-effort routing: medium for simple tasks, high for logic, xhigh for research.' },
   { name: 'gx', usage: 'sks gx init|render|validate|drift|snapshot [name]', description: 'Create and verify deterministic SVG/HTML visual context cartridges.' },
   { name: 'profile', usage: 'sks profile show|set <model>', description: 'Inspect or set the current SKS model profile metadata.' },

package/src/core/team-live.mjs

@@ -72,7 +72,7 @@ export function defaultTeamDashboard(id, prompt, opts = {}) {
       lane: `sks team lane ${id} --agent <agent> --follow`,
       event: `sks team event ${id} --agent <agent> --phase <phase> --message "..."`,
       message: `sks team message ${id} --from <agent> --to <agent|all> --message "..."`,
-      cleanup: `sks team cleanup-warp ${id}`
+      cleanup: `sks team cleanup-tmux ${id}`
     },
     agents: Object.fromEntries([...new Set([...DEFAULT_AGENTS, ...spec.roster.all_agents.map((agent) => agent.id)])].map((name) => [name, { status: 'pending', phase: null, last_seen: null }])),
     phases: ['parallel_analysis_scouting', 'triwiki_refresh', 'debate_team', 'triwiki_refresh_after_consensus', 'parallel_development_team', 'triwiki_refresh_after_implementation', 'strict_review_and_user_acceptance', 'session_cleanup'],
@@ -98,7 +98,7 @@ ${prompt}
 
 ## How to Read
 
-- This file is the Codex App-visible replacement for warp-style team panes.
+- This file is the Codex App-visible replacement for tmux-style team panes.
 - Use at most ${spec.agentSessions} subagent sessions at a time unless the mission is recreated with a different budget.
 - Team mode has three bundles: parallel analysis scouts first, debate team second, then fresh parallel development team.
 - Use relevant TriWiki context before every stage, hydrate low-trust claims from source during the stage, refresh after findings/artifact changes, and validate before handoffs or final claims.
@@ -124,7 +124,7 @@ sks team watch ${id}
 sks team lane ${id} --agent analysis_scout_1 --follow
 sks team event ${id} --agent analysis_scout_1 --phase parallel_analysis_scouting --message "mapped repo slice"
 sks team message ${id} --from analysis_scout_1 --to executor_1 --message "handoff note"
-sks team cleanup-warp ${id}
+sks team cleanup-tmux ${id}
 \`\`\`
 
 ## Roster
@@ -220,7 +220,7 @@ export function parseTeamSpecArgs(args = []) {
       i++;
       continue;
     }
-    if (arg === '--json' || arg === '--open-warp' || arg === '--warp-open') continue;
+    if (arg === '--json' || arg === '--open-tmux' || arg === '--tmux-open') continue;
     cleanArgs.push(args[i]);
   }
   return { cleanArgs, ...normalizeTeamSpec({ roleCounts, agentSessions: explicitSession }) };
@@ -363,7 +363,7 @@ export async function requestTeamSessionCleanup(dir, opts = {}) {
     cleanup_requested_at: opts.ts || nowIso(),
     cleanup_requested_by: opts.agent || 'parent_orchestrator',
     cleanup_reason: opts.reason || 'Team session cleanup requested.',
-    final_message: opts.finalMessage || 'Team session ended. Lane follow loops may stop; Warp panes remain user-controlled.'
+    final_message: opts.finalMessage || 'Team session ended. Lane follow loops may stop; tmux panes remain user-controlled.'
   };
   await writeJsonAtomic(files.control, next);
   return next;
@@ -383,7 +383,7 @@ export function renderTeamCleanupSummary(control = {}) {
     `Requested by: ${control.cleanup_requested_by || 'unknown'}`,
     `Reason: ${control.cleanup_reason || 'Team session cleanup requested.'}`,
     '',
-    control.final_message || 'Team session ended. Warp panes remain user-controlled.'
+    control.final_message || 'Team session ended. tmux panes remain user-controlled.'
   ].join('\n');
 }
 
@@ -469,10 +469,10 @@ export async function renderTeamWatch(dir, opts = {}) {
     '',
     '## Split-Screen Map',
     '- This overview pane follows the whole mission transcript.',
-    '- Neighbor warp panes follow individual `sks team lane ... --agent <name>` views.',
+    '- Neighbor tmux panes follow individual `sks team lane ... --agent <name>` views.',
     '- Use `sks team event ...` to mirror scout, debate, executor, review, and verification status into the live panes.',
     '- Use `sks team message ... --from <agent> --to <agent|all>` for bounded inter-agent communication in transcript/lane views.',
-    '- Use `sks team cleanup-warp ...` at session end; follow loops show cleanup and exit while Warp panes remain user-controlled.',
+    '- Use `sks team cleanup-tmux ...` at session end; follow loops show cleanup and exit while tmux panes remain user-controlled.',
     '',
     '## Cockpit Views',
     '- Mission / Goal | Agents | MultiAgentV2 | Work Orders | Skills | Memory Health | Forget Queue',

package/src/core/tmux-ui.mjs

@@ -0,0 +1,447 @@
+import path from 'node:path';
+import fsp from 'node:fs/promises';
+import { spawnSync } from 'node:child_process';
+import { exists, nowIso, packageRoot, readJson, runProcess, sha256, sksRoot, which, writeJsonAtomic } from './fsx.mjs';
+import { getCodexInfo } from './codex-adapter.mjs';
+import { codexAppIntegrationStatus, formatCodexAppStatus } from './codex-app.mjs';
+
+export const SKS_TMUX_LOGO = [
+  '   _____ __ __ _____',
+  '  / ___// //_// ___/',
+  '  \\__ \\/ ,<   \\__ \\   ㅅㅋㅅ',
+  ' ___/ / /| | ___/ /',
+  '/____/_/ |_|/____/',
+  'Sneakoscope Codex tmux'
+].join('\n');
+
+export function sanitizeTmuxSessionName(input) {
+  const base = String(input || 'sks').trim().replace(/[^A-Za-z0-9_.:-]+/g, '-').replace(/^-+|-+$/g, '');
+  return (base || 'sks').slice(0, 80);
+}
+
+export function defaultTmuxSessionName(root) {
+  const base = sanitizeTmuxSessionName(path.basename(root || process.cwd()) || 'project');
+  const hash = sha256(path.resolve(root || process.cwd())).slice(0, 8);
+  return sanitizeTmuxSessionName(`sks-${base}-${hash}`);
+}
+
+export function shellEscape(value) {
+  return `'${String(value).replace(/'/g, `'\\''`)}'`;
+}
+
+export function platformTmuxInstallHint() {
+  if (process.platform === 'darwin') return 'Install tmux 3.x or newer: brew install tmux';
+  return 'Install tmux 3.x or newer with your OS package manager, then run: sks tmux check';
+}
+
+export function tmuxStatePath(root = process.cwd()) {
+  return path.join(path.resolve(root || process.cwd()), '.sneakoscope', 'state', 'tmux-sessions.json');
+}
+
+export function tmuxTeamStatePath(root = process.cwd()) {
+  return path.join(path.resolve(root || process.cwd()), '.sneakoscope', 'state', 'tmux-team-sessions.json');
+}
+
+export function isTmuxShellSession(env = process.env) {
+  return Boolean(String(env.TMUX || '').trim());
+}
+
+export async function findTmuxBin() {
+  return await which('tmux').catch(() => null);
+}
+
+function parseTmuxVersion(text = '') {
+  const match = String(text || '').match(/tmux\s+([0-9]+(?:\.[0-9]+)?[a-z]?)/i);
+  return match ? match[1] : null;
+}
+
+function tmuxVersionOk(version = '') {
+  const match = String(version || '').match(/^([0-9]+)(?:\.([0-9]+))?/);
+  if (!match) return false;
+  const major = Number(match[1]);
+  const minor = Number(match[2] || 0);
+  return major > 3 || (major === 3 && minor >= 0);
+}
+
+export async function tmuxReadiness(opts = {}) {
+  const bin = opts.bin ?? await findTmuxBin();
+  let version = opts.version || null;
+  let error = null;
+  if (bin && !version) {
+    const run = await runProcess(bin, ['-V'], { timeoutMs: 5000, maxOutputBytes: 4096 }).catch((err) => ({ code: 1, stdout: '', stderr: err.message }));
+    if (run.code === 0) version = parseTmuxVersion(run.stdout || run.stderr || '');
+    else error = run.stderr || run.stdout || 'tmux -V failed';
+  }
+  const ok = Boolean(bin && version && tmuxVersionOk(version));
+  return {
+    ok,
+    bin: bin || null,
+    version,
+    min_version: '3.0',
+    current_session: isTmuxShellSession(opts.env || process.env),
+    error: ok ? null : error || (bin ? `tmux ${version || 'unknown'} is older than 3.0` : 'tmux not found')
+  };
+}
+
+export function tmuxStatusKind(tmux = {}) {
+  return tmux.ok ? 'ok' : 'missing';
+}
+
+export function codexLaunchCommand(root, codexBin, codexArgs = []) {
+  const extraArgs = Array.isArray(codexArgs) ? codexArgs : [];
+  return [
+    'clear',
+    `printf '%s\\n' ${shellEscape(SKS_TMUX_LOGO)}`,
+    `printf '\\nProject: %s\\n' ${shellEscape(root)}`,
+    'printf \'Runtime: tmux session for Codex CLI\\n\'',
+    'printf \'Prompt:  use canonical $ commands, for example $Team or $QA-LOOP\\n\\n\'',
+    'sleep 1',
+    `exec ${[shellEscape(codexBin), ...extraArgs.map(shellEscape), '--cd', shellEscape(root)].join(' ')}`
+  ].join('; ');
+}
+
+function terminalTitleCommand(title = '') {
+  return `printf '\\033]0;%s\\007' ${shellEscape(String(title || '').slice(0, 80))}`;
+}
+
+function ansiColorCode(color = '') {
+  return {
+    blue: '34',
+    cyan: '36',
+    yellow: '33',
+    green: '32',
+    red: '31',
+    magenta: '35'
+  }[String(color || '').toLowerCase()] || '37';
+}
+
+function colorizedLaneBannerCommand(lines = [], color = '') {
+  const code = ansiColorCode(color);
+  const text = lines.join('\n');
+  return `printf '\\033[1;${code}m%s\\033[0m\\n' ${shellEscape(text)}`;
+}
+
+export const TMUX_TEAM_LANE_STYLES = Object.freeze({
+  overview: Object.freeze({ role: 'overview', label: 'overview', color_name: 'Blue', color: 'blue', icon: 'layout-dashboard' }),
+  scout: Object.freeze({ role: 'scout', label: 'scout', color_name: 'Cyan', color: 'cyan', icon: 'search' }),
+  planning: Object.freeze({ role: 'planning', label: 'plan', color_name: 'Yellow', color: 'yellow', icon: 'messages-square' }),
+  execution: Object.freeze({ role: 'execution', label: 'exec', color_name: 'Green', color: 'green', icon: 'hammer' }),
+  review: Object.freeze({ role: 'review', label: 'review', color_name: 'Red', color: 'red', icon: 'shield-check' }),
+  safety: Object.freeze({ role: 'safety', label: 'safety', color_name: 'Magenta', color: 'magenta', icon: 'database' })
+});
+
+export function teamLaneStyle(agentId = '') {
+  const id = String(agentId || '').toLowerCase();
+  if (!id || id === 'mission_overview' || id === 'overview') return TMUX_TEAM_LANE_STYLES.overview;
+  if (/analysis|scout/.test(id)) return TMUX_TEAM_LANE_STYLES.scout;
+  if (/debate|consensus|planner|user/.test(id)) return TMUX_TEAM_LANE_STYLES.planning;
+  if (/db|safety/.test(id)) return TMUX_TEAM_LANE_STYLES.safety;
+  if (/review|qa|validation/.test(id)) return TMUX_TEAM_LANE_STYLES.review;
+  if (/executor|implementation|worker|developer/.test(id)) return TMUX_TEAM_LANE_STYLES.execution;
+  return TMUX_TEAM_LANE_STYLES.planning;
+}
+
+function teamLaneTitle(agentId = '') {
+  const style = teamLaneStyle(agentId);
+  return `${style.label}: ${String(agentId || 'mission_overview')}`.slice(0, 80);
+}
+
+export function teamAgentCommand(root, missionId, agentId, phase) {
+  const style = teamLaneStyle(agentId);
+  const title = teamLaneTitle(agentId);
+  return [
+    terminalTitleCommand(title),
+    'clear',
+    colorizedLaneBannerCommand([...SKS_TMUX_LOGO.split('\n'), '', `Team mission: ${missionId}`, `Agent: ${agentId}`, `Lane: ${style.label} (${style.color_name})`, `Phase: ${phase}`, 'Messages: sks team message ... --to ' + agentId, 'Cleanup: sks team cleanup-tmux ' + missionId], style.color),
+    `cd ${shellEscape(root)}`,
+    `node ${shellEscape(path.join(packageRoot(), 'bin', 'sks.mjs'))} team lane ${shellEscape(missionId)} --agent ${shellEscape(agentId)} --phase ${shellEscape(phase)} --follow --lines 12`
+  ].join('; ');
+}
+
+export function teamOverviewCommand(root, missionId) {
+  const style = teamLaneStyle('mission_overview');
+  const title = teamLaneTitle('mission_overview');
+  return [
+    terminalTitleCommand(title),
+    'clear',
+    colorizedLaneBannerCommand([...SKS_TMUX_LOGO.split('\n'), '', `Team mission: ${missionId}`, 'View: live orchestration overview', `Lane: ${style.label} (${style.color_name})`, 'Messages: sks team message ... --to <agent|all>', 'Cleanup: sks team cleanup-tmux ' + missionId], style.color),
+    `cd ${shellEscape(root)}`,
+    `node ${shellEscape(path.join(packageRoot(), 'bin', 'sks.mjs'))} team watch ${shellEscape(missionId)} --follow --lines 18`
+  ].join('; ');
+}
+
+export async function buildTmuxLaunchPlan(opts = {}) {
+  const root = path.resolve(opts.root || await sksRoot());
+  const session = sanitizeTmuxSessionName(opts.session || opts.workspace || defaultTmuxSessionName(root));
+  const sksBin = opts.sksBin || path.join(packageRoot(), 'bin', 'sks.mjs');
+  const codex = opts.codex || await getCodexInfo().catch(() => ({}));
+  const tmux = opts.tmux || await tmuxReadiness(opts);
+  const app = opts.app || await codexAppIntegrationStatus({ codex });
+  const codexArgs = Array.isArray(opts.codexArgs) ? opts.codexArgs : [];
+  return {
+    root,
+    session,
+    workspace: session,
+    sksBin,
+    codex,
+    tmux,
+    app,
+    codexArgs,
+    attach_command: `tmux attach-session -t ${session}`,
+    ready: Boolean(tmux.ok && codex.bin),
+    warnings: app.ok ? [] : app.guidance || [],
+    blockers: [
+      ...(!tmux.ok ? [`tmux missing or too old. ${platformTmuxInstallHint()}`] : []),
+      ...(!codex.bin ? ['Codex CLI missing. Install: npm i -g @openai/codex, or set SKS_CODEX_BIN.'] : [])
+    ]
+  };
+}
+
+export function formatTmuxBanner(status = null) {
+  const lines = [
+    SKS_TMUX_LOGO,
+    '',
+    'ㅅㅋㅅ tmux runtime',
+    '',
+    'Canonical prompt commands:',
+    '  $DFix  $Answer  $SKS  $Team  $QA-LOOP  $PPT  $Goal  $Research  $AutoResearch  $DB  $GX  $Wiki  $Help',
+    '',
+    'CLI-first runtime:',
+    '  sks tmux open       open or attach a tmux Codex CLI session',
+    '  sks --mad           open one-shot MAD full-access auto-review tmux session',
+    '  sks team "task"     prepare Team mission and tmux multi-pane live view',
+    '',
+    'Useful terminal commands:',
+    '  sks commands',
+    '  sks dollar-commands',
+    '  sks codex-app check',
+    '  sks doctor --fix'
+  ];
+  if (status) lines.push('', formatCodexAppStatus(status));
+  return lines.join('\n');
+}
+
+function tmuxRun(bin, args, opts = {}) {
+  return runProcess(bin || 'tmux', args, { timeoutMs: opts.timeoutMs || 10000, maxOutputBytes: opts.maxOutputBytes || 32 * 1024 })
+    .catch((err) => ({ code: 1, stdout: '', stderr: err.message }));
+}
+
+function paneId(stdout = '') {
+  const id = String(stdout || '').split(/\r?\n/)[0]?.trim() || '';
+  return id.startsWith('%') ? id : null;
+}
+
+async function hasTmuxSession(bin, session) {
+  const run = await tmuxRun(bin, ['has-session', '-t', session], { timeoutMs: 5000 });
+  return run.code === 0;
+}
+
+export function buildTmuxOpenArgs(plan = {}) {
+  return ['attach-session', '-t', sanitizeTmuxSessionName(plan.session || plan.workspace || defaultTmuxSessionName(plan.root))];
+}
+
+export function runTmuxLaunchPlanSyntaxCheck(plan = {}) {
+  const args = buildTmuxOpenArgs(plan);
+  return {
+    ok: args[0] === 'attach-session' && args[1] === '-t' && Boolean(args[2]),
+    has_session: Boolean(args[2]),
+    command: ['tmux', ...args].join(' ')
+  };
+}
+
+export async function createTmuxSession(plan = {}, panes = [], opts = {}) {
+  const tmuxBin = plan.tmux?.bin || await findTmuxBin() || 'tmux';
+  const session = sanitizeTmuxSessionName(plan.session || plan.workspace || defaultTmuxSessionName(plan.root));
+  const root = path.resolve(plan.root || process.cwd());
+  const normalizedPanes = panes.length ? panes : [{ cwd: root, command: plan.command || codexLaunchCommand(root, plan.codex?.bin || 'codex', plan.codexArgs), focused: true }];
+  if (await hasTmuxSession(tmuxBin, session)) {
+    return { ok: true, reused: true, session, panes: [], attach_command: `tmux attach-session -t ${session}` };
+  }
+  const first = normalizedPanes[0] || { cwd: root, command: 'pwd' };
+  const create = await tmuxRun(tmuxBin, ['new-session', '-d', '-s', session, '-c', path.resolve(first.cwd || root), '-n', 'sks', '-P', '-F', '#{pane_id}', first.command || 'pwd']);
+  if (create.code !== 0) return { ok: false, session, panes: [], stderr: create.stderr || create.stdout || 'tmux new-session failed' };
+  const created = [{ pane_id: paneId(create.stdout), role: first.role || 'overview', title: first.title || 'overview' }];
+  for (const pane of normalizedPanes.slice(1)) {
+    const split = await tmuxRun(tmuxBin, ['split-window', '-t', session, pane.vertical ? '-v' : '-h', '-d', '-P', '-F', '#{pane_id}', '-c', path.resolve(pane.cwd || root), pane.command || 'pwd']);
+    if (split.code !== 0) return { ok: false, session, panes: created, stderr: split.stderr || split.stdout || 'tmux split-window failed' };
+    created.push({ pane_id: paneId(split.stdout), role: pane.role || 'lane', title: pane.title || null });
+  }
+  await tmuxRun(tmuxBin, ['select-layout', '-t', session, opts.layout || 'tiled']).catch(() => null);
+  return { ok: true, reused: false, session, panes: created, attach_command: `tmux attach-session -t ${session}` };
+}
+
+export async function launchTmuxUi(args = [], opts = {}) {
+  const rootArg = readOption(args, '--root', opts.root);
+  const sessionArg = readOption(args, '--session', readOption(args, '--workspace', opts.session || opts.workspace));
+  const plan = await buildTmuxLaunchPlan({ ...opts, root: rootArg, session: sessionArg });
+  if (args.includes('--json')) return { plan };
+  if (!plan.ready && !args.includes('--status-only')) {
+    printTmuxLaunchBlocked(plan, { concise: opts.conciseBlockers });
+    process.exitCode = 1;
+    return { plan };
+  }
+  if (args.includes('--status-only')) return { plan };
+  const command = codexLaunchCommand(plan.root, plan.codex.bin, plan.codexArgs);
+  const created = await createTmuxSession({ ...plan, command }, [{ cwd: plan.root, command, focused: true, role: 'codex', title: 'Codex CLI' }]);
+  if (created.ok) await writeTmuxSessionRecord(plan.root, { session: created.session, attach_command: created.attach_command, panes: created.panes }).catch(() => null);
+  if (!args.includes('--quiet')) {
+    console.log(`SKS tmux session: ${created.session || plan.session}`);
+    if (created.ok && created.reused) console.log('tmux: reused existing session');
+    else if (created.ok) console.log(`tmux: created ${created.panes.length} pane(s)`);
+    else console.log(`tmux: not created (${created.stderr || 'tmux failed'})`);
+    if (created.ok) console.log(`Attach: ${created.attach_command}`);
+  }
+  return { plan, created: Boolean(created.ok), session: created.session || plan.session, opened: created };
+}
+
+function printTmuxLaunchBlocked(plan, opts = {}) {
+  if (opts.concise) {
+    console.error('SKS tmux launch blocked.');
+    if (!plan.tmux.ok) console.error(`- tmux missing: ${platformTmuxInstallHint()}`);
+    if (!plan.codex.bin) console.error('- Codex CLI missing. Install: npm i -g @openai/codex@latest, or set SKS_CODEX_BIN.');
+    return;
+  }
+  console.log(formatTmuxBanner(plan.app));
+  console.log('\nLaunch blocked:\n');
+  for (const blocker of Array.from(new Set(plan.blockers))) console.log(`- ${blocker}`);
+}
+
+export async function launchTmuxTeamView({ root, missionId, plan = {}, promptFile = null, json = false } = {}) {
+  const launch = await buildTmuxLaunchPlan({ root, session: `sks-team-${missionId}` });
+  const agents = [
+    ...(plan.roster?.analysis_team || []),
+    ...(plan.roster?.debate_team || []),
+    ...(plan.roster?.development_team || []),
+    ...(plan.roster?.validation_team || [])
+  ];
+  const uniqueAgents = [];
+  const seen = new Set();
+  for (const agent of agents) {
+    const id = agent.id || String(agent);
+    if (seen.has(id)) continue;
+    seen.add(id);
+    uniqueAgents.push(id);
+  }
+  const commands = uniqueAgents.slice(0, Math.max(1, plan.agent_session_count || 3)).map((agentId, index) => ({
+    agent: agentId,
+    command: teamAgentCommand(launch.root, missionId, agentId, index === 0 ? 'analysis' : 'team', promptFile),
+    style: teamLaneStyle(agentId),
+    title: teamLaneTitle(agentId)
+  }));
+  const overview = { agent: 'mission_overview', role: 'overview', command: teamOverviewCommand(launch.root, missionId), style: teamLaneStyle('mission_overview'), title: teamLaneTitle('mission_overview') };
+  const lanes = [overview, ...commands.map((entry) => ({ ...entry, role: entry.style.role }))];
+  const result = {
+    ready: launch.ready,
+    tmux: launch.tmux,
+    session: launch.session,
+    workspace: launch.session,
+    overview,
+    agents: commands,
+    lanes,
+    cleanup_policy: 'mark-complete; tmux panes remain user controlled',
+    blockers: launch.blockers,
+    attach_command: launch.attach_command
+  };
+  if (json || !launch.ready) return result;
+  const panes = lanes.map((lane, index) => ({ cwd: launch.root, command: lane.command, focused: index === 0, role: lane.role, title: lane.title, vertical: index > 1 }));
+  const created = await createTmuxSession(launch, panes);
+  result.created = Boolean(created.ok);
+  result.opened = created;
+  result.session = created.session || launch.session;
+  result.opened_lane_count = created.panes?.length || lanes.length;
+  result.all_lanes_opened = Boolean(created.ok);
+  result.ready = Boolean(result.ready && created.ok);
+  await writeTmuxTeamRecord(launch.root, {
+    mission_id: missionId,
+    session: result.session,
+    attach_command: created.attach_command || launch.attach_command,
+    cleanup_policy: result.cleanup_policy,
+    panes: created.panes || [],
+    lanes: lanes.map((entry) => ({
+      agent: entry.agent,
+      role: entry.style?.role || teamLaneStyle(entry.agent).role,
+      style: entry.style || teamLaneStyle(entry.agent),
+      title: entry.title || teamLaneTitle(entry.agent)
+    }))
+  }).catch(() => null);
+  return result;
+}
+
+async function writeTmuxSessionRecord(root, record = {}) {
+  if (!record.session) return null;
+  const statePath = tmuxStatePath(root);
+  const state = await readJson(statePath, {}).catch(() => ({}));
+  const now = nowIso();
+  const nextRecord = { ...record, schema_version: 1, root: path.resolve(root || process.cwd()), updated_at: now };
+  const sessions = state.sessions && typeof state.sessions === 'object' ? state.sessions : {};
+  await writeJsonAtomic(statePath, {
+    schema_version: 1,
+    updated_at: now,
+    sessions: { ...sessions, [record.session]: nextRecord }
+  });
+  return nextRecord;
+}
+
+async function writeTmuxTeamRecord(root, record = {}) {
+  if (!record.mission_id || !record.session) return null;
+  const statePath = tmuxTeamStatePath(root);
+  const state = await readJson(statePath, {}).catch(() => ({}));
+  const now = nowIso();
+  const nextRecord = { ...record, schema_version: 1, root: path.resolve(root || process.cwd()), updated_at: now };
+  const missions = state.missions && typeof state.missions === 'object' ? state.missions : {};
+  await writeJsonAtomic(statePath, {
+    schema_version: 1,
+    updated_at: now,
+    missions: { ...missions, [record.mission_id]: nextRecord }
+  });
+  return nextRecord;
+}
+
+async function readTmuxTeamRecord(root, missionId) {
+  const state = await readJson(tmuxTeamStatePath(root), {}).catch(() => ({}));
+  const missions = state.missions && typeof state.missions === 'object' ? state.missions : {};
+  if (missionId && missionId !== 'latest') return missions[missionId] || null;
+  const records = Object.values(missions).filter((entry) => entry && typeof entry === 'object');
+  records.sort((a, b) => String(b.updated_at || '').localeCompare(String(a.updated_at || '')));
+  return records[0] || null;
+}
+
+export async function cleanupTmuxTeamView({ root, missionId = 'latest', closeSession = false } = {}) {
+  const resolvedRoot = path.resolve(root || await sksRoot());
+  const record = await readTmuxTeamRecord(resolvedRoot, missionId);
+  if (!record?.session) return { ok: false, skipped: true, reason: 'no recorded tmux Team session', mission_id: missionId };
+  let killed_session = false;
+  if (closeSession || closeSession === true) {
+    const tmuxBin = await findTmuxBin() || 'tmux';
+    const kill = await tmuxRun(tmuxBin, ['kill-session', '-t', record.session], { timeoutMs: 5000 });
+    killed_session = kill.code === 0;
+  }
+  await writeTmuxTeamRecord(resolvedRoot, { ...record, cleanup_completed_at: nowIso(), killed_session }).catch(() => null);
+  return {
+    ok: true,
+    mission_id: record.mission_id,
+    session: record.session,
+    attach_command: record.attach_command,
+    close_session: Boolean(closeSession),
+    killed_session,
+    requested_close_surfaces: closeSession ? 1 : 0,
+    closed_surfaces: killed_session ? 1 : 0,
+    reason: closeSession ? 'tmux kill-session requested for recorded Team session.' : 'cleanup marks the SKS tmux Team record complete; panes remain user-controlled.'
+  };
+}
+
+export async function runTmuxStatus(args = [], opts = {}) {
+  const once = args.includes('--once') || !args.includes('--watch');
+  do {
+    const app = await codexAppIntegrationStatus();
+    console.clear();
+    console.log(formatTmuxBanner(app));
+    if (once) return app;
+    await new Promise((resolve) => setTimeout(resolve, 5000));
+  } while (true);
+}
+
+function readOption(args, name, fallback = null) {
+  const i = args.indexOf(name);
+  return i >= 0 && args[i + 1] ? args[i + 1] : fallback;
+}