@uluops/setup 0.7.0 → 0.9.0

package/README.md

@@ -19,18 +19,69 @@ npx @uluops/setup
 | Claude Code | Fully supported (default) | `claude` | `~/.claude.json` |
 | OpenCode | Fully supported | `oc` | `~/.config/opencode/opencode.json` |
 | Gemini CLI | Fully supported | `gemini` | `~/.gemini/settings.json` |
-| Codex | Coming soon | — | `~/.codex/config.toml` |
+| Codex | Fully supported | — | `~/.codex/config.toml` |
+
+> **Codex note:** the TOML writer seeds `approval_mode = "approve"` for every read-side MCP tool exported by `@uluops/ops-mcp` and `@uluops/registry-mcp` so interactive sessions don't surface an approval prompt on every `list_*`/`get_*`/`query_*` call. Write-side tools (`save_run`, `bulk_update_status`, `publish_definition`, etc.) are intentionally NOT pre-approved — Codex still asks before any state-changing operation. A re-install over a hand-tuned config (any `[mcp_servers.<server>.tools.*]` block present) preserves your customizations verbatim and skips the seed step.
 
 ```bash
 # Install for Claude Code (default)
 npx @uluops/setup
 
-# Install for OpenCode
+# Install for one specific harness
 npx @uluops/setup --harness opencode
-
-# Install for Gemini CLI
 npx @uluops/setup --harness gemini-cli
+
+# Install into every detected stable harness in a single run
+npx @uluops/setup --all-detected
+
+# Install into a specific subset (comma-separated)
+npx @uluops/setup --harness claude-code,gemini-cli
+```
+
+### Harness auto-detection
+
+If you don't pass `--harness` or `--all-detected`, setup probes your home directory for known harness install markers and picks a target:
+
+- **One harness detected** — that harness is used as the target. A dimmed `Detected <Name>` line confirms the choice (suppressed when the detected harness is the default `claude-code`).
+- **Multiple harnesses detected (interactive)** — you get a multi-select checkbox listing every detected harness, with **every option checked by default** so the "install everywhere" case is a single Enter press. Use space to toggle entries off.
+- **Multiple harnesses detected (non-interactive — `--yes`, `--api-key`, piped stdin)** — to keep CI scripts predictable, this preserves earlier behavior: the first detected harness installs and a dimmed notice lists the others. CI users who want multi-install opt in explicitly with `--all-detected`.
+- **No harnesses detected** — falls back to the default (`claude-code`) so `npx @uluops/setup` always does something useful on a fresh machine.
+
+Passing `--harness <name>` always wins — auto-detection is skipped entirely. Auto-detection only returns harnesses marked stable; when a future harness ships as experimental, an explicit `--harness <name>` will remain the only way to opt in.
+
+### Multi-harness install
+
+`@uluops/setup` is a zero-friction installer for any agentic stack you have. When you've installed multiple harnesses on the same machine, one invocation can wire UluOps into all of them — once-per-run prompts (API key, signup, CLI install) run a single time across the whole batch.
+
+```bash
+# Install into every detected stable harness
+npx @uluops/setup --all-detected
+
+# Same thing, alternative form (--all-detected is the canonical name)
+npx @uluops/setup --harness all
+
+# Subset
+npx @uluops/setup --harness claude-code,opencode
+
+# Aliases work in the comma-separated list
+npx @uluops/setup --harness claude,oc
+```
+
+Each harness gets its own per-section block in the summary:
+
 ```
+  Setup complete: 3 installed of 3 harnesses
+
+  ✓ [Claude Code] installed (23 agents · 28 commands · metrics)
+  ✓ [OpenCode] installed (23 agents)
+  ✓ [Gemini CLI] installed (23 agents · 28 commands · metrics)
+
+  Restart each of Claude Code, OpenCode, Gemini CLI to load agents.
+```
+
+**Failure isolation:** one harness failing does not abort the others. The failing harness lands as `✗ [<Name>] failed — <reason>` in the summary with a `Re-run: npx @uluops/setup --harness <name>` hint; siblings install cleanly. The process exits 1 when any harness failed operationally, 0 when every harness either succeeded or was declined at the conflict prompt (user choice is not failure).
+
+**Partial state:** if a per-harness step throws after MCP succeeded (e.g., a `mkdir` permission error during the agents step), the manifest records what landed plus `partial: "<step>"` naming the failed step. `--verify` surfaces this with a `partial install — failed at "<step>"` warning so you know a re-run is needed.
 
 ## What it does
 
