loki-mode 10.7.0 → 10.8.0

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

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

@@ -0,0 +1,111 @@
+// GET /v1/providers (CPE-15): which provider CLIs are installed, their versions, which auth env var NAMES are set (never values), and the model tiers.
+// Behind the /v1 token guard. Every probe is bounded by a timeout; nothing here reads or returns a secret value.
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { delimiter, join } from "node:path";
+import { probeAllowed, ttlCache, type RouteCtx } from "./index.ts";
+
+const ORDER = ["claude", "codex", "cline", "aider", "opencode"] as const;
+const DEPRECATED = ["gemini"] as const;
+const AUTH_ENV: Record<string, string[]> = {
+  claude: ["ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN", "CLAUDE_CODE_OAUTH_TOKEN"],
+  codex: ["OPENAI_API_KEY"],
+  cline: ["ANTHROPIC_API_KEY", "OPENROUTER_API_KEY", "OPENAI_API_KEY"],
+  aider: ["ANTHROPIC_API_KEY", "OPENAI_API_KEY", "OPENROUTER_API_KEY"],
+  opencode: ["ANTHROPIC_API_KEY", "OPENAI_API_KEY", "OPENROUTER_API_KEY"],
+  gemini: ["GEMINI_API_KEY", "GOOGLE_API_KEY"],
+};
+const DEFAULT_TIMEOUT_MS = 3000;
+
+export interface ProbeResult { installed: boolean; version: string | null; probe: "ok" | "timeout" | "error" | "not_found" }
+
+function findOnPath(bin: string, pathVar: string): string | null {
+  for (const d of pathVar.split(delimiter)) {
+    if (!d) continue;
+    const p = join(d, bin);
+    if (existsSync(p)) return p;
+  }
+  return null;
+}
+
+/** Run `<bin> --version` with a hard timeout. Only a version-looking token is returned, never raw output. */
+export function probeCli(bin: string, timeoutMs: number, pathVar = process.env.PATH ?? ""): Promise<ProbeResult> {
+  const exe = findOnPath(bin, pathVar);
+  if (!exe) return Promise.resolve({ installed: false, version: null, probe: "not_found" });
+  return new Promise((resolve) => {
+    let out = "";
+    let done = false;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const finish = (r: ProbeResult): void => { if (!done) { done = true; clearTimeout(timer); resolve(r); } };
+    let child: ReturnType<typeof spawn>;
+    try {
+      child = spawn(exe, ["--version"], { stdio: ["ignore", "pipe", "ignore"], env: { ...process.env, NO_COLOR: "1" } });
+    } catch {
+      return resolve({ installed: true, version: null, probe: "error" });
+    }
+    timer = setTimeout(() => {
+      try { child.kill("SIGKILL"); } catch { /* already gone */ }
+      finish({ installed: true, version: null, probe: "timeout" });
+    }, timeoutMs);
+    child.stdout?.on("data", (d: Buffer) => { if (out.length < 2048) out += d.toString("utf8"); });
+    child.on("error", () => finish({ installed: true, version: null, probe: "error" }));
+    child.on("close", () => {
+      const m = /\d+\.\d+(?:\.\d+)?(?:[-+.][0-9A-Za-z.]+)?/.exec(out);
+      finish({ installed: true, version: m ? m[0] : null, probe: "ok" });
+    });
+  });
+}
+
+function providersDir(): string | null {
+  const cands = [process.env.LOKI_PROVIDERS_DIR, join(import.meta.dir, "../../../../../providers"), join(import.meta.dir, "../../../providers")];
+  return cands.find((d): d is string => !!d && existsSync(join(d, "model_catalog.json"))) ?? null;
+}
+
+interface CatalogModel { id?: string; alias?: string; tier?: string }
+interface CatalogProvider { models?: CatalogModel[]; latest_planning?: string; latest_development?: string; latest_fast?: string }
+
+function loadCatalog(dir: string | null): { providers: Record<string, CatalogProvider>; updated: string | null } {
+  if (!dir) return { providers: {}, updated: null };
+  try {
+    const j = JSON.parse(readFileSync(join(dir, "model_catalog.json"), "utf8"));
+    return { providers: j.providers ?? {}, updated: typeof j.updated === "string" ? j.updated : null };
+  } catch { return { providers: {}, updated: null }; }
+}
+
+export async function listProviders(timeoutMs = DEFAULT_TIMEOUT_MS): Promise<unknown> {
+  const cat = loadCatalog(providersDir());
+  const names = [...ORDER, ...DEPRECATED];
+  const rows = await Promise.all(names.map(async (name) => {
+    const probe = await probeCli(name, timeoutMs);
+    const envNames = AUTH_ENV[name] ?? [];
+    const envSet = envNames.filter((n) => (process.env[n] ?? "") !== "");
+    const cp = cat.providers[name];
+    const tiers: Record<string, string | null> = cp
+      ? { planning: cp.latest_planning ?? null, development: cp.latest_development ?? null, fast: cp.latest_fast ?? null }
+      : {};
+    const models = (cp?.models ?? []).filter((m) => m.id).map((m) => ({ id: m.id as string, alias: m.alias ?? null, tier: m.tier ?? null }));
+    return {
+      id: name,
+      deprecated: (DEPRECATED as readonly string[]).includes(name),
+      installed: probe.installed,
+      version: probe.version,
+      probe: probe.probe,
+      auth_env_names: envNames,
+      auth_env_set: envSet,
+      auth_present: envSet.length > 0,
+      tiers,
+      models,
+    };
+  }));
+  return { providers: rows, catalog_updated: cat.updated, probe_timeout_ms: timeoutMs };
+}
+
+export function mount(ctx: RouteCtx): void {
+  const cached = ttlCache<unknown>();
+  ctx.app.get("/v1/providers", async (c) => {
+    if (!probeAllowed(ctx, c)) return c.json({ error: "loopback only without a token" }, 403);
+    const t = Number.parseInt(process.env.LOKI_PROVIDER_PROBE_TIMEOUT_MS ?? "", 10);
+    const ms = t > 0 ? t : DEFAULT_TIMEOUT_MS;
+    return c.json(await cached(String(ms), () => listProviders(ms)));
+  });
+}

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

