nccgs 2.1.1 → 3.0.0-rc.2

package/.claude/nccgs/tools/paths.mjs

@@ -1,60 +0,0 @@
-import fs from "node:fs";
-import path from "node:path";
-
-// Managed manifests are portable POSIX paths. Reject Windows aliases even on
-// another host so an otherwise valid package cannot become unsafe on Windows.
-export function assertRelativePath(relative) {
-  if (typeof relative !== "string" || !relative || path.posix.isAbsolute(relative)
-      || path.win32.isAbsolute(relative) || /[\\<>:"|?*\u0000-\u001f]/.test(relative)) {
-    throw new Error(`Unsafe project-relative POSIX path: ${String(relative)}`);
-  }
-  for (const part of relative.split("/")) {
-    if (!part || part === "." || part === ".." || /[. ]$/.test(part)
-        || /^(?:con|prn|aux|nul|conin\$|conout\$|clock\$|com[1-9¹²³]|lpt[1-9¹²³])(?:\.|$)/i.test(part)) {
-      throw new Error(`Unsafe project-relative path component: ${relative}`);
-    }
-  }
-  return relative;
-}
-
-function statWithoutLinks(file) {
-  let stat;
-  try { stat = fs.lstatSync(file); }
-  catch (error) { if (error.code === "ENOENT") return null; throw error; }
-  if (stat.isSymbolicLink()) throw new Error(`Symlink/junction/reparse path is not supported: ${file}`);
-  return stat;
-}
-
-export function assertProjectRoot(project) {
-  const root = path.resolve(project);
-  let current = path.parse(root).root;
-  for (const part of root.slice(current.length).split(path.sep).filter(Boolean)) {
-    current = path.join(current, part);
-    const stat = statWithoutLinks(current);
-    if (!stat?.isDirectory()) throw new Error(`Project directory does not exist or is not a directory: ${current}`);
-  }
-  return root;
-}
-
-function inside(root, target) {
-  const relative = path.relative(root, target);
-  return relative === "" || (!path.isAbsolute(relative) && relative !== ".." && !relative.startsWith(`..${path.sep}`));
-}
-
-export function containedPath(project, relative) {
-  assertRelativePath(relative);
-  const root = assertProjectRoot(project);
-  const target = path.resolve(root, ...relative.split("/"));
-  if (target === root || !inside(root, target)) throw new Error(`Path escapes project: ${relative}`);
-  const realRoot = fs.realpathSync(root);
-  let current = root;
-  const parts = relative.split("/");
-  for (let index = 0; index < parts.length; index++) {
-    current = path.join(current, parts[index]);
-    const stat = statWithoutLinks(current);
-    if (!stat) break; // All remaining components are new, after lexical validation.
-    if (index < parts.length - 1 && !stat.isDirectory()) throw new Error(`Parent path is not a directory: ${current}`);
-    if (!inside(realRoot, fs.realpathSync(current))) throw new Error(`Resolved path escapes project: ${relative}`);
-  }
-  return target;
-}

package/.claude/nccgs/tools/policy.mjs

@@ -1,107 +0,0 @@
-import fs from "node:fs";
-import path from "node:path";
-import crypto from "node:crypto";
-import { containedPath } from "./paths.mjs";
-
-export const hash = (value) => crypto.createHash("sha256").update(value).digest("hex");
-export const json = (file) => JSON.parse(fs.readFileSync(file, "utf8"));
-export function loadPipeline(project) {
-  const pipeline = json(path.join(project, ".claude/nccgs/pipeline.json"));
-  if (pipeline.schemaVersion !== 1) throw new Error("Unsupported pipeline schema");
-  if (!pipeline.profiles?.[pipeline.defaultProfile]) throw new Error("Invalid default profile");
-  if (!Array.isArray(pipeline.coreAgents) || !pipeline.coreAgents.includes(pipeline.contract?.reviewAgent)) throw new Error("Core agents must include the required reviewer");
-  if (JSON.stringify(pipeline.profiles["astra-claude"]?.activeAgents) !== JSON.stringify(pipeline.coreAgents)) throw new Error("Default Astra active agents must match coreAgents");
-  if (pipeline.profiles["claude-standalone"] && JSON.stringify(pipeline.profiles["claude-standalone"].activeAgents) !== JSON.stringify(pipeline.coreAgents)) throw new Error("Standalone active agents must match coreAgents");
-  for (const profile of Object.values(pipeline.profiles)) {
-    for (const route of Object.values(profile.models ?? {})) {
-      if (!(route.model === null || typeof route.model === "string") || ![null, "low", "medium", "high", "xhigh", "max"].includes(route.effort)) throw new Error("Invalid model/effort route");
-    }
-    if (profile.session && !profile.models[profile.session.class]) throw new Error("Unknown session model class");
-  }
-  for (const risk of ["FAST", "STANDARD", "CONTROLLED"]) {
-    const tier = pipeline.contract.taskTiers?.[risk];
-    const expectedClass = { FAST: "lightweight", STANDARD: "standard", CONTROLLED: "deep" }[risk];
-    if (tier?.implementationClass !== expectedClass || !pipeline.profiles["astra-claude"].models[expectedClass]) throw new Error(`Invalid implementation route for ${risk}`);
-    if (!Number.isSafeInteger(tier.maxReviewRounds) || tier.maxReviewRounds < 1 || tier.maxReviewRounds > 10) throw new Error(`Invalid review-round budget for ${risk}`);
-  }
-  return pipeline;
-}
-export function selectedProfile(project, explicit) {
-  const file = contained(project, ".nccgs/project.yaml");
-  const text = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
-  const block = text.match(/^models:[ \t]*\r?\n((?:[ \t]+[^\n]*\n?|\s*\n)*)/m)?.[1] ?? "";
-  const value = block.match(/^\s+profile:\s*([^#\r\n]+)/m)?.[1]?.trim().replace(/^['"]|['"]$/g, "");
-  if (explicit || value) return explicit || value;
-  // Legacy schema-1 policy is preserved byte-for-byte during installation.
-  // Its explicit selection lives in installation/activation metadata until the
-  // user migrates the project policy; never silently replace it with a new default.
-  const installed = contained(project, ".claude/nccgs/install-state.json");
-  const installedProfile = fs.existsSync(installed) ? json(installed).modelProfile : null;
-  if (installedProfile) return installedProfile;
-  const activated = contained(project, ".nccgs/agent-activation.json");
-  const activatedProfile = fs.existsSync(activated) ? json(activated).profile : null;
-  if (activatedProfile) return activatedProfile;
-  return loadPipeline(project).defaultProfile;
-}
-export function profilePolicy(project, explicit) {
-  const pipeline = loadPipeline(project);
-  const name = selectedProfile(project, explicit);
-  if (!Object.hasOwn(pipeline.profiles, name)) throw new Error(`Unknown model profile '${name}'`);
-  return { pipeline, name, profile: pipeline.profiles[name] };
-}
-export function executionPolicy(value) {
-  if (!value || typeof value !== "object" || Array.isArray(value) || value.schemaVersion !== 1) throw new Error("Unsupported execution policy schema; expected schemaVersion 1");
-  const allowed = new Set(["schemaVersion", "name", "externalReview", "acceptanceRequired", "requireObservedEffort", "maxParallelWorkers", "designReviewRequired", "reviewContractRequired"]);
-  for (const key of Object.keys(value)) if (!allowed.has(key)) throw new Error(`Unknown execution policy field: ${key}`);
-  if (!["standalone", "compatibility"].includes(value.name)) throw new Error("Execution name must be standalone or compatibility");
-  const standalone = value.name === "standalone";
-  const external = value.externalReview === undefined ? { mode: standalone ? "off" : "required" } : value.externalReview;
-  if (!external || typeof external !== "object" || Array.isArray(external) || Object.keys(external).some(key => key !== "mode") || !["off", "advisory", "required"].includes(external.mode)) throw new Error("externalReview.mode must be off, advisory or required");
-  for (const field of ["acceptanceRequired", "requireObservedEffort", "designReviewRequired", "reviewContractRequired"]) if (value[field] !== undefined && typeof value[field] !== "boolean") throw new Error(`${field} must be boolean`);
-  const workers = value.maxParallelWorkers === undefined ? (standalone ? 2 : 4) : value.maxParallelWorkers;
-  if (!Number.isSafeInteger(workers) || workers < 1 || workers > 4) throw new Error("maxParallelWorkers must be an integer from 1 to 4");
-  if (!standalone && (external.mode !== "required" || value.acceptanceRequired === false || value.requireObservedEffort === false)) throw new Error("Compatibility execution preserves required external review, acceptance and observed effort; migrate explicitly to standalone to change these obligations");
-  return { name: value.name, externalReview: { mode: external.mode }, acceptanceRequired: value.acceptanceRequired ?? !standalone,
-    requireObservedEffort: value.requireObservedEffort ?? !standalone, maxParallelWorkers: workers,
-    ...(value.designReviewRequired !== undefined ? { designReviewRequired: value.designReviewRequired } : {}),
-    ...(value.reviewContractRequired !== undefined ? { reviewContractRequired: value.reviewContractRequired } : {}) };
-}
-// Model selection and execution obligations are intentionally independent. A
-// missing file is a legacy project, never implicit permission to drop gates.
-export function resolveExecution(project) {
-  const { name: profileName, profile } = profilePolicy(project);
-  const file = contained(project, ".nccgs/execution.json");
-  const execution = executionPolicy(fs.existsSync(file) ? json(file) : { schemaVersion: 1, name: "compatibility" });
-  return { name: execution.name, profileName, profile, externalReview: execution.externalReview,
-    acceptanceRequired: execution.acceptanceRequired, requireObservedEffort: execution.requireObservedEffort, maxParallelWorkers: execution.maxParallelWorkers,
-    ...(execution.designReviewRequired !== undefined ? { designReviewRequired: execution.designReviewRequired } : {}),
-    ...(execution.reviewContractRequired !== undefined ? { reviewContractRequired: execution.reviewContractRequired } : {}) };
-}
-export function contained(project, relative) {
-  return containedPath(project, relative);
-}
-export function atomicJson(file, value) {
-  fs.mkdirSync(path.dirname(file), { recursive: true });
-  const temp = `${file}.${crypto.randomUUID()}.tmp`;
-  fs.writeFileSync(temp, `${JSON.stringify(value, null, 2)}\n`, { flag: "wx" });
-  // Windows readers/scanners can briefly deny atomic replacement. Retain the old
-  // complete file and retry only bounded sharing failures, never unlink it first.
-  for (let attempt = 0; ; attempt++) {
-    try { fs.renameSync(temp, file); break; }
-    catch (error) {
-      if (process.platform !== "win32" || !["EPERM", "EACCES", "EBUSY"].includes(error.code) || attempt >= 24) throw error;
-      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 20);
-    }
-  }
-}
-export function artifact(project, relative) {
-  const file = contained(project, relative);
-  if (!fs.statSync(file).isFile()) throw new Error(`Artifact is not a file: ${relative}`);
-  const bytes = fs.readFileSync(file);
-  if (!bytes.length) throw new Error(`Empty artifact: ${relative}`);
-  return { path: relative, sha256: hash(bytes) };
-}
-export function verifyArtifact(project, ref) {
-  if (!ref?.sha256 || artifact(project, ref.path).sha256 !== ref.sha256) throw new Error(`Missing or stale artifact: ${ref?.path ?? "unknown"}`);
-  return contained(project, ref.path);
-}

package/.claude/nccgs/tools/process-lock.mjs

@@ -1,74 +0,0 @@
-import fs from "node:fs";
-import os from "node:os";
-import path from "node:path";
-import crypto from "node:crypto";
-import { atomicJson } from "./policy.mjs";
-import { windowsGroupState } from "./command-process.mjs";
-
-export const delay = ms => new Promise(resolve => setTimeout(resolve, ms));
-export function pidState(pid) {
-  if (!Number.isSafeInteger(pid) || pid <= 0) return "unknown";
-  try { process.kill(pid, 0); return "alive"; }
-  catch (error) { return error.code === "ESRCH" ? "dead" : "unknown"; }
-}
-// No age-based eviction. A reused PID is conservatively treated as live.
-// Foreground commands must not daemonize/detach their descendants.
-export function treeState(child) {
-  if (!child?.pid) return "unknown";
-  const root = pidState(child.pid);
-  if (root !== "dead") return root;
-  if (process.platform !== "win32") {
-    if (!child.group) return "unknown";
-    try { process.kill(-child.pid, 0); return "alive"; }
-    catch (error) { return error.code === "ESRCH" ? "dead" : "unknown"; }
-  }
-  // Only OS-owned groups prove descendant termination. Legacy/unmanaged process
-  // trees remain unknown, even when the direct child PID no longer exists.
-  return child.windowsJob ? windowsGroupState(child.groupName) : "unknown";
-}
-export function ownerState(record) {
-  if (record?.schemaVersion !== 1 || record.host !== os.hostname() || !record.token) return "unknown";
-  const owner = pidState(record.pid);
-  if (owner !== "dead") return owner;
-  if (record.phase === "spawning") return "unknown"; // crash between spawn and PID persistence
-  if (record.child) return treeState(record.child);
-  return "dead";
-}
-export function acquireLock(file, metadata = {}) {
-  fs.mkdirSync(path.dirname(file), { recursive: true });
-  const record = { ...metadata, schemaVersion: 1, host: os.hostname(), pid: process.pid,
-    token: crypto.randomUUID(), createdAt: new Date().toISOString(), phase: "owned", child: null };
-  const create = () => {
-    const fd = fs.openSync(file, "wx");
-    try { fs.writeFileSync(fd, JSON.stringify(record)); } finally { fs.closeSync(fd); }
-  };
-  try { create(); }
-  catch (error) {
-    if (error.code !== "EEXIST") throw error;
-    let old;
-    try { old = JSON.parse(fs.readFileSync(file, "utf8")); } catch { /* unknown owner */ }
-    if (ownerState(old) !== "dead") throw new Error(`Locked: ${file}; owner/child is live or unverified; no lease expiry`);
-    // Serialize reclaimers. An interrupted recovery is deliberately fail-closed.
-    let recovery;
-    try { recovery = fs.openSync(`${file}.recovery`, "wx"); }
-    catch { throw new Error(`Locked: ${file}; recovery already in progress or needs inspection`); }
-    try {
-      fs.writeFileSync(recovery, JSON.stringify(record));
-      const current = JSON.parse(fs.readFileSync(file, "utf8"));
-      if (current.token !== old.token || ownerState(current) !== "dead") throw new Error(`Locked: ${file}; ownership changed`);
-      fs.appendFileSync(`${file}.recoveries.jsonl`, JSON.stringify({ at: new Date().toISOString(), previous: current, recoveredBy: record }) + "\n");
-      fs.unlinkSync(file);
-      create();
-    } finally { fs.closeSync(recovery); fs.unlinkSync(`${file}.recovery`); }
-  }
-  return {
-    record,
-    update(changes) {
-      if (JSON.parse(fs.readFileSync(file, "utf8")).token !== record.token) throw new Error("Lock ownership changed");
-      Object.assign(record, changes); atomicJson(file, record);
-    },
-    release() {
-      if (fs.existsSync(file) && JSON.parse(fs.readFileSync(file, "utf8")).token === record.token) fs.unlinkSync(file);
-    }
-  };
-}

package/.claude/nccgs/tools/repair-packet.mjs

@@ -1,106 +0,0 @@
-import fs from "node:fs";
-import path from "node:path";
-import { artifact, contained, json, verifyArtifact } from "./policy.mjs";
-import { validateUnityRepair, unityEditorToolScope, repairEditorCommand, unityCodePath, unitySceneSafety } from "./unity-repair.mjs";
-
-const need = (ok, message) => { if (!ok) throw new Error(message); };
-export const repairLimits = Object.freeze({ workCalls: 12, readCalls: 6, handoffCalls: 3, durationMs: 600000 });
-const text = (value, max) => typeof value === "string" && value.trim().length > 0 && value.length <= max;
-const keys = (value, allowed) => value && typeof value === "object" && !Array.isArray(value) && Object.keys(value).every(k => allowed.includes(k));
-
-// A repair is an already-decided source edit, not another discovery experiment.
-// Checks stay with the coordinator and retain the existing verification receipts.
-export function pinRepairPacket(project, task, request, snapshot) {
-  need(typeof request.workPacket === "string" && request.workPacket.startsWith(".nccgs/evidence/work-packets/") && request.workPacket.endsWith(".json"), "Repair requires a workPacket JSON under .nccgs/evidence/work-packets/");
-  const reference = artifact(project, request.workPacket);
-  need(fs.statSync(contained(project, reference.path)).size <= 32768, "Repair packet exceeds 32 KiB; narrow the work before dispatch");
-  const packet = json(verifyArtifact(project, reference));
-  const unity = packet.schemaVersion === 2;
-  need(keys(packet, ["schemaVersion", "taskId", "contractHash", "sourceSnapshot", "problem", "solution", "changes", "context", "verification", "budget", ...(unity ? ["repairType", "unity"] : [])]) && [1, 2].includes(packet.schemaVersion), "Invalid repair packet schema");
-  if (!unity) need(fs.statSync(contained(project, reference.path)).size <= 16384, "Repair packet exceeds 16 KiB; narrow the work before dispatch");
-  need(packet.taskId === task.id && packet.contractHash === task.contractHash && packet.sourceSnapshot === snapshot, "Repair packet task/contract/source snapshot is stale or mismatched");
-  need(text(packet.problem, 800) && text(packet.solution, 1600), "Repair packet needs a concise problem and chosen solution");
-  need(Array.isArray(packet.changes) && packet.changes.length >= 1 && packet.changes.length <= (unity ? 8 : 4), "Repair packet must specify 1-4 exact existing source files (up to 8 in a typed Unity packet)");
-  for (const change of packet.changes) {
-    need(keys(change, ["path", "instruction", ...(unity ? ["operation"] : [])]) && text(change.instruction, 1600), "Each repair change needs an exact path and bounded instruction");
-    const file = contained(project, change.path);
-    if (!unity) need(!/^\.(?:nccgs|claude|git)(?:\/|$)/i.test(change.path) && fs.statSync(file).isFile(), "Repair changes must be existing source files, not governance or evidence");
-  }
-  const limits = unity ? validateUnityRepair(project, packet) : repairLimits;
-  const paths = packet.changes.map(c => c.path).sort();
-  need(new Set(paths.map(p => p.toLowerCase())).size === paths.length && JSON.stringify(paths) === JSON.stringify([...request.writePaths].sort()), "Repair writePaths must exactly match packet files; directory ownership is not allowed");
-  need(request.handoffPaths?.length === 1, "Repair requires exactly one fresh handoff path");
-  if (unity) need(!request.handoffPaths.includes(packet.unity.capabilities?.path), "Unity capability evidence cannot be its handoff");
-  need(Array.isArray(packet.context) && packet.context.length <= 4, "Repair context must contain at most four pinned evidence references");
-  for (const ref of packet.context) {
-    need(ref?.path?.startsWith(".nccgs/evidence/") && !ref.path.startsWith(".nccgs/evidence/work-packets/") && !request.handoffPaths.includes(ref.path), "Repair context must reference existing evidence, not the packet or its handoff");
-    verifyArtifact(project, ref);
-  }
-  need(Array.isArray(packet.verification) && packet.verification.length > 0 && new Set(packet.verification).size === packet.verification.length &&
-    packet.verification.every(name => task.contract.requiredChecks.includes(name)) && task.contract.requiredChecks.every(name => packet.verification.includes(name)), "Repair verification must list the task's required checks for the coordinator");
-  need(packet.budget === undefined || keys(packet.budget, Object.keys(repairLimits)), "Unknown repair budget field");
-  const budget = { ...limits, ...packet.budget };
-  for (const [name, value] of Object.entries(budget)) need(Number.isSafeInteger(value) && value >= 1 && value <= limits[name], `Repair ${name} must be between 1 and ${limits[name]}`);
-  need(budget.readCalls <= budget.workCalls, "Repair readCalls cannot exceed workCalls");
-  return { ...packet, reference, budget, ...(unity ? { sceneSafety: unitySceneSafety } : {}) };
-}
-
-export function verifyRepairPacket(project, dispatch) {
-  verifyArtifact(project, dispatch.workPacket.reference);
-  for (const ref of dispatch.workPacket.context) verifyArtifact(project, ref);
-  if (dispatch.workPacket.schemaVersion === 2) {
-    if (dispatch.workPacket.unity.capabilities) verifyArtifact(project, dispatch.workPacket.unity.capabilities);
-    verifyArtifact(project, dispatch.workPacket.scope);
-  }
-}
-
-export function repairPrompt(task, dispatch) {
-  const p = dispatch.workPacket;
-  return `[NCCGS-DISPATCH:${dispatch.id}]\nBounded repair for task ${task.id}: ${task.contract.objective ?? task.objective ?? dispatch.reason}\n` +
-    `Packet: ${p.reference.path} sha256=${p.reference.sha256}\nContract: ${dispatch.contractHash}\nStarting source: ${dispatch.snapshot}\n` +
-    `Problem: ${p.problem}\nChosen solution: ${p.solution}\n` +
-    p.changes.map(c => `${c.operation ?? "Edit"} ${c.path}: ${c.instruction}`).join("\n") +
-    `\nContext references: ${JSON.stringify(p.context)}\n` +
-    `Limits: ${p.budget.workCalls} work tool calls, including at most ${p.budget.readCalls} reads/searches; ${p.budget.durationMs} ms from claim. Separate ${p.budget.handoffCalls} handoff writes. Native turns are separate and are not guaranteed by these counters.\n` +
-    (p.schemaVersion === 2
-      ? `Repair profile: ${p.repairType}. Read/Grep/Glob within this project. ${p.repairType === "unity-code" ? "Write/Edit/MultiEdit only the listed source files." : "Write/Edit/MultiEdit only the listed code files. Change serialized assets only through pinned Editor steps; no raw asset or metadata edits."} Never hand-write .meta files. No general shell, MCP, web, nested agents or parameter sweeps.\n` +
-        (p.sceneSafety ? "Every Editor step first checks all loaded scenes in the same eval. If any scene is dirty, the operation is blocked without saving/discarding it. Return PARTIAL; preserve the attempt and let the owner resolve unsaved work.\n" : "") +
-        (p.unity.steps.length ? `Pinned Unity capabilities: ${JSON.stringify(p.unity.capabilities)}\nRun these foreground Bash tool inputs once, in order; stop and return PARTIAL on a failed or uncertain step:\n`
-          : "No Editor steps are reserved; apply only the existing-file code correction.\n") +
-        p.unity.steps.map(s => JSON.stringify({ command: repairEditorCommand(dispatch, s), timeout: s.timeoutMs + 5000 }) + `\nEditor operation: ${s.command} ${JSON.stringify(s.arguments)}\n`).join("") +
-        "Finish saving/importing all exact files and their Unity-generated metadata before returning; new paths, deleted files or changed existing GUIDs fail completion. Editor return/exit zero is not verification evidence.\n"
-      : `Read/Grep/Glob within this project; Write/Edit/MultiEdit only the listed files. No shell, MCP, web, nested agents, or parameter sweeps.\n`) +
-    `Handoff: ${dispatch.handoffPaths[0]}. Write NCCGS-HANDOFF: PARTIAL early, then replace with NCCGS-HANDOFF: COMPLETE only when these edits are finished. Include changed files, rationale, unverified checks, risks and next owner. Return PARTIAL if the chosen solution needs more investigation.\n` +
-    `Coordinator runs required checks after return: ${p.verification.join(", ")}. COMPLETE is edit handoff, not acceptance PASS. Do not run or invent verification.\n`;
-}
-
-function toolPath(project, value, rootAllowed = false) {
-  need(typeof value === "string" && value.length > 0, "Repair tool needs an explicit project path");
-  const absolute = path.resolve(project, value), relative = path.relative(project, absolute).split(path.sep).join("/");
-  if (rootAllowed && !relative) return "";
-  contained(project, relative);
-  return relative;
-}
-
-// Classifies the request before admission; never executes a tool or command.
-export function repairToolScope(project, dispatch, input) {
-  const tool = input.tool_input ?? {}, name = input.tool_name;
-  const editor = unityEditorToolScope(dispatch, input);
-  if (editor) return editor;
-  if (["Write", "Edit", "MultiEdit"].includes(name)) {
-    const relative = toolPath(project, tool.file_path);
-    if (dispatch.handoffPaths.includes(relative)) return { bucket: "handoff", read: false };
-    need(dispatch.workPacket.repairType !== "unity-editor" || unityCodePath(relative), "Unity assets must be changed through pinned Editor steps, never raw file edits");
-    need(dispatch.writePaths.includes(relative), "Repair write is outside the packet's exact files");
-    return { bucket: "work", read: false };
-  }
-  if (["Read", "Grep", "Glob"].includes(name)) {
-    toolPath(project, name === "Read" ? tool.file_path : tool.path ?? project, name !== "Read");
-    if (name === "Glob" || (name === "Grep" && tool.glob)) {
-      const glob = name === "Glob" ? tool.pattern : tool.glob;
-      need(typeof glob === "string" && !path.posix.isAbsolute(glob) && !path.win32.isAbsolute(glob) && !/[\\:\x00-\x1f]/.test(glob) && !glob.includes(".."), "Repair search pattern must stay within the project");
-    }
-    return { bucket: "work", read: true };
-  }
-  throw new Error("Bounded repair permits only project reads and exact file edits; return the handoff and let the coordinator run declared checks");
-}

package/.claude/nccgs/tools/returned-handoff.mjs

@@ -1,47 +0,0 @@
-import fs from "node:fs";
-import path from "node:path";
-import { artifact, contained } from "./policy.mjs";
-import { nativeCompletion } from "./native-completion.mjs";
-
-// Opt-in transport for read-only workers whose native client returns reports as
-// text. Copy the sole model text block verbatim; never synthesize a verdict,
-// COMPLETE marker, identity, missing content or a replacement for an old attempt.
-export function captureReturnedHandoff(project, dispatch, input, completion, currentSnapshot) {
-  if (dispatch?.handoffTransport !== "native-result") return null;
-  const reject = reason => ({ transport: "native-result", status: "rejected", reason });
-  const response = input.tool_response;
-  if (input.hook_event_name !== "PostToolUse" || !["Agent", "Task"].includes(input.tool_name)
-      || dispatch.status !== "running" || !["analysis", "review"].includes(dispatch.kind)
-      || dispatch.sessionId !== input.session_id || dispatch.toolUseId !== input.tool_use_id
-      || !dispatch.agentId || dispatch.agentId !== response?.agentId
-      || dispatch.agent !== input.tool_input?.subagent_type || dispatch.snapshot !== currentSnapshot)
-    return reject("identity-or-snapshot-mismatch");
-  // Preserve an upstream failure and independently classify the actual response.
-  // A caller-supplied completion cannot certify unknown or incomplete metadata.
-  if (completion?.status !== "completed" || completion.reason)
-    return reject("native-incomplete");
-  const actual = nativeCompletion(response);
-  if (actual.status !== "completed" || actual.reason) return reject("native-incomplete");
-  // Classification validates every designated note and both counts. Strip only
-  // those blocks; model text, including lookalike tags, remains byte-for-byte.
-  const all = response.content;
-  const leading = response.harnessNoteCount ?? 0, tail = response.harnessTailCount ?? 0;
-  const blocks = Array.isArray(all) ? all.slice(leading, all.length - tail) : null;
-  if (!Array.isArray(blocks) || blocks.length !== 1 || blocks[0]?.type !== "text"
-      || typeof blocks[0].text !== "string" || !blocks[0].text.trim()
-      || Buffer.byteLength(blocks[0].text, "utf8") > 262144)
-    return reject("expected-one-bounded-text-block");
-  if (dispatch.handoffPaths?.length !== 1) return reject("expected-one-pinned-handoff");
-  const relative = dispatch.handoffPaths[0];
-  try {
-    const file = contained(project, relative);
-    fs.mkdirSync(path.dirname(file), { recursive: true });
-    // Revalidate newly created parents and refuse symlinks, existing drafts or
-    // concurrent writes. Existing file transport retains its original behavior.
-    contained(project, relative);
-    fs.writeFileSync(file, blocks[0].text, { flag: "wx" });
-    return { transport: "native-result", status: "captured", evidence: artifact(project, relative) };
-  } catch (error) {
-    return reject(error.code === "EEXIST" ? "handoff-already-exists" : "handoff-publication-failed");
-  }
-}

package/.claude/nccgs/tools/review-budget.mjs

@@ -1,171 +0,0 @@
-import fs from "node:fs";
-import { artifact, atomicJson, contained, hash, json, verifyArtifact } from "./policy.mjs";
-import { acquireLock, ownerState, pidState } from "./process-lock.mjs";
-import { sessionBudgetLock, settledCost, taskWithin } from "./session-budget.mjs";
-
-const need = (ok, message) => { if (!ok) throw new Error(`Review reserve: ${message}`); };
-const taskFile = (project, id) => {
-  need(typeof id === "string" && /^[a-zA-Z0-9][\w-]{0,79}$/.test(id), "invalid task ID");
-  return contained(project, `.nccgs/tasks/${id}.json`);
-};
-const planPath = id => `.nccgs/budgets/${id}.json`;
-const markerPath = id => `.nccgs/budgets/${id}.initialized.json`;
-const terms = plan => ({ schemaVersion: plan.schemaVersion, taskId: plan.taskId, limits: plan.limits,
-  request: plan.request, createdAt: plan.createdAt, deadline: plan.deadline, workDeadline: plan.workDeadline });
-function readPlan(project, id) {
-  const file = contained(project, planPath(id)), marker = contained(project, markerPath(id));
-  if (!fs.existsSync(file)) { need(!fs.existsSync(marker), "initialized budget history is missing; never reset it"); return null; }
-  const plan = json(file);
-  need(plan.schemaVersion === 1 && plan.taskId === id && Array.isArray(plan.allocations), "invalid budget plan");
-  need(fs.existsSync(marker) && json(marker).sha256 === hash(JSON.stringify(terms(plan))), "pinned budget terms changed or marker missing");
-  verifyArtifact(project, plan.request);
-  return plan;
-}
-export function findReviewBudget(project, id) {
-  const seen = new Set(); let found = null;
-  while (id) {
-    need(!seen.has(id), "task ancestry cycle"); seen.add(id);
-    const task = json(taskFile(project, id)), plan = readPlan(project, id);
-    need(!plan || !found, "nested budgets cannot mint another reserve");
-    if (plan) found = plan;
-    id = task.parentId;
-  }
-  return found;
-}
-function familyRuns(project, id) {
-  const dir = contained(project, ".nccgs/runs");
-  if (!fs.existsSync(dir)) return [];
-  return fs.readdirSync(dir, { withFileTypes: true }).filter(e => e.isDirectory()).map(e => {
-    const run = json(contained(project, `.nccgs/runs/${e.name}/run.json`));
-    need(run.id === e.name && run.project === project, "invalid native run history"); return run;
-  }).filter(run => taskWithin(project, run.taskId, id));
-}
-function requireWorkerCoverage(project, id, runs, ledger = null) {
-  const file = contained(project, ".nccgs/orchestration.json");
-  ledger ??= fs.existsSync(file) ? json(file) : null;
-  const sessions = new Set(runs.map(run => run.sessionId));
-  need(sessions.size === runs.length, "duplicate session across run records");
-  const workers = Object.values(ledger?.dispatches ?? {}).filter(d => d.startedAt && taskWithin(project, d.taskId, id));
-  need(workers.every(d => sessions.has(d.sessionId)), "worker session has no supervised cost coverage; preserve and reconcile historical spend");
-}
-function history(project, plan, currentId = null) {
-  const records = plan.allocations.map(ref => ({ ...json(verifyArtifact(project, ref)), reference: ref }));
-  need(new Set(records.map(r => r.runId)).size === records.length, "duplicate run allocation");
-  const runs = familyRuns(project, plan.taskId), ids = new Set(runs.map(r => r.id));
-  requireWorkerCoverage(project, plan.taskId, runs);
-  need(records.every(r => ids.has(r.runId)), "allocated run history is missing; spent allowances cannot be refunded");
-  const neverStarted = r => r.status === "blocked" && r.costCoverage === "complete" && r.invocations.length === 0 && r.cumulativeCostUsd === 0;
-  need(runs.every(r => r.id === currentId || records.some(a => a.runId === r.id) || neverStarted(r)), "unallocated native session; reconcile history before spending");
-  let workUsd = 0, reviewUsd = 0;
-  const sessions = [];
-  for (const run of runs.filter(r => r.id !== currentId)) {
-    const allocation = records.find(r => r.runId === run.id);
-    if (!allocation && neverStarted(run)) { sessions.push({ runId: run.id, sessionId: run.sessionId, phase: "not-started", costUsd: 0 }); continue; }
-    need(allocation.sessionId === run.sessionId && ["work", "final-review"].includes(allocation.phase), "allocation identity mismatch");
-    if (!allocation.legacy) need(run.budgetAllocation?.sha256 === allocation.reference.sha256, "native run allocation changed");
-    const cost = settledCost(project, run);
-    if (allocation.phase === "final-review") reviewUsd += cost; else workUsd += cost;
-    sessions.push({ runId: run.id, sessionId: run.sessionId, phase: allocation.phase, costUsd: cost });
-  }
-  return { records, sessions, workUsd, reviewUsd, totalUsd: workUsd + reviewUsd };
-}
-export function registerReviewBudget(project, id, relative) {
-  need(!process.env.CLAUDECODE && !process.env.CLAUDE_CODE_ENTRYPOINT, "budget allocation is external only");
-  const lock = acquireLock(contained(project, sessionBudgetLock), { operation: "register-review-reserve", taskId: id });
-  try {
-    const task = json(taskFile(project, id)), request = artifact(project, relative), input = json(verifyArtifact(project, request));
-    need(task.schemaVersion === 2 && !task.closed, "an open standalone root task is required");
-    const existing = findReviewBudget(project, id);
-    if (existing) { need(existing.taskId === id && existing.request.sha256 === request.sha256, "budget terms are already pinned; no replacement or extension"); return existing; }
-    need(!task.parentId, "register the reserve on the existing task root, never on a child");
-    need(input.schemaVersion === 1 && typeof input.authority === "string" && input.authority.trim(), "explicit external allocation authority is required");
-    const { totalUsd, finalReviewUsd, totalDurationMs, finalReviewDurationMs } = input;
-    need(Number.isFinite(totalUsd) && totalUsd > 0 && Number.isFinite(finalReviewUsd) && finalReviewUsd > 0 && finalReviewUsd < totalUsd, "invalid total/review cost allocation");
-    need(Number.isSafeInteger(totalDurationMs) && totalDurationMs >= 1000 && totalDurationMs <= 86400000
-      && Number.isSafeInteger(finalReviewDurationMs) && finalReviewDurationMs >= 1000 && finalReviewDurationMs < totalDurationMs, "invalid total/review time allocation");
-    const ledgerFile = contained(project, ".nccgs/orchestration.json"), ledger = fs.existsSync(ledgerFile) ? json(ledgerFile) : null;
-    need(!Object.values(ledger?.dispatches ?? {}).some(d => ["reserved", "running", "uncertain"].includes(d.status)), "settle all workers before allocating a reserve");
-    const pinned = ledger?.tasks[id]?.limits.maxCostUsd;
-    need(pinned == null || totalUsd <= pinned, "allocation cannot raise the pinned aggregate cap");
-    const prior = familyRuns(project, id);
-    requireWorkerCoverage(project, id, prior, ledger);
-    const spent = prior.reduce((sum, run) => sum + settledCost(project, run), 0);
-    need(spent < totalUsd - finalReviewUsd, "past spending leaves insufficient work/review reserve; cannot reserve spent money retroactively");
-    const createdAt = new Date().toISOString();
-    const deadline = prior.length ? Math.min(Date.now() + totalDurationMs, Math.max(...prior.map(r => r.deadline))) : Date.now() + totalDurationMs;
-    const workDeadline = deadline - finalReviewDurationMs;
-    need(Date.now() < workDeadline, "past elapsed time leaves no protected review window");
-    const plan = { schemaVersion: 1, taskId: id, request, limits: { totalUsd, finalReviewUsd, totalDurationMs, finalReviewDurationMs },
-      createdAt, deadline, workDeadline, allocations: [] };
-    for (const run of prior) {
-      const file = `.nccgs/budgets/allocations/${run.id}.json`;
-      atomicJson(contained(project, file), { runId: run.id, sessionId: run.sessionId, taskId: run.taskId, phase: "work", legacy: true, recordedAt: createdAt });
-      plan.allocations.push(artifact(project, file));
-    }
-    atomicJson(contained(project, markerPath(id)), { sha256: hash(JSON.stringify(terms(plan))) });
-    atomicJson(contained(project, planPath(id)), plan);
-    return plan;
-  } finally { lock.release(); }
-}
-export function allocateReviewBudget(project, state, phase = "work") {
-  const plan = findReviewBudget(project, state.taskId);
-  if (!plan) { need(phase === "work", "final-review needs a pinned aggregate reserve"); return null; }
-  need(["work", "final-review"].includes(phase), "unknown budget phase");
-  const lock = json(contained(project, sessionBudgetLock));
-  need(lock.runId === state.id && lock.sessionId === state.sessionId && ownerState(lock) === "alive", "exclusive supervisor ownership is required");
-  const task = json(taskFile(project, state.taskId));
-  need(phase !== "final-review" || ["implement", "audit"].includes(task.mode), "design review cannot consume the final delivery reserve");
-  const prior = history(project, plan, state.id), existing = prior.records.find(a => a.runId === state.id);
-  const available = phase === "work"
-    ? plan.limits.totalUsd - prior.workUsd - Math.max(plan.limits.finalReviewUsd, prior.reviewUsd)
-    : plan.limits.totalUsd - prior.totalUsd;
-  const deadline = phase === "work" ? plan.workDeadline : plan.deadline;
-  need(available > 0 && Date.now() < deadline, "phase allowance exhausted; retain the final review reserve and original total");
-  if (existing) {
-    need(existing.phase === phase && state.budgetAllocation?.sha256 === existing.reference.sha256
-      && state.budgetUsd === existing.allowanceUsd && state.deadline === existing.deadline, "recovery cannot alter the allocated phase, cost or deadline");
-    need(state.budgetUsd <= available + 1e-9 && state.deadline <= deadline && Date.now() < state.deadline, "historical spending/time no longer covers this allocation");
-    return existing;
-  }
-  const requestedUsd = state.budgetUsd, requestedDeadline = state.deadline;
-  state.budgetUsd = Math.min(requestedUsd, available); state.deadline = Math.min(requestedDeadline, deadline); state.budgetPhase = phase;
-  const value = { schemaVersion: 1, rootTaskId: plan.taskId, taskId: state.taskId, runId: state.id, sessionId: state.sessionId,
-    phase, requestedUsd, allowanceUsd: state.budgetUsd, requestedDeadline, deadline: state.deadline,
-    recordedAt: new Date().toISOString(), priorSessions: prior.sessions, protectedReviewUsd: Math.max(0, plan.limits.finalReviewUsd - prior.reviewUsd),
-    workerCostInferred: false };
-  const file = `.nccgs/budgets/allocations/${state.id}.json`;
-  need(!fs.existsSync(contained(project, file)), "allocation already exists; preserve interrupted history");
-  atomicJson(contained(project, file), value); state.budgetAllocation = artifact(project, file);
-  plan.allocations.push(state.budgetAllocation); atomicJson(contained(project, planPath(plan.taskId)), plan);
-  return value;
-}
-export function plannedDispatchBudget(project, id, request) {
-  const plan = findReviewBudget(project, id); if (!plan) return null;
-  const runId = process.env.NCCGS_SUPERVISED_RUN;
-  need(typeof runId === "string" && /^[a-f0-9-]{36}$/.test(runId), "planned tasks require their supervised allocation");
-  const state = json(contained(project, `.nccgs/runs/${runId}/run.json`));
-  need(state.taskId === id && state.sessionId === process.env.NCCGS_SUPERVISED_SESSION && state.status === "running"
-    && pidState(state.invocations.at(-1)?.pid) === "alive", "current allocated native session is not live/correlated");
-  const allocation = allocateReviewBudget(project, state, state.budgetPhase);
-  const task = json(taskFile(project, id));
-  if (allocation.phase === "final-review") need(request.kind === "review" && ["implement", "audit"].includes(task.mode), "final-review funds cannot dispatch implementation, repair, analysis or design workers");
-  else need(request.kind !== "review" || !["implement", "audit"].includes(task.mode), "delivery/audit review must use the protected final-review phase");
-  return { ...allocation, reference: state.budgetAllocation };
-}
-export function inFinalReviewPhase(project, sessionId) {
-  const id = process.env.NCCGS_SUPERVISED_RUN; if (!id) return false;
-  need(/^[a-f0-9-]{36}$/.test(id), "invalid supervised run ID");
-  const run = json(contained(project, `.nccgs/runs/${id}/run.json`));
-  need(run.sessionId === sessionId, "supervised session mismatch");
-  return run.budgetPhase === "final-review";
-}
-export function reviewBudgetStatus(project, id) {
-  const plan = findReviewBudget(project, id); if (!plan) return { taskId: id, planned: false };
-  const live = familyRuns(project, plan.taskId).filter(r => ["ready", "running", "waiting-for-verification"].includes(r.status));
-  need(live.length <= 1, "multiple unresolved native allocations");
-  const current = process.env.NCCGS_SUPERVISED_RUN ?? live[0]?.id ?? null, prior = history(project, plan, current);
-  return { taskId: id, planned: true, rootTaskId: plan.taskId, limits: plan.limits, deadline: plan.deadline, workDeadline: plan.workDeadline,
-    settledSessions: prior.sessions, settledCostUsd: prior.totalUsd, protectedReviewUsd: Math.max(0, plan.limits.finalReviewUsd - prior.reviewUsd),
-    currentAllocation: prior.records.find(a => a.runId === current) ?? null,
-    note: "In-flight actual cost remains unknown; the current allocation is a ceiling, never a worker cost or acceptance result." };
-}