@quickchatai/quickreview 0.0.0-stage → 1.1.0

package/docker/memory/Dockerfile

@@ -0,0 +1,191 @@
+# The memory sidecar image: OpenViking, its venv, llama-cpp-python and the
+# pinned GGUF, run by the same supervisors the daemon uses in-container.
+#
+#   docker build -f docker/memory/Dockerfile -t qcr-memory .
+#
+# The build context is the repo root, narrowed by
+# docker/memory/Dockerfile.dockerignore (BuildKit reads it in preference to the
+# root .dockerignore).
+#
+# WHAT IT IS. The daemon's `[openviking] endpoint = "local"` (the default, and
+# every live daemon today) supervises the server and the local embedder as its
+# own children, in its own container. With `endpoint = "remote"` the daemon
+# only probes a server somebody else runs, and THIS image is that somebody:
+# entrypoint.sh renders ov.conf, runs the embedder migration's `prepare`, and
+# provisions the users, then execs src/openviking/sidecar-main.ts, which
+# supervises the server and the embedder and drives the re-embed.
+#
+# The four OpenViking pins of the version-pinning rule move here intact (the vendored
+# extension's base commit rides the repo, not an image). The ARG defaults below
+# are a MIRROR of config.toml [openviking] and deploy/ansible/group_vars/
+# all.yml: tests/memory-image.test.ts fails the moment one drifts, the same
+# discipline as the release image's pins (tests/release-image.test.ts). Bump a
+# pin deliberately - config.toml + group_vars + this Dockerfile together, never
+# one alone - and never change the embedder under a live store without the
+# re-embed migration (docs/memory-embeddings.md).
+ARG NODE_MAJOR=26
+
+# ---- build ---------------------------------------------------------------------
+# Compiles the TypeScript; the sidecar ships dist/, the review core's
+# compiled package (the config parser's review half is the core's), and the
+# one runtime package their import closure reaches (smol-toml -
+# tests/memory-image.test.ts holds the closure to the COPY lines below).
+FROM node:${NODE_MAJOR}-bookworm AS build
+WORKDIR /src
+COPY package.json package-lock.json ./
+# A workspace's manifest must be in place before `npm ci`, which links it.
+COPY packages/pi-plugin/package.json packages/pi-plugin/package.json
+RUN npm ci --no-audit --no-fund
+COPY tsconfig.json ./
+COPY scripts/verify-dist.mjs scripts/verify-dist.mjs
+COPY packages packages
+COPY src src
+COPY extensions extensions
+RUN npx tsc -b && node scripts/verify-dist.mjs
+
+# ---- memory --------------------------------------------------------------------
+FROM ubuntu:24.04 AS memory
+
+# ---- pinned versions (mirror of config.toml + group_vars; see header) -----------
+ARG TZ=Europe/Warsaw
+ARG NODE_MAJOR
+ARG OPENVIKING_VERSION=0.4.15
+ARG LLAMA_CPP_PYTHON_VERSION=0.3.35
+ARG OPENVIKING_VENV=/opt/openviking/venv
+ARG LOCAL_EMBEDDER_MODEL=bge-small-en-v1.5-f16
+ARG LOCAL_EMBEDDER_DIR=/opt/openviking/models
+ARG LOCAL_EMBEDDER_URL=https://huggingface.co/CompendiumLabs/bge-small-en-v1.5-gguf/resolve/d32f8c040ea3b516330eeb75b72bcc2d3a780ab7/bge-small-en-v1.5-f16.gguf
+ARG LOCAL_EMBEDDER_SHA256=f0b2fef971e8366438bfd2d9aefea1b0115919389448806d290237f638bae999
+ARG OPENVIKING_PORT=1933
+# set by buildx per platform: the llama build below targets it, never the build host
+ARG TARGETARCH
+
+ENV DEBIAN_FRONTEND=noninteractive \
+    TZ=${TZ}
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+      ca-certificates curl tzdata \
+      build-essential python3 \
+    && rm -rf /var/lib/apt/lists/*
+
+# Node (NodeSource): the supervisors and the boot scripts are node.
+RUN curl -fsSL "https://deb.nodesource.com/setup_${NODE_MAJOR}.x" | bash - \
+    && apt-get install -y --no-install-recommends nodejs \
+    && rm -rf /var/lib/apt/lists/*
+
+# OpenViking - the context store, in its own venv so its ~90 Python deps never
+# collide with anything system-side.
+#
+# llama-cpp-python is installed FIRST and deliberately: it is NOT an openviking
+# dependency but an undeclared optional extra, and without it the default local
+# dense embedder raises EmbeddingConfigurationError at startup - the official
+# image cannot boot (verified against a running 0.4.15). It is also the
+# runtime of the local English embedder (the model layer below). Do not "clean
+# it up".
+#
+# Both versions come from the ARG mirror above (== config.toml [openviking] ==
+# group_vars); a literal here would be exactly the drift the pin prevents. The
+# layer hard-fails unless the INSTALLED distribution reports the pinned version
+# and the server entry point exists.
+#
+# llama-cpp-python compiles llama.cpp from source, and by default for the BUILD
+# host's CPU (-march=native). CI's runners have AVX-512; the VM's Xeon does not,
+# so a native build dies of SIGILL on the VM (the 1.0.2 cutover). The build is
+# therefore portable: on amd64 the AVX2 level (AVX, AVX2, FMA, F16C) and nothing
+# newer, on arm64 the architecture's baseline. The layer then refuses a library
+# that carries AVX-512, VNNI or AMX instructions, because CI's own smoke runs on
+# a CPU that has them and could never see the crash.
+RUN apt-get update && apt-get install -y --no-install-recommends \
+      python3-venv python3-dev cmake \
+    && python3 -m venv "${OPENVIKING_VENV}" \
+    && "${OPENVIKING_VENV}/bin/pip" install --no-cache-dir --upgrade pip \
+    && arch="${TARGETARCH:-$(dpkg --print-architecture)}" \
+    && case "$arch" in \
+         amd64) llama_cmake="-DGGML_NATIVE=OFF -DGGML_AVX=ON -DGGML_AVX2=ON -DGGML_FMA=ON -DGGML_F16C=ON -DGGML_AVX_VNNI=OFF -DGGML_AVX512=OFF -DGGML_AVX512_VBMI=OFF -DGGML_AVX512_VNNI=OFF -DGGML_AVX512_BF16=OFF -DGGML_AMX_TILE=OFF -DGGML_AMX_INT8=OFF -DGGML_AMX_BF16=OFF" ;; \
+         *) llama_cmake="-DGGML_NATIVE=OFF" ;; \
+       esac \
+    && CMAKE_ARGS="$llama_cmake" "${OPENVIKING_VENV}/bin/pip" install --no-cache-dir --no-binary llama-cpp-python "llama-cpp-python==${LLAMA_CPP_PYTHON_VERSION}" \
+    && if [ "$arch" = amd64 ]; then \
+         libs="$(find "${OPENVIKING_VENV}" -path '*llama_cpp*' -name '*.so*' -type f)" \
+         && [ -n "$libs" ] \
+         && for so in $libs; do \
+              if objdump -d --no-show-raw-insn "$so" | grep -qE '%zmm|vpdpbusd|vpdpwssd|tdpb|tileloadd'; then \
+                echo "FATAL: $so carries AVX-512/VNNI/AMX instructions: the VM cannot run it (SIGILL)" >&2; exit 1; \
+              fi; \
+            done; \
+       fi \
+    && "${OPENVIKING_VENV}/bin/pip" install --no-cache-dir "openviking==${OPENVIKING_VERSION}" \
+    && "${OPENVIKING_VENV}/bin/python" -c "import importlib.metadata as m, sys; v=m.version('openviking'); sys.exit(0 if v=='${OPENVIKING_VERSION}' else 'openviking version %s != ${OPENVIKING_VERSION}' % v)" \
+    && "${OPENVIKING_VENV}/bin/python" -c "import importlib.metadata as m, sys; v=m.version('llama-cpp-python'); sys.exit(0 if v=='${LLAMA_CPP_PYTHON_VERSION}' else 'llama-cpp-python %s != ${LLAMA_CPP_PYTHON_VERSION}' % v)" \
+    && "${OPENVIKING_VENV}/bin/python" -c "import llama_cpp" \
+    && test -x "${OPENVIKING_VENV}/bin/openviking-server" \
+    && rm -rf /var/lib/apt/lists/* \
+    || { echo "FATAL: openviking==${OPENVIKING_VERSION} / llama-cpp-python==${LLAMA_CPP_PYTHON_VERSION} failed verification" >&2; exit 1; }
+
+# The LOCAL ENGLISH EMBEDDER's model file - pinned by URL AND sha256 (the ARG
+# mirror above == config.toml [openviking] local_embedder_* == group_vars
+# openviking_local_embedder_*). Downloaded HERE, at build time, so the running
+# container never fetches a model (the sidecar boots offline); the layer
+# hard-fails unless the bytes hash to the pin, and scripts/openviking-embedder.py
+# re-checks the hash at every start. Carried whatever the configured provider.
+RUN mkdir -p "${LOCAL_EMBEDDER_DIR}" \
+    && curl -fsSL --retry 3 -o "${LOCAL_EMBEDDER_DIR}/${LOCAL_EMBEDDER_MODEL}.gguf" "${LOCAL_EMBEDDER_URL}" \
+    && echo "${LOCAL_EMBEDDER_SHA256}  ${LOCAL_EMBEDDER_DIR}/${LOCAL_EMBEDDER_MODEL}.gguf" | sha256sum -c - \
+    && chmod 0444 "${LOCAL_EMBEDDER_DIR}/${LOCAL_EMBEDDER_MODEL}.gguf" \
+    || { echo "FATAL: the local embedder model ${LOCAL_EMBEDDER_MODEL} failed to download or does not match its pinned sha256" >&2; exit 1; }
+# ...and the image TELLS its entrypoint which file it carries, so the boot
+# renders from the image's pin, whatever ARGs it was built with.
+ENV QCR_OPENVIKING_LOCAL_EMBEDDER_MODEL=${LOCAL_EMBEDDER_MODEL} \
+    QCR_OPENVIKING_LOCAL_EMBEDDER_DIR=${LOCAL_EMBEDDER_DIR} \
+    QCR_OPENVIKING_LOCAL_EMBEDDER_SHA256=${LOCAL_EMBEDDER_SHA256} \
+    QCR_OPENVIKING_VENV=${OPENVIKING_VENV} \
+    QCR_OPENVIKING_PORT=${OPENVIKING_PORT}
+
+# The pins this image carries, as labels the VM's updater and the deploy
+# preflight read without running it (mirrors: config.toml [openviking] ==
+# group_vars openviking_* == the ARGs above).
+LABEL qcr.openviking="${OPENVIKING_VERSION}" \
+      qcr.llama-cpp-python="${LLAMA_CPP_PYTHON_VERSION}" \
+      qcr.embedder-file="${LOCAL_EMBEDDER_DIR}/${LOCAL_EMBEDDER_MODEL}.gguf" \
+      qcr.embedder-sha256="${LOCAL_EMBEDDER_SHA256}"
+
+# The app: root-owned, never written at run time. dist/ is the supervisors and
+# the config parser; scripts/ is the boot provisioning, the migration and the
+# embedder service; smol-toml is the one package config.ts reaches.
+WORKDIR /opt/qcr
+COPY package.json ./
+COPY --from=build /src/dist ./dist
+COPY --from=build /src/node_modules/smol-toml ./node_modules/smol-toml
+# The review core's package, where an install puts it: its manifest (the
+# export map) and its compiled tree.
+COPY --from=build /src/packages/pi-plugin/package.json ./node_modules/@quickchatai/pi-quickreview/package.json
+COPY --from=build /src/packages/pi-plugin/dist ./node_modules/@quickchatai/pi-quickreview/dist
+COPY scripts ./scripts
+COPY config.example.toml ./config.example.toml
+COPY docker/memory/entrypoint.sh /usr/local/bin/entrypoint.sh
+RUN chmod -R a+rX,go-w /opt/qcr && chmod 0755 /usr/local/bin/entrypoint.sh
+
+# The container user. 1001 is the uid the daemon-era stores were
+# written under, so one opens here without a chown. --non-unique because 24.04
+# already ships an `ubuntu` user at 1000; HOME is set EXPLICITLY.
+ARG REVIEW_UID=1001
+RUN useradd --create-home --non-unique --uid ${REVIEW_UID} review
+# The state mount point, owned by the container user: Docker seeds a fresh
+# named volume from the image directory it is mounted over - a mount point the
+# image lacks would be root-owned and unwritable.
+RUN install -d -o review -g review /opt/quickreview/state /opt/quickreview/state/openviking
+# Any uid: the compose stack runs this container as the operator's own uid (so
+# the 0600 key files in the secrets mount stay readable), which owns neither
+# the store nor HOME. World-writable and sticky, like the release image's.
+RUN chmod 1777 /opt/quickreview/state /opt/quickreview/state/openviking /home/review
+ENV HOME=/home/review \
+    QCR_APP_ROOT=/opt/qcr
+
+USER review
+WORKDIR /opt/quickreview/state/openviking
+# The port is the container network's, never published to a host.
+EXPOSE ${OPENVIKING_PORT}
+HEALTHCHECK --interval=30s --timeout=5s --start-period=120s --retries=3 \
+    CMD curl -fsS "http://127.0.0.1:${QCR_OPENVIKING_PORT:-1933}/health" >/dev/null || exit 1
+
+ENTRYPOINT ["/usr/local/bin/entrypoint.sh"]

package/docker/memory/Dockerfile.dockerignore

@@ -0,0 +1,20 @@
+# The memory sidecar's build context (docker/memory/Dockerfile). BuildKit reads
+# this file in preference to the root .dockerignore. Admits only what the image
+# copies; everything else in the checkout stays out.
+*
+!package.json
+!package-lock.json
+!tsconfig.json
+!packages
+!src
+!extensions
+!scripts
+!config.example.toml
+!docker/memory/entrypoint.sh
+**/node_modules
+**/.git
+# A package's build output and its packed data are built in the image.
+packages/*/dist
+packages/*/assets
+# Agent instruction files, never in an image.
+**/CLAUDE.md

