@hone-ai/cli 1.28.0 → 1.29.1

package/README.md

@@ -0,0 +1,90 @@
+# @hone-ai/cli
+
+**Hone AI runs an 18-stage AI SDLC pipeline over your repository.** You describe a story; the
+pipeline grooms it, plans the implementation against your real code, writes failing tests, builds,
+reviews for logic and security, and hands you a pull request to review like any other.
+
+The orchestration, prompts and skills run on Hone's server. This CLI is the client.
+
+## Install
+
+```bash
+npm install -g @hone-ai/cli
+hone init --token <YOUR_TOKEN>
+```
+
+A token is issued when your organization is provisioned. Without one the CLI installs fine but
+every server-backed command will refuse.
+
+## The three commands that matter
+
+```bash
+hone setup       # detect your stack, write .github/.pipeline-config.yml, install agents + skills
+hone derive      # generate domain skills from YOUR codebase (the part that makes plans specific)
+hone run-story   # run a story through the pipeline
+```
+
+`hone setup` inspects the repository rather than guessing: it finds where your source actually
+lives and writes that into `codebase.source_dirs`, which is what the pipeline uses to ground every
+agent in your real file layout. Check it afterwards with:
+
+```bash
+hone doctor --check source-dirs
+hone detect-layout
+```
+
+If `source_dirs` is wrong the pipeline is grounded on a partial map, so this is worth thirty seconds.
+
+## Running a story
+
+```bash
+hone run-story 412                  # a GitHub issue number
+hone run-story HC-101 --include-paths src/api/orders.js
+```
+
+The run pauses at review gates. Approve or inspect:
+
+```bash
+hone run-story <run-id> --status
+hone show step <run-id> step_1      # what the agent actually produced
+hone run-story <run-id> --approve step_1
+```
+
+## Editor mode
+
+By default the pipeline's generation steps run on Hone's server. In **editor mode** the build step
+runs in your own editor's AI on your own plan, and Hone orchestrates and verifies around it. Set
+`execution.mode: editor` in `.github/.pipeline-config.yml`, then:
+
+```bash
+hone step-instruction <run-id>      # what your editor should execute
+hone submit-step <run-id>           # hand the result back for gating
+```
+
+Hone does not select or provision your editor's plan, and you remain responsible for complying with
+your agreement with that provider.
+
+## Useful extras
+
+```bash
+hone status              # pipeline state for a story
+hone workflows           # in-flight runs
+hone usage               # your org's token usage against its budget
+hone doctor              # repo health checks
+hone billing             # subscription status
+```
+
+`hone --help` lists the full command surface.
+
+## Requirements
+
+Node.js 20 or newer, and a git repository.
+
+## Support
+
+`hone doctor` first — it catches most configuration problems and tells you the fix. Beyond that,
+contact the person who issued your token.
+
+## License
+
+UNLICENSED. Proprietary; use is governed by your agreement with Hone AI.

package/hone-cli.js

@@ -1463,7 +1463,16 @@ program
     console.log(`Stack: ${stack} | Repo: ${repoName}`);
 
     // 2. Bundle source files
-    const sourceDirs = pipelineConfig?.source_dirs || ['src/'];
+    // HC-DF-002: was `pipelineConfig?.source_dirs || ['src/']`. With setup's hardcoded `src/`
+    // on a repo that has no src/, every dir failed the existsSync below and derive bundled ZERO
+    // files — the flagship IP flow generating skills from nothing, silently. readSourceDirs now
+    // drops dead entries and detects the real layout, so derive sees code even on a stale config.
+    const _sd = require('./lib/pipeline-config').readSourceDirs(repoRoot);
+    const sourceDirs = (_sd.source_dirs.length ? _sd.source_dirs : (pipelineConfig?.source_dirs || ['src/']));
+    if (_sd.repaired) {
+      console.log(`  → source dirs repaired: ${_sd.dropped.join(', ')} not on disk → using ${sourceDirs.join(', ')}${_sd.detected ? ' (detected)' : ''}`);
+      console.log('     Fix it permanently: set codebase.source_dirs in .github/.pipeline-config.yml');
+    }
     const files      = {};
     const maxFiles   = parseInt(opts.maxFiles);
     let fileCount    = 0;
@@ -3092,6 +3101,32 @@ program
 // Health checks for the adopter repo. First subcheck: docs freshness (catches
 // drifted README test-count badges). Future subchecks (H-018, H-021) plug into
 // the same `--check <name>` switch.
