@fenglimg/fabric-cli 2.1.0-rc.2 → 2.2.0-rc.10

package/templates/hooks/knowledge-hint-broad.cjs

@@ -12,28 +12,20 @@
  * narrow-injection sibling (E2, knowledge-hint-narrow.cjs) handles
  * per-Edit/Write hints with a session-hints cache.
  *
- * Output contract (stderr only):
+ * Output contract (W2 / KT-DEC-0027/0028/0029 — the SessionStart spine):
  *
- *   When narrow count <= 30 (full per-type listing mode):
- *     [fabric] Session start — N broad-scoped knowledge entries available:
- *       [decision] (proven)
- *         - <id> · <summary>
- *       [pitfall] (verified)
- *         - <id> · <summary>
- *       ...
- *     revision_hash: <hash>
- *     Use `fab_get_knowledge_sections` to fetch full content.
+ *   AI sink (additionalContext) — the dynamically generated "MEMORY.md":
+ *     [fabric:SessionStart] <store>
+ *     ALWAYS-ACTIVE RULES (unconditional · act on the line): # guideline/model, BROAD only
+ *       [guideline] team:KT-GLD-0001 · <summary> # INDEX line; body on demand (KT-DEC-0036)
+ *     REFERENCE (situational · Read when must_read_if fires): # decision/pitfall/process, BROAD
+ *       [decision] team:KT-DEC-0001 — <must_read_if>
+ *       … N more folded (broad index > backstop 50; prune via fabric-audit)
+ *     Load full content: fab_recall(paths), or Read <store>/knowledge/<type>/<id>--*.md
  *
- *   When narrow count > 30 (grouped-truncation mode, per type):
- *     [fabric] Session start — N broad-scoped knowledge entries available (truncated):
- *       [decision] proven (3):
- *         - <id> · <summary>
- *         - ...
- *       [decision] verified (12): <id1>, <id2>, ...
- *       [decision] draft: 7 entries
- *       ...
- *     revision_hash: <hash>
- *     Use `fab_get_knowledge_sections` to fetch full content.
+ *   Human sink (systemMessage) — broad-only census breadcrumb; SessionStart is
+ *   SILENT about narrow-scoped knowledge (no on-demand counts, no
+ *   dropped-other-project line).
  *
  *   When 0 entries / CLI unavailable / CLI error / parse failure:
  *     (no output — silent exit 0)
@@ -50,12 +42,17 @@ const { spawnSync } = require("node:child_process");
 const { existsSync, readdirSync, readFileSync } = require("node:fs");
 const { join } = require("node:path");
 
+// W1-01 (ISS-012): the SessionStart broad hook appends a hook_surface_emitted
+// event to the shared events.jsonl. Under multi-window concurrency a bare
+// appendFileSync can interleave a partial write; route through the advisory-lock
+// primitive (drop-on-contention, best-effort — matches injection-log).
+const { appendLockedLine } = require("./lib/injection-log.cjs");
+
 // rc.16 TASK-003: shared banner-i18n lib (resolves fabric_language config and
 // renders localized banner text). Mirror of the wiring in fabric-hint.cjs
 // (TASK-002). Variant is resolved ONCE per main() invocation via
 // readFabricLanguage(cwd) and threaded into renderBanner — no fs in render path.
 const { renderBanner, readFabricLanguage } = require("./lib/banner-i18n.cjs");
-const { resolveOpaqueSummaries } = require("./lib/summary-fallback.cjs");
 // v2.0.0-rc.37 NEW-19: shared fabric-config reader + sidecar I/O. Replaces the
 // five per-key readFileSync+parse config readers (one parse per fire now) and
 // the bespoke last-emit sidecar helpers. The L78 "refactor into lib/ if a
@@ -63,11 +60,23 @@ const { resolveOpaqueSummaries } = require("./lib/summary-fallback.cjs");
 const {
   readConfigNumber,
   readConfigBoolean,
+  readConfigString,
 } = require("./lib/config-cache.cjs");
 const { readTextState, writeTextState } = require("./lib/state-store.cjs");
 // v2.0.0-rc.37 NEW-30: shared client detection (replaces the inline
 // CLAUDE_PROJECT_DIR single-bit check below).
-const { isClaudeCode } = require("./lib/client-adapter.cjs");
+// v2.2 dual-sink (Goal A): + emitDualSink (two-channel SessionStart emit).
+const { isClaudeCode, detectClient, emitDualSink } = require("./lib/client-adapter.cjs");
+// v2.2 dual-sink (Goal A / D4): human-output gate (nudge_mode + observe.*). Only
+// governs the human systemMessage — the AI additionalContext is emitted
+// regardless (flow ⊥ observation). Optional require so an old install lacking the
+// lib degrades to "always emit human" (the pre-dual-sink default).
+let nudgePolicy = null;
+try {
+  nudgePolicy = require("./lib/nudge-policy.cjs");
+} catch {
+  // Lib missing (old install) — human sink always emits (legacy behavior).
+}
 // v2.1.0-rc.1 P4 (F4/S63): hook-side reader for the CLI pre-generated
 // resolved-bindings snapshot. The hook NEVER re-resolves stores or walks store
 // trees — it only echoes the read-set the CLI already computed. Best-effort.
@@ -77,20 +86,72 @@ try {
 } catch {
   // Lib missing (old install) — store labels degrade to silent absence.
 }
+// v2.2 HK3-telemetry (W3-T1): injection-side per-inject logger. Optional require
+// so an old install lacking the lib degrades to silent absence (no telemetry,
+// hook still works).
+let injectionLog = null;
+try {
+  injectionLog = require("./lib/injection-log.cjs");
+} catch {
+  // Lib missing (old install) — injection telemetry degrades to silent absence.
+}
 
