avorelo 0.1.0 → 0.3.0

package/scripts/lib/safe-run-controller.js

@@ -1,887 +0,0 @@
-"use strict";
-
-// ── Safe Run Controller ───────────────────────────────────────────────────────
-//
-// Contract: avorelo.safeRun.v1
-//
-// Orchestrates the full safe-run control pipeline:
-//   project-profile → smart-route → execution-packet → worker-handoff
-//   → safe local proof steps (whitelisted only) → receipt → ledger/proof/outcome
-//
-// Does NOT:
-//   - modify user code
-//   - execute remote agents
-//   - call external APIs
-//   - implement ACP/A2A
-//   - run deploy/publish/prod/release commands
-//   - run destructive commands
-//   - read secrets
-//   - include raw prompts/code/secrets/PII in receipts
-
-const fs = require("node:fs");
-const path = require("node:path");
-const crypto = require("node:crypto");
-const { spawnSync } = require("node:child_process");
-
-const CONTRACT = "avorelo.safeRun.v1";
-const SCHEMA_VERSION = 1;
-
-const SAFE_RUN_DIR_REL = ".claude/cco/orchestration/safe-run";
-const LATEST_RUN_REL = `${SAFE_RUN_DIR_REL}/latest-run.json`;
-
-// ── Allowed local step types ──────────────────────────────────────────────────
-
-const ALLOWED_STEP_TYPES = Object.freeze([
-  "project_profile",
-  "smart_route",
-  "execution_packet",
-  "worker_handoff",
-  "ledger_update",
-  "proof_summary",
-  "outcome_summary",
-  "test_command",
-  "build_command",
-  "lint_command",
-]);
-
-// ── Blocked command patterns ──────────────────────────────────────────────────
-
-const BLOCKED_COMMAND_PATTERNS = Object.freeze([
-  /deploy/i,
-  /publish/i,
-  /release/i,
-  /production/i,
-  /prod/i,
-  /rm\s+-rf/i,
-  /git\s+clean/i,
-  /git\s+reset\s+--hard/i,
-  /drop\s+table/i,
-  /truncate/i,
-  /secret/i,
-  /auth/i,
-  /credential/i,
-  /\.env/i,
-  /wipe/i,
-  /destroy/i,
-]);
-
-// Whitelisted npm script prefixes that are safe to run
-const SAFE_SCRIPT_PREFIXES = Object.freeze([
-  "test",
-  "build",
-  "lint",
-  "type-check",
-  "typecheck",
-  "check",
-  "verify",
-  "validate",
-]);
-
-// Maximum allowed command execution timeout (30s)
-const MAX_COMMAND_TIMEOUT_MS = 30_000;
-
-// Max stdout/stderr captured per command
-const MAX_OUTPUT_CHARS = 2_000;
-
-// ── Helpers ───────────────────────────────────────────────────────────────────
-
-function createRunId() {
-  return `saferun-${crypto.randomBytes(6).toString("hex")}`;
-}
-
-function nowIso() {
-  return new Date().toISOString();
-}
-
-function safeReadJson(absPath) {
-  try {
-    if (!fs.existsSync(absPath)) return null;
-    return JSON.parse(fs.readFileSync(absPath, "utf8").replace(/^/, ""));
-  } catch {
-    return null;
-  }
-}
-
-function ensureDir(p) {
-  fs.mkdirSync(p, { recursive: true });
-}
-
-function safeWriteJson(absPath, obj) {
-  ensureDir(path.dirname(absPath));
-  fs.writeFileSync(absPath, JSON.stringify(obj, null, 2), "utf8");
-}
-
-function summarizeOutput(raw) {
-  if (!raw) return "";
-  const text = String(raw).slice(0, MAX_OUTPUT_CHARS);
-  const lines = text.split("\n").filter((l) => l.trim());
-  if (lines.length === 0) return "";
-  if (lines.length <= 5) return lines.join("\n");
-  // Show first 3 and last 2 lines
-  return [
-    ...lines.slice(0, 3),
-    `... (${lines.length - 5} more lines) ...`,
-    ...lines.slice(-2),
-  ].join("\n");
-}
-
-// ── Command safety check ──────────────────────────────────────────────────────
-
-function isCommandSafe(command) {
-  if (!command || typeof command !== "string") return false;
-  const lower = command.toLowerCase().trim();
-  // Must not match any blocked pattern
-  for (const pattern of BLOCKED_COMMAND_PATTERNS) {
-    if (pattern.test(lower)) return false;
-  }
-  return true;
-}
-
-function isScriptNameSafe(scriptName) {
-  if (!scriptName || typeof scriptName !== "string") return false;
-  const lower = scriptName.toLowerCase().trim();
-  for (const pattern of BLOCKED_COMMAND_PATTERNS) {
-    if (pattern.test(lower)) return false;
-  }
-  return SAFE_SCRIPT_PREFIXES.some((prefix) => lower === prefix || lower.startsWith(prefix + ":") || lower.startsWith(prefix + "-") || lower.startsWith(prefix + "_"));
-}
-
-// ── Project profile discovery ─────────────────────────────────────────────────
-
-function getProjectProfile(cwd) {
-  try {
-    const { detectProjectProfile } = require("./project-profile");
-    return detectProjectProfile(cwd);
-  } catch {
-    return null;
-  }
-}
-
-// ── Discover safe local proof commands from project profile ───────────────────
-
-function discoverSafeLocalCommands(cwd, profile) {
-  const commands = [];
-
-  // Read package.json scripts to determine what's available
-  let scripts = {};
-  try {
-    const pkgPath = path.join(cwd, "package.json");
-    const pkg = safeReadJson(pkgPath);
-    scripts = (pkg && pkg.scripts) || {};
-  } catch {}
-
-  const profileCommands = (profile && profile.commands) || {};
-
-  // test
-  if (profileCommands.test && isCommandSafe(profileCommands.test)) {
-    const scriptName = profileCommands.test.replace(/^npm\s+(run\s+)?/, "").trim();
-    if (scriptName === "test" || scripts[scriptName]) {
-      commands.push({
-        type: "test_command",
-        label: "Run tests",
-        command: "npm",
-        args: profileCommands.test.includes("run") ? ["run", scriptName] : ["test"],
-        scriptName: scriptName === "test" ? "test" : `run:${scriptName}`,
-      });
-    }
-  }
-
-  // build
-  if (profileCommands.build && isCommandSafe(profileCommands.build)) {
-    const scriptName = profileCommands.build.replace(/^npm\s+(run\s+)?/, "").trim();
-    if (scripts[scriptName] || scriptName === "build") {
-      commands.push({
-        type: "build_command",
-        label: "Run build",
-        command: "npm",
-        args: ["run", scriptName],
-        scriptName: `run:${scriptName}`,
-      });
-    }
-  }
-
-  // lint (only if present)
-  if (profileCommands.lint && isCommandSafe(profileCommands.lint)) {
-    const scriptName = profileCommands.lint.replace(/^npm\s+(run\s+)?/, "").trim();
-    if (scripts[scriptName]) {
-      commands.push({
-        type: "lint_command",
-        label: "Run lint",
-        command: "npm",
-        args: ["run", scriptName],
-        scriptName: `run:${scriptName}`,
-      });
-    }
-  }
-
-  return commands;
-}
-
-// ── Run a single whitelisted local step ───────────────────────────────────────
-
-function runAllowedLocalStep(cwd, step, options = {}) {
-  const timeout = Math.min(options.timeout || MAX_COMMAND_TIMEOUT_MS, MAX_COMMAND_TIMEOUT_MS);
-  const startedAt = nowIso();
-  const startMs = Date.now();
-
-  if (!step || !ALLOWED_STEP_TYPES.includes(step.type)) {
-    return {
-      stepType: step?.type || "unknown",
-      status: "blocked",
-      reason: "Step type not in allowed list.",
-      exitCode: null,
-      duration: 0,
-      outputSummary: "",
-      redacted: true,
-    };
-  }
-
-  // Only command steps require actual execution
-  if (!["test_command", "build_command", "lint_command"].includes(step.type)) {
-    return {
-      stepType: step.type,
-      status: "non_executable",
-      reason: "Non-command step — orchestration only.",
-      exitCode: null,
-      duration: 0,
-      outputSummary: "",
-      redacted: true,
-    };
-  }
-
-  // Safety gate on the command
-  const fullCommand = [step.command, ...(step.args || [])].join(" ");
-  if (!isCommandSafe(fullCommand)) {
-    return {
-      stepType: step.type,
-      status: "blocked",
-      reason: "Command failed safety check — blocked pattern detected.",
-      command: "[redacted]",
-      exitCode: null,
-      duration: 0,
-      outputSummary: "",
-      redacted: true,
-    };
-  }
-
-  // Additional script name check
-  const scriptArg = (step.args || []).find((a) => a !== "run" && a !== "test");
-  if (scriptArg && step.args[0] === "run" && !isScriptNameSafe(scriptArg)) {
-    return {
-      stepType: step.type,
-      status: "blocked",
-      reason: `Script name '${scriptArg}' is not in safe script whitelist.`,
-      exitCode: null,
-      duration: 0,
-      outputSummary: "",
-      redacted: true,
-    };
-  }
-
-  try {
-    const result = spawnSync(step.command, step.args || [], {
-      cwd,
-      timeout,
-      encoding: "utf8",
-      env: { ...process.env, CI: "true", FORCE_COLOR: "0" },
-      maxBuffer: 1024 * 512, // 512 KB
-    });
-
-    const duration = Date.now() - startMs;
-    const stdout = summarizeOutput(result.stdout || "");
-    const stderr = summarizeOutput(result.stderr || "");
-    const exitCode = result.status ?? (result.error ? 1 : 0);
-    const timedOut = result.signal === "SIGTERM" || (result.error && result.error.code === "ETIMEDOUT");
-
-    return {
-      stepType: step.type,
-      label: step.label,
-      status: timedOut ? "timeout" : exitCode === 0 ? "pass" : "fail",
-      exitCode,
-      duration,
-      timedOut,
-      outputSummary: [stdout, stderr].filter(Boolean).join("\n---\n").slice(0, MAX_OUTPUT_CHARS),
-      redacted: true,
-    };
-  } catch (err) {
-    return {
-      stepType: step.type,
-      status: "error",
-      reason: err.message,
-      exitCode: null,
-      duration: Date.now() - startMs,
-      outputSummary: "",
-      redacted: true,
-    };
-  }
-}
-
-// ── Determine overall run decision ────────────────────────────────────────────
-
-function resolveRunDecision(routeDecision, taskRiskLevel, options = {}) {
-  if (options.prepareOnly) return "prepared";
-  if (["blocked"].includes(routeDecision)) return "blocked";
-  if (["approval_required"].includes(routeDecision)) return "approval_required";
-  if (["auto_execute", "auto_prepare"].includes(routeDecision)) {
-    return taskRiskLevel === "low" ? "verified" : "prepared";
-  }
-  return "prepared";
-}
-
-function resolveRunMode(routeDecision, riskLevel) {
-  if (["blocked", "approval_required"].includes(routeDecision)) return "manual_debug";
-  if (riskLevel === "low") return "automatic";
-  return "assisted";
-}
-
-// ── Build safe run plan ───────────────────────────────────────────────────────
-
-function buildSafeRunPlan(cwd, taskText, options = {}) {
-  const runId = createRunId();
-  const createdAt = nowIso();
-
-  // Step 1: project profile
-  const profile = getProjectProfile(cwd);
-  const profileRef = path.join(".claude/cco/orchestration/project-profile", "latest-profile.json");
-
-  // Step 2: smart route (reuse existing module, do not duplicate)
-  let route = null;
-  let routeDecision = "auto_prepare";
-  let routeReasonCodes = [];
-  let smartRouteRef = null;
-  try {
-    const { buildSmartWorkRoute, writeSmartWorkRouteReceipt, LATEST_ROUTE_REL } = require("./smart-work-routing");
-    route = buildSmartWorkRoute(cwd, taskText, { taskText });
-    if (!options.dryRun) {
-      writeSmartWorkRouteReceipt(cwd, route);
-    }
-    routeDecision = route.decision || "auto_prepare";
-    routeReasonCodes = (route.executionPath && route.executionPath.reasonCodes) || [];
-    smartRouteRef = LATEST_ROUTE_REL;
-  } catch (err) {
-    routeDecision = "auto_prepare";
-  }
-
-  // Step 3: execution packet (reuse existing module)
-  let packet = null;
-  let packetRef = null;
-  try {
-    const { compileExecutionPacket, writeExecutionPacket, LATEST_PACKET_REL } = require("./execution-packet");
-    packet = compileExecutionPacket(cwd, { userIntent: taskText });
-    if (!options.dryRun) {
-      writeExecutionPacket(cwd, packet);
-    }
-    packetRef = LATEST_PACKET_REL;
-  } catch {}
-
-  // Step 4: worker handoff (reuse existing module)
-  let handoff = null;
-  let handoffRef = null;
-  try {
-    const { buildWorkerHandoff, writeWorkerHandoffReceipt, LATEST_HANDOFF_REL } = require("./smart-work-routing");
-    if (route) {
-      handoff = buildWorkerHandoff(cwd, route, {});
-      if (!options.dryRun) {
-        writeWorkerHandoffReceipt(cwd, handoff);
-      }
-      handoffRef = LATEST_HANDOFF_REL;
-    }
-  } catch {}
-
-  // Step 5: classify task for safe step planning
-  const task = (route && route.task) || { summary: taskText, riskLevel: "medium", taskType: "unknown" };
-  const riskLevel = task.riskLevel || "medium";
-  const taskType = task.taskType || "unknown";
-
-  // Step 6: determine allowed local steps
-  const allowedLocalSteps = [];
-  const blockedSteps = [];
-
-  // Always allow orchestration steps
-  allowedLocalSteps.push(
-    { type: "project_profile", label: "Detect project profile", status: "done", ref: profileRef },
-    { type: "smart_route", label: "Build smart route", status: "done", ref: smartRouteRef },
-    { type: "execution_packet", label: "Compile execution packet", status: "done", ref: packetRef },
-    { type: "worker_handoff", label: "Prepare worker handoff", status: "done", ref: handoffRef }
-  );
-
-  // Proof/local command steps only when safe
-  const localCommandsAllowed =
-    !options.prepareOnly &&
-    !["high", "critical"].includes(riskLevel) &&
-    !["blocked", "approval_required"].includes(routeDecision);
-
-  const discoveredCommands = (profile && localCommandsAllowed)
-    ? discoverSafeLocalCommands(cwd, profile)
-    : [];
-
-  for (const cmd of discoveredCommands) {
-    allowedLocalSteps.push({ ...cmd, status: "pending" });
-  }
-
-  if (!localCommandsAllowed && !options.prepareOnly) {
-    blockedSteps.push({
-      reason: routeDecision === "blocked"
-        ? "Task is blocked — no local execution performed."
-        : routeDecision === "approval_required"
-        ? "Task requires approval — no local execution performed."
-        : `Task risk level '${riskLevel}' prevents automatic local proof execution.`,
-    });
-  }
-
-  // Ledger/proof/outcome steps
-  allowedLocalSteps.push(
-    { type: "ledger_update", label: "Update work ledger", status: "pending" },
-    { type: "proof_summary", label: "Write proof summary", status: "pending" },
-    { type: "outcome_summary", label: "Update outcome summary", status: "pending" }
-  );
-
-  // Step 7: proof plan
-  const proofRequired = (route && route.executionPath && route.executionPath.proofRequired) === true;
-  const proofPlan = {
-    proofRequired,
-    steps: proofRequired
-      ? ["run tests", "run build", "write proof artifact"]
-      : ["route receipt written", "packet receipt written", "handoff receipt written"],
-    approvalRequiredFirst: ["blocked", "approval_required"].includes(routeDecision),
-  };
-
-  // Step 8: safe next action
-  const safeNextAction = buildSafeNextAction(routeDecision, riskLevel, taskType, route);
-
-  // Step 9: run decision and mode
-  const decision = resolveRunDecision(routeDecision, riskLevel, options);
-  const mode = resolveRunMode(routeDecision, riskLevel);
-
-  // Step 10: value evidence
-  const valueEvidence = {
-    stepsOrchestrated: allowedLocalSteps.length,
-    localCommandsAllowed: discoveredCommands.length,
-    secretsExcluded: true,
-    deployBlocked: routeDecision === "blocked" || routeDecision === "approval_required",
-    caveats: [
-      "Savings estimates are approximations from receipt data, not exact billing amounts.",
-      "No guaranteed savings claimed.",
-    ],
-    redacted: true,
-  };
-
-  return {
-    contract: CONTRACT,
-    schemaVersion: SCHEMA_VERSION,
-    runId,
-    createdAt,
-    task: {
-      summary: task.summary || taskText,
-      riskLevel,
-      taskType,
-    },
-    mode,
-    decision,
-    smartRouteRef,
-    executionPacketRef: packetRef,
-    workerHandoffRef: handoffRef,
-    allowedLocalSteps,
-    blockedSteps,
-    proofPlan,
-    executionSummary: null, // filled after execution
-    safety: {
-      secretsExcluded: true,
-      broadContextExcluded: true,
-      deployBlocked: true,
-      destructiveBlocked: true,
-      remoteAgentExecutionBlocked: true,
-      codeModificationBlocked: true,
-      localCommandsWhitelisted: true,
-    },
-    receipts: {
-      smartRoute: smartRouteRef,
-      executionPacket: packetRef,
-      workerHandoff: handoffRef,
-      safeRun: LATEST_RUN_REL,
-    },
-    valueEvidence,
-    safeNextAction,
-    redacted: true,
-  };
-}
-
-function buildSafeNextAction(routeDecision, riskLevel, taskType, route) {
-  if (routeDecision === "blocked") {
-    return "Task blocked. Review the reason codes, narrow the scope, and re-run with a safer task description.";
-  }
-  if (routeDecision === "approval_required") {
-    const base = (route && route.executionPath && route.executionPath.safeNextAction) || "";
-    if (taskType === "deployment_release") {
-      return "Run tests and build verification first: avorelo run \"run tests and build\", then request deployment approval.";
-    }
-    if (taskType === "security_sensitive") {
-      return "Review security scope with avorelo guard before making auth changes.";
-    }
-    return base || "Approval required. Review scope and constraints, then proceed with worker handoff.";
-  }
-  if (riskLevel === "high") {
-    return "Worker handoff prepared. Review scope before executing with target worker.";
-  }
-  if (["documentation", "summarization"].includes(taskType)) {
-    return "Route, packet, and handoff prepared. Safe to execute with local or cheap worker.";
-  }
-  return "Route, packet, and handoff prepared. Run local proof steps, then execute with worker.";
-}
-
-// ── Execute safe run plan ─────────────────────────────────────────────────────
-
-function executeSafeRunPlan(cwd, runPlan, options = {}) {
-  if (!runPlan || runPlan.contract !== CONTRACT) {
-    throw new Error("Invalid run plan: missing or mismatched contract.");
-  }
-
-  const execResults = [];
-  let localStepsRun = 0;
-  let localStepsPassed = 0;
-  let localStepsFailed = 0;
-  let localStepsBlocked = 0;
-
-  const pendingCommandSteps = (runPlan.allowedLocalSteps || []).filter(
-    (s) => ["test_command", "build_command", "lint_command"].includes(s.type) && s.status === "pending"
-  );
-
-  for (const step of pendingCommandSteps) {
-    const result = runAllowedLocalStep(cwd, step, { timeout: MAX_COMMAND_TIMEOUT_MS });
-    execResults.push(result);
-    localStepsRun++;
-
-    if (result.status === "pass") localStepsPassed++;
-    else if (result.status === "blocked") localStepsBlocked++;
-    else localStepsFailed++;
-
-    // Emit product learning event (best-effort)
-    try {
-      const { appendProductLearningEvent } = require("./product-learning-events");
-      appendProductLearningEvent(cwd, {
-        eventName: result.status === "pass" ? "safe_run_local_step_completed" : "safe_run_local_step_blocked",
-        category: "safe_run",
-        surface: "local",
-        status: "observed",
-        payload: {
-          stepType: result.stepType,
-          status: result.status,
-          exitCode: result.exitCode,
-          durationMs: result.duration,
-        },
-      });
-    } catch {}
-  }
-
-  // Ledger update (best-effort)
-  try {
-    writeSafeRunLedgerEntry(cwd, runPlan, execResults);
-  } catch {}
-
-  const allPassed = localStepsFailed === 0 && localStepsBlocked === 0;
-  const finalDecision =
-    runPlan.decision === "blocked" ? "blocked"
-    : runPlan.decision === "approval_required" ? "approval_required"
-    : localStepsRun > 0 && allPassed ? "verified"
-    : localStepsRun > 0 && localStepsFailed > 0 ? "partial"
-    : "prepared";
-
-  const executionSummary = {
-    localStepsRun,
-    localStepsPassed,
-    localStepsFailed,
-    localStepsBlocked,
-    results: execResults,
-    finalDecision,
-    completedAt: nowIso(),
-    redacted: true,
-  };
-
-  return { ...runPlan, executionSummary, decision: finalDecision };
-}
-
-// ── Write safe run receipt ────────────────────────────────────────────────────
-
-function writeSafeRunReceipt(cwd, receipt) {
-  const absPath = path.join(cwd, LATEST_RUN_REL);
-  // Ensure no raw prompt/code/secrets in receipt
-  const safe = {
-    ...receipt,
-    task: receipt.task
-      ? { summary: receipt.task.summary, riskLevel: receipt.task.riskLevel, taskType: receipt.task.taskType }
-      : null,
-    redacted: true,
-  };
-  safeWriteJson(absPath, safe);
-  return absPath;
-}
-
-// ── Ledger entry writer ───────────────────────────────────────────────────────
-
-function writeSafeRunLedgerEntry(cwd, runPlan, execResults) {
-  try {
-    const { normalizeLedgerEntry } = require("./work-ledger");
-    const decision = runPlan.decision || "prepared";
-    const localRan = (execResults || []).filter((r) => r.status === "pass").length;
-    const localFailed = (execResults || []).filter((r) => r.status === "fail").length;
-
-    const valueSignals = [];
-    if (localRan > 0) valueSignals.push(`${localRan} local proof step(s) passed`);
-    if (runPlan.safety && runPlan.safety.deployBlocked) valueSignals.push("deploy_blocked");
-    if (runPlan.safety && runPlan.safety.secretsExcluded) valueSignals.push("secrets_excluded");
-
-    const frictionSignals = [];
-    if (decision === "approval_required") frictionSignals.push("approval_required");
-    if (decision === "blocked") frictionSignals.push("task_blocked");
-    if (localFailed > 0) frictionSignals.push(`${localFailed}_local_step(s)_failed`);
-
-    return normalizeLedgerEntry("safe_run", "safe_run_controller", runPlan, {
-      // blocked/approval_required = safety working correctly (warn), not a broken system
-      status: decision === "verified" ? "pass" : "warn",
-      summary: `Safe run: decision=${decision}, localStepsRun=${(execResults || []).length}.`,
-      evidencePath: LATEST_RUN_REL,
-      evidenceKind: "receipt",
-      valueSignals,
-      frictionSignals,
-      reasonCodes: [],
-    });
-  } catch {
-    return null;
-  }
-}
-
-// ── Build safe run surface ────────────────────────────────────────────────────
-
-function buildSafeRunSurface(cwd, options = {}) {
-  const absPath = path.join(cwd, LATEST_RUN_REL);
-  const receipt = safeReadJson(absPath);
-
-  if (!receipt) {
-    return {
-      status: "not_run",
-      latestRunPath: LATEST_RUN_REL,
-      decision: null,
-      nextAction: "Run `avorelo run \"<task>\"` to execute the safe run pipeline.",
-    };
-  }
-
-  return {
-    status: "present",
-    latestRunPath: LATEST_RUN_REL,
-    decision: receipt.decision,
-    mode: receipt.mode,
-    runId: receipt.runId,
-    task: receipt.task
-      ? { taskType: receipt.task.taskType, riskLevel: receipt.task.riskLevel }
-      : null,
-    localStepsRun: receipt.executionSummary?.localStepsRun ?? 0,
-    nextAction: receipt.safeNextAction,
-  };
-}
-
-// ── Format safe run text ──────────────────────────────────────────────────────
-
-function formatSafeRunText(receipt, options = {}) {
-  const debug = options.debug === true;
-  const decision = receipt.decision || "prepared";
-  const execSummary = receipt.executionSummary;
-
-  const lines = [];
-
-  if (decision === "blocked") {
-    lines.push("Blocked:");
-    const blockedSteps = receipt.blockedSteps || [];
-    for (const b of blockedSteps) {
-      lines.push(`  - ${b.reason}`);
-    }
-    lines.push("Safe next action:");
-    lines.push(`  - ${receipt.safeNextAction}`);
-    lines.push("No execution performed.");
-    return lines.join("\n");
-  }
-
-  if (decision === "approval_required") {
-    lines.push("ACTION REQUIRED");
-    const route = null; // route reason comes from reasonCodes in receipt
-    lines.push(`Reason: Task requires explicit approval before execution.`);
-    lines.push(`Safe next action: ${receipt.safeNextAction}`);
-    lines.push("Prepared:");
-    lines.push("  - smart route");
-    lines.push("  - execution packet");
-    lines.push("  - worker handoff");
-    lines.push("Proof needed:");
-    for (const step of (receipt.proofPlan && receipt.proofPlan.steps) || []) {
-      lines.push(`  - ${step}`);
-    }
-    return lines.join("\n");
-  }
-
-  // Normal (prepared / verified / partial)
-  lines.push("Avorelo prepared the safe run.");
-  lines.push("");
-  lines.push("Done:");
-  lines.push("  - Routed task safely.");
-  lines.push("  - Compiled execution packet.");
-  lines.push("  - Prepared worker handoff.");
-
-  if (execSummary && execSummary.localStepsRun > 0) {
-    const passed = execSummary.localStepsPassed;
-    const total = execSummary.localStepsRun;
-    lines.push(`  - Ran allowed local proof steps: ${passed}/${total} passed.`);
-  } else {
-    lines.push("  - Proof prepared (local steps deferred or not applicable).");
-  }
-
-  lines.push("");
-  lines.push("Protected:");
-  lines.push("  - Secrets/deploy/destructive actions blocked.");
-  lines.push("  - Broad context excluded.");
-  lines.push("");
-  lines.push(`Next:`);
-  lines.push(`  - ${receipt.safeNextAction}`);
-
-  if (debug) {
-    lines.push("");
-    lines.push("--- Debug ---");
-    lines.push(`Run ID: ${receipt.runId}`);
-    lines.push(`Mode: ${receipt.mode}`);
-    lines.push(`Decision: ${decision}`);
-    lines.push(`Task type: ${receipt.task && receipt.task.taskType}`);
-    lines.push(`Risk level: ${receipt.task && receipt.task.riskLevel}`);
-    lines.push(`Smart route ref: ${receipt.smartRouteRef || "none"}`);
-    lines.push(`Execution packet ref: ${receipt.executionPacketRef || "none"}`);
-    lines.push(`Worker handoff ref: ${receipt.workerHandoffRef || "none"}`);
-    lines.push(`Safe run receipt: ${LATEST_RUN_REL}`);
-
-    const allowedSteps = receipt.allowedLocalSteps || [];
-    lines.push(`Allowed local steps: ${allowedSteps.length}`);
-    for (const s of allowedSteps) {
-      lines.push(`  [${s.status || "?"}] ${s.type}: ${s.label || ""}`);
-    }
-
-    const blockedSteps = receipt.blockedSteps || [];
-    if (blockedSteps.length > 0) {
-      lines.push(`Blocked steps: ${blockedSteps.length}`);
-      for (const b of blockedSteps) {
-        lines.push(`  - ${b.reason}`);
-      }
-    }
-
-    if (execSummary && Array.isArray(execSummary.results)) {
-      lines.push("Local command results:");
-      for (const r of execSummary.results) {
-        lines.push(`  [${r.status}] ${r.stepType} (exit ${r.exitCode}, ${r.duration}ms)`);
-        if (r.outputSummary) {
-          lines.push(`    ${r.outputSummary.replace(/\n/g, "\n    ")}`);
-        }
-      }
-    }
-  }
-
-  return lines.join("\n");
-}
-
-// ── Main run orchestrator ─────────────────────────────────────────────────────
-
-function runSafeControlPipeline(cwd, taskText, options = {}) {
-  // Build plan
-  const plan = buildSafeRunPlan(cwd, taskText, options);
-
-  // Execute (unless prepare-only or dry-run)
-  let finalReceipt = plan;
-  if (!options.prepareOnly && !options.dryRun && !["blocked", "approval_required"].includes(plan.decision)) {
-    finalReceipt = executeSafeRunPlan(cwd, plan, options);
-  }
-
-  // Emit events (best-effort)
-  try {
-    const { appendProductLearningEvent } = require("./product-learning-events");
-    appendProductLearningEvent(cwd, {
-      eventName: "safe_run_started",
-      category: "safe_run",
-      surface: "local",
-      status: "observed",
-      payload: { runId: plan.runId, taskType: plan.task.taskType, riskLevel: plan.task.riskLevel },
-    });
-    appendProductLearningEvent(cwd, {
-      eventName: "safe_run_plan_built",
-      category: "safe_run",
-      surface: "local",
-      status: "observed",
-      payload: {
-        decision: plan.decision,
-        allowedLocalSteps: plan.allowedLocalSteps.length,
-        blockedSteps: plan.blockedSteps.length,
-      },
-    });
-    if (finalReceipt.decision === "approval_required") {
-      appendProductLearningEvent(cwd, {
-        eventName: "safe_run_approval_required",
-        category: "safe_run",
-        surface: "local",
-        status: "observed",
-        payload: { runId: plan.runId, taskType: plan.task.taskType },
-      });
-    } else if (finalReceipt.decision === "blocked") {
-      appendProductLearningEvent(cwd, {
-        eventName: "safe_run_blocked",
-        category: "safe_run",
-        surface: "local",
-        status: "observed",
-        payload: { runId: plan.runId, taskType: plan.task.taskType },
-      });
-    } else {
-      appendProductLearningEvent(cwd, {
-        eventName: "safe_run_completed",
-        category: "safe_run",
-        surface: "local",
-        status: "observed",
-        payload: {
-          runId: plan.runId,
-          decision: finalReceipt.decision,
-          localStepsRun: finalReceipt.executionSummary?.localStepsRun ?? 0,
-        },
-      });
-    }
-  } catch {}
-
-  // Write receipt (best-effort)
-  try {
-    if (!options.dryRun) {
-      writeSafeRunReceipt(cwd, finalReceipt);
-      appendProductLearningEventSafe(cwd, {
-        eventName: "safe_run_receipt_written",
-        category: "safe_run",
-        surface: "local",
-        status: "observed",
-        payload: { runId: plan.runId, receiptPath: LATEST_RUN_REL },
-      });
-    }
-  } catch {}
-
-  return finalReceipt;
-}
-
-function appendProductLearningEventSafe(cwd, event) {
-  try {
-    const { appendProductLearningEvent } = require("./product-learning-events");
-    appendProductLearningEvent(cwd, event);
-  } catch {}
-}
-
-module.exports = {
-  CONTRACT,
-  SCHEMA_VERSION,
-  LATEST_RUN_REL,
-  ALLOWED_STEP_TYPES,
-  buildSafeRunPlan,
-  executeSafeRunPlan,
-  runAllowedLocalStep,
-  writeSafeRunReceipt,
-  writeSafeRunLedgerEntry,
-  buildSafeRunSurface,
-  formatSafeRunText,
-  runSafeControlPipeline,
-  isCommandSafe,
-  discoverSafeLocalCommands,
-};