@indigoai-us/hq-cli 5.314.0 → 5.316.0

package/assets/scaffold/core/scripts/checkpoint-stop-gate.sh

@@ -5,6 +5,12 @@
 
 set -uo pipefail
 
+# The main block ends with `} 2>/dev/null`: a Stop hook must not spray
+# diagnostics into a session. Keep one copy of the real stderr so a
+# misconfigured operator switch — the one failure the operator alone can fix,
+# and otherwise invisible — still has somewhere to be said.
+exec 3>&2
+
 {
   self_hq="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")/../.." 2>/dev/null && pwd)"
   HQ="${CLAUDE_PROJECT_DIR:-${HQ_ROOT:-$self_hq}}"
@@ -49,7 +55,168 @@ set -uo pipefail
     return 0
   }
 
+  # checkpoint_gate_trim — strips only the edges. Deleting interior whitespace
+  # would quietly repair a typo: "f alse" would become a valid `false` and
+  # disable the gate the operator was trying to keep on.
+  checkpoint_gate_trim() {
+    local s="$1"
+    s="${s#"${s%%[![:space:]]*}"}"
+    s="${s%"${s##*[![:space:]]}"}"
+    printf '%s' "$s"
+  }
+
+  # checkpoint_gate_setting — one operator switch, resolved the way hq-cli
+  # resolves it: the process environment first, then the HQ root's
+  # `.claude/settings.json` `env` block (overlaid by `settings.local.json`, the
+  # order Claude Code merges them).
+  #
+  # Reading the file matters because only Claude Code exports that block into
+  # hook processes. Under Codex or grok the variable is never set, so an
+  # operator who wrote the switch into settings.json would have had it silently
+  # ignored on exactly the runtimes where they cannot see why. Fail-open: any
+  # missing file, absent jq, or unreadable value leaves the gate at its default.
+  #
+  # Prints the raw value and returns 0 when one resolves. Returns 1 when the
+  # highest-priority file that mentions the key holds something unreadable — a
+  # present key stops the lookup rather than falling through, so a stale `"0"`
+  # further down cannot be promoted by a typo in the file above it. Same
+  # precedence the TypeScript resolver uses.
+  checkpoint_gate_setting() {
+    local key="$1" value="" file raw
+    eval "value=\${$key:-}"
+    value="$(checkpoint_gate_trim "$value")"
+    if [ -n "$value" ]; then
+      printf '%s' "$value"
+      return 0
+    fi
+    command -v jq >/dev/null 2>&1 || return 0
+    for file in "$HQ/.claude/settings.local.json" "$HQ/.claude/settings.json"; do
+      [ -r "$file" ] || continue
+      # Strings, and JSON's own true/false/0/1 — the literal an operator reaches
+      # for first — all resolve; null, an object, or an array does not. The
+      # leading marker separates "absent" (no output) from "present but
+      # unreadable" (`-`), which a bare value could not encode.
+      raw="$(jq -r --arg k "$key" '
+        try (
+          if (.env | type) == "object" and (.env | has($k))
+          then (.env[$k]
+                | if type == "string" or type == "boolean" or type == "number"
+                  then "+" + tostring
+                  else "-" end)
+          else empty end
+        ) catch empty' "$file" 2>/dev/null || true)"
+      case "$raw" in
+        "") continue ;;
+        -*) ;;
+        +*)
+          value="$(checkpoint_gate_trim "${raw#+}")"
+          if [ -n "$value" ]; then
+            printf '%s' "$value"
+            return 0
+          fi
+          ;;
+      esac
+      printf 'checkpoint-stop-gate: ignoring %s in %s (not a value it can read; expected a string such as "0" or "1")\n' \
+        "$key" "$file" >&3 2>/dev/null
+      return 1
+    done
+    return 0
+  }
+
+  # Normalizes one switch to 0, 1, or empty (= not set). An unreadable value is
+  # named on stderr rather than passed over: the operator asked for something.
+  checkpoint_gate_switch() {
+    local key="$1" raw
+    raw="$(checkpoint_gate_setting "$key" 2>/dev/null)" || return 0
+    [ -n "$raw" ] || return 0
+    case "$(printf '%s' "$raw" | tr '[:upper:]' '[:lower:]')" in
+      0|false|off|no) printf '0' ;;
+      1|true|on|yes) printf '1' ;;
+      *) printf 'checkpoint-stop-gate: ignoring %s=%s (expected 0/1, false/true, off/on or no/yes)\n' "$key" "$raw" >&3 2>/dev/null ;;
+    esac
+    return 0
+  }
+
+  # checkpoint_gate_bound_company <hq-root> <session-id> — the session's
+  # declared company slug: scope-capability.json first, then meta.yaml. Prints
+  # empty when the session has no binding.
+  checkpoint_gate_bound_company() {
+    local root="$1" sid="$2" co="" cap meta
+    [ -n "$sid" ] || return 0
+    cap="$root/workspace/sessions/$sid/scope-capability.json"
+    if [ -r "$cap" ]; then
+      co="$(jq -r '.company_slug // empty' "$cap" 2>/dev/null || true)"
+    fi
+    if [ -z "$co" ]; then
+      meta="$root/workspace/sessions/$sid/meta.yaml"
+      if [ -r "$meta" ]; then
+        co="$(awk '
+          $1 == "company_slug:" {
+            sub(/^[^:]+:[[:space:]]*/, "")
+            gsub(/^"|"$/, "")
+            print
+            exit
+          }
+        ' "$meta" 2>/dev/null || true)"
+      fi
+    fi
+    printf '%s' "$co"
+  }
+
+  # checkpoint_gate_company_off <hq-root> <session-id> — succeeds only when the
+  # session's company owner has turned the checkpoint gate off
+  # (companySettings.checkpointGateEnabled = false) according to the local
+  # cache written by `hq core checkpoint-gate-setting --refresh`. The hook
+  # never calls the network: a missing or stale cache starts one detached,
+  # rate-limited refresh and the current turn uses whatever the cache holds.
+  # On, unset, no cache, no company, `personal`, or anything unreadable keeps
+  # the gate on. The refresh removes the cache while the
+  # `checkpoint.gate.company-setting` hq-flag is off, so the setting has no
+  # effect until the flag is on.
+  checkpoint_gate_company_off() {
+    local co dir cache stamp value fetched now stamp_mtime
+    co="$(checkpoint_gate_bound_company "$1" "$2")"
+    case "$co" in
+      ""|personal) return 1 ;;
+      *[!a-z0-9-]*) return 1 ;;
+    esac
+    [ -n "${HOME:-}" ] || return 1
+    dir="${HOME}/.hq/cache/checkpoint-gate"
+    cache="$dir/$co.json"
+    stamp="$dir/$co.refresh"
+    value=""
+    fetched=""
+    if [ -r "$cache" ]; then
+      value="$(jq -r 'if .checkpointGateEnabled == false then "off" elif .checkpointGateEnabled == true then "on" else "" end' "$cache" 2>/dev/null || true)"
+      fetched="$(jq -r '.fetched_at // empty | numbers | floor' "$cache" 2>/dev/null || true)"
+    fi
+    now="$(date +%s 2>/dev/null || true)"
+    case "$now" in ''|*[!0-9]*) now="" ;; esac
+    case "$fetched" in ''|*[!0-9]*) fetched=0 ;; esac
+    if [ -n "$now" ] && [ $((now - fetched)) -gt 600 ] && command -v hq >/dev/null 2>&1; then
+      stamp_mtime="$(stat -c %Y "$stamp" 2>/dev/null || stat -f %m "$stamp" 2>/dev/null || printf 0)"
+      case "$stamp_mtime" in ''|*[!0-9]*) stamp_mtime=0 ;; esac
+      if [ $((now - stamp_mtime)) -gt 600 ] && mkdir -p "$dir" 2>/dev/null && touch "$stamp" 2>/dev/null; then
+        (nohup hq core checkpoint-gate-setting --refresh --company "$co" >/dev/null 2>&1 3>&- &)
+      fi
+    fi
+    [ "$value" = off ]
+  }
+
   input="$(cat 2>/dev/null || printf '{}')"
