@lannguyensi/harness 0.41.0 → 0.42.0

package/dist/cli/index.js

@@ -3,6 +3,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { Command } from "commander";
+import { HermeticSpawnViolationError } from "../runtime/hermetic-spawn-guard.js";
 // Production version probe for `harness doctor`: synchronous --version
 // invocation with a 5s timeout. Tests inject their own probe; the CLI
 // entrypoint wires this default. Same shape as `cli/doctor/codex.ts`.
@@ -40,6 +41,7 @@ import { approveBranchProtection } from "./approve/branch-protection.js";
 import { approveRisk } from "./approve/risk.js";
 import { approveUnderstanding } from "./approve/understanding.js";
 import { readPipedStdin } from "./approve/stdin-report.js";
+import { runRecordDogfood, runRecordReview, runRecordReviewSubagent, } from "./record/index.js";
 import { describe, isPillar } from "./describe.js";
 import { diff as diffRun } from "./diff/index.js";
 import { diffSinceApply } from "./diff/since-apply.js";
@@ -64,9 +66,12 @@ import { runInterceptCli } from "./policy/intercept.js";
 import { runSessionStartPreflight } from "./session-start/index.js";
 import { writePendingApproval } from "../runtime/pending-approval.js";
 import { runSessionStartBranchCheck } from "./session-start/branch-check.js";
+import { runSessionStartToolchainParity } from "./session-start/toolchain-parity.js";
 import { runPackHookBranchProtectionCli } from "./pack/hook-branch-protection.js";
 import { runPackHookSolutionAcceptanceCli } from "./pack/hook-solution-acceptance.js";
 import { runPackHookSolutionAcceptanceWriteguardCli } from "./pack/hook-solution-acceptance-writeguard.js";
+import { runPackHookPostMergeGateRecordCli } from "./pack/hook-post-merge-gate-record.js";
+import { runPackHookPostMergeGateCli } from "./pack/hook-post-merge-gate.js";
 import { runPackHookRuntimeRealityCli } from "./pack/hook-runtime-reality.js";
 import { gateDisable, GateDisableError } from "./gate/disable.js";
 import { gateEnable, GateEnableError } from "./gate/enable.js";
@@ -503,13 +508,25 @@ export function buildProgram(opts = {}) {
     });
     program
         .command("adopt <file>")
