@namewta/speculo 2.0.5 → 2.1.0

package/skills-hub/system/optimize-codex-config/scripts/lib/document.mjs

@@ -0,0 +1,166 @@
+// Full grammar parsing; range edits, not a handwritten TOML/JSON parser.
+import { isDeepStrictEqual } from 'node:util';
+import { parseTOML, getStaticTOMLValue, parseTree, modify, applyEdits } from '../vendor/parsers.mjs';
+
+const forbidden = new Set(['__proto__', 'prototype', 'constructor']);
+export class ConfigError extends Error {
+  constructor(code) { super(code); this.code = code; }
+}
+const keys = node => node.keys.map(key => key.type === 'TOMLBare' ? key.name : key.value);
+const prefix = (a, b) => a.length <= b.length && a.every((v, i) => v === b[i]);
+const same = (a, b) => a.length === b.length && prefix(a, b);
+const keyText = path => path.map(key => JSON.stringify(key)).join('.');
+export function at(value, path) {
+  for (const key of path) {
+    if (value === null || typeof value !== 'object' || !Object.hasOwn(value, key)) return undefined;
+    value = value[key];
+  }
+  return value;
+}
+function checkedPath(path) {
+  if (!Array.isArray(path) || !path.length || path.some(k => typeof k !== 'string' || forbidden.has(k))) {
+    throw new ConfigError('unsafe_key');
+  }
+}
+function set(value, path, replacement) {
+  let cursor = value;
+  for (const key of path.slice(0, -1)) {
+    if (!Object.hasOwn(cursor, key)) cursor[key] = {};
+    if (!cursor[key] || typeof cursor[key] !== 'object' || Array.isArray(cursor[key]) || cursor[key] instanceof Date) {
+      throw new ConfigError('parent_type_conflict');
+    }
+    cursor = cursor[key];
+  }
+  cursor[path.at(-1)] = replacement;
+}
+function tomlNodes(ast) {
+  const entries = [], tables = [], inline = [];
+  function walk(nodes, base = []) {
+    for (const node of nodes) {
+      if (node.type === 'TOMLTable') {
+        const path = node.resolvedKey;
+        if (path.some(k => forbidden.has(k))) throw new ConfigError('unsafe_key');
+        tables.push({ node, path }); walk(node.body, path);
+      } else if (node.type === 'TOMLKeyValue') {
+        const path = [...base, ...keys(node.key)];
+        if (path.some(k => forbidden.has(k))) throw new ConfigError('unsafe_key');
+        entries.push({ node, path });
+        walkValue(node.value, path);
+      }
+    }
+  }
+  function walkValue(node, path) {
+    if (node.type === 'TOMLInlineTable') { inline.push({ node, path }); walk(node.body, path); }
+    if (node.type === 'TOMLArray') node.elements.forEach((child, i) => walkValue(child, [...path, i]));
+  }
+  walk(ast.body[0].body);
+  return { entries, tables, inline };
+}
+function checkJSONTree(node, depth = 0) {
+  if (depth > 64) throw new ConfigError('nesting_limit');
+  if (node.type === 'object') {
+    const seen = new Set();
+    for (const property of node.children ?? []) {
+      const name = property.children[0].value;
+      if (forbidden.has(name)) throw new ConfigError('unsafe_key');
+      if (seen.has(name)) throw new ConfigError('duplicate_json_key');
+      seen.add(name);
+    }
+  }
+  for (const child of node.children ?? []) checkJSONTree(child, depth + 1);
+}
+export function parseDocument(text, format) {
+  if (typeof text !== 'string' || Buffer.byteLength(text) > 1024 * 1024) throw new ConfigError('document_size_limit');
+  try {
+    if (format === 'toml') {
+      const ast = parseTOML(text, { tomlVersion: '1.0.0' });
+      const nodes = tomlNodes(ast); // Reject dangerous object keys before static evaluation.
+      return { text, format, ast, ...nodes, value: getStaticTOMLValue(ast) };
+    }
+    if (format !== 'json') throw new ConfigError('unsupported_format');
+    const value = JSON.parse(text); // Deliberately reject JSONC/trailing commas.
+    const errors = [];
+    const ast = parseTree(text, errors, { allowTrailingComma: false, disallowComments: true });
+    if (errors.length || !ast || ast.type !== 'object') throw new ConfigError('invalid_json_object');
+    checkJSONTree(ast);
+    return { text, format, ast, value };
+  } catch (error) {
+    // Parser errors can quote secrets: expose a code, never the original message.
+    if (error instanceof ConfigError) throw error;
+    throw new ConfigError(format === 'toml' ? 'invalid_toml' : 'invalid_json');
+  }
+}
+function literal(value) {
+  if (typeof value === 'string' || typeof value === 'boolean') return JSON.stringify(value);
+  if (typeof value === 'number' && Number.isSafeInteger(value)) return String(value);
+  if (Array.isArray(value)) return '[' + value.map(literal).join(', ') + ']';
+  throw new ConfigError('unsupported_replacement_type');
+}
+function lineEnd(text, offset) {
+  const end = text.indexOf('\n', offset);
+  return end < 0 ? text.length : end + 1;
+}
+function replaceRanges(text, changes) {
+  const sorted = changes.sort((a, b) => b.start - a.start);
+  let last = text.length + 1;
+  for (const edit of sorted) {
+    if (edit.end > last) throw new ConfigError('overlapping_edits');
+    text = text.slice(0, edit.start) + edit.text + text.slice(edit.end);
+    last = edit.start;
+  }
+  return text;
+}
+function tomlPatch(doc, path, value) {
+  const { text, entries, tables, inline } = doc;
+  const serialized = literal(value);
+  const exact = entries.find(entry => same(entry.path, path));
+  if (exact) return text.slice(0, exact.node.value.range[0]) + serialized + text.slice(exact.node.value.range[1]);
+
+  // A table-valued exporter may be replaced only within its own subtree. The
+  // semantic postcondition below proves that unrelated tables were preserved.
+  const subtree = tables.filter(table => prefix(path, table.path));
+  if (subtree.length) {
+    if (subtree.some(table => table.node.kind === 'array')) throw new ConfigError('array_table_replacement_blocked');
+    const edits = [];
+    for (const table of subtree) {
+      edits.push({ start: table.node.range[0], end: table.node.key.range[1] + 1, text: '' });
+      for (const child of table.node.body) edits.push({ start: child.range[0], end: child.range[1], text: '' });
+    }
+    const without = parseDocument(replaceRanges(text, edits), 'toml');
+    return tomlPatch(without, path, value);
+  }
+  // Object represented by dotted keys without an explicit table header.
+  const dotted = entries.filter(entry => prefix(path, entry.path));
+  if (dotted.length) {
+    const outer = dotted.filter(entry => !dotted.some(other => other !== entry && prefix(other.path, entry.path)));
+    if (outer.some(entry => entry.node.parent.type === 'TOMLInlineTable')) throw new ConfigError('inline_subtree_replacement_blocked');
+    return tomlPatch(parseDocument(replaceRanges(text, outer.map(entry => ({ start: entry.node.range[0], end: entry.node.range[1], text: '' }))), 'toml'), path, value);
+  }
+  const inlined = inline.filter(entry => prefix(entry.path, path)).sort((a, b) => b.path.length - a.path.length)[0];
+  if (inlined) {
+    const pos = inlined.node.range[1] - 1;
+    const insertion = (inlined.node.body.length ? ', ' : ' ') + keyText(path.slice(inlined.path.length)) + ' = ' + serialized + ' ';
+    return text.slice(0, pos) + insertion + text.slice(pos);
+  }
+  const parent = tables.filter(entry => entry.node.kind === 'standard' && prefix(entry.path, path)).sort((a, b) => b.path.length - a.path.length)[0];
+  const eol = text.includes('\r\n') ? '\r\n' : '\n';
+  const pos = parent ? lineEnd(text, parent.node.key.range[1] + 1) : 0;
+  const relative = parent ? path.slice(parent.path.length) : path;
+  return text.slice(0, pos) + (pos && !text.slice(0, pos).endsWith('\n') ? eol : '') + keyText(relative) + ' = ' + serialized + eol + text.slice(pos);
+}
+export function patchDocument(text, format, operations) {
+  let doc = parseDocument(text, format);
+  for (const { path, value } of operations) {
+    checkedPath(path);
+    if (isDeepStrictEqual(at(doc.value, path), value)) continue;
+    const expected = structuredClone(doc.value);
+    set(expected, path, structuredClone(value));
+    const changed = format === 'toml' ? tomlPatch(doc, path, value) : applyEdits(doc.text, modify(doc.text, path, value, {
+      formattingOptions: { insertSpaces: true, tabSize: 2, eol: doc.text.includes('\r\n') ? '\r\n' : '\n' },
+    }));
+    const next = parseDocument(changed, format);
+    if (!isDeepStrictEqual(next.value, expected)) throw new ConfigError('semantic_postcondition_failed');
+    doc = next;
+  }
+  return doc.text;
+}