+  input_reply_evidence="$(printf '%s' "$input" | jq -r '
+    if has("last_assistant_message") then
+      if (.last_assistant_message | type) == "string" then
+        "present:" + ((.last_assistant_message | gsub("\\s+"; "") | length) | tostring)
+      elif (.last_assistant_message | type) == "array" then
+        "present:" + (([.last_assistant_message[]? | (.text? // "")] | join("") | gsub("\\s+"; "") | length) | tostring)
+      else
+        "invalid"
+      end
+    else
+      "absent"
+    end
+  ' 2>/dev/null || printf 'invalid')"
   input_fields="$(printf '%s' "$input" | jq -r '[.transcript_path // "", .session_id // ""] | @tsv' 2>/dev/null)" || exit 0
   IFS=$'\t' read -r transcript_path session_id <<<"$input_fields" || exit 0
 
@@ -57,6 +224,15 @@ set -uo pipefail
   # recursively demand another checkpoint of itself.
   [ "${HQ_CHECKPOINT_SIBLING:-}" = "1" ] && exit 0
 
+  # Resolved once: every branch below reads this instead of the raw variable.
+  gate_switch="$(checkpoint_gate_switch HQ_CHECKPOINT_GATE)"
+  # That was the only diagnostic, so drop the duplicate before anything is
+  # spawned. The detached `nohup ... &` commands below redirect fds 1 and 2
+  # only: a surviving fd 3 would be inherited by them and hold the hook
+  # runner's stderr pipe open, so a runner that reads stderr to EOF would wait
+  # on the supposedly detached checkpoint instead of on this shell.
+  exec 3>&-
+
   # Company-scope gate ---------------------------------------------------------
   # An OPT-IN requirement layered onto this Stop hook: for an operator whose
   # email domain is listed in HQ_CHECKPOINT_SCOPE_GATE_DOMAINS (comma-separated,
@@ -69,7 +245,7 @@ set -uo pipefail
   # alongside the checkpoint gate. Binding is a single recoverable call, so the
   # block loops only until the operator declares a scope.
   gate_domains="${HQ_CHECKPOINT_SCOPE_GATE_DOMAINS:-}"
-  case "${HQ_CHECKPOINT_GATE:-}" in
+  case "$gate_switch" in
     0) ;;
     *)
       gate_session_id="$(printf '%s' "$input" | jq -r '.session_id // ""' 2>/dev/null || true)"
@@ -91,24 +267,7 @@ set -uo pipefail
         fi
         if [ "$gate_match" = 1 ]; then
           gate_root="${HQ_ROOT:-${CLAUDE_PROJECT_DIR:-$self_hq}}"
-          bound_co=""
-          gate_cap="$gate_root/workspace/sessions/$gate_session_id/scope-capability.json"
-          if [ -r "$gate_cap" ]; then
-            bound_co="$(jq -r '.company_slug // empty' "$gate_cap" 2>/dev/null || true)"
-          fi
-          if [ -z "$bound_co" ]; then
-            gate_meta="$gate_root/workspace/sessions/$gate_session_id/meta.yaml"
-            if [ -r "$gate_meta" ]; then
-              bound_co="$(awk '
-                $1 == "company_slug:" {
-                  sub(/^[^:]+:[[:space:]]*/, "")
-                  gsub(/^"|"$/, "")
-                  print
-                  exit
-                }
-              ' "$gate_meta" 2>/dev/null || true)"
-            fi
-          fi
+          bound_co="$(checkpoint_gate_bound_company "$gate_root" "$gate_session_id")"
           # A binding satisfies the gate only when it names a REAL scope: the
           # reserved `personal`, or an actual tenant directory. hq-session will
           # still store a typo'd or invented slug (it validates only the
@@ -120,7 +279,7 @@ set -uo pipefail
             *) [ -d "$gate_root/companies/$bound_co" ] && gate_bound=1 ;;
           esac
           if [ "$gate_bound" = 0 ]; then
-            company_reason="$(printf 'This session has not declared its scope, and a scope is required before the turn can end. Decide where this work belongs, then bind the session and finish the turn with your user-facing reply as the final text after the command output:\n\n  bash %s/core/scripts/hq-session.sh --session-id %s set company_slug <company-slug>\n\nUse a real tenant slug from companies/manifest.yaml — the company this session is actually working in, never an invented one. If this session does no company-scoped work, bind it to the reserved personal scope instead:\n\n  bash %s/core/scripts/hq-session.sh --session-id %s set company_slug personal\n\nAn operator can also disable this requirement for the run by exporting HQ_CHECKPOINT_GATE=0.' "$gate_root" "$gate_session_id" "$gate_root" "$gate_session_id")"
+            company_reason="$(printf 'This session has not declared its scope, and a scope is required before the turn can end. Decide where this work belongs, then bind the session and finish the turn with your user-facing reply as the final text after the command output:\n\n  bash %s/core/scripts/hq-session.sh --session-id %s set company_slug <company-slug>\n\nUse a real tenant slug from companies/manifest.yaml — the company this session is actually working in, never an invented one. If this session does no company-scoped work, bind it to the reserved personal scope instead:\n\n  bash %s/core/scripts/hq-session.sh --session-id %s set company_slug personal\n\nAn operator can also disable this requirement for the run by exporting HQ_CHECKPOINT_GATE=0, or for every runtime by putting \"env\": {\"HQ_CHECKPOINT_GATE\": \"0\"} in .claude/settings.json.' "$gate_root" "$gate_session_id" "$gate_root" "$gate_session_id")"
             printf '{"decision":"block","reason":%s}\n' "$(printf '%s' "$company_reason" | hq_json_encode)"
             exit 0
           fi
@@ -129,11 +288,18 @@ set -uo pipefail
       ;;
   esac
 
+  # Company setting: an owner can turn the checkpoint requirement off for
+  # their company's sessions. An explicit operator switch (0 or 1) wins over it.
+  if [ -z "$gate_switch" ] &&
+    checkpoint_gate_company_off "${HQ_ROOT:-${CLAUDE_PROJECT_DIR:-$self_hq}}" "$session_id"; then
+    exit 0
+  fi
+
   runtime="${HQ_CHECKPOINT_RUNTIME:-claude}"
 
   # Operator switches precede runtime and identity eligibility. A forced gate
   # intentionally bypasses the rollout rules for local trials and tests.
-  case "${HQ_CHECKPOINT_GATE:-}" in
+  case "$gate_switch" in
     0) exit 0 ;;
     1) enforce=true ;;
     *)
