sneakoscope 10.5.4 → 10.5.5

package/README.md

@@ -17,7 +17,7 @@
 Sneakoscope Codex (`sks`) is an open-source trust layer for Codex CLI and ChatGPT Desktop. It coordinates bounded AI coding agents, records machine-verifiable evidence, preserves project memory, and blocks release claims that are not supported by current tests or artifacts. Search visibility outcomes are measured separately; SKS does not promise rankings or traffic.
 <!-- END SKS SEARCH VISIBILITY MARKETING -->
 
-Current package: **SKS 10.5.4**. Install the latest stable release from npm.
+Current package: **SKS 10.5.5**. Install the latest stable release from npm.
 
 Sneakoscope Codex (`sks`) is a local trust layer for Codex CLI and ChatGPT Desktop. It keeps agent work bounded, preserves project context, records machine-verifiable evidence, and prevents release claims that current tests or artifacts cannot support.
 
@@ -66,6 +66,11 @@ The installer resolves the latest npm release, installs `sks`, runs setup and Do
 | Recover safely | Doctor and update flows report a concrete recovery action when a check needs attention. |
 | Operate locally | The CLI works without a hosted control plane; macOS users can also use SKS Center. |
 
+`$sks-align` refreshes the thin managed guidance against current official Codex
+references and rebuilds TriWiki. Update and user-run `sks doctor --fix` share
+that maintenance and repair known ignored configuration settings. User text
+and model choices are preserved. See [harness maintenance](docs/align-modernization.md).
+
 ## Everyday commands
 
 Inside a Codex conversation:

package/config/skills-hash-ledger.v1.json

