nccgs 2.0.0-rc.2 → 2.0.0

package/scripts/install.mjs

@@ -88,6 +88,7 @@ const overrideManifestPath = projectPath(".nccgs/framework-overrides.json");
 // even when a pre-existing file would otherwise be preserved or skipped.
 for (const relative of ["CLAUDE.md", ".claude/settings.json", ".nccgs/project.yaml", ".nccgs/execution.json", ".nccgs/backups", ".nccgs/agent-activation.json"]) projectPath(relative);
 const previousInstallState = readJsonIfPresent(installStatePath, "NCCGS install state");
+const previousActivation = readJsonIfPresent(projectPath(".nccgs/agent-activation.json"), "NCCGS agent activation state");
 const executionFile = projectPath(".nccgs/execution.json");
 const previousExecution = readJsonIfPresent(executionFile, "NCCGS execution policy");
 const existingProjectPolicy = fs.existsSync(projectPath(".nccgs/project.yaml"));
@@ -308,6 +309,15 @@ function planFrameworkFile(item) {
   }
   if (equivalentFiles(item.source, item.destination)) return { ...item, action: "current", override: null };
   if (!force && previous && matchesFingerprint(item.destination, previous)) return { ...item, action: "replace", override: null };
+  // Older profiles could generate optional agents outside install-state.files.
+  // When a later package starts managing one, its recorded generated bytes are
+  // a valid baseline. Real local edits and explicit overrides still need review.
+  const generated = previousActivation?.schemaVersion === 1 && item.relative.startsWith(".claude/agents/")
+    ? { sha256: previousActivation.generated?.[item.relative], canonicalSha256: previousActivation.generatedCanonical?.[item.relative] }
+    : null;
+  if (!force && previousInstallState && !previous && !existingOverride && matchesFingerprint(item.destination, generated)) {
+    return { ...item, action: "replace", override: null };
+  }
   if (force) return { ...item, action: "force-replace", override: null };
   return { ...item, action: "preserve", override: buildOverride(item, existingOverride, upstream, "preserve") };
 }

package/scripts/run.mjs

@@ -16,13 +16,14 @@ 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);
@@ -35,14 +36,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

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(); }
 }

package/scripts/validate.mjs