+program
+  .command('detect-layout')
+  .description('Print the detected source/test directories and framework for this repo as JSON (used by hone setup)')
+  .option('--json', 'JSON output (default)')
+  .action(() => {
+    // HC-DF-002: setup-ai-pipeline.sh is bash and used to HARDCODE `source_dirs: src/` for every
+    // Node repo. Detection belongs in a testable node module; the script shells out to this.
+    try {
+      const { execSync } = require('child_process');
+      const { gitEnv } = require('./lib/git-env');
+      const { detectLayout } = require('./lib/layout-detect');
+      const root = execSync('git rev-parse --show-toplevel', { env: gitEnv(), encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+      const tracked = execSync('git ls-files', { cwd: root, env: gitEnv(), encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).split('\n').filter(Boolean);
+      const fs2 = require('fs'); const path2 = require('path');
+      const d = detectLayout({ root, trackedPaths: tracked });
+      const { detectFrameworks } = require('./lib/layout-detect');
+      const fw = detectFrameworks(tracked, d.manifests, (m) => {
+        try { return fs2.readFileSync(path2.join(root, m), 'utf8'); } catch { return ''; }
+      });
+      process.stdout.write(JSON.stringify({ ...d, ...fw }, null, 2) + '\n');
+    } catch (e) {
+      process.stdout.write(JSON.stringify({ error: String((e && e.message) || e), source_dirs: [], test_dirs: [] }) + '\n');
+      process.exitCode = 1;
+    }
+  });
+
 program
   .command('doctor')
   .description('Run health checks on this repo (docs freshness, etc.)')
@@ -3108,6 +3143,7 @@ program
     // which is the worst doctor outcome ("looks healthy" but
     // actually skipped everything).
     const KNOWN_CHECKS = new Set([
+      'source-dirs',   // HC-DF-002
       'all',
       'docs',
       'admin-merge',
@@ -3115,6 +3151,7 @@ program
       'placeholders',
       'skill-staleness',
       'architecture',
+      'local-run',     // HC-LC-004
     ]);
     if (!KNOWN_CHECKS.has(opts.check)) {
       const known = [...KNOWN_CHECKS].sort().join(', ');
@@ -3178,6 +3215,23 @@ program
       results.push(checkAdminMerge({ repoRoot, lookback: parsedLookback }));
     }
 
+    // HC-DF-002: source_dirs must point at directories that exist — the misconfiguration that
+    // silently guts the repository-structure grounding and `hone derive`.
+    if (opts.check === 'all' || opts.check === 'source-dirs') {
+      const { checkSourceDirs } = require('./lib/doctor-source-dirs');
+      results.push(checkSourceDirs({ repoRoot }));
+    }
+
+    // HC-LC-004: "will a run started now cost me nothing?" Deliberately NOT part of 'all':
+    // it needs a reachable server and spends ~20 tokens of the operator's own subscription
+    // on a live credential probe. That probe is the point — `claude auth status` reported
+    // loggedIn:true through a fully expired token on 2026-09-08, and reported the identical
+    // thing after re-authentication, so the field cannot distinguish the two states.
+    if (opts.check === 'local-run') {
+      const { checkLocalRun } = require('./lib/doctor-local-run');
+      results.push(await checkLocalRun({ apiUrl: getConfig().apiUrl }));
+    }
+
     // HC-002: bind-default check (per E13-A-L1; security-flagged per SC-006-L1)
     if (opts.check === 'all' || opts.check === 'bind-default') {
       const { checkBindDefault } = require('./lib/doctor-bind-default');
@@ -5552,6 +5606,8 @@ program
   .option('--approve <step>', 'Approve a paused gate (e.g., --approve step_0). Exit codes: 2 = paused at a human gate, 3 = parked for your editor (execution.mode: editor)')
   .option('--format <fmt>', 'Output format: pretty or json', 'pretty')
   .option('--poll-interval <s>', 'Poll interval in seconds', '5')
+  .option('--story-file <path>', 'HC-GF-010: read the story text from a local file. Skips the GitHub-issue and Hone-roadmap lookups entirely, so a repo with neither can still run the pipeline.')
+  .option('--description <text>', 'HC-GF-010: the story text, inline. Same effect as --story-file.')
   .option('--include-paths <paths>', 'Comma-separated list of source file paths to bundle into the codebase context (HC-019n-followup-12). Augments auto-detected paths from the issue body.')
   .option('--e2e-specs', 'HC-019n-followup-28: force step_3b (Playwright spec generation) ON for this run (overrides e2e.spec_generation config)')
   .option('--skip-e2e-specs', 'HC-019n-followup-28: force step_3b (Playwright spec generation) OFF for this run (overrides e2e.spec_generation config)')
@@ -5559,6 +5615,23 @@ program
     const config = getConfig();
     const client = api(config);
 
+    // HC-LC-004: the FIRST line, before any other diagnostic, naming which server this run
+    // will use and what it will spend. Sourced from the server's /health, NEVER from
+    // `config` — a banner computed client-side prints whatever this shell believes, which
+    // is exactly the belief that is wrong when it matters. `getConfig` has resolved the API
+    // URL at :48 since forever and never printed it, so ~12 diagnostic lines could scroll
+    // past without once naming the target. That is the silent-wrong-result class that made
+    // 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`);
+      }
+    } catch { /* never block a run on a banner */ }
+
     // Resolve: if it looks like a UUID, use as runId directly.
     // Otherwise treat as storyId — will be used for POST /orchestrate body.
     const isUuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(storyIdOrRunId);
@@ -5597,6 +5670,17 @@ program
           console.log(`Approve: hone run-story ${data.runId} --approve ${data.currentStep}`);
         }
         console.log('');
+        // HC-GF-016: at a TERMINAL state, print the report unasked. The whole
+        // point is that the operator should not have to remember to ask — the
+        // action items are what get lost in the scrollback. Best-effort: a
+        // rendering problem must never change what `--status` reports.
+        if (['completed', 'failed', 'killed'].includes(data.status)) {
+          try {
+            const { buildReport, renderReport } = require('./lib/run-report');
+            console.log(renderReport(buildReport(data)));
+            console.log('');
+          } catch { /* the status above is the contract; this is an extra */ }
+        }
       } catch (e) {
         console.error(`Failed: ${e.response?.data?.error || e.message}`);
         process.exit(1);
@@ -5665,7 +5749,47 @@ program
     const orchestrateConfig = {};
     let issueBodyForFiles = null;
     let resolvedStoryId = storyIdOrRunId; // canonical id for architect-config lookup
-    if (/^\d+$/.test(storyIdOrRunId)) {
+    // HC-GF-010: an EXPLICIT story source, and the only one that works on a repository
+    // that is neither a GitHub issue tracker nor listed on Hone's own roadmap.
+    //
+    // Why this exists: story text reached step_0 from exactly two places — a numeric GitHub
+    // issue, or `GET /stories/:id/context` against Hone's server-side roadmap behind a
+    // fail-closed org allowlist. On any other product every story id 404s, and the CLI
+    // WARNS AND PROCEEDS, so step_0 grooms a story it never received. That is the
+    // documented cause of the placeholder cascades, and it is why FlowForge's 33
+    // pre-written stories in hone/*.issue.md could not be run at all.
+    //
+    // It SHORT-CIRCUITS both lookups rather than merely winning a precedence contest: with
+    // an explicit description the 404-and-proceed path cannot fire, so the operator can
+    // never be told "no roadmap row found" about a story they just handed us.
+    let explicitStory = null;
+    if (opts.storyFile) {
+      const p = path.resolve(opts.storyFile);
+      try {
+        explicitStory = fs.readFileSync(p, 'utf8');
+      } catch (e) {
+        console.error(`✗ --story-file: cannot read ${p} — ${e.message}`);
+        process.exit(1);
+      }
+      if (!explicitStory.trim()) {
+        console.error(`✗ --story-file: ${p} is empty. A blank story would groom to placeholders.`);
+        process.exit(1);
+      }
+    } else if (opts.description) {
+      explicitStory = String(opts.description);
+      if (!explicitStory.trim()) {
+        console.error('✗ --description is empty. A blank story would groom to placeholders.');
+        process.exit(1);
+      }
+    }
+
+    if (explicitStory) {
+      orchestrateConfig.story_description = explicitStory;
+      issueBodyForFiles = explicitStory;
+      console.log(
+        `  → story text from ${opts.storyFile ? path.relative(process.cwd(), path.resolve(opts.storyFile)) : '--description'} ` +
+        `(${explicitStory.length} chars) — roadmap and issue lookups skipped`);
+    } else if (/^\d+$/.test(storyIdOrRunId)) {
       try {
         const remoteUrl = execSync('git remote get-url origin', { encoding: 'utf8' }).trim();
         const m = remoteUrl.match(/[/:]([^/]+)\/([^/]+?)(?:\.git)?$/);
@@ -5944,6 +6068,13 @@ program
       const { readSourceDirs } = require('./lib/pipeline-config');
       const tracked = execSync('git ls-files', { cwd: process.cwd(), env: gitEnv(), encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).split('\n').filter(Boolean);
       const dirs = readSourceDirs(process.cwd());
+      // HC-DF-002: readSourceDirs self-heals a stale config; say so, or the operator sees a
+      // confident success line built from directories that do not exist.
+      if (dirs.repaired) {
+        console.log(`  ⚠ source dirs in .pipeline-config.yml not found on disk: ${dirs.dropped.join(', ')}`);
+        console.log(`     using ${dirs.detected ? 'detected' : 'the surviving'} dirs instead: ${dirs.source_dirs.join(', ') || '(none)'}`);
+        console.log('     fix it permanently: hone detect-layout, then set codebase.source_dirs in .github/.pipeline-config.yml');
+      }
       const tree = buildRepoTree(tracked, { sourceDirs: dirs.source_dirs, testDirs: dirs.test_dirs });
       if (tree.selected_total > 0) {
         orchestrateConfig.repo_tree = tree;
@@ -7386,7 +7517,7 @@ program
     const { execFileSync, spawnSync } = require('child_process');
     const os = require('os');
     const { extractFileBlocks, buildDiff, nodeMaterializeIO, MaterializeError } = require('./lib/materialize-diff');
-    const { resolveCommand, verdictFromRun, EXIT } = require('./lib/verify-patch');
+    const { resolveCommand, verdictFromRun, EXIT, resolveAuxGates, classifyGateRun } = require('./lib/verify-patch');
     const { gitEnv } = require('./lib/git-env');
     const config = getConfig();
     const client = api(config);
@@ -7465,6 +7596,10 @@ program
     // HC-019n-followup-34: capture the verdict + HEAD sha for the closed-loop
     // report (--report). Hoisted so they survive the try/finally to the POST.
     let reportVerdict = null, reportDetail = null, headSha = null;
+    // HC-GF-026: measured verdicts for the gates step_4 asserts. Hoisted so they
+    // survive the try/finally to the --report POST, exactly like reportVerdict.
+    const reportGates = [];
+    const ciCfg = require('./lib/pipeline-config').readCIConfigDetails(process.cwd());
     try { headSha = execFileSync('git', ['rev-parse', 'HEAD'], { cwd: process.cwd(), env: gitEnv(), encoding: 'utf8' }).trim(); } catch { /* best-effort */ }
     try {
       execFileSync('git', ['worktree', 'add', '--detach', wt, 'HEAD'],
@@ -7504,11 +7639,69 @@ program
         const timedOut = run.error && run.error.code === 'ETIMEDOUT';
         const v = verdictFromRun({ code: run.status, timedOut, stdout: run.stdout, stderr: run.stderr });
         const sym = v.verdict === 'pass' ? '✓' : v.verdict === 'timeout' ? '⏱' : '✗';
+
+        // HC-GF-023: on a failure the operator needs the OUTPUT, not a quote from it.
+        // The full log is written OUTSIDE the worktree (cleanup removes the worktree)
+        // and its path is named, so diagnosing does not require re-running by hand.
+        let logPath = null;
+        if (v.verdict !== 'pass') {
+          try {
+            logPath = path.join(os.tmpdir(), `hone-verify-${workflowId.slice(0, 8)}-${opts.stepKey}.log`);
+            fs.writeFileSync(logPath,
+              `$ ${command}\n(cwd: isolated worktree from HEAD ${headSha || 'unknown'})\n\n` +
+              `${run.stdout || ''}\n${run.stderr || ''}\n`);
+          } catch { logPath = null; }
+        }
+
+        let pretty = `${sym} ${v.detail}\n  (command: ${command})`;
+        if (v.failure && v.failure.excerpt && v.failure.excerpt.length) {
+          pretty += `\n  ── last ${v.failure.excerpt.length} lines ──\n`
+            + v.failure.excerpt.map(l => `  │ ${l}`).join('\n');
+        }
+        if (logPath) pretty += `\n  full output: ${logPath}`;
+        if (v.verdict !== 'pass') pretty += `\n  inspect the tree: re-run with --keep`;
+
         emit(
-          { ok: v.verdict === 'pass', verdict: v.verdict, command, detail: v.detail },
-          `${sym} ${v.detail}\n  (command: ${command})`);
+          { ok: v.verdict === 'pass', verdict: v.verdict, command, detail: v.detail,
+            failureCount: v.failure ? v.failure.count : undefined, logPath: logPath || undefined },
+          pretty);
         exitCode = v.exitCode;
         reportVerdict = v.verdict; reportDetail = v.detail;
+
+        // ── HC-GF-026: run the gates step_4 only CLAIMED to run ──────────────
+        // step_4 emitted `$ ruff check … All checks passed!` for a command it
+        // cannot execute, and step_5 repeated it as `STANDARDS: Clean`. These
+        // run in the SAME worktree, on the SAME applied diff, so there is a
+        // measured verdict to set against the asserted one.
+        //
+        // REPORTED, NOT BLOCKING: exitCode is untouched. A lint finding must not
+        // veto a build whose tests pass — that would silently change what
+        // verify-patch's exit code means for every existing adopter, and style
+        // is not correctness. `unavailable` is a third verdict on purpose: a
+        // missing linter must never read as a failing one.
+        try {
+          for (const gate of resolveAuxGates({ configured: ciCfg, cwd: process.cwd() })) {
+            const gr = spawnSync(gate.command, {
+              cwd: wt, shell: true, encoding: 'utf8',
+              timeout: Number(opts.timeout) * 1000, env: gitEnv(),
+              stdio: ['ignore', 'pipe', 'pipe'],
+            });
+            const c = classifyGateRun({
+              code: gr.status, error: gr.error,
+              timedOut: gr.error && gr.error.code === 'ETIMEDOUT',
+              stdout: gr.stdout, stderr: gr.stderr,
+            });
+            reportGates.push({ name: gate.name, command: gate.command, source: gate.source,
+                               verdict: c.verdict, detail: c.detail });
+            if (opts.format !== 'json') {
+              const gsym = c.verdict === 'pass' ? '✓' : c.verdict === 'fail' ? '✗' : '○';
+              console.log(`  ${gsym} ${gate.name}: ${c.verdict} — ${c.detail}  (${gate.command}, via ${gate.source})`);
+              for (const l of (c.verdict === 'fail' ? (c.excerpt || []) : [])) console.log(`    │ ${l}`);
+            }
+          }
+        } catch (e) {
+          if (opts.format !== 'json') console.warn(`  ⚠ aux gates skipped (${e.message})`);
+        }
       }
     } catch (e) {
       emit({ ok: false, verdict: 'error', detail: e.message },
@@ -7532,6 +7725,7 @@ program
           detail: reportDetail,
           attempt: opts.attempt ? Number(opts.attempt) : undefined,
           headSha,
+          gates: reportGates.length ? reportGates : undefined,
         });
         if (opts.format !== 'json') console.log(`  → reported verdict '${reportVerdict}' to the server (advisory)`);
       } catch (e) {
@@ -7541,6 +7735,30 @@ program
     process.exit(exitCode);
   });
 
+// ── HC-GF-016: run-report — what happened, and what still needs you ──────────
+// Derived, never narrated. See cli/lib/run-report.js for why that matters.
+program
+  .command('run-report <runId>')
+  .description('What happened on a run, and what still needs you')
+  .option('--format <fmt>', 'Output format: pretty or json', 'pretty')
+  .action(async (runId, opts) => {
+    const { buildReport, renderReport } = require('./lib/run-report');
+    const config = getConfig();
+    const client = api(config);
+    try {
+      const { data } = await client.get(`/orchestrate/${runId}`);
+      const report = buildReport(data);
+      if (opts.format === 'json') console.log(JSON.stringify(report, null, 2));
+      else console.log(renderReport(report));
+      // Exit non-zero when the operator has something to do, so `hone run-report`
+      // is usable as a gate in a script and not merely as prose.
+      process.exit(report.needsYou.length ? 1 : 0);
+    } catch (e) {
+      console.error(`run-report failed: ${e.response?.data?.error || e.message}`);
+      process.exit(1);
+    }
+  });
+
 // ── HC-019n-followup-25: emit-pr (pipeline-recovery condition 7) ──────────────
 // Condition 6 proved step_4's diff applies AND its tests pass in isolation.
 // Condition 7 turns that verified diff into the reviewable artifact: a branch

package/lib/doctor-local-run.js

@@ -0,0 +1,183 @@
+'use strict';
+/**
+ * doctor-local-run.js — HC-LC-004. "Will a run started right now cost me nothing?"
+ *
+ * THE DESIGN CONSTRAINT THAT SHAPED THIS, learned on 2026-09-08: `claude auth status --json`
+ * reported `loggedIn: true`, `authMethod: claude.ai` and `subscriptionType: max` while every
+ * real call returned `401 OAuth access token has expired`. Then, after re-authentication, it
+ * reported EXACTLY THE SAME THING. The field is identical whether the credentials work or
+ * not, so a check built on it would have been green through a completely broken state.
+ *
+ * Therefore this check PROBES. It spends about 20 tokens of the operator's own subscription
+ * to learn something no status field can tell it. That is the correct trade: 20 tokens
+ * against a run that dies at step 1, or worse, silently completes on a metered key.
+ *
+ * The two questions it answers, both of which cost money to get wrong:
+ *   1. Am I pointed at a server that will run locally, or at production?
+ *   2. Do my local credentials actually WORK, right now?
+ */
+
+const { execFile } = require('child_process');
+
+const PROBE_TIMEOUT_MS = 60_000;
+
+/** Ask the server what it will spend on. The answer must come from the server, never config. */
+async function fetchHealth(apiUrl, fetchImpl) {
+  const f = fetchImpl || globalThis.fetch;
+  const res = await f(`${apiUrl.replace(/\/$/, '')}/health`, { method: 'GET' });
+  if (!res.ok) throw new Error(`/health returned ${res.status}`);
+  return res.json();
+}
+
+/**
+ * Spend ~20 tokens to prove the credentials work. Resolves {ok, detail}.
+ * Injectable so tests never touch the real binary.
+ */
+function probeLocalClaude(bin, execImpl) {
+  const run = execImpl || execFile;
+  return new Promise((resolve) => {
+    const env = { ...process.env };
+    for (const n of ['ANTHROPIC_API_KEY', 'ANTHROPIC_AUTH_TOKEN', 'ANTHROPIC_BASE_URL',
+                     'CLAUDE_CODE_USE_BEDROCK', 'CLAUDE_CODE_USE_VERTEX']) delete env[n];
+
+    const child = run(bin, ['-p', '--output-format', 'json', '--model', 'claude-haiku-4-5'],
+      { env, timeout: PROBE_TIMEOUT_MS },
+      (err, stdout) => {
+        let env2;
+        try { env2 = JSON.parse(stdout); } catch {
+          return resolve({ ok: false, detail: err ? String(err.message).slice(0, 160) : 'unparseable probe output' });
+        }
+        if (env2.is_error === true) {
+          const status = env2.api_error_status;
+          const msg = String(env2.result || '').slice(0, 160);
+          if (status === 401 || status === 403 || /authenticate|expired|oauth/i.test(msg)) {
+            return resolve({ ok: false, kind: 'auth', detail: msg });
+          }
+          if (status === 429 || /rate.?limit|usage limit/i.test(msg)) {
+            return resolve({ ok: false, kind: 'rate_limit', detail: msg });
+          }
+          return resolve({ ok: false, kind: 'api', detail: msg });
+        }
+        resolve({ ok: true, model: Object.keys(env2.modelUsage || {})[0] || null });
+      });
+    try { child.stdin && child.stdin.end('hi'); } catch { /* the callback reports it */ }
+  });
+}
+
+/**
+ * @returns {{name:'local-run', status:'ok'|'drift'|'info', examined:number, reason:string, suggestedFix?:string}}
+ *
+ * FIELD NAMES ARE A CONTRACT, not a preference. The doctor renderer at cli/hone-cli.js
+ * prints `${icon} ${r.name} — ${r.reason}` and then `Fix: ${r.suggestedFix}`. A check that
+ * returns `summary`/`detail` renders as "✓ undefined — undefined" and its remediation is
+ * never shown. HC-GF-001 documented exactly that defect in checkSourceDirs on 2026-09-07 —
+ * and this check reproduced it verbatim on its first real run, which is why the contract is
+ * now pinned by a test rather than remembered.
+ *
+ * `examined` is mandatory per HC-GF-005 — a result that examined nothing may not report ok.
+ */
+async function checkLocalRun(opts = {}) {
+  const apiUrl = opts.apiUrl;
+  const examined = [];
+
+  let health;
+  try {
+    health = await fetchHealth(apiUrl, opts.fetchImpl);
+    examined.push('server /health');
+  } catch (e) {
+    return {
+      name: 'local-run', status: 'drift', examined: examined.length,
+      reason: `cannot reach ${apiUrl} — is the local server running?`,
+      suggestedFix: `Start it with: make services.up && (cd server && npm start). Error: ${e.message}`,
+    };
+  }
+
+  const llm = health.llm || {};
+
+  // Question 1: which server am I on, and what will it spend?
+  if (!llm.local) {
+    return {
+      name: 'local-run', status: 'info', examined: examined.length,
+      reason: `${apiUrl} runs on ${llm.primary || 'a metered provider'} — a run started now COSTS MONEY`,
+      suggestedFix: 'This is correct for Path A. For a free local run, point HONE_API at your local ' +
+              'server and start it with HONE_LOCAL_CLAUDE=1 and NODE_ENV=development.',
+    };
+  }
+  examined.push('provider identity');
+
+  if (llm.fallback_disabled !== true) {
+    return {
+      name: 'local-run', status: 'drift', examined: examined.length,
+      reason: 'the local provider is active but a paid fallback is still reachable',
+      suggestedFix: 'A local failure could silently complete on a metered provider. The provider ' +
+              'array must be REPLACED when armed, not prepended (HC-LC-003).',
+    };
+  }
+  examined.push('fallback disabled');
+
+  // A metered credential visible to the child is not fatal — the provider scrubs it — but the
+  // operator should know their shell carries one.
+  if (llm.auth && llm.auth.api_key_visible) {
+    examined.push('credential hygiene');
+  }
+
+  // Question 2: do the credentials actually WORK? The status field cannot answer this.
+  if (opts.skipProbe) {
+    return {
+      name: 'local-run', status: 'info', examined: examined.length,
+      reason: 'server is local and fallback is disabled; credentials NOT probed',
+      suggestedFix: 'Re-run without --skip-probe to spend ~20 tokens proving the credentials work. ' +
+              'auth status alone is not evidence: it reported loggedIn true through a fully ' +
+              'expired token on 2026-09-08.',
+    };
+  }
+
+  const bin = opts.bin || process.env.HONE_LOCAL_CLAUDE_BIN;
+  if (!bin) {
+    return {
+      name: 'local-run', status: 'drift', examined: examined.length,
+      reason: 'HONE_LOCAL_CLAUDE_BIN is not set in this shell, so the credentials cannot be probed',
+      suggestedFix: 'Set it to the absolute path of your `claude` binary (`which claude`).',
+    };
+  }
+
+  const probe = await probeLocalClaude(bin, opts.execImpl);
+  examined.push('live credential probe');
+
+  if (!probe.ok) {
+    if (probe.kind === 'auth') {
+      return {
+        name: 'local-run', status: 'drift', examined: examined.length,
+        reason: 'local credentials are NOT working — a run started now would fail at step 0',
+        suggestedFix: `Run: claude auth login --claudeai\n  The probe said: ${probe.detail}\n  ` +
+                'Note `claude auth status` reports loggedIn true in this state — it reports ' +
+                'that credentials exist, not that they work.',
+      };
+    }
+    if (probe.kind === 'rate_limit') {
+      return {
+        name: 'local-run', status: 'info', examined: examined.length,
+        reason: 'your subscription window is currently exhausted — a run would park, not fail',
+        suggestedFix: `Wait for the window to refill and resume. The probe said: ${probe.detail}`,
+      };
+    }
+    return {
+      name: 'local-run', status: 'drift', examined: examined.length,
+      reason: 'the local provider could not complete a probe call',
+      suggestedFix: probe.detail,
+    };
+  }
+
+  return {
+    name: 'local-run', status: 'ok', examined: examined.length,
+    reason: 'a run started now costs $0.00 and cannot reach a paid provider',
+    suggestedFix: `server: ${apiUrl} · provider: claude_cli · fallback: disabled · ` +
+            `probe: ok${probe.model ? ` (${probe.model})` : ''}` +
+            (llm.auth && llm.auth.api_key_visible
+              ? '\n  Note: a metered API key is visible in this shell. The provider scrubs it ' +
+                'from the child, but you may want it unset.'
+              : ''),
+  };
+}
+
+module.exports = { checkLocalRun, probeLocalClaude, fetchHealth };