@hone-ai/cli 1.18.0 → 1.20.0

package/lib/materialize-diff.js

@@ -0,0 +1,345 @@
+'use strict';
+/**
+ * materialize-diff.js — HC-019n-followup-23 (pipeline-recovery condition 5).
+ *
+ * step_4 stopped hand-writing unified diffs and now emits WHOLE-FILE contents
+ * (see the ## Changed Files prompt contract). The reason: an LLM counts a short
+ * hunk header correctly and a long one wrong — confirmation run 2c5065ad claimed
+ * `@@ -0,0 +1,65 @@` for a block that actually had 55 lines, and no prompt
+ * wording fixes that. So the LLM writes files (what it is good at) and `git diff`
+ * computes the hunks (what it is good at, and authoritatively — a diff git
+ * produces is one `git apply` accepts by construction).
+ *
+ * This module is split like patch-apply.js: the PURE half (parsing the file
+ * blocks out of step_4 output) is here and unit-tested; the git invocation that
+ * turns a candidate file into a diff needs a real tree and lives in the CLI
+ * command, calling buildFileDiff() with an injected runner so it too can be
+ * tested.
+ *
+ * See .github/pipeline/HC-019n-followup-23/architect.md for why whole-file
+ * emission (Option A) beat structured old/new-string edits (Option B).
+ */
+const path = require('node:path');
+
+/**
+ * A ```file:<path> fenced block, capturing the path and the verbatim body.
+ * Info-string tolerant: ```file:foo, ``` file: foo, ```FILE:foo all match.
+ */
+const FILE_BLOCK_RE = /```[ \t]*file[ \t]*:[ \t]*([^\n`]+?)[ \t]*\r?\n([\s\S]*?)\r?\n```/gi;
+
+/**
+ * A ```edit:<path> fenced block — HC-019n-followup-27. For a file too big to
+ * bundle whole (>25K chars, truncated/windowed), step_4 cannot emit a whole-file
+ * block (it never saw the whole file). Instead it emits a REGION edit: a unique
+ * OLD anchor (from the excerpt it WAS shown) and its NEW replacement, framed with
+ * conflict markers. The CLI applies OLD→NEW to the REAL full file on disk and
+ * lets git build the diff — so the count stays git's, exactly as for whole-file
+ * blocks. See .github/pipeline/HC-019n-followup-27/architect.md.
+ */
+const EDIT_BLOCK_RE = /```[ \t]*edit[ \t]*:[ \t]*([^\n`]+?)[ \t]*\r?\n([\s\S]*?)\r?\n```/gi;
+
+/**
+ * The OLD/NEW split inside an edit block. `<<<<<<< OLD` … `=======` … `>>>>>>> NEW`.
+ * Whitespace after the marker word is tolerated; the bodies are captured verbatim
+ * (indentation is part of the anchor).
+ */
+const EDIT_SPLIT_RE = /^<{3,}[ \t]*OLD[ \t]*\r?\n([\s\S]*?)\r?\n={3,}[ \t]*\r?\n([\s\S]*?)\r?\n>{3,}[ \t]*NEW[ \t]*$/m;
+
+/** A `DELETE: <path>` line inside the ## Changed Files section. */
+const DELETE_RE = /^[ \t]*DELETE:[ \t]*(\S.*?)[ \t]*$/gim;
+
+/**
+ * Typed error for the region-edit apply path, so a consumer can map it to a
+ * distinct exit code and a message that tells step_4 how to fix its anchor.
+ * `.code` is one of 'anchor_not_found' | 'anchor_ambiguous' | 'file_not_found'.
+ */
+class MaterializeError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = 'MaterializeError';
+    this.code = code;
+  }
+}
+
+/**
+ * Parse step_4 output into a set of intended file states.
+ *
+ * @param {string} output  raw step_4 output
+ * @returns {{
+ *   files: Array<{ path: string, contents: string }>,
+ *   deletes: string[],
+ *   noChanges: boolean,
+ *   reason: string|null
+ * }}
+ */
+function extractFileBlocks(output) {
+  const text = String(output || '');
+  const empty = { files: [], edits: [], deletes: [], noChanges: false, reason: null };
+
+  // Scope everything to the ## Changed Files section if present, so a code
+  // sample elsewhere in the prose is never mistaken for an intended file.
+  const secIdx = text.search(/^##\s+Changed Files/im);
+  const scope = secIdx === -1 ? text : text.slice(secIdx);
+
+  // Honest no-op, same shape as the followup-19 NO CHANGES escape. A NO CHANGES
+  // declaration only counts when there is NO file AND NO edit block to apply.
+  const hasBlock = (FILE_BLOCK_RE.test(scope) || EDIT_BLOCK_RE.test(scope));
+  FILE_BLOCK_RE.lastIndex = 0; EDIT_BLOCK_RE.lastIndex = 0;
+  const noChange = scope.match(/NO CHANGES\b[ \t]*[—:-]?[ \t]*([^\n]*)/i);
+  if (noChange && !hasBlock) {
+    return { ...empty, noChanges: true, reason: (noChange[1] || '').trim() || null };
+  }
+
+  const files = [];
+  const seen = new Set();
+  for (const m of scope.matchAll(FILE_BLOCK_RE)) {
+    const rel = normalizeRepoPath(m[1]);
+    if (!rel) continue;            // rejected (traversal/absolute) — see below
+    if (seen.has(rel)) continue;   // first block wins on a dup path
+    seen.add(rel);
+    files.push({ path: rel, contents: m[2] });
+  }
+
+  // HC-019n-followup-27: region edits for files too big to bundle whole.
+  const edits = [];
+  const editSeen = new Set();
+  for (const m of scope.matchAll(EDIT_BLOCK_RE)) {
+    const rel = normalizeRepoPath(m[1]);
+    if (!rel) continue;
+    if (seen.has(rel) || editSeen.has(rel)) continue; // a whole-file block wins; first edit wins
+    const split = EDIT_SPLIT_RE.exec(m[2]);
+    if (!split) continue;          // malformed edit block (no OLD/NEW markers) — skip
+    editSeen.add(rel);
+    edits.push({ path: rel, oldString: split[1], newString: split[2] });
+  }
+
+  const deletes = [];
+  for (const m of scope.matchAll(DELETE_RE)) {
+    const rel = normalizeRepoPath(m[1]);
+    if (rel && !deletes.includes(rel)) deletes.push(rel);
+  }
+
+  return { files, edits, deletes, noChanges: false, reason: null };
+}
+
+/**
+ * Apply a region edit to the real full file contents, deterministically.
+ *
+ * The OLD anchor MUST occur exactly once — this is the entire safety property.
+ * Zero matches (step_4 hallucinated the anchor, or the file drifted) or many
+ * matches (ambiguous — applying to the wrong instance would corrupt) are hard
+ * errors, never a silent partial write. The count check is against the REAL
+ * full file, so a window-unique-but-file-ambiguous anchor is still caught.
+ *
+ * @param {string} fileContents real full file contents
+ * @param {string} oldString    the OLD anchor (verbatim)
+ * @param {string} newString    the NEW replacement
+ * @param {string} repoPath     for error messages
+ * @returns {string} the candidate file contents (OLD replaced by NEW, once)
+ * @throws {MaterializeError} code 'anchor_not_found' | 'anchor_ambiguous'
+ */
+function applyEdit(fileContents, oldString, newString, repoPath) {
+  const src = String(fileContents);
+  const anchor = String(oldString);
+  if (!anchor) {
+    throw new MaterializeError('anchor_not_found', `${repoPath}: edit block has an empty OLD anchor`);
+  }
+  const count = countOccurrences(src, anchor);
+  if (count === 0) {
+    const firstLine = anchor.split('\n').find(l => l.trim()) || anchor.slice(0, 60);
+    throw new MaterializeError('anchor_not_found',
+      `${repoPath}: OLD anchor not found (starts: ${JSON.stringify(firstLine.trim().slice(0, 60))}). ` +
+      `The file may have changed, or the anchor was not copied verbatim.`);
+  }
+  if (count > 1) {
+    throw new MaterializeError('anchor_ambiguous',
+      `${repoPath}: OLD anchor matched ${count} times — include more surrounding context so it is unique.`);
+  }
+  const idx = src.indexOf(anchor);
+  return src.slice(0, idx) + String(newString) + src.slice(idx + anchor.length);
+}
+
+/** Non-overlapping occurrence count of `needle` in `hay` (literal, not regex). */
+function countOccurrences(hay, needle) {
+  if (!needle) return 0;
+  let n = 0, i = 0;
+  for (;;) {
+    const at = hay.indexOf(needle, i);
+    if (at === -1) return n;
+    n += 1;
+    i = at + needle.length;
+  }
+}
+
+/**
+ * Assemble one unified diff from parsed blocks — the SHARED materialization used
+ * by check-patch, verify-patch, and emit-pr (HC-019n-followup-27 de-triplicated
+ * what was three copies of this loop). Whole-file blocks, region edits, and
+ * deletes all resolve to git-authored hunks.
+ *
+ * Injected primitives keep it testable without a real repo:
+ *   - runGitDiff(origArg, candidatePath) → { stdout, code }  (git diff --no-index)
+ *   - readFile(repoRelPath) → string|null                    (real full file, or null)
+ *   - exists(repoRelPath) → boolean
+ *   - tmpFile(contents) → { path, cleanup }                  (write a temp candidate)
+ *
+ * @returns {{ diff: string, partCount: number }}
+ * @throws {MaterializeError} from the region-edit apply path
+ */
+function buildDiff(blocks, { runGitDiff, readFile, exists, tmpFile }) {
+  const parts = [];
+
+  // 1. Whole-file blocks (followup-23 Option A) — unchanged behaviour.
+  for (const f of blocks.files) {
+    const isNew = !exists(f.path);
+    const t = tmpFile(f.contents.endsWith('\n') ? f.contents : f.contents + '\n');
+    try {
+      const built = buildFileDiff({
+        repoPath: f.path, isNew,
+        runGitDiff: () => runGitDiff(isNew ? '/dev/null' : f.path, t.path),
+      });
+      if (built.changed) parts.push(built.diff);
+    } finally { t.cleanup(); }
+  }
+
+  // 2. Region edits (followup-27) — apply OLD→NEW to the REAL file, git-diff it.
+  for (const e of blocks.edits || []) {
+    const real = readFile(e.path);
+    if (real == null) {
+      throw new MaterializeError('file_not_found',
+        `${e.path}: cannot apply edit — file not found in the working tree`);
+    }
+    const candidate = applyEdit(real, e.oldString, e.newString, e.path); // throws typed on 0/many
+    const t = tmpFile(candidate.endsWith('\n') ? candidate : candidate + '\n');
+    try {
+      const built = buildFileDiff({
+        repoPath: e.path, isNew: false,
+        runGitDiff: () => runGitDiff(e.path, t.path),
+      });
+      if (built.changed) parts.push(built.diff);
+    } finally { t.cleanup(); }
+  }
+
+  // 3. Deletions — a whole-file removal hunk against the real file on disk.
+  for (const del of blocks.deletes || []) {
+    if (!exists(del)) continue;
+    const body = readFile(del);
+    if (body == null) continue;
+    const lines = body.replace(/\n$/, '').split('\n');
+    parts.push(
+      `diff --git a/${del} b/${del}\n--- a/${del}\n+++ /dev/null\n` +
+      `@@ -1,${lines.length} +0,0 @@\n` + lines.map(l => `-${l}`).join('\n') + '\n');
+  }
+
+  return { diff: parts.join(''), partCount: parts.length };
+}
+
+/**
+ * Reject anything that could escape the repo root; normalize separators.
+ * Returns null for an unsafe or empty path.
+ */
+function normalizeRepoPath(p) {
+  const raw = String(p || '').trim().replace(/^["'`]|["'`]$/g, '');
+  if (!raw) return null;
+  if (raw.startsWith('/') || raw.startsWith('~') || raw.includes('..')) return null;
+  // Collapse ./ and duplicate slashes without resolving against the FS.
+  const norm = path.posix.normalize(raw).replace(/^\.\//, '');
+  if (norm.startsWith('/') || norm.startsWith('..')) return null;
+  return norm;
+}
+
+/**
+ * Rewrite the temp paths in a `git diff --no-index` result to the real repo
+ * path. git emits `--- a/<tmp>` / `+++ b/<tmp>` (and a `diff --git` line); the
+ * assembled patch must name the repo-relative path so it applies at repo root.
+ *
+ * @param {string} rawDiff  output of `git diff --no-index <orig> <candidate>`
+ * @param {string} repoPath repo-relative destination path
+ * @param {boolean} isNew    true when the original did not exist (create-file)
+ * @returns {string}
+ */
+function rewriteDiffPaths(rawDiff, repoPath, isNew) {
+  if (!rawDiff) return '';
+  const src = isNew ? '/dev/null' : `a/${repoPath}`;
+  return rawDiff
+    .replace(/^diff --git .*$/m, `diff --git a/${repoPath} b/${repoPath}`)
+    .replace(/^--- .*$/m, `--- ${src}`)
+    .replace(/^\+\+\+ .*$/m, `+++ b/${repoPath}`);
+}
+
+/**
+ * Assemble a full unified diff for one file, given an injected git runner.
+ *
+ * The runner takes (origPathOrDevNull, candidatePath) and returns
+ * { stdout, code } from `git diff --no-index` (which exits 1 when they differ,
+ * 0 when identical — NOT an error). Kept injectable so this is unit-testable
+ * without a real FS; the CLI passes a runner that writes temp files and shells
+ * out to git.
+ *
+ * @returns {{ diff: string, changed: boolean }}
+ */
+function buildFileDiff({ repoPath, isNew, runGitDiff }) {
+  const { stdout, code } = runGitDiff();
+  // code 0 => no difference (candidate equals original) => nothing to emit.
+  if (code === 0 || !stdout || !stdout.trim()) {
+    return { diff: '', changed: false };
+  }
+  return { diff: ensureTrailingNewline(rewriteDiffPaths(stdout, repoPath, isNew)), changed: true };
+}
+
+function ensureTrailingNewline(s) {
+  return s.replace(/\s*$/, '') + '\n';
+}
+
+/**
+ * The real node-backed IO for buildDiff: reads the adopter's files off disk,
+ * writes temp candidates, and shells out to `git diff --no-index` with the
+ * ambient git env stripped (gitEnv). Lazily requires its deps so this module
+ * stays side-effect-free to import for the pure-function unit tests.
+ *
+ * @param {{cwd?: string}} [o]
+ * @returns {{ exists: Function, readFile: Function, tmpFile: Function, runGitDiff: Function }}
+ */
+function nodeMaterializeIO({ cwd = process.cwd() } = {}) {
+  const fs = require('node:fs');
+  const os = require('node:os');
+  const p = require('node:path');
+  const { execFileSync } = require('node:child_process');
+  const { gitEnv } = require('./git-env');
+  let n = 0;
+  return {
+    exists: (rel) => fs.existsSync(p.resolve(cwd, rel)),
+    readFile: (rel) => {
+      const abs = p.resolve(cwd, rel);
+      return fs.existsSync(abs) ? fs.readFileSync(abs, 'utf8') : null;
+    },
+    tmpFile: (contents) => {
+      const tp = p.join(os.tmpdir(), `hone-mat-${process.pid}-${Date.now()}-${n++}`);
+      fs.writeFileSync(tp, contents);
+      return { path: tp, cleanup: () => { try { fs.unlinkSync(tp); } catch { /* best-effort */ } } };
+    },
+    runGitDiff: (origArg, candPath) => {
+      let stdout = '', code = 0;
+      try {
+        stdout = execFileSync('git', ['diff', '--no-index', '--', origArg, candPath],
+          { cwd, env: gitEnv(), encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+      } catch (e) { code = e.status || 1; stdout = (e.stdout || '').toString(); }
+      return { stdout, code };
+    },
+  };
+}
+
+module.exports = {
+  extractFileBlocks,
+  normalizeRepoPath,
+  rewriteDiffPaths,
+  buildFileDiff,
+  buildDiff,
+  nodeMaterializeIO,
+  applyEdit,
+  countOccurrences,
+  ensureTrailingNewline,
+  MaterializeError,
+  FILE_BLOCK_RE,
+  EDIT_BLOCK_RE,
+};

package/lib/mcp-tools.js

@@ -0,0 +1,310 @@
+'use strict';
+/**
+ * mcp-tools.js — HC-COMM-012 (A1 P1): the agent-eval/pipeline tool HANDLERS behind
+ * the Hone MCP server. Kept separate from the MCP protocol wiring (mcp-server.js)
+ * so the logic is unit-testable without the SDK or a real MCP client.
+ *
+ * Design (architect memo HC-COMM-012 §3): these handlers SHELL OUT to the installed
+ * `hone` CLI verbs — the one execution implementation — and parse their output. They
+ * re-implement nothing: `verify-patch` etc. still run in the CLI, honoring the
+ * server↔CLI boundary. Pure parsers are exported so the parsing is tested directly.
+ */
+const { spawn } = require('node:child_process');
+const fsSync = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+// Resolve the CLI binary. Default `hone` (the installed bin); overridable for tests
+// / non-global installs via HONE_CLI_BIN (e.g. a path to hone-cli.js run with node).
+function honeBin() {
+  return process.env.HONE_CLI_BIN || 'hone';
+}
+
+// Resolve token + apiUrl the SAME way the CLI's getConfig does (env → ~/.honerc →
+// default) — but WITHOUT exiting on a missing token (the MCP server must start and
+// report the problem via a preflight / hone_doctor, not die). Editor-agnostic:
+// works from any MCP client that passes HONE_TOKEN/HONE_API in the server env.
+function readHoneConfig() {
+  let rc = {};
+  try { rc = JSON.parse(fsSync.readFileSync(path.join(os.homedir(), '.honerc'), 'utf8')) || {}; } catch { rc = {}; }
+  const token = process.env.HONE_TOKEN || rc.token || null;
+  const apiUrl = process.env.HONE_API || rc.api || 'https://api.hone.ai';
+  return { token, apiUrl, hasToken: !!token };
+}
+
+// Run a `hone` subcommand, capturing stdout/stderr/exit. Never throws — returns a
+// structured result (mirrors the executor's never-throw contract).
+function runHone(args, { cwd, timeoutMs = 120000 } = {}) {
+  return new Promise((resolve) => {
+    let child;
+    let stdout = '';
+    let stderr = '';
+    let timedOut = false;
+    try {
+      child = spawn(honeBin(), args, { cwd: cwd || process.cwd(), stdio: ['ignore', 'pipe', 'pipe'] });
+    } catch (e) {
+      return resolve({ ok: false, exitCode: null, stdout: '', stderr: '', error: e.code === 'ENOENT' ? 'hone CLI not found on PATH' : e.message });
+    }
+    const timer = setTimeout(() => { timedOut = true; try { child.kill('SIGTERM'); } catch { /* gone */ } }, timeoutMs);
+    child.stdout.on('data', (c) => { stdout += c.toString(); });
+    child.stderr.on('data', (c) => { stderr += c.toString(); });
+    child.on('error', (e) => { clearTimeout(timer); resolve({ ok: false, exitCode: null, stdout, stderr, error: e.code === 'ENOENT' ? 'hone CLI not found on PATH' : e.message }); });
+    child.on('close', (code) => {
+      clearTimeout(timer);
+      if (timedOut) return resolve({ ok: false, exitCode: null, stdout, stderr, error: `timed out after ${timeoutMs}ms` });
+      resolve({ ok: code === 0, exitCode: code, stdout, stderr });
+    });
+  });
+}
+
+// ── Pure parsers (unit-tested directly) ──────────────────────────────────────
+
+// `hone run-story <id>` prints "Workflow started: <uuid>" on success.
+function parseRunStarted(stdout) {
+  const m = String(stdout).match(/Workflow started:\s*([0-9a-f-]{8,})/i);
+  return m ? m[1] : null;
+}
+
+// `--format json` output: the LAST JSON object/array in stdout (grounding logs may
+// precede it). Returns the parsed value or null.
+function parseLastJson(stdout) {
+  const s = String(stdout);
+  // find the last top-level '{' or '[' and try to parse from there to the end
+  for (const open of ['{', '[']) {
+    const i = s.lastIndexOf('\n' + open);
+    const start = i >= 0 ? i + 1 : (s.trimStart().startsWith(open) ? s.indexOf(open) : -1);
+    if (start < 0) continue;
+    try { return JSON.parse(s.slice(start).trim()); } catch { /* try the other bracket */ }
+  }
+  try { return JSON.parse(s.trim()); } catch { return null; }
+}
+
+// ── Tool handlers ────────────────────────────────────────────────────────────
+
+// hone_run_story — start a run. Pure API path in the CLI (POST /orchestrate).
+async function runStory({ storyId, mode = 'batch', cwd } = {}) {
+  if (storyId === undefined || storyId === null || String(storyId).trim() === '') {
+    return { isError: true, detail: 'storyId is required' };
+  }
+  const r = await runHone(['run-story', String(storyId), '--mode', String(mode)], { cwd });
+  if (r.error) return { isError: true, detail: r.error };
+  const runId = parseRunStarted(r.stdout);
+  return {
+    isError: !runId && !r.ok,
+    runId,
+    exitCode: r.exitCode,
+    detail: runId ? `run started: ${runId}` : (r.stderr || r.stdout || 'run-story produced no workflow id').slice(0, 500),
+  };
+}
+
+// hone_status — read run status (readOnly). GET /orchestrate/:id.
+async function status({ runId, cwd } = {}) {
+  if (!runId) return { isError: true, detail: 'runId is required' };
+  const r = await runHone(['run-story', String(runId), '--status', '--format', 'json'], { cwd });
+  if (r.error) return { isError: true, detail: r.error };
+  const data = parseLastJson(r.stdout);
+  return { isError: !data, status: data, exitCode: r.exitCode, detail: data ? 'ok' : (r.stderr || 'could not parse status JSON').slice(0, 500) };
+}
+
+// hone_verify_patch — apply step_4 diff in a worktree + run make ci (REAL local
+// execution, in the CLI), optionally report the verdict. Long-running → wide timeout.
+async function verifyPatch({ runId, report = false, cwd } = {}) {
+  if (!runId) return { isError: true, detail: 'runId is required' };
+  const args = ['verify-patch', String(runId), '--format', 'json'];
+  if (report) args.push('--report');
+  const r = await runHone(args, { cwd, timeoutMs: 600000 });
+  if (r.error) return { isError: true, detail: r.error };
+  const data = parseLastJson(r.stdout);
+  const verdict = data && (data.verdict || data.result) ? (data.verdict || data.result) : (r.ok ? 'pass' : 'fail');
+  return { isError: false, verdict, passed: r.ok, exitCode: r.exitCode, report: data, detail: (data && data.detail) || (r.ok ? 'tests passed' : 'tests failed') };
+}
+
+// hone_check_patch — does step_4's diff apply cleanly? (throwaway git apply --check)
+async function checkPatch({ runId, stepKey = 'step_4', cwd } = {}) {
+  if (!runId) return { isError: true, detail: 'runId is required' };
+  const r = await runHone(['check-patch', String(runId), '--step-key', String(stepKey), '--format', 'json'], { cwd });
+  if (r.error) return { isError: true, detail: r.error };
+  const data = parseLastJson(r.stdout);
+  return { isError: false, applies: r.ok, exitCode: r.exitCode, report: data, detail: (data && data.detail) || (r.ok ? 'diff applies cleanly' : 'diff does not apply') };
+}
+
+// hone_emit_pr — verified diff → branch → draft PR (staged: --push, --open-pr).
+async function emitPr({ runId, push = false, openPr = false, branch, base, cwd } = {}) {
+  if (!runId) return { isError: true, detail: 'runId is required' };
+  const args = ['emit-pr', String(runId), '--format', 'json'];
+  if (openPr) args.push('--open-pr'); else if (push) args.push('--push');
+  if (branch) args.push('--branch', String(branch));
+  if (base) args.push('--base', String(base));
+  const r = await runHone(args, { cwd, timeoutMs: 180000 });
+  if (r.error) return { isError: true, detail: r.error };
+  const data = parseLastJson(r.stdout);
+  return { isError: !r.ok, exitCode: r.exitCode, report: data, detail: ((data && (data.prUrl || data.detail)) || (r.ok ? 'emitted' : r.stderr || 'emit failed')).slice(0, 500) };
+}
+
+// hone_verify_pr — real skill audit + real CI gate on an open PR, optional report.
+async function verifyPr({ pr, report = false, workflowId, cwd } = {}) {
+  if (!pr) return { isError: true, detail: 'pr (number or branch) is required' };
+  const args = ['verify-pr', String(pr), '--format', 'json'];
+  if (report) { args.push('--report'); if (workflowId) args.push('--workflow-id', String(workflowId)); }
+  const r = await runHone(args, { cwd, timeoutMs: 600000 });
+  if (r.error) return { isError: true, detail: r.error };
+  const data = parseLastJson(r.stdout);
+  const verdict = data && data.verdict ? data.verdict : (r.ok ? 'pass' : 'fail');
+  return { isError: false, verdict, passed: r.ok, exitCode: r.exitCode, report: data, detail: (data && data.detail) || (r.ok ? 'CI green' : 'CI red') };
+}
+
+// hone_agent_eval — test the adopter's own agents (HC-COMM-011), optional report.
+async function agentEval({ category, target, judge = false, provider, report = false, workflowId, cwd } = {}) {
+  const args = ['agent-eval', '--output', 'json'];
+  if (category) args.push('--category', String(category));
+  if (target) args.push('--target', String(target));
+  if (judge) args.push('--judge');
+  if (provider) args.push('--provider', String(provider));
+  if (report) { args.push('--report'); if (workflowId) args.push('--workflow-id', String(workflowId)); }
+  const r = await runHone(args, { cwd, timeoutMs: 300000 });
+  if (r.error) return { isError: true, detail: r.error };
+  const data = parseLastJson(r.stdout);
+  const passed = data && typeof data.passed === 'boolean' ? data.passed : r.ok;
+  return { isError: false, passed, exitCode: r.exitCode, report: data, detail: (data && Array.isArray(data.results)) ? `${data.results.filter((x) => x.passed).length}/${data.results.length} probes passed` : (r.ok ? 'passed' : 'failed') };
+}
+
+// hone_show_step — the LLM output of an orchestrator step (readOnly).
+async function showStep({ runId, stepKey, cwd } = {}) {
+  if (!runId || !stepKey) return { isError: true, detail: 'runId and stepKey are required' };
+  const r = await runHone(['show', 'step', String(runId), String(stepKey)], { cwd });
+  if (r.error) return { isError: true, detail: r.error };
+  return { isError: !r.ok, exitCode: r.exitCode, output: r.stdout.slice(0, 8000), detail: r.ok ? 'ok' : (r.stderr || 'show step failed').slice(0, 500) };
+}
+
+// hone_approve — approve a paused human gate (run-story --approve).
+async function approve({ runId, stepKey, cwd } = {}) {
+  if (!runId || !stepKey) return { isError: true, detail: 'runId and stepKey are required' };
+  const r = await runHone(['run-story', String(runId), '--approve', String(stepKey)], { cwd });
+  if (r.error) return { isError: true, detail: r.error };
+  return { isError: !r.ok, exitCode: r.exitCode, detail: (r.ok ? `approved ${stepKey}` : (r.stderr || r.stdout || 'approve failed')).slice(0, 500) };
+}
+
+// hone_derive — derive/refresh the adopter's domain skills (async, server-side).
+async function derive({ cwd } = {}) {
+  const r = await runHone(['derive'], { cwd, timeoutMs: 600000 });
+  if (r.error) return { isError: true, detail: r.error };
+  return { isError: !r.ok, exitCode: r.exitCode, detail: (r.ok ? 'derive complete' : (r.stderr || r.stdout || 'derive failed')).slice(0, 500) };
+}
+
+// hone_sync — pull latest skills + agent prompts into the local repo (writes files).
+async function sync({ skillsOnly = false, agentsOnly = false, cwd } = {}) {
+  const args = ['sync'];
+  if (skillsOnly) args.push('--skills-only');
+  if (agentsOnly) args.push('--agents-only');
+  const r = await runHone(args, { cwd, timeoutMs: 120000 });
+  if (r.error) return { isError: true, detail: r.error };
+  return { isError: !r.ok, exitCode: r.exitCode, detail: (r.ok ? 'sync complete' : (r.stderr || r.stdout || 'sync failed')).slice(0, 500) };
+}
+
+// hone_doctor — self-check the setup (readOnly): is a token present, and is the
+// `hone` CLI installed + reachable? Invaluable across editors, where "is it wired?"
+// is the #1 MCP setup question. No network call (fast, never hangs).
+async function doctor({ cwd } = {}) {
+  const cfg = readHoneConfig();
+  const checks = [];
+  checks.push({ name: 'token', ok: cfg.hasToken, detail: cfg.hasToken ? 'token present (HONE_TOKEN / ~/.honerc)' : 'no token — run `hone init --token <t>` or set HONE_TOKEN' });
+  checks.push({ name: 'apiUrl', ok: true, detail: cfg.apiUrl });
+  const v = await runHone(['--version'], { cwd, timeoutMs: 15000 });
+  const cliOk = v.ok && /\d+\.\d+\.\d+/.test(v.stdout);
+  checks.push({ name: 'hone-cli', ok: cliOk, detail: cliOk ? `hone ${v.stdout.trim()}` : (v.error || 'hone CLI not found — `npm i -g @hone-ai/cli`') });
+  const allOk = checks.every((c) => c.ok);
+  return { isError: false, ok: allOk, checks, detail: allOk ? 'ready' : 'setup incomplete — see checks' };
+}
+
+// The tool registry the MCP server iterates. Kept declarative so mcp-server.js is thin.
+const TOOLS = [
+  {
+    name: 'hone_run_story',
+    description: 'Start a Hone SDLC pipeline run for a story id or GitHub issue number. Runs server-side on the org\'s Anthropic key; returns a runId. Does not execute locally.',
+    readOnly: false,
+    inputSchema: { type: 'object', properties: { storyId: { type: 'string', description: 'roadmap story id or GitHub issue number' }, mode: { type: 'string', enum: ['interactive', 'batch'], default: 'batch' } }, required: ['storyId'] },
+    handler: runStory,
+  },
+  {
+    name: 'hone_status',
+    description: 'Read the status of a Hone run (steps + gate state). Read-only.',
+    readOnly: true,
+    inputSchema: { type: 'object', properties: { runId: { type: 'string' } }, required: ['runId'] },
+    handler: status,
+  },
+  {
+    name: 'hone_verify_patch',
+    description: 'Verify a run\'s step_4 change LOCALLY: apply the diff in a throwaway worktree and run the tests (make ci), then optionally report the verdict. This RUNS YOUR TESTS and touches a temporary worktree.',
+    readOnly: false,
+    inputSchema: { type: 'object', properties: { runId: { type: 'string' }, report: { type: 'boolean', default: false } }, required: ['runId'] },
+    handler: verifyPatch,
+  },
+  {
+    name: 'hone_check_patch',
+    description: 'Check whether a run\'s step_4 diff applies cleanly (throwaway `git apply --check`). Read-mostly; touches no tracked files.',
+    readOnly: false,
+    inputSchema: { type: 'object', properties: { runId: { type: 'string' }, stepKey: { type: 'string', default: 'step_4' } }, required: ['runId'] },
+    handler: checkPatch,
+  },
+  {
+    name: 'hone_show_step',
+    description: 'Print the LLM output of an orchestrator step for a run (e.g. the plan, the tests, the diff). Read-only.',
+    readOnly: true,
+    inputSchema: { type: 'object', properties: { runId: { type: 'string' }, stepKey: { type: 'string' } }, required: ['runId', 'stepKey'] },
+    handler: showStep,
+  },
+  {
+    name: 'hone_approve',
+    description: 'Approve a paused human gate on a run so it advances (e.g. stepKey "step_4").',
+    readOnly: false,
+    inputSchema: { type: 'object', properties: { runId: { type: 'string' }, stepKey: { type: 'string' } }, required: ['runId', 'stepKey'] },
+    handler: approve,
+  },
+  {
+    name: 'hone_emit_pr',
+    description: 'Turn a verified run into a branch and (staged) a draft PR. By default a local dry run; set push=true to push, openPr=true to open a draft PR. WRITES a branch / PR when pushed.',
+    readOnly: false,
+    inputSchema: { type: 'object', properties: { runId: { type: 'string' }, push: { type: 'boolean', default: false }, openPr: { type: 'boolean', default: false }, branch: { type: 'string' }, base: { type: 'string' } }, required: ['runId'] },
+    handler: emitPr,
+  },
+  {
+    name: 'hone_verify_pr',
+    description: 'Run the real skill audit + CI gate on an open PR (gh pr checks / make ci), optionally reporting the verdict. EXECUTES locally.',
+    readOnly: false,
+    inputSchema: { type: 'object', properties: { pr: { type: 'string', description: 'PR number or branch' }, report: { type: 'boolean', default: false }, workflowId: { type: 'string' } }, required: ['pr'] },
+    handler: verifyPr,
+  },
+  {
+    name: 'hone_agent_eval',
+    description: 'Test the adopter\'s own agents (adversarial, faithfulness, safety, boundary), optionally with the free NLI judge, optionally reporting the verdict. Deterministic + $0 by default. EXECUTES locally.',
+    readOnly: false,
+    inputSchema: { type: 'object', properties: { category: { type: 'string', enum: ['adversarial', 'faithfulness', 'safety', 'boundary'] }, target: { type: 'string' }, judge: { type: 'boolean', default: false }, provider: { type: 'string', enum: ['gh-models', 'claude'] }, report: { type: 'boolean', default: false }, workflowId: { type: 'string' } } },
+    handler: agentEval,
+  },
+  {
+    name: 'hone_derive',
+    description: 'Derive/refresh the adopter\'s domain skills from the codebase (async, server-side). Long-running.',
+    readOnly: false,
+    inputSchema: { type: 'object', properties: {} },
+    handler: derive,
+  },
+  {
+    name: 'hone_sync',
+    description: 'Pull the latest derived skills + agent prompts into the local repo. WRITES files under .claude/agents and .github/skills.',
+    readOnly: false,
+    inputSchema: { type: 'object', properties: { skillsOnly: { type: 'boolean', default: false }, agentsOnly: { type: 'boolean', default: false } } },
+    handler: sync,
+  },
+  {
+    name: 'hone_doctor',
+    description: 'Self-check the Hone setup (read-only): is a token configured, and is the `hone` CLI installed + reachable? Run this first if other tools fail.',
+    readOnly: true,
+    inputSchema: { type: 'object', properties: {} },
+    handler: doctor,
+  },
+];
+
+module.exports = {
+  runStory, status, verifyPatch, checkPatch, showStep, approve, emitPr, verifyPr, agentEval, derive, sync, doctor,
+  runHone, parseRunStarted, parseLastJson, honeBin, readHoneConfig, TOOLS,
+};