@hone-ai/cli 1.38.0 → 1.39.0

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) };

package/lib/run-context.js

@@ -38,7 +38,6 @@ const {
   extractType, extractSecurityImplications, extractCrossRepoDependency,
 } = require('./story-classifier-extract');
 const { readArchitectConfigFromText } = require('./architect-config');
-const { remoteHostFromUrl } = require('./story-provenance');
 const path = require('path');
 
 /**
@@ -121,7 +120,8 @@ async function issueStorySource(io, issueNumber, issue) {
       author: (api.user && api.user.login) || null,
       association: api.author_association,
       html_url: api.html_url,
-      remoteHost: remoteHostFromUrl(got.remoteUrl),
+      // HC-GF-283: the host BOTH gh calls were told about — an SSH alias already resolved to it.
+      remoteHost: (got && got.host) || null,
     };
     return { source, notes: [info(`  → story provenance: ${source.author || 'unknown'} (author_association: ${source.association || 'unknown'})`)] };
   } catch (e) {
@@ -311,7 +311,8 @@ function resolveRepoContext(io, opts = {}) {
  * @param {object} io
  * @param {(n: string) => Promise<{title:string, body?:string, url:string}>|{title:string, body?:string, url:string}} io.fetchIssue
  *   rejects or throws on failure
- * @param {(n: string) => Promise<{owner:string, repo:string, remoteUrl:string, issue:object}>} io.fetchIssueProvenance
+ * @param {(n: string) => Promise<{owner:string, repo:string, remoteUrl:string, host:string, issue:object}>} io.fetchIssueProvenance
+ *   `host` is the GitHub host the call was made against (HC-GF-283), which the provenance check compares with html_url's
  *   HC-GF-270: `gh api repos/<owner>/<repo>/issues/<n>`; rejects with gh's stderr on the error, and
  *   `where: {owner, repo}` once the remote was parsed
  * @param {(id: string) => Promise<object>} io.fetchStoryContext  GET /stories/:id/context; throws
@@ -437,6 +438,10 @@ async function resolveStoryContext(io, repoCtx, storyId, opts = {}) {
   // JSON-lines repo).
   const bundle = { files: 0, chars: 0 };
   const includePaths = opts.includePaths || [];
+  // HC-GF-351: what the operator named, recorded on the run so follow-batch can carry it into a re-serve. Never
+  // inferred: the story's own paths and the defaults are re-derived whenever a story is resolved again.
+  const operatorPaths = parseIncludePaths(includePaths);
+  if (operatorPaths.length) config.include_paths = operatorPaths;
   const defaultIncludePaths = repoCtx.defaultIncludePaths || [];
   if (rawText || parseIncludePaths(includePaths).length > 0 || defaultIncludePaths.length > 0) {
     try {
@@ -575,6 +580,23 @@ async function resolveStoryContext(io, repoCtx, storyId, opts = {}) {
     pre.push(warn('    Fix: hone run-story <id> --include-paths path/one.js,path/two.js'));
   }
 
+  // ── Call sites (HC-GF-217) ────────────────────────────────────────────────────────────────
+  // The planner is told to enumerate every call site of a shared function it changes, and a server-executed
+  // agent has no checkout to search (cwd is a temp dir, deliberately). This CLI has the checkout: it searches for
+  // the compound identifiers the story puts in backticks and sends the result for the server to render. It runs
+  // whatever the classifier axes turn out to be, because the shared-chokepoint axis is harvested from step_0's
+  // output, after this bundle has been sent. Fail-soft: a search that cannot run costs the planner its
+  // enumeration (it then says so and pauses), never the queueing of the story.
+  if (rawText && typeof io.callSites === 'function') {
+    try {
+      const found = await io.callSites(rawText);
+      if (found && found.callSites) config.call_sites = found.callSites;
+      for (const n of (found && found.notes) || []) pre.push(n);
+    } catch (e) {
+      pre.push(warn(`  ⚠ call-site search failed (non-fatal): ${firstLine(e)} — the planner will have no call-site enumeration for this story`));
+    }
+  }
+
   // ── Classifier axes (HC-COMM-010) ─────────────────────────────────────────────────────────
   // Explicit --axes wins. Otherwise the DETERMINISTIC axes from the extractors; judgment axes
   // come from the groomer at step_0 and are harvested server-side. Fail-open.

package/lib/run-target.js

@@ -18,6 +18,8 @@
  * `error` and decides the exit code.
  */
 
