@hone-ai/cli 1.34.0 → 1.35.1

package/lib/story-classifier.js

@@ -53,6 +53,12 @@ const ARCHITECT_AXES = Object.freeze({
   // story with single-module surface + one obvious design engaged NO axis —
   // exactly where an independent architect caught a money leak.
   SHARED_CHOKEPOINT:       'shared-chokepoint',
+  // HC-GF-173: the story's acceptance cannot be verified without stored state — a table, cache,
+  // queue or counter. This is the trigger for the sandbox capability (HC-GF-168/169), which merged
+  // with nothing invoking it. Deliberately NOT engaged where real inputs already exist: a diff and
+  // a file are real data, and seeding there tests the fixture author's imagination.
+  // Additive-only, exactly as SHARED_CHOKEPOINT was: absent or false is today's behaviour.
+  STATEFUL:                'stateful',
 });
 
 // Estimate ordering for threshold comparisons
@@ -107,9 +113,65 @@ function shouldEngageArchitect(input) {
   if (input.touches_shared_chokepoint === true) {
     axes.push(ARCHITECT_AXES.SHARED_CHOKEPOINT);
   }
+  // Stored state → architect for fixture + isolation review (HC-GF-173). Strict `true` so a
+  // truthy string cannot enrol a story by accident.
+  if (input.requires_stored_state === true) {
+    axes.push(ARCHITECT_AXES.STATEFUL);
+  }
   return { engage: axes.length > 0, axes };
 }
 
