sneakoscope 6.0.3 → 6.1.2

package/dist/core/codex-runtime/codex-desktop-config-policy.js

@@ -0,0 +1,305 @@
+import os from 'node:os';
+import path from 'node:path';
+import { DEFAULT_CODEX_APP_PLUGINS } from '../routes.js';
+import { ensureDir, PACKAGE_VERSION, readText, writeTextAtomic } from '../fsx.js';
+import { removeLegacyTopLevelCodexModeLocks, writeCodexConfigGuarded } from '../codex/codex-config-guard.js';
+import { cleanupCodexConfigBackups, validateCodexConfigRoundTrip } from '../codex/codex-config-toml.js';
+export async function ensureGlobalCodexFastModeDuringInstall(opts = {}) {
+    if (process.env.SKS_SKIP_CODEX_FAST_MODE_REPAIR === '1')
+        return { status: 'skipped', reason: 'SKS_SKIP_CODEX_FAST_MODE_REPAIR=1' };
+    const home = opts.home || process.env.HOME || os.homedir();
+    const configPath = opts.configPath || path.join(home, '.codex', 'config.toml');
+    try {
+        await ensureDir(path.dirname(configPath));
+        const current = await readText(configPath, '');
+        if (current.trim()) {
+            const currentSmoke = codexConfigParseSmoke(current);
+            if (!currentSmoke.ok) {
+                const backupPath = await backupCodexConfig(configPath, current, 'unparseable');
+                return { status: 'unparseable_config_preserved', config_path: configPath, backup_path: backupPath, parse_smoke: currentSmoke };
+            }
+        }
+        const next = normalizeCodexFastModeUiConfig(current, {
+            forceFastMode: opts.forceFastMode === true,
+            forceFastModeOff: opts.forceFastModeOff === true
+        });
+        if (next === ensureTrailingNewline(current)) {
+            const guarded = await safeWriteCodexConfigToml(configPath, current, next, 'codex-fast-mode-install-present', {
+                preserveFastUiKeys: opts.forceFastModeOff !== true
+            });
+            return {
+                status: guarded.status,
+                config_path: configPath,
+                backup_path: guarded.backup_path,
+                parse_smoke: guarded.ok ? undefined : guarded
+            };
+        }
+        const safeWrite = await safeWriteCodexConfigToml(configPath, current, next, 'codex-fast-mode-install', {
+            preserveFastUiKeys: opts.forceFastModeOff !== true
+        });
+        return {
+            status: safeWrite.status === 'written' ? 'updated' : safeWrite.status,
+            config_path: configPath,
+            backup_path: safeWrite.backup_path,
+            parse_smoke: safeWrite.ok ? undefined : safeWrite
+        };
+    }
+    catch (err) {
+        return { status: 'failed', config_path: configPath, error: err.message };
+    }
+}
+export function normalizeCodexFastModeUiConfig(text = '', opts = {}) {
+    return normalizeCodexFastModeUiConfigOnce(normalizeCodexFastModeUiConfigOnce(text, opts), opts);
+}
+function normalizeCodexFastModeUiConfigOnce(text = '', opts = {}) {
+    let next = String(text || '');
+    next = removeLegacyTopLevelCodexModeLocks(next);
+    next = removeTopLevelTomlKeyIfValue(next, 'default_profile', 'sks-fast-high');
+    next = removeTomlTable(next, 'user.fast_mode');
+    next = removeTomlTable(next, 'profiles.sks-fast-high');
+    next = removeTomlTableKey(next, 'notice', 'fast_default_opt_out');
+    for (const legacyFlag of ['codex_hooks', 'remote_control', 'fast_mode_ui', 'codex_git_commit']) {
+        next = removeTomlTableKey(next, 'features', legacyFlag, 'true');
+    }
+    if (opts.forceFastMode === true) {
+        next = upsertTopLevelTomlString(next, 'service_tier', 'fast');
+    }
+    else if (opts.forceFastModeOff === true) {
+        next = removeTopLevelTomlKey(next, 'service_tier');
+    }
+    next = upsertTopLevelTomlBooleanIfAbsent(next, 'suppress_unstable_features_warning', true);
+    for (const featureLine of [
+        'hooks = true',
+        'multi_agent = true',
+        'fast_mode = true',
+        'apps = true',
+        'computer_use = true',
+        'browser_use = true',
+        'browser_use_external = true',
+        'image_generation = true',
+        'in_app_browser = true',
+        'guardian_approval = true',
+        'tool_suggest = true',
+        'plugins = true'
+    ]) {
+        next = upsertTomlTableKeyIfAbsent(next, 'features', featureLine);
+    }
+    // Global postinstall must not impose a project concurrency policy. Existing
+    // user [agents] values are preserved verbatim; project setup owns defaults.
+    next = removeTomlTable(next, 'features.multi_agent_v2');
+    if (process.env.SKS_MANAGE_CODEX_APP_PLUGINS === '1') {
+        for (const [name, marketplace] of DEFAULT_CODEX_APP_PLUGINS) {
+            const table = `plugins."${name}@${marketplace}"`;
+            if (!hasTomlTable(next, table))
+                next = upsertTomlTable(next, table, `[${table}]\nenabled = true`);
+        }
+    }
+    return ensureTrailingNewline(next);
+}
+function removeTopLevelTomlKey(text = '', key = '') {
+    const lines = String(text || '').split('\n');
+    const firstTable = lines.findIndex((line) => /^\s*\[.+\]\s*$/.test(line));
+    const end = firstTable === -1 ? lines.length : firstTable;
+    const keyPattern = new RegExp(`^\\s*${escapeRegExp(key)}\\s*=`);
+    return lines.filter((line, index) => index >= end || !keyPattern.test(line)).join('\n').replace(/^\n+/, '').replace(/\n{3,}/g, '\n\n');
+}
+function removeTomlTable(text, table) {
+    const lines = String(text || '').trimEnd().split('\n');
+    const header = `[${table}]`;
+    const start = lines.findIndex((line) => line.trim() === header);
+    if (start === -1)
+        return String(text || '');
+    let end = lines.length;
+    for (let i = start + 1; i < lines.length; i += 1) {
+        if (/^\s*\[.+\]\s*$/.test(lines[i] || '')) {
+            end = i;
+            break;
+        }
+    }
+    return lines.filter((_, index) => index < start || index >= end).join('\n').replace(/^\n+/, '').replace(/\n{3,}/g, '\n\n');
+}
+export function removeTopLevelTomlKeyIfValue(text = '', key = '', value = '') {
+    const lines = String(text || '').split('\n');
+    const firstTable = lines.findIndex((line) => /^\s*\[.+\]\s*$/.test(line));
+    const end = firstTable === -1 ? lines.length : firstTable;
+    const keyPattern = new RegExp(`^\\s*${escapeRegExp(key)}\\s*=\\s*"${escapeRegExp(value)}"\\s*(?:#.*)?$`);
+    return lines.filter((line, index) => index >= end || !keyPattern.test(line)).join('\n').replace(/^\n+/, '').replace(/\n{3,}/g, '\n\n');
+}
+function removeTomlTableKey(text, table, key, expectedValue = null) {
+    const lines = String(text || '').trimEnd().split('\n');
+    if (lines.length === 1 && lines[0] === '')
+        return '';
+    const start = lines.findIndex((line) => line.trim() === `[${table}]`);
+    if (start === -1)
+        return String(text || '');
+    let end = lines.length;
+    for (let i = start + 1; i < lines.length; i += 1) {
+        if (/^\s*\[.+\]\s*$/.test(lines[i] || '')) {
+            end = i;
+            break;
+        }
+    }
+    const valuePattern = expectedValue === null ? '' : `\\s*${escapeRegExp(String(expectedValue))}\\s*(?:#.*)?$`;
+    const keyPattern = new RegExp(`^\\s*${escapeRegExp(key)}\\s*=${valuePattern}`);
+    return lines.filter((line, index) => index <= start || index >= end || !keyPattern.test(line)).join('\n').replace(/\n{3,}/g, '\n\n');
+}
+function upsertTomlTableKey(text, table, line) {
+    const key = String(line).split('=')[0]?.trim() ?? '';
+    const lines = String(text || '').trimEnd().split('\n');
+    if (lines.length === 1 && lines[0] === '')
+        lines.length = 0;
+    const start = lines.findIndex((entry) => entry.trim() === `[${table}]`);
+    if (start === -1)
+        return [...lines, ...(lines.length ? [''] : []), `[${table}]`, line].join('\n').replace(/\n{3,}/g, '\n\n');
+    let end = lines.length;
+    for (let i = start + 1; i < lines.length; i += 1) {
+        if (/^\s*\[.+\]\s*$/.test(lines[i] || '')) {
+            end = i;
+            break;
+        }
+    }
+    const keyPattern = new RegExp(`^\\s*${escapeRegExp(key)}\\s*=`);
+    for (let i = start + 1; i < end; i += 1) {
+        if (keyPattern.test(lines[i] || '')) {
+            lines[i] = line;
+            return lines.join('\n').replace(/\n{3,}/g, '\n\n');
+        }
+    }
+    lines.splice(end, 0, line);
+    return lines.join('\n').replace(/\n{3,}/g, '\n\n');
+}
+function hasTomlTableKey(text, table, key) {
+    const lines = String(text || '').split('\n');
+    const start = lines.findIndex((line) => line.trim() === `[${table}]`);
+    if (start === -1)
+        return false;
+    const keyPattern = new RegExp(`^\\s*${escapeRegExp(key)}\\s*=`);
+    for (let i = start + 1; i < lines.length; i += 1) {
+        if (/^\s*\[.+\]\s*$/.test(lines[i] || ''))
+            break;
+        if (keyPattern.test(lines[i] || ''))
+            return true;
+    }
+    return false;
+}
+function upsertTomlTableKeyIfAbsent(text, table, line) {
+    const key = String(line).split('=')[0]?.trim() ?? '';
+    return hasTomlTableKey(text, table, key) ? String(text || '') : upsertTomlTableKey(text, table, line);
+}
+function upsertTopLevelTomlBooleanIfAbsent(text, key, value) {
+    return hasTopLevelTomlKey(text, key) ? String(text || '') : upsertTopLevelTomlBoolean(text, key, value);
+}
+export function ensureTrailingNewline(text = '') {
+    const value = String(text || '').trimEnd();
+    return value ? `${value}\n` : '';
+}
+export function upsertTopLevelTomlString(text, key, value) {
+    const line = `${key} = "${value}"`;
+    const lines = String(text || '').split('\n');
+    const firstTable = lines.findIndex((entry) => /^\s*\[.+\]\s*$/.test(entry));
+    const end = firstTable === -1 ? lines.length : firstTable;
+    const keyPattern = new RegExp(`^\\s*${escapeRegExp(key)}\\s*=`);
+    for (let i = 0; i < end; i += 1) {
+        if (keyPattern.test(lines[i] || '')) {
+            lines[i] = line;
+            return lines.join('\n').replace(/\n{3,}/g, '\n\n');
+        }
+    }
+    lines.splice(end, 0, line);
+    return lines.join('\n').replace(/^\n+/, '').replace(/\n{3,}/g, '\n\n');
+}
+function hasTopLevelTomlKey(text, key) {
+    const lines = String(text || '').split('\n');
+    const firstTable = lines.findIndex((entry) => /^\s*\[.+\]\s*$/.test(entry));
+    const end = firstTable === -1 ? lines.length : firstTable;
+    const pattern = new RegExp(`^\\s*${escapeRegExp(key)}\\s*=`);
+    return lines.slice(0, end).some((line) => pattern.test(line));
+}
+function codexConfigParseSmoke(text = '') {
+    const value = String(text || '');
+    const unterminatedTriple = (value.match(/"""|'''/g) || []).length % 2 !== 0;
+    const invalidHeader = value.split('\n').find((line) => /^\s*\[/.test(line) && !/^\s*\[\[?[^\]]+\]\]?\s*(?:#.*)?$/.test(line)) || null;
+    return { ok: !unterminatedTriple && !invalidHeader, unterminated_multiline_string: unterminatedTriple, invalid_table_header: invalidHeader };
+}
+async function backupCodexConfig(configPath, text, tag) {
+    try {
+        const backupPath = `${configPath}.sks-${tag}-${PACKAGE_VERSION}-${Date.now().toString(36)}.bak`;
+        await writeTextAtomic(backupPath, text, { mode: 0o600 });
+        await cleanupCodexConfigBackups(configPath, { keepPerTag: 3, maxAgeMs: 30 * 24 * 60 * 60 * 1000 }).catch(() => undefined);
+        return backupPath;
+    }
+    catch {
+        return null;
+    }
+}
+export async function safeWriteCodexConfigToml(configPath, current, next, tag = 'codex-lb', opts = {}) {
+    return writeCodexConfigGuarded({
+        configPath,
+        before: String(current || ''),
+        cause: tag,
+        removeTopLevelModeLocks: true,
+        ...(opts.preserveFastUiKeys === undefined ? {} : { preserveFastUiKeys: opts.preserveFastUiKeys }),
+        mutate: () => String(next || '')
+    });
+}
+export function codexFastModeDesktopStatus(text = '') {
+    const validation = validateCodexConfigRoundTrip(String(text || ''));
+    const globalOn = validation.ok && validation.service_tier === 'fast';
+    return {
+        schema: 'sks.codex-fast-mode-desktop-status.v2',
+        ok: validation.ok,
+        on: Boolean(globalOn),
+        service_tier: validation.service_tier ?? null,
+        model: validation.model ?? null,
+        legacy_keys: validation.legacy_keys,
+        validation: {
+            ok: validation.ok,
+            blockers: validation.blockers,
+            parse_error: validation.parse_error || null,
+            service_tier: validation.service_tier ?? null,
+            model: validation.model ?? null,
+            model_reasoning_effort: validation.model_reasoning_effort ?? null,
+            legacy_keys: validation.legacy_keys
+        }
+    };
+}
+function upsertTopLevelTomlBoolean(text, key, value) {
+    const line = `${key} = ${value ? 'true' : 'false'}`;
+    const lines = String(text || '').split('\n');
+    const firstTable = lines.findIndex((entry) => /^\s*\[.+\]\s*$/.test(entry));
+    const end = firstTable === -1 ? lines.length : firstTable;
+    const pattern = new RegExp(`^\\s*${escapeRegExp(key)}\\s*=`);
+    for (let i = 0; i < end; i += 1) {
+        if (pattern.test(lines[i] || '')) {
+            lines[i] = line;
+            return lines.join('\n').replace(/\n{3,}/g, '\n\n');
+        }
+    }
+    lines.splice(end, 0, line);
+    return lines.join('\n').replace(/^\n+/, '').replace(/\n{3,}/g, '\n\n');
+}
+function hasTomlTable(text, table) {
+    return String(text || '').split('\n').some((line) => String(line).trim() === `[${table}]`);
+}
+export function upsertTomlTable(text, table, block) {
+    let lines = String(text || '').trimEnd().split('\n');
+    if (lines.length === 1 && lines[0] === '')
+        lines = [];
+    const start = lines.findIndex((entry) => entry.trim() === `[${table}]`);
+    const blockLines = String(block || '').trim().split('\n');
+    if (start === -1)
+        return [...lines, ...(lines.length ? [''] : []), ...blockLines].join('\n').replace(/\n{3,}/g, '\n\n');
+    let end = lines.length;
+    for (let i = start + 1; i < lines.length; i += 1) {
+        if (/^\s*\[.+\]\s*$/.test(lines[i] || '')) {
+            end = i;
+            break;
+        }
+    }
+    lines.splice(start, end - start, ...blockLines);
+    return lines.join('\n').replace(/\n{3,}/g, '\n\n');
+}
+function escapeRegExp(value) {
+    return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+//# sourceMappingURL=codex-desktop-config-policy.js.map

package/dist/core/commands/agent-bridge-command.js

@@ -1,7 +1,7 @@
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { ensureDir, exists, nowIso, projectRoot, runProcess, writeJsonAtomic } from '../fsx.js';
-import { buildAgentManifest } from '../agent-bridge/agent-manifest.js';
+import { buildAgentManifest, validateAgentManifest } from '../agent-bridge/agent-manifest.js';
 import { flag } from './command-utils.js';
 async function resolveSksEntrypoint() {
     // Mirrors src/core/agent-bridge/mcp-server.ts's own bin resolution: prefer the
@@ -14,7 +14,10 @@ async function runNonInteractiveSmoke(entrypoint) {
     const result = await runProcess(process.execPath, [entrypoint, 'status', '--json'], {
         env: { SKS_AGENT_MODE: '1' },
         timeoutMs: 15_000,
-        maxOutputBytes: 32 * 1024
+        // Status is intentionally bounded but can exceed 32 KiB when several
+        // session summaries are present. Truncating otherwise-valid JSON makes the
+        // bridge report a false non-interactive failure.
+        maxOutputBytes: 512 * 1024
     }).catch((err) => ({ code: 1, stdout: '', stderr: err instanceof Error ? err.message : String(err) }));
     let stdoutIsCleanJson = false;
     try {
@@ -56,7 +59,24 @@ export async function agentBridgeCommand(subcommand, args = []) {
     }
     const root = await projectRoot();
     const manifest = buildAgentManifest();
+    const manifestValidation = validateAgentManifest(manifest);
     const manifestPath = path.join(root, '.sneakoscope', 'agent-bridge', 'manifest.json');
+    if (!manifestValidation.ok) {
+        const result = {
+            schema: 'sks.agent-bridge-setup.v1',
+            generated_at: nowIso(),
+            ok: false,
+            status: 'manifest_validation_failed',
+            manifest_path: manifestPath,
+            manifest_validation: manifestValidation
+        };
+        process.exitCode = 1;
+        if (flag(args, '--json'))
+            console.log(JSON.stringify(result, null, 2));
+        else
+            console.error(`Agent bridge manifest validation failed: ${manifestValidation.issues.join(', ')}`);
+        return result;
+    }
     await ensureDir(path.dirname(manifestPath));
     await writeJsonAtomic(manifestPath, manifest);
     const entrypoint = await resolveSksEntrypoint();
@@ -67,6 +87,7 @@ export async function agentBridgeCommand(subcommand, args = []) {
         ok: smoke.ok,
         manifest_path: manifestPath,
         tool_count: manifest.tools.length,
+        manifest_validation: manifestValidation,
         registration_snippets: registrationSnippets(),
         non_interactive_smoke: smoke
     };

package/dist/core/commands/agent-command.js

@@ -12,6 +12,8 @@ import { runNativeCliWorkerFromArgs } from '../agents/native-cli-worker.js';
 const AGENT_ACTION_SCHEMA = 'sks.agent-command-result.v1';
 export async function agentCommand(commandOrArgs = 'agent', maybeArgs = []) {
     const args = Array.isArray(commandOrArgs) ? commandOrArgs : maybeArgs;
+    if (args.includes('--help') || args.includes('-h') || args[0] === 'help')
+        return agentHelp(args.includes('--json'));
     const parsed = parseAgentCommandArgs('agent', args);
     if (parsed.action === 'worker')
         return runNativeCliWorkerFromArgs(args.slice(args[0] === 'worker' ? 1 : 0));
@@ -21,7 +23,40 @@ export async function agentCommand(commandOrArgs = 'agent', maybeArgs = []) {
         return agentPlan(parsed);
     return agentMissionAction(parsed);
 }
+function agentHelp(json = false) {
+    const result = {
+        schema: 'sks.agent-help.v1',
+        ok: true,
+        action: 'help',
+        read_only: true,
+        usage: 'sks agent run <prompt> [--mission <id>] [--agents <n>] [--concurrency <n>] [--readonly] [--json]',
+        actions: ['run', 'plan', 'status', 'watch', 'dashboard', 'cockpit', 'lane', 'board', 'ledger', 'collect', 'consensus', 'close', 'cleanup', 'proof', 'explain', 'rollback-patches']
+    };
+    if (json)
+        console.log(JSON.stringify(result, null, 2));
+    else {
+        console.log(result.usage);
+        console.log('Actions: ' + result.actions.join(', '));
+    }
+    return result;
+}
 async function agentRun(parsed) {
+    if (normalizeRouteName(parsed.route) === 'release-review' && parsed.legacyNativeRuntime !== true) {
+        const result = {
+            schema: AGENT_ACTION_SCHEMA,
+            ok: false,
+            status: 'blocked',
+            route: '$Release-Review',
+            blocker: 'release_review_official_subagents_required',
+            blockers: ['release_review_official_subagents_required'],
+            next_command: `sks naruto run "$Release-Review ${String(parsed.prompt || 'release audit').replace(/"/g, '\\"')}" --agents ${Math.max(1, Number(parsed.agents || 1))} --read-only --json`,
+            legacy_escape_hatch: 'Pass --legacy-native-runtime only for an explicitly approved legacy compatibility run.'
+        };
+        process.exitCode = 2;
+        return emit(parsed, result, () => {
+            console.error('Release Review is owned by the Codex official subagent workflow. Use the suggested sks naruto command.');
+        });
+    }
     const result = await runNativeAgentOrchestrator({ ...parsed, routeCommand: 'sks agent run', routeBlackboxKind: 'actual_agent_command' });
     if (normalizeRouteName(parsed.route) === 'release-review' && result.mission_id) {
         await writeReleaseReviewNativeAgentPlan(parsed, result);
@@ -37,11 +72,9 @@ function normalizeRouteName(route = '') {
     return String(route || '').replace(/^\$/, '').trim().toLowerCase();
 }
 /**
- * $Release-Review runs through the generic native agent orchestrator (sks agent run
- * --route "$Release-Review"), which does not itself know it is a release-review run.
- * Write the route-specific release-review-native-agent-plan.json summary artifact here
- * so `route-release-review`'s fixture contract (plan file + agent proof evidence +
- * agent effort policy) is genuinely satisfied by this command rather than only partially.
+ * Legacy compatibility fixtures may explicitly opt into the historical native
+ * Release-Review runner with --legacy-native-runtime. Public $Release-Review
+ * execution is owned by the official Codex subagent workflow.
  */
 async function writeReleaseReviewNativeAgentPlan(parsed, result) {
     const root = await sksRoot();

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

@@ -5,7 +5,7 @@ import { COMMAND_MANIFEST_LITE } from '../../cli/command-manifest-lite.js';
 import { flag } from '../../cli/args.js';
 import { printJson, sksTextLogo } from '../../cli/output.js';
 import { ui as cliUi } from '../../cli/cli-theme.js';
-import { PACKAGE_VERSION, ensureDir, exists, nowIso, projectRoot, readJson, sksRoot, tmpdir, writeJsonAtomic } from '../fsx.js';
+import { PACKAGE_VERSION, ensureDir, exists, nowIso, projectRoot, readJson, rmrf, sksRoot, tmpdir, writeJsonAtomic } from '../fsx.js';
 import { DOLLAR_COMMAND_ALIASES, DOLLAR_COMMANDS, USAGE_TOPICS, routePrompt, routeReasoning, reasoningInstruction } from '../routes.js';
 import { DOLLAR_COMMAND_ALIASES_LITE, DOLLAR_COMMANDS_LITE } from '../routes/dollar-manifest-lite.js';
 import { initProject, normalizeInstallScope, sksCommandPrefix } from '../init.js';
@@ -17,6 +17,7 @@ import { createMission } from '../mission.js';
 import { formatSksUpdateCheckText, runSksUpdateCheck, runSksUpdateNow } from '../update-check.js';
 import { persistSksUpdateNoticeFromVersions } from '../update/update-notice.js';
 import { withSecretPreservationGuard } from '../config/config-migration-journal.js';
+const REMOVED_USAGE_TOPICS = new Set(['db']);
 export async function helpCommand(args = []) {
     const topic = args[0];
     if (topic)
@@ -100,7 +101,9 @@ export function usageCommand(args = []) {
         console.log(row.description);
         return;
     }
-    const route = DOLLAR_COMMANDS.find((entry) => entry.command.toLowerCase() === `$${topic}`.toLowerCase());
+    const route = REMOVED_USAGE_TOPICS.has(String(topic).toLowerCase())
+        ? null
+        : DOLLAR_COMMANDS.find((entry) => entry.command.toLowerCase() === `$${topic}`.toLowerCase());
     if (route) {
         console.log(`${route.command}\n`);
         console.log(`${route.route}: ${route.description}`);
@@ -205,6 +208,27 @@ export async function setupCommand(args = []) {
     if (flag(args, '--help') || flag(args, '-h'))
         return usageCommand(['setup']);
     const root = await projectRoot();
+    const { formatHarnessConflictReport, scanHarnessConflicts } = await import('../harness-conflicts.js');
+    const conflictScan = await scanHarnessConflicts(root);
+    if (conflictScan.hard_block) {
+        const blocked = {
+            schema: 'sks.setup.v1',
+            ok: false,
+            status: 'blocked_harness_conflict',
+            root,
+            blockers: conflictScan.hard.map((item) => `${item.name || 'harness'}:${item.path}`),
+            conflicts: conflictScan.conflicts,
+            cleanup_prompt_command: 'sks conflicts prompt'
+        };
+        process.exitCode = 1;
+        if (flag(args, '--json')) {
+            printJson(blocked);
+            return blocked;
+        }
+        console.error(formatHarnessConflictReport(conflictScan, { includePrompt: false }));
+        console.error('Run `sks conflicts prompt` and obtain explicit human approval before cleanup.');
+        return blocked;
+    }
     const installScope = installScopeFromArgs(args);
     let res = null;
     let cliTools = null;
@@ -218,24 +242,41 @@ export async function setupCommand(args = []) {
         const { ensureRelatedCliTools } = await import('../../cli/install-helpers.js');
         cliTools = await ensureRelatedCliTools(args);
     });
+    const blockers = [
+        ...(res.codex_config_install?.manual_blockers || []),
+        ...(res.agent_install?.manual_blockers || [])
+    ];
+    const warnings = res.codex_config_install?.warnings || [];
     const result = {
         schema: 'sks.setup.v1',
-        ok: true,
+        ok: blockers.length === 0 && res.codex_config_install?.ok !== false && res.agent_install?.ok !== false,
+        status: blockers.length ? 'manual_blocked' : 'completed',
         root,
         install_scope: installScope,
         command_prefix: sksCommandPrefix(installScope, { globalCommand: 'sks' }),
         created: res.created || [],
         local_only: flag(args, '--local-only'),
-        cli_tools: cliTools
+        cli_tools: cliTools,
+        blockers,
+        warnings
     };
-    if (flag(args, '--json'))
-        return printJson(result);
-    console.log(`Setup complete: ${root}`);
+    if (!result.ok)
+        process.exitCode = 1;
+    if (flag(args, '--json')) {
+        printJson(result);
+        return result;
+    }
+    console.log(`${result.ok ? 'Setup complete' : 'Setup blocked'}: ${root}`);
     console.log(`Install scope: ${installScope}`);
     console.log(`Codex CLI: ${cliTools.codex.status}${cliTools.codex.version ? ` ${cliTools.codex.version}` : ''}`);
     console.log(`Zellij: ${cliTools.zellij.ok ? 'ok' : cliTools.zellij.repair.status}${cliTools.zellij.version ? ` ${cliTools.zellij.version}` : ''}`);
     for (const file of result.created)
         console.log(`- ${file}`);
+    for (const warning of warnings)
+        console.log(`Warning: ${warning}`);
+    for (const blocker of blockers)
+        console.error(`Blocker: ${blocker}`);
+    return result;
 }
 export async function bootstrapCommand(args = []) {
     if (flag(args, '--help') || flag(args, '-h'))
@@ -317,29 +358,35 @@ export async function selftestCommand(args = []) {
     const root = await projectRoot();
     const tmp = tmpdir('sks-selftest-');
     await ensureDir(tmp);
-    const registry = await buildFeatureRegistry({ root });
-    const coverage = validateFeatureRegistry(registry);
-    if (!coverage.ok)
-        throw new Error(`selftest: feature registry blocked: ${coverage.blockers.join(', ')}`);
-    const mission = await createMission(tmp, { mode: 'team', prompt: 'selftest route proof fixture' });
-    await writeSelftestRouteProof(tmp, { missionId: mission.id, kind: 'team_gate' });
-    const proof = await readJson(path.join(tmp, '.sneakoscope', 'missions', mission.id, 'completion-proof.json'), null);
-    if (!proof?.mission_id)
-        throw new Error('selftest: completion proof fixture missing');
-    const hookExplain = hooksExplainReport();
-    if (!hookExplain.events.includes('Stop'))
-        throw new Error('selftest: hook explain missing Stop');
-    const result = {
-        schema: 'sks.selftest.v1',
-        ok: true,
-        version: PACKAGE_VERSION,
-        generated_at: nowIso(),
-        checks: ['feature_registry', 'route_completion_proof_fixture', 'hooks_policy_surface'],
-        tmp_root: tmp
-    };
-    if (flag(args, '--json'))
-        return printJson(result);
-    console.log('SKS selftest passed');
+    try {
+        const registry = await buildFeatureRegistry({ root });
+        const coverage = validateFeatureRegistry(registry);
+        if (!coverage.ok)
+            throw new Error(`selftest: feature registry blocked: ${coverage.blockers.join(', ')}`);
+        const mission = await createMission(tmp, { mode: 'team', prompt: 'selftest route proof fixture' });
+        await writeSelftestRouteProof(tmp, { missionId: mission.id, kind: 'team_gate' });
+        const proof = await readJson(path.join(tmp, '.sneakoscope', 'missions', mission.id, 'completion-proof.json'), null);
+        if (!proof?.mission_id)
+            throw new Error('selftest: completion proof fixture missing');
+        const hookExplain = hooksExplainReport();
+        if (!hookExplain.events.includes('Stop'))
+            throw new Error('selftest: hook explain missing Stop');
+        const result = {
+            schema: 'sks.selftest.v1',
+            ok: true,
+            version: PACKAGE_VERSION,
+            generated_at: nowIso(),
+            checks: ['feature_registry', 'route_completion_proof_fixture', 'hooks_policy_surface'],
+            tmp_root: tmp,
+            tmp_cleaned: true
+        };
+        if (flag(args, '--json'))
+            return printJson(result);
+        console.log('SKS selftest passed');
+    }
+    finally {
+        await rmrf(tmp);
+    }
 }
 /**
  * `sks selftest --real`: actually spawns every feature fixture whose kind is

package/dist/core/commands/command-utils.js

@@ -53,7 +53,7 @@ export function positionalArgs(args = []) {
         '--lines', '--intent', '--changed', '--route', '--skills', '--prompt-signature',
         '--mission-id', '--source', '--image-id', '--bbox', '--label', '--evidence',
         '--claim-id', '--type', '--before', '--after', '--anchors', '--verification',
-        '--status', '--agents', '--target-active-slots', '--work-items', '--minimum-work-items',
+        '--status', '--agents', '--clones', '--max-threads', '--target-active-slots', '--work-items', '--minimum-work-items',
         '--max-queue-expansion', '--engine', '--kind', '--severity', '--claim',
         '--prior-status', '--artifact', '--reason', '--root-cause', '--corrective-action',
         '--required-evidence', '--patch-status', '--avoid', '--applies-to', '--files',

package/dist/core/commands/gc-command.js

@@ -25,10 +25,12 @@ export async function memoryCommand(sub, args = []) {
     return gcCommand(args || []);
 }
 export async function gcCommand(args = []) {
-    const root = await sksRoot();
     const action = String(args[0] || '').toLowerCase();
+    if (action === 'help' || args.includes('--help') || args.includes('-h'))
+        return gcHelp(flag(args, '--json'));
+    const root = await sksRoot();
     if (action === 'plan') {
-        const res = await enforceRetention(root, { dryRun: true, pruneReportLogs: true, policy: { max_tmp_age_hours: 0 } });
+        const res = await enforceRetention(root, { dryRun: true, pruneReportLogs: true });
         if (flag(args, '--json'))
             return console.log(JSON.stringify(res.plan, null, 2));
         console.log('ㅅㅋㅅ GC plan');
@@ -47,7 +49,6 @@ export async function gcCommand(args = []) {
         }
         const res = await applyRetentionPlan(root, {
             pruneReportLogs: true,
-            policy: { max_tmp_age_hours: 0 },
             planHash: readOption(args, '--plan-hash', null)
         });
         if (flag(args, '--json'))
@@ -70,7 +71,7 @@ export async function gcCommand(args = []) {
         console.log(`Latest plan: ${res.latest_plan?.plan_hash || 'none'}`);
         return res;
     }
-    const res = await enforceRetention(root, { dryRun: flag(args, '--dry-run'), pruneReportLogs: true, policy: { max_tmp_age_hours: 0 } });
+    const res = await enforceRetention(root, { dryRun: flag(args, '--dry-run'), pruneReportLogs: true });
     if (flag(args, '--json'))
         return console.log(JSON.stringify(res, null, 2));
     console.log(flag(args, '--dry-run') ? 'ㅅㅋㅅ GC dry run' : 'ㅅㅋㅅ GC completed');
@@ -80,6 +81,28 @@ export async function gcCommand(args = []) {
     for (const a of res.actions.slice(0, 20))
         console.log(`- ${a.action} ${a.path || a.mission || ''} ${a.bytes ? formatBytes(a.bytes) : ''}`);
 }
+function gcHelp(json = false) {
+    const help = {
+        schema: 'sks.gc-help.v1',
+        ok: true,
+        usage: 'sks gc [plan|apply|status] [--dry-run] [--json]',
+        commands: {
+            plan: 'Create a hashed dry-run plan using the configured retention policy.',
+            apply: 'Apply a reviewed plan with --yes and optional --plan-hash.',
+            status: 'Show the latest mission index, plan, cleanup, and storage status.'
+        }
+    };
+    if (json)
+        console.log(JSON.stringify(help, null, 2));
+    else {
+        console.log(`Usage: ${help.usage}`);
+        console.log('  sks gc --dry-run');
+        console.log('  sks gc plan [--json]');
+        console.log('  sks gc apply --yes [--plan-hash <hash>] [--json]');
+        console.log('  sks gc status [--json]');
+    }
+    return help;
+}
 function readOption(args = [], name, fallback = null) {
     const index = args.indexOf(name);
     if (index >= 0 && args[index + 1] && !String(args[index + 1]).startsWith('--'))