@hone-ai/cli 1.34.0 → 1.35.0

package/lib/pipeline-config.js

@@ -388,6 +388,47 @@ function readExecutionMode(repoRoot) {
   return DEFAULT_EXECUTION_MODE;
 }
 
+/**
+ * HC-GF-097: the execution mode AS WRITTEN, beside the normalized one. `readExecutionMode` maps any
+ * value it does not know to 'server', which is the right default for a run an operator is
+ * watching — and the wrong one for an unattended overnight batch, where "server" is a guess about a
+ * typo nobody will see. queue-stories refuses `--overnight` on an unrecognised mode, so it has to
+ * be able to tell `mode: edtior` from no `mode:` at all. Same candidate order as readExecutionMode.
+ *
+ * @param {string} repoRoot
+ * @returns {{ raw: string|null, mode: 'server'|'editor', recognized: boolean }}
+ *   raw is null when no config declares a mode (the default is a recognised state).
+ */
+function readExecutionModeRaw(repoRoot) {
+  const none = { raw: null, mode: DEFAULT_EXECUTION_MODE, recognized: true };
+  if (!repoRoot || typeof repoRoot !== 'string') return none;
+  const candidates = [
+    path.join(repoRoot, '.pipeline-config.yml'),
+    path.join(repoRoot, '.github/.pipeline-config.yml'),
+  ];
+  for (const p of candidates) {
+    if (!fs.existsSync(p)) continue;
+    let raw;
+    try { raw = fs.readFileSync(p, 'utf8'); } catch { continue; }
+    let parsed;
+    try {
+      const yaml = require('js-yaml');
+      parsed = yaml.load(raw);
+    } catch { continue; }
+    if (!parsed || typeof parsed !== 'object') continue;
+    const block = parsed.execution;
+    if (!block || typeof block !== 'object') continue;
+    if (block.mode === undefined) continue;
+    const written = String(block.mode == null ? '' : block.mode);
+    return {
+      raw: written,
+      mode: normalizeExecutionMode(block.mode),
+      recognized: EXECUTION_MODES.includes(written.toLowerCase().trim()),
+    };
+  }
+  return none;
+}
+
 // ── HC-019n-followup-34: closed-loop verification gate ────────────────────────
 // The CLI verbs (verify-patch/verify-pr) EXECUTE and report a verdict to the
 // server. `verification.gate` controls what the server does with it:
@@ -542,7 +583,147 @@ function readAgentEvalConfig(repoRoot) {
   return { targets: [] };
 }
 
