smart-context-mcp 1.4.0 → 1.6.0

package/src/tools/smart-summary.js

@@ -1,6 +1,7 @@
 import { countTokens } from '../tokenCounter.js';
 import { persistMetrics } from '../metrics.js';
-import { enforceRepoSafety, getRepoSafety } from '../repo-safety.js';
+import { getRepoMutationSafety, getRepoSafety } from '../repo-safety.js';
+import { attachSafetyMetadata, buildMutationSafety } 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';
@@ -9,6 +10,7 @@ import {
   SQLITE_SCHEMA_VERSION,
   cleanupLegacyState,
   compactState,
+  getStateStorageHealth,
   importLegacyState,
   withStateDb,
   withStateDbSnapshot,
@@ -105,11 +107,6 @@ const CHECKPOINT_POLICY_BY_EVENT = {
   },
 };
 const SUMMARY_WRITE_ACTIONS = new Set(['update', 'append', 'auto_append', 'checkpoint', 'reset', 'compact']);
-const HARD_BLOCK_REPO_SAFETY_REASONS = [
-  ['tracked', 'isTracked'],
-  ['staged', 'isStaged'],
-];
-
 const getTimestamp = (value, fallback = Date.now()) => {
   const parsed = Date.parse(value ?? '');
   return Number.isFinite(parsed) ? parsed : fallback;
@@ -974,22 +971,21 @@ const buildResumeCandidates = (sessions) =>
     isStale: session.isStale,
   }));
 
-const addRepoSafety = (result, repoSafety = getRepoSafety()) => ({
-  ...result,
-  repoSafety,
-});
+const addRepoSafety = (result, repoSafety = getRepoSafety(), sideEffectsSuppressed = false) =>
+  attachSafetyMetadata({
+    ...result,
+    storageHealth: getStateStorageHealth(),
+  }, {
+    repoSafety,
+    sideEffectsSuppressed,
+    subject: 'Project-local context writes',
+    degradedReason: 'repo_safety_blocked',
+    degradedMode: 'read_only_snapshot',
+    degradedImpact: 'Checkpoint maintenance side effects are paused while git hygiene is blocked.',
+  });
 
 const getMutationSafetyPolicy = () => {
-  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 buildMutationBlockedMessage = (reasons, stateDbPath = '.devctx/state.sqlite') => {
@@ -1008,15 +1004,20 @@ const buildMutationBlockedMessage = (reasons, stateDbPath = '.devctx/state.sqlit
   return `Refused to mutate project-local context because ${stateDbPath} failed runtime safety checks.`;
 };
 
-const buildMutationBlockedResponse = ({ action, sessionId, repoSafety, reasons }) =>
-  addRepoSafety({
+const buildMutationBlockedResponse = ({ action, sessionId, repoSafety, reasons }) => {
+  const mutationSafety = buildMutationSafety(repoSafety, {
+    subject: 'Project-local context writes',
+  });
+
+  return addRepoSafety({
     action,
     sessionId: sessionId ?? null,
     blocked: true,
     mutationBlocked: true,
-    blockedBy: reasons,
+    blockedBy: mutationSafety?.blockedBy ?? reasons,
     message: buildMutationBlockedMessage(reasons, repoSafety.stateDbPath ?? '.devctx/state.sqlite'),
   }, repoSafety);
+};
 
 const resolveAutoResumeTarget = (db, { forceRecommended = false, cleanup = true } = {}) => {
   const sessions = listSessions(db, { cleanup });
@@ -1158,7 +1159,7 @@ export const smartSummary = async ({
         activeSessionId,
         totalSessions: sessions.length,
         staleSessions: sessions.filter((session) => session.isStale).length,
-      });
+      }, mutationSafety.repoSafety, !allowReadSideEffects);
     }, allowReadSideEffects ? undefined : {});
   }
 