@@ -43,7 +94,7 @@ npx @uluops/setup --harness gemini-cli
 | Pipeline commands | 2 | `~/.claude/commands/pipelines/` |
 | Agent metrics hook | 1 | `~/.claude/tools/agent-metrics/` |
 
-> Paths shown are for Claude Code (default). Gemini CLI installs agents as `.md` and commands as `.toml` to `~/.gemini/`. OpenCode installs agents to `~/.config/opencode/agents/`. Agent definitions and commands are transformed to the target harness format at install time from a single source.
+> Paths shown are for Claude Code (default). Gemini CLI installs agents as `.md` and commands as `.toml` to `~/.gemini/`. OpenCode installs agents to `~/.config/opencode/agents/`. Codex installs agents as `.toml` to `~/.codex/agents/` and ships a single `uluops-operator` skill under `~/.codex/skills/` instead of slash commands. Agent definitions and commands are transformed to the target harness format at install time from a single source.
 
 The installer runs these steps in sequence:
 
@@ -74,8 +125,16 @@ Setup will first ask whether you're creating a new UluOps account. Pick **Y** to
 npx @uluops/setup [options]
 
   --api-key <key>      API key (skip prompt)
-  --harness <name>     Target harness: claude-code, opencode, gemini-cli, codex
+  --harness <value>    Target harness(es). Single name, comma-separated subset,
+                       or "all" sentinel:
+                         --harness claude-code
+                         --harness claude-code,codex
+                         --harness all
+                       Names: claude-code, opencode, gemini-cli, codex
                        Aliases: claude, oc, gemini (default: claude-code)
+  --all-detected       Install into every detected stable harness. Canonical
+                       synonym for --harness all. Cannot be combined with
+                       --harness <single-name> (fail-fast conflict error).
   --signup             Create account from terminal (email + password)
   --scope <mode>       MCP config scope: "global" or "local" (default: global)
   --local-defs         Save definitions to ./uluops/ for review
@@ -85,7 +144,11 @@ npx @uluops/setup [options]
   --skip-validation    Accept API key without server verification
   --list               Show available agents and workflows without installing
   --verify             Check installation health: manifest, files, MCP config, API connectivity (no changes)
