sneakoscope 8.3.2 → 8.6.0

package/dist/core/release/release-inspection-memo.js

@@ -0,0 +1,69 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { SksLruCache } from '../perf/lru-cache.js';
+export const RELEASE_INSPECTION_MEMO_ENV = 'SKS_RELEASE_INSPECTION_MEMO';
+const MAX_ENTRIES_PER_BUCKET = 64;
+const buckets = new Map();
+export function releaseInspectionMemoEnabled() {
+    return process.env[RELEASE_INSPECTION_MEMO_ENV] !== '0';
+}
+export function fileIdentity(file) {
+    try {
+        const stat = fs.lstatSync(file, { bigint: true });
+        if (!stat.isFile() || stat.isSymbolicLink())
+            return null;
+        return `${stat.dev}:${stat.ino}:${stat.size}:${stat.mtimeNs}:${stat.ctimeNs}`;
+    }
+    catch {
+        return null;
+    }
+}
+export function toolIdentity(command) {
+    const searchPath = String(process.env.PATH || '').split(path.delimiter).filter(Boolean);
+    for (const dir of searchPath) {
+        const candidate = path.join(dir, command);
+        let resolved;
+        try {
+            resolved = fs.realpathSync(candidate);
+        }
+        catch {
+            continue;
+        }
+        const identity = fileIdentity(resolved);
+        if (identity)
+            return `${candidate}>${resolved}#${identity}`;
+    }
+    return null;
+}
+export function inspectionKey(...parts) {
+    if (parts.some((part) => part === null || part === undefined))
+        return null;
+    return crypto.createHash('sha256').update(parts.map(String).join('\0')).digest('hex');
+}
+export function memoizeReleaseInspection(bucket, key, compute, clone = defaultClone) {
+    if (!key || !releaseInspectionMemoEnabled())
+        return compute();
+    let cache = buckets.get(bucket);
+    if (!cache) {
+        cache = new SksLruCache(MAX_ENTRIES_PER_BUCKET);
+        buckets.set(bucket, cache);
+    }
+    const hit = cache.get(key);
+    if (hit !== null)
+        return clone(hit);
+    const value = compute();
+    cache.set(key, value);
+    return clone(value);
+}
+function defaultClone(value) {
+    if (value === null || typeof value !== 'object')
+        return value;
+    return structuredClone(value);
+}
+export function cloneBuffer(value) {
+    return Buffer.from(value);
+}
+export function clearReleaseInspectionMemo() {
+    buckets.clear();
+}

package/dist/core/release/release-pack-content-scanner.js

