loki-mode 10.7.1 → 10.9.1

package/packages/control-plane/src/server/routes/memory.ts

@@ -0,0 +1,219 @@
+// CPE24-P3: memory, context, focus and tasks, ported from dashboard/server.py (list_tasks, set_focus, list_episodes, list_patterns, list_skills,
+// get_token_economics, get_context). Same .loki/ flat-file sources; the legacy SQLite memory backend and the SQL task store have no CP equivalent, so
+// those paths are not ported (see docs/v10/CP-ENTERPRISE-UI.md). Unmeasured values are null, never a fabricated zero.
+// Every path read is derived from the focused project dir plus a fixed suffix; a request value is only ever compared to an id, never joined into a path.
+import { existsSync, readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
+import type { Dirent } from "node:fs";
+import type { Context } from "hono";
+import { join, sep } from "node:path";
+import { isLoopbackHost, peerIsLoopback } from "../auth.ts";
+import { probeAllowed, type RouteCtx } from "./index.ts";
+import { lokiDirOf, readJson } from "./cost_ledger.ts";
+import { registryFile } from "./fleet.ts";
+
+type Rec = Record<string, unknown>;
+const isObj = (v: unknown): v is Rec => typeof v === "object" && v !== null && !Array.isArray(v);
+const nonEmpty = (v: unknown) => !(v === undefined || v === null || v === "" || (Array.isArray(v) && v.length === 0) || (isObj(v) && Object.keys(v).length === 0));
+
+/** The focused project dir (POST /v1/focus); null means the server's own checkout. Process-wide, like the legacy _active_project_dir. */
+export const focus: { dir: string | null } = { dir: null };
+export const lokiFor = (repoDir: string) => lokiDirOf(focus.dir ?? repoDir);
+
+/** State-changing guard: loopback peer and Host, JSON content type, and a browser Origin (when sent) equal to the Host. */
+export function mutationAllowed(c: Context): boolean {
+  if (!peerIsLoopback(c) || !isLoopbackHost(c.req.header("host"))) return false;
+  if (!(c.req.header("content-type") ?? "").toLowerCase().startsWith("application/json")) return false;
+  const origin = c.req.header("origin");
+  if (origin === undefined) return true;
+  try { return new URL(origin).host.toLowerCase() === (c.req.header("host") ?? "").toLowerCase(); } catch { return false; }
+}
+
+/** Every .json file under dir (sorted), never following symlinks, so nothing resolves outside dir. */
+function jsonFiles(dir: string, cap = Infinity): string[] {
+  const out: string[] = [];
+  const walk = (d: string) => {
+    let ents: Dirent[] = [];
+    try { ents = readdirSync(d, { withFileTypes: true }); } catch { return; }
+    for (const e of ents.sort((a, b) => (a.name < b.name ? -1 : 1))) {
+      if (out.length >= cap) return;
+      const p = join(d, e.name);
+      if (e.isDirectory()) walk(p); else if (e.isFile() && e.name.endsWith(".json")) out.push(p);
+    }
+  };
+  walk(dir);
+  return out;
+}
+
+export function focusInfo(repoDir: string) { return { project_dir: focus.dir, loki_dir: lokiFor(repoDir) }; }
+
+/** A focus target must be this checkout or a project in the machine registry, and hold a .loki dir; `..` and relative paths are refused. */
+export function setFocus(repoDir: string, raw: unknown, registry = registryFile()): { ok: true } | { ok: false; error: string } {
+  const s = typeof raw === "string" ? raw.trim() : "";
+  if (!s) return { ok: false, error: "project_dir must not be empty" };
+  if (!s.startsWith("/") || s.split(/[\\/]/).includes("..")) return { ok: false, error: "project_dir must be an absolute path without .. segments" };
+  let real = "";
+  try { real = realpathSync(s); if (!statSync(real).isDirectory()) throw new Error("not a dir"); } catch { return { ok: false, error: `Directory does not exist: ${s}` }; }
+  if (!existsSync(join(real, ".loki")) || !statSync(join(real, ".loki")).isDirectory()) return { ok: false, error: `Directory does not contain a .loki/ subdirectory: ${s}` };
+  const allowed = new Set<string>();
+  try { allowed.add(realpathSync(repoDir)); } catch { /* unreadable */ }
+  const reg = readJson(registry);
+  if (isObj(reg) && isObj(reg.projects)) for (const p of Object.values(reg.projects)) {
+    if (isObj(p) && typeof p.path === "string") { try { allowed.add(realpathSync(p.path)); } catch { /* gone */ } }
+  }
+  if (!allowed.has(real)) return { ok: false, error: "project_dir is not this checkout or a registered project" };
+  focus.dir = real;
+  return { ok: true };
+}
+
+// ---- tasks (dashboard-state.json groups plus .loki/queue/*.json), deduped with the legacy terminal-wins rule ----
+const GROUPS: [string, string][] = [["pending", "pending"], ["inProgress", "in_progress"], ["review", "review"], ["completed", "done"], ["failed", "done"]];
+const QUEUES: [string, string][] = [["pending.json", "pending"], ["in-progress.json", "in_progress"], ["completed.json", "done"], ["failed.json", "done"], ["dead-letter.json", "done"]];
+const RANK: Record<string, number> = { done: 3, in_progress: 2, review: 1, pending: 0 };
+
+export function tasksList(loki: string, status?: string): Rec[] {
+  const all: Rec[] = [];
+  const st = readJson(join(loki, "dashboard-state.json"));
+  const groups = isObj(st) && isObj(st.tasks) ? st.tasks : {};
+  for (const [key, mapped] of GROUPS) {
+    const g = groups[key];
+    if (!Array.isArray(g)) continue;
+    g.forEach((t, i) => {
+      if (!isObj(t)) return;
+      const payload = isObj(t.payload) ? t.payload : {};
+      const e: Rec = { id: t.id ?? `${key}-${i}`, title: t.title ?? payload.action ?? t.type ?? "Task", description: t.description ?? payload.description ?? "", status: mapped, priority: t.priority ?? payload.priority ?? "medium", type: t.type ?? "task", position: i };
+      for (const f of ["acceptance_criteria", "notes", "logs", "user_story", "project", "source", "specification", "provider", "startedAt", "full_content", "completedAt", "phase", "exitCode"]) if (nonEmpty(t[f])) e[f] = t[f];
+      if (t.exitCode === 0) e.exitCode = 0;
+      if (key === "completed" || key === "failed") e._terminal_outcome = key;
+      all.push(e);
+    });
+  }
+  for (const [file, qs] of QUEUES) {
+    const raw = readJson(join(loki, "queue", file));
+    const items = isObj(raw) ? raw.tasks : raw;
+    if (!Array.isArray(items)) continue;
+    const term = file === "completed.json" ? "completed" : file === "failed.json" || file === "dead-letter.json" ? "failed" : null;
+    items.forEach((it, i) => {
+      if (!isObj(it)) return;
+      const id = it.id ?? `q-${qs}-${i}`;
+      if (term === null && all.some((t) => t.id === id)) return;
+      const e: Rec = { id, title: it.title ?? it.action ?? "Task", description: it.description ?? "", status: qs, priority: it.priority ?? "medium", type: it.type ?? "task", position: i };
+      for (const f of ["acceptance_criteria", "user_story", "project", "source", "provider", "startedAt", "completedAt", "phase"]) if (nonEmpty(it[f])) e[f] = it[f];
+      for (const f of ["notes", "logs"]) if (Array.isArray(it[f])) e[f] = it[f];
+      if (Number.isInteger(it.exitCode)) e.exitCode = it.exitCode;
+      if (term) e._terminal_outcome = term;
+      all.push(e);
+    });
+  }
+  const auth = (t: Rec) => [RANK[t.status as string] ?? -1, t._terminal_outcome === "failed" ? 1 : 0] as const;
+  const better = (a: Rec, b: Rec) => { const x = auth(a), y = auth(b); return x[0] !== y[0] ? x[0] > y[0] : x[1] > y[1]; };
+  const byId = new Map<unknown, Rec>(), order: (Rec | { ref: unknown })[] = [];
+  for (const t of all) {
+    if (t.id === undefined || t.id === null) { order.push(t); continue; }
+    const prev = byId.get(t.id);
+    if (!prev) { byId.set(t.id, t); order.push({ ref: t.id }); } else if (better(t, prev)) byId.set(t.id, t);
+  }
+  const out = order.map((o) => ("ref" in o ? (byId.get(o.ref) as Rec) : o));
+  for (const t of out) {
+    if (t.type === "iteration" && !t.description) {
+      const ec = t.exitCode, failed = t._terminal_outcome === "failed";
+      const o = Number.isInteger(ec) && ec === 0 && !failed ? "completed cleanly (exit 0)" : Number.isInteger(ec) && ec !== 0 ? `failed (exit ${ec})` : failed ? "failed"
+        : t._terminal_outcome === "completed" ? "completed" : t.status === "done" ? "finished" : null;
+      if (o) t.description = `Iteration ${o}${t.provider ? `, built by ${t.provider}` : ""}.`;
+    }
+  }
+  return status ? out.filter((t) => t.status === status) : out;
+}
+
+// ---- memory (.loki/memory JSON store) ----
+const memDir = (loki: string, sub: string) => join(loki, "memory", sub);
+
+export function memoryEpisodes(loki: string, limit = 50): Rec[] {
+  const eps = jsonFiles(memDir(loki, "episodic")).map(readJson).filter(isObj);
+  eps.sort((a, b) => String(b.timestamp ?? "").localeCompare(String(a.timestamp ?? "")));
+  return eps.slice(0, limit);
+}
+export function memoryEpisode(loki: string, id: string): Rec | null {
+  for (const f of jsonFiles(memDir(loki, "episodic"))) {
+    const d = readJson(f);
+    if (isObj(d) && (d.id === id || f.split(sep).pop() === `${id}.json`)) return d;
+  }
+  return null;
+}
+export function memoryPatterns(loki: string): Rec[] {
+  const d = readJson(join(memDir(loki, "semantic"), "patterns.json"));
+  const list = Array.isArray(d) ? d : isObj(d) && Array.isArray(d.patterns) ? d.patterns : [];
+  return list.filter(isObj);
+}
+export const memorySkills = (loki: string): Rec[] => jsonFiles(memDir(loki, "skills")).map(readJson).filter(isObj);
+
+export function memoryEconomics(loki: string) {
+  const rawV = readJson(join(loki, "memory", "token_economics.json"));
+  const raw: Rec = isObj(rawV) ? rawV : {};
+  const m = isObj(raw.metrics) ? raw.metrics : {};
+  const n = (v: unknown) => (typeof v === "number" && Number.isFinite(v) ? Math.trunc(v) : 0);
+  const hits = n(m.cache_hits), misses = n(m.cache_misses), total = hits + misses;
+  const recorded = Object.keys(m).length > 0;
+  const disc = recorded ? n(m.discovery_tokens) : null, read = recorded ? n(m.read_tokens) : null;
+  const cands: Rec[] = [];
+  for (const kind of ["episodic", "semantic"]) {
+    for (const f of jsonFiles(memDir(loki, kind), 300)) {
+      const d = readJson(f);
+      if (!isObj(d)) continue;
+      const ctx = isObj(d.context) ? d.context : {};
+      cands.push({ id: d.id ?? "", kind, access_count: n(d.access_count), importance: Number(d.importance) || 0, summary: String(d.summary || d.pattern || ctx.goal || "").slice(0, 160) });
+    }
+  }
+  cands.sort((a, b) => (b.access_count as number) - (a.access_count as number) || (b.importance as number) - (a.importance as number));
+  return {
+    session_id: raw.session_id ?? null, discovery_tokens: disc, read_tokens: read, total_tokens: recorded ? (disc as number) + (read as number) : null,
+    cache_hits: hits, cache_misses: misses, hit_rate: total > 0 ? Math.round((hits / total) * 1e4) / 1e4 : null, ratio: raw.ratio ?? null,
+    savings_percent: raw.savings_percent ?? null, top_patterns: cands.slice(0, 10).filter((p) => (p.access_count as number) > 0),
+    discoveryTokens: disc, readTokens: read, savingsPercent: raw.savings_percent ?? null, raw,
+  };
+}
+
+/** .loki/context/tracking.json; absent means the tracker never ran, so every reading is null. A file that exists but is unreadable is an error, not a zero. */
+export function contextTracking(loki: string): { status: 200 | 500; body: unknown } {
+  const f = join(loki, "context", "tracking.json");
+  if (!existsSync(f)) {
+    return { status: 200, body: {
+      session_id: null, updated_at: null,
+      current: { input_tokens: null, output_tokens: null, cache_read_tokens: null, cache_creation_tokens: null, total_tokens: null, context_window_pct: null, estimated_cost_usd: null },
+      compactions: [], per_iteration: [],
+      totals: { total_input: null, total_output: null, total_cost_usd: null, compaction_count: null, iterations_tracked: null },
+    } };
+  }
+  try { return { status: 200, body: JSON.parse(readFileSync(f, "utf8")) }; } catch { return { status: 500, body: { error: "Failed to read context tracking data" } }; }
+}
+
+export function mount(ctx: RouteCtx): void {
+  const deny = { error: "loopback only without a token" };
+  const read = (path: string, fn: (c: Context, loki: string) => Response) =>
+    ctx.app.get(path, (c) => (probeAllowed(ctx, c) ? fn(c, lokiFor(ctx.repoDir)) : c.json(deny, 403)));
+  read("/v1/tasks", (c, l) => {
+    if (c.req.query("project_id") !== undefined) return c.json({ error: "project_id filter is not supported by the Control Plane" }, 400);
+    return c.json(tasksList(l, c.req.query("status")));
+  });
+  read("/v1/memory/episodes", (c, l) => {
+    const lim = c.req.query("limit") === undefined ? 50 : Number(c.req.query("limit"));
+    return Number.isInteger(lim) && lim >= 1 && lim <= 1000 ? c.json(memoryEpisodes(l, lim)) : c.json({ error: "limit must be 1..1000" }, 422);
+  });
+  read("/v1/memory/episodes/:id", (c, l) => { const e = memoryEpisode(l, c.req.param("id")); return e ? c.json(e) : c.json({ error: "Episode not found" }, 404); });
+  read("/v1/memory/patterns", (c, l) => c.json(memoryPatterns(l)));
+  read("/v1/memory/patterns/:id", (c, l) => { const p = memoryPatterns(l).find((x) => x.id === c.req.param("id")); return p ? c.json(p) : c.json({ error: "Pattern not found" }, 404); });
+  read("/v1/memory/skills", (c, l) => c.json(memorySkills(l)));
+  read("/v1/memory/economics", (c, l) => c.json(memoryEconomics(l)));
+  read("/v1/context", (c, l) => { const r = contextTracking(l); return c.json(r.body, r.status); });
+  read("/v1/focus", (c) => c.json(focusInfo(ctx.repoDir)));
+  ctx.act.post("/v1/focus", async (c) => {
+    if (!mutationAllowed(c)) return c.json({ error: "loopback JSON requests only" }, 403);
+    const body = await c.req.json().catch(() => null);
+    const r = setFocus(ctx.repoDir, isObj(body) ? body.project_dir : undefined);
+    return r.ok ? c.json(focusInfo(ctx.repoDir)) : c.json({ error: r.error }, 400);
+  });
+  ctx.act.delete("/v1/focus", (c) => {
+    if (!mutationAllowed(c)) return c.json({ error: "loopback JSON requests only" }, 403);
+    focus.dir = null;
+    return c.json(focusInfo(ctx.repoDir));
+  });
+}

package/packages/control-plane/src/server/routes/merge_risk.ts

@@ -0,0 +1,209 @@
+// CPE-25 merge queue and CPE-26 PR risk. The CLI is the source of truth: each route runs `loki merge ...` or `loki review --risk --json`
+// with execFile and a fixed argv array (no shell), a timeout and an output cap, in the selected repo. Nothing is reimplemented here.
+import { spawn } from "node:child_process";
+import { realpathSync } from "node:fs";
+import { basename, resolve } from "node:path";
+import type { Context } from "hono";
+import { audit } from "../audit.ts";
+import { childEnv, registryRepos } from "../spawn.ts";
+import { isLoopbackHost } from "../auth.ts";
+import { originOk } from "./start.ts";
+import type { RouteCtx } from "./index.ts";
+
+const PR = /^[0-9]{1,7}$/;
+const REF = /^[A-Za-z0-9._/][A-Za-z0-9._/-]{0,99}$/;
+const MAX_OUT = 256 * 1024;
+const MAX_PRS = 20;
+
+export interface CliResult { code: number | null; stdout: string; stderr: string; timedOut: boolean; capped: boolean; error?: string }
+
+/** Tunables, exported so tests can pin the production values and inject a short timeout. */
+export const limits = { mergeRunMs: 600_000, dryRunMs: 60_000, shortMs: 15_000, riskMs: 60_000, graceMs: 2_000, bodyMax: 5_000, maxConcurrent: 2 };
+
+const killGroup = (pid: number | undefined, sig: NodeJS.Signals): void => {
+  if (!pid) return;
+  try { process.kill(-pid, sig); } catch { /* group already gone */ }
+};
+
+/** Run the CLI with a fixed argv, detached in its own process group so a timeout or output-cap kill reaches every descendant. Never rejects. */
+export function runCli(bin: string, args: string[], cwd: string, timeoutMs: number, extraEnv: Record<string, string> = {}): Promise<CliResult> {
+  return new Promise((done) => {
+    let out = "", err = "", size = 0, timedOut = false, capped = false, settled = false, spawnErr: string | undefined;
+    let timer: ReturnType<typeof setTimeout> | undefined, hard: ReturnType<typeof setTimeout> | undefined;
+    const finish = (code: number | null): void => {
+      if (settled) return;
+      settled = true;
+      if (timer) clearTimeout(timer);
+      if (hard) clearTimeout(hard);
+      const error = spawnErr ?? (timedOut ? "timed out" : capped ? "output exceeded the size cap" : undefined);
+      done({ code: timedOut || capped ? null : code, stdout: out, stderr: err, timedOut, capped, error });
+    };
+    try {
+      const child = spawn(bin, args, { cwd, detached: true, stdio: ["ignore", "pipe", "pipe"], shell: false, env: { ...childEnv(), ...extraEnv }, windowsHide: true });
+      const stop = (): void => {
+        killGroup(child.pid, "SIGTERM");
+        hard = setTimeout(() => { killGroup(child.pid, "SIGKILL"); finish(null); }, limits.graceMs);
+      };
+      const take = (which: "o" | "e") => (d: Buffer): void => {
+        if (capped) return;
+        size += d.length;
+        if (size > MAX_OUT) { capped = true; stop(); return; }
+        if (which === "o") out += d.toString("utf8"); else err += d.toString("utf8");
+      };
+      child.stdout!.on("data", take("o"));
+      child.stderr!.on("data", take("e"));
+      child.once("error", (e) => { spawnErr = e.message; finish(null); });
+      child.once("close", (code) => { killGroup(child.pid, "SIGKILL"); finish(code); });
+      timer = setTimeout(() => { timedOut = true; stop(); }, timeoutMs);
+    } catch (e) { spawnErr = (e as Error).message; finish(null); }
+  });
+}
+
+export interface RiskReport { score: number; level: string; source: string; files: number | null; factors: Array<{ factor: string; points: number; max: number; detail: string }> }
+
+/** Parse `loki review --risk --json`. Anything that is not a well-formed 0-100 report is null (the caller says "not measured"). */
+export function parseRisk(out: string): RiskReport | null {
+  try {
+    const j = JSON.parse(out.trim()) as Record<string, unknown>;
+    const factors = j["factors"];
+    if (typeof j["score"] !== "number" || !Number.isFinite(j["score"]) || j["score"] < 0 || j["score"] > 100 || !Array.isArray(factors)) return null;
+    const fs = factors.map((f) => (f && typeof f === "object" ? (f as Record<string, unknown>) : {}));
+    if (!fs.every((f) => typeof f["factor"] === "string" && typeof f["points"] === "number" && typeof f["max"] === "number")) return null;
+    return {
+      score: j["score"], level: typeof j["level"] === "string" ? j["level"] : "unknown", source: typeof j["source"] === "string" ? j["source"] : "",
+      files: typeof j["files"] === "number" && Number.isFinite(j["files"]) && j["files"] >= 0 ? j["files"] : null,
+      factors: fs.map((f) => ({ factor: f["factor"] as string, points: f["points"] as number, max: f["max"] as number, detail: typeof f["detail"] === "string" ? f["detail"] : "" })),
+    };
+  } catch { return null; }
+}
+
+export function mount(ctx: RouteCtx): void {
+  const { act, db } = ctx;
+  const bin = () => ctx.startBin ?? process.env["LOKI_BIN"] ?? "loki";
+  const busy = new Set<string>();
+  const active = { run: 0, queue: 0, risk: 0 };
+  const real = (p: string): string | null => { try { return realpathSync(p); } catch { return null; } };
+
+  /** The repo must be one the server knows (cwd or the project registry), never an arbitrary path. Returns the REAL path so every lock and cwd is symlink-proof. */
+  const repoFor = (want: unknown): string | null => {
+    if (want === undefined || want === null || want === "") return real(ctx.repoDir);
+    if (typeof want !== "string" || want.includes("\0")) return null;
+    const known = new Map<string, string>();
+    for (const k of [ctx.repoDir, ...registryRepos()]) { const r = real(k); if (r) known.set(r, basename(resolve(k))); }
+    const wantReal = real(want);
+    if (wantReal && known.has(wantReal)) return wantReal;
+    const named = [...known].filter(([r, label]) => label === want || basename(r) === want).map(([r]) => r);
+    return named.length === 1 ? named[0]! : null;
+  };
+  /** Small per-route cap on concurrent CLI spawns. */
+  const slot = async <T,>(c: Context, kind: "run" | "queue" | "risk", auditKind: string, fn: () => Promise<T>): Promise<T | Response> => {
+    if (active[kind] >= limits.maxConcurrent) { audit(db, { kind: auditKind, result: "refused", detail: "too many concurrent requests" }); return c.json({ error: "too many concurrent requests" }, 429); }
+    active[kind]++;
+    try { return await fn(); } finally { active[kind]--; }
+  };
+  const refuse = (c: Context, kind: string, target: string | undefined, status: 400 | 403 | 413 | 422, error: string) => {
+    audit(db, { kind, target, result: "refused", detail: error });
+    return c.json({ error }, status);
+  };
+  /** Shared guard for mutating calls: loopback JSON, loopback Origin, bounded JSON body. */
+  const readBody = async (c: Context, kind: string): Promise<Record<string, unknown> | Response> => {
+    if (!ctx.local(c)) return refuse(c, kind, undefined, 403, "loopback JSON requests only");
+    if (!originOk(c.req.header("origin"))) return refuse(c, kind, undefined, 403, "origin not allowed");
+    const text = await c.req.text();
+    if (text.length > limits.bodyMax) return refuse(c, kind, undefined, 413, "body too large");
+    try {
+      const b = JSON.parse(text) as unknown;
+      return b && typeof b === "object" && !Array.isArray(b) ? (b as Record<string, unknown>) : refuse(c, kind, undefined, 400, "body must be a JSON object");
+    } catch { return refuse(c, kind, undefined, 400, "invalid JSON"); }
+  };
+
+  /** Spawning reads (no body, so no JSON check): loopback peer AND loopback Host, so DNS rebinding cannot drive a CLI spawn. Origin is checked after. */
+  const readGuard = (c: Context): boolean => ctx.peerIsLoopback(c) && isLoopbackHost(c.req.header("host"));
+
+  act.get("/v1/merge/queue", async (c) => {
+    if (!readGuard(c)) return refuse(c, "merge.list", undefined, 403, "loopback only");
+    if (!originOk(c.req.header("origin"))) return refuse(c, "merge.list", undefined, 403, "origin not allowed");
+    const cwd = repoFor(c.req.query("repo"));
+    if (!cwd) return refuse(c, "merge.list", undefined, 422, "repo is not a known project");
+    return slot(c, "queue", "merge.list", async () => {
+      const r = await runCli(bin(), ["merge", "list"], cwd, limits.shortMs);
+      if (r.code !== 0) return c.json({ measured: false, error: r.error ?? `loki merge list exited ${r.code}`, queue: [] });
+      const queue = r.stdout.split("\n").map((l) => /^#([0-9]{1,7})$/.exec(l.trim())?.[1]).filter((n): n is string => n !== undefined).map(Number);
+      return c.json({ measured: true, queue });
+    });
+  });
+
+  act.post("/v1/merge/queue", async (c) => {
+    const b = await readBody(c, "merge.add");
+    if (b instanceof Response) return b;
+    const raw = Array.isArray(b["prs"]) ? (b["prs"] as unknown[]) : b["pr"] !== undefined ? [b["pr"]] : [];
+    const prs = raw.map((p) => (typeof p === "number" && Number.isInteger(p) ? String(p) : p));
+    if (prs.length === 0 || prs.length > MAX_PRS || !prs.every((p) => typeof p === "string" && PR.test(p))) return refuse(c, "merge.add", undefined, 422, `prs must be 1 to ${MAX_PRS} PR numbers (digits only, 7 max)`);
+    const cwd = repoFor(b["repo"]);
+    if (!cwd) return refuse(c, "merge.add", undefined, 422, "repo is not a known project");
+    const list = prs as string[];
+    return slot(c, "queue", "merge.add", async () => {
+      const r = await runCli(bin(), ["merge", "add", ...list], cwd, limits.shortMs);
+      const ok = r.code === 0;
+      const error = ok ? undefined : (r.error ?? (r.stderr.trim() || `exit ${r.code}`));
+      audit(db, { kind: "merge.add", target: list.map((p) => `#${p}`).join(" "), result: ok ? "ok" : "error", detail: error });
+      return c.json({ ok, exit: r.code, output: r.stdout.trim(), error }, ok ? 200 : 500);
+    });
+  });
+
+  // dryRun is required and must be a boolean: a missing flag never silently becomes a real merge.
+  act.post("/v1/merge/run", async (c) => {
+    const b = await readBody(c, "merge.run");
+    if (b instanceof Response) return b;
+    if (typeof b["dryRun"] !== "boolean") return refuse(c, "merge.run", undefined, 422, "dryRun must be a boolean");
+    const dry = b["dryRun"];
+    const kind = dry ? "merge.dry_run" : "merge.run";
+    const cwd = repoFor(b["repo"]);
+    if (!cwd) return refuse(c, kind, undefined, 422, "repo is not a known project");
+    if (!dry && busy.has(cwd)) { audit(db, { kind, result: "conflict", detail: "merge already running" }); return c.json({ error: "a merge run is already in progress for this repo" }, 409); }
+    return slot(c, "run", kind, async () => {
+      if (!dry) busy.add(cwd);
+      try {
+        const ms = dry ? limits.dryRunMs : limits.mergeRunMs;
+        // The CLI polls checks per PR; keep its own budget well inside the route timeout so it ends itself before the group kill.
+        const poll = 20, tries = Math.max(1, Math.floor((ms / 1000) * 0.8 / poll));
+        const r = await runCli(bin(), dry ? ["merge", "run", "--dry-run"] : ["merge", "run"], cwd, ms, { LOKI_MERGE_POLL_S: String(poll), LOKI_MERGE_MAX_POLLS: String(tries) });
+        const lines = r.stdout.split("\n").filter(Boolean);
+        // Only exit 1 means "PRs left in the queue" (a result). Any other non-zero exit, a timeout or a cap kill is an error.
+        const noGh = /gh CLI is required/.test(r.stdout + r.stderr);
+        const ran = (r.code === 0 || r.code === 1) && !noGh;
+        if (!dry) for (const l of lines) { const m = /^#([0-9]{1,7}): merged$/.exec(l.trim()); if (m) audit(db, { kind: "merge.pr_merged", target: `#${m[1]}`, result: "ok", detail: r.timedOut ? "recorded before timeout" : undefined }); }
+        const reason = r.timedOut ? "merge run timed out; the outcome is partial, check the queue and the PRs" : r.capped ? "merge run output exceeded the size cap and was stopped; the outcome is partial" : noGh ? "the gh CLI is required and was not found; nothing was merged" : r.error ?? (!ran ? `loki merge run exited ${r.code}: ${r.stderr.trim().slice(0, 300)}` : undefined);
+        audit(db, { kind, result: !ran ? "error" : r.code === 0 ? "ok" : "blocked", detail: reason ?? lines.slice(-1)[0] });
+        return c.json({ ok: r.code === 0, ran, dryRun: dry, exit: r.code, lines, timedOut: r.timedOut, capped: r.capped, partial: r.timedOut || r.capped, error: reason }, ran ? 200 : 500);
+      } finally { if (!dry) busy.delete(cwd); }
+    });
+  });
+
+  act.get("/v1/review/risk", async (c) => {
+    if (!readGuard(c)) return refuse(c, "risk.read", undefined, 403, "loopback only");
+    if (!originOk(c.req.header("origin"))) return refuse(c, "risk.read", undefined, 403, "origin not allowed");
+    const pr = c.req.query("pr"), since = c.req.query("since"), staged = c.req.query("staged");
+    const given = [pr !== undefined, since !== undefined, staged !== undefined].filter(Boolean).length;
+    if (given !== 1) return refuse(c, "risk.read", undefined, 422, "give exactly one of pr, since or staged=1");
+    let flags: string[], target: string;
+    if (pr !== undefined) {
+      if (!PR.test(pr)) return refuse(c, "risk.read", undefined, 422, "pr must be digits only (7 max)");
+      flags = ["--pr", pr]; target = `#${pr}`;
+    } else if (since !== undefined) {
+      if (!REF.test(since)) return refuse(c, "risk.read", undefined, 422, "since must match [A-Za-z0-9._/-]{1,100} with no leading -");
+      flags = ["--since", since]; target = `since ${since}`;
+    } else {
+      if (staged !== "1") return refuse(c, "risk.read", undefined, 422, "staged must be 1");
+      flags = ["--staged"]; target = "staged";
+    }
+    const cwd = repoFor(c.req.query("repo"));
+    if (!cwd) return refuse(c, "risk.read", target, 422, "repo is not a known project");
+    return slot(c, "risk", "risk.read", async () => {
+      const r = await runCli(bin(), ["review", "--risk", "--json", ...flags], cwd, limits.riskMs);
+      const parsed = r.code === 0 ? parseRisk(r.stdout) : null;
+      if (!parsed) return c.json({ measured: false, reason: r.error ?? (r.code !== 0 ? `loki review exited ${r.code}: ${(r.stderr.trim() || r.stdout.trim()).slice(0, 300)}` : "output was not a risk report") });
+      return c.json({ measured: true, ...parsed });
+    });
+  });
+}

package/packages/control-plane/src/server/routes/metrics.ts

@@ -0,0 +1,93 @@
+// CPE24-P1: GET /v1/metrics, the Prometheus text exposition ported from dashboard/server.py (_build_metrics_text), same .loki/ flat-file sources.
+// Honest data: a gauge whose source is absent or unmeasured emits NO sample (only HELP/TYPE plus a "not measured" comment), never a 0.
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { probeAllowed, type RouteCtx } from "./index.ts";
+import { NOT_MEASURED, costSnapshot, lokiDirExists, lokiDirOf, readJson } from "./cost_ledger.ts";
+import { pidAlive } from "./fleet.ts";
+
+type Rec = Record<string, unknown>;
+const isObj = (v: unknown): v is Rec => typeof v === "object" && v !== null && !Array.isArray(v);
+const arr = (v: unknown) => (Array.isArray(v) ? v : []);
+
+export function buildMetricsText(repoDir: string, now = Date.now()): string {
+  if (!lokiDirExists(repoDir)) return "# loki_up 0\n";
+  const loki = lokiDirOf(repoDir);
+  const L: string[] = [];
+  const gauge = (name: string, help: string, type: string, samples: string[] | null) => {
+    L.push(`# HELP ${name} ${help}`, `# TYPE ${name} ${type}`);
+    if (samples === null) L.push(`# ${name} ${NOT_MEASURED}`); else L.push(...samples);
+    L.push("");
+  };
+  const stRaw = readJson(join(loki, "dashboard-state.json"));
+  const state: Rec | null = isObj(stRaw) ? stRaw : null;
+
+  let status = 0;
+  if (state?.mode === "paused") status = 2;
+  else if (state?.mode === "autonomous" || state?.mode === "running") status = 1;
+  else {
+    try { if (pidAlive(parseInt(readFileSync(join(loki, "loki.pid"), "utf8").trim(), 10))) status = 1; } catch { /* stopped */ }
+  }
+  gauge("loki_session_status", "Current session status (0=stopped, 1=running, 2=paused)", "gauge", [`loki_session_status ${status}`]);
+  gauge("loki_iteration_current", "Current iteration number", "gauge", typeof state?.iteration === "number" ? [`loki_iteration_current ${state.iteration}`] : null);
+  const maxIt = Number.parseInt(process.env.LOKI_MAX_ITERATIONS ?? "", 10);
+  gauge("loki_iteration_max", "Maximum configured iterations", "gauge", [`loki_iteration_max ${Number.isFinite(maxIt) ? maxIt : 1000}`]);
+
+  const tasks = state && isObj(state.tasks) ? state.tasks : null;
+  gauge("loki_tasks_total", "Number of tasks by status", "gauge", tasks ? [
+    `loki_tasks_total{status="pending"} ${arr(tasks.pending).length}`, `loki_tasks_total{status="in_progress"} ${arr(tasks.inProgress).length}`,
+    `loki_tasks_total{status="completed"} ${arr(tasks.completed).length}`, `loki_tasks_total{status="failed"} ${arr(tasks.failed).length}`,
+  ] : null);
+
+  let agents: unknown[] | null = null;
+  const af = readJson(join(loki, "state", "agents.json"));
+  if (Array.isArray(af) && af.length) agents = af;
+  else if (state && Array.isArray(state.agents) && state.agents.length) agents = state.agents;
+  const active = (agents ?? []).filter((a) => isObj(a) && a.status === "active").length;
+  gauge("loki_agents_active", "Number of currently active agents", "gauge", agents ? [`loki_agents_active ${active}`] : null);
+  gauge("loki_agents_total", "Total number of agents registered", "gauge", agents ? [`loki_agents_total ${agents.length}`] : null);
+
+  const cost = costSnapshot(loki);
+  gauge("loki_cost_usd", "Estimated total cost in USD", "gauge", cost.estimated_cost_usd !== null ? [`loki_cost_usd ${cost.estimated_cost_usd}`] : null);
+
+  let events: number | null = null;
+  try { events = readFileSync(join(loki, "events.jsonl"), "utf8").split("\n").filter((l) => l.trim()).length; } catch { /* absent */ }
+  gauge("loki_events_total", "Total number of events recorded", "counter", events !== null ? [`loki_events_total ${events}`] : null);
+
+  let uptime: number | null = null;
+  if (typeof state?.startedAt === "string") {
+    const s = Date.parse(state.startedAt);
+    if (!Number.isNaN(s)) uptime = Math.max(0, Math.round(((now - s) / 1000) * 10) / 10);
+  }
+  gauge("loki_uptime_seconds", "Seconds since session started", "gauge", uptime !== null ? [`loki_uptime_seconds ${uptime}`] : null);
+
+  let total = 0, ver = 0, gaps = 0, notver = 0, unk = 0, att = 0, sig = 0;
+  const pdir = join(loki, "proofs");
+  let entries: string[] = [];
+  try { entries = readdirSync(pdir).sort(); } catch { /* none */ }
+  for (const e of entries) {
+    try { if (!statSync(join(pdir, e)).isDirectory()) continue; } catch { continue; }
+    const d = readJson(join(pdir, e, "proof.json"));
+    if (!isObj(d)) continue;
+    total++;
+    const head = isObj(d.honesty) ? d.honesty.headline : null;
+    if (head === "VERIFIED") ver++; else if (head === "VERIFIED WITH GAPS") gaps++; else if (head === "NOT VERIFIED") notver++; else unk++;
+    if (isObj(d.verification)) { if (d.verification.attestation) att++; if (d.verification.gpg_signature) sig++; }
+  }
+  gauge("loki_receipts_total", "Evidence Receipts on disk", "gauge", [`loki_receipts_total ${total}`]);
+  gauge("loki_receipts_by_verdict", "Receipts bucketed on the recorded honesty headline", "gauge", [
+    `loki_receipts_by_verdict{verdict="verified"} ${ver}`, `loki_receipts_by_verdict{verdict="with_gaps"} ${gaps}`,
+    `loki_receipts_by_verdict{verdict="not_verified"} ${notver}`, `loki_receipts_by_verdict{verdict="unknown"} ${unk}`,
+  ]);
+  gauge("loki_receipts_with_provenance", "Receipts carrying a checkable provenance record", "gauge", [
+    `loki_receipts_with_provenance{kind="attestation"} ${att}`, `loki_receipts_with_provenance{kind="gpg"} ${sig}`,
+  ]);
+  return L.join("\n") + "\n";
+}
+
+export function mount(ctx: RouteCtx): void {
+  ctx.app.get("/v1/metrics", (c) => {
+    if (!probeAllowed(ctx, c)) return c.json({ error: "loopback only without a token" }, 403);
+    return c.text(buildMetricsText(ctx.repoDir), 200, { "content-type": "text/plain; version=0.0.4; charset=utf-8" });
+  });
+}

package/packages/control-plane/src/server/routes/notify.ts

@@ -0,0 +1,48 @@
+// GET /v1/notifications: derived from the runs projection and stored events. Nothing is stored or invented; unread state is client-side.
+import { desc, inArray } from "drizzle-orm";
+import type { Db } from "../../db/migrate.ts";
+import { events, runs } from "../../db/schema.ts";
+import { effectiveVerdict } from "../integrity.ts";
+import type { RouteCtx } from "./index.ts";
+
+export type NotificationKind = "blocked" | "finished" | "tampered" | "conflict" | "budget";
+export interface Notification {
+  id: string; kind: NotificationKind; ts: string; source_id: string; run_id: string;
+  verdict: string | null; title: string; link: string;
+}
+
+const BUDGET_TYPES = ["cap.hit", "budget.hit"];
+
+export function deriveNotifications(db: Db): Notification[] {
+  const out: Notification[] = [];
+  const mk = (kind: NotificationKind, s: string, r: string, ts: string | null, verdict: string | null, title: string, extra = ""): void => {
+    out.push({ id: `${kind}:${s}:${r}${extra}`, kind, ts: ts ?? "", source_id: s, run_id: r, verdict, title, link: `/runs/${encodeURIComponent(s)}/${encodeURIComponent(r)}` });
+  };
+  for (const r of db.select().from(runs).all()) {
+    const when = r.endedAt ?? r.lastEventAt ?? r.startedAt;
+    const name = r.originRepo ?? r.runId;
+    if (r.verdict === "SPEC_CONFLICT") mk("blocked", r.sourceId, r.runId, when, r.verdict, `Blocked, waiting for your answer: ${name}`);
+    else if (r.endedAt && r.verdict) {
+      const ev = effectiveVerdict({ verdict: r.verdict, tampered: r.tampered === 1, attested: r.attested === 1, sig_checked: r.sigChecked === 1 }) ?? r.verdict;
+      mk("finished", r.sourceId, r.runId, r.endedAt, ev, `Finished ${ev}: ${name}`);
+    }
+    if (r.tampered === 1) mk("tampered", r.sourceId, r.runId, when, r.verdict, `Event log failed its integrity check: ${name}`);
+    if (r.conflict === 1) mk("conflict", r.sourceId, r.runId, when, r.verdict, `Ingest conflict, a stored event was contradicted: ${name}`);
+  }
+  for (const e of db.select({ s: events.sourceId, r: events.runId, seq: events.seq, ts: events.ts, type: events.type }).from(events).where(inArray(events.type, BUDGET_TYPES)).orderBy(desc(events.ts)).all()) {
+    mk("budget", e.s, e.r, e.ts, null, `Stopped at its ${e.type === "cap.hit" ? "time" : "budget"} cap: ${e.r}`, `:${e.seq}`);
+  }
+  return out.sort((a, b) => (a.ts < b.ts ? 1 : a.ts > b.ts ? -1 : a.id < b.id ? -1 : 1));
+}
+
+export function mount(ctx: RouteCtx): void {
+  ctx.app.get("/v1/notifications", (c) => {
+    const all = deriveNotifications(ctx.db);
+    const limit = Math.min(Math.max(Number.parseInt(c.req.query("limit") ?? "50", 10) || 50, 1), 200);
+    const offset = Math.max(Number.parseInt(c.req.query("cursor") ?? "0", 10) || 0, 0);
+    const kind = c.req.query("kind");
+    const list = kind ? all.filter((n) => n.kind === kind) : all;
+    const page = list.slice(offset, offset + limit);
+    return c.json({ notifications: page, total: list.length, next_cursor: offset + page.length < list.length ? String(offset + page.length) : null });
+  });
+}