harnessed 3.0.1 → 3.0.3

package/dist/cli.mjs

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 import { execSync, spawnSync, spawn } from 'child_process';
-import { writeFileSync, existsSync, readFileSync, mkdirSync, appendFileSync, readdirSync } from 'fs';
-import { resolve, join, dirname, relative } from 'path';
+import { existsSync, mkdirSync, renameSync, writeFileSync, readFileSync, appendFileSync, readdirSync } from 'fs';
+import { join, resolve, dirname, relative } from 'path';
+import { homedir } from 'os';
 import { Type } from '@sinclair/typebox';
 import { Value } from '@sinclair/typebox/value';
 import { LineCounter, parseDocument, parse, isSeq, isScalar } from 'yaml';
-import { homedir } from 'os';
 import { readFile, readdir, unlink, writeFile, stat, rm, cp, access, mkdir, rename } from 'fs/promises';
 import lockfile from 'proper-lockfile';
 import { Command } from 'commander';
@@ -78,6 +78,46 @@ var init_origin_check = __esm({
   "src/cli/lib/origin-check.ts"() {
   }
 });
+function getHarnessedRoot() {
+  const override = process.env.HARNESSED_ROOT_OVERRIDE;
+  if (override !== void 0 && override !== "") return override;
+  return join(homedir(), ".claude", "harnessed");
+}
+function harnessedSubdir(name) {
+  return join(getHarnessedRoot(), name);
+}
+function harnessedFile(name) {
+  return join(getHarnessedRoot(), name);
+}
+function migrateLegacyHarnessedRoot() {
+  const legacyRoot = join(homedir(), ".harnessed");
+  const newRoot = join(homedir(), ".claude", "harnessed");
+  const claudeParent = join(homedir(), ".claude");
+  if (!existsSync(legacyRoot)) return;
+  if (!existsSync(newRoot)) {
+    mkdirSync(claudeParent, { recursive: true });
+    renameSync(legacyRoot, newRoot);
+    console.error(
+      `[harnessed] migrated legacy state directory ${legacyRoot} \u2192 ${newRoot} (v3.0.3 path change)`
+    );
+    return;
+  }
+  const safetyBak = join(homedir(), ".harnessed.legacy-bak");
+  if (existsSync(safetyBak)) {
+    console.error(
+      `[harnessed] WARN: ${legacyRoot} reappeared after a prior migration (existing bak at ${safetyBak}); leaving in place \u2014 inspect manually if needed`
+    );
+    return;
+  }
+  renameSync(legacyRoot, safetyBak);
+  console.error(
+    `[harnessed] both ${legacyRoot} and ${newRoot} existed \u2014 legacy directory preserved at ${safetyBak} (review manually if you need data from it; v3.0.3 path change)`
+  );
+}
+var init_harnessedRoot = __esm({
+  "src/installers/lib/harnessedRoot.ts"() {
+  }
+});
 
 // src/cli/lib/probe-gstack.ts
 var probe_gstack_exports = {};
@@ -408,7 +448,7 @@ function writeCheckpoint(c, customPath) {
     throw new CheckpointWriteError(`Schema validation failed: ${errs}`);
   }
   const enforced = enforceBudget(c);
-  const path = `.harnessed/checkpoints/${enforced.phase}.json`;
+  const path = join(harnessedSubdir("checkpoints"), `${enforced.phase}.json`);
   mkdirSync(dirname(path), { recursive: true });
   writeFileSync(path, JSON.stringify(enforced, null, 2), "utf8");
   return path;
