incremnt 0.7.2 → 0.8.0

package/src/sync-service.js

@@ -1,9 +1,29 @@
 import { createHash, randomUUID, timingSafeEqual } from 'node:crypto';
 import { anonymizeAccountId } from './anonymize.js';
+import { formatIncrementScorePrelude } from './score-prelude.js';
+import {
+  askVerificationMetadata,
+  buildAskAnswerRepairContext,
+  safeAskVerificationFallback,
+  shouldRepairAskAnswer,
+  verifyAskAnswer
+} from './ask-answer-verifier.js';
+import {
+  askMissingObservationFollowUpContext,
+  askObservationFollowUpContext,
+  askRoutedContext,
+  buildAskStructuredResponse,
+  coachFactKindsForAskQuestion,
+  normalizeObservationFollowUpIntent,
+  planAskEvidence,
+  sanitizeAskAnswerVerificationReceipt
+} from './ask-coach.js';
 import { capabilities as cliCapabilities, contractVersion, officialCommands } from './contract.js';
-import { executeReadCommand } from './queries.js';
+import { canonicalExerciseName, executeReadCommand } from './queries.js';
 import { sanitizeHistory, detectSystemPromptLeak, stripXMLTagBlocks } from './prompt-security.js';
 import { enrichScoreSnapshots } from './score-context.js';
+import { extractAskProgramDraft } from './program-draft.js';
+import { extractPlanChangeset } from './plan-changeset.js';
 
 const MAX_BODY_BYTES = 10 * 1024 * 1024; // 10 MB
 const DEFAULT_RATE_LIMIT_WINDOW_MS = 60_000;