-  --uninstall          Remove all UluOps-managed artifacts
+  --uninstall          Remove UluOps-managed artifacts. Combine with --harness
+                       <name>[,<name>] to uninstall from a subset only —
+                       remaining harnesses (and global infrastructure like
+                       @uluops/cli) are preserved. Plain --uninstall removes
+                       everything (today's behavior).
   --dry-run            Show what would happen without making changes
   -y, --yes            Skip confirmations
 ```
@@ -96,7 +159,7 @@ npx @uluops/setup [options]
 Displays all agents and workflows included in the current version of the setup tool.
 
 ```text
-  ⟨u⟩ ulu·ops v0.6.0 — available agents and workflows
+  ⟨u⟩ ulu·ops v0.8.1 — available agents and workflows
 
   WORKFLOWS
   /workflows:post-implementation   Iterative validation after coding
@@ -115,7 +178,7 @@ Displays all agents and workflows included in the current version of the setup t
 Validates your current installation against the local manifest and checks API connectivity.
 
 ```text
-  ⟨u⟩ ulu·ops Installation Check v0.6.0
+  ⟨u⟩ ulu·ops Installation Check v0.8.1
 
   ✓ Manifest found (~/.uluops/manifest.json)
   ✓ All 23 agents present in ~/.claude/agents/
@@ -139,9 +202,18 @@ npx @uluops/setup --signup
 # Install for OpenCode
 npx @uluops/setup --harness opencode
 
+# Install into every detected stable harness in one run
+npx @uluops/setup --all-detected
+
+# Install into a specific subset
+npx @uluops/setup --harness claude-code,gemini-cli
+
 # Non-interactive (CI/automation)
 npx @uluops/setup --api-key ulr_abc123 -y
 
+# CI multi-harness: explicit opt-in to all-detected
+npx @uluops/setup --api-key ulr_abc123 --all-detected -y
+
 # Local MCP config (project-scoped)
 npx @uluops/setup --scope local
 
@@ -180,10 +252,22 @@ Setup manages four surfaces: agent files, command files, MCP config entries, and
 ## Uninstall
 
 ```
+# Uninstall everything (every harness in the manifest + globals + shell export)
 npx @uluops/setup --uninstall
+
+# Uninstall from a specific harness only — other harnesses + globals preserved
+npx @uluops/setup --uninstall --harness opencode
+
+# Uninstall from a comma-separated subset
+npx @uluops/setup --uninstall --harness opencode,gemini-cli
+
+# Same as no filter — uninstall everything
+npx @uluops/setup --uninstall --all-detected
 ```
 
-Removes only UluOps-managed files: agents, commands, MCP config entries, shell profile export (if `--shell` was used), and the global `@uluops/cli` package (only if this setup installed it — a CLI you installed yourself is left alone). Your custom agents and other MCP servers are preserved. Uninstall iterates all harnesses recorded in the manifest.
+Removes only UluOps-managed files: agents, commands, MCP config entries, shell profile export (if `--shell` was used), and the global `@uluops/cli` package (only if this setup installed it — a CLI you installed yourself is left alone). Your custom agents and other MCP servers are preserved.
+
+**Subset uninstall** (`--uninstall --harness <name>`) removes only the named harness(es) from the manifest and disk. Shared infrastructure (the global `@uluops/cli`, `@uluops/agent-metrics`, and the shell-profile export) is left in place because remaining harnesses still need it. The manifest is updated rather than deleted. A subset uninstall that names a harness not in the manifest fails fast with an error listing what IS in the manifest — no silent no-op.
 
 ## Requirements
 

package/assets/codex/skills/uluops-operator/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: uluops-operator
+description: Use when operating inside UluOps from Codex: using UluOps MCP tools or the ulu CLI; rendering or running registry agents, commands, workflows, or pipelines; saving Codex subagent runs to tracker projects; querying, triaging, or closing tracker issues; inspecting analysis records; or deciding how UluOps definitions should map onto Codex skills, agents, and local assets.
+---
+
+# UluOps Operator
+
+Use this skill as the operating map for UluOps in Codex. UluOps has three main surfaces:
+
+- **Registry**: source of truth for agents, commands, workflows, pipelines, versions, dependencies, and harness-specific rendering.
+- **Tracker**: source of truth for projects, runs, issues, analysis summaries, analysis records, reliability, and lifecycle.
+- **RAH**: statistical and higher-order analysis over registry/tracker state.
+
+Prefer MCP tools for tracker/registry state changes already exposed in the session. Prefer the `ulu` CLI for rendering definitions, execution surfaces not exposed by MCP, and machine-readable scripting.
+
+## Tool Choice
+
+| Task | Prefer | Notes |
+|---|---|---|
+| Query tracker projects, runs, issues, summaries | `mcp__uluops_tracker` | Use `query_issues`, `search_issues`, `get_project_summary`, run/analysis tools when available. |
+| Update tracker issue status or add notes | `mcp__uluops_tracker` | Use structured status updates with concise resolution reasons. |
+| Save Codex agent/pipeline output to tracker | `mcp__uluops_tracker` | Shape recommendations/issues/analysis records explicitly; preserve custom record types when supported. |
+| Query registry definitions, versions, dependencies | `mcp__uluops_registry` or `ulu` | Use MCP for lightweight lookups; CLI when rendered output or JSON scripting is needed. |
+| Render definitions for Codex | `ulu def get ... --rendered --target codex` | Registry remains source of truth; rendered files are working copies. |
+| Execute UluOps definitions directly | `ulu exec ...` | Use when the user explicitly wants CLI execution rather than Codex subagents. |
+| Analyze cross-run/project patterns | `mcp__rah` | Use for statistical or trend questions when exposed. |
+
+If a localhost registry/tracker CLI command fails inside Codex with a connection or sandbox-like error, retry the same command with sandbox escalation before changing environment variables or config.
+
+## Codex Surface Rules
+
+Codex does not have Claude-style slash commands as the primary reusable surface.
+
+- Use **skills** for stable UluOps workflows that should trigger naturally in Codex.
+- Use rendered **agent TOML** as source material for spawning Codex subagents.
+- Treat rendered commands, workflows, and pipelines as **orchestration instructions**. For Codex, they may need to become skills or be executed stepwise by Codex rather than copied as slash commands.
+- Do not bulk-install every registry definition as a skill. Keep registry as source of truth and render on demand unless a workflow is stable and high-value.
+
+Default Codex global paths:
+
+```text
+~/.codex/config.toml
+~/.codex/agents/
+~/.codex/skills/
+```
+
+## Common Commands
+
+Render definitions for Codex:
+
+```bash
+ulu def get agent code-validator --rendered --target codex
+ulu def get workflow ship --rendered --target codex
+ulu def get pipeline foundations --rendered --target codex
+```
+
+Render with a model envelope:
+
+```bash
+ulu def get agent assumption-excavator --rendered --target codex -m gpt
+```
+
+List and inspect definitions:
+
+```bash
+ulu def list --type agent --json
+ulu def get agent code-validator --json
+ulu deps pipeline foundations --json
+ulu versions list agent code-validator --json
+```
+
+Tracker reads via CLI when MCP does not expose the needed surface:
+
+```bash
+ulu projects list --json
+ulu issues list uluops-plans --status open --json
+ulu runs list uluops-plans --json
+ulu analytics burndown --project uluops-plans --days 30 --json
+```
+
+## Canonical Loop
+
+When asked to close the loop on an artifact:
+
+1. Identify the tracker project and artifact path.
+2. Pull current open issues or run the requested agent/pipeline.
+3. Inspect the artifact and nearby code/docs before editing.
+4. Patch the artifact or code with narrow, repo-consistent changes.
+5. Verify with tests, typecheck, or text audits appropriate to the change.
+6. Save the run or analysis to tracker when new agent output was produced.
+7. Mark resolved issues completed with a concrete reason naming the artifact or code path changed.
+8. Report what changed, what was verified, and any remaining risk.
+
+Do not mark an issue completed merely because it was inspected. Complete it only when the artifact/code now addresses the finding. Use `deferred`, `wontfix`, `false-positive`, or `observation` when that status is more accurate.
+
+## Running Registry Agents As Codex Subagents
+
+When the user asks to use a UluOps agent through Codex:
+
+1. Render or locate the agent definition for Codex.
+2. Read only enough of the TOML to understand the role, inputs, expected output, and scoring vocabulary.
+3. Spawn a Codex subagent using that definition's instructions and the target artifact.
+4. Ask the subagent for structured output: decision, score, findings/recommendations, analysis records, and evidence.
+5. Normalize the output before saving to tracker.
+
+For large artifacts, tell the subagent whether it read the full artifact or performed a targeted pass. Preserve that note in the tracker run summary.
+
+## Saving Runs To Tracker
+
+When saving a Codex subagent result:
+
+- Project: use the user-provided tracker project, or infer from local context only when obvious.
+- Workflow type: use the registry definition name or agent name.
+- Agent name: use the UluOps agent identifier, not the subagent nickname.
+- Recommendations/issues: preserve title, severity, category/failure mode, evidence, and actionable remediation.
+- Analysis records: preserve custom `record_type` values; do not force them into a closed enum unless the API requires it.
+- Summary: include artifact path, decision, score, method, caveats, and counts.
+
+If the save tool rejects a custom analysis shape, simplify only the rejected field and preserve the semantic content in `content`, `metadata`, or the run summary.
+
+## Issue Triage
+
+For top-issue workflows:
+
+1. Query open issues for the project with `priority: "all"` or the requested severity.
+2. Sort by tracker order unless the user requests a different ordering.
+3. Investigate each issue against the artifact or code.
+4. Patch the source of truth, not only the generated tracker text.
+5. Bulk update statuses only after the fixes are in place.
+
+Good resolution reasons are short and concrete:
+
+```text
+Resolved in plans/example.md by adding skipMissing runtime semantics and validation coverage.
+```
+
+## Registry And Definition Hygiene
+
+- Registry definitions are source of truth; rendered Codex assets can drift.
+- Use exact versions when reproducibility matters.
+- Use dependencies to understand pipelines before running them.
+- For Codex, a pipeline may be better represented as a skill recipe than a slash command or a static TOML file.
+- Keep stable, high-value Codex workflows as skills. Keep broad, changing catalogs in the registry.
+
+## Naming Discipline
+
+Use canonical project/repo/service names from tracker or registry when available. Do not invent aliases in specs or issue closures. If names disagree across artifacts, fix the source artifact or call out the mismatch explicitly.
+
+Current known canonical examples:
+
+- Tracker project: `uluops-plans`
+- Tracker API service/repo in specs: `ops-uluops-api`
+- Registry frontend: `ops-uluops-registry`
+
+## Safety
+
+- Be conservative with mutating registry operations such as publish, archive, deprecate, fork, or delete.
+- Be conservative with tracker bulk updates; use them when fixes are already made and the status is clear.
+- Never overwrite user edits while installing/rendering local Codex assets. Prefer re-rendering on demand and scoped patches.

package/dist/cli/select-harnesses.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Multi-target harness selection (spec §5 behavior matrix).
+ *
+ * Pure-ish: every external dependency (prompt, info-emitter) is injected
+ * so this module is testable without spawning the CLI or mocking inquirer.
+ * The cli.ts entry point wires it to real @inquirer/prompts + chalk-styled
+ * info() calls; tests pass plain callbacks and assert on the returned
+ * harnessNames + the prompt-input received by the callback.
+ *
+ * Flag conflict detection happens here, not in cli.ts, so the error
+ * messaging is uniform and a single test surface covers every CLI
+ * combinatoric.
+ */
+import type { HarnessProfile } from "../harnesses/index.js";
+export interface HarnessSelectionInput {
+    /**
+     * Value of the --harness flag as received from commander. May be a single
+     * canonical name ('claude-code'), an alias ('claude'), a comma-separated
+     * list ('claude-code,codex'), the 'all' sentinel, or the default
+     * (e.g. 'claude-code' when no --harness was passed).
+     */
+    harnessArg: string;
+    /**
+     * True when commander.getOptionValueSource('harness') === 'cli', i.e.
+     * the user actually passed --harness. False when only the default fired.
+     */
+    harnessFromCli: boolean;
+    /** Whether --all-detected was passed. */
+    allDetected: boolean;
+    /** Result of detectHarnesses() — stable profiles whose home dirs exist. */
+    detected: HarnessProfile[];
+    /**
+     * Fallback harness when zero are detected and the user did not pass an
+     * explicit single name. Today: 'claude-code' (the landing-page promise).
+     */
+    defaultHarness: string;
+    /**
+     * Whether the run is interactive (TTY + no --yes / --api-key /
+     * ULUOPS_API_KEY). The selection branch only prompts when this is true
+     * AND multiple harnesses are detected.
+     */
+    isInteractive: boolean;
+    /**
+     * Async callback that presents the multi-select checkbox to the user.
+     * Receives the detected profiles; returns the chosen subset of harness
+     * names. Only called when isInteractive && detected.length > 1 && no
+     * explicit --harness / --all-detected was provided. May return an empty
+     * array (user unchecked everything) — runSetup handles that case.
+     */
+    promptCheckbox: (profiles: HarnessProfile[]) => Promise<string[]>;
+    /**
+     * Optional info-line emitter for the "dimmed notice" branches. No-op when
+     * undefined (tests can pass a recorder; cli.ts passes the styled info()).
+     */
+    emitInfo?: (msg: string) => void;
+}
+export declare class HarnessSelectionError extends Error {
+    constructor(message: string);
+}
+/**
+ * Parse a --harness value into a list of names (or the 'all' sentinel).
+ * Comma-separated parsing splits on `,` and trims whitespace; empty
+ * tokens are dropped. 'all' is reserved — a literal harness named 'all'
+ * would conflict (no such harness exists today).
+ */
+export declare function parseHarnessArg(arg: string): string[] | "all";
+/**
+ * Resolve the set of harness names to install into.
+ *
+ * Behavior matrix mirrors spec §5:
+ *
+ *   | --harness     | --all-detected | TTY | detected | result                          |
+ *   |---------------|----------------|-----|----------|---------------------------------|
+ *   | omitted       | no             |  *  |    0     | [defaultHarness]                |
+ *   | omitted       | no             |  *  |    1     | [detected[0]]                   |
+ *   | omitted       | no             | yes |   >1     | promptCheckbox(detected)        |
+ *   | omitted       | no             | no  |   >1     | [detected[0]] + dimmed notice   |
+ *   | <name>        | no             |  *  |    *     | [<name>]                        |
+ *   | <a>,<b>       | no             |  *  |    *     | [<a>, <b>]                      |
+ *   | all           | no             |  *  |   >0     | detected.map(p => p.name)       |
+ *   | all           | no             |  *  |    0     | [defaultHarness]                |
+ *   | omitted       | yes            |  *  |   >0     | detected.map(p => p.name)       |
+ *   | omitted       | yes            |  *  |    0     | [defaultHarness]                |
+ *   | all           | yes            |  *  |    *     | (same as either alone)          |
+ *   | <name>        | yes            |  *  |    *     | ERROR: conflicting flags        |
+ *
+ * Caller is responsible for validating each returned name via getProfile()
+ * (typo detection) and for handling the empty-array case (user unchecked
+ * everything — runSetup exits cleanly).
+ */
+export declare function selectHarnesses(input: HarnessSelectionInput): Promise<string[]>;

package/dist/cli/select-harnesses.js

@@ -0,0 +1,108 @@
+/**
+ * Multi-target harness selection (spec §5 behavior matrix).
+ *
+ * Pure-ish: every external dependency (prompt, info-emitter) is injected
+ * so this module is testable without spawning the CLI or mocking inquirer.
+ * The cli.ts entry point wires it to real @inquirer/prompts + chalk-styled
+ * info() calls; tests pass plain callbacks and assert on the returned
+ * harnessNames + the prompt-input received by the callback.
+ *
+ * Flag conflict detection happens here, not in cli.ts, so the error
+ * messaging is uniform and a single test surface covers every CLI
+ * combinatoric.
+ */
+export class HarnessSelectionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "HarnessSelectionError";
+    }
+}
+/**
+ * Parse a --harness value into a list of names (or the 'all' sentinel).
+ * Comma-separated parsing splits on `,` and trims whitespace; empty
+ * tokens are dropped. 'all' is reserved — a literal harness named 'all'
+ * would conflict (no such harness exists today).
+ */
+export function parseHarnessArg(arg) {
+    const trimmed = arg.trim();
+    if (trimmed === "all")
+        return "all";
+    return trimmed
+        .split(",")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}
+/**
+ * Resolve the set of harness names to install into.
+ *
+ * Behavior matrix mirrors spec §5:
+ *
+ *   | --harness     | --all-detected | TTY | detected | result                          |
+ *   |---------------|----------------|-----|----------|---------------------------------|
+ *   | omitted       | no             |  *  |    0     | [defaultHarness]                |
+ *   | omitted       | no             |  *  |    1     | [detected[0]]                   |
+ *   | omitted       | no             | yes |   >1     | promptCheckbox(detected)        |
+ *   | omitted       | no             | no  |   >1     | [detected[0]] + dimmed notice   |
+ *   | <name>        | no             |  *  |    *     | [<name>]                        |
+ *   | <a>,<b>       | no             |  *  |    *     | [<a>, <b>]                      |
+ *   | all           | no             |  *  |   >0     | detected.map(p => p.name)       |
+ *   | all           | no             |  *  |    0     | [defaultHarness]                |
+ *   | omitted       | yes            |  *  |   >0     | detected.map(p => p.name)       |
+ *   | omitted       | yes            |  *  |    0     | [defaultHarness]                |
+ *   | all           | yes            |  *  |    *     | (same as either alone)          |
+ *   | <name>        | yes            |  *  |    *     | ERROR: conflicting flags        |
+ *
+ * Caller is responsible for validating each returned name via getProfile()
+ * (typo detection) and for handling the empty-array case (user unchecked
+ * everything — runSetup exits cleanly).
+ */
+export async function selectHarnesses(input) {
+    // Flag conflict — explicit --harness <name> + --all-detected is
+    // ambiguous and should fail fast before any state is touched. The 'all'
+    // sentinel is the one case where the two flags ARE compatible (they mean
+    // the same thing) so we accept that combination silently.
+    if (input.allDetected &&
+        input.harnessFromCli &&
+        input.harnessArg.trim() !== "all") {
+        throw new HarnessSelectionError(`--harness ${input.harnessArg} conflicts with --all-detected; pick one`);
+    }
+    // Explicit --harness wins over --all-detected, with one harmonization:
+    // --harness all behaves identically to --all-detected.
+    if (input.harnessFromCli) {
+        const parsed = parseHarnessArg(input.harnessArg);
+        if (parsed === "all") {
+            return input.detected.length > 0
+                ? input.detected.map((p) => p.name)
+                : [input.defaultHarness];
+        }
+        return parsed;
+    }
+    // --all-detected without --harness
+    if (input.allDetected) {
+        return input.detected.length > 0
+            ? input.detected.map((p) => p.name)
+            : [input.defaultHarness];
+    }
+    // Auto-detection (no explicit flags)
+    if (input.detected.length === 0) {
+        return [input.defaultHarness];
+    }
+    if (input.detected.length === 1) {
+        const only = input.detected[0];
+        if (only.name !== input.defaultHarness && input.emitInfo) {
+            input.emitInfo(`Detected ${only.displayName} — using as target (pass --harness to override)`);
+        }
+        return [only.name];
+    }
+    // detected.length > 1
+    if (input.isInteractive) {
+        return await input.promptCheckbox(input.detected);
+    }
+    // Non-interactive with multiple detected: today's behavior preserved
+    // (first detected + dimmed notice). Multi-harness CI users opt in with
+    // --all-detected. Spec §10.1.
+    if (input.emitInfo) {
+        input.emitInfo(`Multiple harnesses detected (${input.detected.map((p) => p.displayName).join(", ")}); defaulting to ${input.detected[0].displayName} — pass --all-detected to install into all`);
+    }
+    return [input.detected[0].name];
+}