+
+// ── HC-GF-169: the adopter-declared scratch datastore ────────────────────────────────────────
+//
+// `.pipeline-config.yml` had no data-layer concept, so no step could validate behaviour needing
+// stored state — which is most of an adopter's backend. The contract is the one `ci.local_command`
+// already uses: Hone cannot know their datastore, so the adopter declares it and the CLI executes
+// it adopter-side, where `verify-patch` already runs with their credentials.
+//
+// THE GUARD IS THE LOAD-BEARING PART. Seeding test rows into a customer's production database is
+// the worst outcome this design can produce, so `verify` is REQUIRED whenever commands are declared
+// and the assertion reads the LIVE CONNECTION, never the URL. A URL can spell `_sandbox` and point
+// anywhere — DNS, a pooler, a tunnel, an overridden PGDATABASE.
+//
+// HC-GF-183, learned from the first live run: THE DATABASE AND THE VERIFY TABLE MUST ALREADY
+// EXIST. The probe runs BEFORE `create` — deliberately, because proving a target is scratch has to
+// precede writing to it — so there is nothing for it to read on a fresh database. That makes
+// `create` responsible for the TABLES, not the database: an adopter writing `create: createdb foo`
+// is refused on their first run with nothing explaining why. Provision the database itself once,
+// out of band, then let `create` build the schema inside it.
+//
+// And `reset` must leave the sandbox PROBEABLE. The CLI runs `reset` then `create` as the teardown
+// (see cli/lib/sandbox-lifecycle.js) precisely so a reset that drops the schema cannot brick the
+// next run — which is exactly what happened the first time this was declared against a real
+// database.
+//
+// Wired since HC-GF-171: verify-patch probes, guards, seeds and tears down.
+const SANDBOX_COMMAND_KEYS = Object.freeze(['create', 'migrate', 'reset']);
+
+/**
+ * @param {string} repoRoot
+ * @returns {null | {create: string|null, migrate: string|null, reset: string|null,
+ *                   capabilities: string[], verify: {database: string, table: string, max_rows: number}}}
+ * @throws when a sandbox declares commands without a usable `verify` block.
+ */
+function readSandboxConfig(repoRoot) {
+  if (!repoRoot || typeof repoRoot !== 'string') return null;
+  for (const p of [path.join(repoRoot, '.pipeline-config.yml'),
+                   path.join(repoRoot, '.github/.pipeline-config.yml')]) {
+    if (!fs.existsSync(p)) continue;
+    let parsed;
+    try { parsed = require('js-yaml').load(fs.readFileSync(p, 'utf8')); } catch { continue; }
+    const block = parsed && typeof parsed === 'object' ? parsed.sandbox : null;
+    if (!block || typeof block !== 'object') continue;
+
+    const str = (v) => (typeof v === 'string' && v.trim() ? v.trim() : null);
+    const commands = {};
+    for (const k of SANDBOX_COMMAND_KEYS) commands[k] = str(block[k]);
+    const declaresWork = SANDBOX_COMMAND_KEYS.some(k => commands[k]);
+
+    const v = block.verify && typeof block.verify === 'object' ? block.verify : null;
+    // HC-GF-171: `probe` is the command that PRODUCES the evidence `assertScratchTarget` demands.
+    // Carried through here, required at ENGAGEMENT (see cli/lib/sandbox-lifecycle.js) rather than
+    // at parse time: a declaration missing it is incomplete, not malformed, and the refusal is far
+    // more useful at the moment the sandbox would have fired — it can name what to add.
+    const verify = v && str(v.database) && str(v.table) && Number.isFinite(Number(v.max_rows))
+      ? { database: str(v.database), table: str(v.table), max_rows: Number(v.max_rows),
+          probe: str(v.probe) }
+      : null;
+
+    if (declaresWork && !verify) {
+      throw new Error(
+        `${p}: sandbox declares ${SANDBOX_COMMAND_KEYS.filter(k => commands[k]).join('/')} but no `
+        + 'usable `verify` block (needs database, table and max_rows). Without it the CLI cannot '
+        + 'prove the target is scratch before writing to it, and an optional guard on this action '
+        + 'is worse than no feature.');
+    }
+    if (!declaresWork && !verify) return null;
+
+    const capabilities = Array.isArray(block.capabilities)
+      ? block.capabilities.map(str).filter(Boolean) : [];
+
+    // HC-GF-192: `test` is the command that READS the sandbox, and `env` is what it reads the
+    // connection from. Carried here and required at ENGAGEMENT, for the same reason `probe` is: a
+    // declaration missing them is incomplete rather than malformed, and the refusal is far more
+    // useful at the moment the sandbox would have fired, where it can name what to add.
+    //
+    // Shape is checked in the plan, not here — `env: DATABASE_URL=…` is valid YAML (a string) and
+    // an invalid env map, and refusing it next to the other engagement refusals keeps one place
+    // that decides whether this sandbox can be used.
+    const test = str(block.test);
+    // Passed through UNVALIDATED, deliberately. An earlier draft tested the type here and then
+    // returned `block.env` on both branches — a guard that read like validation and changed no
+    // outcome, which is the shape this whole chain keeps finding. The real check is
+    // `plainStringMap` in sandbox-lifecycle.js, where a bad `env` becomes a refusal that names the
+    // fix; duplicating it here would mean two places deciding, and eventually disagreeing.
+    const env = block.env === undefined ? null : block.env;
+
+    return { ...commands, capabilities, verify, test, env };
+  }
+  return null;
+}
+
+/**
+ * Refuse unless the LIVE connection proves the target is scratch.
+ *
+ * @param {{database: string, table: string, max_rows: number}} verify  what the adopter declared
+ * @param {{database?: string, rows?: number, url?: string}} probe      what the SERVER reported
+ * @throws when the probe is absent, incomplete, names another database, or the target is populated.
+ */
+function assertScratchTarget(verify, probe) {
+  if (!verify || typeof verify !== 'object') {
+    throw new Error('sandbox verify block missing — refusing to treat any target as scratch');
+  }
+  if (!probe || typeof probe !== 'object') {
+    throw new Error('no live probe — refusing to write. "Could not check" is not "checked and '
+      + 'found nothing"; run the probe or stop.');
+  }
+  // `probe.url` is deliberately ignored. It is accepted only so a caller passing it for logging
+  // cannot mistake this for a check of it.
+  const live = typeof probe.database === 'string' ? probe.database.trim() : null;
+  if (!live) {
+    throw new Error('the probe reported no database name — refusing. The name must come from the '
+      + 'server (e.g. `SELECT current_database()`), not from the connection string.');
+  }
+  if (live !== verify.database) {
+    throw new Error(
+      `refusing to write: the live connection reports database "${live}", but the sandbox declares `
+      + `"${verify.database}". A connection string can spell the sandbox name and still point `
+      + 'elsewhere.');
+  }
+  // A real NUMBER, not something that coerces to one. `Number(null)`, `Number('')`,
+  // `Number(false)` and `Number([])` are all 0, so a probe that reported nothing would read as an
+  // empty database and be allowed — the exact "could not check treated as checked" this refuses.
+  if (typeof probe.rows !== 'number' || !Number.isFinite(probe.rows)) {
+    throw new Error(`refusing to write to "${live}": no row count was probed `
+      + `(got ${JSON.stringify(probe.rows)}). A name match alone is not proof — a restored copy of `
+      + 'production can carry the scratch name.');
+  }
+  const rows = probe.rows;
+  if (rows > verify.max_rows) {
+    throw new Error(
+      `refusing to write to "${live}": ${verify.table} holds ${rows} rows, above the declared `
+      + `ceiling of ${verify.max_rows}. This looks like real data.`);
+  }
+  return true;
+}
+
 module.exports = {
+  readSandboxConfig,
+  assertScratchTarget,
+  SANDBOX_COMMAND_KEYS,
   readSourceDirs,
   readCodebaseDefaults,
   readCIConfigDetails,
@@ -551,6 +732,7 @@ module.exports = {
   EDITOR_MODE_CONSENT_NOTE,
   normalizeExecutionMode,
   readExecutionMode,
+  readExecutionModeRaw,
   readStoryClassifierConfig,
   KNOWN_THRESHOLD_KEYS,
   readCIGateConfig,

package/lib/private-temp.js

@@ -0,0 +1,34 @@
+'use strict';
+/**
+ * private-temp.js — HC-GF-304. A temp file no other process can share.
+ *
+ * check-patch, verify-patch and emit-pr named their diff `os.tmpdir()/hone-<verb>-${Date.now()}.diff`. Two of
+ * them started in the same millisecond on one machine (two worktrees, the MCP server beside the CLI, the
+ * regression suite's parallel files) wrote the SAME path, so one applied, verified or committed the other's
+ * patch. On the runner it was caught applying HC-GF-077's `src/app.js` diff inside HC-GF-098's test repository.
+ * A verify-patch that reads another run's diff can report a pass for a patch that is not its run's, and under
+ * `verification_gate: enforce` that pass approves step_4.
+ *
+ * A clock is not an identity. `fs.mkdtempSync` creates a new directory with a random suffix, atomically, with
+ * mode 0700, so the file inside it belongs to exactly one invocation whatever the time, and nobody else can
+ * plant or replace it.
+ */
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+/**
+ * @param {string} prefix  names the owner in the directory, e.g. 'hone-emit'
+ * @param {string} name    the file's name inside its private directory, e.g. 'patch.diff'
+ * @returns {{ file: string, remove: () => void }}  `remove` deletes the directory and never throws
+ */
+function privateTempFile(prefix, name) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), `${prefix}-`));
+  return {
+    file: path.join(dir, name),
+    remove: () => { try { fs.rmSync(dir, { recursive: true, force: true }); } catch { /* best-effort */ } },
+  };
+}
+
+module.exports = { privateTempFile };

