@indigoai-us/hq-cli 5.98.3 → 5.99.1

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

@@ -0,0 +1,251 @@
+#!/usr/bin/env bash
+# hq-core: public
+# hq-session.sh — read/write the current session's metadata.
+#
+# Usage:
+#   core/scripts/hq-session.sh current               # print current session_id (or empty)
+#   core/scripts/hq-session.sh path                  # print path to current meta.yaml
+#   core/scripts/hq-session.sh get <key>             # read a key from meta.yaml
+#   core/scripts/hq-session.sh set <key> <value>     # set/replace a top-level key
+#
+# Reserved value:
+#   set company_slug personal   # bind the session to no-company (personal) work
+#
+# Global option (before the subcommand):
+#   --session-id <id>   operate on this session instead of the resolved one
+#
+# Session bootstrapping is owned by .claude/hooks/master-hook.sh, which
+# writes workspace/sessions/.current and ensures
+# workspace/sessions/<session_id>/meta.yaml exists on every hook event.
+#
+# "Current session" is resolved by core/scripts/lib/session-id.sh: the session id
+# exported into this process wins, and workspace/sessions/.current is only a
+# fallback. .current is a single global pointer rewritten by every hook event, so
+# with concurrent sessions it can name someone else's session — trusting it made
+# `set company_slug` write to the wrong session's meta.yaml while the calling
+# session stayed unbound and blocked by the scope guard.
+
+set -euo pipefail
+
+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,
+# its own location is NOT that tree — the CLI injects the live root via
+# HQ_ROOT / CLAUDE_PROJECT_DIR. Prefer those; fall back to the self-relative
+# root so a loose-file (in-tree) invocation keeps resolving exactly as before.
+REPO_ROOT="${HQ_ROOT:-${CLAUDE_PROJECT_DIR:-$(cd "$SCRIPT_DIR/../.." && pwd)}}"
+SESSIONS_DIR="$REPO_ROOT/workspace/sessions"
+# Libs are sourced from THIS script's own directory, so a bundled dispatch loads
+# the bundled copies and a loose-file invocation loads the tree's copies.
+LIB_DIR="$SCRIPT_DIR/lib"
+# shellcheck source=lib/session-scope-capability.sh
+. "$LIB_DIR/session-scope-capability.sh"
+# shellcheck source=lib/session-id.sh
+. "$LIB_DIR/session-id.sh"
+
+# Set by the --session-id global option; empty means "resolve it".
+SESSION_ID_OVERRIDE=""
+
+usage() {
+  sed -n '2,15p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'
+}
+
+current_id() {
+  if [ -n "$SESSION_ID_OVERRIDE" ]; then
+    printf '%s' "$SESSION_ID_OVERRIDE"
+    return 0
+  fi
+  session_id_resolve "$REPO_ROOT"
+}
+
+current_meta() {
+  local id
+  id="$(current_id)"
+  [ -n "$id" ] || return 0
+  printf '%s/%s/meta.yaml' "$SESSIONS_DIR" "$id"
+}
+
+cmd_current() {
+  current_id
+}
+
+cmd_path() {
+  current_meta
+}
+
+cmd_get() {
+  local key="${1:-}"
+  [ -n "$key" ] || { echo "usage: hq-session.sh get <key>" >&2; exit 1; }
+  local meta
+  meta="$(current_meta)"
+  [ -n "$meta" ] && [ -f "$meta" ] || return 0
+  awk -v k="$key" '
+    $1 == k":" {
+      sub(/^[^:]+:[[:space:]]*/, "")
+      gsub(/^"|"$/, "")
+      print
+      exit
+    }
+  ' "$meta"
+}
+
+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.
+  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
+        exit 1
+        ;;
+    esac
+  fi
+
+  local id meta
+  id="$(current_id)"
+  if [ -z "$id" ]; then
+    echo "hq-session: no current session — no session id in the environment (HQ_SESSION_ID, CLAUDE_CODE_SESSION_ID, CLAUDE_SESSION_ID, CODEX_SESSION_ID, CODEX_THREAD_ID) and workspace/sessions/.current is missing or invalid. Is master-hook installed? Pass --session-id <id> to target a session explicitly." >&2
+    exit 1
+  fi
+  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.
+  if [ ! -f "$meta" ]; then
+    printf 'session_id: %s\nstarted_at: "%s"\n' \
+      "$id" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" > "$meta"
+  fi
+
+  # Capture the prior value so we only surface policies when it actually changes.
+  local prev=""
+  prev="$(cmd_get "$key" 2>/dev/null || true)"
+
+  local tmp
+  tmp="$(mktemp)"
+  awk -v k="$key" -v v="$value" '
+    BEGIN { found = 0 }
+    $1 == k":" { print k": " v; found = 1; next }
+    { print }
+    END { if (!found) print k": " v }
+  ' "$meta" > "$tmp"
+  mv "$tmp" "$meta"
+
+  # When a company is bound (or rebound) mid-session, surface that company's
+  # hard-enforcement policies into this Bash tool result. SessionStart only
+  # injects company policies for the company known *at start*; binding a
+  # company afterward (this path) otherwise surfaces nothing, so an agent can
+  # do company infra/deploy/credential work blind to hard rules. This closes
+  # that gap. Emits policy text only — never secrets.
+  if [ "$key" = "company_slug" ] && [ -n "$value" ] && [ "$value" != "$prev" ]; then
+    session_scope_mint "$REPO_ROOT" "$id" "$value" || {
+      echo "hq-session: failed to mint scope-capability for session $id" >&2
+      exit 1
+    }
+    # `personal` is the reserved scope for work that belongs to no company. It
+    # binds the session — satisfying the checkpoint company gate and scoping the
+    # authorizer to personal/ — but it has no tenant directory, so there are no
+    # company hard-policies to surface and nothing to register with the
+    # company-scoped Work Mesh. Everything else is a real company bind.
+    if [ "$value" != "personal" ]; then
+      emit_company_hard_policies "$value"
+      # Fire-and-forget: register this company bind with the Work Mesh (US-003).
+      # Fully silent (all output → the hook's own bounded log) and guarded so it
+      # can neither fail cmd_set under `set -euo pipefail` nor delay its return.
+      spawn_work_mesh_register "$id" || true
+    fi
+  fi
+}
+
+# Spawn the client-side Work Mesh registration hook, detached, for a mid-session
+# company bind. No-ops silently when the hook or jq is absent (e.g. sandboxed
+# tests copy only hq-session.sh). Never blocks: the hook itself is fire-and-forget
+# 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 logf="$REPO_ROOT/workspace/logs/work-mesh-hook.log"
+  [ -x "$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" \
+    >>"$logf" 2>&1 </dev/null &
+  disown 2>/dev/null || true
+  return 0
+}
+
+# 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.
+emit_company_hard_policies() {
+  local co="$1"
+  local dir="$REPO_ROOT/companies/$co/policies"
+  [ -d "$dir" ] || return 0
+  # Guard the glob: with no matching files "$dir"/*.md expands literally, awk
+  # exits nonzero, and under `set -e` that would abort an otherwise fine bind.
+  local have=0 f
+  for f in "$dir"/*.md; do
+    [ -e "$f" ] && { have=1; break; }
+  done
+  [ "$have" = 1 ] || return 0
+  local lines
+  lines="$(awk '
+    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 } }
+    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>=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 }
+    END { if(seen) flush() }
+  ' "$dir"/*.md 2>/dev/null)"
+  [ -z "$lines" ] && return 0
+  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 '%s\n' "$lines"
+  printf '</company-policy-digest>\n'
+}
+
+while [ $# -gt 0 ]; do
+  case "${1:-}" in
+    --session-id)
+      SESSION_ID_OVERRIDE="${2:-}"
+      if ! session_id_is_valid "$SESSION_ID_OVERRIDE"; then
+        echo "hq-session: invalid --session-id: '${SESSION_ID_OVERRIDE}'" >&2
+        exit 1
+      fi
+      shift 2
+      ;;
+    --session-id=*)
+      SESSION_ID_OVERRIDE="${1#--session-id=}"
+      if ! session_id_is_valid "$SESSION_ID_OVERRIDE"; then
+        echo "hq-session: invalid --session-id: '${SESSION_ID_OVERRIDE}'" >&2
+        exit 1
+      fi
+      shift
+      ;;
+    *) break ;;
+  esac
+done
+
+sub="${1:-}"
+shift || true
+case "$sub" in
+  current) cmd_current "$@" ;;
+  path)    cmd_path "$@" ;;
+  get)     cmd_get "$@" ;;
+  set)     cmd_set "$@" ;;
+  ""|-h|--help|help) usage ;;
+  *) echo "hq-session: unknown subcommand '$sub'" >&2; usage >&2; exit 1 ;;
+esac

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

@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+# hq-core: public
+# session-id.sh — resolve the session id the CURRENT process belongs to.
+#
+# Sourced by core/scripts/hq-session.sh and .claude/hooks/mandatory-scope-authorizer.sh.
+# Never execute directly.
+#
+# WHY THIS EXISTS
+#
+# workspace/sessions/.current is a single, global, last-writer-wins pointer
+# maintained by .claude/hooks/master-hook.sh: every hook event overwrites it with
+# the session id from that event's payload. With two sessions alive at once — an
+# interactive session plus a scheduled/agent run, or two terminals — .current
+# names whichever session fired a hook most recently, NOT the session the running
+# command belongs to.
+#
+# That matters because the enforcement side does not use .current. The scope
+# guard (.claude/hooks/mandatory-scope-authorizer.sh) reads the authoritative
+# session id out of the hook payload. So a helper that resolved "this session"
+# through .current could write company_slug into a DIFFERENT session's record,
+# report success, and leave the calling session unbound — the guard keeps
+# blocking, and a foreign session silently acquires a company binding it never
+# asked for.
+#
+# The session id is also exported into every child process by the host, so an
+# environment variable always describes the session that spawned this command.
+# Prefer it, and keep .current only as a fallback for invocations that have no
+# session environment at all (cron, CI, a bare shell).
+#
+# RESOLUTION ORDER (first syntactically valid, non-empty value wins)
+#   1. HQ_SESSION_ID           — explicit caller/test override
+#   2. CLAUDE_CODE_SESSION_ID  — Claude Code CLI and app
+#   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
+#
+# The env precedence list matches .claude/skills/_shared/journal.sh so every
+# per-session artifact (journal, session meta, scope capability) keys off the
+# same identity.
+
+# session_id_is_valid <id>
+#   Session ids become a path segment under workspace/sessions/, so restrict them
+#   to a conservative charset and reject the traversal spellings outright.
+session_id_is_valid() {
+  local id="${1:-}"
+  [ -n "$id" ] || return 1
+  case "$id" in
+    .|..) return 1 ;;
+    *[!A-Za-z0-9._-]*) return 1 ;;
+  esac
+  return 0
+}
+
+# session_id_from_env
+#   Print the first valid session id found in the environment, or nothing.
+#   An unset, empty, or malformed variable is skipped rather than fatal, so a
+#   stray value in one host cannot wedge every helper.
+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
+    val="${!var:-}"
+    val="$(printf '%s' "$val" | tr -d '[:space:]')"
+    if session_id_is_valid "$val"; then
+      printf '%s' "$val"
+      return 0
+    fi
+  done
+  return 0
+}
+
+# session_id_from_current_file <root>
+#   Print the id in workspace/sessions/.current, or nothing when absent/invalid.
+session_id_from_current_file() {
+  local root="${1:-}" file val
+  [ -n "$root" ] || return 0
+  file="$root/workspace/sessions/.current"
+  [ -f "$file" ] || return 0
+  val="$(tr -d '[:space:]' < "$file" 2>/dev/null || true)"
+  session_id_is_valid "$val" && printf '%s' "$val"
+  return 0
+}
+
+# session_id_resolve <root>
+#   Print this process's session id: environment first, .current as fallback.
+#   Prints nothing (exit 0) when neither source yields a valid id — callers that
+#   need one must fail loudly themselves.
+session_id_resolve() {
+  local root="${1:-}" id
+  id="$(session_id_from_env)"
+  if [ -z "$id" ]; then
+    id="$(session_id_from_current_file "$root")"
+  fi
+  printf '%s' "$id"
+}

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

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+# hq-core: public
+# session-scope-capability.sh — mint/read workspace/sessions/<id>/scope-capability.json
+#
+# Sourced by core/scripts/hq-session.sh and .claude/hooks/mandatory-scope-authorizer.sh.
+# Never execute directly.
+
+# session_scope_capability_path <root> <session_id>
+#   Print the absolute path to scope-capability.json for a session.
+session_scope_capability_path() {
+  local root="${1:-}" sid="${2:-}"
+  [ -n "$root" ] && [ -n "$sid" ] || return 1
+  printf '%s/workspace/sessions/%s/scope-capability.json' "$root" "$sid"
+}
+
+# session_scope_read <root> <session_id>
+#   Print company_slug from scope-capability.json, or empty when absent/invalid.
+session_scope_read() {
+  local root="${1:-}" sid="${2:-}" cap
+  cap="$(session_scope_capability_path "$root" "$sid")" || return 0
+  [ -f "$cap" ] || return 0
+  jq -r '.company_slug // empty' "$cap" 2>/dev/null || true
+}
+
+# session_scope_mint <root> <session_id> <company_slug>
+#   Write scope-capability.json for the session. Returns 0 on success.
+session_scope_mint() {
+  local root="${1:-}" sid="${2:-}" slug="${3:-}"
+  [ -n "$root" ] && [ -n "$sid" ] && [ -n "$slug" ] || return 1
+
+  case "$slug" in
+    ''|*[!a-z0-9_-]*)
+      echo "session-scope-capability: invalid company_slug: $slug" >&2
+      return 1
+      ;;
+  esac
+
+  local cap dir tmp minted_at
+  cap="$(session_scope_capability_path "$root" "$sid")" || return 1
+  dir="$(dirname "$cap")"
+  mkdir -p "$dir" || return 1
+
+  minted_at="$(date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -u +%Y-%m-%dT%H:%M:%S'Z')"
+  tmp="$(mktemp)"
+  jq -n \
+    --arg sid "$sid" \
+    --arg slug "$slug" \
+    --arg minted_at "$minted_at" \
+    '{session_id: $sid, company_slug: $slug, minted_at: $minted_at}' >"$tmp" \
+    || { rm -f "$tmp"; return 1; }
+  mv "$tmp" "$cap"
+}

package/dist/commands/core-checkpoint.js

@@ -552,7 +552,7 @@ export function siblingArgs(backend, prompt) {
                 // journal helper, the queue-draining `mv` — hits an approval gate with
                 // no human attached; headless `claude -p` then denies it and the run
                 // stalls having written no report. `bypassPermissions` is the same
-                // unattended posture codex gets from `-s workspace-write` and grok from
+                // unattended posture codex gets from `-s danger-full-access` and grok from
                 // `--always-approve --sandbox workspace`. Hooks still fire natively —
                 // this only removes the interactive approval gate, not the hook chain.
                 "--permission-mode",
@@ -570,7 +570,7 @@ export function siblingArgs(backend, prompt) {
                 // scan, the journal helper — then hits an approval gate with no human
                 // attached, and grok cancels the whole run: `stopReason: cancelled,
                 // cancellationCategory: PermissionCancelled`. Unattended approval plus
-                // a sandbox is the same posture codex gets from `-s workspace-write`.
+                // a sandbox is the same posture codex gets from `-s danger-full-access`.
                 "--always-approve",
                 "--sandbox",
                 "workspace",
@@ -581,8 +581,16 @@ export function siblingArgs(backend, prompt) {
             return [
                 "exec",
                 "--skip-git-repo-check",
+                // danger-full-access, NOT workspace-write. `-s workspace-write` force-
+                // enables Codex's restrictive sandbox, which denies the temp/cache/socket
+                // writes the maintenance sibling needs on macOS (git/Xcode cache, zsh/asdf
+                // heredocs) and cannot even initialize bubblewrap on some Linux hosts
+                // (`bwrap: loopback: Failed RTM_NEWADDR`) — HQ harness finding 2.3, which
+                // wedged the sibling before it wrote any report. HQ's safety boundary is
+                // its hooks, which still fire here via --dangerously-bypass-hook-trust;
+                // the sandbox is not what guards the HQ root.
                 "-s",
-                "workspace-write",
+                "danger-full-access",
                 "--dangerously-bypass-hook-trust",
                 "-m",
                 CODEX_SIBLING_MODEL,

package/dist/commands/core.js

@@ -44,6 +44,8 @@ import { createWorktree } from "../lib/core-utils/worktree.js";
 import { runCodexSkillBridgeCommand } from "../lib/core-utils/codex-skill-bridge-entry.js";
 import { archiveOldThreads } from "../lib/core-utils/archive-old-threads.js";
 import { qmdReindexAfterSync } from "../lib/core-utils/qmd-reindex-after-sync.js";
+import { softTimeoutCommand } from "../lib/core-utils/soft-timeout.js";
+import { timeoutGuardCommand } from "../lib/core-utils/timeout-guard.js";
 /**
  * These commands are now native implementations. Their retained shell assets
  * are deliberately claimed in SCAFFOLD_ONLY_ASSETS: loose HQ trees still ship
@@ -164,11 +166,24 @@ export const REBUILD_INDEX_TARGETS = [
  * would make the forwarders harder to audit against this table.
  */
 export const SCAFFOLD_COMMANDS = [
-// Empty by design. Every former entry is either native now or retired: the
-// two one-shot backfills (company skill mirrors, workspace mirror) were
-// removed outright, having served installs that predate the current layout.
-// `hq core worker lint|share` are the only remaining bundled dispatches and
-// live in WORKER_SUBCOMMANDS.
+    // Session/harness plumbing relocated out of the HQ tree so a single published
+    // CLI owns it. Both are `root: "live"`: they read and write the live HQ tree
+    // (workspace/sessions, companies/, workspace/orchestrator/hook-state), so the
+    // CLI resolves and injects the live root, exactly as their in-tree originals
+    // derived it. Their loose-file copies remain as thin fallbacks for a tree
+    // whose installed CLI predates this command.
+    {
+        name: "checkpoint-stop-gate",
+        asset: "core/scripts/checkpoint-stop-gate.sh",
+        root: "live",
+        summary: "Stop-hook checkpoint + company-scope gate (reads the hook payload on stdin)",
+    },
+    {
+        name: "hq-session",
+        asset: "core/scripts/hq-session.sh",
+        root: "live",
+        summary: "Read/write the current session's meta.yaml (get/set/current/path)",
+    },
 ];
 /**
  * Bundled solely for HQ-root scaffolds, which still need these as loose files.
@@ -176,6 +191,13 @@ export const SCAFFOLD_COMMANDS = [
  * direct `hq core` command.
  */
 export const SCAFFOLD_ONLY_ASSETS = [
+    // Shared shell libs sourced by the two relocated scripts. Never dispatched on
+    // their own (so no `hq core` command), but they MUST ship in the tarball, or
+    // the bundled hq-session / checkpoint-stop-gate die at `source` time on a
+    // user's box. `root` is inert here — they are sourced, not run.
+    { asset: "core/scripts/hook-lib.sh", root: "live", summary: "Shared shell primitives sourced by the checkpoint gate" },
+    { asset: "core/scripts/lib/session-scope-capability.sh", root: "live", summary: "Session scope-capability lib sourced by hq-session" },
+    { asset: "core/scripts/lib/session-id.sh", root: "live", summary: "Session-id resolver lib sourced by hq-session" },
     { asset: "core/scripts/archive-old-threads.sh", root: "live", summary: "Scaffold-only native utility companion" },
     { asset: "core/scripts/codex-skill-bridge.sh", root: "live", summary: "Scaffold-only native utility companion" },
     { asset: "core/scripts/qmd-reindex-after-sync.sh", root: "cwd", summary: "Scaffold-only native utility companion" },
@@ -401,6 +423,39 @@ export function registerCoreCommands(program) {
             runCommand(entry, args, cmd);
         });
     }
