@indigoai-us/hq-cli 5.314.0 → 5.315.0

package/assets/scaffold/core/scripts/hq-pin.sh

@@ -0,0 +1,118 @@
+#!/usr/bin/env bash
+# hq-pin.sh — anchor the current session to one goal (the "pin").
+#
+# A pin is the message, goal, or target the session keeps working toward
+# across loops, wakeups, compactions, and hand-offs. It is stored per session
+# and re-read at every checkpoint so the session cannot drift.
+#
+# Usage:
+#   core/scripts/hq-pin.sh set  "<goal>" [--done "<criterion>"]... [--owner <name>] [--channel <dm-channel>]
+#   core/scripts/hq-pin.sh show                # print the pin (goal, done criteria, owner, channel, set-at)
+#   core/scripts/hq-pin.sh check               # print a one-line reminder for loop ticks; exit 3 if no pin
+#   core/scripts/hq-pin.sh note "<progress>"   # append a dated progress line under the pin
+#   core/scripts/hq-pin.sh clear               # remove the pin (the goal is met or withdrawn)
+#
+# Storage: workspace/sessions/<sid>/pin.md plus `pin: <goal>` in the session's
+# meta.yaml (via hq-session.sh) so other tooling can see it.
+set -euo pipefail
+
+HQ_ROOT="${HQ_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)}"
+SESSION_SH="$HQ_ROOT/core/scripts/hq-session.sh"
+
+die() { echo "hq-pin: $*" >&2; exit 2; }
+
+session_id() { bash "$SESSION_SH" current 2>/dev/null || true; }
+pin_file() {
+  local sid; sid="$(session_id)"
+  [ -n "$sid" ] || die "no current session (hq-session.sh current is empty)"
+  local d="$HQ_ROOT/workspace/sessions/$sid"; mkdir -p "$d"; echo "$d/pin.md"
+}
+
+cmd_set() {
+  local goal="${1:-}"; [ -n "$goal" ] || die "set needs the goal text"; shift
+  local owner="" channel=""; local -a done=()
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --done)    done+=("$2"); shift 2 ;;
+      --owner)   owner="$2"; shift 2 ;;
+      --channel) channel="$2"; shift 2 ;;
+      *) die "set: unknown arg $1" ;;
+    esac
+  done
+  local f; f="$(pin_file)"
+  {
+    echo "# Pin"
+    echo
+    echo "Goal: $goal"
+    echo
+    echo "Set: $(date -u +%Y-%m-%dT%H:%M:%SZ)"
+    [ -n "$owner" ]   && echo "Owner: $owner"
+    [ -n "$channel" ] && echo "Channel: $channel"
+    if [ ${#done[@]} -gt 0 ]; then
+      echo
+      echo "## Done when"
+      for c in "${done[@]}"; do echo "- [ ] $c"; done
+    fi
+    echo
+    echo "## Progress"
+  } > "$f"
+  bash "$SESSION_SH" set pin "$goal" >/dev/null
+  echo "pinned session $(session_id): $goal"
+}
+
+cmd_show() {
+  local f; f="$(pin_file)"
+  [ -f "$f" ] || { echo "no pin for session $(session_id)"; return 3; }
+  cat "$f"
+}
+
+cmd_check() {
+  local f; f="$(pin_file)"
+  [ -f "$f" ] || { echo "no pin"; return 3; }
+  local goal; goal="$(sed -n 's/^Goal: //p' "$f" | head -1)"
+  local open; open="$(grep -c '^- \[ \]' "$f" 2>/dev/null || true)"
+  local closed; closed="$(grep -c '^- \[x\]' "$f" 2>/dev/null || true)"
+  echo "PIN: $goal (done criteria: ${closed:-0} met, ${open:-0} open)"
+}
+
+cmd_note() {
+  local text="${1:-}"; [ -n "$text" ] || die "note needs text"
+  local f; f="$(pin_file)"
+  [ -f "$f" ] || die "no pin to note against"
+  printf -- '- %s %s\n' "$(date -u +%H:%MZ)" "$text" >> "$f"
+  echo "noted"
+}
+
+cmd_done() {
+  # Mark a done-criterion met by substring match.
+  local needle="${1:-}"; [ -n "$needle" ] || die "done needs a criterion substring"
+  local f; f="$(pin_file)"
+  [ -f "$f" ] || die "no pin"
+  local tmp; tmp="$(mktemp)"
+  local hit=0
+  while IFS= read -r line; do
+    case "$line" in
+      "- [ ] "*"$needle"*) echo "- [x] ${line#- [ ] }"; hit=1 ;;
+      *) echo "$line" ;;
+    esac
+  done < "$f" > "$tmp"
+  mv "$tmp" "$f"
+  [ "$hit" = 1 ] && echo "marked done: $needle" || die "no open criterion matches: $needle"
+}
+
+cmd_clear() {
+  local f; f="$(pin_file)"
+  rm -f "$f"
+  bash "$SESSION_SH" set pin "" >/dev/null
+  echo "pin cleared"
+}
+
+case "${1:-}" in
+  set)   shift; cmd_set "$@" ;;
+  show)  cmd_show ;;
+  check) cmd_check ;;
+  note)  shift; cmd_note "$@" ;;
+  done)  shift; cmd_done "$@" ;;
+  clear) cmd_clear ;;
+  *) sed -n '2,15p' "$0"; exit 2 ;;
+esac