package/docker/memory/README.md

@@ -0,0 +1,60 @@
+# Memory sidecar image
+
+OpenViking, its venv, llama-cpp-python and the pinned GGUF in a container of
+their own. The daemon keeps `[openviking] endpoint = "local"` (supervising the
+same pair in-container) until the VM flips; this image is what
+`endpoint = "remote"` points at, and what `qcr memory on` runs on a laptop.
+
+```sh
+docker build -f docker/memory/Dockerfile -t qcr-memory .   # from the repo root
+```
+
+## What it does at boot
+
+`entrypoint.sh` renders, migrates and provisions the memory store, then
+execs `src/openviking/sidecar-main.ts`:
+
+1. renders `ov.conf` (`scripts/openviking-ov-conf.mjs`; `tests/memory-image.test.ts` runs it);
+2. `openviking-reembed.mjs prepare`: a store built under another embedder has
+   its vector collection moved ASIDE (never deleted) and is journalled for
+   re-embedding;
+3. `openviking-provision.mjs`: creates missing users, never rotates a key;
+4. supervises the server and the local embedder (the daemon's own classes, so
+   the start gate, restart ladder and logs are the same) and drives the
+   re-embed once `/ready` passes.
+
+The GGUF is in the image, so the sidecar boots offline under the local embedder.
+
+## On the VM
+
+`deploy/ansible/playbook.yml` runs it as a second container, `quickreview-memory`,
+beside `quickreview-sandbox` when `openviking_endpoint: "remote"` (group_vars,
+mirrored by `[openviking] endpoint`; `scripts/deploy.sh` refuses them apart and
+plans/verifies both containers). The playbook builds this image from the
+shipped tree with BuildKit, puts both containers on the `quickreview-memory`
+network, and gives the sidecar its own store directory
+(`/opt/quickreview/memory-state`): copied once from the daemon's, verified by
+checksum, never wiped, with the daemon's directory left as the rollback's store.
+`[openviking] endpoint = "local"` (both places) is the rollback.
+
+## Wiring it to a daemon (by hand)
+
+The daemon's config.toml and the sidecar's are the same file (mount the config
+home read-only into both). On the daemon side:
+
+```toml
+[openviking]
+endpoint = "remote"
+host = "quickreview-memory"   # the sidecar's name on the container network
+```
+
+Mount into the sidecar: the config home (read-only), the secrets dir
+(read-only, holding `openviking_root_key` and `openviking_reviewer_key`), and
+the OpenViking state at `/opt/quickreview/state/openviking` (a COPY of the
+daemon's store, never the daemon's own directory while a daemon may still
+write it; the image's user is uid 1001 like the daemon's). Never publish port
+1933 to a host.
+
+The re-embed journal, `provision.json` and `ov.conf` live in that state
+directory. The daemon no longer runs the re-embed driver under `remote`; the
+sidecar does.