@@ -50,7 +50,11 @@ for (const relative of [
   ".claude/nccgs/pipeline.json", ".claude/nccgs/protocols/task-gates.md",
   ".claude/nccgs/protocols/design-lifecycle.md", ".claude/nccgs/tools/design-readiness.mjs", "scaffold/.nccgs/templates/design-contract.json",
   ".claude/nccgs/tools/task.mjs", ".claude/nccgs/tools/gates.mjs", ".claude/nccgs/tools/runtime.mjs",
+  ".claude/nccgs/tools/handoff.mjs", "docs/HANDOFF-AUTOMATION.md",
+  ".claude/nccgs/tools/task-slices.mjs", ".claude/nccgs/protocols/task-slices.md",
+  "scaffold/.nccgs/templates/task-slices.json", "docs/TASK-SLICING.md", "tests/task-slices.test.mjs",
   ".claude/nccgs/tools/repair-packet.mjs", ".claude/nccgs/protocols/bounded-repair.md", "scaffold/.nccgs/templates/repair-packet.json", "docs/BOUNDED-REPAIR.md",
+  ".claude/nccgs/tools/unity-repair.mjs", "scaffold/.nccgs/templates/repair-unity-code.json", "scaffold/.nccgs/templates/repair-unity-editor.json",
   "scaffold/.nccgs/gates.json", "scaffold/.nccgs/execution.json", "tests/gates.test.mjs",
   ".claude/nccgs/settings.fragment.json", ".claude/nccgs/unity-skills-manifest.json",
   ".claude/nccgs/protocols/agent-contract.md", ".claude/nccgs/protocols/orchestration.md",

package/scripts/work-handoff.mjs

@@ -0,0 +1,38 @@
+import { check, record, taskPath } from "../.claude/nccgs/tools/gates.mjs";
+import { json } from "../.claude/nccgs/tools/policy.mjs";
+import { assessCriteria } from "../.claude/nccgs/tools/criteria.mjs";
+import { status } from "../.claude/nccgs/tools/orchestration.mjs";
+import { listJobs, readJob } from "../.claude/nccgs/tools/verification-jobs.mjs";
+
+// Settle only an already recorded implementation. This is deterministic supervisor
+// bookkeeping, never a provider/reviewer verdict or permission to close the task.
+export function settleWorkHandoff(project, state, latestReceiptAt = 0) {
+  if (!state.budgetAllocation || state.budgetPhase !== "work" || state.costCoverage !== "complete") return null;
+  const last = state.invocations.at(-1);
+  if (!last || !["finished", "recovered"].includes(last.status) || last.terminal?.is_error ||
+      (last.code != null && last.code !== 0) || last.signal) return null;
+  const task = json(taskPath(project, state.taskId));
+  if (task.mode !== "implement" || task.closed || task.contractHash !== state.contractHash) return null;
+  if (Date.parse(task.stages.report?.recordedAt) >= Date.parse(state.createdAt)) return null;
+  if (!(Date.parse(task.stages.implementation?.recordedAt) >= Math.max(Date.parse(state.createdAt), latestReceiptAt))) return null;
+  const jobs = listJobs(project, task.id);
+  if (jobs.some(j => !["PASS", "FAIL"].includes(j.status)) || status(project, task.id).active.length) return null;
+  // A later failure cannot be hidden by re-recording an older PASS, even for a
+  // legacy check-only contract without measured acceptance assertions.
+  const byName = new Map();
+  for (const job of jobs) {
+    const queuedAt = Date.parse(readJob(project, job.jobId).queuedAt), previous = byName.get(job.name);
+    if (!Number.isFinite(queuedAt) || previous?.queuedAt === queuedAt) return null;
+    if (!previous || previous.queuedAt < queuedAt) byName.set(job.name, { ...job, queuedAt });
+  }
+  if ([...byName.values()].some(j => j.status !== "PASS")) return null;
+  let ready;
+  try {
+    ready = check(project, task, "review");
+    if (!ready.allowed || !assessCriteria(project, task, ready.snapshot).automaticPassed) return null;
+  } catch { return null; } // Incomplete/stale evidence still follows the bounded continuation path.
+  return record(project, task.id, "report", {
+    outcome: "partial", origin: "supervisor-work-handoff", runId: state.id,
+    summary: "Implementation and current measured checks recorded. Awaiting protected independent delivery review and all remaining acceptance gates. This handoff is deterministic supervisor bookkeeping, not a reviewer verdict."
+  });
+}

package/tests/editor-session-evidence.test.mjs

@@ -0,0 +1,45 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import crypto from "node:crypto";
+import { publishEditorSessionEvidence } from "../.claude/nccgs/tools/editor-session-evidence.mjs";
+const hash = bytes => crypto.createHash("sha256").update(bytes).digest("hex");
+function fixture(t) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "nccgs-editor-evidence-"));
+  t.after(() => fs.rmSync(root, { recursive: true, force: true }));
+  const project = path.join(root, "project"); fs.mkdirSync(project);
+  const identity = { pid: 123, windowsJob: true, groupName: "Local\\NCCGS-12345678-1234-1234-1234-123456789abc" };
+  const values = {
+    start: { at: "2026-01-01T00:00:00Z", project, identity },
+    stop: { identity, state: "dead", forced: false, result: { code: 0, signal: null } },
+    shutdown: { at: "2026-01-01T00:01:00Z", args: ["command", "eval", "UnityEditor.EditorApplication.Exit(0);", "--project-path", project], code: 0, signal: null, identity: { ...identity, pid: 124 }, treeState: "dead" }
+  };
+  const request = { sourceProject: project, id: crypto.randomUUID() };
+  const save = () => { for (const [key, value] of Object.entries(values)) { const f = path.join(root, key + ".json"); fs.writeFileSync(f, JSON.stringify(value)); request[key + "File"] = f; } };
+  save(); return { project, request, values, save, root };
+}
+test("publishes original bytes and hashes under reviewer-readable evidence without task mutation", t => {
+  const f = fixture(t); fs.mkdirSync(path.join(f.project, ".nccgs")); fs.writeFileSync(path.join(f.project, ".nccgs", "task-sentinel"), "original history and budgets");
+  const ref = publishEditorSessionEvidence(f.project, f.request), bytes = fs.readFileSync(path.join(f.project, ref.path)), receipt = JSON.parse(bytes);
+  assert.equal(hash(bytes), ref.sha256); assert.equal(receipt.origin, "external-operator-editor-evidence"); assert.equal(receipt.historicalImport, false);
+  for (const [key, value] of Object.entries(receipt.references)) { const copied = fs.readFileSync(path.join(f.project, value.path)); assert.equal(hash(copied), value.sha256); assert.deepEqual(copied, fs.readFileSync(f.request[key + "File"])); }
+  assert.equal(fs.readFileSync(path.join(f.project, ".nccgs", "task-sentinel"), "utf8"), "original history and budgets");
+  assert.throws(() => publishEditorSessionEvidence(f.project, f.request), /EEXIST/);
+});
+test("separate addendum identifies historical import and preserves the source project", t => {
+  const f = fixture(t), addendum = path.join(f.root, "addendum"); fs.mkdirSync(addendum);
+  const ref = publishEditorSessionEvidence(addendum, f.request), receipt = JSON.parse(fs.readFileSync(path.join(addendum, ref.path)));
+  assert.equal(receipt.historicalImport, true); assert.equal(receipt.sourceProject, f.project); assert.equal(fs.readdirSync(f.project).length, 0);
+});
+for (const [label, mutate] of Object.entries({
+  "mismatched ownership": f => { f.values.stop.identity = { ...f.values.stop.identity, pid: 999 }; },
+  "wrong project": f => { f.values.shutdown.args[4] = path.join(f.root, "other"); },
+  "live process": f => { f.values.stop.state = "alive"; },
+  "unknown process": f => { f.values.shutdown.treeState = "unknown"; },
+  "forced exit": f => { f.values.stop.forced = true; },
+  "failed exit": f => { f.values.stop.result.code = 1; },
+  "missing shutdown method": f => { f.values.shutdown.args[2] = "return 0;"; },
+  "reversed events": f => { f.values.shutdown.at = "2025-01-01T00:00:00Z"; }
+})) test(`rejects ${label} before publishing`, t => { const f = fixture(t); mutate(f); f.save(); assert.throws(() => publishEditorSessionEvidence(f.project, f.request)); assert.equal(fs.readdirSync(f.project).length, 0); });

