scene-capability-engine 3.6.32 → 3.6.36

package/lib/auto/governance-maintenance-presenter.js

@@ -0,0 +1,162 @@
+function defaultEvaluateGovernanceReleaseGateBlockState(assessment) {
+  const releaseGate = assessment && assessment.release_gate && typeof assessment.release_gate === 'object'
+    ? assessment.release_gate
+    : (assessment && assessment.health && assessment.health.release_gate && typeof assessment.health.release_gate === 'object'
+      ? assessment.health.release_gate
+      : {});
+  const blockedReasons = Array.isArray(releaseGate.blocked_reasons) ? releaseGate.blocked_reasons : [];
+  return {
+    blocked: releaseGate.available === true && releaseGate.latest_gate_passed === false,
+    reasons: blockedReasons
+  };
+}
+
+function buildAutoGovernanceMaintenancePlan(assessment = {}, policy = {}, dryRun = false, dependencies = {}) {
+  const sessionTotal = Number(assessment && assessment.archives && assessment.archives.session && assessment.archives.session.total_sessions) || 0;
+  const batchTotal = Number(assessment && assessment.archives && assessment.archives.batch_session && assessment.archives.batch_session.total_sessions) || 0;
+  const controllerTotal = Number(assessment && assessment.archives && assessment.archives.controller_session && assessment.archives.controller_session.total_sessions) || 0;
+  const recoverySignatureCount = Number(assessment && assessment.recovery_memory && assessment.recovery_memory.signature_count) || 0;
+  const failedSessions = Number(assessment && assessment.totals && assessment.totals.failed_sessions) || 0;
+  const pendingGoals = Number(assessment && assessment.throughput && assessment.throughput.controller_pending_goals_sum) || Number(assessment && assessment.totals && assessment.totals.pending_goals_sum) || 0;
+
+  const sessionKeep = Number(policy.session_keep || 0);
+  const batchSessionKeep = Number(policy.batch_session_keep || 0);
+  const controllerSessionKeep = Number(policy.controller_session_keep || 0);
+  const recoveryOlderThanDays = policy.recovery_memory_older_than_days;
+
+  const sessionCommand = `sce auto session prune --keep ${sessionKeep}${dryRun ? ' --dry-run' : ''} --json`;
+  const batchCommand = `sce auto batch-session prune --keep ${batchSessionKeep}${dryRun ? ' --dry-run' : ''} --json`;
+  const controllerCommand = `sce auto controller-session prune --keep ${controllerSessionKeep}${dryRun ? ' --dry-run' : ''} --json`;
+  const recoveryCommand = `sce auto recovery-memory prune --older-than-days ${recoveryOlderThanDays}${dryRun ? ' --dry-run' : ''} --json`;
+  const evaluateGovernanceReleaseGateBlockState = dependencies.evaluateGovernanceReleaseGateBlockState || defaultEvaluateGovernanceReleaseGateBlockState;
+  const releaseGateBlockState = evaluateGovernanceReleaseGateBlockState(assessment);
+  const releaseGateReasons = Array.isArray(releaseGateBlockState.reasons) ? releaseGateBlockState.reasons : [];
+  const releaseGateAdvisoryPlan = [];
+  if (releaseGateBlockState.blocked) {
+    releaseGateAdvisoryPlan.push({
+      id: 'release-gate-evidence-review',
+      type: 'advisory',
+      apply_supported: false,
+      enabled: true,
+      reason: `release gate quality is blocking governance loop: ${releaseGateReasons.join(', ')}`,
+      command: 'sce auto handoff evidence --window 5 --json',
+      blocked_reasons: releaseGateReasons
+    });
+    if (releaseGateReasons.some((item) => `${item}`.includes('scene-batch') || `${item}`.includes('drift'))) {
+      releaseGateAdvisoryPlan.push({
+        id: 'release-gate-scene-batch-remediate',
+        type: 'advisory',
+        apply_supported: false,
+        enabled: true,
+        reason: 'release gate drift/scene signals need package-publish-batch remediation',
+        command: 'sce scene package-publish-batch --manifest docs/handoffs/handoff-manifest.json --dry-run --json',
+        blocked_reasons: releaseGateReasons
+      });
+    }
+    if (releaseGateReasons.some((item) => `${item}`.startsWith('handoff-'))) {
+      releaseGateAdvisoryPlan.push({
+        id: 'release-gate-handoff-remediate',
+        type: 'advisory',
+        apply_supported: false,
+        enabled: true,
+        reason: 'handoff quality signals are blocking governance convergence',
+        command: 'sce auto handoff run --manifest docs/handoffs/handoff-manifest.json --dry-run --json',
+        blocked_reasons: releaseGateReasons
+      });
+    }
+  }
+
+  return [
+    ...releaseGateAdvisoryPlan,
+    {
+      id: 'session-prune',
+      type: 'maintenance',
+      apply_supported: true,
+      enabled: sessionTotal > sessionKeep,
+      reason: sessionTotal > sessionKeep
+        ? `close-loop session archive ${sessionTotal} exceeds keep policy ${sessionKeep}`
+        : 'close-loop session archive is within keep policy',
+      command: sessionCommand,
+      target_total: sessionTotal,
+      keep: sessionKeep
+    },
+    {
+      id: 'batch-session-prune',
+      type: 'maintenance',
+      apply_supported: true,
+      enabled: batchTotal > batchSessionKeep,
+      reason: batchTotal > batchSessionKeep
+        ? `batch session archive ${batchTotal} exceeds keep policy ${batchSessionKeep}`
+        : 'batch session archive is within keep policy',
+      command: batchCommand,
+      target_total: batchTotal,
+      keep: batchSessionKeep
+    },
+    {
+      id: 'controller-session-prune',
+      type: 'maintenance',
+      apply_supported: true,
+      enabled: controllerTotal > controllerSessionKeep,
+      reason: controllerTotal > controllerSessionKeep
+        ? `controller session archive ${controllerTotal} exceeds keep policy ${controllerSessionKeep}`
+        : 'controller session archive is within keep policy',
+      command: controllerCommand,
+      target_total: controllerTotal,
+      keep: controllerSessionKeep
+    },
+    {
+      id: 'recovery-memory-prune',
+      type: 'maintenance',
+      apply_supported: true,
+      enabled: recoverySignatureCount > 0,
+      reason: recoverySignatureCount > 0
+        ? `recovery memory contains ${recoverySignatureCount} signature(s), prune stale entries`
+        : 'recovery memory is empty',
+      command: recoveryCommand,
+      target_total: recoverySignatureCount,
+      older_than_days: recoveryOlderThanDays
+    },
+    {
+      id: 'recover-latest',
+      type: 'advisory',
+      apply_supported: false,
+      enabled: failedSessions > 0,
+      reason: failedSessions > 0
+        ? `${failedSessions} failed session(s) detected, run recovery drain`
+        : 'no failed sessions detected',
+      command: 'sce auto close-loop-recover latest --recover-until-complete --json'
+    },
+    {
+      id: 'controller-resume-latest',
+      type: 'advisory',
+      apply_supported: false,
+      enabled: pendingGoals > 0,
+      reason: pendingGoals > 0
+        ? `${pendingGoals} pending controller goal(s) detected, resume controller queue`
+        : 'no pending controller goals detected',
+      command: 'sce auto close-loop-controller --controller-resume latest --json'
+    }
+  ];
+}
+
+function summarizeGovernanceMaintenanceExecution(plan = [], executedActions = []) {
+  const safePlan = Array.isArray(plan) ? plan : [];
+  const safeExecuted = Array.isArray(executedActions) ? executedActions : [];
+  const plannedActions = safePlan.filter((item) => item && item.enabled).length;
+  const applicableActions = safePlan.filter((item) => item && item.enabled && item.apply_supported).length;
+  const advisoryActions = safePlan.filter((item) => item && item.enabled && !item.apply_supported).length;
+  const appliedActions = safeExecuted.filter((item) => item && item.status === 'applied').length;
+  const failedActions = safeExecuted.filter((item) => item && item.status === 'failed').length;
+  return {
+    planned_actions: plannedActions,
+    applicable_actions: applicableActions,
+    advisory_actions: advisoryActions,
+    applied_actions: appliedActions,
+    failed_actions: failedActions
+  };
+}
+
+module.exports = {
+  buildAutoGovernanceMaintenancePlan,
+  summarizeGovernanceMaintenanceExecution
+};