package/assets/scaffold/core/scripts/hq-session.sh

@@ -27,6 +27,46 @@
 
 set -euo pipefail
 
+# Prefer the CLI-hosted implementation only when it advertises the exact-company
+# directory check. Older CLI bundles may recognize hq-session but still accept
+# case aliases, so they must use this in-tree implementation instead.
+# HQ_HQ_SESSION_NO_CLI=1 forces the in-tree path.
+if [ "${HQ_HQ_SESSION_NO_CLI:-}" != "1" ]; then
+  __hs_hq="$(command -v hq 2>/dev/null || true)"
+  if [ -n "$__hs_hq" ]; then
+    # `hq core --help` costs seconds of node startup, so probe it at most once
+    # per CLI build and cache the answer. Key by resolved path + mtime + size so
+    # a PATH switch or same-second rebuild cannot reuse a stale result; keep the
+    # cache in a private 0700 dir and trust it only when we own it; never persist
+    # a failed probe. HQ_CLI_CAPS_CACHE overrides the path (tests isolate it).
+    __hs_mt="$(stat -c %Y "$__hs_hq" 2>/dev/null || stat -f %m "$__hs_hq" 2>/dev/null || echo 0)"
+    __hs_sz="$(stat -c %s "$__hs_hq" 2>/dev/null || stat -f %z "$__hs_hq" 2>/dev/null || echo 0)"
+    __hs_key="$(printf '%s' "$__hs_hq:$__hs_mt:$__hs_sz" | cksum 2>/dev/null | cut -d' ' -f1)"
+    if [ -n "${HQ_CLI_CAPS_CACHE:-}" ]; then
+      __hs_cache="$HQ_CLI_CAPS_CACHE"
+    else
+      __hs_dir="${XDG_CACHE_HOME:-${HOME:-/tmp}/.cache}/hq-cli"
+      mkdir -p "$__hs_dir" 2>/dev/null && chmod 700 "$__hs_dir" 2>/dev/null || true
+      __hs_cache="$__hs_dir/core-caps.${__hs_key:-0}"
+    fi
+    __hs_caps=""
+    if [ -r "$__hs_cache" ] && [ -O "$__hs_cache" ]; then
+      __hs_caps="$(cat "$__hs_cache" 2>/dev/null || true)"
+    elif __hs_caps="$(hq core --help 2>/dev/null)"; then
+      [ -n "$__hs_caps" ] && (umask 077; printf '%s' "$__hs_caps" >"$__hs_cache" 2>/dev/null) || true
+    else
+      __hs_caps=""
+    fi
+    case "$__hs_caps" in
+      *hq-session*)
+        case "$__hs_caps" in
+          *exact-company-directory-match-v1*) exec hq core hq-session "$@" ;;
+        esac
+        ;;
+    esac
+  fi
+fi
+
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # The DATA tree (sessions, companies, hooks) is the live HQ root. When this
 # script is dispatched as `hq core hq-session` from inside the hq-cli package,
