loki-mode 7.91.1 → 7.93.0

package/autonomy/run.sh

@@ -1050,6 +1050,179 @@ log_error() { echo -e "${RED}[ERROR]${NC} $*"; }
 log_step() { echo -e "${CYAN}[STEP]${NC} $*"; }
 log_debug() { [[ "${LOKI_DEBUG:-}" == "true" ]] && echo -e "${CYAN}[DEBUG]${NC} $*" >&2 || true; }
 
+#===============================================================================
+# Failure diagnosis helpers (T2.4 / T2.5 / T2.6)
+#
+# These make a failing or crashed build self-explanatory: a copy-pasteable
+# "loki why" hint on any non-zero exit, a durable CLASSIFIED LAST_ERROR record
+# on a failed iteration, and a best-effort terminal record on an untrapped
+# death. Every one is best-effort and NEVER alters the build's exit code.
+#===============================================================================
+
+# _loki_surface_why_hint (T2.4): print the "loki why" hint to stderr and write
+# it to .loki/NEXT_STEPS.txt. Called once from main() finalization when the run
+# failed (result != 0). Best-effort: never crashes, never changes exit code.
+_loki_surface_why_hint() {
+    local loki_dir="${TARGET_DIR:-.}/.loki"
+    local hint="For a plain-language diagnosis of what happened, run: loki why"
+    printf '%s\n' "$hint" >&2 || true
+    mkdir -p "$loki_dir" 2>/dev/null || true
+    printf '%s\n' "$hint" > "$loki_dir/NEXT_STEPS.txt" 2>/dev/null || true
+    return 0
+}
+
+# _loki_write_last_error (T2.5): write a durable, classified failure record to
+# .loki/state/LAST_ERROR.json. Schema:
+#   {
+#     "iteration":   <int>,
+#     "error_class": "provider_empty_output"|"build_timeout"|"rate_limited"
+#                    |"auth_error"|"unknown",
+#     "brief":       "<one honest sentence>",
+#     "timestamp":   "<UTC ISO-8601>"
+#   }
+# This is what `loki why` (in autonomy/loki, NOT owned here) can later read.
+# Built via python3 so the free-text brief can never break the JSON. Entirely
+# best-effort: any failure is swallowed and the build is never crashed.
+# Usage: _loki_write_last_error <iteration> <error_class> <brief>
+_loki_write_last_error() {
+    local iteration="${1:-0}"
+    local error_class="${2:-unknown}"
+    local brief="${3:-An iteration failed.}"
+    local loki_dir="${TARGET_DIR:-.}/.loki"
+    local state_dir="$loki_dir/state"
+    mkdir -p "$state_dir" 2>/dev/null || true
+    LOKI_LE_ITER="$iteration" \
+    LOKI_LE_CLASS="$error_class" \
+    LOKI_LE_BRIEF="$brief" \
+    LOKI_LE_FILE="$state_dir/LAST_ERROR.json" \
+    python3 -c "
+import json, os, tempfile
+try:
+    rec = {
+        'iteration': int(os.environ.get('LOKI_LE_ITER', '0') or 0),
+        'error_class': os.environ.get('LOKI_LE_CLASS', 'unknown'),
+        'brief': os.environ.get('LOKI_LE_BRIEF', ''),
+        'timestamp': __import__('datetime').datetime.utcnow().strftime('%Y-%m-%dT%H:%M:%SZ'),
+    }
+    target = os.environ['LOKI_LE_FILE']
+    d = os.path.dirname(target)
+    fd, tmp = tempfile.mkstemp(dir=d, suffix='.json')
+    with os.fdopen(fd, 'w') as f:
+        json.dump(rec, f)
+    os.replace(tmp, target)
+except Exception:
+    pass
+" 2>/dev/null || true
+    return 0
+}
+
+# _loki_classify_iteration_error (T2.5 helper): map an iteration's signals to one
+# of the LAST_ERROR error_class values. Conservative: only returns a specific
+# class when a signal confidently supports it, else "unknown". Never fabricates
+# build_timeout (no timeout signal is detected here, so it is reserved for a
+# caller that has one). Echoes the class on stdout.
+# Usage: _loki_classify_iteration_error <iter_output_file> <empty_output_flag 0|1>
+_loki_classify_iteration_error() {
+    local iter_output="${1:-}"
+    local empty_flag="${2:-0}"
+    if [ "$empty_flag" = "1" ]; then
+        echo "provider_empty_output"
+        return 0
+    fi
+    # Rate limit: reuse the same detector the retry path uses.
+    if [ -n "$iter_output" ] && [ -f "$iter_output" ] && detect_rate_limit "$iter_output" 2>/dev/null | grep -qE '^[1-9]'; then
+        echo "rate_limited"
+        return 0
+    fi
+    # Auth error: a clear 401/403/unauthorized in the output tail.
+    if [ -n "$iter_output" ] && [ -f "$iter_output" ]; then
+        local _tail
+        _tail="$(tail -n 40 "$iter_output" 2>/dev/null || true)"
+        if printf '%s\n' "$_tail" | grep -qiE '(http[ /]?40[13]|status[: ]+40[13]|unauthorized|invalid api key|authentication[_ ]error|401 )' 2>/dev/null; then
+            echo "auth_error"
+            return 0
+        fi
+    fi
+    echo "unknown"
+    return 0
+}
+
+# _loki_terminal_record (T2.6, SAFE SUBSET): on an untrapped exit where the
+# persisted run status is still "running" (a true mid-provider-call crash on a
+# trappable signal -- SIGTERM/SIGINT/SIGHUP via the lock-release trap), leave a
+# best-effort, classified LAST_ERROR record so a post-crash `loki why` is not
+# stale. Piggybacks the existing lock-release EXIT trap (see main()) -- it does
+# NOT install a new broad EXIT trap.
+#
+# IMPORTANT (why this does NOT rewrite autonomy-state.json): the resume-detection
+# block in this file (search "Durable resume") keys the ENT-2 pod-loss resume on
+# prev_status == "running". Flipping the status to "exited" here would make a
+# crashed-but-resumable build (LOKI_DURABLE_STATE=1) reset to iteration 0 on the
+# next start, destroying durable progress. So this writes ONLY the LAST_ERROR
+# side-record (which is what `loki why` reads) and deliberately leaves the
+# status untouched. SIGKILL / power-loss are uncatchable (no trap fires); the
+# ENT-2 durable-resume path covers those. Never alters the exit code; best-effort.
+_loki_terminal_record() {
+    local state_file
+    state_file="$(_loki_state_file 2>/dev/null)" || return 0
+    [ -n "$state_file" ] || return 0
+    [ -f "$state_file" ] || return 0
+    local _status
+    _status="$(LOKI_TR_FILE="$state_file" python3 -c "
+import json, os
+try:
+    print(json.load(open(os.environ['LOKI_TR_FILE'])).get('status','unknown'))
+except Exception:
+    print('unknown')
+" 2>/dev/null || echo "unknown")"
+    # Only act on a genuinely mid-flight "running" status. Any settled status
+    # (council_approved, failed, exited, paused, ...) is left untouched.
+    [ "$_status" = "running" ] || return 0
+    # Leave a classified LAST_ERROR so `loki why` has something honest -- WITHOUT
+    # touching autonomy-state.json (preserving the ENT-2 "running" resume signal).
+    _loki_write_last_error "${ITERATION_COUNT:-0}" "unknown" \
+        "The build process exited unexpectedly before finishing (possible crash or kill)." 2>/dev/null || true
+    return 0
+}
+
+# _loki_write_rate_limit_signal (T2.7): write a best-effort
+# .loki/signals/RATE_LIMITED file. This is FORWARD-LAID infrastructure: no
+# consumer reads it yet (a future dashboard / external watcher could, to tell a
+# normal provider rate-limit wait apart from a hang). The user-visible signal
+# today is the log_info line at the wait site; this file is the durable record. Schema:
+#   {"rate_limited": true, "wait_seconds": <int>, "reset_time": "<string>"}
+# Built via python3 so the reset-time string can never break the JSON. Entirely
+# best-effort: never crashes, never alters the build.
+# Usage: _loki_write_rate_limit_signal <wait_seconds> <reset_time>
+_loki_write_rate_limit_signal() {
+    local wait_seconds="${1:-0}"
+    local reset_time="${2:-}"
+    local signals_dir="${TARGET_DIR:-.}/.loki/signals"
+    mkdir -p "$signals_dir" 2>/dev/null || true
+    LOKI_RL_WAIT="$wait_seconds" \
+    LOKI_RL_RESET="$reset_time" \
+    LOKI_RL_FILE="$signals_dir/RATE_LIMITED" \
+    python3 -c "
+import json, os, tempfile
+try:
+    w = os.environ.get('LOKI_RL_WAIT', '0')
+    try:
+        w = int(w)
+    except Exception:
+        w = 0
+    rec = {'rate_limited': True, 'wait_seconds': w, 'reset_time': os.environ.get('LOKI_RL_RESET', '')}
+    target = os.environ['LOKI_RL_FILE']
+    d = os.path.dirname(target)
+    fd, tmp = tempfile.mkstemp(dir=d, suffix='.json')
+    with os.fdopen(fd, 'w') as f:
+        json.dump(rec, f)
+    os.replace(tmp, target)
+except Exception:
+    pass
+" 2>/dev/null || true
+    return 0
+}
+
 # Live Build HUD (v7.71.0): a single append-only per-iteration status line on the
 # interactive TTY path. Pure additive stdout decoration -- never piped into any
 # tee, so the dashboard agent.log and the stream-json parser are untouched. The
