@smartmemory/compose 0.2.50-beta → 0.2.51

package/server/build-routes.js

@@ -13,15 +13,36 @@
  * tests; it lets a caller inject mock `runBuild` / `abortBuild` / `getDataDir`.
  */
 
+import fs from 'node:fs';
+import path from 'node:path';
 import { runBuild as defaultRunBuild, abortBuild as defaultAbortBuild } from '../lib/build.js';
+import { runNew as defaultRunNew } from '../lib/new.js';
+import { runBuildAll as defaultRunBuildAll } from '../lib/build-all.js';
+import { runGsd as defaultRunGsd } from '../lib/gsd.js';
 import { requireSensitiveOrPaired as requireSensitiveToken } from './security.js';
-import { getDataDir as defaultGetDataDir } from './project-root.js';
+import { getDataDir as defaultGetDataDir, getTargetRoot as defaultGetTargetRoot } from './project-root.js';
 import { readBuildHistory } from '../lib/build-history.js';
 
+// A launcher conflict (another build/GSD run already owns the feature) is a
+// user-facing 409, not a 500. runBuild surfaces "already active"; runGsd
+// refuses a concurrent run ("Refusing to start a concurrent run").
+function launcherErrorStatus(err) {
+  const msg = err && err.message ? err.message : '';
+  return /already active|already running|concurrent run|refusing to start/i.test(msg) ? 409 : 500;
+}
+
 export function attachBuildRoutes(app, deps = {}) {
   const runBuild = deps.runBuild || defaultRunBuild;
   const abortBuild = deps.abortBuild || defaultAbortBuild;
+  const runNew = deps.runNew || defaultRunNew;
+  const runBuildAll = deps.runBuildAll || defaultRunBuildAll;
+  const runGsd = deps.runGsd || defaultRunGsd;
   const getDataDir = deps.getDataDir || defaultGetDataDir;
+  // Bind build dispatch to the active project root (the same global target the
+  // vision store + getDataDir() use). Without this the runners default to
+  // process.cwd(), which switchProject() does not chdir — so after a project
+  // switch the cockpit and a launched build could target different workspaces.
+  const getTargetRoot = deps.getTargetRoot || defaultGetTargetRoot;
 
   // COMP-COCKPIT-3: read-only past-builds history. No sensitive token —
   // mirrors GET /api/build/state (read-only, no secrets in the records).
@@ -38,22 +59,81 @@ export function attachBuildRoutes(app, deps = {}) {
 
   app.post('/api/build/start', requireSensitiveToken, async (req, res) => {
     const body = req.body || {};
-    const { featureCode, mode = 'feature', description = '' } = body;
-    if (!featureCode) {
+    const { featureCode, mode = 'feature', description = '', resume = false } = body;
+
+    // featureCode is required for feature/bug/gsd; 'new' takes a free-text
+    // intent (no code yet) and 'all' sweeps every PLANNED feature.
+    if (!featureCode && mode !== 'all' && mode !== 'new') {
       return res.status(400).json({ error: 'featureCode required' });
     }
-    if (mode !== 'feature' && mode !== 'bug') {
-      return res.status(400).json({ error: "mode must be 'feature' or 'bug'" });
+    if (!['feature', 'bug', 'new', 'all', 'gsd'].includes(mode)) {
+      return res.status(400).json({ error: "mode must be 'feature', 'bug', 'new', 'all', or 'gsd'" });
     }
+
+    // PARITY-2: launch the `new` lifecycle from a description (intent).
+    if (mode === 'new') {
+      const intent = (description || '').trim();
+      if (!intent) {
+        return res.status(400).json({ error: 'intent (description) required for mode=new' });
+      }
+      try {
+        const result = await runNew(intent, { cwd: getTargetRoot() });
+        return res.json(result ?? { ok: true });
+      } catch (err) {
+        return res.status(500).json({ error: err.message || String(err) });
+      }
+    }
+
+    // PARITY-8: build-all sweep.
+    if (mode === 'all') {
+      try {
+        const result = await runBuildAll({ cwd: getTargetRoot() });
+        return res.json(result ?? { ok: true });
+      } catch (err) {
+        return res.status(launcherErrorStatus(err)).json({ error: err.message || String(err) });
+      }
+    }
+
+    // PARITY-8: GSD autonomous run for a single feature.
+    if (mode === 'gsd') {
+      try {
+        const result = await runGsd(featureCode, { cwd: getTargetRoot() });
+        return res.json(result ?? { ok: true });
+      } catch (err) {
+        return res.status(launcherErrorStatus(err)).json({ error: err.message || String(err) });
+      }
+    }
+
+    // PARITY-2: resume an interrupted bug-fix flow from active-build.json.
+    let resumeFlowId = null;
+    if (resume === true) {
+      if (mode !== 'bug') {
+        return res.status(400).json({ error: 'resume is only supported for mode=bug' });
+      }
+      let active = null;
+      try {
+        const activePath = path.join(getDataDir(), 'active-build.json');
+        active = JSON.parse(fs.readFileSync(activePath, 'utf8'));
+      } catch {
+        active = null;
+      }
+      if (!active || active.featureCode !== featureCode || !active.flowId) {
+        return res.status(409).json({ error: 'no resumable build for featureCode' });
+      }
+      if (active.mode && active.mode !== 'bug') {
+        return res.status(409).json({ error: `active build is mode=${active.mode}, not resumable as bug` });
+      }
+      resumeFlowId = active.flowId;
+    }
+
     try {
       const opts = mode === 'bug'
-        ? { mode, template: 'bug-fix', description }
-        : { mode, description };
+        ? { mode, template: 'bug-fix', description, cwd: getTargetRoot(), ...(resumeFlowId ? { resumeFlowId } : {}) }
+        : { mode, description, cwd: getTargetRoot() };
       const result = await runBuild(featureCode, opts);
       res.json(result ?? { ok: true });
     } catch (err) {
-      const code = /already active/i.test(err && err.message ? err.message : '') ? 409 : 500;
-      res.status(code).json({ error: err.message || String(err) });
+      res.status(launcherErrorStatus(err)).json({ error: err.message || String(err) });
     }
   });
 

package/server/build-stream-bridge.js

@@ -471,6 +471,18 @@ export class BuildStreamBridge {
         };
       }
 
+      // COMP-TEST-BOOTSTRAP-4-1: advisory review of the tests the coverage step
+      // generated this build. Forwarded so the cockpit can surface the findings
+      // for human verification (the step never blocks ship).
+      case 'test_review':
+        return {
+          type: 'system', subtype: 'test_review',
+          clean: event.clean ?? true,
+          summary: event.summary ?? '',
+          findings: event.findings ?? [],
+          _source: 'build',
+        };
+
       // COMP-HEALTH item 118: health score after build completion
       case 'health_score':
         return {

package/server/compose-mcp-tools.js

@@ -359,10 +359,82 @@ export async function toolProposeFollowup(args) {
   // propose_followup also accepts a caller-supplied `status` and routes to
   // addRoadmapEntry — gate lifecycle-owned terminal statuses the same way.
   assertTerminalStatusAuthorized(args, 'propose_followup');
-  const { proposeFollowup } = await import('../lib/followup-writer.js');
+  let proposeFollowup;
+  try {
+    ({ proposeFollowup } = await import('../lib/followup-writer.js'));
+  } catch (err) {
+    // COMP-MCP-FOLLOWUP-1: a long-running stdio MCP server caches ESM module
+    // records. If lib/ changed under it (e.g. a later commit added an export
+    // this lazily-imported module now depends on), linking fails with a cryptic
+    // "does not provide an export named ..." even though the on-disk code is
+    // correct — the running server just needs to reload. Rethrow with an
+    // actionable hint instead of the raw ESM error.
+    if (/does not provide an export named|Cannot find module/i.test(err?.message || '')) {
+      const hint = new Error(
+        `propose_followup could not load lib/followup-writer.js: ${err.message}. ` +
+        `This usually means the compose MCP server is running stale code (module-cache skew after a ` +
+        `code change) — reconnect the MCP server (/mcp) to reload it. If it persists after reconnecting, ` +
+        `an export is genuinely missing on disk.`,
+      );
+      hint.cause = err;
+      throw hint;
+    }
+    throw err;
+  }
   return proposeFollowup(getTargetRoot(), args);
 }
 
+// ---------------------------------------------------------------------------
+// Eager boot-time module preload — COMP-MCP-FOLLOWUP-1-1
+// ---------------------------------------------------------------------------
+
+/**
+ * Modules reachable only via a lazy `import()` on a hot tool path, which
+ * therefore escape boot-time ESM linking. Eager-importing them at server start
+ * makes a genuine on-disk break (missing module OR missing export) fail fast at
+ * boot instead of surfacing on first tool invocation — complementing the
+ * COMP-MCP-FOLLOWUP-1 CI import-graph test.
+ *
+ * The default set is exactly one module: `lib/followup-writer.js`, lazily
+ * imported by `toolProposeFollowup`. Its own dynamic import
+ * (`server/artifact-manager.js`) is already statically imported at the top of
+ * this file, so it links at boot regardless — no need to list it here.
+ */
+export const EAGER_PRELOAD_MODULES = [
+  { specifier: '../lib/followup-writer.js', expect: 'proposeFollowup' },
+];
+
+/**
+ * Eagerly import each spec and assert its expected export is a function.
+ * Throws (naming the offending module) on a missing module or missing export.
+ *
+ * `await import()` does NOT throw when a module loads but no longer provides the
+ * expected named export — it resolves with that binding `undefined`. So the
+ * binding check, not the import alone, is what turns a missing export into a
+ * boot failure (the exact COMP-MCP-FOLLOWUP-1 failure class).
+ *
+ * `specs` is injectable for testing and for the `COMPOSE_PRELOAD_PROBE` boot
+ * seam; entries without an `expect` are import-only checks.
+ */
+export async function preloadEagerModules(specs = EAGER_PRELOAD_MODULES) {
+  const loaded = {};
+  for (const { specifier, expect } of specs) {
+    let mod;
+    try {
+      mod = await import(specifier);
+    } catch (err) {
+      throw new Error(`eager preload failed for ${specifier}: ${err.message}`, { cause: err });
+    }
+    if (expect && typeof mod[expect] !== 'function') {
+      throw new Error(
+        `eager preload failed for ${specifier}: expected export '${expect}' to be a function, got ${typeof mod[expect]}`,
+      );
+    }
+    loaded[specifier] = mod;
+  }
+  return loaded;
+}
+
 // ---------------------------------------------------------------------------
 // Checkpoints / resume — COMP-RESUME
 // ---------------------------------------------------------------------------

package/server/compose-mcp.js

@@ -26,6 +26,7 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { writeSync } from 'node:fs';
 import {
   toolGetVisionItems,
   toolGetRoadmap,
@@ -71,6 +72,8 @@ import {
   assertToolPhaseAllowed,
   _getSessionProfile,
   resolveBoundPhase,
+  preloadEagerModules,
+  EAGER_PRELOAD_MODULES,
 } from './compose-mcp-tools.js';
 import { isToolAllowed } from './mcp-tool-policy.js';
 import { switchProject, getTargetRoot, loadProjectConfig } from './project-root.js';
@@ -817,6 +820,30 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 // Start
 // ---------------------------------------------------------------------------
 
+// COMP-MCP-FOLLOWUP-1-1: eager-preload lazily-imported hot-path modules so a
+// genuine on-disk break (missing module/export) fails fast at boot instead of
+// on first tool call. COMPOSE_PRELOAD_PROBE is an ops/test seam: comma-separated
+// entries appended to the default set, each `specifier` or `specifier#export`
+// (the `#export` form also exercises the export assertion). Absent → default.
+const probeExtra = (process.env.COMPOSE_PRELOAD_PROBE || '')
+  .split(',')
+  .map((s) => s.trim())
+  .filter(Boolean)
+  .map((entry) => {
+    const hash = entry.indexOf('#');
+    return hash === -1
+      ? { specifier: entry }
+      : { specifier: entry.slice(0, hash), expect: entry.slice(hash + 1) };
+  });
+try {
+  await preloadEagerModules([...EAGER_PRELOAD_MODULES, ...probeExtra]);
+} catch (err) {
+  // writeSync (not stderr.write) so the line is guaranteed flushed before
+  // process.exit — an async pipe write can otherwise be truncated/dropped.
+  writeSync(2, `[compose-mcp] boot aborted: ${err.message}\n`);
+  process.exit(1);
+}
+
 const transport = new StdioServerTransport();
 await server.connect(transport);
 // Server runs until stdin closes — no explicit exit needed

package/server/feature-scaffold-routes.js

@@ -0,0 +1,82 @@
+/**
+ * feature-scaffold-routes.js — POST /api/features/scaffold.
+ *
+ * Cockpit equivalent of `compose feature <CODE>`: scaffolds docs/features/<CODE>/
+ * (feature.json + seed design.md) and the ROADMAP.md row. Reuses the typed writer
+ * addRoadmapEntry (lib/feature-writer.js) — never reimplements scaffolding and
+ * never echoes the regenerated roadmap back (the lib return is already compact).
+ *
+ * Sensitive (mutating). attachFeatureScaffoldRoutes(app, deps?) — deps is for tests.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { requireSensitiveOrPaired as requireSensitiveToken } from './security.js';
+import { addRoadmapEntry as defaultAddRoadmapEntry } from '../lib/feature-writer.js';
+import { isFeatureCode } from '../lib/feature-code.js';
+import { getTargetRoot as defaultGetProjectRoot } from './project-root.js';
+import { resolveFeaturesPathFromConfig, relForDisplay } from '../lib/project-paths.js';
+
+const DEFAULT_PHASE = 'Backlog';
+
+export function attachFeatureScaffoldRoutes(app, deps = {}) {
+  const addRoadmapEntry = deps.addRoadmapEntry || defaultAddRoadmapEntry;
+  const getProjectRoot = deps.getProjectRoot || defaultGetProjectRoot;
+
+  app.post('/api/features/scaffold', requireSensitiveToken, async (req, res) => {
+    const body = req.body || {};
+    const code = typeof body.code === 'string' ? body.code.trim().toUpperCase() : '';
+    const description = typeof body.description === 'string' ? body.description.trim() : '';
+    const phase = (typeof body.phase === 'string' && body.phase.trim())
+      || (typeof body.group === 'string' && body.group.trim())
+      || DEFAULT_PHASE;
+
+    if (!isFeatureCode(code)) {
+      return res.status(400).json({ error: 'Invalid feature code (e.g. COMP-FOO-1)' });
+    }
+    if (!description) {
+      return res.status(400).json({ error: 'description is required' });
+    }
+
+    const projectRoot = getProjectRoot();
+    try {
+      // 1. feature.json + ROADMAP.md row (compact return — no roadmap echo).
+      const result = await addRoadmapEntry(projectRoot, { code, description, phase });
+
+      // 2. Seed design.md stub (addRoadmapEntry does not write it). Idempotent.
+      //    Resolve the ABSOLUTE features dir (may be relocated) — mirror ideabox.
+      let featurePath = null;
+      try {
+        const composeJsonPath = path.join(projectRoot, '.compose', 'compose.json');
+        let cfg = {};
+        if (fs.existsSync(composeJsonPath)) {
+          try { cfg = JSON.parse(fs.readFileSync(composeJsonPath, 'utf-8')); } catch { /* default cfg */ }
+        }
+        const featuresBase = resolveFeaturesPathFromConfig(projectRoot, cfg);
+        const featureDir = path.join(featuresBase, code);
+        const designPath = path.join(featureDir, 'design.md');
+        if (!fs.existsSync(designPath)) {
+          const today = new Date().toISOString().slice(0, 10);
+          fs.mkdirSync(featureDir, { recursive: true });
+          fs.writeFileSync(designPath,
+            `# ${code}: ${description}\n\n**Status:** PLANNED\n**Created:** ${today}\n\n---\n\n## Intent\n\n${description}\n\n---\n\n## Notes\n\n_Seed design doc created by the New Feature dialog. \`compose build\` will expand it._\n`);
+        }
+        featurePath = relForDisplay(projectRoot, featureDir);
+      } catch { /* design seed is best-effort; feature.json + roadmap already written */ }
+
+      // COMPACT result — never the full roadmap (memory: MCP add_roadmap_entry echo
+      // blows the token cap; the lib return is small, keep it small here too).
+      return res.json({
+        ok: true,
+        code: result.code,
+        phase: result.phase,
+        position: result.position,
+        roadmap_path: result.roadmap_path,
+        featurePath,
+      });
+    } catch (err) {
+      const msg = err && err.message ? err.message : String(err);
+      const code409 = /already exists/i.test(msg);
+      return res.status(code409 ? 409 : 400).json({ error: msg });
+    }
+  });
+}

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 });
+  });
+}