@fenglimg/fabric-cli 2.0.0 → 2.1.0-rc.2

package/templates/hooks/fabric-hint.cjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-const { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } = require("node:fs");
+const { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } = require("node:fs");
 const { dirname, join } = require("node:path");
 
 // v2.0.0-rc.7 T5: session-digest writer. Best-effort (never blocks Stop hook
@@ -13,15 +13,119 @@ try {
   sessionDigestWriter = null;
 }
 
+// v2.0.0-rc.16 TASK-002 (F2-apply): banner-i18n lib for the 5 Signal
+// banners (A/B/C/D-never/D-aged). Resolved ONCE per main() invocation and
+// threaded into decide() / evaluateMaintenanceSignal() via the existing
+// thresholds object. Lib is required at module load; failure to load is
+// fatal-here-but-silent: the require itself can't throw without the .cjs
+// being missing entirely (a packaging bug we'd want to surface during
+// install integration tests, not silently swallow).
+const { renderBanner, readFabricLanguage } = require("./lib/banner-i18n.cjs");
+
+// v2.0.0-rc.24 TASK-04: shared cite-line parser (CJS twin of
+// packages/shared/src/cite-line-parser.ts, byte-shipped via installHookLibs).
+// Provides `parseCiteLine(raw)` → { cite_ids, cite_tags, cite_commitments }.
+// Hook runtime has no node_modules access; the twin is hand-synced and
+// behavior-parity-tested against the TS source.
+let citeLineParser = null;
+try {
+  citeLineParser = require("./lib/cite-line-parser.cjs");
+} catch {
+  // Helper module missing — degrade silently. parseKbLine falls back to a
+  // legacy in-file regex when the lib is unavailable (e.g. mid-upgrade where
+  // hook script lands before lib is copied). New cite_commitments output is
+  // empty in degraded mode.
+  citeLineParser = null;
+}
+
+// v2.0.0-rc.24 TASK-05: L1 enforcement layer — soft Stop hook reminder for
+// [recalled] cites of decision/pitfall types that arrived without operator
+// contract or skip:<reason>. Reads .fabric/agents.meta.json (via
+// lib/cite-contract-reminder.cjs#readKnowledgeTypeMap) to type-route cite
+// ids per B6 lock; emits one
+//   ⚠ KB: <id> cited as [recalled] but missing contract; add → edit:<glob>
+//     or → skip:<reason> next turn
+// line to stderr per offending id. Non-blocking, never throws.
+let citeContractReminder = null;
+try {
+  citeContractReminder = require("./lib/cite-contract-reminder.cjs");
+} catch {
+  // Helper module missing — soft reminder simply doesn't fire. Audit-side
+  // doctor (TASK-08) still catches contract violations at the next run.
+  citeContractReminder = null;
+}
+
+// v2.0.0-rc.37 NEW-30: shared client-protocol adapter. Guarded require (this
+// hook runs in arbitrary user repos); detectClient delegates the 3-tier
+// detection to the lib, falling back to env-only when the lib is absent.
+let clientAdapter = null;
+try {
+  clientAdapter = require("./lib/client-adapter.cjs");
+} catch {
+  clientAdapter = null;
+}
+
+// v2.0.0-rc.37 NEW-16: shared config + sidecar I/O for the per-signal dismiss
+// feature (config-level durable opt-out + session-scoped sidecar). Guarded
+// require (house style); dismiss simply doesn't fire if the lib is absent.
+let configCache = null;
+let stateStore = null;
+try {
+  configCache = require("./lib/config-cache.cjs");
+} catch {
+  configCache = null;
+}
+try {
+  stateStore = require("./lib/state-store.cjs");
+} catch {
+  stateStore = null;
+}
+
+// v2.1.0-rc.1 P4 (F4/S63): hook-side reader for the CLI pre-generated
+// resolved-bindings snapshot. The Stop hint surfaces the read-set stores
+// (per-store, NOT aggregated into one pile) without re-resolving / walking
+// store trees. Best-effort — a missing lib/snapshot omits the store line.
+let bindingsSnapshotReader = null;
+try {
+  bindingsSnapshotReader = require("./lib/bindings-snapshot-reader.cjs");
+} catch {
+  bindingsSnapshotReader = null;
+}
+
+// Read the project's own `project_id` (the snapshot key) from its config.
+function readProjectId(cwd) {
+  try {
+    const parsed = JSON.parse(readFileSync(join(cwd, ".fabric", "fabric-config.json"), "utf8"));
+    return typeof parsed.project_id === "string" ? parsed.project_id : null;
+  } catch {
+    return null;
+  }
+}
+
 // CONSTANTS — duplicated from packages/server/src/services/_shared.ts.
 // DRY violation accepted: this hook script runs in user repos WITHOUT
 // node_modules access, so it cannot import from @fenglimg/fabric-server.
 const FABRIC_DIR = ".fabric";
 const EVENT_LEDGER_FILE = "events.jsonl";
+// v2.0.0-rc.39 (P1 emit-fold): high-frequency empty-shell assistant_turn_observed
+// turns (kb_line_raw=null AND no cite_ids AND no cite_commitments) carry zero
+// cite-audit signal, so emitting one events.jsonl line each is pure bloat. They
+// are folded at the emit source into a single per-Stop metrics.jsonl counter row
+// `{ counters: { assistant_turn_observed[:<client>]: N } }`. The cite-coverage /
+// emit-cadence readers add this counter back into total_turns so the metric is
+// byte-for-byte invariant (the fold preserves count semantics, incl. the legacy
+// per-Stop re-emission, exactly). Mirrors packages/server/src/services/metrics.ts
+// row shape; written directly (the .cjs hook cannot import the TS service).
+const METRICS_LEDGER_FILE = "metrics.jsonl";
 const EVENT_TYPE_PROPOSED = "knowledge_proposed";
 const EVENT_TYPE_INIT_SCAN_COMPLETED = "init_scan_completed";
 // v2.0.0-rc.7 T10: doctor_run event drives Signal D (maintenance hint).
 const EVENT_TYPE_DOCTOR_RUN = "doctor_run";
+// v2.0.0-rc.20 TASK-03: per-turn cite-policy observation event. Emitted by
+// extractAndWriteAssistantTurnsBestEffort() after the Stop hook parses each
+// assistant envelope's first non-empty line for a `KB:` prefix. Schema
+// registered in packages/shared/src/schemas/event-ledger.ts (rc.20 TASK-02).
+const EVENT_TYPE_ASSISTANT_TURN_OBSERVED = "assistant_turn_observed";
 // rc.6 TASK-022 (E5): Signal A is now `24h OR N-edits since last
 // knowledge_proposed`. The edit-count branch reads
 // `.fabric/.cache/edit-counter` (one ISO-8601 line per PreToolUse fire,
@@ -98,14 +202,20 @@ const MAINTENANCE_HINT_LAST_EMIT_FILE = ".fabric/.cache/maintenance-hint-last-em
 // there's barely anything TO lint.
 const MAINTENANCE_HINT_MIN_CANONICAL = 5;
 
