@lannguyensi/harness 0.40.0 → 0.42.0

package/dist/cli/init/interactive.js

@@ -21,14 +21,23 @@
 //   write + file-lock + post-write validate path is reused. The wizard
 //   is essentially a UI for picking the `--template` value.
 import { select, confirm, input, checkbox } from "@inquirer/prompts";
+import * as fs from "node:fs";
 import * as path from "node:path";
 import { spawn } from "node:child_process";
 import { resolveHomeDir } from "../../runtime/home-dir.js";
+import { assertNoRealSpawnInTests, HermeticSpawnViolationError } from "../../runtime/hermetic-spawn-guard.js";
 import { EX_FAIL, HarnessExitError } from "../exit-codes.js";
 import { detect, } from "./detect.js";
 import { init } from "./index.js";
 import { validate } from "../validate/index.js";
-import { apply, CODEX_CONFIG_BASENAME } from "../apply/index.js";
+import { apply, CODEX_CONFIG_BASENAME, SETTINGS_BASENAME } from "../apply/index.js";
+import { buildMcpServers, projectGroundingEnv, } from "../apply/generate-settings.js";
+import { loadManifest } from "../loader.js";
+import { ensureMcpServers, manualRemoveLines, posixSingleQuote, stripOwnedMcpServers, } from "../../io/claude-mcp.js";
+import { atomicWriteFile } from "../../io/atomic-write.js";
+import { resolveGeneratedDir } from "../../io/generated-dir.js";
+import { readLastApply } from "../../io/last-apply.js";
+import { DEFAULT_OWNED_MCP_SERVERS } from "../uninstall/index.js";
 import { checkDependencies, checkDependencyList, dependenciesForCustom, formatDependencyTable, installPackagesGlobally, } from "./dependencies.js";
 import { probeAgentTasksAuth, runBridgeLogin, } from "./agent-tasks-auth.js";
 import { COMPOSABLE_MCPS, COMPOSABLE_PACKS, COMPOSABLE_POLICIES, composeCustom, } from "./composer.js";
@@ -68,7 +77,7 @@ function summariseDetection(d) {
         lines.push(`  MCP wired   ${d.mcpServers.map((s) => s.name).join(", ")}`);
     }
     else {
-        lines.push(`  MCP wired   (none detected in Claude settings.json)`);
+        lines.push(`  MCP wired   (none detected in the Claude Code user-scope registry)`);
     }
     lines.push(`  harness     v${d.harness.version}`);
     return lines.join("\n");
@@ -87,6 +96,33 @@ function runtimeIsConfigured(r) {
         return false;
     return r.homeExists || r.settingsExists;
 }