+/**
+ * HC-GF-173: a story classified stateful with no declared sandbox must SAY SO.
+ *
+ * Silent skipping is how `pipeline-integrity` became 195 learnings pointed at nothing — the
+ * capability existed, nothing invoked it, and no output said so. Returns null when there is
+ * nothing to report, because a warning printed on every story is one nobody reads.
+ *
+ * @param {{axes?: string[], sandbox?: object|null}} input
+ * @returns {string|null}
+ */
+function describeSandboxReadiness({ axes = [], sandbox = null } = {}) {
+  if (!Array.isArray(axes) || !axes.includes(ARCHITECT_AXES.STATEFUL)) return null;
+  if (sandbox && typeof sandbox === 'object') return null;
+  return 'this story is classified `stateful` — its acceptance needs stored state — but no '
+    + '`sandbox:` block is declared in `.pipeline-config.yml`. The pipeline cannot seed a scratch '
+    + 'datastore for it, so any test it writes will assert against whatever the environment '
+    + 'happens to hold. Declare `sandbox:` (create/migrate/reset plus a `verify` block) or '
+    + 'reclassify the story.';
+}
+
+
+/**
+ * A one-shot readiness reporter — HC-GF-189.
+ *
+ * The follow loop re-observes the same run state every few seconds, so the note has to fire once;
+ * and "once" is behaviour, not text. An earlier version of this lived inline in the poll loop with
+ * a source-grep test, and mutation walked straight through it: `if (false) { console.warn(…) }` and
+ * `if (true) {` both kept every asserted identifier in the file. A closure with a returned decision
+ * can be driven directly instead.
+ *
+ * @param {{readSandbox: () => object|null}} deps  reads the adopter's declaration; injected so the
+ *   decision is testable without a repo on disk
+ * @returns {(config: object|null) => string|null} the note the FIRST time there is one, null after
+ */
+function makeReadinessReporter({ readSandbox }) {
+  let reported = false;
+  return (config) => {
+    if (reported) return null;
+    let note = null;
+    try {
+      note = describeSandboxReadiness({
+        axes: (config && config.classifier_axes) || [],
+        sandbox: readSandbox(),
+      });
+    } catch { return null; } // reporting must never break a run
+    if (!note) return null;
+    reported = true;
+    return note;
+  };
+}
+
 // ─── Pass 2: Track determination (priority order) ───
 
 function determineTrack(input, thresholds) {
@@ -281,6 +343,8 @@ function classifyStory(input, thresholds) {
 }
 
 module.exports = {
+  describeSandboxReadiness,
+  makeReadinessReporter,
   classifyStory,
   shouldEngageArchitect,
   determineTrack,

package/lib/story-compose.js

@@ -0,0 +1,69 @@
+'use strict';
+/**
+ * HC-GF-232 — fold the sibling rows the server resolved into the story text step_0 sees.
+ *
+ * `GET /stories/:id/context` returns `{ description, referencedPaths, referencedStories }`.
+ * The CLI took `description` and dropped the rest, so `referencedStories` appeared 6 times in
+ * the server and 0 times in the entire CLI — HC-GF-215's server half could satisfy its
+ * AC-1..AC-6 and never its AC-7, which is the criterion that story exists to prove.
+ *
+ * WHY THIS FOLDS INTO `story_description` RATHER THAN A NEW CONFIG FIELD. The orchestrator
+ * renders `run.config.story_description` as `# Story Description`, and `computeContextHash`
+ * hashes that same string. A separate field would leave the hash unchanged, so the second run
+ * of the A/B would replay the first's cached step_0 artifact and the experiment could not be
+ * run at all. HC-GF-231 put the code bundle into that hash for the same reason.
+ *
+ * WHAT THIS MUST NOT REACH. `issueBodyForFiles`, which drives path extraction. The server's own
+ * contract states `referencedStories` carries PROSE ONLY and a sibling's `referencedPaths` are
+ * deliberately not bundled. Composing into the path-extraction input would bundle files the
+ * story never named — HC-GF-229's defect arriving by a different road.
+ *
+ * Pure, synchronous, no I/O.
+ */
+
+/**
+ * The section marker. Exported so the test pins the same literal the composer writes, and so a
+ * future reader can scope anything that must see only the primary story — `renamedContracts`
+ * (`server/src/services/story-conformance.js`) derives its identifier set from this text, and
+ * sibling prose widens that set in both directions.
+ */
+const RELATED_HEADING = '## Related stories (resolved from [[links]] in this row)';
+
+/**
+ * Append the resolved siblings to a story description.
+ *
+ * Returns the description UNCHANGED when there is nothing to add. That is not a micro-
+ * optimisation: it is the acceptance's second half. Appending an empty section to every
+ * unlinked story would change its hash, invalidate its grooming cache, and re-bill step_0
+ * across the whole backlog for no gain.
+ *
+ * Fails open on a malformed entry, matching the server, which uses `continue` plus a
+ * diagnostic on every sibling failure path and never throws: a story whose sibling is
+ * unresolvable still runs, it just runs with less. An entry needs BOTH an id and prose to be
+ * useful — prose with no id cannot be cited by the agent, and an id with no prose adds a name
+ * and no information — so anything else is skipped rather than half-rendered.
+ *
+ * @param {string} description  the primary story row's text
+ * @param {Array<{storyId: string, description: string}>} [referencedStories]
+ * @returns {string}
+ */
+function composeStoryDescription(description, referencedStories) {
+  const primary = typeof description === 'string' ? description : '';
+  if (!Array.isArray(referencedStories) || referencedStories.length === 0) return primary;
+
+  const parts = [];
+  for (const s of referencedStories) {
+    if (!s || typeof s !== 'object') continue;
+    const id = typeof s.storyId === 'string' ? s.storyId.trim() : '';
+    const prose = typeof s.description === 'string' ? s.description.trim() : '';
+    if (!id || !prose) continue;
+    parts.push(`### ${id}\n\n${prose}`);
+  }
+  if (parts.length === 0) return primary;
+
+  // Order is the server's resolution order, preserved deliberately: the composed string is
+  // hashed, so re-ordering identical inputs would invalidate a cache entry at random.
+  return `${primary}\n\n${RELATED_HEADING}\n\n${parts.join('\n\n')}`;
+}
+
+module.exports = { composeStoryDescription, RELATED_HEADING };

package/lib/story-line.js

@@ -0,0 +1,40 @@
+'use strict';
+/**
+ * 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.
+ *
+ * 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
+ * pin takes: it freezes the regex's SPELLING, so an equivalent rewrite fails the test while a
+ * behavioural change that keeps the spelling passes. What the parser must do is describable
+ * directly, so it is asserted directly.
+ */
+
+/** A line that is neither blank nor a comment. */
+function isStoryLine(line) {
+  const t = String(line).trim();
+  return Boolean(t) && !t.startsWith('#');
+}
+
+/**
+ * @param {string} line
+ * @returns {{storyId: string, dependsOn?: 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.
+ */
+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) };
+  }
+  if (/\s/.test(t)) {
+    return { error: `Malformed line in --file: "${t}"` };
+  }
+  return { storyId: t };
+}
+
+module.exports = { parseStoryLine, isStoryLine };

