@indigoai-us/hq-cli 5.314.0 → 5.315.0

package/assets/scaffold/core/scripts/resolve-company.sh

@@ -0,0 +1,199 @@
+#!/usr/bin/env bash
+# hq-core: public
+# resolve-company.sh — resolve the active company for skills and routing.
+#
+# Resolution order (first hit wins): explicit manifest slug in the prompt,
+# session company_slug, enabled device default, then none. Prompt matching is
+# whole-token only; free text never guesses a company.
+#
+# Output: {"company":"<slug>","source":"prompt|session|device_default|none"}
+# Always exits 0 and never writes state.
+
+set -uo pipefail
+
+ROOT=""
+PROMPT=""
+HAVE_PROMPT=0
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --root) ROOT="${2:-}"; shift 2 || shift ;;
+    --prompt) PROMPT="${2:-}"; HAVE_PROMPT=1; shift 2 || shift ;;
+    --help|-h)
+      sed -n '2,14p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'
+      exit 0
+      ;;
+    *) shift ;;
+  esac
+done
+
+if [ "$HAVE_PROMPT" -eq 0 ] && [ ! -t 0 ]; then
+  PROMPT="$(cat 2>/dev/null || true)"
+fi
+: "${PROMPT:=}"
+
+emit() {
+  printf '{"company":"%s","source":"%s"}\n' "$1" "$2"
+  exit 0
+}
+
+if [ -z "$ROOT" ]; then
+  ROOT="${HQ_ROOT:-${CLAUDE_PROJECT_DIR:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && cd .. && pwd)}}"
+fi
+
+MANIFEST="$ROOT/companies/manifest.yaml"
+[ -f "$MANIFEST" ] || emit "" "none"
+
+SLUGS="$(
+  awk '
+    function keep(slug) {
+      return slug != "" && slug != "_template" && slug != "companies" && slug != "unaffiliated_repos"
+    }
+    /^companies:[[:space:]]*$/ { wrapped = 1; next }
+    wrapped && /^[^[:space:]][^:]*:[[:space:]]*$/ { wrapped = 0 }
+    wrapped && /^  [A-Za-z][A-Za-z0-9_-]*:/ {
+      line = $0; sub(/^[[:space:]]+/, "", line); sub(/:.*/, "", line)
+      if (keep(line)) print line
+      next
+    }
+    !wrapped && /^[A-Za-z][A-Za-z0-9_-]*:/ {
+      line = $0; sub(/:.*/, "", line)
+      if (keep(line)) print line
+    }
+  ' "$MANIFEST" | sort -u
+)"
+[ -n "$SLUGS" ] || emit "" "none"
+
+is_known_slug() {
+  printf '%s\n' "$SLUGS" | grep -Fxq "$1"
+}
+
+prompt_slug() {
+  local normalized="" match=""
+  [ -n "$PROMPT" ] || return 0
+  normalized="$(printf '%s' "$PROMPT" | tr '[:upper:]' '[:lower:]' | tr -c 'a-z0-9_-' ' ')"
+  match="$(
+    # Prompt normalization is case-insensitive, but company IDs are not.
+    # Keep a folded match only when exactly one registered ID has that key.
+    # If IDs differ only by case, do not guess which tenant the prompt means.
+    printf '%s\n' "$SLUGS" | awk -v line="$normalized" '
+      BEGIN {
+        n = split(line, tok, /[ \t]+/)
+        for (i = 1; i <= n; i++) if (tok[i] != "" && !(tok[i] in pos)) pos[tok[i]] = i
+        bestSlug = ""; bestLen = 0; bestPos = 0
+      }
+      {
+        slug = $0
+        key = tolower(slug)
+        if (key in pos) {
+          matches[key]++
+          candidate[key] = slug
+        }
+      }
+      END {
+        for (key in matches) {
+          if (matches[key] != 1) continue
+          slug = candidate[key]
+          len = length(slug); p = pos[key]
+          if (len > bestLen || (len == bestLen && p < bestPos)) {
+            bestSlug = slug; bestLen = len; bestPos = p
+          }
+        }
+        if (bestSlug != "") print bestSlug
+      }
+    '
+  )"
+  printf '%s' "$match"
+}
+
+MATCH="$(prompt_slug)"
+[ -n "$MATCH" ] && emit "$MATCH" "prompt"
+
+SESSION_CO=""
+if [ -x "$ROOT/core/scripts/hq-session.sh" ]; then
+  SESSION_CO="$(bash "$ROOT/core/scripts/hq-session.sh" get company_slug 2>/dev/null || true)"
+  SESSION_CO="$(printf '%s' "$SESSION_CO" | tr -d '[:space:]\"')"
+fi
+if [ -n "$SESSION_CO" ] && is_known_slug "$SESSION_CO"; then
+  emit "$SESSION_CO" "session"
+fi
+
+is_fleet_identity() {
+  [ -n "${HQ_AGENT_WORKDIR:-}" ] && return 0
+  [ -n "${HQ_AGENT_COMPANY_DIR:-}" ] && return 0
+  [ -n "${HQ_AGENT_IDENTITY_FILE:-}" ] && return 0
+  [ -f /etc/hq-agent/identity.json ] && return 0
+  [ -f /etc/hq-agent/machine-creds.json ] && return 0
+  agent_root="${HQ_AGENT_ROOT_PREFIX:-}"
+  if [ -n "$agent_root" ]; then
+    [ -f "${agent_root%/}/var/lib/hq-agent/identity.json" ] && return 0
+  else
+    [ -f /var/lib/hq-agent/identity.json ] && return 0
+  fi
+  [ -f /var/lib/hq-agent/machine-creds.json ] && return 0
+  return 1
+}
+
+run_with_timeout() {
+  command -v node >/dev/null 2>&1 || return 127
+  node -e '
+const { spawn } = require("child_process");
+const command = process.argv[1];
+if (!command) process.exit(127);
+const child = spawn(command, process.argv.slice(2), { detached: true, stdio: ["ignore", "pipe", "ignore"] });
+let finished = false;
+const finish = (status) => {
+  if (finished) return;
+  finished = true;
+  clearTimeout(timer);
+  try { process.kill(-child.pid, "SIGTERM"); } catch (_) {}
+  process.exit(status);
+};
+child.stdout.on("data", (chunk) => process.stdout.write(chunk));
+child.once("error", () => finish(127));
+child.once("exit", (code) => finish(typeof code === "number" ? code : 1));
+const timer = setTimeout(() => finish(124), 2000);
+' "$@"
+}
+
+if ! is_fleet_identity && command -v hq >/dev/null 2>&1 && command -v jq >/dev/null 2>&1; then
+  DEFAULT_JSON="$(run_with_timeout hq mesh context default get --json 2>/dev/null || true)"
+  DEFAULT_SLUG="$(printf '%s' "$DEFAULT_JSON" | jq -er '(.defaultCompany // .) as $default | if $default.enabled == true and ($default.source // "") != "disabled" and ($default.needsChoice // false) == false and ($default.slug | type == "string") then $default.slug else empty end' 2>/dev/null || true)"
+  DEFAULT_SLUG="$(printf '%s' "$DEFAULT_SLUG" | tr -d '[:space:]\"')"
+  if [ -n "$DEFAULT_SLUG" ] && is_known_slug "$DEFAULT_SLUG"; then
+    # A device default is only a local preference. Reconcile performs the
+    # token-backed active-membership check; never promote this fallback when
+    # that preflight is unavailable, times out, or returns a noncanonical row.
+    PREFLIGHT_SESSION_ID="resolve-default-$$-$RANDOM"
+    PREFLIGHT_OPERATION_ID="resolve-default-op-$$-$RANDOM"
+    PREFLIGHT_OBSERVATION="$(jq -cn \
+      --arg session_id "$PREFLIGHT_SESSION_ID" \
+      --arg operation_id "$PREFLIGHT_OPERATION_ID" \
+      --arg root "$ROOT" \
+      '{contractVersion:1,clientOperationId:$operation_id,identity:{sessionId:$session_id,harness:"hq-core",adapterVersion:"1"},cwd:$root,hqRoot:$root}')"
+    PREFLIGHT_STATUS=0
+    PREFLIGHT_RESULT="$(run_with_timeout hq mesh context reconcile --observation-json "$PREFLIGHT_OBSERVATION" --machine --offline 2>/dev/null)" || PREFLIGHT_STATUS=$?
+    VALIDATED_SLUG=""
+    if [ "$PREFLIGHT_STATUS" -eq 0 ]; then
+      VALIDATED_SLUG="$(printf '%s' "$PREFLIGHT_RESULT" | jq -er \
+        --arg slug "$DEFAULT_SLUG" \
+        --arg session_id "$PREFLIGHT_SESSION_ID" \
+        --arg operation_id "$PREFLIGHT_OPERATION_ID" '
+          if type == "object"
+            and .contractVersion == 1
+            and (.sessionId | type == "string") and .sessionId == $session_id
+            and (.clientOperationId | type == "string") and .clientOperationId == $operation_id
+            and (.kind == "queued" or .kind == "needs_project" or .kind == "needs_task" or .kind == "bound")
+            and (.classification == "needs_project" or .classification == "needs_task" or .classification == "bound")
+            and (.delivery == "queued" or .delivery == "acked")
+            and .lifecycle == "open"
+            and .companySlug == $slug
+            and (.companyUid | type == "string") and (.companyUid | length > 0)
+          then .companySlug else empty end
+        ' 2>/dev/null || true)"
+    fi
+    [ "$VALIDATED_SLUG" = "$DEFAULT_SLUG" ] && emit "$DEFAULT_SLUG" "device_default"
+  fi
+fi
+
+emit "" "none"

