loki-mode 7.62.0 → 7.63.0

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

package/VERSION

@@ -1 +1 @@
-7.62.0
+7.63.0

package/autonomy/docker-run.sh

@@ -199,19 +199,11 @@ loki_docker_build_argv() {
     argv+=(-e "LOKI_SKIP_PROJECT_REGISTRY=1")
     # Deterministic per-host-path container name: two repos get two distinct
     # concurrent containers (multi-repo parity with the host CLI) and a stable
-    # handle for `loki docker stop`. Hash the workspace path; fall back to a
-    # sanitized basename if no sha tool is present.
-    local _name_hash=""
-    if command -v shasum >/dev/null 2>&1; then
-        _name_hash="$(printf '%s' "$workspace" | shasum -a 256 2>/dev/null | cut -c1-12)"
-    elif command -v sha256sum >/dev/null 2>&1; then
-        _name_hash="$(printf '%s' "$workspace" | sha256sum 2>/dev/null | cut -c1-12)"
-    fi
-    if [ -n "$_name_hash" ]; then
-        argv+=(--name "loki-${_name_hash}")
-    else
-        argv+=(--name "loki-$(basename "$workspace" | tr -c 'A-Za-z0-9_.-' '_')")
-    fi
+    # handle for `loki docker stop`. Computed by loki_docker_container_name
+    # (single source of truth so cmd_stop reaps the exact same name): sha12 of
+    # the workspace path, with a sanitized-basename fallback if no sha tool is
+    # present.
+    argv+=(--name "$(loki_docker_container_name "$workspace")")
     # The container IS the session boundary, so the runner must NOT setsid into
     # a new, detached session: setsid detach inside a `--rm` container makes the
     # `docker run` exit code report 0 even when the runner failed (a user with
@@ -241,3 +233,213 @@ loki_docker_build_argv() {
 
     printf '%s\n' "${argv[@]}"
 }
+
+#===============================================================================
+# Wave-4 Docker helpers (FEAT-DOCKER-DASH / FEAT-DOCKER-PRUNE / FIX-DOCKER-STOP)
+#
+# These are called by autonomy/loki (cmd_docker, cmd_stop). The CLI guards each
+# call with `declare -F <name>` so missing helpers degrade gracefully, but the
+# NAMES below are part of the contract and must not change.
+#
+# Call contracts (Agent A call sites must match exactly):
+#
+#   loki_docker_pick_host_port
+#     args: none
+#     stdout: a single free host port number (nothing else)
+#     port precedence: ${DASHBOARD_DEFAULT_PORT:-${LOKI_DASHBOARD_PORT:-57374}};
+#       if that port is bound, increments to the next free port (up to 50 tries).
+#
+#   loki_docker_pull_and_prune
+#     args: none (reads $LOKI_DOCKER_IMAGE, $LOKI_DOCKER_PRUNE)
+#     gate: LOKI_DOCKER_PRUNE (default 1). When 0 -> returns 0 immediately,
+#       no docker pull and no prune.
+#     side effects: docker pull, then best-effort rmi of OLD/unused
+#       asklokesh/loki-mode images only. Prints an honest summary.
+#     return: always 0 (best-effort; partial rmi failure is non-fatal).
+#
+#   loki_docker_write_runstate <container> <image> [project_dir]
+#     args: $1 container name, $2 image ref, $3 project dir (default $(pwd))
+#     side effect: atomically writes <project_dir>/.loki/docker/run.json:
+#       {"container","image","project_dir","started_at"(ISO8601 UTC)}
+#     return: 0 on success, non-zero if the file could not be written.
+#
+#   loki_docker_clear_runstate [project_dir]
+#     args: $1 project dir (default $(pwd))
+#     side effect: rm -f <project_dir>/.loki/docker/run.json (no error if absent)
+#     return: always 0.
+#
+#   loki_docker_container_name [workspace_path]
+#     args: $1 workspace path (default $(pwd))
+#     stdout: the deterministic container name loki-<sha12 of path>, identical
+#       to the name loki_docker_build_argv assigns (basename fallback if no
+#       sha tool is present). Nothing else on stdout.
+#===============================================================================
+
+# Normalize a docker image identifier for comparison: strip a leading "sha256:"
+# and truncate to the 12-char short form. `docker images --format '{{.ID}}'`
+# emits a short id, while `docker inspect --format '{{.Id}}'` and
+# `docker ps --format '{{.ImageID}}'` emit the full "sha256:<64hex>" form, so
+# the prune logic MUST normalize both sides before comparing -- otherwise the
+# ":latest" / in-use exclusions silently fail and we delete the wrong image.
+_loki_docker_norm_id() {
+    local id="${1#sha256:}"
+    printf '%s' "${id:0:12}"
+}
+
+# Probe seam: returns 0 if $1 (a host port) is FREE, non-zero if bound.
+# Factored out so tests can override it without binding a real socket.
+# Prefers lsof (used elsewhere in the repo), falls back to nc, then to a
+# bash /dev/tcp probe so there is no hard lsof dependency.
+_loki_docker_port_free() {
+    local port="$1"
+    if command -v lsof >/dev/null 2>&1; then
+        ! lsof -i ":$port" >/dev/null 2>&1
+    elif command -v nc >/dev/null 2>&1; then
+        ! nc -z 127.0.0.1 "$port" >/dev/null 2>&1
+    else
+        # /dev/tcp connect: success means something is listening -> port busy.
+        ! (exec 3<>"/dev/tcp/127.0.0.1/${port}") >/dev/null 2>&1
+    fi
+}
+
+# Echo a free host port. Tries the default dashboard port first, then walks up.
+loki_docker_pick_host_port() {
+    local port="${DASHBOARD_DEFAULT_PORT:-${LOKI_DASHBOARD_PORT:-57374}}"
+    local attempts=0
+    while ! _loki_docker_port_free "$port" && [ "$attempts" -lt 50 ]; do
+        port=$((port + 1))
+        attempts=$((attempts + 1))
+    done
+    printf '%s\n' "$port"
+}
+
+# Pull the loki-mode image and prune ONLY old/unused asklokesh/loki-mode images.
+# Triple-scoped safety: (1) reference filter limits enumeration to
+# asklokesh/loki-mode, (2) the just-pulled :latest id is excluded, (3) any id
+# in use by a running container is excluded. NEVER `docker image prune -a`.
+loki_docker_pull_and_prune() {
+    local image="${LOKI_DOCKER_IMAGE:-asklokesh/loki-mode:latest}"
+    local prune="${LOKI_DOCKER_PRUNE:-1}"
+
+    # Opt-out: skip the explicit pull AND the prune entirely.
+    if [ "$prune" = "0" ]; then
+        return 0
+    fi
+
+    if ! command -v docker >/dev/null 2>&1; then
+        echo "loki_docker_pull_and_prune: docker not found; skipping" >&2
+        return 0
+    fi
+
+    echo "Pulling ${image} ..."
+    docker pull "$image" >/dev/null 2>&1 || {
+        echo "loki_docker_pull_and_prune: pull failed; skipping prune" >&2
+        return 0
+    }
+
+    # Capture the just-pulled image id (normalized short form). If inspect
+    # yields nothing we cannot safely exclude the just-pulled image from the
+    # rmi set, so bail rather than risk deleting it.
+    local latest_raw latest_id
+    latest_raw="$(docker inspect --format '{{.Id}}' "$image" 2>/dev/null)"
+    if [ -z "$latest_raw" ]; then
+        echo "loki_docker_pull_and_prune: could not resolve pulled image id; skipping prune" >&2
+        return 0
+    fi
+    latest_id="$(_loki_docker_norm_id "$latest_raw")"
+
+    # Build the in-use set from running containers (image ids AND names).
+    # Normalize ids so a full sha256 id matches the short id from `docker images`.
+    local -A in_use=()
+    local _line _iid _iname
+    while IFS=' ' read -r _iid _iname; do
+        [ -n "$_iid" ] && in_use["$(_loki_docker_norm_id "$_iid")"]=1
+        [ -n "$_iname" ] && in_use["$_iname"]=1
+    done < <(docker ps --format '{{.ImageID}} {{.Image}}' 2>/dev/null)
+
+    # Enumerate ONLY asklokesh/loki-mode images (tagged + dangling), scoped by
+    # the reference filter so a non-loki-mode image is never even considered.
+    local -A candidates=()
+    while read -r _id; do
+        [ -n "$_id" ] && candidates["$(_loki_docker_norm_id "$_id")"]=1
+    done < <(docker images --filter 'reference=asklokesh/loki-mode' --format '{{.ID}}' 2>/dev/null)
+    while read -r _id; do
+        [ -n "$_id" ] && candidates["$(_loki_docker_norm_id "$_id")"]=1
+    done < <(docker images --filter 'reference=asklokesh/loki-mode' --filter 'dangling=true' -q 2>/dev/null)
+
+    # rmi each candidate that is NOT the just-pulled :latest AND NOT in use.
+    local reclaimed=0 cand
+    for cand in "${!candidates[@]}"; do
+        if [ -n "$latest_id" ] && [ "$cand" = "$latest_id" ]; then
+            continue
+        fi
+        if [ -n "${in_use[$cand]:-}" ]; then
+            continue
+        fi
+        if docker rmi "$cand" >/dev/null 2>&1; then
+            reclaimed=$((reclaimed + 1))
+        fi
+    done
+
+    if [ "$reclaimed" -gt 0 ]; then
+        echo "Reclaimed ${reclaimed} old loki-mode image(s)."
+    else
+        echo "Image cleanup: nothing to reclaim."
+    fi
+    return 0
+}
+
+# Write .loki/docker/run.json atomically. See contract block above for args.
+loki_docker_write_runstate() {
+    local container="$1"
+    local image="$2"
+    local project_dir="${3:-$(pwd)}"
+    [ -n "$container" ] || { echo "loki_docker_write_runstate: missing container" >&2; return 2; }
+    [ -n "$image" ] || { echo "loki_docker_write_runstate: missing image" >&2; return 2; }
+
+    local dir="${project_dir}/.loki/docker"
+    mkdir -p "$dir" || return 2
+
+    local started_at
+    started_at="$(date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null)"
+
+    # tmp file in the SAME dir as the target so `mv` is an atomic rename, not a
+    # cross-device copy.
+    local tmp="${dir}/.run.json.$$"
+    {
+        printf '{\n'
+        printf '  "container": "%s",\n' "$container"
+        printf '  "image": "%s",\n' "$image"
+        printf '  "project_dir": "%s",\n' "$project_dir"
+        printf '  "started_at": "%s"\n' "$started_at"
+        printf '}\n'
+    } > "$tmp" || { rm -f "$tmp" 2>/dev/null; return 2; }
+
+    mv -f "$tmp" "${dir}/run.json" || { rm -f "$tmp" 2>/dev/null; return 2; }
+    return 0
+}
+
+# Remove .loki/docker/run.json. No error if it is already gone.
+loki_docker_clear_runstate() {
+    local project_dir="${1:-$(pwd)}"
+    rm -f "${project_dir}/.loki/docker/run.json" 2>/dev/null
+    return 0
+}
+
+# Echo the deterministic container name for a workspace path. This MUST stay
+# byte-identical to the name loki_docker_build_argv assigns (lines ~204-214), so
+# cmd_stop can reap the container by name. Same sha12 logic + basename fallback.
+loki_docker_container_name() {
+    local workspace="${1:-$(pwd)}"
+    local _name_hash=""
+    if command -v shasum >/dev/null 2>&1; then
+        _name_hash="$(printf '%s' "$workspace" | shasum -a 256 2>/dev/null | cut -c1-12)"
+    elif command -v sha256sum >/dev/null 2>&1; then
+        _name_hash="$(printf '%s' "$workspace" | sha256sum 2>/dev/null | cut -c1-12)"
+    fi
+    if [ -n "$_name_hash" ]; then
+        printf '%s\n' "loki-${_name_hash}"
+    else
+        printf '%s\n' "loki-$(basename "$workspace" | tr -c 'A-Za-z0-9_.-' '_')"
+    fi
+}

package/autonomy/loki

@@ -2304,6 +2304,48 @@ cmd_stop() {
         return 0
     fi
 
+    # FIX-DOCKER-STOP (reap side): a `loki docker start` in this folder runs the
+    # build inside a container named loki-<sha12 of workspace>; the host .loki has
+    # no live pid for it, so the legacy "No active session" path would fire while
+    # the container is Up. Reconcile + reap it here, before the session check.
+    # Folder-scoped: the container name derives from THIS folder's run.json (or a
+    # recompute over $(pwd)), so a run in another folder is never touched (AC18).
+    local _docker_reaped=0
+    if command -v docker >/dev/null 2>&1; then
+        local _docker_runstate="$LOKI_DIR/docker/run.json"
+        local _docker_container=""
+        if [ -f "$_docker_runstate" ] && command -v python3 >/dev/null 2>&1; then
+            _docker_container=$(python3 -c "import json,sys; print(json.load(open(sys.argv[1])).get('container',''))" "$_docker_runstate" 2>/dev/null || true)
+        fi
+        # Fallback: recompute the deterministic name via Agent B's helper. cmd_stop
+        # does NOT source docker-run.sh itself (only cmd_docker does), so source it
+        # here, gated on the module existing, to make the helper available.
+        if [ -z "$_docker_container" ]; then
+            local _docker_mod="$_LOKI_SCRIPT_DIR/docker-run.sh"
+            if [ -f "$_docker_mod" ]; then
+                # shellcheck source=/dev/null
+                source "$_docker_mod" 2>/dev/null || true
+                if declare -F loki_docker_container_name >/dev/null 2>&1; then
+                    _docker_container="$(loki_docker_container_name 2>/dev/null || true)"
+                fi
+            fi
+        fi
+        if [ -n "$_docker_container" ]; then
+            # Only reap if a container with exactly this name is actually running.
+            local _running_id
+            _running_id=$(docker ps -q -f "name=^${_docker_container}$" 2>/dev/null || true)
+            if [ -n "$_running_id" ]; then
+                docker stop "$_docker_container" >/dev/null 2>&1 || true
+                # --rm may auto-remove on stop; rm is best-effort (already-gone is fine).
+                docker rm "$_docker_container" >/dev/null 2>&1 || true
+                _docker_reaped=1
+                echo -e "${RED}Stopped docker run: ${_docker_container}${NC}"
+            fi
+        fi
+        # Clear our run-state record regardless (the container is gone or absent).
+        rm -f "$_docker_runstate" 2>/dev/null || true
+    fi
+
     # No session ID given -- stop all running sessions
     if is_session_running; then
         # Stop per-session PIDs first
@@ -2535,7 +2577,7 @@ PYDASH
         else
             echo -e "${RED}STOP signal sent. Execution will halt immediately.${NC}"
         fi
-    else
+    elif [ "$_docker_reaped" != "1" ]; then
         echo -e "${YELLOW}No active session running.${NC}"
         if [ -f "$LOKI_DIR/STOP" ]; then
             echo "STOP signal already present."
@@ -2560,6 +2602,20 @@ PYDASH
         sleep 0.5
         pkill -9 -f "$_stop_all_pat" 2>/dev/null || true
         echo -e "${RED}--all: signalled all loki-run-* processes on this machine.${NC}"
+
+        # FIX-DOCKER-STOP --all: also reap EVERY loki-mode container on this
+        # machine (parity with the machine-wide PID kill above). Best-effort.
+        if command -v docker >/dev/null 2>&1; then
+            local _all_ids
+            _all_ids=$(docker ps -q --filter ancestor=asklokesh/loki-mode 2>/dev/null || true)
+            if [ -n "$_all_ids" ]; then
+                # shellcheck disable=SC2086
+                docker stop $_all_ids >/dev/null 2>&1 || true
+                # shellcheck disable=SC2086
+                docker rm $_all_ids >/dev/null 2>&1 || true
+                echo -e "${RED}--all: stopped all loki-mode docker containers on this machine.${NC}"
+            fi
+        fi
     fi
 }
 
@@ -8084,9 +8140,11 @@ cmd_doctor() {
             local _install
             _install=$(doctor_provider_install_cmd "$_cmd")
             # Route the per-provider install hint to STDERR (fd 2), mirroring the
-            # doctor_probe_note stderr-only pattern above. This keeps the
-            # parity-captured STDOUT byte-identical to the Bun route (which emits
-            # no per-provider Install line) while the user still sees the hint.
+            # doctor_probe_note stderr-only pattern above. The Bun route emits the
+            # same hint on STDOUT immediately after the provider WARN line; under
+            # the parity harness's 2>&1 capture both land adjacent to the WARN, so
+            # the two routes stay byte-identical when an optional provider is absent
+            # (v7.63.0: closed the cline-absent parity gap by adding the Bun hint).
             [ -n "$_install" ] && echo -e "         ${YELLOW}Install: ${_install}${NC}" >&2
         fi
     }
@@ -28857,6 +28915,68 @@ cmd_docker() {
         return 0
     fi
 
+    # Detect the forwarded loki subcommand (first non-dash token in fwd). This
+    # handles `--api start ...` where the wrapper-kept --api precedes `start`.
+    local _fwd_sub=""
+    local _ft
+    for _ft in "${fwd[@]}"; do
+        case "$_ft" in
+            -*) continue ;;
+            *) _fwd_sub="$_ft"; break ;;
+        esac
+    done
+
+    # Is this docker run launched in background mode? Mirrors the loki `start`
+    # background flags (--bg/--background/--detach/-d) that get forwarded into
+    # the container. Used to gate dashboard auto-open exactly like run.sh:~10088.
+    local _docker_bg=0
+    for _ft in "${fwd[@]}"; do
+        case "$_ft" in
+            --bg|--background|--detach|-d) _docker_bg=1; break ;;
+        esac
+    done
+
+    # FEAT-DOCKER-DASH / FEAT-DOCKER-PRUNE / FIX-DOCKER-STOP (start path only):
+    # the container itself stays dashboard-OFF (no published container port).
+    # Instead we drive the HOST dashboard (which already aggregates local +
+    # docker runs) so `loki docker start` feels exactly like local `loki start`.
+    if [ "$_fwd_sub" = "start" ]; then
+        # F3 FEAT-DOCKER-PRUNE: pull latest + prune old loki-mode images before
+        # the run. Gated by LOKI_DOCKER_PRUNE (default 1); =0 opts out (and the
+        # helper also skips the explicit pull). Best-effort, never blocks a run.
+        if [ "${LOKI_DOCKER_PRUNE:-1}" != "0" ] && declare -F loki_docker_pull_and_prune >/dev/null 2>&1; then
+            loki_docker_pull_and_prune || true
+        fi
+
+        # F2 FEAT-DOCKER-DASH: start/reuse the host dashboard (idempotent: an
+        # already-running dashboard short-circuits in cmd_dashboard_start before
+        # the port-in-use check, so the picked port is ignored on reuse). Run in
+        # a subshell so its internal `exit` paths (already-running -> exit 0,
+        # errors -> exit 1) never abort the blocking docker run.
+        local _dash_port="57374"
+        if declare -F loki_docker_pick_host_port >/dev/null 2>&1; then
+            _dash_port="$(loki_docker_pick_host_port 2>/dev/null || echo 57374)"
+        fi
+        ( cmd_dashboard_start --port "$_dash_port" ) || true
+
+        # Auto-open the dashboard in the browser, gated EXACTLY like
+        # run.sh:~10088: a TTY on stdout, not background, and not opted out via
+        # LOKI_NO_AUTO_OPEN=1. cmd_dashboard_open reads the persisted port file,
+        # so the URL is correct even when an existing dashboard was reused.
+        if [ -t 1 ] && [ "$_docker_bg" != "1" ] && [ "${LOKI_NO_AUTO_OPEN:-0}" != "1" ]; then
+            ( cmd_dashboard_open ) || true
+        fi
+
+        # F4 FIX-DOCKER-STOP (write side): record this run's container/state so
+        # `loki stop` in this folder can reap the container. Cleared after the
+        # blocking run returns (mirrors the register_host running/stopped bracket).
+        # The helper requires the container name + image; compute the deterministic
+        # name once (byte-identical to the build-time --name) and pass the resolved image.
+        if declare -F loki_docker_write_runstate >/dev/null 2>&1 && declare -F loki_docker_container_name >/dev/null 2>&1; then
+            loki_docker_write_runstate "$(loki_docker_container_name)" "${LOKI_DOCKER_IMAGE:-asklokesh/loki-mode:latest}" || true
+        fi
+    fi
+
     # Multi-repo unified dashboard (Option B): register THIS project on the host
     # with the real cwd and NO pid, so the existing host dashboard
     # (`loki dashboard`) lists it alongside host `loki start` projects and reads
