aptly 0.1.0

package/dist/src/diagnostics.js

@@ -0,0 +1,68 @@
+import { randomUUID } from 'node:crypto';
+import { VERSION } from './version.js';
+import { loadConfiguration, loadHostContext } from './config.js';
+import { assertPrivateStatePath } from './files.js';
+const platforms = new Set(['aix', 'darwin', 'freebsd', 'linux', 'openbsd', 'sunos', 'win32', 'android']);
+const architectures = new Set(['arm', 'arm64', 'ia32', 'loong64', 'mips', 'mipsel', 'ppc', 'ppc64', 'riscv64', 's390', 's390x', 'x64']);
+const envValue = (env, name) => {
+    try {
+        if (env === null || (typeof env !== 'object' && typeof env !== 'function'))
+            return undefined;
+        const descriptor = Object.getOwnPropertyDescriptor(env, name);
+        return descriptor && Object.hasOwn(descriptor, 'value') && typeof descriptor.value === 'string' ? descriptor.value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+/** Read-only local checks. No hosts are started and no API authentication probe is made. */
+export function collectDiagnostics({ env = process.env, node = process.versions.node, platform = process.platform, arch = process.arch, now = new Date(), reportId = randomUUID() } = {}) {
+    const checks = [];
+    const add = (id, status, code) => { checks.push({ id, status, code }); };
+    const version = typeof node === 'string' && /^\d{1,4}\.\d{1,4}\.\d{1,4}$/.test(node) ? node : '0.0.0';
+    add('node_runtime', Number(version.split('.')[0]) >= 24 ? 'ok' : 'error', Number(version.split('.')[0]) >= 24 ? 'node_supported' : 'node_unsupported');
+    const rawProvider = envValue(env, 'ROUTER_PROVIDER');
+    const provider = rawProvider === undefined ? 'fixture' : rawProvider;
+    add('classification_provider', ['fixture', 'decisions'].includes(provider) ? 'ok' : 'error', provider === 'fixture' ? 'provider_fixture' : provider === 'decisions' ? 'provider_decisions' : 'provider_invalid');
+    if (provider === 'fixture')
+        add('api_key', 'ok', 'key_not_required');
+    else {
+        const key = envValue(env, 'OPENAI_API_KEY');
+        const present = typeof key === 'string' && key.trim().length > 0;
+        add('api_key', present ? 'unknown' : 'error', present ? 'key_present_unverified' : 'key_missing');
+    }
+    const ledger = envValue(env, 'ROUTER_LEDGER_PATH');
+    if (!ledger)
+        add('ledger_location', provider === 'decisions' ? 'error' : 'unknown', 'ledger_not_configured');
+    else {
+        try {
+            assertPrivateStatePath(ledger);
+            add('ledger_location', 'ok', 'ledger_private_location_ready');
+        }
+        catch {
+            add('ledger_location', 'error', 'ledger_location_unavailable');
+        }
+    }
+    // Configuration and evidence contents are interpreted locally; never copied
+    // into the report. Paths, values, session identities and digests stay private.
+    const configuredPath = envValue(env, 'ROUTER_CONFIG_PATH');
+    const config = loadConfiguration({ ROUTER_CONFIG_PATH: configuredPath });
+    if (config.error)
+        add('operator_configuration', 'error', config.error === 'configuration_invalid' ? 'configuration_invalid' : 'configuration_unavailable');
+    else
+        add('operator_configuration', 'ok', configuredPath ? 'configuration_valid' : 'configuration_default_shadow');
+    if (!config.context_path)
+        add('host_evidence', 'unknown', 'host_evidence_not_configured');
+    else {
+        const loaded = loadHostContext(config.context_path);
+        const code = loaded.reason === 'host_evidence_loaded' ? 'host_evidence_loaded_unverified' : loaded.reason === 'context_sources_changed' ? 'host_evidence_changed' : 'host_evidence_unavailable';
+        add('host_evidence', code === 'host_evidence_loaded_unverified' ? 'unknown' : 'warning', code);
+    }
+    add('host_cli_versions', 'unknown', 'host_cli_not_probed');
+    const summary = { ok: 0, warning: 0, error: 0, unknown: 0 };
+    for (const check of checks)
+        summary[check.status]++;
+    return { schema_version: 1, report_id: reportId, generated_at: now.toISOString(), tool: { name: 'aptly', version: VERSION },
+        environment: { node: version, platform: typeof platform === 'string' && platforms.has(platform) ? platform : 'unknown', arch: typeof arch === 'string' && architectures.has(arch) ? arch : 'unknown' }, checks, summary,
+        privacy: { task_text: false, paths: false, environment_values: false, credentials: false, raw_errors: false }, network_requests: 0, paid_calls: 0 };
+}

package/dist/src/files.d.ts

@@ -0,0 +1,10 @@
+export declare function systemAliasAllowed(path: string, stat: {
+    uid: number;
+}, target: string, platform?: string): boolean;
+export declare function assertNoRedirectedAncestors(path: unknown): asserts path is string;
+export declare function assertPrivateStatePath(path: unknown): asserts path is string;
+/** Bounded nonblocking read; no raw path or parser message is part of its error. */
+export declare function readRegularFile(path: unknown, { privateFile, maxBytes }?: {
+    privateFile?: boolean;
+    maxBytes?: number;
+}): Buffer;

package/dist/src/files.js

@@ -0,0 +1,70 @@
+import { lstatSync, readlinkSync, openSync, fstatSync, readSync, closeSync, constants } from 'node:fs';
+import { dirname, isAbsolute, resolve } from 'node:path';
+import { errorCode } from './types.js';
+// macOS root-owned compatibility aliases are part of the OS filesystem layout,
+// not operator/config redirects. Arbitrary user-owned symlinks stay forbidden.
+export function systemAliasAllowed(path, stat, target, platform = process.platform) {
+    const aliases = { '/tmp': 'private/tmp', '/var': 'private/var', '/etc': 'private/etc' };
+    return platform === 'darwin' && stat.uid === 0 && Object.hasOwn(aliases, path) && aliases[path] === target;
+}
+export function assertNoRedirectedAncestors(path) {
+    if (typeof path !== 'string' || !isAbsolute(path))
+        throw new Error('unsafe_path');
+    let current = resolve(path);
+    while (true) {
+        const stat = lstatSync(current);
+        if (stat.isSymbolicLink() && !systemAliasAllowed(current, stat, readlinkSync(current)))
+            throw new Error('unsafe_path');
+        const parent = dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+}
+export function assertPrivateStatePath(path) {
+    if (typeof path !== 'string' || !isAbsolute(path))
+        throw new Error('private_state_path_required');
+    assertNoRedirectedAncestors(dirname(path));
+    const parent = lstatSync(dirname(path));
+    if (!parent.isDirectory() || (parent.mode & 0o077) || (process.getuid && parent.uid !== process.getuid()))
+        throw new Error('private_state_directory_required');
+    try {
+        const file = lstatSync(path);
+        if (!file.isFile() || file.isSymbolicLink() || (process.getuid && file.uid !== process.getuid()))
+            throw new Error('private_state_file_required');
+    }
+    catch (error) {
+        if (errorCode(error) !== 'ENOENT')
+            throw error;
+    }
+}
+/** Bounded nonblocking read; no raw path or parser message is part of its error. */
+export function readRegularFile(path, { privateFile = false, maxBytes = 65536 } = {}) {
+    let fd;
+    try {
+        assertNoRedirectedAncestors(path);
+        const before = lstatSync(path);
+        if (!before.isFile() || before.isSymbolicLink() || before.size > maxBytes)
+            throw new Error('unsafe_file');
+        fd = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
+        const stat = fstatSync(fd);
+        if (!stat.isFile() || stat.dev !== before.dev || stat.ino !== before.ino || stat.size > maxBytes ||
+            (privateFile && ((stat.mode & 0o077) || (process.getuid && stat.uid !== process.getuid()))))
+            throw new Error('unsafe_file');
+        const buffer = Buffer.alloc(maxBytes + 1);
+        let size = 0;
+        while (size < buffer.length) {
+            const count = readSync(fd, buffer, size, buffer.length - size, null);
+            if (!count)
+                break;
+            size += count;
+        }
+        if (size > maxBytes)
+            throw new Error('unsafe_file');
+        return buffer.subarray(0, size);
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+    }
+}

package/dist/src/hook.d.ts

@@ -0,0 +1,20 @@
+import type { UnknownRecord, RoutingInput, RoutingPolicy } from './types.ts';
+export interface HookOptions {
+    client?: unknown;
+    event?: unknown;
+    recommendation?: unknown;
+    mode?: string;
+    compatibilityVerified?: boolean;
+    policy?: RoutingPolicy;
+}
+export interface HookOutput {
+    hookSpecificOutput?: {
+        hookEventName: 'PreToolUse';
+        permissionDecision?: 'allow';
+        updatedInput: UnknownRecord;
+    };
+}
+/** Extract only a task label and safe structural features, never prompt/message/transcript. */
+export declare function hookInput({ client, event, policy }?: HookOptions): RoutingInput | null;
+/** Native Hook JSON, defaulting to no permission or argument intervention. */
+export declare function hookOutput({ client, event, recommendation, mode, compatibilityVerified, policy }?: HookOptions): HookOutput;

package/dist/src/hook.js

@@ -0,0 +1,102 @@
+import { createHash } from 'node:crypto';
+import { defaultPolicy } from './core.js';
+import { isSupportedProfile } from './catalog.js';
+const own = (value, key) => Object.hasOwn(value, key);
+const object = (value) => value !== null && typeof value === 'object' && !Array.isArray(value) &&
+    [Object.prototype, null].includes(Object.getPrototypeOf(value));
+function target(client, event) {
+    if ((client !== 'codex' && client !== 'claude') || !object(event) ||
+        event.hook_event_name !== 'PreToolUse')
+        return null;
+    if (!(client === 'codex' ? ['spawn_agent', 'collaborationspawn_agent', 'Agent'] : ['Agent']).includes(typeof event.tool_name === 'string' ? event.tool_name : ''))
+        return null;
+    const id = event.tool_use_id ?? event.tool_call_id;
+    if (typeof id !== 'string' || !id.trim() || id.length > 512)
+        return null;
+    let input = event.tool_input;
+    // Claude 2.1.314 expands an object placeholder as a JSON string, while
+    // Codex preserves its JSON type. Decode this bounded transport form only
+    // for Claude; neither input nor parse errors are logged or returned.
+    if (typeof input === 'string') {
+        if (client !== 'claude' || Buffer.byteLength(input) > 16384)
+            return null;
+        try {
+            input = JSON.parse(input);
+        }
+        catch {
+            return null;
+        }
+    }
+    if (!object(input))
+        return null;
+    return { client, event, input, id };
+}
+function constraints(client, input) {
+    return {
+        model_pinned: own(input, 'model'),
+        effort_pinned: ['effort', 'reasoning_effort', 'model_reasoning_effort'].some(k => own(input, k)),
+        role_pinned: ['resume', 'resume_agent', 'agent_id'].some(k => own(input, k)) || (client === 'claude' ? input.subagent_type !== 'general-purpose' :
+            own(input, 'agent_type') || own(input, 'role')),
+        fork_inherits: client === 'codex' ? input.fork_turns !== 'none' || own(input, 'fork_context') : input.subagent_type === 'fork',
+        // Native tool arguments do not prove the source or precedence of settings.
+        provenance_verified: false,
+    };
+}
+/** Extract only a task label and safe structural features, never prompt/message/transcript. */
+export function hookInput({ client, event, policy = defaultPolicy } = {}) {
+    const found = target(client, event);
+    if (!found)
+        return null;
+    const summary = client === 'claude' ? found.input.description : found.input.task_name;
+    if (typeof summary !== 'string' || !summary.trim() || Buffer.byteLength(summary) > 4000)
+        return null;
+    const request_id = createHash('sha256').update(JSON.stringify([
+        found.client, found.event.session_id ?? null, found.id,
+    ])).digest('hex');
+    return {
+        request_id, client: found.client,
+        task: { summary, operation: 'analysis', context_sufficient: false },
+        eligible_profile_ids: policy.profiles.filter(p => p.client === client).map(p => p.id),
+        constraints: constraints(found.client, found.input),
+    };
+}
+/** Native Hook JSON, defaulting to no permission or argument intervention. */
+export function hookOutput({ client, event, recommendation, mode = 'shadow', compatibilityVerified = false, policy = defaultPolicy } = {}) {
+    if (mode !== 'apply' || compatibilityVerified !== true)
+        return {};
+    const found = target(client, event);
+    if (!found || !object(recommendation) || recommendation.status !== 'recommended')
+        return {};
+    const pins = constraints(found.client, found.input);
+    if (['model_pinned', 'effort_pinned', 'role_pinned', 'fork_inherits'].some(k => pins[k]))
+        return {};
+    const profile = policy.profiles.find(p => p.client === client && p.id === recommendation.profile_id);
+    if (!profile || !isSupportedProfile(profile) || recommendation.policy_version !== policy.version ||
+        recommendation.catalog_version !== policy.catalog_version)
+        return {};
+    // Select executable values solely from the trusted catalog. Reject conflicting
+    // copies instead of letting a provider supply arbitrary model/effort strings.
+    if (own(recommendation, 'model') || own(recommendation, 'reasoning_effort') || own(recommendation, 'effort'))
+        return {};
+    const suppliedProfile = recommendation.profile;
+    if (!object(suppliedProfile) || Object.keys(suppliedProfile).length !== Object.keys(profile).length ||
+        Object.entries(profile).some(([key, value]) => suppliedProfile[key] !== value))
+        return {};
+    let updatedInput;
+    try {
+        updatedInput = structuredClone(found.input);
+    }
+    catch {
+        return {};
+    }
+    updatedInput.model = profile.model;
+    if (client === 'codex')
+        updatedInput.reasoning_effort = profile.reasoning_effort;
+    return { hookSpecificOutput: {
+            hookEventName: 'PreToolUse',
+            // Codex requires allow with updatedInput. Claude permits input-only
+            // replacement, retaining the host's normal permission decision path.
+            ...(client === 'codex' ? { permissionDecision: 'allow' } : {}),
+            updatedInput,
+        } };
+}

package/dist/src/inspect.d.ts

@@ -0,0 +1,31 @@
+import type { Client } from './types.ts';
+import type { EvidenceState } from './provenance.ts';
+interface SettingStates {
+    model: EvidenceState;
+    effort: EvidenceState;
+}
+export interface InspectionOptions {
+    client?: unknown;
+    cwd?: unknown;
+    files?: unknown;
+    environment?: unknown;
+    clientVersion?: unknown;
+}
+export interface InspectionResult {
+    client: Client | 'unknown';
+    client_version: string;
+    layers: Array<SettingStates & {
+        source: string;
+    }>;
+    environment: Record<string, 'set' | 'unset' | 'unknown'>;
+    host_extensions: 'unknown';
+    evidence_verified: false;
+    reason: 'effective_host_context_unobserved';
+}
+/**
+ * Explain only explicitly selected files and a caller-supplied env snapshot.
+ * No secret values, paths, file bodies or parse errors leave this function.
+ * File absence is local evidence about that file, not source completeness.
+ */
+export declare function explainSettings({ client, cwd, files, environment, clientVersion }?: InspectionOptions): InspectionResult;
+export {};

package/dist/src/inspect.js

@@ -0,0 +1,219 @@
+// Read only explicitly supplied configuration files. This is a redacted local
+// explanation, never evidence of the effective settings of a running host.
+import { constants, closeSync, fstatSync, lstatSync, openSync, readSync } from 'node:fs';
+import { isAbsolute, resolve } from 'node:path';
+import { parse as parseToml } from 'smol-toml';
+import { provenanceRequirements } from './provenance.js';
+import { assertNoRedirectedAncestors } from './files.js';
+import { errorCode } from './types.js';
+const MAX_BYTES = 65536;
+const MAX_FILES = 64;
+const own = (value, key) => Object.hasOwn(value, key);
+const plain = (value) => value !== null && typeof value === 'object' && !Array.isArray(value) &&
+    [Object.prototype, null].includes(Object.getPrototypeOf(value));
+const unknown = () => ({ model: 'unknown', effort: 'unknown' });
+const unset = () => ({ model: 'unset', effort: 'unset' });
+const mergeState = (a, b) => a === 'pinned' || b === 'pinned' ? 'pinned' : a === 'unknown' || b === 'unknown' ? 'unknown' : 'unset';
+const merge = (a, b) => ({ model: mergeState(a.model, b.model), effort: mergeState(a.effort, b.effort) });
+const allowedFiles = {
+    codex: ['role', 'subagent_defaults', 'profile', 'project', 'user', 'system', 'managed'],
+    claude: ['agent', 'settings_flag', 'local', 'project', 'user', 'managed'],
+};
+const MODEL_ENV = new Set(['CODEX_MODEL', 'CLAUDE_CODE_SUBAGENT_MODEL', 'CLAUDE_CODE_SUBAGENT_MODEL_FORCE',
+    'ANTHROPIC_MODEL', 'ANTHROPIC_SMALL_FAST_MODEL', 'ANTHROPIC_DEFAULT_HAIKU_MODEL',
+    'ANTHROPIC_DEFAULT_SONNET_MODEL', 'ANTHROPIC_DEFAULT_OPUS_MODEL', 'ANTHROPIC_DEFAULT_FABLE_MODEL']);
+const EFFORT_ENV = new Set(['CODEX_REASONING_EFFORT', 'CLAUDE_CODE_EFFORT_LEVEL', 'CLAUDE_CODE_MAX_EFFORT_LEVEL']);
+const CLAUDE_MODEL_POLICIES = ['availableModels', 'deniedModels', 'deniedModelPatterns', 'availableModelsMatch', 'enforceAvailableModels'];
+const CODEX_MODEL_POLICIES = ['allowed_models', 'denied_models', 'model_requirements'];
+function secretPath(path) {
+    return path.split(/[\\/]+/).some(part => /^(?:\.env(?:\..*)?|\.ssh|\.aws|\.gnupg|id_rsa|id_ed25519)$/i.test(part) ||
+        /(?:^|[._-])(?:auth|oauth|credentials?|secrets?|tokens?)(?:[._-]|$)/i.test(part) || /^Bitwarden CLI$/i.test(part));
+}
+function explicitFile(path) {
+    let fd;
+    try {
+        assertNoRedirectedAncestors(path);
+        const before = lstatSync(path);
+        if (!before.isFile() || before.size > MAX_BYTES)
+            return { status: 'unknown' };
+        fd = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
+        const current = fstatSync(fd);
+        if (!current.isFile() || current.size > MAX_BYTES || current.dev !== before.dev || current.ino !== before.ino)
+            return { status: 'unknown' };
+        const buffer = Buffer.alloc(MAX_BYTES + 1);
+        let bytes = 0;
+        while (bytes < buffer.length) {
+            const count = readSync(fd, buffer, bytes, buffer.length - bytes, null);
+            if (!count)
+                break;
+            bytes += count;
+        }
+        if (bytes > MAX_BYTES)
+            return { status: 'unknown' };
+        const text = buffer.subarray(0, bytes).toString('utf8');
+        if (text.includes('\uFFFD'))
+            return { status: 'unknown' };
+        return { status: 'read', text };
+    }
+    catch (error) {
+        return { status: errorCode(error) === 'ENOENT' ? 'missing' : 'unknown' };
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+    }
+}
+// Intentionally a strict frontmatter subset. YAML anchors, lists, multiline
+// scalars, duplicate fields and nested structures stay unknown rather than
+// pretending to resolve a host's full YAML parser behavior.
+function frontmatter(text) {
+    const lines = text.replace(/^\uFEFF/, '').split(/\r?\n/);
+    if (lines[0] !== '---')
+        throw new Error('unknown_frontmatter');
+    const end = lines.indexOf('---', 1);
+    if (end < 0)
+        throw new Error('unknown_frontmatter');
+    const data = {};
+    const known = new Set(['name', 'description', 'model', 'effort', 'model_reasoning_effort', 'tools', 'disallowedTools',
+        'permissionMode', 'maxTurns', 'memory', 'background', 'isolation', 'color', 'initialPrompt', 'context',
+        'user-invocable', 'disable-model-invocation', 'argument-hint', 'allowed-tools']);
+    for (const line of lines.slice(1, end)) {
+        if (!line.trim() || line.trimStart().startsWith('#'))
+            continue;
+        const match = /^([A-Za-z][A-Za-z0-9_-]*):[ \t]*(.*)$/.exec(line);
+        if (!match || !known.has(match[1]) || own(data, match[1]))
+            throw new Error('unknown_frontmatter');
+        const key = match[1], raw = match[2].trim();
+        if (!raw || /^(?:[|>&*!\[{]|---$|\.\.\.$)/.test(raw) || /\s[&*!][A-Za-z]/.test(raw))
+            throw new Error('unknown_frontmatter');
+        if (raw.startsWith('"'))
+            data[key] = JSON.parse(raw);
+        else if (raw.startsWith("'")) {
+            if (!/^'(?:[^']|'')*'$/.test(raw))
+                throw new Error('unknown_frontmatter');
+            data[key] = raw.slice(1, -1).replace(/''/g, "'");
+        }
+        else {
+            if (/^[\[\]{}]|:\s/.test(raw))
+                throw new Error('unknown_frontmatter');
+            data[key] = raw.split(/\s+#/)[0].trim();
+        }
+        if (['model', 'effort', 'model_reasoning_effort'].includes(key) &&
+            (typeof data[key] !== 'string' || !data[key] || /^(?:null|~)$/i.test(data[key])))
+            throw new Error('unknown_frontmatter');
+    }
+    return data;
+}
+function present(data, names) { return names.some(key => own(data, key)); }
+function summarize(client, data) {
+    if (!plain(data))
+        return unknown();
+    let result = unset();
+    if (own(data, 'model'))
+        result.model = 'pinned';
+    if (present(data, client === 'codex' ? ['model_reasoning_effort', 'reasoning_effort', 'effort'] : ['effort', 'effortLevel', 'maxEffortLevel']))
+        result.effort = 'pinned';
+    if (present(data, client === 'codex' ? CODEX_MODEL_POLICIES : CLAUDE_MODEL_POLICIES))
+        result.model = 'pinned';
+    if (own(data, 'env')) {
+        const env = data.env;
+        if (!plain(env))
+            result = merge(result, unknown());
+        else {
+            if ([...MODEL_ENV].some(key => own(env, key)))
+                result.model = 'pinned';
+            if ([...EFFORT_ENV].some(key => own(env, key)))
+                result.effort = 'pinned';
+        }
+    }
+    if (client === 'codex' && own(data, 'agents')) {
+        if (!plain(data.agents))
+            return merge(result, unknown());
+        const agents = data.agents;
+        if (own(agents, 'default_subagent_model'))
+            result.model = 'pinned';
+        if (own(agents, 'default_subagent_reasoning_effort'))
+            result.effort = 'pinned';
+        for (const [key, value] of Object.entries(agents)) {
+            if (['default_subagent_model', 'default_subagent_reasoning_effort', 'enabled', 'max_threads',
+                'max_concurrent_threads_per_session', 'interrupt_message'].includes(key))
+                continue;
+            if (!plain(value)) {
+                result = merge(result, unknown());
+                continue;
+            }
+            if (own(value, 'model'))
+                result.model = 'pinned';
+            if (present(value, ['model_reasoning_effort', 'reasoning_effort', 'effort']))
+                result.effort = 'pinned';
+            if (own(value, 'config_file'))
+                result = merge(result, unknown());
+        }
+    }
+    if (client === 'claude' && own(data, 'modelSettings')) {
+        if (!plain(data.modelSettings))
+            return merge(result, { model: 'unset', effort: 'unknown' });
+        for (const settings of Object.values(data.modelSettings)) {
+            if (!plain(settings))
+                result = merge(result, { model: 'unset', effort: 'unknown' });
+            else if (present(settings, ['effort', 'effortLevel', 'maxEffortLevel']))
+                result.effort = 'pinned';
+        }
+    }
+    return result;
+}
+function inspectOne(client, cwd, descriptor) {
+    if (!plain(descriptor) || typeof descriptor.path !== 'string' || !descriptor.path ||
+        descriptor.path.includes('\0') || Buffer.byteLength(descriptor.path) > 4096 ||
+        typeof cwd !== 'string' || !isAbsolute(cwd))
+        return unknown();
+    const path = resolve(cwd, descriptor.path);
+    if (secretPath(path))
+        return unknown();
+    const format = /\.([^.\\/]+)$/.exec(path)?.[1]?.toLowerCase();
+    if ((!format || !['json', 'toml', 'md'].includes(format)))
+        return unknown();
+    const file = explicitFile(path);
+    if (file.status === 'missing')
+        return unset();
+    if (file.status !== 'read')
+        return unknown();
+    try {
+        const data = format === 'json' ? JSON.parse(file.text) : format === 'toml' ? parseToml(file.text) : frontmatter(file.text);
+        return summarize(client, data);
+    }
+    catch {
+        return unknown();
+    }
+}
+/**
+ * Explain only explicitly selected files and a caller-supplied env snapshot.
+ * No secret values, paths, file bodies or parse errors leave this function.
+ * File absence is local evidence about that file, not source completeness.
+ */
+export function explainSettings({ client, cwd = process.cwd(), files = [], environment = {}, clientVersion } = {}) {
+    const supported = client === 'codex' || client === 'claude';
+    const safeClient = supported ? client : 'unknown';
+    const requirements = supported ? provenanceRequirements[client] : { layers: [], environment: [] };
+    const seen = new Map();
+    if (supported && Array.isArray(files) && files.length <= MAX_FILES) {
+        for (const descriptor of files) {
+            if (!plain(descriptor) || (typeof descriptor.source !== 'string' || !allowedFiles[client].includes(descriptor.source)))
+                continue;
+            const value = inspectOne(client, cwd, descriptor);
+            seen.set(descriptor.source, seen.has(descriptor.source) ? merge(seen.get(descriptor.source), value) : value);
+        }
+    }
+    const env = {};
+    for (const name of requirements.environment)
+        env[name] = environment === null || typeof environment !== 'object' || Array.isArray(environment) ? 'unknown' : own(environment, name) ? 'set' : 'unset';
+    return {
+        client: safeClient,
+        client_version: typeof clientVersion === 'string' && /^\d{1,4}\.\d{1,4}\.\d{1,4}(?:-[A-Za-z0-9.-]{1,32})?$/.test(clientVersion) ? clientVersion : 'unknown',
+        layers: requirements.layers.map(source => ({ source, ...(seen.get(source) ?? unknown()) })),
+        environment: env,
+        host_extensions: 'unknown',
+        evidence_verified: false,
+        reason: 'effective_host_context_unobserved',
+    };
+}

package/dist/src/model-info.d.ts

@@ -0,0 +1,32 @@
+export interface ModelFact {
+    client: 'codex' | 'claude';
+    model: string;
+    description: string;
+}
+export interface ModelInfoSnapshot {
+    schema_version: 1;
+    fetched_at: string;
+    sources: Array<{
+        url: string;
+        sha256: string;
+    }>;
+    facts: ModelFact[];
+}
+export type ModelInfoStatus = 'bundled' | 'fresh' | 'stale' | 'unavailable' | 'invalid';
+export interface LoadedModelInfo {
+    facts: ModelFact[];
+    status: ModelInfoStatus;
+}
+export declare const modelInfoUrls: readonly ["https://code.claude.com/docs/en/model-config.md", "https://learn.chatgpt.com/docs/models.md"];
+/** Fixed endpoints only. Refresh is explicit; request-time recommendation never fetches pages. */
+export declare function fetchModelInfo({ fetchImpl, now, timeoutMs }?: {
+    fetchImpl?: typeof fetch;
+    now?: number;
+    timeoutMs?: number;
+}): Promise<ModelInfoSnapshot>;
+/** Unknown cache data never becomes execution authority; unusable caches use bundled facts. */
+export declare function loadModelInfo(path: unknown, { now }?: {
+    now?: number;
+}): LoadedModelInfo;
+/** Atomic replacement in an existing owner-private directory; unrelated files are never overwritten. */
+export declare function saveModelInfo(path: string, snapshot: ModelInfoSnapshot): void;