loki-mode 7.41.5 → 7.43.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.43.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.43.0 | [Autonomi](https://www.autonomi.dev/) flagship product | ~260 lines core**

package/VERSION

@@ -1 +1 @@
-7.41.5
+7.43.0

package/autonomy/app-runner.sh

@@ -156,6 +156,112 @@ _rewrite_detection_port() {
     _write_detection "$d_type" "$d_command"
 }
 
+# Collect the transitive descendant tree of a PID (children, grandchildren, ...).
+#
+# Echoes one PID per line, deepest-LAST is NOT guaranteed; order is breadth-first
+# from the root. The root PID itself is NOT included. Used by the non-setsid stop
+# fallback (BUG 1): the app is started as `( ... ) &` WITHOUT setsid, so on stock
+# macOS the whole tree (subshell -> bash -lc -> npm -> sh -> node -> workers)
+# inherits the ORCHESTRATOR's process group. A `kill -- -PGID` would therefore
+# signal run.sh and the Claude agent driving it (self-termination), so we MUST
+# walk parent->child links from OUR pid only. This guarantees we never signal a
+# process outside our own subtree: every returned pid has our root as an ancestor.
+#
+# Snapshot semantics: the caller MUST collect the full tree BEFORE sending any
+# signal. If we TERM top-down while walking, grandchildren reparent to init and
+# `pgrep -P <dead-parent>` returns nothing, re-creating the orphaned-worker bug
+# this fix exists to close.
+_app_runner_collect_descendants() {
+    local root="$1"
+    # Guard against empty / init / kernel pids: walking from 0/1 would sweep
+    # unrelated processes. A valid app pid is always > 1.
+    case "$root" in
+        ''|0|1) return 0 ;;
+    esac
+    if ! [[ "$root" =~ ^[0-9]+$ ]]; then
+        return 0
+    fi
+
+    local -a frontier=("$root")
+    local -a found=()
+    local pid child
+    local -a kids
+    # Bound iterations defensively against a pathological/looping tree.
+    local guard=0
+    while [ "${#frontier[@]}" -gt 0 ] && [ "$guard" -lt 10000 ]; do
+        guard=$(( guard + 1 ))
+        pid="${frontier[0]}"
+        frontier=("${frontier[@]:1}")
+        # Direct children of pid.
+        kids=()
+        while IFS= read -r child; do
+            [ -n "$child" ] && kids+=("$child")
+        done < <(pgrep -P "$pid" 2>/dev/null)
+        local k
+        for k in "${kids[@]:-}"; do
+            [ -n "$k" ] || continue
+            found+=("$k")
+            frontier+=("$k")
+        done
+    done
+
+    local f
+    for f in "${found[@]:-}"; do
+        [ -n "$f" ] && printf '%s\n' "$f"
+    done
+}
+
+# Signal an EXPLICIT, pre-captured set of PIDs with a given signal.
+#
+# Usage: _app_runner_signal_pids <SIGNAL> <pid> [pid ...]
+#
+# Why an explicit list and not "(re-)walk from root": a worker that traps
+# SIGTERM (a Node server doing graceful shutdown is the textbook case) survives
+# the TERM phase while its intermediate ancestors (npm, sh) die. Once the
+# ancestors die, the surviving worker reparents to init, so re-deriving the tree
+# from the now-dead root via `pgrep -P` would return NOTHING -- the KILL phase
+# would be skipped and the orphaned, port-holding worker would live on. That is
+# exactly the orphaned-worker bug (BUG 1) resurfacing at the force-kill phase.
+# The fix: the caller snapshots root + all descendants ONCE before any signal,
+# and every phase (TERM, aliveness, KILL) operates over that frozen list.
+#
+# Safety: the caller builds the list from _app_runner_collect_descendants, which
+# only ever follows parent->child links from OUR pid, so the list can never
+# contain a process outside our own subtree. We signal pids individually (never
+# a process group) because in the non-setsid path the app inherits the
+# orchestrator's process group; a group signal would kill run.sh and the agent.
+# Pids are signaled in REVERSE capture order so descendants (captured after the
+# root) are signaled before the root.
+_app_runner_signal_pids() {
+    local sig="$1"; shift
+    local -a pids=("$@")
+    local i p
+    for (( i=${#pids[@]}-1; i>=0; i-- )); do
+        p="${pids[$i]}"
+        case "$p" in
+            ''|0|1) continue ;;
+        esac
+        kill "-${sig}" "$p" 2>/dev/null || true
+    done
+}
+
+# True (0) if ANY pid in the EXPLICIT pre-captured list is still alive.
+# Used by the non-setsid stop grace-wait so a deep worker that outlived the main
+# subshell does not let us fall through to "stopped" prematurely. Operates over
+# the frozen snapshot for the same reason _app_runner_signal_pids does.
+_app_runner_any_alive() {
+    local p
+    for p in "$@"; do
+        case "$p" in
+            ''|0|1) continue ;;
+        esac
+        if kill -0 "$p" 2>/dev/null; then
+            return 0
+        fi
+    done
+    return 1
+}
+
 # Fix #2 (finding #597): reconcile the recorded port with the port the app
 # ACTUALLY bound, using the listen line in app.log as the source of truth. This
 # corrects the dashboard Live Preview even when the app ignores PORT and picks
@@ -887,32 +993,82 @@ app_runner_stop() {
         fi
     fi
 
+    # BUG 1 fix: on the non-setsid fallback (the DEFAULT path on stock macOS,
+    # which has no setsid) capture the FULL process subtree -- root + every
+    # transitive descendant -- ONCE, BEFORE sending any signal. The old
+    # `pkill -TERM -P <pid>` reached only ONE level of children, so deep workers
+    # (npm -> sh -> node -> workers) holding the listening socket survived as
+    # orphans and kept the port bound, blocking the next start.
+    #
+    # Capturing once is load-bearing: a worker that traps SIGTERM survives the
+    # TERM phase while its intermediate ancestors die, then reparents to init.
+    # Re-deriving the tree from the now-dead root would return nothing and skip
+    # the KILL phase, leaving the port-holder alive. Every phase below (TERM,
+    # grace-wait, KILL) operates over this one frozen snapshot instead.
+    local -a _stop_snapshot=()
+    if [ "$_APP_RUNNER_HAS_SETSID" != true ]; then
+        _stop_snapshot=("$_APP_RUNNER_PID")
+        local _snap_d
+        while IFS= read -r _snap_d; do
+            [ -n "$_snap_d" ] && _stop_snapshot+=("$_snap_d")
+        done < <(_app_runner_collect_descendants "$_APP_RUNNER_PID")
+    fi
+
     # Send SIGTERM to process and children
     if [ "$_APP_RUNNER_HAS_SETSID" = true ]; then
+        # setsid path: the app is its own process group leader, so a group
+        # signal reaches the whole tree safely. Unchanged.
         kill -TERM "-$_APP_RUNNER_PID" 2>/dev/null || kill -TERM "$_APP_RUNNER_PID" 2>/dev/null || true
     else
-        pkill -TERM -P "$_APP_RUNNER_PID" 2>/dev/null || true
-        kill -TERM "$_APP_RUNNER_PID" 2>/dev/null || true
+        # Group-kill is NOT used here: in this path the app inherits the
+        # orchestrator's process group, so a group signal would kill run.sh and
+        # the agent driving it. Signal the frozen snapshot, descendants first.
+        _app_runner_signal_pids TERM "${_stop_snapshot[@]}"
     fi
 
-    # Wait up to 5 seconds for graceful shutdown
+    # Wait up to 5 seconds for graceful shutdown. Key the wait on the WHOLE
+    # snapshot being alive (not just the main pid): a deep worker can outlive the
+    # main subshell, and treating the main pid's exit as "done" is exactly what
+    # let workers leak before. setsid path keeps the simpler main-pid check.
     local waited=0
     while [ "$waited" -lt 5 ]; do
-        if ! kill -0 "$_APP_RUNNER_PID" 2>/dev/null; then
-            break
+        if [ "$_APP_RUNNER_HAS_SETSID" = true ]; then
+            kill -0 "$_APP_RUNNER_PID" 2>/dev/null || break
+        else
+            _app_runner_any_alive "${_stop_snapshot[@]}" || break
         fi
         sleep 1
         waited=$(( waited + 1 ))
     done
 
     # Force kill if still running
-    if kill -0 "$_APP_RUNNER_PID" 2>/dev/null; then
+    local _still_alive=false
+    if [ "$_APP_RUNNER_HAS_SETSID" = true ]; then
+        kill -0 "$_APP_RUNNER_PID" 2>/dev/null && _still_alive=true
+    else
+        _app_runner_any_alive "${_stop_snapshot[@]}" && _still_alive=true
+    fi
+    if [ "$_still_alive" = true ]; then
         log_warn "App Runner: process did not stop gracefully, sending SIGKILL"
         if [ "$_APP_RUNNER_HAS_SETSID" = true ]; then
             kill -KILL "-$_APP_RUNNER_PID" 2>/dev/null || kill -KILL "$_APP_RUNNER_PID" 2>/dev/null || true
         else
-            pkill -KILL -P "$_APP_RUNNER_PID" 2>/dev/null || true
-            kill -KILL "$_APP_RUNNER_PID" 2>/dev/null || true
+            # BUG 1 fix (KILL phase): SIGKILL the SAME frozen snapshot (root +
+            # all descendants captured pre-signal), so a TERM-trapping worker
+            # that reparented to init is still force-killed. SIGKILL cannot be
+            # trapped, so this is the terminal guarantee that no port-holder
+            # survives. The snapshot does the real work. The fresh walk below only
+            # adds anything while the root is still alive (a worker spawned during
+            # shutdown); once the root is dead it is empty and the snapshot covers.
+            _app_runner_signal_pids KILL "${_stop_snapshot[@]}"
+            local -a _kill_fresh=()
+            local _kf
+            while IFS= read -r _kf; do
+                [ -n "$_kf" ] && _kill_fresh+=("$_kf")
+            done < <(_app_runner_collect_descendants "$_APP_RUNNER_PID")
+            if [ "${#_kill_fresh[@]}" -gt 0 ]; then
+                _app_runner_signal_pids KILL "${_kill_fresh[@]}"
+            fi
         fi
     fi
 
@@ -1094,6 +1250,11 @@ app_runner_watchdog() {
     # it restarts the stack under the same crash-count circuit breaker.
     if [ "$_APP_RUNNER_IS_DOCKER" = true ] && echo "$_APP_RUNNER_METHOD" | grep -q "docker compose"; then
         if app_runner_health_check; then
+            # BUG 3 fix: the breaker is meant to fire on 5 CONSECUTIVE failures.
+            # A confirmed-healthy observation clears any accumulated count so a
+            # long-lived stack that recovered from a few transient blips is not
+            # tripped permanently on cumulative (non-consecutive) crashes.
+            _APP_RUNNER_CRASH_COUNT=0
             return 0
         fi
         _APP_RUNNER_CRASH_COUNT=$(( _APP_RUNNER_CRASH_COUNT + 1 ))
@@ -1125,6 +1286,11 @@ app_runner_watchdog() {
 
     # Process alive, nothing to do
     if kill -0 "$_APP_RUNNER_PID" 2>/dev/null; then
+        # BUG 3 fix: a confirmed-alive observation clears the accumulated crash
+        # count so the breaker fires only on 5 CONSECUTIVE deaths, not on 5
+        # cumulative crashes that were each successfully recovered over a long
+        # session (which would trip the breaker on a HEALTHY app).
+        _APP_RUNNER_CRASH_COUNT=0
         return 0
     fi
 

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
@@ -1510,8 +1519,17 @@ council_evidence_gate() {
         if committed_files=$(git diff --name-only "$base_sha" HEAD 2>/dev/null); then
             :
         else
-            # Base present but unreachable (e.g. shallow clone): fall back to
-            # working-tree diff vs HEAD (mirrors proof-generator.py fallback).
+            # Base present but UNREACHABLE (e.g. shallow clone, history rewrite,
+            # or `git reset --hard` -- a documented live hazard). The diff vs the
+            # run-start SHA cannot be computed, so we can no longer prove that the
+            # committed-union diff is empty. Treat this as INCONCLUSIVE, not as
+            # positive empty-diff fabrication evidence: an agent that committed
+            # all its work leaves a clean working tree, and `git diff HEAD` would
+            # read empty -> a false BLOCK. We still fall back to the working-tree
+            # diff vs HEAD to capture any uncommitted work, but the empty-diff
+            # block is suppressed below via the diff_inconclusive guard.
+            diff_inconclusive="true"
+            diff_inconclusive_reason="base_unreachable"
             committed_files=$(git diff --name-only HEAD 2>/dev/null || echo "")
         fi
         unstaged_files=$(git diff --name-only HEAD 2>/dev/null || echo "")
@@ -1534,7 +1552,11 @@ council_evidence_gate() {
         else
             diff_files=0
         fi
-        if [ "$diff_files" -eq 0 ]; then
+        # Only treat an empty union as positive fabrication evidence when the
+        # baseline was CONCLUSIVE. If the base SHA was unreachable (history
+        # rewrite / reset --hard), a clean committed tree yields an empty
+        # working-tree diff that must NOT read as empty-diff fabrication.
+        if [ "$diff_files" -eq 0 ] && [ "$diff_inconclusive" != "true" ]; then
             diff_fails="true"
         fi
     fi

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