@@ -43,6 +83,44 @@ LIB_DIR="$SCRIPT_DIR/lib"
 # shellcheck source=lib/session-id.sh
 . "$LIB_DIR/session-id.sh"
 
+# These checks stay local so hq-session remains usable by fixtures and bundled
+# copies that include its capability and ID libraries but not auto-bind.
+hq_session_has_exact_company_dir() {
+  local root="${1:-}" slug="${2:-}" company_dir
+  [ -n "$root" ] && [ -n "$slug" ] || return 1
+  for company_dir in "$root"/companies/*; do
+    [ -d "$company_dir" ] || continue
+    [ -L "$company_dir" ] && continue
+    [ "${company_dir##*/}" = "$slug" ] && return 0
+  done
+  return 1
+}
+
+hq_session_has_case_alias() {
+  local root="${1:-}" slug="${2:-}" company_dir company_slug slug_fold company_fold
+  [ -n "$root" ] && [ -n "$slug" ] || return 1
+
+  # Exact, real entries are the common case. Check them before starting any
+  # case-fold subprocesses on SessionStart or a normal company bind.
+  for company_dir in "$root"/companies/*; do
+    [ -d "$company_dir" ] || continue
+    [ -L "$company_dir" ] && continue
+    company_slug="${company_dir##*/}"
+    [ "$company_slug" = "$slug" ] && return 1
+  done
+
+  slug_fold="$(printf '%s' "$slug" | LC_ALL=C tr '[:upper:]' '[:lower:]')"
+  for company_dir in "$root"/companies/*; do
+    [ -d "$company_dir" ] || continue
+    [ -L "$company_dir" ] && continue
+    company_slug="${company_dir##*/}"
+    [ "$company_slug" = "$slug" ] && continue
+    company_fold="$(printf '%s' "$company_slug" | LC_ALL=C tr '[:upper:]' '[:lower:]')"
+    [ "$company_fold" = "$slug_fold" ] && return 0
+  done
+  return 1
+}
+
 # Set by the --session-id global option; empty means "resolve it".
 SESSION_ID_OVERRIDE=""
 
