@uluops/setup 0.11.0 → 0.13.0

package/README.md

@@ -6,12 +6,16 @@
 
 Zero-friction installer for [UluOps](https://uluops.ai) agentic harnesses. One command sets up MCP servers, agents, and slash commands for Claude Code, OpenCode, and more.
 
-```
+```bash
 npx @uluops/setup
 ```
 
+> Requires **Node.js >= 20** ([full requirements](#requirements)).
+
 > **⚠️ Windows Users:** Native Windows is not yet supported. Please use **WSL2 (Ubuntu)** and run the setup inside your WSL environment.
 
+**Contents:** [Supported harnesses](#supported-harnesses) · [What it does](#what-it-does) · [Usage](#usage) · [Options](#options) · [Advanced commands](#advanced-commands) · [Examples](#examples) · [How updates work](#how-updates-work) · [Troubleshooting](#troubleshooting) · [Uninstall](#uninstall) · [Requirements](#requirements)
+
 ## Supported harnesses
 
 | Harness | Status | Alias | Config |
@@ -43,7 +47,14 @@ npx @uluops/setup --harness claude-code,gemini-cli
 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 (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:
+
+  ```text
+  ? Multiple harnesses detected. Which would you like to install into?
+  ❯ ◉ Claude Code
+    ◉ OpenCode
+    ◉ Gemini CLI
+  ```
 - **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.
 
@@ -69,7 +80,7 @@ npx @uluops/setup --harness claude,oc
 
 Each harness gets its own per-section block in the summary:
 
-```
+```text
   Setup complete: 3 installed of 3 harnesses
 
   ✓ [Claude Code] installed (23 agents · 28 commands · metrics)
@@ -99,17 +110,18 @@ Each harness gets its own per-section block in the summary:
 The installer runs these steps in sequence:
 
 1. **Authenticate** — Asks whether you're creating a new account. New users sign up with email + password; returning users paste an API key. Skip the question with `--api-key`, `--signup`, `--yes`, or `ULUOPS_API_KEY`.
-2. **MCP config** — Writes tracker and registry server entries to the harness config
-3. **Definitions** — Copies pre-rendered agent definition files
-4. **Metrics hook** — Configures a post-agent hook for automatic run capture (Claude Code and Gemini CLI)
-5. **`ulu` CLI** *(optional)* — Offers to install `@uluops/cli` globally. Interactive runs are prompted (default Y); non-interactive runs skip unless `--with-cli` is passed. `--no-cli` always skips. The install is best-effort: if `npm install -g` fails (permissions, nvm prefix, etc.) the rest of setup still completes and a manual install command is printed.
-6. **Health check** — Verifies both API endpoints are reachable
+2. **Registry username** *(optional)* — Offers to set your registry username, the one-time prerequisite for creating or publishing definitions. Never forced: consumers who only run definitions don't need one, and non-interactive runs skip it silently unless `--username <name>` is supplied.
+3. **MCP config** — Writes tracker and registry server entries to the harness config
+4. **Definitions** — Copies pre-rendered agent definition files
+5. **Metrics hook** — Configures a post-agent hook for automatic run capture (Claude Code and Gemini CLI)
+6. **`ulu` CLI** *(optional)* — Offers to install `@uluops/cli` globally. Interactive runs are prompted (default Y); non-interactive runs skip unless `--with-cli` is passed. `--no-cli` always skips. The install is best-effort: if `npm install -g` fails (permissions, nvm prefix, etc.) the rest of setup still completes and a manual install command is printed.
+7. **Health check** — Verifies both API endpoints are reachable
 
 > When this setup installs the CLI, the install is recorded in the manifest so `--uninstall` removes it symmetrically. If the CLI was already on your PATH before running setup, it is left alone on uninstall.
 
 ## Usage
 
-```
+```bash
 npx @uluops/setup
 ```
 
@@ -121,7 +133,7 @@ Setup will first ask whether you're creating a new UluOps account. Pick **Y** to
 
 ### Options
 
-```
+```text
 npx @uluops/setup [options]
 
   --api-key <key>      API key (skip prompt)
@@ -136,6 +148,11 @@ npx @uluops/setup [options]
                        synonym for --harness all. Cannot be combined with
                        --harness <single-name> (fail-fast conflict error).
   --signup             Create account from terminal (email + password)
+  --username <name>    Set your registry username without prompting (lowercase
+                       slug, e.g. ulu-labs). One-time prerequisite for
+                       creating/publishing definitions — optional if you only
+                       run them. Non-interactive runs skip the username step
+                       entirely unless this flag is passed.
   --scope <mode>       MCP config scope: "global" or "local" (default: global)
   --local-defs         Install definitions into ./uluops/ (project-scoped)
                        instead of the harness's home directory
@@ -167,36 +184,43 @@ npx @uluops/setup [options]
 Displays all agents and workflows included in the current version of the setup tool.
 
 ```text
-  ⟨u⟩ ulu·ops v0.9.5 — available agents and workflows
+  ⟨u⟩ ulu·ops v0.12.0 — available agents and workflows
 
   WORKFLOWS
-  /workflows:post-implementation   Iterative validation after coding
-  /workflows:pre-implementation    Design validation before implementation
-  /workflows:prompt-audit          Strategic prompt quality audit
-
-  AGENTS (run individually)                          MODEL
-  /agents:code-validator           Validate cod...  sonnet
-  /agents:type-safety              Deep TypeScr...  sonnet
-  /agents:security-analyst         Comprehensiv...  sonnet
-  /agents:test-architect           Validate tes...  sonnet
-  ...
+    /workflows:post-implementation    Iterative validation workflow. Run af...
+    /workflows:pre-implementation     Validates proposed design and archite...
+    /workflows:prompt-audit           Comprehensive prompt audit with ecosy...
+
+  AGENTS (run individually)                              MODEL
+    /agents:anxiety-reader            Reads from the pos... sonnet
+    /agents:architect                 Run Pre-Implementa... sonnet
+    /agents:assumption-excavator      Surfaces implicit ... sonnet
+    /agents:audit                     Deep runtime corre... sonnet
+    /agents:docs-validate             Validates comprehe... sonnet
+    /agents:security                  Comprehensive secu... sonnet
+    ...
 ```
 
 #### Check installation health (`--verify`)
 Validates your current installation against the local manifest and checks API connectivity.
 
 ```text
-  ⟨u⟩ ulu·ops Installation Check v0.9.5
+  ⟨u⟩ ulu·ops Installation Check v0.12.0
 
-  ✓ Manifest found (~/.uluops/manifest.json)
-  ✓ All 23 agents present in ~/.claude/agents/
-  ✓ MCP servers configured in ~/.claude.json
-  ✓ API connectivity: Tracker (Online)
-  ✓ API connectivity: Registry (Online)
+  ✓ Manifest found (v0.12.0, installed 2026-08-21)
+  ✓ [Claude Code] Readiness
+  ✓ [Claude Code] MCP config present in ~/.claude.json (2 servers)
+  ✓ [Claude Code] 23/23 agents in ~/.claude/agents
+  ✓ [Claude Code] 28/28 commands
+  ✓ [Claude Code] Agent metrics hook configured
+  ✓ API key valid
+  ✓ MCP packages resolvable on npm
 
   All checks passed.
 ```
 
+> With multiple harnesses installed, `--verify` prints one `[<Harness>]` block per manifest entry.
+
 ### Examples
 
 ```bash
@@ -207,6 +231,9 @@ npx @uluops/setup
 # Skip the account question and go straight to signup
 npx @uluops/setup --signup
 
+# Set your registry username during setup (required to publish definitions)
+npx @uluops/setup --username ulu-labs
+
 # Install for OpenCode
 npx @uluops/setup --harness opencode
 
@@ -246,12 +273,17 @@ npx @uluops/setup --no-agent-metrics-cli
 
 ## How updates work
 
-Re-running `npx @uluops/setup` is safe and idempotent:
+Re-running `npx @uluops/setup` is designed to be safe to repeat:
 
 - Unchanged files are skipped (content hash comparison)
 - Updated files are overwritten
-- Removed definitions are cleaned up
-- Your custom agents and non-UluOps MCP servers are never touched
+- Definitions no longer shipped are cleaned up
+- Custom agents and non-UluOps MCP servers are left alone, with two known
+  edges: a hook whose command *contains* the UluOps ownership marker (e.g. a
+  hand-forked copy of our agent-metrics hook) is treated as ours and replaced
+  on re-run, and switching `--local-defs` between runs starts a fresh tree —
+  the previous scope's files stay on disk untracked (setup warns when this
+  happens)
 
 Setup manages four surfaces: agent files, command files, MCP config entries, and the metrics hook. A manifest at `~/.uluops/manifest.json` tracks what was installed so `--uninstall` can cleanly reverse all changes. The manifest supports multiple harnesses — each gets its own installation state.
 
@@ -259,13 +291,13 @@ Setup manages four surfaces: agent files, command files, MCP config entries, and
 
 - **Agents not appearing:** Ensure you have restarted your harness (Claude Code, etc.) after running setup. For Claude Code, simply exit and restart the CLI.
 - **MCP errors:** If the harness fails to start the MCP servers, ensure `npx` is available in your PATH. You can check your config at `~/.claude.json` or `~/.config/opencode/opencode.json`.
-- **API key rejected:** Verify your key at [app.uluops.ai](https://app.uluops.ai). If you are behind a corporate proxy, you may need to set `HTTPS_PROXY`.
+- **API key rejected:** Verify your key at [app.uluops.ai](https://app.uluops.ai). Behind a corporate proxy, note that setup's own API calls do **not** honor `HTTPS_PROXY` (Node's fetch ignores proxy env vars) — use `--skip-validation` to complete setup offline and verify the key later from a network that can reach `api.uluops.ai`.
 - **`@uluops/cli` install warning:** If setup warns it could not install the CLI globally (EACCES, nvm prefix mismatch, network), the rest of setup still completes. Run `npm install -g @uluops/cli` yourself when convenient — once it's on your PATH, every subsequent `npx @uluops/setup` will see it and skip the install step.
 - **Windows issues:** Remember that native Windows is not supported; you must run the installer and your harness within **WSL2**.
 
 ## Uninstall
 
-```
+```bash
 # Uninstall everything (every harness in the manifest + globals + shell export)
 npx @uluops/setup --uninstall
 
@@ -283,6 +315,23 @@ Removes only UluOps-managed files: agents, commands, MCP config entries, shell p
 
 **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.
 
+## Data & privacy
+
+The metrics hook (step 5) captures **agent execution metadata only** — token
+counts, durations, model and agent names — into a **local buffer** on your
+machine. The hook itself sends nothing anywhere: data reaches the UluOps
+tracker only when a run is explicitly saved (by you, or by tooling you run).
+Artifact content being validated is never stored — only validation results.
+
+Validation run and issue data saved to the tracker is **retained
+indefinitely by design** (the immutable forensics model); account and data
+deletion is available on request. Full details:
+[uluops.ai/privacy](https://uluops.ai/privacy).
+
+Opt-outs: `--no-metrics` skips the hook install entirely; `--uninstall`
+removes it later. If you're installing inside an organization, check your
+org's telemetry policy before enabling the hook on shared projects.
+
 ## Requirements
 
 - **Node.js:** >= 20.0.0

package/dist/cli.js

@@ -3,7 +3,7 @@ import { Command } from "commander";
 import chalk from "chalk";
 import { info, printAgentList } from "./lib/display.js";
 import { getVersion } from "./lib/version.js";
-import { listHarnesses, detectHarnesses, getProfile, HarnessNotTestedError, } from "./harnesses/index.js";
+import { listHarnesses, detectHarnesses, detectExcludedExperimental, getProfile, HarnessNotTestedError, } from "./harnesses/index.js";
 import { InstallLockHeldError } from "./lib/install-lock.js";
 import { runSetup } from "./commands/setup.js";
 import { runUninstall } from "./commands/uninstall.js";
@@ -73,6 +73,12 @@ async function main() {
     // matrix of (--harness, --all-detected, detection count, TTY) lives in
     // one tested place. cli.ts only wires the prompt and emit-info callbacks.
     const detected = detectHarnesses();
+    // Name the exclusion: auto-detection only returns stable profiles, and a
+    // user who can see an experimental harness installed reads silence as a
+    // detection bug rather than a policy.
+    for (const p of detectExcludedExperimental()) {
+        console.log(chalk.dim(`  Detected ${p.displayName} (experimental) — excluded from auto-detection; opt in with --harness ${p.name}`));
+    }
     const isInteractive = !opts.yes &&
         !opts.apiKey &&
         !process.env["ULUOPS_API_KEY"] &&

package/dist/commands/helpers.js

@@ -14,6 +14,7 @@ import { installAgentMetricsCli, AGENT_METRICS_PACKAGE, AGENT_METRICS_BIN, } fro
 import { writeShellExport } from "../steps/shell.js";
 import { probeHookSupport } from "../lib/settings-merger.js";
 import { findProjectRoot, ASSETS_DIR } from "../lib/paths.js";
+import { isEnoent } from "../lib/file-ops.js";
 import { getHealthTimeout } from "../lib/health.js";
 import { ok, warn, fail, info } from "../lib/display.js";
 import { ConflictRejectedError } from "./errors.js";
@@ -74,7 +75,14 @@ export async function initContext(opts) {
             ok(`API key generated`);
         }
         else {
-            const interactive = !opts.yes && !opts.apiKey && !process.env["ULUOPS_API_KEY"];
+            // Non-TTY must fall through to resolveApiKey's no-key error (which
+            // names --api-key / ULUOPS_API_KEY) — prompting against a closed stdin
+            // dies on inquirer's raw cancellation instead. Mirrors the isTTY guard
+            // in shouldPromptForAccount.
+            const interactive = !opts.yes &&
+                !opts.apiKey &&
+                !process.env["ULUOPS_API_KEY"] &&
+                Boolean(process.stdin.isTTY);
             const auth = await resolveApiKey({
                 apiKeyFlag: opts.apiKey,
                 skipValidation: opts.skipValidation,
@@ -216,7 +224,14 @@ export async function configureMetricsStep(profile, opts) {
     }
     if (!profile.hooks) {
         info(chalk.dim(`Metrics hooks not supported for ${profile.displayName}`));
-        return { toolFilesCopied: 0, hookConfigured: false, hooksInstalledVersion: null };
+        // skippedReason for shape parity with installMetrics' own hookless
+        // branch — metricsObserved must read this run as non-observing.
+        return {
+            toolFilesCopied: 0,
+            hookConfigured: false,
+            hooksInstalledVersion: null,
+            skippedReason: "no-hook-support",
+        };
     }
     const probe = probeHookSupport();
     if (probe.warning)
@@ -229,6 +244,15 @@ export async function configureMetricsStep(profile, opts) {
         parts.push("hook configured");
         const toolPath = profile.paths.toolsDir?.replace(process.env["HOME"] ?? "", "~");
         ok(`Agent metrics → ${toolPath}/ (${parts.join(", ")})`);
+        // Disclosure, not decoration: the hook captures execution metadata to a
+        // LOCAL buffer and sends nothing itself — say so where it's installed.
+        info(chalk.dim("  Captures agent token/duration metadata to a local buffer (nothing is sent).\n" +
+            "  Skip with --no-metrics · uluops.ai/privacy"));
+    }
+    else if (res.skippedReason === "hook-state-unknown") {
+        // installMetrics already warned with the settings path and the
+        // keeping-prior-record note — do not follow it with a message that
+        // misnames the cause (tool files may well have copied).
     }
     else {
         warn("Agent metrics hook not configured (tool files not found)");
@@ -369,10 +393,18 @@ export async function runHealthCheck(opts) {
                 checkEndpoint("https://api.uluops.ai/api/v1/health"),
                 checkEndpoint("https://api.uluops.ai/api/v1/registry/health"),
             ]);
-            if (trackerOk && registryOk)
+            if (trackerOk && registryOk) {
                 ok("Health check passed — both APIs reachable");
-            else
-                warn("Some APIs unreachable (MCP tools may have limited functionality)");
+            }
+            else {
+                // Name the failing endpoint — "some APIs" gives the user nothing to
+                // report or retry against.
+                const down = [
+                    !trackerOk && "Tracker",
+                    !registryOk && "Registry",
+                ].filter(Boolean);
+                warn(`${down.join(" and ")} API unreachable (MCP tools may have limited functionality)`);
+            }
         }
         catch {
             warn("Health check skipped (network issue)");
@@ -418,12 +450,43 @@ export async function checkConflicts(profile, localDefs) {
         : profile.paths.agentsDir;
     const srcDir = join(ASSETS_DIR, profile.name, "agents");
     let existingFiles;
-    let assetFiles;
     try {
         existingFiles = await readdir(destDir);
+    }
+    catch (err) {
+        if (isEnoent(err)) {
+            return; // No destination dir yet — fresh install, nothing to conflict.
+        }
+        // Unreadable destination = conflicts UNKNOWN, never "no conflicts":
+        // proceeding silently overwrites files we could not enumerate. Ask.
+        warn(`Could not read ${destDir} (${err instanceof Error ? err.message : String(err)}) — cannot check for existing agents that would be overwritten.`);
+        if (!process.stdin.isTTY) {
+            // Non-TTY can't answer the prompt; fail-safe is refusal, not a hang
+            // and not a silent overwrite. This is an OPERATIONAL failure (EACCES
+            // class), not a user policy choice — it must exit 1 for CI, so a
+            // plain Error (failed path), not ConflictRejectedError (exit 0).
+            // (--yes skips checkConflicts entirely.)
+            throw new Error(`Cannot verify conflicts in ${destDir} and no TTY to ask — refusing to risk overwriting existing files. Fix the directory permissions or pass --yes to proceed without the check.`);
+        }
+        const { confirm } = await import("@inquirer/prompts");
+        const proceed = await confirm({
+            message: "Continue anyway (existing files may be overwritten)?",
+            default: false,
+        });
+        if (!proceed) {
+            throw new ConflictRejectedError(profile.name);
+        }
+        return;
+    }
+    let assetFiles;
+    try {
         assetFiles = await readdir(srcDir);
     }
-    catch {
+    catch (err) {
+        // The BUNDLED assets being unreadable is not a fresh-install condition —
+        // it means the package itself is broken. Don't silently skip the
+        // conflict check; say so (the copy step will surface the hard failure).
+        warn(`Could not read bundled agent assets (${err instanceof Error ? err.message : String(err)}) — conflict check skipped`);
         return;
     }
     const conflicts = assetFiles.filter((f) => existingFiles.includes(f));

package/dist/commands/per-harness.d.ts

@@ -50,6 +50,11 @@ export interface PerHarnessResult {
  *   | Any declined AND zero failed                         |  0   |
  *   | Empty (user unchecked all, or no harnesses to run)   |  0   |
  *
+ * The implementation is deliberately a single `anyFailed` check, not four
+ * branches: rows 1, 3, and 4 all share exit 0, so the table collapses to
+ * "any operational failure → 1, everything else → 0". The table is the
+ * spec; the code is its minimal form.
+ *
  * Rationale: CI wrapping `--harness all` should not be poisoned by
  * user-policy choices (declines, no-op outcomes) but MUST fail on
  * operational errors (EACCES, ENOSPC, parse-error) so deploy pipelines

package/dist/commands/per-harness.js

@@ -18,6 +18,11 @@
  *   | Any declined AND zero failed                         |  0   |
  *   | Empty (user unchecked all, or no harnesses to run)   |  0   |
  *
+ * The implementation is deliberately a single `anyFailed` check, not four
+ * branches: rows 1, 3, and 4 all share exit 0, so the table collapses to
+ * "any operational failure → 1, everything else → 0". The table is the
+ * spec; the code is its minimal form.
+ *
  * Rationale: CI wrapping `--harness all` should not be poisoned by
  * user-policy choices (declines, no-op outcomes) but MUST fail on
  * operational errors (EACCES, ENOSPC, parse-error) so deploy pipelines

package/dist/commands/setup.d.ts

@@ -22,4 +22,11 @@ interface RunSetupOpts {
     /** Explicit registry username (slug). Set + confirmed non-interactively when provided. */
     username?: string;
 }
+/**
+ * The main install flow: resolves every target harness up front (fail-fast on
+ * typos), runs the once-per-run steps (auth, username, CLI prompts) a single
+ * time, then installs MCP config, definitions, and the metrics hook per
+ * harness with failure isolation — one harness failing does not abort the
+ * others. Exits 1 if any harness failed operationally.
+ */
 export declare function runSetup(opts: RunSetupOpts): Promise<void>;

package/dist/commands/setup.js

@@ -2,7 +2,7 @@ import chalk from "chalk";
 import { join } from "node:path";
 import { loadManifest, saveManifest, } from "../lib/manifest.js";
 import { findProjectRoot } from "../lib/paths.js";
-import { info, printSetupSummary, warn } from "../lib/display.js";
+import { info, warn, blank, printSetupBanner, printHarnessHeader, printSetupSummary, } from "../lib/display.js";
 import { getVersion } from "../lib/version.js";
 import { getProfile } from "../harnesses/index.js";
 import { acquireInstallLock, } from "../lib/install-lock.js";
@@ -10,6 +10,13 @@ import { initContext, checkConflicts, configureMcpStep, installAgentsDefs, insta
 import { ConflictRejectedError } from "./errors.js";
 import { classifyExit, } from "./per-harness.js";
 import { maybeSetUsername } from "../steps/username.js";
+/**
+ * The main install flow: resolves every target harness up front (fail-fast on
+ * typos), runs the once-per-run steps (auth, username, CLI prompts) a single
+ * time, then installs MCP config, definitions, and the metrics hook per
+ * harness with failure isolation — one harness failing does not abort the
+ * others. Exits 1 if any harness failed operationally.
+ */
 export async function runSetup(opts) {
     if (opts.harnesses.length === 0) {
         info(chalk.dim("Nothing to install — re-run with at least one harness selected.\n"));
@@ -20,21 +27,16 @@ export async function runSetup(opts) {
     // is touched. getProfile throws HarnessNotTestedError or a friendly
     // unknown-name error; the top-level catch in cli.ts surfaces them.
     const profiles = opts.harnesses.map((name) => getProfile(name));
-    console.log();
-    console.log(`  ${chalk.dim("⟨u⟩")} ${chalk.cyan.bold("ulu")}${chalk.bold("·ops")}`);
-    console.log(`      ${chalk.dim("operating intelligence as infrastructure")}`);
-    console.log();
     const targetSummary = profiles.length === 1
         ? profiles[0].displayName
         : `${profiles.length} harnesses (${profiles.map((p) => p.displayName).join(", ")})`;
-    console.log(`  Setup v${version} — ${chalk.bold(targetSummary)}`);
-    console.log();
+    printSetupBanner(version, targetSummary);
     if (opts.dryRun) {
         info(chalk.dim("(dry run — no changes will be made)\n"));
     }
     // === Once-per-run: BEFORE the per-harness loop ===
     const { env, apiKey } = await initContext(opts);
-    console.log();
+    blank();
     // Optional, never-forced: offer to set a registry username (the one-time
     // prerequisite for creating/publishing definitions). Skipped silently in
     // non-interactive runs unless --username is supplied.
@@ -45,7 +47,7 @@ export async function runSetup(opts) {
         dryRun: opts.dryRun,
         emit: (msg) => info(msg),
     });
-    console.log();
+    blank();
     // Acquire the install lock before touching any shared state. Skipped on
     // dry-run (read-only). The lock excludes a second concurrent uluops-setup
     // from racing the manifest / MCP config / shell-profile / settings.json
@@ -53,6 +55,7 @@ export async function runSetup(opts) {
     // concurrent multi-harness installs from separate processes serialize
     // (spec §10.6).
     let lock = null;
+    let exitCode = 0;
     if (!opts.dryRun) {
         lock = await acquireInstallLock();
     }
@@ -60,7 +63,7 @@ export async function runSetup(opts) {
         const existingManifest = await loadManifest();
         if (existingManifest && existingManifest.version !== version) {
             info(`Updating ${chalk.dim(existingManifest.version)} → ${chalk.green(version)}`);
-            console.log();
+            blank();
         }
         // === Per-harness loop ===
         const perHarnessResults = [];
@@ -72,7 +75,7 @@ export async function runSetup(opts) {
             // detection; using the wrong harness's prev list silently orphans
             // files (spec §7.6.1 per-iteration state isolation).
             const existingHarness = existingManifest?.harnesses[harnessName];
-            console.log(chalk.dim(`▸ ${profile.displayName}`));
+            printHarnessHeader(profile.displayName);
             if (existingHarness && !existingHarness.partial) {
                 info(chalk.dim(`  Already installed at v${version} — checking for changes`));
             }
@@ -95,10 +98,23 @@ export async function runSetup(opts) {
                             error: err.message,
                         });
                         warn(`[${harnessName}] skipped (user declined conflict) — continuing with remaining harnesses`);
-                        console.log();
+                        blank();
                         continue;
                     }
-                    throw err;
+                    // Operational failure (e.g. unreadable dest dir, non-TTY refusal):
+                    // classify-and-continue like the MCP branch below — rethrowing
+                    // escaped the per-harness loop, leaving installed siblings with NO
+                    // manifest record and skipping later harnesses (audit pass 6,
+                    // PROBE D). classifyExit yields 1 for a failed result.
+                    perHarnessResults.push({
+                        harnessName,
+                        profile,
+                        status: "failed",
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                    warn(`[${harnessName}] conflict check failed — continuing with remaining harnesses`);
+                    blank();
+                    continue;
                 }
             }
             // MCP must succeed for a manifest entry to exist (the entry depends
@@ -116,7 +132,7 @@ export async function runSetup(opts) {
                     error: err instanceof Error ? err.message : String(err),
                 });
                 warn(`[${harnessName}] MCP configuration failed — continuing with remaining harnesses`);
-                console.log();
+                blank();
                 continue;
             }
             // Subsequent steps may throw on pre-loop work (mkdir EACCES, etc.).
@@ -158,7 +174,7 @@ export async function runSetup(opts) {
                 metricsResult,
                 partial: failedStep,
             });
-            console.log();
+            blank();
         }
         // === Once-per-run: AFTER the per-harness loop ===
         // Global @uluops/cli install — single prompt, single install across the
@@ -192,32 +208,70 @@ export async function runSetup(opts) {
         // harness entry. Declined harnesses and pre-MCP failures land no entry.
         if (!opts.dryRun) {
             const now = new Date().toISOString();
-            const manifest = existingManifest ?? {
-                version,
-                installedAt: now,
-                shellModified: false,
-                harnesses: {},
-            };
+            // Clone rather than alias: mutating the loaded object would silently
+            // change what any later `existingManifest` read sees. Today all reads
+            // precede this block — the clone keeps that a non-condition instead of
+            // an ordering invariant someone has to remember.
+            const manifest = existingManifest
+                ? structuredClone(existingManifest)
+                : {
+                    version,
+                    installedAt: now,
+                    shellModified: false,
+                    harnesses: {},
+                };
             manifest.version = version;
             manifest.installedAt = now;
             manifest.shellModified = shellModified || manifest.shellModified;
             for (const r of perHarnessResults) {
                 if (!r.mcpResult)
                     continue; // no MCP success → no entry
+                // A step that THREW produced no result — falling back to [] here
+                // would replace a populated prior entry with an empty record,
+                // orphaning every previously-installed file the moment a re-run
+                // fails (uninstall trusts these lists). Undefined result = keep the
+                // prior record; the `partial` marker names what didn't complete.
+                const prevEntry = existingManifest?.harnesses[r.harnessName];
+                const newDefsScope = opts.localDefs ? "local" : "global";
+                // TWO gates, deliberately: the FILE LISTS live under defsPath and
+                // may only be inherited within the same scope (a global list against
+                // a local path points uninstall at the wrong tree). The HOOK fields
+                // live in settings.json under profile.paths — scope-independent —
+                // and gating them on defsScope falsified hooksInstalled on a scope
+                // flip (audit pass 6, PROBE C).
+                const prevLists = prevEntry && prevEntry.defsScope === newDefsScope
+                    ? prevEntry
+                    : undefined;
+                const prevHooks = prevEntry;
+                if (prevEntry && !prevLists) {
+                    // Scope flip: the prior tree at the old defsPath is no longer
+                    // tracked by this manifest — say so rather than dropping it
+                    // silently (cross-scope cleanup is not implemented).
+                    warn(`[${r.harnessName}] defs scope changed (${prevEntry.defsScope} → ${newDefsScope}): previously installed files remain untracked at ${prevEntry.defsPath}`);
+                }
+                // A metrics result whose skippedReason is set NEVER OBSERVED the
+                // hook state ("--no-metrics" means don't touch metrics; unsupported
+                // harnesses too) — `??` alone can't express that because false is a
+                // value. Only an observing run may change the recorded hook state.
+                const metricsObserved = r.metricsResult !== undefined && !r.metricsResult.skippedReason;
                 const harnessEntry = {
                     installedAt: now,
                     setupVersion: version,
                     mcpScope: opts.scope,
                     mcpConfigPath: r.mcpResult.configPath,
-                    defsScope: opts.localDefs ? "local" : "global",
+                    defsScope: newDefsScope,
                     defsPath: opts.localDefs
                         ? join(await findProjectRoot(), "uluops")
                         : r.profile.paths.home,
-                    agents: r.agentsResult?.files ?? [],
-                    commands: r.commandsResult?.files ?? [],
-                    skills: r.skillsResult?.files ?? [],
-                    hooksInstalled: r.metricsResult?.hookConfigured ?? false,
-                    hooksInstalledVersion: r.metricsResult?.hooksInstalledVersion ?? null,
+                    agents: r.agentsResult?.files ?? prevLists?.agents ?? [],
+                    commands: r.commandsResult?.files ?? prevLists?.commands ?? [],
+                    skills: r.skillsResult?.files ?? prevLists?.skills ?? [],
+                    hooksInstalled: metricsObserved
+                        ? (r.metricsResult?.hookConfigured ?? false)
+                        : (prevHooks?.hooksInstalled ?? false),
+                    hooksInstalledVersion: metricsObserved
+                        ? (r.metricsResult?.hooksInstalledVersion ?? null)
+                        : (prevHooks?.hooksInstalledVersion ?? null),
                     partial: r.partial ?? null,
                 };
                 manifest.harnesses[r.harnessName] = harnessEntry;
@@ -247,20 +301,31 @@ export async function runSetup(opts) {
         // per-harness status icons, partial markers, re-run hints, and the
         // aggregate counts in the header. Single-harness path preserves
         // today's Setup-complete banner format inside the same function.
-        await printSetupSummary({
-            results: perHarnessResults,
-            apiKey,
-        });
+        try {
+            await printSetupSummary({
+                results: perHarnessResults,
+                apiKey,
+            });
+        }
+        catch (err) {
+            // A render failure must not invert the run outcome: the install and
+            // manifest write already happened — classifyExit below is the
+            // authority, not the pretty-printer.
+            warn(`Could not render the setup summary: ${err instanceof Error ? err.message : String(err)}`);
+        }
         // Exit-code classifier (spec §7.5 4-tier table). One call, one place.
         // Empty perHarnessResults already short-circuited above with the
         // "nothing to install" message; classifyExit handles defense-in-depth.
-        const exitCode = classifyExit(perHarnessResults);
-        if (exitCode !== 0) {
-            process.exit(exitCode);
-        }
+        exitCode = classifyExit(perHarnessResults);
     }
     finally {
         if (lock)
             await lock.release();
     }
+    // process.exit inside the try would skip the finally and leave the lock
+    // held (the signal handlers are a backstop, not the contract) — classify
+    // inside, exit only after cleanup has run.
+    if (exitCode !== 0) {
+        process.exit(exitCode);
+    }
 }