@uluops/setup 0.6.5 → 0.8.1

package/dist/lib/json-guards.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Narrow guards for JSON responses from the UluOps API.
+ *
+ * Centralised so the same envelope shape (`{ data: { ... } }`) is decoded
+ * consistently across call sites (`steps/auth.ts`, `steps/verify.ts`,
+ * `steps/signup.ts`). Each guard returns `null` on absent/wrong-typed fields
+ * and throws a plain `Error` only when the top-level body shape is so wrong
+ * that proceeding would silently coerce garbage into a typed result.
+ *
+ * Why plain `Error`, not `TypeError`: call sites translate `TypeError` into
+ * "Can't reach api.uluops.ai" (fetch's network-failure shape). A `TypeError`
+ * here would be misclassified as a network outage.
+ */
+/**
+ * Narrow `{ data: { email: string } }` from an unknown response body.
+ * Returns the email string when present and well-typed, null otherwise.
+ * Throws when `body` is not an object at all — that indicates the endpoint
+ * is no longer the one we expect (HTML error page, redirect to a captive
+ * portal, schema breakage) and should surface to the user rather than be
+ * papered over as "logged in with no email."
+ */
+export declare function extractEmail(body: unknown): string | null;

package/dist/lib/json-guards.js

@@ -0,0 +1,33 @@
+/**
+ * Narrow guards for JSON responses from the UluOps API.
+ *
+ * Centralised so the same envelope shape (`{ data: { ... } }`) is decoded
+ * consistently across call sites (`steps/auth.ts`, `steps/verify.ts`,
+ * `steps/signup.ts`). Each guard returns `null` on absent/wrong-typed fields
+ * and throws a plain `Error` only when the top-level body shape is so wrong
+ * that proceeding would silently coerce garbage into a typed result.
+ *
+ * Why plain `Error`, not `TypeError`: call sites translate `TypeError` into
+ * "Can't reach api.uluops.ai" (fetch's network-failure shape). A `TypeError`
+ * here would be misclassified as a network outage.
+ */
+/**
+ * Narrow `{ data: { email: string } }` from an unknown response body.
+ * Returns the email string when present and well-typed, null otherwise.
+ * Throws when `body` is not an object at all — that indicates the endpoint
+ * is no longer the one we expect (HTML error page, redirect to a captive
+ * portal, schema breakage) and should surface to the user rather than be
+ * papered over as "logged in with no email."
+ */
+export function extractEmail(body) {
+    if (typeof body !== "object" || body === null) {
+        throw new Error("API returned an unexpected response shape (not an object). The endpoint may have changed — try --skip-validation to continue offline.");
+    }
+    const data = body.data;
+    if (data === undefined || data === null)
+        return null;
+    if (typeof data !== "object")
+        return null;
+    const email = data.email;
+    return typeof email === "string" ? email : null;
+}

package/dist/lib/manifest.d.ts

@@ -11,6 +11,14 @@
  * assumption is documented in the schema, not the comments.
  */
 export type HarnessInstanceKey = string;
+/**
+ * Names of per-harness pipeline steps that can throw before producing a
+ * complete result. Recorded in `HarnessManifest.partial` so verify can warn
+ * and re-runs can re-prompt conflicts (spec §7.6.3). `configureMcpStep` is
+ * NOT in this set — an MCP throw produces no manifest entry at all because
+ * the entry depends on the MCP-derived `mcpConfigPath`.
+ */
+export type PartialStep = "agents" | "commands" | "skills" | "metrics";
 /** Per-harness installation state. */
 export interface HarnessManifest {
     installedAt: string;
@@ -21,6 +29,7 @@ export interface HarnessManifest {
     defsPath: string;
     agents: string[];
     commands: string[];
+    skills?: string[];
     hooksInstalled: boolean;
     /**
      * Version of @uluops/agent-metrics whose dist/ was copied into the harness tree.
@@ -29,6 +38,17 @@ export interface HarnessManifest {
      * the shared version ledger across the setup↔agent-metrics seam.
      */
     hooksInstalledVersion?: string | null;
+    /**
+     * When non-null, names the per-harness pipeline step that threw before
+     * producing a complete result. Earlier steps' file lists are accurate;
+     * later steps were never attempted. Verify surfaces this as a WARNING.
+     * Re-run treats a partial entry as "checkConflicts must run again" (the
+     * user never confirmed it on the failing run — spec §7.6.5).
+     *
+     * Absent (undefined) on manifests written by pre-multi-target versions —
+     * those harnesses are assumed fully installed.
+     */
+    partial?: PartialStep | null;
 }
 /** Top-level manifest with per-harness entries. */
 export interface Manifest {
@@ -45,6 +65,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/manifest.js

@@ -13,8 +13,15 @@ function isNewManifest(obj) {
         typeof m["harnesses"] !== "object" ||
         m["harnesses"] === null)
         return false;
-    // Validate at least one harness entry has required fields
+    // An on-disk manifest must reference at least one harness installation.
+    // The empty-harnesses case used to pass vacuously (the for-loop iterated
+    // zero times), letting a truncated `{...harnesses:{}}` file masquerade as
+    // valid — and a subsequent uninstall would then iterate zero harnesses,
+    // delete the manifest, and report success while leaving every MCP config,
+    // agent, hook, and shell export in place.
     const harnesses = m["harnesses"];
+    if (Object.keys(harnesses).length === 0)
+        return false;
     for (const h of Object.values(harnesses)) {
         if (typeof h !== "object" || h === null)
             return false;
@@ -23,6 +30,14 @@ function isNewManifest(obj) {
             return false;
         if (!Array.isArray(hm["agents"]) || !Array.isArray(hm["commands"]))
             return false;
+        if ("skills" in hm && !Array.isArray(hm["skills"]))
+            return false;
+        if ("partial" in hm) {
+            const p = hm["partial"];
+            if (p !== null && p !== "agents" && p !== "commands" && p !== "skills" && p !== "metrics") {
+                return false;
+            }
+        }
     }
     return true;
 }
@@ -83,20 +98,54 @@ export async function validateManifest(manifest) {
                 warnings.push(`[${harnessName}] Command files missing from disk: ${missing.join(", ")}`);
             }
         }
+        if ((hm.skills?.length ?? 0) > 0 && defsExists) {
+            const missing = await findMissingFiles(hm.defsPath, "skills", hm.skills ?? []);
+            if (missing.length > 0) {
+                warnings.push(`[${harnessName}] Skill files missing from disk: ${missing.join(", ")}`);
+            }
+        }
     }
-    const manifestPath = getManifestPath();
-    try {
-        const raw = await readFile(manifestPath, "utf-8");
-        const parsed = JSON.parse(raw);
-        const { contentHash: storedHash, ...withoutHash } = parsed;
-        const canonical = JSON.stringify(withoutHash, null, 2) + "\n";
-        const currentHash = fileHash(canonical);
-        if (storedHash && storedHash !== currentHash) {
-            warnings.push("Manifest file has been modified since installation — content hash mismatch");
+    // Hash verification reads whichever manifest file actually exists. The
+    // previous implementation hardcoded the new path, which produced a false
+    // "Cannot read manifest file to verify content hash" warning on every
+    // uninstall after `loadManifest` migrated a legacy manifest in memory
+    // without writing it back to the new location. Silently skip the hash
+    // check when no manifest is on disk in either location (in-memory-only
+    // manifest, or both locations missing).
+    let raw = null;
+    for (const candidate of [getManifestPath(), getLegacyManifestPath()]) {
+        try {
+            raw = await readFile(candidate, "utf-8");
+            break;
+        }
+        catch {
+            // Try next candidate
         }
     }
-    catch {
-        warnings.push("Cannot read manifest file to verify content hash");
+    if (raw !== null) {
+        try {
+            const parsed = JSON.parse(raw);
+            const { contentHash: storedHash, ...withoutHash } = parsed;
+            const canonical = JSON.stringify(withoutHash, null, 2) + "\n";
+            const currentHash = fileHash(canonical);
+            // Typeof check rather than truthiness — a malformed manifest with
+            // `contentHash: 0`, `contentHash: false`, `contentHash: ""`, or no
+            // contentHash key at all would all evaluate `storedHash && ...` to
+            // false and silently skip tamper detection. Only a missing-key
+            // (undefined) manifest is legitimately exempt (legacy / pre-hash);
+            // a present-but-not-a-string value is suspect and should warn.
+            if (typeof storedHash === "string") {
+                if (storedHash !== currentHash) {
+                    warnings.push("Manifest file has been modified since installation — content hash mismatch");
+                }
+            }
+            else if (storedHash !== undefined) {
+                warnings.push(`Manifest contentHash has wrong type (${typeof storedHash}); tamper detection skipped`);
+            }
+        }
+        catch {
+            warnings.push("Manifest file is unparseable JSON");
+        }
     }
     return { valid: errors.length === 0, errors, warnings };
 }

package/dist/lib/paths.d.ts

@@ -15,25 +15,10 @@ 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;
-/**
- * Return the backup directory for a harness's **config** files.
- *
- * Scope is deliberately narrow: this directory holds copies of mutable
- * user-owned config surfaces (the MCP config file, the shell profile),
- * NOT vendor-owned tool files in `~/.claude/tools/agent-metrics/`. Tool
- * files are treated as disposable — they can be regenerated by re-running
- * setup, and the source of truth lives in the npm-installed
- * `@uluops/agent-metrics` package. Backing them up would require a
- * different ritual (versioned snapshots tied to the manifest's
- * hooksInstalledVersion) and is not provided here.
- *
- * Renaming this to `getConfigBackupDir` would be more honest but is a
- * public surface change deferred until we have a tool-file backup to
- * disambiguate against.
- */
-export declare function getBackupDir(harnessName: string): string;
 /** Detect the user's shell and return its name and profile path, or null if unsupported. */
 export declare function getShellProfile(): {
     shell: string;

package/dist/lib/paths.js

@@ -90,29 +90,14 @@ 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");
 }
-/**
- * Return the backup directory for a harness's **config** files.
- *
- * Scope is deliberately narrow: this directory holds copies of mutable
- * user-owned config surfaces (the MCP config file, the shell profile),
- * NOT vendor-owned tool files in `~/.claude/tools/agent-metrics/`. Tool
- * files are treated as disposable — they can be regenerated by re-running
- * setup, and the source of truth lives in the npm-installed
- * `@uluops/agent-metrics` package. Backing them up would require a
- * different ritual (versioned snapshots tied to the manifest's
- * hooksInstalledVersion) and is not provided here.
- *
- * Renaming this to `getConfigBackupDir` would be more honest but is a
- * public surface change deferred until we have a tool-file backup to
- * disambiguate against.
- */
-export function getBackupDir(harnessName) {
-    return join(getUluopsDir(), "backups", harnessName);
-}
 /** Detect the user's shell and return its name and profile path, or null if unsupported. */
 export function getShellProfile() {
     const shell = process.env["SHELL"] ?? "";

package/dist/lib/settings-merger.js

@@ -82,7 +82,9 @@ export async function readSettings(path) {
  * Write settings back to file with stable formatting.
  */
 export async function writeSettings(path, settings) {
-    await atomicWrite(path, JSON.stringify(settings, null, 2) + "\n");
+    await atomicWrite(path, JSON.stringify(settings, null, 2) + "\n", {
+        mode: 0o600,
+    });
 }
 /**
  * Merge the UluOps hook into settings, preserving all other

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

@@ -0,0 +1,72 @@
+/**
+ * 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;
+    };
+}
+/**
+ * Parse `npm ls -g --json` output and extract the installed version of
+ * AGENT_METRICS_PACKAGE, or null if absent or unparseable.
+ *
+ * Exported for direct unit testing — keeps the JSON shape contract explicit.
+ */
+export declare function parseGlobalAgentMetricsVersion(stdout: string | undefined): string | null;
+export declare function detectGlobalAgentMetrics(): string | null;
+/** Default executor — queries npm directly to avoid npx-transient-PATH false positives. */
+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,147 @@
+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";
+/**
+ * Parse `npm ls -g --json` output and extract the installed version of
+ * AGENT_METRICS_PACKAGE, or null if absent or unparseable.
+ *
+ * Exported for direct unit testing — keeps the JSON shape contract explicit.
+ */
+export function parseGlobalAgentMetricsVersion(stdout) {
+    if (!stdout)
+        return null;
+    try {
+        const parsed = JSON.parse(stdout);
+        const entry = parsed.dependencies?.[AGENT_METRICS_PACKAGE];
+        return entry?.version ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Detect whether `@uluops/agent-metrics` is installed in npm's GLOBAL prefix.
+ *
+ * IMPORTANT: this cannot be a simple `spawnSync("agent-metrics", ["--version"])`.
+ * `@uluops/agent-metrics` is a runtime dependency of `@uluops/setup` (used by
+ * `findMetricsSource` to resolve files to copy into the harness tree). When
+ * setup runs under `npx @uluops/setup`, npx prepends its transient cache
+ * `.bin/` to PATH for the spawned process — `agent-metrics` resolves there
+ * even when the user has nothing installed globally. The check then returns
+ * "already installed" and setup skips the global install, leaving the user
+ * with `command not found` after npx exits. This was the actual bug behavior
+ * observed in v0.7.0 on the first ship.
+ *
+ * We query npm directly via `npm ls -g --depth=0 --json` — answers the actual
+ * question ("is it in the user's global install") instead of a PATH-resolution
+ * proxy. `npm ls` exits non-zero when the queried package is missing but still
+ * emits valid JSON, so we rely on the JSON content rather than the exit code.
+ */
+/** Same bounds as the @uluops/cli installer — see src/steps/cli.ts rationale. */
+const NPM_TIMEOUT_MS = 5 * 60_000;
+const DETECT_TIMEOUT_MS = 30_000;
+function summarizeNpmResult(r, op) {
+    if (r.status === 0)
+        return { ok: true };
+    if (r.signal === "SIGTERM" && r.status === null) {
+        return {
+            ok: false,
+            error: `npm ${op} exceeded ${NPM_TIMEOUT_MS / 1000}s timeout and was terminated`,
+        };
+    }
+    const stderr = (r.stderr ?? "").toString().trim();
+    const stdout = (r.stdout ?? "").toString().trim();
+    return { ok: false, error: stderr || stdout || `exit ${r.status}` };
+}
+export function detectGlobalAgentMetrics() {
+    const r = spawnSync("npm", ["ls", "-g", AGENT_METRICS_PACKAGE, "--depth=0", "--json"], {
+        encoding: "utf-8",
+        stdio: ["ignore", "pipe", "ignore"],
+        timeout: DETECT_TIMEOUT_MS,
+    });
+    return parseGlobalAgentMetricsVersion(r.stdout);
+}
+/** Default executor — queries npm directly to avoid npx-transient-PATH false positives. */
+export const defaultAgentMetricsExecutor = {
+    detect: detectGlobalAgentMetrics,
+    install: () => {
+        const r = spawnSync("npm", ["install", "-g", AGENT_METRICS_PACKAGE], {
+            encoding: "utf-8",
+            stdio: ["ignore", "pipe", "pipe"],
+            timeout: NPM_TIMEOUT_MS,
+        });
+        return summarizeNpmResult(r, "install");
+    },
+    uninstall: () => {
+        const r = spawnSync("npm", ["uninstall", "-g", AGENT_METRICS_PACKAGE], {
+            encoding: "utf-8",
+            stdio: ["ignore", "pipe", "pipe"],
+            timeout: NPM_TIMEOUT_MS,
+        });
+        return summarizeNpmResult(r, "uninstall");
+    },
+};
+/**
+ * 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/dist/steps/agents.d.ts

@@ -4,6 +4,17 @@ export interface AgentsResult {
     skipped: number;
     removed: number;
     files: string[];
+    /**
+     * Per-file copy failures. The loop continues past errors so a single bad
+     * file (EACCES, ENOSPC, ENAMETOOLONG) cannot abort the whole install and
+     * leave the destination half-populated. The caller surfaces these via
+     * `warn()` and a re-run will pick up the failed files. Files in this list
+     * are NOT counted in `copied` (or `skipped`).
+     */
+    failures: {
+        file: string;
+        error: string;
+    }[];
 }
 /** Copy pre-rendered agent definitions from harness-specific assets to the target directory. */
 export declare function installAgents(profile: HarnessProfile, localDefs: boolean, dryRun: boolean, existingManifestAgents?: string[]): Promise<AgentsResult>;

package/dist/steps/agents.js

@@ -1,7 +1,7 @@
-import { readdir, mkdir, unlink } from "node:fs/promises";
+import { readdir, mkdir } from "node:fs/promises";
 import { join } from "node:path";
 import { ASSETS_DIR, findProjectRoot } from "../lib/paths.js";
-import { copyIfChanged, unlinkFiles } from "../lib/file-ops.js";
+import { copyIfChanged, unlinkFiles, removeStaleFiles, } from "../lib/file-ops.js";
 /** Copy pre-rendered agent definitions from harness-specific assets to the target directory. */
 export async function installAgents(profile, localDefs, dryRun, existingManifestAgents) {
     const srcDir = join(ASSETS_DIR, profile.name, "agents");
@@ -17,35 +17,40 @@ export async function installAgents(profile, localDefs, dryRun, existingManifest
         files = (await readdir(srcDir)).filter((f) => f.endsWith(ext));
     }
     catch {
-        return { copied: 0, skipped: 0, removed: 0, files: [] };
+        return { copied: 0, skipped: 0, removed: 0, files: [], failures: [] };
     }
     let copied = 0;
     let skipped = 0;
+    const installedFiles = [];
+    const failures = [];
     for (const file of files) {
-        const result = await copyIfChanged(join(srcDir, file), join(destDir, file), dryRun);
-        if (result === "copied")
-            copied++;
-        else
-            skipped++;
-    }
-    // Remove files that were in the old manifest but no longer in the package
-    let removed = 0;
-    if (existingManifestAgents) {
-        for (const oldFile of existingManifestAgents) {
-            if (!files.includes(oldFile)) {
-                if (!dryRun) {
-                    try {
-                        await unlink(join(destDir, oldFile));
-                    }
-                    catch {
-                        // Already gone
-                    }
-                }
-                removed++;
-            }
+        try {
+            const result = await copyIfChanged(join(srcDir, file), join(destDir, file), dryRun);
+            if (result === "copied")
+                copied++;
+            else
+                skipped++;
+            // Only files that actually landed on disk enter installedFiles.
+            // A failed copy must not appear here — the manifest treats this list
+            // as authoritative, and uninstall would later attempt to unlink a
+            // file that was never written. Aligned with installCommands /
+            // installSkills behavior; required by the multi-target install
+            // partial-state contract (§7.6.2 / §7.6.6).
+            installedFiles.push(file);
+        }
+        catch (err) {
+            // Continue past per-file failures so one bad file (EACCES, ENOSPC,
+            // ENAMETOOLONG) does not abort the whole install and leave the
+            // destination half-populated. The caller `warn()`s these and a re-run
+            // will retry — setup is idempotent on success.
+            failures.push({
+                file,
+                error: err instanceof Error ? err.message : String(err),
+            });
         }
     }
-    return { copied, skipped, removed, files };
+    const removed = await removeStaleFiles(destDir, existingManifestAgents, installedFiles, dryRun);
+    return { copied, skipped, removed, files: installedFiles, failures };
 }
 /** Remove previously installed agent files by name. */
 export async function uninstallAgents(files, defsPath) {

package/dist/steps/auth.d.ts

@@ -8,6 +8,19 @@ export interface AuthResult {
  * Existence-only — does not validate the file's shape or contents.
  */
 export declare function hasCredentialsFile(): Promise<boolean>;
+/**
+ * Persist an API key to ~/.uluops/credentials.json so @uluops/cli and the SDK
+ * can resolve it from disk without ULUOPS_API_KEY in the shell environment.
+ *
+ * Merges into the existing file when present: only the `default` profile is
+ * replaced; any other named profiles are preserved. Creates ~/.uluops/ with
+ * mode 0o700 if missing. Writes the file at 0o600 via atomicWrite.
+ */
+export declare function writeCredentialsFile(apiKey: string, opts?: {
+    email?: string | null;
+    source?: "signup" | "flag" | "prompt";
+    dryRun?: boolean;
+}): Promise<void>;
 /**
  * Resolve API key from flags, env, credentials file, or interactive prompt.
  */