loki-mode 10.7.1 → 10.9.1

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/session_control.ts

@@ -0,0 +1,155 @@
+// CPE24-P4: session control and the Completion Council, ported from dashboard/server.py (/api/control/{pause,resume,stop}, /api/council/*).
+// Trust (HIGH tier): control accepts only the fixed ACTIONS enum, never a command string, and writes only the signal files run.sh already
+// reads (.loki/PAUSE, .loki/STOP, .loki/signals/COUNCIL_REVIEW_REQUESTED) holding a timestamp. It spawns and signals nothing.
+// Council reads are read-only, take no path from the caller, and cap what they return.
+import { existsSync, mkdirSync, readdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import type { Context } from "hono";
+import { audit } from "../audit.ts";
+import type { Db } from "../../db/migrate.ts";
+import { probeAllowed, type RouteCtx } from "./index.ts";
+import { pidAlive } from "./fleet.ts";
+import { lokiDirOf } from "./cost_ledger.ts";
+
+type Rec = Record<string, unknown>;
+const isObj = (v: unknown): v is Rec => typeof v === "object" && v !== null && !Array.isArray(v);
+
+export const ACTIONS = ["pause", "resume", "stop", "council-review"] as const;
+export type ControlAction = (typeof ACTIONS)[number];
+export const isAction = (v: string): v is ControlAction => (ACTIONS as readonly string[]).includes(v);
+
+/** A browser Origin, when present, must be this server's own host; a cross-site fetch is refused. Absent Origin (curl, the CLI, the extension host) is allowed. */
+export function sameOrigin(c: Context): boolean {
+  if (c.req.header("sec-fetch-site") === "cross-site") 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; }
+}
+
+const readJson = (p: string): unknown => { try { return JSON.parse(readFileSync(p, "utf8")); } catch { return null; } };
+
+function runnerPid(loki: string): number | null {
+  try { const pid = parseInt(readFileSync(join(loki, "loki.pid"), "utf8").trim(), 10); return pidAlive(pid) ? pid : null; } catch { return null; }
+}
+
+export interface ControlResult { status: 200 | 503; body: Rec }
+
+/** Applies one enum action to <repoDir>/.loki by writing or removing a signal file. Never signals a process. */
+export function applyControl(repoDir: string, action: ControlAction): ControlResult {
+  const loki = lokiDirOf(repoDir);
+  const running = runnerPid(loki) !== null;
+  const put = (rel: string) => { const f = join(loki, rel); mkdirSync(dirname(f), { recursive: true }); writeFileSync(f, new Date().toISOString()); };
+  if (action === "council-review") { put(join("signals", "COUNCIL_REVIEW_REQUESTED")); return { status: 200, body: { success: true, message: "Council review requested" } }; }
+  if (action === "resume") {
+    for (const n of ["PAUSE", "STOP"]) { try { unlinkSync(join(loki, n)); } catch { /* absent */ } }
+    return running ? { status: 200, body: { success: true, message: "Session resumed", process_verified: true } }
+      : { status: 503, body: { success: false, message: "Session process is not running; the signal files were cleared" } };
+  }
+  put(action === "pause" ? "PAUSE" : "STOP");
+  if (!running) return { status: 503, body: { success: false, message: `Session process is not running; the ${action} signal may have no effect` } };
+  return { status: 200, body: { success: true, message: action === "pause" ? "Session paused" : "Stop requested; the runner exits at its next check", process_verified: true } };
+}
+
+/** Runs the guarded, audited control action; shared by /v1/control/:action and the legacy mappings. */
+export function runControl(db: Db, repoDir: string, action: ControlAction, c: Context, via: string): Response {
+  if (!sameOrigin(c)) { audit(db, { kind: `session.${action}`, target: via, result: "refused", detail: "origin not allowed" }); return c.json({ error: "origin not allowed" }, 403); }
+  const r = applyControl(repoDir, action);
+  audit(db, { kind: `session.${action}`, target: via, result: r.status === 200 ? "ok" : "unverified" });
+  return c.json(r.body, r.status);
+}
+
+export function councilState(loki: string): Rec {
+  const f = join(loki, "council", "state.json");
+  if (!existsSync(f)) return { enabled: false, total_votes: 0, verdicts: [] };
+  const d = readJson(f);
+  return isObj(d) ? d : { enabled: null, total_votes: null, verdicts: null, error: "unreadable_state" };
+}
+
+export function councilVerdicts(loki: string, limit = 20): Rec {
+  const st = readJson(join(loki, "council", "state.json"));
+  const verdicts = isObj(st) && Array.isArray(st.verdicts) ? st.verdicts : [];
+  const votes = join(loki, "council", "votes");
+  const details: Rec[] = [];
+  let names: string[] = [];
+  try { names = readdirSync(votes, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name).sort().reverse(); } catch { /* none */ }
+  const text = (p: string) => { try { return readFileSync(p, "utf8"); } catch { return null; } };
+  for (const n of names.slice(0, limit)) {
+    const dir = join(votes, n), d: Rec = { iteration: n };
+    const ev = text(join(dir, "evidence.md"));
+    if (ev !== null) d.evidence_preview = ev.slice(0, 500);
+    let files: string[] = [];
+    try { files = readdirSync(dir).filter((f) => /^member-.*\.txt$/.test(f)).sort(); } catch { /* none */ }
+    d.members = files.flatMap((f) => { const t = text(join(dir, f)); return t === null ? [] : [{ member: f.replace(/\.txt$/, ""), content: t.trim() }]; });
+    const con = text(join(dir, "contrarian.txt"));
+    if (con !== null) d.contrarian = con.trim();
+    details.push(d);
+  }
+  return { verdicts, details };
+}
+
+export function councilConvergence(loki: string): Rec {
+  const dataPoints: Rec[] = [];
+  let raw = "";
+  try { raw = readFileSync(join(loki, "council", "convergence.log"), "utf8"); } catch { /* none */ }
+  for (const line of raw.trim().split("\n")) {
+    const p = line.split("|");
+    if (p.length < 5) continue;
+    const n = p.slice(1, 5).map((x) => (/^-?\d+$/.test(x.trim()) ? Number(x) : NaN));
+    if (n.some(Number.isNaN)) continue;
+    dataPoints.push({ timestamp: p[0], iteration: n[0], files_changed: n[1], no_change_streak: n[2], done_signals: n[3] });
+  }
+  return { dataPoints };
+}
+
+export function councilReport(loki: string): Rec {
+  try { return { report: readFileSync(join(loki, "council", "report.md"), "utf8") }; } catch { return { report: null }; }
+}
+
+export function councilTranscripts(loki: string, q: { limit?: number; since?: string; iter_min?: number }): Rec {
+  const limit = Math.min(Math.max(q.limit ?? 20, 1), 200);
+  let since: number | null = null;
+  if (q.since) { since = Date.parse(q.since); if (Number.isNaN(since)) return { error: "Invalid 'since' timestamp format; expected ISO8601" }; }
+  const dir = join(loki, "council", "transcripts");
+  let names: string[] = [];
+  try { names = readdirSync(dir).filter((f) => /^iter-.*\.json$/.test(f)).sort().reverse(); } catch { return { transcripts: [], total: 0, latest_id: null }; }
+  const out: Rec[] = [];
+  for (const n of names) {
+    const rec = readJson(join(dir, n));
+    if (!isObj(rec) || typeof rec.iteration_id !== "string") continue;
+    if (since !== null) { const t = Date.parse(String(rec.timestamp ?? "")); if (Number.isNaN(t) || t <= since) continue; }
+    if (q.iter_min !== undefined && Number(rec.iteration ?? 0) < q.iter_min) continue;
+    out.push(rec);
+    if (out.length >= limit) break;
+  }
+  return { transcripts: out, total: out.length, latest_id: out.length ? out[0]!.iteration_id : null };
+}
+
+/** Parses an optional non-negative integer query param: undefined when absent, null when malformed or above max. */
+export const intQ = (v: string | undefined, max: number): number | undefined | null => (v === undefined ? undefined : /^\d+$/.test(v) && Number(v) <= max ? Number(v) : null);
+
+export function mount(ctx: RouteCtx): void {
+  const deny = { error: "loopback only without a token" };
+  const loki = () => lokiDirOf(ctx.repoDir);
+  // Control: registered on `act` (loopback-bound servers only); real loopback peer plus JSON content type (ctx.local), the CP bearer via tokenGuard, and same-origin.
+  ctx.act.post("/v1/control/:action", (c) => {
+    if (!ctx.local(c)) return c.json({ error: "loopback JSON requests only" }, 403);
+    const action = c.req.param("action");
+    if (!isAction(action)) return c.json({ error: `action must be one of ${ACTIONS.join(", ")}` }, 400);
+    return runControl(ctx.db, ctx.repoDir, action, c, "v1");
+  });
+  const read = (path: string, f: (c: Context) => Response | Rec) => ctx.app.get(path, (c) => {
+    if (!probeAllowed(ctx, c)) return c.json(deny, 403);
+    const r = f(c);
+    return r instanceof Response ? r : c.json(r);
+  });
+  read("/v1/council/state", () => councilState(loki()));
+  read("/v1/council/verdicts", (c) => { const n = intQ(c.req.query("limit"), 1000); return n === null || n === 0 ? c.json({ error: "limit must be 1..1000" }, 422) : councilVerdicts(loki(), n); });
+  read("/v1/council/convergence", () => councilConvergence(loki()));
+  read("/v1/council/report", () => councilReport(loki()));
+  read("/v1/council/transcripts", (c) => {
+    const limit = intQ(c.req.query("limit"), 200), iterMin = intQ(c.req.query("iter_min"), Number.MAX_SAFE_INTEGER);
+    if (limit === null || limit === 0 || iterMin === null) return c.json({ error: "limit must be 1..200 and iter_min a non-negative integer" }, 422);
+    const r = councilTranscripts(loki(), { limit, since: c.req.query("since"), iter_min: iterMin });
+    return "error" in r ? c.json(r, 400) : r;
+  });
+}

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

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

