@indigoai-us/hq-cli 5.314.0 → 5.315.0

package/assets/scaffold/core/scripts/lib/portable.sh

@@ -0,0 +1,211 @@
+# shellcheck shell=bash
+# portable.sh — shared OS-portability helpers for hq-core shell scripts.
+#
+# SOURCED, never executed:  . "$ROOT/core/scripts/lib/portable.sh"
+# bash 3.2 safe; works under Linux, macOS, and Windows Git Bash with set -u.
+#
+# Canonicalizes good in-repo dual-implementation patterns:
+#   - work-mesh-lib.sh wm_file_mtime (numeric-probe dual stat)
+#   - archive-old-threads.sh dual stat / date -d | date -v
+#   - compute-checksums.sh Git Bash awareness
+#
+# JSON engines are NOT here — source core/scripts/hook-lib.sh (hq_json_get /
+# hq_json_encode: jq first, then node). This file owns OS primitives + hard-fail
+# jq install messaging only.
+
+# portable_stat_mtime <path>
+#   Print mtime as epoch seconds. Uses BSD-form stat -f first, accepts only a
+#   strictly numeric result (GNU stat -f is filesystem mode and may print text),
+#   then falls through to GNU stat -c. Mirrors work-mesh-lib.sh:215-230.
+#   Returns 1 when both forms fail.
+portable_stat_mtime() {
+  local f="${1:-}" value
+  [ -n "$f" ] || return 1
+  value="$(stat -f %m "$f" 2>/dev/null)" || value=""
+  case "$value" in
+    ''|*[!0-9]*) ;;
+    *) printf '%s' "$value"; return 0 ;;
+  esac
+  value="$(stat -c %Y "$f" 2>/dev/null)" || value=""
+  case "$value" in
+    ''|*[!0-9]*) return 1 ;;
+    *) printf '%s' "$value"; return 0 ;;
+  esac
+}
+
+# portable_sed_inplace <sed-script> <file> [extra sed args...]
+#   In-place sed that works on both GNU sed (sed -i) and BSD sed (sed -i '').
+portable_sed_inplace() {
+  local script="${1:-}"
+  local file="${2:-}"
+  shift 2 2>/dev/null || true
+  [ -n "$script" ] && [ -n "$file" ] || return 1
+  [ -f "$file" ] || return 1
+  # Prefer GNU form; fall back to BSD empty-suffix form.
+  if sed --version >/dev/null 2>&1; then
+    sed -i "$@" -e "$script" "$file"
+  else
+    sed -i '' "$@" -e "$script" "$file"
+  fi
+}
+
+# portable_tmpdir
+#   Print a writable temp directory (no trailing slash). Prefer TMPDIR, else /tmp.
+portable_tmpdir() {
+  local d="${TMPDIR:-/tmp}"
+  # Strip trailing slash except for root.
+  case "$d" in
+    /) printf '%s' "$d" ;;
+    */) printf '%s' "${d%/}" ;;
+    *) printf '%s' "$d" ;;
+  esac
+}
+
+# portable_date_epoch_to_iso <epoch_seconds>
+#   Convert epoch seconds to UTC ISO-8601 (YYYY-MM-DDTHH:MM:SSZ).
+#   Dual: GNU date -d @N / BSD date -r N.
+portable_date_epoch_to_iso() {
+  local epoch="${1:-}"
+  case "$epoch" in
+    ''|*[!0-9]*) return 1 ;;
+  esac
+  date -u -d "@${epoch}" +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null \
+    || date -u -r "$epoch" +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null \
+    || return 1
+}
+
+# portable_user
+#   Print a filename-safe user key from USER or USERNAME (Git Bash often lacks USER).
+portable_user() {
+  local u="${USER:-${USERNAME:-unknown}}"
+  # shellcheck disable=SC2001
+  u="$(printf '%s' "$u" | sed 's/[^[:alnum:]_.-]/_/g')"
+  [ -n "$u" ] || u="unknown"
+  printf '%s' "$u"
+}
+
+# portable_jq_install_hint
+#   Print multi-line per-OS jq install guidance to stdout.
+portable_jq_install_hint() {
+  # Single multi-OS line so portability lint does not flag brew-only messages.
+  printf '%s\n' "Install jq: Windows: winget install jqlang.jq | choco install jq | scoop install jq; Linux: sudo apt install jq | sudo dnf install jq; macOS: brew install jq"
+}
+
+# require_jq
+#   Return 0 if jq is on PATH. Otherwise print install guidance to stderr and
+#   return 1. Caller decides whether to die. Does not implement JSON parse.
+require_jq() {
+  if command -v jq >/dev/null 2>&1; then
+    return 0
+  fi
+  printf 'jq is required but not installed.\n' >&2
+  portable_jq_install_hint >&2
+  return 1
+}
+
+# portable_native_path <path>
+#   Print a path a native (non-MSYS) Windows binary can open. Git Bash mktemp
+#   and $TMPDIR often yield /tmp/... which Node's hq.exe cannot read, so
+#   --body-file looks empty. cygpath -m produces C:/... mixed paths. On
+#   POSIX hosts this is identity. Empty input returns 1.
+portable_native_path() {
+  local p="${1:-}"
+  [ -n "$p" ] || return 1
+  if command -v cygpath >/dev/null 2>&1; then
+    cygpath -m "$p" 2>/dev/null || printf '%s' "$p"
+    return 0
+  fi
+  printf '%s' "$p"
+}
+
+# portable_qmd_models_dir
+#   Print qmd's GGUF cache directory (no trailing slash). Override with
+#   QMD_MODELS_DIR. Otherwise XDG_CACHE_HOME/qmd/models, then
+#   HOME/.cache/qmd/models, then USERPROFILE/.cache/qmd/models (Windows).
+portable_qmd_models_dir() {
+  local d
+  if [ -n "${QMD_MODELS_DIR:-}" ]; then
+    d="$QMD_MODELS_DIR"
+  elif [ -n "${XDG_CACHE_HOME:-}" ]; then
+    d="$XDG_CACHE_HOME/qmd/models"
+  elif [ -n "${HOME:-}" ]; then
+    d="$HOME/.cache/qmd/models"
+  elif [ -n "${USERPROFILE:-}" ]; then
+    d="$USERPROFILE/.cache/qmd/models"
+    if command -v cygpath >/dev/null 2>&1; then
+      d="$(cygpath -u "$d" 2>/dev/null || printf '%s' "$d")"
+    fi
+  else
+    return 1
+  fi
+  case "$d" in
+    */) d="${d%/}" ;;
+  esac
+  printf '%s' "$d"
+}
+
+# portable_qmd_embed_model_ready
+#   Return 0 when a usable GGUF already sits in the qmd models dir so
+#   vsearch/query/embed will not start a multi-hundred-MB download. A file
+#   named by QMD_EMBED_MODEL (basename after the last /) counts; otherwise
+#   any *.gguf of at least 1 MiB counts. Missing dir or tiny placeholders
+#   return 1.
+portable_qmd_embed_model_ready() {
+  local dir want f sz
+  dir="$(portable_qmd_models_dir)" || return 1
+  [ -d "$dir" ] || return 1
+  if [ -n "${QMD_EMBED_MODEL:-}" ]; then
+    want="${QMD_EMBED_MODEL##*/}"
+    if [ -n "$want" ] && [ -f "$dir/$want" ]; then
+      sz="$(wc -c < "$dir/$want" | tr -d '[:space:]')"
+      case "$sz" in
+        ''|*[!0-9]*) ;;
+        *) [ "$sz" -ge 1048576 ] && return 0 ;;
+      esac
+    fi
+  fi
+  for f in "$dir"/*.gguf; do
+    [ -f "$f" ] || continue
+    sz="$(wc -c < "$f" | tr -d '[:space:]')"
+    case "$sz" in
+      ''|*[!0-9]*) continue ;;
+    esac
+    [ "$sz" -ge 1048576 ] && return 0
+  done
+  return 1
+}
+
+# portable_qmd_cmd_would_download_model <command>
+#   Return 0 when a shell command would invoke qmd vsearch, query, embed, or
+#   pull — the subcommands that auto-download GGUF models on first use.
+#   First non-flag argument after a qmd token is the subcommand, so
+#   `qmd search "how to vsearch"` is NOT a match.
+portable_qmd_cmd_would_download_model() {
+  local cmd="${1:-}"
+  [ -n "$cmd" ] || return 1
+  case "$cmd" in
+    *qmd*) ;;
+    *) return 1 ;;
+  esac
+  printf '%s\n' "$cmd" | awk '
+    BEGIN { found = 0 }
+    {
+      n = split($0, raw, /[[:space:];|&]+/)
+      for (i = 1; i <= n; i++) {
+        tok = raw[i]
+        if (tok == "") continue
+        base = tok
+        sub(/^.*\//, "", base)
+        if (base == "qmd" || base == "qmd.exe") {
+          j = i + 1
+          while (j <= n && raw[j] ~ /^-/) j++
+          if (j <= n && raw[j] ~ /^(vsearch|query|embed|pull)$/) {
+            found = 1
+            exit
+          }
+        }
+      }
+    }
+    END { exit found ? 0 : 1 }
+  '
+}

package/assets/scaffold/core/scripts/lib/secret-patterns.sh

@@ -0,0 +1,58 @@
+# shellcheck shell=bash
+# hq-core: public
+# secret-patterns.sh — shared secret-detection patterns for hq-core shell scripts.
+#
+# SOURCED, never executed:  . "$ROOT/core/scripts/lib/secret-patterns.sh"
+# bash 3.2 safe; no associative arrays.
+#
+# Single source of truth for the secret-shaped patterns that generated
+# artifacts (delegation manifests, briefs, pickup prompts, DM payloads) are
+# scanned against before they are written to disk or transmitted. Mirrors the
+# runtime PreToolUse hook at .claude/hooks/detect-secrets.sh — a regression
+# test (core/scripts/tests/hq-delegate-bundle.test.sh) asserts this list stays
+# a superset of the hook's, so the two cannot silently drift.
+#
+# Entries are "<extended-regex>:<human name>". The regex part may not contain
+# a colon; the name may.
+#
+# Entries are the bare token patterns. SECRET_PATTERN_BOUNDARY below is
+# prepended at match time -- keep them in this form so they stay comparable
+# verbatim with the runtime hook's array (see the drift test named above).
+
+# Left token boundary. Without it the sk- pattern matches mid-word and ordinary
+# HQ filenames (a-ri|sk-..., hq-ta|sk-..., controller-di|sk-...) scan as
+# credentials. Mirrors SECRET_BOUNDARY in .claude/hooks/detect-secrets.sh.
+SECRET_PATTERN_BOUNDARY='(^|[^a-zA-Z0-9])'
+
+SECRET_PATTERNS=(
+  "sk-[a-zA-Z0-9._-]{20,}:OpenAI/Stripe key"
+  "ghp_[a-zA-Z0-9]{36,}:GitHub PAT"
+  "AKIA[0-9A-Z]{16}:AWS access key"
+  "xox[bpsa]-[a-zA-Z0-9-]+:Slack token"
+  "Bearer [a-zA-Z0-9._-]{20,}:Bearer token"
+  "-----BEGIN (RSA |EC |DSA |OPENSSH )?PRIVATE KEY-----:Private key"
+  "glpat-[a-zA-Z0-9_-]{20,}:GitLab PAT"
+  "gho_[a-zA-Z0-9]{36,}:GitHub OAuth token"
+  "github_pat_[a-zA-Z0-9_]{22,}:Fine-grained GitHub PAT"
+  "eyJ[a-zA-Z0-9_-]{20,}\.[a-zA-Z0-9_-]{20,}\.[a-zA-Z0-9_-]{10,}:JWT"
+)
+
+# hq_scan_secrets <file>...
+#   Scan files for secret-shaped content. Prints "pattern: <name> in <file>"
+#   to stderr for every hit (never the matched value itself) and returns 1 if
+#   anything matched, 0 when all files are clean. Missing files are skipped.
+hq_scan_secrets() {
+  local hit=0 f entry pattern name
+  for f in "$@"; do
+    [ -f "$f" ] || continue
+    for entry in "${SECRET_PATTERNS[@]}"; do
+      pattern="${SECRET_PATTERN_BOUNDARY}${entry%%:*}"
+      name="${entry#*:}"
+      if grep -Eq -- "$pattern" "$f" 2>/dev/null; then
+        echo "secret-scan: pattern '$name' matched in $f" >&2
+        hit=1
+      fi
+    done
+  done
+  return "$hit"
+}

package/assets/scaffold/core/scripts/lib/session-id.sh

@@ -33,7 +33,8 @@
 #   3. CLAUDE_SESSION_ID       — Claude Code (alternate/legacy)
 #   4. CODEX_SESSION_ID        — Codex
 #   5. CODEX_THREAD_ID         — Codex, thread-scoped runs
-#   6. workspace/sessions/.current — no session env; last-writer-wins fallback
+#   6. GROK_SESSION_ID         — Grok Build (Desktop / CLI)
+#   7. workspace/sessions/.current — no session env; last-writer-wins fallback
 #
 # The env precedence list matches .claude/skills/_shared/journal.sh so every
 # per-session artifact (journal, session meta, scope capability) keys off the
@@ -59,7 +60,7 @@ session_id_is_valid() {
 session_id_from_env() {
   local var val
   for var in HQ_SESSION_ID CLAUDE_CODE_SESSION_ID CLAUDE_SESSION_ID \
-             CODEX_SESSION_ID CODEX_THREAD_ID; do
+             CODEX_SESSION_ID CODEX_THREAD_ID GROK_SESSION_ID; do
     val="${!var:-}"
     val="$(printf '%s' "$val" | tr -d '[:space:]')"
     if session_id_is_valid "$val"; then

package/assets/scaffold/core/scripts/lib/session-scope-capability.sh

@@ -29,7 +29,7 @@ session_scope_mint() {
   [ -n "$root" ] && [ -n "$sid" ] && [ -n "$slug" ] || return 1
 
   case "$slug" in
-    ''|*[!a-z0-9_-]*)
+    ''|*[!a-zA-Z0-9_-]*)
       echo "session-scope-capability: invalid company_slug: $slug" >&2
       return 1
       ;;

package/assets/scaffold/core/scripts/lib/work-mesh-enqueue.sh

@@ -100,7 +100,8 @@ work_mesh_ulid() {
     bytes=$(dd if=/dev/urandom bs=10 count=1 2>/dev/null | od -An -tu1 | tr -s ' ' '\n' | grep -E '^[0-9]+$' | head -n 10 | tr '\n' ' ')
     # shellcheck disable=SC2206
     local -a bb=($bytes)
-    b=("${bb[@]}")
+    # Bash 3.2 + set -u: empty bb[@] is unbound; keep the copy portable.
+    b=(${bb[@]+"${bb[@]}"})
     while [ "${#b[@]}" -lt 10 ]; do
       b+=($((RANDOM % 256)))
     done

package/assets/scaffold/core/scripts/lib/work-mesh-live-hook.sh

@@ -0,0 +1,378 @@
+#!/usr/bin/env bash
+# hq-core: public
+# work-mesh-live-hook.sh — shared helpers for Work Mesh Live enqueue-only hooks.
+# Sourced by core/hooks/*/3*-work-mesh-*.sh. Never execute directly.
+
+# work_mesh_live_disabled
+#   Exit 0 (true) when kill switches say these hooks must no-op.
+work_mesh_live_disabled() {
+  case "${HQ_WORK_MESH_DISABLED:-}" in
+    1|true|TRUE|yes|YES|on|ON) return 0 ;;
+  esac
+  case ",${HQ_DISABLED_HOOKS:-}," in
+    *,work-mesh,*|*,work-mesh-live,*|*,\*,*) return 0 ;;
+  esac
+  return 1
+}
+
+# work_mesh_live_bootstrap
+#   Resolve HQ_ROOT from the calling hook path; source enqueue + session-id.
+#   Caller must set _WM_HOOK_DIR to dirname of BASH_SOURCE[0] before calling,
+#   OR pass the hook file path as $1.
+work_mesh_live_bootstrap() {
+  local hook_file="${1:-${BASH_SOURCE[1]:-}}"
+  local hook_dir hq
+  hook_dir="$(cd "$(dirname "$hook_file")" 2>/dev/null && pwd)" || return 1
+  # core/hooks/<Event>/<file> -> HQ root is ../../..
+  hq="${HQ_ROOT:-$(cd "$hook_dir/../../.." 2>/dev/null && pwd)}"
+  [ -n "$hq" ] || return 1
+  export HQ_ROOT="$hq"
+  # shellcheck source=core/scripts/lib/work-mesh-enqueue.sh
+  . "$HQ_ROOT/core/scripts/lib/work-mesh-enqueue.sh" 2>/dev/null || return 1
+  # shellcheck source=core/scripts/lib/session-id.sh
+  . "$HQ_ROOT/core/scripts/lib/session-id.sh" 2>/dev/null || true
+  return 0
+}
+
+# work_mesh_live_session_id <stdin-json>
+#   Prefer env (session_id_from_env); else payload session_id / sessionId.
+work_mesh_live_session_id() {
+  local input="${1:-}" id=""
+  if command -v session_id_from_env >/dev/null 2>&1; then
+    id="$(session_id_from_env)"
+  fi
+  if [ -z "$id" ]; then
+    for var in HQ_SESSION_ID CLAUDE_CODE_SESSION_ID CLAUDE_SESSION_ID CODEX_SESSION_ID CODEX_THREAD_ID; do
+      id="${!var:-}"
+      id="$(printf '%s' "$id" | tr -d '[:space:]')"
+      [ -n "$id" ] && break
+    done
+  fi
+  if [ -z "$id" ] && [ -n "$input" ]; then
+    # Prefer jq when present; pure-bash fallback for the common keys.
+    if command -v jq >/dev/null 2>&1; then
+      id="$(printf '%s' "$input" | jq -r '.session_id // .sessionId // .conversation_id // .conversationId // .thread_id // .threadId // empty' 2>/dev/null || true)"
+    else
+      id="$(printf '%s' "$input" | sed -n 's/.*"session_id"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p; t; s/.*"sessionId"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -n1)"
+    fi
+    id="$(printf '%s' "$id" | tr -d '[:space:]')"
+  fi
+  if command -v session_id_is_valid >/dev/null 2>&1; then
+    session_id_is_valid "$id" || id=""
+  else
+    case "$id" in
+      ""|.|..|*[!A-Za-z0-9._-]*) id="" ;;
+    esac
+  fi
+  printf '%s' "$id"
+}
+
+# work_mesh_live_harness
+#   HQ_HARNESS / HQ_WORK_MESH_HARNESS / HQ_CHECKPOINT_RUNTIME -> contract harness.
+work_mesh_live_harness() {
+  local h="${HQ_HARNESS:-${HQ_WORK_MESH_HARNESS:-${HQ_CHECKPOINT_RUNTIME:-claude-code}}}"
+  case "$h" in
+    claude|claude-code|Claude|ClaudeCode) printf 'claude-code' ;;
+    codex|Codex) printf 'codex' ;;
+    grok|Grok) printf 'grok' ;;
+    hq-sessions|hq_sessions|sessions) printf 'hq-sessions' ;;
+    agent-box|agent_box|box) printf 'agent-box' ;;
+    *) printf '%s' "$h" ;;
+  esac
+}
+
+# work_mesh_live_adapter_version
+work_mesh_live_adapter_version() {
+  if [ -n "${HQ_ADAPTER_CONTRACT_VERSION:-}" ]; then
+    printf '%s' "$HQ_ADAPTER_CONTRACT_VERSION"
+    return 0
+  fi
+  if [ -f "${HQ_ROOT:-}/core/scripts/lib/provider-adapter-version.sh" ]; then
+    # shellcheck source=core/scripts/lib/provider-adapter-version.sh
+    . "$HQ_ROOT/core/scripts/lib/provider-adapter-version.sh" 2>/dev/null || true
+  fi
+  printf '%s' "${HQ_ADAPTER_CONTRACT_VERSION:-1.0.0}"
+}
+
+# work_mesh_live_runtime_version
+work_mesh_live_runtime_version() {
+  printf '%s' "${HQ_RUNTIME_VERSION:-${CLAUDE_CODE_VERSION:-${CODEX_VERSION:-${GROK_VERSION:-}}}}"
+}
+
+# work_mesh_live_next_seq <session-id>
+#   Monotonic seq under ~/.hq/work-mesh/seq/<sid> (or WORK_MESH_SEQ_DIR).
+#   Hot path: bash file read, no tr/chmod when the dir already exists.
+work_mesh_live_next_seq() {
+  local sid="$1" dir file n
+  dir="${WORK_MESH_SEQ_DIR:-${HOME}/.hq/work-mesh/seq}"
+  if [ ! -d "$dir" ]; then
+    mkdir -p -- "$dir" 2>/dev/null || true
+    chmod 700 -- "$dir" 2>/dev/null || true
+  fi
+  file="$dir/$sid"
+  n=0
+  if [ -f "$file" ]; then
+    n="$(<"$file")"
+    n="${n//[[:space:]]/}"
+    case "$n" in
+      ""|*[!0-9]*) n=0 ;;
+    esac
+  fi
+  n=$((n + 1))
+  printf '%s\n' "$n" >"$file" 2>/dev/null || return 1
+  printf '%s' "$n"
+}
+
+# work_mesh_live_meta_get <root> <sid> <key>
+work_mesh_live_meta_get() {
+  local root="$1" sid="$2" key="$3" meta
+  meta="$root/workspace/sessions/$sid/meta.yaml"
+  [ -f "$meta" ] || return 0
+  awk -v k="$key" '$1==k":"{ sub(/^[^:]+:[[:space:]]*/,""); gsub(/^"|"$/,""); print; exit }' "$meta" 2>/dev/null
+}
+
+# work_mesh_live_state_path <sid>
+work_mesh_live_state_path() {
+  printf '%s/.hq/work-context/sessions/%s.json' "${WORK_MESH_HOME:-$HOME}" "$1"
+}
+
+# work_mesh_live_board_path <sid>
+work_mesh_live_board_path() {
+  printf '%s/.hq/work-context/sessions/%s/board.md' "${WORK_MESH_HOME:-$HOME}" "$1"
+}
+
+# work_mesh_live_ask_surfaced_path <sid>
+work_mesh_live_ask_surfaced_path() {
+  printf '%s/.hq/work-context/sessions/%s.ask-surfaced' "${WORK_MESH_HOME:-$HOME}" "$1"
+}
+
+# work_mesh_live_pending_decision_path <sid>
+work_mesh_live_pending_decision_path() {
+  printf '%s/.hq/work-context/sessions/%s.pending-decision' "${WORK_MESH_HOME:-$HOME}" "$1"
+}
+
+# work_mesh_live_word_count <text> — count whitespace-separated tokens.
+work_mesh_live_word_count() {
+  local t="$1"
+  # shellcheck disable=SC2086
+  set -- $t
+  printf '%s' "$#"
+}
+
+# work_mesh_live_is_slash_or_short <prompt>
+#   True (0) when slash command or fewer than 3 words.
+work_mesh_live_is_slash_or_short() {
+  local p="$1" n
+  case "$p" in
+    /*) return 0 ;;
+  esac
+  n="$(work_mesh_live_word_count "$p")"
+  [ "$n" -lt 3 ]
+}
+
+# work_mesh_live_bump_tool_writes <sid>
+#   Atomically increment toolWrites on the state JSON (create stub if absent).
+#   Sets REPLY to the new count. Uses temp+mv and chmod 600.
+#   Merge-safe: only toolWrites and updatedAt change; every other field the
+#   hq-cli reconcile/ack path wrote (companyUid, companySlug, projectId, taskId,
+#   startedAt, bindingEpisodeId, decision, contextStatus, ...) is preserved
+#   byte-for-byte. Prefers jq; the no-jq fallback edits the two values in place
+#   in pure bash (compact or pretty-printed JSON, any key order) and only
+#   appends a missing key. contextStatus is set to "unresolved" only on a fresh
+#   stub. Bash 3.2 compatible; no sed/awk/GNU flags.
+#   Concurrency: hq-cli writes the same path with same-dir tmp + rename and has
+#   no lock convention (hq-cli src/lib/work-context/atomic.ts). Two lines of
+#   defense against a reconcile write landing between our read and mv:
+#     1. mkdir lock at <path>.lock (Bash 3.2 safe), bounded wait ~200ms, stale
+#        lock reclaimed by age (>5s). If the lock cannot be taken, the bump is
+#        skipped (return 1) rather than risk a clobber.
+#     2. Re-read immediately before mv; if the file changed since the first
+#        read, rebuild from the new body.
+#   Test seam: WORK_MESH_BUMP_TEST_SLEEP_AFTER_READ=<secs> sleeps between the
+#   first read and the re-read so a test can inject a concurrent writer.
+work_mesh_live_bump_tool_writes() {
+  local sid="$1" path dir lock rc
+  path="$(work_mesh_live_state_path "$sid")"
+  dir="${path%/*}"
+  if [ ! -d "$dir" ]; then
+    mkdir -p -- "$dir" 2>/dev/null || true
+    chmod 700 -- "$dir" 2>/dev/null || true
+  fi
+  lock="$path.lock"
+  _work_mesh_live_lock_acquire "$lock" || return 1
+  _work_mesh_live_bump_locked "$sid" "$path"
+  rc=$?
+  rm -rf -- "$lock" 2>/dev/null || true
+  return $rc
+}
+
+# _work_mesh_live_lock_acquire <lockdir>
+#   mkdir lock; ~20 x 10ms bounded wait; reclaim when the holder's stamp is
+#   older than 5s (or missing after the full wait). 0 = held, 1 = give up.
+_work_mesh_live_lock_acquire() {
+  local lock="$1" i=0 now stamp
+  while :; do
+    if mkdir -- "$lock" 2>/dev/null; then
+      date +%s >"$lock/ts" 2>/dev/null || true
+      return 0
+    fi
+    i=$((i + 1))
+    if [ "$i" -ge 20 ]; then
+      now="$(date +%s 2>/dev/null || printf '0')"
+      stamp="$(cat "$lock/ts" 2>/dev/null || printf '')"
+      case "$stamp" in ""|*[!0-9]*) stamp=0 ;; esac
+      if [ "$stamp" -eq 0 ] || [ $((now - stamp)) -gt 5 ]; then
+        rm -rf -- "$lock" 2>/dev/null || true
+        if mkdir -- "$lock" 2>/dev/null; then
+          date +%s >"$lock/ts" 2>/dev/null || true
+          return 0
+        fi
+      fi
+      return 1
+    fi
+    sleep 0.01 2>/dev/null || sleep 1
+  done
+}
+
+# _work_mesh_live_bump_render <sid> <path> <tmp>
+#   Read <path> (if any), build the bumped document into <tmp>.
+#   Sets _WM_SEEN to the body that was read ("" when absent) and REPLY to the
+#   new count. Returns 1 when the file must not be touched.
+_work_mesh_live_bump_render() {
+  local sid="$1" path="$2" tmp="$3" cur="" next ts body="" rest have_jq=0 written=0
+  _WM_SEEN=""
+  command -v jq >/dev/null 2>&1 && have_jq=1
+  if [ -f "$path" ]; then
+    body="$(<"$path")"
+    _WM_SEEN="$body"
+    case "$body" in
+      *"\"toolWrites\""*)
+        rest="${body#*\"toolWrites\"}"; rest="${rest#*:}"
+        while [ "${rest#"${rest%%[![:space:]]*}"}" != "$rest" ]; do rest="${rest#?}"; done
+        cur="${rest%%[!0-9]*}"
+        ;;
+    esac
+  fi
+  case "$cur" in ""|*[!0-9]*) cur=0 ;; esac
+  next=$((cur + 1))
+  ts=""
+  # %(...)T needs Bash 4.2+; macOS Bash 3.2 falls back to date -u (BSD + GNU).
+  TZ=UTC printf -v ts '%(%Y-%m-%dT%H:%M:%S)T.000Z' -1 2>/dev/null || ts=""
+  case "$ts" in
+    ""|*%*) ts="$(TZ=UTC date -u '+%Y-%m-%dT%H:%M:%S.000Z' 2>/dev/null || true)" ;;
+  esac
+  [ -n "$ts" ] || ts="1970-01-01T00:00:00.000Z"
+  if [ ! -f "$path" ]; then
+    printf '{"contractVersion":1,"sessionId":"%s","contextStatus":"unresolved","toolWrites":%s,"updatedAt":"%s"}\n' \
+      "$sid" "$next" "$ts" >"$tmp" || return 1
+    REPLY="$next"
+    return 0
+  fi
+  if [ "$have_jq" -eq 1 ]; then
+    if printf '%s' "$body" | jq --argjson n "$next" --arg ts "$ts" \
+        '.toolWrites = $n | .updatedAt = $ts' >"$tmp" 2>/dev/null \
+       && [ -s "$tmp" ]; then
+      written=1
+    elif jq -n empty >/dev/null 2>&1; then
+      # jq works but could not parse the file (malformed/partial JSON).
+      # Never replace the CLI's file with a stub: leave it untouched and skip.
+      rm -f -- "$tmp" 2>/dev/null
+      return 1
+    fi
+    # else: jq on PATH is unusable; take the pure-bash path below.
+  fi
+  if [ "$written" -eq 0 ]; then
+    # No-jq fallback: pure-bash in-place edit of the two values (no extra
+    # spawns, Bash 3.2 safe). Works for compact and pretty JSON in any key
+    # order; every other byte of the CLI's file is left as is.
+    local pre digits add
+    case "$body" in
+      *"\"toolWrites\""*)
+        pre="${body%%\"toolWrites\"*}"
+        rest="${body#*\"toolWrites\"}"
+        while [ "${rest#"${rest%%[![:space:]:]*}"}" != "$rest" ]; do rest="${rest#?}"; done
+        digits="${rest%%[!0-9]*}"
+        rest="${rest#"$digits"}"
+        body="$pre\"toolWrites\": $next$rest"
+        ;;
+    esac
+    case "$body" in
+      *"\"updatedAt\""*)
+        pre="${body%%\"updatedAt\"*}"
+        rest="${body#*\"updatedAt\"}"
+        while [ "${rest#"${rest%%[![:space:]:]*}"}" != "$rest" ]; do rest="${rest#?}"; done
+        case "$rest" in
+          \"*) rest="${rest#\"}"; rest="${rest#*\"}" ;;
+        esac
+        body="$pre\"updatedAt\": \"$ts\"$rest"
+        ;;
+    esac
+    add=""
+    case "$body" in *"\"toolWrites\""*) ;; *) add="\"toolWrites\": $next" ;; esac
+    case "$body" in *"\"updatedAt\""*) ;; *) add="${add:+$add, }\"updatedAt\": \"$ts\"" ;; esac
+    if [ -n "$add" ]; then
+      # Insert right after the opening brace so the closing brace stays put.
+      case "$body" in
+        *\{*)
+          pre="${body%%\{*}"
+          rest="${body#*\{}"
+          local peek="$rest"
+          while [ "${peek#"${peek%%[![:space:]]*}"}" != "$peek" ]; do peek="${peek#?}"; done
+          case "$peek" in
+            \}*) body="$pre{$add$peek" ;;
+            *)   body="$pre{$add, $rest" ;;
+          esac
+          ;;
+        *) body="{$add}" ;;
+      esac
+    fi
+    if printf '%s\n' "$body" >"$tmp" 2>/dev/null && [ -s "$tmp" ]; then
+      written=1
+    fi
+  fi
+  if [ "$written" -eq 0 ]; then
+    rm -f -- "$tmp" 2>/dev/null
+    return 1
+  fi
+  REPLY="$next"
+  return 0
+}
+
+# _work_mesh_live_bump_locked <sid> <path>  (caller holds the lock)
+_work_mesh_live_bump_locked() {
+  local sid="$1" path="$2" tmp seen again
+  tmp="$path.tmp.$$"
+  _work_mesh_live_bump_render "$sid" "$path" "$tmp" || return 1
+  seen="$_WM_SEEN"
+  if [ -n "${WORK_MESH_BUMP_TEST_SLEEP_AFTER_READ:-}" ]; then
+    sleep "$WORK_MESH_BUMP_TEST_SLEEP_AFTER_READ" 2>/dev/null || true
+  fi
+  # Second line of defense: re-read right before mv; if a concurrent writer
+  # (hq-cli reconcile/ack) changed the file since our read, rebuild from it.
+  again=""
+  [ -f "$path" ] && again="$(<"$path")"
+  if [ "$again" != "$seen" ]; then
+    rm -f -- "$tmp" 2>/dev/null
+    _work_mesh_live_bump_render "$sid" "$path" "$tmp" || return 1
+  fi
+  mv -f -- "$tmp" "$path" 2>/dev/null || { rm -f -- "$tmp"; return 1; }
+  chmod 600 -- "$path" 2>/dev/null || true
+  return 0
+}
+
+# work_mesh_live_is_file_write_tool <tool_name> <bash_command?>
+work_mesh_live_is_file_write_tool() {
+  local tool="$1" cmd="${2:-}"
+  case "$tool" in
+    Edit|Write|MultiEdit|NotebookEdit|apply_patch|StrReplace|search_replace|write) return 0 ;;
+    Bash|Shell|run_terminal_command)
+      # Redirect / common file-mutating bash forms (no nested quotes in case arms).
+      case "$cmd" in
+        *\>*|*tee\ *|*mv\ *|*cp\ *|*truncate\ *) return 0 ;;
+        *sed\ -i*|*dd\ if=*) return 0 ;;
+        *) return 1 ;;
+      esac
+      ;;
+    *) return 1 ;;
+  esac
+}