@uluops/setup 0.10.0 → 0.12.0

package/dist/commands/uninstall.d.ts

@@ -10,4 +10,11 @@ export interface RunUninstallOpts {
     /** Whether --all-detected was passed. */
     allDetected?: boolean;
 }
+/**
+ * The `--uninstall` flow: removes UluOps-managed artifacts for every harness
+ * in the manifest, or — when a harness filter is passed — only the named
+ * subset, preserving shared infrastructure (global CLI packages, shell
+ * export) that remaining harnesses still need. Fails fast if a named harness
+ * is not in the manifest.
+ */
 export declare function runUninstall(opts: RunUninstallOpts): Promise<void>;

package/dist/commands/uninstall.js

@@ -13,6 +13,13 @@ import { ok, warn, fail, info } from "../lib/display.js";
 import { getVersion } from "../lib/version.js";
 import { getProfile } from "../harnesses/index.js";
 import { resolveUninstallFilter, UninstallFilterError, } from "./uninstall-filter.js";
+/**
+ * The `--uninstall` flow: removes UluOps-managed artifacts for every harness
+ * in the manifest, or — when a harness filter is passed — only the named
+ * subset, preserving shared infrastructure (global CLI packages, shell
+ * export) that remaining harnesses still need. Fails fast if a named harness
+ * is not in the manifest.
+ */
 export async function runUninstall(opts) {
     const version = await getVersion();
     console.log();
@@ -64,7 +71,12 @@ export async function runUninstall(opts) {
             if (err instanceof UninstallFilterError) {
                 fail(err.message);
                 console.log();
-                process.exit(1);
+                // Same rule as runSetup: never process.exit inside the lock-guarded
+                // try. A plain `return` here makes any statement after the finally
+                // unreachable, so the code must ride process.exitCode — safe at this
+                // point because no prompt has run (no lingering stdin handle).
+                process.exitCode = 1;
+                return;
             }
             throw err;
         }
@@ -120,8 +132,8 @@ export async function runUninstall(opts) {
                     await uninstallMcp(profile, hm.mcpConfigPath);
                     ok(`Removed MCP servers from ${hm.mcpConfigPath}`);
                 }
-                catch {
-                    warn(`Could not remove MCP servers from ${hm.mcpConfigPath}`);
+                catch (err) {
+                    warn(`Could not remove MCP servers from ${hm.mcpConfigPath}: ${err instanceof Error ? err.message : String(err)}`);
                 }
             }
             else {
@@ -180,8 +192,13 @@ export async function runUninstall(opts) {
                 const { getShellProfile } = await import("../lib/paths.js");
                 const shellProfile = getShellProfile();
                 if (shellProfile && !opts.dryRun) {
-                    await removeShellExport(shellProfile.path);
-                    ok(`Removed export from ${shellProfile.path}`);
+                    const shellRes = await removeShellExport(shellProfile.path);
+                    if (shellRes.removed) {
+                        ok(`Removed export from ${shellProfile.path}`);
+                    }
+                    else {
+                        warn(`Could not remove export from ${shellProfile.path}${shellRes.reason ? ` — ${shellRes.reason}` : ""}. The plaintext API key may still be in the file; remove the UluOps block manually.`);
+                    }
                 }
                 else if (shellProfile) {
                     ok(`Would remove export from ${shellProfile.path}`);
@@ -199,8 +216,13 @@ export async function runUninstall(opts) {
         //     would reject an empty-harnesses file)
         if (!opts.dryRun) {
             if (isFullUninstall) {
-                await deleteManifest();
-                ok("Manifest deleted");
+                const delRes = await deleteManifest();
+                if (delRes.failed.length === 0) {
+                    ok("Manifest deleted");
+                }
+                else {
+                    warn(`Could not delete manifest: ${delRes.failed.join("; ")} — it still records this install; remove it manually.`);
+                }
             }
             else {
                 for (const name of toUninstall) {
@@ -212,8 +234,13 @@ export async function runUninstall(opts) {
                     ok(`Manifest updated — ${remaining} harness(es) remain: ${Object.keys(manifest.harnesses).join(", ")}`);
                 }
                 else {
-                    await deleteManifest();
-                    ok("Manifest deleted (no harnesses remain)");
+                    const delRes2 = await deleteManifest();
+                    if (delRes2.failed.length === 0) {
+                        ok("Manifest deleted (no harnesses remain)");
+                    }
+                    else {
+                        warn(`Could not delete manifest: ${delRes2.failed.join("; ")} — remove it manually.`);
+                    }
                 }
             }
         }

package/dist/commands/verify.d.ts

@@ -1 +1,6 @@
+/**
+ * The `--verify` flow: prints one check line per verify-step result
+ * (manifest, per-harness readiness/MCP/files/hook, API key) and exits 1
+ * when any check failed. Read-only — makes no changes.
+ */
 export declare function runVerify(): Promise<void>;

package/dist/commands/verify.js

@@ -2,6 +2,11 @@ import chalk from "chalk";
 import { verify } from "../steps/verify.js";
 import { ok, fail, info } from "../lib/display.js";
 import { getVersion } from "../lib/version.js";
+/**
+ * The `--verify` flow: prints one check line per verify-step result
+ * (manifest, per-harness readiness/MCP/files/hook, API key) and exits 1
+ * when any check failed. Read-only — makes no changes.
+ */
 export async function runVerify() {
     const version = await getVersion();
     console.log();

package/dist/harnesses/claude-code.js

@@ -9,6 +9,7 @@ import { ULUOPS_SERVERS, } from "./types.js";
 import { readConfig, mergeUluopsMcp, removeUluopsMcp, writeConfig, } from "../lib/config-merger.js";
 import { readSettings, writeSettings, mergeUluopsHook, removeUluopsHook, hasUluopsHook, } from "../lib/settings-merger.js";
 import { getClaudeHome, getClaudeJsonPath } from "../lib/paths.js";
+import { serialize } from "../lib/write-coordinator.js";
 class ClaudeCodeMcpConfig {
     async read(path) {
         return readConfig(path);
@@ -33,18 +34,25 @@ class ClaudeCodeHooks {
     async install(settingsPath, hookCommand, dryRun) {
         if (dryRun)
             return true;
-        const settings = await readSettings(settingsPath);
-        // Claude Code uses SubagentStop as the default event for auto-save
-        const merged = mergeUluopsHook(settings, hookCommand);
-        await writeSettings(settingsPath, merged);
+        // Serialized for uniformity with the MCP cycle — the invariant is
+        // "every settings RMW is exclusive per path", not "only where files
+        // collide today".
+        await serialize(settingsPath, async () => {
+            const settings = await readSettings(settingsPath);
+            // Claude Code uses SubagentStop as the default event for auto-save
+            const merged = mergeUluopsHook(settings, hookCommand);
+            await writeSettings(settingsPath, merged);
+        });
         return true;
     }
     async remove(settingsPath, dryRun) {
         if (dryRun)
             return;
-        const settings = await readSettings(settingsPath);
-        const cleaned = removeUluopsHook(settings);
-        await writeSettings(settingsPath, cleaned);
+        await serialize(settingsPath, async () => {
+            const settings = await readSettings(settingsPath);
+            const cleaned = removeUluopsHook(settings);
+            await writeSettings(settingsPath, cleaned);
+        });
     }
     async check(settingsPath) {
         const settings = await readSettings(settingsPath);

package/dist/harnesses/codex.js

@@ -11,6 +11,7 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { ULUOPS_SERVERS, } from "./types.js";
 import { atomicWrite } from "../lib/atomic-write.js";
+import { isEnoent } from "../lib/file-ops.js";
 import { OPS_MCP_SPEC, REGISTRY_MCP_SPEC } from "../lib/mcp-packages.js";
 const RAW_TOML = "__rawToml";
 /**
@@ -146,10 +147,17 @@ function removeServerConfigBlocks(raw, name) {
     const kept = [];
     let skipping = false;
     for (const line of lines) {
-        const table = line.trim().match(/^\[([^\]]+)\]$/)?.[1];
+        const trimmed = line.trim();
+        const table = trimmed.match(/^\[([^\]]+)\]$/)?.[1];
         if (table) {
             skipping = isServerTableFor(name, table) || isServerEnvTableFor(name, table);
         }
+        else if (trimmed.startsWith("[")) {
+            // Any header the regex can't parse (array-of-tables [[x]], quoted ']')
+            // still STARTS a new table — the skip must end, or the user's next
+            // block is dropped along with ours.
+            skipping = false;
+        }
         if (!skipping)
             kept.push(line);
     }
@@ -160,10 +168,15 @@ function removeServerSubtree(raw, name) {
     const kept = [];
     let skipping = false;
     for (const line of lines) {
-        const table = line.trim().match(/^\[([^\]]+)\]$/)?.[1];
+        const trimmed = line.trim();
+        const table = trimmed.match(/^\[([^\]]+)\]$/)?.[1];
         if (table) {
             skipping = isServerTableFor(name, table) || isServerSubtableFor(name, table);
         }
+        else if (trimmed.startsWith("[")) {
+            // See removeServerConfigBlocks: an unparseable header still ends the skip.
+            skipping = false;
+        }
         if (!skipping)
             kept.push(line);
     }
@@ -182,8 +195,12 @@ class CodexMcpConfig {
         try {
             return { [RAW_TOML]: await readFile(path, "utf-8") };
         }
-        catch {
-            return { [RAW_TOML]: "" };
+        catch (err) {
+            if (isEnoent(err))
+                return { [RAW_TOML]: "" };
+            // Unreadable-but-PRESENT must never read as fresh: write() replaces
+            // the whole file, so an EACCES here would erase the user's config.
+            throw new Error(`Could not read Codex config at ${path} (${err instanceof Error ? err.message : String(err)}) — refusing to continue rather than overwrite a file that exists but could not be read. Nothing was modified.`);
         }
     }
     merge(config, apiKey) {

package/dist/harnesses/gemini-cli.js

@@ -13,6 +13,7 @@ import { join } from "node:path";
 import { ULUOPS_SERVERS, } from "./types.js";
 import { readConfig, mergeUluopsMcp, removeUluopsMcp, writeConfig, } from "../lib/config-merger.js";
 import { readSettings, writeSettings, mergeUluopsHook, removeUluopsHook, hasUluopsHook, } from "../lib/settings-merger.js";
+import { serialize } from "../lib/write-coordinator.js";
 class GeminiMcpConfig {
     async read(path) {
         return readConfig(path);
@@ -40,17 +41,23 @@ class GeminiHooks {
     async install(settingsPath, hookCommand, dryRun) {
         if (dryRun)
             return true;
-        const settings = await readSettings(settingsPath);
-        const merged = mergeUluopsHook(settings, hookCommand, GeminiHooks.HOOK_TYPE, GeminiHooks.MATCHER);
-        await writeSettings(settingsPath, merged);
+        // Serialized: settings.json is ALSO this profile's MCP config file —
+        // the whole read-merge-write must be exclusive against that cycle.
+        await serialize(settingsPath, async () => {
+            const settings = await readSettings(settingsPath);
+            const merged = mergeUluopsHook(settings, hookCommand, GeminiHooks.HOOK_TYPE, GeminiHooks.MATCHER);
+            await writeSettings(settingsPath, merged);
+        });
         return true;
     }
     async remove(settingsPath, dryRun) {
         if (dryRun)
             return;
-        const settings = await readSettings(settingsPath);
-        const cleaned = removeUluopsHook(settings, GeminiHooks.HOOK_TYPE);
-        await writeSettings(settingsPath, cleaned);
+        await serialize(settingsPath, async () => {
+            const settings = await readSettings(settingsPath);
+            const cleaned = removeUluopsHook(settings, GeminiHooks.HOOK_TYPE);
+            await writeSettings(settingsPath, cleaned);
+        });
     }
     async check(settingsPath) {
         const settings = await readSettings(settingsPath);

package/dist/harnesses/index.d.ts

@@ -23,5 +23,13 @@ export declare function getProfile(name: string): HarnessProfile;
  * list = safe to install" is preserved.
  */
 export declare function detectHarnesses(): HarnessProfile[];
+/**
+ * Experimental profiles whose home dir is present — the set detectHarnesses
+ * deliberately excludes. Exposed so the CLI can SAY it excluded them
+ * (silent exclusion reads as a detection bug to a user who can see the
+ * harness installed) while keeping the "detected = safe to install"
+ * promise intact.
+ */
+export declare function detectExcludedExperimental(): HarnessProfile[];
 /** List all available harness names (not aliases). */
 export declare function listHarnesses(): string[];

package/dist/harnesses/index.js

@@ -53,6 +53,16 @@ export function getProfile(name) {
 export function detectHarnesses() {
     return ALL_PROFILES.filter((p) => p.status === "stable" && existsSync(p.paths.home));
 }
+/**
+ * Experimental profiles whose home dir is present — the set detectHarnesses
+ * deliberately excludes. Exposed so the CLI can SAY it excluded them
+ * (silent exclusion reads as a detection bug to a user who can see the
+ * harness installed) while keeping the "detected = safe to install"
+ * promise intact.
+ */
+export function detectExcludedExperimental() {
+    return ALL_PROFILES.filter((p) => p.status !== "stable" && existsSync(p.paths.home));
+}
 /** List all available harness names (not aliases). */
 export function listHarnesses() {
     return ALL_PROFILES.map((p) => p.name);

package/dist/harnesses/opencode.js

@@ -13,9 +13,10 @@
 import { readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join, isAbsolute } from "node:path";
-import { parse as parseJsonc } from "jsonc-parser";
+import { parse as parseJsonc, } from "jsonc-parser";
 import { ULUOPS_SERVERS, ConfigParseError } from "./types.js";
 import { atomicWrite } from "../lib/atomic-write.js";
+import { isEnoent } from "../lib/file-ops.js";
 import { OPS_MCP_SPEC, REGISTRY_MCP_SPEC } from "../lib/mcp-packages.js";
 class OpenCodeMcpConfig {
     /** Maps requested path → actual resolved path (for .jsonc fallback). */
@@ -30,20 +31,37 @@ class OpenCodeMcpConfig {
                 this.resolvedPaths.set(path, p);
                 break;
             }
-            catch {
-                // Try next
+            catch (err) {
+                if (isEnoent(err))
+                    continue; // Try next candidate
+                // Unreadable-but-PRESENT must never fall through to "no file →
+                // fresh config" — the write would replace the file we couldn't read.
+                throw new Error(`Could not read OpenCode config at ${p} (${err instanceof Error ? err.message : String(err)}) — refusing to continue rather than overwrite a file that exists but could not be read. Nothing was modified.`);
             }
         }
         if (raw === null) {
             this.resolvedPaths.set(path, path);
             return {};
         }
-        try {
-            return parseJsonc(raw);
+        // jsonc-parser's parse() is error-RECOVERING, never throwing: on a
+        // syntax error it silently returns whatever it salvaged, and everything
+        // after the error point would be dropped, merged, and written back over
+        // the user's file. The errors out-param is the only honest signal.
+        const parseErrors = [];
+        const parsed = parseJsonc(raw, parseErrors, {
+            allowTrailingComma: true,
+        });
+        if (parseErrors.length > 0) {
+            const first = parseErrors[0];
+            throw new ConfigParseError(path, new Error(`invalid JSONC (error code ${first.error} at offset ${first.offset}) — fix or remove the file and re-run; nothing was modified`));
         }
-        catch (err) {
-            throw new ConfigParseError(path, err);
+        // Same top-level gate as config-merger/settings-merger: valid JSONC that
+        // isn't an object cannot be merged into — writing it back mangled with
+        // no error is worse than refusing.
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+            throw new ConfigParseError(path, new Error("expected a JSON object at the top level"));
         }
+        return parsed;
     }
     merge(config, apiKey) {
         const raw = config["mcp"];

package/dist/lib/asset-catalog.js

@@ -38,12 +38,25 @@ async function scanCommandDir(dir) {
     try {
         files = await readdir(dir);
     }
-    catch {
+    catch (err) {
+        if (err?.code !== "ENOENT") {
+            // Unreadable bundled dir is a broken build, not "ships no commands".
+            console.warn(`  ⚠ Could not read bundled commands dir ${dir}: ${err instanceof Error ? err.message : String(err)}`);
+        }
         return [];
     }
     const entries = [];
     for (const file of files.filter((f) => f.endsWith(".md"))) {
-        const content = await readFile(join(dir, file), "utf-8");
+        let content;
+        try {
+            content = await readFile(join(dir, file), "utf-8");
+        }
+        catch (err) {
+            // Display/catalog path: an unreadable bundled file (truncated npx
+            // cache) must not throw out of the summary — name it and move on.
+            console.warn(`  ⚠ Could not read bundled ${file}: ${err instanceof Error ? err.message : String(err)}`);
+            continue;
+        }
         const fm = parseFrontmatter(content);
         if (fm["name"]) {
             entries.push({

package/dist/lib/atomic-write.d.ts

@@ -8,4 +8,10 @@ export interface AtomicWriteOptions {
     /** File mode (permissions). Defaults to Node's default (0o666 before umask). */
     mode?: number;
 }
+/**
+ * Write `content` to `path` atomically: write to a random-suffixed temp file
+ * in the same directory, then rename over the target. Readers see either the
+ * old file or the new one, never a partial write. The temp file is unlinked
+ * on failure.
+ */
 export declare function atomicWrite(path: string, content: string, options?: AtomicWriteOptions): Promise<void>;

package/dist/lib/atomic-write.js

@@ -6,6 +6,13 @@
  */
 import { writeFile, rename, unlink, chmod } from "node:fs/promises";
 import { randomBytes } from "node:crypto";
+import { recordWrite } from "./write-coordinator.js";
+/**
+ * Write `content` to `path` atomically: write to a random-suffixed temp file
+ * in the same directory, then rename over the target. Readers see either the
+ * old file or the new one, never a partial write. The temp file is unlinked
+ * on failure.
+ */
 export async function atomicWrite(path, content, options) {
     // Random suffix + 'wx' flag (O_CREAT|O_EXCL) prevents symlink races:
     // an attacker cannot pre-position a symlink at an unpredictable path,
@@ -22,6 +29,9 @@ export async function atomicWrite(path, content, options) {
             await chmod(tmp, options.mode);
         }
         await rename(tmp, path);
+        // Attest the write for the coordinator's restore guard — only content
+        // this process provably wrote may be rolled back over.
+        recordWrite(path, content);
     }
     catch (err) {
         // Clean up temp file on failure

package/dist/lib/config-merger.js

@@ -1,6 +1,8 @@
 import { readFile } from "node:fs/promises";
 import { atomicWrite } from "./atomic-write.js";
-import { MCP_PACKAGES, OPS_MCP_SPEC, REGISTRY_MCP_SPEC, } from "./mcp-packages.js";
+import { stripDangerousKeys } from "./json-guards.js";
+import { isEnoent } from "./file-ops.js";
+import { MCP_PROBE_TARGETS, OPS_MCP_SPEC, REGISTRY_MCP_SPEC, } from "./mcp-packages.js";
 /**
  * In-process memoization for the npm availability probe.
  *
@@ -36,18 +38,21 @@ export function checkMcpPackageAvailability() {
 async function probeAvailability() {
     const available = [];
     const missing = [];
-    const results = await Promise.allSettled(MCP_PACKAGES.map((pkg) => fetch(`https://registry.npmjs.org/${pkg}`, {
+    // Probe the PINNED version endpoints — the harness runs `npx -y <spec>`,
+    // so pin resolvability is the question, not name existence.
+    const results = await Promise.allSettled(MCP_PROBE_TARGETS.map(({ pkg, version }) => fetch(`https://registry.npmjs.org/${pkg}/${version}`, {
         method: "HEAD",
         signal: AbortSignal.timeout(5000),
         redirect: "follow",
     }).then((res) => ({ pkg, ok: res.ok }))));
-    // Per-index correspondence: results[i] corresponds to MCP_PACKAGES[i] by
+    // Per-index correspondence: results[i] corresponds to MCP_PROBE_TARGETS[i] by
     // Promise.allSettled's stable ordering. The previous `?? "unknown"` fallback
     // could emit a literal "unknown" string into `missing`, hiding the real
     // failure reason (DNS error, timeout, 404) under an undiagnosable label.
     for (let i = 0; i < results.length; i++) {
         const result = results[i];
-        const pkg = MCP_PACKAGES[i];
+        const target = MCP_PROBE_TARGETS[i];
+        const pkg = `${target.pkg}@${target.version}`;
         if (result.status === "fulfilled") {
             if (result.value.ok) {
                 available.push(pkg);
@@ -76,15 +81,29 @@ export async function readConfig(path) {
     try {
         raw = await readFile(path, "utf-8");
     }
-    catch {
-        return {}; // File doesn't exist — fresh config
+    catch (err) {
+        if (isEnoent(err))
+            return {}; // File doesn't exist — fresh config
+        // Unreadable-but-PRESENT (EACCES/EISDIR/EIO) must never read as fresh:
+        // the {} would be merged and renamed over the file we couldn't read.
+        throw new Error(`Could not read config at ${path} (${err instanceof Error ? err.message : String(err)}) — refusing to continue rather than overwrite a file that exists but could not be read. Nothing was modified.`);
     }
+    let parsed;
     try {
-        return JSON.parse(raw);
+        parsed = JSON.parse(raw);
     }
     catch {
-        throw new Error(`Failed to parse config at ${path} — file contains invalid JSON`);
+        // The read happens BEFORE any write — say so, or a pre-existing broken
+        // file reads as UluOps-caused corruption.
+        throw new Error(`Failed to parse config at ${path} — file contains invalid JSON. ` +
+            `(Detected before any UluOps change; nothing was modified. Fix or remove the file and re-run.)`);
+    }
+    // Same rationale as the JSON throw: valid JSON that isn't an object cannot
+    // be merged into — spreading it would corrupt the file we then write back.
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new Error(`Failed to parse config at ${path} — expected a JSON object at the top level`);
     }
+    return stripDangerousKeys(parsed);
 }
 /**
  * Merge UluOps MCP server entries into a config, preserving all other keys.

package/dist/lib/display.d.ts

@@ -4,6 +4,12 @@ declare const warn: (msg: string) => void;
 declare const fail: (msg: string) => void;
 declare const info: (msg: string) => void;
 export { ok, warn, fail, info };
+/** Blank spacer line — keeps command modules free of raw console calls. */
+export declare function blank(): void;
+/** Per-harness section header in the multi-harness install loop. */
+export declare function printHarnessHeader(displayName: string): void;
+/** The branded setup banner: logo, tagline, version + target line. */
+export declare function printSetupBanner(version: string, targetSummary: string): void;
 /**
  * Render the final post-run summary.
  *
@@ -26,5 +32,7 @@ export declare function printSetupSummary(input: {
     results: PerHarnessResult[];
     apiKey: string;
 }): Promise<void>;
+/** Mask an API key for display: all but the last 4 chars become `*` (minimum 4 stars). */
 export declare function maskKey(key: string): string;
+/** Render the `--list` output: workflows then agents from the asset catalog, descriptions truncated to fit. */
 export declare function printAgentList(): Promise<void>;

package/dist/lib/display.js

@@ -5,6 +5,23 @@ const warn = (msg) => console.log(`  ${chalk.yellow("⚠")} ${msg}`);
 const fail = (msg) => console.log(`  ${chalk.red("✗")} ${msg}`);
 const info = (msg) => console.log(`  ${msg}`);
 export { ok, warn, fail, info };
+/** Blank spacer line — keeps command modules free of raw console calls. */
+export function blank() {
+    console.log();
+}
+/** Per-harness section header in the multi-harness install loop. */
+export function printHarnessHeader(displayName) {
+    console.log(chalk.dim(`▸ ${displayName}`));
+}
+/** The branded setup banner: logo, tagline, version + target line. */
+export function printSetupBanner(version, targetSummary) {
+    console.log();
+    console.log(`  ${chalk.dim("⟨u⟩")} ${chalk.cyan.bold("ulu")}${chalk.bold("·ops")}`);
+    console.log(`      ${chalk.dim("operating intelligence as infrastructure")}`);
+    console.log();
+    console.log(`  Setup v${version} — ${chalk.bold(targetSummary)}`);
+    console.log();
+}
 const DIVIDER = `  ${chalk.dim("━".repeat(46))}`;
 /**
  * Render the final post-run summary.
@@ -74,7 +91,14 @@ export async function printSetupSummary(input) {
     if (total === 1 &&
         results[0].status === "ok" &&
         results[0].profile.name === "claude-code") {
-        await printAgentList();
+        try {
+            await printAgentList();
+        }
+        catch (err) {
+            // The catalog is decorative; the export line and restart instruction
+            // below are the actionable tail — never lose them to a listing error.
+            warn(`Could not list bundled agents: ${err instanceof Error ? err.message : String(err)}`);
+        }
     }
     // API-key reminder — once per run regardless of harness count.
     const masked = maskKey(apiKey);
@@ -135,12 +159,14 @@ function renderCounts(r) {
         parts.push("metrics");
     return parts.length > 0 ? `(${parts.join(" · ")})` : "";
 }
+/** Mask an API key for display: all but the last 4 chars become `*` (minimum 4 stars). */
 export function maskKey(key) {
     if (!key || key.length <= 4)
         return "****";
     const last4 = key.slice(-4);
     return `${"*".repeat(Math.max(4, key.length - 4))}${last4}`;
 }
+/** Render the `--list` output: workflows then agents from the asset catalog, descriptions truncated to fit. */
 export async function printAgentList() {
     const workflows = await getWorkflowCommands();
     const agents = await getAgentCommands();

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

@@ -1,3 +1,13 @@
+/**
+ * True when `err` is fs ENOENT — the ONLY read error that means "absent".
+ * Every read-then-overwrite path must use this before treating a file as
+ * fresh: EACCES/EISDIR/EIO also land in a catch, and inferring "absent" from
+ * them turns an unreadable-but-present config into a fresh-file overwrite
+ * that destroys the user's content. (This class was fixed once at
+ * steps/mcp.ts's gitignore path and recurred at five other sites — hence a
+ * shared predicate rather than five inline checks.)
+ */
+export declare function isEnoent(err: unknown): boolean;
 /**
  * Copy a file if its content has changed (hash comparison). Returns "copied" or "skipped".
  */
@@ -18,10 +28,9 @@ export declare function unlinkFiles(dir: string, files: string[]): Promise<numbe
  * (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.
+ * and installCommands. ENOENT unlink failures are tolerated silently (the
+ * dominant, idempotent case); any other failure is warned by name and
+ * excluded from the removed count.
  */
 export declare function removeStaleFiles(destDir: string, oldManifestFiles: string[] | undefined, currentFiles: string[], dryRun: boolean): Promise<number>;
 /**