+    // `hq core soft-timeout <interval> [--hard-cap <spec>] [--label <name>] -- <cmd…>`
+    // Async and bespoke (the NATIVE_UTILITY_COMMANDS table is synchronous), since
+    // it spawns a child and warns over time. Warn-don't-kill primitive for
+    // finding 2.1 — the CLI-hosted twin of core/scripts/lib/soft-timeout.sh.
+    core
+        .command("soft-timeout")
+        .description("Run a command under a soft (warn, don't kill) timeout")
+        // Passthrough: the wrapped command owns everything after `--`.
+        .allowUnknownOption()
+        .allowExcessArguments()
+        .helpOption(false)
+        .argument("[args...]", "<interval> [--hard-cap <spec>] [--label <name>] -- <cmd...>")
+        .action(async (args = [], _opts, cmd) => {
+        const operands = cmd.args.length > 0 ? cmd.args : args;
+        const code = await softTimeoutCommand(operands);
+        if (code !== 0)
+            process.exit(code);
+    });
+    // `hq core timeout-guard` — PreToolUse decision for the foreground-timeout
+    // guard (finding 2.1). Reads the hook JSON on stdin and exits 2 to block, 0
+    // to allow. The shipped .claude hook is a thin shim over this.
+    core
+        .command("timeout-guard")
+        .description("PreToolUse guard: block over-ceiling foreground timeouts (reads hook JSON on stdin)")
+        .helpOption(false)
+        .action(async () => {
+        const chunks = [];
+        for await (const chunk of process.stdin)
+            chunks.push(chunk);
+        const code = timeoutGuardCommand(Buffer.concat(chunks).toString("utf8"));
+        if (code !== 0)
+            process.exit(code);
+    });
     return core;
 }
 //# sourceMappingURL=core.js.map

