@quickchatai/quickreview 0.0.0-stage → 1.1.0

package/deploy/ansible/playbook.yml

@@ -0,0 +1,360 @@
+---
+# Review-sandbox PROVISIONING -- one VM, cloudflared on the host, the thin
+# updater installed once. See README.md in this directory. Idempotent; re-run
+# freely. Run it through scripts/deploy.sh provision, which names the extra
+# vars (base_clone_dir, secrets_src, the Slack token names and update_conf_src,
+# the run spec it renders from group_vars).
+#
+# This playbook installs the host, the secrets, the directory layout and the
+# updater (/usr/local/sbin/qcr-update, deploy/qcr-update.sh) with its run spec
+# (/etc/qcr/update.conf). It NEVER pulls or starts an image: every deploy is
+# `scripts/deploy.sh release <version>`, which runs `ssh vm sudo qcr-update ...`
+# (the images are built once by CI and pulled by digest; the containers are the
+# updater's). Nothing is rsynced, built or installed on the VM by a deploy.
+
+- name: Preflight — refuse to trample the shared VM
+  hosts: quickreview
+  become: true
+  tasks:
+    - name: Is the sandbox already installed here? (re-runs are fine)
+      ansible.builtin.stat:
+        path: "{{ sandbox_root }}"
+      register: sandbox_dir
+
+    - name: Check whether the webhook port is already bound
+      ansible.builtin.command: ss -ltnH sport = :{{ webhook_port }}
+      register: port_check
+      changed_when: false
+
+    - name: "Fail: port {{ webhook_port }} is taken by something that is not us"
+      ansible.builtin.fail:
+        msg: >-
+          Port {{ webhook_port }} is already bound on the VM and
+          {{ sandbox_root }} does not exist — another service owns it. Pick a
+          different webhook_port or free the port before deploying.
+      when: not sandbox_dir.stat.exists and port_check.stdout | trim | length > 0
+
+    - name: Check for a pre-existing cloudflared service
+      ansible.builtin.systemd:
+        name: cloudflared
+      register: cf_service
+      failed_when: false
+      when: cloudflared_enabled | bool
+
+    - name: "Fail: a foreign cloudflared already runs here"
+      ansible.builtin.fail:
+        msg: >-
+          cloudflared.service is already active on the VM but the sandbox
+          was never installed — it is serving someone else's tunnel. The
+          `cloudflared service install` step would clobber it. Wire the
+          quickreview hostname into the existing tunnel instead, or run the two
+          side by side manually, then re-run with `-e cloudflared_enabled=false`.
+      when: >-
+        cloudflared_enabled | bool and
+        not sandbox_dir.stat.exists and
+        cf_service.status is defined and
+        (cf_service.status.ActiveState | default('inactive')) == 'active'
+
+    - name: "Fail: not enough free disk"
+      ansible.builtin.fail:
+        msg: "Less than {{ min_free_disk_gb }} GB free on / — the shared VM is too full for the image + worktrees."
+      vars:
+        root_mount: "{{ ansible_mounts | selectattr('mount', 'equalto', '/') | first }}"
+      when: (root_mount.size_available | int) < (min_free_disk_gb | int) * 1024 * 1024 * 1024
+
+# The cloudflared tasks below are OPTIONAL: `cloudflared_enabled`
+# defaults true in group_vars — the live deployment keeps its tunnel — but any
+# other HTTPS ingress to the published webhook port works just as well. Set
+# `-e cloudflared_enabled=false` and bring your own proxy/tunnel; nothing else
+# in this playbook depends on the tunnel existing.
+- name: Host setup — packages, Docker, cloudflared tunnel (optional)
+  hosts: quickreview
+  become: true
+  vars:
+    base_packages: [python3-docker, git, curl, ca-certificates, gnupg, rsync]
+  tasks:
+    # Refresh the apt cache only when a package is actually missing. The VM
+    # is shared and carries third-party repos we do not own; a broken one makes
+    # python-apt's cache update fail (with an empty error), and an unconditional
+    # update_cache would then fail every rebuild even with every package
+    # already installed.
+    - name: Installed packages
+      ansible.builtin.package_facts:
+
+    - name: Base packages
+      ansible.builtin.apt:
+        name: "{{ base_packages }}"
+        state: present
+        update_cache: true
+      when: base_packages | difference(ansible_facts.packages.keys() | list) | length > 0
+
+    # The VM already runs Docker CE (containerd.io conflicts with
+    # docker.io's containerd) — only install a Docker at all when none exists.
+    - name: Is Docker already installed?
+      ansible.builtin.command: docker --version
+      register: docker_present
+      changed_when: false
+      failed_when: false
+
+    - name: Install docker.io when Docker is absent
+      ansible.builtin.apt:
+        name: docker.io
+        state: present
+      when: docker_present.rc != 0
+
+    - name: Docker service enabled and running
+      ansible.builtin.systemd:
+        name: docker
+        state: started
+        enabled: true
+
+    - name: Cloudflare package signing key
+      ansible.builtin.get_url:
+        url: https://pkg.cloudflare.com/cloudflare-main.gpg
+        dest: /usr/share/keyrings/cloudflare-main.gpg
+        mode: "0644"
+      when: cloudflared_enabled | bool
+
+    - name: Cloudflared apt repository
+      ansible.builtin.apt_repository:
+        repo: "deb [signed-by=/usr/share/keyrings/cloudflare-main.gpg] https://pkg.cloudflare.com/cloudflared {{ ansible_distribution_release }} main"
+        filename: cloudflared
+        state: present
+      when: cloudflared_enabled | bool
+
+    - name: Install cloudflared
+      ansible.builtin.apt:
+        name: cloudflared
+        state: present
+        # Same rule as the base packages: no cache refresh for a package the
+        # host already has.
+        update_cache: "{{ 'cloudflared' not in ansible_facts.packages }}"
+      when: cloudflared_enabled | bool
+
+    - name: Register cloudflared as a systemd service (remote-managed tunnel)
+      ansible.builtin.command:
+        cmd: cloudflared service install {{ lookup('file', secrets_src + '/tunnel_token') | trim }}
+        creates: /etc/systemd/system/cloudflared.service
+      no_log: true
+      when: cloudflared_enabled | bool
+
+    - name: Cloudflared service running
+      ansible.builtin.systemd:
+        name: cloudflared
+        state: started
+        enabled: true
+      when: cloudflared_enabled | bool
+
+- name: Provision — directory layout, secrets, the updater and its run spec
+  hosts: quickreview
+  become: true
+  tasks:
+    - name: Directory layout (container user = uid {{ container_uid }})
+      ansible.builtin.file:
+        path: "{{ item.path }}"
+        state: directory
+        mode: "{{ item.mode }}"
+        owner: "{{ item.owner | default(container_uid) }}"
+        group: "{{ item.group | default(item.owner | default(container_uid)) }}"
+      loop:
+        - { path: "{{ sandbox_root }}", mode: "0755", owner: "root" }
+        - { path: "{{ sandbox_root }}/sandbox", mode: "0755" }
+        # Shared with the model's tools through their own gid (tool_gid), as
+        # the bot's entrypoint sets it (share_tool_dirs): setgid, so what
+        # either side makes stays in that group, and sticky, so the tool uid
+        # never renames or removes the daemon's entries (state.db among them).
+        - { path: "{{ sandbox_root }}/state", mode: "3775", group: "{{ tool_gid }}" }
+        # OpenViking's home: ~/.openviking is symlinked here at boot,
+        # so memories + vector db + ov.conf survive an image rebuild. 0700 —
+        # ov.conf carries the server's root key (and, under the hosted
+        # embeddings opt-in, that credential too).
+        - { path: "{{ openviking_home }}", mode: "0700" }
+        - { path: "{{ sandbox_root }}/pihome", mode: "0700" }
+        - { path: "{{ sandbox_root }}/secrets", mode: "0700" }
+        # The install's config home as the updater ships it (config.toml +
+        # profiles/ from the tar on its stdin), mounted read-only. Created
+        # here so the first bind mount has a source.
+        - { path: "{{ sandbox_root }}/config-home", mode: "0755" }
+
+    - name: Secrets into place (readable only by the container user)
+      ansible.builtin.copy:
+        src: "{{ secrets_src }}/{{ item }}"
+        dest: "{{ sandbox_root }}/secrets/{{ item }}"
+        mode: "0400"
+        owner: "{{ container_uid }}"
+        group: "{{ container_uid }}"
+      loop: [app_id, app.pem, webhook_secret]
+      no_log: true
+
+    # Optional — the deployment uses the ChatGPT-OAuth route: pi auths via
+    # `/login` inside the container; the key file ships only if present.
+    - name: OpenAI API key (optional under the OAuth route)
+      ansible.builtin.copy:
+        src: "{{ secrets_src }}/openai_api_key"
+        dest: "{{ sandbox_root }}/secrets/openai_api_key"
+        mode: "0400"
+        owner: "{{ container_uid }}"
+        group: "{{ container_uid }}"
+      no_log: true
+      when: lookup('ansible.builtin.fileglob', secrets_src + '/openai_api_key') | length > 0
+
+    # The HOSTED embeddings credential — a separate file from pi's
+    # key, present only when the operator opted into a hosted embedder
+    # (openviking_embedding_provider != local). Copied-if-present; absent by
+    # default, because the shipped embedder is local and needs no key.
+    - name: Hosted embeddings key (optional — only under the hosted-embedder opt-in)
+      ansible.builtin.copy:
+        src: "{{ secrets_src }}/{{ openviking_embedding_key_file }}"
+        dest: "{{ sandbox_root }}/secrets/{{ openviking_embedding_key_file }}"
+        mode: "0400"
+        owner: "{{ container_uid }}"
+        group: "{{ container_uid }}"
+      no_log: true
+      when: lookup('ansible.builtin.fileglob', secrets_src + '/' + openviking_embedding_key_file) | length > 0
+
+    # The OpenViking auth keys. Copied-if-present, matching the
+    # openai_api_key idiom — a missing root key degrades the boot LOUDLY to
+    # auth_mode=dev (the entrypoint warns), it never blocks the deploy. The
+    # companion key must NEVER be in this list (rule 8: it never touches the VM).
+    - name: OpenViking auth keys (root + reviewer; confinement is dev-mode without them)
+      ansible.builtin.copy:
+        src: "{{ secrets_src }}/{{ item }}"
+        dest: "{{ sandbox_root }}/secrets/{{ item }}"
+        mode: "0400"
+        owner: "{{ container_uid }}"
+        group: "{{ container_uid }}"
+      loop: ["{{ openviking_root_key_file }}", "{{ openviking_reviewer_key_file }}"]
+      no_log: true
+      when: lookup('ansible.builtin.fileglob', secrets_src + '/' + item) | length > 0
+
+    # The Slack concierge's tokens, under the configured [slack] token file
+    # names. Copied-if-present: Slack is
+    # optional and off by default, but with `[slack] enabled = true` a missing
+    # token is a hard startup error (validateSlackConfig), so whatever the
+    # Slack wizard saved in the secrets dir must reach the container.
+    - name: Slack tokens (optional — present once the Slack wizard has run)
+      ansible.builtin.copy:
+        src: "{{ secrets_src }}/{{ item }}"
+        dest: "{{ sandbox_root }}/secrets/{{ item }}"
+        mode: "0400"
+        owner: "{{ container_uid }}"
+        group: "{{ container_uid }}"
+      loop: ["{{ slack_bot_token_file }}", "{{ slack_app_token_file }}"]
+      no_log: true
+      when: lookup('ansible.builtin.fileglob', secrets_src + '/' + item) | length > 0
+
+    # ---- the thin updater ------------------------------------------------------
+    # Installed ONCE, here. After this, a deploy is
+    # `ssh vm sudo qcr-update <version>@<digest> ...` and nothing else runs on
+    # the VM. The script is deploy/qcr-update.sh from the checkout this
+    # playbook came from; the run spec is rendered by scripts/deploy.sh from
+    # group_vars (and the inventory's host vars over them) so the controller
+    # can recompute its fingerprint and refuse a drift with "re-run provision".
+    - name: The updater's directories (root only)
+      ansible.builtin.file:
+        path: "{{ item.path }}"
+        state: directory
+        mode: "{{ item.mode }}"
+        owner: root
+        group: root
+      loop:
+        - { path: /etc/qcr, mode: "0755" }
+        - { path: /var/backups/qcr, mode: "0700" }
+        - { path: /var/lib/qcr-update, mode: "0700" }
+
+    - name: The updater (/usr/local/sbin/qcr-update, root 0755)
+      ansible.builtin.copy:
+        src: "{{ playbook_dir }}/../qcr-update.sh"
+        dest: /usr/local/sbin/qcr-update
+        mode: "0755"
+        owner: root
+        group: root
+
+    - name: The updater's run spec (/etc/qcr/update.conf, root-owned)
+      ansible.builtin.copy:
+        src: "{{ update_conf_src | mandatory }}"
+        dest: /etc/qcr/update.conf
+        mode: "0644"
+        owner: root
+        group: root
+
+    # Re-seal an existing channel without granting authority to session-owned
+    # files, creating the daemon's commands/ parent, or following a symlink.
+    - name: Operator command channel present?
+      ansible.builtin.stat:
+        path: "{{ sandbox_root }}/sandbox/commands/operator"
+      register: operator_channel
+
+    - name: Operator command channel stays root-owned 0755 (the seal)
+      ansible.builtin.file:
+        path: "{{ sandbox_root }}/sandbox/commands/operator"
+        state: directory
+        owner: "0"
+        group: "0"
+        mode: "0755"
+      when: operator_channel.stat.exists and operator_channel.stat.isdir and not operator_channel.stat.islnk
+
+    # Docker would create a missing bind-mount source as root, which the
+    # container user could not write. The host directories are the SAME ones the
+    # legacy container mounted whole as /opt/quickreview/sandbox; the release image's
+    # app root is read-only, so each runtime directory is mounted on its own (by
+    # the updater). commands/ is created for the container user only; the
+    # operator channel below it is never created here (see the seal).
+    - name: Runtime directories the containers mount (container user = uid {{ container_uid }})
+      ansible.builtin.file:
+        path: "{{ sandbox_root }}/sandbox/{{ item }}"
+        state: directory
+        mode: "0755"
+        owner: "{{ container_uid }}"
+        group: "{{ container_uid }}"
+      loop:
+        - wt
+        - archive
+        - digest
+        - inject
+        # the PR sessions' own HOME (<app root>/pihome)
+        - pihome
+        - "{{ base_clone_dir | mandatory }}"
+
+    # What the model's tools write (their scripts' verdicts and session
+    # commands), shared through the tool gid exactly as the bot's entrypoint
+    # sets it, so a provision never takes it back from a running bot: setgid on
+    # both; commands/ also sticky (the root-owned operator channel inside it
+    # cannot be renamed away); verdict/ not, since commit-verdict.sh, run as the
+    # tool uid, publishes by renaming what the session's write tool staged.
+    - name: Directories shared with the model's tools (tool gid {{ tool_gid }})
+      ansible.builtin.file:
+        path: "{{ sandbox_root }}/sandbox/{{ item.path }}"
+        state: directory
+        mode: "{{ item.mode }}"
+        owner: "{{ container_uid }}"
+        group: "{{ tool_gid }}"
+      loop:
+        - { path: commands, mode: "3775" }
+        - { path: verdict, mode: "2775" }
+
+    # The memory sidecar's store directories. The sidecar CONTAINER and its
+    # network are the updater's; its store is seeded from the daemon's once, by
+    # the updater, on the legacy layout.
+    - name: Directories for the sidecar's store (container user = uid {{ container_uid }})
+      ansible.builtin.file:
+        path: "{{ item }}"
+        state: directory
+        mode: "0700"
+        owner: "{{ container_uid }}"
+        group: "{{ container_uid }}"
+      loop:
+        - "{{ openviking_home }}"
+        - "{{ memory_state_dir }}"
+
+    - name: Note — what happens next
+      ansible.builtin.debug:
+        msg: >-
+          Provisioned. No image was pulled or started. Deploy with
+          `scripts/deploy.sh release <version>`. The webhook port is published on
+          127.0.0.1:{{ webhook_port }} only by the daemon container the updater
+          creates.
+          {% if cloudflared_enabled | bool %}cloudflared forwards the public
+          hostname -> localhost:{{ webhook_port }} -> container.{% else %}
+          cloudflared is disabled (cloudflared_enabled=false) — point your own
+          HTTPS proxy or tunnel at localhost:{{ webhook_port }}.{% endif %}