+const path = require('node:path');
+
 const RUN_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
 // GET /orchestrate clamps `limit` to 1..100, lists newest first, and is scoped to the caller's org.
@@ -112,6 +114,19 @@ const isDeriveJobId = (s) => typeof s === 'string' && /^drv_[0-9a-f]{12}$/.test(
 // safe; these three it cannot, because `new URL()` resolves `.` and `..` as directory steps.
 const isPathName = (s) => typeof s === 'string' && s !== '' && s !== '.' && s !== '..';
 
+// HC-GF-270-followup-3: a story id names a directory (`.github/pipeline/<id>/`, `.github/metrics/<id>.yml`).
+// The branch extractor (pipeline-status.js STORY_ID_PATTERN) emits only `[A-Za-z0-9_-]` but has no length cap,
+// so an id read from a branch is checked too (step-5b, metrics collect, verify-pr); the fallbacks are
+// `unknown-story` and `no-story`. No `.`, `/` or `\`, so `../` cannot leave the directory; 80 characters, the cap
+// server/src/routes/stories.js applies (MAX_STORY_ID_LEN). Its STORY_ID_SHAPE is stricter (no `_`): it decides
+// what the server stores, this decides what may name a local directory.
+const isStoryId = (s) => typeof s === 'string' && /^[A-Za-z0-9][A-Za-z0-9_-]{0,79}$/.test(s);
+// A ref git or gh may receive as ONE argument. `;`, `$(` and quotes are harmless there (and legal in ref names);
+// a leading `-` is not: `git diff --name-only '--output=x...HEAD'` writes a file. `--end-of-options` would
+// also stop it, but only on git 2.24 and later — on an older git every diff would fail and an audit would pass
+// on nothing, so the value is refused instead.
+const isGitRev = (s) => typeof s === 'string' && s !== '' && !s.startsWith('-') && !s.includes('\0');
+
 const KINDS = {
   runId: { ok: isRunId, why: 'must be a run ID (a UUID)', hint: ' — run IDs: hone workflows' },
   batchId: { ok: isBatchId, why: 'must be a batch ID (a UUID)', hint: ' — batch IDs: hone queue-stories --list' },
@@ -119,11 +134,27 @@ const KINDS = {
   attempt: { ok: isAttempt, why: 'must be a whole number from 1, like 2', hint: '' },
   deriveJobId: { ok: isDeriveJobId, why: 'must be a derive job ID, like drv_0123456789ab', hint: ' — the ID "hone derive --refresh" printed' },
   pathName: { ok: isPathName, why: 'must be a name, not empty, "." or ".."', hint: '' },
+  storyId: { ok: isStoryId, why: 'must be a story ID, like HC-GF-270 (letters, digits, "-" and "_")', hint: '' },
+  gitRev: { ok: isGitRev, why: 'must be a git branch or revision, not empty and not starting with "-"', hint: '' },
+  count: { ok: isAttempt, why: 'must be a whole number from 1, like 15', hint: '' },
 };
 
+/**
+ * HC-GF-270-followup-3: the directory a story id names under `baseDir`, refusing any id that is not one — or that
+ * resolves anywhere but one level under `baseDir`, checked independently of the pattern. Every verb that writes
+ * here refused a bad id first (`runArgsError`, kind `storyId`), so a throw here is a bug, not an input error.
+ */
+function storyDir(baseDir, storyId) {
+  const base = path.resolve(String(baseDir));
+  if (!isStoryId(storyId)) throw new TypeError(`storyDir: ${JSON.stringify(storyId)} is not a story ID`);
+  const dir = path.resolve(base, storyId);
+  if (path.dirname(dir) !== base) throw new TypeError(`storyDir: ${JSON.stringify(storyId)} leaves ${base}`);
+  return dir;
+}
+
 /**
  * The first failed check's message, or null when every check passes.
- * @param {Array<{ label: string, kind: 'runId'|'batchId'|'stepKey'|'attempt'|'deriveJobId'|'pathName', value: any, optional?: boolean }>} checks
+ * @param {Array<{ label: string, kind: 'runId'|'batchId'|'stepKey'|'attempt'|'deriveJobId'|'pathName'|'storyId'|'gitRev'|'count', value: any, optional?: boolean }>} checks
  *   `label` is the flag or positional as the operator typed it. An `optional` check passes when the value
  *   is undefined (a flag that was not given); an empty string is always checked.
  */
@@ -179,5 +210,6 @@ function orchestratePath(segments, query) {
 
 module.exports = {
   resolveRunTarget, isRunId, LOOKUP_LIMIT,
-  isStepKey, isAttempt, isBatchId, isDeriveJobId, isPathName, runArgsError, apiPath, orchestratePath,
+  isStepKey, isAttempt, isBatchId, isDeriveJobId, isPathName, isStoryId, isGitRev, storyDir,
+  runArgsError, apiPath, orchestratePath,
 };

package/lib/story-line.js

@@ -2,9 +2,15 @@
 /**
  * story-line.js — one line of a `hone queue-stories --file` list.
  *
- * `STORY-ID` or `STORY-ID depends:DEP1,DEP2`. The `depends:` token is case-sensitive and must come
- * after the storyId; multiple deps are comma-separated and whitespace tolerant. A line with no
- * `depends:` yields no `dependsOn` at all — the server validates absence differently from empty.
+ * `STORY-ID`, optionally followed by `depends:DEP1,DEP2` and/or `paths:a.js,b.js`, in either order. Both
+ * tokens are case-sensitive, must come after the storyId, and may each appear once; their lists are
+ * comma-separated and whitespace tolerant. A line with no `depends:` yields no `dependsOn` at all — the server
+ * validates absence differently from empty — and a line with no `paths:` yields no `paths`.
+ *
+ * `paths:` (HC-GF-351) is `run-story --include-paths` for one story of a batch: the files the bundler must put
+ * in that story's context. A batch cannot carry the flag, and `run-story` runs carry no batch id, so
+ * `follow-batch` cannot follow them. The entries are checked where `--include-paths` entries are, by the
+ * bundler (cli/lib/run-context.js), not here: this module only splits the line.
  *
  * Extracted by HC-GF-140 stage 2. The regex was pinned by its SOURCE TEXT
  * (`assert.match(cliSrc, /\^\(\\S\+\)\\s\+depends:\(\\S\+\)\\s\*\$/)`), which is the worst shape a
@@ -19,22 +25,52 @@ function isStoryLine(line) {
   return Boolean(t) && !t.startsWith('#');
 }
 
+const csv = (s) => s.split(',').map((x) => x.trim()).filter(Boolean);
+const unique = (list) => list.filter((x, i) => list.indexOf(x) === i);
+
 /**
  * @param {string} line
- * @returns {{storyId: string, dependsOn?: string[]}|{error: string}}
+ * @returns {{storyId: string, dependsOn?: string[], paths?: string[]}|{error: string}}
  *   `error` for a line the caller must reject — a storyId followed by anything unrecognised.
- *   Silently treating `STORY-A something` as `STORY-A` loses the operator's intent.
+ *   Silently treating `STORY-A something` as `STORY-A` loses the operator's intent. So does a
+ *   `paths:` that names no path: the operator meant to bundle something.
  */
 function parseStoryLine(line) {
   const t = String(line).trim();
-  const m = t.match(/^(\S+)\s+depends:(\S+)\s*$/);
-  if (m) {
-    return { storyId: m[1], dependsOn: m[2].split(',').map(s => s.trim()).filter(Boolean) };
+  const bad = { error: `Malformed line in --file: "${t}"` };
+  const [storyId, ...tokens] = t.split(/\s+/);
+  const out = { storyId };
+  for (const tok of tokens) {
+    if (tok.startsWith('depends:') && tok.length > 'depends:'.length && !('dependsOn' in out)) {
+      out.dependsOn = csv(tok.slice('depends:'.length));
+    } else if (tok.startsWith('paths:') && !('paths' in out)) {
+      const paths = unique(csv(tok.slice('paths:'.length)));
+      if (paths.length === 0) return bad;
+      out.paths = paths;
+    } else {
+      return bad;
+    }
   }
-  if (/\s/.test(t)) {
-    return { error: `Malformed line in --file: "${t}"` };
+  return out;
+}
+
+/**
+ * The line `parseStoryLine` reads back as the same story — for a caller that writes a stories file
+ * (follow-batch's re-serve). Throws on a value the line cannot carry, rather than writing a line that parses as
+ * something else: whitespace splits a token, and a comma splits a list.
+ * @param {{storyId: string, dependsOn?: string[], paths?: string[]}} story
+ */
+function formatStoryLine({ storyId, dependsOn, paths } = {}) {
+  const carries = (v) => typeof v === 'string' && v !== '' && !/[\s,]/.test(v);
+  if (!carries(storyId)) throw new TypeError(`formatStoryLine: ${JSON.stringify(storyId)} is not a story id a line can carry`);
+  const parts = [storyId];
+  for (const [token, list] of [['depends', dependsOn], ['paths', paths]]) {
+    if (!Array.isArray(list) || list.length === 0) continue;
+    const bad = list.find((v) => !carries(v));
+    if (bad !== undefined) throw new TypeError(`formatStoryLine: ${JSON.stringify(bad)} cannot be written in ${token}:`);
+    parts.push(`${token}:${list.join(',')}`);
   }
-  return { storyId: t };
+  return parts.join(' ');
 }
 
-module.exports = { parseStoryLine, isStoryLine };
+module.exports = { parseStoryLine, isStoryLine, formatStoryLine };

package/lib/story-provenance.js

@@ -53,11 +53,12 @@ function isIssueShapedId(storyId) {
 /**
  * Is this a HOSTNAME we may compare against `html_url`'s host?
  *
- * Binding decision 2 (operator, step_1 gate of run fa6e00c4): compare hosts ONLY when the
- * remote's host is a dotted domain — the GitHub Enterprise case. An SSH host alias such as
- * `github-work` from `~/.ssh/config` is not a hostname, and treating it as one would make
- * every collaborator's issue untrusted for every operator who uses one. That false
- * fail-closed is the version of this feature that gets reverted.
+ * HC-GF-270's binding decision 2 (operator, step_1 gate of run fa6e00c4) compared hosts ONLY when
+ * the remote's host was a dotted domain, because an SSH alias such as `github-work` is not a
+ * hostname and comparing it would refuse every collaborator's issue for every operator who uses
+ * one. HC-GF-283 removes the reason for the exception: run-story now resolves an alias with
+ * `ssh -G` (cli/lib/git-remote.js) and records the REAL host, so the comparison runs always, and a
+ * recorded host that is still not a hostname is a host nobody established — untrusted.
  */
 function isDottedDomain(host) {
   const h = String(host == null ? '' : host).trim();
@@ -237,13 +238,18 @@ function assessStorySource(source, storyId) {
         + 'or the request redirected to a different repository');
     }
 
-    const remoteHost = source.remoteHost;
-    if (isDottedDomain(remoteHost)) {
-      const rh = String(remoteHost).trim().toLowerCase();
-      if (rh !== url.hostname.toLowerCase()) {
-        return no('issue', `the git remote's host ${rh} is not ${url.hostname.toLowerCase()} — the issue was read `
-          + 'from a different GitHub host than this repository lives on, where someone else can own the same name');
-      }
+    // HC-GF-283: ALWAYS. An unresolved alias left gh on its default host, where the same owner/repo
+    // name can belong to someone else — the case binding decision 2's exception let through.
+    const rh = String(source.remoteHost == null ? '' : source.remoteHost).trim().toLowerCase();
+    if (!isDottedDomain(rh)) {
+      return no('issue', rh
+        ? `the git remote's host was recorded as '${rh}', which is not a hostname — an SSH alias that was never `
+          + `resolved (a run started before HC-GF-283), so which GitHub host issue ${refLabel(source)} was read from cannot be checked`
+        : `no git remote host was recorded for issue ${refLabel(source)}, so which GitHub host it was read from cannot be checked`);
+    }
+    if (rh !== url.hostname.toLowerCase()) {
+      return no('issue', `the git remote's host ${rh} is not ${url.hostname.toLowerCase()} — the issue was read `
+        + 'from a different GitHub host than this repository lives on, where someone else can own the same name');
     }
 
     return yes('issue', `issue ${refLabel(source)} was authored by ${source.author || 'an unknown user'} `
@@ -258,6 +264,7 @@ function assessStorySource(source, storyId) {
 module.exports = {
   assessStorySource,
   remoteHostFromUrl,
+  rawRemoteHost,
   isIssueShapedId,
   isDottedDomain,
   refLabel,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hone-ai/cli",
-  "version": "1.38.0",
+  "version": "1.39.0",
   "description": "Hone AI — Enterprise SDLC Pipeline CLI",
   "main": "hone-cli.js",
   "bin": {