@indigoai-us/hq-cli 5.314.0 → 5.316.0

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

@@ -0,0 +1,259 @@
+#!/usr/bin/env bash
+# hq-core: public
+# hq-delegate-send.sh — generate the self-sufficient pickup prompt for a
+# delegation and deliver it by DM. The prompt IS the handoff: pasted into a
+# fresh agent session on a clean HQ install, it pulls every file on demand
+# (hq files get per prefix — no /hq-sync run) and reaches the first
+# next-step with no follow-up question to the delegator.
+#
+# Usage:
+#   core/scripts/hq-delegate-send.sh --manifest <path> [--send]
+#     [--headline <text>] [--note <text>]
+#
+# Without --send: (re)generates PICKUP-PROMPT.md next to the manifest and
+# prints its path — inspectable, idempotent, sends nothing.
+# With --send: requires manifest status "verified" (the US-008 probe must
+# have passed), then delivers ONE `hq dm` with --prompt-file/--details-file
+# and advances status to "sent", recording the DM eventId.
+#
+# The caller (the /delegate skill) humanizes --headline / --note per
+# core/knowledge/public/hq-core/humanize-before-send.md (channel dm, light)
+# BEFORE invoking; this helper never rewrites recipients, flags, or the
+# generated command lines.
+#
+# Fail-closed: the generated prompt is scanned for secret-shaped content and
+# share-session URLs; a match aborts before anything is written or sent
+# (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)}"
+
+# shellcheck source=lib/secret-patterns.sh
+. "$SCRIPT_DIR/lib/secret-patterns.sh"
+
+usage() { sed -n '3,27p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'; }
+die()   { echo "hq-delegate-send: $*" >&2; exit 1; }
+
+command -v jq >/dev/null 2>&1 || die "jq is required but not installed"
+
+MANIFEST="" SEND=0 HEADLINE="" NOTE=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --manifest) MANIFEST="${2:-}"; shift 2 ;;
+    --send)     SEND=1; shift ;;
+    --headline) HEADLINE="${2:-}"; shift 2 ;;
+    --note)     NOTE="${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"
+LOCK="$MANIFEST.send-lock"
+if [ "$SEND" -eq 1 ]; then
+  mkdir "$LOCK" 2>/dev/null || die "verification or delivery is active; retry after it finishes"
+  trap 'rmdir "$LOCK"' EXIT
+fi
+
+BUNDLE_DIR="$(cd "$(dirname "$MANIFEST")" && pwd)"
+BRIEF="$BUNDLE_DIR/BRIEF.md"
+PROMPT="$BUNDLE_DIR/PICKUP-PROMPT.md"
+
+COMPANY="$(jq -r '.company // empty' "$MANIFEST")"
+PROJECT="$(jq -r '.project.name // empty' "$MANIFEST")"
+PRINCIPAL="$(jq -r '.to.principal // empty' "$MANIFEST")"
+DISPLAY="$(jq -r '.to.displayName // .to.principal' "$MANIFEST")"
+FROM="$(jq -r '.from.email // .from.personUid // "your teammate"' "$MANIFEST")"
+DELEGATION_ID="$(jq -r '.delegationId // empty' "$MANIFEST")"
+STATUS="$(jq -r '.status // empty' "$MANIFEST")"
+MODE="$(jq -r '.mode // "transfer"' "$MANIFEST")"
+[ -n "$COMPANY" ]   || die "manifest has no company"
+[ -n "$PROJECT" ]   || die "manifest has no project.name"
+[ -n "$PRINCIPAL" ] || die "manifest has no to.principal"
+
+PRD_ABS="$HQ_ROOT/$(jq -r '.project.prdPath' "$MANIFEST")"
+
+# --- assemble prompt sections from the manifest (single source of truth) -----
+
+GOAL="" STATE_LINE="" NEXT_STEPS=""
+if [ -f "$PRD_ABS" ] && jq -e . "$PRD_ABS" >/dev/null 2>&1; then
+  GOAL="$(jq -r '.metadata.goal // .description // ""' "$PRD_ABS")"
+  TOTAL="$(jq -r '[.userStories // [] | .[]] | length' "$PRD_ABS")"
+  DONE="$(jq -r '[.userStories // [] | .[] | select(.passes == true)] | length' "$PRD_ABS")"
+  STATE_LINE="$DONE of $TOTAL stories are complete."
+  NEXT_STEPS="$(jq -r '[.userStories // [] | .[] | select(.passes != true)]
+    | sort_by(.priority) | .[:3] | to_entries | .[]
+    | "\(.key + 1). **\(.value.id): \(.value.title)** — \(.value.description)"' "$PRD_ABS")"
+fi
+
+GET_LINES="$(jq -r --arg co "$COMPANY" \
+  'def bashq: if test("^[A-Za-z0-9_./:@+-]+$") then . else @sh end; .vaultPrefixes[] | "hq files get \(.prefix | bashq) --company \($co | bashq)"' "$MANIFEST")"
+
+REPO_IS_NULL="$(jq -r 'if .repo == null then "yes" else "no" end' "$MANIFEST")"
+REPO_SECTION=""
+if [ "$REPO_IS_NULL" = "no" ]; then
+  R_PATH="$(jq -r '.repo.path // empty' "$MANIFEST")"
+  R_REMOTE="$(jq -r '.repo.remote // empty' "$MANIFEST")"
+  R_BRANCH="$(jq -r '.repo.branch // empty' "$MANIFEST")"
+  R_BASE="$(jq -r '.repo.baseBranch // "main"' "$MANIFEST")"
+  R_SHA="$(jq -r '.repo.headSha // empty' "$MANIFEST")"
+  R_ACCESS="$(jq -r '.repo.accessNote // empty' "$MANIFEST")"
+  if [ -n "$R_BRANCH" ] && git check-ref-format --branch "$R_BRANCH" >/dev/null 2>&1 && [ -n "$R_SHA" ]; then
+    REPO_SECTION="## Get the code
+
+The work lives on branch \`$R_BRANCH\` (base: \`$R_BASE\`)${R_SHA:+ at \`$R_SHA\`}.
+
+\`\`\`bash
+# From your HQ root; clone first if the repo is not present${R_REMOTE:+ (remote: $R_REMOTE)}:
+git -C $(printf '%q' "$R_PATH") fetch origin
+git -C $(printf '%q' "$R_PATH") switch -- $(printf '%q' "$R_BRANCH")
+\`\`\`
+${R_ACCESS:+
+> $R_ACCESS
+}"
+  fi
+fi
+
+SECRET_NAMES="$(jq -r '[.secrets // [] | .[]] | join(",")' "$MANIFEST")"
+SECRETS_SECTION=""
+if [ -n "$SECRET_NAMES" ]; then
+  SECRETS_SECTION="## Credentials
+
+You have been granted read access to the secret names this project needs: \`$SECRET_NAMES\`. Values never travel in this handoff — consume them at runtime:
+
+\`\`\`bash
+# Inject from the project's .env.schema:
+hq run -- <your command>
+# Or explicitly by name:
+hq secrets exec --only $SECRET_NAMES --company $COMPANY -- <your command>
+\`\`\`
+"
+fi
+
+# --- write the prompt (staged, scanned, then placed) -------------------------
+
+STAGE="$(mktemp -d)"
+trap 'rm -rf "$STAGE"; [ "$SEND" -eq 0 ] || rmdir "$LOCK"' EXIT
+
+{
+  echo "# Project handoff: $PROJECT"
+  echo
+  if [ "$MODE" = "share" ]; then
+    echo "$FROM has shared the **$PROJECT** project ($COMPANY) with you${NOTE:+ — $NOTE}. You are working on it together; ownership stays with them."
+  else
+    echo "$FROM has delegated the **$PROJECT** project ($COMPANY) to you${NOTE:+ — $NOTE}. Transfer status is recorded in the dossier. Work Mesh ownership requires separate confirmation. Delegation id: \`$DELEGATION_ID\`."
+  fi
+  echo
+  echo "Completed grant and publication steps are recorded as receipts in the manifest. Sender-side checks do not prove your access: pull the files below and acknowledge receipt, or report any access error."
+  echo
+  if [ -n "$GOAL" ]; then
+    echo "## The goal"
+    echo
+    echo "$GOAL"
+    echo
+  fi
+  if [ -n "$STATE_LINE" ]; then
+    echo "## Where things stand"
+    echo
+    echo "$STATE_LINE"
+    echo
+  fi
+  echo "## Pull the files (on demand — no sync)"
+  echo
+  echo "Run these from your HQ root; each materializes exactly that path locally:"
+  echo
+  echo '```bash'
+  printf '%s\n' "$GET_LINES"
+  echo '```'
+  echo
+  echo "Start with the project dossier: \`companies/$COMPANY/projects/$PROJECT/\` now contains the PRD (\`prd.json\`), a full brief (\`README.md\` / the DM's details pane), and the delegation journal."
+  echo
+  if [ -n "$REPO_SECTION" ]; then
+    printf '%s\n' "$REPO_SECTION"
+    echo
+  fi
+  if [ -n "$SECRETS_SECTION" ]; then
+    printf '%s\n' "$SECRETS_SECTION"
+    echo
+  fi
+  if [ -n "$NEXT_STEPS" ]; then
+    echo "## Your next three steps"
+    echo
+    printf '%s\n' "$NEXT_STEPS"
+    echo
+  fi
+  echo "## If something is off"
+  echo
+  echo "The manifest and BRIEF.md are published under \`delegation/$DELEGATION_ID/\` within \`companies/$COMPANY/projects/$PROJECT/\`. If a pull fails or a path looks empty, report it to $FROM."
+} > "$STAGE/PICKUP-PROMPT.md"
+
+# fail-closed scans: secret shapes + share-session capability URLs
+if ! hq_scan_secrets "$STAGE/PICKUP-PROMPT.md" "$BRIEF"; then
+  die "generated pickup prompt matched a secret-detection pattern — aborting, nothing written or sent"
+fi
+if grep -Eq 'share-session/[A-Za-z0-9_-]+' "$STAGE/PICKUP-PROMPT.md" "$BRIEF" 2>/dev/null; then
+  die "a share-session URL appeared in a delegation artifact — forbidden (direct grants only), aborting"
+fi
+
+mv "$STAGE/PICKUP-PROMPT.md" "$PROMPT"
+rm -rf "$STAGE"
+trap '[ "$SEND" -eq 0 ] || rmdir "$LOCK"' EXIT
+
+echo "hq-delegate-send: pickup prompt written: $PROMPT"
+
+[ "$SEND" -eq 1 ] || exit 0
+
+# --- deliver: ONE hq dm invocation, file flags only --------------------------
+
+STATUS="$(jq -r '.status' "$MANIFEST")"
+[ "$STATUS" = "verified" ] \
+  || die "manifest status is '$STATUS' — the reachability probe (hq-delegate-verify.sh) must pass before sending"
+[ -f "$BRIEF" ] || die "BRIEF.md missing from the bundle — cannot send without the details pane"
+jq -e '.publication.verifiedAt != null and (.publication.files | type == "object" and length > 0)' "$MANIFEST" >/dev/null \
+  || die "verified publication receipt missing; run verification again"
+file_hash() {
+  if command -v sha256sum >/dev/null 2>&1; then sha256sum "$1" | cut -d ' ' -f1; else shasum -a 256 "$1" | cut -d ' ' -f1; fi
+}
+while IFS= read -r row; do
+  path="$(printf '%s' "$row" | jq -r '.key')"
+  expected="$(printf '%s' "$row" | jq -r '.value')"
+  [ -f "$HQ_ROOT/$path" ] && [ "$(file_hash "$HQ_ROOT/$path")" = "$expected" ] \
+    || die "published artifact changed: $path; run verification again"
+done < <(jq -c '.publication.files | to_entries[]' "$MANIFEST")
+PUBLISHED="$HQ_ROOT/$(jq -r '.publication.manifestPath' "$MANIFEST")"
+[ -f "$PUBLISHED" ] || die "published manifest missing; run verification again"
+NORMALIZED="$(jq -cS '.status="granted" | .recipientAccess="unconfirmed" | del(.publication,.verifiedAt,.sentAt,.dmEventId)' "$MANIFEST")"
+[ "$NORMALIZED" = "$(jq -cS . "$PUBLISHED")" ] || die "manifest changed since publication; run verification again"
+[ "$(file_hash "$BRIEF")" = "$(file_hash "$(dirname "$PUBLISHED")/BRIEF.md")" ] \
+  || die "brief changed since publication; run verification again"
+
+[ -n "$HEADLINE" ] || HEADLINE="Project handoff: $PROJECT — open the brief, pull the files, and acknowledge receipt"
+
+TMP_MANIFEST="$(mktemp "${MANIFEST}.tmp.XXXXXX")"
+if ! jq '.status = "sending"' "$MANIFEST" > "$TMP_MANIFEST" || ! mv "$TMP_MANIFEST" "$MANIFEST"; then
+  rm -f "$TMP_MANIFEST"
+  die "could not persist sending state; no DM attempted"
+fi
+DM_OUT="$(hq dm "$PRINCIPAL" "$HEADLINE" --prompt-file "$PROMPT" --details-file "$BRIEF")" \
+  || die "hq dm delivery outcome is uncertain; status is sending, inspect DM history before retrying"
+
+EVENT_ID="$(printf '%s' "$DM_OUT" | grep -oE 'eventId[: ]+[A-Za-z0-9_-]+' | head -1 | sed -E 's/eventId[: ]+//' || true)"
+[ -n "$EVENT_ID" ] || die "DM response has no receipt; status is sending, reconcile DM history before retrying"
+NOW="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+
+TMP_MANIFEST="$(mktemp "${MANIFEST}.tmp.XXXXXX")"
+if ! jq --arg now "$NOW" --arg ev "${EVENT_ID:-}" \
+  '.status = "sent" | .sentAt = $now
+   | .dmEventId = (if $ev == "" then null else $ev end)' \
+  "$MANIFEST" > "$TMP_MANIFEST" || ! mv "$TMP_MANIFEST" "$MANIFEST"; then
+  rm -f "$TMP_MANIFEST"
+  die "DM delivered but receipt could not be saved; reconcile delivery before retrying"
+fi
+
+echo "hq-delegate-send: DM delivered to $DISPLAY ($PRINCIPAL)${EVENT_ID:+ (eventId $EVENT_ID)} — status advanced to 'sent'"

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

