@uluops/setup 0.6.5 → 0.7.0

package/dist/cli.js

@@ -4,6 +4,7 @@ import chalk from "chalk";
 import { info, printAgentList } from "./lib/display.js";
 import { getVersion } from "./lib/version.js";
 import { resolveHarnessName, listHarnesses, detectHarnesses, HarnessNotTestedError, } from "./harnesses/index.js";
+import { InstallLockHeldError } from "./lib/install-lock.js";
 import { runSetup } from "./commands/setup.js";
 import { runUninstall } from "./commands/uninstall.js";
 import { runVerify } from "./commands/verify.js";
@@ -21,6 +22,8 @@ async function main() {
         .option("--shell", "Write API key export to shell profile", false)
         .option("--with-cli", "Install @uluops/cli globally without prompting")
         .option("--no-cli", "Skip @uluops/cli install without prompting (takes precedence over --with-cli)")
+        .option("--with-agent-metrics-cli", "Install @uluops/agent-metrics globally without prompting")
+        .option("--no-agent-metrics-cli", "Skip @uluops/agent-metrics install without prompting (takes precedence over --with-agent-metrics-cli)")
         .option("--skip-validation", "Accept API key without verifying", false)
         .option("--list", "Show available agents and workflows without installing")
         .option("--verify", "Check existing installation health")
@@ -96,6 +99,8 @@ async function main() {
         shell: opts.shell,
         withCli: opts.withCli,
         cli: opts.cli,
+        withAgentMetricsCli: opts.withAgentMetricsCli,
+        agentMetricsCli: opts.agentMetricsCli,
         skipValidation: opts.skipValidation,
         dryRun: opts.dryRun,
         yes: opts.yes,
@@ -107,6 +112,13 @@ main().catch((err) => {
         console.error(chalk.yellow(`\n  ${err.message}\n`));
         process.exit(1);
     }
+    if (err instanceof InstallLockHeldError) {
+        console.error(chalk.yellow(`\n  ${err.message}\n`));
+        console.error(chalk.dim("  Wait for the other process to finish, or — if it crashed —\n" +
+            "  the lock auto-releases after 30 minutes or when the held\n" +
+            "  PID is detected as no longer running.\n"));
+        process.exit(1);
+    }
     const msg = err instanceof Error ? err.message : String(err);
     console.error(chalk.red(`\n  Error: ${msg}\n`));
     process.exit(1);

package/dist/commands/helpers.d.ts

@@ -4,6 +4,7 @@ import type { AgentsResult } from "../steps/agents.js";
 import type { CommandsResult } from "../steps/commands.js";
 import type { MetricsResult } from "../steps/metrics.js";
 import type { CliExecutor, CliInstallResult } from "../steps/cli.js";
+import type { AgentMetricsCliExecutor, AgentMetricsCliInstallResult } from "../steps/agent-metrics-cli.js";
 import type { HarnessProfile } from "../harnesses/index.js";
 /** Resolve API key via flag, env, file, signup, or interactive prompt. Returns env detection + key. */
 export declare function initContext(opts: {
@@ -54,6 +55,30 @@ export declare function configureCliStep(opts: {
     dryRun: boolean;
     executor?: CliExecutor;
 }): Promise<CliInstallResult | null>;
+/**
+ * Decide whether to install `@uluops/agent-metrics` globally and do it.
+ *
+ * Only meaningful when the SubagentStop hook actually got configured —
+ * otherwise the CLI has no captures to read. Caller gates on
+ * `metricsResult.hookConfigured`.
+ *
+ * Decision matrix mirrors `configureCliStep`:
+ * - `--no-agent-metrics-cli` (opts.agentMetricsCli === false) → skip, no prompt
+ * - `--with-agent-metrics-cli` (opts.withAgentMetricsCli === true) → install, no prompt
+ * - Neither flag + non-interactive (--yes / --api-key / no TTY) → skip
+ * - Neither flag + interactive → prompt (default Y)
+ *
+ * Returns null when the step did not run (skipped). Returns an install result
+ * when an attempt was made, for manifest recording.
+ */
+export declare function configureAgentMetricsCliStep(opts: {
+    withAgentMetricsCli?: boolean;
+    agentMetricsCli?: boolean;
+    yes: boolean;
+    apiKey?: string;
+    dryRun: boolean;
+    executor?: AgentMetricsCliExecutor;
+}): Promise<AgentMetricsCliInstallResult | null>;
 /** Ping tracker and registry health endpoints. */
 export declare function runHealthCheck(opts: {
     skipValidation: boolean;

package/dist/commands/helpers.js

@@ -9,6 +9,7 @@ import { installAgents } from "../steps/agents.js";
 import { installCommands } from "../steps/commands.js";
 import { installMetrics } from "../steps/metrics.js";
 import { installCli, CLI_PACKAGE } from "../steps/cli.js";
+import { installAgentMetricsCli, AGENT_METRICS_PACKAGE, AGENT_METRICS_BIN, } from "../steps/agent-metrics-cli.js";
 import { writeShellExport } from "../steps/shell.js";
 import { probeHookSupport } from "../lib/settings-merger.js";
 import { findProjectRoot, ASSETS_DIR } from "../lib/paths.js";
@@ -213,6 +214,71 @@ export async function configureCliStep(opts) {
     }
     return res;
 }
+/**
+ * Decide whether to install `@uluops/agent-metrics` globally and do it.
+ *
+ * Only meaningful when the SubagentStop hook actually got configured —
+ * otherwise the CLI has no captures to read. Caller gates on
+ * `metricsResult.hookConfigured`.
+ *
+ * Decision matrix mirrors `configureCliStep`:
+ * - `--no-agent-metrics-cli` (opts.agentMetricsCli === false) → skip, no prompt
+ * - `--with-agent-metrics-cli` (opts.withAgentMetricsCli === true) → install, no prompt
+ * - Neither flag + non-interactive (--yes / --api-key / no TTY) → skip
+ * - Neither flag + interactive → prompt (default Y)
+ *
+ * Returns null when the step did not run (skipped). Returns an install result
+ * when an attempt was made, for manifest recording.
+ */
+export async function configureAgentMetricsCliStep(opts) {
+    if (opts.agentMetricsCli === false) {
+        info(chalk.dim(`Skipped global ${AGENT_METRICS_PACKAGE} install (--no-agent-metrics-cli)`));
+        return null;
+    }
+    let shouldInstall;
+    if (opts.withAgentMetricsCli === true) {
+        shouldInstall = true;
+    }
+    else {
+        const nonInteractive = opts.yes || !!opts.apiKey || !process.stdin.isTTY;
+        if (nonInteractive) {
+            info(chalk.dim(`Skipped global ${AGENT_METRICS_PACKAGE} install (non-interactive — pass --with-agent-metrics-cli to install)`));
+            return null;
+        }
+        const { confirm } = await import("@inquirer/prompts");
+        shouldInstall = await confirm({
+            message: `Install ${AGENT_METRICS_PACKAGE} globally (provides the ${chalk.cyan(AGENT_METRICS_BIN)} command for reading captures)?`,
+            default: true,
+        });
+        if (!shouldInstall) {
+            info(chalk.dim(`Skipped global ${AGENT_METRICS_PACKAGE} install`));
+            return null;
+        }
+    }
+    const res = await installAgentMetricsCli({
+        dryRun: opts.dryRun,
+        executor: opts.executor,
+    });
+    if (opts.dryRun && !res.alreadyPresent) {
+        ok(`Would install ${AGENT_METRICS_PACKAGE} globally`);
+        return res;
+    }
+    if (res.alreadyPresent) {
+        ok(`${AGENT_METRICS_PACKAGE} already installed${res.version ? ` (${res.version})` : ""} — no change`);
+        return res;
+    }
+    if (res.installed) {
+        ok(`${AGENT_METRICS_PACKAGE} installed globally${res.version ? ` (${res.version})` : ""}`);
+        return res;
+    }
+    warn(`Could not install ${AGENT_METRICS_PACKAGE} globally — try ${chalk.cyan(`npm install -g ${AGENT_METRICS_PACKAGE}`)} manually`);
+    if (res.error) {
+        const oneLine = res.error.split("\n")[0]?.slice(0, 120) ?? "";
+        if (oneLine)
+            info(chalk.dim(`  ${oneLine}`));
+    }
+    return res;
+}
 /** Ping tracker and registry health endpoints. */
 export async function runHealthCheck(opts) {
     if (!opts.skipValidation && !opts.dryRun) {

package/dist/commands/setup.d.ts

@@ -10,4 +10,6 @@ export declare function runSetup(opts: {
     harness: string;
     withCli?: boolean;
     cli?: boolean;
+    withAgentMetricsCli?: boolean;
+    agentMetricsCli?: boolean;
 }): Promise<void>;

package/dist/commands/setup.js

@@ -5,7 +5,8 @@ import { findProjectRoot } from "../lib/paths.js";
 import { info, printSetupSummary } from "../lib/display.js";
 import { getVersion } from "../lib/version.js";
 import { getProfile } from "../harnesses/index.js";
-import { initContext, checkConflicts, configureMcpStep, installAgentsDefs, installCommandsDefs, configureMetricsStep, configureCliStep, runHealthCheck, configureShell, } from "./helpers.js";
+import { acquireInstallLock, } from "../lib/install-lock.js";
+import { initContext, checkConflicts, configureMcpStep, installAgentsDefs, installCommandsDefs, configureMetricsStep, configureCliStep, configureAgentMetricsCliStep, runHealthCheck, configureShell, } from "./helpers.js";
 export async function runSetup(opts) {
     const version = await getVersion();
     const profile = getProfile(opts.harness);
@@ -20,74 +21,108 @@ export async function runSetup(opts) {
     }
     const { env, apiKey } = await initContext(opts);
     console.log();
-    // Load existing manifest for update detection
-    const existingManifest = await loadManifest();
-    const existingHarness = existingManifest?.harnesses[profile.name];
-    if (existingManifest && existingManifest.version !== version) {
-        info(`Updating ${chalk.dim(existingManifest.version)} → ${chalk.green(version)}`);
-        console.log();
-    }
-    else if (existingHarness) {
-        info(chalk.dim(`Already at v${version} — checking for changes`));
-        console.log();
-    }
-    // Check for conflicts on first install for this harness
-    if (!existingHarness && !opts.yes && !opts.dryRun) {
-        await checkConflicts(profile, opts.localDefs);
-    }
-    const mcpResult = await configureMcpStep(profile, apiKey, opts);
-    const agentsResult = await installAgentsDefs(profile, opts, existingHarness?.agents);
-    const commandsResult = await installCommandsDefs(profile, opts, existingHarness?.commands);
-    const metricsResult = await configureMetricsStep(profile, opts);
-    const cliResult = await configureCliStep({
-        withCli: opts.withCli,
-        cli: opts.cli,
-        yes: opts.yes,
-        apiKey: opts.apiKey,
-        dryRun: opts.dryRun,
-    });
-    await runHealthCheck(opts);
-    const shellModified = await configureShell(env, apiKey, opts);
-    // Save manifest
+    // 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
+    // read-merge-write windows. Released in `finally` below.
+    let lock = null;
     if (!opts.dryRun) {
-        const now = new Date().toISOString();
-        const harnessEntry = {
-            installedAt: now,
-            setupVersion: version,
-            mcpScope: opts.scope,
-            mcpConfigPath: mcpResult.configPath,
-            defsScope: opts.localDefs ? "local" : "global",
-            defsPath: opts.localDefs
-                ? join(await findProjectRoot(), "uluops")
-                : profile.paths.home,
-            agents: agentsResult.files,
-            commands: commandsResult.files,
-            hooksInstalled: metricsResult.hookConfigured,
-            hooksInstalledVersion: metricsResult.hooksInstalledVersion,
-        };
-        const manifest = existingManifest ?? {
-            version,
-            installedAt: now,
-            shellModified: false,
-            harnesses: {},
-        };
-        manifest.version = version;
-        manifest.installedAt = now;
-        manifest.shellModified = shellModified || manifest.shellModified;
-        manifest.harnesses[profile.name] = harnessEntry;
-        // Only flip cliInstalled to true when WE installed it (not when user-installed).
-        // Once true, persist across re-runs so uninstall remains symmetric — until the
-        // user explicitly removes it with --no-cli + uninstall, this manifest owns it.
-        if (cliResult && cliResult.installed && !cliResult.alreadyPresent) {
-            manifest.cliInstalled = true;
-            manifest.cliInstalledVersion = cliResult.version;
+        lock = await acquireInstallLock();
+    }
+    try {
+        // Load existing manifest for update detection
+        const existingManifest = await loadManifest();
+        const existingHarness = existingManifest?.harnesses[profile.name];
+        if (existingManifest && existingManifest.version !== version) {
+            info(`Updating ${chalk.dim(existingManifest.version)} → ${chalk.green(version)}`);
+            console.log();
         }
-        await saveManifest(manifest);
+        else if (existingHarness) {
+            info(chalk.dim(`Already at v${version} — checking for changes`));
+            console.log();
+        }
+        // Check for conflicts on first install for this harness
+        if (!existingHarness && !opts.yes && !opts.dryRun) {
+            await checkConflicts(profile, opts.localDefs);
+        }
+        const mcpResult = await configureMcpStep(profile, apiKey, opts);
+        const agentsResult = await installAgentsDefs(profile, opts, existingHarness?.agents);
+        const commandsResult = await installCommandsDefs(profile, opts, existingHarness?.commands);
+        const metricsResult = await configureMetricsStep(profile, opts);
+        const cliResult = await configureCliStep({
+            withCli: opts.withCli,
+            cli: opts.cli,
+            yes: opts.yes,
+            apiKey: opts.apiKey,
+            dryRun: opts.dryRun,
+        });
+        // Only offer the agent-metrics CLI when the hook itself got configured —
+        // the CLI's purpose is reading captures the hook produces, so without the
+        // hook there's nothing for the CLI to surface.
+        const agentMetricsCliResult = metricsResult.hookConfigured
+            ? await configureAgentMetricsCliStep({
+                withAgentMetricsCli: opts.withAgentMetricsCli,
+                agentMetricsCli: opts.agentMetricsCli,
+                yes: opts.yes,
+                apiKey: opts.apiKey,
+                dryRun: opts.dryRun,
+            })
+            : null;
+        await runHealthCheck(opts);
+        const shellModified = await configureShell(env, apiKey, opts);
+        // Save manifest
+        if (!opts.dryRun) {
+            const now = new Date().toISOString();
+            const harnessEntry = {
+                installedAt: now,
+                setupVersion: version,
+                mcpScope: opts.scope,
+                mcpConfigPath: mcpResult.configPath,
+                defsScope: opts.localDefs ? "local" : "global",
+                defsPath: opts.localDefs
+                    ? join(await findProjectRoot(), "uluops")
+                    : profile.paths.home,
+                agents: agentsResult.files,
+                commands: commandsResult.files,
+                hooksInstalled: metricsResult.hookConfigured,
+                hooksInstalledVersion: metricsResult.hooksInstalledVersion,
+            };
+            const manifest = existingManifest ?? {
+                version,
+                installedAt: now,
+                shellModified: false,
+                harnesses: {},
+            };
+            manifest.version = version;
+            manifest.installedAt = now;
+            manifest.shellModified = shellModified || manifest.shellModified;
+            manifest.harnesses[profile.name] = harnessEntry;
+            // Only flip cliInstalled to true when WE installed it (not when user-installed).
+            // Once true, persist across re-runs so uninstall remains symmetric — until the
+            // user explicitly removes it with --no-cli + uninstall, this manifest owns it.
+            if (cliResult && cliResult.installed && !cliResult.alreadyPresent) {
+                manifest.cliInstalled = true;
+                manifest.cliInstalledVersion = cliResult.version;
+            }
+            // Same ownership rule for agent-metrics CLI — only manifest a global install
+            // we performed ourselves.
+            if (agentMetricsCliResult &&
+                agentMetricsCliResult.installed &&
+                !agentMetricsCliResult.alreadyPresent) {
+                manifest.agentMetricsCliInstalled = true;
+                manifest.agentMetricsCliInstalledVersion = agentMetricsCliResult.version;
+            }
+            await saveManifest(manifest);
+        }
+        await printSetupSummary({
+            profile,
+            agentCount: agentsResult.files.length,
+            commandCount: commandsResult.files.length,
+            apiKey,
+        });
+    }
+    finally {
+        if (lock)
+            await lock.release();
     }
-    await printSetupSummary({
-        profile,
-        agentCount: agentsResult.files.length,
-        commandCount: commandsResult.files.length,
-        apiKey,
-    });
 }

package/dist/commands/uninstall.js

@@ -1,11 +1,13 @@
 import chalk from "chalk";
 import { loadManifest, deleteManifest, validateManifest, } from "../lib/manifest.js";
+import { acquireInstallLock, } from "../lib/install-lock.js";
 import { uninstallMcp } from "../steps/mcp.js";
 import { uninstallAgents } from "../steps/agents.js";
 import { uninstallCommands } from "../steps/commands.js";
 import { removeShellExport } from "../steps/shell.js";
 import { uninstallMetrics } from "../steps/metrics.js";
 import { uninstallCli, CLI_PACKAGE } from "../steps/cli.js";
+import { uninstallAgentMetricsCli, AGENT_METRICS_PACKAGE, } from "../steps/agent-metrics-cli.js";
 import { ok, warn, fail, info } from "../lib/display.js";
 import { getVersion } from "../lib/version.js";
 import { getProfile } from "../harnesses/index.js";
@@ -17,110 +19,140 @@ export async function runUninstall(opts) {
     if (opts.dryRun) {
         info(chalk.dim("(dry run — no changes will be made)\n"));
     }
-    const manifest = await loadManifest();
-    if (!manifest) {
-        warn("No manifest found — nothing to uninstall.");
-        return;
-    }
-    const validation = await validateManifest(manifest);
-    if (!validation.valid) {
-        fail("Manifest references paths that no longer exist:");
-        for (const err of validation.errors)
-            info(`  ${err}`);
-        console.log();
-        info("Uninstall may be incomplete. Proceeding with what's available.");
-        console.log();
-    }
-    if (validation.warnings.length > 0) {
-        for (const w of validation.warnings)
-            warn(w);
-        console.log();
+    // Same lock as runSetup — concurrent setup+uninstall would race the same
+    // shared state. Skipped on dry-run (read-only).
+    let lock = null;
+    if (!opts.dryRun) {
+        lock = await acquireInstallLock();
     }
-    for (const [harnessName, hm] of Object.entries(manifest.harnesses)) {
-        let profile;
-        try {
-            profile = getProfile(harnessName);
-        }
-        catch {
-            warn(`Unknown harness "${harnessName}" in manifest — skipping`);
-            continue;
+    try {
+        const manifest = await loadManifest();
+        if (!manifest) {
+            warn("No manifest found — nothing to uninstall.");
+            return;
         }
-        info(chalk.bold(profile.displayName));
-        if (!opts.dryRun) {
-            const agentCount = await uninstallAgents(hm.agents, hm.defsPath);
-            ok(`Removed ${agentCount} agent(s)`);
+        const validation = await validateManifest(manifest);
+        if (!validation.valid) {
+            fail("Manifest references paths that no longer exist:");
+            for (const err of validation.errors)
+                info(`  ${err}`);
+            console.log();
+            info("Uninstall may be incomplete. Proceeding with what's available.");
+            console.log();
         }
-        else {
-            ok(`Would remove ${hm.agents.length} agent(s)`);
+        if (validation.warnings.length > 0) {
+            for (const w of validation.warnings)
+                warn(w);
+            console.log();
         }
-        if (hm.commands.length > 0) {
+        for (const [harnessName, hm] of Object.entries(manifest.harnesses)) {
+            let profile;
+            try {
+                profile = getProfile(harnessName);
+            }
+            catch {
+                warn(`Unknown harness "${harnessName}" in manifest — skipping`);
+                continue;
+            }
+            info(chalk.bold(profile.displayName));
             if (!opts.dryRun) {
-                const cmdCount = await uninstallCommands(hm.commands, hm.defsPath);
-                ok(`Removed ${cmdCount} command(s)`);
+                const agentCount = await uninstallAgents(hm.agents, hm.defsPath);
+                ok(`Removed ${agentCount} agent(s)`);
             }
             else {
-                ok(`Would remove ${hm.commands.length} command(s)`);
-            }
-        }
-        if (!opts.dryRun) {
-            try {
-                await uninstallMcp(profile, hm.mcpConfigPath);
-                ok(`Removed MCP servers from ${hm.mcpConfigPath}`);
+                ok(`Would remove ${hm.agents.length} agent(s)`);
             }
-            catch {
-                warn(`Could not remove MCP servers from ${hm.mcpConfigPath}`);
+            if (hm.commands.length > 0) {
+                if (!opts.dryRun) {
+                    const cmdCount = await uninstallCommands(hm.commands, hm.defsPath);
+                    ok(`Removed ${cmdCount} command(s)`);
+                }
+                else {
+                    ok(`Would remove ${hm.commands.length} command(s)`);
+                }
             }
-        }
-        else {
-            ok(`Would remove MCP servers from ${hm.mcpConfigPath}`);
-        }
-        if (hm.hooksInstalled) {
             if (!opts.dryRun) {
-                await uninstallMetrics(profile, false);
-                ok("Removed agent-metrics hook and tool files");
+                try {
+                    await uninstallMcp(profile, hm.mcpConfigPath);
+                    ok(`Removed MCP servers from ${hm.mcpConfigPath}`);
+                }
+                catch {
+                    warn(`Could not remove MCP servers from ${hm.mcpConfigPath}`);
+                }
             }
             else {
-                ok("Would remove agent-metrics hook and tool files");
+                ok(`Would remove MCP servers from ${hm.mcpConfigPath}`);
             }
+            if (hm.hooksInstalled) {
+                if (!opts.dryRun) {
+                    await uninstallMetrics(profile, false);
+                    ok("Removed agent-metrics hook and tool files");
+                }
+                else {
+                    ok("Would remove agent-metrics hook and tool files");
+                }
+            }
+            console.log();
         }
-        console.log();
-    }
-    // Remove global @uluops/cli if WE installed it (per manifest).
-    // We never auto-remove a user-installed CLI — manifest.cliInstalled gates this.
-    if (manifest.cliInstalled) {
-        const res = await uninstallCli({ dryRun: opts.dryRun });
-        if (opts.dryRun) {
-            ok(`Would remove ${CLI_PACKAGE} (global)`);
-        }
-        else if (res.removed) {
-            ok(`Removed ${CLI_PACKAGE} (global)`);
+        // Remove global @uluops/cli if WE installed it (per manifest).
+        // We never auto-remove a user-installed CLI — manifest.cliInstalled gates this.
+        if (manifest.cliInstalled) {
+            const res = await uninstallCli({ dryRun: opts.dryRun });
+            if (opts.dryRun) {
+                ok(`Would remove ${CLI_PACKAGE} (global)`);
+            }
+            else if (res.removed) {
+                ok(`Removed ${CLI_PACKAGE} (global)`);
+            }
+            else {
+                warn(`Could not remove ${CLI_PACKAGE} (global) — try \`npm uninstall -g ${CLI_PACKAGE}\` manually`);
+                if (res.error) {
+                    const oneLine = res.error.split("\n")[0]?.slice(0, 120) ?? "";
+                    if (oneLine)
+                        info(`  ${oneLine}`);
+                }
+            }
         }
-        else {
-            warn(`Could not remove ${CLI_PACKAGE} (global) — try \`npm uninstall -g ${CLI_PACKAGE}\` manually`);
-            if (res.error) {
-                const oneLine = res.error.split("\n")[0]?.slice(0, 120) ?? "";
-                if (oneLine)
-                    info(`  ${oneLine}`);
+        // Same ownership rule for the agent-metrics CLI.
+        if (manifest.agentMetricsCliInstalled) {
+            const res = await uninstallAgentMetricsCli({ dryRun: opts.dryRun });
+            if (opts.dryRun) {
+                ok(`Would remove ${AGENT_METRICS_PACKAGE} (global)`);
+            }
+            else if (res.removed) {
+                ok(`Removed ${AGENT_METRICS_PACKAGE} (global)`);
+            }
+            else {
+                warn(`Could not remove ${AGENT_METRICS_PACKAGE} (global) — try \`npm uninstall -g ${AGENT_METRICS_PACKAGE}\` manually`);
+                if (res.error) {
+                    const oneLine = res.error.split("\n")[0]?.slice(0, 120) ?? "";
+                    if (oneLine)
+                        info(`  ${oneLine}`);
+                }
             }
         }
-    }
-    // Remove shell export
-    if (manifest.shellModified) {
-        const { getShellProfile } = await import("../lib/paths.js");
-        const shellProfile = getShellProfile();
-        if (shellProfile && !opts.dryRun) {
-            await removeShellExport(shellProfile.path);
-            ok(`Removed export from ${shellProfile.path}`);
+        // Remove shell export
+        if (manifest.shellModified) {
+            const { getShellProfile } = await import("../lib/paths.js");
+            const shellProfile = getShellProfile();
+            if (shellProfile && !opts.dryRun) {
+                await removeShellExport(shellProfile.path);
+                ok(`Removed export from ${shellProfile.path}`);
+            }
+            else if (shellProfile) {
+                ok(`Would remove export from ${shellProfile.path}`);
+            }
         }
-        else if (shellProfile) {
-            ok(`Would remove export from ${shellProfile.path}`);
+        if (!opts.dryRun) {
+            await deleteManifest();
+            ok("Manifest deleted");
         }
+        console.log();
+        info("UluOps has been removed. Restart your harness to complete.");
+        console.log();
     }
-    if (!opts.dryRun) {
-        await deleteManifest();
-        ok("Manifest deleted");
+    finally {
+        if (lock)
+            await lock.release();
     }
-    console.log();
-    info("UluOps has been removed. Restart your harness to complete.");
-    console.log();
 }

package/dist/lib/install-lock.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Process-level mutex for uluops-setup install/uninstall operations.
+ *
+ * Solves the TOCTOU race surfaced by ship-pipeline code-auditor (AF-006):
+ * two concurrent `npx @uluops/setup` invocations both read shared state,
+ * each merges and writes its own version, second write clobbers first.
+ *
+ * Uses `mkdir` atomicity (POSIX + NTFS, ~50 years stable) instead of a
+ * dependency. Meta file inside the lock dir carries PID + hostname +
+ * start timestamp so stale locks can be reclaimed automatically.
+ *
+ * Scope is intentionally narrow: this protects setup-vs-setup races only.
+ * Setup-vs-harness races (the harness CLI writing to its own settings file
+ * concurrently) require a separate compare-and-swap design.
+ */
+export interface LockHandle {
+    release(): Promise<void>;
+}
+export interface AcquireOptions {
+    /** Max time a held lock is considered valid before being reclaimed (default 30 min). */
+    maxAgeMs?: number;
+    /** How long to wait for a held lock before failing (default 0). */
+    waitMs?: number;
+    /** Override the lock directory (test seam). */
+    lockDir?: string;
+}
+/** Thrown when another process holds the lock and waiting has exhausted. */
+export declare class InstallLockHeldError extends Error {
+    readonly holder: {
+        pid: number;
+        hostname: string;
+        ageMs: number;
+    };
+    constructor(holder: {
+        pid: number;
+        hostname: string;
+        ageMs: number;
+    });
+}
+/**
+ * Acquire the install lock. Resolves with a handle whose `release()` must be
+ * called in a `finally` block. Throws `InstallLockHeldError` if the lock is
+ * held by a live process and waiting (if any) has exhausted.
+ */
+export declare function acquireInstallLock(opts?: AcquireOptions): Promise<LockHandle>;
+/** Test-only: detach handlers and clear lock-dir tracking so tests can rebind. */
+export declare function __resetSignalHandlersForTesting(): void;

package/dist/lib/install-lock.js

@@ -0,0 +1,241 @@
+/**
+ * Process-level mutex for uluops-setup install/uninstall operations.
+ *
+ * Solves the TOCTOU race surfaced by ship-pipeline code-auditor (AF-006):
+ * two concurrent `npx @uluops/setup` invocations both read shared state,
+ * each merges and writes its own version, second write clobbers first.
+ *
+ * Uses `mkdir` atomicity (POSIX + NTFS, ~50 years stable) instead of a
+ * dependency. Meta file inside the lock dir carries PID + hostname +
+ * start timestamp so stale locks can be reclaimed automatically.
+ *
+ * Scope is intentionally narrow: this protects setup-vs-setup races only.
+ * Setup-vs-harness races (the harness CLI writing to its own settings file
+ * concurrently) require a separate compare-and-swap design.
+ */
+import { mkdir, readFile, rm, unlink, writeFile, } from "node:fs/promises";
+import { rmSync } from "node:fs";
+import { hostname } from "node:os";
+import { join } from "node:path";
+import { getInstallLockDir } from "./paths.js";
+const META_FILENAME = "meta.json";
+const DEFAULT_MAX_AGE_MS = 30 * 60 * 1000; // 30 min
+const DEFAULT_WAIT_MS = 0;
+const POLL_INTERVAL_MS = 500;
+/** Thrown when another process holds the lock and waiting has exhausted. */
+export class InstallLockHeldError extends Error {
+    holder;
+    constructor(holder) {
+        super(`Another uluops-setup process is already running (PID ${holder.pid} on ${holder.hostname}, started ${Math.round(holder.ageMs / 1000)}s ago).`);
+        this.holder = holder;
+        this.name = "InstallLockHeldError";
+    }
+}
+/**
+ * Acquire the install lock. Resolves with a handle whose `release()` must be
+ * called in a `finally` block. Throws `InstallLockHeldError` if the lock is
+ * held by a live process and waiting (if any) has exhausted.
+ */
+export async function acquireInstallLock(opts = {}) {
+    const lockDir = opts.lockDir ?? getInstallLockDir();
+    const maxAgeMs = opts.maxAgeMs ?? DEFAULT_MAX_AGE_MS;
+    const waitMs = opts.waitMs ?? DEFAULT_WAIT_MS;
+    const deadline = Date.now() + waitMs;
+    // First try (and one retry after stale-lock reclaim).
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            await mkdir(lockDir, { recursive: false });
+            // Won the race. Write metadata, register handlers, return handle.
+            const meta = {
+                pid: process.pid,
+                hostname: hostname(),
+                startedAt: Date.now(),
+            };
+            await writeFile(join(lockDir, META_FILENAME), JSON.stringify(meta));
+            return registerHandle(lockDir);
+        }
+        catch (err) {
+            const code = err.code;
+            if (code !== "EEXIST")
+                throw err;
+        }
+        // Lock exists. Inspect it.
+        const verdict = await inspectHeldLock(lockDir, maxAgeMs);
+        if (verdict.kind === "stale") {
+            // Reclaim and retry once.
+            await rm(lockDir, { recursive: true, force: true });
+            continue;
+        }
+        // Live holder. Optionally wait.
+        if (Date.now() < deadline) {
+            while (Date.now() < deadline) {
+                await sleep(POLL_INTERVAL_MS);
+                const recheck = await inspectHeldLock(lockDir, maxAgeMs);
+                if (recheck.kind === "stale") {
+                    // Holder released or died during wait.
+                    break;
+                }
+            }
+            // Retry once after wait.
+            continue;
+        }
+        throw new InstallLockHeldError({
+            pid: verdict.meta.pid,
+            hostname: verdict.meta.hostname,
+            ageMs: Date.now() - verdict.meta.startedAt,
+        });
+    }
+    // Both attempts exhausted without acquiring.
+    throw new InstallLockHeldError({ pid: -1, hostname: "unknown", ageMs: 0 });
+}
+async function inspectHeldLock(lockDir, maxAgeMs) {
+    const metaPath = join(lockDir, META_FILENAME);
+    let raw;
+    try {
+        raw = await readFile(metaPath, "utf-8");
+    }
+    catch {
+        // Lock dir exists but meta missing or unreadable — treat as stale.
+        return { kind: "stale", reason: "missing-meta" };
+    }
+    let meta;
+    try {
+        const parsed = JSON.parse(raw);
+        if (!isLockMeta(parsed)) {
+            return { kind: "stale", reason: "malformed-meta" };
+        }
+        meta = parsed;
+    }
+    catch {
+        return { kind: "stale", reason: "invalid-json" };
+    }
+    if (Date.now() - meta.startedAt > maxAgeMs) {
+        return { kind: "stale", reason: "timeout" };
+    }
+    // Same host: probe the PID. Different host: trust the meta until timeout.
+    if (meta.hostname === hostname()) {
+        if (!isPidAlive(meta.pid)) {
+            return { kind: "stale", reason: "dead-pid" };
+        }
+    }
+    return { kind: "live", meta };
+}
+function isLockMeta(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const v = value;
+    return (typeof v["pid"] === "number" &&
+        typeof v["hostname"] === "string" &&
+        typeof v["startedAt"] === "number");
+}
+function isPidAlive(pid) {
+    if (pid <= 0 || !Number.isInteger(pid))
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ESRCH")
+            return false;
+        if (code === "EPERM")
+            return true; // exists but we lack permission
+        return false;
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+// ─── Signal handler registry ─────────────────────────────────────────────────
+//
+// All active lock dirs are tracked at module scope so signal handlers can
+// release every held lock synchronously before re-raising the signal.
+const heldLockDirs = new Set();
+let signalHandlersInstalled = false;
+let installedSigintHandler = null;
+let installedSigtermHandler = null;
+let installedUncaughtHandler = null;
+function registerHandle(lockDir) {
+    heldLockDirs.add(lockDir);
+    ensureSignalHandlers();
+    let released = false;
+    return {
+        async release() {
+            if (released)
+                return;
+            released = true;
+            heldLockDirs.delete(lockDir);
+            try {
+                await unlink(join(lockDir, META_FILENAME));
+            }
+            catch {
+                // Already gone or unreadable; proceed to rmdir.
+            }
+            try {
+                await rm(lockDir, { recursive: true, force: true });
+            }
+            catch {
+                // Best-effort; do not throw from release().
+            }
+        },
+    };
+}
+function ensureSignalHandlers() {
+    if (signalHandlersInstalled)
+        return;
+    signalHandlersInstalled = true;
+    const cleanup = (signal) => {
+        for (const dir of heldLockDirs) {
+            try {
+                rmSync(dir, { recursive: true, force: true });
+            }
+            catch {
+                // Best-effort.
+            }
+        }
+        heldLockDirs.clear();
+        // Re-raise the signal so default Node behavior runs (exit with the
+        // conventional 128 + signum code). Listeners were already triggered.
+        process.removeListener(signal, cleanup);
+        process.kill(process.pid, signal);
+    };
+    const uncaught = (err) => {
+        for (const dir of heldLockDirs) {
+            try {
+                rmSync(dir, { recursive: true, force: true });
+            }
+            catch {
+                // Best-effort.
+            }
+        }
+        heldLockDirs.clear();
+        // Restore default behavior: print stack and exit 1.
+        console.error(err);
+        process.exit(1);
+    };
+    installedSigintHandler = cleanup;
+    installedSigtermHandler = cleanup;
+    installedUncaughtHandler = uncaught;
+    process.on("SIGINT", cleanup);
+    process.on("SIGTERM", cleanup);
+    process.on("uncaughtException", uncaught);
+}
+// ─── Test seams ──────────────────────────────────────────────────────────────
+/** Test-only: detach handlers and clear lock-dir tracking so tests can rebind. */
+export function __resetSignalHandlersForTesting() {
+    if (installedSigintHandler) {
+        process.removeListener("SIGINT", installedSigintHandler);
+        installedSigintHandler = null;
+    }
+    if (installedSigtermHandler) {
+        process.removeListener("SIGTERM", installedSigtermHandler);
+        installedSigtermHandler = null;
+    }
+    if (installedUncaughtHandler) {
+        process.removeListener("uncaughtException", installedUncaughtHandler);
+        installedUncaughtHandler = null;
+    }
+    signalHandlersInstalled = false;
+    heldLockDirs.clear();
+}

package/dist/lib/manifest.d.ts

@@ -45,6 +45,14 @@ export interface Manifest {
     cliInstalled?: boolean;
     /** Version reported by `ulu --version` at install time, for drift detection. */
     cliInstalledVersion?: string | null;
+    /**
+     * Tracks whether `@uluops/agent-metrics` was installed globally by this
+     * setup run. Same ownership semantics as `cliInstalled` — uninstall only
+     * removes the global package when this is true.
+     */
+    agentMetricsCliInstalled?: boolean;
+    /** Version reported by `agent-metrics --version` at install time. */
+    agentMetricsCliInstalledVersion?: string | null;
     contentHash?: string;
 }
 export interface ManifestValidationResult {

package/dist/lib/paths.d.ts

@@ -15,6 +15,8 @@ export declare function getLocalMcpPath(): Promise<string>;
 export declare function getUluopsDir(): string;
 /** Return the path to the UluOps install manifest file (new location). */
 export declare function getManifestPath(): string;
+/** Return the directory used as a process-level install/uninstall mutex. */
+export declare function getInstallLockDir(): string;
 /** Return the legacy manifest path for migration. */
 export declare function getLegacyManifestPath(): string;
 /**

package/dist/lib/paths.js

@@ -90,6 +90,10 @@ export function getUluopsDir() {
 export function getManifestPath() {
     return join(getUluopsDir(), "manifest.json");
 }
+/** Return the directory used as a process-level install/uninstall mutex. */
+export function getInstallLockDir() {
+    return join(getUluopsDir(), "install.lock");
+}
 /** Return the legacy manifest path for migration. */
 export function getLegacyManifestPath() {
     return join(getClaudeHome(), "uluops-manifest.json");

package/dist/steps/agent-metrics-cli.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Global install of the @uluops/agent-metrics CLI.
+ *
+ * Companion to src/steps/cli.ts (which handles @uluops/cli). The agent-metrics
+ * package is ALREADY copied into the harness tree by src/steps/metrics.ts
+ * (so the SubagentStop hook can invoke dist/hook.js at a fixed path), but
+ * that copy never goes on PATH. This step makes the `agent-metrics` command
+ * available to users who want to inspect the captures the hook produces.
+ *
+ * Gated externally by the helper in src/commands/helpers.ts — only invoked
+ * when the metrics hook actually got configured.
+ */
+export declare const AGENT_METRICS_PACKAGE = "@uluops/agent-metrics";
+export declare const AGENT_METRICS_BIN = "agent-metrics";
+export interface AgentMetricsCliExecutor {
+    /** Returns the installed CLI version, or null if `agent-metrics` is not on PATH or fails to run. */
+    detect: () => string | null;
+    /** Best-effort `npm install -g`. Returns ok + captured error for surface display. */
+    install: () => {
+        ok: boolean;
+        error?: string;
+    };
+    /** Best-effort `npm uninstall -g`. Returns ok + captured error. */
+    uninstall: () => {
+        ok: boolean;
+        error?: string;
+    };
+}
+/** Default executor — shells out to `agent-metrics` and `npm`. */
+export declare const defaultAgentMetricsExecutor: AgentMetricsCliExecutor;
+export interface AgentMetricsCliInstallResult {
+    /** `agent-metrics` is on PATH after this step, regardless of how it got there. */
+    installed: boolean;
+    /** Version string from `agent-metrics --version`, if detectable. */
+    version: string | null;
+    /** True when `agent-metrics` was already on PATH before we did anything. */
+    alreadyPresent: boolean;
+    /** Set when our `npm install -g` attempt failed; caller decides how to surface. */
+    error?: string;
+}
+/**
+ * Install `@uluops/agent-metrics` globally if not already present.
+ *
+ * Mirrors `installCli` semantics — never aborts the parent setup flow:
+ * - If `agent-metrics` is already on PATH, returns `{ installed: true, alreadyPresent: true }` without touching npm.
+ * - If `npm install -g` fails, returns `{ installed: false, error }` so the caller can warn-and-continue.
+ * - In dryRun mode, no executor calls happen.
+ */
+export declare function installAgentMetricsCli(opts: {
+    dryRun: boolean;
+    executor?: AgentMetricsCliExecutor;
+}): Promise<AgentMetricsCliInstallResult>;
+export interface AgentMetricsCliUninstallResult {
+    removed: boolean;
+    error?: string;
+}
+/**
+ * Uninstall `@uluops/agent-metrics` globally. Best-effort: if the package
+ * isn't there, npm exits non-zero on some platforms — we treat that as success.
+ */
+export declare function uninstallAgentMetricsCli(opts: {
+    dryRun: boolean;
+    executor?: AgentMetricsCliExecutor;
+}): Promise<AgentMetricsCliUninstallResult>;

package/dist/steps/agent-metrics-cli.js

@@ -0,0 +1,101 @@
+import { spawnSync } from "node:child_process";
+/**
+ * Global install of the @uluops/agent-metrics CLI.
+ *
+ * Companion to src/steps/cli.ts (which handles @uluops/cli). The agent-metrics
+ * package is ALREADY copied into the harness tree by src/steps/metrics.ts
+ * (so the SubagentStop hook can invoke dist/hook.js at a fixed path), but
+ * that copy never goes on PATH. This step makes the `agent-metrics` command
+ * available to users who want to inspect the captures the hook produces.
+ *
+ * Gated externally by the helper in src/commands/helpers.ts — only invoked
+ * when the metrics hook actually got configured.
+ */
+export const AGENT_METRICS_PACKAGE = "@uluops/agent-metrics";
+export const AGENT_METRICS_BIN = "agent-metrics";
+/** Default executor — shells out to `agent-metrics` and `npm`. */
+export const defaultAgentMetricsExecutor = {
+    detect: () => {
+        const r = spawnSync(AGENT_METRICS_BIN, ["--version"], {
+            encoding: "utf-8",
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        if (r.status !== 0 || !r.stdout)
+            return null;
+        return r.stdout.trim() || null;
+    },
+    install: () => {
+        const r = spawnSync("npm", ["install", "-g", AGENT_METRICS_PACKAGE], {
+            encoding: "utf-8",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        if (r.status === 0)
+            return { ok: true };
+        const stderr = (r.stderr ?? "").toString().trim();
+        const stdout = (r.stdout ?? "").toString().trim();
+        return { ok: false, error: stderr || stdout || `exit ${r.status}` };
+    },
+    uninstall: () => {
+        const r = spawnSync("npm", ["uninstall", "-g", AGENT_METRICS_PACKAGE], {
+            encoding: "utf-8",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        if (r.status === 0)
+            return { ok: true };
+        const stderr = (r.stderr ?? "").toString().trim();
+        const stdout = (r.stdout ?? "").toString().trim();
+        return { ok: false, error: stderr || stdout || `exit ${r.status}` };
+    },
+};
+/**
+ * Install `@uluops/agent-metrics` globally if not already present.
+ *
+ * Mirrors `installCli` semantics — never aborts the parent setup flow:
+ * - If `agent-metrics` is already on PATH, returns `{ installed: true, alreadyPresent: true }` without touching npm.
+ * - If `npm install -g` fails, returns `{ installed: false, error }` so the caller can warn-and-continue.
+ * - In dryRun mode, no executor calls happen.
+ */
+export async function installAgentMetricsCli(opts) {
+    const executor = opts.executor ?? defaultAgentMetricsExecutor;
+    const existing = executor.detect();
+    if (existing !== null) {
+        return { installed: true, version: existing, alreadyPresent: true };
+    }
+    if (opts.dryRun) {
+        return { installed: false, version: null, alreadyPresent: false };
+    }
+    const res = executor.install();
+    if (!res.ok) {
+        return {
+            installed: false,
+            version: null,
+            alreadyPresent: false,
+            error: res.error,
+        };
+    }
+    const after = executor.detect();
+    return {
+        installed: after !== null,
+        version: after,
+        alreadyPresent: false,
+    };
+}
+/**
+ * Uninstall `@uluops/agent-metrics` globally. Best-effort: if the package
+ * isn't there, npm exits non-zero on some platforms — we treat that as success.
+ */
+export async function uninstallAgentMetricsCli(opts) {
+    const executor = opts.executor ?? defaultAgentMetricsExecutor;
+    if (opts.dryRun)
+        return { removed: true };
+    const before = executor.detect();
+    if (before === null)
+        return { removed: true };
+    const res = executor.uninstall();
+    if (res.ok)
+        return { removed: true };
+    const after = executor.detect();
+    if (after === null)
+        return { removed: true };
+    return { removed: false, error: res.error };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uluops/setup",
-  "version": "0.6.5",
+  "version": "0.7.0",
   "description": "Zero-friction installer for UluOps agentic harnesses",
   "license": "MIT",
   "repository": {