loki-mode 7.61.0 → 7.63.0

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
@@ -9809,9 +9892,16 @@ CPEOF
             old_cp="${checkpoint_dir}/${old_cp}"
             rm -rf "$old_cp" 2>/dev/null || true
         done
-        # Rebuild index atomically from remaining checkpoints (sorted by epoch)
+        # Rebuild index atomically from remaining checkpoints (sorted by epoch).
+        # BUG-ST-012: sort on the checkpoint dir BASENAME, not the full path.
+        # Checkpoint ids are cp-<iter>-<epoch> so basename field 3 is the epoch,
+        # but a full path like .../loki-mode/.loki/.../cp-N-EPOCH/metadata.json has
+        # extra hyphens (e.g. the loki-mode cwd) that shift the epoch out of field 3.
+        # Prefix each path with a basename-derived key, sort on it, then strip it.
         local tmp_index="${index_file}.tmp.$$"
-        for remaining in $(find "$checkpoint_dir" -maxdepth 2 -name "metadata.json" -path "*/cp-*/*" 2>/dev/null | sort -t'-' -k3 -n); do
+        for remaining in $(find "$checkpoint_dir" -maxdepth 2 -name "metadata.json" -path "*/cp-*/*" 2>/dev/null \
+            | while read -r mp; do printf '%s\t%s\n' "$(basename "$(dirname "$mp")")" "$mp"; done \
+            | sort -t'-' -k3 -n | cut -f2-); do
             [ -f "$remaining" ] || continue
             _CP_META="$remaining" python3 -c "
 import json,os
@@ -12402,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
@@ -13826,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..."

package/autonomy/sandbox.sh