@@ -0,0 +1,175 @@
+#!/usr/bin/env bash
+# hq-core: public
+# hq-delegate-transfer.sh — make a delegation real everywhere HQ tracks
+# ownership: board entry, PRD metadata, work mesh, and the project journal.
+#
+# Usage:
+#   core/scripts/hq-delegate-transfer.sh --manifest <path>
+#
+# Behavior (mode "transfer"; mode "share" skips every mutation):
+#   1. companies/<co>/board.json — the project's entry gets owner=<recipient>
+#      and a bumped updated_at; created (once) if absent
+#   2. prd.json metadata gains owner, delegatedFrom, delegatedAt
+#   3. work-mesh: `done` event closes the delegator's in-progress thread and
+#      broadcasts the reassignment; silently skipped when the helper is
+#      unavailable (local/offline installs) — the transfer still succeeds
+#   4. a dated "Delegated" stanza is appended to the project journal naming
+#      the recipient, delegation id, and transferred scope
+#
+# Idempotent: re-running updates owner/timestamps in place — never a
+# duplicate board entry, never a duplicated journal stanza.
+#
+# The delegator's own vault access is untouched (granting the recipient
+# write does not revoke anything).
+#
+# 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,25p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'; }
+die()   { echo "hq-delegate-transfer: $*" >&2; exit 1; }
+
+command -v jq >/dev/null 2>&1 || die "jq is required but not installed"
+
+MANIFEST=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --manifest) MANIFEST="${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"
+
+MODE="$(jq -r '.mode // "transfer"' "$MANIFEST")"
+COMPANY="$(jq -r '.company // empty' "$MANIFEST")"
+PROJECT="$(jq -r '.project.name // empty' "$MANIFEST")"
+PRINCIPAL="$(jq -r '.to.principal // empty' "$MANIFEST")"
+DISPLAY="$(jq -r '.to.displayName // .to.principal // empty' "$MANIFEST")"
+DELEGATION_ID="$(jq -r '.delegationId // empty' "$MANIFEST")"
+FROM="$(jq -r '.from.email // .from.personUid // "unknown"' "$MANIFEST")"
+[ -n "$COMPANY" ]   || die "manifest has no company"
+[ -n "$PROJECT" ]   || die "manifest has no project.name"
+[ -n "$PRINCIPAL" ] || die "manifest has no to.principal"
+
+if [ "$MODE" = "share" ]; then
+  echo "hq-delegate-transfer: mode is 'share' — ownership stays with the delegator, nothing mutated"
+  exit 0
+fi
+
+jq -e '.status == "granted"' "$MANIFEST" >/dev/null || die "transfer requires confirmed grants (status granted)"
+[ "$FROM" != "unknown" ] && [ -n "$FROM" ] || die "sender identity missing; rebuild the bundle"
+NOW="$(jq -r '.ownershipTransferredAt // empty' "$MANIFEST")"
+[ -n "$NOW" ] || NOW="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+TODAY="$(date -u +%Y-%m-%d)"
+PRD_PATH="companies/$COMPANY/projects/$PROJECT/prd.json"
+PRD_ABS="$HQ_ROOT/$PRD_PATH"
+PROJECT_DIR="$HQ_ROOT/companies/$COMPANY/projects/$PROJECT"
+BOARD="$HQ_ROOT/companies/$COMPANY/board.json"
+
+[ -f "$PRD_ABS" ] || die "prd not found: $PRD_PATH"
+
+# --- 1. board entry: update in place, create once if absent ------------------
+
+if [ -f "$BOARD" ]; then
+  jq -e . "$BOARD" >/dev/null 2>&1 || die "board.json is not valid JSON: $BOARD"
+else
+  echo '{"projects": []}' > "$BOARD"
+fi
+
+TITLE="$(jq -r '.name // empty' "$PRD_ABS")"
+DESC="$(jq -r '.description // ""' "$PRD_ABS" | head -c 300)"
+
+TMP_BOARD="$(mktemp)"
+jq \
+  --arg prd "$PRD_PATH" \
+  --arg owner "$PRINCIPAL" \
+  --arg now "$NOW" \
+  --arg title "$TITLE" \
+  --arg desc "$DESC" \
+  --arg project "$PROJECT" \
+  '
+  if ([.projects // [] | .[] | select(.prd_path == $prd)] | length) > 0 then
+    .projects = [.projects[] |
+      if .prd_path == $prd then .owner = $owner | .updated_at = $now else . end]
+  else
+    .projects = (.projects // []) + [{
+      id: ("proj-" + $project),
+      title: $title,
+      description: $desc,
+      status: "in_progress",
+      owner: $owner,
+      prd_path: $prd,
+      created_at: $now,
+      updated_at: $now
+    }]
+  end
+  | .updated_at = $now
+  ' "$BOARD" > "$TMP_BOARD" && mv "$TMP_BOARD" "$BOARD"
+
+# --- 2. prd metadata ----------------------------------------------------------
+
+TMP_PRD="$(mktemp)"
+jq \
+  --arg owner "$PRINCIPAL" \
+  --arg from "$FROM" \
+  --arg now "$NOW" \
+  '.metadata.owner = $owner
+   | .metadata.delegatedFrom = $from
+   | .metadata.delegatedAt = $now' \
+  "$PRD_ABS" > "$TMP_PRD" && mv "$TMP_PRD" "$PRD_ABS"
+
+# --- 3. work mesh: close the delegator's thread, broadcast reassignment ------
+# Silently tolerated when unavailable (local/offline installs no-op).
+
+if command -v hq >/dev/null 2>&1; then
+  # `--session-id` is the CLI option (hq-cli 5.157+ rejects `--session` with
+  # "unknown option"); --company-slug/--project attribute the note to the
+  # delegated project.
+  hq mesh session note --enqueue --session-id "${HQ_SESSION_ID:-delegate}" --seq 1 \
+    --harness claude-code --adapter-version 1.0.0 \
+    --company-slug "$COMPANY" --project "$PROJECT" \
+    --summary "Delegated to $DISPLAY ($PRINCIPAL) — delegation $DELEGATION_ID; ownership transferred" \
+    || echo "hq-delegate-transfer: mesh note failed; authoritative mesh ownership remains unconfirmed" >&2
+fi
+
+# --- 4. journal: one dated stanza per delegation id --------------------------
+
+JOURNAL_DIR="$PROJECT_DIR/journal"
+JOURNAL_FILE="$JOURNAL_DIR/delegations.md"
+mkdir -p "$JOURNAL_DIR"
+if [ ! -f "$JOURNAL_FILE" ]; then
+  {
+    echo "# Delegation log — $PROJECT"
+    echo
+    echo "Ownership handoffs for this project, appended by /delegate."
+  } > "$JOURNAL_FILE"
+fi
+
+if ! grep -qF "$DELEGATION_ID" "$JOURNAL_FILE"; then
+  SCOPE="$(jq -r '[.vaultPrefixes // [] | .[] | .prefix] | join(", ")' "$MANIFEST")"
+  {
+    echo
+    echo "## $TODAY — Delegated to $DISPLAY"
+    echo
+    echo "- Delegation: \`$DELEGATION_ID\`"
+    echo "- From: $FROM"
+    echo "- To: $DISPLAY ($PRINCIPAL)"
+    echo "- Transferred scope: $SCOPE"
+    echo "- Local board and PRD ownership updated; Work Mesh ownership is unconfirmed. Existing delegator access is unchanged."
+  } >> "$JOURNAL_FILE"
+fi
+
+# --- record on the manifest ---------------------------------------------------
+
+TMP_MANIFEST="$(mktemp)"
+jq --arg now "$NOW" '.ownershipTransferredAt = $now | .workMeshOwnership = "unconfirmed"' "$MANIFEST" > "$TMP_MANIFEST" \
+  && mv "$TMP_MANIFEST" "$MANIFEST"
+
+echo "hq-delegate-transfer: ownership of '$PROJECT' transferred to $DISPLAY ($PRINCIPAL) — local board, PRD, and journal updated; Work Mesh ownership unconfirmed"

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

@@ -0,0 +1,238 @@
+#!/usr/bin/env bash
+# hq-core: public
+# hq-delegate-verify.sh — prove a delegation can actually be picked up
+# before anyone is told it is theirs, or print the full plan without
+# touching anything.
+#
+# Usage (probe mode — after grants, before the DM):
+#   core/scripts/hq-delegate-verify.sh --manifest <path>
+#
+# Probes every manifest vaultPrefix with `hq files browse` and requires it
+# reachable AND non-empty. All pass -> manifest advances granted -> verified
+# (send is gated on this). Any failure -> non-zero, the failing prefix and
+# likely cause named, status left at its last successful value so a re-run
+# resumes without re-granting.
+#
+# Usage (dry-run mode — full plan, zero mutation):
+#   core/scripts/hq-delegate-verify.sh --dry-run \
+#     --company <slug> --project <name> --to <principal> [--mode transfer|share]
+#
+# Prints recipient, mode, every prefix with its permission, the secret
+# names an .env.schema would grant, repo + branch, and the DM headline that
+# would be sent. Exits 0. Creates nothing under workspace/delegations/ and
+# invokes no mutating command.
+#
+# 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,25p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'; }
+die()   { echo "hq-delegate-verify: $*" >&2; exit 1; }
+
+command -v jq >/dev/null 2>&1 || die "jq is required but not installed"
+
+MANIFEST="" DRY_RUN=0 COMPANY="" PROJECT="" TO="" MODE="transfer"
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --manifest) MANIFEST="${2:-}"; shift 2 ;;
+    --dry-run)  DRY_RUN=1; shift ;;
+    --company)  COMPANY="${2:-}"; shift 2 ;;
+    --project)  PROJECT="${2:-}"; shift 2 ;;
+    --to)       TO="${2:-}"; shift 2 ;;
+    --mode)     MODE="${2:-}"; shift 2 ;;
+    -h|--help)  usage; exit 0 ;;
+    *) die "unknown argument: $1" ;;
+  esac
+done
+
+# =============================================================================
+# Dry-run mode: full plan from the builder's own derivation, zero mutation
+# =============================================================================
+
+if [ "$DRY_RUN" -eq 1 ]; then
+  [ -n "$COMPANY" ] || die "--dry-run requires --company"
+  [ -n "$PROJECT" ] || die "--dry-run requires --project"
+  [ -n "$TO" ]      || die "--dry-run requires --to"
+
+  # The builder's --dry-run prints the manifest it WOULD write — single
+  # derivation source, nothing lands on disk.
+  PLAN_JSON="$(HQ_ROOT="$HQ_ROOT" bash "$SCRIPT_DIR/hq-delegate-bundle.sh" build \
+    --company "$COMPANY" --project "$PROJECT" --to "$TO" --mode "$MODE" --dry-run)" \
+    || die "could not derive the delegation plan (see builder error above)"
+
+  # Secret names the US-005 step would grant (same .env.schema derivation).
+  REPO_REL="$(printf '%s' "$PLAN_JSON" | jq -r '.repo.path // empty')"
+  SCHEMA=""
+  for candidate in \
+    "$HQ_ROOT/companies/$COMPANY/projects/$PROJECT/.env.schema" \
+    "${REPO_REL:+$HQ_ROOT/$REPO_REL/.env.schema}"; do
+    [ -n "$candidate" ] && [ -f "$candidate" ] && { SCHEMA="$candidate"; break; }
+  done
+  SECRET_NAMES="(none — no .env.schema found)"
+  if [ -n "$SCHEMA" ]; then
+    SECRET_NAMES="$(grep -E '^[A-Za-z_][A-Za-z0-9_]*=' "$SCHEMA" | cut -d= -f1 | sort -u | tr '\n' ' ')"
+    [ -n "$SECRET_NAMES" ] || SECRET_NAMES="(none declared)"
+  fi
+
+  echo "Delegation dry run — nothing will be pushed, granted, transferred, or sent."
+  echo
+  echo "  Recipient:  $TO"
+  echo "  Mode:       $MODE"
+  echo "  Company:    $COMPANY"
+  echo "  Project:    $PROJECT"
+  echo
+  echo "  Vault grants that would be written:"
+  printf '%s' "$PLAN_JSON" | jq -r '.vaultPrefixes[] | "    \(.permission)\ton \(.prefix)\t(\(.reason // ""))"'
+  echo
+  echo "  Secret names that would be granted (read): $SECRET_NAMES"
+  echo
+  if printf '%s' "$PLAN_JSON" | jq -e '.repo != null' >/dev/null; then
+    printf '%s' "$PLAN_JSON" | jq -r '"  Repo handover: \(.repo.path) — branch \(.repo.branch // "(none)") (base \(.repo.baseBranch))"'
+  else
+    echo "  Repo handover: none (project has no repoPath)"
+  fi
+  echo
+  echo "  DM that would be sent to $TO:"
+  echo "    \"Project handoff: $PROJECT is yours now — open details for the brief, paste the prompt into your agent to pick it up\""
+  echo "    (prompt: generated pickup prompt; details: the delegation brief)"
+  exit 0
+fi
+
+# =============================================================================
+# Probe mode: reachability of every granted prefix
+# =============================================================================
+
+[ -n "$MANIFEST" ] || die "--manifest is required (or --dry-run with --company/--project/--to)"
+[ -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")"
+LOCK="$MANIFEST.send-lock"
+mkdir "$LOCK" 2>/dev/null || die "verification or delivery is active; retry after it finishes"
+REF_BROWSE_CACHE=""
+trap '[[ -z "$REF_BROWSE_CACHE" ]] || rm -rf "$REF_BROWSE_CACHE"; rmdir "$LOCK"' EXIT
+STATUS="$(jq -r '.status // empty' "$MANIFEST")"
+[ -n "$COMPANY" ] || die "manifest has no company"
+
+case "$STATUS" in
+  granted|verified) ;;
+  building) die "manifest status is 'building' — run hq-delegate-grant.sh first (probe verifies grants, it cannot create them)" ;;
+  *) die "manifest status is '$STATUS' — probe runs from 'granted' (or re-runs from 'verified')" ;;
+esac
+
+PREFIX_COUNT="$(jq '.vaultPrefixes | length' "$MANIFEST")"
+[ "$PREFIX_COUNT" -gt 0 ] || die "manifest has no vaultPrefixes to probe"
+
+echo "hq-delegate-verify: probing $PREFIX_COUNT prefix(es) in company '$COMPANY'"
+FAILED=0
+i=0
+while [ "$i" -lt "$PREFIX_COUNT" ]; do
+  PFX="$(jq -r ".vaultPrefixes[$i].prefix" "$MANIFEST")"
+  BROWSE_OUT="$(hq files browse "$PFX" --company "$COMPANY" 2>&1)" && BROWSE_RC=0 || BROWSE_RC=$?
+  if [ "$BROWSE_RC" -ne 0 ]; then
+    echo "  FAIL  $PFX — browse errored (likely cause: the grant did not land, or the caller's session expired — re-run /hq-login and hq-delegate-grant.sh)"
+    FAILED=1
+  elif [ -z "$(printf '%s' "$BROWSE_OUT" | tr -d '[:space:]')" ] || [ "$(printf '%s' "$BROWSE_OUT" | tr -d '[:space:]')" = "Noobjectsunderthatprefix." ]; then
+    echo "  FAIL  $PFX — reachable but EMPTY (likely cause: the dossier was never pushed to the vault — hq sync push companies/$COMPANY/... and re-run)"
+    FAILED=1
+  else
+    echo "  pass  $PFX"
+  fi
+  i=$((i + 1))
+done
+
+# --- referenced files: prefix reachability is not enough ---------------------
+# (Live finding: a knowledge prefix can be reachable and non-empty while the
+# SPECIFIC referenced file is absent — the recipient then pulls a folder that
+# silently misses the note the brief points at. Probe each referenced file.)
+
+# Memoized, throttle-tolerant browse for the referenced-file loop. Multiple
+# referenced files can share a parent prefix (e.g. two policies under
+# policies/), and back-to-back vault browses of the same prefix can be throttled
+# to an EMPTY page — which the grep below would misread as "file not in vault".
+# Browse each distinct parent at most once, and retry an empty result a few
+# times before trusting it. (Cache dir cleaned on exit.)
+REF_BROWSE_CACHE="$(mktemp -d)"
+listing_has_exact_key() {
+  local listing="$1" expected="$2"
+  printf '%s\n' "$listing" | awk -v expected="$expected" '
+    function exact_key(row, expected, modified, size) {
+      gsub(/\033\[[0-9;]*m/, "", row)
+      sub(/[[:space:]]+$/, "", row)
+      if (row !~ / +(shared-with-you|creator access — creator-only|role-bypass|personal-vault|private folder — children are creator-only)$/) return 0
+      sub(/ +(shared-with-you|creator access — creator-only|role-bypass|personal-vault|private folder — children are creator-only)$/, "", row)
+      modified = row
+      sub(/^.* +/, "", modified)
+      if (modified != "—" && modified !~ /^[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]T[0-9][0-9]:[0-9][0-9]:[0-9][0-9]\.[0-9][0-9][0-9]Z$/) return 0
+      sub(/ +[^[:space:]]+$/, "", row)
+      sub(/[[:space:]]+$/, "", row)
+      size = row
+      sub(/^.* +/, "", size)
+      if (size !~ /^[0-9]+$/) return 0
+      sub(/ +[0-9]+$/, "", row)
+      sub(/[[:space:]]+$/, "", row)
+      return row == expected
+    }
+    NR > 2 && exact_key($0, expected) { found = 1 }
+    END { exit found ? 0 : 1 }
+  '
+}
+
+browse_parent() { # parent -> listing (memoized per run, retried on empty)
+  local parent="$1" key out attempt
+  key="$REF_BROWSE_CACHE/$(printf '%s' "$parent" | tr '/@:' '___')"
+  if [ -f "$key" ]; then cat "$key"; return 0; fi
+  attempt=1
+  out=""
+  while :; do
+    out="$(hq files browse "$parent" --company "$COMPANY" 2>/dev/null || true)"
+    [ -n "$(printf '%s' "$out" | tr -d '[:space:]')" ] && break
+    [ "$attempt" -ge "${HQ_DELEGATE_BROWSE_RETRIES:-3}" ] && break
+    attempt=$((attempt + 1))
+    sleep "${HQ_DELEGATE_BROWSE_RETRY_SLEEP:-2}"
+  done
+  printf '%s' "$out" > "$key"
+  printf '%s' "$out"
+}
+
+REF_COUNT="$(jq -r --arg co "$COMPANY" \
+  '[((.knowledge // []) + (.policies // []))[] | select(startswith("companies/" + $co + "/"))] | length' "$MANIFEST")"
+if [ "$REF_COUNT" -gt 0 ]; then
+  echo "hq-delegate-verify: probing $REF_COUNT referenced knowledge/policy file(s)"
+  while IFS= read -r kpath; do
+    [ -n "$kpath" ] || continue
+    REL="${kpath#companies/$COMPANY/}"
+    PARENT="$(dirname "$REL")/"
+    BASE="$(basename "$REL")"
+    LISTING="$(browse_parent "$PARENT")"
+    # Pipe-free substring test: `printf | grep -q` lets grep close the pipe on an
+    # early match, which under `set -o pipefail` surfaces printf's SIGPIPE as a
+    # non-zero pipeline and FALSE-FAILS a file that is genuinely present (it bit
+    # exactly the referenced files that sort early in a large parent listing).
+    if listing_has_exact_key "$LISTING" "$kpath"; then
+      echo "  pass  $REL"
+    else
+      echo "  FAIL  $REL — granted prefix is reachable but this referenced file is NOT in the vault (likely cause: it was never pushed — hq sync push $kpath --company $COMPANY and re-run)"
+      FAILED=1
+    fi
+  done <<EOF
+$(jq -r --arg co "$COMPANY" '((.knowledge // []) + (.policies // []))[] | select(startswith("companies/" + $co + "/"))' "$MANIFEST")
+EOF
+fi
+
+if [ "$FAILED" -ne 0 ]; then
+  echo "hq-delegate-verify: probe FAILED — the DM must not be sent; fix the failing prefix(es) above and re-run (manifest status left at '$STATUS')" >&2
+  exit 1
+fi
+
+HQ_ROOT="$HQ_ROOT" bash "$SCRIPT_DIR/hq-delegate-publish.sh" --manifest "$MANIFEST" --lock-held \
+  || die "final dossier publication failed; notification blocked"
+NOW="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+TMP_MANIFEST="$(mktemp)"
+jq --arg now "$NOW" '.status = "verified" | .verifiedAt = $now' \
+  "$MANIFEST" > "$TMP_MANIFEST" && mv "$TMP_MANIFEST" "$MANIFEST"
+
+echo "hq-delegate-verify: all $PREFIX_COUNT prefix(es) reachable — manifest status advanced to 'verified'"