package/skills-hub/system/optimize-codex-config/scripts/lib/inspect.mjs

@@ -0,0 +1,211 @@
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { readdir } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { isDeepStrictEqual } from 'node:util';
+import { definition as codex } from '../adapters/codex.mjs';
+import { definition as claude, disabledEnvironment } from '../adapters/claude.mjs';
+import { ConfigError, parseDocument, at } from './document.mjs';
+import { absolute, safePath, metadata, readBounded, fingerprint, sha256, canonical } from './io.mjs';
+
+export const adapters = { codex, claude };
+// Only built-in read-only system paths use macOS's canonical /private/etc.
+// User homes and project paths retain safePath's strict no-symlink contract.
+export function codexSystemPaths(platform = process.platform) {
+  if (platform === 'win32') return { defaults: [], managed: [] };
+  const root = platform === 'darwin' ? '/private/etc/codex' : '/etc/codex';
+  return { defaults: [root + '/config.toml'],
+    managed: [root + '/managed_config.toml', root + '/requirements.toml'] };
+}
+export const rendererSource = fileURLToPath(new URL('../statusline/claude-statusline.mjs', import.meta.url));
+const specKeys = ['client', 'scope', 'project', 'codex_home', 'claude_home', 'mode', 'replace_statusline', 'evidence'];
+export function normalizeSpec(input = {}, env = process.env) {
+  if (Object.keys(input).some(key => !specKeys.includes(key))) throw new ConfigError('unknown_spec_key');
+  const result = {
+    client: input.client ?? 'all', scope: input.scope ?? 'user',
+    project: input.project ? absolute(input.project) : null,
+    codex_home: absolute(input.codex_home ?? env.CODEX_HOME ?? join(homedir(), '.codex')),
+    claude_home: absolute(input.claude_home ?? env.CLAUDE_CONFIG_DIR ?? join(homedir(), '.claude')),
+    mode: input.mode ?? 'local-private', replace_statusline: input.replace_statusline ?? false,
+    evidence: input.evidence ? absolute(input.evidence) : null,
+  };
+  if (!['all', 'codex', 'claude'].includes(result.client) || !['user', 'project'].includes(result.scope)
+      || !['local-private', 'privacy-only', 'statusline-only'].includes(result.mode)
+      || typeof result.replace_statusline !== 'boolean') throw new ConfigError('invalid_selection');
+  if (result.scope === 'project' && !result.project) throw new ConfigError('project_required');
+  return result;
+}
+export const selectedClients = spec => spec.client === 'all' ? ['codex', 'claude'] : [spec.client];
+export function targetFor(spec, client) {
+  const root = spec.scope === 'user' ? spec[client + '_home'] : join(spec.project, '.' + client);
+  const filename = client === 'claude' && spec.scope === 'project' ? 'settings.local.json' : adapters[client].filename;
+  return { client, root, path: join(root, filename), format: adapters[client].format };
+}
+export async function rulesFor(spec, client) {
+  const target = targetFor(spec, client);
+  const source = await readBounded(rendererSource);
+  const runtime = join(target.root, '.wta-ai-cli-config', 'runtime', 'claude-statusline-' + source.sha256.slice(0, 16) + '.mjs');
+  const rules = [
+    ...(spec.mode !== 'statusline-only' ? adapters[client].privacy : []),
+    ...(spec.mode !== 'privacy-only' ? adapters[client].statusline(process.execPath, runtime) : []),
+  ];
+  return { rules, runtime, source, target };
+}
+const nonemptyOff = new Set(['CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC', 'DISABLE_TELEMETRY']);
+function envMatches(key, value) {
+  if (nonemptyOff.has(key)) return typeof value === 'string' && value.length > 0;
+  return value === disabledEnvironment[key];
+}
+export function environmentState(env) {
+  const observed = Object.keys(disabledEnvironment).map(key => ({
+    key, present: Object.hasOwn(env, key), matches_policy: Object.hasOwn(env, key) ? envMatches(key, env[key]) : null,
+  }));
+  // Hash only explicitly named control values. Never enumerate process secrets.
+  const digest = sha256(canonical(Object.fromEntries(Object.keys(disabledEnvironment).filter(k => Object.hasOwn(env, k)).map(k => [k, env[k]]))));
+  return { digest: sha256(digest + (env.NODE_OPTIONS ? ':node-options-present' : ':clean-node-options')), observed };
+}
+function safeValue(value, desired) {
+  if (value === undefined) return '<absent>';
+  if (isDeepStrictEqual(value, desired)) return desired;
+  if (typeof value === 'boolean' || ['none', 'otlp', 'statsig', '0', '1', 'true', 'false'].includes(value)) return value;
+  // Config strings and objects can contain arbitrary secrets, even at innocent keys.
+  return '<redacted-existing-value>';
+}
+export const previewValue = safeValue;
+async function layer(path, label, format, files) {
+  try {
+    const file = await readBounded(path);
+    const parsed = parseDocument(file.exists ? file.text : format === 'toml' ? '' : '{}', format);
+    const entry = { path, label, ...fingerprint(file), value: parsed.value, text: file.text, format };
+    files.push(entry); return entry;
+  } catch (error) {
+    const entry = { path, label, error: error.code ?? 'read_failed', format };
+    files.push(entry); return entry;
+  }
+}
+async function managedLayers(client, files) {
+  const paths = client === 'codex'
+    ? codexSystemPaths().managed
+    : [join(process.platform === 'darwin' ? '/Library/Application Support/ClaudeCode'
+      : process.platform === 'win32' ? 'C:\\Program Files\\ClaudeCode' : '/etc/claude-code', 'managed-settings.json')];
+  for (const path of paths) await layer(path, client + '-managed', client === 'codex' ? 'toml' : 'json', files);
+  if (client === 'claude') {
+    const directory = join(dirname(paths[0]), 'managed-settings.d');
+    try {
+      await safePath(directory);
+      const names = (await readdir(directory)).filter(n => !n.startsWith('.') && n.endsWith('.json')).sort();
+      if (names.length > 32) throw new ConfigError('managed_fragment_limit');
+      for (const name of names) await layer(join(directory, name), 'claude-managed-fragment', 'json', files);
+    } catch (error) {
+      if (error.code !== 'ENOENT') files.push({ path: directory, label: 'claude-managed-fragments', error: error.code ?? 'read_failed' });
+    }
+  }
+}
+export async function inspect(input = {}, { env = process.env } = {}) {
+  const spec = normalizeSpec(input, env);
+  const files = [], clients = [], findings = [];
+  const add = (client, code, severity = 'warning') => findings.push({ client, code, severity });
+  if (spec.project) {
+    await safePath(spec.project);
+    if ((await metadata(spec.project)).type !== 'directory') throw new ConfigError('project_directory_required');
+  }
+  const environment = environmentState(env);
+  if (env.NODE_OPTIONS) add('runtime', 'node_startup_options_require_clean_environment', 'blocker');
+  let evidence = null, evidenceFingerprint = null;
+  if (spec.evidence) {
+    const file = await readBounded(spec.evidence);
+    if (file.exists) { evidence = parseDocument(file.text, 'json').value; evidenceFingerprint = fingerprint(file); }
+  }
+  for (const client of selectedClients(spec)) {
+    const { target, rules, runtime, source } = await rulesFor(spec, client);
+    const ownFiles = [];
+    if (client === 'codex') for (const path of codexSystemPaths().defaults) await layer(path, 'codex-system', 'toml', ownFiles);
+    const user = await layer(join(spec[client + '_home'], adapters[client].filename), client + '-user', target.format, ownFiles);
+    if (spec.project) {
+      const dirs = [spec.project];
+      if (client === 'codex') {
+        let directory = spec.project;
+        for (let n = 0; n < 20 && !(await metadata(join(directory, '.git'))).exists; n++) {
+          const parent = dirname(directory); if (parent === directory) break;
+          dirs.unshift(parent); directory = parent;
+        }
+      }
+      for (const directory of dirs) await layer(join(directory, '.' + client, adapters[client].filename), client + '-project', target.format, ownFiles);
+      if (client === 'claude') await layer(join(spec.project, '.claude', 'settings.local.json'), 'claude-local', 'json', ownFiles);
+    }
+    await managedLayers(client, ownFiles);
+    files.push(...ownFiles);
+    for (const f of ownFiles) if (f.error) add(client, f.label + ':' + f.error, 'blocker');
+    // Do not guess which server/OS-managed source is authoritative, execute a
+    // policy helper, or merge its restrictions with a writable user document.
+    if (ownFiles.some(f => f.label.includes('managed') && f.exists)) add(client, 'managed_policy_requires_operator_review', 'blocker');
+    if (client === 'codex' && (at(user.value, ['profile']) !== undefined || at(user.value, ['profiles']) !== undefined)) {
+      add(client, 'profile_selection_requires_operator_review', 'blocker');
+    }
+    const targetFile = ownFiles.find(f => f.path === target.path);
+    if (!targetFile) throw new ConfigError('target_not_discovered');
+    const credentials = [];
+    const names = client === 'codex' ? ['auth.json'] : ['.credentials.json'];
+    for (const name of names) {
+      try { credentials.push({ name, ...await metadata(join(spec[client + '_home'], name)), contents_read: false }); }
+      catch { credentials.push({ name, state: 'unknown', contents_read: false }); }
+    }
+    const integrations = [];
+    for (const field of ['hooks', 'mcp_servers', 'mcpServers', 'plugins', 'enabledPlugins', 'extraKnownMarketplaces', 'apiKeyHelper', 'policyHelper', 'notify']) {
+      if (ownFiles.some(f => at(f.value, [field]) !== undefined)) integrations.push(field);
+    }
+    if (integrations.length) add(client, 'integrations_preserved_not_executed_or_privacy_verified');
+    if (client === 'claude' && environment.observed.some(v => v.present && !v.matches_policy) && spec.mode !== 'statusline-only') {
+      add(client, 'inherited_environment_conflict', 'blocker');
+    }
+    const cells = rules.map(rule => {
+      let found;
+      for (const f of ownFiles) {
+        if (f.error || !f.exists) continue;
+        // Machine-local Codex telemetry cannot be supplied by project config.
+        if (client === 'codex' && f.label.endsWith('project') && rule.scope === 'user') continue;
+        const value = at(f.value, rule.path);
+        if (value !== undefined) found = { file: f, value };
+      }
+      return { key: rule.path.join('.'), source: found?.file.label ?? 'client-default-unknown',
+        observed: safeValue(found?.value, rule.value), matches_policy: found ? isDeepStrictEqual(found.value, rule.value) : null,
+        higher_override: !!found && found.file.path !== target.path && ownFiles.indexOf(found.file) > ownFiles.indexOf(targetFile),
+      };
+    });
+    for (const cell of cells) if (cell.higher_override && !cell.matches_policy) add(client, 'higher_precedence_override:' + cell.key, 'blocker');
+    if (spec.mode !== 'privacy-only' && client === 'claude') {
+      if (ownFiles.some(f => at(f.value, ['disableAllHooks']) === true)) add(client, 'statusline_disabled_by_disableAllHooks', 'blocker');
+      const command = rules.find(r => r.path.join('.') === 'statusLine.command').value;
+      const custom = ownFiles.some(f => {
+        const prior = at(f.value, ['statusLine', 'command']);
+        return prior !== undefined && prior !== command;
+      });
+      if (custom && !spec.replace_statusline) add(client, 'existing_statusline_requires_explicit_replacement', 'blocker');
+    }
+    for (const rule of rules) if (spec.scope === 'project' && rule.scope === 'user') add(client, 'requires_user_scope:' + rule.path.join('.'), 'blocker');
+    const attestation = evidence?.schema_version === 1 ? evidence.clients?.[client] : null;
+    const reviewedAt = Date.parse(evidence?.reviewed_at ?? '');
+    const fresh = Number.isFinite(reviewedAt) && reviewedAt <= Date.now() && Date.now() - reviewedAt <= 30 * 86400_000;
+    const version = typeof attestation?.version === 'string' && /^[A-Za-z0-9.+ -]{1,80}$/.test(attestation.version) ? attestation.version : null;
+    const supported = version && fresh && attestation?.verification === 'manual-local'
+      && attestation?.higher_precedence_reviewed === true
+      && Array.isArray(attestation?.scopes) && attestation.scopes.includes(spec.scope)
+      && Array.isArray(attestation?.keys) && rules.every(r => attestation.keys.includes(r.path.join('.')))
+      && (client !== 'codex' || spec.mode === 'privacy-only' || adapters.codex.statusline()[0].value.every(item => attestation?.status_items?.includes(item)));
+    if (!supported) add(client, 'installed_capabilities_not_attested', 'blocker');
+    clients.push({ client, target, targetFile, rules, runtime, source,
+      credentials, integrations, cells, version, capabilities: supported ? 'operator-attested-not-auto-probed' : 'unknown' });
+  }
+  return { spec, files, clients, findings, environment, evidenceFingerprint };
+}
+export function publicReport(snapshot) {
+  return { schema_version: 2, scope: snapshot.spec.scope, mode: snapshot.spec.mode,
+    network: 'not-used', commands: 'not-run', credential_contents: 'not-read',
+    effective_configuration: 'observed-files-only; CLI flags, OS/remote policies and helpers require local review',
+    clients: snapshot.clients.map(c => ({ client: c.client, version: c.version, capabilities: c.capabilities,
+      configuration: fingerprint(c.targetFile), credentials: c.credentials, integrations: c.integrations, settings: c.cells,
+    })),
+    // Do not output targetFile.value/text or a provider's identifiers/URLs.
+    findings: snapshot.findings, environment: snapshot.environment.observed,
+  };
+}

