@ijfw/memory-server 1.4.3 → 1.5.0

package/src/observability/cost-anomaly.js

@@ -0,0 +1,166 @@
+/**
+ * observability/cost-anomaly.js -- v1.5.0 N4.obs M4.
+ *
+ * Rolling z-score anomaly detection on the daily cost series. No LLM call,
+ * no external service. Designed for the dashboard cost tile: when today is
+ * unusually expensive, surface it ("Today is 3.4x yesterday's average; top
+ * driver = ijfw_memory_search calls, 54% of cost").
+ *
+ * Inputs (per the dashboard's existing /api/data shape):
+ *   - daily:        { date: 'YYYY-MM-DD', cost: number }[]   (oldest -> newest OR
+ *                                                              newest -> oldest;
+ *                                                              we sort defensively)
+ *   - todayDrivers: { name: string, cost: number }[]         (optional;
+ *                                                              top-driver
+ *                                                              attribution)
+ *
+ * Output:
+ *   {
+ *     anomalous:  boolean,       // true when today > mean + 2*stdev of trailing window
+ *     today:      number,        // today's cost
+ *     baseline:   { mean, stdev, days, window } // baseline stats
+ *     factor:     number|null,   // today / yesterday-baseline-mean (1.0 = on par)
+ *     z:          number|null,   // (today - mean) / stdev (∞-bounded; null if stdev=0)
+ *     topDriver:  { name, cost, sharePct }|null
+ *     reason:     string         // human-readable summary for the tile
+ *   }
+ *
+ * Tuning knobs:
+ *   - windowDays:  rolling window length (default 7)
+ *   - threshold:   z above which we mark anomalous (default 2.0; equivalent to
+ *                   "more than 2 standard deviations above the trailing mean")
+ *
+ * Edge cases the dashboard relies on:
+ *   - Fewer than `windowDays` historical days => not anomalous, return
+ *     `{anomalous:false, reason:'insufficient_history', ...}` so the tile can
+ *     hide gracefully.
+ *   - Zero stdev (flat baseline) => fall back to factor-based check
+ *     (today > baseline mean by >= 2x).
+ *   - Empty/malformed series => anomalous=false, reason='no_data'.
+ */
+
+const DEFAULT_WINDOW = 7;
+const DEFAULT_THRESHOLD = 2.0;
+// When stdev=0 but today exceeds mean by this multiple, still flag.
+const FLAT_BASELINE_FACTOR = 2.0;
+
+/**
+ * Detect a daily-cost anomaly.
+ *
+ * @param {{daily: Array<{date:string, cost:number}>, todayDrivers?: Array<{name:string,cost:number}>, windowDays?: number, threshold?: number}} input
+ * @returns {object} result described above
+ */
+export function detectCostAnomaly(input = {}) {
+  const windowDays = Number.isFinite(input.windowDays) && input.windowDays > 0
+    ? Math.floor(input.windowDays)
+    : DEFAULT_WINDOW;
+  const threshold = Number.isFinite(input.threshold) && input.threshold > 0
+    ? input.threshold
+    : DEFAULT_THRESHOLD;
+
+  const daily = Array.isArray(input.daily) ? input.daily : [];
+  const cleaned = daily
+    .filter((d) => d && typeof d.date === 'string' && Number.isFinite(d.cost))
+    .map((d) => ({ date: d.date, cost: Math.max(0, d.cost) }))
+    // Sort oldest -> newest, defensively.
+    .sort((a, b) => a.date.localeCompare(b.date));
+
+  if (cleaned.length === 0) {
+    return {
+      anomalous: false,
+      today: 0,
+      baseline: { mean: 0, stdev: 0, days: 0, window: windowDays },
+      factor: null,
+      z: null,
+      topDriver: null,
+      reason: 'no_data',
+    };
+  }
+
+  // Today = last entry; trailing window = the windowDays entries BEFORE it.
+  const todayEntry = cleaned[cleaned.length - 1];
+  const trailing = cleaned.slice(Math.max(0, cleaned.length - 1 - windowDays), cleaned.length - 1);
+
+  if (trailing.length < Math.min(3, windowDays)) {
+    return {
+      anomalous: false,
+      today: todayEntry.cost,
+      baseline: { mean: 0, stdev: 0, days: trailing.length, window: windowDays },
+      factor: null,
+      z: null,
+      topDriver: pickTopDriver(input.todayDrivers, todayEntry.cost),
+      reason: 'insufficient_history',
+    };
+  }
+
+  // mean/stdev (sample variance, ddof=1 when n>1)
+  const n = trailing.length;
+  const sum = trailing.reduce((s, d) => s + d.cost, 0);
+  const mean = sum / n;
+  const variance = n > 1
+    ? trailing.reduce((s, d) => s + (d.cost - mean) ** 2, 0) / (n - 1)
+    : 0;
+  const stdev = Math.sqrt(variance);
+
+  const today = todayEntry.cost;
+  const factor = mean > 0 ? today / mean : null;
+  const z = stdev > 0 ? (today - mean) / stdev : null;
+
+  let anomalous = false;
+  let reason;
+  if (z !== null) {
+    anomalous = z >= threshold;
+    if (anomalous) {
+      reason = `Today is ${factor != null ? factor.toFixed(1) : '?'}x the ${windowDays}-day average (z=${z.toFixed(1)}).`;
+    } else {
+      reason = `Within normal range (z=${z.toFixed(1)}, threshold=${threshold}).`;
+    }
+  } else if (mean > 0 && factor !== null && factor >= FLAT_BASELINE_FACTOR) {
+    // Flat baseline -- mean > 0 but stdev == 0. Still flag if we more than
+    // doubled.
+    anomalous = true;
+    reason = `Today is ${factor.toFixed(1)}x the ${windowDays}-day flat baseline.`;
+  } else if (mean === 0) {
+    // Baseline was zero -- today is anomalous iff there's non-zero spend.
+    anomalous = today > 0;
+    reason = anomalous
+      ? `First non-zero day after a ${windowDays}-day quiet stretch.`
+      : 'No spend in window.';
+  } else {
+    reason = 'Within normal range (flat baseline, factor < 2).';
+  }
+
+  const topDriver = pickTopDriver(input.todayDrivers, today);
+  if (anomalous && topDriver) {
+    reason += ` Top driver: ${topDriver.name} (${topDriver.sharePct}%).`;
+  }
+
+  return {
+    anomalous,
+    today,
+    baseline: {
+      mean,
+      stdev,
+      days: n,
+      window: windowDays,
+    },
+    factor,
+    z,
+    topDriver,
+    reason,
+  };
+}
+
+function pickTopDriver(drivers, total) {
+  if (!Array.isArray(drivers) || drivers.length === 0) return null;
+  if (!Number.isFinite(total) || total <= 0) return null;
+  let top = null;
+  for (const d of drivers) {
+    if (!d || typeof d.name !== 'string' || !Number.isFinite(d.cost)) continue;
+    if (d.cost <= 0) continue;
+    if (!top || d.cost > top.cost) top = d;
+  }
+  if (!top) return null;
+  const sharePct = Math.round((top.cost / total) * 100);
+  return { name: top.name, cost: top.cost, sharePct };
+}

