nccgs 2.0.0-rc.3 → 2.1.0

package/docs/UNINSTALL.md

@@ -0,0 +1,134 @@
+# Remove NCCGS from a project
+
+`uninstall` is available in the **unpublished 2.1.0 package**. The published
+2.0.0 CLI does not have this command. Use the local 2.1.0 archive (or its source
+CLI) to remove an existing 2.0.0 installation; no preliminary update is needed.
+
+Close Claude Code sessions and let managed workers/verification finish first.
+Run from an external terminal. The command checks recorded process ownership,
+dispatches, runs and jobs; it never kills processes, settles jobs or closes tasks.
+Sessions launched directly with `claude`, or with older launchers, may have no
+session record, so they must also be closed by the operator.
+
+## Preview and remove
+
+```powershell
+$NccgsArchive = "D:\path\to\nccgs-2.1.0.tgz"
+npx --yes --package "$NccgsArchive" nccgs uninstall --project "D:\path\to\UnityProject" --dry-run
+npx --yes --package "$NccgsArchive" nccgs uninstall --project "D:\path\to\UnityProject"
+```
+
+From this source checkout, use `node scripts/cli.mjs uninstall --project DIR`
+with the same options. Always name the intended project. The package refuses
+to uninstall its own source directory.
+
+The preview writes nothing and lists files to remove, shared files to edit and
+modified/unknown inventoried files to preserve. There is no `--force` or history
+purge option. A repeated uninstall reports `NOT_INSTALLED` after successful removal.
+
+| Item | Result |
+|---|---|
+| Unchanged inventoried NCCGS/Unity skills, agents, protocols and tools | Removed after fingerprint checks |
+| Optional generated NCCGS agents | Removed only if their recorded fingerprints still match |
+| Customized or unknown managed files; unrelated files in `.claude` | Kept in place |
+| Exact NCCGS hooks and canonical import in `CLAUDE.md` | Removed; unrelated hooks and owner text kept |
+| Unchanged NCCGS bootstrap `CLAUDE.md` | Removed |
+| Game source, scenes, prefabs, packages and project settings | Unchanged |
+| `.nccgs` policy, task history, reviews, evidence, budgets and prior backups | Kept byte for byte |
+| Generic Claude permission/model preferences | Kept; older installers did not track their ownership |
+
+A retained custom NCCGS skill or agent may still be discoverable by Claude and
+may refer to removed tools. The output identifies those files for manual review;
+they are not silently deleted. Unknown non-inventoried owner files are never
+claimed as NCCGS-owned. Customized compound hooks/imports must be separated by
+the owner before removal, because automatically editing them could lose behavior.
+
+## Backup and recovery
+
+Removal prints an `id` and saves a manifest plus original file bytes beneath
+`.nccgs/uninstall/<id>/`. Keep that directory if you may need recovery.
+
+```powershell
+npx --yes --package "$NccgsArchive" nccgs uninstall --project "D:\path\to\UnityProject" --rollback "PRINTED-UUID" --dry-run
+npx --yes --package "$NccgsArchive" nccgs uninstall --project "D:\path\to\UnityProject" --rollback "PRINTED-UUID"
+npx --yes --package "$NccgsArchive" nccgs doctor --project "D:\path\to\UnityProject"
+```
+
+Use the same package for recovery. All backup hashes and destination files are
+checked before restoration; a later edit or damaged backup causes refusal. The
+receipt and history remain after restoration. A write failure attempts automatic
+restoration; an interrupted operation requires inspection and explicit rollback.
+New launch/install/update operations refuse an incomplete uninstall receipt.
+Do not delete locks or receipts merely to bypass this check.
+
+Agent reconfiguration, execution migration and policy regeneration also participate
+in the uninstall admission lock. New cooperating operations cannot register a
+session while removal/rollback holds this lock. A refusal before any managed file
+is changed leaves a `cancelled` receipt with its diagnostic and backups; it does
+not require rollback. After changes begin, normal ownership checks still apply to
+restoration. Unrecorded/older concurrent operations require operator inspection.
+Failure to remove an empty directory is a warning after successful removal; the
+result still returns the backup path and rollback ID.
+
+Two launches/configuration commands can briefly contend for the admission lock.
+This reports `installation admission is busy or unverified`, rather than claiming
+an uninstall is running. Retry once the other operation finishes; the command
+does not retry automatically or take over a live/unverified lock.
+Empty, incomplete, unreadable or disappearing lock records also produce the
+busy/unverified diagnostic, retaining the original cause for inspection. They
+never authorize admission or automatic recovery. A holder that releases before
+the error recheck still results in refusal; retry explicitly once work settles.
+
+## Recover a crashed launcher lease
+
+Closing a terminal forcibly or a crash can leave a `nccgs run` lease in
+`.nccgs/sessions/<UUID>.lock`. An unmanaged child's descendants cannot be proven
+stopped merely because its launcher and child PIDs are dead. Uninstall therefore
+continues to refuse this unknown state automatically.
+
+The external operator can explicitly reconcile **only that launcher lease**:
+
+```powershell
+npx --yes --package "$NccgsArchive" nccgs recover-session --project "D:\path\to\UnityProject" --id "SESSION-UUID" --dry-run
+```
+
+Independently inspect and stop the entire session process tree first, including
+any child that spawned before its PID was recorded. Rebooting the host and checking
+that the session has not restarted is one way to establish that boundary. Only
+when this is true, use the preview's SHA-256 and record how it was confirmed:
+
+```powershell
+npx --yes --package "$NccgsArchive" nccgs recover-session --project "D:\path\to\UnityProject" --id "SESSION-UUID" --sha256 "HASH-FROM-PREVIEW" --confirm-process-tree-stopped --reason "Describe how the full session tree was confirmed stopped"
+```
+
+This is a human/operator attestation, **not automatic descendant proof**. The
+command refuses live/unverified recorded PIDs, a foreign host, changed hashes,
+wrong operation, unsafe IDs and invocation inside Claude Code. It archives the
+exact original lease and a receipt with the operator's reason under
+`.nccgs/session-recoveries/<id>/`. It never kills a process or edits task/job/run
+locks, verdicts, history or budgets. Other active/unknown work still blocks
+uninstall. A missing child PID during `spawning` explicitly remains unobserved
+in the receipt; the operator must establish shutdown independently before confirming.
+Keep the receipts and retry the original uninstall/rollback only after all work
+has settled. There is no age-based or automatic eviction of unknown leases.
+
+Each recovery writes an immutable `receipt.json` with status `pending` before
+moving the lease, then a separate `outcome.json` with status `completed` or
+`failed`. The outcome identifies the pending receipt by SHA-256. A rename failure
+leaves the original lease in place and records the error; it is not a successful
+recovery. If a crash or write failure leaves no valid outcome, completion remains
+unconfirmed: inspect both the original lease and the archive, retaining every
+record. The lease may already have moved if recording completion failed. A pending
+receipt alone never proves success, and the command does not report success when
+it cannot record completion. Retrying a failed move creates a new receipt; it
+does not overwrite the earlier attempt.
+
+Reinstalling later reuses retained policy and task records. It does not replenish
+spent money, turns, reviews or time. Restoring an old uninstall must not overwrite
+a subsequent installation. Removal/rollback is a maintenance action, not a task
+PASS, independent review, acceptance decision or a new allowance.
+
+The command removes the project integration only. It does not uninstall Claude
+Code, Unity, Node.js, global npm packages or npm's cache, and makes no provider
+calls. Symlinks/junctions, malformed records and uncertain process ownership fail
+closed rather than permitting deletion outside the checked project.

