loki-mode 7.41.5 → 7.42.0

package/README.md

@@ -29,7 +29,7 @@ _The free, source-available autonomous coding agent by [Autonomi](https://www.au
 - **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).
-- **Mid-flight model switching + Claude Fable tier** -- switch the model a live run uses from the dashboard (applies at the next iteration, current run only), with Claude Fable available as a premium tier at its published $10/$50 per MTok (2x Opus). For every model lever (session pin to Fable, mid-flight override, architect pass) and every `LOKI_MAX_TIER` path, the `loki plan` quote, the dashboard's reported model, and the actual dispatched model agree, with the ceiling enforced (v7.31.0).
+- **Mid-flight model switching** -- switch the model a live run uses from the dashboard (applies at the next iteration, current run only). A Fable tier lever exists in the CLI, dashboard, and override paths, but Claude Fable 5 is not yet available at the API, so selecting Fable currently collapses to Opus at every dispatch chokepoint and the `loki plan` quote reflects Opus accordingly. For every model lever (session pin, mid-flight override, architect pass) and every `LOKI_MAX_TIER` path, the `loki plan` quote, the dashboard's reported model, and the actual dispatched model agree, with the ceiling enforced (v7.31.0; Fable-to-Opus collapse v7.39.1).
 - **A calmer CLI** -- the help surface is ~20 grouped workflow entries instead of a 70-command wall; merged commands live on as aliases that forward byte-identically with a one-line stderr pointer, so no script breaks (v7.31.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).
