@smartmemory/compose 0.2.49-beta → 0.2.51-beta

package/server/health-routes.js

@@ -0,0 +1,261 @@
+/**
+ * health-routes.js — Read-only environment-health REST API (COMP-PARITY-3).
+ *
+ * Routes:
+ *   GET  /api/environment-health — surfaces `compose doctor` (external-dep
+ *     presence + version drift) and `compose hooks status` (git-hook drift) as
+ *     structured JSON for the cockpit's header health-dot + popover.
+ *   POST /api/environment-health/repair-hooks (COMP-PARITY-3-1) — guarded,
+ *     local, idempotent remediation: runs `compose hooks install --post-commit
+ *     --pre-push --workspace=<id>` (+ `--force` when body.force) in the request
+ *     workspace, then returns the recomputed hook states. Mutating → gated by
+ *     requireSensitiveOrPaired. Dependency installs and `compose update` are
+ *     deliberately NOT executed server-side (the panel surfaces command text).
+ *
+ * Deliberately NOT under `/api/health/*`: that prefix is in the remote auth
+ * allowlist (server/index.js + auth-middleware.js prefix-match), so nesting
+ * here would make local dependency inventory and `?refresh` registry fetches
+ * publicly reachable in remote mode. This path is non-allowlisted → default-deny
+ * in remote mode (sensitive token / paired JWT), open on localhost.
+ *
+ * Degrade-never-fail: each section is computed defensively; a failing sub-check
+ * becomes `{ unavailable: true }` (deps/binaries/hooks) or `null` (version).
+ * The endpoint never 500s on a sub-check.
+ *
+ * Reuses (no logic fork):
+ *   - lib/deps.js          — dep/binary presence (off the compose PACKAGE_ROOT)
+ *   - lib/version-check.js — version drift (off PACKAGE_ROOT + homedir cache)
+ *   - lib/hooks-status.js  — git-hook drift (off the request's workspace root)
+ */
+import { join, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+
+import {
+  loadDeps,
+  checkExternalSkills,
+  buildDepReport,
+  checkExternalBinaries,
+  buildBinaryReport,
+} from '../lib/deps.js';
+import { checkLatestVersion } from '../lib/version-check.js';
+import { computeHooksStatus } from '../lib/hooks-status.js';
+import { requireSensitiveOrPaired as requireSensitiveToken } from './security.js';
+
+/** The compose package root (where .compose-deps.json + package.json live). */
+const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+function safe(fn, fallback) {
+  try {
+    return fn();
+  } catch {
+    return fallback;
+  }
+}
+
+/**
+ * Map a raw hook status (from computeHooksStatus) to the API-facing shape.
+ * The key honesty rule: an installed-current hook whose workspace id could not
+ * be verified (expectedWsId was null) is reported as `workspace-unverified`,
+ * never a false `installed-current`.
+ */
+export function hookRawToApi(raw) {
+  if (!raw || typeof raw !== 'object') return { state: 'unavailable' };
+  if (raw.state === 'installed-current') {
+    return raw.wsVerified
+      ? { state: 'installed-current', workspace: raw.bakedWorkspace ?? null }
+      : { state: 'workspace-unverified' };
+  }
+  if (raw.state === 'installed-stale') {
+    const out = { state: 'installed-stale', reason: raw.reason ?? null };
+    if (raw.reason === 'STALE_WORKSPACE_ID') out.expected = { workspaceId: raw.expectedWorkspace ?? null };
+    return out;
+  }
+  return { state: raw.state }; // 'absent' | 'foreign'
+}
+
+/**
+ * Worst-wins summary rollup driving the header dot color.
+ *   error: any required dep/binary missing OR any hook `foreign`
+ *   warn:  version behind OR hook installed-stale/workspace-unverified OR
+ *          optional dep/binary missing OR a section is unavailable
+ *   ok:    everything present/current/up-to-date (version null & hook absent are neutral)
+ */
+export function rollupSummary({ dependencies, binaries, version, hooks }) {
+  let error = false;
+  let warn = false;
+
+  for (const section of [dependencies, binaries]) {
+    if (!section) continue;
+    if (section.unavailable) {
+      warn = true;
+      continue;
+    }
+    for (const d of section.missing || []) {
+      if (d.optional) warn = true;
+      else error = true;
+    }
+  }
+
+  if (version && version.behind) warn = true;
+
+  if (hooks && hooks.unavailable) {
+    warn = true;
+  } else {
+    for (const h of Object.values(hooks || {})) {
+      if (h?.state === 'foreign') error = true;
+      else if (h?.state === 'installed-stale' || h?.state === 'workspace-unverified') warn = true;
+    }
+  }
+
+  return error ? 'error' : warn ? 'warn' : 'ok';
+}
+
+/**
+ * Default command runner: spawn `node <composeBin> <args...>` synchronously in
+ * the given cwd. Injectable via attachHealthRoutes so tests can stub it without
+ * shelling out. Returns a normalized `{ status, stdout, stderr, error }` so the
+ * route never has to know about spawnSync's shape and never throws on failure.
+ *
+ * @param {object} opts
+ * @param {string} opts.composeNode — node binary to run compose with
+ * @param {string} opts.composeBin  — path to bin/compose.js
+ * @param {string[]} opts.args      — compose CLI args (e.g. ['hooks','install',…])
+ * @param {string} opts.cwd         — working directory (the workspace root)
+ * @returns {{status:number|null, stdout:string, stderr:string, error:string|null}}
+ */
+function defaultRunCommand({ composeNode, composeBin, args, cwd }) {
+  const r = spawnSync(composeNode, [composeBin, ...args], {
+    cwd,
+    encoding: 'utf-8',
+    timeout: 30000,
+  });
+  return {
+    status: r.status,
+    stdout: r.stdout || '',
+    stderr: r.stderr || '',
+    error: r.error ? r.error.message : null,
+  };
+}
+
+/**
+ * @param {import('express').Express} app
+ * @param {object} [deps]
+ * @param {string} [deps.packageRoot] — compose package root (default: resolved from this module)
+ * @param {string} [deps.composeBin]  — expected COMPOSE_BIN baked in hooks
+ * @param {string} [deps.composeNode] — expected COMPOSE_NODE baked in hooks
+ * @param {Function} [deps.runCommand] — injectable command runner (default: spawnSync-based)
+ */
+export function attachHealthRoutes(app, {
+  packageRoot = PACKAGE_ROOT,
+  composeBin = join(PACKAGE_ROOT, 'bin', 'compose.js'),
+  composeNode = process.execPath,
+  runCommand = defaultRunCommand,
+} = {}) {
+  app.get('/api/environment-health', async (req, res) => {
+    // --- dependencies + binaries (compose install) ---------------------------
+    let dependencies;
+    let binaries;
+    const deps = safe(() => loadDeps(packageRoot), null);
+    if (!deps) {
+      // loadDeps returns null (not throws) on a missing/invalid manifest — must
+      // branch explicitly; the checkers would throw or mislead on a null deps.
+      dependencies = { unavailable: true };
+      binaries = { unavailable: true };
+    } else {
+      dependencies = safe(() => {
+        // Drop scannedPaths — it leaks absolute host filesystem paths
+        // (e.g. ~/.claude/...) the UI doesn't need; this route is remotely
+        // reachable when paired. The contract is {present, missing}.
+        const { scannedPaths, ...rest } = buildDepReport(checkExternalSkills(deps));
+        return rest;
+      }, { unavailable: true });
+      binaries = safe(() => buildBinaryReport(checkExternalBinaries(deps)), { unavailable: true });
+    }
+
+    // --- version drift (compose install + homedir cache) ---------------------
+    let version = null;
+    try {
+      const current = JSON.parse(readFileSync(join(packageRoot, 'package.json'), 'utf-8')).version;
+      version = await checkLatestVersion(current, { force: req.query.refresh === '1' });
+    } catch {
+      version = null;
+    }
+
+    // --- git hooks (this request's workspace) --------------------------------
+    let hooks;
+    try {
+      const root = req.workspace?.root;
+      if (!root) throw new Error('no workspace root');
+      const raw = computeHooksStatus({
+        projectRoot: root,
+        expectedWsId: req.workspace?.id ?? null,
+        composeNode,
+        composeBin,
+      });
+      hooks = {};
+      for (const [type, r] of Object.entries(raw)) hooks[type] = hookRawToApi(r);
+    } catch {
+      hooks = { unavailable: true };
+    }
+
+    const summary = rollupSummary({ dependencies, binaries, version, hooks });
+    res.json({ summary, dependencies, binaries, version, hooks });
+  });
+
+  // --- POST /api/environment-health/repair-hooks (COMP-PARITY-3-1) ----------
+  // Guarded, local, idempotent remediation. Only the hook repair is executed
+  // server-side; dependency installs and `compose update` are intentionally NOT
+  // run here (the panel surfaces their command text instead).
+  app.post('/api/environment-health/repair-hooks', requireSensitiveToken, (req, res) => {
+    const root = req.workspace?.root;
+    const wsId = req.workspace?.id ?? null;
+    if (!root) {
+      // No workspace to operate in — a guarded failure, not a 500.
+      return res.json({ ok: false, error: 'no workspace root', stderr: '' });
+    }
+
+    const force = req.body && req.body.force === true;
+    const args = ['hooks', 'install', '--post-commit', '--pre-push'];
+    if (wsId != null) args.push(`--workspace=${wsId}`);
+    if (force) args.push('--force');
+    const ranCommand = `compose ${args.join(' ')}`;
+
+    // Run the repair. The runner normalizes spawnSync's shape and never throws;
+    // a non-zero exit / spawn error becomes { ok:false }, never a 500.
+    let result;
+    try {
+      result = runCommand({ composeNode, composeBin, args, cwd: root });
+    } catch (e) {
+      return res.json({ ok: false, error: e?.message || 'command failed', stderr: '' });
+    }
+
+    const failed = result.error != null || (result.status != null && result.status !== 0);
+    if (failed) {
+      return res.json({
+        ok: false,
+        error: result.error || `compose hooks install exited with status ${result.status}`,
+        stderr: result.stderr || '',
+        ranCommand,
+      });
+    }
+
+    // Recompute hook states so the panel can refresh from the response (or refetch).
+    let hooks;
+    try {
+      const raw = computeHooksStatus({
+        projectRoot: root,
+        expectedWsId: wsId,
+        composeNode,
+        composeBin,
+      });
+      hooks = {};
+      for (const [type, r] of Object.entries(raw)) hooks[type] = hookRawToApi(r);
+    } catch {
+      hooks = { unavailable: true };
+    }
+
+    res.json({ ok: true, ranCommand, hooks });
+  });
+}

package/server/ideabox-routes.js

@@ -25,6 +25,7 @@ import {
 } from '../lib/ideabox.js'
 import { writeFeature } from '../lib/feature-json.js'
 import { IdeaboxCache } from './ideabox-cache.js'
+import { resolveIdeaboxPathFromConfig, resolveFeaturesPathFromConfig, relForDisplay } from '../lib/project-paths.js'
 
 /**
  * @param {object} app              — Express app
@@ -41,8 +42,7 @@ export function attachIdeaboxRoutes(app, { getProjectRoot, getDataDir, broadcast
     const dataDir = getDataDir()
     if (!_cache || _lastProjectRoot !== projectRoot || _lastDataDir !== dataDir) {
       const config = loadConfig(projectRoot)
-      const ideaboxRel = config?.paths?.ideabox || 'docs/product/ideabox.md'
-      const sourceFile = path.join(projectRoot, ideaboxRel)
+      const sourceFile = resolveIdeaboxPathFromConfig(projectRoot, config)
       _cache = new IdeaboxCache(dataDir, sourceFile)
       _lastProjectRoot = projectRoot
       _lastDataDir = dataDir
@@ -172,16 +172,17 @@ export function attachIdeaboxRoutes(app, { getProjectRoot, getDataDir, broadcast
         resolvedCode = `IDEA-${sourceIdea.num}-${slug}`.toUpperCase()
       }
 
-      // Create feature folder + feature.json (same logic as CLI promote)
+      // Create feature folder + feature.json (same logic as CLI promote).
+      // COMP-PATHS-EXTERNAL: resolve the ABSOLUTE features base (may be
+      // relocated outside projectRoot). Re-rooting under projectRoot would make
+      // existsSync check the wrong path and risk overwriting external canon.
       const composeJsonPath = path.join(projectRoot, '.compose', 'compose.json')
-      let featuresRel = 'docs/features'
+      let cfg = {}
       if (fs.existsSync(composeJsonPath)) {
-        try {
-          const cfg = JSON.parse(fs.readFileSync(composeJsonPath, 'utf-8'))
-          featuresRel = cfg?.paths?.features || 'docs/features'
-        } catch {}
+        try { cfg = JSON.parse(fs.readFileSync(composeJsonPath, 'utf-8')) } catch {}
       }
-      const featuresDir = path.join(projectRoot, featuresRel, resolvedCode)
+      const featuresBase = resolveFeaturesPathFromConfig(projectRoot, cfg)  // absolute
+      const featuresDir = path.join(featuresBase, resolvedCode)
       if (!fs.existsSync(featuresDir)) {
         // COMP-MCP-VALIDATE-1: route through the validated writer instead of a
         // raw fs.writeFileSync so the promoted feature.json is schema-guarded.
@@ -191,7 +192,7 @@ export function attachIdeaboxRoutes(app, { getProjectRoot, getDataDir, broadcast
           status: 'PLANNED',
           promotedFrom: sourceIdea.id,
           createdAt: new Date().toISOString(),
-        }, featuresRel)
+        }, featuresBase)
       }
 
       promoteIdea(parsed, id, resolvedCode)
@@ -200,7 +201,7 @@ export function attachIdeaboxRoutes(app, { getProjectRoot, getDataDir, broadcast
       broadcastUpdate()
 
       const updated = parsed.ideas.find(i => i.id.toUpperCase() === upper)
-      res.json({ ...(updated || { id }), featureCode: resolvedCode, featurePath: `${featuresRel}/${resolvedCode}` })
+      res.json({ ...(updated || { id }), featureCode: resolvedCode, featurePath: relForDisplay(projectRoot, featuresDir) })
     } catch (err) {
       const status = err.message.includes('not found') ? 404 : 500
       res.status(status).json({ error: err.message })

package/server/project-root.js

@@ -15,6 +15,7 @@ import path from 'node:path';
 import fs from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { findProjectRoot } from './find-root.js';
+import { DEFAULT_PATHS, resolvePathValue } from '../lib/paths-core.js';
 
 export { findProjectRoot } from './find-root.js';
 
@@ -99,7 +100,7 @@ export function ensureDataDir() {
 const DEFAULT_CONFIG = Object.freeze({
   version: 1,
   capabilities: Object.freeze({ stratum: true, lifecycle: true }),
-  paths: Object.freeze({ docs: 'docs', features: 'docs/features', journal: 'docs/journal' }),
+  paths: DEFAULT_PATHS,                        // single source of truth (COMP-PATHS-EXTERNAL)
 });
 
 function cloneConfig(obj) {
@@ -120,9 +121,11 @@ export function loadProjectConfig() {
 
 export function resolveProjectPath(key) {
   const config = loadProjectConfig();
-  const rel = config.paths?.[key];
-  if (!rel) return path.join(getTargetRoot(), DEFAULT_CONFIG.paths[key] || key);
-  return path.join(getTargetRoot(), rel);
+  // resolvePathValue handles in-root / ../-escaping / absolute overrides.
+  // Preserve the legacy `|| key` fallback for keys absent from DEFAULT_PATHS.
+  // (COMP-PATHS-EXTERNAL)
+  const value = config.paths?.[key] ?? DEFAULT_PATHS[key] ?? key;
+  return resolvePathValue(getTargetRoot(), value, key);
 }
 
 /**

package/server/qa-scope-routes.js

@@ -0,0 +1,96 @@
+/**
+ * qa-scope-routes.js — Read-only QA-scope REST API (COMP-PARITY-10).
+ *
+ * Route:
+ *   GET /api/qa-scope?featureCode=<CODE> — surfaces `compose qa-scope <CODE>`
+ *     (diff-to-route mapping from COMP-QA) as structured JSON for the cockpit's
+ *     QA Scope view. Maps the feature's recorded filesChanged → affected /
+ *     adjacent routes via lib/qa-scoping.js. Read-only, no side effects.
+ *
+ * Not auth-gated (mirrors GET /api/environment-health): it reads only
+ * feature.json + heuristic route mapping, no host paths leaked, no mutation.
+ *
+ * Degrade-never-fail: a bad feature code or unreadable feature.json returns a
+ * structured { found:false } / empty result, never a 500.
+ *
+ * Reuses (no logic fork):
+ *   - lib/feature-json.js  — readFeature(cwd, code)
+ *   - lib/qa-scoping.js    — mapFilesToRoutes(filesChanged,{cwd}), classifyRoutes(routes,[])
+ */
+import { readFeature as defaultReadFeature } from '../lib/feature-json.js';
+import {
+  mapFilesToRoutes as defaultMapFilesToRoutes,
+  classifyRoutes as defaultClassifyRoutes,
+} from '../lib/qa-scoping.js';
+
+/**
+ * @param {import('express').Express} app
+ * @param {object} [deps]
+ * @param {Function} [deps.readFeature]      — (cwd, code) => FeatureJson|null
+ * @param {Function} [deps.mapFilesToRoutes] — (filesChanged, {cwd}) => {affectedRoutes,unmappedFiles,framework,docsOnly}
+ * @param {Function} [deps.classifyRoutes]   — (routes, allKnown) => {affected,adjacent}
+ */
+export function attachQaScopeRoutes(app, {
+  readFeature = defaultReadFeature,
+  mapFilesToRoutes = defaultMapFilesToRoutes,
+  classifyRoutes = defaultClassifyRoutes,
+} = {}) {
+  app.get('/api/qa-scope', (req, res) => {
+    const featureCode = (req.query.featureCode || '').toString().trim();
+    if (!featureCode) {
+      return res.json({ found: false, error: 'featureCode required' });
+    }
+
+    const root = req.workspace?.root;
+    if (!root) {
+      return res.json({ found: false, error: 'no workspace root', featureCode });
+    }
+
+    let feature;
+    try {
+      feature = readFeature(root, featureCode);
+    } catch {
+      feature = null;
+    }
+    if (!feature) {
+      return res.json({ found: false, featureCode });
+    }
+
+    const filesChanged = feature.filesChanged ?? [];
+    if (filesChanged.length === 0) {
+      // Mirror the CLI's empty-diff guidance (bin/compose.js:2716-2719).
+      return res.json({
+        found: true,
+        featureCode,
+        filesChanged: [],
+        framework: 'unknown',
+        docsOnly: false,
+        affected: [],
+        adjacent: [],
+        unmappedFiles: [],
+        emptyDiff: true,
+      });
+    }
+
+    // Same pipeline as the CLI (bin/compose.js:2722-2724); allKnown=[] (v1: no registry).
+    let result, classified;
+    try {
+      result = mapFilesToRoutes(filesChanged, { cwd: root });
+      classified = classifyRoutes(result.affectedRoutes, []);
+    } catch (e) {
+      return res.json({ found: true, featureCode, error: e?.message || 'qa-scope failed' });
+    }
+
+    res.json({
+      found: true,
+      featureCode,
+      filesChanged,
+      framework: result.framework,
+      docsOnly: result.docsOnly,
+      affected: classified.affected,
+      adjacent: classified.adjacent,
+      unmappedFiles: result.unmappedFiles,
+      emptyDiff: false,
+    });
+  });
+}

package/server/session-routes.js

@@ -11,7 +11,7 @@
 
 import path from 'node:path';
 import { readSessionsByFeature } from './session-store.js';
-import { getTargetRoot, getDataDir } from './project-root.js';
+import { getTargetRoot, getDataDir, resolveProjectPath } from './project-root.js';
 import { appendPhaseHistory } from './lifecycle-phase-history.js';
 import { reconcile } from '../lib/checkpoint/reconciler.js';
 import { checkpointConfig } from '../lib/checkpoint/checkpoint-writer.js';
@@ -140,7 +140,7 @@ export function attachSessionRoutes(app, { sessionManager, scheduleBroadcast, br
         featureCode,
         item,
         cwd: targetRoot,
-        featureDir: path.join(targetRoot, 'docs', 'features', featureCode),
+        featureDir: path.join(resolveProjectPath('features'), featureCode),
         composeDir: path.join(targetRoot, '.compose'),
         dataDir,
         store: cpStore,

package/server/stratum-sync.js

@@ -2,7 +2,19 @@
  * stratum-sync.js — Stratum flow poller + route registration.
  *
  * Polls stratum flow state via stratum-client (not direct file reads) and syncs
- * into the vision store every 15 seconds.
+ * into the vision store on a self-scheduling, sleep-aware loop.
+ *
+ * Sleep behavior: each poll cold-starts a `stratum-mcp` subprocess (Python
+ * interpreter spin-up — the expensive part, not the query itself). Doing that
+ * every few seconds generated enough periodic activity to keep the host from
+ * sleeping. Two mitigations:
+ *   1. Cadence widened to 60s (override with COMPOSE_STRATUM_POLL_MS).
+ *   2. The spawn is skipped entirely when no bound flow can still change state
+ *      (`hasLiveFlows`), so an idle/finished Forge does zero periodic spawning
+ *      and the host is free to sleep. The cheap in-memory scan that gates this
+ *      holds no power assertion.
+ * On wake, a tick that fired far later than scheduled is treated as a
+ * post-sleep resync rather than business as usual.
  *
  * Routes: POST /api/stratum/bind, POST /api/stratum/audit/:itemId
  * (Flow/gate query routes are now in stratum-api.js)
@@ -10,6 +22,38 @@
 
 import { queryFlows } from './stratum-client.js';
 
+// Poll cadence. 60s is plenty for a flow list (slower than any build step) and
+// keeps periodic process-spawn activity low enough not to fight host sleep.
+const DEFAULT_POLL_MS = 60_000;
+const MIN_POLL_MS = 1_000;
+const POLL_MS = (() => {
+  const raw = parseInt(process.env.COMPOSE_STRATUM_POLL_MS ?? '', 10);
+  return Number.isFinite(raw) && raw >= MIN_POLL_MS ? raw : DEFAULT_POLL_MS;
+})();
+// A tick that fires later than POLL_MS * this factor means the host slept
+// through scheduled ticks — log it and treat the next sync as a wake resync.
+const WAKE_GAP_FACTOR = 1.5;
+
+/**
+ * Sleep-aware poll gate: true only when some bound vision item could still
+ * change state (i.e. is bound to a flow and not settled-`complete`). When this
+ * is false the poller skips the stratum-mcp spawn so an idle host can sleep.
+ *
+ * A bound `complete` item is steady-state (status only advances to `complete`
+ * via the audit route, never back), so polling it changes nothing. Anything
+ * else bound — `in_progress`, `blocked`, or mid-flight — can still transition
+ * and is worth a poll.
+ *
+ * @param {Iterable<{stratumFlowId?: string, status?: string}>} items
+ * @returns {boolean}
+ */
+export function hasLiveFlows(items) {
+  for (const item of items) {
+    if (item.stratumFlowId && item.status !== 'complete') return true;
+  }
+  return false;
+}
+
 // ---------------------------------------------------------------------------
 // StratumSync class
 // ---------------------------------------------------------------------------
@@ -18,6 +62,8 @@ export class StratumSync {
   #store;
   #scheduleBroadcast;
   #pollTimer = null;
+  #stopped = true;
+  #lastTickAt = 0;
 
   /**
    * @param {object} store — VisionStore instance
@@ -28,23 +74,53 @@ export class StratumSync {
     this.#scheduleBroadcast = scheduleBroadcast;
   }
 
-  /** Start the 15s polling interval. */
+  /** Start the self-scheduling, sleep-aware poll loop (default 60s). */
   start() {
-    this.#pollTimer = setInterval(() => {
-      this.#syncFlows().catch(err => {
-        console.error('[vision] Stratum poll error:', err.message);
-      });
-    }, 15_000);
+    this.#stopped = false;
+    this.#lastTickAt = Date.now();
+    this.#scheduleNext();
   }
 
