@hone-ai/cli 1.35.0 → 1.36.0

package/hone-cli.js

@@ -39,6 +39,7 @@ const { parseReviewJSON } = require('./lib/parse-review-json');
 const { resolveBaseRef, getMaxDiffChars } = require('./lib/release-review-config');
 const { gitEnv } = require('./lib/git-env');
 const { collectIncludePaths } = require('./lib/include-paths');
+const { runArgsError, orchestratePath } = require('./lib/run-target'); // HC-GF-270-followup-1
 const program = new Command();
 
 // ── Config resolution ─────────────────────────────────────────────────────────
@@ -68,6 +69,31 @@ function requireAdminKey() {
   return adminKey;
 }
 
+/**
+ * HC-GF-270-followup-1: refuse a caller-supplied run id, batch id, step key or attempt that is not one,
+ * with exit 2. Called as the FIRST statement of a verb's action, before getConfig() or api(), so a
+ * refusal makes no request, reads no ~/.honerc, and runs no probe, gh call or CI command.
+ */
+function refuseBadRunArgs(checks) {
+  const msg = runArgsError(checks);
+  if (msg) {
+    console.error(msg);
+    process.exit(2);
+  }
+}
+
+/**
+ * The arguments check-patch, verify-patch and emit-pr turn into a step-output URL. HC-GF-270 (second
+ * review MEDIUM-1): the step key goes into a URL and a file name, and URL resolution collapses `..` —
+ * `--step-key ../../<other run>/step/step_4` fetched ANOTHER run's patch while THIS run's config was
+ * assessed. A step key is a step key, a run id is a run id, and an attempt is a whole number.
+ */
+const stepFetchChecks = (workflowId, opts) => [
+  { label: '<workflowId>', kind: 'runId', value: workflowId },
+  { label: '--step-key', kind: 'stepKey', value: opts.stepKey },
+  { label: '--attempt', kind: 'attempt', value: opts.attempt, optional: true },
+];
+
 function getConfig() {
   // Priority: env var → ~/.honerc → error
   const rc     = readRc();
@@ -188,6 +214,8 @@ program
   .option('--workflow-id <id>', 'The run id to report the verdict against (for --report)')
   .option('--timeout <s>', 'Seconds to allow each probe (default 5 — raise it for packs that need a real generation)', '5')
   .action(async (opts) => {
+    // HC-GF-270-followup-1: a --workflow-id is checked before any probe spends provider quota.
+    refuseBadRunArgs([{ label: '--workflow-id', kind: 'runId', value: opts.workflowId, optional: true }]);
     const { readAgentEvalConfig } = require('./lib/pipeline-config');
     const { runAgent } = require('./lib/agent-executor');
     const { runCheck } = require('./lib/eval-graders');
@@ -343,13 +371,13 @@ program
       } else {
         try {
           const client = api(getConfig());
-          await client.post(`/orchestrate/${opts.workflowId}/verdict`, {
+          await client.post(orchestratePath([opts.workflowId, 'verdict']), {
             source: 'agent-eval',
             stepKey: 'step_4',
             verdict: anyFailed ? 'fail' : 'pass',
             exitCode: anyFailed ? 1 : 0,
             detail: `agent-eval ${opts.category}: ${results.filter((r) => r.passed).length}/${results.length} probes passed`,
-          });
+          }, require('./lib/fresh-connection').freshConnection());
           if (opts.output !== 'json') console.log(`  → reported agent-eval verdict '${anyFailed ? 'fail' : 'pass'}' to run ${opts.workflowId} (advisory)`);
         } catch (e) {
           if (opts.output !== 'json') console.warn(`  ⚠ verdict report failed (non-fatal): ${e.response?.data?.error || e.message}`);
@@ -900,6 +928,9 @@ program
     if (ciGateChoice.source !== 'auto-detect') {
       setupEnv.CI_GATE = ciGateChoice.mode;
     }
+    // HC-GF-321: --stack was declared and never read. The script applies it
+    // after detection (apply_stack_override) and refuses an unsupported value.
+    if (opts.stack) setupEnv.HONE_STACK_OVERRIDE = String(opts.stack).toLowerCase();
     try {
       execSync(`bash "${scriptPath}" ${flags}`, {
         stdio: 'inherit',
@@ -911,6 +942,25 @@ program
       process.exit(1);
     }
 
+    // HC-GF-320: every phase below writes (CLAUDE.md, config grounding, test
+    // packages, GitHub branch protection). A dry run stops here and says what
+    // they would do.
+    if (opts.dryRun) {
+      const { postScriptDryRunPlan } = require('./lib/setup-dry-run');
+      const plan = postScriptDryRunPlan({
+        claudeMdTemplate: fs.existsSync(path.join(tmpDir, 'CLAUDE.md')),
+        claudeMdExists: fs.existsSync(path.join(process.cwd(), 'CLAUDE.md')),
+        configExists: fs.existsSync(path.join(process.cwd(), '.github', '.pipeline-config.yml')),
+        installTests: !!opts.installTests,
+        skipBranchProtection: opts.branchProtection === false ||
+          /^(1|true|yes)$/i.test(process.env.HONE_SKIP_BRANCH_PROTECTION || ''),
+      });
+      for (const line of plan) console.log(`  DRY-RUN: ${line}`);
+      console.log('  Dry run complete: nothing was written.');
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+      return;
+    }
+
     // HC-RC-004: if the adopter chose `local`, run the setup-local-ci
     // scaffold inline so they end the setup command with a working
     // local-CI stack (Makefile + compose) instead of having to know
@@ -1536,6 +1586,10 @@ async function createTestEnv(repoRoot, opts) {
 function recommendTestFramework(repoRoot) {
   const detected = detectExistingTestFramework(repoRoot);
   if (detected.testFw) return; // Already has tests — no recommendation needed
+  // HC-GF-321: every recommendation below is an npm package. Without a root
+  // package.json the stack is not Node (or lives in subdirectories), and a
+  // pytest repository was told to install vitest.
+  if (detected.stack === 'unknown') return;
 
   const pkgs = getInstallPackages(detected.stack);
   const installCmd = detected.pkgMgr === 'yarn' ? 'yarn add -D' : detected.pkgMgr === 'pnpm' ? 'pnpm add -D' : 'npm install -D';
@@ -3060,23 +3114,25 @@ program
         console.log('No .github/learnings/ directory found — nothing to retract.');
         return;
       }
-      const yaml = require('js-yaml');
+      // HC-GF-311-followup-1: per learning, in every schema `hone promote` reads — not just the file's top level.
+      const { parseRetracted } = require('./lib/learnings-parse');
       const files = fs.readdirSync(learningsDir).filter(f => f.endsWith('.yml'));
       for (const file of files) {
-        try {
-          const parsed = yaml.load(fs.readFileSync(path.join(learningsDir, file), 'utf8'));
-          const entries = Array.isArray(parsed) ? parsed : [parsed];
-          for (const entry of entries) {
-            if (entry?.status === 'retracted' && entry.id) {
-              payload.push({
-                id: entry.id,
-                repo_name: repoName,
-                reason: entry.retraction_reason || 'Retracted (no reason provided in YAML)',
-              });
-            }
-          }
-        } catch (e) {
-          console.warn(`  ⚠ ${file}: parse error — ${e.message}`);
+        // One unreadable entry (a directory or a dangling link named *.yml) must not hide the rest.
+        let content;
+        try { content = fs.readFileSync(path.join(learningsDir, file), 'utf8'); }
+        catch (e) { console.warn(`  ⚠ ${file}: read error — ${e.message}`); continue; }
+        const { retracted, parseError } = parseRetracted(content);
+        if (parseError) {
+          console.warn(`  ⚠ ${file}: parse error — ${parseError.message}`);
+          continue;
+        }
+        for (const { id, reason } of retracted) {
+          payload.push({
+            id,
+            repo_name: repoName,
+            reason: reason || 'Retracted (no reason provided in YAML)',
+          });
         }
       }
       if (payload.length === 0) {
@@ -4955,10 +5011,19 @@ program
     }
     // Path B: GitHub issue fetch via gh
     else if (issueId) {
+      // HC-GF-270-followup-1: an issue number or an issue URL, which are the forms gh accepts, and
+      // nothing else. gh reads an argument that begins with `-` as a flag even without a shell.
+      if (!/^[1-9]\d*$/.test(issueId) && !/^https:\/\/[^/\s]+\/[^/\s]+\/[^/\s]+\/issues\/[1-9]\d*$/.test(issueId)) {
+        console.error(`error: <issueId> must be an issue number like 142, or an issue URL (got ${JSON.stringify(issueId)})`);
+        console.error('usage: hone classify-story 142');
+        console.error('       hone classify-story --input-file inputs.yml');
+        process.exit(2);
+      }
       try {
-        const out = execSync(
-          `gh issue view ${issueId} --json title,body,labels,url`,
-          { cwd: repoRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }
+        // An argument list, not a shell string, and a bound: a hung gh must not hang the command.
+        const out = require('child_process').execFileSync(
+          'gh', ['issue', 'view', String(issueId), '--json', 'title,body,labels,url'],
+          { cwd: repoRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 30_000 }
         );
         issueMeta = JSON.parse(out);
         const labels = (issueMeta.labels || []).map(l => l.name);
@@ -4980,6 +5045,10 @@ program
           is_first_of_its_kind: false,
         };
       } catch (e) {
+        if (e && e.code === 'ETIMEDOUT') {
+          console.error(`error: gh issue view ${issueId} timed out after 30s`);
+          process.exit(2);
+        }
         console.error(`error: gh issue view ${issueId} failed: ${(e.stderr || '').toString().trim() || e.message}`);
         console.error(`hint: install GitHub CLI (cli.github.com), run \`gh auth login\`, or pass --input-file <path>`);
         process.exit(2);
@@ -5924,7 +5993,7 @@ program
     try {
       // HC-GF-092: advertise what this CLI can honour. The server serves the highest it also
       // knows, so an older CLI — which sends nothing — keeps being served contract 1.
-      const { data } = await client.get(`/orchestrate/${encodeURIComponent(runId)}/step-instruction?contracts=1,2`);
+      const { data } = await client.get(orchestratePath([runId, 'step-instruction'], { contracts: '1,2' }));
       if (opts.format === 'json') { console.log(JSON.stringify(data, null, 2)); return; }
       console.log(`Step:      ${data.stepKey} (${data.agent})`);
       console.log(`Contract:  ${data.contractVersion}`);
@@ -5976,7 +6045,7 @@ program
         output = fs.readFileSync(opts.file, 'utf8');
       }
       const { data } = await client.post(
-        `/orchestrate/${encodeURIComponent(runId)}/step/${encodeURIComponent(stepKey)}/editor-output`,
+        orchestratePath([runId, 'step', stepKey, 'editor-output']),
         { contractVersion: opts.contract, output }
       );
       if (opts.format === 'json') { console.log(JSON.stringify(data, null, 2)); return; }
@@ -6124,12 +6193,7 @@ program
     // the 2026-09-08 editor test nearly meaningless; here it costs money rather than time.
     try {
       const h = await client.get('/health').then(r => r.data).catch(() => null);
-      const llm = (h && h.llm) || null;
-      if (llm && llm.local) {
-        console.log(`LOCAL  ${config.apiUrl} · provider claude_cli · no paid fallback · this run costs $0.00`);
-      } else {
-        console.log(`PROD   ${config.apiUrl} · provider ${llm ? llm.primary : 'unknown'} · THIS RUN COSTS MONEY`);
-      }
+      console.log(require('./lib/server-banner').serverBanner(config.apiUrl, h));
     } catch { /* never block a run on a banner */ }
 
     const { resolveRunTarget, isRunId } = require('./lib/run-target');
@@ -6182,7 +6246,7 @@ program
 
         let status;
         try {
-          const { data: pollData } = await client.get(`/orchestrate/${pollRunId}`);
+          const { data: pollData } = await client.get(orchestratePath([pollRunId]));
           status = pollData;
         } catch (e) {
           console.error(`Poll error: ${e.message}`);
@@ -6250,7 +6314,8 @@ program
                 console.log(`  ${remedy.stepKey} named the files it needs. Re-queue with:`);
                 console.log(`    ${cmd}`);
                 if (remedy.truncated) {
-                  console.log(`    ⚠ it asked for more than ${remedy.paths.length} files; the rest were dropped.`);
+                  // HC-GF-263-followup-1: the cap counts entries, and one file may have several.
+                  console.log(`    ⚠ it asked for more than ${remedy.paths.length} paths; the rest were dropped.`);
                 }
               }
               // H5: say how many requested paths were withheld from the command, never what they were.
@@ -6352,14 +6417,14 @@ program
 
             if (answer.toLowerCase() === 'y' || answer.toLowerCase() === 'yes') {
               try {
-                await client.post(`/orchestrate/${pollRunId}/approve`, { stepKey: d.stepKey });
+                await client.post(orchestratePath([pollRunId, 'approve']), { stepKey: d.stepKey });
                 console.log('  Approved — workflow resuming...');
               } catch (e) {
                 console.error(`  Approve failed: ${e.response?.data?.error || e.message}`);
               }
             } else if (answer.toLowerCase() === 'kill') {
               try {
-                await client.post(`/orchestrate/${pollRunId}/kill`, { reason: 'CLI kill' });
+                await client.post(orchestratePath([pollRunId, 'kill']), { reason: 'CLI kill' });
                 console.log('  Workflow killed.');
                 process.exit(0);
               } catch (e) {
@@ -6388,7 +6453,7 @@ program
     if (opts.status) {
       try {
         const statusId = await existingRunId('--status');
-        const { data } = await client.get(`/orchestrate/${statusId}`);
+        const { data } = await client.get(orchestratePath([statusId]));
         if (opts.format === 'json') { console.log(JSON.stringify(data, null, 2)); return; }
         console.log('');
         console.log(`Workflow: ${data.runId}`);
@@ -6438,7 +6503,7 @@ program
     if (opts.kill) {
       try {
         const killId = await existingRunId('--kill');
-        const { data } = await client.post(`/orchestrate/${killId}/kill`, { reason: 'CLI kill' });
+        const { data } = await client.post(orchestratePath([killId, 'kill']), { reason: 'CLI kill' });
         console.log(`Workflow ${data.runId} killed.`);
       } catch (e) {
         console.error(`Failed: ${e.response?.data?.error || e.message}`);
@@ -6452,7 +6517,7 @@ program
       let approveId;
       try {
         approveId = await existingRunId(`--approve ${opts.approve}`);
-        await client.post(`/orchestrate/${approveId}/approve`,
+        await client.post(orchestratePath([approveId, 'approve']),
           { stepKey: opts.approve, acknowledgeAbort: opts.acknowledgeAbort === true,
             acknowledgeFailedVerdict: opts.acknowledgeFailedVerdict === true });
         console.log(`Gate ${opts.approve} approved. Workflow resuming.`);
@@ -6606,6 +6671,10 @@ program
   // auto-approve on output text, which never ran. Approve overnight on evidence with `hone follow-batch`.
   .option('--overnight', 'Enable Night Shift mode (longer timeouts, max 25 stories; step_4/step_5 still pause for approval)', false)
   .action(async (opts) => {
+    refuseBadRunArgs([ // HC-GF-270-followup-1
+      { label: '--status', kind: 'batchId', value: opts.status, optional: true },
+      { label: '--report', kind: 'batchId', value: opts.report, optional: true },
+    ]);
     const config = getConfig();
     const client = api(config);
 
@@ -6650,7 +6719,7 @@ program
       try {
         const format = opts.format === 'json' ? 'json' : 'md';
         const { data, headers } = await client.get(
-          `/orchestrate/batch/${opts.report}/report`,
+          orchestratePath(['batch', opts.report, 'report']),
           { params: { format }, responseType: 'text', transformResponse: [(d) => d] }
         );
         if (format === 'json') {
@@ -6701,7 +6770,7 @@ program
     // ── --status <batchId> ────────────────────────────────────
     if (opts.status) {
       try {
-        const { data } = await client.get(`/orchestrate/batch/${opts.status}`);
+        const { data } = await client.get(orchestratePath(['batch', opts.status]));
         if (opts.format === 'json') { console.log(JSON.stringify(data, null, 2)); return; }
         console.log('');
         console.log(`Batch:    ${data.batchId}`);
@@ -7561,13 +7630,15 @@ showCmd
   .option('--attempt <n>', 'Specific attempt number (default: latest)')
   .option('--prompt', 'Also print the exact prompt this step sent to the model (HC-GF-055)')
   .action(async (workflowId, stepKey, opts) => {
+    refuseBadRunArgs([ // HC-GF-270-followup-1
+      { label: '<workflowId>', kind: 'runId', value: workflowId },
+      { label: '<stepKey>', kind: 'stepKey', value: stepKey },
+      { label: '--attempt', kind: 'attempt', value: opts.attempt, optional: true },
+    ]);
     const config = getConfig();
     const client = api(config);
     try {
-      const q = [];
-      if (opts.attempt) q.push(`attempt=${opts.attempt}`);
-      if (opts.prompt) q.push('prompt=1');
-      const url = `/orchestrate/${workflowId}/step/${stepKey}${q.length ? `?${q.join('&')}` : ''}`;
+      const url = orchestratePath([workflowId, 'step', stepKey], { attempt: opts.attempt, prompt: opts.prompt ? '1' : undefined });
       const r = await client.get(url);
       const s = r.data;
       console.log(`── step output ──────────────────────────────────────────`);
@@ -7624,6 +7695,7 @@ program
   .option('--attempt <n>', 'Specific attempt number (default: latest)')
   .option('--format <fmt>', 'Output format: pretty or json', 'pretty')
   .action(async (workflowId, opts) => {
+    refuseBadRunArgs(stepFetchChecks(workflowId, opts)); // HC-GF-270-followup-1
     const { execFileSync } = require('child_process');
     const os = require('os');
     const { extractDiff, interpretApplyCheck } = require('./lib/patch-apply');
@@ -7639,8 +7711,7 @@ program
 
     let output;
     try {
-      const url = `/orchestrate/${workflowId}/step/${opts.stepKey}` +
-        (opts.attempt ? `?attempt=${opts.attempt}` : '');
+      const url = orchestratePath([workflowId, 'step', opts.stepKey], { attempt: opts.attempt });
       const r = await client.get(url);
       output = r.data?.output;
     } catch (e) {
@@ -7764,6 +7835,7 @@ program
   .option('--trust-source', 'HC-GF-270: run a patch whose story text came from a source Hone does not trust (you have read the diff)')
   .option('--format <fmt>', 'Output format: pretty or json', 'pretty')
   .action(async (workflowId, opts) => {
+    refuseBadRunArgs(stepFetchChecks(workflowId, opts)); // HC-GF-270(-followup-1): first, before any config read
     const { execFileSync, spawnSync } = require('child_process');
     // HC-GF-200: refuse a mistyped bound HERE, naming the flag. Left to node,
     // a NaN becomes `RangeError: ... It must be an integer. Received NaN` from
@@ -7782,13 +7854,6 @@ program
     const { gitEnv } = require('./lib/git-env');
     const config = getConfig();
     const client = api(config);
-    // HC-GF-270 (second review MEDIUM-1): the step key goes into a URL and a file name, and URL
-    // resolution collapses `..` — `--step-key ../../<other run>/step/step_4` fetched ANOTHER run's
-    // patch while THIS run's config was assessed. A step key is a step key.
-    if (!/^step_[0-9a-z_]+$/i.test(String(opts.stepKey || ''))) {
-      console.error(`--step-key must name a step, like step_4 (got ${JSON.stringify(opts.stepKey)})`);
-      process.exit(2);
-    }
     const sameRun = (id) => String(id).toLowerCase() === String(workflowId).toLowerCase();
 
     const emit = (obj, humanLine) => {
@@ -7806,8 +7871,7 @@ program
     let runStoryId = null;
     let runFetchFailed = false;
     try {
-      const url = `/orchestrate/${encodeURIComponent(workflowId)}/step/${encodeURIComponent(opts.stepKey)}` +
-        (opts.attempt ? `?attempt=${opts.attempt}` : '');
+      const url = orchestratePath([workflowId, 'step', opts.stepKey], { attempt: opts.attempt });
       const r = await client.get(url);
       // The step output must be THIS run's: nothing else ties the patch to the config assessed below.
       if (r.data?.runId && !sameRun(r.data.runId)) throw new Error(`the server returned ${opts.stepKey} for a different run`);
@@ -7817,7 +7881,7 @@ program
       verifiedAttempt = r.data?.attempt != null ? Number(r.data.attempt) : undefined;
       // best-effort: pull the run's ci_local_command for the default
       try {
-        const runR = await client.get(`/orchestrate/${encodeURIComponent(workflowId)}`);
+        const runR = await client.get(orchestratePath([workflowId]));
         // HC-GF-270 (security review BLOCKER-1): the id is ENCODED above, so a crafted
         // `<uuid>/step/step_4?` cannot turn this into a fetch of some other endpoint that answers
         // 200 with no config. And a body that is not THIS run is not this run's config.
@@ -8234,7 +8298,7 @@ program
     // change the local exit code (the verdict is already true locally).
     if (opts.report && reportVerdict) {
       try {
-        await client.post(`/orchestrate/${encodeURIComponent(workflowId)}/verdict`, {
+        await client.post(orchestratePath([workflowId, 'verdict']), {
           source: 'verify-patch',
           stepKey: opts.stepKey,
           verdict: reportVerdict,
@@ -8243,7 +8307,7 @@ program
           attempt: opts.attempt ? Number(opts.attempt) : verifiedAttempt,
           headSha,
           gates: reportGates.length ? reportGates : undefined,
-        });
+        }, require('./lib/fresh-connection').freshConnection());
         if (opts.format !== 'json') {
           // HC-GF-070: name the gate that is actually configured. This said "(advisory)"
           // unconditionally, and printed it on a run where `enforce` was auto-approving
@@ -8268,11 +8332,12 @@ program
   .description('What happened on a run, and what still needs you')
   .option('--format <fmt>', 'Output format: pretty or json', 'pretty')
   .action(async (runId, opts) => {
+    refuseBadRunArgs([{ label: '<runId>', kind: 'runId', value: runId }]); // HC-GF-270-followup-1
     const { buildReport, renderReport } = require('./lib/run-report');
     const config = getConfig();
     const client = api(config);
     try {
-      const { data } = await client.get(`/orchestrate/${runId}`);
+      const { data } = await client.get(orchestratePath([runId]));
       const report = buildReport(data);
       if (opts.format === 'json') console.log(JSON.stringify(report, null, 2));
       else console.log(renderReport(report));
@@ -8334,8 +8399,8 @@ program
     const client = api(config);
     const repoName = opts.repo || path.basename(process.cwd());
     const io = {
-      fetchBatch: async (id) => (await client.get(`/orchestrate/batch/${encodeURIComponent(id)}`)).data,
-      fetchRun: async (id) => (await client.get(`/orchestrate/${encodeURIComponent(id)}`)).data,
+      fetchBatch: async (id) => (await client.get(orchestratePath(['batch', id]))).data,
+      fetchRun: async (id) => (await client.get(orchestratePath([id]))).data,
       runVerb: (argv) => new Promise((resolve) => {
         const child = spawn(process.execPath, [process.argv[1], ...argv],
           { cwd: process.cwd(), env: process.env, stdio: ['ignore', 'inherit', 'inherit'] });
@@ -8389,6 +8454,7 @@ program
   .option('--no-provision', 'Do not install/link dependencies into the isolated worktree (HC-COMM-010-followup-6)')
   .option('--format <fmt>', 'Output format: pretty or json', 'pretty')
   .action(async (workflowId, opts) => {
+    refuseBadRunArgs(stepFetchChecks(workflowId, opts)); // HC-GF-270(-followup-1): first, before any config read
     const { execFileSync, spawnSync } = require('child_process');
     // HC-GF-200: refuse a mistyped bound HERE, naming the flag. Left to node,
     // a NaN becomes `RangeError: ... It must be an integer. Received NaN` from
@@ -8406,19 +8472,26 @@ program
     const { resolveCommandDetailed, verdictFromRun, verifyCommandEnv } = require('./lib/verify-patch');
     const { verifyStateFor } = require('./lib/emit-pr');
     const {
-      EXIT, buildBranchName, buildCommitMessage, buildPrBody, decidePublish,
+      EXIT, buildBranchName, buildCommitMessage, buildPrBody, decidePublish, recordPr,
     } = require('./lib/emit-pr');
     const { gitEnv } = require('./lib/git-env');
     const config = getConfig();
     const client = api(config);
-    // HC-GF-270 (second review MEDIUM-1): the step key goes into a URL and a file name, and URL
-    // resolution collapses `..` — `--step-key ../../<other run>/step/step_4` fetched ANOTHER run's
-    // patch while THIS run's config was assessed. A step key is a step key.
-    if (!/^step_[0-9a-z_]+$/i.test(String(opts.stepKey || ''))) {
-      console.error(`--step-key must name a step, like step_4 (got ${JSON.stringify(opts.stepKey)})`);
-      process.exit(2);
-    }
     const sameRun = (id) => String(id).toLowerCase() === String(workflowId).toLowerCase();
+    // HC-GF-302: record the PR on the run. The POST goes out after the verify, push and `gh` steps,
+    // which block the event loop for minutes, and a keep-alive socket the server closed meanwhile
+    // fails `write EPIPE` when reused (HC-GF-326). A fresh connection per record avoids that.
+    //
+    // F3 (review): baseSha and attempt are the CALLER's to supply, not this closure's defaults —
+    // the two call sites below have different bases for trusting each one (see their own
+    // comments). recordPr itself stays pure; this only wires up the transport.
+    const recordPrOnRun = ({ prUrl, branch: prBranch, baseSha: recBaseSha = null, attempt: recAttempt }) => recordPr({
+      post: (p, body) => client.post(p, body, require('./lib/fresh-connection').freshConnection()),
+      path: orchestratePath([workflowId, 'pr-record']),
+      prUrl, branch: prBranch, baseSha: recBaseSha, attempt: recAttempt,
+    });
+    const recordWarning = (rec) => (rec.recorded || opts.format === 'json'
+      ? '' : `\n  ⚠ the run's PR record was not saved (non-fatal; the morning report may miss this link): ${rec.reason}`);
 
     // --open-pr implies --push (cannot open a PR against an unpushed branch).
     const doPush = Boolean(opts.push || opts.openPr);
@@ -8439,15 +8512,18 @@ program
     // branch naming, and 'story' is not all digits — so assessing it would trust a run whose id
     // never arrived.
     let runStoryId = null;
+    // HC-GF-302: the attempt the server resolved (the latest one unless --attempt named it), which
+    // orders this run's PR records. Not opts.attempt: that is absent in the default case.
+    let stepAttempt = null;
     try {
-      const url = `/orchestrate/${encodeURIComponent(workflowId)}/step/${encodeURIComponent(opts.stepKey)}` +
-        (opts.attempt ? `?attempt=${opts.attempt}` : '');
+      const url = orchestratePath([workflowId, 'step', opts.stepKey], { attempt: opts.attempt });
       const r = await client.get(url);
       // The step output must be THIS run's: nothing else ties the patch to the config assessed below.
       if (r.data?.runId && !sameRun(r.data.runId)) throw new Error(`the server returned ${opts.stepKey} for a different run`);
       output = r.data?.output;
+      stepAttempt = Number.isInteger(r.data?.attempt) ? r.data.attempt : null;
       try {
-        const runR = await client.get(`/orchestrate/${encodeURIComponent(workflowId)}`);
+        const runR = await client.get(orchestratePath([workflowId]));
         // HC-GF-270 (security review BLOCKER-1): see verify-patch — encoded id, and a body that
         // is not THIS run does not count as its config.
         if (runR.data?.runId && !sameRun(runR.data.runId)) throw new Error('run id mismatch');
@@ -8550,8 +8626,24 @@ program
     }
     const decision = decidePublish({ branchExists, openPrUrl });
     if (decision.action === 'already_open') {
-      emit({ ok: true, verdict: 'already_open', prUrl: decision.prUrl, branch },
-        `✓ a draft PR is already open for ${branch}: ${decision.prUrl}`);
+      // HC-GF-302 (review F3): record here too — hone follow-batch sends a completed run's emit
+      // to the branch its draft already opened, so this is the path that retries a record the
+      // draft failed to save. But this path never verified anything against a specific attempt:
+      // it found an already-open PR without running check-patch/verify-patch here, so it has no
+      // basis to claim `headSha` is this attempt's base — baseSha is always null on this path.
+      // And `stepAttempt` above is whichever attempt the server considers LATEST, which is not
+      // necessarily the attempt the open PR's branch was built from — so this only records when
+      // the caller named the attempt explicitly with --attempt. `hone follow-batch` always does
+      // (cli/lib/batch-follow.js buildArgs pushes `--attempt N` for every emit-pr call it makes);
+      // a bare `hone emit-pr --open-pr` with no --attempt has no basis to order a record either,
+      // so it records nothing rather than guessing.
+      const explicitAttempt = opts.attempt !== undefined ? Number(opts.attempt) : null;
+      const rec = explicitAttempt != null
+        ? await recordPrOnRun({ prUrl: decision.prUrl, branch, baseSha: null, attempt: explicitAttempt })
+        : { recorded: false, reason: 'the open PR\'s attempt is unknown; pass --attempt' };
+      emit({ ok: true, verdict: 'already_open', prUrl: decision.prUrl, branch, recorded: rec.recorded,
+        ...(rec.recorded ? {} : { recordError: rec.reason }) },
+        `✓ a draft PR is already open for ${branch}: ${decision.prUrl}${recordWarning(rec)}`);
       process.exit(EXIT.PASS);
     }
     if (decision.action === 'branch_conflict') {
@@ -8724,8 +8816,13 @@ program
 
           if (exitCode === EXIT.PASS) {
             const tier = prUrl ? 'pr' : pushed ? 'pushed' : 'dry_run';
+            // HC-GF-302: only a PR is recorded; a pushed or local branch has no link to show. This
+            // is the path that just verified the diff and committed it: headSha is the commit the
+            // patch was verified against, so it is a true baseSha here (unlike the already_open
+            // path above, which never ran that verification and always records baseSha: null).
+            const rec = prUrl ? await recordPrOnRun({ prUrl, branch, baseSha: headSha || null, attempt: stepAttempt }) : null;
             const human = prUrl
-              ? `✓ draft PR opened: ${prUrl}`
+              ? `✓ draft PR opened: ${prUrl}${recordWarning(rec)}`
               : pushed
                 ? `✓ branch pushed to origin/${branch}\n  → open a PR: gh pr create --head ${branch} --draft`
                 : `✓ branch '${branch}' built locally (dry run — nothing pushed)\n` +
@@ -8733,7 +8830,11 @@ program
                   `  → push it:      hone emit-pr ${workflowId} --push\n` +
                   `  → push + PR:    hone emit-pr ${workflowId} --open-pr\n` +
                   `  → discard it:   git branch -D ${branch}`;
-            emit({ ok: true, verdict: tier, branch, verifyState, prUrl, pushed, headSha }, human);
+            // F8 (review): --format json previously dropped the failure reason entirely once
+            // `recorded` was false — a reader had no way to tell why without re-running in
+            // --format pretty. Same object, one extra field, omitted once recorded:true.
+            emit({ ok: true, verdict: tier, branch, verifyState, prUrl, pushed, headSha,
+              ...(rec ? { recorded: rec.recorded, ...(rec.recorded ? {} : { recordError: rec.reason }) } : {}) }, human);
           }
         }
       }
@@ -8766,6 +8867,8 @@ program
   .option('--workflow-id <id>', 'the run id to report the verdict against (required with --report)')
   .option('--format <fmt>', 'pretty or json', 'pretty')
   .action(async (prOrBranch, opts) => {
+    // HC-GF-270-followup-1: a --workflow-id is checked before any gh call or CI command runs.
+    refuseBadRunArgs([{ label: '--workflow-id', kind: 'runId', value: opts.workflowId, optional: true }]);
     const { execFileSync, spawnSync } = require('child_process');
     // HC-GF-200: refuse a mistyped bound HERE, naming the flag. Left to node,
     // a NaN becomes `RangeError: ... It must be an integer. Received NaN` from
@@ -8867,13 +8970,13 @@ program
       } else {
         try {
           const client = api(getConfig());
-          await client.post(`/orchestrate/${opts.workflowId}/verdict`, {
+          await client.post(orchestratePath([opts.workflowId, 'verdict']), {
             source: 'verify-pr',
             stepKey: 'step_5c',
             verdict: verdict.verdict,
             exitCode: verdict.exitCode,
             detail: verdict.detail,
-          });
+          }, require('./lib/fresh-connection').freshConnection());
           reported = true;
           if (opts.format !== 'json') console.log(`  → reported CI-gate verdict '${verdict.verdict}' to run ${opts.workflowId} (advisory)`);
         } catch (e) {

package/lib/bundle-paths.js

@@ -315,13 +315,25 @@ function anchorLineForStory(content, storyText) {
  * The fallback is the OLD behaviour on purpose: a term that is only ever mentioned still
  * gets the operator a window near it, which beats none.
  */
+/**
+ * HC-GF-206-followup-1: a collapsed hit is a real site — the collapse only means it EXPECTS to
+ * share its neighbour's window, not that it is covered. The final window's radius is chosen
+ * later (as low as 200 chars, `planFileExcerpt`) and can land under the 40-line threshold that
+ * collapsed it, so a hit collapsed at 36 lines from its neighbour can fall outside the window
+ * that was supposed to carry it, with nothing reporting the loss. `collapsed` returns each
+ * dropped hit with `near`, the kept site's line it was folded into, so the caller can extend
+ * that site's window to actually reach it.
+ *
+ * @returns {{sites: Array<{line: number, anchor: string}>,
+ *            collapsed: Array<{line: number, anchor: string, near: number}>}}
+ */
 function anchorSitesForStory(content, storyText, max = 6) {
   // HC-GF-204: every region a story's terms point at, best-first. `anchorLineForStory`
   // answers "where does this live"; a story also needs "where is it USED", and on run
   // ad4a561f the planner had the definition and refused for want of the call sites.
   const text = String(content || '');
   const story = String(storyText || '');
-  if (!text || !story) return [];
+  if (!text || !story) return { sites: [], collapsed: [] };
   const candidates = [...story.matchAll(BACKTICKED_RE)]
     .map((m) => m[1].trim())
     .filter((c) => c.length >= 3
@@ -331,6 +343,7 @@ function anchorSitesForStory(content, storyText, max = 6) {
 
   const seenLine = new Set();
   const sites = [];
+  const collapsed = [];
   for (const anchor of candidates) {
     const def = definitionIndexOf(text, anchor);
     if (def === -1) continue;
@@ -339,14 +352,16 @@ function anchorSitesForStory(content, storyText, max = 6) {
     for (const m of text.matchAll(new RegExp(`(?<![\\w$])${t}(?![\\w$])`, 'g'))) offsets.push(m.index);
     for (const off of offsets) {
       const line = text.slice(0, off).split('\n').length;
-      // Collapse near-duplicates: two hits 20 lines apart share one window.
-      if ([...seenLine].some((l) => Math.abs(l - line) < 40)) continue;
+      // Collapse near-duplicates: two hits 20 lines apart share one window. `near` records
+      // WHICH kept site it shares with, so a caller can pull it back in later.
+      const near = [...seenLine].find((l) => Math.abs(l - line) < 40);
+      if (near !== undefined) { collapsed.push({ line, anchor, near }); continue; }
       seenLine.add(line);
       sites.push({ line, anchor });
-      if (sites.length >= max) return sites;
+      if (sites.length >= max) return { sites, collapsed };
     }
   }
-  return sites;
+  return { sites, collapsed };
 }
 
 function definitionIndexOf(text, term) {
@@ -428,7 +443,7 @@ function planFileExcerpt({ content, cap, line = null, lines = null, storyText =
     // hence budgeted first, and `mergeIntersectingWindows` unions it with any inferred
     // window it overlaps. No sort, no priority field — array order already says it.
     // HC-GF-288: every stated line seeds it, in the caller's order.
-    const inferred = anchorSitesForStory(text, storyText);
+    const { sites: inferred, collapsed } = anchorSitesForStory(text, storyText);
     const sites = [...stated.map((l) => ({ line: l, anchor: null })), ...inferred];
     const chosen = sites.length ? sites : [hit];
     const why = (a, l) => (a ? `anchored on \`${a}\`` : `centered on referenced line ${l}`);
@@ -515,15 +530,15 @@ function planFileExcerpt({ content, cap, line = null, lines = null, storyText =
     // only ever dropped when the stated regions alone exceed the cap.
     const budget = (ord) => {
       const kept = [];
+      const skipped = [];
       let spent = 0;
-      let skipped = 0;
       for (const site of ord) {
         const cost = costOf(site);
         if (spent + cost > limit) {
           // A dropped stated region is reported by LINE below, not counted here: the
           // advice attached to this count — "name them as path:<line>" — is advice the
           // operator has already followed for those.
-          if (!site.stated) skipped += 1;
+          if (!site.stated) skipped.push(site);
           continue;
         }
         spent += cost;
@@ -551,6 +566,12 @@ function planFileExcerpt({ content, cap, line = null, lines = null, storyText =
     // considered: a layout with no window sends the result to the fallback, which overruns
     // the cap by construction. Third review: preferring width alone discarded a 1,066-char
     // layout for a 33,002-char fallback at cap 12,000.
+    //
+    // HC-GF-188-followup-1: so a layout that kept nothing has not succeeded, stated lines or
+    // not. With none stated, "honours every stated line" was vacuously true at the estimate,
+    // the narrower retry never ran, and the fallback returned 30,502 chars at cap 12,000 —
+    // the first inferred anchor's long line — while the second anchor's window, 411 chars at
+    // radius 200, was never tried. With a stated line, honouring it already means a window.
     let best = null;
     const better = (a, b) => (a.honoured - b.honoured)
       || (Number(a.plan.kept.length > 0) - Number(b.plan.kept.length > 0))
@@ -560,10 +581,10 @@ function planFileExcerpt({ content, cap, line = null, lines = null, storyText =
       const honoured = stated.filter((l) => plan.kept.some(({ w }) => covers(w, l))).length;
       const cand = { r, plan, honoured };
       if (!best || better(cand, best) > 0) best = cand;
-      return honoured === stated.length;
+      return honoured === stated.length && plan.kept.length > 0;
     };
     if (!tryRadius(radius) && radius > 200 && tryRadius(200)) {
-      // All stated lines fit at 200 but not at the estimate: binary-search between them.
+      // It fits at 200 but not at the estimate: binary-search between them.
       // Bounded by log2(radius) layouts — measured at most 12 layouts and 228 ms on a
       // 1.6 MB file of long lines, a few ms on ordinary source.
       let lo = 200;
@@ -575,7 +596,6 @@ function planFileExcerpt({ content, cap, line = null, lines = null, storyText =
     }
     radius = best.r;
     windows.push(...best.plan.kept);
-    const dropped = best.plan.skipped;
     if (!windows.length) {
       // Nothing fits at any radius tried — one line alone is longer than the cap. Build the
       // window at the MINIMUM radius, so the overrun is that line and no more: at the
@@ -583,6 +603,66 @@ function planFileExcerpt({ content, cap, line = null, lines = null, storyText =
       const w = windowAroundLine(text, chosen[0].line, 200);
       windows.push({ w, anchor: chosen[0].anchor, line: chosen[0].line });
     }
+    // HC-GF-188-followup-1: a region is dropped when NOTHING bundled reaches it — counted
+    // against what is returned, not what the budget skipped. The fallback above returns one
+    // region the budget had skipped, and the notice still called it dropped: "2 further
+    // region(s) DROPPED" with one missing. Every window grows with the radius around the
+    // same line, so the fallback's window lies inside that region's; and the layout's
+    // regions are disjoint once merged, so no other skipped region intersects a kept one.
+    const dropped = best.plan.skipped.filter((s) =>
+      !windows.some(({ w }) => w.startLine <= s.w.endLine && s.w.startLine <= w.endLine)).length;
+
+    // HC-GF-206-followup-1: a collapsed hit shares its neighbour's window in EXPECTATION only.
+    // `radius` was chosen for the whole layout and can end up under the 40-line threshold that
+    // collapsed the hit in the first place, cutting it out of the window that was supposed to
+    // carry it. Pull each missed hit back in by widening its neighbour's window to reach it,
+    // then re-merge — widening can make two previously-separate kept windows intersect.
+    let unreached = 0;
+    if (collapsed.length) {
+      for (const hit of collapsed) {
+        if (windows.some(({ w }) => covers(w, hit.line))) continue; // already inside some window
+        // The neighbour is the kept window whose site.line this hit collapsed into — falling
+        // back to nearest-by-distance when that site's own window was dropped for budget.
+        let target = windows.find(({ line: siteLine }) => siteLine === hit.near);
+        if (!target) {
+          let bestDist = Infinity;
+          for (const entry of windows) {
+            const dist = hit.line < entry.w.startLine ? entry.w.startLine - hit.line
+              : hit.line > entry.w.endLine ? hit.line - entry.w.endLine : 0;
+            if (dist < bestDist) { bestDist = dist; target = entry; }
+          }
+        }
+        if (!target) continue; // no window exists at all — reported as unreached below
+        // THE BUDGET PROMISE STILL HOLDS: widen, re-merge (an overlap with another kept window
+        // is a real possibility once widened), price the result, and roll back rather than
+        // overrun the cap. A hit that cannot be reached within budget is unreached, not free.
+        const before = windows.map((e) => ({ ...e }));
+        target.w = windowBetweenLines(text,
+          Math.min(target.w.startLine, hit.line), Math.max(target.w.endLine, hit.line));
+        const merged = mergeIntersectingWindows(text, windows);
+        const cost = merged.reduce((s, e) => s + costOf(e), 0);
+        if (cost > limit) {
+          windows.length = 0;
+          windows.push(...before);
+          continue;
+        }
+        windows.length = 0;
+        windows.push(...merged);
+      }
+      // Re-sort stated windows back to the front — merging can reorder when a widened window
+      // now overlaps one processed earlier, and `windows[0]` below is read as THE region (its
+      // anchor and line drive `because`). Mirrors `layout()`'s own sort exactly: `rankOf` returns
+      // -1 for a non-stated window, and sorting on that raw value would put it AHEAD of a stated
+      // one (found-index 0) rather than behind every stated window — map it to Infinity first.
+      const resorted = windows
+        .map((c, i) => { const k = rankOf(c); return { c, k: k === -1 ? Infinity : k, i }; })
+        .sort((a, b) => (a.k - b.k) || (a.i - b.i))
+        .map(({ c }) => c);
+      windows.length = 0;
+      windows.push(...resorted);
+      unreached = collapsed.filter((hit) => !windows.some(({ w }) => covers(w, hit.line))).length;
+    }
+
     // HC-GF-288: which stated lines no kept window contains. Only the budget can do that
     // here — every stated line seeded a window, and a merge never shrinks one.
     const lost = stated.filter((l) => !windows.some(({ w }) => covers(w, l)));
@@ -600,6 +680,11 @@ function planFileExcerpt({ content, cap, line = null, lines = null, storyText =
       : '')
       + (lost.length > 0
         ? ` — stated line(s) ${lost.join(', ')} DROPPED for budget; name fewer regions in ${filePath}`
+        : '')
+      // HC-GF-206-followup-1: a hit collapsed into a neighbour whose final window still missed
+      // it — counted rather than silent, the same shape as `dropped` and `lost` above.
+      + (unreached > 0
+        ? ` — ${unreached} near-duplicate hit(s) collapsed into a window that did not reach them`
         : '');
 
     return {
@@ -613,12 +698,16 @@ function planFileExcerpt({ content, cap, line = null, lines = null, storyText =
     };
   }
 
-  const dropped = text.length - limit;
+  // HC-GF-188-followup-1: the marker is inside the cap, as a window's header and footer are.
+  // Appended after `limit` chars, it took cli/hone-cli.js to 8,077 chars at cap 8,000. It
+  // names the chars KEPT, which is at most `limit`, so its own length can only shrink.
+  const marker = (n) => `\n\n# [HC-019n-followup-12: truncated at ${n} chars; full file is ${text.length} chars]`;
+  const keep = Math.max(0, limit - marker(limit).length);
+  const dropped = text.length - keep;
   return {
     mode: 'truncate',
     unhonoured,
-    content: text.slice(0, limit)
-      + `\n\n# [HC-019n-followup-12: truncated at ${limit} chars; full file is ${text.length} chars]`,
+    content: text.slice(0, keep) + marker(keep),
     notice: `  ⚠ ${filePath} is ${text.length} chars (cap ${limit}) — head-truncated, ${dropped} chars `
       + `DROPPED and nothing in the story text matched inside the file, so the region you care about `
       + `may not be in the bundle. Name it as ${filePath}:<line>, or quote the code, to anchor it.`,

package/lib/emit-pr.js

@@ -188,7 +188,35 @@ function decidePublish({ branchExists, openPrUrl }) {
   return { action: 'proceed', exitCode: EXIT.PASS };
 }
 
+/**
+ * HC-GF-302: tell the server which PR this emit opened or found already open, so the batch's
+ * morning report links it instead of hoping an agent wrote the URL into its output.
+ *
+ * Best-effort, and the caller never changes its exit code on the result: the PR exists either way.
+ * It only reports whether the server now knows about it. No PR URL (a dry run, or a push without
+ * --open-pr) records nothing: the report has no link to show for a branch. The attempt is the one
+ * the step GET resolved; without it the server cannot order records, so nothing is sent.
+ *
+ * @param {{ post: (path: string, body: object) => Promise<unknown>, path: string, prUrl?: string|null,
+ *   branch: string, baseSha?: string|null, attempt?: number|null }} args
+ * @returns {Promise<{ recorded: boolean, reason?: string }>}
+ */
+async function recordPr({ post, path, prUrl, branch, baseSha, attempt }) {
+  if (!prUrl) return { recorded: false, reason: 'no PR URL to record' };
+  if (!Number.isInteger(attempt) || attempt < 1) {
+    return { recorded: false, reason: 'the server did not say which step_4 attempt this is' };
+  }
+  try {
+    await post(path, { branch, prUrl, baseSha: baseSha || null, attempt });
+    return { recorded: true };
+  } catch (e) {
+    const detail = (e && e.response && e.response.data && e.response.data.error) || (e && (e.code || e.message)) || String(e);
+    return { recorded: false, reason: e && e.response ? `HTTP ${e.response.status}: ${detail}` : detail };
+  }
+}
+
 module.exports = {
+  recordPr,
   verifyStateFor,
   EXIT,
   HONEST_LIMIT,

package/lib/fresh-connection.js

@@ -0,0 +1,27 @@
+'use strict';
+
+/**
+ * HC-GF-326: request options that open a NEW connection for one request.
+ *
+ * Node's default agent keeps sockets alive. verify-patch GETs the run, then runs the
+ * test suite with spawnSync, which blocks the event loop for minutes — far past the
+ * server's keep-alive timeout (5 s by default). The server closes the idle socket, the
+ * blocked client never processes the close, and the verdict POST is written to the dead
+ * pooled socket: `read ECONNRESET`, 5 reports out of 5, each labelled non-fatal. Every
+ * verdict a verify produced was lost to the server.
+ *
+ * Pass these to the one request that follows a long synchronous block. What makes the
+ * connection fresh is the new agent: its pool is empty, so the request opens a socket.
+ * `keepAlive: false` only stops that socket being pooled afterwards.
+ */
+const http = require('http');
+const https = require('https');
+
+function freshConnection() {
+  return {
+    httpAgent: new http.Agent({ keepAlive: false }),
+    httpsAgent: new https.Agent({ keepAlive: false }),
+  };
+}
+
+module.exports = { freshConnection };

package/lib/learnings-parse.js

@@ -284,11 +284,55 @@ function parseSchemaD(doc, includePromoted = false) {
   }];
 }
 
+// ─────────────────────────────────────────────────────────────────────
+// parseRetracted — the entries `hone retract --from-yaml` sends
+//
+// HC-GF-311-followup-1: the retract action read only each file's TOP level, so a Schema C
+// file offered its story frame, which has no `id`, and every per-learning
+// `status: retracted` beneath it was skipped. Measured 2026-09-26 on
+// origin/main: 14 retracted learnings in 12 files, and the dry-run found 0.
+// Each id below is the one the matching parseSchemaX gives `hone promote`,
+// because the server can only retract a row under the id it was promoted as.
+// The id stays the value YAML loaded, not String(id): both commands send it
+// through JSON, so `id: 2026-09-26` (a Date) arrives as the same ISO string.
+// An entry with no id is skipped; promote sent those under the file name.
+// A learning must say `retracted` itself: a story-level status is not
+// inherited here, because a retraction is a claim about one learning.
+// Returns { schema, retracted: [{ id, reason }], parseError? }; reason is
+// null when the entry gives no `retraction_reason`.
+// ─────────────────────────────────────────────────────────────────────
+function parseRetracted(content) {
+  let parsed;
+  try { parsed = yaml.load(content); }
+  catch (e) { return { schema: SCHEMA_UNKNOWN, retracted: [], parseError: e }; }
+
+  const schema = detectSchema(parsed);
+  const isRetracted = (e) => e && typeof e === 'object' && e.status === 'retracted';
+  const entry = (id, e) => ({ id, reason: e.retraction_reason || null });
+
+  let retracted = [];
+  if (schema === SCHEMA_A) {
+    retracted = parsed.filter(i => isRetracted(i) && i.id).map(i => entry(i.id, i));
+  } else if (schema === SCHEMA_B) {
+    retracted = parsed.enterprise_candidates
+      .filter(c => isRetracted(c) && c.id !== null && c.id !== undefined)
+      .map(c => entry(`${parsed.story_id}-${c.id}`, c));
+  } else if (schema === SCHEMA_C) {
+    retracted = parsed.learnings.filter(l => isRetracted(l) && l.id).map(l => entry(l.id, l));
+  } else if (schema === SCHEMA_D) {
+    if (isRetracted(parsed) && (parsed.id || parsed.story_id)) retracted = [entry(parsed.id || parsed.story_id, parsed)];
+  } else if (isRetracted(parsed) && parsed.id) {
+    // Any other single dict keeps the top-level read the action always did.
+    retracted = [entry(parsed.id, parsed)];
+  }
+  return { schema, retracted };
+}
+
 // ─────────────────────────────────────────────────────────────────────
 // writeBackPromoted — schema-aware idempotent regex rewrite
 //
 // All 3 schemas write per-item `status: promoted` because `hone retract`
-// at cli/hone-cli.js:1349 reads `entry?.status === 'retracted'` per-item.
+// (parseRetracted above) reads `status: retracted` per-item.
 // Replacing per-item status with a top-level marker would break retract.
 // ─────────────────────────────────────────────────────────────────────
 function writeBackPromoted(content, schema, idsPromoted) {
@@ -424,6 +468,7 @@ module.exports = {
   SCHEMA_UNKNOWN,
   detectSchema,
   parseLearningsFile,
+  parseRetracted,
   writeBackPromoted,
   // LC-001 / #58 G2 partial: categorization API (advisory).
   LEARNING_CATEGORIES,

package/lib/mcp-tools.js

@@ -13,6 +13,7 @@ const { spawn } = require('node:child_process');
 const fsSync = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
+const { privateTempFile } = require('./private-temp');
 
 // Resolve the CLI binary. Default `hone` (the installed bin); overridable for tests
 // / non-global installs via HONE_CLI_BIN (e.g. a path to hone-cli.js run with node).
@@ -24,12 +25,15 @@ function honeBin() {
 // default) — but WITHOUT exiting on a missing token (the MCP server must start and
 // report the problem via a preflight / hone_doctor, not die). Editor-agnostic:
 // works from any MCP client that passes HONE_TOKEN/HONE_API in the server env.
+// HC-GF-304-followup-1: reports THAT a token exists, never the token. Nothing here sends one — every
+// tool shells out to the CLI, which reads its own — and `token` was returned to callers that read
+// only `hasToken`, one serialization away from the stderr preflight.
 function readHoneConfig() {
   let rc = {};
   try { rc = JSON.parse(fsSync.readFileSync(path.join(os.homedir(), '.honerc'), 'utf8')) || {}; } catch { rc = {}; }
   const token = process.env.HONE_TOKEN || rc.token || null;
   const apiUrl = process.env.HONE_API || rc.api || 'https://api.hone.ai';
-  return { token, apiUrl, hasToken: !!token };
+  return { apiUrl, hasToken: !!token };
 }
 
 // Run a `hone` subcommand, capturing stdout/stderr/exit. Never throws — returns a
@@ -163,7 +167,7 @@ async function stepInstruction({ runId, cwd } = {}) {
 
 // hone_submit_step — submit editor-executed output (HC-COMM-010 B3). Output
 // travels via a temp file (1MB-class payloads must not ride argv); the file
-// is best-effort deleted after the shell-out.
+// and its directory are best-effort deleted after the shell-out.
 async function submitStep({ runId, stepKey, output, contractVersion = '1', fromTree = false, testReport, cwd } = {}) {
   if (!runId) return { isError: true, detail: 'runId is required' };
   if (!stepKey) return { isError: true, detail: 'stepKey is required' };
@@ -184,18 +188,20 @@ async function submitStep({ runId, stepKey, output, contractVersion = '1', fromT
 
   const base = ['submit-step', String(runId), String(stepKey), '--contract', String(contractVersion), '--format', 'json'];
   let tmp = null;
-  if (fromTree) {
-    base.push('--from-tree');
-    // Never invented: an absent report stays absent, the same rule the CLI and the prompt carry.
-    if (typeof testReport === 'string' && testReport.trim() !== '') base.push('--test-report', testReport);
-  } else {
-    // Output travels via a temp file — 1MB-class payloads must not ride argv.
-    tmp = path.join(os.tmpdir(), `hone-editor-output-${Date.now()}-${process.pid}.txt`);
-    fsSync.writeFileSync(tmp, output, 'utf8');
-    base.push('--file', tmp);
-  }
-
   try {
+    if (fromTree) {
+      base.push('--from-tree');
+      // Never invented: an absent report stays absent, the same rule the CLI and the prompt carry.
+      if (typeof testReport === 'string' && testReport.trim() !== '') base.push('--test-report', testReport);
+    } else {
+      // Output travels via a temp file — 1MB-class payloads must not ride argv. HC-GF-304-followup-1: in a
+      // directory only this call created (mode 0700). The old pid-named file could not collide, but its
+      // name was predictable in a shared /tmp. Created inside the `try` so a failed write removes it too.
+      tmp = privateTempFile('hone-editor-output', 'output.txt');
+      fsSync.writeFileSync(tmp.file, output, 'utf8');
+      base.push('--file', tmp.file);
+    }
+
     const r = await module.exports._internal.runHone(base, { cwd });
     if (r.error) return { isError: true, detail: r.error };
     const data = parseLastJson(r.stdout);
@@ -209,7 +215,7 @@ async function submitStep({ runId, stepKey, output, contractVersion = '1', fromT
         : (r.stderr || r.stdout || 'submission failed').slice(0, 500),
     };
   } finally {
-    if (tmp) { try { fsSync.unlinkSync(tmp); } catch { /* best-effort cleanup */ } }
+    if (tmp) tmp.remove(); // the directory, not just the file; never throws
   }
 }
 

package/lib/private-temp.js

@@ -12,6 +12,13 @@
  * 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.
+ *
+ * HC-CI-081: `remove` is a recursive delete of a computed path in a root every process of this user shares, so
+ * it deletes only a directory shaped like the one `mkdtempSync` made for it: a direct child of the temp root,
+ * named `<prefix>-` plus mkdtemp's six characters. On 2026-09-26 a local mutation run replaced the mkdtemp with
+ * `os.tmpdir()` and left `remove` as it was, so each call was `rm -rf $TMPDIR`. It ran outside the sandbox, in
+ * the tmpdir the self-hosted runners share, and deleted three other tests' directories mid-run on runner 2
+ * (HC-CI-063's, HC-CI-064's and HC-GF-098's; run 36211682382, attempt 1).
  */
 
 const fs = require('node:fs');
@@ -21,14 +28,25 @@ 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
+ * @returns {{ file: string, remove: () => void }}  `remove` deletes the directory and never throws; a directory
+ *   it did not make is left alone
  */
 function privateTempFile(prefix, name) {
-  const dir = fs.mkdtempSync(path.join(os.tmpdir(), `${prefix}-`));
+  const root = path.resolve(os.tmpdir());
+  const dir = fs.mkdtempSync(path.join(root, `${prefix}-`));
   return {
     file: path.join(dir, name),
-    remove: () => { try { fs.rmSync(dir, { recursive: true, force: true }); } catch { /* best-effort */ } },
+    remove: () => {
+      if (!madeBy(root, prefix, dir)) return;
+      try { fs.rmSync(dir, { recursive: true, force: true }); } catch { /* best-effort */ }
+    },
   };
 }
 
+/** Whether `dir` is what `mkdtempSync(path.join(root, prefix + '-'))` returns: that prefix, six more characters. */
+function madeBy(root, prefix, dir) {
+  const base = path.basename(dir);
+  return path.dirname(dir) === root && base.startsWith(`${prefix}-`) && base.length === prefix.length + 7;
+}
+
 module.exports = { privateTempFile };

package/lib/run-target.js

@@ -94,4 +94,69 @@ async function resolveRunTarget({ client, idOrStory, repoName, flag }) {
   };
 }
 
-module.exports = { resolveRunTarget, isRunId, LOOKUP_LIMIT };
+/**
+ * HC-GF-270-followup-1 — what a caller-supplied argument must look like before any verb builds a URL
+ * from it. HC-GF-270 checked the step key inline in two verbs; five more verbs took a run id, a step key
+ * or an attempt that nothing checked. Encoding alone is not enough: `encodeURIComponent('..') === '..'`,
+ * and axios resolves the request path with `new URL()`, which collapses dot segments, so
+ * `/orchestrate/../verdict` goes out as `/verdict`.
+ */
+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;
+
+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: '' },
+};
+
+/**
+ * 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
+ *   `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.
+ */
+function runArgsError(checks) {
+  for (const { label, kind, value, optional } of checks) {
+    if (optional && value === undefined) continue;
+    const k = KINDS[kind];
+    if (!k) throw new TypeError(`runArgsError: unknown kind ${JSON.stringify(kind)}`);
+    // JSON.stringify: a crafted value's control characters are escaped, never printed raw to the terminal.
+    if (!k.ok(value)) return `${label} ${k.why} (got ${JSON.stringify(value === undefined ? null : value)})${k.hint}`;
+  }
+  return null;
+}
+
+/**
+ * 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.
+ *
+ * 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.
+ */
+function orchestratePath(segments, query) {
+  if (!Array.isArray(segments) || segments.length === 0) throw new TypeError('orchestratePath: segments must be a non-empty array');
+  const parts = segments.map((v, i) => {
+    if (v === null || v === undefined) throw new TypeError(`orchestratePath: segment ${i} is ${v}`);
+    const s = String(v);
+    if (s === '' || s === '.' || s === '..') throw new TypeError(`orchestratePath: segment ${i} is ${JSON.stringify(s)}`);
+    return encodeURIComponent(s);
+  });
+  const base = ['', 'orchestrate', ...parts].join('/');
+  const qs = new URLSearchParams();
+  for (const [k, v] of Object.entries(query || {})) {
+    if (v === null || v === undefined || v === false || v === '') continue;
+    qs.append(k, String(v));
+  }
+  const q = qs.toString();
+  return q ? `${base}?${q}` : base;
+}
+
+module.exports = {
+  resolveRunTarget, isRunId, LOOKUP_LIMIT,
+  isStepKey, isAttempt, isBatchId, runArgsError, orchestratePath,
+};

package/lib/server-banner.js

@@ -0,0 +1,19 @@
+'use strict';
+
+/**
+ * HC-LC-004 banner, with a third state (HC-GF-328).
+ *
+ * `health` is the parsed `/health` body, or null when the server did not answer. The
+ * banner used to print PROD / THIS RUN COSTS MONEY for null, so an unreachable
+ * 127.0.0.1 was announced as a paid production run, and the run then failed with
+ * ECONNREFUSED. A server that did not answer is named as such: nothing about its cost
+ * or provider is known, so the line keeps HC-LC-004's safe default: assume it costs money.
+ */
+function serverBanner(apiUrl, health) {
+  if (!health) return `UNREACHABLE ${apiUrl} · /health did not answer · provider unknown · if this run starts, assume it COSTS MONEY`;
+  const llm = health.llm || null;
+  if (llm && llm.local) return `LOCAL  ${apiUrl} · provider claude_cli · no paid fallback · this run costs $0.00`;
+  return `PROD   ${apiUrl} · provider ${llm ? llm.primary : 'unknown'} · THIS RUN COSTS MONEY`;
+}
+
+module.exports = { serverBanner };

package/lib/setup-dry-run.js

@@ -0,0 +1,29 @@
+'use strict';
+
+/**
+ * HC-GF-320: what `hone setup --dry-run` would do AFTER the setup script.
+ *
+ * The script honours --dry-run itself; the CLI phases that follow it did not.
+ * A dry run installed CLAUDE.md, rewrote an existing .pipeline-config.yml
+ * (platform grounding), installed test packages (--install-tests) and PUT
+ * branch protection on the default branch through the GitHub API. The CLI
+ * now stops after the script on a dry run and prints these lines instead.
+ *
+ * Pure: every fact is passed in, so the plan is testable without a server.
+ */
+function postScriptDryRunPlan({ claudeMdTemplate, claudeMdExists, configExists, installTests, skipBranchProtection }) {
+  const lines = [];
+  if (claudeMdTemplate) {
+    lines.push(claudeMdExists
+      ? 'CLAUDE.md already exists — would skip it'
+      : 'Would install CLAUDE.md (Claude Code pipeline context)');
+  }
+  if (configExists) lines.push('Would re-run platform grounding on .github/.pipeline-config.yml');
+  if (installTests) lines.push('Would install a unit test framework (--install-tests)');
+  lines.push(skipBranchProtection
+    ? 'Would skip branch protection (opted out)'
+    : 'Would install GitHub branch protection on the default branch (pass --no-branch-protection to skip)');
+  return lines;
+}
+
+module.exports = { postScriptDryRunPlan };

package/package.json

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