@@ -391,6 +391,23 @@ Run `loki --help` for all options. Full reference: [CLI Reference](wiki/CLI-Refe
 
 ---
 
+<details>
+<summary><strong>Configuration env vars (intelligent defaults, opt-out knobs)</strong></summary>
+
+Loki Mode's accuracy and autonomy behaviors are default-on. Each is an opt-out escape hatch, not a setting you have to discover. The most relevant knobs from the v7.41.x accuracy/autonomy hardening:
+
+| Env var | Default | Effect |
+|---------|---------|--------|
+| `LOKI_REVIEW_INCONCLUSIVE_BLOCK` | `1` | Blocks completion when a code-review round returns zero usable verdicts (an all-empty review proves nothing). Set `0` to record the inconclusive result without blocking. |
+| `LOKI_COMPLETION_TEST_CAPTURE` | `1` | Captures fresh test results before the verified-completion evidence gate evaluates. Set `0` to skip the pre-gate capture. |
+| `LOKI_AUTO_DOCS` | `true` | Generates the `.loki/docs/` suite before the documentation gate scores it (bounded: once per run when docs are missing, and again only when >10 commits stale). Set `false` to opt out. |
+| `LOKI_CAVEMAN` | `1` (on) | Output-token compressor for free-form generation only (never trust-gate subcalls). Set `0` to opt out. |
+| `LOKI_CAVEMAN_LEVEL` | inferred | Compression level for the compressor. Auto-inferred per invocation from the run's RARV tier; set explicitly (`lite` / `full` / `ultra`) to override the inference. |
+
+This is a subset. See the [wiki](wiki/Home.md) for the full env-var reference and the RARV-C closure knobs (`LOKI_INJECT_FINDINGS`, `LOKI_OVERRIDE_COUNCIL`, `LOKI_AUTO_LEARNINGS`, `LOKI_HANDOFF_MD`).
+
+</details>
+
 <details>
 <summary><strong>BMAD Method Integration</strong></summary>
 

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.41.5
+# Loki Mode v7.42.0
 
 **You are an autonomous agent. You make decisions. You do not ask questions. You do not stop.**
 
@@ -398,4 +398,4 @@ See `CHANGELOG.md` entries [7.5.7], [7.5.8], [7.5.13] for the per-fix list and r
 
 ---
 
-**v7.41.5 | [Autonomi](https://www.autonomi.dev/) flagship product | ~260 lines core**
+**v7.42.0 | [Autonomi](https://www.autonomi.dev/) flagship product | ~260 lines core**

package/VERSION

@@ -1 +1 @@
-7.41.5
+7.42.0

package/autonomy/completion-council.sh

@@ -710,8 +710,18 @@ print('true' if ratio > budget else 'false')
         ((member++))
     done
 
-    # Anti-sycophancy check: if unanimous APPROVE, run devil's advocate
+    # Anti-sycophancy check: if unanimous APPROVE, run devil's advocate.
+    #
+    # Audit-trail snapshots (these do NOT affect the live vote): capture whether
+    # the council was unanimous BEFORE the decrement below, and whether the DA
+    # actually fired and flipped the verdict. The transcript fields
+    # _ct_triggered/_ct_flipped used to be re-derived from approve_count AFTER
+    # this block decremented it, so on rounds where the DA fired AND flipped they
+    # were mis-recorded as false/false, corrupting the trust-metrics audit trail.
+    local _da_was_unanimous="false"
+    local _da_flipped="false"
     if [ $approve_count -eq $COUNCIL_SIZE ] && [ $COUNCIL_SIZE -ge 2 ]; then
+        _da_was_unanimous="true"
         log_warn "Unanimous approval detected - running anti-sycophancy check..."
         local contrarian_verdict
         contrarian_verdict=$(council_devils_advocate "$evidence_file" "$vote_dir")
@@ -731,6 +741,7 @@ print('true' if ratio > budget else 'false')
             log_warn "Overriding to require one more iteration for verification"
             approve_count=$((approve_count - 1))
             reject_count=$((reject_count + 1))
+            _da_flipped="true"
         fi
     fi
 
@@ -795,20 +806,18 @@ with open(state_file, 'w') as f:
             >/dev/null 2>&1 || true
     fi
 
-    # Write transcript for this council round (Path A: council_vote path)
+    # Write transcript for this council round (Path A: council_vote path).
+    #
+    # Drive contrarian_triggered/_flipped off the snapshots captured in the
+    # anti-sycophancy block ABOVE, not off the now-mutated approve_count. The DA
+    # fires exactly when the council was unanimous (_da_was_unanimous), and it
+    # flips exactly when it did not confirm the approval (_da_flipped). Re-deriving
+    # from approve_count was wrong because the flip path already decremented it,
+    # so triggered/flipped were both recorded as false on flip rounds.
     local _ct_outcome
     _ct_outcome=$([ $approve_count -ge $effective_threshold ] && echo "APPROVED" || echo "REJECTED")
-    local _ct_triggered="false"
-    local _ct_flipped="false"
-    if [ $approve_count -eq $COUNCIL_SIZE ] && [ $COUNCIL_SIZE -ge 2 ]; then
-        _ct_triggered="true"
-    fi
-    # contrarian_flipped: DA voted REJECT/CANNOT_VALIDATE causing approve_count drop
-    # Detect by checking if approve dropped from unanimous (COUNCIL_SIZE) to less
-    # We infer flip if triggered AND final approve < COUNCIL_SIZE
-    if [ "$_ct_triggered" = "true" ] && [ $approve_count -lt $COUNCIL_SIZE ]; then
-        _ct_flipped="true"
-    fi
+    local _ct_triggered="$_da_was_unanimous"
+    local _ct_flipped="$_da_flipped"
     council_write_transcript "${ITERATION_COUNT:-0}" "$_ct_outcome" "$_ct_triggered" "$_ct_flipped" "$effective_threshold"
 
     if [ $approve_count -ge $effective_threshold ]; then

package/autonomy/hooks/migration-hooks.sh

@@ -317,14 +317,38 @@ hook_pre_healing_modify() {
     if [[ -f "$heal_dir/friction-map.json" ]]; then
         local blocked
         blocked=$(python3 -c "
-import json, sys
+import json, os, sys
 file_path = sys.argv[1]
 strict = sys.argv[2] == 'true'
 with open(sys.argv[3]) as f:
     data = json.load(f)
+
+# Path-aware match (not raw substring 'in', which over-matched app.py against
+# myapp.py and under-matched src/foo.py against a foo.py:10 location). Friction
+# locations are formatted 'path:line' (or just 'path'); strip a trailing
+# ':<line>' then compare by basename and normalized path so the same file is
+# matched regardless of how it was referenced.
+def norm(p):
+    # Drop a trailing ':<line>' (and optional ':<col>') suffix from a location.
+    parts = p.rsplit(':', 1)
+    while len(parts) == 2 and parts[1].isdigit():
+        p = parts[0]
+        parts = p.rsplit(':', 1)
+    return p
+
+def matches(target, loc):
+    loc = norm(loc)
+    if not target or not loc:
+        return False
+    # Exact normalized-path match, or same basename. Basename equality is the
+    # path-aware replacement for substring containment.
+    if os.path.normpath(target) == os.path.normpath(loc):
+        return True
+    return os.path.basename(target) == os.path.basename(loc)
+
 for friction in data.get('frictions', []):
     loc = friction.get('location', '')
-    if file_path in loc:
+    if matches(file_path, loc):
         cls = friction.get('classification', 'unknown')
         safe = friction.get('safe_to_remove', False)
         if cls in ('business_rule', 'unknown') and not safe:
@@ -343,9 +367,101 @@ print('OK')
         fi
     fi
 
+    # Capture a pre-edit snapshot so post_healing_modify can revert ONLY the
+    # healing edit on test failure (not unrelated uncommitted changes, and not
+    # via git checkout which discards everything). Keyed by file path.
+    _heal_snapshot_save "$heal_dir" "$file_path"
+
+    return 0
+}
+
+# Snapshot path helper: maps a target file path to its snapshot blob location.
+# Uses a flat directory with the path's basename plus a hash of the full path
+# to avoid collisions between same-named files in different directories.
+_heal_snapshot_path() {
+    local heal_dir="$1"
+    local file_path="$2"
+    local key
+    key=$(printf '%s' "$file_path" | cksum | awk '{print $1"-"$2}')
+    printf '%s/snapshots/%s.%s' "$heal_dir" "$(basename "$file_path")" "$key"
+}
+
+# Save a pre-edit snapshot of file_path. If the file does not exist yet (the
+# healing edit will CREATE it), write a sentinel marker instead so the revert
+# path knows to remove the file rather than restore content.
+#
+# Pairing contract: hook_pre_healing_modify (which calls this) MUST run for a
+# file before hook_post_healing_modify reverts it. The snapshot is refreshed on
+# every pre call, so a post without a matching fresh pre could restore a stale
+# blob. On the success path the snapshot is intentionally left in place; the
+# next pre overwrites it.
+_heal_snapshot_save() {
+    local heal_dir="$1"
+    local file_path="$2"
+    [[ -z "$file_path" ]] && return 0
+    local snap_dir="$heal_dir/snapshots"
+    mkdir -p "$snap_dir" 2>/dev/null || return 0
+    local snap
+    snap=$(_heal_snapshot_path "$heal_dir" "$file_path")
+    if [[ -f "$file_path" ]]; then
+        cp "$file_path" "$snap" 2>/dev/null || return 0
+        rm -f "$snap.absent" 2>/dev/null || true
+    else
+        # File does not exist pre-edit: record an "absent" marker, drop any
+        # stale content snapshot.
+        rm -f "$snap" 2>/dev/null || true
+        : > "$snap.absent" 2>/dev/null || true
+    fi
     return 0
 }
 
+# Restore file_path from its pre-edit snapshot, reverting ONLY the healing edit.
+# Echoes an accurate human-readable message describing what actually happened
+# (content restored / healing-added file removed / could not revert). Returns 0
+# when the revert succeeded as reported, 1 when it could not be performed.
+_heal_snapshot_restore() {
+    local heal_dir="$1"
+    local file_path="$2"
+    if [[ -z "$file_path" ]]; then
+        echo "No file path given; nothing reverted."
+        return 1
+    fi
+    local snap
+    snap=$(_heal_snapshot_path "$heal_dir" "$file_path")
+
+    if [[ -f "$snap" ]]; then
+        # Pre-edit content snapshot exists: restore exactly that content, which
+        # preserves any unrelated uncommitted changes present before the edit.
+        if cp "$snap" "$file_path" 2>/dev/null; then
+            echo "Healing edit reverted to pre-edit snapshot."
+            return 0
+        fi
+        echo "Could not restore pre-edit snapshot for ${file_path}; file left as-is."
+        return 1
+    fi
+
+    if [[ -f "$snap.absent" ]]; then
+        # File did not exist pre-edit: the healing edit created it. Remove only
+        # that file, not unrelated state.
+        if [[ ! -e "$file_path" ]]; then
+            echo "Healing-added file ${file_path} no longer present; nothing to remove."
+            return 0
+        fi
+        if rm -f "$file_path" 2>/dev/null; then
+            echo "Healing-added file ${file_path} removed."
+            return 0
+        fi
+        echo "Could not remove healing-added file ${file_path}; file left as-is."
+        return 1
+    fi
+
+    # No snapshot was captured (pre_healing_modify did not run for this file).
+    # Be honest: do not claim a revert that did not happen, and do NOT fall back
+    # to a destructive git checkout.
+    echo "No pre-edit snapshot found for ${file_path}; could not revert (left as-is)."
+    return 1
+}
+
 # Hook: post_healing_modify - runs AFTER agent modifies a file in healing mode
 # Verifies characterization tests still pass after modification
 hook_post_healing_modify() {
@@ -384,9 +500,17 @@ hook_post_healing_modify() {
         test_output=$(cat "$test_result_file")
         rm -f "$test_result_file"
 
-        # Revert the change - characterization tests must pass
-        git -C "$codebase_path" checkout -- "$file_path" 2>/dev/null || true
-        echo "HOOK_BLOCKED: Characterization tests failed after healing modification to ${file_path}. Change reverted."
+        # Revert ONLY the healing edit using the pre-edit snapshot captured by
+        # hook_pre_healing_modify. Do NOT use `git checkout -- "$file_path"`:
+        # that discards ALL uncommitted changes to the file (not just the
+        # healing edit) and silently no-ops for an untracked file while still
+        # claiming the change was reverted. Report exactly what happened.
+        local revert_msg
+        # _heal_snapshot_restore returns nonzero when it could not revert; we
+        # surface the outcome via its message (recorded below) rather than a
+        # code, and must not let a nonzero return abort under set -e.
+        revert_msg=$(_heal_snapshot_restore "$heal_dir" "$file_path") || true
+        echo "HOOK_BLOCKED: Characterization tests failed after healing modification to ${file_path}. ${revert_msg}"
         echo "Test output: ${test_output}"
 
         # Record failure in failure-modes.json
@@ -404,12 +528,12 @@ data.setdefault('modes', []).append({
     'trigger': 'healing_modification',
     'file': sys.argv[2],
     'behavior': 'Characterization tests failed after modification',
-    'recovery': 'Change automatically reverted',
+    'recovery': sys.argv[3],
     'is_intentional': False
 })
 with open(sys.argv[1], 'w') as f:
     json.dump(data, f, indent=2)
-" "$heal_dir/failure-modes.json" "$file_path" 2>/dev/null || true
+" "$heal_dir/failure-modes.json" "$file_path" "$revert_msg" 2>/dev/null || true
         fi
 
         return 1

package/autonomy/loki

@@ -13178,13 +13178,18 @@ FEOF
                 ;;
             --disable)
                 if [ -f "$failover_file" ]; then
-                    python3 -c "
-import json
-with open('$failover_file') as f: d = json.load(f)
+                    if _FAILOVER_FILE="$failover_file" python3 -c "
+import json, os
+failover_file = os.environ['_FAILOVER_FILE']
+with open(failover_file) as f: d = json.load(f)
 d['enabled'] = False
-with open('$failover_file', 'w') as f: json.dump(d, f, indent=2)
-" 2>/dev/null
-                    echo -e "${YELLOW}Failover disabled${NC}"
+with open(failover_file, 'w') as f: json.dump(d, f, indent=2)
+"; then
+                        echo -e "${YELLOW}Failover disabled${NC}"
+                    else
+                        echo -e "${RED}Error: failed to disable failover${NC}"
+                        return 1
+                    fi
                 else
                     echo "Failover not initialized."
                 fi
@@ -13212,13 +13217,19 @@ with open('$failover_file', 'w') as f: json.dump(d, f, indent=2)
                     return 1
                 fi
 
-                python3 -c "
-import json
-with open('$failover_file') as f: d = json.load(f)
-d['chain'] = '$new_chain'.split(',')
-with open('$failover_file', 'w') as f: json.dump(d, f, indent=2)
-" 2>/dev/null
-                echo "Failover chain updated: $new_chain"
+                if _FAILOVER_FILE="$failover_file" _NEW_CHAIN="$new_chain" python3 -c "
+import json, os
+failover_file = os.environ['_FAILOVER_FILE']
+new_chain = os.environ['_NEW_CHAIN']
+with open(failover_file) as f: d = json.load(f)
+d['chain'] = new_chain.split(',')
+with open(failover_file, 'w') as f: json.dump(d, f, indent=2)
+"; then
+                    echo "Failover chain updated: $new_chain"
+                else
+                    echo -e "${RED}Error: failed to update failover chain${NC}"
+                    return 1
+                fi
                 shift
                 ;;
             --test)
@@ -18601,16 +18612,16 @@ else:
                 exit 1
             fi
 
-            python3 -c "
+            _REGISTRY_FILE="$registry_file" _PROJ_PATH="$path" _PROJ_NAME="$name" _PROJ_ALIAS="$alias" python3 -c "
 import json
 import os
 import hashlib
 from datetime import datetime, timezone
 
-registry_file = '$registry_file'
-path = '$path'
-name = '$name' or os.path.basename(path)
-alias = '$alias' or None
+registry_file = os.environ['_REGISTRY_FILE']
+path = os.environ['_PROJ_PATH']
+name = os.environ['_PROJ_NAME'] or os.path.basename(path)
+alias = os.environ['_PROJ_ALIAS'] or None
 
 # Generate project ID
 project_id = hashlib.md5(path.encode()).hexdigest()[:12]
@@ -18651,7 +18662,7 @@ with open(registry_file, 'w') as f:
 print(f'  Path: {path}')
 if alias:
     print(f'  Alias: {alias}')
-" 2>/dev/null
+"
             ;;
 
         remove|rm)
@@ -18662,12 +18673,12 @@ if alias:
                 exit 1
             fi
 
-            python3 -c "
+            _REGISTRY_FILE="$registry_file" _IDENTIFIER="$identifier" python3 -c "
 import json
 import os
 
-registry_file = '$registry_file'
-identifier = '$identifier'
+registry_file = os.environ['_REGISTRY_FILE']
+identifier = os.environ['_IDENTIFIER']
 
 with open(registry_file, 'r') as f:
     data = json.load(f)
@@ -18690,7 +18701,7 @@ if found_id:
 else:
     print(f'Not found: {identifier}')
     exit(1)
-" 2>/dev/null
+"
             ;;
 
         discover)
@@ -18842,12 +18853,12 @@ print(f'Added: {added}, Missing: {missing}, Total: {len(projects)}')
         health)
             local identifier="${2:-$(pwd)}"
 
-            python3 -c "
+            _REGISTRY_FILE="$registry_file" _IDENTIFIER="$identifier" python3 -c "
 import json
 import os
 
-registry_file = '$registry_file'
-identifier = '$identifier'
+registry_file = os.environ['_REGISTRY_FILE']
+identifier = os.environ['_IDENTIFIER']
 
 # If it's a path, resolve it
 if os.path.isdir(identifier):
@@ -18886,7 +18897,7 @@ print('Health Checks:')
 for check, passed in checks.items():
     icon = '[OK]' if passed else '[FAIL]'
     print(f'  {icon} {check}')
-" 2>/dev/null
+"
             ;;
 
         --help|-h|help)
