@hone-ai/cli 1.37.0 → 1.38.1

package/lib/operator-question.js

@@ -0,0 +1,94 @@
+/**
+ * operator-question.js — HC-GF-234: render the operator question(s) a step asked and nobody answered.
+ *
+ * A step that ends by asking the operator something used to be recorded exactly like a step that
+ * did its work (`status: completed`, `gateResult: approved`). The server now stores
+ * `{ count, questions }` on the step's attempt row and carries it as `operatorQuestion` on
+ * `GET /orchestrate/:runId` and `.../step/:stepKey`. Four CLI surfaces print it — `--status`,
+ * `show step`, the human-gate prompt, and the NEEDS YOU list — and they share this module so the
+ * wording and the two honesty rules below cannot drift apart.
+ *
+ * PURE: data in, strings out. No fs, no console, no process — a leaf, so run-report.js can keep
+ * its "derived, never narrated" contract and require it.
+ *
+ * TWO HONESTY RULES.
+ *   - `count` is the TRUE number of questions the step asked; `questions` holds at most the first
+ *     five. When count exceeds what is stored, the surfaces say "+N more not stored" instead of
+ *     letting a short list read as the whole of it.
+ *   - The text is AGENT-WRITTEN and goes to a terminal. The server scrubs control characters
+ *     before storing, but this CLI may talk to an older or different server, so it scrubs again
+ *     at the point of printing: C0/C1 controls, DEL, and the bidirectional controls that reorder
+ *     what a terminal draws.
+ *
+ * TOLERANT OF AN OLDER SERVER BY CONSTRUCTION: a missing key, null, or a payload of the wrong
+ * shape normalises to null, which is today's output (nothing printed).
+ */
+
+// U+061C ARABIC LETTER MARK is the third bidi mark beside LRM/RLM (review round 3 F3). Written as
+// \u escapes: a literal bidi character in this source would reorder how THIS file reads.
+// eslint-disable-next-line no-control-regex -- the whole point is to match control chars.
+const TERMINAL_UNSAFE_RE = /[\x00-\x1f\x7f-\x9f\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]/g;
+
+function scrub(text) {
+  return String(text == null ? '' : text).replace(TERMINAL_UNSAFE_RE, '');
+}
+
+/**
+ * @param {*} oq  a step's `operatorQuestion`, straight off the network (not trusted to have a shape)
+ * @returns {{count:number, questions:string[], more:number}|null}  null = the step did not ask
+ */
+function normalizeQuestion(oq) {
+  if (!oq || typeof oq !== 'object') return null;
+  const count = Math.floor(Number(oq.count));
+  if (!Number.isFinite(count) || count < 1) return null;
+  const questions = (Array.isArray(oq.questions) ? oq.questions : []).map(scrub);
+  return { count, questions, more: Math.max(0, count - questions.length) };
+}
+
+// Clips by CODE POINT, not UTF-16 unit (review round 3 F4): a `.slice(0, max)` that lands between
+// the halves of an emoji prints a lone surrogate, which a terminal draws as U+FFFD.
+function clip(text, max) {
+  if (!Number.isFinite(max)) return text;
+  const points = Array.from(text);
+  return points.length > max ? `${points.slice(0, max).join('')}...` : text;
+}
+
+/**
+ * One entry per stored question (`- <question>`, clipped to `max` chars) and, when the step asked
+ * more than was stored, a closing `+ N more not stored`. Callers add their own indentation.
+ */
+function questionLines(asked, { max = Infinity } = {}) {
+  if (!asked) return [];
+  const lines = asked.questions.map((q) => `- ${clip(q, max)}`);
+  if (asked.more > 0) lines.push(`+ ${asked.more} more not stored`);
+  return lines;
+}
+
+function countPhrase(count) {
+  return `${count} question${count === 1 ? '' : 's'}`;
+}
+
+/**
+ * The block printed at the human gate, right before "Approve?" — the one place the operator
+ * decides, and where approving silently consumes the question without answering it.
+ *
+ * SCOPED TO THE STEP THE RUN IS PAUSED AT (`stepKey`), the same discipline as
+ * hard-pause-remedy.js's remedyFor: the column is durable, so a question step_3b asked must not
+ * be re-printed as if it belonged to an unrelated step_4 gate.
+ *
+ * @param {object} status  a GET /orchestrate/:runId payload
+ * @param {string} stepKey the step the gate is for
+ * @returns {string[]} lines to print (empty when that step asked nothing)
+ */
+function gateQuestionLines(status, stepKey) {
+  const steps = status && Array.isArray(status.steps) ? status.steps : [];
+  const step = steps.find((x) => x && typeof x === 'object' && x.stepKey === stepKey);
+  const asked = step ? normalizeQuestion(step.operatorQuestion) : null;
+  if (!asked) return [];
+  return [
+    `  ${stepKey} asked ${countPhrase(asked.count)} that nobody has answered — approving does not answer ${asked.count === 1 ? 'it' : 'them'}:`,
+    ...questionLines(asked, { max: 240 }).map((l) => `    ${l}`),
+  ];
+}
+
+module.exports = { normalizeQuestion, questionLines, gateQuestionLines, countPhrase };

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

