@indigoai-us/hq-cli 5.276.0 → 5.277.0

package/CHANGELOG.md

@@ -2,6 +2,82 @@
 
 ## [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

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

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

@@ -0,0 +1,129 @@
+#!/usr/bin/env bash
+# hq-core: public
+# hq-delegate-secrets.sh — grant a delegation recipient access to the secrets
+# a project needs, BY NAME ONLY. No command in this helper ever reads,
+# prints, logs, or interpolates a secret value.
+#
+# Usage:
+#   core/scripts/hq-delegate-secrets.sh --manifest <path> [--yes] [--no-secrets]
+#     [--env-schema <path>]
+#
+# Behavior:
+#   - derives required secret NAMES from the project's / repo's .env.schema
+#     (--env-schema overrides discovery); no schema -> records secrets: []
+#     and says so plainly rather than guessing at credentials
+#   - without --yes: prints a full-prose confirmation listing every name and
+#     the principal, then exits 2 granting nothing — this step is a privilege
+#     handover and gets its own confirmation, separate from the file grants
+#   - with --yes: hq secrets share <NAME> --with <principal> --permission read
+#     per name, then records the names (and only the names) in the manifest
+#   - --no-secrets: skips everything, records {secrets: [], secretsSkipped: true}
+#
+# Consumption on the recipient's side is via `hq run` / `hq secrets exec` —
+# documented in the brief; values never appear in any delegation artifact
+# (policy hq-delegate-never-inlines-secrets-or-share-urls).
+#
+# 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,24p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'; }
+die()   { echo "hq-delegate-secrets: $*" >&2; exit 1; }
+
+command -v jq >/dev/null 2>&1 || die "jq is required but not installed"
+
+MANIFEST="" YES=0 NO_SECRETS=0 ENV_SCHEMA=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --manifest)   MANIFEST="${2:-}"; shift 2 ;;
+    --yes)        YES=1; shift ;;
+    --no-secrets) NO_SECRETS=1; shift ;;
+    --env-schema) ENV_SCHEMA="${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"
+
+COMPANY="$(jq -r '.company // empty' "$MANIFEST")"
+PRINCIPAL="$(jq -r '.to.principal // empty' "$MANIFEST")"
+PROJECT="$(jq -r '.project.name // empty' "$MANIFEST")"
+[ -n "$COMPANY" ]   || die "manifest has no company"
+[ -n "$PRINCIPAL" ] || die "manifest has no to.principal"
+
+update_manifest() { # jq-filter
+  local tmp
+  tmp="$(mktemp)"
+  jq "$1" "$MANIFEST" > "$tmp" && mv "$tmp" "$MANIFEST"
+}
+
+# --- explicit skip ------------------------------------------------------------
+
+if [ "$NO_SECRETS" -eq 1 ]; then
+  update_manifest '.secrets = [] | .secretsSkipped = true'
+  echo "hq-delegate-secrets: skipped (--no-secrets) — no credential access granted"
+  exit 0
+fi
+
+# --- discover the env schema --------------------------------------------------
+
+if [ -z "$ENV_SCHEMA" ]; then
+  REPO_REL="$(jq -r '.repo.path // empty' "$MANIFEST")"
+  for candidate in \
+    "$HQ_ROOT/companies/$COMPANY/projects/$PROJECT/.env.schema" \
+    "${REPO_REL:+$HQ_ROOT/$REPO_REL/.env.schema}"; do
+    [ -n "$candidate" ] && [ -f "$candidate" ] && { ENV_SCHEMA="$candidate"; break; }
+  done
+fi
+
+if [ -z "$ENV_SCHEMA" ] || [ ! -f "$ENV_SCHEMA" ]; then
+  update_manifest '.secrets = [] | .secretsSkipped = false'
+  echo "hq-delegate-secrets: no .env.schema found for this project or its repo — no secret names to grant. If the project needs credentials, add an .env.schema and re-run, or grant them manually with 'hq secrets share'."
+  exit 0
+fi
+
+# --- parse names (KEY= lines; comments and blanks ignored) --------------------
+
+NAMES="$(grep -E '^[A-Za-z_][A-Za-z0-9_]*=' "$ENV_SCHEMA" | cut -d= -f1 | sort -u)"
+if [ -z "$NAMES" ]; then
+  update_manifest '.secrets = [] | .secretsSkipped = false'
+  echo "hq-delegate-secrets: $ENV_SCHEMA declares no secret names — nothing to grant"
+  exit 0
+fi
+NAME_COUNT="$(printf '%s\n' "$NAMES" | wc -l | tr -d ' ')"
+
+# --- confirmation gate (full prose; separate from the file-grant confirm) ----
+
+echo "Secret access handover — this grants the recipient the ability to use these credentials."
+echo
+echo "The following $NAME_COUNT secret name(s), declared by $(basename "$ENV_SCHEMA") for project '$PROJECT', will be shared with read permission to '$PRINCIPAL' in company '$COMPANY':"
+echo
+printf '%s\n' "$NAMES" | sed 's/^/  - /'
+echo
+echo "Only the names are granted and recorded; no secret value is read, printed, or transmitted by this step. The recipient consumes them through 'hq run' / 'hq secrets exec'."
+
+if [ "$YES" -ne 1 ]; then
+  echo
+  echo "hq-delegate-secrets: confirmation required — re-run with --yes after the user approves (or --no-secrets to skip)" >&2
+  exit 2
+fi
+
+# --- grant each name (names only — never a value read) ------------------------
+
+printf '%s\n' "$NAMES" | while IFS= read -r name; do
+  hq secrets share "$name" --with "$PRINCIPAL" --permission read --company "$COMPANY" \
+    || die "failed to grant '$name' to '$PRINCIPAL' — aborting; manifest not updated"
+  echo "hq-delegate-secrets: granted read on '$name' to '$PRINCIPAL'"
+done
+
+NAMES_JSON="$(printf '%s\n' "$NAMES" | jq -R . | jq -cs .)"
+NOW="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+update_manifest ".secrets = $NAMES_JSON | .secretsSkipped = false | .secretsGrantedAt = \"$NOW\""
+
+echo "hq-delegate-secrets: $NAME_COUNT secret name(s) granted and recorded (names only)"