avorelo 0.1.0

package/scripts/lib/session-context-optimizer.js

@@ -0,0 +1,1211 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+const { ensureCcoDirs, nowIso, safeReadJson, safeWriteJson, safeWriteText } = require("./fsx");
+const { appendProductLearningEvent } = require("./product-learning-events");
+
+const SESSION_CONTEXT_CONTRACT = "avorelo.sessionContext.v1";
+const SESSION_CONTEXT_SCHEMA_VERSION = 1;
+const LATEST_CONTEXT_REL_PATH = ".claude/cco/orchestration/session-context/latest-context.json";
+const LATEST_CONTEXT_MD_REL_PATH = ".claude/cco/orchestration/session-context/latest-context.md";
+const CONTEXT_HISTORY_DIR_REL_PATH = ".claude/cco/orchestration/session-context/history";
+const CONTEXT_EVENT_LOG_REL_PATH = ".claude/cco/events/session-context.jsonl";
+
+const DEFAULT_MAX_CHARS = 6000;
+const HARD_MAX_CHARS = 12000;
+
+const SECRET_PATTERN = /(?:sk-[A-Za-z0-9_-]{16,}|ghp_[A-Za-z0-9]{20,}|AKIA[0-9A-Z]{16}|(?:api[_ -]?key|token|password|secret|authorization)\s*[:=]\s*\S+)/i;
+
+function redactIfSecret(text) {
+  if (!text) return text;
+  const s = String(text);
+  return SECRET_PATTERN.test(s) ? "[REDACTED]" : s;
+}
+
+function createContextId() {
+  return `sc-${Date.now()}-${crypto.randomBytes(4).toString("hex")}`;
+}
+
+function estimateTokens(chars) {
+  return Math.ceil(chars / 4);
+}
+
+// ── Source receipt readers ────────────────────────────────────────────────────
+
+function readWorkControlReceipt(cwd) {
+  try {
+    const { readLatestWorkControlReceipt } = require("./work-control-receipts");
+    return readLatestWorkControlReceipt(cwd);
+  } catch {
+    return null;
+  }
+}
+
+function readProof(cwd) {
+  try {
+    const { readCurrentProof } = require("./orchestration");
+    return readCurrentProof(cwd);
+  } catch {
+    return null;
+  }
+}
+
+function readOrBuildWorkspaceMap(cwd, options = {}) {
+  try {
+    const { readWorkspaceMap, writeWorkspaceMap } = require("./workspace-map");
+    const existing = readWorkspaceMap(cwd);
+    if (existing && !options.refreshWorkspaceMap) return existing;
+    return writeWorkspaceMap(cwd, { task: options.task || "" });
+  } catch {
+    return null;
+  }
+}
+
+function readWorkspaceRegistry(cwd) {
+  try {
+    const { readLatestRegistry } = require("./workspace-registry");
+    return readLatestRegistry(cwd);
+  } catch {
+    return null;
+  }
+}
+
+// ── Section builders ──────────────────────────────────────────────────────────
+
+function buildObjectiveSection(options, wcReceipt, proof) {
+  const taskText = redactIfSecret(
+    options.task
+    || wcReceipt?.task?.text
+    || proof?.task
+    || "Session Context / Continuation Optimization Foundation v1"
+  );
+  return String(taskText).slice(0, 300);
+}
+
+function buildCurrentStateSection(wcReceipt) {
+  if (!wcReceipt) {
+    return {
+      finalState: "missing",
+      receiptPath: null,
+      source: "no-work-control-receipt",
+    };
+  }
+  const wc = wcReceipt.workControl || {};
+  return {
+    finalState: wc.finalState || "missing",
+    receiptPath: ".claude/cco/orchestration/work-control/latest-receipt.json",
+    blockedCount: wc.blockedCount || 0,
+    approvalRequiredCount: wc.approvalRequiredCount || 0,
+    highRiskIntakeCount: wc.highRiskIntakeCount || 0,
+    unknownSourcesCount: wc.unknownSourcesCount || 0,
+    source: "work-control-receipt",
+  };
+}
+
+function buildNextSafestAction(wcReceipt) {
+  if (!wcReceipt) {
+    return "Run `node bin/avorelo work-control --json` to establish current state before proceeding.";
+  }
+  return wcReceipt.workControl?.nextSafestAction
+    || "Continue with the smallest local scope. Re-run proof before next session.";
+}
+
+function buildAlreadyDone(wcReceipt, proof) {
+  const items = [];
+  if (wcReceipt?.workControl?.carryForward?.lastRoute) {
+    items.push(`Last route: ${wcReceipt.workControl.carryForward.lastRoute}`);
+  }
+  if (wcReceipt?.workControl?.carryForward?.lastTaskSummary) {
+    items.push(`Last task: ${String(wcReceipt.workControl.carryForward.lastTaskSummary).slice(0, 120)}`);
+  }
+  if (wcReceipt?.evidencePaths?.length) {
+    items.push(`Evidence receipts recorded: ${wcReceipt.evidencePaths.length}`);
+  }
+  if (proof?.runId) {
+    items.push(`Proof run: ${proof.runId}`);
+  }
+  if (proof?.route?.selectedRoute) {
+    items.push(`Route proven: ${proof.route.selectedRoute}`);
+  }
+  return items.length ? items : ["No prior carry-forward found — start from current work-control receipt."];
+}
+
+function buildDoNotRepeat(wcReceipt) {
+  const base = [
+    "Do not broad-scan the repo — use workspace map and named files first.",
+    "Do not paste huge JSON into context — use `avorelo work-control --json` for compact receipts.",
+    "Do not start over — read latest-context.md or work-control receipt to continue.",
+  ];
+  const fromReceipt = wcReceipt?.workControl?.doNotRepeat || [];
+  const combined = [...new Set([...base, ...fromReceipt])];
+  return combined.slice(0, 8);
+}
+
+function buildActiveRisks(wcReceipt) {
+  const risks = [];
+  if (!wcReceipt) {
+    risks.push("No work-control receipt — run `avorelo work-control` before proceeding.");
+    return risks;
+  }
+  const intake = wcReceipt.controls?.installIntake;
+  const governance = wcReceipt.controls?.governance;
+  const safePath = wcReceipt.controls?.safePath;
+
+  if (intake?.highRiskItems > 0) {
+    risks.push(`Install intake: ${intake.highRiskItems} high-risk items — review before tool/MCP use.`);
+  }
+  if (intake?.unknownItems > 0) {
+    risks.push(`Install intake: ${intake.unknownItems} unknown-source items — do not execute without review.`);
+  }
+  if (governance?.subjectTrustStatus === "unknown") {
+    risks.push(`Governance: subject trust status is 'unknown' — requires review before proceeding.`);
+  }
+  if (governance?.decision === "block" || wcReceipt.workControl?.blockedCount > 0) {
+    risks.push(`Governance: blocked action recorded — preserve block, do not bypass.`);
+  }
+  if (safePath?.lastDecision === "recommend_reduced_scope") {
+    risks.push(`Safe Path: reduced scope recommended — use narrow local boundary only.`);
+  }
+  if (!governance?.latestReceiptPath) {
+    risks.push("Governance receipt missing — run `avorelo guard` to establish governance baseline.");
+  }
+  if (!safePath?.latestReceiptPath) {
+    risks.push("Safe Path receipt missing — run `avorelo guard` to establish safe-path baseline.");
+  }
+  return risks.length ? risks : ["No active risks detected — re-run `avorelo work-control` to refresh."];
+}
+
+function buildRelevantFiles(wcReceipt, workspaceMap, options = {}) {
+  const task = String(options.task || wcReceipt?.task?.text || "").toLowerCase();
+  const maxFiles = options.maxFiles || 20;
+  const files = [];
+
+  // Task-aware file selection from workspace map
+  if (workspaceMap) {
+    const taskKeywords = {
+      "session": ["scripts/lib/session-context-optimizer.js", "tests/session-context-optimization.test.js"],
+      "context": ["scripts/lib/session-context-optimizer.js", "scripts/lib/workspace-map.js"],
+      "brain": ["scripts/lib/brain-pack.js", "tests/brain-pack.test.js"],
+      "recipe": ["scripts/lib/brain-pack.js", "tests/brain-pack.test.js"],
+      "work-control": ["scripts/lib/work-control-receipts.js", "tests/work-control-receipts.test.js"],
+      "workspace": ["scripts/lib/workspace-map.js", "tests/workspace-map.test.js"],
+      "registry": ["scripts/lib/workspace-registry.js", "tests/workspace-registry.test.js"],
+      "capability": ["scripts/lib/plans.js", "scripts/lib/capability-registry.js", "scripts/lib/capability-packs.js"],
+      "skill": ["scripts/lib/skills-operating-layer.js", "scripts/lib/avorelo-skill-registry.js"],
+      "intake": ["scripts/lib/install-intake-risk.js", "tests/install-intake-risk.test.js"],
+      "safe-path": ["scripts/lib/safe-path-engine.js"],
+      "governance": ["scripts/lib/agent-access-governance.js", "scripts/lib/agent-enforcement.js"],
+      "product-learning": ["scripts/lib/product-learning-events.js", "docs/Product-Learning-Telemetry.md"],
+      "status": ["scripts/cco-status.js", "scripts/lib/dashboard.js"],
+      "cli": ["scripts/lib/public-cli.js", "bin/avorelo"],
+    };
+
+    for (const [keyword, keyFiles] of Object.entries(taskKeywords)) {
+      if (task.includes(keyword)) {
+        files.push(...keyFiles);
+      }
+    }
+  }
+
+  // Optionally enrich from workspace registry (read latest, do not rebuild)
+  if (options.useRegistry !== false) {
+    const registry = readWorkspaceRegistry(options.cwd || process.cwd());
+    if (registry && Array.isArray(registry.recommendations?.sessionContextRelevantFiles)) {
+      const regFiles = registry.recommendations.sessionContextRelevantFiles.slice(0, 10);
+      files.push(...regFiles);
+    }
+  }
+
+  // Always include core files for this feature
+  const coreFiles = [
+    "scripts/lib/session-context-optimizer.js",
+    "scripts/lib/brain-pack.js",
+    "scripts/lib/work-control-receipts.js",
+    "scripts/lib/workspace-map.js",
+    "scripts/lib/public-cli.js",
+    "scripts/lib/plans.js",
+    "scripts/lib/product-learning-events.js",
+    "tests/session-context-optimization.test.js",
+    "docs/dogfood/session-context-optimization-dogfood.md",
+  ];
+
+  const combined = [...new Set([...files, ...coreFiles])].slice(0, maxFiles);
+  return combined;
+}
+
+// ── Dynamic commands (task/target-aware) ──────────────────────────────────────
+
+const TASK_COMMAND_MAP = [
+  {
+    signals: ["intake", "mcp", "package", "install", "dependency", "risk"],
+    commands: [
+      "node bin/avorelo intake --json",
+      "node bin/avorelo guard --action tool_call --target \"unknown-mcp-server\" --json",
+      "node --test tests/install-intake-risk.test.js",
+    ],
+  },
+  {
+    signals: ["safe-path", "governance", "guard", "block", "agent"],
+    commands: [
+      "node bin/avorelo guard --action file_write --target \".env\" --json",
+      "node --test tests/avorelo-agent-enforcement.test.js",
+    ],
+  },
+  {
+    signals: ["session", "context", "continuation", "handoff", "rediscovery"],
+    commands: [
+      "node bin/avorelo session-context --json",
+      "node bin/avorelo session-context --handoff",
+      "node --test tests/session-context-optimization.test.js",
+    ],
+  },
+  {
+    signals: ["brain", "brain-pack", "brain pack", "context intelligence"],
+    commands: [
+      "node bin/avorelo brain-pack --json",
+      "node --test tests/brain-pack.test.js",
+    ],
+  },
+  {
+    signals: ["skill", "recipe", "workflow", "source-backed"],
+    commands: [
+      "node bin/avorelo skills route --task \"<task>\"",
+    ],
+  },
+  {
+    signals: ["frontend", "browser", "screenshot", "visual", "playwright"],
+    commands: [
+      "node bin/avorelo visual-qa --dry-run",
+    ],
+  },
+  {
+    signals: ["release", "merge", "ci", "build", "validate", "pr", "pull request"],
+    commands: [
+      "node scripts/validate-operating-layer.js",
+      "cmd /c npm test",
+      "node bin/avorelo proof",
+    ],
+  },
+];
+
+const BASE_COMMANDS = [
+  "node bin/avorelo work-control --json",
+  "node bin/avorelo session-context --json",
+  "node bin/avorelo session-context --handoff",
+  "node bin/avorelo proof",
+];
+
+function buildRelevantCommands(task, targetSurface, wcReceipt, options = {}) {
+  const taskStr = String(task || wcReceipt?.task?.text || "").toLowerCase();
+  const matched = [];
+
+  for (const entry of TASK_COMMAND_MAP) {
+    if (entry.signals.some((s) => taskStr.includes(s))) {
+      matched.push(...entry.commands);
+    }
+  }
+
+  // Substitute <task> placeholder
+  const taskSlice = String(task || wcReceipt?.task?.text || "current task").slice(0, 60);
+  const substituted = matched.map((c) => c.replace(/<task>/g, taskSlice));
+
+  const combined = [...new Set([...BASE_COMMANDS, ...substituted])];
+
+  // Target-specific filtering
+  if (targetSurface === "local_model") {
+    // Local model: minimal — only the most essential
+    return combined.slice(0, 3);
+  }
+  if (targetSurface === "codex") {
+    // Codex: command/test oriented — drop explanation-heavy ones
+    return combined
+      .filter((c) => c.includes("--test") || c.includes("npm test") || c.includes("validate-operating-layer") || c.includes("work-control") || c.includes("proof"))
+      .slice(0, 6);
+  }
+
+  return combined.slice(0, 8);
+}
+
+// ── Skills route fallback ──────────────────────────────────────────────────────
+
+function buildSkillsRouteFallback(wcReceipt, task) {
+  const skills = wcReceipt?.controls?.skills;
+  const skillsReceiptMissing = !skills || skills.status === "missing" || !skills.latestRouteReceiptPath;
+
+  if (!skillsReceiptMissing) return null;
+
+  const taskStr = String(task || wcReceipt?.task?.text || "");
+  if (!taskStr) return null;
+
+  // Only recommend fallback for task types where skills route is useful
+  const skillsSignals = ["skill", "recipe", "workflow", "reference", "source-backed", "build", "implement", "refactor"];
+  const isRelevant = skillsSignals.some((s) => taskStr.toLowerCase().includes(s));
+  if (!isRelevant) return null;
+
+  return {
+    fallbackCommand: `node bin/avorelo skills route --task "${taskStr.slice(0, 60)}"`,
+    reason: "No skills route receipt found — run this command to get source-backed workflow guidance.",
+    note: "This is a fallback only. Skills route is not run automatically.",
+  };
+}
+
+function buildModelEffortRecommendation(wcReceipt, proof) {
+  if (!proof?.route) {
+    if (!wcReceipt) {
+      return {
+        source: "none",
+        recommendation: "Run `avorelo route <task>` to get model/effort recommendation.",
+      };
+    }
+    return {
+      source: "work-control",
+      recommendation: wcReceipt.workControl?.nextSafestAction
+        ? "Use smallest safe local scope per work-control guidance."
+        : "No route available — run `avorelo route <task>` for routing recommendation.",
+    };
+  }
+  const route = proof.route;
+  return {
+    source: "proof-route",
+    selectedRoute: route.selectedRoute || null,
+    chosenTool: route.chosenTool || null,
+    selectedModel: route.selectedModel || null,
+    chosenModelProfile: route.chosenModelProfile || null,
+    fallbackTool: route.fallbackTool || null,
+    recommendation: [
+      route.chosenTool ? `Use: ${route.chosenTool}` : null,
+      route.selectedModel ? `Model: ${route.selectedModel}` : null,
+      route.chosenModelProfile ? `Profile: ${route.chosenModelProfile}` : null,
+      (route.safetyNotes || []).slice(0, 2).join("; ") || null,
+    ].filter(Boolean).join(" · ") || "Use medium scope, local-first.",
+  };
+}
+
+function buildSkillsHints(wcReceipt) {
+  const skills = wcReceipt?.controls?.skills;
+  if (!skills || skills.status === "missing") {
+    return null;
+  }
+  return {
+    status: skills.status,
+    reviewedSources: skills.reviewedSources || 0,
+    deferredSources: skills.deferredSources || 0,
+    latestRouteReceiptPath: skills.latestRouteReceiptPath || null,
+    hint: skills.deferredSources > 0
+      ? `${skills.deferredSources} skill sources deferred — do not use without intake review.`
+      : "Skill sources reviewed — use existing skill route receipt.",
+  };
+}
+
+function buildReceiptPathSummary(wcReceipt) {
+  const paths = [];
+  paths.push("work-control: .claude/cco/orchestration/work-control/latest-receipt.json");
+  const cf = wcReceipt?.workControl?.carryForward;
+  if (cf?.receiptPaths?.length) {
+    paths.push(...cf.receiptPaths.slice(0, 5));
+  }
+  const unchecked = cf?.uncheckedItems || [];
+  return { checked: paths, unchecked };
+}
+
+// ── Compact prompt builder ────────────────────────────────────────────────────
+
+function buildCompactPrompt(sessionStart, targetSurface) {
+  const toolName = targetSurface === "codex"
+    ? "Codex"
+    : targetSurface === "local_model"
+      ? "your local model"
+      : "Claude";
+
+  const lines = [
+    `# Start here — do not rediscover repo`,
+    "",
+    `**Task:** ${sessionStart.objective}`,
+    "",
+    `**Current state:** ${sessionStart.currentState.finalState?.toUpperCase() || "UNKNOWN"}`,
+    `**Next safest action:** ${sessionStart.nextSafestAction}`,
+    "",
+    "## Do not repeat",
+    ...(sessionStart.doNotRepeat || []).slice(0, 5).map((item) => `- ${item}`),
+    "",
+    "## Relevant files (start here)",
+    ...(sessionStart.relevantFiles || []).slice(0, 12).map((f) => `- ${f}`),
+    "",
+    "## Commands to run first",
+    ...(sessionStart.relevantCommands || []).slice(0, 5).map((c) => `- \`${c}\``),
+    "",
+    "## Active risks",
+    ...(sessionStart.activeRisks || []).slice(0, 4).map((r) => `- ${r}`),
+  ];
+
+  if (sessionStart.recommendedModelOrWorker?.recommendation) {
+    lines.push("", `**Model/effort:** ${sessionStart.recommendedModelOrWorker.recommendation}`);
+  }
+
+  if (sessionStart.skillsHints) {
+    lines.push("", `**Skills:** ${sessionStart.skillsHints.hint}`);
+  }
+
+  if (sessionStart.skillsRouteFallback) {
+    lines.push("", `**Skills fallback:** ${sessionStart.skillsRouteFallback.reason}`);
+    lines.push(`  Command: \`${sessionStart.skillsRouteFallback.fallbackCommand}\``);
+  }
+
+  if (sessionStart.capabilityRecommendation?.recommendedCapabilityPack) {
+    lines.push("", `**Capability:** ${sessionStart.capabilityRecommendation.recommendedCapabilityPackName || sessionStart.capabilityRecommendation.recommendedCapabilityPack}`);
+    lines.push(`  Why: ${sessionStart.capabilityRecommendation.capabilityReason || ""}`);
+  }
+
+  if (sessionStart.nextRunContext?.compactText) {
+    lines.push("", sessionStart.nextRunContext.compactText);
+  }
+
+  lines.push(
+    "",
+    `*Context generated by Avorelo session-context. Do not paste raw receipts — use \`avorelo work-control --json\` for live state.*`,
+  );
+
+  return lines.join("\n");
+}
+
+// ── Context budget guard ──────────────────────────────────────────────────────
+
+function applyContextBudget(context, maxChars) {
+  const hard = Math.min(maxChars, HARD_MAX_CHARS);
+  const sections = context.sessionStart;
+  const prompt = buildCompactPrompt(sections, context.targetSurface || "generic");
+
+  if (prompt.length <= hard) {
+    return {
+      compactPrompt: prompt,
+      truncationApplied: false,
+      includedSections: Object.keys(sections),
+      excludedSections: [],
+      estimatedTokens: estimateTokens(prompt.length),
+      avoidedJsonDump: true,
+      avoidedBroadRediscovery: true,
+    };
+  }
+
+  // Drop lowest priority sections to fit budget
+  const dropOrder = [
+    "alreadyDone",
+    "receiptPathSummary",
+    "skillsHints",
+    "recommendedModelOrWorker",
+    "relevantFiles",
+    "activeRisks",
+  ];
+
+  const reduced = { ...sections };
+  const excluded = [];
+
+  for (const key of dropOrder) {
+    const test = buildCompactPrompt(reduced, context.targetSurface || "generic");
+    if (test.length <= hard) break;
+    if (key in reduced) {
+      delete reduced[key];
+      excluded.push(key);
+    }
+  }
+
+  const finalPrompt = buildCompactPrompt(reduced, context.targetSurface || "generic");
+  return {
+    compactPrompt: finalPrompt,
+    truncationApplied: excluded.length > 0,
+    includedSections: Object.keys(reduced),
+    excludedSections: excluded,
+    estimatedTokens: estimateTokens(finalPrompt.length),
+    avoidedJsonDump: true,
+    avoidedBroadRediscovery: true,
+  };
+}
+
+// ── Markdown handoff builder ──────────────────────────────────────────────────
+
+function buildMarkdownHandoff(context, budgetResult) {
+  const targetLabel = {
+    claude: "Claude Code",
+    codex: "Codex",
+    local_model: "Local Model",
+    generic: "AI Assistant",
+  }[context.targetSurface || "generic"] || "AI Assistant";
+
+  const s = context.sessionStart;
+  const lines = [
+    `# Avorelo Session Context — ${targetLabel}`,
+    `> **Start here — do not rediscover repo**`,
+    `> Generated: ${context.createdAt}`,
+    `> Context ID: ${context.contextId}`,
+    "",
+    `## Task`,
+    s.objective,
+    "",
+    `## Current State`,
+    `- **Status:** ${s.currentState?.finalState?.toUpperCase() || "UNKNOWN"}`,
+    s.currentState?.blockedCount > 0 ? `- **Blocked actions:** ${s.currentState.blockedCount}` : null,
+    s.currentState?.highRiskIntakeCount > 0 ? `- **High-risk intake items:** ${s.currentState.highRiskIntakeCount}` : null,
+    `- **Receipt:** \`.claude/cco/orchestration/work-control/latest-receipt.json\``,
+    "",
+    `## Next Safest Action`,
+    s.nextSafestAction,
+    "",
+    `## Do Not Repeat`,
+    ...(s.doNotRepeat || []).map((item) => `- ${item}`),
+    "",
+    `## Relevant Files`,
+    ...(s.relevantFiles || []).map((f) => `- \`${f}\``),
+    "",
+    `## Commands to Run First`,
+    ...(s.relevantCommands || []).map((c) => `- \`${c}\``),
+    "",
+    `## Active Risks`,
+    ...(s.activeRisks || []).map((r) => `- ${r}`),
+    "",
+  ].filter((line) => line !== null);
+
+  if (s.alreadyDone?.length) {
+    lines.push("## Already Done");
+    s.alreadyDone.forEach((item) => lines.push(`- ${item}`));
+    lines.push("");
+  }
+
+  if (s.recommendedModelOrWorker?.recommendation) {
+    lines.push("## Model / Effort");
+    lines.push(s.recommendedModelOrWorker.recommendation);
+    lines.push("");
+  }
+
+  if (s.skillsHints) {
+    lines.push("## Skills Continuation");
+    lines.push(s.skillsHints.hint);
+    lines.push("");
+  }
+
+  if (s.skillsRouteFallback) {
+    lines.push("## Skills Route Fallback");
+    lines.push(s.skillsRouteFallback.reason);
+    lines.push(`\`${s.skillsRouteFallback.fallbackCommand}\``);
+    lines.push("");
+  }
+
+  if (s.capabilityRecommendation?.recommendedCapabilityPack) {
+    const cap = s.capabilityRecommendation;
+    lines.push("## Recommended Capability");
+    lines.push(`- Pack: **${cap.recommendedCapabilityPackName || cap.recommendedCapabilityPack}**`);
+    lines.push(`- Why: ${cap.capabilityReason || ""}`);
+    lines.push(`- Next: ${cap.capabilityNextAction || ""}`);
+    if (cap.additionalCapabilityPacks?.length) {
+      lines.push(`- Also relevant: ${cap.additionalCapabilityPacks.map((p) => p.name).join(", ")}`);
+    }
+    lines.push("");
+  }
+
+  if (s.brainPackSummary) {
+    const bp = s.brainPackSummary;
+    lines.push("## Brain Pack");
+    lines.push(`- Project: ${bp.projectName || ""}`);
+    lines.push(`- Stage: ${bp.currentRoadmapStage || ""}`);
+    if (bp.detectedRecipe) lines.push(`- Recipe: ${bp.detectedRecipe}`);
+    lines.push(`- Path: \`${bp.jsonPath}\``);
+    lines.push("");
+  }
+
+  if (s.targetSpecific) {
+    const ts = s.targetSpecific;
+    lines.push(`## Target: ${ts.targetLabel}`);
+    lines.push(ts.topNote);
+    if (ts.architectureNote) lines.push(`> ${ts.architectureNote}`);
+    if (ts.doNotStart?.length) {
+      ts.doNotStart.forEach((d) => lines.push(`- ${d}`));
+    }
+    lines.push("");
+  }
+
+  if (s.nextRunContext?.compactText) {
+    lines.push("## Run Improvements · Next-Run Context");
+    lines.push(s.nextRunContext.compactText);
+    lines.push(`- Status: ${s.nextRunContext.status} · ${s.nextRunContext.defaultsCount} default(s)`);
+    lines.push(`- Artifact: \`${s.nextRunContext.artifactPath}\``);
+    lines.push("");
+  }
+
+  lines.push("## Context Budget");
+  lines.push(`- Estimated tokens: ${budgetResult.estimatedTokens}`);
+  lines.push(`- Truncation applied: ${budgetResult.truncationApplied}`);
+  if (budgetResult.excludedSections.length) {
+    lines.push(`- Excluded sections: ${budgetResult.excludedSections.join(", ")}`);
+  }
+  lines.push("");
+  lines.push("---");
+  lines.push("*Generated by `avorelo session-context`. Do not paste raw receipts — use `avorelo work-control --json` for live state.*");
+
+  return lines.join("\n");
+}
+
+// ── Main build function ───────────────────────────────────────────────────────
+
+// ── Capability recommender integration ────────────────────────────────────────
+
+function readCapabilityRecommendation(cwd) {
+  try {
+    const { recommendCapabilities } = require("./capability-recommender");
+    const rec = recommendCapabilities({ cwd, signals: {}, plan: "free" });
+    return {
+      recommendedCapabilityPack: rec.recommendedPack?.id || null,
+      recommendedCapabilityPackName: rec.recommendedPack?.name || null,
+      capabilityReason: rec.reason || null,
+      capabilityNextAction: rec.nextAction || null,
+      capabilityFirstCommand: rec.nextAction
+        ? rec.nextAction.replace(/^Run\s+/, "").replace(/\s+to\s.*$/, "").replace(/[`'"]/g, "").trim()
+        : null,
+      additionalCapabilityPacks: (rec.additionalPacks || []).map((p) => ({
+        id: p.id,
+        name: p.name,
+      })),
+    };
+  } catch {
+    return null;
+  }
+}
+
+// ── Brain Pack reader (safe) ──────────────────────────────────────────────────
+
+function readBrainPackForContext(cwd) {
+  try {
+    const { readLatestBrainPack } = require("./brain-pack");
+    const bp = readLatestBrainPack(cwd);
+    if (!bp) return null;
+    // Return a compact summary only — never the full brain pack
+    return {
+      brainPackId: bp.brainPackId,
+      projectName: bp.project?.name || null,
+      currentRoadmapStage: bp.project?.currentRoadmapStage || null,
+      contextRules: bp.contextRules || null,
+      lastWorkControlFinalState: bp.signals?.lastWorkControlFinalState || null,
+      capabilityRecommended: bp.capabilityRecommendation?.recommendedPackId || null,
+      recipesCount: (bp.recipes || []).length,
+      detectedRecipe: (bp.recipes || [])[0]?.detectedRecipe || null,
+      jsonPath: ".claude/cco/context/brain-pack/latest.json",
+    };
+  } catch {
+    return null;
+  }
+}
+
+// ── Target-specific context additions ────────────────────────────────────────
+
+function buildTargetSpecificGuidance(targetSurface, objective, capabilityRec) {
+  switch (targetSurface) {
+    case "claude":
+      return {
+        targetLabel: "Claude Code",
+        emphasis: "full context, architecture awareness, named files, bounded implementation",
+        topNote: "Do not rediscover repo. Read named files first. Inspect before coding. Keep scope bounded.",
+        architectureNote: "Capability Recommender is the single router — no duplicate routing tables.",
+        doNotStart: capabilityRec?.additionalCapabilityPacks?.map((p) => `Do not start ${p.name} work in this session`) || [],
+      };
+    case "codex":
+      return {
+        targetLabel: "Codex",
+        emphasis: "command/test oriented, short scope, exact validation commands",
+        topNote: "Use exact commands. Run tests to verify. Avoid broad explanation. Stay within bounded scope.",
+        architectureNote: null,
+        doNotStart: ["Do not do broad codebase explanation.", "Use exact test commands to verify changes."],
+      };
+    case "local_model":
+      return {
+        targetLabel: "Local Model",
+        emphasis: "shortest context, fewer files, simple tasks only",
+        topNote: "Minimal context. Simple bounded task only. Do not attempt architecture-heavy changes.",
+        architectureNote: null,
+        doNotStart: ["Do not attempt complex multi-file changes.", "Prefer single-file bounded edits."],
+      };
+    default:
+      return {
+        targetLabel: "AI Assistant",
+        emphasis: "neutral compact handoff",
+        topNote: "Start from current state. Do not rediscover repo. Use named files.",
+        architectureNote: null,
+        doNotStart: [],
+      };
+  }
+}
+
+function buildSessionContext(cwd, options = {}) {
+  const maxChars = Math.min(
+    options.maxChars || DEFAULT_MAX_CHARS,
+    HARD_MAX_CHARS,
+  );
+  const targetSurface = options.targetSurface || "generic";
+  const task = options.task;
+
+  const wcReceipt = readWorkControlReceipt(cwd);
+  const proof = readProof(cwd);
+  const workspaceMap = readOrBuildWorkspaceMap(cwd, {
+    refreshWorkspaceMap: options.refreshWorkspaceMap || false,
+    task: task || wcReceipt?.task?.text || "",
+  });
+
+  const objective = buildObjectiveSection(options, wcReceipt, proof);
+  const currentState = buildCurrentStateSection(wcReceipt);
+  const nextSafestAction = buildNextSafestAction(wcReceipt);
+  const alreadyDone = buildAlreadyDone(wcReceipt, proof);
+  const doNotRepeat = buildDoNotRepeat(wcReceipt);
+  const activeRisks = buildActiveRisks(wcReceipt);
+  const relevantFiles = buildRelevantFiles(wcReceipt, workspaceMap, {
+    task: task || wcReceipt?.task?.text || "",
+    maxFiles: 20,
+    cwd,
+  });
+  const relevantCommands = buildRelevantCommands(task, targetSurface, wcReceipt, {});
+  const recommendedModelOrWorker = buildModelEffortRecommendation(wcReceipt, proof);
+  const skillsHints = buildSkillsHints(wcReceipt);
+  const skillsRouteFallback = buildSkillsRouteFallback(wcReceipt, task || wcReceipt?.task?.text);
+  const receiptPathSummary = buildReceiptPathSummary(wcReceipt);
+
+  // Next-run context (run improvements + learning) — compact injection only
+  let nextRunContext = null;
+  try {
+    const { loadNextRunContext, buildCompactContextText } = require("./next-run-context");
+    const nrc = loadNextRunContext(cwd);
+    if (nrc && (nrc.status === "prepared" || nrc.status === "applied" || nrc.status === "injected") && (nrc.appliedDefaults || []).length > 0) {
+      nextRunContext = {
+        status: nrc.status,
+        defaultsCount: (nrc.appliedDefaults || []).length,
+        topDefault: (nrc.appliedDefaults || [])[0]?.text || null,
+        compactText: buildCompactContextText(nrc),
+        artifactPath: ".claude/cco/state/next-run-context.json",
+      };
+    }
+  } catch {}
+
+  // Capability recommender integration (reuse, do not duplicate)
+  const capabilityRecommendation = readCapabilityRecommendation(cwd);
+
+  // Brain pack compact inclusion
+  const brainPackSummary = readBrainPackForContext(cwd);
+
+  // Target-specific guidance
+  const targetSpecific = buildTargetSpecificGuidance(targetSurface, objective, capabilityRecommendation);
+
+  const sessionStart = {
+    objective,
+    currentState,
+    nextSafestAction,
+    alreadyDone,
+    doNotRepeat,
+    activeRisks,
+    relevantFiles,
+    relevantCommands,
+    recommendedModelOrWorker,
+    skillsHints,
+    skillsRouteFallback,
+    receiptPathSummary,
+    contextBudget: { maxChars, hardMaxChars: HARD_MAX_CHARS },
+    capabilityRecommendation,
+    brainPackSummary,
+    targetSpecific,
+    nextRunContext,
+  };
+
+  const contextId = createContextId();
+  const createdAt = nowIso();
+
+  const baseContext = {
+    schemaVersion: SESSION_CONTEXT_SCHEMA_VERSION,
+    contract: SESSION_CONTEXT_CONTRACT,
+    contextType: "session_start",
+    contextId,
+    createdAt,
+    targetSurface,
+    sourceReceipts: {
+      workControl: wcReceipt ? ".claude/cco/orchestration/work-control/latest-receipt.json" : null,
+      proof: proof ? ".claude/cco/orchestration/current-proof.json" : null,
+      route: proof?.route ? "via-proof" : null,
+      intake: wcReceipt?.controls?.installIntake?.latestReceiptPath || null,
+      governance: wcReceipt?.controls?.governance?.latestReceiptPath || null,
+      safePath: wcReceipt?.controls?.safePath?.latestReceiptPath || null,
+      skills: wcReceipt?.controls?.skills?.latestRouteReceiptPath || null,
+      workspaceMap: workspaceMap?.artifactPath || null,
+    },
+    sessionStart,
+  };
+
+  const budgetResult = applyContextBudget(baseContext, maxChars);
+  const markdownHandoff = buildMarkdownHandoff(baseContext, budgetResult);
+
+  baseContext.sessionStart.compactPrompt = budgetResult.compactPrompt;
+  baseContext.sessionStart.markdownHandoff = markdownHandoff;
+
+  baseContext.tokenDiscipline = {
+    maxChars,
+    estimatedTokens: budgetResult.estimatedTokens,
+    avoidedJsonDump: budgetResult.avoidedJsonDump,
+    avoidedBroadRediscovery: budgetResult.avoidedBroadRediscovery,
+    includedSections: budgetResult.includedSections,
+    excludedSections: budgetResult.excludedSections,
+    truncationApplied: budgetResult.truncationApplied,
+  };
+
+  // Brain Pack is now real — scaffold is superseded
+  baseContext.brainPackUsed = Boolean(brainPackSummary);
+  baseContext.brainPackSummary = brainPackSummary;
+  baseContext.targetSpecificOutput = targetSurface !== "generic";
+  baseContext.dynamicCommands = true;
+
+  baseContext.featureCoverageLedger = [
+    { feature: "compact_session_start_context", status: "implemented_now" },
+    { feature: "continuation_packet_from_work_control", status: "implemented_now" },
+    { feature: "do_not_repeat_guidance", status: "implemented_now" },
+    { feature: "branch_worktree_task_summary", status: "implemented_now" },
+    { feature: "receipt_path_summary", status: "implemented_now" },
+    { feature: "next_safest_action", status: "implemented_now" },
+    { feature: "what_was_checked_not_checked", status: "implemented_now" },
+    { feature: "relevant_files_from_workspace_map", status: "implemented_now" },
+    { feature: "avoid_huge_json_dumps", status: "implemented_now" },
+    { feature: "avoid_broad_repo_rediscovery", status: "implemented_now" },
+    { feature: "context_budget_guard", status: "implemented_now" },
+    { feature: "model_effort_recommendation_summary", status: "implemented_now" },
+    { feature: "skills_aware_continuation_hints", status: "implemented_now" },
+    { feature: "intake_governance_safe_path_risk_summary", status: "implemented_now" },
+    { feature: "cli_command_session_context", status: "implemented_now" },
+    { feature: "product_learning_events", status: "implemented_now" },
+    { feature: "status_proof_dashboard_compact_surface", status: "implemented_now" },
+    { feature: "dogfood_with_avorelo_on_this_pr", status: "implemented_now" },
+    { feature: "brain_pack_basic", status: "implemented_now" },
+    { feature: "recipe_detection_basic", status: "implemented_now" },
+    { feature: "dynamic_relevant_commands", status: "implemented_now" },
+    { feature: "target_specific_handoff", status: "implemented_now" },
+    { feature: "skills_route_fallback", status: "implemented_now" },
+    { feature: "capability_recommender_context_bridge", status: "implemented_now" },
+    { feature: "dogfood_feedback_loop_structured", status: "implemented_now" },
+    { feature: "task_context_pack_builder_shape", status: "scaffolded_now" },
+    { feature: "post_run_proof_summary_hook", status: "scaffolded_now" },
+    { feature: "tool_connector_gating_hook", status: "scaffolded_now" },
+    { feature: "local_premium_routing_hints", status: "scaffolded_now" },
+    { feature: "token_savings_estimate", status: "scaffolded_now" },
+    { feature: "adapter_output_hook", status: "scaffolded_now" },
+    { feature: "full_brain_pack_management", status: "documented_deferred" },
+    { feature: "full_ai_workflow_discipline_system", status: "documented_deferred" },
+    { feature: "workflow_intelligence_radar", status: "documented_deferred" },
+    { feature: "ai_workspace_registry_asset_inventory", status: "documented_deferred" },
+    { feature: "browser_proof_evidence", status: "documented_deferred" },
+    { feature: "full_token_cost_analytics_dashboard", status: "documented_deferred" },
+    { feature: "full_recipe_library", status: "documented_deferred" },
+    { feature: "full_model_gateway_optillm", status: "documented_deferred" },
+    { feature: "team_cloud_sync", status: "documented_deferred" },
+    { feature: "pricing_website_plugin_launch", status: "documented_deferred" },
+  ];
+
+  baseContext.productLearning = {
+    eventsWritten: 0,
+    suggestedEvents: [
+      "session_context_generated",
+      "session_context_handoff_generated",
+      "context_budget_applied",
+      "broad_rediscovery_avoided",
+      "huge_json_dump_avoided",
+      "continuation_packet_used",
+      "model_effort_recommendation_generated",
+      "brain_pack_used_in_session_context",
+      "dynamic_commands_generated",
+      "target_specific_handoff_generated",
+      "capability_recommendation_embedded",
+      "skills_route_fallback_recommended",
+    ],
+  };
+
+  baseContext.redacted = true;
+  return baseContext;
+}
+
+function writeSessionContext(cwd, context, options = {}) {
+  ensureCcoDirs(cwd);
+
+  const fs2 = require("fs");
+  const path2 = require("path");
+
+  // Ensure session-context dir exists
+  const scDir = path2.join(cwd, ".claude", "cco", "orchestration", "session-context");
+  fs2.mkdirSync(scDir, { recursive: true });
+
+  // Write latest JSON (without markdownHandoff to keep it compact)
+  const jsonPayload = { ...context };
+  const { markdownHandoff, compactPrompt, ...sessionStartWithoutBulky } = context.sessionStart;
+  jsonPayload.sessionStart = {
+    ...sessionStartWithoutBulky,
+    compactPromptLength: compactPrompt?.length || 0,
+    markdownHandoffLength: markdownHandoff?.length || 0,
+    markdownHandoffPath: LATEST_CONTEXT_MD_REL_PATH,
+  };
+  safeWriteJson(cwd, LATEST_CONTEXT_REL_PATH, jsonPayload);
+
+  // Write latest Markdown
+  safeWriteText(cwd, LATEST_CONTEXT_MD_REL_PATH, markdownHandoff || "");
+
+  // Write history (plan-gated)
+  const canExport = options.plan && options.plan !== "free";
+  if (canExport) {
+    const historyDir = path2.join(cwd, CONTEXT_HISTORY_DIR_REL_PATH);
+    fs2.mkdirSync(historyDir, { recursive: true });
+    safeWriteJson(cwd, `${CONTEXT_HISTORY_DIR_REL_PATH}/${context.contextId}.json`, jsonPayload);
+  }
+
+  // Append to event log
+  const eventLine = {
+    contextId: context.contextId,
+    finalState: context.sessionStart?.currentState?.finalState || "missing",
+    estimatedTokens: context.tokenDiscipline?.estimatedTokens || 0,
+    truncationApplied: context.tokenDiscipline?.truncationApplied || false,
+    targetSurface: context.targetSurface || "generic",
+    createdAt: context.createdAt,
+  };
+  try {
+    const abs = path2.join(cwd, CONTEXT_EVENT_LOG_REL_PATH);
+    fs2.mkdirSync(path2.dirname(abs), { recursive: true });
+    fs2.appendFileSync(abs, `${JSON.stringify(eventLine)}\n`, "utf8");
+  } catch {}
+
+  // Write product learning events
+  let eventsWritten = 0;
+  const productEvents = [
+    {
+      eventName: "session_context_generated",
+      category: "session_context",
+      status: "completed",
+      payload: {
+        finalState: context.sessionStart?.currentState?.finalState || "missing",
+        estimatedTokens: context.tokenDiscipline?.estimatedTokens || 0,
+        truncationApplied: context.tokenDiscipline?.truncationApplied || false,
+        targetSurface: context.targetSurface || "generic",
+        avoidedJsonDump: context.tokenDiscipline?.avoidedJsonDump || false,
+        avoidedBroadRediscovery: context.tokenDiscipline?.avoidedBroadRediscovery || false,
+      },
+    },
+    {
+      eventName: "context_budget_applied",
+      category: "session_context",
+      status: "completed",
+      payload: {
+        maxChars: context.tokenDiscipline?.maxChars || DEFAULT_MAX_CHARS,
+        estimatedTokens: context.tokenDiscipline?.estimatedTokens || 0,
+        truncationApplied: context.tokenDiscipline?.truncationApplied || false,
+        excludedSectionsCount: (context.tokenDiscipline?.excludedSections || []).length,
+      },
+    },
+    {
+      eventName: "broad_rediscovery_avoided",
+      category: "session_context",
+      status: "completed",
+      payload: {
+        relevantFilesCount: (context.sessionStart?.relevantFiles || []).length,
+        workspaceMapUsed: Boolean(context.sourceReceipts?.workspaceMap),
+      },
+    },
+    {
+      eventName: "huge_json_dump_avoided",
+      category: "session_context",
+      status: "completed",
+      payload: {
+        avoidedJsonDump: true,
+        estimatedTokens: context.tokenDiscipline?.estimatedTokens || 0,
+      },
+    },
+    {
+      eventName: "continuation_packet_used",
+      category: "session_context",
+      status: "completed",
+      payload: {
+        workControlReceiptAvailable: Boolean(context.sourceReceipts?.workControl),
+        carryForwardAvailable: Boolean(context.sessionStart?.alreadyDone?.length),
+      },
+    },
+  ];
+
+  if (context.sessionStart?.recommendedModelOrWorker?.source !== "none") {
+    productEvents.push({
+      eventName: "model_effort_recommendation_generated",
+      category: "session_context",
+      status: "completed",
+      payload: {
+        source: context.sessionStart.recommendedModelOrWorker.source || "unknown",
+        hasChosenTool: Boolean(context.sessionStart.recommendedModelOrWorker.chosenTool),
+      },
+    });
+  }
+
+  if (context.brainPackUsed) {
+    productEvents.push({
+      eventName: "brain_pack_used_in_session_context",
+      category: "brain_pack",
+      status: "completed",
+      payload: {
+        brainPackId: context.brainPackSummary?.brainPackId || null,
+        detectedRecipe: context.brainPackSummary?.detectedRecipe || null,
+      },
+    });
+  }
+
+  if (context.dynamicCommands) {
+    productEvents.push({
+      eventName: "dynamic_commands_generated",
+      category: "session_context",
+      status: "completed",
+      payload: {
+        commandsCount: (context.sessionStart?.relevantCommands || []).length,
+        targetSurface: context.targetSurface || "generic",
+      },
+    });
+  }
+
+  if (context.targetSpecificOutput) {
+    productEvents.push({
+      eventName: "target_specific_handoff_generated",
+      category: "session_context",
+      status: "completed",
+      payload: {
+        targetSurface: context.targetSurface || "generic",
+        targetLabel: context.sessionStart?.targetSpecific?.targetLabel || null,
+      },
+    });
+  }
+
+  if (context.sessionStart?.capabilityRecommendation?.recommendedCapabilityPack) {
+    productEvents.push({
+      eventName: "capability_recommendation_embedded",
+      category: "session_context",
+      status: "completed",
+      payload: {
+        recommendedPackId: context.sessionStart.capabilityRecommendation.recommendedCapabilityPack,
+        additionalPacksCount: (context.sessionStart.capabilityRecommendation.additionalCapabilityPacks || []).length,
+      },
+    });
+  }
+
+  if (context.sessionStart?.skillsRouteFallback) {
+    productEvents.push({
+      eventName: "skills_route_fallback_recommended",
+      category: "session_context",
+      status: "completed",
+      payload: {
+        reason: context.sessionStart.skillsRouteFallback.reason || null,
+      },
+    });
+  }
+
+  productEvents.forEach((event) => {
+    try {
+      appendProductLearningEvent(cwd, event);
+      eventsWritten += 1;
+    } catch {}
+  });
+
+  context.productLearning.eventsWritten = eventsWritten;
+  return LATEST_CONTEXT_REL_PATH;
+}
+
+function readLatestSessionContext(cwd) {
+  return safeReadJson(cwd, LATEST_CONTEXT_REL_PATH, null);
+}
+
+function buildSessionContextSurface(cwd) {
+  const latest = readLatestSessionContext(cwd);
+  if (!latest) {
+    return {
+      status: "missing",
+      latestContextPath: null,
+      latestMarkdownPath: null,
+      estimatedTokens: 0,
+      avoidedJsonDump: false,
+      avoidedBroadRediscovery: false,
+      contextBudgetStatus: "no-context-generated",
+      nextAction: "Run `avorelo session-context` to generate the first session context.",
+      showInStatus: true,
+      showInDashboard: true,
+      statusLine: "Session Context: MISSING · no context generated yet",
+    };
+  }
+
+  const td = latest.tokenDiscipline || {};
+  const budgetStatus = td.truncationApplied ? "truncated" : "within-budget";
+
+  return {
+    status: "active",
+    latestContextPath: LATEST_CONTEXT_REL_PATH,
+    latestMarkdownPath: LATEST_CONTEXT_MD_REL_PATH,
+    estimatedTokens: td.estimatedTokens || 0,
+    avoidedJsonDump: td.avoidedJsonDump || false,
+    avoidedBroadRediscovery: td.avoidedBroadRediscovery || false,
+    contextBudgetStatus: budgetStatus,
+    finalState: latest.sessionStart?.currentState?.finalState || "missing",
+    brainPackUsed: latest.brainPackUsed || false,
+    targetSpecificOutput: latest.targetSpecificOutput || false,
+    dynamicCommands: latest.dynamicCommands || false,
+    recommendedCapabilityPack: latest.sessionStart?.capabilityRecommendation?.recommendedCapabilityPack || null,
+    nextAction: latest.sessionStart?.nextSafestAction
+      || "Continue from session context — run `avorelo session-context --handoff`.",
+    showInStatus: true,
+    showInDashboard: true,
+    statusLine: `Session Context: ${budgetStatus.toUpperCase()} · ~${td.estimatedTokens || 0} tokens · latest ${LATEST_CONTEXT_REL_PATH}`,
+  };
+}
+
+function formatSessionContextText(contextOrSurface, options = {}) {
+  const isHandoff = options.handoff === true;
+  const targetSurface = options.targetSurface || contextOrSurface?.targetSurface || "generic";
+
+  if (!contextOrSurface) {
+    return "Session Context: MISSING · run `avorelo session-context` to generate.\n";
+  }
+
+  if (contextOrSurface.contract === SESSION_CONTEXT_CONTRACT) {
+    const ctx = contextOrSurface;
+    const s = ctx.sessionStart || {};
+
+    if (isHandoff) {
+      return (s.markdownHandoff || buildMarkdownHandoff(ctx, { estimatedTokens: 0, truncationApplied: false, excludedSections: [] })) + "\n";
+    }
+
+    const lines = [
+      `Session Context: ${ctx.contextId}`,
+      `State: ${s.currentState?.finalState?.toUpperCase() || "UNKNOWN"}`,
+      `Target: ${ctx.targetSurface || "generic"}`,
+      `Next: ${s.nextSafestAction || "Continue from context."}`,
+      `Capability: ${s.capabilityRecommendation?.recommendedCapabilityPackName || "none"}`,
+      `BrainPack: ${ctx.brainPackUsed ? "used" : "missing"}`,
+      `Tokens: ~${ctx.tokenDiscipline?.estimatedTokens || 0}`,
+      `Budget: ${ctx.tokenDiscipline?.truncationApplied ? "truncated" : "within-budget"}`,
+      `Context: ${LATEST_CONTEXT_REL_PATH}`,
+      `Handoff: ${LATEST_CONTEXT_MD_REL_PATH}`,
+    ];
+
+    return lines.join("\n") + "\n";
+  }
+
+  // Surface object
+  const surface = contextOrSurface;
+  const lines = [
+    `Session Context: ${surface.contextBudgetStatus?.toUpperCase() || "MISSING"}`,
+    `Tokens: ~${surface.estimatedTokens || 0}`,
+  ];
+  if (surface.nextAction) lines.push(`Next: ${surface.nextAction}`);
+  if (surface.latestContextPath) lines.push(`Context: ${surface.latestContextPath}`);
+  return lines.join("\n") + "\n";
+}
+
+module.exports = {
+  SESSION_CONTEXT_CONTRACT,
+  SESSION_CONTEXT_SCHEMA_VERSION,
+  LATEST_CONTEXT_REL_PATH,
+  LATEST_CONTEXT_MD_REL_PATH,
+  DEFAULT_MAX_CHARS,
+  HARD_MAX_CHARS,
+  buildSessionContext,
+  writeSessionContext,
+  readLatestSessionContext,
+  buildSessionContextSurface,
+  formatSessionContextText,
+};