loki-mode 11.7.1 → 11.9.1

package/autonomy/loki

@@ -2703,13 +2703,14 @@ cmd_start() {
                 echo "  --log-level LEVEL     debug | info | warn | error (default: info)"
                 echo "  --max-duration DUR    Wall-clock cap: seconds, or 90m / 2h (default: none)"
                 echo ""
-                echo "Issue-mode options (only used when input is an ISSUE-REF):"
+                echo "Issue-mode options (used when input is an ISSUE-REF or a --brief):"
                 echo "  --dry-run             Preview generated PRD without starting"
                 echo "  --no-start            Generate PRD but don't start execution"
                 echo "  --output FILE         Save generated PRD to custom path"
                 echo "  --worktree, -w        Git worktree isolation (separate branch)"
                 echo "  --pr                  Worktree + auto-create PR"
                 echo "  --ship                Worktree + PR + auto-merge"
+                echo "  --detach, -d          Run in background (implies --worktree)"
                 echo ""
                 echo "Preview without spending (any input mode):"
                 echo "  loki plan <PRD>       Analyze a spec WITHOUT executing: complexity,"
@@ -3443,6 +3444,24 @@ cmd_start() {
         return $?
     fi
 
+    # BRIEF + isolation flags (--pr/--worktree/--detach/--prepare-pr/--ship):
+    # the flags were collected above but only the issue path consumed them, so a
+    # delegated brief ran in the caller's checkout with no PR. Route it through
+    # cmd_run (worktree, detach, receipt-bearing PR) as a tracker-less issue.
+    if [ "$detected_type" = "brief" ] && [ "$issue_use_worktree" = "true" ]; then
+        local brief_run_args=("--brief-text" "$brief_text")
+        for a in "${issue_mode_args[@]+"${issue_mode_args[@]}"}"; do
+            brief_run_args+=("$a")
+        done
+        for a in "${args[@]+"${args[@]}"}"; do
+            brief_run_args+=("$a")
+        done
+        brief_run_args+=("--no-plan")
+        export LOKI_UNIFIED_START=1
+        cmd_run "${brief_run_args[@]}"
+        return $?
+    fi
+
     # R7 (zero-config first run): BRIEF mode. The user gave a one-line brief
     # (`loki start "build a todo app"` or `loki start --brief "..."`). Synthesize
     # a forward-looking PRD, switch to the lightweight TTFV profile (honest fast:
@@ -9751,7 +9770,11 @@ _deploy_latest_receipt() {
     return 0
 }
 
-# _deploy_record <dir> <command> <exit_code> <run_id> <anchor_sha>
+# _deploy_record <dir> <command> <exit_code> <run_id> <anchor_sha> [state] [health_status] [health_url] [rb_attempted] [rb_exit] [receipt_sha256] [started_at] [finished_at] [target] [canary]
+# Writes the executed deploy's own record, then signs it (loki.deploy/1, Ed25519 via the
+# receipt signer in loki-ts/src/util/receipt_signer.ts) so it is bound to the receipt that
+# authorized it; `loki verify <record>` re-checks it offline. An unsigned record is reported
+# loudly and verifies as UNCHECKED, never VERIFIED.
 # Writes the executed deploy's own record. A deploy with no record of itself
 # defeats the entire premise of gating on evidence.
 #
@@ -9769,17 +9792,27 @@ _deploy_record() {
     # Post-deploy health and rollback facts. "unchecked" never implies healthy.
     local health_status="${7:-unchecked}" health_url="${8:-}"
     local rb_attempted="${9:-false}" rb_exit="${10:-}"
+    local receipt_sha="${11:-}" started_at="${12:-}" finished_at="${13:-}" target="${14:-}" canary="${15:-false}"
     local ddir="$dir/.loki/deploys"
     [ -d "${LOKI_DIR:-}" ] && ddir="${LOKI_DIR}/deploys"
     mkdir -p "$ddir" 2>/dev/null || return 0
     local f="$ddir/$(date -u +%Y%m%dT%H%M%SZ)-$$.json"
     DR_CMD="$command" DR_RC="$rc" DR_RUN="$run_id" DR_ANCHOR="$anchor" DR_OUT="$f" \
     DR_STATE="$anchor_state" DR_HS="$health_status" DR_HU="$health_url" \
-    DR_RBA="$rb_attempted" DR_RBX="$rb_exit" \
+    DR_RBA="$rb_attempted" DR_RBX="$rb_exit" DR_RSHA="$receipt_sha" DR_T0="$started_at" \
+    DR_T1="$finished_at" DR_TGT="$target" DR_CAN="$canary" \
         python3 -c '
 import json, os, datetime
 state = os.environ.get("DR_STATE") or "anchored"
+now = datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
 json.dump({
+    "schema": "loki.deploy/1",
+    "receipt_sha256": os.environ.get("DR_RSHA", ""),
+    "head_sha": os.environ["DR_ANCHOR"],
+    "target": os.environ.get("DR_TGT", ""),
+    "started_at": os.environ.get("DR_T0") or now,
+    "finished_at": os.environ.get("DR_T1") or now,
+    "canary": os.environ.get("DR_CAN") == "true",
     "recorded_at": datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
     "command": os.environ["DR_CMD"],
     "exit_code": int(os.environ["DR_RC"]),
@@ -9795,6 +9828,10 @@ json.dump({
     "rollback_exit": int(os.environ["DR_RBX"]) if os.environ.get("DR_RBX", "") != "" else None,
 }, open(os.environ["DR_OUT"], "w"), indent=2)
 ' 2>/dev/null || return 0
+    # Sign through the one Bun implementation. A subshell, because the delegate execs.
+    if ! ( _loki_bun_delegate engine10 verify --sign-deploy "$f" ) >/dev/null 2>&1; then
+        echo -e "${YELLOW}WARNING: the deploy record is UNSIGNED (no signing key or Bun route); it verifies as UNCHECKED.${NC}" >&2
+    fi
     printf '%s' "$f"
     return 0
 }
@@ -9946,6 +9983,20 @@ _deploy_try_execute() {
         return 1
     fi
 
+    # --canary uses only documented staged verbs; anything else refuses, naming why.
+    local canary="${_LOKI_DEPLOY_CANARY:-false}" exec_cmd="$command" canary_kind=""
+    if [ "$canary" = true ]; then
+        case "$command" in
+            "vercel --prod") canary_kind="vercel"; exec_cmd="vercel" ;;
+            "fly deploy") canary_kind="fly"; exec_cmd="fly deploy --strategy canary" ;;
+            *)
+                echo -e "${RED}REFUSED: --canary is not supported for: ${command}${NC}" >&2
+                echo "  This provider documents no staged rollout verb (Vercel: deploy then 'vercel promote'; Fly: 'fly deploy --strategy canary'). Nothing was run." >&2
+                return 1
+                ;;
+        esac
+    fi
+
     local reasons
     reasons="$(_deploy_gate "$dir" "$command")"
 
@@ -10002,7 +10053,7 @@ _deploy_try_execute() {
     else
         echo -e "${GREEN}Evidence gate PASSED.${NC} Receipt ${run_id:-unknown} VERIFIED this tree (${anchor:0:12})."
     fi
-    echo "Running: ${command}"
+    if [ "$canary" = true ]; then echo "Running (canary): ${exec_cmd}"; else echo "Running: ${command}"; fi
     echo ""
 
     # Run in the project dir. No credential env var is read, set, or forwarded:
@@ -10032,13 +10083,40 @@ _deploy_try_execute() {
         esac
     fi
 
-    local rc=0
-    ( cd "$dir" && eval "$command" ) || rc=$?
+    local rc=0 started_at finished_at purl="" canary_out=""
+    started_at="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+    local health_status="unchecked" rb_attempted=false rb_exit="" hcode=""
+    if [ "$canary_kind" = vercel ]; then
+        # Staged: a preview deploy (no --prod), probe the preview URL, promote only if healthy.
+        # Nothing reaches production before the probe, so there is nothing to roll back.
+        rb_cmd=""; auto_rollback=false
+        exec_cmd="vercel"
+        canary_out="$( cd "$dir" && eval "$exec_cmd" )" || rc=$?
+        printf '%s\n' "$canary_out"
+        purl="$(grep -Eo 'https?://[^[:space:]]+' <<<"$canary_out" | tail -n 1)"
+        if [ "$rc" -eq 0 ] && [ -n "$purl" ]; then
+            health_url="$purl"
+            echo "Probing canary health: ${health_url}"
+            if hcode="$(_deploy_probe_health "$health_url")"; then
+                health_status="healthy"
+                echo "Promoting: vercel promote ${purl}"
+                exec_cmd="vercel; vercel promote ${purl}"
+                ( cd "$dir" && vercel promote "$purl" ) || rc=$?
+            else
+                health_status="FAILED_HEALTH"
+                echo "  The canary was NOT promoted. Production is unchanged." >&2
+            fi
+        elif [ "$rc" -eq 0 ]; then
+            echo "  The preview deploy printed no URL, so it cannot be health-checked and is NOT promoted." >&2
+            rc=4
+        fi
+    else
+        ( cd "$dir" && eval "$exec_cmd" ) || rc=$?
+    fi
 
     # Health probe only after a deploy that exited 0. Without a URL, or after a
     # failed deploy, status is "unchecked": never a claim the service is healthy.
-    local health_status="unchecked" rb_attempted=false rb_exit="" hcode=""
-    if [ "$rc" -eq 0 ] && [ -n "$health_url" ]; then
+    if [ "$canary_kind" != vercel ] && [ "$rc" -eq 0 ] && [ -n "$health_url" ]; then
         echo "Probing health: ${health_url}"
         if hcode="$(_deploy_probe_health "$health_url")"; then
             health_status="healthy"
@@ -10066,9 +10144,12 @@ _deploy_try_execute() {
         fi
     fi
 
-    local rec
-    rec="$(_deploy_record "$dir" "$command" "$rc" "${run_id:-unknown}" "${anchor:-unknown}" \
-        "$anchor_state" "$health_status" "$health_url" "$rb_attempted" "$rb_exit")"
+    local rec rsha
+    finished_at="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+    rsha="$(python3 -c 'import json,sys;print((json.load(open(sys.argv[1])).get("verification") or {}).get("hash") or "")' "$pj" 2>/dev/null || printf '')"
+    rec="$(_deploy_record "$dir" "$exec_cmd" "$rc" "${run_id:-unknown}" "${anchor:-unknown}" \
+        "$anchor_state" "$health_status" "$health_url" "$rb_attempted" "$rb_exit" \
+        "$rsha" "$started_at" "$finished_at" "${command%% *}" "$canary")"
     echo ""
     if [ "$rc" -eq 0 ]; then
         echo -e "${GREEN}Deploy command exited 0.${NC}"
@@ -10208,7 +10289,7 @@ cmd_deploy() {
     # file alone weakens this gate.
     local LOKI_DEPLOY_ALLOW_UNANCHORED=false
     # Per-invocation like --execute; local so an ambient env var cannot set them.
-    local _LOKI_DEPLOY_HEALTH_URL="" _LOKI_DEPLOY_AUTO_ROLLBACK=false
+    local _LOKI_DEPLOY_HEALTH_URL="" _LOKI_DEPLOY_AUTO_ROLLBACK=false _LOKI_DEPLOY_CANARY=false
 
     # Arg parse (mirror cmd_preview: lenient on unknown args -> no behavior drift).
     while [ $# -gt 0 ]; do
@@ -10216,7 +10297,7 @@ cmd_deploy() {
             --help|-h|help)
                 echo -e "${BOLD}Loki Mode -- deploy command advisory (print-only by default)${NC}"
                 echo ""
-                echo "Usage: loki deploy [--dir <path>] [--no-clip] [--execute] [--health-url URL [--auto-rollback]]"
+                echo "Usage: loki deploy [--dir <path>] [--no-clip] [--execute [--canary]] [--health-url URL [--auto-rollback]]"
                 echo ""
                 echo "Detects your project type and your installed cloud CLI (and any"
                 echo "CI/CD pipeline), then PRINTS the exact deploy command for YOU to run."
@@ -10283,6 +10364,18 @@ cmd_deploy() {
                 echo "                    print a manual note. Needs --health-url. The rolled-back"
                 echo "                    service is not re-probed."
                 echo ""
+                echo "Staged rollout (only with --execute):"
+                echo "  --canary          Vercel: deploy without --prod, health-check the preview"
+                echo "                    URL, then run 'vercel promote <url>'; a failed probe never"
+                echo "                    promotes. Fly: 'fly deploy --strategy canary'. Other"
+                echo "                    providers document no staged path and refuse --canary."
+                echo ""
+                echo "The executed deploy's record in .loki/deploys/ is a signed loki.deploy/1"
+                echo "attestation bound to the receipt (receipt_sha256). Re-check it offline with"
+                echo "'loki verify <record.json>' (add --pubkey FILE to use a given key). It fails"
+                echo "closed: a tampered, unsigned or unkeyed record, or a cited receipt that is not"
+                echo "VERIFIED, is never reported as VERIFIED."
+                echo ""
                 echo "Options:"
                 echo "  --dir <path>   Project directory to scan (default: current dir)"
                 echo "  --no-clip      Do not copy the idiomatic command to the clipboard"
@@ -10311,6 +10404,9 @@ cmd_deploy() {
             --auto-rollback)
                 _LOKI_DEPLOY_AUTO_ROLLBACK=true
                 ;;
+            --canary)
+                _LOKI_DEPLOY_CANARY=true
+                ;;
             --dir)
                 # Guard against a missing OR flag-shaped value: an unguarded
                 # shift when --dir is the last arg underflows under set -e, and a
@@ -10332,6 +10428,10 @@ cmd_deploy() {
         echo "loki deploy --auto-rollback requires --health-url (no health signal, no rollback)" >&2
         return 1
     fi
+    if [ "$_LOKI_DEPLOY_CANARY" = true ] && [ "$do_execute" != true ]; then
+        echo "loki deploy --canary requires --execute" >&2
+        return 1
+    fi
     if [ "$do_execute" != true ] && [ -n "$_LOKI_DEPLOY_HEALTH_URL" ]; then
         echo "Note: --health-url and --auto-rollback only apply with --execute; ignored on this advisory run." >&2
     fi
@@ -10939,6 +11039,10 @@ cmd_run() {
     local prepare_pr=false
     local auto_merge=false
     local run_detached=false
+    # Internal: set by cmd_start when a one-line brief carries --pr/--worktree/
+    # --detach. The brief is treated as a tracker-less issue so it reuses the
+    # worktree, detach and PR machinery below instead of a parallel copy.
+    local brief_in=""
 
     # Parse arguments
     while [[ $# -gt 0 ]]; do
@@ -11128,6 +11232,15 @@ cmd_run() {
             --config=*|--vars=*|--env-file=*)
                 shift
                 ;;
+            --brief-text)
+                if [ "$#" -ge 2 ]; then
+                    brief_in="$2"
+                    shift 2
+                else
+                    echo -e "${RED}--brief-text requires text${NC}"
+                    exit 1
+                fi
+                ;;
             -*)
                 echo -e "${RED}Unknown option: $1${NC}"
                 echo "Run 'loki run --help' for usage."
@@ -11163,6 +11276,10 @@ cmd_run() {
         start_args+=("--parallel")
     fi
 
+    if [[ -n "$brief_in" ]]; then
+        issue_ref="brief"
+    fi
+
     if [[ -z "$issue_ref" ]]; then
         echo -e "${RED}Error: Issue reference required${NC}"
         echo ""
@@ -11202,16 +11319,33 @@ cmd_run() {
 
     # Detect provider
     local issue_provider
-    issue_provider=$(detect_issue_provider "$issue_ref")
-    echo -e "${CYAN}Issue provider:${NC} ${issue_provider}"
-
-    # Fetch the issue
-    echo -e "${CYAN}Fetching issue...${NC}"
     local issue_json
-    issue_json=$(fetch_issue "$issue_ref") || {
-        echo -e "${RED}Failed to fetch issue${NC}"
-        exit 1
-    }
+    if [[ -n "$brief_in" ]]; then
+        # Brief: no tracker to fetch from. The text travels in env so quoting in
+        # the brief can never reach the shell or python source.
+        issue_provider="brief"
+        echo -e "${CYAN}Source:${NC} one-line brief"
+        issue_json=$(LOKI_BRIEF_IN="$brief_in" LOKI_BRIEF_TS="$(date +%s)" python3 -c "
+import json, os
+t = os.environ['LOKI_BRIEF_IN']
+first = t.strip().splitlines()[0] if t.strip() else 'brief'
+print(json.dumps({'provider': 'brief', 'number': 'b' + os.environ['LOKI_BRIEF_TS'],
+    'title': first[:80], 'body': t, 'labels': [], 'url': '', 'repo': ''}))
+") || {
+            echo -e "${RED}Failed to build brief${NC}"
+            exit 1
+        }
+    else
+        issue_provider=$(detect_issue_provider "$issue_ref")
+        echo -e "${CYAN}Issue provider:${NC} ${issue_provider}"
+
+        # Fetch the issue
+        echo -e "${CYAN}Fetching issue...${NC}"
+        issue_json=$(fetch_issue "$issue_ref") || {
+            echo -e "${RED}Failed to fetch issue${NC}"
+            exit 1
+        }
+    fi
 
     # Extract fields for display
     local title number url
@@ -11557,7 +11691,7 @@ ${_gh_receipt}"
             fi
 
             case "${issue_provider:-github}" in
-                github)
+                github|brief)
                     if command -v gh &>/dev/null; then
                         local branch_current
                         branch_current=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "")
@@ -11609,7 +11743,7 @@ ${_gh_receipt}"
                     branch_current=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "")
                     if gh pr merge "$branch_current" --squash --delete-branch 2>/dev/null; then
                         echo -e "${GREEN}PR merged and branch deleted${NC}"
-                        if [[ -n "${number:-}" ]]; then
+                        if [[ "${number:-}" =~ ^[0-9]+$ ]]; then
                             gh issue close "$number" --comment "Resolved by Loki Mode" 2>/dev/null || true
                         fi
                     else
@@ -18134,9 +18268,15 @@ cmd_verify() {
     # verified by the engine10 verifier directly; bin/loki sends a bare verify back here.
     for _pk_arg in "$@"; do
         case "$_pk_arg" in
-            composite.json|*/composite.json|--seal-composite|--seal-composite=*)
+            --sign-deploy|--receipt|composite.json|*/composite.json|--seal-composite|--seal-composite=*|--max-age|--max-age=*|.loki/groups/*/receipt.json|*/.loki/groups/*/receipt.json)
                 _loki_bun_delegate engine10 verify "$@"
                 return $? ;;
+            # A signed deploy record (.loki/deploys/*.json, schema loki.deploy/1) is re-checked by the same verifier.
+            *.json)
+                if [ -f "$_pk_arg" ] && grep -q 'loki\.deploy/1' "$_pk_arg" 2>/dev/null; then
+                    _loki_bun_delegate engine10 verify "$@"
+                    return $?
+                fi ;;
         esac
     done
     # --fast: deterministic checks only, in milliseconds. Measured on this repo
@@ -28012,93 +28152,32 @@ cmd_trust_metrics() {
     python3 "$tm_mod" --loki-dir "$loki_dir" ${pass_args[@]+"${pass_args[@]}"}
 }
 
-# Transparent cost view (R3): per-run + per-project spend, model routing, and
-# budget status with the 80% warn line. Reuses efficiency_cost.collect_efficiency
-# for the current-run aggregate (single source of truth) and reads .loki/proofs/
-# for persistent per-run history. Honest: prints "not recorded" when cost was
-# never collected, never a fabricated $0.00.
-# Forward cost projection. Wraps tools/estimate-run.py.
-#
-# --iterations is REQUIRED by that tool by design: no multi-run history exists
-# to derive a horizon from, so projecting a total without one would be guessing
-# at the single number the operator asked for. We surface that requirement here
-# rather than inventing a default, for the same reason cost reports UNKNOWN
-# instead of $0.00 -- an unearned number is worse than an absent one.
+# loki estimate: one estimator. The estimate is loki-ts/src/runner/router/cost_preview.ts,
+# the same one 'loki start' prints; this arm only hands off to the Bun CLI (bin/loki is the
+# normal route; this covers 'loki help estimate' and a direct bash invocation). tools/estimate-run.py
+# stays for its other callers (preflight, model-advisor) but is no longer reachable from here.
 cmd_estimate() {
-    local iterations=""
-    local show_json=false
-
-    while [[ $# -gt 0 ]]; do
-        case "$1" in
-            --help|-h)
-                echo -e "${BOLD}loki estimate${NC} - Project what a run is likely to cost"
-                echo ""
-                echo "Usage: loki estimate --iterations N [--json]"
-                echo ""
-                echo "Projects a run cost from this workspace's MEASURED history in"
-                echo ".loki/metrics/efficiency/. With no measured history there is no"
-                echo "basis, and it says so rather than returning a fabricated number."
-                echo ""
-                echo "Options:"
-                echo "  --iterations N       REQUIRED. How many iterations to project."
-                echo "                       No multi-run history exists to derive a horizon"
-                echo "                       from, so there is no honest default."
-                echo "  --json               Machine-readable JSON output"
-                echo "  --help, -h           Show this help"
-                echo ""
-                echo "Examples:"
-                echo "  loki estimate --iterations 10"
-                echo "  loki estimate --iterations 25 --json"
-                echo ""
-                echo "See also: loki cost --detail (what a run ALREADY spent)"
-                return 0
-                ;;
-            --json) show_json=true; shift ;;
-            --iterations) iterations="${2:-}"; shift 2 || shift ;;
-            --iterations=*) iterations="${1#*=}"; shift ;;
-            *) echo -e "${RED}Unknown option: $1${NC}" >&2; echo "Run 'loki estimate --help' for usage." >&2; return 1 ;;
-        esac
-    done
-
-    if [ -z "$iterations" ]; then
-        echo -e "${RED}--iterations is required${NC}" >&2
-        echo "" >&2
-        echo "No multi-run history exists to derive a horizon from, so there is no" >&2
-        echo "honest default for how many iterations to project. Say how many you" >&2
-        echo "expect and the projection is scaled from measured per-iteration cost." >&2
-        echo "" >&2
-        echo "  loki estimate --iterations 10" >&2
-        echo "" >&2
-        echo "Run 'loki estimate --help' for usage." >&2
-        return 1
-    fi
-
-    case "$iterations" in
-        ''|*[!0-9]*)
-            echo -e "${RED}--iterations must be a positive whole number (got: $iterations)${NC}" >&2
-            return 1
-            ;;
-    esac
-
-    local estimate_py="$SKILL_DIR/tools/estimate-run.py"
-    if ! command -v python3 >/dev/null 2>&1; then
-        echo -e "${RED}python3 is required for 'loki estimate'${NC}" >&2
-        echo "Install python3 and re-run." >&2
-        return 1
+    local entry="${LOKI_TS_ENTRY:-}"
+    if [ -z "$entry" ]; then
+        if [ -f "$SKILL_DIR/loki-ts/dist/loki.js" ]; then
+            entry="$SKILL_DIR/loki-ts/dist/loki.js"
+        elif [ -f "$SKILL_DIR/loki-ts/src/cli.ts" ]; then
+            entry="$SKILL_DIR/loki-ts/src/cli.ts"
+        fi
     fi
-    if [ ! -f "$estimate_py" ]; then
-        echo -e "${RED}Estimate tool not found: $estimate_py${NC}" >&2
-        echo "Your install looks incomplete. Reinstall: loki self-update" >&2
+    if [ -z "$entry" ] || [ ! -f "$entry" ] || ! command -v bun >/dev/null 2>&1; then
+        echo -e "${RED}loki estimate requires the Bun runtime and is not available on the bash route.${NC}" >&2
+        echo "Install Bun (https://bun.sh) or remove LOKI_LEGACY_BASH=1." >&2
         return 1
     fi
-
-    # Same workspace derivation as 'loki cost --detail': the tool takes the
-    # workspace and appends .loki itself, while LOKI_DIR is the .loki path.
-    local est_args=("$(dirname "${LOKI_DIR:-.loki}")" "--iterations" "$iterations")
-    [ "$show_json" = "true" ] && est_args+=("--json")
-    python3 "$estimate_py" "${est_args[@]}"
+    bun "$entry" estimate "$@"
 }
 
+# Transparent cost view (R3): per-run + per-project spend, model routing, and
+# budget status with the 80% warn line. Reuses efficiency_cost.collect_efficiency
+# for the current-run aggregate (single source of truth) and reads .loki/proofs/
+# for persistent per-run history. Honest: prints "not recorded" when cost was
+# never collected, never a fabricated $0.00.
 cmd_cost() {
     local show_json=false
     local last_n=0