@@ -151,7 +317,7 @@ set -uo pipefail
 
   refresh_eligibility() {
     command -v hq >/dev/null 2>&1 || return 0
-    (nohup env HQ_CHECKPOINT_RUNTIME="$runtime" hq core checkpoint --gate-probe >/dev/null 2>&1 &)
+    (nohup env HQ_CHECKPOINT_RUNTIME="$runtime" hq core checkpoint --gate-probe >/dev/null 2>&1 3>&- &)
   }
 
   if [ "$runtime" = "codex" ] && [ "$enforce" = false ]; then
@@ -191,6 +357,15 @@ set -uo pipefail
   session_key="$(hq_hook_safe_session_key "$session_id")"
   [ -n "$session_key" ] || exit 0
 
+  reply_ambiguity_log="$state_dir/checkpoint-stop-gate-ambiguity.log"
+  log_reply_ambiguity() {
+    local reason="$1"
+    local timestamp
+    timestamp="$(date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || printf 'unknown-time')"
+    printf '%s\t%s\treply-evidence-ambiguous\t%s\n' "$timestamp" "$session_key" "$reason" \
+      >>"$reply_ambiguity_log" 2>/dev/null || true
+  }
+
   # Parse only the recent JSONL tail. Claude and Codex persist different row
   # shapes, so normalize both to the same user/tool boundary before checking
   # whether the final action was the checkpoint command.