-        .description("Capture hand-edits from a runtime file (today: ~/.claude/settings.json) " +
-        "into the manifest. Diffs against the manifest's current declarations and " +
-        "prompts y/N before writing.")
+        .description("Capture hand-edits into the manifest. Hooks are diffed against <file> " +
+        "(today: ~/.claude/settings.json). MCP servers are ALWAYS diffed " +
+        "against the effective Claude Code registry (top-level mcpServers in " +
+        "~/.claude.json, respecting CLAUDE_CONFIG_DIR) regardless of <file> — " +
+        "Claude Code does not read <file>'s mcpServers block at runtime. " +
+        "Prompts y/N before writing.")
         .option("--config <path>", "manifest path (default: ~/.harness/harness.yaml; legacy fallback ~/.claude/harness.yaml)")
         .option("--yes", "skip the confirmation prompt (for non-interactive use)")
         .action(async (file, options) => {
         const result = await adopt(file, { configPath: options.config, yes: options.yes });
+        if (result.deadSettingsMcpNames.length > 0) {
+            stderr(`⚠ ${file} has a dead \`mcpServers\` block (${result.deadSettingsMcpNames.join(", ")}); ` +
+                "Claude Code does not read this file for MCP registration — adopt diffed against the " +
+                "effective registry instead. Safe to remove by hand.\n");
+        }
+        if (result.registryReadError !== undefined) {
+            stderr(`⚠ could not read the Claude Code MCP registry: ${result.registryReadError}; ` +
+                "treated as empty for MCP drift purposes.\n");
+        }
         if (result.outcome === "no-drift") {
             stdout(`nothing to adopt (no drift between ${file} and ${result.manifestPath})\n`);
             return;
@@ -1029,6 +1046,61 @@ export function buildProgram(opts = {}) {
             throw new HarnessExitError("", result.exitCode);
         }
     });
+    packHookCmd
+        .command("post-merge-gate-record")
+        .description("PostToolUse producer for the post-merge-gate pack: read tool-event JSON from stdin and, on a " +
+        "`gh pr merge` Bash call whose tool_output.exit_code is the number 0, record a " +
+        "`post-merge-gate:merged:<repo>:<branch>:<sha>` fact to the evidence ledger. blocking:false; every " +
+        "non-match / failure path is a no-op.")
+        .option("--config <path>", "manifest path (default: ~/.harness/harness.yaml; legacy fallback ~/.claude/harness.yaml)")
+        .option("--project <name>", "apply per-project overrides")
+        .option("--ledger-timeout <ms>", "per-call ledger timeout in milliseconds")
+        .option("--cwd <path>", "override cwd resolution (default: stdin event.cwd then process.cwd())")
+        .action(async (options) => {
+        const cliOpts = {};
+        if (options.config)
+            cliOpts.configPath = options.config;
+        if (options.project)
+            cliOpts.project = options.project;
+        if (options.cwd)
+            cliOpts.cwd = options.cwd;
+        if (options.ledgerTimeout) {
+            const n = Number.parseInt(options.ledgerTimeout, 10);
+            if (Number.isFinite(n) && n > 0)
+                cliOpts.ledgerTimeoutMs = n;
+        }
+        await runPackHookPostMergeGateRecordCli(cliOpts);
+    });
+    packHookCmd
+        .command("post-merge-gate")
+        .description("PreToolUse blocker for the post-merge-gate pack: read tool-event JSON from stdin, and on a curated " +
+        "history-mutating Bash command (git commit/add/push/merge/rebase/cherry-pick/revert/reset/stash " +
+        "pop|apply, gh pr create/merge) emit a deny envelope when the current branch tip matches a recorded " +
+        "merged-tip fact. An escape allowlist (git switch/checkout/pull/fetch, git branch -d/-D, git stash " +
+        "list/show, any `harness ...` command) is checked first, unconditionally. Fails open when the ledger " +
+        "is unreachable.")
+        .option("--config <path>", "manifest path (default: ~/.harness/harness.yaml; legacy fallback ~/.claude/harness.yaml)")
+        .option("--project <name>", "apply per-project overrides")
+        .option("--ledger-timeout <ms>", "per-call ledger timeout in milliseconds")
+        .option("--cwd <path>", "override cwd resolution (default: stdin event.cwd then process.cwd())")
+        .action(async (options) => {
+        const cliOpts = {};
+        if (options.config)
+            cliOpts.configPath = options.config;
+        if (options.project)
+            cliOpts.project = options.project;
+        if (options.cwd)
+            cliOpts.cwd = options.cwd;
+        if (options.ledgerTimeout) {
+            const n = Number.parseInt(options.ledgerTimeout, 10);
+            if (Number.isFinite(n) && n > 0)
+                cliOpts.ledgerTimeoutMs = n;
+        }
+        const result = await runPackHookPostMergeGateCli(cliOpts);
+        if (result.exitCode !== 0) {
+            throw new HarnessExitError("", result.exitCode);
+        }
+    });
     packHookCmd
         .command("runtime-reality")
         .description("PreToolUse drift gate: read tool-event JSON from stdin, run the operator-configured " +
@@ -1689,6 +1761,124 @@ export function buildProgram(opts = {}) {
         cliOpts.stagePendingApproval = writePendingApproval;
         await runSessionStartPreflight(cliOpts);
     });
+    // Shared by the three `record` verbs' action handlers below: parse
+    // `--ledger-timeout <ms>` into `cliOpts.ledgerTimeoutMs`, and report a
+    // `RecordResult` (print the recorded fact on success; on failure, throw
+    // with the runner's own exit code and an EMPTY message, since the
+    // runner already wrote the reason to stderr itself — throwing the same
+    // text again would double-print it).
+    //
+    // An unparseable / non-positive value used to fall back to the
+    // default silently (review finding, T-004): an operator who typo'd
+    // `--ledger-timeout 5ooo` got the default timeout with zero
+    // diagnostic. Now a malformed value warns once on stderr before
+    // falling back, same "never a silent gap" convention `resolveBase`'s
+    // own degrade path already uses below.
+    const applyLedgerTimeout = (raw, cliOpts) => {
+        if (!raw)
+            return;
+        const n = Number.parseInt(raw, 10);
+        if (Number.isFinite(n) && n > 0) {
+            cliOpts.ledgerTimeoutMs = n;
+            return;
+        }
+        stderr(`harness record: --ledger-timeout ${JSON.stringify(raw)} is not a positive integer; using the default timeout.\n`);
+    };
+    const reportRecordResult = (result) => {
+        if (result.wrote) {
+            stdout(`recorded ${result.content} for session ${result.sessionId}\n`);
+        }
+        if (result.exitCode !== 0) {
+            throw new HarnessExitError("", result.exitCode);
+        }
+    };
+    // `harness record {review,review-subagent,dogfood}` (task T-001):
+    // evidence-ledger producers for the review-before-merge,
+    // review-subagent-before-pr-create, and dogfood-before-release gate
+    // families (see src/cli/init/templates.ts for the exact policies).
+    // Unlike the `preflight` / `session-start preflight` pair above,
+    // these are NOT hooks: they are invoked deliberately by an agent or
+    // operator, so a failure exits non-zero with a clear stderr message
+    // (written by the runner itself) rather than degrading silently.
+    const recordCmd = program
+        .command("record")
+        .description("Evidence-ledger producers for the review / review-subagent / dogfood gate families. " +
+        "Interactive verbs (not hooks): a failure exits non-zero.");
+    recordCmd
+        .command("review <summary>")
+        .description("Record a review:${PR_NUMBER} + review:${BRANCH} (+ review:${BASE}) fact for the " +
+        "review-before-merge / review-before-merge-bash gates.")
+        .option("--config <path>", "manifest path (default: ~/.harness/harness.yaml; legacy fallback ~/.claude/harness.yaml)")
+        .option("--project <name>", "apply per-project overrides")
+        .requiredOption("--pr <number>", "PR number the review:${PR_NUMBER} tag is namespaced by")
+        .option("--base <branch>", "base branch for the review:${BASE} tag. Default: the remote's default branch read from " +
+        "refs/remotes/origin/HEAD (packed-refs fallback included); omitted with a stderr warning " +
+        "when neither resolves. No `gh` shell-out.")
+        .option("--branch <name>", "explicit branch override for review:${BRANCH} (default: current git branch)")
+        .option("--session <id>", "explicit session id (default: $CLAUDE_CODE_SESSION_ID, then $CLAUDE_SESSION_ID, then newest Claude Code transcript)")
+        .option("--ledger-timeout <ms>", "per-call ledger timeout in milliseconds")
+        .action(async (summary, options) => {
+        const cliOpts = { pr: options.pr, summary };
+        if (options.config)
+            cliOpts.configPath = options.config;
+        if (options.project)
+            cliOpts.project = options.project;
+        if (options.base)
+            cliOpts.base = options.base;
+        if (options.branch)
+            cliOpts.branch = options.branch;
+        if (options.session)
+            cliOpts.session = options.session;
+        applyLedgerTimeout(options.ledgerTimeout, cliOpts);
+        reportRecordResult(await runRecordReview(cliOpts));
+    });
+    recordCmd
+        .command("review-subagent [summary]")
+        .description("Record a review-subagent:${TASK_ID} + review-subagent:${BRANCH} fact for the " +
+        "review-subagent-before-pr-create / review-subagent-before-pr-create-bash gates.")
+        .option("--config <path>", "manifest path (default: ~/.harness/harness.yaml; legacy fallback ~/.claude/harness.yaml)")
+        .option("--project <name>", "apply per-project overrides")
+        .requiredOption("--task <id>", "agent-tasks task id the review-subagent:${TASK_ID} tag is namespaced by")
+        .requiredOption("--verdict <text>", "reviewer verdict recorded in the fact content")
+        .option("--branch <name>", "explicit branch override for review-subagent:${BRANCH} (default: current git branch)")
+        .option("--session <id>", "explicit session id (default: $CLAUDE_CODE_SESSION_ID, then $CLAUDE_SESSION_ID, then newest Claude Code transcript)")
+        .option("--ledger-timeout <ms>", "per-call ledger timeout in milliseconds")
+        .action(async (summary, options) => {
+        const cliOpts = {
+            task: options.task,
+            verdict: options.verdict,
+        };
+        if (options.config)
+            cliOpts.configPath = options.config;
+        if (options.project)
+            cliOpts.project = options.project;
+        if (options.branch)
+            cliOpts.branch = options.branch;
+        if (options.session)
+            cliOpts.session = options.session;
+        if (summary)
+            cliOpts.summary = summary;
+        applyLedgerTimeout(options.ledgerTimeout, cliOpts);
+        reportRecordResult(await runRecordReviewSubagent(cliOpts));
+    });
+    recordCmd
+        .command("dogfood <summary>")
+        .description("Record a dogfood:${SESSION_ID} fact for the dogfood-before-release gate.")
+        .option("--config <path>", "manifest path (default: ~/.harness/harness.yaml; legacy fallback ~/.claude/harness.yaml)")
+        .option("--project <name>", "apply per-project overrides")
+        .option("--session <id>", "explicit session id (default: $CLAUDE_CODE_SESSION_ID, then $CLAUDE_SESSION_ID, then newest Claude Code transcript)")
+        .option("--ledger-timeout <ms>", "per-call ledger timeout in milliseconds")
+        .action(async (summary, options) => {
+        const cliOpts = { summary };
+        if (options.config)
+            cliOpts.configPath = options.config;
+        if (options.project)
+            cliOpts.project = options.project;
+        if (options.session)
+            cliOpts.session = options.session;
+        applyLedgerTimeout(options.ledgerTimeout, cliOpts);
+        reportRecordResult(await runRecordDogfood(cliOpts));
+    });
     const sessionStart = program
         .command("session-start")
         .description("SessionStart hook entrypoints (called by Claude Code via settings.json)");
@@ -1759,6 +1949,36 @@ export function buildProgram(opts = {}) {
         }
         await runSessionStartBranchCheck(cliOpts);
     });