-// Read the project's own `project_id` from `.fabric/fabric-config.json` (the
-// snapshot key). Reading the PROJECT config is not a store-tree read — it is how
-// the hook learns which snapshot to fetch. Returns null on any failure.
-function readProjectId(cwd) {
+// Read the workspace binding id from `.fabric/fabric-config.json` (the snapshot
+// key). Defaults to project_id when workspace_binding_id is absent.
+function readWorkspaceBindingId(cwd) {
   try {
     const raw = readFileSync(join(cwd, ".fabric", "fabric-config.json"), "utf8");
     const parsed = JSON.parse(raw);
+    if (typeof parsed.workspace_binding_id === "string") return parsed.workspace_binding_id;
     return typeof parsed.project_id === "string" ? parsed.project_id : null;
   } catch {
     return null;
   }
 }
 
+function readSnapshotCanonicalCount(projectRoot) {
+  // No reader / not bound → degrade to an empty corpus (0), the documented
+  // store-only behavior (KT-DEC-0007). Only the "snapshot EXISTS but predates
+  // knowledge_store_dirs" case below is undeterminable → null (skip).
+  if (bindingsSnapshotReader === null) {
+    return 0;
+  }
+  const bindingId = readWorkspaceBindingId(projectRoot);
+  if (bindingId === null) {
+    return 0;
+  }
+  try {
+    const snapshot = bindingsSnapshotReader.readBindingsSnapshot(bindingId);
+    // No snapshot file at all → treat as an empty corpus (KT-DEC-0007),
+    // preserving the fresh-project underseed nudge.
+    if (!snapshot) {
+      return 0;
+    }
+    // LIVE recount off the snapshot's resolved store dirs. The cached
+    // knowledge_stats.canonical_count is frozen at snapshot-write time and goes
+    // stale when store content syncs in out-of-band (e.g. the store grew from 1
+    // → 57 nodes via a `git pull`/cross-workspace sync that never regenerated
+    // THIS workspace's snapshot), which mis-fired the "knowledge sparse"
+    // underseed nudge (KT-PIT-0017, same stale-projection root cause).
+    const live = bindingsSnapshotReader.liveKnowledgeStats(snapshot);
+    // #3: a snapshot that predates knowledge_store_dirs makes liveKnowledgeStats
+    // return null — the count is undeterminable and the cached projection is
+    // unreliable. Return null (not 0) so countCanonicalNodes / shouldRecommendImport
+    // SKIP the nudge instead of false-firing on stale data; the snapshot
+    // self-heals on the next install/sync. A genuine live 0 (dirs present, no
+    // *.md) still returns 0 and fires correctly.
+    if (live === null) {
+      return null;
+    }
+    return Number.isFinite(live.canonicalCount) ? Math.floor(live.canonicalCount) : 0;
+  } catch {
+    // Read/parse fault → degrade to empty (0), preserving prior behavior. The
+    // only undeterminable→skip path is the explicit live===null above.
+    return 0;
+  }
+}
+
+
 // -----------------------------------------------------------------------------
 // rc.12: SessionStart broad-menu is now unconditionally emitted on every
 // SessionStart fire (matching Skill-style progressive disclosure). Prior
@@ -108,7 +169,6 @@ const FABRIC_DIR_REL = ".fabric";
 // cannot `require` each other. If a third hook ever needs the same logic,
 // refactor into packages/cli/templates/hooks/lib/. Keep these values in sync
 // with packages/cli/templates/hooks/fabric-hint.cjs.
-const AGENTS_META_FILE = "agents.meta.json";
 const IMPORT_STATE_FILE = ".import-state.json";
 const KNOWLEDGE_CANONICAL_TYPES = [
   "decisions",
@@ -119,11 +179,12 @@ const KNOWLEDGE_CANONICAL_TYPES = [
 ];
 const DEFAULT_UNDERSEED_NODE_THRESHOLD = 10;
 
-// v2.0.0-rc.33 W2-1 (P0-9): TopK upper bound on broad-scoped entries surfaced
-// per SessionStart fire. Keeps the banner inside ~1 screenful so the agent
-// actually reads the top-priority entries instead of triaging a wall of text.
-// Overridable via fabric-config.json#hint_broad_top_k (range 1..50).
-const DEFAULT_HINT_BROAD_TOP_K = 8;
+// W2-1 (KT-DEC-0028): the broad index is shown in FULL (no top-K hard cap). The
+// only scale guard is a backstop: when the rendered broad index exceeds this
+// many lines, the overflow tail folds into one marker that doubles as a drift
+// signal (the W4 doctor `broad-index-drift` lint is the authoritative detector).
+// Overridable via fabric-config.json#broad_index_backstop (W4 schema range 20..500).
+const DEFAULT_HINT_BROAD_INDEX_BACKSTOP = 50;
 
 // v2.0.0-rc.33 W2-5 (P1-8): cooldown (in hours) between broad-hint re-emits.
 // Default 0 preserves rc.32 behavior — every SessionStart re-fires the banner.
@@ -153,37 +214,15 @@ const DEFAULT_HINT_REMINDER_TO_CONTEXT = true;
 // -----------------------------------------------------------------------------
 
 /**
- * Count canonical knowledge entries across the five canonical type subdirs
- * (decisions / pitfalls / guidelines / models / processes). Pending entries
- * are NOT counted — they are proposals, not seeded knowledge.
- *
- * Returns the integer count. ENOENT / unreadable subdir → silently treated as
- * zero (preserves never-block-on-failure invariant). Filters on `.md` suffix
- * only; the more-precise canonical filename pattern check is owned by
- * doctor.ts (the hook is a coarse signal, not a lint).
+ * Count canonical knowledge entries from the CLI-generated resolved-bindings
+ * snapshot. Store-only: hooks never walk project-local knowledge or store
+ * trees — a missing snapshot degrades to zero (KT-DEC-0007).
  */
 function countCanonicalNodes(projectRoot) {
-  const knowledgeRoot = join(projectRoot, FABRIC_DIR_REL, "knowledge");
-  if (!existsSync(knowledgeRoot)) {
-    return 0;
-  }
-  let count = 0;
-  for (const type of KNOWLEDGE_CANONICAL_TYPES) {
-    const typeDir = join(knowledgeRoot, type);
-    if (!existsSync(typeDir)) continue;
-    let entries;
-    try {
-      entries = readdirSync(typeDir);
-    } catch {
-      continue;
-    }
-    for (const entry of entries) {
-      if (entry.endsWith(".md")) {
-        count += 1;
-      }
-    }
-  }
-  return count;
+  // #3: null = undeterminable (old snapshot lacking store dirs, or no binding
+  // context). Propagate it — shouldRecommendImport SKIPS on null rather than
+  // treating it as zero and false-firing the underseed nudge on a stale corpus.
+  return readSnapshotCanonicalCount(projectRoot);
 }
 
 /**
@@ -200,14 +239,15 @@ function readUnderseedThreshold(projectRoot) {
 }
 
 /**
- * v2.0.0-rc.33 W2-1: resolve hint_broad_top_k from fabric-config.json. Slices
- * the broad entry list to TopK before group/truncation render. Validates the
- * schema's 1..50 range inline so a malformed config silently falls back.
+ * W2-1 (KT-DEC-0028): resolve broad_index_backstop from fabric-config.json. Caps
+ * the rendered broad index line count; the overflow tail folds into a drift
+ * marker. Validates the W4 schema's 20..500 range inline so a malformed config
+ * silently falls back to the default.
  */
-function readBroadTopK(projectRoot) {
-  return readConfigNumber(projectRoot, "hint_broad_top_k", DEFAULT_HINT_BROAD_TOP_K, {
-    min: 1,
-    max: 50,
+function readBroadIndexBackstop(projectRoot) {
+  return readConfigNumber(projectRoot, "broad_index_backstop", DEFAULT_HINT_BROAD_INDEX_BACKSTOP, {
+    min: 20,
+    max: 500,
     floor: true,
   });
 }
@@ -293,9 +333,11 @@ function isImportTouched(projectRoot) {
  * surface the one-line `/fabric-import` recommendation banner.
  *
  * Three-condition truth table (ALL must hold to return true):
- *   1. `.fabric/agents.meta.json` exists
- *      (workspace has been `fabric init`-ed; otherwise the recommendation
- *       is meaningless — `fabric-import` requires init's baseline scan).
+ *   1. the workspace is fabric-bound — readWorkspaceBindingId(cwd) !== null
+ *      (a resolved binding id in fabric-config.json; otherwise the
+ *       recommendation is meaningless — `fabric-import` requires a bound
+ *       workspace. Store-only: replaces the legacy derived-index-file
+ *       existence probe.)
  *   2. countCanonicalNodes(cwd) < readUnderseedThreshold(cwd)
  *      (knowledge graph is sparse — import would meaningfully enrich it).
  *   3. isImportTouched(cwd) === 'absent'
@@ -306,13 +348,26 @@ function isImportTouched(projectRoot) {
  *
  * Best-effort: any unexpected error → return false (do not nag on faults).
  */
-function shouldRecommendImport(projectRoot) {
+function shouldRecommendImport(projectRoot, liveTotal) {
   try {
-    const metaPath = join(projectRoot, FABRIC_DIR_REL, AGENTS_META_FILE);
-    if (!existsSync(metaPath)) return false;
+    if (readWorkspaceBindingId(projectRoot) === null) return false;
 
     const threshold = readUnderseedThreshold(projectRoot);
-    const nodeCount = countCanonicalNodes(projectRoot);
+    // P0 (Goal H3 / KT-PIT-0017 + KT-PIT-0019): prefer the LIVE census total the
+    // HUD displays as the single count source. The census walks the read-set
+    // fresh every fire (never a frozen snapshot projection), so feeding it here
+    // makes the import nudge and the HUD agree by construction — killing the
+    // "HUD shows 61 entries but the nudge claims the KB is sparse" contradiction
+    // the stale-snapshot count produced. Fall back to the snapshot-derived count
+    // only when no live total is supplied (e.g. direct unit-test calls).
+    const nodeCount =
+      typeof liveTotal === "number" && Number.isFinite(liveTotal)
+        ? liveTotal
+        : countCanonicalNodes(projectRoot);
+    // #3: undeterminable count (old snapshot predating knowledge_store_dirs) →
+    // skip. `null < threshold` coerces to true in JS, so an explicit guard is
+    // required — otherwise the stale-snapshot case would still false-fire.
+    if (nodeCount === null) return false;
     if (nodeCount >= threshold) return false;
 
     if (isImportTouched(projectRoot) !== "absent") return false;
@@ -338,6 +393,12 @@ function shouldRecommendImport(projectRoot) {
 // truncation summary lines) consume it as a single source of truth.
 const TRUNCATION_THRESHOLD = 12;
 
+// Goal H4 action ladder — review rung: surface a single `/fabric-review` line when
+// the LIVE pending backlog exceeds this. Mirrors fabric-hint.cjs's
+// DEFAULT_REVIEW_HINT_PENDING_COUNT (the Stop hook's review threshold) so the two
+// surfaces agree on "how much pending is too much". Strictly `> threshold`.
+const REVIEW_PENDING_THRESHOLD = 10;
+
 // `fabric plan-context-hint` is a thin wrapper over planContext(); on a
 // well-seeded repo it returns in ~100ms. Two-second cap is defensive — any
 // pathological hang must not stall session start.
@@ -499,7 +560,18 @@ function truncateSummary(raw, maxLen) {
 function formatEntryLine(entry, maxLen) {
   const id = entry.id || "(no-id)";
   const summary = truncateSummary(entry.summary, maxLen);
-  return summary.length > 0 ? `    - ${id} · ${summary}` : `    - ${id}`;
+  // lifecycle-refactor W3-T2 (§7 图谱消费 / §5 hook 沿 related 二阶召回): when this
+  // entry was pulled in by following a surfaced entry's `related` graph edge,
+  // tag the line with its provenance so the agent knows it arrived via the graph,
+  // not its own ranking. Omitted entirely for ordinarily-ranked entries — no fake
+  // "related" annotation is ever synthesized (graph-empty honesty).
+  const provenance =
+    typeof entry.related_to === "string" && entry.related_to.length > 0
+      ? ` (related-to-${entry.related_to})`
+      : "";
+  return summary.length > 0
+    ? `    - ${id} · ${summary}${provenance}`
+    : `    - ${id}${provenance}`;
 }
 
 /**
@@ -610,6 +682,8 @@ function renderSummary(payload, maxLen) {
     ? `[fabric] Session start — ${entries.length} broad-scoped knowledge entries available (truncated):`
     : `[fabric] Session start — ${entries.length} broad-scoped knowledge entries available:`;
 
+  // KT-DEC-0028 completeness: the rendered census is bounded by the per-line
+  // maxLen + TRUNCATION_THRESHOLD grouped mode, not by a body char budget.
   const body = truncated ? renderTruncated(entries, maxLen) : renderFull(entries, maxLen);
 
   const lines = [banner, ...body];
@@ -657,15 +731,423 @@ function renderSummary(payload, maxLen) {
     }
   }
 
-  lines.push("  Use `fab_get_knowledge_sections` to fetch full content.");
+  // W2-4 (KT-DEC-0026): single lean retrieval flow. The two-step
+  // fab_plan_context → fab_get_knowledge_sections footer is retired — fab_recall
+  // returns descriptions + read paths, and bodies load via a native Read.
+  lines.push(
+    "  Load full content: `fab_recall(paths)`, or Read `<store>/knowledge/<type>/<id>--*.md` directly.",
+  );
   return lines;
 }
 
+// -----------------------------------------------------------------------------
+// v2.2 dual-sink (Goal A): two-sink SessionStart rendering.
+//
+// HUMAN sink (systemMessage): a grouped census (§3 / D8) — always-loaded vs
+// on-demand split + [team]/[personal] + ✗ dropped-other-project. Count-summary
+// form (not a per-entry wall of text); the verbose nudge_mode appends the legacy
+// per-entry renderSummary listing on top.
+//
+// AI sink (additionalContext): the always-active (guideline/model) BODIES (§3 /
+// D9), bounded by the injection char budget with overflow degrading to summary +
+// a recall pointer, followed by on-demand category counts. Replaces the legacy
+// top_k=8 id-list that used to be the AI payload.
+// -----------------------------------------------------------------------------
+
+// Singular display label for a plural knowledge_type.
+const TYPE_SINGULAR = {
+  decisions: "decision",
+  pitfalls: "pitfall",
+  guidelines: "guideline",
+  models: "model",
+  processes: "process",
+};
+
+const ALWAYS_TYPES = ["guidelines", "models"];
+
+// Normalize a knowledge_type to its canonical PLURAL form. Frontmatter / entries
+// may carry the singular ("decision") while the census keys on the plural enum
+// ("decisions"); fold both so counting + display stay consistent.
+const TYPE_TO_PLURAL = {
+  decision: "decisions",
+  pitfall: "pitfalls",
+  guideline: "guidelines",
+  model: "models",
+  process: "processes",
+};
+function toPluralType(type) {
+  return TYPE_TO_PLURAL[type] || type;
+}
+
+// Fallback census when payload.census is absent (old CLI / unit-test payloads):
+// count the (possibly sliced) entries by knowledge_type so the human banner still
+// has something to group. Production payloads always carry the unsliced census.
+function deriveCensusFromEntries(entries) {
+  const census = {
+    by_type: {},
+    by_layer: { team: 0, personal: 0, project: 0 },
+    broad_by_type: {},
+    narrow_total: 0,
+    dropped_other_project: 0,
+    total: 0,
+  };
+  if (!Array.isArray(entries)) return census;
+  for (const e of entries) {
+    const type = e && typeof e.type === "string" ? toPluralType(e.type) : null;
+    if (type === null) continue;
+    const isNarrow = e.relevance_scope === "narrow";
+    census.by_type[type] = (census.by_type[type] || 0) + 1;
+    if (isNarrow) census.narrow_total += 1;
+    else census.broad_by_type[type] = (census.broad_by_type[type] || 0) + 1;
+    census.total += 1;
+  }
+  return census;
+}
+
+// Render the human-facing scope-primary status HUD (Goal H2). `lang` is
+// "zh-CN" | other (en). Returns an array of lines (empty when census is empty).
+//
+// Shape (KT-DEC-0029 — SessionStart is scope-primary; broad is the spine that's
+// injected this session, narrow surfaces contextually via the PreToolUse hint):
+//   ▸ [fabric] 共 N 条 · 团队X · 项目Y · 个人Z
+//     broad B · 本会话注入
+//       ├ 常驻规则 G+M  guideline G · model M     (KT-DEC-0027 resident tier)
+//       └ 情境参考 D+P+Pr  decision D · pitfall P · process Pr  (reference tier)
+//     narrow M · 编辑对应文件时浮现                (合计 only, no per-type)
+// Self-consistency invariant: broad (= 常驻 + 参考) + narrow == total.
+function renderHumanCensus(census, opts) {
+  const { lang } = opts || {};
+  const c = census || {};
+  const total = typeof c.total === "number" ? c.total : 0;
+  if (total === 0 && (c.dropped_other_project || 0) === 0) return [];
+  const zh = lang === "zh-CN";
+
+  const broadByType = c.broad_by_type || {};
+  const narrowTotal = typeof c.narrow_total === "number" ? c.narrow_total : 0;
+  // Per-tier broad counts. `broad_by_type` keys on the plural enum.
+  const g = broadByType.guidelines || 0;
+  const m = broadByType.models || 0;
+  const d = broadByType.decisions || 0;
+  const p = broadByType.pitfalls || 0;
+  const pr = broadByType.processes || 0;
+  const residentN = g + m; // 常驻规则 (always-active: guideline + model)
+  const referenceN = d + p + pr; // 情境参考 (decision + pitfall + process)
+  const broadN = residentN + referenceN;
+
+  const layer = c.by_layer || {};
+  const teamCount = layer.team || 0;
+  const personalCount = layer.personal || 0;
+  const projectCount = layer.project || 0;
+
+  const lines = [];
+  // Header: total entry count + semantic_scope breakdown (KT-MOD-0001 三轴).
+  const scopeSegs = [zh ? `团队 ${teamCount}` : `team ${teamCount}`];
+  if (projectCount > 0) scopeSegs.push(zh ? `项目 ${projectCount}` : `project ${projectCount}`);
+  scopeSegs.push(zh ? `个人 ${personalCount}` : `personal ${personalCount}`);
+  const totalLabel = zh ? `共 ${total} 条` : `${total} ${total === 1 ? "entry" : "entries"}`;
+  lines.push(`▸ [fabric] ${totalLabel} · ${scopeSegs.join(" · ")}`);
+
+  // broad spine — injected this session.
+  lines.push(zh ? `  broad ${broadN} · 本会话注入` : `  broad ${broadN} · injected this session`);
+  const residentDetail = [];
+  if (g > 0) residentDetail.push(`guideline ${g}`);
+  if (m > 0) residentDetail.push(`model ${m}`);
+  const refDetail = [];
+  if (d > 0) refDetail.push(`decision ${d}`);
+  if (p > 0) refDetail.push(`pitfall ${p}`);
+  if (pr > 0) refDetail.push(`process ${pr}`);
+  const dash = zh ? "—" : "—";
+  lines.push(
+    zh
+      ? `    ├ 常驻规则 ${residentN}  ${residentDetail.join(" · ") || dash}`
+      : `    ├ resident ${residentN}  ${residentDetail.join(" · ") || dash}`,
+  );
+  lines.push(
+    zh
+      ? `    └ 情境参考 ${referenceN}  ${refDetail.join(" · ") || dash}`
+      : `    └ reference ${referenceN}  ${refDetail.join(" · ") || dash}`,
+  );
+
+  // narrow remainder — 合计 only (no per-type; it's file-specific, surfaces on edit).
+  lines.push(
+    zh
+      ? `  narrow ${narrowTotal} · 编辑对应文件时浮现`
+      : `  narrow ${narrowTotal} · surfaces when you edit matching files`,
+  );
+  return lines;
+}
+
+// Goal H2: the SessionStart store label, scope-primary wording — `写入 X · 只读 Y`
+// (write target receives new knowledge; the rest are read-only sources). Replaces
+// the legacy `read-set stores: a (write), b (ro)` jargon line inline (kept local
+// to this hook so the shared lib formatStoreLabels — used by other hooks — is
+// untouched). Empty string when there is nothing to show.
+function renderScopeStoreLabel(snapshot, lang) {
+  if (!snapshot || !snapshot.read_set || !Array.isArray(snapshot.read_set.stores)) return "";
+  const stores = snapshot.read_set.stores;
+  if (stores.length === 0) return "";
+  const zh = lang === "zh-CN";
+  const writeAlias = snapshot.write_target && snapshot.write_target.alias;
+  const writeStores = [];
+  const readonlyStores = [];
+  for (const s of stores) {
+    const alias = s && typeof s.alias === "string" ? s.alias : null;
+    if (alias === null) continue;
+    if (alias === writeAlias) writeStores.push(alias);
+    else readonlyStores.push(alias);
+  }
+  const segs = [];
+  if (writeStores.length > 0) segs.push((zh ? "写入 " : "write ") + writeStores.join(", "));
+  if (readonlyStores.length > 0) segs.push((zh ? "只读 " : "readonly ") + readonlyStores.join(", "));
+  if (segs.length === 0) return "";
+  return "  " + segs.join(" · ");
+}
+
+// W2 (KT-DEC-0027/0028/0029): render the AI-facing sink — the dynamically
+// generated "MEMORY.md" spine injected into the SessionStart context. Two
+// type-tiered sections over the BROAD knowledge (narrow stays silent — D0029):
+//
+//   ALWAYS-ACTIVE RULES (guideline/model): INDEX LINE only (title + summary) —
+//     never the eager body (KT-DEC-0036). The body is one cheap on-demand fetch
+//     away, so injecting it on every SessionStart is a permanent context tax
+//     (KT-GLD-0005) we no longer pay; each entry stays individually visible.
+//   REFERENCE (decision/pitfall/process): TITLE + must_read_if hook only
+//     (situational; the agent Reads the body on demand) — never the body.
+//
+// `broadIndexBackstop` (D0028) caps the total rendered index lines; the overflow
+// tail folds into one marker that doubles as the drift signal (fabric-audit /
+// the W4 doctor lint is the authoritative detector). `entries` is the broad
+// plan-context-hint entry list ({id,type,maturity,summary,relevance_scope,
+// must_read_if}); `alwaysBodies` is always_bodies[] ({id,type,layer,summary,body}).
+const REFERENCE_TYPES = new Set(["decision", "pitfall", "process"]);
+
+function renderAiSink(opts) {
+  const { entries, alwaysBodies, storeLabel, broadIndexBackstop, summaryMaxLen, lang } =
+    opts || {};
+  const zh = lang === "zh-CN";
+  const bodies = Array.isArray(alwaysBodies) ? alwaysBodies : [];
+  // REFERENCE = broad decision/pitfall/process. narrow entries stay silent (D0029).
+  const referenceEntries = (Array.isArray(entries) ? entries : []).filter((e) => {
+    if (!e || e.relevance_scope === "narrow") return false;
+    return REFERENCE_TYPES.has(TYPE_SINGULAR[toPluralType(e.type)] || e.type);
+  });
+  // Nothing to inject → empty so main() stays silent on an empty knowledge base.
+  if (bodies.length === 0 && referenceEntries.length === 0) return "";
+
+  const backstop =
+    typeof broadIndexBackstop === "number" && broadIndexBackstop > 0 ? broadIndexBackstop : 0;
+  let indexCount = 0; // total rendered index lines (always + reference), for the backstop.
+
+  const lines = [];
+  lines.push(`[fabric:SessionStart] ${storeLabel || "store"}`);
+
+  // ALWAYS-ACTIVE RULES — index-only (title + summary), never the eager body.
+  lines.push(
+    zh
+      ? "ALWAYS-ACTIVE RULES (无条件适用 · 照此行遵循,正文按需取):"
+      : "ALWAYS-ACTIVE RULES (unconditional · act on the line; body on demand):",
+  );
+  if (bodies.length === 0) {
+    lines.push(zh ? "  (无 always-active 条目)" : "  (none)");
+  } else {
+    // KT-DEC-0036: render each always-active entry as a single index line
+    // (title + summary). The body is one cheap on-demand fetch away (see footer),
+    // so injecting it on every SessionStart is a permanent context tax
+    // (KT-GLD-0005) we no longer pay.
+    for (const b of bodies) {
+      const label = `[${TYPE_SINGULAR[b.type] || b.type}] ${b.id}`;
+      const summary = typeof b.summary === "string" ? b.summary.trim() : "";
+      lines.push(summary.length > 0 ? `  ${label} · ${summary}` : `  ${label}`);
+      indexCount += 1;
+    }
+  }
+
+  // REFERENCE — broad decision/pitfall/process: title + must_read_if hook.
+  if (referenceEntries.length > 0) {
+    lines.push(
+      zh
+        ? "REFERENCE (情境触发 · 命中 must_read_if 时 Read / fab_recall):"
+        : "REFERENCE (situational · Read when must_read_if fires / fab_recall):",
+    );
+    let folded = 0;
+    for (const e of referenceEntries) {
+      if (backstop > 0 && indexCount >= backstop) {
+        folded += 1;
+        continue;
+      }
+      const type = TYPE_SINGULAR[toPluralType(e.type)] || e.type;
+      const rawHook =
+        typeof e.must_read_if === "string" && e.must_read_if.length > 0
+          ? e.must_read_if
+          : typeof e.summary === "string"
+            ? e.summary
+            : "";
+      const hookText = truncateSummary(rawHook, summaryMaxLen);
+      lines.push(hookText.length > 0 ? `  [${type}] ${e.id} — ${hookText}` : `  [${type}] ${e.id}`);
+      indexCount += 1;
+    }
+    // D0028 backstop: fold the overflow tail into one marker + drift signal.
+    if (folded > 0) {
+      lines.push(
+        zh
+          ? `  … 另 ${folded} 条 broad 条目折叠 (broad index > backstop ${backstop})。先跑 fabric-audit 瘦身;确需全展示再调 .fabric/fabric-config.json#broad_index_backstop (20..500)`
+          : `  … ${folded} more broad entr${folded === 1 ? "y" : "ies"} folded (broad index > backstop ${backstop}). Run fabric-audit to prune first; raise .fabric/fabric-config.json#broad_index_backstop (20..500) only if you truly need them all`,
+      );
+    }
+  }
+
+  // W2-4 footer: single lean retrieval flow — no two-step.
+  lines.push(
+    zh
+      ? "取正文: fab_recall(paths), 或 Read <store>/knowledge/<type>/<id>--*.md"
+      : "Load full content: fab_recall(paths), or Read <store>/knowledge/<type>/<id>--*.md",
+  );
+  // H6 scope discipline: this sink carries ONLY broad (always-relevant) knowledge;
+  // narrow (file-specific) entries surface contextually via the PreToolUse hint
+  // when you edit a matching file (KT-DEC-0029). Stops the agent from assuming
+  // SessionStart is the whole KB.
+  lines.push(
+    zh
+      ? "范围: 此处仅 broad(始终相关);narrow(文件专属)在你编辑对应文件时由 PreToolUse 浮现"
+      : "Scope: broad only (always relevant) here; narrow (file-specific) surfaces via the PreToolUse hint when you edit a matching file",
+  );
+  return lines.join("\n");
+}
+
 // -----------------------------------------------------------------------------
 // Main entry — invoked both as a CLI (require.main === module) and in-process
 // by tests. Wraps the entire flow in try/catch: ANY error → silent exit 0.
 // -----------------------------------------------------------------------------
 
+// Block 5 (Option X): build the two SessionStart sinks (human systemMessage +
+// AI additionalContext) from a plan-context-hint payload, WITHOUT emitting or
+// recording telemetry. This is the single shared renderer: main() calls it then
+// emits + logs; `fabric context` calls it then prints (byte-identical injection
+// by construction — same code, same config/FS reads). Pure-ish: it reads config
+// + snapshot + .md summaries for `cwd` but has no stdout/ledger side effects.
+//
+// Returns:
+//   human               — gated final human text (null when gated off / empty)
+//   ai                  — gated final AI text (null when reminder-to-context off / empty)
+//   resolvedPayload     — the plan-context payload, passed through unchanged (for telemetry / --explain)
+//   hasRenderedContent  — true when ANY sink rendered content (main's silent-exit gate)
+//   reminderToContext   — readReminderToContext(cwd) (telemetry target-channel)
+function buildSessionStartSinks(cwd, payload, env) {
+  // KT-GLD-0006: the rc.35 opaque-summary runtime substitution
+  // (resolveOpaqueSummaries) is retired. The write-time mechanical floor in
+  // extractKnowledge (summary !== stable_id/slug + length floor) prevents
+  // degenerate summaries at the source, so SessionStart no longer band-aids them
+  // at render time; surviving legacy opaque summaries are fixed by the
+  // review-time cold-eval audit pass.
+  const resolvedPayload = payload;
+
+  const summaryMaxLen = readSummaryMaxLen(cwd);
+  const fabricLanguageForEmit = readFabricLanguage(cwd);
+
+  const census =
+    env && env.census !== undefined
+      ? env.census
+      : payload && payload.census
+        ? payload.census
+        : deriveCensusFromEntries(resolvedPayload && resolvedPayload.entries);
+  const alwaysBodies =
+    env && env.alwaysBodies !== undefined
+      ? env.alwaysBodies
+      : payload && Array.isArray(payload.always_bodies)
+        ? payload.always_bodies
+        : [];
+
+  // H3: the LIVE census total is the single count source for the import gate —
+  // computed AFTER census so the nudge and the HUD agree by construction.
+  const censusTotal = census && typeof census.total === "number" ? census.total : undefined;
+  const recommendImport = shouldRecommendImport(cwd, censusTotal);
+
+  // Read the resolved-bindings snapshot ONCE — reused for the scope store label
+  // (写入/只读) and the H4 review-rung pending count. Best-effort/decorative: any
+  // failure leaves snapshot null and the dependent lines simply don't render.
+  let snapshot = null;
+  if (bindingsSnapshotReader !== null) {
+    try {
+      const bindingId = readWorkspaceBindingId(cwd);
+      if (bindingId) snapshot = bindingsSnapshotReader.readBindingsSnapshot(bindingId);
+    } catch {
+      snapshot = null;
+    }
+  }
+
+  const humanGate =
+    nudgePolicy !== null
+      ? nudgePolicy.resolveHumanSink(cwd, "session_start", {})
+      : { emitHuman: true, verbosity: "normal" };
+
+  // ---- HUMAN sink: §3 grouped census (+ verbose per-entry detail). ----
+  const humanLines = renderHumanCensus(census, { lang: fabricLanguageForEmit });
+  if (humanLines.length > 0 && humanGate.verbosity === "verbose") {
+    const detail = renderSummary(resolvedPayload, summaryMaxLen);
+    humanLines.push(...detail);
+  }
+  // H2: scope store label — `写入 X · 只读 Y` (replaces the legacy read-set jargon).
+  if (humanLines.length > 0 && snapshot !== null) {
+    const storeLabel = renderScopeStoreLabel(snapshot, fabricLanguageForEmit);
+    if (storeLabel) humanLines.push(storeLabel);
+  }
+
+  // H4 action ladder (KT-DEC-0007: nudge, never a gate). AT MOST ONE line, the
+  // highest-priority rung wins, and steady state is fully silent:
+  //   1. import  — KB is sparse (recommendImport, off the live census total)
+  //   2. review  — pending backlog exceeds REVIEW_PENDING_THRESHOLD (live count)
+  //   3. (silent)
+  if (humanLines.length > 0 && fabricLanguageForEmit !== null) {
+    if (recommendImport) {
+      humanLines.push(renderBanner("broadImportBanner", fabricLanguageForEmit, {}));
+    } else if (snapshot !== null && bindingsSnapshotReader !== null) {
+      let pendingCount = 0;
+      try {
+        const live = bindingsSnapshotReader.liveKnowledgeStats(snapshot);
+        if (live && Number.isFinite(live.pendingCount)) pendingCount = Math.floor(live.pendingCount);
+      } catch {
+        pendingCount = 0;
+      }
+      if (pendingCount > REVIEW_PENDING_THRESHOLD) {
+        humanLines.push(
+          fabricLanguageForEmit === "zh-CN"
+            ? `  📋 Fabric: ${pendingCount} 条 pending 待审,是否调 /fabric-review?`
+            : `  📋 Fabric: ${pendingCount} pending entries — run /fabric-review?`,
+        );
+      }
+    }
+  }
+
+  // H5: the `下一步: …fab_recall…` AI-plumbing line is retired from the human sink
+  // (the AI gets it from its own footer + the MCP server directive). Keep only the
+  // pointer to the byte-identical inspector for this injection.
+  if (humanLines.length > 0) {
+    humanLines.push(
+      fabricLanguageForEmit === "zh-CN"
+        ? "  看具体注入: fabric context (--explain 看每条来源)"
+        : "  Inspect this injection: fabric context (--explain for per-entry provenance)",
+    );
+  }
+
+  // ---- AI sink: spine — always-active INDEX lines (no eager body, KT-DEC-0036)
+  // + reference, bounded by the broad_index_backstop fold. ----
+  const broadIndexBackstop = readBroadIndexBackstop(cwd);
+  const aiText = renderAiSink({
+    entries: resolvedPayload && Array.isArray(resolvedPayload.entries) ? resolvedPayload.entries : [],
+    alwaysBodies,
+    broadIndexBackstop,
+    summaryMaxLen,
+    lang: fabricLanguageForEmit,
+  });
+
+  const hasRenderedContent = humanLines.length > 0 || (typeof aiText === "string" && aiText.length > 0);
+  const human = humanGate.emitHuman && humanLines.length > 0 ? humanLines.join("\n") : null;
+  const reminderToContext = readReminderToContext(cwd);
+  const ai = reminderToContext && aiText && aiText.length > 0 ? aiText : null;
+
+  return { human, ai, resolvedPayload, hasRenderedContent, reminderToContext };
+}
+
 function main(env, stdio) {
   try {
     const cwd = (env && env.cwd) || process.cwd();
@@ -703,123 +1185,98 @@ function main(env, stdio) {
       env && env.payload !== undefined ? env.payload : invokePlanContextHint(cwd);
     if (payload === null || payload === undefined) return; // silent
 
-    // v2.0.0-rc.33 W2-1 (P0-9): apply TopK slice BEFORE renderSummary so the
-    // grouped/truncation rendering operates on the bounded set. Slicing here
-    // (not inside renderSummary) keeps the formatter pure — it never has to
-    // know about the cap.
-    const topK = readBroadTopK(cwd);
-    const slicedPayload =
-      payload && Array.isArray(payload.entries) && payload.entries.length > topK
-        ? { ...payload, entries: payload.entries.slice(0, topK) }
-        : payload;
-
-    // rc.35 TASK-06 (P0-10.b): summary-fallback substitution. Entries whose
-    // description.summary equals stable_id render as "<id> · <id>" and the
-    // AI skips fetching them; the fallback reads `## Summary` from the
-    // entry's .md file and swaps in the first paragraph. Best-effort —
-    // failure leaves the original opaque summary untouched.
-    let resolvedPayload = slicedPayload;
-    try {
-      if (slicedPayload && Array.isArray(slicedPayload.entries)) {
-        const resolvedEntries = resolveOpaqueSummaries(
-          slicedPayload.entries,
-          cwd,
-          typeof slicedPayload.revision_hash === "string" ? slicedPayload.revision_hash : "",
-        );
-        resolvedPayload = { ...slicedPayload, entries: resolvedEntries };
-      }
-    } catch {
-      // resolveOpaqueSummaries swallows its own errors; this catch is belt
-      // + suspenders for any unexpected exception from the lib layer.
+    // W2-1 (KT-DEC-0028): broad 全显示 — the legacy hint_broad_top_k hard cap is
+    // retired. SessionStart must SEE every broad entry; scale is bounded by the
+    // per-line char cap + broad_index_backstop fold, not by dropping entries.
+
+    // Block 5 (Option X): build both sinks via the shared renderer (same code
+    // `fabric context` uses → byte-identical injection). Side-effect-free; the
+    // emit + telemetry below stay in main().
+    const { human, ai, resolvedPayload, hasRenderedContent, reminderToContext } =
+      buildSessionStartSinks(cwd, payload, env);
+
+    // Nothing to say at all → silent exit (preserves the empty-payload contract).
+    if (!hasRenderedContent) return;
+
+    // v2.2 dual-sink (Goal A / D7): emit both channels in one render. The human
+    // systemMessage is gated by nudge_mode (emitHuman); the AI additionalContext
+    // is emitted regardless. emitDualSink shapes the protocol per client (CC/Codex
+    // camelCase nested envelope; unknown → stderr).
+    if (!(env && env.skipStdout === true)) {
+      emitDualSink(
+        { human, ai },
+        { client: detectClient(), eventName: "SessionStart", streams: { stdout: out, stderr: err } },
+      );
+    } else if (human !== null) {
+      // skipStdout test seam: still surface the human breadcrumb to stderr.
+      err.write(`${human}\n`);
     }
 
-    // rc.8 underseed self-check: decide whether to surface the one-line
-    // `/fabric-import` recommendation banner alongside the broad summary.
-    const recommendImport = shouldRecommendImport(cwd);
-
-    // rc.12: broad-summary body is unconditionally rendered on every
-    // SessionStart fire (Skill-style progressive disclosure). The prior
-    // revision_hash cooldown gate (rc.7 T8 — rc.11) was removed because
-    // compact/clear-triggered SessionStart re-fires must re-inject the menu
-    // for the agent's working memory. rc.33 W2-5 reintroduces an opt-in
-    // hours-based cooldown via fabric-config (see gate above).
-    const summaryMaxLen = readSummaryMaxLen(cwd);
-    const lines = renderSummary(resolvedPayload, summaryMaxLen);
-
-    // v2.0.0-rc.37 NEW-23: resolve fabric_language ONCE per emit path —
-    // shared between the (existing) broadImportBanner branch and the new
-    // 'next step' nudge tail added below. 'match-existing' / unknown variants
-    // fold to 'en' inside renderBanner per UX i18n Policy class 1.
-    const fabricLanguageForEmit = lines.length > 0 || recommendImport ? readFabricLanguage(cwd) : null;
-    if (recommendImport && fabricLanguageForEmit !== null) {
-      lines.push(renderBanner("broadImportBanner", fabricLanguageForEmit, {}));
+    // v2.2 HK3-telemetry (W3-T1): record the injection side. We just OFFERED the
+    // agent `resolvedPayload.entries` (the top_k-sliced broad menu); log their
+    // ids so the true hit rate (consumed ÷ injected) is computable against the
+    // consumption-side metrics.jsonl. Best-effort — never affects the emit.
+    if (injectionLog !== null) {
+      const injectedEntries = Array.isArray(resolvedPayload && resolvedPayload.entries)
+        ? resolvedPayload.entries
+        : [];
+      injectionLog.logInjection(cwd, {
+        surface: "broad",
+        stableIds: injectedEntries.map((e) => (e && e.id) || "").filter(Boolean),
+        count: injectedEntries.length,
+        revisionHash:
+          resolvedPayload && typeof resolvedPayload.revision_hash === "string"
+            ? resolvedPayload.revision_hash
+            : null,
+        ts: nowMs,
+      });
     }
 
-    if (lines.length === 0) return; // nothing to say — silent exit
-
-    // v2.1.0-rc.1 P4 (F4/S63): append a per-store read-set label from the
-    // CLI-pre-generated bindings snapshot so the session opens aware of which
-    // stores it reads and where writes land. Best-effort, never blocks: a
-    // missing snapshot / single-store setup just omits the line.
-    if (bindingsSnapshotReader !== null) {
-      try {
-        const projectId = readProjectId(cwd);
-        if (projectId) {
-          const label = bindingsSnapshotReader.formatStoreLabels(
-            bindingsSnapshotReader.readBindingsSnapshot(projectId),
-          );
-          if (label) lines.push(label);
+    // v2.2 dual-sink (Goal A): the legacy rc.33 W2-6 stdout JSON envelope is
+    // replaced by emitDualSink above (which carries BOTH the human systemMessage
+    // and the AI additionalContext, shaped per client). hint_reminder_to_context
+    // still gates whether the AI sink is populated (see `ai` above).
+
+    // v2.1 NEW-N-3 (ADJ-NEWN-3): hook_surface_emitted instrumentation. One
+    // best-effort ledger row recording WHICH broad-scoped ids were surfaced
+    // into the session — the join key for measuring hook→behavior delta (did
+    // the agent fab_recall what the hook surfaced?). SessionStart fires once
+    // per session boot so this never bloats the ledger. Never blocks the hook
+    // (KT-DEC-0007): any failure (no .fabric/, undetected client, write error)
+    // degrades to silent skip. Client is omitted-by-skip when undetectable
+    // because the schema's `client` enum admits only cc/codex.
+    try {
+      const surfaceClient = detectClient();
+      const fabricDir = join(cwd, FABRIC_DIR_REL);
+      if (surfaceClient !== undefined && existsSync(fabricDir)) {
+        const renderedIds =
+          resolvedPayload && Array.isArray(resolvedPayload.entries)
+            ? resolvedPayload.entries
+                .map((e) => (e && typeof e.id === "string" ? e.id : null))
+                .filter((x) => x !== null)
+            : [];
+        let idSuffix;
+        try {
+          idSuffix = require("node:crypto").randomUUID();
+        } catch {
+          idSuffix = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
         }
-      } catch {
-        // store labels are decorative provenance — never crash the hook
-      }
-    }
-
-    // v2.0.0-rc.37 NEW-23: SessionStart 索引末尾"下一步"引导。Tail line that
-    // tells the AI what to do with the broad index it just received. Without
-    // this, the model often parses the index and moves on without ever calling
-    // fab_recall / fab_plan_context. One-line nudge, bilingual.
-    const nextStepNudge =
-      fabricLanguageForEmit === "zh-CN"
-        ? "下一步: 调 fab_recall(paths) 拿 KB 相关条目;或调 fab_plan_context 先看候选 description_index。"
-        : "Next: call fab_recall(paths) to fetch related KB entries, or fab_plan_context to preview the description_index first.";
-    lines.push(nextStepNudge);
-
-    // Stderr: always emit (human-facing breadcrumb + legacy contract).
-    for (const line of lines) {
-      err.write(`${line}\n`);
-    }
-
-    // v2.0.0-rc.33 W2-6 (P0-7): stdout JSON envelope. When
-    // hint_reminder_to_context is true (default), serialize the same banner
-    // body as Claude Code's SessionStart hookSpecificOutput shape so the model
-    // receives the reminder IN-CONTEXT (rc.32 baseline cite-coverage 3.1%
-    // root cause: reminders never entered model context). Stderr stays the
-    // host-facing channel.
-    //
-    // Failure to write JSON envelope must NOT crash the hook — stderr already
-    // delivered, the stdout layer is best-effort.
-    // v2.0.0-rc.33 W4 review-fix (gemini High-1): the stdout JSON envelope
-    // is Claude Code-specific (hookSpecificOutput.additionalContext contract).
-    // Codex CLI / Cursor don't parse it — leaking it to their stdout risks
-    // either polluting the terminal or crashing the host's hook-parsing
-    // pipeline. CLAUDE_PROJECT_DIR is set by CC when invoking hooks (see
-    // packages/cli/templates/hooks/configs/claude-code.json sigil paths);
-    // its presence is the single-bit "this is Claude Code" signal (now via
-    // the shared client-adapter, rc.37 NEW-30).
-    const reminderToContext = readReminderToContext(cwd) && isClaudeCode();
-    if (reminderToContext && !(env && env.skipStdout === true)) {
-      try {
-        const envelope = {
-          hookSpecificOutput: {
-            hookEventName: "SessionStart",
-            additionalContext: lines.join("\n"),
-          },
+        const surfaceEvent = {
+          kind: "fabric-event",
+          id: `event:${idSuffix}`,
+          ts: Date.now(),
+          schema_version: 1,
+          event_type: "hook_surface_emitted",
+          hook_name: "knowledge-hint-broad",
+          client: surfaceClient,
+          target_channel: reminderToContext ? "stdout-additionalContext" : "stderr",
+          rendered_ids: renderedIds,
+          delivery_status: "delivered",
         };
-        out.write(`${JSON.stringify(envelope)}\n`);
-      } catch {
-        // Best-effort — stderr is the durable contract
+        appendLockedLine(join(fabricDir, "events.jsonl"), JSON.stringify(surfaceEvent) + "\n");
       }
+    } catch {
+      // best-effort telemetry — never block session start
     }
 
     // v2.0.0-rc.33 W2-5 (P1-8): record successful emit timestamp for the
@@ -836,6 +1293,7 @@ function main(env, stdio) {
 
 module.exports = {
   main,
+  buildSessionStartSinks,
   invokePlanContextHint,
   groupEntries,
   renderFull,
@@ -847,8 +1305,8 @@ module.exports = {
   readUnderseedThreshold,
   isImportTouched,
   shouldRecommendImport,
-  // v2.0.0-rc.33 W2-1 / W2-5 / W2-6 helpers.
-  readBroadTopK,
+  // W2-1 (KT-DEC-0028) + rc.33 W2-5 / W2-6 helpers.
+  readBroadIndexBackstop,
   readBroadCooldownHours,
   readReminderToContext,
   readBroadLastEmit,
@@ -865,7 +1323,7 @@ module.exports = {
     MATURITY_DRAFT,
     DEFAULT_UNDERSEED_NODE_THRESHOLD,
     KNOWLEDGE_CANONICAL_TYPES,
-    DEFAULT_HINT_BROAD_TOP_K,
+    DEFAULT_HINT_BROAD_INDEX_BACKSTOP,
     DEFAULT_HINT_BROAD_COOLDOWN_HOURS,
     DEFAULT_HINT_REMINDER_TO_CONTEXT,
     HINT_BROAD_LAST_EMIT_FILE_NAME,