@ijfw/memory-server 1.4.1 → 1.4.4

package/src/orchestrator/review.js

@@ -0,0 +1,101 @@
+/**
+ * review.js — Two-stage per-task review for the IJFW orchestrator.
+ *
+ * Stage 1: spec-compliance reviewer — confirms the diff faithfully
+ *   implements every requirement in the task spec.
+ * Stage 2: code-quality reviewer — checks correctness, security, and
+ *   project-convention adherence (runs only after Stage 1 passes).
+ *
+ * The `dispatch` parameter is injected by the caller so this module is
+ * testable without a live Agent tool. Signature:
+ *   (kind: 'spec-compliance' | 'code-quality', ctx: object)
+ *     => Promise<{ verdict: 'PASS' | 'FAIL', findings: string[] }>
+ *
+ * Landed in W10-A2 (v1.4.4 — N3).
+ */
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** Maximum re-review iterations before escalation. */
+export const REVIEW_MAX_ITERATIONS = 3;
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns true when re-review should be triggered.
+ *
+ * @param {'PASS'|'FAIL'} prevVerdict
+ * @param {number} iteration  1-based iteration count (1 = first attempt)
+ * @returns {boolean}
+ */
+export function shouldReReview(prevVerdict, iteration) {
+  return prevVerdict !== 'PASS' && iteration < REVIEW_MAX_ITERATIONS;
+}
+
+// ---------------------------------------------------------------------------
+// Main export
+// ---------------------------------------------------------------------------
+
+/**
+ * Run two-stage review for a completed task.
+ *
+ * @param {object} params
+ * @param {string} params.taskId               Blackboard task ID
+ * @param {string} params.taskSpec             Full task specification text
+ * @param {string} params.commitSha            SHA of the implementer's commit
+ * @param {string} params.branch               Branch name
+ * @param {string} [params.projectConventions] CLAUDE.md / AGENTS.md excerpt
+ * @param {Function} params.dispatch           Injected reviewer dispatcher
+ *
+ * @returns {Promise<{
+ *   ok: boolean,
+ *   stage: 'spec' | 'quality',
+ *   findings: string[]
+ * }>}
+ */
+export async function reviewTask({
+  taskId,
+  taskSpec,
+  commitSha,
+  branch,
+  projectConventions = '',
+  dispatch,
+}) {
+  // ------------------------------------------------------------------
+  // Stage 1: spec-compliance reviewer
+  // ------------------------------------------------------------------
+  const spec = await dispatch('spec-compliance', {
+    taskId,
+    taskSpec,
+    commitSha,
+    branch,
+  });
+
+  if (spec.verdict !== 'PASS') {
+    return {
+      ok: false,
+      stage: 'spec',
+      findings: spec.findings ?? [],
+    };
+  }
+
+  // ------------------------------------------------------------------
+  // Stage 2: code-quality reviewer (only runs after spec PASS)
+  // ------------------------------------------------------------------
+  const quality = await dispatch('code-quality', {
+    taskId,
+    commitSha,
+    branch,
+    projectConventions,
+  });
+
+  return {
+    ok: quality.verdict === 'PASS',
+    stage: 'quality',
+    findings: quality.findings ?? [],
+  };
+}

package/src/orchestrator/status-protocol.js