@@ -559,7 +559,7 @@ cleanup_worktrees() {
     while IFS= read -r line; do
         if [[ "$line" == *"$WORKTREE_PREFIX"* ]]; then
             log_info "  Found: $line"
-            ((found++))
+            found=$((found+1))
         fi
     done < <(git worktree list 2>/dev/null)
 
@@ -651,8 +651,18 @@ _desktop_build_env_args() {
         printf -v _escaped '%s' "$GH_TOKEN"
         DESKTOP_ENV_ARGS+=("-e" "GH_TOKEN=$_escaped")
     fi
-    # Forward all LOKI_* env vars via --env-file to avoid shell expansion issues
-    local _env_file="${TMPDIR:-/tmp}/loki-sandbox-env-$$"
+    # Forward all LOKI_* env vars via --env-file to avoid shell expansion issues.
+    # Security: LOKI_* values may include secrets, so the env-file is created with
+    # mktemp (unpredictable name, no symlink race) and restricted to mode 600 before
+    # anything is written into it. The desktop path consumes this file via a
+    # foreground/blocking "docker sandbox exec" (see start_docker_desktop_sandbox),
+    # so the file is no longer needed once the script exits -- an EXIT trap is the
+    # correct cleanup point here. The trap value is baked in (double quotes) so the
+    # local path is captured now rather than re-evaluated at exit when it is out of
+    # scope. We append our removal so we do not clobber any existing INT/TERM trap.
+    local _env_file
+    _env_file="$(mktemp "${TMPDIR:-/tmp}/loki-sandbox-env.XXXXXX")"
+    chmod 600 "$_env_file"
     local _has_loki_vars=false
     local var
     while IFS= read -r var; do
@@ -663,6 +673,11 @@ _desktop_build_env_args() {
     done < <(compgen -v LOKI_ 2>/dev/null || true)
     if [[ "$_has_loki_vars" == "true" ]] && [[ -f "$_env_file" ]]; then
         DESKTOP_ENV_ARGS+=("--env-file" "$_env_file")
+        # shellcheck disable=SC2064
+        trap "rm -f -- '$_env_file'" EXIT
+    else
+        # No LOKI_ vars were forwarded; the file is unused, remove it immediately.
+        rm -f -- "$_env_file"
     fi
 }
 
@@ -1063,13 +1078,23 @@ start_sandbox() {
     if [[ "$SANDBOX_READONLY" == "true" ]]; then
         docker_args+=("--volume" "$PROJECT_DIR:/workspace:ro")
         # Need a writable .loki directory - copy existing state to a temp dir so we
-        # do not start with an empty volume (which would lose config/state)
-        local _loki_state_tmp="${TMPDIR:-/tmp}/loki-sandbox-state-$$"
-        mkdir -p "$_loki_state_tmp"
+        # do not start with an empty volume (which would lose config/state).
+        # Security: created with mktemp -d (unpredictable name, no symlink/predictable
+        # race) and restricted to mode 700 since it holds a copy of the project's .loki
+        # state. Lifecycle: this directory is bind-mounted into a DETACHED container
+        # (see "--detach" in docker_args) that outlives this function, so an EXIT trap
+        # would delete it out from under the running container. Instead, its path is
+        # recorded on the container via a docker label and removed by stop_sandbox()
+        # right before the container is removed. The label survives across separate
+        # script invocations, which a $$-derived name would not.
+        local _loki_state_tmp
+        _loki_state_tmp="$(mktemp -d "${TMPDIR:-/tmp}/loki-sandbox-state.XXXXXX")"
+        chmod 700 "$_loki_state_tmp"
         if [[ -d "$PROJECT_DIR/.loki" ]]; then
             cp -a "$PROJECT_DIR/.loki/." "$_loki_state_tmp/" 2>/dev/null || true
         fi
         docker_args+=("--volume" "$_loki_state_tmp:/workspace/.loki:rw")
+        docker_args+=("--label" "loki.state_dir=$_loki_state_tmp")
     else
         docker_args+=("--volume" "$PROJECT_DIR:/workspace:rw")
     fi
@@ -1237,6 +1262,11 @@ stop_sandbox() {
     if docker ps --format '{{.Names}}' | grep -q "^${CONTAINER_NAME}$"; then
         log_info "Stopping sandbox: $CONTAINER_NAME"
 
+        # Read the read-only-mode temp state dir path recorded as a container label
+        # (see start_sandbox H5 handling). It is removed once the container is gone.
+        local _state_dir=""
+        _state_dir=$(docker inspect --format '{{ index .Config.Labels "loki.state_dir" }}' "$CONTAINER_NAME" 2>/dev/null || true)
+
         # Try graceful stop first (touch STOP file)
         docker exec "$CONTAINER_NAME" touch /workspace/.loki/STOP 2>/dev/null || true
 
@@ -1245,10 +1275,14 @@ stop_sandbox() {
         while [ $waited -lt 10 ]; do
             if ! docker ps --format '{{.Names}}' | grep -q "^${CONTAINER_NAME}$"; then
                 log_success "Sandbox stopped gracefully"
+                # Remove the temp state dir now that the container has stopped.
+                if [[ -n "$_state_dir" ]] && [[ -d "$_state_dir" ]]; then
+                    rm -rf -- "$_state_dir" 2>/dev/null || true
+                fi
                 return 0
             fi
             sleep 1
-            ((waited++))
+            waited=$((waited+1))
         done
 
         # Force stop if still running
@@ -1256,6 +1290,11 @@ stop_sandbox() {
         docker stop --time 5 "$CONTAINER_NAME" 2>/dev/null || true
         docker rm -f "$CONTAINER_NAME" 2>/dev/null || true
 
+        # Remove the temp state dir now that the container is gone.
+        if [[ -n "$_state_dir" ]] && [[ -d "$_state_dir" ]]; then
+            rm -rf -- "$_state_dir" 2>/dev/null || true
+        fi
+
         log_success "Sandbox stopped"
     else
         log_warn "No running sandbox found"

package/autonomy/spec-interrogation.sh

@@ -248,6 +248,61 @@ except Exception:
     return 0
 }
 
+# ---------------------------------------------------------------------------
+# M5: is a (lowercased, trimmed) finding line an honest NEGATIVE / clean-bill
+# report that must NOT be persisted as a finding? Returns 0 (skip) / 1 (keep).
+#
+# Disambiguation (proximity, not co-occurrence): we skip "no/none/nothing/not"
+# closely followed by a PROBLEM-WORD, or a short clean-bill phrase. We KEEP
+# "no <feature>" findings (missing-feature descriptions) and lines where the
+# problem-word is far from the negation (a real finding that mentions an issue).
+# Err toward KEEP when ambiguous.
+# ---------------------------------------------------------------------------
+_spec_line_is_negative() {
+    _SPEC_LINE="$1" python3 -c '
+import os, re
+line = os.environ.get("_SPEC_LINE", "").strip().lower()
+if not line:
+    raise SystemExit(1)  # empty -> handled elsewhere; not our negative
+
+problem = (r"concerns?|issues?|gaps?|conflicts?|contradictions?|"
+           r"ambiguit(?:y|ies)|blind\s*spots?|risks?|problems?|"
+           r"inconsistenc(?:y|ies)|defects?|bugs?|flaws?|weaknesses?")
+
+# Clean-bill phrasings: "looks good/complete/clear/fine", "nothing stands out".
+clean_bill = [
+    r"^(this\s+)?(section|spec|prd|requirement|design)?\s*looks\s+(good|complete|clear|fine|solid|ok|okay)\b",
+    r"^looks\s+(good|complete|clear|fine|solid|ok|okay)\b",
+    r"^(this\s+)?(section|spec|prd)?\s*(is|seems|appears)\s+(complete|clear|fine|well\s*-?\s*defined|unambiguous)\b",
+    r"^nothing\s+(stands?\s+out|notable|of\s+(concern|note)|to\s+(add|flag|report))\b",
+    r"^all\s+(clear|good)\b",
+]
+for pat in clean_bill:
+    if re.search(pat, line):
+        raise SystemExit(0)  # skip
+
+# Proximity negation: a negation word, then within a few words a problem-word.
+# Allow up to ~3 intervening words (handles "no major concerns", "no obvious
+# security issues here" stays KEEP because "issues" is >3 words out? -- no:
+# "security issues" is 1 word out from "obvious"; but the negation must be the
+# CLAUSE START to be a clean negative). We anchor the negation near line start
+# so a mid-sentence "...which is a security issue" (real finding) is NOT matched.
+neg_start = r"^(no|none|nothing|not|n/?a)\b"
+if re.search(neg_start, line):
+    # Within the leading clause (before the first comma / "but" / "however"),
+    # is the negation closely followed by a problem-word?
+    head = re.split(r",|\bbut\b|\bhowever\b|\bexcept\b|\bwhich\b|;", line, 1)[0]
+    # negation word, then 0-3 filler words, then a problem-word.
+    prox = r"\b(no|none|nothing|not)\b(?:\s+\w+){0,3}\s+(?:" + problem + r")\b"
+    if re.search(prox, head):
+        raise SystemExit(0)  # skip: "no major concerns", "nothing stands out"
+    # "no <problem-word>" can also be possessive/standalone: "no concerns."
+    if re.search(r"\b(no)\s+(?:" + problem + r")\b", head):
+        raise SystemExit(0)
+raise SystemExit(1)  # keep
+' 2>/dev/null
+}
+
 # ---------------------------------------------------------------------------
 # Classify a grill report.md into ledger entries.
 # Usage: spec_interrogation_classify_report <report.md path>
@@ -260,7 +315,8 @@ spec_interrogation_classify_report() {
     [ -f "$report" ] || return 1
 
     local section=""
-    local line stripped q
+    local line stripped q marker_line
+    local unparsed_count=0
     while IFS= read -r line || [ -n "$line" ]; do
         # Track the current "### Section" heading.
         case "$line" in
@@ -277,13 +333,44 @@ spec_interrogation_classify_report() {
 
         [ -z "$section" ] && continue
 
-        # Finding lines look like "1. <question>" or "- <question>".
-        case "$line" in
+        # M6: strip LEADING whitespace into a separate var BEFORE the marker
+        # match so indented list items ("  - x", "  * x", "    1. x") parse. We
+        # keep the original $line untouched so the existing "### "/"## " heading
+        # matches above were unaffected.
+        marker_line="${line#"${line%%[![:space:]]*}"}"
+        # Blank / whitespace-only lines are not findings and are not "unparsed".
+        [ -z "$marker_line" ] && continue
+
+        # M6: finding lines historically looked like "1. <q>" or "- <q>". Broaden
+        # to also tolerate "N)" / "N:" numbered forms and the "* " / "+ " markdown
+        # bullet markers, and any of these after leading whitespace (handled
+        # above). The original "N. " and "- " behavior is preserved byte-
+        # identically (first two cases). Exotic Unicode bullet glyphs are NOT
+        # matched (multibyte glob matching is unreliable on bash 3.2). Lines that
+        # match NO marker under an active section are counted (unparsed_count) so
+        # silent finding-loss becomes visible -- the old code dropped "N)", "*",
+        # etc. with a bare "continue".
+        case "$marker_line" in
             [0-9]*". "*)
-                q="${line#*. }" ;;
+                q="${marker_line#*. }" ;;
             "- "*)
-                q="${line#- }" ;;
+                q="${marker_line#- }" ;;
+            [0-9]*") "*)
+                q="${marker_line#*) }" ;;
+            [0-9]*": "*)
+                q="${marker_line#*: }" ;;
+            "* "*)
+                q="${marker_line#"* "}" ;;
+            "+ "*)
+                # "+ " is a valid markdown unordered-list marker too.
+                q="${marker_line#+ }" ;;
             *)