package/lib/story-provenance.js

@@ -0,0 +1,267 @@
+'use strict';
+/**
+ * story-provenance.js — HC-GF-270: is the text this run was built from something Hone
+ * may EXECUTE unattended?
+ *
+ * WHY THIS EXISTS. `hone run-story <issue-number>` takes story text from a GitHub issue
+ * (cli/hone-cli.js, the `fetched GitHub issue #` site), the pipeline turns that text into a
+ * patch, and auto-verify (HC-GF-064) then RUNS that patch — the provisioning install first
+ * (cli/lib/worktree-provision.js) — as the operator, with `$HOME` and the network, the
+ * moment the run pauses. HC-GF-269 removed Hone's own credentials from the child's
+ * environment; it did not remove `~/.aws`, `~/.ssh`, `~/.npmrc` or the network from its
+ * REACH, because the child still runs as the operator. That is the fork-PR problem on a
+ * path GitHub's fork-PR secret withholding never sees, because no PR exists yet.
+ *
+ * TRUST IS DERIVED IN EXACTLY ONE PLACE — here. The callers (the poll-loop decider,
+ * verify-patch, emit-pr) record and pass RAW FACTS and never re-derive the decision, so a
+ * change to the trusted set is one edit and one mutation, not four
+ * (HC-GF-070/074/106: route every site of a decision through one function).
+ *
+ * PURE. No filesystem, no network, no process. Never throws: a malformed `source` resolves
+ * to untrusted, mirroring auto-verify.js's "a malformed config must not break the run".
+ *
+ * Design: .github/pipeline/HC-GF-270/architect.md §1 and §3.
+ */
+
+/**
+ * The `author_association` values trusted to auto-verify: the repository's owner, members of its
+ * organization, and its collaborators. NOT the same as "has write access" — MEMBER includes org
+ * members whose base role is none or read, and COLLABORATOR includes outside collaborators with
+ * read or triage (security review MEDIUM-1; a write-permission check is HC-GF-282). Everything
+ * outside the set is untrusted, INCLUDING values GitHub adds later:
+ * `CONTRIBUTOR` (merged a PR once, which is not write access), `FIRST_TIME_CONTRIBUTOR`,
+ * `FIRST_TIMER`, `MANNEQUIN`, `NONE`, and deleted users (`ghost`, reported as `NONE`).
+ */
+const TRUSTED_ASSOCIATIONS = new Set(['OWNER', 'MEMBER', 'COLLABORATOR']);
+
+/** Story text the operator typed or pointed at. Not someone else's words. */
+const OPERATOR_AUTHORED_KINDS = new Set(['file', 'description']);
+
+const ISSUE_ID_RE = /^\d+$/;
+/** A hostname, not an SSH alias: at least one dot, and no path/user/port parts. */
+const DOTTED_DOMAIN_RE = /^[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?(?:\.[A-Za-z0-9-]+)+$/;
+
+/**
+ * An all-digits story id is the ONLY id shape that could have reached the issue fetch.
+ * This is the whole legacy rule: runs created before HC-GF-270 carry no `story_source`,
+ * and this is the only evidence left about where their text came from.
+ */
+function isIssueShapedId(storyId) {
+  return ISSUE_ID_RE.test(String(storyId == null ? '' : storyId).trim());
+}
+
+/**
+ * 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.
+ */
+function isDottedDomain(host) {
+  const h = String(host == null ? '' : host).trim();
+  return h !== '' && DOTTED_DOMAIN_RE.test(h);
+}
+
+/**
+ * The host of a git remote URL, or null when there isn't one (a local path).
+ * Handles `git@host:owner/repo.git`, `ssh://git@host/owner/repo`, `https://host/owner/repo`.
+ */
+function remoteHostFromUrl(remoteUrl) {
+  const host = rawRemoteHost(remoteUrl);
+  // GitHub's documented SSH-over-HTTPS endpoint (`ssh://git@ssh.github.com:443/…`) serves
+  // github.com's repositories. Compared as-is it would refuse every collaborator's issue for an
+  // operator behind a firewall that blocks port 22 (security review LOW-3).
+  return host === 'ssh.github.com' ? 'github.com' : host;
+}
+
+function rawRemoteHost(remoteUrl) {
+  const s = String(remoteUrl == null ? '' : remoteUrl).trim();
+  if (!s) return null;
+  const scp = s.match(/^[^/@\s]+@([^/:\s]+):/);
+  if (scp) return scp[1].toLowerCase();
+  try {
+    const u = new URL(s);
+    if (u.hostname) return u.hostname.toLowerCase();
+  } catch { /* not a URL — fall through */ }
+  const bare = s.match(/^([A-Za-z0-9][A-Za-z0-9._-]*):/);
+  return bare ? bare[1].toLowerCase() : null;
+}
+
+function parseUrl(u) {
+  try { return new URL(String(u)); } catch { return null; }
+}
+
+/** A value named in a reason string, without ever throwing on it. */
+function describe(v) {
+  if (v === undefined) return 'undefined';
+  if (v === null) return 'null';
+  if (typeof v === 'string') return JSON.stringify(v);
+  if (typeof v === 'object') { try { return JSON.stringify(v); } catch { return String(v); } }
+  return String(v);
+}
+
+/**
+ * `owner/repo#number` when we have it, so every reason names WHICH issue.
+ *
+ * HC-GF-270 code review (LOW-6): `ref` is now ALWAYS `{owner, repo, number}` or null, for
+ * every kind — the unified-return-shape rule. A human-readable name for a non-issue source
+ * (`story.md`, `--description`, `HC-GF-270`) travels in its own `label` field, so no reader
+ * has to branch on `typeof source.ref` and a sixth kind cannot get that branch wrong.
+ */
+function refLabel(source) {
+  const r = source && source.ref;
+  if (r && typeof r === 'object' && !Array.isArray(r) && r.owner && r.repo && r.number != null) {
+    return `${r.owner}/${r.repo}#${r.number}`;
+  }
+  const label = source && source.label;
+  if (typeof label === 'string' && label.trim() !== '') return label.trim();
+  return '(unidentified issue)';
+}
+
+/** The operator-facing name of a source, for kinds that have no owner/repo/number. */
+function sourceLabel(source, fallback) {
+  const label = source && source.label;
+  if (typeof label === 'string' && label.trim() !== '') return label.trim();
+  return fallback;
+}
+
+/** The ONLY `html_url` path this run's issue may have. Transfers and redirects change it. */
+function expectedIssuePath(ref) {
+  if (!ref || typeof ref !== 'object' || Array.isArray(ref)) return null;
+  const { owner, repo, number } = ref;
+  if (!owner || !repo || number == null || String(number).trim() === '') return null;
+  // `run-story 007` is issue 7: GitHub's html_url carries no leading zeros (security review LOW-3).
+  const n = String(number).trim();
+  const num = /^\d+$/.test(n) ? String(Number(n)) : n;
+  return `/${String(owner).toLowerCase()}/${String(repo).toLowerCase()}/issues/${num}`;
+}
+
+/**
+ * @param {object|null|undefined} source  config.story_source, as recorded at fetch time
+ * @param {string|number|null|undefined} storyId  the run's story id (the legacy rule's input)
+ * @returns {{ trusted: boolean, label: string, reason: string }}
+ *   `reason` is ALWAYS populated, including when trusted, because the callers print it: an
+ *   operator told only "this run will not auto-verify" cannot tell a real refusal from a bug.
+ */
+function assessStorySource(source, storyId) {
+  const yes = (label, reason) => ({ trusted: true, label, reason });
+  const no = (label, reason) => ({ trusted: false, label, reason });
+  const id = String(storyId == null ? '' : storyId).trim() || '(unknown)';
+  // HC-GF-270 (security review BLOCKER-1): the two id-shape rules below read "not all digits" as
+  // "never reached the issue fetch". A MISSING id is not evidence of that — it is what a caller
+  // sees when the run fetch answered with something other than this run — so it is untrusted.
+  const idMissing = String(storyId == null ? '' : storyId).trim() === '';
+
+  // No `story_source` at all: a run created before this change, or a config that could not
+  // be read. Fails closed exactly where an issue could have been involved, and never pauses
+  // a roadmap run (architect memo §3).
+  if (!source || typeof source !== 'object' || Array.isArray(source)) {
+    if (idMissing) {
+      return no('legacy', 'this run recorded no story_source and no story id — nothing says where its text came from');
+    }
+    return isIssueShapedId(storyId)
+      ? no('legacy', `this run recorded no story_source and its story id '${id}' is all digits — `
+          + 'an issue number is the only id shape that could have reached the issue fetch, so its text may not be yours')
+      : yes('legacy', `this run recorded no story_source, and its story id '${id}' is not an issue number, `
+          + 'so it never reached the issue fetch');
+  }
+
+  // Any error recorded while establishing provenance is untrusted, and the reason carries the
+  // original text: "a gh failure pauses rather than proceeds" is only actionable if the
+  // operator can see WHICH failure (a missing token and a rate limit want different moves).
+  if (source.error !== undefined && source.error !== null && String(source.error).trim() !== '') {
+    return no('error', 'story provenance could not be established: '
+      + String(source.error).split('\n')[0].slice(0, 200));
+  }
+
+  const kind = typeof source.kind === 'string' ? source.kind : '';
+
+  if (OPERATOR_AUTHORED_KINDS.has(kind)) {
+    const where = kind === 'file'
+      ? `--story-file ${sourceLabel(source, '(unnamed file)')}`
+      : '--description';
+    return yes(kind, `the story text came from ${where} — you wrote it`);
+  }
+  if (kind === 'roadmap') {
+    return yes('roadmap', `the story text for ${sourceLabel(source, id)} came from the roadmap `
+      + '— committed repository content');
+  }
+
+  // Written by queue-stories before HC-GF-097. Since then queue-stories resolves each story's text
+  // through cli/lib/run-context.js and records its real source (roadmap, issue, ...), so this kind
+  // appears only on runs queued earlier, and is kept for them.
+  // Binding decision 1 (operator, step_1 gate of run fa6e00c4): queue-stories sends IDS and
+  // never fetches issue text, so only an all-digits id could have become issue text
+  // downstream. Any other id stays trusted — an overnight batch of roadmap ids must keep
+  // auto-verify, which is the entire point of running it overnight.
+  if (kind === 'id-only') {
+    const sent = sourceLabel(source, id);
+    if (idMissing) {
+      return no('id-only', 'queue-stories stamped this run but its story id is missing — nothing says which id was sent');
+    }
+    return isIssueShapedId(storyId)
+      ? no('id-only', `queue-stories sent the id '${sent}' and it is all digits, so this run may have fetched issue text`)
+      : yes('id-only', `queue-stories sent the id '${sent}', which is not an issue number — no issue text was fetched`);
+  }
+
+  if (kind === 'issue') {
+    const assoc = source.association;
+    // Schema drift is untrusted, not trusted-by-accident: if GitHub renames or drops this
+    // field, a gate that reads `undefined` as "not in the untrusted list" opens silently.
+    if (typeof assoc !== 'string' || assoc.trim() === '') {
+      return no('issue', `issue ${refLabel(source)} reports no usable author_association `
+        + `(${describe(assoc)}) — failing closed`);
+    }
+    const a = assoc.trim().toUpperCase();
+    if (!TRUSTED_ASSOCIATIONS.has(a)) {
+      return no('issue', `issue ${refLabel(source)} was authored by ${source.author || 'an unknown user'}, `
+        + `whose author_association is ${a} — not one of ${[...TRUSTED_ASSOCIATIONS].join(', ')}`);
+    }
+
+    // The path check runs in EVERY case, host alias or not: a transferred issue redirects,
+    // and a redirect is how a trusted association from one repository gets attached to text
+    // in another.
+    const url = parseUrl(source.html_url);
+    if (!url) {
+      return no('issue', `issue ${refLabel(source)} has no parsable html_url (${describe(source.html_url)}) — failing closed`);
+    }
+    const want = expectedIssuePath(source.ref);
+    if (!want) {
+      return no('issue', `story_source.ref does not name an owner, repo and number (${describe(source.ref)}) — `
+        + 'the html_url could not be checked, so this run is not trusted');
+    }
+    if (url.pathname.toLowerCase().replace(/\/+$/, '') !== want) {
+      return no('issue', `html_url ${source.html_url} is not ${want} — the issue may have been transferred, `
+        + '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');
+      }
+    }
+
+    return yes('issue', `issue ${refLabel(source)} was authored by ${source.author || 'an unknown user'} `
+      + `with author_association ${a}`);
+  }
+
+  // An unrecognised kind is a newer writer, a typo, or a hand-edited config. None of those
+  // is evidence of trust.
+  return no('unknown', `story_source.kind ${describe(source.kind)} is not a kind this version recognises — failing closed`);
+}
+
+module.exports = {
+  assessStorySource,
+  remoteHostFromUrl,
+  isIssueShapedId,
+  isDottedDomain,
+  refLabel,
+  sourceLabel,
+  TRUSTED_ASSOCIATIONS,
+  OPERATOR_AUTHORED_KINDS,
+};