@@ -28866,6 +28986,11 @@ cmd_docker() {
     "${docker_argv[@]}"
     local rc=$?
     _loki_docker_register_host stopped
+    # F4 FIX-DOCKER-STOP (clear side): runs unconditionally after the blocking
+    # call (not gated on rc), same as register_host stopped.
+    if [ "$_fwd_sub" = "start" ]; then
+        declare -F loki_docker_clear_runstate >/dev/null 2>&1 && loki_docker_clear_runstate || true
+    fi
     [ "$cleanup_creds" = "1" ] && rm -f "$creds" 2>/dev/null || true
     return $rc
 }

package/autonomy/prd-checklist.sh

@@ -33,13 +33,33 @@
 # Configuration
 CHECKLIST_ENABLED=${LOKI_CHECKLIST_ENABLED:-true}
 CHECKLIST_INTERVAL=${LOKI_CHECKLIST_INTERVAL:-5}
-# Guard against zero/negative interval (division by zero in modulo)
-if [ "$CHECKLIST_INTERVAL" -le 0 ] 2>/dev/null; then
+# Normalize the interval. This is sourced into run.sh which runs under
+# `set -uo pipefail`, and CHECKLIST_INTERVAL flows into a modulo at
+# checklist_should_verify (current_iteration % CHECKLIST_INTERVAL).
+# A non-numeric value (e.g. "abc") would be treated as an unbound variable
+# name by arithmetic expansion and abort the host loop; an empty value would
+# cause a divide-by-zero. The old `[ ... -le 0 ] 2>/dev/null` guard only
+# caught numeric <=0 (the `[` error on non-numeric was swallowed and the bad
+# value retained). The case below rejects empty and any non-digit input first
+# (pure string match, never errors), then the arithmetic test is safe.
+case "$CHECKLIST_INTERVAL" in
+    ''|*[!0-9]*) CHECKLIST_INTERVAL=5 ;;   # empty or non-digit -> default
+esac
+# Guard against zero interval (division by zero in modulo); value is all-digits.
+if [ "$CHECKLIST_INTERVAL" -le 0 ]; then
     CHECKLIST_INTERVAL=5
 fi
 CHECKLIST_TIMEOUT=${LOKI_CHECKLIST_TIMEOUT:-30}
