@indigoai-us/hq-cli 5.291.0 → 5.293.0

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

@@ -0,0 +1,226 @@
+#!/usr/bin/env bash
+# hq-core: public
+# hq-delegate-grant.sh — materialize a delegation's dossier in the vault and
+# write the ACL grants its manifest declares, verifying each one landed.
+#
+# Usage:
+#   core/scripts/hq-delegate-grant.sh --manifest <path> [--yes]
+#
+# Without --yes: prints the full grant plan (prefix, principal, permission —
+# the write grant is a privilege escalation and needs explicit confirmation)
+# and exits 2 without mutating anything. The caller (the /delegate skill)
+# confirms with the user, then re-invokes with --yes.
+#
+# With --yes:
+#   1. hq sync push the project directory so the vault prefix exists
+#   2. hq files share each manifest vaultPrefix to the recipient
+#   3. read each grant back with hq files acl and match grantee + permission
+#   4. advance manifest status building -> granted, stamping verifiedAt
+#
+# Direct ACL grants ONLY — this helper never mints a share-session URL
+# (policy hq-delegate-never-inlines-secrets-or-share-urls).
+#
+# Idempotent: a prefix whose grant already exists is reported, not an error.
+# A failed read-back exits non-zero and leaves manifest status unchanged.
+#
+# 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-grant: $*" >&2; exit 1; }
+
+command -v jq >/dev/null 2>&1 || die "jq is required but not installed"
+
+MANIFEST="" YES=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --manifest) MANIFEST="${2:-}"; shift 2 ;;
+    --yes)      YES=1; shift ;;
+    -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")"
+PROJECT="$(jq -r '.project.name // empty' "$MANIFEST")"
+PRINCIPAL="$(jq -r '.to.principal // empty' "$MANIFEST")"
+DISPLAY="$(jq -r '.to.displayName // .to.principal // empty' "$MANIFEST")"
+STATUS="$(jq -r '.status // empty' "$MANIFEST")"
+[ -n "$COMPANY" ]   || die "manifest has no company"
+[ -n "$PROJECT" ]   || die "manifest has no project.name"
+[ -n "$PRINCIPAL" ] || die "manifest has no to.principal"
+
+# File-ACL principals must be an email, grp_<id>, or @all — an agentUid is
+# NOT accepted by `hq files share`. For agent recipients, grants flow through
+# a deterministic per-agent delegation group (the /new-agent pattern):
+# grp_dlg-<uid tail>, containing exactly that agent.
+GRANT_PRINCIPAL="$PRINCIPAL"
+case "$PRINCIPAL" in
+  agt_*)
+    TAIL="$(printf '%s' "$PRINCIPAL" | tail -c 9 | tr '[:upper:]' '[:lower:]')"
+    GRANT_PRINCIPAL="grp_dlg-$TAIL"
+    ;;
+esac
+
+case "$STATUS" in
+  building|granted) ;;
+  *) die "manifest status is '$STATUS' — grants run from 'building' (or re-run from 'granted'), not from there" ;;
+esac
+
+PREFIX_COUNT="$(jq '.vaultPrefixes | length' "$MANIFEST")"
+[ "$PREFIX_COUNT" -gt 0 ] || die "manifest has no vaultPrefixes"
+
+# --- validate every prefix BEFORE touching anything --------------------------
+# Company-relative, trailing-slash folder form. A bare prefix would degrade to
+# a single literal key and grant nothing useful; company-anchored prefixes do
+# not exist in the bucket. Either is a hard error, never a silent grant.
+
+BAD="$(jq -r '.vaultPrefixes[] | .prefix
+  | select((endswith("/") | not) or startswith("companies/") or startswith("/"))' "$MANIFEST")"
+if [ -n "$BAD" ]; then
+  die "prefix violates the hq-files prefix conventions (must be company-relative folder form ending in '/'): $BAD"
+fi
+
+# --- plan (always printed; the only output without --yes) --------------------
+
+echo "Delegation grant plan — company '$COMPANY', recipient '$PRINCIPAL':"
+if [ "$GRANT_PRINCIPAL" != "$PRINCIPAL" ]; then
+  echo "  0. Agent recipient: grants flow through group $GRANT_PRINCIPAL (created if absent, containing exactly $DISPLAY)"
+fi
+echo "  1. Push companies/$COMPANY/projects/$PROJECT/ to the vault (on-conflict keep)"
+jq -r '.vaultPrefixes[] | "  2. Grant \(.permission) on \(.prefix) — \(.reason // "")"' "$MANIFEST"
+WRITE_PREFIXES="$(jq -r '.vaultPrefixes[] | select(.permission == "write") | .prefix' "$MANIFEST")"
+if [ -n "$WRITE_PREFIXES" ]; then
+  echo
+  echo "NOTE: granting 'write' is a privilege escalation. The recipient will be able"
+  echo "to upload, overwrite, and delete under: $(printf '%s ' "$WRITE_PREFIXES")"
+fi
+
+if [ "$YES" -ne 1 ]; then
+  echo
+  echo "hq-delegate-grant: confirmation required — re-run with --yes after the user approves" >&2
+  exit 2
+fi
+
+# --- 1. materialize the dossier AND referenced knowledge in the vault --------
+# (Live finding: granting read on a knowledge prefix is useless if the
+# specific referenced file was never pushed — the recipient's pull succeeds
+# on the prefix and silently misses the file. Push every referenced
+# company-local knowledge/policy path alongside the dossier.)
+
+hq sync push "companies/$COMPANY/projects/$PROJECT/" --company "$COMPANY" --on-conflict keep \
+  || die "vault push failed for companies/$COMPANY/projects/$PROJECT/"
+
+jq -r --arg co "$COMPANY" \
+  '((.knowledge // []) + (.policies // []))[] | select(startswith("companies/" + $co + "/"))' \
+  "$MANIFEST" | while IFS= read -r kpath; do
+  if [ -e "$HQ_ROOT/$kpath" ]; then
+    hq sync push "$kpath" --company "$COMPANY" --on-conflict keep \
+      || die "vault push failed for referenced knowledge: $kpath"
+  else
+    echo "hq-delegate-grant: referenced path missing locally (cannot push): $kpath — the verify probe will fail if it is not already in the vault" >&2
+  fi
+done
+
+# --- 1b. agent recipients: ensure the delegation group exists + contains them
+
+if [ "$GRANT_PRINCIPAL" != "$PRINCIPAL" ]; then
+  # Both calls are idempotent-tolerated: an existing group / existing member
+  # is fine — the ACL read-back below is the arbiter of success.
+  hq groups create "$GRANT_PRINCIPAL" --name "Delegation: $DISPLAY" --company "$COMPANY" \
+    || echo "hq-delegate-grant: group create reported an error (may already exist) — continuing" >&2
+  hq groups add "$GRANT_PRINCIPAL" "$PRINCIPAL" --company "$COMPANY" \
+    || echo "hq-delegate-grant: group add reported an error (may already be a member) — continuing" >&2
+fi
+
+# --- 2+3. exact structured read-back; never infer identity from a new row ---
+# Requires the structured CLI contracts. Unsupported/failed reads stop the flow.
+EXPECTED_TYPE="" EXPECTED_ID="" EXPECTED_COMPANY=""
+case "$GRANT_PRINCIPAL" in
+  grp_*) EXPECTED_TYPE=group; EXPECTED_ID="$GRANT_PRINCIPAL" ;;
+  @all) EXPECTED_TYPE=company-wide; EXPECTED_ID="" ;;
+  *)
+    RESOLVE_RC=0
+    RESOLVED="$(hq people resolve "$PRINCIPAL" --company "$COMPANY" --json --membership-only)" || RESOLVE_RC=$?
+    if printf '%s' "$RESOLVED" | jq -e '.status == "found" and (.person.personUid | type == "string") and (.person.companyUid | type == "string")' >/dev/null; then
+      [ "$RESOLVE_RC" -eq 0 ] || die "recipient resolution failed"
+      EXPECTED_TYPE=person
+      EXPECTED_ID="$(printf '%s' "$RESOLVED" | jq -r '.person.personUid')"
+      EXPECTED_COMPANY="$(printf '%s' "$RESOLVED" | jq -r '.person.companyUid')"
+    elif printf '%s' "$RESOLVED" | jq -e '.status == "not_found"' >/dev/null; then
+      case "$PRINCIPAL" in *@*) EXPECTED_TYPE=email; EXPECTED_ID="$(printf '%s' "$PRINCIPAL" | tr '[:upper:]' '[:lower:]' | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')" ;; *) die "unresolved recipient" ;; esac
+    else
+      die "authoritative recipient lookup failed; update hq-cli if --membership-only is unsupported"
+    fi
+    ;;
+esac
+
+read_acl() {
+  local result
+  result="$(hq files acl "$1" --company "$COMPANY" --json)" || return 1
+  printf '%s' "$result" | jq -e --arg prefix "$1" --arg company "$EXPECTED_COMPANY" '
+    .schemaVersion == 1 and
+    (
+      .prefix == $prefix or
+      (($prefix | endswith("/*")) and .prefix == ($prefix | sub("\\*$"; "")))
+    ) and
+    (.companyUid | type == "string") and ($company == "" or .companyUid == $company) and
+    (.direct | type == "array") and (.exists | type == "boolean")
+  ' >/dev/null || { echo "hq-delegate-grant: invalid structured ACL response for $1" >&2; return 1; }
+  printf '%s' "$result"
+}
+
+NOW="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+i=0
+while [ "$i" -lt "$PREFIX_COUNT" ]; do
+  PFX="$(jq -r ".vaultPrefixes[$i].prefix" "$MANIFEST")"
+  PERM="$(jq -r ".vaultPrefixes[$i].permission" "$MANIFEST")"
+  # Always address the recursive "folder/*" pattern explicitly. Since hq-pro
+  # #3662 (2026-09-23) the server echoes the raw pattern back on read, and a
+  # bare trailing "/" can mean a PRIVATE folder pattern when that flag is on.
+  # A delegation grant is always the recursive share, never a private folder.
+  ACL_PATTERN="${PFX}*"
+  BEFORE="$(read_acl "$ACL_PATTERN")" || die "ACL preflight failed; no share attempted for $PFX"
+  EXPECTED_COMPANY="$(printf '%s' "$BEFORE" | jq -r '.companyUid')"
+  SHARE_RC=0
+  hq files share "$ACL_PATTERN" --with "$GRANT_PRINCIPAL" --permission "$PERM" --company "$COMPANY" || SHARE_RC=$?
+  [ "$SHARE_RC" -eq 0 ] || echo "hq-delegate-grant: share reported an error on $PFX; checking exact grant" >&2
+  landed=0
+  for delay in 0 1 2; do
+    [ "$delay" -eq 0 ] || sleep "$delay"
+    if AFTER="$(read_acl "$ACL_PATTERN")" && printf '%s' "$AFTER" | jq -e \
+      --arg id "$EXPECTED_ID" --arg type "$EXPECTED_TYPE" --arg perm "$PERM" \
+      '.exists and any(.direct[]; .granteeType == $type and .granteeId == $id and .permission == $perm)' >/dev/null; then
+      landed=1
+      break
+    fi
+  done
+  [ "$landed" -eq 1 ] || die "grant outcome unconfirmed for $PRINCIPAL on $PFX; retain this manifest and resume"
+  TMP_MANIFEST="$(mktemp)"
+  jq --argjson i "$i" --arg now "$NOW" --arg id "$EXPECTED_ID" --arg type "$EXPECTED_TYPE" \
+    --arg company "$EXPECTED_COMPANY" --argjson rc "$SHARE_RC" '
+    .vaultPrefixes[$i].verifiedAt = $now |
+    .vaultPrefixes[$i].grantReceipt = {companyUid:$company,granteeType:$type,granteeId:$id,shareExitCode:$rc,verifiedAt:$now}
+  ' "$MANIFEST" > "$TMP_MANIFEST" && mv "$TMP_MANIFEST" "$MANIFEST"
+  echo "hq-delegate-grant: verified $PERM on $PFX for $PRINCIPAL"
+  i=$((i + 1))
+done
+
+# --- 4. advance manifest status ----------------------------------------------
+
+TMP_MANIFEST="$(mktemp)"
+jq --arg now "$NOW" --arg gp "$GRANT_PRINCIPAL" '
+  .status = "granted"
+  | .grantPrincipal = $gp
+  | .vaultPrefixes = [.vaultPrefixes[] | . + {verifiedAt: $now}]
+' "$MANIFEST" > "$TMP_MANIFEST" && mv "$TMP_MANIFEST" "$MANIFEST"
+
+echo "hq-delegate-grant: all $PREFIX_COUNT grants verified — manifest status advanced to 'granted'"

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