package/dist/commands/doctor.d.ts

@@ -0,0 +1,97 @@
+/**
+ * `hq doctor` — verify HQ's hook guardrails are wired and firing.
+ *
+ * US-002 builds the command skeleton and the extensible check registry:
+ *   - HQ root resolution walks up from the working directory looking for the
+ *     marker directories that identify an HQ tree, and exposes the resolved root
+ *     to every check.
+ *   - Running outside any HQ tree exits non-zero with a message naming exactly
+ *     what it looked for — never a throw, never a false PASS.
+ *   - The command performs no network calls and needs no authentication; it is
+ *     purely a function of the on-disk shape of the tree.
+ *
+ * US-015 adds reporting, `--json`, and the exit-code contract: the exit code is
+ * 0 unless some result is FAIL or UNKNOWN (WARN/UNTESTED/NA/KNOWN-DEFECT never
+ * fail); `--verbose` also prints PASS results; `--json` emits the versioned,
+ * machine-readable document; and text output carries no ANSI when stdout is not
+ * a TTY. The rendering and contract live in ../lib/doctor/report.ts and
+ * ../lib/doctor/json-output.ts; this command wires them to the CLI.
+ *
+ * The detected platform is a placeholder (UNKNOWN_PLATFORM) until host platform
+ * detection (US-003) lands and injects the real value through `platform`.
+ */
+import { Command } from "commander";
+import { type DoctorRegistry } from "../lib/doctor/registry.js";
+import type { FamilyRun } from "../lib/doctor/types.js";
+import { type DoctorPlatform } from "../lib/doctor/report.js";
+/**
+ * Marker directories that identify an HQ tree root. A directory is an HQ root
+ * only when it contains ALL of these. `.claude` + `core` are present in both
+ * the real HQ tree and the synthetic fixture trees the doctor is tested
+ * against, and are absent from an arbitrary directory — so requiring both
+ * avoids a false positive on a random repo that merely carries a `.claude/`
+ * folder.
+ */
+export declare const HQ_ROOT_MARKERS: readonly [".claude", "core"];
+/**
+ * Walk up from `startDir` (default: the current working directory) looking for
+ * the nearest ancestor that contains every {@link HQ_ROOT_MARKERS} entry as a
+ * directory. Returns the resolved (realpath'd) root, or `null` when no ancestor
+ * qualifies — i.e. the caller is not inside an HQ tree.
+ */
+export declare function resolveHqRoot(startDir?: string): string | null;
+/** Options for {@link runDoctor}. All are injectable so the run is unit-testable. */
+export interface RunDoctorOptions {
+    /** Directory to resolve the HQ root from. Default: `process.cwd()`. */
+    cwd?: string;
+    /** Explicit HQ root, bypassing resolution. Takes precedence over `cwd`. */
+    root?: string;
+    /** Registry to run. Default: {@link createDefaultRegistry}. */
+    registry?: DoctorRegistry;
+    /** stdout sink. Default: `process.stdout.write`. */
+    stdout?: (chunk: string) => void;
+    /** stderr sink. Default: `process.stderr.write`. */
+    stderr?: (chunk: string) => void;
+    /** Emit the machine-readable JSON document instead of text. Default: false. */
+    json?: boolean;
+    /** In text mode, also print every PASS result. Default: false. */
+    verbose?: boolean;
+    /** In text mode, emit ANSI colour. Default: false (no escape sequences). */
+    color?: boolean;
+    /**
+     * The detected platform. Defaults to {@link UNKNOWN_PLATFORM}; host platform
+     * detection (US-003) injects the real value here. It is exposed to every check
+     * so host-specific checks (the US-006 runtime probe) can key off it.
+     */
+    platform?: DoctorPlatform;
+    /**
+     * Session id to scope the runtime probe's ledger check to (US-006
+     * `--session-id`), so an older session's ledger cannot be mistaken for the
+     * current runtime.
+     */
+    sessionId?: string;
+    /**
+     * Additionally execute pure-guard fixtures through the real gate under all
+     * three profiles, in a sandbox (US-008 `--deep-test`). Off by default: the
+     * default registry never fires a hook, and this branch is the ONLY path that
+     * does — so a plain `hq doctor` stays purely a function of the on-disk shape.
+     */
+    deepTest?: boolean;
+}
+/** The outcome of a doctor run, returned rather than thrown so it is testable. */
+export interface RunDoctorResult {
+    /** Process exit code: 0 inside a tree, 1 when no HQ tree was found. */
+    exitCode: number;
+    /** The resolved HQ root, or null when resolution failed. */
+    hqRoot: string | null;
+    /** Grouped per-family results (empty when resolution failed). */
+    families: FamilyRun[];
+}
+/**
+ * Resolve the HQ root, run every registered check family against it, and render
+ * a plain-text summary. Makes no network calls and needs no authentication.
+ */
+export declare function runDoctor(options?: RunDoctorOptions): Promise<RunDoctorResult>;
+/** Register the top-level `hq doctor` command so it appears in `hq --help`. */
+export declare function registerDoctorCommand(program: Command): void;
+//# sourceMappingURL=doctor.d.ts.map