package/src/observability/evaluator-checkpoint-contract.js

@@ -0,0 +1,117 @@
+/**
+ * observability/evaluator-checkpoint-contract.js -- v1.5.0 N4.obs M3.
+ *
+ * First shipped pre-built evaluator. Story for the audit / dashboard / docs:
+ *
+ *   "IJFW ships evaluators. Even without integrating with Weave / Phoenix /
+ *   Langfuse, you get N built-in checks that score every subagent report
+ *   against the orchestrator's contracts."
+ *
+ * THIS evaluator scores a subagent's final Status block against the v1.4.4 N2
+ * status-protocol contract -- the four MANDATORY sections every implementer
+ * agent is required to emit on completion:
+ *
+ *   1. Status:     -- one of DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED
+ *   2. SHAs:       -- list of commit SHAs landed (or "(none)")
+ *   3. Files:      -- list of files touched (or "(none)")
+ *   4. Tests:      -- "<pass>/<total>" or "(none)"
+ *
+ * The four-section contract is enforced by:
+ *   - orchestrator/checkpoint-contract.md (cadence + size cap)
+ *   - orchestrator/status-protocol.js (parseAgentReport regex)
+ *   - the N4.obs M3 brief instructions all implementer subagents receive
+ *
+ * Returns:
+ *   {
+ *     valid:    boolean,                // true iff missing[] is empty
+ *     missing:  string[],               // section names that were absent
+ *     details:  { [section]: 'present'|'absent' },
+ *     reason?:  string,                 // when valid=false, short rationale
+ *   }
+ *
+ * Designed to be cheap (regex-only, no LLM call) so dispatch-planner and
+ * plan-checker can run it inline on every report.
+ *
+ * Future evaluators can be added next to this file under the same exported
+ * `evaluators` registry shape so the dashboard can enumerate them.
+ */
+
+/** Canonical evaluator id -- stable, matches the file slug. */
+export const ID = 'checkpoint-contract';
+
+/** The four sections required by v1.4.4 N2. Stable order = stable UI. */
+export const REQUIRED_SECTIONS = Object.freeze([
+  'STATUS',
+  'SHAS',
+  'FILES',
+  'TESTS',
+]);
+
+/**
+ * Synonyms tolerated for each section heading. Implementer agents have shipped
+ * a few minor variants ("SHA(s):", "Files:", "Tests:"), so the evaluator
+ * accepts them all. The status-protocol parser is stricter; we want this
+ * evaluator to be a high-recall first-pass so it doesn't false-flag obviously
+ * compliant reports.
+ */
+const SECTION_PATTERNS = Object.freeze({
+  // STATUS must be on its own line; allow trailing space + colon + value.
+  STATUS: /^\s*Status\s*:\s*(?:DONE(?:_WITH_CONCERNS)?|NEEDS_CONTEXT|BLOCKED)\b/im,
+  SHAS:   /^\s*SHA(?:s|\(s\))?\s*:/im,
+  FILES:  /^\s*Files?\s*:/im,
+  TESTS:  /^\s*Tests?\s*:/im,
+});
+
+/**
+ * Evaluate a subagent's final report against the checkpoint-contract.
+ *
+ * @param {string} statusBlock  the agent's final Status block (or full report)
+ * @returns {{valid: boolean, missing: string[], details: Record<string, 'present'|'absent'>, reason?: string}}
+ */
+export function evaluateCheckpointContract(statusBlock) {
+  if (typeof statusBlock !== 'string' || statusBlock.length === 0) {
+    return {
+      valid: false,
+      missing: [...REQUIRED_SECTIONS],
+      details: Object.fromEntries(REQUIRED_SECTIONS.map((s) => [s, 'absent'])),
+      reason: 'empty or non-string report',
+    };
+  }
+
+  const details = {};
+  const missing = [];
+  for (const section of REQUIRED_SECTIONS) {
+    const re = SECTION_PATTERNS[section];
+    const present = re ? re.test(statusBlock) : false;
+    details[section] = present ? 'present' : 'absent';
+    if (!present) missing.push(section);
+  }
+
+  const valid = missing.length === 0;
+  return {
+    valid,
+    missing,
+    details,
+    ...(valid ? {} : { reason: `missing required sections: ${missing.join(', ')}` }),
+  };
+}
+
+/**
+ * Evaluator registry entry. Loaders (dashboard tile, plan-checker, dispatcher)
+ * import this to enumerate built-in evaluators without name-spelunking.
+ */
+export const evaluator = Object.freeze({
+  id: ID,
+  title: 'Checkpoint contract (4 required sections)',
+  description:
+    'Scores a subagent\'s final Status block against the v1.4.4 N2 four-section contract: Status / SHAs / Files / Tests.',
+  // Per-evaluator weights live with the evaluator so dashboard can show them
+  // alongside the score without an external registry.
+  weight: 1.0,
+  run: evaluateCheckpointContract,
+});
+
+/**
+ * Registry shape. Adding evaluators later is "import + push".
+ */
+export const evaluators = Object.freeze([evaluator]);

