avorelo 0.4.0-rc.2 → 0.4.0-rc.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "avorelo",
-  "version": "0.4.0-rc.2",
+  "version": "0.4.0-rc.5",
   "private": false,
   "avoreloDistributionState": "ready_to_publish",
   "description": "Avorelo local-first activation, safety, and optimization runtime.",

package/scripts/lib/activation/activation-self-healing.js

@@ -33,6 +33,8 @@ const READINESS_CHECKS = Object.freeze([
   { id: "brain_pack",                  label: "Brain pack",                   required: true },
   { id: "session_context",             label: "Session context ready",        required: true },
   { id: "operating_value",             label: "Value tracking baseline",      required: true },
+  { id: "handler_sanity",              label: "Handler sanity (structural)",  required: true },
+  { id: "runtime_sanity",              label: "Live runtime verified",        required: false },
   { id: "dashboard_preview",           label: "Dashboard ready",              required: false },
   { id: "proof_summary",               label: "Proof summary",                required: false },
   { id: "security_baseline",           label: "Security checks ready",        required: false },
@@ -232,6 +234,28 @@ function checkReadiness(cwd, context) {
   // security_baseline (non-blocking — intake may not have run yet)
   checks.security_baseline = safeExists(cwd, ".claude/cco/security");
 
+  // handler_sanity (RC5) — STRUCTURAL behavioral check, required. Runs a benign and a
+  // mutating turn through the real handlers and requires the benign turn is NOT
+  // self-blocked. This is NOT live-host proof — it cannot show Claude Code loaded the
+  // hooks. It only guarantees Avorelo's own handlers won't self-trap a conversation.
+  try {
+    const { buildHandlerSanityProof } = require("../lifecycle-hooks");
+    const proof = buildHandlerSanityProof({});
+    checks.handler_sanity = proof.status === "pass";
+  } catch {
+    checks.handler_sanity = false;
+  }
+
+  // runtime_sanity (RC5) — LIVE-HOST state, NON-blocking. Passed only after a real
+  // CLAUDE_CODE_LIVE benign turn; pending at activation time (the customer has not taken
+  // a turn yet). Surfaced honestly; never satisfied by simulation/handler/test.
+  try {
+    const { readRuntimeSanity } = require("../lifecycle-hooks");
+    checks.runtime_sanity = readRuntimeSanity(cwd).state === "passed";
+  } catch {
+    checks.runtime_sanity = false;
+  }
+
   // model_routing (from context, non-blocking)
   checks.model_routing = Boolean(context && context.detectedModelRouting && context.detectedModelRouting.status);
 

package/scripts/lib/activation/activation-state.js

@@ -35,7 +35,7 @@ function defaultActivationState(cwd) {
     manualFixesRequired: [],
     nextAction: {
       label: "Check setup",
-      command: "npx avorelo@latest activate",
+      command: require("../runtime-provenance").versionAwareActivateCommand("activate"),
       reason: "Activation has not run yet.",
       blocking: false,
     },

package/scripts/lib/activation/repair-engine.js

@@ -39,7 +39,7 @@ function buildContextPack(cwd, context) {
     commands: {
       status: "avorelo status --text",
       audit: "avorelo audit",
-      activate: "npx avorelo@latest activate",
+      activate: require("../runtime-provenance").versionAwareActivateCommand("activate"),
     },
     hosts: (context.detectedHosts || [])
       .filter((host) => host.detected)
@@ -145,7 +145,7 @@ function runRepairEngine(cwd, context, options = {}) {
     manualFixesRequired.push({
       id: "run_activation_with_repair",
       label: "Run activation with repair enabled",
-      command: "npx avorelo@latest activate --repair",
+      command: require("../runtime-provenance").versionAwareActivateCommand("activate --repair"),
       reason: "Avorelo can recreate missing local state automatically when repair is enabled.",
       blocking: false,
     });

package/scripts/lib/activation/run-entry.js

@@ -302,7 +302,7 @@ function verifyRunEntry(cwd, options = {}) {
     checks,
     missingRequired,
     advisoryMissing: advisory,
-    repairCommand: "npx avorelo@latest activate",
+    repairCommand: require("../runtime-provenance").versionAwareActivateCommand("activate"),
   };
 }
 

package/scripts/lib/agent-enforcement.js

@@ -193,6 +193,9 @@ function getMatchedRules(input = {}, classification, profile) {
   const unknownTool = reasons.has("UNKNOWN_MCP_TOOL");
   const writeCapableTool = reasons.has("WRITE_CAPABLE_TOOL");
   const destructiveCommand = reasons.has("DESTRUCTIVE_COMMAND") || reasons.has("FORCE_PUSH_OR_HISTORY_REWRITE");
+  const secretFileRead = reasons.has("SECRET_FILE_READ");
+  const broadPermissionChange = reasons.has("BROAD_PERMISSION_CHANGE");
+  const writeOutsideProject = reasons.has("WRITE_OUTSIDE_PROJECT");
   const externalExport = reasons.has("EXTERNAL_REPO_EXPORT");
   const externalNetwork = reasons.has("EXTERNAL_NETWORK_REQUEST");
   const localhostVisualQa = actionType === "visual_qa_run" && reasons.has("VISUAL_QA_LOCAL_TARGET");
@@ -309,6 +312,30 @@ function getMatchedRules(input = {}, classification, profile) {
     });
   }
 
+  if (secretFileRead) {
+    rules.push({
+      id: "secret_file_read_block",
+      outcome: "block",
+      summary: "Reading secret-bearing files (.env, keys, credentials) is blocked.",
+    });
+  }
+
+  if (writeOutsideProject) {
+    rules.push({
+      id: "write_outside_project_block",
+      outcome: "block",
+      summary: "Writes outside the project root are blocked.",
+    });
+  }
+
+  if (broadPermissionChange) {
+    rules.push({
+      id: "broad_permission_change_guard",
+      outcome: "approval_required",
+      summary: "Broad or recursive permission changes require explicit approval.",
+    });
+  }
+
   if (externalExport) {
     rules.push({
       id: "external_export_guard",

package/scripts/lib/agent-security/sensitive-targets.js

@@ -0,0 +1,94 @@
+"use strict";
+
+// Shared detection for secret-bearing file targets, secret-file reads,
+// and broad permission changes. Used by both the live lifecycle PreToolUse
+// hook and the guard/agent-enforcement CLI path so the two surfaces cannot drift.
+
+function normalize(value) {
+  return String(value || "").replace(/\\/g, "/").trim();
+}
+
+// Secret-bearing file patterns (env files, package/registry auth, ssh/tls keys, secret bundles).
+const SECRET_FILE_PATTERNS = Object.freeze([
+  /(^|\/)\.env(\.[A-Za-z0-9._-]+)?$/i,
+  /(^|\/)\.npmrc$/i,
+  /(^|\/)\.pypirc$/i,
+  /(^|\/)\.netrc$/i,
+  /(^|\/)id_rsa(\.pub)?$/i,
+  /(^|\/)id_ed25519(\.pub)?$/i,
+  /(^|\/)id_dsa(\.pub)?$/i,
+  /(^|\/)id_ecdsa(\.pub)?$/i,
+  /\.pem$/i,
+  /\.key$/i,
+  /\.p12$/i,
+  /\.pfx$/i,
+  /(^|\/)secrets?(\.[A-Za-z0-9._-]+)?$/i,
+  /(^|\/)credentials?(\.[A-Za-z0-9._-]+)?$/i,
+  /(^|\/)\.ssh(\/|$)/i,
+  /(^|\/)\.aws(\/|$)/i,
+]);
+
+function isSecretFilePath(target) {
+  const value = normalize(target);
+  if (!value) return false;
+  return SECRET_FILE_PATTERNS.some((pattern) => pattern.test(value));
+}
+
+// Shell verbs that read/print file contents (POSIX + PowerShell/Windows).
+const READ_VERB = /\b(cat|type|more|less|head|tail|nl|strings|xxd|od|hexdump|base64|grep|egrep|fgrep|rg|ag|findstr|sort|uniq|awk|sed|Get-Content|gc|Select-String|sls)\b/i;
+
+// A token inside a command that looks like a secret file path.
+const SECRET_TOKEN = /(?:^|[\s"'=(])(?:[^\s"'|;&()]*\/)?(?:\.env(?:\.[A-Za-z0-9._-]+)?|\.npmrc|\.pypirc|\.netrc|id_rsa|id_ed25519|id_dsa|id_ecdsa|[^\s"'|;&()]*\.pem|[^\s"'|;&()]*\.key|[^\s"'|;&()]*\.p12|[^\s"'|;&()]*\.pfx|secrets?(?:\.[A-Za-z0-9._-]+)?|credentials?(?:\.[A-Za-z0-9._-]+)?)(?=$|[\s"'|;&)])/i;
+
+function detectSecretFileRead(command) {
+  const text = String(command || "");
+  if (!text.trim()) return null;
+  if (!READ_VERB.test(text)) return null;
+  if (!SECRET_TOKEN.test(text)) return null;
+  return {
+    code: "SECRET_FILE_READ",
+    message: "Reading secret-bearing files (.env, keys, credentials) is blocked.",
+  };
+}
+
+// Broad / recursive permission changes: chmod 777, recursive chmod, or broad Windows ACL grants.
+function detectBroadPermissionChange(command) {
+  const text = String(command || "");
+  if (!text.trim()) return null;
+
+  const chmod = /\bchmod\b/i.test(text);
+  const recursive = /\b(-R|--recursive)\b/i.test(text) || /\bchmod\b[^\n]*\s-\w*R/i.test(text);
+  const worldWritable = /\b(777|666|a\+rwx|ugo\+rwx|o\+w|a\+w)\b/i.test(text);
+  const broadTarget = /\bchmod\b[^\n]*\s(\.|\/|\*|~|\$HOME)(\s|$)/i.test(text);
+
+  if (chmod && worldWritable && (recursive || broadTarget)) {
+    return {
+      code: "BROAD_PERMISSION_CHANGE",
+      severity: "high",
+      message: "Broad recursive permission change (chmod 777 across the repo) is blocked.",
+    };
+  }
+  if (chmod && worldWritable) {
+    return {
+      code: "BROAD_PERMISSION_CHANGE",
+      severity: "medium",
+      message: "World-writable chmod is unsafe. Prefer least privilege.",
+    };
+  }
+  // Windows broad ACL grant to Everyone / full control across a tree.
+  if (/\bicacls\b/i.test(text) && /\/grant\b/i.test(text) && /(Everyone|Users):\(?[^)]*F/i.test(text) && /\/t\b/i.test(text)) {
+    return {
+      code: "BROAD_PERMISSION_CHANGE",
+      severity: "high",
+      message: "Broad recursive Windows ACL grant is blocked.",
+    };
+  }
+  return null;
+}
+
+module.exports = {
+  SECRET_FILE_PATTERNS,
+  isSecretFilePath,
+  detectSecretFileRead,
+  detectBroadPermissionChange,
+};

package/scripts/lib/brain-pack.js

@@ -80,42 +80,68 @@ function readLatestDogfoodSignals(cwd) {
 
 // ── Project builder ───────────────────────────────────────────────────────────
 
+function extractClaudeMdBullets(content, headingRegex) {
+  const lines = String(content || "").split("\n");
+  const out = [];
+  let capturing = false;
+  for (const line of lines) {
+    if (/^#{1,6}\s/.test(line)) {
+      if (capturing) break; // a new heading ends the captured section
+      capturing = headingRegex.test(line);
+      continue;
+    }
+    if (capturing) {
+      const m = line.match(/^\s*[-*]\s+(.*)$/);
+      if (m && m[1].trim()) out.push(m[1].trim().slice(0, 120));
+    }
+  }
+  return out.slice(0, 8);
+}
+
+// Derive project facts from real evidence (CLAUDE.md, package.json, work-control).
+// Never inject Avorelo's own roadmap/architecture into an unrelated project.
 function buildProject(cwd, pkg) {
   const name = pkg?.name || path.basename(cwd);
   const productName = pkg?.productName || pkg?.name || name;
 
-  // Try to read CLAUDE.md for product direction hints
-  let productDirection = "Local AI coding optimization platform.";
-  let architecturePrinciples = [
-    "local-first, no mandatory cloud",
-    "deterministic, no LLM calls in core logic",
-    "compact receipts, not huge JSON",
-    "capability-router pattern: one router, no duplicates",
-    "evidence-backed decisions",
-  ];
-  let nonGoals = [
-    "AI Workspace Registry (deferred)",
-    "Browser Proof (deferred)",
-    "Workflow Intelligence Radar (deferred)",
-    "Full model gateway (deferred)",
-    "Pricing / website (deferred)",
-  ];
+  let productDirection = "";
+  let architecturePrinciples = [];
+  let nonGoals = [];
+  let evidenceBasis = "none";
 
+  let claudeMd = "";
   try {
     const claudeMdPath = path.join(cwd, "CLAUDE.md");
-    if (fs.existsSync(claudeMdPath)) {
-      const content = fs.readFileSync(claudeMdPath, "utf8");
-      // Extract first non-empty line after # heading as direction hint
-      const lines = content.split("\n").filter((l) => l.trim() && !l.startsWith("#")).slice(0, 3);
-      if (lines.length) productDirection = lines[0].slice(0, 200);
-    }
+    if (fs.existsSync(claudeMdPath)) claudeMd = fs.readFileSync(claudeMdPath, "utf8");
   } catch {}
 
-  // Detect current roadmap stage from work-control or package version
+  if (claudeMd) {
+    evidenceBasis = "claude_md";
+    const lines = claudeMd
+      .split("\n")
+      .map((l) => l.trim())
+      .filter((l) => l && !l.startsWith("#") && !l.startsWith("<!--") && !l.startsWith("-->") && !l.startsWith("<"))
+      .slice(0, 5);
+    if (lines.length) productDirection = lines[0].slice(0, 200);
+    architecturePrinciples = extractClaudeMdBullets(claudeMd, /(architecture|convention|principle)/i);
+    nonGoals = extractClaudeMdBullets(claudeMd, /(non[- ]?goal|boundaries|out of scope|do not)/i);
+  }
+
+  if (!productDirection) {
+    if (pkg?.description) {
+      productDirection = String(pkg.description).slice(0, 200);
+      if (evidenceBasis === "none") evidenceBasis = "package_json";
+    } else {
+      productDirection = "No project-specific direction recorded yet.";
+    }
+  }
+
   const wcReceipt = readWorkControlForBrainPack(cwd);
   const currentRoadmapStage = wcReceipt?.task?.text
     ? String(wcReceipt.task.text).slice(0, 100)
-    : "Context Intelligence Completion v1";
+    : pkg?.version
+      ? `v${pkg.version}`
+      : "No project-specific stage recorded yet.";
 
   return {
     name: redactIfSecret(name),
@@ -125,6 +151,7 @@ function buildProject(cwd, pkg) {
     productDirection,
     nonGoals,
     architecturePrinciples,
+    evidenceBasis,
   };
 }
 

package/scripts/lib/dashboard.js

@@ -711,7 +711,7 @@ function buildStatusDashboard(cwd, options = {}) {
   const scopeRepair = (() => { try { return buildScopeRepairSurface(cwd); } catch { return null; } })();
   const nextRunContinuity = (() => { try { return buildNextRunContinuitySurface(cwd, { buildIfMissing: false }); } catch { return null; } })();
   const dataPermissions = (() => { try { return buildDataPermissionsGuardSurface(cwd, { buildIfMissing: false }); } catch { return null; } })();
-  const deploymentEnvironment = (() => { try { return buildDeploymentEnvironmentGuardSurface(cwd, { buildIfMissing: false }); } catch { return null; } })();
+  const deploymentEnvironment = (() => { try { return buildDeploymentEnvironmentGuardSurface(cwd, { buildIfMissing: true }); } catch { return null; } })();
   const supplyChainDependency = (() => { try { return buildSupplyChainDependencyGuardSurface(cwd, { buildIfMissing: false }); } catch { return null; } })();
   const observabilityRecovery = (() => { try { return buildObservabilityRecoveryGuardSurface(cwd, { buildIfMissing: false }); } catch { return null; } })();
   const costAbuse = (() => { try { return buildCostAbuseGuardSurface(cwd, { buildIfMissing: false }); } catch { return null; } })();

package/scripts/lib/hook-apply.js

@@ -16,15 +16,28 @@ const BACKUP_DIR_REL = `${APPLY_DIR_REL}/backups`;
 // Avorelo hook marker used to identify managed entries in config
 const AVORELO_HOOK_MARKER = "_avorelo_managed";
 
-// The lifecycle-hook commands that Avorelo manages
-// Uses npx to resolve the binary from the project's node_modules
+// Runtime-provenance policy lives in runtime-provenance.js (single source of truth):
+// prereleases pin an exact package spec so `npx` cannot silently resolve to `latest`.
+const {
+  resolveAvoreloVersion,
+  isPrereleaseVersion,
+  avoreloNpxSpec,
+} = require("./runtime-provenance");
+
+function lifecycleHookCommand(hookId, version = resolveAvoreloVersion()) {
+  return `npx ${avoreloNpxSpec(version)} lifecycle-hook ${hookId} --json`;
+}
+
+// The lifecycle hooks that Avorelo manages. The `command` field is derived
+// version-aware at build time via lifecycleHookCommand(); the static string
+// here is a stable-spec reference used only for shape/metadata.
 const AVORELO_LIFECYCLE_COMMANDS = Object.freeze([
-  { event: "SessionStart", command: "npx avorelo lifecycle-hook session-start --json", blocking: false, matcher: "" },
-  { event: "UserPromptSubmit", command: "npx avorelo lifecycle-hook user-prompt-submit --json", blocking: false, matcher: "" },
-  { event: "PreToolUse", command: "npx avorelo lifecycle-hook pre-tool-use --json", blocking: true, matcher: "" },
-  { event: "PostToolUse", command: "npx avorelo lifecycle-hook post-tool-use --json", blocking: false, matcher: "" },
-  { event: "Stop", command: "npx avorelo lifecycle-hook stop --json", blocking: true, matcher: "" },
-  { event: "SessionEnd", command: "npx avorelo lifecycle-hook session-end --json", blocking: false, matcher: "" },
+  { event: "SessionStart", hookId: "session-start", command: "npx avorelo lifecycle-hook session-start --json", blocking: false, matcher: "" },
+  { event: "UserPromptSubmit", hookId: "user-prompt-submit", command: "npx avorelo lifecycle-hook user-prompt-submit --json", blocking: false, matcher: "" },
+  { event: "PreToolUse", hookId: "pre-tool-use", command: "npx avorelo lifecycle-hook pre-tool-use --json", blocking: true, matcher: "" },
+  { event: "PostToolUse", hookId: "post-tool-use", command: "npx avorelo lifecycle-hook post-tool-use --json", blocking: false, matcher: "" },
+  { event: "Stop", hookId: "stop", command: "npx avorelo lifecycle-hook stop --json", blocking: true, matcher: "" },
+  { event: "SessionEnd", hookId: "session-end", command: "npx avorelo lifecycle-hook session-end --json", blocking: false, matcher: "" },
 ]);
 
 // Supported host configs
@@ -115,24 +128,70 @@ function parseExistingConfig(configAbsPath, format) {
 function isAvoreloManagedHook(entry) {
   if (!entry || typeof entry !== "object") return false;
   if (entry[AVORELO_HOOK_MARKER] === true) return true;
+  const isLifecycleCommand = (value) => /avorelo(@\S+)?\s+lifecycle-hook/i.test(String(value || ""));
   if (Array.isArray(entry.hooks)) {
-    return entry.hooks.some((h) => h && typeof h.command === "string" && h.command.includes("avorelo lifecycle-hook"));
+    return entry.hooks.some((h) => h && isLifecycleCommand(h.command));
+  }
+  return isLifecycleCommand(entry.command);
+}
+
+// ── User-scope (global) hook blast-radius ─────────────────────────────────────
+// Avorelo installs hooks project-scoped only. This detects Avorelo-managed hooks
+// that ended up in the USER settings (~/.claude/settings.json) — e.g. migration
+// residue or a manual global install — so `doctor` can warn and offer safe removal.
+function userSettingsPath(homeDir) {
+  return path.join(homeDir || os.homedir(), ".claude", "settings.json");
+}
+
+function detectUserScopeAvoreloHooks(homeDir) {
+  const settingsPath = userSettingsPath(homeDir);
+  if (!safeExists(settingsPath)) return { present: false, exists: false, avoreloEvents: [], settingsPath };
+  const data = safeReadJson(settingsPath);
+  if (!data || typeof data.hooks !== "object" || Array.isArray(data.hooks)) {
+    return { present: false, exists: true, avoreloEvents: [], settingsPath };
+  }
+  const avoreloEvents = [];
+  for (const [event, entries] of Object.entries(data.hooks)) {
+    if (Array.isArray(entries) && entries.some(isAvoreloManagedHook)) avoreloEvents.push(event);
   }
-  const cmd = entry.command || "";
-  return cmd.includes("avorelo lifecycle-hook");
+  return { present: avoreloEvents.length > 0, exists: true, avoreloEvents, settingsPath };
+}
+
+// Remove ONLY Avorelo-managed hooks from user settings, preserving every other
+// setting (env, permissions, theme, effort, unrelated hooks). Dry-run by default.
+function removeUserScopeAvoreloHooks(homeDir, options = {}) {
+  const settingsPath = userSettingsPath(homeDir);
+  if (!safeExists(settingsPath)) {
+    return { status: "nothing_to_remove", settingsPath, applied: false };
+  }
+  const data = safeReadJson(settingsPath);
+  if (!data) return { status: "invalid_json", settingsPath, applied: false };
+  const before = detectUserScopeAvoreloHooks(homeDir).avoreloEvents;
+  if (before.length === 0) return { status: "nothing_to_remove", settingsPath, applied: false };
+
+  const cleaned = removeAvoreloHooks(data, "claude_code_settings");
+  if (!options.apply && !options.yes) {
+    return { status: "dry_run", settingsPath, wouldRemoveEvents: before, applied: false };
+  }
+  // Backup then write, preserving all non-Avorelo settings.
+  try {
+    fs.copyFileSync(settingsPath, `${settingsPath}.avorelo-backup-${makeTimestamp()}`);
+  } catch {}
+  safeWriteJson(settingsPath, cleaned);
+  return { status: "removed", settingsPath, removedEvents: before, applied: true };
 }
 
 /**
  * Build the Avorelo hook entries for Claude Code settings.json format.
  * Claude Code v2.1+ expects: {matcher: string, hooks: [{type, command}]}
  */
-function buildClaudeCodeHookEntries() {
+function buildClaudeCodeHookEntries(version = resolveAvoreloVersion()) {
   return AVORELO_LIFECYCLE_COMMANDS.map((lc) => ({
     matcher: lc.matcher,
     hooks: [
       {
         type: "command",
-        command: lc.command,
+        command: lifecycleHookCommand(lc.hookId, version),
       },
     ],
     [AVORELO_HOOK_MARKER]: true,
@@ -143,10 +202,10 @@ function buildClaudeCodeHookEntries() {
 /**
  * Build the Avorelo hook entries for OpenHands hooks.json format.
  */
-function buildOpenHandsHookEntries() {
+function buildOpenHandsHookEntries(version = resolveAvoreloVersion()) {
   return AVORELO_LIFECYCLE_COMMANDS.map((lc) => ({
     event: lc.event,
-    command: lc.command,
+    command: lifecycleHookCommand(lc.hookId, version),
     blocking: lc.blocking,
     [AVORELO_HOOK_MARKER]: true,
   }));
@@ -525,6 +584,15 @@ function applyHookConfig(cwd, plan, options = {}) {
     redacted: true,
   };
 
+  // RC5: applying/changing hooks invalidates any prior runtime sanity — the customer
+  // must restart Claude Code and take a fresh benign turn before we claim live-verified.
+  if (hostsApplied.length > 0) {
+    try {
+      const { invalidateRuntimeSanity } = require("./lifecycle-hooks");
+      invalidateRuntimeSanity(cwd, "hooks_applied");
+    } catch {}
+  }
+
   safeWriteJson(receiptPath, receipt);
   writeLedgerEntry(cwd, "hook_apply", receipt);
   return receipt;
@@ -837,6 +905,39 @@ function runHookDoctor(cwd, options = {}) {
     checks.push({ id: "user_hooks_preserved", host: hostKey, status: "pass", message: `${userHooks.length} user hook(s) preserved.` });
   }
 
+  // Check 1b: HANDLER SANITY (RC5) — structural behavioral check ONLY. Proves the
+  // benign handler sequence does not self-block and unverified mutation gates. This is
+  // NOT proof that Claude Code loaded the hooks or that the host is usable (that is
+  // runtime sanity, below).
+  try {
+    const { buildHandlerSanityProof } = require("./lifecycle-hooks");
+    const sanity = buildHandlerSanityProof({});
+    if (sanity.status === "pass") {
+      checks.push({ id: "handler_sanity", status: "pass", message: "Handler sanity: benign sequence does not self-block; unverified mutation gates with a reason. (Not a live-host verdict.)" });
+    } else if (sanity.conversationCompletes === false) {
+      checks.push({ id: "handler_sanity", status: "fail", message: `Handler sanity FAIL: a benign handler sequence self-blocks (Stop=${sanity.evidence?.conversationTurn?.decision}). Do not treat activation as ready.` });
+    } else {
+      checks.push({ id: "handler_sanity", status: "warn", message: `Handler sanity: intervention did not fire cleanly (${sanity.summary}).` });
+    }
+  } catch (e) {
+    checks.push({ id: "handler_sanity", status: "warn", message: `Handler sanity probe skipped: ${e.message}` });
+  }
+
+  // Check 1c: RUNTIME SANITY STATE (RC5) — honest live-host state. Passed only after a
+  // real CLAUDE_CODE_LIVE benign turn; pending after activation / hook change until the
+  // customer takes a first normal turn in a fresh Claude Code process.
+  try {
+    const { readRuntimeSanity } = require("./lifecycle-hooks");
+    const rs = readRuntimeSanity(cwd);
+    if (rs.state === "passed") {
+      checks.push({ id: "runtime_sanity", status: "pass", message: `Runtime sanity PASSED from a real live benign turn (${rs.provenance || "live"}).` });
+    } else {
+      checks.push({ id: "runtime_sanity", status: "warn", message: "Runtime sanity PENDING: restart Claude Code once; it will verify automatically on your first normal turn. (Not yet live-verified — this is honest, not a failure.)" });
+    }
+  } catch (e) {
+    checks.push({ id: "runtime_sanity", status: "warn", message: `Runtime sanity state unavailable: ${e.message}` });
+  }
+
   // Check 2: Lifecycle handler commands work
   try {
     const { handleLifecycleHook } = require("./lifecycle-hooks");
@@ -896,12 +997,28 @@ function runHookDoctor(cwd, options = {}) {
       : "No backup found. Apply hooks first to enable rollback.",
   });
 
-  // Check 7: No global config modification
-  checks.push({
-    id: "no_global_config_modified",
-    status: "pass",
-    message: "Hook apply only modifies repo-local config. Global config untouched.",
-  });
+  // Check 7: User-scope (global) hook blast-radius. Avorelo installs project-scoped
+  // only; warn if Avorelo-managed hooks are present in user settings (cross-project).
+  try {
+    const userScope = detectUserScopeAvoreloHooks(options.homeDir);
+    if (userScope.present) {
+      checks.push({
+        id: "no_global_hook_blast_radius",
+        status: "warn",
+        message: `Avorelo-managed hooks found in USER settings (${userScope.settingsPath}) for: ${userScope.avoreloEvents.join(", ")}. These affect every repository. Avorelo installs project-scoped only — run \`avorelo hooks uninstall --scope user --yes\` to remove just the Avorelo entries (other settings preserved).`,
+        scope: "user",
+        avoreloEvents: userScope.avoreloEvents,
+      });
+    } else {
+      checks.push({
+        id: "no_global_hook_blast_radius",
+        status: "pass",
+        message: "No Avorelo hooks in user/global settings. Hook install is project-scoped only.",
+      });
+    }
+  } catch {
+    checks.push({ id: "no_global_hook_blast_radius", status: "pass", message: "User-scope hook check skipped (no user settings)." });
+  }
 
   const failCount = checks.filter((c) => c.status === "fail").length;
   const warnCount = checks.filter((c) => c.status === "warn").length;
@@ -1056,6 +1173,8 @@ module.exports = {
   validateAppliedHooks,
   rollbackHookApply,
   uninstallAvoreloHooks,
+  detectUserScopeAvoreloHooks,
+  removeUserScopeAvoreloHooks,
   runHookDoctor,
   writeHookApplyReceipt,
   buildHookApplySurface,
@@ -1064,6 +1183,8 @@ module.exports = {
   formatHookDoctorText,
   // Helpers (exported for testing)
   isAvoreloManagedHook,
+  buildClaudeCodeHookEntries,
+  buildOpenHandsHookEntries,
   mergeClaudeCodeConfig,
   mergeOpenHandsConfig,
   removeAvoreloHooks,
@@ -1072,4 +1193,8 @@ module.exports = {
   parseExistingConfig,
   requiresExplicitApproval,
   isDryRun,
+  resolveAvoreloVersion,
+  isPrereleaseVersion,
+  avoreloNpxSpec,
+  lifecycleHookCommand,
 };