smart-context-mcp 1.4.0 → 1.6.0

package/src/tools/smart-doctor.js

@@ -0,0 +1,418 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { getRepoMutationSafety } from '../repo-safety.js';
+import {
+  ACTIVE_SESSION_SCOPE,
+  diagnoseStateStorage,
+  getLegacyActiveSessionPath,
+  getLegacyMetricsPath,
+  getLegacySessionsDir,
+  getMeta,
+  getStateDbPath,
+  withStateDbSnapshot,
+} from '../storage/sqlite.js';
+import { attachSafetyMetadata } from '../utils/mutation-safety.js';
+import { recordToolUsage } from '../usage-feedback.js';
+import { recordDecision, DECISION_REASONS, EXPECTED_BENEFITS } from '../decision-explainer.js';
+import { recordDevctxOperation } from '../missed-opportunities.js';
+import { countTokens } from '../tokenCounter.js';
+
+const DEFAULT_RETENTION_DAYS = 30;
+const DEFAULT_KEEP_LATEST_EVENTS_PER_SESSION = 20;
+const DEFAULT_KEEP_LATEST_METRICS = 1000;
+const SESSION_EVENTS_WARNING_FLOOR = DEFAULT_KEEP_LATEST_EVENTS_PER_SESSION * 10;
+const METRICS_WARNING_FLOOR = Math.ceil(DEFAULT_KEEP_LATEST_METRICS * 1.5);
+const STATUS_RANK = {
+  info: 0,
+  ok: 1,
+  warning: 2,
+  error: 3,
+};
+
+const uniqueStrings = (items) => [...new Set(items.filter((item) => typeof item === 'string' && item.trim().length > 0))];
+
+const compactPath = (filePath) => {
+  if (!filePath) {
+    return filePath;
+  }
+  const normalized = filePath.replace(/\\/g, '/');
+  const parts = normalized.split('/').filter(Boolean);
+  return parts.length <= 3 ? normalized : `.../${parts.slice(-3).join('/')}`;
+};
+
+const daysSince = (isoString) => {
+  const timestamp = Date.parse(isoString ?? '');
+  if (!Number.isFinite(timestamp)) {
+    return null;
+  }
+  return Math.max(0, (Date.now() - timestamp) / (24 * 60 * 60 * 1000));
+};
+
+const buildCheck = ({ id, status, message, recommendedActions = [], details = {} }) => ({
+  id,
+  status,
+  message,
+  recommendedActions: uniqueStrings(recommendedActions),
+  details,
+});
+
+const readMaintenanceSnapshot = async ({ filePath, storageHealth }) => {
+  if (!storageHealth?.exists) {
+    return { available: false, reason: 'missing' };
+  }
+
+  if (['locked', 'corrupted', 'unavailable', 'unknown'].includes(storageHealth.issue)) {
+    return { available: false, reason: storageHealth.issue };
+  }
+
+  try {
+    return await withStateDbSnapshot((db) => {
+      const count = (tableName) => db.prepare(`SELECT COUNT(*) AS count FROM ${tableName}`).get().count;
+
+      return {
+        available: true,
+        counts: {
+          sessions: count('sessions'),
+          sessionEvents: count('session_events'),
+          metricsEvents: count('metrics_events'),
+          hookTurnState: count('hook_turn_state'),
+          workflowMetrics: count('workflow_metrics'),
+        },
+        activeSessionId: db.prepare('SELECT session_id FROM active_session WHERE scope = ?').get(ACTIVE_SESSION_SCOPE)?.session_id ?? null,
+        schemaVersion: Number(getMeta(db, 'schema_version') ?? 0),
+        lastCompactedAt: getMeta(db, 'state_compacted_at'),
+        retentionDays: Number(getMeta(db, 'state_compaction_retention_days') ?? DEFAULT_RETENTION_DAYS),
+        legacyImport: {
+          sessions: Number(getMeta(db, 'legacy_sessions_import_count') ?? 0),
+          metrics: Number(getMeta(db, 'legacy_metrics_import_count') ?? 0),
+        },
+      };
+    }, { filePath });
+  } catch (error) {
+    return {
+      available: false,
+      reason: error.storageHealth?.issue ?? 'unknown',
+      error: error.message,
+    };
+  }
+};
+
+const inspectLegacyFiles = () => {
+  const sessionsDir = getLegacySessionsDir();
+  const metricsFile = getLegacyMetricsPath();
+  const activeSessionFile = getLegacyActiveSessionPath();
+  const sessionFiles = fs.existsSync(sessionsDir)
+    ? fs.readdirSync(sessionsDir)
+      .filter((fileName) => fileName.endsWith('.json') && fileName !== 'active.json')
+      .map((fileName) => path.join(sessionsDir, fileName))
+    : [];
+
+  return {
+    sessionsDir,
+    sessionFiles,
+    activeSessionFile,
+    activeSessionExists: fs.existsSync(activeSessionFile),
+    metricsFile,
+    metricsExists: fs.existsSync(metricsFile),
+  };
+};
+
+const buildRepoSafetyCheck = (mutationSafety) => {
+  const repoSafety = mutationSafety.repoSafety;
+
+  if (!repoSafety?.available) {
+    return buildCheck({
+      id: 'repoSafety',
+      status: 'info',
+      message: 'Repository safety checks are unavailable because this project is not inside a git repository.',
+      recommendedActions: [],
+      details: {
+        available: false,
+      },
+    });
+  }
+
+  if (mutationSafety.shouldBlock) {
+    return buildCheck({
+      id: 'repoSafety',
+      status: 'error',
+      message: 'Git hygiene is actively blocking persisted devctx writes for project-local state.',
+      recommendedActions: repoSafety.recommendedActions,
+      details: {
+        blockedBy: mutationSafety.reasons,
+        stateDbPath: repoSafety.stateDbPath,
+        warnings: repoSafety.warnings,
+      },
+    });
+  }
+
+  if (repoSafety.riskLevel === 'warning') {
+    return buildCheck({
+      id: 'repoSafety',
+      status: 'warning',
+      message: 'Repository safety is degraded: local devctx state is not fully protected against accidental commits.',
+      recommendedActions: repoSafety.recommendedActions,
+      details: {
+        stateDbPath: repoSafety.stateDbPath,
+        warnings: repoSafety.warnings,
+      },
+    });
+  }
+
+  return buildCheck({
+    id: 'repoSafety',
+    status: 'ok',
+    message: 'Repository safety checks are healthy for project-local devctx state.',
+    recommendedActions: [],
+    details: {
+      stateDbPath: repoSafety.stateDbPath,
+      projectGitignorePath: repoSafety.projectGitignorePath,
+    },
+  });
+};
+
+const buildStorageCheck = (storageHealth) => {
+  const status = storageHealth.status === 'error'
+    ? 'error'
+    : storageHealth.status === 'warning'
+      ? 'warning'
+      : 'ok';
+
+  return buildCheck({
+    id: 'storageHealth',
+    status,
+    message: storageHealth.message,
+    recommendedActions: storageHealth.recommendedActions,
+    details: {
+      issue: storageHealth.issue,
+      filePath: compactPath(storageHealth.filePath),
+      relativePath: storageHealth.relativePath,
+      sizeBytes: storageHealth.sizeBytes,
+      softMaxBytes: storageHealth.softMaxBytes,
+      integrity: storageHealth.integrity ?? null,
+    },
+  });
+};
+
+const buildCompactionCheck = ({ storageHealth, maintenance }) => {
+  if (!storageHealth.exists) {
+    return buildCheck({
+      id: 'compaction',
+      status: 'info',
+      message: 'Compaction checks are not applicable until project-local SQLite state exists.',
+      recommendedActions: [],
+      details: {
+        available: false,
+        reason: 'missing',
+      },
+    });
+  }
+
+  if (!maintenance?.available) {
+    return buildCheck({
+      id: 'compaction',
+      status: storageHealth.status === 'error' ? 'warning' : 'info',
+      message: 'Compaction hygiene could not be inspected until SQLite storage health is repaired.',
+      recommendedActions: storageHealth.recommendedActions,
+      details: {
+        available: false,
+        reason: maintenance?.reason ?? storageHealth.issue,
+      },
+    });
+  }
+
+  const {
+    counts,
+    lastCompactedAt,
+    retentionDays,
+    schemaVersion,
+    activeSessionId,
+  } = maintenance;
+  const daysSinceCompaction = daysSince(lastCompactedAt);
+  const sessionEventThreshold = Math.max(SESSION_EVENTS_WARNING_FLOOR, counts.sessions * DEFAULT_KEEP_LATEST_EVENTS_PER_SESSION * 5);
+  const needsCompaction = [];
+
+  if (storageHealth.issue === 'oversized') {
+    needsCompaction.push('database_size');
+  }
+
+  if (!lastCompactedAt && (counts.sessionEvents > sessionEventThreshold || counts.metricsEvents > METRICS_WARNING_FLOOR)) {
+    needsCompaction.push('never_compacted');
+  }
+
+  if (
+    daysSinceCompaction !== null
+    && daysSinceCompaction > retentionDays
+    && (counts.sessionEvents > sessionEventThreshold || counts.metricsEvents > DEFAULT_KEEP_LATEST_METRICS)
+  ) {
+    needsCompaction.push('stale_compaction');
+  }
+
+  if (needsCompaction.length > 0) {
+    return buildCheck({
+      id: 'compaction',
+      status: 'warning',
+      message: 'SQLite retention/compaction hygiene should be refreshed before the local state grows further.',
+      recommendedActions: [
+        'Run smart_summary with action="compact" to prune old events and metrics.',
+        'Use vacuum=true if you expect large deletions and want to reclaim file size immediately.',
+      ],
+      details: {
+        available: true,
+        recommended: true,
+        reasons: needsCompaction,
+        schemaVersion,
+        activeSessionId,
+        counts,
+        lastCompactedAt,
+        daysSinceCompaction,
+        retentionDays,
+      },
+    });
+  }
+
+  return buildCheck({
+    id: 'compaction',
+    status: 'ok',
+    message: 'SQLite retention and compaction hygiene look healthy for the current local state volume.',
+    recommendedActions: [],
+    details: {
+      available: true,
+      recommended: false,
+      schemaVersion,
+      activeSessionId,
+      counts,
+      lastCompactedAt,
+      daysSinceCompaction,
+      retentionDays,
+    },
+  });
+};
+
+const buildLegacyCheck = ({ legacyFiles, maintenance }) => {
+  const totalArtifacts = legacyFiles.sessionFiles.length + (legacyFiles.activeSessionExists ? 1 : 0) + (legacyFiles.metricsExists ? 1 : 0);
+
+  if (totalArtifacts === 0) {
+    return buildCheck({
+      id: 'legacyState',
+      status: 'ok',
+      message: 'No legacy JSON/JSONL state artifacts were detected alongside SQLite state.',
+      recommendedActions: [],
+      details: {
+        present: false,
+        sessionFiles: 0,
+        metricsExists: false,
+        activeSessionExists: false,
+      },
+    });
+  }
+
+  const importedSessions = maintenance?.available ? maintenance.legacyImport.sessions : null;
+  const importedMetrics = maintenance?.available ? maintenance.legacyImport.metrics : null;
+
+  return buildCheck({
+    id: 'legacyState',
+    status: 'warning',
+    message: 'Legacy JSON/JSONL state artifacts are still present and should be reviewed for cleanup.',
+    recommendedActions: [
+      'Run smart_summary with action="cleanup_legacy" to inspect removable legacy files.',
+      importedSessions || importedMetrics
+        ? 'If the SQLite import is already validated, rerun smart_summary cleanup_legacy with apply=true to remove eligible files.'
+        : 'Validate that legacy state has been imported before deleting old JSON/JSONL files.',
+    ],
+    details: {
+      present: true,
+      sessionFiles: legacyFiles.sessionFiles.length,
+      sampleSessionFiles: legacyFiles.sessionFiles.slice(0, 3).map(compactPath),
+      metricsExists: legacyFiles.metricsExists,
+      activeSessionExists: legacyFiles.activeSessionExists,
+      importedSessions,
+      importedMetrics,
+    },
+  });
+};
+
+const summarizeOverall = (checks) => {
+  const highest = checks.reduce((max, check) => Math.max(max, STATUS_RANK[check.status] ?? 0), 0);
+  if (highest >= STATUS_RANK.error) {
+    return 'error';
+  }
+  if (highest >= STATUS_RANK.warning) {
+    return 'warning';
+  }
+  return 'ok';
+};
+
+const buildSummaryMessage = (overall) => {
+  if (overall === 'error') {
+    return 'devctx doctor found blocking operational issues in local state or repo hygiene.';
+  }
+  if (overall === 'warning') {
+    return 'devctx doctor found non-blocking issues that should be cleaned up before they accumulate.';
+  }
+  return 'devctx doctor found the local state setup healthy for normal use.';
+};
+
+export const smartDoctor = async ({ verifyIntegrity = true } = {}) => {
+  recordDecision({
+    tool: 'smart_doctor',
+    reason: DECISION_REASONS.CONTEXT_VISIBILITY,
+    benefit: EXPECTED_BENEFITS.TRANSPARENCY,
+  });
+  recordDevctxOperation('smart_doctor');
+
+  const mutationSafety = getRepoMutationSafety();
+  const storageHealth = await diagnoseStateStorage({
+    filePath: getStateDbPath(),
+    verifyIntegrity,
+  });
+  const maintenance = await readMaintenanceSnapshot({
+    filePath: getStateDbPath(),
+    storageHealth,
+  });
+  const legacyFiles = inspectLegacyFiles();
+
+  const checks = [
+    buildRepoSafetyCheck(mutationSafety),
+    buildStorageCheck(storageHealth),
+    buildCompactionCheck({ storageHealth, maintenance }),
+    buildLegacyCheck({ legacyFiles, maintenance }),
+  ];
+
+  const overall = summarizeOverall(checks);
+  const recommendedActions = uniqueStrings(checks.flatMap((check) => check.recommendedActions));
+  const result = attachSafetyMetadata({
+    success: overall !== 'error',
+    overall,
+    message: buildSummaryMessage(overall),
+    checks,
+    recommendedActions,
+    storageHealth,
+    maintenance: maintenance?.available ? maintenance : null,
+    legacyState: {
+      sessionsDir: compactPath(legacyFiles.sessionsDir),
+      metricsFile: compactPath(legacyFiles.metricsFile),
+      activeSessionFile: compactPath(legacyFiles.activeSessionFile),
+      sessionFiles: legacyFiles.sessionFiles.length,
+      activeSessionExists: legacyFiles.activeSessionExists,
+      metricsExists: legacyFiles.metricsExists,
+    },
+  }, {
+    repoSafety: mutationSafety.repoSafety,
+    sideEffectsSuppressed: mutationSafety.shouldBlock,
+    subject: 'Project-local context writes',
+    degradedReason: 'repo_safety_blocked',
+    degradedMode: 'read_only_snapshot',
+    degradedImpact: 'Persistent writes remain blocked while repo safety is unhealthy.',
+  });
+
+  recordToolUsage({
+    tool: 'smart_doctor',
+    rawTokens: 0,
+    compressedTokens: countTokens(JSON.stringify(result)),
+    savedTokens: 0,
+    savingsPct: 0,
+  });
+
+  return result;
+};

