ds4-context-engine 0.1.0

package/src/extension/commands.ts

@@ -0,0 +1,872 @@
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import {
+  isPrivacyClassification,
+  type PrivacyClassification,
+} from "ds4-context-core/privacy/privacy-policy";
+import type {
+  Ds4ContextRuntime,
+  RuntimeDiagnostics,
+  SummaryGraphDiagnostics,
+} from "./runtime.ts";
+
+const NUMBER_FORMAT = new Intl.NumberFormat("en-US");
+const SUBCOMMANDS = [
+  "status",
+  "tokens",
+  "manifest",
+  "explain",
+  "included",
+  "excluded",
+  "summaries",
+  "retrieved",
+  "project",
+  "pins",
+  "pin",
+  "unpin",
+  "memory",
+  "privacy",
+  "model",
+  "continuation",
+  "artifacts",
+  "compaction",
+  "compact-preview",
+  "health",
+  "rebuild-index",
+] as const;
+
+function classificationOption(value: string | undefined): PrivacyClassification | undefined {
+  if (value === undefined) return undefined;
+  const normalized = value.trim().toLowerCase();
+  if (!isPrivacyClassification(normalized)) {
+    throw new Error("Classification must be normal, internal, sensitive, or local-only");
+  }
+  return normalized;
+}
+
+function count(value: number | undefined): string {
+  return value === undefined ? "n/a" : NUMBER_FORMAT.format(value);
+}
+
+function present(ctx: ExtensionCommandContext, message: string, level: "info" | "warning" | "error" = "info"): void {
+  if (ctx.hasUI) ctx.ui.notify(message, level);
+  else console.log(message);
+}
+
+interface ParsedCommandArgs {
+  positionals: string[];
+  options: Map<string, string>;
+}
+
+function commandTokens(value: string): string[] {
+  const tokens: string[] = [];
+  let current = "";
+  let quote: "\"" | "'" | undefined;
+  let escaped = false;
+  for (const character of value.trim()) {
+    if (escaped) {
+      current += character;
+      escaped = false;
+      continue;
+    }
+    if (character === "\\") {
+      escaped = true;
+      continue;
+    }
+    if (quote) {
+      if (character === quote) quote = undefined;
+      else current += character;
+      continue;
+    }
+    if (character === "\"" || character === "'") {
+      quote = character;
+      continue;
+    }
+    if (/\s/u.test(character)) {
+      if (current) tokens.push(current);
+      current = "";
+      continue;
+    }
+    current += character;
+  }
+  if (escaped) current += "\\";
+  if (quote) throw new Error("Unterminated quote in /context arguments");
+  if (current) tokens.push(current);
+  return tokens;
+}
+
+function parseCommandArgs(value: string): ParsedCommandArgs {
+  const tokens = commandTokens(value);
+  const positionals: string[] = [];
+  const options = new Map<string, string>();
+  for (let index = 0; index < tokens.length; index++) {
+    const token = tokens[index] ?? "";
+    if (token === "--") {
+      positionals.push(...tokens.slice(index + 1));
+      break;
+    }
+    if (!token.startsWith("--")) {
+      positionals.push(token);
+      continue;
+    }
+    const equals = token.indexOf("=");
+    if (equals > 2) {
+      options.set(token.slice(2, equals).toLowerCase(), token.slice(equals + 1));
+      continue;
+    }
+    const name = token.slice(2).toLowerCase();
+    const next = tokens[index + 1];
+    if (!next || next.startsWith("--")) throw new Error(`Option --${name} requires a value`);
+    options.set(name, next);
+    index++;
+  }
+  return { positionals, options };
+}
+
+function sourceIds(value: string | undefined): string[] {
+  return value ? [...new Set(value.split(",").map((item) => item.trim()).filter(Boolean))] : [];
+}
+
+function splitCommand(value: string, fallback = ""): { command: string; args: string } {
+  const match = value.trim().match(/^(\S+)(?:\s+([\s\S]*))?$/u);
+  return match
+    ? { command: (match[1] ?? fallback).toLowerCase(), args: match[2] ?? "" }
+    : { command: fallback, args: "" };
+}
+
+function assertOptions(options: ReadonlyMap<string, string>, allowed: readonly string[]): void {
+  const allowedSet = new Set(allowed);
+  const unknown = [...options.keys()].filter((name) => !allowedSet.has(name));
+  if (unknown.length > 0) throw new Error(`Unknown option(s): ${unknown.map((name) => `--${name}`).join(", ")}`);
+}
+
+function formatStatus(diagnostics: RuntimeDiagnostics): string {
+  const session = diagnostics.session;
+  const observation = diagnostics.observation;
+  const budget = observation?.budget;
+  const model = diagnostics.model ? `${diagnostics.model.provider}/${diagnostics.model.id}` : "not selected";
+  const indexStatus = diagnostics.lastIndexResult
+    ? `${diagnostics.lastIndexResult.mode} (${diagnostics.lastIndexResult.reason})`
+    : "not run";
+
+  return [
+    "DS4 Context Engine",
+    "",
+    `State:                    ${diagnostics.phase}`,
+    `Planner:                  ${diagnostics.plannerVersion} (${diagnostics.lastManifest?.planning?.mode ?? diagnostics.contextMode})`,
+    `Extension / Pi target:    ${diagnostics.extensionVersion} / ${diagnostics.supportedPiVersion}`,
+    `Session:                  ${session?.sessionId ?? "unavailable"}`,
+    `Session entries:          ${count(session?.totalEntries)}`,
+    `Current branch entries:   ${count(session?.branchEntries)}`,
+    `Model:                    ${model}`,
+    `Original messages:        ${count(observation?.originalMessageCount)}`,
+    `Selected messages:        ${count(observation?.messageCount)}`,
+    `Original message tokens:  ${count(observation?.originalEstimatedMessageTokens)} estimated`,
+    `Selected message tokens:  ${count(observation?.estimatedMessageTokens)} estimated`,
+    `Planning duration:        ${observation?.planningDurationMs === undefined ? "n/a" : `${observation.planningDurationMs.toFixed(1)} ms`}`,
+    `Active input budget:      ${count(budget?.activeInputBudget ?? diagnostics.lastManifest?.targetInputTokens)}`,
+    `Latest manifest:          ${diagnostics.lastManifest?.id ?? "not built"}`,
+    `Compaction:               ${diagnostics.compaction.phase}`,
+    `Proactive compaction:     ${diagnostics.compaction.proactiveEligible ? "eligible" : "not eligible"}`,
+    `Retrieved evidence:       ${count(diagnostics.retrieval.selected.length)} item(s), ${count(diagnostics.retrieval.selectedTokens)} tokens`,
+    `Retrieval duration:       ${diagnostics.retrieval.durationMs.toFixed(1)} ms`,
+    `Project knowledge:        ${diagnostics.project.status}`,
+    `Project snippets:         ${count(diagnostics.project.selected.length)} item(s), ${count(diagnostics.project.selectedTokens)} tokens`,
+    `Project index files:       ${count(diagnostics.project.stats?.files)}`,
+    `Stale project snippets:    ${count(diagnostics.project.stats?.staleSnippets)}`,
+    `Pins active / selected:    ${count(diagnostics.memory.activePins)} / ${count(diagnostics.memory.selectedPins.length)}`,
+    `Memory active / selected:  ${count(diagnostics.memory.activeMemories)} / ${count(diagnostics.memory.selectedMemories.length)}`,
+    `Memory tokens:             ${count(diagnostics.memory.selectedPinTokens + diagnostics.memory.selectedMemoryTokens)}`,
+    `Privacy enforcement:       ${diagnostics.privacy.enforcement}`,
+    `Privacy blocked/redacted:  ${count(diagnostics.privacy.blockedBlocks)} / ${count(diagnostics.privacy.secretRedactions)}`,
+    `Estimator calibration:     ${diagnostics.modelAwareness?.calibration.calibrated ? `x${diagnostics.modelAwareness.calibration.appliedRatio.toFixed(3)}` : "collecting/neutral"}`,
+    `Calibration samples:       ${count(diagnostics.modelAwareness?.calibration.acceptedSamples)} accepted`,
+    `Native continuation:       ${diagnostics.nativeContinuation.status} (${diagnostics.nativeContinuation.last?.mode ?? "no request"})`,
+    `Continuation saved items:  ${count(diagnostics.nativeContinuation.last?.omittedInputItems)}`,
+    `Artifact offload:          ${count(diagnostics.artifacts.offloadedCount)} result(s), ${count(diagnostics.artifacts.offloadedBytes)} bytes`,
+    `Artifact tokens saved:     ${count(diagnostics.artifacts.estimatedTokensSaved)} estimated`,
+    `Artifact objects / refs:   ${count(diagnostics.artifacts.stats.objects)} / ${count(diagnostics.artifacts.stats.references)}`,
+    `Indexed entries:          ${count(diagnostics.indexed?.entries)}`,
+    `Last index sync:          ${indexStatus}`,
+    `Malformed JSONL lines:    ${count(diagnostics.lastIndexResult?.malformedLines)}`,
+    `Database schema:          ${diagnostics.databaseSchemaVersion ?? "unavailable"}`,
+    `Database:                 ${diagnostics.databasePath ?? "unavailable"}`,
+    ...(diagnostics.configWarnings.length > 0
+      ? [`Configuration warnings:    ${diagnostics.configWarnings.length}`]
+      : []),
+    ...(diagnostics.lastIndexError ? [`Index warning:             ${diagnostics.lastIndexError}`] : []),
+    ...(observation?.fallbackReason ? [`Planner fallback:          ${observation.fallbackReason}`] : []),
+    ...(diagnostics.lastError ? [`Runtime fallback:          ${diagnostics.lastError}`] : []),
+  ].join("\n");
+}
+
+function formatTokens(diagnostics: RuntimeDiagnostics): string {
+  const observation = diagnostics.observation;
+  const budget = observation?.budget;
+  const manifest = diagnostics.lastManifest;
+  const tokensFor = (kind: string) => manifest?.included
+    .filter((item) => item.kind === kind)
+    .reduce((total, item) => total + item.tokens, 0);
+  return [
+    `DS4 Context Tokens (${manifest?.planning?.mode ?? diagnostics.contextMode} mode)`,
+    "",
+    `System prompt:            ${count(manifest?.composition.systemTokens)}`,
+    `Tool definitions:         ${count(manifest?.composition.toolTokens)}`,
+    `AgentMessage[]:           ${count(manifest?.composition.messageTokens)}`,
+    `  Recent verbatim:        ${count(tokensFor("recent"))}`,
+    `  Pinned context:         ${count(tokensFor("pin"))}`,
+    `  Durable memory:         ${count(tokensFor("memory"))}`,
+    `  Historical retrieval:   ${count(tokensFor("retrieval"))}`,
+    `  Project snippets:       ${count(tokensFor("project"))}`,
+    `  Artifactized results*:  ${count(manifest?.artifacts?.reduce((total, artifact) => total + artifact.condensedTokens, 0))}`,
+    `  Active summaries:       ${count(tokensFor("summary"))}`,
+    `  Current request:        ${count(tokensFor("current"))}`,
+    `Estimated provider input: ${count(manifest?.estimatedInputTokens)}`,
+    `Actual provider input:    ${count(manifest?.actualInputTokens)}`,
+    `  Uncached input:         ${count(manifest?.providerUsage?.inputTokens)}`,
+    `  Cache read / write:     ${count(manifest?.providerUsage?.cacheReadTokens)} / ${count(manifest?.providerUsage?.cacheWriteTokens)}`,
+    `Pi reported context:      ${count(manifest?.piReportedContextTokens ?? observation?.reportedTokens)}`,
+    `Model context window:     ${count(budget?.contextWindow ?? manifest?.contextWindow)}`,
+    `Output reserve:           ${count(budget?.outputReserve ?? manifest?.outputReserve)}`,
+    `Safety margin:            ${count(budget?.safetyMargin)}`,
+    `Estimator calibration:    ${budget?.calibrationRatio === undefined ? "n/a" : `x${budget.calibrationRatio.toFixed(3)} (${count(budget.calibrationSamples)} samples)`}`,
+    `Nominal soft / hard:      ${count(budget?.nominalSoftInputLimit)} / ${count(budget?.nominalHardInputLimit)}`,
+    `Soft input limit:         ${count(budget?.softInputLimit)}`,
+    `Hard input limit:         ${count(budget?.hardInputLimit ?? manifest?.hardInputLimit)}`,
+    `Preferred input target:   ${count(budget?.preferredInputTarget ?? manifest?.targetInputTokens)}`,
+    `Active input budget:      ${count(budget?.activeInputBudget ?? manifest?.targetInputTokens)}`,
+    "",
+    "Estimates cover Pi's effective system prompt, active tool schemas, and AgentMessage[] before provider rendering.",
+    "* Artifactized result tokens are already included in AgentMessage[] and the recent/current categories.",
+  ].join("\n");
+}
+
+function formatManifest(diagnostics: RuntimeDiagnostics): string {
+  const manifest = diagnostics.lastManifest;
+  if (!manifest) return "No Context Manifest has been built for this session yet.";
+
+  const kinds = new Map<string, { items: number; tokens: number }>();
+  for (const item of manifest.included) {
+    const aggregate = kinds.get(item.kind) ?? { items: 0, tokens: 0 };
+    aggregate.items++;
+    aggregate.tokens += item.tokens;
+    kinds.set(item.kind, aggregate);
+  }
+  const composition = [...kinds.entries()]
+    .map(([kind, value]) => `  ${kind.padEnd(10)} ${String(value.items).padStart(4)} item(s)  ${count(value.tokens).padStart(10)} tokens`);
+
+  return [
+    "DS4 Context Manifest",
+    "",
+    `ID:                 ${manifest.id}`,
+    `Session / leaf:     ${manifest.sessionId} / ${manifest.branchLeafId ?? "root"}`,
+    `Provider / model:   ${manifest.provider} / ${manifest.model}`,
+    `Prompt hash:        ${manifest.promptHash}`,
+    `Planner / policy:   ${manifest.plannerVersion} / ${manifest.policyVersion}`,
+    `Estimated input:    ${count(manifest.estimatedInputTokens)}`,
+    `Actual input:       ${count(manifest.actualInputTokens)}`,
+    `Usage input/cache:  ${count(manifest.providerUsage?.inputTokens)} / ${count(manifest.providerUsage?.cacheReadTokens)} read / ${count(manifest.providerUsage?.cacheWriteTokens)} write`,
+    `Target / hard:      ${count(manifest.targetInputTokens)} / ${count(manifest.hardInputLimit)}`,
+    `Included / excluded:${count(manifest.included.length)} / ${count(manifest.excluded.length)}`,
+    `Planning mode:      ${manifest.planning?.mode ?? "observer"}`,
+    `Original messages:  ${count(manifest.planning?.originalMessageCount ?? manifest.composition.messageCount)}`,
+    `Selected messages:  ${count(manifest.composition.messageCount)}`,
+    `Recent-tail limit:  ${count(manifest.planning?.recentTailTokenLimit)}`,
+    `Planning duration:  ${manifest.planning?.durationMs === undefined ? "n/a" : `${manifest.planning.durationMs.toFixed(1)} ms`}`,
+    ...(manifest.planning?.fallbackReason ? [`Fallback:           ${manifest.planning.fallbackReason}`] : []),
+    `Summary sources:    ${manifest.summaryIds.length > 0 ? manifest.summaryIds.join(", ") : "none"}`,
+    `Project snippets:   ${count(manifest.projectSnippets.length)}`,
+    `Project revision:   ${manifest.projectRevision?.head ?? "non-git/unavailable"}${manifest.projectRevision?.dirty ? " (dirty)" : ""}`,
+    `Pins / memories:    ${count(manifest.pins?.length ?? 0)} / ${count(manifest.memories?.length ?? 0)}`,
+    `Artifacts:          ${count(manifest.artifacts?.length ?? 0)}`,
+    `Privacy:            ${manifest.privacy?.enforcement ?? "disabled"}${manifest.privacy ? ` (${manifest.privacy.destination})` : ""}`,
+    `Model calibration:  ${manifest.modelAwareness?.calibration.calibrated ? `x${manifest.modelAwareness.calibration.appliedRatio.toFixed(3)}` : "neutral/collecting"}`,
+    `Adaptive tail/hist/project: ${count(manifest.modelAwareness?.adaptive.recentTailTokens)} / ${count(manifest.modelAwareness?.adaptive.maxRetrievedHistoryTokens)} / ${count(manifest.modelAwareness?.adaptive.maxProjectTokens)}`,
+    `Continuation:       ${manifest.nativeContinuation?.mode ?? "disabled"}; sent/full ${count(manifest.nativeContinuation?.sentInputItems)} / ${count(manifest.nativeContinuation?.fullInputItems)}`,
+    "",
+    "Composition",
+    ...composition,
+  ].join("\n");
+}
+
+function formatManifestItems(diagnostics: RuntimeDiagnostics, type: "included" | "excluded"): string {
+  const manifest = diagnostics.lastManifest;
+  if (!manifest) return "No Context Manifest has been built for this session yet.";
+  const items = manifest[type];
+  return [
+    `DS4 Context ${type === "included" ? "Included" : "Excluded"} Items`,
+    "",
+    ...(items.length === 0
+      ? ["none"]
+      : items.map((item, index) => {
+          const score = item.score === undefined ? "-" : item.score.toFixed(3);
+          const source = item.sourceId ?? "transient";
+          const group = item.groupId ? ` group=${item.groupId}` : "";
+          const classification = item.classification ? ` class=${item.classification}` : "";
+          return `${String(index + 1).padStart(3)}. ${item.kind.padEnd(8)} ${count(item.tokens).padStart(8)} tok score=${score} source=${source}${group}${classification}\n     ${item.reason}`;
+        })),
+  ].join("\n");
+}
+
+function formatExplain(diagnostics: RuntimeDiagnostics): string {
+  const planning = diagnostics.lastManifest?.planning;
+  if (!planning) {
+    return "Latest context used observer mode; no managed-context selection was applied.";
+  }
+  return [
+    "DS4 Context Plan",
+    "",
+    `Mode:                 ${planning.mode}`,
+    `Original messages:    ${count(planning.originalMessageCount)}`,
+    `Original tokens:      ${count(planning.originalMessageTokens)}`,
+    `Fixed system/tools:   ${count(planning.fixedTokens)}`,
+    `Message target:       ${count(planning.messageTargetTokens)}`,
+    `Message hard limit:   ${count(planning.messageHardLimitTokens)}`,
+    `Recent-tail limit:    ${count(planning.recentTailTokenLimit)}`,
+    `Selected groups:      ${count(planning.selectedGroupCount)}`,
+    `Excluded groups:      ${count(planning.excludedGroupCount)}`,
+    `Duration:             ${planning.durationMs === undefined ? "n/a" : `${planning.durationMs.toFixed(1)} ms`}`,
+    ...(planning.fallbackReason ? [`Fallback reason:       ${planning.fallbackReason}`] : []),
+    "",
+    "Use /context included or /context excluded for item-level provenance.",
+    "Label an active Pi entry with 'ds4:pin' to make its atomic turn mandatory.",
+  ].join("\n");
+}
+
+function formatSummaryGraph(graph: SummaryGraphDiagnostics): string {
+  const recentNodes = graph.nodes.slice(0, 24);
+  return [
+    "DS4 Hierarchical Summary Graph",
+    "",
+    `Nodes:                   ${count(graph.totalNodes)}`,
+    `Committed/prepared/failed: ${count(graph.committedNodes)} / ${count(graph.preparedNodes)} / ${count(graph.failedNodes)}`,
+    `Segment/aggregate/branch:  ${count(graph.segmentNodes)} / ${count(graph.aggregateNodes)} / ${count(graph.branchNodes)}`,
+    `Maximum graph level:     ${count(graph.maxGraphLevel)}`,
+    `Active summary:          ${graph.activeSummaryId ?? "none on current branch"}`,
+    `Active path nodes:       ${count(graph.activePathIds.length)}`,
+    `Committed roots:         ${graph.rootSummaryIds.length > 0 ? graph.rootSummaryIds.join(", ") : "none"}`,
+    "",
+    "Recent nodes (* = current branch active path)",
+    ...(recentNodes.length === 0
+      ? ["none"]
+      : recentNodes.map((node) => {
+          const marker = node.activePath ? "*" : " ";
+          const children = node.children.length > 0 ? node.children.join(",") : "-";
+          return `${marker} ${node.id}  ${node.kind} L${node.graphLevel} ${node.lifecycleStatus}/${node.validationStatus} sources=${node.sourceEntries} children=${children}`;
+        })),
+    ...(graph.nodes.length > recentNodes.length ? [`... ${graph.nodes.length - recentNodes.length} older node(s) omitted`] : []),
+  ].join("\n");
+}
+
+function formatRetrieved(diagnostics: RuntimeDiagnostics): string {
+  const retrieval = diagnostics.retrieval;
+  return [
+    "DS4 Retrieved Historical Evidence",
+    "",
+    `Status:                   ${retrieval.status}`,
+    `Query terms:              ${retrieval.queryTerms.length > 0 ? retrieval.queryTerms.join(", ") : "none"}`,
+    `Candidates:               ${count(retrieval.candidateCount)}`,
+    `Alternate-branch blocked:${count(retrieval.alternateBranchCandidates).padStart(9)}`,
+    `Duplicate candidates:     ${count(retrieval.duplicateCandidates)}`,
+    `Planner exclusions:       ${count(retrieval.plannerExcludedCount)}`,
+    `Selected:                 ${count(retrieval.selected.length)}`,
+    `Selected / maximum tokens:${count(retrieval.selectedTokens).padStart(9)} / ${count(retrieval.maxTokens)}`,
+    `Duration:                 ${retrieval.durationMs.toFixed(3)} ms`,
+    ...(retrieval.fallbackReason ? [`Fallback:                 ${retrieval.fallbackReason}`] : []),
+    ...retrieval.warnings.map((warning) => `Warning:                  ${warning}`),
+    "",
+    ...(retrieval.selected.length === 0
+      ? ["No historical evidence was injected into the latest managed context."]
+      : retrieval.selected.flatMap((evidence, index) => [
+          `${index + 1}. ${evidence.entryId}  score=${evidence.score.toFixed(3)}  tokens=${count(evidence.estimatedTokens)}  role=${evidence.role ?? "unknown"}`,
+          `   ${evidence.reason}`,
+          `   ${evidence.excerpt.replace(/\s+/gu, " ").slice(0, 500)}${evidence.excerpt.length > 500 ? "…" : ""}`,
+        ])),
+  ].join("\n");
+}
+
+function formatProject(diagnostics: RuntimeDiagnostics): string {
+  const project = diagnostics.project;
+  const revision = project.revision;
+  const sync = project.lastSync;
+  return [
+    "DS4 Project Knowledge",
+    "",
+    `Status / trusted:          ${project.status} / ${project.trusted ? "yes" : "no"}`,
+    `Project:                   ${project.projectPath ?? "not indexed"}`,
+    `Git branch / HEAD:         ${revision?.branch ?? "n/a"} / ${revision?.head ?? "n/a"}`,
+    `Working tree:              ${revision?.dirty ? "dirty" : "clean or non-git"}`,
+    `Changed files:             ${count(revision?.changedFiles.length)}`,
+    `Current / deleted files:   ${count(project.stats?.files)} / ${count(project.stats?.deletedFiles)}`,
+    `Current / stale snippets:  ${count(project.stats?.currentSnippets)} / ${count(project.stats?.staleSnippets)}`,
+    `Indexed snippet tokens:    ${count(project.stats?.indexedTokens)}`,
+    `Last sync mode:            ${sync?.mode ?? "not run"}`,
+    `Indexed / unchanged files: ${count(sync?.indexedFiles)} / ${count(sync?.unchangedFiles)}`,
+    `Skipped large/binary/secret:${count(sync?.skippedLarge).padStart(7)} / ${count(sync?.skippedBinary)} / ${count(sync?.skippedSensitive)}`,
+    `Query terms:               ${project.queryTerms.length > 0 ? project.queryTerms.join(", ") : "none"}`,
+    `Candidates / duplicates:   ${count(project.candidateCount)} / ${count(project.duplicateCandidates)}`,
+    `Invalidated / reindexed:   ${count(project.invalidatedSnippets)} / ${count(project.reindexedFiles)}`,
+    `Planner exclusions:        ${count(project.plannerExcludedCount)}`,
+    `Selected / maximum tokens: ${count(project.selectedTokens)} / ${count(project.maxTokens)}`,
+    `Index/retrieval duration:  ${sync?.durationMs.toFixed(3) ?? "n/a"} / ${project.durationMs.toFixed(3)} ms`,
+    ...(project.fallbackReason ? [`Fallback:                  ${project.fallbackReason}`] : []),
+    ...project.warnings.map((warning) => `Warning:                   ${warning}`),
+    "",
+    ...(project.selected.length === 0
+      ? ["No project snippets were injected into the latest managed context."]
+      : project.selected.flatMap((evidence, index) => [
+          `${index + 1}. ${evidence.path}:${evidence.startLine}-${evidence.endLine} score=${evidence.score.toFixed(3)} tokens=${count(evidence.estimatedTokens)}${evidence.modified ? " modified" : ""}`,
+          `   ${evidence.reason}`,
+          `   ${evidence.excerpt.replace(/\s+/gu, " ").slice(0, 500)}${evidence.excerpt.length > 500 ? "…" : ""}`,
+        ])),
+  ].join("\n");
+}
+
+function formatPins(runtime: Ds4ContextRuntime): string {
+  const pins = runtime.listPins(false);
+  return [
+    "DS4 Persistent Pins",
+    "",
+    ...(pins.length === 0
+      ? ["No pins are available for this session/project."]
+      : pins.map((pin, index) => [
+          `${index + 1}. ${pin.id}  ${pin.scope}  ${pin.status} class=${pin.classification ?? "default"}${pin.supersededBy ? ` -> ${pin.supersededBy}` : ""}`,
+          `   created=${new Date(pin.createdAt).toISOString()}${pin.branchLeafId ? ` branch=${pin.branchLeafId}` : ""}`,
+          `   ${pin.content.slice(0, 500)}${pin.content.length > 500 ? "…" : ""}`,
+          ...(pin.statusReason ? [`   reason: ${pin.statusReason}`] : []),
+        ].join("\n"))),
+    "",
+    "Create: /context pin [--scope session|branch|project] [--classification LEVEL] [--source ENTRY] [--file PATH] <content>",
+    "Replace: add --supersedes PIN_ID. Remove: /context unpin PIN_ID [reason]",
+  ].join("\n");
+}
+
+function formatMemory(runtime: Ds4ContextRuntime, diagnostics: RuntimeDiagnostics): string {
+  const memories = runtime.listMemories(false);
+  return [
+    "DS4 Durable Memory",
+    "",
+    `Status:                   ${diagnostics.memory.status}`,
+    `Active / inactive:        ${count(diagnostics.memory.activeMemories)} / ${count(diagnostics.memory.inactiveMemories)}`,
+    `Selected / excluded:      ${count(diagnostics.memory.selectedMemories.length)} / ${count(diagnostics.memory.excludedMemories)}`,
+    `Selected tokens:          ${count(diagnostics.memory.selectedMemoryTokens)}`,
+    ...diagnostics.memory.warnings.map((warning) => `Warning:                  ${warning}`),
+    "",
+    ...(memories.length === 0
+      ? ["No memory items are available for this session/project."]
+      : memories.map((memory, index) => [
+          `${index + 1}. ${memory.id}  ${memory.scope}  ${memory.status} class=${memory.classification ?? "default"}${memory.key ? ` key=${memory.key}` : ""}${memory.supersededBy ? ` -> ${memory.supersededBy}` : ""}`,
+          `   sources=${memory.sourceEntryIds.join(",") || "mutation"}`,
+          `   ${memory.claim.slice(0, 500)}${memory.claim.length > 500 ? "…" : ""}`,
+          ...(memory.statusReason ? [`   reason: ${memory.statusReason}`] : []),
+        ].join("\n"))),
+    "",
+    "Add: /context memory add [--scope session|project] [--classification LEVEL] [--key KEY] [--source ID,ID] <claim>",
+    "Replace: /context memory supersede MEMORY_ID [--classification LEVEL] [--source ID,ID] <new claim>",
+    "Invalidate/expire: /context memory invalidate|expire MEMORY_ID [reason]",
+  ].join("\n");
+}
+
+function formatPrivacy(diagnostics: RuntimeDiagnostics): string {
+  const privacy = diagnostics.privacy;
+  const selected = Object.entries(privacy.selectedClassifications)
+    .map(([classification, value]) => `${classification}=${count(value)}`)
+    .join(", ");
+  return [
+    "DS4 Privacy and Provider Policy",
+    "",
+    `Enabled:                    ${privacy.enabled ? "yes" : "no"}`,
+    `Provider / destination:     ${privacy.provider ?? "n/a"} / ${privacy.destination ?? "n/a"}`,
+    `Allowed classifications:    ${privacy.allowedClassifications.join(", ") || "none"}`,
+    `Selected classifications:   ${selected}`,
+    `Inspected messages:         ${count(privacy.inspectedMessages)}`,
+    `Blocked classified blocks:  ${count(privacy.blockedBlocks)}`,
+    `Excluded source slices:     ${count(privacy.excludedSources)}`,
+    `Credential redactions:      ${count(privacy.secretRedactions)}`,
+    `Provider final checks:      ${count(privacy.providerChecks)}`,
+    `Provider payload redactions:${count(privacy.providerPayloadRedactions).padStart(8)}`,
+    `Enforcement:                ${privacy.enforcement}`,
+    ...privacy.warnings.map((warning) => `Warning:                    ${warning}`),
+    "",
+    "Classification markers: [ds4:local-only]...[/ds4:local-only] (also normal, internal, sensitive).",
+    "Pin/memory commands accept --classification. Local-only is never permitted by a remote allow rule.",
+  ].join("\n");
+}
+
+function formatModelAwareness(diagnostics: RuntimeDiagnostics): string {
+  const awareness = diagnostics.modelAwareness;
+  if (!awareness) return "No active model profile has been resolved for this session yet.";
+  const calibration = awareness.calibration;
+  const cache = calibration.cache;
+  const usage = diagnostics.lastManifest?.providerUsage;
+  const modelSwitch = awareness.switch;
+  return [
+    "DS4 Advanced Model Awareness",
+    "",
+    `Enabled:                    ${awareness.enabled ? "yes" : "no"}`,
+    `Profile:                    ${awareness.profileKey}`,
+    `Overrides:                  ${awareness.overrideKeys.join(", ") || "none"}`,
+    `Context / max output:       ${count(awareness.contextWindow)} / ${count(awareness.maxOutputTokens)}`,
+    `Safety margin:              ${count(awareness.safetyMarginTokens)}`,
+    `Estimator:                  ${calibration.estimator}`,
+    `Calibration ratio:          ${calibration.calibrated ? `x${calibration.appliedRatio.toFixed(6)}` : "x1.000000 (neutral)"}`,
+    `Samples observed/accepted:  ${count(calibration.observedSamples)} / ${count(calibration.acceptedSamples)}`,
+    `Samples rejected/outliers:  ${count(calibration.rejectedSamples)} / ${count(calibration.outlierSamples)}`,
+    `Calibration bounds/window:  ${calibration.lowerRatioBound.toFixed(2)}-${calibration.upperRatioBound.toFixed(2)} / ${count(calibration.windowSize)}`,
+    `Adaptive recent tail:       ${count(awareness.adaptive.recentTailTokens)} (nominal ${count(awareness.adaptive.nominalRecentTailTokens)})`,
+    `Adaptive history retrieval: ${count(awareness.adaptive.maxRetrievedHistoryTokens)} (nominal ${count(awareness.adaptive.nominalRetrievedHistoryTokens)})`,
+    `Adaptive project retrieval: ${count(awareness.adaptive.maxProjectTokens)} (nominal ${count(awareness.adaptive.nominalProjectTokens)})`,
+    `Cache window read/write:     ${count(cache.cacheReadTokens)} / ${count(cache.cacheWriteTokens)}`,
+    `Cache window shares:         ${(cache.cacheReadShare * 100).toFixed(2)}% read / ${(cache.cacheWriteShare * 100).toFixed(2)}% write`,
+    `Latest input/cache read/write:${count(usage?.inputTokens).padStart(8)} / ${count(usage?.cacheReadTokens)} / ${count(usage?.cacheWriteTokens)}`,
+    `Model switch:                ${modelSwitch ? `${modelSwitch.source}; ${modelSwitch.switched ? "cold model switch" : modelSwitch.cacheDisposition}; profile ${modelSwitch.profileReused ? "reused" : "new"}` : "n/a"}`,
+    ...(modelSwitch?.previousProvider && modelSwitch.previousModel
+      ? [`Previous profile:            ${modelSwitch.previousProvider}/${modelSwitch.previousModel}`]
+      : []),
+    "",
+    "Calibration is isolated by exact provider/model and uses bounded median/MAD outlier rejection.",
+    "Provider cache state is an optimization; Pi JSONL and DS4 provenance remain canonical.",
+  ].join("\n");
+}
+
+function formatNativeContinuation(diagnostics: RuntimeDiagnostics): string {
+  const continuation = diagnostics.nativeContinuation;
+  const latest = continuation.last;
+  return [
+    "DS4 Optional Native Continuation",
+    "",
+    `Enabled / storage consent: ${continuation.enabled ? "yes" : "no"} / ${continuation.allowProviderStorage ? "yes" : "no"}`,
+    `Strategy:                  ${continuation.strategy}`,
+    `Status / state:            ${continuation.status} / ${continuation.stateAvailable ? "ready" : "cold"}`,
+    `Profiles:                  ${continuation.profiles.join(", ") || "none"}`,
+    `Provider wrappers:         ${continuation.registeredProviders.join(", ") || "none"}`,
+    `Requests full/native:      ${count(continuation.fullReplayRequests)} / ${count(continuation.continuationRequests)}`,
+    `Native successes:          ${count(continuation.continuationSuccesses)}`,
+    `Invalidations:             ${count(continuation.invalidations)}`,
+    `Retry attempts/success/fail:${count(continuation.retryAttempts).padStart(7)} / ${count(continuation.retrySuccesses)} / ${count(continuation.retryFailures)}`,
+    `Latest provider/model:     ${continuation.lastProvider && continuation.lastModel ? `${continuation.lastProvider}/${continuation.lastModel}` : "n/a"}`,
+    `Latest mode:               ${latest?.mode ?? "n/a"}`,
+    `Latest full/sent/omitted:  ${count(latest?.fullInputItems)} / ${count(latest?.sentInputItems)} / ${count(latest?.omittedInputItems)}`,
+    `Latest retry:              ${latest?.retry ?? "n/a"}`,
+    ...(latest?.stateAgeMs !== undefined ? [`Latest state age:          ${count(latest.stateAgeMs)} ms`] : []),
+    ...(latest?.fallbackReason ? [`Latest fallback:           ${latest.fallbackReason}`] : []),
+    ...(latest?.invalidationReason ? [`Latest invalidation:       ${latest.invalidationReason}`] : []),
+    ...continuation.warnings.map((warning) => `Warning:                    ${warning}`),
+    "",
+    "Provider response IDs and payload content are never included in these diagnostics or Context Manifests.",
+    "Eligible OpenAI Responses calls use store=true only after explicit configuration consent.",
+  ].join("\n");
+}
+
+function formatArtifacts(diagnostics: RuntimeDiagnostics): string {
+  const artifacts = diagnostics.artifacts;
+  return [
+    "DS4 Artifact Store",
+    "",
+    `Enabled:                  ${artifacts.enabled ? "yes" : "no"}`,
+    `Store:                    ${artifacts.storePath ?? "unavailable"}`,
+    `Objects / references:     ${count(artifacts.stats.objects)} / ${count(artifacts.stats.references)}`,
+    `Stored bytes:             ${count(artifacts.stats.bytes)}`,
+    `Missing / corrupt:        ${count(artifacts.stats.missing)} / ${count(artifacts.stats.corrupt)}`,
+    `Current branch references:${count(artifacts.currentBranchReferences).padStart(8)}`,
+    `Latest offloaded:         ${count(artifacts.offloadedCount)}`,
+    `Latest bytes offloaded:   ${count(artifacts.offloadedBytes)}`,
+    `Estimated tokens saved:   ${count(artifacts.estimatedTokensSaved)}`,
+    `Latest failures:          ${count(artifacts.failedCount)}`,
+    ...artifacts.warnings.map((warning) => `Warning:                  ${warning}`),
+    "",
+    ...(artifacts.references.length === 0
+      ? ["No artifacts are referenced by the active branch."]
+      : artifacts.references.slice(0, 50).map((artifact, index) =>
+          `${index + 1}. ${artifact.artifactId}  ${JSON.stringify(artifact.toolName)}/${JSON.stringify(artifact.toolCallId)}  ${count(artifact.sizeBytes)} bytes  ${artifact.originalTokens}->${artifact.condensedTokens} tokens  ${artifact.mimeType}${artifact.isError ? " error" : ""}`
+        )),
+    ...(artifacts.references.length > 50 ? [`... ${artifacts.references.length - 50} older reference(s) omitted`] : []),
+    "",
+    "Use context_artifact_search with an Artifact ID and a narrow literal query.",
+  ].join("\n");
+}
+
+function formatCompaction(diagnostics: RuntimeDiagnostics, preview: boolean): string {
+  const compaction = diagnostics.compaction;
+  return [
+    preview ? "DS4 Compaction Preview" : "DS4 Compaction",
+    "",
+    `Custom compaction:       ${compaction.enabled ? "enabled" : "disabled"}`,
+    `Deterministic validator: ${compaction.validate ? "enabled" : "disabled"}`,
+    `Preserve recent tail:    ${compaction.preserveRecentVerbatim ? "yes" : "no"}`,
+    `Segment target:          ${count(compaction.segmentTargetTokens)}`,
+    `Current context tokens:  ${count(compaction.contextTokens)}`,
+    `Model soft limit:        ${count(compaction.softLimitTokens)}`,
+    `Proactive threshold:     ${count(compaction.proactiveThresholdTokens)}`,
+    `Would compact now:       ${compaction.proactiveEligible ? "yes" : "no"}`,
+    `Last phase:              ${compaction.phase}`,
+    `Last trigger:            ${compaction.trigger ?? "n/a"}`,
+    `Summary ID:              ${compaction.summaryId ?? "n/a"}`,
+    `Source entries:          ${count(compaction.sourceEntries)}`,
+    `Validation:              ${compaction.validationStatus ?? "n/a"}`,
+    `First kept entry:        ${compaction.firstKeptEntryId ?? "n/a"}`,
+    `Tokens before:           ${count(compaction.tokensBefore)}`,
+    ...(compaction.lastError ? [`Last error:              ${compaction.lastError}`] : []),
+    ...(preview
+      ? ["", "Pi determines the exact cut point; DS4 preserves Pi's firstKeptEntryId and validates the generated summary before replacing history."]
+      : []),
+  ].join("\n");
+}
+
+export function registerContextCommand(pi: ExtensionAPI, runtime: Ds4ContextRuntime): void {
+  pi.registerCommand("context", {
+    description: "Inspect DS4 managed context, provenance, tokens, or storage health",
+    getArgumentCompletions: (prefix) => {
+      const matches = SUBCOMMANDS.filter((command) => command.startsWith(prefix.trim()));
+      return matches.length > 0 ? matches.map((command) => ({ value: command, label: command })) : null;
+    },
+    handler: async (args, ctx) => {
+      const parsedCommand = splitCommand(args, "status");
+      const subcommand = parsedCommand.command;
+      const subcommandArgs = parsedCommand.args;
+
+      try {
+        if (subcommand === "status") {
+          const diagnostics = runtime.diagnostics(ctx);
+          const level = diagnostics.phase === "degraded" ? "warning" : "info";
+          present(ctx, formatStatus(diagnostics), level);
+          return;
+        }
+
+        if (subcommand === "tokens") {
+          present(ctx, formatTokens(runtime.diagnostics(ctx)));
+          return;
+        }
+
+        if (subcommand === "manifest") {
+          present(ctx, formatManifest(runtime.diagnostics(ctx)));
+          return;
+        }
+
+        if (subcommand === "explain") {
+          present(ctx, formatExplain(runtime.diagnostics(ctx)));
+          return;
+        }
+
+        if (subcommand === "included" || subcommand === "excluded") {
+          present(ctx, formatManifestItems(runtime.diagnostics(ctx), subcommand));
+          return;
+        }
+
+        if (subcommand === "summaries") {
+          present(ctx, formatSummaryGraph(runtime.summaryGraph(ctx)));
+          return;
+        }
+
+        if (subcommand === "retrieved") {
+          present(ctx, formatRetrieved(runtime.diagnostics(ctx)));
+          return;
+        }
+
+        if (subcommand === "project") {
+          present(ctx, formatProject(runtime.diagnostics(ctx)));
+          return;
+        }
+
+        if (subcommand === "pins") {
+          present(ctx, formatPins(runtime));
+          return;
+        }
+
+        if (subcommand === "pin") {
+          const parsed = parseCommandArgs(subcommandArgs);
+          assertOptions(parsed.options, ["scope", "source", "file", "supersedes", "classification"]);
+          const scope = (parsed.options.get("scope") ?? "session").toLowerCase();
+          const classification = classificationOption(parsed.options.get("classification"));
+          if (scope !== "session" && scope !== "branch" && scope !== "project") {
+            throw new Error("Pin scope must be session, branch, or project");
+          }
+          const result = runtime.createPin({
+            content: parsed.positionals.join(" "),
+            scope,
+            ...(parsed.options.get("source") ? { sourceEntryId: parsed.options.get("source") } : {}),
+            ...(parsed.options.get("file") ? { sourceFile: parsed.options.get("file") } : {}),
+            ...(parsed.options.get("supersedes") ? { supersedes: parsed.options.get("supersedes") } : {}),
+            ...(classification ? { classification } : {}),
+          }, ctx, (customType, data) => pi.appendEntry(customType, data));
+          present(
+            ctx,
+            `${result.duplicate ? "Existing" : "Created"} ${result.pin.scope} pin ${result.pin.id}`,
+          );
+          return;
+        }
+
+        if (subcommand === "unpin") {
+          const parsed = parseCommandArgs(subcommandArgs);
+          assertOptions(parsed.options, []);
+          const pinId = parsed.positionals[0];
+          if (!pinId) throw new Error("Usage: /context unpin PIN_ID [reason]");
+          const pin = runtime.unpin(
+            pinId,
+            parsed.positionals.slice(1).join(" ") || undefined,
+            ctx,
+            (customType, data) => pi.appendEntry(customType, data),
+          );
+          present(ctx, `Pin ${pin.id} is ${pin.status}`);
+          return;
+        }
+
+        if (subcommand === "memory") {
+          const nested = splitCommand(subcommandArgs, "list");
+          if (nested.command === "list") {
+            present(ctx, formatMemory(runtime, runtime.diagnostics(ctx)));
+            return;
+          }
+          const parsed = parseCommandArgs(nested.args);
+          if (nested.command === "add") {
+            assertOptions(parsed.options, ["scope", "key", "source", "classification"]);
+            const scope = (parsed.options.get("scope") ?? "session").toLowerCase();
+            const classification = classificationOption(parsed.options.get("classification"));
+            if (scope !== "session" && scope !== "project") {
+              throw new Error("Memory scope must be session or project");
+            }
+            const result = runtime.createMemory({
+              claim: parsed.positionals.join(" "),
+              scope,
+              ...(parsed.options.get("key") ? { key: parsed.options.get("key") } : {}),
+              ...(classification ? { classification } : {}),
+              sourceEntryIds: sourceIds(parsed.options.get("source")),
+            }, ctx, (customType, data) => pi.appendEntry(customType, data));
+            present(
+              ctx,
+              `${result.duplicate ? "Existing" : "Created"} ${result.memory.scope} memory ${result.memory.id}`,
+            );
+            return;
+          }
+          if (nested.command === "supersede") {
+            assertOptions(parsed.options, ["source", "classification"]);
+            const previousId = parsed.positionals[0];
+            const claim = parsed.positionals.slice(1).join(" ");
+            if (!previousId || !claim) {
+              throw new Error("Usage: /context memory supersede MEMORY_ID [--source ID,ID] <new claim>");
+            }
+            const memory = runtime.supersedeMemory(
+              previousId,
+              claim,
+              sourceIds(parsed.options.get("source")),
+              classificationOption(parsed.options.get("classification")),
+              ctx,
+              (customType, data) => pi.appendEntry(customType, data),
+            );
+            present(ctx, `Memory ${previousId} superseded by ${memory.id}`);
+            return;
+          }
+          if (nested.command === "invalidate" || nested.command === "expire") {
+            assertOptions(parsed.options, []);
+            const memoryId = parsed.positionals[0];
+            if (!memoryId) throw new Error(`Usage: /context memory ${nested.command} MEMORY_ID [reason]`);
+            const memory = runtime.setMemoryStatus(
+              memoryId,
+              nested.command === "invalidate" ? "invalid" : "expired",
+              parsed.positionals.slice(1).join(" ") || undefined,
+              ctx,
+              (customType, data) => pi.appendEntry(customType, data),
+            );
+            present(ctx, `Memory ${memory.id} is ${memory.status}`);
+            return;
+          }
+          throw new Error("Usage: /context memory [list|add|supersede|invalidate|expire]");
+        }
+
+        if (subcommand === "privacy") {
+          present(ctx, formatPrivacy(runtime.diagnostics(ctx)));
+          return;
+        }
+
+        if (subcommand === "model") {
+          present(ctx, formatModelAwareness(runtime.diagnostics(ctx)));
+          return;
+        }
+
+        if (subcommand === "continuation") {
+          present(ctx, formatNativeContinuation(runtime.diagnostics(ctx)));
+          return;
+        }
+
+        if (subcommand === "artifacts") {
+          present(ctx, formatArtifacts(runtime.diagnostics(ctx)));
+          return;
+        }
+
+        if (subcommand === "compaction" || subcommand === "compact-preview") {
+          present(ctx, formatCompaction(runtime.diagnostics(ctx), subcommand === "compact-preview"));
+          return;
+        }
+
+        if (subcommand === "rebuild-index") {
+          await ctx.waitForIdle();
+          const result = runtime.rebuildIndex(ctx);
+          present(
+            ctx,
+            [
+              "DS4 Context Index Rebuilt",
+              "",
+              `Reason:              ${result.reason}`,
+              `Processed entries:   ${count(result.processedEntries)}`,
+              `Indexed entries:     ${count(result.totalEntries)}`,
+              `Malformed lines:     ${count(result.malformedLines)}`,
+              `Duration:            ${result.durationMs.toFixed(1)} ms`,
+              `Project files:       ${count(runtime.diagnostics(ctx).project.stats?.files)}`,
+              `Project snippets:    ${count(runtime.diagnostics(ctx).project.stats?.currentSnippets)}`,
+              `Pins / memories:     ${count(runtime.diagnostics(ctx).memory.activePins)} / ${count(runtime.diagnostics(ctx).memory.activeMemories)}`,
+              `Artifact references: ${count(runtime.diagnostics(ctx).artifacts.stats.references)}`,
+            ].join("\n"),
+          );
+          return;
+        }
+
+        if (subcommand === "health") {
+          const health = runtime.health();
+          if (!health) {
+            present(ctx, "DS4 Context Engine database is unavailable; Pi fallback remains active.", "warning");
+            return;
+          }
+          runtime.verifyArtifactHealth(ctx);
+          const diagnostics = runtime.diagnostics(ctx);
+          const staleProjectSnippets = diagnostics.project.stats?.staleSnippets ?? 0;
+          const artifactIntegrityIssues = diagnostics.artifacts.stats.missing + diagnostics.artifacts.stats.corrupt;
+          const healthy = health.ok
+            && staleProjectSnippets === 0
+            && diagnostics.project.status !== "failed"
+            && diagnostics.memory.status !== "failed"
+            && diagnostics.memory.warnings.length === 0
+            && diagnostics.privacy.warnings.length === 0
+            && diagnostics.nativeContinuation.warnings.length === 0
+            && artifactIntegrityIssues === 0
+            && diagnostics.artifacts.warnings.length === 0;
+          present(
+            ctx,
+            [
+              "DS4 Context Engine Health",
+              "",
+              `Status:              ${healthy ? "OK" : "WARN"}`,
+              `SQLite quick_check:  ${health.quickCheck}`,
+              `Journal mode:        ${health.journalMode}`,
+              `Foreign keys:        ${health.foreignKeys ? "enabled" : "disabled"}`,
+              `Schema version:      ${health.schemaVersion}`,
+              `Applied migrations:  ${health.appliedMigrations}`,
+              `Project stale snippets: ${count(staleProjectSnippets)}`,
+              `Memory/pin warnings: ${count(diagnostics.memory.warnings.length)}`,
+              `Privacy enforcement:  ${diagnostics.privacy.enforcement}`,
+              `Privacy warnings:     ${count(diagnostics.privacy.warnings.length)}`,
+              `Continuation warnings: ${count(diagnostics.nativeContinuation.warnings.length)}`,
+              `Artifact missing/corrupt: ${count(diagnostics.artifacts.stats.missing)} / ${count(diagnostics.artifacts.stats.corrupt)}`,
+              `Artifact warnings:     ${count(diagnostics.artifacts.warnings.length)}`,
+            ].join("\n"),
+            healthy ? "info" : "warning",
+          );
+          return;
+        }
+
+        present(ctx, `Unknown /context command: ${subcommand}\nUsage: /context [${SUBCOMMANDS.join("|")}]`, "warning");
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        present(ctx, `DS4 Context Engine diagnostics failed: ${message}`, "warning");
+      }
+    },
+  });
+}