skillgauntlet 0.0.0-stage → 1.1.0

package/lib/codewhale.js

@@ -0,0 +1,174 @@
+// Codewhale (formerly DeepSeek-TUI) as a trigger host.
+//
+// Its stream is one JSON object per line (`schema: codewhale.exec-stream`). A skill is read through a
+// `load_skill` tool: `{"type":"tool_use","name":"load_skill","input":{"name":"<skill>"}}`, and the
+// result starts with `# Skill: <skill>`. `input.query` is a search and `input.name == "list"` lists the
+// catalogue; neither selects a skill. That differs from Claude Code, where the model picks from a
+// fixed list, so a rate measured here is a Codewhale number and is never merged with another host's.
+//
+// Two facts from live runs shape the launch:
+//   * a skill in the workspace's own .agents/skills is loaded only once the workspace is trusted, which a
+//     tool-restricted exec run is not; a skill in the *global* root (<home>/.agents/skills) is loaded
+//     without trust. So the trial gets a throw-away home directory holding only the tested skill. That
+//     also keeps the user's own skills out of the catalogue.
+//   * `--auto` means full access and Windows has no execution sandbox, so the run is limited with
+//     `--allowed-tools load_skill`: the model can look a skill up and can do nothing else.
+//
+// Usage statistics are on by default in a fresh home; they are switched off in the throw-away home
+// before the first request.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execFileSync, spawn } from 'node:child_process';
+import { launchSpec } from './spawn.js';
+
+function copyDir(src, dst) {
+  fs.mkdirSync(dst, { recursive: true });
+  for (const e of fs.readdirSync(src, { withFileTypes: true })) {
+    if (e.name === '.git') continue;
+    const s = path.join(src, e.name);
+    const d = path.join(dst, e.name);
+    if (e.isDirectory()) copyDir(s, d);
+    else if (e.isFile()) fs.copyFileSync(s, d);
+  }
+}
+
+function killTree(child) {
+  if (!child || child.killed) return;
+  try {
+    if (process.platform === 'win32') execFileSync('taskkill', ['/T', '/F', '/PID', String(child.pid)], { stdio: 'ignore' });
+    else child.kill('SIGKILL');
+  } catch { /* already gone */ }
+}
+
+// A throw-away home with only the tested skill in its global skills root, and an empty working directory.
+export function isolatedHome(skillDir, skillName) {
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), 'sg-cw-home-'));
+  const cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'sg-cw-cwd-'));
+  if (skillDir) copyDir(skillDir, path.join(home, '.agents', 'skills', skillName));
+  return {
+    home,
+    cwd,
+    env: { ...process.env, HOME: home, USERPROFILE: home },
+    cleanup() {
+      for (const d of [home, cwd]) { try { fs.rmSync(d, { recursive: true, force: true }); } catch { /* best effort */ } }
+    },
+  };
+}
+
+function telemetryOff(bin, env) {
+  const launch = launchSpec(bin, ['config', 'set', 'telemetry', 'false'], 'codewhale');
+  try {
+    execFileSync(launch.cmd, launch.args, { env, stdio: 'ignore', timeout: 30000, shell: launch.shell, windowsHide: true });
+  } catch { /* the setting is a courtesy; a failure here must not hide the trial's own result */ }
+}
+
+// The verdict for one stream line, or null to keep reading.
+export function judgeLine(ev, skillName, rec) {
+  if (ev.type === 'tool_use' && ev.name === 'load_skill') {
+    rec.tools.push('load_skill');
+    rec.firstTool = rec.firstTool || 'load_skill';
+    const name = typeof ev.input?.name === 'string' ? ev.input.name : '';
+    if (!name || name === 'list') return null; // a search or a catalogue listing selects nothing
+    if (name === skillName || name.endsWith(`:${skillName}`)) return { verdict: 'triggered', invokedSkill: name };
+    return { verdict: 'other_skill', invokedSkill: name };
+  }
+  if (ev.type === 'tool_use') {
+    rec.tools.push(ev.name);
+    rec.firstTool = rec.firstTool || ev.name;
+    return { verdict: 'not_triggered' };
+  }
+  if (ev.type === 'error') return { verdict: 'error', error: String(ev.error || 'error').slice(0, 500) };
+  if (ev.type === 'done') return { verdict: 'not_triggered' };
+  return null;
+}
+
+export function runCodewhaleTrial({ bin, skillDir, skillName, query, model, timeout = 180 }) {
+  return new Promise((resolve) => {
+    const iso = isolatedHome(skillDir, skillName);
+    telemetryOff(bin, iso.env);
+    const args = ['exec', '--allowed-tools', 'load_skill', '--output-format', 'stream-json'];
+    if (model) args.push('--model', model);
+    args.push('--', query);
+    const rec = { host: 'codewhale', verdict: null, invokedSkill: null, firstTool: null, tools: [], exploreSteps: 0, error: null,
+      events: { lines: 0, toolUse: 0, types: {} } };
+    const launch = launchSpec(bin, args, 'codewhale');
+    const child = spawn(launch.cmd, launch.args, {
+      cwd: iso.cwd, env: iso.env, shell: launch.shell, windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    let timedOut = false;
+    const timer = setTimeout(() => { timedOut = true; killTree(child); }, timeout * 1000);
+    let stderr = '';
+    child.stderr.setEncoding('utf8');
+    child.stderr.on('data', (c) => { if (stderr.length < 4000) stderr += c; });
+    let buf = '';
+    let settled = false;
+    const finish = (verdict, extra = {}) => {
+      if (settled) return;
+      settled = true;
+      rec.verdict = verdict;
+      Object.assign(rec, extra);
+      killTree(child);
+    };
+    child.stdout.setEncoding('utf8');
+    child.stdout.on('data', (chunk) => {
+      buf += chunk;
+      let nl;
+      while ((nl = buf.indexOf('\n')) >= 0) {
+        const line = buf.slice(0, nl).trim();
+        buf = buf.slice(nl + 1);
+        if (!line) continue;
+        let ev;
+        try { ev = JSON.parse(line); } catch { continue; }
+        rec.events.lines += 1;
+        rec.events.types[ev.type] = (rec.events.types[ev.type] || 0) + 1;
+        if (ev.type === 'tool_use') rec.events.toolUse += 1;
+        if (ev.type === 'metadata') rec.modelResolved = ev.meta?.model;
+        const v = judgeLine(ev, skillName, rec);
+        if (v) { finish(v.verdict, v); return; }
+      }
+    });
+    child.on('error', (err) => { rec.error = String(err.message || err); finish('error'); });
+    child.on('close', () => {
+      clearTimeout(timer);
+      if (!settled) {
+        if (timedOut) finish('timeout', { error: `no verdict within ${timeout}s` });
+        else if (rec.error) finish('error');
+        else if (!rec.events.lines) {
+          finish('error', { error: (stderr.trim().split(/\r?\n/).filter(Boolean).slice(0, 2).join(' ') || 'no output from the CLI').slice(0, 500) });
+        } else finish('not_triggered');
+      }
+      iso.cleanup();
+      resolve(rec);
+    });
+  });
+}
+
+// One-shot answer with no tools: the text is the concatenated `content` events.
+export function draftWithCodewhale({ bin, prompt, model, timeout }) {
+  const iso = isolatedHome(null, null);
+  telemetryOff(bin, iso.env);
+  const args = ['exec', '--output-format', 'stream-json'];
+  if (model) args.push('--model', model);
+  args.push('--', prompt);
+  const launch = launchSpec(bin, args, 'codewhale');
+  let out;
+  try {
+    out = execFileSync(launch.cmd, launch.args, {
+      encoding: 'utf8', timeout: timeout * 1000, maxBuffer: 32 * 1024 * 1024, cwd: iso.cwd, env: iso.env,
+      shell: launch.shell, windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'],
+    });
+  } catch (err) {
+    // A rejected key still prints its reason as an `error` event on stdout.
+    const events = String(err.stdout || '').split(/\r?\n/).filter(Boolean).map((l) => { try { return JSON.parse(l); } catch { return null; } });
+    const e = events.find((x) => x?.type === 'error');
+    const why = e ? String(e.error).split(/\r?\n/)[0] : (err.killed ? `no answer within ${timeout}s` : String(err.stderr || err.message).split(/\r?\n/).find(Boolean));
+    throw new Error(`the drafting call failed: ${why}`);
+  } finally {
+    iso.cleanup();
+  }
+  const events = out.split(/\r?\n/).filter(Boolean).map((l) => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
+  const err = events.find((x) => x.type === 'error');
+  if (err) throw new Error(`the drafting call failed: ${String(err.error).split(/\r?\n/)[0]}`);
+  return events.filter((x) => x.type === 'content').map((x) => x.content).join('');
+}

package/lib/codex.js

@@ -0,0 +1,318 @@
+// Codex host. What Codex exposes is narrower than Claude Code's, and the difference is structural,
+// not a missing flag.
+//
+// Schema, confirmed against a live run on 2026-10-27 (codex-cli 0.159.2, ChatGPT account):
+//   events : thread.started / turn.started / turn.completed / turn.failed / item.started /
+//            item.updated / item.completed / error
+//   items  : command_execution, mcp_tool_call, file_change, todo_list, agent_message, user_message,
+//            agent_reasoning, error
+//   usage  : turn.completed carries input_tokens, cached_input_tokens, output_tokens
+//
+// There is no skill item. In Codex a skill is host-side context: it is selected and injected, not
+// called as a tool, so "did the model choose this skill" has no observable answer. `skills_used`
+// exists only in the telemetry profile struct (unique_skills_used, total_skills_used), not in the
+// stream. Reporting a trigger rate here would mean inventing one.
+//
+// So this host supports what is observable: whether the agent acted, what it ran, what it changed,
+// and therefore the paired with/without probe and the contract checks. Not a trigger rate.
+//
+// Two traps found by that run: with --sandbox read-only every exec_command is refused by policy, so
+// a probe needs workspace-write; and without --ignore-user-config a stale model id in
+// ~/.codex/config.toml fails every turn for reasons unrelated to the skill.
+//
+// A third trap, found by the probe itself: installing the skill into .codex/skills as well as
+// .agents/skills made the skill-installed side report a read-only workspace while the clean side
+// wrote files, which turned the comparison into a false positive. Only the documented path is used.
+import { execFileSync, spawn } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { runnerFor, quoteForCmd } from './spawn.js';
+
+const KNOWN_ITEMS = new Set([
+  'command_execution', 'mcp_tool_call', 'file_change', 'todo_list',
+  'agent_message', 'user_message', 'agent_reasoning', 'error',
+]);
+const ACTION_ITEMS = new Set(['command_execution', 'mcp_tool_call', 'file_change', 'web_search']);
+
+export function parseCodexJsonl(text) {
+  const events = [];
+  const items = [];
+  const unknownItemTypes = new Set();
+  const errors = [];
+  let tokenUsage = null;
+  let completed = false;
+  for (const line of text.split(/\r?\n/)) {
+    if (!line.trim()) continue;
+    let obj;
+    try { obj = JSON.parse(line); } catch { continue; }
+    const type = obj.type || obj.msg?.type || '';
+    events.push({ type, raw: obj });
+    if (type === 'turn.completed') completed = true;
+    if (type === 'turn.failed' || type === 'error') {
+      const msg = obj.error?.message || obj.message || obj.error || type;
+      errors.push(typeof msg === 'string' ? msg : JSON.stringify(msg));
+    }
+    if (type.startsWith('item.')) {
+      const item = obj.item || obj.msg?.item;
+      if (item && typeof item === 'object') {
+        items.push({ phase: type.slice(5), ...item });
+        if (item.type === 'error') errors.push(String(item.message || item.error || 'error item'));
+        if (item.type && !KNOWN_ITEMS.has(item.type)) unknownItemTypes.add(item.type);
+      }
+    }
+    if (type === 'turn.completed') tokenUsage = obj.usage || obj.token_usage || null;
+  }
+  return { events, items, unknownItemTypes: [...unknownItemTypes], errors, completed, tokenUsage };
+}
+
+function detailOf(item) {
+  switch (item.type) {
+    case 'command_execution':
+      return (item.command || item.cmd || item.args || []).toString().slice(0, 200);
+    case 'mcp_tool_call':
+      return [item.server, item.name || item.tool].filter(Boolean).join(':');
+    case 'file_change': {
+      const paths = item.paths || item.changes?.map?.((c) => c.path) || item.path || [];
+      return Array.isArray(paths) ? paths.join(', ') : String(paths);
+    }
+    default:
+      return '';
+  }
+}
+
+export function firstAction(items) {
+  const hit = items.find((i) => ACTION_ITEMS.has(i.type) && i.phase !== 'started') || items.find((i) => ACTION_ITEMS.has(i.type));
+  return hit ? { kind: hit.type, detail: detailOf(hit) } : null;
+}
+
+export function finalMessage(items) {
+  const msgs = items.filter((i) => i.type === 'agent_message' || i.type === 'assistant_message');
+  const last = msgs[msgs.length - 1];
+  return last ? String(last.message || last.text || last.content || '').slice(0, 2000) : '';
+}
+
+export function changedFiles(items) {
+  const out = new Set();
+  for (const i of items.filter((x) => x.type === 'file_change')) {
+    const paths = i.paths || i.path || [];
+    for (const p of Array.isArray(paths) ? paths : [paths]) if (p) out.add(String(p));
+  }
+  return [...out].sort();
+}
+
+function copyDir(src, dst) {
+  fs.mkdirSync(dst, { recursive: true });
+  for (const e of fs.readdirSync(src, { withFileTypes: true })) {
+    if (e.name === '.git') continue;
+    const s = path.join(src, e.name);
+    const d = path.join(dst, e.name);
+    if (e.isDirectory()) copyDir(s, d);
+    else if (e.isFile()) fs.copyFileSync(s, d);
+  }
+}
+
+// Codex reads `.agents/skills/` per the shared convention; several guides also claim
+// `.codex/skills/`. Installing into both looked safer, but a `.codex/` directory in the workspace is
+// also where Codex looks for project config, and its presence changed the sandbox outcome of a run
+// (the skill-installed side reported a read-only workspace while the clean side wrote files). A probe
+// is only meaningful if both sides run under identical conditions, so only the documented path is used.
+function installSkill(tmp, skillDir, skillName) {
+  copyDir(skillDir, path.join(tmp, '.agents', 'skills', skillName));
+}
+
+function listFiles(root) {
+  const out = [];
+  const walk = (dir) => {
+    let entries = [];
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      if (e.name === '.agents' || e.name === '.codex' || e.name === '.git') continue;
+      const p = path.join(dir, e.name);
+      if (e.isDirectory()) walk(p);
+      else out.push(path.relative(root, p).replace(/\\/g, '/'));
+    }
+  };
+  walk(root);
+  return out.sort();
+}
+
+// A minimal model catalog for a DeepSeek model, using the field names of DeepSeek's own Codex guide. The
+// long agent instructions of the official file are replaced by a short fixed text, so a probe through this
+// catalog does not run with DeepSeek's recommended prompt; it is the same on both sides of the comparison.
+const INSTRUCTIONS = 'You are a coding agent running in a terminal. Do what the user asks by running commands and editing files in the current directory, then stop.';
+
+export function deepseekCatalog(model) {
+  return `${JSON.stringify({
+    models: [{
+      slug: model,
+      display_name: model,
+      description: 'DeepSeek model for a SkillGauntlet probe',
+      default_reasoning_level: 'high',
+      supported_reasoning_levels: [
+        { effort: 'low', description: 'Fast' },
+        { effort: 'medium', description: 'Balanced' },
+        { effort: 'high', description: 'Thorough' },
+      ],
+      shell_type: 'shell_command',
+      visibility: 'list',
+      supported_in_api: true,
+      priority: 1,
+      minimal_client_version: '0.144.0',
+      apply_patch_tool_type: 'freeform',
+      web_search_tool_type: 'text',
+      input_modalities: ['text'],
+      truncation_policy: { mode: 'tokens', limit: 10000 },
+      supports_parallel_tool_calls: true,
+      supports_reasoning_summaries: true,
+      supports_search_tool: false,
+      context_window: 1048576,
+      max_context_window: 1048576,
+      effective_context_window_percent: 95,
+      auto_review_model_override: model,
+      prefer_websockets: false,
+      support_verbosity: true,
+      default_verbosity: 'low',
+      supports_image_detail_original: false,
+      tool_mode: null,
+      multi_agent_version: 'v2',
+      use_responses_lite: false,
+      include_skills_usage_instructions: false,
+      auto_compact_token_limit: null,
+      comp_hash: '3000',
+      reasoning_summary_format: 'experimental',
+      default_reasoning_summary: 'none',
+      availability_nux: null,
+      upgrade: null,
+      default_service_tier: null,
+      model_messages: { instructions_template: INSTRUCTIONS, instructions_variables: ['', '', ''], approvals: null },
+      experimental_supported_tools: [],
+      base_instructions: INSTRUCTIONS,
+    }],
+  }, null, 2)}
+`;
+}
+
+export function runCodexTrial({
+  bin, skillDir, skillName, query, model, sandbox = 'read-only', timeout = 180, keepDir = false,
+  ignoreUserConfig = true, keepRaw = false, reasoningEffort = null, effort = process.env.SG_CODEX_EFFORT,
+}) {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'sg-codex-'));
+  if (skillDir) installSkill(tmp, skillDir, skillName);
+  const before = listFiles(tmp);
+  const args = ['exec', '--json', '-C', tmp, '--skip-git-repo-check'];
+  // --approve-for-me replaces --sandbox rather than combining with it: the two flags are mutually
+  // exclusive, and that flag carries the workspace-write sandbox. Without it, a non-interactive run
+  // refuses every command ("blocked by policy"), the turn ends with an apology, and no
+  // command_execution item is ever produced. The sandbox-bypass flag is never used, because it would
+  // run code we are deliberately treating as untrusted without any sandbox at all.
+  if (sandbox === 'read-only') args.push('--sandbox', 'read-only');
+  else args.push('--approve-for-me');
+  if (ignoreUserConfig) args.push('--ignore-user-config');
+  if (model) args.push('-m', model);
+  // DeepSeek's Codex guide points a model provider at its Responses endpoint. With --ignore-user-config the
+  // user's config.toml is not read, so the provider is passed inline and the key comes from the environment.
+  let catalogFile = null;
+  if (/^deepseek/i.test(model || '')) {
+    // The catalog entry carries auto_review_model_override: --approve-for-me asks a review model, named
+    // codex-auto-review by default, which DeepSeek's API rejects. It is a per-model catalog field, not a
+    // config key (passing it with -c is reported as "ignored").
+    catalogFile = path.join(os.tmpdir(), `sg-codex-catalog-${process.pid}-${Date.now()}.json`);
+    fs.writeFileSync(catalogFile, deepseekCatalog(model));
+    args.push('-c', 'model_provider="deepseek"',
+      '-c', 'model_providers.deepseek={name="deepseek", base_url="https://api.deepseek.com/", wire_api="responses", env_key="DEEPSEEK_API_KEY"}',
+      '-c', `model_catalog_json="${catalogFile.replace(/\\/g, '/')}"`);
+  }
+  // --ignore-user-config also drops the user's effort setting, so it has to be passed explicitly. The
+  // value is left unquoted: codex falls back to a plain string, and quotes get mangled on the cmd shim.
+  const pinnedEffort = reasoningEffort || effort;
+  if (pinnedEffort) args.push('-c', `model_reasoning_effort=${pinnedEffort}`);
+  args.push(query);
+  const runner = runnerFor(bin, 'codex');
+  const argv = [...runner.prefix, ...args];
+  const cmdArgs = runner.shell ? argv.map(quoteForCmd) : argv;
+
+  return new Promise((resolve) => {
+    const started = Date.now();
+    const child = spawn(runner.cmd, cmdArgs, {
+      cwd: tmp, env: process.env, windowsHide: true, shell: runner.shell,
+      // Without this codex waits on stdin ("Reading additional input from stdin...") forever,
+      // because an inherited pipe stays open.
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    let out = '';
+    let err = '';
+    const timer = setTimeout(() => {
+      try {
+        if (process.platform === 'win32') execFileSync('taskkill', ['/T', '/F', '/PID', String(child.pid)], { stdio: 'ignore' });
+        else child.kill('SIGKILL');
+      } catch { /* already gone */ }
+      setTimeout(() => finish(), 3000);
+    }, timeout * 1000);
+    child.stdout.setEncoding('utf8');
+    child.stdout.on('data', (c) => { out += c; });
+    child.stderr.setEncoding('utf8');
+    child.stderr.on('data', (c) => { err += c; });
+    let finished = false;
+    const finish = () => {
+      if (finished) return;
+      finished = true;
+      clearTimeout(timer);
+      // An agent can leave a background process (a browser daemon) holding our pipes, in which case
+      // 'close' never fires and the run would hang past its timeout.
+      try { child.stdout.destroy(); child.stderr.destroy(); } catch { /* already closed */ }
+      const parsed = parseCodexJsonl(out);
+      // file_change items only appear for patch-style edits; on Windows the agent usually writes
+      // through a shell command, so the filesystem diff is the dependable record of what it did.
+      const after = listFiles(tmp);
+      const rec = {
+        host: 'codex',
+        // What was asked of the CLI, so an archived record says which model and settings produced it.
+        invocation: { model: model || null, effort: effort || null, sandbox, ignoreUserConfig },
+        // Deliberately not a trigger verdict: the stream cannot answer that question.
+        verdict: 'unobservable',
+        firstAction: firstAction(parsed.items),
+        commands: parsed.items.filter((i) => i.type === 'command_execution').map(detailOf),
+        finalMessage: finalMessage(parsed.items),
+        changedFiles: changedFiles(parsed.items),
+        createdFiles: after.filter((f) => !before.includes(f)),
+        itemTypes: [...new Set(parsed.items.map((i) => i.type).filter(Boolean))],
+        unknownItemTypes: parsed.unknownItemTypes,
+        tokenUsage: parsed.tokenUsage,
+        eventTypes: [...new Set(parsed.events.map((e) => e.type).filter(Boolean))],
+        eventCount: parsed.events.length,
+        completed: parsed.completed,
+        errors: parsed.errors,
+        latencyMs: Date.now() - started,
+        stderr: err.slice(-500),
+        rawLines: parsed.events.length,
+      };
+      if (catalogFile) { try { fs.rmSync(catalogFile, { force: true }); } catch { /* best effort */ } }
+      // The unparsed event stream, so a batch record can be re-read without re-running.
+      if (keepRaw) rec.rawJsonl = out;
+      if (keepDir) rec.dir = tmp;
+      else { try { fs.rmSync(tmp, { recursive: true, force: true }); } catch { /* best effort */ } }
+      resolve(rec);
+    };
+    child.on('error', (e) => { err += String(e.message || e); finish(); });
+    child.on('close', finish);
+    // Give buffered output a moment to arrive after the process exits, then stop waiting for the pipes.
+    child.on('exit', () => setTimeout(() => finish(), 2000));
+  });
+}
+
+// Paired probe: the same request with and without the skill installed. It returns facts, not a
+// verdict. Two runs of the same request never execute identical command strings, so "the first
+// action differs" is true almost always and means nothing; an automatic influenced/not-influenced
+// flag would be a coin flip dressed up as a finding. The report shows both sides and the reader
+// decides.
+export async function probeActivation(opts) {
+  const withSkill = await runCodexTrial({ ...opts, sandbox: 'workspace-write' });
+  const without = await runCodexTrial({ ...opts, skillDir: null, sandbox: 'workspace-write' });
+  return {
+    withSkill,
+    without,
+    actionKindIdentical: withSkill.firstAction?.kind === without.firstAction?.kind,
+    artifactsIdentical: JSON.stringify(withSkill.createdFiles) === JSON.stringify(without.createdFiles),
+  };
+}

package/lib/depth.js

@@ -0,0 +1,55 @@
+// Test-strength presets. The point of exposing these is that a user can spend one minute and
+// a tenth of a cent before deciding whether the full run is worth it.
+//
+// Cost model, per trial:
+//   Anthropic  via Claude Code  -> subscription quota, not cash; ~1% of a Pro week per ~120 trials
+//   DeepSeek   via any host      -> ~0.04 CNY per trial (its endpoint ignores cache_control,
+//                                   so the whole prompt is billed at the cache-miss price)
+// Times assume 2 parallel trials at ~4 s each.
+//
+// Labels and hints live in lib/i18n.js (depthQuick, depthQuickHint, ...). No amount of money is shown
+// to the user: the estimate was never accurate enough to print.
+
+export const DEPTHS = {
+  quick: {
+    id: 'quick',
+    sets: 1,
+    perClause: 2,
+    negatives: 4,
+    runs: 1,
+    maxExplore: 0,
+    layers: ['static', 'trigger'],
+  },
+  standard: {
+    id: 'standard',
+    sets: 2,
+    perClause: 3,
+    negatives: 10,
+    runs: 3,
+    maxExplore: 0,
+    layers: ['static', 'trigger', 'gain'],
+  },
+  deep: {
+    id: 'deep',
+    sets: 3,
+    perClause: 4,
+    negatives: 10,
+    runs: 3,
+    maxExplore: 3,
+    layers: ['static', 'trigger', 'gain', 'robustness'],
+  },
+};
+
+export function estimate(depth, clauses = 3) {
+  const d = DEPTHS[depth];
+  const perSet = d.perClause * clauses + d.negatives;
+  const queries = perSet * d.sets;
+  const trials = queries * d.runs;
+  return {
+    ...d,
+    clauses,
+    queries,
+    trials,
+    minutes: Math.max(1, Math.round((trials * 4) / 2 / 60)),
+  };
+}

package/lib/discover.js

@@ -0,0 +1,83 @@
+// Locating skills: a local directory, or owner/repo cloned at a pinned commit.
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const SKIP = new Set(['.git', 'node_modules', '.cache', 'dist', 'build', 'vendor', '__pycache__']);
+
+export function findSkills(root, { maxDepth = 6 } = {}) {
+  const found = [];
+  const walk = (dir, depth) => {
+    if (depth > maxDepth) return;
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    if (entries.some((e) => e.isFile() && e.name === 'SKILL.md')) {
+      found.push(dir);
+      return; // a skill dir does not contain nested skills
+    }
+    for (const e of entries) {
+      if (!e.isDirectory() || SKIP.has(e.name) || e.name.startsWith('.')) continue;
+      walk(path.join(dir, e.name), depth + 1);
+    }
+  };
+  walk(path.resolve(root), 0);
+  return found.sort();
+}
+
+export function readFrontmatter(skillDir) {
+  const file = path.join(skillDir, 'SKILL.md');
+  let text = '';
+  try { text = fs.readFileSync(file, 'utf8'); } catch { return { fm: {}, text: '', file }; }
+  const fm = {};
+  const m = text.match(/^---\s*\r?\n([\s\S]*?)\r?\n---/);
+  if (m) {
+    let key = null;
+    for (const line of m[1].split(/\r?\n/)) {
+      const kv = line.match(/^([A-Za-z0-9_-]+)\s*:\s*(.*)$/);
+      if (kv) {
+        key = kv[1];
+        fm[key] = kv[2].replace(/^["']|["']$/g, '').trim();
+      } else if (key && /^\s+\S/.test(line)) {
+        fm[key] = `${fm[key]} ${line.trim()}`.trim();
+      }
+    }
+  }
+  return { fm, text, file };
+}
+
+function cacheRoot() {
+  const base = process.env.SKILLGAUNTLET_CACHE
+    || path.join(os.homedir(), '.cache', 'skillgauntlet');
+  fs.mkdirSync(base, { recursive: true });
+  return base;
+}
+
+// Accepts: a local path, or owner/repo, or a github URL (with optional #ref).
+export function resolveSpec(spec) {
+  const local = path.resolve(spec);
+  if (fs.existsSync(local)) return { kind: 'local', dir: local, source: { path: spec } };
+
+  const m = spec.match(/^(?:https?:\/\/github\.com\/)?([\w.-]+)\/([\w.-]+?)(?:\.git)?(?:#(.+))?$/);
+  if (!m) {
+    const err = new Error(`cannot read this address: ${spec} (use a local directory or owner/repo)`);
+    err.messageKey = 'badSource';
+    err.vars = { spec };
+    throw err;
+  }
+  const [, owner, repo, ref] = m;
+  const slug = `${owner}__${repo}${ref ? `@${ref}` : ''}`.replace(/[^\w.@-]/g, '_');
+  const dir = path.join(cacheRoot(), slug);
+  if (!fs.existsSync(path.join(dir, '.git'))) {
+    fs.rmSync(dir, { recursive: true, force: true });
+    const args = ['clone', '--quiet', '--depth', '1'];
+    if (ref) args.push('--branch', ref);
+    args.push(`https://github.com/${owner}/${repo}.git`, dir);
+    execFileSync('git', args, { stdio: 'inherit' });
+  }
+  let commit = '';
+  try {
+    commit = execFileSync('git', ['-C', dir, 'rev-parse', 'HEAD'], { encoding: 'utf8' }).trim();
+  } catch { /* keep empty */ }
+  return { kind: 'git', dir, source: { repo: `https://github.com/${owner}/${repo}`, commit, ref: ref || null } };
+}