@cleocode/caamp 2026.4.7 → 2026.4.10

package/dist/{chunk-HEAGCHKU.js → chunk-XVZT7K6F.js}

@@ -511,12 +511,78 @@ 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, open, readdir, readFile, rename, rm as rm3, stat, 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";
@@ -626,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.
@@ -662,19 +760,25 @@ var PiHarness = class {
     return scope.kind === "global" ? join5(getPiAgentDir2(), "AGENTS.md") : join5(scope.projectDir, "AGENTS.md");
   }
   // ── Skills ──────────────────────────────────────────────────────────
-  /** {@inheritDoc Harness.installSkill} */
+  /**
+   * Install a skill directory into the resolved Pi skills location.
+   */
   async installSkill(sourcePath, skillName, scope) {
     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} */
+  /**
+   * Remove a skill directory from the resolved Pi skills location.
+   */
   async removeSkill(skillName, scope) {
     const targetDir = join5(this.skillsDir(scope), skillName);
     await rm3(targetDir, { recursive: true, force: true });
   }
-  /** {@inheritDoc Harness.listSkills} */
+  /**
+   * List the installed skill directories at the given scope.
+   */
   async listSkills(scope) {
     const dir = this.skillsDir(scope);
     if (!existsSync4(dir)) return [];
@@ -682,7 +786,10 @@ var PiHarness = class {
     return entries.filter((e) => e.isDirectory()).map((e) => e.name);
   }
   // ── Instructions ────────────────────────────────────────────────────
-  /** {@inheritDoc Harness.injectInstructions} */
+  /**
+   * Inject or replace a CAAMP-managed instruction block inside the Pi
+   * `AGENTS.md` file for the resolved scope.
+   */
   async injectInstructions(content, scope) {
     const filePath = this.agentsMdPath(scope);
     await mkdir3(dirname2(filePath), { recursive: true });
@@ -706,7 +813,10 @@ ${MARKER_END}`;
     }
     await writeFile(filePath, updated, "utf8");
   }
-  /** {@inheritDoc Harness.removeInstructions} */
+  /**
+   * Remove the CAAMP-managed instruction block from the Pi `AGENTS.md`
+   * file at the resolved scope.
+   */
   async removeInstructions(scope) {
     const filePath = this.agentsMdPath(scope);
     if (!existsSync4(filePath)) return;
@@ -716,21 +826,79 @@ ${MARKER_END}`;
     await writeFile(filePath, stripped.length === 0 ? "" : `${stripped}
 `, "utf8");
   }
-  // ── Subagent spawn ──────────────────────────────────────────────────
+  // ── Subagent spawn (ADR-035 §D6) ────────────────────────────────────
   /**
-   * {@inheritDoc Harness.spawnSubagent}
+   * Spawn a subagent through Pi's configured `spawnCommand` and return a
+   * live handle bound to the canonical streaming, attribution, and
+   * cleanup contract.
    *
    * @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.
+   * 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.
    *
-   * Throws immediately when the provider entry is missing a `spawnCommand`
-   * so callers see configuration errors early rather than at child-exit time.
+   * **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.
+   *
+   * **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(
@@ -741,46 +909,316 @@ ${MARKER_END}`;
     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} */
+  /**
+   * Read the Pi `settings.json` file for the resolved scope.
+   */
   async readSettings(scope) {
     const filePath = this.settingsPath(scope);
     if (!existsSync4(filePath)) return {};
@@ -791,7 +1229,10 @@ ${MARKER_END}`;
       return {};
     }
   }
-  /** {@inheritDoc Harness.writeSettings} */
+  /**
+   * Merge a partial patch into the Pi `settings.json` file for the
+   * resolved scope using an atomic write.
+   */
   async writeSettings(patch, scope) {
     const filePath = this.settingsPath(scope);
     const current = await this.readSettings(scope);
@@ -799,7 +1240,10 @@ ${MARKER_END}`;
     const merged = deepMerge(currentObj, patch);
     await atomicWriteJson(filePath, merged);
   }
-  /** {@inheritDoc Harness.configureModels} */
+  /**
+   * Persist the supplied model-name patterns into `settings.enabledModels`
+   * at the resolved scope.
+   */
   async configureModels(modelPatterns, scope) {
     await this.writeSettings({ enabledModels: modelPatterns }, scope);
   }
@@ -824,7 +1268,10 @@ ${MARKER_END}`;
     return join5(getPiAgentDir2(), "sessions");
   }
   // ── Extensions (Wave-1, T263) ───────────────────────────────────────
-  /** {@inheritDoc Harness.installExtension} */
+  /**
+   * Install a Pi extension `.ts` source file into the resolved tier's
+   * extensions directory, validating that it has a default export.
+   */
   async installExtension(sourcePath, name, tier, projectDir, opts) {
     if (!existsSync4(sourcePath)) {
       throw new Error(`installExtension: source file does not exist: ${sourcePath}`);
@@ -856,7 +1303,9 @@ ${MARKER_END}`;
     await writeFile(targetPath, contents, "utf8");
     return { targetPath, tier };
   }