package/docker/memory/entrypoint.sh

@@ -0,0 +1,163 @@
+#!/usr/bin/env bash
+# Memory sidecar entrypoint (docker/memory/Dockerfile).
+#
+# The memory image's boot, for a container whose only
+# job is OpenViking: render ov.conf, run the embedder migration's `prepare`,
+# provision the users, then exec the process supervisor. The knobs and their
+# defaults are QCR_OPENVIKING_* (config.toml [openviking]); tests/memory-image.test.ts
+# holds them to it, and the invariants below.
+#
+# Invariants:
+#   * never an interactive wizard (no `openviking-server init`), never a vlm;
+#   * the root key comes from the read-only secrets mount, never a literal;
+#   * degrade, never block: a step that fails says so and the sidecar still
+#     comes up (memory then degrades, exactly as in the daemon's container);
+#   * NEVER WIPE A STORE. `prepare` moves a mismatched vector collection
+#     ASIDE; the re-embed driver rebuilds it once the server is ready.
+set -euo pipefail
+
+APP="${QCR_APP_ROOT:-/opt/qcr}"
+SECRETS="${QCR_SECRETS:-/opt/quickreview/secrets}"
+
+# The same config.toml the daemon reads; mounted read-only at the config home.
+export QCR_CONFIG="${QCR_CONFIG:-/opt/quickreview/config-home/${QCR_CONFIG_NAME:-config.toml}}"
+
+OV_HOME="${QCR_OPENVIKING_HOME:-/opt/quickreview/state/openviking}"
+OV_PORT="${QCR_OPENVIKING_PORT:-1933}"
+# The server binds the container network's interfaces; the port is never
+# published, and api_key mode confines every key.
+OV_BIND_HOST="${QCR_OPENVIKING_BIND_HOST:-0.0.0.0}"
+OV_WORKERS="${QCR_OPENVIKING_WORKERS:-1}"
+OV_QUEUE_CONCURRENCY="${QCR_OPENVIKING_QUEUE_CONCURRENCY:-2}"
+OV_AUTH_MODE="${QCR_OPENVIKING_AUTH_MODE:-api_key}"
+OV_EMBEDDING_PROVIDER="${QCR_OPENVIKING_EMBEDDING_PROVIDER:-local}"
+OV_EMBEDDING_MODEL="${QCR_OPENVIKING_EMBEDDING_MODEL:-bge-small-en-v1.5-f16}"
+OV_EMBEDDING_DIMENSION="${QCR_OPENVIKING_EMBEDDING_DIMENSION:-384}"
+OV_EMBEDDING_KEY_FILE="${QCR_OPENVIKING_EMBEDDING_KEY_FILE:-openai_embeddings_api_key}"
+# The local embedder's pin: the image's own (Dockerfile ENV); the literals only
+# cover an image that does not export them.
+OV_LOCAL_EMBEDDER_MODEL="${QCR_OPENVIKING_LOCAL_EMBEDDER_MODEL:-bge-small-en-v1.5-f16}"
+OV_LOCAL_EMBEDDER_DIMENSION="${QCR_OPENVIKING_LOCAL_EMBEDDER_DIMENSION:-384}"
+OV_LOCAL_EMBEDDER_DIR="${QCR_OPENVIKING_LOCAL_EMBEDDER_DIR:-/opt/openviking/models}"
+OV_LOCAL_EMBEDDER_SHA256="${QCR_OPENVIKING_LOCAL_EMBEDDER_SHA256:-f0b2fef971e8366438bfd2d9aefea1b0115919389448806d290237f638bae999}"
+OV_LOCAL_EMBEDDER_PORT="${QCR_OPENVIKING_LOCAL_EMBEDDER_PORT:-1934}"
+OV_LOCAL_EMBEDDER_THREADS="${QCR_OPENVIKING_LOCAL_EMBEDDER_THREADS:-1}"
+OV_ROOT_KEY_FILE="${QCR_OPENVIKING_ROOT_KEY_FILE:-openviking_root_key}"
+OV_REVIEWER_KEY_FILE="${QCR_OPENVIKING_REVIEWER_KEY_FILE:-openviking_reviewer_key}"
+OV_PROVISION_USERS="${QCR_OPENVIKING_PROVISION_USERS:-reviewer,companion}"
+OV_VENV="${QCR_OPENVIKING_VENV:-/opt/openviking/venv}"
+
+# ~/.openviking is a SYMLINK onto the state volume, so memories, the vector db
+# and ov.conf survive an image rebuild. The old daemon image used the same idiom.
+mkdir -p "$OV_HOME/workspace" || echo "openviking: could not create $OV_HOME/workspace" >&2
+BOOT_OK=1
+# config.toml's [github] secrets_dir names a host path; the loader resolves it to
+# the mount instead, as the daemon's container does.
+export QCR_SECRETS_MOUNT="$SECRETS"
+# Memory switched off in config.toml: the sidecar only idles, so no step below
+# renders, migrates or provisions. An unreadable config counts as enabled (degrade,
+# never block).
+OV_ENABLED="$(node --input-type=module -e \
+  'const m = await import(process.argv[1]); process.stdout.write(m.loadConfig().openviking.enabled ? "1" : "0")' \
+  "$APP/dist/src/config.js" 2>/dev/null || echo 1)"
+# The credential file names: the environment wins (the VM's run spec passes it),
+# else the same config.toml [openviking] the supervisor loads, else the knob
+# defaults above.
+ov_config_value() {
+  node --input-type=module -e \
+    'const m = await import(process.argv[1]); process.stdout.write(String(m.loadConfig().openviking[process.argv[2]] ?? ""))' \
+    "$APP/dist/src/config.js" "$1" 2>/dev/null || true
+}
+if [[ -z "${QCR_OPENVIKING_ROOT_KEY_FILE:-}" ]]; then
+  OV_ROOT_KEY_FILE="$(ov_config_value root_key_file)"
+  OV_ROOT_KEY_FILE="${OV_ROOT_KEY_FILE:-openviking_root_key}"
+fi
+if [[ -z "${QCR_OPENVIKING_REVIEWER_KEY_FILE:-}" ]]; then
+  OV_REVIEWER_KEY_FILE="$(ov_config_value reviewer_key_file)"
+  OV_REVIEWER_KEY_FILE="${OV_REVIEWER_KEY_FILE:-openviking_reviewer_key}"
+fi
+if [[ "$OV_ENABLED" == 0 ]]; then
+  BOOT_OK=0
+  echo "openviking: memory is disabled in config.toml; boot steps skipped" >&2
+fi
+if [[ "$BOOT_OK" == 1 && -e "$HOME/.openviking" && ! -L "$HOME/.openviking" ]]; then
+  if cp -a "$HOME/.openviking/." "$OV_HOME/" && rm -rf "$HOME/.openviking"; then
+    :
+  else
+    BOOT_OK=0
+    echo "openviking: migration failed; original memory retained, boot steps skipped" >&2
+  fi
+fi
+if [[ "$BOOT_OK" == 1 ]] && ! { [[ -L "$HOME/.openviking" ]] || ln -sfn "$OV_HOME" "$HOME/.openviking"; }; then
+  BOOT_OK=0
+  echo "openviking: state link failed; boot steps skipped" >&2
+fi
+
+if [[ "$BOOT_OK" == 1 ]]; then
+
+# ov.conf is RENDERED on every boot (scripts/openviking-ov-conf.mjs), so a knob change ships with a
+# restart. The `||` is deliberate: a memory engine that cannot be configured
+# must not stop the container from coming up.
+OPENVIKING_CONF="$OV_HOME/ov.conf" QCR_SECRETS="$SECRETS" QCR_OV_HOST="$OV_BIND_HOST" \
+QCR_OV_PORT="$OV_PORT" QCR_OV_WORKERS="$OV_WORKERS" \
+QCR_OV_QUEUE_CONCURRENCY="$OV_QUEUE_CONCURRENCY" \
+QCR_OV_AUTH_MODE="$OV_AUTH_MODE" \
+QCR_OV_EMBEDDING_PROVIDER="$OV_EMBEDDING_PROVIDER" \
+QCR_OV_EMBEDDING_MODEL="$OV_EMBEDDING_MODEL" \
+QCR_OV_EMBEDDING_DIMENSION="$OV_EMBEDDING_DIMENSION" \
+QCR_OV_EMBEDDING_KEY_FILE="$OV_EMBEDDING_KEY_FILE" \
+QCR_OV_LOCAL_EMBEDDER_MODEL="$OV_LOCAL_EMBEDDER_MODEL" \
+QCR_OV_LOCAL_EMBEDDER_DIMENSION="$OV_LOCAL_EMBEDDER_DIMENSION" \
+QCR_OV_LOCAL_EMBEDDER_PORT="$OV_LOCAL_EMBEDDER_PORT" \
+QCR_OV_ROOT_KEY_FILE="$OV_ROOT_KEY_FILE" \
+node "$APP/scripts/openviking-ov-conf.mjs" \
+  || echo "openviking: ov.conf render FAILED - the sidecar starts, memory degrades" >&2
+
+# Embedder migration check - BEFORE any server starts. A store whose vector
+# collection was built under a different embedder than ov.conf now names holds
+# vectors the new embedder cannot read, and the server refuses to start on it.
+# `prepare` moves that collection ASIDE (never deletes - the old vectors are
+# the rollback) and journals every provisioned namespace as pending in
+# reembed.json; the re-embed driver in sidecar-main rebuilds reviewer memory
+# through the server's reindex API once /ready passes, and any other namespace
+# is its key holder's (docs/memory-embeddings.md). On a matching store this is
+# a no-op in milliseconds, every boot. Exit 0 by contract, `||` as belt.
+node "$APP/scripts/openviking-reembed.mjs" prepare \
+  --home "$OV_HOME" --config "$OV_HOME/ov.conf" \
+  --users "$OV_PROVISION_USERS" --user reviewer \
+  || echo "openviking: embedder migration check did not complete - the server may refuse to start on a mismatched store until an operator looks (docs/memory-embeddings.md)" >&2
+
+# Boot provisioning - idempotent: it CREATES a missing user, LEAVES an existing
+# one exactly as it is, never rotates a key. It starts the server (and, under
+# the local embedder, the loopback service) in the foreground, briefly, and
+# stops them again - the long-lived pair is sidecar-main's.
+OV_EMBEDDER_ARGS=()
+if [[ "$OV_EMBEDDING_PROVIDER" == "local" ]]; then
+  OV_EMBEDDER_ARGS=(
+    --embedder-python "$OV_VENV/bin/python"
+    --embedder-script "$APP/scripts/openviking-embedder.py"
+    --embedder-model "$OV_LOCAL_EMBEDDER_MODEL"
+    --embedder-file "$OV_LOCAL_EMBEDDER_DIR/$OV_LOCAL_EMBEDDER_MODEL.gguf"
+    --embedder-sha256 "$OV_LOCAL_EMBEDDER_SHA256"
+    --embedder-port "$OV_LOCAL_EMBEDDER_PORT"
+    --embedder-threads "$OV_LOCAL_EMBEDDER_THREADS"
+  )
+fi
+node "$APP/scripts/openviking-provision.mjs" \
+  --base "http://127.0.0.1:$OV_PORT" \
+  --users "$OV_PROVISION_USERS" \
+  --root-key-file "$SECRETS/$OV_ROOT_KEY_FILE" \
+  --reviewer-key-file "$SECRETS/$OV_REVIEWER_KEY_FILE" \
+  --start-server \
+  --bin "$OV_VENV/bin/openviking-server" \
+  --config "$OV_HOME/ov.conf" \
+  --host 127.0.0.1 --port "$OV_PORT" \
+  "${OV_EMBEDDER_ARGS[@]}" \
+  || echo "openviking: boot provisioning did not complete - the sidecar starts and memory degrades until it does" >&2
+
+fi
+
+# PID 1 is the supervisor: it owns the server, the embedder and the re-embed
+# driver, and stops them on SIGTERM.
+export QCR_OPENVIKING_BIND_HOST="$OV_BIND_HOST"
+exec node "$APP/dist/src/openviking/sidecar-main.js"

