loki-mode 11.17.1 → 11.17.6

package/autonomy/loki

@@ -134,15 +134,15 @@ _loki_caveman_narration_level() {
 
 # P12-26b: permission flags for the migrate/doc/heal claude launches. Lazily sources
 # claude-flags.sh (like the caveman wrapper above) and fills _LOKI_PERM_ARGV; unset
-# LOKI_PERMISSION_POLICY keeps --dangerously-skip-permissions byte-identically.
+# LOKI_PERMISSION_POLICY=legacy keeps --dangerously-skip-permissions byte-identically.
 _loki_perm_argv_for() {
     _LOKI_PERM_ARGV=(--dangerously-skip-permissions)
-    # Unset policy: return before sourcing anything (claude-flags.sh exports caveman vars).
-    [ "${LOKI_PERMISSION_POLICY:-}" = "compiled" ] || return 0
+    # Legacy policy: return before sourcing anything (claude-flags.sh exports caveman vars).
+    [ "${LOKI_PERMISSION_POLICY:-}" = "legacy" ] && return 0
     _LOKI_PERM_ARGV=(--permission-mode plan)
     local _pa_lib="${_LOKI_SCRIPT_DIR}/lib/claude-flags.sh" _pa_out _pa_a
     if [ ! -f "$_pa_lib" ]; then
-        echo "[loki] WARNING: LOKI_PERMISSION_POLICY=compiled: helper missing; using most restrictive mode (plan)" >&2
+        echo "[loki] WARNING: compiled permission policy: helper missing; using most restrictive mode (plan)" >&2
         return 0
     fi
     # Subshell so the helper's top-level exports never leak into this shell.
@@ -1825,6 +1825,7 @@ show_help_all() {
     echo "  stop             Stop execution immediately"
     echo "  pause            Pause after current session"
     echo "  resume           Resume a paused or interrupted run (after Ctrl-C or a crash)"
+    echo "  cancel           Cancel the active Loki 10 run at its next stage boundary"
     echo "  steer \"<note>\"    Nudge a running build (Loki 10 engine; legacy loop needs LOKI_PROMPT_INJECTION=true)"
     echo ""
     echo "Verify / trust:"
@@ -1957,7 +1958,7 @@ show_help_all() {
     echo ""
     echo "All commands:"
     echo "  agents chat diff edit models route"
-    echo "  acp agent analyze api assets audit backlog bench checkpoint (cp) ci cleanup"
+    echo "  acp agent analyze api assets audit backlog backup bench cancel checkpoint (cp) ci cleanup"
     echo "  cluster cockpit code compliance completions compound config context (ctx)"
     echo "  cost council crash dashboard demo deploy docker docs doctor dogfood"
     echo "  enterprise estimate explain export failover github grill heal help"
@@ -1965,7 +1966,7 @@ show_help_all() {
     echo "  issue keys kpis logs magic mcp memory metrics migrate modernize monitor"
     echo "  next notify onboard open optimize otel outcomes own (handoff) pause plan preview"
     echo "  projects proof (receipt) provider quick quickstart rc remote report reset"
-    echo "  merge resume review rollback run sandbox secrets secure self-update sentrux"
+    echo "  merge restore resume review rollback run sandbox secrets secure self-update sentrux"
     echo "  serve setup setup-skill share ship spec start state stats status steer stop"
     echo "  syslog telemetry template test tour trigger trust trust-metrics"
     echo "  ultracode undo update verify version voice watch watchdog web welcome why"
@@ -2547,23 +2548,33 @@ _loki_start_handoff() {
 }
 
 # Start Loki Mode
-# Every value-taking cmd_start flag (its value is never brief text or a run id).
-# The one list: the --workspace brief scan and the --resume scan both use it.
-# It also names value flags that are not cmd_start's own, so a scan never
-# mistakes their value for a brief or run id. --model is honored nowhere (model
-# routing is LOKI_MODEL_ROUTE); --max-cost only via the engine10 rewrite.
-_loki_start_flag_takes_value() {
-    case "$1" in
-        --provider|--brief|--budget|--prd|--issue|--isolation|--aider-model|--aider-flags|--cline-model|--compliance|--max-duration|--log-level|--bmad-project|--openspec|--mirofish-rounds|--mirofish-timeout|--output|--config|--vars|--env-file|--remote|--attempts|--mirofish-docker|--spec|--model|--max-cost|--max-wait|--base-wait|--max-iterations|--max-retries|--budget-limit|--session-model|--completion-promise) return 0 ;;
+# The ONE allowlist of cmd_start flags. _loki_start_flag_kind sets
+# _LOKI_START_FLAG_KIND to value | optional | bool, or returns 1 for an unknown
+# flag. The --workspace brief scan and the --resume scan both read it, so a value
+# is never mistaken for a brief or run id and an unknown flag exits 64 like the
+# parser's own catch-all. tests/test-cli-allow-haiku-flag.sh checks it against the
+# cmd_start case arms, so the parser and this list cannot drift apart. --model and
+# the other Bun/engine10 flags are handled by bin/loki before cmd_start runs, so
+# they are unknown to cmd_start's pre-scans by design.
+_loki_start_flag_kind() {
+    _LOKI_START_FLAG_KIND=""
+    case "${1%%=*}" in
+        --provider|--brief|--budget|--prd|--issue|--isolation|--aider-model|--aider-flags|--cline-model|--compliance|--max-duration|--log-level|--bmad-project|--openspec|--mirofish-rounds|--mirofish-timeout|--output|--config|--vars|--env-file|--remote|--attempts|--mirofish-docker) _LOKI_START_FLAG_KIND=value ;;
+        --mirofish) _LOKI_START_FLAG_KIND=optional ;;
+        --parallel|--allow-haiku|--regen-prd|--regenerate-prd|--regen|--fresh-prd|--bg|--background|--simple|--complex|--github|--no-dashboard|--api|--sandbox|--skip-memory|--yes|-y|--quiet|--mirofish-bg|--no-mirofish|--no-plan|--fast|--repo-fast|--full|--repo-full|--dry-run|--no-start|--worktree|-w|--pr|--prepare-pr|--ship|--detach|-d|--help|-h|--resume|--) _LOKI_START_FLAG_KIND=bool ;;
+        *) return 1 ;;
     esac
-    return 1
+    # A "--flag=value" token carries its own value, so it never consumes the next one.
+    if [[ "$1" == --*=* ]]; then _LOKI_START_FLAG_KIND=bool; fi
+    return 0
 }
 
 # Optional-value cmd_start flags (--mirofish [URL]). The one decision on whether
 # the NEXT token is the flag's value: non-empty and not another --flag. The
 # cmd_start --mirofish arm and both scans use it, so they cannot disagree.
-_loki_start_flag_optional_value() { [ "$1" = "--mirofish" ]; }
 _loki_start_optval_consumes() { [[ -n "${1:-}" && "${1:-}" != --* ]]; }
+# Same message and exit code as the cmd_start parser's catch-all arm.
+_loki_start_unknown_flag() { echo -e "${RED}Unknown option: $1${NC}"; exit 64; }
 
 # One exit-code mapping for an engine10 resume, shared by cmd_resume and
 # `loki start --resume`. 0 and 4 (phase reported) -> 0, 5 (publish failed) -> 1.
@@ -2648,8 +2659,13 @@ cmd_start() {
             case "$_ps_a" in
                 --brief=*) _ps_brief+=("${_ps_a#*=}") ;;
                 --brief) _ps_skip=2 ;;
