@cleocode/caamp 2026.4.7 → 2026.4.9

package/dist/index.d.ts

@@ -1487,252 +1487,6 @@ interface InstructionUpdateSummary {
  */
 declare function updateInstructionsSingleOperation(providers: Provider[], content: string, scope?: Scope, projectDir?: string): Promise<InstructionUpdateSummary>;
 
-/**
- * Format utility functions
- */
-/**
- * Deep merge two objects, with `source` values winning on conflict.
- *
- * Recursively merges nested plain objects. Arrays and non-object values from
- * `source` overwrite `target` values.
- *
- * @param target - Base object to merge into
- * @param source - Object with values that take precedence
- * @returns A new merged object (does not mutate inputs)
- *
- * @remarks
- * Only plain objects are recursively merged. Arrays and primitive values from
- * `source` replace `target` values outright. Neither input is mutated.
- *
- * @example
- * ```typescript
- * const merged = deepMerge({ a: 1, b: { c: 2 } }, { b: { d: 3 } });
- * // { a: 1, b: { c: 2, d: 3 } }
- * ```
- *
- * @public
- */
-declare function deepMerge(target: Record<string, unknown>, source: Record<string, unknown>): Record<string, unknown>;
-/**
- * Get a nested value from an object using a dot-notation key path.
- *
- * @param obj - Object to traverse
- * @param keyPath - Dot-separated key path (e.g. `"mcpServers"` or `"a.b.c"`)
- * @returns The value at the key path, or `undefined` if not found
- *
- * @remarks
- * Splits the key path on `.` and walks the object tree. Returns `undefined`
- * at the first missing or non-object segment.
- *
- * @example
- * ```typescript
- * getNestedValue({ a: { b: { c: 42 } } }, "a.b.c"); // 42
- * getNestedValue({ a: 1 }, "a.b"); // undefined
- * ```
- *
- * @public
- */
-declare function getNestedValue(obj: Record<string, unknown>, keyPath: string): unknown;
-/**
- * Ensure that the parent directories of a file path exist.
- *
- * Creates directories recursively if they do not exist.
- *
- * @param filePath - Absolute path to a file (parent directories will be created)
- *
- * @remarks
- * Uses `mkdir` with `recursive: true` so existing directories are not an error.
- *
- * @example
- * ```typescript
- * await ensureDir("/path/to/new/dir/file.json");
- * // /path/to/new/dir/ now exists
- * ```
- *
- * @public
- */
-declare function ensureDir(filePath: string): Promise<void>;
-
-/**
- * Provides format-agnostic config read, write, and remove operations that
- * dispatch to JSON/JSONC, YAML, or TOML handlers based on the specified
- * format.
- *
- * @packageDocumentation
- */
-
-/**
- * Read and parse a config file in the specified format.
- *
- * Dispatches to the appropriate format handler (JSON/JSONC, YAML, or TOML).
- *
- * @param filePath - Absolute path to the config file
- * @param format - Config file format
- * @returns Parsed config object
- * @throws If the file cannot be read or the format is unsupported
- *
- * @remarks
- * Supported formats: `"json"`, `"jsonc"`, `"yaml"`, `"toml"`. Throws for
- * any unrecognized format string.
- *
- * @example
- * ```typescript
- * const config = await readConfig("/path/to/config.json", "jsonc");
- * ```
- *
- * @public
- */
-declare function readConfig(filePath: string, format: ConfigFormat): Promise<Record<string, unknown>>;
-/**
- * Write a server entry to a config file, preserving existing content.
- *
- * Dispatches to the appropriate format handler. For JSONC files, comments are
- * preserved using `jsonc-parser`.
- *
- * @param filePath - Absolute path to the config file
- * @param format - Config file format
- * @param key - Dot-notation key path to the servers section (e.g. `"mcpServers"`)
- * @param serverName - Name/key for the server entry
- * @param serverConfig - Server configuration object to write
- * @throws If the format is unsupported
- *
- * @remarks
- * For JSONC files, comments and formatting are preserved using `jsonc-parser`.
- * For YAML and TOML, the file is fully re-serialized after deep-merging.
- *
- * @example
- * ```typescript
- * await writeConfig("/path/to/config.json", "jsonc", "mcpServers", "my-server", config);
- * ```
- *
- * @public
- */
-declare function writeConfig(filePath: string, format: ConfigFormat, key: string, serverName: string, serverConfig: unknown): Promise<void>;
-/**
- * Remove a server entry from a config file in the specified format.
- *
- * @param filePath - Absolute path to the config file
- * @param format - Config file format
- * @param key - Dot-notation key path to the servers section
- * @param serverName - Name/key of the server entry to remove
- * @returns `true` if the entry was removed, `false` otherwise
- * @throws If the format is unsupported
- *
- * @remarks
- * Delegates to the format-specific removal function. Returns `false` when the
- * file does not exist or the entry is not found.
- *
- * @example
- * ```typescript
- * const removed = await removeConfig("/path/to/config.json", "jsonc", "mcpServers", "my-server");
- * ```
- *
- * @public
- */
-declare function removeConfig(filePath: string, format: ConfigFormat, key: string, serverName: string): Promise<boolean>;
-
-/**
- * Skill installer - canonical + symlink model
- *
- * Skills are stored once in a canonical location (.agents/skills/<name>/)
- * and symlinked to each target agent's skills directory.
- */
-
-/**
- * Result of installing a skill to the canonical location and linking to agents.
- *
- * @example
- * ```typescript
- * const result = await installSkill(sourcePath, "my-skill", providers, true);
- * if (result.success) {
- *   console.log(`Installed to ${result.canonicalPath}`);
- *   console.log(`Linked to: ${result.linkedAgents.join(", ")}`);
- * }
- * ```
- *
- * @public
- */
-interface SkillInstallResult {
-    /** Skill name. */
-    name: string;
-    /** Absolute path to the canonical installation directory. */
-    canonicalPath: string;
-    /** Provider IDs that were successfully linked. */
-    linkedAgents: string[];
-    /** Error messages from failed link operations. */
-    errors: string[];
-    /** Whether at least one agent was successfully linked. */
-    success: boolean;
-}
-/**
- * Install a skill from a local path to the canonical location and link to agents.
- *
- * @remarks
- * Copies the skill directory to the canonical skills directory and creates symlinks
- * (or copies on Windows) from each provider's skills directory to the canonical path.
- *
- * @param sourcePath - Local path to the skill directory to install
- * @param skillName - Name for the installed skill
- * @param providers - Target providers to link the skill to
- * @param isGlobal - Whether to link to global or project skill directories
- * @param projectDir - Project directory (defaults to `process.cwd()`)
- * @returns Install result with linked agents and any errors
- *
- * @example
- * ```typescript
- * const result = await installSkill("/tmp/my-skill", "my-skill", providers, true, "/my/project");
- * if (result.success) {
- *   console.log(`Linked to: ${result.linkedAgents.join(", ")}`);
- * }
- * ```
- *
- * @public
- */
-declare function installSkill(sourcePath: string, skillName: string, providers: Provider[], isGlobal: boolean, projectDir?: string): Promise<SkillInstallResult>;
-/**
- * Remove a skill from the canonical location and all agent symlinks.
- *
- * @remarks
- * Removes symlinks from each provider's skills directory and then removes the
- * canonical copy from the centralized canonical skills directory.
- *
- * @param skillName - Name of the skill to remove
- * @param providers - Providers to unlink the skill from
- * @param isGlobal - Whether to target global or project skill directories
- * @param projectDir - Project directory (defaults to `process.cwd()`)
- * @returns Object with arrays of successfully removed provider IDs and error messages
- *
- * @example
- * ```typescript
- * const { removed, errors } = await removeSkill("my-skill", providers, true, "/my/project");
- * console.log(`Removed from: ${removed.join(", ")}`);
- * ```
- *
- * @public
- */
-declare function removeSkill(skillName: string, providers: Provider[], isGlobal: boolean, projectDir?: string): Promise<{
-    removed: string[];
-    errors: string[];
-}>;
-/**
- * List all skills installed in the canonical skills directory.
- *
- * @remarks
- * Returns the directory names of all skills, which correspond to skill names.
- * Includes both regular directories and symlinks in the canonical location.
- *
- * @returns Array of skill names
- *
- * @example
- * ```typescript
- * const skills = await listCanonicalSkills();
- * // ["my-skill", "another-skill"]
- * ```
- *
- * @public
- */
-declare function listCanonicalSkills(): Promise<string[]>;
-
 /**
  * Three-tier scope helper for Pi harness operations.
  *
@@ -1816,6 +1570,72 @@ type HarnessScope = {
     kind: 'project';
     projectDir: string;
 };
+/**
+ * Options accepted by `resolveDefaultTargetProviders` (defined in
+ * `./index.ts`).
+ *
+ * @remarks
+ * Both fields are optional. When the entire options object is omitted the
+ * helper behaves exactly as it did pre-ADR-035 §D7 in `auto` mode with Pi
+ * installed — the no-regression contract for existing callers.
+ *
+ * Lives here in `types.ts` rather than next to the function so that
+ * downstream packages can `import type { ResolveDefaultTargetProvidersOptions }`
+ * without pulling in the harness dispatcher's runtime imports.
+ *
+ * @public
+ */
+interface ResolveDefaultTargetProvidersOptions {
+    /**
+     * Explicit list of providers requested by the user (e.g. via `--agent`).
+     *
+     * @remarks
+     * When supplied, this list signals that the caller is honouring an
+     * explicit user selection rather than asking for the implicit default.
+     * In `auto` mode, an explicit list that excludes Pi while Pi is installed
+     * triggers a one-time deprecation warning per process. In `force-pi`
+     * mode the explicit list is ignored if it does not contain Pi (Pi is
+     * still required). In `legacy` mode the list is returned verbatim with
+     * no warning.
+     *
+     * Pass `undefined` (or omit entirely) to request the implicit default
+     * resolution.
+     *
+     * @defaultValue undefined
+     */
+    explicit?: Provider[];
+}
+/**
+ * Controls how `resolveDefaultTargetProviders` (defined in `./index.ts`)
+ * selects target providers at runtime invocation time.
+ *
+ * @remarks
+ * Introduced by ADR-035 §D7 ("v3 exclusivity") to give users an explicit
+ * knob over how aggressively CAAMP routes runtime commands through Pi
+ * versus other installed providers.
+ *
+ * - `'auto'` (default) — Pi is preferred when installed; explicit
+ *   `--agent <non-pi>` selections are still honoured but emit a one-time
+ *   deprecation warning per process. Behaviourally identical to v2026.4.5
+ *   when no explicit non-Pi target is supplied.
+ * - `'force-pi'` — Pi is required at runtime invocation. The dispatcher
+ *   throws with an `E_NOT_FOUND_RESOURCE`-shaped error when Pi is not
+ *   installed; callers decide whether to surface this as an exit code 4
+ *   or render a remediation hint.
+ * - `'legacy'` — Pre-exclusivity behaviour. No deprecation warnings, no
+ *   hard requirement on Pi. Matches the resolution order CAAMP shipped
+ *   before ADR-035 §D7 landed; preserved so users with brittle scripts
+ *   can pin until they migrate.
+ *
+ * **Important**: this setting affects RUNTIME INVOCATION paths only. Skill
+ * and instruction install paths
+ * (e.g. {@link dispatchInstallSkillAcrossProviders} and friends) are
+ * UNAFFECTED and continue to dispatch to multiple providers regardless of
+ * mode. See ADR-035 §D7 for the full design rationale.
+ *
+ * @public
+ */
+type ExclusivityMode = 'auto' | 'force-pi' | 'legacy';
 /**
  * Metadata describing a Pi extension discovered on disk.
  *
@@ -1896,6 +1716,121 @@ interface HarnessInstallOptions {
      */
     force?: boolean;
 }
