@indigoai-us/hq-cli 5.289.0 → 5.290.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,187 @@
+#!/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"
+
+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. Trust only
+# the finalizer's lowercase company-slug metadata before constructing a path.
+if [[ -n "$THREAD_PATH" && -f "$THREAD_PATH" ]] && command -v hq >/dev/null 2>&1; then
+  while IFS= read -r company; do
+    [[ "$company" =~ ^[a-z][a-z0-9_-]*$ ]] || continue
+    [[ -d "$HQ_ROOT/companies/$company/workspace" ]] || continue
+    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 '.metadata.company // empty | if type == "array" then .[] else . end' "$THREAD_PATH" 2>/dev/null || true)
+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=""
+  if [[ -f "$HQ_ROOT/workspace/sessions/.current" ]]; then
+    sid="$(tr -d '[:space:]' <"$HQ_ROOT/workspace/sessions/.current" 2>/dev/null || true)"
+  fi
+  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"

package/assets/scaffold/core/scripts/qmd-reindex-bg.sh

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+# FORWARDER — the implementation of this script now lives in the hq CLI.
+#
+# It runs as `hq index background`. This file stays behind so every existing
+# caller — skills, other scripts, CI, and muscle memory — keeps working against
+# the path it already knows.
+#
+# Why the implementation moved: the single-flight background reindex is a
+# durable state machine (lock ownership, stale reclaim, completion stamps,
+# signal cleanup) that belongs in tested code rather than 700 lines of shell.
+#
+# Equivalence is not assumed. hq-cli's e2e/qmd-background-differential.test.ts
+# runs a byte-frozen copy of this script's pre-migration source against the CLI
+# over identical injected worlds and compares exit status, stdout, the qmd argv
+# sequence, and the resulting lock/stamp state: agent short-circuit before any
+# qmd lookup or lock, empty-HOME silence, cleanup->update->embed ordering with a
+# completion stamp, no stamp after a failed update, and no competing writer
+# behind a held lock.
+#
+# ONE INTENDED DIVERGENCE: this script printed "skipped" when no qmd was on
+# PATH. The CLI bundles qmd (@tobilu/qmd is a dependency, resolved via
+# node_modules/.bin since hq-cli 5.94.1), so it proceeds instead of skipping.
+# That is the point of bundling; see hq-cli#333.
+#
+# The ABI is otherwise preserved: arguments are forwarded unchanged, stdin is
+# never read by this file, stdout and stderr are inherited untouched, and the
+# child replaces this process so its exit code and signal disposition become the
+# caller's.
+
+set -euo pipefail
+
+HQ_ROOT="${HQ_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)}"
+
+if ! command -v hq >/dev/null 2>&1; then
+  echo "qmd-reindex-bg.sh: requires the hq CLI — this script's implementation now ships with it." >&2
+  echo "Install it with: npm install -g @indigoai-us/hq-cli" >&2
+  exit 127
+fi
+
+exec hq index background --hq-root "$HQ_ROOT" "$@"

package/dist/command-catalog.generated.d.ts

