hydra-nano 0.1.0 → 0.2.0

package/skills/hydra/scripts/install.mjs

@@ -7,6 +7,7 @@ import { execFileSync } from 'node:child_process';
 import { installRuntime, findNpx } from './lib/bootstrap.mjs';
 import { ensureLocal, home } from './lib/local.mjs';
 import { claudeDir, installHooks } from './lib/claude_hooks.mjs';
+import * as integrations from './lib/integrations.mjs';
 
 const here = path.dirname(fileURLToPath(import.meta.url));
 try {
@@ -15,7 +16,10 @@ try {
   if (!manifest.model) throw new Error('GGUF publication is not ready; no downloads or installation performed');
   // Install for the agents named with --agent, or else for every agent found on this machine.
   const named = process.argv.flatMap((arg, i) => arg === '--agent' ? [process.argv[i + 1]] : []);
-  const found = [['claude-code', claudeDir()], ['codex', path.join(os.homedir(), '.codex')]].filter(([, dir]) => existsSync(dir)).map(([id]) => id);
+  // The skill goes where an agent has no hook to route it: Claude Code (plus its hooks), Codex and Antigravity.
+  // Other tools get the MCP server and a hook instead (below), so their context does not carry both.
+  const found = [['claude-code', claudeDir()], ['codex', path.join(os.homedir(), '.codex')], ['antigravity', path.join(os.homedir(), '.gemini', 'antigravity')]]
+    .filter(([, dir]) => existsSync(dir)).map(([id]) => id);
   const agents = named.length ? named : found;
   if (!process.argv.includes('--runtime-only')) {
     if (!agents.length) throw new Error('No Claude Code (~/.claude) or Codex (~/.codex) found; name one with --agent <skills CLI agent ID>');
@@ -42,5 +46,20 @@ The server stays running until stopped or the computer restarts. Download time d
 Test and build runs now go through Hydra, and new sessions are told to ask Hydra about git history.
 Remove them with: node "${path.join(skill, 'hydra.mjs')}" hooks remove`);
   }
+  // Every other coding tool found here: Hydra's MCP server, plus its test/build hook where the tool has hooks.
+  if (!process.argv.includes('--runtime-only') && !process.argv.includes('--no-agents')) {
+    const scripts = integrations.installSharedScripts(here);
+    const tools = integrations.detected(scripts);
+    if (tools.length) {
+      console.log(`Registering Hydra's MCP server${process.argv.includes('--no-hooks') ? '' : ' and test/build hook'} in ${tools.join(', ')} ` +
+        `(each edited file is backed up once as <file>.before-hydra; skip with --no-agents):`);
+      for (const result of integrations.apply(tools, 'install', { scripts, hooks: !process.argv.includes('--no-hooks') })) {
+        console.log(`  ${result.id}: ${result.changes.join('; ') || 'nothing changed'}`);
+        for (const message of result.manual) console.log(`    ${message.replace(/\n/g, '\n    ')}`);
+        if (result.note) console.log(`    ${result.note}`);
+      }
+      console.log(`  Remove them with: node "${path.join(scripts, 'hydra.mjs')}" agents remove`);
+    }
+  }
   console.log('Hydra skill and local runtime ready. Run the installed scripts/hydra.mjs doctor to verify.');
 } catch (error) { console.error(`hydra-install: ${error.message}`); process.exitCode = 2; }

package/skills/hydra/scripts/lib/claude_hooks.mjs

