hydra-nano 0.1.0 → 0.3.0

package/skills/hydra/scripts/hydra.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { readFileSync } from 'node:fs';
+import { existsSync, readFileSync, statSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -10,11 +10,13 @@ import * as git from './lib/git.mjs';
 import * as test_logs from './lib/test_logs.mjs';
 import * as read from './lib/read.mjs';
 import * as osHead from './lib/os.mjs';
-import { record, stats, tokens } from './lib/ledger.mjs';
+import { findings, metered, record, stats, tokens } from './lib/ledger.mjs';
 import { chat, hasModel, BACKEND, modelFor, Unavailable } from './lib/runtime.mjs';
 import { route } from './lib/route.mjs';
 import { stopLocal } from './lib/local.mjs';
 import { hookStatus, installHooks, removeHooks } from './lib/claude_hooks.mjs';
+import * as integrations from './lib/integrations.mjs';
+import * as refactor from './lib/refactor.mjs';
 
 const HEADS = { git, files, test: test_logs, read, os: osHead };
 
@@ -22,19 +24,31 @@ const USAGE = `usage:
   hydra ask "<question>" [--head git|files|test|read|os] answer a question about the repo or system
   hydra search <term...>                               search codebase with definition ranking
   hydra read <file> [symbol|--lines <start-end>]       slice a file, symbol, or show outline
+  hydra smell [file|dir|--diff|--staged]               detect Refactoring.Guru code smells & anti-patterns
+  hydra refactor <file> [symbol|--lines <start-end>]   step-by-step refactoring recipe for a function or range
+  hydra design [pattern|query] [--file <file>]         GoF design pattern advisor & architecture guide
   hydra run [--head test] -- <command...>              run a command and digest test/build output
   hydra os [question...]                               inspect ports, processes, disk, system
   hydra stats                                          token accounting for past calls
+  hydra improve [--since <date>] [--json]              what the local telemetry says to improve
   hydra doctor                                         check that the local model is ready
   hydra setup                                          show runtime setup instructions
   hydra stop                                           stop Hydra's managed llama-server
-  hydra hooks install|remove|status                    Claude Code hooks that route tests and git questions here`;
+  hydra hooks install|remove|status                    Claude Code hooks that route tests and git questions here
+  hydra agents install|remove|status [tool...]         Hydra's MCP server and hooks in codex, cursor, opencode,
+                                                       gemini-cli, antigravity and antigravity-ide (default: every tool found)
+  hydra mcp                                            run the MCP server on stdio`;
 
 function fail(code, message) {
   console.error(message);
   process.exit(code);
 }
 
+// The footer reports a saving; when there is none (short output passed through whole) it is pure cost.
+function withFooter(text, head, raw, returned, seconds) {
+  return returned < raw ? `${text}\n\n[hydra ${head} · read ~${raw} tok locally, returned ~${returned} tok · ${seconds}s]` : text;
+}
+
 async function ask(args) {
   const flag = args.indexOf('--head');
   const forced = flag >= 0 ? args.splice(flag, 2)[1] : undefined;
@@ -47,15 +61,15 @@ async function ask(args) {
   if (head === 'git' && !repo) fail(1, 'hydra: the git head needs a git repository, and this directory is not in one');
 
   const started = Date.now();
-  const headChat = opts => chat({ ...opts, model: modelFor(head) });
-  const sections = await HEADS[head].gather(question, cwd, headChat);
-  const { text, rawChars } = await answer(question, sections, headChat);
+  const meter = metered(opts => chat({ ...opts, model: modelFor(head) }));
+  const sections = await HEADS[head].gather(question, cwd, meter.chat);
+  const { text, rawChars } = await answer(question, sections, meter.chat);
   const raw = tokens(rawChars);
   const returned = tokens(text.length);
   const seconds = Number(((Date.now() - started) / 1000).toFixed(1));
 
-  record({ ts: new Date().toISOString(), head, question, raw, returned, seconds });
-  console.log(`${text}\n\n[hydra ${head} · read ~${raw} tok locally, returned ~${returned} tok · ${seconds}s]`);
+  record({ ts: new Date().toISOString(), head, question, raw, returned, seconds, modelCalls: meter.modelCalls, modelSeconds: meter.modelSeconds });
+  console.log(withFooter(text, head, raw, returned, seconds));
 }
 
 async function runCommand(args) {
@@ -67,13 +81,13 @@ async function runCommand(args) {
       const stdinData = readFileSync(0, 'utf8');
       if (stdinData.trim()) {
         const started = Date.now();
-        const testChat = opts => chat({ ...opts, model: modelFor('test') });
-        const { text, rawChars, exitCode } = await test_logs.digest({ cmd: 'pipe', out: stdinData, exitCode: 1 }, testChat);
+        const meter = metered(opts => chat({ ...opts, model: modelFor('test') }));
+        const { text, rawChars, exitCode } = await test_logs.digest({ cmd: 'pipe', out: stdinData, exitCode: 1 }, meter.chat);
         const raw = tokens(rawChars);
         const returned = tokens(text.length);
         const seconds = Number(((Date.now() - started) / 1000).toFixed(1));
-        record({ ts: new Date().toISOString(), head: 'test', question: 'pipe', raw, returned, seconds });
-        console.log(`${text}\n\n[hydra test · read ~${raw} tok locally, returned ~${returned} tok · ${seconds}s]`);
+        record({ ts: new Date().toISOString(), head: 'test', question: 'pipe', raw, returned, seconds, modelCalls: meter.modelCalls, modelSeconds: meter.modelSeconds });
+        console.log(withFooter(text, 'test', raw, returned, seconds));
         if (exitCode !== 0) process.exit(exitCode);
         return;
       }
@@ -85,18 +99,20 @@ async function runCommand(args) {
   const cwd = process.cwd();
   const started = Date.now();
   const res = await run(prog, progArgs, cwd);
-  const testChat = opts => chat({ ...opts, model: modelFor('test') });
+  const commandSeconds = Number(((Date.now() - started) / 1000).toFixed(1));
+  const meter = metered(opts => chat({ ...opts, model: modelFor('test') }));
   const { text, rawChars, exitCode } = await test_logs.digest({
     cmd: cmdArgs.join(' '),
     out: res.out,
     err: res.err,
     exitCode: res.exitCode,
-  }, testChat);
+  }, meter.chat);
   const raw = tokens(rawChars);
   const returned = tokens(text.length);
   const seconds = Number(((Date.now() - started) / 1000).toFixed(1));
-  record({ ts: new Date().toISOString(), head: 'test', question: cmdArgs.join(' '), raw, returned, seconds });
-  console.log(`${text}\n\n[hydra test · read ~${raw} tok locally, returned ~${returned} tok · ${seconds}s]`);
+  record({ ts: new Date().toISOString(), head: 'test', question: cmdArgs.join(' '), raw, returned, seconds,
+    commandSeconds, exit: exitCode, modelCalls: meter.modelCalls, modelSeconds: meter.modelSeconds });
+  console.log(withFooter(text, 'test', raw, returned, seconds));
   if (exitCode !== 0) process.exit(exitCode);
 }
 
@@ -147,21 +163,21 @@ async function readCommand(args) {
     seconds,
   });
 
-  console.log(`${res.text}\n\n[hydra read · read ~${raw} tok locally, returned ~${returned} tok · ${seconds}s]`);
+  console.log(withFooter(res.text, 'read', raw, returned, seconds));
 }
 
 async function osCommand(args) {
   const question = args.join(' ').trim() || 'system overview';
   const started = Date.now();
-  const osChat = opts => chat({ ...opts, model: modelFor('os') });
-  const sections = await osHead.gather(question, process.cwd(), osChat);
-  const { text, rawChars } = await answer(question, sections, osChat);
+  const meter = metered(opts => chat({ ...opts, model: modelFor('os') }));
+  const sections = await osHead.gather(question, process.cwd(), meter.chat);
+  const { text, rawChars } = await answer(question, sections, meter.chat);
   const raw = tokens(rawChars);
   const returned = tokens(text.length);
   const seconds = Number(((Date.now() - started) / 1000).toFixed(1));
 
-  record({ ts: new Date().toISOString(), head: 'os', question, raw, returned, seconds });
-  console.log(`${text}\n\n[hydra os · read ~${raw} tok locally, returned ~${returned} tok · ${seconds}s]`);
+  record({ ts: new Date().toISOString(), head: 'os', question, raw, returned, seconds, modelCalls: meter.modelCalls, modelSeconds: meter.modelSeconds });
+  console.log(withFooter(text, 'os', raw, returned, seconds));
 }
 
 async function searchCommand(args) {
@@ -201,7 +217,7 @@ async function searchCommand(args) {
     seconds,
   });
 
-  console.log(`${text}\n\n[hydra files · read ~${raw} tok locally, returned ~${returned} tok · ${seconds}s]`);
+  console.log(withFooter(text, 'files', raw, returned, seconds));
 }
 
 function showStats() {
@@ -218,6 +234,30 @@ Estimate: output size / 4. It counts the output an agent would have read by runn
 the commands itself, and leaves out the extra turns those commands would have cost.`);
 }
 
