sneakoscope 6.0.3 → 6.1.2

package/dist/core/feature-registry.js

@@ -2,6 +2,7 @@ import fs from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
+import { COMMAND_MANIFEST_LITE } from '../cli/command-manifest-lite.js';
 import { COMMANDS } from '../cli/command-registry.js';
 import { COMMAND_CATALOG, DOLLAR_COMMAND_ALIASES, DOLLAR_COMMANDS, ROUTES } from './routes.js';
 import { FEATURE_QUALITY_LEVELS, fixtureForFeature, fixtureSummary, validateFeatureFixtures } from './feature-fixtures.js';
@@ -27,12 +28,12 @@ const FEATURE_ACCEPTANCE_DEFAULTS = Object.freeze([
     'release-mapped'
 ]);
 export async function buildFeatureRegistry({ root = packageRoot(), generatedAt = nowIso() } = {}) {
-    const handlerKeys = await parseMainHandlerKeys(root);
+    const handlerKeys = actualCommandHandlerKeys();
     const skillNames = await listProjectSkillNames(root);
     const docRouteMentions = await collectDocRouteMentions(root);
     const handlerToFeature = mapHandlerKeysToFeatureIds(handlerKeys);
     const features = [];
-    for (const command of COMMAND_CATALOG) {
+    for (const command of featureCommandCatalog()) {
         const handlerAliases = Object.entries(handlerToFeature)
             .filter(([, featureId]) => featureId === `cli-${command.name}`)
             .map(([handler]) => handler)
@@ -64,7 +65,7 @@ export async function buildFeatureRegistry({ root = packageRoot(), generatedAt =
         generated_at: generatedAt,
         inventory_sources: {
             commands_json: 'sks commands --json',
-            main_handlers: 'src/cli/main.js',
+            main_handlers: 'src/cli/command-registry.ts COMMANDS',
             dollar_routes: 'src/core/routes.js',
             docs: ['README.md', '.codex/SNEAKOSCOPE.md', 'AGENTS.md', '.agents/skills/.sks-generated.json'],
             skills: '.agents/skills'
@@ -73,7 +74,7 @@ export async function buildFeatureRegistry({ root = packageRoot(), generatedAt =
         fixture_summary: fixtureSummary(features),
         feature_quality_summary: featureQualitySummary(features),
         source_inventory: {
-            cli_command_names: COMMAND_CATALOG.map((entry) => entry.name),
+            cli_command_names: COMMAND_MANIFEST_LITE.map((entry) => entry.name),
             handler_keys: handlerKeys,
             dollar_commands: DOLLAR_COMMANDS.map((entry) => entry.command),
             app_skill_aliases: DOLLAR_COMMAND_ALIASES.map((entry) => entry.app_skill),
@@ -198,7 +199,8 @@ export function buildAllFeaturesSelftest(registry, opts = {}) {
         checkRow('agent_lease_policy_present', registry.features.some((feature) => feature.id === 'route-native-agent-intake' && /bounded workspace-write/i.test(JSON.stringify(feature.contract || {})) && /lease/i.test(JSON.stringify(feature.contract || {}))), ['route-native-agent-intake']),
         checkRow('fixture_pass_threshold', (fixturesSummary.counts.pass || 0) >= 90, [`pass=${fixturesSummary.counts.pass || 0}`]),
         checkRow('fixture_not_required_ceiling', (fixturesSummary.counts.not_required || 0) <= 16, [`not_required=${fixturesSummary.counts.not_required || 0}`]),
-        checkRow('fixture_mock_blocked_zero', (fixturesSummary.counts.blocked || 0) === 0, [`blocked=${fixturesSummary.counts.blocked || 0}`]),
+        checkRow('fixture_blocked_contracts_honest', (registry.features || []).filter((feature) => feature.fixture?.status === 'blocked')
+            .every((feature) => String(feature.fixture?.reason || '').trim().length > 0 && feature.fixture?.fallback_removed === true), (registry.features || []).filter((feature) => feature.fixture?.status === 'blocked' && (!String(feature.fixture?.reason || '').trim() || feature.fixture?.fallback_removed !== true)).map((feature) => feature.id)),
         ...(executable ? [checkRow('executable_fixture_contracts', executable.ok, executable.failures)] : [])
     ];
     const ok = checks.every((check) => check.ok);
@@ -219,8 +221,11 @@ export function buildAllFeaturesSelftest(registry, opts = {}) {
 }
 export async function writeAllFeatureCompletionReport({ root = packageRoot(), outDir = path.join(root, '.sneakoscope', 'reports') } = {}) {
     const registry = await buildFeatureRegistry({ root });
-    const packageJson = await readJson(path.join(root, 'package.json'), {});
-    const report = buildAllFeatureCompletionReport(registry, { root, packageJson });
+    const [packageJson, releaseManifest] = await Promise.all([
+        readJson(path.join(root, 'package.json'), {}),
+        readJson(path.join(root, 'release-gates.v2.json'), { gates: [] })
+    ]);
+    const report = buildAllFeatureCompletionReport(registry, { root, packageJson, releaseManifest });
     const jsonPath = path.join(outDir, `all-feature-completion-${PACKAGE_VERSION}.json`);
     const markdownPath = path.join(outDir, `all-feature-completion-${PACKAGE_VERSION}.md`);
     await writeJsonAtomic(jsonPath, report);
@@ -229,15 +234,16 @@ export async function writeAllFeatureCompletionReport({ root = packageRoot(), ou
 }
 export function buildAllFeatureCompletionReport(registry, opts = {}) {
     const packageJson = opts.packageJson || {};
+    const releaseGateIds = new Set((Array.isArray(opts.releaseManifest?.gates) ? opts.releaseManifest.gates : []).map((gate) => String(gate.id || '')));
     const features = [
         ...(registry.features || []).map((feature) => featureCompletionRow(feature)),
-        ...derivedReleaseFeatureRows(opts.root || packageRoot(), packageJson)
+        ...derivedReleaseFeatureRows(opts.root || packageRoot(), packageJson, releaseGateIds)
     ];
-    const missingScripts = SECTION_29_PACKAGE_SCRIPTS.filter((script) => !packageJson.scripts?.[script]);
+    const missingGates = FLAGSHIP_RELEASE_GATES.filter((gate) => !releaseGateIds.has(gate));
     const runtimeStatic = runtimeRoutesNotStaticContract(registry.features || []);
     const blockers = [
         ...(registry.coverage?.blockers || []),
-        ...missingScripts.map((script) => `missing_script:${script}`),
+        ...missingGates.map((gate) => `missing_release_gate:${gate}`),
         ...runtimeStatic.blockers,
         ...(packageJson.version === PACKAGE_VERSION ? [] : [`package_version:${packageJson.version || 'missing'}`]),
         ...features.flatMap((feature) => feature.blockers.map((blocker) => `${feature.id}:${blocker}`))
@@ -252,12 +258,12 @@ export function buildAllFeatureCompletionReport(registry, opts = {}) {
             features: features.length,
             registry_features: registry.features?.length || 0,
             derived_release_features: features.length - (registry.features?.length || 0),
-            package_scripts_required: SECTION_29_PACKAGE_SCRIPTS.length,
-            package_scripts_missing: missingScripts.length
+            release_gates_required: FLAGSHIP_RELEASE_GATES.length,
+            release_gates_missing: missingGates.length
         },
         blockers,
-        required_scripts: SECTION_29_PACKAGE_SCRIPTS,
-        missing_scripts: missingScripts,
+        required_gates: FLAGSHIP_RELEASE_GATES,
+        missing_gates: missingGates,
         release_gates: {
             version_metadata: packageJson.version === PACKAGE_VERSION ? 'present' : 'blocked',
             feature_registry: registry.coverage?.ok ? 'present' : 'blocked',
@@ -278,7 +284,7 @@ export function renderAllFeatureCompletionMarkdown(report) {
         '',
         `- Status: ${report.status}`,
         `- Features: ${report.counts?.features || 0}`,
-        `- Missing scripts: ${(report.missing_scripts || []).length ? report.missing_scripts.join(', ') : 'none'}`,
+        `- Missing release gates: ${(report.missing_gates || []).length ? report.missing_gates.join(', ') : 'none'}`,
         `- Blockers: ${(report.blockers || []).length ? report.blockers.join(', ') : 'none'}`,
         '',
         '| Feature | Fixture | Evidence | Proof | Trust | Wrongness | Blackbox | Status |',
@@ -288,38 +294,27 @@ export function renderAllFeatureCompletionMarkdown(report) {
         const c = feature.coverage || {};
         lines.push(`| \`${feature.id}\` | ${c.fixture?.status || 'missing'} | ${c.evidence_router?.status || 'missing'} | ${c.completion_proof?.status || 'missing'} | ${c.trust_report?.status || 'missing'} | ${c.wrongness?.status || 'missing'} | ${c.blackbox?.status || 'missing'} | ${feature.status} |`);
     }
-    lines.push('', '## Required Release Scripts', '');
-    for (const script of report.required_scripts || [])
-        lines.push(`- ${script}: ${(report.missing_scripts || []).includes(script) ? 'missing' : 'present'}`);
+    lines.push('', '## Required Release Gates', '');
+    for (const gate of report.required_gates || [])
+        lines.push(`- ${gate}: ${(report.missing_gates || []).includes(gate) ? 'missing' : 'present'}`);
     return `${lines.join('\n')}\n`;
 }
-const SECTION_29_PACKAGE_SCRIPTS = Object.freeze([
+const FLAGSHIP_RELEASE_GATES = Object.freeze([
     'ux-review:run-wires-imagegen',
     'ux-review:extract-wires-real-extractor',
     'ux-review:patch-diff-recheck',
+    'ux-review:imagegen-blackbox',
     'ppt:real-export-adapter',
     'ppt:real-imagegen-wiring',
     'ppt:reexport-rereview',
+    'ppt:full-e2e-blackbox',
     'dfix:patch-handoff',
     'dfix:verification-recommendation',
     'all-features:deep-completion',
     'evidence:flagship-coverage',
-    'ux-review:generate-callouts-fixture',
-    'ux-review:extract-real-callouts-fixture',
-    'ux-review:patch-handoff-fixture',
-    'ux-review:recapture-recheck-fixture',
-    'ux-review:no-fake-callouts',
-    'ppt:imagegen-review-fixture',
-    'ppt:slide-export-fixture',
-    'ppt:no-text-fallback',
-    'ppt:no-mock-as-real',
-    'ppt:issue-extraction-fixture',
-    'ppt:image-voxel-relations',
-    'ppt:proof-trust-fixture',
     'dfix:fixture',
     'dfix:verification',
-    'all-features:completion',
-    'json-schema:recursive-check'
+    'schema:check'
 ]);
 function featureCompletionRow(feature) {
     const coverage = {
@@ -354,14 +349,14 @@ function featureCompletionRow(feature) {
         blockers
     };
 }
-function derivedReleaseFeatureRows(root, packageJson) {
+function derivedReleaseFeatureRows(root, packageJson, releaseGateIds) {
     const derived = [
         { id: 'release-version-1-14', title: `Release version metadata ${PACKAGE_VERSION}`, artifact: 'package.json', ok: packageJson.version === PACKAGE_VERSION },
         { id: 'all-feature-completion', title: 'All feature completion matrix', artifact: `.sneakoscope/reports/all-feature-completion-${PACKAGE_VERSION}.json`, ok: true },
         { id: 'ppt-imagegen-review', title: 'PPT imagegen review route', artifact: 'src/core/ppt-review/index.ts', ok: existsSync(path.join(root, 'src', 'core', 'ppt-review', 'index.ts')) },
         { id: 'dfix-loop', title: 'DFix diagnose/plan/patch/verify loop', artifact: 'src/core/commands/dfix-command.ts', ok: existsSync(path.join(root, 'src', 'core', 'commands', 'dfix-command.ts')) },
         { id: 'recursive-json-schema-validator', title: 'Recursive JSON schema validator', artifact: 'src/core/json-schema-validator.ts', ok: existsSync(path.join(root, 'src', 'core', 'json-schema-validator.ts')) },
-        { id: 'release-section-29-scripts', title: 'Section 29 release scripts', artifact: 'package.json', ok: SECTION_29_PACKAGE_SCRIPTS.every((script) => packageJson.scripts?.[script]) },
+        { id: 'release-flagship-gates', title: 'Current flagship release gates', artifact: 'release-gates.v2.json', ok: FLAGSHIP_RELEASE_GATES.every((gate) => releaseGateIds.has(gate)) },
         { id: 'release-blackbox-matrix', title: 'Release blackbox feature matrix', artifact: 'test/blackbox', ok: true }
     ];
     return derived.map((feature) => derivedFeatureCompletionRow(feature));
@@ -509,7 +504,6 @@ const SAFE_EXECUTABLE_FIXTURE_ARGS = Object.freeze({
     'cli-proof': ['proof', 'smoke', '--json'],
     'cli-trust': { setup: [['run', 'fixture', '--mock', '--json']], command: ['trust', 'report', 'latest', '--json'] },
     'cli-wrongness': ['wrongness', 'add', '--kind', 'missing_evidence', '--claim', 'fixture wrongness', '--json'],
-    'cli-db': ['db', 'policy'],
     'cli-wiki': ['wiki', 'image-ingest', 'test/fixtures/images/one-by-one.png', '--json'],
     'cli-codex': ['codex', 'compatibility', '--json'],
     'cli-codex-lb': ['codex-lb', 'metrics', '--json'],
@@ -530,8 +524,10 @@ const SAFE_EXECUTABLE_FIXTURE_ARGS = Object.freeze({
     'cli-daemon': ['daemon', 'status', '--json'],
     'cli-dfix': ['dfix', 'fixture', '--json'],
     'cli-all-features': ['all-features', 'complete', '--json'],
-    'route-team': ['team', 'fixture', '--mock', '--clones', '4', '--backend', 'fake', '--work-items', '4', '--json'],
-    'route-naruto': ['naruto', 'run', 'fixture', '--clones', '4', '--backend', 'fake', '--work-items', '4', '--json'],
+    'cli-naruto': ['naruto', 'run', 'fixture', '--agents', '4', '--max-threads', '4', '--json'],
+    'cli-team': ['team', 'fixture', '--agents', '4', '--max-threads', '4', '--json'],
+    'route-team': ['team', 'fixture', '--agents', '4', '--max-threads', '4', '--json'],
+    'route-naruto': ['naruto', 'run', 'fixture', '--agents', '4', '--max-threads', '4', '--json'],
     'route-qa-loop': { setup: [['qa-loop', 'prepare', 'fixture API QA', '--json']], command: ['qa-loop', 'run', 'latest', '--mock', '--json'] },
     'route-research': { setup: [['research', 'prepare', 'fixture research topic', '--json']], command: ['research', 'run', 'latest', '--mock', '--json'] },
     'route-ppt': ['ppt', 'fixture', '--mock', '--json'],
@@ -540,7 +536,6 @@ const SAFE_EXECUTABLE_FIXTURE_ARGS = Object.freeze({
     'route-dfix': ['dfix', 'fixture', '--json'],
     'route-seo-geo-optimizer': ['seo-geo-optimizer', 'fixture', '--mode', 'geo', '--json'],
     'route-fast-mode': ['fast-mode', 'status', '--json'],
-    'route-db': ['db', 'check', '--sql', 'SELECT 1', '--json'],
     'route-wiki': ['wiki', 'image-ingest', 'test/fixtures/images/one-by-one.png', '--json'],
     'route-gx': ['gx', 'validate', 'fixture', '--mock', '--json']
 });
@@ -587,15 +582,14 @@ export function renderFeatureInventoryMarkdown(registry) {
         lines.push(`- doc_route_mentions_without_route: ${coverage.doc_route_mentions_without_route.join(', ')}`);
     }
     lines.push('', '## Prompt Checklist Coverage', '');
-    lines.push('- [x] Collected `sks commands --json` command surface via `COMMAND_CATALOG`.');
-    lines.push('- [x] Parsed `src/cli/main.js` handler keys, including hidden handlers and aliases.');
+    lines.push('- [x] Collected the complete `sks commands --json` command surface via `COMMAND_MANIFEST_LITE`.');
+    lines.push('- [x] Collected the actual `src/cli/command-registry.ts` `COMMANDS` handler keys, including hidden handlers.');
     lines.push('- [x] Collected dollar routes and app skill aliases from `src/core/routes.js`.');
     lines.push('- [x] Scanned README, Codex quick reference, AGENTS, and generated skill manifest for dollar-route mentions.');
     lines.push('- [x] Mapped project skills from `.agents/skills` into the registry.');
     lines.push('- [x] Exposed the registry through `sks features list --json`.');
     lines.push('- [x] Added a release coverage check through `sks features check --json`.');
     lines.push('- [x] Documented fixture status for every registry feature.');
-    lines.push('');
     return `${lines.join('\n')}\n`;
 }
 function commandFeature(command, handlerAliases = []) {
@@ -608,7 +602,7 @@ function commandFeature(command, handlerAliases = []) {
         commands: [command.usage],
         aliases,
         category,
-        maturity,
+        maturity: command.maturity || maturity,
         intent: command.description,
         completion_proof_integration: proofContract(category),
         voxel_triwiki_integration: voxelContract(category),
@@ -669,10 +663,10 @@ function nativeAgentIntakeFeature() {
     return baseFeature({
         id: 'route-native-agent-intake',
         commands: ['sks agent run "task" --route "$Team" --agents 5 --concurrency 4 --mock --json'],
-        aliases: ['sks team "task" [executor:5 reviewer:6 user:1]'],
+        aliases: [],
         category: 'proof-route',
         maturity: 'stable',
-        intent: 'Default bounded workspace-write native multi-session agent intake before serious route implementation.',
+        intent: 'Separate bounded workspace-write agent-runtime intake for explicit sks agent missions; it is not the default Naruto workflow.',
         voxel_triwiki_integration: 'native agent findings are TriWiki-ready and can require image voxel evidence for visual routes',
         completion_proof_integration: 'Completion Proof evidence.agents records agent_count, route, leases, no-overlap proof, cleanup, proof graph, and dynamic effort policy',
         known_gaps: ['real speedup claims require runtime timing/eval evidence; mock/static timing is not enough'],
@@ -836,7 +830,7 @@ function baseFeature(feature) {
     };
 }
 function mapHandlerKeysToFeatureIds(handlerKeys = []) {
-    const catalogNames = new Set(COMMAND_CATALOG.map((entry) => entry.name));
+    const catalogNames = new Set(COMMAND_MANIFEST_LITE.map((entry) => entry.name));
     const out = {};
     for (const handler of handlerKeys) {
         const commandName = HANDLER_ALIAS_TO_COMMAND[handler] || handler;
@@ -844,19 +838,19 @@ function mapHandlerKeysToFeatureIds(handlerKeys = []) {
     }
     return out;
 }
-async function parseMainHandlerKeys(root) {
-    const registryText = await readText(path.join(root, 'src', 'cli', 'command-registry.js'), '');
-    const registryMatch = registryText.match(/export const COMMANDS = \{([\s\S]*?)\n\};/);
-    if (registryMatch)
-        return parseObjectKeys(registryMatch[1]);
-    return [];
+function featureCommandCatalog() {
+    const detailed = new Map(COMMAND_CATALOG.map((entry) => [entry.name, entry]));
+    return COMMAND_MANIFEST_LITE.map((entry) => {
+        const detail = detailed.get(entry.name);
+        return {
+            ...entry,
+            usage: detail?.usage || `sks ${entry.name}`,
+            description: detail?.description || entry.summary
+        };
+    });
 }
-function parseObjectKeys(text = '') {
-    const keys = [];
-    for (const keyMatch of text.matchAll(/^\s{2}(?:'([^']+)'|"([^"]+)"|([A-Za-z_$][\w$-]*))\s*:/gm)) {
-        keys.push(keyMatch[1] || keyMatch[2] || keyMatch[3]);
-    }
-    return [...new Set(keys)].sort();
+function actualCommandHandlerKeys() {
+    return Object.keys(COMMANDS).sort();
 }
 async function listProjectSkillNames(root) {
     const dir = path.join(root, '.agents', 'skills');
@@ -911,6 +905,7 @@ function isExternalPromptCommandMention(mention) {
     const normalized = String(mention || '').toUpperCase();
     return [
         '$CODEX_HOME',
+        '$HOME',
         '$CODEX_LB_API_KEY',
         '$SKS_CODEX_APP_IMAGEGEN_OUTPUT',
         '$SKS_CODEX_APP_IMAGEGEN_OUTPUT_ID',

package/dist/core/fsx.js

@@ -5,10 +5,13 @@ import os from 'node:os';
 import crypto from 'node:crypto';
 import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
+import { gunzip as gunzipCallback } from 'node:zlib';
+import { promisify } from 'node:util';
 import { PACKAGE_VERSION } from './version.js';
 export { PACKAGE_VERSION };
 export const DEFAULT_PROCESS_TAIL_BYTES = 256 * 1024;
 export const DEFAULT_PROCESS_TIMEOUT_MS = 30 * 60 * 1000;
+const gunzipAsync = promisify(gunzipCallback);
 export function nowIso() {
     return new Date().toISOString();
 }
@@ -70,16 +73,27 @@ export async function readText(p, fallback) {
         throw err;
     }
 }
-export async function writeTextAtomic(p, text) {
+export async function writeTextAtomic(p, text, opts = {}) {
     await ensureDir(path.dirname(p));
     try {
-        if ((await fsp.readFile(p, 'utf8')) === text)
-            return;
+        if ((await fsp.readFile(p, 'utf8')) === text) {
+            if (opts.mode === undefined)
+                return;
+            const existing = await fsp.lstat(p).catch(() => null);
+            if (existing?.isFile() && !existing.isSymbolicLink()) {
+                await fsp.chmod(p, opts.mode & 0o777);
+                return;
+            }
+            // Replace symlink or non-regular targets atomically below. Never chmod
+            // through a link merely because its current contents happen to match.
+        }
     }
     catch { }
     const tmp = `${p}.${process.pid}.${randomId(6)}.tmp`;
+    const existingMode = await fsp.lstat(p).then((stat) => stat.isFile() && !stat.isSymbolicLink() ? stat.mode & 0o777 : null).catch(() => null);
+    const requestedMode = opts.mode === undefined ? existingMode : opts.mode & 0o777;
     try {
-        const handle = await fsp.open(tmp, 'w');
+        const handle = await fsp.open(tmp, 'w', requestedMode ?? 0o666);
         try {
             await handle.writeFile(text, 'utf8');
             await handle.sync().catch(() => { });
@@ -87,7 +101,11 @@ export async function writeTextAtomic(p, text) {
         finally {
             await handle.close().catch(() => { });
         }
+        if (requestedMode !== null)
+            await fsp.chmod(tmp, requestedMode);
         await fsp.rename(tmp, p);
+        if (requestedMode !== null)
+            await fsp.chmod(p, requestedMode);
     }
     catch (err) {
         await fsp.rm(tmp, { force: true }).catch(() => { });
@@ -95,7 +113,9 @@ export async function writeTextAtomic(p, text) {
             throw err;
         try {
             await ensureDir(path.dirname(p));
-            await fsp.writeFile(p, text, 'utf8');
+            await fsp.writeFile(p, text, { encoding: 'utf8', ...(requestedMode === null ? {} : { mode: requestedMode }) });
+            if (requestedMode !== null)
+                await fsp.chmod(p, requestedMode);
         }
         catch (fallbackErr) {
             const error = fallbackErr instanceof Error ? fallbackErr : new Error(String(fallbackErr));
@@ -129,7 +149,11 @@ function errorMessage(err) {
 }
 export async function readJson(p, fallback) {
     try {
-        return JSON.parse(await fsp.readFile(p, 'utf8'));
+        const parsed = JSON.parse(await fsp.readFile(p, 'utf8'));
+        if (parsed?.retention_archived === true) {
+            return await hydrateRetentionArchivedJson(p, parsed);
+        }
+        return parsed;
     }
     catch (err) {
         if (fallback !== undefined)
@@ -137,6 +161,30 @@ export async function readJson(p, fallback) {
         throw err;
     }
 }
+async function hydrateRetentionArchivedJson(p, stub) {
+    const archive = stub?.retention_archive;
+    const sourceRel = String(archive?.source_path || '').split(path.sep).join('/');
+    const gzipRel = String(archive?.gzip_path || '').split(path.sep).join('/');
+    if (!sourceRel || sourceRel.startsWith('../') || path.posix.isAbsolute(sourceRel) || path.posix.normalize(sourceRel) !== sourceRel) {
+        throw new Error('retention_archive_invalid_source_path');
+    }
+    if (gzipRel !== `${sourceRel}.gz`)
+        throw new Error('retention_archive_invalid_gzip_path');
+    const sourceParts = sourceRel.split('/').filter(Boolean);
+    const archiveRoot = path.resolve(path.dirname(p), ...Array(Math.max(0, sourceParts.length - 1)).fill('..'));
+    const resolvedSource = path.resolve(p);
+    const resolvedGzip = path.resolve(archiveRoot, ...gzipRel.split('/'));
+    if (path.resolve(archiveRoot, ...sourceParts) !== resolvedSource || resolvedGzip !== `${resolvedSource}.gz`) {
+        throw new Error('retention_archive_path_escape');
+    }
+    const compressed = await fsp.readFile(resolvedGzip);
+    const original = await gunzipAsync(compressed);
+    const expectedSha = String(archive?.original_sha256 || '');
+    if (!/^[a-f0-9]{64}$/i.test(expectedSha) || sha256(original) !== expectedSha) {
+        throw new Error('retention_archive_sha256_mismatch');
+    }
+    return JSON.parse(original.toString('utf8'));
+}
 export async function writeJsonAtomic(p, data) {
     await writeTextAtomic(p, `${JSON.stringify(data, null, 2)}\n`);
 }

package/dist/core/harness-conflicts.js

@@ -5,11 +5,15 @@ export const OTHER_HARNESS_NAMES = ['OMX', 'DCodex'];
 export async function scanHarnessConflicts(root, opts = {}) {
     const projectRoot = path.resolve(root || process.cwd());
     const home = opts.home || process.env.HOME || '';
+    const codexHomes = [...new Set([
+            home ? path.join(home, '.codex') : '',
+            opts.codexHome || process.env.CODEX_HOME || ''
+        ].filter(Boolean).map((entry) => path.resolve(entry)))];
     const includeGlobal = opts.includeGlobal !== false;
     const conflicts = [];
     conflicts.push(...await scanProjectHarnessConflicts(projectRoot));
-    if (includeGlobal && home)
-        conflicts.push(...await scanGlobalHarnessConflicts(home));
+    if (includeGlobal && (home || codexHomes.length))
+        conflicts.push(...await scanGlobalHarnessConflicts(home, codexHomes));
     const hard = conflicts.filter((x) => x.hard_block);
     const repairable = conflicts.filter((x) => x.repairable && !x.hard_block);
     return {
@@ -18,6 +22,7 @@ export async function scanHarnessConflicts(root, opts = {}) {
         requires_human_approval: conflicts.some((x) => x.requires_human_approval),
         project_root: projectRoot,
         global_home: home || null,
+        global_codex_homes: codexHomes,
         conflicts,
         hard,
         repairable
@@ -72,9 +77,9 @@ async function scanProjectHarnessConflicts(root) {
     }
     return out;
 }
-async function scanGlobalHarnessConflicts(home) {
+async function scanGlobalHarnessConflicts(home, codexHomes) {
     const out = [];
-    for (const rel of [
+    for (const rel of home ? [
         '.omx',
         '.omxrc',
         '.config/omx',
@@ -83,17 +88,19 @@ async function scanGlobalHarnessConflicts(home) {
         '.dcodexrc',
         '.config/dcodex',
         'Library/Application Support/DCodex'
-    ]) {
+    ] : []) {
         const abs = path.join(home, rel);
         if (await exists(abs)) {
             const name = rel.toLowerCase().includes('omx') ? 'OMX' : 'DCodex';
             out.push(blockingConflict('global', abs, `${name} global harness marker exists`, `${name} must be removed globally before SKS can be installed.`));
         }
     }
-    const globalCodex = path.join(home, '.codex', 'config.toml');
-    const configText = await readText(globalCodex, null);
-    if (typeof configText === 'string' && /\bomx\b|\.omx|\bdcodex\b|\.dcodex/i.test(configText)) {
-        out.push(blockingConflict('global', globalCodex, 'Other harness marker detected in global Codex config', 'Remove the other harness global config before SKS setup.'));
+    for (const codexHome of codexHomes) {
+        const globalCodex = path.join(codexHome, 'config.toml');
+        const configText = await readText(globalCodex, null);
+        if (typeof configText === 'string' && /\bomx\b|\.omx|\bdcodex\b|\.dcodex/i.test(configText)) {
+            out.push(blockingConflict('global', globalCodex, 'Other harness marker detected in global Codex config', 'Remove the other harness global config before SKS setup.'));
+        }
     }
     return out;
 }
@@ -169,7 +176,7 @@ export function formatHarnessConflictReport(scan, opts = {}) {
 }
 export function llmHarnessCleanupPrompt(scan) {
     const paths = (scan?.conflicts || []).map((x) => `- ${x.scope}: ${x.path} (${x.reason})`).join('\n') || '- No paths supplied. Re-run `sks doctor --json` first.';
-    return `Use GPT-5.5 with reasoning effort high.
+    return `Use GPT-5.6 with reasoning effort high.
 
 Goal: completely remove the conflicting Codex harnesses before installing Sneakoscope Codex.
 
@@ -204,6 +211,8 @@ export async function repairSksGeneratedArtifacts(root, opts = {}) {
         '.sneakoscope/harness-guard.json'
     ];
     for (const rel of rels) {
+        if (rel === '.codex/agents' && opts.preserveCodexAgents === true)
+            continue;
         const abs = path.join(root, rel);
         if (!(await exists(abs)))
             continue;

package/dist/core/hooks-runtime/code-pack-freshness-preflight.js

@@ -11,10 +11,11 @@ import { exists, readJson, runProcess } from '../fsx.js';
  * the whole check is one JSON read plus one `git rev-parse HEAD`, wrapped in a hard
  * timeout so it cannot blow the hook latency budget. Any failure resolves to null. */
 export async function codePackFreshnessNote(root, opts = {}) {
-    const budgetMs = opts.budgetMs ?? 250;
-    return raceWithTimeout(computeNote(root), budgetMs).catch(() => null);
+    const budgetMs = Math.max(1, opts.budgetMs ?? 250);
+    const gitTimeoutMs = Math.max(1, budgetMs - 50);
+    return raceWithTimeout(computeNote(root, gitTimeoutMs), budgetMs).catch(() => null);
 }
-async function computeNote(root) {
+async function computeNote(root, gitTimeoutMs) {
     const packPath = path.join(root, '.sneakoscope', 'wiki', 'code-pack.json');
     if (!(await exists(packPath)))
         return null;
@@ -24,7 +25,7 @@ async function computeNote(root) {
     // rather than nag with a comparison we can't actually make.
     if (!packSha)
         return null;
-    const head = await runProcess('git', ['rev-parse', 'HEAD'], { cwd: root, timeoutMs: 200 }).catch(() => null);
+    const head = await runProcess('git', ['rev-parse', 'HEAD'], { cwd: root, timeoutMs: gitTimeoutMs }).catch(() => null);
     const currentSha = head && head.code === 0 ? String(head.stdout || '').trim() : null;
     if (!currentSha || currentSha === packSha)
         return null;