@indigoai-us/hq-cli 5.314.0 → 5.316.0

package/assets/scaffold/core/scripts/handoff-open-steps.sh

@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+# hq-core: public
+# handoff-open-steps.sh — list and close next steps across handoff threads
+# (2026-09-07).
+#
+# Handoff threads record next_steps; since 2026-09-07 each carries an `id`
+# (`<thread_id>#<n>`) and a `status` (open|done|dropped). This script is the
+# closure side: /startwork and /resumework list what is still open instead of
+# re-copying it forward, and a session closes a step when it is actually done.
+#
+# Usage:
+#   handoff-open-steps.sh list [--limit N] [--company <slug>] [--json]
+#   handoff-open-steps.sh close <step-id> [--as done|dropped] [--note "<why>"]
+#   handoff-open-steps.sh reopen <step-id>
+#
+# Threads live in workspace/threads/T-*.json (and archive/**). Closing edits
+# the step in place inside its thread file (only `status`, `closed_at`,
+# `closed_by`, `note`) and bumps `updated_at`; nothing else in the thread is
+# touched. Legacy steps without an id are listed with a synthetic id and can be
+# closed the same way (the id is written on first close).
+set -uo pipefail
+HQ_ROOT="${HQ_ROOT:-${CLAUDE_PROJECT_DIR:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)}}"
+THREADS="$HQ_ROOT/workspace/threads"
+command -v jq >/dev/null 2>&1 || { echo "handoff-open-steps: jq required" >&2; exit 2; }
+CMD="${1:-list}"; shift || true
+
+thread_files() { # newest first, handoffs and checkpoints only
+  find "$THREADS" -name 'T-*.json' ! -name '*.changeset.json' ! -path '*/resume-locks/*' 2>/dev/null \
+    | while IFS= read -r f; do printf '%s\t%s\n' "$(stat -c %Y "$f" 2>/dev/null || stat -f %m "$f")" "$f"; done \
+    | sort -rn | cut -f2
+}
+normalize_thread() { # <file> -> ensure every step has id/status (in memory)
+  jq -c '.next_steps = ((.next_steps // []) | to_entries | map(.key as $k |
+      (if (.value|type)=="string" then {step:.value} else .value end)
+      | .id = (.id // (input_filename|split("/")|last|sub("\\.json$";"")) + "#" + (($k+1)|tostring))
+      | .status = (.status // "open")) | map(del(.key)))' "$1"
+}
+
+case "$CMD" in
+  list)
+    LIMIT=20; CO=""; JSON=0
+    while [ $# -gt 0 ]; do case "$1" in --limit) LIMIT="$2"; shift 2;; --company) CO="$2"; shift 2;; --json) JSON=1; shift;; *) shift;; esac; done
+    n=0; rows=""
+    while IFS= read -r f; do
+      [ -n "$f" ] || continue
+      [ "$n" -ge "$LIMIT" ] && break
+      n=$((n+1))
+      t="$(normalize_thread "$f" 2>/dev/null)" || continue
+      if [ -n "$CO" ]; then
+        printf '%s' "$t" | jq -e --arg co "$CO" '(.metadata.company // []) | index($co) != null' >/dev/null 2>&1 || continue
+      fi
+      rows="$rows$(printf '%s' "$t" | jq -c '{thread: .thread_id, title: (.metadata.title // ""), created: .created_at} as $h | .next_steps[] | select(.status == "open") | $h + {id, step}')
+"
+    done < <(thread_files)
+    if [ "$JSON" = 1 ]; then printf '%s' "$rows" | jq -s 'map(select(. != null))'; exit 0; fi
+    if [ -z "$(printf '%s' "$rows" | tr -d '[:space:]')" ]; then echo "No open handoff steps in the last $n thread(s)."; exit 0; fi
+    printf '%s' "$rows" | jq -r '"\(.id)  \(.step)  [\(.title)]"'
+    ;;
+  close|reopen)
+    ID="${1:-}"; shift || true
+    [ -n "$ID" ] || { echo "usage: $CMD <step-id>" >&2; exit 2; }
+    AS="done"; NOTE=""
+    while [ $# -gt 0 ]; do case "$1" in --as) AS="$2"; shift 2;; --note) NOTE="$2"; shift 2;; *) shift;; esac; done
+    [ "$CMD" = reopen ] && AS="open"
+    case "$AS" in done|dropped|open) ;; *) echo "--as must be done|dropped" >&2; exit 2;; esac
+    tid="${ID%%#*}"
+    f="$(find "$THREADS" -name "$tid.json" ! -path '*/resume-locks/*' 2>/dev/null | head -1)"
+    [ -n "$f" ] || { echo "handoff-open-steps: thread $tid not found under $THREADS" >&2; exit 3; }
+    now="$(date -u +%Y-%m-%dT%H:%M:%SZ)"; by="${HQ_SESSION_ID:-${CLAUDE_SESSION_ID:-unknown-session}}"
+    normalize_thread "$f" | jq --arg id "$ID" --arg as "$AS" --arg now "$now" --arg by "$by" --arg note "$NOTE" '
+      if ([.next_steps[] | select(.id == $id)] | length) == 0 then error("step \($id) not in thread") else . end
+      | .next_steps = (.next_steps | map(if .id == $id then
+          (if $as == "open" then del(.closed_at, .closed_by) | .status = "open"
+           else .status = $as | .closed_at = $now | .closed_by = $by | (if $note != "" then .note = $note else . end) end)
+        else . end))
+      | .updated_at = $now' > "$f.tmp" 2>"$f.err" || { cat "$f.err" >&2; rm -f "$f.tmp" "$f.err"; exit 3; }
+    rm -f "$f.err"; mv "$f.tmp" "$f"
+    echo "handoff-open-steps: $ID -> $AS"
+    ;;
+  *) sed -n 2,22p "$0"; exit 2 ;;
+esac

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