@@ -0,0 +1,85 @@
+// CPE-05: Server-Sent Events for one run's new events and for runs-list changes.
+// Driven by the store: a short poll of the events table sees rows from ingest (and so from the shipper watcher) with no coupling to the writer.
+// Auth: /v1/* is already behind tokenGuard in app.ts. Streams are bounded; a disconnect frees its slot.
+import { and, asc, eq, gt, sql } from "drizzle-orm";
+import { events, runs } from "../../db/schema.ts";
+import type { RouteCtx } from "./index.ts";
+
+const num = (v: string | undefined, d: number) => { const n = Number(v); return Number.isFinite(n) && n > 0 ? n : d; };
+
+export function mount(ctx: RouteCtx): void {
+  const pollMs = num(process.env.LOKI_CONTROL_STREAM_POLL_MS, 1000);
+  const heartbeatMs = num(process.env.LOKI_CONTROL_STREAM_HEARTBEAT_MS, 15000);
+  const maxStreams = num(process.env.LOKI_CONTROL_STREAM_MAX, 32);
+  const { db } = ctx;
+  const enc = new TextEncoder();
+  let open = 0;
+
+  const headers = { "content-type": "text/event-stream", "cache-control": "no-cache, no-transform", connection: "keep-alive", "x-accel-buffering": "no" };
+
+  /** Open one SSE response. tick() runs each poll and returns frames to send; the slot is freed exactly once on abort, cancel or error. */
+  const sse = (signal: AbortSignal, hello: string, tick: () => string[]): Response => {
+    if (open >= maxStreams) return Response.json({ error: "too many streams" }, { status: 429, headers: { "retry-after": "5" } });
+    open++;
+    let freed = false;
+    let poll: ReturnType<typeof setInterval> | undefined;
+    let beat: ReturnType<typeof setInterval> | undefined;
+    const free = () => { if (freed) return; freed = true; clearInterval(poll); clearInterval(beat); open--; };
+    const body = new ReadableStream<Uint8Array>({
+      start(ctrl) {
+        const send = (s: string) => { try { ctrl.enqueue(enc.encode(s)); } catch { free(); } };
+        const close = () => { free(); try { ctrl.close(); } catch { /* already closed */ } };
+        send(hello);
+        poll = setInterval(() => { try { for (const f of tick()) send(f); } catch { close(); } }, pollMs);
+        beat = setInterval(() => send(": heartbeat\n\n"), heartbeatMs);
+        if (signal.aborted) close(); else signal.addEventListener("abort", close, { once: true });
+      },
+      cancel: free,
+    });
+    return new Response(body, { headers });
+  };
+
+  const maxSeq = (source: string, run: string): number =>
+    db.select({ m: sql<number | null>`max(${events.seq})` }).from(events).where(and(eq(events.sourceId, source), eq(events.runId, run))).get()?.m ?? -1;
+
+  ctx.app.get("/v1/runs/:source/:run/stream", (c) => {
+    const source = c.req.param("source"), run = c.req.param("run");
+    if (!db.select({ r: runs.runId }).from(runs).where(and(eq(runs.sourceId, source), eq(runs.runId, run))).get()) return c.json({ error: "run not found" }, 404);
+    // Resume point: Last-Event-ID (reconnect) or ?after=; a fresh client with neither gets only events from now on.
+    const given = c.req.header("last-event-id") ?? c.req.query("after");
+    const parsed = given === undefined || given === "" ? NaN : Number(given);
+    let cursor = Number.isInteger(parsed) ? parsed : maxSeq(source, run);
+    const tick = (): string[] => {
+      const rows = db.select().from(events).where(and(eq(events.sourceId, source), eq(events.runId, run), gt(events.seq, cursor))).orderBy(asc(events.seq)).limit(200).all();
+      if (rows.length) cursor = rows[rows.length - 1]!.seq;
+      return rows.map((e) => `id: ${e.seq}\nevent: event\ndata: ${JSON.stringify({ run: e.runId, seq: e.seq, ts: e.ts, type: e.type, stage: e.stage, data: e.data })}\n\n`);
+    };
+    const first = tick(); // replay for a resuming client is flushed with the hello
+    return sse(c.req.raw.signal, `retry: 3000\n: connected\n\n${first.join("")}`, tick);
+  });
+
+  ctx.app.get("/v1/stream", (c) => {
+    const snapshot = (): Map<string, string> => {
+      const m = new Map<string, string>();
+      for (const e of db.select({ s: events.sourceId, r: events.runId, m: sql<number>`max(${events.seq})` }).from(events).groupBy(events.sourceId, events.runId).all()) m.set(`${e.s}:${e.r}`, String(e.m));
+      for (const r of db.select({ s: runs.sourceId, r: runs.runId, v: runs.verdict, e: runs.endedAt }).from(runs).all()) {
+        const k = `${r.s}:${r.r}`;
+        m.set(k, `${m.get(k) ?? ""}|${r.v ?? ""}|${r.e ?? ""}`);
+      }
+      return m;
+    };
+    let seen = snapshot();
+    const tick = (): string[] => {
+      const now = snapshot();
+      const out: string[] = [];
+      for (const [k, sig] of now) {
+        if (seen.get(k) === sig) continue;
+        const i = k.indexOf(":");
+        out.push(`event: run\ndata: ${JSON.stringify({ source: k.slice(0, i), run: k.slice(i + 1) })}\n\n`);
+      }
+      seen = now;
+      return out;
+    };
+    return sse(c.req.raw.signal, "retry: 3000\n: connected\n\n", tick);
+  });
+}

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

