@uluops/setup 0.11.0 → 0.13.0

package/dist/lib/file-ops.js

@@ -1,6 +1,19 @@
-import { readFile, writeFile, mkdir, unlink, readdir } from "node:fs/promises";
-import { join } from "node:path";
+import { readFile, mkdir, unlink, readdir } from "node:fs/promises";
+import { join, resolve, relative, isAbsolute } from "node:path";
 import { fileHash } from "./hash.js";
+import { atomicWrite } from "./atomic-write.js";
+/**
+ * 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 function isEnoent(err) {
+    return err?.code === "ENOENT";
+}
 /**
  * Copy a file if its content has changed (hash comparison). Returns "copied" or "skipped".
  */
@@ -13,11 +26,17 @@ export async function copyIfChanged(srcPath, destPath, dryRun) {
             return "skipped";
         }
     }
-    catch {
-        // File doesn't exist yet
+    catch (err) {
+        // Only genuine absence means "copy fresh" — an unreadable-but-present
+        // destination should surface, not be silently overwritten (isEnoent doc).
+        if (!isEnoent(err))
+            throw err;
     }
     if (!dryRun) {
-        await writeFile(destPath, srcContent);
+        // Atomic: a crash mid-copy must not leave a truncated agent/command file
+        // whose hash matches neither side (re-run would fix it, but the harness
+        // may load the torn file first).
+        await atomicWrite(destPath, srcContent);
     }
     return "copied";
 }
@@ -33,26 +52,51 @@ export async function writeIfChanged(destPath, content, dryRun) {
             return "skipped";
         }
     }
-    catch {
-        // File doesn't exist yet
+    catch (err) {
+        if (!isEnoent(err))
+            throw err; // see copyIfChanged
     }
     if (!dryRun) {
-        await writeFile(destPath, content);
+        await atomicWrite(destPath, content);
     }
     return "copied";
 }