package/docs/UPGRADE-QUALIFICATION.md

@@ -1,6 +1,6 @@
 # Published 1.3.0 upgrade qualification
 
-Target: **2.0.0-rc.3**. This is installation/configuration qualification on Windows
+Historical target: **2.0.0-rc.3**. This is installation/configuration qualification on Windows
 with Node.js 24.12.0 using the published npm 1.3.0 archive and the exact RC3 archive.
 It does not establish Node 18, macOS/Linux, provider execution or gameplay results.
 

package/docs/WORKFLOWS.md

@@ -1,4 +1,4 @@
-# NCCGS workflows — 2.0 RC
+# NCCGS workflows — 2.0.0
 
 New installations use standalone Claude Code execution with the claude-standalone
 model profile. The coordinator owns intake, planning, dispatch, verification and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nccgs",
-  "version": "2.0.0-rc.3",
+  "version": "2.1.0",
   "description": "Unity-first game-studio operating system for Claude Code",
   "license": "MIT",
   "type": "module",
@@ -28,7 +28,7 @@
   },
   "publishConfig": {
     "access": "public",
-    "tag": "next",
+    "tag": "latest",
     "registry": "https://registry.npmjs.org/"
   },
   "scripts": {

package/scaffold/.nccgs/templates/repair-unity-code.json

@@ -0,0 +1,18 @@
+{
+  "schemaVersion": 2,
+  "repairType": "unity-code",
+  "taskId": "REPLACE_WITH_TASK_ID",
+  "contractHash": "REPLACE_WITH_CURRENT_CONTRACT_HASH",
+  "sourceSnapshot": "REPLACE_WITH_CURRENT_SOURCE_SNAPSHOT",
+  "problem": "Describe the recorded failure and its evidence.",
+  "solution": "State the chosen correction, relevant callers and regression coverage.",
+  "changes": [
+    { "path": "Assets/REPLACE_WITH_SOURCE.cs", "operation": "edit", "instruction": "Apply the exact chosen correction; preserve the full acceptance contract." }
+  ],
+  "context": [],
+  "verification": ["REPLACE_WITH_REQUIRED_CHECK_NAME"],
+  "unity": {
+    "steps": []
+  },
+  "budget": { "workCalls": 24, "readCalls": 12, "handoffCalls": 3, "durationMs": 900000 }
+}

package/scaffold/.nccgs/templates/repair-unity-editor.json

@@ -0,0 +1,21 @@
+{
+  "schemaVersion": 2,
+  "repairType": "unity-editor",
+  "taskId": "REPLACE_WITH_TASK_ID",
+  "contractHash": "REPLACE_WITH_CURRENT_CONTRACT_HASH",
+  "sourceSnapshot": "REPLACE_WITH_CURRENT_SOURCE_SNAPSHOT",
+  "problem": "Describe the recorded scene, prefab or asset failure.",
+  "solution": "State the chosen Editor operation and how it saves only the exact affected files.",
+  "changes": [
+    { "path": "Assets/REPLACE_WITH_PREFAB.prefab", "operation": "edit", "instruction": "Apply and save the chosen correction through Unity Editor APIs." }
+  ],
+  "context": [],
+  "verification": ["REPLACE_WITH_REQUIRED_CHECK_NAME"],
+  "unity": {
+    "capabilities": { "path": ".nccgs/evidence/REPLACE_WITH_UNITY_DISCOVERY.json", "sha256": "REPLACE_WITH_CAPTURED_HASH" },
+    "steps": [
+      { "id": "apply-and-save", "command": "eval", "arguments": ["REPLACE_WITH_CHOSEN_CSHARP_BODY_USING_FULLY_QUALIFIED_TYPES"], "timeoutMs": 30000 }
+    ]
+  },
+  "budget": { "workCalls": 20, "readCalls": 8, "handoffCalls": 3, "durationMs": 900000 }
+}

package/scaffold/.nccgs/templates/task-slices.json

@@ -0,0 +1,28 @@
+{
+  "schemaVersion": 1,
+  "taskId": "REPLACE_WITH_EXISTING_TASK_ID",
+  "contractHash": "REPLACE_WITH_CURRENT_CONTRACT_HASH",
+  "sourceSnapshot": "REPLACE_WITH_CURRENT_SOURCE_SNAPSHOT",
+  "planId": "delivery-one",
+  "supersedes": null,
+  "reason": "Split the existing contract into bounded assignments within its remaining budget.",
+  "integration": "integrate",
+  "slices": [
+    {
+      "id": "foundation",
+      "objective": "Implement the first coherent behavior and its targeted test.",
+      "agent": "nccgs-gameplay-programmer",
+      "dependsOn": [],
+      "writePaths": ["Assets/REPLACE_WITH_FIRST_SOURCE.cs", "Assets/Tests/REPLACE_WITH_FIRST_TEST.cs"],
+      "criteria": ["REPLACE_WITH_ORIGINAL_CRITERION_ID"]
+    },
+    {
+      "id": "integrate",
+      "objective": "Implement the remaining behavior and integrate the full original contract.",
+      "agent": "nccgs-gameplay-programmer",
+      "dependsOn": ["foundation"],
+      "writePaths": ["Assets/REPLACE_WITH_SECOND_SOURCE.cs", "Assets/Tests/REPLACE_WITH_INTEGRATION_TEST.cs"],
+      "criteria": ["REPLACE_WITH_REMAINING_ORIGINAL_CRITERION_ID"]
+    }
+  ]
+}

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,11 +171,19 @@ 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]
   nccgs run --recover-run RUN_ID [--project DIR] [--claude EXECUTABLE]
   nccgs task init|snapshot|ref|observe|verify|acceptance-status|record|check|close|bind|extend-review|refresh-inputs|migrate-evidence [options]