@@ -231,7 +406,11 @@ set -uo pipefail
       else ""
       end;
     def checkpoint_command:
-      test("(^|[;&|(\\s])(command\\s+)?([A-Za-z_][A-Za-z0-9_]*=[^\\s]*\\s+)*hq\\s+core\\s+checkpoint(\\s|$)");
+      # Match the actual command at a shell command boundary. A whitespace
+      # boundary alone would accept `echo hq core checkpoint`; allow only the
+      # shell wrappers and environment assignments that can invoke hq itself.
+      # Quoted assignment values and executable paths may contain spaces.
+      test("(^\\s*|[;&|()]\\s*|\\n\\s*)(?:(?:command|exec)\\s+)?(?:env\\s+)?([A-Za-z_][A-Za-z0-9_]*=(?:\"(?:\\\\.|[^\"\\\\])*\"|\\u0027[^\\u0027]*\\u0027|[^\\s;&|()]*)\\s+)*(?:(?:command|exec|env)\\s+)?(\"[^\"]*[/\\\\]hq\"|[^\\s;&|()]*[/\\\\]hq|hq)\\s+core\\s+checkpoint(\\s|$)");
     def strip_quoted:
       # Remove quoted spans so flag text inside a --summary value (e.g.
       # --summary "investigated --gate-probe behavior") is never mistaken for