package/skills-hub/system/optimize-codex-config/scripts/lib/io.mjs

@@ -0,0 +1,104 @@
+// Bounded, no-follow local I/O. Does not read credentials, run a CLI, or use a network.
+import { constants } from 'node:fs';
+import { lstat, open, mkdir, rmdir } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { resolve, isAbsolute, parse, join, relative, sep, dirname } from 'node:path';
+import { ConfigError } from './document.mjs';
+
+export const sha256 = bytes => createHash('sha256').update(bytes).digest('hex');
+export const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+export function canonical(value) {
+  if (Array.isArray(value)) return '[' + value.map(canonical).join(',') + ']';
+  if (value && typeof value === 'object') return '{' + Object.keys(value).sort().map(k => JSON.stringify(k) + ':' + canonical(value[k])).join(',') + '}';
+  return JSON.stringify(value);
+}
+export function absolute(path) {
+  if (typeof path !== 'string' || !isAbsolute(path) || /[\x00-\x1f\x7f]/.test(path)) throw new ConfigError('absolute_path_required');
+  return resolve(path);
+}
+export function within(root, path) {
+  const part = relative(root, path);
+  if (part === '..' || part.startsWith('..' + sep) || isAbsolute(part)) throw new ConfigError('path_escape');
+  return path;
+}
+export async function metadata(path) {
+  try {
+    const s = await lstat(path);
+    return { exists: true, type: s.isSymbolicLink() ? 'symlink' : s.isFile() ? 'file' : s.isDirectory() ? 'directory' : 'other',
+      bytes: s.size, mode: s.mode & 0o777, mtime: s.mtimeMs, dev: s.dev, ino: s.ino };
+  } catch (error) {
+    if (error.code === 'ENOENT') return { exists: false };
+    throw new ConfigError('metadata_unavailable');
+  }
+}
+export async function safePath(path, { privateWrite = false } = {}) {
+  path = absolute(path);
+  let current = parse(path).root;
+  for (const component of path.slice(current.length).split(sep).filter(Boolean)) {
+    current = join(current, component);
+    const meta = await metadata(current);
+    if (!meta.exists) continue;
+    if (meta.type === 'symlink' || (current !== path && meta.type !== 'directory')) throw new ConfigError('unsafe_path');
+    if (privateWrite && process.platform !== 'win32') {
+      const stat = await lstat(current);
+      // Sticky system temp parents are acceptable; private state itself is checked separately.
+      if (stat.isDirectory() && (stat.mode & 0o022) && !(stat.mode & 0o1000)) throw new ConfigError('shared_writable_parent');
+      if (current === path && process.getuid && stat.uid !== process.getuid()) throw new ConfigError('owner_mismatch');
+    }
+  }
+  return path;
+}
+export async function readBounded(path, limit = 1024 * 1024) {
+  await safePath(path);
+  const before = await metadata(path);
+  if (!before.exists) return { ...before, text: '' };
+  if (before.type !== 'file' || before.bytes > limit) throw new ConfigError('unsafe_or_oversize_file');
+  let handle;
+  try {
+    handle = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    const stat = await handle.stat();
+    if (!stat.isFile() || stat.dev !== before.dev || stat.ino !== before.ino || stat.size > limit) throw new ConfigError('read_race');
+    const buffer = Buffer.alloc(Math.min(limit + 1, stat.size + 1));
+    let total = 0;
+    while (total < buffer.length) {
+      const { bytesRead } = await handle.read(buffer, total, buffer.length - total, null);
+      if (!bytesRead) break;
+      total += bytesRead;
+    }
+    if (total !== stat.size || total > limit) throw new ConfigError('read_race');
+    const text = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(buffer.subarray(0, total));
+    if (!same(before, await metadata(path))) throw new ConfigError('read_race');
+    return { ...before, sha256: sha256(buffer.subarray(0, total)), text };
+  } catch (error) {
+    if (error instanceof ConfigError) throw error;
+    throw new ConfigError('read_failed');
+  } finally { await handle?.close(); }
+}
+export function fingerprint(value) {
+  return Object.fromEntries(['exists', 'type', 'bytes', 'mode', 'mtime', 'dev', 'ino', 'sha256'].filter(k => Object.hasOwn(value, k)).map(k => [k, value[k]]));
+}
+export async function makePrivateDirs(path, made = []) {
+  await safePath(path, { privateWrite: true });
+  const meta = await metadata(path);
+  if (meta.exists) {
+    if (meta.type !== 'directory') throw new ConfigError('directory_required');
+    return made;
+  }
+  await makePrivateDirs(dirname(path), made);
+  await mkdir(path, { mode: 0o700 });
+  made.push(path);
+  return made;
+}
+export async function newPrivateFile(path, content) {
+  await safePath(path, { privateWrite: true });
+  const h = await open(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW ?? 0), 0o600);
+  try { await h.writeFile(content, 'utf8'); await h.sync(); }
+  finally { await h.close(); }
+}
+export async function cleanCreatedDirs(dirs) {
+  for (const directory of [...dirs].reverse()) {
+    try { await rmdir(directory); } catch (error) {
+      if (!['ENOTEMPTY', 'ENOENT', 'EEXIST'].includes(error.code)) throw new ConfigError('directory_cleanup_failed');
+    }
+  }
+}