package/lib/auto/governance-maintenance-service.js

@@ -0,0 +1,112 @@
+async function runAutoGovernanceMaintenance(projectPath, options = {}, dependencies = {}) {
+  const {
+    normalizeStatsWindowDays,
+    normalizeStatusFilter,
+    normalizeGovernanceKeepOption,
+    normalizeGovernanceRecoveryOlderThanDays,
+    buildAutoGovernanceStats,
+    buildAutoGovernanceMaintenancePlan,
+    evaluateGovernanceReleaseGateBlockState,
+    pruneCloseLoopSessions,
+    pruneCloseLoopBatchSummarySessionsCli,
+    pruneCloseLoopControllerSessionsCli,
+    pruneCloseLoopRecoveryMemory,
+    summarizeGovernanceMaintenanceExecution,
+    now = () => new Date()
+  } = dependencies;
+
+  const days = normalizeStatsWindowDays(options.days);
+  const statusFilter = normalizeStatusFilter(options.status);
+  const assessmentOptions = {
+    days,
+    status: statusFilter.length > 0 ? statusFilter.join(',') : undefined
+  };
+  const policy = {
+    session_keep: normalizeGovernanceKeepOption(options.sessionKeep, '--session-keep', 50),
+    batch_session_keep: normalizeGovernanceKeepOption(options.batchSessionKeep, '--batch-session-keep', 50),
+    controller_session_keep: normalizeGovernanceKeepOption(options.controllerSessionKeep, '--controller-session-keep', 50),
+    recovery_memory_older_than_days: normalizeGovernanceRecoveryOlderThanDays(options.recoveryMemoryOlderThanDays, 90)
+  };
+  const apply = Boolean(options.apply);
+  const dryRun = Boolean(options.dryRun);
+  const assessment = await buildAutoGovernanceStats(projectPath, assessmentOptions);
+  const plan = buildAutoGovernanceMaintenancePlan(assessment, policy, dryRun, {
+    evaluateGovernanceReleaseGateBlockState
+  });
+  const executedActions = [];
+
+  if (apply) {
+    for (const action of plan) {
+      if (!action.enabled || !action.apply_supported) {
+        continue;
+      }
+      try {
+        let result = null;
+        if (action.id === 'session-prune') {
+          result = await pruneCloseLoopSessions(projectPath, {
+            keep: policy.session_keep,
+            olderThanDays: null,
+            dryRun
+          });
+        } else if (action.id === 'batch-session-prune') {
+          result = await pruneCloseLoopBatchSummarySessionsCli(projectPath, {
+            keep: policy.batch_session_keep,
+            olderThanDays: null,
+            dryRun
+          });
+        } else if (action.id === 'controller-session-prune') {
+          result = await pruneCloseLoopControllerSessionsCli(projectPath, {
+            keep: policy.controller_session_keep,
+            olderThanDays: null,
+            dryRun
+          });
+        } else if (action.id === 'recovery-memory-prune') {
+          result = await pruneCloseLoopRecoveryMemory(projectPath, {
+            olderThanDays: policy.recovery_memory_older_than_days,
+            dryRun
+          });
+        }
+        executedActions.push({
+          id: action.id,
+          status: 'applied',
+          result
+        });
+      } catch (error) {
+        executedActions.push({
+          id: action.id,
+          status: 'failed',
+          error: error.message
+        });
+      }
+    }
+  }
+
+  const afterAssessment = apply && !dryRun
+    ? await buildAutoGovernanceStats(projectPath, assessmentOptions)
+    : null;
+
+  const nowValue = now();
+  return {
+    mode: 'auto-governance-maintain',
+    generated_at: nowValue instanceof Date ? nowValue.toISOString() : new Date(nowValue).toISOString(),
+    apply,
+    dry_run: dryRun,
+    criteria: {
+      days,
+      status_filter: statusFilter,
+      since: days === null
+        ? null
+        : new Date((nowValue instanceof Date ? nowValue.getTime() : new Date(nowValue).getTime()) - (days * 24 * 60 * 60 * 1000)).toISOString()
+    },
+    policy,
+    assessment,
+    plan,
+    executed_actions: executedActions,
+    summary: summarizeGovernanceMaintenanceExecution(plan, executedActions),
+    after_assessment: afterAssessment
+  };
+}
+
+module.exports = {
+  runAutoGovernanceMaintenance
+};