-# Guard against zero/negative timeout
-if [ "$CHECKLIST_TIMEOUT" -le 0 ] 2>/dev/null; then
+# Normalize the timeout. It does not flow into arithmetic (only passed as a
+# --timeout CLI arg to checklist-verify.py at line ~650), so it cannot crash
+# the loop, but the same flawed `[ ... -le 0 ] 2>/dev/null` guard would retain
+# a non-numeric value and hand garbage to the downstream tool. Normalize it the
+# same way for robustness.
+case "$CHECKLIST_TIMEOUT" in
+    ''|*[!0-9]*) CHECKLIST_TIMEOUT=30 ;;   # empty or non-digit -> default
+esac
+# Guard against zero timeout; value is all-digits.
+if [ "$CHECKLIST_TIMEOUT" -le 0 ]; then
     CHECKLIST_TIMEOUT=30
 fi
 
@@ -393,6 +413,15 @@ checklist_should_verify() {
 
     # Check iteration interval
     local current_iteration="${ITERATION_COUNT:-0}"
+    # Defensive numeric guard: current_iteration feeds the modulo below, the
+    # single choke point for both operands under `set -uo pipefail`. A
+    # non-numeric value would be treated as an unbound variable name by
+    # arithmetic expansion and abort the sourced host loop. ITERATION_COUNT is
+    # loki-internal (lower risk than the env-driven interval), but normalize
+    # here so the modulo can never crash. Pure string match, never errors.
+    case "$current_iteration" in
+        ''|*[!0-9]*) current_iteration=0 ;;   # empty or non-digit -> treat as 0
+    esac
     if [ "$current_iteration" -eq 0 ]; then
         return 1
     fi

