@indigoai-us/hq-cli 5.289.0 → 5.290.0

package/assets/scaffold/core/scripts/handoff-finalize.sh

@@ -0,0 +1,670 @@
+#!/bin/bash
+# handoff-finalize.sh — collapse the mechanical tail of /handoff into one call.
+#
+# Folds steps 1/2/3b/4/5/7 of the handoff skill into a single subprocess so the
+# model doesn't narrate each step. Writes the thread file, handoff.json,
+# regenerates INDEX files, commits HQ via explicit paths, and launches qmd
+# reindex fire-and-forget via qmd-reindex-bg.sh (agent skip / laptop single-flight).
+#
+# Usage (all args optional):
+#   handoff-finalize.sh \
+#     --title "Handoff: brief description" \
+#     --summary "What was accomplished" \
+#     --message "User message or autogenerated" \
+#     --next-steps-json '["step 1","step 2"]' \
+#     --files-touched-json '["path1","path2"]' \
+#     --files-touched-json-file workspace/threads/.changeset.json \
+#     --learnings-json '[]' \
+#     --tags-json '["handoff"]' \
+#     --slug "handoff-short-tag" \
+#     --next-command "/startwork"
+#
+# The changeset (files-touched) may be supplied inline via --files-touched-json
+# OR from a file via --files-touched-json-file <path>. Prefer the file form for
+# large changesets: on Windows Git Bash, CreateProcess caps a command line at
+# ~32KB (~8KB under cmd.exe), so a big inline value would overflow argv as it
+# rides through hq-status-summary.sh and jq. The file form keeps the giant JSON
+# off argv at every hop. --files-touched-json-file wins if both are given; a
+# missing file path is a hard error (exit 3). Relative paths resolve against the
+# HQ root.
+#
+# --next-command is copied to the user's clipboard fail-soft (pbcopy /
+# wl-copy / xclip) so the follow-up command is ready to paste into a fresh
+# session. Defaults to "/resumework {thread_id}". Pass "" to skip the copy.
+#
+# Outputs JSON on stdout:
+#   {"thread_id":"...","thread_path":"...","handoff_path":"...",
+#    "hq_committed":true,"hq_commit_status":"committed","hq_commit_error":"",
+#    "committed_paths":[...],"stage_failures":[],"indexes_regen":true,
+#    "qmd_pid":12345,"next_command":"/resumework T-...","clipboard_copied":true}
+#
+# hq_commit_status is the honest reason behind hq_committed:
+#   committed         — the handoff commit landed; committed_paths lists it
+#   nothing-to-commit — no staged change existed; hq_committed:false, exit 0
+#   failed            — git refused the commit; committed_paths is [],
+#                       hq_commit_error carries git's message, exit 4
+#   stage-failed      — git add rejected one or more paths, so the handoff is
+#                       incomplete even if a commit landed for the rest; exit 4.
+#                       This is the shape a held .git/index.lock takes.
+# stage_failures lists paths git add rejected for a reason other than gitignore.
+#
+# Exit codes: 0 ok · 2 bad argument · 3 changeset file missing · 4 handoff not
+# durable (commit refused or paths unstageable).
+
+set -euo pipefail
+
+HQ_ROOT="${HQ_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)}"
+cd "$HQ_ROOT"
+HQ_ROOT="$(pwd -P)"
+HAS_GIT_CHECKOUT="false"
+COMMON_GIT_DIR=""
+GIT_PROBE_OUTPUT=""
+if GIT_PROBE_OUTPUT="$(LC_ALL=C git rev-parse --git-common-dir 2>&1)"; then
+  COMMON_GIT_DIR="$GIT_PROBE_OUTPUT"
+  HAS_GIT_CHECKOUT="true"
+else
+  GIT_PROBE_STATUS=$?
+  if [[ ! -e "$HQ_ROOT/.git" && ! -L "$HQ_ROOT/.git" && \
+        "$GIT_PROBE_OUTPUT" == *"not a git repository"* ]]; then
+    COMMON_GIT_DIR=""
+  else
+    printf 'handoff-finalize: Git checkout probe failed (exit %s): %s\n' \
+      "$GIT_PROBE_STATUS" "$GIT_PROBE_OUTPUT" >&2
+    exit 4
+  fi
+fi
+
+# -------- args --------
+TITLE="Handoff: session continuation"
+SUMMARY=""
+MESSAGE=""
+NEXT_STEPS_JSON="[]"
+FILES_TOUCHED_JSON="[]"
+FILES_TOUCHED_JSON_FILE=""
+LEARNINGS_JSON="[]"
+TAGS_JSON='["handoff"]'
+SLUG="handoff"
+NEXT_COMMAND="__auto__"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --title) TITLE="$2"; shift 2 ;;
+    --summary) SUMMARY="$2"; shift 2 ;;
+    --message) MESSAGE="$2"; shift 2 ;;
+    --next-steps-json) NEXT_STEPS_JSON="$2"; shift 2 ;;
+    --files-touched-json) FILES_TOUCHED_JSON="$2"; shift 2 ;;
+    --files-touched-json-file) FILES_TOUCHED_JSON_FILE="$2"; shift 2 ;;
+    --learnings-json) LEARNINGS_JSON="$2"; shift 2 ;;
+    --tags-json) TAGS_JSON="$2"; shift 2 ;;
+    --slug) SLUG="$2"; shift 2 ;;
+    --next-command) NEXT_COMMAND="$2"; shift 2 ;;
+    *) echo "Unknown arg: $1" >&2; exit 2 ;;
+  esac
+done
+
+# -------- temp-file registry for off-argv JSON --------
+# The Windows argv-overflow fix: any JSON value that scales with the changeset
+# (the changeset itself, and the staged/skipped/committed path lists and status
+# summary derived from it) is written to a temp file and fed to jq via
+# --slurpfile, never via --argjson/--arg on the command line. CreateProcess caps
+# a command line at ~32KB on Git Bash; even POSIX hosts cap a single argument at
+# 128KB (MAX_ARG_STRLEN). A few-thousand-path changeset breaches both. Small,
+# bounded values (title, ids, tags, company slugs, counts) stay inline.
+#
+# Temps live under workspace/threads/.handoff-tmp/ (gitignored) — not beside
+# durable thread JSON — so they never flip git.dirty or baseline_noise before
+# the status-summary call. Do not use /tmp (missing on some Windows Git Bash).
+HANDOFF_TMP_DIR="workspace/threads/.handoff-tmp"
+mkdir -p workspace/threads "$HANDOFF_TMP_DIR"
+FINALIZE_TMP_FILES=()
+cleanup_finalize_tmp() {
+  local f
+  for f in "${FINALIZE_TMP_FILES[@]:-}"; do
+    [[ -n "$f" ]] && rm -f "$f"
+  done
+  return 0
+}
+trap cleanup_finalize_tmp EXIT
+
+# new_tmp NAME: create a registered temp file under .handoff-tmp/ (Git Bash safe;
+# not /tmp) and assign its absolute path to NAME in the *current* shell.
+# Callers must not use VAR=$(new_tmp) — command substitution runs in a subshell,
+# so FINALIZE_TMP_FILES+= would never reach the EXIT trap and temps would leak.
+new_tmp() {
+  local __outvar="$1"
+  local t
+  [[ -n "$__outvar" ]] || { echo "handoff-finalize: new_tmp requires a varname" >&2; exit 3; }
+  t=$(mktemp "$HANDOFF_TMP_DIR/.handoff-XXXXXX")
+  case "$t" in /*) : ;; *) t="$PWD/$t" ;; esac
+  FINALIZE_TMP_FILES+=("$t")
+  printf -v "$__outvar" '%s' "$t"
+}
+
+# -------- resolve changeset source to a single on-disk file --------
+# Every downstream consumer of the changeset (path extraction, hq-status-summary,
+# and the two jq emitters) reads it from FILES_TOUCHED_FILE, never from argv.
+# --files-touched-json-file <path> wins over inline --files-touched-json; the
+# inline form is materialized to a temp file so the read path is uniform.
+if [[ -n "$FILES_TOUCHED_JSON_FILE" ]]; then
+  if [[ ! -f "$FILES_TOUCHED_JSON_FILE" ]]; then
+    echo "handoff-finalize: --files-touched-json-file not found: $FILES_TOUCHED_JSON_FILE" >&2
+    exit 3
+  fi
+  FILES_TOUCHED_FILE="$FILES_TOUCHED_JSON_FILE"
+  case "$FILES_TOUCHED_FILE" in
+    /*) : ;;
+    *) FILES_TOUCHED_FILE="$PWD/$FILES_TOUCHED_FILE" ;;
+  esac
+else
+  new_tmp FILES_TOUCHED_FILE
+  printf '%s' "$FILES_TOUCHED_JSON" > "$FILES_TOUCHED_FILE"
+fi
+
+# -------- changeset path extraction / validation --------
+# Skipped paths accumulate as NDJSON on disk from the first record_skip — never
+# rebuild a growing JSON document via jq argv/here-string (thousands of skips
+# would hit Windows CreateProcess / Linux MAX_ARG_STRLEN before emit).
+new_tmp SKIPPED_NDJSON_FILE
+: > "$SKIPPED_NDJSON_FILE"
+new_tmp SKIPPED_PATHS_FILE
+printf '[]' > "$SKIPPED_PATHS_FILE"
+SAFE_STAGE_PATHS=()
+MIRROR_COMPANIES_JSON="[]"
+MIRRORED_COMPANIES=()
+MIRRORED_COMPANIES_JSON="[]"
+MIRROR_STAGE_PATHS=()
+
+record_skip() {
+  local path="$1"
+  local reason="$2"
+  jq -nc --arg path "$path" --arg reason "$reason" \
+    '{path: $path, reason: $reason}' >> "$SKIPPED_NDJSON_FILE"
+}
+
+is_sensitive_path() {
+  local p="$1"
+  case "$p" in
+    core/settings/.gitkeep|core/settings/pure-ralph.json)
+      return 1
+      ;;
+    .git|.git/*|.env|.env.*|*.credentials.json|*.secret.*|.hq/deploy-passwords.json|.hq/cognito-tokens.json|.claude/settings.local.json|.claude/settings.local.*|companies/*/settings/*|settings/*.json|settings/**/*.json|core/settings/*.json|core/settings/**/*.json)
+      return 0
+      ;;
+    *)
+      return 1
+      ;;
+  esac
+}
+
+normalize_rel_path() {
+  local raw="$1"
+  local rel="$raw"
+  if [[ "$raw" == "$HQ_ROOT/"* ]]; then
+    rel="${raw#"$HQ_ROOT/"}"
+  elif [[ "$raw" == /* ]]; then
+    return 1
+  fi
+  rel="${rel#./}"
+  [[ -z "$rel" ]] && return 1
+  [[ "$rel" == -* || "$rel" == ".." || "$rel" == ../* || "$rel" == */../* || "$rel" == .git || "$rel" == .git/* ]] && return 1
+  printf '%s\n' "$rel"
+}
+
+while IFS=$'\t' read -r raw_path deleted_flag; do
+  [[ -z "${raw_path:-}" ]] && continue
+  if ! rel_path=$(normalize_rel_path "$raw_path"); then
+    record_skip "$raw_path" "unsafe-path"
+    continue
+  fi
+  if is_sensitive_path "$rel_path"; then
+    record_skip "$rel_path" "sensitive-path"
+    continue
+  fi
+  if [[ ! -e "$rel_path" ]]; then
+    if [[ "$HAS_GIT_CHECKOUT" == "true" && "$deleted_flag" == "true" ]] \
+      && git ls-files --error-unmatch "$rel_path" >/dev/null 2>&1; then
+      SAFE_STAGE_PATHS+=("$rel_path")
+    else
+      record_skip "$rel_path" "missing"
+    fi
+    continue
+  fi
+  SAFE_STAGE_PATHS+=("$rel_path")
+done < <(
+  jq -r '
+    if type != "array" then empty else
+      .[] |
+      if type == "string" then
+        [., "false"]
+      else
+        [(.path // ""), (((.deleted == true) or (.status == "deleted")) | tostring)]
+      end | @tsv
+    end
+  ' "$FILES_TOUCHED_FILE" 2>/dev/null || true
+)
+
+# Company workspace mirrors are scoped from the already-validated changeset,
+# never from ambient repository state. A handoff can legitimately touch more
+# than one company, so preserve all unique slugs in durable thread metadata.
+MIRROR_COMPANIES_JSON=$(printf '%s\n' "${SAFE_STAGE_PATHS[@]:-}" | jq -R -s -c '
+  split("\n")
+  | [ .[] | select(length > 0) | try (capture("^companies/(?<company>[a-z][a-z0-9_-]*)/").company) ]
+  | unique
+' 2>/dev/null || printf '[]')
+
+# -------- bg git reap (if launched by caller) --------
+GIT_BG_ERRORS=""
+if [[ -f /tmp/handoff-git-bg.pid ]]; then
+  PID=$(cat /tmp/handoff-git-bg.pid 2>/dev/null || true)
+  if [[ -n "$PID" ]]; then
+    wait "$PID" 2>/dev/null || true
+    if [[ -f /tmp/handoff-git-bg.log ]]; then
+      GIT_BG_ERRORS=$(grep '^ERR:' /tmp/handoff-git-bg.log 2>/dev/null || true)
+    fi
+  fi
+  rm -f /tmp/handoff-git-bg.pid
+fi
+
+# -------- thread file --------
+TS=$(date -u +%Y%m%dT%H%M%SZ)
+DAY=$(date +%Y%m%d)
+HM=$(date +%H%M%S)
+THREAD_ID="T-${DAY}-${HM}-${SLUG}"
+THREAD_PATH="workspace/threads/${THREAD_ID}.json"
+CHANGESET_PATH="workspace/threads/${THREAD_ID}.changeset.json"
+
+BRANCH=$(git symbolic-ref --short HEAD 2>/dev/null || echo "DETACHED")
+START_COMMIT=$(git rev-parse --short HEAD 2>/dev/null || echo "unknown")
+DIRTY="false"
+[[ -n "$(git status --porcelain 2>/dev/null)" ]] && DIRTY="true"
+
+# Status summary and staged-path list both scale with the changeset / repo
+# noise, so they are captured to files and later slurped into jq off argv.
+new_tmp STATUS_SUMMARY_FILE
+printf '{}' > "$STATUS_SUMMARY_FILE"
+if command -v hq >/dev/null 2>&1; then
+  hq core hq-status-summary --session-files-file "$FILES_TOUCHED_FILE" --json > "$STATUS_SUMMARY_FILE" 2>/dev/null \
+    || printf '{}' > "$STATUS_SUMMARY_FILE"
+  # Guard against a truncated/empty write masquerading as success.
+  [[ -s "$STATUS_SUMMARY_FILE" ]] || printf '{}' > "$STATUS_SUMMARY_FILE"
+fi
+BASELINE_NOISE_COUNT=$(jq -r '.counts.baseline_noise // 0' "$STATUS_SUMMARY_FILE" 2>/dev/null || echo 0)
+new_tmp STAGED_PATHS_FILE
+if [[ "$HAS_GIT_CHECKOUT" == "true" ]]; then
+  printf '%s\n' "${SAFE_STAGE_PATHS[@]:-}" | jq -R -s 'split("\n") | map(select(length > 0))' > "$STAGED_PATHS_FILE"
+else
+  printf '[]' > "$STAGED_PATHS_FILE"
+fi
+
+mkdir -p workspace/threads
+# Every next step carries an id and a closure status (2026-09-07). Handoffs
+# used to record steps with no way to close one; an audit found a task copied
+# forward through three consecutive handoffs and never started. Ids are
+# `<thread_id>#<n>`; status starts "open" and is closed by
+# core/scripts/handoff-open-steps.sh close. Strings and {step:...} objects are
+# both accepted; already-normalized objects keep their fields.
+NEXT_STEPS_NORMALIZED_JSON="$(jq -c --arg tid "$THREAD_ID" '
+  to_entries | map(.key as $k |
+    (if (.value|type) == "string" then {step: .value} else .value end)
+    | .id = (.id // ($tid + "#" + (($k + 1)|tostring)))
+    | .status = (.status // "open")
+  ) | map(del(.key))' <<<"$NEXT_STEPS_JSON" 2>/dev/null || printf '%s' "$NEXT_STEPS_JSON")"
+
+jq -n \
+  --arg thread_id "$THREAD_ID" \
+  --arg ts "$TS" \
+  --arg root "$HQ_ROOT" \
+  --arg cwd "$(pwd)" \
+  --arg branch "$BRANCH" \
+  --arg commit "$START_COMMIT" \
+  --arg changeset_path "$CHANGESET_PATH" \
+  --argjson dirty "$DIRTY" \
+  --arg summary "$SUMMARY" \
+  --arg title "$TITLE" \
+  --argjson next_steps "$NEXT_STEPS_NORMALIZED_JSON" \
+  --slurpfile files_touched "$FILES_TOUCHED_FILE" \
+  --argjson learnings "$LEARNINGS_JSON" \
+  --argjson tags "$TAGS_JSON" \
+  --argjson companies "$MIRROR_COMPANIES_JSON" \
+  '{
+    thread_id: $thread_id,
+    version: 1,
+    type: "handoff",
+    created_at: $ts,
+    updated_at: $ts,
+    workspace_root: $root,
+    cwd: $cwd,
+    git: { branch: $branch, current_commit: $commit, dirty: $dirty },
+    changeset_path: $changeset_path,
+    conversation_summary: $summary,
+    next_steps: $next_steps,
+    files_touched: ($files_touched[0] // []),
+    learnings: $learnings,
+    metadata: { title: $title, tags: $tags, company: $companies }
+  }' > "$THREAD_PATH"
+
+# `handoff-finalize.sh` writes from a shell subprocess, so its thread creation
+# does not pass through editor PostToolUse hooks. Replay the installed mirror
+# hook with Bash: hooks are source files and do not require an executable bit.
+MIRROR_HOOK="$HQ_ROOT/.claude/hooks/mirror-thread-to-company.sh"
+if [[ -f "$MIRROR_HOOK" ]]; then
+  jq -n --arg file_path "$HQ_ROOT/$THREAD_PATH" \
+    '{tool_name:"Write", tool_input:{file_path:$file_path}}' | \
+    bash "$MIRROR_HOOK" >/dev/null 2>&1 || true
+fi
+while IFS= read -r company; do
+  [[ -n "$company" ]] || continue
+  if [[ -f "companies/${company}/workspace/sessions/${THREAD_ID}.json" ]]; then
+    MIRRORED_COMPANIES+=("$company")
+    MIRROR_STAGE_PATHS+=(
+      "companies/${company}/workspace/index.jsonl"
+      "companies/${company}/workspace/.gitignore"
+    )
+  fi
+done < <(jq -r '.[]' <<<"$MIRROR_COMPANIES_JSON")
+MIRRORED_COMPANIES_JSON=$(printf '%s\n' "${MIRRORED_COMPANIES[@]:-}" | jq -R -s -c 'split("\n") | map(select(length > 0))')
+
+# Materialize NDJSON skips into a JSON array for --slurpfile (stdin only; no
+# growing argv). Empty NDJSON stays the [] written at init.
+if [[ -s "$SKIPPED_NDJSON_FILE" ]]; then
+  jq -s '.' "$SKIPPED_NDJSON_FILE" > "$SKIPPED_PATHS_FILE"
+fi
+
+jq -n \
+  --arg thread_id "$THREAD_ID" \
+  --arg thread_path "$THREAD_PATH" \
+  --arg ts "$TS" \
+  --arg title "$TITLE" \
+  --arg summary "$SUMMARY" \
+  --arg branch "$BRANCH" \
+  --arg started_commit "$START_COMMIT" \
+  --arg finalized_commit_note "The exact handoff commit is emitted by handoff-finalize.sh as commit_after_finalize; a file cannot contain the hash of the commit that contains itself." \
+  --slurpfile files_touched "$FILES_TOUCHED_FILE" \
+  --slurpfile staged_paths "$STAGED_PATHS_FILE" \
+  --slurpfile skipped_paths "$SKIPPED_PATHS_FILE" \
+  --slurpfile status_summary "$STATUS_SUMMARY_FILE" \
+  '{
+    thread_id: $thread_id,
+    thread_path: $thread_path,
+    created_at: $ts,
+    intent: { title: $title, summary: $summary },
+    git: {
+      branch: $branch,
+      started_commit: $started_commit,
+      finalized_commit: null,
+      finalized_commit_note: $finalized_commit_note
+    },
+    files_touched: ($files_touched[0] // []),
+    staged_paths: ($staged_paths[0] // []),
+    skipped_paths: ($skipped_paths[0] // []),
+    verification: { notes: [], upstream_refs_compared: [] },
+    status_summary: ($status_summary[0] // {})
+  }' > "$CHANGESET_PATH"
+
+# -------- handoff.json pointer --------
+# Keep the pointer readable as one complete file at all times. The temp is in
+# the destination directory so mv publishes it with a same-filesystem rename.
+# The pointer path is checkout-relative so the synced handoff stays portable.
+write_handoff_pointer() {
+  local destination="$1" thread_path="$2" destination_dir pointer_tmp
+  destination_dir="$(dirname "$destination")"
+  mkdir -p "$destination_dir"
+  pointer_tmp="$(mktemp "$destination_dir/.handoff-pointer.XXXXXX")"
+  FINALIZE_TMP_FILES+=("$pointer_tmp")
+  if ! jq -n --arg ts "$TS" --arg msg "$MESSAGE" --arg thread_id "$THREAD_ID" --arg thread_path "$thread_path" --arg summary "$SUMMARY" '{
+    created_at: $ts,
+    message: $msg,
+    last_thread: $thread_id,
+    thread_path: $thread_path,
+    context_notes: $summary
+  }' > "$pointer_tmp"; then
+    rm -f "$pointer_tmp"
+    return 1
+  fi
+  if ! mv -f "$pointer_tmp" "$destination"; then
+    rm -f "$pointer_tmp"
+    return 1
+  fi
+}
+
+copy_handoff_thread() {
+  local destination="$1" destination_dir thread_tmp
+  destination_dir="$(dirname "$destination")"
+  mkdir -p "$destination_dir"
+  thread_tmp="$(mktemp "$destination_dir/.handoff-thread.XXXXXX")"
+  FINALIZE_TMP_FILES+=("$thread_tmp")
+  if ! cp "$HQ_ROOT/$THREAD_PATH" "$thread_tmp"; then
+    rm -f "$thread_tmp"
+    return 1
+  fi
+  if ! mv -f "$thread_tmp" "$destination"; then
+    rm -f "$thread_tmp"
+    return 1
+  fi
+}
+
+write_handoff_pointer "workspace/threads/handoff.json" "$THREAD_PATH"
+if [[ "$HAS_GIT_CHECKOUT" == "true" ]]; then
+  case "$COMMON_GIT_DIR" in
+    /*|[A-Za-z]:/*) ;;
+    *) COMMON_GIT_DIR="$HQ_ROOT/$COMMON_GIT_DIR" ;;
+  esac
+  MAIN_CHECKOUT_ROOT="$(cd "$COMMON_GIT_DIR/.." && pwd -P)"
+  if [[ "$MAIN_CHECKOUT_ROOT" != "$HQ_ROOT" ]]; then
+    copy_handoff_thread "$MAIN_CHECKOUT_ROOT/$THREAD_PATH"
+    write_handoff_pointer "$MAIN_CHECKOUT_ROOT/workspace/threads/handoff.json" "$THREAD_PATH"
+  fi
+fi
+
+# -------- regen INDEX files via dedicated scripts --------
+# Inline INDEX regen replaced with delegations to reusable bash scripts.
+# Index regen is also callable independently (e.g. /cleanup --reindex,
+# handoff-post.sh). Zero Claude context either way.
+hq core rebuild-index threads --both >/dev/null 2>&1 || true
+hq core rebuild-index orchestrator >/dev/null 2>&1 || true
+
+# -------- INDEX.md top-level timestamp only --------
+if [[ -f INDEX.md ]]; then
+  # Bump 'Generated:' line in place if present, else skip
+  if grep -q '^Generated:' INDEX.md; then
+    tmpf=$(mktemp)
+    awk -v ts="$TS" '/^Generated:/ { print "Generated: " ts; next } { print }' INDEX.md > "$tmpf"
+    mv "$tmpf" INDEX.md
+  fi
+fi
+
+# -------- HQ commit (explicit paths only — never git add -A) --------
+# A failed commit must never ride inside a success payload. hq_committed alone
+# cannot say why it is false — "there was nothing to commit" and "git refused
+# the commit" are the same value — so hq_commit_status carries the reason and a
+# genuine failure also exits non-zero (4).
+HQ_COMMITTED="false"
+HQ_COMMIT_STATUS="nothing-to-commit"
+if [[ "$HAS_GIT_CHECKOUT" != "true" ]]; then
+  HQ_COMMIT_STATUS="no-git-checkout"
+fi
+HQ_COMMIT_ERROR=""
+EXPLICIT_PATHS=(
+  "${SAFE_STAGE_PATHS[@]:-}"
+  "${MIRROR_STAGE_PATHS[@]:-}"
+  "workspace/threads/${THREAD_ID}.json"
+  "workspace/threads/${THREAD_ID}.changeset.json"
+  "workspace/threads/handoff.json"
+  "workspace/threads/recent.md"
+  "workspace/threads/INDEX.md"
+  "workspace/orchestrator/INDEX.md"
+  "INDEX.md"
+)
+STAGED=0
+# Newline-separated, not an array: `${#arr[@]}` on an empty array is an unbound
+# variable under bash 3.2 + `set -u` (the same trap the SAFE_STAGE_PATHS
+# regression hit), and macOS still ships bash 3.2.
+STAGE_FAILURES=""
+STAGE_FAILURE_COUNT=0
+if [[ "$HAS_GIT_CHECKOUT" == "true" ]]; then
+  for p in "${EXPLICIT_PATHS[@]}"; do
+    [[ -n "$p" ]] || continue
+    if [[ -e "$p" || -n "$(git status --porcelain -- "$p" 2>/dev/null)" ]]; then
+      add_rc=0
+      git add -- "$p" >/dev/null 2>&1 || add_rc=$?
+      if [[ $add_rc -eq 0 ]]; then
+        STAGED=$((STAGED+1))
+      elif git ls-files --error-unmatch -- "$p" >/dev/null 2>&1; then
+        # The path is already TRACKED but a broad later ignore rule now shadows it
+        # (the scaffold's /workspace/ entry over the tracked handoff pointer/index
+        # files), so a plain `git add` refuses it. A tracked file must still be
+        # committed, so force-add it. Only a force-add that ALSO fails (e.g. a held
+        # .git/index.lock) is a genuine stage failure.
+        if git add -f -- "$p" >/dev/null 2>&1; then
+          STAGED=$((STAGED+1))
+        else
+          STAGE_FAILURES="${STAGE_FAILURES}${p}"$'\n'
+          STAGE_FAILURE_COUNT=$((STAGE_FAILURE_COUNT+1))
+        fi
+      elif git check-ignore --no-index -q -- "$p" 2>/dev/null; then
+        # An UNtracked, gitignored path is a deliberate exclusion, not a failed
+        # write. --no-index is required: plain `git check-ignore` SKIPS tracked
+        # files (it would wrongly report a tracked-but-ignored path as not-ignored,
+        # the bug that made this a stage-failure); the tracked case is handled above.
+        :
+      else
+        STAGE_FAILURES="${STAGE_FAILURES}${p}"$'\n'
+        STAGE_FAILURE_COUNT=$((STAGE_FAILURE_COUNT+1))
+      fi
+    fi
+  done
+fi
+# committed_paths scales with the staged set; capture it to a file (git piped to
+# jq via stdin, then the result written to disk) so it too stays off argv.
+new_tmp COMMITTED_PATHS_FILE
+printf '[]' > "$COMMITTED_PATHS_FILE"
+new_tmp STAGE_FAILURES_FILE
+printf '[]' > "$STAGE_FAILURES_FILE"
+if [[ -n "$STAGE_FAILURES" ]]; then
+  printf '%s' "$STAGE_FAILURES" \
+    | jq -R -s 'split("\n") | map(select(length > 0))' > "$STAGE_FAILURES_FILE"
+fi
+if [[ $STAGED -gt 0 ]] && [[ -n "$(git diff --cached --name-only 2>/dev/null)" ]]; then
+  # Snapshot the staged set separately. It only becomes committed_paths once the
+  # commit actually lands; a refused commit must not report paths as committed.
+  new_tmp PENDING_PATHS_FILE
+  git diff --cached --name-only | jq -R -s 'split("\n") | map(select(length > 0))' > "$PENDING_PATHS_FILE"
+  commit_out=""
+  commit_rc=0
+  commit_out="$(git commit -m "checkpoint: handoff ${THREAD_ID}" 2>&1)" || commit_rc=$?
+  if [[ $commit_rc -eq 0 ]]; then
+    HQ_COMMITTED="true"
+    HQ_COMMIT_STATUS="committed"
+    cat "$PENDING_PATHS_FILE" > "$COMMITTED_PATHS_FILE"
+  else
+    HQ_COMMIT_STATUS="failed"
+    HQ_COMMIT_ERROR="$(printf '%s' "$commit_out" | tr '\r\n' '  ' | sed 's/  */ /g; s/^ //; s/ $//' | cut -c1-500)"
+    [[ -n "$HQ_COMMIT_ERROR" ]] || HQ_COMMIT_ERROR="git commit exited ${commit_rc} with no output"
+  fi
+fi
+# A staging failure is just as fatal as a refused commit, and it is the shape a
+# held .git/index.lock actually takes: every `git add` fails, STAGED stays 0, no
+# commit is even attempted, and the run would otherwise look like the benign
+# "nothing to commit" case while the entire handoff sits uncommitted on disk.
+if [[ $STAGE_FAILURE_COUNT -gt 0 && "$HQ_COMMIT_STATUS" != "failed" ]]; then
+  HQ_COMMIT_STATUS="stage-failed"
+  if [[ -z "$HQ_COMMIT_ERROR" ]]; then
+    HQ_COMMIT_ERROR="git add failed for ${STAGE_FAILURE_COUNT} path(s) — see stage_failures"
+  fi
+fi
+COMMIT_AFTER=$(git rev-parse --short HEAD 2>/dev/null || echo "unknown")
+
+# -------- qmd reindex fire-and-forget (agent: skip; laptop: single-flight) --------
+# Agent boxes: managed timer owns indexing — handoff never kicks qmd.
+# Laptop: qmd-reindex-bg single-flight reindex. See qmd-reindex-bg.sh.
+# Helper is invoked synchronously: it is fail-soft and either prints
+# skipped-agent / skipped, or launches its own detached worker and prints a PID.
+# qmd_pid must never claim an agent reindex ran.
+QMD_PID=""
+# Prefer Core US-001 helper; fleet binary only if Core file is missing.
+_QMD_BG="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/qmd-reindex-bg.sh"
+if [[ ! -f "$_QMD_BG" ]] && [[ -x /usr/local/bin/hq-agent-qmd-reindex-bg ]]; then
+  _QMD_BG=/usr/local/bin/hq-agent-qmd-reindex-bg
+fi
+if [[ -x "$_QMD_BG" ]] || [[ -f "$_QMD_BG" ]]; then
+  # bash (not require +x) so a fresh checkout still routes through the helper.
+  QMD_PID="$(bash "$_QMD_BG" --log /tmp/qmd-handoff.log 2>/dev/null || true)"
+elif [[ -d /var/lib/hq-agent ]]; then
+  # Agent box without helper yet: still do not raw-embed.
+  QMD_PID="skipped-agent"
+fi
+
+# -------- copy next-step command to clipboard (fail-soft) --------
+[[ "$NEXT_COMMAND" == "__auto__" ]] && NEXT_COMMAND="/resumework ${THREAD_ID}"
+CLIPBOARD_COPIED="false"
+if [[ -n "$NEXT_COMMAND" ]]; then
+  if command -v pbcopy >/dev/null 2>&1; then
+    printf '%s' "$NEXT_COMMAND" | pbcopy 2>/dev/null && CLIPBOARD_COPIED="true"
+  elif command -v wl-copy >/dev/null 2>&1; then
+    printf '%s' "$NEXT_COMMAND" | wl-copy 2>/dev/null && CLIPBOARD_COPIED="true"
+  elif command -v xclip >/dev/null 2>&1; then
+    printf '%s' "$NEXT_COMMAND" | xclip -selection clipboard 2>/dev/null && CLIPBOARD_COPIED="true"
+  fi
+fi
+
+# -------- emit result --------
+jq -n \
+  --arg thread_id "$THREAD_ID" \
+  --arg thread_path "$THREAD_PATH" \
+  --arg handoff_path "workspace/threads/handoff.json" \
+  --argjson hq_committed "$HQ_COMMITTED" \
+  --argjson indexes_regen "true" \
+  --arg qmd_pid "${QMD_PID:-}" \
+  --arg git_bg_errors "$GIT_BG_ERRORS" \
+  --arg changeset_path "$CHANGESET_PATH" \
+  --arg hq_commit_status "$HQ_COMMIT_STATUS" \
+  --arg hq_commit_error "$HQ_COMMIT_ERROR" \
+  --slurpfile committed_paths "$COMMITTED_PATHS_FILE" \
+  --slurpfile stage_failures "$STAGE_FAILURES_FILE" \
+  --slurpfile skipped_paths "$SKIPPED_PATHS_FILE" \
+  --argjson baseline_noise_count "$BASELINE_NOISE_COUNT" \
+  --arg commit_after_finalize "$COMMIT_AFTER" \
+  --arg next_command "$NEXT_COMMAND" \
+  --argjson clipboard_copied "$CLIPBOARD_COPIED" \
+  --argjson mirror_companies "$MIRRORED_COMPANIES_JSON" \
+  '{
+    thread_id: $thread_id,
+    thread_path: $thread_path,
+    changeset_path: $changeset_path,
+    handoff_path: $handoff_path,
+    hq_committed: $hq_committed,
+    hq_commit_status: $hq_commit_status,
+    hq_commit_error: $hq_commit_error,
+    commit_after_finalize: $commit_after_finalize,
+    committed_paths: ($committed_paths[0] // []),
+    stage_failures: ($stage_failures[0] // []),
+    skipped_paths: ($skipped_paths[0] // []),
+    baseline_noise_count: $baseline_noise_count,
+    indexes_regen: $indexes_regen,
+    qmd_pid: $qmd_pid,
+    git_bg_errors: $git_bg_errors,
+    next_command: $next_command,
+    clipboard_copied: $clipboard_copied,
+    mirror_companies: $mirror_companies
+  }'
+
+# -------- fail loudly on a git write that did not land --------
+# The payload above is always emitted first: the caller still needs the thread
+# id and paths to recover. What changes is that a refused commit no longer
+# leaves the process looking successful.
+if [[ -n "$GIT_BG_ERRORS" ]]; then
+  echo "handoff-finalize: WARNING background git step reported errors: $GIT_BG_ERRORS" >&2
+fi
+if [[ $STAGE_FAILURE_COUNT -gt 0 ]]; then
+  echo "handoff-finalize: ERROR git add failed for ${STAGE_FAILURE_COUNT} path(s):" >&2
+  printf '%s' "$STAGE_FAILURES" | sed 's/^/handoff-finalize:   /' >&2
+fi
+case "$HQ_COMMIT_STATUS" in
+  failed|stage-failed)
+    echo "handoff-finalize: ERROR the HQ handoff commit FAILED — thread files were written but are NOT committed." >&2
+    echo "handoff-finalize: git said: $HQ_COMMIT_ERROR" >&2
+    echo "handoff-finalize: resolve the git error and re-run /handoff before ending the session." >&2
+    exit 4
+    ;;
+esac
+exit 0