package/lib/auto/governance-session-presenter.js

@@ -0,0 +1,70 @@
+function presentGovernanceSessionList(
+  projectPath,
+  filteredSessions,
+  statusFilter,
+  resumeOnly,
+  buildStatusCounts,
+  getGovernanceCloseLoopSessionDir,
+  limit = null
+) {
+  const sessions = Array.isArray(filteredSessions) ? filteredSessions : [];
+  const resumedSessions = sessions.filter((session) => session && session.resumed_from_governance_session_id).length;
+  const maxItems = Number.isInteger(limit) && limit > 0 ? limit : sessions.length;
+  return {
+    mode: 'auto-governance-session-list',
+    session_dir: getGovernanceCloseLoopSessionDir(projectPath),
+    total: sessions.length,
+    status_filter: statusFilter,
+    resume_only: resumeOnly,
+    resumed_sessions: resumedSessions,
+    fresh_sessions: sessions.length - resumedSessions,
+    status_counts: buildStatusCounts(sessions),
+    sessions: sessions.slice(0, maxItems).map((item) => ({
+      id: item.id,
+      status: item.status,
+      target_risk: item.target_risk,
+      final_risk: item.final_risk,
+      performed_rounds: item.performed_rounds,
+      max_rounds: item.max_rounds,
+      converged: item.converged,
+      execute_advisory: item.execute_advisory,
+      advisory_failed_actions: item.advisory_failed_actions,
+      release_gate_available: item.release_gate_available,
+      release_gate_latest_gate_passed: item.release_gate_latest_gate_passed,
+      release_gate_pass_rate_percent: item.release_gate_pass_rate_percent,
+      release_gate_drift_alert_rate_percent: item.release_gate_drift_alert_rate_percent,
+      round_release_gate_observed: item.round_release_gate_observed,
+      round_release_gate_changed: item.round_release_gate_changed,
+      stop_detail_weekly_ops_available: item.stop_detail_weekly_ops_available,
+      stop_detail_weekly_ops_blocked: item.stop_detail_weekly_ops_blocked,
+      stop_detail_weekly_ops_high_pressure: item.stop_detail_weekly_ops_high_pressure,
+      stop_detail_weekly_ops_config_warning_positive: item.stop_detail_weekly_ops_config_warning_positive,
+      stop_detail_weekly_ops_auth_tier_block_rate_high: item.stop_detail_weekly_ops_auth_tier_block_rate_high,
+      stop_detail_weekly_ops_dialogue_authorization_block_rate_high:
+        item.stop_detail_weekly_ops_dialogue_authorization_block_rate_high,
+      stop_detail_weekly_ops_runtime_block_rate_high: item.stop_detail_weekly_ops_runtime_block_rate_high,
+      stop_detail_weekly_ops_runtime_ui_mode_violation_high:
+        item.stop_detail_weekly_ops_runtime_ui_mode_violation_high,
+      stop_detail_weekly_ops_blocked_runs: item.stop_detail_weekly_ops_blocked_runs,
+      stop_detail_weekly_ops_block_rate_percent: item.stop_detail_weekly_ops_block_rate_percent,
+      stop_detail_weekly_ops_config_warnings_total: item.stop_detail_weekly_ops_config_warnings_total,
+      stop_detail_weekly_ops_auth_tier_block_rate_percent: item.stop_detail_weekly_ops_auth_tier_block_rate_percent,
+      stop_detail_weekly_ops_dialogue_authorization_block_rate_percent:
+        item.stop_detail_weekly_ops_dialogue_authorization_block_rate_percent,
+      stop_detail_weekly_ops_runtime_block_rate_percent: item.stop_detail_weekly_ops_runtime_block_rate_percent,
+      stop_detail_weekly_ops_runtime_ui_mode_violation_total:
+        item.stop_detail_weekly_ops_runtime_ui_mode_violation_total,
+      stop_detail_weekly_ops_runtime_ui_mode_violation_rate_percent:
+        item.stop_detail_weekly_ops_runtime_ui_mode_violation_rate_percent,
+      stop_reason: item.stop_reason,
+      resumed_from_governance_session_id: item.resumed_from_governance_session_id,
+      updated_at: item.updated_at,
+      parse_error: item.parse_error,
+      file: item.file
+    }))
+  };
+}
+
+module.exports = {
+  presentGovernanceSessionList
+};

