loki-mode 7.5.10 → 7.5.12

package/README.md

@@ -18,7 +18,7 @@
 
 ---
 
-> **How it works:** You provide a PRD. Loki Mode classifies complexity (`run.sh:detect_complexity()`), assembles an agent team from 41 specialized types across 8 swarms, and runs autonomous RARV cycles (Reason - Act - Reflect - Verify, see `run.sh:run_autonomous()`) with 11 quality gates (see `skills/quality-gates.md`). Code is not "done" until it passes automated verification. Output is a Git repo with source, tests, configs, and audit logs.
+> **How it works:** Drop a spec -- a PRD, GitHub issue, OpenAPI/JSON/YAML, or one-line brief. Loki Mode classifies complexity (`run.sh:detect_complexity()`), assembles an agent team from 41 specialized types across 8 swarms, and runs autonomous RARV cycles (Reason - Act - Reflect - Verify, see `run.sh:run_autonomous()`) with 11 quality gates (see `skills/quality-gates.md`). Code is not "done" until it passes automated verification. Output is a Git repo with source, tests, configs, and audit logs.
 
 ---
 
@@ -49,7 +49,9 @@ bun install -g loki-mode
 loki doctor                                   # verify environment
 loki init my-app --template simple-todo-app
 cd my-app
-loki start prd.md                             # autonomous build starts
+loki start prd.md                             # autonomous build from a Markdown PRD
+loki start owner/repo#123                     # ...or a GitHub issue
+loki start ./openapi.yaml                     # ...or an OpenAPI/YAML spec
 ```
 
 Or skip scaffolding and go straight to a quick task:
@@ -64,7 +66,7 @@ loki quick "build a landing page with a signup form"
 |--------|---------|-------|
 | **Bun (recommended)** | `bun install -g loki-mode` | Fastest. v8 will be Bun-only. |
 | **Homebrew** | `brew tap asklokesh/tap && brew install loki-mode` | Auto-installs Bun as a dep |
-| **Docker** | `docker pull asklokesh/loki-mode:7.5.9 && docker run --rm asklokesh/loki-mode:7.5.9 start prd.md` | Bun pre-installed in image |
+| **Docker** | `docker pull asklokesh/loki-mode:7.5.11 && docker run --rm asklokesh/loki-mode:7.5.11 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:**
@@ -124,7 +126,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.5.9` |
+| **Docker** | `docker pull asklokesh/loki-mode:7.5.11` |
 | **Inside Claude Code** | `claude --dangerously-skip-permissions` then type "Loki Mode" |
 | **Git clone** | `git clone https://github.com/asklokesh/loki-mode.git` |
 
@@ -132,6 +134,29 @@ See the full [Installation Guide](docs/INSTALLATION.md).
 
 </details>
 
+<details>
+<summary><strong>Supported spec formats</strong></summary>
+
+A "spec" is whatever you hand `loki start`. Loki auto-detects the format and normalises it before the RARV loop. A Markdown PRD is one form of spec; the table below lists every input the v7.5.11 CLI accepts.
+
+| Format | Example | Notes |
+|--------|---------|-------|
+| Markdown PRD | `loki start ./prd.md` | Canonical form. Headings become section anchors. |
+| JSON spec | `loki start ./spec.json` | Free-form JSON; keys surfaced to agents. |
+| YAML spec | `loki start ./openapi.yaml` | OpenAPI / AsyncAPI / plain YAML all accepted. |
+| Plain text brief | `loki start ./brief.txt` | One-paragraph briefs work; complexity auto-detects to "simple". |
+| GitHub issue URL | `loki start https://github.com/owner/repo/issues/42` | Title + body + labels become the spec. |
+| GitHub shorthand | `loki start owner/repo#42` | Same as above, shorter. |
+| Jira ticket key | `loki start PROJ-456` | Requires `JIRA_BASE_URL` + `JIRA_TOKEN` env vars. |
+| GitLab / Azure DevOps URL | `loki start https://gitlab.com/group/proj/-/issues/7` | GitLab and Azure DevOps issue URLs both supported. |
+| Bare issue number | `loki start #123` or `loki start 123` | Resolved against the current repo's `origin` remote. |
+| OpenSpec change directory | `loki start --openspec ./openspec/change-001` | Reads OpenSpec change manifest + delta files. |
+| Auto-detect (no input) | `loki start` | Picks up `./prd.md`, `./spec.{json,yaml,yml}`, or `./SPEC.md` from cwd. |
+
+All formats land in the same RARV pipeline and pass the same 11 quality gates (`skills/quality-gates.md`).
+
+</details>
+
 ---
 
 ## What You Can Build