+                # Non-empty section line with no recognized ASCII list marker
+                # (this includes exotic Unicode bullet glyphs, which we do NOT
+                # try to match: multibyte bracket/glob matching is unreliable on
+                # bash 3.2). Count it so the loss is no longer silent (M6), then
+                # skip. The unparsed_count warn after the loop surfaces these.
+                unparsed_count=$((unparsed_count + 1))
                 continue ;;
         esac
 
@@ -294,16 +381,39 @@ spec_interrogation_classify_report() {
         # reports "nothing found" never becomes a persisted finding (and, under
         # "### Contradictions", never deadlocks a clean spec to max-iterations).
         # Match a lowercased copy (bash 3.2 has no ${var,,}); write the original.
-        # Patterns are START-anchored to whole-line negative phrasings so a real
-        # finding that merely contains "no" (e.g. "no input validation on the
-        # login endpoint") is NOT skipped.
+        #
+        # M5 DISAMBIGUATION RULE: skip a line ONLY when it is an honest NEGATIVE
+        # about a PROBLEM-WORD, not when it reports a missing FEATURE.
+        #   skip  "no/none/nothing/not <problem-word>"  where the problem-word
+        #         (concern|issue|gap|problem|conflict|contradiction|ambiguity|
+        #          blind spot|risk|...) appears CLOSE AFTER the negation (within a
+        #          few words -- proximity, NOT co-occurrence anywhere), so
+        #          "No major concerns here" / "Nothing stands out" are skipped but
+        #          "No input validation, which is a security issue" is KEPT (the
+        #          problem-word "issue" is far from the negation, the line is a
+        #          real finding about a missing feature);
+        #   skip  short clean-bill phrases: "looks (good|complete|clear|fine)",
+        #          "nothing (stands out|notable|of concern)", bare "none"/"n/a";
+        #   KEEP  "no <feature>" (e.g. "No rate limiting on the login endpoint")
+        #          -- that DESCRIBES a missing thing and is a real finding.
+        # Err toward KEEPING when ambiguous: a false finding is acked/medium, a
+        # dropped real one is worse.
+        # Known limitation: a finding whose missing-FEATURE name happens to BE a
+        # problem-word (e.g. "No issue tracking is specified") can be mis-skipped
+        # by the "no <problem-word>" rule. This is rare phrasing; we accept it
+        # rather than loosen the rule and let real negatives through.
         local stripped_lc
         stripped_lc="$(printf '%s' "$stripped" | tr '[:upper:]' '[:lower:]')"
+        # Fast path: exact whole-line clean-bill phrasings.
         case "$stripped_lc" in
-            "none"|"none."*|"none found"*|"none identified"*|\
+            "none"|"none."|"none found"*|"none identified"*|\
             "no contradiction"*|"no issues"*|"no conflicts"*|"no problems"*|\
             "no concerns"*|"no gaps"*|"not applicable"*|"n/a"*) continue ;;
         esac