@@ -243,12 +422,21 @@ set -uo pipefail
     def checkpoint_flag($flag):
       strip_quoted | test("(^|\\s)" + $flag + "(\\s|$)");
     def pure_checkpoint:
-      # The command is ONLY a checkpoint invocation (optional env-assignment
-      # prefix, no other command joined by a separator). A compound call like
-      # `git status; hq core checkpoint --idle` did other work in the same
-      # tool call, so its exemptions must not apply.
-      strip_quoted
-      | test("^\\s*(command\\s+)?([A-Za-z_][A-Za-z0-9_]*=[^\\s]*\\s+)*hq\\s+core\\s+checkpoint([\\s][^;&|\n]*)?$");
+      # The command is ONLY a checkpoint invocation (recognized wrappers and
+      # env assignments are allowed, but no other command may be joined by a
+      # separator). A compound call like `git status; hq core checkpoint
+      # --idle` did other work in the same tool call, so its exemptions do not
+      # apply.
+      # Normalize a quoted or path-qualified executable to hq before
+      # stripping quoted argument values, so a path with spaces still gets
+      # the same --idle exemptions.
+      (capture("^(?<prefix>\\s*(?:(?:command|exec)\\s+)?(?:env\\s+)?([A-Za-z_][A-Za-z0-9_]*=(?:\"(?:\\\\.|[^\"\\\\])*\"|\\u0027[^\\u0027]*\\u0027|[^\\s;&|()]*)\\s+)*(?:(?:command|exec|env)\\s+)?)(?<executable>\"[^\"]*[/\\\\]hq\"|[^\\s;&|()]*[/\\\\]hq|hq)(?<tail>\\s+core\\s+checkpoint(?:\\s+[^;&|\n]*)?)$")? // false) as $parts
+      | if $parts == false then false
+        else
+          ($parts.prefix + "hq" + $parts.tail)
+          | strip_quoted
+          | test("^\\s*(?:(?:command|exec)\\s+)?(?:env\\s+)?([A-Za-z_][A-Za-z0-9_]*=(?:\"(?:\\\\.|[^\"\\\\])*\"|\\u0027[^\\u0027]*\\u0027|[^\\s;&|()]*)\\s+)*(?:(?:command|exec|env)\\s+)?hq\\s+core\\s+checkpoint([\\s][^;&|\n]*)?$")
+        end;
     def gate_feedback_user:
       # This gate surfaces its own Stop feedback as a synthetic user row. That
       # row is a turn boundary for the checkpoint requirement, but NOT for
@@ -372,7 +560,12 @@ set -uo pipefail
           else (if $seg_reply_chars > 0 then "0-replied" else "0-unreplied" end)
           end
       end
-  ' 2>/dev/null)" || exit 0
+  ' 2>/dev/null)"
+  parsed_status=$?
+  if [ "$parsed_status" -ne 0 ]; then
+    log_reply_ambiguity "transcript-parse-failed"
+    exit 0
+  fi
   # A Claude success verdict carries the satisfying checkpoint's tool id, the
   # count of non-whitespace assistant text characters delivered after the
   # genuine turn's last work tool (its user-facing reply, wherever it sits
@@ -397,6 +590,53 @@ set -uo pipefail
     *) exit 0 ;;
   esac
 