package/SKILL.md

@@ -1,12 +1,14 @@
 ---
 name: loki-mode
-description: Multi-agent autonomous startup system. Triggers on "Loki Mode". Takes PRD to deployed product with minimal human intervention. Requires --dangerously-skip-permissions flag.
+description: Multi-agent autonomous startup system. Triggers on "Loki Mode". Takes a spec (PRD, GitHub issue, OpenAPI doc, etc.) to deployed product with minimal human intervention. Requires --dangerously-skip-permissions flag.
 ---
 
-# Loki Mode v7.5.10
+# Loki Mode v7.5.12
 
 **You are an autonomous agent. You make decisions. You do not ask questions. You do not stop.**
 
+**Spec in, product out.** A "spec" is whatever describes the work: a Markdown PRD, a GitHub issue, an OpenAPI doc, a Jira ticket -- a PRD is one form of spec.
+
 **Multi-provider (stable since v5.0.0):** Claude/Codex/Gemini/Cline/Aider with abstract model tiers and degraded mode for non-Claude providers. See `skills/providers.md`. **Current track (v7.5.x):** Phase 1 RARV-C closure -- real provider judges, gate-failure flock, synthetic PRD e2e, status `--json`, dead code cleanup.
 
 **Runtime migration in progress:** A bash-to-Bun migration is underway on the `feat/bun-migration` branch. The first phase (shipped in v7.3.0) routes a small set of read-only commands -- `version`, `status`, `stats`, `doctor`, `provider show/list`, `memory list/index` -- through a Bun runtime via `bin/loki`. Every other command remains on the Bash runtime (`autonomy/loki`). Rollback is available with `LOKI_LEGACY_BASH=1`. See `UPGRADING.md` and `docs/architecture/ADR-001-runtime-migration.md` for the full plan.
@@ -89,11 +91,11 @@ These rules guide autonomous operation. Test results and code quality always tak
 
 ## Model Selection
 
-**Default since v5.3.0 (reaffirmed in v7.5.10):** Haiku disabled for quality. Use `--allow-haiku` or `LOKI_ALLOW_HAIKU=true` to enable.
+**Default since v5.3.0 (reaffirmed in v7.5.12):** Haiku disabled for quality. Use `--allow-haiku` or `LOKI_ALLOW_HAIKU=true` to enable.
 
 | Task Type | Tier | Claude (default) | Claude (--allow-haiku) | Codex (GPT-5.3) | Gemini |
 |-----------|------|------------------|------------------------|------------------|--------|
-| PRD analysis, architecture, system design | **planning** | opus | opus | effort=xhigh | thinking=high |
+| Spec analysis, architecture, system design | **planning** | opus | opus | effort=xhigh | thinking=high |
 | Feature implementation, complex bugs | **development** | opus | sonnet | effort=high | thinking=medium |
 | Code review (planned: 3 parallel reviewers) | **development** | opus | sonnet | effort=high | thinking=medium |
 | Integration tests, E2E, deployment | **development** | opus | sonnet | effort=high | thinking=medium |