package/lib/run-report.js

@@ -16,6 +16,10 @@
  * Rendering is separate so both are testable without a server.
  */
 
+// HC-GF-234: the one wording for a step's unanswered question, shared with `--status`, `show
+// step` and the human-gate prompt. A pure leaf module, so this file stays pure.
+const { normalizeQuestion, questionLines, countPhrase } = require('./operator-question');
+
 /** Gate verdicts the pipeline already speaks. Do not invent synonyms. */
 const ACTIONABLE_GATE_VERDICTS = ['fail', 'unavailable'];
 
@@ -324,6 +328,31 @@ function buildReport(run, extra = {}) {
     }
   }
 
+  // 1e. HC-GF-234: a step that ended by asking the operator something.
+  //
+  // `status: completed` / `gateResult: approved` cannot say this: batch mode has no human gate on
+  // steps 0-3b, and approving a gate records `approved` whether or not the question was read. The
+  // step row carries the question on its own column; this is the only place a TERMINAL run's
+  // report can tell "did its work" from "asked, and nobody here answered".
+  //
+  // Says only what is MEASURED — the step asked, and the run has no answer to it. It does not say
+  // the step produced no deliverable or that the run proceeded on a guess: nothing checks either.
+  //
+  // ADVISORY (HC-026c: a new signal REPORTS before it GATES): `hone run-report` exits 1 on any
+  // non-advisory item, and an agent that asks one benign question must not turn an adopter's
+  // passing script red overnight. Visible in the report, absent from the exit code.
+  for (const s of steps) {
+    const asked = normalizeQuestion(s.operatorQuestion);
+    if (!asked) continue;
+    needsYou.push({
+      what: `${s.stepKey} (${s.agent || 'agent'}) asked ${countPhrase(asked.count)} that nothing in this run answered`,
+      detail: questionLines(asked, { max: 200 }),
+      how: `hone show step ${run.runId} ${s.stepKey}`,
+      howLabel: 'inspect',
+      advisory: true,
+    });
+  }
+
   // 2. The last verification is ONE event, so it becomes ONE item with sub-lines.
   //    Listing "verification failed" and "lint failed" separately gave two entries
   //    for one problem resolved by one fix — and NEEDS YOU is a list of DISTINCT

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.
@@ -104,17 +106,55 @@ async function resolveRunTarget({ client, idOrStory, repoName, flag }) {
 const isStepKey = (s) => typeof s === 'string' && /^step_[0-9a-z_]+$/i.test(s);
 const isAttempt = (s) => (typeof s === 'string' || typeof s === 'number') && /^[1-9]\d{0,8}$/.test(String(s));
 const isBatchId = isRunId;
+// HC-GF-270-followup-2: POST /derive is the only producer of a derive job id (server/src/routes/derive.js),
+// and it issues `drv_` + 12 lower-case hex characters into a TEXT key compared exactly, so no other shape
+// can name a job. `hone approve --job` GETs and then POSTs under that id.
+const isDeriveJobId = (s) => typeof s === 'string' && /^drv_[0-9a-f]{12}$/.test(s);
+// A name that becomes ONE path segment, such as a repository name. Encoding makes any other character
+// 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' },
   stepKey: { ok: isStepKey, why: 'must name a step, like step_4', hint: '' },
   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', 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.
  */
@@ -130,23 +170,29 @@ function runArgsError(checks) {
 }
 
 /**
- * The one way a CLI verb builds an `/orchestrate/…` path. Each segment is encoded exactly once, and the
- * segments encoding cannot make safe (empty, `.`, `..`, null, undefined) throw: every caller-supplied value
- * has passed `runArgsError` first, so a throw here is a bug, not an input error. Query values that are
- * null, undefined, false or '' are dropped; the rest go through URLSearchParams.
+ * The one way the CLI builds a path on the Hone API: `/<prefix>/<segment>/…?<query>`. `prefix` is a
+ * literal resource name (`derive`, `skills`, …), never a value. Each segment is encoded exactly once, and
+ * the segments encoding cannot make safe (empty, `.`, `..`, null, undefined) throw: every caller-supplied
+ * value has passed `runArgsError` first, so a throw here is a bug, not an input error. Query values that
+ * are null, undefined, false or '' are dropped; the rest go through URLSearchParams.
  *
  * Callers pass raw values. A pre-encoded segment would be encoded twice (`%` becomes `%25`), and the
- * HC-GF-270-followup-1 scan fails on one.
+ * HC-GF-270-followup-2 scan fails on one.
+ *
+ * HC-GF-270-followup-2: generalized from orchestratePath. HC-GF-270-followup-1 closed the defect under
+ * `/orchestrate/`; `/derive/`, `/skills/`, `/prompts/`, `/scripts/` and `/stories/` were still built by
+ * hand, and `hone approve --job` POSTed under an id nothing checked.
  */
-function orchestratePath(segments, query) {
-  if (!Array.isArray(segments) || segments.length === 0) throw new TypeError('orchestratePath: segments must be a non-empty array');
+function apiPath(prefix, segments, query) {
+  if (typeof prefix !== 'string' || !/^[a-z][a-z0-9-]*$/.test(prefix)) throw new TypeError(`apiPath: prefix must be a resource name, got ${JSON.stringify(prefix)}`);
+  if (!Array.isArray(segments)) throw new TypeError('apiPath: segments must be an array');
   const parts = segments.map((v, i) => {
-    if (v === null || v === undefined) throw new TypeError(`orchestratePath: segment ${i} is ${v}`);
+    if (v === null || v === undefined) throw new TypeError(`apiPath: segment ${i} is ${v}`);
     const s = String(v);
-    if (s === '' || s === '.' || s === '..') throw new TypeError(`orchestratePath: segment ${i} is ${JSON.stringify(s)}`);
+    if (s === '' || s === '.' || s === '..') throw new TypeError(`apiPath: segment ${i} is ${JSON.stringify(s)}`);
     return encodeURIComponent(s);
   });
-  const base = ['', 'orchestrate', ...parts].join('/');
+  const base = ['', prefix, ...parts].join('/');
   const qs = new URLSearchParams();
   for (const [k, v] of Object.entries(query || {})) {
     if (v === null || v === undefined || v === false || v === '') continue;
@@ -156,7 +202,14 @@ function orchestratePath(segments, query) {
   return q ? `${base}?${q}` : base;
 }
 
+/** An `/orchestrate/…` path: `apiPath('orchestrate', …)` with at least one segment (HC-GF-270-followup-1). */
+function orchestratePath(segments, query) {
+  if (!Array.isArray(segments) || segments.length === 0) throw new TypeError('orchestratePath: segments must be a non-empty array');
+  return apiPath('orchestrate', segments, query);
+}
+
 module.exports = {
   resolveRunTarget, isRunId, LOOKUP_LIMIT,
-  isStepKey, isAttempt, isBatchId, runArgsError, orchestratePath,
+  isStepKey, isAttempt, isBatchId, isDeriveJobId, isPathName, isStoryId, isGitRev, storyDir,
+  runArgsError, apiPath, orchestratePath,
 };

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.37.0",
+  "version": "1.38.1",
   "description": "Hone AI — Enterprise SDLC Pipeline CLI",
   "main": "hone-cli.js",
   "bin": {