@@ -1798,9 +1971,93 @@ get_iteration_duration_ms() {
 # Supports Docker/K8s secret file mounts as fallback.
 #===============================================================================
 
+# Zero-friction preflight helpers (T1.1). These run for ALL environments
+# (not just Docker/K8s) BEFORE the build starts, via validate_api_keys. git is a
+# genuine hard requirement (the build inits a repo) so a missing git BLOCKS with a
+# copy-pasteable fix; node-version and network reachability are ADVISORY (warn and
+# continue, fail-open) so a probabilistic or optional signal never blocks a working
+# user. The goal: surface real problems early without ever wrongly refusing to start.
+#
+# _loki_check_node_version: ADVISORY only. If node is present and its major
+# version is < 18, log a warning (node only matters for node-based builds) and
+# continue. If node is absent entirely this is a NO-OP. Always returns 0 -- it
+# never blocks the build (fail-open); the real node call, if any, is the test.
+_loki_check_node_version() {
+    command -v node >/dev/null 2>&1 || return 0
+    local node_version major
+    node_version="$(node --version 2>/dev/null || echo '')"
+    # node --version -> "v20.11.0"; extract the leading major integer.
+    major="$(printf '%s' "$node_version" | sed -E 's/^v?([0-9]+).*/\1/')"
+    # Advisory only: node is OPTIONAL (absence is a no-op above, and many builds -
+    # Python/Go/Rust - never touch node). A present-but-old node only matters for
+    # node-based builds, so WARN and continue (fail-open); never hard-block a
+    # working user. The actual node call (only for JS/TS work) is the real test.
+    if [ -n "$major" ] && [[ "$major" =~ ^[0-9]+$ ]] && [ "$major" -lt 18 ]; then
+        log_warn "Node.js >= 18 recommended for node-based builds; found ${node_version:-unknown}. Upgrade if your project uses node: https://nodejs.org"
+    fi
+    return 0
+}
+
+# _loki_check_git_present: the build initializes a git repo, so git is required.
+_loki_check_git_present() {
+    if ! command -v git >/dev/null 2>&1; then
+        log_error "Git is required (the build initializes a repo). Install: https://git-scm.com/downloads"
+        return 1
+    fi
+    return 0
+}
+
+# _loki_check_network_reachable: ADVISORY only. A fast (3s) reachability probe to
+# the active provider endpoint that WARNS and continues if it cannot reach it -- a
+# curl failure does not prove the provider CLI cannot connect (3s timeout under
+# load, transient DNS, or a proxy set for the CLI but not the shell all curl-fail
+# while the real build succeeds). Always returns 0 (fail-open); the actual
+# provider call is the authoritative connectivity test. Skipped entirely when curl
+# is missing, when LOKI_SKIP_NET_PREFLIGHT=1, when ANTHROPIC_BASE_URL is set (alt
+# provider endpoint we cannot assume), or for any provider whose endpoint we do
+# not know. It NEVER blocks the build.
+_loki_check_network_reachable() {
+    local provider="${1:-claude}"
+    [ "${LOKI_SKIP_NET_PREFLIGHT:-}" = "1" ] && return 0
+    command -v curl >/dev/null 2>&1 || return 0
+    # Alternate provider base URL set -> do not assume the default endpoint.
+    [ -n "${ANTHROPIC_BASE_URL:-}" ] && return 0
+
+    local endpoint=""
+    case "$provider" in
+        claude) endpoint="https://api.anthropic.com" ;;
+        *)      return 0 ;;  # unknown endpoint -> fail open, never guess
+    esac
+
+    # Advisory only: a fast curl probe failing does NOT prove the provider CLI
+    # cannot connect (a 3s timeout under load, transient DNS, or a proxy set for
+    # the CLI but not the shell all curl-fail while the real build succeeds). WARN
+    # and continue - the actual provider call is the authoritative connectivity
+    # test. Silence this with LOKI_SKIP_NET_PREFLIGHT=1. Never hard-block here.
+    if ! curl -sS -m 3 -o /dev/null "$endpoint" 2>/dev/null; then
+        log_warn "Could not verify network reachability to the AI provider (firewall/VPN/transient?). Continuing; the provider call will be the real test. Silence with LOKI_SKIP_NET_PREFLIGHT=1."
+    fi
+    return 0
+}
+
 validate_api_keys() {
     local provider="${LOKI_PROVIDER:-claude}"
 
+    # Zero-friction preflight (T1.1): toolchain + reachability checks that apply
+    # to EVERY environment, run BEFORE the Docker/K8s early-return below so they
+    # are not silently skipped in the common local case. Node/git are genuinely
+    # required (node only when present-but-too-old); the network probe is
+    # fail-open and opt-out (LOKI_SKIP_NET_PREFLIGHT=1).
+    if ! _loki_check_node_version; then
+        return 1
+    fi
+    if ! _loki_check_git_present; then
+        return 1
+    fi
+    if ! _loki_check_network_reachable "$provider"; then
+        return 1
+    fi
+
     # CLI tools (claude, codex, cline, aider) use their own login sessions.
     # Only require API keys inside Docker/K8s where CLI login isn't available.
     if [[ ! -f "/.dockerenv" ]] && [[ -z "${KUBERNETES_SERVICE_HOST:-}" ]]; then
@@ -16170,9 +16427,13 @@ if __name__ == "__main__":
         esac
 
         # BUG-EC-013: Detect empty provider output (0 bytes = no work done)
+        # T2.5: track this distinct cause so the failure path can classify the
+        # durable LAST_ERROR record as provider_empty_output specifically.
+        local _empty_output=0
         if [ -f "$iter_output" ] && [ ! -s "$iter_output" ] && [ $exit_code -eq 0 ]; then
             log_warn "Provider returned empty output (0 bytes) despite exit code 0 -- treating as error"
             exit_code=1
+            _empty_output=1
         fi
 
         save_state $retry "exited" $exit_code
@@ -16967,6 +17228,24 @@ else:
         # the "Will retry" log_warn below. TTY-gated, `|| true`, never tee'd.
         render_build_hud "${ITERATION_COUNT:-0}" "${rarv_phase:-?}" "${duration:-0}" || true
 
+        # T2.5: durable, classified failure record for `loki why`. Best-effort,
+        # never crashes the build. Skip signal-induced exits (130 SIGINT /
+        # 143 SIGTERM / 137 SIGKILL): a user/operator interrupt is not an error
+        # to record (mirrors the crash-capture exclusion above). Classification
+        # is conservative -- provider_empty_output | rate_limited | auth_error,
+        # else unknown; never fabricates a class that no signal supports.
+        if [ "$exit_code" -ne 130 ] && [ "$exit_code" -ne 143 ] && [ "$exit_code" -ne 137 ]; then
+            local _err_class _err_brief
+            _err_class="$(_loki_classify_iteration_error "$iter_output" "${_empty_output:-0}")"
+            case "$_err_class" in
+                provider_empty_output) _err_brief="The provider returned no output (0 bytes) on this iteration -- no work was done." ;;
+                rate_limited)          _err_brief="The provider rate-limited the request; the build will wait and retry." ;;
+                auth_error)            _err_brief="The provider rejected the request as unauthorized (check your login or API key)." ;;
+                *)                     _err_brief="Iteration ${ITERATION_COUNT:-?} failed with exit code ${exit_code} (cause not classified)." ;;
+            esac
+            _loki_write_last_error "${ITERATION_COUNT:-0}" "$_err_class" "$_err_brief" || true
+        fi
+
         # Checkpoint failed iteration state (v5.57.0)
         create_checkpoint "iteration-${ITERATION_COUNT} failed (exit=$exit_code)" "iteration-${ITERATION_COUNT}-fail"
 