package/assets/scaffold/core/scripts/resume-thread-lock.sh

@@ -0,0 +1,285 @@
+#!/usr/bin/env bash
+# hq-core: public
+# resume-thread-lock.sh — durable, session-attributed lock markers for
+# /resumework. Locks live outside individual thread JSON files so archival can
+# move a thread without orphaning or mutating its immutable handoff record.
+#
+# Usage:
+#   resume-thread-lock.sh inspect <thread-id>
+#   resume-thread-lock.sh acquire <thread-id> --session-id <session-id>
+#   resume-thread-lock.sh acquire <thread-id> --replace --expected-generation <generation> --session-id <session-id>
+#
+# inspect always exits zero and returns one JSON object with status unlocked,
+# locked, or stale. acquire exits 3 with that same locked/stale JSON when an
+# existing marker needs an explicit user confirmation; --replace is reserved
+# for the confirmed re-resume path.
+
+set -euo pipefail
+
+HQ_ROOT="${HQ_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)}"
+THREADS_DIR="$HQ_ROOT/workspace/threads"
+LOCKS_DIR="$THREADS_DIR/resume-locks"
+STALE_SECONDS="${HQ_RESUME_LOCK_STALE_SECONDS:-86400}"
+REPLACE_CLAIM_STALE_SECONDS="${HQ_RESUME_REPLACE_CLAIM_STALE_SECONDS:-60}"
+
+usage() {
+  cat <<'USAGE'
+usage:
+  resume-thread-lock.sh inspect <thread-id>
+  resume-thread-lock.sh acquire <thread-id> --session-id <session-id>
+  resume-thread-lock.sh acquire <thread-id> --replace --expected-generation <generation> --session-id <session-id>
+USAGE
+}
+
+fail_usage() {
+  echo "resume-thread-lock: $*" >&2
+  usage >&2
+  exit 2
+}
+
+command -v jq >/dev/null 2>&1 || {
+  echo "resume-thread-lock: jq is required" >&2
+  exit 1
+}
+
+[[ "$STALE_SECONDS" =~ ^[0-9]+$ ]] || fail_usage "HQ_RESUME_LOCK_STALE_SECONDS must be a non-negative integer"
+[[ "$REPLACE_CLAIM_STALE_SECONDS" =~ ^[0-9]+$ ]] || fail_usage "HQ_RESUME_REPLACE_CLAIM_STALE_SECONDS must be a non-negative integer"
+
+subcommand="${1:-}"
+shift || true
+
+thread_id="${1:-}"
+shift || true
+[[ "$thread_id" =~ ^T-[A-Za-z0-9][A-Za-z0-9_-]*$ ]] || fail_usage "thread id must be a canonical T-* id"
+
+replace="false"
+session_id=""
+expected_generation=""
+expected_generation_set="false"
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --replace)
+      replace="true"
+      shift
+      ;;
+    --session-id)
+      [[ $# -ge 2 ]] || fail_usage "--session-id requires a value"
+      session_id="$2"
+      shift 2
+      ;;
+    --expected-generation)
+      [[ $# -ge 2 ]] || fail_usage "--expected-generation requires a value"
+      expected_generation="$2"
+      expected_generation_set="true"
+      shift 2
+      ;;
+    *)
+      fail_usage "unknown argument: $1"
+      ;;
+  esac
+done
+
+case "$subcommand" in
+  inspect)
+    [[ "$replace" = "false" && -z "$session_id" ]] \
+      || fail_usage "inspect takes only a thread id"
+    ;;
+  acquire)
+    [[ -n "$session_id" ]] || fail_usage "acquire requires --session-id"
+    if [[ "$replace" = "true" ]]; then
+      [[ "$expected_generation_set" = "true" ]] || fail_usage "--replace requires --expected-generation from the inspected lock"
+    else
+      [[ "$expected_generation_set" = "false" ]] || fail_usage "--expected-generation is only valid with --replace"
+    fi
+    ;;
+  *)
+    fail_usage "expected inspect or acquire"
+    ;;
+esac
+
+lock_dir="$LOCKS_DIR/$thread_id.lock"
+record_path="$lock_dir/current.json"
+replace_claim_dir="$lock_dir/.replace-claim"
+relative_lock_path="workspace/threads/resume-locks/$thread_id.lock"
+
+now_epoch() {
+  date -u +%s
+}
+
+now_iso() {
+  date -u +%Y-%m-%dT%H:%M:%SZ
+}
+
+claim_is_stale() {
+  local claim_mtime current_epoch
+  claim_mtime="$(stat -f %m "$replace_claim_dir" 2>/dev/null || stat -c %Y "$replace_claim_dir" 2>/dev/null || echo 0)"
+  [[ "$claim_mtime" =~ ^[0-9]+$ ]] || return 1
+  current_epoch="$(now_epoch)"
+  (( current_epoch - claim_mtime > REPLACE_CLAIM_STALE_SECONDS ))
+}
+
+acquire_replace_claim() {
+  if mkdir "$replace_claim_dir" 2>/dev/null; then
+    return 0
+  fi
+
+  # A killed process can leave an empty claim directory behind. Recover only a
+  # demonstrably stale claim, and only with rmdir so an unexpected payload is
+  # never removed.
+  if [[ -d "$replace_claim_dir" ]] && claim_is_stale; then
+    rmdir "$replace_claim_dir" 2>/dev/null || true
+    mkdir "$replace_claim_dir" 2>/dev/null && return 0
+  fi
+
+  return 1
+}
+
+emit_unlocked() {
+  jq -cn \
+    --arg thread_id "$thread_id" \
+    --arg lock_path "$relative_lock_path" \
+    '{status:"unlocked", thread_id:$thread_id, lock_path:$lock_path}'
+}
+
+emit_stale() {
+  local reason="$1" owner_session="$2" resumed_at="$3" generation="$4"
+  local prompt="This thread was already resumed by ${owner_session} at ${resumed_at}. Its lock is stale (${reason}). Re-resume anyway?"
+  jq -cn \
+    --arg thread_id "$thread_id" \
+    --arg lock_path "$relative_lock_path" \
+    --arg stale_reason "$reason" \
+    --arg session_id "$owner_session" \
+    --arg resumed_at "$resumed_at" \
+    --arg lock_generation "$generation" \
+    --arg prompt "$prompt" \
+    '{status:"stale", thread_id:$thread_id, lock_path:$lock_path, stale_reason:$stale_reason, session_id:$session_id, resumed_at:$resumed_at, lock_generation:$lock_generation, prompt:$prompt}'
+}
+
+emit_locked() {
+  local owner_session="$1" resumed_at="$2" generation="$3"
+  local prompt="This thread was already resumed by ${owner_session} at ${resumed_at}. Re-resume anyway?"
+  jq -cn \
+    --arg thread_id "$thread_id" \
+    --arg lock_path "$relative_lock_path" \
+    --arg session_id "$owner_session" \
+    --arg resumed_at "$resumed_at" \
+    --arg lock_generation "$generation" \
+    --arg prompt "$prompt" \
+    '{status:"locked", thread_id:$thread_id, lock_path:$lock_path, session_id:$session_id, resumed_at:$resumed_at, lock_generation:$lock_generation, prompt:$prompt}'
+}
+
+# Print the existing lock's state. A damaged or expired marker is deliberately
+# not removed: it is still evidence that this handoff was resumed and must pass
+# through the same explicit re-resume confirmation as a fresh marker.
+existing_state() {
+  if [[ ! -d "$lock_dir" ]]; then
+    if [[ -e "$lock_dir" ]]; then
+      emit_stale "invalid-lock-path" "unknown session" "unknown time" ""
+    else
+      emit_unlocked
+    fi
+    return
+  fi
+
+  if [[ ! -f "$record_path" ]]; then
+    emit_stale "missing-record" "unknown session" "unknown time" ""
+    return
+  fi
+
+  if ! jq -e '
+    .version == 1
+    and (.thread_id | type == "string" and length > 0)
+    and (.session_id | type == "string" and length > 0)
+    and (.resumed_at | type == "string" and length > 0)
+    and (.resumed_epoch | type == "number")
+    and (.generation | type == "string" and length > 0)
+  ' "$record_path" >/dev/null 2>&1; then
+    emit_stale "invalid-record" "unknown session" "unknown time" ""
+    return
+  fi
+
+  local record_thread record_session record_at record_epoch record_generation current_epoch
+  record_thread="$(jq -r '.thread_id' "$record_path")"
+  record_session="$(jq -r '.session_id' "$record_path")"
+  record_at="$(jq -r '.resumed_at' "$record_path")"
+  record_epoch="$(jq -r '.resumed_epoch' "$record_path")"
+  record_generation="$(jq -r '.generation' "$record_path")"
+
+  if [[ "$record_thread" != "$thread_id" || ! "$record_epoch" =~ ^[0-9]+$ ]]; then
+    emit_stale "invalid-record" "$record_session" "$record_at" "$record_generation"
+    return
+  fi
+
+  current_epoch="$(now_epoch)"
+  if (( current_epoch - record_epoch > STALE_SECONDS )); then
+    emit_stale "expired" "$record_session" "$record_at" "$record_generation"
+    return
+  fi
+
+  emit_locked "$record_session" "$record_at" "$record_generation"
+}
+
+write_record() {
+  local record_dir="$1" epoch timestamp tmp generation
+  epoch="$(now_epoch)"
+  timestamp="$(now_iso)"
+  tmp="$(mktemp "$record_dir/.current.XXXXXX")"
+  generation="$(basename "$tmp")"
+  jq -cn \
+    --arg thread_id "$thread_id" \
+    --arg session_id "$session_id" \
+    --arg resumed_at "$timestamp" \
+    --arg generation "$generation" \
+    --argjson resumed_epoch "$epoch" \
+    '{version:1, thread_id:$thread_id, session_id:$session_id, resumed_at:$resumed_at, resumed_epoch:$resumed_epoch, generation:$generation}' \
+    > "$tmp"
+  mv -f "$tmp" "$record_path"
+  WRITTEN_GENERATION="$generation"
+}
+
+emit_acquired() {
+  local generation="$1"
+  jq -cn \
+    --arg thread_id "$thread_id" \
+    --arg lock_path "$relative_lock_path" \
+    --arg session_id "$session_id" \
+    --arg lock_generation "$generation" \
+    '{status:"acquired", thread_id:$thread_id, lock_path:$lock_path, session_id:$session_id, lock_generation:$lock_generation}'
+}
+
+case "$subcommand" in
+  inspect)
+    existing_state
+    ;;
+  acquire)
+    mkdir -p "$LOCKS_DIR"
+    if mkdir "$lock_dir" 2>/dev/null; then
+      write_record "$lock_dir"
+      emit_acquired "$WRITTEN_GENERATION"
+      exit 0
+    fi
+
+    if [[ "$replace" != "true" ]]; then
+      existing_state
+      exit 3
+    fi
+
+    [[ -d "$lock_dir" ]] || {
+      echo "resume-thread-lock: cannot refresh non-directory lock path: $relative_lock_path" >&2
+      exit 1
+    }
+    if ! acquire_replace_claim; then
+      existing_state
+      exit 4
+    fi
+    trap 'rmdir "$replace_claim_dir" 2>/dev/null || true' EXIT
+    current_state="$(existing_state)"
+    current_generation="$(jq -r '.lock_generation // ""' <<<"$current_state")"
+    if [[ "$current_generation" != "$expected_generation" ]]; then
+      printf '%s\n' "$current_state"
+      exit 4
+    fi
+    write_record "$lock_dir"
+    emit_acquired "$WRITTEN_GENERATION"
+    ;;
+esac

