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

package/dist/{whoami-B6AEMSEV.js → whoami-2MLO4Y37.js}

@@ -1,4 +1,7 @@
 #!/usr/bin/env node
+import {
+  getProjectTranslator
+} from "./chunk-2CY4BMTH.js";
 import {
   whoami
 } from "./chunk-T5RPGCCM.js";
@@ -10,19 +13,21 @@ import { defineCommand } from "citty";
 var whoami_default = defineCommand({
   meta: { name: "whoami", description: "Show this machine's Fabric uid and mounted stores" },
   run() {
+    const t = getProjectTranslator();
     const info = whoami();
     if (info === null) {
-      console.log("no global Fabric config \u2014 run `fabric install --global <url>` first");
+      console.log(t("cli.cmd.no-global-config"));
       return;
     }
-    console.log(`uid: ${info.uid}`);
+    console.log(t("cli.whoami.uid", { uid: info.uid }));
     if (info.stores.length === 0) {
-      console.log("stores: (none mounted)");
+      console.log(t("cli.whoami.stores-none"));
       return;
     }
-    console.log("stores:");
+    console.log(t("cli.whoami.stores-label"));
+    const localOnly = t("cli.shared.local-only");
     for (const store of info.stores) {
-      console.log(`  ${store.alias}	${store.store_uuid}${store.local_only ? "	(local-only)" : ""}`);
+      console.log(`  ${store.alias}	${store.store_uuid}${store.local_only ? `	${localOnly}` : ""}`);
     }
   }
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fenglimg/fabric-cli",
-  "version": "2.1.0-rc.2",
+  "version": "2.2.0-rc.1",
   "description": "Fabric CLI — installs the MCP server + skills + hooks for Claude Code, Cursor, and Codex CLI; runs doctor / knowledge maintenance.",
   "license": "MIT",
   "author": "wangzhichao <fenglimg90@gmail.com>",
@@ -45,8 +45,8 @@
     "tree-sitter-javascript": "^0.25.0",
     "tree-sitter-typescript": "^0.23.2",
     "web-tree-sitter": "^0.26.8",
-    "@fenglimg/fabric-server": "2.1.0-rc.2",
-    "@fenglimg/fabric-shared": "2.1.0-rc.2"
+    "@fenglimg/fabric-server": "2.2.0-rc.1",
+    "@fenglimg/fabric-shared": "2.2.0-rc.1"
   },
   "devDependencies": {
     "@types/node": "^22.15.0",

package/templates/hooks/fabric-hint.cjs

@@ -1,7 +1,13 @@
 #!/usr/bin/env node
-const { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } = require("node:fs");
+const { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } = require("node:fs");
 const { dirname, join } = require("node:path");
 
+// W1-01 (ISS-012): Stop / SessionStart hooks append to shared, non-session-scoped
+// ledgers (events.jsonl, metrics.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");
+
 // v2.0.0-rc.7 T5: session-digest writer. Best-effort (never blocks Stop hook
 // on failure — see contract in lib/session-digest-writer.cjs).
 let sessionDigestWriter = null;
@@ -783,6 +789,11 @@ function decide(events, now, pendingStats, underseedStats, editCounterStats, thr
       reason,
       signal: "archive",
       recommended_skill: "fabric-archive",
+      // v2.1 NEW-N-3: surface the firing sub-signal's numbers for the
+      // hook_signal_emitted ledger row main() writes. Dual trigger (24h OR
+      // N-edits): report the hours pair when it fired, else the edit-count pair.
+      threshold: triggerByHours ? archiveHintHours : editStats.threshold,
+      actual_value: triggerByHours ? hoursElapsed : editStats.editsSinceLastProposed,
     };
   }
 
@@ -819,6 +830,10 @@ function decide(events, now, pendingStats, underseedStats, editCounterStats, thr
       reason,
       signal: "review",
       recommended_skill: "fabric-review",
+      // v2.1 NEW-N-3: dual trigger (pending-count OR oldest-age). Report the
+      // count pair when it fired, else the oldest-age-in-days pair.
+      threshold: triggerByPendingCount ? reviewHintPendingCount : reviewHintPendingAgeDays,
+      actual_value: triggerByPendingCount ? stats.count : stats.oldestAgeMs / MS_PER_DAY,
     };
   }
 
