loki-mode 7.28.2 → 7.29.0

package/README.md

@@ -28,6 +28,7 @@
 - **Production quality built in** -- 11 quality gates (`skills/quality-gates.md`), blind 3-reviewer code review (`run.sh:run_code_review()`), anti-sycophancy checks
 - **Standalone verification: `loki verify`** -- Run Loki's deterministic gates (build, tests, static analysis, secret scan, dependency audit) against any branch or PR diff, including code written by other agents or humans. CI-ready exit codes (0 VERIFIED, 1 CONCERNS, 2 BLOCKED), machine-readable evidence at `.loki/verify/evidence.json`. Inconclusive evidence is never reported as VERIFIED (v7.27.0).
 - **Living spec and pre-build interrogation** -- `loki spec` locks a spec and detects drift deterministically (`spec.lock`, `drift-report.json`, and a `SPEC_DRIFT` finding in `loki verify` with CI exit codes), so you can tell when the build diverges from what was agreed. `loki grill` runs a Devil's-Advocate interrogation of the spec before you build, surfacing gaps and contradictions early (v7.28.0).
+- **Guided first build: `loki quickstart`** -- four quick questions (setup check, one-line idea, template pick, plan review) and your build starts; pressing Enter through every step builds the sample Todo app. The plan step quotes the real cost/time estimate before anything is spent, and `loki demo` now confirms its estimate the same way. If no AI provider CLI is installed, Loki offers to install Claude Code (consent-gated, interactive terminals only) (v7.29.0).
 - **Live App Preview** -- The dashboard embeds the locally-running app in an iframe so you can interact with it immediately during a build. Use `loki preview` (alias `loki open`) to print the URL and open it in your browser. Local-first: no hosted service, no vendor lock (v7.24.0).
 - **Compose-first fullstack** -- When a spec needs more than one service (web + database + cache) Loki generates a 12-factor `docker-compose.yml` with healthchecks, `depends_on` wiring, env-var config, and a `.env.example`. The Live App Preview surfaces the web service URL (not a database port), and health reflects the web service's Docker healthcheck so a crashed app shows as crashed even when the database stays up. Single-service apps stay on a plain run command. All local-first, no hosted service (v7.26.0).
 - **Intelligent `loki start`** -- For interactive foreground runs the dashboard auto-opens in the browser (cross-platform; skipped in CI, SSH-without-TTY, and piped runs; opt out with `LOKI_NO_AUTO_OPEN=1`). The completion summary shows "Your app is live at <url>" so you know exactly where to try what Loki just built. The autonomous loop passes Claude Code's `--effort`, `--max-budget-usd`, and `--fallback-model` on every iteration (each gated on CLI support and individual opt-out env vars) for better long-run unattended execution (v7.25.0).
@@ -101,7 +102,7 @@ loki quick "build a landing page with a signup form"
 |--------|---------|-------|
 | **Bun (recommended)** | `bun install -g loki-mode` | Fastest startup for CLI commands. |
 | **Homebrew** | `brew tap asklokesh/tap && brew install loki-mode` | Auto-installs Bun as a dep |
-| **Docker** | `docker pull asklokesh/loki-mode:7.28.2 && docker run --rm asklokesh/loki-mode:7.28.2 start prd.md` | Bun pre-installed in image |
+| **Docker** | `docker pull asklokesh/loki-mode:7.29.0 && docker run --rm asklokesh/loki-mode:7.29.0 start prd.md` | Bun pre-installed in image |
 | **npm (compat)** | `npm install -g loki-mode` | Works without Bun (bash fallback). Migrate any time with `loki self-update --to bun`. |
 
 **Upgrading:**
@@ -161,7 +162,7 @@ The next major release sunsets the Bash runtime entirely. There is no firm calen
 | Method | Command |
 |--------|---------|
 | **Homebrew** | `brew tap asklokesh/tap && brew install loki-mode` |
-| **Docker** | `docker pull asklokesh/loki-mode:7.28.2` |
+| **Docker** | `docker pull asklokesh/loki-mode:7.29.0` |
 | **Inside Claude Code** | `claude --dangerously-skip-permissions` then type "Loki Mode" |
 | **Git clone** | `git clone https://github.com/asklokesh/loki-mode.git` |
 

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, 11 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.28.2
+# Loki Mode v7.29.0
 
 **You are an autonomous agent. You make decisions. You do not ask questions. You do not stop.**
 