package/lib/auto/governance-session-storage-service.js

@@ -0,0 +1,198 @@
+const path = require('path');
+
+async function readGovernanceCloseLoopSessionEntries(projectPath, dependencies = {}) {
+  const {
+    getGovernanceCloseLoopSessionDir,
+    fs,
+    normalizeGovernanceReleaseGateSnapshot,
+    summarizeGovernanceRoundReleaseGateTelemetry,
+    normalizeGovernanceWeeklyOpsStopDetail,
+    deriveGovernanceWeeklyOpsReasonFlags
+  } = dependencies;
+  const sessionDir = getGovernanceCloseLoopSessionDir(projectPath);
+  if (!(await fs.pathExists(sessionDir))) {
+    return [];
+  }
+
+  const files = (await fs.readdir(sessionDir)).filter((item) => item.toLowerCase().endsWith('.json'));
+  const sessions = [];
+
+  for (const file of files) {
+    const filePath = path.join(sessionDir, file);
+    const stats = await fs.stat(filePath);
+    const fallbackTimestamp = new Date(stats.mtimeMs).toISOString();
+    const fallbackId = path.basename(file, '.json');
+    let payload = null;
+    let parseError = null;
+
+    try {
+      payload = await fs.readJson(filePath);
+    } catch (error) {
+      parseError = error;
+    }
+
+    const finalReleaseGate = normalizeGovernanceReleaseGateSnapshot(
+      payload && payload.final_assessment && payload.final_assessment.health
+        ? payload.final_assessment.health.release_gate
+        : null
+    );
+    const roundReleaseGateTelemetry = summarizeGovernanceRoundReleaseGateTelemetry(payload && payload.rounds);
+    const stopDetail = payload && payload.stop_detail && typeof payload.stop_detail === 'object' ? payload.stop_detail : null;
+    const stopDetailReasons = Array.isArray(stopDetail && stopDetail.reasons) ? stopDetail.reasons : [];
+    const stopDetailWeeklyOps = normalizeGovernanceWeeklyOpsStopDetail(stopDetail && stopDetail.weekly_ops);
+    const stopDetailWeeklyOpsReasonFlags = deriveGovernanceWeeklyOpsReasonFlags(stopDetailReasons);
+
+    const latestAuthTier = stopDetailWeeklyOps && stopDetailWeeklyOps.latest && Number.isFinite(stopDetailWeeklyOps.latest.authorization_tier_block_rate_percent)
+      ? stopDetailWeeklyOps.latest.authorization_tier_block_rate_percent
+      : (stopDetailWeeklyOps && stopDetailWeeklyOps.aggregates && Number.isFinite(stopDetailWeeklyOps.aggregates.authorization_tier_block_rate_max_percent)
+        ? stopDetailWeeklyOps.aggregates.authorization_tier_block_rate_max_percent
+        : null);
+    const latestDialogue = stopDetailWeeklyOps && stopDetailWeeklyOps.latest && Number.isFinite(stopDetailWeeklyOps.latest.dialogue_authorization_block_rate_percent)
+      ? stopDetailWeeklyOps.latest.dialogue_authorization_block_rate_percent
+      : (stopDetailWeeklyOps && stopDetailWeeklyOps.aggregates && Number.isFinite(stopDetailWeeklyOps.aggregates.dialogue_authorization_block_rate_max_percent)
+        ? stopDetailWeeklyOps.aggregates.dialogue_authorization_block_rate_max_percent
+        : null);
+    const latestRuntimeBlock = stopDetailWeeklyOps && stopDetailWeeklyOps.latest && Number.isFinite(stopDetailWeeklyOps.latest.runtime_block_rate_percent)
+      ? stopDetailWeeklyOps.latest.runtime_block_rate_percent
+      : (stopDetailWeeklyOps && stopDetailWeeklyOps.aggregates && Number.isFinite(stopDetailWeeklyOps.aggregates.runtime_block_rate_max_percent)
+        ? stopDetailWeeklyOps.aggregates.runtime_block_rate_max_percent
+        : null);
+    const latestUiTotal = stopDetailWeeklyOps && stopDetailWeeklyOps.latest && Number.isFinite(stopDetailWeeklyOps.latest.runtime_ui_mode_violation_total)
+      ? stopDetailWeeklyOps.latest.runtime_ui_mode_violation_total
+      : (stopDetailWeeklyOps && stopDetailWeeklyOps.aggregates && Number.isFinite(stopDetailWeeklyOps.aggregates.runtime_ui_mode_violation_total)
+        ? stopDetailWeeklyOps.aggregates.runtime_ui_mode_violation_total
+        : null);
+    const latestUiRate = stopDetailWeeklyOps && stopDetailWeeklyOps.latest && Number.isFinite(stopDetailWeeklyOps.latest.runtime_ui_mode_violation_rate_percent)
+      ? stopDetailWeeklyOps.latest.runtime_ui_mode_violation_rate_percent
+      : (stopDetailWeeklyOps && stopDetailWeeklyOps.aggregates && Number.isFinite(stopDetailWeeklyOps.aggregates.runtime_ui_mode_violation_rate_max_percent)
+        ? stopDetailWeeklyOps.aggregates.runtime_ui_mode_violation_rate_max_percent
+        : null);
+
+    sessions.push({
+      id: payload && payload.governance_session && typeof payload.governance_session.id === 'string' ? payload.governance_session.id : fallbackId,
+      file: filePath,
+      status: payload && typeof payload.status === 'string' ? payload.status : (parseError ? 'invalid' : 'unknown'),
+      target_risk: payload && typeof payload.target_risk === 'string' ? payload.target_risk : null,
+      final_risk: payload && payload.final_assessment && payload.final_assessment.health && typeof payload.final_assessment.health.risk_level === 'string'
+        ? payload.final_assessment.health.risk_level
+        : null,
+      performed_rounds: Number(payload && payload.performed_rounds) || 0,
+      max_rounds: Number(payload && payload.max_rounds) || null,
+      converged: Boolean(payload && payload.converged),
+      execute_advisory: payload && payload.execute_advisory === true,
+      advisory_failed_actions: payload && payload.advisory_summary ? Number(payload.advisory_summary.failed_actions) || 0 : null,
+      release_gate_available: finalReleaseGate ? finalReleaseGate.available : null,
+      release_gate_latest_gate_passed: finalReleaseGate ? finalReleaseGate.latest_gate_passed : null,
+      release_gate_pass_rate_percent: finalReleaseGate ? finalReleaseGate.pass_rate_percent : null,
+      release_gate_scene_package_batch_pass_rate_percent: finalReleaseGate ? finalReleaseGate.scene_package_batch_pass_rate_percent : null,
+      release_gate_drift_alert_rate_percent: finalReleaseGate ? finalReleaseGate.drift_alert_rate_percent : null,
+      release_gate_drift_blocked_runs: finalReleaseGate ? finalReleaseGate.drift_blocked_runs : null,
+      round_release_gate_observed: roundReleaseGateTelemetry.observed_rounds,
+      round_release_gate_changed: roundReleaseGateTelemetry.changed_rounds,
+      stop_detail_weekly_ops_available: stopDetailWeeklyOps !== null || stopDetailWeeklyOpsReasonFlags.has_weekly_ops_reason,
+      stop_detail_weekly_ops_blocked: (stopDetailWeeklyOps && stopDetailWeeklyOps.pressure && typeof stopDetailWeeklyOps.pressure.blocked === 'boolean') ? stopDetailWeeklyOps.pressure.blocked : stopDetailWeeklyOpsReasonFlags.blocked,
+      stop_detail_weekly_ops_high_pressure: (stopDetailWeeklyOps && stopDetailWeeklyOps.pressure && typeof stopDetailWeeklyOps.pressure.high === 'boolean') ? stopDetailWeeklyOps.pressure.high : stopDetailWeeklyOpsReasonFlags.high,
+      stop_detail_weekly_ops_config_warning_positive: (stopDetailWeeklyOps && stopDetailWeeklyOps.pressure && typeof stopDetailWeeklyOps.pressure.config_warning_positive === 'boolean') ? stopDetailWeeklyOps.pressure.config_warning_positive : stopDetailWeeklyOpsReasonFlags.config_warning_positive,
+      stop_detail_weekly_ops_auth_tier_block_rate_high: (stopDetailWeeklyOps && stopDetailWeeklyOps.pressure && typeof stopDetailWeeklyOps.pressure.auth_tier_block_rate_high === 'boolean') ? stopDetailWeeklyOps.pressure.auth_tier_block_rate_high : stopDetailWeeklyOpsReasonFlags.auth_tier_block_rate_high,
+      stop_detail_weekly_ops_dialogue_authorization_block_rate_high: (stopDetailWeeklyOps && stopDetailWeeklyOps.pressure && typeof stopDetailWeeklyOps.pressure.dialogue_authorization_block_rate_high === 'boolean') ? stopDetailWeeklyOps.pressure.dialogue_authorization_block_rate_high : stopDetailWeeklyOpsReasonFlags.dialogue_authorization_block_rate_high,
+      stop_detail_weekly_ops_runtime_block_rate_high: (stopDetailWeeklyOps && stopDetailWeeklyOps.pressure && typeof stopDetailWeeklyOps.pressure.runtime_block_rate_high === 'boolean') ? stopDetailWeeklyOps.pressure.runtime_block_rate_high : stopDetailWeeklyOpsReasonFlags.runtime_block_rate_high,
+      stop_detail_weekly_ops_runtime_ui_mode_violation_high: (stopDetailWeeklyOps && stopDetailWeeklyOps.pressure && typeof stopDetailWeeklyOps.pressure.runtime_ui_mode_violation_high === 'boolean') ? stopDetailWeeklyOps.pressure.runtime_ui_mode_violation_high : stopDetailWeeklyOpsReasonFlags.runtime_ui_mode_violation_high,
+      stop_detail_weekly_ops_blocked_runs: stopDetailWeeklyOps && stopDetailWeeklyOps.aggregates ? stopDetailWeeklyOps.aggregates.blocked_runs : null,
+      stop_detail_weekly_ops_block_rate_percent: stopDetailWeeklyOps && stopDetailWeeklyOps.aggregates ? stopDetailWeeklyOps.aggregates.block_rate_percent : null,
+      stop_detail_weekly_ops_config_warnings_total: stopDetailWeeklyOps && stopDetailWeeklyOps.aggregates ? stopDetailWeeklyOps.aggregates.config_warnings_total : null,
+      stop_detail_weekly_ops_auth_tier_block_rate_percent: latestAuthTier,
+      stop_detail_weekly_ops_dialogue_authorization_block_rate_percent: latestDialogue,
+      stop_detail_weekly_ops_runtime_block_rate_percent: latestRuntimeBlock,
+      stop_detail_weekly_ops_runtime_ui_mode_violation_total: latestUiTotal,
+      stop_detail_weekly_ops_runtime_ui_mode_violation_rate_percent: latestUiRate,
+      stop_reason: payload && typeof payload.stop_reason === 'string' ? payload.stop_reason : null,
+      resumed_from_governance_session_id: payload && payload.resumed_from_governance_session && typeof payload.resumed_from_governance_session.id === 'string'
+        ? payload.resumed_from_governance_session.id
+        : null,
+      updated_at: payload && typeof payload.updated_at === 'string' ? payload.updated_at : fallbackTimestamp,
+      parse_error: parseError ? parseError.message : null,
+      mtime_ms: stats.mtimeMs
+    });
+  }
+
+  sessions.sort((a, b) => b.mtime_ms - a.mtime_ms);
+  return sessions;
+}
+
+async function resolveGovernanceCloseLoopSessionFile(projectPath, sessionCandidate, dependencies = {}) {
+  const { readGovernanceCloseLoopSessionEntries, getGovernanceCloseLoopSessionDir, sanitizeBatchSessionId, fs } = dependencies;
+  if (typeof sessionCandidate !== 'string' || !sessionCandidate.trim()) {
+    throw new Error('--governance-resume requires a session id/file or "latest".');
+  }
+  const normalizedCandidate = sessionCandidate.trim();
+  if (normalizedCandidate.toLowerCase() === 'latest') {
+    const sessions = await readGovernanceCloseLoopSessionEntries(projectPath, dependencies);
+    if (sessions.length === 0) {
+      throw new Error(`No governance close-loop sessions found in: ${getGovernanceCloseLoopSessionDir(projectPath)}`);
+    }
+    return sessions[0].file;
+  }
+  if (path.isAbsolute(normalizedCandidate)) {
+    return normalizedCandidate;
+  }
+  if (normalizedCandidate.includes('/') || normalizedCandidate.includes('\\') || normalizedCandidate.toLowerCase().endsWith('.json')) {
+    return path.join(projectPath, normalizedCandidate);
+  }
+  const byId = path.join(getGovernanceCloseLoopSessionDir(projectPath), `${sanitizeBatchSessionId(normalizedCandidate)}.json`);
+  if (await fs.pathExists(byId)) {
+    return byId;
+  }
+  return path.join(projectPath, normalizedCandidate);
+}
+
+async function loadGovernanceCloseLoopSessionPayload(projectPath, sessionCandidate, dependencies = {}) {
+  const { fs } = dependencies;
+  const sessionFile = await resolveGovernanceCloseLoopSessionFile(projectPath, sessionCandidate, dependencies);
+  if (!(await fs.pathExists(sessionFile))) {
+    throw new Error(`Governance close-loop session file not found: ${sessionFile}`);
+  }
+  let payload = null;
+  try {
+    payload = await fs.readJson(sessionFile);
+  } catch (error) {
+    throw new Error(`Invalid governance close-loop session JSON: ${sessionFile} (${error.message})`);
+  }
+  if (!payload || typeof payload !== 'object') {
+    throw new Error(`Invalid governance close-loop session payload: ${sessionFile}`);
+  }
+  const sessionId = payload && payload.governance_session && payload.governance_session.id
+    ? payload.governance_session.id
+    : path.basename(sessionFile, '.json');
+  return { id: sessionId, file: sessionFile, payload };
+}
+
+async function persistGovernanceCloseLoopSession(projectPath, sessionId, payload, status = 'running', dependencies = {}) {
+  const { sanitizeBatchSessionId, getGovernanceCloseLoopSessionDir, schemaVersion, fs, now = () => new Date() } = dependencies;
+  const safeSessionId = sanitizeBatchSessionId(sessionId);
+  if (!safeSessionId) {
+    return null;
+  }
+  const sessionDir = getGovernanceCloseLoopSessionDir(projectPath);
+  const sessionFile = path.join(sessionDir, `${safeSessionId}.json`);
+  const nowValue = now();
+  const updatedAt = nowValue instanceof Date ? nowValue.toISOString() : new Date(nowValue).toISOString();
+  const persisted = {
+    ...payload,
+    schema_version: schemaVersion,
+    status,
+    governance_session: { id: safeSessionId, file: sessionFile },
+    updated_at: updatedAt
+  };
+  await fs.ensureDir(sessionDir);
+  await fs.writeJson(sessionFile, persisted, { spaces: 2 });
+  return { id: safeSessionId, file: sessionFile };
+}
+
+module.exports = {
+  readGovernanceCloseLoopSessionEntries,
+  resolveGovernanceCloseLoopSessionFile,
+  loadGovernanceCloseLoopSessionPayload,
+  persistGovernanceCloseLoopSession
+};
+
+