+function improve(args) {
+  const flag = args.indexOf('--since');
+  const since = flag >= 0 ? args[flag + 1] : undefined;
+  if (flag >= 0 && (!since || Number.isNaN(Date.parse(since)))) fail(1, 'usage: hydra improve [--since <date>] [--json]');
+  const report = findings(undefined, { since: since && new Date(since).toISOString() });
+  if (args.includes('--json')) return console.log(JSON.stringify(report, null, 2));
+  const lines = [`since ${report.since ?? 'the start'}: ${report.calls} calls; ${report.sessions.usingHydra} of ${report.sessions.seen} recorded sessions used Hydra`];
+  for (const [head, h] of Object.entries(report.perHead)) {
+    lines.push(`${head.padEnd(6)} ${h.calls} calls, saved ~${h.saved} tok (${Math.round(h.savedShare * 100)}%), ` +
+      `${h.costMore} cost more than raw, p50 ${h.p50Seconds}s, p90 ${h.p90Seconds}s, ${h.modelCalls} model calls`);
+    for (const row of h.costMoreExamples) lines.push(`         cost more: ${row.question.slice(0, 80)} (${row.raw} -> ${row.returned})`);
+  }
+  for (const [agent, a] of Object.entries(report.agents)) {
+    lines.push(`agent  ${agent}: ${a.calls} calls (${a.viaMcp} through MCP), ${a.denials} runs turned back, ${a.sessions} sessions started`);
+  }
+  const { denials, followedByHydra, trimmed, rawBypasses } = report.hooks;
+  const { decisions, p50Ms, p90Ms } = report.hooks;
+  lines.push(`hooks  ${decisions} Bash calls checked (p50 ${p50Ms} ms, p90 ${p90Ms} ms); ${denials} test/build runs turned back, ` +
+    `${followedByHydra} followed by a Hydra run within 5 minutes; ${trimmed} let through already cut short (| tail -n N)`);
+  for (const command of rawBypasses) lines.push(`         HYDRA_RAW=1 bypass (check for a false match): ${command.slice(0, 100)}`);
+  for (const error of report.errors) lines.push(`error  ${error.ts} ${error.command}: ${error.error}`);
+  console.log(lines.join('\n'));
+}
+
 async function doctor() {
   const checks = new Map();
   const modelStatuses = await Promise.all(
@@ -258,6 +298,180 @@ This command prints instructions only; it does not install, download or launch a
   }
 }
 
