@uluops/setup 0.7.0 → 0.9.0

package/dist/lib/file-ops.d.ts

@@ -11,6 +11,19 @@ export declare function writeIfChanged(destPath: string, content: string, dryRun
  * Remove files from a directory. Returns count of successfully removed files.
  */
 export declare function unlinkFiles(dir: string, files: string[]): Promise<number>;
+/**
+ * Reconcile a manifest's old file list against the current source set,
+ * unlinking the files that were installed previously but are no longer in
+ * the source. Returns the count of files that would have been removed
+ * (whether or not the unlink actually ran in dry-run mode).
+ *
+ * Extracted from three near-identical blocks in syncAssets, installAgents,
+ * and installCommands. Errors from unlink are swallowed silently — the
+ * "already gone" case is the dominant one (idempotent re-run, manual user
+ * deletion, prior failed install), and there's no recovery the caller
+ * can usefully perform mid-loop.
+ */
+export declare function removeStaleFiles(destDir: string, oldManifestFiles: string[] | undefined, currentFiles: string[], dryRun: boolean): Promise<number>;
 /**
  * Ensure a directory exists, then copy matching .md files using hash comparison.
  * Returns list of copied files, skipped count, and removed count (for old manifest entries).
@@ -27,8 +40,3 @@ export declare function syncAssets(opts: {
     removed: number;
     files: string[];
 }>;
-/**
- * Back up a file to the UluOps backup directory before modifying it.
- * No-op if the source file doesn't exist.
- */
-export declare function backupFile(srcPath: string, backupDir: string): Promise<void>;

package/dist/lib/file-ops.js

@@ -1,5 +1,5 @@
-import { readFile, writeFile, mkdir, unlink, access, copyFile, readdir } from "node:fs/promises";
-import { join, basename } from "node:path";
+import { readFile, writeFile, mkdir, unlink, readdir } from "node:fs/promises";
+import { join } from "node:path";
 import { fileHash } from "./hash.js";
 /**
  * Copy a file if its content has changed (hash comparison). Returns "copied" or "skipped".
@@ -57,6 +57,37 @@ export async function unlinkFiles(dir, files) {
     }
     return removed;
 }
+/**
+ * Reconcile a manifest's old file list against the current source set,
+ * unlinking the files that were installed previously but are no longer in
+ * the source. Returns the count of files that would have been removed
+ * (whether or not the unlink actually ran in dry-run mode).
+ *
+ * Extracted from three near-identical blocks in syncAssets, installAgents,
+ * and installCommands. Errors from unlink are swallowed silently — the
+ * "already gone" case is the dominant one (idempotent re-run, manual user
+ * deletion, prior failed install), and there's no recovery the caller
+ * can usefully perform mid-loop.
+ */
+export async function removeStaleFiles(destDir, oldManifestFiles, currentFiles, dryRun) {
+    if (!oldManifestFiles)
+        return 0;
+    let removed = 0;
+    for (const oldFile of oldManifestFiles) {
+        if (!currentFiles.includes(oldFile)) {
+            if (!dryRun) {
+                try {
+                    await unlink(join(destDir, oldFile));
+                }
+                catch {
+                    // Already gone
+                }
+            }
+            removed++;
+        }
+    }
+    return removed;
+}
 /**
  * Ensure a directory exists, then copy matching .md files using hash comparison.
  * Returns list of copied files, skipped count, and removed count (for old manifest entries).
@@ -83,40 +114,9 @@ export async function syncAssets(opts) {
         }
     }
     // Remove files that were in the old manifest but no longer in the package
-    let removed = 0;
-    if (opts.oldManifestFiles) {
-        for (const oldFile of opts.oldManifestFiles) {
-            if (!assetFiles.includes(oldFile)) {
-                if (!opts.dryRun) {
-                    try {
-                        await unlink(join(opts.destDir, oldFile));
-                    }
-                    catch {
-                        // Already gone
-                    }
-                }
-                removed++;
-            }
-        }
-    }
+    const removed = await removeStaleFiles(opts.destDir, opts.oldManifestFiles, assetFiles, opts.dryRun);
     if (errors.length > 0) {
         throw new Error(`Failed to copy ${errors.length} file(s):\n  ${errors.join("\n  ")}`);
     }
     return { copied, skipped, removed, files: assetFiles };
 }
-/**
- * Back up a file to the UluOps backup directory before modifying it.
- * No-op if the source file doesn't exist.
- */
-export async function backupFile(srcPath, backupDir) {
-    try {
-        await access(srcPath);
-    }
-    catch {
-        return; // Nothing to back up
-    }
-    await mkdir(backupDir, { recursive: true });
-    const filename = basename(srcPath);
-    const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
-    await copyFile(srcPath, join(backupDir, `${filename}.${timestamp}.bak`));
-}

package/dist/lib/install-lock.js

@@ -16,7 +16,7 @@
 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 { dirname, join } from "node:path";
 import { getInstallLockDir } from "./paths.js";
 const META_FILENAME = "meta.json";
 const DEFAULT_MAX_AGE_MS = 30 * 60 * 1000; // 30 min
@@ -41,6 +41,16 @@ export async function acquireInstallLock(opts = {}) {
     const maxAgeMs = opts.maxAgeMs ?? DEFAULT_MAX_AGE_MS;
     const waitMs = opts.waitMs ?? DEFAULT_WAIT_MS;
     const deadline = Date.now() + waitMs;
+    // Ensure the parent directory exists before the atomic lock mkdir below.
+    // The lock dir itself is created with `recursive: false` to preserve
+    // mkdir-atomicity as the lock primitive (two racing processes can't both
+    // win the mkdir). But if the user has never run setup before, ~/.uluops/
+    // doesn't exist yet — and `recursive: false` mkdir surfaces ENOENT on
+    // the missing parent rather than EEXIST on the lock itself, so the loop
+    // below would treat that as an unrecoverable error. Pre-creating the
+    // parent with `recursive: true` is safe (it's idempotent and not part of
+    // the atomicity contract — only the lock dir mkdir is).
+    await mkdir(dirname(lockDir), { recursive: true });
     // First try (and one retry after stale-lock reclaim).
     for (let attempt = 0; attempt < 2; attempt++) {
         try {

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 {

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

@@ -19,23 +19,6 @@ export declare function getManifestPath(): string;
 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

@@ -98,25 +98,6 @@ export function getInstallLockDir() {
 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

@@ -26,7 +26,15 @@ export interface AgentMetricsCliExecutor {
         error?: string;
     };
 }
-/** Default executor — shells out to `agent-metrics` and `npm`. */
+/**
+ * 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. */

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

@@ -13,38 +13,84 @@ import { spawnSync } from "node:child_process";
  */
 export const AGENT_METRICS_PACKAGE = "@uluops/agent-metrics";
 export const AGENT_METRICS_BIN = "agent-metrics";
-/** Default executor — shells out to `agent-metrics` and `npm`. */
+/**
+ * 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: () => {
-        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;
-    },
+    detect: detectGlobalAgentMetrics,
     install: () => {
         const r = spawnSync("npm", ["install", "-g", AGENT_METRICS_PACKAGE], {
             encoding: "utf-8",
             stdio: ["ignore", "pipe", "pipe"],
+            timeout: NPM_TIMEOUT_MS,
         });
-        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}` };
+        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,
         });
-        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}` };
+        return summarizeNpmResult(r, "uninstall");
     },
 };
 /**

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.
  */