package/lib/timeout-option.js

@@ -0,0 +1,42 @@
+'use strict';
+/**
+ * timeout-option.js — HC-GF-200. One refusal for every `--timeout` flag.
+ *
+ * `Number('abc')` is NaN and `Number('  ')` is 0, so a mistyped flag reaches a
+ * child_process call as NaN or as an instant kill. Node itself refuses the NaN
+ * with `RangeError [ERR_OUT_OF_RANGE]: ... It must be an integer. Received NaN`,
+ * which is safe — it throws rather than running unbounded — but it names node's
+ * internals instead of the flag the operator mistyped, and the zero case is not
+ * refused at all.
+ *
+ * Note for anyone carrying the older claim forward: this is NOT the
+ * `setTimeout(NaN)` hazard. `setTimeout(NaN)` fires on the next tick; a
+ * child_process `timeout` option throws. HC-GF-198's row said verify-patch
+ * shared the 1ms behaviour and could therefore produce a wrong merge verdict —
+ * measured 2026-09-19, it does not, and HC-GF-200 corrects that record.
+ */
+
+/**
+ * @param {string|number} raw   what the operator typed
+ * @param {string} flag         the flag name, for the message ('--timeout')
+ * @returns {number} seconds
+ * @throws {Error} naming the flag and echoing the value
+ */
+function parseTimeoutSeconds(raw, flag = '--timeout') {
+  // A blank string needs NO special case: Number('') and Number('  ') are both 0,
+  // and the `<= 0` below already refuses it. A first draft added an explicit
+  // trim guard for that input; mutation showed deleting it changed nothing,
+  // because it could not. A guard that cannot alter an outcome reads as
+  // protection and is only maintenance — HC-CI-030 records eight in this repo.
+  // The BEHAVIOUR is still pinned: the suite asserts a blank value is refused,
+  // which is the property, independent of which branch does the refusing.
+  const seconds = Number(raw);
+  if (!Number.isFinite(seconds) || seconds <= 0) {
+    throw new Error(
+      `${flag} must be a positive number of seconds (got ${JSON.stringify(raw)})`,
+    );
+  }
+  return seconds;
+}
+
+module.exports = { parseTimeoutSeconds };