@@ -19040,17 +19051,17 @@ cmd_enterprise() {
                         esac
                     done
 
-                    python3 -c "
+                    _TOKEN_FILE="$token_file" _TOKEN_NAME="$name" _TOKEN_SCOPES="$scopes" _TOKEN_EXPIRES="$expires" python3 -c "
 import json
 import secrets
 import hashlib
 from datetime import datetime, timezone, timedelta
 import os
 
-token_file = '$token_file'
-name = '$name'
-scopes_str = '$scopes'
-expires_str = '$expires'
+token_file = os.environ['_TOKEN_FILE']
+name = os.environ['_TOKEN_NAME']
+scopes_str = os.environ['_TOKEN_SCOPES']
+expires_str = os.environ['_TOKEN_EXPIRES']
 
 # Parse scopes
 scopes = scopes_str.split(',') if scopes_str else ['*']
@@ -19105,7 +19116,7 @@ if expires_at:
 print('')
 print('Token (save this - shown only once):')
 print(f'  {raw_token}')
-" 2>/dev/null
+"
                     ;;
 
                 list|ls)
@@ -19174,12 +19185,12 @@ else:
                         exit 2
                     fi
 
-                    python3 -c "
-import json
+                    _TOKEN_FILE="$token_file" _IDENTIFIER="$identifier" python3 -c "
+import json, os
 from datetime import datetime, timezone
 
