@hone-ai/cli 1.38.0 → 1.39.0

package/lib/context-reserve.js

@@ -0,0 +1,270 @@
+'use strict';
+/**
+ * context-reserve.js — HC-GF-351: serve the files a hard-paused run asked for, once, without a person.
+ *
+ * A step that cannot proceed for want of a file says so (HC-GF-263 records the paths it named), and a batch had
+ * nothing to serve them with. `follow-batch` now kills that run and queues its story again with those paths
+ * added to the story's line. This module is the part that decides WHETHER a request may be served and WHAT the
+ * line says. Pure: data in, data out. The loop's I/O is injected (cli/lib/batch-follow.js).
+ *
+ * THE TRUST BOUNDARY. The paths came out of an LLM artifact and the bundler reads each one and sends its contents
+ * to a model. An agent can be steered by the bundled source and the story text, so a request is a claim to check,
+ * not an instruction. A request is served only when EVERY path in it:
+ *   - passes hard-pause-remedy's token allowlist (the characters a shell could misread are refused outright),
+ *   - is a plain relative path: no `..`, nothing absolute, home-relative or option-like, no empty segment,
+ *   - is not a credential file or a hidden file or directory (`.env`, `*.pem`, `id_rsa*`, `.ssh/`, `.git/`),
+ *   - is a REGULAR FILE that git tracks in this checkout. A tracked symlink is refused: the bundler follows it,
+ *     so `notes.txt -> ~/.ssh/id_rsa` would be a tracked path that leaves the checkout.
+ *   - resolves, on the disk as it is NOW, to a path inside this checkout that passes the same rules. The index
+ *     says what git recorded; a file or a directory replaced by a symlink since is invisible to it, and the
+ *     bundler reads through the link (`realPath`, repoRealPath).
+ * The paths the story's own line carried (config.include_paths) are held to the same rules: any client of the org
+ * can write a run's config, so they are no more trusted than an agent's.
+ * One path that fails refuses the whole request, and so does a request the server cut off (`truncated`). A partly served request is a run that pauses again for what was
+ * left out, and the loop does not serve twice.
+ *
+ * Why not just "exists in the working tree": that includes untracked and ignored files, which is exactly where an
+ * `.env`, a local key or a scratch file with a pasted token lives. Tracked means a reviewer already sees it.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { remedyFor, partitionSafePaths, tokenOf, isSafeToken } = require('./hard-pause-remedy');
+const { parseIncludeTarget } = require('./include-paths');
+const { isSecretPath } = require('./bundle-context');
+const { isBatchId } = require('./run-target');
+
+/** The start of the reason a re-served run is killed with. The loop reads it back to find the new batch. */
+const RESERVED_PREFIX = 're-served as batch ';
+
+/** What the kill reason says; `reservedBatchOf` reads it back. */
+function reserveReason(batchId, stepKey) {
+  return `${RESERVED_PREFIX}${batchId}: ${stepKey} named files it was not given`;
+}
+
+/**
+ * The batch a killed run was re-served as, or null. The kill is how the loop remembers, so a restart follows the
+ * new batch and does not serve the same story a second time.
+ * @param {object} run  a row of `GET /orchestrate/batch/:id` runs (untrusted shape)
+ */
+function reservedBatchOf(run) {
+  if (!run || run.status !== 'killed' || typeof run.errorMessage !== 'string') return null;
+  const m = run.errorMessage.match(/^re-served as batch (\S+?)(?::|\s|$)/);
+  return m && isBatchId(m[1]) ? m[1] : null;
+}
+
+/**
+ * The request a run is hard-paused on, or null. Scoped by hard-pause-remedy's reader to the run's CURRENT step,
+ * and the step the pause message names must be that step, so a request recorded on an earlier step that the run
+ * has since moved past is never served as if the current pause had asked for it.
+ * @param {object} run  a `GET /orchestrate/:runId` payload
+ * @returns {{stepKey: string, paths: object[], truncated: boolean}|null}
+ */
+function hardPauseRequest(run) {
+  if (!run || run.status !== 'paused' || typeof run.errorMessage !== 'string') return null;
+  const at = run.errorMessage.match(/^hard_pause at (\S+?)(?::|\s|$)/);
+  const remedy = at ? remedyFor(run) : null;
+  return remedy && remedy.stepKey === at[1] ? remedy : null;
+}
+
+// Credential-looking names the bundler's own refusal (isSecretPath) does not cover: a public half of a key pair,
+// key containers, anything the author named a secret or a credential.
+const SECRET_LOOKING = [/(^|[._-])id_(rsa|dsa|ecdsa|ed25519)/i, /\.(key|pfx|jks|keystore|p8)$/i, /(secret|credential)/i];
+
+/** Why a path is not a plain relative path, or null. `file` has no `:line` or `:symbol` suffix. */
+function structuralRefusal(file) {
+  if (typeof file !== 'string' || file === '') return 'empty';
+  if (/^[-/~]/.test(file)) return 'absolute, home-relative or option-like';
+  if (/[\\\0]/.test(file)) return 'not a plain relative path';
+  if (file.split('/').some((s) => s === '' || s === '.' || s === '..')) return 'not a plain relative path';
+  return null;
+}
+
+/**
+ * Why the CONTENT of a path (a plain file path, no `:line`) must not be sent to a model, or null: the three
+ * rules that need no file list. HC-GF-217 reads this directly for the lines of a search result, so a search
+ * and a re-serve cannot disagree about what is withheld (they used to be one inline sequence in requestRefusal).
+ * @param {string} file
+ */
+function contentRefusal(file) {
+  const plain = structuralRefusal(file);
+  if (plain) return plain;
+  if (isSecretPath(file) || SECRET_LOOKING.some((re) => re.test(path.posix.basename(file)))) return 'looks like a credential file';
+  if (file.split('/').some((s) => s.startsWith('.'))) return 'a hidden file or directory';
+  return null;
+}
+
+/**
+ * Why a requested path (`file`, `file:line` or `file:symbol`) must not be served, or null.
+ * @param {string} token
+ * @param {Set<string>|null} tracked  the regular files git tracks here; null when they could not be listed
+ */
+function requestRefusal(token, tracked) {
+  const file = parseIncludeTarget(token).path;
+  const why = contentRefusal(file);
+  if (why) return why;
+  if (!(tracked instanceof Set)) return 'this checkout\'s tracked files could not be listed';
+  if (!tracked.has(file)) return 'not a regular file git tracks in this checkout';
+  return null;
+}
+
+/**
+ * May this request be served? All of it, or none of it.
+ * @param {{paths: object[], truncated?: boolean}} request  from hardPauseRequest
+ * @param {{tracked?: Set<string>|null, realPath?: ((file: string) => string|null)|null, original?: string[]}} [ctx]
+ *   `realPath`: where `file` resolves on the disk now, relative to the checkout, or null if outside it or unreadable;
+ *   without it nothing is served (a request is not checked on a disk nobody looked at). `original`: the entries of
+ *   the story's own line, judged by the same rules and written before what the step asked for.
+ * @returns {{ok: true, tokens: string[]}|{ok: false, reason: string}}
+ */
+function judgeRequest(request, { tracked = null, realPath = null, original = [] } = {}) {
+  if (request && request.truncated === true) {
+    return { ok: false, reason: 'the step asked for more paths than were recorded, and a part of a request pauses again; nothing was served' };
+  }
+  const { safe, dropped } = partitionSafePaths(request && request.paths);
+  const candidates = [...original.map((token) => ({ token, own: true })), ...safe.map((p) => ({ token: tokenOf(p) }))];
+  const tokens = [];
+  const refused = [];
+  for (const { token, own } of candidates) {
+    const why = requestRefusal(token, tracked) || resolutionRefusal(token, tracked, realPath);
+    if (why) refused.push(`${token} (${why}${own ? ', on the story\'s own line' : ''})`);
+    else if (!tokens.includes(token)) tokens.push(token);
+  }
+  if (refused.length === 0 && dropped.length === 0) return { ok: true, tokens };
+  // A path the allowlist dropped is never printed: it holds characters a terminal or a shell could misread.
+  const parts = [];
+  if (refused.length) parts.push(`refused ${refused.slice(0, 5).join(', ')}${refused.length > 5 ? `, and ${refused.length - 5} more` : ''}`);
+  if (dropped.length) parts.push(`${dropped.length} requested path(s) hold characters a shell could misread`);
+  return { ok: false, reason: `${parts.join('; ')}; nothing was served` };
+}
+
+/**
+ * Where a path that passed requestRefusal really points. Null when it is fine, else why not. The path the bundler
+ * will read is the one the disk resolves, so THAT path has to pass the rules: a tracked `notes.txt` that is a link to
+ * the checkout's own `.env` is a credential read, and one that is a link out of the checkout is a read of anything.
+ */
+function resolutionRefusal(token, tracked, realPath) {
+  if (typeof realPath !== 'function') return 'where it resolves on the disk was not checked';
+  const file = parseIncludeTarget(token).path;
+  const real = realPath(file);
+  if (real === null || real === undefined) return 'it does not resolve to a readable path inside this checkout';
+  if (real === file) return null;
+  const why = requestRefusal(real, tracked);
+  return why ? `it resolves to ${real}, which is refused: ${why}` : null;
+}
+
+/**
+ * `rel` resolved through every symlink on the disk, relative to the checkout (POSIX separators), or null when it
+ * does not exist or ends outside the checkout. The one place this module touches the file system.
+ */
+function repoRealPath(cwd, rel) {
+  try {
+    const root = fs.realpathSync(cwd);
+    const inside = path.relative(root, fs.realpathSync(path.resolve(root, rel)));
+    if (inside === '' || inside === '..' || inside.startsWith(`..${path.sep}`) || path.isAbsolute(inside)) return null;
+    return inside.split(path.sep).join('/');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The paths the story's own line carried, recorded on its run config as `include_paths` (cli/lib/run-context.js).
+ * An entry that is not a safe token is counted, never passed on; the rest are judged by judgeRequest with the
+ * request, because the config can be written by any client of the org.
+ * @param {object} run  a `GET /orchestrate/:runId` payload
+ * @returns {{paths: string[], dropped: number}}
+ */
+function originalPathsOf(run) {
+  const list = run && run.config && Array.isArray(run.config.include_paths) ? run.config.include_paths : [];
+  const paths = [];
+  let dropped = 0;
+  for (const entry of list) {
+    if (!isSafeToken(entry)) dropped += 1;
+    else if (!paths.includes(entry)) paths.push(entry);
+  }
+  return { paths, dropped };
+}
+
+/**
+ * The batch id `hone queue-stories --format json` printed. The command prints its per-story lines first and the
+ * response document last, and the document starts at a line that is exactly `{`.
+ * @returns {string|null} a batch id, or null when no document with one is there
+ */
+function batchIdFromQueueOutput(stdout) {
+  const text = String(stdout || '');
+  const starts = [...text.matchAll(/^\{$/gm)].map((m) => m.index).reverse();
+  for (const at of starts) {
+    try {
+      const doc = JSON.parse(text.slice(at));
+      if (doc && isBatchId(doc.batchId)) return doc.batchId;
+    } catch { /* not the document; try the next opening brace back */ }
+  }
+  return null;
+}
+
+/**
+ * Has this story already been served? From `GET /orchestrate?storyId=&repoName=` rows (id, story_id, repo_name,
+ * status, created_at, error_message), newest first.
+ *  - `later`: a run of the story in this repository, created AFTER the paused one and not killed. A re-serve that
+ *    queued but whose kill failed, or that died between the two, leaves exactly this and no marker.
+ *  - `earlier`: a run of the story killed with `re-served as batch <id>` BEFORE this one, so this run is that
+ *    re-serve (the loop was started on the new batch alone) and a second pause here is the second.
+ *  - `unknown`: the paused run's creation time is not a date, so neither can be told.
+ * @returns {{kind: 'later'|'earlier'|'unknown', runId?: string, batchId?: string}|null}
+ */
+function serveHistory(rows, { runId, storyId, repoName, since }) {
+  const t0 = Date.parse(since);
+  if (!Number.isFinite(t0)) return { kind: 'unknown' };
+  for (const row of Array.isArray(rows) ? rows : []) {
+    if (!row || row.id === runId || row.story_id !== storyId || row.repo_name !== repoName) continue;
+    const t = Date.parse(row.created_at);
+    if (!Number.isFinite(t)) continue;
+    if (t > t0 && row.status !== 'killed') return { kind: 'later', runId: row.id };
+    const batchId = t < t0 ? reservedBatchOf({ status: row.status, errorMessage: row.error_message }) : null;
+    if (batchId) return { kind: 'earlier', runId: row.id, batchId };
+  }
+  return null;
+}
+
+/**
+ * serveHistory over the server, and, for a `later` run, the batch it is in (found among the batches created since the
+ * paused run, newest first, at most 10; a lookup that fails only costs the batch id).
+ * @param {{listRuns: (storyId: string, repoName: string) => Promise<object[]>, listBatches: () => Promise<object[]>,
+ *          fetchBatch: (id: string) => Promise<object>}} io
+ * @param {{runId: string, storyId: string, repoName: string|null, since: string|null}} action
+ */
+async function findServe(io, action) {
+  const hit = serveHistory(await io.listRuns(action.storyId, action.repoName), action);
+  if (!hit || hit.kind !== 'later') return hit;
+  try {
+    const since = Date.parse(action.since) - 60_000;
+    const recent = (await io.listBatches()).filter((b) => b && isBatchId(b.batchId) && !(Date.parse(b.createdAt) < since)).slice(0, 10);
+    for (const b of recent) {
+      const batch = await io.fetchBatch(b.batchId);
+      if ((Array.isArray(batch && batch.runs) ? batch.runs : []).some((r) => r && r.runId === hit.runId)) return { ...hit, batchId: b.batchId };
+    }
+  } catch { /* the batch is only worth following if it can be found */ }
+  return hit;
+}
+
+/**
+ * The regular files in `git ls-files -z -s` output. A symlink (120000) and a submodule (160000) are tracked but
+ * are not files this checkout holds, and a symlink can point anywhere; a conflicted path (stage above 0) has no
+ * single content.
+ * @param {string} output
+ * @returns {Set<string>}
+ */
+function trackedRegularFiles(output) {
+  const files = new Set();
+  for (const entry of String(output || '').split('\0')) {
+    const m = entry.match(/^(\d{6}) [0-9a-f]+ (\d)\t(.+)$/s);
+    if (m && m[2] === '0' && (m[1] === '100644' || m[1] === '100755')) files.add(m[3]);
+  }
+  return files;
+}
+
+module.exports = {
+  RESERVED_PREFIX, reserveReason, reservedBatchOf, hardPauseRequest, requestRefusal, contentRefusal, judgeRequest, repoRealPath,
+  originalPathsOf, serveHistory, findServe, batchIdFromQueueOutput, trackedRegularFiles,
+};

package/lib/detect-test-framework.js

@@ -0,0 +1,54 @@
+'use strict';
+/**
+ * detect-test-framework.js — what `hone setup` finds already installed in an adopter repo: the stack,
+ * test framework, package manager, Playwright, configs and test script, read from package.json, the
+ * lockfiles and the config files on disk.
+ *
+ * HC-CI-019-followup-3: moved verbatim out of cli/hone-cli.js, which cannot be required (it parses
+ * argv on load), so a test can call it. Before the move no suite asserted any of its fields:
+ * deleting each one left every suite the continuity gate selects green. The I/O stays here rather
+ * than behind injected callbacks, so the move changes no behaviour.
+ */
+const fs = require('fs');
+const path = require('path');
+
+function detectExistingTestFramework(repoRoot) {
+  const pkgPath = path.join(repoRoot, 'package.json');
+  if (!fs.existsSync(pkgPath)) return { stack: 'unknown', testFw: null, pkgMgr: null };
+
+  const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+  const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+
+  // Detect stack
+  let stack = 'node';
+  if (allDeps['react']) stack = allDeps['vite'] ? 'react-vite' : 'react';
+  if (allDeps['next']) stack = 'nextjs';
+  if (allDeps['@nestjs/core']) stack = 'nestjs';
+
+  // Detect existing test framework
+  let testFw = null;
+  if (allDeps['vitest']) testFw = 'vitest';
+  else if (allDeps['jest']) testFw = 'jest';
+  else if (allDeps['mocha']) testFw = 'mocha';
+
+  // Detect Playwright
+  const hasPlaywright = !!allDeps['@playwright/test'];
+
+  // Detect package manager
+  let pkgMgr = 'npm';
+  if (fs.existsSync(path.join(repoRoot, 'yarn.lock'))) pkgMgr = 'yarn';
+  if (fs.existsSync(path.join(repoRoot, 'pnpm-lock.yaml'))) pkgMgr = 'pnpm';
+
+  // Detect existing configs
+  const hasTestConfig = ['vitest.config.js', 'vitest.config.ts', 'jest.config.js', 'jest.config.ts', 'jest.config.cjs']
+    .some(f => fs.existsSync(path.join(repoRoot, f)));
+  const hasPlaywrightConfig = fs.existsSync(path.join(repoRoot, 'playwright.config.js'))
+    || fs.existsSync(path.join(repoRoot, 'playwright.config.ts'));
+
+  // Detect existing test script
+  const hasTestScript = !!pkg.scripts?.test && pkg.scripts.test !== 'echo "Error: no test specified" && exit 1';
+
+  return { stack, testFw, hasPlaywright, pkgMgr, hasTestConfig, hasPlaywrightConfig, hasTestScript, pkg };
+}
+
+module.exports = { detectExistingTestFramework };

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/hard-pause-remedy.js

@@ -98,4 +98,4 @@ function renderIncludePathsCommand(storyId, paths) {
   return `hone run-story ${id} ${safe.map((p) => `--include-paths ${tokenOf(p)}`).join(' ')}`;
 }
 
-module.exports = { remedyFor, renderIncludePathsCommand, partitionSafePaths };
+module.exports = { remedyFor, renderIncludePathsCommand, partitionSafePaths, tokenOf, isSafeToken };

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/learnings-sync.js

@@ -67,7 +67,8 @@ function updateTopLevelStatus(yamlText, newStatus) {
     return { text: yamlText, updated: false };
   }
   return {
-    text: yamlText.replace(re, `status: ${newStatus}`),
+    // A function, so a `$&` or `$'` in the status is written as itself, not expanded as a replacement pattern.
+    text: yamlText.replace(re, () => `status: ${newStatus}`),
     updated: true,
   };
 }