+/**
+ * Containment gate for manifest-supplied file names (CWE-22): the manifest
+ * is a same-UID-writable JSON file, and a hand-edited or foreign-written
+ * entry containing `../` would otherwise turn uninstall into an
+ * arbitrary-delete primitive. Only paths that resolve INSIDE `dir` pass.
+ */
+function resolveContained(dir, file) {
+    const base = resolve(dir);
+    const target = resolve(base, file);
+    const rel = relative(base, target);
+    if (rel === "" || rel.startsWith("..") || isAbsolute(rel))
+        return null;
+    return target;
+}
 /**
  * Remove files from a directory. Returns count of successfully removed files.
  */
 export async function unlinkFiles(dir, files) {
     let removed = 0;
     for (const file of files) {
+        const target = resolveContained(dir, file);
+        if (target === null) {
+            console.warn(`  ⚠ Refusing to remove ${JSON.stringify(file)} — resolves outside ${dir}`);
+            continue;
+        }
         try {
-            await unlink(join(dir, file));
+            await unlink(target);
             removed++;
         }
-        catch {
-            // Already gone
+        catch (err) {
+            // ENOENT = already gone (the dominant, idempotent case). Anything
+            // else is a file we FAILED to remove — say so, because the caller's
+            // count alone reads as success and the manifest may be deleted next.
+            if (!isEnoent(err)) {
+                console.warn(`  ⚠ Could not remove ${join(dir, file)}: ${err instanceof Error ? err.message : String(err)}`);
+            }
         }
     }
     return removed;
@@ -64,10 +108,9 @@ export async function unlinkFiles(dir, files) {
  * (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 async function removeStaleFiles(destDir, oldManifestFiles, currentFiles, dryRun) {
     if (!oldManifestFiles)
@@ -75,12 +118,20 @@ export async function removeStaleFiles(destDir, oldManifestFiles, currentFiles,
     let removed = 0;
     for (const oldFile of oldManifestFiles) {
         if (!currentFiles.includes(oldFile)) {
+            const staleTarget = resolveContained(destDir, oldFile);
+            if (staleTarget === null) {
+                console.warn(`  ⚠ Refusing to remove stale ${JSON.stringify(oldFile)} — resolves outside ${destDir}`);
+                continue;
+            }
             if (!dryRun) {
                 try {
-                    await unlink(join(destDir, oldFile));
+                    await unlink(staleTarget);
                 }
-                catch {
-                    // Already gone
+                catch (err) {
+                    if (!isEnoent(err)) {
+                        console.warn(`  ⚠ Could not remove stale ${join(destDir, oldFile)}: ${err instanceof Error ? err.message : String(err)}`);
+                        continue; // failed — must not count as removed
+                    }
                 }
             }
             removed++;

package/dist/lib/install-lock.js

@@ -26,7 +26,9 @@ const POLL_INTERVAL_MS = 500;
 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).`);
+        super(holder.pid > 0
+            ? `Another uluops-setup process is already running (PID ${holder.pid} on ${holder.hostname}, started ${Math.round(holder.ageMs / 1000)}s ago).`
+            : `Another uluops-setup process appears to be running but could not be identified (${holder.hostname}). If no other setup is running, re-run in a moment or remove ~/.uluops/install.lock manually.`);
         this.holder = holder;
         this.name = "InstallLockHeldError";
     }
@@ -61,7 +63,9 @@ export async function acquireInstallLock(opts = {}) {
                 hostname: hostname(),
                 startedAt: Date.now(),
             };
-            await writeFile(join(lockDir, META_FILENAME), JSON.stringify(meta));
+            await writeFile(join(lockDir, META_FILENAME), JSON.stringify(meta), {
+                mode: 0o600,
+            });
             return registerHandle(lockDir);
         }
         catch (err) {
@@ -89,11 +93,16 @@ export async function acquireInstallLock(opts = {}) {
             // Retry once after wait.
             continue;
         }
-        throw new InstallLockHeldError({
-            pid: verdict.meta.pid,
-            hostname: verdict.meta.hostname,
-            ageMs: Date.now() - verdict.meta.startedAt,
-        });
+        if (verdict.kind === "live") {
+            throw new InstallLockHeldError({
+                pid: verdict.meta.pid,
+                hostname: verdict.meta.hostname,
+                ageMs: Date.now() - verdict.meta.startedAt,
+            });
+        }
+        // "held" — present but unverifiable (unreadable meta). Never reclaim:
+        // stealing a possibly-live lock disarms the mutual exclusion.
+        throw new InstallLockHeldError({ pid: -1, hostname: verdict.reason, ageMs: 0 });
     }
     // Both attempts exhausted without acquiring.
     throw new InstallLockHeldError({ pid: -1, hostname: "unknown", ageMs: 0 });
@@ -104,9 +113,26 @@ async function inspectHeldLock(lockDir, maxAgeMs) {
     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" };
+    catch (err) {
+        if (err?.code !== "ENOENT") {
+            // Unreadable-but-present meta is UNVERIFIABLE, not stale: classifying
+            // it stale lets a second process rm -rf a live holder's lock and
+            // disarms the mutual exclusion entirely.
+            return {
+                kind: "held",
+                reason: `meta.json unreadable (${err instanceof Error ? err.message : String(err)})`,
+            };
+        }
+        // Genuinely missing meta: usually a crashed holder — but also the
+        // window between the winner's mkdir and its meta write. Grace-recheck:
+        // a race resolves in milliseconds, a crash leaves it missing forever.
+        await new Promise((r) => setTimeout(r, 250));
+        try {
+            raw = await readFile(metaPath, "utf-8");
+        }
+        catch {
+            return { kind: "stale", reason: "missing-meta" };
+        }
     }
     let meta;
     try {
@@ -175,7 +201,6 @@ function registerHandle(lockDir) {
             if (released)
                 return;
             released = true;
-            heldLockDirs.delete(lockDir);
             try {
                 await unlink(join(lockDir, META_FILENAME));
             }
@@ -185,9 +210,16 @@ function registerHandle(lockDir) {
             try {
                 await rm(lockDir, { recursive: true, force: true });
             }
-            catch {
-                // Best-effort; do not throw from release().
+            catch (err) {
+                // force:true tolerates ENOENT, so this is a REAL failure
+                // (EACCES/EBUSY). Best-effort — never throw from release() — but
+                // say so; a surviving lock blocks the next run until staleness.
+                console.warn(`  ⚠ Could not remove install lock at ${lockDir}: ${err instanceof Error ? err.message : String(err)}`);
             }
+            // Deregister only AFTER the dir is actually gone: a signal landing
+            // mid-release must still find the dir in the set so the sync handler
+            // can clean it (deleting first opened a leak window).
+            heldLockDirs.delete(lockDir);
         },
     };
 }

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

@@ -19,4 +19,19 @@
  * portal, schema breakage) and should surface to the user rather than be
  * papered over as "logged in with no email."
  */
+/**
+ * Recursively delete `__proto__` OWN keys from parsed-JSON data. Our own
+ * merges are spread-based (CreateDataProperty semantics — they cannot be
+ * polluted), but a config we read and write BACK would hand a `__proto__`
+ * own-key to every other consumer of the file, some of which merge with
+ * assign semantics. Strip at the read boundary so the hazard never
+ * round-trips. Mutates in place and returns the input.
+ *
+ * Deliberately __proto__ ONLY: assign-semantics pollution runs through the
+ * `__proto__` setter; own-property `constructor`/`prototype` keys assigned
+ * by Object.assign land as plain data properties and pollute nothing —
+ * while stripping them would silently eat legitimate keys from user configs
+ * (JSON-schema fragments, template maps) on the round-trip.
+ */
+export declare function stripDangerousKeys<T>(value: T): T;
 export declare function extractEmail(body: unknown): string | null;

package/dist/lib/json-guards.js

@@ -19,6 +19,36 @@
  * portal, schema breakage) and should surface to the user rather than be
  * papered over as "logged in with no email."
  */
+/**
+ * Recursively delete `__proto__` OWN keys from parsed-JSON data. Our own
+ * merges are spread-based (CreateDataProperty semantics — they cannot be
+ * polluted), but a config we read and write BACK would hand a `__proto__`
+ * own-key to every other consumer of the file, some of which merge with
+ * assign semantics. Strip at the read boundary so the hazard never
+ * round-trips. Mutates in place and returns the input.
+ *
+ * Deliberately __proto__ ONLY: assign-semantics pollution runs through the
+ * `__proto__` setter; own-property `constructor`/`prototype` keys assigned
+ * by Object.assign land as plain data properties and pollute nothing —
+ * while stripping them would silently eat legitimate keys from user configs
+ * (JSON-schema fragments, template maps) on the round-trip.
+ */
+export function stripDangerousKeys(value) {
+    if (typeof value !== "object" || value === null)
+        return value;
+    if (Array.isArray(value)) {
+        for (const item of value)
+            stripDangerousKeys(item);
+        return value;
+    }
+    const record = value;
+    if (Object.prototype.hasOwnProperty.call(record, "__proto__")) {
+        delete record["__proto__"];
+    }
+    for (const v of Object.values(record))
+        stripDangerousKeys(v);
+    return value;
+}
 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.");

package/dist/lib/manifest.d.ts

@@ -86,5 +86,12 @@ export declare function validateManifest(manifest: Manifest): Promise<ManifestVa
 export declare function loadManifest(): Promise<Manifest | null>;
 /** Save the install manifest to ~/.uluops/manifest.json. Creates directory if needed. */
 export declare function saveManifest(manifest: Manifest): Promise<void>;
-/** Delete the install manifest file from disk. Tries both locations. */
-export declare function deleteManifest(): Promise<void>;
+/**
+ * Delete the install manifest file from disk. Tries both locations.
+ * Returns the paths that could NOT be removed (non-ENOENT failures) so the
+ * caller can report the truth instead of an unconditional success —
+ * a manifest that survives keeps claiming a full install.
+ */
+export declare function deleteManifest(): Promise<{
+    failed: string[];
+}>;

package/dist/lib/manifest.js

@@ -3,6 +3,7 @@ import { join } from "node:path";
 import { getManifestPath, getLegacyManifestPath, getUluopsDir } from "./paths.js";
 import { fileHash } from "./hash.js";
 import { atomicWrite } from "./atomic-write.js";
+import { isEnoent } from "./file-ops.js";
 function isNewManifest(obj) {
     if (typeof obj !== "object" || obj === null)
         return false;
@@ -28,10 +29,25 @@ function isNewManifest(obj) {
         const hm = h;
         if (typeof hm["mcpConfigPath"] !== "string" || typeof hm["defsPath"] !== "string")
             return false;
+        // defsScope is load-bearing (the prev-list inheritance gate branches on
+        // it) — an absent/invalid value reads as a permanent scope flip that
+        // orphans every recorded file. Refuse-by-name like every other shape.
+        if (hm["defsScope"] !== "global" && hm["defsScope"] !== "local")
+            return false;
         if (!Array.isArray(hm["agents"]) || !Array.isArray(hm["commands"]))
             return false;
-        if ("skills" in hm && !Array.isArray(hm["skills"]))
+        // Element typing: a hand-edited agents: [1,2] otherwise reaches
+        // join(dir, file) in uninstall and TypeErrors mid-removal.
+        if (!hm["agents"].every((x) => typeof x === "string"))
+            return false;
+        if (!hm["commands"].every((x) => typeof x === "string"))
             return false;
+        if ("skills" in hm) {
+            if (!Array.isArray(hm["skills"]))
+                return false;
+            if (!hm["skills"].every((x) => typeof x === "string"))
+                return false;
+        }
         if ("partial" in hm) {
             const p = hm["partial"];
             if (p !== null && p !== "agents" && p !== "commands" && p !== "skills" && p !== "metrics") {
@@ -49,6 +65,10 @@ function isLegacyManifest(obj) {
         typeof m["installedAt"] === "string" &&
         typeof m["mcpConfigPath"] === "string" &&
         typeof m["defsPath"] === "string" &&
+        // defsScope is load-bearing post-migration (the inheritance gate
+        // branches on it) — validate here so a bad value hits the
+        // unrecognized-shape refusal instead of migrating to undefined.
+        (m["defsScope"] === "global" || m["defsScope"] === "local") &&
         Array.isArray(m["agents"]) &&
         Array.isArray(m["commands"]) &&
         !("harnesses" in m));
@@ -118,8 +138,15 @@ export async function validateManifest(manifest) {
             raw = await readFile(candidate, "utf-8");
             break;
         }
-        catch {
-            // Try next candidate
+        catch (err) {
+            if (!isEnoent(err)) {
+                // Warning-only path (hash tamper check) — an unreadable candidate
+                // must not masquerade as "no manifest on disk"; name it and skip
+                // the hash check rather than silently treating it as absent.
+                warnings.push(`Cannot read manifest at ${candidate} to verify content hash (${err instanceof Error ? err.message : String(err)})`);
+                break;
+            }
+            // Absent — try next candidate.
         }
     }
     if (raw !== null) {
@@ -166,12 +193,26 @@ async function findMissingFiles(baseDir, subDir, files) {
     return results.filter((r) => !r.exists).map((r) => r.file);
 }
 async function readManifestFile(path) {
+    let raw;
+    try {
+        raw = await readFile(path, "utf-8");
+    }
+    catch (err) {
+        if (isEnoent(err))
+            return null; // genuinely absent
+        // Unreadable-but-PRESENT must never read as "no manifest": loadManifest's
+        // null flows into saveManifest overwriting the file we couldn't read,
+        // orphaning every recorded agent/command/hook — and into uninstall's
+        // "nothing to uninstall". Same class, same rule as the config readers.
+        throw new Error(`Could not read the install manifest at ${path} (${err instanceof Error ? err.message : String(err)}) — refusing to continue rather than overwrite the record of what is installed. Nothing was modified.`);
+    }
     try {
-        const raw = await readFile(path, "utf-8");
         return JSON.parse(raw);
     }
     catch {
-        return null;
+        // Malformed is not absent either: proceeding would rewrite the file and
+        // orphan everything it recorded. Name the path and the way out.
+        throw new Error(`The install manifest at ${path} contains invalid JSON — fix or remove it and re-run. (Detected before any UluOps change; nothing was modified. Removing it makes setup treat this as a fresh install; previously installed files will not be tracked for uninstall.)`);
     }
 }
 /** Load the install manifest. Tries new location first, falls back to legacy, auto-migrates. */
@@ -188,6 +229,13 @@ export async function loadManifest() {
     // Also check if legacy location has new format (written by newer version but not yet moved)
     if (legacyData && isNewManifest(legacyData))
         return legacyData;
+    // A PRESENT file that matches no known shape is the last surviving form
+    // of "read problem means absent": returning null here lets setup build a
+    // fresh manifest and overwrite the record. Refuse by name instead.
+    if (newData !== null || legacyData !== null) {
+        const path = newData !== null ? getManifestPath() : getLegacyManifestPath();
+        throw new Error(`The install manifest at ${path} has an unrecognized shape — fix or remove it and re-run. (Detected before any UluOps change; nothing was modified. Removing it makes setup treat this as a fresh install; previously installed files will not be tracked for uninstall.)`);
+    }
     return null;
 }
 /** Save the install manifest to ~/.uluops/manifest.json. Creates directory if needed. */
@@ -203,14 +251,24 @@ export async function saveManifest(manifest) {
     const final = JSON.stringify({ ...withoutHash, contentHash: hash }, null, 2) + "\n";
     await atomicWrite(getManifestPath(), final);
 }
-/** Delete the install manifest file from disk. Tries both locations. */
+/**
+ * Delete the install manifest file from disk. Tries both locations.
+ * Returns the paths that could NOT be removed (non-ENOENT failures) so the
+ * caller can report the truth instead of an unconditional success —
+ * a manifest that survives keeps claiming a full install.
+ */
 export async function deleteManifest() {
+    const failed = [];
     for (const path of [getManifestPath(), getLegacyManifestPath()]) {
         try {
             await unlink(path);
         }
-        catch {
-            // Already gone
+        catch (err) {
+            if (!isEnoent(err)) {
+                failed.push(`${path} (${err instanceof Error ? err.message : String(err)})`);
+            }
+            // ENOENT — already gone.
         }
     }
+    return { failed };
 }

package/dist/lib/mcp-packages.d.ts

@@ -13,22 +13,24 @@
  * silently picks up a downstream regression; a missed bump shows up as
  * the next setup release stamping the previous combination.
  *
- * The bare package NAMES (without versions) remain available as
- * `MCP_PACKAGES` for the npm availability probe — that probe asks
- * "does this name exist on the registry" not "does this version exist".
- * Pinning the probe to a specific version would turn a temporary
- * registry blip on an older version into a setup failure even when
- * the latest version was reachable.
+ * The availability probe checks the PINNED VERSION, not the bare name.
+ * This used to be deliberate the other way ("a registry blip on an older
+ * version shouldn't fail setup when latest is reachable") — reversed
+ * 2026-08-21: the harness runs `npx -y <PINNED SPEC>`, so the pin being
+ * unresolvable is exactly the condition that must fail loudly at install
+ * time instead of surfacing hours later as an opaque npx error at first
+ * MCP launch. A pin is not a publish; the probe is what enforces that here.
  */
 export declare const OPS_MCP_PACKAGE = "@uluops/ops-mcp";
-export declare const OPS_MCP_VERSION = "0.11.0";
-export declare const OPS_MCP_SPEC: "@uluops/ops-mcp@0.11.0";
+export declare const OPS_MCP_VERSION = "0.17.2";
+export declare const OPS_MCP_SPEC: "@uluops/ops-mcp@0.17.2";
 export declare const REGISTRY_MCP_PACKAGE = "@uluops/registry-mcp";
-export declare const REGISTRY_MCP_VERSION = "0.3.5";
-export declare const REGISTRY_MCP_SPEC: "@uluops/registry-mcp@0.3.5";
-/**
- * Bare package names for the npm availability probe. The probe checks
- * existence on the registry, not version-specific resolvability, so it
- * uses these unversioned names.
- */
+export declare const REGISTRY_MCP_VERSION = "0.3.7";
+export declare const REGISTRY_MCP_SPEC: "@uluops/registry-mcp@0.3.7";
+/** Probe targets: the pinned versions the harness will actually resolve. */
+export declare const MCP_PROBE_TARGETS: readonly {
+    pkg: string;
+    version: string;
+}[];
+/** Bare names, kept for display and for callers that only need identity. */
 export declare const MCP_PACKAGES: readonly string[];

package/dist/lib/mcp-packages.js

@@ -13,24 +13,26 @@
  * silently picks up a downstream regression; a missed bump shows up as
  * the next setup release stamping the previous combination.
  *
- * The bare package NAMES (without versions) remain available as
- * `MCP_PACKAGES` for the npm availability probe — that probe asks
- * "does this name exist on the registry" not "does this version exist".
- * Pinning the probe to a specific version would turn a temporary
- * registry blip on an older version into a setup failure even when
- * the latest version was reachable.
+ * The availability probe checks the PINNED VERSION, not the bare name.
+ * This used to be deliberate the other way ("a registry blip on an older
+ * version shouldn't fail setup when latest is reachable") — reversed
+ * 2026-08-21: the harness runs `npx -y <PINNED SPEC>`, so the pin being
+ * unresolvable is exactly the condition that must fail loudly at install
+ * time instead of surfacing hours later as an opaque npx error at first
+ * MCP launch. A pin is not a publish; the probe is what enforces that here.
  */
 export const OPS_MCP_PACKAGE = "@uluops/ops-mcp";
-export const OPS_MCP_VERSION = "0.11.0";
+export const OPS_MCP_VERSION = "0.17.2";
 export const OPS_MCP_SPEC = `${OPS_MCP_PACKAGE}@${OPS_MCP_VERSION}`;
 export const REGISTRY_MCP_PACKAGE = "@uluops/registry-mcp";
-export const REGISTRY_MCP_VERSION = "0.3.5";
+export const REGISTRY_MCP_VERSION = "0.3.7";
 export const REGISTRY_MCP_SPEC = `${REGISTRY_MCP_PACKAGE}@${REGISTRY_MCP_VERSION}`;
-/**
- * Bare package names for the npm availability probe. The probe checks
- * existence on the registry, not version-specific resolvability, so it
- * uses these unversioned names.
- */
+/** Probe targets: the pinned versions the harness will actually resolve. */
+export const MCP_PROBE_TARGETS = [
+    { pkg: OPS_MCP_PACKAGE, version: OPS_MCP_VERSION },
+    { pkg: REGISTRY_MCP_PACKAGE, version: REGISTRY_MCP_VERSION },
+];
+/** Bare names, kept for display and for callers that only need identity. */
 export const MCP_PACKAGES = [
     OPS_MCP_PACKAGE,
     REGISTRY_MCP_PACKAGE,

package/dist/lib/settings-merger.js

@@ -6,6 +6,8 @@
  */
 import { readFile } from "node:fs/promises";
 import { atomicWrite } from "./atomic-write.js";
+import { stripDangerousKeys } from "./json-guards.js";
+import { isEnoent } from "./file-ops.js";
 /**
  * Substring used purely as an *ownership sentinel* — present in every hook
  * command we install, so we can identify our own entries in `settings.json`
@@ -68,15 +70,41 @@ export async function readSettings(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 must never read as fresh (see isEnoent's doc).
+        throw new Error(`Could not read settings 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 settings 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 settings 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 above: a shape we can't merge into must
+    // surface, not crash mid-merge or silently corrupt on spread. Valid JSON
+    // that isn't an object (or whose hooks aren't matcher arrays) is treated
+    // as unmergeable, not coerced.
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new Error(`Failed to parse settings at ${path} — expected a JSON object at the top level`);
+    }
+    const hooks = parsed.hooks;
+    if (hooks !== undefined) {
+        const hooksValid = typeof hooks === "object" &&
+            hooks !== null &&
+            !Array.isArray(hooks) &&
+            Object.values(hooks).every((v) => Array.isArray(v) &&
+                v.every((m) => typeof m === "object" && m !== null));
+        if (!hooksValid) {
+            throw new Error(`Failed to parse settings at ${path} — 'hooks' has an unexpected shape; fix or remove it and re-run`);
+        }
     }
+    return stripDangerousKeys(parsed);
 }
 /**
  * Write settings back to file with stable formatting.
@@ -86,6 +114,22 @@ export async function writeSettings(path, settings) {
         mode: 0o600,
     });
 }
+/**
+ * True when a matcher entry is a UluOps-owned hook. THE single ownership
+ * predicate — merge, remove, and has must all use it, or they disagree on
+ * malformed shapes (the exact defect this replaced: merge was defensive
+ * while remove/has dereferenced m.hooks unguarded and crashed uninstall/
+ * verify on hand-edited files). Defensive by design: readSettings' gate
+ * deliberately tolerates unknown-shaped user entries (no hooks array,
+ * non-string commands) so the merge can preserve them — anything not
+ * positively identifiable as ours is user data: preserved by remove,
+ * invisible to has, never a crash.
+ */
+function isUluopsMatcher(m) {
+    return (Array.isArray(m?.hooks) &&
+        m.hooks.some((h) => typeof h?.command === "string" &&
+            h.command.includes(HOOK_OWNERSHIP_SIGNATURE)));
+}
 /**
  * Merge the UluOps hook into settings, preserving all other
  * hooks and settings. If a UluOps hook already exists, it is replaced.
@@ -94,7 +138,7 @@ export function mergeUluopsHook(settings, hookCommand, hookTypeOverride, matcher
     const hookType = hookTypeOverride ?? getDefaultHookEventType();
     const hooks = settings.hooks ?? {};
     const existing = hooks[hookType] ?? [];
-    const filtered = existing.filter((m) => !m.hooks.some((h) => h.command.includes(HOOK_OWNERSHIP_SIGNATURE)));
+    const filtered = existing.filter((m) => !isUluopsMatcher(m));
     const uluopsHook = {
         hooks: [
             {
@@ -125,9 +169,9 @@ export function removeUluopsHook(settings, hookTypeOverride) {
     if (!hooks)
         return settings;
     const hookEntries = hooks[hookType];
-    if (!hookEntries)
+    if (!Array.isArray(hookEntries))
         return settings;
-    const filtered = hookEntries.filter((m) => !m.hooks.some((h) => h.command.includes(HOOK_OWNERSHIP_SIGNATURE)));
+    const filtered = hookEntries.filter((m) => !isUluopsMatcher(m));
     const updatedHooks = { ...hooks };
     if (filtered.length === 0) {
         delete updatedHooks[hookType];
@@ -150,7 +194,7 @@ export function removeUluopsHook(settings, hookTypeOverride) {
 export function hasUluopsHook(settings, hookTypeOverride) {
     const hookType = hookTypeOverride ?? getDefaultHookEventType();
     const hookEntries = settings.hooks?.[hookType];
-    if (!hookEntries)
+    if (!Array.isArray(hookEntries))
         return false;
-    return hookEntries.some((m) => m.hooks.some((h) => h.command.includes(HOOK_OWNERSHIP_SIGNATURE)));
+    return hookEntries.some(isUluopsMatcher);
 }