@skillcap/gdh 0.26.2 → 0.26.4

package/node_modules/@gdh/adapters/dist/templates/authoring-hook.js.tpl

@@ -4,9 +4,18 @@
 const PINNED_VERSION = {{pinnedVersionJson}};
 const TARGET_RELATIVE_PATH = {{targetRelativePathJson}};
 const AGENT = {{agentJson}};
+// POSIX-normalised relative path from this hook script's directory (__dirname)
+// to the integration root's `.gdh-state/` directory. Baked at install-plan time
+// from `path.relative(hookDirAbsolute, path.join(integrationRootAbsolute, ".gdh-state"))`.
+// The embedded broker-snapshot reader (Task 2) resolves
+// `path.resolve(__dirname, STATE_RELATIVE_PATH_FROM_HOOK)` to find
+// `authoring/lsp-instance.json` and `authoring/diagnostics-broker/snapshot.json`.
+const STATE_RELATIVE_PATH_FROM_HOOK = {{stateRelativePathFromHookJson}};
 
 const fs = require('fs');
 const path = require('path');
+const crypto = require('crypto');
+const { pathToFileURL } = require('url');
 const { spawnSync } = require('child_process');
 
 const AUTHORING_EXTENSIONS = new Set(['.gd', '.tscn', '.tres']);