@@ -0,0 +1,39 @@
+// CPE-07: POST /v1/runs (and the /v1/start alias) starts a run. Registered on the loopback-only router, so a non-loopback bind never has it.
+import type { Context } from "hono";
+import { isLoopbackHost } from "../auth.ts";
+import { audit } from "../audit.ts";
+import { planStart, registryRepos, spawnStart } from "../spawn.ts";
+import type { RouteCtx } from "./index.ts";
+
+/** A browser always sends Origin on a cross-site POST. Absent is a non-browser client (allowed, the peer check still applies); present must be a loopback http(s) origin. */
+export function originOk(origin: string | undefined | null): boolean {
+  if (origin === undefined || origin === null) return true;
+  try {
+    const u = new URL(origin);
+    return (u.protocol === "http:" || u.protocol === "https:") && isLoopbackHost(u.host);
+  } catch { return false; }
+}
+
+export function mount(ctx: RouteCtx): void {
+  const { act, db, repoDir, local } = ctx;
+  const inflight = new Set<string>();
+  const handler = async (c: Context) => {
+    if (!local(c)) return c.json({ error: "loopback JSON requests only" }, 403);
+    if (!originOk(c.req.header("origin"))) return c.json({ error: "origin not allowed" }, 403);
+    const text = await c.req.text();
+    if (text.length > 20_000) return c.json({ error: "body too large" }, 413);
+    let body: unknown;
+    try { body = JSON.parse(text); } catch { return c.json({ error: "invalid JSON" }, 400); }
+    const target = typeof (body as { target?: unknown } | null)?.target === "string" ? (body as { target: string }).target : undefined;
+    const plan = planStart(body, [repoDir, ...registryRepos()], ctx.startBin);
+    if (!plan.ok) { audit(db, { kind: "run.start", target, result: "refused", detail: plan.error }); return c.json({ error: plan.error }, 400); }
+    if (inflight.has(plan.cwd)) { audit(db, { kind: "run.start", target, result: "conflict", detail: "start already in flight" }); return c.json({ error: "a run is already starting or running in this repo" }, 409); }
+    inflight.add(plan.cwd);
+    const r = await (ctx.spawnImpl ?? spawnStart)(plan.argv, plan.cwd, () => inflight.delete(plan.cwd), plan.env);
+    if ("error" in r) { inflight.delete(plan.cwd); audit(db, { kind: "run.start", target, result: "error", detail: r.error }); return c.json({ error: r.error }, 500); }
+    audit(db, { kind: "run.start", target, result: "started", detail: `pid ${r.pid}; ${plan.argv.slice(1).join(" ")}` });
+    return c.json({ ok: true, pid: r.pid, command: plan.argv.slice(1).join(" ") });
+  };
+  act.post("/v1/runs", handler);
+  act.post("/v1/start", handler);
+}

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