+        # Proximity-based negative detector for reworded honest negatives.
+        if _spec_line_is_negative "$stripped_lc"; then
+            continue
+        fi
 
         local sev class affects assumption
         sev="$(spec_interrogation_severity_for "$section" "$stripped")"
@@ -335,6 +445,14 @@ spec_interrogation_classify_report() {
             "$affects" \
             "grill"
     done < "$report"
+
+    # M6: make any silently-unparsed finding lines visible. The old parser sent
+    # "N)", "N:", "*", bullet glyphs etc. straight to a bare continue, losing
+    # real findings without a trace. We now count them and warn so a malformed
+    # grill report (or a new list style) is diagnosable instead of invisible.
+    if [ "${unparsed_count:-0}" -gt 0 ]; then
+        log_warn "Spec interrogation: ${unparsed_count} non-empty section line(s) under a finding heading did not match a known list marker and were skipped (report=${report})."
+    fi
     return 0
 }
 
@@ -394,24 +512,139 @@ spec_interrogation_external_check() {
     # No declared dependencies => no concrete repo signal => nothing to conflict.
     [ -n "$manifests" ] || return 0
 
-    # Lowercase the spec body and the manifest text once.
-    local spec_lc deps_lc
+    # Lowercase the spec body once.
+    local spec_lc
     spec_lc="$(tr '[:upper:]' '[:lower:]' < "$spec_path" 2>/dev/null)"
+    [ -n "$spec_lc" ] || return 0
+
+    # H4 fix: collect declared DEPENDENCY NAMES, one per line, lowercased -- NOT
+    # the entire manifest text. The old code grepped driver tokens (e.g. the
+    # 2-char "pg") as UNANCHORED substrings of the whole manifest blob, so "pg"
+    # matched the word "upgrade" in package.json scripts, any URL containing
+    # "pg", etc. That wrote a high/contradictory ledger entry on a CLEAN spec
+    # (contradictions are never auto-acked, so the completion gate never cleared
+    # and the run ground to max-iterations) -- a direct violation of this
+    # function's positive-conflict-only contract.
+    #
+    # For package.json we parse JSON and emit ONLY the keys under
+    # dependencies / devDependencies / peerDependencies / optionalDependencies,
+    # which structurally excludes scripts.upgrade (the worst offender). For the
+    # line-oriented manifests (requirements.txt, pyproject.toml, go.mod, Gemfile)
+    # we emit each non-comment line's leading token / quoted module path, which is
+    # the dependency name. Tokens are later matched as a NAME PREFIX (see
+    # _spec_repo_declares_engine), so "psycopg" still matches "psycopg2-binary"
+    # and "mysql" still matches "mysql2" -- no false negatives from anchoring.
+    local dep_names
     # shellcheck disable=SC2086  # word-split of the manifest path list is intended
-    deps_lc="$(cat $manifests 2>/dev/null | tr '[:upper:]' '[:lower:]')"
-    [ -n "$spec_lc" ] && [ -n "$deps_lc" ] || return 0
-
-    # Engine -> concrete driver-dependency token (a dependency name, not prose).
+    dep_names="$(_SPEC_MANIFESTS="$manifests" python3 -c '
+import json, os, re, sys
+names = set()
+for m in os.environ.get("_SPEC_MANIFESTS", "").split():
+    if not m or not os.path.isfile(m):
+        continue
+    base = os.path.basename(m).lower()
+    try:
+        text = open(m, "r", encoding="utf-8", errors="replace").read()
+    except Exception:
+        continue
+    if base == "package.json":
+        try:
+            data = json.loads(text)
+        except Exception:
+            data = None
+        if isinstance(data, dict):
+            for key in ("dependencies", "devDependencies",
+                        "peerDependencies", "optionalDependencies"):
+                section = data.get(key)
+                if isinstance(section, dict):
+                    for dep in section.keys():
+                        names.add(str(dep).lower())
+        continue
+    # Line-oriented manifests: take the leading dependency token of each line.
+    for raw in text.splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#") or line.startswith("//"):
+            continue
+        # Quoted module/gem path (go.mod require, Gemfile gem "name", pyproject).
+        q = re.findall(r"[\x22\x27]([^\x22\x27]+)[\x22\x27]", line)
+        if q:
+            for tok in q:
+                tok = tok.strip().lower()
+                if tok:
+                    names.add(tok)
+            # go.mod / Gemfile also carry a bare leading token sometimes; fall
+            # through to grab it too.
+        # Bare leading token (requirements.txt "psycopg2-binary==2.9",
+        # go.mod "gorm.io/driver/postgres v1.5.0").
+        tok = re.split(r"[\s=<>!~;\[\]()]", line, 1)[0].strip().lower()
+        # Strip a leading directive word (go.mod "require", Gemfile "gem").
+        if tok in ("require", "gem", "module", "go", "toolchain", "exclude",
+                   "replace", "retract"):
+            rest = line.split(None, 1)
+            if len(rest) > 1:
+                tok = re.split(r"[\s=<>!~;\[\]()]", rest[1].strip(), 1)[0].strip().lower()
+                tok = tok.strip("\x22\x27")
+        if tok:
+            names.add(tok)
+for n in sorted(names):
+    print(n)
+' 2>/dev/null)"
+    # No parsed dependency names => no concrete repo signal => nothing to conflict.
+    [ -n "$dep_names" ] || return 0
+
+    # Engine -> concrete driver-dependency tokens (dependency NAMES, not prose).
     # Keys are the engine names we look for in the SPEC; values are the package
-    # tokens that prove the repo is wired to that engine.
+    # name tokens (space-separated) that prove the repo is wired to that engine.
+    # H4: these are matched against extracted dependency NAMES as a name-prefix
+    # (see _spec_repo_declares_engine), never as substrings of the whole manifest.
     _spec_db_driver_token() {
         case "$1" in
-            postgres) printf '%s' 'pg|psycopg|postgresql|asyncpg|node-postgres|sequelize-postgres|gorm.io/driver/postgres' ;;
-            mongodb)  printf '%s' 'mongoose|pymongo|mongodb|motor|go.mongodb.org/mongo-driver' ;;
-            mysql)    printf '%s' 'mysql|mysql2|pymysql|mysqlclient|gorm.io/driver/mysql' ;;
+            postgres) printf '%s' 'pg psycopg postgresql asyncpg node-postgres sequelize-postgres gorm.io/driver/postgres' ;;
+            mongodb)  printf '%s' 'mongoose pymongo mongodb motor go.mongodb.org/mongo-driver' ;;
+            mysql)    printf '%s' 'mysql mysql2 pymysql mysqlclient gorm.io/driver/mysql' ;;
             *)        printf '' ;;
         esac
     }