package/autonomy/run.sh

@@ -4901,6 +4901,24 @@ decide_generated_prd_action() {
     if [ ! -f "$sig_file" ]; then
         echo "update"; return 0
     fi
+    # source:"user" short-circuit (LOCK 2): an explicit user-provided PRD was
+    # persisted into the canonical slot. Always use it as-is, never enter the
+    # signature-diff update path -- even if the file hash drifted (hand-edit) or
+    # the codebase changed since. --fresh-prd/LOKI_PRD_REGEN (checked above)
+    # still wins and forces a regenerate. A missing/empty source falls through
+    # to the generated-PRD logic below (defensive: correctness never depends on
+    # a backfilled field).
+    local prd_source
+    prd_source=$(LOKI_SIG_FILE="$sig_file" python3 -c "
+import json, os
+try:
+    print(json.load(open(os.environ['LOKI_SIG_FILE'])).get('source',''))
+except Exception:
+    print('')
+" 2>/dev/null)
+    if [ "$prd_source" = "user" ]; then
+        echo "user_owned"; return 0
+    fi
     local stored stored_prd_sha current cur_prd_sha
     stored=$(LOKI_SIG_FILE="$sig_file" python3 -c "
 import json, os
@@ -5050,11 +5068,76 @@ rec = {
   'prd_sha': os.environ.get('LOKI_PRD_SHA',''),
   'mode': os.environ['LOKI_SIG_MODE'],
   'loki_version': os.environ['LOKI_SIG_VER'],
+  'source': 'generated',
   }
 print(json.dumps(rec))
 " > "$tmp" 2>/dev/null && mv -f "$tmp" "$loki_dir/state/prd-signature.json" 2>/dev/null || rm -f "$tmp" 2>/dev/null
 }
 
+# Persist an explicit user-provided PRD into the canonical generated-PRD slot so
+# later no-file runs continue from it (brownfield reuse), and stamp source:"user"
+# so it is always treated as user-owned (reuse/use-as-is), never incrementally
+# updated. Echoes the canonical relative path (".loki/generated-prd.md") on a
+# successful persist so the caller can repoint prd_path; echoes nothing (empty)
+# and changes no state on any failure (the caller then keeps the original path).
+#
+# $1 = the original user PRD file path (the arg passed to run_autonomous).
+# Reads/writes under "${TARGET_DIR:-.}/.loki" to stay aligned with
+# decide_generated_prd_action and _loki_prd_file_hash (which anchor there too).
+persist_user_prd() {
+    local src="$1"
+    [ -n "$src" ] || { echo ""; return 0; }
+    [ -f "$src" ] || { echo ""; return 0; }
+    # Skip when the source already IS the canonical generated PRD (a no-op copy,
+    # and the no-file reuse path owns that case). Mirrors the persist guard.
+    case "$src" in
+        *.loki/generated-prd.md|*.loki/generated-prd.json) echo ""; return 0 ;;
+    esac
+
+    local loki_dir="${TARGET_DIR:-.}/.loki"
+    mkdir -p "$loki_dir" "$loki_dir/state" 2>/dev/null || { echo ""; return 0; }
+
+    # Atomic copy: write to a temp file in the destination dir, then mv into
+    # place so a concurrent reader never sees a half-written PRD.
+    local dest="$loki_dir/generated-prd.md"
+    local tmp_prd="$loki_dir/.generated-prd.md.tmp.$$"
+    cp -f "$src" "$tmp_prd" 2>/dev/null || { rm -f "$tmp_prd" 2>/dev/null; echo ""; return 0; }
+    mv -f "$tmp_prd" "$dest" 2>/dev/null || { rm -f "$tmp_prd" 2>/dev/null; echo ""; return 0; }
+
+    # Content hash of the PRD we just wrote (over the copied file) + the current
+    # codebase signature, recorded directly (NOT via persist_prd_signature_if_present,
+    # whose guards skip non-canonical/user paths and whose user_owned early-return
+    # would skip it anyway). source:"user" makes decide_generated_prd_action short
+    # circuit to user_owned on every later no-file run (LOCK 2).
+    local prd_sha sig mode
+    prd_sha=$(_loki_prd_file_hash "${TARGET_DIR:-.}")
+    sig=$(compute_codebase_signature "${TARGET_DIR:-.}")
+    mode="files"; case "$sig" in git:*) mode="git" ;; esac
+
+    local sig_tmp="$loki_dir/state/.prd-signature.json.tmp.$$"
+    LOKI_SIG="$sig" LOKI_SIG_MODE="$mode" \
+    LOKI_SIG_VER="$(get_version 2>/dev/null || echo unknown)" \
+    LOKI_PRD_SHA="$prd_sha" LOKI_ORIGIN_PATH="$src" \
+    python3 -c "
+import json, os, datetime
+rec = {
+  'signature': os.environ.get('LOKI_SIG',''),
+  'generated_at': datetime.datetime.now(datetime.timezone.utc).isoformat().replace('+00:00','Z'),
+  'prd_path': '.loki/generated-prd.md',
+  'prd_sha': os.environ.get('LOKI_PRD_SHA',''),
+  'mode': os.environ.get('LOKI_SIG_MODE','files'),
+  'loki_version': os.environ.get('LOKI_SIG_VER','unknown'),
+  'source': 'user',
+  'origin_path': os.environ.get('LOKI_ORIGIN_PATH',''),
+  }
+print(json.dumps(rec))
+" > "$sig_tmp" 2>/dev/null \
+        && mv -f "$sig_tmp" "$loki_dir/state/prd-signature.json" 2>/dev/null \
+        || rm -f "$sig_tmp" 2>/dev/null
+
+    echo ".loki/generated-prd.md"
+}
+
 # generate_proof_of_run: thin fire-and-forget wrapper around the standalone
 # proof-of-run generator (autonomy/lib/proof-generator.py). Runs on both
 # success and failure session ends. The generator owns the schema, redaction