@@ -3,7 +3,12 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
+import { fileIdentity, inspectionKey, memoizeReleaseInspection, toolIdentity } from './release-inspection-memo.js';
 export function scanTarballTextContents(input) {
+    const key = inspectionKey(input.temp_prefix, input.tarball, fileIdentity(input.tarball), toolIdentity('tar'), String(input.max_findings), input.include_allowlisted_count === true ? 'allowlisted' : 'plain', input.patterns.map((pattern) => `${pattern.kind}=${pattern.regex.source}/${pattern.regex.flags}`).join('\0'), String(input.allow_finding || 'no_allowlist'), String(input.finding_blocker));
+    return memoizeReleaseInspection('tarball-content-scan', key, () => computeTarballTextContents(input));
+}
+function computeTarballTextContents(input) {
     const temp = fs.mkdtempSync(path.join(os.tmpdir(), input.temp_prefix));
     const findings = [];
     const blockers = [];

package/dist/core/release/release-pack-receipt.js

@@ -6,6 +6,7 @@ import { spawnSync } from 'node:child_process';
 import { tmpdir } from '../fsx.js';
 import { DEFAULT_MAX_PACK_BYTES, DEFAULT_MAX_UNPACKED_BYTES } from './package-size-budget.js';
 import { readCurrentNpmPackGateArtifacts } from './npm-pack-proof.js';
+import { inspectionKey, memoizeReleaseInspection, toolIdentity } from './release-inspection-memo.js';
 import { scanTarballTextContents } from './release-pack-content-scanner.js';
 import { RELEASE_PACK_COMPARE_SCHEMA, RELEASE_PACK_RECEIPT_SCHEMA } from './release-pack-contract.js';
 import { tarInventory, tarPackageJson, tarUnpackedBytes } from './release-pack-tarball.js';
@@ -298,12 +299,32 @@ export function inspectLocalReleaseSourceState(root) {
     else if (String(fullStatus.stdout || '').split(/\r?\n/).some((line) => line.startsWith('?? '))) {
         blockers.push('npm_pack_untracked_files_present');
     }
+    const inventory = memoizeReleaseInspection('npm-pack-source-inventory', inspectionKey(path.resolve(root), head, toolIdentity('git'), toolIdentity('npm'), process.env.SKS_RELEASE_NPM_CACHE || '', String(trackedStatus.status), String(trackedStatus.stdout || ''), String(fullStatus.status), String(fullStatus.stdout || '')), () => packSourceInventory(root));
+    const trackedFiles = inventory.tracked_files ? new Set(inventory.tracked_files) : null;
+    if (!trackedFiles)
+        blockers.push('npm_pack_tracked_file_inventory_unavailable');
+    const packedFiles = inventory.packed_files;
+    if (!packedFiles)
+        blockers.push('npm_pack_dry_run_file_inventory_unavailable');
+    const packEligibleUntracked = trackedFiles && packedFiles
+        ? unique(packedFiles.filter((relative) => !trackedFiles.has(relative) && !isGeneratedDistPackagePath(relative))).sort()
+        : [];
+    if (packEligibleUntracked.length > 0)
+        blockers.push('npm_pack_eligible_untracked_files_present');
+    return {
+        ok: blockers.length === 0,
+        head,
+        source_tree_sha256: sourceTreeSha256,
+        tracked_changes: trackedChanges,
+        pack_eligible_untracked: packEligibleUntracked,
+        blockers: unique(blockers)
+    };
+}
+function packSourceInventory(root) {
     const trackedFilesResult = spawnSync('git', ['ls-files', '-z'], { cwd: root, encoding: 'utf8', maxBuffer: 32 * 1024 * 1024 });
     const trackedFiles = trackedFilesResult.status === 0
-        ? new Set(String(trackedFilesResult.stdout || '').split('\0').filter(Boolean).map(normalizePath))
+        ? unique(String(trackedFilesResult.stdout || '').split('\0').filter(Boolean).map(normalizePath))
         : null;
-    if (!trackedFiles)
-        blockers.push('npm_pack_tracked_file_inventory_unavailable');
     const dryRun = spawnSync('npm', ['pack', '--dry-run', '--ignore-scripts', '--json'], {
         cwd: root,
         encoding: 'utf8',
@@ -323,21 +344,7 @@ export function inspectLocalReleaseSourceState(root) {
             packedFiles = null;
         }
     }
-    if (!packedFiles)
-        blockers.push('npm_pack_dry_run_file_inventory_unavailable');
-    const packEligibleUntracked = trackedFiles && packedFiles
-        ? unique(packedFiles.filter((relative) => !trackedFiles.has(relative) && !isGeneratedDistPackagePath(relative))).sort()
-        : [];
-    if (packEligibleUntracked.length > 0)
-        blockers.push('npm_pack_eligible_untracked_files_present');
-    return {
-        ok: blockers.length === 0,
-        head,
-        source_tree_sha256: sourceTreeSha256,
-        tracked_changes: trackedChanges,
-        pack_eligible_untracked: packEligibleUntracked,
-        blockers: unique(blockers)
-    };
+    return { tracked_files: trackedFiles, packed_files: packedFiles };
 }
 export function writeReleaseJson(file, value) {
     fs.mkdirSync(path.dirname(file), { recursive: true });
@@ -536,6 +543,9 @@ function gitHead(root) {
     return result.status === 0 ? String(result.stdout || '').trim() : '';
 }
 function gitTreeSha256(root, commit) {
+    return memoizeReleaseInspection('git-tree-sha256', inspectionKey(path.resolve(root), commit, toolIdentity('git')), () => computeGitTreeSha256(root, commit));
+}
+function computeGitTreeSha256(root, commit) {
     if (!/^[a-f0-9]{40}$/i.test(commit))
         return '';
     const verified = spawnSync('git', ['rev-parse', '--verify', `${commit}^{commit}`], { cwd: root, encoding: 'utf8' });

package/dist/core/release/release-pack-tarball.js

@@ -2,7 +2,11 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
+import { fileIdentity, inspectionKey, memoizeReleaseInspection, toolIdentity } from './release-inspection-memo.js';
 export function tarInventory(tarball) {
+    return memoizeReleaseInspection('tar-inventory', inspectionKey(tarball, fileIdentity(tarball), toolIdentity('tar')), () => computeTarInventory(tarball));
+}
+function computeTarInventory(tarball) {
     const result = spawnSync('tar', ['-tzf', tarball], { encoding: 'utf8', maxBuffer: 32 * 1024 * 1024 });
     if (result.status !== 0)
         return { files: [], blockers: ['tarball_inventory_command_failed'] };
@@ -28,6 +32,9 @@ export function tarInventory(tarball) {
     return { files, blockers };
 }
 export function tarPackageJson(tarball) {
+    return memoizeReleaseInspection('tar-package-json', inspectionKey(tarball, fileIdentity(tarball), toolIdentity('tar')), () => computeTarPackageJson(tarball));
+}
+function computeTarPackageJson(tarball) {
     const result = spawnSync('tar', ['-xOzf', tarball, 'package/package.json'], { encoding: 'utf8', maxBuffer: 1024 * 1024 });
     if (result.status !== 0)
         return null;
@@ -40,6 +47,9 @@ export function tarPackageJson(tarball) {
     }
 }
 export function tarUnpackedBytes(tarball) {
+    return memoizeReleaseInspection('tar-unpacked-bytes', inspectionKey(tarball, fileIdentity(tarball), toolIdentity('tar')), () => computeTarUnpackedBytes(tarball));
+}
+function computeTarUnpackedBytes(tarball) {
     const temp = fs.mkdtempSync(path.join(os.tmpdir(), 'sks-release-pack-unpacked-'));
     try {
         const result = spawnSync('tar', ['-xzf', tarball, '-C', temp], { encoding: 'utf8', maxBuffer: 32 * 1024 * 1024 });

package/dist/core/release/release-upgrade-baseline.js

@@ -4,6 +4,10 @@ export const RELEASE_UPGRADE_BASELINE_SHA256 = '40a9e89f3a234dfcd32507ab7deeb950
 export function releaseUpgradeProofFilename(targetVersion) {
     return `upgrade-${RELEASE_UPGRADE_BASELINE_LABEL}-to-${targetVersion}.json`;
 }
+export function isExpectedReleaseUpgradeLaunchctlCall(call) {
+    return /^(?:unsetenv (?:CODEX_LB_API_KEY|OPENROUTER_API_KEY)|print|bootout (?:com\.sneakoscope\.sks-menubar|com\.sneakoscope\.telegram-hub))$/
+        .test(String(call));
+}
 export function releaseUpgradeExpectedVersion(stateName, targetVersion) {
     return stateName.startsWith('target_') ? targetVersion : RELEASE_UPGRADE_BASELINE_VERSION;
 }

package/dist/core/routes.js

@@ -647,7 +647,7 @@ export const COMMAND_CATALOG = [
     { name: 'check', usage: 'sks check --tier instant|affected|confidence|release|real-check [--sla 5m] [--changed-since auto] [--json]', description: 'Run build-once proof-bank checks: affected/confidence use incremental build and cached proof reuse; release keeps full clean proof for publish readiness.' },
     { name: 'task', usage: 'sks task run [--sla 5m] [--json]', description: 'Run the normal affected-scope, release-equivalent task verification path.' },
     { name: 'release', usage: 'sks release affected|full|background|stage [--json]', description: 'Run affected release proof, full release proof, or background release proof explicitly, or drive the staged npm publish up to the human approval step.' },
-    { name: 'triwiki', usage: 'sks triwiki index|affected|proof-bank [--json]', description: 'Inspect TriWiki module cards, gate impact maps, affected graphs, and proof bank status.' },
+    { name: 'triwiki', usage: 'sks triwiki index|affected|proof-bank|graph-status|graph-lint|graph-query|atlas-status|atlas-lint|atlas-list|atlas-show|atlas-why [--json]', description: 'Inspect TriWiki module cards, gate impact maps, affected graphs, proof bank status, and Architecture Map views.' },
     { name: 'daemon', usage: 'sks daemon status|warm|stop [--json]', description: 'Inspect or warm the local SKS daemon cache state for build/proof reuse.' },
     { name: 'run', usage: 'sks run "task" [--visual|--research|--db] [--json]', description: 'Classify a plain-language task, materialize a mission, and route it through the SKS trust kernel.' },
     { name: 'plan', usage: 'sks plan "task" [--json]', description: 'Write a planning-only artifact under .sneakoscope/plans without editing code.' },

package/dist/core/safety/ssot-authority-inventory.js

@@ -0,0 +1,114 @@
+export const SKS_SSOT_AUTHORITY_INVENTORY = Object.freeze([
+    Object.freeze({
+        id: 'route_contract',
+        title: 'Route contract',
+        authorityKind: 'runtime_owner',
+        canonicalSources: Object.freeze([
+            'decision-contract.json, route prompt, and pipeline-plan.json'
+        ]),
+        allowedWriters: Object.freeze(['pipeline plan writer', 'request intake']),
+        allowedReaders: Object.freeze(['naruto', 'workers', 'stop gate']),
+        derivedArtifacts: Object.freeze([
+            'subagent-plan.json',
+            'subagent-events.jsonl',
+            'worker inboxes'
+        ]),
+        protected: true,
+        description: 'The sealed user objective, constraints, non-goals, and acceptance criteria define what code may be created.',
+        authority: 'The sealed user objective, constraints, non-goals, and acceptance criteria define what code may be created.',
+        rule: 'Do not implement behavior outside the sealed route contract; block with evidence if the requested path cannot be honored.'
+    }),
+    Object.freeze({
+        id: 'triwiki_context',
+        title: 'TriWiki context pack',
+        authorityKind: 'file',
+        canonicalSources: Object.freeze(['.sneakoscope/wiki/context-pack.json']),
+        allowedWriters: Object.freeze(['sks wiki pack', 'sks align run', 'triwiki refresh']),
+        allowedReaders: Object.freeze(['pipeline stages', 'naruto parent', 'honest mode']),
+        derivedArtifacts: Object.freeze([
+            'subagent-parent-summary.json',
+            'subagent-evidence.json',
+            'reflection.md'
+        ]),
+        protected: true,
+        description: 'TriWiki is the bounded mission context SSOT and must be refreshed or packed, then validated before risky handoffs and final claims.',
+        authority: 'TriWiki is the bounded mission context SSOT and must be refreshed or packed, then validated before risky handoffs and final claims.',
+        rule: 'Use the latest coordinate+voxel overlay pack; coordinate-only legacy packs are invalid for pipeline decisions.'
+    }),
+    Object.freeze({
+        id: 'runtime_source',
+        title: 'TypeScript runtime source',
+        authorityKind: 'file',
+        canonicalSources: Object.freeze(['src/**/*.ts']),
+        allowedWriters: Object.freeze(['implementation workers under sealed route']),
+        allowedReaders: Object.freeze(['build', 'tests', 'release gates']),
+        derivedArtifacts: Object.freeze(['dist/**', 'dist/bin/sks.js']),
+        protected: true,
+        description: 'TypeScript source is the runtime SSOT.',
+        authority: 'TypeScript source is the runtime SSOT.',
+        rule: 'Edit source, rebuild derived output, and rely on runtime:ts-source-of-truth plus runtime:dist-parity.'
+    }),
+    Object.freeze({
+        id: 'generated_outputs',
+        title: 'Generated outputs',
+        authorityKind: 'generated_projection',
+        canonicalSources: Object.freeze([
+            'source generators, build scripts, and schema definitions'
+        ]),
+        allowedWriters: Object.freeze(['generators', 'build scripts']),
+        allowedReaders: Object.freeze(['release', 'doctor', 'install']),
+        derivedArtifacts: Object.freeze([
+            'release-gates.v2.json',
+            'infra-harness-gates.json',
+            '.sneakoscope/reports/**',
+            'dist/build-manifest.json'
+        ]),
+        protected: true,
+        description: 'Generated files are derived from their generator or schema owner.',
+        authority: 'Generated files are derived from their generator or schema owner.',
+        rule: 'Regenerate derived artifacts instead of hand-editing them as independent truth.'
+    }),
+    Object.freeze({
+        id: 'stack_current_docs',
+        title: 'Stack current docs',
+        authorityKind: 'file',
+        canonicalSources: Object.freeze(['.sneakoscope/memory/q2_facts/stack-current-docs.md']),
+        allowedWriters: Object.freeze(['Context7 hydration', 'docs refresh']),
+        allowedReaders: Object.freeze(['implementation', 'research']),
+        derivedArtifacts: Object.freeze(['implementation notes', 'route evidence']),
+        protected: false,
+        description: 'Current vendor or Context7 docs override model-memory defaults when stack versions or APIs change.',
+        authority: 'Current vendor or Context7 docs override model-memory defaults when stack versions or APIs change.',
+        rule: 'Fetch and record current docs before relying on external package, SDK, API, MCP, or generated-doc behavior that may have changed.'
+    }),
+    Object.freeze({
+        id: 'release_gate_manifest',
+        title: 'Release gate manifest',
+        authorityKind: 'manifest',
+        canonicalSources: Object.freeze([
+            'src/core/release/gate-manifest.ts and src/scripts/release-parallel-check.ts'
+        ]),
+        allowedWriters: Object.freeze(['release maintainers via source edit']),
+        allowedReaders: Object.freeze(['release DAG', 'publish preflight']),
+        derivedArtifacts: Object.freeze([
+            '.sneakoscope/reports/release-gate-plan.json',
+            '.sneakoscope/reports/gate-policy-audit.json'
+        ]),
+        protected: true,
+        description: 'Release gate selection and publish-required status live in the manifest plus the release DAG.',
+        authority: 'Release gate selection and publish-required status live in the manifest plus the release DAG.',
+        rule: 'Publish-blocking guard gates must appear in the DAG, manifest, and package scripts.'
+    })
+]);
+export function canonicalSsotAuthorityInventory() {
+    return SKS_SSOT_AUTHORITY_INVENTORY;
+}
+export function inventoryAsSsotGuardSources() {
+    return SKS_SSOT_AUTHORITY_INVENTORY.map((domain) => ({
+        id: domain.id,
+        source: domain.canonicalSources.join(', '),
+        authority: domain.authority,
+        derived: [...domain.derivedArtifacts],
+        rule: domain.rule
+    }));
+}

package/dist/core/safety/ssot-guard.js

@@ -1,5 +1,6 @@
 import { nowIso } from '../fsx.js';
 import { isRecord } from '../json/records.js';
+import { inventoryAsSsotGuardSources } from './ssot-authority-inventory.js';
 export const SSOT_GUARD_SCHEMA = 'sks.ssot-guard.v1';
 export const SSOT_GUARD_ARTIFACT = 'ssot-guard.json';
 export function buildSsotGuard(input = {}) {
@@ -34,50 +35,7 @@ export function buildSsotGuard(input = {}) {
     };
 }
 export function canonicalSsotSources() {
-    return [
-        {
-            id: 'route_contract',
-            source: 'decision-contract.json, route prompt, and pipeline-plan.json',
-            authority: 'The sealed user objective, constraints, non-goals, and acceptance criteria define what code may be created.',
-            derived: ['subagent-plan.json', 'subagent-events.jsonl', 'worker inboxes'],
-            rule: 'Do not implement behavior outside the sealed route contract; block with evidence if the requested path cannot be honored.'
-        },
-        {
-            id: 'triwiki_context',
-            source: '.sneakoscope/wiki/context-pack.json',
-            authority: 'TriWiki is the bounded mission context SSOT and must be refreshed or packed, then validated before risky handoffs and final claims.',
-            derived: ['subagent-parent-summary.json', 'subagent-evidence.json', 'reflection.md'],
-            rule: 'Use the latest coordinate+voxel overlay pack; coordinate-only legacy packs are invalid for pipeline decisions.'
-        },
-        {
-            id: 'runtime_source',
-            source: 'src/**/*.ts',
-            authority: 'TypeScript source is the runtime SSOT.',
-            derived: ['dist/**', 'dist/bin/sks.js'],
-            rule: 'Edit source, rebuild derived output, and rely on runtime:ts-source-of-truth plus runtime:dist-parity.'
-        },
-        {
-            id: 'generated_outputs',
-            source: 'source generators, build scripts, and schema definitions',
-            authority: 'Generated files are derived from their generator or schema owner.',
-            derived: ['release-gates.v2.json', 'infra-harness-gates.json', '.sneakoscope/reports/**', 'dist/build-manifest.json'],
-            rule: 'Regenerate derived artifacts instead of hand-editing them as independent truth.'
-        },
-        {
-            id: 'stack_current_docs',
-            source: '.sneakoscope/memory/q2_facts/stack-current-docs.md',
-            authority: 'Current vendor or Context7 docs override model-memory defaults when stack versions or APIs change.',
-            derived: ['implementation notes', 'route evidence'],
-            rule: 'Fetch and record current docs before relying on external package, SDK, API, MCP, or generated-doc behavior that may have changed.'
-        },
-        {
-            id: 'release_gate_manifest',
-            source: 'src/core/release/gate-manifest.ts and src/scripts/release-parallel-check.ts',
-            authority: 'Release gate selection and publish-required status live in the manifest plus the release DAG.',
-            derived: ['.sneakoscope/reports/release-gate-plan.json', '.sneakoscope/reports/gate-policy-audit.json'],
-            rule: 'Publish-blocking guard gates must appear in the DAG, manifest, and package scripts.'
-        }
-    ];
+    return inventoryAsSsotGuardSources().map((row) => ({ ...row }));
 }
 export function validateSsotGuardArtifact(value) {
     const issues = [];

package/dist/core/subagents/agent-catalog.js

@@ -100,7 +100,8 @@ export function officialSubagentFanoutPolicy(input = {}) {
         ...(input.suggestedRoles === undefined ? {} : { suggestedRoles: input.suggestedRoles }),
         ...(input.independentSliceCount === undefined ? {} : { independentSliceCount: input.independentSliceCount }),
         ...(input.maxThreads === undefined ? {} : { maxThreads: input.maxThreads }),
-        ...(input.hardware === undefined ? {} : { hardware: input.hardware })
+        ...(input.hardware === undefined ? {} : { hardware: input.hardware }),
+        ...(input.requiresWrite === undefined ? {} : { requiresWrite: input.requiresWrite })
     });
     const requested = explicit ? explicitRequested : automatic.count;
     const automaticReviewerCeiling = automatic.criticalMultiDomain
@@ -141,7 +142,8 @@ function automaticSubagentFanout(input) {
     const critical = CRITICAL_RISK_RE.test(text);
     const largeScale = LARGE_SCALE_WORK_RE.test(text);
     const criticalMultiDomain = highRisk && critical && riskDomains.length >= 3;
-    const reviewerOnly = isReviewerOnlyFanout(input.suggestedRoles || []);
+    const reviewerOnly = isReviewerOnlyFanout(input.suggestedRoles || [])
+        && input.requiresWrite !== true;
     const massLane = decideSubagentModel({ description: text }).policy;
     const massParallel = MASS_PARALLEL_WORK_RE.test(text)
         && !NON_CHEAP_MASS_ACTION_RE.test(text)

package/dist/core/subagents/official-subagent-config.js

@@ -20,17 +20,23 @@ export const LEGACY_SKS_MAX_THREAD_VALUES = Object.freeze([4, 5, 6, 12]);
 export const AGENTS_MAX_CONCURRENT_THREADS_KEY = 'max_concurrent_threads_per_session';
 export const LEGACY_AGENTS_MAX_THREADS_KEY = 'max_threads';
 export const LEGACY_AGENTS_JOB_MAX_RUNTIME_KEY = 'job_max_runtime_seconds';
+export const SKS_MANAGED_CODEX_CONFIG_MARKER = '# SKS-MANAGED-CODEX-CONFIG';
 export function mergeOfficialSubagentConfig(text = '', opts = {}) {
+    return mergeOfficialSubagentConfigResult(text, opts).text;
+}
+export function mergeOfficialSubagentConfigResult(text = '', opts = {}) {
     const source = String(text || '');
-    if (!inspectToml(source).ok)
-        return source;
+    if (!inspectToml(source).ok) {
+        return { text: source, blockers: ['project_official_subagent_config_toml_parse_failed'] };
+    }
     const inherited = parsedToml(opts.inheritedText || '');
     const inheritedAgents = objectValue(inherited?.agents);
     const inheritedFeatures = objectValue(inherited?.features);
     let next = source.trimEnd();
     if (!next.trim())
-        next = '# SKS-MANAGED-CODEX-CONFIG';
+        next = SKS_MANAGED_CODEX_CONFIG_MARKER;
     if (opts.sksOwned === true) {
+        next = stampManagedConfigMarker(next);
         next = removeExactLegacyManagedAgentBlocks(next);
         next = stripLegacyUnsupportedAgentKeys(next);
     }
@@ -48,10 +54,12 @@ export function mergeOfficialSubagentConfig(text = '', opts = {}) {
     next = mergeOfficialMultiAgentV2FeatureConfig(next, {
         sksOwned: opts.sksOwned === true,
         inheritedFeatures,
-        maxThreads: readAgentsMaxThreads(next) || targetMaxThreads
+        maxThreads: Math.min(readAgentsMaxThreads(next) || targetMaxThreads, HARD_NARUTO_MAX_THREADS)
     });
     const merged = ensureTrailingNewline(next);
-    return inspectToml(merged).ok ? merged : source;
+    if (inspectToml(merged).ok)
+        return { text: merged, blockers: [] };
+    return { text: source, blockers: ['official_subagent_config_merge_produced_invalid_toml'] };
 }
 export function mergeOfficialMultiAgentV2FeatureConfig(text = '', opts = {}) {
     const source = String(text || '');
@@ -61,18 +69,21 @@ export function mergeOfficialMultiAgentV2FeatureConfig(text = '', opts = {}) {
     const inheritedMaV2 = featureTomlObject(inheritedFeatures.multi_agent_v2);
     let next = source.trimEnd();
     if (!next.trim())
-        next = '# SKS-MANAGED-CODEX-CONFIG';
-    if (hasTomlTableKey(next, 'features', 'multi_agent_v2')) {
+        next = SKS_MANAGED_CODEX_CONFIG_MARKER;
+    if (hasUnmanageableMultiAgentV2Declaration(next))
+        return ensureTrailingNewline(next);
+    const booleanForm = readTomlTableBoolean(next, 'features', 'multi_agent_v2');
+    if (booleanForm !== null) {
         next = removeTomlTableKey(next, 'features', 'multi_agent_v2');
     }
     const maxThreads = boundedManagedMaxThreads(opts.maxThreads, DEFAULT_OFFICIAL_SUBAGENT_MAX_THREADS);
     const targetTotal = Math.max(1, maxThreads + 1);
     if (!hasTomlTable(next, 'features.multi_agent_v2')) {
-        if (inheritedMaV2)
+        if (inheritedMaV2 && booleanForm === null)
             return ensureTrailingNewline(next);
         next = upsertTomlTable(next, 'features.multi_agent_v2', [
             '[features.multi_agent_v2]',
-            'enabled = true',
+            `enabled = ${booleanForm === null ? true : booleanForm}`,
             `max_concurrent_threads_per_session = ${targetTotal}`,
             'expose_spawn_agent_model_overrides = true'
         ].join('\n'));
@@ -81,7 +92,7 @@ export function mergeOfficialMultiAgentV2FeatureConfig(text = '', opts = {}) {
     if (opts.sksOwned === true) {
         next = upsertTomlTableKey(next, 'features.multi_agent_v2', 'enabled = true');
         const currentTotal = readTomlTableInteger(next, 'features.multi_agent_v2', 'max_concurrent_threads_per_session');
-        if (currentTotal === DEFAULT_NARUTO_LEGACY_TOTAL_THREADS || currentTotal === null) {
+        if (currentTotal === null || LEGACY_MANAGED_V2_TOTAL_THREADS.includes(currentTotal)) {
             next = upsertTomlTableKey(next, 'features.multi_agent_v2', `max_concurrent_threads_per_session = ${targetTotal}`);
         }
         if (!hasTomlTableKey(next, 'features.multi_agent_v2', 'expose_spawn_agent_model_overrides')) {
@@ -105,6 +116,10 @@ export function mergeOfficialMultiAgentV2FeatureConfig(text = '', opts = {}) {
     return ensureTrailingNewline(next);
 }
 const DEFAULT_NARUTO_LEGACY_TOTAL_THREADS = 13;
+const LEGACY_MANAGED_V2_TOTAL_THREADS = Object.freeze([
+    ...LEGACY_SKS_MAX_THREAD_VALUES.map((value) => value + 1),
+    DEFAULT_NARUTO_LEGACY_TOTAL_THREADS
+]);
 export async function readOfficialSubagentConfig(root, opts = {}) {
     const projectConfigPath = path.resolve(opts.projectConfigPath || path.join(root, '.codex', 'config.toml'));
     const home = opts.home || process.env.HOME || os.homedir();
@@ -173,6 +188,9 @@ export function officialSubagentConfigWarnings(text = '', inheritedText = '') {
             ? [`official_subagent_max_depth_coerced_to_one:${maxDepth.value}:${maxDepth.source}`]
             : []),
         ...capacityNormalizationWarnings(maxThreads, multiAgentV2),
+        ...(hasUnmanageableMultiAgentV2Declaration(text)
+            ? ['project_multi_agent_v2_declaration_form_unmanaged']
+            : []),
         ...project.legacyWarnings,
         ...inherited.legacyWarnings
     ];
@@ -315,6 +333,8 @@ export function officialSubagentConfigOwnershipProof(input = {}) {
     }
     if (hasExactManagedConfigMarker(text))
         reasons.push('managed_marker_or_hash');
+    if (hasManagedAgentsConfigFingerprint(text))
+        reasons.push('managed_agents_config_fingerprint');
     if (migrationReceiptProvesManagedMaxThreads(input.migrationReceipt)) {
         reasons.push('migration_receipt:agents.max_concurrent_threads_per_session');
     }
@@ -482,7 +502,38 @@ function featureTomlObject(value) {
     return Object.keys(row).length ? row : null;
 }
 function hasExactManagedConfigMarker(text) {
-    return /^(?:#\s*SKS-MANAGED-CODEX-CONFIG\b|#\s*SKS managed Codex config\b|#\s*sks_managed_(?:body_)?sha256\s*=\s*["'][a-f0-9]{64}["'])/mi.test(text);
+    return /^\s*(?:#\s*SKS-MANAGED-CODEX-CONFIG\b|#\s*SKS managed Codex config\b|#\s*sks_managed_(?:body_)?sha256\s*=\s*["'][a-f0-9]{64}["'])/mi.test(text);
+}
+export function stampSksManagedCodexConfigMarker(text) {
+    return stampManagedConfigMarker(text);
+}
+function stampManagedConfigMarker(text) {
+    const source = String(text || '');
+    if (hasExactManagedConfigMarker(source))
+        return source;
+    const body = source.replace(/^\n+/, '');
+    return body ? `${SKS_MANAGED_CODEX_CONFIG_MARKER}\n${body}` : SKS_MANAGED_CODEX_CONFIG_MARKER;
+}
+const MANAGED_AGENTS_FINGERPRINT_KEYS = Object.freeze([
+    'enabled',
+    'max_depth',
+    'interrupt_message',
+    'default_subagent_model',
+    'default_subagent_reasoning_effort'
+]);
+export function hasManagedAgentsConfigFingerprint(text) {
+    const parsed = parsedToml(text);
+    if (!parsed)
+        return false;
+    const agents = objectValue(parsed.agents);
+    if (!MANAGED_AGENTS_FINGERPRINT_KEYS.every((key) => hasOwn(agents, key)))
+        return false;
+    if (readAgentsMaxThreadsFromRecord(agents) === undefined)
+        return false;
+    if (agents.max_depth !== DEFAULT_OFFICIAL_SUBAGENT_MAX_DEPTH)
+        return false;
+    const multiAgentV2 = featureTomlObject(objectValue(parsed.features).multi_agent_v2);
+    return multiAgentV2 !== null && hasOwn(multiAgentV2, 'expose_spawn_agent_model_overrides');
 }
 function migrationReceiptProvesManagedMaxThreads(value) {
     const root = objectValue(value);
@@ -676,11 +727,37 @@ function upsertDefaultUnlessInherited(text, inheritedAgents, key, line) {
 }
 function readTomlTableInteger(text, table, key) {
     const line = tomlTableKeyLine(text, table, key);
-    const match = line?.match(/^\s*[^=]+\s*=\s*([0-9]+)\s*(?:#.*)?$/);
-    if (!match?.[1])
+    const raw = line?.match(/^\s*[^=]+\s*=\s*([^#]+?)\s*(?:#.*)?$/)?.[1];
+    return parseTomlInteger(raw);
+}
+function parseTomlInteger(raw) {
+    const value = String(raw ?? '').trim().replace(/_/g, '');
+    const match = value.match(/^([+-]?)(?:0x([0-9a-fA-F]+)|0o([0-7]+)|0b([01]+)|([0-9]+))$/);
+    if (!match)
         return null;
-    const value = Number(match[1]);
-    return Number.isSafeInteger(value) ? value : null;
+    const magnitude = match[2] !== undefined
+        ? Number.parseInt(match[2], 16)
+        : match[3] !== undefined
+            ? Number.parseInt(match[3], 8)
+            : match[4] !== undefined
+                ? Number.parseInt(match[4], 2)
+                : Number(match[5]);
+    const parsed = (match[1] === '-' ? -1 : 1) * magnitude;
+    return Number.isSafeInteger(parsed) ? parsed : null;
+}
+function hasUnmanageableMultiAgentV2Declaration(text) {
+    const parsed = parsedToml(text);
+    if (!parsed)
+        return false;
+    if (!hasOwn(objectValue(parsed.features), 'multi_agent_v2'))
+        return false;
+    return !hasTomlTable(text, 'features.multi_agent_v2')
+        && readTomlTableBoolean(text, 'features', 'multi_agent_v2') === null;
+}
+function readTomlTableBoolean(text, table, key) {
+    const line = tomlTableKeyLine(text, table, key);
+    const match = line?.match(/^\s*[^=]+\s*=\s*(true|false)\s*(?:#.*)?$/);
+    return match?.[1] ? match[1] === 'true' : null;
 }
 function hasTomlTableKey(text, table, key) {
     return tomlTableKeyLine(text, table, key) !== null;

package/dist/core/subagents/official-subagent-preparation.js

@@ -107,6 +107,7 @@ async function prepareOfficialSubagentMissionLocked(input) {
         taskProfile,
         suggestedRoles: suggestedAgents,
         goal,
+        requiresWrite: input.readOnly !== true,
         maxThreads: input.maxThreads ?? officialConfig.maxThreads,
         ...(input.hardware ? { hardware: input.hardware } : {}),
         ...(slices.length > 0 ? { independentSliceCount: slices.length } : {})