mcp-coordinator 0.4.0 → 0.5.0

package/README.md

@@ -666,6 +666,20 @@ Resolution priority (highest to lowest): CLI flag → env var → config.json
 | `COORDINATOR_ADMIN_SECRET` | — | Separate secret for admin token creation |
 | `MAX_QUOTA_PCT` | `95` | Pre-flight abort threshold for Anthropic quota |
 
+### Environment variables (v0.6)
+
+| Variable | Default | Effect |
+|---|---|---|
+| `COORDINATOR_REPO_ROOT` | (unset → team-mode) | Repo root for path-guard, FS fallback, Layer 4 |
+| `COORDINATOR_MAX_BODY_BYTES` | `1048576` | parseBody hard cap |
+| `COORDINATOR_LAYER4_DENYLIST` | (uses defaults) | Comma-separated globs appended to denylist |
+| `COORDINATOR_LAYER4_SINCE_DAYS` | `7` | git log --since window |
+| `COORDINATOR_LAYER4_MAX_COMMITS` | `2000` | git log --max-count |
+| `COORDINATOR_LAYER4_REFRESH_INTERVAL_MS` | `1800000` | Refresh on success |
+| `COORDINATOR_LAYER4_RETRY_MS` | `300000` | Retry on timeout |
+| `COORDINATOR_WORKING_FILES_TTL_MIN` | `30` | working_files claim TTL |
+| `COORDINATOR_WORKING_FILES_SWEEP_INTERVAL_MS` | `60000` | TTL sweeper tick |
+
 ---
 
 ## Structured Logging

package/dashboard/public/index.html

@@ -217,6 +217,16 @@
       <div id="token-total"></div>
       <div id="token-agents"></div>
 
+      <div class="panel-title" style="margin-top:16px;">Conflict signals (24h)</div>
+      <div id="conflict-signals">
+        <div class="metric"><span class="metric-label">L0 announced</span><span class="metric-value" data-layer="L0">—</span></div>
+        <div class="metric"><span class="metric-label">L1 same file</span><span class="metric-value" data-layer="L1">—</span></div>
+        <div class="metric"><span class="metric-label">L0.5 disjoint</span><span class="metric-value" data-layer="L0.5">—</span></div>
+        <div class="metric"><span class="metric-label">L2 depends_on</span><span class="metric-value" data-layer="L2">—</span></div>
+        <div class="metric"><span class="metric-label">L3 module</span><span class="metric-value" data-layer="L3">—</span></div>
+        <div class="metric"><span class="metric-label">L4 co-change</span><span class="metric-value" data-layer="L4">—</span></div>
+      </div>
+
       <div class="panel-title" style="margin-top:16px;">Configuration</div>
       <div id="run-config">
         <div style="color:#64748b;font-size:12px;">Aucun run actif</div>
@@ -1171,6 +1181,19 @@
     // Fetch config on load
     fetch(`${COORDINATOR_URL}/api/run-config`).then(r => r.json()).then(renderRunConfig).catch(() => {});
 
+    async function refreshConflictSignals() {
+      try {
+        const r = await fetch(`${COORDINATOR_URL}/api/scoring-stats?since=24h`);
+        const j = await r.json();
+        for (const layer of j.layers) {
+          const el = document.querySelector(`[data-layer="${layer.layer}"]`);
+          if (el) el.textContent = layer.fire_count;
+        }
+      } catch {}
+    }
+    refreshConflictSignals();
+    setInterval(refreshConflictSignals, 30000);
+
     connectSSE();
     updateAgents();
   </script>

package/dist/cli/server/start.js