package/tests/fixtures/compiler-shutdown.cs

@@ -0,0 +1,64 @@
+using System;
+using System.Diagnostics;
+using System.IO;
+using System.IO.Pipes;
+using System.Runtime.InteropServices;
+using System.Threading;
+using System.Threading.Tasks;
+
+// Synthetic IPC guard fixture, not Unity execution evidence.
+public static class CompilerShutdownFixture {
+  [DllImport("kernel32.dll")] static extern IntPtr CreateJobObject(IntPtr attributes,string name);
+  [DllImport("kernel32.dll")] static extern bool AssignProcessToJobObject(IntPtr job,IntPtr process);
+  [DllImport("kernel32.dll")] static extern bool CloseHandle(IntPtr handle);
+  static void Need(bool ok,string message) { if(!ok) throw new Exception(message); }
+  static void Exchange(IntPtr job,IntPtr process,int pid,bool expected,bool answer) {
+    string name="nccgs-compiler-guard-"+Guid.NewGuid().ToString("N");
+    using(var server=new NamedPipeServerStream(name,PipeDirection.InOut,1,PipeTransmissionMode.Byte,PipeOptions.Asynchronous)) {
+      var connected=server.WaitForConnectionAsync();
+      var receive=Task.Run(()=>{
+        connected.GetAwaiter().GetResult();
+        var length=new byte[4]; int count=server.Read(length,0,4);
+        if(count==0) return 0; // Refused peers must receive no request bytes.
+        Need(count==4 && BitConverter.ToInt32(length,0)==117,"bad request frame");
+        int remaining=117; var buffer=new byte[117];
+        while(remaining>0) { int n=server.Read(buffer,117-remaining,remaining); Need(n>0,"truncated request"); remaining-=n; }
+        if(answer) {
+          using(var writer=new BinaryWriter(server,System.Text.Encoding.Unicode,true)) {
+            writer.Write(8); writer.Write(3); writer.Write(Process.GetCurrentProcess().Id); writer.Flush();
+          }
+        } else Thread.Sleep(1500);
+        return 121;
+      });
+      bool accepted=NccgsUnityCompilerShutdown.Request(job,process,pid,name);
+      Need(accepted==expected,"incorrect shutdown acknowledgement");
+      Need(receive.Wait(3000),"pipe fixture failed to settle");
+      if(!expected && answer) Need(receive.Result==0,"foreign/unowned peer received shutdown bytes");
+    }
+  }
+  public static int Main(string[] args) {
+    IntPtr job=CreateJobObject(IntPtr.Zero,null);
+    try {
+      Need(job!=IntPtr.Zero,"job creation failed");
+      var process=Process.GetCurrentProcess();
+      // Golden frame captured from the installed Roslyn 4.3.1 serializer, not a
+      // second implementation of our own encoder.
+      const string golden="75000000000000000000000000000000000000002125534450340031006100350061006600390064003200630034003500390061003000360063003000370039003500620066003200310061003100630030003400360032003000300066003300370035006200660001000000257214510000000000000000";
+      Need(BitConverter.ToString(NccgsUnityCompilerShutdown.ShutdownFrame()).Replace("-","").ToLowerInvariant()==golden,"Roslyn protocol changed");
+      Exchange(job,process.Handle,process.Id,false,true); // Same PID, foreign job.
+      Need(AssignProcessToJobObject(job,process.Handle),"fixture job assignment failed");
+      Exchange(job,process.Handle,process.Id+1000000,false,true); // Wrong pipe server PID.
+      Exchange(job,process.Handle,process.Id,true,true); // Exact owned pipe.
+      Exchange(job,process.Handle,process.Id,false,false); // Missing acknowledgement stays unconfirmed.
+      string data=Path.Combine(args[0],"Editor","Data");
+      string dll=Path.Combine(data,"DotNetSdkRoslyn","VBCSCompiler.dll"),host=Path.Combine(data,"NetCoreRuntime","dotnet.exe");
+      Directory.CreateDirectory(Path.GetDirectoryName(dll)); Directory.CreateDirectory(Path.GetDirectoryName(host));
+      File.WriteAllText(dll,"unqualified binary"); File.WriteAllText(host,"unqualified host");
+      Need(NccgsUnityCompilerShutdown.QualifiedPipe(host,new[]{host,"exec",dll,"-pipename:safe"})==null,"unqualified binaries accepted");
+      Need(NccgsUnityCompilerShutdown.QualifiedPipe(host,new[]{host,"exec",dll,"-pipename:../../foreign"})==null,"invalid pipe accepted");
+      Need(NccgsUnityCompilerShutdown.QualifiedPipe(host,new[]{host,"exec",dll,"-pipename:safe","-shutdown"})==null,"unexpected arguments accepted");
+      Console.WriteLine("compiler shutdown guards PASS"); return 0;
+    } catch(Exception error) { Console.Error.WriteLine(error); return 1; }
+    finally { if(job!=IntPtr.Zero) CloseHandle(job); }
+  }
+}

