loki-mode 7.79.0 → 7.80.0

package/SKILL.md

@@ -3,7 +3,7 @@ name: loki-mode
 description: Autonomous spec-driven build system with a built-in trust layer. It does not call work done until it is verified (RARV-C closure loop, 8 quality gates, completion council, verified-completion evidence gate). Triggers on "Loki Mode". Takes a spec (PRD, GitHub issue, OpenAPI doc, etc.) to deployed product with minimal human intervention. Provider-agnostic. Requires --dangerously-skip-permissions flag.
 ---
 
-# Loki Mode v7.79.0
+# Loki Mode v7.80.0
 
 **You are an autonomous agent. You make decisions. You do not ask questions. You do not stop.**
 
@@ -406,4 +406,4 @@ See `CHANGELOG.md` entries [7.5.7], [7.5.8], [7.5.13] for the per-fix list and r
 
 ---
 
-**v7.79.0 | [Autonomi](https://www.autonomi.dev/) flagship product | ~260 lines core**
+**v7.80.0 | [Autonomi](https://www.autonomi.dev/) flagship product | ~260 lines core**

package/VERSION

@@ -1 +1 @@
-7.79.0
+7.80.0

package/autonomy/loki

@@ -2927,6 +2927,133 @@ cmd_resume() {
     fi
 }
 
+# loki why -- actionable failure/outcome diagnosis (B5).
+# Reads the already-captured run artifacts (no new state): the terminal run state
+# (.loki/<autonomy-state>.json: status, lastExitCode, iterationCount), the durable
+# completion record (.loki/state/completion.json: outcome, branch, files, pr_url),
+# and the latest structured handoff (.loki/memory/handoffs/*.md). Produces an
+# honest "what happened + what to do" report. Read-only; never fabricates -- if a
+# field was not captured it says so. --json emits the machine-readable record.
+cmd_why() {
+    local as_json=0
+    case "${1:-}" in
+        --json) as_json=1 ;;
+        --help|-h) echo "Usage: loki why [--json]  -- explain the last build's outcome and what to do next"; return 0 ;;
+        "" ) : ;;
+        *) echo -e "${RED}Unknown flag: $1${NC}"; echo "Usage: loki why [--json]"; return 1 ;;
+    esac
+
+    local loki_dir="${LOKI_DIR:-.loki}"
+    # Session-namespaced state when LOKI_SESSION_ID is set (mirrors run.sh A6).
+    local state_file="$loki_dir/autonomy-state.json"
+    if [ -n "${LOKI_SESSION_ID:-}" ] && [ -f "$loki_dir/sessions/${LOKI_SESSION_ID}/autonomy-state.json" ]; then
+        state_file="$loki_dir/sessions/${LOKI_SESSION_ID}/autonomy-state.json"
+    fi
+    local completion_file="$loki_dir/state/completion.json"
+
+    if [ ! -f "$state_file" ] && [ ! -f "$completion_file" ]; then
+        echo "loki why: no run found here yet (no $state_file or $completion_file)." >&2
+        echo "Run a build first: loki start <spec>" >&2
+        return 1
+    fi
+
+    if [ "$as_json" = "1" ]; then
+        _LOKI_WHY_STATE="$state_file" _LOKI_WHY_COMPLETION="$completion_file" python3 - <<'WHYJSON'
+import json, os
+def load(p):
+    try:
+        with open(p) as f: return json.load(f)
+    except Exception: return {}
+state = load(os.environ.get("_LOKI_WHY_STATE", ""))
+comp = load(os.environ.get("_LOKI_WHY_COMPLETION", ""))
+print(json.dumps({"state": state, "completion": comp}, indent=2))
+WHYJSON
+        return 0
+    fi
+
+    # Human-readable report. The diagnosis maps the terminal status to a plain
+    # explanation + a concrete next action; everything is sourced from the files,
+    # nothing is invented.
+    _LOKI_WHY_STATE="$state_file" _LOKI_WHY_COMPLETION="$completion_file" \
+    _LOKI_WHY_HANDOFFS="$loki_dir/memory/handoffs" python3 - <<'WHYTXT'
+import json, os, glob
+def load(p):
+    try:
+        with open(p) as f: return json.load(f)
+    except Exception: return {}
+state = load(os.environ.get("_LOKI_WHY_STATE", ""))
+comp = load(os.environ.get("_LOKI_WHY_COMPLETION", ""))
+status = state.get("status") or comp.get("outcome") or "unknown"
+exit_code = state.get("lastExitCode")
+iters = state.get("iterationCount")
+
+# status -> (one-line meaning, suggested next action). Honest + specific.
+GUIDE = {
+    "council_approved": ("The completion council agreed the work is done and verified.",
+                         "Review the diff and open a PR (git push + gh pr create, or LOKI_AUTO_PR=1)."),
+    "council_force_approved": ("Completion was force-approved (council could not fully converge).",
+                               "Review the diff carefully before merging -- convergence was not unanimous."),
+    "completion_promise_fulfilled": ("The agent declared its explicit completion promise fulfilled.",
+                                     "Verify the promised outcome, then review and PR."),
+    "max_iterations_reached": ("The build hit the iteration cap before the council approved it.",
+                               "Inspect what is left (loki status), raise LOKI_MAX_ITERATIONS or narrow the spec, and resume."),
+    "max_retries_exceeded": ("The build exhausted its retry budget on a repeating failure.",
+                             "Read .loki/logs for the recurring error (rate limit? failing test?), fix the root cause, then re-run."),
+    "failed": ("The build ended in a failure state.",
+               "Read .loki/logs/ + the handoff below for the failure, fix it, then re-run."),
+    "policy_blocked": ("A policy/trust gate blocked completion.",
+                       "Review the blocking finding; address it or use the documented override path."),
+    "budget_exceeded": ("The cost budget breaker paused the build.",
+                        "Raise LOKI_BUDGET_LIMIT or accept the partial result, then resume."),
+    "paused": ("The build is paused (human-intervention signal).",
+               "Resume with: loki resume."),
+    "interrupted": ("The build was interrupted before a terminal state.",
+                    "Resume with: loki resume."),
+    "stopped": ("The build was stopped by the operator.",
+                "Start a new build with loki start, or resume if you meant to continue."),
+    "force_stopped": ("The build was force-stopped.",
+                      "Start a new build, or investigate why a force-stop was needed."),
+    "running": ("The recorded state says a build is still running (or crashed mid-run).",
+                "If no build is active it likely crashed; in durable mode (LOKI_DURABLE_STATE=1) a restart resumes, else loki start re-runs."),
+}
+meaning, action = GUIDE.get(status, ("No diagnosis mapping for this status; see the raw fields below.",
+                                     "Check loki status and .loki/logs/ for detail."))
+
+print("Loki: why")
+print("=" * 60)
+print(f"  Outcome     : {status}")
+if exit_code is not None:
+    print(f"  Exit code   : {exit_code}")
+if iters is not None:
+    print(f"  Iterations  : {iters}")
+if comp.get("branch"):
+    print(f"  Branch      : {comp['branch']}")
+if comp.get("files_changed") is not None:
+    print(f"  Changes     : {comp.get('files_changed',0)} files (+{comp.get('insertions',0)}/-{comp.get('deletions',0)})")
+if comp.get("pr_url"):
+    print(f"  PR          : {comp['pr_url']}")
+print()
+print(f"  What happened: {meaning}")
+print(f"  What to do   : {action}")
+
+# Surface the latest structured handoff (already-captured context), honestly.
+hd = sorted(glob.glob(os.path.join(os.environ.get("_LOKI_WHY_HANDOFFS",""), "*.md")))
+if hd:
+    print()
+    print(f"  Latest handoff: {hd[-1]}")
+    try:
+        with open(hd[-1]) as f:
+            head = "".join(f.readlines()[:8]).rstrip()
+        for line in head.splitlines():
+            print(f"    {line}")
+    except Exception:
+        pass
+print()
+print("  (loki why --json for the raw record; loki status for live state.)")
+WHYTXT
+    return 0
+}
+
 # Show current status
 cmd_status() {
     # Check for flags
@@ -15481,6 +15608,9 @@ main() {
         status)
             cmd_status "$@"
             ;;
+        why)
+            cmd_why "$@"
+            ;;
         stats)
             # CLI consolidation (Phase A): 'stats' is a deprecated alias of
             # 'report session'. On the Bun route this arm is never reached

