@hone-ai/cli 1.25.0 → 1.27.0

package/hone-cli.js

@@ -17,6 +17,7 @@
  */
 
 const { Command } = require('commander');
+const { isEditorParked, editorParkedGuidance, currentStep, EDITOR_PARKED_EXIT_CODE } = require('./lib/editor-park'); // HC-COMM-010-followup-1
 const axios        = require('axios');
 const fs           = require('fs');
 const path         = require('path');
@@ -2385,6 +2386,19 @@ program
       const { isEditorStubbedAgent, editorStubContent } = require('./lib/editor-stub');
       const { readExecutionMode } = require('./lib/pipeline-config');
       const syncExecutionMode = readExecutionMode(process.cwd());
+      // HC-COMM-010-followup-3: in editor mode, register the Hone MCP server for
+      // Claude Code by writing a project-scoped .mcp.json (merge, never clobber).
+      // Replaces the manual `claude mcp add hone -- hone-mcp` runbook step.
+      try {
+        const { ensureClaudeMcpConfig, MCP_FILE, FALLBACK_LINE } = require('./lib/mcp-config');
+        const mcp = ensureClaudeMcpConfig(process.cwd(), { mode: syncExecutionMode });
+        if (mcp.action === 'written' || mcp.action === 'updated') console.log(`  ✓ Registered the Hone MCP server for Claude Code in ${MCP_FILE} (commit it; Claude Code asks once to approve project servers)`);
+        else if (mcp.action === 'skipped' && syncExecutionMode === 'editor') console.log(`  ⚠ ${mcp.reason}`);
+        else if (mcp.action === 'unchanged') console.log(`  ✓ Hone MCP server already registered in ${MCP_FILE}`);
+        void FALLBACK_LINE;
+      } catch (e) {
+        console.log(`  ⚠ MCP registration skipped (non-fatal): ${e.message}`);
+      }
 
       let synced = 0;
       for (const agent of agents) {
@@ -5535,7 +5549,7 @@ program
   .option('--status', 'Show status of the latest workflow run for this story')
   .option('--kill', 'Kill the latest workflow run for this story')
   .option('--axes <axes>', 'Comma-separated classifier axes for this run (e.g. shared-chokepoint) — composition input (HC-COMM-010 C0)')
-  .option('--approve <step>', 'Approve a paused gate (e.g., --approve step_0)')
+  .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('--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.')
@@ -5569,9 +5583,15 @@ program
         for (const s of (data.steps || [])) {
           const icon = s.status === 'completed' ? '✓' : s.status === 'running' ? '⏳' : s.status === 'failed' ? '✗' : '⬜';
           const gate = s.gateResult ? ` (${s.gateResult})` : '';
-          console.log(`  ${icon} ${s.stepKey}  (${s.agent})  ${s.status}${gate}`);
+          // HC-019n-followup-40: one line per step = its CURRENT state; a retried
+          // step says so instead of listing a stale failed row above a completed one.
+          const tries = (s.attempts || 1) > 1 ? `  [attempt ${s.attempt} of ${s.attempts}]` : '';
+          console.log(`  ${icon} ${s.stepKey}  (${s.agent})  ${s.status}${gate}${tries}`);
         }
-        if (data.awaitingApproval) {
+        if (data.awaitingApproval && isEditorParked(data)) {
+          console.log('');
+          console.log(editorParkedGuidance(data.runId, data.currentStep, currentStep(data)?.agent));
+        } else if (data.awaitingApproval) {
           console.log('');
           console.log(`Awaiting approval at ${data.currentStep}.`);
           console.log(`Approve: hone run-story ${data.runId} --approve ${data.currentStep}`);
@@ -5877,6 +5897,37 @@ program
       console.warn('    Fix: hone run-story <id> --include-paths path/one.js,path/two.js');
     }
 
+    // HC-COMM-010 axes wiring (CLI half): when --axes wasn't given, derive
+    // the DETERMINISTIC axes from the extractors (SC-002) — security labels/
+    // text, cross-repo markers, recently-modified overlap vs the bundled
+    // paths. Judgment axes (shared-chokepoint etc.) come from the groomer at
+    // step_0 and are harvested server-side. Fail-open; explicit --axes wins.
+    if (!opts.axes) {
+      try {
+        const { classifyStory } = require('./lib/story-classifier');
+        const {
+          extractType, extractSecurityImplications, extractCrossRepoDependency, extractRecentlyModifiedOverlap,
+        } = require('./lib/story-classifier-extract');
+        const autoBody = issueBodyForFiles || '';
+        const autoLabels = [];
+        const touched = Array.isArray(orchestrateConfig.codebaseFiles)
+          ? orchestrateConfig.codebaseFiles.map(f => f.path).filter(Boolean)
+          : Object.keys(orchestrateConfig.codebaseFiles || {});
+        const auto = classifyStory({
+          type: extractType(autoLabels, autoBody, String(storyIdOrRunId)),
+          has_security_implications: extractSecurityImplications(autoLabels, autoBody),
+          cross_repo_dependency: extractCrossRepoDependency(autoBody),
+          recently_modified_overlap: extractRecentlyModifiedOverlap(process.cwd(), touched, 14),
+        });
+        if (auto.architect.engage && auto.architect.axes.length > 0) {
+          orchestrateConfig.classifier_axes = auto.architect.axes;
+          console.log(`  → auto-detected classifier axes: ${auto.architect.axes.join(', ')}`);
+        }
+      } catch (e) {
+        console.warn(`  ⚠ axes auto-detection failed (non-fatal): ${(e && e.message || String(e)).split('\n')[0]}`);
+      }
+    }
+
     // HC-101-followup-2: pass the adopter's CI gate config to the
     // orchestrator so step_5c can branch (github / local / both / none).
     // Defaults to gate=github + local_command='make ci' when the config
@@ -6049,6 +6100,12 @@ program
 
         if (status.status === 'paused' && status.awaitingApproval) {
           const step = status.steps.find(s => s.stepKey === status.currentStep);
+          // HC-COMM-010-followup-1: an editor-parked run is a gate the EDITOR
+          // satisfies, not a human — never offer --approve here (B4 refuses it).
+          if (isEditorParked(status)) {
+            console.log(editorParkedGuidance(data.runId, status.currentStep, step?.agent));
+            process.exit(EDITOR_PARKED_EXIT_CODE);
+          }
           console.log(`⏳ Step ${status.currentStep} (${step?.agent || 'unknown'}) — awaiting approval`);
 
           // Interactive prompt
@@ -7296,6 +7353,7 @@ program
   .option('--command <cmd>', 'Test command (default: ci.local_command from config, else `make ci`)')
   .option('--timeout <sec>', 'Seconds before the test command is killed', '600')
   .option('--keep', 'Leave the worktree in place for debugging')
+  .option('--no-provision', 'Do not install/link dependencies into the isolated worktree (HC-COMM-010-followup-6)')
   .option('--report', 'HC-019n-followup-34: report the verdict back to the server (closed loop, advisory)')
   .option('--format <fmt>', 'Output format: pretty or json', 'pretty')
   .action(async (workflowId, opts) => {
@@ -7361,7 +7419,7 @@ program
     const wt = fs.mkdtempSync(path.join(os.tmpdir(), 'hone-verify-'));
     const diffFile = path.join(os.tmpdir(), `hone-verify-${Date.now()}.diff`);
     fs.writeFileSync(diffFile, diff);
-    const command = resolveCommand(opts.command, runConfig?.ci_local_command);
+    const command = resolveCommand(opts.command, runConfig?.ci_local_command, { cwd: process.cwd() }) // followup-7: file re-read + Makefile/npm-aware default;
     let cleanupDone = false;
     const cleanup = () => {
       if (cleanupDone || opts.keep) return;
@@ -7401,6 +7459,16 @@ program
         reportVerdict = 'does_not_apply'; reportDetail = applyDetail;
       } else {
         // 5. Run the adopter's test command in the worktree.
+        // HC-COMM-010-followup-6: a bare worktree has no dependencies — provision it
+        // (link the repo's node_modules when the lockfile is unchanged, else run the
+        // lockfile's install, or ci.install_command). Fail-open; --no-provision opts out.
+        if (opts.provision !== false) {
+          const { planProvision, provisionWorktree } = require('./lib/worktree-provision');
+          const { readCIConfigDetails } = require('./lib/pipeline-config');
+          const plan = planProvision({ worktreeDir: wt, parentDir: process.cwd(), installCommand: readCIConfigDetails(process.cwd()).install_command });
+          const prov = provisionWorktree(plan, { worktreeDir: wt, exec: spawnSync });
+          if (opts.format !== 'json') console.log(`  provisioning: ${prov.summary}`);
+        }
         if (opts.format !== 'json') console.log(`  running: ${command}  (in isolated worktree, timeout ${opts.timeout}s)`);
         const run = spawnSync(command, {
           cwd: wt, shell: true, encoding: 'utf8',
@@ -7466,6 +7534,7 @@ program
   .option('--command <cmd>', 'Test command for --verify (default: ci.local_command, else `make ci`)')
   .option('--timeout <sec>', 'Seconds before the verify test command is killed', '600')
   .option('--keep', 'Leave the worktree in place for debugging')
+  .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) => {
     const { execFileSync, spawnSync } = require('child_process');
@@ -7577,7 +7646,7 @@ program
     const wt = fs.mkdtempSync(path.join(os.tmpdir(), 'hone-emit-'));
     const diffFile = path.join(os.tmpdir(), `hone-emit-${Date.now()}.diff`);
     fs.writeFileSync(diffFile, diff);
-    const command = resolveCommand(opts.command, runConfig?.ci_local_command);
+    const command = resolveCommand(opts.command, runConfig?.ci_local_command, { cwd: process.cwd() }) // followup-7: file re-read + Makefile/npm-aware default;
     // `worktree add -b` creates the branch ref BEFORE apply/verify. If we bail
     // before a successful commit (apply fails, verify fails), that empty branch
     // (pointing at HEAD) must be torn down too — else "a failing diff never
@@ -7622,6 +7691,16 @@ program
         // 4b. Re-verify inline (default) — a failing diff never reaches a branch.
         let verifyOk = true;
         if (doVerify) {
+          // HC-COMM-010-followup-6: a bare worktree has no dependencies — provision it
+          // (link the repo's node_modules when the lockfile is unchanged, else run the
+          // lockfile's install, or ci.install_command). Fail-open; --no-provision opts out.
+          if (opts.provision !== false) {
+            const { planProvision, provisionWorktree } = require('./lib/worktree-provision');
+            const { readCIConfigDetails } = require('./lib/pipeline-config');
+            const plan = planProvision({ worktreeDir: wt, parentDir: process.cwd(), installCommand: readCIConfigDetails(process.cwd()).install_command });
+            const prov = provisionWorktree(plan, { worktreeDir: wt, exec: spawnSync });
+            if (opts.format !== 'json') console.log(`  provisioning: ${prov.summary}`);
+          }
           if (opts.format !== 'json') console.log(`  verifying: ${command}  (in isolated worktree, timeout ${opts.timeout}s)`);
           const run = spawnSync(command, {
             cwd: wt, shell: true, encoding: 'utf8',

package/lib/editor-park.js

@@ -0,0 +1,43 @@
+'use strict';
+/**
+ * editor-park.js — HC-COMM-010-followup-1: recognize a run that is PARKED FOR
+ * THE EDITOR (execution.mode: editor, step awaiting_editor) and say what to do.
+ *
+ * Why: the run-status endpoint reports an editor-parked run as
+ * `paused` + `awaitingApproval: true` (it IS at a gate, just not one a human
+ * approves) — so run-story's poll loop used to print "--approve" guidance,
+ * which the B4 guard then refuses. Detection keys on the CURRENT step's
+ * status, reliable since HC-019n-followup-40 collapsed steps[] to the latest
+ * attempt. Pure: no I/O, no process access — the CLI decides how to exit.
+ */
+const EDITOR_PARKED_EXIT_CODE = 3; // distinct from 2 (paused at a human gate)
+
+function currentStep(status) {
+  if (!status || !Array.isArray(status.steps)) return null;
+  return status.steps.find(s => s && s.stepKey === status.currentStep) || null;
+}
+
+/** @returns {boolean} true when the run is paused because the editor owes output */
+function isEditorParked(status) {
+  if (!status || status.status !== 'paused') return false;
+  const step = currentStep(status);
+  return !!(step && step.status === 'awaiting_editor');
+}
+
+/**
+ * The parked-state copy (ux-copy pass, 2026-09-05): what happened, where it is,
+ * the two ways forward (editor MCP tools / CLI verbs), and the closing step.
+ */
+function editorParkedGuidance(runId, stepKey, agent) {
+  const a = agent ? ` (${agent})` : '';
+  return [
+    `⏸ Parked for your editor at ${stepKey}${a} — this step runs in your editor AI, not on Hone.`,
+    `  In Claude Code:  call hone_step_instruction, build the step there, then hone_submit_step.`,
+    `  From the CLI:    hone step-instruction ${runId}`,
+    `                   … build … then: hone submit-step ${runId} ${stepKey} --file out.md`,
+    `  When submitted:  hone run-story ${runId} --approve ${stepKey}`,
+    `  Guide: docs/runbooks/editor-mode.md`,
+  ].join('\n');
+}
+
+module.exports = { EDITOR_PARKED_EXIT_CODE, isEditorParked, editorParkedGuidance, currentStep };

package/lib/mcp-config.js

@@ -0,0 +1,41 @@
+'use strict';
+/**
+ * mcp-config.js — HC-COMM-010-followup-3: register the Hone MCP server for
+ * Claude Code by writing a PROJECT-scoped `.mcp.json` when the repo runs in
+ * editor mode. Replaces the manual `claude mcp add hone -- hone-mcp` step.
+ *
+ * Contract: merge, never clobber. Other servers in an existing `.mcp.json` are
+ * preserved; only the `hone` entry is added/refreshed; a malformed file is left
+ * untouched (fail-open with a reason). Pure over an injected repoRoot.
+ */
+const fs = require('node:fs');
+const path = require('node:path');
+
+const MCP_FILE = '.mcp.json';
+const HONE_SERVER = Object.freeze({ command: 'hone-mcp', args: [] });
+const FALLBACK_LINE = 'claude mcp add hone -- hone-mcp';
+
+function ensureClaudeMcpConfig(repoRoot, { mode } = {}) {
+  if (mode !== 'editor') return { action: 'skipped', reason: 'execution.mode is not editor' };
+  const file = path.join(repoRoot, MCP_FILE);
+  let doc = { mcpServers: {} };
+  if (fs.existsSync(file)) {
+    try {
+      const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+      if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) throw new Error('not an object');
+      doc = parsed;
+      if (!doc.mcpServers || typeof doc.mcpServers !== 'object' || Array.isArray(doc.mcpServers)) doc.mcpServers = {};
+    } catch (e) {
+      return { action: 'skipped', reason: `${MCP_FILE} is not valid JSON (${e.message}); left untouched — register manually: ${FALLBACK_LINE}` };
+    }
+  }
+  const existing = doc.mcpServers.hone;
+  if (existing && existing.command === HONE_SERVER.command && JSON.stringify(existing.args || []) === '[]') {
+    return { action: 'unchanged', file };
+  }
+  doc.mcpServers.hone = { ...HONE_SERVER, args: [] };
+  fs.writeFileSync(file, JSON.stringify(doc, null, 2) + '\n');
+  return { action: existing ? 'updated' : 'written', file };
+}
+
+module.exports = { ensureClaudeMcpConfig, MCP_FILE, HONE_SERVER, FALLBACK_LINE };

package/lib/pipeline-config.js

@@ -33,7 +33,7 @@ const path = require('node:path');
 const KNOWN_THRESHOLD_KEYS = ['estimate_full_sdlc', 'recently_modified_window_days'];
 
 const CI_GATE_MODES = ['github', 'local', 'both', 'none'];
-const KNOWN_CI_GATE_KEYS = ['gate', 'local_command'];
+const KNOWN_CI_GATE_KEYS = ['gate', 'local_command', 'install_command']; // install_command: HC-COMM-010-followup-6
 const DEFAULT_CI_LOCAL_COMMAND = 'make ci';
 
 /**
@@ -111,6 +111,29 @@ function normalizeCIGate(raw) {
  * @param {string} repoRoot
  * @returns {{ gate: 'github'|'local'|'both'|'none', local_command: string }}
  */
+/**
+ * HC-COMM-010-followup-6/-7: the ci: block details readCIGateConfig deliberately
+ * does not expose (its return shape is pinned): whether local_command was set
+ * EXPLICITLY in the file (vs the `make ci` default), and an optional
+ * install_command used to provision the verification worktree.
+ * @returns {{ local_command: string|null, local_command_explicit: boolean, install_command: string|null }}
+ */
+function readCIConfigDetails(repoRoot) {
+  const none = { local_command: null, local_command_explicit: false, install_command: null };
+  if (!repoRoot || typeof repoRoot !== 'string') return none;
+  for (const p of [path.join(repoRoot, '.pipeline-config.yml'), path.join(repoRoot, '.github/.pipeline-config.yml')]) {
+    if (!fs.existsSync(p)) continue;
+    let parsed;
+    try { parsed = require('js-yaml').load(fs.readFileSync(p, 'utf8')); } catch { continue; }
+    const block = parsed && typeof parsed === 'object' ? parsed.ci : null;
+    if (!block || typeof block !== 'object') continue;
+    const lc = typeof block.local_command === 'string' && block.local_command.trim() ? block.local_command.trim() : null;
+    const ic = typeof block.install_command === 'string' && block.install_command.trim() ? block.install_command.trim() : null;
+    return { local_command: lc, local_command_explicit: lc !== null, install_command: ic };
+  }
+  return none;
+}
+
 function readCIGateConfig(repoRoot) {
   const defaults = { gate: 'github', local_command: DEFAULT_CI_LOCAL_COMMAND };
   if (!repoRoot || typeof repoRoot !== 'string') return defaults;
@@ -417,6 +440,7 @@ function readAgentEvalConfig(repoRoot) {
 }
 
 module.exports = {
+  readCIConfigDetails,
   EXECUTION_MODES,
   DEFAULT_EXECUTION_MODE,
   EDITOR_MODE_CONSENT_NOTE,

package/lib/verify-patch.js

@@ -38,12 +38,50 @@ const EXIT = {
  * @param {string|undefined} configured ci_local_command from run config
  * @returns {string}
  */
-function resolveCommand(explicit, configured) {
-  const pick = (explicit && explicit.trim())
-    || (configured && configured.trim())
-    || 'make ci';
-  return pick;
+const DEFAULT_COMMAND = 'make ci';
+function _hasMakeCiTarget(cwd) {
+  try { const f = require('node:fs'); const p = require('node:path').join(cwd, 'Makefile'); return f.existsSync(p) && /^ci\s*:/m.test(f.readFileSync(p, 'utf8')); } catch { return false; }
 }
+function _npmTestScript(cwd) {
+  try {
+    const f = require('node:fs'); const p = require('node:path').join(cwd, 'package.json');
+    if (!f.existsSync(p)) return null;
+    const t = JSON.parse(f.readFileSync(p, 'utf8'))?.scripts?.test;
+    return (typeof t === 'string' && t.trim() && !/no test specified/i.test(t)) ? 'npm test' : null;
+  } catch { return null; }
+}
+/**
+ * HC-COMM-010-followup-7: tiered resolution. Without `opts.cwd` this is the
+ * original pure function (explicit → configured → `make ci`). With `opts.cwd`:
+ *   1. --command (explicit)
+ *   2. ci.local_command set EXPLICITLY in the file NOW (re-read at verify/emit
+ *      time — the run config captured it at creation and may be stale)
+ *   3. the run config's ci_local_command, unless it is just the stamped default
+ *   4. `make ci` if the Makefile has a ci target
+ *   5. `npm test` if package.json has a real test script
+ *   6. `make ci` (documented default; fails loudly)
+ * @returns {{command:string, source:string}}
+ */
+function resolveCommandDetailed(explicit, configured, opts = {}) {
+  const e = (typeof explicit === 'string' ? explicit : '').trim();
+  if (e) return { command: e, source: '--command' };
+  const cwd = opts && opts.cwd;
+  if (cwd) {
+    try {
+      const { readCIConfigDetails } = require('./pipeline-config');
+      const d = readCIConfigDetails(cwd);
+      if (d.local_command_explicit) return { command: d.local_command, source: 'ci.local_command (config file)' };
+    } catch { /* fall through */ }
+  }
+  const c = (typeof configured === 'string' ? configured : '').trim();
+  if (c && c !== DEFAULT_COMMAND) return { command: c, source: 'run config' };
+  if (cwd) {
+    if (_hasMakeCiTarget(cwd)) return { command: DEFAULT_COMMAND, source: 'Makefile ci target' };
+    const npm = _npmTestScript(cwd); if (npm) return { command: npm, source: 'package.json test script' };
+  }
+  return { command: DEFAULT_COMMAND, source: 'default' };
+}
+function resolveCommand(explicit, configured, opts) { return resolveCommandDetailed(explicit, configured, opts).command; }
 
 /**
  * Interpret a completed command run into a condition-6 verdict.
@@ -75,4 +113,4 @@ function lastMeaningfulLine({ stdout = '', stderr = '' }) {
   return (failLine || combined[0] || '').slice(0, 200);
 }
 
-module.exports = { EXIT, resolveCommand, verdictFromRun, lastMeaningfulLine };
+module.exports = { EXIT, resolveCommand, resolveCommandDetailed, DEFAULT_COMMAND, verdictFromRun, lastMeaningfulLine };

package/lib/worktree-provision.js

@@ -0,0 +1,64 @@
+'use strict';
+/**
+ * worktree-provision.js — HC-COMM-010-followup-6: "verify in an isolated
+ * worktree" implies "provision the worktree". A bare `git worktree add` has no
+ * node_modules, so a Node adopter's test command failed with "Cannot find
+ * package 'vitest'" before any test ran (found 2026-09-05, run 4ab3a962).
+ *
+ * Plan (pure) → execute (injected exec). Fast path: when the worktree's
+ * lockfile is byte-identical to the repo's and the repo already has
+ * node_modules, LINK it (seconds, no network). Otherwise run the lockfile's
+ * install. Explicit `ci.install_command` wins. Fail-open: a provisioning
+ * failure is reported and the test command still runs (it will fail clearly).
+ */
+const fs = require('node:fs');
+const path = require('node:path');
+
+const LOCKFILES = [
+  ['package-lock.json',   'npm ci --no-audit --no-fund'],
+  ['npm-shrinkwrap.json', 'npm ci --no-audit --no-fund'],
+  ['pnpm-lock.yaml',      'pnpm install --frozen-lockfile'],
+  ['yarn.lock',           'yarn install --frozen-lockfile'],
+];
+const INSTALL_TIMEOUT_MS = 10 * 60 * 1000;
+
+function planProvision({ worktreeDir, parentDir, installCommand = null, fsMod = fs }) {
+  const ex = (p) => { try { return fsMod.existsSync(p); } catch { return false; } };
+  const rd = (p) => { try { return fsMod.readFileSync(p, 'utf8'); } catch { return null; } };
+  if (installCommand && String(installCommand).trim()) {
+    return { kind: 'install', command: String(installCommand).trim(), reason: 'ci.install_command' };
+  }
+  for (const [lock, cmd] of LOCKFILES) {
+    const wl = path.join(worktreeDir, lock);
+    if (!ex(wl)) continue;
+    const pl = path.join(parentDir, lock); const pnm = path.join(parentDir, 'node_modules');
+    if (ex(pnm) && ex(pl) && rd(wl) !== null && rd(wl) === rd(pl)) {
+      return { kind: 'link', target: pnm, reason: `${lock} unchanged — linking the repo's node_modules` };
+    }
+    return { kind: 'install', command: cmd, reason: `${lock} present${ex(pnm) ? ' but changed' : ''}` };
+  }
+  if (ex(path.join(worktreeDir, 'package.json'))) {
+    return { kind: 'install', command: 'npm install --no-audit --no-fund', reason: 'package.json without a lockfile' };
+  }
+  return { kind: 'none', reason: 'no dependency manifest detected' };
+}
+
+/** @returns {{ok:boolean, did:'none'|'link'|'install', summary:string, command?:string}} */
+function provisionWorktree(plan, { worktreeDir, exec, fsMod = fs }) {
+  if (!plan || plan.kind === 'none') return { ok: true, did: 'none', summary: `skipped (${plan ? plan.reason : 'no plan'})` };
+  if (plan.kind === 'link') {
+    try {
+      const dest = path.join(worktreeDir, 'node_modules');
+      if (!fsMod.existsSync(dest)) fsMod.symlinkSync(plan.target, dest, 'dir');
+      return { ok: true, did: 'link', summary: `linked node_modules (${plan.reason})` };
+    } catch (e) { return { ok: false, did: 'link', summary: `link failed (${e.message}) — tests run unprovisioned` }; }
+  }
+  try {
+    const run = exec(plan.command, { cwd: worktreeDir, shell: true, encoding: 'utf8', timeout: INSTALL_TIMEOUT_MS, stdio: ['ignore', 'pipe', 'pipe'] });
+    const ok = run && run.status === 0;
+    const tail = ok ? '' : ` — ${String((run && (run.stderr || run.stdout)) || '').trim().split('\n').filter(Boolean).pop() || 'install failed'}`;
+    return { ok, did: 'install', command: plan.command, summary: `${ok ? 'ran' : 'FAILED'} \`${plan.command}\` (${plan.reason})${tail}` };
+  } catch (e) { return { ok: false, did: 'install', command: plan.command, summary: `install threw (${e.message}) — tests run unprovisioned` }; }
+}
+
+module.exports = { planProvision, provisionWorktree, LOCKFILES, INSTALL_TIMEOUT_MS };

package/package.json

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