package/deploy/collect-secrets.sh

@@ -0,0 +1,289 @@
+#!/usr/bin/env bash
+# Interactive wizard: collect the quickreview secrets into the install's secrets
+# dir — $QC_SECRETS_DIR, else the install locator's answer: the live config's
+# [github] secrets_dir when set, else <config home>/secrets
+# (~/.config/qcr/<install>/secrets) — the dir deploy.sh and the daemon read. An old
+# ~/.config/quickreview-bot/ is never read (`qcr install migrate` moves it).
+# Values are read with hidden input and NEVER printed back. Re-run any time —
+# existing files are kept unless you choose to replace them.
+#
+# `scripts/qcr onboard` writes app_id / app.pem / webhook_secret itself, from
+# the GitHub App manifest exchange, and mints the OpenViking keys — so on the
+# guided path you only reach for this script for the values it points you at
+# (the OpenAI key, a tunnel token, an ngrok authtoken, the hosted-embeddings
+# key under that opt-in). It writes the same file
+# names with the same validation and the same 0600 mode; the two paths must
+# stay in step. See docs/onboarding.md.
+#
+# The wizard is deployment-shape-aware: the first choice is HOW the
+# GitHub webhook reaches the daemon, and the required set follows from it.
+#   tunnel — a Cloudflare Tunnel on the host fronts the webhook port
+#            (tunnel_token REQUIRED)
+#   docker — plain Docker; you bring your own ingress/TLS to the webhook port
+#            (tunnel_token not needed)
+# The choice persists in <secrets dir>/deploy_shape; QC_DEPLOY_SHAPE=tunnel|docker
+# overrides it non-interactively.
+#
+#   bash deploy/collect-secrets.sh          # prompt for whatever is missing
+#   bash deploy/collect-secrets.sh --force  # offer to replace existing files too
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+. "$ROOT/scripts/install-locator.sh"
+
+# [github] secrets_dir out of the live config, as written — "" when the config
+# or the key is absent, which leaves the choice to the install locator.
+configured_secrets_dir() {
+  local config
+  config="$(qcr_locate_config "$ROOT" 2>/dev/null)" || return 0
+  [[ -r "$config" ]] || return 0
+  awk '
+    /^\[github\][[:space:]]*(#.*)?$/ { in_t = 1; next }
+    /^\[/                            { in_t = 0 }
+    in_t && /^[[:space:]]*secrets_dir[[:space:]]*=/ {
+      line = $0
+      sub(/^[^=]*=[[:space:]]*/, "", line)
+      sub(/[[:space:]]*(#.*)?$/, "", line)
+      gsub(/^["'"'"']|["'"'"']$/, "", line)
+      print line
+      exit
+    }
+  ' "$config"
+}
+
+if [[ -n "${QC_SECRETS_DIR:-}" ]]; then
+  DIR="$(qcr_locate_secrets "" "$QC_SECRETS_DIR")"
+else
+  DIR="$(qcr_locate_secrets "$(configured_secrets_dir)")" || exit 1
+fi
+FORCE=0
+[[ "${1:-}" == "--force" ]] && FORCE=1
+
+bold() { printf '\033[1m%s\033[0m\n' "$*"; }
+ok()   { printf '  \033[32m✔\033[0m %s\n' "$*"; }
+bad()  { printf '  \033[31m✘\033[0m %s\n' "$*"; }
+info() { printf '  · %s\n' "$*"; }
+
+mkdir -p "$DIR"
+chmod 700 "$DIR"
+
+SHAPE_FILE="$DIR/deploy_shape"
+
+status_of() { # file
+  if [[ -s "$DIR/$1" ]]; then
+    printf 'present (%s bytes, %s)' "$(wc -c < "$DIR/$1" | tr -d ' ')" "$(date -r "$DIR/$1" '+%Y-%m-%d %H:%M')"
+  else
+    printf 'MISSING'
+  fi
+}
+
+shape() { # -> "tunnel" | "docker" | "" (unset)
+  if [[ -s "$SHAPE_FILE" ]]; then cat "$SHAPE_FILE"; fi
+}
+
+save_shape() { # tunnel|docker
+  umask 077
+  printf '%s' "$1" > "$SHAPE_FILE"
+  chmod 600 "$SHAPE_FILE"
+}
+
+choose_shape() {
+  if [[ -n "${QC_DEPLOY_SHAPE:-}" ]]; then
+    case "$QC_DEPLOY_SHAPE" in
+      tunnel|docker) save_shape "$QC_DEPLOY_SHAPE"; info "deployment shape: $QC_DEPLOY_SHAPE (from QC_DEPLOY_SHAPE)"; return 0 ;;
+      *) bad "QC_DEPLOY_SHAPE must be 'tunnel' or 'docker' (got: $QC_DEPLOY_SHAPE)"; exit 1 ;;
+    esac
+  fi
+  local current; current="$(shape)"
+  if [[ -n "$current" && $FORCE -eq 0 ]]; then
+    info "deployment shape: $current (stored; re-run with --force to change)"
+    return 0
+  fi
+  bold "deployment shape — how does the GitHub webhook reach the daemon?"
+  info "1) tunnel — Cloudflare Tunnel on the host fronts the webhook port (needs tunnel_token)"
+  info "2) docker — plain Docker; you bring your own ingress/TLS to the webhook port (no tunnel_token)"
+  local a
+  while true; do
+    if ! read -r -p "  choose [1/2]${current:+ (Enter keeps: $current)}: " a; then
+      [[ -n "$current" ]] && { save_shape "$current"; return 0; }
+      bad "no input — set QC_DEPLOY_SHAPE=tunnel|docker to choose non-interactively"
+      exit 1
+    fi
+    case "$a" in
+      1|tunnel) save_shape tunnel; break ;;
+      2|docker) save_shape docker; break ;;
+      "") if [[ -n "$current" ]]; then save_shape "$current"; break; fi; bad "pick 1 or 2" ;;
+      *) bad "pick 1 or 2" ;;
+    esac
+  done
+  ok "deployment shape: $(shape)"
+}
+
+overview() {
+  local s; s="$(shape)"
+  bold "quickreview secrets — $DIR  (deployment shape: ${s:-unset})"
+  for f in app_id app.pem webhook_secret tunnel_token openai_api_key openai_embeddings_api_key openviking_root_key openviking_reviewer_key; do
+    printf '  %-24s %s\n' "$f" "$(status_of "$f")"
+  done
+  if [[ "$s" == "docker" ]]; then
+    info "tunnel_token is NOT required under the docker shape (own ingress)"
+  else
+    info "tunnel_token is required under the tunnel shape"
+  fi
+  info "openai_api_key is OPTIONAL (pi's model credential on the API-key route; ChatGPT-OAuth route: pi /login instead)"
+  info "openai_embeddings_api_key is OPTIONAL and SEPARATE: memory embeds LOCALLY by default and nothing"
+  info "but the model call leaves the machine. Only a hosted-embeddings opt-in (config.toml [openviking]"
+  info "embedding_provider = \"openai\") reads it — pi's key is never used for embeddings."
+  info "openviking_root_key / openviking_reviewer_key: memory. Missing root key => the"
+  info "server falls back to auth_mode=dev and per-user confinement is NOT enforced."
+  info "NEVER put the COMPANION key here — a review session could read it (rule 8)."
+  echo
+}
+
+want() { # file  -> 0 if we should prompt for it
+  if [[ -s "$DIR/$1" ]]; then
+    if [[ $FORCE -eq 1 ]]; then
+      read -r -p "  $1 exists — replace it? [y/N] " a
+      [[ "$a" == "y" || "$a" == "Y" ]]
+    else
+      return 1
+    fi
+  fi
+}
+
+save() { # file  (value on stdin)
+  umask 077
+  cat > "$DIR/$1"
+  chmod 600 "$DIR/$1"
+}
+
+prompt_hidden() { # file  label  validator-fn
+  local file=$1 label=$2 validate=$3 value
+  while true; do
+    read -r -s -p "  paste $label (input hidden, Enter to submit; empty to skip): " value || value=""
+    echo
+    if [[ -z "$value" ]]; then
+      info "skipped $file"
+      return 0
+    fi
+    if printf '%s' "$value" | "$validate"; then
+      printf '%s' "$value" | save "$file"
+      ok "$file saved"
+      return 0
+    fi
+    bad "that doesn't look right — try again (or Enter to skip)"
+  done
+}
+
+# ---- validators (read candidate on stdin, exit 0/1, print reason on stderr) --
+v_app_id()   { grep -qE '^[0-9]{1,12}$' || { echo "    app_id must be a number (GitHub App settings → App ID)" >&2; return 1; }; }
+v_secret()   { local v; v="$(cat)"; [[ ${#v} -ge 8 ]] || { echo "    suspiciously short (<8 chars)" >&2; return 1; }; }
+v_token()    { local v; v="$(cat)"; [[ ${#v} -ge 60 && "$v" != *" "* ]] || { echo "    tunnel token should be one long unbroken string (connector page → the string after 'cloudflared service install')" >&2; return 1; }; }
+# The same rule as validateOpenAiKey (src/onboard/steps/llmauth.ts): sk- plus at
+# least one more character, one unbroken string. tests/onboard-llmauth.test.ts
+# runs this function against the TypeScript validator's table. The whitespace
+# list is ECMAScript whitespace, matched as exact strings regardless of locale.
+v_openai()   { local v c; v="$(cat)"; for c in $'\t' $'\n' $'\v' $'\f' $'\r' ' ' $'\xc2\xa0' $'\xe1\x9a\x80' $'\xe2\x80\x80' $'\xe2\x80\x81' $'\xe2\x80\x82' $'\xe2\x80\x83' $'\xe2\x80\x84' $'\xe2\x80\x85' $'\xe2\x80\x86' $'\xe2\x80\x87' $'\xe2\x80\x88' $'\xe2\x80\x89' $'\xe2\x80\x8a' $'\xe2\x80\xa8' $'\xe2\x80\xa9' $'\xe2\x80\xaf' $'\xe2\x81\x9f' $'\xe3\x80\x80' $'\xef\xbb\xbf'; do if [[ "$v" == *"$c"* ]]; then v=""; break; fi; done; [[ "$v" == sk-?* ]] || { echo "    OpenAI keys start with sk- and contain no spaces" >&2; return 1; }; }
+# OpenViking keys have no documented prefix — length and "one unbroken string"
+# is everything we can honestly assert about them.
+v_nonempty() { local v; v="$(cat)"; [[ ${#v} -ge 16 && "$v" != *" "* ]] || { echo "    expected one unbroken string of at least 16 characters" >&2; return 1; }; }
+
+prompt_pem() {
+  want app.pem || return 0
+  bold "app.pem — the GitHub App private key"
+  info "GitHub → Settings → Developer settings → GitHub Apps → your App → Private keys"
+  read -r -e -p "  path to the downloaded .pem (or Enter to paste it instead): " pempath || return 0
+  if [[ -n "$pempath" ]]; then
+    pempath="${pempath/#\~/$HOME}"
+    [[ -r "$pempath" ]] || { bad "cannot read $pempath"; return 1; }
+    save app.pem < "$pempath"
+  else
+    info "paste the whole PEM, then Ctrl-D on an empty line:"
+    save app.pem
+  fi
+  if openssl pkey -in "$DIR/app.pem" -noout 2>/dev/null; then
+    ok "app.pem saved (valid private key)"
+  else
+    bad "app.pem does not parse as a private key — re-run to fix"
+    rm -f "$DIR/app.pem"
+    return 1
+  fi
+}
+
+choose_shape
+overview
+
+if want app_id; then
+  bold "app_id — the numeric GitHub App ID"
+  prompt_hidden app_id "the App ID" v_app_id
+fi
+
+prompt_pem || true
+
+if want webhook_secret; then
+  bold "webhook_secret — the secret on the App's webhook config"
+  prompt_hidden webhook_secret "the webhook secret" v_secret
+fi
+
+if [[ "$(shape)" == "tunnel" ]]; then
+  if want tunnel_token; then
+    bold "tunnel_token — Cloudflare Zero Trust → Networks → Tunnels → connector token"
+    prompt_hidden tunnel_token "the tunnel token" v_token
+  fi
+fi
+
+if want openai_api_key; then
+  bold "openai_api_key — OPTIONAL: pi's model credential on the API-key route (skip under ChatGPT OAuth)"
+  info "NOT used for memory embeddings — those run locally unless you opt into a hosted embedder below"
+  prompt_hidden openai_api_key "the OpenAI API key" v_openai
+fi
+
+# The HOSTED embeddings credential, its OWN file. The shipped
+# default embeds memory locally (nothing but the model call leaves), so this
+# is needed ONLY by an operator who set config.toml [openviking]
+# embedding_provider = "openai". Kept separate from pi's key on purpose: either
+# can be set without the other.
+if want openai_embeddings_api_key; then
+  bold "openai_embeddings_api_key — OPTIONAL: only under the hosted-embeddings opt-in (skip to keep memory local)"
+  info "read by the memory engine alone; leaving it unset changes nothing about pi's credential"
+  prompt_hidden openai_embeddings_api_key "the OpenAI key for embeddings" v_openai
+fi
+
+# The memory engine's identity. Two files, and only two: the SERVER's
+# own root key (ov.conf needs it to run in api_key mode; boot provisioning uses
+# it to create users) and the REVIEWER user key (the one client credential this
+# container may hold). The COMPANION key never belongs on this machine: review
+# sessions run in this container, and a companion key they could read would
+# defeat the confinement entirely.
+if want openviking_root_key; then
+  bold "openviking_root_key — the OpenViking SERVER root key (api_key mode + boot provisioning)"
+  info "never handed to a session, the companion, or the daemon; ov.conf holds it 0600"
+  prompt_hidden openviking_root_key "the OpenViking root key" v_nonempty
+fi
+
+if want openviking_reviewer_key; then
+  bold "openviking_reviewer_key — the reviewer USER key (daemon + every review session)"
+  info "the SAME value goes in $(qcr_locate_keys_file) on your PC"
+  prompt_hidden openviking_reviewer_key "the reviewer USER key" v_nonempty
+fi
+
+echo
+overview
+SHAPE_NOW="$(shape)"
+required=(app_id app.pem webhook_secret)
+if [[ "$SHAPE_NOW" == "tunnel" ]]; then
+  required+=(tunnel_token)
+fi
+missing=0
+for f in "${required[@]}"; do
+  [[ -s "$DIR/$f" ]] || { bad "still missing: $f"; missing=1; }
+done
+if [[ $missing -eq 0 ]]; then
+  ok "all required secrets in place for the '$SHAPE_NOW' shape — tell the session 'secrets done' to continue the deploy"
+  if [[ "$SHAPE_NOW" == "docker" && -s "$DIR/tunnel_token" ]]; then
+    info "tunnel_token is present but unused under the docker shape"
+  fi
+else
+  info "re-run this wizard to fill the gaps (deploy will refuse until they exist)"
+  exit 1
+fi