@@ -0,0 +1,66 @@
+// Receipt verify and public key (CPE-16). Calls the engine's own verifyReceipt in process (loki-ts verify_cmd.ts), never reimplements the crypto.
+// Read-only: it reads <repo>/.loki/runs/<run>/receipt.json (and events.jsonl beside it) and writes nothing. Loopback-only (on `act`), same path containment as the artifacts route.
+import { readFileSync, realpathSync } from "node:fs";
+import { createPublicKey } from "node:crypto";
+import { join, sep } from "node:path";
+import { and, eq } from "drizzle-orm";
+import { localRepos, runs } from "../../db/schema.ts";
+import { verifyReceipt } from "../../../../../loki-ts/src/engine10/verify_cmd.ts";
+import { kidOf, loadSigningKey } from "../../../../../loki-ts/src/engine10/stages/seal.ts";
+import { outcomeOf, runIdGuard } from "../../../../../loki-ts/src/features/receipt_dsse.ts";
+import { audit } from "../audit.ts";
+import type { RouteCtx } from "./index.ts";
+
+const ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const safeId = (s: string) => ID.test(s) && !s.includes("..");
+
+export function mount(ctx: RouteCtx): void {
+  const { act, db } = ctx;
+
+  act.post("/v1/runs/:source/:run/verify", async (c) => {
+    const source = c.req.param("source"), run = c.req.param("run");
+    const target = `${source}/${run}`;
+    const done = (status: 403 | 404, error: string, result: string) => { audit(db, { kind: "receipt.verify", target, result, detail: error }); return c.json({ error }, status); };
+    if (!ctx.local(c)) return done(403, "loopback only", "refused");
+    if (!safeId(source) || !safeId(run)) return done(404, "run not found", "not_found");
+    const known = db.select({ r: runs.runId }).from(runs).where(and(eq(runs.sourceId, source), eq(runs.runId, run))).get();
+    if (!known) return done(404, "run not found", "not_found");
+    const repo = db.select({ p: localRepos.realpath }).from(localRepos).where(eq(localRepos.sourceId, source)).get();
+    if (!repo) return done(404, "receipt not available", "not_found");
+    let runDir: string, file: string;
+    try {
+      const root = realpathSync(join(repo.p, ".loki", "runs"));
+      runDir = realpathSync(join(root, run));
+      if (runDir !== join(root, run)) return done(404, "receipt not found", "not_found");
+      file = realpathSync(join(runDir, "receipt.json"));
+    } catch { return done(404, "receipt not found", "not_found"); }
+    if (!file.startsWith(runDir + sep)) return done(404, "receipt not found", "not_found");
+    // Same order as `loki verify <run-id>`: the envelope must describe this run, then integrity, then the run outcome.
+    let integrity: string, reasons: string[], sha: string | null = null, outcome = "UNREADABLE";
+    try {
+      const bad = runIdGuard(file, run);
+      if (bad) { integrity = "TAMPERED"; reasons = [bad]; }
+      else { const r = await verifyReceipt(file); integrity = r.verdict; reasons = r.reasons; sha = r.receiptSha256 ?? null; }
+      try { outcome = outcomeOf(JSON.parse(readFileSync(file, "utf8"))); } catch { outcome = "UNREADABLE"; }
+    } catch (e) {
+      integrity = "UNCHECKED"; reasons = [`verifier error: ${(e as Error).message}`];
+    }
+    // Intact does not mean passing: an intact receipt of a run that did not verify is NOT_VERIFIED, as in the CLI (exit 4).
+    const intact = integrity === "VERIFIED" || integrity === "UNSIGNED";
+    const passing = outcome === "VERIFIED" || outcome === "ALREADY_SATISFIED";
+    let verdict = integrity;
+    if (intact && !passing) { verdict = "NOT_VERIFIED"; reasons = [`run outcome ${outcome}; receipt integrity ${integrity === "UNSIGNED" ? "unattested" : "intact"}`, ...reasons]; }
+    audit(db, { kind: "receipt.verify", target, result: verdict.toLowerCase(), detail: reasons[0] });
+    return c.json({ run, verdict, integrity, outcome, reasons, receipt_sha256: sha, verified_at: new Date().toISOString() });
+  });
+
+  // The public half of the receipt signer as a JWK. The private key never leaves loadSigningKey.
+  act.get("/v1/keys", (c) => {
+    if (!ctx.peerIsLoopback(c)) { audit(db, { kind: "keys.read", result: "refused", detail: "loopback only" }); return c.json({ error: "loopback only" }, 403); }
+    const priv = loadSigningKey(false);
+    if (!priv) { audit(db, { kind: "keys.read", result: "no_key" }); return c.json({ error: "no signing key on this machine (run a sealed build first or set LOKI_RECEIPT_SIGNING_KEY_FILE)" }, 404); }
+    const pub = createPublicKey(priv), { kty, crv, x } = pub.export({ format: "jwk" });
+    audit(db, { kind: "keys.read", result: "ok" });
+    return c.json({ kty, crv, x, kid: kidOf(pub), alg: "EdDSA", use: "sig" });
+  });
+}

