@bvdm/delano 0.1.7 → 0.1.8

package/assets/payload/.agents/scripts/check-sync-schemas.mjs

@@ -0,0 +1,52 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const repoRoot = resolveRepoRoot(__dirname);
+const errors = [];
+const taxonomyPath = path.join(repoRoot, ".agents", "schemas", "sync", "drift-taxonomy.json");
+const syncMapSchemaPath = path.join(repoRoot, ".agents", "schemas", "sync", "sync-map.schema.json");
+const taxonomy = readJson(taxonomyPath, "drift taxonomy");
+const syncMapSchema = readJson(syncMapSchemaPath, "sync map schema");
+
+const requiredDrifts = ["mapping-drift", "status-drift", "dependency-drift", "orphan-drift", "repair-recommendation"];
+if (taxonomy.schema_version !== 1) errors.push("drift taxonomy schema_version must be 1.");
+const driftTypes = Array.isArray(taxonomy.drift_types) ? taxonomy.drift_types : [];
+for (const id of requiredDrifts) {
+  const drift = driftTypes.find((entry) => entry.id === id);
+  if (!drift) {
+    errors.push(`drift taxonomy missing type: ${id}`);
+    continue;
+  }
+  if (!drift.description || !Array.isArray(drift.severity) || drift.severity.length === 0 || !drift.repair_posture) {
+    errors.push(`drift type ${id} must define description, severity, and repair_posture.`);
+  }
+}
+
+if (syncMapSchema.type !== "object") errors.push("sync map schema must be an object schema.");
+for (const field of ["schema_version", "projects"]) {
+  if (!syncMapSchema.required?.includes(field)) errors.push(`sync map schema must require ${field}.`);
+}
+const projectProperties = syncMapSchema.properties?.projects?.items?.properties || {};
+for (const field of ["slug", "local_path", "linear_project_id", "github_repo", "tasks"]) {
+  if (!projectProperties[field]) errors.push(`sync map project schema missing ${field}.`);
+}
+
+if (errors.length > 0) {
+  console.error("Sync schema check failed:");
+  for (const error of errors) console.error(`- ${error}`);
+  process.exit(1);
+}
+console.log("Sync schema check passed for drift taxonomy and sync map schema.");
+
+function readJson(filePath, label) {
+  try { return JSON.parse(readFileSync(filePath, "utf8")); }
+  catch (error) { errors.push(`Could not read ${label}: ${error.message}`); return {}; }
+}
+function resolveRepoRoot(startDir) {
+  const candidates = [path.resolve(startDir, ".."), path.resolve(startDir, "..", "..")];
+  for (const candidate of candidates) if (existsSync(path.join(candidate, ".agents"))) return candidate;
+  return path.resolve(startDir, "..");
+}

package/assets/payload/.agents/scripts/check-text-safety.mjs