@@ -29,14 +29,79 @@ const RUNNERS = [
 export const claudeDir = () => process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude');
 export const settingsFile = () => path.join(claudeDir(), 'settings.json');
 
-/** The test/build run inside a shell command, or null. Hydra's own runs and HYDRA_RAW=1 pass. */
-export function testRun(command) {
-  if (!command || /hydra(?:\.mjs)?\s+(?:run|test)\b/.test(command) || /\bHYDRA_RAW=1\b/.test(command)) return null;
-  const run = command.split(/&&|\|\||;|\|/).map(part => part.trim().replace(/^(?:\w+=\S*\s+)+/, ''))
+/** The simple commands of a shell line: split on &&, ||, ;, | and newlines outside quotes, so a
+ * quoted grep pattern such as "test\|pytest" is never mistaken for a command of its own. A heredoc
+ * body (<<EOF ... EOF) is data, not commands, and is skipped whole. */
+export function simpleCommands(command) {
+  const parts = [];
+  let current = '';
+  let quote = null;
+  const heredocs = [];
+  for (let i = 0; i < command.length; i++) {
+    const c = command[i];
+    const heredoc = !quote && c === '<' && command[i + 1] === '<' && command[i + 2] !== '<'
+      && /^<<-?\s*(['"]?)([A-Za-z_]\w*)\1/.exec(command.slice(i));
+    if (heredoc) {
+      heredocs.push(heredoc[2]);
+      current += heredoc[0];
+      i += heredoc[0].length - 1;
+      continue;
+    }
+    if (!quote && c === '\n' && heredocs.length) {
+      parts.push(current);
+      current = '';
+      // Skip each body up to the line that holds only its delimiter.
+      for (const delimiter of heredocs.splice(0)) {
+        const end = command.slice(i + 1).split('\n').findIndex(line => line.trim() === delimiter);
+        if (end < 0) return parts.map(part => part.trim()).filter(Boolean);
+        i += command.slice(i + 1).split('\n').slice(0, end + 1).join('\n').length + 1;
+      }
+      continue;
+    }
+    if (quote) {
+      if (quote === '"' && c === '\\') { current += c + (command[++i] ?? ''); continue; }
+      if (c === quote) quote = null;
+      current += c;
+    } else if (c === "'" || c === '"') {
+      quote = c;
+      current += c;
+    } else if (c === '\\') {
+      current += c + (command[++i] ?? '');
+    } else if ((c === '&' || c === '|') && command[i + 1] === c) {
+      parts.push(current);
+      current = '';
+      i++;
+    } else if (c === ';' || c === '|' || c === '\n') {
+      parts.push(current);
+      current = '';
+    } else {
+      current += c;
+    }
+  }
+  parts.push(current);
+  return parts.map(part => part.trim()).filter(Boolean);
+}
+
+const ownRun = command => /hydra(?:\.mjs)?"?\s+(?:run|test)\b/.test(command);
+
+function runnerIn(command) {
+  const run = simpleCommands(command).map(part => part.replace(/^(?:\w+=\S*\s+)+/, ''))
     .find(part => RUNNERS.some(re => re.test(part)));
   return run ? run.replace(/\s+2>&1\s*$/, '') : null;
 }
 
+/** The test/build run inside a shell command, or null. Hydra's own runs and HYDRA_RAW=1 pass. */
+export function testRun(command) {
+  if (!command || ownRun(command) || /\bHYDRA_RAW=1\b/.test(command)) return null;
+  return runnerIn(command);
+}
+
+/** A test/build run let through by HYDRA_RAW=1: the agent wanted more than Hydra's digest. */
+export function rawBypass(command) {
+  return Boolean(command) && /\bHYDRA_RAW=1\b/.test(command) && !ownRun(command)
+    && runnerIn(command.replace(/\bHYDRA_RAW=1\s+/g, '')) !== null;
+}
+
 function load(file) {
   if (!existsSync(file)) return {};
   const text = readFileSync(file, 'utf8');

package/skills/hydra/scripts/lib/integrations.mjs

@@ -0,0 +1,251 @@
+// Hydra in every coding tool: the MCP server (mcp.mjs) for tools, and a shell-command hook that sends
+// test/build runs through Hydra wherever the tool has one. Claude Code keeps its skill and hooks
+// (claude_hooks.mjs) and gets no MCP entry, since that would duplicate the same tools.
+//
+//   tool         MCP entry                                    hook
+//   codex        ~/.codex/config.toml [mcp_servers.hydra]     ~/.codex/hooks.json PreToolUse + SessionStart (trust with /hooks)
+//   cursor       ~/.cursor/mcp.json mcpServers.hydra          ~/.cursor/hooks.json beforeShellExecution + sessionStart
+//   opencode     ~/.config/opencode/opencode.json(c) mcp.hydra ~/.config/opencode/plugins/hydra.js tool.execute.before
+//   gemini-cli   ~/.gemini/settings.json mcpServers.hydra     same file, hooks.BeforeTool on run_shell_command
+//   antigravity  ~/.gemini/antigravity/mcp_config.json        none known; the MCP server's instructions guide it
+//
+// Every file Hydra edits is backed up once as <file>.before-hydra, written atomically, and only
+// Hydra's own entries are added or removed. A file Hydra cannot edit safely (JSON with comments, or
+// invalid) is left alone and the entry to add by hand is reported instead.
+import { copyFileSync, cpSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const home = () => process.env.HYDRA_TOOLS_HOME || os.homedir();
+const OURS = /[\\/](?:\.hydra[\\/]scripts|skills[\\/]hydra[\\/]scripts)[\\/]/;
+const BEGIN = '# >>> hydra (managed by Hydra; remove with: hydra agents remove codex) >>>';
+const END = '# <<< hydra <<<';
+
+/** Hydra's own copy of its scripts, which every tool's MCP entry and hook points at. */
+export const sharedScripts = () => path.join(process.env.HYDRA_HOME ?? path.join(os.homedir(), '.hydra'), 'scripts');
+
+/** Copy the skill's scripts to sharedScripts(), so registrations never point into an npx cache. */
+export function installSharedScripts(from) {
+  const target = sharedScripts();
+  if (path.resolve(from) === path.resolve(target)) return target; // Already running from the shared copy.
+  mkdirSync(path.dirname(target), { recursive: true });
+  rmSync(`${target}.hydra-tmp`, { recursive: true, force: true });
+  cpSync(from, `${target}.hydra-tmp`, { recursive: true });
+  rmSync(target, { recursive: true, force: true });
+  renameSync(`${target}.hydra-tmp`, target);
+  return target;
+}
+
+const quote = value => JSON.stringify(value);
+const node = () => process.execPath;
+const hookCommand = (scripts, name, format) => `${quote(node())} ${quote(path.join(scripts, 'hooks', name))} --format ${format}`;
+
+function backup(file) {
+  if (existsSync(file) && !existsSync(`${file}.before-hydra`)) copyFileSync(file, `${file}.before-hydra`);
+}
+
+function write(file, text) {
+  mkdirSync(path.dirname(file), { recursive: true });
+  backup(file);
+  writeFileSync(`${file}.hydra-tmp`, text);
+  renameSync(`${file}.hydra-tmp`, file);
+}
+
+class Manual extends Error {
+  constructor(file, snippet, why) { super(`${file} ${why}; add this by hand:\n${snippet}`); this.manual = true; }
+}
+
+/** Read a JSON settings file Hydra may rewrite. Comments would be lost on rewrite, so they stop it. */
+function loadJson(file, snippet) {
+  if (!existsSync(file)) return {};
+  const text = readFileSync(file, 'utf8');
+  if (!text.trim()) return {};
+  const withoutStrings = text.replace(/"(?:[^"\\]|\\.)*"/g, '""');
+  if (/\/\/|\/\*/.test(withoutStrings)) throw new Manual(file, snippet, 'has comments that a rewrite would drop');
+  let value;
+  try { value = JSON.parse(text); } catch { value = null; }
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Manual(file, snippet, 'is not valid JSON');
+  return value;
+}
+
+const saveJson = (file, value) => write(file, `${JSON.stringify(value, null, 2)}\n`);
+const mentionsOurs = value => OURS.test(JSON.stringify(value ?? ''));
+
+/** Add or remove Hydra's entry in a JSON object of named servers, such as mcpServers. */
+function jsonServer(file, key, entry) {
+  return {
+    install() {
+      const snippet = JSON.stringify({ [key]: { hydra: entry } }, null, 2);
+      const settings = loadJson(file, snippet);
+      settings[key] = { ...(settings[key] ?? {}), hydra: entry };
+      saveJson(file, settings);
+      return `${file}: ${key}.hydra`;
+    },
+    remove() {
+      if (!existsSync(file)) return null;
+      const settings = loadJson(file, '');
+      if (!settings[key]?.hydra || !mentionsOurs(settings[key].hydra)) return null;
+      delete settings[key].hydra;
+      if (!Object.keys(settings[key]).length) delete settings[key];
+      saveJson(file, settings);
+      return `${file}: ${key}.hydra`;
+    },
+    status: () => existsSync(file) && (() => { try { return mentionsOurs(loadJson(file, '')[key]?.hydra); } catch { return false; } })(),
+  };
+}
+
+/** Claude-style hook lists ({event: [{matcher, hooks: [{type, command}]}]}) under `root` in a JSON file. */
+function jsonHooks(file, events, { root = 'hooks', extra = {} } = {}) {
+  const without = settings => {
+    for (const [event, groups] of Object.entries(settings[root] ?? {})) {
+      if (!Array.isArray(groups)) continue;
+      const kept = groups.map(group => (group.hooks ? { ...group, hooks: group.hooks.filter(hook => !OURS.test(hook.command ?? '')) } : group))
+        .filter(group => (group.hooks ? group.hooks.length : !OURS.test(group.command ?? '')));
+      if (kept.length) settings[root][event] = kept; else delete settings[root][event];
+    }
+    if (settings[root] && !Object.keys(settings[root]).length) delete settings[root];
+    return settings;
+  };
+  return {
+    install() {
+      const snippet = JSON.stringify({ ...extra, [root]: events }, null, 2);
+      const settings = without(loadJson(file, snippet));
+      Object.assign(settings, Object.fromEntries(Object.entries(extra).filter(([k]) => settings[k] === undefined)));
+      settings[root] ??= {};
+      for (const [event, groups] of Object.entries(events)) (settings[root][event] ??= []).push(...groups);
+      saveJson(file, settings);
+      return `${file}: ${Object.keys(events).join(', ')}`;
+    },
+    remove() {
+      if (!existsSync(file)) return null;
+      const settings = loadJson(file, '');
+      const before = JSON.stringify(settings);
+      without(settings);
+      if (JSON.stringify(settings) === before) return null;
+      saveJson(file, settings);
+      return `${file}: hooks`;
+    },
+    status: () => existsSync(file) && OURS.test(readFileSync(file, 'utf8')),
+  };
+}
+
+/** Codex keeps MCP servers in TOML; Hydra's table sits between marker comments it alone writes. */
+function tomlServer(file, scripts) {
+  const block = `${BEGIN}\n[mcp_servers.hydra]\ncommand = ${quote(node())}\nargs = [${quote(path.join(scripts, 'mcp.mjs'))}]\nstartup_timeout_sec = 20\ntool_timeout_sec = 1800\n${END}\n`;
+  // Install appends "\n" + block to text ending in a newline, so removing "\n" + block restores it exactly.
+  const strip = text => text.replace(new RegExp(`\\n?${BEGIN.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}[\\s\\S]*?${END}\\n?`), '');
+  return {
+    install() {
+      const text = existsSync(file) ? strip(readFileSync(file, 'utf8')) : '';
+      if (/^\[mcp_servers\.hydra\]/m.test(text)) throw new Manual(file, block, 'already has an [mcp_servers.hydra] table that Hydra did not write');
+      // Appended at the end: a TOML table runs until the next header, so nothing after it is captured.
+      write(file, `${text.replace(/\s*$/, '\n')}\n${block}`);
+      return `${file}: [mcp_servers.hydra]`;
+    },
+    remove() {
+      if (!existsSync(file)) return null;
+      const text = readFileSync(file, 'utf8');
+      if (!text.includes(BEGIN)) return null;
+      write(file, strip(text));
+      return `${file}: [mcp_servers.hydra]`;
+    },
+    status: () => existsSync(file) && readFileSync(file, 'utf8').includes(BEGIN),
+  };
+}
+
+/** OpenCode loads every file in its plugins folder; Hydra's is one small file that imports the shared scripts. */
+function opencodePlugin(file, scripts) {
+  const url = name => quote(new URL(`file://${path.join(scripts, name).replace(/\\/g, '/')}`).href);
+  const source = `// Hydra (managed by Hydra; remove with: hydra agents remove opencode): send test/build runs through Hydra.
+import { testRun } from ${url('lib/claude_hooks.mjs')};
+import { record } from ${url('lib/ledger.mjs')};
+
+export const Hydra = async () => ({
+  'tool.execute.before': async (input, output) => {
+    if (input.tool !== 'bash') return;
+    const command = String(output.args?.command ?? '');
+    const run = testRun(command);
+    if (!run) return;
+    record({ ts: new Date().toISOString(), kind: 'hook', hook: 'route-tests', agent: 'opencode', decision: 'deny',
+      command: command.slice(0, 300), run, ...(input.sessionID ? { session: input.sessionID } : {}) });
+    throw new Error('Test/build runs go through Hydra so the full log stays out of context. Run it as: ' +
+      'node ' + ${quote(JSON.stringify(path.join(scripts, 'hydra.mjs')))} + ' run -- ' + run + ', or call the hydra_run tool with that command. ' +
+      'If you truly need the raw log, prefix the original command with HYDRA_RAW=1.');
+  },
+});
+`;
+  return {
+    install() { write(file, source); return file; },
+    remove() {
+      if (!existsSync(file) || !readFileSync(file, 'utf8').includes('managed by Hydra')) return null;
+      rmSync(file);
+      if (existsSync(`${file}.before-hydra`)) rmSync(`${file}.before-hydra`);
+      return file;
+    },
+    status: () => existsSync(file) && readFileSync(file, 'utf8').includes('managed by Hydra'),
+  };
+}
+
+const opencodeConfig = dir => ['opencode.json', 'opencode.jsonc'].map(name => path.join(dir, name)).find(existsSync) ?? path.join(dir, 'opencode.json');
+
+/** Every tool Hydra can join, with where it lives and what Hydra registers there. */
+export function tools(scripts = sharedScripts()) {
+  const h = home();
+  const mcp = { command: node(), args: [path.join(scripts, 'mcp.mjs')] };
+  const codex = path.join(h, '.codex');
+  const cursor = path.join(h, '.cursor');
+  const opencode = path.join(h, '.config', 'opencode');
+  const gemini = path.join(h, '.gemini');
+  return {
+    codex: { dir: codex, parts: {
+      mcp: tomlServer(path.join(codex, 'config.toml'), scripts),
+      hooks: jsonHooks(path.join(codex, 'hooks.json'), {
+        PreToolUse: [{ matcher: 'Bash', hooks: [{ type: 'command', command: hookCommand(scripts, 'route-tests.mjs', 'codex'), timeout: 10 }] }],
+        SessionStart: [{ hooks: [{ type: 'command', command: hookCommand(scripts, 'session-guide.mjs', 'codex'), timeout: 10 }] }] }) },
+      note: 'Codex runs new hooks only after you trust them: open Codex and run /hooks.' },
+    cursor: { dir: cursor, parts: {
+      mcp: jsonServer(path.join(cursor, 'mcp.json'), 'mcpServers', mcp),
+      hooks: jsonHooks(path.join(cursor, 'hooks.json'), {
+        beforeShellExecution: [{ command: hookCommand(scripts, 'route-tests.mjs', 'cursor'), timeout: 10 }],
+        sessionStart: [{ command: hookCommand(scripts, 'session-guide.mjs', 'cursor'), timeout: 10 }] }, { extra: { version: 1 } }) } },
+    opencode: { dir: opencode, parts: {
+      mcp: jsonServer(opencodeConfig(opencode), 'mcp', { type: 'local', command: [mcp.command, ...mcp.args], enabled: true, timeout: 1_800_000 }),
+      hooks: opencodePlugin(path.join(opencode, 'plugins', 'hydra.js'), scripts) } },
+    'gemini-cli': { dir: path.join(gemini, 'settings.json'), parts: {
+      mcp: jsonServer(path.join(gemini, 'settings.json'), 'mcpServers', { ...mcp, timeout: 1_800_000 }),
+      hooks: jsonHooks(path.join(gemini, 'settings.json'), {
+        BeforeTool: [{ matcher: 'run_shell_command', hooks: [{ name: 'hydra', type: 'command', command: hookCommand(scripts, 'route-tests.mjs', 'gemini'), timeout: 10_000 }] }] }) } },
+    antigravity: { dir: path.join(gemini, 'antigravity'), parts: {
+      mcp: jsonServer(path.join(gemini, 'antigravity', 'mcp_config.json'), 'mcpServers', mcp) } },
+  };
+}
+
+/** The tools whose folders exist on this machine. */
+export const detected = (scripts) => Object.entries(tools(scripts)).filter(([, tool]) => existsSync(tool.dir)).map(([id]) => id);
+
+/** Register (or with remove, take out) Hydra for each tool; one tool failing never stops the others. */
+export function apply(ids, action, { scripts = sharedScripts(), hooks = true } = {}) {
+  const all = tools(scripts);
+  return ids.map(id => {
+    const tool = all[id];
+    if (!tool) return { id, error: `unknown tool; known: ${Object.keys(all).join(', ')}` };
+    const changes = [];
+    const manual = [];
+    for (const [name, part] of Object.entries(tool.parts)) {
+      if (action === 'install' && name === 'hooks' && !hooks) continue;
+      try {
+        const change = part[action]();
+        if (change) changes.push(change);
+      } catch (error) {
+        if (!error.manual) throw error;
+        manual.push(error.message);
+      }
+    }
+    return { id, changes, manual, ...(action === 'install' && tool.note && tool.parts.hooks && hooks ? { note: tool.note } : {}) };
+  });
+}
+
+export function status(scripts = sharedScripts()) {
+  return Object.entries(tools(scripts)).map(([id, tool]) => ({ id, present: existsSync(tool.dir),
+    ...Object.fromEntries(Object.entries(tool.parts).map(([name, part]) => [name, Boolean(part.status())])) }));
+}

package/skills/hydra/scripts/lib/ledger.mjs

@@ -1,3 +1,9 @@
+// Local telemetry: one JSON line per Hydra call or hook decision in ~/.hydra/ledger.jsonl.
+// Nothing leaves the machine. HYDRA_TELEMETRY=0 turns recording off.
+//   kind 'call' (or no kind, rows written before telemetry v2): a head answered; raw/returned token estimates.
+//   kind 'hook': the PreToolUse hook turned a command back ('deny'), let HYDRA_RAW=1 through ('raw') or
+//     passed it ('pass', recorded without the command). hookMs is the hook process's whole lifetime.
+//   kind 'error': a command failed (model unavailable, crash).
 import { appendFileSync, mkdirSync, readFileSync } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
@@ -8,27 +14,120 @@ const file = () => path.join(home(), 'ledger.jsonl');
 // A rough count that needs no tokenizer; every figure built on it is an estimate.
 export const tokens = chars => Math.ceil(chars / 4);
 
+export const enabled = () => process.env.HYDRA_TELEMETRY !== '0';
+
+/** Who is calling: the agent family and its session when the agent says so, else a plain shell.
+ * AI_AGENT differs inside hooks (claude-code_<version>_harness) and the agent's shell (..._agent),
+ * so `agent` keeps only the family and `agentDetail` the full value. */
+export function caller(session = process.env.CLAUDE_CODE_SESSION_ID) {
+  // HYDRA_AGENT is the MCP client's own name (codex-mcp-client, gemini-cli, opencode, ...), set by mcp.mjs.
+  const detail = process.env.HYDRA_AGENT || process.env.AI_AGENT;
+  const agent = process.env.HYDRA_AGENT ? detail.toLowerCase().replace(/[-_ ]?mcp[-_ ]?client$/, '')
+    : detail ? detail.split('_')[0] : process.env.CLAUDECODE ? 'claude-code' : 'shell';
+  return { agent, ...(detail ? { agentDetail: detail } : {}), ...(process.env.HYDRA_VIA ? { via: process.env.HYDRA_VIA } : {}),
+    ...(session ? { session } : {}) };
+}
+
 export function record(entry) {
+  if (!enabled()) return;
   try {
     mkdirSync(home(), { recursive: true });
-    appendFileSync(file(), `${JSON.stringify(entry)}\n`);
+    appendFileSync(file(), `${JSON.stringify({ v: 2, kind: 'call', ...caller(), ...entry })}\n`);
   } catch {
     // Accounting must never fail the answer.
   }
 }
 
-export function stats() {
-  let rows = [];
+/** Wrap a chat function so a call's record can say how often and how long the local model ran. */
+export function metered(chat) {
+  const meter = { modelCalls: 0, modelSeconds: 0 };
+  meter.chat = async opts => {
+    const started = Date.now();
+    meter.modelCalls += 1;
+    try {
+      return await chat(opts);
+    } finally {
+      meter.modelSeconds = Number((meter.modelSeconds + (Date.now() - started) / 1000).toFixed(2));
+    }
+  };
+  return meter;
+}
+
+export function rows() {
   try {
-    rows = readFileSync(file(), 'utf8').split('\n').filter(Boolean).map(line => JSON.parse(line));
+    return readFileSync(file(), 'utf8').split('\n').filter(Boolean).flatMap(line => {
+      try { return [JSON.parse(line)]; } catch { return []; }
+    });
   } catch {
-    // No ledger yet.
+    return []; // No ledger yet.
   }
-  const total = { calls: rows.length, raw: 0, returned: 0, heads: {} };
-  for (const row of rows) {
+}
+
+const isCall = row => (row.kind ?? 'call') === 'call';
+
+export function stats(all = rows()) {
+  const total = { calls: 0, raw: 0, returned: 0, heads: {} };
+  for (const row of all.filter(isCall)) {
+    total.calls += 1;
     total.raw += row.raw;
     total.returned += row.returned;
     total.heads[row.head] = (total.heads[row.head] ?? 0) + 1;
   }
   return total;
 }
+
+const percentile = (values, p) => {
+  if (!values.length) return 0;
+  const sorted = [...values].sort((a, b) => a - b);
+  return sorted[Math.min(sorted.length - 1, Math.floor(p * sorted.length))];
+};
+
+/**
+ * What the ledger says Hydra should improve, newest data first. `since` is an ISO time.
+ * Per head: calls, tokens saved, calls that returned more than the raw output, latency, model use.
+ * Hooks: denials, how many the agent followed with a Hydra run in the same session, and
+ * HYDRA_RAW=1 bypasses, which are often a pattern the hook should not have matched.
+ */
+export function findings(all = rows(), { since } = {}) {
+  const recent = since ? all.filter(row => (row.ts ?? '') >= since) : all;
+  const calls = recent.filter(isCall);
+  const heads = {};
+  for (const row of calls) {
+    const head = heads[row.head] ??= { calls: 0, raw: 0, returned: 0, costMore: [], seconds: [], modelCalls: 0, failedRuns: 0 };
+    head.calls += 1;
+    head.raw += row.raw;
+    head.returned += row.returned;
+    head.seconds.push(row.seconds ?? 0);
+    head.modelCalls += row.modelCalls ?? 0;
+    if (row.exit) head.failedRuns += 1;
+    if (row.returned > row.raw) head.costMore.push(row);
+  }
+  const perHead = Object.fromEntries(Object.entries(heads).map(([name, h]) => [name, {
+    calls: h.calls, saved: h.raw - h.returned, savedShare: h.raw ? Number(((h.raw - h.returned) / h.raw).toFixed(3)) : 0,
+    costMore: h.costMore.length, p50Seconds: percentile(h.seconds, 0.5), p90Seconds: percentile(h.seconds, 0.9),
+    modelCalls: h.modelCalls, failedRuns: h.failedRuns,
+    costMoreExamples: h.costMore.slice(-3).map(row => ({ question: row.question, raw: row.raw, returned: row.returned })),
+  }]));
+  const hooks = recent.filter(row => row.kind === 'hook');
+  const hookMs = hooks.map(row => row.hookMs).filter(Number.isFinite);
+  const denials = hooks.filter(row => row.decision === 'deny');
+  const followed = denials.filter(deny => calls.some(call => call.session && call.session === deny.session
+    && call.head === 'test' && call.ts >= deny.ts && Date.parse(call.ts) - Date.parse(deny.ts) <= 5 * 60_000));
+  const agents = {};
+  for (const row of recent) {
+    const agent = agents[row.agent ?? 'unknown'] ??= { calls: 0, viaMcp: 0, denials: 0, sessions: 0 };
+    if (isCall(row)) { agent.calls += 1; if (row.via === 'mcp') agent.viaMcp += 1; }
+    if (row.kind === 'hook' && row.decision === 'deny') agent.denials += 1;
+    if (row.kind === 'session') agent.sessions += 1;
+  }
+  const sessions = new Set(recent.map(row => row.session).filter(Boolean));
+  const sessionsUsing = new Set(calls.map(row => row.session).filter(Boolean));
+  return {
+    since: since ?? recent[0]?.ts ?? null, calls: calls.length, perHead, agents,
+    hooks: { decisions: hooks.length, p50Ms: percentile(hookMs, 0.5), p90Ms: percentile(hookMs, 0.9),
+             denials: denials.length, followedByHydra: followed.length,
+             rawBypasses: hooks.filter(row => row.decision === 'raw').map(row => row.command).slice(-5) },
+    errors: recent.filter(row => row.kind === 'error').slice(-5).map(row => ({ ts: row.ts, command: row.command, error: row.error })),
+    sessions: { seen: sessions.size, usingHydra: sessionsUsing.size },
+  };
+}

package/skills/hydra/scripts/lib/test_logs.mjs

@@ -7,6 +7,9 @@ const PASS_THROUGH = 800;
 const MAX_CANDIDATES = 60;
 const MAX_CITED = 12;
 const WHOLE_REGIONS = 2000;
+// The command as the agent typed it, minus the program's directory: a long venv or toolchain path
+// costs tokens on every reply and tells the agent nothing it does not know.
+export const label = cmd => cmd.replace(/^(?:"[^"]*[\\/]|[^\s"]*[\\/])([^\s"\\/]+)"?/, '$1');
 // Colour codes and the prefixes CI runners put on each line (timestamps, BuildKit step markers,
 // GitLab section markers) are removed before matching. Output always keeps the original line.
 const ANSI = /\x1b\[[0-9;?]*[A-Za-z]/g;
@@ -145,10 +148,11 @@ export async function digest({ cmd, out = '', err = '', exitCode = 0 }, chat) {
   const rawText = (out + (err ? (out ? '\n' : '') + err : '')).trimEnd();
   const rawChars = rawText.length;
 
-  // Short output passes through verbatim with no model call
+  // Short output passes through verbatim with no model call. A short pass needs no command line:
+  // the agent knows what it ran, and the line would cost more than the output it labels.
   if (rawChars <= PASS_THROUGH) {
     return {
-      text: `$ ${cmd}${exitCode !== 0 ? ` (exit ${exitCode})` : ''}\n${rawText}`,
+      text: exitCode !== 0 ? `$ ${label(cmd)} (exit ${exitCode})\n${rawText}` : rawText || '(no output)',
       rawChars,
       exitCode,
     };
@@ -162,7 +166,7 @@ export async function digest({ cmd, out = '', err = '', exitCode = 0 }, chat) {
       .slice(-8)
       .join('\n');
     return {
-      text: `$ ${cmd} (exit 0)\nAll tests passed.\n${summaryLines ? `${summaryLines}\n` : ''}(Verbose output withheld)`,
+      text: `$ ${label(cmd)} (exit 0)\nAll tests passed.\n${summaryLines ? `${summaryLines}\n` : ''}(Verbose output withheld)`,
       rawChars,
       exitCode,
     };
@@ -176,7 +180,7 @@ export async function digest({ cmd, out = '', err = '', exitCode = 0 }, chat) {
     const indices = new Set([...lines.slice(0, 3).map((_, i) => i), ...lines.slice(-12).map((_, i) => Math.max(0, lines.length - 12) + i)]);
     const excerpt = [...indices].sort((a, b) => a - b).map(i => lines[i]).join('\n');
     return {
-      text: `$ ${cmd} (exit ${exitCode})\n${excerpt}\n(... ${lines.length - indices.size} lines withheld)`,
+      text: `$ ${label(cmd)} (exit ${exitCode})\n${excerpt}\n(... ${lines.length - indices.size} lines withheld)`,
       rawChars,
       exitCode,
     };
@@ -185,7 +189,7 @@ export async function digest({ cmd, out = '', err = '', exitCode = 0 }, chat) {
   // Failure regions this small cost less to return whole than to have the model cut down, and whole is always complete.
   const regions = candidates.map(c => c.text);
   if (regions.length && regions.join('\n').length <= WHOLE_REGIONS) {
-    return { text: `$ ${cmd} (exit ${exitCode})\n${regions.join('\n')}`, rawChars, exitCode };
+    return { text: `$ ${label(cmd)} (exit ${exitCode})\n${regions.join('\n')}`, rawChars, exitCode };
   }
 
   const numbered = candidates.map(c => `[${c.id}] ${c.text}`).join('\n');
@@ -215,7 +219,7 @@ export async function digest({ cmd, out = '', err = '', exitCode = 0 }, chat) {
     evidenceLines = candidates.slice(0, 12).map(c => c.text);
   }
 
-  const text = `$ ${cmd} (exit ${exitCode})\n${evidenceLines.join('\n')}`;
+  const text = `$ ${label(cmd)} (exit ${exitCode})\n${evidenceLines.join('\n')}`;
   return { text, rawChars, exitCode };
 }