@smartmemory/compose 0.3.7 → 0.3.8

package/server/decision-event-emit.js

@@ -21,6 +21,7 @@ import {
   iterationDecisionEventId,
   gateDecisionEventId,
   driftThresholdDecisionEventId,
+  policyViolationDecisionEventId,
 } from './decision-event-id.js';
 import { mapResolveOutcomeToSchema } from './gate-log-store.js';
 
@@ -43,13 +44,15 @@ export function emitDecisionEvent(broadcastMessage, event) {
 /**
  * Build a kind=phase_transition DecisionEvent.
  *
- * @param {{ featureCode, from, to, outcome, agent_id, timestamp }} params
+ * @param {{ featureCode, from, to, outcome, agent_id, timestamp, origin, recordedAt, confidence }} params
  *   - from: previous phase string, or null for the initial lifecycle start
  *   - to: new phase string
  *   - outcome: optional outcome string (for context)
  *   - agent_id: optional operator/agent identifier
  */
-export function buildPhaseTransitionEvent({ featureCode, from, to, outcome, agent_id, timestamp }) {
+export function buildPhaseTransitionEvent({
+  featureCode, from, to, outcome, agent_id, timestamp, origin, recordedAt, confidence,
+}) {
   const now = timestamp || new Date().toISOString();
   const fromStr = from == null ? 'null' : String(from);
   const id = phaseTransitionDecisionEventId(featureCode, from, to, now);
@@ -64,6 +67,9 @@ export function buildPhaseTransitionEvent({ featureCode, from, to, outcome, agen
     metadata: {
       from_phase: fromStr,
       to_phase: String(to),
+      ...(origin !== undefined ? { origin } : {}),
+      ...(recordedAt !== undefined ? { recorded_at: recordedAt } : {}),
+      ...(confidence !== undefined ? { confidence } : {}),
     },
     roles: [{ name: 'PRODUCER', agent_id: agent_id || null }],
   };
@@ -173,3 +179,36 @@ export function buildGateEvent({ featureCode, gateLogEntryId, gateId, decision,
     roles: [],
   };
 }
+
+/**
+ * Build a kind=policy_violation DecisionEvent (COMP-POLICY-CHECK-5).
+ *
+ * CONTRACT: first-class kind since `contracts/comp-obs-contract.schema.json`
+ * v0.2.6 (2026-08-17) — closed metadata subschema {step_id, rule, matched,
+ * suppressed, user_mode, build_id}. Keep the emitted shape and the subschema in
+ * lockstep; extending either is a versioned contract edit.
+ *
+ * @param {{ featureCode, buildId, stepId, rule, matched, suppressed, userMode, timestamp }} params
+ */
+export function buildPolicyViolationEvent({
+  featureCode, buildId, stepId, rule, matched, suppressed, userMode, timestamp,
+}) {
+  const now = timestamp || new Date().toISOString();
+  const id = policyViolationDecisionEventId(featureCode, buildId ?? 'no-build', stepId, rule, matched);
+  return {
+    id,
+    feature_code: featureCode,
+    timestamp: now,
+    kind: 'policy_violation',
+    title: `${suppressed ? 'Policy match suppressed' : 'Policy violation'}: ${rule}`,
+    metadata: {
+      step_id: stepId,
+      rule,
+      matched,
+      suppressed: Boolean(suppressed),
+      user_mode: userMode,
+      build_id: buildId ?? null,
+    },
+    roles: [],
+  };
+}

package/server/decision-event-id.js

@@ -62,3 +62,20 @@ export function driftThresholdDecisionEventId(featureCode, axisId, breachStarted
   const featureNs = uuidv5(String(featureCode), ROOT_NAMESPACE);
   return uuidv5(`drift_threshold:${axisId}:${breachStartedAtIso}`, featureNs);
 }
+
+/**
+ * Deterministic id for a policy_violation DecisionEvent (COMP-POLICY-CHECK-5).
+ * Unique per (featureCode, buildId, stepId, rule, matched pattern) so a replayed
+ * build-stream line re-derives the same id and the timeline stays deduplicated.
+ *
+ * @param {string} featureCode
+ * @param {string} buildId
+ * @param {string} stepId
+ * @param {string} ruleName
+ * @param {string} matched — the pattern text that matched
+ * @returns {string} UUID v5
+ */
+export function policyViolationDecisionEventId(featureCode, buildId, stepId, ruleName, matched) {
+  const featureNs = uuidv5(String(featureCode), ROOT_NAMESPACE);
+  return uuidv5(`policy_violation:${buildId}:${stepId}:${ruleName}:${matched}`, featureNs);
+}

package/server/decision-events-snapshot.js

@@ -53,6 +53,9 @@ export function deriveDecisionEvents(state, featureCode) {
         outcome: entry.outcome,
         agent_id: entry.agent_id || null,
         timestamp: entry.timestamp,
+        origin: entry.origin,
+        recordedAt: entry.recordedAt,
+        confidence: entry.confidence,
       }));
     }
 

package/server/design-routes.js

@@ -16,7 +16,7 @@ import { randomUUID } from 'node:crypto';
 import { parseDecisionBlocks } from '../src/components/vision/designSessionState.js';
 import { StratumMcpClient } from '../lib/stratum-mcp-client.js';
 import { KNOWN_VERSIONS } from '../lib/build-stream-schema.js';
-import { getTargetRoot, resolveProjectPath } from './project-root.js';
+import { getTargetRoot, resolveProjectPath, trackProjectWork } from './project-root.js';
 import { resolveStratumMcpConnection } from '../lib/stratum-engine.js';
 import { relForDisplay } from '../lib/project-paths.js';
 
@@ -50,11 +50,11 @@ async function _getStratum(root = getTargetRoot(), { factory } = {}) {
 // Test-only export: exercise the root-keyed connect/cache without a live server.
 export { _getStratum as _getDesignStratumForTest };
 
-/** Tear down every cached Stratum connection. Tests should call this in after(). */
-export async function closeDesignStratum() {
-  const clients = [..._stratumClients.values()];
-  _stratumClients.clear();
-  _stratumConnectPromises.clear();
+/** Tear down an evicted workspace's connection, or all connections at shutdown. */
+export async function closeDesignStratum(projectRoot) {
+  const keys = projectRoot === undefined ? [..._stratumConnectPromises.keys()] : [projectRoot];
+  const clients = keys.map(key => _stratumClients.get(key)).filter(Boolean);
+  for (const key of keys) { _stratumClients.delete(key); _stratumConnectPromises.delete(key); }
   for (const c of clients) {
     try { await c.close(); } catch { /* ignore */ }
   }
@@ -66,6 +66,12 @@ export const designListeners = new Map();
 /** In-flight guard — prevents overlapping agent runs for the same session. */
 const _inFlight = new Set();
 
+export function hasDesignWork(projectRoot) {
+  const prefix = `${projectRoot}:`;
+  return [..._inFlight].some(key => key.startsWith(prefix))
+    || [...designListeners].some(([key, clients]) => key.startsWith(prefix) && clients.size > 0);
+}
+
 /**
  * Build a session key for SSE listener scoping.
  * @param {string} scope
@@ -384,7 +390,7 @@ export function attachDesignRoutes(app, { getSessionManager, getProjectRoot }) {
   });
 
   // POST /api/design/complete — generate design doc and mark session complete
-  app.post('/api/design/complete', async (req, res) => {
+  app.post('/api/design/complete', (req, res) => trackProjectWork(async () => {
     const { scope, featureCode, draftDoc } = req.body || {};
     try {
       const sessionManager = getSessionManager();
@@ -528,7 +534,7 @@ Output ONLY the Markdown content, no code fences.`;
       }
       res.status(400).json({ error: err.message });
     }
-  });
+  }));
 
   // POST /api/design/revise — mark a decision as superseded and re-ask
   app.post('/api/design/revise', (req, res) => {

package/server/feature-scan.js

@@ -18,6 +18,8 @@ import path from 'node:path';
 import { parse as parseYaml } from 'yaml';
 import { getTargetRoot, resolveProjectPath } from './project-root.js';
 import { relForDisplay } from '../lib/project-paths.js';
+import { featureStatusToVisionStatus } from '../lib/status-projection.js';
+import { VERIFIED_BY } from './completion-projection.js';
 import { assertValidLinkShape } from '../lib/feature-write-guard.js';
 import { depsToEdges } from '../lib/roadmap-graph/model.js';
 
@@ -175,7 +177,9 @@ export function scanFeatures(featuresDir) {
       const specPath = path.join(featureDir, 'feature.json');
       if (fs.existsSync(specPath)) {
         feature.hasFeatureJson = true;
+        feature.featureJsonUnreadable = true; // cleared once the parse succeeds
         const spec = JSON.parse(fs.readFileSync(specPath, 'utf-8'));
+        feature.featureJsonUnreadable = false;
         if (typeof spec.group === 'string' && spec.group.trim()) {
           feature.group = spec.group.trim();
         }
@@ -185,6 +189,7 @@ export function scanFeatures(featuresDir) {
         // it (COMP-ROADMAP-GRAPH-2: kills the feature.json/cockpit status de-sync).
         if (typeof spec.status === 'string' && spec.status.trim()) {
           feature.status = normalizeStatus(spec.status);
+          feature.canonicalStatus = spec.status.trim().toUpperCase();
         }
       }
     } catch { /* ignore malformed feature.json */ }
@@ -473,6 +478,33 @@ export function writeFeatureGroupToDisk(item, newGroup, featuresDir) {
  * @param {object} store — VisionStore instance
  * @returns {{ features: number, updated: number, connections: number }}
  */
+/**
+ * The synchronous startup tier for a scanned `complete` feature (§2.3b).
+ * @returns {{status:string, completion_projection?:object}}
+ */
+function seedCompletionTier(feature) {
+  if (feature.canonicalStatus === 'COMPLETE') {
+    return {
+      status: 'complete',
+      completion_projection: { verified_by: VERIFIED_BY.CANONICAL, at: new Date().toISOString(), source: 'startup-scan' },
+    };
+  }
+  if (!feature.hasFeatureJson) {
+    // No feature.json at all: the scanner inferred completion from documents
+    // (report.md present, design.md prose). Weakest tier — and the ONLY case
+    // that gets it. This is what "unmanaged" means (§2.3b round 5).
+    return {
+      status: 'complete',
+      completion_projection: { verified_by: VERIFIED_BY.DOCUMENT, at: new Date().toISOString(), source: 'startup-scan' },
+    };
+  }
+  // A feature.json exists and does not say COMPLETE — malformed, or valid with
+  // no status while the documents claim completion. Canon wins: a managed
+  // feature is never seeded complete on document evidence (Codex r1 #4).
+  if (feature.featureJsonUnreadable) return { status: 'planned' };
+  return { status: featureStatusToVisionStatus(feature.canonicalStatus) || 'planned' };
+}
+
 export function seedFeatures(features, store) {
   const seeded = { features: 0, updated: 0, connections: 0 };
   const featureItemMap = new Map(); // featureCode → itemId
@@ -489,11 +521,23 @@ export function seedFeatures(features, store) {
     );
 
     if (!featureItem) {
+      // COMP-COMPLETION-GATE slice 3 (AC-4d, AC-16a, AC-16b): startup seeding is
+      // synchronous and pre-listen, so it does not consult the guard (§2.3b,
+      // round 5). A `complete` status is projected through the same predicate
+      // as every other transport — on canonical feature.json alone, stamped
+      // `canonical-status-only`, or `document-derived` for an unmanaged folder
+      // (no feature.json; the scanner inferred completion from report.md or doc
+      // metadata). That is display state, never a completion compose vouches
+      // for. A folder whose documents say complete but whose feature.json does
+      // NOT is created as its feature.json says.
+      const projected = feature.status === 'complete'
+        ? seedCompletionTier(feature)
+        : { status: feature.status || 'planned' };
       featureItem = store.createItem({
         type: 'feature',
         title: feature.name,
         description: feature.description || '',
-        status: feature.status || 'planned',
+        status: projected.status,
         phase: feature.phase || 'planning',
         confidence: feature.confidence,
         files: feature.artifacts.map(a => artifactPath(feature, a)),
@@ -503,6 +547,9 @@ export function seedFeatures(features, store) {
       try {
         store.updateLifecycle(featureItem.id, { featureCode: feature.name, currentPhase: 'explore_design' });
       } catch { /* lifecycle method may not exist */ }
+      if (projected.completion_projection) {
+        store.updateItem(featureItem.id, { completion_projection: projected.completion_projection });
+      }
       featureItem = store.items.get(featureItem.id);
       seeded.features++;
     } else {
@@ -511,8 +558,35 @@ export function seedFeatures(features, store) {
       if (feature.description && feature.description !== featureItem.description) {
         updates.description = feature.description;
       }
+      // A complete item is RE-VERIFIED on every scan, not only when its status
+      // differs (Codex r1 #5, r2 #2): an item stamped when canon was valid must
+      // be downgraded if canon is later corrupted or loses its status, and an
+      // item complete before tiers existed must gain its stamp.
+      if (feature.status === 'complete' && featureItem.status === 'complete') {
+        const projected = seedCompletionTier(feature);
+        if (projected.status !== 'complete') {
+          updates.status = projected.status;
+          updates.completion_projection = null;
+        } else if (!featureItem.completion_projection
+            || featureItem.completion_projection.verified_by !== projected.completion_projection.verified_by) {
+          updates.completion_projection = projected.completion_projection;
+        }
+      }
       if (feature.status && feature.status !== featureItem.status) {
-        updates.status = feature.status;
+        if (feature.status === 'complete') {
+          const projected = seedCompletionTier(feature);
+          if (projected.status === 'complete') {
+            updates.status = 'complete';
+            updates.completion_projection = projected.completion_projection;
+          } else if (projected.status !== featureItem.status) {
+            updates.status = projected.status;
+          }
+        } else {
+          updates.status = feature.status;
+          // Leaving complete for any recognized status: the stamp is a claim
+          // about a completion that canon no longer records (Codex r3).
+          if (featureItem.completion_projection) updates.completion_projection = null;
+        }
       }
       if (feature.confidence > (featureItem.confidence || 0)) {
         updates.confidence = feature.confidence;

package/server/file-watcher.js

@@ -10,9 +10,13 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { getTargetRoot, loadProjectConfig, ensureDataDir } from './project-root.js';
-import { resolveDocsPathFromConfig, resolveFeaturesPathFromConfig } from '../lib/project-paths.js';
+import {
+  resolveDocsPathFromConfig,
+  resolveFeaturesPathFromConfig,
+  resolveIdeaboxPathFromConfig,
+  relForDisplay,
+} from '../lib/project-paths.js';
 
-const PROJECT_ROOT = getTargetRoot();
 
 /**
  * fs.watch fileFilter for the pipelines/ watch (COMP-PIPE-EDIT-6): only
@@ -32,8 +36,77 @@ export function buildSpecChangedMessage(file, relativePath) {
   return { type: 'specChanged', file, path: relativePath };
 }
 
+/** Coalescing window for the ideabox-projection watch. */
+export const IDEABOX_COALESCE_MS = 100;
+
+/**
+ * fs.watch fileFilter for the ideabox-projection watch (IDEA-24). That watch is
+ * NON-recursive on the projection's own parent directory, so `filename` is a bare
+ * name and exact equality is the whole test.
+ *
+ * Exact equality, not a suffix or basename match, because `render-ideabox.js`
+ * publishes atomically through `.ideabox.md.tmp.<uuid>` in the SAME directory. A
+ * looser predicate would fire on the temp file — announcing an update before the
+ * rename that makes it real, and a second time after.
+ */
+export function isIdeaboxProjectionFile(filename, projectionBasename) {
+  return typeof filename === 'string'
+    && typeof projectionBasename === 'string'
+    && projectionBasename.length > 0
+    && filename === projectionBasename;
+}
+
+/**
+ * Shape of the vision-WS `ideaboxUpdated` broadcast raised by the projection
+ * watch (IDEA-24).
+ *
+ * `type` is byte-identical to what `server/ideabox-routes.js` broadcasts, because
+ * both ideabox clients compare `msg.type === 'ideaboxUpdated'` and nothing else —
+ * a differently-named event would be silently ignored, which is the bug this
+ * closes. `timestamp` matches the route's shape so one channel carries one shape;
+ * `source` exists so a WS log distinguishes a route-driven update from a
+ * file-driven one, which is precisely the diagnosis that was missing here.
+ */
+export function buildIdeaboxUpdatedMessage(relativePath) {
+  return {
+    type: 'ideaboxUpdated',
+    source: 'projection-watch',
+    path: relativePath,
+    timestamp: new Date().toISOString(),
+  };
+}
+
+/**
+ * Fire `fn` once, `waitMs` after the LAST call. TRAILING, unlike the
+ * leading-edge-and-drop debounce the other watches use, and the difference is
+ * the whole point.
+ *
+ * A leading-edge debounce announces the first write of a burst and discards the
+ * rest — so the cockpit ends up showing the state at the START of the burst and
+ * never hears about the end of it. That is the same "your list is stale until
+ * you reload" bug IDEA-24 exists to close, just at a 100ms timescale, and it is
+ * reachable from two `compose ideabox add` calls in quick succession.
+ *
+ * For a NOTIFICATION the last event is the one that must survive; the payload
+ * is a re-fetch, so intermediate events carry nothing worth delivering. One
+ * broadcast per logical write, always reflecting final state, ~waitMs late.
+ */
+export function createTrailingDebouncer(fn, waitMs) {
+  let timer = null;
+  return {
+    trigger() {
+      if (timer) clearTimeout(timer);
+      timer = setTimeout(() => { timer = null; fn(); }, waitMs);
+    },
+    cancel() {
+      if (timer) { clearTimeout(timer); timer = null; }
+    },
+  };
+}
+
 export class FileWatcherServer {
-  constructor() {
+  constructor({ projectRoot = getTargetRoot() } = {}) {
+    this.projectRoot = projectRoot;
     this.clients = new Set();
     this.wss = null;
     this.watchers = [];
@@ -41,8 +114,8 @@ export class FileWatcherServer {
 
   /** Resolve and validate a relative path stays within project root */
   safePath(relativePath) {
-    const resolved = path.resolve(PROJECT_ROOT, relativePath);
-    if (!resolved.startsWith(PROJECT_ROOT + path.sep) && resolved !== PROJECT_ROOT) {
+    const resolved = path.resolve(this.projectRoot, relativePath);
+    if (!resolved.startsWith(this.projectRoot + path.sep) && resolved !== this.projectRoot) {
       return null;
     }
     return resolved;
@@ -89,7 +162,7 @@ export class FileWatcherServer {
       const config = loadProjectConfig();
       const docsPrefix = config.paths?.docs || 'docs';
       // COMP-PATHS-EXTERNAL: list the RESOLVED docs dir (may be relocated).
-      const docsDir = resolveDocsPathFromConfig(PROJECT_ROOT, config);
+      const docsDir = resolveDocsPathFromConfig(this.projectRoot, config);
       try {
         const files = this.listMarkdownFiles(docsDir, docsPrefix);
         res.json({ files });
@@ -174,26 +247,44 @@ export class FileWatcherServer {
   startWatching() {
     const debounceMap = new Map();
 
-    const watchDir = (dir, prefix, onChanged, fileFilter = (f) => f.endsWith('.md')) => {
+    /**
+     * @param {object} [opts]
+     * @param {boolean} [opts.recursive=true] fs.watch recursion.
+     * @param {number} [opts.debounceMs=100] leading-edge suppression window.
+     *
+     *   PASS 0 FOR ANY WATCH OVER AN ALREADY-WATCHED FILE. `debounceMap` is
+     *   shared across every watchDir call and keyed by the prefixed relative
+     *   path, so two watches whose dir+prefix resolve to the SAME relative path
+     *   for one file suppress each other: whichever fs.watch delivers second
+     *   inside the window is silently dropped, and which one that is depends on
+     *   the OS. (That already happens between `docs/` and `docs/features/`; it is
+     *   left exactly as it was rather than changed underneath callers here.) 0
+     *   opts out of the shared map entirely — for a watch that coalesces its own
+     *   events, which is the only reason to be in that position.
+     */
+    const watchDir = (dir, prefix, onChanged, fileFilter = (f) => f.endsWith('.md'), opts = {}) => {
+      const { recursive = true, debounceMs = 100 } = opts;
       if (!fs.existsSync(dir)) {
         console.warn(`[file-watcher] ${prefix}/ directory not found, skipping watch`);
         return;
       }
       try {
-        const watcher = fs.watch(dir, { recursive: true }, (eventType, filename) => {
+        const watcher = fs.watch(dir, { recursive }, (eventType, filename) => {
           if (!filename || !fileFilter(filename)) return;
 
           const relativePath = path.join(prefix, filename);
           // COMP-PATHS-EXTERNAL: derive the real path from the WATCHED dir, not
-          // by re-rooting under PROJECT_ROOT — the dir may be relocated outside
+          // by re-rooting under this.projectRoot — the dir may be relocated outside
           // the workspace. Byte-identical to the old form for an in-root dir.
           const fullPath = path.join(dir, filename);
 
-          // Debounce: ignore events within 100ms of each other for the same file
-          const now = Date.now();
-          const lastEvent = debounceMap.get(relativePath);
-          if (lastEvent && now - lastEvent < 100) return;
-          debounceMap.set(relativePath, now);
+          // Debounce: ignore events within debounceMs of each other for the same file
+          if (debounceMs > 0) {
+            const now = Date.now();
+            const lastEvent = debounceMap.get(relativePath);
+            if (lastEvent && now - lastEvent < debounceMs) return;
+            debounceMap.set(relativePath, now);
+          }
 
           onChanged(relativePath, fullPath);
         });
@@ -204,10 +295,10 @@ export class FileWatcherServer {
     };
 
     // Watch docs/ — broadcast fileChanged events. COMP-PATHS-EXTERNAL: watch
-    // the RESOLVED absolute dir (may be relocated outside PROJECT_ROOT).
+    // the RESOLVED absolute dir (may be relocated outside this.projectRoot).
     const config = loadProjectConfig();
     const docsPrefix = config.paths?.docs || 'docs';
-    watchDir(resolveDocsPathFromConfig(PROJECT_ROOT, config), docsPrefix, (relativePath, fullPath) => {
+    watchDir(resolveDocsPathFromConfig(this.projectRoot, config), docsPrefix, (relativePath, fullPath) => {
       try {
         if (!fs.existsSync(fullPath)) return;
         const content = fs.readFileSync(fullPath, 'utf-8');
@@ -219,9 +310,9 @@ export class FileWatcherServer {
 
     // Watch features/ — notify for auto-reseed into vision store
     const featuresPrefix = config.paths?.features || 'docs/features';
-    watchDir(resolveFeaturesPathFromConfig(PROJECT_ROOT, config), featuresPrefix, (relativePath, fullPath) => {
+    watchDir(resolveFeaturesPathFromConfig(this.projectRoot, config), featuresPrefix, (relativePath, fullPath) => {
       // Also broadcast as fileChanged (features are docs). fullPath comes from
-      // the watched dir (COMP-PATHS-EXTERNAL) — do not re-root under PROJECT_ROOT.
+      // the watched dir (COMP-PATHS-EXTERNAL) — do not re-root under this.projectRoot.
       try {
         if (fs.existsSync(fullPath)) {
           const content = fs.readFileSync(fullPath, 'utf-8');
@@ -241,16 +332,67 @@ export class FileWatcherServer {
     // `fileChanged` on this server's /ws/files. The payload carries `file` as a
     // BASENAME because editorSpecFile is a bare filename (a prefixed relative path
     // would never match the store's compare).
-    const pipelinesDir = path.join(PROJECT_ROOT, 'pipelines');
+    const pipelinesDir = path.join(this.projectRoot, 'pipelines');
     watchDir(pipelinesDir, 'pipelines', (relativePath, fullPath) => {
       if (typeof this.onSpecChanged === 'function') {
         this.onSpecChanged(buildSpecChangedMessage(path.basename(fullPath), relativePath));
       }
     }, isStratumSpecFile);
 
+    // Watch the ideabox projection → `ideaboxUpdated` on the VISION WS (IDEA-24).
+    //
+    // A CLI ideabox write goes straight to the record store; it never reaches
+    // `server/ideabox-routes.js`, which is the only thing that broadcasts. So an
+    // open cockpit or mobile client kept showing the pre-write list until someone
+    // reloaded it by hand. The `fileChanged` this file already emits for the same
+    // write goes out on /ws/files, which neither ideabox client subscribes to.
+    //
+    // THE PROJECTION IS THE TRIGGER, NOT THE PAYLOAD. Clients respond by
+    // re-fetching GET /api/ideabox, which reads RECORDS — the markdown is never
+    // parsed to serve a read (COMP-PLAN-IDEA-UNIFY D21). The projection is used
+    // only as the signal, and it is a sound one because `ideabox-ops.js`
+    // guarantees the record is durable BEFORE the render: an event from this
+    // watch can never arrive ahead of the data the re-fetch will return.
+    //
+    // Two consequences, both accepted:
+    //  - An API-driven mutation broadcasts twice (the route's own, then this
+    //    one). The re-fetch is idempotent, and suppressing the echo would need a
+    //    "did I just write this?" mtime handshake — a race, to save one GET.
+    //  - A write whose render FAILED does not notify. That is the
+    //    `projectionStale` path: the writer is already told, and `compose ideabox
+    //    render` both repairs the file and fires this watch.
+    //
+    // Watched NON-recursively on the projection's own parent so a relocated
+    // `paths.ideabox` outside `paths.docs` still works.
+    const ideaboxPath = resolveIdeaboxPathFromConfig(this.projectRoot, config);
+    const ideaboxDir = path.dirname(ideaboxPath);
+    // The projection's directory may not exist yet in a project that has never
+    // rendered one. Create it, or the watch is skipped and the very first CLI
+    // write — the one most likely to be watched for — silently does not refresh.
+    try { fs.mkdirSync(ideaboxDir, { recursive: true }); } catch { /* read-only tree — watchDir skips */ }
+    //
+    // Raw fs events are coalesced by a TRAILING debouncer rather than the
+    // leading-edge one `watchDir` applies (hence `debounceMs: 0`): see
+    // `createTrailingDebouncer` for why the LAST event is the one that has to
+    // survive here. That also folds the rename+change pair of a single atomic
+    // publish into one broadcast.
+    const ideaboxRelative = relForDisplay(this.projectRoot, ideaboxPath);
+    this._ideaboxDebouncer = createTrailingDebouncer(() => {
+      if (typeof this.onIdeaboxChanged === 'function') {
+        this.onIdeaboxChanged(buildIdeaboxUpdatedMessage(ideaboxRelative));
+      }
+    }, IDEABOX_COALESCE_MS);
+    watchDir(
+      ideaboxDir,
+      relForDisplay(this.projectRoot, ideaboxDir),
+      () => this._ideaboxDebouncer.trigger(),
+      (f) => isIdeaboxProjectionFile(f, path.basename(ideaboxPath)),
+      { recursive: false, debounceMs: 0 },
+    );
+
     // Watch .compose/data/ for active-build.json changes
     const self = this;
-    const dataDir = path.join(PROJECT_ROOT, '.compose', 'data');
+    const dataDir = path.join(this.projectRoot, '.compose', 'data');
     let dataDirWatcherRegistered = false;
 
     // Guarantee .compose/data/ exists before registering the watcher
@@ -309,11 +451,18 @@ export class FileWatcherServer {
     return results;
   }
 
-  close() {
+  stopWatching() {
     for (const watcher of this.watchers) {
       watcher.close();
     }
+    // AFTER the watchers: cancelling first would leave a window in which a last
+    // fs event re-arms the timer, and a pending timer holds the event loop open.
+    this._ideaboxDebouncer?.cancel();
     this.watchers = [];
+  }
+
+  close() {
+    this.stopWatching();
     for (const client of this.clients) {
       client.close();
     }