package/autonomy/run.sh

@@ -5253,6 +5253,9 @@ print_ttfv_next_steps() {
         echo "    loki start ./prd.md        # build from a full PRD"
         echo "    loki start \"<one line>\"    # fast first pass from a brief"
     fi
+    # Frictionless discovery: surface 'loki why' so users learn the
+    # what-happened/what-to-do diagnosis without having to know it exists.
+    echo "    loki why                   # explain this outcome + what to do next"
     echo ""
     return 0
 }

package/dashboard/__init__.py

@@ -7,7 +7,7 @@ Modules:
     control: Session control API (start/stop/pause/resume)
 """
 
-__version__ = "7.79.0"
+__version__ = "7.80.0"
 
 # Expose the control app for easy import
 try:

package/dashboard/registry.py

@@ -525,6 +525,218 @@ def get_cross_project_tasks(project_ids: Optional[list[str]] = None) -> list[dic
     return all_tasks
 
 
+def _pid_alive(pid) -> bool:
+    """Return True if pid is a positive int naming a live process.
+
+    Mirrors the liveness probe used by the dashboard's running-projects view:
+    signal 0 delivered -> alive; EPERM (owned by another user) -> alive; ESRCH
+    -> dead. Never raises.
+    """
+    if not isinstance(pid, int) or pid <= 0:
+        return False
+    try:
+        os.kill(pid, 0)
+        return True
+    except PermissionError:
+        return True
+    except (ProcessLookupError, OSError):
+        return False
+
+
+def _read_project_run_snapshot(path: str) -> dict:
+    """Read a single project's live run snapshot from its .loki/ state files.
+
+    HONEST SCOPE: this polls the shared on-disk metadata that `loki start`
+    already writes per project (no new store, no controller). It reads:
+      - .loki/dashboard-state.json (phase, iteration; written ~every 2s)
+      - .loki/session.json         (status, startedAt fallback)
+      - .loki/metrics/efficiency/*.json (summed cost_usd) with a
+        .loki/context/tracking.json fallback (totals.total_cost_usd)
+
+    Returns a dict with phase, iteration, cost_usd, started_at, and ended_at
+    (best-effort; missing values default to None/0). Never raises: any file
+    problem degrades the affected field to its default.
+    """
+    snap = {
+        "phase": "",
+        "iteration": 0,
+        "cost_usd": 0.0,
+        "started_at": None,
+        "ended_at": None,
+    }
+    if not path:
+        return snap
+    loki_dir = Path(path) / ".loki"
+
+    # Phase + iteration from dashboard-state.json (the live writer).
+    state_file = loki_dir / "dashboard-state.json"
+    if state_file.exists():
+        try:
+            state = json.loads(state_file.read_text())
+            if isinstance(state, dict):
+                _p = state.get("phase", "")
+                snap["phase"] = _p if isinstance(_p, str) else ""
+                _i = state.get("iteration", 0)
+                snap["iteration"] = _i if isinstance(_i, int) else 0
+        except (json.JSONDecodeError, OSError, ValueError):
+            pass
+
+    # Timestamps from session.json (startedAt; endedAt when present).
+    session_file = loki_dir / "session.json"
+    if session_file.exists():
+        try:
+            sd = json.loads(session_file.read_text())
+            if isinstance(sd, dict):
+                _sa = sd.get("startedAt") or sd.get("started_at")
+                snap["started_at"] = _sa if isinstance(_sa, str) else None
+                _ea = sd.get("endedAt") or sd.get("ended_at")
+                snap["ended_at"] = _ea if isinstance(_ea, str) else None
+        except (json.JSONDecodeError, OSError, ValueError):
+            pass
+
+    # Cost: sum per-iteration efficiency files; fall back to context tracking.
+    cost = 0.0
+    found_cost = False
+    eff_dir = loki_dir / "metrics" / "efficiency"
+    if eff_dir.is_dir():
+        try:
+            for eff_file in eff_dir.glob("*.json"):
+                try:
+                    data = json.loads(eff_file.read_text())
+                    if not isinstance(data, dict):
+                        continue
+                    c = data.get("cost_usd")
+                    if isinstance(c, (int, float)):
+                        cost += float(c)
+                        found_cost = True
+                except (json.JSONDecodeError, OSError, ValueError):
+                    continue
+        except OSError:
+            pass
+    if not found_cost:
+        ctx_file = loki_dir / "context" / "tracking.json"
+        if ctx_file.exists():
+            try:
+                ctx = json.loads(ctx_file.read_text())
+                if isinstance(ctx, dict):
+                    totals = ctx.get("totals", {})
+                    if isinstance(totals, dict):
+                        tc = totals.get("total_cost_usd")
+                        if isinstance(tc, (int, float)):
+                            cost = float(tc)
+            except (json.JSONDecodeError, OSError, ValueError):
+                pass
+    snap["cost_usd"] = round(cost, 6)
+    return snap
+
+
+def get_fleet_runs(include_inactive: bool = True) -> list[dict]:
+    """Build a fleet-wide view of builds across ALL registered projects.
+
+    v1 SCOPE (honest): this polls the shared metadata store that `loki start`
+    already maintains -- the machine-global registry (~/.loki/dashboard/
+    projects.json) plus each project's own .loki/ state files. There is NO
+    controller, CRD, or Job-watcher here; a real k8s operator watching Jobs is
+    future work. One registered project maps to one "run" entry (its current /
+    most-recent build), which is the granularity the registry tracks.
+
+    Each entry carries: id, name, path, status (running|stopped|<registry
+    status>), running (live pid probe), phase, iteration, cost_usd, started_at,
+    duration_seconds, port. Never raises: registry problems degrade to an empty
+    list and per-project read problems degrade that entry's fields.
+    """
+    try:
+        projects = list_projects(include_inactive=include_inactive)
+    except Exception:
+        return []
+
+    out = []
+    for p in projects:
+        path = p.get("path", "")
+        pid = p.get("pid")
+        running = _pid_alive(pid)
+        snap = _read_project_run_snapshot(path)
+
+        # A live pid is authoritative for "running"; otherwise reflect the
+        # registry status (stopped/active/missing). This mirrors the
+        # running-projects endpoint's pid-first precedence.
+        if running:
+            status = "running"
+        else:
+            status = p.get("status") or "unknown"
+
+        # Duration: wall time from started_at to ended_at (or now if running).
+        duration_seconds = None
+        started_at = snap.get("started_at")
+        if started_at:
+            try:
+                st = datetime.fromisoformat(str(started_at).replace("Z", "+00:00"))
+                if st.tzinfo is None:
+                    st = st.replace(tzinfo=timezone.utc)
+                end_ref = None
+                ended_at = snap.get("ended_at")
+                if ended_at and not running:
+                    try:
+                        end_ref = datetime.fromisoformat(
+                            str(ended_at).replace("Z", "+00:00")
+                        )
+                        if end_ref.tzinfo is None:
+                            end_ref = end_ref.replace(tzinfo=timezone.utc)
+                    except (ValueError, TypeError):
+                        end_ref = None
+                if end_ref is None:
+                    end_ref = datetime.now(timezone.utc)
+                duration_seconds = max(0, int((end_ref - st).total_seconds()))
+            except (ValueError, TypeError):
+                duration_seconds = None
+
+        out.append({
+            "id": p.get("id"),
+            "name": p.get("name") or (os.path.basename(path) if path else "project"),
+            "path": path,
+            "status": status,
+            "running": running,
+            "phase": snap.get("phase", ""),
+            "iteration": snap.get("iteration", 0),
+            "cost_usd": snap.get("cost_usd", 0.0),
+            "started_at": started_at,
+            "duration_seconds": duration_seconds,
+            "port": p.get("port"),
+        })
+
+    # Running builds first, then by most-recent start time.
+    out.sort(
+        key=lambda r: (
+            0 if r.get("running") else 1,
+            r.get("started_at") or "",
+        ),
+        reverse=False,
+    )
+    # Within the same running-group, most recent start first.
+    out.sort(key=lambda r: r.get("started_at") or "", reverse=True)
+    out.sort(key=lambda r: 0 if r.get("running") else 1)
+    return out
+
+
+def get_fleet_summary(include_inactive: bool = True) -> dict:
+    """Aggregate fleet-wide totals from get_fleet_runs().
+
+    Returns counts (total / running / stopped) and a summed cost across all
+    registered projects. v1 polls the shared metadata store (see
+    get_fleet_runs); not a controller. Never raises.
+    """
+    runs = get_fleet_runs(include_inactive=include_inactive)
+    total = len(runs)
+    running = sum(1 for r in runs if r.get("running"))
+    total_cost = round(sum(float(r.get("cost_usd") or 0.0) for r in runs), 6)
+    return {
+        "total_runs": total,
+        "running_runs": running,
+        "stopped_runs": total - running,
+        "total_cost_usd": total_cost,
+    }
+
+
 def get_cross_project_learnings() -> dict:
     """
     Get learnings from the global learnings database.

package/dashboard/server.py

@@ -2389,6 +2389,118 @@ async def get_cross_project_learnings():
     return learnings
 
 
+# =============================================================================
+# Fleet Observability (v1: poll the shared metadata store)
+# =============================================================================
+#
+# HONEST SCOPE: these endpoints aggregate the data `loki start` already writes
+# -- the machine-global registry (~/.loki/dashboard/projects.json) plus each
+# project's own .loki/ state files. There is NO controller, CRD, or Kubernetes
+# Job-watcher; a real operator watching Jobs is future work. One registered
+# project maps to one fleet "run" (its current / most-recent build), which is
+# the granularity the registry tracks. Cancel reuses the same STOP-file + pid
+# teardown as the per-project switcher Stop. Retry is intentionally NOT exposed
+# here: there is no clean cross-project re-launch primitive in the registry
+# path (the original spec source lives only in each project's CWD), so retry is
+# a follow-up.
+
+
+class FleetRunResponse(BaseModel):
+    """One fleet run = one registered project's current/most-recent build."""
+    id: Optional[str] = None
+    name: str
+    path: str
+    status: str
+    running: bool
+    phase: str = ""
+    iteration: int = 0
+    cost_usd: float = 0.0
+    started_at: Optional[str] = None
+    duration_seconds: Optional[int] = None
+    port: Optional[int] = None
+
+
+class FleetSummaryResponse(BaseModel):
+    """Fleet-wide totals across all registered projects."""
+    total_runs: int
+    running_runs: int
+    stopped_runs: int
+    total_cost_usd: float
+
+
+@app.get(
+    "/api/fleet/runs",
+    response_model=list[FleetRunResponse],
+    dependencies=[Depends(auth.require_scope("read"))],
+)
+async def list_fleet_runs(include_inactive: bool = True):
+    """List all builds across every registered project (fleet view).
+
+    v1 polls the shared metadata store (registry + per-project .loki/ state);
+    it is not a controller. Never raises: registry problems degrade to [].
+    """
+    if not _read_limiter.check("fleet_runs"):
+        raise HTTPException(status_code=429, detail="Rate limit exceeded")
+    return await asyncio.to_thread(registry.get_fleet_runs, include_inactive)
+
+
+@app.get(
+    "/api/fleet/summary",
+    response_model=FleetSummaryResponse,
+    dependencies=[Depends(auth.require_scope("read"))],
+)
+async def get_fleet_summary(include_inactive: bool = True):
+    """Fleet-wide totals (counts + summed cost) across registered projects."""
+    if not _read_limiter.check("fleet_summary"):
+        raise HTTPException(status_code=429, detail="Rate limit exceeded")
+    return await asyncio.to_thread(registry.get_fleet_summary, include_inactive)
+
+
+@app.get(
+    "/api/fleet/runs/{identifier}",
+    response_model=FleetRunResponse,
+    dependencies=[Depends(auth.require_scope("read"))],
+)
+async def get_fleet_run(identifier: str):
+    """Get a single fleet run by registry id / path / alias.
+
+    Resolves the identifier through the registry (never a caller-supplied
+    arbitrary path), then returns that project's current build snapshot.
+    """
+    project = await asyncio.to_thread(registry.get_project, identifier)
+    if not project:
+        raise HTTPException(status_code=404, detail="Run not found in fleet")
+    pid = project.get("pid")
+    running = registry._pid_alive(pid)
+    snap = registry._read_project_run_snapshot(project.get("path", ""))
+    duration_seconds = None
+    started_at = snap.get("started_at")
+    if started_at:
+        try:
+            st = datetime.fromisoformat(str(started_at).replace("Z", "+00:00"))
+            if st.tzinfo is None:
+                st = st.replace(tzinfo=timezone.utc)
+            duration_seconds = max(
+                0, int((datetime.now(timezone.utc) - st).total_seconds())
+            )
+        except (ValueError, TypeError):
+            duration_seconds = None
+    path = project.get("path", "")
+    return FleetRunResponse(
+        id=project.get("id"),
+        name=project.get("name") or (os.path.basename(path) if path else "project"),
+        path=path,
+        status="running" if running else (project.get("status") or "unknown"),
+        running=running,
+        phase=snap.get("phase", ""),
+        iteration=snap.get("iteration", 0),
+        cost_usd=snap.get("cost_usd", 0.0),
+        started_at=started_at,
+        duration_seconds=duration_seconds,
+        port=project.get("port"),
+    )
+
+
 # =============================================================================
 # Active Project Focus (for AI Chat / cross-directory usage)
 # =============================================================================
@@ -3204,6 +3316,130 @@ async def stop_running_project(request: Request, body: RunningProjectStopRequest
     }
 
 
+@app.post(
+    "/api/fleet/runs/{identifier}/cancel",
+    dependencies=[Depends(auth.require_scope("control"))],
+)
+async def cancel_fleet_run(request: Request, identifier: str):
+    """Cancel ONE build in the fleet view.
+
+    Resolves the run via the registry (by id / path / alias), then runs the
+    same teardown the per-project switcher Stop uses: write a STOP file into the
+    registry-resolved .loki dir (the only path ever written -- never a
+    caller-supplied one) for a clean runner exit, SIGTERM->poll->SIGKILL the
+    recorded orchestrator pid, group-kill + cwd-scoped reap as backstop, then
+    mark the registry/session stopped.
+
+    Retry is intentionally NOT exposed: there is no clean cross-project
+    re-launch primitive in the registry path (the original spec source lives
+    only in each project's CWD). Retry is a documented follow-up.
+    """
+    if not _control_limiter.check("control"):
+        raise HTTPException(status_code=429, detail="Rate limit exceeded")
+
+    project = registry.get_project(identifier)
+    if not project:
+        raise HTTPException(status_code=404, detail="Run not found in fleet")
+
+    project_id = project.get("id")
+    audit.log_event(
+        action="cancel",
+        resource_type="fleet_run",
+        details={"source": "api", "project_id": project_id},
+        ip_address=request.client.host if request.client else None,
+    )
+
+    # Only ever operate on the registry-stored path.
+    path = project.get("path", "")
+    loki_dir = None
+    if path:
+        p = _Path(path)
+        if p.is_dir() and (p / ".loki").is_dir():
+            loki_dir = p / ".loki"
+
+    # STOP file: clean runner teardown (also stops a containerized `loki docker`
+    # build polling the bind-mounted .loki/STOP).
+    stop_signaled = False
+    if loki_dir is not None:
+        try:
+            (loki_dir / "STOP").write_text(datetime.now(timezone.utc).isoformat())
+            stop_signaled = True
+        except OSError:
+            pass
+
+    pid = project.get("pid")
+    stopped = False
+    # Ownership guard (hardening): only direct-kill the registry pid if it is STILL
+    # a process whose cwd is this project's path. A stale pid reused by an unrelated
+    # host process after a crash must NOT be SIGKILLed. If ownership cannot be
+    # confirmed, skip the direct kill and let the cwd-scoped reaper below handle it.
+    if isinstance(pid, int) and pid > 0:
+        _owned = True
+        try:
+            _cwd = _pid_cwd(pid)
+            if _cwd is not None and path:
+                _owned = os.path.realpath(_cwd) == os.path.realpath(path)
+        except Exception:
+            _owned = True  # best-effort: if we cannot tell, preserve prior behavior
+        if not _owned:
+            pid = None  # do not direct-kill a pid that is not this project's
+    if isinstance(pid, int) and pid > 0:
+        try:
+            os.kill(pid, 15)  # SIGTERM
+            for _ in range(10):
+                await asyncio.sleep(0.5)
+                try:
+                    os.kill(pid, 0)
+                except OSError:
+                    stopped = True
+                    break
+            if not stopped:
+                try:
+                    os.kill(pid, 9)  # SIGKILL
+                    stopped = True
+                except (OSError, ProcessLookupError):
+                    stopped = True
+        except (ValueError, OSError, ProcessLookupError):
+            stopped = True
+    else:
+        # No host pid (genuinely stopped, or a docker build): the STOP write is
+        # the cancel signal. Treat a successful STOP write as cancelled.
+        stopped = stop_signaled
+
+    # Group-kill + cwd-scoped reaper backstop against a stale pid.
+    if loki_dir is not None:
+        proj_dir = loki_dir.parent
+        _pgid = _read_pgid(loki_dir)
+        if _pgid is not None:
+            await asyncio.to_thread(
+                _killpg_project, _pgid, _collect_protected_pids(loki_dir)
+            )
+        found_any, all_gone = await asyncio.to_thread(
+            _reap_orchestrators_until_clear, proj_dir, str(proj_dir)
+        )
+        if found_any:
+            stopped = all_gone
+
+        # Mark session.json stopped.
+        session_file = loki_dir / "session.json"
+        if session_file.exists():
+            try:
+                sd = json.loads(session_file.read_text())
+                sd["status"] = "stopped"
+                atomic_write_json(session_file, sd, use_lock=True)
+            except Exception:
+                pass
+
+    registry.mark_project_stopped(project_id)
+
+    return {
+        "success": True,
+        "project_id": project_id,
+        "cancelled": stopped,
+        "stop_signaled": stop_signaled,
+    }
+
+
 # =============================================================================
 # Enterprise Features (Optional - enabled via environment variables)
 # =============================================================================