@@ -8,7 +8,32 @@ export function createServerStartCommand() {
         .option("--port <port>", "Server port")
         .option("--data-dir <path>", "Data directory")
         .option("--daemon", "Run as background daemon")
+        .option("--repo-root <path>", "Project repo root (enables Layer 4 + FS fallback). Default env COORDINATOR_REPO_ROOT.")
+        .option("--max-body-bytes <bytes>", "Max HTTP request body in bytes. Default 1048576.")
+        .option("--working-files-ttl-min <minutes>", "TTL for working_files claims. Default 30.")
+        .option("--working-files-sweep-ms <ms>", "TTL sweeper tick interval. Default 60000.")
+        .option("--layer4-since-days <days>", "git log --since window. Default 7.")
+        .option("--layer4-max-commits <count>", "git log --max-count. Default 2000.")
+        .option("--layer4-refresh-ms <ms>", "Layer 4 successful-build refresh interval. Default 1800000.")
+        .option("--layer4-retry-ms <ms>", "Layer 4 retry interval on timeout. Default 300000.")
         .action(async (opts) => {
+        // Wire CLI flags to env vars (CLI takes precedence; rest of codebase reads from env)
+        if (opts.repoRoot)
+            process.env.COORDINATOR_REPO_ROOT = opts.repoRoot;
+        if (opts.maxBodyBytes)
+            process.env.COORDINATOR_MAX_BODY_BYTES = opts.maxBodyBytes;
+        if (opts.workingFilesTtlMin)
+            process.env.COORDINATOR_WORKING_FILES_TTL_MIN = opts.workingFilesTtlMin;
+        if (opts.workingFilesSweepMs)
+            process.env.COORDINATOR_WORKING_FILES_SWEEP_INTERVAL_MS = opts.workingFilesSweepMs;
+        if (opts.layer4SinceDays)
+            process.env.COORDINATOR_LAYER4_SINCE_DAYS = opts.layer4SinceDays;
+        if (opts.layer4MaxCommits)
+            process.env.COORDINATOR_LAYER4_MAX_COMMITS = opts.layer4MaxCommits;
+        if (opts.layer4RefreshMs)
+            process.env.COORDINATOR_LAYER4_REFRESH_INTERVAL_MS = opts.layer4RefreshMs;
+        if (opts.layer4RetryMs)
+            process.env.COORDINATOR_LAYER4_RETRY_MS = opts.layer4RetryMs;
         const config = loadConfig();
         const port = parseInt(opts.port ?? process.env.PORT ?? String(config.server.port), 10);
         const dataDir = opts.dataDir ?? process.env.COORDINATOR_DATA_DIR ?? config.server.data_dir;
@@ -47,6 +72,14 @@ export function createServerStartCommand() {
             fwd("COORDINATOR_ADMIN_SECRET", process.env.COORDINATOR_ADMIN_SECRET);
             fwd("COORDINATOR_MQTT_TCP_PORT", process.env.COORDINATOR_MQTT_TCP_PORT);
             fwd("COORDINATOR_MQTT_WS_PATH", process.env.COORDINATOR_MQTT_WS_PATH);
+            fwd("COORDINATOR_REPO_ROOT", process.env.COORDINATOR_REPO_ROOT);
+            fwd("COORDINATOR_MAX_BODY_BYTES", process.env.COORDINATOR_MAX_BODY_BYTES);
+            fwd("COORDINATOR_WORKING_FILES_TTL_MIN", process.env.COORDINATOR_WORKING_FILES_TTL_MIN);
+            fwd("COORDINATOR_WORKING_FILES_SWEEP_INTERVAL_MS", process.env.COORDINATOR_WORKING_FILES_SWEEP_INTERVAL_MS);
+            fwd("COORDINATOR_LAYER4_SINCE_DAYS", process.env.COORDINATOR_LAYER4_SINCE_DAYS);
+            fwd("COORDINATOR_LAYER4_MAX_COMMITS", process.env.COORDINATOR_LAYER4_MAX_COMMITS);
+            fwd("COORDINATOR_LAYER4_REFRESH_INTERVAL_MS", process.env.COORDINATOR_LAYER4_REFRESH_INTERVAL_MS);
+            fwd("COORDINATOR_LAYER4_RETRY_MS", process.env.COORDINATOR_LAYER4_RETRY_MS);
             const child = spawn(cmd, args, {
                 detached: true,
                 stdio: ["ignore", logFd, logFd],

package/dist/src/announce-workflow.d.ts

@@ -42,6 +42,7 @@ export interface CommonFlowParams {
     depends_on_files?: string[];
     exports_affected?: string[];
     keep_open?: boolean;
+    target_symbols?: string[];
 }
 /**
  * Run the common post-`announceWork` orchestration. Mutates the thread row

package/dist/src/announce-workflow.js

@@ -15,7 +15,16 @@ export function runCommonAnnounceFlow(services, threadId, params) {
         target_files: params.target_files,
         depends_on_files: params.depends_on_files,
         exports_affected: params.exports_affected,
+        target_symbols: params.target_symbols,
     });
+    // Layer firing log: one row per concerned/gray-zone scored agent.
+    // Used by /api/scoring-stats and the dashboard "Conflict signals" panel.
+    const dbForFirings = getDb();
+    const insertFiring = dbForFirings.prepare("INSERT INTO layer_firings (thread_id, layer, score, agent_id) VALUES (?, ?, ?, ?)");
+    for (const s of [...categorized.concerned, ...categorized.gray_zone]) {
+        const layer = inferLayerFromReasons(s.reasons);
+        insertFiring.run(threadId, layer, s.score, s.agent_id);
+    }
     // 2. Override expected_respondents on the thread with the scored set.
     // Auto-resolve only when truly alone — if peers are online but not concerned
     // (e.g., they haven't announced yet), keep the thread open so a subsequent
@@ -72,6 +81,25 @@ export function runCommonAnnounceFlow(services, threadId, params) {
     const respondents = JSON.parse(updated.expected_respondents || "[]");
     return { updated, categorized, respondents, planQuality };
 }
+function inferLayerFromReasons(reasons) {
+    for (const r of reasons) {
+        if (r.includes("disjoint symbols"))
+            return "L0.5";
+        if (r.includes("announced same file") || r.includes("modifies my dependency") || r.includes("they depend on my target"))
+            return "L0";
+        if (r.includes("same file (in flight)"))
+            return "L1";
+        if (r.includes("same file"))
+            return "L1";
+        if (r.includes("co-change"))
+            return "L4";
+        if (r.includes("depends on"))
+            return "L2";
+        if (r.includes("module overlap"))
+            return "L3";
+    }
+    return "L1";
+}
 function scoredCategory(s) {
     if (s.score >= 90)
         return "concerned";

package/dist/src/database.js

@@ -3,6 +3,7 @@ import { mkdirSync } from "fs";
 import { createRequire } from "module";
 const require = createRequire(import.meta.url);
 let db;
+const CURRENT_USER_VERSION = 6;
 const SCHEMA = `
     CREATE TABLE IF NOT EXISTS agents (
       id TEXT PRIMARY KEY,
@@ -129,6 +130,45 @@ const SCHEMA = `
       revoked_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
       revoked_by TEXT NOT NULL
     );
+
+    CREATE TABLE IF NOT EXISTS working_files (
+      agent_id          TEXT NOT NULL,
+      file_path         TEXT NOT NULL,
+      started_at        TEXT NOT NULL,
+      last_activity_at  TEXT NOT NULL,
+      claim_until       TEXT NOT NULL,
+      PRIMARY KEY (agent_id, file_path)
+    );
+    CREATE INDEX IF NOT EXISTS idx_working_files_path  ON working_files(file_path);
+    CREATE INDEX IF NOT EXISTS idx_working_files_until ON working_files(claim_until);
+
+    CREATE TABLE IF NOT EXISTS git_cochange (
+      file_a        TEXT NOT NULL,
+      file_b        TEXT NOT NULL,
+      count         INTEGER NOT NULL,
+      total_commits INTEGER NOT NULL,
+      computed_at   TEXT NOT NULL,
+      PRIMARY KEY (file_a, file_b),
+      CHECK (file_a < file_b)
+    );
+    CREATE INDEX IF NOT EXISTS idx_cochange_a ON git_cochange(file_a);
+    CREATE INDEX IF NOT EXISTS idx_cochange_b ON git_cochange(file_b);
+
+    CREATE TABLE IF NOT EXISTS git_cochange_meta (
+      k TEXT PRIMARY KEY,
+      v TEXT
+    );
+
+    CREATE TABLE IF NOT EXISTS layer_firings (
+      id        INTEGER PRIMARY KEY AUTOINCREMENT,
+      thread_id TEXT,
+      layer     TEXT NOT NULL,
+      score     INTEGER NOT NULL,
+      agent_id  TEXT,
+      fired_at  TEXT DEFAULT CURRENT_TIMESTAMP
+    );
+    CREATE INDEX IF NOT EXISTS idx_firings_layer  ON layer_firings(layer, fired_at);
+    CREATE INDEX IF NOT EXISTS idx_firings_thread ON layer_firings(thread_id);
 `;
 function createBetterSqlite3(dataDir) {
     mkdirSync(dataDir, { recursive: true });
@@ -157,6 +197,20 @@ export function initDatabase(dataDir) {
     else {
         db = createBetterSqlite3(dataDir);
     }
+    // Check for downgrade: refuse if DB was written by a newer binary
+    let foundVersion = 0;
+    try {
+        const v = db
+            .prepare("PRAGMA user_version")
+            .get();
+        foundVersion = v?.user_version ?? 0;
+    }
+    catch {
+        foundVersion = 0;
+    }
+    if (foundVersion > CURRENT_USER_VERSION) {
+        throw new Error(`Database schema is from a newer version (${foundVersion}) than this binary supports (${CURRENT_USER_VERSION}). Downgrade not supported.`);
+    }
     db.exec(SCHEMA);
     // Migrations for existing databases — columns may already exist
     try {
@@ -182,6 +236,17 @@ export function initDatabase(dataDir) {
         db.exec("ALTER TABLE threads ADD COLUMN assigned_to TEXT");
     }
     catch { /* already exists */ }
+    // v0.6: per-edit symbol metadata on file_activity
+    try {
+        db.exec("ALTER TABLE file_activity ADD COLUMN symbols_touched TEXT");
+    }
+    catch { /* already exists */ }
+    try {
+        db.exec("ALTER TABLE file_activity ADD COLUMN content_hash TEXT");
+    }
+    catch { /* already exists */ }
+    // v0.6: schema version marker. Used by cli/server/restore.ts to refuse downgrades.
+    db.exec("PRAGMA user_version = 6");
 }
 export function getDb() {
     if (!db)

package/dist/src/file-tracker.d.ts

@@ -6,6 +6,8 @@ export declare class FileTracker {
         agent_name?: string;
         tool_name: string;
         file_path: string;
+        content_hash?: string | null;
+        symbols_touched?: string[] | null;
     }): void;
     getBySession(sessionId: string): FileActivity[];
     getHotFiles(sinceMinutes?: number): {

package/dist/src/file-tracker.js

@@ -3,8 +3,9 @@ export class FileTracker {
     log(params) {
         const db = getDb();
         const module = this.fileToModule(params.file_path);
-        db.prepare(`INSERT INTO file_activity (session_id, agent_id, agent_name, tool_name, file_path, module)
-       VALUES (?, ?, ?, ?, ?, ?)`).run(params.session_id, params.agent_id, params.agent_name || null, params.tool_name, params.file_path, module);
+        db.prepare(`INSERT INTO file_activity
+       (session_id, agent_id, agent_name, tool_name, file_path, module, content_hash, symbols_touched)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)`).run(params.session_id, params.agent_id, params.agent_name || null, params.tool_name, params.file_path, module, params.content_hash || null, params.symbols_touched ? JSON.stringify(params.symbols_touched) : null);
     }
     getBySession(sessionId) {
         const db = getDb();

package/dist/src/git-cochange-builder.d.ts

@@ -0,0 +1,32 @@
+import { type Logger } from "./logger.js";
+import type { Metrics } from "./metrics.js";
+interface BuilderOpts {
+    repoRoot: string;
+    sinceDays?: number;
+    maxCount?: number;
+    timeoutMs?: number;
+    refreshMs?: number;
+    retryMs?: number;
+    logger?: Logger;
+    metrics?: Metrics;
+}
+export declare class GitCochangeBuilder {
+    private repoRoot;
+    private sinceDays;
+    private maxCount;
+    private timeoutMs;
+    private refreshMs;
+    private retryMs;
+    private log;
+    private metrics?;
+    private timer;
+    constructor(opts: BuilderOpts);
+    /** Build once. Resolves after persistence. */
+    build(): Promise<void>;
+    private runGitLog;
+    private parseLog;
+    /** Schedule a refresh loop. unref() so it doesn't keep the loop alive. */
+    startScheduler(): void;
+    stopScheduler(): void;
+}
+export {};

package/dist/src/git-cochange-builder.js

@@ -0,0 +1,238 @@
+// src/git-cochange-builder.ts
+import { spawn } from "child_process";
+import { existsSync } from "fs";
+import path from "path";
+import { getDb } from "./database.js";
+import { silentLogger } from "./logger.js";
+const DEFAULT_DENYLIST = [
+    /package-lock\.json$/, /pnpm-lock\.yaml$/, /yarn\.lock$/, /\.lock$/,
+    /\/dist\//, /\/build\//, /\/\.next\//, /\/__snapshots__\//,
+    /\.min\.js$/, /\.map$/, /\/coverage\//, /\/node_modules\//, /\.snap$/,
+];
+export class GitCochangeBuilder {
+    repoRoot;
+    sinceDays;
+    maxCount;
+    timeoutMs;
+    refreshMs;
+    retryMs;
+    log;
+    metrics;
+    timer = null;
+    constructor(opts) {
+        this.repoRoot = opts.repoRoot;
+        this.sinceDays = opts.sinceDays ?? 7;
+        this.maxCount = opts.maxCount ?? 2000;
+        this.timeoutMs = opts.timeoutMs ?? 5000;
+        this.refreshMs = opts.refreshMs ?? 1800000;
+        this.retryMs = opts.retryMs ?? 300000;
+        this.log = opts.logger || silentLogger;
+        this.metrics = opts.metrics;
+    }
+    /** Build once. Resolves after persistence. */
+    async build() {
+        const db = getDb();
+        const setMeta = (k, v) => db.prepare("INSERT OR REPLACE INTO git_cochange_meta (k, v) VALUES (?, ?)").run(k, v);
+        if (!existsSync(path.join(this.repoRoot, ".git"))) {
+            this.log.info({}, "Layer 4 unavailable: no .git");
+            setMeta("available", "false");
+            this.metrics?.gitCochangeBuilds.inc({ outcome: "failed" });
+            return;
+        }
+        if (existsSync(path.join(this.repoRoot, ".git", "shallow"))) {
+            this.log.info({}, "Layer 4 unavailable: shallow clone");
+            setMeta("available", "false");
+            this.metrics?.gitCochangeBuilds.inc({ outcome: "shallow_skipped" });
+            return;
+        }
+        let stdout = null;
+        try {
+            stdout = await this.runGitLog();
+        }
+        catch (err) {
+            this.log.warn({ err }, "git log failed");
+            setMeta("available", "false");
+            setMeta("last_error", String(err.message));
+            this.metrics?.gitCochangeBuilds.inc({ outcome: "failed" });
+            return;
+        }
+        if (stdout === "TIMEOUT") {
+            setMeta("available", "stale_partial");
+            this.log.warn({}, "git log timed out — Layer 4 stale_partial");
+            this.metrics?.gitCochangeBuilds.inc({ outcome: "timeout" });
+            return;
+        }
+        const { pairs, totalCommits } = this.parseLog(stdout);
+        // Dynamic predictor cap: any file appearing in > 40% of effective commits is
+        // excluded as a *predictor* (still allowed as a *target*). Prevents hotspot files
+        // like config or barrel index from saturating co-change with every other file.
+        const PREDICTOR_CAP_RATIO = 0.4;
+        const fileCommitCount = new Map();
+        for (const key of pairs.keys()) {
+            const [a, b] = key.split("|");
+            fileCommitCount.set(a, (fileCommitCount.get(a) ?? 0) + (pairs.get(key) ?? 0));
+            fileCommitCount.set(b, (fileCommitCount.get(b) ?? 0) + (pairs.get(key) ?? 0));
+        }
+        const promiscuous = new Set();
+        for (const [file, count] of fileCommitCount) {
+            // count is total times the file appeared in any pair; max possible is roughly
+            // (totalCommits) per file. Use raw count / totalCommits as an approximation
+            // of the file's commit frequency.
+            if (totalCommits > 0 && count / totalCommits > PREDICTOR_CAP_RATIO) {
+                promiscuous.add(file);
+            }
+        }
+        if (promiscuous.size > 0) {
+            this.log.info({ count: promiscuous.size, files: Array.from(promiscuous) }, "Layer 4 dynamic predictor cap excluded files");
+        }
+        db.exec("DELETE FROM git_cochange");
+        const stmt = db.prepare("INSERT INTO git_cochange (file_a, file_b, count, total_commits, computed_at) VALUES (?, ?, ?, ?, datetime('now'))");
+        const insertMany = db.transaction(() => {
+            for (const [key, count] of pairs.entries()) {
+                const [a, b] = key.split("|");
+                // Skip pairs where EITHER file is a promiscuous predictor (file is allowed
+                // as target only, but a pair where it's a predictor is dropped). For the
+                // index entry to be useful, both files must be non-promiscuous predictors.
+                if (promiscuous.has(a) || promiscuous.has(b))
+                    continue;
+                if (a < b)
+                    stmt.run(a, b, count, totalCommits);
+            }
+        });
+        insertMany();
+        setMeta("available", "true");
+        setMeta("last_built_at", new Date().toISOString());
+        this.metrics?.gitCochangeBuilds.inc({ outcome: "success" });
+        this.metrics?.gitCochangePairs.set(pairs.size);
+    }
+    runGitLog() {
+        return new Promise((resolve, reject) => {
+            const args = [
+                "log",
+                `--max-count=${this.maxCount}`,
+                "--diff-filter=AMRD",
+                `--since=${this.sinceDays} days ago`,
+                "--no-renames",
+                "--pretty=format:%H",
+                "--name-only",
+                "-z",
+            ];
+            const proc = spawn("git", args, { cwd: this.repoRoot });
+            let buf = "";
+            const timer = setTimeout(() => {
+                proc.kill();
+                resolve("TIMEOUT");
+            }, this.timeoutMs);
+            proc.stdout.on("data", (c) => (buf += c.toString("utf-8")));
+            proc.on("error", (err) => { clearTimeout(timer); reject(err); });
+            proc.on("close", (code) => {
+                clearTimeout(timer);
+                if (code === 0)
+                    resolve(buf);
+                else
+                    reject(new Error(`git log exit ${code}`));
+            });
+        });
+    }
+    parseLog(stdout) {
+        // git log -z --pretty=format:%H --name-only output format:
+        // Each commit entry: <SHA>\n<file1>\0<file2>\0...\0
+        // Between commits the NUL separator also acts as delimiter.
+        // We split on NUL first, then detect SHA boundaries within tokens.
+        const tokens = stdout.split("\0").filter(t => t.length > 0);
+        const pairs = new Map();
+        let totalCommits = 0;
+        let currentFiles = [];
+        const flush = () => {
+            if (currentFiles.length === 0)
+                return;
+            // Skip massive commits (likely sweeps)
+            if (currentFiles.length > 200) {
+                currentFiles = [];
+                return;
+            }
+            // Apply denylist
+            const eligible = currentFiles.filter(f => !DEFAULT_DENYLIST.some(re => re.test(f)));
+            for (let i = 0; i < eligible.length; i++) {
+                for (let j = i + 1; j < eligible.length; j++) {
+                    const [a, b] = eligible[i] < eligible[j] ? [eligible[i], eligible[j]] : [eligible[j], eligible[i]];
+                    const key = `${a}|${b}`;
+                    pairs.set(key, (pairs.get(key) ?? 0) + 1);
+                }
+            }
+            totalCommits++;
+            currentFiles = [];
+        };
+        // SHA pattern: 40 hex chars
+        const shaRe = /^([0-9a-f]{40})\n(.*)$/s;
+        for (const t of tokens) {
+            // Each token after splitting on \0 may look like:
+            // "\nSHA40\npath" (commit boundary with preceding newline)
+            // "SHA40\npath"  (commit boundary at start)
+            // "path"         (file path continuation)
+            // "\nSHA40"      (SHA only, no file on same token)
+            // Strip leading newlines to normalize
+            const stripped = t.replace(/^\n+/, "");
+            const shaMatch = stripped.match(shaRe);
+            if (shaMatch) {
+                // We found a SHA — flush the previous commit's files
+                flush();
+                const trailingPath = shaMatch[2].trim();
+                if (trailingPath)
+                    currentFiles.push(trailingPath);
+            }
+            else {
+                // Check if this token itself IS a SHA (no file attached, happens when
+                // --pretty=format:%H emits the SHA on its own NUL-terminated chunk)
+                const pureSha = stripped.match(/^[0-9a-f]{40}$/);
+                if (pureSha) {
+                    flush();
+                }
+                else {
+                    // It's a file path (or part of one); newlines indicate embedded commit
+                    // boundaries when a file is on the same NUL chunk as the next SHA.
+                    // Handle the case where "path\nSHA\npath" might appear.
+                    const parts = stripped.split("\n");
+                    for (let i = 0; i < parts.length; i++) {
+                        const part = parts[i].trim();
+                        if (!part)
+                            continue;
+                        if (/^[0-9a-f]{40}$/.test(part)) {
+                            flush();
+                        }
+                        else {
+                            currentFiles.push(part);
+                        }
+                    }
+                }
+            }
+        }
+        flush();
+        return { pairs, totalCommits };
+    }
+    /** Schedule a refresh loop. unref() so it doesn't keep the loop alive. */
+    startScheduler() {
+        const tick = async () => {
+            try {
+                await this.build();
+                this.timer = setTimeout(tick, this.refreshMs);
+            }
+            catch (err) {
+                this.log.warn({ err }, "build failed, retrying");
+                this.timer = setTimeout(tick, this.retryMs);
+            }
+            if (this.timer && typeof this.timer.unref === "function")
+                this.timer.unref();
+        };
+        // First build after 5s grace
+        this.timer = setTimeout(tick, 5000);
+        if (this.timer && typeof this.timer.unref === "function")
+            this.timer.unref();
+    }
+    stopScheduler() {
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+    }
+}

package/dist/src/http/handle-health.d.ts

@@ -13,7 +13,7 @@ export declare function handleLivez(_req: IncomingMessage, res: ServerResponse):
  * structured `{ok:false,error:"…"}` instead of a 500. The response shape is
  * identical between 200 and 503 so consumers can parse uniformly.
  */
-export declare function handleReadyz(_req: IncomingMessage, res: ServerResponse, services: Pick<CoordinatorServices, "mqttBridge">): void;
+export declare function handleReadyz(_req: IncomingMessage, res: ServerResponse, services: Pick<CoordinatorServices, "mqttBridge" | "treeSitter" | "gitCochange">): void;
 /**
  * Backwards-compatible alias. The original /health route returned a fixed
  * {status:"ok",version} payload with no dep checks; semantically that is a

package/dist/src/http/handle-health.js

@@ -47,6 +47,8 @@ export function handleReadyz(_req, res, services) {
     const checks = {
         db: { ok: false },
         mqtt: { ok: false },
+        tree_sitter: { ok: false, grammars_loaded: 0, total_grammars: 7, optional: true },
+        git_cochange: { available: false, status: "unavailable", optional: true },
     };
     try {
         // Cheapest possible round-trip that exercises the connection without
@@ -69,6 +71,30 @@ export function handleReadyz(_req, res, services) {
     catch (err) {
         checks.mqtt.error = err.message;
     }
+    // Optional: tree-sitter status (does NOT gate readiness — Layer 0.5 degrades gracefully)
+    try {
+        if (services.treeSitter) {
+            checks.tree_sitter = services.treeSitter.status();
+        }
+    }
+    catch {
+        // keep default { ok: false, grammars_loaded: 0, total_grammars: 7, optional: true }
+    }
+    // Optional: git_cochange availability (does NOT gate readiness — Layer 4 degrades gracefully)
+    try {
+        const row = getDb()
+            .prepare("SELECT v FROM git_cochange_meta WHERE k = ?")
+            .get("available");
+        checks.git_cochange = {
+            available: row?.v === "true",
+            status: row?.v ?? "unavailable",
+            optional: true,
+        };
+    }
+    catch {
+        // keep default { available: false, status: "unavailable", optional: true }
+    }
+    // Gating: only db + mqtt block readiness. tree_sitter and git_cochange are reported but optional.
     const allOk = checks.db.ok && checks.mqtt.ok;
     json(res, {
         status: allOk ? "ready" : "not_ready",