@fenglimg/fabric-server 2.0.0-rc.27 → 2.0.0-rc.29

package/dist/{http-3WADEK3O.js → http-TAI5X7U5.js}

@@ -14,7 +14,7 @@ import {
   readEventLedger,
   runDoctorReport,
   sha256
-} from "./chunk-NZSGNQKE.js";
+} from "./chunk-CTQ4UMO4.js";
 
 // src/http.ts
 import { randomUUID as randomUUID2 } from "crypto";
@@ -972,6 +972,16 @@ function createBearerAuthMiddleware(token) {
     next();
   };
 }
+function createLoopbackDenyMiddleware() {
+  return function loopbackDenyMiddleware(_req, res, _next) {
+    sendError(
+      res,
+      401,
+      "UNAUTHORIZED",
+      "FABRIC_AUTH_TOKEN is not set. Either export FABRIC_AUTH_TOKEN=<secret> before running `fab serve`, or pass `--allow-loopback-no-auth` to explicitly opt in to unauthenticated loopback access (security risk)."
+    );
+  };
+}
 function readAuthorizationHeader(value) {
   if (typeof value === "string" && value.length > 0) {
     return value;
@@ -998,6 +1008,10 @@ function hashToken(token) {
 // src/http.ts
 var DEFAULT_HOST = "127.0.0.1";
 var NOTIFY_DEBOUNCE_MS = 200;
+var LOOPBACK_HOSTS = /* @__PURE__ */ new Set(["127.0.0.1", "localhost", "::1"]);
+function isLoopbackHost(host) {
+  return LOOPBACK_HOSTS.has(host);
+}
 var JsonlEventStore = class {
   constructor(projectRoot) {
     this.projectRoot = projectRoot;
@@ -1089,7 +1103,12 @@ function handleCacheWatcherEvent(relativePath, projectRoot, sessions, timers) {
   }
 }
 function createFabricHttpApp(options) {
-  const { projectRoot, host = DEFAULT_HOST, authToken } = options;
+  const { projectRoot, host = DEFAULT_HOST, authToken, allowLoopbackNoAuth = false } = options;
+  if (allowLoopbackNoAuth && authToken === void 0 && !isLoopbackHost(host)) {
+    throw new Error(
+      `createFabricHttpApp: allowLoopbackNoAuth=true requires a loopback host (127.0.0.1 / localhost / ::1); got ${JSON.stringify(host)}. Either bind to loopback or set FABRIC_AUTH_TOKEN.`
+    );
+  }
   const app = createMcpExpressApp({ host });
   const eventStore = new JsonlEventStore(projectRoot);
   const sessions = /* @__PURE__ */ new Map();
@@ -1142,6 +1161,11 @@ function createFabricHttpApp(options) {
     app.use("/api", bearerAuth);
     app.use("/events", bearerAuth);
     app.use("/mcp", bearerAuth);
+  } else if (!allowLoopbackNoAuth) {
+    const denyAll = createLoopbackDenyMiddleware();
+    app.use("/api", denyAll);
+    app.use("/events", denyAll);
+    app.use("/mcp", denyAll);
   }
   registerKnowledgeApi(app, projectRoot);
   registerKnowledgeContextApi(app, projectRoot);

package/dist/index.d.ts

@@ -40,6 +40,11 @@ type DoctorIssue = {
     path?: string;
     actionHint?: string;
 };
+type DoctorPayloadLimits = {
+    warn_bytes: number;
+    hard_bytes: number;
+    source: "default" | "config";
+};
 type DoctorSummary = {
     target: string;
     framework: {
@@ -60,6 +65,7 @@ type DoctorSummary = {
     warningCount: number;
     infoCount: number;
     targetFiles: Record<string, boolean>;
+    payload_limits: DoctorPayloadLimits;
 };
 type DoctorReport = {
     status: DoctorStatus;
@@ -156,7 +162,7 @@ type ArchiveHistoryReport = {
 declare function runDoctorArchiveHistory(projectRoot: string, options: {
     since: number;
 }): Promise<ArchiveHistoryReport>;
-type EnrichDescriptionsMode = "auto" | "interactive";
+type EnrichDescriptionsMode = "auto" | "preview" | "readonly" | "interactive";
 type EnrichDescriptionsCandidate = {
     path: string;
     missing: Array<"intent_clues" | "tech_stack" | "impact" | "must_read_if">;
@@ -194,13 +200,13 @@ type WriteKnowledgeMetaOptions = {
  * guideline+process = deferred to rc.25 LLM-judge). Cited ids absent from
  * this map fall into the `cite_id_unresolved` bucket.
  *
- * **Singular knowledge_type contract (rc.24 lock):** the returned map values
- * are the SINGULAR `KnowledgeType` enum (`"model" | "decision" | "guideline"
- * | "pitfall" | "process"`) — matching both the on-disk `agents.meta.json`
- * storage AND the canonical `KnowledgeTypeSchema` exported from
- * `@fenglimg/fabric-shared`. No normalization happens at this boundary; the
- * loader is a thin extract over engine-maintained meta. Downstream callers
- * (TASK-08 doctor) must match against the singular enum.
+ * **Plural knowledge_type contract (rc.29 BUG-C1 unification):** the returned
+ * map values are the PLURAL `KnowledgeType` enum (`"models" | "decisions" |
+ * "guidelines" | "pitfalls" | "processes"`) — matching disk frontmatter,
+ * filesystem layout, MCP I/O surface, and the canonical `KnowledgeTypeSchema`
+ * exported from `@fenglimg/fabric-shared`. Legacy singular frontmatter is
+ * normalized at parse time (see `SINGULAR_TO_PLURAL` in `parseFrontmatter`);
+ * downstream callers (TASK-08 doctor) match against the plural enum.
  *
  * Both team (KT-*) and personal (KP-*) entries are included — they live in
  * the same `meta.nodes` map.
@@ -382,6 +388,19 @@ interface KnowledgeSyncOptions {
     mode?: "incremental" | "full";
     /** When true, invalid frontmatter throws RuleValidationError (default: false — collect as warning). */
     throwOnInvalidFrontmatter?: boolean;
+    /**
+     * v2.0.0-rc.29 TASK-005 (BUG-G1): when true, `ensureKnowledgeFresh`
+     * synchronously follows a drift detection with a `reconcileKnowledge`
+     * call to materialize the auto-heal (rewrite agents.meta.json + emit a
+     * paired `knowledge_meta_auto_healed` event). Default false preserves
+     * the rc.28 hot-path semantics where drift detection never blocks the
+     * MCP read on a meta rebuild. Opt-in is intended for callers that can
+     * tolerate ~tens-of-ms extra latency in exchange for the invariant
+     * "every knowledge_drift_detected has a paired heal event in the same
+     * tail window." Audit (BUG-G1) found 5/72 drifts healed on this repo
+     * (~7%) because the hot path emitted detect-only events.
+     */
+    autoHealOnDrift?: boolean;
 }
 interface StructuredWarning {
     code: string;
@@ -432,7 +451,7 @@ interface ReconcileKnowledgeOptions {
      * plan_context call's auto-heal, which leaves the entry undiscoverable in
      * the description_index window between approve and the next hint call.
      */
-    trigger?: "startup" | "doctor" | "manual" | "auto-heal-description" | "post-approve" | "post-modify";
+    trigger?: "startup" | "doctor" | "manual" | "auto-heal-description" | "auto-heal-after-drift" | "post-approve" | "post-modify";
 }
 /**
  * Full scan + rewrites agents.meta.json with ground-truth disk state + emits
@@ -501,6 +520,7 @@ declare function startHttpServer(options: {
     projectRoot: string;
     host?: string;
     authToken?: string;
+    allowLoopbackNoAuth?: boolean;
 }): Promise<Server>;
 
 export { AGENTS_MD_RESOURCE_URI, type AcquireOptions, type ArchiveHistoryEntry, type ArchiveHistoryReport, type CiteCoverageReport, type DoctorApplyLintMutation, type DoctorApplyLintMutationKind, type DoctorApplyLintReport, type DoctorFixReport, type DoctorIssue, type DoctorReport, EVENT_LEDGER_PATH, type EnrichDescriptionsCandidate, type EnrichDescriptionsMode, type EnrichDescriptionsReport, 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, enrichDescriptions, ensureKnowledgeFresh, extractKnowledge, flushAndSyncEventLedger, formatPreexistingRootMessage, getEventLedgerPath, getLedgerPath, getLegacyLedgerPath, isSameKnowledgeTestIndex, loadKbIdTypeMap, planContext, readLockState, readSelectionToken, reconcileKnowledge, releaseLock, reviewKnowledge, runDoctorApplyLint, runDoctorArchiveHistory, runDoctorCiteCoverage, runDoctorFix, runDoctorReport, stableStringify, startHttpServer, startStdioServer, writeKnowledgeMeta };

package/dist/index.js

@@ -26,6 +26,8 @@ import {
   loadKbIdTypeMap,
   normalizeKnowledgePath,
   readLockState,
+  readPayloadLimits,
+  readSelectionTokenTtlMs,
   reconcileKnowledge,
   releaseLock,
   resolveProjectRoot,
@@ -37,12 +39,12 @@ import {
   sha256,
   stableStringify,
   writeKnowledgeMeta
-} from "./chunk-NZSGNQKE.js";
+} from "./chunk-CTQ4UMO4.js";
 
 // src/index.ts
-import { existsSync as existsSync4 } from "fs";
+import { existsSync as existsSync3 } from "fs";
 import { readFile as readFile5 } from "fs/promises";
-import { join as join5, resolve as resolve2 } from "path";
+import { join as join4, resolve as resolve2 } from "path";
 import { fileURLToPath } from "url";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -155,29 +157,11 @@ import {
 } from "@fenglimg/fabric-shared/schemas/api-contracts";
 import { enforcePayloadLimit } from "@fenglimg/fabric-shared/node/mcp-payload-guard";
 
-// src/config-loader.ts
-import { existsSync, readFileSync } from "fs";
-import { join } from "path";
-function readFabricConfig(projectRoot) {
-  const configPath = join(projectRoot, "fabric.config.json");
-  if (!existsSync(configPath)) {
-    return {};
-  }
-  const parsed = JSON.parse(readFileSync(configPath, "utf8"));
-  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
-    throw new Error(`Expected object in ${configPath}`);
-  }
-  return parsed;
-}
-function readPayloadLimits(projectRoot) {
-  return readFabricConfig(projectRoot).mcpPayloadLimits;
-}
-
 // src/services/extract-knowledge.ts
-import { existsSync as existsSync2 } from "fs";
+import { existsSync } from "fs";
 import { readFile } from "fs/promises";
 import { homedir } from "os";
-import { join as join2, relative } from "path";
+import { join, relative } from "path";
 import {
   PROPOSED_REASON_DESCRIPTIONS
 } from "@fenglimg/fabric-shared/schemas/api-contracts";
@@ -185,9 +169,9 @@ var TEAM_PENDING_REL = ".fabric/knowledge/pending";
 var SLUG_MAX_LENGTH = 40;
 function pendingBase(layer, projectRoot) {
   if (layer === "personal") {
-    return join2(resolvePersonalRoot(), ".fabric", "knowledge", "pending");
+    return join(resolvePersonalRoot(), ".fabric", "knowledge", "pending");
   }
-  return join2(projectRoot, TEAM_PENDING_REL);
+  return join(projectRoot, TEAM_PENDING_REL);
 }
 function resolvePersonalRoot() {
   return process.env.FABRIC_HOME ?? homedir();
@@ -243,10 +227,10 @@ async function extractKnowledge(projectRoot, input) {
     });
   }
   const baseDir = pendingBase(layer, projectRoot);
-  const absolutePath = join2(baseDir, input.type, `${sanitizedSlug}.md`);
+  const absolutePath = join(baseDir, input.type, `${sanitizedSlug}.md`);
   const reportedPath = layer === "personal" ? `~/${relative(resolvePersonalRoot(), absolutePath)}` : relative(projectRoot, absolutePath);
   await ensureParentDirectory(absolutePath);
-  if (existsSync2(absolutePath)) {
+  if (existsSync(absolutePath)) {
     const existing = await readFile(absolutePath, "utf8");
     const existingKey = readFrontmatterKey(existing, "x-fabric-idempotency-key");
     if (existingKey === idempotencyKey) {
@@ -584,7 +568,7 @@ import { enforcePayloadLimit as enforcePayloadLimit2 } from "@fenglimg/fabric-sh
 // src/services/plan-context.ts
 import { minimatch } from "minimatch";
 import { deriveAgentsMetaLayer } from "@fenglimg/fabric-shared";
-var SELECTION_TOKEN_TTL_MS = 5 * 60 * 1e3;
+var SELECTION_TOKEN_TTL_DEFAULT_MS = 5 * 60 * 1e3;
 var selectionTokenCache = /* @__PURE__ */ new Map();
 function assertPathInSandbox(rawPath) {
   if (rawPath === "**" || rawPath === "*") return;
@@ -644,7 +628,8 @@ async function planContext(projectRoot, input) {
   });
   const sharedDescriptionIndex = dedupeDescriptionIndex(entries.flatMap((entry) => entry.description_index));
   const sharedStableIds = sharedDescriptionIndex.map((item) => item.stable_id);
-  const selectionToken = createSelectionToken(meta.revision, uniquePaths, [], sharedStableIds);
+  const ttlMs = readSelectionTokenTtlMs(projectRoot) ?? SELECTION_TOKEN_TTL_DEFAULT_MS;
+  const selectionToken = createSelectionToken(meta.revision, uniquePaths, [], sharedStableIds, Date.now(), ttlMs);
   const result = {
     revision_hash: meta.revision,
     stale,
@@ -694,7 +679,7 @@ function readSelectionToken(token, now = Date.now()) {
   }
   return state2;
 }
-function createSelectionToken(revisionHash, targetPaths, requiredStableIds, aiSelectableStableIds, now = Date.now()) {
+function createSelectionToken(revisionHash, targetPaths, requiredStableIds, aiSelectableStableIds, now = Date.now(), ttlMs = SELECTION_TOKEN_TTL_DEFAULT_MS) {
   const token = `selection:${revisionHash}:${now.toString(36)}:${Math.random().toString(36).slice(2)}`;
   selectionTokenCache.set(token, {
     token,
@@ -703,7 +688,7 @@ function createSelectionToken(revisionHash, targetPaths, requiredStableIds, aiSe
     required_stable_ids: requiredStableIds,
     ai_selectable_stable_ids: aiSelectableStableIds,
     created_at: now,
-    expires_at: now + SELECTION_TOKEN_TTL_MS
+    expires_at: now + ttlMs
   });
   return token;
 }
@@ -916,10 +901,10 @@ import { enforcePayloadLimit as enforcePayloadLimit3 } from "@fenglimg/fabric-sh
 
 // src/services/review.ts
 import { execFileSync } from "child_process";
-import { existsSync as existsSync3 } from "fs";
+import { existsSync as existsSync2 } from "fs";
 import { readFile as readFile3, readdir, unlink } from "fs/promises";
 import { homedir as homedir2 } from "os";
-import { basename, join as join3, relative as relative2, resolve } from "path";
+import { basename, join as join2, relative as relative2, resolve } from "path";
 
 // src/services/knowledge-id-allocator.ts
 import { readFile as readFile2 } from "fs/promises";
@@ -1002,9 +987,9 @@ function isNodeError(err) {
 var PENDING_BASE_TEAM_REL = ".fabric/knowledge/pending";
 function pendingBaseAbs(layer, projectRoot) {
   if (layer === "personal") {
-    return join3(resolvePersonalRoot2(), ".fabric", "knowledge", "pending");
+    return join2(resolvePersonalRoot2(), ".fabric", "knowledge", "pending");
   }
-  return join3(projectRoot, PENDING_BASE_TEAM_REL);
+  return join2(projectRoot, PENDING_BASE_TEAM_REL);
 }
 var PLURAL_TYPES = [
   "decisions",
@@ -1013,13 +998,6 @@ var PLURAL_TYPES = [
   "models",
   "processes"
 ];
-var PLURAL_TO_SINGULAR = {
-  decisions: "decision",
-  pitfalls: "pitfall",
-  guidelines: "guideline",
-  models: "model",
-  processes: "process"
-};
 async function reviewKnowledge(projectRoot, input) {
   switch (input.action) {
     case "list":
@@ -1114,8 +1092,8 @@ async function listPending(projectRoot, filters) {
   ];
   for (const source of sources) {
     for (const type of typesToScan) {
-      const dir = join3(source.root, type);
-      if (!existsSync3(dir)) {
+      const dir = join2(source.root, type);
+      if (!existsSync2(dir)) {
         continue;
       }
       let entries;
@@ -1126,7 +1104,7 @@ async function listPending(projectRoot, filters) {
       }
       for (const name of entries) {
         if (!name.endsWith(".md")) continue;
-        const absolutePath = join3(dir, name);
+        const absolutePath = join2(dir, name);
         let content;
         try {
           content = await readFile3(absolutePath, "utf8");
@@ -1182,7 +1160,7 @@ async function listPending(projectRoot, filters) {
 }
 async function approveAll(projectRoot, pendingPaths) {
   const allocator = new KnowledgeIdAllocator(
-    join3(projectRoot, ".fabric", "agents.meta.json")
+    join2(projectRoot, ".fabric", "agents.meta.json")
   );
   const approved = [];
   for (const pendingPath of pendingPaths) {
@@ -1233,12 +1211,11 @@ async function approveOne(projectRoot, pendingPath, allocator) {
       throw new Error(`pending file missing or invalid 'type' frontmatter: ${pendingPath}`);
     }
     const layer = fm.layer ?? "team";
-    const singularType = PLURAL_TO_SINGULAR[pluralType];
-    const stableId = await allocator.allocate(layer, singularType);
+    const stableId = await allocator.allocate(layer, pluralType);
     allocatedId = stableId;
     const newFilename = `${stableId}--${slug}.md`;
-    const layerRoot = layer === "personal" ? join3(resolvePersonalRoot2(), ".fabric") : join3(projectRoot, ".fabric");
-    targetAbs = join3(layerRoot, "knowledge", pluralType, newFilename);
+    const layerRoot = layer === "personal" ? join2(resolvePersonalRoot2(), ".fabric") : join2(projectRoot, ".fabric");
+    targetAbs = join2(layerRoot, "knowledge", pluralType, newFilename);
     await ensureParentDirectory(targetAbs);
     const rewritten = rewriteFrontmatterForPromote(content, stableId);
     await atomicWriteText(targetAbs, rewritten);
@@ -1250,12 +1227,12 @@ async function approveOne(projectRoot, pendingPath, allocator) {
           stdio: ["ignore", "pipe", "pipe"]
         });
       } catch {
-        if (existsSync3(sourceAbs)) {
+        if (existsSync2(sourceAbs)) {
           await unlink(sourceAbs);
         }
       }
     } else {
-      if (existsSync3(sourceAbs)) {
+      if (existsSync2(sourceAbs)) {
         await unlink(sourceAbs);
       }
     }
@@ -1271,7 +1248,7 @@ async function approveOne(projectRoot, pendingPath, allocator) {
     }
     return { pending_path: pendingPath, stable_id: stableId };
   } catch (err) {
-    if (writtenTarget && targetAbs !== void 0 && existsSync3(targetAbs)) {
+    if (writtenTarget && targetAbs !== void 0 && existsSync2(targetAbs)) {
       try {
         await unlink(targetAbs);
       } catch {
@@ -1292,7 +1269,7 @@ async function rejectAll(projectRoot, pendingPaths, reason) {
   for (const pendingPath of pendingPaths) {
     try {
       const sandboxed = resolveSandboxedPath(projectRoot, pendingPath, { allowPersonal: true });
-      if (existsSync3(sandboxed.abs)) {
+      if (existsSync2(sandboxed.abs)) {
         const content = await readFile3(sandboxed.abs, "utf8");
         const merged = rewriteFrontmatterMerge(content, { status: "rejected" });
         if (merged !== content) {
@@ -1335,7 +1312,7 @@ function resolveModifyTarget(projectRoot, pendingPath) {
   } catch {
     return null;
   }
-  if (existsSync3(sandboxed.abs)) {
+  if (existsSync2(sandboxed.abs)) {
     return {
       absPath: sandboxed.abs,
       isInProjectTree: sandboxed.isInProjectTree,
@@ -1375,12 +1352,11 @@ async function modifyLayerFlip(projectRoot, target, content, fm, changes) {
   const fromScope = fm.relevance_scope ?? "broad";
   const shouldAutoDegrade = fromScope === "narrow" && fromLayer === "team" && toLayer === "personal";
   const allocator = new KnowledgeIdAllocator(
-    join3(projectRoot, ".fabric", "agents.meta.json")
+    join2(projectRoot, ".fabric", "agents.meta.json")
   );
-  const singularType = PLURAL_TO_SINGULAR[pluralType];
-  const newStableId = await allocator.allocate(toLayer, singularType);
-  const toRoot = toLayer === "personal" ? join3(resolvePersonalRoot2(), ".fabric") : join3(projectRoot, ".fabric");
-  const toAbs = join3(toRoot, "knowledge", pluralType, `${newStableId}--${slug}.md`);
+  const newStableId = await allocator.allocate(toLayer, pluralType);
+  const toRoot = toLayer === "personal" ? join2(resolvePersonalRoot2(), ".fabric") : join2(projectRoot, ".fabric");
+  const toAbs = join2(toRoot, "knowledge", pluralType, `${newStableId}--${slug}.md`);
   await ensureParentDirectory(toAbs);
   await emitEventBestEffort2(projectRoot, {
     event_type: "knowledge_promote_started",
@@ -1404,11 +1380,11 @@ async function modifyLayerFlip(projectRoot, target, content, fm, changes) {
         stdio: ["ignore", "pipe", "pipe"]
       });
     } catch {
-      if (existsSync3(target.absPath)) {
+      if (existsSync2(target.absPath)) {
         await unlink(target.absPath);
       }
     }
-  } else if (existsSync3(target.absPath)) {
+  } else if (existsSync2(target.absPath)) {
     await unlink(target.absPath);
   }
   await emitEventBestEffort2(projectRoot, {
@@ -1447,14 +1423,14 @@ async function searchEntries(projectRoot, query, filters) {
   const sources = [
     { root: pendingBaseAbs("team", projectRoot), isPending: true, isPersonal: false },
     { root: pendingBaseAbs("personal", projectRoot), isPending: true, isPersonal: true },
-    { root: join3(projectRoot, ".fabric", "knowledge"), isPending: false, isPersonal: false },
-    { root: join3(resolvePersonalRoot2(), ".fabric", "knowledge"), isPending: false, isPersonal: true }
+    { root: join2(projectRoot, ".fabric", "knowledge"), isPending: false, isPersonal: false },
+    { root: join2(resolvePersonalRoot2(), ".fabric", "knowledge"), isPending: false, isPersonal: true }
   ];
   const typesToScan = filters?.type !== void 0 ? [filters.type] : PLURAL_TYPES;
   for (const source of sources) {
     for (const type of typesToScan) {
-      const dir = join3(source.root, type);
-      if (!existsSync3(dir)) continue;
+      const dir = join2(source.root, type);
+      if (!existsSync2(dir)) continue;
       let entries;
       try {
         entries = await readdir(dir);
@@ -1463,7 +1439,7 @@ async function searchEntries(projectRoot, query, filters) {
       }
       for (const name of entries) {
         if (!name.endsWith(".md")) continue;
-        const absolutePath = join3(dir, name);
+        const absolutePath = join2(dir, name);
         let content;
         try {
           content = await readFile3(absolutePath, "utf8");
@@ -1505,15 +1481,14 @@ async function searchEntries(projectRoot, query, filters) {
         if (!matches) continue;
         const reportedPath = source.isPersonal ? `~/${relative2(resolvePersonalRoot2(), absolutePath)}` : relative2(projectRoot, absolutePath);
         items.push({
-          pending_path: reportedPath,
-          // v2.0.0-rc.27 TASK-001 (§2.12): absolute companion for personal
-          // entries (mirrors listPending).
-          ...source.isPersonal ? { pending_path_absolute: absolutePath } : {},
+          area: source.isPending ? "pending" : "canonical",
+          path: reportedPath,
+          ...source.isPersonal ? { path_absolute: absolutePath } : {},
           type,
           layer,
           maturity,
-          // Only pending entries carry an origin tag (search results that are
-          // canonical entries don't have a pending root to point back to).
+          // Only pending entries carry an origin tag (canonical hits live
+          // outside the dual-pending-root convention).
           ...source.isPending ? { origin: source.isPersonal ? "personal" : "team" } : {},
           ...fm.tags !== void 0 && fm.tags.length > 0 ? { tags: fm.tags } : {},
           ...fm.title !== void 0 ? { title: fm.title } : {},
@@ -1521,10 +1496,11 @@ async function searchEntries(projectRoot, query, filters) {
           ...fm.status !== void 0 ? { status: fm.status } : {},
           ...fm.deferred_until !== void 0 ? { deferred_until: fm.deferred_until } : {},
           // v2.0.0-rc.27 TASK-006 (audit §2.23): body emission when opted in.
-          // Reuse the already-computed bodyForSearch to avoid a second pass
-          // over the content (the search loop above extracted it iff
-          // include_body=true).
-          ...filters?.include_body === true ? { body: bodyForSearch } : {}
+          ...filters?.include_body === true ? { body: bodyForSearch } : {},
+          // Canonical hits always have an id; pending hits typically don't
+          // yet — surface the frontmatter id when present so consumers can
+          // dedupe across runs.
+          ...fm.id !== void 0 ? { stable_id: fm.id } : {}
         });
       }
     }
@@ -1536,7 +1512,7 @@ async function deferAll(projectRoot, pendingPaths, until, reason) {
   for (const pendingPath of pendingPaths) {
     try {
       const sandboxed = resolveSandboxedPath(projectRoot, pendingPath, { allowPersonal: true });
-      if (existsSync3(sandboxed.abs)) {
+      if (existsSync2(sandboxed.abs)) {
         const content = await readFile3(sandboxed.abs, "utf8");
         const patch = {
           status: "deferred",
@@ -1797,7 +1773,7 @@ import { enforcePayloadLimit as enforcePayloadLimit4 } from "@fenglimg/fabric-sh
 // src/services/knowledge-sections.ts
 import { readFile as readFile4 } from "fs/promises";
 import { homedir as homedir3 } from "os";
-import { join as join4 } from "path";
+import { join as join3 } from "path";
 var PRIORITY_ORDER = {
   high: 0,
   medium: 1,
@@ -1957,9 +1933,9 @@ function outputLevelOrder(level) {
 function resolveRuleSourcePath(projectRoot, contentRef) {
   if (contentRef.startsWith("~/.fabric/knowledge/")) {
     const home = process.env.FABRIC_HOME ?? homedir3();
-    return join4(home, ".fabric", "knowledge", contentRef.slice("~/.fabric/knowledge/".length));
+    return join3(home, ".fabric", "knowledge", contentRef.slice("~/.fabric/knowledge/".length));
   }
-  return join4(projectRoot, contentRef);
+  return join3(projectRoot, contentRef);
 }
 function pickSelectionReasons(selectedStableIds, reasons) {
   return Object.fromEntries(selectedStableIds.map((stableId) => [stableId, reasons[stableId] ?? ""]));
@@ -2028,15 +2004,15 @@ function formatError(error) {
 }
 function formatPreexistingRootMessage(projectRoot) {
   const preexisting = [];
-  if (existsSync4(join5(projectRoot, "CLAUDE.md"))) preexisting.push("CLAUDE.md");
-  if (existsSync4(join5(projectRoot, "AGENTS.md"))) preexisting.push("AGENTS.md");
+  if (existsSync3(join4(projectRoot, "CLAUDE.md"))) preexisting.push("CLAUDE.md");
+  if (existsSync3(join4(projectRoot, "AGENTS.md"))) preexisting.push("AGENTS.md");
   if (preexisting.length === 0) return null;
   return `[startup] info: detected ${preexisting.join(", ")} at project root. Note: Fabric serves knowledge from .fabric/knowledge/ via MCP \u2014 root markdown files are not auto-loaded into the AI context.`;
 }
 function createFabricServer(tracker) {
   const server = new McpServer({
     name: "fabric-knowledge-server",
-    version: "2.0.0-rc.27"
+    version: "2.0.0-rc.29"
   });
   registerPlanContext(server, tracker);
   registerKnowledgeSections(server, tracker);
@@ -2051,9 +2027,9 @@ function createFabricServer(tracker) {
     },
     async (_uri) => {
       const projectRoot = process.env.FABRIC_PROJECT_ROOT ?? process.cwd();
-      const path = join5(projectRoot, ".fabric", "bootstrap", "README.md");
+      const path = join4(projectRoot, ".fabric", "bootstrap", "README.md");
       let text = "";
-      if (existsSync4(path)) {
+      if (existsSync3(path)) {
         text = await readFile5(path, "utf8");
       }
       return {
@@ -2144,9 +2120,9 @@ function createShutdownHandler(deps) {
   };
 }
 async function startHttpServer(options) {
-  const { createFabricHttpApp } = await import("./http-3WADEK3O.js");
-  const { port, projectRoot, host = "127.0.0.1", authToken } = options;
-  const app = createFabricHttpApp({ projectRoot, host, authToken });
+  const { createFabricHttpApp } = await import("./http-TAI5X7U5.js");
+  const { port, projectRoot, host = "127.0.0.1", authToken, allowLoopbackNoAuth } = options;
+  const app = createFabricHttpApp({ projectRoot, host, authToken, allowLoopbackNoAuth });
   return await new Promise((resolveServer, rejectServer) => {
     const server = app.listen(port, host);
     server.once("close", () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fenglimg/fabric-server",
-  "version": "2.0.0-rc.27",
+  "version": "2.0.0-rc.29",
   "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.27"
+    "@fenglimg/fabric-shared": "2.0.0-rc.29"
   },
   "devDependencies": {
     "@types/express": "^5.0.6",