@@ -12409,7 +12492,10 @@ build_prompt() {
     local gate_failure_context=""
     if [ -f "${TARGET_DIR:-.}/.loki/quality/gate-failures.txt" ]; then
         local failures
-        failures=$(cat "${TARGET_DIR:-.}/.loki/quality/gate-failures.txt")
+        # Cap at the FIRST 8000 bytes to bound prompt context growth from a large
+        # prior-iteration gate-failures dump. Parity with the Bun route's
+        # readBytesSafe(gfPath, 8000), which does buf.subarray(0, 8000) (head, not tail).
+        failures=$(head -c 8000 "${TARGET_DIR:-.}/.loki/quality/gate-failures.txt")
         gate_failure_context="QUALITY GATE FAILURES FROM PREVIOUS ITERATION: [$failures]. "
         if [ -f "${TARGET_DIR:-.}/.loki/quality/static-analysis.json" ]; then
             local sa_summary
@@ -13833,6 +13919,31 @@ run_autonomous() {
         source "${SCRIPT_DIR}/lib/sentrux-gate.sh" 2>/dev/null || true
     fi
 
+    # Explicit user PRD persistence (brownfield reuse, LOCK 1/LOCK 2): when the
+    # user passed a real file that is NOT already the canonical generated PRD,
+    # copy its content into .loki/generated-prd.md and stamp source:"user" so a
+    # later no-file run continues from it without re-running codebase analysis,
+    # and never rewrites it. Runs BEFORE the auto-detect block below (which only
+    # handles the empty prd_path case). On any failure persist_user_prd echoes
+    # "" and changes no state, so the original prd_path is preserved.
+    if [ -n "$prd_path" ]; then
+        case "$prd_path" in
+            *.loki/generated-prd.md|*.loki/generated-prd.json) ;;
+            *)
+                if [ -f "$prd_path" ]; then
+                    local _persisted_prd
+                    _persisted_prd=$(persist_user_prd "$prd_path")
+                    if [ -n "$_persisted_prd" ]; then
+                        log_info "Persisted your PRD ($prd_path) to $_persisted_prd; later runs without a file will reuse it as-is"
+                        prd_path="$_persisted_prd"
+                        GENERATED_PRD_ACTION="user_owned"
+                        export GENERATED_PRD_ACTION
+                    fi
+                fi
+                ;;
+        esac
+    fi
+
     # Auto-detect PRD if not provided
     if [ -z "$prd_path" ]; then
         log_step "No PRD provided, searching for existing PRD files..."