package/packages/control-plane/src/server/spawn.ts

@@ -0,0 +1,79 @@
+// Start-a-run planning and spawning for the UI (CPE-07). A run is started by spawning the same `loki start` path an operator would type (argv array, no shell).
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, join, resolve } from "node:path";
+
+const ISSUE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}\/[A-Za-z0-9._-]{1,100}#[1-9][0-9]{0,8}$/;
+// A free-text task: letters, digits, spaces and a small punctuation set. No colon, quotes, backticks, $, ;, &, |, <, >, parens, braces, backslash or control chars.
+const TASK = /^[A-Za-z0-9][A-Za-z0-9 .,_/#@+=-]{0,499}$/;
+const hasDotDot = (t: string): boolean => t.split(/[\\/ ]/).some((seg) => seg.startsWith(".."));
+
+/** Child env: the server's own secrets and bind config never reach a spawned run. */
+export function childEnv(env: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
+  const e: NodeJS.ProcessEnv = { ...env, LOKI_NO_BROWSER: "1" };
+  for (const k of ["LOKI_CONTROL_TOKEN", "LOKI_CONTROL_DB", "LOKI_CONTROL_HOST", "PORT"]) delete e[k];
+  return e;
+}
+
+// Optional run fields, each mapped to one known loki flag (or env var) and validated against an allowlist. Nothing else is accepted.
+const PROVIDERS = new Set(["claude", "codex", "cline", "aider", "opencode"]);
+const MODEL = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+const BUDGET = /^(?:[1-9][0-9]{0,5}|0)(?:\.[0-9]{1,2})?$/;
+const WORKSPACE = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
+
+export type StartPlan = { ok: true; argv: string[]; cwd: string; env: Record<string, string> } | { ok: false; error: string };
+
+/** Registered project paths from ~/.loki/dashboard/projects.json (the `loki projects` registry), existing directories only. */
+export function registryRepos(env: NodeJS.ProcessEnv = process.env): string[] {
+  try {
+    const j = JSON.parse(readFileSync(join(env.HOME || homedir(), ".loki", "dashboard", "projects.json"), "utf8")) as { projects?: Record<string, { path?: unknown }> };
+    return Object.values(j.projects ?? {}).map((p) => (typeof p?.path === "string" ? p.path : "")).filter((p) => p && existsSync(p) && statSync(p).isDirectory());
+  } catch { return []; }
+}
+
+/** Validate a start request. The repo must be one the server already knows (registry or cwd), never an arbitrary path. */
+export function planStart(body: unknown, known: string[], bin = "loki"): StartPlan {
+  const b = (body && typeof body === "object" ? body : {}) as { target?: unknown; repo?: unknown; model?: unknown; provider?: unknown; budget?: unknown; workspace?: unknown };
+  if (typeof b.target !== "string") return { ok: false, error: "target must be a string" };
+  const target = b.target.trim();
+  const issue = ISSUE.test(target);
+  if (!issue && !TASK.test(target)) return { ok: false, error: "target must be owner/repo#N or a plain task (letters, digits, spaces, . , _ / # @ + = -)" };
+  if (hasDotDot(target)) return { ok: false, error: "target must not contain a .. path segment" };
+  let cwd = process.cwd();
+  if (b.repo !== undefined && b.repo !== "") {
+    if (typeof b.repo !== "string" || b.repo.includes("\0")) return { ok: false, error: "repo must be a path string" };
+    // GET /v1/repos exposes display names only, so a repo may be given as a known path or as the unique display name of a known project.
+    const want = resolve(b.repo);
+    const paths = known.map((k) => resolve(k));
+    const named = paths.filter((k) => basename(k) === b.repo);
+    const hit = paths.find((k) => k === want) ?? (named.length === 1 ? named[0] : undefined);
+    if (!hit) return { ok: false, error: named.length > 1 ? "repo name is ambiguous" : "repo is not a known project" };
+    cwd = hit;
+  }
+  const opt = (v: unknown): string | undefined => (v === undefined || v === null || v === "" ? undefined : typeof v === "number" && Number.isFinite(v) ? String(v) : typeof v === "string" ? v : "\0bad");
+  const provider = opt(b.provider), model = opt(b.model), budget = opt(b.budget), workspace = opt(b.workspace);
+  if (provider !== undefined && !PROVIDERS.has(provider)) return { ok: false, error: "provider must be one of: " + [...PROVIDERS].join(", ") };
+  if (model !== undefined && !MODEL.test(model)) return { ok: false, error: "model must match [A-Za-z0-9][A-Za-z0-9._-]{0,63}" };
+  if (budget !== undefined && (!BUDGET.test(budget) || Number(budget) <= 0)) return { ok: false, error: "budget must be a positive USD amount such as 5 or 5.00" };
+  if (workspace !== undefined && !WORKSPACE.test(workspace)) return { ok: false, error: "workspace must be a workspace name from loki.yaml (letters, digits, _ -)" };
+  if (workspace !== undefined && (provider !== undefined || budget !== undefined)) return { ok: false, error: "workspace runs do not take provider or budget; set them per repo in loki.yaml" };
+  const env: Record<string, string> = model !== undefined ? { LOKI_SESSION_MODEL: model } : {};
+  // A workspace run is `loki workspace run <name> <ref>` (the existing multi-repo path). Otherwise free text goes as an explicit brief, never auto-detected as a PRD path.
+  if (workspace !== undefined) return { ok: true, argv: [bin, "workspace", "run", workspace, target], cwd, env };
+  const flags = [...(provider !== undefined ? ["--provider", provider] : []), ...(budget !== undefined ? ["--budget", budget] : [])];
+  return { ok: true, argv: issue ? [bin, "start", target, ...flags] : [bin, "start", "--brief", target, ...flags], cwd, env };
+}
+
+/** Spawn detached with no shell; resolves with the pid once the process exists, or an error if it cannot be launched. */
+export function spawnStart(argv: string[], cwd: string, onExit: () => void = () => {}, extraEnv: Record<string, string> = {}): Promise<{ pid: number } | { error: string }> {
+  return new Promise((done) => {
+    try {
+      const [cmd, ...args] = argv;
+      const child = spawn(cmd!, args, { cwd, detached: true, stdio: "ignore", shell: false, env: { ...childEnv(), ...extraEnv } });
+      child.once("exit", onExit);
+      child.once("error", (e) => { onExit(); done({ error: `could not start loki: ${e.message}` }); });
+      child.once("spawn", () => { child.unref(); done({ pid: child.pid ?? 0 }); });
+    } catch (e) { done({ error: `could not start loki: ${(e as Error).message}` }); }
+  });
+}