+/**
+ * Counts of top-level CANT sections discovered in a `.cant` file.
+ *
+ * @remarks
+ * Returned by {@link Harness.listCantProfiles} and
+ * {@link Harness.validateCantProfile} so that callers can surface a
+ * concise summary of every profile (agents, workflows, pipelines,
+ * top-level hooks, and skill references declared by an agent's
+ * `skills:` property) without reading the full document body.
+ *
+ * The cant-core AST tags every section as a single-key wrapper
+ * (`{ Agent: { ... } }`, `{ Workflow: { ... } }`, etc.), so these
+ * counters are derived by walking `document.sections` and bucketing
+ * by tag. `skillCount` aggregates the unique skill names declared
+ * across every Agent section's `skills:` property — it is NOT a
+ * count of standalone `skill { ... }` blocks because cant-core does
+ * not currently expose those at the document level.
+ *
+ * @public
+ */
+interface CantProfileCounts {
+    /** Number of `agent { ... }` sections in the document. */
+    agentCount: number;
+    /** Number of `workflow { ... }` sections in the document. */
+    workflowCount: number;
+    /** Number of `pipeline { ... }` sections in the document. */
+    pipelineCount: number;
+    /**
+     * Number of hook bodies discovered. Top-level `Hook` sections plus
+     * the `hooks` array nested inside every Agent section are summed.
+     */
+    hookCount: number;
+    /**
+     * Number of distinct skill names referenced via an Agent section's
+     * `skills:` property (e.g. `skills: ["ct-cleo", "ct-task-executor"]`).
+     * The count is de-duplicated across agents within a single document.
+     */
+    skillCount: number;
+}
+/**
+ * Metadata describing a `.cant` profile installed at one of the three
+ * Pi harness tiers.
+ *
+ * @remarks
+ * Returned by {@link Harness.listCantProfiles}. Mirrors the shape of
+ * {@link ExtensionEntry} so consumers can render both with the same
+ * UI primitives, but adds a {@link counts} bag with parsed AST stats
+ * so the list output can summarise each profile without forcing the
+ * caller to re-parse every file.
+ *
+ * @public
+ */
+interface CantProfileEntry {
+    /** Profile name (basename of the `.cant` file without the extension). */
+    name: string;
+    /** Tier at which this entry lives. */
+    tier: HarnessTier;
+    /** Absolute on-disk path to the `.cant` file. */
+    sourcePath: string;
+    /** Parsed section counts for the profile. */
+    counts: CantProfileCounts;
+    /**
+     * When `true`, this entry is shadowed by a higher-precedence entry
+     * with the same name. Mirrors the shadow flag emitted by
+     * {@link Harness.listExtensions} so the same UI logic applies.
+     * @defaultValue false
+     */
+    shadowedByHigherTier?: boolean;
+}
+/**
+ * Diagnostic emitted by the cant-core 42-rule validator, normalised to
+ * the harness layer's vocabulary.
+ *
+ * @remarks
+ * Mirrors the `NativeDiagnostic` shape exported by `@cleocode/cant`'s
+ * native loader. Captured here as a first-class harness type so callers
+ * never have to import from `@cleocode/cant` directly to consume
+ * {@link Harness.validateCantProfile} results.
+ *
+ * @public
+ */
+interface CantValidationDiagnostic {
+    /** Cant-core rule id (`PARSE`, `S01`, `P06`, ...). */
+    ruleId: string;
+    /** Human-readable diagnostic message. */
+    message: string;
+    /** 1-based line number where the diagnostic was emitted. */
+    line: number;
+    /** 1-based column number where the diagnostic was emitted. */
+    col: number;
+    /** Severity bucket from cant-core (`error`, `warning`, `info`, `hint`). */
+    severity: 'error' | 'warning' | 'info' | 'hint';
+}
+/**
+ * Result of validating a `.cant` profile via the cant-core 42-rule
+ * engine.
+ *
+ * @remarks
+ * Returned by {@link Harness.validateCantProfile}. The `valid` flag is
+ * `true` only when no error-severity diagnostics were emitted (warnings
+ * are tolerated, matching cant-core's own definition). The
+ * {@link counts} bag is populated only when parsing succeeded — when
+ * the file is so broken cant-core cannot produce a document, every
+ * counter is `0` and the diagnostics array carries the parse errors.
+ *
+ * @public
+ */
+interface ValidateCantProfileResult {
+    /** Whether validation passed (no error-severity diagnostics). */
+    valid: boolean;
+    /** All diagnostics emitted by the 42-rule engine, in source order. */
+    errors: CantValidationDiagnostic[];
+    /** Section counts for the profile (zero when parsing failed). */
+    counts: CantProfileCounts;
+}
 /**
  * Summary header extracted from the first line of a Pi session JSONL file.
  *
@@ -2058,6 +1993,12 @@ interface ModelListEntry {
  * is a routing hint passed to the harness; concrete harnesses may use it
  * to select an inner agent or simply record it for observability.
  *
+ * Per ADR-035 §D6, every spawn has a stable {@link taskId} and is
+ * attributed to a parent session via {@link parentSessionId}. When the
+ * caller provides {@link parentSessionPath}, the harness records a
+ * `subagent_link` custom entry into that file so listing the parent
+ * session surfaces its children automatically.
+ *
  * @public
  */
 interface SubagentTask {
@@ -2065,6 +2006,42 @@ interface SubagentTask {
     targetProviderId: string;
     /** The prompt / instruction to give the spawned agent. */
     prompt: string;
+    /**
+     * Stable task identifier used to derive the child session filename and
+     * to correlate streamed events with their originating task.
+     *
+     * @remarks
+     * When omitted, the harness generates a short id at spawn time so
+     * legacy callers (pre-ADR-035 §D6) keep working. New callers SHOULD
+     * always supply a deterministic value.
+     *
+     * @defaultValue undefined
+     */
+    taskId?: string;
+    /**
+     * Identifier of the parent session that owns this subagent.
+     *
+     * @remarks
+     * Used to compose the child session filename
+     * (`subagent-{parentSessionId}-{taskId}.jsonl`) per ADR-035 §D6.
+     * When omitted, the harness substitutes `"orphan"` so legacy callers
+     * still produce a well-formed file path.
+     *
+     * @defaultValue undefined
+     */
+    parentSessionId?: string;
+    /**
+     * Absolute path to the parent session JSONL file.
+     *
+     * @remarks
+     * When supplied, the harness appends a {@link SubagentLinkEntry} as
+     * a `custom` entry to this file at spawn time so listing the parent
+     * surfaces its children automatically. When omitted, no link entry
+     * is written and the parent session is not modified.
+     *
+     * @defaultValue undefined
+     */
+    parentSessionPath?: string;
     /**
      * Working directory for the spawned agent.
      * @defaultValue undefined
@@ -2076,18 +2053,136 @@ interface SubagentTask {
      */
     env?: Record<string, string>;
     /**
-     * Abort signal. When it aborts, the harness will terminate the subagent.
+     * Abort signal. When it aborts, the harness will terminate the subagent
+     * via the configured SIGTERM-then-SIGKILL cleanup sequence.
      * @defaultValue undefined
      */
     signal?: AbortSignal;
 }
 /**
- * Final result of a subagent's execution.
+ * Per-call options that override harness-wide spawn defaults.
+ *
+ * @remarks
+ * Introduced for ADR-035 §D6 streaming + cleanup semantics. Every field
+ * is optional so callers that just want default behaviour can omit the
+ * second argument entirely.
+ *
+ * @public
+ */
+interface SubagentSpawnOptions {
+    /**
+     * Streaming callback invoked once per parsed event from the child.
+     *
+     * @remarks
+     * The harness fires this for every line of stdout (parsed as JSON when
+     * possible), every line of stderr, the final exit, and the
+     * `subagent_link` write. Callbacks are best-effort: throwing from the
+     * callback is caught and recorded as a stderr line so the spawn loop
+     * is never aborted by user code.
+     *
+     * @defaultValue undefined
+     */
+    onStream?: (event: SubagentStreamEvent) => void;
+    /**
+     * Override the SIGTERM grace window before SIGKILL fires.
+     *
+     * @remarks
+     * When omitted, the harness reads
+     * `settings.json:pi.subagent.terminateGraceMs` (global scope) and
+     * falls back to `5000` ms if absent or invalid. Tests use very small
+     * values to keep cleanup checks fast.
+     *
+     * @defaultValue undefined
+     */
+    terminateGraceMs?: number;
+    /**
+     * Environment variable overrides layered atop the task-level env.
+     *
+     * @remarks
+     * Convenience hook for per-call secrets that should not live on the
+     * task object itself. Merged after {@link SubagentTask.env} so
+     * call-site keys win.
+     *
+     * @defaultValue undefined
+     */
+    env?: Record<string, string>;
+    /**
+     * Working directory override that wins over {@link SubagentTask.cwd}.
+     *
+     * @remarks
+     * Useful when the same task description is reused across multiple
+     * working directories.
+     *
+     * @defaultValue undefined
+     */
+    cwd?: string;
+}
+/**
+ * One streaming event surfaced through {@link SubagentSpawnOptions.onStream}.
+ *
+ * @remarks
+ * Discriminated by {@link kind}:
+ *
+ * - `"message"` — a successfully parsed JSON line from the child's
+ *   stdout. {@link payload} is the parsed object and {@link lineNumber}
+ *   is the 1-based line index within the child's stdout stream.
+ * - `"stderr"` — a single line from the child's stderr stream. The
+ *   {@link payload} is `{ line: string }`. The harness NEVER injects
+ *   stderr into the parent LLM context per ADR-035 §D6.
+ * - `"exit"` — the child has exited. {@link payload} is a
+ *   {@link SubagentExitResult}.
+ * - `"link"` — the harness wrote a `subagent_link` custom entry to the
+ *   parent session. {@link payload} is the {@link SubagentLinkEntry}.
+ *
+ * @public
+ */
+interface SubagentStreamEvent {
+    /** Event kind discriminator. */
+    kind: 'message' | 'stderr' | 'exit' | 'link';
+    /** Subagent identifier (matches {@link SubagentHandle.subagentId}). */
+    subagentId: string;
+    /**
+     * 1-based line number within the child's stdout stream. Only set for
+     * `"message"` events that originated from a parsed stdout line.
+     * @defaultValue undefined
+     */
+    lineNumber?: number;
+    /** Event payload, shaped according to {@link kind}. */
+    payload: unknown;
+}
+/**
+ * Resolution value of {@link SubagentHandle.exitPromise}.
+ *
+ * @remarks
+ * Captured exactly once when the child process exits. The promise NEVER
+ * rejects — failure is encoded by a non-zero {@link code}, a non-null
+ * {@link signal}, or partial output preserved in the child session file
+ * at {@link childSessionPath}.
+ *
+ * @public
+ */
+interface SubagentExitResult {
+    /**
+     * Process exit code, or `null` when the child was terminated by a
+     * signal before exiting normally.
+     */
+    code: number | null;
+    /** Terminating signal, or `null` when the child exited normally. */
+    signal: NodeJS.Signals | null;
+    /** Absolute path to the child session JSONL file on disk. */
+    childSessionPath: string;
+    /** Wall-clock duration from spawn to exit, in milliseconds. */
+    durationMs: number;
+}
+/**
+ * Final result of a subagent's execution (legacy v1 shape).
  *
  * @remarks
- * Collected once the child process exits. {@link parsed} is populated
- * on a best-effort basis: if the subagent emits JSON on stdout the
- * harness will parse it, otherwise {@link parsed} is left undefined.
+ * Preserved for back-compat with pre-ADR-035 §D6 callers. New code
+ * SHOULD await {@link SubagentHandle.exitPromise} (which resolves with
+ * a richer {@link SubagentExitResult}) instead. The harness still
+ * populates this field on every spawn so existing tests and callers
+ * keep working.
  *
  * @public
  */
@@ -2110,18 +2205,87 @@ interface SubagentResult {
  *
  * @remarks
  * Returned synchronously from {@link Harness.spawnSubagent}. The caller
- * may await {@link result} to collect the final output, or invoke
- * {@link abort} to terminate the child early.
+ * may:
+ *
+ * - Await {@link exitPromise} to collect the rich {@link SubagentExitResult}
+ *   (preferred path, ADR-035 §D6).
+ * - Await {@link result} to collect the legacy {@link SubagentResult}
+ *   (preserved for back-compat).
+ * - Invoke {@link terminate} (preferred) or {@link abort} (legacy) to
+ *   stop the child early via the configured SIGTERM-then-SIGKILL
+ *   cleanup sequence.
+ * - Inspect {@link recentStderr} for the most recent stderr lines
+ *   captured by the harness — useful for post-mortem diagnostics
+ *   without injecting stderr into the parent LLM context.
  *
  * @public
  */
 interface SubagentHandle {
+    /**
+     * Stable subagent identifier generated at spawn time.
+     *
+     * @remarks
+     * Format: `sub-{taskId}-{shortRandom}`. Used to correlate
+     * {@link SubagentStreamEvent} entries and `subagent_link` records
+     * with this handle. Always defined (the harness never returns a
+     * handle without one).
+     */
+    subagentId: string;
+    /** Task identifier from {@link SubagentTask.taskId} (or generated default). */
+    taskId: string;
+    /** Absolute path to the child session JSONL file on disk. */
+    childSessionPath: string;
     /** PID of the spawned process, or `null` if spawning did not yield one. */
     pid: number | null;
-    /** Promise resolving to the subagent's final output once the process exits. */
+    /** Wall-clock timestamp captured immediately after spawn. */
+    startedAt: Date;
+    /**
+     * Promise resolving to the rich exit result once the child process
+     * has fully terminated. NEVER rejects — failures are encoded in the
+     * resolved value (non-zero code, non-null signal, partial output in
+     * the session file).
+     */
+    exitPromise: Promise<SubagentExitResult>;
+    /**
+     * Promise resolving to the legacy {@link SubagentResult} shape.
+     *
+     * @remarks
+     * Preserved for back-compat. Resolves to the same exit code as
+     * {@link exitPromise} plus the full captured stdout / stderr buffers
+     * and a best-effort `parsed` field for callers that emit a single
+     * JSON document.
+     */
     result: Promise<SubagentResult>;
-    /** Synchronously terminate the subagent. Safe to call after exit. */
+    /**
+     * Terminate the subagent gracefully.
+     *
+     * @remarks
+     * Sends SIGTERM, waits for the configured grace window, then sends
+     * SIGKILL if the child is still alive. Idempotent — subsequent calls
+     * after the first are no-ops. Returns once the cleanup sequence has
+     * fully resolved.
+     */
+    terminate(): Promise<void>;
+    /**
+     * Synchronously trigger the cleanup sequence (legacy v1 alias for
+     * {@link terminate}).
+     *
+     * @remarks
+     * Preserved so existing callers that use `handle.abort()` keep
+     * working. Internally enqueues the same SIGTERM-then-SIGKILL flow as
+     * {@link terminate} but does not return the resulting promise.
+     */
     abort: () => void;
+    /**
+     * Snapshot of the most recent stderr lines captured for this child.
+     *
+     * @remarks
+     * Bounded ring buffer (last 100 lines) so memory cannot grow without
+     * bound under chatty stderr. Stderr is NEVER injected into the
+     * parent LLM context — this accessor is intended for diagnostics and
+     * post-mortem inspection only.
+     */
+    recentStderr(): string[];
 }
 /**
  * Contract every first-class harness must implement.
@@ -2209,16 +2373,25 @@ interface Harness {
      * @remarks
      * For Pi: invokes `child_process.spawn` with the provider's configured
      * `capabilities.spawn.spawnCommand`, appending the task prompt as a
-     * trailing positional argument. The returned handle lets the caller await
-     * completion or abort early.
+     * trailing positional argument. The returned handle lets the caller
+     * await completion ({@link SubagentHandle.exitPromise}), terminate the
+     * child via the SIGTERM-then-SIGKILL cleanup sequence
+     * ({@link SubagentHandle.terminate}), and inspect recent stderr for
+     * post-mortem diagnostics ({@link SubagentHandle.recentStderr}).
+     *
+     * Per ADR-035 §D6, this is the **only** canonical subagent spawn path
+     * in CLEO. New callers MUST go through the harness instead of calling
+     * `child_process.spawn` directly so session attribution, streaming,
+     * and cleanup remain uniform.
      *
      * Optional — harnesses that cannot spawn other agents should omit this
      * method. Callers MUST feature-check before invoking.
      *
      * @param task - Subagent task specification.
+     * @param opts - Per-call streaming and cleanup overrides.
      * @returns A live subagent handle.
      */
-    spawnSubagent?(task: SubagentTask): Promise<SubagentHandle>;
+    spawnSubagent?(task: SubagentTask, opts?: SubagentSpawnOptions): Promise<SubagentHandle>;
     /**
      * Configure which models are available in the harness's model picker.
      *
@@ -2392,7 +2565,497 @@ interface Harness {
     listThemes?(projectDir?: string): Promise<ThemeEntry[]>;
     /** Remove a Pi theme by name from the given tier. */
     removeTheme?(name: string, tier: HarnessTier, projectDir?: string): Promise<boolean>;
+    /**
+     * Install a CANT profile (`.cant` file) into the given tier.
+     *
+     * @remarks
+     * Per ADR-035 §D5 (CANT single engine), CANT profiles are first-class
+     * Pi assets consumed by the canonical `cant-bridge.ts` extension via
+     * `/cant:load <file>` at runtime. This verb copies a source `.cant`
+     * file into the requested tier so the bridge can discover it.
+     *
+     * Implementations MUST validate the source via cant-core's 42-rule
+     * engine before copying — invalid `.cant` files are rejected. The
+     * conflict-on-write rule from §D1 cross-cutting concerns applies:
+     * existing targets cause an error unless `opts.force` is set.
+     *
+     * Optional on the interface because only first-class harnesses with a
+     * native CANT bridge support this verb.
+     *
+     * @param sourcePath - Absolute path to the source `.cant` file on disk.
+     * @param name - Profile name (used as the target file basename).
+     * @param tier - Target tier (`project`/`user`/`global`).
+     * @param projectDir - Project directory (required when `tier='project'`).
+     * @param opts - Install options (see {@link HarnessInstallOptions}).
+     */
+    installCantProfile?(sourcePath: string, name: string, tier: HarnessTier, projectDir?: string, opts?: HarnessInstallOptions): Promise<{
+        targetPath: string;
+        tier: HarnessTier;
+        counts: CantProfileCounts;
+    }>;
+    /**
+     * Remove a CANT profile by name from the given tier.
+     *
+     * @remarks
+     * Missing files are tolerated silently so the verb is usable as an
+     * idempotent "ensure absent" operation.
+     *
+     * @param name - Profile name (basename without `.cant`).
+     * @param tier - Target tier to remove from.
+     * @param projectDir - Project directory (required when `tier='project'`).
+     * @returns `true` when a file was removed, `false` when none existed.
+     */
+    removeCantProfile?(name: string, tier: HarnessTier, projectDir?: string): Promise<boolean>;
+    /**
+     * List CANT profiles across all tiers, precedence-ordered.
+     *
+     * @remarks
+     * Walks every tier in {@link HarnessTier} precedence order
+     * (project → user → global) and parses each `.cant` file to extract
+     * its section counts. Higher-precedence tiers shadow lower-precedence
+     * entries with the same name; the {@link CantProfileEntry.shadowedByHigherTier}
+     * flag indicates shadowed copies so callers can warn about
+     * cross-tier name collisions per ADR-035 §D1.
+     *
+     * @param projectDir - Project directory for the `project` tier. When
+     *   omitted the `project` tier is skipped rather than failing.
+     */
+    listCantProfiles?(projectDir?: string): Promise<CantProfileEntry[]>;
+    /**
+     * Validate a `.cant` file via cant-core's 42-rule engine without
+     * installing anything.
+     *
+     * @remarks
+     * Pure helper used by `caamp pi cant validate <path>`. Reads the file,
+     * parses it, runs the validator, and returns a structured
+     * {@link ValidateCantProfileResult}. Never mutates state on disk.
+     *
+     * @param sourcePath - Absolute path to the `.cant` file on disk.
+     */
+    validateCantProfile?(sourcePath: string): Promise<ValidateCantProfileResult>;
+}
+
+/**
+ * CAAMP-wide configuration accessors.
+ *
+ * @remarks
+ * This module is the single source of truth for CAAMP configuration values
+ * that affect runtime behaviour across the package. Today it carries one
+ * setting — {@link ExclusivityMode} — introduced by ADR-035 §D7 to control
+ * how `resolveDefaultTargetProviders()` selects target providers at runtime
+ * invocation time.
+ *
+ * The accessor pattern intentionally uses a layered resolution order so the
+ * setting can be overridden by tests, by environment variables in CI, and by
+ * future programmatic callers (e.g. a `caamp config set` subcommand) without
+ * any of those layers needing to know about the others:
+ *
+ * 1. Programmatic override via {@link setExclusivityMode} (highest priority).
+ * 2. Environment variable `CAAMP_EXCLUSIVITY_MODE`.
+ * 3. Default value `'auto'`.
+ *
+ * The programmatic override exists primarily for tests and for future
+ * `caamp config set` integration; production code should prefer the
+ * environment variable when wiring CI or shell sessions.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Default exclusivity mode used when no override is configured.
+ *
+ * @remarks
+ * `auto` mirrors the v2026.4.5+ behaviour: Pi is preferred when installed,
+ * but explicit non-Pi targets remain functional. This is the value the
+ * accessor returns when neither {@link setExclusivityMode} nor the
+ * `CAAMP_EXCLUSIVITY_MODE` environment variable is set.
+ *
+ * @public
+ */
+declare const DEFAULT_EXCLUSIVITY_MODE: ExclusivityMode;
+/**
+ * Environment variable name read by {@link getExclusivityMode} when no
+ * programmatic override is active.
+ *
+ * @remarks
+ * Exported as a constant so tests and downstream tooling can refer to the
+ * canonical name without typo risk. The variable accepts the same three
+ * literal values as the {@link ExclusivityMode} type.
+ *
+ * @public
+ */
+declare const EXCLUSIVITY_MODE_ENV_VAR = "CAAMP_EXCLUSIVITY_MODE";
+/**
+ * Error raised when {@link getExclusivityMode} resolves to `'force-pi'` but
+ * Pi is not installed at the moment a runtime dispatch is requested.
+ *
+ * @remarks
+ * Carries an `E_NOT_FOUND_RESOURCE`-shaped `code` so command-layer error
+ * envelopes (LAFS) can map it to a stable category. Callers decide whether
+ * to surface this as a process exit (typically code 4) or as a structured
+ * envelope; the harness layer never calls `process.exit` itself.
+ *
+ * Lives next to the configuration accessor rather than in the harness
+ * dispatcher so consumers that import the mode also pick up the matching
+ * error type without a second module hop.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const targets = resolveDefaultTargetProviders();
+ * } catch (err) {
+ *   if (err instanceof PiRequiredError) {
+ *     process.exit(4);
+ *   }
+ *   throw err;
+ * }
+ * ```
+ *
+ * @public
+ */
+declare class PiRequiredError extends Error {
+    /** LAFS-stable error code identifying this failure mode. */
+    readonly 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?: string);
+}
+/**
+ * Type guard that narrows an arbitrary string to {@link ExclusivityMode}.
+ *
+ * @remarks
+ * Used both internally and by callers that need to validate untrusted input
+ * (e.g. CLI flag parsers, env var readers) before passing it through to
+ * {@link setExclusivityMode}.
+ *
+ * @param value - Candidate value to validate.
+ * @returns `true` when `value` is one of `'auto'`, `'force-pi'`, `'legacy'`.
+ *
+ * @example
+ * ```typescript
+ * if (isExclusivityMode(userInput)) {
+ *   setExclusivityMode(userInput);
+ * }
+ * ```
+ *
+ * @public
+ */
+declare function isExclusivityMode(value: string): value is ExclusivityMode;
+/**
+ * Resolve the active CAAMP exclusivity mode using the layered precedence
+ * documented in {@link DEFAULT_EXCLUSIVITY_MODE}.
+ *
+ * @remarks
+ * Resolution order:
+ *
+ * 1. Programmatic override (set via {@link setExclusivityMode}).
+ * 2. Environment variable `CAAMP_EXCLUSIVITY_MODE`.
+ * 3. {@link DEFAULT_EXCLUSIVITY_MODE} (`'auto'`).
+ *
+ * Invalid environment variable values are silently ignored (resolution
+ * falls through to the default) so a typo in CI does not crash the CLI.
+ * The value is never cached — every call re-reads the environment so tests
+ * that mutate `process.env` see consistent results without needing to
+ * reset module state.
+ *
+ * @returns The currently effective exclusivity mode.
+ *
+ * @example
+ * ```typescript
+ * const mode = getExclusivityMode();
+ * if (mode === 'force-pi') {
+ *   // ...
+ * }
+ * ```
+ *
+ * @public
+ */
+declare function getExclusivityMode(): ExclusivityMode;
+/**
+ * Install a programmatic override for the exclusivity mode.
+ *
+ * @remarks
+ * The override takes precedence over the environment variable for the
+ * remainder of the process or until {@link resetExclusivityModeOverride}
+ * is called. Intended for tests, for future `caamp config set` wiring, and
+ * for short-lived runtime adjustments (e.g. a one-shot CLI flag).
+ *
+ * @param mode - Mode to install.
+ *
+ * @example
+ * ```typescript
+ * setExclusivityMode('force-pi');
+ * try {
+ *   await runCommand();
+ * } finally {
+ *   resetExclusivityModeOverride();
+ * }
+ * ```
+ *
+ * @public
+ */
+declare function setExclusivityMode(mode: ExclusivityMode): void;
+/**
+ * Clear any programmatic override installed by {@link setExclusivityMode}.
+ *
+ * @remarks
+ * After calling this, {@link getExclusivityMode} resumes reading from the
+ * environment variable (and falls back to the default when the env var is
+ * unset or invalid). Idempotent — safe to call when no override is active.
+ *
+ * @public
+ */
+declare function resetExclusivityModeOverride(): void;
+
+/**
+ * Format utility functions
+ */
+/**
+ * Deep merge two objects, with `source` values winning on conflict.
+ *
+ * Recursively merges nested plain objects. Arrays and non-object values from
+ * `source` overwrite `target` values.
+ *
+ * @param target - Base object to merge into
+ * @param source - Object with values that take precedence
+ * @returns A new merged object (does not mutate inputs)
+ *
+ * @remarks
+ * Only plain objects are recursively merged. Arrays and primitive values from
+ * `source` replace `target` values outright. Neither input is mutated.
+ *
+ * @example
+ * ```typescript
+ * const merged = deepMerge({ a: 1, b: { c: 2 } }, { b: { d: 3 } });
+ * // { a: 1, b: { c: 2, d: 3 } }
+ * ```
+ *
+ * @public
+ */
+declare function deepMerge(target: Record<string, unknown>, source: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Get a nested value from an object using a dot-notation key path.
+ *
+ * @param obj - Object to traverse
+ * @param keyPath - Dot-separated key path (e.g. `"mcpServers"` or `"a.b.c"`)
+ * @returns The value at the key path, or `undefined` if not found
+ *
+ * @remarks
+ * Splits the key path on `.` and walks the object tree. Returns `undefined`
+ * at the first missing or non-object segment.
+ *
+ * @example
+ * ```typescript
+ * getNestedValue({ a: { b: { c: 42 } } }, "a.b.c"); // 42
+ * getNestedValue({ a: 1 }, "a.b"); // undefined
+ * ```
+ *
+ * @public
+ */
+declare function getNestedValue(obj: Record<string, unknown>, keyPath: string): unknown;
+/**
+ * Ensure that the parent directories of a file path exist.
+ *
+ * Creates directories recursively if they do not exist.
+ *
+ * @param filePath - Absolute path to a file (parent directories will be created)
+ *
+ * @remarks
+ * Uses `mkdir` with `recursive: true` so existing directories are not an error.
+ *
+ * @example
+ * ```typescript
+ * await ensureDir("/path/to/new/dir/file.json");
+ * // /path/to/new/dir/ now exists
+ * ```
+ *
+ * @public
+ */
+declare function ensureDir(filePath: string): Promise<void>;
+
+/**
+ * Provides format-agnostic config read, write, and remove operations that
+ * dispatch to JSON/JSONC, YAML, or TOML handlers based on the specified
+ * format.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Read and parse a config file in the specified format.
+ *
+ * Dispatches to the appropriate format handler (JSON/JSONC, YAML, or TOML).
+ *
+ * @param filePath - Absolute path to the config file
+ * @param format - Config file format
+ * @returns Parsed config object
+ * @throws If the file cannot be read or the format is unsupported
+ *
+ * @remarks
+ * Supported formats: `"json"`, `"jsonc"`, `"yaml"`, `"toml"`. Throws for
+ * any unrecognized format string.
+ *
+ * @example
+ * ```typescript
+ * const config = await readConfig("/path/to/config.json", "jsonc");
+ * ```
+ *
+ * @public
+ */
+declare function readConfig(filePath: string, format: ConfigFormat): Promise<Record<string, unknown>>;
+/**
+ * Write a server entry to a config file, preserving existing content.
+ *
+ * Dispatches to the appropriate format handler. For JSONC files, comments are
+ * preserved using `jsonc-parser`.
+ *
+ * @param filePath - Absolute path to the config file
+ * @param format - Config file format
+ * @param key - Dot-notation key path to the servers section (e.g. `"mcpServers"`)
+ * @param serverName - Name/key for the server entry
+ * @param serverConfig - Server configuration object to write
+ * @throws If the format is unsupported
+ *
+ * @remarks
+ * For JSONC files, comments and formatting are preserved using `jsonc-parser`.
+ * For YAML and TOML, the file is fully re-serialized after deep-merging.
+ *
+ * @example
+ * ```typescript
+ * await writeConfig("/path/to/config.json", "jsonc", "mcpServers", "my-server", config);
+ * ```
+ *
+ * @public
+ */
+declare function writeConfig(filePath: string, format: ConfigFormat, key: string, serverName: string, serverConfig: unknown): Promise<void>;
+/**
+ * Remove a server entry from a config file in the specified format.
+ *
+ * @param filePath - Absolute path to the config file
+ * @param format - Config file format
+ * @param key - Dot-notation key path to the servers section
+ * @param serverName - Name/key of the server entry to remove
+ * @returns `true` if the entry was removed, `false` otherwise
+ * @throws If the format is unsupported
+ *
+ * @remarks
+ * Delegates to the format-specific removal function. Returns `false` when the
+ * file does not exist or the entry is not found.
+ *
+ * @example
+ * ```typescript
+ * const removed = await removeConfig("/path/to/config.json", "jsonc", "mcpServers", "my-server");
+ * ```
+ *
+ * @public
+ */
+declare function removeConfig(filePath: string, format: ConfigFormat, key: string, serverName: string): Promise<boolean>;
+
+/**
+ * Skill installer - canonical + symlink model
+ *
+ * Skills are stored once in a canonical location (.agents/skills/<name>/)
+ * and symlinked to each target agent's skills directory.
+ */
+
+/**
+ * Result of installing a skill to the canonical location and linking to agents.
+ *
+ * @example
+ * ```typescript
+ * const result = await installSkill(sourcePath, "my-skill", providers, true);
+ * if (result.success) {
+ *   console.log(`Installed to ${result.canonicalPath}`);
+ *   console.log(`Linked to: ${result.linkedAgents.join(", ")}`);
+ * }
+ * ```
+ *
+ * @public
+ */
+interface SkillInstallResult {
+    /** Skill name. */
+    name: string;
+    /** Absolute path to the canonical installation directory. */
+    canonicalPath: string;
+    /** Provider IDs that were successfully linked. */
+    linkedAgents: string[];
+    /** Error messages from failed link operations. */
+    errors: string[];
+    /** Whether at least one agent was successfully linked. */
+    success: boolean;
 }
+/**
+ * Install a skill from a local path to the canonical location and link to agents.
+ *
+ * @remarks
+ * Copies the skill directory to the canonical skills directory and creates symlinks
+ * (or copies on Windows) from each provider's skills directory to the canonical path.
+ *
+ * @param sourcePath - Local path to the skill directory to install
+ * @param skillName - Name for the installed skill
+ * @param providers - Target providers to link the skill to
+ * @param isGlobal - Whether to link to global or project skill directories
+ * @param projectDir - Project directory (defaults to `process.cwd()`)
+ * @returns Install result with linked agents and any errors
+ *
+ * @example
+ * ```typescript
+ * const result = await installSkill("/tmp/my-skill", "my-skill", providers, true, "/my/project");
+ * if (result.success) {
+ *   console.log(`Linked to: ${result.linkedAgents.join(", ")}`);
+ * }
+ * ```
+ *
+ * @public
+ */
+declare function installSkill(sourcePath: string, skillName: string, providers: Provider[], isGlobal: boolean, projectDir?: string): Promise<SkillInstallResult>;
+/**
+ * Remove a skill from the canonical location and all agent symlinks.
+ *
+ * @remarks
+ * Removes symlinks from each provider's skills directory and then removes the
+ * canonical copy from the centralized canonical skills directory.
+ *
+ * @param skillName - Name of the skill to remove
+ * @param providers - Providers to unlink the skill from
+ * @param isGlobal - Whether to target global or project skill directories
+ * @param projectDir - Project directory (defaults to `process.cwd()`)
+ * @returns Object with arrays of successfully removed provider IDs and error messages
+ *
+ * @example
+ * ```typescript
+ * const { removed, errors } = await removeSkill("my-skill", providers, true, "/my/project");
+ * console.log(`Removed from: ${removed.join(", ")}`);
+ * ```
+ *
+ * @public
+ */
+declare function removeSkill(skillName: string, providers: Provider[], isGlobal: boolean, projectDir?: string): Promise<{
+    removed: string[];
+    errors: string[];
+}>;
+/**
+ * List all skills installed in the canonical skills directory.
+ *
+ * @remarks
+ * Returns the directory names of all skills, which correspond to skill names.
+ * Includes both regular directories and symlinks in the canonical location.
+ *
+ * @returns Array of skill names
+ *
+ * @example
+ * ```typescript
+ * const skills = await listCanonicalSkills();
+ * // ["my-skill", "another-skill"]
+ * ```
+ *
+ * @public
+ */
+declare function listCanonicalSkills(): Promise<string[]>;
 
 /**
  * Pi coding agent harness.
@@ -2470,19 +3133,118 @@ declare class PiHarness implements Harness {
     /** {@inheritDoc Harness.removeInstructions} */
     removeInstructions(scope: HarnessScope): Promise<void>;
     /**
-     * {@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
+     * 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.
+     *
+     * **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.
+     */
+    spawnSubagent(task: SubagentTask, opts?: SubagentSpawnOptions): Promise<SubagentHandle>;
+    /**
+     * 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 raceSubagents(handles: SubagentHandle[]): Promise<SubagentExitResult>;
+    /**
+     * Settle a set of subagent handles, returning a parallel array of
+     * results.
      *
      * @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.
+     * 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 settleAllSubagents(handles: SubagentHandle[]): Promise<PromiseSettledResult<SubagentExitResult>[]>;
+    /**
+     * Per-line stdout dispatcher used by the streaming buffer flusher.
      *
-     * Throws immediately when the provider entry is missing a `spawnCommand`
-     * so callers see configuration errors early rather than at child-exit time.
+     * @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).
      */
-    spawnSubagent(task: SubagentTask): Promise<SubagentHandle>;
+    private handleStdoutLine;
     /** {@inheritDoc Harness.readSettings} */
     readSettings(scope: HarnessScope): Promise<unknown>;
     /** {@inheritDoc Harness.writeSettings} */
@@ -2543,6 +3305,47 @@ declare class PiHarness implements Harness {
     listThemes(projectDir?: string): Promise<ThemeEntry[]>;
     /** {@inheritDoc Harness.removeTheme} */
     removeTheme(name: string, tier: HarnessTier, projectDir?: string): Promise<boolean>;
+    /**
+     * {@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.
+     */
+    installCantProfile(sourcePath: string, name: string, tier: HarnessTier, projectDir?: string, opts?: HarnessInstallOptions): Promise<{
+        targetPath: string;
+        tier: HarnessTier;
+        counts: CantProfileCounts;
+    }>;
+    /** {@inheritDoc Harness.removeCantProfile} */
+    removeCantProfile(name: string, tier: HarnessTier, projectDir?: string): Promise<boolean>;
+    /**
+     * {@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.
+     */
+    listCantProfiles(projectDir?: string): Promise<CantProfileEntry[]>;
+    /**
+     * {@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.
+     */
+    validateCantProfile(sourcePath: string): Promise<ValidateCantProfileResult>;
 }
 
 /**
@@ -2624,42 +3427,52 @@ declare function getPrimaryHarness(): Harness | null;
 declare function getAllHarnesses(): Harness[];
 /**
  * Resolve the default set of target providers when the user has not passed
- * `--agent`.
+ * `--agent`, honouring the active {@link ExclusivityMode}.
  *
  * @remarks
- * Resolution policy:
+ * Resolution policy is layered. The active {@link ExclusivityMode} (read
+ * via {@link getExclusivityMode}) selects which branch of the matrix runs:
  *
- * 1. If the registry's primary harness (the provider with
- *    `priority === "primary"`) is installed on the current system,
- *    return `[primaryProvider]` so that commands dispatch to the
- *    primary harness by default.
- * 2. Otherwise, return the set of installed providers at priority
- *    `"primary"` or `"high"`. This restores the legacy "detected high-tier
- *    providers" fallback that CAAMP has always used when no primary
- *    harness is available.
- * 3. If the priority filter yields an empty list (e.g. in tests that stub
- *    providers without a `priority` field, or in fresh installs with only
- *    medium/low-tier providers detected), fall back to the full installed
- *    provider list so that commands retain a valid target.
+ * | Mode | Pi installed | Pi absent |
+ * |---|---|---|
+ * | `'auto'` (default) | Returns `[piProvider]`. Explicit non-Pi targets emit a one-time deprecation warning per process. | Falls back to installed primary/high-tier providers (legacy v2026.4.5 behaviour) and emits a one-time boot warning. |
+ * | `'force-pi'` | Returns `[piProvider]`. | Throws {@link PiRequiredError}. |
+ * | `'legacy'` | Returns the full installed provider list in priority order (matches pre-exclusivity behaviour). | Same. |
  *
- * This helper is intentionally defensive: it swallows registry-related
- * exceptions (returning an empty-primary-harness result) so stubbed test
- * environments that do not wire the full provider registry still behave
- * sensibly.
+ * **Install paths are unaffected.** Per ADR-035 §D7, this helper governs
+ * RUNTIME INVOCATION dispatch only. Skill and instruction install
+ * dispatchers ({@link dispatchInstallSkillAcrossProviders},
+ * {@link dispatchRemoveSkillAcrossProviders}) intentionally do not call
+ * this function — they target every requested provider directly so that
+ * users in `force-pi` mode can still `caamp skills install foo --agent
+ * claude-code` while Pi is being installed.
  *
+ * The helper is intentionally defensive: registry/detection exceptions
+ * are caught and treated as "Pi unknown" so stubbed test environments
+ * that do not wire the full registry still behave sensibly.
+ *
+ * @param options - Optional explicit provider selection (e.g. from
+ *   `--agent`) used by `auto`-mode deprecation warning detection. Omit to
+ *   request the implicit default resolution.
  * @returns Ordered list of providers to target by default.
+ * @throws {@link PiRequiredError} when mode is `'force-pi'` and Pi is not
+ *   installed.
  *
  * @example
  * ```typescript
+ * // Implicit default — used by `caamp skills list` and friends.
  * const targets = resolveDefaultTargetProviders();
- * if (targets.length === 0) {
- *   console.error("No target providers found. Use --agent or --all.");
- * }
+ *
+ * // Explicit user selection — emits a deprecation warning in `auto` mode
+ * // when the selection excludes Pi and Pi is installed.
+ * const explicit = resolveDefaultTargetProviders({
+ *   explicit: [getProvider('claude-code')!],
+ * });
  * ```
  *
  * @public
  */
-declare function resolveDefaultTargetProviders(): Provider[];
+declare function resolveDefaultTargetProviders(options?: ResolveDefaultTargetProvidersOptions): Provider[];
 
 /**
  * All hook event categories (8 total).
@@ -7099,4 +7912,4 @@ declare function parseSource(input: string): ParsedSource;
  */
 declare function isMarketplaceScoped(input: string): boolean;
 
-export { type AuditFinding, type AuditResult, type AuditRule, type AuditSeverity, type BatchInstallOptions, type BatchInstallResult, CANONICAL_HOOK_EVENTS, type CaampLockFile, type CanonicalEventDefinition, type CanonicalHookEvent, type ConfigFormat, type CrossProviderMatrix, type CtDispatchMatrix, type CtManifest, type CtManifestSkill, type CtProfileDefinition, type CtSkillEntry, type CtValidationIssue, type CtValidationResult, type DetectionCacheOptions, type DetectionResult, type EnsureProviderInstructionFileOptions, type EnsureProviderInstructionFileResult, type GlobalOptions, HOOK_CATEGORIES, type Harness, type HarnessScope, type HookCategory, type HookEvent, type HookHandlerType, type HookMapping, type HookSupportResult, type HookSystemType, type InjectionCheckResult, type InjectionStatus, type InjectionTemplate, type InstallMcpServerOptions, type InstallMcpServerResult, type InstructionUpdateSummary, type LockEntry, MarketplaceClient, type MarketplaceResult, type MarketplaceSearchResult, type MarketplaceSkill, type McpConfigFormat, type McpDetectionEntry, type McpScope, type McpServerConfig, type McpServerEntriesByProvider, type McpServerEntry, type McpTransportType, type NormalizedHookEvent, type NormalizedRecommendationCriteria, type ParsedSource, PiHarness, type PlatformPaths, type Provider, type ProviderCapabilities, type ProviderHarnessCapability, type ProviderHookProfile, type ProviderHookSummary, type ProviderHooksCapability, type ProviderMcpCapability, type ProviderPriority, type ProviderSkillsCapability, type ProviderSpawnCapability, type ProviderStatus, RECOMMENDATION_ERROR_CODES, type RankedSkillRecommendation, type RecommendSkillsResult, type RecommendationCriteriaInput, type RecommendationErrorCode, type RecommendationOptions, type RecommendationReason, type RecommendationReasonCode, type RecommendationScoreBreakdown, type RecommendationValidationIssue, type RecommendationValidationResult, type RecommendationWeights, type RegistryHarnessKind, type RegistryHookCatalog, type RegistryHookFormat, type RemoveMcpServerOptions, type RemoveMcpServerResult, type SkillBatchOperation, type SkillEntry, type SkillInstallResult, type SkillIntegrityResult, type SkillIntegrityStatus, type SkillLibrary, type SkillLibraryDispatchMatrix, type SkillLibraryEntry, type SkillLibraryManifest, type SkillLibraryManifestSkill, type SkillLibraryProfile, type SkillLibraryValidationIssue, type SkillLibraryValidationResult, type SkillMetadata, type SkillsPrecedence, type SourceType, type SpawnAdapter, type SpawnMechanism, type SpawnOptions, type SpawnResult, type SubagentHandle, type SubagentResult, type SubagentTask, type SystemInfo, type TransportType, type ValidationIssue, type ValidationResult, _resetPlatformPathsCache, buildHookMatrix, buildInjectionContent, buildLibraryFromFiles, buildSkillsMap, catalog, checkAllInjections, checkAllSkillIntegrity, checkAllSkillUpdates, checkInjection, checkSkillIntegrity, checkSkillUpdate, clearRegisteredLibrary, deepMerge, detectAllProviders, detectMcpInstallations, detectProjectProviders, detectProvider, discoverSkill, discoverSkills, ensureAllProviderInstructionFiles, ensureDir, ensureProviderInstructionFile, formatSkillRecommendations, generateInjectionContent, generateSkillsSection, getAgentsConfigPath, getAgentsHome, getAgentsInstructFile, getAgentsLinksDir, getAgentsMcpDir, getAgentsMcpServersPath, getAgentsSpecDir, getAgentsWikiDir, getAllCanonicalEvents, getAllHarnesses, getAllProviders, getCanonicalEvent, getCanonicalEventsByCategory, getCanonicalSkillsDir, getCommonEvents, getCommonHookEvents, getEffectiveSkillsPaths, getHarnessFor, getHookConfigPath, getHookMappingsVersion, getHookSupport, getHookSystemType, getInstalledProviders, getInstructionFiles, getLockFilePath, getMappedProviderIds, getNestedValue, getPlatformLocations, getPlatformPaths, getPrimaryHarness, getPrimaryProvider, getProjectAgentsDir, getProvider, getProviderCapabilities, getProviderCount, getProviderHookProfile, getProviderOnlyEvents, getProviderSummary, getProvidersByHookEvent, getProvidersByInstructFile, getProvidersByPriority, getProvidersBySkillsPrecedence, getProvidersBySpawnCapability, getProvidersByStatus, getProvidersForEvent, getRegistryVersion, getSpawnCapableProviders, getSupportedEvents, getSystemInfo, getTrackedSkills, getUnsupportedEvents, groupByInstructFile, inject, injectAll, installBatchWithRollback, installMcpServer, installSkill, isCaampOwnedSkill, isMarketplaceScoped, isQuiet, isVerbose, listAllMcpServers, listCanonicalSkills, listMcpServers, loadLibraryFromModule, normalizeRecommendationCriteria, parseInjectionContent, parseSkillFile, parseSource, providerSupports, providerSupportsById, rankSkills, readConfig, recommendSkills, recordSkillInstall, registerSkillLibrary, registerSkillLibraryFromPath, removeConfig, removeInjection, removeMcpServer, removeMcpServerFromAll, removeSkill, removeSkillFromLock, resetDetectionCache, resolveAlias, resolveDefaultTargetProviders, resolveMcpConfigPath, resolveNativeEvent, resolveProviderSkillsDirs, resolveRegistryTemplatePath, scanDirectory, scanFile, scoreSkillRecommendation, searchSkills, selectProvidersByMinimumPriority, setQuiet, setVerbose, shouldOverrideSkill, supportsHook, toCanonical, toNative, toNativeBatch, toSarif, tokenizeCriteriaValue, translateToAll, updateInstructionsSingleOperation, validateInstructionIntegrity, validateRecommendationCriteria, validateSkill, writeConfig };
+export { type AuditFinding, type AuditResult, type AuditRule, type AuditSeverity, type BatchInstallOptions, type BatchInstallResult, CANONICAL_HOOK_EVENTS, type CaampLockFile, type CanonicalEventDefinition, type CanonicalHookEvent, type CantProfileCounts, type CantProfileEntry, type CantValidationDiagnostic, type ConfigFormat, type CrossProviderMatrix, type CtDispatchMatrix, type CtManifest, type CtManifestSkill, type CtProfileDefinition, type CtSkillEntry, type CtValidationIssue, type CtValidationResult, DEFAULT_EXCLUSIVITY_MODE, type DetectionCacheOptions, type DetectionResult, EXCLUSIVITY_MODE_ENV_VAR, type EnsureProviderInstructionFileOptions, type EnsureProviderInstructionFileResult, type ExclusivityMode, type GlobalOptions, HOOK_CATEGORIES, type Harness, type HarnessScope, type HookCategory, type HookEvent, type HookHandlerType, type HookMapping, type HookSupportResult, type HookSystemType, type InjectionCheckResult, type InjectionStatus, type InjectionTemplate, type InstallMcpServerOptions, type InstallMcpServerResult, type InstructionUpdateSummary, type LockEntry, MarketplaceClient, type MarketplaceResult, type MarketplaceSearchResult, type MarketplaceSkill, type McpConfigFormat, type McpDetectionEntry, type McpScope, type McpServerConfig, type McpServerEntriesByProvider, type McpServerEntry, type McpTransportType, type NormalizedHookEvent, type NormalizedRecommendationCriteria, type ParsedSource, PiHarness, PiRequiredError, type PlatformPaths, type Provider, type ProviderCapabilities, type ProviderHarnessCapability, type ProviderHookProfile, type ProviderHookSummary, type ProviderHooksCapability, type ProviderMcpCapability, type ProviderPriority, type ProviderSkillsCapability, type ProviderSpawnCapability, type ProviderStatus, RECOMMENDATION_ERROR_CODES, type RankedSkillRecommendation, type RecommendSkillsResult, type RecommendationCriteriaInput, type RecommendationErrorCode, type RecommendationOptions, type RecommendationReason, type RecommendationReasonCode, type RecommendationScoreBreakdown, type RecommendationValidationIssue, type RecommendationValidationResult, type RecommendationWeights, type RegistryHarnessKind, type RegistryHookCatalog, type RegistryHookFormat, type RemoveMcpServerOptions, type RemoveMcpServerResult, type ResolveDefaultTargetProvidersOptions, type SkillBatchOperation, type SkillEntry, type SkillInstallResult, type SkillIntegrityResult, type SkillIntegrityStatus, type SkillLibrary, type SkillLibraryDispatchMatrix, type SkillLibraryEntry, type SkillLibraryManifest, type SkillLibraryManifestSkill, type SkillLibraryProfile, type SkillLibraryValidationIssue, type SkillLibraryValidationResult, type SkillMetadata, type SkillsPrecedence, type SourceType, type SpawnAdapter, type SpawnMechanism, type SpawnOptions, type SpawnResult, type SubagentHandle, type SubagentResult, type SubagentTask, type SystemInfo, type TransportType, type ValidateCantProfileResult, type ValidationIssue, type ValidationResult, _resetPlatformPathsCache, buildHookMatrix, buildInjectionContent, buildLibraryFromFiles, buildSkillsMap, catalog, checkAllInjections, checkAllSkillIntegrity, checkAllSkillUpdates, checkInjection, checkSkillIntegrity, checkSkillUpdate, clearRegisteredLibrary, deepMerge, detectAllProviders, detectMcpInstallations, detectProjectProviders, detectProvider, discoverSkill, discoverSkills, ensureAllProviderInstructionFiles, ensureDir, ensureProviderInstructionFile, formatSkillRecommendations, generateInjectionContent, generateSkillsSection, getAgentsConfigPath, getAgentsHome, getAgentsInstructFile, getAgentsLinksDir, getAgentsMcpDir, getAgentsMcpServersPath, getAgentsSpecDir, getAgentsWikiDir, getAllCanonicalEvents, getAllHarnesses, getAllProviders, getCanonicalEvent, getCanonicalEventsByCategory, getCanonicalSkillsDir, getCommonEvents, getCommonHookEvents, getEffectiveSkillsPaths, getExclusivityMode, getHarnessFor, getHookConfigPath, getHookMappingsVersion, getHookSupport, getHookSystemType, getInstalledProviders, getInstructionFiles, getLockFilePath, getMappedProviderIds, getNestedValue, getPlatformLocations, getPlatformPaths, getPrimaryHarness, getPrimaryProvider, getProjectAgentsDir, getProvider, getProviderCapabilities, getProviderCount, getProviderHookProfile, getProviderOnlyEvents, getProviderSummary, getProvidersByHookEvent, getProvidersByInstructFile, getProvidersByPriority, getProvidersBySkillsPrecedence, getProvidersBySpawnCapability, getProvidersByStatus, getProvidersForEvent, getRegistryVersion, getSpawnCapableProviders, getSupportedEvents, getSystemInfo, getTrackedSkills, getUnsupportedEvents, groupByInstructFile, inject, injectAll, installBatchWithRollback, installMcpServer, installSkill, isCaampOwnedSkill, isExclusivityMode, isMarketplaceScoped, isQuiet, isVerbose, listAllMcpServers, listCanonicalSkills, listMcpServers, loadLibraryFromModule, normalizeRecommendationCriteria, parseInjectionContent, parseSkillFile, parseSource, providerSupports, providerSupportsById, rankSkills, readConfig, recommendSkills, recordSkillInstall, registerSkillLibrary, registerSkillLibraryFromPath, removeConfig, removeInjection, removeMcpServer, removeMcpServerFromAll, removeSkill, removeSkillFromLock, resetDetectionCache, resetExclusivityModeOverride, resolveAlias, resolveDefaultTargetProviders, resolveMcpConfigPath, resolveNativeEvent, resolveProviderSkillsDirs, resolveRegistryTemplatePath, scanDirectory, scanFile, scoreSkillRecommendation, searchSkills, selectProvidersByMinimumPriority, setExclusivityMode, setQuiet, setVerbose, shouldOverrideSkill, supportsHook, toCanonical, toNative, toNativeBatch, toSarif, tokenizeCriteriaValue, translateToAll, updateInstructionsSingleOperation, validateInstructionIntegrity, validateRecommendationCriteria, validateSkill, writeConfig };