package/lib/untrusted-code-env.js

@@ -0,0 +1,51 @@
+'use strict';
+/**
+ * untrusted-code-env.js — HC-GF-269. The environment for code Hone did not write.
+ *
+ * verify-patch, emit-pr and verify-pr run a shell command in a tree that holds step_4's patch — an
+ * LLM's output, and its tests — and auto-verify (HC-GF-064) runs it the moment a run pauses, before
+ * anyone has read it. The worktree isolates the FILES. The environment was the operator's whole
+ * shell. Measured on local run 7a4b09b2 (2026-09-24): `tests/e2e/dashboard.smoke.test.js:27` read
+ * `process.env.HONE_TOKEN` inside `hone verify-patch`, received the operator's local dogfood token and
+ * sent it to production — the target `ci.e2e` pins — which answered 401. Story text can come from a
+ * GitHub issue, so whoever can file one can try to steer the builder into a test that sends it
+ * somewhere else.
+ *
+ * The rule: Hone's own namespace never reaches code Hone did not write. Every `HONE_*` variable goes,
+ * by PREFIX rather than by list — the CLI reads six credential or endpoint variables today, and a
+ * list is out of date the day a seventh is added. The adopter's own variables all stay: database
+ * URLs, cloud profiles, proxies, toolchain. The cost is Hone's own SETTINGS an adopter's CI may read
+ * (`HONE_SOURCE_DIRS`, docs/sdlc/setup.md): exported in the operator's shell they no longer reach the
+ * command, so set them in the command itself — `ci.local_command` or `--command`.
+ *
+ * Sibling to `git-env.js` (variables that select a REPOSITORY) and `verdict-env.js` (variables that
+ * invert a RESULT), and separate for the same reason they are: this scrub withholds CREDENTIALS, and
+ * unlike those two it also applies to installs — a patched package.json's `postinstall` is code the
+ * builder wrote too.
+ *
+ * NOT A SANDBOX. The child still runs as the operator, with $HOME and the network: `~/.honerc` holds
+ * the same token and any test can read it. This closes the leak that was measured — a credential
+ * handed to generated code in its environment — not a patch written to steal one. HC-GF-270 keeps an
+ * outside party's patch from running unattended at all (cli/lib/story-provenance.js); OS isolation of
+ * the child remains a separate opt-in.
+ */
+
+/** Hone's namespace: the CLI's and the server's variables, credentials among them. */
+const HONE_PREFIX = 'HONE_';
+
+/** Case-folded: Windows resolves `process.env.HONE_TOKEN` against a key spelled `Hone_Token`. */
+function isHoneVar(key) {
+  return String(key).toUpperCase().startsWith(HONE_PREFIX);
+}
+
+/**
+ * @param {NodeJS.ProcessEnv} [base] Base env; defaults to process.env. Injectable for tests.
+ * @returns {NodeJS.ProcessEnv} a copy — the caller's environment is untouched
+ */
+function withoutHoneVars(base) {
+  const env = { ...(base || process.env) };
+  for (const key of Object.keys(env)) if (isHoneVar(key)) delete env[key];
+  return env;
+}
+
+module.exports = { withoutHoneVars, isHoneVar, HONE_PREFIX };