@@ -0,0 +1,91 @@
+#!/usr/bin/env bash
+# hq-core: public
+# Publish final delegation artifacts and verify their canonical cloud bytes.
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+HQ_ROOT="${HQ_ROOT:-$(cd "$SCRIPT_DIR/../.." && pwd)}"
+. "$SCRIPT_DIR/lib/secret-patterns.sh"
+die() { echo "hq-delegate-publish: $*" >&2; exit 1; }
+[ "${1:-}" = --manifest ] && [ -f "${2:-}" ] || die 'usage: --manifest <path>'
+MANIFEST="$2"
+LOCK="$MANIFEST.send-lock"
+if [ "${3:-}" = --lock-held ]; then
+  [ -d "$LOCK" ] || die 'verification lock missing'
+  OWN_LOCK=0
+else
+  [ "$#" -eq 2 ] || die 'usage: --manifest <path>'
+  mkdir "$LOCK" 2>/dev/null || die 'verification or delivery is active; retry after it finishes'
+  OWN_LOCK=1
+fi
+STAGE=""
+trap '[[ -z "$STAGE" ]] || rm -rf "$STAGE"; [ "$OWN_LOCK" -eq 0 ] || rmdir "$LOCK"' EXIT
+COMPANY="$(jq -er '.company' "$MANIFEST")"
+PROJECT="$(jq -er '.project.name' "$MANIFEST")"
+ID="$(jq -er '.delegationId' "$MANIFEST")"
+for part in "$COMPANY" "$PROJECT" "$ID"; do
+  [[ "$part" =~ ^[A-Za-z0-9_-][A-Za-z0-9._-]*$ ]] || die 'unsafe path segment'
+done
+jq -e '.status == "granted" or .status == "verified"' "$MANIFEST" >/dev/null || die 'confirmed grants required'
+if [ "$(jq -r '.mode' "$MANIFEST")" = transfer ]; then
+  jq -e '.ownershipTransferredAt != null' "$MANIFEST" >/dev/null || die 'transfer must finish before publication'
+fi
+REL="companies/$COMPANY/projects/$PROJECT"
+PROJECT_DIR="$HQ_ROOT/$REL"
+BUNDLE="$(cd "$(dirname "$MANIFEST")" && pwd)"
+[ -f "$BUNDLE/BRIEF.md" ] || die 'BRIEF.md missing'
+[ -f "$PROJECT_DIR/prd.json" ] || die 'PRD missing'
+if [ "$(jq -r '.mode' "$MANIFEST")" = transfer ]; then
+  EXPECTED_OWNER="$(jq -r '.to.principal' "$MANIFEST")"
+  jq -e --arg owner "$EXPECTED_OWNER" '.metadata.owner == $owner' "$PROJECT_DIR/prd.json" >/dev/null || die 'local PRD owner does not match recipient'
+fi
+STAGE="$(mktemp -d)"
+atomic_copy() {
+  local target_tmp
+  target_tmp="$(mktemp "${2}.tmp.XXXXXX")"
+  if ! cp "$1" "$target_tmp"; then rm -f "$target_tmp"; return 1; fi
+  mv -f "$target_tmp" "$2"
+}
+DEST="$PROJECT_DIR/delegation/$ID"
+cp "$BUNDLE/BRIEF.md" "$STAGE/BRIEF.md"
+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
+}
+# Snapshot final project content, excluding mutable/self-referential receipts.
+: > "$STAGE/hashes"
+for file in "$PROJECT_DIR/prd.json" "$PROJECT_DIR/README.md" "$PROJECT_DIR/journal/delegations.md"; do
+  [ -f "$file" ] || continue
+  jq -cn --arg key "${file#"$HQ_ROOT/"}" --arg value "$(file_hash "$file")" '{key:$key,value:$value}' >> "$STAGE/hashes"
+done
+jq -cn --arg key "$REL/delegation/$ID/BRIEF.md" --arg value "$(file_hash "$STAGE/BRIEF.md")" '{key:$key,value:$value}' >> "$STAGE/hashes"
+jq -s 'from_entries' "$STAGE/hashes" > "$STAGE/checksums"
+jq --slurpfile hashes "$STAGE/checksums" '.checksums=$hashes[0] | .status="granted" | .recipientAccess="unconfirmed" | del(.publication,.verifiedAt,.sentAt,.dmEventId)' "$MANIFEST" > "$STAGE/manifest.json"
+hq_scan_secrets "$STAGE/manifest.json" "$STAGE/BRIEF.md" || die 'unsafe generated dossier'
+if grep -Eq 'share-session/[A-Za-z0-9_-]+' "$STAGE/manifest.json" "$STAGE/BRIEF.md"; then
+  die 'share-session capability in dossier; nothing published'
+fi
+mkdir -p "$DEST"
+atomic_copy "$STAGE/BRIEF.md" "$DEST/BRIEF.md"
+atomic_copy "$STAGE/manifest.json" "$DEST/manifest.json"
+atomic_copy "$STAGE/manifest.json" "$MANIFEST"
+# keep may preserve stale canonical content. Read-back must catch that instead
+# of overwriting concurrent changes merely to make the check pass.
+hq sync push "$REL/" --company "$COMPANY" --on-conflict keep || die 'final dossier push failed; resume publication'
+cp "$STAGE/hashes" "$STAGE/receipts"
+jq -cn --arg key "$REL/delegation/$ID/manifest.json" --arg value "$(file_hash "$DEST/manifest.json")" '{key:$key,value:$value}' >> "$STAGE/receipts"
+while IFS= read -r row; do
+  path="$(printf '%s' "$row" | jq -r '.key')"
+  expected="$(printf '%s' "$row" | jq -r '.value')"
+  matched=0
+  for delay in 0 1 2; do
+    [ "$delay" -eq 0 ] || sleep "$delay"
+    if hq files cat "${path#"companies/$COMPANY/"}" --company "$COMPANY" > "$STAGE/remote"; then
+      if [ "$(file_hash "$STAGE/remote")" = "$expected" ]; then matched=1; break; fi
+    fi
+  done
+  [ "$matched" -eq 1 ] || die "canonical cloud content differs or is unreadable: $path; resolve before sending"
+done < "$STAGE/receipts"
+jq -s 'from_entries' "$STAGE/receipts" > "$STAGE/files"
+jq --arg now "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg path "$REL/delegation/$ID/manifest.json" --slurpfile files "$STAGE/files" \
+  '.publication={verifiedAt:$now,manifestPath:$path,files:$files[0]} | .recipientAccess="unconfirmed"' "$MANIFEST" > "$STAGE/updated"
+atomic_copy "$STAGE/updated" "$MANIFEST"
+echo 'hq-delegate-publish: canonical dossier bytes verified as sender; recipient access unconfirmed'

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'"