@@ -869,6 +884,10 @@ function decide(events, now, pendingStats, underseedStats, editCounterStats, thr
       reason,
       signal: "import",
       recommended_skill: "fabric-import",
+      // v2.1 NEW-N-3: underseed corpus trigger — node-count vs threshold. The
+      // "import" signal collapses to schema signal_type "other" in main().
+      threshold: underseed.threshold,
+      actual_value: underseed.nodeCount,
     };
   }
 
@@ -979,8 +998,15 @@ function readShownCache(projectRoot) {
 function writeShownCache(projectRoot, cache) {
   const cachePath = join(projectRoot, SHOWN_CACHE_FILE);
   try {
-    mkdirSync(dirname(cachePath), { recursive: true });
-    writeFileSync(cachePath, JSON.stringify(cache));
+    // ISS-016: atomic tmp+rename so concurrent windows / a crash never leave a
+    // truncated shown-cache (this file is NOT session-scoped). Falls back to a
+    // plain write only if the shared lib failed to load.
+    if (stateStore && typeof stateStore.atomicWrite === "function") {
+      stateStore.atomicWrite(cachePath, JSON.stringify(cache));
+    } else {
+      mkdirSync(dirname(cachePath), { recursive: true });
+      writeFileSync(cachePath, JSON.stringify(cache));
+    }
   } catch {
     // Silent — cache failure must never block the hook.
   }
@@ -1117,8 +1143,13 @@ function readMaintenanceLastEmit(projectRoot) {
 function writeMaintenanceLastEmit(projectRoot, nowMs) {
   const p = join(projectRoot, MAINTENANCE_HINT_LAST_EMIT_FILE);
   try {
-    mkdirSync(dirname(p), { recursive: true });
-    writeFileSync(p, new Date(nowMs).toISOString());
+    // ISS-016: atomic tmp+rename (see writeShownCache).
+    if (stateStore && typeof stateStore.atomicWrite === "function") {
+      stateStore.atomicWrite(p, new Date(nowMs).toISOString());
+    } else {
+      mkdirSync(dirname(p), { recursive: true });
+      writeFileSync(p, new Date(nowMs).toISOString());
+    }
   } catch {
     // Silent — sidecar failure must never block the hook.
   }
@@ -1207,9 +1238,64 @@ function evaluateMaintenanceSignal(events, now, canonicalCount, lastEmitMs, thre
     signal: "maintenance",
     // CLI recommendation rather than Skill — doctor is a CLI surface.
     recommended_skill: null,
+    // v2.1 NEW-N-3: staleness trigger. threshold=days; actual=ageDays. When
+    // lint was NEVER run ageDays is null — main() skips the signal emit rather
+    // than fabricate a number (honest gap over fake telemetry).
+    threshold: days,
+    actual_value: ageDays,
   };
 }
 
+// v2.1 NEW-N-3 (ADJ-NEWN-3): hook_signal_emitted instrumentation. Writes ONE
+// best-effort ledger row at the point a nudge is actually delivered (post-
+// cooldown), so the join key measures nudge-trigger logic (which signal fired,
+// at what threshold vs. actual). Emitted at delivery rather than at
+// threshold-cross so it inherits the cooldown gate — a fired-but-cooled signal
+// does not spam the ledger every session. Skips silently when threshold /
+// actual_value are not finite numbers (e.g. maintenance "never run" → null
+// age). Never blocks the hook (KT-DEC-0007).
+const SIGNAL_TYPE_ENUM = new Set(["archive", "review", "maintenance", "other"]);
+function emitSignalFiredEvent(cwd, sessionId, result) {
+  try {
+    if (!result || typeof result.signal !== "string") return;
+    const threshold = result.threshold;
+    const actualValue = result.actual_value;
+    if (
+      typeof threshold !== "number" ||
+      !Number.isFinite(threshold) ||
+      typeof actualValue !== "number" ||
+      !Number.isFinite(actualValue)
+    ) {
+      return;
+    }
+    const fabricDir = join(cwd, FABRIC_DIR);
+    if (!existsSync(fabricDir)) return;
+    // "import" / any non-canonical signal collapses to schema's catch-all "other".
+    const signalType = SIGNAL_TYPE_ENUM.has(result.signal) ? result.signal : "other";
+    let idSuffix;
+    try {
+      idSuffix = require("node:crypto").randomUUID();
+    } catch {
+      idSuffix = `${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,
+      event_type: "hook_signal_emitted",
+      signal_type: signalType,
+      threshold,
+      actual_value: actualValue,
+      fired: true,
+    };
+    if (typeof sessionId === "string" && sessionId.length > 0) event.session_id = sessionId;
+    appendLockedLine(join(fabricDir, EVENT_LEDGER_FILE), JSON.stringify(event) + "\n");
+  } catch {
+    // best-effort telemetry — never block the hook
+  }
+}
+
 /**
  * v2.0.0-rc.7 T5: best-effort sync stdin reader for the Stop hook.
  *
@@ -1414,7 +1500,7 @@ function extractAndWriteAssistantTurnsBestEffort(cwd, stdinPayload) {
           timestamp: new Date().toISOString(),
         };
         if (client !== undefined) event.client = client;
-        appendFileSync(ledgerPath, JSON.stringify(event) + "\n", "utf8");
+        appendLockedLine(ledgerPath, JSON.stringify(event) + "\n");
       } catch {
         // Per-turn failure must not abort the remaining turns; the Stop hook
         // contract is "never block on hook failure". Best-effort continues.
@@ -1439,7 +1525,7 @@ function extractAndWriteAssistantTurnsBestEffort(cwd, stdinPayload) {
           counters: { [counterKey]: emptyShellCount },
         };
         const metricsPath = join(fabricDir, METRICS_LEDGER_FILE);
-        appendFileSync(metricsPath, JSON.stringify(metricsRow) + "\n", "utf8");
+        appendLockedLine(metricsPath, JSON.stringify(metricsRow) + "\n");
       } catch {
         // metrics fold is observability-only; never block the hook on failure.
       }
@@ -1951,6 +2037,9 @@ function main(env, stdio) {
     // see MAINTENANCE_HINT_LAST_EMIT_FILE). The A/B/C shared cooldown cache
     // uses hours, so we branch here to avoid mixing semantics.
     if (result.signal === "maintenance") {
+      emitSignalFiredEvent(cwd, sessionId, result);
+      delete result.threshold;
+      delete result.actual_value;
       out.write(JSON.stringify(result));
       writeMaintenanceLastEmit(cwd, nowMs);
       return;
@@ -1972,6 +2061,9 @@ function main(env, stdio) {
       return; // Still in cooldown — silent.
     }
 
+    emitSignalFiredEvent(cwd, sessionId, result);
+    delete result.threshold;
+    delete result.actual_value;
     out.write(JSON.stringify(result));
     cache[result.signal] = nowMs;
     writeShownCache(cwd, cache);

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

@@ -22,7 +22,7 @@
  *         - <id> · <summary>
  *       ...
  *     revision_hash: <hash>
- *     Use `fab_get_knowledge_sections` to fetch full content.
+ *     Load full content: `fab_recall(paths)`, or `fab_plan_context` -> `fab_get_knowledge_sections` to trim first.
  *
  *   When narrow count > 30 (grouped-truncation mode, per type):
  *     [fabric] Session start — N broad-scoped knowledge entries available (truncated):
@@ -33,7 +33,7 @@
  *       [decision] draft: 7 entries
  *       ...
  *     revision_hash: <hash>
- *     Use `fab_get_knowledge_sections` to fetch full content.
+ *     Load full content: `fab_recall(paths)`, or `fab_plan_context` -> `fab_get_knowledge_sections` to trim first.
  *
  *   When 0 entries / CLI unavailable / CLI error / parse failure:
  *     (no output — silent exit 0)
@@ -50,6 +50,12 @@ 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
@@ -63,11 +69,12 @@ 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");
+const { isClaudeCode, detectClient } = require("./lib/client-adapter.cjs");
 // 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,6 +84,15 @@ 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
@@ -349,6 +365,65 @@ const CLI_TIMEOUT_MS = 2000;
 // `hint_summary_max_len` in fabric-config overrides this default (range 40..240).
 const DEFAULT_SUMMARY_MAX_LEN = 80;
 
+// v2.2 HK2-degrade (W2-T2): char budget for the rendered broad-menu BODY. The
+// hook already degrades by COUNT (hint_broad_top_k slice + TRUNCATION_THRESHOLD
+// grouped mode), but nothing bounded the total rendered SIZE — a corpus with
+// many types or long (near-maxLen) summaries could still emit a wall of text
+// that displaces the agent's working memory. Borrowing the maestro
+// context-budget idea, this is the final rung of the degradation ladder: once
+// the body exceeds the budget, the tail collapses to a single "N more omitted"
+// marker. Default 2000 chars ≈ one screenful. Overridable via
+// fabric-config.json#hint_broad_budget_chars (range 200..20000); 0 disables.
+const DEFAULT_HINT_BROAD_BUDGET_CHARS = 2000;
+
+// v2.2 C5-budget (W2-T3): bind the injection char budget to the layered retrieval
+// budget profile. Mirrors the injectionChars column of shared/retrieval-budget.ts
+// PROFILES (kept in sync — the hook cannot require the TS resolver). The explicit
+// `hint_broad_budget_chars` knob still wins; the profile only supplies the
+// default. `balanced` (and an absent/unknown profile) keeps the historical 2000.
+const RETRIEVAL_BUDGET_INJECTION_CHARS = {
+  conservative: 1000,
+  balanced: 2000,
+  generous: 4000,
+};
+
+function readBroadBudgetChars(projectRoot) {
+  const profile = readConfigString(projectRoot, "retrieval_budget_profile", "balanced");
+  const profileDefault =
+    RETRIEVAL_BUDGET_INJECTION_CHARS[profile] ?? DEFAULT_HINT_BROAD_BUDGET_CHARS;
+  return readConfigNumber(projectRoot, "hint_broad_budget_chars", profileDefault, {
+    min: 0,
+    max: 20000,
+    floor: true,
+  });
+}
+
+// v2.2 HK2-degrade (W2-T2): cap the rendered body to `budgetChars`, collapsing
+// the overflow tail into one marker line. Structural lines (banner, revision_hash,
+// footer) are appended by renderSummary AFTER this pass, so they always survive —
+// only entry/group body lines are subject to the budget. `budgetChars` of 0 or
+// undefined is a no-op (preserves the pre-HK2 unbounded behavior and all
+// existing snapshot tests).
+function capBodyToBudget(body, budgetChars) {
+  if (!budgetChars || budgetChars <= 0) return body;
+  const kept = [];
+  let total = 0;
+  for (let i = 0; i < body.length; i += 1) {
+    const line = body[i];
+    // +1 for the newline each line costs once joined.
+    if (kept.length > 0 && total + line.length + 1 > budgetChars) {
+      const remaining = body.length - i;
+      kept.push(
+        `  … ${remaining} more entr${remaining === 1 ? "y" : "ies"} omitted (injection budget ${budgetChars} chars; raise hint_broad_budget_chars or narrow scope)`,
+      );
+      return kept;
+    }
+    kept.push(line);
+    total += line.length + 1;
+  }
+  return kept;
+}
+
 function readSummaryMaxLen(projectRoot) {
   return readConfigNumber(projectRoot, "hint_summary_max_len", DEFAULT_SUMMARY_MAX_LEN, {
     min: 40,
@@ -587,7 +662,7 @@ function renderTruncated(narrow, maxLen) {
  * after writing exactly one stderr breadcrumb so operators grepping a stuck-
  * banner report can diagnose the version drift without source-diving.
  */
-function renderSummary(payload, maxLen) {
+function renderSummary(payload, maxLen, budgetChars) {
   if (!payload || payload.version !== 2) {
     if (payload && payload.version !== undefined) {
       try {
@@ -610,7 +685,9 @@ 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:`;
 
-  const body = truncated ? renderTruncated(entries, maxLen) : renderFull(entries, maxLen);
+  const renderedBody = truncated ? renderTruncated(entries, maxLen) : renderFull(entries, maxLen);
+  // v2.2 HK2-degrade (W2-T2): final budget rung — cap the body's rendered size.
+  const body = capBodyToBudget(renderedBody, budgetChars);
 
   const lines = [banner, ...body];
   const revHash = typeof payload.revision_hash === "string" ? payload.revision_hash : null;
@@ -657,7 +734,18 @@ function renderSummary(payload, maxLen) {
     }
   }
 
-  lines.push("  Use `fab_get_knowledge_sections` to fetch full content.");
+  // v2.2 MC3-fix-guidance (W1-T5): unify the footer with the canonical recall
+  // flow. The prior text ("Use `fab_get_knowledge_sections` to fetch full
+  // content.") told the agent to call a tool that REQUIRES a selection_token it
+  // does not yet have — directly contradicting the bilingual next-step nudge
+  // (and AGENTS.md) which leads with `fab_recall`. Footer now states the same
+  // two-path model: single-step `fab_recall`, or `fab_plan_context` →
+  // `fab_get_knowledge_sections` when the bodies must be trimmed first. Keeps
+  // the `fab_get_knowledge_sections` token (downstream substring contracts) but
+  // sequences it correctly behind the token-issuing `fab_plan_context`.
+  lines.push(
+    "  Load full content: `fab_recall(paths)` (one step), or `fab_plan_context` → `fab_get_knowledge_sections` to trim first.",
+  );
   return lines;
 }
 
@@ -744,7 +832,9 @@ function main(env, stdio) {
     // 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.2 HK2-degrade (W2-T2): thread the injection char-budget into the renderer.
+    const broadBudgetChars = readBroadBudgetChars(cwd);
+    const lines = renderSummary(resolvedPayload, summaryMaxLen, broadBudgetChars);
 
     // v2.0.0-rc.37 NEW-23: resolve fabric_language ONCE per emit path —
     // shared between the (existing) broadImportBanner branch and the new
@@ -779,10 +869,13 @@ function main(env, stdio) {
     // 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.
+    // v2.2 W1-REVIEW codex LOW-6: `description_index` was renamed to `candidates`
+    // in rc.38 UX-1; the nudge now uses the current field name so the guidance
+    // matches the actual MCP response shape.
     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.";
+        ? "下一步: 调 fab_recall(paths) 拿 KB 相关条目;或调 fab_plan_context 先看候选描述(candidates)。"
+        : "Next: call fab_recall(paths) to fetch related KB entries, or fab_plan_context to preview the candidate descriptions first.";
     lines.push(nextStepNudge);
 
     // Stderr: always emit (human-facing breadcrumb + legacy contract).
@@ -790,6 +883,26 @@ function main(env, stdio) {
       err.write(`${line}\n`);
     }
 
+    // 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,
+      });
+    }
+
     // 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
@@ -822,6 +935,48 @@ function main(env, stdio) {
       }
     }
 
+    // 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/cursor.
+    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)}`;
+        }
+        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",
+        };
+        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
     // cooldown gate's next-invocation check. Skip when cooldown is disabled
     // (cooldownHours === 0) to avoid polluting the FS with a never-read

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

@@ -66,7 +66,6 @@
 const { spawnSync } = require("node:child_process");
 const { createHash, randomUUID } = require("node:crypto");
 const {
-  appendFileSync,
   existsSync,
   mkdirSync,
   readFileSync,
@@ -85,6 +84,13 @@ const { resolveOpaqueSummaries } = require("./lib/summary-fallback.cjs");
 // cache (skips a redundant CLI cold-start spawn when the same path-set is
 // re-edited within a session and the knowledge graph hasn't changed).
 const { readJsonState, writeJsonState } = require("./lib/state-store.cjs");
+// W1-01 (ISS-011): the PreToolUse hook is the highest-frequency, most
+// concurrency-exposed write surface in Fabric. Multi-window edits spawn
+// concurrent hook processes that all append to the SAME non-session-scoped
+// ledger/counter files; a bare appendFileSync can interleave a partial write
+// and corrupt a line. Route every shared-file append through the advisory-lock
+// primitive (drop-on-contention, best-effort — matches injection-log).
+const { appendLockedLine } = require("./lib/injection-log.cjs");
 // v2.1.0-rc.1 P4 (F4/S63): hook-side reader for the CLI pre-generated
 // resolved-bindings snapshot. Store-aware hint surfaces the write-target store
 // for the edited file WITHOUT re-resolving or walking store trees. Best-effort.
@@ -427,7 +433,7 @@ function appendEditIntentToLedger(projectRoot, now, paths, toolName, sessionId)
         window_ms: 0,
       }))
       .join("\n") + "\n";
-    appendFileSync(join(fabricDir, EVENTS_LEDGER_FILE), lines, "utf8");
+    appendLockedLine(join(fabricDir, EVENTS_LEDGER_FILE), lines);
   } catch {
     // Silent — events ledger failure must never block the edit.
   }
@@ -471,7 +477,7 @@ function appendEditCounter(projectRoot, now, paths) {
           .filter((p) => typeof p === "string" && p.length > 0)
       : [];
     const line = JSON.stringify({ ts: iso, paths: pathList });
-    appendFileSync(file, `${line}\n`, "utf8");
+    appendLockedLine(file, `${line}\n`);
   } catch {
     // Silent — sidecar failure must never block the edit.
   }
@@ -501,7 +507,7 @@ function appendHintSilenceCounter(projectRoot, now) {
       mkdirSync(dir, { recursive: true });
     }
     const iso = now instanceof Date ? now.toISOString() : new Date(now).toISOString();
-    appendFileSync(file, `${iso}\n`, "utf8");
+    appendLockedLine(file, `${iso}\n`);
   } catch {
     // Silent — sidecar failure must never block the edit.
   }

package/templates/hooks/lib/injection-log.cjs

@@ -0,0 +1,91 @@
+// v2.2 HK3-telemetry (W3-T1): injection-side telemetry. `.fabric/metrics.jsonl`
+// (server) records the CONSUMPTION side — which knowledge the agent actually
+// fetched/consumed. But nothing recorded the INJECTION side — which knowledge a
+// hook OFFERED the agent at SessionStart / PreToolUse. Without that denominator
+// the "true hit rate" (consumed ÷ injected) cannot be computed: a high consume
+// count tells you nothing if the hook injected ten times as many entries.
+//
+// This lib appends one row per injection to `.fabric/injections.jsonl`:
+//   { ts, surface: "broad"|"narrow", count, stable_ids: [...], revision_hash }
+//
+// Best-effort + synchronous: hooks are short-lived processes, so a sync append
+// is simpler than threading async, and ANY failure is swallowed — telemetry
+// must never break or delay the hook (failure invariant: silent). Concurrent
+// writers from multiple windows are serialized with an advisory lock (see
+// appendLockedLine below) so a contended write can't corrupt a line.
+
+const { appendFileSync, mkdirSync, openSync, closeSync, statSync, rmSync } = require("node:fs");
+const { join, dirname } = require("node:path");
+
+// Multi-window concurrency guard (ADJ-W3-INJECTION-CONCURRENCY): the same repo
+// is frequently edited from several client sessions at once, so multiple hook
+// processes can append to injections.jsonl simultaneously. A bare appendFileSync
+// can interleave a partial write under contention and corrupt a line. We guard
+// each append with an advisory lock file created atomically via O_EXCL ("wx"):
+//   - acquired  → write the row, then release the lock
+//   - contended → DROP this row. Telemetry is best-effort; a missing row only
+//                 shrinks the denominator slightly, and dropping is what keeps
+//                 the ledger from ever being corrupted by an interleave.
+//   - stale     → a holder that crashed leaves the lock behind; reclaim it once
+//                 past STALE_LOCK_MS so contention can't wedge forever.
+const STALE_LOCK_MS = 5000;
+
+function appendLockedLine(path, line) {
+  const lockPath = `${path}.lock`;
+  let fd;
+  try {
+    fd = openSync(lockPath, "wx"); // atomic create-exclusive = acquire
+  } catch (err) {
+    if (!err || err.code !== "EEXIST") return; // unexpected → drop (best-effort)
+    try {
+      if (Date.now() - statSync(lockPath).mtimeMs <= STALE_LOCK_MS) return; // fresh holder → drop
+      rmSync(lockPath, { force: true }); // stale holder crashed → reclaim
+      fd = openSync(lockPath, "wx");
+    } catch {
+      return; // racing another reclaimer → drop
+    }
+  }
+  try {
+    closeSync(fd);
+    appendFileSync(path, line);
+  } finally {
+    try {
+      rmSync(lockPath, { force: true });
+    } catch {
+      /* lock already released */
+    }
+  }
+}
+
+/**
+ * Append one injection record to `<projectRoot>/.fabric/injections.jsonl`.
+ *
+ * @param {string} projectRoot
+ * @param {{ surface: "broad"|"narrow", stableIds?: string[], count?: number, revisionHash?: string|null, ts?: number }} record
+ */
+function logInjection(projectRoot, record) {
+  try {
+    if (!projectRoot || !record || typeof record.surface !== "string") {
+      return;
+    }
+    const stableIds = Array.isArray(record.stableIds) ? record.stableIds.filter((id) => typeof id === "string") : [];
+    const count = typeof record.count === "number" ? record.count : stableIds.length;
+    if (count <= 0) {
+      return; // nothing injected → no row (keeps the denominator honest)
+    }
+    const row = {
+      ts: typeof record.ts === "number" ? record.ts : Date.now(),
+      surface: record.surface,
+      count,
+      stable_ids: stableIds,
+      revision_hash: typeof record.revisionHash === "string" ? record.revisionHash : null,
+    };
+    const path = join(projectRoot, ".fabric", "injections.jsonl");
+    mkdirSync(dirname(path), { recursive: true });
+    appendLockedLine(path, `${JSON.stringify(row)}\n`);
+  } catch {
+    // Telemetry is best-effort — never crash or delay the hook.
+  }
+}
+
+module.exports = { logInjection, appendLockedLine };