@@ -15,6 +15,7 @@
     {
       "canonical_name": "sks-align",
       "trusted_sha256": [
+        "c3073b4a10203e642dd1236902b01772ecff6a3a7464cdecde0aad21e3c12b80",
         "9eef36214be7e07a963eb36bb1df2c025cd0578b7419ddf4fd307081a2b62093",
         "b9db40d6e1dd2fc6e4665a2b30738d370da955cd4d6e86c88bd85059c7faa08c",
         "c485f39d4873adb9793672f7dcf4e956595ffb9dcbb032b3ffb0515b5857d31d",

package/crates/sks-core/Cargo.lock

@@ -259,7 +259,7 @@ dependencies = [
 
 [[package]]
 name = "sks-core"
-version = "10.5.4"
+version = "10.5.5"
 dependencies = [
  "globset",
  "grep-matcher",

package/crates/sks-core/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "sks-core"
-version = "10.5.4"
+version = "10.5.5"
 edition = "2021"
 
 [dependencies]

package/dist/commands/doctor-console.js

@@ -84,6 +84,12 @@ export function renderDoctorConsoleReport(result, extras) {
         for (const warning of codexConfigSyntaxRepair.warnings || [])
             line(`  warning: ${warning}`);
     }
+    if (result.harness_maintenance) {
+        const guidance = result.harness_maintenance;
+        line(`Official harness guidance: ${guidance.guidance_status}${guidance.fetched_at ? ` (${guidance.fetched_at})` : ''}`);
+        for (const warning of guidance.warnings || [])
+            line(`  warning: ${warning}`);
+    }
     line(`  codex doctor:    ${formatCodexDoctorConsoleStatus(result.codex_doctor)}`);
     line(`Rust acc.: ${rust.mode || (rust.available ? 'rust_accelerated' : 'js_fallback')} ${rust.version || rust.status || ''}`);
     line(`Codex App: ${codexApp.skipped === true ? DOCTOR_CONSOLE_NOT_MEASURED : ready.codex_app_ready ? 'ok' : 'optional_missing'}`);

package/dist/commands/doctor.js

@@ -1,6 +1,6 @@
 import os from 'node:os';
 import path from 'node:path';
-import { projectRoot, exists, formatBytes, nowIso, writeJsonAtomic } from '../core/fsx.js';
+import { projectRoot, exists, ensureDir, formatBytes, nowIso, writeJsonAtomic } from '../core/fsx.js';
 import { flag } from '../cli/args.js';
 import { printJson } from '../cli/output.js';
 import { ui as cliUi } from '../cli/cli-theme.js';
@@ -27,6 +27,7 @@ import { detectImagegenCapability } from '../core/imagegen/imagegen-capability.j
 import { formatHarnessConflictReport, scanHarnessConflicts } from '../core/harness-conflicts.js';
 import { doctorArgWarnings as baseDoctorArgWarnings, doctorGlobalOnlySelection, doctorMenuBarInstallPolicy, doctorPhaseIdsForProfile, doctorProfileFromArgs, doctorProfileRequiresDesktopBridgeReadiness } from './doctor-profile.js';
 import { renderDoctorConsoleReport } from './doctor-console.js';
+import { isVerificationTestHarness } from '../core/verification-profile.js';
 import { buildCodexAppUiDiagnosticFailure, buildRuntimeReadiness, captureCodexConfigSnapshot, deferredNativeRepair, fallbackCodexNativeFeatureMatrix, formatCodexDoctorConsoleStatus, installScopeFromArgs, isMigrationUserOwnedProjectConfigBlocker, mergeObservedCodexStartupWarnings, readOption, rebootstrapSksMenuBarLaunchdForDoctorFix, sksMenuBarRunningVersionConsoleLines, writeFixMigrationJournal, writeJsonReportFile } from './doctor-helpers.js';
 export { doctorMenuBarInstallPolicy, doctorProfileFromArgs, doctorProfileRequiresDesktopBridgeReadiness } from './doctor-profile.js';
 export { buildCodexAppUiDiagnosticFailure, buildRuntimeReadiness, formatCodexDoctorConsoleStatus, rebootstrapSksMenuBarLaunchdForDoctorFix, sksMenuBarRunningVersionConsoleLines };
@@ -202,6 +203,10 @@ export async function executeDoctorGlobalOnlyFix(args = [], root, deps = {}) {
         error: err?.message || String(err)
     }));
     const doctorProfile = doctorProfileFromArgs(args, true);
+    const syntaxRepair = await (await import('../core/doctor/codex-config-syntax-repair.js')).runCodexConfigSyntaxRepair({
+        root: home, fix: true, codexHome: doctorEnv.CODEX_HOME || path.join(home, '.codex')
+    });
+    const harnessMaintenance = await doctorHarnessMaintenance(path.resolve(deps.globalRuntimeRoot || doctorEnv.SKS_GLOBAL_ROOT || path.join(home, '.sneakoscope-global')), doctorProfile, doctorEnv, deps);
     const menuBarPolicy = doctorMenuBarInstallPolicy(args, true, doctorEnv);
     const menuBar = menuBarPolicy.phase_enabled
         ? await installMenuBarImpl({
@@ -248,6 +253,8 @@ export async function executeDoctorGlobalOnlyFix(args = [], root, deps = {}) {
         && globalFastMode?.ok !== false;
     const menuBarReady = menuBar?.ok !== false;
     const migrationScopeBlockers = [...new Set([
+            ...syntaxRepair.blockers,
+            ...(harnessMaintenance?.blockers || []),
             ...(!globalSkillsReady ? [`global_skills_reconcile_failed:${globalSkills?.error || 'core_skill_integrity'}`] : []),
             ...(currentSurface?.ok !== true ? (currentSurface?.blockers || ['global_current_surface_reconcile_failed']) : []),
             ...(!globalFastModeReady ? [`global_fast_mode_repair_failed:${globalFastMode?.error || globalFastMode?.status || 'unknown'}`] : [])
@@ -291,6 +298,8 @@ export async function executeDoctorGlobalOnlyFix(args = [], root, deps = {}) {
             ...migrationReceiptBlockers
         ].map(String).filter(Boolean))];
     const warnings = [...new Set([
+            ...syntaxRepair.warnings,
+            ...(harnessMaintenance?.warnings || []),
             ...(!bridgeReadinessRequired ? bridgeBlockers.map((blocker) => `migration_optional_blocker:${blocker}`) : []),
             ...(desktopBridgeRepair?.warnings || []),
             ...(desktopBridge?.warnings || [])
@@ -321,6 +330,8 @@ export async function executeDoctorGlobalOnlyFix(args = [], root, deps = {}) {
         ],
         skills: { global: globalSkills, project: { skipped: true, reason: 'global_only_doctor' } },
         current_public_surface: currentSurface,
+        codex_config_syntax_repair: syntaxRepair,
+        harness_maintenance: harnessMaintenance,
         codex_app_fast_mode: globalFastMode,
         openrouter_provider: desktopBridge.providers?.openrouter || null,
         sks_menubar: menuBar,
@@ -569,6 +580,7 @@ async function runDoctor(args = [], root, doctorFix, deps = {}) {
         actions: []
     })) : { ok: true, skipped: true, reason: 'doctor_without_fix', actions: [] };
     const doctorProfile = doctorProfileFromArgs(args, doctorFix);
+    const harnessMaintenance = doctorFix ? await doctorHarnessMaintenance(root, doctorProfile, process.env, deps) : null;
     const machineOnly = flag(args, '--machine-only');
     const reportFile = readOption(args, '--report-file', null);
     const argWarnings = doctorArgWarnings(args);
@@ -1467,6 +1479,7 @@ async function runDoctor(args = [], root, doctorFix, deps = {}) {
     }
     const runtimeReadiness = buildRuntimeReadiness(codexNativeFeatureMatrix);
     const resultBlockers = [
+        ...(harnessMaintenance?.blockers || []),
         ...(ready.ready
             ? []
             : (Array.isArray(ready.blockers) && ready.blockers.length
@@ -1511,7 +1524,7 @@ async function runDoctor(args = [], root, doctorFix, deps = {}) {
         root,
         arg_warnings: argWarnings,
         blockers: [...new Set(resultBlockers.map(String))],
-        warnings: [...oauthCallbackPortDiagnostic.warnings, ...(desktopBridge.warnings || [])],
+        warnings: [...oauthCallbackPortDiagnostic.warnings, ...(desktopBridge.warnings || []), ...(harnessMaintenance?.warnings || [])],
         operator_actions: [...new Set([
                 ...oauthCallbackOperatorActions,
                 ...(desktopBridge.ok === false ? desktopBridge.recovery_actions || [] : []),
@@ -1542,6 +1555,7 @@ async function runDoctor(args = [], root, doctorFix, deps = {}) {
         codex_startup_repair: codexStartupRepair,
         startup_config_repair: startupConfigRepair,
         codex_config_syntax_repair: codexConfigSyntaxRepair,
+        harness_maintenance: harnessMaintenance,
         context7_mcp_repair: context7McpRepair,
         supabase_mcp_repair: supabaseMcpRepair,
         doctor_fix_transaction: doctorFixTransaction,
@@ -1616,3 +1630,17 @@ async function runDoctor(args = [], root, doctorFix, deps = {}) {
     if (!result.ok)
         process.exitCode = 1;
 }
+async function doctorHarnessMaintenance(root, profile, env, deps) {
+    const duringUpdate = env.SKS_UPDATE_DEFER_MENUBAR_RESTART === '1';
+    if (profile === 'migration' && !duringUpdate)
+        return null;
+    await ensureDir(root);
+    const maintain = deps.maintainHarnessGuidanceImpl
+        || (await import('../core/agent-guidance/harness-maintenance.js')).maintainHarnessGuidance;
+    const codexHome = deps.codexHome || deps.env?.CODEX_HOME
+        || (deps.home ? path.join(deps.home, '.codex') : !isVerificationTestHarness() ? env.CODEX_HOME : undefined);
+    return maintain({
+        root, trigger: duringUpdate ? 'update' : 'doctor', reuseRecent: duringUpdate,
+        ...(codexHome ? { codexHome } : {})
+    });
+}

package/dist/config/skills-manifest.json

@@ -1,6 +1,6 @@
 {
   "schema": "sks.skills-manifest.v1",
-  "package_version": "10.5.4",
+  "package_version": "10.5.5",
   "skills": [
     {
       "canonical_name": "sks",
@@ -18,8 +18,9 @@
     {
       "canonical_name": "sks-align",
       "type": "core",
-      "content_sha256": "9eef36214be7e07a963eb36bb1df2c025cd0578b7419ddf4fd307081a2b62093",
+      "content_sha256": "c3073b4a10203e642dd1236902b01772ecff6a3a7464cdecde0aad21e3c12b80",
       "hash_history": [
+        "9eef36214be7e07a963eb36bb1df2c025cd0578b7419ddf4fd307081a2b62093",
         "b9db40d6e1dd2fc6e4665a2b30738d370da955cd4d6e86c88bd85059c7faa08c",
         "c485f39d4873adb9793672f7dcf4e956595ffb9dcbb032b3ffb0515b5857d31d",
         "e98e1b67e228bec5c37d00c0206a2e01d2da698a83c80b527105bf04a19c136a"

package/dist/core/agent-guidance/harness-maintenance.js

@@ -0,0 +1,185 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { readText, writeTextAtomic, writeJsonAtomic, mergeManagedBlock } from '../fsx.js';
+import { ensureConfinedDirectory, inspectConfinedPath } from '../managed-path-safety.js';
+import { withFileLock } from '../locks/file-lock.js';
+import { isVerificationTestHarness } from '../verification-profile.js';
+import { reconcileManagedProjectPromptGuidance } from '../doctor/current-project-guidance.js';
+import { globalAgentsBlockText, GLOBAL_AGENTS_MARKER } from '../codex-hooks/codex-global-hooks.js';
+export async function maintainHarnessGuidance(input) {
+    const root = path.resolve(input.root);
+    const codexHome = path.resolve(input.codexHome || process.env.CODEX_HOME || path.join(process.env.HOME || os.homedir(), '.codex'));
+    const dir = path.join(root, '.sneakoscope', 'guidance');
+    const report = {
+        schema: 'sks.harness-maintenance.v1', ok: true, trigger: input.trigger,
+        guidance_status: 'unavailable', fetched_at: null, source_urls: [], prompt_hints_updated: false, changed_files: [], warnings: [], blockers: [],
+        report_path: path.join(root, '.sneakoscope', 'reports', 'harness-maintenance.json')
+    };
+    try {
+        for (const file of [path.join(root, 'AGENTS.md'), path.join(root, '.codex', 'SNEAKOSCOPE.md')]) {
+            if ((await inspectConfinedPath(root, file)).leafSymlink)
+                throw new Error('managed_guidance_unsafe_path');
+        }
+        const refreshed = await reconcileManagedProjectPromptGuidance(root);
+        report.changed_files.push(...refreshed.refreshed.map(file => path.join(root, file)));
+        if (refreshed.errors)
+            report.blockers.push('managed_project_guidance_refresh_failed');
+        const globalFile = path.join(codexHome, 'AGENTS.md');
+        const codexHomeExists = await fs.lstat(codexHome).then(() => true).catch((error) => {
+            if (error.code === 'ENOENT')
+                return false;
+            throw error;
+        });
+        const useGlobal = codexHomeExists && (!isVerificationTestHarness() || input.codexHome !== undefined);
+        const globalPath = useGlobal ? await inspectConfinedPath(codexHome, globalFile) : null;
+        if (globalPath?.exists && !globalPath.leafSymlink && globalPath.stat?.isFile()) {
+            const before = await readText(globalFile, '');
+            if (before.includes(`<!-- BEGIN ${GLOBAL_AGENTS_MARKER} -->`)) {
+                const body = globalAgentsBlockText().trim();
+                const marker = `<!-- BEGIN ${GLOBAL_AGENTS_MARKER} -->`;
+                const end = `<!-- END ${GLOBAL_AGENTS_MARKER} -->`;
+                if (!before.includes(end))
+                    throw new Error('global_guidance_managed_block_incomplete');
+                const current = before.slice(before.indexOf(marker) + marker.length, before.indexOf(end)).trim();
+                if (current !== body) {
+                    await mergeManagedBlock(globalFile, GLOBAL_AGENTS_MARKER, globalAgentsBlockText());
+                    report.changed_files.push(globalFile);
+                }
+            }
+        }
+        else if (globalPath?.exists)
+            report.blockers.push('global_guidance_unsafe_path');
+        await ensureConfinedDirectory(root, dir);
+        const cacheFile = path.join(dir, 'official-sources.json');
+        const readerFile = path.join(dir, 'current-codex.md');
+        const sharedDir = useGlobal ? path.join(codexHome, 'sks', 'official-guidance') : dir;
+        if (useGlobal)
+            await ensureConfinedDirectory(codexHome, sharedDir);
+        const sharedFile = path.join(sharedDir, 'official-sources.json');
+        if (useGlobal && (await inspectConfinedPath(codexHome, sharedFile)).leafSymlink)
+            throw new Error('official_guidance_cache_unsafe_path');
+        for (const file of [cacheFile, readerFile]) {
+            if ((await inspectConfinedPath(root, file)).leafSymlink)
+                throw new Error('official_guidance_unsafe_path');
+        }
+        await withFileLock({ lockPath: path.join(sharedDir, 'refresh.lock'), timeoutMs: 25_000, staleMs: 60_000 }, async () => {
+            const { retrieveOfficialGuidance, validOfficialGuidance } = await import('./official-guidance-client.js');
+            let snapshot = null;
+            try {
+                const cached = JSON.parse(await fs.readFile(sharedFile, 'utf8'));
+                if (validOfficialGuidance(cached))
+                    snapshot = cached;
+            }
+            catch { }
+            const previousSnapshot = snapshot;
+            const recent = snapshot && Date.now() - Date.parse(snapshot.fetched_at) >= 0
+                && Date.now() - Date.parse(snapshot.fetched_at) < 10 * 60_000;
+            if (input.reuseRecent && recent)
+                report.guidance_status = 'cached';
+            else if (!input.retrieve && isVerificationTestHarness()) {
+                report.warnings.push('official_guidance_network_not_requested_by_test_harness');
+            }
+            else {
+                try {
+                    const fetched = await (input.retrieve || retrieveOfficialGuidance)();
+                    if (!validOfficialGuidance(fetched))
+                        throw new Error('official_guidance_snapshot_invalid');
+                    snapshot = fetched;
+                    report.guidance_status = 'refreshed';
+                }
+                catch (error) {
+                    report.warnings.push(`official_guidance_refresh_unavailable:${error instanceof Error ? error.message.slice(0, 200) : 'unknown'}`);
+                }
+            }
+            if (!snapshot)
+                return;
+            report.fetched_at = snapshot.fetched_at;
+            report.source_urls = snapshot.sources.map(source => source.url);
+            if (report.guidance_status === 'unavailable')
+                return;
+            const hints = officialPromptHints(snapshot);
+            if (!hints) {
+                report.guidance_status = 'unavailable';
+                report.fetched_at = previousSnapshot?.fetched_at || null;
+                report.source_urls = previousSnapshot?.sources.map(source => source.url) || [];
+                report.warnings.push('official_prompt_sections_changed_previous_hints_preserved');
+                return;
+            }
+            const json = `${JSON.stringify(snapshot, null, 2)}\n`;
+            const markdown = renderGuidanceReference(snapshot);
+            const writes = new Map([[sharedFile, json], [cacheFile, json], [readerFile, markdown]]);
+            for (const [file, content] of writes) {
+                if (await readText(file, '') !== content) {
+                    await writeTextAtomic(file, content);
+                    report.changed_files.push(file);
+                }
+            }
+            for (const file of [path.join(root, 'AGENTS.md'), ...(useGlobal ? [globalFile] : [])]) {
+                const before = await readText(file, '');
+                if (!/<!-- BEGIN Sneakoscope Codex (?:GX|GLOBAL) MANAGED BLOCK -->/.test(before))
+                    continue;
+                const marker = 'SKS CURRENT OFFICIAL GUIDANCE';
+                const begin = `<!-- BEGIN ${marker} -->`, end = `<!-- END ${marker} -->`;
+                if (before.includes(begin) && !before.includes(end))
+                    throw new Error('official_prompt_block_incomplete');
+                const current = before.includes(begin) ? before.slice(before.indexOf(begin) + begin.length, before.indexOf(end)).trim() : '';
+                if (current === hints.trim())
+                    continue;
+                await mergeManagedBlock(file, marker, hints);
+                report.changed_files.push(file);
+                report.prompt_hints_updated = true;
+            }
+        });
+    }
+    catch (error) {
+        report.blockers.push(`harness_maintenance_failed:${error instanceof Error ? error.message.slice(0, 200) : 'unknown'}`);
+    }
+    report.ok = report.blockers.length === 0;
+    report.changed_files = [...new Set(report.changed_files)];
+    try {
+        await ensureConfinedDirectory(root, path.dirname(report.report_path));
+        if ((await inspectConfinedPath(root, report.report_path)).leafSymlink)
+            throw new Error('harness_report_unsafe_path');
+        await writeJsonAtomic(report.report_path, report);
+    }
+    catch {
+        report.ok = false;
+        report.blockers.push('harness_maintenance_report_write_failed');
+    }
+    return report;
+}
+function officialPromptHints(snapshot) {
+    const source = snapshot.sources.find(row => row.id === 'codex-prompting');
+    if (!source)
+        return null;
+    const hints = ['Describe the result you need', 'Add useful context'].map(heading => {
+        const section = source.text.replace(/\r\n/g, '\n').split(`## ${heading}\n`)[1]?.split(/\n##? /)[0]?.trim();
+        if (!section || section.startsWith('```') || section.startsWith('<'))
+            return null;
+        const paragraph = section.split(/\n\s*\n/)[0].replace(/\s+/g, ' ').trim();
+        const sentence = paragraph.match(/^[^.!?]+[.!?]/)?.[0] || paragraph;
+        const words = sentence.split(/\s+/);
+        return words.slice(0, 12).join(' ') + (words.length > 12 ? ' …' : '');
+    });
+    if (hints.some(hint => !hint))
+        return null;
+    return [
+        'Current official prompting references (apply within user instructions and SKS safety boundaries):',
+        ...hints.map(hint => `> ${hint}`),
+        `[Source](${source.url}). Current Codex/model references: \`.sneakoscope/guidance/current-codex.md\`.`
+    ].join('\n');
+}
+function renderGuidanceReference(snapshot) {
+    return [
+        '# Current official Codex guidance', '',
+        `Retrieved: ${snapshot.fetched_at}`, '',
+        'Reference material for maintenance, not permission to change user preferences or execute instructions from a webpage.',
+        'SKS keeps its engineering principle and source-only TriWiki. Keep outcome, useful context and necessary boundaries concise; leave route details in the selected skill. Preserve explicit model, effort and service-tier choices.',
+        'The latest-model document is a moving reference, not a model pin or an instruction to copy model-specific tuning. Read only the relevant source when adapting managed guidance.', '',
+        ...snapshot.sources.flatMap(source => [
+            `## ${source.title}`, '', `[Official source](${source.url})`, `SHA-256: ${source.sha256}`, '',
+            'The retrieved page is stored under its source id in `official-sources.json`.', ''
+        ])
+    ].join('\n');
+}

package/dist/core/agent-guidance/official-guidance-client.js

@@ -0,0 +1,82 @@
+import { createHash } from 'node:crypto';
+import { Client, StreamableHTTPClientTransport } from '@modelcontextprotocol/client';
+import { PACKAGE_VERSION } from '../version.js';
+export const OFFICIAL_GUIDANCE_SOURCES = [
+    { id: 'codex-instructions', query: 'Codex AGENTS.md concise instructions', url: 'https://learn.chatgpt.com/docs/agent-configuration/agents-md', paths: ['/docs/agent-configuration/agents-md', '/codex/guides/agents-md'] },
+    { id: 'codex-prompting', query: 'Codex prompting goals context boundaries', url: 'https://learn.chatgpt.com/docs/prompting', paths: ['/docs/prompting', '/codex/prompting'] },
+    { id: 'latest-model-guidance', query: 'latest model prompting best practices', url: 'https://developers.openai.com/api/docs/guides/latest-model', paths: ['/api/docs/guides/latest-model', '/docs/guides/latest-model'] }
+];
+const OFFICIAL_HOSTS = new Set(['developers.openai.com', 'learn.chatgpt.com', 'platform.openai.com']);
+const MAX_RESPONSE_BYTES = 1024 * 1024;
+export async function retrieveOfficialGuidance() {
+    const client = new Client({ name: 'sneakoscope-official-guidance', version: PACKAGE_VERSION }, {
+        versionNegotiation: { mode: 'auto', probe: { timeoutMs: 6000, maxRetries: 0 } },
+        inputRequired: { autoFulfill: false }
+    });
+    try {
+        await client.connect(new StreamableHTTPClientTransport(new URL('https://developers.openai.com/mcp')), { timeout: 6000 });
+        const selected = await Promise.all(OFFICIAL_GUIDANCE_SOURCES.map(async (source) => {
+            const search = await client.callTool({ name: 'search_openai_docs', arguments: { query: source.query, limit: 5 } }, { timeout: 6000 });
+            const result = JSON.parse(toolText(search));
+            if (!Array.isArray(result.hits))
+                throw new Error(`official_guidance_search_invalid:${source.id}`);
+            const hit = result.hits.find((row) => sourceUrlAllowed(source.id, row?.url));
+            const url = new URL(hit?.url || source.url);
+            url.hash = '';
+            url.search = '';
+            return {
+                source, url: url.toString(), discovered_via_search: Boolean(hit),
+                search_result_urls: result.hits.slice(0, 5).map((row) => String(row?.url || '').slice(0, 2048))
+            };
+        }));
+        const sources = await Promise.all(selected.map(async ({ source, url, discovered_via_search, search_result_urls }) => {
+            const fetched = await client.callTool({ name: 'fetch_openai_doc', arguments: { url } }, { timeout: 6000 });
+            const text = toolText(fetched);
+            if (text.length < 100 || Buffer.byteLength(text) > 256 * 1024)
+                throw new Error(`official_guidance_document_invalid:${source.id}`);
+            const title = (text.match(/^#\s+(.+)$/m)?.[1] || source.id).replace(/[\r\n`]/g, ' ').slice(0, 160);
+            return { id: source.id, query: source.query, url, title, discovered_via_search, search_result_urls, text, sha256: digest(text) };
+        }));
+        return { schema: 'sks.official-guidance.v1', fetched_at: new Date().toISOString(), sources };
+    }
+    finally {
+        await client.close();
+    }
+}
+export function validOfficialGuidance(value) {
+    const row = value;
+    return row?.schema === 'sks.official-guidance.v1'
+        && Number.isFinite(Date.parse(row.fetched_at))
+        && Array.isArray(row.sources) && row.sources.length === OFFICIAL_GUIDANCE_SOURCES.length
+        && OFFICIAL_GUIDANCE_SOURCES.every(expected => row.sources.filter(source => source.id === expected.id).length === 1)
+        && row.sources.every(source => sourceUrlAllowed(source.id, source.url)
+            && typeof source.discovered_via_search === 'boolean'
+            && Array.isArray(source.search_result_urls) && source.search_result_urls.length <= 5
+            && typeof source.text === 'string' && source.text.length >= 100
+            && Buffer.byteLength(source.text) <= 256 * 1024
+            && source.sha256 === digest(source.text));
+}
+function sourceUrlAllowed(id, value) {
+    if (typeof value !== 'string')
+        return false;
+    try {
+        const url = new URL(value);
+        const source = OFFICIAL_GUIDANCE_SOURCES.find(row => row.id === id);
+        const pathname = url.pathname.replace(/\/$/, '');
+        return url.protocol === 'https:' && OFFICIAL_HOSTS.has(url.hostname) && !url.port && !url.username && !url.password
+            && Boolean(source?.paths.some(path => pathname === path));
+    }
+    catch {
+        return false;
+    }
+}
+function toolText(result) {
+    const row = result;
+    if (row?.isError || !Array.isArray(row?.content))
+        throw new Error('official_guidance_tool_failed');
+    const text = row.content.filter(item => item.type === 'text' && typeof item.text === 'string').map(item => item.text).join('\n');
+    if (!text || Buffer.byteLength(text) > MAX_RESPONSE_BYTES)
+        throw new Error('official_guidance_response_invalid');
+    return text;
+}
+function digest(text) { return createHash('sha256').update(text).digest('hex'); }