sneakoscope 0.7.64 → 0.7.66

package/README.md

@@ -2,7 +2,7 @@
 
 ![](https://github.com/mandarange/Sneakoscope-Codex/raw/dev/docs/assets/sneakoscope-codex-logo.png)
 
-Sneakoscope Codex (`sks`, displayed as `ㅅㅋㅅ`) is a Codex CLI/App harness for repeatable agent workflows. It adds terminal commands, Codex App `$` prompt commands, tmux-native CLI workspaces, Team/QA/Research routes, inspectable pipeline plans, a maximum-speed Computer Use lane, an imagegen/gpt-image-2 UI/UX review route, a fast Goal bridge for native `/goal` persistence, Context7 evidence checks, DB safety, TriWiki context tracking, design-system SSOT routing, lightweight skill dreaming, Honest Mode, and release-readiness gates.
+Sneakoscope Codex (`sks`) is a Codex CLI/App harness for repeatable workflows. It adds terminal commands, Codex App `$` commands, tmux workspaces, Team/QA/Research routes, pipeline plans, Computer Use, imagegen UI/UX review, Goal, Context7, DB safety, TriWiki, design-system routing, skill dreaming, Honest Mode.
 
 ## Quick Start
 
@@ -50,15 +50,15 @@ sks selftest --mock
 | Skill dreaming | Records cheap generated-skill usage counters in JSON and only periodically scans `.agents/skills` for keep, merge, prune, and improvement candidates. Reports are recommendation-only and never delete skills automatically. |
 | From-Chat-IMG | Turns chat screenshots plus original attachments into source-bound work orders, then requires scoped QA evidence before completion. |
 | QA loop | Dogfoods UI/API behavior with safety gates, Codex Computer Use-only UI evidence, safe fixes, and rechecks. |
-| PPT pipeline | Uses `$PPT` for simple, restrained, information-first HTML/PDF presentation artifacts, first asking delivery context, audience profile, STP strategy, decision context, and 3+ pain-point to solution/aha mappings before source research, design-system work, HTML/PDF export, and render QA. Independent strategy/render/file-write phases run in parallel where inputs allow and are recorded in `ppt-parallel-report.json`; editable source HTML is preserved under `source-html/`, PPT-only temporary build files are cleaned after completion, installed skills/MCPs outside the `$PPT` allowlist are ignored, generated image assets must use real `$imagegen`/`gpt-image-2` output when sealed in the contract, and `ppt-style-tokens.json` records the design SSOT plus fused source inputs. |
-| Image UX Review | Uses `$Image-UX-Review` / `$UX-Review` for UI/UX audits where source screenshots are first turned into generated annotated review images through Codex App `$imagegen`/`gpt-image-2`; those generated images are then read back into `image-ux-issue-ledger.json`, optional requested fixes are rechecked, and missing generated review images or text-only screenshot critique cannot pass `image-ux-review-gate.json`. |
+| PPT pipeline | Uses `$PPT` for restrained HTML/PDF presentation artifacts with sealed delivery context, audience, STP, decision context, source research, design SSOT, export QA, editable source HTML, and real `$imagegen` assets when required. |
+| Image UX Review | Uses `$Image-UX-Review` / `$UX-Review` for UI/UX audits that require generated annotated review images through Codex App `$imagegen`/`gpt-image-2` before issue extraction and optional rechecks. |
 | Computer Use fast lane | Uses `$Computer-Use` / `$CU` for UI/browser/visual work that needs maximum speed: skip Team debate and upfront TriWiki loops, use Codex Computer Use directly, then refresh/validate TriWiki and run Honest Mode at final closeout. |
-| Goal | Provides a fast SKS bridge overlay for Codex native persisted `/goal` create, pause, resume, and clear controls; an ambient non-disruptive Goal continuation overlay is also recorded in normal pipeline plans while implementation continues through the selected SKS execution route. |
+| Goal | Bridges Codex native `/goal` create, pause, resume, and clear controls while implementation continues through the selected SKS route. |
 | TriWiki voxels | Maintains `.sneakoscope/wiki/context-pack.json` as the context SSOT with coordinate anchors, voxel metadata, `attention.use_first`, `attention.hydrate_first`, and prompt-bound mistake recall ledgers. |
 | Context7 | Requires current docs for external packages, APIs, MCPs, SDKs, and framework/runtime behavior when correctness depends on current guidance. |
 | Design SSOT | Treats `design.md` as the only design decision source of truth. `docs/Design-Sys-Prompt.md` is the builder prompt; getdesign.md, official getdesign docs, and curated DESIGN.md examples from `VoltAgent/awesome-design-md` are source inputs that must be fused into `design.md` or route-local style tokens instead of becoming parallel authorities. |
 | 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. |
+| Release hygiene | Checks versioning, changelog, package size, syntax, selftests. |
 
 ## Requirements
 
@@ -171,7 +171,7 @@ Bare `sks` creates or reuses the default named tmux session for Codex CLI and at
 
 Before opening tmux, SKS checks the installed Codex CLI against npm `@openai/codex@latest`. If a newer version exists, it asks `Y/n`; answering `y` updates automatically with `npm i -g @openai/codex@latest` and then opens tmux with the updated Codex CLI.
 
-If you use [codex-lb](https://github.com/Soju06/codex-lb), start it first, create an API key in its dashboard, then run:
+For [codex-lb](https://github.com/Soju06/codex-lb), start the server, create a dashboard API key, then run:
 
 ```sh
 sks codex-lb setup --host https://your-codex-lb.example.com --api-key "sk-clb-..."
@@ -179,30 +179,9 @@ sks codex-lb repair
 sks
 ```
 
-Bare `sks` asks this before opening Codex when codex-lb is not configured:
+Bare `sks` can also prompt for codex-lb auth before launch; SKS stores the key in `~/.codex/sks-codex-lb.env`, syncs `codex login --with-api-key`, and loads it into a fresh tmux session.
 
-```text
-Authenticate and route Codex through codex-lb? [y/N]
-```
-
-Answering `y` asks for the hosted domain and API key, writes `~/.codex/config.toml`, stores the key in `~/.codex/sks-codex-lb.env` with mode `0600`, syncs Codex CLI API-key auth through `codex login --with-api-key`, and sources that env file before launching Codex in tmux. When codex-lb is configured from this prompt, SKS opens a fresh tmux session for that launch so the new key is loaded by the Codex process immediately. SKS keeps Codex App Fast mode visible and defaulted by writing top-level `model = "gpt-5.5"`, `service_tier = "fast"`, `[features].fast_mode = true`, and the `sks-fast-high` profile while removing legacy top-level reasoning locks; route-specific reasoning stays in named profiles or explicit tmux launch args.
-
-If Codex CLI auth drifts after a tmux/MAD launch, run `sks codex-lb repair` or `sks auth repair`. This reuses the stored `~/.codex/sks-codex-lb.env` key and re-syncs Codex CLI API-key auth without asking for the key again. To replace the key or host, run `sks codex-lb reconfigure --host <domain> --api-key <key>`.
-
-The generated provider config follows the codex-lb README's Codex CLI API-key setup:
-
-```toml
-model_provider = "codex-lb"
-service_tier = "fast"
-
-[model_providers.codex-lb]
-name = "OpenAI"
-base_url = "http://127.0.0.1:2455/backend-api/codex"
-wire_api = "responses"
-env_key = "CODEX_LB_API_KEY"
-supports_websockets = true
-requires_openai_auth = true
-```
+If Codex CLI auth drifts after a launch or reinstall, run `sks codex-lb repair`; to replace it, run `sks codex-lb reconfigure --host <domain> --api-key <key>`.
 
 ### MAD tmux Launch
 

package/package.json

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

package/src/cli/install-helpers.mjs

@@ -6,7 +6,7 @@ import { stdin as input, stdout as output } from 'node:process';
 import { ensureDir, exists, globalSksRoot, packageRoot, readText, runProcess, which, writeTextAtomic } from '../core/fsx.mjs';
 import { getCodexInfo } from '../core/codex-adapter.mjs';
 import { formatHarnessConflictReport, llmHarnessCleanupPrompt, scanHarnessConflicts } from '../core/harness-conflicts.mjs';
-import { installSkills } from '../core/init.mjs';
+import { initProject, installSkills } from '../core/init.mjs';
 import { context7ConfigToml, DOLLAR_SKILL_NAMES, GETDESIGN_REFERENCE, hasContext7ConfigText, RECOMMENDED_SKILLS } from '../core/routes.mjs';
 import { codexLaunchCommand, platformTmuxInstallHint, tmuxReadiness } from '../core/tmux-ui.mjs';
 
@@ -869,6 +869,12 @@ export async function selftestCodexLb(tmp) {
   const codexLbEnv = await safeReadText(path.join(codexLbHome, '.codex', 'sks-codex-lb.env'));
   const codexLbAuth = await safeReadText(path.join(codexLbHome, '.codex', 'auth.json'));
   if (!codexLbSetupJson.ok || codexLbSetupJson.base_url !== 'https://lb.example.test/backend-api/codex' || !codexLbConfig.includes('model_provider = "codex-lb"') || !codexLbConfig.includes('[model_providers.codex-lb]') || !codexLbEnv.includes("CODEX_LB_API_KEY='sk-test'") || !/(\"auth_mode\"\s*:\s*\"apikey\")/.test(codexLbAuth)) throw new Error('selftest failed: codex-lb setup did not write provider config, env key, and Codex API-key auth');
+  await writeTextAtomic(path.join(codexLbHome, '.codex', 'config.toml'), `${codexLbConfig}\n[mcp_servers.supabase]\nurl = "https://mcp.supabase.com/mcp?project_ref=ref&read_only=true&features=database,docs"\n`);
+  const ptmp = path.join(tmp, 'codex-lb-project-config'), prevHome = process.env.HOME;
+  try { process.env.HOME = codexLbHome; await initProject(ptmp, { installScope: 'global' }); }
+  finally { if (prevHome === undefined) delete process.env.HOME; else process.env.HOME = prevHome; }
+  const pcfg = await safeReadText(path.join(ptmp, '.codex', 'config.toml'));
+  if (!pcfg.includes('model_provider = "codex-lb"') || !pcfg.includes('[model_providers.codex-lb]') || !pcfg.includes('[mcp_servers.supabase]') || !pcfg.includes('read_only=true')) throw new Error('selftest failed: project bootstrap lost global codex-lb or MCP config');
   await writeTextAtomic(path.join(codexLbHome, '.codex', 'auth.json'), '{"auth_mode":"browser"}\n');
   const codexLbRepair = await runProcess(process.execPath, [path.join(packageRoot(), 'bin', 'sks.mjs'), 'auth', 'repair', '--json'], { cwd: tmp, env: codexLbEnvForSelftest, timeoutMs: 15000, maxOutputBytes: 64 * 1024 });
   if (codexLbRepair.code !== 0) throw new Error(`selftest failed: codex-lb repair exited ${codexLbRepair.code}: ${codexLbRepair.stderr}`);

package/src/cli/main.mjs

@@ -2010,10 +2010,26 @@ async function selftest() {
   };
   for (let i = 0; i < 5; i++) {
     const stop = await evaluateStop(tmp, clarificationState, { last_assistant_message: 'continuing implementation without visible questions' });
-    if (stop?.gate === 'clarification' || /ambiguity|clarification|question/i.test(String(stop?.reason || ''))) throw new Error('selftest failed: stale clarification gate still hard-paused without visible questions');
+    if (stop?.decision !== 'block' || stop?.gate !== 'clarification' || !/paused|answers|pipeline answer/i.test(String(stop?.reason || ''))) throw new Error('selftest failed: clarification not paused');
   }
-  const visibleQuestionStop = await evaluateStop(tmp, clarificationState, { last_assistant_message: 'Required questions still pending:\n1. GOAL_PRECISE: What should be changed?\n\nReply by slot id; I will seal the contract with sks pipeline answer latest --stdin.' });
-  if (visibleQuestionStop?.gate === 'clarification' || /ambiguity|clarification/i.test(String(visibleQuestionStop?.reason || ''))) throw new Error('selftest failed: visible stale clarification wording still blocked stop');
+  if (await exists(path.join(clarificationMission.dir, 'hard-blocker.json'))) throw new Error('selftest failed: clarification wrote hard-blocker');
+  const visibleQuestionStop = await evaluateStop(tmp, clarificationState, { last_assistant_message: 'Required questions\n1. GOAL_PRECISE\nsks pipeline answer latest --stdin' });
+  if (visibleQuestionStop?.continue !== true) throw new Error('selftest failed: visible clarification did not wait');
+  const cg = await projectGateStatus(tmp, clarificationState);
+  if (!cg.blockers.includes('clarification-gate:explicit_user_answers') || !cg.blockers.includes('clarification-gate:pipeline_answer')) throw new Error('selftest failed: missing clarification blockers');
+  await setCurrent(tmp, clarificationState);
+  const hookPath = path.join(packageRoot(), 'bin', 'sks.mjs');
+  const blockedPre = await runProcess(process.execPath, [hookPath, 'hook', 'pre-tool'], { cwd: tmp, input: JSON.stringify({ cwd: tmp, tool_name: 'Bash', tool_input: { command: 'npm run selftest' } }), timeoutMs: 15000, maxOutputBytes: 64 * 1024 });
+  if (blockedPre.code !== 0) throw new Error(`selftest failed: pre-tool exit ${blockedPre.code}: ${blockedPre.stderr}`);
+  const bp = JSON.parse(blockedPre.stdout || '{}');
+  if (bp.decision !== 'block' || !String(bp.reason || '').includes('waiting for explicit user answers')) throw new Error('selftest failed: pre-tool not blocked');
+  const deniedPermission = await runProcess(process.execPath, [hookPath, 'hook', 'permission-request'], { cwd: tmp, input: JSON.stringify({ cwd: tmp, command: 'npm run selftest', action: 'Run command' }), timeoutMs: 15000, maxOutputBytes: 64 * 1024 });
+  if (deniedPermission.code !== 0) throw new Error(`selftest failed: permission exit ${deniedPermission.code}: ${deniedPermission.stderr}`);
+  const dp = JSON.parse(deniedPermission.stdout || '{}');
+  if (dp.hookSpecificOutput?.decision?.behavior !== 'deny' || !String(dp.hookSpecificOutput?.decision?.message || '').includes('waiting for explicit user answers')) throw new Error('selftest failed: permission not denied');
+  const answerTool = await runProcess(process.execPath, [hookPath, 'hook', 'pre-tool'], { cwd: tmp, input: JSON.stringify({ cwd: tmp, tool_name: 'Bash', tool_input: { command: `sks pipeline answer ${clarificationMission.id} --stdin` } }), timeoutMs: 15000, maxOutputBytes: 64 * 1024 });
+  if (answerTool.code !== 0) throw new Error(`selftest failed: answer hook exit ${answerTool.code}: ${answerTool.stderr}`);
+  if (JSON.parse(answerTool.stdout || '{}').decision === 'block') throw new Error('selftest failed: answer command blocked');
   await setCurrent(tmp, loopState);
   const dfixPromptHook = await runProcess(process.execPath, [path.join(packageRoot(), 'bin', 'sks.mjs'), 'hook', 'user-prompt-submit'], {
     cwd: tmp,
@@ -3275,7 +3291,9 @@ async function selftest() {
   await writeTextAtomic(fakeTmuxBin, `#!/usr/bin/env node\nconst fs = require('node:fs');\nconst log = process.env.SKS_FAKE_TMUX_LOG;\nif (log) fs.appendFileSync(log, process.argv.slice(2).join(' ') + '\\n');\nconst cmd = process.argv[2];\nif (cmd === 'has-session') process.exit(0);\nif (cmd === 'kill-session') process.exit(0);\nif (cmd === 'kill-pane') process.exit(0);\nif (cmd === 'new-session') { console.log('%1'); process.exit(0); }\nif (cmd === 'split-window') { console.log(process.env.SKS_FAKE_TMUX_SPLIT_ID || '%2'); process.exit(0); }\nif (cmd === 'list-windows') { console.log('@1'); process.exit(0); }\nif (cmd === 'display-message') { console.log(process.env.SKS_FAKE_TMUX_DISPLAY || 'sks-existing-selftest\\t@1\\t%1'); process.exit(0); }\nif (cmd === 'list-panes') { console.log(process.env.SKS_FAKE_TMUX_LIST || ''); process.exit(0); }\nif (cmd === 'set-option' || cmd === 'select-layout' || cmd === 'resize-window' || cmd === 'set-window-option' || cmd === 'set-hook') process.exit(0);\nprocess.exit(0);\n`);
   await fsp.chmod(fakeTmuxBin, 0o755);
   const previousFakeTmuxLog = process.env.SKS_FAKE_TMUX_LOG;
+  const previousPath = process.env.PATH;
   process.env.SKS_FAKE_TMUX_LOG = fakeTmuxLog;
+  process.env.PATH = `${fakeTmuxDir}${path.delimiter}${previousPath || ''}`;
   const recreatedTmux = await createTmuxSession({ root: tmp, session: 'sks-existing-selftest', tmux: { bin: fakeTmuxBin }, codex: { bin: process.execPath } }, [
     { cwd: tmp, command: 'pwd', role: 'overview' },
     { cwd: tmp, command: 'pwd', role: 'lane' }
@@ -3332,6 +3350,8 @@ async function selftest() {
   if (!madCockpit.created || madCockpit.mode !== 'mad_session' || madCockpit.opened?.panes?.length !== 1 || !madTmuxLogText.includes('new-session') || madTmuxLogText.includes('split-window')) throw new Error('selftest failed: MAD tmux launch should create one pane and leave split panes to Team lanes');
   if (previousFakeTmuxLog === undefined) delete process.env.SKS_FAKE_TMUX_LOG;
   else process.env.SKS_FAKE_TMUX_LOG = previousFakeTmuxLog;
+  if (previousPath === undefined) delete process.env.PATH;
+  else process.env.PATH = previousPath;
   const codexLaunchArgs = defaultCodexLaunchArgs({ SKS_CODEX_REASONING: 'low' }).join(' ');
   if (!codexLaunchArgs.includes('service_tier="fast"') || !codexLaunchArgs.includes('model_reasoning_effort="low"')) throw new Error('selftest failed: Codex tmux launch args do not force Fast service tier plus dynamic reasoning');
   await initTeamLive(teamId, teamDir, '역할 팀 테스트', { agentSessions: roleTeamPlan.agent_session_count, roleCounts: roleTeamPlan.role_counts, roster: roleTeamPlan.roster });
@@ -3422,7 +3442,7 @@ async function selftest() {
   if (!teamLive.includes('Context tracking SSOT: TriWiki')) throw new Error('selftest failed: team live transcript missing TriWiki context tracking');
   if (!(await readTeamTranscriptTail(teamDir, 1)).join('\n').includes('selftest mapped options')) throw new Error('selftest failed: team transcript tail missing event');
   const teamLane = await renderTeamAgentLane(teamDir, { missionId: teamId, agent: 'analysis_scout_1', lines: 4 });
-  if (!teamLane.includes('SKS Team Agent Lane') || !teamLane.includes('analysis_scout_1') || !teamLane.includes('selftest mapped repo slice')) throw new Error('selftest failed: team agent lane missing agent event context');
+  if (!teamLane.includes('selftest mapped repo slice')) throw new Error('selftest failed: team agent lane missing event context');
   const teamLaneCli = await runProcess(process.execPath, [hookBin, 'team', 'lane', teamId, '--agent', 'analysis_scout_1', '--lines', '4'], { cwd: tmp, env: { SKS_DISABLE_UPDATE_CHECK: '1' }, timeoutMs: 15000, maxOutputBytes: 64 * 1024 });
   if (teamLaneCli.code !== 0 || !String(teamLaneCli.stdout || '').includes('SKS Team Agent Lane') || !String(teamLaneCli.stdout || '').includes('analysis_scout_1')) throw new Error('selftest failed: sks team lane CLI did not render an agent lane');
   await writeTextAtomic(path.join(teamDir, 'team-analysis.md'), '- claim: analysis scout mapped route registry | source: src/core/routes.mjs | risk: high | confidence: supported\n');

package/src/cli/maintenance-commands.mjs

@@ -1,6 +1,6 @@
 import path from 'node:path';
 import fsp from 'node:fs/promises';
-import { readJson, writeJsonAtomic, writeTextAtomic, appendJsonlBounded, nowIso, exists, ensureDir, packageRoot, dirSize, formatBytes, PACKAGE_VERSION, sksRoot } from '../core/fsx.mjs';
+import { readJson, writeJsonAtomic, writeTextAtomic, appendJsonlBounded, nowIso, exists, ensureDir, packageRoot, dirSize, formatBytes, PACKAGE_VERSION, sksRoot, readStdin } from '../core/fsx.mjs';
 import { initProject } from '../core/init.mjs';
 import { getCodexInfo, runCodexExec } from '../core/codex-adapter.mjs';
 import { createMission, loadMission, findLatestMission, missionDir, setCurrent, stateFile } from '../core/mission.mjs';
@@ -640,7 +640,7 @@ export async function dbCommand(sub, args = []) {
     return;
   }
   if (sub === 'scan-payload') {
-    const raw = await fsp.readFile(0, 'utf8');
+    const raw = await readStdin();
     const payload = raw.trim() ? JSON.parse(raw) : {};
     const decision = await checkDbOperation(root, {}, payload, { duringNoQuestion: false });
     console.log(JSON.stringify(decision, null, 2));

package/src/core/db-safety.mjs

@@ -204,7 +204,7 @@ function recursivelyCollectStrings(obj, out = [], depth = 0) {
   if (Array.isArray(obj)) { for (const x of obj) recursivelyCollectStrings(x, out, depth + 1); return out; }
   if (typeof obj === 'object') {
     for (const [k, v] of Object.entries(obj)) {
-      if (/^(sql|query|statement|command|migration|body|input|text)$/i.test(k) || typeof v === 'object') recursivelyCollectStrings(v, out, depth + 1);
+      if (/^(sql|query|statement|command|migration|body|input|text|action|purpose|intent|description)$/i.test(k) || typeof v === 'object') recursivelyCollectStrings(v, out, depth + 1);
     }
   }
   return out;
@@ -216,6 +216,12 @@ function looksLikeSqlText(text = '') {
     || /;\s*(select|with|show|explain|describe|insert|update|delete|drop|truncate|alter|create|grant|revoke)\b/i.test(s);
 }
 
+function hasReadOnlyDbInspectionIntent(text = '') {
+  const s = String(text || '').toLowerCase();
+  if (/\b(insert|update|delete|drop|truncate|alter|create|grant|revoke|write|mutate|migration|apply|push|reset|repair)\b|삭제|수정|변경|쓰기|삽입|생성|초기화|적용/i.test(s)) return false;
+  return /\b(read.?only|select|with|show|explain|describe|inspect|list|get|fetch|count|schema)\b|조회|확인|읽|보기|목록|스키마/i.test(s);
+}
+
 export function classifyToolPayload(payload = {}) {
   const strings = recursivelyCollectStrings(payload).slice(0, 200);
   const toolName = [payload.tool_name, payload.toolName, payload.name, payload.tool?.name, payload.server, payload.mcp_tool, payload.tool, payload.type].filter(Boolean).join(' ').toLowerCase();
@@ -241,7 +247,14 @@ export function classifyToolPayload(payload = {}) {
   }
   if (toolReasons.includes('dangerous_supabase_management_tool')) level = 'destructive';
   if (toolReasons.includes('migration_apply_tool') && level !== 'destructive') level = 'write';
-  if (toolReasons.includes('database_tool') && level === 'none') level = 'possible_db';
+  if (toolReasons.includes('database_tool') && level === 'none') {
+    if (hasReadOnlyDbInspectionIntent([toolName, ...strings].join(' '))) {
+      level = 'safe';
+      reasons.push('read_only_database_inspection_intent');
+    } else {
+      level = 'possible_db';
+    }
+  }
   return { level, toolName, toolReasons, reasons, sql: sqlClass, command: commandClass, stringsExamined: strings.length };
 }
 

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.7.64';
+export const PACKAGE_VERSION = '0.7.66';
 export const DEFAULT_PROCESS_TAIL_BYTES = 256 * 1024;
 export const DEFAULT_PROCESS_TIMEOUT_MS = 30 * 60 * 1000;
 

package/src/core/hooks-runtime.mjs

@@ -181,14 +181,17 @@ async function hookUserPrompt(root, state, payload, noQuestion) {
 }
 
 function isClarificationAwaiting(state = {}) {
-  return Boolean(state.clarification_required && String(state.phase || '').includes('CLARIFICATION_AWAITING_ANSWERS'))
-    || ['QALOOP_CLARIFICATION_AWAITING_ANSWERS'].includes(String(state.phase || ''));
+  const phase = String(state.phase || '');
+  const stopGate = String(state.stop_gate || '');
+  const gateAwaiting = phase.includes('CLARIFICATION_AWAITING_ANSWERS') || stopGate === 'clarification-gate';
+  if (!gateAwaiting) return false;
+  if (!state?.mission_id) return false;
+  if (state.ambiguity_gate_required !== true || state.ambiguity_gate_passed === true) return false;
+  return Boolean(state.clarification_required || state.implementation_allowed === false);
 }
 
 function isBlockingClarificationAwaiting(state = {}) {
-  if (!isClarificationAwaiting(state)) return false;
-  return ['QALoop', 'PPT'].includes(String(state.route || ''))
-    || ['QALOOP', 'PPT'].includes(String(state.mode || ''));
+  return isClarificationAwaiting(state);
 }
 
 function looksLikeClarificationCancel(prompt = '') {
@@ -316,7 +319,7 @@ function clarificationGateLocked(state = {}) {
     && state.implementation_allowed === false
     && state.ambiguity_gate_required === true
     && state.ambiguity_gate_passed !== true
-    && isBlockingClarificationAwaiting(state)
+    && (String(state.phase || '').includes('CLARIFICATION_AWAITING_ANSWERS') || String(state.stop_gate || '') === 'clarification-gate')
   );
 }
 

package/src/core/init.mjs

@@ -462,6 +462,34 @@ function mergeManagedCodexConfigToml(existingContent = '') {
   return `${next.trim()}\n`;
 }
 
+async function mergeGlobalCodexConfigIfAvailable(configText = '', configPath = '') {
+  const selectedRe = /(^|\n)\s*model_provider\s*=\s*"codex-lb"\s*(?:#.*)?(?=\n|$)/;
+  const home = process.env.HOME || '';
+  if (!home) return configText;
+  const globalConfigPath = path.join(home, '.codex', 'config.toml');
+  if (configPath && path.resolve(configPath) === path.resolve(globalConfigPath)) return configText;
+  const globalConfig = await readText(globalConfigPath, '');
+  let next = mergeGlobalMcpServers(configText, globalConfig);
+  if (selectedRe.test(next) && /\[model_providers\.codex-lb\]/.test(next)) return `${String(next || '').trim()}\n`;
+  if (!(await exists(path.join(home, '.codex', 'sks-codex-lb.env')))) return next;
+  const baseUrl = globalConfig.match(/(^|\n)\[model_providers\.codex-lb\][\s\S]*?\n\s*base_url\s*=\s*"([^"]+)"/)?.[2];
+  if (!selectedRe.test(globalConfig) || !baseUrl) return next;
+  next = upsertTopLevelTomlString(next, 'model_provider', 'codex-lb');
+  next = upsertTomlTable(next, 'model_providers.codex-lb', `[model_providers.codex-lb]\nname = "OpenAI"\nbase_url = "${baseUrl}"\nwire_api = "responses"\nenv_key = "CODEX_LB_API_KEY"\nsupports_websockets = true\nrequires_openai_auth = true`);
+  return `${next.trim()}\n`;
+}
+
+function mergeGlobalMcpServers(configText = '', globalConfig = '') {
+  let next = configText;
+  const re = /(?:^|\n)(\[(mcp_servers\.[^\]\r\n]+)\][\s\S]*?)(?=\n\[[^\]]+\]|\s*$)/g;
+  for (const match of String(globalConfig || '').matchAll(re)) {
+    const block = match[1].trim();
+    const table = match[2].trim();
+    if (!new RegExp(`(^|\\n)\\[${escapeRegExp(table)}\\]`).test(next)) next = upsertTomlTable(next, table, block);
+  }
+  return next;
+}
+
 function removeLegacyTopLevelCodexModeLocks(text = '') {
   const legacy = {
     model_reasoning_effort: new Set(['high'])
@@ -619,7 +647,11 @@ function upsertTomlTable(text, table, block) {
 
   const generatedCodexConfigPath = path.join(root, '.codex', 'config.toml');
   const existingCodexConfig = await readText(generatedCodexConfigPath, '');
-  await writeTextAtomic(generatedCodexConfigPath, mergeManagedCodexConfigToml(existingCodexConfig));
+  const managedCodexConfig = await mergeGlobalCodexConfigIfAvailable(
+    mergeManagedCodexConfigToml(existingCodexConfig),
+    generatedCodexConfigPath
+  );
+  await writeTextAtomic(generatedCodexConfigPath, managedCodexConfig);
   created.push('.codex/config.toml');
 
   await writeTextAtomic(path.join(root, '.codex', 'SNEAKOSCOPE.md'), codexAppQuickReference(installScope, hookCommandPrefix));

package/src/core/pipeline.mjs

@@ -509,8 +509,7 @@ export async function activeRouteContext(root, state) {
     return `SKS Honest Mode found unresolved gaps for ${state.route_command || state.route || state.mode}. Do not ask ambiguity questions again. Continue from the sealed decision-contract.json, inspect .sneakoscope/missions/${state.mission_id}/honest-loopback.json, fix gaps, rerun verification, refresh/validate TriWiki, then retry final Honest Mode.${reasoningNote}${planNote}`;
   }
   if (state.clarification_required && String(state.phase || '').includes('CLARIFICATION_AWAITING_ANSWERS')) {
-    if (['QALoop', 'PPT'].includes(String(state.route || '')) || ['QALOOP', 'PPT'].includes(String(state.mode || ''))) return clarificationAwaitingAnswersContext(root, state);
-    return `Previous ${state.route_command || state.route || state.mode || 'SKS'} clarification state is non-blocking. Do not reprint old question sheets; prepare the current prompt normally and replace stale route state when needed.`;
+    return clarificationAwaitingAnswersContext(root, state);
   }
   if (state.clarification_passed && String(state.phase || '').includes('CLARIFICATION_CONTRACT_SEALED')) {
     return `Route contract sealed for ${state.route_command || state.route || state.mode}. Use decision-contract.json and ${PIPELINE_PLAN_ARTIFACT} before executing the route. Before the next route phase, read relevant TriWiki context, hydrate low-trust claims from source, and refresh/validate TriWiki again after new findings or artifact changes. Next atomic action: continue the original route lifecycle with the inferred goal, constraints, non-goals, risk boundary, and test scope.${planNote}`;
@@ -993,7 +992,7 @@ async function clarificationAwaitingAnswersContext(root, state) {
   const id = state.mission_id;
   if (!id) return '';
   const planNote = await activePipelinePlanNote(root, state);
-  return `Active SKS route ${state.route_command || state.route || state.mode} has stale prequestion state. Do not reprint old question sheets. Re-prepare the current prompt so the route auto-seals from prompt, TriWiki/current-code defaults, and conservative SKS policy, or seal the existing mission internally with "sks pipeline answer ${id} --stdin" using inferred answers.${planNote}`;
+  return `Active SKS route ${state.route_command || state.route || state.mode} is paused at its ambiguity gate and waiting for explicit user answers. Do not advance to implementation, tests, route materialization, or a new pipeline stage. If the user's reply is now available, seal it with "sks pipeline answer ${id} --stdin"; otherwise show only the missing slot ids from .sneakoscope/missions/${id}/questions.md and wait.${planNote}`;
 }
 
 function clarificationVisibleResponseContract(id) {
@@ -1031,9 +1030,9 @@ async function clarificationStopReason(root, state, kind) {
   const files = state?.mission_id ? `
 Answer schema: .sneakoscope/missions/${state.mission_id}/required-answers.schema.json` : '';
   const command = `sks pipeline answer ${id} --stdin`;
-  const title = `SKS ${routeName} has stale prequestion state.`;
+  const title = `SKS ${routeName} is paused for explicit user answers.`;
   return `${title}
-Do not reprint old question sheets. Seal internally with inferred answers using "${command}", or re-prepare the current prompt so the route auto-seals.${files}
+Do not continue to implementation or the next pipeline stage until the ambiguity gate is sealed. Ask only the missing slot ids if they have not already been shown, then wait for the user. When the user's reply is available, seal it with "${command}".${files}
 
 After the contract is sealed, continue the original ${routeName} route.`;
 }
@@ -1329,7 +1328,15 @@ export async function evaluateStop(root, state, payload, opts = {}) {
 }
 
 function clarificationGatePending(state = {}) {
-  return false;
+  const phase = String(state.phase || '');
+  return Boolean(state?.clarification_required && phase.includes('CLARIFICATION_AWAITING_ANSWERS'))
+    || Boolean(
+      state?.mission_id
+      && state.implementation_allowed === false
+      && state.ambiguity_gate_required === true
+      && state.ambiguity_gate_passed !== true
+      && (phase.includes('CLARIFICATION_AWAITING_ANSWERS') || state.stop_gate === 'clarification-gate')
+    );
 }
 
 async function complianceBlock(root, state = {}, reason = '', detail = {}) {

package/src/core/team-live.mjs

@@ -6,6 +6,7 @@ export { MIN_TEAM_REVIEWER_LANES, MIN_TEAM_REVIEW_POLICY_TEXT, MIN_TEAM_REVIEW_S
 
 const MAX_LIVE_BYTES = 192 * 1024;
 const TEAM_RUNTIME_TASKS_ARTIFACT = 'team-runtime-tasks.json';
+const TEAM_SESSION_CLEANUP_ARTIFACT = 'team-session-cleanup.json';
 const DEFAULT_AGENTS = ['parent_orchestrator', 'analysis_scout', 'team_consensus', 'implementation_worker', 'db_safety_reviewer', 'qa_reviewer'];
 export const DEFAULT_TEAM_ROLE_COUNTS = { user: 1, planner: 1, reviewer: MIN_TEAM_REVIEWER_LANES, executor: 3 };
 export const DEFAULT_MAX_TEAM_AGENT_SESSIONS = 6;
@@ -471,7 +472,19 @@ async function reconcileTeamTmuxFromEvent(dir, record = {}) {
 }
 
 export async function readTeamControl(dir) {
-  return readJson(teamLogPaths(dir).control, defaultTeamControl(path.basename(dir)));
+  const control = await readJson(teamLogPaths(dir).control, defaultTeamControl(path.basename(dir)));
+  const cleanup = await readJson(path.join(dir, TEAM_SESSION_CLEANUP_ARTIFACT), null).catch(() => null);
+  if (!cleanup || (cleanup.passed !== true && cleanup.live_transcript_finalized !== true && cleanup.all_sessions_closed !== true)) return control;
+  return {
+    ...defaultTeamControl(path.basename(dir)),
+    ...control,
+    status: 'ended',
+    cleanup_requested: true,
+    cleanup_requested_at: cleanup.updated_at || cleanup.completed_at || cleanup.closed_at || control.cleanup_requested_at || 'artifact',
+    cleanup_requested_by: cleanup.agent || control.cleanup_requested_by || 'parent_orchestrator',
+    cleanup_reason: cleanup.reason || control.cleanup_reason || `${TEAM_SESSION_CLEANUP_ARTIFACT} passed.`,
+    final_message: cleanup.final_message || control.final_message || 'Team session ended. Lane follow loops stop and managed tmux Team panes should close.'
+  };
 }
 
 export async function requestTeamSessionCleanup(dir, opts = {}) {
@@ -532,26 +545,30 @@ export async function renderTeamAgentLane(dir, opts = {}) {
   const missionId = opts.missionId || dashboard?.mission_id || runtime?.mission_id || path.basename(dir);
   const status = dashboard?.agents?.[agent] || {};
   const runtimeTasks = Array.isArray(runtime?.tasks) ? runtime.tasks : Array.isArray(runtime) ? runtime : [];
-  const assignedTasks = runtimeTasks.filter((task) => task?.worker === agent || task?.agent_hint === agent);
   const eventWindow = await readTeamTranscriptTail(dir, Math.max(lines * 8, 80));
   const parsedWindow = eventWindow.map(parseTranscriptLine).filter(Boolean);
-  const agentEvents = parsedWindow.filter((event) => event?.agent === agent || eventAddressedTo(event, agent)).slice(-lines);
-  const directMessages = parsedWindow.filter((event) => event?.type === 'message' && eventAddressedTo(event, agent)).slice(-lines);
-  const globalTail = (await readTeamTranscriptTail(dir, lines)).map(parseTranscriptLine).filter(Boolean);
+  const aliases = teamLaneAliases(agent, parsedWindow, dashboard, runtimeTasks);
+  const aliasSet = new Set(aliases);
+  const statusAliases = aliases.length > 1 ? [...aliases.slice(1), aliases[0]] : aliases;
+  const laneStatus = statusAliases.map((id) => dashboard?.agents?.[id]).find((entry) => entry && entry.status && entry.status !== 'pending') || status;
+  const assignedTasks = runtimeTasks.filter((task) => aliasSet.has(task?.worker) || aliasSet.has(task?.agent_hint));
+  const agentEvents = parsedWindow.filter((event) => aliasSet.has(event?.agent) || aliases.some((id) => eventAddressedTo(event, id))).slice(-lines);
+  const directMessages = parsedWindow.filter((event) => event?.type === 'message' && aliases.some((id) => eventAddressedTo(event, id))).slice(-lines);
   const laneStyle = teamLaneTextStyle(agent);
   return [
     `# SKS Team Agent Lane`,
     '',
     `Mission: ${missionId}`,
     `Agent: ${agent}`,
+    aliases.length > 1 ? `Mirrored agents: ${aliases.slice(1).join(', ')}` : null,
     `Lane color: ${laneStyle.color_name}`,
     `Requested phase: ${phase || 'any'}`,
     teamCleanupRequested(control) ? `Cleanup: requested at ${control.cleanup_requested_at || 'unknown'}` : null,
     '',
     `## Agent Status`,
-    `- status: ${status.status || 'pending'}`,
-    `- phase: ${status.phase || 'unknown'}`,
-    `- last_seen: ${status.last_seen || 'never'}`,
+    `- status: ${laneStatus.status || 'pending'}`,
+    `- phase: ${laneStatus.phase || 'unknown'}`,
+    `- last_seen: ${laneStatus.last_seen || 'never'}`,
     '',
     `## Assigned Runtime Tasks`,
     ...(runtime ? formatRuntimeTasks(assignedTasks) : ['- team-runtime-tasks.json not available yet.']),
@@ -561,9 +578,11 @@ export async function renderTeamAgentLane(dir, opts = {}) {
     '',
     `## Direct Messages`,
     ...(directMessages.length ? directMessages.map(formatTranscriptEvent) : ['- No direct or broadcast messages in the bounded tail.']),
-    '',
-    `## Fallback Global Tail`,
-    ...(globalTail.length ? globalTail.map(formatTranscriptEvent) : ['- No transcript events yet.']),
+    opts.includeGlobalTail ? '' : null,
+    opts.includeGlobalTail ? `## Global Tail` : null,
+    ...(opts.includeGlobalTail
+      ? (await readTeamTranscriptTail(dir, lines)).map(parseTranscriptLine).filter(Boolean).map(formatTranscriptEvent)
+      : []),
     teamCleanupRequested(control) ? ['', renderTeamCleanupSummary(control)].join('\n') : null
   ].filter((line) => line !== null).join('\n');
 }
@@ -685,6 +704,32 @@ function eventAddressedTo(event = {}, agent = '') {
   return target === name || target === 'all' || target === '*' || target === 'broadcast';
 }
 
+function teamLaneAliases(agent = '', events = [], dashboard = null, runtimeTasks = []) {
+  const primary = String(agent || '').trim();
+  if (!primary) return [];
+  const aliases = [primary];
+  const ordinal = numberedLaneOrdinal(primary);
+  if (!ordinal) return aliases;
+  const role = teamLaneTextStyle(primary).role;
+  const candidates = uniqueAgentIds([
+    ...Object.keys(dashboard?.agents || {}),
+    ...events.map((event) => event?.agent).filter(Boolean),
+    ...runtimeTasks.flatMap((task) => [task?.worker, task?.agent_hint]).filter(Boolean)
+  ])
+    .filter((id) => id !== primary)
+    .filter((id) => !DEFAULT_AGENTS.includes(id))
+    .filter((id) => teamLaneTextStyle(id).role === role)
+    .filter((id) => !numberedLaneOrdinal(id));
+  const concrete = candidates[ordinal - 1];
+  if (concrete) aliases.push(concrete);
+  return aliases;
+}
+
+function numberedLaneOrdinal(agent = '') {
+  const match = String(agent || '').match(/_(\d+)$/);
+  return match ? Number(match[1]) : 0;
+}
+
 function teamLaneTextStyle(agentId = '') {
   const id = String(agentId || '').toLowerCase();
   if (!id || id === 'mission_overview' || id === 'overview') return { role: 'overview', color_name: 'Blue' };

package/src/core/tmux-ui.mjs

@@ -119,6 +119,9 @@ const TERMINAL_TEAM_AGENT_STATUSES = new Set([
   'tmux_lane_closed'
 ]);
 
+const LEGACY_TEAM_PANE_TITLE_RE = /^(?:overview: mission_overview|scout: analysis_scout|plan: (?:debate|consensus|planner|user)|exec: (?:executor|implementation|worker)|review: (?:reviewer|qa|validation)|safety:)/;
+const GENERIC_TEAM_AGENT_IDS = new Set(['parent_orchestrator', 'analysis_scout', 'team_consensus', 'implementation_worker', 'db_safety_reviewer', 'qa_reviewer']);
+
 export function isTmuxShellSession(env = process.env) {
   return Boolean(String(env.TMUX || '').trim());
 }
@@ -395,6 +398,11 @@ function teamCockpitAgentIds(plan = {}, dashboard = null, control = null, opts =
   const visible = teamViewAgentIds(plan).filter((id) => id && id !== 'mission_overview');
   const agents = dashboard?.agents && typeof dashboard.agents === 'object' ? dashboard.agents : null;
   if (!agents) return opts.plannedFallback ? visible : [];
+  const concrete = concreteDashboardAgentIds(agents, visible).filter((id) => {
+    const status = String(agents[id]?.status || '').trim().toLowerCase();
+    return status && status !== 'pending' && !isTerminalTeamAgentStatus(status);
+  });
+  if (concrete.length) return uniqueAgentIds(concrete);
   const active = [];
   for (const id of visible) {
     const entry = agents[id] || {};
@@ -407,6 +415,17 @@ function teamCockpitAgentIds(plan = {}, dashboard = null, control = null, opts =
   return uniqueAgentIds(active);
 }
 
+function concreteDashboardAgentIds(agents = {}, planned = []) {
+  const plannedSet = new Set(planned);
+  const concrete = Object.keys(agents)
+    .filter((id) => id && !plannedSet.has(id))
+    .filter((id) => !GENERIC_TEAM_AGENT_IDS.has(id))
+    .filter((id) => !/_(?:\d+)$/.test(id));
+  if (!concrete.length) return [];
+  const plannedRoles = new Set(planned.map((id) => teamLaneStyle(id).role));
+  return concrete.filter((id) => plannedRoles.has(teamLaneStyle(id).role));
+}
+
 function teamCockpitLanes(plan = {}, dashboard = null, control = null, opts = {}) {
   const agents = teamCockpitAgentIds(plan, dashboard, control, opts);
   if (!agents.length) return [];
@@ -441,6 +460,10 @@ function parseTmuxPaneLines(stdout = '') {
   }).filter((pane) => /^%\d+$/.test(pane.pane_id || ''));
 }
 
+function isLegacyTeamPane(pane = {}) {
+  return LEGACY_TEAM_PANE_TITLE_RE.test(String(pane.title || '').trim());
+}
+
 async function listTmuxWindowPanes(bin, windowId) {
   const format = ['#{pane_id}', '#{pane_title}', '#{pane_current_command}', '#{@sks_team_managed}', '#{@sks_mission_id}', '#{@sks_agent_id}', '#{@sks_lane_role}'].join('\t');
   const run = await tmuxRun(bin, ['list-panes', '-t', windowId, '-F', format], { timeoutMs: 5000, maxOutputBytes: 32 * 1024 });
@@ -784,7 +807,13 @@ export async function reconcileTmuxTeamCockpit({ root, missionId, plan = {}, pro
 
 export async function launchTmuxTeamView({ root, missionId, plan = {}, promptFile = null, json = false, attach = false, args = [] } = {}) {
   const launch = await buildTmuxLaunchPlan({ root, session: `sks-team-${missionId}` });
-  const visibleAgents = teamViewAgentIds(plan);
+  const missionDir = path.join(launch.root, '.sneakoscope', 'missions', missionId);
+  const dashboard = await readTeamDashboard(missionDir).catch(() => null);
+  const control = await readTeamControl(missionDir).catch(() => null);
+  const plannedAgents = teamViewAgentIds(plan);
+  const concreteAgents = concreteDashboardAgentIds(dashboard?.agents || {}, plannedAgents);
+  const cleanupRequested = teamCleanupRequested(control);
+  const visibleAgents = cleanupRequested ? [] : (json ? plannedAgents : (concreteAgents.length ? concreteAgents : plannedAgents));
   const commands = visibleAgents.map((agentId) => ({
     agent: agentId,
     command: teamAgentCommand(launch.root, missionId, agentId, teamLanePhase(agentId), promptFile),
@@ -792,7 +821,7 @@ export async function launchTmuxTeamView({ root, missionId, plan = {}, promptFil
     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 lanes = cleanupRequested ? [] : [overview, ...commands.map((entry) => ({ ...entry, role: entry.style.role }))];
   const splitUi = {
     mode: 'single_window_split_panes',
     window: 'sks',
@@ -813,14 +842,14 @@ export async function launchTmuxTeamView({ root, missionId, plan = {}, promptFil
     agents: commands,
     lanes,
     split_ui: splitUi,
-    cleanup_policy: 'mark-complete; tmux panes remain user controlled',
+    cleanup_policy: 'mark-complete; close SKS-managed Team panes; main Codex pane remains user controlled',
     blockers: launch.blockers,
     attach_command: launch.attach_command
   };
   if (json || !launch.ready) return result;
   const wantsSeparateSession = args.includes('--separate-session') || args.includes('--new-session') || args.includes('--legacy-team-session') || args.includes('--no-dynamic-team-tmux');
   if (!wantsSeparateSession) {
-    const cockpit = await reconcileTmuxTeamCockpit({ root: launch.root, missionId, plan, promptFile, plannedFallback: true });
+    const cockpit = await reconcileTmuxTeamCockpit({ root: launch.root, missionId, plan, promptFile, dashboard, control, plannedFallback: true });
     result.dynamic_cockpit = cockpit;
     if (cockpit.ok) {
       result.created = true;
@@ -962,8 +991,25 @@ async function readTmuxTeamRecord(root, missionId) {
 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 };
+  if (!record?.session) {
+    const legacy = await cleanupLegacyTmuxTeamSurfaces(resolvedRoot, missionId, { closeSession }).catch((err) => ({ ok: false, skipped: true, reason: err.message || 'legacy tmux cleanup failed' }));
+    return {
+      ok: legacy.ok,
+      skipped: legacy.closed_lane_count === 0 && !legacy.killed_session,
+      reason: legacy.reason,
+      mission_id: missionId,
+      legacy_cleanup: legacy,
+      requested_close_surfaces: legacy.requested_close_surfaces || 0,
+      closed_surfaces: legacy.closed_lane_count || (legacy.killed_session ? 1 : 0)
+    };
+  }
   const dynamicCleanup = await reconcileTmuxTeamCockpit({ root: resolvedRoot, missionId: record.mission_id || missionId, close: true }).catch((err) => ({ ok: false, skipped: true, reason: err.message || 'dynamic tmux cleanup failed' }));
+  const recordedCleanup = dynamicCleanup?.ok
+    ? null
+    : await cleanupRecordedTmuxTeamPanes(resolvedRoot, record.mission_id || missionId, record).catch((err) => ({ ok: false, skipped: true, reason: err.message || 'recorded tmux cleanup failed' }));
+  const legacyCleanup = (dynamicCleanup?.closed_lane_count || recordedCleanup?.closed_lane_count)
+    ? null
+    : await cleanupLegacyTmuxTeamSurfaces(resolvedRoot, record.mission_id || missionId, { closeSession: false }).catch((err) => ({ ok: false, skipped: true, reason: err.message || 'legacy tmux cleanup failed' }));
   let killed_session = false;
   if ((closeSession || closeSession === true) && record.mode !== 'current_session_dynamic_panes') {
     const tmuxBin = await findTmuxBin() || 'tmux';
@@ -979,13 +1025,110 @@ export async function cleanupTmuxTeamView({ root, missionId = 'latest', closeSes
     close_session: Boolean(closeSession),
     killed_session,
     dynamic_cleanup: dynamicCleanup,
-    requested_close_surfaces: closeSession ? 1 : (dynamicCleanup?.closed_lane_count || 0),
-    closed_surfaces: killed_session ? 1 : (dynamicCleanup?.closed_lane_count || 0),
+    recorded_cleanup: recordedCleanup,
+    legacy_cleanup: legacyCleanup,
+    requested_close_surfaces: closeSession ? 1 : (dynamicCleanup?.closed_lane_count || recordedCleanup?.closed_lane_count || legacyCleanup?.requested_close_surfaces || 0),
+    closed_surfaces: killed_session ? 1 : (dynamicCleanup?.closed_lane_count || recordedCleanup?.closed_lane_count || legacyCleanup?.closed_lane_count || 0),
     reason: dynamicCleanup?.ok
       ? 'cleanup closed managed Team panes in the current SKS tmux session.'
+      : recordedCleanup?.ok
+        ? 'cleanup closed recorded managed Team panes by stored tmux pane ids.'
+        : legacyCleanup?.ok
+          ? legacyCleanup.reason
       : closeSession
         ? 'tmux kill-session requested for recorded Team session.'
-        : 'cleanup marks the SKS tmux Team record complete; panes remain user-controlled.'
+        : 'cleanup marks the SKS tmux Team record complete; no managed panes were reachable.'
+  };
+}
+
+async function cleanupLegacyTmuxTeamSurfaces(root, missionId, opts = {}) {
+  const id = String(missionId || '').trim();
+  const tmuxBin = await findTmuxBin() || 'tmux';
+  const current = await currentTmuxTarget(tmuxBin).catch(() => ({ ok: false }));
+  const closed = [];
+  const failed = [];
+  let killed_session = false;
+  let session_kill_requested = false;
+  const session = id && id !== 'latest' ? sanitizeTmuxSessionName(`sks-team-${id}`) : '';
+  if (session && await hasTmuxSession(tmuxBin, session)) {
+    if (current.ok && current.session === session) {
+      const panes = await listTmuxWindowPanes(tmuxBin, current.window_id);
+      if (panes.ok) {
+        for (const pane of panes.panes.filter((entry) => entry.pane_id !== current.pane_id && isLegacyTeamPane(entry))) {
+          const kill = await tmuxRun(tmuxBin, ['kill-pane', '-t', pane.pane_id], { timeoutMs: 5000 });
+          if (kill.code === 0) closed.push({ pane_id: pane.pane_id, title: pane.title });
+          else failed.push({ pane_id: pane.pane_id, title: pane.title, stderr: kill.stderr || kill.stdout || 'tmux kill-pane failed' });
+        }
+      }
+    } else {
+      session_kill_requested = true;
+      const kill = await tmuxRun(tmuxBin, ['kill-session', '-t', session], { timeoutMs: 5000 });
+      killed_session = kill.code === 0;
+      if (!killed_session) failed.push({ session, stderr: kill.stderr || kill.stdout || 'tmux kill-session failed' });
+    }
+  }
+  if (current.ok) {
+    const panes = await listTmuxWindowPanes(tmuxBin, current.window_id);
+    if (panes.ok) {
+      for (const pane of panes.panes.filter((entry) => !entry.managed && entry.pane_id !== current.pane_id && isLegacyTeamPane(entry))) {
+        if (closed.some((entry) => entry.pane_id === pane.pane_id)) continue;
+        const kill = await tmuxRun(tmuxBin, ['kill-pane', '-t', pane.pane_id], { timeoutMs: 5000 });
+        if (kill.code === 0) closed.push({ pane_id: pane.pane_id, title: pane.title });
+        else failed.push({ pane_id: pane.pane_id, title: pane.title, stderr: kill.stderr || kill.stdout || 'tmux kill-pane failed' });
+      }
+      if (closed.length) {
+        await tmuxRun(tmuxBin, ['select-layout', '-t', current.window_id, 'tiled'], { timeoutMs: 5000 }).catch(() => null);
+        await tmuxRun(tmuxBin, ['select-layout', '-t', current.window_id, '-E'], { timeoutMs: 5000 }).catch(() => null);
+      }
+    }
+  }
+  return {
+    ok: failed.length === 0,
+    skipped: !killed_session && closed.length === 0,
+    session: session || null,
+    killed_session,
+    closed_lane_count: closed.length,
+    requested_close_surfaces: (session_kill_requested ? 1 : 0) + closed.length,
+    closed,
+    failed,
+    reason: killed_session
+      ? 'cleanup closed legacy Team tmux session by mission id.'
+      : closed.length
+        ? 'cleanup closed legacy Team panes by lane title.'
+        : 'cleanup found no legacy Team panes for this mission.'
+  };
+}
+
+async function cleanupRecordedTmuxTeamPanes(root, missionId, record = {}) {
+  const id = record.mission_id || missionId;
+  const cockpitState = await readJson(tmuxCockpitStatePath(root), {}).catch(() => ({}));
+  const cockpit = cockpitState?.missions?.[id] || {};
+  const target = cockpit.window_id || record.window_id || cockpit.session || record.session;
+  if (!target) return { ok: false, skipped: true, reason: 'no recorded tmux target', closed_lane_count: 0 };
+  const tmuxBin = await findTmuxBin() || 'tmux';
+  const paneList = await listTmuxWindowPanes(tmuxBin, target);
+  if (!paneList.ok) return { ok: false, skipped: true, reason: paneList.stderr, closed_lane_count: 0 };
+  const managed = paneList.panes.filter((pane) => pane.managed && pane.mission_id === id);
+  const closed = [];
+  const failed = [];
+  for (const pane of managed) {
+    const kill = await tmuxRun(tmuxBin, ['kill-pane', '-t', pane.pane_id], { timeoutMs: 5000 });
+    if (kill.code === 0) closed.push({ pane_id: pane.pane_id, agent: pane.agent, role: pane.role });
+    else failed.push({ pane_id: pane.pane_id, agent: pane.agent, stderr: kill.stderr || kill.stdout || 'tmux kill-pane failed' });
+  }
+  if (closed.length) {
+    await tmuxRun(tmuxBin, ['select-layout', '-t', target, 'tiled'], { timeoutMs: 5000 }).catch(() => null);
+    await tmuxRun(tmuxBin, ['select-layout', '-t', target, '-E'], { timeoutMs: 5000 }).catch(() => null);
+  }
+  return {
+    ok: failed.length === 0,
+    skipped: false,
+    session: cockpit.session || record.session,
+    window_id: cockpit.window_id || record.window_id || null,
+    closed_lane_count: closed.length,
+    closed,
+    failed,
+    reason: closed.length ? 'closed recorded managed panes' : 'no recorded managed panes found'
   };
 }