+                # bin/loki turns --model into --session-model and forwards --max-cost on
+                # the legacy route; a workspace start ignores both. Skip them and their value.
+                --session-model|--max-cost) _ps_skip=1 ;;
+                --session-model=*|--max-cost=*) ;;
                 # Every value-taking cmd_start flag: its value is never brief text.
-                -*) if _loki_start_flag_takes_value "$_ps_a"; then _ps_skip=1; elif _loki_start_flag_optional_value "$_ps_a"; then _ps_skip=3; fi ;;
+                -*) _loki_start_flag_kind "$_ps_a" || _loki_start_unknown_flag "$_ps_a"
+                    if [ "$_LOKI_START_FLAG_KIND" = value ]; then _ps_skip=1; elif [ "$_LOKI_START_FLAG_KIND" = optional ]; then _ps_skip=3; fi ;;
                 *) _ps_brief+=("$_ps_a") ;;
             esac
         done
@@ -2677,17 +2693,22 @@ cmd_start() {
     # P12-07b: a bare `loki start --resume [run-id]` goes to the same engine10
     # resume path as `loki resume` (util/run_outputs.ts resumeMain), never into a
     # new build. Exit codes go through _loki_e10_resume_map (0 and 4 -> 0, 5 -> 1); any other code, such as 3 for nothing to resume, is returned as is.
-    local _ps_resume=0 _ps_resume_args=() _ps_rskip=0
+    local _ps_resume=0 _ps_resume_args=() _ps_rskip=0 _ps_unknown=""
     for _ps_a in ${_ps_rest[@]+"${_ps_rest[@]}"}; do
         if [ "$_ps_rskip" = 1 ]; then _ps_rskip=0; continue; fi
         if [ "$_ps_rskip" = 3 ]; then _ps_rskip=0; if _loki_start_optval_consumes "$_ps_a"; then continue; fi; fi
         case "$_ps_a" in
             --resume) _ps_resume=1 ;;