package/docker/setid/qcr-setid.c

@@ -0,0 +1,109 @@
+/*
+ * qcr-setid: the always-on bot's way to run the model's tools as the tool uid
+ *.
+ *
+ * The bot runs as its own uid, not root, so a `docker exec` into it lands as
+ * that uid, and docker gives a non-root uid no ambient capabilities. This
+ * binary carries CAP_SETUID and CAP_SETGID as FILE capabilities, and only the
+ * gate group may run it (docker/Dockerfile). It is not setpriv: it can switch
+ * to exactly ONE identity, the tool uid and tool gid compiled in below, and
+ * nothing else. A copy of setpriv with the same capabilities would let
+ * whatever runs as the bot's uid become root (`--reuid=0`), and root inside the
+ * container owns the operator channel's seal and the image's own files.
+ *
+ * It takes setpriv's argv as the engine spells it (src/engine/tooluid.ts
+ * setprivSwitches), so the engine is the same whichever binary it starts:
+ *
+ *   qcr-setid --reuid=<TOOL_UID> --regid=<TOOL_GID> --clear-groups \
+ *     --inh-caps=-all --ambient-caps=-all --no-new-privs -- <program> [args...]
+ *
+ * Every switch is required and every one must say exactly that; any other uid,
+ * gid or switch is a refusal (exit 126) before anything changes. Then: no
+ * supplementary groups, all three gids and uids the tool's, every capability
+ * set emptied (a non-root process keeps a file capability across setuid, so it
+ * is dropped by hand), no_new_privs, and the program exec'd.
+ */
+#define _GNU_SOURCE
+#include <errno.h>
+#include <grp.h>
+#include <linux/capability.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/prctl.h>
+#include <sys/syscall.h>
+#include <unistd.h>
+
+#ifndef TOOL_UID
+#error "build with -DTOOL_UID=<the tool uid>"
+#endif
+#ifndef TOOL_GID
+#error "build with -DTOOL_GID=<the tool gid>"
+#endif
+#if TOOL_UID == 0 || TOOL_GID == 0
+#error "the tool uid and gid must not be root's"
+#endif
+
+#define STR_(x) #x
+#define STR(x) STR_(x)
+
+static int refuse(const char *why) {
+  fprintf(stderr, "qcr-setid: refused: %s\n", why);
+  return 126;
+}
+
+static int fail(const char *what) {
+  fprintf(stderr, "qcr-setid: %s: %s\n", what, strerror(errno));
+  return 126;
+}
+
+int main(int argc, char **argv) {
+  static const char *const want[] = {
+      "--reuid=" STR(TOOL_UID), "--regid=" STR(TOOL_GID), "--clear-groups",
+      "--inh-caps=-all",        "--ambient-caps=-all",    "--no-new-privs",
+  };
+  const int nwant = (int)(sizeof want / sizeof want[0]);
+  int seen[sizeof want / sizeof want[0]] = {0};
+  int i = 1;
+  for (; i < argc && strcmp(argv[i], "--") != 0; i++) {
+    int k = 0;
+    while (k < nwant && strcmp(argv[i], want[k]) != 0) k++;
+    if (k == nwant) return refuse("a switch other than the tool identity's (only uid " STR(TOOL_UID) ", gid " STR(TOOL_GID) ")");
+    if (seen[k]++) return refuse("a switch given twice");
+  }
+  for (int k = 0; k < nwant; k++)
+    if (!seen[k]) return refuse("a required switch is missing");
+  if (i >= argc - 1) return refuse("no program after --");
+  char **prog = argv + i + 1;
+
+  if (setgroups(0, NULL) != 0) return fail("setgroups");
+  if (setresgid(TOOL_GID, TOOL_GID, TOOL_GID) != 0) return fail("setresgid");
+  if (setresuid(TOOL_UID, TOOL_UID, TOOL_UID) != 0) return fail("setresuid");
+
+  if (prctl(PR_CAP_AMBIENT, PR_CAP_AMBIENT_CLEAR_ALL, 0, 0, 0) != 0 && errno != EINVAL)
+    return fail("clear the ambient capabilities");
+  struct __user_cap_header_struct hdr = {_LINUX_CAPABILITY_VERSION_3, 0};
+  struct __user_cap_data_struct none[_LINUX_CAPABILITY_U32S_3];
+  memset(none, 0, sizeof none);
+  if (syscall(SYS_capset, &hdr, none) != 0) return fail("drop the capabilities");
+  if (prctl(PR_SET_NO_NEW_PRIVS, 1, 0, 0, 0) != 0) return fail("no_new_privs");
+
+  /* Prove the switch before handing over: an identity or a capability left
+   * behind is a refusal, never a program run with it. */
+  uid_t ru, eu, su;
+  gid_t rg, eg, sg;
+  struct __user_cap_data_struct now[_LINUX_CAPABILITY_U32S_3];
+  if (getresuid(&ru, &eu, &su) != 0 || getresgid(&rg, &eg, &sg) != 0)
+    return fail("read back the ids");
+  if (ru != TOOL_UID || eu != TOOL_UID || su != TOOL_UID || rg != TOOL_GID ||
+      eg != TOOL_GID || sg != TOOL_GID)
+    return refuse("the ids did not switch");
+  if (getgroups(0, NULL) != 0) return refuse("supplementary groups are left");
+  if (syscall(SYS_capget, &hdr, now) != 0) return fail("read back the capabilities");
+  for (int k = 0; k < _LINUX_CAPABILITY_U32S_3; k++)
+    if (now[k].effective || now[k].permitted || now[k].inheritable)
+      return refuse("a capability is left");
+
+  execvp(prog[0], prog);
+  return fail(prog[0]);
+}