-  /** {@inheritDoc Harness.removeExtension} */
+  /**
+   * Remove a Pi extension `.ts` source file from the resolved tier.
+   */
   async removeExtension(name, tier, projectDir) {
     const dir = resolveTierDir({ tier, kind: "extensions", projectDir });
     const targetPath = join5(dir, `${name}.ts`);
@@ -864,7 +1313,10 @@ ${MARKER_END}`;
     await rm3(targetPath, { force: true });
     return true;
   }
-  /** {@inheritDoc Harness.listExtensions} */
+  /**
+   * List Pi extension files across every tier in precedence order,
+   * flagging shadowed entries from lower tiers.
+   */
   async listExtensions(projectDir) {
     const tiers = resolveAllTiers("extensions", projectDir);
     const out = [];
@@ -895,7 +1347,10 @@ ${MARKER_END}`;
     return out;
   }
   // ── Sessions (Wave-1, T264) ─────────────────────────────────────────
-  /** {@inheritDoc Harness.listSessions} */
+  /**
+   * List Pi session JSONL files (including subagent children when
+   * requested), summarising only the header line per file.
+   */
   async listSessions(opts) {
     const rootDir = this.sessionsDir();
     if (!existsSync4(rootDir)) return [];
@@ -935,7 +1390,9 @@ ${MARKER_END}`;
     summaries.sort((a, b) => b.mtimeMs - a.mtimeMs);
     return summaries;
   }
-  /** {@inheritDoc Harness.showSession} */
+  /**
+   * Show the full entries of a single Pi session by id.
+   */
   async showSession(id) {
     const summaries = await this.listSessions({ includeSubagents: true });
     const match = summaries.find((s) => s.id === id);
@@ -951,7 +1408,10 @@ ${MARKER_END}`;
     return { summary: match, entries };
   }
   // ── Models (Wave-1, T265) ───────────────────────────────────────────
-  /** {@inheritDoc Harness.readModelsConfig} */
+  /**
+   * Read the Pi `models.json` file for the resolved scope, tolerating
+   * missing or malformed files by returning an empty provider map.
+   */
   async readModelsConfig(scope) {
     const filePath = this.modelsConfigPath(scope);
     if (!existsSync4(filePath)) return { providers: {} };
@@ -977,12 +1437,18 @@ ${MARKER_END}`;
       return { providers: {} };
     }
   }
-  /** {@inheritDoc Harness.writeModelsConfig} */
+  /**
+   * Write the Pi `models.json` file for the resolved scope via an atomic
+   * tmp-then-rename sequence.
+   */
   async writeModelsConfig(config, scope) {
     const filePath = this.modelsConfigPath(scope);
     await atomicWriteJson(filePath, config);
   }
-  /** {@inheritDoc Harness.listModels} */
+  /**
+   * Compose a flat `ModelListEntry` list from `models.json` plus the
+   * `enabledModels` and default-model hints in `settings.json`.
+   */
   async listModels(scope) {
     const models = await this.readModelsConfig(scope);
     const settings = await this.readSettings(scope);
@@ -1044,7 +1510,10 @@ ${MARKER_END}`;
     return out;
   }
   // ── Prompts (Wave-1, T266) ──────────────────────────────────────────
