@cleocode/caamp 2026.4.6 → 2026.4.9

package/dist/{chunk-43GULI6J.js → chunk-JC77OAHA.js}

@@ -13,6 +13,7 @@ import {
   getCanonicalSkillsDir,
   getLockFilePath,
   getPlatformLocations,
+  resolveProviderConfigPath,
   resolveProviderProjectPath,
   resolveProviderSkillsDirs
 } from "./chunk-364OHA2T.js";
@@ -220,8 +221,8 @@ async function linkToAgent(canonicalPath, provider, skillName, isGlobal, project
       await mkdir(targetSkillsDir, { recursive: true });
       const linkPath = join2(targetSkillsDir, skillName);
       if (existsSync2(linkPath)) {
-        const stat2 = lstatSync(linkPath);
-        if (stat2.isSymbolicLink()) {
+        const stat4 = lstatSync(linkPath);
+        if (stat4.isSymbolicLink()) {
           await rm(linkPath);
         } else {
           await rm(linkPath, { recursive: true });
@@ -352,8 +353,8 @@ async function snapshotSkillState(providerTargets, operation, projectDir, backup
       pathSnapshots.push({ linkPath, state: "missing" });
       continue;
     }
-    const stat2 = lstatSync2(linkPath);
-    if (stat2.isSymbolicLink()) {
+    const stat4 = lstatSync2(linkPath);
+    if (stat4.isSymbolicLink()) {
       pathSnapshots.push({
         linkPath,
         state: "symlink",
@@ -363,7 +364,7 @@ async function snapshotSkillState(providerTargets, operation, projectDir, backup
     }
     const backupPath = join3(backupRoot, "links", provider.id, `${skillName}-${basename(linkPath)}`);
     await mkdir2(dirname(backupPath), { recursive: true });
-    if (stat2.isDirectory()) {
+    if (stat4.isDirectory()) {
       await cp2(linkPath, backupPath, { recursive: true });
       pathSnapshots.push({ linkPath, state: "directory", backupPath });
       continue;
@@ -510,15 +511,83 @@ async function updateInstructionsSingleOperation(providers, content, scope = "pr
   return summary;
 }
 
+// src/core/config/caamp-config.ts
+var DEFAULT_EXCLUSIVITY_MODE = "auto";
+var EXCLUSIVITY_MODE_ENV_VAR = "CAAMP_EXCLUSIVITY_MODE";
+var programmaticOverride = null;
+var exclusivityWarningState = {
+  piAbsentAutoWarned: false,
+  explicitNonPiAutoWarned: false
+};
+function hasPiAbsentAutoWarned() {
+  return exclusivityWarningState.piAbsentAutoWarned;
+}
+function hasExplicitNonPiAutoWarned() {
+  return exclusivityWarningState.explicitNonPiAutoWarned;
+}
+function markPiAbsentAutoWarned() {
+  exclusivityWarningState.piAbsentAutoWarned = true;
+}
+function markExplicitNonPiAutoWarned() {
+  exclusivityWarningState.explicitNonPiAutoWarned = true;
+}
+var PiRequiredError = class extends Error {
+  /** LAFS-stable error code identifying this failure mode. */
+  code = "E_NOT_FOUND_RESOURCE";
+  /**
+   * Construct a new {@link PiRequiredError}.
+   *
+   * @param message - Human-readable failure description; defaults to a
+   *   stable string suitable for direct CLI display.
+   */
+  constructor(message = 'caamp.exclusivityMode is set to "force-pi" but Pi is not installed. Install Pi (https://github.com/mariozechner/pi-coding-agent) or change the mode with CAAMP_EXCLUSIVITY_MODE=auto.') {
+    super(message);
+    this.name = "PiRequiredError";
+  }
+};
+function isExclusivityMode(value) {
+  return value === "auto" || value === "force-pi" || value === "legacy";
+}
+function getExclusivityMode() {
+  if (programmaticOverride !== null) {
+    return programmaticOverride;
+  }
+  const envValue = process.env[EXCLUSIVITY_MODE_ENV_VAR];
+  if (envValue !== void 0 && isExclusivityMode(envValue)) {
+    return envValue;
+  }
+  return DEFAULT_EXCLUSIVITY_MODE;
+}
+function setExclusivityMode(mode) {
+  programmaticOverride = mode;
+}
+function resetExclusivityModeOverride() {
+  programmaticOverride = null;
+}
+
 // src/core/harness/pi.ts
 import { spawn } from "child_process";
 import { existsSync as existsSync4 } from "fs";
-import { cp as cp3, mkdir as mkdir3, readdir, readFile, rename, rm as rm3, writeFile } from "fs/promises";
+import {
+  appendFile,
+  cp as cp3,
+  mkdir as mkdir3,
+  open,
+  readdir,
+  readFile,
+  rename,
+  rm as rm3,
+  stat,
+  writeFile
+} from "fs/promises";
+import { homedir as homedir2 } from "os";
+import { basename as basename2, dirname as dirname2, extname, join as join5 } from "path";
+import { parseDocument, validateDocument } from "@cleocode/cant";
+
+// src/core/harness/scope.ts
 import { homedir } from "os";
-import { dirname as dirname2, join as join4 } from "path";
-var MARKER_START = "<!-- CAAMP:START -->";
-var MARKER_END = "<!-- CAAMP:END -->";
-var MARKER_PATTERN = /<!-- CAAMP:START -->[\s\S]*?<!-- CAAMP:END -->/;
+import { join as join4 } from "path";
+var TIER_PRECEDENCE = ["project", "user", "global"];
 function getPiAgentDir() {
   const env = process.env["PI_CODING_AGENT_DIR"];
   if (env !== void 0 && env.length > 0) {
@@ -528,6 +597,79 @@ function getPiAgentDir() {
   }
   return join4(homedir(), ".pi", "agent");
 }
+function getCleoHomeDir() {
+  const env = process.env["CLEO_HOME"];
+  if (env !== void 0 && env.trim().length > 0) {
+    return env.trim();
+  }
+  if (process.platform === "win32") {
+    const localAppData = process.env["LOCALAPPDATA"];
+    if (localAppData !== void 0 && localAppData.length > 0) {
+      return join4(localAppData, "cleo", "Data");
+    }
+    return join4(homedir(), "AppData", "Local", "cleo", "Data");
+  }
+  if (process.platform === "darwin") {
+    return join4(homedir(), "Library", "Application Support", "cleo");
+  }
+  const xdgData = process.env["XDG_DATA_HOME"];
+  if (xdgData !== void 0 && xdgData.length > 0) {
+    return join4(xdgData, "cleo");
+  }
+  return join4(homedir(), ".local", "share", "cleo");
+}
+function assetDirName(kind) {
+  switch (kind) {
+    case "extensions":
+      return { native: "extensions", hubSuffix: "pi-extensions" };
+    case "prompts":
+      return { native: "prompts", hubSuffix: "pi-prompts" };
+    case "themes":
+      return { native: "themes", hubSuffix: "pi-themes" };
+    case "sessions":
+      return { native: "sessions", hubSuffix: "pi-sessions" };
+    case "cant":
+      return { native: "cant", hubSuffix: "pi-cant" };
+  }
+}
+function resolveTierDir(opts) {
+  const { tier, kind } = opts;
+  const names = assetDirName(kind);
+  if (tier === "project") {
+    if (opts.projectDir === void 0 || opts.projectDir.length === 0) {
+      throw new Error("resolveTierDir: 'project' tier requires a projectDir argument");
+    }
+    return join4(opts.projectDir, ".pi", names.native);
+  }
+  if (tier === "user") {
+    return join4(getPiAgentDir(), names.native);
+  }
+  return join4(getCleoHomeDir(), names.hubSuffix);
+}
+function resolveAllTiers(kind, projectDir) {
+  const out = [];
+  for (const tier of TIER_PRECEDENCE) {
+    if (tier === "project" && (projectDir === void 0 || projectDir.length === 0)) {
+      continue;
+    }
+    out.push({ tier, dir: resolveTierDir({ tier, kind, projectDir }) });
+  }
+  return out;
+}
+
+// src/core/harness/pi.ts
+var MARKER_START = "<!-- CAAMP:START -->";
+var MARKER_END = "<!-- CAAMP:END -->";
+var MARKER_PATTERN = /<!-- CAAMP:START -->[\s\S]*?<!-- CAAMP:END -->/;
+function getPiAgentDir2() {
+  const env = process.env["PI_CODING_AGENT_DIR"];
+  if (env !== void 0 && env.length > 0) {
+    if (env === "~") return homedir2();
+    if (env.startsWith("~/")) return join5(homedir2(), env.slice(2));
+    return env;
+  }
+  return join5(homedir2(), ".pi", "agent");
+}
 function isPlainObject(v) {
   return typeof v === "object" && v !== null && !Array.isArray(v);
 }
@@ -550,6 +692,38 @@ async function atomicWriteJson(filePath, data) {
 `, "utf8");
   await rename(tmp, filePath);
 }
+var DEFAULT_TERMINATE_GRACE_MS = 5e3;
+var STDERR_RING_BUFFER_SIZE = 100;
+var activeSubagents = /* @__PURE__ */ new Set();
+var orphanSweeperRegistered = false;
+function ensureOrphanSweeperRegistered() {
+  if (orphanSweeperRegistered) return;
+  orphanSweeperRegistered = true;
+  const sweeper = () => {
+    for (const entry of activeSubagents) {
+      try {
+        entry.terminate();
+      } catch {
+      }
+    }
+  };
+  process.on("exit", sweeper);
+}
+function generateShortId() {
+  const ts = Date.now().toString(36);
+  const rand = Math.random().toString(36).slice(2, 8);
+  return `${ts}${rand}`;
+}
+function readTerminateGraceFromSettings(settings, fallback) {
+  if (!isPlainObject(settings)) return fallback;
+  const piBlock = settings["pi"];
+  if (!isPlainObject(piBlock)) return fallback;
+  const subBlock = piBlock["subagent"];
+  if (!isPlainObject(subBlock)) return fallback;
+  const value = subBlock["terminateGraceMs"];
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0) return fallback;
+  return value;
+}
 var PiHarness = class {
   /**
    * Construct a harness bound to a resolved Pi provider.
@@ -566,19 +740,13 @@ var PiHarness = class {
    * Resolve the skills directory for a given scope.
    */
   skillsDir(scope) {
-    return scope.kind === "global" ? join4(getPiAgentDir(), "skills") : join4(scope.projectDir, ".pi", "skills");
-  }
-  /**
-   * Resolve the extensions directory for a given scope.
-   */
-  extensionsDir(scope) {
-    return scope.kind === "global" ? join4(getPiAgentDir(), "extensions") : join4(scope.projectDir, ".pi", "extensions");
+    return scope.kind === "global" ? join5(getPiAgentDir2(), "skills") : join5(scope.projectDir, ".pi", "skills");
   }
   /**
    * Resolve the settings.json path for a given scope.
    */
   settingsPath(scope) {
-    return scope.kind === "global" ? join4(getPiAgentDir(), "settings.json") : join4(scope.projectDir, ".pi", "settings.json");
+    return scope.kind === "global" ? join5(getPiAgentDir2(), "settings.json") : join5(scope.projectDir, ".pi", "settings.json");
   }
   /**
    * Resolve the AGENTS.md instruction file path for a given scope.
@@ -589,19 +757,19 @@ var PiHarness = class {
    * auto-discovering `AGENTS.md` from the working directory upwards.
    */
   agentsMdPath(scope) {
-    return scope.kind === "global" ? join4(getPiAgentDir(), "AGENTS.md") : join4(scope.projectDir, "AGENTS.md");
+    return scope.kind === "global" ? join5(getPiAgentDir2(), "AGENTS.md") : join5(scope.projectDir, "AGENTS.md");
   }
   // ── Skills ──────────────────────────────────────────────────────────
   /** {@inheritDoc Harness.installSkill} */
   async installSkill(sourcePath, skillName, scope) {
-    const targetDir = join4(this.skillsDir(scope), skillName);
+    const targetDir = join5(this.skillsDir(scope), skillName);
     await rm3(targetDir, { recursive: true, force: true });
     await mkdir3(dirname2(targetDir), { recursive: true });
     await cp3(sourcePath, targetDir, { recursive: true });
   }
   /** {@inheritDoc Harness.removeSkill} */
   async removeSkill(skillName, scope) {
-    const targetDir = join4(this.skillsDir(scope), skillName);
+    const targetDir = join5(this.skillsDir(scope), skillName);
     await rm3(targetDir, { recursive: true, force: true });
   }
   /** {@inheritDoc Harness.listSkills} */
@@ -646,86 +814,79 @@ ${MARKER_END}`;
     await writeFile(filePath, stripped.length === 0 ? "" : `${stripped}
 `, "utf8");
   }
-  // ── MCP-as-extension scaffold ───────────────────────────────────────
+  // ── Subagent spawn (ADR-035 §D6) ────────────────────────────────────
   /**
-   * {@inheritDoc Harness.installMcpAsExtension}
+   * Spawn a subagent through Pi's configured `spawnCommand` and return a
+   * live handle bound to the canonical streaming, attribution, and
+   * cleanup contract.
    *
    * @remarks
-   * Emits a SCAFFOLD Pi extension file under `extensions/mcp-<name>.ts`.
-   * The scaffold registers a Pi tool whose `execute` function currently
-   * returns an "isError" payload explaining that the MCP bridge runtime
-   * is not yet implemented. This preserves the public lifecycle surface
-   * (install/list/remove) so orchestration code can treat the bridge as
-   * a first-class asset while the concrete JSON-RPC runtime is built out
-   * in a later wave.
-   */
-  async installMcpAsExtension(server, scope) {
-    const dir = this.extensionsDir(scope);
-    await mkdir3(dir, { recursive: true });
-    const filePath = join4(dir, `mcp-${server.name}.ts`);
-    const launchConfig = JSON.stringify(
-      {
-        command: server.command,
-        args: server.args ?? [],
-        url: server.url,
-        env: server.env ?? {},
-        headers: server.headers ?? {}
-      },
-      null,
-      2
-    );
-    const src = `// AUTO-GENERATED by @cleocode/caamp \u2014 do not edit.
-// MCP-as-Pi-extension bridge scaffold for "${server.name}".
-// TODO: implement the MCP JSON-RPC bridge. Current behavior is a stub
-// that logs every tool invocation. The scaffold exists so that CAAMP
-// can manage the extension lifecycle (install/remove/list) without
-// blocking on a full MCP runtime bridge.
-
-const CONFIG = ${launchConfig};
-
-export default (pi: unknown) => {
-  const api = pi as {
-    registerTool: (def: {
-      name: string;
-      label: string;
-      description: string;
-      parameters: unknown;
-      execute: (...args: unknown[]) => Promise<{ type: 'text'; text: string; isError?: boolean }>;
-    }) => void;
-  };
-
-  api.registerTool({
-    name: ${JSON.stringify(`mcp_${server.name}`)},
-    label: ${JSON.stringify(`MCP: ${server.name}`)},
-    description: ${JSON.stringify(
-      `MCP server "${server.name}" \u2014 bridge scaffold, not yet implemented.`
-    )},
-    parameters: { type: 'object', properties: {} },
-    execute: async () => ({
-      type: 'text',
-      text: \`MCP bridge for "${server.name}" is a scaffold. Config: \${JSON.stringify(CONFIG)}\`,
-      isError: true,
-    }),
-  });
-};
-`;
-    await writeFile(filePath, src, "utf8");
-  }
-  // ── Subagent spawn ──────────────────────────────────────────────────
-  /**
-   * {@inheritDoc Harness.spawnSubagent}
+   * Per ADR-035 §D6 this is the **only** sanctioned subagent spawn path
+   * in CLEO. All historical direct `child_process.spawn` callers in
+   * subagent contexts (including the `cant-bridge.ts` Pi extension and
+   * the legacy CLEO orchestrator paths) MUST migrate to this method so
+   * the contract below holds uniformly. A custom biome rule banning
+   * raw `spawn()` from subagent code is planned for v3 cleanup but is
+   * intentionally NOT enforced in v2 to keep the migration incremental.
    *
-   * @remarks
-   * Invokes Pi's configured `spawnCommand` (e.g.
-   * `["pi", "--mode", "json", "-p", "--no-session"]`) with the task prompt
-   * appended as the trailing positional argument. The {@link SubagentTask.targetProviderId}
-   * is a routing hint carried in the prompt stream; Pi's own extension
-   * layer dispatches to the correct inner agent.
+   * **Streaming semantics** — Pi's `--mode json` produces line-delimited
+   * JSON on stdout. The harness:
+   *
+   * - Line-buffers stdout, parses each line as JSON, and forwards a
+   *   `{ kind: 'message', subagentId, lineNumber, payload }`
+   *   {@link SubagentStreamEvent} via {@link SubagentSpawnOptions.onStream}.
+   *   Non-parseable lines increment a warning counter (recorded in the
+   *   child session as `{ type: 'raw' }`) but never crash the loop.
+   * - Line-buffers stderr separately, forwards each line as
+   *   `{ kind: 'stderr', subagentId, payload: { line } }`, and stores
+   *   it in a 100-line ring buffer accessible via
+   *   {@link SubagentHandle.recentStderr}. Stderr is **never** injected
+   *   into the parent LLM context per ADR-035 §D6.
+   * - Emits a final `{ kind: 'exit', subagentId, payload: SubagentExitResult }`
+   *   when the child terminates.
+   *
+   * **Session attribution** — Every spawn produces a child session JSONL
+   * file at
+   * `~/.pi/agent/sessions/subagents/subagent-{parentSessionId}-{taskId}.jsonl`.
+   * The header line records the subagentId, taskId, and parent linkage.
+   * When {@link SubagentTask.parentSessionPath} is supplied, a
+   * {@link SubagentLinkEntry} is appended to the parent session file as
+   * a JSONL line so listing the parent surfaces its children.
+   *
+   * **Exit propagation** — {@link SubagentHandle.exitPromise} resolves
+   * with `{ code, signal, childSessionPath, durationMs }` exactly once
+   * when the child exits. The promise NEVER rejects: failure is
+   * encoded by a non-zero `code`, a non-null `signal`, or partial
+   * output preserved in the child session file.
+   *
+   * **Cleanup** — {@link SubagentHandle.terminate} sends SIGTERM, waits
+   * the configured grace window, then sends SIGKILL if the child is
+   * still alive. The grace window is sourced from
+   * {@link SubagentSpawnOptions.terminateGraceMs} when supplied,
+   * otherwise from `settings.json:pi.subagent.terminateGraceMs`,
+   * otherwise from {@link DEFAULT_TERMINATE_GRACE_MS}. A
+   * `subagent_exit` entry with reason `terminated` is appended to the
+   * child session file when cleanup runs.
    *
-   * Throws immediately when the provider entry is missing a `spawnCommand`
-   * so callers see configuration errors early rather than at child-exit time.
+   * **Concurrency** — Use the static helpers
+   * {@link PiHarness.raceSubagents} and
+   * {@link PiHarness.settleAllSubagents} to compose `parallel: race`
+   * and `parallel: settle` constructs from CANT workflows over multiple
+   * handles.
+   *
+   * **Orphan handling** — On the first spawn the harness registers a
+   * process-wide `'exit'` handler that terminates every still-active
+   * subagent so a parent crash never strands children.
+   *
+   * Throws immediately when the provider entry is missing a
+   * `spawnCommand` so callers see configuration errors early rather
+   * than at child-exit time.
+   *
+   * @param task - Subagent task specification.
+   * @param opts - Per-call streaming and cleanup overrides.
+   * @returns A live subagent handle.
    */
-  async spawnSubagent(task) {
+  async spawnSubagent(task, opts = {}) {
     const cmd = this.provider.capabilities.spawn.spawnCommand;
     if (cmd === null || cmd.length === 0) {
       throw new Error(
@@ -736,44 +897,312 @@ export default (pi: unknown) => {
     if (typeof program !== "string" || program.length === 0) {
       throw new Error("PiHarness.spawnSubagent: invalid spawnCommand (missing program)");
     }
+    const taskId = task.taskId ?? generateShortId();
+    const parentSessionId = task.parentSessionId ?? "orphan";
+    const subagentId = `sub-${taskId}-${generateShortId().slice(0, 6)}`;
+    const childSessionPath = join5(
+      getPiAgentDir2(),
+      "sessions",
+      "subagents",
+      `subagent-${parentSessionId}-${taskId}.jsonl`
+    );
+    await mkdir3(dirname2(childSessionPath), { recursive: true });
+    let grace = opts.terminateGraceMs;
+    if (grace === void 0) {
+      try {
+        const settings = await this.readSettings({ kind: "global" });
+        grace = readTerminateGraceFromSettings(settings, DEFAULT_TERMINATE_GRACE_MS);
+      } catch {
+        grace = DEFAULT_TERMINATE_GRACE_MS;
+      }
+    }
+    if (!Number.isFinite(grace) || grace < 0) {
+      grace = DEFAULT_TERMINATE_GRACE_MS;
+    }
+    const startedAt = /* @__PURE__ */ new Date();
+    const startedAtIso = startedAt.toISOString();
+    const sessionHeader = {
+      type: "session",
+      version: 3,
+      id: subagentId,
+      timestamp: startedAtIso,
+      cwd: opts.cwd ?? task.cwd ?? process.cwd(),
+      parentSession: task.parentSessionId ?? null,
+      taskId,
+      childSessionPath
+    };
+    await writeFile(childSessionPath, `${JSON.stringify(sessionHeader)}
+`, "utf8");
     const baseArgs = cmd.slice(1);
     const args = [...baseArgs, task.prompt];
     const child = spawn(program, args, {
-      cwd: task.cwd,
-      env: { ...process.env, ...task.env },
+      cwd: opts.cwd ?? task.cwd,
+      env: { ...process.env, ...task.env, ...opts.env },
       stdio: ["ignore", "pipe", "pipe"]
     });
-    let stdout = "";
-    let stderr = "";
+    let stdoutAccum = "";
+    let stderrAccum = "";
+    let stdoutBuffer = "";
+    let stderrBuffer = "";
+    let stdoutLineNumber = 0;
+    let nonJsonLineCount = 0;
+    const stderrRing = [];
+    const safeOnStream = (event) => {
+      if (opts.onStream === void 0) return;
+      try {
+        opts.onStream(event);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        stderrRing.push(`[onStream] ${message}`);
+        if (stderrRing.length > STDERR_RING_BUFFER_SIZE) stderrRing.shift();
+      }
+    };
+    const writeChildSession = (entry) => {
+      void appendFile(childSessionPath, `${JSON.stringify(entry)}
+`, "utf8").catch(() => {
+        const synthetic = `[childSession] failed to append entry`;
+        stderrRing.push(synthetic);
+        if (stderrRing.length > STDERR_RING_BUFFER_SIZE) stderrRing.shift();
+      });
+    };
+    const flushStdoutBuffer = (final) => {
+      let nlIdx = stdoutBuffer.indexOf("\n");
+      while (nlIdx !== -1) {
+        const line = stdoutBuffer.slice(0, nlIdx);
+        stdoutBuffer = stdoutBuffer.slice(nlIdx + 1);
+        this.handleStdoutLine(line, {
+          subagentId,
+          increment: () => ++stdoutLineNumber,
+          incrementNonJson: () => ++nonJsonLineCount,
+          writeChildSession,
+          safeOnStream
+        });
+        nlIdx = stdoutBuffer.indexOf("\n");
+      }
+      if (final && stdoutBuffer.length > 0) {
+        const remainder = stdoutBuffer;
+        stdoutBuffer = "";
+        this.handleStdoutLine(remainder, {
+          subagentId,
+          increment: () => ++stdoutLineNumber,
+          incrementNonJson: () => ++nonJsonLineCount,
+          writeChildSession,
+          safeOnStream
+        });
+      }
+    };
+    const flushStderrBuffer = (final) => {
+      let nlIdx = stderrBuffer.indexOf("\n");
+      while (nlIdx !== -1) {
+        const line = stderrBuffer.slice(0, nlIdx);
+        stderrBuffer = stderrBuffer.slice(nlIdx + 1);
+        stderrRing.push(line);
+        if (stderrRing.length > STDERR_RING_BUFFER_SIZE) stderrRing.shift();
+        writeChildSession({ type: "subagent_stderr", line });
+        safeOnStream({ kind: "stderr", subagentId, payload: { line } });
+        nlIdx = stderrBuffer.indexOf("\n");
+      }
+      if (final && stderrBuffer.length > 0) {
+        const line = stderrBuffer;
+        stderrBuffer = "";
+        stderrRing.push(line);
+        if (stderrRing.length > STDERR_RING_BUFFER_SIZE) stderrRing.shift();
+        writeChildSession({ type: "subagent_stderr", line });
+        safeOnStream({ kind: "stderr", subagentId, payload: { line } });
+      }
+    };
     child.stdout?.on("data", (chunk) => {
-      stdout += chunk.toString("utf8");
+      const text = chunk.toString("utf8");
+      stdoutAccum += text;
+      stdoutBuffer += text;
+      flushStdoutBuffer(false);
     });
     child.stderr?.on("data", (chunk) => {
-      stderr += chunk.toString("utf8");
-    });
-    const result = new Promise((resolve) => {
-      child.on("close", (exitCode) => {
-        let parsed;
-        try {
-          parsed = JSON.parse(stdout);
-        } catch {
-        }
-        resolve({ exitCode, stdout, stderr, parsed });
-      });
+      const text = chunk.toString("utf8");
+      stderrAccum += text;
+      stderrBuffer += text;
+      flushStderrBuffer(false);
     });
+    let terminating = false;
+    let terminationReason = "natural";
+    let terminatePromise = null;
+    const terminateImpl = () => {
+      if (terminatePromise !== null) return terminatePromise;
+      terminating = true;
+      terminationReason = "terminated";
+      terminatePromise = terminateSubagent(child, grace ?? DEFAULT_TERMINATE_GRACE_MS);
+      return terminatePromise;
+    };
+    const terminateSync = () => {
+      if (terminating) return;
+      terminating = true;
+      terminationReason = "terminated";
+      try {
+        child.kill("SIGTERM");
+      } catch {
+      }
+    };
+    const activeRecord = {
+      child,
+      subagentId,
+      terminate: terminateSync
+    };
+    activeSubagents.add(activeRecord);
+    ensureOrphanSweeperRegistered();
     if (task.signal !== void 0) {
-      task.signal.addEventListener("abort", () => {
-        child.kill();
+      const onAbort = () => {
+        void terminateImpl();
+      };
+      if (task.signal.aborted) {
+        onAbort();
+      } else {
+        task.signal.addEventListener("abort", onAbort, { once: true });
+      }
+    }
+    const exitPromise = new Promise((resolve) => {
+      child.on("close", (exitCode, signal) => {
+        flushStdoutBuffer(true);
+        flushStderrBuffer(true);
+        const durationMs = Date.now() - startedAt.getTime();
+        writeChildSession({
+          type: "subagent_exit",
+          code: exitCode,
+          signal,
+          reason: terminationReason,
+          durationMs,
+          nonJsonLineCount
+        });
+        activeSubagents.delete(activeRecord);
+        const result2 = {
+          code: exitCode,
+          signal,
+          childSessionPath,
+          durationMs
+        };
+        safeOnStream({ kind: "exit", subagentId, payload: result2 });
+        resolve(result2);
+      });
+      child.on("error", () => {
       });
+    });
+    const result = exitPromise.then(({ code }) => {
+      let parsed;
+      try {
+        parsed = JSON.parse(stdoutAccum);
+      } catch {
+      }
+      return { exitCode: code, stdout: stdoutAccum, stderr: stderrAccum, parsed };
+    });
+    const linkEntry = {
+      type: "subagent_link",
+      subagentId,
+      taskId,
+      childSessionPath,
+      startedAt: startedAtIso
+    };
+    if (task.parentSessionPath !== void 0 && task.parentSessionPath.length > 0) {
+      try {
+        await writeSubagentLink(task.parentSessionPath, linkEntry);
+        safeOnStream({ kind: "link", subagentId, payload: linkEntry });
+      } catch {
+        stderrRing.push(`[link] failed to write subagent_link to parent`);
+        if (stderrRing.length > STDERR_RING_BUFFER_SIZE) stderrRing.shift();
+      }
     }
     return {
+      subagentId,
+      taskId,
+      childSessionPath,
       pid: child.pid ?? null,
+      startedAt,
+      exitPromise,
       result,
+      terminate: terminateImpl,
       abort: () => {
-        child.kill();
-      }
+        void terminateImpl();
+      },
+      recentStderr: () => stderrRing.slice()
     };
   }
+  /**
+   * Race a set of subagent handles, returning the first one that exits.
+   *
+   * @remarks
+   * Maps CANT's `parallel: race` construct (per ADR-035 §D6) onto the
+   * canonical {@link spawnSubagent} contract. The losing handles are
+   * gracefully terminated via {@link SubagentHandle.terminate} once the
+   * first settles so no straggler children outlive the race.
+   *
+   * @param handles - Subagent handles to race.
+   * @returns The {@link SubagentExitResult} of the first child to exit.
+   * @throws When `handles` is empty (caller bug — a race over zero
+   *   children has no winner).
+   */
+  static async raceSubagents(handles) {
+    if (handles.length === 0) {
+      throw new Error("PiHarness.raceSubagents: cannot race an empty handle list");
+    }
+    const tagged = handles.map(
+      (handle, index) => handle.exitPromise.then((value) => ({ index, value }))
+    );
+    const winner = await Promise.race(tagged);
+    const losers = [];
+    for (let i = 0; i < handles.length; i += 1) {
+      if (i === winner.index) continue;
+      const loser = handles[i];
+      if (loser === void 0) continue;
+      losers.push(loser.terminate().catch(() => void 0));
+    }
+    await Promise.all(losers);
+    return winner.value;
+  }
+  /**
+   * Settle a set of subagent handles, returning a parallel array of
+   * results.
+   *
+   * @remarks
+   * Maps CANT's `parallel: settle` construct (per ADR-035 §D6) onto the
+   * canonical {@link spawnSubagent} contract. Because
+   * {@link SubagentHandle.exitPromise} never rejects, every entry in
+   * the returned array is `{ status: 'fulfilled', value: ... }` under
+   * normal operation; the `PromiseSettledResult` shape is preserved
+   * for forward compatibility with future failure modes.
+   *
+   * @param handles - Subagent handles to settle.
+   * @returns Parallel array of settled exit results, one per input.
+   */
+  static async settleAllSubagents(handles) {
+    return Promise.allSettled(handles.map((h) => h.exitPromise));
+  }
+  /**
+   * Per-line stdout dispatcher used by the streaming buffer flusher.
+   *
+   * @remarks
+   * Extracted as a private method so the line-handling logic stays
+   * close to {@link spawnSubagent} but does not bloat the parent
+   * function. Skips empty lines (a leading newline produces a zero-
+   * length entry that has no semantic meaning).
+   */
+  handleStdoutLine(rawLine, ctx) {
+    const trimmed = rawLine.endsWith("\r") ? rawLine.slice(0, -1) : rawLine;
+    if (trimmed.length === 0) return;
+    const lineNumber = ctx.increment();
+    let parsed;
+    try {
+      parsed = JSON.parse(trimmed);
+    } catch {
+      ctx.incrementNonJson();
+      ctx.writeChildSession({ type: "raw", lineNumber, line: trimmed });
+      return;
+    }
+    ctx.writeChildSession({ type: "custom_message", lineNumber, payload: parsed });
+    ctx.safeOnStream({
+      kind: "message",
+      subagentId: ctx.subagentId,
+      lineNumber,
+      payload: parsed
+    });
+  }
   // ── Settings ────────────────────────────────────────────────────────
   /** {@inheritDoc Harness.readSettings} */
   async readSettings(scope) {
@@ -798,7 +1227,722 @@ export default (pi: unknown) => {
   async configureModels(modelPatterns, scope) {
     await this.writeSettings({ enabledModels: modelPatterns }, scope);
   }
-};
+  // ── Wave-1 three-tier helpers ───────────────────────────────────────
+  /**
+   * Resolve the `models.json` path for a given legacy two-tier scope.
+   *
+   * @remarks
+   * Lives next to `settings.json`. Global scope uses the Pi state root,
+   * project scope uses the project's `.pi/` directory, matching the
+   * dual-file authority model documented in ADR-035 §D3.
+   */
+  modelsConfigPath(scope) {
+    return scope.kind === "global" ? join5(getPiAgentDir2(), "models.json") : join5(scope.projectDir, ".pi", "models.json");
+  }
+  /**
+   * Resolve the sessions directory — always user-tier because Pi owns
+   * session storage and the three-tier model folds session listings to
+   * the single authoritative location per ADR-035 §D2.
+   */
+  sessionsDir() {
+    return join5(getPiAgentDir2(), "sessions");
+  }
+  // ── Extensions (Wave-1, T263) ───────────────────────────────────────
+  /** {@inheritDoc Harness.installExtension} */
+  async installExtension(sourcePath, name, tier, projectDir, opts) {
+    if (!existsSync4(sourcePath)) {
+      throw new Error(`installExtension: source file does not exist: ${sourcePath}`);
+    }
+    const stats = await stat(sourcePath);
+    if (!stats.isFile()) {
+      throw new Error(`installExtension: source path is not a regular file: ${sourcePath}`);
+    }
+    const ext = extname(sourcePath);
+    if (ext !== ".ts" && ext !== ".tsx" && ext !== ".mts") {
+      throw new Error(
+        `installExtension: expected a TypeScript source file (.ts/.tsx/.mts), got: ${ext || "(no extension)"}`
+      );
+    }
+    const contents = await readFile(sourcePath, "utf8");
+    if (!/\bexport\s+default\b/.test(contents)) {
+      throw new Error(
+        `installExtension: source file is missing an 'export default' \u2014 Pi extensions must export a default function`
+      );
+    }
+    const dir = resolveTierDir({ tier, kind: "extensions", projectDir });
+    const targetPath = join5(dir, `${name}.ts`);
+    if (existsSync4(targetPath) && opts?.force !== true) {
+      throw new Error(
+        `installExtension: target already exists at ${targetPath} (pass --force to overwrite)`
+      );
+    }
+    await mkdir3(dir, { recursive: true });
+    await writeFile(targetPath, contents, "utf8");
+    return { targetPath, tier };
+  }
+  /** {@inheritDoc Harness.removeExtension} */
+  async removeExtension(name, tier, projectDir) {
+    const dir = resolveTierDir({ tier, kind: "extensions", projectDir });
+    const targetPath = join5(dir, `${name}.ts`);
+    if (!existsSync4(targetPath)) return false;
+    await rm3(targetPath, { force: true });
+    return true;
+  }
+  /** {@inheritDoc Harness.listExtensions} */
+  async listExtensions(projectDir) {
+    const tiers = resolveAllTiers("extensions", projectDir);
+    const out = [];
+    const seenNames = /* @__PURE__ */ new Set();
+    for (const { tier, dir } of tiers) {
+      if (!existsSync4(dir)) continue;
+      let entries;
+      try {
+        entries = await readdir(dir, { withFileTypes: true });
+      } catch {
+        continue;
+      }
+      for (const entry of entries) {
+        if (!entry.isFile()) continue;
+        const fileName = entry.name;
+        if (!fileName.endsWith(".ts")) continue;
+        const name = fileName.slice(0, -".ts".length);
+        const shadowed = seenNames.has(name);
+        out.push({
+          name,
+          tier,
+          path: join5(dir, fileName),
+          shadowed
+        });
+        seenNames.add(name);
+      }
+    }
+    return out;
+  }
+  // ── Sessions (Wave-1, T264) ─────────────────────────────────────────
+  /** {@inheritDoc Harness.listSessions} */
+  async listSessions(opts) {
+    const rootDir = this.sessionsDir();
+    if (!existsSync4(rootDir)) return [];
+    const files = [];
+    let rootEntries;
+    try {
+      rootEntries = await readdir(rootDir, { withFileTypes: true });
+    } catch {
+      return [];
+    }
+    for (const entry of rootEntries) {
+      if (entry.isFile() && entry.name.endsWith(".jsonl")) {
+        files.push(join5(rootDir, entry.name));
+      }
+    }
+    if (opts?.includeSubagents !== false) {
+      const subDir = join5(rootDir, "subagents");
+      if (existsSync4(subDir)) {
+        try {
+          const subEntries = await readdir(subDir, { withFileTypes: true });
+          for (const entry of subEntries) {
+            if (entry.isFile() && entry.name.endsWith(".jsonl")) {
+              files.push(join5(subDir, entry.name));
+            }
+          }
+        } catch {
+        }
+      }
+    }
+    const summaries = [];
+    for (const filePath of files) {
+      const summary = await readSessionHeader(filePath);
+      if (summary !== null) {
+        summaries.push(summary);
+      }
+    }
+    summaries.sort((a, b) => b.mtimeMs - a.mtimeMs);
+    return summaries;
+  }
+  /** {@inheritDoc Harness.showSession} */
+  async showSession(id) {
+    const summaries = await this.listSessions({ includeSubagents: true });
+    const match = summaries.find((s) => s.id === id);
+    if (match === void 0) {
+      throw new Error(`showSession: no session found with id ${id}`);
+    }
+    const raw = await readFile(match.filePath, "utf8");
+    const allLines = raw.split("\n");
+    while (allLines.length > 0 && allLines[allLines.length - 1] === "") {
+      allLines.pop();
+    }
+    const entries = allLines.slice(1);
+    return { summary: match, entries };
+  }
+  // ── Models (Wave-1, T265) ───────────────────────────────────────────
+  /** {@inheritDoc Harness.readModelsConfig} */
+  async readModelsConfig(scope) {
+    const filePath = this.modelsConfigPath(scope);
+    if (!existsSync4(filePath)) return { providers: {} };
+    let raw;
+    try {
+      raw = await readFile(filePath, "utf8");
+    } catch {
+      return { providers: {} };
+    }
+    try {
+      const parsed = JSON.parse(raw);
+      if (!isPlainObject(parsed)) return { providers: {} };
+      const providersField = parsed["providers"];
+      if (!isPlainObject(providersField)) return { providers: {} };
+      const providers = {};
+      for (const [id, block] of Object.entries(providersField)) {
+        if (isPlainObject(block)) {
+          providers[id] = block;
+        }
+      }
+      return { providers };
+    } catch {
+      return { providers: {} };
+    }
+  }
+  /** {@inheritDoc Harness.writeModelsConfig} */
+  async writeModelsConfig(config, scope) {
+    const filePath = this.modelsConfigPath(scope);
+    await atomicWriteJson(filePath, config);
+  }
+  /** {@inheritDoc Harness.listModels} */
+  async listModels(scope) {
+    const models = await this.readModelsConfig(scope);
+    const settings = await this.readSettings(scope);
+    const settingsObj = isPlainObject(settings) ? settings : {};
+    const enabledRaw = settingsObj["enabledModels"];
+    const enabled = Array.isArray(enabledRaw) ? enabledRaw.filter((v) => typeof v === "string") : [];
+    const defaultModel = typeof settingsObj["defaultModel"] === "string" ? settingsObj["defaultModel"] : null;
+    const defaultProvider = typeof settingsObj["defaultProvider"] === "string" ? settingsObj["defaultProvider"] : null;
+    const out = [];
+    const seen = /* @__PURE__ */ new Set();
+    for (const [providerId, providerBlock] of Object.entries(models.providers)) {
+      const modelDefs = providerBlock.models ?? [];
+      for (const def of modelDefs) {
+        const key = `${providerId}:${def.id}`;
+        seen.add(key);
+        const isEnabled = enabled.includes(key) || enabled.includes(`${providerId}/*`);
+        const isDefault = defaultProvider === providerId && defaultModel === def.id;
+        out.push({
+          provider: providerId,
+          id: def.id,
+          name: def.name ?? null,
+          enabled: isEnabled,
+          isDefault,
+          custom: true
+        });
+      }
+    }
+    for (const selection of enabled) {
+      if (!selection.includes(":") && !selection.includes("/")) continue;
+      const match = selection.match(/^([^:/]+)[:/]([^:/].*)$/);
+      if (match === null) continue;
+      const provider = match[1];
+      const id = match[2];
+      if (provider === void 0 || id === void 0) continue;
+      if (id.endsWith("*")) continue;
+      const key = `${provider}:${id}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      const isDefault = defaultProvider === provider && defaultModel === id;
+      out.push({
+        provider,
+        id,
+        name: null,
+        enabled: true,
+        isDefault,
+        custom: false
+      });
+    }
+    if (defaultProvider !== null && defaultModel !== null && !seen.has(`${defaultProvider}:${defaultModel}`)) {
+      out.push({
+        provider: defaultProvider,
+        id: defaultModel,
+        name: null,
+        enabled: false,
+        isDefault: true,
+        custom: false
+      });
+    }
+    return out;
+  }
+  // ── Prompts (Wave-1, T266) ──────────────────────────────────────────
+  /** {@inheritDoc Harness.installPrompt} */
+  async installPrompt(sourceDir, name, tier, projectDir, opts) {
+    if (!existsSync4(sourceDir)) {
+      throw new Error(`installPrompt: source directory does not exist: ${sourceDir}`);
+    }
+    const stats = await stat(sourceDir);
+    if (!stats.isDirectory()) {
+      throw new Error(`installPrompt: source path is not a directory: ${sourceDir}`);
+    }
+    if (!existsSync4(join5(sourceDir, "prompt.md"))) {
+      throw new Error(`installPrompt: source directory is missing a prompt.md file: ${sourceDir}`);
+    }
+    const baseDir = resolveTierDir({ tier, kind: "prompts", projectDir });
+    const targetPath = join5(baseDir, name);
+    if (existsSync4(targetPath)) {
+      if (opts?.force !== true) {
+        throw new Error(
+          `installPrompt: target already exists at ${targetPath} (pass --force to overwrite)`
+        );
+      }
+      await rm3(targetPath, { recursive: true, force: true });
+    }
+    await mkdir3(baseDir, { recursive: true });
+    await cp3(sourceDir, targetPath, { recursive: true });
+    return { targetPath, tier };
+  }
+  /** {@inheritDoc Harness.listPrompts} */
+  async listPrompts(projectDir) {
+    const tiers = resolveAllTiers("prompts", projectDir);
+    const out = [];
+    const seenNames = /* @__PURE__ */ new Set();
+    for (const { tier, dir } of tiers) {
+      if (!existsSync4(dir)) continue;
+      let entries;
+      try {
+        entries = await readdir(dir, { withFileTypes: true });
+      } catch {
+        continue;
+      }
+      for (const entry of entries) {
+        if (!entry.isDirectory()) continue;
+        const name = entry.name;
+        const shadowed = seenNames.has(name);
+        out.push({
+          name,
+          tier,
+          path: join5(dir, name),
+          shadowed
+        });
+        seenNames.add(name);
+      }
+    }
+    return out;
+  }
+  /** {@inheritDoc Harness.removePrompt} */
+  async removePrompt(name, tier, projectDir) {
+    const dir = resolveTierDir({ tier, kind: "prompts", projectDir });
+    const targetPath = join5(dir, name);
+    if (!existsSync4(targetPath)) return false;
+    await rm3(targetPath, { recursive: true, force: true });
+    return true;
+  }
+  // ── Themes (Wave-1, T267) ───────────────────────────────────────────
+  /** {@inheritDoc Harness.installTheme} */
+  async installTheme(sourceFile, name, tier, projectDir, opts) {
+    if (!existsSync4(sourceFile)) {
+      throw new Error(`installTheme: source file does not exist: ${sourceFile}`);
+    }
+    const stats = await stat(sourceFile);
+    if (!stats.isFile()) {
+      throw new Error(`installTheme: source path is not a regular file: ${sourceFile}`);
+    }
+    const ext = extname(sourceFile);
+    if (ext !== ".ts" && ext !== ".tsx" && ext !== ".mts" && ext !== ".json") {
+      throw new Error(
+        `installTheme: expected a theme file (.ts/.tsx/.mts/.json), got: ${ext || "(no extension)"}`
+      );
+    }
+    const dir = resolveTierDir({ tier, kind: "themes", projectDir });
+    const targetPath = join5(dir, `${name}${ext}`);
+    if (existsSync4(targetPath) && opts?.force !== true) {
+      throw new Error(
+        `installTheme: target already exists at ${targetPath} (pass --force to overwrite)`
+      );
+    }
+    const otherExts = [".ts", ".tsx", ".mts", ".json"].filter((e) => e !== ext);
+    for (const otherExt of otherExts) {
+      const otherPath = join5(dir, `${name}${otherExt}`);
+      if (existsSync4(otherPath) && opts?.force !== true) {
+        throw new Error(
+          `installTheme: conflicting theme exists at ${otherPath} (pass --force to overwrite both)`
+        );
+      }
+      if (existsSync4(otherPath) && opts?.force === true) {
+        await rm3(otherPath, { force: true });
+      }
+    }
+    await mkdir3(dir, { recursive: true });
+    const contents = await readFile(sourceFile);
+    await writeFile(targetPath, contents);
+    return { targetPath, tier };
+  }
+  /** {@inheritDoc Harness.listThemes} */
+  async listThemes(projectDir) {
+    const tiers = resolveAllTiers("themes", projectDir);
+    const out = [];
+    const seenNames = /* @__PURE__ */ new Set();
+    const validExts = /* @__PURE__ */ new Set([".ts", ".tsx", ".mts", ".json"]);
+    for (const { tier, dir } of tiers) {
+      if (!existsSync4(dir)) continue;
+      let entries;
+      try {
+        entries = await readdir(dir, { withFileTypes: true });
+      } catch {
+        continue;
+      }
+      for (const entry of entries) {
+        if (!entry.isFile()) continue;
+        const fileExt = extname(entry.name);
+        if (!validExts.has(fileExt)) continue;
+        const name = entry.name.slice(0, -fileExt.length);
+        const shadowed = seenNames.has(name);
+        out.push({
+          name,
+          tier,
+          path: join5(dir, entry.name),
+          fileExt,
+          shadowed
+        });
+        seenNames.add(name);
+      }
+    }
+    return out;
+  }
+  /** {@inheritDoc Harness.removeTheme} */
+  async removeTheme(name, tier, projectDir) {
+    const dir = resolveTierDir({ tier, kind: "themes", projectDir });
+    let removed = false;
+    for (const ext of [".ts", ".tsx", ".mts", ".json"]) {
+      const targetPath = join5(dir, `${name}${ext}`);
+      if (existsSync4(targetPath)) {
+        await rm3(targetPath, { force: true });
+        removed = true;
+      }
+    }
+    return removed;
+  }
+  // ── CANT profiles (Wave-1, T276) ────────────────────────────────────
+  /**
+   * {@inheritDoc Harness.installCantProfile}
+   *
+   * @remarks
+   * Validates the source via {@link validateCantProfile} before copying so
+   * we never persist a `.cant` file the runtime bridge cannot load. The
+   * target layout is `<tier-root>/cant/<name>.cant`, resolved through
+   * {@link resolveTierDir} so the project/user/global hierarchy stays
+   * consistent with the other Wave-1 verbs.
+   */
+  async installCantProfile(sourcePath, name, tier, projectDir, opts) {
+    if (!existsSync4(sourcePath)) {
+      throw new Error(`installCantProfile: source file does not exist: ${sourcePath}`);
+    }
+    const stats = await stat(sourcePath);
+    if (!stats.isFile()) {
+      throw new Error(`installCantProfile: source path is not a regular file: ${sourcePath}`);
+    }
+    const ext = extname(sourcePath);
+    if (ext !== ".cant") {
+      throw new Error(
+        `installCantProfile: expected a CANT source file (.cant), got: ${ext || "(no extension)"}`
+      );
+    }
+    const validation = await this.validateCantProfile(sourcePath);
+    if (!validation.valid) {
+      const firstError = validation.errors.find((e) => e.severity === "error") ?? validation.errors[0];
+      const detail = firstError !== void 0 ? ` (${firstError.ruleId} at ${firstError.line}:${firstError.col}: ${firstError.message})` : "";
+      throw new Error(`installCantProfile: source file failed cant-core validation${detail}`);
+    }
+    const dir = resolveTierDir({ tier, kind: "cant", projectDir });
+    const targetPath = join5(dir, `${name}.cant`);
+    if (existsSync4(targetPath) && opts?.force !== true) {
+      throw new Error(
+        `installCantProfile: target already exists at ${targetPath} (pass --force to overwrite)`
+      );
+    }
+    const contents = await readFile(sourcePath);
+    await mkdir3(dir, { recursive: true });
+    await writeFile(targetPath, contents);
+    return { targetPath, tier, counts: validation.counts };
+  }
+  /** {@inheritDoc Harness.removeCantProfile} */
+  async removeCantProfile(name, tier, projectDir) {
+    const dir = resolveTierDir({ tier, kind: "cant", projectDir });
+    const targetPath = join5(dir, `${name}.cant`);
+    if (!existsSync4(targetPath)) return false;
+    await rm3(targetPath, { force: true });
+    return true;
+  }
+  /**
+   * {@inheritDoc Harness.listCantProfiles}
+   *
+   * @remarks
+   * Walks every tier in {@link TIER_PRECEDENCE} order, parsing each
+   * discovered `.cant` file via cant-core to extract a
+   * {@link CantProfileCounts} bag. Higher-precedence tiers shadow
+   * lower-precedence entries with the same name; shadowed entries
+   * still appear in the result but carry the
+   * `shadowedByHigherTier` flag so callers can render the precedence
+   * story without losing visibility of the duplicate.
+   */
+  async listCantProfiles(projectDir) {
+    const tiers = resolveAllTiers("cant", projectDir);
+    const out = [];
+    const seenNames = /* @__PURE__ */ new Set();
+    for (const { tier, dir } of tiers) {
+      if (!existsSync4(dir)) continue;
+      let entries;
+      try {
+        entries = await readdir(dir, { withFileTypes: true });
+      } catch {
+        continue;
+      }
+      for (const entry of entries) {
+        if (!entry.isFile()) continue;
+        const fileName = entry.name;
+        if (!fileName.endsWith(".cant")) continue;
+        const name = fileName.slice(0, -".cant".length);
+        const sourcePath = join5(dir, fileName);
+        const counts = await extractCantCounts(sourcePath);
+        const shadowed = seenNames.has(name);
+        const profile = {
+          name,
+          tier,
+          sourcePath,
+          counts
+        };
+        if (shadowed) {
+          profile.shadowedByHigherTier = true;
+        }
+        out.push(profile);
+        seenNames.add(name);
+      }
+    }
+    return out;
+  }
+  /**
+   * {@inheritDoc Harness.validateCantProfile}
+   *
+   * @remarks
+   * Pure validator. Reads the file, runs `parseDocument` to derive
+   * counts (when parsing succeeds) and `validateDocument` to collect
+   * the 42-rule diagnostic feed. The two calls are kept independent so
+   * we can still report counts for files that pass parsing but fail a
+   * lint rule.
+   */
+  async validateCantProfile(sourcePath) {
+    if (!existsSync4(sourcePath)) {
+      throw new Error(`validateCantProfile: source file does not exist: ${sourcePath}`);
+    }
+    const stats = await stat(sourcePath);
+    if (!stats.isFile()) {
+      throw new Error(`validateCantProfile: source path is not a regular file: ${sourcePath}`);
+    }
+    const counts = await extractCantCounts(sourcePath);
+    const validation = await validateDocument(sourcePath);
+    const errors = validation.diagnostics.map((d) => ({
+      ruleId: d.ruleId,
+      message: d.message,
+      line: d.line,
+      col: d.col,
+      severity: normaliseSeverity(d.severity)
+    }));
+    return {
+      valid: validation.valid,
+      errors,
+      counts
+    };
+  }
+};
+async function terminateSubagent(child, graceMs) {
+  if (child.exitCode !== null || child.signalCode !== null) {
+    return;
+  }
+  try {
+    child.kill("SIGTERM");
+  } catch {
+    return;
+  }
+  const pollInterval = Math.min(25, Math.max(1, graceMs));
+  const deadline = Date.now() + graceMs;
+  await new Promise((resolve) => {
+    const timer = setInterval(() => {
+      if (child.exitCode !== null || child.signalCode !== null) {
+        clearInterval(timer);
+        resolve();
+        return;
+      }
+      if (Date.now() >= deadline) {
+        clearInterval(timer);
+        try {
+          child.kill("SIGKILL");
+        } catch {
+        }
+        resolve();
+      }
+    }, pollInterval);
+    child.once("close", () => {
+      clearInterval(timer);
+      resolve();
+    });
+  });
+}
+async function writeSubagentLink(parentSessionPath, entry) {
+  await mkdir3(dirname2(parentSessionPath), { recursive: true });
+  const wrapped = {
+    type: "custom",
+    subtype: entry.type,
+    subagentId: entry.subagentId,
+    taskId: entry.taskId,
+    childSessionPath: entry.childSessionPath,
+    startedAt: entry.startedAt
+  };
+  const line = `${JSON.stringify(wrapped)}
+`;
+  await appendFile(parentSessionPath, line, "utf8");
+}
+async function readSessionHeader(filePath) {
+  let handle = null;
+  try {
+    handle = await open(filePath, "r");
+    const stats = await handle.stat();
+    const capacity = Math.min(stats.size, 64 * 1024);
+    if (capacity === 0) return null;
+    const buffer = Buffer.alloc(capacity);
+    const { bytesRead } = await handle.read(buffer, 0, capacity, 0);
+    const text = buffer.subarray(0, bytesRead).toString("utf8");
+    const newlineIdx = text.indexOf("\n");
+    const firstLine = newlineIdx === -1 ? text : text.slice(0, newlineIdx);
+    if (firstLine.trim().length === 0) return null;
+    let parsed;
+    try {
+      parsed = JSON.parse(firstLine);
+    } catch {
+      return null;
+    }
+    if (!isPlainObject(parsed)) return null;
+    const id = typeof parsed["id"] === "string" ? parsed["id"] : null;
+    if (id === null) {
+      const stem = basename2(filePath, ".jsonl");
+      return {
+        id: stem,
+        version: typeof parsed["version"] === "number" ? parsed["version"] : 0,
+        timestamp: typeof parsed["timestamp"] === "string" ? parsed["timestamp"] : null,
+        cwd: typeof parsed["cwd"] === "string" ? parsed["cwd"] : null,
+        parentSession: typeof parsed["parentSession"] === "string" ? parsed["parentSession"] : null,
+        filePath,
+        mtimeMs: stats.mtimeMs
+      };
+    }
+    return {
+      id,
+      version: typeof parsed["version"] === "number" ? parsed["version"] : 0,
+      timestamp: typeof parsed["timestamp"] === "string" ? parsed["timestamp"] : null,
+      cwd: typeof parsed["cwd"] === "string" ? parsed["cwd"] : null,
+      parentSession: typeof parsed["parentSession"] === "string" ? parsed["parentSession"] : null,
+      filePath,
+      mtimeMs: stats.mtimeMs
+    };
+  } catch {
+    return null;
+  } finally {
+    if (handle !== null) {
+      await handle.close().catch(() => {
+      });
+    }
+  }
+}
+var EMPTY_CANT_COUNTS = {
+  agentCount: 0,
+  workflowCount: 0,
+  pipelineCount: 0,
+  hookCount: 0,
+  skillCount: 0
+};
+function isRecord(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function unwrapSpanned(value) {
+  if (typeof value === "string") return value;
+  if (isRecord(value) && typeof value["value"] === "string") {
+    return value["value"];
+  }
+  return null;
+}
+function collectSkillNames(value, out) {
+  if (!isRecord(value)) return;
+  const arr = value["Array"];
+  if (!Array.isArray(arr)) return;
+  for (const item of arr) {
+    if (!isRecord(item)) continue;
+    const stringWrapper = item["String"];
+    if (isRecord(stringWrapper) && typeof stringWrapper["raw"] === "string") {
+      out.add(stringWrapper["raw"]);
+      continue;
+    }
+    const identWrapper = item["Identifier"];
+    if (typeof identWrapper === "string") {
+      out.add(identWrapper);
+    }
+  }
+}
+async function extractCantCounts(sourcePath) {
+  let parsed;
+  try {
+    parsed = await parseDocument(sourcePath);
+  } catch {
+    return { ...EMPTY_CANT_COUNTS };
+  }
+  if (!parsed.success || !isRecord(parsed.document)) {
+    return { ...EMPTY_CANT_COUNTS };
+  }
+  const sections = parsed.document["sections"];
+  if (!Array.isArray(sections)) {
+    return { ...EMPTY_CANT_COUNTS };
+  }
+  let agentCount = 0;
+  let workflowCount = 0;
+  let pipelineCount = 0;
+  let hookCount = 0;
+  const skillNames = /* @__PURE__ */ new Set();
+  for (const section of sections) {
+    if (!isRecord(section)) continue;
+    if (isRecord(section["Agent"])) {
+      agentCount += 1;
+      const agent = section["Agent"];
+      const hooks = agent["hooks"];
+      if (Array.isArray(hooks)) {
+        hookCount += hooks.length;
+      }
+      const properties = agent["properties"];
+      if (Array.isArray(properties)) {
+        for (const prop of properties) {
+          if (!isRecord(prop)) continue;
+          const key = unwrapSpanned(prop["key"]);
+          if (key === "skills") {
+            collectSkillNames(prop["value"], skillNames);
+          }
+        }
+      }
+      continue;
+    }
+    if (isRecord(section["Workflow"])) {
+      workflowCount += 1;
+      continue;
+    }
+    if (isRecord(section["Pipeline"])) {
+      pipelineCount += 1;
+      continue;
+    }
+    if (isRecord(section["Hook"])) {
+      hookCount += 1;
+    }
+  }
+  return {
+    agentCount,
+    workflowCount,
+    pipelineCount,
+    hookCount,
+    skillCount: skillNames.size
+  };
+}
+function normaliseSeverity(raw) {
+  if (raw === "warning" || raw === "info" || raw === "hint") return raw;
+  return "error";
+}
 
 // src/core/harness/index.ts
 function getHarnessFor(provider) {
@@ -818,28 +1962,67 @@ function getAllHarnesses() {
   }
   return result;
 }
-function resolveDefaultTargetProviders() {
+function resolveDefaultTargetProviders(options = {}) {
+  const mode = getExclusivityMode();
   let primary = null;
   try {
     primary = getPrimaryHarness();
   } catch {
     primary = null;
   }
-  const installed = getInstalledProviders();
-  if (primary !== null) {
-    const primaryId = primary.provider.id;
-    const primaryInstalled = installed.some((p) => p.id === primaryId);
-    if (primaryInstalled) {
+  let installed;
+  try {
+    installed = getInstalledProviders();
+  } catch {
+    installed = [];
+  }
+  const primaryId = primary?.provider.id ?? null;
+  const primaryInstalled = primaryId !== null && installed.some((provider) => provider.id === primaryId);
+  const explicit = options.explicit;
+  const explicitContainsPrimary = explicit !== void 0 && primaryId !== null ? explicit.some((provider) => provider.id === primaryId) : false;
+  const legacyFallback = () => {
+    if (primary !== null && primaryInstalled) {
       return [primary.provider];
     }
+    const highTier = installed.filter(
+      (provider) => provider.priority === "primary" || provider.priority === "high"
+    );
+    if (highTier.length > 0) {
+      return highTier;
+    }
+    return installed;
+  };
+  if (mode === "force-pi") {
+    if (primary === null || !primaryInstalled) {
+      throw new PiRequiredError();
+    }
+    return [primary.provider];
   }
-  const highTier = installed.filter(
-    (provider) => provider.priority === "primary" || provider.priority === "high"
-  );
-  if (highTier.length > 0) {
-    return highTier;
+  if (mode === "legacy") {
+    if (explicit !== void 0) {
+      return explicit;
+    }
+    return legacyFallback();
+  }
+  if (explicit !== void 0 && explicit.length > 0 && !explicitContainsPrimary && primaryInstalled && !hasExplicitNonPiAutoWarned()) {
+    console.warn(
+      "Warning: Targeting a non-Pi provider explicitly is deprecated when Pi is installed. Future versions will route all runtime commands through Pi. To suppress this warning, set caamp.exclusivityMode to 'legacy'."
+    );
+    markExplicitNonPiAutoWarned();
   }
-  return installed;
+  if (explicit !== void 0) {
+    return explicit;
+  }
+  if (primary !== null && primaryInstalled) {
+    return [primary.provider];
+  }
+  if (!hasPiAbsentAutoWarned()) {
+    console.warn(
+      "Warning: Pi is not installed. CAAMP is falling back to direct provider dispatch. Install Pi (https://github.com/mariozechner/pi-coding-agent) to enable orchestration, or set caamp.exclusivityMode to 'legacy' to suppress this warning."
+    );
+    markPiAbsentAutoWarned();
+  }
+  return legacyFallback();
 }
 async function dispatchInstallSkillAcrossProviders(sourcePath, skillName, providers, isGlobal, projectDir) {
   const harnessTargets = [];
@@ -1105,63 +2288,395 @@ async function removeYamlConfig(filePath, configKey, serverName) {
     if (typeof next !== "object" || next === null) return false;
     current = next;
   }
-  if (!(serverName in current)) return false;
-  delete current[serverName];
-  const content = yaml.dump(existing, {
-    indent: 2,
-    lineWidth: -1,
-    noRefs: true,
-    sortKeys: false
-  });
-  await writeFile4(filePath, content, "utf-8");
-  return true;
-}
-
-// src/core/formats/index.ts
-async function readConfig(filePath, format) {
-  debug(`reading config: ${filePath} (format: ${format})`);
-  switch (format) {
-    case "json":
-    case "jsonc":
-      return readJsonConfig(filePath);
-    case "yaml":
-      return readYamlConfig(filePath);
-    case "toml":
-      return readTomlConfig(filePath);
-    default:
-      throw new Error(`Unsupported config format: ${format}`);
+  if (!(serverName in current)) return false;
+  delete current[serverName];
+  const content = yaml.dump(existing, {
+    indent: 2,
+    lineWidth: -1,
+    noRefs: true,
+    sortKeys: false
+  });
+  await writeFile4(filePath, content, "utf-8");
+  return true;
+}
+
+// src/core/formats/index.ts
+async function readConfig(filePath, format) {
+  debug(`reading config: ${filePath} (format: ${format})`);
+  switch (format) {
+    case "json":
+    case "jsonc":
+      return readJsonConfig(filePath);
+    case "yaml":
+      return readYamlConfig(filePath);
+    case "toml":
+      return readTomlConfig(filePath);
+    default:
+      throw new Error(`Unsupported config format: ${format}`);
+  }
+}
+async function writeConfig(filePath, format, key, serverName, serverConfig) {
+  debug(`writing config: ${filePath} (format: ${format}, key: ${key}, server: ${serverName})`);
+  switch (format) {
+    case "json":
+    case "jsonc":
+      return writeJsonConfig(filePath, key, serverName, serverConfig);
+    case "yaml":
+      return writeYamlConfig(filePath, key, serverName, serverConfig);
+    case "toml":
+      return writeTomlConfig(filePath, key, serverName, serverConfig);
+    default:
+      throw new Error(`Unsupported config format: ${format}`);
+  }
+}
+async function removeConfig(filePath, format, key, serverName) {
+  switch (format) {
+    case "json":
+    case "jsonc":
+      return removeJsonConfig(filePath, key, serverName);
+    case "yaml":
+      return removeYamlConfig(filePath, key, serverName);
+    case "toml":
+      return removeTomlConfig(filePath, key, serverName);
+    default:
+      throw new Error(`Unsupported config format: ${format}`);
+  }
+}
+
+// src/core/mcp/reader.ts
+import { existsSync as existsSync8 } from "fs";
+import { stat as stat2 } from "fs/promises";
+function resolveMcpConfigPath(provider, scope, projectDir) {
+  if (provider.capabilities.mcp === null) return null;
+  return resolveProviderConfigPath(provider, scope, projectDir);
+}
+async function listMcpServers(provider, scope, projectDir) {
+  const mcp = provider.capabilities.mcp;
+  if (mcp === null) return [];
+  const configPath = resolveMcpConfigPath(provider, scope, projectDir);
+  if (configPath === null) return [];
+  if (!existsSync8(configPath)) {
+    debug(`mcp.list: ${provider.id} (${scope}) \u2014 config file missing at ${configPath}`);
+    return [];
+  }
+  let parsed;
+  try {
+    parsed = await readConfig(configPath, mcp.configFormat);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    debug(`mcp.list: ${provider.id} parse failed at ${configPath}: ${message}`);
+    return [];
+  }
+  const servers = getNestedValue(parsed, mcp.configKey);
+  if (servers === void 0 || servers === null || typeof servers !== "object") return [];
+  const out = [];
+  for (const [name, raw] of Object.entries(servers)) {
+    out.push({
+      name,
+      providerId: provider.id,
+      providerName: provider.toolName,
+      scope,
+      configPath,
+      config: raw ?? {}
+    });
+  }
+  return out;
+}
+async function listAllMcpServers(scope, projectDir) {
+  const out = /* @__PURE__ */ new Map();
+  for (const provider of getAllProviders()) {
+    if (provider.capabilities.mcp === null) continue;
+    const entries = await listMcpServers(provider, scope, projectDir);
+    out.set(provider.id, entries);
+  }
+  return out;
+}
+async function detectMcpInstallations(scope, projectDir) {
+  const out = [];
+  for (const provider of getAllProviders()) {
+    const mcp = provider.capabilities.mcp;
+    if (mcp === null) continue;
+    const configPath = resolveMcpConfigPath(provider, scope, projectDir);
+    if (configPath === null) continue;
+    const exists = existsSync8(configPath);
+    let serverCount = null;
+    let lastModified = null;
+    if (exists) {
+      try {
+        const stats = await stat2(configPath);
+        lastModified = stats.mtime.toISOString();
+      } catch {
+        lastModified = null;
+      }
+      const entries = await listMcpServers(provider, scope, projectDir);
+      serverCount = entries.length;
+    }
+    out.push({
+      providerId: provider.id,
+      providerName: provider.toolName,
+      scope,
+      configPath,
+      exists,
+      serverCount,
+      lastModified
+    });
+  }
+  return out;
+}
+
+// src/core/mcp/installer.ts
+async function installMcpServer(provider, serverName, config, opts) {
+  const mcp = provider.capabilities.mcp;
+  if (mcp === null) {
+    throw new Error(`Provider ${provider.id} does not declare an MCP capability.`);
+  }
+  const configPath = resolveMcpConfigPath(provider, opts.scope, opts.projectDir);
+  if (configPath === null) {
+    throw new Error(
+      `Provider ${provider.id} has no ${opts.scope}-scoped MCP config path available.`
+    );
+  }
+  debug(
+    `mcp.install: ${provider.id} ${serverName} \u2192 ${configPath} (format=${mcp.configFormat}, key=${mcp.configKey})`
+  );
+  const existing = await listMcpServers(provider, opts.scope, opts.projectDir);
+  const conflicted = existing.some((e) => e.name === serverName);
+  if (conflicted && opts.force !== true) {
+    return {
+      installed: false,
+      conflicted: true,
+      sourcePath: configPath,
+      providerId: provider.id,
+      serverName
+    };
+  }
+  await writeConfig(configPath, mcp.configFormat, mcp.configKey, serverName, config);
+  return {
+    installed: true,
+    conflicted,
+    sourcePath: configPath,
+    providerId: provider.id,
+    serverName
+  };
+}
+
+// src/core/mcp/remover.ts
+import { existsSync as existsSync9 } from "fs";
+async function removeMcpServer(provider, serverName, opts) {
+  const mcp = provider.capabilities.mcp;
+  if (mcp === null) {
+    return {
+      providerId: provider.id,
+      serverName,
+      sourcePath: null,
+      removed: false,
+      reason: "no-mcp-capability"
+    };
+  }
+  const configPath = resolveMcpConfigPath(provider, opts.scope, opts.projectDir);
+  if (configPath === null) {
+    return {
+      providerId: provider.id,
+      serverName,
+      sourcePath: null,
+      removed: false,
+      reason: "no-config-path"
+    };
+  }
+  if (!existsSync9(configPath)) {
+    return {
+      providerId: provider.id,
+      serverName,
+      sourcePath: configPath,
+      removed: false,
+      reason: "file-missing"
+    };
+  }
+  debug(`mcp.remove: ${provider.id} ${serverName} \u2192 ${configPath}`);
+  const removed = await removeConfig(configPath, mcp.configFormat, mcp.configKey, serverName);
+  return {
+    providerId: provider.id,
+    serverName,
+    sourcePath: configPath,
+    removed,
+    reason: removed ? null : "entry-missing"
+  };
+}
+async function removeMcpServerFromAll(serverName, opts) {
+  const out = [];
+  for (const provider of getAllProviders()) {
+    if (provider.capabilities.mcp === null) continue;
+    out.push(await removeMcpServer(provider, serverName, opts));
+  }
+  return out;
+}
+
+// src/core/sources/parser.ts
+var GITHUB_SHORTHAND = /^([a-zA-Z0-9_.-]+)\/([a-zA-Z0-9_.-]+)(?:\/(.+))?$/;
+var GITHUB_URL = /^https?:\/\/(?:www\.)?github\.com\/([^/]+)\/([^/]+)(?:\/(?:tree|blob)\/([^/]+)(?:\/(.+))?)?/;
+var GITLAB_URL = /^https?:\/\/(?:www\.)?gitlab\.com\/([^/]+)\/([^/]+)(?:\/-\/(?:tree|blob)\/([^/]+)(?:\/(.+))?)?/;
+var HTTP_URL = /^https?:\/\//;
+var NPM_SCOPED = /^@[a-zA-Z0-9_.-]+\/[a-zA-Z0-9_.-]+$/;
+var NPM_PACKAGE = /^[a-zA-Z0-9_.-]+$/;
+var LIBRARY_SKILL = /^(@[a-zA-Z0-9_.-]+\/[a-zA-Z0-9_.-]+|[a-zA-Z0-9_.-]+):([a-zA-Z0-9_.-]+)$/;
+function inferName(source, type) {
+  if (type === "library") {
+    const match = source.match(LIBRARY_SKILL);
+    return match?.[2] ?? source;
+  }
+  if (type === "remote") {
+    try {
+      const url = new URL(source);
+      const parts = url.hostname.split(".");
+      if (parts.length >= 2) {
+        const fallback = parts[0] ?? source;
+        const secondLevel = parts[parts.length - 2] ?? fallback;
+        const brand = parts.length === 3 ? secondLevel : fallback;
+        if (brand !== "www" && brand !== "api" && brand !== "mcp") {
+          return brand;
+        }
+        return secondLevel;
+      }
+      return parts[0] ?? source;
+    } catch {
+      return source;
+    }
+  }
+  if (type === "package") {
+    let name = source.replace(/^@[^/]+\//, "");
+    name = name.replace(/^mcp-server-/, "");
+    name = name.replace(/^server-/, "");
+    name = name.replace(/-mcp$/, "");
+    name = name.replace(/-server$/, "");
+    return name;
+  }
+  if (type === "github" || type === "gitlab") {
+    const match = source.match(/\/([^/]+?)(?:\.git)?$/);
+    return match?.[1] ?? source;
+  }
+  if (type === "local") {
+    const normalized = source.replace(/\\/g, "/").replace(/\/+$/, "");
+    const lastSegment = normalized.split("/").pop();
+    return lastSegment ?? source;
+  }
+  if (type === "command") {
+    const parts = source.split(/\s+/);
+    const command = parts.find(
+      (p) => !p.startsWith("-") && p !== "npx" && p !== "node" && p !== "python" && p !== "python3"
+    );
+    return command ?? parts[0] ?? source;
+  }
+  return source;
+}
+function parseSource(input) {
+  const ghUrlMatch = input.match(GITHUB_URL);
+  if (ghUrlMatch) {
+    const owner = ghUrlMatch[1];
+    const repo = ghUrlMatch[2];
+    const path = ghUrlMatch[4];
+    if (!owner || !repo) {
+      return { type: "command", value: input, inferredName: inferName(input, "command") };
+    }
+    const inferredName = path ? path.split("/").pop() ?? repo : repo;
+    return {
+      type: "github",
+      value: input,
+      inferredName,
+      owner,
+      repo,
+      ref: ghUrlMatch[3],
+      path
+    };
+  }
+  const glUrlMatch = input.match(GITLAB_URL);
+  if (glUrlMatch) {
+    const owner = glUrlMatch[1];
+    const repo = glUrlMatch[2];
+    const path = glUrlMatch[4];
+    if (!owner || !repo) {
+      return { type: "command", value: input, inferredName: inferName(input, "command") };
+    }
+    const inferredName = path ? path.split("/").pop() ?? repo : repo;
+    return {
+      type: "gitlab",
+      value: input,
+      inferredName,
+      owner,
+      repo,
+      ref: glUrlMatch[3],
+      path
+    };
+  }
+  if (HTTP_URL.test(input)) {
+    return {
+      type: "remote",
+      value: input,
+      inferredName: inferName(input, "remote")
+    };
+  }
+  if (input.startsWith("/") || input.startsWith("./") || input.startsWith("../") || input.startsWith("~")) {
+    return {
+      type: "local",
+      value: input,
+      inferredName: inferName(input, "local")
+    };
+  }
+  const ghShorthand = input.match(GITHUB_SHORTHAND);
+  if (ghShorthand && !NPM_SCOPED.test(input)) {
+    const owner = ghShorthand[1];
+    const repo = ghShorthand[2];
+    const path = ghShorthand[3];
+    if (!owner || !repo) {
+      return { type: "command", value: input, inferredName: inferName(input, "command") };
+    }
+    const inferredName = path ? path.split("/").pop() ?? repo : repo;
+    return {
+      type: "github",
+      value: `https://github.com/${owner}/${repo}`,
+      inferredName,
+      owner,
+      repo,
+      path
+    };
+  }
+  const libraryMatch = input.match(LIBRARY_SKILL);
+  if (libraryMatch) {
+    return {
+      type: "library",
+      value: input,
+      inferredName: inferName(input, "library"),
+      owner: libraryMatch[1],
+      // This will be the package name, e.g. @cleocode/skills
+      repo: libraryMatch[2]
+      // This will be the skill name, e.g. ct-research-agent
+    };
+  }
+  if (NPM_SCOPED.test(input)) {
+    return {
+      type: "package",
+      value: input,
+      inferredName: inferName(input, "package")
+    };
   }
-}
-async function writeConfig(filePath, format, key, serverName, serverConfig) {
-  debug(`writing config: ${filePath} (format: ${format}, key: ${key}, server: ${serverName})`);
-  switch (format) {
-    case "json":
-    case "jsonc":
-      return writeJsonConfig(filePath, key, serverName, serverConfig);
-    case "yaml":
-      return writeYamlConfig(filePath, key, serverName, serverConfig);
-    case "toml":
-      return writeTomlConfig(filePath, key, serverName, serverConfig);
-    default:
-      throw new Error(`Unsupported config format: ${format}`);
+  if (NPM_PACKAGE.test(input) && !input.includes(" ")) {
+    return {
+      type: "package",
+      value: input,
+      inferredName: inferName(input, "package")
+    };
   }
+  return {
+    type: "command",
+    value: input,
+    inferredName: inferName(input, "command")
+  };
 }
-async function removeConfig(filePath, format, key, serverName) {
-  switch (format) {
-    case "json":
-    case "jsonc":
-      return removeJsonConfig(filePath, key, serverName);
-    case "yaml":
-      return removeYamlConfig(filePath, key, serverName);
-    case "toml":
-      return removeTomlConfig(filePath, key, serverName);
-    default:
-      throw new Error(`Unsupported config format: ${format}`);
-  }
+function isMarketplaceScoped(input) {
+  return /^@[a-zA-Z0-9_.-]+\/[a-zA-Z0-9_.-]+$/.test(input);
 }
 
 // src/core/skills/audit/scanner.ts
-import { existsSync as existsSync8 } from "fs";
+import { existsSync as existsSync10 } from "fs";
 import { readFile as readFile5 } from "fs/promises";
 
 // src/core/skills/audit/rules.ts
@@ -1534,7 +3049,7 @@ var SEVERITY_WEIGHTS = {
   info: 0
 };
 async function scanFile(filePath, rules) {
-  if (!existsSync8(filePath)) {
+  if (!existsSync10(filePath)) {
     return { file: filePath, findings: [], score: 100, passed: true };
   }
   const content = await readFile5(filePath, "utf-8");
@@ -1568,14 +3083,14 @@ async function scanFile(filePath, rules) {
 }
 async function scanDirectory(dirPath) {
   const { readdir: readdir3 } = await import("fs/promises");
-  const { join: join8 } = await import("path");
-  if (!existsSync8(dirPath)) return [];
+  const { join: join9 } = await import("path");
+  if (!existsSync10(dirPath)) return [];
   const entries = await readdir3(dirPath, { withFileTypes: true });
   const results = [];
   for (const entry of entries) {
     if (entry.isDirectory() || entry.isSymbolicLink()) {
-      const skillFile = join8(dirPath, entry.name, "SKILL.md");
-      if (existsSync8(skillFile)) {
+      const skillFile = join9(dirPath, entry.name, "SKILL.md");
+      if (existsSync10(skillFile)) {
         results.push(await scanFile(skillFile));
       }
     }
@@ -1626,178 +3141,14 @@ function toSarif(results) {
   };
 }
 
-// src/core/sources/parser.ts
-var GITHUB_SHORTHAND = /^([a-zA-Z0-9_.-]+)\/([a-zA-Z0-9_.-]+)(?:\/(.+))?$/;
-var GITHUB_URL = /^https?:\/\/(?:www\.)?github\.com\/([^/]+)\/([^/]+)(?:\/(?:tree|blob)\/([^/]+)(?:\/(.+))?)?/;
-var GITLAB_URL = /^https?:\/\/(?:www\.)?gitlab\.com\/([^/]+)\/([^/]+)(?:\/-\/(?:tree|blob)\/([^/]+)(?:\/(.+))?)?/;
-var HTTP_URL = /^https?:\/\//;
-var NPM_SCOPED = /^@[a-zA-Z0-9_.-]+\/[a-zA-Z0-9_.-]+$/;
-var NPM_PACKAGE = /^[a-zA-Z0-9_.-]+$/;
-var LIBRARY_SKILL = /^(@[a-zA-Z0-9_.-]+\/[a-zA-Z0-9_.-]+|[a-zA-Z0-9_.-]+):([a-zA-Z0-9_.-]+)$/;
-function inferName(source, type) {
-  if (type === "library") {
-    const match = source.match(LIBRARY_SKILL);
-    return match?.[2] ?? source;
-  }
-  if (type === "remote") {
-    try {
-      const url = new URL(source);
-      const parts = url.hostname.split(".");
-      if (parts.length >= 2) {
-        const fallback = parts[0] ?? source;
-        const secondLevel = parts[parts.length - 2] ?? fallback;
-        const brand = parts.length === 3 ? secondLevel : fallback;
-        if (brand !== "www" && brand !== "api" && brand !== "mcp") {
-          return brand;
-        }
-        return secondLevel;
-      }
-      return parts[0] ?? source;
-    } catch {
-      return source;
-    }
-  }
-  if (type === "package") {
-    let name = source.replace(/^@[^/]+\//, "");
-    name = name.replace(/^mcp-server-/, "");
-    name = name.replace(/^server-/, "");
-    name = name.replace(/-mcp$/, "");
-    name = name.replace(/-server$/, "");
-    return name;
-  }
-  if (type === "github" || type === "gitlab") {
-    const match = source.match(/\/([^/]+?)(?:\.git)?$/);
-    return match?.[1] ?? source;
-  }
-  if (type === "local") {
-    const normalized = source.replace(/\\/g, "/").replace(/\/+$/, "");
-    const lastSegment = normalized.split("/").pop();
-    return lastSegment ?? source;
-  }
-  if (type === "command") {
-    const parts = source.split(/\s+/);
-    const command = parts.find(
-      (p) => !p.startsWith("-") && p !== "npx" && p !== "node" && p !== "python" && p !== "python3"
-    );
-    return command ?? parts[0] ?? source;
-  }
-  return source;
-}
-function parseSource(input) {
-  const ghUrlMatch = input.match(GITHUB_URL);
-  if (ghUrlMatch) {
-    const owner = ghUrlMatch[1];
-    const repo = ghUrlMatch[2];
-    const path = ghUrlMatch[4];
-    if (!owner || !repo) {
-      return { type: "command", value: input, inferredName: inferName(input, "command") };
-    }
-    const inferredName = path ? path.split("/").pop() ?? repo : repo;
-    return {
-      type: "github",
-      value: input,
-      inferredName,
-      owner,
-      repo,
-      ref: ghUrlMatch[3],
-      path
-    };
-  }
-  const glUrlMatch = input.match(GITLAB_URL);
-  if (glUrlMatch) {
-    const owner = glUrlMatch[1];
-    const repo = glUrlMatch[2];
-    const path = glUrlMatch[4];
-    if (!owner || !repo) {
-      return { type: "command", value: input, inferredName: inferName(input, "command") };
-    }
-    const inferredName = path ? path.split("/").pop() ?? repo : repo;
-    return {
-      type: "gitlab",
-      value: input,
-      inferredName,
-      owner,
-      repo,
-      ref: glUrlMatch[3],
-      path
-    };
-  }
-  if (HTTP_URL.test(input)) {
-    return {
-      type: "remote",
-      value: input,
-      inferredName: inferName(input, "remote")
-    };
-  }
-  if (input.startsWith("/") || input.startsWith("./") || input.startsWith("../") || input.startsWith("~")) {
-    return {
-      type: "local",
-      value: input,
-      inferredName: inferName(input, "local")
-    };
-  }
-  const ghShorthand = input.match(GITHUB_SHORTHAND);
-  if (ghShorthand && !NPM_SCOPED.test(input)) {
-    const owner = ghShorthand[1];
-    const repo = ghShorthand[2];
-    const path = ghShorthand[3];
-    if (!owner || !repo) {
-      return { type: "command", value: input, inferredName: inferName(input, "command") };
-    }
-    const inferredName = path ? path.split("/").pop() ?? repo : repo;
-    return {
-      type: "github",
-      value: `https://github.com/${owner}/${repo}`,
-      inferredName,
-      owner,
-      repo,
-      path
-    };
-  }
-  const libraryMatch = input.match(LIBRARY_SKILL);
-  if (libraryMatch) {
-    return {
-      type: "library",
-      value: input,
-      inferredName: inferName(input, "library"),
-      owner: libraryMatch[1],
-      // This will be the package name, e.g. @cleocode/skills
-      repo: libraryMatch[2]
-      // This will be the skill name, e.g. ct-research-agent
-    };
-  }
-  if (NPM_SCOPED.test(input)) {
-    return {
-      type: "package",
-      value: input,
-      inferredName: inferName(input, "package")
-    };
-  }
-  if (NPM_PACKAGE.test(input) && !input.includes(" ")) {
-    return {
-      type: "package",
-      value: input,
-      inferredName: inferName(input, "package")
-    };
-  }
-  return {
-    type: "command",
-    value: input,
-    inferredName: inferName(input, "command")
-  };
-}
-function isMarketplaceScoped(input) {
-  return /^@[a-zA-Z0-9_.-]+\/[a-zA-Z0-9_.-]+$/.test(input);
-}
-
 // src/core/skills/lock.ts
 import { execFile } from "child_process";
 import { promisify } from "util";
 import { simpleGit } from "simple-git";
 
 // src/core/lock-utils.ts
-import { existsSync as existsSync9 } from "fs";
-import { mkdir as mkdir4, open, readFile as readFile6, rename as rename2, rm as rm4, stat, writeFile as writeFile5 } from "fs/promises";
+import { existsSync as existsSync11 } from "fs";
+import { mkdir as mkdir4, open as open2, readFile as readFile6, rename as rename2, rm as rm4, stat as stat3, writeFile as writeFile5 } from "fs/promises";
 var LOCK_GUARD_PATH = `${LOCK_FILE_PATH}.lock`;
 var STALE_LOCK_MS = 5e3;
 function sleep(ms) {
@@ -1805,7 +3156,7 @@ function sleep(ms) {
 }
 async function removeStaleLock() {
   try {
-    const info = await stat(LOCK_GUARD_PATH);
+    const info = await stat3(LOCK_GUARD_PATH);
     if (Date.now() - info.mtimeMs > STALE_LOCK_MS) {
       await rm4(LOCK_GUARD_PATH, { force: true });
       return true;
@@ -1818,7 +3169,7 @@ async function acquireLockGuard(retries = 40, delayMs = 25) {
   await mkdir4(AGENTS_HOME, { recursive: true });
   for (let attempt = 0; attempt < retries; attempt += 1) {
     try {
-      const handle = await open(LOCK_GUARD_PATH, "wx");
+      const handle = await open2(LOCK_GUARD_PATH, "wx");
       await handle.close();
       return;
     } catch (error) {
@@ -1844,7 +3195,7 @@ async function writeLockFileUnsafe(lock) {
 }
 async function readLockFile() {
   try {
-    if (!existsSync9(LOCK_FILE_PATH)) {
+    if (!existsSync11(LOCK_FILE_PATH)) {
       return { version: 1, skills: {}, mcpServers: {} };
     }
     const content = await readFile6(LOCK_FILE_PATH, "utf-8");
@@ -2575,9 +3926,9 @@ async function recommendSkills2(query, criteria, options = {}) {
 }
 
 // src/core/skills/library-loader.ts
-import { existsSync as existsSync10, readdirSync, readFileSync } from "fs";
+import { existsSync as existsSync12, readdirSync, readFileSync } from "fs";
 import { createRequire } from "module";
-import { basename as basename2, dirname as dirname3, join as join5 } from "path";
+import { basename as basename3, dirname as dirname3, join as join6 } from "path";
 var require2 = createRequire(import.meta.url);
 function loadLibraryFromModule(root) {
   let mod;
@@ -2623,16 +3974,16 @@ function loadLibraryFromModule(root) {
   return mod;
 }
 function buildLibraryFromFiles(root) {
-  const catalogPath = join5(root, "skills.json");
-  if (!existsSync10(catalogPath)) {
+  const catalogPath = join6(root, "skills.json");
+  if (!existsSync12(catalogPath)) {
     throw new Error(`No skills.json found at ${root}`);
   }
   const catalogData = JSON.parse(readFileSync(catalogPath, "utf-8"));
   const entries = catalogData.skills ?? [];
   const version = catalogData.version ?? "0.0.0";
-  const manifestPath = join5(root, "skills", "manifest.json");
+  const manifestPath = join6(root, "skills", "manifest.json");
   let manifest;
-  if (existsSync10(manifestPath)) {
+  if (existsSync12(manifestPath)) {
     manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
   } else {
     manifest = {
@@ -2642,14 +3993,14 @@ function buildLibraryFromFiles(root) {
       skills: []
     };
   }
-  const profilesDir = join5(root, "profiles");
+  const profilesDir = join6(root, "profiles");
   const profiles = /* @__PURE__ */ new Map();
-  if (existsSync10(profilesDir)) {
+  if (existsSync12(profilesDir)) {
     for (const file of readdirSync(profilesDir)) {
       if (!file.endsWith(".json")) continue;
       try {
         const profile = JSON.parse(
-          readFileSync(join5(profilesDir, file), "utf-8")
+          readFileSync(join6(profilesDir, file), "utf-8")
         );
         profiles.set(profile.name, profile);
       } catch {
@@ -2663,9 +4014,9 @@ function buildLibraryFromFiles(root) {
   function getSkillDir2(name) {
     const entry = skillMap.get(name);
     if (entry) {
-      return dirname3(join5(root, entry.path));
+      return dirname3(join6(root, entry.path));
     }
-    return join5(root, "skills", name);
+    return join6(root, "skills", name);
   }
   function resolveDeps(names, visited = /* @__PURE__ */ new Set()) {
     const result = [];
@@ -2693,8 +4044,8 @@ function buildLibraryFromFiles(root) {
     return resolveDeps([...new Set(skills)]);
   }
   function discoverFiles(dir, ext) {
-    if (!existsSync10(dir)) return [];
-    return readdirSync(dir).filter((f) => f.endsWith(ext)).map((f) => basename2(f, ext));
+    if (!existsSync12(dir)) return [];
+    return readdirSync(dir).filter((f) => f.endsWith(ext)).map((f) => basename3(f, ext));
   }
   const library = {
     version,
@@ -2710,14 +4061,14 @@ function buildLibraryFromFiles(root) {
     getSkillPath(name) {
       const entry = skillMap.get(name);
       if (entry) {
-        return join5(root, entry.path);
+        return join6(root, entry.path);
       }
-      return join5(root, "skills", name, "SKILL.md");
+      return join6(root, "skills", name, "SKILL.md");
     },
     getSkillDir: getSkillDir2,
     readSkillContent(name) {
       const skillPath = library.getSkillPath(name);
-      if (!existsSync10(skillPath)) {
+      if (!existsSync12(skillPath)) {
         throw new Error(`Skill content not found: ${skillPath}`);
       }
       return readFileSync(skillPath, "utf-8");
@@ -2744,11 +4095,11 @@ function buildLibraryFromFiles(root) {
       return resolveProfileByName(name);
     },
     listSharedResources() {
-      return discoverFiles(join5(root, "skills", "_shared"), ".md");
+      return discoverFiles(join6(root, "skills", "_shared"), ".md");
     },
     getSharedResourcePath(name) {
-      const resourcePath = join5(root, "skills", "_shared", `${name}.md`);
-      return existsSync10(resourcePath) ? resourcePath : void 0;
+      const resourcePath = join6(root, "skills", "_shared", `${name}.md`);
+      return existsSync12(resourcePath) ? resourcePath : void 0;
     },
     readSharedResource(name) {
       const resourcePath = library.getSharedResourcePath(name);
@@ -2756,15 +4107,15 @@ function buildLibraryFromFiles(root) {
       return readFileSync(resourcePath, "utf-8");
     },
     listProtocols() {
-      const rootProtocols = discoverFiles(join5(root, "protocols"), ".md");
+      const rootProtocols = discoverFiles(join6(root, "protocols"), ".md");
       if (rootProtocols.length > 0) return rootProtocols;
-      return discoverFiles(join5(root, "skills", "protocols"), ".md");
+      return discoverFiles(join6(root, "skills", "protocols"), ".md");
     },
     getProtocolPath(name) {
-      const rootPath = join5(root, "protocols", `${name}.md`);
-      if (existsSync10(rootPath)) return rootPath;
-      const skillsPath = join5(root, "skills", "protocols", `${name}.md`);
-      return existsSync10(skillsPath) ? skillsPath : void 0;
+      const rootPath = join6(root, "protocols", `${name}.md`);
+      if (existsSync12(rootPath)) return rootPath;
+      const skillsPath = join6(root, "skills", "protocols", `${name}.md`);
+      return existsSync12(skillsPath) ? skillsPath : void 0;
     },
     readProtocol(name) {
       const protocolPath = library.getProtocolPath(name);
@@ -2789,8 +4140,8 @@ function buildLibraryFromFiles(root) {
       if (!entry.version) {
         issues.push({ level: "warn", field: "version", message: "Missing version" });
       }
-      const skillPath = join5(root, entry.path);
-      if (!existsSync10(skillPath)) {
+      const skillPath = join6(root, entry.path);
+      if (!existsSync12(skillPath)) {
         issues.push({
           level: "error",
           field: "path",
@@ -2849,15 +4200,15 @@ __export(catalog_exports, {
   validateAll: () => validateAll,
   validateSkillFrontmatter: () => validateSkillFrontmatter
 });
-import { existsSync as existsSync11 } from "fs";
-import { join as join6 } from "path";
+import { existsSync as existsSync13 } from "fs";
+import { join as join7 } from "path";
 var _library = null;
 function registerSkillLibrary(library) {
   _library = library;
 }
 function registerSkillLibraryFromPath(root) {
-  const indexPath = join6(root, "index.js");
-  if (existsSync11(indexPath)) {
+  const indexPath = join7(root, "index.js");
+  if (existsSync13(indexPath)) {
     _library = loadLibraryFromModule(root);
     return;
   }
@@ -2868,13 +4219,13 @@ function clearRegisteredLibrary() {
 }
 function discoverLibrary() {
   const envPath = process.env["CAAMP_SKILL_LIBRARY"];
-  if (envPath && existsSync11(envPath)) {
+  if (envPath && existsSync13(envPath)) {
     try {
-      const indexPath = join6(envPath, "index.js");
-      if (existsSync11(indexPath)) {
+      const indexPath = join7(envPath, "index.js");
+      if (existsSync13(indexPath)) {
         return loadLibraryFromModule(envPath);
       }
-      if (existsSync11(join6(envPath, "skills.json"))) {
+      if (existsSync13(join7(envPath, "skills.json"))) {
         return buildLibraryFromFiles(envPath);
       }
     } catch {
@@ -2981,9 +4332,9 @@ function getLibraryRoot() {
 }
 
 // src/core/skills/discovery.ts
-import { existsSync as existsSync12 } from "fs";
+import { existsSync as existsSync14 } from "fs";
 import { readdir as readdir2, readFile as readFile7 } from "fs/promises";
-import { join as join7 } from "path";
+import { join as join8 } from "path";
 import matter from "gray-matter";
 async function parseSkillFile(filePath) {
   try {
@@ -3007,8 +4358,8 @@ async function parseSkillFile(filePath) {
   }
 }
 async function discoverSkill(skillDir) {
-  const skillFile = join7(skillDir, "SKILL.md");
-  if (!existsSync12(skillFile)) return null;
+  const skillFile = join8(skillDir, "SKILL.md");
+  if (!existsSync14(skillFile)) return null;
   const metadata = await parseSkillFile(skillFile);
   if (!metadata) return null;
   return {
@@ -3019,12 +4370,12 @@ async function discoverSkill(skillDir) {
   };
 }
 async function discoverSkills(rootDir) {
-  if (!existsSync12(rootDir)) return [];
+  if (!existsSync14(rootDir)) return [];
   const entries = await readdir2(rootDir, { withFileTypes: true });
   const skills = [];
   for (const entry of entries) {
     if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
-    const skillDir = join7(rootDir, entry.name);
+    const skillDir = join8(rootDir, entry.name);
     const skill = await discoverSkill(skillDir);
     if (skill) {
       skills.push(skill);
@@ -3048,7 +4399,7 @@ async function discoverSkillsMulti(dirs) {
 }
 
 // src/core/skills/validator.ts
-import { existsSync as existsSync13 } from "fs";
+import { existsSync as existsSync15 } from "fs";
 import { readFile as readFile8 } from "fs/promises";
 import matter2 from "gray-matter";
 var RESERVED_NAMES = [
@@ -3070,7 +4421,7 @@ var WARN_BODY_LINES = 500;
 var WARN_DESCRIPTION_LENGTH = 50;
 async function validateSkill(filePath) {
   const issues = [];
-  if (!existsSync13(filePath)) {
+  if (!existsSync15(filePath)) {
     return {
       valid: false,
       issues: [{ level: "error", field: "file", message: "File does not exist" }],
@@ -3205,6 +4556,13 @@ export {
   selectProvidersByMinimumPriority,
   installBatchWithRollback,
   updateInstructionsSingleOperation,
+  DEFAULT_EXCLUSIVITY_MODE,
+  EXCLUSIVITY_MODE_ENV_VAR,
+  PiRequiredError,
+  isExclusivityMode,
+  getExclusivityMode,
+  setExclusivityMode,
+  resetExclusivityModeOverride,
   PiHarness,
   getHarnessFor,
   getPrimaryHarness,
@@ -3219,17 +4577,25 @@ export {
   writeConfig,
   removeConfig,
   readLockFile,
+  resolveMcpConfigPath,
+  listMcpServers,
+  listAllMcpServers,
+  detectMcpInstallations,
+  installMcpServer,
+  removeMcpServer,
+  removeMcpServerFromAll,
+  fetchWithTimeout,
+  formatNetworkError,
+  parseSource,
+  isMarketplaceScoped,
   scanFile,
   scanDirectory,
   toSarif,
-  parseSource,
-  isMarketplaceScoped,
   recordSkillInstall,
   removeSkillFromLock,
   getTrackedSkills,
   checkSkillUpdate,
   checkAllSkillUpdates,
-  formatNetworkError,
   MarketplaceClient,
   RECOMMENDATION_ERROR_CODES,
   tokenizeCriteriaValue,
@@ -3258,4 +4624,4 @@ export {
   discoverSkillsMulti,
   validateSkill
 };
-//# sourceMappingURL=chunk-43GULI6J.js.map
+//# sourceMappingURL=chunk-JC77OAHA.js.map