-token_file = '$token_file'
-identifier = '$identifier'
+token_file = os.environ['_TOKEN_FILE']
+identifier = os.environ['_IDENTIFIER']
 
 with open(token_file, 'r') as f:
     data = json.load(f)
@@ -19202,7 +19213,7 @@ if found_id:
 else:
     print(f'Token not found: {identifier}')
     exit(1)
-" 2>/dev/null
+"
                     ;;
 
                 delete)
@@ -19213,11 +19224,11 @@ else:
                         exit 2
                     fi
 
-                    python3 -c "
-import json
+                    _TOKEN_FILE="$token_file" _IDENTIFIER="$identifier" python3 -c "
+import json, os
 
-token_file = '$token_file'
-identifier = '$identifier'
+token_file = os.environ['_TOKEN_FILE']
+identifier = os.environ['_IDENTIFIER']
 
 with open(token_file, 'r') as f:
     data = json.load(f)
@@ -19241,7 +19252,7 @@ if found_id:
 else:
     print(f'Token not found: {identifier}')
     exit(1)
-" 2>/dev/null
+"
                     ;;
 
                 *)

package/dashboard/__init__.py

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

package/dashboard/server.py

@@ -7034,6 +7034,96 @@ def _pid_is_alive(pid):
         return None
 
 