+    sessionStart
+        .command("toolchain-parity")
+        .description("SessionStart producer (opt-in via `toolchain_parity.enabled: true`): writes THIS machine's " +
+        "toolchain snapshot (node version, npm globals, OW-Kit version, MCP server names) to " +
+        "`<machine_state_dir>/<profile>.json`, compares it against every OTHER snapshot file already " +
+        "in that directory, and records a `toolchain-parity:ok` / `toolchain-parity:drift:<n>` fact " +
+        "to the evidence ledger. Purely advisory — never blocking, and never touches a peer's file. " +
+        "Cross-machine transport of the snapshot files is agent-memory-sync's job, not this command's.")
+        .option("--config <path>", "manifest path (default: ~/.harness/harness.yaml; legacy fallback ~/.claude/harness.yaml)")
+        .option("--project <name>", "apply per-project overrides")
+        .option("--session <id>", "explicit session id (overrides stdin event + env)")
+        .option("--cwd <path>", "override cwd resolution (default: stdin event.cwd then process.cwd())")
+        .option("--ledger-timeout <ms>", "per-call ledger timeout in milliseconds")
+        .action(async (options) => {
+        const cliOpts = {};
+        if (options.config)
+            cliOpts.configPath = options.config;
+        if (options.project)
+            cliOpts.project = options.project;
+        if (options.session)
+            cliOpts.session = options.session;
+        if (options.cwd)
+            cliOpts.cwd = options.cwd;
+        if (options.ledgerTimeout) {
+            const n = Number.parseInt(options.ledgerTimeout, 10);
+            if (Number.isFinite(n) && n > 0)
+                cliOpts.ledgerTimeoutMs = n;
+        }
+        await runSessionStartToolchainParity(cliOpts);
+    });
     // `harness gate` — operator escape hatch for hard-blocking hooks.
     // Task 8fcddb26: the understanding-before-execution PreToolUse hook can
     // lock a Claude session out of every Bash call, and the recommended