-// rc.7 T1: cross-surface sentinel from `fabric init` Y-confirm. Empty file
-// at `.fabric/.import-requested`. Stop hook reads it to bypass the Signal C
-// cooldown and emit the import recommendation regardless of underseed or
-// 24h-since-last-emit gates. SessionStart hook (knowledge-hint-broad.cjs)
-// has its own mirror of this pickup logic. The fabric-import Skill's
-// Phase 3.4 clears the sentinel; until then it remains and continues to
-// surface the recommendation.
-const IMPORT_REQUESTED_SENTINEL_FILE = join(".fabric", ".import-requested");
+// v2.0.0-rc.8 (TASK-002): in-flight import gate for Signal B.
+// fabric-import skill writes `.fabric/.import-state.json` checkpoints after
+// every successful sub-step (P1/P2/P3 — see fabric-import/SKILL.md). The
+// Stop hook reads this file as a soft signal to know that an import is
+// mid-run, so we can silence Signal B (review hint at pending count >= 10)
+// to avoid interrupting the import while it accumulates pending entries.
+//
+// Gate is intentionally narrow: ONLY Signal B is suppressed. Signals A
+// (archive), C (import recommendation), D (maintenance) retain their
+// pre-existing behaviour byte-for-byte. The 24h TTL on `last_checkpoint_at`
+// guards against stale state files that would otherwise permanently
+// silence Signal B if a user abandoned an import without completing.
+const IMPORT_STATE_FILE_REL = join(".fabric", ".import-state.json");
+const IMPORT_IN_FLIGHT_MAX_AGE_HOURS = 24;
 
 /**
  * Read the events.jsonl ledger from <projectRoot>/.fabric/events.jsonl.
@@ -296,35 +406,62 @@ function countEditsSince(projectRoot, anchorTs) {
 }
 
 /**
- * rc.7 T1: detect the `.fabric/.import-requested` sentinel. Best-effort
- * presence check — returns false on any I/O error so a hostile filesystem
- * never blocks the Stop hook on this branch.
+ * v2.0.0-rc.8 (TASK-002): detect whether a fabric-import skill run is
+ * currently in flight, used to gate Signal B (review hint) so the Stop
+ * hook does not interrupt an active import when its pending pile crosses
+ * the review threshold.
+ *
+ * Truth table — returns false (i.e. NOT in flight, do not gate) on:
+ *   - `.fabric/.import-state.json` missing (no import has ever started or
+ *     state file was deleted)
+ *   - JSON.parse failure (malformed state file — never-block invariant
+ *     forbids permanently silencing Signal B due to corruption)
+ *   - `phase === "complete"` (import finished — see fabric-import SKILL.md
+ *     Phase 3.4)
+ *   - `last_checkpoint_at` missing OR older than IMPORT_IN_FLIGHT_MAX_AGE_HOURS
+ *     (stale state — user likely abandoned the import; do not let a forever
+ *     orphaned state file silence Signal B forever)
+ *   - any unexpected throw (defensive — never-block invariant)
+ *
+ * Returns true ONLY when state file exists, parses, has a non-"complete"
+ * phase, and a fresh `last_checkpoint_at` (< 24h ago). Field names
+ * (`phase`, `last_checkpoint_at`) verified against fabric-import SKILL.md
+ * § Checkpoint Logic.
+ *
+ * `now` is optional — defaults to `new Date()`. Tests can inject a fixed
+ * Date for determinism; production callers may omit it.
  */