package/skills-hub/system/optimize-codex-config/scripts/lib/plan.mjs

@@ -0,0 +1,79 @@
+import { at, patchDocument, ConfigError, parseDocument } from './document.mjs';
+import { inspect, previewValue, rulesFor, normalizeSpec, selectedClients } from './inspect.mjs';
+import { readBounded, fingerprint, sha256, canonical, newPrivateFile } from './io.mjs';
+
+const digest = value => sha256(canonical(value));
+export function planId(plan) { const { id, ...body } = plan; return digest(body); }
+export async function createPlan(input, options) {
+  const snapshot = await inspect(input, options);
+  const entries = [], findings = [...snapshot.findings];
+  for (const client of snapshot.clients) {
+    const { target, targetFile, rules } = client;
+    if (targetFile.error) continue;
+    try {
+      const text = targetFile.exists ? targetFile.text : target.format === 'toml' ? '' : '{}\n';
+      const changed = patchDocument(text, target.format, rules);
+      if (target.client === 'claude' && snapshot.spec.mode !== 'privacy-only') {
+        const existing = await readBounded(client.runtime);
+        // Content-addressed renderer names are immutable: do not overwrite a custom script.
+        if (existing.exists && existing.sha256 !== client.source.sha256) throw new ConfigError('renderer_content_conflict');
+        entries.push({ client: target.client, kind: 'renderer', root: target.root, path: client.runtime,
+          before: fingerprint(existing), after_hash: client.source.sha256, noop: existing.exists,
+        });
+      }
+      entries.push({ client: target.client, kind: 'config', root: target.root, path: target.path, format: target.format,
+        before: fingerprint(targetFile), after_hash: sha256(changed), noop: targetFile.exists && targetFile.sha256 === sha256(changed),
+        operations: rules,
+        diff: rules.filter(rule => canonical(at(targetFile.value, rule.path)) !== canonical(rule.value)).map(rule => ({
+          key: rule.path.join('.'), before: previewValue(at(targetFile.value, rule.path), rule.value), after: rule.value, reason: rule.reason,
+        })),
+      });
+    } catch (error) { findings.push({ client: target.client, code: error.code ?? 'plan_failed', severity: 'blocker' }); }
+  }
+  const plan = {
+    schema_version: 1, kind: 'wta-ai-cli-config-plan', policy_revision: '2026-10-10', spec: snapshot.spec,
+    platform: process.platform, node: process.execPath,
+    observations: {
+      files: snapshot.files.map(f => ({ path: f.path, fingerprint: fingerprint(f), ...(f.error ? { error: f.error } : {}) })),
+      evidence: snapshot.evidenceFingerprint, environment: snapshot.environment.digest,
+    },
+    entries, findings, ready: !findings.some(f => f.severity === 'blocker'),
+    verification: 'offline parse/hash/policy only; host load, account limits and OS/remote policy not automatically verified',
+    privacy: 'no runtime network; existing integrations preserved and not certified',
+    backup: '<each-target-root>/.wta-ai-cli-config/transactions/<plan-id>/N.pre-optimize.bak',
+  };
+  return { ...plan, id: planId(plan) };
+}
+export async function savePlan(plan, path) {
+  if (!path.endsWith('.plan.json') || plan.entries.some(entry => entry.path === path) || plan.spec.evidence === path) throw new ConfigError('plan_output_requires_new_plan_json');
+  await newPrivateFile(path, JSON.stringify(plan, null, 2) + '\n');
+}
+export async function loadPlan(path) {
+  const file = await readBounded(path);
+  if (!file.exists) throw new ConfigError('plan_missing');
+  const plan = parseDocument(file.text, 'json').value;
+  if (plan.kind !== 'wta-ai-cli-config-plan' || plan.schema_version !== 1 || plan.id !== planId(plan)
+      || !/^[0-9a-f]{64}$/.test(plan.id) || plan.platform !== process.platform || plan.node !== process.execPath) {
+    throw new ConfigError('plan_integrity_or_platform_mismatch');
+  }
+  if (canonical(normalizeSpec(plan.spec)) !== canonical(plan.spec)) throw new ConfigError('noncanonical_plan_spec');
+  const expected = [];
+  for (const client of selectedClients(plan.spec)) {
+    const r = await rulesFor(plan.spec, client);
+    if (client === 'claude' && plan.spec.mode !== 'privacy-only') expected.push({ path: r.runtime, kind: 'renderer', client, root: r.target.root });
+    expected.push({ ...r.target, kind: 'config', operations: r.rules });
+  }
+  if (plan.entries.length !== expected.length) throw new ConfigError('incomplete_plan');
+  for (let i = 0; i < expected.length; i++) {
+    for (const [key, value] of Object.entries(expected[i])) {
+      if (canonical(plan.entries[i][key]) !== canonical(value)) throw new ConfigError('plan_target_or_operation_mismatch');
+    }
+  }
+  return plan;
+}
+export async function desiredText(plan, entry) {
+  const rules = await rulesFor(plan.spec, entry.client);
+  if (entry.kind === 'renderer') return rules.source.text;
+  const file = await readBounded(entry.path);
+  return patchDocument(file.exists ? file.text : entry.format === 'toml' ? '' : '{}\n', entry.format, rules.rules);
+}