@indigoai-us/hq-cli 5.290.0 → 5.292.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" \
+  '.vaultPrefixes[] | "hq files get \(.prefix) --company \($co)"' "$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-verify.sh

@@ -0,0 +1,213 @@
+#!/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:]')" ]; 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)"
+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" == *"$BASE"* ]]; 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'"