package/src/tools/smart-metrics.js

@@ -1,7 +1,9 @@
 import fs from 'node:fs';
-import { enforceRepoSafety, getRepoSafety } from '../repo-safety.js';
+import { getRepoMutationSafety, getRepoSafety } from '../repo-safety.js';
 import {
   ACTIVE_SESSION_SCOPE,
+  diagnoseStateStorage,
+  getStateStorageHealth,
   importLegacyState,
   withStateDb,
   withStateDbSnapshot,
@@ -15,6 +17,8 @@ import {
   resolveMetricsInput,
 } from '../metrics.js';
 import { analyzeAdoption } from '../analytics/adoption.js';
+import { analyzeProductQuality } from '../analytics/product-quality.js';
+import { attachSafetyMetadata } from '../utils/mutation-safety.js';
 
 const WINDOW_MS = {
   '24h': 24 * 60 * 60 * 1000,
@@ -62,22 +66,8 @@ const buildLatestEntries = (entries, limit) =>
 
 const getActiveSessionId = (db) =>
   db.prepare('SELECT session_id FROM active_session WHERE scope = ?').get(ACTIVE_SESSION_SCOPE)?.session_id ?? null;
-const HARD_BLOCK_REPO_SAFETY_REASONS = [
-  ['tracked', 'isTracked'],
-  ['staged', 'isStaged'],
-];
-
 const getSqliteSafetyPolicy = () => {
-  const repoSafety = enforceRepoSafety();
-  const reasons = HARD_BLOCK_REPO_SAFETY_REASONS
-    .filter(([, field]) => repoSafety[field])
-    .map(([reason]) => reason);
-
-  return {
-    repoSafety,
-    shouldBlock: reasons.length > 0,
-    reasons,
-  };
+  return getRepoMutationSafety();
 };
 
 const resolveSessionId = (sessionId, activeSessionId) => {
@@ -190,6 +180,7 @@ export const smartMetrics = async ({
   latest = 10,
 }) => {
   const resolved = resolveMetricsInput({ file });
+  const preflightStorageHealth = resolved.kind === 'sqlite' ? getStateStorageHealth({ filePath: resolved.storagePath }) : null;
 
   if (resolved.kind === 'file') {
     const { entries, invalidLines } = readMetricsEntries(resolved.storagePath);
@@ -200,12 +191,10 @@ export const smartMetrics = async ({
 
     const adoption = analyzeAdoption(filteredEntries);
     
-    return {
+    return attachSafetyMetadata({
       filePath: resolved.storagePath,
       storagePath: resolved.storagePath,
       source: resolved.source,
-      repoSafety: null,
-      sideEffectsSuppressed: false,
       activeSessionId: null,
       filters: {
         tool: tool ?? null,
@@ -216,10 +205,37 @@ export const smartMetrics = async ({
       invalidLines,
       summary: aggregateMetrics(filteredEntries),
       adoption,
+      productQuality: analyzeProductQuality(filteredEntries),
       latestEntries: buildLatestEntries(filteredEntries, latest),
-    };
+    }, {
+      repoSafety: null,
+      sideEffectsSuppressed: false,
+      subject: 'Project-local metrics writes',
+    });
   }
 
+  const sqliteResult = await (async () => {
+    try {
+      return await readSqliteMetricsEntries({
+        tool,
+        sessionId,
+        window,
+      });
+    } catch (error) {
+      const storageHealth = error.storageHealth ?? await diagnoseStateStorage({ filePath: resolved.storagePath });
+      return {
+        entries: [],
+        activeSessionId: null,
+        resolvedSessionId: resolveSessionId(sessionId, null),
+        invalidLines: [],
+        repoSafety: getRepoSafety(),
+        sideEffectsSuppressed: false,
+        error,
+        storageHealth,
+      };
+    }
+  })();
+
   const {
     entries,
     activeSessionId,
@@ -227,20 +243,16 @@ export const smartMetrics = async ({
     invalidLines,
     repoSafety,
     sideEffectsSuppressed,
-  } = await readSqliteMetricsEntries({
-    tool,
-    sessionId,
-    window,
-  });
+    error,
+    storageHealth,
+  } = sqliteResult;
 
   const adoption = analyzeAdoption(entries);
-  
-  return {
+
+  return attachSafetyMetadata({
     filePath: resolved.storagePath,
     storagePath: resolved.storagePath,
     source: resolved.source,
-    repoSafety,
-    sideEffectsSuppressed,
     activeSessionId,
     filters: {
       tool: tool ?? null,
@@ -251,6 +263,18 @@ export const smartMetrics = async ({
     invalidLines,
     summary: aggregateMetrics(entries),
     adoption,
+    productQuality: analyzeProductQuality(entries),
     latestEntries: buildLatestEntries(entries, latest),
-  };
+    storageHealth: storageHealth ?? (sideEffectsSuppressed
+      ? await diagnoseStateStorage({ filePath: resolved.storagePath })
+      : (preflightStorageHealth ?? null)),
+    ...(error ? { error: error.message } : {}),
+  }, {
+    repoSafety,
+    sideEffectsSuppressed,
+    subject: 'Project-local metrics writes',
+    degradedReason: 'repo_safety_blocked',
+    degradedMode: 'snapshot_metrics_read',
+    degradedImpact: 'Metrics writes and maintenance side effects are paused while git hygiene is blocked.',
+  });
 };

package/src/tools/smart-status.js

@@ -1,4 +1,12 @@
-import { withStateDb } from '../storage/sqlite.js';
+import { getRepoMutationSafety } from '../repo-safety.js';
+import {
+  diagnoseStateStorage,
+  getStateStorageHealth,
+  importLegacyState,
+  withStateDb,
+  withStateDbSnapshot,
+} from '../storage/sqlite.js';
+import { attachSafetyMetadata } from '../utils/mutation-safety.js';
 import { recordToolUsage } from '../usage-feedback.js';
 import { recordDecision, DECISION_REASONS, EXPECTED_BENEFITS } from '../decision-explainer.js';
 import { recordDevctxOperation } from '../missed-opportunities.js';
@@ -7,7 +15,15 @@ import { countTokens } from '../tokenCounter.js';
 const ACTIVE_SESSION_SCOPE = 'active';
 
 const getActiveSession = async () => {
-  return withStateDb((db) => {
+  const mutationSafety = getRepoMutationSafety();
+  const allowReadSideEffects = !mutationSafety.shouldBlock;
+  const reader = allowReadSideEffects ? withStateDb : withStateDbSnapshot;
+
+  if (allowReadSideEffects) {
+    await importLegacyState();
+  }
+
+  const session = await reader((db) => {
     let activeSessionId = db.prepare(`
       SELECT session_id
       FROM active_session
@@ -63,7 +79,13 @@ const getActiveSession = async () => {
       touchedFilesCount: row.touched_files_count || 0,
       updatedAt: row.updated_at,
     };
-  });
+  }, allowReadSideEffects ? undefined : {});
+
+  return {
+    session,
+    repoSafety: mutationSafety.repoSafety,
+    sideEffectsSuppressed: !allowReadSideEffects,
+  };
 };
 
 const formatContextItem = (item, index, total) => {
@@ -89,6 +111,7 @@ const compactPath = (filePath) => {
 
 export const smartStatus = async ({ format = 'detailed', maxItems = 10 } = {}) => {
   const startTime = Date.now();
+  const preflightStorageHealth = getStateStorageHealth();
 
   recordDecision({
     tool: 'smart_status',
@@ -98,14 +121,54 @@ export const smartStatus = async ({ format = 'detailed', maxItems = 10 } = {}) =
 
   recordDevctxOperation('smart_status');
 
-  const session = await getActiveSession();
+  let sessionResult;
+  try {
+    sessionResult = await getActiveSession();
+  } catch (error) {
+    const storageHealth = error.storageHealth ?? await diagnoseStateStorage();
+    const response = attachSafetyMetadata({
+      success: false,
+      message: storageHealth.message,
+      hint: storageHealth.recommendedActions?.[0] ?? 'Inspect .devctx/state.sqlite before retrying.',
+      storageHealth,
+      error: error.message,
+    }, {
+      repoSafety: getRepoMutationSafety().repoSafety,
+      sideEffectsSuppressed: false,
+      subject: 'Project-local context writes',
+      degradedReason: 'storage_unavailable',
+      degradedMode: 'storage_error',
+      degradedImpact: 'Persistent session state could not be opened.',
+    });
+
+    recordToolUsage({
+      tool: 'smart_status',
+      rawTokens: 0,
+      compressedTokens: countTokens(JSON.stringify(response)),
+      savedTokens: 0,
+      savingsPct: 0,
+    });
+
+    return response;
+  }
+
+  const { session, repoSafety, sideEffectsSuppressed } = sessionResult;
+  const storageHealth = sideEffectsSuppressed ? await diagnoseStateStorage() : preflightStorageHealth;
 
   if (!session) {
-    const response = {
+    const response = attachSafetyMetadata({
       success: false,
       message: 'No active session found',
       hint: 'Use smart_summary with action=update to create a session',
-    };
+      storageHealth,
+    }, {
+      repoSafety,
+      sideEffectsSuppressed,
+      subject: 'Project-local context writes',
+      degradedReason: 'repo_safety_blocked',
+      degradedMode: 'read_only_snapshot',
+      degradedImpact: 'Session-maintenance side effects are paused while git hygiene is blocked.',
+    });
 
     recordToolUsage({
       tool: 'smart_status',
@@ -135,6 +198,7 @@ export const smartStatus = async ({ format = 'detailed', maxItems = 10 } = {}) =
         files: session.touchedFilesCount,
       },
       recentFiles: recentFiles.slice(-3),
+      storageHealth,
       updatedAt: session.updatedAt,
     };
   } else {
@@ -182,6 +246,7 @@ export const smartStatus = async ({ format = 'detailed', maxItems = 10 } = {}) =
         pinned: session.pinnedContext,
         questions: session.unresolvedQuestions,
       },
+      storageHealth,
       updatedAt: session.updatedAt,
     };
   }
@@ -197,5 +262,12 @@ export const smartStatus = async ({ format = 'detailed', maxItems = 10 } = {}) =
     savingsPct: 0,
   });
 
-  return output;
+  return attachSafetyMetadata(output, {
+    repoSafety,
+    sideEffectsSuppressed,
+    subject: 'Project-local context writes',
+    degradedReason: 'repo_safety_blocked',
+    degradedMode: 'read_only_snapshot',
+    degradedImpact: 'Session-maintenance side effects are paused while git hygiene is blocked.',
+  });
 };