@indigoai-us/hq-cli 5.275.0 → 5.277.0

package/CHANGELOG.md

@@ -2,6 +2,113 @@
 
 ## [Unreleased]
 
+## [5.277.0] — 2026-09-29
+
+### Fixed
+
+- `hq lanes accounts list` and `accounts balance` now report a Claude account
+  whose home is missing on the current host and show the `set-home` repair
+  command. Balance exits non-zero for an enabled account in that state. On
+  Linux, account login stores a host-specific home and requires `--home` when
+  an existing account only has a shared home.
+- Claude account balancing can use the default-off
+  `lanes.claude-account-balance-signals` hq-flags key to break equal live-lane
+  counts by the age of each account's latest completed lane run when provider
+  percentage data is unavailable.
+
+### Added
+
+- Add a default-off `cli.secrets-env-fast-path` hq-flags route for `hq secrets
+  env`. It skips the full CLI graph while reusing the existing credential,
+  usage-audit, server authorization, and offline-cache behavior.
+- `hq lanes list --json` accepts repeatable `--lane` filters, `--active`, and
+  owner-only hire-hierarchy snapshots. Remote lane lookup now requests the
+  needed hierarchy once per Outpost invocation and falls back to an unfiltered
+  list when an older owner CLI rejects a new filter. Internal snapshot switches
+  stay out of normal help and the generated command catalog.
+- Add the default-off `checkpoint.ontology.dominant-sibling-link` hq-flags key.
+  When it is on, checkpoint ontology apply moves a knowledge link from an entity
+  whose name another type also holds to the same-name entity that other entity
+  files link to most. The move needs at least three times the inbound links and
+  at least five. An example is project Build Your Own AGI moving to the concept,
+  or the numbered copy `hq-core 2` moving to `hq-core`. Moves are reported
+  under `dominant_sibling_redirects`, and no entity file is written.
+- Add the default-off `lanes.running-superseded-message-delivery` hq-flags key
+  so messages can reach otherwise messageable superseded lanes outside the done
+  and interrupted states. Accepted messages include a warning; done and
+  interrupted lanes keep the existing senior and successor checks.
+- `hq core delegate resolve`, `pickup`, `repo`, `secrets`, and `transfer` are
+  available through native implementations when the default-off
+  `core-native-delegate` flag is enabled; the bundled scripts remain as the
+  rollback path.
+
+- `hq lanes set <lane> --model <model> --effort <level> [--reason <text>]`
+  changes the model or effort a lane uses from its next resume, including the
+  keep-alive resume of a done lead. Before, keep-alive always resumed on the
+  recorded values, so a lead's model could not change without racing it. The
+  lane itself or its senior may run it; each change is kept in
+  `settings_history` and shown by `hq lanes show`.
+- `hq daemon sync` reports runner ownership and health, starts an immediate sync pass, pauses or resumes sync, and sets per-company sync mode. The daemon waits for an existing desktop runner to release its lease before starting its own.
+- `hq lanes interrupt <lane-id>` stops a running lane's turn and leaves it
+  `interrupted` (reason `operator_interrupt`) with its provider session, so
+  `hq lanes resume` continues it. Keep-alive does not resume it. The command
+  records the session id from the interrupted turn's output, holds the
+  provider's admission lock until the worker has stopped, and reports
+  `resumable: false` with a stderr warning when the turn produced no session id.
+- An operator `hq lanes resume` clears keep-alive's `terminal_state` block, so
+  keep-alive can continue the lane after that turn.
+
+### Changed
+
+- `hq lanes stop` on a running lane warns on stderr that the lane is killed and
+  cannot be resumed, names `hq lanes interrupt`, and adds `terminal: true` and
+  `resumable: false` to its JSON output, including for Outpost lanes stopped
+  from the primary.
+- The lane drain hook avoids loading the lanes module graph when no lane is
+  resolved or its drop box is empty, while continuing to record tool activity
+  and using the full drain path whenever delivery or replay may be needed.
+
+### Fixed
+
+- Doctor command tests use temporary home and state directories and skip the
+  live integrations inventory, so their results do not depend on a developer's
+  local HQ state.
+- Outpost resume account moves forward the primary's hire-grant context through
+  the owner-side session move. The owner checks the current senior and hire
+  capacity before starting the worker.
+- Security: `hq dm inbox --json` and agent-side raw message output omit the delegated `actingContext` object.
+
+## [5.276.0] — 2026-09-28
+
+### Added
+
+- Suggest inviting a teammate after the billing link in an over-limit Starter
+  notice for a one-member company, behind the default-off
+  `cli.limit-invite-teammate-v1` flag.
+- Add a default-off native route for `hq core timeout-guard`, backed by a
+  private company flag snapshot and a paired CI latency benchmark.
+
+### Changed
+
+- Starter setup guidance now says it includes one integration.
+
+### Fixed
+
+- `hq core checkpoint` no longer loses the company files of a checkpoint that
+  was queued behind a busy sibling, behind the `checkpoint.ontology.queued-touches`
+  flag (off by default). The queued checkpoint records its company files, and
+  the next sibling run adds them to the ontology plan. A run whose own
+  checkpoint names no company takes the ontology step for the company whose
+  files have waited longest.
+- `hq feedback bug|feature` validates report content and the serialized request
+  size before uploading screenshots or logs, avoiding orphaned attachments when
+  the server would reject the submission.
+
+- Reconcile clears a stale `superseded` keep-alive block when no active successor
+  remains; the five-minute minimum retry delay still applies. The block is
+  cleared even when the lead then waits on backoff or a full queue, and the
+  clear does not move a done lead's retry clock past its done envelope.
+
 ## [5.275.0] — 2026-09-28
 
 ### Fixed