@@ -342,6 +342,12 @@ Two completion-trust features extend the verification gates. Full details in `sk
 - **Held-out spec evals:** ~25% of checklist items (deterministic `sha256(id)` order, `N >= 4`) are reserved into `.loki/checklist/held-out.json` and excluded from the build prompt feed; the completion council blocks if a held-out item fails. Opt out with `LOKI_HELDOUT_GATE=0`. Honest limit: this guards the prompt feed, not a sandbox; the reservation file is on disk and an agent with filesystem access can read it.
 - **Inconclusive-baseline disclosure:** when the evidence gate cannot establish a diff baseline (`no_git_repo` / `no_run_start_sha`) it writes `.loki/state/evidence-inconclusive.json` and `COMPLETION.txt` carries an honest "not independently verified" line. It never blocks non-git projects; red tests still block.
 
+## First-run UX (v7.29.0)
+
+- **`loki quickstart`:** guided 4-step first build (setup check, one-line idea, offline template match, plan review with real estimator figures); Enter-through-everything builds the sample Todo app; non-TTY/CI exits 2 with an automation hint.
+- **Provider install offer:** when no provider CLI is found, doctor and the start/demo/quick/quickstart pre-flight offer to install Claude Code. Consent-gated on an interactive TTY only; the single command executed is printed first; auth handoff via `claude auth login` with readiness confirmed by `claude auth status`. Opt out: `LOKI_NO_INSTALL_OFFER=1`.
+- **`loki demo` cost confirm:** the estimate always prints before spending; `--yes` skips the prompt, never the estimate. `LOKI_COMPLEXITY` is honored by `loki plan` with an honest forced-tier note.
+
 ---
 
 ## Concurrency and Security Hardening (v7.5.7 - v7.5.13)
@@ -392,4 +398,4 @@ See `CHANGELOG.md` entries [7.5.7], [7.5.8], [7.5.13] for the per-fix list and r
 
 ---
 
-**v7.28.2 | [Autonomi](https://www.autonomi.dev/) flagship product | ~260 lines core**
+**v7.29.0 | [Autonomi](https://www.autonomi.dev/) flagship product | ~260 lines core**

package/VERSION

@@ -1 +1 @@
-7.28.2
+7.29.0

package/autonomy/loki

@@ -68,6 +68,24 @@ if [ -f "$_LOKI_SCRIPT_DIR/crash.sh" ]; then
     source "$_LOKI_SCRIPT_DIR/crash.sh"
 fi
 
+# Provider install offer (v7.29.0): shared, self-contained helper providing
+# detect_any_provider, offer_provider_install, and provider_offer_gate. Sourced
+# here for the bash route; doctor.ts invokes the same file via child_process so
+# the offer copy never drifts between routes. Self-guarded against double-source.
+if [ -f "$_LOKI_SCRIPT_DIR/provider-offer.sh" ]; then
+    # shellcheck source=provider-offer.sh
+    source "$_LOKI_SCRIPT_DIR/provider-offer.sh"
+fi
+
+# Quickstart guided interview (v7.29.0): provides cmd_quickstart and its
+# deterministic offline template matcher. Functions-only file (no top-level
+# command), sourced here so the dispatch case can call cmd_quickstart. Composes
+# the provider offer (above), show_prd_plan, and cmd_start. Self-guarded.
+if [ -f "$_LOKI_SCRIPT_DIR/quickstart.sh" ]; then
+    # shellcheck source=quickstart.sh
+    source "$_LOKI_SCRIPT_DIR/quickstart.sh"
+fi
+
 # Resolve the script's real path (handles symlinks)
 resolve_script_path() {
     local script="$1"
@@ -522,6 +540,7 @@ show_help() {
     echo "  quick \"task\"     Quick single-task mode (lightweight, 3 iterations max)"
     echo "  monitor [path]   Monitor Docker Compose services with auto-fix (v6.67.0)"
     echo "  demo             Build a sample todo app end to end (real run)"
+    echo "  quickstart [idea]  Guided first build: setup, idea, template, plan, go"
     echo "  init [name]      Project scaffolding with 21 PRD templates"
     echo "  issue <url|num>  (deprecated) Use 'loki start <issue-ref>' instead"
     echo "  watch [prd]      Auto-rerun on PRD file changes (v6.33.0)"
@@ -1260,6 +1279,17 @@ cmd_start() {
         esac
     done
 
+    # v7.29.0: provider pre-flight gate. If no provider CLI is installed, offer
+    # to install one (TTY) or print honest manual instructions and exit 2
+    # (non-TTY/CI), BEFORE any spend or runner entry. This moves what used to be
+    # an opaque deep-runner failure to a friendly, actionable top-of-run gate.
+    # --help already returned inside the arg loop, so we never gate help.
+    if declare -f provider_offer_gate >/dev/null 2>&1; then
+        if ! provider_offer_gate; then
+            exit 2
+        fi
+    fi
+
     # Clear any stale raw-brief marker from a PRIOR run before we decide the
     # mode of THIS run. Only the brief branch (below) re-writes it. Without this,
     # a brief run leaves .loki/state/brief.txt behind and a later non-brief run
@@ -2286,10 +2316,18 @@ PYDASH
     # v7.7.30: --all preserves the legacy machine-wide kill. It runs even when
     # the current folder has no live session (the "clean everything" use case),
     # reaping every folder's orphaned loki-run-* temp script (SIGTERM, SIGKILL).
+    #
+    # The kill pattern is "loki-run-" for real users and is NOT user-overridable
+    # at the CLI -- that is the documented machine-wide behavior. LOKI_STOP_ALL_PATTERN
+    # exists ONLY so the test suite can exercise this exact code path against its
+    # own uniquely-marked fake runners without SIGKILLing an unrelated live
+    # loki-run-* on the same machine (e.g. a long SWE-bench instance). It defaults
+    # to "loki-run-" so user-facing semantics are unchanged when unset.
     if [ "$stop_all" = true ]; then
-        pkill -f "loki-run-" 2>/dev/null || true
+        local _stop_all_pat="${LOKI_STOP_ALL_PATTERN:-loki-run-}"
+        pkill -f "$_stop_all_pat" 2>/dev/null || true
         sleep 0.5
-        pkill -9 -f "loki-run-" 2>/dev/null || true
+        pkill -9 -f "$_stop_all_pat" 2>/dev/null || true
         echo -e "${RED}--all: signalled all loki-run-* processes on this machine.${NC}"
     fi
 }
@@ -7728,15 +7766,19 @@ cmd_doctor() {
     doctor_check "Cline CLI"           cline    optional || true
     doctor_check "Aider CLI"           aider    optional || true
 
-    # Check if at least one provider is installed
-    local _any_provider=false
-    for _dp in claude codex cline aider; do
-        command -v "$_dp" &>/dev/null && _any_provider=true && break
-    done
-    if ! $_any_provider; then
+    # Check if at least one provider is installed (detect_any_provider is the
+    # shared helper from provider-offer.sh, extracted from this exact loop).
+    if ! detect_any_provider; then
         echo -e "  ${RED}FAIL${NC}  No AI provider CLI installed -- at least one is required"
         echo -e "         ${YELLOW}Install: npm install -g @anthropic-ai/claude-code${NC}"
         fail_count=$((fail_count + 1))
+        # v7.29.0: on a TTY (non-json), append the consent-gated install offer.
+        # In report mode the helper is a no-op on non-TTY/CI, so the doctor
+        # output stays byte-identical for the bun-parity matrix. --json never
+        # reaches here (cmd_doctor dispatches to cmd_doctor_json earlier).
+        if declare -f offer_provider_install >/dev/null 2>&1; then
+            offer_provider_install report || true
+        fi
     fi
     echo ""
 
@@ -9030,6 +9072,69 @@ cmd_sandbox() {
     exec "$SANDBOX_SH" "$subcommand" "$@"
 }
 
+# v7.29.0 (feature #4): print the SIMPLE-tier cost/time/iteration estimate for
+# the demo PRD, parsed from the single estimator source (show_prd_plan JSON).
+# Because `loki demo` always runs `loki start --simple` (which exports
+# LOKI_COMPLEXITY=simple), the estimate is computed with LOKI_COMPLEXITY=simple
+# so the quoted figures are the ones the demo will actually incur -- honest by
+# construction (the keystone fix makes show_prd_plan honor LOKI_COMPLEXITY).
+# Returns 0 when a real estimate was printed, 1 when the estimator failed (the
+# caller then falls back to a no-number confirm). Never fabricates a number.
+emit_demo_estimate() {
+    local prd_path="$1"
+    local plan_json=""
+    plan_json=$(LOKI_COMPLEXITY=simple show_prd_plan "$prd_path" "true" "false" 2>/dev/null) || plan_json=""
+
+    if [ -z "$plan_json" ]; then
+        echo -e "${YELLOW}Could not compute a cost estimate (the estimator did not return a result).${NC}"
+        return 1
+    fi
+
+    local parsed
+    parsed=$(printf '%s' "$plan_json" | python3 -c "
+import json, sys
+try:
+    d = json.load(sys.stdin)
+except Exception:
+    sys.exit(1)
+cost = d.get('cost', {}).get('total_usd')
+time_est = d.get('time', {}).get('estimated')
+iters = d.get('iterations', {}).get('estimated')
+rng = d.get('iterations', {}).get('range', [])
+tier = d.get('complexity', {}).get('tier', 'simple')
+if cost is None or time_est is None or iters is None:
+    sys.exit(1)
+rng_str = ''
+if isinstance(rng, list) and len(rng) == 2:
+    rng_str = ' (range {}-{})'.format(rng[0], rng[1])
+print(tier.upper())
+print('{:.2f}'.format(float(cost)))
+print(time_est)
+print('{}{}'.format(iters, rng_str))
+" 2>/dev/null) || parsed=""
+
+    if [ -z "$parsed" ]; then
+        echo -e "${YELLOW}Could not compute a cost estimate (the estimator did not return a result).${NC}"
+        return 1
+    fi
+
+    local tier_u cost_u time_u iter_u
+    tier_u=$(printf '%s' "$parsed" | sed -n '1p')
+    cost_u=$(printf '%s' "$parsed" | sed -n '2p')
+    time_u=$(printf '%s' "$parsed" | sed -n '3p')
+    iter_u=$(printf '%s' "$parsed" | sed -n '4p')
+
+    echo -e "${BOLD}Estimate (${tier_u} tier, the path this demo actually runs):${NC}"
+    printf '  Cost:        ~$%s\n' "$cost_u"
+    echo "  Time:        ~$time_u"
+    echo "  Iterations:  $iter_u"
+    echo ""
+    echo -e "${DIM}This is an estimate. Actual usage depends on PRD complexity,"
+    echo -e "code review cycles, and test failures.${NC}"
+    echo ""
+    return 0
+}
+
 # Demo mode - build a real project from a bundled PRD template
 cmd_demo() {
     # Handle --help
@@ -9062,10 +9167,21 @@ cmd_demo() {
     local provider=""
     local dry_run=false
     local start_args=()
+    # v7.29.0 (feature #4): demo now shows the FORCED-simple cost estimate
+    # before spending and asks for confirmation. --yes / LOKI_ASSUME_YES skip
+    # the prompt but still print the estimate (the spend is never hidden).
+    local assume_yes=false
+    if [ "${LOKI_ASSUME_YES:-}" = "1" ] || [ "${LOKI_ASSUME_YES:-}" = "true" ]; then
+        assume_yes=true
+    fi
 
     # Parse arguments
     while [[ $# -gt 0 ]]; do
         case "$1" in
+            --yes|-y)
+                assume_yes=true
+                shift
+                ;;
             --dir)
                 if [[ -z "${2:-}" ]]; then
                     echo -e "${RED}Error: --dir requires a path${NC}"
@@ -9106,6 +9222,17 @@ cmd_demo() {
         esac
     done
 
+    # v7.29.0: provider pre-flight gate (skipped for --dry-run, which never
+    # spends). On a TTY, offer to install; on non-TTY/CI, print honest manual
+    # instructions and exit 2 before any spend. Detect-first, so the nested
+    # cmd_start gate below no-ops once a provider is present. --help already
+    # returned at the top of cmd_demo.
+    if [ "$dry_run" != true ] && declare -f provider_offer_gate >/dev/null 2>&1; then
+        if ! provider_offer_gate; then
+            exit 2
+        fi
+    fi
+
     # Fall back to examples/ if templates/ doesn't exist
     if [ ! -f "$demo_prd" ]; then
         demo_prd="$SKILL_DIR/examples/simple-todo-app.md"
@@ -9146,6 +9273,9 @@ cmd_demo() {
     fi
 
     if [ "$dry_run" = true ]; then
+        # v7.29.0: dry-run is now a genuine cost preview -- show the estimate,
+        # no prompt, no spend.
+        emit_demo_estimate "$demo_dir/prd.md" || true
         echo -e "${YELLOW}[dry-run] Would run:${NC}"
         echo "  cd $demo_dir"
         echo -n "  loki start prd.md --simple --yes"
@@ -9156,6 +9286,52 @@ cmd_demo() {
         return 0
     fi
 
+    # v7.29.0 (feature #4): cost confirm before any spend. The estimate ALWAYS
+    # prints (even with --yes), so the spend is never hidden. The prompt is
+    # shown only on a TTY without --yes; non-TTY without --yes refuses (exit 2)
+    # rather than hanging on read -- the project's "never hang in CI" idiom.
+    local estimate_ok=true
+    emit_demo_estimate "$demo_dir/prd.md" || estimate_ok=false
+
+    # Interactive only when stdin is a real TTY and CI is not forcing
+    # non-interactive (matches the project's first-run gate semantics).
+    local demo_interactive=true
+    if [ ! -t 0 ] || [ -n "${CI:-}" ]; then
+        demo_interactive=false
+    fi
+
+    if [ "$assume_yes" != true ]; then
+        if [ "$demo_interactive" = true ]; then
+            local demo_answer=""
+            if [ "$estimate_ok" = true ]; then
+                # Default YES: Enter proceeds.
+                echo -n "Build the Todo app now? [Y/n] "
+                read -r demo_answer </dev/tty 2>/dev/null || demo_answer=""
+                if [[ -n "$demo_answer" && ! "$demo_answer" =~ ^[Yy] ]]; then
+                    echo ""
+                    echo -e "Cancelled. Nothing was spent. The demo PRD is at:"
+                    echo -e "  ${CYAN}$demo_dir/prd.md${NC}"
+                    echo -e "Run 'loki plan ${demo_dir}/prd.md' for the full breakdown."
+                    return 0
+                fi
+            else
+                # No honest number available: default NO (the safe direction).
+                echo -n "Proceed with the demo build anyway? [y/N] "
+                read -r demo_answer </dev/tty 2>/dev/null || demo_answer=""
+                if [[ ! "$demo_answer" =~ ^[Yy] ]]; then
+                    echo ""
+                    echo -e "Cancelled. Nothing was spent. The demo PRD is at:"
+                    echo -e "  ${CYAN}$demo_dir/prd.md${NC}"
+                    return 0
+                fi
+            fi
+        else
+            # Non-TTY without --yes: never hang; refuse with an honest message.
+            echo "demo needs confirmation; re-run with --yes to proceed non-interactively" >&2
+            return 2
+        fi
+    fi
+
     echo -e "${DIM}Starting autonomous build...${NC}"
     echo -e "${DIM}(Press Ctrl+C to stop at any time)${NC}"
     echo ""
@@ -9380,6 +9556,15 @@ cmd_quick() {
         exit 2
     fi
 
+    # v7.29.0: provider pre-flight gate. Offer install on a TTY; print honest
+    # manual instructions and exit 2 on non-TTY/CI, before any spend. --help and
+    # the no-args usage path already returned/exited above.
+    if declare -f provider_offer_gate >/dev/null 2>&1; then
+        if ! provider_offer_gate; then
+            exit 2
+        fi
+    fi
+
     local task_desc="$*"
     local version=$(get_version)
     local max_iter="${LOKI_MAX_ITERATIONS:-3}"
@@ -12833,6 +13018,20 @@ show_verbose = sys.argv[3] == 'true'
 session_model_env = (os.environ.get('LOKI_SESSION_MODEL', 'sonnet') or 'sonnet').strip().lower()
 legacy_tier_switching = (os.environ.get('LOKI_LEGACY_TIER_SWITCHING', 'false') or 'false').strip().lower() == 'true'
 
+# v7.29.0: Honor LOKI_COMPLEXITY -- the SAME env var the runner honors at
+# run.sh:920 -- so a forced-tier run (e.g. 'loki demo' / 'loki start --simple'
+# which export LOKI_COMPLEXITY=simple) quotes the tier it will actually run,
+# not the content-derived tier. Without this the estimate diverges from
+# execution (audit finding #9). Runner vocabulary is auto|simple|standard|complex;
+# the estimator's internal tiers are simple|moderate|complex|enterprise, so
+# 'standard' aliases to 'moderate' (the 6-12 iteration analog). 'auto', empty,
+# and any unrecognized value are ignored (content tier is used) -- honest by
+# construction. The override is applied AFTER the content score-to-tier map.
+_forced_complexity_raw = (os.environ.get('LOKI_COMPLEXITY', '') or '').strip().lower()
+forced_complexity = {'standard': 'moderate'}.get(_forced_complexity_raw, _forced_complexity_raw)
+if forced_complexity not in ('simple', 'moderate', 'complex', 'enterprise'):
+    forced_complexity = ''
+
 # Map session model name to tier key used in tokens_per_tier below.
 # Unknown models fall through to 'development' (Sonnet) as a safe default.
 _session_tier_map = {
@@ -12985,6 +13184,14 @@ elif complexity_score <= 5:
 else:
     complexity = 'enterprise'
 
+# v7.29.0: apply the forced-tier override AFTER the content score-to-tier map,
+# so it is not clobbered by the assignment above. Everything downstream
+# (iterations, tokens, cost, time) derives from the complexity variable, so the
+# whole estimate becomes consistent with what the run will actually do.
+if forced_complexity:
+    complexity = forced_complexity
+    complexity_reasons.insert(0, 'Complexity forced via LOKI_COMPLEXITY=' + _forced_complexity_raw)
+
 # --- Estimate iterations ---
 iteration_map = {
     'simple': (3, 5),
@@ -13215,7 +13422,10 @@ if ui_count > 0:
 color = {'simple': GREEN, 'moderate': YELLOW, 'complex': RED, 'enterprise': RED}
 cx_color = color.get(complexity, NC)
 print(f'\n{CYAN}Complexity{NC}')
-print(f'  Tier: {cx_color}{BOLD}{complexity.upper()}{NC} (score: {complexity_score})')
+if forced_complexity:
+    print(f'  Tier: {cx_color}{BOLD}{complexity.upper()}{NC} (forced via LOKI_COMPLEXITY={_forced_complexity_raw})')
+else:
+    print(f'  Tier: {cx_color}{BOLD}{complexity.upper()}{NC} (score: {complexity_score})')
 for reason in complexity_reasons:
     print(f'  {DIM}- {reason}{NC}')
 
@@ -13446,6 +13656,9 @@ main() {
         demo)
             cmd_demo "$@"
             ;;
+        quickstart)
+            cmd_quickstart "$@"
+            ;;
         welcome)
             cmd_welcome "$@"
             ;;

package/autonomy/provider-offer.sh

@@ -0,0 +1,249 @@
+#!/usr/bin/env bash
+# provider-offer.sh -- shared, self-contained provider install offer (v7.29.0).
+#
+# Single source of truth for "no AI provider CLI found" handling, used by BOTH
+# the bash CLI (autonomy/loki, sourced) and the Bun-routed doctor
+# (loki-ts/src/commands/doctor.ts, via child_process). Parity is by
+# construction: there is exactly one prompt + npm install + login handoff
+# implementation, and both routes call it.
+#
+# Self-containment contract (load-bearing for parity): this file depends ONLY
+# on bash builtins + npm/claude on PATH. It defines its own colors and never
+# reads $RED/$NC or any other variable owned by autonomy/loki, because when
+# doctor.ts spawns it standalone those variables are unset. If this file ever
+# starts depending on loki's environment, the bash-route and Bun-route bytes
+# diverge and the bun-parity matrix breaks.
+#
+# Security posture (design 1.7): the ONLY command ever executed on the user's
+# behalf is `npm install -g @anthropic-ai/claude-code`, only after explicit
+# consent, with the exact command printed first. No sudo. No curl-pipe-bash.
+# Non-interactive / CI contexts never run an install.
+
+# Guard against double-source (loki may source this more than once via reloads).
+if [ -n "${_LOKI_PROVIDER_OFFER_SOURCED:-}" ]; then
+    return 0 2>/dev/null || true
+fi
+_LOKI_PROVIDER_OFFER_SOURCED=1
+
+# --- Self-contained colors (honor NO_COLOR; no dependency on loki) ----------
+if [ -n "${NO_COLOR:-}" ] || [ ! -t 1 ]; then
+    _PO_RED=''; _PO_YELLOW=''; _PO_BOLD=''; _PO_DIM=''; _PO_NC=''
+else
+    _PO_RED=$'\033[0;31m'
+    _PO_YELLOW=$'\033[1;33m'
+    _PO_BOLD=$'\033[1m'
+    _PO_NC=$'\033[0m'
+fi
+
+# The one canonical install command. Quoted everywhere; never re-derived.
+_PO_INSTALL_CMD="npm install -g @anthropic-ai/claude-code"
+
+# detect_any_provider: true (0) if any supported provider CLI is on PATH.
+# Extracted verbatim from the loki doctor detection loop (design 1.2).
+detect_any_provider() {
+    local _dp
+    for _dp in claude codex cline aider; do
+        command -v "$_dp" >/dev/null 2>&1 && return 0
+    done
+    return 1
+}
+
+# _po_assume_yes: true when the user has opted into unattended confirmation.
+# Honors --yes (LOKI_AUTO_CONFIRM, set by loki:1013) and LOKI_ASSUME_YES.
+_po_assume_yes() {
+    [ "${LOKI_ASSUME_YES:-}" = "1" ] && return 0
+    [ "${LOKI_AUTO_CONFIRM:-}" = "true" ] && return 0
+    return 1
+}
+
+# _po_non_interactive: true when we must NEVER prompt (non-TTY or CI).
+# Mirrors cmd_welcome_maybe_firstrun (loki:4286) and maybe_show_auto_plan.
+_po_non_interactive() {
+    [ ! -t 1 ] && return 0
+    [ ! -t 0 ] && return 0
+    [ -n "${CI:-}" ] && return 0
+    return 1
+}
+
+# _po_run_login: offer (or auto-accept) the claude auth login handoff after a
+# successful install. Inherited stdio; Loki never handles credentials.
+_po_run_login() {
+    # claude must actually be on PATH for login to make sense.
+    if ! command -v claude >/dev/null 2>&1; then
+        printf "%sInstalled, but 'claude' is not on your PATH yet. You may need to restart your shell or add npm's global bin to PATH (npm config get prefix). Run 'loki doctor' to recheck.%s\n" "$_PO_YELLOW" "$_PO_NC"
+        return 0
+    fi
+
+    local do_login=""
+    if _po_assume_yes; then
+        do_login="y"
+    else
+        printf 'Claude Code installed.\n'
+        printf '\n'
+        printf 'You still need to authenticate. Run the login flow now? [Y/n] '
+        read -r do_login || do_login="n"
+    fi
+    case "$do_login" in
+        ""|y|Y|yes|YES)
+            if claude auth login; then
+                # Do not trust the exit code alone: verify the session is
+                # actually authenticated before claiming readiness (council
+                # HIGH: the old path could falsely report success).
+                if claude auth status 2>/dev/null | grep -q '"loggedIn"[[:space:]]*:[[:space:]]*true'; then
+                    printf "%sProvider ready. Run 'loki doctor' to confirm, or 'loki quickstart' to build.%s\n" "$_PO_BOLD" "$_PO_NC"
+                    return 0
+                fi
+                printf "Login finished but authentication could not be confirmed. Run 'claude auth status' to check, then 'loki doctor'.\n"
+                return 0
+            fi
+            printf "Login not completed. Run 'claude auth login' when ready, then 'loki doctor'.\n"
+            return 0
+            ;;
+        *)
+            printf "Login not completed. Run 'claude auth login' when ready, then 'loki doctor'.\n"
+            return 0
+            ;;
+    esac
+}
+
+# _po_do_install: run the one consented command, print it first, handle result.
+# Returns 0 on success, non-zero on failure (caller decides exit behavior).
+_po_do_install() {
+    printf 'Installing Claude Code (%s) ...\n' "$_PO_INSTALL_CMD"
+    # The exact, fixed argv. No interpolation, no extra flags. (design 1.7)
+    # Capture npm's exit code directly (not via `if`, whose statement status is
+    # 0 when the condition is false with no else, masking the real npm code).
+    local code=0
+    npm install -g @anthropic-ai/claude-code || code=$?
+    if [ "$code" -eq 0 ]; then
+        printf '\n'
+        _po_run_login
+        return 0
+    fi
+    printf '%sInstall failed (npm exited %s). You can retry manually:%s\n' "$_PO_RED" "$code" "$_PO_NC"
+    printf '  %s\n' "$_PO_INSTALL_CMD"
+    printf 'If this is a permissions error, see https://docs.npmjs.com/resolving-eacces-permissions-errors\n'
+    return "$code"
+}
+
+# offer_provider_install <mode>
+#   mode = "report"  -> doctor: append the offer on a TTY; on non-TTY/CI do
+#                       NOTHING (doctor already printed the FAIL + install line,
+#                       and we must keep non-TTY/json bytes identical for parity).
+#                       Never exits the process.
+#   mode = "gate"    -> start/demo/quick pre-flight: on non-TTY/CI print the
+#                       honest one-liner to stderr and return 2. On a TTY, prompt;
+#                       on decline return 2. On accept install + login.
+#
+# Honors:
+#   LOKI_NO_INSTALL_OFFER=1  -> never prompt; print manual command (1.4)
+#   --yes / LOKI_ASSUME_YES  -> auto-accept install + login (1.4)
+offer_provider_install() {
+    local mode="${1:-gate}"
+
+    # Opt-out: never offer, just surface the manual command.
+    if [ "${LOKI_NO_INSTALL_OFFER:-}" = "1" ]; then
+        if [ "$mode" = "gate" ]; then
+            printf 'No AI provider CLI found. Install one when ready:\n' >&2
+            printf '  %s   (then: claude auth login)\n' "$_PO_INSTALL_CMD" >&2
+            return 2
+        fi
+        printf '\n'
+        printf 'Install a provider when ready:\n'
+        printf '  %s   (then: claude auth login)\n' "$_PO_INSTALL_CMD"
+        printf '  Other supported providers: codex, cline, aider.\n'
+        return 0
+    fi
+
+    # Non-interactive / CI: NEVER prompt, NEVER install.
+    #
+    # gate (start/demo/quick): print the honest one-liner to stderr and return 2
+    #   so the caller exits with an actionable message before any spend.
+    # report (doctor): stay SILENT. doctor has already printed the FAIL line and
+    #   the install command on stdout, so no information is lost. Silence here is
+    #   load-bearing for parity: doctor.ts gates its child_process bridge on
+    #   process.stdout.isTTY, so on a non-TTY/CI run the Bun route emits nothing
+    #   extra. If report-mode printed a stderr line, the bash route would diverge
+    #   from Bun in exactly the no-provider/non-TTY case the bun-parity matrix
+    #   captures (2>&1) on CI runners, which have no provider installed.
+    if _po_non_interactive; then
+        if [ "$mode" = "gate" ]; then
+            printf 'No AI provider CLI found; cannot prompt to install in a non-interactive shell. Run: %s\n' "$_PO_INSTALL_CMD" >&2
+            return 2
+        fi
+        return 0
+    fi
+
+    # npm missing: degraded path, never attempt a non-npm install.
+    if ! command -v npm >/dev/null 2>&1; then
+        printf '\n'
+        printf '%sNo AI provider CLI was found, and npm is not installed either, so Loki%s\n' "$_PO_BOLD" "$_PO_NC"
+        printf 'cannot install one for you.\n'
+        printf '\n'
+        printf 'Install Node.js + npm first (https://nodejs.org), then run:\n'
+        printf '  %s\n' "$_PO_INSTALL_CMD"
+        printf '  claude auth login\n'
+        printf '\n'
+        printf "Already have a provider via another method? Make sure 'claude' (or codex,\n"
+        printf "cline, aider) is on your PATH, then run 'loki doctor'.\n"
+        [ "$mode" = "gate" ] && return 2
+        return 0
+    fi
+
+    # TTY, npm present: the interactive offer.
+    printf '\n'
+    printf 'No AI provider CLI was found. Loki needs one agent CLI to run a build.\n'
+    printf '\n'
+    printf 'Claude Code is the recommended provider (full feature support).\n'
+    printf '  Install:  %s\n' "$_PO_INSTALL_CMD"
+    printf '  Then:     claude auth login\n'
+    printf '\n'
+
+    local answer=""
+    if _po_assume_yes; then
+        answer="y"
+    else
+        printf 'Install Claude Code now? [Y/n] '
+        read -r answer || answer="n"
+    fi
+
+    case "$answer" in
+        ""|y|Y|yes|YES)
+            if _po_do_install; then
+                return 0
+            fi
+            # Install failed: honest failure already printed by _po_do_install.
+            [ "$mode" = "gate" ] && return 2
+            return 1
+            ;;
+        *)
+            printf 'Skipped. Install a provider when ready:\n'
+            printf '  %s   (then: claude auth login)\n' "$_PO_INSTALL_CMD"
+            printf 'Other supported providers: codex, cline, aider.\n'
+            [ "$mode" = "gate" ] && return 2
+            return 0
+            ;;
+    esac
+}
+
+# provider_offer_gate: convenience wrapper for the start/demo/quick pre-flight.
+# Returns 0 if a provider is present (or one was just installed); returns 2 to
+# signal the caller should `exit 2` (no provider, declined or non-interactive).
+provider_offer_gate() {
+    detect_any_provider && return 0
+    offer_provider_install gate || return 2
+    # After an accepted install, re-detect; if still absent, fail the gate.
+    detect_any_provider && return 0
+    return 2
+}
+
+# Executed directly (doctor.ts child_process bridge, or manual): run the offer.
+# When sourced by autonomy/loki, this block does not run.
+if [ "${BASH_SOURCE[0]}" = "$0" ]; then
+    case "${1:-report}" in
+        offer|report) offer_provider_install report ;;
+        gate)         offer_provider_install gate ;;
+        detect)       detect_any_provider ;;
+        *)            offer_provider_install report ;;
+    esac
+fi