+async function smellCommand(args) {
+  const isJson = args.includes('--json');
+  const isDiff = args.includes('--diff');
+  const isStaged = args.includes('--staged');
+  const target = args.filter(a => !a.startsWith('--'))[0] || (isDiff || isStaged ? '.' : process.cwd());
+
+  const started = Date.now();
+  let text = '';
+  let rawChars = 0;
+
+  if (isDiff || isStaged) {
+    const gitArgs = ['diff'];
+    if (isStaged) gitArgs.push('--staged');
+    const diffRes = await run('git', gitArgs, process.cwd());
+    const diffOutput = diffRes.out || '';
+    rawChars = diffOutput.length;
+    const diffReport = refactor.scanDiff(diffOutput);
+    if (isJson) {
+      text = JSON.stringify(diffReport, null, 2);
+    } else {
+      if (!diffReport.filesWithSmells) {
+        text = '✔ No code smells introduced in this diff.';
+      } else {
+        text = `[hydra smell] ${diffReport.filesWithSmells} changed files with smells:\n\n` +
+          diffReport.reports.map(r => refactor.formatSmellReport(r)).join('\n\n');
+      }
+    }
+  } else {
+    const resolved = path.resolve(target);
+    if (!existsSync(resolved)) fail(1, `hydra smell: path not found: ${target}`);
+    const isDir = statSync(resolved).isDirectory();
+    if (isDir) {
+      const dirReport = refactor.scanDirectory(resolved);
+      rawChars = dirReport.reports.reduce((s, r) => s + r.totalLines * 30, 100);
+      if (isJson) {
+        text = JSON.stringify(dirReport, null, 2);
+      } else {
+        if (!dirReport.filesWithSmells) {
+          text = `✔ ${target}: No code smells detected across scanned files.`;
+        } else {
+          text = `[hydra smell] ${dirReport.totalSmells} smells across ${dirReport.filesWithSmells} files in ${target}:\n\n` +
+            dirReport.reports.map(r => refactor.formatSmellReport(r)).join('\n\n');
+        }
+      }
+    } else {
+      const report = refactor.scanFile(resolved);
+      rawChars = report.totalLines * 35;
+      text = isJson ? JSON.stringify(report, null, 2) : refactor.formatSmellReport(report);
+    }
+  }
+
+  const raw = tokens(rawChars);
+  const returned = tokens(text.length);
+  const seconds = Number(((Date.now() - started) / 1000).toFixed(2));
+
+  record({
+    ts: new Date().toISOString(),
+    head: 'refactor',
+    question: `smell ${args.join(' ')}`,
+    raw,
+    returned,
+    seconds,
+  });
+
+  console.log(withFooter(text, 'smell', raw, returned, seconds));
+}
+
+async function refactorCommand(args) {
+  const isJson = args.includes('--json');
+  const cleanArgs = args.filter(a => a !== '--json');
+  if (cleanArgs.length === 0) fail(1, 'usage: hydra refactor <file> [symbol|--lines <start-end>]');
+
+  let fileArg = null;
+  let symbol = null;
+  let lines = null;
+
+  for (let i = 0; i < cleanArgs.length; i++) {
+    const arg = cleanArgs[i];
+    if (arg === '--lines' && i + 1 < cleanArgs.length) {
+      lines = cleanArgs[++i];
+    } else if (arg.startsWith('--lines=')) {
+      lines = arg.slice('--lines='.length);
+    } else if (/^\d+[:-]\d+$/.test(arg)) {
+      lines = arg;
+    } else if (!fileArg) {
+      fileArg = arg;
+    } else if (!symbol) {
+      symbol = arg;
+    }
+  }
+
+  if (!fileArg) fail(1, 'usage: hydra refactor <file> [symbol|--lines <start-end>]');
+  const resolved = path.resolve(fileArg);
+  if (!existsSync(resolved) || statSync(resolved).isDirectory()) {
+    fail(1, `hydra refactor: file not found: ${fileArg}`);
+  }
+
+  const started = Date.now();
+  const content = readFileSync(resolved, 'utf8');
+
+  let startLine, endLine;
+  if (lines) {
+    const [s, e] = lines.split(/[:-]/).map(Number);
+    startLine = s;
+    endLine = e;
+  }
+
+  const recipe = refactor.generateRecipe(content, { symbol, startLine, endLine });
+  const rawChars = content.length;
+  const text = isJson ? JSON.stringify(recipe, null, 2) : refactor.formatRecipe(recipe);
+
+  const raw = tokens(rawChars);
+  const returned = tokens(text.length);
+  const seconds = Number(((Date.now() - started) / 1000).toFixed(2));
+
+  record({
+    ts: new Date().toISOString(),
+    head: 'refactor',
+    question: `refactor ${fileArg}${symbol ? ` ${symbol}` : ''}`,
+    raw,
+    returned,
+    seconds,
+  });
+
+  console.log(withFooter(text, 'refactor', raw, returned, seconds));
+}
+
+async function designCommand(args) {
+  const isJson = args.includes('--json');
+  let fileArg = null;
+  const words = [];
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--json') continue;
+    if (arg === '--file' && i + 1 < args.length) {
+      fileArg = args[++i];
+    } else if (arg.startsWith('--file=')) {
+      fileArg = arg.slice('--file='.length);
+    } else {
+      words.push(arg);
+    }
+  }
+
+  const query = words.join(' ').trim();
+  let codeSnippet = '';
+  if (fileArg) {
+    const resolved = path.resolve(fileArg);
+    if (existsSync(resolved) && !statSync(resolved).isDirectory()) {
+      codeSnippet = readFileSync(resolved, 'utf8').slice(0, 5000);
+    }
+  }
+
+  const started = Date.now();
+  const adv = refactor.advisePattern(query, codeSnippet);
+  const text = isJson ? JSON.stringify(adv, null, 2) : refactor.formatPattern(adv);
+
+  const seconds = Number(((Date.now() - started) / 1000).toFixed(2));
+
+  // A pattern lookup replaces no command output, so it has no raw baseline: it counts as neither a
+  // saving nor a cost, and its size is kept apart.
+  record({
+    ts: new Date().toISOString(),
+    head: 'refactor',
+    question: `design ${query}`,
+    raw: 0,
+    returned: 0,
+    replyTokens: tokens(text.length),
+    seconds,
+  });
+
+  console.log(text);
+}
+
 const [command, ...rest] = process.argv.slice(2);
 const commands = {
   ask: () => ask(rest),
@@ -266,14 +480,43 @@ const commands = {
   run: () => runCommand(rest),
   test: () => runCommand(rest),
   read: () => readCommand(rest),
+  smell: () => smellCommand(rest),
+  refactor: () => refactorCommand(rest),
+  design: () => designCommand(rest),
   os: () => osCommand(rest),
   stats: showStats,
+  improve: () => improve(rest),
   doctor,
   setup,
   stop: () => console.log(stopLocal() ? 'Hydra local server stopped.' : 'No managed Hydra server is running.'),
   hooks: () => hooksCommand(rest[0]),
+  agents: () => agentsCommand(rest),
+  mcp: () => import('./mcp.mjs').then(server => server.serve()),
 };
 
+function agentsCommand(args) {
+  const [action, ...words] = args;
+  const ids = words.filter(word => !word.startsWith('--'));
+  if (action === 'status') {
+    for (const row of integrations.status()) {
+      console.log(`${row.id.padEnd(15)} ${row.present ? 'found    ' : 'not found'}  mcp ${row.mcp ? 'yes' : 'no '}${'hooks' in row ? `  hooks ${row.hooks ? 'yes' : 'no'}` : ''}${'skill' in row ? `  skill ${row.skill ? 'yes' : 'no'}` : ''}`);
+    }
+    console.log(`claude-code     ${hookStatus().length ? 'hooks yes' : 'hooks no'} (skill and hooks; see hydra hooks status)`);
+    return;
+  }
+  if (!['install', 'remove'].includes(action)) fail(1, 'usage: hydra agents install|remove|status [codex cursor opencode gemini-cli antigravity antigravity-ide] [--no-hooks]');
+  const scripts = action === 'install'
+    ? integrations.installSharedScripts(path.dirname(fileURLToPath(import.meta.url))) : integrations.sharedScripts();
+  const targets = ids.length ? ids : action === 'install' ? integrations.detected(scripts) : Object.keys(integrations.tools(scripts));
+  if (!targets.length) return console.log('No supported coding tool found (codex, cursor, opencode, gemini-cli, antigravity, antigravity-ide).');
+  for (const result of integrations.apply(targets, action, { scripts, hooks: !words.includes('--no-hooks') })) {
+    if (result.error) { console.log(`${result.id}: ${result.error}`); continue; }
+    console.log(`${result.id}: ${result.changes.length ? result.changes.join('; ') : action === 'install' ? 'nothing changed' : 'nothing to remove'}`);
+    for (const message of result.manual) console.log(`  ${message.replace(/\n/g, '\n  ')}`);
+    if (result.note) console.log(`  ${result.note}`);
+  }
+}
+
 function hooksCommand(action) {
   const scripts = path.dirname(fileURLToPath(import.meta.url));
   if (action === 'install') console.log(`Hydra hooks registered in ${installHooks(scripts)}.`);
@@ -286,6 +529,7 @@ try {
   if (!commands[command]) fail(1, USAGE);
   await commands[command]();
 } catch (e) {
+  record({ ts: new Date().toISOString(), kind: 'error', command, error: String(e?.message ?? e).slice(0, 300) });
   if (!(e instanceof Unavailable)) throw e;
   fail(2, `hydra unavailable: ${e.message}`);
 }

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,12 +29,116 @@ 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. */
+/** 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. With pipes false, a pipeline
+ * (a | b) stays one piece. */
+export function simpleCommands(command, { pipes = true } = {}) {
+  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 === '|' && !pipes) {
+      current += c;
+    } 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);
+
+// A later pipeline stage that keeps at most this many lines leaves little for Hydra to save.
+const FEW_LINES = 40;
+
+/** A pipeline stage that cuts its input to a few lines or a count: tail/head of at most FEW_LINES
+ * lines (10 when not given), grep -c, or wc. tail -f and tail -n +N can return everything. */
+function cutsShort(stage) {
+  const [name, ...args] = stage.split(/\s+/);
+  if (name === 'wc') return true;
+  if (name === 'grep' || name === 'rg') return args.some(arg => /^-[a-zA-Z]*c[a-zA-Z]*$/.test(arg) || arg === '--count');
+  if (name !== 'tail' && name !== 'head') return false;
+  let lines = 10;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (/^-[a-zA-Z]*[fF]/.test(arg) || arg.startsWith('--follow')) return false;
+    const value = /^-\d+$/.test(arg) ? arg.slice(1) : arg === '-n' || arg === '--lines' ? args[++i]
+      : /^-n./.test(arg) ? arg.slice(2) : arg.startsWith('--lines=') ? arg.slice(8) : null;
+    if (value === null) continue;
+    if (!/^\d+$/.test(value ?? '')) return false;
+    lines = Number(value);
+  }
+  return lines <= FEW_LINES;
+}
+
+/** Each test/build run in a shell line, and whether its own pipeline cuts the output short. */
+function runsIn(command) {
+  return simpleCommands(command, { pipes: false }).flatMap(pipeline => {
+    const stages = simpleCommands(pipeline).map(part => part.replace(/^(?:\w+=\S*\s+)+/, ''));
+    const at = stages.findIndex(part => RUNNERS.some(re => re.test(part)));
+    return at < 0 ? [] : [{ run: stages[at].replace(/\s+2>&1\s*$/, ''), cut: stages.slice(at + 1).some(cutsShort) }];
+  });
+}
+
+const passesAnyway = command => !command || ownRun(command) || /\bHYDRA_RAW=1\b/.test(command);
+
+/** The test/build run inside a shell command that would put its whole log in context, or null.
+ * Hydra's own runs, HYDRA_RAW=1 and runs already cut to a few lines (| tail -n 15) 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+)+/, ''))
-    .find(part => RUNNERS.some(re => re.test(part)));
-  return run ? run.replace(/\s+2>&1\s*$/, '') : null;
+  if (passesAnyway(command)) return null;
+  return runsIn(command).find(run => !run.cut)?.run ?? null;
+}
+
+/** A command whose every test/build run is already cut to a few lines by its own pipeline. */
+export function trimmedRun(command) {
+  if (passesAnyway(command)) return false;
+  const runs = runsIn(command);
+  return runs.length > 0 && runs.every(run => run.cut);
+}
+
+/** 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)
+    && runsIn(command.replace(/\bHYDRA_RAW=1\s+/g, '')).length > 0;
 }
 
 function load(file) {