@hone-ai/cli 1.37.0 → 1.38.1

package/lib/asset-fetch-list.js

@@ -11,6 +11,10 @@
  * network or a filesystem.
  */
 
+// HC-GF-270-followup-2: every path goes through the one builder. The derived set's repository is the
+// checkout's directory name, which can hold `?`, `#` or `%`; hand-built, `x?y` fetched `/skills/x`.
+const { apiPath } = require('./run-target');
+
 /**
  * @param {object} args
  * @param {string[]} args.agents      agent names
@@ -39,12 +43,12 @@ function assetFetchList({ agents = [], skills = [], derivedRepo = null, get, wri
   return [
     ...agents.map(agent => ({
       key: `${agent}.agent.md`,
-      promise: get(`/scripts/agent-stub/${agent}`),
+      promise: get(apiPath('scripts', ['agent-stub', agent])),
       write: (data) => writeAgent(agent, data),
     })),
     ...skills.map(skill => ({
       key: `skills/${skill}/SKILL.md`,
-      promise: get(`/skills/${skill}`),
+      promise: get(apiPath('skills', [skill])),
       write: (data) => writeSkill(skill, data),
     })),
     // ── HC-GF-184: the per-repo DERIVED set ────────────────────────────────────────────────────
@@ -59,7 +63,7 @@ function assetFetchList({ agents = [], skills = [], derivedRepo = null, get, wri
     // derived, so setup behaves exactly as before for them.
     ...(derivedRepo ? [{
       key: `skills/<derived for ${derivedRepo}>`,
-      promise: get(`/skills/${derivedRepo}/derived`),
+      promise: get(apiPath('skills', [derivedRepo, 'derived'])),
       // Tolerant by construction: this runs mid-setup, AFTER the baseline has landed, so a shape
       // change at the endpoint must not abort an adopter's install half-written.
       write: (data) => {

package/lib/bundle-paths.js

@@ -259,6 +259,22 @@ function extractPathRefs(text) {
 /** Backticked spans in a story, longest first — the longest is the most specific anchor. */
 const BACKTICKED_RE = /`([^`\n]{3,200})`/g;
 
+/**
+ * The terms a story quotes that could locate code, longest first — one copy of the filter.
+ * HC-GF-206-followup-3: three readers now ask this question (`anchorLineForStory`,
+ * `anchorSitesForStory` and `unanchoredTerms`), and two hand-typed copies of it is how one
+ * reader ends up judging a different set of terms than the others. Path-shaped spans and the
+ * extensionless filenames are dropped: a story always quotes the file's own path.
+ */
+function storyTermsOf(storyText) {
+  return [...String(storyText || '').matchAll(BACKTICKED_RE)]
+    .map((m) => m[1].trim())
+    .filter((c) => c.length >= 3
+      && !new RegExp(`^[\\w.\\-/]+\\.(?:${FILE_EXT})$`).test(c)
+      && !new RegExp(`^(?:${EXTENSIONLESS})$`).test(c))
+    .sort((a, b) => b.length - a.length);
+}
+
 /**
  * The line of the first thing the STORY quoted that actually occurs in this file — HC-GF-188.
  *
@@ -286,12 +302,7 @@ function anchorLineForStory(content, storyText) {
   const story = String(storyText || '');
   if (!text || !story) return null;
 
-  const candidates = [...story.matchAll(BACKTICKED_RE)]
-    .map((m) => m[1].trim())
-    .filter((c) => c.length >= 3
-      && !new RegExp(`^[\\w.\\-/]+\\.(?:${FILE_EXT})$`).test(c)
-      && !new RegExp(`^(?:${EXTENSIONLESS})$`).test(c))
-    .sort((a, b) => b.length - a.length);
+  const candidates = storyTermsOf(story);
 
   for (const anchor of candidates) {
     const at = definitionIndexOf(text, anchor);
@@ -334,12 +345,7 @@ function anchorSitesForStory(content, storyText, max = 6) {
   const text = String(content || '');
   const story = String(storyText || '');
   if (!text || !story) return { sites: [], collapsed: [] };
-  const candidates = [...story.matchAll(BACKTICKED_RE)]
-    .map((m) => m[1].trim())
-    .filter((c) => c.length >= 3
-      && !new RegExp(`^[\\w.\\-/]+\\.(?:${FILE_EXT})$`).test(c)
-      && !new RegExp(`^(?:${EXTENSIONLESS})$`).test(c))
-    .sort((a, b) => b.length - a.length);
+  const candidates = storyTermsOf(story);
 
   const seenLine = new Set();
   const sites = [];
@@ -382,6 +388,81 @@ function definitionIndexOf(text, term) {
   return text.indexOf(term);
 }
 
+/**
+ * The story's terms that occur in this file but in NONE of the windows bundled — HC-GF-206-followup-3.
+ *
+ * `anchorSitesForStory` stops at 6 sites, and terms are tried longest first, so every hit after
+ * the sixth site — including every hit of a shorter term — is neither a site nor a collapsed hit.
+ * A window can also be dropped for budget with its term in it. The notice counted neither, and
+ * nothing told the agent: a term absent from the excerpt reads exactly like a term absent from the
+ * FILE. Measured 2026-10-05 at the production cap over every roadmap row against cli/hone-cli.js and
+ * server/src/services/orchestrator.js: 425 of 1,198 windowed excerpts left out 901 whole-word terms,
+ * none named.
+ *
+ * Judged against the FINAL windows, not the site list, so it holds whatever dropped the term — the
+ * site limit, the budget, a collapse — and needs no knowledge of how the layout was chosen.
+ *
+ * A term counts as occurring only where it stands as a whole word. `definitionIndexOf` falls back to
+ * a bare `indexOf`, which finds `info` inside `information`; reporting that as "`info` is at line N"
+ * would send an agent to a line that does not contain it.
+ *
+ * @param {string} content full file contents
+ * @param {string} storyText
+ * @param {Array<[number, number]>} ranges the bundled windows' [startLine, endLine], 1-indexed
+ * @returns {Array<{term: string, line: number}>} story order (longest first); `line` is the
+ *   definition's line when the definition is a whole-word occurrence, else the first mention
+ */
+function unanchoredTerms(content, storyText, ranges) {
+  const text = String(content || '');
+  if (!text) return [];
+  const starts = [0];
+  for (let i = text.indexOf('\n'); i !== -1; i = text.indexOf('\n', i + 1)) starts.push(i + 1);
+  const lineOf = (off) => {
+    let lo = 0;
+    let hi = starts.length - 1;
+    while (lo < hi) { const mid = (lo + hi + 1) >> 1; if (starts[mid] <= off) lo = mid; else hi = mid - 1; }
+    return lo + 1;
+  };
+  const covered = (l) => ranges.some(([a, b]) => a <= l && l <= b);
+  const out = [];
+  for (const term of new Set(storyTermsOf(storyText))) {
+    const def = definitionIndexOf(text, term);
+    if (def === -1) continue;
+    const t = term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const mentions = [...text.matchAll(new RegExp(`(?<![\\w$])${t}(?![\\w$])`, 'g'))].map((m) => lineOf(m.index));
+    if (!mentions.length) continue;
+    // Covered only by a whole-word occurrence. The bundler may have anchored on `def` itself, but
+    // when `def` is the indexOf fallback that window shows `information`, not `info`.
+    if (mentions.some(covered)) continue;
+    const defLine = lineOf(def);
+    out.push({ term, line: mentions.includes(defLine) ? defLine : mentions[0] });
+  }
+  return out;
+}
+
+/**
+ * The excerpt's first line when story terms were left out — HC-GF-206-followup-3. It goes FIRST
+ * because step_0's premise check keeps only the first 2,000 chars of each file
+ * (`STEP_0_CODE_CAP_PER_FILE`, server/src/services/orchestrator.js), and "this symbol already
+ * exists" is exactly what that step looks for. It must fit the room the windows left under the cap:
+ * terms are listed longest first and the tail is folded into "+N more"; with no room for even that,
+ * it is omitted and only the operator's notice carries the list.
+ */
+function unanchoredMarker(unanchored, room) {
+  if (!unanchored.length) return '';
+  const head = `# [HC-GF-206-followup-3: ${unanchored.length} term(s) the story names occur in this file `
+    + 'OUTSIDE every excerpt below: ';
+  const tail = '. They exist; you were not shown them, so do not conclude they are absent.]\n';
+  const items = unanchored.map(({ term, line }) => `\`${term}\` (line ${line})`);
+  for (let k = items.length; k >= 0; k -= 1) {
+    const rest = items.length - k;
+    const list = items.slice(0, k).join(', ') + (rest ? `${k ? ', ' : ''}+${rest} more` : '');
+    const marker = head + list + tail;
+    if (marker.length <= room) return marker;
+  }
+  return '';
+}
+
 /**
  * Decide what a bundled file should actually contain — HC-GF-188.
  *
@@ -401,7 +482,9 @@ function definitionIndexOf(text, term) {
  *
  * @param {{content: string, cap: number, line?: number|null, lines?: number[], storyText?: string, path?: string}} input
  * @returns {{mode: 'full'|'window'|'truncate', content: string, notice: string|null, anchor?: string,
- *   unhonoured: Array<{line: number, reason: 'past-eof'|'budget', totalLines: number}>}}
+ *   unhonoured: Array<{line: number, reason: 'past-eof'|'budget', totalLines: number}>,
+ *   unanchored: Array<{term: string, line: number}>}} — HC-GF-206-followup-3: story terms the file
+ *   has that no bundled window carries; always empty outside `window` mode
  */
 function planFileExcerpt({ content, cap, line = null, lines = null, storyText = '', path: filePath = 'file' } = {}) {
   const text = String(content || '');
@@ -415,7 +498,7 @@ function planFileExcerpt({ content, cap, line = null, lines = null, storyText =
   const stated = requested.filter((n) => n <= totalLines);
   const unhonoured = requested.filter((n) => n > totalLines)
     .map((n) => ({ line: n, reason: 'past-eof', totalLines }));
-  if (text.length <= limit) return { mode: 'full', content: text, notice: null, unhonoured };
+  if (text.length <= limit) return { mode: 'full', content: text, notice: null, unhonoured, unanchored: [] };
 
   // An explicit line wins: the author stated it, the anchor is inferred from prose.
   const hit = stated.length ? { line: stated[0], anchor: null } : anchorLineForStory(text, storyText);
@@ -698,14 +781,30 @@ function planFileExcerpt({ content, cap, line = null, lines = null, storyText =
         ? ` — ${unreached} near-duplicate hit(s) collapsed into a window that did not reach them`
         : '');
 
+    const body = windows.map(({ w, anchor, line: siteLine }) =>
+      header(w, anchor, siteLine) + w.excerpt + footer).join('\n');
+    // HC-GF-206-followup-3: a story term the file has and no window carries is NAMED, to the agent
+    // first and the operator second. Only the room the windows left is spent: the layout above is
+    // untouched, so what every run already bundled stays exactly what it was.
+    const unanchored = unanchoredTerms(text, storyText, windows.map(({ w }) => [w.startLine, w.endLine]));
+    const marker = unanchoredMarker(unanchored, limit - body.length);
+    const SHOWN = 8;
+    const termsNote = unanchored.length
+      ? ` — ${unanchored.length} story term(s) in the file but in no bundled window: `
+        + unanchored.slice(0, SHOWN).map(({ term, line: l }) => `\`${term}\` (line ${l})`).join(', ')
+        + (unanchored.length > SHOWN ? `, +${unanchored.length - SHOWN} more` : '')
+        + `; name them as ${filePath}:<line> to anchor them`
+        + (marker ? '' : ' (the excerpt had no room left to tell the agent)')
+      : '';
+
     return {
       mode: 'window',
       unhonoured,
+      unanchored,
       anchor: windows[0].anchor || null,
-      content: windows.map(({ w, anchor, line: siteLine }) =>
-        header(w, anchor, siteLine) + w.excerpt + footer).join('\n'),
+      content: marker + body,
       notice: `  ⚠ ${filePath} is ${text.length} chars (cap ${limit}) — bundled lines `
-        + `${ranges} of ${windows[0].w.totalLines}, ${because}${shortfall}`,
+        + `${ranges} of ${windows[0].w.totalLines}, ${because}${shortfall}${termsNote}`,
     };
   }
 
@@ -718,6 +817,7 @@ function planFileExcerpt({ content, cap, line = null, lines = null, storyText =
   return {
     mode: 'truncate',
     unhonoured,
+    unanchored: [], // reached only when no story term occurs in the file at all
     content: text.slice(0, keep) + marker(keep),
     notice: `  ⚠ ${filePath} is ${text.length} chars (cap ${limit}) — head-truncated, ${dropped} chars `
       + `DROPPED and nothing in the story text matched inside the file, so the region you care about `
@@ -932,7 +1032,7 @@ function classifyStoryPaths(text, named) {
 module.exports = {
   BARE_FILE_RE, extractBareNames, extractBareRefs, resolveBareName, alreadyCovered, windowAroundLine,
   PATH_REF_RE, extractPathRefs, anchorLineForStory, planFileExcerpt, definitionIndexOf, anchorSitesForStory,
-  windowBetweenLines, mergeIntersectingWindows,
+  windowBetweenLines, mergeIntersectingWindows, storyTermsOf, unanchoredTerms, unanchoredMarker,
   // HC-GF-229 — classification. Pinned byte-for-byte against the server copy.
   LABEL_RE, maskCodeSpans, targetSpans, classifyStoryPaths,
 };

package/lib/doctor-admin-merge.js

@@ -22,7 +22,7 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
-const { execSync } = require('node:child_process');
+const { execFileSync } = require('node:child_process');
 const { gitEnv } = require('./git-env');
 
 // HC-005-A: ambiguous pattern named explicitly so the ambiguity-guard
@@ -62,10 +62,18 @@ function checkAdminMerge(args) {
     return { name, status: 'skip', reason: 'no repoRoot supplied' };
   }
 
+  // HC-GF-270-followup-3: `lookback` became part of a shell string, so any caller of this exported
+  // function could run a command through it. It is a count; anything else is refused, and git gets an
+  // argument list. The format has no shell quotes now — under a shell they were stripped; as an
+  // argument they would reach git literally and end up in every sha.
+  if (!Number.isInteger(lookback) || lookback < 1) {
+    return { name, status: 'skip', reason: `lookback must be a positive integer (got ${typeof lookback === 'number' ? String(lookback) : JSON.stringify(lookback)})` };
+  }
+
   // Verify it's a git repo
   let log;
   try {
-    log = execSync(`git log -n ${lookback} --pretty=format:'%H%x09%s%x09%b%x1e'`, {
+    log = execFileSync('git', ['log', '-n', String(lookback), '--pretty=format:%H%x09%s%x09%b%x1e'], {
       cwd: repoRoot, env: gitEnv(),
       encoding: 'utf8',
       stdio: ['ignore', 'pipe', 'pipe'],
@@ -166,7 +174,7 @@ function checkAdminMerge(args) {
  */
 function isShallowClone(repoRoot) {
   try {
-    const out = execSync('git rev-parse --is-shallow-repository', {
+    const out = execFileSync('git', ['rev-parse', '--is-shallow-repository'], {
       cwd: repoRoot, env: gitEnv(),
       encoding: 'utf8',
       stdio: ['ignore', 'pipe', 'pipe'],

package/lib/git-remote.js

@@ -0,0 +1,103 @@
+'use strict';
+/**
+ * git-remote.js — HC-GF-283: the GitHub host, owner and repository this checkout's `origin` names, with
+ * an SSH host alias resolved to the host it stands for.
+ *
+ * WHY. `run-story <issue-number>` fetches the issue's text with `gh issue view` and its author with
+ * `gh api`. Both used to receive `owner/repo` and no host, so gh used its DEFAULT host. For a remote
+ * like `git@ghe:platform/api.git`, where `ghe` is a `~/.ssh/config` alias for a GitHub Enterprise host
+ * and gh's default is github.com, both calls read `github.com/platform/api` — where someone else can
+ * own that name, file issue #N as its OWNER, and pass HC-GF-270's provenance check, which skipped the
+ * host comparison for an alias because an alias is not a hostname.
+ *
+ * `ssh -G <alias>` prints the configuration ssh would use for that alias, `hostname` included, without
+ * connecting. That turns the alias into the host gh must be told about, so both gh calls name it and
+ * the provenance check can always compare it with the issue's `html_url`.
+ *
+ * Pure apart from the injected `sshConfig`, so every branch is testable without ssh or a network.
+ */
+
+const { rawRemoteHost } = require('./story-provenance');
+
+// owner/repo: the last two path segments, `.git` dropped. The same rule run-story has always used.
+const OWNER_REPO_RE = /[/:]([^/]+)\/([^/]+?)(?:\.git)?$/;
+// What may be handed to `ssh -G` as an argument: a host name or alias, never an option. A remote of
+// `git@-oProxyCommand=…:o/r` must not become `ssh -G -oProxyCommand=…`.
+const SSH_HOST_ARG_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+// The resolved host gh is told about: a hostname, nothing that could be read as a path or a flag.
+const HOSTNAME_RE = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)*$/;
+
+class RemoteHostError extends Error {
+  constructor(message) { super(message); this.code = 'HC_REMOTE_HOST'; }
+}
+
+/**
+ * How the remote is reached: 'ssh' (an scp-like `user@host:path` or an ssh:// URL — the host may be an
+ * alias), 'url' (https/http/git — the host is the host), or null (a local path or nothing parsable).
+ */
+function remoteTransport(remoteUrl) {
+  const s = String(remoteUrl == null ? '' : remoteUrl).trim();
+  if (!s) return null;
+  const scheme = s.match(/^([A-Za-z][A-Za-z0-9+.-]*):\/\//);
+  if (scheme) {
+    const p = scheme[1].toLowerCase();
+    if (p === 'ssh' || p === 'git+ssh' || p === 'ssh+git') return 'ssh';
+    if (p === 'https' || p === 'http' || p === 'git') return 'url';
+    return null;   // file:// and anything else has no GitHub host
+  }
+  // scp-like: `[user@]host:path`. A Windows drive letter (`C:\…`, `C:/…`) is a local path.
+  if (/^[A-Za-z]:[\\/]/.test(s)) return null;
+  return /^(?:[^@/\s]+@)?[^/:\s]+:/.test(s) ? 'ssh' : null;
+}
+
+/** GitHub's SSH-over-HTTPS endpoint serves github.com's repositories (HC-GF-270 security review LOW-3). */
+function canonicalHost(host) {
+  const h = String(host || '').trim().toLowerCase();
+  return h === 'ssh.github.com' ? 'github.com' : h;
+}
+
+/** The `hostname` line of `ssh -G` output, or null. */
+function hostnameFromSshConfig(stdout) {
+  const m = String(stdout || '').match(/^hostname\s+(\S+)\s*$/im);
+  return m ? m[1] : null;
+}
+
+/**
+ * @param {string} remoteUrl  `git remote get-url origin`
+ * @param {{ sshConfig: (host: string) => Promise<string> }} io  runs `ssh -G <host>` and resolves to its stdout
+ * @returns {Promise<{ host: string, owner: string, repo: string, remoteUrl: string, via: string|null }>}
+ *   `host` is the host gh must be told about; `via` is the alias it was resolved from, or null.
+ *   Rejects with a RemoteHostError (code HC_REMOTE_HOST) when the host cannot be established: the
+ *   callers then fetch nothing, rather than letting gh fall back to its default host.
+ */
+async function resolveRemote(remoteUrl, io) {
+  const url = String(remoteUrl == null ? '' : remoteUrl).trim();
+  const m = url.match(OWNER_REPO_RE);
+  if (!m) throw new RemoteHostError(`could not parse owner/repo from remote: ${url}`);
+  const [, owner, repo] = m;
+  const transport = remoteTransport(url);
+  const raw = rawRemoteHost(url);
+  if (!transport || !raw) throw new RemoteHostError(`the remote ${url} names no GitHub host`);
+
+  let host = raw;
+  let via = null;
+  if (transport === 'ssh') {
+    if (!SSH_HOST_ARG_RE.test(raw)) throw new RemoteHostError(`the remote's SSH host ${JSON.stringify(raw)} is not a host name`);
+    let out;
+    try {
+      out = await io.sshConfig(raw);
+    } catch (e) {
+      const why = String((e && e.stderr) || (e && e.message) || e).trim().split('\n')[0];
+      throw new RemoteHostError(`could not resolve the SSH host ${raw} with ssh -G: ${why}`);
+    }
+    const resolved = hostnameFromSshConfig(out);
+    if (!resolved) throw new RemoteHostError(`ssh -G ${raw} printed no hostname`);
+    host = resolved.toLowerCase();
+    if (host !== raw) via = raw;
+  }
+  host = canonicalHost(host);
+  if (!HOSTNAME_RE.test(host)) throw new RemoteHostError(`the remote's host ${JSON.stringify(host)} is not a hostname`);
+  return { host, owner, repo, remoteUrl: url, via };
+}
+
+module.exports = { resolveRemote, remoteTransport, hostnameFromSshConfig, canonicalHost, RemoteHostError };

package/lib/judge-provider.js

@@ -1,27 +1,44 @@
-'use strict';
 /**
- * judge-provider.js — HC-COMM-011-followup-3
+ * judge-provider.js — HC-COMM-011-followup-3, HC-GF-340
  *
  * The shared LLM-judge provider builder. Returns a `callLLM(system, user)` bound to
- * a provider, honoring the zero-cost discipline (feedback_pipeline_llm_cost_reduction):
- * default is FREE GH Models (via GITHUB_TOKEN); paid Claude Sonnet is opt-in.
+ * a provider. Returns `{ callLLM }` on success or `{ error }` when no working provider
+ * was named or its credential is missing — the caller decides how to surface it.
  *
- * Extracted so both `hone eval --judge` and `hone agent-eval --judge` use ONE path
- * instead of duplicating the provider wiring. Returns `{ callLLM }` on success or
- * `{ error }` when the required credential is missing — the caller decides how to
- * surface it (exit, skip, warn).
+ * HC-GF-340: the free default (GitHub Models via GITHUB_TOKEN) is gone. GitHub retired it on
+ * 2026-07-30 and its endpoint now answers HTTP 200 "OK" to every request, so a judge on it could
+ * not answer and every criterion read "could not parse response". There is no free replacement
+ * here, so no provider is a default: the operator names one, and the only one that works is the
+ * paid `claude` (Sonnet) provider. An adopter must not be billed by a default they never chose.
  *
- * MODEL CHOICE (feedback_model_choice_cost_amplifier): the judge is NOT on the
- * OPUS_AGENTS allowlist — paid mode uses Sonnet (`claude-sonnet-5`), never Opus.
+ * ADOPTER SURFACE (HC-LC-001): this file ships in the published CLI, so it must never spawn a
+ * local Claude Code binary. A free path for the repo owner's own machine, if wanted, belongs in
+ * the unshipped `scripts/` tree.
  */
+
+/** Said by every command that used to default to GitHub Models, so the cause is one sentence. */
+const GH_MODELS_RETIRED =
+  'GitHub Models (--provider gh-models), the free default, was retired by GitHub on 2026-07-30: '
+  + 'its endpoint answers HTTP 200 "OK" to every request, so nothing can be judged or reviewed through it.';
+
+/**
+ * The message for an unnamed or retired provider.
+ * @param {string} flag e.g. '--provider claude' — the one working provider for the calling command.
+ */
+function providerRequiredMessage(flag) {
+  return `${GH_MODELS_RETIRED}\n  Name a provider that works: ${flag} (paid, needs ANTHROPIC_API_KEY).`;
+}
+
 function buildJudgeCallLLM(provider, { axios }) {
-  const p = String(provider || 'gh-models').toLowerCase();
+  const p = String(provider || '').toLowerCase();
 
   if (p === 'claude' || p === 'anthropic') {
     const apiKey = process.env.ANTHROPIC_API_KEY;
     if (!apiKey) {
-      return { error: 'ANTHROPIC_API_KEY required for --provider claude. Set it, or use the default free gh-models path (needs GITHUB_TOKEN).' };
+      return { error: 'ANTHROPIC_API_KEY required for --provider claude. Set it: export ANTHROPIC_API_KEY=sk-ant-...' };
     }
+    // MODEL CHOICE (feedback_model_choice_cost_amplifier): the judge is NOT on the
+    // OPUS_AGENTS allowlist — paid mode uses Sonnet (`claude-sonnet-5`), never Opus.
     const callLLM = async (systemPrompt, userPrompt) => {
       const { data } = await axios.post('https://api.anthropic.com/v1/messages', {
         model: 'claude-sonnet-5',
@@ -33,31 +50,19 @@ function buildJudgeCallLLM(provider, { axios }) {
         headers: { 'x-api-key': apiKey, 'anthropic-version': '2023-06-01', 'content-type': 'application/json' },
         timeout: 60000,
       });
-      return (data.content || []).find((b) => b?.type === 'text')?.text || '';
+      const text = (data.content || []).find((b) => b?.type === 'text')?.text;
+      // A provider that answered with nothing is a provider failure, not a failed criterion:
+      // returning '' here made every criterion read "could not parse response".
+      if (typeof text !== 'string' || !text.trim()) {
+        throw new Error(`the claude provider returned no text (stop_reason: ${data.stop_reason || 'unknown'})`);
+      }
+      return text;
     };
     return { callLLM, provider: 'claude', paid: true };
   }
 
-  // Default: GH Models — free inference via GITHUB_TOKEN (OpenAI-shaped).
-  const ghToken = process.env.GITHUB_TOKEN;
-  if (!ghToken) {
-    return { error: 'GITHUB_TOKEN not set — required for the default free gh-models judge. In CI it is auto-injected; locally: export GITHUB_TOKEN=<PAT>. Or use --provider claude (paid, needs ANTHROPIC_API_KEY).' };
-  }
-  const callLLM = async (systemPrompt, userPrompt) => {
-    const { data } = await axios.post('https://models.github.ai/inference/chat/completions', {
-      model: 'openai/gpt-4.1',
-      messages: [
-        { role: 'system', content: systemPrompt },
-        { role: 'user', content: userPrompt },
-      ],
-      max_tokens: 2048,
-    }, {
-      headers: { Authorization: `Bearer ${ghToken}`, 'content-type': 'application/json' },
-      timeout: 60000,
-    });
-    return data.choices?.[0]?.message?.content || '';
-  };
-  return { callLLM, provider: 'gh-models', paid: false };
+  // No provider named, or the retired one: refuse before any request is made.
+  return { error: providerRequiredMessage('--provider claude') };
 }
 
-module.exports = { buildJudgeCallLLM };
+module.exports = { buildJudgeCallLLM, providerRequiredMessage, GH_MODELS_RETIRED };

package/lib/mcp-tools.js

@@ -124,10 +124,22 @@ async function listWorkflows({ status, limit, cwd } = {}) {
 // Right for a person at a terminal; wrong behind a tool whose contract is an explicit run ID, where a
 // story ID is an agent's guess at a target. It used to fail only by accident (the server 404'd it), so
 // the tools that ACT on a run refuse anything that is not a run ID before shelling out.
-const { isRunId } = require('./run-target');
+const { isRunId, runArgsError } = require('./run-target');
 const notARunId = (runId) =>
   `runId must be a run ID (a UUID); ${JSON.stringify(String(runId))} is not. Get one from hone_run_story or hone_list_workflows.`;
 
+// HC-GF-270-followup-3: the other tools that take a run id, step key or ref check it the same way, BEFORE the
+// CLI is spawned. The CLI refuses them too, but with exit 2 — which checkPatch reported to the agent as
+// "diff does not apply". Labels are the tool's own input names. Values are checked as the CLI receives them.
+const refused = (checks) => {
+  const msg = runArgsError(checks);
+  return msg ? { isError: true, detail: msg } : null;
+};
+// An optional input that is absent, null or '' counts as not given: both tools that use this drop such a value
+// before it reaches the CLI (`if (workflowId)`), so there is nothing to check. That is deliberate, unlike runArgsError on its own,
+// which still checks a '' it is handed.
+const asArg = (v) => (v === undefined || v === null || v === '' ? undefined : String(v));
+
 // hone_kill_workflow — kill ONE run by explicit id (DESTRUCTIVE, irreversible).
 // runId is schema-required: an agent must never guess a target for a kill —
 // explicit id or nothing (memo D3 refutation). Server 409s non-killable states.
@@ -150,6 +162,8 @@ async function killWorkflow({ runId, cwd } = {}) {
 // written to disk by any Hone code.
 async function stepInstruction({ runId, cwd } = {}) {
   if (!runId) return { isError: true, detail: 'runId is required' };
+  const bad = refused([{ label: 'runId', kind: 'runId', value: String(runId) }]);
+  if (bad) return bad;
   const r = await runHone(['step-instruction', String(runId), '--format', 'json'], { cwd });
   if (r.error) return { isError: true, detail: r.error };
   const data = parseLastJson(r.stdout);
@@ -185,6 +199,12 @@ async function submitStep({ runId, stepKey, output, contractVersion = '1', fromT
   if (!fromTree && !hasOutput) {
     return { isError: true, detail: 'output is required (the complete step output text), or set fromTree' };
   }
+  // Before the temp file: a refused id writes nothing.
+  const bad = refused([
+    { label: 'runId', kind: 'runId', value: String(runId) },
+    { label: 'stepKey', kind: 'stepKey', value: String(stepKey) },
+  ]);
+  if (bad) return bad;
 
   const base = ['submit-step', String(runId), String(stepKey), '--contract', String(contractVersion), '--format', 'json'];
   let tmp = null;
@@ -232,6 +252,8 @@ async function status({ runId, cwd } = {}) {
 // 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 bad = refused([{ label: 'runId', kind: 'runId', value: String(runId) }]);
+  if (bad) return bad;
   const args = ['verify-patch', String(runId), '--format', 'json'];
   if (report) args.push('--report');
   const r = await runHone(args, { cwd, timeoutMs: 600000 });
@@ -246,6 +268,11 @@ async function verifyPatch({ runId, report = false, cwd } = {}) {
 // 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 bad = refused([
+    { label: 'runId', kind: 'runId', value: String(runId) },
+    { label: 'stepKey', kind: 'stepKey', value: String(stepKey) },
+  ]);
+  if (bad) return bad;
   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);
@@ -255,6 +282,8 @@ async function checkPatch({ runId, stepKey = 'step_4', cwd } = {}) {
 // 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 bad = refused([{ label: 'runId', kind: 'runId', value: String(runId) }]);
+  if (bad) return bad;
   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));
@@ -268,6 +297,11 @@ async function emitPr({ runId, push = false, openPr = false, branch, base, cwd }
 // 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 bad = refused([
+    { label: 'pr', kind: 'gitRev', value: String(pr) },
+    { label: 'workflowId', kind: 'runId', value: asArg(workflowId), optional: true },
+  ]);
+  if (bad) return bad;
   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 });
@@ -280,6 +314,8 @@ async function verifyPr({ pr, report = false, workflowId, cwd } = {}) {
 
 // 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 bad = refused([{ label: 'workflowId', kind: 'runId', value: asArg(workflowId), optional: true }]);
+  if (bad) return bad;
   const args = ['agent-eval', '--output', 'json'];
   if (category) args.push('--category', String(category));
   if (target) args.push('--target', String(target));
@@ -296,6 +332,11 @@ async function agentEval({ category, target, judge = false, provider, report = f
 // 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 bad = refused([
+    { label: 'runId', kind: 'runId', value: String(runId) },
+    { label: 'stepKey', kind: 'stepKey', value: String(stepKey) },
+  ]);
+  if (bad) return bad;
   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) };