package/lib/promote-payload.js

@@ -0,0 +1,77 @@
+'use strict';
+/**
+ * promote-payload.js — what `hone promote-learnings` sends to `POST /learnings/promote`.
+ *
+ * Extracted by HC-GF-143's batch because HC-GF-136's gate found all seven fields computed inline
+ * and asserted by nothing: deleting any of them broke no test.
+ *
+ * This mapping is an IP BOUNDARY, which is why it is the one to extract first. A learning carries
+ * BOTH `local_summary` (this repo's specifics — paths, story ids, internal detail) and
+ * `enterprise_summary` (the generalised rule). Only the second may leave the machine. A rename, a
+ * copy-paste, or a spread of the whole object would ship the first, and nothing would have noticed.
+ */
+
+/** Fields that may cross to the server. Anything not named here does not leave. */
+const PROMOTED_FIELDS = Object.freeze([
+  'id', 'repo_name', 'type', 'agent', 'target_skill', 'target_kind', 'enterprise_summary',
+  'proposed_fix',
+]);
+
+/** A path that looks like a pipeline script, named in prose. */
+// HC-GF-161: `tests` added. A learning whose fix is "extend this regression test" names a real,
+// editable target in exactly the same way a script does, and 3 learnings were unroutable only
+// because this list omitted it. The backticks and the extension list are NOT relaxed: the
+// backticks are what stop this matching prose that merely mentions a file, and the extensions
+// are what stop it claiming a doc, for which there is no kind.
+const SCRIPT_PATH = /`((?:scripts|cli|server|tests|\.github)\/[\w./-]+\.(?:js|mjs|cjs|sh))`/;
+
+/**
+ * HC-GF-159a: WHAT a learning would change, and what it is called.
+ *
+ * A learning is not always about a skill. It can change a skill, an agent's PROMPT, or a pipeline
+ * SCRIPT — and sending only a field named `target_skill` is why all 418 promoted learnings routed
+ * to the server's `|| 'general'` fallback. The kind travels with the name so the far side can tell
+ * "change pipeline-integrity" from "change the code-reviewer prompt" from "change mutate-check.js".
+ *
+ * Order matters: a learning that names a skill targets the skill even when an agent captured it —
+ * `agent:` records WHO noticed, which is not the same as what should change.
+ *
+ * An unroutable learning says `unrouted` rather than borrowing a default. 'general' is a claim that
+ * the lesson belongs everywhere, which is how 418 of them became indistinguishable.
+ */
+function targetOf(l) {
+  // An explicitly-set `target_skill` is the most specific statement of intent there is — a caller
+  // that already decided. Deriving over the top of it silently overrode the decision, which the
+  // HC-GF-143b suite caught when its fixture's `target_skill` was replaced by the agent name.
+  if (l.target_skill) return { kind: 'skill', name: l.target_skill };
+  if (l.referenced_skill) return { kind: 'skill', name: l.referenced_skill };
+  if (l.agent) return { kind: 'prompt', name: l.agent };
+  const m = SCRIPT_PATH.exec(String(l.proposed_fix || ''));
+  if (m) return { kind: 'script', name: m[1] };
+  return { kind: 'unrouted', name: null };
+}
+
+/**
+ * @param {Array<object>} eligible learnings selected for promotion
+ * @returns {Array<object>} one payload row per learning
+ */
+function promotePayload(eligible) {
+  return (eligible || []).map((l) => {
+    const target = targetOf(l);
+    return {
+      id: l.id || l._file,
+      repo_name: l.repo_name,
+      // HC-GF-159a: `type` and `agent` come from the parser now. They were mapped here from names
+      // the parser never emitted, so JSON.stringify dropped them and the server saw `unknown`.
+      type: l.type || null,
+      agent: l.agent || null,
+      // The NAME the far side routes on, whatever kind of thing it is.
+      target_skill: target.name,
+      target_kind: target.kind,
+      enterprise_summary: l.enterprise_summary,
+      proposed_fix: l.proposed_fix || l.absorbed_into || null,
+    };
+  });
+}
+
+module.exports = { promotePayload, PROMOTED_FIELDS, targetOf };