@@ -78,7 +156,19 @@ cmd_get() {
   [ -n "$key" ] || { echo "usage: hq-session.sh get <key>" >&2; exit 1; }
   local meta
   meta="$(current_meta)"
+  # Missing meta.yaml: no keys to read. Print nothing, exit 0.
+  # Unreadable meta.yaml: awk fails and this function exits non-zero under
+  # set -e. Those two are not the same case — do not default either.
   [ -n "$meta" ] && [ -f "$meta" ] || return 0
+  # Absent key: print nothing. For `senior`, a record written before that
+  # field existed has no line; that is a successful read of a file that does
+  # not contain the key, not a failed read. §3.1 defaults `senior` to `user`
+  # at write time (the seed in cmd_set / master-hook.sh). This getter does
+  # not invent that default, so "never written" stays distinguishable from
+  # an explicit `senior: user`. Authority walkers apply the §3.1 default at
+  # the walk site. Substituting `user` here would collapse absence into the
+  # permissive value that hq-never-swallow-errors and
+  # monitor-unknown-paths-must-not-resolve-to-healthy forbid.
   awk -v k="$key" '
     $1 == k":" {
       sub(/^[^:]+:[[:space:]]*/, "")
@@ -93,17 +183,55 @@ cmd_set() {
   local key="${1:-}" value="${2:-}"
   [ -n "$key" ] && [ $# -ge 2 ] || { echo "usage: hq-session.sh set <key> <value>" >&2; exit 1; }
 
-  # Reject an invalid company_slug BEFORE writing anything. Otherwise a bad value
-  # lands in meta.yaml and only fails later at session_scope_mint, leaving
-  # corrupt state that the scope gate would read as a (bogus) binding. Mirrors
-  # session_scope_mint's own character-set rule; `personal` is a valid slug.
+  # Reject invalid company_slug values before writing anything. A case alias
+  # could otherwise bind the session and surface policies from a differently
+  # named company directory on a case-insensitive filesystem.
   if [ "$key" = "company_slug" ] && [ -n "$value" ]; then
     case "$value" in
-      *[!a-z0-9_-]*)
-        echo "hq-session: invalid company_slug: '$value' (allowed characters: a-z 0-9 - _)" >&2
+      *[!a-zA-Z0-9_-]*)
+        echo "hq-session: invalid company_slug: '$value' (allowed characters: A-Z a-z 0-9 - _)" >&2
         exit 1
         ;;
     esac
+    if [ "$value" != "personal" ] && {
+      [ -L "$REPO_ROOT/companies/$value" ] \
+        || hq_session_has_case_alias "$REPO_ROOT" "$value"
+    }; then
+      echo "hq-session: company_slug must use the exact real directory name: '$value'" >&2
+      exit 1
+    fi
+  fi
+
+  # Reject an invalid senior BEFORE writing anything. Otherwise a bad value
+  # lands in meta.yaml and only fails later when the authority walk reads it,
+  # leaving corrupt state that hop 2 would treat as a real parent. Same shape
+  # as the company_slug guard above.
+  #
+  # Accepted forms: user | session:<id> | lane:<id>.
+  # <id> charset is A-Za-z0-9._- — company_slug's a-z0-9_- plus `.` (hostnames
+  # contain dots) plus A-Z because lane ids on this box are ULID_hostname
+  # (e.g. 01M30KHSEX50K0G203QNV2590N_ip-172-31-47-133-ec2-internal; ULIDs are
+  # Crockford base32, typically uppercase) and session ids are UUID hex
+  # (e.g. 0026e2dd-7fff-4733-8d61-9a6fe7004908). `.` and `..` are rejected as
+  # ids: they are path segments under workspace/sessions/.
+  if [ "$key" = "senior" ]; then
+    local senior_ok=0 senior_id
+    case "$value" in
+      user)
+        senior_ok=1
+        ;;
+      session:*|lane:*)
+        senior_id="${value#*:}"
+        case "$senior_id" in
+          ""|.|..|*[!A-Za-z0-9._-]*) ;;
+          *) senior_ok=1 ;;
+        esac
+        ;;
+    esac
+    if [ "$senior_ok" != 1 ]; then
+      echo "hq-session: invalid senior: '$value' (accepted forms: user, session:<id>, lane:<id>)" >&2
+      exit 1
+    fi
   fi
 
   local id meta