@@ -13,6 +120,9 @@
 
 ### Added
 
+- Track CLI feature events behind the default-off `cli.feature-used-telemetry-v1`
+  hq-flags key with a separate one-time disclosure.
+
 - Outpost daemons can take over running services after a CLI update instead
   of restarting all of them, behind the `daemon.supervisor-handoff` flag (off
   by default). On Linux, the updated daemon adopts the services the previous
@@ -45,6 +155,8 @@
   `outpost_self_target`.
 - `hq sync status` validates an explicit `--hq-root` and continues to read
   journals from the configured state directory, which it now prints.
+- Root daemon tests use a temporary system adopted-record file; the CLI still
+  defaults to `/var/lib/hq/daemon/adopted.json`.
 
 ## [5.274.1] — 2026-09-28
 

package/README.md

@@ -47,6 +47,18 @@ plane can accept the event. The body does not include command names, arguments,
 timings, file contents, or secrets. The guidance fields are sent only when that
 optional feature is enabled and a person sees or follows its next step.
 
+When the default-off hq-flags key `cli.feature-used-telemetry-v1` is enabled,
+the CLI sends `cli_feature_used` for supported secret reads (`hq secrets exec`
+and `hq run`) and lane create and resume actions. Each event carries
+`properties.kind` and `properties.outcome` (`success` or `failure`). Events also
+carry the authenticated company UID when available. hq-pro resolves the signed-in
+identity. Events omit command names and arguments, secret names and values,
+prompt text, file paths, and command lines. User hooks and skills run in the
+provider host, which hq-cli cannot see. The default signed-in notice above is
+unchanged. On interactive TTY runs, the first enabled feature event has a
+separate one-time notice naming the feature kind, outcome, and company UID
+when available.
+
 The first signed-in interactive run (stdout is a TTY, and the command is not
 `--json`) prints this line once on stderr and records that it was shown under
 `~/.hq/cli-telemetry-disclosed`:

package/assets/bot-workers/setup/context/USER-GUIDE.md

@@ -323,10 +323,10 @@ HQ/
 HQ has three plans: **Starter**, **HQ Workforce** ($500/month per workspace), and
 **Enterprise**.
 
