@fenglimg/fabric-cli 2.0.1 → 2.2.0-rc.1

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;
@@ -81,6 +87,27 @@ try {
   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.
@@ -762,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,
     };
   }
 
@@ -798,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,
     };
   }
 
@@ -848,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,
     };
   }
 
@@ -958,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.
   }
@@ -1096,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.
   }
@@ -1186,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.
  *
@@ -1393,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.
@@ -1418,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.
       }
@@ -1907,10 +2014,32 @@ function main(env, stdio) {
       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.
     if (result.signal === "maintenance") {
+      emitSignalFiredEvent(cwd, sessionId, result);
+      delete result.threshold;
+      delete result.actual_value;
       out.write(JSON.stringify(result));
       writeMaintenanceLastEmit(cwd, nowMs);
       return;
@@ -1932,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,43 @@ 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.
+let bindingsSnapshotReader = null;
+try {
+  bindingsSnapshotReader = require("./lib/bindings-snapshot-reader.cjs");
+} 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) {
+  try {
+    const raw = readFileSync(join(cwd, ".fabric", "fabric-config.json"), "utf8");
+    const parsed = JSON.parse(raw);
+    return typeof parsed.project_id === "string" ? parsed.project_id : null;
+  } catch {
+    return null;
+  }
+}
 
 // -----------------------------------------------------------------------------
 // rc.12: SessionStart broad-menu is now unconditionally emitted on every
@@ -327,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,
@@ -565,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 {
@@ -588,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;
@@ -635,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;
 }
 
@@ -722,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
@@ -735,14 +847,35 @@ function main(env, stdio) {
 
     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);
+        }
+      } 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.
+    // 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).
@@ -750,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
@@ -782,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,33 @@ 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.
+let bindingsSnapshotReader = null;
+try {
+  bindingsSnapshotReader = require("./lib/bindings-snapshot-reader.cjs");
+} catch {
+  // Lib missing (old install) — store labels degrade to silent absence.
+}
+
+// Read the project's own `project_id` (the snapshot key) from its config. Not a
+// store-tree read — it is how the hook learns which snapshot to fetch.
+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
@@ -407,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.
   }
@@ -451,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.
   }
@@ -481,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.
   }
@@ -1466,6 +1492,25 @@ function main(env, stdio) {
     const lines = renderSummary({ ...cliPayload, entries: resolvedEntries }, summaryMaxLen);
     if (lines.length === 0) return;
 
+    // v2.1.0-rc.1 P4 (F4/S63): store-aware hint — append the write-target store
+    // so the edit-time hint says WHERE a derived knowledge entry would land.
+    // Best-effort; missing snapshot / single-store setup omits the line.
+    if (bindingsSnapshotReader !== null) {
+      try {
+        const projectId = readProjectId(cwd);
+        if (projectId) {
+          const snapshot = bindingsSnapshotReader.readBindingsSnapshot(projectId);
+          const writeAlias =
+            snapshot && snapshot.write_target && snapshot.write_target.alias;
+          if (writeAlias) {
+            lines.push(`[fabric] writes here land in store '${writeAlias}'`);
+          }
+        }
+      } catch {
+        // store label is decorative provenance — never crash the hook
+      }
+    }
+
     // Stderr: human-facing breadcrumb + legacy contract.
     for (const line of lines) {
       err.write(`${line}\n`);