avorelo 0.1.0

package/scripts/lib/pro-moments.js

@@ -0,0 +1,1216 @@
+"use strict";
+
+const { getCurrentPlan } = require("./entitlements");
+const { nowIso } = require("./fsx");
+const { appendProMomentEvent } = require("./pro-moment-events");
+const {
+  buildDefaultProMomentState,
+  getMomentStateEntry,
+  getSuppressionState,
+  readProMomentState,
+  updateProMomentState,
+} = require("./pro-moment-state");
+const { ValueLedger } = require("./value-ledger");
+
+const TRUST_CRITICAL_BASELINES = Object.freeze([
+  "setup_quality",
+  "readiness_truth",
+  "safe_local_repair_basics",
+  "unsafe_action_blocks",
+  "basic_risky_instruction_handling",
+  "basic_skill_instruction_safety_checks",
+  "latest_proof",
+  "latest_status_value_summary",
+  "one_clear_next_action",
+  "basic_recovery_path",
+  "basic_local_usability",
+]);
+
+const ALLOWED_PRO_DEPTH_AREAS = new Set([
+  "deeper_continuity",
+  "richer_history",
+  "export",
+  "longer_retention",
+  "more_visual_qa",
+  "deeper_safe_path",
+  "approval_posture",
+  "source_trust_depth",
+  "risk_based_automatic_routing",
+  "deeper_worker_handoff",
+  "deeper_context_token_insight_history",
+  "multi_repo_depth",
+  "team_shared_policies",
+]);
+
+const PRO_MOMENT_MATURITY_LEVELS = Object.freeze({
+  idea_only: 0,
+  defined_but_disabled: 1,
+  eligibility_implemented: 2,
+  surface_integrated: 3,
+  user_controls_implemented: 4,
+  telemetry_hardened: 5,
+  trust_privacy_copy_regressions: 6,
+  docs_and_decision_record: 7,
+  production_active: 8,
+});
+
+const PRO_MOMENT_COPY_GUARD_PROFILES = Object.freeze({
+  calm_depth: Object.freeze({
+    bannedPhrases: Object.freeze([
+      "Upgrade now",
+      "Stay protected with Pro",
+      "You are unsafe",
+      "You are missing out",
+      "Pay to see proof",
+      "Unlock truth",
+      "limited time",
+      "countdown",
+      "setup is better in Pro",
+      "unlock protection",
+    ]),
+    valueBacked: true,
+    fearBased: false,
+    modalPressure: false,
+  }),
+});
+
+const PRO_MOMENT_PRIVACY_PROFILES = Object.freeze({
+  no_raw_content: Object.freeze({
+    redactPaths: true,
+    redactPrompts: true,
+    redactCode: true,
+    redactSecrets: true,
+    redactSensitiveRepoContent: true,
+  }),
+});
+
+const PRO_MOMENT_TELEMETRY_PROFILES = Object.freeze({
+  human_visible_text_only: Object.freeze({
+    jsonCountsAsShown: false,
+    humanVisibleTextCountsAsShown: true,
+    jsonStartsSuppression: false,
+    recentShownSuppressionHours: 12,
+    redactionRequired: true,
+  }),
+});
+
+const PRO_MOMENT_REQUIRED_USER_CONTROLS = Object.freeze([
+  "inspect",
+  "dismiss",
+  "suppress",
+]);
+
+const PRO_MOMENT_HELPER_SCRIPT = "node scripts/cco-pro-moments.js";
+const CONTINUITY_DETAILS_MESSAGE =
+  "Free preserves your latest next step. Pro can keep deeper continuity across sessions so Avorelo carries more context, proof, and handoff depth over time.";
+const EVIDENCE_HISTORY_DETAILS_MESSAGE =
+  "Free keeps your latest proof. Pro adds richer proof history and export for repeated work, review, and handoff.";
+
+const PRO_MOMENT_DEFINITIONS = Object.freeze({
+  continuity_depth: {
+    id: "continuity_depth",
+    label: "Continuity depth",
+    description: "Offer deeper repeated-work continuity only after Avorelo already preserved useful local context.",
+    status: "active",
+    maturityLevel: PRO_MOMENT_MATURITY_LEVELS.production_active,
+    category: "continuity",
+    planRequirement: "free",
+    freeBoundary: {
+      summary: "Free preserves the latest next step and current continuity truth.",
+      guarantees: [
+        "latest_status_value_summary",
+        "one_clear_next_action",
+        "basic_local_usability",
+      ],
+    },
+    proDepth: {
+      summary: "Pro keeps deeper continuity, proof, and handoff depth across repeated work.",
+      capabilities: ["deeper_continuity", "richer_history"],
+    },
+    allowedSurfaces: ["status", "dashboard", "reentry"],
+    allowedDisplayLevels: ["passive", "contextual_inline"],
+    requiredSignals: ["activation_completed", "value_seen", "repeat_usage"],
+    hardBlockers: ["first_session", "risk_state", "error_state", "cooldown_active"],
+    cooldownDays: 14,
+    globalCooldownDays: 7,
+    cooldownProfile: {
+      momentCooldownDays: 14,
+      globalCooldownDays: 7,
+      repeatedDismissalSuppressionDays: 30,
+      dontShowAgainSuppressionDays: 60,
+      recentShownSuppressionHours: 12,
+    },
+    depthAreas: ["deeper_continuity", "richer_history"],
+    copyGuardProfile: "calm_depth",
+    privacyProfile: "no_raw_content",
+    telemetryProfile: "human_visible_text_only",
+    requiredUserControls: PRO_MOMENT_REQUIRED_USER_CONTROLS,
+    requiredTests: [
+      "eligibility",
+      "surface_rendering",
+      "text_vs_json_telemetry",
+      "cooldown_and_suppression",
+      "copy_guard",
+      "privacy_redaction",
+      "trust_boundaries",
+    ],
+    docs: {
+      engine: "docs/Pro-Moment-Engine.md",
+      decisionRecord: "docs/Pro-Moment-Decision-Records/continuity-depth.md",
+      closureReport: "docs/Pro-Moment-Closure-Report.md",
+      dogfoodChecklist: "docs/Pro-Moment-Dogfood-Checklist.md",
+    },
+    copyVariants: {
+      title: "Keep more continuity across sessions",
+      body:
+        "Avorelo preserved your latest next step. Pro can keep deeper continuity across sessions, so you spend less time rebuilding context.",
+      alternateBody:
+        "Free keeps the latest next step. Pro helps Avorelo carry more context, proof, and handoff depth across repeated work.",
+      primaryAction: "See Pro continuity",
+      secondaryAction: "Not now",
+      tertiaryAction: "Do not show this again for continuity",
+    },
+  },
+  evidence_history_export: {
+    id: "evidence_history_export",
+    label: "Evidence history and export",
+    description: "Offer deeper retained proof history and local export only after the user explicitly reaches for proof depth.",
+    status: "active",
+    maturityLevel: PRO_MOMENT_MATURITY_LEVELS.production_active,
+    category: "evidence",
+    planRequirement: "free",
+    freeBoundary: {
+      summary: "Free keeps the latest proof, current-state truth, and one clear next action visible.",
+      guarantees: [
+        "latest_proof",
+        "latest_status_value_summary",
+        "one_clear_next_action",
+      ],
+    },
+    proDepth: {
+      summary: "Pro keeps the trail with richer history, local export, and longer retained review depth.",
+      capabilities: ["richer_history", "export", "longer_retention"],
+    },
+    allowedSurfaces: ["proof_history", "proof_export", "proof_depth"],
+    allowedDisplayLevels: ["passive", "contextual_inline", "strong"],
+    requiredSignals: ["proof_generated"],
+    hardBlockers: ["first_session", "activation_incomplete", "risk_state", "error_state", "recovery_state", "cooldown_active", "state_invalid"],
+    cooldownDays: 14,
+    globalCooldownDays: 7,
+    cooldownProfile: {
+      momentCooldownDays: 14,
+      globalCooldownDays: 7,
+      repeatedDismissalSuppressionDays: 30,
+      dontShowAgainSuppressionDays: 60,
+      recentShownSuppressionHours: 12,
+    },
+    depthAreas: ["richer_history", "export", "longer_retention"],
+    copyGuardProfile: "calm_depth",
+    privacyProfile: "no_raw_content",
+    telemetryProfile: "human_visible_text_only",
+    requiredUserControls: PRO_MOMENT_REQUIRED_USER_CONTROLS,
+    requiredTests: [
+      "explicit_intent_only",
+      "plain_proof_stays_free",
+      "history_and_export_entitlements",
+      "text_vs_json_telemetry",
+      "cooldown_and_suppression",
+      "copy_guard",
+      "privacy_redaction",
+      "trust_boundaries",
+    ],
+    docs: {
+      engine: "docs/Pro-Moment-Engine.md",
+      decisionRecord: "docs/Pro-Moment-Decision-Records/evidence-history-export.md",
+      closureReport: "docs/Pro-Moment-Closure-Report.md",
+      dogfoodChecklist: "docs/Pro-Moment-Dogfood-Checklist.md",
+    },
+    copyVariants: {
+      title: "Free keeps the latest proof. Pro keeps the trail.",
+      body:
+        "Free keeps your latest proof. Pro adds proof history so repeated work is easier to review and continue.",
+      alternateBody:
+        "Free keeps your latest proof. Pro adds local proof export for review, handoff, and repeated work.",
+      primaryAction: "See Pro proof history",
+      secondaryAction: "Not now",
+      tertiaryAction: "Do not show this again for proof history",
+    },
+  },
+  advanced_security_safe_path: {
+    id: "advanced_security_safe_path",
+    label: "Advanced Safe Path depth",
+    description: "Future depth moment for deeper Safe Path and approval posture.",
+    status: "future",
+    maturityLevel: PRO_MOMENT_MATURITY_LEVELS.defined_but_disabled,
+    category: "security",
+    planRequirement: "free",
+    freeBoundary: {
+      summary: "Basic unsafe-action protection and Safe Path truth remain free.",
+      guarantees: [
+        "unsafe_action_blocks",
+        "basic_risky_instruction_handling",
+        "basic_skill_instruction_safety_checks",
+      ],
+    },
+    proDepth: {
+      summary: "Any future Pro depth would be deeper Safe Path posture only, never basic safety.",
+      capabilities: ["deeper_safe_path", "approval_posture", "source_trust_depth"],
+    },
+    allowedSurfaces: ["status", "dashboard", "security"],
+    allowedDisplayLevels: ["passive", "contextual_inline", "strong"],
+    requiredSignals: ["safe_path_suggested"],
+    hardBlockers: ["first_session", "risk_state", "error_state", "cooldown_active"],
+    cooldownDays: 14,
+    globalCooldownDays: 7,
+    cooldownProfile: {
+      momentCooldownDays: 14,
+      globalCooldownDays: 7,
+      repeatedDismissalSuppressionDays: 30,
+      dontShowAgainSuppressionDays: 60,
+      recentShownSuppressionHours: 12,
+    },
+    depthAreas: ["deeper_safe_path", "approval_posture", "source_trust_depth"],
+    copyGuardProfile: "calm_depth",
+    privacyProfile: "no_raw_content",
+    telemetryProfile: "human_visible_text_only",
+    requiredUserControls: PRO_MOMENT_REQUIRED_USER_CONTROLS,
+    requiredTests: ["not_active_yet"],
+    docs: {
+      engine: "docs/Pro-Moment-Engine.md",
+    },
+  },
+  automatic_risk_based_routing: {
+    id: "automatic_risk_based_routing",
+    label: "Automatic risk-based routing",
+    description: "Future depth moment for automatic routing once the repo has stronger routing truth.",
+    status: "future",
+    maturityLevel: PRO_MOMENT_MATURITY_LEVELS.defined_but_disabled,
+    category: "routing",
+    planRequirement: "free",
+    freeBoundary: {
+      summary: "Basic routing truth and recommendations remain free.",
+      guarantees: [
+        "latest_status_value_summary",
+        "one_clear_next_action",
+      ],
+    },
+    proDepth: {
+      summary: "Any future Pro depth would be deeper risk-based automation only.",
+      capabilities: ["risk_based_automatic_routing"],
+    },
+    allowedSurfaces: ["status", "dashboard", "routing"],
+    allowedDisplayLevels: ["passive", "contextual_inline", "strong"],
+    requiredSignals: ["route_recommendation_shown"],
+    hardBlockers: ["first_session", "risk_state", "error_state", "cooldown_active"],
+    cooldownDays: 14,
+    globalCooldownDays: 7,
+    cooldownProfile: {
+      momentCooldownDays: 14,
+      globalCooldownDays: 7,
+      repeatedDismissalSuppressionDays: 30,
+      dontShowAgainSuppressionDays: 60,
+      recentShownSuppressionHours: 12,
+    },
+    depthAreas: ["risk_based_automatic_routing"],
+    copyGuardProfile: "calm_depth",
+    privacyProfile: "no_raw_content",
+    telemetryProfile: "human_visible_text_only",
+    requiredUserControls: PRO_MOMENT_REQUIRED_USER_CONTROLS,
+    requiredTests: ["not_active_yet"],
+    docs: {
+      engine: "docs/Pro-Moment-Engine.md",
+    },
+  },
+  visual_qa_quota: {
+    id: "visual_qa_quota",
+    label: "Visual QA depth",
+    description: "Future depth moment for expanded Visual QA quota and richer retained reports.",
+    status: "disabled",
+    maturityLevel: PRO_MOMENT_MATURITY_LEVELS.defined_but_disabled,
+    category: "visual_qa",
+    planRequirement: "free",
+    freeBoundary: {
+      summary: "Basic local Visual QA value is not paywalled.",
+      guarantees: [
+        "latest_status_value_summary",
+        "basic_local_usability",
+      ],
+    },
+    proDepth: {
+      summary: "Any future Pro depth would be higher-volume QA and richer retained reports.",
+      capabilities: ["more_visual_qa", "richer_history"],
+    },
+    allowedSurfaces: ["dashboard", "visual_qa"],
+    allowedDisplayLevels: ["passive", "contextual_inline", "strong"],
+    requiredSignals: ["visual_qa_completed"],
+    hardBlockers: ["first_session", "risk_state", "error_state", "cooldown_active"],
+    cooldownDays: 14,
+    globalCooldownDays: 7,
+    cooldownProfile: {
+      momentCooldownDays: 14,
+      globalCooldownDays: 7,
+      repeatedDismissalSuppressionDays: 30,
+      dontShowAgainSuppressionDays: 60,
+      recentShownSuppressionHours: 12,
+    },
+    depthAreas: ["more_visual_qa", "richer_history"],
+    copyGuardProfile: "calm_depth",
+    privacyProfile: "no_raw_content",
+    telemetryProfile: "human_visible_text_only",
+    requiredUserControls: PRO_MOMENT_REQUIRED_USER_CONTROLS,
+    requiredTests: ["not_active_yet"],
+    docs: {
+      engine: "docs/Pro-Moment-Engine.md",
+    },
+  },
+  context_token_insight_depth: {
+    id: "context_token_insight_depth",
+    label: "Context insight depth",
+    description: "Future depth moment for longer context and token insight history.",
+    status: "future",
+    maturityLevel: PRO_MOMENT_MATURITY_LEVELS.defined_but_disabled,
+    category: "context",
+    planRequirement: "free",
+    freeBoundary: {
+      summary: "Basic context discipline and latest next action remain free.",
+      guarantees: [
+        "one_clear_next_action",
+        "basic_local_usability",
+      ],
+    },
+    proDepth: {
+      summary: "Any future Pro depth would be deeper retained context/token history only.",
+      capabilities: ["deeper_context_token_insight_history"],
+    },
+    allowedSurfaces: ["status", "dashboard", "context"],
+    allowedDisplayLevels: ["passive", "contextual_inline"],
+    requiredSignals: ["context_discipline_applied"],
+    hardBlockers: ["first_session", "risk_state", "error_state", "cooldown_active"],
+    cooldownDays: 14,
+    globalCooldownDays: 7,
+    cooldownProfile: {
+      momentCooldownDays: 14,
+      globalCooldownDays: 7,
+      repeatedDismissalSuppressionDays: 30,
+      dontShowAgainSuppressionDays: 60,
+      recentShownSuppressionHours: 12,
+    },
+    depthAreas: ["deeper_context_token_insight_history"],
+    copyGuardProfile: "calm_depth",
+    privacyProfile: "no_raw_content",
+    telemetryProfile: "human_visible_text_only",
+    requiredUserControls: PRO_MOMENT_REQUIRED_USER_CONTROLS,
+    requiredTests: ["not_active_yet"],
+    docs: {
+      engine: "docs/Pro-Moment-Engine.md",
+    },
+  },
+  multi_repo_depth: {
+    id: "multi_repo_depth",
+    label: "Multi-repo depth",
+    description: "Future depth moment for cross-repo continuity later.",
+    status: "future",
+    maturityLevel: PRO_MOMENT_MATURITY_LEVELS.defined_but_disabled,
+    category: "continuity",
+    planRequirement: "free",
+    freeBoundary: {
+      summary: "Single-repo continuity truth remains free.",
+      guarantees: [
+        "latest_status_value_summary",
+        "one_clear_next_action",
+      ],
+    },
+    proDepth: {
+      summary: "Any future Pro depth would be multi-repo continuity only.",
+      capabilities: ["multi_repo_depth"],
+    },
+    allowedSurfaces: ["dashboard"],
+    allowedDisplayLevels: ["passive", "contextual_inline"],
+    requiredSignals: ["repeat_usage"],
+    hardBlockers: ["first_session", "risk_state", "error_state", "cooldown_active"],
+    cooldownDays: 14,
+    globalCooldownDays: 7,
+    cooldownProfile: {
+      momentCooldownDays: 14,
+      globalCooldownDays: 7,
+      repeatedDismissalSuppressionDays: 30,
+      dontShowAgainSuppressionDays: 60,
+      recentShownSuppressionHours: 12,
+    },
+    depthAreas: ["multi_repo_depth"],
+    copyGuardProfile: "calm_depth",
+    privacyProfile: "no_raw_content",
+    telemetryProfile: "human_visible_text_only",
+    requiredUserControls: PRO_MOMENT_REQUIRED_USER_CONTROLS,
+    requiredTests: ["not_active_yet"],
+    docs: {
+      engine: "docs/Pro-Moment-Engine.md",
+    },
+  },
+  team_shared_policy_later: {
+    id: "team_shared_policy_later",
+    label: "Shared policy depth",
+    description: "Future depth moment for team/shared policy surfaces later.",
+    status: "future",
+    maturityLevel: PRO_MOMENT_MATURITY_LEVELS.defined_but_disabled,
+    category: "team",
+    planRequirement: "free",
+    freeBoundary: {
+      summary: "Local single-user truth remains free.",
+      guarantees: [
+        "latest_status_value_summary",
+        "one_clear_next_action",
+        "basic_local_usability",
+      ],
+    },
+    proDepth: {
+      summary: "Any future Pro depth would be shared policy and team carry-forward only.",
+      capabilities: ["team_shared_policies"],
+    },
+    allowedSurfaces: ["dashboard"],
+    allowedDisplayLevels: ["passive", "contextual_inline", "strong"],
+    requiredSignals: ["repeat_usage"],
+    hardBlockers: ["first_session", "risk_state", "error_state", "cooldown_active"],
+    cooldownDays: 14,
+    globalCooldownDays: 7,
+    cooldownProfile: {
+      momentCooldownDays: 14,
+      globalCooldownDays: 7,
+      repeatedDismissalSuppressionDays: 30,
+      dontShowAgainSuppressionDays: 60,
+      recentShownSuppressionHours: 12,
+    },
+    depthAreas: ["team_shared_policies"],
+    copyGuardProfile: "calm_depth",
+    privacyProfile: "no_raw_content",
+    telemetryProfile: "human_visible_text_only",
+    requiredUserControls: PRO_MOMENT_REQUIRED_USER_CONTROLS,
+    requiredTests: ["not_active_yet"],
+    docs: {
+      engine: "docs/Pro-Moment-Engine.md",
+    },
+  },
+});
+
+function getProMomentDefinition(momentId) {
+  return PRO_MOMENT_DEFINITIONS[String(momentId || "").trim()] || null;
+}
+
+function listProMomentDefinitions() {
+  return Object.values(PRO_MOMENT_DEFINITIONS);
+}
+
+function isActiveProMomentDefinition(definition) {
+  return Boolean(definition) && definition.status === "active";
+}
+
+function validateProMomentDefinitions() {
+  return listProMomentDefinitions().every((definition) => {
+    const copyProfile = PRO_MOMENT_COPY_GUARD_PROFILES[definition.copyGuardProfile];
+    const privacyProfile = PRO_MOMENT_PRIVACY_PROFILES[definition.privacyProfile];
+    const telemetryProfile = PRO_MOMENT_TELEMETRY_PROFILES[definition.telemetryProfile];
+    return Array.isArray(definition.depthAreas)
+      && definition.depthAreas.every((area) => ALLOWED_PRO_DEPTH_AREAS.has(area))
+      && Number.isInteger(definition.maturityLevel)
+      && definition.maturityLevel >= PRO_MOMENT_MATURITY_LEVELS.idea_only
+      && definition.maturityLevel <= PRO_MOMENT_MATURITY_LEVELS.production_active
+      && definition.freeBoundary
+      && Array.isArray(definition.freeBoundary.guarantees)
+      && definition.proDepth
+      && Array.isArray(definition.proDepth.capabilities)
+      && definition.proDepth.capabilities.every((area) => ALLOWED_PRO_DEPTH_AREAS.has(area))
+      && Array.isArray(definition.requiredUserControls)
+      && definition.requiredUserControls.every((control) => PRO_MOMENT_REQUIRED_USER_CONTROLS.includes(control))
+      && copyProfile
+      && privacyProfile
+      && telemetryProfile
+      && definition.docs
+      && typeof definition.docs.engine === "string";
+  });
+}
+
+function isTrustCriticalBaseline(key) {
+  return TRUST_CRITICAL_BASELINES.includes(String(key || "").trim());
+}
+
+function countValueEvents(cwd, status) {
+  let total = 0;
+
+  try {
+    const ledger = new ValueLedger(cwd);
+    const events = ledger.loadAll();
+    total += Math.min(events.length, 5);
+    if ((events || []).some((event) => event?.bucket === "reentry_reused")) {
+      total += 1;
+    }
+  } catch {}
+
+  if (status?.activation?.firstValue?.available) total += 1;
+  if (status?.currentState?.reentryStatus) total += 1;
+  if (Number(status?.reentryMemory?.candidatesCount || 0) > 0) total += 1;
+  if (status?.currentState?.nextBoundedAction) total += 1;
+
+  return total;
+}
+
+function deriveRiskState(status) {
+  const explicitRisk = status?.workflowDiscipline?.signals?.riskLevel;
+  if (explicitRisk === "high" || explicitRisk === "medium") return explicitRisk;
+  if (status?.currentState?.reentryStatus === "repair_then_retry") return "recovery";
+  if (status?.currentState?.reentryStatus === "rollback_now") return "recovery";
+  return "safe";
+}
+
+function deriveErrorState(status) {
+  const activationStatus = String(status?.activation?.status || "").toLowerCase();
+  if (activationStatus.includes("fail") || activationStatus.includes("error") || activationStatus.includes("blocked")) {
+    return true;
+  }
+  const readiness = String(status?.currentState?.readinessState || "").toLowerCase();
+  return readiness === "fail" || readiness === "blocked";
+}
+
+function deriveRecoveryState(status) {
+  const reentryStatus = String(status?.currentState?.reentryStatus || "").toLowerCase();
+  return reentryStatus === "repair_then_retry" || reentryStatus === "rollback_now";
+}
+
+function deriveUserAction(surface, status) {
+  if (status?.currentState?.reentryStatus || Number(status?.reentryMemory?.candidatesCount || 0) > 0) {
+    return "viewed_reentry_summary";
+  }
+  return `viewed_${surface}`;
+}
+
+function deriveEligibilityInput(cwd, options = {}) {
+  const surface = String(options.surface || "status");
+  const status = options.status || {};
+  const sessionCount = Math.max(
+    Number(status?.weeklySummary?.sessions || 0),
+    Array.isArray(status?.sessions) ? status.sessions.length : 0,
+  );
+  const activationStatus = String(status?.activation?.status || "");
+  const activationCompleted =
+    status?.activation?.present === true
+    && ["first_value_ready", "active", "completed", "ready"].includes(activationStatus);
+  const firstValueShown = status?.activation?.firstValue?.available === true;
+  const valueEventsCount = countValueEvents(cwd, status);
+  const currentRiskState = deriveRiskState(status);
+  const currentErrorState = deriveErrorState(status);
+  const currentRecoveryState = deriveRecoveryState(status);
+  const repeatedFreeCapabilityUsage =
+    sessionCount >= 2
+    || Number(status?.reentryMemory?.candidatesCount || 0) > 0
+    || Boolean(status?.currentState?.reentryStatus);
+
+  return {
+    plan: String(options.plan || getCurrentPlan({ cwd })),
+    surface,
+    currentSurface: surface,
+    momentCandidate: String(options.momentId || "continuity_depth"),
+    sessionCount,
+    activationCompleted,
+    activationFailed:
+      String(status?.activation?.status || "").toLowerCase().includes("fail")
+      || String(status?.activation?.status || "").toLowerCase().includes("error"),
+    firstValueShown,
+    valueEventsCount,
+    currentRiskState,
+    currentErrorState,
+    currentRecoveryState,
+    userAction: options.userAction || deriveUserAction(surface, status),
+    featureRequested: options.featureRequested || null,
+    quotaReached: options.quotaReached === true,
+    naturalBoundary:
+      ["status", "dashboard", "reentry", "proof_history", "proof_export", "proof_depth"].includes(surface),
+    repeatedFreeCapabilityUsage,
+    reentryUsed: Boolean(status?.currentState?.reentryStatus),
+    proofGenerated: Boolean(status?.latestReport || status?.currentState?.latestTrustworthyRunId),
+    handoffCreated: Boolean(status?.workControl?.latestReceiptPath),
+    contextDisciplineApplied:
+      Boolean(status?.workflowDiscipline?.signals)
+      || Boolean(status?.contextBudgetGuard?.reductionPlan),
+    riskBlockedWarnedScoped:
+      currentRiskState !== "safe"
+      || Number(status?.safePath?.approvalsRequired || 0) > 0
+      || Number(status?.safePath?.blocksPreserved || 0) > 0,
+    safePathSuggested: Number(status?.safePath?.reductionsRecommended || 0) > 0,
+    visualQaCompleted: Number(status?.planSummary?.visualQa?.quota?.used || 0) > 0,
+    routeRecommendationShown: Boolean(status?.orchestration?.statusLine),
+  };
+}
+
+function normalizeMomentInput(input = {}) {
+  return {
+    plan: String(input.plan || "free"),
+    surface: String(input.surface || input.currentSurface || "status"),
+    currentSurface: String(input.currentSurface || input.surface || "status"),
+    momentCandidate: String(input.momentCandidate || "continuity_depth"),
+    sessionCount: Number.isFinite(Number(input.sessionCount)) ? Number(input.sessionCount) : 0,
+    activationCompleted: input.activationCompleted === true,
+    activationFailed: input.activationFailed === true,
+    firstValueShown: input.firstValueShown === true,
+    valueEventsCount: Number.isFinite(Number(input.valueEventsCount)) ? Number(input.valueEventsCount) : 0,
+    currentRiskState: String(input.currentRiskState || "safe"),
+    currentErrorState: input.currentErrorState === true,
+    currentRecoveryState: input.currentRecoveryState === true,
+    userAction: input.userAction ? String(input.userAction) : null,
+    featureRequested: input.featureRequested ? String(input.featureRequested) : null,
+    quotaReached: input.quotaReached === true,
+    naturalBoundary: input.naturalBoundary !== false,
+    repeatedFreeCapabilityUsage: input.repeatedFreeCapabilityUsage === true,
+    reentryUsed: input.reentryUsed === true,
+    proofGenerated: input.proofGenerated === true,
+    handoffCreated: input.handoffCreated === true,
+    contextDisciplineApplied: input.contextDisciplineApplied === true,
+    riskBlockedWarnedScoped: input.riskBlockedWarnedScoped === true,
+    safePathSuggested: input.safePathSuggested === true,
+    visualQaCompleted: input.visualQaCompleted === true,
+    routeRecommendationShown: input.routeRecommendationShown === true,
+    stateIntegrity: String(input.stateIntegrity || "valid"),
+    suppressionState: input.suppressionState || null,
+  };
+}
+
+function hasAnyValueSignal(input) {
+  return Boolean(
+    input.activationCompleted
+    || input.firstValueShown
+    || input.proofGenerated
+    || input.handoffCreated
+    || input.reentryUsed
+    || input.contextDisciplineApplied
+    || input.riskBlockedWarnedScoped
+    || input.safePathSuggested
+    || input.visualQaCompleted
+    || input.routeRecommendationShown
+    || input.valueEventsCount > 0,
+  );
+}
+
+function relatedSurfaceOpen(input) {
+  return input.userAction === "viewed_reentry_summary"
+    || input.currentSurface === "reentry"
+    || input.currentSurface === "proof_history"
+    || input.currentSurface === "proof_export"
+    || input.currentSurface === "proof_depth";
+}
+
+function activeNextEligibleAt(suppressionState) {
+  const values = [
+    suppressionState?.globalSuppressedUntil,
+    suppressionState?.momentSuppressedUntil,
+    suppressionState?.recentlyShownUntil,
+  ]
+    .map((value) => Date.parse(value || ""))
+    .filter((value) => Number.isFinite(value));
+  if (!values.length) return null;
+  return new Date(Math.max(...values)).toISOString();
+}
+
+function buildBlockedReasonCodes(input, definition, suppressionState) {
+  const blocked = [];
+
+  if (!definition) return ["moment_unknown"];
+  if (!isActiveProMomentDefinition(definition)) blocked.push("moment_disabled");
+  if (input.plan !== definition.planRequirement) blocked.push("not_free_plan");
+  if (!definition.allowedSurfaces.includes(input.surface)) blocked.push("surface_not_allowed");
+  if (input.stateIntegrity === "invalid" && !input.featureRequested) blocked.push("state_invalid");
+  if (input.sessionCount <= 1) blocked.push("first_session");
+  if (input.activationFailed) blocked.push("activation_failed");
+  if (!input.activationCompleted) blocked.push("activation_incomplete");
+  if (!hasAnyValueSignal(input)) blocked.push("no_value_signal");
+  if (input.currentRiskState !== "safe") blocked.push("risk_state");
+  if (input.currentErrorState) blocked.push("error_state");
+  if (input.currentRecoveryState) blocked.push("recovery_state");
+  if (suppressionState?.globalCooldownActive) blocked.push("cooldown_active");
+  if (suppressionState?.momentCooldownActive) blocked.push("moment_cooldown_active");
+  if (suppressionState?.recentlyShownActive) blocked.push("recently_shown");
+  if (
+    !input.featureRequested
+    && suppressionState?.momentState?.dismissCount >= 2
+    && suppressionState?.momentCooldownActive
+  ) {
+    blocked.push("multiple_dismissals_suppressed");
+  }
+  if (
+    !input.featureRequested
+    && Number(suppressionState?.momentState?.dismissCount || 0) >= 1
+    && suppressionState?.momentCooldownActive
+  ) {
+    blocked.push("dismissed_recently");
+  }
+
+  return [...new Set(blocked)];
+}
+
+function computeScore(input, suppressionState) {
+  let score = 0;
+  const reasonCodes = [];
+
+  if (input.activationCompleted) {
+    score += 2;
+    reasonCodes.push("activation_completed");
+  }
+  if (input.firstValueShown || input.valueEventsCount > 0) {
+    score += 2;
+    reasonCodes.push("value_seen");
+  }
+  if (input.sessionCount >= 2) {
+    score += 2;
+    reasonCodes.push("repeat_usage");
+  }
+  if (input.valueEventsCount >= 3) {
+    score += 2;
+    reasonCodes.push("value_events_depth");
+  }
+  if (relatedSurfaceOpen(input)) {
+    score += 3;
+    reasonCodes.push("related_surface_opened");
+  }
+  if (input.featureRequested) {
+    score += 4;
+    reasonCodes.push("feature_requested");
+  }
+  if (input.quotaReached) {
+    score += 4;
+    reasonCodes.push("quota_reached");
+  }
+  if (input.naturalBoundary) {
+    score += 2;
+    reasonCodes.push("natural_boundary");
+  }
+  if (input.repeatedFreeCapabilityUsage) {
+    score += 2;
+    reasonCodes.push("repeated_free_capability_usage");
+  }
+
+  if (input.sessionCount <= 1) score -= 10;
+  if (input.currentRiskState !== "safe" || input.currentErrorState || input.currentRecoveryState) score -= 8;
+  if (input.activationFailed) score -= 8;
+  if (suppressionState?.globalCooldownActive) score -= 8;
+  if (suppressionState?.momentCooldownActive) score -= 8;
+  if (Number(suppressionState?.momentState?.dismissCount || 0) >= 1) score -= 5;
+  if (Number(suppressionState?.momentState?.dismissCount || 0) >= 2) {
+    score -= 8;
+  }
+  if (
+    Number(suppressionState?.momentState?.strongModalCount || 0) > 0
+    || Number(suppressionState?.global?.strongModalCount || 0) > 0
+  ) {
+    score -= 8;
+  }
+  if (suppressionState?.recentlyShownActive) score -= 8;
+
+  return {
+    score,
+    reasonCodes,
+  };
+}
+
+function buildProMomentMessage(momentId, context = {}) {
+  const definition = getProMomentDefinition(momentId);
+  if (!definition || !definition.copyVariants) return null;
+  const useAlternate =
+    context.surface === "dashboard"
+    || context.surface === "proof_export"
+    || context.userAction === "viewed_dashboard"
+    || context.valueEventsCount >= 4;
+  return {
+    title: definition.copyVariants.title,
+    body: useAlternate ? definition.copyVariants.alternateBody : definition.copyVariants.body,
+    primaryAction: definition.copyVariants.primaryAction,
+    secondaryAction: definition.copyVariants.secondaryAction,
+    tertiaryAction: definition.copyVariants.tertiaryAction || null,
+  };
+}
+
+function buildProMomentDetailMessage(momentId) {
+  if (momentId === "continuity_depth") {
+    return CONTINUITY_DETAILS_MESSAGE;
+  }
+  if (momentId === "evidence_history_export") {
+    return EVIDENCE_HISTORY_DETAILS_MESSAGE;
+  }
+  return null;
+}
+
+function buildProMomentActionCommands(momentId, surface = "status") {
+  const safeMomentId = String(momentId || "continuity_depth");
+  const safeSurface = String(surface || "status");
+  if (safeMomentId === "evidence_history_export") {
+    return {
+      inspect: {
+        label: "See Pro proof history",
+        command: `${PRO_MOMENT_HELPER_SCRIPT} inspect ${safeMomentId} --surface ${safeSurface}`,
+      },
+      dismiss: {
+        label: "Not now",
+        command: `${PRO_MOMENT_HELPER_SCRIPT} dismiss ${safeMomentId} --surface ${safeSurface}`,
+      },
+      suppress: {
+        label: "Hide proof history",
+        command: `${PRO_MOMENT_HELPER_SCRIPT} suppress ${safeMomentId} --surface ${safeSurface}`,
+      },
+    };
+  }
+  return {
+    inspect: {
+      label: "See Pro continuity",
+      command: `${PRO_MOMENT_HELPER_SCRIPT} inspect ${safeMomentId} --surface ${safeSurface}`,
+    },
+    dismiss: {
+      label: "Not now",
+      command: `${PRO_MOMENT_HELPER_SCRIPT} dismiss ${safeMomentId} --surface ${safeSurface}`,
+    },
+    suppress: {
+      label: "Hide continuity",
+      command: `${PRO_MOMENT_HELPER_SCRIPT} suppress ${safeMomentId} --surface ${safeSurface}`,
+    },
+  };
+}
+
+function resolveDisplayLevel(definition, input, score) {
+  if (!definition) return "none";
+  if (
+    score >= 10
+    && (input.featureRequested || input.quotaReached)
+    && definition.allowedDisplayLevels.includes("strong")
+  ) {
+    return "strong";
+  }
+  if (
+    score >= 6
+    && definition.allowedDisplayLevels.includes("contextual_inline")
+    && relatedSurfaceOpen(input)
+  ) {
+    return "contextual_inline";
+  }
+  if (score >= 6 && definition.allowedDisplayLevels.includes("passive")) {
+    return "passive";
+  }
+  return "none";
+}
+
+function evaluateProMomentEligibility(input) {
+  const normalized = normalizeMomentInput(input);
+  const definition = input?.definitionOverride || getProMomentDefinition(normalized.momentCandidate);
+  const suppressionState =
+    normalized.suppressionState
+    || getSuppressionState(buildDefaultProMomentState(), normalized.momentCandidate);
+  const blockedReasonCodes = buildBlockedReasonCodes(normalized, definition, suppressionState);
+  const { score, reasonCodes } = computeScore(normalized, suppressionState);
+  const hardBlocked = blockedReasonCodes.length > 0;
+  const displayLevel = hardBlocked ? "none" : resolveDisplayLevel(definition, normalized, score);
+  const eligible = !hardBlocked && score >= 6 && displayLevel !== "none";
+
+  return {
+    eligible,
+    momentId: normalized.momentCandidate,
+    displayLevel,
+    score,
+    reasonCodes,
+    blockedReasonCodes,
+    nextEligibleAt: eligible ? null : activeNextEligibleAt(suppressionState),
+    message: eligible
+      ? buildProMomentMessage(normalized.momentCandidate, {
+          surface: normalized.surface,
+          userAction: normalized.userAction,
+          valueEventsCount: normalized.valueEventsCount,
+        })
+      : null,
+  };
+}
+
+function buildProMomentSurface(cwd, options = {}) {
+  const momentId = String(options.momentId || "continuity_depth");
+  const stateRead = readProMomentState(cwd);
+  const suppressionState = getSuppressionState(stateRead.state, momentId, {
+    proactive: options.proactive !== undefined ? options.proactive : !options.featureRequested,
+    respectRecentShown:
+      options.respectRecentShown !== undefined ? options.respectRecentShown : !options.featureRequested,
+  });
+  const input = {
+    ...deriveEligibilityInput(cwd, {
+      surface: options.surface || "status",
+      status: options.status || {},
+      momentId,
+      featureRequested: options.featureRequested,
+      quotaReached: options.quotaReached,
+      plan: options.plan,
+      userAction: options.userAction,
+    }),
+    stateIntegrity: stateRead.integrity,
+    suppressionState,
+  };
+  const decision = evaluateProMomentEligibility(input);
+
+  return {
+    ...decision,
+    surface: input.surface,
+    plan: input.plan,
+    sessionCount: input.sessionCount,
+    valueEventsCount: input.valueEventsCount,
+    dismissCount: suppressionState.momentState.dismissCount,
+    cooldownActive:
+      suppressionState.globalCooldownActive
+      || suppressionState.momentCooldownActive
+      || suppressionState.recentlyShownActive,
+    detailMessage: buildProMomentDetailMessage(momentId),
+    actions: buildProMomentActionCommands(momentId, input.surface),
+    statePath: stateRead.path,
+    stateIntegrity: stateRead.integrity,
+    warning: stateRead.warning,
+  };
+}
+
+function buildCompactProMomentLines(surface) {
+  if (!surface?.eligible || !surface.message) return [];
+  return [
+    `Pro depth available: ${surface.message.body}`,
+    `${surface.actions.inspect.label}: ${surface.actions.inspect.command}`,
+    `${surface.actions.dismiss.label}: ${surface.actions.dismiss.command}`,
+    `${surface.actions.suppress.label}: ${surface.actions.suppress.command}`,
+  ];
+}
+
+function buildEventPayload(surface) {
+  return {
+    momentId: surface.momentId,
+    surface: surface.surface,
+    displayLevel: surface.displayLevel,
+    reasonCodes: surface.reasonCodes,
+    blockedReasonCodes: surface.blockedReasonCodes,
+    plan: surface.plan,
+    sessionCount: surface.sessionCount,
+    valueEventsCount: surface.valueEventsCount,
+    dismissCount: surface.dismissCount,
+    cooldownActive: surface.cooldownActive,
+    nextEligibleAt: surface.nextEligibleAt,
+    timestamp: nowIso(),
+  };
+}
+
+function recordProMomentShown(cwd, params = {}) {
+  const momentId = String(params.momentId || "continuity_depth");
+  const now = params.timestamp || nowIso();
+
+  const writeResult = updateProMomentState(cwd, (current) => {
+    const source = current || buildDefaultProMomentState();
+    const currentMoment = getMomentStateEntry(source, momentId);
+    return {
+      ...source,
+      global: {
+        ...source.global,
+        lastShownAt: now,
+        strongModalCount:
+          source.global.strongModalCount + (params.displayLevel === "strong" ? 1 : 0),
+      },
+      moments: {
+        ...source.moments,
+        [momentId]: {
+          ...currentMoment,
+          lastShownAt: now,
+          shownCount: currentMoment.shownCount + 1,
+        },
+      },
+    };
+  });
+
+  const event = appendProMomentEvent(cwd, "pro_nudge_shown", {
+    ...params,
+    momentId,
+    timestamp: now,
+  });
+
+  return {
+    ok: writeResult.ok && event.ok,
+    statePath: writeResult.path,
+    event,
+  };
+}
+
+function recordProMomentClicked(cwd, params = {}) {
+  const momentId = String(params.momentId || "continuity_depth");
+  const now = params.timestamp || nowIso();
+
+  updateProMomentState(cwd, (current) => {
+    const source = current || buildDefaultProMomentState();
+    const currentMoment = getMomentStateEntry(source, momentId);
+    return {
+      ...source,
+      moments: {
+        ...source.moments,
+        [momentId]: {
+          ...currentMoment,
+          clickedCount: currentMoment.clickedCount + 1,
+          lastClickedAt: now,
+        },
+      },
+    };
+  });
+
+  return appendProMomentEvent(cwd, "pro_nudge_clicked", {
+    ...params,
+    momentId,
+    timestamp: now,
+  });
+}
+
+function recordProMomentDismissed(cwd, params = {}) {
+  const momentId = String(params.momentId || "continuity_depth");
+  const now = params.timestamp || nowIso();
+  const kind = params.kind === "dont_show_again" ? "dont_show_again" : "not_now";
+
+  const updated = updateProMomentState(cwd, (current) => {
+    const source = current || buildDefaultProMomentState();
+    const currentMoment = getMomentStateEntry(source, momentId);
+    const nextMomentDismissCount = currentMoment.dismissCount + 1;
+    const nextGlobalDismissCount = Number(source.global.dismissCount || 0) + 1;
+    const momentSuppressedDays =
+      kind === "dont_show_again"
+        ? 60
+        : nextMomentDismissCount >= 2
+          ? 30
+          : 14;
+    const globalSuppressedDays = nextGlobalDismissCount >= 3 ? 30 : 7;
+
+    return {
+      ...source,
+      global: {
+        ...source.global,
+        dismissCount: nextGlobalDismissCount,
+        suppressedUntil: new Date(
+          Date.parse(now) + globalSuppressedDays * 24 * 60 * 60 * 1000,
+        ).toISOString(),
+      },
+      moments: {
+        ...source.moments,
+        [momentId]: {
+          ...currentMoment,
+          dismissCount: nextMomentDismissCount,
+          lastDismissedAt: now,
+          suppressedUntil: new Date(
+            Date.parse(now) + momentSuppressedDays * 24 * 60 * 60 * 1000,
+          ).toISOString(),
+        },
+      },
+    };
+  });
+
+  const nextState = readProMomentState(cwd).state;
+  const nextMoment = getMomentStateEntry(nextState, momentId);
+  appendProMomentEvent(cwd, "pro_nudge_dismissed", {
+    ...params,
+    momentId,
+    dismissCount: nextMoment.dismissCount,
+    timestamp: now,
+  });
+  appendProMomentEvent(cwd, "pro_nudge_cooldown_started", {
+    ...params,
+    momentId,
+    dismissCount: nextMoment.dismissCount,
+    cooldownActive: true,
+    nextEligibleAt: nextMoment.suppressedUntil,
+    timestamp: now,
+  });
+  if (kind === "not_now") {
+    appendProMomentEvent(cwd, "pro_nudge_not_now_clicked", {
+      ...params,
+      momentId,
+      dismissCount: nextMoment.dismissCount,
+      timestamp: now,
+    });
+  }
+  if (kind === "dont_show_again") {
+    appendProMomentEvent(cwd, "pro_nudge_dont_show_again_clicked", {
+      ...params,
+      momentId,
+      dismissCount: nextMoment.dismissCount,
+      cooldownActive: true,
+      nextEligibleAt: nextMoment.suppressedUntil,
+      timestamp: now,
+    });
+  }
+  if (nextMoment.dismissCount >= 2) {
+    appendProMomentEvent(cwd, "pro_nudge_multiple_dismissals", {
+      ...params,
+      momentId,
+      dismissCount: nextMoment.dismissCount,
+      cooldownActive: true,
+      nextEligibleAt: nextMoment.suppressedUntil,
+      timestamp: now,
+    });
+  }
+
+  return {
+    ok: updated.ok,
+    statePath: updated.path,
+    state: nextState,
+  };
+}
+
+function recordProMomentEvaluation(cwd, surface, options = {}) {
+  if (!surface || !surface.momentId) return { ok: false, reason: "missing_surface" };
+  if (options.humanVisible === false) {
+    return { ok: true, skipped: true, reason: "not_human_visible" };
+  }
+  const payload = buildEventPayload(surface);
+  const shouldLogSuppression =
+    surface.eligible
+    || surface.blockedReasonCodes?.includes("cooldown_active")
+    || surface.blockedReasonCodes?.includes("moment_cooldown_active")
+    || surface.blockedReasonCodes?.includes("recently_shown")
+    || surface.blockedReasonCodes?.includes("multiple_dismissals_suppressed")
+    || surface.blockedReasonCodes?.includes("state_invalid");
+  if (!shouldLogSuppression) {
+    return { ok: true, skipped: true };
+  }
+
+  appendProMomentEvent(cwd, "pro_moment_candidate_detected", payload);
+
+  if (surface.eligible) {
+    appendProMomentEvent(cwd, "pro_moment_eligible", payload);
+    return recordProMomentShown(cwd, payload);
+  }
+
+  if (surface.blockedReasonCodes?.length) {
+    appendProMomentEvent(cwd, "pro_moment_suppressed", payload);
+    if (
+      surface.blockedReasonCodes.includes("cooldown_active")
+      || surface.blockedReasonCodes.includes("moment_cooldown_active")
+      || surface.blockedReasonCodes.includes("recently_shown")
+    ) {
+      appendProMomentEvent(cwd, "pro_nudge_hidden_due_to_cooldown", payload);
+    }
+  }
+
+  return { ok: true, suppressed: true };
+}
+
+module.exports = {
+  ALLOWED_PRO_DEPTH_AREAS,
+  PRO_MOMENT_COPY_GUARD_PROFILES,
+  PRO_MOMENT_DEFINITIONS,
+  PRO_MOMENT_MATURITY_LEVELS,
+  PRO_MOMENT_PRIVACY_PROFILES,
+  PRO_MOMENT_REQUIRED_USER_CONTROLS,
+  PRO_MOMENT_TELEMETRY_PROFILES,
+  TRUST_CRITICAL_BASELINES,
+  buildCompactProMomentLines,
+  buildProMomentActionCommands,
+  buildProMomentDetailMessage,
+  buildProMomentMessage,
+  buildProMomentSurface,
+  deriveEligibilityInput,
+  evaluateProMomentEligibility,
+  getProMomentDefinition,
+  isActiveProMomentDefinition,
+  isTrustCriticalBaseline,
+  listProMomentDefinitions,
+  recordProMomentClicked,
+  recordProMomentDismissed,
+  recordProMomentEvaluation,
+  recordProMomentShown,
+  validateProMomentDefinitions,
+};