package/tests/framework.test.mjs

@@ -459,6 +459,44 @@ test("update replaces untouched files, preserves local overrides, and doctor gat
   }
 });
 
+test("update adopts unchanged generated agents newly tracked by the package, preserving real edits", () => {
+  const f = safetyFixture("nccgs-generated-adoption-");
+  try {
+    const installed = f.run("install", "--model-profile", "quality");
+    assert.equal(installed.status, 0, installed.stderr || installed.stdout);
+    const relative = ".claude/agents/nccgs-game-designer.md";
+    const file = path.join(f.project, relative);
+    const stateFile = path.join(f.project, ".claude/nccgs/install-state.json");
+    const generatedFile = path.join(f.project, ".nccgs/agent-activation.json");
+    const original = fs.readFileSync(file, "utf8");
+    // Older packages can generate a profile's optional agent without listing it
+    // in install-state.files. A later package can make that agent a core file.
+    const state = JSON.parse(fs.readFileSync(stateFile, "utf8"));
+    state.files = state.files.filter(item => item.relative !== relative);
+    fs.writeFileSync(stateFile, JSON.stringify(state));
+    const update = f.run("update");
+    assert.equal(update.status, 0, update.stderr || update.stdout);
+    const doctor = f.run("doctor");
+    assert.equal(doctor.status, 0, doctor.stderr || doctor.stdout);
+    assert.equal(fs.readFileSync(file, "utf8"), original);
+    assert.ok(JSON.parse(fs.readFileSync(stateFile)).files.some(item => item.relative === relative));
+
+    // A stored generated hash alone must never authorize replacing later edits.
+    const nextState = JSON.parse(fs.readFileSync(stateFile, "utf8"));
+    nextState.files = nextState.files.filter(item => item.relative !== relative);
+    fs.writeFileSync(stateFile, JSON.stringify(nextState));
+    assert.ok(JSON.parse(fs.readFileSync(generatedFile)).generated[relative]);
+    const customized = original + "\nOwner instruction: keep the custom design rule.\n";
+    fs.writeFileSync(file, customized);
+    const preserved = f.run("update");
+    assert.equal(preserved.status, 0, preserved.stderr || preserved.stdout);
+    assert.equal(fs.readFileSync(file, "utf8"), customized);
+    const manifest = JSON.parse(fs.readFileSync(path.join(f.project, ".nccgs/framework-overrides.json")));
+    assert.equal(manifest.overrides.find(item => item.path === relative).status, "pending_review");
+    assert.equal(f.run("doctor").status, 1);
+  } finally { f.dispose(); }
+});
+
 test("doctor accepts a legacy CRLF raw hash after Git normalizes the file to LF", () => {
   const temp = fs.mkdtempSync(path.join(os.tmpdir(), "nccgs-eol-test-"));
   try {

package/tests/orchestration-v15.test.mjs

@@ -11,8 +11,10 @@ import { pinInputs } from "../.claude/nccgs/tools/inputs.mjs";
 import { artifact, atomicJson, hash, json } from "../.claude/nccgs/tools/policy.mjs";
 import { persistRuntimeObservation } from "../.claude/nccgs/tools/evidence.mjs";
 import { observe } from "../.claude/nccgs/tools/runtime.mjs";
-import { validateStandaloneRuntime, initializeStandalone, recordStandalone } from "../.claude/nccgs/tools/lifecycle.mjs";
+import { validateStandaloneRuntime, initializeStandalone, recordStandalone, migrateFrameworkBaseline } from "../.claude/nccgs/tools/lifecycle.mjs";
 import { guardTool } from "../.claude/nccgs/tools/tool-guard.mjs";
+import { acquireLock } from "../.claude/nccgs/tools/process-lock.mjs";
+import { sessionBudgetLock } from "../.claude/nccgs/tools/session-budget.mjs";
 
 // These are synthetic framework fixtures, never Claude Code execution evidence.
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
@@ -87,6 +89,55 @@ function external(action) {
 function failRun(f, run) {
   return external(() => reconcile(f.project, run.reservation.id, { status: "failed", reason: "TEST FIXTURE process confirmed terminated", reference: "TEST FIXTURE external process-exit receipt" }));
 }
+test("external framework migration proves the old inventory, rejects game changes and invalidates all approvals without quota refunds", () => {
+  const f = fixture();
+  try {
+    f.write('.nccgs/intake.json', { objective: 'Synthetic plan migration', mode: 'plan', analysisArtifacts: ['.nccgs/evidence/analysis/plan.md'] });
+    const t = initializeStandalone(f.project, 'migration', { intake: '.nccgs/intake.json' });
+    const beforeFiles = snapshot(f.project, t, { includeFiles: true }).fileEntries;
+    const run = f.start('migration'); failRun(f, run);
+    t.reviewBudget.used = 1; t.stages = { analysis: { fixture: true }, report: { outcome: 'partial' } }; f.write('.nccgs/tasks/migration.json', t);
+    const decision = '.nccgs/evidence/migration.json';
+    f.write(decision, { reason: 'Fixture framework patch', authority: 'Synthetic external fixture', beforeFiles });
+    f.write('.claude/nccgs/new-tool.mjs', '// fixture framework update');
+    f.write('Assets/game.cs', '// unauthorized source change');
+    assert.throws(() => external(() => migrateFrameworkBaseline(f.project, 'migration', decision)), /non-framework/);
+    f.write('Assets/game.cs', '// TEST FIXTURE source, not a game implementation\n');
+    process.env.CLAUDECODE = 'fixture';
+    try { assert.throws(() => migrateFrameworkBaseline(f.project, 'migration', decision), /external|External/); } finally { delete process.env.CLAUDECODE; }
+    const result = external(() => migrateFrameworkBaseline(f.project, 'migration', decision));
+    assert.equal(result.contractHash, t.contractHash); assert.equal(result.reviewBudget.used, 1); assert.deepEqual(result.stages, {});
+    assert.deepEqual(result.history.at(-1).stages, t.stages); assert.equal(result.history.at(-1).previousBaseline, t.analysisBaseline);
+    assert.equal(status(f.project, 'migration').usage.dispatches, 1);
+    assert.throws(() => external(() => migrateFrameworkBaseline(f.project, 'migration', decision)), /inventory/);
+  } finally { f.dispose(); }
+});
+test("missing worker cost admits only its live supervised allowance and keeps telemetry/limits/history", () => {
+  const f = fixture(), saved = [process.env.NCCGS_SUPERVISED_RUN, process.env.NCCGS_SUPERVISED_SESSION];
+  let lock;
+  try {
+    f.task("budget");
+    const run = f.start("budget", f.request("analysis", { limits: { maxCostUsd: 3 } }));
+    const observed = f.observation(run); complete(f.project, run.reservation.id, { runtime: observed });
+    assert.throws(() => reserve(f.project, "budget", f.request("analysis")), /missing costUsd/);
+    const id = "12345678-1234-1234-1234-123456789abc", sessionId = run.identity.sessionId;
+    f.write(`.nccgs/runs/${id}/run.json`, { id, project: f.project, taskId: "budget", sessionId, budgetUsd: 3, cumulativeCostUsd: 0,
+      deadline: Date.now() + 60000, status: "running", invocations: [{ status: "running", pid: process.pid }] });
+    lock = acquireLock(path.join(f.project, sessionBudgetLock), { runId: id, sessionId });
+    process.env.NCCGS_SUPERVISED_RUN = id; process.env.NCCGS_SUPERVISED_SESSION = sessionId;
+    const next = reserve(f.project, "budget", f.request("analysis"));
+    assert.equal(next.budgetEvidence[0].ceilingUsd, 3);
+    assert.throws(() => claim(f.project, next.id, { sessionId: "other", toolUseId: "next", agent: next.agent }), /owns its budget/);
+    const current = status(f.project, "budget"); assert.equal(current.usage.dispatches, 2); assert.equal(current.limits.maxCostUsd, 3);
+    assert.equal(current.telemetry.metrics.costUsd.total, null); assert.equal(current.telemetry.metrics.costUsd.measured, 0);
+    lock.release(); lock = null;
+    assert.throws(() => reserve(f.project, "budget", f.request("analysis")), /ENOENT/);
+  } finally {
+    lock?.release();
+    for (const [i,k] of ["NCCGS_SUPERVISED_RUN", "NCCGS_SUPERVISED_SESSION"].entries()) { if(saved[i]===undefined) delete process.env[k]; else process.env[k]=saved[i]; }
+    f.dispose();
+  }
+});
 test("external dispatch extension keeps spent attempts and parent cap, and rejects live or native changes", () => {
   const f = fixture();
   try {

package/tests/phase1.test.mjs

@@ -13,6 +13,7 @@ import { startCommand } from "../.claude/nccgs/tools/command-process.mjs";
 import { startVerification, waitVerification, jobStatus, readJob, jobDirectory } from "../.claude/nccgs/tools/verification-jobs.mjs";
 import { safeVerifyCommand, guardTool } from "../.claude/nccgs/tools/tool-guard.mjs";
 import { cumulativeCost, supervise } from "../scripts/supervise.mjs";
+import { registerReviewBudget, reviewBudgetStatus } from "../.claude/nccgs/tools/review-budget.mjs";
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 function fixture(timeoutMs = 5000, mode = "implement") {
@@ -213,6 +214,55 @@ test("OS-owned process group retains orphan descendants and proves their exit af
   } finally { if (host && pidState(host.pid) === "alive") host.kill("SIGKILL"); f.dispose(); }
 });
 
+test("managed wrappers avoid the resident Unity auth broker without changing the caller or persisting its environment", () => {
+  const f = fixture();
+  const key = "UNITY_NO_AUTH_BROKER", previous = process.env[key];
+  const sentinelKey = "NCCGS_TEST_PRIVATE_ENV", previousSentinel = process.env[sentinelKey];
+  const sentinel = crypto.randomUUID();
+  try {
+    // Even a wrapper, rather than a direct `unity` executable, must inherit it.
+    // Explicitly avoid modifying stored auth, peer-signature or account settings.
+    process.env[key] = "0"; process.env[sentinelKey] = sentinel;
+    const code = "const cp=require('node:child_process'); const c=cp.spawnSync(process.execPath,['-e',\"console.log(JSON.stringify({broker:process.env.UNITY_NO_AUTH_BROKER,peer:process.env.UNITY_PEER_AUTH_MODE??null,privateEnv:process.env.NCCGS_TEST_PRIVATE_ENV}))\"],{encoding:'utf8'});process.stdout.write(c.stdout);process.exitCode=c.status;";
+    const started = startVerification(f.project, "fixture", { name: "test", executable: process.execPath, arguments: ["-e", code], requestKey: "direct-keyring" });
+    const settled = waitVerification(f.project, started.jobId, "fixture", 15000);
+    assert.equal(settled.status, "PASS");
+    const receipt = json(path.join(f.project, settled.evidence.path));
+    const values = JSON.parse(fs.readFileSync(path.join(f.project, receipt.log.path), "utf8"));
+    assert.equal(values.broker, "1");
+    assert.equal(values.peer, process.env.UNITY_PEER_AUTH_MODE ?? null);
+    assert.equal(values.privateEnv, sentinel);
+    assert.equal(process.env[key], "0"); assert.equal(process.env[sentinelKey], sentinel);
+    // Environment values are inherited in memory, never serialized in the job
+    // specification or receipt (which may otherwise expose credentials).
+    assert.equal(JSON.stringify(receipt).includes(sentinel), false);
+    const spec = path.join(jobDirectory(f.project, started.jobId), `${started.jobId}-command.json`);
+    if (fs.existsSync(spec)) assert.equal(fs.readFileSync(spec, "utf8").includes(sentinel), false);
+  } finally {
+    if (previous === undefined) delete process.env[key]; else process.env[key] = previous;
+    if (previousSentinel === undefined) delete process.env[sentinelKey]; else process.env[sentinelKey] = previousSentinel;
+    f.dispose();
+  }
+});
+
+test("a completed wrapper still waits for its real descendant and retains the wrapper exit code", { skip: process.platform !== "win32" }, async () => {
+  const f = fixture();
+  try {
+    const descendant = "setTimeout(()=>require('node:fs').writeFileSync('.nccgs/evidence/descendant-completed.txt','done'),1800)";
+    const wrapper = `const cp=require('node:child_process'),fs=require('node:fs');const p=cp.spawn(process.execPath,['-e',${JSON.stringify(descendant)}],{stdio:'ignore',detached:true});fs.writeFileSync('.nccgs/evidence/wrapper-completed.txt','done');p.unref();process.exitCode=7;`;
+    const started = startVerification(f.project, "fixture", { name: "test", executable: process.execPath, arguments: ["-e", wrapper], requestKey: "descendant-drain" });
+    const marker = path.join(f.project, '.nccgs/evidence/wrapper-completed.txt');
+    const deadline = Date.now() + 10000;
+    while (!fs.existsSync(marker) && Date.now() < deadline) await delay(20);
+    assert.equal(fs.existsSync(marker), true);
+    assert.equal(jobStatus(f.project, started.jobId, "fixture").status, "RUNNING");
+    const result = waitVerification(f.project, started.jobId, "fixture", 15000);
+    assert.equal(result.status, "FAIL");
+    assert.equal(json(path.join(f.project, result.evidence.path)).exitCode, 7);
+    assert.equal(fs.readFileSync(path.join(f.project, '.nccgs/evidence/descendant-completed.txt'), 'utf8'), 'done');
+  } finally { f.dispose(); }
+});
+
 test("orphan verification becomes a retained failed attempt without rerunning the command", () => {
   const f = fixture();
   try {
@@ -228,6 +278,21 @@ test("orphan verification becomes a retained failed attempt without rerunning th
   } finally { f.dispose(); }
 });
 
+test("Unity compiler shutdown verifies exact pipe ownership, qualified binaries and bounded acknowledgement", { skip: process.platform !== "win32" }, () => {
+  const f = fixture();
+  try {
+    const binary = path.join(f.project, '.nccgs/compiler-shutdown-fixture.exe');
+    const compiler = path.join(process.env.SystemRoot || 'C:/Windows', 'Microsoft.NET/Framework64/v4.0.30319/csc.exe');
+    const built = spawnSync(compiler, ['/nologo', '/target:exe', `/out:${binary}`,
+      path.join(root, '.claude/nccgs/tools/windows-compiler-server.cs'),
+      path.join(root, 'tests/fixtures/compiler-shutdown.cs')], { encoding: 'utf8', windowsHide: true, timeout: 30000 });
+    assert.equal(built.status, 0, built.stdout + built.stderr);
+    const result = spawnSync(binary, [path.join(f.project, '.nccgs/fake-install')], { encoding: 'utf8', windowsHide: true, timeout: 10000 });
+    assert.equal(result.status, 0, result.stdout + result.stderr);
+    assert.match(result.stdout, /compiler shutdown guards PASS/);
+  } finally { f.dispose(); }
+});
+
 // The fake native executable below is explicitly a fixture, never Claude evidence.
 function fakeNative(f, { missingUsage = false, omitReport = false } = {}) {
   return f.write(".nccgs/fake-native.mjs", `
@@ -240,6 +305,33 @@ else if(${!omitReport}) run(['report','--id','fixture','--outcome','partial','--
 console.log(JSON.stringify({type:'result',session_id:session,total_cost_usd:${missingUsage ? "null" : "resumed?0.6:0.4"},result:'Synthetic native result; no actual model execution'}));
 `);
 }
+test("supervisor clamps real launch arguments to work allowance and retains the final review reserve", async () => {
+  const f = fixture();
+  try {
+    f.write('.nccgs/evidence/budget-request.json', { schemaVersion: 1, authority: 'Synthetic test only', totalUsd: 1, finalReviewUsd: 0.4, totalDurationMs: 60000, finalReviewDurationMs: 10000 });
+    registerReviewBudget(f.project, 'fixture', '.nccgs/evidence/budget-request.json');
+    const binary = fakeNative(f), prompt = f.write('.nccgs/prompt.txt', 'Synthetic fixture only');
+    assert.equal(await supervise({ project: f.project, binary: process.execPath, mode: 'full', args: [binary], env: f.env,
+      supervision: { taskId: 'fixture', promptFile: prompt, budgetUsd: 1, maxResumes: 1, timeoutMs: 20000, budgetPhase: 'work' } }), 0);
+    const id = fs.readdirSync(path.join(f.project, '.nccgs/runs'), { withFileTypes: true }).find(e => e.isDirectory()).name;
+    const run = json(path.join(f.project, `.nccgs/runs/${id}/run.json`));
+    assert.equal(run.budgetUsd, 0.6); assert.equal(run.invocations[0].allowanceUsd, 0.6);
+    assert.ok(Math.abs(run.invocations[1].allowanceUsd - 0.2) < 1e-9); assert.equal(run.cumulativeCostUsd, 0.6);
+    assert.equal(reviewBudgetStatus(f.project, 'fixture').protectedReviewUsd, 0.4);
+  } finally { f.dispose(); }
+});
+test("final-review session blocks new engine jobs in both hook and direct lifecycle command", () => {
+  const f = fixture(), names = ['NCCGS_SUPERVISED_RUN','NCCGS_SUPERVISED_SESSION'], saved = names.map(n => process.env[n]);
+  try {
+    const id = crypto.randomUUID(), session = 'final-review-fixture';
+    f.write(`.nccgs/runs/${id}/run.json`, { sessionId: session, budgetPhase: 'final-review' });
+    f.write(`.nccgs/runtime/bindings/${session}.json`, { taskId: 'fixture' });
+    process.env.NCCGS_SUPERVISED_RUN = id; process.env.NCCGS_SUPERVISED_SESSION = session;
+    assert.throws(() => startVerification(f.project, 'fixture', { name: 'test', executable: process.execPath, arguments: ['-e','console.log(1)'] }), /Final-review reserve/);
+    assert.throws(() => guardTool(f.project, { session_id: session, tool_name: 'Bash', tool_input: { command: 'node .claude/nccgs/tools/task.mjs verify --id fixture --name test -- node helper.mjs' } }), /Final-review reserve/);
+    assert.throws(() => guardTool(f.project, { session_id: session, tool_name: 'Bash', tool_input: { command: 'node .claude/nccgs/tools/task.mjs budget-plan --id fixture --file .nccgs/evidence/budget.json' } }), /External decisions/);
+  } finally { names.forEach((n,i) => { if(saved[i]===undefined) delete process.env[n]; else process.env[n]=saved[i]; }); f.dispose(); }
+});
 test("supervisor waits outside the model, resumes the same session once, preserves cumulative budget and receipts", async () => {
   const f = fixture();
   try {

package/tests/policy-v15.test.mjs

@@ -96,6 +96,20 @@ test("compiler separates standalone ownership from preserved Astra contract", ()
   assert.doesNotMatch(outputs.get(".claude/agents/nccgs-adversarial-reviewer.md"), /^model: fable$/m);
 });
 
+test("generated turn ceilings track the role template and stale documentation is detected", () => {
+  const target = temporary();
+  fs.cpSync(packageRoot, target, { recursive: true });
+  const role = ".claude/nccgs/agent-library/nccgs-adversarial-reviewer.md";
+  const template = fs.readFileSync(path.join(target, role), "utf8");
+  write(target, role, template.replace(/^maxTurns: \d+$/m, "maxTurns: 199"));
+  const outputs = generated(target), routing = outputs.get(".claude/nccgs/routing.generated.md");
+  assert.match(routing, /\| nccgs-adversarial-reviewer \| 199 \|/);
+  assert.match(outputs.get(".claude/agents/nccgs-adversarial-reviewer.md"), /^maxTurns: 199$/m);
+  assert.ok(compile(target).includes(".claude/nccgs/routing.generated.md"));
+  compile(target, true);
+  assert.deepEqual(compile(target), []);
+});
+
 test("new install defaults to standalone without erasing custom settings and hooks", () => {
   const target = project();
   const custom = { matcher: "Read", hooks: [{ type: "command", command: "echo project-owned" }] };