avorelo 0.1.0

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

@@ -0,0 +1,887 @@
+"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,
+};