-Starter is free. It holds up to 5 members, and it does not include integrations
-or MCP, Atlas, or telemetry. Everything else — knowledge, projects, policies,
-workers, secrets, vault storage, `hq deploy`, and `hq share` — works the same as
-on the paid plans.
+Starter is free. It holds up to 5 members and includes 1 integration. MCP,
+Atlas, and telemetry are not included. Everything else — knowledge, projects,
+policies, workers, secrets, vault storage, `hq deploy`, and `hq share` — works
+the same as on the paid plans.
 
 ### When a workspace goes over
 

package/assets/scaffold/core/scripts/hq-delegate-pickup.sh

@@ -0,0 +1,99 @@
+#!/usr/bin/env bash
+# hq-core: public
+# hq-delegate-pickup.sh — close the delegation loop with a receipt or a FAILED
+# state (2026-09-07).
+#
+# Why: the delegate pipeline ended at "sent", which is a send receipt, not a
+# delivery receipt. Seven delegations sat at sent/building with no way to tell
+# whether the recipient could act. This script adds the two missing states:
+#
+#   sent --(evidence)--> picked-up      recipient demonstrably has the work
+#   sent --(silence past window)--> failed   nobody picked it up; sender is told why
+#
+# Evidence, checked in order (any one suffices):
+#   1. --ack "<text>"            an explicit acknowledgement (DM reply, chat) —
+#                                recorded verbatim with a timestamp
+#   2. repo branch has a commit by the recipient after sentAt
+#      (manifest.repo.path + repo.branch, author email == to.principal)
+#   3. --evidence "<free text>"  any other proof the operator observed
+#
+# Usage:
+#   hq-delegate-pickup.sh --manifest <path> --ack "<text>"        # record receipt
+#   hq-delegate-pickup.sh --manifest <path> --evidence "<text>"   # record receipt
+#   hq-delegate-pickup.sh --manifest <path> --check [--window-hours N]   # probe repo; fail if silent past window (default 72)
+#   hq-delegate-pickup.sh --manifest <path> --status               # print state line
+#
+# Exit 0: picked-up (or already). Exit 5: failed (window elapsed, no evidence).
+# Exit 6: still waiting (inside window, no evidence). Exit 2: usage/precondition.
+set -uo pipefail
+MANIFEST=""; ACK=""; EVIDENCE=""; CHECK=0; STATUS_ONLY=0; WINDOW="${HQ_DELEGATE_PICKUP_WINDOW_HOURS:-72}"
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --manifest) MANIFEST="$2"; shift 2 ;;
+    --ack) ACK="$2"; shift 2 ;;
+    --evidence) EVIDENCE="$2"; shift 2 ;;
+    --check) CHECK=1; shift ;;
+    --window-hours) WINDOW="$2"; shift 2 ;;
+    --status) STATUS_ONLY=1; shift ;;
+    -h|--help) sed -n 2,28p "$0"; exit 0 ;;
+    *) echo "hq-delegate-pickup: unknown arg $1" >&2; exit 2 ;;
+  esac
+done
+[ -n "$MANIFEST" ] && [ -r "$MANIFEST" ] || { echo "usage: --manifest <path> (--ack|--evidence|--check|--status)" >&2; exit 2; }
+command -v jq >/dev/null 2>&1 || { echo "hq-delegate-pickup: jq required" >&2; exit 2; }
+NOW="${HQ_DELEGATE_NOW:-$(date -u +%Y-%m-%dT%H:%M:%SZ)}"
+STATUS="$(jq -r '.status // empty' "$MANIFEST")"
+SENT_AT="$(jq -r '.sentAt // empty' "$MANIFEST")"
+TO="$(jq -r '.to.principal // empty' "$MANIFEST")"
+NAME="$(jq -r '.to.displayName // .to.principal // "the recipient"' "$MANIFEST")"
+
+if [ "$STATUS_ONLY" = 1 ]; then
+  jq -r '"\(.delegationId) \(.status)" + (if .pickedUpAt then " picked-up " + .pickedUpAt + " via " + (.pickup.kind // "?") else "" end) + (if .failedAt then " failed " + .failedAt + ": " + (.failure.reason // "") else "" end)' "$MANIFEST"
+  exit 0
+fi
+case "$STATUS" in
+  picked-up) echo "hq-delegate-pickup: already picked up ($(jq -r '.pickedUpAt' "$MANIFEST"))"; exit 0 ;;
+  failed) echo "hq-delegate-pickup: already failed ($(jq -r '.failure.reason // ""' "$MANIFEST"))"; exit 5 ;;
+  sent) ;;
+  *) echo "hq-delegate-pickup: manifest status is '$STATUS' — only a 'sent' delegation can be picked up (send it first)" >&2; exit 2 ;;
+esac
+
+record_pickup() { # <kind> <detail>
+  jq --arg now "$NOW" --arg k "$1" --arg d "$2" \
+    '.status = "picked-up" | .pickedUpAt = $now | .pickup = {kind: $k, detail: $d, recordedAt: $now}' \
+    "$MANIFEST" > "$MANIFEST.tmp" && mv "$MANIFEST.tmp" "$MANIFEST"
+  echo "hq-delegate-pickup: $NAME picked up the delegation ($1) — status advanced to 'picked-up'"
+  exit 0
+}
+[ -n "$ACK" ] && record_pickup ack "$ACK"
+[ -n "$EVIDENCE" ] && record_pickup evidence "$EVIDENCE"
+
+[ "$CHECK" = 1 ] || { echo "hq-delegate-pickup: nothing to do (pass --ack, --evidence, --check, or --status)" >&2; exit 2; }
+
+# Evidence 2: a commit by the recipient on the handed-over branch after sentAt.
+REPO="$(jq -r '.repo.path // empty' "$MANIFEST")"
+BRANCH="$(jq -r '.repo.branch // empty' "$MANIFEST")"
+if [ -n "$REPO" ] && [ -d "$REPO" ] && [ -n "$BRANCH" ] && [ -n "$TO" ]; then
+  git -C "$REPO" fetch -q origin "$BRANCH" 2>/dev/null || true
+  ref="origin/$BRANCH"; git -C "$REPO" show-ref --verify --quiet "refs/remotes/$ref" || ref="$BRANCH"
+  c="$(git -C "$REPO" log "$ref" --author="$TO" ${SENT_AT:+--since="$SENT_AT"} --format='%h %ad %s' --date=short -1 2>/dev/null || true)"
+  [ -n "$c" ] && record_pickup commit "$c on $BRANCH"
+fi
+
+# No evidence. Inside the window: waiting. Past it: FAILED, with the reason.
+if [ -n "$SENT_AT" ]; then
+  sent_epoch="$(date -u -d "$SENT_AT" +%s 2>/dev/null || date -u -j -f %Y-%m-%dT%H:%M:%SZ "$SENT_AT" +%s 2>/dev/null || echo 0)"
+  now_epoch="$(date -u -d "$NOW" +%s 2>/dev/null || date -u -j -f %Y-%m-%dT%H:%M:%SZ "$NOW" +%s 2>/dev/null || date +%s)"
+  age_h=$(( (now_epoch - sent_epoch) / 3600 ))
+else
+  age_h=0
+fi
+if [ "$age_h" -lt "$WINDOW" ]; then
+  echo "hq-delegate-pickup: waiting — no pickup evidence from $NAME yet (${age_h}h of a ${WINDOW}h window)"
+  exit 6
+fi
+reason="no pickup evidence from $NAME within ${WINDOW}h of send (${SENT_AT:-unknown}): no acknowledgement, no commit by $TO on ${BRANCH:-the branch}"
+jq --arg now "$NOW" --arg r "$reason" '.status = "failed" | .failedAt = $now | .failure = {reason: $r, recordedAt: $now}' \
+  "$MANIFEST" > "$MANIFEST.tmp" && mv "$MANIFEST.tmp" "$MANIFEST"
+echo "hq-delegate-pickup: FAILED — $reason. Re-send with a direct ask, or hand it to someone else." >&2
+exit 5

