loki-mode 7.87.0 → 7.89.0

package/autonomy/spec-interrogation.sh

@@ -820,15 +820,37 @@ print("%d %d" % (total, high))
 # resolution (sets confirmed=true). This is deliberately the same teeth the
 # LOKI_ASSUMPTIONS_REQUIRE_CONFIRM=1 path applies to ALL entries, scoped here to
 # just contradictions in default autonomous mode. See the design note below.
+#
+# F50 (zero-config brief mode): a one-line-brief run (LOKI_TTFV=brief) is the
+# zero-config first-pass path. There is no human in the loop and the audience
+# is non-technical: a permanently-blocking contradiction makes a brief run grind
+# to max-iterations and NEVER cleanly complete -- a broken first-run UX for the
+# exact users the brief path exists to serve. Worse, a synthetic brief-PRD that
+# Loki itself wrote is unlikely to carry a real human-authored contradiction;
+# leaving the gate blocking yields no signal a non-technical user can act on.
+# So in brief mode contradictions are RESOLVED-WITH-DEFAULT, not blocked: Loki
+# acknowledges the entry, records resolved_with_default=true plus an honest
+# resolution note, and the gate is allowed to clear. This is NOT hiding the gap:
+# spec_ledger_counts still counts the entry, build_completion_summary still folds
+# it into the proof-of-done, ledger.md still lists it, and `loki own` still tells
+# the user to review the assumptions Loki had to make. PRD mode (a real
+# human-authored spec, where a human CAN resolve a contradiction) keeps the
+# original BLOCKING behavior unchanged. brief mode is detected from LOKI_TTFV=brief
+# (set by cmd_start) and is overridable by the explicit param for tests/callers.
+# Usage: spec_ledger_acknowledge_all [brief_mode]   # brief_mode: "brief" to resolve contradictions
 # ---------------------------------------------------------------------------
 spec_ledger_acknowledge_all() {
     [ "${LOKI_ASSUMPTIONS_REQUIRE_CONFIRM:-0}" = "1" ] && return 0
-    local dir
+    local dir brief_mode
+    # F50: brief/zero-config mode resolves contradictions with a default rather
+    # than blocking forever. Explicit param wins; otherwise read LOKI_TTFV.
+    brief_mode="${1:-${LOKI_TTFV:-}}"
     dir="$(_spec_ledger_dir)"
     [ -d "$dir" ] || return 0
-    _SL_DIR="$dir" python3 -c '
+    _SL_DIR="$dir" _SL_BRIEF="$brief_mode" python3 -c '
 import glob, json, os, tempfile
 d = os.environ["_SL_DIR"]
+brief = os.environ.get("_SL_BRIEF", "") == "brief"
 for p in glob.glob(os.path.join(d, "a-*.json")):
     try:
         with open(p) as f:
@@ -837,10 +859,22 @@ for p in glob.glob(os.path.join(d, "a-*.json")):
         continue
     if r.get("acknowledged"):
         continue
-    # P2-4: a contradiction cannot be assumed away, so it is never auto-acked.
-    if r.get("class") == "contradictory":
+    is_contradiction = r.get("class") == "contradictory"
+    # P2-4: a contradiction cannot be assumed away, so it is never auto-acked
+    # in default / PRD mode (a human can resolve it there).
+    if is_contradiction and not brief:
         continue
     r["acknowledged"] = True
+    # F50: brief-mode contradictions are resolved-with-default, marked honestly
+    # so the receipt / ledger / `loki own` can show "Loki chose a default here".
+    if is_contradiction and brief:
+        r["resolved_with_default"] = True
+        if not r.get("resolution_note"):
+            r["resolution_note"] = (
+                "Resolved with a reasonable default in zero-config brief mode "
+                "(no human in the loop). Review and refine via a full PRD run "
+                "(loki start ./prd.md) if this default is wrong."
+            )
     fd, tmp = tempfile.mkstemp(dir=os.path.dirname(p), suffix=".tmp")
     try:
         with os.fdopen(fd, "w", encoding="utf-8") as f:
@@ -907,7 +941,17 @@ else:
     lines.append("Total assumptions: %d (%d high-severity)" % (len(entries), high))
     lines.append("")
     for e in entries:
-        state = "confirmed" if e.get("confirmed") else ("acknowledged" if e.get("acknowledged") else "OPEN")
+        # F50: surface a resolved-with-default state distinctly so a brief-mode
+        # contradiction reads honestly ("Loki chose a default") rather than as a
+        # plain ack or a silent pass.
+        if e.get("confirmed"):
+            state = "confirmed"
+        elif e.get("resolved_with_default"):
+            state = "resolved-with-default"
+        elif e.get("acknowledged"):
+            state = "acknowledged"
+        else:
+            state = "OPEN"
         lines.append("## %s [%s / %s / %s]" % (e.get("id",""), e.get("severity",""), e.get("class",""), state))
         lines.append("")
         lines.append("- Gap: %s" % e.get("gap",""))
@@ -915,6 +959,8 @@ else:
         lines.append("- Why: %s" % e.get("why",""))
         lines.append("- Affects: %s" % e.get("affects",""))
         lines.append("- Source: %s" % e.get("source",""))
+        if e.get("resolution_note"):
+            lines.append("- Resolution: %s" % e.get("resolution_note"))
         lines.append("")
 out = os.path.join(d, "ledger.md")
 fd, tmp = tempfile.mkstemp(dir=d, suffix=".tmp")

package/autonomy/telemetry.sh

@@ -1,24 +1,97 @@
 #!/usr/bin/env bash
 # Anonymous usage telemetry for Loki Mode
-# Collection is OPT-IN and OFF by default. Nothing is sent unless the user opts
-# in, so a default install never phones home (air-gapped / GDPR / FedRAMP safe).
-# Opt-in:  LOKI_TELEMETRY=on  OR  ~/.loki/config: TELEMETRY_ENABLED=true
+# Collection is ON BY DEFAULT for individual interactive installs, but AUTO-OFF
+# in enterprise / CI / air-gapped contexts (see _loki_telemetry_auto_off), so
+# enterprise + air-gapped deployments stay silent out of the box (GDPR / FedRAMP
+# safe). Only anonymous diagnostics are ever sent (os, arch, version, error type,
+# sanitized stack signatures); never code, prompts, paths, keys, or repo names.
 # Opt-out (always wins): LOKI_TELEMETRY=off / LOKI_TELEMETRY_DISABLED=true /
 #                        DO_NOT_TRACK=1 / ~/.loki/config: TELEMETRY_DISABLED=true
-# All calls are fire-and-forget, silent on failure, non-blocking
+# Force-on:  LOKI_TELEMETRY=on  OR  ~/.loki/config: TELEMETRY_ENABLED=true
+# All calls are fire-and-forget, silent on failure, non-blocking.
+# Disclosed in docs/PRIVACY.md + a one-time disclosure on first use (never covert).
+
+# _loki_telemetry_auto_off: returns 0 (true, auto-disable) when the environment is
+# enterprise / CI / non-interactive / air-gapped, where on-by-default would be
+# inappropriate. Keeps "enterprise + air-gapped safe out of the box" literally
+# true while still defaulting ON for ordinary individual users. Shared by every
+# gate (crash.sh, dashboard/telemetry.py mirror this list).
+#   - CI/automation: CI / GITHUB_ACTIONS / GITLAB_CI / BUILDKITE / JENKINS_URL /
+#     TEAMCITY_VERSION / CONTINUOUS_INTEGRATION
+#   - Enterprise opt-out: LOKI_ENTERPRISE=true / LOKI_AIRGAP=true
+#   - Non-interactive: no TTY on stdout AND stdin (scripts/pipes/detached)
+_loki_telemetry_auto_off() {
+    [ "${CI:-}" = "true" ] && return 0
+    [ -n "${GITHUB_ACTIONS:-}" ] && return 0
+    [ -n "${GITLAB_CI:-}" ] && return 0
+    [ -n "${BUILDKITE:-}" ] && return 0
+    [ -n "${JENKINS_URL:-}" ] && return 0
+    [ -n "${TEAMCITY_VERSION:-}" ] && return 0
+    [ "${CONTINUOUS_INTEGRATION:-}" = "true" ] && return 0
+    [ "${LOKI_ENTERPRISE:-}" = "true" ] && return 0
+    [ "${LOKI_AIRGAP:-}" = "true" ] && return 0
+    # Non-interactive detection (council cH_r1 AC2). Interactivity is resolved
+    # EXACTLY ONCE at the real entry point (bin/loki shim top / autonomy/loki
+    # main), while the user's TTY is present, and exported as LOKI_TTY_INTERACTIVE.
+    # We must trust that explicit signal here instead of a fresh `-t` probe,
+    # because this gate runs inside FD-detached subshells (the bin/loki gate-check
+    # and the backgrounded emit) where a `-t` probe always sees non-TTY and would
+    # wrongly auto-off a real interactive user.
+    # Precedence:
+    #   - LOKI_TTY_INTERACTIVE=1  -> interactive (do NOT auto-off here)
+    #   - LOKI_TTY_INTERACTIVE=0/other set -> non-interactive (auto-off)
+    #   - UNSET (gate ran without passing an entry point, e.g. an isolated unit
+    #     test) -> fall back to the live `-t` probe so isolated gate tests behave.
+    if [ -n "${LOKI_TTY_INTERACTIVE:-}" ]; then
+        [ "${LOKI_TTY_INTERACTIVE}" = "1" ] && return 1
+        return 0
+    fi
+    if [ ! -t 1 ] && [ ! -t 0 ]; then
+        return 0
+    fi
+    return 1
+}
 
 LOKI_POSTHOG_HOST="${LOKI_TELEMETRY_ENDPOINT:-https://us.i.posthog.com}"
 LOKI_POSTHOG_KEY="phc_ya0vGBru41AJWtGNfZZ8H9W4yjoZy4KON0nnayS7s87"
 
+# _loki_disclose_telemetry_once: one-time, route-shared disclosure (council
+# cH_r1 AC4). Prints a single anonymous-diagnostics disclosure to the user's
+# REAL stderr the first time collection is ACTUALLY enabled at egress time, then
+# records its OWN marker so it never repeats. This is the SINGLE shared impl used
+# by BOTH the Bun route (bin/loki, which sources this file at top level just for
+# this helper) and the bash route (autonomy/loki main, before its foreground
+# cli_command egress) so no first command is ever covert and the copy never
+# drifts between routes. Keyed on ~/.loki/.telemetry-disclosed, NOT the
+# .loki-first-run sentinel: a first run in CI/auto-off sets .loki-first-run while
+# suppressing disclosure, which must NOT permanently silence the disclosure on a
+# later interactive (enabled) run (the sentinel edge, AC5). Guarded so a single
+# definition wins if both this file and another loader define it.
+if ! declare -f _loki_disclose_telemetry_once >/dev/null 2>&1; then
+_loki_disclose_telemetry_once() {
+    local _marker="${HOME}/.loki/.telemetry-disclosed"
+    [ -f "$_marker" ] 2>/dev/null && return 0
+    printf '%s\n' \
+      "Loki Mode sends anonymous diagnostics (os, arch, version, error type only --" \
+      "never your code, prompts, paths, or keys) to help fix bugs. Off in enterprise/" \
+      "CI/air-gapped setups. Turn it off anytime: loki telemetry off  (docs/PRIVACY.md)" >&2
+    mkdir -p "${HOME}/.loki" 2>/dev/null || return 0
+    : > "$_marker" 2>/dev/null || true
+    return 0
+}
+fi
+
 _loki_telemetry_enabled() {
-    # Unified OPT-IN gate. Returns 0 (enabled) ONLY when the user opted in AND
-    # did not also opt out. Opt-out always wins; default is OFF. This precedence
+    # Unified gate. Default ON for individual interactive installs; auto-OFF in
+    # enterprise/CI/air-gapped contexts; explicit opt-out always wins. Precedence
     # MUST mirror loki_collection_enabled in autonomy/crash.sh and _is_enabled in
     # dashboard/telemetry.py so one model gates BOTH usage telemetry and crash
     # reporting.
-    #   1. Any opt-out flag present  -> 1 (hard kill, always wins)
-    #   2. Else any opt-in flag present -> 0
-    #   3. Else (default)            -> 1 (no egress)
+    #   1. Any opt-out flag present     -> 1 (hard kill, always wins)
+    #   2. Else explicit opt-in present -> 0 (force-on, even in CI/enterprise)
+    #   3. Else enterprise/CI/air-gapped -> 1 (auto-off, safe out of the box)
+    #   4. Else (individual default)    -> 0 (on, anonymous diagnostics)
+    # All enabled paths still require curl (no egress tool -> off).
     local _telem_lower
     _telem_lower="$(printf '%s' "${LOKI_TELEMETRY:-}" | tr '[:upper:]' '[:lower:]')"
 
@@ -30,7 +103,7 @@ _loki_telemetry_enabled() {
         return 1
     fi
 
-    # --- 2. Opt-in required to enable ---
+    # --- 2. Explicit opt-in forces ON (overrides the enterprise/CI auto-off) ---
     if [ "$_telem_lower" = "on" ]; then
         command -v curl >/dev/null 2>&1 || return 1
         return 0
@@ -40,8 +113,12 @@ _loki_telemetry_enabled() {
         return 0
     fi
 
-    # --- 3. Default: OFF ---
-    return 1
+    # --- 3. Enterprise / CI / air-gapped: auto-off (safe out of the box) ---
+    _loki_telemetry_auto_off && return 1
+
+    # --- 4. Individual interactive default: ON (anonymous diagnostics) ---
+    command -v curl >/dev/null 2>&1 || return 1
+    return 0
 }
 
 _loki_telemetry_id() {

package/bin/loki

@@ -32,6 +32,21 @@ SCRIPT_DIR=$(dirname "$SCRIPT_PATH")
 REPO_ROOT=$(cd "$SCRIPT_DIR/.." 2>/dev/null && pwd)
 BASH_CLI="$REPO_ROOT/autonomy/loki"
 
+# v7.89.0 telemetry TTY fix (council cH_r1): resolve interactivity EXACTLY ONCE
+# here, while this shim still owns the user's real TTY, and export it as an
+# explicit signal. The telemetry gates (telemetry.sh / crash.sh / dashboard
+# telemetry.py) must NOT re-probe `-t` later: the gate is evaluated inside
+# subshells that redirect FDs (the `) </dev/null >/dev/null 2>&1` gate-check
+# subshells below), and the backgrounded emit subshell also detaches its FDs, so
+# a fresh `-t` probe there always sees non-TTY and would auto-off a REAL
+# interactive user (killing on-by-default + the disclosure). Set the var only
+# when a terminal is actually present at this entry point; leave it UNSET
+# otherwise so an isolated unit test that bypasses this entry point falls back to
+# the gate's own `-t` probe (documented precedence in the *_auto_off helpers).
+if [ -t 1 ] || [ -t 0 ]; then
+    export LOKI_TTY_INTERACTIVE=1
+fi
+
 # Resolve which Bun entry to use:
 #   1. LOKI_TS_ENTRY=...   -- explicit override (custom builds, tests)
 #   2. BUN_FROM_SOURCE=1   -- prefer src/cli.ts (used by bench --compare-dist
@@ -87,6 +102,42 @@ else
     exec "$BASH_CLI" "$@"
 fi
 
+# v7.88.1 covert-path fix (council cF_r2 + cG_r2 sentinel edge): under on-by-default
+# diagnostics, NO telemetry may egress before the user has seen a disclosure once.
+# The cmd_start welcome only shows on `loki start`, so a first `loki version`/`doctor`
+# would otherwise egress covertly. _loki_disclose_telemetry_once prints a one-time
+# disclosure to the user's REAL stderr the first time collection is ACTUALLY enabled
+# at egress time. It is keyed on its OWN marker (~/.loki/.telemetry-disclosed), NOT
+# the .loki-first-run sentinel: the sentinel edge is that a first run in CI/auto-off
+# sets .loki-first-run while suppressing disclosure, which must NOT permanently
+# silence the disclosure on a later interactive (enabled) run. Every enabled egress
+# path (installed + cli_command) calls this first, so whichever fires first discloses.
+#
+# v7.89.0 (council cH_r1 AC4): the helper now lives in autonomy/telemetry.sh as
+# the SINGLE shared impl for both routes (the bash route in autonomy/loki calls
+# the same function before its foreground egress, so the copy never drifts).
+# Source it here at top level just for this helper -- telemetry.sh executes
+# nothing on source beyond defining functions and two host/key vars, so this is
+# side-effect-free for the shim. If the source fails for any reason, define a
+# local fallback so on-by-default disclosure is never silently skipped.
+if [ -f "$REPO_ROOT/autonomy/telemetry.sh" ]; then
+    # shellcheck source=../autonomy/telemetry.sh
+    source "$REPO_ROOT/autonomy/telemetry.sh" 2>/dev/null || true
+fi
+if ! declare -f _loki_disclose_telemetry_once >/dev/null 2>&1; then
+_loki_disclose_telemetry_once() {
+    local _marker="${HOME}/.loki/.telemetry-disclosed"
+    [ -f "$_marker" ] 2>/dev/null && return 0
+    printf '%s\n' \
+      "Loki Mode sends anonymous diagnostics (os, arch, version, error type only --" \
+      "never your code, prompts, paths, or keys) to help fix bugs. Off in enterprise/" \
+      "CI/air-gapped setups. Turn it off anytime: loki telemetry off  (docs/PRIVACY.md)" >&2
+    mkdir -p "${HOME}/.loki" 2>/dev/null || return 0
+    : > "$_marker" 2>/dev/null || true
+    return 0
+}
+fi
+
 # v7.4.13: one-shot first-run telemetry, MOVED from autonomy/loki main()
 # into the shim because the 8 ported commands (version, status, doctor,
 # stats, provider, memory) bypass main() entirely -- only unported
@@ -96,13 +147,26 @@ fi
 if [ -z "${LOKI_TELEMETRY_DISABLED:-}" ] && [ "${DO_NOT_TRACK:-}" != "1" ] && [ ! -f "${HOME}/.loki-first-run" ] 2>/dev/null; then
     touch "${HOME}/.loki-first-run" 2>/dev/null || true
     if command -v curl &>/dev/null && [ -f "$REPO_ROOT/autonomy/telemetry.sh" ]; then
-        # Source telemetry helpers + fire installed event in background
-        # so the user does not pay latency on first invocation.
-        # Detach all three FDs so the backgrounded subshell never holds this
-        # shim's stdout/stderr/stdin open (v7.8.3: same fix as the cli_command
-        # emit below -- prevents a macOS broken-pipe in piped callers).
-        ( SCRIPT_DIR="$REPO_ROOT/autonomy"; source "$SCRIPT_DIR/telemetry.sh" 2>/dev/null && loki_telemetry "installed" "first_command=${1:-}" 2>/dev/null ) >/dev/null 2>&1 </dev/null &
-        disown 2>/dev/null || true
+        # Decide with the SAME gate the egress uses (_loki_telemetry_enabled), in a
+        # subshell so sourcing telemetry.sh cannot pollute the shim env.
+        # AC3: evaluate the GATE in the foreground (do NOT detach FDs here) so it
+        # inherits the real TTY / sees the exported LOKI_TTY_INTERACTIVE signal;
+        # only the network EMIT below is backgrounded with detached FDs. The
+        # sourced helper is silenced via 2>/dev/null and the gate writes nothing
+        # to stdout, so foreground evaluation adds no output.
+        if ( SCRIPT_DIR="$REPO_ROOT/autonomy"; source "$SCRIPT_DIR/telemetry.sh" 2>/dev/null \
+             && declare -f _loki_telemetry_enabled >/dev/null 2>&1 \
+             && _loki_telemetry_enabled ); then
+            # Disclosure BEFORE the installed egress -- see the shared
+            # _loki_disclose_telemetry_once helper below (keyed on its OWN
+            # disclosed-marker, NOT .loki-first-run, so a first run in CI that
+            # suppressed disclosure does not permanently silence it).
+            _loki_disclose_telemetry_once
+            # Fire-and-forget the installed event; detach all FDs (v7.8.3 broken-pipe fix).
+            ( SCRIPT_DIR="$REPO_ROOT/autonomy"; source "$SCRIPT_DIR/telemetry.sh" 2>/dev/null \
+              && loki_telemetry "installed" "first_command=${1:-}" 2>/dev/null ) >/dev/null 2>&1 </dev/null &
+            disown 2>/dev/null || true
+        fi
     fi
 fi
 
@@ -176,6 +240,15 @@ if [ "${1:-}" = "report" ]; then
     done
     if [ "$_report_first_sub" = "kpis" ]; then
         if command -v curl &>/dev/null && [ -f "$REPO_ROOT/autonomy/telemetry.sh" ]; then
+            # Disclose once before egress if collection is genuinely enabled
+            # (covers the case where a cli_command is the first ENABLED egress,
+            # e.g. first run was CI/auto-off so .loki-first-run is already set).
+            # AC3: foreground gate evaluation (no FD detach) so the exported
+            # LOKI_TTY_INTERACTIVE signal / real TTY drives the verdict.
+            if ( SCRIPT_DIR="$REPO_ROOT/autonomy"; source "$SCRIPT_DIR/telemetry.sh" 2>/dev/null \
+                 && declare -f _loki_telemetry_enabled >/dev/null 2>&1 && _loki_telemetry_enabled ); then
+                _loki_disclose_telemetry_once
+            fi
             ( SCRIPT_DIR="$REPO_ROOT/autonomy"; source "$SCRIPT_DIR/telemetry.sh" 2>/dev/null && loki_telemetry "cli_command" "command=${1:-}" 2>/dev/null ) >/dev/null 2>&1 </dev/null &
             disown 2>/dev/null || true
         fi
@@ -187,7 +260,7 @@ fi
 # Two-token routes (provider show/list, memory list/index) match on the first
 # token only; the Bun dispatcher handles subcommand routing internally.
 case "${1:-}" in
-    version|--version|-v|status|stats|doctor|provider|memory|rollback|internal|kpis|trust|proof|wiki|crash)
+    version|--version|-v|status|stats|doctor|provider|memory|rollback|internal|kpis|trust|proof|receipt|wiki|crash)
         # v7.5.2: rollback added (wires loki-ts/src/commands/rollback.ts).
         # v7.5.3: internal added for autonomy/run.sh phase1-hooks calls.
         # v7.5.28: kpis added (Phase K MVP: read-only KPI snapshot).
@@ -210,6 +283,14 @@ case "${1:-}" in
             # stdout/stderr/stdin open. Without this, the lingering FD changed
             # pipe-teardown timing and produced a macOS-only broken-pipe in the
             # shim-route CLI test harness (v7.8.2 -> fixed v7.8.3).
+            # Disclose once before egress if collection is genuinely enabled
+            # (first ENABLED egress may be a cli_command, not installed).
+            # AC3: foreground gate evaluation (no FD detach) so the exported
+            # LOKI_TTY_INTERACTIVE signal / real TTY drives the verdict.
+            if ( SCRIPT_DIR="$REPO_ROOT/autonomy"; source "$SCRIPT_DIR/telemetry.sh" 2>/dev/null \
+                 && declare -f _loki_telemetry_enabled >/dev/null 2>&1 && _loki_telemetry_enabled ); then
+                _loki_disclose_telemetry_once
+            fi
             ( SCRIPT_DIR="$REPO_ROOT/autonomy"; source "$SCRIPT_DIR/telemetry.sh" 2>/dev/null && loki_telemetry "cli_command" "command=${1:-}" 2>/dev/null ) >/dev/null 2>&1 </dev/null &
             disown 2>/dev/null || true
         fi

package/dashboard/__init__.py

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

package/dashboard/server.py

@@ -10190,6 +10190,219 @@ async def get_proof_html(run_id: str):
     return FileResponse(str(index_html), media_type="text/html")
 
 
+# ---------------------------------------------------------------------------
+# Active spec + spec history.
+#
+# Gives the dashboard honest visibility into WHAT Loki is building from. The
+# resolution order mirrors proof-generator.py::_collect_spec so the panel and
+# the Evidence Receipt can never disagree about the spec source:
+#   1. PRD file  -> session.json prdPath (only when the file still exists)
+#   2. one-line brief -> .loki/state/brief.txt
+#   3. generated PRD  -> .loki/generated-prd.md
+#   4. no spec        -> codebase-analysis
+# Issue mode is detected from the latest proof.json's spec.source (a GitHub
+# issue URL): issue runs re-dispatch through cmd_run, which synthesizes a PRD,
+# so at runtime they look like a generated-prd; the proof carries the real
+# issue ref. We never fabricate a type -- when nothing is resolvable we say so.
+#
+# History is derived from the proofs the Evidence Receipt already writes
+# (.loki/proofs/<run_id>/proof.json), newest-first. No new store is invented.
+# ---------------------------------------------------------------------------
+# Cap on the spec body returned to the dashboard so a huge PRD cannot bloat the
+# payload. The panel shows a preview; the full file lives on disk.
+_SPEC_CONTENT_CAP = 20000
+# Issue URLs (mirrors autonomy/loki's issue-mode detection regex). Matches a
+# tracker host followed somewhere by an /issue(s)/ path or a Jira /browse/ key.
+_ISSUE_URL_RE = re.compile(
+    r"(github\.com|gitlab\.com|atlassian\.net|dev\.azure\.com|"
+    r"visualstudio\.com)/.*\b(issues?|browse)/", re.IGNORECASE)
+
+
+def _spec_source_is_issue(source: str) -> bool:
+    """True when a proof spec.source string is a tracker issue reference."""
+    if not source:
+        return False
+    return bool(_ISSUE_URL_RE.search(source))
+
+
+def _latest_proof(proofs_dir: _Path) -> Optional[dict]:
+    """Return the newest proof.json dict for the active project, or None."""
+    try:
+        entries = sorted(proofs_dir.iterdir())
+    except (OSError, FileNotFoundError):
+        return None
+    newest = None
+    newest_key = ""
+    for entry in entries:
+        if not entry.is_dir():
+            continue
+        proof_json = entry / "proof.json"
+        if not proof_json.is_file():
+            continue
+        data = _safe_json_read(proof_json, default=None)
+        if not isinstance(data, dict):
+            continue
+        key = data.get("generated_at") or entry.name
+        if newest is None or key >= newest_key:
+            newest = data
+            newest_key = key
+    return newest
+
+
+def _spec_summary(source: str, brief: str) -> str:
+    """One-line summary for a history row, derived honestly from the spec.
+
+    Prefers the first non-empty line of the brief; falls back to the source
+    basename. Never fabricates -- returns an honest label when nothing exists.
+    """
+    if brief:
+        for line in brief.splitlines():
+            line = line.strip().lstrip("#").strip()
+            if line:
+                return line[:160]
+    if source in ("brief", "codebase-analysis", "", None):
+        return {"brief": "one-line brief",
+                "codebase-analysis": "Codebase analysis (no spec)"}.get(
+                    source, "Unknown spec")
+    if _spec_source_is_issue(source):
+        return source
+    return os.path.basename(source) or source
+
+
+def _classify_proof_spec(spec: dict) -> str:
+    """Map a proof.json spec dict to a dashboard spec type, honestly."""
+    if not isinstance(spec, dict):
+        return "unknown"
+    source = (spec.get("source") or "").strip()
+    if _spec_source_is_issue(source):
+        return "issue"
+    if source == "brief":
+        return "brief"
+    if source == "codebase-analysis":
+        return "codebase-analysis"
+    if not source:
+        return "unknown"
+    # A real filesystem path (PRD or generated PRD). A synthesized PRD lives at
+    # .loki/generated-prd.md or .loki/brief-prd-*.md; anything else is a user
+    # PRD. We report the broad "spec" type and the path so the UI can show it.
+    return "spec"
+
+
+@app.get("/api/spec", dependencies=[Depends(auth.require_scope("read"))])
+async def get_active_spec():
+    """Return the current run's spec source + content, honestly typed.
+
+    Types: prd | brief | spec | issue | codebase-analysis | none. The `none`
+    state is the honest empty state when no run has produced a spec yet. We
+    never invent a spec: each branch reads a real file or says it cannot.
+    """
+    loki_dir = _get_loki_dir()
+
+    # 1. PRD file recorded by the running orchestrator (session.json prdPath).
+    #    Only trust it when the file still exists on disk.
+    session = _safe_json_read(loki_dir / "session.json", default=None)
+    prd_path = ""
+    if isinstance(session, dict):
+        prd_path = (session.get("prdPath") or "").strip()
+    if prd_path:
+        p = _Path(prd_path)
+        if p.is_file():
+            content = _safe_read_text(p)
+            return {
+                "type": "prd",
+                "path": str(p),
+                "content": content[:_SPEC_CONTENT_CAP],
+                "truncated": len(content) > _SPEC_CONTENT_CAP,
+            }
+
+    # 2. one-line brief (zero-config first run). The raw brief is the strongest
+    #    honest artifact -- show it verbatim.
+    brief_file = loki_dir / "state" / "brief.txt"
+    if brief_file.is_file():
+        text = _safe_read_text(brief_file).strip()
+        if text:
+            return {"type": "brief", "text": text[:_SPEC_CONTENT_CAP],
+                    "truncated": len(text) > _SPEC_CONTENT_CAP}
+
+    # 3. Issue mode: a brief/PRD run that originated from a tracker issue. The
+    #    runtime has only the synthesized PRD, but the latest proof.json carries
+    #    the real issue ref + brief. Surface it as an issue when we can prove it.
+    latest = _latest_proof(loki_dir / "proofs")
+    if isinstance(latest, dict):
+        pspec = latest.get("spec")
+        if isinstance(pspec, dict):
+            src = (pspec.get("source") or "").strip()
+            if _spec_source_is_issue(src):
+                pbrief = (pspec.get("brief") or "").strip()
+                return {
+                    "type": "issue",
+                    "ref": src,
+                    "title": _spec_summary(src, pbrief),
+                    "body": pbrief[:_SPEC_CONTENT_CAP],
+                    "truncated": len(pbrief) > _SPEC_CONTENT_CAP,
+                }
+
+    # 4. Generated PRD (synthesized from a brief, or from codebase analysis).
+    for name in ("generated-prd.md",):
+        gen = loki_dir / name
+        if gen.is_file():
+            content = _safe_read_text(gen)
+            if content.strip():
+                return {
+                    "type": "spec",
+                    "path": str(gen),
+                    "content": content[:_SPEC_CONTENT_CAP],
+                    "truncated": len(content) > _SPEC_CONTENT_CAP,
+                    "generated": True,
+                }
+
+    # 5. Codebase analysis (no explicit spec) -- only claim this when a run has
+    #    actually happened (a session or a proof exists). Otherwise honest none.
+    has_session = isinstance(session, dict) and bool(session)
+    if has_session or latest is not None:
+        return {"type": "codebase-analysis"}
+
+    # 6. Nothing yet -- honest empty state, not a fabricated spec.
+    return {"type": "none"}
+
+
+@app.get("/api/spec/history", dependencies=[Depends(auth.require_scope("read"))])
+async def get_spec_history():
+    """Return past specs/issues/briefs for this codebase, newest-first.
+
+    Derived from the Evidence Receipts (.loki/proofs/<run_id>/proof.json) that
+    every run already writes; no separate spec store is invented. Each row:
+    {when, type, summary, run_id}. Missing/corrupt proofs are skipped, never
+    faked. Empty -> {"history": []} (honest empty state).
+    """
+    proofs_dir = _get_loki_dir() / "proofs"
+    rows: list[dict] = []
+    try:
+        entries = sorted(proofs_dir.iterdir())
+    except (OSError, FileNotFoundError):
+        return {"history": []}
+    for entry in entries:
+        if not entry.is_dir():
+            continue
+        proof_json = entry / "proof.json"
+        if not proof_json.is_file():
+            continue
+        data = _safe_json_read(proof_json, default=None)
+        if not isinstance(data, dict):
+            continue
+        spec = data.get("spec")
+        spec = spec if isinstance(spec, dict) else {}
+        source = (spec.get("source") or "").strip()
+        rows.append({
+            "run_id": data.get("run_id", entry.name),
+            "when": data.get("generated_at"),
+            "type": _classify_proof_spec(spec),
+            "summary": _spec_summary(source, (spec.get("brief") or "").strip()),
+        })
+    rows.sort(key=lambda x: (x.get("when") or ""), reverse=True)
+    return {"history": rows}
+
+
 # ---------------------------------------------------------------------------
 # R5: Auto-wiki + cited codebase Q&A (Loki's DeepWiki).
 #