@indigoai-us/hq-cli 5.314.0 → 5.315.0

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