+  # Claude's Stop payload carries the final assistant message independently of
+  # the transcript writer. Use the stronger of the two sources: the transcript
+  # can already contain a reply while the payload is empty, and the payload can
+  # arrive before the transcript writer flushes. If neither source can prove a
+  # reply, the evidence is ambiguous rather than proof that no reply exists.
+  # Fail open for the reply demand and record the ambiguity so a host-side
+  # flush regression remains observable without forcing a duplicate.
+  reply_evidence_ambiguous=0
+  case "$reply_chars" in
+    ''|*[!0-9]*) reply_chars=0 ;;
+  esac
+  case "$input_reply_evidence" in
+    present:*)
+      payload_reply_chars="${input_reply_evidence#present:}"
+      case "$payload_reply_chars" in
+        ''|*[!0-9]*) reply_evidence_ambiguous=1 ;;
+        *)
+          if [ "$runtime" = "claude" ]; then
+            if [ "$satisfied" = "1" ]; then
+              if [ "$payload_reply_chars" -gt "$reply_chars" ]; then
+                reply_chars="$payload_reply_chars"
+              fi
+            elif [ "$satisfied" = "0" ] && [ "$payload_reply_chars" -gt 0 ]; then
+              replied=1
+            fi
+          fi
+          ;;
+      esac
+      ;;
+    absent|invalid)
+      if [ "$runtime" = "claude" ] && [ "$reply_chars" -eq 0 ]; then
+        if [ "$satisfied" = "1" ] && [ "$reply_required" = "1" ]; then
+          reply_evidence_ambiguous=1
+        elif [ "$satisfied" = "0" ]; then
+          # A missing checkpoint plus an unflushed reply is also ambiguous;
+          # let the already-replied branch record the turn without asking the
+          # host to repeat text that may already be visible.
+          reply_evidence_ambiguous=1
+          replied=1
+        fi
+      fi
+      ;;
+  esac
+  if [ "$reply_evidence_ambiguous" = "1" ]; then
+    log_reply_ambiguity "payload=$input_reply_evidence;transcript-reply-chars=$reply_chars"
+  fi
+
   # Codex tool-result envelopes do not reliably expose a nested shell exit
   # status. The CLI writes this session-scoped stamp only after a successful
   # checkpoint, so require a fresh stamp in addition to the final command.
@@ -449,25 +689,23 @@ set -uo pipefail
 
     # Reply-owed enforcement (Claude runtime only). The checkpoint payload
     # goes to the background sibling, never the user. A genuine turn that did
-    # work and reaches a satisfying checkpoint with (next to) no assistant
-    # text after its last WORK tool call is a turn whose user-facing reply is
-    # missing, however rich the checkpoint flags are: block once and demand
-    # the reply. The window deliberately crosses this gate's own feedback
+    # work and reaches a satisfying checkpoint must have some user-facing text
+    # after its last WORK tool call. The window crosses this gate's feedback
     # boundaries and accepts a reply on either side of the checkpoint, so an
     # agent that replied and then checkpointed is never told to repeat itself
     # (double-messaging is the failure the reply-aware block variants exist
     # to prevent). Evidence (transcript audit 2026-08-19, 1471 stop-gate
     # checkpoint turns): 2.7% ended with no reply anywhere while the substance
     # lived only in the checkpoint payload. The nudge fires at most once per
-    # checkpoint tool id (stamped in hook-state), so a legitimately terse turn
-    # costs exactly one extra Stop round-trip and the gate can never loop.
-    # Codex is excluded: its Stop feedback is a synthetic re-prompt with its
-    # own delivery contract. HQ_CHECKPOINT_REPLY_MIN overrides the minimum
-    # non-whitespace character threshold; 0 disables the enforcement.
+    # checkpoint tool id (stamped in hook-state). By default, any non-whitespace
+    # reply counts, including a terse reply such as "done.". Codex is excluded:
+    # its Stop feedback is a synthetic re-prompt with its own delivery contract.
+    # HQ_CHECKPOINT_REPLY_MIN can require a longer reply; 0 disables enforcement.
     if [ "$satisfied" = "1" ] && [ "$runtime" = "claude" ] \
-      && [ "$reply_required" = "1" ] && [ -n "$reply_tool_id" ]; then
-      reply_min="${HQ_CHECKPOINT_REPLY_MIN:-80}"
-      case "$reply_min" in ''|*[!0-9]*) reply_min=80 ;; esac
+      && [ "$reply_required" = "1" ] && [ -n "$reply_tool_id" ] \
+      && [ "$reply_evidence_ambiguous" != "1" ]; then
+      reply_min="${HQ_CHECKPOINT_REPLY_MIN:-1}"
+      case "$reply_min" in ''|*[!0-9]*) reply_min=1 ;; esac
       case "$reply_chars" in ''|*[!0-9]*) reply_chars=0 ;; esac
       if [ "$reply_min" -gt 0 ] && [ "$reply_chars" -lt "$reply_min" ] && [ "$block_count" -lt 3 ]; then
         nudge_file="$state_dir/checkpoint-reply-nudge-$session_key"