@@ -5208,6 +5208,9 @@ export declare const COMMAND_CATALOG: readonly [{
             }, {
                 readonly flags: "--only <file>";
                 readonly description: "handle only the copy -> original pairs listed in this JSON file";
+            }, {
+                readonly flags: "--rewrite-refs";
+                readonly description: "also re-point signal refs, invoice, source and knowledge links to the survivor and carry external ids and web domains (checkpoint.ontology.merge-rewrite-refs)";
             }, {
                 readonly flags: "--json";
                 readonly description: "print JSON";
@@ -5402,6 +5405,54 @@ export declare const COMMAND_CATALOG: readonly [{
             readonly options: readonly [];
             readonly subcommands: readonly [];
         }];
+    }, {
+        readonly name: "handoff";
+        readonly description: "Handoff session helpers";
+        readonly aliases: readonly [];
+        readonly hidden: false;
+        readonly usage: "[options] [command]";
+        readonly arguments: readonly [];
+        readonly options: readonly [];
+        readonly subcommands: readonly [{
+            readonly name: "finalize";
+            readonly description: "Write and commit the current session handoff";
+            readonly aliases: readonly [];
+            readonly hidden: false;
+            readonly usage: "[args...]";
+            readonly arguments: readonly [{
+                readonly name: "args";
+                readonly required: false;
+                readonly variadic: true;
+            }];
+            readonly options: readonly [];
+            readonly subcommands: readonly [];
+        }, {
+            readonly name: "post";
+            readonly description: "Run best-effort post-handoff maintenance";
+            readonly aliases: readonly [];
+            readonly hidden: false;
+            readonly usage: "[args...]";
+            readonly arguments: readonly [{
+                readonly name: "args";
+                readonly required: false;
+                readonly variadic: true;
+            }];
+            readonly options: readonly [];
+            readonly subcommands: readonly [];
+        }, {
+            readonly name: "open-steps";
+            readonly description: "List and update open handoff steps";
+            readonly aliases: readonly [];
+            readonly hidden: false;
+            readonly usage: "[args...]";
+            readonly arguments: readonly [{
+                readonly name: "args";
+                readonly required: false;
+                readonly variadic: true;
+            }];
+            readonly options: readonly [];
+            readonly subcommands: readonly [];
+        }];
     }, {
         readonly name: "knowledge-prefs";
         readonly description: "Resolve a company knowledge-store preference";

package/dist/command-catalog.generated.js

@@ -6734,6 +6734,10 @@ export const COMMAND_CATALOG = [
                                 "flags": "--only <file>",
                                 "description": "handle only the copy -> original pairs listed in this JSON file"
                             },
+                            {
+                                "flags": "--rewrite-refs",
+                                "description": "also re-point signal refs, invoice, source and knowledge links to the survivor and carry external ids and web domains (checkpoint.ontology.merge-rewrite-refs)"
+                            },
                             {
                                 "flags": "--json",
                                 "description": "print JSON"
@@ -6976,6 +6980,65 @@ export const COMMAND_CATALOG = [
                     }
                 ]
             },
+            {
+                "name": "handoff",
+                "description": "Handoff session helpers",
+                "aliases": [],
+                "hidden": false,
+                "usage": "[options] [command]",
+                "arguments": [],
+                "options": [],
+                "subcommands": [
+                    {
+                        "name": "finalize",
+                        "description": "Write and commit the current session handoff",
+                        "aliases": [],
+                        "hidden": false,
+                        "usage": "[args...]",
+                        "arguments": [
+                            {
+                                "name": "args",
+                                "required": false,
+                                "variadic": true
+                            }
+                        ],
+                        "options": [],
+                        "subcommands": []
+                    },
+                    {
+                        "name": "post",
+                        "description": "Run best-effort post-handoff maintenance",
+                        "aliases": [],
+                        "hidden": false,
+                        "usage": "[args...]",
+                        "arguments": [
+                            {
+                                "name": "args",
+                                "required": false,
+                                "variadic": true
+                            }
+                        ],
+                        "options": [],
+                        "subcommands": []
+                    },
+                    {
+                        "name": "open-steps",
+                        "description": "List and update open handoff steps",
+                        "aliases": [],
+                        "hidden": false,
+                        "usage": "[args...]",
+                        "arguments": [
+                            {
+                                "name": "args",
+                                "required": false,
+                                "variadic": true
+                            }
+                        ],
+                        "options": [],
+                        "subcommands": []
+                    }
+                ]
+            },
             {
                 "name": "knowledge-prefs",
                 "description": "Resolve a company knowledge-store preference",

package/dist/commands/core-handoff.d.ts

@@ -0,0 +1,22 @@
+/** Native implementations of the handoff scaffold command family. */
+import { Command } from "commander";
+type RunResult = {
+    code: number;
+    stdout: string;
+    stderr: string;
+};
+type HandoffContext = {
+    root: string;
+    cwd: string;
+    now?: () => Date;
+    /** Test-only override for the finalizer's historical fixed /tmp paths. */
+    tmpDir?: string;
+};
+export declare function runHandoffOpenSteps(args: string[], context: HandoffContext): RunResult;
+export declare function runHandoffFinalize(args: string[], context: HandoffContext): RunResult;
+export declare function runHandoffPost(args: string[], context: HandoffContext): RunResult | Promise<RunResult>;
+export declare function runHandoffPostWorker(args: string[], context: HandoffContext): RunResult;
+/** Register native handoff commands behind the shared default-off flag. */
+export declare function registerCoreHandoffCommand(core: Command): void;
+export {};
+//# sourceMappingURL=core-handoff.d.ts.map