+# Margin (seconds) added to the recorded reference time before a live pid is
+# judged to be a recycled (different) process. Must comfortably exceed clock
+# skew plus the launch-to-first-state-write gap so a genuine app is never
+# downgraded. A PID recycled after a crash typically belongs to a process that
+# started minutes or hours later, so a generous margin still catches recycles
+# while strongly biasing against the far worse false-positive of killing a live
+# app's status. See _reconcile_app_runner_liveness.
+_APP_RUNNER_PID_RECYCLE_MARGIN_SECONDS = 120
+
+
+def _pid_start_time(pid):
+    """Best-effort wall-clock start time of pid, as epoch seconds, or None.
+
+    Reads `ps -o lstart= -p <pid>`, which is available on both macOS and Linux
+    and prints the process start time in local time (e.g. "Sun Jun 14 18:39:15
+    2026"). The string is locale-dependent (%a/%b), so any parse failure, empty
+    output, or missing process returns None and the caller degrades gracefully
+    to its prior behavior. The returned epoch is timezone-correct because the
+    naive local timestamp is interpreted in the system's local zone before
+    conversion (ps reports local time; never mix it with a UTC value directly).
+    """
+    try:
+        pid = int(pid)
+    except (TypeError, ValueError):
+        return None
+    if pid <= 0:
+        return None
+    try:
+        out = subprocess.run(["ps", "-o", "lstart=", "-p", str(pid)],
+                             capture_output=True, text=True, timeout=5)
+    except (OSError, subprocess.SubprocessError):
+        return None
+    raw = (out.stdout or "").strip()
+    if not raw:
+        return None
+    try:
+        # lstart is local time without a zone; parse naive then attach the
+        # local zone so .timestamp() yields a correct epoch regardless of TZ.
+        naive = datetime.strptime(raw, "%a %b %d %H:%M:%S %Y")
+        local = naive.replace(tzinfo=datetime.now().astimezone().tzinfo)
+        return local.timestamp()
+    except (ValueError, OverflowError, OSError):
+        return None
+
+
+def _state_reference_epoch(state):
+    """Epoch seconds for state.json's recorded reference time, or None.
+
+    Uses `started_at` (rewritten by the app-runner on every state write; it is
+    the last-state-write time, not pure launch time). For a genuine process the
+    real start time is always <= this value, so it is a safe upper bound to
+    compare a live pid's start time against. The value is UTC (Z-suffixed).
+    """
+    if not isinstance(state, dict):
+        return None
+    started_at = state.get("started_at")
+    if not started_at:
+        return None
+    try:
+        ts = datetime.fromisoformat(str(started_at).replace("Z", "+00:00"))
+    except (ValueError, TypeError):
+        return None
+    if ts.tzinfo is None:
+        ts = ts.replace(tzinfo=timezone.utc)
+    return ts.timestamp()
+
+
+def _pid_is_recycled(state):
+    """True if the recorded main_pid is alive but is a DIFFERENT process now.
+
+    After the recorded app dies, the OS can recycle its numeric pid for an
+    unrelated process; os.kill(pid, 0) then reports the stale pid "alive"
+    forever and a dead run is never reconciled. We detect this by comparing the
+    live pid's real start time against the recorded reference time: a genuine
+    process started at or before the reference, so a live pid whose start time
+    is comfortably AFTER the reference cannot be the original.
+
+    Returns True only with positive evidence of recycling. Any missing data
+    (no recorded reference, start time unavailable) returns False so the caller
+    keeps its prior behavior -- best-effort, biased against false positives.
+    """
+    reference = _state_reference_epoch(state)
+    if reference is None:
+        return False
+    pid_start = _pid_start_time(state.get("main_pid"))
+    if pid_start is None:
+        return False
+    return pid_start > reference + _APP_RUNNER_PID_RECYCLE_MARGIN_SECONDS
+
+
 def _health_checked_age_seconds(state):
     """Seconds since last_health.checked_at, or None if unparseable/absent."""
     health = state.get("last_health")