@@ -43,38 +52,44 @@ function handlePostEdit(input, targetRoot) {
   const changed = collectChangedFiles(input, targetRoot);
   const authoring = changed.filter(isAuthoringValidationPath);
   if (authoring.length === 0) return allow();
-  // Phase 82 / LSP-02: fire-and-forget warmup BEFORE the bounded check. The verb
-  // is idempotent (lsp.lock single-attempt; in-flight warmups return "warming"
-  // without re-spawning) so spamming on every edit is safe. Hook still returns
-  // within CHECK_TIMEOUT_MS regardless of warmup outcome (Pitfall 1: detached +
-  // stdio:'ignore' + .unref() means the parent never blocks on the child).
-  spawnDetachedWarmup(targetRoot);
-  const changedArgs = authoring.flatMap((file) => ['--changed', file]);
-  // Run one compact fast check. Post-edit checks reuse a running LSP if present,
-  // trust only content-matched broker diagnostics, and avoid cold Godot startup.
-  const result = runGdh(targetRoot, ['authoring', 'check', '--target', targetRoot, '--mode', 'post-edit', '--format', 'compact', ...changedArgs], {
-    timeoutMs: CHECK_TIMEOUT_MS,
-  });
-  if (result.timedOut) {
-    return context(`GDH post-edit authoring check timed out after ${CHECK_TIMEOUT_MS}ms; continuing without blocking. Run \`gdh authoring check --mode final\` before claiming code-validity.`);
+  // Phase 82 / LSP-02: fire-and-forget scoped diagnostics refresh BEFORE the
+  // bounded read. The verb calls `refreshAuthoringDiagnostics` which boots
+  // Godot LSP if needed, opens scoped files via LSP, drains diagnostics, and
+  // writes `diagnostics-broker/snapshot.json` + `primed` marker. Hook still
+  // returns within CHECK_TIMEOUT_MS regardless of refresh outcome (Pitfall 1:
+  // detached + stdio:'ignore' + .unref() means the parent never blocks on
+  // the child).
+  spawnDetachedRefresh(targetRoot, authoring);
+  // Quick task 260504-ix2: embedded broker-snapshot reader. Replaces the
+  // per-edit synchronous `npx -y @skillcap/gdh@PINNED authoring check ...`
+  // shellout (which was eating the full `CHECK_TIMEOUT_MS` budget on the npx
+  // bootstrap path even before any GDH code ran). The reader synthesises the
+  // same `[fresh]` / `[stale]` / `[pending]` bracketed-token vocabulary the
+  // existing dispatch already consumes, so the regex ladder below is unchanged.
+  let output;
+  try {
+    output = runEmbeddedDiagnosticsRead(targetRoot, authoring);
+  } catch (_err) {
+    return context('GDH post-edit hook embedded read threw; continuing without blocking. Run `gdh authoring check --mode final` before claiming code-validity.');
   }
   // Phase 81 / LSP-06 / D-01: dispatch on bracketed-token vocabulary.
   // Pitfall 5: anchor regex to line-start with /m flag so per-diagnostic
   // [error]/[warning]/[info] severity brackets do not match the status token.
-  if (/^\[failed\]/m.test(result.output) || /^\[partial\]/m.test(result.output)) {
-    return block(formatBlockingReason(result.output));
+  // The embedded reader does not currently emit `[failed]` / `[partial]` /
+  // `[timeout]` (those statuses come from the legacy CLI compact formatter),
+  // but the dispatch retains them as forward-compat branches in case a future
+  // reader extension surfaces them.
+  if (/^\[failed\]/m.test(output) || /^\[partial\]/m.test(output)) {
+    return block(formatBlockingReason(output));
   }
-  if (/^\[fresh\]/m.test(result.output)) {
+  if (/^\[fresh\]/m.test(output)) {
     return allow();
   }
-  if (/^\[pending\]/m.test(result.output) || /^\[stale\]/m.test(result.output)) {
-    return context(`GDH post-edit authoring check could not prove this edit quickly; continuing without blocking. ${compactOneLine(result.output || 'Run final authoring validation before claiming code-validity.')}`);
-  }
-  if (/^\[timeout\]/m.test(result.output)) {
-    return context(`GDH post-edit authoring check returned a timeout status; continuing without blocking. ${compactOneLine(result.output || 'Run final authoring validation before claiming code-validity.')}`);
+  if (/^\[pending\]/m.test(output) || /^\[stale\]/m.test(output)) {
+    return context(`GDH post-edit authoring check could not prove this edit quickly; continuing without blocking. ${compactOneLine(output || 'Run final authoring validation before claiming code-validity.')} ${reasonHint(output, targetRoot)}`);
   }
-  if (!result.ok) {
-    return context(`GDH post-edit authoring check failed before producing diagnostics; continuing without blocking. ${compactOneLine(result.error || result.output || 'Run final authoring validation before claiming code-validity.')}`);
+  if (/^\[timeout\]/m.test(output)) {
+    return context(`GDH post-edit authoring check returned a timeout status; continuing without blocking. ${compactOneLine(output || 'Run final authoring validation before claiming code-validity.')} ${reasonHint(output, targetRoot)}`);
   }
   return allow();
 }
@@ -117,78 +132,80 @@ function handlePostToolBatch(input, targetRoot) {
   const authoring = unique(files).filter(isAuthoringValidationPath);
   if (authoring.length === 0) return allow();  // Pitfall 2: no authoring files — no work
 
-  // SC2: spawnDetachedWarmup reuses Phase 82's lsp.lock-serialized helper. If a
-  // per-edit warmup is already in flight when this fires, the lock primitive
-  // returns warming without spawning a second Godot.
-  spawnDetachedWarmup(targetRoot);
-
-  const changedArgs = authoring.flatMap((file) => ['--changed', file]);
-  // SC1: ONE coalesced check, not N. Same runGdh envelope as handlePostEdit —
-  // do NOT introduce a parallel CLI path.
-  const result = runGdh(
-    targetRoot,
-    ['authoring', 'check', '--target', targetRoot, '--mode', 'post-edit', '--format', 'compact', ...changedArgs],
-    { timeoutMs: CHECK_TIMEOUT_MS },
-  );
+  // SC2: spawnDetachedRefresh reuses the lsp.lock-serialized helper. If a
+  // per-edit refresh is already in flight when this fires, the broker side
+  // serializes via the lock primitive — no double-spawn of Godot.
+  spawnDetachedRefresh(targetRoot, authoring);
 
-  if (result.timedOut) {
-    return context(`GDH PostToolBatch authoring check timed out after ${CHECK_TIMEOUT_MS}ms; continuing without blocking. Run \`gdh authoring check --mode final\` before claiming code-validity.`);
+  // Quick task 260504-ix2: embedded broker-snapshot reader replaces the
+  // synchronous `npx ... authoring check` shellout. The reader is invoked
+  // ONCE with the full deduplicated authoring set — the LSP-09 coalescing
+  // invariant is preserved: the loop in `runEmbeddedDiagnosticsRead` walks
+  // every file but returns on the first non-fresh status (first-failure-wins
+  // is the documented contract; a [stale] in any one file routes the batch
+  // through the drift dispatch branch).
+  let output;
+  try {
+    output = runEmbeddedDiagnosticsRead(targetRoot, authoring);
+  } catch (_err) {
+    return context('GDH PostToolBatch hook embedded read threw; continuing without blocking. Run `gdh authoring check --mode final` before claiming code-validity.');
   }
+
   // Bracketed-token dispatch — IDENTICAL to handlePostEdit. Pitfall 5 from Phase 81
   // applies: anchor regex with /^.../m so per-diagnostic [error]/[warning]/[info]
-  // severity brackets do not match the line-leading status token.
-  if (/^\[failed\]/m.test(result.output) || /^\[partial\]/m.test(result.output)) {
-    return block(formatBlockingReason(result.output));
+  // severity brackets do not match the line-leading status token. Forward-compat
+  // [partial] / [timeout] branches retained per quick-task 260504-ix2 plan note.
+  if (/^\[failed\]/m.test(output) || /^\[partial\]/m.test(output)) {
+    return block(formatBlockingReason(output));
   }
-  if (/^\[fresh\]/m.test(result.output)) {
+  if (/^\[fresh\]/m.test(output)) {
     return allow();
   }
-  if (/^\[pending\]/m.test(result.output) || /^\[stale\]/m.test(result.output)) {
-    return context(`GDH PostToolBatch authoring check could not prove this batch quickly; continuing without blocking. ${compactOneLine(result.output || 'Run final authoring validation before claiming code-validity.')}`);
-  }
-  if (/^\[timeout\]/m.test(result.output)) {
-    return context(`GDH PostToolBatch authoring check returned a timeout status; continuing without blocking. ${compactOneLine(result.output || 'Run final authoring validation before claiming code-validity.')}`);
+  if (/^\[pending\]/m.test(output) || /^\[stale\]/m.test(output)) {
+    return context(`GDH PostToolBatch authoring check could not prove this batch quickly; continuing without blocking. ${compactOneLine(output || 'Run final authoring validation before claiming code-validity.')} ${reasonHint(output, targetRoot)}`);
   }
-  if (!result.ok) {
-    return context(`GDH PostToolBatch authoring check failed before producing diagnostics; continuing without blocking. ${compactOneLine(result.error || result.output || 'Run final authoring validation before claiming code-validity.')}`);
+  if (/^\[timeout\]/m.test(output)) {
+    return context(`GDH PostToolBatch authoring check returned a timeout status; continuing without blocking. ${compactOneLine(output || 'Run final authoring validation before claiming code-validity.')} ${reasonHint(output, targetRoot)}`);
   }
   return allow();
 }
 
-function runGdh(targetRoot, args, options = {}) {
-  const result = spawnSync('npx', ['-y', `@skillcap/gdh@${PINNED_VERSION}`, ...args], {
-    cwd: targetRoot,
-    encoding: 'utf8',
-    windowsHide: true,
-    timeout: options.timeoutMs || CHECK_TIMEOUT_MS,
-  });
-  const output = `${result.stdout || ''}${result.stderr || ''}`.trim();
-  const error = result.error ? String(result.error.message || result.error) : '';
-  return {
-    ok: result.status === 0 && !result.error,
-    output,
-    error,
-    timedOut: Boolean(
-      (result.error && result.error.code === 'ETIMEDOUT') ||
-      result.signal === 'SIGTERM'
-    ),
-  };
-}
+// Quick task 260504-ix2: `runGdh` deleted. The function previously wrapped
+// `spawnSync('npx', ['-y', '@skillcap/gdh@PINNED', ...args])` for the three
+// event handlers (handlePostEdit, handlePostToolBatch, handleStop). All three
+// now call `runEmbeddedDiagnosticsRead` instead. `spawnDetachedRefresh` uses
+// `child_process.spawn` directly (always did — it was never a `runGdh`
+// caller), so removing the helper has no effect on the refresh path.
+// Quick task 260504-o6w renamed `spawnDetachedWarmup` → `spawnDetachedRefresh`
+// and switched the spawn argv from `lsp warmup` to `authoring diagnostics
+// refresh --changed`. Detached spawn still uses `child_process.spawn` directly
+// (always did).
 
-// Phase 82 / LSP-02. Fire-and-forget warmup spawn from the post-edit hook. The
-// hook returns within CHECK_TIMEOUT_MS regardless of whether warmup has finished
-// — Godot startup typically takes 2-5 s, much longer than the 2500 ms cap.
+// Quick task 260504-o6w. Fire-and-forget scoped diagnostics refresh from the
+// post-edit hook. The CLI verb calls `refreshAuthoringDiagnostics` which boots
+// Godot LSP if needed, opens scoped files via LSP, drains diagnostics, and
+// writes `diagnostics-broker/snapshot.json` + `primed` marker — so this single
+// fire-and-forget call covers BOTH warmup and broker priming. The previous
+// `lsp warmup` argv only wrote `lsp-instance.json` and left the broker empty,
+// leaving the embedded reader stuck on `[pending] broker_not_yet_primed`
+// indefinitely (verified live on TheBeacon, 2026-05-04 dogfooding session 14).
 //
 // All three options are required (Pitfall 1):
 //   - detached: true       — child gets its own process group, survives parent exit
 //   - stdio: 'ignore'      — no fds tether the child to the parent's lifecycle
 //   - windowsHide: true    — prevents a console flash on Windows
 // .unref() is required so the Node event loop does not wait on the child.
-function spawnDetachedWarmup(targetRoot) {
+function spawnDetachedRefresh(targetRoot, files) {
   try {
+    const args = ['-y', `@skillcap/gdh@${PINNED_VERSION}`, 'authoring', 'diagnostics', 'refresh', '--target', targetRoot];
+    if (Array.isArray(files)) {
+      for (const f of files) {
+        args.push('--changed', f);
+      }
+    }
     const child = require('child_process').spawn(
       'npx',
-      ['-y', `@skillcap/gdh@${PINNED_VERSION}`, 'lsp', 'warmup', '--target', targetRoot],
+      args,
       {
         cwd: targetRoot,
         detached: true,
@@ -198,29 +215,52 @@ function spawnDetachedWarmup(targetRoot) {
     );
     child.unref();
   } catch (_error) {
-    // Silent failure — warmup is fire-and-forget. The bounded check below still runs.
+    // Silent failure — refresh is fire-and-forget. The bounded read below still runs.
   }
 }
 
-// Phase 82 / LSP-03. Session-end ("Stop") freshness barrier.
+// Phase 82 / LSP-03 + Quick task 260504-ix2 — Stop-hook contract relaxation.
+//
+// Original Phase 82 contract: Stop synchronously invoked
+// `gdh authoring check --mode final`, which calls
+// `getManagedLspStatus(launch_if_needed)` and could spawn Godot LSP from the
+// Stop event. Real-world dogfooding (2026-05-04 session) showed this path
+// always timed out due to per-invocation `npx -y @skillcap/gdh@PINNED` cost
+// (~9.3 s on the operator's measured machine). The hook ate the full
+// `STOP_TIMEOUT_MS` budget on the npx bootstrap path before producing any
+// output.
 //
-// Hard contract:
-//   - Runs gdh authoring check --mode final with STOP_TIMEOUT_MS bound (60 s default)
-//   - Reports unresolved diagnostics as additionalContext, NEVER decision: block (Pitfall 3)
-//   - Degrades to context() on subprocess timeout, error, or Godot crash
-//   - additionalContext bounded to MAX_STOP_CONTEXT_CHARS = 8000 (Pitfall 6)
+// Updated contract (RFC 0009 addendum): Stop reads the existing broker
+// snapshot via the embedded dependency-free reader; it does NOT synchronously
+// launch LSP. Cold/missing-broker case returns `additionalContext`
+// recommending the user run `gdh authoring check --mode final` manually AND
+// spawns detached warmup so the next session's PostToolUse events have a
+// primed broker. This trades the rare "fresh session, no warm broker" case
+// (where Stop would have produced final diagnostics synchronously) for the
+// common case of sub-100ms hook return on every Stop.
 //
-// Stop hook waits for in-flight warmup naturally: --mode final calls
-// getManagedLspStatus(launch_if_needed) which acquires lsp.lock; if warmup is
-// holding the lock, the 5 s LSP_STATE_LOCK_ACQUIRE_TIMEOUT_MS retry loop inside
-// the lock primitive handles the wait (Pitfall 9 — well within 60 s).
+// Hard invariants preserved:
+//   - GF3 (260504): zero authoring-files-in-target → noop (git gate, runs first)
+//   - Pitfall 3: NEVER returns decision: block (Stop hook must not block session end)
+//   - Pitfall 5: Claude additionalContext lives in hookSpecificOutput
+//   - Pitfall 6: additionalContext bounded to MAX_STOP_CONTEXT_CHARS = 8000
 function handleStop(input, targetRoot) {
   if (!hasAuthoringWorkInTarget(targetRoot)) return allow();
-  const result = runGdh(
-    targetRoot,
-    ['authoring', 'check', '--target', targetRoot, '--mode', 'final', '--format', 'compact'],
-    { timeoutMs: STOP_TIMEOUT_MS },
-  );
+
+  // Discover the authoring file set from the working tree under targetRoot.
+  // We feed this into the embedded reader so it can resolve broker entries
+  // by file:// URI. If the discovery fails (git unavailable, etc.) we fall
+  // through with an empty list, which routes to a `[pending]` status with
+  // reason `file_not_in_snapshot` — same effect as no broker primed.
+  const authoringFiles = listAuthoringFilesInTarget(targetRoot);
+
+  let output;
+  try {
+    output = runEmbeddedDiagnosticsRead(targetRoot, authoringFiles);
+  } catch (_err) {
+    output = '[pending]\nReasons: embedded_read_threw';
+  }
+
   const truncatedSuffix = ' Run `gdh authoring check --mode final` for full output.';
   function stopContext(message) {
     const text = String(message || '').trim();
@@ -229,33 +269,254 @@ function handleStop(input, targetRoot) {
     const headroom = ceiling - truncatedSuffix.length;
     return context(text.slice(0, headroom).trimEnd() + truncatedSuffix);
   }
-  if (result.timedOut) {
-    return stopContext(
-      `GDH session-end check timed out after ${STOP_TIMEOUT_MS}ms; continuing without blocking.` +
-      ' Run `gdh authoring check --mode final` manually before claiming code-validity.',
-    );
-  }
+
   // Bracketed-token dispatch — same vocabulary as PostToolUse but EVERY branch
   // routes to context() or allow(); decision: block is forbidden on Stop.
-  if (/^\[fresh\]/m.test(result.output)) {
+  // Forward-compat [partial] / [timeout] / [failed] branches retained for
+  // potential future reader extensions; the embedded reader currently emits
+  // only [fresh] / [stale] / [pending].
+  if (/^\[fresh\]/m.test(output)) {
     return allow();
   }
-  if (/^\[failed\]/m.test(result.output) || /^\[partial\]/m.test(result.output) || /^\[stale\]/m.test(result.output)) {
-    return stopContext(`GDH session-end check found unresolved diagnostics: ${compactOneLine(result.output)}`);
+  if (/^\[failed\]/m.test(output) || /^\[partial\]/m.test(output) || /^\[stale\]/m.test(output)) {
+    return stopContext(`GDH session-end check found unresolved diagnostics: ${compactOneLine(output)} ${reasonHint(output, targetRoot)}`);
   }
-  if (/^\[pending\]/m.test(result.output) || /^\[timeout\]/m.test(result.output)) {
+  if (/^\[pending\]/m.test(output) || /^\[timeout\]/m.test(output)) {
+    // Cold/missing broker: spawn detached refresh so the NEXT session benefits.
+    // The current Stop returns additionalContext recommending manual
+    // `gdh authoring check --mode final` (the relaxed contract — see RFC 0009
+    // addendum 2026-05-04). spawnDetachedRefresh is fire-and-forget; it never
+    // blocks hook return.
+    spawnDetachedRefresh(targetRoot, authoringFiles);
     return stopContext(
-      'GDH session-end check did not produce a final result before time bound; continuing without blocking. ' +
-      compactOneLine(result.output || 'Run final authoring validation before claiming code-validity.'),
+      'GDH session-end check could not prove final code-validity from the cached broker snapshot; continuing without blocking. ' +
+      'Run `gdh authoring check --mode final` manually before claiming code-validity. ' +
+      compactOneLine(output) + ' ' + reasonHint(output, targetRoot),
     );
   }
-  // Unknown / runtime error: degrade to additionalContext (NEVER block).
+  // Unknown status: degrade to additionalContext (NEVER block).
+  spawnDetachedRefresh(targetRoot, authoringFiles);
   return stopContext(
     'GDH session-end check could not produce a final result; continuing without blocking. ' +
-    compactOneLine(result.output || result.error || 'Run final authoring validation before claiming code-validity.'),
+    'Run `gdh authoring check --mode final` manually before claiming code-validity. ' +
+    compactOneLine(output) + ' ' + reasonHint(output, targetRoot),
   );
 }
 
+// Quick task 260504-ix2: collect authoring-relevant files in the working tree
+// under `targetRoot`. Sibling helper to `hasAuthoringWorkInTarget` (which
+// returns a boolean for the GF3 gate); this returns the list of files for the
+// embedded broker-snapshot reader to look up by file:// URI. Order-stable.
+//
+// Fail-open: returns [] on any git failure (the embedded reader will then emit
+// `[pending]` reasons, which Stop dispatches to additionalContext — never
+// block).
+function listAuthoringFilesInTarget(targetRoot) {
+  let result;
+  try {
+    result = spawnSync('git', ['-C', targetRoot, 'status', '--porcelain', '--', '.'], {
+      encoding: 'utf8',
+      timeout: 1500,
+      windowsHide: true,
+    });
+  } catch (_error) {
+    return [];
+  }
+  if (!result || result.error || result.status !== 0 || result.signal) return [];
+  const files = [];
+  for (const raw of String(result.stdout || '').split('\n')) {
+    if (!raw || raw.length < 4) continue;
+    let rest = raw.slice(3);
+    const arrow = rest.indexOf(' -> ');
+    if (arrow !== -1) rest = rest.slice(arrow + 4);
+    if (rest.startsWith('"') && rest.endsWith('"')) rest = rest.slice(1, -1);
+    if (isAuthoringValidationPath(rest)) files.push(rest);
+  }
+  return unique(files);
+}
+
+// Quick task 260504-ix2: dependency-free embedded broker-snapshot reader.
+//
+// Replaces the per-edit `npx -y @skillcap/gdh@PINNED authoring check ...`
+// shellout (which paid the ~9.3 s npx bootstrap cost on every hook fire).
+// Reads `<stateRoot>/authoring/lsp-instance.json` and
+// `<stateRoot>/authoring/diagnostics-broker/snapshot.json` directly,
+// validates LSP instance identity + per-file SHA-256 content hash +
+// freshness window, and synthesises the same bracketed-token output the
+// existing dispatch consumes (`[fresh]` / `[stale]` / `[pending]`).
+//
+// Reasons vocabulary (kept aligned with packages/authoring/src/lsp.ts):
+//   lsp_instance_not_running, lsp_instance_parse_error,
+//   broker_not_yet_primed, snapshot_parse_error, unsupported_broker_schema,
+//   lsp_instance_identity_mismatch, content_hash_mismatch, freshness_expired,
+//   file_not_in_snapshot, state_root_unresolved.
+//
+// Hash parity: the broker writer (`packages/authoring/src/diagnostics-broker.ts`
+// `hashText`) and the cache validator (`packages/authoring/src/lsp.ts`
+// `hashFilesByUri`) both read files via `fs.readFile(path, "utf8")` and
+// SHA-256 the resulting string. The embedded reader MUST do the same so a
+// fresh snapshot covering an unmodified file matches by content hash.
+function runEmbeddedDiagnosticsRead(targetRoot, authoringFiles) {
+  const stateRoot = resolveStateRoot(targetRoot);
+  if (stateRoot === null) {
+    return formatStatus('pending', ['state_root_unresolved']);
+  }
+
+  const lspInstancePath = path.join(stateRoot, 'authoring', 'lsp-instance.json');
+  let lspInstance;
+  try {
+    const raw = fs.readFileSync(lspInstancePath, 'utf8');
+    lspInstance = JSON.parse(raw);
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return formatStatus('pending', ['lsp_instance_not_running']);
+    return formatStatus('pending', ['lsp_instance_parse_error']);
+  }
+  const expectedInstanceId = lspInstance && lspInstance.instance && lspInstance.instance.instanceId;
+  if (typeof expectedInstanceId !== 'string' || expectedInstanceId.length === 0) {
+    return formatStatus('pending', ['lsp_instance_not_running']);
+  }
+
+  const snapshotPath = path.join(stateRoot, 'authoring', 'diagnostics-broker', 'snapshot.json');
+  let snapshot;
+  try {
+    const raw = fs.readFileSync(snapshotPath, 'utf8');
+    snapshot = JSON.parse(raw);
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return formatStatus('pending', ['broker_not_yet_primed']);
+    return formatStatus('pending', ['snapshot_parse_error']);
+  }
+  if (!snapshot || snapshot.schemaVersion !== 1) {
+    return formatStatus('pending', ['unsupported_broker_schema']);
+  }
+  if (snapshot.lspInstanceId !== expectedInstanceId) {
+    return formatStatus('stale', ['lsp_instance_identity_mismatch']);
+  }
+
+  const filesByUri = new Map();
+  if (Array.isArray(snapshot.files)) {
+    for (const f of snapshot.files) if (f && typeof f.uri === 'string') filesByUri.set(f.uri, f);
+  }
+
+  // Match the constant in `packages/authoring/src/lsp.ts`
+  // (`DIAGNOSTICS_BROKER_DEFAULT_FRESHNESS_STALE_AFTER_MS`). Hard-coded here
+  // because the hook is dependency-free and cannot import @gdh/authoring.
+  const STALE_AFTER_MS = 60000;
+  const nowMs = Date.now();
+  const allDiagnostics = [];
+
+  for (const relPath of authoringFiles) {
+    // Match the broker writer's URI canonicalisation: it calls
+    // `fs.realpath` on each requested file before `pathToFileURL.href`,
+    // which collapses macOS `/var/folders` → `/private/var/folders`
+    // symlinks (and similar real-symlink layouts on Linux/Windows). The
+    // hook's `__dirname` already comes through canonicalised by Node's
+    // module loader, but the legacy `path.resolve` in the resolver does
+    // NOT walk symlinks. Use `canonicalPath` (already-defined helper) so
+    // the URIs match a snapshot captured by `hashFilesByUri`.
+    const absolutePath = canonicalPath(path.resolve(targetRoot, relPath));
+    const expectedUri = pathToFileURL(absolutePath).href;
+    const entry = filesByUri.get(expectedUri);
+    if (!entry) return formatStatus('pending', ['file_not_in_snapshot']);
+
+    if (typeof entry.contentHash !== 'string' || entry.contentHash.length === 0) {
+      // Pre-content-hash snapshot entries cannot prove current file content.
+      // Plan info-note: route through `[pending]` (not `[stale]`) — the broker
+      // is not yet fully primed for this file even if the snapshot exists.
+      return formatStatus('pending', ['broker_not_yet_primed']);
+    }
+
+    let onDiskHash;
+    try {
+      const text = fs.readFileSync(absolutePath, 'utf8');
+      onDiskHash = crypto.createHash('sha256').update(text).digest('hex');
+    } catch (_err) {
+      // File deleted between hook trigger and read, or unreadable encoding.
+      // Fallthrough: treat as not-in-snapshot so we degrade to additionalContext.
+      return formatStatus('pending', ['file_not_in_snapshot']);
+    }
+    if (onDiskHash !== entry.contentHash) {
+      return formatStatus('stale', ['content_hash_mismatch']);
+    }
+
+    const updatedMs = Date.parse(entry.lastUpdatedAt);
+    if (!Number.isFinite(updatedMs) || (nowMs - updatedMs) > STALE_AFTER_MS) {
+      return formatStatus('stale', ['freshness_expired']);
+    }
+
+    if (Array.isArray(entry.diagnostics)) {
+      for (const diag of entry.diagnostics) {
+        allDiagnostics.push({ uri: entry.uri, diag });
+      }
+    }
+  }
+
+  return formatFreshDiagnostics(allDiagnostics);
+}
+
+function formatStatus(token, reasons) {
+  return `[${token}]\nReasons: ${reasons.join(', ')}`;
+}
+
+function formatFreshDiagnostics(items) {
+  let errors = 0;
+  let warnings = 0;
+  let infoCount = 0;
+  const lines = [];
+  for (const item of items) {
+    const diag = item.diag;
+    const sev = (diag && typeof diag.severity === 'string') ? diag.severity : 'info';
+    if (sev === 'error') errors += 1;
+    else if (sev === 'warning') warnings += 1;
+    else infoCount += 1;
+    const line = (diag && diag.range && diag.range.start && Number.isFinite(diag.range.start.line)) ? diag.range.start.line + 1 : 0;
+    const col = (diag && diag.range && diag.range.start && Number.isFinite(diag.range.start.character)) ? diag.range.start.character + 1 : 0;
+    const msg = (diag && typeof diag.message === 'string') ? diag.message : '';
+    lines.push(`${item.uri}:${line}:${col} [${sev}] ${msg}`);
+  }
+  // Mirror packages/authoring/src/diagnostics-summary.ts: with the default
+  // "error" severity policy, ANY error diagnostic produces a `blocked` summary
+  // → CLI emits `[failed]` → hook dispatch routes to `block()`. The embedded
+  // reader must produce the same status token so the hook still blocks edits
+  // that introduce errors. Warnings and info do not alter the status token.
+  const statusToken = errors > 0 ? 'failed' : 'fresh';
+  const completion = errors > 0 ? 'blocked' : 'allowed';
+  const head = lines.length ? `${lines.join('\n')}\n` : '';
+  return `${head}[${statusToken}] ${errors} errors, ${warnings} warnings, ${infoCount} info. Completion ${completion}.`;
+}
+
+function resolveStateRoot(targetRoot) {
+  // 1. Baked render-time path — the canonical resolution for installed hooks.
+  try {
+    const baked = path.resolve(__dirname, STATE_RELATIVE_PATH_FROM_HOOK);
+    if (fs.existsSync(baked)) return baked;
+  } catch (_err) {
+    // Fall through to walk-up fallbacks if the baked path is malformed.
+  }
+  // 2. Walk up from __dirname looking for `.gdh/project.yaml`. Useful when the
+  //    hook script has been moved or the bake-time relative path is wrong.
+  let dir = __dirname;
+  for (let i = 0; i < 10; i += 1) {
+    if (fs.existsSync(path.join(dir, '.gdh', 'project.yaml'))) {
+      return path.join(dir, '.gdh-state');
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  // 3. Walk up from targetRoot — covers root-launched cases where the hook
+  //    might be loaded from outside the project tree.
+  dir = targetRoot;
+  for (let i = 0; i < 10; i += 1) {
+    if (fs.existsSync(path.join(dir, '.gdh', 'project.yaml'))) {
+      return path.join(dir, '.gdh-state');
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
 function collectChangedFiles(input, targetRoot) {
   const baseCwd = input && typeof input.cwd === 'string' ? input.cwd : process.cwd();
   const files = [];
@@ -382,15 +643,49 @@ function compactOneLine(value) {
 }
 
 function allow() { process.exit(0); }
-function context(additionalContext) {
-  // Codex always receives hookSpecificOutput.additionalContext (any event).
-  // Claude receives hookSpecificOutput.additionalContext on Stop (Phase 82 / LSP-03) and
-  // on PostToolBatch (Phase 83 / LSP-09 — coalesced batch result). Without the third
-  // branch below, [pending]/[stale]/[timeout] PostToolBatch results would silently drop
-  // additionalContext on Claude — Pitfall 1.
-  if (AGENT !== 'codex') {
-    if (CURRENT_EVENT !== 'Stop' && CURRENT_EVENT !== 'PostToolBatch') return allow();
+// Quick task 260504-o6w: agent-actionable hint derived from the Reasons: line in
+// the embedded reader's output. The mapping covers all reason classes emitted by
+// `formatStatus` so the agent receives a copy-paste-ready command rather than a
+// generic "authoring check failed" message.
+function reasonHint(output, targetRoot) {
+  const text = String(output || '');
+  const match = text.match(/^Reasons:\s*(.+)$/m);
+  const reasons = match ? match[1].split(',').map(r => r.trim()).filter(Boolean) : [];
+  // JSON.stringify embeds the path so spaces and quotes survive shell re-use.
+  const targetArg = JSON.stringify(targetRoot);
+  // First-match-wins ordering: more specific reasons before generic.
+  if (reasons.includes('lsp_instance_identity_mismatch')) {
+    return `Cross-worktree LSP from another checkout. Run \`gdh lsp prune --target ${targetArg}\` then retry the edit.`;
+  }
+  if (reasons.includes('lsp_instance_not_running')) {
+    return `LSP launching in background; next edit will report fresh diagnostics. Force-prime: \`gdh authoring diagnostics refresh --target ${targetArg}\``;
   }
+  if (reasons.includes('broker_not_yet_primed') || reasons.includes('file_not_in_snapshot')) {
+    return `Broker priming in background; next edit will be fresh. Force-prime: \`gdh authoring diagnostics refresh --target ${targetArg}\``;
+  }
+  if (reasons.includes('content_hash_mismatch') || reasons.includes('freshness_expired')) {
+    return `Broker snapshot stale; background refresh running. Force-prime: \`gdh authoring diagnostics refresh --target ${targetArg}\``;
+  }
+  return `Run \`gdh authoring check --mode final --target ${targetArg}\` to prime broker before claiming code-validity.`;
+}
+// Codex always receives hookSpecificOutput.additionalContext (any event — Codex's
+// hook contract accepts it on PreToolUse / PostToolUse / Stop / etc.).
+//
+// Claude receives hookSpecificOutput.additionalContext on PostToolUse / PostToolBatch
+// / FileChanged. Claude Stop is silent-allow because the Stop hook schema does NOT
+// accept additionalContext (only decision/reason/continue/stopReason/suppressOutput/
+// systemMessage). The previous gate emitted the wrong shape on every Claude Stop
+// and Claude rejected it as "invalid stop hook JSON output" (quick task 260504-o6w
+// bug B, verified live on TheBeacon 2026-05-04).
+function context(additionalContext) {
+  // Claude: Stop hook schema does NOT accept hookSpecificOutput.additionalContext
+  // (only decision/reason/continue/stopReason/suppressOutput/systemMessage). Emitting
+  // the wrong shape causes Claude to reject the hook with "invalid stop hook JSON
+  // output" — verified locally 2026-05-04 (quick task 260504-o6w bug B). Drop to
+  // silent-allow on Claude Stop. Claude PostToolUse / PostToolBatch DO accept
+  // additionalContext, so those branches still flow through. Codex accepts
+  // additionalContext on every event.
+  if (AGENT !== 'codex' && CURRENT_EVENT === 'Stop') return allow();
   const payload = { hookSpecificOutput: { hookEventName: CURRENT_EVENT, additionalContext } };
   process.stdout.write(`${JSON.stringify(payload)}\n`);
   process.exit(0);