@@ -1194,7 +1195,7 @@ export const smartSummary = async ({
             candidates: resolution.candidates,
             recommendedSessionId: resolution.recommendedSessionId,
             message: resolution.message,
-          });
+          }, mutationSafety.repoSafety, suppressReadSideEffects);
         }
 
         targetSessionId = resolution.sessionId;
@@ -1207,7 +1208,7 @@ export const smartSummary = async ({
           sessionId: null,
           found: false,
           message: 'No active session found. Use action=update to create one.',
-        });
+        }, mutationSafety.repoSafety, suppressReadSideEffects);
       }
 
       const session = hydrateSession(getSessionRow(db, targetSessionId));
@@ -1217,7 +1218,7 @@ export const smartSummary = async ({
           sessionId: targetSessionId,
           found: false,
           message: 'Session not found.',
-        });
+        }, mutationSafety.repoSafety, suppressReadSideEffects);
       }
 
       if (resumeMeta?.autoResumed && allowReadSideEffects) {
@@ -1277,10 +1278,9 @@ export const smartSummary = async ({
         ambiguous: resumeMeta?.ambiguous ?? false,
         recommendedSessionId: resumeMeta?.recommendedSessionId ?? targetSessionId,
         ...(resumeMeta?.candidates ? { candidates: resumeMeta.candidates } : {}),
-        ...(suppressReadSideEffects ? { sideEffectsSuppressed: true } : {}),
         schemaVersion: session.schemaVersion ?? 1,
         updatedAt: session.updatedAt,
-      });
+      }, mutationSafety.repoSafety, suppressReadSideEffects);
     }, allowReadSideEffects ? undefined : {});
   }
 

package/src/tools/smart-turn.js

@@ -1,10 +1,27 @@
+import { buildIndexIncremental, persistIndex } from '../index.js';
+import { projectRoot } from '../utils/runtime-config.js';
+import {
+  autoTrackWorkflow,
+  endWorkflow,
+  getActiveWorkflowForSession,
+  isWorkflowTrackingEnabled,
+} from '../workflow-tracker.js';
+import { persistMetrics } from '../metrics.js';
+import { PRODUCT_QUALITY_ANALYTICS_KIND } from '../analytics/product-quality.js';
+import { attachSafetyMetadata, buildMutationSafety } from '../utils/mutation-safety.js';
+import { smartContext } from './smart-context.js';
 import { smartMetrics } from './smart-metrics.js';
 import { smartSummary } from './smart-summary.js';
 
 const DEFAULT_START_MAX_TOKENS = 400;
 const DEFAULT_END_MAX_TOKENS = 500;
 const DEFAULT_END_EVENT = 'milestone';
+const DEFAULT_REFRESH_CONTEXT_MAX_TOKENS = 1400;
 const MAX_PROMPT_PREVIEW = 160;