@@ -15,6 +35,7 @@ const DEFAULT_RATE_LIMIT_RULES = {
   'vitals-summary-ai': 3,
   'checkpoint-summary-ai': 3,
   'ask-ai': 5,
+  'ask-plan': 30,
   'ai-feedback': 60,
   'coach-memory': 30,
   'weekly-checkin-enroll': 10,
@@ -25,6 +46,8 @@ const DEFAULT_RATE_LIMIT_RULES = {
   'coach-observations-current': 30,
   'coach-observations-seen': 30,
   'coach-observations-dismiss': 30,
+  'coach-observations-outcome': 30,
+  'coach-observations-feedback': 30,
   'dev-login': 10,
   'device-start': 20,
   'device-poll': 300,
@@ -102,6 +125,173 @@ const DEFAULT_RATE_LIMIT_RULES = {
   'sync-push-device-register': 30,
   'sync-push-device-revoke': 30
 };
+const ASK_HISTORY_MAX_MESSAGES = 20;
+const ASK_HISTORY_MAX_MESSAGE_LENGTH = 2000;
+const ASK_STRUCTURED_MAX_ITEMS = 10;
+const ASK_STRUCTURED_MAX_STRING_LENGTH = 1000;
+const ASK_STRUCTURED_MAX_JSON_LENGTH = 30000;
+const COACH_OBSERVATION_OUTCOME_STATUSES = new Set(['improved', 'unchanged', 'regressed', 'inconclusive']);
+const COACH_OBSERVATION_FEEDBACK_STATUSES = new Set(['accepted', 'rejected']);
+
+function askStorageString(value, { maxLength = ASK_STRUCTURED_MAX_STRING_LENGTH } = {}) {
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim();
+  if (!trimmed) return null;
+  return trimmed.length > maxLength ? trimmed.slice(0, maxLength) : trimmed;
+}
+
+function askStorageStringArray(value, { maxItems = ASK_STRUCTURED_MAX_ITEMS, maxLength = 240 } = {}) {
+  if (!Array.isArray(value)) return [];
+  return value
+    .map((item) => askStorageString(item, { maxLength }))
+    .filter(Boolean)
+    .slice(0, maxItems);
+}
+
+function evidenceLabel(section, toolName) {
+  const cleaned = String(section || toolName || 'evidence')
+    .replace(/^observation_/, '')
+    .replace(/_/g, ' ')
+    .trim();
+  return cleaned ? cleaned.replace(/\b\w/g, (char) => char.toUpperCase()) : 'Evidence';
+}
+
+// Fold tools the agentic loop fetched at generation time into the routing
+// metadata so toolsUsed, provenance, and the structured evidence list reflect
+// what was actually read (keeps ask_tool_provenance honest). Mutates in place.
+function mergeAgenticToolProvenance(routingMetadata, toolInvocations = []) {
+  if (!routingMetadata || !Array.isArray(toolInvocations) || toolInvocations.length === 0) return;
+  const names = toolInvocations.map((invocation) => invocation.name).filter(Boolean);
+  routingMetadata.toolsUsed = [...new Set([...(routingMetadata.toolsUsed ?? []), ...names])];
+  routingMetadata.toolParams = {
+    ...(routingMetadata.toolParams ?? {}),
+    ...Object.fromEntries(toolInvocations
+      .filter((invocation) => invocation?.name)
+      .map((invocation) => [invocation.name, invocation.params ?? {}]))
+  };
+  if (routingMetadata.evidencePlan && typeof routingMetadata.evidencePlan === 'object') {
+    routingMetadata.evidencePlan = {
+      ...routingMetadata.evidencePlan,
+      executedTools: [...new Set([...(routingMetadata.evidencePlan.executedTools ?? []), ...names])]
+    };
+  }
+  routingMetadata.agenticToolInvocations = toolInvocations.map((invocation) => ({
+    name: invocation.name,
+    params: invocation.params ?? {},
+    sourceIds: invocation.sourceIds ?? []
+  }));
+
+  const provenanceEntries = toolInvocations.map((invocation) => ({
+    section: invocation.name,
+    toolName: invocation.name,
+    sourceIds: invocation.sourceIds ?? []
+  }));
+  routingMetadata.provenance = [...(routingMetadata.provenance ?? []), ...provenanceEntries];
+
+  const contextBundle = routingMetadata.contextBundle;
+  if (contextBundle && typeof contextBundle === 'object') {
+    const evidenceEntries = provenanceEntries.map((entry) => ({
+      label: evidenceLabel(entry.section, entry.toolName),
+      section: entry.section,
+      toolName: entry.toolName,
+      sourceTimestamp: null,
+      sourceIds: entry.sourceIds,
+      noteSourceIds: [],
+      missingDataFlags: []
+    }));
+    routingMetadata.contextBundle = {
+      ...contextBundle,
+      executedTools: [...new Set([...(contextBundle.executedTools ?? []), ...names])],
+      evidenceUsed: [...(contextBundle.evidenceUsed ?? []), ...evidenceEntries]
+    };
+  }
+}
+
+function sanitizeAskEvidenceForStorage(item) {
+  if (!item || typeof item !== 'object' || Array.isArray(item)) return null;
+  const sanitized = {};
+  for (const key of ['label', 'section', 'toolName', 'sourceTimestamp']) {
+    const value = askStorageString(item[key], { maxLength: 240 });
+    if (value) sanitized[key] = value;
+  }
+  for (const key of ['sourceIds', 'noteSourceIds', 'missingDataFlags']) {
+    const values = askStorageStringArray(item[key], { maxItems: ASK_STRUCTURED_MAX_ITEMS, maxLength: 160 });
+    if (values.length > 0) sanitized[key] = values;
+  }
+  return Object.keys(sanitized).length > 0 ? sanitized : null;
+}
+
+function sanitizeAskActionForStorage(item) {
+  if (!item || typeof item !== 'object' || Array.isArray(item)) return null;
+  const id = askStorageString(item.id, { maxLength: 160 });
+  const label = askStorageString(item.label, { maxLength: 240 });
+  const kind = askStorageString(item.kind, { maxLength: 120 });
+  if (!id && !label) return null;
+  return {
+    ...(id ? { id } : {}),
+    label: label ?? id,
+    ...(kind ? { kind } : {})
+  };
+}
+
+function sanitizeAskProgramDraftForStorage(value) {
+  if (value == null) return null;
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  const serialized = JSON.stringify(value);
+  if (serialized.length > ASK_STRUCTURED_MAX_JSON_LENGTH) return null;
+  return JSON.parse(serialized);
+}
+
+function sanitizeAskStructuredResponseForStorage(structured) {
+  if (!structured || typeof structured !== 'object' || Array.isArray(structured)) return null;
+  const confidence = askStorageString(structured.confidence, { maxLength: 40 });
+  const answer = askStorageString(structured.answer);
+  const evidenceUsed = Array.isArray(structured.evidenceUsed)
+    ? structured.evidenceUsed.map(sanitizeAskEvidenceForStorage).filter(Boolean).slice(0, ASK_STRUCTURED_MAX_ITEMS)
+    : [];
+  const recommendedActions = Array.isArray(structured.recommendedActions)
+    ? structured.recommendedActions.map(sanitizeAskActionForStorage).filter(Boolean).slice(0, ASK_STRUCTURED_MAX_ITEMS)
+    : [];
+  const followUpSuggestions = askStorageStringArray(structured.followUpSuggestions, { maxItems: 5, maxLength: 240 });
+  const limitations = askStorageStringArray(structured.limitations, { maxItems: ASK_STRUCTURED_MAX_ITEMS, maxLength: 240 });
+  const answerVerification = sanitizeAskAnswerVerificationReceipt(structured.answerVerification);
+  const programDraft = sanitizeAskProgramDraftForStorage(structured.programDraft);
+
+  return {
+    ...(answer ? { answer } : {}),
+    ...(confidence ? { confidence } : {}),
+    evidenceUsed,
+    recommendedActions,
+    followUpSuggestions,
+    limitations,
+    ...(answerVerification ? { answerVerification } : {}),
+    programDraft
+  };
+}
+
+function sanitizeAskMessagesForStorage(messages, { allowStructured = false } = {}) {
+  if (!Array.isArray(messages)) return [];
+
+  const cleaned = messages
+    .filter((message) => message && ['user', 'assistant'].includes(message.role) && typeof message.content === 'string')
+    .map((message) => {
+      const item = {
+        role: message.role,
+        content: message.content.length > ASK_HISTORY_MAX_MESSAGE_LENGTH
+          ? message.content.slice(0, ASK_HISTORY_MAX_MESSAGE_LENGTH)
+          : message.content
+      };
+      if (allowStructured && message.role === 'assistant') {
+        const structured = sanitizeAskStructuredResponseForStorage(message.structured);
+        if (structured) item.structured = structured;
+      }
+      return item;
+    });
+
+  return cleaned.length > ASK_HISTORY_MAX_MESSAGES
+    ? cleaned.slice(cleaned.length - ASK_HISTORY_MAX_MESSAGES)
+    : cleaned;
+}
 
 export function isNoInsightResponse(text) {
   const normalized = String(text ?? '')
@@ -178,6 +368,42 @@ function isoDateFromParts({ year, month, day }) {
   ].join('-');
 }
 
+function isoDateParts(isoDate) {
+  const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(String(isoDate ?? ''));
+  if (!match) return null;
+  return {
+    year: Number(match[1]),
+    month: Number(match[2]),
+    day: Number(match[3])
+  };
+}
+
+function weeklyCheckinContextOptions(row) {
+  const parts = isoDateParts(row?.weekStartDate);
+  if (!parts) return { now: new Date(`${row?.weekStartDate ?? ''}T23:59:59.999Z`) };
+  const timeZoneId = isValidTimeZone(row?.timezoneId) ? row.timezoneId : 'UTC';
+  const weekStartParts = addCalendarDays(parts, -7);
+  const nextDay = addCalendarDays(parts, 1);
+  const now = new Date(zonedDateTimeToUtc(timeZoneId, {
+    ...nextDay,
+    hour: 0,
+    minute: 0,
+    second: 0
+  }).getTime() - 1);
+  const cutoff = zonedDateTimeToUtc(timeZoneId, {
+    ...weekStartParts,
+    hour: 0,
+    minute: 0,
+    second: 0
+  });
+  return {
+    now,
+    todayIso: isoDateFromParts(parts),
+    weekStartIso: isoDateFromParts(weekStartParts),
+    cutoff
+  };
+}
+
 export function nextWeeklyCheckinSchedule(timeZoneId, now = new Date()) {
   if (!isValidTimeZone(timeZoneId)) {
     const err = new Error('Invalid timezoneId');
@@ -208,196 +434,6 @@ export function nextWeeklyCheckinSchedule(timeZoneId, now = new Date()) {
   };
 }
 
-const PROGRAM_DRAFT_VERSION = 1;
-const VALID_PROGRAM_DRAFT_EQUIPMENT_TIERS = new Set(['fullGym', 'benchDumbbells', 'dumbbellsOnly', 'bodyweightOnly']);
-const VALID_PROGRAM_DRAFT_VOLUME_LEVELS = new Set(['minimum', 'moderate', 'high']);
-
-const PROGRAM_DRAFT_LIMITS = {
-  nameMaxLen: 120,
-  muscleGroupMaxLen: 60,
-  dayLabelMaxLen: 60,
-  dayTitleMaxLen: 120,
-  daySubtitleMaxLen: 120,
-  noteMaxLen: 1000,
-  minWeight: 0,
-  maxWeight: 600,
-  minReps: 1,
-  maxReps: 30,
-  minRir: 0,
-  maxRir: 5,
-  minSetsPerExercise: 1,
-  maxSetsPerExercise: 12,
-  minExercisesPerDay: 1,
-  maxExercisesPerDay: 24,
-  minDaysPerWeek: 1,
-  maxDaysPerWeek: 7,
-  minDays: 1,
-  maxDays: 14
-};
-
-function collapseBlankLines(text) {
-  return String(text ?? '')
-    .replace(/\n{3,}/g, '\n\n')
-    .trim();
-}
-
-function titleCaseExerciseName(name) {
-  return String(name ?? '')
-    .split(' ')
-    .filter(Boolean)
-    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
-    .join(' ');
-}
-
-function normalizedExerciseDisplayName(name, canonicalizeExerciseName) {
-  const trimmed = String(name ?? '').trim();
-  if (!trimmed) return '';
-  const canonical = canonicalizeExerciseName ? canonicalizeExerciseName(trimmed) : trimmed.toLowerCase();
-  return titleCaseExerciseName(canonical);
-}
-
-function normalizeProgramDraftSet(set) {
-  const weight = Number(set?.weight);
-  const reps = Number(set?.reps);
-  if (!Number.isFinite(weight) || !Number.isInteger(reps)) return null;
-  if (
-    weight < PROGRAM_DRAFT_LIMITS.minWeight ||
-    weight > PROGRAM_DRAFT_LIMITS.maxWeight ||
-    reps < PROGRAM_DRAFT_LIMITS.minReps ||
-    reps > PROGRAM_DRAFT_LIMITS.maxReps
-  ) return null;
-  return {
-    weight,
-    reps,
-    isComplete: false,
-    isWarmup: set?.isWarmup === true
-  };
-}
-
-function normalizeProgramDraftExercise(exercise, canonicalizeExerciseName) {
-  const name = normalizedExerciseDisplayName(exercise?.name, canonicalizeExerciseName);
-  const muscleGroup = String(exercise?.muscleGroup ?? '').trim();
-  const sets = Array.isArray(exercise?.sets)
-    ? exercise.sets.map(normalizeProgramDraftSet).filter(Boolean)
-    : [];
-
-  if (!name || name.length > PROGRAM_DRAFT_LIMITS.nameMaxLen) return null;
-  if (!muscleGroup || muscleGroup.length > PROGRAM_DRAFT_LIMITS.muscleGroupMaxLen) return null;
-  if (
-    sets.length < PROGRAM_DRAFT_LIMITS.minSetsPerExercise ||
-    sets.length > PROGRAM_DRAFT_LIMITS.maxSetsPerExercise
-  ) return null;
-
-  const rir = exercise?.rir == null ? null : Number(exercise.rir);
-  if (rir != null && (
-    !Number.isInteger(rir) ||
-    rir < PROGRAM_DRAFT_LIMITS.minRir ||
-    rir > PROGRAM_DRAFT_LIMITS.maxRir
-  )) return null;
-
-  const note = exercise?.note == null ? null : String(exercise.note);
-  if (note && note.length > PROGRAM_DRAFT_LIMITS.noteMaxLen) return null;
-
-  return {
-    name,
-    muscleGroup,
-    lastSuggestion: '',
-    nextSuggestion: '',
-    sets,
-    ...(note ? { note } : {}),
-    ...(rir != null ? { rir } : {})
-  };
-}
-
-function normalizeProgramDraftDay(day, canonicalizeExerciseName) {
-  const dayLabel = String(day?.dayLabel ?? '').trim();
-  const title = String(day?.title ?? '').trim();
-  const subtitle = String(day?.subtitle ?? '').trim();
-  const exercises = Array.isArray(day?.exercises)
-    ? day.exercises.map((exercise) => normalizeProgramDraftExercise(exercise, canonicalizeExerciseName)).filter(Boolean)
-    : [];
-
-  if (!dayLabel || dayLabel.length > PROGRAM_DRAFT_LIMITS.dayLabelMaxLen) return null;
-  if (!title || title.length > PROGRAM_DRAFT_LIMITS.dayTitleMaxLen) return null;
-  if (subtitle.length > PROGRAM_DRAFT_LIMITS.daySubtitleMaxLen) return null;
-  if (
-    exercises.length < PROGRAM_DRAFT_LIMITS.minExercisesPerDay ||
-    exercises.length > PROGRAM_DRAFT_LIMITS.maxExercisesPerDay
-  ) return null;
-
-  return { dayLabel, title, subtitle, exercises };
-}
-
-function normalizeProgramDraft(rawProgram, { canonicalizeExerciseName } = {}) {
-  if (!rawProgram || typeof rawProgram !== 'object' || Array.isArray(rawProgram)) return null;
-
-  const name = String(rawProgram.name ?? '').trim();
-  const days = Array.isArray(rawProgram.days)
-    ? rawProgram.days.map((day) => normalizeProgramDraftDay(day, canonicalizeExerciseName)).filter(Boolean)
-    : [];
-  const daysPerWeek = Number(rawProgram.daysPerWeek);
-  const currentDayIndex = rawProgram.currentDayIndex == null ? 0 : Number(rawProgram.currentDayIndex);
-  const equipmentTier = String(rawProgram.equipmentTier ?? 'fullGym').trim();
-  const volumeLevel = String(rawProgram.volumeLevel ?? 'moderate').trim();
-
-  if (!name || name.length > PROGRAM_DRAFT_LIMITS.nameMaxLen) return null;
-  if (days.length < PROGRAM_DRAFT_LIMITS.minDays || days.length > PROGRAM_DRAFT_LIMITS.maxDays) return null;
-  if (
-    !Number.isInteger(daysPerWeek) ||
-    daysPerWeek < PROGRAM_DRAFT_LIMITS.minDaysPerWeek ||
-    daysPerWeek > PROGRAM_DRAFT_LIMITS.maxDaysPerWeek
-  ) return null;
-  if (!Number.isInteger(currentDayIndex) || currentDayIndex < 0 || currentDayIndex >= days.length) return null;
-  if (!VALID_PROGRAM_DRAFT_EQUIPMENT_TIERS.has(equipmentTier) || !VALID_PROGRAM_DRAFT_VOLUME_LEVELS.has(volumeLevel)) return null;
-
-  return {
-    name,
-    daysPerWeek,
-    equipmentTier,
-    volumeLevel,
-    source: 'guided',
-    days,
-    currentDayIndex
-  };
-}
-
-function extractAskProgramDraft(rawText, { canonicalizeExerciseName } = {}) {
-  const text = String(rawText ?? '');
-  const match = text.match(/<program_draft>\s*([\s\S]*?)\s*<\/program_draft>/i);
-  if (!match) {
-    return { answerText: text.trim(), programDraft: null };
-  }
-
-  const answerText = collapseBlankLines(text.replace(match[0], ''));
-  let parsed;
-  try {
-    parsed = JSON.parse(match[1]);
-  } catch (err) {
-    console.warn('askCoach: <program_draft> JSON parse failed — dropping draft:', err.message);
-    return { answerText, programDraft: null };
-  }
-
-  const program = normalizeProgramDraft(parsed, { canonicalizeExerciseName });
-  if (!program) {
-    console.warn('askCoach: <program_draft> payload failed validation — dropping draft');
-    return { answerText, programDraft: null };
-  }
-
-  return {
-    answerText,
-    programDraft: {
-      program,
-      provenance: {
-        source: 'ai-coach',
-        type: 'program',
-        version: PROGRAM_DRAFT_VERSION,
-        createdAt: new Date().toISOString(),
-        tokenHint: null
-      }
-    }
-  };
-}
-
 function json(response, statusCode, payload) {
   response.writeHead(statusCode, { 'content-type': 'application/json' });
   response.end(JSON.stringify(payload));
@@ -514,7 +550,132 @@ function currentAIGitSha() {
     ?? null;
 }
 
+function compactLogObject(obj) {
+  return Object.fromEntries(
+    Object.entries(obj).filter(([, value]) => {
+      if (value === undefined || value === null) return false;
+      if (Array.isArray(value)) return value.length > 0;
+      return true;
+    })
+  );
+}
+
+function logStringArray(values, { max = 12 } = {}) {
+  const unique = [];
+  const seen = new Set();
+  for (const value of Array.isArray(values) ? values : []) {
+    const text = typeof value === 'string' ? value.trim() : '';
+    if (!text || seen.has(text)) continue;
+    seen.add(text);
+    unique.push(text);
+    if (unique.length >= max) break;
+  }
+  return unique;
+}
+
+export function buildAskInteractionLogPayload({
+  accountId = null,
+  status = 'ok',
+  promptSurface = 'ask',
+  routingMetadata = {},
+  askResult = {},
+  structured = {}
+} = {}) {
+  const evidencePlan = routingMetadata?.evidencePlan ?? {};
+  const contextBundle = routingMetadata?.contextBundle ?? {};
+  const missingDataFlags = logStringArray([
+    ...(routingMetadata?.missingDataFlags ?? []),
+    ...(contextBundle?.missingDataFlags ?? []),
+    ...(evidencePlan?.evidenceGaps ?? [])
+  ]);
+  const evidenceUsed = Array.isArray(structured?.evidenceUsed) ? structured.evidenceUsed : [];
+  const recommendedActions = Array.isArray(structured?.recommendedActions) ? structured.recommendedActions : [];
+  const answerVerification = routingMetadata?.answerVerification ?? {};
+
+  return compactLogObject({
+    event: 'ask_coach_interaction',
+    surface: promptSurface,
+    status,
+    aid: accountId ? anonymizeAccountId(accountId) : undefined,
+    model: askResult?.model ?? undefined,
+    durationMs: typeof askResult?.durationMs === 'number' ? askResult.durationMs : undefined,
+    fallback: askResult?.fallback === true ? true : undefined,
+    route: routingMetadata?.route ?? evidencePlan?.route,
+    effectiveRoute: routingMetadata?.effectiveRoute ?? evidencePlan?.effectiveRoute,
+    requestedAction: routingMetadata?.intent?.requestedAction,
+    intentConfidence: typeof routingMetadata?.intent?.confidence === 'number' ? routingMetadata.intent.confidence : undefined,
+    structuredConfidence: typeof structured?.confidence === 'string' ? structured.confidence : undefined,
+    contextCharCount: typeof routingMetadata?.contextCharCount === 'number' ? routingMetadata.contextCharCount : undefined,
+    historyTurnCount: typeof routingMetadata?.historyTurnCount === 'number' ? routingMetadata.historyTurnCount : undefined,
+    requiredTools: logStringArray(evidencePlan?.requiredTools),
+    executedTools: logStringArray(evidencePlan?.executedTools ?? routingMetadata?.toolsUsed ?? contextBundle?.executedTools),
+    evidenceGaps: logStringArray(evidencePlan?.evidenceGaps),
+    missingDataFlags,
+    evidenceUsedLabels: logStringArray(evidenceUsed.map((item) => item?.label)),
+    evidenceUsedTools: logStringArray(evidenceUsed.map((item) => item?.toolName)),
+    recommendedActionIds: logStringArray(recommendedActions.map((item) => item?.id)),
+    recommendedActionLabels: logStringArray(recommendedActions.map((item) => item?.label)),
+    followUpSuggestionCount: Array.isArray(structured?.followUpSuggestions) ? structured.followUpSuggestions.length : undefined,
+    limitationCount: Array.isArray(structured?.limitations) ? structured.limitations.length : undefined,
+    hasProgramDraft: structured?.programDraft != null ? true : undefined,
+    askVerificationStatus: answerVerification.status,
+    askVerificationRetryCount: typeof answerVerification.retryCount === 'number' ? answerVerification.retryCount : undefined,
+    askVerificationBlockingFailureCount: typeof answerVerification.blockingFailureCount === 'number' ? answerVerification.blockingFailureCount : undefined,
+    askVerificationAdvisoryFailureCount: typeof answerVerification.advisoryFailureCount === 'number' ? answerVerification.advisoryFailureCount : undefined,
+    askVerificationFailureKeys: logStringArray(answerVerification.failureKeys),
+    coachFactsIncluded: routingMetadata?.coachFactsIncluded === true ? true : undefined,
+    coachFactCount: Array.isArray(routingMetadata?.includedCoachFactIds)
+      ? routingMetadata.includedCoachFactIds.length
+      : Array.isArray(routingMetadata?.coachFactIds)
+        ? routingMetadata.coachFactIds.length
+        : undefined,
+    coachObservationCount: Array.isArray(routingMetadata?.includedCoachObservationIds)
+      ? routingMetadata.includedCoachObservationIds.length
+      : Array.isArray(routingMetadata?.coachObservationIds)
+        ? routingMetadata.coachObservationIds.length
+        : undefined,
+    langfuseTraceId: askResult?.langfuseTraceId,
+    langfuseObservationId: askResult?.langfuseObservationId
+  });
+}
+
+function shouldRequireProgramDraftForAsk({ persistedKind, requestedCoachObservation, missingRequestedCoachObservation }) {
+  return persistedKind === 'ask' &&
+    requestedCoachObservation?.intent === 'successor_plan' &&
+    !missingRequestedCoachObservation;
+}
+
+function shouldRequirePlanChangesetForAsk({ persistedKind, requestedCoachObservation, missingRequestedCoachObservation }) {
+  return persistedKind === 'ask' &&
+    requestedCoachObservation?.intent === 'plan_adjustment' &&
+    !missingRequestedCoachObservation;
+}
+
+function buildMissingProgramDraftRepairContext(context) {
+  return `${context}
+
+Program draft repair:
+  A program draft was required for this matched successor plan request, but the previous answer only gave prose.
+  Re-answer with 1-2 short prose sentences and exactly one trailing <program_draft>{JSON}</program_draft> block.
+  The JSON must be a complete Program object using the schema already specified above.
+  Do not ask a follow-up question unless the evidence is weak, stale, or contradicted by the tools above.`;
+}
+
+function buildMissingPlanChangesetRepairContext(context) {
+  return `${context}
+
+Plan changeset repair:
+  A plan changeset was required for this matched plan adjustment request, but the previous answer only gave prose.
+  Re-answer with 1-2 short prose sentences and exactly one trailing <plan_changeset>{JSON}</plan_changeset> block.
+  The JSON must use the Plan adjustment request schema already specified above.
+  Do not include concrete weights, reps, set counts, or deltas.
+  Do not ask a follow-up question unless the evidence is weak, stale, or contradicted by the tools above.`;
+}
+
 function buildAIGenerationMetadata(surface, model, promptVersion, generation = {}) {
+  const routing = generation.routingMetadata && typeof generation.routingMetadata === 'object'
+    ? generation.routingMetadata
+    : {};
   return {
     surface,
     generatedAt: new Date().toISOString(),
@@ -522,7 +683,15 @@ function buildAIGenerationMetadata(surface, model, promptVersion, generation = {
     promptVersion: promptVersion ?? null,
     gitSha: currentAIGitSha(),
     langfuseTraceId: generation.langfuseTraceId ?? null,
-    langfuseObservationId: generation.langfuseObservationId ?? null
+    langfuseObservationId: generation.langfuseObservationId ?? null,
+    ...(typeof routing.route === 'string' ? { route: routing.route } : {}),
+    ...(typeof routing.effectiveRoute === 'string' ? { effectiveRoute: routing.effectiveRoute } : {}),
+    ...(typeof routing.observationFollowUpIntent === 'string' ? { observationFollowUpIntent: routing.observationFollowUpIntent } : {}),
+    ...(typeof routing.requestedCoachObservationIntent === 'string' ? { requestedCoachObservationIntent: routing.requestedCoachObservationIntent } : {}),
+    ...(typeof routing.requestedCoachObservationId === 'string' ? { requestedCoachObservationId: routing.requestedCoachObservationId } : {}),
+    ...(Array.isArray(routing.coachObservationIds) && routing.coachObservationIds.length > 0
+      ? { coachObservationIds: routing.coachObservationIds }
+      : {})
   };
 }
 
@@ -588,6 +757,23 @@ function forbidden(response, message = 'Forbidden') {
   json(response, 403, { error: message });
 }
 
+function insufficientScope(response, request, requiredAccess = 'write') {
+  if (request) logRequest(request, 403);
+  json(response, 403, {
+    error: `Insufficient token scope. This endpoint requires ${requiredAccess} access.`,
+    code: 'INSUFFICIENT_SCOPE',
+    requiredAccess
+  });
+}
+
+async function rejectInsufficientScopeForReadToken(response, request, requestToken, readAuthenticator, requiredAccess = 'write') {
+  if (!requestToken || !readAuthenticator) return false;
+  const readAccount = await readAuthenticator(requestToken);
+  if (!readAccount) return false;
+  insufficientScope(response, request, requiredAccess);
+  return true;
+}
+
 function methodNotAllowed(response, message = 'Method not allowed') {
   json(response, 405, { error: message });
 }
@@ -690,6 +876,24 @@ function parseLimit(value, { defaultValue, max }) {
   return Number.isFinite(parsed) && parsed > 0 ? Math.min(parsed, max) : defaultValue;
 }
 
+function coachToolObservationOptions(toolName, body = {}) {
+  if (toolName === 'get_current_coach_observations') {
+    return {
+      limit: parseLimit(body?.limit, { defaultValue: 5, max: 20 }),
+      includeDismissed: Boolean(body?.includeDismissed),
+      includeOutcomeHistory: Boolean(body?.includeOutcomeHistory)
+    };
+  }
+  if (toolName === 'compare_session_to_observations') {
+    return {
+      limit: parseLimit(body?.observationLimit, { defaultValue: 5, max: 20 }),
+      includeDismissed: false,
+      includeOutcomeHistory: Boolean(body?.includeOutcomeHistory)
+    };
+  }
+  return null;
+}
+
 function coachObservationSourceTriggerForScoreSnapshots(snapshots) {
   if (!Array.isArray(snapshots)) return undefined;
   const reasons = snapshots.map((snapshot) => snapshot?.triggerReason);
@@ -717,7 +921,12 @@ function coachObservationGenerationMetadata(result, sourceTrigger) {
 function normalizeAskCoachObservationFollowUp(value) {
   if (!value || typeof value !== 'object') return null;
   const id = String(value.id ?? '').trim();
-  return id ? { id: id.slice(0, 128) } : null;
+  if (!id) return null;
+  const intent = normalizeObservationFollowUpIntent(value.intent);
+  return {
+    id: id.slice(0, 128),
+    ...(intent ? { intent } : {})
+  };
 }
 
 function selectAskCoachObservationFollowUp(requested, observations) {
@@ -726,6 +935,8 @@ function selectAskCoachObservationFollowUp(requested, observations) {
     .find((observation) => String(observation?.id ?? '') === requested.id);
 }
 
+const ASK_REQUESTED_COACH_OBSERVATION_LIMIT = 20;
+
 function routeRequest(url, method) {
   const pathname = url.pathname;
 
@@ -797,6 +1008,22 @@ function routeRequest(url, method) {
     return { command: 'contract', options: {} };
   }
 
+  if (pathname === '/cli/agent-tokens') {
+    return { command: 'agent-tokens', options: {} };
+  }
+
+  {
+    const agentTokenMatch = pathname.match(/^\/cli\/agent-tokens\/([^/]+)$/);
+    if (agentTokenMatch) {
+      return {
+        command: 'agent-token',
+        options: {
+          id: decodeURIComponent(agentTokenMatch[1])
+        }
+      };
+    }
+  }
+
   if (pathname === '/sync/snapshot') {
     return { command: 'sync-upload', options: {} };
   }
@@ -944,11 +1171,34 @@ function routeRequest(url, method) {
     return { command: 'program-detail', options: {} };
   }
 
+  if (pathname === '/cli/programs/progress') {
+    return {
+      command: 'program-progress',
+      options: {
+        'program-id': url.searchParams.get('program-id') ?? undefined,
+        since: url.searchParams.get('since') ?? undefined,
+        limitExercises: url.searchParams.get('limitExercises') ?? undefined
+      }
+    };
+  }
+
   const programShowMatch = pathname.match(/^\/cli\/programs\/([^/]+)$/);
   if (programShowMatch) {
     return { command: 'program-detail', options: { id: programShowMatch[1] } };
   }
 
+  if (pathname === '/cli/exercises/progress') {
+    return {
+      command: 'exercise-progress-summary',
+      options: {
+        name: url.searchParams.get('name') ?? undefined,
+        since: url.searchParams.get('since') ?? undefined,
+        'program-id': url.searchParams.get('program-id') ?? undefined,
+        limit: url.searchParams.get('limit') ?? undefined
+      }
+    };
+  }
+
   if (pathname === '/cli/exercises/history') {
     return {
       command: 'exercise-history',
@@ -980,6 +1230,16 @@ function routeRequest(url, method) {
     };
   }
 
+  if (pathname === '/cli/cycles/progress') {
+    return {
+      command: 'cycle-progression-summary',
+      options: {
+        'program-id': url.searchParams.get('program-id') ?? undefined,
+        limit: url.searchParams.get('limit') ?? undefined
+      }
+    };
+  }
+
   const cyclesShowMatch = pathname.match(/^\/cli\/cycles\/([^/]+)$/);
   if (cyclesShowMatch) {
     return { command: 'cycle-summary-show', options: { id: decodeURIComponent(cyclesShowMatch[1]) } };
@@ -1064,6 +1324,10 @@ function routeRequest(url, method) {
     return { command: 'ask-ai', options: {} };
   }
 
+  if (pathname === '/cli/ask/plan') {
+    return { command: 'ask-plan', options: {} };
+  }
+
   if (pathname === '/cli/ask/history') {
     return { command: 'ask-history', options: { limit: url.searchParams.get('limit') ?? undefined } };
   }
@@ -1110,7 +1374,7 @@ function routeRequest(url, method) {
   }
 
   {
-    const coachObservationActionMatch = pathname.match(/^\/cli\/coach-observations\/([^/]+)\/(seen|dismiss)$/);
+    const coachObservationActionMatch = pathname.match(/^\/cli\/coach-observations\/([^/]+)\/(seen|dismiss|outcome|feedback)$/);
     if (coachObservationActionMatch) {
       return {
         command: `coach-observations-${coachObservationActionMatch[2]}`,
@@ -1141,6 +1405,15 @@ function routeRequest(url, method) {
     return { command: 'training-load', options: {} };
   }
 
+  if (pathname === '/cli/training-profile') {
+    return {
+      command: 'training-profile',
+      options: {
+        since: url.searchParams.get('since') ?? undefined
+      }
+    };
+  }
+
   // --- Social endpoints ---
   if (pathname === '/cli/social/me/profile') {
     return { command: 'social-me-profile', options: {} };
@@ -1505,55 +1778,10 @@ function routeRequest(url, method) {
   return null;
 }
 
-export function formatIncrementScorePrelude(snapshots) {
-  if (!Array.isArray(snapshots) || snapshots.length === 0) return null;
-  const latest = snapshots[0];
-  if (latest == null || typeof latest.score !== 'number') return null;
-
-  const lines = ['[Increment Score]'];
-  const tier = latest.dataTier ? ` · ${latest.dataTier}` : '';
-  lines.push(`- Current: ${latest.score}/100${tier}`);
-
-  if (latest.components && typeof latest.components === 'object') {
-    const parts = [];
-    for (const [name, value] of Object.entries(latest.components)) {
-      const num = typeof value === 'number' ? value : value?.score;
-      if (typeof num === 'number') parts.push(`${name} ${num}`);
-    }
-    if (parts.length > 0) lines.push(`- Components: ${parts.join(', ')}`);
-  }
-
-  const driverLabels = (list) => {
-    if (!Array.isArray(list) || list.length === 0) return null;
-    return list
-      .slice(0, 3)
-      .map((d) => d?.label ?? d?.id ?? d?.driver)
-      .filter(Boolean)
-      .join('; ');
-  };
-  const positives = driverLabels(latest.topPositiveDrivers);
-  if (positives) lines.push(`- Top positive drivers: ${positives}`);
-  const negatives = driverLabels(latest.topNegativeDrivers);
-  if (negatives) lines.push(`- Top negative drivers: ${negatives}`);
-
-  if (snapshots.length > 1) {
-    const prior = snapshots[1];
-    if (typeof prior?.score === 'number') {
-      const delta = latest.score - prior.score;
-      const sign = delta > 0 ? '+' : '';
-      lines.push(`- Day-over-day delta: ${sign}${delta}`);
-    }
-    const recent = snapshots
-      .slice(0, 7)
-      .map((s) => (typeof s?.score === 'number' ? s.score : null))
-      .filter((s) => s != null);
-    if (recent.length >= 3) {
-      lines.push(`- Last ${recent.length} days: ${recent.join(', ')}`);
-    }
-  }
-
-  return lines.join('\n');
-}
+// formatIncrementScorePrelude lives in score-prelude.js (no server deps) so the
+// eval harness can build the same context. Imported at the top; re-exported here
+// for existing importers (e.g. cli.test.js, the ask handler below).
+export { formatIncrementScorePrelude };
 
 async function readJsonBody(request) {
   const chunks = [];
@@ -1979,7 +2207,8 @@ export function syncServiceContractPayload({
     tokenBootstrap: true,
     deviceFlow: false,
     browserApproval: false,
-    devEmail: false
+    devEmail: false,
+    agentTokens: false
   },
   providers = {
     apple: {
@@ -2042,6 +2271,10 @@ export function createSyncServiceRequestHandler({
   completeGoogleWebAuth = null,
   completeGoogleMobileAuth = null,
   refreshSession,
+  issueAgentToken,
+  listAgentTokens,
+  revokeAgentToken,
+  authenticateAgentTokenManagement,
   authenticateConnectedWriteToken,
   allowManualDeviceApproval = false,
   rateLimitConfig = null,
@@ -2067,6 +2300,7 @@ export function createSyncServiceRequestHandler({
   getCurrentWeeklyCheckinForAccount = null,
   upsertScheduledWeeklyCheckinForAccount = null,
   transitionWeeklyCheckinForAccount = null,
+  updateWeeklyCheckinRecapForAccount = null,
   generateWeeklyCheckinRecapImpl = null,
   generateCheckinQuestionsImpl = null,
   saveAIFeedbackForAccount = null,
@@ -2083,10 +2317,21 @@ export function createSyncServiceRequestHandler({
   listCurrentCoachObservationsForAccount = null,
   markCoachObservationSeenForAccount = null,
   dismissCoachObservationForAccount = null,
+  recordCoachObservationOutcomeForAccount = null,
+  recordCoachObservationFeedbackForAccount = null,
   // Social
   social = null,
   onError = null
 }) {
+  // Fail-closed invariant: agent-token management is a human-only, full/session
+  // scoped operation. If management is enabled, it MUST be gated by a dedicated
+  // authenticator. Without this guard, the per-request `?? readAuthenticator`
+  // fallback below would let the read authenticator (which accepts agent tokens)
+  // manage tokens — a read-token → write-token escalation. Boot loudly instead.
+  if ((issueAgentToken || listAgentTokens || revokeAgentToken) && typeof authenticateAgentTokenManagement !== 'function') {
+    throw new Error('authenticateAgentTokenManagement must be provided when agent-token management is enabled; it must not fall back to the read authenticator.');
+  }
+
   const rateLimiter = createRateLimiter(rateLimitConfig ?? {});
 
   return async function handle(request, response) {
@@ -2883,6 +3128,101 @@ export function createSyncServiceRequestHandler({
       const writeAuthenticator = authenticateWriteToken ?? authenticateToken;
       const connectedWriteAuthenticator = authenticateConnectedWriteToken ?? readAuthenticator;
       const mobileSyncAuthenticator = writeAuthenticator;
+      // Safe fallback: the construction-time invariant guarantees a dedicated
+      // authenticator whenever management handlers are wired, so this only ever
+      // resolves to readAuthenticator when management is disabled (issueAgentToken
+      // absent), where the route returns 405 before any token is honoured.
+      const agentTokenManagementAuthenticator = authenticateAgentTokenManagement ?? readAuthenticator;
+
+      if (route.command === 'agent-tokens') {
+        if (request.method !== 'POST' && request.method !== 'GET') {
+          methodNotAllowed(response, 'Use GET or POST for /cli/agent-tokens.');
+          return;
+        }
+
+        if (!requestToken) {
+          unauthorized(response, request);
+          return;
+        }
+
+        const managementAccount = agentTokenManagementAuthenticator
+          ? await agentTokenManagementAuthenticator(requestToken)
+          : null;
+        if (!managementAccount) {
+          unauthorized(response, request);
+          return;
+        }
+
+        if (request.method === 'POST') {
+          if (!issueAgentToken) {
+            methodNotAllowed(response, 'Agent token creation is not enabled for this service mode.');
+            return;
+          }
+          try {
+            const body = await readJsonBody(request);
+            const agentToken = await issueAgentToken(managementAccount, {
+              name: body?.name,
+              access: body?.access ?? 'read',
+              expiresDays: body?.expiresDays ?? 90
+            });
+            json(response, 201, {
+              ok: true,
+              agentToken
+            });
+            return;
+          } catch (error) {
+            badRequest(response, error.message);
+            return;
+          }
+        }
+
+        if (!listAgentTokens) {
+          methodNotAllowed(response, 'Agent token listing is not enabled for this service mode.');
+          return;
+        }
+        const agentTokens = await listAgentTokens(managementAccount);
+        json(response, 200, {
+          agentTokens
+        });
+        return;
+      }
+
+      if (route.command === 'agent-token') {
+        if (request.method !== 'DELETE') {
+          methodNotAllowed(response, 'Use DELETE for /cli/agent-tokens/:id.');
+          return;
+        }
+
+        if (!requestToken) {
+          unauthorized(response, request);
+          return;
+        }
+
+        if (!revokeAgentToken) {
+          methodNotAllowed(response, 'Agent token revocation is not enabled for this service mode.');
+          return;
+        }
+
+        const managementAccount = agentTokenManagementAuthenticator
+          ? await agentTokenManagementAuthenticator(requestToken)
+          : null;
+        if (!managementAccount) {
+          unauthorized(response, request);
+          return;
+        }
+
+        const agentToken = await revokeAgentToken(managementAccount, route.options.id);
+        if (!agentToken) {
+          notFound(response, 'Agent token not found.');
+          return;
+        }
+
+        json(response, 200, {
+          ok: true,
+          agentToken
+        });
+        return;
+      }
 
       if (route.command === 'mobile-sync-bootstrap') {
         if (request.method !== 'GET') {
@@ -2929,19 +3269,21 @@ export function createSyncServiceRequestHandler({
       }
 
       if (route.command === 'score-snapshots') {
-        const account = connectedWriteAuthenticator
-          ? await connectedWriteAuthenticator(requestToken)
-          : null;
-        if (!account) {
-          unauthorized(response, request);
-          return;
-        }
-
         if (request.method === 'POST') {
           if (!insertScoreSnapshotsForAccount) {
             methodNotAllowed(response, 'Score snapshot upload is not enabled for this service mode.');
             return;
           }
+          const account = connectedWriteAuthenticator
+            ? await connectedWriteAuthenticator(requestToken)
+            : null;
+          if (!account) {
+            if (await rejectInsufficientScopeForReadToken(response, request, requestToken, readAuthenticator)) {
+              return;
+            }
+            unauthorized(response, request);
+            return;
+          }
           try {
             const body = await readJsonBody(request);
             if (!body || typeof body !== 'object' || !Array.isArray(body.snapshots)) {
@@ -2974,6 +3316,13 @@ export function createSyncServiceRequestHandler({
         }
 
         if (request.method === 'GET') {
+          const account = readAuthenticator
+            ? await readAuthenticator(requestToken)
+            : null;
+          if (!account) {
+            unauthorized(response, request);
+            return;
+          }
           if (!listScoreSnapshotsForAccount) {
             methodNotAllowed(response, 'Score snapshot history is not enabled for this service mode.');
             return;
@@ -3044,6 +3393,19 @@ export function createSyncServiceRequestHandler({
           return;
         }
 
+        // Account deletion is an irreversible human action. Agent tokens — even
+        // write-scoped ones — must never be able to delete the account; a leaked
+        // CI/automation token would otherwise nuke everything. Require a human
+        // (full/session) credential.
+        if (typeof deleteAccount.tokenScope === 'string' && deleteAccount.tokenScope.startsWith('agent')) {
+          logRequest(request, 403);
+          json(response, 403, {
+            error: 'Account deletion requires a human login and cannot be performed with an agent token.',
+            code: 'AGENT_TOKEN_FORBIDDEN'
+          });
+          return;
+        }
+
         try {
           await deleteAccountForUser(deleteAccount.id);
           logRequest(request, 200);
@@ -3068,6 +3430,9 @@ export function createSyncServiceRequestHandler({
               ? { id: 'remote-user', email: null }
               : null;
           if (!proposalAccount) {
+            if (await rejectInsufficientScopeForReadToken(response, request, requestToken, readAuthenticator)) {
+              return;
+            }
             unauthorized(response, request);
             return;
           }
@@ -3136,6 +3501,9 @@ export function createSyncServiceRequestHandler({
             ? { id: 'remote-user', email: null }
             : null;
         if (!proposalAccount) {
+          if (await rejectInsufficientScopeForReadToken(response, request, requestToken, readAuthenticator)) {
+            return;
+          }
           unauthorized(response, request);
           return;
         }
@@ -3174,6 +3542,9 @@ export function createSyncServiceRequestHandler({
           ? await connectedWriteAuthenticator(requestToken)
           : null;
         if (!account) {
+          if (await rejectInsufficientScopeForReadToken(response, request, requestToken, readAuthenticator)) {
+            return;
+          }
           unauthorized(response, request);
           return;
         }
@@ -3258,6 +3629,9 @@ export function createSyncServiceRequestHandler({
           ? await connectedWriteAuthenticator(requestToken)
           : null;
         if (!account) {
+          if (await rejectInsufficientScopeForReadToken(response, request, requestToken, readAuthenticator)) {
+            return;
+          }
           unauthorized(response, request);
           return;
         }
@@ -3299,7 +3673,8 @@ export function createSyncServiceRequestHandler({
             tokenBootstrap: Boolean(issueSession || token),
             deviceFlow: Boolean(issueDeviceChallenge && consumeDeviceChallenge),
             browserApproval: Boolean(approveDeviceChallenge),
-            devEmail: Boolean(issueDevLogin)
+            devEmail: Boolean(issueDevLogin),
+            agentTokens: Boolean(issueAgentToken && listAgentTokens && revokeAgentToken)
           }
         }));
         return;
@@ -3626,6 +4001,9 @@ export function createSyncServiceRequestHandler({
                 ? account
                 : null;
             if (!writeAccount) {
+              if (await rejectInsufficientScopeForReadToken(response, request, requestToken, readAuthenticator)) {
+                return;
+              }
               unauthorized(response, request);
               return;
             }
@@ -3680,6 +4058,18 @@ export function createSyncServiceRequestHandler({
           json(response, 503, { error: 'Coach observations not available' });
           return;
         }
+        const writeAccount = connectedWriteAuthenticator
+          ? await connectedWriteAuthenticator(requestToken)
+          : requestToken === token
+            ? account
+            : null;
+        if (!writeAccount) {
+          if (await rejectInsufficientScopeForReadToken(response, request, requestToken, readAuthenticator)) {
+            return;
+          }
+          unauthorized(response, request);
+          return;
+        }
         let body = {};
         try {
           body = await readOptionalJsonBody(request);
@@ -3693,7 +4083,7 @@ export function createSyncServiceRequestHandler({
           return;
         }
         try {
-          const observation = await markCoachObservationSeenForAccount(account, route.options.id, { seenAt });
+          const observation = await markCoachObservationSeenForAccount(writeAccount, route.options.id, { seenAt });
           if (!observation) {
             notFound(response, 'Observation not found');
             return;
@@ -3715,6 +4105,18 @@ export function createSyncServiceRequestHandler({
           json(response, 503, { error: 'Coach observations not available' });
           return;
         }
+        const writeAccount = connectedWriteAuthenticator
+          ? await connectedWriteAuthenticator(requestToken)
+          : requestToken === token
+            ? account
+            : null;
+        if (!writeAccount) {
+          if (await rejectInsufficientScopeForReadToken(response, request, requestToken, readAuthenticator)) {
+            return;
+          }
+          unauthorized(response, request);
+          return;
+        }
         try {
           await readOptionalJsonBody(request);
         } catch {
@@ -3722,7 +4124,7 @@ export function createSyncServiceRequestHandler({
           return;
         }
         try {
-          const observation = await dismissCoachObservationForAccount(account, route.options.id, {});
+          const observation = await dismissCoachObservationForAccount(writeAccount, route.options.id, {});
           if (!observation) {
             notFound(response, 'Observation not found');
             return;
@@ -3735,6 +4137,126 @@ export function createSyncServiceRequestHandler({
         return;
       }
 
+      if (route.command === 'coach-observations-outcome') {
+        if (request.method !== 'POST') {
+          methodNotAllowed(response, 'Use POST for /cli/coach-observations/:id/outcome.');
+          return;
+        }
+        if (!recordCoachObservationOutcomeForAccount) {
+          json(response, 503, { error: 'Coach observations not available' });
+          return;
+        }
+        const writeAccount = connectedWriteAuthenticator
+          ? await connectedWriteAuthenticator(requestToken)
+          : requestToken === token
+            ? account
+            : null;
+        if (!writeAccount) {
+          if (await rejectInsufficientScopeForReadToken(response, request, requestToken, readAuthenticator)) {
+            return;
+          }
+          unauthorized(response, request);
+          return;
+        }
+        let body = {};
+        try {
+          body = await readOptionalJsonBody(request);
+        } catch {
+          badRequest(response, 'Invalid request body.');
+          return;
+        }
+        const outcomeStatus = String(body?.outcomeStatus ?? '').trim();
+        if (!COACH_OBSERVATION_OUTCOME_STATUSES.has(outcomeStatus)) {
+          badRequest(response, 'outcomeStatus must be improved, unchanged, regressed, or inconclusive.');
+          return;
+        }
+        const outcomeObservedAt = body?.outcomeObservedAt ? new Date(body.outcomeObservedAt) : new Date();
+        if (Number.isNaN(outcomeObservedAt.getTime())) {
+          badRequest(response, 'Invalid outcomeObservedAt.');
+          return;
+        }
+        try {
+          const observation = await recordCoachObservationOutcomeForAccount(writeAccount, route.options.id, {
+            outcomeStatus,
+            outcomeObservedAt,
+            outcomeNotes: typeof body?.outcomeNotes === 'string' && body.outcomeNotes.trim()
+              ? body.outcomeNotes.trim()
+              : null,
+            linkedFollowupObservationId: typeof body?.linkedFollowupObservationId === 'string' && body.linkedFollowupObservationId.trim()
+              ? body.linkedFollowupObservationId.trim()
+              : null
+          });
+          if (!observation) {
+            notFound(response, 'Observation not found');
+            return;
+          }
+          json(response, 200, { observation });
+        } catch (err) {
+          console.error('Coach observation outcome error:', err.message);
+          if (err.code === 'INVALID_LINKED_FOLLOWUP_OBSERVATION') {
+            badRequest(response, err.message);
+            return;
+          }
+          json(response, 500, { error: 'Failed to record observation outcome' });
+        }
+        return;
+      }
+
+      if (route.command === 'coach-observations-feedback') {
+        if (request.method !== 'POST') {
+          methodNotAllowed(response, 'Use POST for /cli/coach-observations/:id/feedback.');
+          return;
+        }
+        if (!recordCoachObservationFeedbackForAccount) {
+          json(response, 503, { error: 'Coach observations not available' });
+          return;
+        }
+        const writeAccount = connectedWriteAuthenticator
+          ? await connectedWriteAuthenticator(requestToken)
+          : requestToken === token
+            ? account
+            : null;
+        if (!writeAccount) {
+          if (await rejectInsufficientScopeForReadToken(response, request, requestToken, readAuthenticator)) {
+            return;
+          }
+          unauthorized(response, request);
+          return;
+        }
+        let body = {};
+        try {
+          body = await readOptionalJsonBody(request);
+        } catch {
+          badRequest(response, 'Invalid request body.');
+          return;
+        }
+        const feedbackStatus = String(body?.feedbackStatus ?? '').trim();
+        if (!COACH_OBSERVATION_FEEDBACK_STATUSES.has(feedbackStatus)) {
+          badRequest(response, 'feedbackStatus must be accepted or rejected.');
+          return;
+        }
+        const feedbackAt = body?.feedbackAt ? new Date(body.feedbackAt) : new Date();
+        if (Number.isNaN(feedbackAt.getTime())) {
+          badRequest(response, 'Invalid feedbackAt.');
+          return;
+        }
+        try {
+          const observation = await recordCoachObservationFeedbackForAccount(writeAccount, route.options.id, {
+            feedbackStatus,
+            feedbackAt
+          });
+          if (!observation) {
+            notFound(response, 'Observation not found');
+            return;
+          }
+          json(response, 200, { observation });
+        } catch (err) {
+          console.error('Coach observation feedback error:', err.message);
+          json(response, 500, { error: 'Failed to record observation feedback' });
+        }
+        return;
+      }
+
       let snapshot;
       try {
         snapshot = loadSnapshotForAccount
@@ -3757,6 +4279,85 @@ export function createSyncServiceRequestHandler({
           };
         }
       };
+      const weeklyCheckinContextForRow = async (row) => {
+        const { weeklyCheckinContext } = await import('./queries.js');
+        return weeklyCheckinContext(snapshot, account.id, weeklyCheckinContextOptions(row));
+      };
+      const priorWeeklyCheckinCommitment = async (ctx) => {
+        if (!listActiveCoachCommitmentsForAccount || !ctx) return null;
+        try {
+          const activeCommitments = await listActiveCoachCommitmentsForAccount(account, {
+            limit: 1,
+            weekStartDate: ctx.weekRangeIso?.start
+          });
+          return activeCommitments[0] ?? null;
+        } catch (commitmentErr) {
+          console.error('Weekly-checkin commitment read failed:', commitmentErr.message);
+          return null;
+        }
+      };
+      const weeklyCheckinFreshnessForRow = async (row) => {
+        const checkedAt = new Date().toISOString();
+        if (!row?.recap || row.recap.placeholder) return null;
+        const storedDigest = typeof row.recap.contextDigest === 'string' ? row.recap.contextDigest : null;
+        if (!storedDigest) return { state: 'unknown', checkedAt };
+        try {
+          const ctx = await weeklyCheckinContextForRow(row);
+          const priorCommitmentRow = await priorWeeklyCheckinCommitment(ctx);
+          const { weeklyCheckinContextDigest } = await import('./queries.js');
+          const currentDigest = weeklyCheckinContextDigest(ctx, {
+            priorCommitment: priorCommitmentRow?.commitment ?? null,
+            coachCommitmentIds: priorCommitmentRow?.id ? [priorCommitmentRow.id] : []
+          });
+          if (!currentDigest) return { state: 'unknown', checkedAt };
+          return { state: currentDigest === storedDigest ? 'fresh' : 'stale', checkedAt };
+        } catch {
+          return { state: 'unknown', checkedAt };
+        }
+      };
+      const generateWeeklyCheckinRecapPayload = async (row) => {
+        const openrouterKey = process.env.OPENROUTER_API_KEY;
+        if (!openrouterKey || !generateWeeklyCheckinRecapImpl || !generateCheckinQuestionsImpl) {
+          const err = new Error('Weekly check-in refresh is unavailable.');
+          err.code = 'weekly_checkin_refresh_unavailable';
+          throw err;
+        }
+
+        const ctx = await weeklyCheckinContextForRow(row);
+        if (!ctx) {
+          const err = new Error('Weekly check-in context is unavailable.');
+          err.code = 'weekly_checkin_context_unavailable';
+          throw err;
+        }
+
+        const priorCommitmentRow = await priorWeeklyCheckinCommitment(ctx);
+        const { weeklyCheckinContextDigest } = await import('./queries.js');
+        const coachCommitmentIds = priorCommitmentRow?.id ? [priorCommitmentRow.id] : [];
+        const recapResult = await generateWeeklyCheckinRecapImpl(ctx, {
+          apiKey: openrouterKey,
+          user: aiUser,
+          sessionId: `weekly-checkin:${row.id}:recap`,
+          priorCommitment: priorCommitmentRow?.commitment ?? null,
+          contextMetadata: {
+            coachCommitmentIds: priorCommitmentRow?.id ? [priorCommitmentRow.id] : []
+          }
+        });
+        const questionsResult = await generateCheckinQuestionsImpl(ctx, recapResult.text, {
+          apiKey: openrouterKey,
+          user: aiUser,
+          sessionId: `weekly-checkin:${row.id}:questions`
+        });
+        return {
+          recapText: recapResult.text,
+          questions: questionsResult.questions,
+          model: recapResult.model,
+          generatedAt: new Date().toISOString(),
+          contextDigest: weeklyCheckinContextDigest(ctx, {
+            priorCommitment: priorCommitmentRow?.commitment ?? null,
+            coachCommitmentIds
+          })
+        };
+      };
 
       if (route.command === 'increment-score-current') {
         if (request.method !== 'GET') {
@@ -3791,6 +4392,12 @@ export function createSyncServiceRequestHandler({
           if (route.options.toolName === 'get_increment_score') {
             await hydrateIncrementScore(body?.historyDays ?? 14);
           }
+          const observationOptions = coachToolObservationOptions(route.options.toolName, body ?? {});
+          if (observationOptions) {
+            snapshot.coachObservations = listCurrentCoachObservationsForAccount
+              ? await listCurrentCoachObservationsForAccount(account, observationOptions) ?? []
+              : [];
+          }
           json(response, 200, queries.executeCoachReadTool(snapshot, route.options.toolName, body ?? {}));
           return;
         } catch (error) {
@@ -3949,52 +4556,11 @@ export function createSyncServiceRequestHandler({
           }
           // Lazy-gen path: if scheduled and overdue, attempt to generate now.
           if (row.status === 'scheduled' && row.nextRecapDueAt && new Date(row.nextRecapDueAt) <= new Date()) {
-            const openrouterKey = process.env.OPENROUTER_API_KEY;
             let recap = null;
-            if (openrouterKey && generateWeeklyCheckinRecapImpl && generateCheckinQuestionsImpl) {
-              try {
-                const { weeklyCheckinContext } = await import('./queries.js');
-                // Anchor to row.weekStartDate so lazy-gen describes the
-                // canonical week, matching cron behaviour (onemore-8oc5).
-                const referenceNow = new Date(`${row.weekStartDate}T23:59:59.999Z`);
-                const ctx = weeklyCheckinContext(snapshot, account.id, { now: referenceNow });
-                if (ctx) {
-                  let priorCommitmentRow = null;
-                  if (listActiveCoachCommitmentsForAccount) {
-                    try {
-                      const activeCommitments = await listActiveCoachCommitmentsForAccount(account, {
-                        limit: 1,
-                        weekStartDate: ctx.weekRangeIso?.start
-                      });
-                      priorCommitmentRow = activeCommitments[0] ?? null;
-                    } catch (commitmentErr) {
-                      console.error('Lazy weekly-checkin commitment read failed:', commitmentErr.message);
-                    }
-                  }
-                  const recapResult = await generateWeeklyCheckinRecapImpl(ctx, {
-                    apiKey: openrouterKey,
-                    user: aiUser,
-                    sessionId: `weekly-checkin:${row.id}:recap`,
-                    priorCommitment: priorCommitmentRow?.commitment ?? null,
-                    contextMetadata: {
-                      coachCommitmentIds: priorCommitmentRow?.id ? [priorCommitmentRow.id] : []
-                    }
-                  });
-                  const questionsResult = await generateCheckinQuestionsImpl(ctx, recapResult.text, {
-                    apiKey: openrouterKey,
-                    user: aiUser,
-                    sessionId: `weekly-checkin:${row.id}:questions`
-                  });
-                  recap = {
-                    recapText: recapResult.text,
-                    questions: questionsResult.questions,
-                    model: recapResult.model,
-                    generatedAt: new Date().toISOString()
-                  };
-                }
-              } catch (genErr) {
-                console.error('Lazy weekly-checkin gen failed:', genErr.message);
-              }
+            try {
+              recap = await generateWeeklyCheckinRecapPayload(row);
+            } catch (genErr) {
+              console.error('Lazy weekly-checkin gen failed:', genErr.message);
             }
             if (!recap) {
               recap = { recapText: 'Your recap is being prepared.', questions: [], placeholder: true, generatedAt: new Date().toISOString() };
@@ -4012,12 +4578,14 @@ export function createSyncServiceRequestHandler({
               }
             }
           }
+          const freshness = await weeklyCheckinFreshnessForRow(row);
           json(response, 200, {
             id: row.id,
             weekStartDate: row.weekStartDate,
             status: row.status,
             recap: row.recap,
-            conversationId: row.conversationId
+            conversationId: row.conversationId,
+            freshness
           });
         } catch (err) {
           console.error('Weekly check-in current error:', err.message);
@@ -4074,7 +4642,10 @@ export function createSyncServiceRequestHandler({
           json(response, 503, { error: 'Weekly check-in not available' });
           return;
         }
-        const row = await getCurrentWeeklyCheckinForAccount(account);
+        let body;
+        try { body = await readOptionalJsonBody(request); } catch { badRequest(response, 'Invalid JSON body.'); return; }
+        const refreshIfStale = body?.refreshIfStale === true;
+        let row = await getCurrentWeeklyCheckinForAccount(account);
         if (!row) {
           notFound(response, 'No weekly check-in scheduled.');
           return;
@@ -4084,9 +4655,9 @@ export function createSyncServiceRequestHandler({
           return;
         }
         const conversationId = `weekly-checkin:${row.id}`;
-        const recapText = String(row.recap.recapText ?? '').trim();
-        const questions = Array.isArray(row.recap.questions) ? row.recap.questions : [];
-        const firstAssistantMessage = [recapText, ...(questions.length ? [questions.map((q, i) => `${i + 1}. ${q}`).join('\n')] : [])].filter(Boolean).join('\n\n');
+        let recapText = String(row.recap.recapText ?? '').trim();
+        let questions = Array.isArray(row.recap.questions) ? row.recap.questions : [];
+        let firstAssistantMessage = [recapText, ...(questions.length ? [questions.map((q, i) => `${i + 1}. ${q}`).join('\n')] : [])].filter(Boolean).join('\n\n');
         try {
           const { AI_PROMPT_VERSIONS } = await import('./openrouter.js');
           const existingConversation = getAskConversationForAccount
@@ -4102,6 +4673,61 @@ export function createSyncServiceRequestHandler({
             });
             return;
           }
+          if (refreshIfStale) {
+            const freshness = await weeklyCheckinFreshnessForRow(row);
+            if (freshness?.state === 'stale' || freshness?.state === 'unknown') {
+              if (!updateWeeklyCheckinRecapForAccount) {
+                json(response, 503, {
+                  error: 'Weekly check-in refresh is not available.',
+                  code: 'refresh_unavailable'
+                });
+                return;
+              }
+              let recap;
+              try {
+                recap = await generateWeeklyCheckinRecapPayload(row);
+              } catch (refreshErr) {
+                console.error('Weekly check-in refresh failed:', refreshErr.message);
+                if (refreshErr?.code === 'weekly_checkin_refresh_unavailable' ||
+                    refreshErr?.code === 'weekly_checkin_context_unavailable') {
+                  json(response, 503, {
+                    error: 'Weekly check-in refresh is not available.',
+                    code: 'refresh_unavailable'
+                  });
+                } else {
+                  json(response, 502, {
+                    error: 'Failed to refresh weekly check-in.',
+                    code: 'refresh_failed'
+                  });
+                }
+                return;
+              }
+              let updated;
+              try {
+                updated = await updateWeeklyCheckinRecapForAccount(account, row.id, {
+                  recap
+                });
+              } catch (refreshUpdateErr) {
+                console.error('Weekly check-in refresh update failed:', refreshUpdateErr.message);
+                json(response, 502, {
+                  error: 'Failed to refresh weekly check-in.',
+                  code: 'refresh_failed'
+                });
+                return;
+              }
+              if (!updated) {
+                json(response, 409, {
+                  error: 'Weekly check-in was not refreshed.',
+                  code: 'refresh_conflict'
+                });
+                return;
+              }
+              row = updated;
+            }
+          }
+          recapText = String(row.recap.recapText ?? '').trim();
+          questions = Array.isArray(row.recap.questions) ? row.recap.questions : [];
+          firstAssistantMessage = [recapText, ...(questions.length ? [questions.map((q, i) => `${i + 1}. ${q}`).join('\n')] : [])].filter(Boolean).join('\n\n');
           if (row.status !== 'in_progress') {
             let openedRow = row;
             if (openedRow.status === 'generated' || openedRow.status === 'delivered') {
@@ -4333,12 +4959,128 @@ export function createSyncServiceRequestHandler({
         return;
       }
 
+      if (route.command === 'ask-plan') {
+        if (request.method !== 'POST') {
+          methodNotAllowed(response, 'Use POST for /cli/ask/plan.');
+          return;
+        }
+
+        let body;
+        try {
+          body = await readJsonBody(request);
+        } catch {
+          badRequest(response, 'Invalid JSON body.');
+          return;
+        }
+
+        const question = body?.question;
+        if (!question || typeof question !== 'string' || question.trim().length === 0) {
+          badRequest(response, 'question is required');
+          return;
+        }
+        if (question.length > 500) {
+          badRequest(response, 'question must be 500 characters or fewer');
+          return;
+        }
+
+        const exclude = parseExclude(body?.exclude);
+        const conversationId = typeof body?.conversationId === 'string' ? body.conversationId : null;
+        const history = sanitizeHistory(body?.history);
+        const persistedConversation = conversationId && getAskConversationForAccount
+          ? await getAskConversationForAccount(account, conversationId)
+          : null;
+        const persistedMessages = Array.isArray(persistedConversation?.messages)
+          ? sanitizeHistory(persistedConversation.messages)
+          : null;
+        const canonicalHistory = (persistedMessages?.length ? persistedMessages : null) ?? history;
+        const requestedCoachObservation = normalizeAskCoachObservationFollowUp(body?.coachObservation);
+        const plannedEvidence = planAskEvidence(snapshot, question, {
+          exclude,
+          history: canonicalHistory
+        });
+        let coachFacts = [];
+        if (listCoachFactsForAccount) {
+          try {
+            const kinds = coachFactKindsForAskQuestion(snapshot, question, { history: canonicalHistory });
+            coachFacts = await listCoachFactsForAccount(account, { kinds, limit: 30 });
+          } catch (factErr) {
+            console.error('Coach facts read error (ask plan):', factErr.message);
+          }
+        }
+        if (
+          listScoreSnapshotsForAccount &&
+          (requestedCoachObservation || plannedEvidence.requiredTools.includes('get_increment_score'))
+        ) {
+          try {
+            const scoreSnapshots = await listScoreSnapshotsForAccount(account, { limit: 14 }) ?? [];
+            if (scoreSnapshots.length > 0) {
+              const enrichedSnapshots = enrichScoreSnapshots(scoreSnapshots);
+              snapshot.incrementScore = {
+                latest: enrichedSnapshots[0],
+                history: enrichedSnapshots
+              };
+            }
+          } catch (scoreErr) {
+            console.error('Increment Score read error (ask plan):', scoreErr.message);
+          }
+        }
+        let coachObservations = [];
+        if (listCurrentCoachObservationsForAccount && !exclude.has('coach_observations')) {
+          try {
+            coachObservations = await listCurrentCoachObservationsForAccount(account, {
+              limit: requestedCoachObservation ? ASK_REQUESTED_COACH_OBSERVATION_LIMIT : 3,
+              includeOutcomeHistory: true
+            }) ?? [];
+          } catch (observationErr) {
+            console.error('Coach observations read error (ask plan):', observationErr.message);
+          }
+        }
+        snapshot.coachObservations = coachObservations;
+        const coachObservationFollowUp = selectAskCoachObservationFollowUp(requestedCoachObservation, coachObservations);
+        const routedContext = coachObservationFollowUp
+          ? askObservationFollowUpContext(snapshot, question, coachObservationFollowUp, {
+              exclude,
+              coachFacts,
+              intent: requestedCoachObservation?.intent
+            })
+          : requestedCoachObservation?.intent === 'successor_plan'
+            ? askMissingObservationFollowUpContext(snapshot, question, requestedCoachObservation, {
+                exclude,
+                intent: requestedCoachObservation.intent,
+                today: new Date()
+              })
+            : askRoutedContext(snapshot, question, {
+                exclude,
+                coachFacts,
+                coachObservations,
+                history: canonicalHistory
+              });
+        json(response, 200, {
+          contextBundle: routedContext.contextBundle,
+          metadata: routedContext.metadata
+        });
+        return;
+      }
+
       if (route.command === 'ask-ai') {
         if (request.method !== 'POST') {
           methodNotAllowed(response, 'Use POST for /cli/ask.');
           return;
         }
 
+        const writeAccount = connectedWriteAuthenticator
+          ? await connectedWriteAuthenticator(requestToken)
+          : requestToken === token
+            ? account
+            : null;
+        if (!writeAccount) {
+          if (await rejectInsufficientScopeForReadToken(response, request, requestToken, readAuthenticator)) {
+            return;
+          }
+          unauthorized(response, request);
+          return;
+        }
+
         let body;
         try {
           body = await readJsonBody(request);
@@ -4371,21 +5113,23 @@ export function createSyncServiceRequestHandler({
           ? sanitizeHistory(persistedConversation.messages)
           : null;
         const canonicalHistory = (persistedMessages?.length ? persistedMessages : null) ?? history;
+        const persistedStorageMessages = Array.isArray(persistedConversation?.messages)
+          ? sanitizeAskMessagesForStorage(persistedConversation.messages, { allowStructured: true })
+          : null;
+        const canonicalStorageHistory = (persistedStorageMessages?.length ? persistedStorageMessages : null)
+          ?? sanitizeAskMessagesForStorage(body?.history);
         const openrouterKey = process.env.OPENROUTER_API_KEY;
         if (!openrouterKey) {
           json(response, 503, { error: 'AI not configured', code: 'not_configured' });
           return;
         }
 
-        const queries = await import('./queries.js');
         const exclude = parseExclude(body?.exclude);
         const requestedCoachObservation = normalizeAskCoachObservationFollowUp(body?.coachObservation);
         let coachFacts = [];
         if (listCoachFactsForAccount) {
           try {
-            const kinds = queries.coachFactKindsForAskQuestion
-              ? queries.coachFactKindsForAskQuestion(snapshot, question)
-              : [];
+            const kinds = coachFactKindsForAskQuestion(snapshot, question, { history: canonicalHistory });
             coachFacts = await listCoachFactsForAccount(account, { kinds, limit: 30 });
           } catch (factErr) {
             console.error('Coach facts read error (ask):', factErr.message);
@@ -4407,22 +5151,35 @@ export function createSyncServiceRequestHandler({
           };
         }
         let coachObservations = [];
-        if (listCurrentCoachObservationsForAccount) {
+        if (listCurrentCoachObservationsForAccount && !exclude.has('coach_observations')) {
           try {
-            coachObservations = await listCurrentCoachObservationsForAccount(account, { limit: requestedCoachObservation ? 10 : 3 }) ?? [];
+            coachObservations = await listCurrentCoachObservationsForAccount(account, {
+              limit: requestedCoachObservation ? ASK_REQUESTED_COACH_OBSERVATION_LIMIT : 3,
+              includeOutcomeHistory: true
+            }) ?? [];
           } catch (observationErr) {
             console.error('Coach observations read error (ask):', observationErr.message);
           }
         }
+        snapshot.coachObservations = coachObservations;
         const coachObservationFollowUp = selectAskCoachObservationFollowUp(requestedCoachObservation, coachObservations);
-
-        const routedContext = coachObservationFollowUp && queries.askObservationFollowUpContext
-          ? queries.askObservationFollowUpContext(snapshot, question, coachObservationFollowUp, { exclude, coachFacts })
-          : queries.askRoutedContext
-            ? queries.askRoutedContext(snapshot, question, { exclude, coachFacts, coachObservations })
-            : { context: queries.askContext(snapshot, { exclude }), metadata: { route: 'legacy' } };
+        const missingRequestedCoachObservation = Boolean(requestedCoachObservation && !coachObservationFollowUp);
+
+        const routedContext = coachObservationFollowUp
+          ? askObservationFollowUpContext(snapshot, question, coachObservationFollowUp, {
+              exclude,
+              coachFacts,
+              intent: requestedCoachObservation?.intent
+            })
+          : requestedCoachObservation?.intent === 'successor_plan'
+            ? askMissingObservationFollowUpContext(snapshot, question, requestedCoachObservation, {
+                exclude,
+                intent: requestedCoachObservation.intent,
+                today: new Date()
+              })
+            : askRoutedContext(snapshot, question, { exclude, coachFacts, coachObservations, history: canonicalHistory });
         const persistedKind = persistedConversation?.kind ?? (conversationId?.startsWith('weekly-checkin:') ? 'weekly-checkin' : 'ask');
-        const incrementScorePrelude = formatIncrementScorePrelude(scoreSnapshots);
+        const incrementScorePrelude = formatIncrementScorePrelude(scoreSnapshots, { question });
 
         const preludes = [incrementScorePrelude].filter(Boolean);
         const ctx = preludes.length > 0
@@ -4432,51 +5189,195 @@ export function createSyncServiceRequestHandler({
         const askTone = ['default', 'hype', 'numbers-only'].includes(body?.tone) ? body.tone : undefined;
 
         try {
-          const { AI_PROMPT_VERSIONS, generateAskAnswer, WEEKLY_CHECKIN_PROMPT } = await import('./openrouter.js');
-          const generateAsk = generateAskAnswerImpl ?? generateAskAnswer;
+          const { AI_PROMPT_VERSIONS, generateAskAnswerAgentic, SYSTEM_PROMPTS_FOR_LEAK_CHECK, WEEKLY_CHECKIN_PROMPT } = await import('./openrouter.js');
+          const generateAsk = generateAskAnswerImpl ?? generateAskAnswerAgentic;
           const systemPromptOverride = persistedKind === 'weekly-checkin' ? WEEKLY_CHECKIN_PROMPT : undefined;
+          const routingMetadata = {
+            ...routedContext.metadata,
+            contextCharCount: ctx.length,
+            historyTurnCount: canonicalHistory.filter((m) => m.role === 'user').length,
+            coachFactsIncluded: (routedContext.metadata?.includedCoachFactIds ?? []).length > 0,
+            coachFactIds: routedContext.metadata?.includedCoachFactIds ?? [],
+            coachFactKinds: routedContext.metadata?.coachFactKinds ?? [],
+            coachObservationIds: routedContext.metadata?.includedCoachObservationIds ?? [],
+            requestedCoachObservationId: requestedCoachObservation?.id ?? undefined,
+            requestedCoachObservationIntent: requestedCoachObservation?.intent ?? undefined,
+            coachObservationFollowUpMissing: missingRequestedCoachObservation || undefined
+          };
 
-          const askResult = await generateAsk(ctx, question, {
-            apiKey: openrouterKey,
-            history: canonicalHistory,
-            tone: askTone,
-            user: aiUser,
-            sessionId: `ask:${conversationId}`,
-            systemPrompt: systemPromptOverride,
-            routingMetadata: {
-              ...routedContext.metadata,
-              contextCharCount: ctx.length,
-              historyTurnCount: canonicalHistory.filter((m) => m.role === 'user').length,
-              coachFactsIncluded: (routedContext.metadata?.includedCoachFactIds ?? []).length > 0,
-              coachFactIds: routedContext.metadata?.includedCoachFactIds ?? [],
-              coachFactKinds: routedContext.metadata?.coachFactKinds ?? [],
-              coachObservationIds: routedContext.metadata?.includedCoachObservationIds ?? []
-            }
-          });
+          const generateAttempt = async (contextForGeneration, { maxSteps } = {}) => {
+            const result = await generateAsk(contextForGeneration, question, {
+              apiKey: openrouterKey,
+              history: canonicalHistory,
+              tone: askTone,
+              user: aiUser,
+              sessionId: `ask:${conversationId}`,
+              systemPrompt: systemPromptOverride,
+              routingMetadata,
+              snapshot,
+              exclude: [...exclude],
+              ...(Number.isInteger(maxSteps) ? { maxSteps } : {})
+            });
 
-          const parsedAsk = extractAskProgramDraft(askResult.text, {
-            canonicalizeExerciseName: queries.canonicalExerciseName
-          });
-          const assistantAnswer = stripXMLTagBlocks(parsedAsk.answerText);
+            // Fold any tools the agent fetched dynamically into provenance so
+            // structured evidence and verifier replay reflect what was actually
+            // read, not just the warm-start route plan.
+            mergeAgenticToolProvenance(routingMetadata, result.toolInvocations);
+
+            const parsed = extractAskProgramDraft(result.text, {
+              canonicalizeExerciseName: canonicalExerciseName
+            });
+            const changesetParsed = extractPlanChangeset(parsed.answerText);
+            const requestedPlanAdjustment = requestedCoachObservation?.intent === 'plan_adjustment';
+            const draft = missingRequestedCoachObservation && requestedCoachObservation?.intent === 'successor_plan'
+              ? undefined
+              : parsed.programDraft;
+            // Drop a changeset if the requested observation is missing/stale — same
+            // guard as successor_plan: no live observation, no plan edits.
+            const changeset = !requestedPlanAdjustment || missingRequestedCoachObservation
+              ? undefined
+              : changesetParsed.planChangeset;
+            const answer = stripXMLTagBlocks(changesetParsed.answerText);
+            return { askResult: result, programDraft: draft, planChangeset: changeset, assistantAnswer: answer };
+          };
+
+          let attempt = await generateAttempt(ctx);
+          let programDraftRetryCount = 0;
+          let planChangesetRetryCount = 0;
+          if (
+            shouldRequireProgramDraftForAsk({
+              persistedKind,
+              requestedCoachObservation,
+              missingRequestedCoachObservation
+            }) &&
+            !attempt.programDraft
+          ) {
+            programDraftRetryCount = 1;
+            const draftRepairContext = buildMissingProgramDraftRepairContext(ctx);
+            const draftRepairAttempt = await generateAttempt(draftRepairContext, { maxSteps: 2 });
+            if (draftRepairAttempt.programDraft || !attempt.assistantAnswer) {
+              attempt = draftRepairAttempt;
+            }
+          }
+          if (
+            shouldRequirePlanChangesetForAsk({
+              persistedKind,
+              requestedCoachObservation,
+              missingRequestedCoachObservation
+            }) &&
+            !attempt.planChangeset
+          ) {
+            planChangesetRetryCount = 1;
+            const changesetRepairContext = buildMissingPlanChangesetRepairContext(ctx);
+            const changesetRepairAttempt = await generateAttempt(changesetRepairContext, { maxSteps: 2 });
+            if (changesetRepairAttempt.planChangeset || !attempt.assistantAnswer) {
+              attempt = changesetRepairAttempt;
+            }
+          }
           // Check for system prompt leakage before persisting. We inspect only
           // the user-visible prose, not the structured draft payload, so valid
           // <program_draft> output does not false-positive as a prompt leak.
-          const { SYSTEM_PROMPTS_FOR_LEAK_CHECK } = await import('./openrouter.js');
-          if (detectSystemPromptLeak(assistantAnswer, SYSTEM_PROMPTS_FOR_LEAK_CHECK)) {
+          if (detectSystemPromptLeak(attempt.assistantAnswer, SYSTEM_PROMPTS_FOR_LEAK_CHECK)) {
             console.error('SECURITY: System prompt leak detected in ask-ai response, blocking');
             onError?.(new Error('System prompt leak detected in AI response'), { feature: 'ask-coach', security: true });
-            json(response, 200, { answer: 'I can only answer questions about your training. Could you rephrase?', model: askResult.model, filtered: true });
+            json(response, 200, { answer: 'I can only answer questions about your training. Could you rephrase?', model: attempt.askResult.model, filtered: true });
             return;
           }
 
-          const promptSurface = persistedKind === 'weekly-checkin' ? 'weekly-checkin' : 'ask';
-          const promptVersion = persistedKind === 'weekly-checkin' ? AI_PROMPT_VERSIONS.weeklyCheckin : AI_PROMPT_VERSIONS.ask;
-          const metadata = buildAIGenerationMetadata(promptSurface, askResult.model, promptVersion, askResult);
-          const updatedMessages = [
-            ...canonicalHistory,
+          let verification = persistedKind === 'ask'
+            ? verifyAskAnswer({
+                answer: attempt.assistantAnswer,
+                snapshot,
+                routingMetadata,
+                today: new Date(),
+                exclude: [...exclude]
+              })
+            : null;
+          let verificationRetryCount = 0;
+          let verificationRepaired = false;
+          let verificationFallback = false;
+
+          if (persistedKind === 'ask' && shouldRepairAskAnswer(verification)) {
+            verificationRetryCount = 1;
+            const repairContext = buildAskAnswerRepairContext(ctx, attempt.assistantAnswer, verification);
+            const repairAttempt = await generateAttempt(repairContext, { maxSteps: 2 });
+            if (detectSystemPromptLeak(repairAttempt.assistantAnswer, SYSTEM_PROMPTS_FOR_LEAK_CHECK)) {
+              console.error('SECURITY: System prompt leak detected in ask-ai repair response, blocking');
+              onError?.(new Error('System prompt leak detected in AI repair response'), { feature: 'ask-coach', security: true });
+              json(response, 200, { answer: 'I can only answer questions about your training. Could you rephrase?', model: repairAttempt.askResult.model, filtered: true });
+              return;
+            }
+            const repairVerification = verifyAskAnswer({
+              answer: repairAttempt.assistantAnswer,
+              snapshot,
+              routingMetadata,
+              today: new Date(),
+              exclude: [...exclude]
+            });
+            if (repairVerification.blockingFailureCount <= verification.blockingFailureCount) {
+              attempt = repairAttempt;
+              verification = repairVerification;
+              verificationRepaired = repairVerification.passed;
+            }
+          }
+
+          if (persistedKind === 'ask' && shouldRepairAskAnswer(verification)) {
+            verificationFallback = true;
+            attempt = {
+              ...attempt,
+              assistantAnswer: safeAskVerificationFallback(),
+              programDraft: undefined,
+              planChangeset: undefined
+            };
+          }
+
+          const answerVerification = persistedKind === 'ask'
+            ? askVerificationMetadata(verification, {
+                retryCount: verificationRetryCount,
+                repaired: verificationRepaired,
+                fallback: verificationFallback
+              })
+            : undefined;
+          if (answerVerification) {
+            routingMetadata.answerVerification = answerVerification;
+          }
+          if (verificationFallback && onError) {
+            const warning = new Error('Ask Coach answer verification fallback');
+            warning.level = 'warning';
+            onError(warning, {
+              feature: 'ask-coach',
+              verification: answerVerification
+            });
+          }
+
+          const { askResult, assistantAnswer, programDraft, planChangeset } = attempt;
+          const promptSurface = askResult.promptSurface
+            ?? (persistedKind === 'weekly-checkin' ? 'weekly-checkin' : 'ask');
+          const promptVersion = askResult.promptVersion
+            ?? (persistedKind === 'weekly-checkin' ? AI_PROMPT_VERSIONS.weeklyCheckin : AI_PROMPT_VERSIONS.askAgentic);
+          const metadata = {
+            ...buildAIGenerationMetadata(promptSurface, askResult.model, promptVersion, {
+              ...askResult,
+              routingMetadata
+            }),
+            routing: routingMetadata,
+            ...(programDraftRetryCount > 0 ? { programDraftRetryCount } : {}),
+            ...(planChangesetRetryCount > 0 ? { planChangesetRetryCount } : {})
+          };
+          const structured = buildAskStructuredResponse(assistantAnswer, routingMetadata, { programDraft, planChangeset, question });
+          console.log(`ask-coach-meta ${JSON.stringify(buildAskInteractionLogPayload({
+            accountId: account.id,
+            status: 'ok',
+            promptSurface,
+            routingMetadata,
+            askResult,
+            structured
+          }))}`);
+          const updatedMessages = sanitizeAskMessagesForStorage([
+            ...canonicalStorageHistory,
             { role: 'user', content: question },
-            { role: 'assistant', content: assistantAnswer }
-          ];
+            { role: 'assistant', content: assistantAnswer, structured }
+          ], { allowStructured: true });
           if (saveAskConversationForAccount) {
             try {
               await saveAskConversationForAccount(account, {
@@ -4564,7 +5465,9 @@ export function createSyncServiceRequestHandler({
             answer: assistantAnswer,
             model: askResult.model,
             metadata,
-            programDraft: parsedAsk.programDraft
+            structured,
+            programDraft,
+            planChangeset
           });
         } catch (err) {
           console.error('AI ask error:', err.message);
@@ -4812,6 +5715,10 @@ export function createSyncServiceRequestHandler({
           return;
         }
         const report = await social.getUserReport(account.id, route.options.accountId);
+        if (report?.error === 'forbidden') {
+          json(response, 403, { ok: false, error: 'Access denied' });
+          return;
+        }
         if (!report) {
           notFound(response, 'User report not found.');
           return;