@fenglimg/fabric-server 2.0.0-rc.13 → 2.0.0-rc.21

package/dist/{chunk-3ZBYYPXQ.js → chunk-7R6MFA7Y.js}

@@ -1281,7 +1281,12 @@ import {
   AgentsMetaCountersSchema,
   forensicReportSchema,
   parseKnowledgeId as parseKnowledgeId2,
-  knowledgeTestIndexSchema as knowledgeTestIndexSchema2
+  knowledgeTestIndexSchema as knowledgeTestIndexSchema2,
+  LEGACY_KB_REGEX,
+  BOOTSTRAP_CANONICAL,
+  BOOTSTRAP_MARKER_BEGIN,
+  BOOTSTRAP_MARKER_END,
+  BOOTSTRAP_REGEX
 } from "@fenglimg/fabric-shared";
 import { detectFramework } from "@fenglimg/fabric-shared/node";
 import { atomicWriteJson as atomicWriteJson2, atomicWriteText as atomicWriteText3 } from "@fenglimg/fabric-shared/node/atomic-write";
@@ -1342,7 +1347,13 @@ var TARGET_FILE_PATHS = [
   ".fabric/agents.meta.json",
   ".fabric/.cache/knowledge-test.index.json",
   ".fabric/events.jsonl",
-  ".fabric/knowledge"
+  ".fabric/knowledge",
+  // v2.0.0-rc.19 bootstrap-consolidation TASK-005: L1 canonical snapshot
+  // (.fabric/AGENTS.md) and optional project-rules concat source
+  // (.fabric/project-rules.md). Surfaced in summary.targetFiles so --json
+  // consumers can confirm L1 presence at a glance.
+  ".fabric/AGENTS.md",
+  ".fabric/project-rules.md"
 ];
 async function runDoctorReport(target) {
   const projectRoot = normalizeTarget(target);
@@ -1352,12 +1363,24 @@ async function runDoctorReport(target) {
     forensic,
     meta,
     eventLedger,
-    knowledgeTestIndex
+    knowledgeTestIndex,
+    bootstrapMarkerMigration,
+    l1BootstrapSnapshotDrift,
+    l2ManagedBlockDrift
   ] = await Promise.all([
     inspectForensic(projectRoot),
     inspectMeta(projectRoot),
     inspectEventLedger(projectRoot),
-    inspectKnowledgeTestIndex(projectRoot)
+    inspectKnowledgeTestIndex(projectRoot),
+    // v2.0.0-rc.19 TASK-004: one-time fabric:knowledge-base → fabric:bootstrap
+    // marker migration scan. Inspect runs in this Promise.all block to keep
+    // performance parity with the other I/O-bound inspections.
+    inspectBootstrapMarkerMigration(projectRoot),
+    // v2.0.0-rc.19 TASK-005: L1 + L2 byte-level drift detection. Both are
+    // I/O-bound (small file reads + buffer compare) so they live in the same
+    // Promise.all block as the other bootstrap inspections.
+    inspectL1BootstrapSnapshotDrift(projectRoot),
+    inspectL2ManagedBlockDrift(projectRoot)
   ]);
   const mcpConfigInWrongFile = inspectMcpConfigInWrongFile(projectRoot);
   const metaManuallyDiverged = await inspectMetaManuallyDiverged(projectRoot);
@@ -1385,6 +1408,15 @@ async function runDoctorReport(target) {
   const skillMdYamlInvalid = inspectSkillMdYamlInvalid(projectRoot);
   const checks = [
     createBootstrapAnchorCheck(bootstrapAnchor),
+    // v2.0.0-rc.19 TASK-004: bootstrap marker migration check sits adjacent to
+    // the anchor check — both are bootstrap-file invariants. fixable_error
+    // when any of the four target paths still carries the legacy marker.
+    createBootstrapMarkerMigrationCheck(bootstrapMarkerMigration),
+    // v2.0.0-rc.19 TASK-005: L1 + L2 byte-level drift detection sit immediately
+    // after the marker migration check. Order: anchor existence → migration →
+    // L1 (canonical ↔ snapshot) → L2 (snapshot+rules ↔ three-end blocks).
+    createL1BootstrapSnapshotDriftCheck(l1BootstrapSnapshotDrift),
+    createL2ManagedBlockDriftCheck(l2ManagedBlockDrift),
     createKnowledgeDirMissingCheck(knowledgeDirMissing),
     createForensicCheck(forensic, framework.kind, entryPoints.length),
     // v2.0: removed `createInitContextCheck` — `.fabric/init-context.json`
@@ -1494,6 +1526,33 @@ async function runDoctorFix(target) {
   const projectRoot = normalizeTarget(target);
   const before = await runDoctorReport(projectRoot);
   const fixed = [];
+  if (before.fixable_errors.some(
+    (issue) => issue.code === "bootstrap_marker_migration_required"
+  )) {
+    const migrated = await migrateBootstrapMarkers(projectRoot);
+    fixed.push(findIssue(before.fixable_errors, "bootstrap_marker_migration_required"));
+    for (const path of migrated.paths) {
+      await appendEventLedgerEvent(projectRoot, {
+        event_type: "bootstrap_marker_migrated",
+        path,
+        migrated_count: migrated.countPerPath[path] ?? 1,
+        legacy_marker: "fabric:knowledge-base",
+        new_marker: "fabric:bootstrap",
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      }).catch(() => {
+      });
+    }
+  }
+  if (before.fixable_errors.some((issue) => issue.code === "bootstrap_snapshot_drift")) {
+    const snapshotPath = join5(projectRoot, ".fabric", "AGENTS.md");
+    await ensureParentDirectory(snapshotPath);
+    await atomicWriteText3(snapshotPath, BOOTSTRAP_CANONICAL);
+    fixed.push(findIssue(before.fixable_errors, "bootstrap_snapshot_drift"));
+  }
+  if (before.fixable_errors.some((issue) => issue.code === "managed_block_drift")) {
+    await rewriteThreeEndManagedBlocks(projectRoot);
+    fixed.push(findIssue(before.fixable_errors, "managed_block_drift"));
+  }
   if (before.fixable_errors.some((issue) => issue.code === "knowledge_dir_missing")) {
     await ensureKnowledgeSubdirs(projectRoot);
     fixed.push(findIssue(before.fixable_errors, "knowledge_dir_missing"));
@@ -2124,6 +2183,186 @@ function inspectBootstrapAnchor(projectRoot) {
     hasClaudeMd: existsSync4(join5(projectRoot, "CLAUDE.md"))
   };
 }
+var BOOTSTRAP_MARKER_MIGRATION_TARGETS = [
+  "CLAUDE.md",
+  "AGENTS.md",
+  ".cursor/rules",
+  ".cursor/rules/fabric-bootstrap.mdc"
+];
+async function inspectBootstrapMarkerMigration(target) {
+  const filesNeedingMigration = [];
+  for (const rel of BOOTSTRAP_MARKER_MIGRATION_TARGETS) {
+    const abs = join5(target, rel);
+    if (!existsSync4(abs)) {
+      continue;
+    }
+    let content;
+    try {
+      content = await readFile5(abs, "utf8");
+    } catch {
+      continue;
+    }
+    if (LEGACY_KB_REGEX.test(content)) {
+      filesNeedingMigration.push(abs);
+    }
+  }
+  return { filesNeedingMigration };
+}
+function createBootstrapMarkerMigrationCheck(inspection) {
+  if (inspection.filesNeedingMigration.length === 0) {
+    return okCheck(
+      "Bootstrap marker migration",
+      "No legacy fabric:knowledge-base markers detected in bootstrap target files."
+    );
+  }
+  const list = inspection.filesNeedingMigration.join(", ");
+  return issueCheck(
+    "Bootstrap marker migration",
+    "error",
+    "fixable_error",
+    "bootstrap_marker_migration_required",
+    `${inspection.filesNeedingMigration.length} file${inspection.filesNeedingMigration.length === 1 ? "" : "s"} still carry the legacy fabric:knowledge-base bootstrap marker: ${list}.`,
+    "Run `fab doctor --fix` to migrate to fabric:bootstrap marker"
+  );
+}
+async function inspectL1BootstrapSnapshotDrift(target) {
+  const abs = join5(target, ".fabric", "AGENTS.md");
+  if (!existsSync4(abs)) {
+    return { status: "missing", canonical: BOOTSTRAP_CANONICAL, onDisk: null };
+  }
+  let onDisk;
+  try {
+    onDisk = await readFile5(abs, "utf8");
+  } catch {
+    return { status: "missing", canonical: BOOTSTRAP_CANONICAL, onDisk: null };
+  }
+  if (onDisk === BOOTSTRAP_CANONICAL) {
+    return { status: "ok", canonical: BOOTSTRAP_CANONICAL, onDisk };
+  }
+  return { status: "drift", canonical: BOOTSTRAP_CANONICAL, onDisk };
+}
+function createL1BootstrapSnapshotDriftCheck(inspection) {
+  if (inspection.status === "drift") {
+    return issueCheck(
+      "Bootstrap snapshot drift",
+      "error",
+      "fixable_error",
+      "bootstrap_snapshot_drift",
+      ".fabric/AGENTS.md content diverges byte-for-byte from BOOTSTRAP_CANONICAL.",
+      "Run `fab doctor --fix` to restore canonical bootstrap snapshot"
+    );
+  }
+  return okCheck(
+    "Bootstrap snapshot drift",
+    inspection.status === "ok" ? ".fabric/AGENTS.md byte-equals BOOTSTRAP_CANONICAL." : ".fabric/AGENTS.md absent \u2014 delegated to bootstrap_anchor_missing."
+  );
+}
+async function inspectL2ManagedBlockDrift(target) {
+  const snapshotPath = join5(target, ".fabric", "AGENTS.md");
+  if (!existsSync4(snapshotPath)) {
+    return { status: "ok", drifted: [] };
+  }
+  let snapshot;
+  try {
+    snapshot = await readFile5(snapshotPath, "utf8");
+  } catch {
+    return { status: "ok", drifted: [] };
+  }
+  const projectRulesPath = join5(target, ".fabric", "project-rules.md");
+  let expectedBody = snapshot;
+  if (existsSync4(projectRulesPath)) {
+    try {
+      const projectRules = await readFile5(projectRulesPath, "utf8");
+      expectedBody = `${snapshot}
+---
+${projectRules}`;
+    } catch {
+    }
+  }
+  const drifted = [];
+  let anyManagedBlockFound = false;
+  const blockTargets = [
+    join5(target, "AGENTS.md"),
+    join5(target, ".cursor", "rules", "fabric-bootstrap.mdc")
+  ];
+  for (const abs of blockTargets) {
+    if (!existsSync4(abs)) {
+      continue;
+    }
+    let content;
+    try {
+      content = await readFile5(abs, "utf8");
+    } catch {
+      continue;
+    }
+    if (!BOOTSTRAP_REGEX.test(content) && LEGACY_KB_REGEX.test(content)) {
+      continue;
+    }
+    const match = content.match(BOOTSTRAP_REGEX);
+    if (match === null) {
+      continue;
+    }
+    anyManagedBlockFound = true;
+    const region = match[0];
+    const beginIdx = region.indexOf(BOOTSTRAP_MARKER_BEGIN);
+    const bodyStart = beginIdx + BOOTSTRAP_MARKER_BEGIN.length;
+    const endIdx = region.indexOf(BOOTSTRAP_MARKER_END, bodyStart);
+    if (bodyStart < 0 || endIdx < 0) {
+      continue;
+    }
+    let body = region.slice(bodyStart, endIdx);
+    if (body.startsWith("\n")) body = body.slice(1);
+    if (body.endsWith("\n")) body = body.slice(0, -1);
+    if (body !== expectedBody) {
+      drifted.push({ path: abs, expected: expectedBody, actual: body });
+    }
+  }
+  const claudeMdPath = join5(target, "CLAUDE.md");
+  if (existsSync4(claudeMdPath)) {
+    let claudeContent;
+    try {
+      claudeContent = await readFile5(claudeMdPath, "utf8");
+      if (!BOOTSTRAP_REGEX.test(claudeContent) && LEGACY_KB_REGEX.test(claudeContent)) {
+      } else {
+        anyManagedBlockFound = true;
+        const lines = claudeContent.split(/\r?\n/u);
+        const hasAtImport = lines.some((line) => line.trim() === "@.fabric/AGENTS.md");
+        if (!hasAtImport) {
+          drifted.push({
+            path: claudeMdPath,
+            expected: "@.fabric/AGENTS.md",
+            actual: "(line missing)"
+          });
+        }
+      }
+    } catch {
+    }
+  }
+  if (!anyManagedBlockFound) {
+    return { status: "no-managed-block", drifted: [] };
+  }
+  if (drifted.length === 0) {
+    return { status: "ok", drifted: [] };
+  }
+  return { status: "drift", drifted };
+}
+function createL2ManagedBlockDriftCheck(inspection) {
+  if (inspection.status === "drift") {
+    const list = inspection.drifted.map((d) => d.path).join(", ");
+    return issueCheck(
+      "Managed block drift",
+      "error",
+      "fixable_error",
+      "managed_block_drift",
+      `${inspection.drifted.length} three-end managed block${inspection.drifted.length === 1 ? "" : "s"} diverge from expected body (snapshot + optional project-rules concat): ${list}.`,
+      "Run `fab doctor --fix` to restore three-end managed blocks from canonical"
+    );
+  }
+  return okCheck(
+    "Managed block drift",
+    inspection.status === "ok" ? "Three-end managed blocks byte-equal expectedBody." : "No three-end managed blocks detected \u2014 propagation pending or legacy-marker state."
+  );
+}
 function createBootstrapAnchorCheck(inspection) {
   if (!inspection.hasAgentsMd && !inspection.hasClaudeMd) {
     return issueCheck(
@@ -3953,6 +4192,125 @@ function createIndexDriftCheck(inspection) {
     "Run `fab doctor --apply-lint` (rc.4 TASK-003) to bump agents.meta.json counters to max_observed + 1."
   );
 }
+async function migrateBootstrapMarkers(projectRoot) {
+  const paths = [];
+  const countPerPath = {};
+  for (const rel of BOOTSTRAP_MARKER_MIGRATION_TARGETS) {
+    const abs = join5(projectRoot, rel);
+    if (!existsSync4(abs)) {
+      continue;
+    }
+    let original;
+    try {
+      original = await readFile5(abs, "utf8");
+    } catch {
+      continue;
+    }
+    const beginMatches = original.match(/<!-- fabric:knowledge-base:begin -->/g);
+    const endMatches = original.match(/<!-- fabric:knowledge-base:end -->/g);
+    const replacedCount = (beginMatches?.length ?? 0) + (endMatches?.length ?? 0);
+    if (replacedCount === 0) {
+      continue;
+    }
+    const rewritten = original.replace(/<!-- fabric:knowledge-base:begin -->/g, BOOTSTRAP_MARKER_BEGIN).replace(/<!-- fabric:knowledge-base:end -->/g, BOOTSTRAP_MARKER_END);
+    if (rewritten === original) {
+      continue;
+    }
+    await atomicWriteText3(abs, rewritten);
+    paths.push(abs);
+    countPerPath[abs] = replacedCount;
+  }
+  return { paths, countPerPath };
+}
+async function rewriteThreeEndManagedBlocks(projectRoot) {
+  const snapshotPath = join5(projectRoot, ".fabric", "AGENTS.md");
+  if (!existsSync4(snapshotPath)) {
+    return;
+  }
+  let snapshot;
+  try {
+    snapshot = await readFile5(snapshotPath, "utf8");
+  } catch {
+    return;
+  }
+  const projectRulesPath = join5(projectRoot, ".fabric", "project-rules.md");
+  const hasProjectRules = existsSync4(projectRulesPath);
+  let expectedBody = snapshot;
+  if (hasProjectRules) {
+    try {
+      const projectRules = await readFile5(projectRulesPath, "utf8");
+      expectedBody = `${snapshot}
+---
+${projectRules}`;
+    } catch {
+    }
+  }
+  const managedBlock = `${BOOTSTRAP_MARKER_BEGIN}
+${expectedBody}
+${BOOTSTRAP_MARKER_END}`;
+  const blockTargets = [
+    join5(projectRoot, "AGENTS.md"),
+    join5(projectRoot, ".cursor", "rules", "fabric-bootstrap.mdc")
+  ];
+  for (const abs of blockTargets) {
+    if (!existsSync4(abs)) {
+      continue;
+    }
+    let existing;
+    try {
+      existing = await readFile5(abs, "utf8");
+    } catch {
+      continue;
+    }
+    let next;
+    const match = existing.match(BOOTSTRAP_REGEX);
+    if (match !== null) {
+      const before = existing.slice(0, match.index ?? 0);
+      const after = existing.slice((match.index ?? 0) + match[0].length);
+      const stripped = `${before}${after.replace(/^\r?\n/, "")}`;
+      const trailingNewline = stripped.length === 0 || stripped.endsWith("\n") ? "" : "\n";
+      next = `${stripped}${trailingNewline}
+${managedBlock}
+`;
+    } else {
+      const trailingNewline = existing.length === 0 || existing.endsWith("\n") ? "" : "\n";
+      next = `${existing}${trailingNewline}
+${managedBlock}
+`;
+    }
+    if (next === existing) {
+      continue;
+    }
+    await atomicWriteText3(abs, next);
+  }
+  const claudeMdPath = join5(projectRoot, "CLAUDE.md");
+  if (existsSync4(claudeMdPath)) {
+    let claudeContent;
+    try {
+      claudeContent = await readFile5(claudeMdPath, "utf8");
+    } catch {
+      return;
+    }
+    const lines = claudeContent.split(/\r?\n/u);
+    let updated = claudeContent;
+    const ensureLine = (line) => {
+      if (lines.some((existingLine) => existingLine.trim() === line)) {
+        return;
+      }
+      const trailingNewline = updated.length === 0 || updated.endsWith("\n") ? "" : "\n";
+      updated = `${updated}${trailingNewline}${line}
+`;
+      lines.push(line);
+    };
+    ensureLine("@.fabric/AGENTS.md");
+    if (hasProjectRules) {
+      ensureLine("@.fabric/project-rules.md");
+    }
+    if (updated !== claudeContent) {
+      await atomicWriteText3(claudeMdPath, updated);
+    }
+  }
+}
 async function fixMcpConfigInWrongFile(projectRoot) {
   const settingsPath = join5(projectRoot, ".claude", "settings.json");
   if (!existsSync4(settingsPath)) {
@@ -4026,6 +4384,275 @@ async function ensureEventLedger(projectRoot) {
   await ensureParentDirectory(path);
   await writeFile2(path, "", { encoding: "utf8", flag: "a" });
 }
+var CITE_POLICY_VERSION = "2.0.0-rc.20";
+async function ensureCitePolicyActivatedMarker(projectRoot) {
+  let existing;
+  try {
+    const { events } = await readEventLedger(projectRoot, { event_type: "cite_policy_activated" });
+    if (events.length > 0) {
+      existing = events[0];
+    }
+  } catch {
+    return { marker_ts: 0, emitted_now: false };
+  }
+  if (existing !== void 0) {
+    return { marker_ts: existing.ts, emitted_now: false };
+  }
+  try {
+    const stored = await appendEventLedgerEvent(projectRoot, {
+      event_type: "cite_policy_activated",
+      policy_version: CITE_POLICY_VERSION,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    });
+    return { marker_ts: stored.ts, emitted_now: true };
+  } catch {
+    return { marker_ts: 0, emitted_now: false };
+  }
+}
+function categorizeCiteTag(tag) {
+  if (tag === "planned" || tag === "recalled" || tag === "chained-from" || tag === "none") {
+    return { category: tag };
+  }
+  if (tag === "dismissed") {
+    return { category: "dismissed", reason: "unspecified" };
+  }
+  if (tag.startsWith("dismissed:")) {
+    const remainder = tag.slice("dismissed:".length);
+    if (remainder.startsWith("other:")) {
+      return { category: "dismissed", reason: remainder.slice("other:".length) || "other" };
+    }
+    return { category: "dismissed", reason: remainder || "unspecified" };
+  }
+  return { category: "none" };
+}
+function matchesRelevancePath(editPath, relevancePaths) {
+  if (relevancePaths.length === 0) {
+    return false;
+  }
+  const normalized = normalizePath(editPath);
+  for (const glob of relevancePaths) {
+    if (minimatch(normalized, glob, { dot: true, matchBase: false })) {
+      return true;
+    }
+  }
+  return false;
+}
+async function runDoctorCiteCoverage(projectRoot, options) {
+  const marker = await ensureCitePolicyActivatedMarker(projectRoot);
+  const generatedAt = (/* @__PURE__ */ new Date()).toISOString();
+  const zeroMetrics = {
+    edits_touched: 0,
+    qualifying_cites: 0,
+    recalled_unverified: 0,
+    expected_but_missed: 0,
+    total_turns: 0
+  };
+  if (marker.marker_ts === 0) {
+    return {
+      status: "skipped",
+      marker_ts: 0,
+      marker_emitted_now: false,
+      since_ts: options.since,
+      client_filter: options.client,
+      metrics: zeroMetrics,
+      generated_at: generatedAt
+    };
+  }
+  const effectiveSince = Math.max(marker.marker_ts, options.since);
+  let ledgerEvents = [];
+  try {
+    const result = await readEventLedger(projectRoot, { since: effectiveSince });
+    ledgerEvents = result.events;
+  } catch {
+    return {
+      status: "ok",
+      marker_ts: marker.marker_ts,
+      marker_emitted_now: marker.emitted_now,
+      since_ts: effectiveSince,
+      client_filter: options.client,
+      metrics: zeroMetrics,
+      generated_at: generatedAt
+    };
+  }
+  const assistantTurns = [];
+  const editEvents = [];
+  const fetchEvents = [];
+  for (const event of ledgerEvents) {
+    switch (event.event_type) {
+      case "assistant_turn_observed":
+        assistantTurns.push(event);
+        break;
+      case "edit_intent_checked":
+        editEvents.push(event);
+        break;
+      case "knowledge_sections_fetched":
+        fetchEvents.push(event);
+        break;
+      default:
+        break;
+    }
+  }
+  const filteredTurns = options.client === "all" ? assistantTurns : assistantTurns.filter((t) => t.client === options.client);
+  let clientSessionIds = null;
+  if (options.client !== "all") {
+    clientSessionIds = /* @__PURE__ */ new Set();
+    for (const turn of assistantTurns) {
+      if (turn.client === options.client) {
+        const sid = turn.session_id;
+        if (typeof sid === "string" && sid.length > 0) {
+          clientSessionIds.add(sid);
+        }
+      }
+    }
+  }
+  const kbIndex = /* @__PURE__ */ new Map();
+  try {
+    const meta = await readAgentsMeta(projectRoot);
+    for (const node of Object.values(meta.nodes)) {
+      const stableId = node.stable_id;
+      if (typeof stableId !== "string" || stableId.length === 0) continue;
+      const description = node.description;
+      if (description === void 0) continue;
+      const paths = description.relevance_paths ?? [];
+      const scope = description.relevance_scope ?? "broad";
+      kbIndex.set(stableId, {
+        relevance_paths: paths,
+        // A broad entry with no paths is the safe default. A narrow entry must
+        // carry at least one path; an empty-paths narrow is treated as broad.
+        relevance_scope: scope === "narrow" && paths.length > 0 ? "narrow" : "broad"
+      });
+    }
+  } catch {
+  }
+  const fetchesBySession = /* @__PURE__ */ new Map();
+  for (const fetch of fetchEvents) {
+    const sid = fetch.session_id;
+    if (typeof sid !== "string" || sid.length === 0) continue;
+    const list = fetchesBySession.get(sid) ?? [];
+    list.push(fetch.ts);
+    fetchesBySession.set(sid, list);
+  }
+  for (const list of fetchesBySession.values()) {
+    list.sort((a, b) => a - b);
+  }
+  const RECALL_WINDOW_MS = 6e4;
+  const isRecallVerified = (turn) => {
+    const sid = turn.session_id;
+    if (typeof sid !== "string" || sid.length === 0) return false;
+    const fetches = fetchesBySession.get(sid);
+    if (fetches === void 0 || fetches.length === 0) return false;
+    for (const ft of fetches) {
+      if (Math.abs(ft - turn.ts) <= RECALL_WINDOW_MS) return true;
+    }
+    return false;
+  };
+  const dismissedHistogram = {};
+  const perClientAccum = /* @__PURE__ */ new Map();
+  const emptyMetrics = () => ({
+    edits_touched: 0,
+    qualifying_cites: 0,
+    recalled_unverified: 0,
+    expected_but_missed: 0,
+    total_turns: 0
+  });
+  const bumpClient = (client, mut) => {
+    if (typeof client !== "string" || client.length === 0) return;
+    const existing = perClientAccum.get(client) ?? emptyMetrics();
+    mut(existing);
+    perClientAccum.set(client, existing);
+  };
+  const sessionCitedKbs = /* @__PURE__ */ new Map();
+  let totalTurns = 0;
+  let qualifyingCites = 0;
+  let recalledUnverified = 0;
+  for (const turn of filteredTurns) {
+    totalTurns += 1;
+    bumpClient(turn.client, (m) => {
+      m.total_turns += 1;
+    });
+    const sid = turn.session_id;
+    if (typeof sid === "string" && sid.length > 0) {
+      const set = sessionCitedKbs.get(sid) ?? /* @__PURE__ */ new Set();
+      for (const id of turn.cite_ids) {
+        set.add(id);
+      }
+      sessionCitedKbs.set(sid, set);
+    }
+    let turnHadRecalled = false;
+    for (const tag of turn.cite_tags) {
+      const { category, reason } = categorizeCiteTag(tag);
+      switch (category) {
+        case "planned":
+        case "recalled":
+        case "chained-from":
+          qualifyingCites += 1;
+          bumpClient(turn.client, (m) => {
+            m.qualifying_cites += 1;
+          });
+          if (category === "recalled") turnHadRecalled = true;
+          break;
+        case "dismissed": {
+          const key = reason ?? "unspecified";
+          dismissedHistogram[key] = (dismissedHistogram[key] ?? 0) + 1;
+          break;
+        }
+        case "none":
+        default:
+          break;
+      }
+    }
+    if (turnHadRecalled && !isRecallVerified(turn)) {
+      recalledUnverified += 1;
+      bumpClient(turn.client, (m) => {
+        m.recalled_unverified += 1;
+      });
+    }
+  }
+  let editsTouched = 0;
+  let expectedButMissed = 0;
+  for (const edit of editEvents) {
+    const sid = edit.session_id;
+    if (clientSessionIds !== null) {
+      if (typeof sid !== "string" || sid.length === 0) continue;
+      if (!clientSessionIds.has(sid)) continue;
+    }
+    editsTouched += 1;
+    if (typeof sid !== "string" || sid.length === 0) continue;
+    const citedSet = sessionCitedKbs.get(sid) ?? /* @__PURE__ */ new Set();
+    for (const [kbId, kb] of kbIndex) {
+      if (kb.relevance_scope !== "narrow") continue;
+      if (!matchesRelevancePath(edit.path, kb.relevance_paths)) continue;
+      if (!citedSet.has(kbId)) {
+        expectedButMissed += 1;
+      }
+    }
+  }
+  const metrics = {
+    edits_touched: editsTouched,
+    qualifying_cites: qualifyingCites,
+    recalled_unverified: recalledUnverified,
+    expected_but_missed: expectedButMissed,
+    total_turns: totalTurns
+  };
+  let perClient;
+  if (options.client === "all" && perClientAccum.size > 0) {
+    perClient = {};
+    for (const [client, m] of perClientAccum) {
+      perClient[client] = m;
+    }
+  }
+  return {
+    status: "ok",
+    marker_ts: marker.marker_ts,
+    marker_emitted_now: marker.emitted_now,
+    since_ts: effectiveSince,
+    client_filter: options.client,
+    metrics,
+    ...perClient !== void 0 ? { per_client: perClient } : {},
+    ...Object.keys(dismissedHistogram).length > 0 ? { dismissed_reason_histogram: dismissedHistogram } : {},
+    generated_at: generatedAt
+  };
+}
 function createFixMessage(fixed, report) {
   const fixedText = fixed.length === 0 ? "No deterministic doctor fixes were needed." : `Applied ${fixed.length} deterministic doctor fix${fixed.length === 1 ? "" : "es"}.`;
   const manualText = report.manual_errors.length === 0 ? "No manual errors remain." : `${report.manual_errors.length} manual error${report.manual_errors.length === 1 ? "" : "s"} remain.`;
@@ -4332,5 +4959,6 @@ export {
   normalizeKnowledgePath,
   runDoctorReport,
   runDoctorFix,
-  runDoctorApplyLint
+  runDoctorApplyLint,
+  runDoctorCiteCoverage
 };

package/dist/{http-B3UKRP5Y.js → http-JGWQGUZS.js}

@@ -14,7 +14,7 @@ import {
   readEventLedger,
   runDoctorReport,
   sha256
-} from "./chunk-3ZBYYPXQ.js";
+} from "./chunk-7R6MFA7Y.js";
 
 // src/http.ts
 import { randomUUID as randomUUID2 } from "crypto";

package/dist/index.d.ts

@@ -97,6 +97,27 @@ type DoctorApplyLintReport = {
 declare function runDoctorReport(target: string): Promise<DoctorReport>;
 declare function runDoctorFix(target: string): Promise<DoctorFixReport>;
 declare function runDoctorApplyLint(target: string): Promise<DoctorApplyLintReport>;
+type CiteCoverageReport = {
+    status: "ok" | "skipped";
+    marker_ts: number;
+    marker_emitted_now: boolean;
+    since_ts: number;
+    client_filter: "cc" | "codex" | "cursor" | "all";
+    metrics: {
+        edits_touched: number;
+        qualifying_cites: number;
+        recalled_unverified: number;
+        expected_but_missed: number;
+        total_turns: number;
+    };
+    per_client?: Record<string, Partial<CiteCoverageReport["metrics"]>>;
+    dismissed_reason_histogram?: Record<string, number>;
+    generated_at: string;
+};
+declare function runDoctorCiteCoverage(projectRoot: string, options: {
+    since: number;
+    client: "cc" | "codex" | "cursor" | "all";
+}): Promise<CiteCoverageReport>;
 
 type KnowledgeMetaBuildSource = "doctor_fix" | "sync_meta";
 type KnowledgeMetaBuildResult = {
@@ -382,4 +403,4 @@ declare function startHttpServer(options: {
     authToken?: string;
 }): Promise<Server>;
 
-export { AGENTS_MD_RESOURCE_URI, type AcquireOptions, type DoctorApplyLintMutation, type DoctorApplyLintMutationKind, type DoctorApplyLintReport, type DoctorFixReport, type DoctorIssue, type DoctorReport, EVENT_LEDGER_PATH, type InFlightTracker, KnowledgeIdAllocator, type KnowledgeMetaBuildResult, type KnowledgeMetaBuildSource, type KnowledgeSyncLedgerEvent, type KnowledgeSyncOptions, type KnowledgeSyncReport, LEDGER_PATH, LEGACY_LEDGER_PATH, type LedgerEvent, type LockState, type PlanContextInput, type PlanContextResult, type ReconcileKnowledgeOptions, type RequirementProfile, type SelectionTokenState, ServeLockHeldError, type ShutdownHandlerDeps, type StructuredWarning, type WriteKnowledgeMetaOptions, acquireLock, appendEventLedgerEvent, buildKnowledgeMeta, checkLockOrThrow, computeKnowledgeBasedAgentsMeta, computeKnowledgeTestIndex, createFabricServer, createInFlightTracker, createShutdownHandler, deriveKnowledgeMetaLayer, deriveKnowledgeMetaTopologyType, ensureKnowledgeFresh, extractKnowledge, flushAndSyncEventLedger, formatPreexistingRootMessage, getEventLedgerPath, getLedgerPath, getLegacyLedgerPath, isSameKnowledgeTestIndex, planContext, readLockState, readSelectionToken, reconcileKnowledge, releaseLock, reviewKnowledge, runDoctorApplyLint, runDoctorFix, runDoctorReport, stableStringify, startHttpServer, startStdioServer, writeKnowledgeMeta };
+export { AGENTS_MD_RESOURCE_URI, type AcquireOptions, type CiteCoverageReport, type DoctorApplyLintMutation, type DoctorApplyLintMutationKind, type DoctorApplyLintReport, type DoctorFixReport, type DoctorIssue, type DoctorReport, EVENT_LEDGER_PATH, type InFlightTracker, KnowledgeIdAllocator, type KnowledgeMetaBuildResult, type KnowledgeMetaBuildSource, type KnowledgeSyncLedgerEvent, type KnowledgeSyncOptions, type KnowledgeSyncReport, LEDGER_PATH, LEGACY_LEDGER_PATH, type LedgerEvent, type LockState, type PlanContextInput, type PlanContextResult, type ReconcileKnowledgeOptions, type RequirementProfile, type SelectionTokenState, ServeLockHeldError, type ShutdownHandlerDeps, type StructuredWarning, type WriteKnowledgeMetaOptions, acquireLock, appendEventLedgerEvent, buildKnowledgeMeta, checkLockOrThrow, computeKnowledgeBasedAgentsMeta, computeKnowledgeTestIndex, createFabricServer, createInFlightTracker, createShutdownHandler, deriveKnowledgeMetaLayer, deriveKnowledgeMetaTopologyType, ensureKnowledgeFresh, extractKnowledge, flushAndSyncEventLedger, formatPreexistingRootMessage, getEventLedgerPath, getLedgerPath, getLegacyLedgerPath, isSameKnowledgeTestIndex, planContext, readLockState, readSelectionToken, reconcileKnowledge, releaseLock, reviewKnowledge, runDoctorApplyLint, runDoctorCiteCoverage, runDoctorFix, runDoctorReport, stableStringify, startHttpServer, startStdioServer, writeKnowledgeMeta };

package/dist/index.js

@@ -21,12 +21,13 @@ import {
   reconcileKnowledge,
   resolveProjectRoot,
   runDoctorApplyLint,
+  runDoctorCiteCoverage,
   runDoctorFix,
   runDoctorReport,
   sha256,
   stableStringify,
   writeKnowledgeMeta
-} from "./chunk-3ZBYYPXQ.js";
+} from "./chunk-7R6MFA7Y.js";
 
 // src/index.ts
 import { existsSync as existsSync4 } from "fs";
@@ -318,9 +319,9 @@ ${renderEvidenceBlock(newSummary, newRecentPaths)}
     const pathSection = /Recent paths:\s*\n([\s\S]*?)(?:\n\s*Notes:|$)/u.exec(block);
     if (pathSection !== null) {
       for (const rawLine of (pathSection[1] ?? "").split(/\r?\n/u)) {
-        const t = rawLine.trim();
-        if (t.startsWith("- ")) {
-          existingPaths.push(t.slice(2).trim());
+        const t2 = rawLine.trim();
+        if (t2.startsWith("- ")) {
+          existingPaths.push(t2.slice(2).trim());
         }
       }
     }
@@ -329,16 +330,16 @@ ${renderEvidenceBlock(newSummary, newRecentPaths)}
     const bulletLines = [];
     let prose = [];
     for (const rawLine of noteBody.split(/\r?\n/u)) {
-      const t = rawLine.trim();
-      if (t.length === 0) continue;
-      if (t.startsWith("- ")) {
+      const t2 = rawLine.trim();
+      if (t2.length === 0) continue;
+      if (t2.startsWith("- ")) {
         if (prose.length > 0) {
           existingNotes.push(prose.join(" ").trim());
           prose = [];
         }
-        bulletLines.push(t.slice(2).trim());
+        bulletLines.push(t2.slice(2).trim());
       } else {
-        prose.push(t);
+        prose.push(t2);
       }
     }
     if (prose.length > 0) existingNotes.push(prose.join(" ").trim());
@@ -934,7 +935,7 @@ async function listPending(projectRoot, filters) {
         }
         if (filters?.tags !== void 0 && filters.tags.length > 0) {
           const itemTags = fm.tags ?? [];
-          const hasAll = filters.tags.every((t) => itemTags.includes(t));
+          const hasAll = filters.tags.every((t2) => itemTags.includes(t2));
           if (!hasAll) continue;
         }
         if (filters?.created_after !== void 0) {
@@ -1234,7 +1235,7 @@ async function searchEntries(projectRoot, query, filters) {
         }
         if (filters?.tags !== void 0 && filters.tags.length > 0) {
           const itemTags = fm.tags ?? [];
-          const hasAll = filters.tags.every((t) => itemTags.includes(t));
+          const hasAll = filters.tags.every((t2) => itemTags.includes(t2));
           if (!hasAll) continue;
         }
         if (filters?.created_after !== void 0) {
@@ -1781,8 +1782,10 @@ function registerKnowledgeSections(server, tracker) {
 // src/services/serve-lock.ts
 import fs from "fs";
 import path from "path";
+import { createTranslator, detectNodeLocale } from "@fenglimg/fabric-shared";
 import { IOFabricError } from "@fenglimg/fabric-shared/errors";
 var LOCK_FILENAME = ".serve.lock";
+var t = createTranslator(detectNodeLocale());
 var ServeLockHeldError = class extends IOFabricError {
   code = "SERVE_LOCK_HELD";
   httpStatus = 423;
@@ -1813,7 +1816,7 @@ function acquireLock(projectRoot, opts) {
       throw new ServeLockHeldError(
         `serve lock held by live PID ${state.pid}`,
         {
-          actionHint: `Stop the other process (PID ${state.pid}) or run with --force to override`,
+          actionHint: t("cli.serve.lock-held.action-hint", { pid: String(state.pid) }),
           details: state
         }
       );
@@ -1863,7 +1866,7 @@ function checkLockOrThrow(projectRoot, opts) {
   throw new ServeLockHeldError(
     `serve lock held by live PID ${state.pid}`,
     {
-      actionHint: `Stop the other serve process (PID ${state.pid}) before running this command, or pass --force to override`,
+      actionHint: t("cli.serve.lock-held.action-hint", { pid: String(state.pid) }),
       details: state
     }
   );
@@ -1890,7 +1893,7 @@ function formatPreexistingRootMessage(projectRoot) {
 function createFabricServer(tracker) {
   const server = new McpServer({
     name: "fabric-knowledge-server",
-    version: "2.0.0-rc.13"
+    version: "2.0.0-rc.21"
   });
   registerPlanContext(server, tracker);
   registerKnowledgeSections(server, tracker);
@@ -1990,7 +1993,7 @@ function createShutdownHandler(deps) {
   };
 }
 async function startHttpServer(options) {
-  const { createFabricHttpApp } = await import("./http-B3UKRP5Y.js");
+  const { createFabricHttpApp } = await import("./http-JGWQGUZS.js");
   const { port, projectRoot, host = "127.0.0.1", authToken } = options;
   const app = createFabricHttpApp({ projectRoot, host, authToken });
   return await new Promise((resolveServer, rejectServer) => {
@@ -2048,6 +2051,7 @@ export {
   releaseLock,
   reviewKnowledge,
   runDoctorApplyLint,
+  runDoctorCiteCoverage,
   runDoctorFix,
   runDoctorReport,
   stableStringify,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fenglimg/fabric-server",
-  "version": "2.0.0-rc.13",
+  "version": "2.0.0-rc.21",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -13,7 +13,7 @@
     "express": "^5.2.1",
     "minimatch": "^10.0.1",
     "zod": "^3.25.0",
-    "@fenglimg/fabric-shared": "2.0.0-rc.13"
+    "@fenglimg/fabric-shared": "2.0.0-rc.21"
   },
   "devDependencies": {
     "@types/express": "^5.0.6",