package/docker/tunnel/Dockerfile.cloudflared

@@ -0,0 +1,51 @@
+# The cloudflared tunnel sidecar — the OFFICIAL cloudflared image
+# behind the thin wrapper in sidecar.mjs.
+#
+# The client binary is copied verbatim out of `cloudflare/cloudflared` (the
+# vendor's own published image, pinned by tag): we run THEIR build, not a
+# rebuild of it. The official image is distroless — no shell, no node — so the
+# wrapper cannot live inside it; this two-stage image is the smallest thing
+# that gives the wrapper a runtime while keeping the client byte-identical to
+# upstream's.
+#
+# The COPY path and the pin are both verified AT BUILD TIME (`cloudflared
+# --version` must print the pinned version): if upstream ever moves the binary
+# or the tag resolves to something else, the build fails loudly here instead of
+# the sidecar silently never starting. Same discipline as the memory image's
+# "failed verification" check.
+#
+# Bumping the pin is a deliberate act (tests/tunnel-sidecar.test.ts refuses a
+# floating `latest` and holds the compose file to this ARG default):
+#   docker compose --profile quick-tunnel build --no-cache
+ARG NODE_MAJOR=26
+ARG CLOUDFLARED_VERSION=2026.8.1
+
+FROM cloudflare/cloudflared:${CLOUDFLARED_VERSION} AS client
+
+# glibc base on purpose: the vendor binaries are built for it, and a musl base
+# is one silent-startup-failure class we do not need on an operator's laptop.
+FROM node:${NODE_MAJOR}-bookworm-slim
+ARG CLOUDFLARED_VERSION
+
+COPY --from=client /usr/local/bin/cloudflared /usr/local/bin/cloudflared
+RUN cloudflared --version \
+    && cloudflared --version | grep -qF "${CLOUDFLARED_VERSION}" \
+    || { echo "cloudflared failed verification: not the pinned ${CLOUDFLARED_VERSION}" >&2; exit 1; }
+
+COPY sidecar.mjs /usr/local/lib/qcr/sidecar.mjs
+
+# The shared hostname directory is created HERE so a fresh named volume
+# inherits its ownership and mode instead of arriving root-owned and empty.
+RUN mkdir -p /ingress
+
+# Runs as root INSIDE ITS OWN CONTAINER on purpose: it must write the shared
+# hostname volume whichever container created it, and (for the named-tunnel
+# variant) read a 0600 credential owned by the host operator through the
+# read-only secrets mount. The container holds nothing else — no repo, no
+# state, no GitHub credential.
+ENV QCR_TUNNEL_KIND=quick \
+    QCR_TUNNEL_UPSTREAM=http://daemon:8787 \
+    QCR_TUNNEL_HOSTNAME_FILE=/ingress/hostname \
+    QCR_TUNNEL_SECRETS_DIR=/opt/quickreview/secrets
+
+ENTRYPOINT ["node", "/usr/local/lib/qcr/sidecar.mjs"]