+/**
+ * Read `.last-apply` BEFORE `apply()` gets a chance to re-stamp it (task
+ * 363a6de0, Reviewer-Finding 2 / D-107). `apply()` overwrites `.last-apply`
+ * with the CURRENT manifest's snapshot whenever anything changed —
+ * including a combined edit that both removes a `tools.mcp[]` entry AND
+ * touches something else (e.g. a hook via a pack) — which would erase the
+ * PRE-edit provenance GC's ownership union needs. Malformed JSON or a
+ * schema-invalid record (`readLastApply`'s own validation throws for
+ * both) degrades to `null` — the same conservative "no snapshot" fallback
+ * D-107 already specifies — rather than letting a corrupt file crash
+ * wire-now (previously this was read late and only reachable after
+ * Ensure succeeded; hoisting it here means a throw would otherwise
+ * surface twice, once from the try branch and again from the catch
+ * branch's own `wireClaudeMcp` call).
+ */
+function readPriorLastApply(o) {
+    const generatedDir = resolveGeneratedDir({
+        ...(o.homeDir !== undefined ? { homeDir: o.homeDir } : {}),
+        manifestPath: o.configPath,
+    });
+    try {
+        return readLastApply(generatedDir);
+    }
+    catch {
+        return null;
+    }
+}
 async function wireRuntime(o) {
     // Defensive: only claude-code and codex have apply paths in v1. The
     // checkbox UI disables "opencode" until task f34eb233 lands, so this
@@ -97,6 +133,15 @@ async function wireRuntime(o) {
         throw new HarnessExitError(`wireRuntime: ${o.runtime} is not a wirable runtime in this harness build`, EX_FAIL);
     }
     if (o.runtime === "claude-code") {
+        // D-107 / Reviewer-Finding 2 (task 363a6de0): capture `.last-apply`'s
+        // manifest snapshot BEFORE apply() runs. apply() re-stamps
+        // `.last-apply` with the CURRENT (already-edited) manifest whenever
+        // anything changed — including a combined edit that both removes a
+        // `tools.mcp[]` entry AND touches something else (e.g. a hook via a
+        // pack). Reading it only after apply() (the pre-fix ordering) would
+        // silently erase the very provenance GC's ownership union needs to
+        // see a manifest entry that existed just before THIS run.
+        const priorLastApply = readPriorLastApply(o);
         // init's wire-now intent is "wire this freshly written manifest"
         // — the operator already confirmed by ticking claude-code in the
         // wire-now checkbox. A pre-existing drift in
@@ -147,14 +192,30 @@ async function wireRuntime(o) {
             if (!r.targetWritten && !r.targetInSync) {
                 outcome.recoveryHint = `harness apply --target ${o.claudeSettingsPath} --merge --overwrite-drift`;
             }
+            // T-002: MCP registration below is independent of this hooks/
+            // settings.json merge — it goes through the `claude mcp` CLI, not
+            // through settings.json. Run it regardless of the merge outcome so
+            // a hooks-merge hiccup doesn't also withhold MCP wiring.
+            await wireClaudeMcp(o, outcome, priorLastApply);
             return outcome;
         }
         catch (err) {
+            // Hermetic guard (task 0d80e969): a real-spawn violation from
+            // `wireClaudeMcp`'s FIRST call above (inside this `try`) must
+            // never be treated as an ordinary `apply()` failure — this catch
+            // otherwise degrades any thrown error to a "Failed to wire ..."
+            // warning AND calls `wireClaudeMcp` a SECOND time below, which
+            // would both print a misleading message and retry a spawn that
+            // must never happen under vitest. Re-throw before any of that.
+            if (err instanceof HermeticSpawnViolationError)
+                throw err;
             const message = err instanceof Error ? err.message : String(err);
             const recoveryHint = `harness apply --target ${o.claudeSettingsPath} --merge --overwrite-drift`;
             o.stderr(`\nFailed to wire ${o.claudeSettingsPath}: ${message}\n`);
             o.stderr(`Manifest is on disk. To retry the merge manually:\n  ${recoveryHint}\n`);
-            return { runtime: "claude-code", recoveryHint };
+            const outcome = { runtime: "claude-code", recoveryHint };
+            await wireClaudeMcp(o, outcome, priorLastApply);
+            return outcome;
         }
     }
     // Codex path: apply --runtime codex emits harness.generated/codex/config.toml.
@@ -199,6 +260,289 @@ async function wireRuntime(o) {
         return { runtime: "codex", recoveryHint };
     }
 }
