nccgs 2.0.0 → 2.1.0

package/scripts/cli.mjs

@@ -6,6 +6,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import crypto from "node:crypto";
 import { atomicJson, contained, executionPolicy, hash, json, profilePolicy, resolveExecution } from "../.claude/nccgs/tools/policy.mjs";
+import { acquireInstallationLease, assertInstallationAvailable } from "../.claude/nccgs/tools/installation-guard.mjs";
 
 const scriptDir = path.dirname(fileURLToPath(import.meta.url));
 const root = path.resolve(scriptDir, "..");
@@ -29,13 +30,13 @@ if (command === "run") {
   catch (error) { console.error(`Execution migration failed: ${error.message}`); process.exitCode = 1; }
 } else {
 
-if (!new Set(["install", "update", "doctor", "task", "agents", "policy"]).has(command)) {
+if (!new Set(["install", "update", "uninstall", "recover-session", "doctor", "task", "agents", "policy"]).has(command)) {
   console.error(`Unknown command: ${command}`);
   printHelp();
   process.exit(2);
 }
 
-const scripts = { doctor: "doctor.mjs", task: "../.claude/nccgs/tools/task.mjs", agents: "../.claude/nccgs/tools/configure-models.mjs", policy: "../.claude/nccgs/tools/compile-policy.mjs" };
+const scripts = { uninstall: "uninstall.mjs", "recover-session": "recover-session.mjs", doctor: "doctor.mjs", task: "../.claude/nccgs/tools/task.mjs", agents: "../.claude/nccgs/tools/configure-models.mjs", policy: "../.claude/nccgs/tools/compile-policy.mjs" };
 const script = scripts[command] || "install.mjs";
 let forwardedArgs = command === "update" ? ["--update-only", ...args] : args;
 if (command === "agents" && !args.includes("--project")) forwardedArgs = ["--project", process.cwd(), ...args];
@@ -66,6 +67,9 @@ function migrateExecution() {
     if (!allowed.has(args[i])) throw new Error(`Unknown migration option: ${args[i]}`);
     if (args[i] !== "--dry-run") i++;
   }
+  assertInstallationAvailable(target);
+  const lease = dryRun ? null : acquireInstallationLease(target, "nccgs-migrate-execution");
+  try {
   const at = relative => contained(target, relative);
   if (!fs.existsSync(at(".claude/nccgs/install-state.json"))) throw new Error("Install/update NCCGS before migrating execution");
   const studio = json(at(".claude/nccgs/studio.json"));
@@ -158,6 +162,7 @@ function migrateExecution() {
     throw error;
   }
   console.log(`Execution migration ${id} applied. Rollback: nccgs migrate-execution --rollback ${id} --dry-run`);
+  } finally { lease?.release(); }
 }
 
 function printHelp() {
@@ -166,6 +171,10 @@ function printHelp() {
 Usage:
   nccgs install [options]
   nccgs update [options]
+  nccgs uninstall [--project DIR] [--dry-run]
+  nccgs uninstall --rollback UNINSTALL_ID [--project DIR] [--dry-run]
+  nccgs recover-session --id SESSION_UUID [--project DIR] --dry-run
+  nccgs recover-session --id SESSION_UUID --sha256 HASH --confirm-process-tree-stopped --reason TEXT [--project DIR]
   nccgs doctor [options]
   nccgs run [--project DIR] [--claude EXECUTABLE] [--dry-run] -- [Claude arguments/prompt]
   nccgs run --supervise --task ID --prompt-file FILE --session-budget-usd N [--max-resumes 2] [--timeout-ms 3600000] -- [provider options]

package/scripts/install.mjs

@@ -11,6 +11,7 @@ import {
 import { assertProjectRoot, assertRelativePath, containedPath } from "../.claude/nccgs/tools/paths.mjs";
 import { executionPolicy } from "../.claude/nccgs/tools/policy.mjs";
 import { autonomyPolicy, canonicalHookCommand } from "../.claude/nccgs/tools/autonomy.mjs";
+import { acquireInstallationLease, assertInstallationAvailable } from "../.claude/nccgs/tools/installation-guard.mjs";
 
 const scriptDir = path.dirname(fileURLToPath(import.meta.url));
 const root = path.resolve(scriptDir, "..");
@@ -43,6 +44,8 @@ if (project === root) {
   console.error("The NCCGS package directory cannot be its own installation target.");
   process.exit(2);
 }
+try { assertInstallationAvailable(project); }
+catch (error) { console.error(error.message); process.exit(2); }
 
 const unityMarkers = ["Assets", "Packages", "ProjectSettings"];
 const missingMarkers = unityMarkers.filter((item) => !fs.existsSync(projectPath(item)));
@@ -63,6 +66,17 @@ if (validation.status !== 0) {
   process.exit(1);
 }
 
+// Register before reading the installation to keep a concurrent uninstall from
+// invalidating the plan. The second guard closes the acquisition race. Dry-run
+// remains read-only; the exit handler covers all existing early exit paths.
+if (!dryRun) {
+  try {
+    const lease = acquireInstallationLease(project, "nccgs-install");
+    process.once("exit", () => lease.release());
+    assertInstallationAvailable(project);
+  } catch (error) { console.error(error.message); process.exit(2); }
+}
+
 const frameworkSource = path.join(root, ".claude");
 const frameworkFiles = walk(frameworkSource).map((file) => ({
   source: file,

package/scripts/recover-session.mjs

@@ -0,0 +1,89 @@
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import crypto from "node:crypto";
+import { fileURLToPath } from "node:url";
+import { assertProjectRoot, containedPath } from "../.claude/nccgs/tools/paths.mjs";
+import { acquireLock, pidState } from "../.claude/nccgs/tools/process-lock.mjs";
+import { sha256 } from "../.claude/nccgs/tools/integrity.mjs";
+
+const need = (ok, message) => { if (!ok) throw new Error(message); };
+const uuid = value => typeof value === "string" && /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/.test(value);
+
+// Explicit operator reconciliation, never automatic proof that an unmanaged
+// descendant tree stopped. The immutable receipt says which facts are observed
+// and which are attested; ownerState and all task/job/run locks stay unchanged.
+export function recoverSession(project, { id, expectedSha256, confirmStopped = false, reason, dryRun = false } = {}) {
+  project = assertProjectRoot(project);
+  need(!(process.env.CLAUDECODE || process.env.CLAUDE_CODE_ENTRYPOINT || process.env.NCCGS_SUPERVISED_SESSION), "Session recovery requires an external operator terminal.");
+  need(uuid(id), "Use the UUID from .nccgs/sessions/<UUID>.lock.");
+  const relative = `.nccgs/sessions/${id}.lock`, at = name => containedPath(project, name);
+  const inspect = () => {
+    const bytes = fs.readFileSync(at(relative)), record = JSON.parse(bytes.toString("utf8"));
+    need(record.schemaVersion === 1 && record.operation === "nccgs-run" && record.host === os.hostname()
+      && uuid(record.token) && ["owned", "spawning", "running"].includes(record.phase), "Only a valid local nccgs-run session lease can be reconciled.");
+    need(pidState(record.pid) === "dead", "Session launcher is live or unverified; stop/inspect it first.");
+    if (record.child !== null) need(record.child && pidState(record.child.pid) === "dead", "Recorded child is live or unverified; stop/inspect it first.");
+    return { bytes, record, hash: sha256(bytes) };
+  };
+  const preview = inspect();
+  if (dryRun) return { status: "RECOVERY_PREVIEW", project, id, sha256: preview.hash, launcherPid: preview.record.pid,
+    childPid: preview.record.child?.pid ?? null, observedPids: "dead", descendantTree: "unverified",
+    required: "Independently stop/verify the entire session process tree (including any spawn without a recorded PID), then provide --sha256, --confirm-process-tree-stopped and --reason. PID death alone is insufficient." };
+  need(typeof expectedSha256 === "string" && /^[a-f0-9]{64}$/.test(expectedSha256) && preview.hash === expectedSha256, "Lease changed or --sha256 does not match the preview.");
+  need(confirmStopped && typeof reason === "string" && reason.trim().length >= 10 && reason.length <= 2000,
+    "Require --confirm-process-tree-stopped and a specific --reason recording how the entire process tree was confirmed stopped; this cannot be inferred from dead PIDs.");
+  const gate = acquireLock(at(".nccgs/uninstall.lock"), { operation: "session-reconciliation" });
+  try {
+    const current = inspect(); need(current.hash === expectedSha256, "Lease changed after preview.");
+    const recoveryId = crypto.randomUUID(), directory = `.nccgs/session-recoveries/${recoveryId}`;
+    fs.mkdirSync(at(directory), { recursive: true });
+    const receipt = { schemaVersion: 1, kind: "operator-session-reconciliation", status: "pending", outcomeFile: "outcome.json", id: recoveryId, sessionId: id,
+      at: new Date().toISOString(), host: os.hostname(), operator: os.userInfo().username, originalPath: relative,
+      originalSha256: current.hash, originalToken: current.record.token,
+      observed: { launcherPid: current.record.pid, launcherState: "dead", childPid: current.record.child?.pid ?? null, childState: current.record.child ? "dead" : "not-recorded" },
+      attestation: { entireProcessTreeStopped: true, reason: reason.trim(), automaticDescendantProof: false },
+      history: "Intent: archive only this launcher lease. This pending receipt does not prove completion. No process is killed; no task, job, run, verdict or budget is modified." };
+    const receiptText = JSON.stringify(receipt, null, 2) + "\n";
+    fs.writeFileSync(at(`${directory}/receipt.json`), receiptText, { flag: "wx" });
+    const writeOutcome = (status, details) => fs.writeFileSync(at(`${directory}/outcome.json`), JSON.stringify({
+      schemaVersion: 1, kind: "operator-session-reconciliation-outcome", id: recoveryId, sessionId: id,
+      at: new Date().toISOString(), receiptSha256: sha256(receiptText), status, ...details
+    }, null, 2) + "\n", { flag: "wx" });
+    try {
+      need(inspect().hash === expectedSha256, "Lease changed during reconciliation; retained receipt did not release it.");
+      // Both resolved paths are inside the project and checked for links/aliases.
+      // Rename archives the exact original bytes instead of deleting the record.
+      fs.renameSync(at(relative), at(`${directory}/lease.lock`));
+    } catch (error) {
+      let auditError = "";
+      try { writeOutcome("failed", { error: error.message, code: error.code ?? null }); }
+      catch (recordError) { auditError = ` Outcome could not be recorded: ${recordError.message}; completion remains unconfirmed.`; }
+      throw new Error(`Session recovery ${recoveryId} failed: ${error.message}. Inspect ${directory}; keep its pending receipt.${auditError}`);
+    }
+    try { writeOutcome("completed", { archivedLease: `${directory}/lease.lock`, originalSha256: current.hash }); }
+    catch (error) {
+      throw new Error(`Session recovery ${recoveryId}: lease was archived, but completion could not be recorded: ${error.message}. Inspect ${directory}; the pending receipt alone is not completion evidence.`);
+    }
+    return { status: "SESSION_RECONCILED", id, recoveryId, receipt: `${directory}/receipt.json`, outcome: `${directory}/outcome.json`, archivedLease: `${directory}/lease.lock`,
+      scope: "Explicit operator attestation, not automatic descendant proof. Other active/unknown records continue to block uninstall." };
+  } finally { gate.release(); }
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try {
+    const options = {}, args = process.argv.slice(2), seen = new Set(); let project = process.cwd();
+    const values = { "--id": "id", "--sha256": "expectedSha256", "--reason": "reason" };
+    for (let i = 0; i < args.length; i++) {
+      const option = args[i]; need(!seen.has(option), `Duplicate option: ${option}`); seen.add(option);
+      if (option === "--dry-run") options.dryRun = true;
+      else if (option === "--confirm-process-tree-stopped") options.confirmStopped = true;
+      else {
+        need(option === "--project" || Object.hasOwn(values, option), `Unknown recovery option: ${option}`);
+        const value = args[++i]; need(value && !value.startsWith("--"), `${option} requires a value`);
+        if (option === "--project") project = path.resolve(value); else options[values[option]] = value;
+      }
+    }
+    console.log(JSON.stringify(recoverSession(project, options), null, 2));
+  } catch (error) { console.error(`NCCGS session recovery refused: ${error.message}`); process.exitCode = 1; }
+}

package/scripts/run.mjs

@@ -4,6 +4,7 @@ import { spawn } from "node:child_process";
 import { autonomyPolicy } from "../.claude/nccgs/tools/autonomy.mjs";
 import { containedPath } from "../.claude/nccgs/tools/paths.mjs";
 import { supervise } from "./supervise.mjs";
+import { acquireInstallationLease, assertInstallationAvailable } from "../.claude/nccgs/tools/installation-guard.mjs";
 
 // No shell construction, restrictive tool allowlist, or model override.
 export function launchPlan(argv, env = process.env) {
@@ -29,6 +30,7 @@ export function launchPlan(argv, env = process.env) {
     else supervision.budgetUsd = Number(value);
   }
   project = fs.realpathSync(project);
+  assertInstallationAvailable(project);
   if (!fs.existsSync(containedPath(project, ".claude/nccgs/install-state.json"))) throw new Error("Install/update NCCGS in the target project first");
   const mode = autonomyPolicy(project).mode;
   if (env.CLAUDECODE || env.CLAUDE_CODE_ENTRYPOINT) throw new Error("Start nccgs run from the external terminal/operator, not by nesting it inside an active Claude session");
@@ -60,14 +62,24 @@ export async function run(argv) {
     return 0;
   }
   console.error(`NCCGS ${plan.mode} task session | ${plan.project} | ${plan.mode === "full" ? "Native task permissions enabled, including outside-project commands; explicit deny rules and integrity guards remain effective." : "Existing guarded permissions retained."}`);
-  if (plan.supervision) return supervise(plan);
-  const child = spawn(plan.binary, plan.args, { cwd: plan.project, env: plan.env, stdio: "inherit", windowsHide: true });
-  const interrupt = () => child.kill("SIGINT");
-  process.on("SIGINT", interrupt);
+  const lease = acquireInstallationLease(plan.project, "nccgs-run");
+  let child = null;
+  const interrupt = () => child?.kill("SIGINT");
   try {
+    // Recheck after registering the session: uninstall checks this lease before
+    // removing any file. A racing launch cannot proceed through both gates.
+    assertInstallationAvailable(plan.project);
+    // Removal may have finished between launchPlan and lease acquisition.
+    if (!fs.existsSync(containedPath(plan.project, ".claude/nccgs/install-state.json")))
+      throw new Error("Install/update NCCGS in the target project first; it was removed before launch");
+    if (plan.supervision) return await supervise(plan);
+    lease.update({ phase: "spawning" });
+    child = spawn(plan.binary, plan.args, { cwd: plan.project, env: plan.env, stdio: "inherit", windowsHide: true });
+    child.once("spawn", () => lease.update({ phase: "running", child: { pid: child.pid, group: false } }));
+    process.on("SIGINT", interrupt);
     return await new Promise((resolve, reject) => {
       child.once("error", error => reject(new Error(`Cannot start Claude Code: ${error.message}. Use --claude with the native executable path.`)));
       child.once("close", (code, signal) => resolve(code ?? (signal ? 130 : 1)));
     });
-  } finally { process.off("SIGINT", interrupt); }
+  } finally { process.off("SIGINT", interrupt); lease.release(); }
 }

package/scripts/uninstall.mjs

@@ -0,0 +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; }
+}

package/scripts/validate.mjs

@@ -66,6 +66,8 @@ for (const relative of [
   "scaffold/.nccgs/templates/closure-record.md", "package-assets/setup-vivox-voice-chat-evals.gitignore",
   "package-assets/nccgs-project.gitignore",
   "scripts/cli.mjs", "scripts/doctor.mjs", "scripts/install.mjs",
+  "scripts/uninstall.mjs", ".claude/nccgs/tools/installation-guard.mjs", "tests/uninstall.test.mjs", "docs/UNINSTALL.md",
+  "scripts/recover-session.mjs",
   "scripts/sync-unity-skills.mjs", "tests/framework.test.mjs",
   ".claude/nccgs/tools/integrity.mjs", ".claude/nccgs/tools/approve-overrides.mjs"
 ]) requireFile(relative);