@@ -113,7 +115,7 @@ These rules guide autonomous operation. Test results and code quality always tak
 
 ```
 BOOTSTRAP ──[project initialized]──> DISCOVERY
-DISCOVERY ──[PRD analyzed, requirements clear]──> ARCHITECTURE
+DISCOVERY ──[spec analyzed, requirements clear]──> ARCHITECTURE
 ARCHITECTURE ──[design approved, specs written]──> DEEPEN_PLAN (standard/complex only)
 DEEPEN_PLAN ──[plan enhanced by 4 research agents]──> INFRASTRUCTURE
 INFRASTRUCTURE ──[cloud/DB ready]──> DEVELOPMENT
@@ -187,20 +189,21 @@ This protocol governs **skill module** loading -- task-scoped instruction files
 
 ## Invocation
 
-**Unified entry point (v6.84.0):** `loki start` auto-detects whether the input is a PRD file, an issue URL, or an issue number. No need to pick between `loki start` and `loki run` -- the single command handles all cases.
+**Unified entry point (v6.84.0):** `loki start [SPEC|ISSUE-REF]` auto-detects whether the input is a PRD file, an issue URL, an issue number, or another spec format (e.g. OpenAPI). No need to pick between `loki start` and `loki run` -- the single command handles all cases.
 
 ```bash
 # Standard mode (Claude - full features)
 claude --dangerously-skip-permissions
-# Then say: "Loki Mode" or "Loki Mode with PRD at path/to/prd.md" (or .json)
+# Then say: "Loki Mode" or "Loki Mode with spec at path/to/spec" (PRD .md/.json, OpenAPI .yaml, etc.)
 
 # Unified `loki start` -- one command, auto-detected mode
-loki start                                   # no arg: analyze current dir, auto-generate PRD
-loki start ./prd.md                          # PRD mode (.md/.json/.txt/.yaml)
+loki start                                   # no arg: analyze current dir, auto-generate spec
+loki start ./prd.md                          # PRD mode (.md/.json/.txt/.yaml) -- a PRD is one form of spec
+loki start ./openapi.yaml                    # SPEC mode (OpenAPI doc treated as the spec)
+loki start owner/repo#123                    # ISSUE mode (GitHub specific repo)
 loki start https://github.com/o/r/issues/42  # ISSUE mode (GitHub URL)
 loki start 123                               # ISSUE mode (GitHub issue in current repo)
 loki start PROJ-456                          # ISSUE mode (Jira)
-loki start owner/repo#789                    # ISSUE mode (GitHub specific repo)
 loki start --prd ./prd.md                    # Explicit PRD mode (overrides detection)
 loki start --issue 123                       # Explicit issue mode (overrides detection)
 
@@ -330,7 +333,7 @@ See `references/core-workflow.md` for the full RARV-C contract.
 
 ---
 
-## Concurrency and Security Hardening (v7.5.7 - v7.5.10)
+## Concurrency and Security Hardening (v7.5.7 - v7.5.12)
 
 Three back-to-back patches closed cross-process and security gaps. No user-facing behavior change on the default flow; verify via the cited paths.
 
@@ -339,7 +342,7 @@ Three back-to-back patches closed cross-process and security gaps. No user-facin
 - **Dashboard auth** now required on `/api/memory/*`, `/api/learning/*`, and `/api/status` in `dashboard/server.py` (previously unauthenticated read paths).
 - **Bash quoting hardening** across `autonomy/run.sh` and `autonomy/loki` -- variable expansions inside command substitution and `[ ]` tests quoted to prevent word-splitting on paths with spaces.
 
-See `CHANGELOG.md` entries [7.5.7], [7.5.8], [7.5.10] for the per-fix list and reviewer sign-off.
+See `CHANGELOG.md` entries [7.5.7], [7.5.8], [7.5.12] for the per-fix list and reviewer sign-off.
 
 ---
 
@@ -355,7 +358,7 @@ See `CHANGELOG.md` entries [7.5.7], [7.5.8], [7.5.10] for the per-fix list and r
 | Notification Triggers | v5.40.0 | `GET/PUT /api/notifications/triggers` |
 | GitHub integration | v5.42.2 | Import, sync-back, PR creation, export. CLI: `loki github`, API: `/api/github/*` |
 | Legacy System Healing | v6.67.0 | `loki heal <path>` -- friction-as-semantics, characterization tests |