@@ -0,0 +1,76 @@
+// GET /v1/stats?since=<ISO>: counts, verified rate, cost (measured and partial kept apart) and the receipts count, folded from the runs projection and stored events.
+// An unpriced run is never summed as zero: its known part is reported as partial, and a window with nothing priced reads null.
+import { eq } from "drizzle-orm";
+import type { Db } from "../../db/migrate.ts";
+import { events, runs } from "../../db/schema.ts";
+import { effectiveVerdict, pubkeysFromEnv } from "../integrity.ts";
+import type { RouteCtx } from "./index.ts";
+
+export interface Stats {
+  since: string | null;
+  runs_total: number;
+  runs_finished: number;
+  runs_running: number;
+  by_verdict: Record<string, number>;
+  blocked_waiting: number;
+  /** Plain VERIFIED (attested, signature-checked) over finished runs that carry a verdict; null when there are none. */
+  verified_rate: number | null;
+  /** Finished successes whose signature could not be checked (VERIFIED (signature not checked)); a rate of 0 with these is "not measured", not "failing". */
+  verified_unchecked: number;
+  /** At least one receipt verification key is configured (LOKI_CP_RECEIPT_PUBKEYS). */
+  keys_configured: boolean;
+  cost: {
+    /** Sum over runs whose cost is fully measured; null when no run in the window is. */
+    measured_usd: number | null;
+    measured_runs: number;
+    /** Sum of the known part of runs with an unpriced session (a lower bound); null when there are none. */
+    partial_usd: number | null;
+    partial_runs: number;
+    label: "measured" | "partial" | "not measured";
+  };
+  receipts: { total: number; signed: number };
+}
+
+export function computeStats(db: Db, since: string | null): Stats {
+  const all = db.select().from(runs).all().filter((r) => !since || (r.startedAt !== null && r.startedAt >= since));
+  const by: Record<string, number> = {};
+  let finished = 0, running = 0, blocked = 0, withVerdict = 0, verified = 0, unchecked = 0;
+  let mUsd = 0, mRuns = 0, pUsd = 0, pRuns = 0;
+  for (const r of all) {
+    if (r.endedAt) finished++; else running++;
+    // FC-08 effective verdict: a tampered log reads TAMPERED, an unattested or unchecked success is never counted as plain VERIFIED (L3, L7)
+    const verdict = r.verdict ? effectiveVerdict({ verdict: r.verdict, tampered: r.tampered === 1, attested: r.attested === 1, sig_checked: r.sigChecked === 1 }) : null;
+    if (verdict) {
+      by[verdict] = (by[verdict] ?? 0) + 1;
+      if (r.endedAt) { withVerdict++; if (verdict === "VERIFIED") verified++; else if (verdict === "VERIFIED (signature not checked)") unchecked++; }
+    }
+    if (r.verdict === "SPEC_CONFLICT") blocked++;
+    if (r.costUsd !== null) { mUsd += r.costUsd; mRuns++; }
+    else if (r.totalSessions > 0) { pUsd += r.partialUsd; pRuns++; }
+  }
+  const keys = new Set(all.map((r) => `${r.sourceId}/${r.runId}`));
+  let total = 0, signed = 0;
+  for (const e of db.select({ s: events.sourceId, r: events.runId, data: events.data }).from(events).where(eq(events.type, "receipt.sealed")).all()) {
+    if (!keys.has(`${e.s}/${e.r}`)) continue;
+    total++;
+    if ((e.data as { signed?: unknown } | null)?.signed === true) signed++;
+  }
+  const r6 = (n: number): number => Math.round(n * 1e6) / 1e6;
+  return {
+    since, runs_total: all.length, runs_finished: finished, runs_running: running, by_verdict: by, blocked_waiting: blocked,
+    verified_rate: withVerdict ? verified / withVerdict : null, verified_unchecked: unchecked, keys_configured: pubkeysFromEnv().configured === true,
+    cost: {
+      measured_usd: mRuns ? r6(mUsd) : null, measured_runs: mRuns, partial_usd: pRuns ? r6(pUsd) : null, partial_runs: pRuns,
+      label: pRuns ? "partial" : mRuns ? "measured" : "not measured",
+    },
+    receipts: { total, signed },
+  };
+}
+
+export function mount(ctx: RouteCtx): void {
+  ctx.app.get("/v1/stats", (c) => {
+    const since = c.req.query("since") ?? null;
+    if (since !== null && (!/^\d{4}-\d{2}-\d{2}/.test(since) || Number.isNaN(Date.parse(since)))) return c.json({ error: "since must be an ISO date or timestamp" }, 400);
+    return c.json(computeStats(ctx.db, since === null ? null : new Date(since).toISOString()));
+  });
+}