+/**
+ * Reload the effective manifest and translate `tools.mcp[]` into the
+ * server-spec shape the `claude mcp` CLI wants (task
+ * init-mcp-wiring-claude-code/T-002). Reuses the exact same
+ * `buildMcpServers` + `projectGroundingEnv` functions the settings.json
+ * projection used to feed into the (now dead) `mcpServers` block —
+ * see generate-settings.ts's `GenerateSettingsResult.mcpServers` doc.
+ * `harnessHomeDir` is the harness STATE root (`harnessHomeArg(opts)`),
+ * not the operator's `$HOME`; `projectGroundingEnv`'s tilde-expansion is
+ * deliberately left on its default (`os.homedir()`) here, mirroring
+ * `apply.ts`'s own `buildExpectedFiles` call, which never overrides it
+ * either.
+ *
+ * Returns `null` when the manifest can't be reloaded (should not happen
+ * right after a successful `init()`, but a hand-edited/deleted manifest
+ * between write and this read is possible); callers degrade gracefully.
+ */
+function loadDesiredMcpServers(configPath, harnessHomeDir) {
+    let manifest;
+    try {
+        manifest = loadManifest({
+            configPath,
+            ...(harnessHomeDir !== undefined ? { homeDir: harnessHomeDir } : {}),
+        }).manifest;
+    }
+    catch {
+        return null;
+    }
+    const warnings = [];
+    const desired = buildMcpServers(manifest.tools.mcp, warnings);
+    projectGroundingEnv(manifest, desired);
+    return { manifest, desired, warnings };
+}
+/** One `claude mcp add-json --scope user <name> '<json>'` line per desired server, sorted by name. */
+function manualAddJsonLines(desired) {
+    return Object.keys(desired)
+        .sort()
+        .map((name) => `claude mcp add-json --scope user ${name} ${posixSingleQuote(JSON.stringify(desired[name]))}`);
+}
+/**
+ * Extract the mcpServers names a PREVIOUS apply wrote into
+ * `harness.generated/settings.json`, from `.last-apply`. Pre-T-002
+ * harness versions projected `mcpServers` into that file; a leftover
+ * record from one of those versions is the provenance signal the
+ * migration step (below) needs to safely strip the matching names out of
+ * the live (dead) settings.json block without guessing. Mirrors the
+ * equivalent snippet in `apply.ts`'s `--target --merge` provenance
+ * handling (kept separate rather than shared: apply.ts's version is
+ * private to that module and the two call sites read a different record
+ * shape's field, not worth a shared export for ~10 lines).
+ */
+function priorGeneratedMcpNames(lastApply) {
+    const content = lastApply?.files[SETTINGS_BASENAME]?.content;
+    if (content === undefined)
+        return [];
+    try {
+        const prior = JSON.parse(content);
+        const mcp = prior["mcpServers"];
+        if (mcp !== null && typeof mcp === "object" && !Array.isArray(mcp)) {
+            return Object.keys(mcp);
+        }
+    }
+    catch {
+        // Corrupt .last-apply record: no provenance names from it; the
+        // manifest + DEFAULT_OWNED_MCP_SERVERS sets still apply.
+    }
+    return [];
+}
+/**
+ * Extract `tools.mcp[]` names from the manifest snapshot `.last-apply`
+ * stores (`LastApplyRecord.manifest`, Phase 3 #1) — the effective manifest
+ * as of the apply BEFORE this run (see `readPriorLastApply` — the record
+ * passed in here is captured before this run's `apply()` re-stamps the
+ * file), not necessarily the manifest on disk right now. GC ownership
+ * (task 363a6de0, D-107) needs this: a server whose `tools.mcp[]` entry
+ * was removed or disabled just before THIS run is still harness-owned,
+ * and the CURRENT manifest alone can never surface it — by definition
+ * it's gone from there. An older `.last-apply` record (pre-manifest-
+ * snapshot, so `.manifest` is absent) or a snapshot that fails to parse
+ * both degrade to an EMPTY result — the conservative fallback D-107
+ * calls for is to fall back to JUST the current manifest's names (NOT
+ * `DEFAULT_OWNED_MCP_SERVERS` — see the D-107 note on `wireClaudeMcp`)
+ * rather than guess at this one.
+ */
+function priorManifestMcpNames(lastApply) {
+    const content = lastApply?.manifest?.content;
+    if (content === undefined)
+        return [];
+    try {
+        const prior = JSON.parse(content);
+        const mcp = prior.tools?.mcp;
+        if (!Array.isArray(mcp))
+            return [];
+        const names = [];
+        for (const entry of mcp) {
+            if (entry !== null &&
+                typeof entry === "object" &&
+                typeof entry.name === "string") {
+                names.push(entry.name);
+            }
+        }
+        return names;
+    }
+    catch {
+        // Corrupt .last-apply record: no provenance names from it; the
+        // current manifest's names still apply.
+        return [];
+    }
+}
+/**
+ * Strip harness-owned names from the dead `mcpServers` block in
+ * `o.claudeSettingsPath` (D-002/D-003: only ever called AFTER Ensure has
+ * confirmed every desired server is correctly registered via the `claude`
+ * CLI). Owned = the current manifest's `tools.mcp[]` names, UNION any
+ * names a pre-T-002 harness version generated into settings.json
+ * (`.last-apply` provenance), UNION the uninstall module's default
+ * ownership set (covers a manifest-less/first-run migration the same way
+ * `harness uninstall` already does). Foreign entries (anything outside
+ * that union — an operator hand-add, or another tool's MCP server) are
+ * left untouched. Writes only when something actually changes.
+ *
+ * `lastApply` is read once, BEFORE `apply()` runs, by `wireRuntime`
+ * (`readPriorLastApply`, task 363a6de0 / D-107) and threaded through
+ * `wireClaudeMcp` rather than re-read here — both this function's
+ * pre-T-002 provenance check and GC's ownership-union construction need
+ * the SAME pre-apply snapshot (apply() re-stamps `.last-apply` with the
+ * current manifest whenever anything changed, which would otherwise be
+ * read back here as if it were "prior").
+ */
+function migrateDeadSettingsMcpBlock(o, manifest, lastApply) {
+    let raw;
+    try {
+        raw = fs.readFileSync(o.claudeSettingsPath, "utf8");
+    }
+    catch {
+        return []; // No settings.json (yet) — nothing to migrate.
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        o.stderr(`\n⚠ ${o.claudeSettingsPath} is not valid JSON; skipped the dead mcpServers cleanup. Fix the file and re-run \`harness init --interactive\`.\n`);
+        return [];
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        return [];
+    }
+    const ownedNames = new Set([
+        ...manifest.tools.mcp.map((m) => m.name),
+        ...priorGeneratedMcpNames(lastApply),
+        ...DEFAULT_OWNED_MCP_SERVERS,
+    ]);
+    const { settings, removedNames } = stripOwnedMcpServers(parsed, [...ownedNames]);
+    if (removedNames.length === 0)
+        return [];
+    atomicWriteFile(o.claudeSettingsPath, `${JSON.stringify(settings, null, 2)}\n`);
+    return removedNames;
+}
+/**
+ * Register the manifest's `tools.mcp[]` servers with Claude Code's
+ * user-scope registry via the `claude mcp` CLI (task
+ * init-mcp-wiring-claude-code/T-001/T-002), then — only once every
+ * desired server is confirmed correctly registered (D-002) — strip the
+ * dead settings.json `mcpServers` block. Mutates `outcome` in place so
+ * both the try and catch branches of the caller (the settings.json/hooks
+ * apply above) get the same MCP wiring regardless of whether that apply
+ * itself succeeded.
+ *
+ * `claude` CLI missing (`cli-missing`) is NOT a hard failure: the wizard
+ * warns, prints copy-pasteable `claude mcp add-json --scope user <name>
+ * '<json>'` commands per server, and continues — the manifest is on disk
+ * and hooks may already be wired even if MCP isn't yet. Migration is
+ * skipped in that case (and for any other incomplete registration) so a
+ * still-effective legacy settings.json entry is never removed out from
+ * under a server that couldn't be re-registered.
+ *
+ * Also drives GC (task 363a6de0): `ensureMcpServers`'s `gc` option is
+ * given the D-107 ownership union — the current manifest's `tools.mcp[]`
+ * names UNION the `tools.mcp[]` names of `priorLastApply` (the
+ * `.last-apply` manifest snapshot captured by the caller BEFORE this
+ * run's `apply()` ran, see `readPriorLastApply`) — so a server whose
+ * manifest entry was removed or disabled since it was last registered
+ * gets `claude mcp remove`d. `DEFAULT_OWNED_MCP_SERVERS` is DELIBERATELY
+ * NOT part of this union (D-107, reviewer HIGH finding on the original
+ * D-103): a server sharing a name with a harness default (grounding-mcp,
+ * agent-tasks, codebase-oracle) that the operator registered themselves
+ * — outside of, or before, any harness manifest on this machine — must
+ * never be GC'd just because it never appears in `desired`; "never in
+ * the manifest" is not the same ownership claim as "removed from the
+ * manifest". GC reporting is independent of the add/replace gate below —
+ * it runs, and is reported, regardless of whether the add/replace pass
+ * for `desired` succeeded.
+ */
+async function wireClaudeMcp(o, outcome, priorLastApply) {
+    const loaded = loadDesiredMcpServers(o.configPath, o.homeDir);
+    if (loaded === null) {
+        o.stderr(`\n⚠ Could not reload the manifest to register MCP servers with the claude CLI; skipped.\n`);
+        return;
+    }
+    for (const w of loaded.warnings)
+        o.stderr(`mcp warning: ${w}\n`);
+    // D-107: GC eligibility is manifest-provenance-based ONLY — current
+    // manifest names ∪ the pre-apply `.last-apply` snapshot's names.
+    // DEFAULT_OWNED_MCP_SERVERS is intentionally excluded here (see the
+    // function doc above); it remains the ownership source for the
+    // read-only paths below (dead-settings-block migration, detection).
+    const gcOwnedNames = [
+        ...new Set([
+            ...loaded.manifest.tools.mcp.map((m) => m.name),
+            ...priorManifestMcpNames(priorLastApply),
+        ]),
+    ];
+    const claudeHomeDir = path.dirname(o.claudeSettingsPath);
+    const ensureResult = await ensureMcpServers({
+        desired: loaded.desired,
+        homeDir: claudeHomeDir,
+        gc: { ownedNames: gcOwnedNames },
+        ...(o.mcpExec ? { exec: o.mcpExec } : {}),
+    });
+    outcome.mcpEnsure = ensureResult;
+    const gcResults = ensureResult.gc?.results ?? [];
+    const gcRemoved = gcResults.filter((r) => r.action === "removed");
+    const gcSkipped = gcResults.filter((r) => r.action === "skipped");
+    if (gcRemoved.length > 0) {
+        o.stderr(`deregistered ${gcRemoved.length} stale MCP server(s) no longer in the manifest ` +
+            `(user scope, claude CLI): ${gcRemoved.map((r) => r.name).join(", ")}\n`);
+    }
+    if (gcSkipped.length > 0) {
+        o.stderr([
+            "",
+            "⚠ Could not deregister one or more stale MCP server(s) via the `claude` CLI:",
+            ...gcSkipped.map((r) => `  ${r.name}: ${r.reason ?? r.remove.message}`),
+            "  Remove them yourself:",
+            ...manualRemoveLines(gcSkipped.map((r) => r.name)).map((l) => `    ${l}`),
+            "",
+        ].join("\n"));
+    }
+    if (ensureResult.gc?.registryReadError) {
+        o.stderr("⚠ Could not read the claude CLI user-scope registry to garbage-collect stale MCP " +
+            `servers: ${ensureResult.gc.registryReadError}\n`);
+    }
+    const actionable = ensureResult.results.filter((r) => r.action !== "noop");
+    const cliMissing = actionable.some((r) => r.add?.status === "cli-missing" || r.remove?.status === "cli-missing");
+    const allOk = ensureResult.results.every((r) => r.action === "noop" ||
+        ((r.action === "add" || r.action === "replace") && r.add?.status === "added"));
+    if (!allOk) {
+        if (cliMissing) {
+            o.stderr([
+                "",
+                "⚠ The `claude` CLI is not on PATH — MCP servers were not registered automatically.",
+                "  Install Claude Code, then register the manifest's MCP servers yourself:",
+                "",
+                ...manualAddJsonLines(Object.fromEntries(actionable.map((r) => [r.name, loaded.desired[r.name]]))).map((l) => `    ${l}`),
+                "",
+            ].join("\n"));
+        }
+        else {
+            o.stderr([
+                "",
+                "⚠ Registering one or more MCP servers with the `claude` CLI failed:",
+                ...actionable.map((r) => `  ${r.name}: ${r.add?.message ?? r.remove?.message ?? r.reason ?? r.action}`),
+                "",
+            ].join("\n"));
+        }
+        o.stderr("  Re-run `harness init --interactive` after fixing the issue to finish MCP registration and the settings.json cleanup.\n");
+        if (outcome.recoveryHint === undefined) {
+            outcome.recoveryHint =
+                "re-run `harness init --interactive` to finish registering MCP servers with the claude CLI";
+        }
+        return; // D-002: migration runs only after every desired server registers successfully.
+    }
+    if (actionable.length > 0) {
+        o.stderr(`\nregistered ${actionable.length} MCP server(s) with the claude CLI (user scope): ${actionable
+            .map((r) => r.name)
+            .join(", ")}\n`);
+    }
+    const removedNames = migrateDeadSettingsMcpBlock(o, loaded.manifest, priorLastApply);
+    if (removedNames.length > 0) {
+        outcome.mcpMigrationRemovedNames = removedNames;
+        o.stderr(`removed ${removedNames.length} dead mcpServers entr${removedNames.length === 1 ? "y" : "ies"} from ${o.claudeSettingsPath}: ${removedNames.join(", ")}\n`);
+    }
+}
 /**
  * Post-install auth check for the agent-tasks bridge. Probes the
  * bridge's `status` verb and, when no token is configured, offers the
@@ -322,8 +666,17 @@ async function ensureAgentTasksAuth(o) {
  * PATH) resolves `code: 1` rather than throwing, so the caller's
  * graceful-failure path handles a missing toolchain the same as a
  * non-zero exit.
+ *
+ * Hermetic guard (task 54739002): asserts BEFORE touching
+ * `child_process` that we are not running under vitest without a test
+ * having injected `owInitSpawn`. See
+ * src/runtime/hermetic-spawn-guard.ts for why and the env signal used.
+ * The thrown `HermeticSpawnViolationError` is re-thrown past the
+ * caller's try/catch (which otherwise degrades a thrown runner to a
+ * warning) — see the catch in offerOrchestratorWorkflow below.
  */
 function realOwInitSpawn(cmd, args) {
+    assertNoRealSpawnInTests("npx orchestrator-workflow init", "Inject a fake `owInitSpawn` runner in the test instead of exercising the real spawn path.");
     return new Promise((resolve) => {
         const child = spawn(cmd, args, { stdio: ["ignore", "inherit", "pipe"] });
         let stderr = "";
@@ -414,6 +767,12 @@ async function offerOrchestratorWorkflow(o) {
         result = await run("npx", ["orchestrator-workflow", "init", "--yes", o.repoDir]);
     }
     catch (err) {
+        // Hermetic guard (task 54739002): a real-spawn violation under
+        // vitest is NOT an ordinary runner failure — it must propagate past
+        // this optional-and-warn handling and fail the test hard, so it is
+        // re-thrown here before the generic degrade-to-warning below runs.
+        if (err instanceof HermeticSpawnViolationError)
+            throw err;
         // A thrown runner (an injected spawn that rejects, or an unexpected
         // throw) is treated exactly like a non-zero exit: OW is optional, so
         // we warn and continue rather than failing harness init.
@@ -498,7 +857,7 @@ export async function runInteractive(opts = {}) {
         }
         if (profileNeedsAgentTasks(profile) && !detectionHasAgentTasks(detection)) {
             const proceed = await prompts.confirm({
-                message: "The Team profile wires the agent-tasks MCP via the `agent-tasks-mcp-bridge` binary AND assumes you have an agent-tasks account (hosted or self-hosted). Claude's settings.json does not yet declare the MCP; the wizard will offer to install missing packages and wire it in a moment via `harness apply --target ~/.claude/settings.json --merge`. Proceed?",
+                message: "The Team profile wires the agent-tasks MCP via the `agent-tasks-mcp-bridge` binary AND assumes you have an agent-tasks account (hosted or self-hosted). It is not registered with Claude Code yet; the wizard will offer to install missing packages and register it in a moment via the `claude mcp` CLI (user scope). Proceed?",
                 default: true,
             });
             if (!proceed) {
@@ -590,6 +949,17 @@ export async function runInteractive(opts = {}) {
         if (homeArg !== undefined) {
             initOpts.homeDir = homeArg;
         }
+        // Task 7f8fb4bc: reuse the dependency-check PATH override (when a
+        // test supplies one) for `init()`'s own post-write bin-resolution
+        // check, so the two checks agree on what's "installed" for this run.
+        if (opts.dependencyPathEnv !== undefined) {
+            initOpts.pathEnv = opts.dependencyPathEnv;
+        }
+        // Task 325ace29: same forwarding for the `npm prefix -g` runner, so a
+        // test can keep `init()`'s bin-resolution check off the real npm.
+        if (opts.npmBinExec !== undefined) {
+            initOpts.npmBinExec = opts.npmBinExec;
+        }
         const initResult = await init(initOpts);
         stdout(initResult.stdout);
         const tailResult = await runPostInitTail({
@@ -617,6 +987,14 @@ export async function runInteractive(opts = {}) {
         return tailResult;
     }
     catch (err) {
+        // Defense-in-depth (task 54739002): a hermetic-spawn-guard violation
+        // must always propagate out of runInteractive as a hard failure.
+        // `isAbortError` below already wouldn't match a
+        // HermeticSpawnViolationError (it checks for an ExitPromptError/
+        // abort-shaped name), so this is belt-and-suspenders against a
+        // future change to isAbortError narrowing that behavior by name.
+        if (err instanceof HermeticSpawnViolationError)
+            throw err;
         if (isAbortError(err)) {
             stderr("Aborted: Ctrl-C received during prompt; no manifest written.\n");
             return { aborted: true };
@@ -645,6 +1023,17 @@ async function runPostInitTail(t) {
         stderr(`\nValidate reported errors. Fix the manifest before running \`harness apply\`.\n`);
         return { aborted: false, profile, init: initResult, validateClean };
     }
+    // Bin-resolution check (task 7f8fb4bc): validate() only checks the
+    // manifest's shape, not whether the binaries it declares actually
+    // resolve. A binary that installed successfully but landed under a npm
+    // global bin dir NOT on PATH (the dogfood incident this task fixes)
+    // passes validate cleanly and only used to surface as an opaque
+    // `harness doctor` crash later. `init()` itself already ran this check
+    // against the just-written manifest (threaded through `pathEnv` above)
+    // and folded any findings into `initResult.stderr`, printed at the top
+    // of this function — read its verdict here rather than re-running the
+    // check a second time with different (test-injection) plumbing.
+    const binResolutionClean = initResult.binResolutionErrorCount === 0;
     if (profile === "team" || profile === "full") {
         // Reminder splits at the "Not using agent-tasks?" paragraph because
         // Full ships review-before-merge-bash + review-subagent-before-pr-create-bash
@@ -711,14 +1100,31 @@ async function runPostInitTail(t) {
         ],
     }));
     if (selectedRuntimes.length === 0) {
+        // T-002: claude-code wiring is now two independent steps — the
+        // settings.json/hooks merge (still `harness apply --target ... --merge`)
+        // and MCP registration (via the `claude mcp` CLI, not settings.json;
+        // see io/claude-mcp.ts). There is no single non-interactive command for
+        // the latter yet, so print the manifest's per-server add-json commands
+        // directly — the same manual fallback the wizard itself prints when
+        // the `claude` CLI is missing.
+        const desiredMcp = loadDesiredMcpServers(initResult.path, harnessHomeArg(opts));
+        const mcpLines = desiredMcp !== null && Object.keys(desiredMcp.desired).length > 0
+            ? manualAddJsonLines(desiredMcp.desired)
+            : [];
         stderr([
             "",
             "Manifest written; no runtimes selected for wiring. To wire later:",
-            `  claude-code: harness apply --target ${claudeSettingsPath} --merge`,
+            `  claude-code hooks: harness apply --target ${claudeSettingsPath} --merge`,
+            ...(mcpLines.length > 0
+                ? [
+                    "  claude-code MCP:   re-run `harness init --interactive` and select claude-code, or run:",
+                    ...mcpLines.map((l) => `    ${l}`),
+                ]
+                : []),
             `  codex:       harness apply --runtime codex --install --codex-config ${codexConfigPath}`,
             "",
         ].join("\n"));
-        return { aborted: false, profile, init: initResult, validateClean, applies: [] };
+        return { aborted: false, profile, init: initResult, validateClean, binResolutionClean, applies: [] };
     }
     if (selectedRuntimes.length > 1) {
         stderr("\nMulti-runtime wiring: harness.lock will reflect the last-applied runtime; re-run `harness apply --runtime <name>` to refresh drift baselines.\n");
@@ -735,6 +1141,8 @@ async function runPostInitTail(t) {
         const homeArg = harnessHomeArg(opts);
         if (homeArg !== undefined)
             wireOpts.homeDir = homeArg;
+        if (opts.mcpExec)
+            wireOpts.mcpExec = opts.mcpExec;
         const outcome = await wireRuntime(wireOpts);
         applies.push(outcome);
     }
@@ -744,6 +1152,7 @@ async function runPostInitTail(t) {
         profile,
         init: initResult,
         validateClean,
+        binResolutionClean,
         applies,
     };
     if (legacyApply !== undefined)
@@ -883,6 +1292,12 @@ async function runCustomProfile(rc) {
     const homeArg = harnessHomeArg(opts);
     if (homeArg !== undefined)
         initOpts.homeDir = homeArg;
+    // Task 7f8fb4bc: see the named-profile path above for rationale.
+    if (opts.dependencyPathEnv !== undefined)
+        initOpts.pathEnv = opts.dependencyPathEnv;
+    // Task 325ace29: see the named-profile path above for rationale.
+    if (opts.npmBinExec !== undefined)
+        initOpts.npmBinExec = opts.npmBinExec;
     const initResult = await init(initOpts);
     stdout(initResult.stdout);
     return await runPostInitTail({