@quickchatai/quickreview 0.0.0-stage → 1.1.0

package/docker/companion/Dockerfile

@@ -0,0 +1,139 @@
+# The clone route's scan sandbox image (src/scanbox.ts). Now this is NOT
+# the companion: the local companion is the release image (docker/Dockerfile)
+# in `companion` mode, built by `qcr companion rebuild`. What is left here is
+# the throwaway container `qcr scan start` drives a scan in
+# ([scan] sandbox = "docker", default image `qcr-scan`), through the one-shot
+# mode of docker/companion/entrypoint.sh. It goes when scanbox moves onto the
+# release image. A plain `docker build` from the app root (`qcr scan rebuild`
+# runs it, after `npm run build`):
+#
+#   docker build -t qcr-scan -f docker/companion/Dockerfile \
+#     --build-arg COMPANION_UID="$(id -u)" --build-arg BUILD_SHA=<stamp> .
+#
+# The context is the whole checkout, narrowed by the root .dockerignore to what
+# the image copies: the built app (below).
+#
+# Deltas from the VM image:
+#   - node:26 base instead of ubuntu + NodeSource (same major, less plumbing).
+#   - no memory extension baked in: memory is OpenViking over the
+#     host-owned forward, through the vendored extension mounted at /workspace.
+#   - no gh CLI / mint-token credential helper / webhook port: the companion
+#     reads the daemon over ssh and writes local files, it never mutates GitHub.
+#   - its own pihome volume: never share the VM's auth.json (OAuth tokens
+#     refresh in place; two hosts refreshing one grant is a hazard). One-time
+#     `/login` inside the container is a HITL step.
+FROM node:26-bookworm
+
+ENV DEBIAN_FRONTEND=noninteractive \
+    TZ=Europe/Warsaw
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+      ca-certificates curl git jq openssh-client tzdata \
+    && rm -rf /var/lib/apt/lists/*
+
+# tmux 3.5a from source — bookworm ships 3.3a, below the ≥3.5 needed for
+# `extended-keys-format csi-u` (modified keys actually reaching pi). Recipe
+# copied from the VM image so both sides speak the same key protocol.
+ARG TMUX_VERSION=3.5a
+RUN apt-get update && apt-get install -y --no-install-recommends \
+      build-essential libevent-dev libncurses-dev bison pkg-config \
+    && curl -fsSL https://github.com/tmux/tmux/releases/download/${TMUX_VERSION}/tmux-${TMUX_VERSION}.tar.gz \
+      | tar xz -C /tmp \
+    && cd /tmp/tmux-${TMUX_VERSION} && ./configure && make -j"$(nproc)" && make install \
+    && rm -rf /tmp/tmux-${TMUX_VERSION} \
+    && apt-get purge -y bison && apt-get autoremove -y && rm -rf /var/lib/apt/lists/*
+
+# pi — pinned, never floating. Pin must equal config.toml [pi], package.json's
+# `qcrPi` block and deploy/ansible/group_vars, or every VERIFY-ON-PIN assumption
+# in this repo is void.
+ARG PI_PACKAGE=@earendil-works/pi-coding-agent
+ARG PI_VERSION=1.4.0
+RUN npm install -g ${PI_PACKAGE}@${PI_VERSION}
+
+# No memory extension is installed here. The companion's memory is OpenViking
+# on the VM, reached over a host-owned forward, and its pi extension is the
+# vendored+patched `extensions/vendor/openviking-pi` bind-mounted at /workspace
+# and passed with `--extension` by src/tui/companion.ts — nothing to bake into
+# the image. Do not add a local memory package (pi-memory, qmd): a second
+# engine writing a local MEMORY.md would fork the companion's memory silently.
+
+# Non-root, and the uid MUST match the invoking host user: every interesting
+# mount here is a host bind mount the companion writes (/alerts, /feed,
+# /workspace, /tracker), so a mismatched uid means "Permission denied" on the
+# very first alert file (the VM image's 1001 does not transfer to a laptop). Both
+# scripts/companion-e2e.sh and scripts/smoke-companion.sh build with
+# `--build-arg COMPANION_UID="$(id -u)"`; the default is the usual desktop
+# 1000. --non-unique because node:26 already ships a uid-1000 `node` user.
+ARG COMPANION_UID=1000
+RUN useradd --create-home --non-unique --uid ${COMPANION_UID} companion \
+    && mkdir -p /home/companion/.pi /workspace /tracker /feed /alerts \
+    && chown -R companion:companion /home/companion /feed /alerts
+
+COPY docker/companion/entrypoint.sh /usr/local/bin/entrypoint.sh
+# The memory health watcher. Baked into the image rather than read off
+# /workspace so it starts with the container, before any repo build exists.
+COPY docker/companion/memory-health.mjs /usr/local/lib/qcr/memory-health.mjs
+RUN chmod 0755 /usr/local/bin/entrypoint.sh && chmod 0644 /usr/local/lib/qcr/memory-health.mjs
+
+# The app, baked in for the scan sandbox (src/scanbox.ts): a `qcr scan`
+# driver runs from /opt/qcr and needs nothing from the checkout — the built
+# dist, its runtime dependencies, and the agent, prompt, seed and profile
+# trees the scan's agent build reads. src/ and extensions/ ride along so an
+# extension loaded from here resolves its imports. Root-owned: the companion
+# user reads it and never writes it. The list is src/appstamp.ts BAKED_PATHS.
+WORKDIR /opt/qcr
+COPY package.json package-lock.json /opt/qcr/
+# The review core's workspace manifest first: `npm ci` links the package.
+COPY packages/pi-plugin/package.json /opt/qcr/packages/pi-plugin/package.json
+RUN npm ci --omit=dev && npm cache clean --force
+COPY dist /opt/qcr/dist
+COPY packages/pi-plugin /opt/qcr/packages/pi-plugin
+COPY src /opt/qcr/src
+COPY extensions /opt/qcr/extensions
+COPY agents /opt/qcr/agents
+COPY prompts /opt/qcr/prompts
+COPY seeds /opt/qcr/seeds
+COPY profiles /opt/qcr/profiles
+COPY docker/companion /opt/qcr/docker/companion
+# The build stamp: the hash `qcr companion rebuild` computed over exactly the
+# files copied above. `qcr scan start` refuses an image whose stamp is not
+# the checkout's (src/appstamp.ts).
+ARG BUILD_SHA=unstamped
+LABEL qcr.build-sha="${BUILD_SHA}"
+RUN printf '%s\n' "${BUILD_SHA}" > /opt/qcr/BUILD_SHA
+
+# Mount points — the lifecycle code (src/tui/companion.ts) wires the host side:
+#   /home/companion/.pi  named volume companion-pihome (OAuth, sessions, memory)
+#   /workspace           the review-sandbox repo, rw
+#   /tracker             the issue tracker, rw (actor `companion`)
+#   /feed                TUI → companion ambient snapshots
+#   /alerts             companion → TUI alert files
+#
+# A scan sandbox container (src/scanbox.ts) mounts a different, smaller set:
+# the reviewed repo read-only, the state home, its own pi home volume and the
+# config, and runs `node /opt/qcr/dist/src/cli.js scan … --foreground`
+# through the entrypoint's one-shot mode.
+#
+# Its ssh to the VM (the companion boundary, full ssh) is the host's agent socket,
+# ssh config and known_hosts, mounted read-only by src/tui/companion.ts — never
+# a key file. Memory does not ride it: OpenViking is reached over a forward
+# owned by the host (scripts/companion-memory-forward.mjs), at
+# OPENVIKING_ENDPOINT on the qcr-memory docker bridge with the two USER keys
+# docker passes in via --env-file.
+VOLUME ["/home/companion/.pi"]
+
+USER companion
+# HOME must be set EXPLICITLY. `useradd --non-unique --uid 1000 companion`
+# leaves two passwd entries at uid 1000, and docker resolves `USER companion`
+# back through the uid to the FIRST of them — node:26's own `node` user — so
+# HOME would be /home/node while the pihome volume is mounted on
+# /home/companion/.pi. Everything pi writes to $HOME/.pi (settings, trust,
+# `auth.json`) would then land on the container's writable layer and the OAuth
+# login would not survive a recreate. Do not remove this line, and do not
+# "simplify" it by dropping the companion user: uid 1000 is required to write
+# /workspace and /tracker as the host user, so the collision cannot be avoided
+# — only overridden.
+ENV HOME=/home/companion
+WORKDIR /workspace
+
+ENTRYPOINT ["/usr/local/bin/entrypoint.sh"]

package/docker/companion/agents/evidence.md

@@ -0,0 +1,34 @@
+---
+name: evidence
+description: Reads finished-round evidence for one PR — transcripts under /evidence plus the reviewed source at /reviewed-repo — and reports what actually happened
+tools: read, grep, find, ls
+model: openai-codex/gpt-6.1-sol:medium
+---
+
+You are a round-evidence reader inside the quickreview companion container. You
+run as an isolated process with NO inherited context: the task description is
+all you know — it should name a PR (`pr-<n>`) and a question; if it does not
+name one, say so and stop.
+
+Sources, all read-only:
+- `/evidence/pr-<n>/` — finished-round artifacts the TUI copied down from the
+  VM (session transcripts, verdicts, lens outputs). This is the record of what
+  the reviewer actually did.
+- `/reviewed-repo` — the reviewed repo's source, for checking a finding
+  against the code it talks about.
+
+Your job: answer the question from the evidence — what a session concluded,
+which lens produced a finding, whether a claim in a review matches the code —
+and return a brief with exact citations (file, and line or entry offset).
+
+Discipline:
+- The evidence is the authority on what happened; the code is the authority on
+  what is true. Keep the two apart in your answer.
+- Quote the decisive lines verbatim when short; summarize when long, and say
+  where the full text lives.
+- An empty or missing `/evidence/pr-<n>/` is an answer ("no rounds copied for
+  this PR"), not an error to improvise around.
+
+Output: verdict on the question first, then the supporting citations, then
+anything adjacent you noticed that the caller did not ask about (one line
+each, clearly marked as unasked).

package/docker/companion/agents/explore.md

@@ -0,0 +1,26 @@
+---
+name: explore
+description: Read-only codebase recon — finds code, maps structure, answers "where/how is X done" across /workspace and /reviewed-repo
+tools: read, grep, find, ls
+model: openai-codex/gpt-6.1-sol:low
+---
+
+You are a read-only codebase scout inside the quickreview companion container.
+You run as an isolated process with NO inherited context: everything you know
+about the task is in the task description you were given. If it names no
+directory, assume `/workspace` (the review-sandbox repo). `/reviewed-repo` is
+the reviewed product's source, mounted read-only.
+
+Your job: answer the question you were given by reading code, and return a
+compact brief the caller can act on without re-opening the files.
+
+Discipline:
+- You cannot write anything, and you must not try to work around that.
+- Cite every claim as `path:line` so the caller can jump straight there.
+- Distinguish plainly between what you VERIFIED by reading and what you
+  inferred; never present an inference as a read.
+- If the question cannot be answered from the mounted trees, say exactly that
+  and what was searched — a clean "not found here" beats a guess.
+
+Output: a short summary first (2-3 sentences), then findings as a cited list,
+then open questions if any.

package/docker/companion/agents/pass-survey.md

@@ -0,0 +1,49 @@
+---
+name: pass-survey
+description: The setup survey's lens — reads one survey case of the reviewed repo (the repo-wide directive files and design docs, or one unit's code sample) and writes the conventions and architecture a reviewer must know. Hunts no bugs. Launched by the setup engine; not for ad-hoc questions (use explore).
+tools: read, grep, find, ls
+model: openai-codex/gpt-6.1-sol:low
+---
+
+You are the survey lens of a code reviewer being set up on a repository it has
+never seen. You run as an isolated process with NO inherited context: the task
+description names the case — the repo-wide read or one unit — and the exact
+files to read. The repository is mounted read-only; you cannot change it and
+must not try.
+
+Your job is to learn the repo, not to review it. What you write becomes the
+reviewer's memory: every later pull-request review of this repo reads it. So
+write only what a careful reviewer would need to know before judging a change
+here, and write it so it is still true next month.
+
+What to write:
+- **conventions** — how code here is expected to be written: naming, layout
+  of a module, error handling, logging, how tests are organised, what the
+  directive files demand or forbid, the house style where it is stated or
+  consistently followed.
+- **architecture** — how this part is put together: its layers and where each
+  kind of code lives, its entry points, the models or schemas it owns, the
+  boundaries it keeps with the rest of the repo, the invariants its design
+  depends on.
+
+Discipline:
+- Read every file you were given, in the order given. Directive files and
+  design docs are read IN FULL — they are the team's own words and outrank
+  your inference.
+- A note states one thing and names the file(s) that show it, as repo-relative
+  paths. A convention you saw once is not a convention: say what you saw
+  only when the files state it or the sample follows it consistently.
+- Keep what the files SAY apart from what you infer. Mark an inference
+  ("appears to", "the sample suggests").
+- No findings. Do not report bugs, risks, smells or improvements — a survey
+  that hunts bugs is a scan, and it is not your job.
+- Do not restate a note the task says the repo-wide read already made.
+- Nothing generic: "code should be readable" teaches a reviewer nothing.
+
+Output grammar (parsed by a program — follow it exactly):
+- One note per paragraph, each opening with its kind in brackets at the start
+  of a line: `[convention] …` or `[architecture] …`. A note may run over
+  several lines; a blank line ends it.
+- At most 12 notes, each at most a few sentences (longer is cut).
+- Nothing else is kept: no headings, no preamble, no summary.
+- If the case teaches nothing a reviewer needs, answer exactly `NONE`.

package/docker/companion/agents/study.md

@@ -0,0 +1,26 @@
+---
+name: study
+description: Reads long-form material — tracker tickets and maps under /tracker, docs, specs, session notes — and returns a faithful digest scoped to a question
+tools: read, grep, find, ls
+model: openai-codex/gpt-6.1-sol:medium
+---
+
+You are a document reader inside the quickreview companion container. You run as
+an isolated process with NO inherited context: the task description is all you
+know. Typical sources: `/tracker` (the issue tracker — efforts, maps, tickets,
+inbox drops), `/workspace/docs`, `/workspace/prompts`, `/tracker-docs`.
+
+Your job: read what you were pointed at (or find it by ticket id / filename),
+and return a digest scoped to the caller's question — not a general summary.
+
+Discipline:
+- Read-only. You never claim, edit, or resolve a ticket; you only report.
+- Preserve the source's own decisions verbatim where they matter — ratified
+  decisions, hard rules, and "rejected: …" lines are load-bearing and must not
+  be paraphrased into something weaker.
+- Keep provenance: every point in the digest names the file it came from
+  (and the ticket id where there is one).
+- If sources conflict, surface the conflict; do not silently pick one.
+
+Output: the answer to the question first, then the digest as a cited list,
+then a "what I did not read" line if you had to cut scope.

package/docker/companion/entrypoint.sh

@@ -0,0 +1,343 @@
+#!/usr/bin/env bash
+# The scan sandbox image's entrypoint (docker/companion/Dockerfile). Its one-shot
+# mode is all that is used now the local companion is the release image
+# in `companion` mode (docker/entrypoint.sh). The companion branch below is the
+# superseded one and goes with this image.
+#
+# Companion container entrypoint. PID 1 owns exactly two jobs:
+# start a correctly-configured tmux server and then stay alive. pi itself is
+# spawned by the TUI through `docker exec` (src/tui/companion.ts), the same
+# adopt-don't-kill shape the VM sessions use — so a pi crash never takes the
+# container (and the conversation volume) with it.
+#
+# One-shot mode: given a command (`docker run … <image> <cmd…>`), it
+# provisions pi's settings and then execs that command instead of the tmux
+# server — how the scan sandbox runs its driver (src/scanbox.ts) and how
+# `qcr scan login` / `doctor` run pi. Its own lines go to stderr, so the
+# command's stdout is the command's; with QCR_DRIVER_LOG set, both go to that
+# file (the scan driver's log in the mounted state home).
+set -euo pipefail
+
+if [ "$#" -gt 0 ]; then
+  ENTRY_MODE=oneshot
+  if [ -n "${QCR_DRIVER_LOG:-}" ]; then
+    mkdir -p "$(dirname "$QCR_DRIVER_LOG")"
+    exec >>"$QCR_DRIVER_LOG" 2>&1
+  fi
+  exec 3>&1 1>&2
+else
+  ENTRY_MODE=companion
+fi
+# The settings merge below reads it: a one-shot container has no /workspace.
+export QCR_ENTRY_MODE="$ENTRY_MODE"
+
+PI_HOME_DIR="${HOME}/.pi"
+mkdir -p "$PI_HOME_DIR/agent" 2>/dev/null || true
+if [ "$ENTRY_MODE" = companion ]; then
+  mkdir -p /workspace /tracker /feed /alerts 2>/dev/null || true
+fi
+
+# Durability guard. pi writes its OAuth token, settings and trust store under
+# $HOME/.pi. If that is NOT the mounted volume (a uid collision moving $HOME is
+# enough), every one of them lives on the container's writable layer and dies
+# with the next recreate — the login silently stops persisting, and nobody
+# finds out until they are asked to log in again. Loud, never fatal: a
+# companion that starts is worth more than one that is right, and the operator
+# can see this line. The companion's alone: a one-shot container's pi home is
+# what it mounts — the scan sandbox's is a private tmpfs, meant to vanish.
+# /proc/mounts, not `mountpoint`: util-linux is not guaranteed in the base
+# image, and a guard that reports a false alarm when its own tool is missing
+# teaches you to ignore it.
+if [ "$ENTRY_MODE" = companion ]; then
+if ! awk -v d="$PI_HOME_DIR" '$2 == d { found = 1 } END { exit !found }' /proc/mounts; then
+  echo "!! $PI_HOME_DIR is NOT a mount point — pi's OAuth token and settings will"
+  echo "!! NOT survive a container recreate. Expected the companion-pihome volume"
+  echo "!! here. HOME=$HOME; check the Dockerfile's ENV HOME against"
+  echo "!! CONTAINER.piHome in src/tui/companion.ts."
+else
+  echo "pi home on the volume: $PI_HOME_DIR (OAuth + conversation are durable)"
+fi
+fi
+
+# Everything from here to the pi settings is the companion's: its mounts,
+# its tmux and its git identity. A one-shot container skips it.
+if [ "$ENTRY_MODE" = companion ]; then
+
+# Reviewed-repo mount. The reviewed repo's source arrives READ-ONLY at
+# /reviewed-repo so the companion can read the code a review is about. It is
+# conditional by design (src/tui/companion.ts runArgv): a host without the
+# checkout gets no mount, and that must leave the companion under-equipped
+# rather than unable to start — same degrade discipline as the skills dir and
+# the vendored extension. Never `mkdir` it as a fallback: an empty tree reads
+# as "the code says nothing", which is worse than a plainly absent mount.
+if [ -d /reviewed-repo ] && [ -n "$(ls -A /reviewed-repo 2>/dev/null)" ]; then
+  echo "reviewed repo mounted READ-ONLY at /reviewed-repo (read it; you can never write it)"
+else
+  echo "!! /reviewed-repo is not mounted — no reviewed-repo source to read."
+  echo "!! Set [companion] reviewed_repo_dir to the reviewed repo's checkout on this host."
+fi
+
+# Evidence store. Finished-round artefacts the TUI copied down from
+# the VM arrive READ-ONLY at /evidence. Say which world this boot is in: an
+# empty store (no rounds copied yet) and an absent mount look identical from
+# inside the conversation, and only one of them is a misconfiguration.
+if [ -d /evidence ]; then
+  echo "round evidence mounted READ-ONLY at /evidence ($(ls -1 /evidence 2>/dev/null | wc -l) PR dirs)"
+else
+  echo "!! /evidence is not mounted — no finished-round transcripts to read."
+  echo "!! Set [companion] evidence_dir and restart the TUI (qcr companion rebuild not needed)."
+fi
+
+# Read-only GitHub token. The TUI mints it on the host and re-mints
+# it into /github-read before it expires; only the file's PRESENCE is echoed,
+# never a value. Absent = the TUI has no App credential or is not running.
+if [ -s /github-read/github-read.env ]; then
+  echo "read-only GitHub token file at /github-read/github-read.env (source it; it cannot write)"
+else
+  echo "!! no read-only GitHub token yet — GitHub reads unavailable until the TUI mints one."
+fi
+
+# csi-u extended keys must be configured BEFORE the server starts, or modified
+# Enter (Shift/Alt/Ctrl) collapses to plain Enter before reaching pi and the
+# TUI's steer/queue keys die. Requires tmux ≥3.5 (built from source in the
+# image). Same three lines as the VM entrypoint — keep them in sync.
+cat > "$HOME/.tmux.conf" <<'TMUXCONF'
+# csi-u extended keys end-to-end — do not remove.
+set -g extended-keys on
+set -g extended-keys-format csi-u
+set -as terminal-features 'xterm*:extkeys'
+# Mouse wheel scrolls the pane HISTORY (tmux copy-mode), not pi's prompt list;
+# pi /copy propagates via OSC 52 through set-clipboard. Keep in sync with the
+# VM entrypoint template.
+set -g mouse on
+set -g set-clipboard on
+set -as terminal-features 'xterm*:clipboard'
+set -g history-limit 50000
+# Muted look — no bright greens anywhere.
+set -g status-style 'bg=colour235,fg=colour247'
+set -g status-left-style 'fg=colour250'
+set -g status-right-style 'fg=colour244'
+set -g window-status-current-style 'fg=colour252,bold'
+set -g message-style 'bg=colour235,fg=colour250'
+set -g mode-style 'bg=colour238,fg=colour252'
+set -g pane-border-style 'fg=colour238'
+set -g pane-active-border-style 'fg=colour245'
+TMUXCONF
+
+# Git identity. The companion commits its own work to the mounted
+# repo with a `[companion]` prefix, and git refuses to commit at all without an
+# identity ("Please tell me who you are"). ~/.gitconfig lives on the container's
+# writable layer, NOT the pihome volume, so it is rewritten every start rather
+# than seeded once. Author, not committer-of-record for anyone else: the name
+# says plainly which hands made the commit.
+# `|| true` on every one: `set -e` is on, and a git that exits non-zero here
+# would take the CONTAINER down at boot — mounting a git WORKTREE at /workspace
+# does it, because its `.git` is a file pointing at a path that does not exist
+# inside the container, and git fails while discovering the repo. An unusable
+# git identity degrades the companion's committing; it must never stop the
+# companion from starting.
+git config --global user.name "QCR Companion" || true
+git config --global user.email "companion@quickchat.ai" || true
+# The repo is bind-mounted from the host and owned by the same uid, so
+# safe.directory is not needed — but a uid mismatch (a rebuilt image with a
+# different COMPANION_UID) would otherwise wedge every git call with a
+# confusing ownership error rather than a permission one.
+git config --global --add safe.directory /workspace || true
+
+fi
+
+# pi settings. ~/.pi lives on a named volume; the merge below preserves every
+# existing key (hand edits win, append-only extensions).
+#
+# No memory extension is registered here. The companion's memory is
+# OpenViking on the VM, and its vendored+patched extension is passed per spawn
+# with `--extension` by src/tui/companion.ts — a per-spawn flag, not a global
+# registration.
+SETTINGS="$PI_HOME_DIR/agent/settings.json"
+mkdir -p "$PI_HOME_DIR/agent"
+# Idempotent MERGE (mirrors the VM entrypoint): seeding only when the file is
+# absent would skip every key once pi itself had written settings.json.
+node <<'PI_EXT_MERGE'
+const fs = require("fs");
+// A one-shot container (the scan sandbox, `qcr scan login`) mounts no
+// /workspace: the skills, the companion agent set and the /workspace trust
+// are the companion's alone, and are left untouched there.
+const oneshot = process.env.QCR_ENTRY_MODE === "oneshot";
+const path = process.env.HOME + "/.pi/agent/settings.json";
+let cfg = {};
+try { cfg = JSON.parse(fs.readFileSync(path, "utf8")); } catch {}
+if (!Array.isArray(cfg.extensions)) cfg.extensions = [];
+// Never block on pi's interactive "Trust project folder?" modal (mirrors the
+// VM entrypoint — the pr-5334 stall).
+cfg.defaultProjectTrust = "always";
+// pi 1.0 made the interactive TUI fullscreen by default. Sessions run under
+// tmux and the operator TUI mirrors and scrolls their panes, so keep the
+// terminal's normal scrollback (pi 0.99's default) — packages/pi-plugin/src/pibuiltins.ts PI_TUI_MODE.
+cfg.tuiMode = "regular";
+// pi 0.99's built-in extensions (mcp, codemode, tool-search, llama.cpp) are
+// switched OFF, as on the VM: MCP launches server processes from any trusted
+// mcp.json — a path around companion-guard, which vetoes TOOL CALLS — and the
+// other three change the tool/provider set (reasons per built-in:
+// packages/pi-plugin/src/pibuiltins.ts, the list this mirrors). Documented switch: a
+// `-builtin:<name>` entry in the global `extensions`. This one key overrides
+// "hand edits win": any other global `builtin:` entry is dropped first.
+const DISABLED_BUILTINS = ["-builtin:mcp", "-builtin:codemode", "-builtin:tool-search", "-builtin:llama.cpp"];
+cfg.extensions = cfg.extensions.filter((p) => !/^[-+!]?builtin:/.test(p)).concat(DISABLED_BUILTINS);
+
+// Skills. The repo carries the vendored mattpocock set at
+// /workspace/.claude/skills/ — wayfinder, grilling, domain-modeling and 22
+// more. pi supports SKILL.md natively, but `.claude/skills` is NOT one of the
+// paths it looks in on its own (~/.pi/agent/skills, ~/.agents/skills,
+// .pi/skills and .agents/skills in cwd+ancestors, package skills/ dirs). Until
+// this registration they were plain files the system prompt had to name by
+// hand, one at a time, with no progressive disclosure: the companion could
+// only use a skill it had already been told existed.
+//
+// The settings `skills` array is pi's documented interop hook for exactly this
+// — the docs' own example is ["~/.claude/skills", "~/.codex/skills"]
+//. VERIFY-ON-PIN: array-of-directories form, and that a
+// registered dir is scanned one level deep for <name>/SKILL.md.
+//
+// COMPANION ONLY — deliberately not mirrored into the VM entrypoint. Reviewer
+// lens passes are leaves (rule 9) and a charting/planning skill set is nothing
+// a lens should be able to reach for mid-round.
+//
+// Registered only when the dir is really there: an unmounted /workspace must
+// leave the companion under-equipped, never unable to start. Same degrade
+// discipline as the vendored OpenViking extension in piArgv.
+const skillsDir = "/workspace/.claude/skills";
+if (!Array.isArray(cfg.skills)) cfg.skills = [];
+const skillsPresent = !oneshot && fs.existsSync(skillsDir);
+if (skillsPresent && !cfg.skills.includes(skillsDir)) cfg.skills.push(skillsDir);
+
+// OUR OWN skills, a SECOND registered directory. `.claude/skills` is
+// a pinned vendored copy (see .claude/skills/VENDORED.md — it is re-copied
+// wholesale on an upstream bump), so a companion skill we author cannot live
+// there: the next vendor pass would either clobber it or make the folder no
+// longer a clean mirror. It gets its own tree at /workspace/skills/companion/,
+// scanned one level deep for <name>/SKILL.md exactly like the vendored one —
+// which is why this is a second ARRAY ENTRY and not a merged parent dir.
+// Guarded independently and the same way: a missing dir leaves the companion
+// under-equipped (it keeps the vendored set), never unable to start.
+const ourSkillsDir = "/workspace/skills/companion";
+const ourSkillsPresent = !oneshot && fs.existsSync(ourSkillsDir);
+if (ourSkillsPresent && !cfg.skills.includes(ourSkillsDir)) cfg.skills.push(ourSkillsDir);
+// `/skill:<name>` from pi's own input line. The embedded companion column is a
+// TERMINAL (rule: every byte goes to pi), so the owner's `/` commands reach pi
+// directly — this is what makes the set invocable by hand as well as by the
+// model. Set unconditionally, like defaultProjectTrust: seed-only-if-absent is
+// how keys silently stopped landing once pi had written settings.json itself.
+cfg.enableSkillCommands = true;
+// The configured model ("provider/model[:thinking]", [companion] model) is
+// pi's default on every start, so a fresh login or a bare `pi` never falls
+// back to a model an older login stored.
+const defModel = process.env.QCR_PI_DEFAULT_MODEL || "";
+const defMatch = /^([^/:\s]+)\/([^:\s]+)(?::([a-z]+))?$/.exec(defModel);
+if (defMatch) {
+  cfg.defaultProvider = defMatch[1];
+  cfg.defaultModel = defMatch[2];
+  if (defMatch[3]) cfg.defaultThinkingLevel = defMatch[3];
+}
+
+fs.writeFileSync(path, JSON.stringify(cfg, null, 2) + "\n");
+console.log("pi settings merged (extensions: " + (cfg.extensions.join(", ") || "none registered globally") + ")");
+if (!oneshot) {
+console.log(
+  cfg.skills.length
+    ? "pi skills registered: " + cfg.skills.join(", ") + " (/skill:<name> enabled)"
+    : "!! no skills registered. Is /workspace mounted?",
+);
+// Each missing dir says so on its own line: the two degrade independently, and
+// "the vendored set is there" must never read as "adjudicate is there".
+if (!skillsPresent) console.log("!! " + skillsDir + " is missing — the vendored skill set is not registered.");
+if (!ourSkillsPresent) console.log("!! " + ourSkillsDir + " is missing — our own skills (adjudicate) are not registered.");
+}
+
+// Braces to that belt (mirrors the VM entrypoint): pre-seed the trust store
+// for the workspace, so even a settings regression — or a pihome volume
+// carrying an older settings.json — cannot re-surface the modal. The third
+// layer is `--approve` on the spawn itself (src/tui/companion.ts piArgv).
+// /workspace, not /opt/quickreview: that is where the repo is mounted here.
+if (!oneshot) {
+const trustFile = process.env.HOME + "/.pi/agent/trust.json";
+let trust = {};
+try { trust = JSON.parse(fs.readFileSync(trustFile, "utf8")); } catch {}
+if (trust["/workspace"] !== true) {
+  trust["/workspace"] = true;
+  fs.writeFileSync(trustFile, JSON.stringify(trust, null, 2) + "\n");
+}
+console.log("pi project trust: defaultProjectTrust=always, /workspace pre-trusted");
+}
+
+// Agent discovery for the lens tool (packages/pi-plugin/extensions/lens.ts): its agent dir's
+// `agents` is $HOME/.pi/agent/agents; link that at the companion agent set (explore/evidence/study) riding the
+// /workspace mount. Same degrade discipline as the skills dirs: a missing
+// /workspace leaves the link dangling and discovery simply finds no agents —
+// an under-equipped companion, never one that won't start. Symlink-or-absent
+// only: a REAL directory here is someone's own agents and is never clobbered.
+if (!oneshot) {
+const agentsLink = process.env.HOME + "/.pi/agent/agents";
+const companionAgents = "/workspace/docker/companion/agents";
+try {
+  const st = fs.lstatSync(agentsLink, { throwIfNoEntry: false });
+  if (st && !st.isSymbolicLink()) {
+    console.log("!! " + agentsLink + " exists and is not a symlink — NOT touching it; the companion agent set is not discoverable");
+  } else {
+    if (st) fs.unlinkSync(agentsLink);
+    fs.symlinkSync(companionAgents, agentsLink);
+    console.log("pi user agents dir -> " + companionAgents);
+  }
+} catch (e) {
+  console.log("!! could not link " + agentsLink + ": " + e.message);
+}
+}
+PI_EXT_MERGE
+
+# One-shot: the command takes the container from here, its stdout restored.
+if [ "$ENTRY_MODE" = oneshot ]; then
+  exec 1>&3 3>&-
+  exec "$@"
+fi
+
+# OpenAI auth: the OAuth route (`/login` once inside a pi session) persists in
+# $PI_HOME_DIR/agent/auth.json on the volume and takes precedence over the env
+# var. OPENAI_API_KEY is honored when the caller passes one.
+# Provider prefix under OAuth is `openai-codex/`, not `openai/`.
+
+# Memory health watcher: probes OpenViking through the host-owned
+# forward and drops an alert file into /alerts when it stops answering (and a
+# notice when it comes back). Backgrounded and non-fatal by construction — an
+# unwired or unreachable memory path degrades the companion, it never wedges
+# it. With no QCR_MEMORY_ENDPOINT in the env the watcher exits immediately.
+if [ -n "${QCR_MEMORY_ENDPOINT:-}${OPENVIKING_URL:-}${OPENVIKING_BASE_URL:-}" ] && [ -f /usr/local/lib/qcr/memory-health.mjs ]; then
+  node /usr/local/lib/qcr/memory-health.mjs &
+else
+  echo "memory watcher idle: no OpenViking endpoint configured for this container"
+fi
+
+# The tmux server is the jump-in surface: `docker exec -it <c> tmux attach -t
+# companion`. Panes inherit the SERVER's env, not the client's — per-session
+# QCR_* vars ride the pi command line (see spawnPi in src/tui/companion.ts).
+tmux start-server
+
+# Stay alive, and DIE PROMPTLY when asked.
+#
+# PID 1 has no default signal dispositions, so a signal with no explicit
+# handler is ignored outright and `docker stop` would wait its full 10 s
+# timeout before SIGKILL — after the TUI has already restored the terminal,
+# leaving it dead for those 10 s. A trap gives PID 1 the handler it lacks.
+# `sleep &` + `wait` rather than `exec`, because a foreground child would
+# block the trap until it returned.
+term() {
+  kill "$child" 2>/dev/null || true
+  exit 0
+}
+trap term TERM INT
+sleep infinity &
+child=$!
+# `|| true`: a signal makes `wait` return 128+N, and under `set -e` that status
+# would end the script before the trap's own `exit 0`, and the container would
+# record "Exited (128)" on every clean stop, which reads like a crash in
+# `docker ps -a`.
+wait "$child" || true
+exit 0