-  /** {@inheritDoc Harness.installPrompt} */
+  /**
+   * Install a Pi prompt directory (containing `prompt.md`) into the
+   * resolved tier's prompts directory.
+   */
   async installPrompt(sourceDir, name, tier, projectDir, opts) {
     if (!existsSync4(sourceDir)) {
       throw new Error(`installPrompt: source directory does not exist: ${sourceDir}`);
@@ -1070,7 +1539,10 @@ ${MARKER_END}`;
     await cp3(sourceDir, targetPath, { recursive: true });
     return { targetPath, tier };
   }
-  /** {@inheritDoc Harness.listPrompts} */
+  /**
+   * List Pi prompt directories across every tier in precedence order,
+   * flagging shadowed entries from lower tiers.
+   */
   async listPrompts(projectDir) {
     const tiers = resolveAllTiers("prompts", projectDir);
     const out = [];
@@ -1098,7 +1570,9 @@ ${MARKER_END}`;
     }
     return out;
   }
-  /** {@inheritDoc Harness.removePrompt} */
+  /**
+   * Remove a Pi prompt directory from the resolved tier.
+   */
   async removePrompt(name, tier, projectDir) {
     const dir = resolveTierDir({ tier, kind: "prompts", projectDir });
     const targetPath = join5(dir, name);
@@ -1107,7 +1581,11 @@ ${MARKER_END}`;
     return true;
   }
   // ── Themes (Wave-1, T267) ───────────────────────────────────────────
-  /** {@inheritDoc Harness.installTheme} */
+  /**
+   * Install a Pi theme file (`.ts`/`.tsx`/`.mts`/`.json`) into the
+   * resolved tier's themes directory, blocking same-stem conflicts
+   * unless `--force` is supplied.
+   */
   async installTheme(sourceFile, name, tier, projectDir, opts) {
     if (!existsSync4(sourceFile)) {
       throw new Error(`installTheme: source file does not exist: ${sourceFile}`);
@@ -1146,7 +1624,10 @@ ${MARKER_END}`;
     await writeFile(targetPath, contents);
     return { targetPath, tier };
   }
-  /** {@inheritDoc Harness.listThemes} */
+  /**
+   * List Pi theme files across every tier in precedence order, flagging
+   * shadowed entries from lower tiers.
+   */
   async listThemes(projectDir) {
     const tiers = resolveAllTiers("themes", projectDir);
     const out = [];
@@ -1178,7 +1659,10 @@ ${MARKER_END}`;
     }
     return out;
   }
-  /** {@inheritDoc Harness.removeTheme} */
+  /**
+   * Remove a Pi theme from the resolved tier, matching any of the
+   * supported theme extensions for the given name stem.
+   */
   async removeTheme(name, tier, projectDir) {
     const dir = resolveTierDir({ tier, kind: "themes", projectDir });
     let removed = false;
@@ -1191,7 +1675,187 @@ ${MARKER_END}`;
     }
     return removed;
   }
+  // ── CANT profiles (Wave-1, T276) ────────────────────────────────────
+  /**
+   * Install a `.cant` profile into the resolved tier after passing it
+   * through the cant-core validator.
+   *
+   * Validates the source via {@link PiHarness.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 `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 };
+  }
+  /**
+   * Remove a `.cant` profile from the resolved tier.
+   */
+  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;
+  }
+  /**
+   * List installed `.cant` profiles across every tier in precedence
+   * order, parsing each file to extract section counts.
+   *
+   * Walks every tier in `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;
+  }
+  /**
+   * Validate a `.cant` source file against cant-core's parser and
+   * 42-rule linter, returning section counts and per-diagnostic detail.
+   *
+   * 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 {
@@ -1243,6 +1907,104 @@ async function readSessionHeader(filePath) {
     }
   }
 }
+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) {
@@ -1262,28 +2024,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();
+  }
+  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 installed;
+  return legacyFallback();
 }
 async function dispatchInstallSkillAcrossProviders(sourcePath, skillName, providers, isGlobal, projectDir) {
   const harnessTargets = [];
@@ -3817,6 +4618,13 @@ export {
   selectProvidersByMinimumPriority,
   installBatchWithRollback,
   updateInstructionsSingleOperation,
+  DEFAULT_EXCLUSIVITY_MODE,
+  EXCLUSIVITY_MODE_ENV_VAR,
+  PiRequiredError,
+  isExclusivityMode,
+  getExclusivityMode,
+  setExclusivityMode,
+  resetExclusivityModeOverride,
   PiHarness,
   getHarnessFor,
   getPrimaryHarness,
@@ -3878,4 +4686,4 @@ export {
   discoverSkillsMulti,
   validateSkill
 };
-//# sourceMappingURL=chunk-HEAGCHKU.js.map
+//# sourceMappingURL=chunk-XVZT7K6F.js.map