nccgs 2.1.0 → 2.1.1

package/scripts/uninstall.mjs

@@ -1,292 +1,292 @@
-import fs from "node:fs";
-import path from "node:path";
-import crypto from "node:crypto";
-import { fileURLToPath } from "node:url";
-import { assertProjectRoot, assertRelativePath, containedPath } from "../.claude/nccgs/tools/paths.mjs";
-import { matchesFingerprint, equivalentBuffers, sha256 } from "../.claude/nccgs/tools/integrity.mjs";
-import { canonicalHookCommand } from "../.claude/nccgs/tools/autonomy.mjs";
-import { acquireLock, ownerState } from "../.claude/nccgs/tools/process-lock.mjs";
-import { assertInstallationAvailable } from "../.claude/nccgs/tools/installation-guard.mjs";
-
-const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
-const statePath = ".claude/nccgs/install-state.json";
-const lockPath = ".nccgs/uninstall.lock";
-const need = (ok, message) => { if (!ok) throw new Error(message); };
-const object = value => value !== null && typeof value === "object" && !Array.isArray(value);
-const digest = value => typeof value === "string" && /^[a-f0-9]{64}$/.test(value);
-const read = file => JSON.parse(fs.readFileSync(file, "utf8"));
-
-function files(project, relative) {
-  const directory = containedPath(project, relative);
-  if (!fs.existsSync(directory)) return [];
-  need(fs.statSync(directory).isDirectory(), `Expected a directory: ${relative}`);
-  return fs.readdirSync(directory, { withFileTypes: true }).flatMap(entry => {
-    const name = `${relative}/${entry.name}`, file = containedPath(project, name);
-    if (entry.isDirectory()) return files(project, name);
-    need(entry.isFile() && fs.statSync(file).isFile(), `Unsupported entry: ${name}`);
-    return [name];
-  });
-}
-
-// Read only: do not settle/recover a job, rewrite a task, reclaim an old lock or
-// terminate a process merely to make uninstallation possible.
-export function assertUninstallIdle(project, ownToken = null) {
-  need(!(process.env.CLAUDECODE || process.env.CLAUDE_CODE_ENTRYPOINT || process.env.NCCGS_SUPERVISED_SESSION),
-    "Close Claude Code and run uninstall from an external terminal.");
-  const at = relative => containedPath(project, relative);
-  const candidates = [...[".nccgs/orchestration.lock", ".nccgs/measurement-start.lock", lockPath].flatMap(name => [name, `${name}.recovery`]),
-    ...[".nccgs/tasks", ".nccgs/jobs", ".nccgs/runs", ".nccgs/sessions"].flatMap(dir => files(project, dir))];
-  for (const relative of candidates.filter(name => /\.lock(?:\.recovery)?$/.test(name))) {
-    if (!fs.existsSync(at(relative))) continue;
-    const lock = read(at(relative));
-    if (relative === lockPath && ownToken && lock.token === ownToken) continue;
-    need(ownerState(lock) === "dead", `Cannot uninstall: active or unverified process lock ${relative}. Stop/recover the owning work first.${relative.startsWith(".nccgs/sessions/") && lock.operation === "nccgs-run" ? " For a crashed launcher, see recover-session --dry-run and docs/UNINSTALL.md; never infer descendant shutdown from PID death." : ""}`);
-  }
-  const ledger = at(".nccgs/orchestration.json");
-  if (fs.existsSync(ledger)) {
-    const value = read(ledger);
-    need(object(value.dispatches), "Invalid dispatch ledger; inspect it before uninstalling.");
-    for (const dispatch of Object.values(value.dispatches)) {
-      need(object(dispatch) && ["completed", "failed", "cancelled"].includes(dispatch.status),
-        `Cannot uninstall: dispatch ${dispatch?.id ?? "unknown"} is active or unverified.`);
-    }
-  }
-  for (const relative of candidates.filter(name => /^\.nccgs\/jobs\/[^/]+\/request\.json$/.test(name))) {
-    const result = at(relative.replace(/request\.json$/, "result.json"));
-    need(fs.existsSync(result) && ["PASS", "FAIL"].includes(read(result).status), `Cannot uninstall: unsettled verification job ${relative}.`);
-  }
-  for (const relative of candidates.filter(name => /^\.nccgs\/runs\/[^/]+\/run\.json$/.test(name))) {
-    const run = read(at(relative));
-    need(["ready", "settled", "blocked"].includes(run.status) && Array.isArray(run.invocations)
-      && run.invocations.every(item => ["finished", "recovered"].includes(item.status)), `Cannot uninstall: active or unverified run ${relative}.`);
-  }
-}
-
-function catalog() {
-  const known = new Set(files(root, ".claude"));
-  known.add(".claude/skills/setup-vivox-voice-chat/evals/.gitignore");
-  const studio = read(path.join(root, ".claude/nccgs/studio.json"));
-  for (const agent of studio.agents) known.add(`.claude/agents/${agent.name}.md`);
-  return known;
-}
-
-function removeHooks(text) {
-  const settings = JSON.parse(text);
-  need(object(settings), "Claude settings must be an object.");
-  if (settings.hooks === undefined) return text;
-  need(object(settings.hooks), "Invalid Claude hooks; no files were removed.");
-  const fragment = read(path.join(root, ".claude/nccgs/settings.fragment.json"));
-  const commands = new Set(Object.values(fragment.hooks).flatMap(groups => groups.flatMap(g => g.hooks))
-    .map(hook => canonicalHookCommand(hook.command)));
-  let changed = false;
-  for (const [event, groups] of Object.entries(settings.hooks)) {
-    need(Array.isArray(groups), `Invalid hook groups: ${event}`);
-    settings.hooks[event] = groups.flatMap(group => {
-      need(object(group) && Array.isArray(group.hooks), `Invalid hook group: ${event}`);
-      const hooks = group.hooks.filter(hook => {
-        need(object(hook), `Invalid hook: ${event}`);
-        if (hook.type !== "command" || typeof hook.command !== "string") return true;
-        if (commands.has(canonicalHookCommand(hook.command))) { changed = true; return false; }
-        need(!/[\\/]\.claude[\\/]nccgs[\\/]|\.claude[\\/]nccgs[\\/]/i.test(hook.command),
-          `Customized NCCGS hook in ${event}; separate/remove it manually before uninstalling.`);
-        return true;
-      });
-      // Keep unrelated hooks and their matcher/timeout/metadata, even when they
-      // share a group with a framework hook.
-      return hooks.length || !group.hooks.length ? [{ ...group, hooks }] : [];
-    });
-    if (!settings.hooks[event].length && groups.length) delete settings.hooks[event];
-  }
-  if (!Object.keys(settings.hooks).length) delete settings.hooks;
-  // Old installers did not record ownership of generic deny/model preferences.
-  // Preserve those shared settings instead of guessing which values to remove.
-  return changed ? `${JSON.stringify(settings, null, 2)}\n` : text;
-}
-
-function removeImport(buffer) {
-  if (equivalentBuffers(buffer, fs.readFileSync(path.join(root, "CLAUDE.md")))) return null;
-  const text = buffer.toString("utf8");
-  need(Buffer.from(text, "utf8").equals(buffer), "CLAUDE.md must be UTF-8 to remove the NCCGS import safely.");
-  const next = text.replace(/^<!-- NCCGS:BEGIN -->\r?\n@\.claude\/nccgs\/constitution\.md\r?\n<!-- NCCGS:END -->(?:\r?\n|$)/gm, "")
-    .replace(/^[ \t]*@\.claude\/nccgs\/constitution\.md[ \t]*(?:\r?\n|$)/gm, "");
-  need(!/@\.claude\/nccgs\//.test(next), "Customized NCCGS import in CLAUDE.md; remove it manually before uninstalling.");
-  return Buffer.from(next, "utf8");
-}
-
-export function planUninstall(project, ownToken = null) {
-  project = assertProjectRoot(project);
-  need(fs.realpathSync(project) !== fs.realpathSync(root), "The NCCGS package cannot uninstall itself.");
-  assertUninstallIdle(project, ownToken);
-  const at = relative => containedPath(project, relative), known = catalog(), file = at(statePath);
-  if (!fs.existsSync(file)) return { project, status: "NOT_INSTALLED", changes: [], preserved: [], warnings: [] };
-  const state = read(file);
-  need([1, 2, 3].includes(state.schemaVersion) && Array.isArray(state.files) && typeof state.frameworkVersion === "string", "Invalid install state; refuse unsafe cleanup.");
-  const managed = new Map(), aliases = new Set();
-  for (const item of state.files) {
-    const relative = assertRelativePath(item.relative);
-    need(relative.startsWith(".claude/") && ![".claude/settings.json", ".claude/settings.local.json", statePath].includes(relative), `Unsafe managed path: ${relative}`);
-    need(digest(item.sha256) && (item.canonicalSha256 === undefined || digest(item.canonicalSha256)), `Invalid managed fingerprint: ${relative}`);
-    need(!aliases.has(relative.toLowerCase()), `Duplicate managed path: ${relative}`);
-    aliases.add(relative.toLowerCase()); at(relative); managed.set(relative, item);
-  }
-  const activationPath = at(".nccgs/agent-activation.json");
-  if (fs.existsSync(activationPath)) {
-    const activation = read(activationPath);
-    need(activation.schemaVersion === 1 && object(activation.generated), "Invalid generated-agent inventory.");
-    for (const [relative, hash] of Object.entries(activation.generated)) {
-      need(known.has(relative) && /^\.claude\/agents\/nccgs-[\w-]+\.md$/.test(relative) && digest(hash), `Unsafe generated agent: ${relative}`);
-      at(relative);
-      // Profile/optional-agent configuration can be newer than install-state.
-      const canonicalSha256 = activation.generatedCanonical?.[relative];
-      need(canonicalSha256 === undefined || digest(canonicalSha256), `Invalid generated-agent fingerprint: ${relative}`);
-      managed.set(relative, { sha256: hash, ...(canonicalSha256 ? { canonicalSha256 } : {}) });
-    }
-  }
-  const changes = [], preserved = [], warnings = [];
-  const change = (relative, after) => {
-    const current = fs.readFileSync(at(relative));
-    if (after !== null && current.equals(after)) return;
-    changes.push({ path: relative, before: sha256(current), after: after === null ? null : sha256(after), bytes: current, output: after });
-  };
-  for (const [relative, fingerprint] of managed) {
-    if (!fs.existsSync(at(relative))) continue;
-    need(fs.statSync(at(relative)).isFile(), `Managed target is not a file: ${relative}`);
-    if (!known.has(relative)) { preserved.push({ path: relative, reason: "Not in this package's trusted file catalog" }); continue; }
-    if (!matchesFingerprint(at(relative), fingerprint)) { preserved.push({ path: relative, reason: "Locally modified or pre-existing override" }); continue; }
-    change(relative, null);
-  }
-  if (fs.existsSync(at(".claude/settings.json"))) change(".claude/settings.json", Buffer.from(removeHooks(fs.readFileSync(at(".claude/settings.json"), "utf8"))));
-  if (fs.existsSync(at("CLAUDE.md"))) change("CLAUDE.md", removeImport(fs.readFileSync(at("CLAUDE.md"))));
-  // Removing this marker last makes repeated uninstall a no-op and stops run.
-  change(statePath, null);
-  warnings.push("Project .nccgs history, budgets, policy, backups and generic Claude permission/model settings are retained.");
-  if (preserved.length) warnings.push("Modified/unknown managed files remain in place; inspect the preserved list before removing them manually.");
-  return { project, status: "PLANNED", frameworkVersion: state.frameworkVersion, changes, preserved, warnings };
-}
-
-function manifestPath(id) {
-  need(/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/.test(id), "Rollback requires the printed uninstall UUID.");
-  return `.nccgs/uninstall/${id}/manifest.json`;
-}
-
-function writeManifest(project, relative, value) {
-  const temporary = `${relative}.${crypto.randomUUID()}.tmp`;
-  fs.writeFileSync(containedPath(project, temporary), JSON.stringify(value, null, 2) + "\n", { flag: "wx" });
-  fs.renameSync(containedPath(project, temporary), containedPath(project, relative));
-}
-
-export function restoreUninstall(project, id, { dryRun = false, ownToken = null } = {}) {
-  project = assertProjectRoot(project); assertUninstallIdle(project, ownToken);
-  const relative = manifestPath(id), manifest = read(containedPath(project, relative));
-  need(manifest.schemaVersion === 1 && manifest.kind === "nccgs-uninstall" && manifest.id === id
-    && ["prepared", "applying", "completed", "restoring", "failed"].includes(manifest.status) && Array.isArray(manifest.files), "Invalid or already restored uninstall receipt.");
-  const known = catalog(), aliases = new Set(), restores = [];
-  for (const item of manifest.files) {
-    assertRelativePath(item.path);
-    need(known.has(item.path) || [statePath, "CLAUDE.md", ".claude/settings.json"].includes(item.path), `Unsafe rollback path: ${item.path}`);
-    need(!aliases.has(item.path.toLowerCase()) && digest(item.before) && (item.after === null || digest(item.after)), "Invalid rollback record.");
-    aliases.add(item.path.toLowerCase());
-    const destination = containedPath(project, item.path), backup = containedPath(project, `.nccgs/uninstall/${id}/files/${item.path}`);
-    const bytes = fs.readFileSync(backup); need(sha256(bytes) === item.before, `Changed rollback backup: ${item.path}`);
-    const current = fs.existsSync(destination) ? sha256(fs.readFileSync(destination)) : null;
-    need(current === item.before || current === item.after, `File changed after uninstall; refusing to overwrite: ${item.path}`);
-    if (current !== item.before) restores.push({ ...item, bytes });
-  }
-  if (dryRun) return { status: "ROLLBACK_PREVIEW", id, restoredFiles: restores.map(x => x.path) };
-  manifest.status = "restoring"; writeManifest(project, relative, manifest);
-  for (const item of restores) {
-    const file = containedPath(project, item.path), current = fs.existsSync(file) ? sha256(fs.readFileSync(file)) : null;
-    need(current === item.after, `Concurrent change during rollback: ${item.path}`);
-    fs.mkdirSync(path.dirname(file), { recursive: true });
-    fs.writeFileSync(containedPath(project, item.path), item.bytes, { flag: item.after === null ? "wx" : "w" });
-  }
-  manifest.status = "restored"; manifest.restoredAt = new Date().toISOString(); writeManifest(project, relative, manifest);
-  return { status: "RESTORED", id, restoredFiles: restores.map(x => x.path) };
-}
-
-export function uninstall(project, { dryRun = false, rollback = null } = {}) {
-  project = assertProjectRoot(project);
-  need(fs.realpathSync(project) !== fs.realpathSync(root), "The NCCGS package cannot uninstall itself.");
-  if (!rollback) assertInstallationAvailable(project);
-  if (dryRun) return rollback ? restoreUninstall(project, rollback, { dryRun: true }) : summary(planUninstall(project));
-  assertUninstallIdle(project);
-  if (!rollback && !fs.existsSync(containedPath(project, statePath))) return summary(planUninstall(project));
-  const lock = acquireLock(containedPath(project, lockPath), { operation: "uninstall" });
-  try {
-    if (rollback) return restoreUninstall(project, rollback, { ownToken: lock.record.token });
-    // Planning is read-only, with our own lock explicitly recognized.
-    const plan = planUninstall(project, lock.record.token);
-    const id = crypto.randomUUID(), relative = manifestPath(id), directory = path.dirname(containedPath(project, relative));
-    for (const item of plan.changes) {
-      const file = containedPath(project, `.nccgs/uninstall/${id}/files/${item.path}`);
-      fs.mkdirSync(path.dirname(file), { recursive: true });
-      fs.writeFileSync(containedPath(project, `.nccgs/uninstall/${id}/files/${item.path}`), item.bytes, { flag: "wx" });
-    }
-    fs.mkdirSync(directory, { recursive: true });
-    const manifest = { schemaVersion: 1, kind: "nccgs-uninstall", id, frameworkVersion: plan.frameworkVersion,
-      createdAt: new Date().toISOString(), status: "prepared", files: plan.changes.map(({ path, before, after }) => ({ path, before, after })),
-      preserved: plan.preserved, warnings: plan.warnings };
-    writeManifest(project, relative, manifest);
-    let mutationStarted = false;
-    try {
-      assertUninstallIdle(project, lock.record.token);
-      for (const item of plan.changes) need(sha256(fs.readFileSync(containedPath(project, item.path))) === item.before, `Concurrent change before uninstall: ${item.path}`);
-      manifest.status = "applying"; writeManifest(project, relative, manifest);
-      for (const item of plan.changes) {
-        const file = containedPath(project, item.path);
-        need(sha256(fs.readFileSync(file)) === item.before, `Concurrent change during uninstall: ${item.path}`);
-        mutationStarted = true;
-        if (item.output === null) fs.unlinkSync(containedPath(project, item.path));
-        else fs.writeFileSync(containedPath(project, item.path), item.output);
-      }
-      manifest.status = "completed"; manifest.completedAt = new Date().toISOString(); writeManifest(project, relative, manifest);
-    } catch (error) {
-      if (!mutationStarted) {
-        manifest.status = "cancelled"; manifest.error = error.message; manifest.cancelledAt = new Date().toISOString();
-        writeManifest(project, relative, manifest);
-        throw new Error(`${error.message}; uninstall cancelled before changing files; receipt ${relative}`);
-      }
-      manifest.status = "failed"; manifest.error = error.message; writeManifest(project, relative, manifest);
-      try { restoreUninstall(project, id, { ownToken: lock.record.token }); }
-      catch (restoreError) { throw new Error(`${error.message}; backup ${relative}; recovery requires inspection: ${restoreError.message}`); }
-      throw new Error(`${error.message}; all planned files restored from ${relative}`);
-    }
-    // Only empty directories derived from individually checked managed paths.
-    const directories = new Set();
-    for (const item of plan.changes.filter(x => x.output === null && x.path.startsWith(".claude/"))) {
-      let dir = path.posix.dirname(item.path);
-      while (dir.startsWith(".claude/")) { directories.add(dir); dir = path.posix.dirname(dir); }
-    }
-    const cleanupWarnings = [];
-    for (const dir of [...directories].sort((a, b) => b.length - a.length)) {
-      try { fs.rmdirSync(containedPath(project, dir)); }
-      catch (error) {
-        if (!["ENOENT", "ENOTEMPTY", "EEXIST"].includes(error.code))
-          cleanupWarnings.push(`Empty-directory cleanup skipped for ${dir}: ${error.code || error.message}`);
-      }
-    }
-    return { ...summary(plan), warnings: [...plan.warnings, ...cleanupWarnings], status: plan.preserved.length ? "UNINSTALLED_WITH_PRESERVED_FILES" : "UNINSTALLED", id, backup: relative };
-  } finally { lock.release(); }
-}
-
-function summary(plan) {
-  return { project: plan.project, status: plan.status, frameworkVersion: plan.frameworkVersion,
-    remove: plan.changes.filter(x => x.after === null).map(x => x.path),
-    edit: plan.changes.filter(x => x.after !== null).map(x => x.path), preserved: plan.preserved, warnings: plan.warnings };
-}
-
-if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
-  try {
-    let project = process.cwd(), dryRun = false, rollback = null;
-    const args = process.argv.slice(2), seen = new Set();
-    for (let i = 0; i < args.length; i++) {
-      const arg = args[i]; need(!seen.has(arg), `Duplicate option: ${arg}`); seen.add(arg);
-      if (arg === "--dry-run") dryRun = true;
-      else if (["--project", "--rollback"].includes(arg)) {
-        const value = args[++i]; need(value && !value.startsWith("--"), `${arg} requires a value`);
-        if (arg === "--project") project = path.resolve(value); else rollback = value;
-      } else throw new Error(`Unknown uninstall option: ${arg}`);
-    }
-    console.log(JSON.stringify(uninstall(project, { dryRun, rollback }), null, 2));
-  } catch (error) { console.error(`NCCGS uninstall refused: ${error.message}`); process.exitCode = 1; }
-}
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import { fileURLToPath } from "node:url";
+import { assertProjectRoot, assertRelativePath, containedPath } from "../.claude/nccgs/tools/paths.mjs";
+import { matchesFingerprint, equivalentBuffers, sha256 } from "../.claude/nccgs/tools/integrity.mjs";
+import { managedHookKey, referencesNccgsHook } from "../.claude/nccgs/tools/hook-transport.mjs";
+import { acquireLock, ownerState } from "../.claude/nccgs/tools/process-lock.mjs";
+import { assertInstallationAvailable } from "../.claude/nccgs/tools/installation-guard.mjs";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const statePath = ".claude/nccgs/install-state.json";
+const lockPath = ".nccgs/uninstall.lock";
+const need = (ok, message) => { if (!ok) throw new Error(message); };
+const object = value => value !== null && typeof value === "object" && !Array.isArray(value);
+const digest = value => typeof value === "string" && /^[a-f0-9]{64}$/.test(value);
+const read = file => JSON.parse(fs.readFileSync(file, "utf8"));
+
+function files(project, relative) {
+  const directory = containedPath(project, relative);
+  if (!fs.existsSync(directory)) return [];
+  need(fs.statSync(directory).isDirectory(), `Expected a directory: ${relative}`);
+  return fs.readdirSync(directory, { withFileTypes: true }).flatMap(entry => {
+    const name = `${relative}/${entry.name}`, file = containedPath(project, name);
+    if (entry.isDirectory()) return files(project, name);
+    need(entry.isFile() && fs.statSync(file).isFile(), `Unsupported entry: ${name}`);
+    return [name];
+  });
+}
+
+// Read only: do not settle/recover a job, rewrite a task, reclaim an old lock or
+// terminate a process merely to make uninstallation possible.
+export function assertUninstallIdle(project, ownToken = null) {
+  need(!(process.env.CLAUDECODE || process.env.CLAUDE_CODE_ENTRYPOINT || process.env.NCCGS_SUPERVISED_SESSION),
+    "Close Claude Code and run uninstall from an external terminal.");
+  const at = relative => containedPath(project, relative);
+  const candidates = [...[".nccgs/orchestration.lock", ".nccgs/measurement-start.lock", lockPath].flatMap(name => [name, `${name}.recovery`]),
+    ...[".nccgs/tasks", ".nccgs/jobs", ".nccgs/runs", ".nccgs/sessions"].flatMap(dir => files(project, dir))];
+  for (const relative of candidates.filter(name => /\.lock(?:\.recovery)?$/.test(name))) {
+    if (!fs.existsSync(at(relative))) continue;
+    const lock = read(at(relative));
+    if (relative === lockPath && ownToken && lock.token === ownToken) continue;
+    need(ownerState(lock) === "dead", `Cannot uninstall: active or unverified process lock ${relative}. Stop/recover the owning work first.${relative.startsWith(".nccgs/sessions/") && lock.operation === "nccgs-run" ? " For a crashed launcher, see recover-session --dry-run and docs/UNINSTALL.md; never infer descendant shutdown from PID death." : ""}`);
+  }
+  const ledger = at(".nccgs/orchestration.json");
+  if (fs.existsSync(ledger)) {
+    const value = read(ledger);
+    need(object(value.dispatches), "Invalid dispatch ledger; inspect it before uninstalling.");
+    for (const dispatch of Object.values(value.dispatches)) {
+      need(object(dispatch) && ["completed", "failed", "cancelled"].includes(dispatch.status),
+        `Cannot uninstall: dispatch ${dispatch?.id ?? "unknown"} is active or unverified.`);
+    }
+  }
+  for (const relative of candidates.filter(name => /^\.nccgs\/jobs\/[^/]+\/request\.json$/.test(name))) {
+    const result = at(relative.replace(/request\.json$/, "result.json"));
+    need(fs.existsSync(result) && ["PASS", "FAIL"].includes(read(result).status), `Cannot uninstall: unsettled verification job ${relative}.`);
+  }
+  for (const relative of candidates.filter(name => /^\.nccgs\/runs\/[^/]+\/run\.json$/.test(name))) {
+    const run = read(at(relative));
+    need(["ready", "settled", "blocked"].includes(run.status) && Array.isArray(run.invocations)
+      && run.invocations.every(item => ["finished", "recovered"].includes(item.status)), `Cannot uninstall: active or unverified run ${relative}.`);
+  }
+}
+
+function catalog() {
+  const known = new Set(files(root, ".claude"));
+  known.add(".claude/skills/setup-vivox-voice-chat/evals/.gitignore");
+  const studio = read(path.join(root, ".claude/nccgs/studio.json"));
+  for (const agent of studio.agents) known.add(`.claude/agents/${agent.name}.md`);
+  return known;
+}
+
+function removeHooks(text) {
+  const settings = JSON.parse(text);
+  need(object(settings), "Claude settings must be an object.");
+  if (settings.hooks === undefined) return text;
+  need(object(settings.hooks), "Invalid Claude hooks; no files were removed.");
+  const fragment = read(path.join(root, ".claude/nccgs/settings.fragment.json"));
+  const commands = new Set(Object.values(fragment.hooks).flatMap(groups => groups.flatMap(g => g.hooks))
+    .map(managedHookKey).filter(Boolean));
+  let changed = false;
+  for (const [event, groups] of Object.entries(settings.hooks)) {
+    need(Array.isArray(groups), `Invalid hook groups: ${event}`);
+    settings.hooks[event] = groups.flatMap(group => {
+      need(object(group) && Array.isArray(group.hooks), `Invalid hook group: ${event}`);
+      const hooks = group.hooks.filter(hook => {
+        need(object(hook), `Invalid hook: ${event}`);
+        if (hook.type !== "command" || typeof hook.command !== "string") return true;
+        if (commands.has(managedHookKey(hook))) { changed = true; return false; }
+        need(!referencesNccgsHook(hook),
+          `Customized NCCGS hook in ${event}; separate/remove it manually before uninstalling.`);
+        return true;
+      });
+      // Keep unrelated hooks and their matcher/timeout/metadata, even when they
+      // share a group with a framework hook.
+      return hooks.length || !group.hooks.length ? [{ ...group, hooks }] : [];
+    });
+    if (!settings.hooks[event].length && groups.length) delete settings.hooks[event];
+  }
+  if (!Object.keys(settings.hooks).length) delete settings.hooks;
+  // Old installers did not record ownership of generic deny/model preferences.
+  // Preserve those shared settings instead of guessing which values to remove.
+  return changed ? `${JSON.stringify(settings, null, 2)}\n` : text;
+}
+
+function removeImport(buffer) {
+  if (equivalentBuffers(buffer, fs.readFileSync(path.join(root, "CLAUDE.md")))) return null;
+  const text = buffer.toString("utf8");
+  need(Buffer.from(text, "utf8").equals(buffer), "CLAUDE.md must be UTF-8 to remove the NCCGS import safely.");
+  const next = text.replace(/^<!-- NCCGS:BEGIN -->\r?\n@\.claude\/nccgs\/constitution\.md\r?\n<!-- NCCGS:END -->(?:\r?\n|$)/gm, "")
+    .replace(/^[ \t]*@\.claude\/nccgs\/constitution\.md[ \t]*(?:\r?\n|$)/gm, "");
+  need(!/@\.claude\/nccgs\//.test(next), "Customized NCCGS import in CLAUDE.md; remove it manually before uninstalling.");
+  return Buffer.from(next, "utf8");
+}
+
+export function planUninstall(project, ownToken = null) {
+  project = assertProjectRoot(project);
+  need(fs.realpathSync(project) !== fs.realpathSync(root), "The NCCGS package cannot uninstall itself.");
+  assertUninstallIdle(project, ownToken);
+  const at = relative => containedPath(project, relative), known = catalog(), file = at(statePath);
+  if (!fs.existsSync(file)) return { project, status: "NOT_INSTALLED", changes: [], preserved: [], warnings: [] };
+  const state = read(file);
+  need([1, 2, 3].includes(state.schemaVersion) && Array.isArray(state.files) && typeof state.frameworkVersion === "string", "Invalid install state; refuse unsafe cleanup.");
+  const managed = new Map(), aliases = new Set();
+  for (const item of state.files) {
+    const relative = assertRelativePath(item.relative);
+    need(relative.startsWith(".claude/") && ![".claude/settings.json", ".claude/settings.local.json", statePath].includes(relative), `Unsafe managed path: ${relative}`);
+    need(digest(item.sha256) && (item.canonicalSha256 === undefined || digest(item.canonicalSha256)), `Invalid managed fingerprint: ${relative}`);
+    need(!aliases.has(relative.toLowerCase()), `Duplicate managed path: ${relative}`);
+    aliases.add(relative.toLowerCase()); at(relative); managed.set(relative, item);
+  }
+  const activationPath = at(".nccgs/agent-activation.json");
+  if (fs.existsSync(activationPath)) {
+    const activation = read(activationPath);
+    need(activation.schemaVersion === 1 && object(activation.generated), "Invalid generated-agent inventory.");
+    for (const [relative, hash] of Object.entries(activation.generated)) {
+      need(known.has(relative) && /^\.claude\/agents\/nccgs-[\w-]+\.md$/.test(relative) && digest(hash), `Unsafe generated agent: ${relative}`);
+      at(relative);
+      // Profile/optional-agent configuration can be newer than install-state.
+      const canonicalSha256 = activation.generatedCanonical?.[relative];
+      need(canonicalSha256 === undefined || digest(canonicalSha256), `Invalid generated-agent fingerprint: ${relative}`);
+      managed.set(relative, { sha256: hash, ...(canonicalSha256 ? { canonicalSha256 } : {}) });
+    }
+  }
+  const changes = [], preserved = [], warnings = [];
+  const change = (relative, after) => {
+    const current = fs.readFileSync(at(relative));
+    if (after !== null && current.equals(after)) return;
+    changes.push({ path: relative, before: sha256(current), after: after === null ? null : sha256(after), bytes: current, output: after });
+  };
+  for (const [relative, fingerprint] of managed) {
+    if (!fs.existsSync(at(relative))) continue;
+    need(fs.statSync(at(relative)).isFile(), `Managed target is not a file: ${relative}`);
+    if (!known.has(relative)) { preserved.push({ path: relative, reason: "Not in this package's trusted file catalog" }); continue; }
+    if (!matchesFingerprint(at(relative), fingerprint)) { preserved.push({ path: relative, reason: "Locally modified or pre-existing override" }); continue; }
+    change(relative, null);
+  }
+  if (fs.existsSync(at(".claude/settings.json"))) change(".claude/settings.json", Buffer.from(removeHooks(fs.readFileSync(at(".claude/settings.json"), "utf8"))));
+  if (fs.existsSync(at("CLAUDE.md"))) change("CLAUDE.md", removeImport(fs.readFileSync(at("CLAUDE.md"))));
+  // Removing this marker last makes repeated uninstall a no-op and stops run.
+  change(statePath, null);
+  warnings.push("Project .nccgs history, budgets, policy, backups and generic Claude permission/model settings are retained.");
+  if (preserved.length) warnings.push("Modified/unknown managed files remain in place; inspect the preserved list before removing them manually.");
+  return { project, status: "PLANNED", frameworkVersion: state.frameworkVersion, changes, preserved, warnings };
+}
+
+function manifestPath(id) {
+  need(/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/.test(id), "Rollback requires the printed uninstall UUID.");
+  return `.nccgs/uninstall/${id}/manifest.json`;
+}
+
+function writeManifest(project, relative, value) {
+  const temporary = `${relative}.${crypto.randomUUID()}.tmp`;
+  fs.writeFileSync(containedPath(project, temporary), JSON.stringify(value, null, 2) + "\n", { flag: "wx" });
+  fs.renameSync(containedPath(project, temporary), containedPath(project, relative));
+}
+
+export function restoreUninstall(project, id, { dryRun = false, ownToken = null } = {}) {
+  project = assertProjectRoot(project); assertUninstallIdle(project, ownToken);
+  const relative = manifestPath(id), manifest = read(containedPath(project, relative));
+  need(manifest.schemaVersion === 1 && manifest.kind === "nccgs-uninstall" && manifest.id === id
+    && ["prepared", "applying", "completed", "restoring", "failed"].includes(manifest.status) && Array.isArray(manifest.files), "Invalid or already restored uninstall receipt.");
+  const known = catalog(), aliases = new Set(), restores = [];
+  for (const item of manifest.files) {
+    assertRelativePath(item.path);
+    need(known.has(item.path) || [statePath, "CLAUDE.md", ".claude/settings.json"].includes(item.path), `Unsafe rollback path: ${item.path}`);
+    need(!aliases.has(item.path.toLowerCase()) && digest(item.before) && (item.after === null || digest(item.after)), "Invalid rollback record.");
+    aliases.add(item.path.toLowerCase());
+    const destination = containedPath(project, item.path), backup = containedPath(project, `.nccgs/uninstall/${id}/files/${item.path}`);
+    const bytes = fs.readFileSync(backup); need(sha256(bytes) === item.before, `Changed rollback backup: ${item.path}`);
+    const current = fs.existsSync(destination) ? sha256(fs.readFileSync(destination)) : null;
+    need(current === item.before || current === item.after, `File changed after uninstall; refusing to overwrite: ${item.path}`);
+    if (current !== item.before) restores.push({ ...item, bytes });
+  }
+  if (dryRun) return { status: "ROLLBACK_PREVIEW", id, restoredFiles: restores.map(x => x.path) };
+  manifest.status = "restoring"; writeManifest(project, relative, manifest);
+  for (const item of restores) {
+    const file = containedPath(project, item.path), current = fs.existsSync(file) ? sha256(fs.readFileSync(file)) : null;
+    need(current === item.after, `Concurrent change during rollback: ${item.path}`);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(containedPath(project, item.path), item.bytes, { flag: item.after === null ? "wx" : "w" });
+  }
+  manifest.status = "restored"; manifest.restoredAt = new Date().toISOString(); writeManifest(project, relative, manifest);
+  return { status: "RESTORED", id, restoredFiles: restores.map(x => x.path) };
+}
+
+export function uninstall(project, { dryRun = false, rollback = null } = {}) {
+  project = assertProjectRoot(project);
+  need(fs.realpathSync(project) !== fs.realpathSync(root), "The NCCGS package cannot uninstall itself.");
+  if (!rollback) assertInstallationAvailable(project);
+  if (dryRun) return rollback ? restoreUninstall(project, rollback, { dryRun: true }) : summary(planUninstall(project));
+  assertUninstallIdle(project);
+  if (!rollback && !fs.existsSync(containedPath(project, statePath))) return summary(planUninstall(project));
+  const lock = acquireLock(containedPath(project, lockPath), { operation: "uninstall" });
+  try {
+    if (rollback) return restoreUninstall(project, rollback, { ownToken: lock.record.token });
+    // Planning is read-only, with our own lock explicitly recognized.
+    const plan = planUninstall(project, lock.record.token);
+    const id = crypto.randomUUID(), relative = manifestPath(id), directory = path.dirname(containedPath(project, relative));
+    for (const item of plan.changes) {
+      const file = containedPath(project, `.nccgs/uninstall/${id}/files/${item.path}`);
+      fs.mkdirSync(path.dirname(file), { recursive: true });
+      fs.writeFileSync(containedPath(project, `.nccgs/uninstall/${id}/files/${item.path}`), item.bytes, { flag: "wx" });
+    }
+    fs.mkdirSync(directory, { recursive: true });
+    const manifest = { schemaVersion: 1, kind: "nccgs-uninstall", id, frameworkVersion: plan.frameworkVersion,
+      createdAt: new Date().toISOString(), status: "prepared", files: plan.changes.map(({ path, before, after }) => ({ path, before, after })),
+      preserved: plan.preserved, warnings: plan.warnings };
+    writeManifest(project, relative, manifest);
+    let mutationStarted = false;
+    try {
+      assertUninstallIdle(project, lock.record.token);
+      for (const item of plan.changes) need(sha256(fs.readFileSync(containedPath(project, item.path))) === item.before, `Concurrent change before uninstall: ${item.path}`);
+      manifest.status = "applying"; writeManifest(project, relative, manifest);
+      for (const item of plan.changes) {
+        const file = containedPath(project, item.path);
+        need(sha256(fs.readFileSync(file)) === item.before, `Concurrent change during uninstall: ${item.path}`);
+        mutationStarted = true;
+        if (item.output === null) fs.unlinkSync(containedPath(project, item.path));
+        else fs.writeFileSync(containedPath(project, item.path), item.output);
+      }
+      manifest.status = "completed"; manifest.completedAt = new Date().toISOString(); writeManifest(project, relative, manifest);
+    } catch (error) {
+      if (!mutationStarted) {
+        manifest.status = "cancelled"; manifest.error = error.message; manifest.cancelledAt = new Date().toISOString();
+        writeManifest(project, relative, manifest);
+        throw new Error(`${error.message}; uninstall cancelled before changing files; receipt ${relative}`);
+      }
+      manifest.status = "failed"; manifest.error = error.message; writeManifest(project, relative, manifest);
+      try { restoreUninstall(project, id, { ownToken: lock.record.token }); }
+      catch (restoreError) { throw new Error(`${error.message}; backup ${relative}; recovery requires inspection: ${restoreError.message}`); }
+      throw new Error(`${error.message}; all planned files restored from ${relative}`);
+    }
+    // Only empty directories derived from individually checked managed paths.
+    const directories = new Set();
+    for (const item of plan.changes.filter(x => x.output === null && x.path.startsWith(".claude/"))) {
+      let dir = path.posix.dirname(item.path);
+      while (dir.startsWith(".claude/")) { directories.add(dir); dir = path.posix.dirname(dir); }
+    }
+    const cleanupWarnings = [];
+    for (const dir of [...directories].sort((a, b) => b.length - a.length)) {
+      try { fs.rmdirSync(containedPath(project, dir)); }
+      catch (error) {
+        if (!["ENOENT", "ENOTEMPTY", "EEXIST"].includes(error.code))
+          cleanupWarnings.push(`Empty-directory cleanup skipped for ${dir}: ${error.code || error.message}`);
+      }
+    }
+    return { ...summary(plan), warnings: [...plan.warnings, ...cleanupWarnings], status: plan.preserved.length ? "UNINSTALLED_WITH_PRESERVED_FILES" : "UNINSTALLED", id, backup: relative };
+  } finally { lock.release(); }
+}
+
+function summary(plan) {
+  return { project: plan.project, status: plan.status, frameworkVersion: plan.frameworkVersion,
+    remove: plan.changes.filter(x => x.after === null).map(x => x.path),
+    edit: plan.changes.filter(x => x.after !== null).map(x => x.path), preserved: plan.preserved, warnings: plan.warnings };
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try {
+    let project = process.cwd(), dryRun = false, rollback = null;
+    const args = process.argv.slice(2), seen = new Set();
+    for (let i = 0; i < args.length; i++) {
+      const arg = args[i]; need(!seen.has(arg), `Duplicate option: ${arg}`); seen.add(arg);
+      if (arg === "--dry-run") dryRun = true;
+      else if (["--project", "--rollback"].includes(arg)) {
+        const value = args[++i]; need(value && !value.startsWith("--"), `${arg} requires a value`);
+        if (arg === "--project") project = path.resolve(value); else rollback = value;
+      } else throw new Error(`Unknown uninstall option: ${arg}`);
+    }
+    console.log(JSON.stringify(uninstall(project, { dryRun, rollback }), null, 2));
+  } catch (error) { console.error(`NCCGS uninstall refused: ${error.message}`); process.exitCode = 1; }
+}