package/assets/scaffold/core/scripts/hq-delegate-repo.sh

@@ -0,0 +1,158 @@
+#!/usr/bin/env bash
+# hq-core: public
+# hq-delegate-repo.sh — code/branch handover for a delegation: make sure the
+# project's branch exists on the remote, record uncommitted work as NOT
+# transferred, and verify the recipient's repository access read-only.
+#
+# Usage:
+#   core/scripts/hq-delegate-repo.sh --manifest <path> [--yes] [--github-user <login>]
+#
+# Behavior (driven by the manifest's repo{} block; no-op when repo is null):
+#   - records remote URL and the branch's headSha into the manifest
+#   - a branch that exists only locally requires confirmation: without --yes
+#     the helper prints the plan and exits 2; with --yes it pushes via an
+#     explicitly anchored `git -C <abs path> push -u origin <branch>`
+#   - dirty/untracked files are captured into repo.dirtyFiles[] and appended
+#     to BRIEF.md as work NOT transferred — never silently dropped
+#   - recipient access is checked read-only via gh when --github-user is
+#     given; otherwise (or on a gh failure) repo.accessVerified stays false
+#     and the brief says so plainly — the helper never claims unverified access
+#   - never touches vaultPrefixes[] and never pushes repo content to the vault
+#
+# Env: HQ_ROOT — HQ root override (default: resolved from script location)
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+HQ_ROOT="${HQ_ROOT:-$(cd "$SCRIPT_DIR/../.." && pwd)}"
+
+usage() { sed -n '3,22p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'; }
+die()   { echo "hq-delegate-repo: $*" >&2; exit 1; }
+
+command -v jq >/dev/null 2>&1 || die "jq is required but not installed"
+
+MANIFEST="" YES=0 GH_USER=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --manifest)    MANIFEST="${2:-}"; shift 2 ;;
+    --yes)         YES=1; shift ;;
+    --github-user) GH_USER="${2:-}"; shift 2 ;;
+    -h|--help)     usage; exit 0 ;;
+    *) die "unknown argument: $1" ;;
+  esac
+done
+
+[ -n "$MANIFEST" ] || die "--manifest is required"
+[ -f "$MANIFEST" ] || die "manifest not found: $MANIFEST"
+jq -e . "$MANIFEST" >/dev/null 2>&1 || die "manifest is not valid JSON: $MANIFEST"
+
+BUNDLE_DIR="$(cd "$(dirname "$MANIFEST")" && pwd)"
+BRIEF="$BUNDLE_DIR/BRIEF.md"
+
+# --- no-repo projects skip cleanly -------------------------------------------
+
+if jq -e '.repo == null' "$MANIFEST" >/dev/null; then
+  echo "hq-delegate-repo: project has no repoPath — nothing to hand over"
+  exit 0
+fi
+
+REPO_REL="$(jq -r '.repo.path // empty' "$MANIFEST")"
+BRANCH="$(jq -r '.repo.branch // empty' "$MANIFEST")"
+[ -n "$REPO_REL" ] || die "manifest repo block has no path"
+
+REPO_DIR="$HQ_ROOT/$REPO_REL"
+[ -d "$REPO_DIR/.git" ] || git -C "$REPO_DIR" rev-parse --git-dir >/dev/null 2>&1 \
+  || die "not a git repository: $REPO_DIR"
+
+REMOTE_URL="$(git -C "$REPO_DIR" remote get-url origin 2>/dev/null || true)"
+
+# --- dirty / untracked work is recorded, never dropped -----------------------
+
+DIRTY_JSON="$(git -C "$REPO_DIR" status --porcelain | sed 's/^...//' | jq -R . | jq -cs .)"
+
+# --- branch state -------------------------------------------------------------
+
+BRANCH_PUSHED=false HEAD_SHA=""
+if [ -n "$BRANCH" ]; then
+  git check-ref-format --branch "$BRANCH" >/dev/null 2>&1 || die "invalid branch name in PRD: $BRANCH"
+  LOCAL_SHA="$(git -C "$REPO_DIR" rev-parse --verify --quiet "refs/heads/$BRANCH" || true)"
+  REMOTE_SHA="$(git -C "$REPO_DIR" rev-parse --verify --quiet "refs/remotes/origin/$BRANCH" || true)"
+
+  if [ -n "$REMOTE_SHA" ]; then
+    BRANCH_PUSHED=true
+    HEAD_SHA="$REMOTE_SHA"
+  elif [ -n "$LOCAL_SHA" ]; then
+    echo "Branch handover plan — repo '$REPO_REL':"
+    echo "  branch '$BRANCH' exists only locally ($LOCAL_SHA)"
+    echo "  action: git -C $REPO_DIR push -u origin $BRANCH"
+    if [ "$YES" -ne 1 ]; then
+      echo
+      echo "hq-delegate-repo: confirmation required — re-run with --yes to push the branch" >&2
+      exit 2
+    fi
+    git -C "$REPO_DIR" push -u origin "$BRANCH" \
+      || die "failed to push branch '$BRANCH' to origin"
+    BRANCH_PUSHED=true
+    HEAD_SHA="$LOCAL_SHA"
+  else
+    echo "hq-delegate-repo: branch '$BRANCH' does not exist yet (declared in the PRD, not started) — recording as unpushed"
+  fi
+fi
+
+# --- read-only recipient access check ----------------------------------------
+
+ACCESS_VERIFIED=false ACCESS_NOTE=""
+if [ -n "$GH_USER" ] && [ -n "$REMOTE_URL" ] && command -v gh >/dev/null 2>&1; then
+  # owner/repo from ssh or https remote forms
+  OWNER_REPO="$(printf '%s' "$REMOTE_URL" | sed -E 's#^(git@[^:]+:|https?://[^/]+/)##; s#\.git$##')"
+  if gh api "repos/$OWNER_REPO/collaborators/$GH_USER" >/dev/null 2>&1; then
+    ACCESS_VERIFIED=true
+    ACCESS_NOTE="verified: $GH_USER is a collaborator on $OWNER_REPO"
+  else
+    ACCESS_NOTE="UNVERIFIED: could not confirm $GH_USER has access to $OWNER_REPO — the recipient may need to be invited before they can pull the branch"
+  fi
+else
+  ACCESS_NOTE="UNVERIFIED: recipient repository access was not checked (no GitHub login supplied) — confirm they can reach the repo before assuming so"
+fi
+
+# --- manifest update (repo block only — vaultPrefixes are never touched) -----
+
+TMP_MANIFEST="$(mktemp)"
+jq \
+  --arg remote "$REMOTE_URL" \
+  --arg headSha "$HEAD_SHA" \
+  --argjson dirty "$DIRTY_JSON" \
+  --argjson pushed "$BRANCH_PUSHED" \
+  --argjson access "$ACCESS_VERIFIED" \
+  --arg accessNote "$ACCESS_NOTE" \
+  '.repo.remote = (if $remote == "" then null else $remote end)
+   | .repo.headSha = (if $headSha == "" then null else $headSha end)
+   | .repo.dirtyFiles = $dirty
+   | .repo.branchPushed = $pushed
+   | .repo.accessVerified = $access
+   | .repo.accessNote = $accessNote' \
+  "$MANIFEST" > "$TMP_MANIFEST" && mv "$TMP_MANIFEST" "$MANIFEST"
+
+# --- brief: call out untransferred work and unverified access ----------------
+
+if [ -f "$BRIEF" ]; then
+  DIRTY_COUNT="$(printf '%s' "$DIRTY_JSON" | jq 'length')"
+  if [ "$DIRTY_COUNT" -gt 0 ] || [ "$ACCESS_VERIFIED" != "true" ]; then
+    {
+      echo
+      echo "## Code handover notes"
+      echo
+      if [ "$DIRTY_COUNT" -gt 0 ]; then
+        echo "The delegator's working tree had uncommitted changes that are **not transferred** with this delegation. If something seems missing, these files are why — ask the delegator to commit and push them:"
+        echo
+        printf '%s' "$DIRTY_JSON" | jq -r '.[] | "- `\(.)`"'
+        echo
+      fi
+      if [ "$ACCESS_VERIFIED" != "true" ]; then
+        echo "$ACCESS_NOTE"
+      fi
+    } >> "$BRIEF"
+  fi
+fi
+
+echo "hq-delegate-repo: recorded branch state (pushed=$BRANCH_PUSHED, dirty=$(printf '%s' "$DIRTY_JSON" | jq 'length') files, accessVerified=$ACCESS_VERIFIED)"