-  /** Stop the polling interval. */
+  /** Stop the poll loop. */
   stop() {
+    this.#stopped = true;
     if (this.#pollTimer) {
-      clearInterval(this.#pollTimer);
+      clearTimeout(this.#pollTimer);
       this.#pollTimer = null;
     }
   }
 
+  /** Arm the next tick. No-op once stopped so stop() is final. */
+  #scheduleNext() {
+    if (this.#stopped) return;
+    this.#pollTimer = setTimeout(() => this.#tick(), POLL_MS);
+  }
+
+  /**
+   * One poll tick. Skips the stratum-mcp spawn when nothing is live (lets the
+   * host sleep); on a tick that fired far later than scheduled, notes the
+   * sleep gap before resyncing.
+   */
+  async #tick() {
+    if (this.#stopped) return;
+    const now = Date.now();
+    const gap = now - this.#lastTickAt;
+    this.#lastTickAt = now;
+
+    if (hasLiveFlows(this.#store.items.values())) {
+      if (gap > POLL_MS * WAKE_GAP_FACTOR) {
+        console.log(`[vision] Stratum sync resuming after ${Math.round(gap / 1000)}s gap (host likely slept) — resyncing`);
+      }
+      try {
+        await this.#syncFlows();
+      } catch (err) {
+        console.error('[vision] Stratum poll error:', err.message);
+      }
+    }
+
+    this.#scheduleNext();
+  }
+
   /**
    * Fetch flow summaries via stratum-client (stable contract, not direct file reads).
    * Maps stratum's query output to the shape the sync logic expects.

package/server/validate-routes.js

@@ -0,0 +1,70 @@
+/**
+ * validate-routes.js — Read-only cross-artifact validation REST API (COMP-PARITY-6).
+ *
+ * Route:
+ *   GET /api/validate?scope=feature|project&featureCode=<CODE>
+ *     Surfaces `compose validate` (lib/feature-validator.js validateFeature/
+ *     validateProject) as structured JSON for the cockpit Validate view.
+ *     Read-only; local-only (no network xref resolution); degrades, never 500s.
+ *
+ * Deliberately NOT under an auth-allowlisted prefix (mirrors health-routes.js):
+ * non-allowlisted → default-deny in remote mode, open on localhost.
+ *
+ * Reuses (no logic fork): lib/feature-validator.js validateFeature/validateProject.
+ */
+import {
+  validateFeature as defaultValidateFeature,
+  validateProject as defaultValidateProject,
+} from '../lib/feature-validator.js';
+
+const SEVERITIES = ['error', 'warning', 'info'];
+
+/** Group a findings array into { error: n, warning: n, info: n }. */
+export function summarizeFindings(findings = []) {
+  const by = { error: 0, warning: 0, info: 0 };
+  for (const f of findings) {
+    if (by[f?.severity] !== undefined) by[f.severity] += 1;
+  }
+  return by;
+}
+
+/**
+ * @param {import('express').Express} app
+ * @param {object} [deps]
+ * @param {Function} [deps.validateFeature] — injectable (default: lib validator)
+ * @param {Function} [deps.validateProject] — injectable (default: lib validator)
+ */
+export function attachValidateRoutes(app, {
+  validateFeature = defaultValidateFeature,
+  validateProject = defaultValidateProject,
+} = {}) {
+  app.get('/api/validate', async (req, res) => {
+    const root = req.workspace?.root;
+    if (!root) {
+      // No workspace to validate — a guarded failure, not a 500.
+      return res.json({ scope: null, findings: [], bySeverity: summarizeFindings([]), unavailable: true });
+    }
+    const scope = req.query.scope === 'feature' ? 'feature' : 'project';
+    const featureCode = typeof req.query.featureCode === 'string' ? req.query.featureCode : null;
+
+    if (scope === 'feature' && !featureCode) {
+      return res.status(400).json({ error: 'scope=feature requires featureCode' });
+    }
+
+    try {
+      const result = scope === 'feature'
+        ? await validateFeature(root, featureCode)        // local-only; no `external`
+        : await validateProject(root, {});                // local-only; no `external`
+      const findings = Array.isArray(result.findings) ? result.findings : [];
+      // Pass the validator result through verbatim + add the severity rollup.
+      return res.json({ ...result, bySeverity: summarizeFindings(findings) });
+    } catch (err) {
+      // validateCode throws INVALID_INPUT on a malformed feature code → 400.
+      if (err && err.code === 'INVALID_INPUT') {
+        return res.status(400).json({ error: err.message });
+      }
+      // Any other failure degrades to a non-500 unavailable body.
+      return res.json({ scope, feature_code: featureCode, findings: [], bySeverity: summarizeFindings([]), unavailable: true, error: err?.message || 'validate failed' });
+    }
+  });
+}