-function isImportRequestedSentinelPresent(projectRoot) {
+function isImportInFlight(projectRoot, now) {
   try {
-    return existsSync(join(projectRoot, IMPORT_REQUESTED_SENTINEL_FILE));
+    const p = join(projectRoot, IMPORT_STATE_FILE_REL);
+    if (!existsSync(p)) return false;
+    let raw;
+    try {
+      raw = readFileSync(p, "utf8");
+    } catch {
+      return false;
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      return false;
+    }
+    if (parsed === null || typeof parsed !== "object") return false;
+    if (parsed.phase === "complete") return false;
+    const ts = parsed.last_checkpoint_at;
+    if (typeof ts !== "string" || ts.length === 0) return false;
+    const ms = Date.parse(ts);
+    if (!Number.isFinite(ms)) return false;
+    const nowMs = now instanceof Date ? now.getTime() : Number(now) || Date.now();
+    const ageHours = (nowMs - ms) / MS_PER_HOUR;
+    if (ageHours > IMPORT_IN_FLIGHT_MAX_AGE_HOURS) return false;
+    return true;
   } catch {
     return false;
   }
 }
 
-/**
- * rc.7 T1: build the import-recommendation result that the Stop hook emits
- * when the sentinel is present. Reuses the existing Signal C shape so
- * downstream consumers (Cursor `followup_message`, etc.) need no schema
- * change. The reason text reuses the rc.7 T4 人-first banner style.
- */
-function makeImportSentinelResult() {
-  const line1 =
-    "📋 Fabric: 检测到 fabric init 提示要回灌知识 — 是否调 /fabric-import 从 git 历史和现有文档抽取?";
-  return {
-    decision: "block",
-    reason: line1,
-    signal: "import",
-    recommended_skill: "fabric-import",
-  };
-}
-
 /**
  * rc.7 T4: read the edit-counter sidecar and return the top-N most-edited
  * directories (grouped by the leading 2 path segments) since `anchorTs`.
@@ -397,14 +534,49 @@ function getTopEditedDirectories(projectRoot, topN, anchorTs) {
       // any leading "./". POSIX-style only — the hook ships under POSIX
       // path conventions even on Windows (the project doesn't currently
       // ship a CRLF/backslash test matrix for the sidecar).
-      const norm = p.replace(/\\/g, "/").replace(/^\.\//, "");
+      //
+      // v2.0.0-rc.27 TASK-005 (audit §2.8 leak surface): absolute paths
+      // already accumulated in legacy sidecars start with `/`. We strip
+      // the leading slash and also reject buckets that resolve to user-home
+      // segments (`Users/<name>/...`, `home/<name>/...`) so historical
+      // pollution from absolute-path writes doesn't surface the user's
+      // $HOME in the archive banner. The rc.27 appendEditCounter no longer
+      // writes such paths, but the sidecar is append-only so old lines
+      // persist until rotation.
+      let norm = p.replace(/\\/g, "/").replace(/^\.\//, "");
+      // Strip leading `/` so a stale absolute entry doesn't generate a leak.
+      while (norm.startsWith("/")) norm = norm.slice(1);
       const segs = norm.split("/").filter((s) => s.length > 0);
+      // Reject any bucket whose top segments look like a host-system home
+      // prefix. The pattern is `<top>/<user>/...` where top ∈ Users|home|root.
+      // This silently drops legacy absolute-path entries from $HOME without
+      // mangling the buckets for legitimate project-relative `Users/...`
+      // (unlikely but possible) — the heuristic favours $HOME leak prevention
+      // over false-positive bucketing of project paths named after Unix
+      // conventions.
+      if (segs.length >= 2 && (segs[0] === "Users" || segs[0] === "home" || segs[0] === "root")) {
+        continue;
+      }
+      // v2.0.0-rc.27 TASK-005 (audit §2.8 file-as-dir): when segs[1] looks
+      // like a file (contains a dot-extension at the end), surface segs[0]
+      // alone instead of `segs[0]/segs[1]/` — a 2-seg path of the form
+      // `assets/foo.ts` would otherwise render as "assets/foo.ts/" which
+      // misleads the operator about whether they're seeing a file or a
+      // directory. The extension regex is permissive: any `.X` where X is
+      // 1-8 alphanumerics counts. README.md / package.json / foo.ts all
+      // match; "v1.2" or "dotted.module" do too — acceptable false-positive
+      // rate, since the worst outcome is over-aggregation to the parent.
+      const looksLikeFile = (segment) => /\.[A-Za-z0-9]{1,8}$/u.test(segment);
       let bucket;
       if (segs.length >= 2) {
-        // Leading 2 segments: "packages/cli", "docs/decisions", etc. We
-        // trail with "/" so the banner reads "packages/cli/" — clearly a
-        // directory rather than a file basename.
-        bucket = `${segs[0]}/${segs[1]}/`;
+        if (looksLikeFile(segs[1])) {
+          bucket = `${segs[0]}/`;
+        } else {
+          // Leading 2 segments: "packages/cli", "docs/decisions", etc. We
+          // trail with "/" so the banner reads "packages/cli/" — clearly a
+          // directory rather than a file basename.
+          bucket = `${segs[0]}/${segs[1]}/`;
+        }
       } else if (segs.length === 1) {
         // Single segment — treat the basename as its own bucket. Bare
         // root-level files (README.md, package.json) get some signal too.
@@ -500,7 +672,7 @@ function readArchiveEditThreshold(projectRoot) {
 // without touching the filesystem. Omitting the arg falls back to documented
 // defaults so existing in-process callers (tests that pre-date T7) still
 // pass without modification — they implicitly exercise the default path.
-function decide(events, now, pendingStats, underseedStats, editCounterStats, thresholds, banner) {
+function decide(events, now, pendingStats, underseedStats, editCounterStats, thresholds, banner, importInFlight) {
   const nowMs = now instanceof Date ? now.getTime() : Number(now) || Date.now();
   const stats = pendingStats || { count: 0, oldestAgeMs: null };
   const underseed =
@@ -523,6 +695,10 @@ function decide(events, now, pendingStats, underseedStats, editCounterStats, thr
     typeof cfg.reviewHintPendingAgeDays === "number" && cfg.reviewHintPendingAgeDays > 0
       ? cfg.reviewHintPendingAgeDays
       : DEFAULT_REVIEW_HINT_PENDING_AGE_DAYS;
+  // rc.16 TASK-002: banner variant for the i18n lib. Defaults to 'zh-CN' so
+  // existing test callers (which never pass thresholds.variant) get the rc.15
+  // byte-identical Chinese output. main() always supplies the resolved variant.
+  const variant = typeof cfg.variant === "string" ? cfg.variant : "zh-CN";
 
   // ---- Archive signal (rc.6 TASK-022 — Signal A, 24h-OR-N-edits) -----------
   // Locate the most-recent knowledge_proposed event. If none exists, Signal A
@@ -569,23 +745,38 @@ function decide(events, now, pendingStats, underseedStats, editCounterStats, thr
     //   - "<editCount> 次编辑"
     //   - "阈值 <N>"
     //   - "fabric-archive"
+    // v2.0.0-rc.27 TASK-005 (audit §2.17): parts now assembled per-variant
+    // via banner-i18n's archivePartsHours / archivePartsEdits so en mode
+    // gets fully-English fragments instead of mixed-language output. zh-CN
+    // / zh-CN-hybrid still render the original substring contract verbatim.
     const parts = [];
     if (triggerByHours) {
-      parts.push(`已过 ${hoursElapsed.toFixed(1)}h（阈值 ${archiveHintHours}h）`);
+      parts.push(
+        renderBanner("archivePartsHours", variant, {
+          hoursFixed: hoursElapsed.toFixed(1),
+          threshold: archiveHintHours,
+        }),
+      );
     }
     if (triggerByEdits) {
       parts.push(
-        `累计 ${editStats.editsSinceLastProposed} 次编辑（阈值 ${editStats.threshold}）`,
+        renderBanner("archivePartsEdits", variant, {
+          count: editStats.editsSinceLastProposed,
+          threshold: editStats.threshold,
+        }),
       );
     }
-    const line1 = `📋 Fabric: 距上次归档 ${parts.join(" / ")}。`;
+    // rc.16 TASK-002: 5-banner i18n via lib/banner-i18n.cjs. Substring
+    // contracts ('25.0h', '阈值 N', 'fabric-archive') preserved by the lib's
+    // zh-CN templates — see lib header for the full contract.
+    const line1 = renderBanner("archiveLine1", variant, { parts: parts.join(" / ") });
     const activity = banner && typeof banner.activityOverview === "string"
       ? banner.activityOverview
       : "";
     const line2 = activity.length > 0
-      ? `   最近活动集中在: ${activity}。`
+      ? renderBanner("archiveActivity", variant, { activity })
       : "";
-    const line3 = "   是否调 /fabric-archive 检查值得归档的决策/踩坑/复用?";
+    const line3 = renderBanner("archiveCta", variant, {});
     const reason = [line1, line2, line3].filter((l) => l.length > 0).join("\n");
     return {
       decision: "block",
@@ -600,7 +791,13 @@ function decide(events, now, pendingStats, underseedStats, editCounterStats, thr
   const triggerByPendingAge =
     stats.oldestAgeMs !== null && stats.oldestAgeMs / MS_PER_DAY >= reviewHintPendingAgeDays;
 
-  if (triggerByPendingCount || triggerByPendingAge) {
+  // v2.0.0-rc.8 (TASK-002): suppress ONLY Signal B while a fabric-import
+  // skill run is in flight (read from .fabric/.import-state.json by main()
+  // and threaded in as `importInFlight`). Signals A, C, D are unaffected.
+  // We fall through to Signal C evaluation rather than returning null —
+  // review backlog should not pre-empt import-recommendation evaluation
+  // when import is mid-run.
+  if ((triggerByPendingCount || triggerByPendingAge) && importInFlight !== true) {
     // rc.7 T4: 人-first banner reformat for Signal B. Keeps the pending
     // count and age substrings (`${count} 条`, `${days} 天`) so existing
     // tests pass; drops the Agent-jussive "建议调用 ... skill ..." for a
@@ -609,8 +806,13 @@ function decide(events, now, pendingStats, underseedStats, editCounterStats, thr
       stats.oldestAgeMs !== null
         ? ` / 最早一条 ${(stats.oldestAgeMs / MS_PER_DAY).toFixed(1)} 天前`
         : "";
-    const line1 = `📋 Fabric: 已积累 ${stats.count} 条待审核知识${ageSuffix}。`;
-    const line2 = "   是否调 /fabric-review 审核 pending/ 条目?";
+    // rc.16 TASK-002: i18n via lib. Substrings ('${count} 条', 'fabric-review')
+    // preserved by the lib's zh-CN templates.
+    const line1 = renderBanner("reviewLine1", variant, {
+      count: stats.count,
+      ageSuffix,
+    });
+    const line2 = renderBanner("reviewCta", variant, {});
     const reason = `${line1}\n${line2}`;
     return {
       decision: "block",
@@ -651,12 +853,16 @@ function decide(events, now, pendingStats, underseedStats, editCounterStats, thr
     (hoursSinceProposed === null || hoursSinceProposed >= UNDERSEED_NO_PROPOSED_HOURS);
 
   if (triggerUnderseed) {
-    // rc.7 T4: 人-first banner reformat for Signal C. Preserves the
-    // `${nodeCount}/${threshold}` substring (e.g. "3/10") that existing
-    // tests assert against; drops Agent-jussive phrasing.
-    const line1 =
-      `📋 Fabric: 知识库节点数 ${underseed.nodeCount}/${underseed.threshold}，距 init_scan_completed ${hoursSinceInit.toFixed(1)}h。`;
-    const line2 = "   是否调 /fabric-import 从 git 历史与现有文档回灌知识?";
+    // rc.16 TASK-002: i18n via lib. Substrings ('${nodeCount}/${threshold}',
+    // 'fabric-import', '${hoursSinceInit}h') preserved by the lib's zh-CN
+    // templates. Note: hoursSinceInit is passed as already-toFixed(1) string
+    // to keep the lib pure (no number formatting in render path).
+    const line1 = renderBanner("importLine1", variant, {
+      nodeCount: underseed.nodeCount,
+      threshold: underseed.threshold,
+      hoursSinceInit: hoursSinceInit.toFixed(1),
+    });
+    const line2 = renderBanner("importCta", variant, {});
     const reason = `${line1}\n${line2}`;
     return {
       decision: "block",
@@ -780,6 +986,97 @@ function writeShownCache(projectRoot, cache) {
   }
 }
 
+// -----------------------------------------------------------------------------
+// v2.0.0-rc.37 NEW-16 — per-signal dismiss.
+//
+// Two suppression levers, both honoured at emit time (a chosen signal whose
+// type is dismissed exits silently, exactly like a cooldown hit):
+//   1. Durable opt-out — fabric-config.json#hint_dismiss_signals: string[].
+//      Mirrors the cite_evict_interval=0 opt-out convention; survives across
+//      sessions. The concrete user-actionable lever surfaced in the nudge.
+//   2. Session-scoped — .fabric/.cache/hint-dismiss-{sessionId}.json
+//      { dismissed: string[] }. Ephemeral; written by the agent when the user
+//      asks to silence a nudge type for the current session (Fabric's
+//      AI-driven write convention — no new CLI surface).
+//
+// The four signal types ('archive' / 'review' / 'import' / 'maintenance')
+// each have an independent cooldown ALREADY (signal-keyed SHOWN_CACHE for
+// A/B/C + the maintenance day-cooldown sidecar), so dismiss layers cleanly on
+// top of per-signal cadence without a physical 4-hook split (which would 4×
+// the per-Stop process spawn and break the deliberate single-nudge-per-turn
+// precedence model — KT-DEC-0007 anti-nag spirit).
+// -----------------------------------------------------------------------------
+
+const DISMISSABLE_SIGNALS = ["archive", "review", "import", "maintenance"];
+
+function sessionDismissFileName(sessionId) {
+  const safe = String(sessionId || "anonymous").replace(/[^A-Za-z0-9_.-]/g, "-");
+  return `hint-dismiss-${safe}.json`;
+}
+
+// Returns a Set of dismissed signal types (config-durable ∪ session sidecar).
+// Never throws — degrades to an empty set when libs are absent.
+function readDismissedSignals(projectRoot, sessionId) {
+  const dismissed = new Set();
+  try {
+    if (configCache && typeof configCache.readConfig === "function") {
+      const cfg = configCache.readConfig(projectRoot);
+      const list = cfg && cfg.hint_dismiss_signals;
+      if (Array.isArray(list)) {
+        for (const s of list) {
+          if (DISMISSABLE_SIGNALS.includes(s)) dismissed.add(s);
+        }
+      }
+    }
+  } catch {
+    // defensive
+  }
+  try {
+    if (stateStore && typeof stateStore.readJsonState === "function" && sessionId) {
+      const sidecar = stateStore.readJsonState(
+        projectRoot,
+        sessionDismissFileName(sessionId),
+        (p) => p && typeof p === "object" && Array.isArray(p.dismissed),
+      );
+      if (sidecar) {
+        for (const s of sidecar.dismissed) {
+          if (DISMISSABLE_SIGNALS.includes(s)) dismissed.add(s);
+        }
+      }
+    }
+  } catch {
+    // defensive
+  }
+  return dismissed;
+}
+
+// Persist a session-scoped dismiss set (additive merge). Exposed for the
+// agent-driven write path + tests; not auto-invoked by the hook. Never throws.
+function writeSessionDismiss(projectRoot, sessionId, signals) {
+  if (!stateStore || typeof stateStore.writeJsonState !== "function") return;
+  const fileName = sessionDismissFileName(sessionId);
+  const prior = stateStore.readJsonState(
+    projectRoot,
+    fileName,
+    (p) => p && typeof p === "object" && Array.isArray(p.dismissed),
+  );
+  const merged = new Set(prior && Array.isArray(prior.dismissed) ? prior.dismissed : []);
+  for (const s of Array.isArray(signals) ? signals : []) {
+    if (DISMISSABLE_SIGNALS.includes(s)) merged.add(s);
+  }
+  stateStore.writeJsonState(projectRoot, fileName, { dismissed: [...merged] });
+}
+
+// Bilingual one-line dismiss hint appended to every nudge so the user knows
+// the lever exists. Variant fold mirrors banner-i18n: zh-CN / zh-CN-hybrid →
+// Chinese; en / match-existing / unknown → English.
+function renderDismissOption(signal, variant) {
+  const zh = variant === "zh-CN" || variant === "zh-CN-hybrid";
+  return zh
+    ? `  (不想再看到此类提醒？在 .fabric/fabric-config.json 设 "hint_dismiss_signals": ["${signal}"]，或让我本会话关闭 ${signal} 提醒)`
+    : `  (Silence this nudge? Set "hint_dismiss_signals": ["${signal}"] in .fabric/fabric-config.json, or ask me to dismiss ${signal} for this session)`;
+}
+
 /**
  * v2.0.0-rc.7 T10: find the most recent doctor_run event ts in the ledger.
  * Returns the ts (epoch ms) of the newest doctor_run event, or null if none
@@ -859,15 +1156,23 @@ function evaluateMaintenanceSignal(events, now, canonicalCount, lastEmitMs, thre
     typeof cfg.maintenanceHintCooldownDays === "number" && cfg.maintenanceHintCooldownDays > 0
       ? cfg.maintenanceHintCooldownDays
       : DEFAULT_MAINTENANCE_HINT_COOLDOWN_DAYS;
+  // rc.16 TASK-002: banner variant for the i18n lib. Defaults to 'zh-CN' so
+  // existing rc.7 T10 test fixtures (which never set thresholds.variant) get
+  // the byte-identical Chinese maintenance banner.
+  const variant = typeof cfg.variant === "string" ? cfg.variant : "zh-CN";
 
   if (canonicalCount < MAINTENANCE_HINT_MIN_CANONICAL) {
     return null;
   }
 
   // Cooldown gate — short-circuit when we just nagged.
+  // rc.34 TASK-01 + review-fix (Gemini P1): future-stamped lastEmit (backward
+  // clock skew) bypasses cooldown — treats sidecar as "expired" so the gate
+  // heals on the next invocation instead of waiting (cooldown + |skew|).
   if (
     typeof lastEmitMs === "number" &&
     Number.isFinite(lastEmitMs) &&
+    nowMs >= lastEmitMs &&
     nowMs - lastEmitMs < cooldownDays * MS_PER_DAY
   ) {
     return null;
@@ -883,14 +1188,18 @@ function evaluateMaintenanceSignal(events, now, canonicalCount, lastEmitMs, thre
     if (ageDays < days) return null; // doctor ran recently, no nag.
   }
 
-  // rc.7 T4: keep the existing T10 banner shape (already 人-first with the
-  // 📋 prefix), but split the action-prompt onto its own line for visual
-  // consistency with Signals A/B/C. Substrings ("从未运行 lint 检查",
-  // "已 N 天未跑 lint", "fabric doctor --lint") preserved for the T10 tests.
-  const line2 = "   是否调 `fabric doctor --lint` 看看知识库健康度?";
-  const reason = lastDoctorTs === null
-    ? `📋 Fabric: 从未运行 lint 检查。\n${line2}`
-    : `📋 Fabric: 已 ${days} 天未跑 lint 检查（实际 ${ageDays.toFixed(1)}d）。\n${line2}`;
+  // rc.16 TASK-002: i18n via lib. Substrings ('从未运行 lint 检查',
+  // '已 N 天未跑 lint', 'fabric doctor --lint') preserved by the lib's
+  // zh-CN templates. ageDays passed as already-toFixed(1) string to keep
+  // the lib pure (no number formatting in render path).
+  const line2 = renderBanner("maintenanceLine2", variant, {});
+  const line1 = lastDoctorTs === null
+    ? renderBanner("maintenanceLine1Never", variant, {})
+    : renderBanner("maintenanceLine1Aged", variant, {
+        days,
+        ageDays: ageDays.toFixed(1),
+      });
+  const reason = `${line1}\n${line2}`;
 
   return {
     decision: "block",
@@ -922,11 +1231,224 @@ function tryReadStdinJson() {
     const parsed = JSON.parse(buf);
     if (parsed === null || typeof parsed !== "object") return null;
     return parsed;
-  } catch {
+  } catch (e) {
+    // v2.0.0-rc.29 TASK-008 (BUG-L1): hook used to silent-swallow JSON.parse
+    // errors which masked real client-side payload bugs (e.g. CLI hosts that
+    // stopped emitting Stop-hook JSON envelopes). Log a single best-effort
+    // diagnostic line so operators see WHY the hook went quiet; keep returning
+    // null so downstream behaviour (graceful exit 0, no rule render) is
+    // unchanged.
+    try {
+      const message = (e && typeof e === "object" && "message" in e) ? String(e.message) : String(e);
+      process.stderr.write(`[fabric-hint] malformed input: ${message}\n`);
+    } catch {
+      // stderr write failed (very unusual — sandbox / closed fd). The
+      // hook contract still requires we never throw upward.
+    }
     return null;
   }
 }
 
+/**
+ * v2.0.0-rc.20 TASK-03 → v2.0.0-rc.24 TASK-04: legacy shim signature for
+ * parsing the raw text that follows the `KB:` prefix on the first non-empty
+ * line of an assistant turn. As of rc.24 the implementation delegates to the
+ * shared `parseCiteLine` (inline-shipped via lib/cite-line-parser.cjs) to
+ * eliminate per-client regex drift.
+ *
+ * Contract (rc.24 strict mode — superset of rc.20):
+ *   - Sentinel `none` (incl. `[no-relevant]` / `[not-applicable]` tail)
+ *     → cite_ids=[], cite_tags=["none"], cite_commitments=[]
+ *   - `KT-DEC-0001 [planned]` → cite_ids=["KT-DEC-0001"], cite_tags=["planned"],
+ *     cite_commitments=[{operators:[], skip_reason:null}]
+ *   - `KT-DEC-0001 [recalled] → edit:foo.ts` → cite_commitments=[{operators:
+ *     [{kind:"edit", target:"foo.ts"}], skip_reason:null}]
+ *   - `KT-DEC-0001 [recalled] → skip:sequencing` → cite_commitments=[{operators:
+ *     [], skip_reason:"sequencing"}]
+ *   - Id form is now strict `K[TP]-[A-Z]+-\d+` (rc.20 lax form `KP-001`
+ *     without letter-prefix is rejected — see TASK-03 schema).
+ *
+ * Argument is the post-`KB:` substring (matches the rc.20 call site). Returns
+ * { cite_ids, cite_tags, cite_commitments }; cite_commitments was added in
+ * rc.24 and is always present (empty array when no cite-line found).
+ *
+ * Never throws.
+ */
+function parseKbLine(raw) {
+  // Compose the full `KB: <raw>` line because the shared parser anchors on
+  // the `KB:` prefix. Handles the legacy `none` / `<sentinel>` inputs naturally
+  // because parseCiteLine's SENTINEL_RE matches the composed line.
+  if (typeof raw !== "string") {
+    return { cite_ids: [], cite_tags: [], cite_commitments: [] };
+  }
+  const composed = `KB: ${raw}`;
+  if (citeLineParser && typeof citeLineParser.parseCiteLine === "function") {
+    return citeLineParser.parseCiteLine(composed);
+  }
+  // Degraded fallback: lib missing (e.g. partial install). Emit empty result
+  // so downstream consumers see the cite-line as unobservable rather than
+  // mis-parsed. The Stop-hook contract is best-effort, never blocking.
+  return { cite_ids: [], cite_tags: [], cite_commitments: [] };
+}
+
+/**
+ * v2.0.0-rc.20 TASK-03: detect which client surface invoked the hook so the
+ * emitted assistant_turn_observed event can carry a `client` discriminator
+ * without having to inspect the transcript shape.
+ *
+ * Resolution order (first match wins):
+ *   1. `FABRIC_HINT_CLIENT` env var — explicit override, set by the per-
+ *      client install pipeline when the hook-config schema supports env
+ *      injection.
+ *   2. Path heuristic against `__dirname` — `.claude/` → "cc", `.codex/` →
+ *      "codex". Covers the dominant deployment shape (hook script lives
+ *      under the client's per-repo dir).
+ *
+ * Returns `undefined` when neither signal fires (e.g. Cursor — deferred to
+ * rc.21 — or a custom deployment). The Zod schema marks `client` optional,
+ * so omitting it leaves the event valid.
+ */
+function detectClient() {
+  // Delegate the full 3-tier detection (env → CLAUDE_PROJECT_DIR → path
+  // heuristic, incl. .cursor) to the shared adapter. __dirname is passed so
+  // the path heuristic reflects THIS hook's location.
+  if (clientAdapter && typeof clientAdapter.detectClient === "function") {
+    return clientAdapter.detectClient(__dirname);
+  }
+  // Fallback (adapter lib absent): env override only.
+  const envClient = process.env.FABRIC_HINT_CLIENT;
+  if (typeof envClient === "string" && envClient.length > 0) {
+    const normalised = envClient.trim().toLowerCase();
+    if (normalised === "cc" || normalised === "codex" || normalised === "cursor") {
+      return normalised;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * v2.0.0-rc.20 TASK-03: emit one `assistant_turn_observed` event per
+ * assistant envelope harvested from the transcript. Wrapped in try/catch
+ * (best-effort, never throws — Stop hook MUST stay non-blocking on any
+ * failure here). The event shape mirrors
+ * assistantTurnObservedEventSchema in
+ * packages/shared/src/schemas/event-ledger.ts (registered in rc.20 TASK-02).
+ *
+ * Call site sits immediately AFTER writeSessionDigestBestEffort so both
+ * digest + per-turn events derive from the same transcript snapshot.
+ *
+ * `id` mirrors the server's convention (`event:<uuid>`) using
+ * crypto.randomUUID when available — falls back to a timestamp+counter
+ * tuple on older Node where randomUUID is missing (cjs hook tooling
+ * defensively targets Node 18+, but the fallback keeps it event-shaped).
+ */
+function extractAndWriteAssistantTurnsBestEffort(cwd, stdinPayload) {
+  if (stdinPayload === null || typeof stdinPayload !== "object") return;
+  try {
+    const sessionId = stdinPayload.session_id;
+    if (typeof sessionId !== "string" || sessionId.length === 0) return;
+    const transcript = summarizeTranscript(stdinPayload.transcript_path);
+    const turns = transcript.assistant_turns;
+    if (!Array.isArray(turns) || turns.length === 0) return;
+
+    // Resolve event-ledger path. Caller already validated cwd shape.
+    const fabricDir = join(cwd, FABRIC_DIR);
+    if (!existsSync(fabricDir)) {
+      // No .fabric/ → workspace is uninitialised. Silently skip; the digest
+      // writer applies the same guard via its own internal check.
+      return;
+    }
+    const ledgerPath = join(fabricDir, EVENT_LEDGER_FILE);
+    const client = detectClient();
+    let randomUUID;
+    try {
+      ({ randomUUID } = require("node:crypto"));
+    } catch {
+      randomUUID = null;
+    }
+
+    // v2.0.0-rc.39 (P1 emit-fold): empty-shell turns (no KB: line, no cites)
+    // do not get an events.jsonl line — they are tallied and folded into one
+    // metrics.jsonl counter row at the end of this batch. This zeroes the 99%
+    // empty-shell bloat at the source while keeping cite-bearing turns as
+    // discrete audit events. Count carries per-Stop re-emission exactly (we
+    // tally every empty turn the transcript presents, not just new ones), so
+    // the reader-side counter merge reconstructs total_turns byte-for-byte.
+    let emptyShellCount = 0;
+    for (const turn of turns) {
+      try {
+        const citeIds = Array.isArray(turn.cite_ids) ? turn.cite_ids : [];
+        const citeCommitments = Array.isArray(turn.cite_commitments)
+          ? turn.cite_commitments
+          : [];
+        const isEmptyShell =
+          (turn.kb_line_raw === null || turn.kb_line_raw === undefined) &&
+          citeIds.length === 0 &&
+          citeCommitments.length === 0;
+        if (isEmptyShell) {
+          emptyShellCount += 1;
+          continue;
+        }
+        const idSuffix = typeof randomUUID === "function"
+          ? randomUUID()
+          : `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+        const event = {
+          kind: "fabric-event",
+          id: `event:${idSuffix}`,
+          ts: Date.now(),
+          schema_version: 1,
+          session_id: sessionId,
+          event_type: EVENT_TYPE_ASSISTANT_TURN_OBSERVED,
+          kb_line_raw: turn.kb_line_raw,
+          cite_ids: citeIds,
+          cite_tags: Array.isArray(turn.cite_tags) ? turn.cite_tags : [],
+          // rc.24 TASK-04: cite_commitments parallel array (assistantTurn
+          // ObservedEventSchema gained this slot in rc.24 TASK-01). Empty
+          // array for legacy turns or when the parser lib is unavailable —
+          // the schema defaults `.default([])` so omitting it would also be
+          // valid, but emitting an explicit `[]` keeps the on-disk shape
+          // uniform across rc.24+ events.
+          cite_commitments: citeCommitments,
+          turn_id: `${sessionId}-${turn.envelope_index}`,
+          envelope_index: turn.envelope_index,
+          timestamp: new Date().toISOString(),
+        };
+        if (client !== undefined) event.client = client;
+        appendFileSync(ledgerPath, JSON.stringify(event) + "\n", "utf8");
+      } catch {
+        // Per-turn failure must not abort the remaining turns; the Stop hook
+        // contract is "never block on hook failure". Best-effort continues.
+      }
+    }
+
+    // rc.39 emit-fold: write one metrics.jsonl counter row for the folded
+    // empty-shell turns. Best-effort — a failure here must never block the
+    // Stop hook (KT-DEC-0007). The counter key is namespaced by client so the
+    // reader's per_client total_turns breakdown stays invariant; an undefined
+    // client (adapter lib absent) folds into the bare `assistant_turn_observed`
+    // key, mirroring how such turns omit the event-side `client` discriminator.
+    if (emptyShellCount > 0) {
+      try {
+        const counterKey =
+          client !== undefined
+            ? `${EVENT_TYPE_ASSISTANT_TURN_OBSERVED}:${client}`
+            : EVENT_TYPE_ASSISTANT_TURN_OBSERVED;
+        const metricsRow = {
+          timestamp: new Date().toISOString(),
+          window: "stop",
+          counters: { [counterKey]: emptyShellCount },
+        };
+        const metricsPath = join(fabricDir, METRICS_LEDGER_FILE);
+        appendFileSync(metricsPath, JSON.stringify(metricsRow) + "\n", "utf8");
+      } catch {
+        // metrics fold is observability-only; never block the hook on failure.
+      }
+    }
+  } catch {
+    // Outer guard — never throw. Hook continues silently.
+  }
+}
+
 /**
  * v2.0.0-rc.7 T5: extract user_messages + edit_paths + 1-line title from the
  * transcript JSONL referenced by the hook's stdin payload. Best-effort, never
@@ -935,9 +1457,18 @@ function tryReadStdinJson() {
  * Claude Code's transcript_path points at a JSONL where each line is a
  * message envelope. We sniff for `role: "user"` lines (text content) and
  * for tool-use entries naming Edit / Write / MultiEdit to harvest file_path.
+ *
+ * v2.0.0-rc.20 TASK-03: additionally collects `assistant_turns[]` — one
+ * entry per assistant envelope with the parsed KB-line cite metadata. Field
+ * is additive; existing callers (writeSessionDigestBestEffort) ignore it.
  */
 function summarizeTranscript(transcriptPath) {
-  const out = { user_messages: [], edit_paths: [], title: "" };
+  // rc.20 TASK-03: additive `assistant_turns` array — one entry per assistant
+  // envelope, regardless of whether the first line matched KB:. Downstream
+  // consumers (extractAndWriteAssistantTurnsBestEffort) emit one
+  // assistant_turn_observed event per element; `kb_line_raw=null` when no
+  // KB: line was found.
+  const out = { user_messages: [], edit_paths: [], title: "", assistant_turns: [] };
   if (typeof transcriptPath !== "string" || transcriptPath.length === 0) return out;
   if (!existsSync(transcriptPath)) return out;
   let raw;
@@ -947,6 +1478,7 @@ function summarizeTranscript(transcriptPath) {
     return out;
   }
   const lines = raw.split(/\r?\n/);
+  let envelopeIndex = -1;
   for (const line of lines) {
     const trimmed = line.trim();
     if (trimmed.length === 0) continue;
@@ -957,12 +1489,23 @@ function summarizeTranscript(transcriptPath) {
       continue;
     }
     if (envelope === null || typeof envelope !== "object") continue;
-
-    // User text message — Claude Code shape: { role: "user", content: [...] }
-    // OR nested under `message.role`. Be generous.
-    const role = envelope.role || (envelope.message && envelope.message.role);
+    envelopeIndex += 1;
+
+    // v2.0.0-rc.27 TASK-009 (audit §2.16): Codex CLI uses a different
+    // envelope shape — { type:"response_item", payload:{ type:"message",
+    // role, content:[{type:"input_text"|"output_text", text}] } } — vs Claude
+    // Code's { type:"user", message:{ role, content } }. Resolve role +
+    // content from whichever shape is present; without this, every Codex
+    // session's digest came out empty (audit §2.16 — fixed here).
+    const role =
+      envelope.role ||
+      (envelope.message && envelope.message.role) ||
+      (envelope.payload && envelope.payload.role);
     if (role === "user") {
-      const content = envelope.content || (envelope.message && envelope.message.content);
+      const content =
+        envelope.content ||
+        (envelope.message && envelope.message.content) ||
+        (envelope.payload && envelope.payload.content);
       if (typeof content === "string") {
         out.user_messages.push(content);
       } else if (Array.isArray(content)) {
@@ -974,6 +1517,85 @@ function summarizeTranscript(transcriptPath) {
       }
     }
 
+    // rc.20 TASK-03: assistant envelope — capture first non-empty line of the
+    // first text block and parse for `KB:` prefix. We push ONE assistant_turns
+    // entry per assistant envelope (even when no KB: line) so downstream can
+    // distinguish "turn observed, no KB" (kb_line_raw=null) from "no turn".
+    if (role === "assistant") {
+      const content =
+        envelope.content ||
+        (envelope.message && envelope.message.content) ||
+        (envelope.payload && envelope.payload.content);
+      let firstText = null;
+      if (typeof content === "string") {
+        firstText = content;
+      } else if (Array.isArray(content)) {
+        for (const block of content) {
+          if (block && typeof block === "object" && block.type === "text" && typeof block.text === "string") {
+            firstText = block.text;
+            break;
+          }
+        }
+      }
+      let kbLineRaw = null;
+      let citeIds = [];
+      let citeTags = [];
+      // rc.24 TASK-04: parallel `cite_commitments` array, populated by the
+      // shared cite-line parser. One entry per non-sentinel cite (index-aligned
+      // with cite_ids). Sentinel `KB: none` contributes a `cite_tags=["none"]`
+      // entry but no commitment — matches the parseCiteLine index contract.
+      let citeCommitments = [];
+      // v2.0.0-rc.27 TASK-009: Codex assistant blocks carry text under
+      // `type:"output_text"` (not `type:"text"`). Fall back when no text-typed
+      // block matched but a typed output_text block exists.
+      if (firstText === null && Array.isArray(content)) {
+        for (const block of content) {
+          if (block && typeof block === "object" && block.type === "output_text" && typeof block.text === "string") {
+            firstText = block.text;
+            break;
+          }
+        }
+      }
+      if (typeof firstText === "string" && firstText.length > 0) {
+        // First non-empty line.
+        const linesOfText = firstText.split(/\r?\n/);
+        let firstNonEmpty = "";
+        for (const l of linesOfText) {
+          if (l.trim().length > 0) {
+            firstNonEmpty = l.trim();
+            break;
+          }
+        }
+        if (firstNonEmpty.length > 0) {
+          // rc.24 TASK-04: route the FULL `KB: ...` line to the shared parser.
+          // parseCiteLine handles sentinels (`KB: none [<reason>]`) AND full
+          // cite form including contract tail (`KB: KT-DEC-0001 [recalled] →
+          // edit:foo.ts`) uniformly. The sentinel's `[<reason>]` tail stays in
+          // `kb_line_raw` for doctor's downstream histogram parse; cite_tags
+          // still emits the bare `none` token (schema enum-bound).
+          if (/^KB:\s*/i.test(firstNonEmpty)) {
+            kbLineRaw = firstNonEmpty;
+            if (citeLineParser && typeof citeLineParser.parseCiteLine === "function") {
+              const parsed = citeLineParser.parseCiteLine(firstNonEmpty);
+              citeIds = parsed.cite_ids;
+              citeTags = parsed.cite_tags;
+              citeCommitments = parsed.cite_commitments;
+            }
+            // Degraded mode (lib missing) → keep kbLineRaw but emit empty
+            // arrays; doctor downstream treats this as "turn observed, parse
+            // unavailable" without crashing.
+          }
+        }
+      }
+      out.assistant_turns.push({
+        envelope_index: envelopeIndex,
+        kb_line_raw: kbLineRaw,
+        cite_ids: citeIds,
+        cite_tags: citeTags,
+        cite_commitments: citeCommitments,
+      });
+    }
+
     // Tool use — look for Edit / Write / MultiEdit and harvest file_path.
     const candidates = [];
     if (envelope.type === "tool_use") candidates.push(envelope);
@@ -999,6 +1621,27 @@ function summarizeTranscript(transcriptPath) {
         }
       }
     }
+
+    // v2.0.0-rc.27 TASK-009 (audit §2.16): Codex apply_patch path. Codex
+    // emits one response_item envelope per file-edit invocation with payload
+    // shape { type:"custom_tool_call", name:"apply_patch", input:<patch
+    // string> }. The patch body lists target files via `*** Update File:`,
+    // `*** Add File:`, `*** Delete File:` directives — harvest those.
+    if (
+      envelope.type === "response_item" &&
+      envelope.payload &&
+      envelope.payload.type === "custom_tool_call" &&
+      envelope.payload.name === "apply_patch" &&
+      typeof envelope.payload.input === "string"
+    ) {
+      const patchInput = envelope.payload.input;
+      const fileDirectiveRe = /^\*\*\*\s+(?:Update|Add|Delete)\s+File:\s+(.+?)\s*$/gm;
+      let m;
+      while ((m = fileDirectiveRe.exec(patchInput)) !== null) {
+        const fp = m[1].trim();
+        if (fp.length > 0) out.edit_paths.push(fp);
+      }
+    }
   }
   // 1-line title = first non-empty user message (trimmed). Falls back to "".
   if (out.user_messages.length > 0) {
@@ -1015,6 +1658,50 @@ function summarizeTranscript(transcriptPath) {
   return out;
 }
 
+/**
+ * v2.0.0-rc.24 TASK-05: emit soft L1 reminder to stderr when assistant turns
+ * cited a decision/pitfall id with [recalled] but no operator contract and no
+ * skip:<reason>. Reads agents.meta.json once per invocation; aggregated per
+ * turn (one line per offending id). Non-blocking — never throws, always
+ * returns the array of emitted reminder strings (for unit tests + callers
+ * that want to observe what was written).
+ *
+ * The reminder writes go to stderr (the hook contract: stdout is structured
+ * banner JSON consumed by the harness; stderr is free-text system message
+ * that surfaces back to the model on the next turn in cc / codex / cursor).
+ */
+function emitCiteContractRemindersBestEffort(cwd, stdinPayload, stderr) {
+  if (citeContractReminder === null) return [];
+  if (stdinPayload === null || typeof stdinPayload !== "object") return [];
+  try {
+    const transcript = summarizeTranscript(stdinPayload.transcript_path);
+    const turns = transcript.assistant_turns;
+    if (!Array.isArray(turns) || turns.length === 0) return [];
+
+    const idTypeMap = citeContractReminder.readKnowledgeTypeMap(cwd);
+    if (!(idTypeMap instanceof Map) || idTypeMap.size === 0) return [];
+
+    const reminders = citeContractReminder.formatContractMissingReminders({
+      assistant_turns: turns,
+      idTypeMap,
+    });
+    if (!Array.isArray(reminders) || reminders.length === 0) return [];
+
+    const sink = stderr || process.stderr;
+    for (const line of reminders) {
+      try {
+        sink.write(line + "\n");
+      } catch {
+        // Sink write failure must not abort emission of remaining reminders.
+      }
+    }
+    return reminders;
+  } catch {
+    // Outer guard — never throw. Hook continues silently.
+    return [];
+  }
+}
+
 /**
  * v2.0.0-rc.7 T5: writeSessionDigestBestEffort — non-blocking digest fan-out.
  * Called from main() before the existing decide() flow. Failure is silently
@@ -1060,6 +1747,23 @@ function main(env, stdio) {
         ? env.stdin_payload
         : tryReadStdinJson();
     writeSessionDigestBestEffort(cwd, stdinPayload);
+    // v2.0.0-rc.20 TASK-03: per-turn cite-policy observation events. Same
+    // best-effort contract as the digest writer — never throws, never blocks
+    // the Stop hook on failure. Shares the transcript snapshot read by
+    // writeSessionDigestBestEffort (each call re-reads independently; the
+    // transcript file is small in practice and re-parse cost is dwarfed by
+    // the hook's other I/O).
+    extractAndWriteAssistantTurnsBestEffort(cwd, stdinPayload);
+
+    // v2.0.0-rc.24 TASK-05: L1 soft reminder layer. Surfaces ⚠ KB:<id> lines
+    // to stderr when decision/pitfall cites arrived with [recalled] tag but
+    // empty contract. Non-blocking, never throws; doctor (TASK-08) catches
+    // any contract violation the model ignored.
+    emitCiteContractRemindersBestEffort(
+      cwd,
+      stdinPayload,
+      stdio && stdio.stderr,
+    );
 
     const events = readLedger(cwd);
     let pendingStats;
@@ -1108,6 +1812,19 @@ function main(env, stdio) {
     // rc.7 T7: read the externalized thresholds and pass them into decide.
     // Reader failures degrade silently to documented defaults — fabric-hint
     // must never block on config errors (see hook contract above).
+    //
+    // rc.16 TASK-002 (F2-apply): resolve `fabric_language` ONCE per main()
+    // invocation via the banner-i18n lib. The result threads through
+    // `thresholds.variant` into both decide() and evaluateMaintenanceSignal()
+    // so we read the config file at most once, not five times. Lib reader
+    // is never-throw; defensive try/catch is belt-and-suspenders.
+    let variant = "zh-CN";
+    try {
+      variant = readFabricLanguage(cwd);
+    } catch {
+      variant = "zh-CN";
+    }
+
     let thresholds;
     try {
       thresholds = {
@@ -1116,6 +1833,7 @@ function main(env, stdio) {
         reviewHintPendingAgeDays: readReviewHintPendingAgeDays(cwd),
         maintenanceHintDays: readMaintenanceHintDays(cwd),
         maintenanceHintCooldownDays: readMaintenanceHintCooldownDays(cwd),
+        variant,
       };
     } catch {
       thresholds = {
@@ -1124,6 +1842,7 @@ function main(env, stdio) {
         reviewHintPendingAgeDays: DEFAULT_REVIEW_HINT_PENDING_AGE_DAYS,
         maintenanceHintDays: DEFAULT_MAINTENANCE_HINT_DAYS,
         maintenanceHintCooldownDays: DEFAULT_MAINTENANCE_HINT_COOLDOWN_DAYS,
+        variant,
       };
     }
 
@@ -1147,28 +1866,29 @@ function main(env, stdio) {
       activityOverview = "";
     }
 
-    // rc.7 T1: sentinel-priority pickup. The `.fabric/.import-requested`
-    // file is the cross-surface signal from `fabric init` Y-confirm. When
-    // present, the Stop hook emits a Signal C "import" result regardless of
-    // underseed thresholds, cooldown sidecar state, or precedence with
-    // other signals. This branch sits BEFORE decide() so the import
-    // recommendation always wins until the fabric-import Skill clears the
-    // sentinel in its Phase 3.4. Cooldown sidecar IS bypassed (the
-    // recommendation surface area is intentionally aggressive — the user
-    // explicitly asked for it at init time).
-    const sentinelPresent = isImportRequestedSentinelPresent(cwd);
-
-    let result = sentinelPresent
-      ? makeImportSentinelResult()
-      : decide(
-          events,
-          now,
-          pendingStats,
-          underseedStats,
-          editCounterStats,
-          thresholds,
-          { activityOverview },
-        );
+    // v2.0.0-rc.8 (TASK-002): probe `.fabric/.import-state.json` to
+    // determine whether a fabric-import skill run is currently in flight.
+    // Threaded into decide() so Signal B (review hint) is suppressed for
+    // the duration of an active import — preventing the Stop hook from
+    // interrupting the import when its pending pile crosses the review
+    // threshold. See isImportInFlight() docstring for the full truth table.
+    let importInFlight = false;
+    try {
+      importInFlight = isImportInFlight(cwd, now);
+    } catch {
+      importInFlight = false;
+    }
+
+    let result = decide(
+      events,
+      now,
+      pendingStats,
+      underseedStats,
+      editCounterStats,
+      thresholds,
+      { activityOverview },
+      importInFlight,
+    );
 
     // v2.0.0-rc.7 T10: Signal D — maintenance hint. Evaluated AFTER A/B/C
     // because the existing three signals carry higher urgency (in-flight
@@ -1193,6 +1913,40 @@ function main(env, stdio) {
 
     if (result === null) return;
 
+    // v2.0.0-rc.37 NEW-16: per-signal dismiss. A chosen signal whose type the
+    // user dismissed (config-durable or session sidecar) exits silently —
+    // same shape as a cooldown hit. Covers BOTH maintenance and A/B/C paths.
+    const sessionId =
+      stdinPayload && typeof stdinPayload.session_id === "string"
+        ? stdinPayload.session_id
+        : null;
+    if (readDismissedSignals(cwd, sessionId).has(result.signal)) {
+      return;
+    }
+    // Append the bilingual dismiss-option line so the lever is discoverable.
+    if (typeof result.reason === "string") {
+      result.reason = `${result.reason}\n${renderDismissOption(result.signal, variant)}`;
+    }
+
+    // v2.1.0-rc.1 P4 (F4/S63): surface the read-set stores on the Stop hint so
+    // backlog/maintenance nudges are read per-store, not as one undifferentiated
+    // pile. Best-effort; missing snapshot / single-store omits the line.
+    if (bindingsSnapshotReader !== null && typeof result.reason === "string") {
+      try {
+        const projectId = readProjectId(cwd);
+        if (projectId) {
+          const label = bindingsSnapshotReader.formatStoreLabels(
+            bindingsSnapshotReader.readBindingsSnapshot(projectId),
+          );
+          if (label) {
+            result.reason = `${result.reason}\n${label}`;
+          }
+        }
+      } catch {
+        // store label is decorative provenance — never crash the hook
+      }
+    }
+
     // v2.0.0-rc.7 T10: Signal D uses its own cooldown sidecar (day-based,
     // see MAINTENANCE_HINT_LAST_EMIT_FILE). The A/B/C shared cooldown cache
     // uses hours, so we branch here to avoid mixing semantics.
@@ -1202,24 +1956,19 @@ function main(env, stdio) {
       return;
     }
 
-    // rc.7 T1: sentinel-driven results bypass the cooldown sidecar entirely.
-    // The user explicitly asked at init time for the import recommendation
-    // to surface; the cooldown is a noise-throttle for organic signals,
-    // not for explicit user-driven hand-offs. We also do NOT bump the
-    // cooldown cache when the sentinel fires — that would silence the
-    // *next* organic Signal C unnecessarily.
-    if (sentinelPresent) {
-      out.write(JSON.stringify(result));
-      return;
-    }
-
     // Cooldown throttle: once a signal fires, stay silent for
     // archive_hint_cooldown_hours (default 12h) regardless of state drift.
     // Pure reminder-noise reduction; the underlying trigger logic is unchanged.
     const cooldownMs = readCooldownHours(cwd) * MS_PER_HOUR;
     const cache = readShownCache(cwd);
     const lastShown = cache[result.signal];
-    if (typeof lastShown === "number" && nowMs - lastShown < cooldownMs) {
+    // rc.34 TASK-01 + review-fix (Gemini P1): future-stamped lastShown
+    // (backward clock skew) bypasses cooldown — sidecar treated as expired.
+    if (
+      typeof lastShown === "number" &&
+      nowMs >= lastShown &&
+      nowMs - lastShown < cooldownMs
+    ) {
       return; // Still in cooldown — silent.
     }
 
@@ -1240,13 +1989,20 @@ module.exports = {
   // rc.7 T4: top-edited-directories aggregator + banner overview formatter.
   getTopEditedDirectories,
   formatActivityOverview,
-  // rc.7 T1: cross-surface sentinel pickup helpers (exported for testing).
-  isImportRequestedSentinelPresent,
-  makeImportSentinelResult,
+  // v2.0.0-rc.8 (TASK-002): in-flight import gate for Signal B (exported
+  // for unit testing of the truth table).
+  isImportInFlight,
   decide,
   readCooldownHours,
   readUnderseedThreshold,
   readArchiveEditThreshold,
+  // v2.0.0-rc.37 NEW-16: per-signal dismiss helpers (exported for tests +
+  // the agent-driven session-dismiss write path).
+  readDismissedSignals,
+  writeSessionDismiss,
+  sessionDismissFileName,
+  renderDismissOption,
+  DISMISSABLE_SIGNALS,
   // v2.0.0-rc.7 T5: session digest helpers (exported for unit testing).
   tryReadStdinJson,
   summarizeTranscript,
@@ -1264,9 +2020,20 @@ module.exports = {
   readMaintenanceHintCooldownDays,
   readShownCache,
   writeShownCache,
+  // v2.0.0-rc.20 TASK-03 / TASK-09: cite-policy parsing + per-turn emission
+  // helpers (exported for unit testing of the parse + emit contract).
+  parseKbLine,
+  detectClient,
+  extractAndWriteAssistantTurnsBestEffort,
+  // v2.0.0-rc.24 TASK-05: L1 soft reminder helpers (exported for unit testing
+  // of the contract-missing emission contract). The lib module itself is
+  // also exported indirectly via the reminder helper.
+  emitCiteContractRemindersBestEffort,
   CONSTANTS: {
     FABRIC_DIR,
     EVENT_LEDGER_FILE,
+    METRICS_LEDGER_FILE,
+    EVENT_TYPE_ASSISTANT_TURN_OBSERVED,
     EVENT_TYPE_PROPOSED,
     EVENT_TYPE_INIT_SCAN_COMPLETED,
     // rc.7 T7: legacy aliases kept for back-compat with the existing test
@@ -1296,8 +2063,9 @@ module.exports = {
     EVENT_TYPE_DOCTOR_RUN,
     MAINTENANCE_HINT_LAST_EMIT_FILE,
     MAINTENANCE_HINT_MIN_CANONICAL,
-    // rc.7 T1: cross-surface sentinel for `fabric init` → import-skill hand-off.
-    IMPORT_REQUESTED_SENTINEL_FILE,
+    // v2.0.0-rc.8 (TASK-002): in-flight import gate for Signal B.
+    IMPORT_STATE_FILE_REL,
+    IMPORT_IN_FLIGHT_MAX_AGE_HOURS,
   },
 };