@@ -0,0 +1,168 @@
+/**
+ * status-protocol.js — 4-value agent status protocol + commit-before-report verification.
+ *
+ * Every implementer agent must end its report with:
+ *   Status: <VALUE>
+ *   Branch: <branch>
+ *   Commit: <sha>
+ *   Tests: <summary>
+ *
+ * Landed in W10-A1 (v1.4.4 N2).
+ */
+
+import { execFileSync } from 'node:child_process';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+export const STATUS_VALUES = Object.freeze([
+  'DONE',
+  'DONE_WITH_CONCERNS',
+  'NEEDS_CONTEXT',
+  'BLOCKED',
+]);
+
+// ---------------------------------------------------------------------------
+// ProtocolViolation
+// ---------------------------------------------------------------------------
+
+export class ProtocolViolation extends Error {
+  /**
+   * @param {string} reason  Human-readable explanation
+   * @param {string} raw     The original report text
+   */
+  constructor(reason, raw) {
+    super(reason);
+    this.name = 'ProtocolViolation';
+    this.reason = reason;
+    this.raw = raw;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// parseAgentReport
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse a structured agent report into its constituent fields.
+ *
+ * Required field: `Status: <VALUE>` — throws ProtocolViolation if missing or invalid.
+ * All other fields are extracted best-effort (undefined if absent).
+ *
+ * @param {string} reportText
+ * @returns {{ status: string, commit_sha?: string, branch?: string, tests?: string,
+ *             concerns?: string, reason?: string, missing?: string, tried?: string,
+ *             raw: string }}
+ * @throws {ProtocolViolation}
+ */
+export function parseAgentReport(reportText) {
+  const raw = reportText;
+
+  const statusMatch = raw.match(/^Status:\s*(\S+)\s*$/m);
+  if (!statusMatch) {
+    throw new ProtocolViolation('missing Status: line in agent report', raw);
+  }
+  const status = statusMatch[1];
+  if (!STATUS_VALUES.includes(status)) {
+    throw new ProtocolViolation(
+      `invalid status "${status}"; expected one of ${STATUS_VALUES.join(', ')}`,
+      raw,
+    );
+  }
+
+  return {
+    status,
+    commit_sha: extract(raw, 'Commit'),
+    branch:     extract(raw, 'Branch'),
+    tests:      extract(raw, 'Tests'),
+    concerns:   extract(raw, 'Concerns'),
+    reason:     extract(raw, 'Reason'),
+    missing:    extract(raw, 'Missing'),
+    tried:      extract(raw, 'Tried'),
+    raw,
+  };
+}
+
+/** Extract a single-line field value, or undefined if absent. */
+function extract(text, field) {
+  const m = text.match(new RegExp(`^${field}:\\s*(.+?)\\s*$`, 'm'));
+  return m ? m[1] : undefined;
+}
+
+// ---------------------------------------------------------------------------
+// verifyFreshCommit (internal)
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns true if the commit at `sha` was authored at or after
+ * (dispatchTimestamp - 5s tolerance).
+ *
+ * @param {string|undefined} sha
+ * @param {string|undefined} _branch  (reserved for future ref-checking)
+ * @param {number}           dispatchTimestamp  Unix seconds
+ * @param {{ projectRoot: string }} ctx
+ * @returns {boolean}
+ */
+function verifyFreshCommit(sha, _branch, dispatchTimestamp, ctx) {
+  if (!sha) return false;
+  try {
+    const out = execFileSync(
+      'git',
+      ['log', '-1', '--format=%ct', sha],
+      { cwd: ctx.projectRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] },
+    ).trim();
+    const commitTs = parseInt(out, 10);
+    if (!Number.isFinite(commitTs)) return false;
+    // r13-M-02: 5s window was too generous — let pre-existing commits pass as "fresh"
+    // when the orchestrator dispatched ~4s after a stale commit. 1s preserves
+    // minimal clock-skew tolerance. Future v1.5.0: verify commit is on the
+    // dispatched branch (tuple check), not just newer-than-dispatch.
+    return commitTs >= dispatchTimestamp - 1;
+  } catch {
+    return false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// handleStatus
+// ---------------------------------------------------------------------------
+
+/**
+ * Decide the orchestrator action based on a parsed agent report.
+ *
+ * @param {{ status: string, commit_sha?: string, branch?: string, concerns?: string,
+ *           missing?: string, reason?: string, tried?: string }} parsed
+ * @param {number}  dispatchTimestamp  Unix seconds (Date.now()/1000 at dispatch)
+ * @param {{ projectRoot: string }} ctx
+ * @returns {{ action: string, [key: string]: unknown }}
+ */
+export function handleStatus(parsed, dispatchTimestamp, ctx) {
+  switch (parsed.status) {
+    case 'DONE': {
+      const fresh = verifyFreshCommit(
+        parsed.commit_sha,
+        parsed.branch,
+        dispatchTimestamp,
+        ctx,
+      );
+      if (!fresh) {
+        return { action: 'redispatch_needs_context', missing: 'commit-before-report' };
+      }
+      return { action: 'proceed_to_review', commit_sha: parsed.commit_sha };
+    }
+
+    case 'DONE_WITH_CONCERNS':
+      return { action: 'proceed_with_flag', concerns: parsed.concerns };
+
+    case 'NEEDS_CONTEXT':
+      return { action: 'redispatch_with_context', missing: parsed.missing };
+
+    case 'BLOCKED':
+      return { action: 'escalate_to_user', reason: parsed.reason, tried: parsed.tried };
+
+    default:
+      // STATUS_VALUES is exhaustive; parseAgentReport guards this.
+      throw new ProtocolViolation(`unhandled status "${parsed.status}"`, parsed.raw ?? '');
+  }
+}

package/src/orchestrator/verification-gate.js

@@ -0,0 +1,97 @@
+/**
+ * verification-gate.js — Advisory lint: detects completion claims in a
+ * message that lack fresh verification evidence (a Bash test/build call
+ * in the same message).
+ *
+ * ADVISORY ONLY — never throws, never blocks. Returns { ok: true } or
+ * { ok: false, violation: string, claim: string }.
+ *
+ * Violations are persisted to .ijfw/memory/verification-violations.jsonl
+ * so the memory-feedback system (v1.4.1 B10) can pattern-detect over time.
+ *
+ * Landed in W10-A2 (v1.4.4 — N5).
+ */
+
+import { appendFile, mkdir } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+
+// ---------------------------------------------------------------------------
+// Detection patterns
+// ---------------------------------------------------------------------------
+
+// r13-M-01 + r13-M-04: dropped bare `complete`, lowercase `done`, AND lowercase
+// `pass(?:es)?` — all three fired falsely on common neutral language ("not yet
+// complete", "to be done in v1.5", "pass the context"). Detection list is now:
+// protocol literal `DONE`, `completed`/`shipped` (deliberate completion verbs),
+// uppercase `PASS` (verdict literal), `✅` emoji, and explicit completion phrases
+// ("all tests pass" / "build succeeded" / "deployed" / "ready to ship").
+const COMPLETION_PATTERNS = [
+  /\b(?:DONE|completed|shipped|PASS)\b/,
+  /✅/,
+  /\b(?:all tests pass|build succeeded|deployed|ready to ship)\b/i,
+];
+
+// Bash tool calls that count as fresh verification evidence.
+const VERIFICATION_COMMAND_RE =
+  /(?:npm test|node --test|cargo test|pytest|preflight|ijfw preflight|build)/i;
+
+// ---------------------------------------------------------------------------
+// Core gate
+// ---------------------------------------------------------------------------
+
+/**
+ * Check whether a message that contains a completion claim also has fresh
+ * verification evidence (a Bash tool call running tests/build).
+ *
+ * @param {string} message           Full text of the agent message.
+ * @param {Array<{tool: string, input?: {command?: string}}>} toolCallsInMessage
+ *   Tool calls that appeared in the same message turn.
+ *
+ * @returns {{ ok: true } | { ok: false, violation: string, claim: string }}
+ */
+export function checkVerificationGate(message, toolCallsInMessage) {
+  const claims = COMPLETION_PATTERNS.flatMap((p) => message.match(p) ?? []);
+  if (claims.length === 0) return { ok: true };
+
+  const verificationCalls = toolCallsInMessage.filter(
+    (t) =>
+      t.tool === 'Bash' &&
+      VERIFICATION_COMMAND_RE.test(t.input?.command ?? ''),
+  );
+
+  if (verificationCalls.length === 0) {
+    return {
+      ok: false,
+      violation: `Completion claim "${claims[0]}" without fresh verification in same message`,
+      claim: claims[0],
+    };
+  }
+
+  return { ok: true };
+}
+
+// ---------------------------------------------------------------------------
+// Violation recorder
+// ---------------------------------------------------------------------------
+
+/**
+ * Append a violation record to .ijfw/memory/verification-violations.jsonl.
+ * Auto-creates parent directories. Advisory — errors are silently swallowed
+ * so a write failure never blocks the orchestrator.
+ *
+ * @param {{ violation: string, claim: string, [key: string]: unknown }} violation
+ * @param {string} projectRoot  Absolute path to the project root.
+ * @returns {Promise<void>}
+ */
+export async function recordViolation(violation, projectRoot) {
+  const file = join(projectRoot, '.ijfw', 'memory', 'verification-violations.jsonl');
+  try {
+    await mkdir(dirname(file), { recursive: true });
+    await appendFile(
+      file,
+      JSON.stringify({ ...violation, recorded_at: new Date().toISOString() }) + '\n',
+    );
+  } catch {
+    // Advisory — never propagate write errors.
+  }
+}

package/src/orchestrator/wave-state.js

@@ -0,0 +1,255 @@
+/**
+ * wave-state.js — Atomic STATE.md read/write for orchestrator wave tracking.
+ *
+ * STATE.md lives at <projectRoot>/.ijfw/wave-<waveId>/STATE.md.
+ * Format: YAML frontmatter (---delimited) + markdown body.
+ * Writes are atomic: withFsLock + write-to-tmp + rename.
+ *
+ * Landed in W10-A0 (v1.4.4 prelude). checkpointWave is a stub;
+ * N4 (W10-A2) will flesh out the blackboard→STATE rollup logic.
+ */
+
+import { mkdir, readFile, writeFile, rename, appendFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { withFsLock } from '../fs-lock.js';
+
+// ---------------------------------------------------------------------------
+// Internal YAML helpers — flat subset only (string/number/boolean/string[])
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse a YAML frontmatter block (lines between the two `---` delimiters).
+ * Supports: scalar string/number/boolean values, arrays of strings (block style).
+ * Rejects nested maps with a clear error.
+ *
+ * @param {string} block  Lines between the two `---` markers (no delimiters)
+ * @returns {object}
+ */
+function parseYaml(block) {
+  const result = {};
+  const lines = block.split('\n');
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i];
+    if (line.trim() === '' || line.trimStart().startsWith('#')) { i++; continue; }
+
+    const colonIdx = line.indexOf(':');
+    if (colonIdx === -1) { i++; continue; }
+
+    const key = line.slice(0, colonIdx).trim();
+    const rest = line.slice(colonIdx + 1).trim();
+
+    if (!key) { i++; continue; }
+
+    // Detect nested map: next non-empty lines are indented key: value pairs
+    if (rest === '') {
+      // Could be array or nested map — peek ahead
+      const nextLines = [];
+      let j = i + 1;
+      while (j < lines.length && lines[j].trim() !== '' && !lines[j].match(/^\S.*:/)) {
+        nextLines.push(lines[j]);
+        j++;
+      }
+      if (nextLines.length > 0 && nextLines[0].trimStart().startsWith('- ')) {
+        // Block sequence
+        result[key] = nextLines.map((l) => l.replace(/^\s*-\s?/, ''));
+        i = j;
+        continue;
+      } else if (nextLines.length > 0) {
+        throw new Error(`wave-state: nested YAML maps are not supported (key: "${key}")`);
+      }
+      result[key] = null;
+      i++;
+      continue;
+    }
+
+    // Inline array: [a, b, c]
+    if (rest.startsWith('[')) {
+      const inner = rest.replace(/^\[/, '').replace(/\]$/, '');
+      result[key] = inner ? inner.split(',').map((s) => s.trim().replace(/^['"]|['"]$/g, '')) : [];
+      i++;
+      continue;
+    }
+
+    // Scalar
+    if (rest === 'true') { result[key] = true; }
+    else if (rest === 'false') { result[key] = false; }
+    else if (rest === 'null' || rest === '~') { result[key] = null; }
+    else if (!Number.isNaN(Number(rest)) && rest !== '') { result[key] = Number(rest); }
+    else { result[key] = rest.replace(/^['"]|['"]$/g, ''); }
+    i++;
+  }
+  return result;
+}
+
+/**
+ * Emit a YAML frontmatter block for flat string/number/boolean/string[] values.
+ * @param {object} obj
+ * @returns {string}  (no leading/trailing `---`)
+ */
+function emitYaml(obj) {
+  const lines = [];
+  for (const [key, val] of Object.entries(obj)) {
+    if (val === null || val === undefined) {
+      lines.push(`${key}: null`);
+    } else if (Array.isArray(val)) {
+      if (val.length === 0) {
+        lines.push(`${key}: []`);
+      } else {
+        lines.push(`${key}:`);
+        for (const item of val) lines.push(`  - ${item}`);
+      }
+    } else if (typeof val === 'boolean') {
+      lines.push(`${key}: ${val}`);
+    } else if (typeof val === 'number') {
+      lines.push(`${key}: ${val}`);
+    } else if (typeof val === 'object') {
+      throw new Error(`wave-state: nested YAML objects are not supported (key: "${key}")`);
+    } else {
+      lines.push(`${key}: ${val}`);
+    }
+  }
+  return lines.join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// Path helpers
+// ---------------------------------------------------------------------------
+
+function wavePaths(waveId, projectRoot) {
+  const dir = join(projectRoot, '.ijfw', `wave-${waveId}`);
+  return {
+    dir,
+    state: join(dir, 'STATE.md'),
+    summary: join(dir, 'SUMMARY.md'),
+    lock: join(dir, '.STATE.md.lock'),
+    summaryLock: join(dir, '.SUMMARY.md.lock'),
+    tmp: join(dir, '.STATE.md.tmp'),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Read a wave's STATE.md and return parsed { frontmatter, body, raw }.
+ * Returns null if the wave directory or file doesn't exist.
+ * Throws on malformed frontmatter.
+ *
+ * @param {string} waveId       e.g. "W10-A0"
+ * @param {string} projectRoot  absolute path to project root
+ * @returns {Promise<{frontmatter: object, body: string, raw: string} | null>}
+ */
+export async function readWaveState(waveId, projectRoot) {
+  const { state } = wavePaths(waveId, projectRoot);
+  let raw;
+  try {
+    raw = await readFile(state, 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') return null;
+    throw err;
+  }
+
+  // Parse frontmatter
+  if (!raw.startsWith('---')) {
+    throw new Error(`wave-state: STATE.md for "${waveId}" is missing YAML frontmatter`);
+  }
+  const secondDelim = raw.indexOf('\n---', 3);
+  if (secondDelim === -1) {
+    throw new Error(`wave-state: STATE.md for "${waveId}" has unclosed YAML frontmatter`);
+  }
+  const fmBlock = raw.slice(4, secondDelim); // skip "---\n"
+  const body = raw.slice(secondDelim + 4).replace(/^\n+/, ''); // skip "\n---\n\n"
+
+  const frontmatter = parseYaml(fmBlock);
+  return { frontmatter, body, raw };
+}
+
+/**
+ * Atomically write a wave's STATE.md using withFsLock + tmp+rename.
+ * Auto-creates .ijfw/wave-<waveId>/ if missing.
+ *
+ * @param {string} waveId
+ * @param {{frontmatter: object, body: string}} state
+ * @param {string} projectRoot
+ * @returns {Promise<void>}
+ */
+export async function writeWaveState(waveId, state, projectRoot) {
+  const { dir, state: statePath, lock, tmp } = wavePaths(waveId, projectRoot);
+  const payload = `---\n${emitYaml(state.frontmatter)}\n---\n\n${state.body}`;
+
+  await withFsLock(lock, async () => {
+    await mkdir(dir, { recursive: true });
+    await writeFile(tmp, payload, 'utf8');
+    await rename(tmp, statePath);
+  });
+}
+
+/**
+ * Append a delta entry to a wave's SUMMARY.md — markdown append-only log.
+ * r13-M-03 (post-Trident r13 fix): minimum-viable implementation closing the
+ * handoff §N4 promise. Full blackboard→STATE rollup remains future work for
+ * v1.5.0 (would mean reading blackboard.js claims/findings and summarising).
+ *
+ * Delta shape (caller chooses what to record):
+ *   { agent_id?, task_id?, commits?: string[], tests_delta?: string,
+ *     contracts_touched?: string[], surprises?: string }
+ *
+ * Atomic via withFsLock + appendFile. Each delta is rendered as a markdown
+ * H3 section dated by ISO timestamp; subsequent entries append below.
+ *
+ * @param {string} waveId
+ * @param {object} delta
+ * @param {string} projectRoot
+ * @returns {Promise<void>}
+ */
+export async function appendSummary(waveId, delta, projectRoot) {
+  const { dir, summary, summaryLock } = wavePaths(waveId, projectRoot);
+  const ts = new Date().toISOString();
+  const lines = [`### ${ts}`];
+  if (delta.agent_id) lines.push(`- **agent:** ${delta.agent_id}`);
+  if (delta.task_id) lines.push(`- **task:** ${delta.task_id}`);
+  if (Array.isArray(delta.commits) && delta.commits.length) {
+    lines.push(`- **commits:** ${delta.commits.join(', ')}`);
+  }
+  if (delta.tests_delta) lines.push(`- **tests:** ${delta.tests_delta}`);
+  if (Array.isArray(delta.contracts_touched) && delta.contracts_touched.length) {
+    lines.push(`- **contracts:** ${delta.contracts_touched.join(', ')}`);
+  }
+  if (delta.surprises) lines.push(`- **surprises:** ${delta.surprises}`);
+  const payload = lines.join('\n') + '\n\n';
+
+  await withFsLock(summaryLock, async () => {
+    await mkdir(dir, { recursive: true });
+    await appendFile(summary, payload, 'utf8');
+  });
+}
+
+/**
+ * Stub checkpoint — full blackboard→STATE rollup remains v1.5.0 work.
+ * Seeds an empty state if missing; updates only frontmatter.checkpoint_at.
+ *
+ * @param {string} waveId
+ * @param {string} projectRoot
+ * @returns {Promise<{frontmatter: object, body: string}>}
+ */
+export async function checkpointWave(waveId, projectRoot) {
+  const now = new Date().toISOString();
+  const existing = await readWaveState(waveId, projectRoot);
+
+  const next = existing
+    ? { frontmatter: { ...existing.frontmatter, checkpoint_at: now }, body: existing.body }
+    : {
+        frontmatter: {
+          wave_id: waveId,
+          status: 'in_progress',
+          created_at: now,
+          checkpoint_at: now,
+        },
+        body: '',
+      };
+
+  await writeWaveState(waveId, next, projectRoot);
+  return next;
+}

package/src/runtime-mediator.js

@@ -21,6 +21,10 @@ import { readFile, mkdir, appendFile, rename, stat } from 'node:fs/promises';
 import { join } from 'node:path';
 import { homedir } from 'node:os';
 
+// B18 — divergence helper imported lazily inside maybeWarnDivergence to keep
+// the module side-effect-light. detectCrossIdeDivergence has its own internal
+// stale-file cleanup + last-seen writer; we just consume the verdict.
+
 // Log rotation: when permission-events.jsonl exceeds this many lines, rename
 // to .0 (overwriting any prior .0) and start fresh. Total on disk = 2 * cap.
 const ROTATION_LINE_CAP = 10_000;
@@ -167,6 +171,33 @@ export async function logPermissionEvent(event, opts = {}) {
   }
 }
 
+/**
+ * B18 — surface a cross-IDE divergence warning on stderr (does NOT block).
+ * Called by permission-check call sites once per dispatch. Returns the
+ * divergence verdict so callers can attach `divergent_ide: true` to event
+ * log entries.
+ *
+ * Best-effort: any error returns `{ divergent: false }` and never throws.
+ *
+ * @param {{ homeDir?: string }} [opts]
+ * @returns {Promise<{ divergent: boolean, last_writer?: string|null, current_ide?: string, age_seconds?: number|null }>}
+ */
+export async function maybeWarnDivergence(opts = {}) {
+  try {
+    const { detectCrossIdeDivergence } = await import('./active-extension-writer.js');
+    const verdict = await detectCrossIdeDivergence({ homeDir: opts.homeDir });
+    if (verdict && verdict.divergent) {
+      const age = typeof verdict.age_seconds === 'number' ? `${verdict.age_seconds}s ago` : 'unknown time ago';
+      process.stderr.write(
+        `[ijfw] active extension last activated by '${verdict.last_writer}' ${age}; this IDE is '${verdict.current_ide}'\n`,
+      );
+    }
+    return verdict || { divergent: false };
+  } catch {
+    return { divergent: false };
+  }
+}
+
 /**
  * Map an MCP tool name (+ args) to the (action, target) tuple used for
  * permission checks. Returns null for unrecognised tool names; callers