@@ -0,0 +1,252 @@
+#!/usr/bin/env bash
+# handoff-post.sh — detached post-handoff orchestrator.
+#
+# Runs AFTER handoff-finalize.sh emits handoff.json. Does the mechanical work
+# that used to burn foreground-session tokens:
+#   1. Archive old threads (60d), then regen thread INDEX.md + recent.md (bash)
+#   2. Regen orchestrator INDEX.md (bash)
+#   3. qmd reindex via qmd-reindex-bg.sh (single-flight; agent boxes skip)
+#
+# Model work is intentionally not launched from this detached shell. /learn and
+# /document-release follow-ups run from the handoff skill itself, so auth
+# failures cannot disappear into /tmp logs.
+#
+# Usage (called by handoff skill as `nohup handoff-post.sh ... &`):
+#   core/scripts/handoff-post.sh <thread_path> [learnings_json_file]
+
+set -euo pipefail
+
+HQ_ROOT="${HQ_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)}"
+cd "$HQ_ROOT"
+HANDOFF_SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$HANDOFF_SCRIPT_DIR/lib/session-id.sh"
+
+THREAD_PATH="${1:-}"
+LEARNINGS_FILE="${2:-}"
+
+LOG_DIR="${HANDOFF_LOG_DIR:-/tmp}"
+LOG_MAIN="${LOG_DIR}/handoff-post.log"
+LOG_QMD="${LOG_DIR}/qmd-handoff.log"
+
+TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+
+log() { echo "[${TS}] $*" >> "$LOG_MAIN"; }
+
+: > "$LOG_MAIN"
+log "handoff-post starting (thread=${THREAD_PATH:-none}, learnings=${LEARNINGS_FILE:-none})"
+
+# --- 1. Archive old threads (gated once per 24h) ---
+if hq core archive-old-threads --gated >>"$LOG_MAIN" 2>&1; then
+  log "archive: ok"
+else
+  log "archive: error (continuing)"
+fi
+
+# --- 2. Regen thread INDEX + recent (bash, no Claude) ---
+if hq core rebuild-index threads --both >>"$LOG_MAIN" 2>&1; then
+  log "threads-index: ok"
+else
+  log "threads-index: error (continuing)"
+fi
+
+# --- 3. Regen orchestrator INDEX (bash, no Claude) ---
+if hq core rebuild-index orchestrator >>"$LOG_MAIN" 2>&1; then
+  log "orchestrator-index: ok"
+else
+  log "orchestrator-index: error (continuing)"
+fi
+
+if [[ -n "$LEARNINGS_FILE" && -s "$LEARNINGS_FILE" ]]; then
+  learning_count=$(jq 'if type == "array" then length else 0 end' "$LEARNINGS_FILE" 2>/dev/null || echo 0)
+  if [[ "${learning_count:-0}" -gt 0 ]]; then
+    log "learn: eligible and pending runtime dispatch by handoff skill (${learning_count} learning(s); no dispatch proof)"
+  else
+    log "learn: no learnings to dispatch"
+  fi
+else
+  log "learn: no learnings file provided"
+fi
+
+if [[ -n "$THREAD_PATH" && -f "$THREAD_PATH" ]]; then
+  if scope_counts=$(jq -r '
+    (.files_touched // []) as $files
+    | (if ($files | type) == "array" then
+         [$files[] |
+           if type == "string" then .
+           elif type == "object" and (.path | type) == "string" then .path
+           else null
+           end]
+       else [] end) as $paths
+    | [
+        ($paths | map(select(if type == "string" then test("^(companies|repos)/") else false end)) | length),
+        ($paths | map(select(. == null)) | length)
+      ]
+    | @tsv
+  ' "$THREAD_PATH" 2>/dev/null); then
+    IFS=$'\t' read -r scope_match skipped_count <<< "$scope_counts"
+  else
+    scope_match=0
+    skipped_count=0
+    log "document-release: skipped (invalid thread JSON)"
+  fi
+  for ((skipped_index = 0; skipped_index < skipped_count; skipped_index++)); do
+    log "document-release: skipped unsupported files_touched entry"
+  done
+  if [[ "$scope_match" -gt 0 ]]; then
+    if bash "$HQ_ROOT/core/scripts/skill-installed.sh" document-release "${HQ_ACTIVE_COMPANY:-}" >/dev/null 2>>"$LOG_MAIN"; then
+      log "document-release: eligible and pending runtime dispatch by handoff skill ($scope_match scoped files; no dispatch proof)"
+    else
+      log "document-release: skipped (skill not installed)"
+    fi
+  else
+    log "document-release: skipped (no company/repo files in files_touched)"
+  fi
+else
+  log "document-release: skipped (no thread path)"
+fi
+
+# --- 3b. Push company handoff mirrors promptly (best effort) ---
+# Session snapshots are intentionally gitignored, so a completed mirror needs
+# the sync client to make the handoff available to a second device. Keep
+# finalizer company metadata and add the company bound to this session when no
+# changed path identified one; never use a device-wide active-company value.
+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"
+}
+
+if [[ -n "$THREAD_PATH" && -f "$THREAD_PATH" ]] && command -v hq >/dev/null 2>&1; then
+  if [[ "$THREAD_PATH" == /* ]]; then
+    THREAD_FILE="$THREAD_PATH"
+  else
+    THREAD_FILE="$HQ_ROOT/$THREAD_PATH"
+  fi
+  SYNC_COMPANIES_JSON="$(jq -c '
+    (.metadata.company // [])
+    | (if type == "array" then . else [.] end)
+    | map(select(type == "string" and test("^[a-z][a-z0-9_-]*$")))
+    | unique
+  ' "$THREAD_FILE" 2>/dev/null || printf '[]')"
+  BOUND_COMPANY="$(bound_session_company)"
+  if [[ -n "$BOUND_COMPANY" ]]; then
+    UPDATED_SYNC_COMPANIES_JSON="$(jq -c --arg company "$BOUND_COMPANY" '. + [$company] | unique' <<< "$SYNC_COMPANIES_JSON")"
+    if [[ "$SYNC_COMPANIES_JSON" != "$UPDATED_SYNC_COMPANIES_JSON" ]]; then
+      SYNC_COMPANIES_JSON="$UPDATED_SYNC_COMPANIES_JSON"
+      THREAD_TMP="$(mktemp "$HQ_ROOT/workspace/threads/.handoff-post-XXXXXX")"
+      if jq -c --argjson companies "$SYNC_COMPANIES_JSON" \
+        '.metadata = (.metadata // {}) | .metadata.company = $companies' \
+        "$THREAD_FILE" > "$THREAD_TMP" && mv "$THREAD_TMP" "$THREAD_FILE"; then
+        :
+      else
+        rm -f "$THREAD_TMP"
+        log "workspace-sync: skipped (could not add bound company to handoff thread)"
+        SYNC_COMPANIES_JSON='[]'
+      fi
+    else
+      SYNC_COMPANIES_JSON="$UPDATED_SYNC_COMPANIES_JSON"
+    fi
+  fi
+  THREAD_ID="$(jq -r '.thread_id // empty' "$THREAD_FILE" 2>/dev/null || true)"
+  THREAD_MIRRORABLE="false"
+  case "$THREAD_FILE" in
+    "$HQ_ROOT"/workspace/threads/T-*.json)
+      if [[ "$THREAD_ID" =~ ^T-[A-Za-z0-9._-]+$ ]]; then THREAD_MIRRORABLE="true"; fi
+      ;;
+  esac
+  if [[ "$THREAD_MIRRORABLE" == "true" && "$SYNC_COMPANIES_JSON" != '[]' ]]; then
+    MIRROR_HOOK="$HQ_ROOT/.claude/hooks/mirror-thread-to-company.sh"
+    if [[ -f "$MIRROR_HOOK" ]]; then
+      jq -n --arg file_path "$THREAD_FILE" \
+        '{tool_name:"Write",tool_input:{file_path:$file_path}}' | \
+        bash "$MIRROR_HOOK" >>"$LOG_MAIN" 2>&1 || \
+        log "workspace-sync: mirror hook failed for handoff thread"
+    else
+      log "workspace-sync: mirror hook unavailable for handoff thread"
+    fi
+  fi
+  while IFS= read -r company; do
+    [[ "$company" =~ ^[a-z][a-z0-9_-]*$ ]] || continue
+    [[ -d "$HQ_ROOT/companies/$company/workspace" ]] || continue
+    if [[ "$THREAD_MIRRORABLE" != "true" || \
+          ! -f "$HQ_ROOT/companies/$company/workspace/sessions/$THREAD_ID.json" ]]; then
+      log "workspace-sync: skipped (thread mirror missing for $company)"
+      continue
+    fi
+    if hq sync push --company "$company" "companies/$company/workspace" >>"$LOG_MAIN" 2>&1; then
+      log "workspace-sync: pushed companies/$company/workspace"
+    else
+      log "workspace-sync: failed companies/$company/workspace"
+    fi
+  done < <(jq -r '.[]' <<< "$SYNC_COMPANIES_JSON")
+elif [[ -n "$THREAD_PATH" && -f "$THREAD_PATH" ]]; then
+  log "workspace-sync: skipped (hq CLI unavailable)"
+fi
+
+# --- 4. qmd reindex (agent: skip; laptop: single-flight) ---
+# handoff-finalize may already have run the helper; agent boxes no-op
+# (skipped-agent). Never dual-nohup raw cleanup+update+embed on agents.
+# Never invoke managed index wrappers — handoff owns no agent freshness.
+# Prefer Core US-001 helper; fleet binary only if Core file is missing.
+# Lock acquisition runs BEFORE the US-010 session_end spawn so a detached
+# session-end hook cannot delay or interleave with finalize+post single-flight.
+_QMD_BG="$HQ_ROOT/core/scripts/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
+  _qmd_out="$(bash "$_QMD_BG" --log "$LOG_QMD" 2>/dev/null || true)"
+  # Empty stdout is busy/dedupe quiet — never claim "ok".
+  log "qmd: reindex-bg → ${_qmd_out:-busy-or-quiet}"
+elif [[ -d /var/lib/hq-agent ]]; then
+  log "qmd: skipped-agent (no helper; indexer owns freshness)"
+else
+  log "qmd: skipped (helper missing)"
+fi
+
+# --- 4b. Work Mesh Live: enqueue session_end (US-010) ---
+# Detached + non-blocking. Presence ends via spool; daemon flushes.
+# Same launch shape as the former work-mesh-close hook (nohup + disown).
+# Runs AFTER qmd reindex so this path cannot perturb single-flight lock
+# acquisition order or spawn count. Guarded: older checkouts skip quietly.
+WM_END_HOOK="$HQ_ROOT/core/hooks/SessionEnd/35-work-mesh-session-end.sh"
+if [[ -f "$WM_END_HOOK" ]]; then
+  sid=""
+  sid="$(session_id_resolve "$HQ_ROOT")"
+  if [[ -n "$sid" ]]; then
+    payload=$(printf '{"session_id":"%s"}' "$sid")
+  else
+    payload='{}'
+  fi
+  HQ_ROOT="$HQ_ROOT" CLAUDE_CODE_SESSION_ID="${sid:-}" \
+    nohup bash -c 'printf "%s\n" "$1" | bash "$2" SessionEnd' \
+    _ "$payload" "$WM_END_HOOK" \
+    >>"${LOG_DIR}/work-mesh-session-end.log" 2>&1 </dev/null &
+  disown 2>/dev/null || true
+  log "work-mesh-session-end: launched PID $!"
+else
+  log "work-mesh-session-end: skipped (hook absent)"
+fi
+
+# --- 5. Worktree GC (gated once-per-24h, detached, fully fail-soft) ---
+# HQ worktrees accumulate forever and can reach hundreds of GB. Opportunistically
+# GC the provably-safe stale ones on every handoff. --gated caps this to once per
+# 24h; --apply lets it actually remove (the script's own guards keep it to clean,
+# old, branch-preserved, unreferenced worktrees only). Launched DETACHED because
+# the safety check fetches from origin per repo — it must never block or fail the
+# handoff. Guarded so an older checkout without the script simply skips it.
+WT_GC="$HQ_ROOT/core/scripts/worktree-gc.sh"
+if [[ -f "$WT_GC" ]]; then
+  HQ_ROOT="$HQ_ROOT" nohup bash "$WT_GC" --apply --gated >>"${LOG_DIR}/worktree-gc.log" 2>&1 </dev/null &
+  disown 2>/dev/null || true
+  log "worktree-gc: launched PID $! (--apply --gated)"
+else
+  log "worktree-gc: skipped (script absent)"
+fi
+
+log "handoff-post complete"