loki-mode 10.6.7 → 10.6.8

package/mcp/__init__.py

@@ -75,4 +75,4 @@ try:
 except ImportError:
     __all__ = ['mcp']
 
-__version__ = '10.6.7'
+__version__ = '10.6.8'

package/mcp/server.py

@@ -1368,6 +1368,82 @@ async def get_pending_tasks() -> str:
 # ENTERPRISE TOOLS (P0-1)
 # ============================================================
 
+@mcp.tool()
+async def loki_v10_run(ref: str, repo_path: str) -> str:
+    """
+    Start a Loki 10 run in the background (same engine as `loki <ref>`).
+
+    Args:
+        ref: Task text or issue reference (owner/repo#N or issue URL)
+        repo_path: Repository directory (must be inside the project root)
+
+    Returns:
+        JSON with run_id (null if not yet created), pid and log_path. Never blocks.
+    """
+    _emit_tool_event_async('loki_v10_run', 'start', parameters={'repo_path': repo_path})
+    try:
+        from mcp import v10_tools
+        result = await asyncio.to_thread(
+            v10_tools.v10_run, ref, repo_path, lambda p: validate_path(p, allowed_dirs=['.']))
+        _emit_tool_event_async('loki_v10_run', 'complete', result_status='error' if isinstance(result, dict) and result.get('error') else 'success')
+        return json.dumps(result)
+    except Exception as e:
+        logger.error(f"loki_v10_run failed: {e}")
+        _emit_tool_event_async('loki_v10_run', 'complete', result_status='error', error=str(e))
+        return json.dumps({"error": str(e)})
+
+
+@mcp.tool()
+async def loki_v10_status(repo_path: str, run_id: str = "") -> str:
+    """
+    Read the state of a Loki 10 run from its events log.
+
+    Args:
+        repo_path: Repository directory containing .loki/runs
+        run_id: Run id (e10-...); defaults to the newest run
+
+    Returns:
+        JSON with phase, done, verdict (once done) and cost_usd (null if unmeasured)
+    """
+    _emit_tool_event_async('loki_v10_status', 'start', parameters={'repo_path': repo_path, 'run_id': run_id})
+    try:
+        from mcp import v10_tools
+        result = v10_tools.v10_status(
+            run_id, repo_path, lambda p: validate_path(p, allowed_dirs=['.']))
+        _emit_tool_event_async('loki_v10_status', 'complete', result_status='error' if isinstance(result, dict) and result.get('error') else 'success')
+        return json.dumps(result)
+    except Exception as e:
+        logger.error(f"loki_v10_status failed: {e}")
+        _emit_tool_event_async('loki_v10_status', 'complete', result_status='error', error=str(e))
+        return json.dumps({"error": str(e)})
+
+
+@mcp.tool()
+async def loki_v10_verify(receipt_path: str = "", repo_path: str = "") -> str:
+    """
+    Run `loki verify` on a receipt (or the newest run of a repo).
+
+    Args:
+        receipt_path: Path to a receipt.json (takes priority)
+        repo_path: Repository directory; verifies its newest run
+
+    Returns:
+        JSON with exit_code, verified and an output summary
+    """
+    _emit_tool_event_async('loki_v10_verify', 'start', parameters={'receipt_path': receipt_path, 'repo_path': repo_path})
+    try:
+        from mcp import v10_tools
+        result = await asyncio.to_thread(
+            v10_tools.v10_verify, receipt_path, repo_path,
+            lambda p: validate_path(p, allowed_dirs=['.']))
+        _emit_tool_event_async('loki_v10_verify', 'complete', result_status='error' if isinstance(result, dict) and result.get('error') else 'success')
+        return json.dumps(result)
+    except Exception as e:
+        logger.error(f"loki_v10_verify failed: {e}")
+        _emit_tool_event_async('loki_v10_verify', 'complete', result_status='error', error=str(e))
+        return json.dumps({"error": str(e)})
+
+
 @mcp.tool()
 async def loki_start_project(prd_content: str = "", prd_path: str = "") -> str:
     """

package/mcp/tests/test_v10_tools.py

@@ -0,0 +1,137 @@
+"""Unit tests for mcp/v10_tools.py with subprocess mocked."""
+
+import json
+import os
+import subprocess
+import sys
+import tempfile
+import unittest
+from unittest import mock
+
+_REPO_ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), '..', '..'))
+if _REPO_ROOT not in sys.path:
+    sys.path.insert(0, _REPO_ROOT)
+
+from mcp import v10_tools  # noqa: E402
+
+
+def _ok(p):
+    return os.path.realpath(p)
+
+
+def _deny(p):
+    raise PermissionError("Access denied: " + p)
+
+
+def _write_events(repo, run_id, events):
+    d = os.path.join(repo, ".loki", "runs", run_id)
+    os.makedirs(d)
+    with open(os.path.join(d, "events.jsonl"), "w") as f:
+        for e in events:
+            f.write(json.dumps(e) + "\n")
+
+
+class RunTests(unittest.TestCase):
+    def test_rejects_flag_like_ref(self):
+        with mock.patch("subprocess.Popen") as popen:
+            r = v10_tools.v10_run("--help", "/x", _ok)
+        self.assertIn("error", r)
+        popen.assert_not_called()
+
+    def test_path_validation_failure(self):
+        with mock.patch("subprocess.Popen") as popen:
+            r = v10_tools.v10_run("fix the bug", "/etc", _deny)
+        self.assertIn("Access denied", r["error"])
+        popen.assert_not_called()
+
+    def test_starts_in_background_with_arg_list(self):
+        with tempfile.TemporaryDirectory() as repo, \
+                mock.patch.object(v10_tools, "V10_RUN_ID_WAIT_S", 0), \
+                mock.patch("subprocess.Popen") as popen:
+            popen.return_value.pid = 4242
+            r = v10_tools.v10_run("fix the bug", repo, _ok)
+            args, kwargs = popen.call_args
+            self.assertEqual(args[0][1], "fix the bug")
+            self.assertIsInstance(args[0], list)
+            self.assertNotIn("shell", kwargs)
+            self.assertTrue(kwargs["start_new_session"])
+            self.assertEqual(kwargs["env"]["LOKI_ENGINE"], "v10")
+            self.assertEqual(r["pid"], 4242)
+            self.assertIsNone(r["run_id"])
+            self.assertTrue(r["log_path"].startswith(os.path.realpath(repo)))
+
+
+class StatusTests(unittest.TestCase):
+    def test_done_run(self):
+        ev = [
+            {"seq": 0, "type": "run.started", "stage": None, "data": {}},
+            {"seq": 1, "type": "stage.started", "stage": "plan", "data": {}},
+            {"seq": 2, "type": "cost", "stage": "plan", "data": {"usd": 0.5}},
+            {"seq": 3, "type": "stage.completed", "stage": "plan", "data": {}},
+            {"seq": 4, "type": "run.completed", "stage": None, "data": {"verdict": "VERIFIED"}},
+        ]
+        with tempfile.TemporaryDirectory() as repo:
+            _write_events(repo, "e10-a", ev)
+            r = v10_tools.v10_status("", repo, _ok)
+        self.assertEqual(r["run_id"], "e10-a")
+        self.assertTrue(r["done"])
+        self.assertEqual(r["verdict"], "VERIFIED")
+        self.assertEqual(r["phase"], "done")
+        self.assertAlmostEqual(r["cost_usd"], 0.5)
+
+    def test_running_and_unmeasured_cost(self):
+        ev = [
+            {"seq": 0, "type": "stage.started", "stage": "build", "data": {}},
+            {"seq": 1, "type": "cost", "stage": "build", "data": {}},
+        ]
+        with tempfile.TemporaryDirectory() as repo:
+            _write_events(repo, "e10-b", ev)
+            r = v10_tools.v10_status("e10-b", repo, _ok)
+        self.assertFalse(r["done"])
+        self.assertEqual(r["phase"], "build")
+        self.assertIsNone(r["cost_usd"])
+        self.assertIsNone(r["verdict"])
+
+    def test_bad_run_id_and_missing(self):
+        with tempfile.TemporaryDirectory() as repo:
+            self.assertIn("error", v10_tools.v10_status("../x", repo, _ok))
+            self.assertIn("error", v10_tools.v10_status("", repo, _ok))
+            self.assertIn("error", v10_tools.v10_status("", "", _ok))
+
+
+class VerifyTests(unittest.TestCase):
+    def test_receipt_path_runs_verify(self):
+        with tempfile.TemporaryDirectory() as repo:
+            receipt = os.path.join(repo, "receipt.json")
+            open(receipt, "w").write("{}")
+            cp = subprocess.CompletedProcess([], 0, stdout="VERIFIED\n", stderr="")
+            with mock.patch("subprocess.run", return_value=cp) as run:
+                r = v10_tools.v10_verify(receipt, "", _ok)
+            args, kwargs = run.call_args
+            self.assertEqual(args[0][1:], ["verify", os.path.realpath(receipt)])
+            self.assertEqual(kwargs["timeout"], v10_tools.V10_VERIFY_TIMEOUT_S)
+            self.assertNotIn("shell", kwargs)
+        self.assertEqual(r["exit_code"], 0)
+        self.assertTrue(r["verified"])
+        self.assertIn("VERIFIED", r["output"])
+
+    def test_repo_path_nonzero_exit(self):
+        with tempfile.TemporaryDirectory() as repo:
+            cp = subprocess.CompletedProcess([], 1, stdout="", stderr="hash mismatch")
+            with mock.patch("subprocess.run", return_value=cp):
+                r = v10_tools.v10_verify("", repo, _ok)
+        self.assertEqual(r["exit_code"], 1)
+        self.assertFalse(r["verified"])
+
+    def test_timeout_and_validation(self):
+        with tempfile.TemporaryDirectory() as repo:
+            with mock.patch("subprocess.run", side_effect=subprocess.TimeoutExpired("loki", 1)):
+                self.assertIn("timed out", v10_tools.v10_verify("", repo, _ok)["error"])
+        with mock.patch("subprocess.run") as run:
+            self.assertIn("error", v10_tools.v10_verify("/etc/passwd", "", _deny))
+            self.assertIn("error", v10_tools.v10_verify("", "", _ok))
+            run.assert_not_called()
+
+
+if __name__ == "__main__":
+    unittest.main()

package/mcp/v10_tools.py

@@ -0,0 +1,172 @@
+"""Loki 10 MCP tool helpers: start a v10 run, read its status, verify a receipt.
+
+Plain functions returning dicts so they are testable without the MCP SDK; the
+thin @mcp.tool wrappers live in mcp/server.py. Subprocesses use argument lists
+only (never a shell), and every path is checked by the caller-supplied
+validator before use.
+"""
+
+import json
+import os
+import subprocess
+import time
+from pathlib import Path
+from typing import Callable, Dict, List, Optional
+
+LOKI_BIN = str(Path(__file__).resolve().parent.parent / "bin" / "loki")
+RUNS_REL = os.path.join(".loki", "runs")
+V10_RUN_ID_WAIT_S = 2.0
+V10_VERIFY_TIMEOUT_S = 120
+_TERMINAL = {"stage.completed", "stage.failed", "stage.skipped"}
+
+
+def _env() -> Dict[str, str]:
+    env = dict(os.environ)
+    env["LOKI_ENGINE"] = "v10"
+    env["LOKI_NO_BROWSER"] = env.get("LOKI_NO_BROWSER", "1")
+    return env
+
+
+def _run_ids(repo: str) -> List[str]:
+    d = os.path.join(repo, RUNS_REL)
+    if not os.path.isdir(d):
+        return []
+    return sorted(n for n in os.listdir(d) if os.path.isdir(os.path.join(d, n)))
+
+
+def v10_run(ref: str, repo_path: str, validate: Callable[[str], str]) -> dict:
+    if not isinstance(ref, str) or not ref.strip() or ref.startswith("-") or "\x00" in ref:
+        return {"error": "invalid ref: must be a non-empty task or issue reference that does not start with '-'"}
+    try:
+        repo = validate(repo_path)
+    except Exception as e:  # PathTraversalError from the server validator
+        return {"error": str(e)}
+    if not os.path.isdir(repo):
+        return {"error": f"repo_path is not a directory: {repo_path}"}
+    before = set(_run_ids(repo))
+    log_dir = os.path.join(repo, ".loki")
+    os.makedirs(log_dir, exist_ok=True)
+    log_path = os.path.join(log_dir, f"v10-mcp-{int(time.time() * 1000)}.log")
+    try:
+        with open(log_path, "ab") as log:
+            proc = subprocess.Popen(
+                [LOKI_BIN, ref],
+                cwd=repo,
+                env=_env(),
+                stdin=subprocess.DEVNULL,
+                stdout=log,
+                stderr=log,
+                start_new_session=True,
+            )
+    except OSError as e:
+        return {"error": f"could not start loki: {e}"}
+    run_id: Optional[str] = None
+    deadline = time.time() + V10_RUN_ID_WAIT_S
+    while True:
+        new = [r for r in _run_ids(repo) if r not in before]
+        if new:
+            run_id = new[-1]
+            break
+        if time.time() >= deadline:
+            break
+        time.sleep(0.1)
+    return {"run_id": run_id, "pid": proc.pid, "log_path": log_path}
+
+
+def _read_events(path: str) -> List[dict]:
+    events = []
+    with open(path, "r", encoding="utf-8") as f:
+        for line in f:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                e = json.loads(line)
+            except ValueError:
+                continue
+            if isinstance(e, dict):
+                events.append(e)
+    return events
+
+
+def v10_status(run_id: str, repo_path: str, validate: Callable[[str], str]) -> dict:
+    if not repo_path:
+        return {"error": "repo_path is required"}
+    try:
+        repo = validate(repo_path)
+    except Exception as e:
+        return {"error": str(e)}
+    if run_id:
+        if "/" in run_id or "\\" in run_id or run_id.startswith(".") or "\x00" in run_id:
+            return {"error": "invalid run_id"}
+    else:
+        ids = _run_ids(repo)
+        if not ids:
+            return {"error": "no v10 runs found under .loki/runs"}
+        run_id = ids[-1]
+    events_path = os.path.join(repo, RUNS_REL, run_id, "events.jsonl")
+    if not os.path.isfile(events_path):
+        return {"error": f"no events.jsonl for run {run_id}"}
+    events = _read_events(events_path)
+    open_stages: Dict[str, bool] = {}
+    verdict = None
+    done = False
+    usd = 0.0
+    saw_cost = False
+    unmeasured = False
+    for e in events:
+        t, stage = e.get("type"), e.get("stage")
+        data = e.get("data") if isinstance(e.get("data"), dict) else {}
+        if stage:
+            if t == "stage.started":
+                open_stages[stage] = True
+            elif t in _TERMINAL:
+                open_stages.pop(stage, None)
+        if t == "run.completed":
+            done = True
+            verdict = data.get("verdict") if isinstance(data.get("verdict"), str) else None
+        elif t == "cost":
+            saw_cost = True
+            if isinstance(data.get("usd"), (int, float)):
+                usd += data["usd"]
+            else:
+                unmeasured = True
+    phase = "done" if done else ("+".join(sorted(open_stages)) or "starting")
+    return {
+        "run_id": run_id,
+        "phase": phase,
+        "done": done,
+        "verdict": verdict,
+        "cost_usd": usd if saw_cost and not unmeasured else None,
+        "events": len(events),
+    }
+
+
+def v10_verify(receipt_path: str, repo_path: str, validate: Callable[[str], str]) -> dict:
+    args = [LOKI_BIN, "verify"]
+    try:
+        if receipt_path:
+            receipt = validate(receipt_path)
+            if not os.path.isfile(receipt):
+                return {"error": f"receipt not found: {receipt_path}"}
+            args.append(receipt)
+            cwd = os.path.dirname(receipt)
+        elif repo_path:
+            cwd = validate(repo_path)
+            if not os.path.isdir(cwd):
+                return {"error": f"repo_path is not a directory: {repo_path}"}
+        else:
+            return {"error": "receipt_path or repo_path is required"}
+    except Exception as e:
+        return {"error": str(e)}
+    try:
+        p = subprocess.run(
+            args, cwd=cwd, env=_env(), stdin=subprocess.DEVNULL,
+            capture_output=True, text=True, timeout=V10_VERIFY_TIMEOUT_S,
+        )
+    except subprocess.TimeoutExpired:
+        return {"error": f"loki verify timed out after {V10_VERIFY_TIMEOUT_S}s"}
+    except OSError as e:
+        return {"error": f"could not run loki verify: {e}"}
+    out = ((p.stdout or "") + (p.stderr or "")).strip()
+    return {"exit_code": p.returncode, "verified": p.returncode == 0, "output": out[-2000:]}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "loki-mode",
   "mcpName": "io.github.asklokesh/loki-mode",
-  "version": "10.6.7",
+  "version": "10.6.8",
   "description": "An autonomous software factory that knows what it is supposed to deliver, and proves it did.",
   "keywords": [
     "agent",

package/packages/control-plane/dist/server.js

@@ -16,7 +16,7 @@ var __export = (target, all) => {
 
 // src/server/app.ts
 import { existsSync as existsSync2, statSync } from "fs";
-import { join as join2, resolve, sep } from "path";
+import { join as join3, resolve, sep } from "path";
 
 // node_modules/hono/dist/request/constants.js
 var GET_MATCH_RESULT = Symbol();
@@ -5658,6 +5658,35 @@ var RULES = [
 ];
 var redactSecrets = (s) => RULES.reduce((a, [re, to]) => a.replace(re, to), s);
 
+// src/server/answer.ts
+import { chmodSync, mkdirSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { join as join2 } from "path";
+var MAX_ANSWER = 4000;
+var ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+var defaultAnswerDir = (env = process.env) => env.LOKI_CONTROL_ANSWER_DIR || join2(env.HOME || homedir(), ".loki", "control", "answers");
+function blockedQuestion(evs, verdict) {
+  if (verdict !== "SPEC_CONFLICT")
+    return null;
+  const why = evs.find((e) => e.type === "stage.completed" && e.stage === "implement")?.data.spec_conflict_reason;
+  return (typeof why === "string" && why ? why : "the run is blocked on a spec conflict").replace(/[\x00-\x1f\x7f]+/g, " ").slice(0, 500);
+}
+function writeAnswer(dir, source, run, answer) {
+  if (!ID.test(source) || !ID.test(run) || source.includes("..") || run.includes(".."))
+    return { status: 400, body: { error: "invalid run id" } };
+  if (typeof answer !== "string" || answer.trim() === "")
+    return { status: 400, body: { error: "answer must be a non-empty string" } };
+  if (answer.length > MAX_ANSWER)
+    return { status: 413, body: { error: `answer over ${MAX_ANSWER} characters` } };
+  const d = join2(dir, source);
+  mkdirSync(d, { recursive: true, mode: 448 });
+  const path = join2(d, `${run}.answer.txt`);
+  writeFileSync(path, `${answer.trim()}
+`, { mode: 384 });
+  chmodSync(path, 384);
+  return { status: 200, body: { ok: true, path, resume: `loki "$(cat '${path}')"  # re-run the task with the answer, or paste it into the issue` } };
+}
+
 // src/server/runs.ts
 var str = (x) => typeof x === "string" ? x : null;
 function loadEvents(db, sourceId, runId) {
@@ -5792,6 +5821,7 @@ function runDetail(db, sourceId, runId) {
   const sealed = evs.find((e) => e.type === "receipt.sealed")?.data;
   return {
     ...withLive(db, r),
+    blocked_question: blockedQuestion(evs, r.verdict),
     stages,
     stages_completed: f.completed,
     receipt: sealed ? { sha256: str(sealed.receipt_sha256), signed: sealed.signed === true, verdict: str(sealed.verdict), path: str(sealed.path) } : null,
@@ -5848,11 +5878,12 @@ function ingest(db, body) {
 
 // src/server/app.ts
 var MAX_BODY = 1e6;
-var defaultUiDir = () => [join2(import.meta.dir, "../../ui/dist"), join2(import.meta.dir, "../ui/dist")].find((d) => existsSync2(join2(d, "index.html")));
+var defaultUiDir = () => [join3(import.meta.dir, "../../ui/dist"), join3(import.meta.dir, "../ui/dist")].find((d) => existsSync2(join3(d, "index.html")));
 function createApp(opts) {
   const uiDir = opts.uiDir ?? defaultUiDir();
   const { db, sqlite } = openDb(opts.dbPath);
   let ready = true;
+  const answerDir = opts.answerDir ?? defaultAnswerDir();
   const app = new Hono3;
   app.get("/health", (c) => c.json({ service: "loki-control", pid: process.pid, install_path: import.meta.dir }));
   app.get("/ready", (c) => {
@@ -5885,6 +5916,27 @@ function createApp(opts) {
     return d ? c.json(d) : c.json({ error: "run not found" }, 404);
   };
   app.get("/v1/runs/:source/:run", (c) => detail(c, c.req.param("source"), c.req.param("run")));
+  app.post("/v1/runs/:source/:run/answer", async (c) => {
+    const source = c.req.param("source"), run = c.req.param("run");
+    if (!(c.req.header("content-type") ?? "").toLowerCase().startsWith("application/json"))
+      return c.json({ error: "content-type must be application/json" }, 400);
+    const text2 = await c.req.text();
+    if (text2.length > 20000)
+      return c.json({ error: "body too large" }, 413);
+    let body;
+    try {
+      body = JSON.parse(text2);
+    } catch {
+      return c.json({ error: "invalid JSON" }, 400);
+    }
+    const d = runDetail(db, source, run);
+    if (!d)
+      return c.json({ error: "run not found" }, 404);
+    if (!d.blocked_question)
+      return c.json({ error: "run is not blocked on a question" }, 409);
+    const r = writeAnswer(answerDir, source, run, body?.answer);
+    return c.json(r.body, r.status);
+  });
   app.get("/v1/runs/:id", (c) => {
     const id = c.req.param("id");
     const i = id.indexOf(":");
@@ -5900,14 +5952,14 @@ function createApp(opts) {
       return new Response(Bun.file(f));
     if (/\.[a-z0-9]+$/i.test(p))
       return c.json({ error: "not found" }, 404);
-    return new Response(Bun.file(join2(root, "index.html")));
+    return new Response(Bun.file(join3(root, "index.html")));
   });
   return { app, db, close: () => sqlite.close() };
 }
 
 // src/server/serve.ts
 var { app } = createApp({ dbPath: process.env.LOKI_CONTROL_DB ?? "control.db" });
-var serve = (port) => Bun.serve({ port, hostname: "127.0.0.1", fetch: app.fetch });
+var serve = (port) => Bun.serve({ port, hostname: process.env.LOKI_CONTROL_HOST || "127.0.0.1", fetch: app.fetch });
 var s;
 try {
   s = serve(Number(process.env.PORT ?? 0));

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

@@ -0,0 +1,33 @@
+// BLOCKED answer: a human reply to a run's one question, written to a file the operator resumes from.
+// File: <answerDir>/<source>/<run>.answer.txt (default ~/.loki/control/answers, override LOKI_CONTROL_ANSWER_DIR).
+import { chmodSync, mkdirSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { EventEnvelope } from "../../../../loki-ts/src/engine10/types.ts";
+
+export const MAX_ANSWER = 4000;
+const ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+
+export const defaultAnswerDir = (env: NodeJS.ProcessEnv = process.env): string =>
+  env.LOKI_CONTROL_ANSWER_DIR || join(env.HOME || homedir(), ".loki", "control", "answers");
+
+/** The question a BLOCKED (spec conflict) run is waiting on, or null when it is not blocked. */
+export function blockedQuestion(evs: EventEnvelope[], verdict: string | null): string | null {
+  if (verdict !== "SPEC_CONFLICT") return null;
+  const why = evs.find((e) => e.type === "stage.completed" && e.stage === "implement")?.data.spec_conflict_reason;
+  return (typeof why === "string" && why ? why : "the run is blocked on a spec conflict").replace(/[\x00-\x1f\x7f]+/g, " ").slice(0, 500);
+}
+
+export type AnswerResult = { status: 200; body: { ok: true; path: string; resume: string } } | { status: 400 | 413; body: { error: string } };
+
+export function writeAnswer(dir: string, source: string, run: string, answer: unknown): AnswerResult {
+  if (!ID.test(source) || !ID.test(run) || source.includes("..") || run.includes("..")) return { status: 400, body: { error: "invalid run id" } };
+  if (typeof answer !== "string" || answer.trim() === "") return { status: 400, body: { error: "answer must be a non-empty string" } };
+  if (answer.length > MAX_ANSWER) return { status: 413, body: { error: `answer over ${MAX_ANSWER} characters` } };
+  const d = join(dir, source);
+  mkdirSync(d, { recursive: true, mode: 0o700 });
+  const path = join(d, `${run}.answer.txt`);
+  writeFileSync(path, `${answer.trim()}\n`, { mode: 0o600 });
+  chmodSync(path, 0o600);
+  return { status: 200, body: { ok: true, path, resume: `loki "$(cat '${path}')"  # re-run the task with the answer, or paste it into the issue` } };
+}

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

@@ -3,6 +3,7 @@ import { join, resolve, sep } from "node:path";
 import { Hono } from "hono";
 import { openDb } from "../db/migrate.ts";
 import { ingest } from "./ingest.ts";
+import { defaultAnswerDir, writeAnswer } from "./answer.ts";
 import { listRuns, runDetail } from "./runs.ts";
 
 const MAX_BODY = 1_000_000;
@@ -11,10 +12,11 @@ const MAX_BODY = 1_000_000;
 const defaultUiDir = () => [join(import.meta.dir, "../../ui/dist"), join(import.meta.dir, "../ui/dist")].find((d) => existsSync(join(d, "index.html")));
 
 /** dbPath ":memory:" for tests. Migrations run here, so /ready is true as soon as this returns. uiDir overrides the built-UI location. */
-export function createApp(opts: { dbPath: string; uiDir?: string }) {
+export function createApp(opts: { dbPath: string; uiDir?: string; answerDir?: string }) {
   const uiDir = opts.uiDir ?? defaultUiDir();
   const { db, sqlite } = openDb(opts.dbPath);
   let ready = true;
+  const answerDir = opts.answerDir ?? defaultAnswerDir();
   const app = new Hono();
 
   app.get("/health", (c) => c.json({ service: "loki-control", pid: process.pid, install_path: import.meta.dir }));
@@ -41,6 +43,20 @@ export function createApp(opts: { dbPath: string; uiDir?: string }) {
     return d ? c.json(d) : c.json({ error: "run not found" }, 404);
   };
   app.get("/v1/runs/:source/:run", (c) => detail(c, c.req.param("source"), c.req.param("run")));
+  // BLOCKED answer: only for a run blocked on a question; JSON content type required (blocks cross-site form posts).
+  app.post("/v1/runs/:source/:run/answer", async (c) => {
+    const source = c.req.param("source"), run = c.req.param("run");
+    if (!(c.req.header("content-type") ?? "").toLowerCase().startsWith("application/json")) return c.json({ error: "content-type must be application/json" }, 400);
+    const text = await c.req.text();
+    if (text.length > 20_000) return c.json({ error: "body too large" }, 413);
+    let body: { answer?: unknown } | null;
+    try { body = JSON.parse(text) as { answer?: unknown } | null; } catch { return c.json({ error: "invalid JSON" }, 400); }
+    const d = runDetail(db, source, run);
+    if (!d) return c.json({ error: "run not found" }, 404);
+    if (!d.blocked_question) return c.json({ error: "run is not blocked on a question" }, 409);
+    const r = writeAnswer(answerDir, source, run, body?.answer);
+    return c.json(r.body, r.status);
+  });
   // :id is `source:run` (run ids never contain a colon)
   app.get("/v1/runs/:id", (c) => {
     const id = c.req.param("id");

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

@@ -3,6 +3,7 @@ import { fold, partialCost } from "../../../../loki-ts/src/engine10/events.ts";
 import type { EventEnvelope } from "../../../../loki-ts/src/engine10/types.ts";
 import type { Db } from "../db/migrate.ts";
 import { events, runs } from "../db/schema.ts";
+import { blockedQuestion } from "./answer.ts";
 
 const str = (x: unknown): string | null => (typeof x === "string" ? x : null);
 
@@ -108,6 +109,7 @@ export function runDetail(db: Db, sourceId: string, runId: string) {
   const sealed = evs.find((e) => e.type === "receipt.sealed")?.data;
   return {
     ...withLive(db, r),
+    blocked_question: blockedQuestion(evs, r.verdict),
     stages,
     stages_completed: f.completed,
     receipt: sealed ? { sha256: str(sealed.receipt_sha256), signed: sealed.signed === true, verdict: str(sealed.verdict), path: str(sealed.path) } : null,

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

@@ -1,10 +1,10 @@
 // Entry for `loki control serve` (bundled to dist/server.js). Config comes from env: PORT, LOKI_CONTROL_DB.
-// Binds loopback only. LOKI_CONTROL_PORT_FALLBACK=1 (set for the default port, never for an explicit --port)
+// Binds loopback unless LOKI_CONTROL_HOST is set (the container image sets 0.0.0.0). LOKI_CONTROL_PORT_FALLBACK=1 (set for the default port, never for an explicit --port)
 // retries on any free port when PORT is taken; the URL printed below is always the real one.
 import { createApp } from "./app.ts";
 
 const { app } = createApp({ dbPath: process.env.LOKI_CONTROL_DB ?? "control.db" });
-const serve = (port: number) => Bun.serve({ port, hostname: "127.0.0.1", fetch: app.fetch });
+const serve = (port: number) => Bun.serve({ port, hostname: process.env.LOKI_CONTROL_HOST || "127.0.0.1", fetch: app.fetch });
 let s: ReturnType<typeof serve>;
 try {
   s = serve(Number(process.env.PORT ?? 0));