package/src/observability/trace-id.js

@@ -0,0 +1,163 @@
+/**
+ * observability/trace-id.js -- v1.5.0 N4.obs M1
+ *
+ * Session-scoped trace IDs (Langfuse / Helicone-style sessions->traces->observations
+ * rollup). One UUID per orchestrator session, propagated to subagent worktrees
+ * via the IJFW_TRACE_ID env var, and recorded on every checkpoint / receipt /
+ * observation / session row.
+ *
+ * Discovery order (caller-side):
+ *   1. process.env.IJFW_TRACE_ID  (set explicitly by orchestrator or subagent parent)
+ *   2. lazy-init: generate one and cache in module state
+ *
+ * Zero deps -- Node built-in crypto only.
+ *
+ * Threading model: a single Node process holds at most ONE current trace id at a
+ * time. Subagents inherit via env var; if they call ensureTraceId() they keep
+ * the parent's id. resetTraceId() exists for tests only.
+ */
+
+import { randomUUID } from 'node:crypto';
+
+const ENV_VAR = 'IJFW_TRACE_ID';
+// RFC 4122 v4 UUID -- 32 hex chars + 4 dashes
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+let _cached = null;
+
+/**
+ * Hierarchical observation path (Helicone-style) -- v1.5.0 N4.obs M2.
+ *
+ * The orchestrator-LLM walks down `/wave-<waveId>/sub-<subId>/tool-<toolName>`
+ * via pushPath/popPath wrappers (NOT exported -- callers compose the segment
+ * themselves so the runtime doesn't have to track a stack across async ops).
+ */
+const PATH_SEPARATOR = '/';
+
+/**
+ * Validate a UUID-shaped trace id. Reject anything else so a poisoned env
+ * var (e.g. `IJFW_TRACE_ID=$(rm -rf /)`) doesn't flow into receipt files.
+ */
+export function isValidTraceId(value) {
+  return typeof value === 'string' && UUID_PATTERN.test(value);
+}
+
+/**
+ * Get the current trace id, generating one if none exists. Idempotent within a
+ * process: subsequent calls return the same id unless `resetTraceId` is called.
+ *
+ * If process.env.IJFW_TRACE_ID is set and valid, it is adopted (this is how
+ * worktree subagents inherit the orchestrator's trace).
+ *
+ * @returns {string} current trace id (RFC 4122 v4 UUID).
+ */
+export function ensureTraceId() {
+  if (_cached && isValidTraceId(_cached)) return _cached;
+  const fromEnv = process.env[ENV_VAR];
+  if (isValidTraceId(fromEnv)) {
+    _cached = fromEnv;
+    return _cached;
+  }
+  _cached = randomUUID();
+  // Reflect into env so a child process spawned without an explicit env arg
+  // still inherits via the standard mechanism.
+  process.env[ENV_VAR] = _cached;
+  return _cached;
+}
+
+/**
+ * Read the current trace id without generating one. Returns null if neither the
+ * cache nor the env var has a valid id. Useful for "tag if available, don't
+ * fabricate" call sites.
+ *
+ * @returns {string|null}
+ */
+export function getTraceId() {
+  if (_cached && isValidTraceId(_cached)) return _cached;
+  const fromEnv = process.env[ENV_VAR];
+  if (isValidTraceId(fromEnv)) {
+    _cached = fromEnv;
+    return _cached;
+  }
+  return null;
+}
+
+/**
+ * Adopt a trace id explicitly. Used when an orchestrator dispatches a subagent
+ * and wants to set the env var into the spawn options.
+ *
+ * @param {string} id
+ * @returns {string} the adopted id (throws if invalid)
+ */
+export function setTraceId(id) {
+  if (!isValidTraceId(id)) {
+    throw new Error(`trace-id: refusing to adopt invalid trace id "${id}"`);
+  }
+  _cached = id;
+  process.env[ENV_VAR] = id;
+  return _cached;
+}
+
+/**
+ * Test-only: clear the cached trace id and the env var. Caller-side tests
+ * import this to reset state between cases.
+ */
+export function resetTraceId() {
+  _cached = null;
+  delete process.env[ENV_VAR];
+}
+
+/**
+ * Build the env object to hand to child_process.spawn / Agent worktree dispatch
+ * so the child inherits the current trace id. Pass-through clones existing env
+ * keys; callers MAY override.
+ *
+ * @param {object} [extra] extra env keys to merge in
+ * @returns {object}
+ */
+export function traceEnv(extra = {}) {
+  const id = ensureTraceId();
+  return { ...process.env, [ENV_VAR]: id, ...extra };
+}
+
+/**
+ * Compose a hierarchical observation path -- v1.5.0 N4.obs M2.
+ *
+ * Convention: `/wave-<waveId>/sub-<subId>/tool-<toolName>`. Each segment is
+ * sanitised to `[A-Za-z0-9_-]` so the path is safe to render in a dashboard
+ * tree without escaping. Empty/missing segments are skipped.
+ *
+ * Example:
+ *   composePath({ waveId: 'W12-A', subId: 'N05', tool: 'Bash' })
+ *   -> "/wave-W12-A/sub-N05/tool-Bash"
+ *
+ * @param {{waveId?: string, subId?: string, tool?: string, segments?: string[]}} parts
+ * @returns {string}
+ */
+export function composePath(parts = {}) {
+  const segs = [];
+  if (parts && typeof parts === 'object') {
+    if (typeof parts.waveId === 'string' && parts.waveId.length > 0) {
+      segs.push(`wave-${sanitiseSegment(parts.waveId)}`);
+    }
+    if (typeof parts.subId === 'string' && parts.subId.length > 0) {
+      segs.push(`sub-${sanitiseSegment(parts.subId)}`);
+    }
+    if (typeof parts.tool === 'string' && parts.tool.length > 0) {
+      segs.push(`tool-${sanitiseSegment(parts.tool)}`);
+    }
+    if (Array.isArray(parts.segments)) {
+      for (const s of parts.segments) {
+        if (typeof s !== 'string' || s.length === 0) continue;
+        segs.push(sanitiseSegment(s));
+      }
+    }
+  }
+  if (segs.length === 0) return '';
+  return PATH_SEPARATOR + segs.join(PATH_SEPARATOR);
+}
+
+function sanitiseSegment(s) {
+  // Collapse anything outside [A-Za-z0-9_-] to '_'. Cap at 64 chars.
+  return String(s).replace(/[^A-Za-z0-9_-]+/g, '_').slice(0, 64);
+}