@@ -16986,7 +17265,15 @@ else:
             wait_time=$rate_limit_wait
             local human_time=$(format_duration $wait_time)
             log_warn "Rate limit detected! Waiting until reset (~$human_time)..."
-            log_info "Rate limit resets at approximately $(date -v+${wait_time}S '+%I:%M %p' 2>/dev/null || date -d "+${wait_time} seconds" '+%I:%M %p' 2>/dev/null || echo 'soon')"
+            local _reset_at
+            _reset_at="$(date -v+${wait_time}S '+%I:%M %p' 2>/dev/null || date -d "+${wait_time} seconds" '+%I:%M %p' 2>/dev/null || echo 'soon')"
+            log_info "Rate limit resets at approximately $_reset_at"
+            # T2.7: elevate the wait to an explicit, reassuring INFO line (the
+            # human time was previously only at DEBUG inside detect_rate_limit's
+            # calculated-backoff branch) so a multi-minute wait does not look
+            # like a hang, and persist a machine-readable signal for watchers.
+            log_info "Rate-limited by the provider; waiting ~${wait_time}s (resets ${_reset_at}). This is normal, not a hang."
+            _loki_write_rate_limit_signal "$wait_time" "$_reset_at" || true
             notify_rate_limit "$wait_time"
         else
             wait_time=$(calculate_wait $retry)