+const REFRESHED_CONTEXT_FILE_LIMIT = 3;
+const SAFE_CONTINUITY_STATES = new Set(['aligned', 'resume']);
+const WORKFLOW_END_EVENTS = new Set(['milestone', 'task_complete', 'session_end', 'blocker']);
+const INDEX_REFRESH_STATES = new Set(['stale', 'unavailable']);
 const STOP_WORDS = new Set([
   'the', 'and', 'for', 'with', 'that', 'this', 'from', 'into', 'when', 'where',
   'what', 'have', 'will', 'your', 'about', 'there', 'their', 'then', 'than',
@@ -71,14 +88,24 @@ const summarizeMetrics = (metrics) => {
     count: metrics.summary.count,
     savedTokens: metrics.summary.savedTokens,
     savingsPct: metrics.summary.savingsPct,
+    netSavedTokens: metrics.summary.netSavedTokens,
+    netSavingsPct: metrics.summary.netSavingsPct,
+    overheadTokens: metrics.summary.overheadTokens,
     topTools: metrics.summary.tools.slice(0, 3).map((tool) => ({
       tool: tool.tool,
       savedTokens: tool.savedTokens,
+      netSavedTokens: tool.netSavedTokens,
       count: tool.count,
     })),
   };
 };
 
+const buildRecommendedStep = (tool, instruction, priority = 'recommended') => ({
+  tool,
+  instruction,
+  priority,
+});
+
 const classifyContinuity = ({ prompt, summaryResult }) => {
   if (!summaryResult?.found) {
     if (summaryResult?.ambiguous) {
@@ -163,6 +190,236 @@ const buildAutoCreateUpdate = (prompt) => ({
   nextStep: 'Inspect relevant code, confirm the task boundaries, and checkpoint the first milestone.',
 });
 
+const summarizeRefreshedContext = (result, { indexRefreshed = false } = {}) => {
+  if (!result?.success) {
+    return null;
+  }
+
+  return {
+    indexFreshness: result.indexFreshness ?? 'unavailable',
+    indexRefreshed,
+    graphCoverage: result.graphCoverage ?? result.confidence?.graphCoverage ?? null,
+    hints: Array.isArray(result.hints) ? result.hints.slice(0, 2) : [],
+    topFiles: Array.isArray(result.context)
+      ? result.context.slice(0, REFRESHED_CONTEXT_FILE_LIMIT).map((item) => ({
+          file: item.file,
+          role: item.role,
+          readMode: item.readMode ?? null,
+          reasonIncluded: item.reasonIncluded ?? null,
+          symbols: Array.isArray(item.symbols) ? item.symbols.slice(0, 3) : [],
+        }))
+      : [],
+  };
+};
+
+const refreshPromptContext = async (prompt) => {
+  if (!hasMeaningfulPrompt(prompt)) {
+    return null;
+  }
+
+  const buildContext = async () => smartContext({
+    task: prompt,
+    detail: 'minimal',
+    include: ['hints'],
+    maxTokens: DEFAULT_REFRESH_CONTEXT_MAX_TOKENS,
+  });
+
+  let result = await buildContext();
+  let indexRefreshed = false;
+
+  if (INDEX_REFRESH_STATES.has(result?.indexFreshness ?? '')) {
+    try {
+      const { index } = buildIndexIncremental(projectRoot);
+      await persistIndex(index, projectRoot);
+      indexRefreshed = true;
+      result = await buildContext();
+    } catch {
+      // best-effort refresh only
+    }
+  }
+
+  return summarizeRefreshedContext(result, { indexRefreshed });
+};
+
+const shouldIsolateSession = ({ sessionId, ensureSession, prompt, continuity }) =>
+  !sessionId
+  && ensureSession
+  && hasMeaningfulPrompt(prompt)
+  && continuity
+  && !SAFE_CONTINUITY_STATES.has(continuity.state ?? '');
+
+const shouldRefreshContext = ({ prompt, ensureSession, summaryResult, continuity, isolatedSession, autoCreated }) =>
+  hasMeaningfulPrompt(prompt)
+  && (
+    isolatedSession
+    || autoCreated
+    || (ensureSession && (summaryResult?.ambiguous || !summaryResult?.found))
+    || ['possible_shift', 'context_mismatch'].includes(continuity?.state)
+  );
+
+const buildStartRecommendedPath = ({
+  prompt,
+  ensureSession,
+  summaryResult,
+  continuity,
+  refreshedContext,
+  mutationSafety,
+  autoCreated,
+  isolatedSession,
+}) => {
+  const nextTools = [];
+  const steps = [];
+
+  if (mutationSafety?.blocked) {
+    nextTools.push('repo_safety', 'smart_search', 'smart_read');
+    steps.push(buildRecommendedStep(
+      'repo_safety',
+      'Pause persisted-write workflows, surface blockedBy, and follow recommendedActions before retrying checkpoints or workflow tracking.',
+      'required',
+    ));
+    steps.push(buildRecommendedStep(
+      'smart_search',
+      'Continue with read-only exploration until repo safety is fixed.',
+      'recommended',
+    ));
+  } else if (refreshedContext?.topFiles?.length) {
+    nextTools.push('smart_read', 'smart_turn');
+    steps.push(buildRecommendedStep(
+      'smart_read',
+      'Start from refreshedContext.topFiles with smart_read(outline|signatures|symbol) before any full reads.',
+    ));
+  } else if (hasMeaningfulPrompt(prompt)) {
+    nextTools.push('smart_context', 'smart_read', 'smart_turn');
+    steps.push(buildRecommendedStep(
+      'smart_context',
+      'Build focused multi-file context with smart_context(...) or smart_search(intent=...) before opening more files.',
+    ));
+    steps.push(buildRecommendedStep(
+      'smart_read',
+      'Use smart_read(outline|signatures|symbol) as the default follow-up read path.',
+    ));
+  } else {
+    nextTools.push('smart_search', 'smart_read');
+    steps.push(buildRecommendedStep(
+      'smart_search',
+      'Stay lightweight: only use devctx search/read if the task grows beyond a trivial lookup.',
+    ));
+  }
+
+  if (summaryResult?.ambiguous && summaryResult?.recommendedSessionId) {
+    nextTools.unshift('smart_turn');
+    steps.unshift(buildRecommendedStep(
+      'smart_turn',
+      `Reuse or pass sessionId=${summaryResult.recommendedSessionId} if you want to resume the recommended persisted session explicitly.`,
+      'required',
+    ));
+  }
+
+  if (!mutationSafety?.blocked) {
+    nextTools.push('smart_turn');
+    steps.push(buildRecommendedStep(
+      'smart_turn',
+      'Checkpoint with smart_turn(end, event=milestone) after the first meaningful progress point.',
+    ));
+  }
+
+  return {
+    phase: 'start',
+    mode: mutationSafety?.blocked
+      ? 'blocked_guided'
+      : refreshedContext
+        ? 'guided_refresh'
+        : hasMeaningfulPrompt(prompt)
+          ? 'guided_context'
+          : 'lightweight',
+    contextSource: refreshedContext
+      ? 'refreshed_context'
+      : continuity?.shouldReuseContext
+        ? 'persisted_summary'
+        : 'direct_prompt',
+    continuityState: continuity?.state ?? null,
+    ensureSessionRecommended: Boolean(hasMeaningfulPrompt(prompt) && (ensureSession || !summaryResult?.found)),
+    autoCreated,
+    isolatedSession,
+    nextTools: [...new Set(nextTools)],
+    steps,
+  };
+};
+
+const buildEndRecommendedPath = ({ event, checkpoint, mutationSafety, workflow }) => {
+  const nextTools = [];
+  const steps = [];
+
+  if (mutationSafety?.blocked) {
+    nextTools.push('repo_safety', 'smart_search', 'smart_read');
+    steps.push(buildRecommendedStep(
+      'repo_safety',
+      'Fix repo safety before expecting checkpoints, workflow tracking, or hook state writes to persist.',
+      'required',
+    ));
+  } else if (checkpoint?.skipped) {
+    nextTools.push('smart_turn');
+    steps.push(buildRecommendedStep(
+      'smart_turn',
+      'No durable checkpoint was written; keep working and call smart_turn(end, event=milestone) once you have a concrete milestone or next step.',
+      'required',
+    ));
+  } else {
+    nextTools.push('smart_turn');
+    steps.push(buildRecommendedStep(
+      'smart_turn',
+      'On the next substantial prompt, restart with smart_turn(start, prompt, ensureSession=true) to reuse this checkpoint cleanly.',
+    ));
+  }
+
+  if (workflow?.ended) {
+    nextTools.push('smart_turn');
+    steps.push(buildRecommendedStep(
+      'smart_turn',
+      'This workflow is closed; start a fresh turn for the next substantial task boundary.',
+    ));
+  }
+
+  return {
+    phase: 'end',
+    mode: mutationSafety?.blocked
+      ? 'blocked_guided'
+      : checkpoint?.skipped
+        ? 'continue_until_milestone'
+        : 'checkpointed',
+    checkpointEvent: event,
+    nextTools: [...new Set(nextTools)],
+    steps,
+  };
+};
+
+const persistSmartTurnQualityMetrics = async ({
+  phase,
+  sessionId,
+  target,
+  action,
+  latencyMs,
+  metadata,
+}) => {
+  await persistMetrics({
+    tool: 'smart_turn',
+    action,
+    sessionId,
+    target,
+    rawTokens: 0,
+    compressedTokens: 0,
+    savedTokens: 0,
+    savingsPct: 0,
+    latencyMs,
+    metadata: {
+      analyticsKind: PRODUCT_QUALITY_ANALYTICS_KIND,
+      phase,
+      ...metadata,
+    },
+    timestamp: new Date().toISOString(),
+  });
+};
+
 const startTurn = async ({
   sessionId,
   prompt,
@@ -172,6 +429,7 @@ const startTurn = async ({
   metricsWindow = '7d',
   latestMetrics = 5,
 } = {}) => {
+  const startTime = Date.now();
   let summaryResult = await smartSummary({
     action: 'get',
     sessionId,
@@ -179,6 +437,8 @@ const startTurn = async ({
   });
 
   let autoCreated = false;
+  let isolatedSession = false;
+  let previousSessionId = null;
   if (!summaryResult.found && !summaryResult.ambiguous && ensureSession && hasMeaningfulPrompt(prompt)) {
     const created = await smartSummary({
       action: 'update',
@@ -195,8 +455,69 @@ const startTurn = async ({
     }
   }
 
-  const continuity = classifyContinuity({ prompt, summaryResult });
+  let continuity = classifyContinuity({ prompt, summaryResult });
+
+  if (summaryResult.found && shouldIsolateSession({ sessionId, ensureSession, prompt, continuity })) {
+    const created = await smartSummary({
+      action: 'update',
+      update: buildAutoCreateUpdate(prompt),
+      maxTokens,
+    });
+
+    if (!created.blocked) {
+      isolatedSession = true;
+      previousSessionId = summaryResult.sessionId ?? null;
+      summaryResult = await smartSummary({
+        action: 'get',
+        sessionId: created.sessionId,
+        maxTokens,
+      });
+      continuity = classifyContinuity({ prompt, summaryResult });
+    }
+  }
+
   const effectiveSessionId = summaryResult.sessionId ?? sessionId ?? summaryResult.recommendedSessionId ?? null;
+  const mutationSafety = buildMutationSafety(summaryResult.repoSafety);
+  const workflowBlocked = Boolean(isWorkflowTrackingEnabled() && mutationSafety?.blocked);
+  const refreshedContext = shouldRefreshContext({
+    prompt,
+    ensureSession,
+    summaryResult,
+    continuity,
+    isolatedSession,
+    autoCreated,
+  })
+    ? await refreshPromptContext(prompt)
+    : null;
+
+  let workflow = null;
+  if (workflowBlocked) {
+    workflow = { enabled: true, blocked: true, workflowId: null, workflowType: null, autoTracked: false };
+  } else if (effectiveSessionId && isWorkflowTrackingEnabled()) {
+    const workflowId = await autoTrackWorkflow(
+      effectiveSessionId,
+      summaryResult.summary?.goal ?? prompt ?? '',
+    );
+    if (workflowId) {
+      const activeWorkflow = await getActiveWorkflowForSession(effectiveSessionId);
+      workflow = activeWorkflow
+        ? {
+            enabled: true,
+            workflowId: activeWorkflow.workflow_id,
+            workflowType: activeWorkflow.workflow_type,
+            autoTracked: true,
+          }
+        : {
+            enabled: true,
+            workflowId,
+            workflowType: null,
+            autoTracked: true,
+          };
+    } else {
+      workflow = { enabled: true, workflowId: null, workflowType: null, autoTracked: false };
+    }
+  }
+
   const metrics = includeMetrics
     ? await smartMetrics({
         window: metricsWindow,
@@ -205,26 +526,76 @@ const startTurn = async ({
       })
     : null;
 
+  const recommendedPath = buildStartRecommendedPath({
+    prompt,
+    ensureSession,
+    summaryResult,
+    continuity,
+    refreshedContext,
+    mutationSafety,
+    autoCreated,
+    isolatedSession,
+  });
 
-  return {
+  await persistSmartTurnQualityMetrics({
+    phase: 'start',
+    sessionId: effectiveSessionId ?? null,
+    target: truncate(prompt, 120) || 'smart_turn:start',
+    action: 'start',
+    latencyMs: Date.now() - startTime,
+    metadata: {
+      continuityState: continuity?.state ?? null,
+      shouldReuseContext: Boolean(continuity?.shouldReuseContext),
+      sessionFound: Boolean(summaryResult.found),
+      ambiguousResume: Boolean(summaryResult.ambiguous),
+      autoCreated,
+      isolatedSession,
+      previousSessionId,
+      mutationBlocked: Boolean(mutationSafety?.blocked),
+      blockedBy: mutationSafety?.blockedBy ?? [],
+      recommendedActionsCount: mutationSafety?.recommendedActions?.length ?? 0,
+      refreshedContext: Boolean(refreshedContext),
+      refreshedTopFiles: refreshedContext?.topFiles?.length ?? 0,
+      indexRefreshed: Boolean(refreshedContext?.indexRefreshed),
+      recommendedPathMode: recommendedPath.mode,
+      nextToolsCount: recommendedPath.nextTools.length,
+      workflowEnabled: Boolean(workflow?.enabled),
+      workflowAutoTracked: Boolean(workflow?.autoTracked),
+    },
+  });
+
+  return attachSafetyMetadata({
     phase: 'start',
     promptPreview: truncate(prompt, MAX_PROMPT_PREVIEW),
     sessionId: effectiveSessionId,
     found: summaryResult.found ?? false,
     autoCreated,
+    isolatedSession,
+    ...(previousSessionId ? { previousSessionId } : {}),
     continuity,
     summary: summaryResult.summary ?? null,
-    repoSafety: summaryResult.repoSafety ?? metrics?.repoSafety ?? null,
-    sideEffectsSuppressed: Boolean(summaryResult.sideEffectsSuppressed ?? metrics?.sideEffectsSuppressed),
+    ...(refreshedContext ? { refreshedContext } : {}),
+    ...(workflow ? { workflow } : {}),
     ...(summaryResult.candidates ? { candidates: summaryResult.candidates } : {}),
     ...(summaryResult.recommendedSessionId ? { recommendedSessionId: summaryResult.recommendedSessionId } : {}),
     ...(metrics ? { metrics: summarizeMetrics(metrics) } : {}),
-    message: summaryResult.found
-      ? continuity.reason
-      : autoCreated
-        ? 'Created a new persisted session for this task prompt.'
-        : continuity.reason,
-  };
+    storageHealth: summaryResult.storageHealth ?? metrics?.storageHealth ?? null,
+    recommendedPath,
+    message: mutationSafety?.blocked
+      ? mutationSafety.message
+      : summaryResult.found
+        ? continuity.reason
+        : autoCreated
+          ? 'Created a new persisted session for this task prompt.'
+          : continuity.reason,
+  }, {
+    repoSafety: summaryResult.repoSafety ?? metrics?.repoSafety ?? null,
+    sideEffectsSuppressed: Boolean(summaryResult.sideEffectsSuppressed ?? metrics?.sideEffectsSuppressed),
+    subject: 'Project-local context writes',
+    degradedReason: 'repo_safety_blocked',
+    degradedMode: 'read_only_snapshot',
+    degradedImpact: 'Checkpoint and workflow side effects are paused while git hygiene is blocked.',
+  });
 };
 
 const endTurn = async ({
@@ -237,6 +608,7 @@ const endTurn = async ({
   metricsWindow = '7d',
   latestMetrics = 5,
 } = {}) => {
+  const startTime = Date.now();
   const checkpoint = await smartSummary({
     action: 'checkpoint',
     sessionId,
@@ -247,6 +619,39 @@ const endTurn = async ({
   });
 
   const effectiveSessionId = checkpoint.sessionId ?? sessionId ?? 'active';
+  const mutationSafety = buildMutationSafety(checkpoint.repoSafety);
+  const workflowBlocked = Boolean(isWorkflowTrackingEnabled() && mutationSafety?.blocked);
+  let workflow = null;
+  if (workflowBlocked) {
+    workflow = { enabled: true, blocked: true, workflowId: null, workflowType: null, ended: false };
+  } else if (
+    checkpoint.sessionId
+    && !checkpoint.skipped
+    && WORKFLOW_END_EVENTS.has(event)
+    && isWorkflowTrackingEnabled()
+  ) {
+    const activeWorkflow = await getActiveWorkflowForSession(checkpoint.sessionId);
+    if (activeWorkflow?.workflow_id) {
+      const endedWorkflow = await endWorkflow(activeWorkflow.workflow_id);
+      workflow = endedWorkflow
+        ? {
+            enabled: true,
+            workflowId: endedWorkflow.workflowId,
+            workflowType: endedWorkflow.workflowType,
+            ended: true,
+            summary: endedWorkflow,
+          }
+        : {
+            enabled: true,
+            workflowId: activeWorkflow.workflow_id,
+            workflowType: activeWorkflow.workflow_type,
+            ended: false,
+          };
+    } else {
+      workflow = { enabled: true, workflowId: null, workflowType: null, ended: false };
+    }
+  }
+
   const metrics = includeMetrics
     ? await smartMetrics({
         window: metricsWindow,
@@ -255,15 +660,51 @@ const endTurn = async ({
       })
     : null;
 
-  return {
+  const recommendedPath = buildEndRecommendedPath({
+    event,
+    checkpoint,
+    mutationSafety,
+    workflow,
+  });
+
+  await persistSmartTurnQualityMetrics({
+    phase: 'end',
+    sessionId: checkpoint.sessionId ?? sessionId ?? null,
+    target: event,
+    action: 'end',
+    latencyMs: Date.now() - startTime,
+    metadata: {
+      event,
+      checkpointSkipped: Boolean(checkpoint.skipped),
+      checkpointPersisted: !checkpoint.skipped && !checkpoint.blocked,
+      mutationBlocked: Boolean(mutationSafety?.blocked),
+      blockedBy: mutationSafety?.blockedBy ?? [],
+      recommendedActionsCount: mutationSafety?.recommendedActions?.length ?? 0,
+      recommendedPathMode: recommendedPath.mode,
+      workflowEnabled: Boolean(workflow?.enabled),
+      workflowEnded: Boolean(workflow?.ended),
+      checkpointScore: checkpoint.checkpoint?.score ?? null,
+      checkpointThreshold: checkpoint.checkpoint?.threshold ?? null,
+    },
+  });
+
+  return attachSafetyMetadata({
     phase: 'end',
     sessionId: checkpoint.sessionId ?? sessionId ?? null,
     checkpoint,
+    ...(workflow ? { workflow } : {}),
+    ...(metrics ? { metrics: summarizeMetrics(metrics) } : {}),
+    storageHealth: checkpoint.storageHealth ?? metrics?.storageHealth ?? null,
+    recommendedPath,
+    message: mutationSafety?.blocked ? mutationSafety.message : checkpoint.message,
+  }, {
     repoSafety: checkpoint.repoSafety ?? metrics?.repoSafety ?? null,
     sideEffectsSuppressed: Boolean(checkpoint.sideEffectsSuppressed ?? metrics?.sideEffectsSuppressed),
-    ...(metrics ? { metrics: summarizeMetrics(metrics) } : {}),
-    message: checkpoint.message,
-  };
+    subject: 'Project-local context writes',
+    degradedReason: 'repo_safety_blocked',
+    degradedMode: 'read_only_snapshot',
+    degradedImpact: 'Checkpoint and workflow side effects are paused while git hygiene is blocked.',
+  });
 };
 
 export const smartTurn = async ({