package/lib/refresh-knowledge.js

@@ -24,9 +24,12 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const crypto = require('node:crypto');
-const { execSync } = require('node:child_process');
+const { execFileSync } = require('node:child_process');
 const { gitEnv } = require('./git-env');
 
+// A backup of the knowledge dirs is seconds of work; this only stops a stuck tar holding the run.
+const TAR_TIMEOUT_MS = 2 * 60 * 1000;
+
 // HC-019y (2026-05-29): removed `.github/agents` from refresh paths.
 // Agents live exclusively at `.claude/agents/` (Claude Code's read path)
 // after the install-time mirror was eliminated. `.github/agents/` is now
@@ -42,7 +45,7 @@ const ENTERPRISE_MANAGED_END_RE = /<!--\s*END ENTERPRISE-MANAGED\s*-->/;
 const FRONTMATTER_MANAGED_RE = /^---[\s\S]*?managed_by:\s*\S+[\s\S]*?---/m;
 
 /**
- * Default channel runner — invokes `hone <name>` via execSync.
+ * Default channel runner — invokes `hone <name>` via execFileSync (argv, no shell).
  * Tests inject a fake runner; real CLI uses this default.
  */
 function defaultRunChannel(name, repoRoot) {
@@ -53,7 +56,9 @@ function defaultRunChannel(name, repoRoot) {
     // down an ambient GIT_DIR — under a hook, `rebase -x`, or
     // `submodule foreach` — the child would resolve those against the OUTER
     // repo while we intended repoRoot. Sanitize at the boundary instead.
-    const out = execSync(`node "${cliPath}" ${name}`, {
+    // HC-GF-097-followup-2: argv, not a shell string — double quotes around a path do not
+    // stop `$(...)` or backticks, and a channel name is one argument, not a command line.
+    const out = execFileSync('node', [cliPath, name], {
       cwd: repoRoot,
       env: gitEnv(),
       encoding: 'utf8',
@@ -319,11 +324,14 @@ function createBackup({ repoRoot, backupDir, knowledgeFiles, now }) {
 
   if (relPaths.length === 0) return null;
 
-  // Use system tar for portability
+  // Use system tar for portability. HC-GF-097-followup-2: argv, not a shell string. These are
+  // the adopter repo's own file names, and a double-quoted `$(...)` in one runs as a command.
+  // Every relPath starts with a KNOWLEDGE_DIRS entry, so none can be read as a tar option.
   try {
-    execSync(`tar -czf "${backupPath}" ${relPaths.map(p => `"${p}"`).join(' ')}`, {
+    execFileSync('tar', ['-czf', backupPath, ...relPaths], {
       cwd: repoRoot,
       stdio: ['ignore', 'pipe', 'pipe'],
+      timeout: TAR_TIMEOUT_MS,
     });
   } catch (e) {
     throw new Error(`tar failed: ${e.message}`);
@@ -333,9 +341,10 @@ function createBackup({ repoRoot, backupDir, knowledgeFiles, now }) {
 }
 
 function restoreFromBackup({ repoRoot, backupPath }) {
-  execSync(`tar -xzf "${backupPath}"`, {
+  execFileSync('tar', ['-xzf', backupPath], {
     cwd: repoRoot,
     stdio: ['ignore', 'pipe', 'pipe'],
+    timeout: TAR_TIMEOUT_MS,
   });
 }
 

package/lib/repo-tree.js

@@ -88,6 +88,16 @@ function renderTree(paths, { maxEntries = DEFAULT_MAX_ENTRIES, maxBytes = DEFAUL
 
 const MAX_TRANSPORT_PATHS = 5000;
 const MAX_TRANSPORT_DIRS = 3000;
+// HC-GF-097: a BYTE bound on the two lists, because the count caps alone bound nothing a request
+// body limit can be derived from — 5000 paths can be any length. Sized so the count caps are what
+// normally decides: 8000 entries at 64 bytes each. This repo transports 2,452 paths + 227 dirs in
+// 116,634 bytes (~44 bytes an entry, measured 2026-09-24), well inside it; a 64 KB cap would have
+// dropped both lists here and switched off the server's `## Files` guard on every run. Over the
+// cap the lists are omitted exactly as over the count caps: the server reads v1 and skips the guard.
+const MAX_TRANSPORT_BYTES = (MAX_TRANSPORT_PATHS + MAX_TRANSPORT_DIRS) * 64;
+// The whole transported tree: both lists, the rendered `text`, and the scalar and detected-dir
+// fields (a few hundred bytes on a real repo; 16 KB leaves room for a pathological layout).
+const MAX_TREE_TRANSPORT_BYTES = MAX_TRANSPORT_BYTES + DEFAULT_MAX_BYTES + 16 * 1024;
 
 /**
  * HC-019n-followup-43: every tracked directory repo-wide (minus generated/dependency dirs),
@@ -111,7 +121,7 @@ function allDirs(allPaths) {
  * from v1 (prompt bytes stable). Both lists are capped; over the cap they are omitted and
  * the server treats the tree as v1 (guard skipped, never a false rejection).
  */
-function buildRepoTree(allPaths, { sourceDirs = [], testDirs = [], maxEntries, maxBytes } = {}) {
+function buildRepoTree(allPaths, { sourceDirs = [], testDirs = [], maxEntries, maxBytes, maxTransportBytes = Infinity } = {}) {
   const selected = selectPaths(allPaths, { sourceDirs, testDirs });
   const r = renderTree(selected, { maxEntries, maxBytes });
   const dirs = allDirs(allPaths);
@@ -130,7 +140,13 @@ function buildRepoTree(allPaths, { sourceDirs = [], testDirs = [], maxEntries, m
     shown: r.shown,
     text: r.text,
   };
-  if (selected.length <= MAX_TRANSPORT_PATHS && dirs.length <= MAX_TRANSPORT_DIRS) {
+  // The BYTE cap applies only when the caller passes one: `hone queue-stories`, whose request
+  // limit is derived from it. `hone run-story` sends one story and keeps the count caps alone, as
+  // before HC-GF-097 — review of #1100 found a 4,900-path repository (under both count caps) that
+  // the byte cap would have stripped of its lists, switching off the `## Files` guard on single runs.
+  if (selected.length <= MAX_TRANSPORT_PATHS && dirs.length <= MAX_TRANSPORT_DIRS
+      && (maxTransportBytes === Infinity
+        || Buffer.byteLength(JSON.stringify({ paths: selected, dirs }), 'utf8') <= maxTransportBytes)) {
     tree.paths = selected; tree.dirs = dirs;
   }
   try {
@@ -145,4 +161,7 @@ function buildRepoTree(allPaths, { sourceDirs = [], testDirs = [], maxEntries, m
   return tree;
 }
 
-module.exports = { selectPaths, renderTree, buildRepoTree, allDirs, DEFAULT_MAX_ENTRIES, DEFAULT_MAX_BYTES, MAX_TRANSPORT_PATHS, MAX_TRANSPORT_DIRS };
+module.exports = {
+  selectPaths, renderTree, buildRepoTree, allDirs, DEFAULT_MAX_ENTRIES, DEFAULT_MAX_BYTES,
+  MAX_TRANSPORT_PATHS, MAX_TRANSPORT_DIRS, MAX_TRANSPORT_BYTES, MAX_TREE_TRANSPORT_BYTES,
+};