@indigoai-us/hq-cli 5.312.2-beta.0 → 5.314.0

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

@@ -1,688 +0,0 @@
-#!/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)"
-HANDOFF_SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-source "$HANDOFF_SCRIPT_DIR/lib/session-id.sh"
-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 '[]')
-
-bound_session_company() {
-  local session_id metadata company
-  session_id="$(session_id_resolve "$HQ_ROOT")"
-  [[ -n "$session_id" ]] || return 0
-  metadata="$HQ_ROOT/workspace/sessions/$session_id/meta.yaml"
-  [[ -r "$metadata" ]] || return 0
-  company="$(awk '$1 == "company_slug:" { sub(/^[^:]+:[[:space:]]*/, ""); gsub(/^"|"$/, ""); print; exit }' "$metadata" 2>/dev/null || true)"
-  [[ "$company" =~ ^[a-z][a-z0-9_-]*$ ]] || return 0
-  printf '%s' "$company"
-}
-
-BOUND_SESSION_COMPANY="$(bound_session_company)"
-if [[ -n "$BOUND_SESSION_COMPANY" && -d "companies/$BOUND_SESSION_COMPANY" ]]; then
-  MIRROR_COMPANIES_JSON="$(jq -c --arg company "$BOUND_SESSION_COMPANY" '. + [$company] | unique' <<< "$MIRROR_COMPANIES_JSON")"
-fi
-
-# -------- 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