sneakoscope 4.1.0 → 4.2.0

package/dist/core/codex/agent-config-file-repair.js

@@ -5,7 +5,8 @@ import { managedAgentRoleConfigForFile, managedAgentRoleConfigForRole } from '..
 export async function repairAgentConfigFileReferences(input) {
     const root = path.resolve(input.root);
     const configPath = path.join(root, '.codex', 'config.toml');
-    const original = await fs.readFile(configPath, 'utf8').catch(() => '');
+    const configExists = await fs.stat(configPath).then((stat) => stat.isFile()).catch(() => false);
+    const original = configExists ? await fs.readFile(configPath, 'utf8').catch(() => '') : minimalManagedConfigToml();
     const createdFiles = [];
     const repairedPaths = [];
     const removedUnsupportedFields = [];
@@ -38,7 +39,12 @@ export async function repairAgentConfigFileReferences(input) {
     }
     if (edits.length)
         text = applyEdits(original, edits);
-    if (input.apply && text !== original) {
+    if (input.apply && !configExists) {
+        await ensureDir(path.dirname(configPath));
+        await writeTextAtomic(configPath, text.replace(/\n{3,}/g, '\n\n').replace(/\s*$/, '\n'));
+        createdFiles.push(configPath);
+    }
+    else if (input.apply && text !== original) {
         await writeTextAtomic(configPath, text.replace(/\n{3,}/g, '\n\n').replace(/\s*$/, '\n'));
     }
     const effectiveText = input.apply ? await fs.readFile(configPath, 'utf8').catch(() => text) : text;
@@ -154,4 +160,39 @@ function escapeToml(value) {
 function escapeRegExp(value) {
     return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
+function minimalManagedConfigToml() {
+    return [
+        'model = "gpt-5.5"',
+        'model_reasoning_effort = "medium"',
+        'service_tier = "fast"',
+        '',
+        '[features]',
+        'hooks = true',
+        'remote_control = true',
+        'multi_agent = true',
+        'fast_mode = true',
+        '',
+        '[mcp_servers.context7]',
+        'url = "https://mcp.context7.com/mcp"',
+        '',
+        agentConfigBlock('native_agent', 'Read-only SKS analysis agent.', './agents/native-agent-intake.toml', ['Analysis', 'Mapper']),
+        '',
+        agentConfigBlock('team_consensus', 'SKS planning/debate agent.', './agents/team-consensus.toml', ['Consensus', 'Atlas']),
+        '',
+        agentConfigBlock('implementation_worker', 'SKS bounded implementation worker.', './agents/implementation-worker.toml', ['Builder', 'Mason']),
+        '',
+        agentConfigBlock('db_safety_reviewer', 'Read-only DB safety reviewer.', './agents/db-safety-reviewer.toml', ['Sentinel', 'Ledger']),
+        '',
+        agentConfigBlock('qa_reviewer', 'Read-only QA reviewer.', './agents/qa-reviewer.toml', ['Verifier', 'Reviewer']),
+        ''
+    ].join('\n');
+}
+function agentConfigBlock(table, description, configFile, nicknames = []) {
+    return [
+        `[agents.${table}]`,
+        `description = "${description}"`,
+        `config_file = "${configFile}"`,
+        `nickname_candidates = [${nicknames.map((name) => `"${name}"`).join(', ')}]`
+    ].join('\n');
+}
 //# sourceMappingURL=agent-config-file-repair.js.map

package/dist/core/codex-app/codex-agent-role-sync.js

@@ -1,7 +1,7 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import os from 'node:os';
-import { nowIso, writeJsonAtomic, writeTextAtomic, ensureDir } from '../fsx.js';
+import { PACKAGE_VERSION, nowIso, writeJsonAtomic, writeTextAtomic, ensureDir } from '../fsx.js';
 import { repairAgentRoleConfigs } from '../agents/agent-role-config.js';
 import { agentRolePayloadFor, probeCodexAgentTypeSupport } from './codex-agent-type-probe.js';
 const DIRECTIVE_ROLES = [
@@ -86,12 +86,12 @@ export async function syncCodexAgentRoles(input) {
 function roleToml(role, payload) {
     return [
         `name = "${role}"`,
-        `description = "SKS managed 4.1.0 directive role: ${role}"`,
+        `description = "SKS managed ${PACKAGE_VERSION} directive role: ${role}"`,
         'model_reasoning_effort = "medium"',
         role.includes('implementer') ? 'sandbox_mode = "workspace-write"' : 'sandbox_mode = "read-only"',
         'approval_policy = "never"',
         'developer_instructions = """',
-        `You are ${role}. SKS managed 4.1.0 directive role with bounded ownership.`,
+        `You are ${role}. SKS managed ${PACKAGE_VERSION} directive role with bounded ownership.`,
         'Bounded ownership: use only the assigned owner files/directories and treat memory as guidance, not permission.',
         role.includes('implementer') ? 'Maker/checker separation: implementer may patch only owner scope and cannot self-approve.' : 'Maker/checker separation: checker is read-only and must reject missing gates or missing proof artifacts.',
         role.includes('implementer') ? 'Allowed sandbox: workspace-write only within assigned owner scope.' : 'Allowed sandbox: read-only; checker roles cannot mutate.',
@@ -107,7 +107,7 @@ function roleToml(role, payload) {
     ].join('\n');
 }
 function isSksManagedDirectiveRole(text) {
-    return /SKS managed (?:3\.1\.(?:4|5|6|7|11)|4\.1\.0) (?:directive|bounded) role/.test(text)
+    return /SKS managed (?:3\.1\.(?:4|5|6|7|11)|4\.1\.\d+) (?:directive|bounded) role/.test(text)
         || /\bmessage_role_prefix\s*=/.test(text) && /SKS managed 3\.1\./.test(text);
 }
 function blockersOf(value) {

package/dist/core/codex-control/codex-0142-capability.js

@@ -3,7 +3,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { CURRENT_CODEX_RELEASE_MANIFEST } from '../codex-compat/codex-release-manifest.js';
 import { compareSemverLike } from '../codex-compat/codex-version-policy.js';
-import { ensureDir, nowIso, runProcess, sha256, writeJsonAtomic } from '../fsx.js';
+import { ensureDir, nowIso, packageRoot, readJson, runProcess, sha256, writeJsonAtomic } from '../fsx.js';
 import { resolveCodexRuntime } from '../codex-runtime/resolve-codex-runtime.js';
 export const CODEX_0142_FEATURE_KEYS = [
     'runtime_identity',
@@ -31,8 +31,9 @@ export async function detectCodex0142Capability(input = {}) {
         return blockedCapability('blocked', null, null, [...runtime.blockers]);
     }
     const versionOk = compareSemverLike(runtime.identity.version, CURRENT_CODEX_RELEASE_MANIFEST.requiredCliVersion) >= 0;
-    const schemaProbe = await generateSchemaProbe(root, runtime.identity.realpath);
-    const appServerClientText = await fsp.readFile(path.join(root, 'src', 'core', 'codex-control', 'codex-app-server-v2-client.ts'), 'utf8').catch(() => '');
+    const schemaProbe = await schemaProbeForMode(root, runtime.identity.realpath, input.requireReal === true);
+    const implementationRoot = packageRoot();
+    const appServerClientText = await fsp.readFile(path.join(implementationRoot, 'src', 'core', 'codex-control', 'codex-app-server-v2-client.ts'), 'utf8').catch(() => '');
     const states = featureStatesFromSchema(schemaProbe.text, schemaProbe.ok, appServerClientText);
     const blockers = [
         ...(versionOk ? [] : ['codex_0_142_required']),
@@ -40,6 +41,7 @@ export async function detectCodex0142Capability(input = {}) {
         ...Object.values(states).flatMap((state) => state.blockers)
     ];
     const realEnough = blockers.length === 0
+        && schemaProbe.mode === 'real-schema'
         && schemaProbe.sha256 !== null
         && CURRENT_CODEX_RELEASE_MANIFEST.generatedSchemaSha256 !== 'pending-generated-schema'
         && schemaProbe.sha256 === CURRENT_CODEX_RELEASE_MANIFEST.generatedSchemaSha256
@@ -54,7 +56,7 @@ export async function detectCodex0142Capability(input = {}) {
         runtime_identity: runtime.identity,
         generated_schema_sha256: schemaProbe.sha256,
         manifest_schema_sha256: CURRENT_CODEX_RELEASE_MANIFEST.generatedSchemaSha256,
-        probe_mode: schemaProbe.ok ? 'real-schema' : 'blocked',
+        probe_mode: schemaProbe.ok ? schemaProbe.mode : 'blocked',
         feature_states: states,
         blockers,
         warnings: [
@@ -133,7 +135,37 @@ function currentTimeState(schemaTextLower, schemaOk, appServerClientText) {
         blockers: clientHandlesCurrentTime ? [] : ['codex_0142_current_time_read_handler_not_verified']
     };
 }
+async function schemaProbeForMode(root, codexBin, requireReal) {
+    if (!requireReal && process.env.SKS_CODEX_0142_REFRESH !== '1') {
+        const shipped = await shippedSchemaProbe();
+        if (shipped.ok)
+            return shipped;
+    }
+    return generateSchemaProbe(root, codexBin);
+}
+async function shippedSchemaProbe() {
+    const schemaRoot = path.join(packageRoot(), 'schemas', 'codex', 'app-server-0.142');
+    const files = await listFiles(schemaRoot).catch(() => []);
+    if (!files.length)
+        return { ok: false, text: 'shipped schema cache missing', sha256: null, mode: 'shipped-manifest-cache' };
+    const rows = await Promise.all(files.map(async (file) => {
+        const text = await fsp.readFile(file, 'utf8');
+        return {
+            relative: path.relative(schemaRoot, file),
+            text,
+            canonicalText: canonicalSchemaContent(file, text)
+        };
+    }));
+    const joined = rows.map((row) => `${row.relative}\n${row.text}`).join('\n');
+    const canonicalJoined = rows.map((row) => `${row.relative}\n${row.canonicalText}`).join('\n');
+    return { ok: true, text: joined, sha256: sha256(canonicalJoined), mode: 'shipped-manifest-cache' };
+}
 async function generateSchemaProbe(root, codexBin) {
+    const cachePath = await schemaCachePath(root, codexBin);
+    const cached = await readJson(cachePath, null).catch(() => null);
+    if (cached?.ok === true && typeof cached.text === 'string' && cached.sha256) {
+        return { ok: true, text: cached.text, sha256: cached.sha256, mode: 'real-schema' };
+    }
     const out = path.join(os.tmpdir(), `sks-codex-0142-schema-${process.pid}-${Date.now()}`);
     await ensureDir(out);
     const result = await runProcess(codexBin, ['app-server', 'generate-json-schema', '--out', out], {
@@ -150,7 +182,7 @@ async function generateSchemaProbe(root, codexBin) {
         timedOut: false
     }));
     if (result.code !== 0)
-        return { ok: false, text: `${result.stdout}\n${result.stderr}`, sha256: null };
+        return { ok: false, text: `${result.stdout}\n${result.stderr}`, sha256: null, mode: 'real-schema' };
     const files = await listFiles(out);
     const rows = await Promise.all(files.map(async (file) => {
         const text = await fsp.readFile(file, 'utf8');
@@ -163,7 +195,20 @@ async function generateSchemaProbe(root, codexBin) {
     const joined = rows.map((row) => `${row.relative}\n${row.text}`).join('\n');
     const canonicalJoined = rows.map((row) => `${row.relative}\n${row.canonicalText}`).join('\n');
     await fsp.rm(out, { recursive: true, force: true }).catch(() => { });
-    return { ok: true, text: joined, sha256: sha256(canonicalJoined) };
+    const probe = { ok: true, text: joined, sha256: sha256(canonicalJoined), mode: 'real-schema' };
+    await writeJsonAtomic(cachePath, probe).catch(() => undefined);
+    return probe;
+}
+async function schemaCachePath(root, codexBin) {
+    const realpath = await fsp.realpath(codexBin).catch(() => codexBin);
+    const key = sha256(JSON.stringify({
+        realpath,
+        target: CURRENT_CODEX_RELEASE_MANIFEST.targetTag,
+        manifest_schema_sha256: CURRENT_CODEX_RELEASE_MANIFEST.generatedSchemaSha256,
+        platform: process.platform,
+        arch: process.arch
+    }));
+    return path.join(root, '.sneakoscope', 'cache', 'codex-0142-schema', `${key}.json`);
 }
 function canonicalSchemaContent(file, text) {
     if (!file.endsWith('.json'))

package/dist/core/codex-control/codex-app-server-v2-client.js

@@ -1,5 +1,5 @@
 import { spawn } from 'node:child_process';
-import { nowIso } from '../fsx.js';
+import { nowIso, PACKAGE_VERSION } from '../fsx.js';
 import { resolveCodexRuntime } from '../codex-runtime/resolve-codex-runtime.js';
 export class CodexAppServerV2Client {
     command;
@@ -28,7 +28,7 @@ export class CodexAppServerV2Client {
             clientInfo: {
                 name: 'sneakoscope-codex-app-server-v2',
                 title: 'Sneakoscope Codex app-server v2',
-                version: '4.1.0'
+                version: PACKAGE_VERSION
             },
             capabilities: {
                 experimentalApi: true,

package/dist/core/codex-native/codex-native-feature-broker.js

@@ -16,11 +16,34 @@ import { codexNativeFeatureState, computeCodexNativeInvocationDefaults } from '.
 const REPORT_PATH = '.sneakoscope/reports/codex-native-feature-matrix.json';
 const REQUIRED_SKILL_NAMES = MANAGED_SKILLS.map((skill) => skill.id);
 const REQUIRED_AGENT_ROLES = MANAGED_AGENT_ROLES.map((role) => role.id);
+const invocationMatrixCache = new Map();
 export async function buildCodexNativeFeatureMatrix(input = { root: process.cwd() }) {
     const root = path.resolve(input.root || process.cwd());
+    if (input.snapshot) {
+        await writeCodexNativeFeatureMatrix(root, input.snapshot, input.missionDir);
+        return input.snapshot;
+    }
     const deprecatedApplyRepairs = input.applyRepairs === true;
     const mode = input.mode || (deprecatedApplyRepairs || input.repairManagedAssets === true ? 'repair' : 'read-only');
     const repairManagedAssets = mode === 'repair' && (input.repairManagedAssets === true || deprecatedApplyRepairs);
+    const managedAssetFingerprint = await readManagedAssetFingerprint(root);
+    const cacheKey = JSON.stringify({
+        root,
+        mode,
+        repairManagedAssets,
+        codexHome: process.env.CODEX_HOME || null,
+        managedAssetFingerprint,
+        fixture: [
+            process.env.SKS_CODEX_0138_FAKE,
+            process.env.SKS_CODEX_0139_FAKE,
+            process.env.SKS_CODEX_0140_FAKE,
+            process.env.SKS_CODEX_0142_FAKE,
+            process.env.SKS_CODEX_PLUGIN_JSON_FAKE
+        ]
+    });
+    if (!input.missionDir && !repairManagedAssets && invocationMatrixCache.has(cacheKey)) {
+        return invocationMatrixCache.get(cacheKey);
+    }
     const fixtureMode = process.env.SKS_CODEX_0138_FAKE === '1' || process.env.SKS_CODEX_0139_FAKE === '1' || process.env.SKS_CODEX_0140_FAKE === '1' || process.env.SKS_CODEX_0142_FAKE === '1' || process.env.SKS_CODEX_PLUGIN_JSON_FAKE === '1';
     const codexBin = fixtureMode ? process.env.CODEX_BIN || 'codex' : await findCodexBinary().catch(() => null);
     const version = codexBin ? await codexVersion(codexBin) : null;
@@ -190,6 +213,8 @@ export async function buildCodexNativeFeatureMatrix(input = { root: process.cwd(
         invocation_defaults: computeCodexNativeInvocationDefaults(matrixBase)
     };
     await writeCodexNativeFeatureMatrix(root, matrix, input.missionDir);
+    if (!input.missionDir && !repairManagedAssets)
+        invocationMatrixCache.set(cacheKey, matrix);
     return matrix;
 }
 async function inspectManagedSkillState(root) {
@@ -252,6 +277,31 @@ async function inspectManagedAgentRoleState(root) {
         warnings: existingCount > managed.size ? ['non_sks_agent_roles_ignored'] : []
     };
 }
+async function readManagedAssetFingerprint(root) {
+    const dirs = [
+        path.join(root, '.agents', 'skills'),
+        path.join(root, '.codex', 'agents'),
+        ...(process.env.CODEX_HOME ? [path.join(process.env.CODEX_HOME, 'skills'), path.join(process.env.CODEX_HOME, 'agents')] : [])
+    ];
+    const rows = [];
+    for (const dir of dirs) {
+        const stat = await fs.stat(dir).catch(() => null);
+        rows.push(`${dir}:${stat ? `${stat.mtimeMs}:${stat.size}` : 'missing'}`);
+        const entries = await fs.readdir(dir, { withFileTypes: true }).catch(() => []);
+        for (const entry of entries) {
+            const file = path.join(dir, entry.name);
+            const childStat = await fs.stat(file).catch(() => null);
+            rows.push(`${file}:${entry.isDirectory() ? 'dir' : 'file'}:${childStat ? `${childStat.mtimeMs}:${childStat.size}` : 'missing'}`);
+            if (entry.isDirectory()) {
+                const skillFile = path.join(file, 'SKILL.md');
+                const skillStat = await fs.stat(skillFile).catch(() => null);
+                if (skillStat)
+                    rows.push(`${skillFile}:file:${skillStat.mtimeMs}:${skillStat.size}`);
+            }
+        }
+    }
+    return rows;
+}
 export async function writeCodexNativeFeatureMatrix(root, matrix, missionDir) {
     await writeJsonAtomic(path.join(root, REPORT_PATH), matrix);
     if (missionDir)

package/dist/core/codex-native/native-capability-postcheck.js

@@ -7,13 +7,19 @@ export async function postcheckNativeCapabilities(input) {
     const fixture = input.fixture || false;
     const matrix = input.matrix || await buildNativeCapabilityRepairMatrix({ root, fixture, reportPath: null });
     const capabilities = await Promise.all(matrix.capabilities.map((state) => postcheckCapability(root, state, fixture)));
-    const blockers = capabilities.flatMap((state) => state.after === 'verified' || state.after === 'degraded' ? [] : state.blockers);
+    const coreBlockers = capabilities.flatMap((state) => state.core_blockers || []);
+    const routeBlockers = mergeRouteBlockers(capabilities);
     const checked = {
         ...matrix,
         generated_at: new Date().toISOString(),
-        ok: blockers.length === 0,
+        ok: coreBlockers.length === 0,
         capabilities,
-        blockers,
+        core_blockers: coreBlockers,
+        route_blockers: routeBlockers,
+        optional_manual_required: capabilities
+            .filter((state) => state.availability === 'manual-required' && state.after !== 'verified')
+            .map((state) => state.id),
+        blockers: coreBlockers,
         warnings: capabilities.flatMap((state) => state.warnings)
     };
     const reportPath = input.reportPath === null
@@ -48,17 +54,19 @@ function postcheckImageGeneration(state, fixture) {
     return {
         ...state,
         after: 'unknown',
-        blockers: ['imagegen_auth_or_codex_app_builtin_missing'],
+        core_blockers: [],
+        route_blockers: mergeStateRouteBlockers(state, 'route-image', ['imagegen_auth_or_codex_app_builtin_missing']),
+        blockers: [],
         warnings: [...new Set([...state.warnings, 'image_generation_not_verified_without_real_capability'])]
     };
 }
 async function postcheckImageFollowupEdit(root, state) {
     const contract = await validateSavedArtifactPathContract(root);
     if (!contract.ok)
-        return { ...state, after: 'blocked', blockers: contract.blockers };
+        return routeBlocked(state, 'route-image', contract.blockers);
     const sample = path.join(contract.imageArtifacts, 'postcheck-followup-sample.txt');
     if (!(await writeReadSample(sample)))
-        return { ...state, after: 'blocked', blockers: ['image_followup_sample_artifact_unwritable'] };
+        return routeBlocked(state, 'route-image', ['image_followup_sample_artifact_unwritable']);
     return verified(state);
 }
 function postcheckComputerUse(state, _fixture) {
@@ -67,7 +75,9 @@ function postcheckComputerUse(state, _fixture) {
     return {
         ...state,
         after: 'unknown',
-        blockers: ['computer_use_os_permission_or_capability_unknown'],
+        core_blockers: [],
+        route_blockers: mergeStateRouteBlockers(state, 'route-computer-use', ['computer_use_os_permission_or_capability_unknown']),
+        blockers: [],
         warnings: [...new Set([...state.warnings, 'manual_os_permission_required'])]
     };
 }
@@ -77,7 +87,9 @@ function postcheckChromeWebReview(state, fixture) {
     return {
         ...state,
         after: 'unknown',
-        blockers: ['codex_chrome_extension_readiness_not_verified'],
+        core_blockers: [],
+        route_blockers: mergeStateRouteBlockers(state, 'route-chrome-web-review', ['codex_chrome_extension_readiness_not_verified']),
+        blockers: [],
         warnings: [...new Set([...state.warnings, 'manual_chrome_extension_setup_required'])]
     };
 }
@@ -88,12 +100,12 @@ async function postcheckAppScreenshot(root, state) {
     const dir = path.join(root, '.sneakoscope', 'app-screenshots');
     const registry = path.join(dir, 'screenshot-registry.json');
     if (!(await writeReadSample(path.join(dir, 'postcheck-screenshot-sample.txt')))) {
-        return { ...state, after: 'blocked', blockers: ['app_screenshot_directory_unwritable'] };
+        return routeBlocked(state, 'route-image', ['app_screenshot_directory_unwritable']);
     }
     await writeJsonAtomic(registry, { schema: 'sks.app-screenshot-registry.v1', generated_at: new Date().toISOString(), screenshots: [] }).catch(() => undefined);
     const json = await readJson(registry, {}).catch(() => ({}));
     if (json.schema !== 'sks.app-screenshot-registry.v1')
-        return { ...state, after: 'blocked', blockers: ['app_screenshot_registry_invalid'] };
+        return routeBlocked(state, 'route-image', ['app_screenshot_registry_invalid']);
     return verified(state);
 }
 function postcheckAppHandoff(state, fixture) {
@@ -102,7 +114,9 @@ function postcheckAppHandoff(state, fixture) {
     return {
         ...state,
         after: 'unknown',
-        blockers: ['codex_app_handoff_not_verified'],
+        core_blockers: [],
+        route_blockers: mergeStateRouteBlockers(state, 'route-app-handoff', ['codex_app_handoff_not_verified']),
+        blockers: [],
         warnings: [...new Set([...state.warnings, 'manual_app_handoff_approval_required'])]
     };
 }
@@ -114,24 +128,53 @@ async function postcheckImagePathExposure(root, state, fixture) {
         return {
             ...state,
             after: 'degraded',
+            availability: 'available-unverified',
+            core_blockers: [],
+            route_blockers: {},
             blockers: [],
             warnings: [...new Set([...state.warnings, 'using_saved_artifact_path_contract_fallback'])]
         };
     }
-    return { ...state, after: 'blocked', blockers: ['image_path_exposure_missing_without_fallback_contract', ...contract.blockers] };
+    return routeBlocked(state, 'route-image', ['image_path_exposure_missing_without_fallback_contract', ...contract.blockers]);
 }
 async function postcheckSavedArtifactPathContract(root, state) {
     const contract = await validateSavedArtifactPathContract(root);
     if (!contract.ok)
-        return { ...state, after: 'blocked', blockers: contract.blockers };
+        return routeBlocked(state, 'route-image', contract.blockers);
     if (!(await writeReadSample(path.join(contract.imageArtifacts, 'postcheck-contract-image.txt'))))
-        return { ...state, after: 'blocked', blockers: ['image_artifacts_directory_unwritable'] };
+        return routeBlocked(state, 'route-image', ['image_artifacts_directory_unwritable']);
     if (!(await writeReadSample(path.join(contract.appScreenshots, 'postcheck-contract-screenshot.txt'))))
-        return { ...state, after: 'blocked', blockers: ['app_screenshots_directory_unwritable'] };
+        return routeBlocked(state, 'route-image', ['app_screenshots_directory_unwritable']);
     return verified(state);
 }
 function verified(state) {
-    return { ...state, after: 'verified', blockers: [] };
+    return { ...state, after: 'verified', availability: 'verified', core_blockers: [], route_blockers: {}, blockers: [] };
+}
+function routeBlocked(state, scope, blockers) {
+    return {
+        ...state,
+        after: 'blocked',
+        core_blockers: [],
+        route_blockers: mergeStateRouteBlockers(state, scope, blockers),
+        blockers: []
+    };
+}
+function mergeStateRouteBlockers(state, scope, blockers) {
+    return {
+        ...(state.route_blockers || {}),
+        [scope]: [...new Set([...(state.route_blockers?.[scope] || []), ...blockers])]
+    };
+}
+function mergeRouteBlockers(states) {
+    const merged = {};
+    for (const state of states) {
+        for (const [scope, blockers] of Object.entries(state.route_blockers || {})) {
+            merged[scope] = [
+                ...new Set([...(merged[scope] || []), ...blockers])
+            ];
+        }
+    }
+    return merged;
 }
 async function validateSavedArtifactPathContract(root) {
     const contractPath = path.join(root, '.sneakoscope', 'reports', 'saved-artifact-path-contract.json');

package/dist/core/codex-native/native-capability-repair-matrix.js

@@ -24,14 +24,20 @@ export async function buildNativeCapabilityRepairMatrix(input) {
         ? fixtureNativeFeatureMatrix(fixture)
         : await buildCodexNativeFeatureMatrix({ root, mode: 'read-only' }).catch((err) => ({ ok: false, features: {}, blockers: [messageOf(err)], invocation_defaults: {} }));
     const states = await Promise.all(NATIVE_CAPABILITY_IDS.filter((id) => selected.has(id)).map((id) => stateForCapability(root, id, imageCapability, nativeFeatureMatrix)));
-    const blockers = states.flatMap((state) => state.blockers);
+    const coreBlockers = states.flatMap((state) => state.core_blockers || state.blockers);
+    const routeBlockers = mergeRouteBlockers(states);
     const warnings = states.flatMap((state) => state.warnings);
     const matrix = {
         schema: 'sks.native-capability-repair-matrix.v1',
         generated_at: nowIso(),
-        ok: blockers.length === 0,
+        ok: coreBlockers.length === 0,
         capabilities: states,
-        blockers,
+        core_blockers: coreBlockers,
+        route_blockers: routeBlockers,
+        optional_manual_required: states
+            .filter((state) => state.availability === 'manual-required' && state.required_for.every((scope) => !isCoreScope(scope)))
+            .map((state) => state.id),
+        blockers: coreBlockers,
         warnings
     };
     const reportPath = input.reportPath === null
@@ -49,10 +55,15 @@ async function stateForCapability(root, id, imageCapability, nativeFeatureMatrix
             id,
             before: verified ? 'verified' : 'blocked',
             repairability: verified ? 'auto' : 'manual-required',
-            repair_actions: verified ? ['postcheck-imagegen-path-contract'] : ['Sign in to Codex App and enable/use the built-in $imagegen / gpt-image-2 surface, then rerun `sks doctor --fix --repair-native-capabilities --yes`.'],
+            availability: verified ? 'verified' : 'manual-required',
+            required_for: ['route-image'],
+            repair_actions: verified ? ['postcheck-imagegen-path-contract'] : ['Sign in to Codex App and enable/use the built-in $imagegen / gpt-image-2 surface, then rerun `sks doctor --capabilities --yes`.'],
             after: null,
             artifact_path: path.join(reports, 'native-capability-repair-matrix.json'),
-            blockers: verified ? [] : ['imagegen_auth_or_codex_app_builtin_missing'],
+            core_blockers: [],
+            route_blockers: verified ? {} : { 'route-image': ['imagegen_auth_or_codex_app_builtin_missing'] },
+            manual_actions: verified ? [] : ['Sign in to Codex App and enable/use the built-in $imagegen / gpt-image-2 surface before image routes.'],
+            blockers: [],
             warnings: verified ? [] : ['image_generation_not_verified_without_real_capability']
         };
     }
@@ -75,10 +86,15 @@ async function stateForCapability(root, id, imageCapability, nativeFeatureMatrix
             id,
             before: ok ? 'verified' : 'unknown',
             repairability: ok ? 'auto' : 'manual-required',
-            repair_actions: ok ? ['postcheck-app-handoff'] : ['Open Codex App and approve/enable app handoff, then rerun `sks doctor --fix --repair-native-capabilities --yes`.'],
+            availability: ok ? 'verified' : 'manual-required',
+            required_for: ['route-app-handoff'],
+            repair_actions: ok ? ['postcheck-app-handoff'] : ['Open Codex App and approve/enable app handoff, then rerun `sks doctor --capabilities --yes`.'],
             after: null,
             artifact_path: path.join(reports, 'native-capability-repair-matrix.json'),
-            blockers: ok ? [] : ['codex_app_handoff_not_verified'],
+            core_blockers: [],
+            route_blockers: ok ? {} : { 'route-app-handoff': ['codex_app_handoff_not_verified'] },
+            manual_actions: ok ? [] : ['Open Codex App and approve/enable app handoff before app handoff routes.'],
+            blockers: [],
             warnings: ok ? [] : ['manual_app_handoff_approval_required']
         };
     }
@@ -89,10 +105,15 @@ async function stateForCapability(root, id, imageCapability, nativeFeatureMatrix
             id,
             before: ok ? 'verified' : fallback ? 'degraded' : 'missing',
             repairability: ok ? 'auto' : 'doctor-fix',
+            availability: ok ? 'verified' : fallback ? 'available-unverified' : 'unavailable',
+            required_for: ['route-image'],
             repair_actions: ok ? ['postcheck-image-path-exposure'] : ['create-saved-artifact-path-contract'],
             after: null,
             artifact_path: path.join(reports, 'saved-artifact-path-contract.json'),
-            blockers: ok || fallback ? [] : ['image_path_exposure_missing_without_fallback_contract'],
+            core_blockers: [],
+            route_blockers: ok || fallback ? {} : { 'route-image': ['image_path_exposure_missing_without_fallback_contract'] },
+            manual_actions: [],
+            blockers: [],
             warnings: ok ? [] : ['using_saved_artifact_path_contract_fallback']
         };
     }
@@ -101,11 +122,16 @@ async function stateForCapability(root, id, imageCapability, nativeFeatureMatrix
         return {
             id,
             before: envVerified ? 'verified' : 'unknown',
+            availability: envVerified ? 'verified' : 'manual-required',
+            required_for: ['route-computer-use'],
             repairability: envVerified ? 'auto' : 'manual-required',
-            repair_actions: envVerified ? ['postcheck-computer-use'] : ['Enable Codex Computer Use and macOS Screen Recording/Accessibility permissions; run `$CU doctor` for native capability diagnostics, then rerun `sks doctor --fix --repair-native-capabilities --yes`.'],
+            repair_actions: envVerified ? ['postcheck-computer-use'] : ['Enable Codex Computer Use and macOS Screen Recording/Accessibility permissions; run `$CU doctor` for native capability diagnostics, then rerun `sks doctor --capabilities --yes`.'],
             after: null,
             artifact_path: path.join(reports, 'native-capability-repair-matrix.json'),
-            blockers: envVerified ? [] : ['computer_use_os_permission_or_capability_unknown'],
+            core_blockers: [],
+            route_blockers: envVerified ? {} : { 'route-computer-use': ['computer_use_os_permission_or_capability_unknown'] },
+            manual_actions: envVerified ? [] : ['Enable Codex Computer Use and macOS Screen Recording/Accessibility permissions before `$CU` routes.'],
+            blockers: [],
             warnings: envVerified ? [] : ['manual_os_permission_required']
         };
     }
@@ -113,11 +139,16 @@ async function stateForCapability(root, id, imageCapability, nativeFeatureMatrix
     return {
         id,
         before: chromeReady ? 'verified' : 'unknown',
+        availability: chromeReady ? 'verified' : 'manual-required',
+        required_for: ['route-chrome-web-review'],
         repairability: chromeReady ? 'auto' : 'manual-required',
-        repair_actions: chromeReady ? ['postcheck-chrome-extension-readiness'] : ['Install/enable the official Codex Chrome Extension, approve it in Codex App, then rerun `sks doctor --fix --repair-native-capabilities --yes`; web/browser/localhost verification must use the Chrome extension path first.'],
+        repair_actions: chromeReady ? ['postcheck-chrome-extension-readiness'] : ['Install/enable the official Codex Chrome Extension, approve it in Codex App, then rerun `sks doctor --capabilities --yes`; web/browser/localhost verification must use the Chrome extension path first.'],
         after: null,
         artifact_path: path.join(reports, 'native-capability-repair-matrix.json'),
-        blockers: chromeReady ? [] : ['codex_chrome_extension_readiness_not_verified'],
+        core_blockers: [],
+        route_blockers: chromeReady ? {} : { 'route-chrome-web-review': ['codex_chrome_extension_readiness_not_verified'] },
+        manual_actions: chromeReady ? [] : ['Install/enable the official Codex Chrome Extension before browser/web review routes.'],
+        blockers: [],
         warnings: chromeReady ? [] : ['manual_chrome_extension_setup_required']
     };
 }
@@ -157,14 +188,47 @@ function autoState(id, ready, artifactPath, actions) {
     return {
         id,
         before: ready ? 'verified' : 'missing',
+        availability: ready ? 'verified' : 'available-unverified',
+        required_for: routeScopesForCapability(id),
         repairability: ready ? 'auto' : 'doctor-fix',
         repair_actions: ready ? [`postcheck-${id}`] : actions,
         after: null,
         artifact_path: artifactPath,
-        blockers: ready ? [] : [`${id}_repair_required`],
+        core_blockers: [],
+        route_blockers: ready ? {} : routeBlockerForCapability(id, `${id}_repair_required`),
+        manual_actions: [],
+        blockers: [],
         warnings: []
     };
 }
+function routeScopesForCapability(id) {
+    if (id === 'image_followup_edit' || id === 'saved_artifact_path_contract' || id === 'codex_app_screenshot')
+        return ['route-image'];
+    if (id === 'app_handoff')
+        return ['route-app-handoff'];
+    if (id === 'computer_use')
+        return ['route-computer-use'];
+    if (id === 'chrome_web_review')
+        return ['route-chrome-web-review'];
+    return [];
+}
+function routeBlockerForCapability(id, blocker) {
+    const scopes = routeScopesForCapability(id);
+    return Object.fromEntries(scopes.map((scope) => [scope, [blocker]]));
+}
+function mergeRouteBlockers(states) {
+    const merged = {};
+    for (const state of states) {
+        for (const [scope, blockers] of Object.entries(state.route_blockers || {})) {
+            const next = [...(merged[scope] || []), ...blockers];
+            merged[scope] = [...new Set(next)];
+        }
+    }
+    return merged;
+}
+function isCoreScope(scope) {
+    return scope === 'core-cli' || scope === 'mad-interactive' || scope === 'managed-migration';
+}
 function featureOk(matrix, feature) {
     return matrix?.features?.[feature]?.ok === true;
 }