@@ -115,9 +243,10 @@ cmd_set() {
   meta="$SESSIONS_DIR/$id/meta.yaml"
   mkdir -p "$(dirname "$meta")"
   # Seed the same header master-hook.sh writes, so binding a session the hook
-  # has not bootstrapped yet still produces a well-formed record.
+  # has not bootstrapped yet still produces a well-formed record. `senior: user`
+  # is the §3.1 default so hop 2 of the authority walk has a field to read.
   if [ ! -f "$meta" ]; then
-    printf 'session_id: %s\nstarted_at: "%s"\n' \
+    printf 'session_id: %s\nstarted_at: "%s"\nsenior: user\n' \
       "$id" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" > "$meta"
   fi
 
@@ -159,6 +288,29 @@ cmd_set() {
       spawn_work_mesh_register "$id" || true
     fi
   fi
+
+  # US-011: mid-session project change closes the old card and opens a new one.
+  # First bind (empty prev) only updates the live-binding marker — SessionStart
+  # already emitted session_start (or reconcile will bind without a card flip).
+  if [ "$key" = "project" ] && [ -n "$value" ] && [ "$value" != "$prev" ]; then
+    local co tk
+    co="$(cmd_get company_slug 2>/dev/null || true)"
+    tk="$(cmd_get task 2>/dev/null || true)"
+    if [ -f "$REPO_ROOT/core/scripts/lib/work-mesh-enqueue.sh" ] && \
+       [ -f "$REPO_ROOT/core/scripts/lib/work-mesh-live-rebind.sh" ]; then
+      # shellcheck source=lib/work-mesh-enqueue.sh
+      . "$REPO_ROOT/core/scripts/lib/work-mesh-enqueue.sh" 2>/dev/null || true
+      # shellcheck source=lib/work-mesh-live-hook.sh
+      . "$REPO_ROOT/core/scripts/lib/work-mesh-live-hook.sh" 2>/dev/null || true
+      # shellcheck source=lib/work-mesh-live-rebind.sh
+      . "$REPO_ROOT/core/scripts/lib/work-mesh-live-rebind.sh" 2>/dev/null || true
+      if [ -n "$prev" ] && command -v work_mesh_live_rebind >/dev/null 2>&1; then
+        work_mesh_live_rebind "$id" "$co" "$prev" "$tk" "$co" "$value" "$tk" || true
+      elif command -v work_mesh_live_write_binding_marker >/dev/null 2>&1; then
+        work_mesh_live_write_binding_marker "$id" "$co" "$value" "$tk" || true
+      fi
+    fi
+  fi
 }
 
 # Spawn the client-side Work Mesh registration hook, detached, for a mid-session
@@ -167,15 +319,16 @@ cmd_set() {
 # and this backgrounds even its fast foreground path off cmd_set's return path.
 spawn_work_mesh_register() {
   local sid="$1"
-  local hook="$REPO_ROOT/core/hooks/work-mesh-register.sh"
+  local hook="$REPO_ROOT/core/hooks/SessionStart/35-work-mesh-session-start.sh"
   local logf="$REPO_ROOT/workspace/logs/work-mesh-hook.log"
-  [ -x "$hook" ] || return 0
+  [ -f "$hook" ] || return 0
   command -v jq >/dev/null 2>&1 || return 0
   local ev
   ev="$(jq -nc --arg sid "$sid" --arg cwd "${PWD:-}" '{session_id:$sid,cwd:$cwd}' 2>/dev/null)" || return 0
   [ -n "$ev" ] || return 0
   mkdir -p "$(dirname "$logf")" 2>/dev/null || true
-  HQ_ROOT="$REPO_ROOT" nohup bash -c 'printf "%s" "$1" | "$2" company_slug' _ "$ev" "$hook" \
+  HQ_ROOT="$REPO_ROOT" CLAUDE_CODE_SESSION_ID="$sid" \
+    nohup bash -c 'printf "%s" "$1" | bash "$2" SessionStart' _ "$ev" "$hook" \
     >>"$logf" 2>&1 </dev/null &
   disown 2>/dev/null || true
   return 0
@@ -183,15 +336,18 @@ spawn_work_mesh_register() {
 
 # Print a company's hard-enforcement policies, read directly from the policy
 # files (the pre-built digest was retired — the when/on trigger hook is now the
-# sole policy-surfacing path). Emits one `- [hard] **slug**: rule` line each,
-# deduped (digest/README/example/sync-conflict copies are skipped) and budgeted
-# (HQ_COMPANY_BIND_POLICY_CAP lines / HQ_COMPANY_BIND_POLICY_BYTES bytes, with a
-# non-silent pointer for the overflow). An unbounded dump — observed at ~298
-# lines for a large tenant — buries the rules it exists to surface; the
-# reactive trigger hook re-injects any withheld policy when its trigger fires.
+# sole policy-surfacing path). Emits one `- [hard] **id**: rule` line per policy,
+# including its exact source path so IDs do not have to match filenames. Lines
+# are deduped (digest/README/example/sync-conflict copies are skipped) and
+# budgeted (HQ_COMPANY_BIND_POLICY_CAP lines / HQ_COMPANY_BIND_POLICY_BYTES
+# bytes, with a non-silent pointer for the overflow). An unbounded dump —
+# observed at ~298 lines for a large tenant — buries the rules it exists to
+# surface; the reactive trigger hook re-injects any withheld policy when its
+# trigger fires.
 emit_company_hard_policies() {
   local co="$1"
   local dir="$REPO_ROOT/companies/$co/policies"
+  hq_session_has_exact_company_dir "$REPO_ROOT" "$co" || return 0
   [ -d "$dir" ] || return 0
   # Collect real policy files only. Skip the generated digest, docs, examples,
   # and sync-conflict duplicates: policy slugs never contain spaces, so a space
@@ -209,13 +365,15 @@ emit_company_hard_policies() {
   done
   [ "${#files[@]}" -gt 0 ] || return 0
   local lines
-  lines="$(awk '
+  lines="$(awk -v co="$co" '
     function bn(p,  n,a,b){ n=split(p,a,"/"); b=a[n]; sub(/\.md$/,"",b); return b }
-    function flush(){ if(enf=="hard" && rule!=""){ if(id=="")id=bn(fn); printf "- [hard] **%s**: %s\n", id, rule } }
+    function policy_file(p,  n,a){ n=split(p,a,"/"); return a[n] }
+    function flush(){ if(enf=="hard" && rule!=""){ if(id=="")id=bn(fn); printf "- [hard] **%s**: %s Full text: `companies/%s/policies/%s`.\n", id, rule, co, policy_file(fn) } }
     FNR==1 { if(seen) flush(); d=0;id="";enf="";rule="";rsec=0;rcap=0;fn=FILENAME;seen=1 }
     /^---[ \t]*$/ { d++; next }
     d==1 && /^id:/          { s=$0; sub(/^id:[ \t]*/,"",s); gsub(/^["'"'"']|["'"'"']$/,"",s); id=s; next }
     d==1 && /^enforcement:/ { s=$0; sub(/^enforcement:[ \t]*/,"",s); gsub(/[ \t]/,"",s); enf=s; next }
+    d==1 && /^status:[ \t]*retired/ { enf="" ; next }
     d>=2 && /^## Rule[ \t]*$/ { rsec=1; next }
     d>=2 && rsec && /^## / { rsec=0 }
     d>=2 && rsec && !rcap && NF { line=$0; gsub(/\*\*/,"",line); if(length(line)>160)line=substr(line,1,157)"..."; rule=line; rcap=1 }
@@ -226,11 +384,14 @@ emit_company_hard_policies() {
   # (glob order), never silent — overflow is summarized with a pointer so the
   # withheld policies stay one command away.
   local cap="${HQ_COMPANY_BIND_POLICY_CAP:-32}"
-  local max_bytes="${HQ_COMPANY_BIND_POLICY_BYTES:-40960}"
+  # 2026-09-07: was 40960. Claude Code persists hook output above ~10,000
+  # bytes and shows the model a 2 KB preview, so a 40 KB digest was never
+  # read. Keep the whole digest under the host ceiling with margin.
+  local max_bytes="${HQ_COMPANY_BIND_POLICY_BYTES:-7168}"
   printf '\n<company-policy-digest co="%s">\n' "$co"
   printf '# %s hard-enforcement policies (auto-surfaced on company bind)\n' "$co"
   printf '> Company context just bound mid-session. These HARD rules now apply.\n'
-  printf '> Full text: `companies/%s/policies/{slug}.md` (or `qmd get -c %s {slug}`).\n\n' "$co" "$co"
+  printf '> Full text: open the file path shown on each policy line. Browse `companies/%s/policies/` for the full set.\n\n' "$co"
   printf '%s\n' "$lines" | awk -v cap="$cap" -v maxb="$max_bytes" -v co="$co" '
     NF {
       n++
@@ -242,8 +403,8 @@ emit_company_hard_policies() {
     END {
       dropped = n - kept
       if (dropped > 0)
-        printf "\n> %d more hard %s not shown (bind budget: %d policies / %d bytes). Full set: `companies/%s/policies/` or `qmd get -c %s {slug}`; matching rules re-surface via the policy trigger hook when they apply.\n", \
-          dropped, (dropped == 1 ? "policy" : "policies"), cap, maxb, co, co
+        printf "\n> %d more hard %s not shown (bind budget: %d policies / %d bytes). Browse `companies/%s/policies/` for the full set; matching rules re-surface via the policy trigger hook when they apply.\n", \
+          dropped, (dropped == 1 ? "policy" : "policies"), cap, maxb, co
     }'
   printf '</company-policy-digest>\n'
 }