@@ -416,6 +456,7 @@ function writeCheckpoint(c, customPath) {
 var BUDGET_TOKEN, CheckpointTooLargeError, CheckpointWriteError;
 var init_template = __esm({
   "src/checkpoint/template.ts"() {
+    init_harnessedRoot();
     init_schema();
     BUDGET_TOKEN = 1e3;
     CheckpointTooLargeError = class extends Error {
@@ -579,10 +620,25 @@ var init_check_planning_with_files = __esm({
     REMEDIATION = "install via Claude Code plugin marketplace: `claude plugin install planning-with-files` (requires >=2.2.0 per R20.15 + D-15)";
   }
 });
+function statePath() {
+  return harnessedFile("current-workflow.json");
+}
+function lockTarget() {
+  return getHarnessedRoot();
+}
+function lockOpts() {
+  return {
+    stale: 1e4,
+    retries: { retries: 3, factor: 2, minTimeout: 100 },
+    lockfilePath: harnessedFile(".lock")
+  };
+}
 async function withLock(fn) {
+  const target = lockTarget();
+  await mkdir(target, { recursive: true });
   let release;
   try {
-    release = await lockfile.lock(LOCK_TARGET, LOCK_OPTS);
+    release = await lockfile.lock(target, lockOpts());
   } catch (e) {
     if (e.code === "ELOCKED") throw new LockHeldError();
     throw e;
@@ -596,7 +652,7 @@ async function withLock(fn) {
 async function readCurrentWorkflow() {
   let raw;
   try {
-    raw = await readFile(STATE_PATH, "utf8");
+    raw = await readFile(statePath(), "utf8");
   } catch {
     return null;
   }
@@ -617,9 +673,10 @@ async function writeCurrentWorkflow(s) {
     const errs = [...Value.Errors(CurrentWorkflowV1, s)].map((e) => e.message).join("; ");
     throw new WorkflowStateError(`current-workflow schema validation failed: ${errs}`);
   }
-  await mkdir(dirname(STATE_PATH), { recursive: true });
+  const path = statePath();
+  await mkdir(dirname(path), { recursive: true });
   await withLock(async () => {
-    await writeFile(STATE_PATH, JSON.stringify(s, null, 2), "utf8");
+    await writeFile(path, JSON.stringify(s, null, 2), "utf8");
   });
 }
 async function activate(phase, checkpointPath = null) {
@@ -636,18 +693,12 @@ async function complete() {
   if (!s) return;
   await writeCurrentWorkflow({ ...s, status: "complete", completed_at: (/* @__PURE__ */ new Date()).toISOString() });
 }
-var STATE_PATH, LOCK_TARGET, LOCK_OPTS, WorkflowStateError, LockHeldError;
+var WorkflowStateError, LockHeldError;
 var init_state = __esm({
   "src/checkpoint/state.ts"() {
+    init_harnessedRoot();
     init_schemaVersion();
     init_schema();
-    STATE_PATH = ".harnessed/current-workflow.json";
-    LOCK_TARGET = ".harnessed";
-    LOCK_OPTS = {
-      stale: 1e4,
-      retries: { retries: 3, factor: 2, minTimeout: 100 },
-      lockfilePath: ".harnessed/.lock"
-    };
     WorkflowStateError = class extends Error {
       constructor(message) {
         super(message);
@@ -657,7 +708,7 @@ var init_state = __esm({
     LockHeldError = class _LockHeldError extends Error {
       constructor() {
         super(
-          "another harnessed process holds the lock at .harnessed/.lock \u2014 wait or kill stale process (try: harnessed status)"
+          `another harnessed process holds the lock at ${harnessedFile(".lock")} \u2014 wait or kill stale process (try: harnessed status)`
         );
         this.name = "LockHeldError";
         Object.setPrototypeOf(this, _LockHeldError.prototype);
@@ -740,7 +791,10 @@ __export(resume_exports, {
 async function runResume() {
   const current = await readCurrentWorkflow();
   if (!current) {
-    return { status: "no-paused-phase", error: "no .harnessed/current-workflow.json found" };
+    return {
+      status: "no-paused-phase",
+      error: "no current-workflow.json found under <harnessed-root>"
+    };
   }
   if (current.status !== "paused") {
     return {
@@ -793,7 +847,7 @@ var init_resume = __esm({
 
 // package.json
 var package_default = {
-  version: "3.0.1"};
+  version: "3.0.3"};
 
 // src/manifest/errors.ts
 function instancePathToKeyPath(instancePath) {
@@ -1546,7 +1600,12 @@ audited ${yamls.length} manifest${yamls.length === 1 ? "" : "s"} \u2014 ${findin
     process.exit(errorCount > 0 ? 1 : 0);
   });
 }
-var AUDIT_PATH = ".harnessed/audit.log";
+
+// src/cli/audit-log.ts
+init_harnessedRoot();
+function auditPath() {
+  return harnessedFile("audit.log");
+}
 var REDACT_PATTERNS = [
   [/api[_-]?key\s*[:=]\s*\S+/gi, "api_key=[REDACTED]"],
   [/\btoken\s*[:=]\s*\S+/gi, "token=[REDACTED]"],
@@ -1594,7 +1653,9 @@ function pipeToJq(filterExpr, lines) {
   });
 }
 function registerAuditLog(program2) {
-  program2.command("audit-log").description("Query routing audit log (.harnessed/audit.log) with optional jq filter (R10.1)").option("--filter <expr>", `jq filter expression (e.g. '.category=="engineering"')`).option("--tail <n>", "show N most recent records (default 50)", "50").option("--head <n>", "show N oldest records (--head takes priority over --tail)").option("--reverse", "flip output order").option("--json", "output full 12-field JSON instead of human table").action(
+  program2.command("audit-log").description(
+    "Query routing audit log (<harnessed-root>/audit.log) with optional jq filter (R10.1)"
+  ).option("--filter <expr>", `jq filter expression (e.g. '.category=="engineering"')`).option("--tail <n>", "show N most recent records (default 50)", "50").option("--head <n>", "show N oldest records (--head takes priority over --tail)").option("--reverse", "flip output order").option("--json", "output full 12-field JSON instead of human table").action(
     async (opts) => {
       const tailN = opts.tail !== void 0 ? Number(opts.tail) : 50;
       if (Number.isNaN(tailN) || tailN < 1) {
@@ -1606,11 +1667,12 @@ function registerAuditLog(program2) {
         console.error("\u2717 --head must be a positive integer");
         process.exit(2);
       }
-      if (!existsSync(AUDIT_PATH)) {
-        console.log("no audit records found (.harnessed/audit.log does not exist)");
+      const path = auditPath();
+      if (!existsSync(path)) {
+        console.log(`no audit records found (${path} does not exist)`);
         process.exit(0);
       }
-      const raw = readFileSync(AUDIT_PATH, "utf8");
+      const raw = readFileSync(path, "utf8");
       const lines = raw.split("\n").map((l) => l.trim()).filter((l) => l.length > 0);
       if (lines.length === 0) {
         console.log("no audit records found (audit.log is empty)");
@@ -1646,8 +1708,11 @@ function registerAuditLog(program2) {
     }
   );
 }
+
+// src/installers/lib/backup.ts
+init_harnessedRoot();
 function getBackupRoot() {
-  return join(homedir(), ".harnessed", "backups");
+  return harnessedSubdir("backups");
 }
 var HOME_DIR = process.env.HOME ?? process.env.USERPROFILE ?? "";
 function mirrorPath(target, scope, backupDir) {
@@ -2317,7 +2382,12 @@ function matchesWhen(when, task) {
   }
   return true;
 }
-var AUDIT_PATH2 = ".harnessed/audit.log";
+
+// src/audit/log.ts
+init_harnessedRoot();
+function auditPath2() {
+  return harnessedFile("audit.log");
+}
 Type.Object(
   {
     ts: Type.String(),
@@ -2352,8 +2422,9 @@ function buildAuditRecord(task, decision, matched, ctx) {
   };
 }
 function emitAuditRecord(record) {
-  mkdirSync(dirname(AUDIT_PATH2), { recursive: true });
-  appendFileSync(AUDIT_PATH2, `${JSON.stringify(record)}
+  const path = auditPath2();
+  mkdirSync(dirname(path), { recursive: true });
+  appendFileSync(path, `${JSON.stringify(record)}
 `);
 }
 
@@ -2371,18 +2442,19 @@ function emitAudit(task, decision, matched, outcome, sessionId) {
 }
 
 // src/checkpoint/engineHook.ts
+init_harnessedRoot();
 init_schemaVersion();
 init_state();
 init_template();
 async function activatePhase(phaseId) {
-  const checkpointPath = `.harnessed/checkpoints/${phaseId}.json`;
+  const checkpointPath = join(harnessedSubdir("checkpoints"), `${phaseId}.json`);
   await activate(phaseId, checkpointPath);
   return { checkpointPath };
 }
 async function completePhase(ctx) {
   if (ctx.phaseId === "unknown") {
     console.error(
-      '[harnessed] WARN engineHook: phaseId="unknown" \u2014 checkpoint paths fall back to .harnessed/checkpoints/unknown.json (Karpathy fail-loud non-blocking; W-04 mitigation)'
+      `[harnessed] WARN engineHook: phaseId="unknown" \u2014 checkpoint paths fall back to ${join(harnessedSubdir("checkpoints"), "unknown.json")} (Karpathy fail-loud non-blocking; W-04 mitigation)`
     );
   }
   writeCheckpoint({
@@ -2395,7 +2467,7 @@ async function completePhase(ctx) {
     ...ctx.sessionId ? { session_id: ctx.sessionId } : {},
     cwd: process.cwd(),
     timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-    archive_path: `.harnessed/archive/phase-${ctx.phaseId}/`
+    archive_path: `${join(harnessedSubdir("archive"), `phase-${ctx.phaseId}`)}/`
   });
   await complete();
 }
@@ -2479,11 +2551,11 @@ var VerbatimCompleteFailError = class extends Error {
   }
   lastMessage;
 };
-async function ralphLoopWrap(spawn9, maxIter) {
+async function ralphLoopWrap(spawn6, maxIter) {
   let last = "";
   let sessionId;
   for (let i = 0; i < maxIter; i++) {
-    last = await spawn9(sessionId, (id) => {
+    last = await spawn6(sessionId, (id) => {
       sessionId = id;
     });
     if (isComplete(last)) return last;
@@ -3239,12 +3311,15 @@ function preflight(ctx) {
   }
   return { ok: errors.length === 0, errors };
 }
+
+// src/installers/lib/state.ts
+init_harnessedRoot();
 var DEFAULT_STATE = { version: "1", installed: {} };
-function statePath(cwd) {
-  return join(cwd, ".harnessed", "state.json");
+function statePath2(_cwd) {
+  return harnessedFile("state.json");
 }
 async function readState(cwd) {
-  const path = statePath(cwd);
+  const path = statePath2();
   let raw;
   try {
     raw = await readFile(path, "utf8");
@@ -3265,7 +3340,7 @@ async function readState(cwd) {
   }
 }
 async function writeState(cwd, state) {
-  const path = statePath(cwd);
+  const path = statePath2();
   const tmp = `${path}.tmp`;
   await mkdir(dirname(path), { recursive: true });
   await writeFile(tmp, `${JSON.stringify(state, null, 2)}
@@ -3273,7 +3348,7 @@ async function writeState(cwd, state) {
   await rename(tmp, path);
 }
 async function updateInstalled(cwd, name, version, manifestSha1) {
-  const state = await readState(cwd);
+  const state = await readState();
   state.installed[name] = {
     version,
     installedAt: (/* @__PURE__ */ new Date()).toISOString(),
@@ -3382,6 +3457,39 @@ var installCcHookAdd = async (ctx) => {
   await updateInstalled(ctx.cwd, ctx.manifest.metadata.name, "", "");
   return { ok: true, backupId: bk.backupId, appliedFiles: [settingsPath] };
 };
+function getUserClaudeJsonPath() {
+  return join(homedir(), ".claude.json");
+}
+async function readUserClaudeJson() {
+  const path = getUserClaudeJsonPath();
+  let raw;
+  try {
+    raw = await readFile(path, "utf8");
+  } catch (err2) {
+    if (err2.code === "ENOENT") return {};
+    throw err2;
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed === null || typeof parsed !== "object") return {};
+    return parsed;
+  } catch {
+    return {};
+  }
+}
+async function isMcpServerRegistered(name) {
+  const config = await readUserClaudeJson();
+  const servers = config.mcpServers;
+  if (!servers || typeof servers !== "object") return false;
+  return Object.hasOwn(servers, name);
+}
+async function isPluginRegistered(pluginName) {
+  const config = await readUserClaudeJson();
+  const plugins = config.enabledPlugins;
+  if (!plugins || typeof plugins !== "object") return false;
+  if (Object.hasOwn(plugins, pluginName)) return true;
+  return Object.keys(plugins).some((k) => k.split("@")[0] === pluginName);
+}
 function runArgs(claudeArgs, cwd, timeoutMs = 15e3) {
   return new Promise((resolve9) => {
     const isWin = process.platform === "win32";
@@ -3404,6 +3512,9 @@ function runArgs(claudeArgs, cwd, timeoutMs = 15e3) {
     });
   });
 }
+function getMcpSpawnCwd() {
+  return homedir();
+}
 
 // src/installers/ccPluginMarketplace.ts
 function parseCmd(cmd) {
@@ -3455,8 +3566,8 @@ var installCcPluginMarketplace = async (ctx) => {
       }
     };
   }
-  const pluginName = parsed.pluginAtMkt.split("@")[0];
-  const installArgs = ["plugin", "install", parsed.pluginAtMkt, "--scope", "project"];
+  const pluginName = parsed.pluginAtMkt.split("@")[0] ?? parsed.pluginAtMkt;
+  const installArgs = ["plugin", "install", parsed.pluginAtMkt, "--scope", "user"];
   const allArgs = [];
   if (parsed.marketplaceRef !== null) {
     allArgs.push(["plugin", "marketplace", "add", parsed.marketplaceRef]);
@@ -3464,30 +3575,30 @@ var installCcPluginMarketplace = async (ctx) => {
   allArgs.push(installArgs);
   for (const argSet of allArgs) {
     for (const a of argSet) {
-      const violation2 = checkCmdString(a);
-      if (violation2) {
+      const violation = checkCmdString(a);
+      if (violation) {
         return {
           ok: false,
           phase: "preflight",
           error: err(
             ctx,
             "/spec/install/cmd",
-            `shell escape detected in constructed cc-plugin arg '${a.slice(0, 60)}': ${violation2.label} (${violation2.hint})`,
+            `shell escape detected in constructed cc-plugin arg '${a.slice(0, 60)}': ${violation.label} (${violation.hint})`,
             "security-gate-bypass"
           )
         };
       }
     }
   }
-  const settingsFile = `${ctx.cwd}/.claude/settings.json`;
+  const settingsFile = `${getMcpSpawnCwd()}/.claude.json`;
   const newEntry = JSON.stringify({ enabledPlugins: { [parsed.pluginAtMkt]: true } }, null, 2);
   const plan = {
     files: [
       {
         target: settingsFile,
-        scope: "PROJECT",
+        scope: "HOME",
         oldText: "",
-        newText: `// will be merged into .claude/settings.json enabledPlugins map by \`claude plugin install\`:
+        newText: `// will be merged into ~/.claude.json enabledPlugins map by \`claude plugin install --scope user\`:
 ${newEntry}
 `
       }
@@ -3502,15 +3613,13 @@ ${newEntry}
   if (ctx.opts.dryRun) return { aborted: true, reason: "user-cancel" };
   const bk = await backup(plan, ctx);
   if (!bk.ok) return { ok: false, phase: "preflight", error: bk.error };
+  const spawnCwd = install.cwd ?? getMcpSpawnCwd();
   let stepOneStderr = "";
   if (parsed.marketplaceRef !== null) {
-    const r1 = await runArgs(
-      ["plugin", "marketplace", "add", parsed.marketplaceRef],
-      install.cwd ?? ctx.cwd
-    );
+    const r1 = await runArgs(["plugin", "marketplace", "add", parsed.marketplaceRef], spawnCwd);
     stepOneStderr = r1.stderr;
   }
-  const r2 = await runArgs(installArgs, install.cwd ?? ctx.cwd);
+  const r2 = await runArgs(installArgs, spawnCwd);
   if (r2.exitCode !== 0) {
     return {
       ok: false,
@@ -3524,11 +3633,8 @@ ${newEntry}
       )
     };
   }
-  const verifyShell = process.platform === "win32" ? "cmd.exe" : "/bin/sh";
-  const verifyFlag = process.platform === "win32" ? "/c" : "-c";
-  const verifyLine = `claude plugin list --json | grep -q ${pluginName}`;
-  const violation = checkCmdString(verifyLine);
-  if (violation) {
+  const registered = await isPluginRegistered(pluginName);
+  if (!registered) {
     return {
       ok: false,
       phase: "verify",
@@ -3536,39 +3642,7 @@ ${newEntry}
       error: err(
         ctx,
         "/spec/verify/cmd",
-        `verify shell escape: ${violation.label}`,
-        "security-gate-bypass"
-      )
-    };
-  }
-  const vr = await new Promise((resolve9) => {
-    const child = spawn(verifyShell, [verifyFlag, verifyLine], { cwd: ctx.cwd, windowsHide: true });
-    let stderr = "";
-    child.stderr?.setEncoding("utf8").on("data", (c) => {
-      stderr += c;
-    });
-    const timer = setTimeout(() => {
-      child.kill("SIGKILL");
-      resolve9({ exitCode: -1, stderr: `${stderr}[timeout]` });
-    }, 15e3);
-    child.on("error", (e) => {
-      clearTimeout(timer);
-      resolve9({ exitCode: -1, stderr: e.message });
-    });
-    child.on("close", (code) => {
-      clearTimeout(timer);
-      resolve9({ exitCode: code ?? -1, stderr });
-    });
-  });
-  if (vr.exitCode !== 0) {
-    return {
-      ok: false,
-      phase: "verify",
-      backupId: bk.backupId,
-      error: err(
-        ctx,
-        "/spec/verify/cmd",
-        `verify exit ${vr.exitCode}: ${vr.stderr.slice(0, 200)}`,
+        `verify: plugin '${pluginName}' not found in enabledPlugins map of ~/.claude.json after install spawn exit 0 (file may have been overwritten, or claude plugin install wrote to a non-default location)`,
         "verify-failed"
       )
     };
@@ -3576,8 +3650,9 @@ ${newEntry}
   await updateInstalled(ctx.cwd, ctx.manifest.metadata.name, install.git_ref, "");
   return { ok: true, backupId: bk.backupId, appliedFiles: [settingsFile] };
 };
-var DEFAULT_TIMEOUT_MS = 15e3;
-async function spawnCmd(ctx, cmd, args) {
+var DEFAULT_VERIFY_TIMEOUT_MS = 15e3;
+var DEFAULT_INSTALL_TIMEOUT_MS = 6e4;
+async function spawnCmd(ctx, cmd, args, timeoutMs) {
   const violation = checkCmdString(cmd);
   if (violation) {
     return {
@@ -3594,8 +3669,7 @@ async function spawnCmd(ctx, cmd, args) {
     };
   }
   const installCfg = ctx.manifest.spec.install;
-  const verifyCfg = ctx.manifest.spec.verify;
-  const timeoutMs = verifyCfg.timeout_ms ?? DEFAULT_TIMEOUT_MS;
+  const effectiveTimeoutMs = timeoutMs ?? DEFAULT_INSTALL_TIMEOUT_MS;
   const env = { ...process.env, ...installCfg.env ?? {} };
   const cwd = installCfg.cwd ?? ctx.cwd;
   let child;
@@ -3622,13 +3696,13 @@ async function spawnCmd(ctx, cmd, args) {
         error: {
           file: ctx.manifest.metadata.name,
           path: "/spec/install/cmd",
-          message: `spawn timed out after ${timeoutMs}ms (cmd: ${cmd}); partial stderr: ${stderr.slice(0, 200)}`,
+          message: `spawn timed out after ${effectiveTimeoutMs}ms (cmd: ${cmd}); partial stderr: ${stderr.slice(0, 200)}`,
           line: null,
           column: null,
           keyword: "spawn-timeout"
         }
       });
-    }, timeoutMs);
+    }, effectiveTimeoutMs);
     child.on("error", (err2) => {
       clearTimeout(timer);
       resolve9({
@@ -3774,7 +3848,7 @@ var installGitCloneWithSetup = async (ctx) => {
   if (ctx.opts.dryRun) return { aborted: true, reason: "user-cancel" };
   const bk = await backup(plan, ctx);
   if (!bk.ok) return { ok: false, phase: "preflight", error: bk.error };
-  const sp = await spawnCmd(ctx, install.cmd, []);
+  const sp = await spawnCmd(ctx, install.cmd, [], DEFAULT_INSTALL_TIMEOUT_MS);
   if (!("exitCode" in sp)) return { ...sp, backupId: bk.backupId };
   if (sp.exitCode !== 0) {
     return {
@@ -3816,7 +3890,8 @@ var installGitCloneWithSetup = async (ctx) => {
       )
     };
   }
-  const vr = await spawnCmd(ctx, ctx.manifest.spec.verify.cmd, []);
+  const verifyTimeoutMs = ctx.manifest.spec.verify.timeout_ms ?? DEFAULT_VERIFY_TIMEOUT_MS;
+  const vr = await spawnCmd(ctx, ctx.manifest.spec.verify.cmd, [], verifyTimeoutMs);
   if (!("exitCode" in vr)) return { ...vr, backupId: bk.backupId };
   const expected = ctx.manifest.spec.verify.expected_exit_code ?? 0;
   if (vr.exitCode !== expected) {
@@ -3835,6 +3910,8 @@ var installGitCloneWithSetup = async (ctx) => {
   await updateInstalled(ctx.cwd, name, install.git_ref, "");
   return { ok: true, backupId: bk.backupId, appliedFiles: [cloneTarget] };
 };
+
+// src/installers/mcpHttpAdd.ts
 function resolveEnvVars(value) {
   const pattern = /\$\{([A-Z_][A-Z0-9_]*)\}/g;
   let resolved = value;
@@ -3919,33 +3996,23 @@ var installMcpHttpAdd = async (ctx) => {
       }
     };
   }
-  const addArgs = [
-    "mcp",
-    "add",
-    "--scope",
-    "project",
-    "--transport",
-    "http",
-    ...hdr.flat,
-    name,
-    url
-  ];
+  const addArgs = ["mcp", "add", "--scope", "user", "--transport", "http", ...hdr.flat, name, url];
   for (const a of addArgs) {
-    const violation2 = checkCmdString(a);
-    if (violation2) {
+    const violation = checkCmdString(a);
+    if (violation) {
       return {
         ok: false,
         phase: "preflight",
         error: err(
           ctx,
           "/spec/install/cmd",
-          `shell escape detected in constructed mcp-http-add arg '${a.slice(0, 60)}': ${violation2.label} (${violation2.hint})`,
+          `shell escape detected in constructed mcp-http-add arg '${a.slice(0, 60)}': ${violation.label} (${violation.hint})`,
           "security-gate-bypass"
         )
       };
     }
   }
-  const mcpFile = `${ctx.cwd}/.mcp.json`;
+  const mcpFile = `${getMcpSpawnCwd()}/.claude.json`;
   const headersObj = {};
   for (let i = 0; i < hdr.flat.length; i += 2) {
     const kv = hdr.flat[i + 1];
@@ -3959,9 +4026,9 @@ var installMcpHttpAdd = async (ctx) => {
     files: [
       {
         target: mcpFile,
-        scope: "PROJECT",
+        scope: "HOME",
         oldText: "",
-        newText: `// will be merged into .mcp.json mcpServers map by \`claude mcp add\`:
+        newText: `// will be merged into ~/.claude.json mcpServers map by \`claude mcp add --scope user\`:
 ${newEntry}
 `
       }
@@ -3976,9 +4043,10 @@ ${newEntry}
   if (ctx.opts.dryRun) return { aborted: true, reason: "user-cancel" };
   const bk = await backup(plan, ctx);
   if (!bk.ok) return { ok: false, phase: "preflight", error: bk.error };
-  const r = await runArgs(addArgs, install.cwd ?? ctx.cwd);
+  const spawnCwd = install.cwd ?? getMcpSpawnCwd();
+  const r = await runArgs(addArgs, spawnCwd);
   if (r.exitCode !== 0) {
-    if (r.stderr.includes("already exists in .mcp.json")) {
+    if (r.stderr.includes("already exists")) {
       return { ok: true, alreadyInstalled: true, backupId: bk.backupId };
     }
     return {
@@ -3993,43 +4061,8 @@ ${newEntry}
       )
     };
   }
-  const verifyShell = process.platform === "win32" ? "cmd.exe" : "/bin/sh";
-  const verifyFlag = process.platform === "win32" ? "/c" : "-c";
-  const verifyLine = `claude mcp list | grep -q ${name}`;
-  const violation = checkCmdString(verifyLine);
-  if (violation) {
-    return {
-      ok: false,
-      phase: "verify",
-      backupId: bk.backupId,
-      error: err(
-        ctx,
-        "/spec/verify/cmd",
-        `verify shell escape: ${violation.label}`,
-        "security-gate-bypass"
-      )
-    };
-  }
-  const vr = await new Promise((resolve9) => {
-    const child = spawn(verifyShell, [verifyFlag, verifyLine], { cwd: ctx.cwd, windowsHide: true });
-    let stderr = "";
-    child.stderr?.setEncoding("utf8").on("data", (c) => {
-      stderr += c;
-    });
-    const timer = setTimeout(() => {
-      child.kill("SIGKILL");
-      resolve9({ exitCode: -1, stderr: `${stderr}[timeout]` });
-    }, 15e3);
-    child.on("error", (e) => {
-      clearTimeout(timer);
-      resolve9({ exitCode: -1, stderr: e.message });
-    });
-    child.on("close", (code) => {
-      clearTimeout(timer);
-      resolve9({ exitCode: code ?? -1, stderr });
-    });
-  });
-  if (vr.exitCode !== 0) {
+  const registered = await isMcpServerRegistered(name);
+  if (!registered) {
     return {
       ok: false,
       phase: "verify",
@@ -4037,7 +4070,7 @@ ${newEntry}
       error: err(
         ctx,
         "/spec/verify/cmd",
-        `verify exit ${vr.exitCode}: ${vr.stderr.slice(0, 200)}`,
+        `verify: '${name}' not found in mcpServers map of ~/.claude.json after install spawn exit 0 (file may have been overwritten, or claude mcp add wrote to a non-default location)`,
         "verify-failed"
       )
     };
@@ -4045,6 +4078,8 @@ ${newEntry}
   await updateInstalled(ctx.cwd, name, install.npm_version, "");
   return { ok: true, backupId: bk.backupId, appliedFiles: [mcpFile] };
 };
+
+// src/installers/mcpStdioAdd.ts
 var installMcpStdioAdd = async (ctx) => {
   const install = ctx.manifest.spec.install;
   if (install.method !== "mcp-stdio-add") {
@@ -4073,7 +4108,7 @@ var installMcpStdioAdd = async (ctx) => {
     "mcp",
     "add",
     "--scope",
-    "project",
+    "user",
     "--transport",
     "stdio",
     name,
@@ -4083,21 +4118,21 @@ var installMcpStdioAdd = async (ctx) => {
     `${pkg}@${ver}`
   ];
   for (const a of addArgs) {
-    const violation2 = checkCmdString(a);
-    if (violation2) {
+    const violation = checkCmdString(a);
+    if (violation) {
       return {
         ok: false,
         phase: "preflight",
         error: err(
           ctx,
           "/spec/install/cmd",
-          `shell escape detected in constructed mcp-add arg '${a.slice(0, 60)}': ${violation2.label} (${violation2.hint})`,
+          `shell escape detected in constructed mcp-add arg '${a.slice(0, 60)}': ${violation.label} (${violation.hint})`,
           "security-gate-bypass"
         )
       };
     }
   }
-  const mcpFile = `${ctx.cwd}/.mcp.json`;
+  const mcpFile = `${getMcpSpawnCwd()}/.claude.json`;
   const newEntry = JSON.stringify(
     { [name]: { type: "stdio", command: "npx", args: ["--yes", `${pkg}@${ver}`] } },
     null,
@@ -4107,9 +4142,9 @@ var installMcpStdioAdd = async (ctx) => {
     files: [
       {
         target: mcpFile,
-        scope: "PROJECT",
+        scope: "HOME",
         oldText: "",
-        newText: `// will be merged into .mcp.json mcpServers map by \`claude mcp add\`:
+        newText: `// will be merged into ~/.claude.json mcpServers map by \`claude mcp add --scope user\`:
 ${newEntry}
 `
       }
@@ -4124,9 +4159,10 @@ ${newEntry}
   if (ctx.opts.dryRun) return { aborted: true, reason: "user-cancel" };
   const bk = await backup(plan, ctx);
   if (!bk.ok) return { ok: false, phase: "preflight", error: bk.error };
-  const r = await runArgs(addArgs, install.cwd ?? ctx.cwd);
+  const spawnCwd = install.cwd ?? getMcpSpawnCwd();
+  const r = await runArgs(addArgs, spawnCwd);
   if (r.exitCode !== 0) {
-    if (r.stderr.includes("already exists in .mcp.json")) {
+    if (r.stderr.includes("already exists")) {
       return { ok: true, alreadyInstalled: true, backupId: bk.backupId };
     }
     return {
@@ -4141,11 +4177,8 @@ ${newEntry}
       )
     };
   }
-  const verifyShell = process.platform === "win32" ? "cmd.exe" : "/bin/sh";
-  const verifyFlag = process.platform === "win32" ? "/c" : "-c";
-  const verifyLine = `claude mcp list | grep -q ${name}`;
-  const violation = checkCmdString(verifyLine);
-  if (violation) {
+  const registered = await isMcpServerRegistered(name);
+  if (!registered) {
     return {
       ok: false,
       phase: "verify",
@@ -4153,39 +4186,7 @@ ${newEntry}
       error: err(
         ctx,
         "/spec/verify/cmd",
-        `verify shell escape: ${violation.label}`,
-        "security-gate-bypass"
-      )
-    };
-  }
-  const vr = await new Promise((resolve9) => {
-    const child = spawn(verifyShell, [verifyFlag, verifyLine], { cwd: ctx.cwd, windowsHide: true });
-    let stderr = "";
-    child.stderr?.setEncoding("utf8").on("data", (c) => {
-      stderr += c;
-    });
-    const timer = setTimeout(() => {
-      child.kill("SIGKILL");
-      resolve9({ exitCode: -1, stderr: `${stderr}[timeout]` });
-    }, 15e3);
-    child.on("error", (e) => {
-      clearTimeout(timer);
-      resolve9({ exitCode: -1, stderr: e.message });
-    });
-    child.on("close", (code) => {
-      clearTimeout(timer);
-      resolve9({ exitCode: code ?? -1, stderr });
-    });
-  });
-  if (vr.exitCode !== 0) {
-    return {
-      ok: false,
-      phase: "verify",
-      backupId: bk.backupId,
-      error: err(
-        ctx,
-        "/spec/verify/cmd",
-        `verify exit ${vr.exitCode}: ${vr.stderr.slice(0, 200)}`,
+        `verify: '${name}' not found in mcpServers map of ~/.claude.json after install spawn exit 0 (file may have been overwritten, or claude mcp add wrote to a non-default location)`,
         "verify-failed"
       )
     };
@@ -4251,7 +4252,7 @@ var installNpmCli = async (ctx) => {
   if (ctx.opts.dryRun) return { aborted: true, reason: "user-cancel" };
   const bk = await backup(plan, ctx);
   if (!bk.ok) return { ok: false, phase: "preflight", error: bk.error };
-  const sp = await spawnCmd(ctx, cmd, []);
+  const sp = await spawnCmd(ctx, cmd, [], DEFAULT_INSTALL_TIMEOUT_MS);
   if (!("exitCode" in sp)) return { ...sp, backupId: bk.backupId };
   if (sp.exitCode !== 0) {
     return {
@@ -4266,7 +4267,8 @@ var installNpmCli = async (ctx) => {
       )
     };
   }
-  const vr = await spawnCmd(ctx, ctx.manifest.spec.verify.cmd, []);
+  const verifyTimeoutMs = ctx.manifest.spec.verify.timeout_ms ?? DEFAULT_VERIFY_TIMEOUT_MS;
+  const vr = await spawnCmd(ctx, ctx.manifest.spec.verify.cmd, [], verifyTimeoutMs);
   if (!("exitCode" in vr)) return { ...vr, backupId: bk.backupId };
   const expected = ctx.manifest.spec.verify.expected_exit_code ?? 0;
   if (vr.exitCode !== expected) {
@@ -4367,7 +4369,7 @@ var installNpxSkillInstaller = async (ctx) => {
   if (ctx.opts.dryRun) return { aborted: true, reason: "user-cancel" };
   const bk = await backup(plan, ctx);
   if (!bk.ok) return { ok: false, phase: "preflight", error: bk.error };
-  const sp = await spawnCmd(ctx, install.cmd, []);
+  const sp = await spawnCmd(ctx, install.cmd, [], DEFAULT_INSTALL_TIMEOUT_MS);
   if (!("exitCode" in sp)) return { ...sp, backupId: bk.backupId };
   if (sp.exitCode !== 0) {
     return {
@@ -4400,7 +4402,8 @@ var installNpxSkillInstaller = async (ctx) => {
       }
     };
   }
-  const vr = await spawnCmd(ctx, ctx.manifest.spec.verify.cmd, []);
+  const verifyTimeoutMs = ctx.manifest.spec.verify.timeout_ms ?? DEFAULT_VERIFY_TIMEOUT_MS;
+  const vr = await spawnCmd(ctx, ctx.manifest.spec.verify.cmd, [], verifyTimeoutMs);
   if (!("exitCode" in vr)) return { ...vr, backupId: bk.backupId };
   const expected = ctx.manifest.spec.verify.expected_exit_code ?? 0;
   if (vr.exitCode !== expected) {
@@ -4896,7 +4899,7 @@ async function warnIfAgentTeamsMissing() {
   console.warn("\n\u26A0\uFE0F  Agent Teams \u672A\u542F\u7528 \u2014 parallelism-gate \u5347\u7EA7\u8DEF\u5F84\u4E0D\u53EF\u7528");
   console.warn("   \u4FEE\u590D: claude config set env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 1");
   console.warn(
-    "   \u8BF4\u660E: harnessed v2.0 \u4E09\u5C42\u6808\u65B9\u6CD5\u8BBA parallelism-gate \u5347\u7EA7\u8DEF\u5F84\u9700 CC 2.1.133+ Agent Teams enable (sister ~/.claude/rules/agent-teams.md)"
+    "   \u8BF4\u660E: harnessed v3.0 \u4E09\u5C42\u6808\u65B9\u6CD5\u8BBA parallelism-gate \u5347\u7EA7\u8DEF\u5F84\u9700 CC 2.1.133+ Agent Teams enable"
   );
   console.warn(
     "   \u4E0D\u963B\u585E setup,\u540E\u7EED parallelism-gate workflow phase \u89E6\u53D1\u65F6\u81EA\u52A8\u964D\u7EA7 subagent fan-out\n"
@@ -5052,7 +5055,7 @@ MCP servers configured. Run \`/mcp\` in Claude Code to verify each server's conn
       );
     }
     console.log(
-      "\n\u2713 harnessed v2.0 \u4E09\u5C42\u6808\u65B9\u6CD5\u8BBA bundled \u2014 4 workflows + 6 judgments + 37 capabilities ready"
+      "\n\u2713 harnessed v3.0 \u4E09\u5C42\u6808\u65B9\u6CD5\u8BBA bundled \u2014 23 workflows (4 master + 18 sub + 1 standalone) + 6 disciplines + 10 judgments + ~83 capabilities ready"
     );
     console.log(
       "  workflows in <packageRoot>/workflows/ (Pure bundled, NOT user-dir override per D-01)"
@@ -5060,12 +5063,15 @@ MCP servers configured. Run \`/mcp\` in Claude Code to verify each server's conn
     process.exit(0);
   });
 }
+
+// src/cli/status.ts
+init_harnessedRoot();
 function registerStatus(program2) {
-  program2.command("status").description("Show installed upstreams (from .harnessed/state.json)").action(async () => {
+  program2.command("status").description("Show installed upstreams (from <harnessed-root>/state.json)").action(async () => {
     const state = await readState(process.cwd());
     const names = Object.keys(state.installed).sort();
     if (names.length === 0) {
-      console.log("no installs recorded (.harnessed/state.json absent or empty)");
+      console.log(`no installs recorded (${harnessedFile("state.json")} absent or empty)`);
     } else {
       for (const n of names) {
         const e = state.installed[n];
@@ -5075,18 +5081,19 @@ function registerStatus(program2) {
       console.log(`
 ${names.length} install${names.length === 1 ? "" : "s"} recorded`);
     }
+    const lockPath = harnessedFile(".lock");
     try {
-      const isLocked = await lockfile.check(".harnessed", {
-        lockfilePath: ".harnessed/.lock",
+      const isLocked = await lockfile.check(getHarnessedRoot(), {
+        lockfilePath: lockPath,
         stale: 1e4
       });
       if (isLocked) {
-        const s = await stat(".harnessed/.lock");
+        const s = await stat(lockPath);
         const ageMs = Date.now() - s.mtime.getTime();
         const stale = ageMs > 1e4;
         console.log(`
 lock: held (since ${s.mtime.toISOString()})${stale ? " \u2014 STALE" : ""}`);
-        console.log("  to release: wait for process to finish or delete .harnessed/.lock");
+        console.log(`  to release: wait for process to finish or delete ${lockPath}`);
       } else {
         console.log("\nlock: free");
       }
@@ -5415,6 +5422,8 @@ function registerUninstall(program2) {
 }
 
 // src/cli.ts
+init_harnessedRoot();
+migrateLegacyHarnessedRoot();
 var program = new Command();
 program.name("harnessed").description("AI coding harness package manager + composition orchestrator").version(package_default.version);
 registerInstall(program);