package/assets/scaffold/core/scripts/hq-delegate-resolve.sh

@@ -0,0 +1,145 @@
+#!/usr/bin/env bash
+# hq-core: public
+# hq-delegate-resolve.sh — resolve a delegation recipient to a confirmed
+# principal (person email / prs_ uid, or fleet-agent agt_ uid). Read-only.
+#
+# Usage:
+#   core/scripts/hq-delegate-resolve.sh --company <slug> --to <token>
+#
+# Output (stdout, JSON): {kind, principal, displayName, source}
+#   kind      — "person" | "agent"
+#   principal — confirmed email, prs_… or agt_… uid
+#   source    — "verbatim" | "people-resolve" | "agents-list"
+#
+# Exit codes:
+#   0 — resolved
+#   1 — usage error (missing/invalid arguments)
+#   3 — ambiguous: candidate list printed to stdout as JSON
+#       {status:"ambiguous", matches:[…]} — caller must present a picker
+#   4 — not found (or found with no email): plain message on stderr
+#
+# Tenancy: every lookup is scoped with an explicit --company. This helper
+# never enumerates or falls back across companies — single-company by
+# construction, matching the /dm skill's resolution contract.
+#
+# Fast path: a token containing "@" or starting with prs_ / agt_ passes
+# through verbatim with NO lookup, preserving existing invocations exactly.
+
+set -euo pipefail
+
+usage() {
+  sed -n '3,26p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'
+}
+
+die_usage() {
+  echo "hq-delegate-resolve: $*" >&2
+  usage >&2
+  exit 1
+}
+
+command -v jq >/dev/null 2>&1 || { echo "hq-delegate-resolve: jq is required" >&2; exit 1; }
+
+COMPANY="" TOKEN=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --company) COMPANY="${2:-}"; shift 2 ;;
+    --to)      TOKEN="${2:-}"; shift 2 ;;
+    -h|--help) usage; exit 0 ;;
+    *) die_usage "unknown argument: $1" ;;
+  esac
+done
+
+[ -n "$COMPANY" ] || die_usage "--company is required (single-company lookups only; never a multi-company scan)"
+[ -n "$TOKEN" ]   || die_usage "--to is required"
+
+emit() { # kind principal displayName source
+  jq -cn --arg kind "$1" --arg principal "$2" --arg name "$3" --arg source "$4" \
+    '{kind: $kind, principal: $principal,
+      displayName: (if $name == "" then null else $name end), source: $source}'
+}
+
+# Strip CLI noise (version warnings, session-refresh notices) before the JSON
+# payload: keep everything from the first line that starts a JSON value.
+json_only() {
+  awk 'started {print; next} /^[[:space:]]*[{[]/ {started=1; print}'
+}
+
+# --- fast path: already a principal — pass through verbatim, no lookup -------
+
+case "$TOKEN" in
+  agt_*)
+    emit agent "$TOKEN" "" verbatim
+    exit 0
+    ;;
+  prs_*|*@*)
+    emit person "$TOKEN" "" verbatim
+    exit 0
+    ;;
+esac
+
+# --- name → people roster (single-company, read-only) ------------------------
+
+PEOPLE_RAW="$(hq people resolve "$TOKEN" --json --company "$COMPANY" 2>/dev/null | json_only || true)"
+PEOPLE_STATUS=""
+if [ -n "$PEOPLE_RAW" ] && printf '%s' "$PEOPLE_RAW" | jq -e . >/dev/null 2>&1; then
+  PEOPLE_STATUS="$(printf '%s' "$PEOPLE_RAW" | jq -r '.status // empty')"
+fi
+
+case "$PEOPLE_STATUS" in
+  found)
+    EMAIL="$(printf '%s' "$PEOPLE_RAW" | jq -r '.email // empty')"
+    NAME="$(printf '%s' "$PEOPLE_RAW" | jq -r '.name // .displayName // empty')"
+    [ -n "$EMAIL" ] || { echo "hq-delegate-resolve: resolver returned found but no email for '$TOKEN'" >&2; exit 4; }
+    emit person "$EMAIL" "$NAME" people-resolve
+    exit 0
+    ;;
+  ambiguous)
+    printf '%s' "$PEOPLE_RAW" | jq -c '{status: "ambiguous", matches: (.matches // [])}'
+    exit 3
+    ;;
+  no_email)
+    # A person entry without an email is often a fleet agent's roster row —
+    # fall through to the agent roster before treating this as terminal.
+    PERSON_NO_EMAIL=1
+    ;;
+  not_found|"")
+    : # fall through to the fleet-agent roster
+    ;;
+  *)
+    echo "hq-delegate-resolve: unexpected resolver status '$PEOPLE_STATUS' for '$TOKEN'" >&2
+    exit 4
+    ;;
+esac
+
+# --- name → fleet-agent roster (same company, read-only) ---------------------
+
+AGENTS_RAW="$(hq agents list --company "$COMPANY" --json 2>/dev/null | json_only || true)"
+if [ -z "$AGENTS_RAW" ] || ! printf '%s' "$AGENTS_RAW" | jq -e . >/dev/null 2>&1; then
+  AGENTS_RAW="[]"
+fi
+
+MATCHES="$(printf '%s' "$AGENTS_RAW" | jq -c --arg t "$TOKEN" '
+  [ .[]
+    | select((.name // .displayName // "") | ascii_downcase == ($t | ascii_downcase))
+    | {agentUid: (.agentUid // .uid // empty), name: (.name // .displayName // "")}
+    | select(.agentUid != "")
+  ]')"
+MATCH_COUNT="$(printf '%s' "$MATCHES" | jq 'length')"
+
+if [ "$MATCH_COUNT" -eq 1 ]; then
+  emit agent \
+    "$(printf '%s' "$MATCHES" | jq -r '.[0].agentUid')" \
+    "$(printf '%s' "$MATCHES" | jq -r '.[0].name')" \
+    agents-list
+  exit 0
+elif [ "$MATCH_COUNT" -gt 1 ]; then
+  printf '%s' "$MATCHES" | jq -c '{status: "ambiguous", matches: .}'
+  exit 3
+fi
+
+if [ "${PERSON_NO_EMAIL:-0}" -eq 1 ]; then
+  echo "hq-delegate-resolve: '$TOKEN' was found in company '$COMPANY' but has no email on record and matches no fleet agent — pass their exact email, personUid (prs_…), or agentUid (agt_…) instead" >&2
+else
+  echo "hq-delegate-resolve: no teammate or fleet agent named '$TOKEN' found in company '$COMPANY' — pass the exact email, personUid (prs_…), or agentUid (agt_…) instead" >&2
+fi
+exit 4