harnessed 1.0.3 → 2.0.0

package/dist/cli.mjs

@@ -148,8 +148,8 @@ var init_path_guard = __esm({
   }
 });
 function branchOnSchemaVersion(v, handlers) {
-  const isKnownV1 = Object.values(SCHEMA_VERSIONS).includes(v);
-  return isKnownV1 ? handlers.v1() : handlers.unknown();
+  const isKnownVersion = Object.values(SCHEMA_VERSIONS).includes(v);
+  return isKnownVersion ? handlers.v1() : handlers.unknown();
 }
 var SCHEMA_VERSIONS;
 var init_schemaVersion = __esm({
@@ -172,8 +172,14 @@ var init_schemaVersion = __esm({
       // ← Phase 3.3 W0 T0.5 BACKFILL 11th surface (sister Phase 3.2 W2 T2.2 b875e21 commit msg claim "11th surface" was LATENT STALE — never registered; T0.5 surgical fix per sister Phase 3.2 W2 T2.6 latent W1 c37ee29 Rule 1 pattern)
       aliases: "harnessed.aliases.v1",
       // ← Phase 3.3 W1 T1.1 ADD 12th surface (D-01 RICH manifests/aliases.yaml upstream rename redirect + metadata)
-      knownGood: "harnessed.known-good.v1"
+      knownGood: "harnessed.known-good.v1",
       // ← Phase 3.3 W1 T1.1 ADD 13th surface (D-03 YAML versions/<harnessed-ver>-known-good.yaml per-version lock)
+      capabilities: "harnessed.capabilities.v1",
+      // ← Phase v2.0-2.3 W0 T2.3.W0.6 ADD 14th surface (R20.2 flat yaml capabilities manifest validate)
+      judgment: "harnessed.judgment.v1",
+      // ← Phase v2.0-2.3 W0 T2.3.W0.6 ADD 15th surface (R20.4 multi-file judgments triggers/rules validate)
+      workflow: "harnessed.workflow.v2"
+      // ← Phase v2.0-2.4 W0 T2.4.W0.1 ADD 16th surface (R20.1 + R20.2 + R20.9 — workflow.yaml v2 schema: gate / on / capability / args / fallback / parallelism 字段, sister 4 workflow.yaml: plan-feature + execute-task + research + verify-work)
     };
     Type.Union([
       Type.Literal(SCHEMA_VERSIONS.routingSnapshot),
@@ -193,8 +199,14 @@ var init_schemaVersion = __esm({
       // ← Phase 3.3 W0 T0.5 BACKFILL 11th surface
       Type.Literal(SCHEMA_VERSIONS.aliases),
       // ← Phase 3.3 W1 T1.1 ADD 12th surface
-      Type.Literal(SCHEMA_VERSIONS.knownGood)
+      Type.Literal(SCHEMA_VERSIONS.knownGood),
       // ← Phase 3.3 W1 T1.1 ADD 13th surface
+      Type.Literal(SCHEMA_VERSIONS.capabilities),
+      // ← Phase v2.0-2.3 W0 T2.3.W0.6 ADD 14th surface
+      Type.Literal(SCHEMA_VERSIONS.judgment),
+      // ← Phase v2.0-2.3 W0 T2.3.W0.6 ADD 15th surface
+      Type.Literal(SCHEMA_VERSIONS.workflow)
+      // ← Phase v2.0-2.4 W0 T2.4.W0.1 ADD 16th surface (workflow.yaml v2 schema, NOTE first .v2 surface in union)
     ]);
   }
 });
@@ -456,6 +468,109 @@ var init_check_token_budget = __esm({
     PER_SKILL_THRESHOLD = 5e3;
   }
 });
+async function checkAgentTeams() {
+  const envValue = process.env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS;
+  const envOn = envValue === "1";
+  let settingsValue;
+  let settingsOn = false;
+  try {
+    const path = resolve(homedir(), ".claude", "settings.json");
+    const raw = await readFile(path, "utf8");
+    const data = JSON.parse(raw);
+    settingsValue = data.env?.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS;
+    settingsOn = settingsValue === "1";
+  } catch {
+  }
+  const detected = { env: envOn, settingsJson: settingsOn };
+  if (envOn || settingsOn) {
+    return { status: "pass", detected, envValue, settingsValue };
+  }
+  return {
+    status: "missing",
+    detected,
+    envValue,
+    settingsValue,
+    remediation: 'Agent Teams not enabled. Add to ~/.claude/settings.json:\n  "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" }\nOR run: claude config set env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 1\nOR export env var:\n  export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1\nThen restart Claude Code (CC >= 2.1.133 required).'
+  };
+}
+var init_checkAgentTeams = __esm({
+  "src/cli/lib/checkAgentTeams.ts"() {
+  }
+});
+
+// src/cli/lib/check-agent-teams-doctor.ts
+var check_agent_teams_doctor_exports = {};
+__export(check_agent_teams_doctor_exports, {
+  checkAgentTeamsDoctor: () => checkAgentTeamsDoctor
+});
+async function checkAgentTeamsDoctor() {
+  const r = await checkAgentTeams();
+  if (r.status === "pass") {
+    const source = r.detected.env ? "env var" : "settings.json";
+    return {
+      name: "Agent Teams env",
+      status: "pass",
+      message: `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 (${source})`
+    };
+  }
+  return {
+    name: "Agent Teams env",
+    status: "warn",
+    message: "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS not set (Agent Teams disabled)",
+    fix: r.remediation
+  };
+}
+var init_check_agent_teams_doctor = __esm({
+  "src/cli/lib/check-agent-teams-doctor.ts"() {
+    init_checkAgentTeams();
+  }
+});
+
+// src/cli/lib/check-planning-with-files.ts
+var check_planning_with_files_exports = {};
+__export(check_planning_with_files_exports, {
+  checkPlanningWithFiles: () => checkPlanningWithFiles
+});
+async function checkPlanningWithFiles() {
+  const root = join(
+    homedir(),
+    ".claude",
+    "plugins",
+    "cache",
+    "planning-with-files",
+    "planning-with-files"
+  );
+  try {
+    const entries = await readdir(root);
+    const versions = entries.filter((e) => /^\d+\.\d+/.test(e));
+    if (versions.length > 0) {
+      return {
+        name: "planning-with-files plugin",
+        status: "pass",
+        message: `installed (version ${versions.join(", ")})`
+      };
+    }
+    return {
+      name: "planning-with-files plugin",
+      status: "warn",
+      message: "plugin directory exists but no version subdir found",
+      fix: REMEDIATION
+    };
+  } catch {
+    return {
+      name: "planning-with-files plugin",
+      status: "warn",
+      message: "not installed (plugin cache path missing)",
+      fix: REMEDIATION
+    };
+  }
+}
+var REMEDIATION;
+var init_check_planning_with_files = __esm({
+  "src/cli/lib/check-planning-with-files.ts"() {
+    REMEDIATION = "install via Claude Code plugin marketplace: `claude plugin install planning-with-files` (requires >=2.2.0 per R20.15 + D-15)";
+  }
+});
 async function withLock(fn) {
   let release;
   try {
@@ -670,7 +785,7 @@ var init_resume = __esm({
 
 // package.json
 var package_default = {
-  version: "1.0.3"};
+  version: "2.0.0"};
 
 // src/manifest/errors.ts
 function instancePathToKeyPath(instancePath) {
@@ -1451,7 +1566,7 @@ function renderHumanTable(records) {
   }
 }
 function pipeToJq(filterExpr, lines) {
-  return new Promise((resolve10, reject) => {
+  return new Promise((resolve11, reject) => {
     const child = spawn("jq", [filterExpr], {
       stdio: ["pipe", "inherit", "inherit"],
       windowsHide: true
@@ -1460,12 +1575,12 @@ function pipeToJq(filterExpr, lines) {
       const e = err2;
       if (e.code === "ENOENT") {
         console.error("\u2717 jq not found in PATH \u2014 run: harnessed doctor");
-        resolve10(1);
+        resolve11(1);
       } else {
         reject(err2);
       }
     });
-    child.on("close", (code) => resolve10(code ?? 0));
+    child.on("close", (code) => resolve11(code ?? 0));
     child.stdin.write(lines.join("\n"));
     child.stdin.end();
   });
@@ -1649,29 +1764,36 @@ async function checkDeprecations2() {
 async function checkTokenBudget2() {
   return (await Promise.resolve().then(() => (init_check_token_budget(), check_token_budget_exports))).checkTokenBudget();
 }
+async function checkAgentTeamsEnv() {
+  return (await Promise.resolve().then(() => (init_check_agent_teams_doctor(), check_agent_teams_doctor_exports))).checkAgentTeamsDoctor();
+}
+async function checkPlanningPlugin() {
+  return (await Promise.resolve().then(() => (init_check_planning_with_files(), check_planning_with_files_exports))).checkPlanningWithFiles();
+}
 function registerDoctor(program2) {
   program2.command("doctor").description(
-    "Preflight checks (Node / MCP scope / jq / Win bash / origin URL / gstack prefix / deprecations / token budget)"
+    "Preflight checks (Node / MCP scope / jq / Win bash / origin URL / gstack prefix / deprecations / token budget / Agent Teams / planning-with-files)"
   ).option("--json", "output JSON instead of human-readable").action(async (opts) => {
-    const [mcpScope, originUrl, gstackPrefix, deprecations, tokenBudget] = await Promise.all([
+    const [mcp, origin, gstack, dep, tok, at, ppwf] = await Promise.all([
       checkMcpScope(),
       checkOriginUrl(),
       checkGstackPrefix(),
-      // ← Phase 3.2 W1 T1.5 ADD 6th check (D-01 PROBE)
       checkDeprecations2(),
-      // ← Phase 3.3 W1 T1.7 ADD 7th check (D-02 DOCTOR-ONLY-WARN)
-      checkTokenBudget2()
-      // ← Phase 3.4 W1 T1.2 ADD 8th check (D-03 + D-04 DOCTOR WARN)
+      checkTokenBudget2(),
+      checkAgentTeamsEnv(),
+      checkPlanningPlugin()
     ]);
     const results = [
       checkNodeVersion(),
-      mcpScope,
+      mcp,
       checkJq(),
       checkWinBash(),
-      originUrl,
-      gstackPrefix,
-      deprecations,
-      tokenBudget
+      origin,
+      gstack,
+      dep,
+      tok,
+      at,
+      ppwf
     ];
     const hasFail = results.some((r) => r.status === "fail");
     const hasWarn = results.some((r) => r.status === "warn");
@@ -2056,6 +2178,51 @@ async function completePhase(ctx) {
   await complete();
 }
 
+// src/routing/lib/fallbackHandlers.ts
+function handleMaxIterationsExceeded(err2, fallback, ctx) {
+  const yamlShort = fallback.message.replace(
+    /\{\{\s*args\.max_iterations\s*\}\}/g,
+    String(ctx.maxIterations)
+  );
+  const truncated = (ctx.lastMessage ?? "<empty>").slice(0, 500);
+  const uxText = `\u274C ralph-loop max-iterations exceeded (${err2.iterations}/${ctx.maxIterations}).
+Sub-task: ${ctx.subtaskSummary}
+Workflow: ${ctx.workflowName} / phase ${ctx.phaseId}
+Last subagent output (truncated): ${truncated}
+The subagent attempted ${err2.iterations} iterations without emitting verbatim "<promise>COMPLETE</promise>".
+This indicates one of:
+  1. Sub-task is genuinely incomplete (escalate to user / re-scope)
+  2. Subagent is stuck in a loop (review prompt / system instructions)
+  3. max-iterations too low (override via --max-iterations <N>, hard upper limit 100)
+Manual options:
+  A) Continue with current state: \`harnessed workflow resume --skip-completion-gate\`
+  B) Re-run from last checkpoint: \`harnessed workflow resume --from-checkpoint\`
+  C) Abort cleanly: exit 1
+Exit code: ${fallback.exit_code}
+${yamlShort}`;
+  console.error(uxText);
+  process.exit(fallback.exit_code);
+  throw new Error("unreachable");
+}
+function handleVerbatimCompleteFail(err2, fallback, ctx) {
+  const truncated = err2.lastMessage.slice(0, 500);
+  const uxText = `\u274C ralph-loop verbatim COMPLETE signal missing (F33 P1).
+Sub-task: ${ctx.subtaskSummary}
+Workflow: ${ctx.workflowName} / phase ${ctx.phaseId}
+Last subagent output (truncated): ${truncated}
+The subagent's final message lacked verbatim "<promise>COMPLETE</promise>" tag.
+This indicates one of:
+  1. Subagent skipped the completion-promise contract (review system prompt)
+  2. Output format misconfigured (check outputFormat schema)
+Manual options:
+  A) Re-run with explicit COMPLETE instruction in subagent prompt
+  B) Abort cleanly: exit ${fallback.exit_code}
+Exit code: ${fallback.exit_code}`;
+  console.error(uxText);
+  process.exit(fallback.exit_code);
+  throw new Error("unreachable");
+}
+
 // src/routing/lib/promiseExtract.ts
 var PROMISE_PATTERN = /<promise>([^<]+)<\/promise>/;
 function extractPromise(text) {
@@ -2265,9 +2432,6 @@ async function runRouting(task, opts = {}) {
   try {
     await ensureSkillsInstalled(decision.required_skills ?? [], skillsRoot);
   } catch (error) {
-    if (error instanceof RestartRequiredError || error instanceof SkillNotInstalledError || error instanceof MissingSkillsError) {
-      return { ok: false, phase: "install", error };
-    }
     return { ok: false, phase: "install", error };
   }
   let agentDef;
@@ -2294,6 +2458,11 @@ async function runRouting(task, opts = {}) {
       onSessionIdInner?.(id);
     }
   });
+  const fbCtx = {
+    subtaskSummary: task.task,
+    workflowName: task.task_type ?? "unknown",
+    phaseId: opts.fallbackPhaseId ?? task.phaseId ?? "unknown"
+  };
   try {
     const result = await ralphLoopWrap(wrappedSpawn, maxIter);
     await completePhase({ phaseId, sessionId: capturedSessionId, status: "complete" });
@@ -2302,10 +2471,16 @@ async function runRouting(task, opts = {}) {
   } catch (error) {
     if (error instanceof MaxIterationsExceededError) {
       emitAudit(task, decision, matched, "max-iter", capturedSessionId);
+      if (opts.fallbackConfig)
+        handleMaxIterationsExceeded(error, opts.fallbackConfig, {
+          ...fbCtx,
+          maxIterations: maxIter
+        });
       return { aborted: true, reason: error.message };
     }
     if (error instanceof VerbatimCompleteFailError) {
       emitAudit(task, decision, matched, "verbatim-fail", capturedSessionId);
+      if (opts.fallbackConfig) handleVerbatimCompleteFail(error, opts.fallbackConfig, fbCtx);
       return { ok: false, phase: "verbatim", error };
     }
     emitAudit(task, decision, matched, "spawn-err", capturedSessionId);
@@ -2346,6 +2521,70 @@ var PhasesSchema = Type.Object(
   { additionalProperties: false }
 );
 
+// src/workflow/schema/workflow.ts
+init_schemaVersion();
+var ModelTier2 = Type.Union([Type.Literal("haiku"), Type.Literal("sonnet"), Type.Literal("opus")]);
+var OnAction = Type.Union([Type.Literal("skip"), Type.Literal("invoke")]);
+var OnClause = Type.Object(
+  {
+    if: Type.String(),
+    // expr-eval expression OR judgments.<file>.<gate>.fires ref
+    invoke: Type.Optional(Type.String()),
+    // '{{ capabilities.<name>.cmd }}' OR literal
+    action: Type.Optional(OnAction)
+  },
+  { additionalProperties: false }
+);
+var FallbackMaxIterationsExceeded = Type.Object(
+  {
+    action: Type.Literal("emit_warning_and_halt"),
+    // R20.10 acceptance c "explicit NOT silent"
+    message: Type.String(),
+    exit_code: Type.Number()
+  },
+  { additionalProperties: false }
+);
+var PhaseFallback = Type.Object(
+  {
+    max_iterations_exceeded: Type.Optional(FallbackMaxIterationsExceeded)
+  },
+  { additionalProperties: false }
+);
+var WorkflowPhaseV2 = Type.Object(
+  {
+    id: Type.String({ minLength: 1 }),
+    name: Type.Optional(Type.String()),
+    upstream: Type.Optional(Type.String()),
+    capability: Type.Optional(Type.String()),
+    // '{{ capabilities.ralph-loop.cmd }}'
+    model: Type.Optional(ModelTier2),
+    invokes: Type.Optional(Type.String()),
+    // legacy slash-cmd OR JINJA template
+    args: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
+    gate: Type.Optional(Type.String()),
+    // judgments.<file>.<gate>.fires 4-level ref
+    on: Type.Optional(Type.Array(OnClause)),
+    parallelism: Type.Optional(Type.String()),
+    // judgments.parallelism-gate.<route>.fires
+    fallback: Type.Optional(PhaseFallback),
+    max_iterations: Type.Optional(
+      Type.Union([Type.Number(), Type.String()])
+      // numeric literal OR jinja '{{ defaults.x.y }}'
+    ),
+    artifacts_expected: Type.Optional(Type.Array(Type.String()))
+  },
+  { additionalProperties: false }
+);
+var WorkflowSchemaV2 = Type.Object(
+  {
+    schema_version: Type.Literal(SCHEMA_VERSIONS.workflow),
+    workflow: Type.String({ minLength: 1 }),
+    description: Type.Optional(Type.String()),
+    phases: Type.Array(WorkflowPhaseV2, { minItems: 1 })
+  },
+  { additionalProperties: false }
+);
+
 // src/workflow/loadPhases.ts
 var PhasesValidationError = class extends Error {
   constructor(errors) {
@@ -2358,10 +2597,18 @@ var PhasesValidationError = class extends Error {
 function loadPhases(yamlPath, vars) {
   const raw = readFileSync(yamlPath, "utf8");
   const parsed = parse(raw);
-  if (!Value.Check(PhasesSchema, parsed)) {
-    throw new PhasesValidationError([...Value.Errors(PhasesSchema, parsed)]);
+  const isV2 = parsed?.schema_version === "harnessed.workflow.v2";
+  if (isV2) {
+    if (!Value.Check(WorkflowSchemaV2, parsed)) {
+      throw new PhasesValidationError([...Value.Errors(WorkflowSchemaV2, parsed)]);
+    }
+  } else {
+    if (!Value.Check(PhasesSchema, parsed)) {
+      throw new PhasesValidationError([...Value.Errors(PhasesSchema, parsed)]);
+    }
   }
-  return parsed;
+  const validated = parsed;
+  return validated;
 }
 
 // src/cli/lib/validateFlags.ts
@@ -2407,9 +2654,20 @@ function registerExecuteTask(program2) {
       );
       process.exit(0);
     }
+    let fallbackConfig;
+    let fallbackPhaseId;
+    for (const ph of phases.phases) {
+      if ("fallback" in ph && ph.fallback?.max_iterations_exceeded) {
+        fallbackConfig = ph.fallback.max_iterations_exceeded;
+        fallbackPhaseId = ph.id;
+        break;
+      }
+    }
     const result = await runRouting(taskCtx, {
       maxIterations: raw.maxIterations ?? 20,
-      ...raw.model ? { agentOpts: { modelOverride: raw.model } } : {}
+      ...raw.model ? { agentOpts: { modelOverride: raw.model } } : {},
+      ...fallbackConfig ? { fallbackConfig } : {},
+      ...fallbackPhaseId ? { fallbackPhaseId } : {}
     });
     if ("aborted" in result) {
       console.error(`aborted: ${result.reason}`);
@@ -2894,7 +3152,7 @@ var installCcHookAdd = async (ctx) => {
   return { ok: true, backupId: bk.backupId, appliedFiles: [settingsPath] };
 };
 function runArgs(claudeArgs, cwd, timeoutMs = 15e3) {
-  return new Promise((resolve10) => {
+  return new Promise((resolve11) => {
     const isWin = process.platform === "win32";
     const child = isWin ? spawn("cmd.exe", ["/c", "claude", ...claudeArgs], { cwd, windowsHide: true }) : spawn("claude", claudeArgs, { cwd, shell: false });
     let stderr = "";
@@ -2903,15 +3161,15 @@ function runArgs(claudeArgs, cwd, timeoutMs = 15e3) {
     });
     const timer = setTimeout(() => {
       child.kill("SIGKILL");
-      resolve10({ exitCode: -1, stderr: `${stderr}[timeout after ${timeoutMs}ms]` });
+      resolve11({ exitCode: -1, stderr: `${stderr}[timeout after ${timeoutMs}ms]` });
     }, timeoutMs);
     child.on("error", (e) => {
       clearTimeout(timer);
-      resolve10({ exitCode: -1, stderr: `${stderr}${e.message}` });
+      resolve11({ exitCode: -1, stderr: `${stderr}${e.message}` });
     });
     child.on("close", (code) => {
       clearTimeout(timer);
-      resolve10({ exitCode: code ?? -1, stderr });
+      resolve11({ exitCode: code ?? -1, stderr });
     });
   });
 }
@@ -3052,7 +3310,7 @@ ${newEntry}
       )
     };
   }
-  const vr = await new Promise((resolve10) => {
+  const vr = await new Promise((resolve11) => {
     const child = spawn(verifyShell, [verifyFlag, verifyLine], { cwd: ctx.cwd, windowsHide: true });
     let stderr = "";
     child.stderr?.setEncoding("utf8").on("data", (c) => {
@@ -3060,15 +3318,15 @@ ${newEntry}
     });
     const timer = setTimeout(() => {
       child.kill("SIGKILL");
-      resolve10({ exitCode: -1, stderr: `${stderr}[timeout]` });
+      resolve11({ exitCode: -1, stderr: `${stderr}[timeout]` });
     }, 15e3);
     child.on("error", (e) => {
       clearTimeout(timer);
-      resolve10({ exitCode: -1, stderr: e.message });
+      resolve11({ exitCode: -1, stderr: e.message });
     });
     child.on("close", (code) => {
       clearTimeout(timer);
-      resolve10({ exitCode: code ?? -1, stderr });
+      resolve11({ exitCode: code ?? -1, stderr });
     });
   });
   if (vr.exitCode !== 0) {
@@ -3124,10 +3382,10 @@ async function spawnCmd(ctx, cmd, args) {
   child.stderr?.setEncoding("utf8").on("data", (chunk) => {
     stderr += chunk;
   });
-  return await new Promise((resolve10) => {
+  return await new Promise((resolve11) => {
     const timer = setTimeout(() => {
       child.kill("SIGKILL");
-      resolve10({
+      resolve11({
         ok: false,
         phase: "spawn",
         error: {
@@ -3142,7 +3400,7 @@ async function spawnCmd(ctx, cmd, args) {
     }, timeoutMs);
     child.on("error", (err2) => {
       clearTimeout(timer);
-      resolve10({
+      resolve11({
         ok: false,
         phase: "spawn",
         error: {
@@ -3157,14 +3415,14 @@ async function spawnCmd(ctx, cmd, args) {
     });
     child.on("close", (code) => {
       clearTimeout(timer);
-      resolve10({ ok: true, exitCode: code ?? -1, stdout: stdout2, stderr });
+      resolve11({ ok: true, exitCode: code ?? -1, stdout: stdout2, stderr });
     });
   });
 }
 
 // src/installers/gitCloneWithSetup.ts
 function gitRevParseHead(cwd, timeoutMs = 1e4) {
-  return new Promise((resolve10) => {
+  return new Promise((resolve11) => {
     const isWin = process.platform === "win32";
     const child = isWin ? spawn("cmd.exe", ["/c", "git", "rev-parse", "HEAD"], { cwd, windowsHide: true }) : spawn("git", ["rev-parse", "HEAD"], { cwd, shell: false });
     let stdout2 = "";
@@ -3173,15 +3431,15 @@ function gitRevParseHead(cwd, timeoutMs = 1e4) {
     });
     const timer = setTimeout(() => {
       child.kill("SIGKILL");
-      resolve10({ sha: "", exit: -1 });
+      resolve11({ sha: "", exit: -1 });
     }, timeoutMs);
     child.on("error", () => {
       clearTimeout(timer);
-      resolve10({ sha: "", exit: -1 });
+      resolve11({ sha: "", exit: -1 });
     });
     child.on("close", (code) => {
       clearTimeout(timer);
-      resolve10({ sha: stdout2.trim(), exit: code ?? -1 });
+      resolve11({ sha: stdout2.trim(), exit: code ?? -1 });
     });
   });
 }
@@ -3489,6 +3747,9 @@ ${newEntry}
   if (!bk.ok) return { ok: false, phase: "preflight", error: bk.error };
   const r = await runArgs(addArgs, install.cwd ?? ctx.cwd);
   if (r.exitCode !== 0) {
+    if (r.stderr.includes("already exists in .mcp.json")) {
+      return { ok: true, alreadyInstalled: true, backupId: bk.backupId };
+    }
     return {
       ok: false,
       phase: "spawn",
@@ -3518,7 +3779,7 @@ ${newEntry}
       )
     };
   }
-  const vr = await new Promise((resolve10) => {
+  const vr = await new Promise((resolve11) => {
     const child = spawn(verifyShell, [verifyFlag, verifyLine], { cwd: ctx.cwd, windowsHide: true });
     let stderr = "";
     child.stderr?.setEncoding("utf8").on("data", (c) => {
@@ -3526,15 +3787,15 @@ ${newEntry}
     });
     const timer = setTimeout(() => {
       child.kill("SIGKILL");
-      resolve10({ exitCode: -1, stderr: `${stderr}[timeout]` });
+      resolve11({ exitCode: -1, stderr: `${stderr}[timeout]` });
     }, 15e3);
     child.on("error", (e) => {
       clearTimeout(timer);
-      resolve10({ exitCode: -1, stderr: e.message });
+      resolve11({ exitCode: -1, stderr: e.message });
     });
     child.on("close", (code) => {
       clearTimeout(timer);
-      resolve10({ exitCode: code ?? -1, stderr });
+      resolve11({ exitCode: code ?? -1, stderr });
     });
   });
   if (vr.exitCode !== 0) {
@@ -3634,6 +3895,9 @@ ${newEntry}
   if (!bk.ok) return { ok: false, phase: "preflight", error: bk.error };
   const r = await runArgs(addArgs, install.cwd ?? ctx.cwd);
   if (r.exitCode !== 0) {
+    if (r.stderr.includes("already exists in .mcp.json")) {
+      return { ok: true, alreadyInstalled: true, backupId: bk.backupId };
+    }
     return {
       ok: false,
       phase: "spawn",
@@ -3663,7 +3927,7 @@ ${newEntry}
       )
     };
   }
-  const vr = await new Promise((resolve10) => {
+  const vr = await new Promise((resolve11) => {
     const child = spawn(verifyShell, [verifyFlag, verifyLine], { cwd: ctx.cwd, windowsHide: true });
     let stderr = "";
     child.stderr?.setEncoding("utf8").on("data", (c) => {
@@ -3671,15 +3935,15 @@ ${newEntry}
     });
     const timer = setTimeout(() => {
       child.kill("SIGKILL");
-      resolve10({ exitCode: -1, stderr: `${stderr}[timeout]` });
+      resolve11({ exitCode: -1, stderr: `${stderr}[timeout]` });
     }, 15e3);
     child.on("error", (e) => {
       clearTimeout(timer);
-      resolve10({ exitCode: -1, stderr: e.message });
+      resolve11({ exitCode: -1, stderr: e.message });
     });
     child.on("close", (code) => {
       clearTimeout(timer);
-      resolve10({ exitCode: code ?? -1, stderr });
+      resolve11({ exitCode: code ?? -1, stderr });
     });
   });
   if (vr.exitCode !== 0) {
@@ -4068,6 +4332,7 @@ function registerInstallBase(program2) {
       color: "auto"
     };
     const installed = [];
+    const alreadyInstalled = [];
     const skipped = [];
     const failed = [];
     for (const path of await listBaseManifests(getPackageRoot())) {
@@ -4091,18 +4356,21 @@ function registerInstallBase(program2) {
       }
       const r = await runInstall(v.manifest, opts);
       if ("aborted" in r) skipped.push({ name, reason: `aborted: ${r.reason}` });
+      else if (r.ok && "alreadyInstalled" in r && r.alreadyInstalled) alreadyInstalled.push(name);
       else if (r.ok) installed.push(name);
       else failed.push({ name, reason: r.error.message });
     }
     console.log(
       `
-  installed: ${installed.length} / skipped (deferred phase 2.1): ${skipped.length} / failed: ${failed.length}`
+  installed: ${installed.length} / already-installed: ${alreadyInstalled.length} / skipped (deferred phase 2.1): ${skipped.length} / failed: ${failed.length}`
     );
-    for (const i of installed) console.log(`  installed  ${i}`);
-    for (const s of skipped) console.log(`  skipped    ${s.name} \u2014 ${s.reason}`);
-    for (const f of failed) console.error(`  failed     ${f.name} \u2014 ${f.reason}`);
+    for (const i of installed) console.log(`  installed          ${i}`);
+    for (const a of alreadyInstalled)
+      console.log(`  already-installed  ${a} \u2014 run \`/mcp\` in Claude Code to verify connection`);
+    for (const s of skipped) console.log(`  skipped            ${s.name} \u2014 ${s.reason}`);
+    for (const f of failed) console.error(`  failed             ${f.name} \u2014 ${f.reason}`);
     if (failed.length > 0) process.exit(1);
-    if (installed.length === 0) process.exit(2);
+    if (installed.length === 0 && alreadyInstalled.length === 0) process.exit(2);
     process.exit(0);
   });
 }
@@ -4288,12 +4556,96 @@ function registerRollback(program2) {
     console.log(`restored ${meta.files.length} file(s) from ${timestamp}`);
   });
 }
+init_checkAgentTeams();
 var PHASE_212 = /* @__PURE__ */ new Set([
   "cc-plugin-marketplace",
   "git-clone-with-setup",
   "npx-skill-installer",
   "mcp-http-add"
 ]);
+async function warnIfAgentTeamsMissing() {
+  const r = await checkAgentTeams();
+  if (r.status !== "missing") return;
+  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)"
+  );
+  console.warn(
+    "   \u4E0D\u963B\u585E setup,\u540E\u7EED parallelism-gate workflow phase \u89E6\u53D1\u65F6\u81EA\u52A8\u964D\u7EA7 subagent fan-out\n"
+  );
+}
+async function scanWorkflowsWithSkill(workflowsDir, entries) {
+  const out = [];
+  for (const entry of entries.sort()) {
+    const src = join(workflowsDir, entry);
+    try {
+      const s = await stat(src);
+      if (!s.isDirectory()) continue;
+      await stat(join(src, "SKILL.md"));
+      out.push(entry);
+    } catch {
+    }
+  }
+  return out;
+}
+async function runStepBInstall(manifestPaths) {
+  const opts = {
+    apply: true,
+    dryRun: false,
+    system: false,
+    nonInteractive: true,
+    fullDiff: false,
+    color: "auto"
+  };
+  const start = Date.now();
+  const settled = await Promise.allSettled(
+    manifestPaths.map(async (path) => {
+      let yamlSrc;
+      try {
+        yamlSrc = await readFile(path, "utf8");
+      } catch (e) {
+        return { status: "failed", name: path, reason: `read: ${e.message}` };
+      }
+      const v = validateManifestFile(yamlSrc, path);
+      if (!v.ok) {
+        return {
+          status: "failed",
+          name: path,
+          reason: `validate: ${v.errors[0]?.message ?? "unknown"}`
+        };
+      }
+      const name = v.manifest.metadata.name;
+      const method = v.manifest.spec.install.method;
+      if (PHASE_212.has(method)) return { status: "skipped", name };
+      const r = await runInstall(v.manifest, opts);
+      if ("aborted" in r) return { status: "skipped", name };
+      if (r.ok && "alreadyInstalled" in r && r.alreadyInstalled)
+        return { status: "already-installed", name };
+      if (r.ok) return { status: "installed", name };
+      return { status: "failed", name, reason: r.error.message };
+    })
+  );
+  const installed = [];
+  const alreadyInstalled = [];
+  const skipped = [];
+  const failed = [];
+  for (const s of settled) {
+    const v = s.status === "fulfilled" ? s.value : {
+      status: "failed",
+      name: "?",
+      reason: String(s.reason)
+    };
+    if (v.status === "installed") installed.push(v.name);
+    else if (v.status === "already-installed") alreadyInstalled.push(v.name);
+    else if (v.status === "skipped") skipped.push(v.name);
+    else
+      failed.push(`${v.name}: ${v.reason}`);
+  }
+  return { installed, alreadyInstalled, skipped, failed, elapsedMs: Date.now() - start };
+}
+
+// src/cli/setup.ts
 async function listBaseManifests2(pkgRoot) {
   const out = [];
   for (const d of ["manifests/tools", "manifests/skill-packs"]) {
@@ -4313,6 +4665,7 @@ function registerSetup(program2) {
     const pkgRoot = getPackageRoot();
     const workflowsDir = resolve(pkgRoot, "workflows");
     const skillsBase = resolve(homedir(), ".claude", "skills");
+    await warnIfAgentTeamsMissing();
     let entries;
     try {
       entries = await readdir(workflowsDir);
@@ -4320,17 +4673,7 @@ function registerSetup(program2) {
       console.error(`error: workflows directory not found at ${workflowsDir}`);
       process.exit(1);
     }
-    const toInstall = [];
-    for (const entry of entries.sort()) {
-      const src = join(workflowsDir, entry);
-      try {
-        const s = await stat(src);
-        if (!s.isDirectory()) continue;
-        await stat(join(src, "SKILL.md"));
-        toInstall.push(entry);
-      } catch {
-      }
-    }
+    const toInstall = await scanWorkflowsWithSkill(workflowsDir, entries);
     if (toInstall.length === 0) {
       console.log("setup: no workflow directories with SKILL.md found \u2014 nothing to install");
       process.exit(2);
@@ -4362,73 +4705,34 @@ function registerSetup(program2) {
       `
 Step A complete: ${skillsInstalled} workflow skill(s) installed to ${skillsBase}`
     );
-    const opts = {
-      apply: true,
-      dryRun: false,
-      system: false,
-      nonInteractive: true,
-      fullDiff: false,
-      color: "auto"
-    };
     const manifestPaths = await listBaseManifests2(pkgRoot);
-    const stepBStart = Date.now();
-    const settled = await Promise.allSettled(
-      manifestPaths.map(async (path) => {
-        let yamlSrc;
-        try {
-          yamlSrc = await readFile(path, "utf8");
-        } catch (e) {
-          return {
-            status: "failed",
-            name: path,
-            reason: `read: ${e.message}`
-          };
-        }
-        const v = validateManifestFile(yamlSrc, path);
-        if (!v.ok) {
-          return {
-            status: "failed",
-            name: path,
-            reason: `validate: ${v.errors[0]?.message ?? "unknown"}`
-          };
-        }
-        const name = v.manifest.metadata.name;
-        const method = v.manifest.spec.install.method;
-        if (PHASE_212.has(method)) {
-          return { status: "skipped", name };
-        }
-        const r = await runInstall(v.manifest, opts);
-        if ("aborted" in r) return { status: "skipped", name };
-        if (r.ok) return { status: "installed", name };
-        return { status: "failed", name, reason: r.error.message };
-      })
+    const b = await runStepBInstall(manifestPaths);
+    const stepBMs = (b.elapsedMs / 1e3).toFixed(1);
+    console.log(
+      `Step B complete: ${b.installed.length} manifest(s) installed / ${b.alreadyInstalled.length} already-installed / ${b.skipped.length} skipped / ${b.failed.length} failed [parallel ${stepBMs}s]`
     );
-    const baseInstalled = [];
-    const baseSkipped = [];
-    const baseFailed = [];
-    for (const s of settled) {
-      const v = s.status === "fulfilled" ? s.value : {
-        status: "failed",
-        name: "?",
-        reason: String(s.reason)
-      };
-      if (v.status === "installed") baseInstalled.push(v.name);
-      else if (v.status === "skipped") baseSkipped.push(v.name);
-      else
-        baseFailed.push(
-          `${v.name}: ${v.reason}`
-        );
+    for (const n of b.installed) console.log(`  [B] installed          ${n}`);
+    for (const n of b.alreadyInstalled)
+      console.log(
+        `  [B] already-installed  ${n} \u2014 run \`/mcp\` in Claude Code to verify connection`
+      );
+    for (const n of b.skipped) console.log(`  [B] skipped            ${n}`);
+    for (const n of b.failed) console.error(`  [B] failed             ${n}`);
+    console.log(
+      `
+setup complete: ${skillsInstalled} workflow skill(s) + ${b.installed.length + b.alreadyInstalled.length} base manifest(s) configured`
+    );
+    if (b.alreadyInstalled.length > 0 || b.installed.length > 0) {
+      console.log(
+        `
+MCP servers configured. Run \`/mcp\` in Claude Code to verify each server's connection status. If a server shows disconnected, restart Claude Code or check the MCP command spec.`
+      );
     }
-    const stepBMs = ((Date.now() - stepBStart) / 1e3).toFixed(1);
     console.log(
-      `Step B complete: ${baseInstalled.length} manifest(s) installed / ${baseSkipped.length} skipped / ${baseFailed.length} failed [parallel ${stepBMs}s]`
+      "\n\u2713 harnessed v2.0 \u4E09\u5C42\u6808\u65B9\u6CD5\u8BBA bundled \u2014 4 workflows + 6 judgments + 37 capabilities ready"
     );
-    for (const n of baseInstalled) console.log(`  [B] installed  ${n}`);
-    for (const n of baseSkipped) console.log(`  [B] skipped    ${n}`);
-    for (const n of baseFailed) console.error(`  [B] failed     ${n}`);
     console.log(
-      `
-setup complete: ${skillsInstalled} workflow skill(s) + ${baseInstalled.length} base manifest(s) installed`
+      "  workflows in <packageRoot>/workflows/ (Pure bundled, NOT user-dir override per D-01)"
     );
     process.exit(0);
   });
@@ -4654,7 +4958,7 @@ var uninstallNpmCli = async (ctx) => {
   const m = install.cmd.match(/npm\s+(?:install|i)\s+(?:-g\s+)?(\S+)/);
   const pkg = m?.[1] ?? ctx.manifest.metadata.upstream.source;
   const isWin = process.platform === "win32";
-  const result = await new Promise((resolve10) => {
+  const result = await new Promise((resolve11) => {
     const child = isWin ? spawn("cmd.exe", ["/c", "npm", "uninstall", "-g", pkg], { windowsHide: true }) : spawn("npm", ["uninstall", "-g", pkg], { shell: false });
     let stderr = "";
     child.stderr?.setEncoding("utf8").on("data", (c) => {
@@ -4662,15 +4966,15 @@ var uninstallNpmCli = async (ctx) => {
     });
     const timer = setTimeout(() => {
       child.kill("SIGKILL");
-      resolve10({ exitCode: -1, stderr: `${stderr}[timeout]` });
+      resolve11({ exitCode: -1, stderr: `${stderr}[timeout]` });
     }, 3e4);
     child.on("error", (e) => {
       clearTimeout(timer);
-      resolve10({ exitCode: -1, stderr: e.message });
+      resolve11({ exitCode: -1, stderr: e.message });
     });
     child.on("close", (code) => {
       clearTimeout(timer);
-      resolve10({ exitCode: code ?? -1, stderr });
+      resolve11({ exitCode: code ?? -1, stderr });
     });
   });
   if (result.exitCode !== 0) {