fix(pull): warn loudly when disk-form hash fallback fires; docs/cosmetic polish

Address B1 (single action item) from the 3-commit follow-up code review:

When `hashLocalResource` returns null after a successful writeResourceFile
(e.g. broken file extension, race with rm, parseResourceDataFromFile throw),
the silent fallback to `hashPayload(withCredNames)` reintroduces the exact
M1 in-memory-vs-disk asymmetry that commit f296173 fixed \u2014 with NO log line
for the next operator to find. They'd see phantom drift on the next pull
and have no breadcrumb explaining why.

Fix: capture diskHash separately, emit a `\u26a0\ufe0f` console.warn pointing at the
specific resource when the fallback fires, then use the same nullish-coalesce.
Bootstrap mode (no file written) is correctly excluded from the warning since
the fallback there is expected.

Also bundling 2 cosmetic nits from the same review:

- A1: canonicalizeForHash JSDoc said pipeline mismatches make `lastPulledHash`
  disagree with the next read's `localHash`. The audit never writes
  lastPulledHash \u2014 it reads it. Correct framing is platformHash recomputation
  disagreeing with the stored lastPulledHash from a prior pull.

- C2: summarizeFindings rendered '1 info' next to '1 error(s)' / '1 warning(s)'
  \u2014 inconsistent pluralization. Updated to '1 info finding(s)' for symmetry.
  Adjacent test assertion updated.

Defer to follow-ups (non-blocking):
  - B2 bootstrap + manually-placed files edge case (narrow audience)
  - B3 perf measurement on 1000+-resource customers
  - C1 --no-info flag (monitor; add if customer complaints surface)
  - D1 split end-of-pull legend into 'skip reasons' + 'write outcomes'

Tests: 266/266 green; tsc --noEmit clean.

Author: dhruva-vapi

src/audit.ts

@@ -565,6 +565,6 @@ export function summarizeFindings(findings: AuditFinding[]): string {
   const warns = findings.filter((f) => f.severity === "warn").length;
   const infos = findings.filter((f) => f.severity === "info").length;
   const parts = [`${errors} error(s)`, `${warns} warning(s)`];
-  if (infos > 0) parts.push(`${infos} info`);
+  if (infos > 0) parts.push(`${infos} info finding(s)`);
   return `📋 Audit: ${findings.length} finding(s) — ${parts.join(", ")}`;
 }

src/pull.ts

@@ -516,9 +516,9 @@ export function resolveReferencesToResourceIds(
  * ALL hash sites MUST use this helper. The classifier (pull.ts), the audit
  * (audit.ts/checkContentDrift), and the pull-write fallback all need the
  * same transformation applied in the same order — any divergence (a missing
- * step, a different mutation order) makes the resulting `lastPulledHash`
- * disagree with the next read's `localHash`, producing permanent phantom
- * `both-diverged` reports that only `--overwrite` can clear.
+ * step, a different mutation order) makes the recomputed `platformHash`
+ * disagree with the stored `lastPulledHash` from a prior pull, producing
+ * permanent phantom `both-diverged` reports that only `--overwrite` can clear.
  *
  * Note: this is the *pre-write* canonical form (in-memory). At write sites,
  * `lastPulledHash` should still be sourced from `hashLocalResource(...)` after
@@ -1018,11 +1018,20 @@ export async function pullResourceType(
     // code review on the drift-direction-classifier PR.
     //
     // Bootstrap mode writes no file; fall back to the in-memory canonical form.
+    // Warn loudly when the disk-form hash fails on a written file — silent
+    // fallback would reintroduce the M1 asymmetry with no diagnostic for the
+    // next operator to find.
+    const diskHash = bootstrap
+      ? null
+      : hashLocalResource(resourceType, resourceId);
+    if (!bootstrap && diskHash === null) {
+      console.warn(
+        `   ⚠️  ${resourceType}/${resourceId}: failed to hash post-write disk form; falling back to in-memory hash (may produce phantom drift on next pull)`,
+      );
+    }
     upsertState(newStateSection, resourceId, {
       uuid: resource.id,
-      lastPulledHash:
-        hashLocalResource(resourceType, resourceId) ??
-        hashPayload(withCredNames),
+      lastPulledHash: diskHash ?? hashPayload(withCredNames),
       lastPulledAt: new Date().toISOString(),
     });
   }
@@ -1110,11 +1119,15 @@ async function resolveBothDivergedResources(options: {
       `   ⬇️  ${entry.resourceId} (both diverged — resolving with --resolve=theirs, overwriting local with platform) ${formatDriftLabel("both-diverged")}`,
     );
     // Hash the post-write disk form (same invariant as the normal pull-write path).
+    const diskHash = hashLocalResource(entry.resourceType, entry.resourceId);
+    if (diskHash === null) {
+      console.warn(
+        `   ⚠️  ${entry.resourceType}/${entry.resourceId}: failed to hash post-write disk form; falling back to in-memory hash (may produce phantom drift on next pull)`,
+      );
+    }
     upsertState(section, entry.resourceId, {
       uuid: entry.resource.id,
-      lastPulledHash:
-        hashLocalResource(entry.resourceType, entry.resourceId) ??
-        hashPayload(withCredNames),
+      lastPulledHash: diskHash ?? hashPayload(withCredNames),
       lastPulledAt: new Date().toISOString(),
     });
   }

tests/audit.test.ts

@@ -588,7 +588,7 @@ test("summarizeFindings: info-severity count appears in the summary line when pr
   ];
   const out = summarizeFindings(findings);
   assert.match(out, /1 warning/);
-  assert.match(out, /1 info/);
+  assert.match(out, /1 info finding/);
   assert.match(out, /2 finding/);
 });