@@ -0,0 +1,158 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const repoRoot = path.resolve(__dirname, "..", "..");
+
+const bidiControls = new Map([
+  [0x200E, "LEFT-TO-RIGHT MARK"],
+  [0x200F, "RIGHT-TO-LEFT MARK"],
+  [0x202A, "LEFT-TO-RIGHT EMBEDDING"],
+  [0x202B, "RIGHT-TO-LEFT EMBEDDING"],
+  [0x202C, "POP DIRECTIONAL FORMATTING"],
+  [0x202D, "LEFT-TO-RIGHT OVERRIDE"],
+  [0x202E, "RIGHT-TO-LEFT OVERRIDE"],
+  [0x2066, "LEFT-TO-RIGHT ISOLATE"],
+  [0x2067, "RIGHT-TO-LEFT ISOLATE"],
+  [0x2068, "FIRST STRONG ISOLATE"],
+  [0x2069, "POP DIRECTIONAL ISOLATE"]
+]);
+
+const binaryExtensions = new Set([
+  ".bmp",
+  ".gif",
+  ".ico",
+  ".jpeg",
+  ".jpg",
+  ".pdf",
+  ".png",
+  ".tgz",
+  ".ttf",
+  ".webp",
+  ".woff",
+  ".woff2",
+  ".zip"
+]);
+
+const args = process.argv.slice(2);
+const files = resolveFiles(args);
+const findings = [];
+
+for (const file of files) {
+  const absolutePath = path.resolve(repoRoot, file);
+  if (!existsSync(absolutePath) || !statSync(absolutePath).isFile()) {
+    continue;
+  }
+
+  if (binaryExtensions.has(path.extname(absolutePath).toLowerCase())) {
+    continue;
+  }
+
+  const buffer = readFileSync(absolutePath);
+  if (isProbablyBinary(buffer)) {
+    continue;
+  }
+
+  inspectText(absolutePath, buffer.toString("utf8"));
+}
+
+if (findings.length > 0) {
+  console.error("Text safety check failed:");
+  for (const finding of findings) {
+    console.error(`- ${finding.file}:${finding.line}:${finding.column} contains ${finding.code} (${finding.name})`);
+  }
+  process.exit(1);
+}
+
+console.log(`Text safety check passed for ${files.length} tracked file(s).`);
+
+function resolveFiles(rawArgs) {
+  if (rawArgs.length === 0) {
+    return gitTrackedFiles();
+  }
+
+  const selectedFiles = [];
+  for (let index = 0; index < rawArgs.length; index += 1) {
+    const arg = rawArgs[index];
+    if (arg === "--file") {
+      const value = rawArgs[index + 1];
+      if (!value) {
+        throw new Error("--file requires a path");
+      }
+      selectedFiles.push(value);
+      index += 1;
+    } else {
+      selectedFiles.push(arg);
+    }
+  }
+
+  return selectedFiles;
+}
+
+function gitTrackedFiles() {
+  const output = execFileSync("git", ["ls-files", "-z"], {
+    cwd: repoRoot,
+    encoding: "buffer"
+  });
+
+  return output
+    .toString("utf8")
+    .split("\0")
+    .filter(Boolean);
+}
+
+function isProbablyBinary(buffer) {
+  const sampleLength = Math.min(buffer.length, 8000);
+  for (let index = 0; index < sampleLength; index += 1) {
+    if (buffer[index] === 0) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function inspectText(absolutePath, text) {
+  for (let index = 0; index < text.length; index += 1) {
+    const codePoint = text.codePointAt(index);
+    if (!bidiControls.has(codePoint)) {
+      continue;
+    }
+
+    const position = locate(text, index);
+    findings.push({
+      file: displayPath(absolutePath),
+      line: position.line,
+      column: position.column,
+      code: `U+${codePoint.toString(16).toUpperCase().padStart(4, "0")}`,
+      name: bidiControls.get(codePoint)
+    });
+  }
+}
+
+function locate(text, index) {
+  let line = 1;
+  let lineStart = 0;
+
+  for (let cursor = 0; cursor < index; cursor += 1) {
+    if (text[cursor] === "\n") {
+      line += 1;
+      lineStart = cursor + 1;
+    }
+  }
+
+  return {
+    line,
+    column: index - lineStart + 1
+  };
+}
+
+function displayPath(absolutePath) {
+  const relativePath = path.relative(repoRoot, absolutePath).replace(/\\/g, "/");
+  if (!path.isAbsolute(relativePath) && !relativePath.startsWith("..") && relativePath !== "") {
+    return relativePath;
+  }
+  return path.basename(absolutePath);
+}

package/assets/payload/.agents/scripts/check-worktree-health.mjs

@@ -0,0 +1,100 @@
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+
+const riskySharedPrefixes = [
+  ".agents/scripts/",
+  ".claude/scripts/",
+  "scripts/",
+  "package.json",
+  "assets/install-manifest.json",
+  "assets/payload/"
+];
+
+const status = git(["status", "--porcelain=v1"]);
+const branch = git(["rev-parse", "--abbrev-ref", "HEAD"]);
+const upstream = git(["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}"]);
+const worktreeList = git(["worktree", "list", "--porcelain"]);
+const worktreePrune = git(["worktree", "prune", "--dry-run", "--verbose"]);
+
+const issues = [];
+const warnings = [];
+if (status.status !== 0) issues.push("git status failed");
+const branchName = branch.stdout.trim();
+if (branch.status !== 0 || !branchName) issues.push("branch could not be resolved");
+else if (branchName === "HEAD") warnings.push("branch is detached");
+if (worktreeList.status !== 0) issues.push("git worktree list failed");
+if (worktreePrune.status !== 0) warnings.push("git worktree prune dry-run failed");
+
+const dirtyFiles = parseStatus(status.stdout);
+const riskySharedFiles = dirtyFiles.filter((file) => riskySharedPrefixes.some((prefix) => file.path === prefix || file.path.startsWith(prefix)));
+const worktrees = parseWorktrees(worktreeList.stdout);
+const staleWorktrees = parseStaleWorktrees(worktreePrune.stdout);
+
+for (const file of riskySharedFiles) warnings.push(`risky shared file is dirty: ${file.path}`);
+for (const stale of staleWorktrees) warnings.push(`stale worktree candidate: ${stale}`);
+
+const result = {
+  schema_version: 1,
+  branch: branchName || "unknown",
+  upstream: upstream.status === 0 ? upstream.stdout.trim() : "",
+  dirty: dirtyFiles.length > 0,
+  dirty_files: dirtyFiles,
+  risky_shared_files: riskySharedFiles,
+  worktrees,
+  stale_worktrees: staleWorktrees,
+  issues,
+  warnings
+};
+
+if (process.argv.includes("--json")) {
+  console.log(JSON.stringify(result, null, 2));
+} else {
+  console.log(`Worktree health: ${issues.length ? "issues" : "ok"}; dirty=${result.dirty}; branch=${result.branch}; risky=${riskySharedFiles.length}; stale=${staleWorktrees.length}.`);
+}
+if (issues.length) process.exit(1);
+
+function git(args) {
+  return spawnSync("git", args, { encoding: "utf8" });
+}
+function parseStatus(text) {
+  return text.split("\n").filter(Boolean).map((line) => {
+    const statusCode = line.slice(0, 2);
+    const rawPath = line.slice(3).trim();
+    const filePath = rawPath.includes(" -> ") ? rawPath.split(" -> ").pop() : rawPath;
+    return { status: statusCode.trim() || "??", path: normalizePath(filePath) };
+  });
+}
+function parseWorktrees(text) {
+  const entries = [];
+  let current = null;
+  for (const line of text.split("\n")) {
+    if (!line.trim()) {
+      if (current) entries.push(current);
+      current = null;
+      continue;
+    }
+    const [key, ...rest] = line.split(" ");
+    const value = rest.join(" ");
+    if (key === "worktree") current = { path: safeWorktreePath(value), branch: "", head: "", bare: false, detached: false };
+    else if (!current) continue;
+    else if (key === "HEAD") current.head = value;
+    else if (key === "branch") current.branch = value.replace(/^refs\/heads\//, "");
+    else if (key === "bare") current.bare = true;
+    else if (key === "detached") current.detached = true;
+  }
+  if (current) entries.push(current);
+  return entries;
+}
+function parseStaleWorktrees(text) {
+  return text.split("\n").map((line) => line.trim()).filter(Boolean).map((line) => normalizePath(line.replace(/^Removing worktrees\//, "worktrees/")));
+}
+function safeWorktreePath(value) {
+  const absolute = path.resolve(String(value || ""));
+  const cwd = path.resolve(process.cwd());
+  if (absolute === cwd) return ".";
+  if (absolute.startsWith(`${cwd}${path.sep}`)) return normalizePath(path.relative(cwd, absolute));
+  return `external:${path.basename(absolute)}`;
+}
+function normalizePath(value) {
+  return String(value || "").replaceAll(path.sep, "/");
+}

package/assets/payload/.agents/scripts/fix-path-standards.sh

@@ -9,6 +9,6 @@ fi
 
 for file in "$@"; do
   [[ -f "$file" ]] || { echo "Skip missing file: $file"; continue; }
-  perl -0777 -i -pe 's#/home/[^\s)]+#<ABS_PATH>#g; s#/Users/[^\s)]+#<ABS_PATH>#g; s#[A-Za-z]:\\[^\s)]+#<ABS_PATH>#g' "$file"
+  perl -0777 -i -pe 's#/home/[^\s)]+#<ABS_PATH>#g; s#/Users/[^\s)]+#<ABS_PATH>#g; s#/mnt/[A-Za-z]/[^\s)]+#<ABS_PATH>#g; s#[A-Za-z]:\\[^\s)]+#<ABS_PATH>#g' "$file"
   echo "Normalized paths in: $file"
 done

package/assets/payload/.agents/scripts/inspect-github-sync.mjs

@@ -0,0 +1,108 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { readLocalSyncMap } from "./read-local-sync-map.mjs";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const repoRoot = resolveRepoRoot(__dirname);
+const jsonMode = process.argv.includes("--json");
+const errors = [];
+const report = inspectGithubSync(repoRoot);
+
+if (jsonMode) {
+  console.log(JSON.stringify(report, null, 2));
+} else {
+  console.log(`GitHub sync inspection passed for ${report.projects.length} projects, ${report.summary.issue_refs} issue refs, and ${report.summary.pr_refs} PR refs.`);
+  for (const drift of report.drift) console.log(`- ${drift.severity}: ${drift.summary}`);
+}
+
+if (errors.length > 0) {
+  if (!jsonMode) {
+    console.error("GitHub sync inspection failed:");
+    for (const error of errors) console.error(`- ${error}`);
+  }
+  process.exit(1);
+}
+
+export function inspectGithubSync(root = repoRoot) {
+  const syncMap = readLocalSyncMap(root);
+  const fallbackRepo = normalizeGitHubRepo(readGitRemote(root));
+  const projects = [];
+  const drift = [];
+  let issueRefs = 0;
+  let prRefs = 0;
+
+  for (const project of syncMap.projects) {
+    const githubRepo = normalizeGitHubRepo(project.github_repo) || fallbackRepo || "";
+    const inspectedTasks = [];
+    for (const task of project.tasks) {
+      const issue = normalizeGitHubRef(task.github_issue, githubRepo, "issue");
+      const pr = normalizeGitHubRef(task.github_pr, githubRepo, "pull_request");
+      if (issue) issueRefs += 1;
+      if (pr) prRefs += 1;
+      if ((task.github_issue || task.github_pr) && !githubRepo) {
+        drift.push({
+          drift_type: "mapping-drift",
+          severity: "warning",
+          target: `${project.slug}/${task.local_id}`,
+          summary: "Task has GitHub references but no project github_repo or origin GitHub remote.",
+          proposed_action: "Add github_repo to the sync registry or project contract before remote inspection.",
+          apply_posture: "dry-run-plan-first"
+        });
+      }
+      inspectedTasks.push({
+        local_id: task.local_id,
+        status: task.status,
+        issue,
+        pull_request: pr
+      });
+    }
+    projects.push({ slug: project.slug, github_repo: githubRepo, tasks: inspectedTasks });
+  }
+
+  return {
+    schema_version: 1,
+    mode: "local-dry-run",
+    source: "local-task-metadata-and-git-remote",
+    summary: { issue_refs: issueRefs, pr_refs: prRefs, drift_count: drift.length },
+    projects,
+    drift
+  };
+}
+
+function normalizeGitHubRef(value, fallbackRepo, kind) {
+  const raw = String(value || "").trim();
+  if (!raw) return null;
+  const numberMatch = raw.match(/^#?([0-9]+)$/);
+  if (numberMatch) return { kind, repo: fallbackRepo || "", number: Number(numberMatch[1]), url: fallbackRepo ? `https://github.com/${fallbackRepo}/${kind === "pull_request" ? "pull" : "issues"}/${numberMatch[1]}` : "" };
+  const urlMatch = raw.match(/^https:\/\/github\.com\/([^/]+\/[^/]+)\/(issues|pull)\/([0-9]+)\/?$/);
+  if (urlMatch) return { kind: urlMatch[2] === "pull" ? "pull_request" : "issue", repo: normalizeGitHubRepo(urlMatch[1]), number: Number(urlMatch[3]), url: raw.replace(/\/$/, "") };
+  errors.push(`Invalid GitHub ${kind} reference: ${raw}`);
+  return null;
+}
+
+function normalizeGitHubRepo(value) {
+  const raw = String(value || "").trim();
+  if (!raw) return "";
+  const ssh = raw.match(/^git@github\.com:([^/]+\/[^/]+?)(?:\.git)?$/);
+  if (ssh) return ssh[1].replace(/\.git$/, "");
+  const https = raw.match(/^https:\/\/github\.com\/([^/]+\/[^/]+?)(?:\.git)?\/?$/);
+  if (https) return https[1].replace(/\.git$/, "");
+  if (/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(raw)) return raw.replace(/\.git$/, "");
+  return "";
+}
+
+function readGitRemote(root) {
+  const configPath = path.join(root, ".git", "config");
+  if (!existsSync(configPath)) return "";
+  const text = readFileSync(configPath, "utf8");
+  const match = text.match(/\[remote "origin"\][\s\S]*?url = (.+)/);
+  return match ? match[1].trim() : "";
+}
+
+function resolveRepoRoot(startDir) {
+  const candidates = [path.resolve(startDir, ".."), path.resolve(startDir, "..", "..")];
+  for (const candidate of candidates) if (existsSync(path.join(candidate, ".project")) && existsSync(path.join(candidate, ".agents"))) return candidate;
+  return path.resolve(startDir, "..");
+}

package/assets/payload/.agents/scripts/lease-manager.mjs

@@ -0,0 +1,88 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const repoRoot = resolveRepoRoot(__dirname);
+const command = process.argv[2] || "self-test";
+const statePath = readOption("--state") || path.join(repoRoot, ".agents", "leases", "active-leases.json");
+
+try {
+  const result = run(command, statePath);
+  if (process.argv.includes("--json")) console.log(JSON.stringify(result, null, 2));
+  else console.log(result.message);
+} catch (error) {
+  console.error(error.message);
+  process.exit(error.exitCode || 1);
+}
+
+export function run(command, statePath) {
+  if (command === "self-test") return selfTest();
+  if (command === "list" || command === "inspect") return { message: `Lease inspection found ${readState(statePath).leases.length} lease(s).`, leases: readState(statePath).leases };
+  if (command === "acquire") return acquire(statePath, readRequired("--owner"), readRequired("--project"), readRequired("--task"), readList("--zone"), readOption("--mode") || "shared", Number(readOption("--ttl-minutes") || 120));
+  if (command === "release") return release(statePath, readRequired("--lease-id"), readOption("--reason") || "released by owner", readOption("--handoff") || "");
+  throw Object.assign(new Error(`Unknown lease command: ${command}`), { exitCode: 1 });
+}
+
+function acquire(statePath, owner, project, taskId, zones, mode, ttlMinutes) {
+  if (!zones.length) throw Object.assign(new Error("At least one --zone is required."), { exitCode: 1 });
+  if (!["shared", "exclusive"].includes(mode)) throw Object.assign(new Error("--mode must be shared or exclusive."), { exitCode: 1 });
+  const state = readState(statePath);
+  const now = new Date();
+  const lease = {
+    schema_version: 1,
+    lease_id: `lease-${now.toISOString().replace(/[:.]/g, "-")}-${taskId.toLowerCase()}`,
+    owner,
+    project,
+    task_id: taskId,
+    status: "active",
+    mode,
+    paths: zones,
+    conflict_zones: zones,
+    created_at: now.toISOString(),
+    acquired_at: now.toISOString(),
+    expires_at: new Date(now.getTime() + ttlMinutes * 60_000).toISOString()
+  };
+  state.leases.push(lease);
+  writeState(statePath, state);
+  return { message: `Acquired ${lease.lease_id} for ${project}/${taskId}.`, lease };
+}
+
+function release(statePath, leaseId, reason, handoff) {
+  const state = readState(statePath);
+  const lease = state.leases.find((item) => item.lease_id === leaseId);
+  if (!lease) throw Object.assign(new Error(`Lease not found: ${leaseId}`), { exitCode: 1 });
+  if (!handoff.trim()) {
+    throw Object.assign(new Error("--handoff is required and must summarize changed work, evidence, blockers, lease state, and next safe action."), { exitCode: 1 });
+  }
+  lease.status = "released";
+  lease.released_at = new Date().toISOString();
+  lease.release_reason = reason;
+  lease.handoff_summary = handoff.trim();
+  writeState(statePath, state);
+  return { message: `Released ${leaseId} with handoff summary.`, lease };
+}
+
+function selfTest() {
+  const dir = path.join(os.tmpdir(), `delano-lease-${process.pid}`);
+  const state = path.join(dir, "leases.json");
+  mkdirSync(dir, { recursive: true });
+  const acquired = acquire(state, "self-test", "delano-multi-agent-execution", "T-002", ["scripts/lease-manager.mjs"], "exclusive", 5).lease;
+  const inspected = readState(state).leases.length;
+  release(state, acquired.lease_id, "self-test complete", "validated acquire inspect release lifecycle");
+  const released = readState(state).leases[0].status;
+  rmSync(dir, { recursive: true, force: true });
+  return { message: `Lease manager self-test passed (${inspected} acquired, ${released}).` };
+}
+
+function readState(filePath) {
+  if (!existsSync(filePath)) return { schema_version: 1, leases: [] };
+  return JSON.parse(readFileSync(filePath, "utf8"));
+}
+function writeState(filePath, state) { mkdirSync(path.dirname(filePath), { recursive: true }); writeFileSync(filePath, JSON.stringify(state, null, 2) + "\n"); }
+function readOption(name) { const i = process.argv.indexOf(name); return i === -1 ? "" : process.argv[i + 1]; }
+function readRequired(name) { const v = readOption(name); if (!v) throw Object.assign(new Error(`${name} is required.`), { exitCode: 1 }); return v; }
+function readList(name) { const out=[]; process.argv.forEach((arg,i)=>{ if(arg===name && process.argv[i+1]) out.push(process.argv[i+1]); }); return out; }
+function resolveRepoRoot(startDir) { for (const c of [path.resolve(startDir,".."),path.resolve(startDir,"..","..")]) if (existsSync(path.join(c,".agents"))) return c; return path.resolve(startDir,".."); }

package/assets/payload/.agents/scripts/log-event.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 const fs = require('fs');
 const path = require('path');
+const { redactObject } = require('../common/log-safety');
 
 const args = process.argv.slice(2);
 if (args.length < 2) {
@@ -24,6 +25,8 @@ for (let i = 0; i < rest.length; i++) {
   event.meta[key] = value;
 }
 
+event.meta = redactObject(event.meta);
+
 const root = process.cwd();
 const logDir = path.join(root, '.agents', 'logs');
 const logFile = path.join(logDir, 'changes.jsonl');

package/assets/payload/.agents/scripts/plan-sync-repairs.mjs

@@ -0,0 +1,66 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { buildDriftReport } from "./build-drift-report.mjs";
+import { readLocalSyncMap } from "./read-local-sync-map.mjs";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const repoRoot = resolveRepoRoot(__dirname);
+const args = new Set(process.argv.slice(2));
+const jsonMode = args.has("--json");
+const apply = args.has("--apply");
+const approve = readOption("--approve");
+
+const report = buildDriftReport(readLocalSyncMap(repoRoot), {}, {}, { localOnlyMode: true });
+const plan = buildRepairPlan(report, { apply, approve });
+
+if (jsonMode) console.log(JSON.stringify(plan, null, 2));
+else {
+  console.log(`Repair plan produced ${plan.summary.action_count} action(s).`);
+  console.log(`Apply gate: ${plan.apply_gate.status}.`);
+  for (const action of plan.actions) console.log(`- ${action.mode}: ${action.target} ${action.summary}`);
+}
+
+if (apply && plan.apply_gate.status !== "approved") {
+  if (!jsonMode) console.error(`Refusing apply: ${plan.apply_gate.reason}`);
+  process.exit(2);
+}
+
+export function buildRepairPlan(report, options = {}) {
+  const actions = (report.repair_recommendations || []).map((recommendation) => ({
+    id: recommendation.id,
+    mode: "dry-run-plan",
+    drift_type: recommendation.drift_type,
+    target: recommendation.target,
+    summary: recommendation.summary,
+    proposed_action: recommendation.proposed_action,
+    apply_posture: recommendation.apply_posture || "dry-run-plan-first",
+    evidence: recommendation.evidence || {}
+  }));
+  const token = `APPLY-${report.schema_version}-${report.summary.drift_count}-${report.summary.repair_count}`;
+  const approved = options.apply && options.approve === token;
+  return {
+    schema_version: 1,
+    mode: options.apply ? "apply-request" : "dry-run-plan",
+    source_report: { schema_version: report.schema_version, generated_at: report.generated_at, drift_count: report.summary.drift_count },
+    apply_gate: {
+      status: approved ? "approved" : "blocked",
+      required_token: token,
+      provided_token: options.approve || "",
+      reason: approved ? "Explicit operator token matched; caller may perform a separate apply step." : "Explicit operator approval token is required before any local or remote mutation."
+    },
+    summary: { action_count: actions.length, dry_run: !approved, mutation_count: 0 },
+    actions
+  };
+}
+
+function readOption(name) {
+  const index = process.argv.indexOf(name);
+  return index === -1 ? "" : process.argv[index + 1];
+}
+function resolveRepoRoot(startDir) {
+  const candidates = [path.resolve(startDir, ".."), path.resolve(startDir, "..", "..")];
+  for (const candidate of candidates) if (existsSync(path.join(candidate, ".project")) && existsSync(path.join(candidate, ".agents"))) return candidate;
+  return path.resolve(startDir, "..");
+}