@@ -17026,6 +17313,10 @@ else:
         done
         echo ""
 
+        # T2.7: the wait is over -- clear the RATE_LIMITED signal so it never
+        # lingers stale once the build resumes. Best-effort.
+        rm -f "${TARGET_DIR:-.}/.loki/signals/RATE_LIMITED" 2>/dev/null || true
+
         # Clean up per-iteration output file
         rm -f "$iter_output" 2>/dev/null
 
@@ -18010,8 +18301,15 @@ main() {
         fi
         # Release on session-process exit so a fresh `loki start` can
         # immediately re-acquire after this one finishes / is killed.
+        # T2.6: piggyback the existing lock-release trap (we deliberately do NOT
+        # add a new broad EXIT trap) to write a best-effort terminal record on an
+        # untrapped non-zero exit where the run status is still "running" -- so a
+        # post-crash `loki why` is not stale. _loki_terminal_record is a strict
+        # no-op on every graceful path (status already settled) and never alters
+        # the exit code. SIGKILL/power-loss stay uncatchable (no trap fires); the
+        # ENT-2 durable-resume path covers those.
         # shellcheck disable=SC2064
-        trap "safe_release_lock '$lock_file'" EXIT INT TERM HUP
+        trap "_loki_terminal_record || true; safe_release_lock '$lock_file'" EXIT INT TERM HUP
 
         # Check PID file after acquiring lock
         if [ -f "$pid_file" ]; then
@@ -18174,6 +18472,13 @@ main() {
         fi
     fi
 
+    # Clear any stale per-run diagnosis record from a PRIOR run before this one
+    # starts. LAST_ERROR.json is a single side-record; if it survived a previous
+    # failed run it must not surface next to THIS run's outcome (a stale error
+    # shown beside a fresh success would be a fake-green-adjacent lie). Mirrors
+    # the RATE_LIMITED signal clear. Best-effort; never blocks the run.
+    rm -f "${TARGET_DIR:-.}/.loki/state/LAST_ERROR.json" 2>/dev/null || true
+
     if [ "$PARALLEL_MODE" = "true" ]; then
         # Parallel mode: orchestrate multiple worktrees
         log_header "Running in Parallel Mode"
@@ -18423,6 +18728,13 @@ except (json.JSONDecodeError, OSError): pass
 " 2>/dev/null || true
     fi
 
+    # T2.4: on ANY non-zero final result, surface a plain-language next step
+    # (print to stderr + write .loki/NEXT_STEPS.txt). Single chokepoint at the
+    # finalization exit so it fires once and never double-prints on success.
+    if [ "$result" != "0" ]; then
+        _loki_surface_why_hint || true
+    fi
+
     exit $result
 }
 

package/dashboard/__init__.py

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

package/dashboard/server.py

@@ -667,7 +667,14 @@ async def _push_loki_state_loop() -> None:
                             "running_agents": running_agents,
                             "pending_tasks": len(pending) if isinstance(pending, list) else 0,
                             "current_task": in_prog[0].get("payload", {}).get("action", "") if isinstance(in_prog, list) and in_prog else "",
-                            "version": raw.get("version", ""),
+                            # Version reflects the RUNNING engine, not the project's
+                            # stored state. raw.get("version") is whatever engine
+                            # last wrote dashboard-state.json for THIS project (can
+                            # be an old version, e.g. a project first built under
+                            # 7.7.29), which made the displayed version flip between
+                            # this stale value and the live one from the fallback
+                            # path below. Always use the live engine version.
+                            "version": _version,
                         }
                         await manager.broadcast({
                             "type": "status_update",
@@ -705,14 +712,10 @@ async def _push_loki_state_loop() -> None:
                                 pass
 
                         if _sk_fresh:
-                            # Read version from VERSION file
-                            _sk_version = ""
-                            _vf = _Path(os.path.dirname(os.path.dirname(__file__))) / "VERSION"
-                            if _vf.is_file():
-                                try:
-                                    _sk_version = _vf.read_text().strip()
-                                except OSError:
-                                    pass
+                            # Version reflects the running engine (single source of
+                            # truth), the same value the dashboard-state path uses
+                            # above, so the displayed version never flips.
+                            _sk_version = _version
 
                             # Read orchestrator state
                             _sk_phase = ""
@@ -1106,17 +1109,10 @@ async def get_status() -> StatusResponse:
     loki_dir = _get_loki_dir()
     uptime = (datetime.now(timezone.utc) - start_time).total_seconds()
 
-    # Read VERSION file early (independent of .loki/ dir)
-    version = "unknown"
-    dashboard_dir = os.path.dirname(__file__)
-    project_root = os.path.dirname(dashboard_dir)
-    version_file = os.path.join(project_root, "VERSION")
-    if os.path.isfile(version_file):
-        try:
-            with open(version_file) as vf:
-                version = vf.read().strip()
-        except (OSError, IOError) as e:
-            logger.warning(f"Failed to read VERSION file: {e}")
+    # Version reflects the running engine (single source of truth: the package
+    # __version__, same value every status path uses) so the displayed version is
+    # always the live engine, never a stale per-project value.
+    version = _version
 
     # If .loki/ directory doesn't exist, return idle status immediately
     if not loki_dir.is_dir():
@@ -8784,6 +8780,157 @@ def _reconcile_app_runner_liveness(state):
     return state
 
 
+# Per-probe TCP connect timeout (seconds) for the single-process port probe.
+# Kept short so a stopped/firewalled port fails fast and the status endpoint
+# stays responsive for the dashboard's 3-5s pollers.
+_APP_RUNNER_PORT_PROBE_TIMEOUT = 1.0
+
+
+def _port_is_serving(port):
+    """True only if a TCP connection to 127.0.0.1:<port> genuinely succeeds.
+
+    Honest by construction: this proves *something* is accepting connections on
+    the recorded port right now, never fabricates a result. Any failure (refused,
+    timeout, bad port, OS error) returns False so the caller degrades to an
+    honest non-running state. Synchronous; the caller offloads it to a worker
+    thread so the event loop is never blocked by the connect.
+    """
+    try:
+        port = int(port)
+    except (TypeError, ValueError):
+        return False
+    if port <= 0 or port > 65535:
+        return False
+    import socket
+    for host in ("127.0.0.1", "::1"):
+        sock = None
+        try:
+            family = socket.AF_INET6 if ":" in host else socket.AF_INET
+            sock = socket.socket(family, socket.SOCK_STREAM)
+            sock.settimeout(_APP_RUNNER_PORT_PROBE_TIMEOUT)
+            if sock.connect_ex((host, port)) == 0:
+                return True
+        except OSError:
+            continue
+        finally:
+            if sock is not None:
+                try:
+                    sock.close()
+                except OSError:
+                    pass
+    return False
+
+
+def _dashboard_self_port():
+    """The TCP port this dashboard process itself is bound to, or None.
+
+    The user's app can never listen on the port the dashboard already occupies,
+    so this is used to exclude a self-hit from the single-process probe (a stale
+    recorded port that happens to equal the dashboard's port would otherwise
+    probe-succeed against the dashboard and be misreported as the app running).
+    Reads LOKI_DASHBOARD_PORT (the same env run_server binds), defaulting to the
+    well-known 57374. Returns an int or None.
+    """
+    try:
+        return int(os.environ.get("LOKI_DASHBOARD_PORT", "57374"))
+    except (TypeError, ValueError):
+        return 57374
+
+
+def _recorded_app_port(state):
+    """Best-effort recorded port for the single-process app, or None.
+
+    Reads the port the app-runner/CLI already recorded for THIS project, never a
+    guessed value: first state.json's own `port`, then the app-runner
+    detection.json the engine writes (`.loki/app-runner/detection.json`). Returns
+    an int in the valid range or None. Pairing the probe to a *recorded* port is
+    what keeps the result honest -- we never sweep arbitrary common ports.
+
+    Honesty guards:
+      - A docker-compose detection.json is ignored here; a compose stack is the
+        compose-discovery path's domain (which verifies the container belongs to
+        the project), so feeding its port into the single-process probe would
+        risk a false positive against an unrelated local service.
+      - The dashboard's own port is never returned, since the user's app cannot
+        bind it and a stale recorded value equal to it would self-hit the probe.
+    """
+    self_port = _dashboard_self_port()
+
+    def _ok(p):
+        try:
+            p = int(p)
+        except (TypeError, ValueError):
+            return None
+        if not (0 < p <= 65535):
+            return None
+        if self_port is not None and p == self_port:
+            return None
+        return p
+
+    if isinstance(state, dict):
+        p = _ok(state.get("port"))
+        if p is not None:
+            return p
+    try:
+        det_file = _get_loki_dir() / "app-runner" / "detection.json"
+        if det_file.is_file():
+            det = json.loads(det_file.read_text())
+            if isinstance(det, dict) and not det.get("is_docker"):
+                p = _ok(det.get("port"))
+                if p is not None:
+                    return p
+    except (OSError, ValueError, TypeError, json.JSONDecodeError):
+        pass
+    return None
+
+
+def _discover_single_process_app_runner_state(state):
+    """Detect a genuinely-running single-process app via a recorded-port probe.
+
+    A SKILL/CLI-built project (e.g. one started with `npm run dev` outside
+    app-runner.sh, or whose orchestrator has since exited) leaves a state.json
+    with status "stopped"/"stale" and main_pid 0, even while the app itself is
+    still serving. The dashboard would then report "not running" for a live app.
+
+    Resolution (all probe-verified, never fabricated):
+      - Find the RECORDED port (state.json.port or non-docker detection.json) --
+        never a guessed port, and never the dashboard's own port.
+      - Probe 127.0.0.1:<port>. Only if the connection genuinely succeeds do we
+        synthesize a "running" state using the recorded url/port.
+      - Otherwise (no recorded port, or recorded port not reachable) return None;
+        the caller keeps the honest reconciled state, which already carries
+        positive evidence (the writer's settled "stopped", or a pid_gone /
+        recycled / health_stale downgrade). "Unknown" would be less honest than
+        that evidence, so we never override it here.
+
+    Synchronous and self-contained; the caller offloads it onto a worker thread.
+    Never raises.
+    """
+    try:
+        port = _recorded_app_port(state)
+        if not port:
+            return None
+        if not _port_is_serving(port):
+            return None
+        url = ""
+        if isinstance(state, dict):
+            url = state.get("url") or ""
+        if not url:
+            url = "http://localhost:{}".format(port)
+        return {
+            "status": "running",
+            "url": url,
+            "port": int(port),
+            "method": (state.get("method") if isinstance(state, dict) else "") or "",
+            "source": "probe",
+            "externally_managed": True,
+            "last_health": {"ok": True},
+        }
+    except Exception:
+        # Fail open: never let the probe break the status endpoint.
+        return None
+
+
 # =============================================================================
 # Docker-compose app-runner discovery
 #
@@ -9191,6 +9338,10 @@ async def get_app_runner_status():
         discovered = await asyncio.to_thread(_discover_compose_app_runner_state)
         if discovered is not None:
             return discovered
+        # No state.json at all and no compose stack: there is no recorded port to
+        # probe, so the single-process probe can only ever return an honest
+        # "unknown" here. Keep returning not_initialized (the project has never
+        # had an app-runner record) rather than overstating with "unknown".
         return {"status": "not_initialized"}
 
     try:
@@ -9208,6 +9359,14 @@ async def get_app_runner_status():
     discovered = await asyncio.to_thread(_discover_compose_app_runner_state)
     if discovered is not None:
         return discovered
+
+    # Still nothing from compose: a SKILL/CLI-built project may be serving on its
+    # recorded port even though no live app-runner.sh process owns it (main_pid 0
+    # / orchestrator exited). Probe the RECORDED port and only report running when
+    # the port genuinely answers; otherwise keep the honest reconciled state.
+    probed = await asyncio.to_thread(_discover_single_process_app_runner_state, state)
+    if isinstance(probed, dict) and probed.get("status") == "running":
+        return probed
     return reconciled