@@ -7059,6 +7149,9 @@ def _reconcile_app_runner_liveness(state):
     Here we cross-check the recorded main_pid against the real OS before
     returning, and only ever downgrade -- never upgrade -- the status:
       - recorded running/starting + pid genuinely gone   -> "stopped"
+      - recorded running/starting + pid "alive" but its real start time is
+        after the recorded reference (the OS recycled a dead run's pid for an
+        unrelated process)                                -> "stopped"
       - recorded running/starting + pid not verifiable    +
         last_health.checked_at older than the threshold   -> "stale"
     Any failure falls back to the raw recorded status (fail open to the writer's
@@ -7076,6 +7169,15 @@ def _reconcile_app_runner_liveness(state):
             state["status"] = "stopped"
             state["liveness"] = "pid_gone"
             return state
+        if alive is True:
+            # The numeric pid exists, but os.kill(pid, 0) cannot tell whether it
+            # is still the SAME process. After a dead run the OS can recycle the
+            # pid; detect that via the process start time so a recycled pid is
+            # treated as gone rather than reported "running" forever.
+            if _pid_is_recycled(state):
+                state["status"] = "stopped"
+                state["liveness"] = "pid_recycled"
+            return state
         if alive is None:
             # Cannot verify via pid (e.g. compose subshell pid). Fall back to
             # the health-beat freshness with a generous threshold.