+    # H4: does the repo's declared dependency NAMES include a driver for engine $1?
+    # Matches each driver token against the extracted dependency names (in
+    # $dep_names, one per line) using EXACT-name OR NAME-PREFIX semantics:
+    #   - exact: name == token                 ("pg" matches a "pg" dep)
+    #   - prefix: name == token + suffix       ("psycopg" matches "psycopg2-binary",
+    #             where suffix begins with a NON-alphanumeric boundary char OR a
+    #             digit, so "mysql" matches "mysql2" but "pg" does NOT match "pgx"
+    #             of an unrelated package -- wait, see below)
+    # We anchor on a delimiter/digit boundary so the 2-char "pg" cannot match an
+    # unrelated longer alpha name, while real versioned variants (mysql2,
+    # psycopg2-binary) still match. Returns 0 if a driver is declared, else 1.
+    _spec_repo_declares_engine() {
+        local engine="$1" tokens
+        tokens="$(_spec_db_driver_token "$engine")"
+        [ -n "$tokens" ] || return 1
+        _SPEC_DEP_NAMES="$dep_names" _SPEC_TOKENS="$tokens" python3 -c '
+import os
+names = set(n.strip().lower() for n in os.environ.get("_SPEC_DEP_NAMES", "").splitlines() if n.strip())
+tokens = [t.strip().lower() for t in os.environ.get("_SPEC_TOKENS", "").split() if t.strip()]
+def matches(name, tok):
+    if name == tok:
+        return True
+    # Path-style tokens (go module paths) match a name that IS that path.
+    if "/" in tok:
+        return name == tok
+    if name.startswith(tok):
+        nxt = name[len(tok):len(tok)+1]
+        # A real driver variant continues with a digit (mysql2) or a delimiter
+        # (psycopg2-binary -> after "psycopg" comes "2"; node-postgres handled
+        # by exact). An unrelated longer alpha name (e.g. "pglite", "pgbouncer")
+        # must NOT match the 2-char "pg" token, so we reject an alpha suffix.
+        return nxt.isdigit() or nxt in ("-", "_", ".")
+    return False
+for name in names:
+    for tok in tokens:
+        if matches(name, tok):
+            raise SystemExit(0)
+raise SystemExit(1)
+' 2>/dev/null
+    }
     # Does the spec name engine $1? Match unambiguous engine names only.
     _spec_names_engine() {
         case "$1" in
@@ -432,11 +665,14 @@ spec_interrogation_external_check() {
 
         # Spec names this engine. Is the repo wired to a DIFFERENT one, with no
         # driver for the spec's engine?
-        local spec_engine_token
-        spec_engine_token="$(_spec_db_driver_token "$spec_engine")"
+        # H4: match driver tokens against the extracted dependency NAMES (exact /
+        # name-prefix), NOT as substrings of the whole manifest. The old blob
+        # grep here could substring-match unrelated text and SUPPRESS a real
+        # conflict (false negative), so this site is fixed too, not just the
+        # firing site below.
         # If the repo DOES declare a driver for the spec's engine, there is no
         # conflict (they agree) -- skip.
-        if printf '%s' "$deps_lc" | grep -E -q -- "$spec_engine_token"; then
+        if _spec_repo_declares_engine "$spec_engine"; then
             continue
         fi
 
@@ -451,10 +687,11 @@ spec_interrogation_external_check() {
             if [ -n "$other_spec_pat" ] && printf '%s' "$spec_lc" | grep -q -e "$other_spec_pat"; then
                 continue
             fi
-            local other_token
-            other_token="$(_spec_db_driver_token "$other_engine")"
-            [ -n "$other_token" ] || continue
-            if printf '%s' "$deps_lc" | grep -E -q -- "$other_token"; then
+            # H4: same name-based match for the firing site -- the repo must
+            # declare a concrete driver NAME for the other engine. This is the
+            # site that wrote the bogus high/contradictory entry on a clean spec
+            # when "pg" substring-matched "upgrade" in package.json scripts.
+            if _spec_repo_declares_engine "$other_engine"; then
                 # UNAMBIGUOUS: spec names X, repo declares a Y driver, repo has
                 # no X driver. Record one high/contradictory external finding.
                 local gap assumption

package/dashboard/__init__.py

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