sneakoscope 3.1.6 → 3.1.8

package/dist/core/codex-app/codex-skill-sync.js

@@ -1,167 +1,95 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import os from 'node:os';
-import crypto from 'node:crypto';
-import { ensureDir, nowIso, writeJsonAtomic, writeTextAtomic } from '../fsx.js';
-const SKS_SKILLS = [
-    '$Loop',
-    '$Naruto',
-    '$QA-LOOP',
-    '$Research',
-    '$DFix',
-    '$Image-UX-Review',
-    '$Computer-Use',
-    '$Init-Deep'
-];
+import { ensureDir, nowIso, writeJsonAtomic } from '../fsx.js';
+import { buildSksCoreSkillManifest } from '../codex-native/core-skill-manifest.js';
+import { syncCoreSkillsIntegrity } from '../codex-native/core-skill-integrity.js';
+import { dedupeProjectSkills } from '../codex-native/project-skill-dedupe.js';
 const EXTERNAL_ROUTE_RESERVED = new Set(['ulw-loop', 'ulw-plan', 'start-work']);
 export async function syncCodexSksSkills(input) {
     const root = path.resolve(input.root);
     const skillsRoot = input.skillsRoot || path.join(process.env.CODEX_HOME || path.join(os.homedir(), '.codex'), 'skills');
-    const existing = await listSkillNames(skillsRoot);
-    const collisions = existing.filter((name) => EXTERNAL_ROUTE_RESERVED.has(name));
-    const desired = SKS_SKILLS.map((skill) => skillName(skill));
-    const created = [];
-    const skipped = [];
-    if (input.apply === true) {
-        await ensureDir(skillsRoot);
-        for (const name of desired) {
-            if (EXTERNAL_ROUTE_RESERVED.has(name)) {
-                skipped.push(name);
-                continue;
-            }
-            const dir = path.join(skillsRoot, name);
-            const file = path.join(dir, 'SKILL.md');
-            const content = skillContent(name);
-            const current = await fs.readFile(file, 'utf8').catch(() => '');
-            if (current && !current.includes('BEGIN SKS MANAGED SKILL')) {
-                skipped.push(name);
-                continue;
-            }
-            await ensureDir(dir);
-            await writeTextAtomic(file, content);
-            created.push(file);
+    return withSkillSyncLock(root, async () => {
+        const beforeExisting = await listSkillNames(skillsRoot);
+        const reserved = beforeExisting.filter((name) => EXTERNAL_ROUTE_RESERVED.has(name));
+        const manifest = buildSksCoreSkillManifest();
+        const desired = manifest.skills.map((skill) => skill.canonical_name);
+        const integrity = await syncCoreSkillsIntegrity({
+            root,
+            apply: input.apply === true,
+            skillsRoot,
+            reportPath: path.join(root, '.sneakoscope', 'reports', 'core-skill-integrity.json')
+        });
+        const dedupe = await dedupeProjectSkills({
+            root,
+            fix: input.apply === true,
+            yes: true,
+            quarantineUserDuplicates: false,
+            reportPath: path.join(root, '.sneakoscope', 'reports', 'project-skill-dedupe.json')
+        }).catch((err) => ({
+            ok: false,
+            blockers: [err instanceof Error ? err.message : String(err)],
+            unresolved_user_duplicates: [],
+            actions: []
+        }));
+        const report = {
+            schema: 'sks.codex-skill-sync.v1',
+            generated_at: nowIso(),
+            ok: integrity.ok && dedupe.ok !== false,
+            apply: input.apply === true,
+            skills_root: skillsRoot,
+            desired_skills: desired,
+            existing_skills: beforeExisting,
+            created: integrity.installed,
+            skipped: integrity.skipped_user_authored,
+            external_route_names_preserved: reserved,
+            integrity_report: '.sneakoscope/reports/core-skill-integrity.json',
+            dedupe_report: '.sneakoscope/reports/project-skill-dedupe.json',
+            interop: {
+                mode: 'coexist',
+                clobbered_external_routes: false,
+                clobbered_user_skills: false,
+                skipped_user_skills: integrity.skipped_user_authored,
+                managed_skills: desired
+            },
+            blockers: [...integrity.blockers, ...(dedupe.blockers || [])]
+        };
+        await writeJsonAtomic(path.join(root, '.sneakoscope', 'reports', 'codex-skill-sync.json'), report).catch(() => undefined);
+        return report;
+    });
+}
+export async function withSkillSyncLock(root, fn) {
+    const lockPath = path.join(path.resolve(root), '.sneakoscope', 'locks', 'skill-sync.lock');
+    await ensureDir(path.dirname(lockPath));
+    const started = Date.now();
+    while (true) {
+        try {
+            await fs.mkdir(lockPath);
+            break;
+        }
+        catch (err) {
+            const code = err && typeof err === 'object' && 'code' in err ? String(err.code) : '';
+            if (code !== 'EEXIST')
+                throw err;
+            if (Date.now() - started > 30000)
+                throw new Error(`Timed out waiting for skill sync lock: ${lockPath}`);
+            await new Promise((resolve) => setTimeout(resolve, 25));
         }
     }
-    const report = {
-        schema: 'sks.codex-skill-sync.v1',
-        generated_at: nowIso(),
-        ok: true,
-        apply: input.apply === true,
-        skills_root: skillsRoot,
-        desired_skills: desired,
-        existing_skills: existing,
-        created,
-        skipped,
-        external_route_names_preserved: collisions,
-        interop: {
-            mode: 'coexist',
-            clobbered_external_routes: false,
-            clobbered_user_skills: false
-        },
-        blockers: []
-    };
-    await writeJsonAtomic(path.join(root, '.sneakoscope', 'reports', 'codex-skill-sync.json'), report).catch(() => undefined);
-    return report;
+    try {
+        await writeJsonAtomic(path.join(lockPath, 'owner.json'), {
+            schema: 'sks.skill-sync-lock.v1',
+            pid: process.pid,
+            acquired_at: nowIso()
+        }).catch(() => undefined);
+        return await fn();
+    }
+    finally {
+        await fs.rm(lockPath, { recursive: true, force: true }).catch(() => undefined);
+    }
 }
 async function listSkillNames(root) {
     const rows = await fs.readdir(root, { withFileTypes: true }).catch(() => []);
     return rows.filter((row) => row.isDirectory()).map((row) => row.name).sort();
 }
-function skillName(value) {
-    return value.replace(/^\$/, '').toLowerCase();
-}
-function skillContent(name) {
-    const profile = skillProfile(name);
-    const body = [
-        '---',
-        `name: ${name}`,
-        `description: SKS managed Codex App route bridge for ${profile.command}.`,
-        '---',
-        '',
-        '<!-- BEGIN SKS MANAGED SKILL -->',
-        `Command: ${profile.command}`,
-        `Purpose: ${profile.purpose}`,
-        `Use when: ${profile.when}`,
-        `Route: ${profile.command}`,
-        `Evidence: ${profile.evidence}`,
-        'Safety: keep route state bounded, preserve user and external route assets, and stop on hard blockers instead of fabricating fallback behavior.',
-        'Proof paths: write the route-local mission artifact named in Evidence before claiming completion.',
-        'Failure recovery: if a proof path cannot be produced, record the blocker and continue only when the selected SKS route has another allowed evidence path.',
-        `Fallback: ${profile.fallback}`,
-        `checksum: ${hash(`${name}:${profile.command}:${profile.evidence}:${profile.fallback}`)}`,
-        '<!-- END SKS MANAGED SKILL -->',
-        ''
-    ].join('\n');
-    return body;
-}
-function skillProfile(name) {
-    const table = {
-        loop: {
-            command: '$Loop',
-            purpose: 'compile persisted route work into bounded loop plans with continuation evidence.',
-            when: 'a mission needs stage-by-stage execution, memory hints, or resume-safe artifacts.',
-            evidence: '.sneakoscope/loops/** plus codex-app-execution-profile.json',
-            fallback: 'use message-role routing when native agent_type is not verified.'
-        },
-        naruto: {
-            command: '$Naruto',
-            purpose: 'fan out bounded native worker lanes for high-scale review or implementation.',
-            when: 'parallel lanes are explicitly selected by the route and parent integration remains owner.',
-            evidence: 'naruto work graph, worker ledgers, and execution profile payloads.',
-            fallback: 'degrade to message-role workers without dropping proof artifacts.'
-        },
-        'qa-loop': {
-            command: '$QA-LOOP',
-            purpose: 'dogfood UI/API behavior with gate artifacts and current execution profile.',
-            when: 'route completion needs human-proxy verification or app handoff checks.',
-            evidence: 'qa-loop gate/result ledgers and codex-app-execution-profile.json.',
-            fallback: 'record the unavailable surface as blocked rather than inventing visual proof.'
-        },
-        research: {
-            command: '$Research',
-            purpose: 'run evidence-bound research cycles with source routing and synthesis ledgers.',
-            when: 'the request depends on discovery, evaluation, or external-source claims.',
-            evidence: 'research plan, source ledger, cycle record, and execution profile routing.',
-            fallback: 'mark unavailable source tools explicitly and avoid unsupported live-accuracy claims.'
-        },
-        dfix: {
-            command: '$DFix',
-            purpose: 'perform tiny direct fixes without the full Team route.',
-            when: 'copy/config/docs/labels/spacing/translation/mechanical edits are truly narrow.',
-            evidence: 'focused diff plus DFix Honest check.',
-            fallback: 'route broad implementation through Team/Loop instead.'
-        },
-        'image-ux-review': {
-            command: '$Image-UX-Review',
-            purpose: 'produce generated annotated UI review images and extract issue ledgers.',
-            when: 'visual UX critique is requested from screenshots or app captures.',
-            evidence: 'source inventory, generated annotation images, extracted issue ledger.',
-            fallback: 'block if raster annotation cannot be produced.'
-        },
-        'computer-use': {
-            command: '$Computer-Use',
-            purpose: 'operate native macOS desktop apps through the fast Computer Use lane.',
-            when: 'the task depends on non-web desktop UI or OS settings.',
-            evidence: 'desktop interaction notes/screenshots where available.',
-            fallback: 'use Browser/Chrome only for web targets.'
-        },
-        'init-deep': {
-            command: '$Init-Deep',
-            purpose: 'refresh project-local memory, directory AGENTS sections, and loop memory hints.',
-            when: 'a route needs deeper local context or directory-specific instruction recall.',
-            evidence: '.sneakoscope/context/AGENTS.generated.md and managed directory AGENTS blocks.',
-            fallback: 'preserve user content and skip directories that cannot be safely updated.'
-        }
-    };
-    return table[name] || {
-        command: `$${name}`,
-        purpose: 'bridge an SKS managed Codex App route.',
-        when: 'the matching SKS route is explicitly requested.',
-        evidence: '.sneakoscope route artifacts.',
-        fallback: 'record blockers with evidence.'
-    };
-}
-function hash(value) {
-    return crypto.createHash('sha256').update(`sks-skill:${value}`).digest('hex').slice(0, 12);
-}
 //# sourceMappingURL=codex-skill-sync.js.map

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

@@ -22,6 +22,7 @@ export async function detectCodex0138Capability(input = {}) {
         };
     const pluginJsonOk = atLeast138 && (probeMode === 'version-only' || featureProbeResults.plugin_json !== 'failed');
     const appHandoffOk = atLeast138 && (probeMode === 'version-only' || featureProbeResults.app_handoff_platform === 'passed');
+    const imagePathExposureOk = atLeast138 && process.env.SKS_CODEX_0138_FAKE_IMAGE_PATH_FAIL !== '1';
     const blockers = [
         ...(!codexBin ? ['codex_cli_missing'] : []),
         ...(atLeast138 ? [] : ['codex_0_138_required_for_app_plugin_features']),
@@ -36,7 +37,7 @@ export async function detectCodex0138Capability(input = {}) {
         parsed_version: parsed,
         supports_app_handoff: appHandoffOk,
         supports_plugin_json: pluginJsonOk,
-        supports_image_path_exposure: atLeast138,
+        supports_image_path_exposure: imagePathExposureOk,
         supports_model_defined_efforts: atLeast138,
         supports_app_server_token_usage: atLeast138,
         supports_v2_pat_auth: atLeast138,
@@ -78,7 +79,9 @@ async function probeCodex0138Features(codexBin, opts = {}) {
     if (opts.fake) {
         return {
             plugin_json: process.env.SKS_CODEX_0138_FAKE_PLUGIN_JSON_FAIL === '1' ? 'failed' : 'passed',
-            app_handoff_platform: process.platform === 'darwin' || process.platform === 'win32' ? 'passed' : 'failed',
+            app_handoff_platform: process.env.SKS_CODEX_0138_FAKE_APP_HANDOFF_FAIL === '1'
+                ? 'failed'
+                : process.platform === 'darwin' || process.platform === 'win32' ? 'passed' : 'failed',
             image_path_exposure_contract: 'sks-enforced'
         };
     }

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

@@ -1,10 +1,9 @@
 import path from 'node:path';
+import fs from 'node:fs/promises';
 import { findCodexBinary } from '../codex-adapter.js';
 import { codexAppIntegrationStatus } from '../codex-app.js';
-import { syncCodexAgentRoles } from '../codex-app/codex-agent-role-sync.js';
 import { probeCodexAgentTypeSupport } from '../codex-app/codex-agent-type-probe.js';
 import { probeCodexHookApprovalState } from '../codex-app/codex-hook-approval-probe.js';
-import { syncCodexSksSkills } from '../codex-app/codex-skill-sync.js';
 import { detectCodex0138Capability } from '../codex-control/codex-0138-capability.js';
 import { detectCodex0139Capability } from '../codex-control/codex-0139-capability.js';
 import { buildCodexPluginInventory } from '../codex-plugins/codex-plugin-json.js';
@@ -12,8 +11,13 @@ import { nowIso, runProcess, writeJsonAtomic } from '../fsx.js';
 import { buildMcpPluginServerCandidates } from '../mcp/mcp-plugin-inventory.js';
 import { codexNativeFeatureState, computeCodexNativeInvocationDefaults } from './codex-native-feature-matrix.js';
 const REPORT_PATH = '.sneakoscope/reports/codex-native-feature-matrix.json';
+const REQUIRED_SKILL_NAMES = ['loop', 'naruto', 'qa-loop', 'research', 'dfix', 'image-ux-review', 'computer-use', 'init-deep'];
+const REQUIRED_AGENT_ROLES = ['sks-explorer', 'sks-planner', 'sks-implementer', 'sks-checker', 'sks-release-verifier', 'sks-zellij-ui-verifier', 'sks-codex-probe-verifier'];
 export async function buildCodexNativeFeatureMatrix(input = { root: process.cwd() }) {
     const root = path.resolve(input.root || process.cwd());
+    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 fixtureMode = process.env.SKS_CODEX_0138_FAKE === '1' || process.env.SKS_CODEX_0139_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;
@@ -57,8 +61,8 @@ export async function buildCodexNativeFeatureMatrix(input = { root: process.cwd(
         blockers: [messageOf(err)],
         warnings: ['agent_type_probe_failed_message_role_fallback']
     }));
-    const skillSync = await syncCodexSksSkills({ root, apply: input.applyRepairs === true }).catch((err) => ({ ok: false, blockers: [messageOf(err)] }));
-    const agentRoles = await syncCodexAgentRoles({ root, apply: input.applyRepairs === true }).catch((err) => ({ ok: false, blockers: [messageOf(err)] }));
+    const skillSync = await inspectManagedSkillState(root);
+    const agentRoles = await inspectManagedAgentRoleState(root);
     const appRecord = isRecord(app) ? app : {};
     const requiredSkills = isRecord(appRecord.required_skills) ? appRecord.required_skills : {};
     const skills = isRecord(appRecord.skills) ? appRecord.skills : {};
@@ -91,7 +95,7 @@ export async function buildCodexNativeFeatureMatrix(input = { root: process.cwd(
             unavailableStatus: 'fallback'
         }),
         mcp_inventory: codexNativeFeatureState({
-            ok: mcpCandidates.candidates.length > 0 || Array.isArray(plugins.plugins),
+            ok: mcpCandidates.candidates.length > 0,
             source: 'plugin-inventory',
             artifact_path: '.sneakoscope/mcp-plugin-server-candidates.json',
             evidence: [`candidate_count:${mcpCandidates.candidates.length}`],
@@ -134,7 +138,11 @@ export async function buildCodexNativeFeatureMatrix(input = { root: process.cwd(
             ...(!codexBin ? ['codex_cli_missing'] : []),
             ...Object.values(features).flatMap((feature) => feature.blockers)
         ],
-        warnings: Object.values(features).flatMap((feature) => feature.warnings)
+        warnings: [
+            ...Object.values(features).flatMap((feature) => feature.warnings),
+            ...(deprecatedApplyRepairs ? ['deprecated_apply_repairs_input'] : []),
+            ...(mode === 'repair' && !repairManagedAssets ? ['repair_mode_without_managed_asset_repair'] : [])
+        ]
     };
     const matrix = {
         ...matrixBase,
@@ -144,6 +152,66 @@ export async function buildCodexNativeFeatureMatrix(input = { root: process.cwd(
     await writeCodexNativeFeatureMatrix(root, matrix, input.missionDir);
     return matrix;
 }
+async function inspectManagedSkillState(root) {
+    const skillRoots = [
+        path.join(root, '.agents', 'skills'),
+        ...(process.env.CODEX_HOME ? [path.join(process.env.CODEX_HOME, 'skills')] : [])
+    ];
+    let existingCount = 0;
+    const managed = new Set();
+    for (const dir of skillRoots) {
+        const rows = await fs.readdir(dir, { withFileTypes: true }).catch(() => []);
+        existingCount += rows.filter((row) => row.isDirectory()).length;
+        for (const name of REQUIRED_SKILL_NAMES) {
+            if (managed.has(name))
+                continue;
+            const text = await fs.readFile(path.join(dir, name, 'SKILL.md'), 'utf8').catch(() => '');
+            if (text.includes('BEGIN SKS MANAGED SKILL'))
+                managed.add(name);
+        }
+    }
+    const missing = REQUIRED_SKILL_NAMES.filter((name) => !managed.has(name));
+    return {
+        ok: missing.length === 0,
+        apply: false,
+        artifact_path: '.sneakoscope/reports/codex-skill-sync.json',
+        existing_count: existingCount,
+        managed_count: managed.size,
+        missing_required: missing,
+        blockers: missing.length ? [`managed_skills_missing:${missing.join(',')}`] : [],
+        warnings: existingCount > managed.size ? ['non_sks_skill_dirs_ignored'] : []
+    };
+}
+async function inspectManagedAgentRoleState(root) {
+    const dirs = [
+        path.join(root, '.codex', 'agents'),
+        ...(process.env.CODEX_HOME ? [path.join(process.env.CODEX_HOME, 'agents')] : [])
+    ];
+    let existingCount = 0;
+    const managed = new Set();
+    for (const dir of dirs) {
+        const rows = await fs.readdir(dir, { withFileTypes: true }).catch(() => []);
+        existingCount += rows.filter((row) => row.isFile() && row.name.endsWith('.toml')).length;
+        for (const role of REQUIRED_AGENT_ROLES) {
+            if (managed.has(role))
+                continue;
+            const text = await fs.readFile(path.join(dir, `${role}.toml`), 'utf8').catch(() => '');
+            if (text.includes('SKS managed 3.1.7 directive role'))
+                managed.add(role);
+        }
+    }
+    const missing = REQUIRED_AGENT_ROLES.filter((role) => !managed.has(role));
+    return {
+        ok: missing.length === 0,
+        apply: false,
+        artifact_path: '.sneakoscope/reports/codex-agent-role-sync.json',
+        existing_count: existingCount,
+        managed_count: managed.size,
+        missing_required: missing,
+        blockers: missing.length ? [`managed_agent_roles_missing:${missing.join(',')}`] : [],
+        warnings: existingCount > managed.size ? ['non_sks_agent_roles_ignored'] : []
+    };
+}
 export async function writeCodexNativeFeatureMatrix(root, matrix, missionDir) {
     await writeJsonAtomic(path.join(root, REPORT_PATH), matrix);
     if (missionDir)

package/dist/core/codex-native/codex-native-pattern-analysis.js

@@ -1,4 +1,5 @@
 import path from 'node:path';
+import { createHash } from 'node:crypto';
 import { nowIso, writeJsonAtomic, writeTextAtomic } from '../fsx.js';
 import { analyzeCodexNativeReferenceSource, renderCodexNativeReferenceMarkdown } from './codex-native-reference-source.js';
 const PATTERN_ROWS = [
@@ -19,22 +20,26 @@ export async function buildCodexNativePatternAnalysis(input) {
     const root = path.resolve(input.root);
     const evidence = input.evidence || await analyzeCodexNativeReferenceSource({ root, sourceDir: input.sourceDir || null, writeReport: true }).catch(() => null);
     const evidenceByPattern = new Map();
+    const confidenceByPattern = new Map();
     for (const item of evidence?.evidence || []) {
         const list = evidenceByPattern.get(item.pattern_id) || [];
         list.push(item.snippet_hash);
         evidenceByPattern.set(item.pattern_id, list);
+        confidenceByPattern.set(item.pattern_id, strongerConfidence(confidenceByPattern.get(item.pattern_id), item.confidence));
     }
     return {
         schema: 'sks.codex-native-pattern-analysis.v1',
         generated_at: nowIso(),
         source_kind: 'external-reference-source',
-        source_ref: evidence?.source_ref || input.sourceDir || '.sneakoscope/cache/codex-native-reference',
+        source_ref: evidence?.source_ref || neutralSourceRef(input.sourceDir || '.sneakoscope/cache/codex-native-reference'),
         source_sha: evidence?.source_sha || null,
+        source_url_hash: evidence?.source_url_hash || null,
+        cache_report_path: evidence?.cache_report_path || null,
         patterns: PATTERN_ROWS.map((pattern) => {
             const hashes = evidenceByPattern.get(pattern.id) || [];
             return {
                 ...pattern,
-                confidence: hashes.length ? 'high' : evidence ? 'medium' : 'low',
+                confidence: confidenceByPattern.get(pattern.id) || (hashes.length ? 'medium' : evidence ? 'low' : 'low'),
                 evidence_hashes: hashes
             };
         }),
@@ -42,6 +47,13 @@ export async function buildCodexNativePatternAnalysis(input) {
         warnings: evidence?.warnings || ['reference_evidence_unavailable']
     };
 }
+function neutralSourceRef(value) {
+    return `source:${createHash('sha256').update(value).digest('hex').slice(0, 16)}`;
+}
+function strongerConfidence(current, next) {
+    const rank = { low: 0, medium: 1, high: 2 };
+    return current && rank[current] >= rank[next] ? current : next;
+}
 export async function writeCodexNativePatternAnalysis(root, input = {}) {
     const evidence = await analyzeCodexNativeReferenceSource({ root, sourceDir: input.sourceDir || null, writeReport: true }).catch(() => null);
     const report = await buildCodexNativePatternAnalysis({ root, evidence, sourceDir: input.sourceDir || null });

package/dist/core/codex-native/codex-native-reference-cache.js

@@ -0,0 +1,98 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { exists, nowIso, runProcess, sha256, writeJsonAtomic } from '../fsx.js';
+export async function ensureCodexNativeReferenceSnapshot(input) {
+    const root = path.resolve(input.root);
+    const cacheDir = path.join(root, '.sneakoscope', 'cache', 'codex-native-reference');
+    const reportPath = path.join(root, '.sneakoscope', 'reports', 'codex-native-reference-cache.json');
+    const sourceUrl = input.sourceUrl ?? process.env.SKS_CODEX_NATIVE_REFERENCE_SOURCE_URL ?? null;
+    const sourceRef = input.ref || process.env.SKS_CODEX_NATIVE_REFERENCE_REF || 'HEAD';
+    const offline = input.offline === true || process.env.SKS_CODEX_NATIVE_REFERENCE_OFFLINE === '1' || !sourceUrl;
+    const blockers = [];
+    const warnings = [];
+    let refreshed = false;
+    if (!offline && sourceUrl) {
+        const parent = path.dirname(cacheDir);
+        await fs.mkdir(parent, { recursive: true });
+        const gitDir = path.join(cacheDir, '.git');
+        const timeoutMs = input.timeoutMs || 60_000;
+        if (!(await exists(gitDir))) {
+            if (await exists(cacheDir))
+                await fs.rm(cacheDir, { recursive: true, force: true });
+            const cloneArgs = [
+                'clone',
+                '--depth',
+                '1',
+                '--filter=blob:none',
+                ...(sourceRef === 'HEAD' ? [] : ['--branch', sourceRef]),
+                sourceUrl,
+                cacheDir
+            ];
+            const cloned = await runProcess('git', cloneArgs, {
+                timeoutMs,
+                maxOutputBytes: 128 * 1024
+            }).catch((err) => ({ code: 1, stderr: messageOf(err), stdout: '' }));
+            if (cloned.code === 0)
+                refreshed = true;
+            else
+                blockers.push('source_snapshot_fetch_failed');
+        }
+        else if (input.refresh === true) {
+            const fetched = await runProcess('git', ['fetch', '--depth', '1', 'origin', sourceRef], {
+                cwd: cacheDir,
+                timeoutMs,
+                maxOutputBytes: 128 * 1024
+            }).catch((err) => ({ code: 1, stderr: messageOf(err), stdout: '' }));
+            if (fetched.code === 0) {
+                await runProcess('git', ['checkout', 'FETCH_HEAD'], { cwd: cacheDir, timeoutMs, maxOutputBytes: 64 * 1024 }).catch(() => null);
+                refreshed = true;
+            }
+            else {
+                blockers.push('source_snapshot_refresh_failed');
+            }
+        }
+    }
+    else {
+        warnings.push(sourceUrl ? 'reference_cache_offline_mode' : 'reference_source_url_missing_offline_cache_only');
+    }
+    const cacheExists = await hasTextFiles(cacheDir);
+    if (!cacheExists)
+        blockers.push('source_snapshot_missing');
+    const report = {
+        schema: 'sks.codex-native-reference-cache.v1',
+        generated_at: nowIso(),
+        ok: blockers.length === 0,
+        cache_dir: path.relative(root, cacheDir),
+        source_url_hash: sourceUrl ? sha256(sourceUrl) : null,
+        source_ref: sourceRef,
+        source_sha: await gitSha(cacheDir),
+        refreshed,
+        offline,
+        blockers: [...new Set(blockers)],
+        warnings: [...new Set(warnings)]
+    };
+    await writeJsonAtomic(reportPath, report).catch(() => undefined);
+    return report;
+}
+async function hasTextFiles(dir) {
+    const rows = await fs.readdir(dir, { withFileTypes: true }).catch(() => []);
+    for (const row of rows) {
+        if (row.name === '.git' || row.name === 'node_modules' || row.name === 'dist')
+            continue;
+        const full = path.join(dir, row.name);
+        if (row.isFile() && /\.(md|txt|json|toml|ya?ml|js|ts|mjs|cjs)$/i.test(row.name))
+            return true;
+        if (row.isDirectory() && await hasTextFiles(full))
+            return true;
+    }
+    return false;
+}
+async function gitSha(sourceDir) {
+    const run = await runProcess('git', ['rev-parse', 'HEAD'], { cwd: sourceDir, timeoutMs: 5000, maxOutputBytes: 4096 }).catch(() => null);
+    const sha = run?.code === 0 ? `${run.stdout || ''}`.trim() : '';
+    return /^[0-9a-f]{40}$/i.test(sha) ? sha : null;
+}
+function messageOf(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+//# sourceMappingURL=codex-native-reference-cache.js.map