package/src/orchestrator/agents-md-blackboard.js

@@ -0,0 +1,152 @@
+/**
+ * agents-md-blackboard.js — populate the AGENTS.md BLACKBOARD marker block.
+ *
+ * v1.5.0 S4 (initial landing): shelled out to
+ *   claude/skills/ijfw-agents-md/scripts/merge-block-aware.sh
+ * under `withFsLock(.AGENTS.md.lock)` via `execFile('bash', …)`. That
+ * pattern HELD an fs-lock across a subprocess spawn — a STATE-SDK-CONTRACT
+ * §3 violation:
+ *     "No lock is held across a subprocess spawn. `merge-block-aware.sh` is
+ *      ported to in-process JS (T8); any unavoidable spawn pre-renders its
+ *      payload and runs outside the lock."
+ *
+ * v1.5.0 T8 (this rewrite):
+ *   - The shell script is ported to in-process JS at
+ *     `./merge-block-aware.js` (single-pair AGENTS.md block merge with
+ *     parity-tested semantics — see `test-merge-block-aware.js`).
+ *   - The AGENTS.md write happens under `withFsLock(lockPathFor(<AGENTS.md>))`
+ *     — i.e. the STATE-SDK-CONTRACT §3 #8 tier lock — using the SAME lock
+ *     primitive every other state writer uses. No subprocess is ever
+ *     spawned anywhere in the call graph; the critical section is
+ *     read → mergeBlocks() → writeAtomic().
+ *   - The blackboard refresh is registered with the SDK as a fire-and-forget
+ *     observability event via `query('event.emit', …)` AFTER the lock is
+ *     released. This is the SDK-routing requirement from the T8 brief
+ *     ("Blackboard writes route through verbs"): every blackboard write
+ *     emits an `agents-md.blackboard.set` event, classifiable by replay.
+ *
+ * SDK-VERB GAP — T8-followup-1 (mirror of T7-followup-1):
+ *   The frozen 20-verb state-SDK contract (`.planning/v150-gap-closure/
+ *   STATE-SDK-CONTRACT.md` §7+§8) does NOT include a verb that writes
+ *   `<projectRoot>/AGENTS.md`. The contract §1 table lists this module
+ *   ("agents-md-blackboard.js (T8)") as the sole writer for the BLACKBOARD
+ *   marker block, and the contract §3 lock hierarchy assigns AGENTS.md to
+ *   tier #8 — but no verb signature emits that write today. T8 closes the
+ *   subprocess-under-lock violation in-process; absorbing the actual file
+ *   write into a future `agents-md.blackboard.set` verb is deferred to a
+ *   later contract amendment (do-not-touch state-sdk.js per the T8 brief).
+ *   The §3 #8 lock IS taken, the §3 §4 ordering invariant holds (no other
+ *   tier locks are acquired by this writer), and the SDK is notified of the
+ *   write via the `event.emit` verb after release — so the absence of a
+ *   dedicated verb is purely a contract-API gap, not a correctness gap.
+ *
+ * Failure handling: non-throwing. Returns `{ok, reason?, error?}` so a
+ * missing AGENTS.md / missing template / write-error degrades the blackboard
+ * refresh to advisory (the wave-state checkpoint must never be blocked by an
+ * AGENTS.md hiccup — see `wave-state.js#checkpointWave`).
+ */
+
+import { join } from 'node:path';
+
+import { withFsLock, lockPathFor } from '../fs-lock.js';
+import { readWaveState } from './wave-state.js';
+import { mergeFile, MergeBlockAwareError } from './merge-block-aware.js';
+import { query } from './state-sdk.js';
+
+/**
+ * Render the BLACKBOARD marker-block payload from a wave's STATE.md
+ * frontmatter slice. Stable shape — consumers (humans + the dashboard's
+ * BLACKBOARD lens) read these keys directly.
+ *
+ * @param {string} waveId
+ * @param {object} state  parsed STATE.md (`readWaveState` result)
+ * @returns {string}      pretty-printed JSON (2-space indent — matches v1.5.0 S4)
+ */
+function renderBlackboardPayload(waveId, state) {
+  const fm = state?.frontmatter || {};
+  return JSON.stringify({
+    wave_id: waveId,
+    state_path: `.ijfw/wave-${waveId}/STATE.md`,
+    status: fm.status,
+    claims_active: fm.claims_active ?? 0,
+    blockers_open: fm.blockers_open ?? [],
+    findings_recent: fm.findings_recent ?? [],
+    updated_at: new Date().toISOString(),
+  }, null, 2);
+}
+
+/**
+ * Refresh the BLACKBOARD marker block in `<projectRoot>/AGENTS.md` from the
+ * given wave's STATE.md. Held under the §3 #8 AGENTS.md lock; in-process
+ * (no spawn). Best-effort SDK event emit after lock release.
+ *
+ * Return shapes:
+ *   `{ ok: true }`                          — wrote AGENTS.md
+ *   `{ ok: false, reason: 'no-state' }`     — wave STATE.md absent (skip)
+ *   `{ ok: false, reason: 'merge-error', error }`  — merger threw
+ *
+ * @param {string} waveId
+ * @param {string} projectRoot
+ * @returns {Promise<{ok: boolean, reason?: string, error?: string}>}
+ */
+export async function populateBlackboardBlock(waveId, projectRoot) {
+  const state = await readWaveState(waveId, projectRoot);
+  if (!state) return { ok: false, reason: 'no-state' };
+
+  const payload = renderBlackboardPayload(waveId, state);
+  const agentsMdPath = join(projectRoot, 'AGENTS.md');
+  const lockPath = lockPathFor(agentsMdPath);
+
+  let mergeResult;
+  let mergeError = null;
+  try {
+    mergeResult = await withFsLock(lockPath, async () => mergeFile(
+      agentsMdPath,
+      [{ block: 'BLACKBOARD', content: payload }],
+    ));
+  } catch (err) {
+    mergeError = err;
+  }
+
+  if (mergeError) {
+    // Surface the same shape callers expected from the legacy
+    // `execFile`-of-merger failure mode: ok:false + a reason + an error
+    // string. `reason` is the canonical T8 replacement for the v1.5.0 S4
+    // `merger-failed`/`merger-missing` strings (the merger is now in-
+    // process — the failure surface is "merge-error").
+    const code = mergeError instanceof MergeBlockAwareError ? mergeError.code : null;
+    return {
+      ok: false,
+      reason: code === 'ERR_TEMPLATE_MISSING' ? 'template-missing' : 'merge-error',
+      error: String(mergeError.message || mergeError),
+    };
+  }
+
+  // SDK-routed observability event — fire-and-forget AFTER the lock has been
+  // released. STATE-SDK-CONTRACT §5 (Model 3): the event tap is observability,
+  // not state. Failure here is swallowed (advisory by design).
+  //
+  // `event.emit` requires `subagentId` + `waveId` (both stable from the
+  // checkpoint context). `dedupKey` uses the file bytes + waveId so two
+  // identical refreshes within the same wave are idempotent on the event
+  // log (matches the §6 append/dedup semantics).
+  try {
+    await query('event.emit', {
+      subagentId: 'parent',
+      waveId,
+      eventType: 'agents-md.blackboard.set',
+      data: {
+        path: mergeResult?.path ?? agentsMdPath,
+        bytes: mergeResult?.bytes ?? 0,
+        seeded: !!mergeResult?.seeded,
+        wave_status: state?.frontmatter?.status ?? null,
+      },
+      dedupKey: `agents-md.blackboard.set:${waveId}:${mergeResult?.bytes ?? 0}`,
+    }, { projectRoot, subagentId: 'parent' });
+  } catch {
+    // Observability is best-effort; never demote a successful AGENTS.md
+    // rewrite because the event tap had a hiccup.
+  }
+
+  return { ok: true };
+}