@@ -511,7 +749,7 @@ set -uo pipefail
        --trigger stop-gate-auto \
        --transcript "$transcript_path" \
        --summary "turn ended with its user-facing reply already delivered" \
-       >/dev/null 2>&1 &)
+       >/dev/null 2>&1 3>&- &)
     rm -f "$block_count_file" 2>/dev/null || true
     exit 0
   fi

package/assets/scaffold/core/scripts/clean-worktree-reconcile-handoff.sh

@@ -0,0 +1,171 @@
+#!/usr/bin/env bash
+# Remove only handoff mirrors that are byte-identical to the incoming branch,
+# so clean-worktree's merge can recreate them from that branch.
+set -euo pipefail
+
+usage() {
+  echo "Usage: clean-worktree-reconcile-handoff.sh <absolute-hq-root> <local-branch>" >&2
+}
+
+if [[ $# -ne 2 ]]; then
+  usage
+  exit 64
+fi
+
+HQ_ROOT="$1"
+BRANCH="$2"
+if [[ "$HQ_ROOT" != /* ]]; then
+  echo "ERROR: HQ root must be an absolute path" >&2
+  usage
+  exit 64
+fi
+if [[ ! -d "$HQ_ROOT" ]]; then
+  echo "ERROR: HQ root is not a directory: $HQ_ROOT" >&2
+  exit 1
+fi
+HQ_ROOT="$(cd -P "$HQ_ROOT" && pwd -P)"
+TOPLEVEL="$(git -C "$HQ_ROOT" rev-parse --show-toplevel 2>/dev/null)" || {
+  echo "ERROR: HQ root is not a Git worktree: $HQ_ROOT" >&2
+  exit 1
+}
+TOPLEVEL="$(cd -P "$TOPLEVEL" && pwd -P)"
+if [[ "$TOPLEVEL" != "$HQ_ROOT" ]]; then
+  echo "ERROR: supplied path is not the Git worktree root: $HQ_ROOT" >&2
+  exit 1
+fi
+
+BRANCH_REF="refs/heads/$BRANCH"
+if ! git -C "$HQ_ROOT" show-ref --verify --quiet "$BRANCH_REF"; then
+  echo "ERROR: incoming branch does not exist locally: $BRANCH" >&2
+  exit 1
+fi
+
+POINTER_PATH="workspace/threads/handoff.json"
+if ! git -C "$HQ_ROOT" cat-file -e "$BRANCH_REF:$POINTER_PATH" 2>/dev/null; then
+  echo "No incoming handoff pointer on $BRANCH; no mirror paths to reconcile."
+  exit 0
+fi
+
+THREAD_PATH="$(git -C "$HQ_ROOT" show "$BRANCH_REF:$POINTER_PATH" | jq -er '.thread_path | select(type == "string")')" || {
+  echo "ERROR: incoming branch handoff pointer has no string thread_path" >&2
+  exit 1
+}
+case "$THREAD_PATH" in
+  workspace/threads/*) ;;
+  *) echo "ERROR: unsafe incoming handoff thread_path: $THREAD_PATH" >&2; exit 1 ;;
+esac
+case "/$THREAD_PATH/" in
+  *"//"*|*"/./"*|*"/../"*)
+    echo "ERROR: unsafe incoming handoff thread_path: $THREAD_PATH" >&2
+    exit 1
+    ;;
+esac
+if [[ "$THREAD_PATH" == "$POINTER_PATH" || "$THREAD_PATH" == *$'\n'* || "$THREAD_PATH" == *$'\r'* ]]; then
+  echo "ERROR: unsafe incoming handoff thread_path: $THREAD_PATH" >&2
+  exit 1
+fi
+if ! git -C "$HQ_ROOT" cat-file -e "$BRANCH_REF:$THREAD_PATH" 2>/dev/null; then
+  echo "ERROR: incoming handoff thread is missing from $BRANCH: $THREAD_PATH" >&2
+  exit 1
+fi
+
+branch_file_matches() {
+  local relative_path="$1" local_file="$2" comparison_status=0
+  if git -C "$HQ_ROOT" show "$BRANCH_REF:$relative_path" | cmp -s - "$local_file"; then
+    return 0
+  else
+    comparison_status=$?
+  fi
+  if [[ "$comparison_status" -eq 1 ]]; then
+    return 1
+  fi
+  return 2
+}
+
+declare -a mirror_paths=("$POINTER_PATH" "$THREAD_PATH")
+declare -a identical_paths=()
+declare -a differing_paths=()
+for relative_path in "${mirror_paths[@]}"; do
+  absolute_path="$HQ_ROOT/$relative_path"
+  if [[ ! -e "$absolute_path" && ! -L "$absolute_path" ]]; then
+    continue
+  fi
+  if [[ -L "$absolute_path" || ! -f "$absolute_path" ]]; then
+    differing_paths+=("$relative_path (not a regular file)")
+    continue
+  fi
+  comparison_status=0
+  if branch_file_matches "$relative_path" "$absolute_path"; then
+    identical_paths+=("$relative_path")
+  else
+    comparison_status=$?
+    if [[ "$comparison_status" -eq 1 ]]; then
+      differing_paths+=("$relative_path (content differs from $BRANCH)")
+    else
+      echo "ERROR: could not compare incoming $relative_path with $absolute_path" >&2
+      exit 1
+    fi
+  fi
+done
+
+if [[ ${#differing_paths[@]} -gt 0 ]]; then
+  for relative_path in "${differing_paths[@]}"; do
+    echo "BLOCK: preserved main-checkout handoff path: $relative_path" >&2
+  done
+  echo "No mirror paths were removed; surface these local files before merging." >&2
+  exit 2
+fi
+
+reconciliation_blocked=0
+for relative_path in "${identical_paths[@]}"; do
+  absolute_path="$HQ_ROOT/$relative_path"
+  if [[ ! -e "$absolute_path" && ! -L "$absolute_path" ]]; then
+    continue
+  fi
+  if [[ -L "$absolute_path" || ! -f "$absolute_path" ]]; then
+    echo "BLOCK: preserved changed main-checkout path: $relative_path" >&2
+    reconciliation_blocked=1
+    continue
+  fi
+
+  destination_dir="$(dirname "$absolute_path")"
+  moved_file="$(mktemp "$destination_dir/.clean-worktree-handoff.XXXXXX")"
+  if ! mv "$absolute_path" "$moved_file"; then
+    rm -f "$moved_file"
+    echo "ERROR: could not safely move mirrored handoff path: $relative_path" >&2
+    exit 1
+  fi
+
+  comparison_status=0
+  if [[ ! -L "$moved_file" && -f "$moved_file" ]] && branch_file_matches "$relative_path" "$moved_file"; then
+    if [[ -e "$absolute_path" || -L "$absolute_path" ]]; then
+      rm -f "$moved_file"
+      echo "BLOCK: a new main-checkout file appeared during reconciliation; preserved it: $relative_path" >&2
+      reconciliation_blocked=1
+    else
+      rm "$moved_file"
+      echo "Reconciled byte-identical handoff mirror: $relative_path"
+    fi
+  else
+    comparison_status=$?
+    if [[ ! -e "$absolute_path" && ! -L "$absolute_path" ]]; then
+      if mv "$moved_file" "$absolute_path"; then
+        echo "BLOCK: handoff path changed during reconciliation; restored it untouched: $relative_path" >&2
+      else
+        echo "BLOCK: handoff path changed during reconciliation; preserved it at $moved_file" >&2
+      fi
+    else
+      echo "BLOCK: handoff path changed during reconciliation; preserved captured file at $moved_file and current path $absolute_path" >&2
+    fi
+    if [[ "$comparison_status" -gt 1 ]]; then
+      echo "ERROR: could not compare incoming $relative_path with its moved file" >&2
+      exit 1
+    fi
+    reconciliation_blocked=1
+  fi
+done
+
+if [[ "$reconciliation_blocked" -ne 0 ]]; then
+  echo "No merge should be attempted until the changed handoff paths are surfaced." >&2
+  exit 2
+fi