@@ -1937,7 +2157,7 @@ export function buildProgram(opts = {}) {
         if (options.settings)
             cliOpts.settingsPath = options.settings;
         try {
-            const result = uninstall(cliOpts);
+            const result = await uninstall(cliOpts);
             const inv = result.inventory;
             if (result.mode === "list") {
                 const nothing = inv.manifestPath === null &&
@@ -1946,6 +2166,7 @@ export function buildProgram(opts = {}) {
                     inv.gateStateDir === null &&
                     inv.hookGroups.length === 0 &&
                     inv.mcpServers.length === 0 &&
+                    inv.mcpRegistryServers.length === 0 &&
                     inv.preHarnessBackups.length === 0;
                 const rootsLabel = inv.stateDir === inv.homeDir
                     ? inv.homeDir
@@ -1975,6 +2196,10 @@ export function buildProgram(opts = {}) {
                 if (inv.mcpServers.length > 0) {
                     stdout(`  mcpServers in ${inv.settingsPath}: ${inv.mcpServers.join(", ")}\n`);
                 }
+                if (inv.mcpRegistryServers.length > 0) {
+                    stdout(`  mcpServers registered in the claude CLI user-scope registry (${inv.mcpRegistryPath}): ` +
+                        `${inv.mcpRegistryServers.join(", ")}\n`);
+                }
                 if (inv.preHarnessBackups.length > 0) {
                     stdout(`  pre-harness backups:\n`);
                     for (const b of inv.preHarnessBackups)
@@ -1995,6 +2220,11 @@ export function buildProgram(opts = {}) {
                     for (const f of result.removedFiles)
                         stdout(`  ${f}\n`);
                 }
+                if (result.mcpRegistryRemovals.length > 0) {
+                    stdout(`claude mcp remove (user scope, ${inv.mcpRegistryPath}):\n`);
+                    for (const r of result.mcpRegistryRemovals)
+                        stdout(`  ${r.name}: ${r.status}\n`);
+                }
                 stdout(`\nTo finish: \`npm uninstall -g @lannguyensi/harness\` (uninstall does not touch the npm install).\n`);
                 for (const w of inv.warnings)
                     stderr(`warning: ${w}\n`);
@@ -2034,9 +2264,15 @@ export function buildProgram(opts = {}) {
                     /* state root itself may be gone or unreadable; nothing to report */
                 }
             }
+            if (result.mcpRegistryRemovals.length > 0) {
+                stdout(`claude mcp remove (user scope, ${inv.mcpRegistryPath}):\n`);
+                for (const r of result.mcpRegistryRemovals)
+                    stdout(`  ${r.name}: ${r.status}\n`);
+            }
             if (result.backupPath === null &&
                 result.snapshotPath === null &&
-                result.removedFiles.length === 0) {
+                result.removedFiles.length === 0 &&
+                result.mcpRegistryRemovals.length === 0) {
                 const rootsLabel = inv.stateDir === inv.homeDir
                     ? inv.homeDir
                     : `${inv.stateDir} (state) + ${inv.homeDir} (settings)`;
@@ -2205,6 +2441,18 @@ export async function run(opts = {}) {
         return 0;
     }
     catch (err) {
+        // Defense-in-depth (task 325ace29): a hermetic-spawn-guard violation
+        // must always propagate out of run() as a hard failure, never be
+        // folded into the generic "return 70" branch below. Without this,
+        // any test that merely asserts "exit code != 0" (rather than the
+        // specific message) would mask a future real spawn slipping past a
+        // guarded call site. This is production-neutral: the guard
+        // (src/runtime/hermetic-spawn-guard.ts) only ever throws when
+        // `process.env.VITEST` is set, which a real, standalone `harness`
+        // invocation never has — so this branch is unreachable outside of
+        // vitest and changes no production behavior.
+        if (err instanceof HermeticSpawnViolationError)
+            throw err;
         if (err instanceof HarnessExitError) {
             if (err.exitCode !== 0 && err.message)
                 stderr(`${err.message}\n`);