-            --*=*) ;;
-            -*) if _loki_start_flag_takes_value "$_ps_a"; then _ps_rskip=1; elif _loki_start_flag_optional_value "$_ps_a"; then _ps_rskip=3; fi ;;
+            -*) if ! _loki_start_flag_kind "$_ps_a"; then
+                    [ -n "$_ps_unknown" ] || _ps_unknown="$_ps_a"
+                elif [ "$_LOKI_START_FLAG_KIND" = value ]; then _ps_rskip=1
+                elif [ "$_LOKI_START_FLAG_KIND" = optional ]; then _ps_rskip=3
+                fi ;;
             *) _ps_resume_args+=("$_ps_a") ;;
         esac
     done
+    # Without --resume the cmd_start parser reports the same error itself.
+    if [ "$_ps_resume" = 1 ] && [ -n "$_ps_unknown" ]; then _loki_start_unknown_flag "$_ps_unknown"; fi
     if [ "$_ps_resume" = 1 ]; then
         local _ps_rrc=0
         for _ps_a in ${_ps_resume_args[@]+"${_ps_resume_args[@]}"}; do
@@ -5098,6 +5119,39 @@ cmd_cleanup() {
     fi
 }
 
+# P12-10b: Loki 10 run control. True when the newest engine10 run has no run.completed yet. A pending request
+# ("$1" = pause) additionally requires control-request.json to hold that action.
+_loki_e10_active_run() {
+    local last="" d
+    for d in "$LOKI_DIR"/runs/e10-*; do [ -d "$d" ] && last="$d"; done
+    [ -n "$last" ] && [ -f "$last/events.jsonl" ] || return 1
+    ! grep -q '"type":"run.completed"' "$last/events.jsonl" 2>/dev/null || return 1
+    [ -z "${1:-}" ] || grep -q "\"action\":\"$1\"" "$last/control-request.json" 2>/dev/null
+}
+
+# loki cancel: asks the active Loki 10 run to stop at its next stage boundary; the run ends CANCELLED with no PR.
+cmd_cancel() {
+    case "${1:-}" in
+        --help|-h)
+            echo -e "${BOLD}Loki Mode -- cancel the active Loki 10 run${NC}"
+            echo ""
+            echo "Usage: loki cancel"
+            echo ""
+            echo "Writes a cancel request that the engine reads at the next stage boundary."
+            echo "The run then completes as CANCELLED (run.completed with cancelled:true)."
+            echo ""
+            echo "See also: loki pause, loki resume, loki stop"
+            return 0
+            ;;
+    esac
+    if _loki_e10_active_run; then
+        ( LOKI_DIR="$LOKI_DIR" _loki_bun_delegate cancel )
+        return $?
+    fi
+    echo -e "${YELLOW}No active Loki 10 run to cancel.${NC}"
+    return 1
+}
+
 # Pause after current session
 cmd_pause() {
     # v7.6.2 B-13 fix: --help must print help, not act on session state.
@@ -5123,6 +5177,13 @@ cmd_pause() {
         exit 0
     fi
 
+    # P12-10b: an active Loki 10 run takes a stage-boundary request; anything else keeps the legacy PAUSE file.
+    if _loki_e10_active_run; then
+        local _pz_rc=0
+        ( LOKI_DIR="$LOKI_DIR" _loki_bun_delegate pause ) || _pz_rc=$?
+        [ "$_pz_rc" -ne 0 ] || return 0
+    fi
+
     if is_session_running; then
         # Warn if running in perpetual mode where PAUSE is auto-cleared (#84)
         local current_mode="${LOKI_AUTONOMY_MODE:-perpetual}"
@@ -5379,6 +5440,13 @@ cmd_resume() {
         exit 0
     fi
 
+    # P12-10b: a Loki 10 run paused by `loki pause` is released by clearing its request.
+    if _loki_e10_active_run pause; then
+        local _rz_rc=0
+        ( LOKI_DIR="$LOKI_DIR" _loki_bun_delegate resume ) || _rz_rc=$?
+        [ "$_rz_rc" -ne 0 ] || return 0
+    fi
+
     # RECOVERY: an interrupted engine10 run is resumed at its phase by loki-ts/src/util/run_outputs.ts
     # (exit 0 resumed, 4 phase reported, 5 publish failed, anything else: nothing for it, fall through).
     if ls "$LOKI_DIR"/runs/e10-*/events.jsonl >/dev/null 2>&1; then
@@ -6646,6 +6714,22 @@ cmd_status() {
         fi
     fi
 
+    # P12-19 (D04): freshness of the newest Loki 10 run, same wording as the Bun route
+    # ("last event Ns ago (seq N)"). Display-only; silent when there is no run or no parseable event.
+    local _e10_last _e10_ev _e10_seq _e10_ts _e10_epoch
+    _e10_last=$(ls -d "$LOKI_DIR"/runs/e10-*/ 2>/dev/null | sort | tail -1) || _e10_last=""
+    _e10_ev="${_e10_last%/}/events.jsonl"
+    if [ -n "$_e10_last" ] && [ -s "$_e10_ev" ]; then
+        _e10_seq=$(tail -n 1 "$_e10_ev" | jq -r '.seq // empty' 2>/dev/null) || _e10_seq=""
+        _e10_ts=$(tail -n 1 "$_e10_ev" | jq -r '.ts // empty' 2>/dev/null) || _e10_ts=""
+        _e10_epoch=$(python3 -c "import sys,datetime; print(int(datetime.datetime.fromisoformat(sys.argv[1].replace('Z','+00:00')).timestamp()))" "$_e10_ts" 2>/dev/null) || _e10_epoch=""
+        if [ -n "$_e10_seq" ] && [ -n "$_e10_epoch" ]; then
+            local _e10_age=$(( $(date +%s) - _e10_epoch ))
+            [ "$_e10_age" -lt 0 ] && _e10_age=0
+            echo -e "${CYAN}Freshness:${NC} last event ${_e10_age}s ago (seq ${_e10_seq})"
+        fi
+    fi
+
     # v7.82: surface the single most valuable, most shareable fact -- where the
     # built app is running -- when the app runner reports a live app. Display-only
     # read of .loki/app-runner/state.json (same shape build_completion_summary
@@ -9889,7 +9973,7 @@ _deploy_latest_receipt() {
     return 0
 }
 
-# _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] [post_rollback_health] [health_http_code] [health_match] [tree_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] [post_rollback_health] [health_http_code] [health_match] [tree_sha] [destination]
 # 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
@@ -9912,7 +9996,7 @@ _deploy_record() {
     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 post_rb="${16:-unchecked}" hcode_rec="${17:-}" hmatch="${18:-}" tree_sha="${19:-}"
+    local post_rb="${16:-unchecked}" hcode_rec="${17:-}" hmatch="${18:-}" tree_sha="${19:-}" dest_rec="${20:-}"
     local ddir="$dir/.loki/deploys"
     [ -d "${LOKI_DIR:-}" ] && ddir="${LOKI_DIR}/deploys"
     mkdir -p "$ddir" 2>/dev/null || return 0
@@ -9920,7 +10004,7 @@ _deploy_record() {
     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_RSHA="$receipt_sha" DR_T0="$started_at" \
-    DR_T1="$finished_at" DR_TGT="$target" DR_CAN="$canary" DR_PRB="$post_rb" DR_HC="$hcode_rec" DR_HM="$hmatch" DR_TREE="$tree_sha" \
+    DR_T1="$finished_at" DR_TGT="$target" DR_CAN="$canary" DR_PRB="$post_rb" DR_HC="$hcode_rec" DR_HM="$hmatch" DR_TREE="$tree_sha" DR_DEST="$dest_rec" \
         python3 -c '
 import json, os, datetime
 state = os.environ.get("DR_STATE") or "anchored"
@@ -9949,6 +10033,7 @@ json.dump({
     "post_rollback_health": os.environ.get("DR_PRB") or "unchecked",
     "health_match": os.environ.get("DR_HM", ""),
     "tree_sha": os.environ.get("DR_TREE", ""),
+    "destination": os.environ.get("DR_DEST", ""),
     "health_http_code": int(os.environ["DR_HC"]) if os.environ.get("DR_HC", "").isdigit() else None,
 }, open(os.environ["DR_OUT"], "w"), indent=2)
 ' 2>/dev/null || return 0
@@ -10097,6 +10182,26 @@ _deploy_policy_refusal() {
     return 0
 }
 
+# _deploy_staging_receipt_ok <dir> <sha>
+# Returns 0 only when a staging deploy record for exactly <sha> exists in
+# .loki/deploys/, exited 0, did not fail its health probe, and `loki verify`
+# reports VERIFIED. Anything that cannot be evaluated is "no" (fail closed).
+_deploy_staging_receipt_ok() {
+    local dir="${1:-.}" sha="${2:-}" ddir="$1/.loki/deploys" f
+    [ -n "$sha" ] || return 1
+    [ -d "${LOKI_DIR:-}" ] && ddir="${LOKI_DIR}/deploys"
+    [ -d "$ddir" ] || return 1
+    for f in "$ddir"/*.json; do
+        [ -f "$f" ] || continue
+        python3 -c 'import json,sys
+r=json.load(open(sys.argv[1]))
+ok=r.get("schema")=="loki.deploy/1" and r.get("destination")=="staging" and r.get("anchor_sha")==sys.argv[2] and r.get("exit_code")==0 and r.get("health_status")!="FAILED_HEALTH"
+sys.exit(0 if ok else 1)' "$f" "$sha" 2>/dev/null || continue
+        ( _loki_bun_delegate engine10 verify "$f" 2>&1 ) | grep -q "^verdict: VERIFIED" && return 0
+    done
+    return 1
+}
+
 # _deploy_try_execute <dir> <type>
 # The ONLY place a deploy command is ever run. Evaluates the gate, and either
 # executes + records, or REFUSES naming every failed check. Returns the deploy
@@ -10133,6 +10238,19 @@ _deploy_try_execute() {
         esac
     fi
 
+    # preview/staging use a non-production verb; only Vercel documents one here.
+    local dest="${_LOKI_DEPLOY_DESTINATION:-}"
+    if [ "$dest" = preview ] || [ "$dest" = staging ]; then
+        case "$command" in
+            "vercel --prod") exec_cmd="vercel" ;;
+            *)
+                echo -e "${RED}REFUSED: --destination ${dest} is not supported for: ${command}${NC}" >&2
+                echo "  No non-production verb is documented for this provider (Vercel: 'vercel' without --prod). Nothing was run." >&2
+                return 1
+                ;;
+        esac
+    fi
+
     local reasons
     reasons="$(_deploy_gate "$dir" "$command")"
 
@@ -10292,7 +10410,7 @@ _deploy_try_execute() {
     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" "$post_rb" "$hcode" "$health_match" "$(git -C "$dir" rev-parse 'HEAD^{tree}' 2>/dev/null || true)")"
+        "$rsha" "$started_at" "$finished_at" "${command%% *}" "$canary" "$post_rb" "$hcode" "$health_match" "$(git -C "$dir" rev-parse 'HEAD^{tree}' 2>/dev/null || true)" "$dest")"
     echo ""
     if [ "$rc" -eq 0 ]; then
         echo -e "${GREEN}Deploy command exited 0.${NC}"
@@ -10403,6 +10521,12 @@ _deploy_gate() {
         esac
     fi
 
+    if [ "${_LOKI_DEPLOY_DESTINATION:-}" = production ]; then
+        _deploy_staging_receipt_ok "$dir" "$(git -C "$dir" rev-parse HEAD 2>/dev/null || true)" \
+            || reasons="${reasons}no VERIFIED staging deploy receipt for this SHA (deploy with --destination staging first)
+"
+    fi
+
     local dirty
     dirty="$(_deploy_tree_clean "$dir")"
     [ -n "$dirty" ] && reasons="${reasons}${dirty}
@@ -10434,7 +10558,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_HEALTH_MATCH="" _LOKI_DEPLOY_AUTO_ROLLBACK=false _LOKI_DEPLOY_CANARY=false
+    local _LOKI_DEPLOY_HEALTH_URL="" _LOKI_DEPLOY_HEALTH_MATCH="" _LOKI_DEPLOY_AUTO_ROLLBACK=false _LOKI_DEPLOY_CANARY=false _LOKI_DEPLOY_DESTINATION=""
 
     # Arg parse (mirror cmd_preview: lenient on unknown args -> no behavior drift).
     while [ $# -gt 0 ]; do
@@ -10442,7 +10566,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 [--canary]] [--health-url URL [--health-match STR] [--auto-rollback]]"
+                echo "Usage: loki deploy [--dir <path>] [--no-clip] [--execute [--canary]] [--destination preview|staging|production] [--health-url URL [--health-match STR] [--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."
@@ -10528,6 +10652,10 @@ cmd_deploy() {
                 echo "  --dir <path>   Project directory to scan (default: current dir)"
                 echo "  --no-clip      Do not copy the idiomatic command to the clipboard"
                 echo "  --execute      Run the deploy command if the receipt gate passes"
+                echo "  --destination preview|staging|production"
+                echo "                 With --execute: preview/staging run a non-production deploy"
+                echo "                 (Vercel only); production is refused unless a VERIFIED staging"
+                echo "                 deploy record exists for the same SHA. Unset keeps today's behavior."
                 echo "  --allow-unanchored"
                 echo "                 Proceed when the receipt records NO baseline (nothing"
                 echo "                 about this tree is proven). Never bypasses a recorded"
@@ -10559,6 +10687,12 @@ cmd_deploy() {
             --canary)
                 _LOKI_DEPLOY_CANARY=true
                 ;;
+            --destination)
+                case "${2:-}" in
+                    preview|staging|production) _LOKI_DEPLOY_DESTINATION="$2"; shift ;;
+                    *) echo "loki deploy --destination must be one of: preview, staging, production" >&2; return 1 ;;
+                esac
+                ;;
             --dir)
                 # Guard against a missing OR flag-shaped value: an unguarded
                 # shift when --dir is the last arg underflows under set -e, and a
@@ -10588,6 +10722,10 @@ cmd_deploy() {
         echo "loki deploy --canary requires --execute" >&2
         return 1
     fi
+    if [ "$_LOKI_DEPLOY_CANARY" = true ] && [ -n "$_LOKI_DEPLOY_DESTINATION" ] && [ "$_LOKI_DEPLOY_DESTINATION" != production ]; then
+        echo "loki deploy --canary only applies to --destination production" >&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
@@ -14630,6 +14768,7 @@ cmd_doctor() {
         echo "loki doctor: the Bun doctor is unavailable, so only this minimal report can run."
         echo "Fix: ${_LOKI_DELEGATE_FIX}"
         echo "${_LOKI_DELEGATE_WHY}"
+        ( source "$SKILL_DIR/providers/model_routes.sh" 2>/dev/null && loki_model_route_lane_report ) || true
     fi
     return 1
 }
@@ -18632,6 +18771,7 @@ cmd_modernize() {
             echo "  heal <path>      Legacy system healing in phases (was: loki heal)"
             echo "  migrate <path>   Codebase migration in phases (was: loki migrate)"
             echo "  unit --repo <owner/name> --ref <ref> --unit <id>   Run one unit (remote unit job worker)"
+            echo "  <repo> --to <lang>   Full modernization: oracle capture, waves, verify, ship"
             echo ""
             echo "Run 'loki modernize <subcommand> --help' for each. The old"
             echo "top-level names still work; see 'loki help aliases'."
@@ -21646,6 +21786,9 @@ main() {
         steer)
             cmd_steer "$@"
             ;;
+        cancel)
+            cmd_cancel "$@"
+            ;;
         resume)
             cmd_resume "$@"
             ;;
@@ -21787,6 +21930,12 @@ main() {
         rollback)
             cmd_rollback "$@"
             ;;
+        backup)
+            cmd_backup "$@"
+            ;;
+        restore)
+            cmd_restore "$@"
+            ;;
         merge)
             cmd_merge "$@"
             ;;
@@ -26327,6 +26476,178 @@ cmd_merge() {
 # Restore is destructive on .loki/ state, so it ALWAYS captures a forced
 # pre-rollback snapshot first (re-undoability invariant) and then glob-restores
 # whatever the checkpoint dir contains (works across all three checkpoint writers).
+# P12-48: back up and restore the machine-global dashboard state directory
+# (audit log, retention checkpoint, config). Archive = tar.gz holding
+# LOKI-BACKUP-MANIFEST (sha256 per file) plus the state tree, with a sidecar
+# <archive>.sha256 over the whole archive. Restore verifies both before
+# touching anything and refuses to overwrite existing state without --force.
+_backup_state_dir() {
+    printf '%s' "${LOKI_DASHBOARD_STATE_DIR:-${HOME}/.loki/dashboard}"
+}
+
+_backup_sha256() {
+    if command -v sha256sum >/dev/null 2>&1; then
+        sha256sum "$1" | awk '{print $1}'
+    else
+        shasum -a 256 "$1" | awk '{print $1}'
+    fi
+}
+
+cmd_backup() {
+    local dir out="" arg
+    dir="$(_backup_state_dir)"
+    while [ $# -gt 0 ]; do
+        arg="$1"; shift
+        case "$arg" in
+            --dir) dir="${1:-}"; shift || true ;;
+            --out) out="${1:-}"; shift || true ;;
+            -h|--help)
+                echo "Usage: loki backup [--dir STATE_DIR] [--out ARCHIVE.tar.gz]"
+                echo "  Archives the dashboard state directory (default ~/.loki/dashboard) with a"
+                echo "  sha256 manifest and writes ARCHIVE.sha256 next to it."
+                return 0 ;;
+            *) echo -e "${RED}Unknown option: $arg${NC}" >&2; return 2 ;;
+        esac
+    done
+    if [ ! -d "$dir" ]; then
+        echo -e "${RED}Error: state directory not found: $dir${NC}" >&2
+        return 1
+    fi
+    [ -n "$out" ] || out="./loki-backup-$(date -u +%Y%m%d-%H%M%S).tar.gz"
+    if [ -e "$out" ]; then
+        echo -e "${RED}Error: refusing to overwrite existing archive: $out${NC}" >&2
+        return 1
+    fi
+    dir="$(cd "$dir" && pwd -P)" || return 1
+
+    local mdir manifest rel digest count=0
+    mdir="$(mktemp -d "${TMPDIR:-/tmp}/loki-backup.XXXXXXXX")" || return 1
+    manifest="$mdir/LOKI-BACKUP-MANIFEST"
+    : > "$manifest"
+    while IFS= read -r -d '' rel; do
+        digest="$(_backup_sha256 "$dir/$rel")" || { rm -rf -- "$mdir"; return 1; }
+        printf '%s  %s\n' "$digest" "$rel" >> "$manifest"
+        count=$((count + 1))
+    done < <(cd "$dir" && find . -type f ! -name '*.pid' -print0 | LC_ALL=C sort -z)
+
+    # Symlinks and special files cannot be verified by the manifest; refuse them.
+    if [ -n "$(cd "$dir" && find . ! -type f ! -type d ! -name '*.pid' -print -quit)" ]; then
+        rm -rf -- "$mdir"
+        echo -e "${RED}Error: $dir holds symlinks or special files; cannot back up safely${NC}" >&2
+        return 1
+    fi
+    if ! tar -czf "$out" --exclude='*.pid' -C "$mdir" LOKI-BACKUP-MANIFEST -C "$dir" .; then
+        rm -f -- "$out"
+        rm -rf -- "$mdir"
+        echo -e "${RED}Error: tar failed${NC}" >&2
+        return 1
+    fi
+    rm -rf -- "$mdir"
+    printf '%s  %s\n' "$(_backup_sha256 "$out")" "$(basename "$out")" > "${out}.sha256"
+    echo "Backed up $count file(s) from $dir"
+    echo "  archive: $out"
+    echo "  sha256:  ${out}.sha256"
+}
+
+cmd_restore() {
+    local archive="" dir force=0 expect="" arg
+    dir="$(_backup_state_dir)"
+    while [ $# -gt 0 ]; do
+        arg="$1"; shift
+        case "$arg" in
+            --dir) dir="${1:-}"; shift || true ;;
+            --force) force=1 ;;
+            --sha256) expect="${1:-}"; shift || true ;;
+            -h|--help)
+                echo "Usage: loki restore ARCHIVE.tar.gz [--dir STATE_DIR] [--force] [--sha256 HEX]"
+                echo "  Verifies the archive (sidecar or --sha256) and its manifest, then restores."
+                echo "  Refuses to replace a non-empty STATE_DIR without --force; with --force the"
+                echo "  existing directory is moved to STATE_DIR.pre-restore.<timestamp>."
+                return 0 ;;
+            -*) echo -e "${RED}Unknown option: $arg${NC}" >&2; return 2 ;;
+            *) archive="$arg" ;;
+        esac
+    done
+    if [ -z "$archive" ] || [ ! -f "$archive" ]; then
+        echo -e "${RED}Error: archive not found. Usage: loki restore ARCHIVE.tar.gz${NC}" >&2
+        return 2
+    fi
+
+    # 1. Whole-archive digest: explicit --sha256, else the sidecar. Required.
+    if [ -z "$expect" ]; then
+        if [ -f "${archive}.sha256" ]; then
+            expect="$(awk 'NR==1 {print $1}' "${archive}.sha256")"
+        else
+            echo -e "${RED}Error: no ${archive}.sha256 sidecar and no --sha256; refusing unverified restore${NC}" >&2
+            return 1
+        fi
+    fi
+    if [ "$(_backup_sha256 "$archive")" != "$expect" ]; then
+        echo -e "${RED}Error: archive sha256 mismatch (tampered or corrupt); nothing restored${NC}" >&2
+        return 1
+    fi
+
+    # 2. Entry names must be plain relative paths with no symlinks or specials.
+    local listing
+    listing="$(tar -tzf "$archive" 2>/dev/null)" || { echo -e "${RED}Error: unreadable archive${NC}" >&2; return 1; }
+    if printf '%s\n' "$listing" | grep -E -q '(^/|(^|/)\.\.(/|$))'; then
+        echo -e "${RED}Error: archive contains unsafe paths; nothing restored${NC}" >&2
+        return 1
+    fi
+
+    # 3. Extract to a staging dir beside the target (same filesystem), verify the manifest.
+    mkdir -p "$(dirname "$dir")" || return 1
+    local stage
+    stage="$(mktemp -d "${dir}.restore.XXXXXXXX")" || return 1
+    if ! tar -xzf "$archive" -C "$stage" 2>/dev/null; then
+        rm -rf -- "$stage"
+        echo -e "${RED}Error: extraction failed; nothing restored${NC}" >&2
+        return 1
+    fi
+    local bad=""
+    if [ ! -f "$stage/LOKI-BACKUP-MANIFEST" ]; then
+        bad="missing manifest"
+    elif [ -n "$(find "$stage" ! -type f ! -type d -print -quit)" ]; then
+        bad="non-regular entry in archive"
+    else
+        local digest rel n_files n_listed
+        while IFS= read -r line; do
+            digest="${line%%  *}"; rel="${line#*  }"
+            if [ ! -f "$stage/$rel" ] || [ "$(_backup_sha256 "$stage/$rel")" != "$digest" ]; then
+                bad="manifest mismatch: $rel"; break
+            fi
+        done < "$stage/LOKI-BACKUP-MANIFEST"
+        if [ -z "$bad" ]; then
+            n_files="$(find "$stage" -type f ! -name LOKI-BACKUP-MANIFEST | wc -l | tr -d ' ')"
+            n_listed="$(wc -l < "$stage/LOKI-BACKUP-MANIFEST" | tr -d ' ')"
+            [ "$n_files" = "$n_listed" ] || bad="archive holds files the manifest does not list"
+        fi
+    fi
+    if [ -n "$bad" ]; then
+        rm -rf -- "$stage"
+        echo -e "${RED}Error: archive failed verification ($bad); nothing restored${NC}" >&2
+        return 1
+    fi
+    rm -f -- "$stage/LOKI-BACKUP-MANIFEST"
+
+    # 4. Never overwrite existing state silently.
+    if [ -e "$dir" ] && [ -n "$(ls -A "$dir" 2>/dev/null)" ]; then
+        if [ "$force" -ne 1 ]; then
+            rm -rf -- "$stage"
+            echo -e "${RED}Error: $dir is not empty; re-run with --force to replace it${NC}" >&2
+            return 1
+        fi
+        local aside
+        aside="${dir}.pre-restore.$(date -u +%Y%m%d-%H%M%S)"
+        mv "$dir" "$aside" || { rm -rf -- "$stage"; return 1; }
+        echo "  previous state kept at: $aside"
+    elif [ -d "$dir" ]; then
+        rmdir "$dir" 2>/dev/null || true
+    fi
+    mv "$stage" "$dir" || return 1
+    echo "Restored $dir from $archive (verified)"
+}
+
 cmd_rollback() {
     local subcommand="${1:-help}"
     shift 2>/dev/null || true
@@ -32374,7 +32695,32 @@ _docs_invoke_provider() {
             # not the workload that needs the top tier. Pinned to the same
             # default the review subcall uses (run.sh:13762), and overridable
             # for anyone who wants a different trade.
-            result=$($t_prefix env CAVEMAN_DEFAULT_MODE=off claude -p --model "${LOKI_DOCS_MODEL:-sonnet}" "$prompt" 2>/dev/null) || exit_code=$?
+            # S6 lean child: text-only role, so the lean flag set (from
+            # claude-flags.sh, lazily sourced) drops user hooks, MCP and tools.
+            # When the child ledger helper exists the call uses
+            # --output-format json so usage is recorded, then unwraps .result.
+            local _lean=() _lf _ledger=false
+            if ! declare -F loki_lean_child_flags >/dev/null 2>&1 \
+               && [ -f "${_LOKI_SCRIPT_DIR:-.}/lib/claude-flags.sh" ]; then
+                # shellcheck source=autonomy/lib/claude-flags.sh
+                . "${_LOKI_SCRIPT_DIR}/lib/claude-flags.sh" 2>/dev/null || true
+            fi
+            if declare -F loki_lean_child_flags >/dev/null 2>&1; then
+                while IFS= read -r _lf; do _lean+=("$_lf"); done < <(loki_lean_child_flags docs 2>/dev/null)
+            fi
+            declare -F loki_child_ledger_append >/dev/null 2>&1 && _ledger=true
+            local _fmt=()
+            [ "$_ledger" = true ] && _fmt=(--output-format json)
+            result=$($t_prefix env CAVEMAN_DEFAULT_MODE=off claude -p ${_lean[@]+"${_lean[@]}"} ${_fmt[@]+"${_fmt[@]}"} --model "${LOKI_DOCS_MODEL:-sonnet}" "$prompt" 2>/dev/null) || exit_code=$?
+            if [ "$_ledger" = true ] && [ -n "$result" ]; then
+                loki_child_ledger_append docs "$result" >/dev/null 2>&1 || true
+                result=$(printf '%s' "$result" | python3 -c 'import json,sys
+try:
+    d = json.load(sys.stdin)
+    print(d.get("result", ""))
+except Exception:
+    pass' 2>/dev/null)
+            fi
             ;;
         codex)
             result=$($t_prefix codex exec --sandbox workspace-write "$prompt" 2>/dev/null) || exit_code=$?
@@ -32442,14 +32788,20 @@ MANIFEST_EOF
 # --- loki docs generate ---
 _docs_generate() {
     local target_path="."
+    local docs_requested=false
 
     while [[ $# -gt 0 ]]; do
         case "$1" in
             --help|-h)
-                echo "Usage: loki docs generate [path]"
+                echo "Usage: loki docs generate [--docs] [path]"
                 echo "Generate full documentation suite in .loki/docs/"
+                echo "  --docs   Generate even when LOKI_DOCS_TIER is small (explicit request)"
                 return 0
                 ;;
+            --docs)
+                docs_requested=true
+                shift
+                ;;
             -*)
                 log_error "Unknown option: $1"
                 return 1
@@ -32467,6 +32819,17 @@ _docs_generate() {
     fi
     target_path="$(cd "$target_path" && pwd)"
 
+    # S6: a small-tier run (caller exports LOKI_DOCS_TIER) does not pay for the
+    # eight-doc suite unless docs were asked for explicitly.
+    case "${LOKI_DOCS_TIER:-}" in
+        small|simple)
+            if [ "$docs_requested" != true ]; then
+                log_info "Small tier: skipping the 8-doc suite (pass --docs to force)"
+                return 0
+            fi
+            ;;
+    esac
+
     local docs_dir="$target_path/.loki/docs"
     mkdir -p "$docs_dir"