package/docker/tunnel/Dockerfile.ngrok

@@ -0,0 +1,40 @@
+# The ngrok tunnel sidecar — the OFFICIAL ngrok image behind the
+# same thin wrapper as the cloudflared variant (sidecar.mjs).
+#
+# Symmetric with Dockerfile.cloudflared in every way that matters: the vendor's
+# own binary copied verbatim out of their published image, the pin verified at
+# build time, the wrapper writing the same hostname-file contract the daemon's
+# watcher reads (src/webhookheal.ts). The difference is only what the operator
+# trades: an ngrok account and its free-tier caps, for a hostname that does not
+# rotate (a reserved domain, passed as QCR_TUNNEL_DOMAIN).
+#
+# The authtoken is NEVER an argv: the wrapper reads
+# <secrets>/ngrok_authtoken from the read-only secrets mount and hands it to
+# the client as NGROK_AUTHTOKEN in its environment.
+#
+#   docker compose --profile ngrok build --no-cache
+ARG NODE_MAJOR=26
+ARG NGROK_VERSION=3.31.0
+
+FROM ngrok/ngrok:${NGROK_VERSION}-alpine AS client
+
+FROM node:${NODE_MAJOR}-bookworm-slim
+ARG NGROK_VERSION
+
+COPY --from=client /bin/ngrok /usr/local/bin/ngrok
+RUN ngrok version \
+    && ngrok version | grep -qF "${NGROK_VERSION}" \
+    || { echo "ngrok failed verification: not the pinned ${NGROK_VERSION}" >&2; exit 1; }
+
+COPY sidecar.mjs /usr/local/lib/qcr/sidecar.mjs
+
+# See Dockerfile.cloudflared for why the dir is pre-created and why this runs
+# as root inside its own container.
+RUN mkdir -p /ingress
+
+ENV QCR_TUNNEL_KIND=ngrok \
+    QCR_TUNNEL_UPSTREAM=http://daemon:8787 \
+    QCR_TUNNEL_HOSTNAME_FILE=/ingress/hostname \
+    QCR_TUNNEL_SECRETS_DIR=/opt/quickreview/secrets
+
+ENTRYPOINT ["node", "/usr/local/lib/qcr/sidecar.mjs"]