+  nccgs task dispatch-prompt|handoff-validate|record-review --id TASK --dispatch ID [--file HANDOFF]
+  nccgs task repair-editor --id TASK --dispatch ID --step STEP  (admitted Unity repair worker only)
+  nccgs task slice-preview|slice-plan --id TASK --file PLAN  (same task and budget)
+  nccgs task slice-status --id TASK
   nccgs agents --enable <role> | --disable <role> [--project <directory>]
   nccgs policy [--write]              Check/regenerate package routing
   nccgs migrate-execution --to standalone [--external-review off|advisory|required] [--model-profile <profile>] [--dry-run]

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) {
@@ -16,18 +17,20 @@ export function launchPlan(argv, env = process.env) {
     const option = options[i];
     if (option === "--dry-run") { dryRun = true; continue; }
     if (option === "--supervise") { supervised = true; continue; }
-    if (!["--project", "--claude", "--task", "--prompt-file", "--max-resumes", "--timeout-ms", "--session-budget-usd", "--recover-run"].includes(option) || !options[i + 1] || options[i + 1].startsWith("--")) throw new Error(`Invalid run option: ${option}; put Claude arguments after --`);
+    if (!["--project", "--claude", "--task", "--prompt-file", "--max-resumes", "--timeout-ms", "--session-budget-usd", "--recover-run", "--budget-phase"].includes(option) || !options[i + 1] || options[i + 1].startsWith("--")) throw new Error(`Invalid run option: ${option}; put Claude arguments after --`);
     const value = options[++i];
     if (option === "--project") project = path.resolve(value);
     else if (option === "--claude") binary = value;
     else if (option === "--task") supervision.taskId = value;
     else if (option === "--prompt-file") supervision.promptFile = path.resolve(value);
     else if (option === "--recover-run") { supervision.recoverRun = value; supervised = true; }
+    else if (option === "--budget-phase") { if (!["work", "final-review"].includes(value)) throw new Error("Budget phase must be work or final-review"); supervision.budgetPhase = value; }
     else if (option === "--max-resumes") supervision.maxResumes = Number(value);
     else if (option === "--timeout-ms") supervision.timeoutMs = Number(value);
     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");
@@ -35,14 +38,14 @@ export function launchPlan(argv, env = process.env) {
   for (const argument of forwarded) if (conflicting.test(argument)) throw new Error(`NCCGS owns session permission/root settings; conflicting option: ${argument}`);
   if (supervised) {
     if (supervision.recoverRun) {
-      if (forwarded.length || supervision.taskId || supervision.promptFile || supervision.budgetUsd !== undefined || options.includes("--max-resumes") || options.includes("--timeout-ms")) throw new Error("Recovery preserves the original prompt, limits and provider arguments");
+      if (forwarded.length || supervision.taskId || supervision.promptFile || supervision.budgetUsd !== undefined || supervision.budgetPhase || options.includes("--max-resumes") || options.includes("--timeout-ms")) throw new Error("Recovery preserves the original prompt, limits and provider arguments");
     } else {
       if (!supervision.taskId || !supervision.promptFile || !Number.isFinite(supervision.budgetUsd) || supervision.budgetUsd <= 0) throw new Error("Supervision needs --task, --prompt-file and --session-budget-usd");
       if (!Number.isSafeInteger(supervision.maxResumes) || supervision.maxResumes < 0 || supervision.maxResumes > 5 || !Number.isSafeInteger(supervision.timeoutMs) || supervision.timeoutMs < 1000 || supervision.timeoutMs > 86400000) throw new Error("Invalid supervision continuation/time limits");
       const owned = /^(?:-p|--print|--output-format|--input-format|--session-id|--resume|-r|--continue|-c|--fork-session|--no-session-persistence|--max-budget-usd|--verbose|--bg|--background|--remote|--cloud)(?:=|$)/;
       for (const argument of forwarded) if (owned.test(argument)) throw new Error(`Supervisor owns native lifecycle option: ${argument}`);
     }
-  } else if (options.some(option => ["--task", "--prompt-file", "--max-resumes", "--timeout-ms", "--session-budget-usd"].includes(option))) throw new Error("Lifecycle options require --supervise");
+  } else if (options.some(option => ["--task", "--prompt-file", "--max-resumes", "--timeout-ms", "--session-budget-usd", "--budget-phase"].includes(option))) throw new Error("Lifecycle options require --supervise");
   return { project, binary, dryRun, mode, args: ["--permission-mode", mode === "full" ? "bypassPermissions" : "default", ...forwarded],
     supervision: supervised ? supervision : null, env: { ...env, NCCGS_PROJECT_ROOT: project, NCCGS_TASK_AUTONOMY: mode,
       // Native auto-backgrounding can otherwise turn a claimed foreground worker
@@ -59,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/supervise.mjs

@@ -7,6 +7,9 @@ import { taskPath } from "../.claude/nccgs/tools/gates.mjs";
 import { checkpoint, status as dispatchStatus } from "../.claude/nccgs/tools/orchestration.mjs";
 import { listJobs } from "../.claude/nccgs/tools/verification-jobs.mjs";
 import { acquireLock, delay, pidState } from "../.claude/nccgs/tools/process-lock.mjs";
+import { sessionBudgetLock, sessionBudgetCoverage } from "../.claude/nccgs/tools/session-budget.mjs";
+import { allocateReviewBudget } from "../.claude/nccgs/tools/review-budget.mjs";
+import { settleWorkHandoff } from "./work-handoff.mjs";
 
 const need = (condition, message) => { if (!condition) throw new Error(message); };
 const now = () => new Date().toISOString();
@@ -44,11 +47,13 @@ export async function supervise(plan) {
       budgetUsd: config.budgetUsd, cumulativeCostUsd: 0, costCoverage: "complete", invocations: [], status: "ready" };
   }
   const lock = acquireLock(contained(project, `.nccgs/runs/task-${state.taskId}.lock`), { runId: state.id });
+  let budgetLock;
   const directory = path.dirname(file), save = () => atomicJson(file, state);
   let interrupted = false, child;
   const interrupt = () => { interrupted = true; if (child) child.kill("SIGINT"); };
   process.on("SIGINT", interrupt);
   try {
+    budgetLock = acquireLock(contained(project, sessionBudgetLock), { runId: state.id, sessionId: state.sessionId });
     fs.mkdirSync(directory, { recursive: true });
     const task = json(taskPath(project, state.taskId));
     need(task.contractHash === state.contractHash, "Task contract changed during supervised run");
@@ -63,7 +68,9 @@ export async function supervise(plan) {
       state.cumulativeCostUsd = cumulativeCost(state.cumulativeCostUsd, terminal, state.sessionId);
       state.costCoverage = "complete";
       Object.assign(last, { status: "recovered", terminal, recoveredAt: now() }); save();
+      last.evidence = artifact(project, `.nccgs/runs/${state.id}/${last.log}`); save();
     }
+    allocateReviewBudget(project, state, state.budgetPhase ?? config.budgetPhase ?? "work"); save();
     for (;;) {
       need(!interrupted, "Supervised run interrupted; jobs and checkpoint retained");
       need(Date.now() < state.deadline, "Supervised run deadline reached; no automatic extension");
@@ -75,11 +82,16 @@ export async function supervise(plan) {
         await delay(250); continue; // deterministic wait, no model request or fake verification receipt
       }
       if (state.invocations.length) {
-        const latestTask = json(taskPath(project, state.taskId));
+        let latestTask = json(taskPath(project, state.taskId));
         const latestReceiptAt = Math.max(0, ...jobs.map(j => Date.parse(json(contained(project, j.evidence.path)).finishedAt)));
-        const reportAt = Date.parse(latestTask.stages.report?.recordedAt ?? "");
         const active = dispatchStatus(project, state.taskId).active;
         need(!active.length, "Native worker dispatch remains active/uncertain; preserve quota and request reconciliation");
+        const handoff = settleWorkHandoff(project, state, latestReceiptAt);
+        if (handoff) {
+          latestTask = json(taskPath(project, state.taskId));
+          state.workHandoff = { origin: "supervisor-work-handoff", evidence: latestTask.stages.report.evidence, recordedAt: latestTask.stages.report.recordedAt };
+        }
+        const reportAt = Date.parse(latestTask.stages.report?.recordedAt ?? "");
         if (Number.isFinite(reportAt) && reportAt >= latestReceiptAt && reportAt >= Date.parse(state.createdAt)) {
           state.status = "settled"; state.taskOutcome = latestTask.outcome; state.taskPhase = latestTask.phase;
           state.finishedAt = now(); save(); return 0;
@@ -88,28 +100,40 @@ export async function supervise(plan) {
       }
       const remaining = state.budgetUsd - state.cumulativeCostUsd;
       need(remaining > 0, "Session list-cost budget exhausted; no budget reset on resume");
+      allocateReviewBudget(project, state, state.budgetPhase ?? "work");
+      for (let id = state.taskId; id; id = json(taskPath(project, id)).parentId) {
+        const ledger = dispatchStatus(project, id);
+        if (ledger.limits?.maxCostUsd != null)
+          sessionBudgetCoverage(project, id, ledger.reservations, ledger.limits.maxCostUsd, state, { running: false });
+      }
       const index = state.invocations.length, invocation = { index, startedAt: now(), status: "running", pid: null,
         log: `native-${index}.jsonl`, stderr: `native-${index}.stderr.log`, allowanceUsd: remaining };
-      const prompt = index === 0 ? state.prompt : `Continue NCCGS task ${state.taskId} in this same session. Read task inspect and task job-status. Use the existing verification receipts; do not rerun successful commands just to create receipts. Investigate failed checks within remaining scope/budget. Record a truthful report (success/partial/blocked/failed). Do not claim DONE without all configured gates. Jobs: ${JSON.stringify(jobs)}. This continuation preserves all previous attempts, review rounds and costs.`;
+      const workNotice = task.mode === "implement"
+        ? `Final delivery review money/time is protected in a separate final-review phase. Finish the implementation record, then invoke node .claude/nccgs/tools/task.mjs report --id ${state.taskId} --outcome partial --summary "Implementation recorded; awaiting protected independent review". A prose PARTIAL response alone does not record the handoff. Do not spend this work phase on delivery review.`
+        : "Complete this task's normal analysis, independent design review, report and closure gates. Final delivery review money/time is protected for the later implementation task.";
+      const phaseNotice = state.budgetAllocation ? `Budget phase: ${state.budgetPhase}. Effective cumulative session ceiling USD ${state.budgetUsd}; absolute deadline ${new Date(state.deadline).toISOString()}. Read task budget-status for the pinned allocation. ${state.budgetPhase === "work" ? workNotice : "This phase only admits independent delivery review and settlement. No source workers, repair or new verification jobs. Read existing current measured evidence; preserve all ordinary gates and the exact reviewer verdict."}\n\n` : "";
+      const prompt = phaseNotice + (index === 0 ? state.prompt : `Continue NCCGS task ${state.taskId} in this same session. Read task inspect and task job-status. Use the existing verification receipts; do not rerun successful commands just to create receipts. Investigate failed checks within remaining scope/budget. Record a truthful report (success/partial/blocked/failed). Do not claim DONE without all configured gates. Jobs: ${JSON.stringify(jobs)}. This continuation preserves all previous attempts, review rounds and costs.`);
       state.invocations.push(invocation); state.status = "running"; state.costCoverage = "unknown-current-invocation"; save();
       lock.update({ phase: "spawning" });
+      budgetLock.update({ phase: "spawning" });
       const output = fs.openSync(path.join(directory, invocation.log), "wx"), errors = fs.openSync(path.join(directory, invocation.stderr), "wx");
       const args = [...state.providerArgs, "-p", "--output-format", "stream-json", "--verbose", "--max-budget-usd", String(remaining),
         ...(index === 0 ? ["--session-id", state.sessionId] : ["--resume", state.sessionId])];
       let deadlineTimer;
       try {
         child = spawn(state.binary, args, { cwd: project, windowsHide: true, stdio: ["pipe", "pipe", "pipe"],
-          env: { ...plan.env, NCCGS_SUPERVISED_SESSION: state.sessionId, NCCGS_TASK_ID: state.taskId } });
+          env: { ...plan.env, NCCGS_SUPERVISED_SESSION: state.sessionId, NCCGS_SUPERVISED_RUN: state.id, NCCGS_TASK_ID: state.taskId } });
         child.stdin.on("error", () => {}); // early native failure is captured in its terminal/exit evidence
         child.stdout.on("data", data => { fs.writeSync(output, data); process.stdout.write(data); });
         child.stderr.on("data", data => { fs.writeSync(errors, data); process.stderr.write(data); });
-        child.once("spawn", () => { invocation.pid = child.pid; save(); lock.update({ phase: "running", child: { pid: child.pid, group: false } }); });
+        child.once("spawn", () => { invocation.pid = child.pid; save(); const ownership = { phase: "running", child: { pid: child.pid, group: false } }; lock.update(ownership); budgetLock.update(ownership); });
         child.stdin.end(prompt);
         deadlineTimer = setTimeout(() => { interrupted = true; child.kill("SIGINT"); }, Math.max(1, state.deadline - Date.now()));
         const result = await new Promise((resolve, reject) => { child.once("error", reject); child.once("close", (code, signal) => resolve({ code, signal })); });
         Object.assign(invocation, result, { finishedAt: now() });
       } finally { clearTimeout(deadlineTimer); fs.closeSync(output); fs.closeSync(errors); child = null; }
       lock.update({ phase: "owned", child: null });
+      budgetLock.update({ phase: "owned", child: null });
       invocation.terminal = terminalFrom(path.join(directory, invocation.log));
       state.cumulativeCostUsd = cumulativeCost(state.cumulativeCostUsd, invocation.terminal, state.sessionId);
       state.costCoverage = "complete";
@@ -120,5 +144,5 @@ export async function supervise(plan) {
     state.status = "blocked"; state.reason = error.message; state.stoppedAt = now();
     try { state.checkpoint = checkpoint(project, state.taskId, { reason: error.message }); } catch { /* original failure retained */ }
     save(); console.error(`NCCGS supervisor: ${error.message}. Run record: ${file}`); return 1;
-  } finally { process.off("SIGINT", interrupt); lock.release(); }
+  } finally { process.off("SIGINT", interrupt); budgetLock?.release(); lock.release(); }
 }