-| Unified `loki start` | v6.84.0 | Auto-detects PRD vs issue input |
+| Unified `loki start` | v6.84.0 | Auto-detects spec (PRD, OpenAPI, etc.) vs issue input |
 | Managed Agents (memory mirror) | v7.2.0 | Opt-in via `LOKI_MANAGED_AGENTS` -- see Managed Agents section |
 | Bun runtime (Phase 1) | v7.3.0 | Read-only commands routed through `bin/loki`; `LOKI_LEGACY_BASH=1` to revert |
 | Phase 1 RARV-C closure | v7.5.x | Findings injection, real judges, auto-learnings, handoff.md |
@@ -378,4 +381,4 @@ See `CHANGELOG.md` entries [7.5.7], [7.5.8], [7.5.10] for the per-fix list and r
 
 ---
 
-**v7.5.10 | [Autonomi](https://www.autonomi.dev/) flagship product | ~260 lines core**
+**v7.5.12 | [Autonomi](https://www.autonomi.dev/) flagship product | ~260 lines core**

package/VERSION

@@ -1 +1 @@
-7.5.10
+7.5.12

package/autonomy/app-runner.sh

@@ -431,6 +431,66 @@ _install_python_deps() {
     fi
 }
 
+# Resolve the directory containing the compose file. Falls back to the passed
+# directory when no compose file is found (callers should already have verified
+# detection). Honors LOKI_COMPOSE_FILE override.
+_app_runner_compose_dir() {
+    local base="${1:-${TARGET_DIR:-.}}"
+    if [ -n "${LOKI_COMPOSE_FILE:-}" ] && [ -f "${LOKI_COMPOSE_FILE}" ]; then
+        dirname "${LOKI_COMPOSE_FILE}"
+        return
+    fi
+    for candidate in \
+        "$base/docker-compose.yml" \
+        "$base/docker-compose.yaml" \
+        "$base/compose.yml" \
+        "$base/compose.yaml"; do
+        if [ -f "$candidate" ]; then
+            dirname "$candidate"
+            return
+        fi
+    done
+    printf '%s\n' "$base"
+}
+
+# Count containers currently in the "running" state for the compose project.
+# Polls up to LOKI_COMPOSE_HEALTH_TIMEOUT seconds (default 30) at 1s intervals
+# so containers transitioning from Created -> Running are not falsely reported
+# as failed. Echoes the final running-container count (0 on failure).
+_app_runner_compose_running_count() {
+    local base="${1:-${TARGET_DIR:-.}}"
+    local compose_dir
+    compose_dir=$(_app_runner_compose_dir "$base")
+    local timeout="${LOKI_COMPOSE_HEALTH_TIMEOUT:-30}"
+    if ! [[ "$timeout" =~ ^[0-9]+$ ]]; then
+        timeout=30
+    fi
+    local elapsed=0
+    local count=0
+    while [ "$elapsed" -lt "$timeout" ]; do
+        # Prefer the structured --format '{{.State}}' which lists one state per
+        # container (one per line) and is stable across docker-compose v2.x.
+        local states
+        states=$(cd "$compose_dir" && docker compose ps --format '{{.State}}' 2>/dev/null || true)
+        if [ -n "$states" ]; then
+            # Match exact "running" lines only (case-insensitive). Avoid grep -c
+            # on empty input which can return 0 with success even when nothing
+            # ran. Also strip CR for safety on weird terminals.
+            count=$(printf '%s\n' "$states" | tr -d '\r' | grep -ciE '^running$' || true)
+        else
+            count=0
+        fi
+        if [ "${count:-0}" -gt 0 ]; then
+            printf '%s\n' "$count"
+            return 0
+        fi
+        sleep 1
+        elapsed=$(( elapsed + 1 ))
+    done
+    printf '%s\n' "${count:-0}"
+    return 0
+}
+
 #===============================================================================
 # Lifecycle
 #===============================================================================
@@ -501,15 +561,24 @@ app_runner_start() {
 
     # Verify process started
     if [ "$_APP_RUNNER_IS_DOCKER" = true ] && echo "$_APP_RUNNER_METHOD" | grep -q "docker compose"; then
-        # Docker compose -d exits immediately; check containers instead of PID
+        # Docker compose -d exits immediately; poll for containers in "running"
+        # state. Containers may report "Created" briefly before transitioning to
+        # "Running", so retry up to ~30 seconds before declaring failure.
         local running_containers
-        running_containers=$(cd "${TARGET_DIR:-.}" && { docker compose ps --status running -q 2>/dev/null || docker compose ps 2>/dev/null | grep -ciE 'running|up'; } | wc -l | tr -d ' ')
+        running_containers=$(_app_runner_compose_running_count "$dir")
         if [ "${running_containers:-0}" -gt 0 ]; then
             _write_app_state "running"
             log_info "App Runner: docker compose started ($running_containers container(s) running)"
             return 0
         else
-            log_error "App Runner: docker compose containers failed to start"
+            # Capture diagnostic output for postmortem
+            local compose_dir
+            compose_dir=$(_app_runner_compose_dir "$dir")
+            local diag
+            diag=$(cd "$compose_dir" && docker compose ps 2>&1 || true)
+            log_error "App Runner: docker compose containers failed to start (no containers in running state after retries)"
+            log_error "App Runner: docker compose ps output:"
+            printf '%s\n' "$diag" | while IFS= read -r line; do log_error "  $line"; done
             _APP_RUNNER_CRASH_COUNT=$(( _APP_RUNNER_CRASH_COUNT + 1 ))
             _write_app_state "failed"
             return 1
@@ -547,7 +616,9 @@ app_runner_stop() {
             docker rm "$_APP_RUNNER_DOCKER_CONTAINER" 2>/dev/null || true
         fi
         if echo "$_APP_RUNNER_METHOD" | grep -q "docker compose"; then
-            (cd "${TARGET_DIR:-.}" && docker compose down 2>/dev/null) || true
+            local _stop_compose_dir
+            _stop_compose_dir=$(_app_runner_compose_dir "${TARGET_DIR:-.}")
+            (cd "$_stop_compose_dir" && docker compose down 2>/dev/null) || true
         fi
     fi
 
@@ -619,8 +690,10 @@ app_runner_health_check() {
 
     # Docker compose: check containers instead of PID (docker compose up -d exits immediately)
     if [ "$_APP_RUNNER_IS_DOCKER" = true ] && echo "$_APP_RUNNER_METHOD" | grep -q "docker compose"; then
+        # Use a 1-second timeout for health checks (no long retry); start-time
+        # retries are handled in app_runner_start.
         local running_containers
-        running_containers=$(cd "${TARGET_DIR:-.}" && { docker compose ps --status running -q 2>/dev/null || docker compose ps 2>/dev/null | grep -ciE 'running|up'; } | wc -l | tr -d ' ')
+        running_containers=$(LOKI_COMPOSE_HEALTH_TIMEOUT=1 _app_runner_compose_running_count "${TARGET_DIR:-.}")
         if [ "${running_containers:-0}" -gt 0 ]; then
             _write_health "true"
             _write_app_state "running"
@@ -759,7 +832,9 @@ app_runner_cleanup() {
             docker rm "$_APP_RUNNER_DOCKER_CONTAINER" 2>/dev/null || true
         fi
         if echo "$_APP_RUNNER_METHOD" | grep -q "docker compose"; then
-            (cd "${TARGET_DIR:-.}" && docker compose down 2>/dev/null) || true
+            local _stop_compose_dir
+            _stop_compose_dir=$(_app_runner_compose_dir "${TARGET_DIR:-.}")
+            (cd "$_stop_compose_dir" && docker compose down 2>/dev/null) || true
         fi
     fi
 

package/autonomy/lib/lock.sh

@@ -0,0 +1,147 @@
+#!/usr/bin/env bash
+# Loki Mode -- portable file locking helper.
+#
+# Why this exists:
+#   flock(1) is a Linux util-linux binary not shipped on macOS or BSDs.
+#   Bash callers that depend on it either degrade to non-atomic PID checks
+#   (race condition) or print a "flock not available" warning. This helper
+#   gives every bash caller one cross-platform primitive.
+#
+# Strategy:
+#   mkdir() is atomic on all POSIX filesystems -- exactly one concurrent
+#   caller wins the create. We use <target>.lockdir as the mutex, write a
+#   PID-stamped sentinel inside it for stale detection, and clean up via
+#   trap so a killed holder cannot wedge later callers.
+#
+# Public API:
+#   safe_acquire_lock <target> [timeout_seconds]   -> 0 on acquire, 1 on timeout
+#   safe_release_lock <target>                     -> always 0
+#   safe_with_lock   <target> <command...>         -> runs command under lock,
+#                                                     returns command's exit code
+#
+# Stale-lock policy: a lockdir whose sentinel PID is no longer alive AND
+# whose mtime is >30s old is reaped automatically.
+#
+# Acquire timing: poll every 50ms, default ceiling 5s.
+
+# Guard against double-source.
+if [ "${__LOKI_LOCK_SH_LOADED:-0}" = "1" ]; then
+    return 0 2>/dev/null || true
+fi
+__LOKI_LOCK_SH_LOADED=1
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+# _loki_lock_sleep_50ms: portable 50ms sleep.
+# perl is preinstalled on macOS + most Linux; bash builtin `read -t 0.05` is
+# the fallback; final fallback is a 1s sleep (still correct, just slower).
+_loki_lock_sleep_50ms() {
+    perl -e 'select(undef,undef,undef,0.05)' 2>/dev/null \
+        || read -r -t 0.05 _ < /dev/null 2>/dev/null \
+        || sleep 1
+}
+
+# _loki_lock_mtime <path>: portable mtime in epoch seconds, "0" on failure.
+_loki_lock_mtime() {
+    stat -f%m "$1" 2>/dev/null \
+        || stat -c%Y "$1" 2>/dev/null \
+        || echo 0
+}
+
+# _loki_lock_is_stale <lockdir>: 0 if reapable, 1 otherwise.
+# Stale = sentinel PID dead AND mtime >30s old. A bare lockdir with no
+# sentinel (legacy / partial create) is treated as stale after 30s as well.
+_loki_lock_is_stale() {
+    local lockdir="$1"
+    local sentinel="$lockdir/owner.pid"
+    local now age pid
+    now=$(date +%s 2>/dev/null || echo 0)
+    age=$(( now - $(_loki_lock_mtime "$lockdir") ))
+    if [ "$age" -le 30 ]; then
+        return 1
+    fi
+    if [ -f "$sentinel" ]; then
+        pid=$(cat "$sentinel" 2>/dev/null)
+        if [ -n "$pid" ] && kill -0 "$pid" 2>/dev/null; then
+            return 1
+        fi
+    fi
+    return 0
+}
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+# safe_acquire_lock <target> [timeout_seconds=5]
+# Acquires a mutex on <target>.lockdir. Returns 0 on acquire, 1 on timeout.
+safe_acquire_lock() {
+    local target="$1"
+    local timeout_s="${2:-5}"
+    local lockdir="${target}.lockdir"
+    local target_dir
+    target_dir=$(dirname "$target")
+    [ -d "$target_dir" ] || mkdir -p "$target_dir" 2>/dev/null || true
+
+    # 50ms poll interval -> 20 attempts/sec.
+    local max_attempts=$(( timeout_s * 20 ))
+    [ "$max_attempts" -lt 1 ] && max_attempts=1
+    local attempts=0
+
+    while ! mkdir "$lockdir" 2>/dev/null; do
+        if _loki_lock_is_stale "$lockdir"; then
+            rm -rf "$lockdir" 2>/dev/null || true
+            continue
+        fi
+        attempts=$((attempts + 1))
+        if [ "$attempts" -ge "$max_attempts" ]; then
+            return 1
+        fi
+        _loki_lock_sleep_50ms
+    done
+
+    # Stamp sentinel for stale detection.
+    echo "$$" > "$lockdir/owner.pid" 2>/dev/null || true
+    return 0
+}
+
+# safe_release_lock <target>
+# Releases the mutex on <target>.lockdir. Idempotent.
+safe_release_lock() {
+    local target="$1"
+    local lockdir="${target}.lockdir"
+    rm -rf "$lockdir" 2>/dev/null || true
+    return 0
+}
+
+# safe_with_lock <target> <command> [args...]
+# Runs <command args...> under an exclusive lock on <target>. Releases the
+# lock automatically (trap-based) even on signal. Returns the command's
+# exit code. If the lock cannot be acquired within 5s, returns 1 without
+# running the command (caller can detect via $?).
+safe_with_lock() {
+    local target="$1"; shift
+    if ! safe_acquire_lock "$target" 5; then
+        return 1
+    fi
+    # Trap at caller scope so signal-driven termination still releases.
+    # We keep this in the current shell (not a subshell) so the trap can
+    # see the local $target. We carefully restore any prior EXIT trap.
+    local rc=0
+    local _prev_exit_trap
+    _prev_exit_trap=$(trap -p EXIT 2>/dev/null)
+    # shellcheck disable=SC2064
+    trap "safe_release_lock '$target'" EXIT INT TERM HUP
+    "$@"
+    rc=$?
+    safe_release_lock "$target"
+    # Restore prior EXIT trap (or clear if none).
+    if [ -n "$_prev_exit_trap" ]; then
+        eval "$_prev_exit_trap"
+    else
+        trap - EXIT INT TERM HUP
+    fi
+    return $rc
+}

package/autonomy/loki

@@ -1379,6 +1379,28 @@ cmd_start() {
         fi
     fi
 
+    # v7.5.12 Gap B: Stale-PID detection. Hard-kill (Ctrl+C followed by SIGKILL or
+    # `loki stop`) can leave .loki/loki.pid + .loki/session.lock orphaned. The
+    # next `loki start` then refuses to launch -- or worse, run.sh's downstream
+    # cleanup may treat the stale pid as live. Detect-and-clean here, BEFORE
+    # exec, so the user gets one clear log line instead of mysterious silent
+    # behavior.
+    local _start_loki_dir="${LOKI_DIR:-.loki}"
+    local _start_pid_file="$_start_loki_dir/loki.pid"
+    if [ -f "$_start_pid_file" ]; then
+        local _existing_pid
+        _existing_pid=$(cat "$_start_pid_file" 2>/dev/null | tr -dc '0-9')
+        if [ -n "$_existing_pid" ] && kill -0 "$_existing_pid" 2>/dev/null; then
+            echo -e "${RED}Error: another loki instance is running (pid $_existing_pid).${NC}" >&2
+            echo -e "${YELLOW}Run 'loki stop' first, then retry 'loki start'.${NC}" >&2
+            exit 1
+        fi
+        # PID is stale (file present but process gone). Log + remove + continue.
+        echo -e "${YELLOW}Removing stale pid file ($_start_pid_file, pid=${_existing_pid:-empty} not alive)${NC}" >&2
+        rm -f "$_start_pid_file" 2>/dev/null || true
+        rm -f "$_start_loki_dir/session.lock" 2>/dev/null || true
+    fi
+
     # Determine effective provider for display
     local effective_provider="${provider:-${LOKI_PROVIDER:-claude}}"