package/lib/verdict-env.js

@@ -0,0 +1,31 @@
+'use strict';
+/**
+ * verdict-env.js — HC-GF-144. The environment for a subprocess whose VERDICT we read.
+ *
+ * `node --test` exports NODE_TEST_CONTEXT and NODE_TEST_WORKER_ID to every process it spawns, and
+ * a nested `node --test` that inherits them exits 0 EVEN WHEN TESTS FAIL (measured: exit 1 with a
+ * clean env, exit 0 with the variable). Anything whose exit code is believed must run without them.
+ *
+ * Sibling to `git-env.js`, and deliberately separate: that one removes the variables that select a
+ * REPOSITORY, this one removes the variables that invert a RESULT. Merging them would apply each
+ * scrub where it is not wanted.
+ *
+ * NOT for subprocesses that exist to USE the operator's toolchain — pip, npm and playwright
+ * installs need the real environment (proxy, registry, an active virtualenv), and scrubbing it
+ * there is the bug rather than the fix.
+ */
+
+/** Variables a parent test runner exports that flip a child runner's exit code. */
+const VERDICT_FLIPPING_VARS = ['NODE_TEST_CONTEXT', 'NODE_TEST_WORKER_ID'];
+
+/**
+ * @param {NodeJS.ProcessEnv} [base] Base env; defaults to process.env. Injectable for tests.
+ * @returns {NodeJS.ProcessEnv}
+ */
+function verdictEnv(base) {
+  const env = { ...(base || process.env) };
+  for (const key of VERDICT_FLIPPING_VARS) delete env[key];
+  return env;
+}
+
+module.exports = { verdictEnv, VERDICT_FLIPPING_VARS };