package/assets/scaffold/core/scripts/source-yaml-validate.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+# source-yaml-validate.sh — validate a sources/{channel}/source.yaml.
+# Spec: core/knowledge/public/hq-core/source-yaml-spec.md
+# Usage: source-yaml-validate.sh <path/to/source.yaml>
+# Exit 0 valid; 1 invalid (each violation printed); 2 bad usage / missing file.
+set -uo pipefail
+f="${1:-}"
+[ -n "$f" ] || { echo "usage: source-yaml-validate.sh <source.yaml>" >&2; exit 2; }
+[ -f "$f" ] || { echo "source-yaml-validate: no such file $f" >&2; exit 2; }
+
+get() {
+  awk -v k="$1" '$0 ~ "^"k":" { sub("^"k":[[:space:]]*", ""); sub("[[:space:]]+#.*$", ""); gsub(/^["\x27]|["\x27]$/, ""); print; exit }' "$f"
+}
+v=0
+bad() { echo "$f: $*"; v=$((v+1)); }
+oneof() { case " $3 " in *" $2 "*) ;; *) bad "$1 must be one of: $3 (got '${2:-<missing>}')" ;; esac; }
+
+channel="$(get channel)"; kind="$(get kind)"; arrives="$(get arrives)"; pull="$(get pull_command)"
+aud="$(get audience_rule)"; proc="$(get processor)"; run="$(get run)"; sched="$(get schedule)"
+
+[ -n "$channel" ] || bad "channel is required"
+folder="$(basename "$(dirname "$f")")"
+[ -z "$channel" ] || [ "$channel" = "$folder" ] || bad "channel '$channel' must equal its folder name '$folder'"
+oneof kind "$kind" "meeting email slack doc custom"
+oneof arrives "$arrives" "drop pull cloud"
+[ "$arrives" != pull ] || [ -n "$pull" ] || bad "pull_command is required when arrives: pull"
+[ -n "$aud" ] || bad "audience_rule is required (attendees|thread|channel|company|explicit); it is never defaulted"
+[ -z "$aud" ] || oneof audience_rule "$aud" "attendees thread channel company explicit"
+[ -n "$proc" ] || bad "processor is required (<worker>/<skill>)"
+[ -z "$proc" ] || printf '%s' "$proc" | grep -Eq '^[a-z0-9-]+/[a-z0-9-]+$' || bad "processor must look like <worker>/<skill> (got '$proc')"
+oneof run "$run" "local cloud"
+if [ -z "$sched" ]; then bad "schedule is required (cron or on-close)"
+elif [ "$sched" != on-close ] && [ "$(printf '%s' "$sched" | awk '{print NF}')" -ne 5 ]; then bad "schedule must be a 5-field cron or on-close (got '$sched')"; fi
+
+[ "$v" -eq 0 ] && { echo "$f: ok"; exit 0; }
+exit 1