@quickchatai/quickreview 0.0.0-stage → 1.1.0

package/docker-compose.yml

@@ -0,0 +1,348 @@
+# The compose stack: the always-on review daemon, its memory sidecar and an
+# optional webhook tunnel, all from the released images.
+#
+#   docker compose pull --ignore-buildable && docker compose up -d
+#
+# Nothing here builds the app or needs a checkout: `daemon` and `memory` are
+# pulled, `QCR_VERSION` pins them, and the project directory holds this file,
+# a .env and (for a tunnel) docker/tunnel/ -- all of which the image carries and
+# the onboarding wizard hands you the command to extract (qcr onboard, step 70):
+#
+#   docker run --rm --entrypoint tar ghcr.io/quickchatai/quickreview:<version> \
+#     -C /opt/qcr -cf - docker-compose.yml docker/tunnel | tar -xf -
+#
+# The images are public; a private mirror needs `gh auth refresh -s read:packages`,
+# then `gh auth token | docker login ghcr.io -u <user> --password-stdin`.
+#
+# Needed on the host, all named in .env (the wizard's bring-up writes them):
+#   QCR_VERSION       the release to run (the image tag), e.g. 0.1.0
+#   QCR_CONFIG_HOME   the directory holding your config.toml, mounted read-only
+#   QCR_CONFIG_NAME   the file in it (default config.toml)
+#   QCR_SECRETS_DIR   the secrets dir -- app_id, app.pem, webhook_secret at
+#                     least; optional openai_api_key (pi's API-key route),
+#                     openviking_root_key, openviking_reviewer_key, and
+#                     openai_embeddings_api_key (only under the hosted-embeddings
+#                     opt-in -- memory embeds locally by default)
+#   QCR_UID           your uid, so the daemon can read 0600 files you own
+#   QCR_CLONE_DIR     the base clone's directory name: [github] clone_dir, else
+#                     the repo's name ("acme/webapp" => webapp)
+#
+# config.toml must say `[openviking] endpoint = "remote"` and `host = "memory"`:
+# the memory engine runs in the `memory` service, not inside the daemon (the
+# release image carries no OpenViking). The wizard's bring-up writes both.
+#
+# Ingress is the operator's choice, and the wizard's ingress step makes it for
+# you. Four shapes, three of them a SIDECAR in this file, each behind its own
+# compose profile -- with no profile selected you get the daemon (and its
+# memory) ALONE, which is the polling-only shape:
+#
+#   COMPOSE_PROFILES=quick-tunnel   cloudflared quick tunnel; no account, the
+#                                   hostname ROTATES and the daemon re-points
+#                                   the App's webhook URL itself ([ingress]
+#                                   shape = "tunnel-file")
+#   COMPOSE_PROFILES=ngrok          ngrok; needs an account + authtoken file,
+#                                   free-tier request/bandwidth caps apply,
+#                                   hostname stable with a reserved domain
+#   COMPOSE_PROFILES=named-tunnel   your own Cloudflare tunnel token + your own
+#                                   domain (the VM route's default shape)
+#   (unset)                         no tunnel at all -- the reconcile poll is
+#                                   the trigger path ([daemon] poll_interval_s)
+#
+# The wizard writes the profile into the project's .env; set it by hand with
+# `COMPOSE_PROFILES=quick-tunnel docker compose up -d` if you prefer. Any other
+# HTTPS proxy or tunnel pointed at the published webhook port also works.
+# See docker/README.md.
+#
+# Pins: pi, OpenViking, llama-cpp-python and tmux are the images' Dockerfile
+# ARG defaults (docker/Dockerfile, docker/memory/Dockerfile), mirrored against
+# config.toml and deploy/ansible/group_vars/all.yml by tests/release-image.test.ts
+# and tests/memory-image.test.ts. A version bump is a new release, never an
+# override here.
+name: quickreview
+
+services:
+  # One-shot, as root, before the daemon: hands the roots of the daemon's named
+  # volumes to QCR_UID. A volume over a path the image lacks (wt/, verdict/, the
+  # base clone ...) arrives root-owned and unwritable by the daemon, and one
+  # over a path the image has arrives world-writable (state/, pi's home), which
+  # the model's tool uid must not get. It touches the volume roots only, never a
+  # file inside one: the daemon's own 0755; state/, verdict/ and commands/
+  # shared with the model's tools through their own gid (4749, the image's
+  # qcr.tool-gid) -- setgid, and state/ and commands/ sticky, as the daemon's
+  # entrypoint sets them; pi's home 0700; and the operator channel,
+  # commands/operator, made root's own 0755 here, so the operator's
+  # `docker exec -u 0` writes into a directory root owns and the daemon needs
+  # no capability for it.
+  volume-init:
+    image: ghcr.io/quickchatai/quickreview:${QCR_VERSION:?set QCR_VERSION to the release to run (the image tag)}
+    user: "0:0"
+    entrypoint: ["/bin/sh", "-c"]
+    command:
+      - >-
+        set -eu;
+        for d in /v/state /v/wt /v/archive /v/commands /v/digest /v/inject /v/verdict
+        /v/pihome /v/base-clone /v/home-pi; do chown "$$QCR_UID:$$QCR_UID" "$$d"; done;
+        chgrp 4749 /v/state /v/verdict /v/commands;
+        chmod 3775 /v/state /v/commands;
+        chmod 2775 /v/verdict;
+        chmod 0755 /v/wt /v/archive /v/digest /v/inject /v/pihome /v/base-clone;
+        chmod 0700 /v/home-pi;
+        if [ -L /v/commands/operator ]; then echo 'commands/operator is a symlink' >&2; exit 1; fi;
+        mkdir -p /v/commands/operator;
+        chown -h 0:0 /v/commands/operator;
+        chmod 0755 /v/commands/operator
+    environment:
+      QCR_UID: ${QCR_UID:-1000}
+    network_mode: none
+    cap_drop: [ALL]
+    cap_add: [CHOWN, FOWNER, DAC_OVERRIDE]
+    security_opt:
+      - no-new-privileges:true
+    volumes:
+      - qcr-state:/v/state
+      - qcr-wt:/v/wt
+      - qcr-archive:/v/archive
+      - qcr-commands:/v/commands
+      - qcr-digest:/v/digest
+      - qcr-inject:/v/inject
+      - qcr-verdict:/v/verdict
+      - qcr-sessions-home:/v/pihome
+      - qcr-base-clone:/v/base-clone
+      - qcr-pihome:/v/home-pi
+
+  daemon:
+    image: ghcr.io/quickchatai/quickreview:${QCR_VERSION:?set QCR_VERSION to the release to run (the image tag)}
+    # The image's mode dispatch (docker/entrypoint.sh): the always-on bot.
+    command: ["daemon"]
+    # The image carries no passwd entry for the user it runs as; the caller
+    # picks it. Your uid, so the 0600 files you own in the secrets mount stay
+    # readable and nothing else is shared.
+    user: "${QCR_UID:-1000}:${QCR_UID:-1000}"
+    # The model's tools run as another uid and gid (65534:4749, the image's
+    # qcr.tool-uid / qcr.tool-gid), which cannot read the secrets mount or
+    # pi's login (docker/entrypoint.sh): the daemon reaches it through the
+    # image's setid helper, which switches to that one identity only and which
+    # only the gate group 4748 may run (the image's qcr.setid-gid label); 4749
+    # is how it shares the directories the tools write. The same shape as the
+    # VM's (deploy/qcr-update.sh): SETUID/SETGID for the helper's file
+    # capabilities and nothing else, and no no-new-privileges, which would void
+    # the helper (the model's tools carry no_new_privs of their own).
+    group_add: ["4748", "4749"]
+    depends_on:
+      volume-init:
+        condition: service_completed_successfully
+    # PID-1 discipline: the daemon runs a tmux server beside itself, so PID 1
+    # must reap. tini forwards signals and adopts orphans.
+    init: true
+    restart: unless-stopped
+    cap_drop: [ALL]
+    cap_add: [SETUID, SETGID]
+    # Resource caps -- same defaults as the live VM (a shared box). Raise via
+    # QCR_CPUS / QCR_MEMORY if the host is yours alone.
+    cpus: ${QCR_CPUS:-2}
+    mem_limit: ${QCR_MEMORY:-8g}
+    memswap_limit: ${QCR_MEMORY:-8g}
+    # The webhook port is the ONLY thing this container publishes, and on
+    # loopback by default -- put your HTTPS ingress in front of it. OpenViking's
+    # port (1933) is the memory service's, on the compose network, and is
+    # deliberately never published.
+    ports:
+      - "${QCR_WEBHOOK_BIND:-127.0.0.1}:${QCR_WEBHOOK_PORT:-8787}:8787"
+    volumes:
+      # The state volume. /opt/qcr/state is the one writable directory under the
+      # app root (the MutationGate's state/dryrun, the onboarding checklist, the
+      # companion's rollover and alert state all live here); the image ships it
+      # world-writable, so a fresh volume is writable by whatever uid runs.
+      - qcr-state:/opt/qcr/state
+      # The tunnel sidecar's ONLY shared surface: the one directory holding
+      # the hostname file the self-heal watcher reads
+      # (/opt/qcr/state/ingress/hostname, the default `[ingress] hostname_file`).
+      # A nested mount so the sidecar never sees the rest of the state volume:
+      # no SQLite, no memory, no dry-run record.
+      - qcr-ingress:/opt/qcr/state/ingress
+      - ${QCR_SECRETS_DIR:?set QCR_SECRETS_DIR to your secrets directory}:/opt/quickreview/secrets:ro
+      # The directory holding the live config.toml the install locator found
+      # on the host -- the install's config home, or wherever QCR_CONFIG
+      # points -- and with it the profiles/ beside that config. The container
+      # reads no other config. Mounted read-only: the wizard edits it on the
+      # host, and the daemon reads it once, at boot.
+      - ${QCR_CONFIG_HOME:?set QCR_CONFIG_HOME to the directory holding config.toml}:/opt/quickreview/config-home:ro
+      # pi's home: OAuth tokens (auth.json), session JSONLs, models.json --
+      # must survive container recreates (sticky sessions + /login tokens).
+      - qcr-pihome:/home/qcr/.pi
+      # Everything else the daemon writes under the read-only app root, the
+      # same set the VM's run spec mounts (deploy/qcr-update.sh; the two are
+      # held equal by tests/compose-stack.test.ts): the PR worktrees, the
+      # closed-PR archive, the command channel (commands/operator is the
+      # operator's, root-owned), the digests, the inject channel and the
+      # companion inbox, the verdicts, the sessions' own HOME (their ovcli.conf
+      # and recall hints) and the reviewed repo's base clone, whose directory
+      # name is the config's ([github] clone_dir, else the repo's name).
+      - qcr-wt:/opt/qcr/wt
+      - qcr-archive:/opt/qcr/archive
+      - qcr-commands:/opt/qcr/commands
+      - qcr-digest:/opt/qcr/digest
+      - qcr-inject:/opt/qcr/inject
+      - qcr-verdict:/opt/qcr/verdict
+      - qcr-sessions-home:/opt/qcr/pihome
+      - qcr-base-clone:/opt/qcr/${QCR_CLONE_DIR:?set QCR_CLONE_DIR to the base clone's directory name ([github] clone_dir, else the repo's name)}
+    environment:
+      TZ: ${TZ:-Europe/Warsaw}
+      QC_REVIEW_PORT: "8787"
+      QCR_CONFIG: /opt/quickreview/config-home/${QCR_CONFIG_NAME:-config.toml}
+      # In-container bind must be 0.0.0.0 -- the published port targets the
+      # container's eth0; host exposure stays loopback-only above.
+      QC_BIND_HOST: "0.0.0.0"
+      # The secrets mount, named to the install locator on the CONTAINER (the
+      # entrypoint exports it too): a set [github] secrets_dir in the shared
+      # config.toml names a HOST path, and a `docker exec` process (the TUI's
+      # in-container mint-token.sh read) never inherits the entrypoint's env.
+      QCR_SECRETS_MOUNT: /opt/quickreview/secrets
+      # The uid the model's tools run as: never QCR_UID.
+      QCR_TOOLS_AS: ${QCR_TOOLS_AS:-65534}
+
+  # ---- the memory sidecar --------------------------------------------------
+  # OpenViking, its venv, llama-cpp-python and the pinned GGUF in a container
+  # of their own (docker/memory/). The daemon only probes its health
+  # ([openviking] endpoint = "remote", host = "memory"); the sidecar owns the
+  # processes, the boot provisioning and the re-embed. Port 1933 stays on the
+  # compose network. The GGUF is in the image: it boots offline.
+  memory:
+    image: ghcr.io/quickchatai/quickreview-memory:${QCR_VERSION:?set QCR_VERSION to the release to run (the image tag)}
+    user: "${QCR_UID:-1000}:${QCR_UID:-1000}"
+    init: true
+    restart: unless-stopped
+    cap_drop: [ALL]
+    security_opt:
+      - no-new-privileges:true
+    cpus: ${QCR_MEMORY_CPUS:-1}
+    mem_limit: ${QCR_MEMORY_LIMIT:-4g}
+    memswap_limit: ${QCR_MEMORY_LIMIT:-4g}
+    volumes:
+      # The memory store: memories, the vector db, ov.conf, the re-embed
+      # journal. Never wiped by anything here; `docker compose down` keeps it.
+      - qcr-memory:/opt/quickreview/state/openviking
+      # Read-only: the root and reviewer keys (and the hosted-embeddings key,
+      # only under that opt-in).
+      - ${QCR_SECRETS_DIR:?set QCR_SECRETS_DIR to your secrets directory}:/opt/quickreview/secrets:ro
+      # The SAME config.toml the daemon reads.
+      - ${QCR_CONFIG_HOME:?set QCR_CONFIG_HOME to the directory holding config.toml}:/opt/quickreview/config-home:ro
+    environment:
+      TZ: ${TZ:-Europe/Warsaw}
+      QCR_CONFIG_NAME: ${QCR_CONFIG_NAME:-config.toml}
+      # The memory engine's embedder: local by default -- the local English
+      # embedder, served on loopback inside this container -- so nothing but
+      # the model call leaves the machine. A hosted opt-in is these four in the
+      # project .env (the onboarding bring-up step mirrors them from config.toml
+      # [openviking] embedding_*) plus <secrets>/<key file> -- its OWN file,
+      # never pi's openai_api_key. Defaults mirror config.toml. Under local the
+      # entrypoint runs the image's pinned model whatever model/dimension say
+      # here.
+      QCR_OPENVIKING_EMBEDDING_PROVIDER: ${QCR_OPENVIKING_EMBEDDING_PROVIDER:-local}
+      QCR_OPENVIKING_EMBEDDING_MODEL: ${QCR_OPENVIKING_EMBEDDING_MODEL:-bge-small-en-v1.5-f16}
+      QCR_OPENVIKING_EMBEDDING_DIMENSION: ${QCR_OPENVIKING_EMBEDDING_DIMENSION:-384}
+      QCR_OPENVIKING_EMBEDDING_KEY_FILE: ${QCR_OPENVIKING_EMBEDDING_KEY_FILE:-openai_embeddings_api_key}
+      # The local embedder's runtime knobs: the port the rendered ov.conf routes
+      # embeddings to and the provisioning step serves on, and its thread count.
+      # The daemon reads the SAME two from config.toml [openviking]
+      # local_embedder_port / _threads, so the bring-up step mirrors them here
+      # on every bring-up -- a port the two disagree on is a search that nothing
+      # serves. Model, dimension and file are the image's (its ENV), never the
+      # .env's.
+      QCR_OPENVIKING_LOCAL_EMBEDDER_PORT: ${QCR_OPENVIKING_LOCAL_EMBEDDER_PORT:-1934}
+      QCR_OPENVIKING_LOCAL_EMBEDDER_THREADS: ${QCR_OPENVIKING_LOCAL_EMBEDDER_THREADS:-1}
+
+  # ---- webhook ingress sidecars -------------------------------------------
+  # All three run the same wrapper (docker/tunnel/sidecar.mjs) around an
+  # official vendor binary, and all three are OPTIONAL: no profile, no
+  # sidecar. They are the one thing built here rather than pulled -- a thin
+  # wrapper over the vendor's own image, built from docker/tunnel/ (extracted
+  # beside this file) the first time a profile selects one. None of them
+  # publishes a port -- the tunnel dials OUT and reaches the daemon over the
+  # compose network, so nothing new is exposed on the host. OpenViking's port
+  # (1933) stays unpublished on the host; it is reachable from the sidecars on
+  # the shared compose network, where its key is the access control. The
+  # sidecars mount one directory and, at most, the secrets dir.
+
+  # The default laptop shape: no account, no signup, rotating hostname.
+  # cloudflared prints the assigned *.trycloudflare.com name; the wrapper
+  # writes it to the shared hostname file and the daemon re-points the App's
+  # own webhook URL. A restart just writes the new name — nothing to fix by
+  # hand, and the reconcile poll covers the gap either way.
+  tunnel-quick:
+    profiles: ["quick-tunnel"]
+    build:
+      context: docker/tunnel
+      dockerfile: Dockerfile.cloudflared
+    image: quickreview-tunnel-cloudflared:v1
+    init: true
+    restart: unless-stopped
+    depends_on:
+      - daemon
+    environment:
+      QCR_TUNNEL_KIND: quick
+      QCR_TUNNEL_UPSTREAM: http://daemon:8787
+      QCR_TUNNEL_HOSTNAME_FILE: /ingress/hostname
+    volumes:
+      - qcr-ingress:/ingress
+
+  # Stable hostname, at the price of an account. The authtoken is a FILE in
+  # the secrets dir (<secrets>/ngrok_authtoken), read by the wrapper and
+  # handed to the client in its environment — never on a command line.
+  # QCR_NGROK_DOMAIN is your reserved domain, if you have one; without it the
+  # name still rotates and the self-heal still handles it.
+  tunnel-ngrok:
+    profiles: ["ngrok"]
+    build:
+      context: docker/tunnel
+      dockerfile: Dockerfile.ngrok
+    image: quickreview-tunnel-ngrok:v1
+    init: true
+    restart: unless-stopped
+    depends_on:
+      - daemon
+    environment:
+      QCR_TUNNEL_KIND: ngrok
+      QCR_TUNNEL_UPSTREAM: http://daemon:8787
+      QCR_TUNNEL_HOSTNAME_FILE: /ingress/hostname
+      QCR_TUNNEL_DOMAIN: ${QCR_NGROK_DOMAIN:-}
+    volumes:
+      - qcr-ingress:/ingress
+      - ${QCR_SECRETS_DIR:?set QCR_SECRETS_DIR to your secrets directory}:/opt/quickreview/secrets:ro
+
+  # Your own named Cloudflare tunnel: a permanent hostname on your domain,
+  # driven by the connector token the secrets wizard collects (tunnel_token).
+  # It writes NO hostname file — the name is yours and does not rotate, so
+  # `[ingress] shape` stays "none" and `[server] hostname` carries it.
+  tunnel-named:
+    profiles: ["named-tunnel"]
+    build:
+      context: docker/tunnel
+      dockerfile: Dockerfile.cloudflared
+    image: quickreview-tunnel-cloudflared:v1
+    init: true
+    restart: unless-stopped
+    depends_on:
+      - daemon
+    environment:
+      QCR_TUNNEL_KIND: named
+    volumes:
+      - ${QCR_SECRETS_DIR:?set QCR_SECRETS_DIR to your secrets directory}:/opt/quickreview/secrets:ro
+
+volumes:
+  qcr-state:
+  qcr-pihome:
+  # The daemon's runtime trees under the app root (see its volumes above).
+  qcr-wt:
+  qcr-archive:
+  qcr-commands:
+  qcr-digest:
+  qcr-inject:
+  qcr-verdict:
+  qcr-sessions-home:
+  qcr-base-clone:
+  # The memory store, the sidecar's alone.
+  qcr-memory:
+  # Shared by the daemon (read) and a tunnel sidecar (write): the hostname
+  # file, and nothing else.
+  qcr-ingress:

package/extensions/cli/bash-guard-ambient.ts

@@ -0,0 +1,71 @@
+// bash-guard's checkers with the process as their default context: the cwd,
+// the env and the secrets dirs of THIS process, where packages/pi-plugin/extensions/bash-guard.ts
+// takes them as arguments. Exported checkers that a test or a tool calls with
+// no policy of its own come here; a session's guard is built from an explicit
+// config (createBashGuard).
+import {
+  bashGuardConfigFromEnv as configFromEnv,
+  checkBashCommand as checkBash,
+  checkProcSecrets as checkProc,
+  checkReadPath as checkRead,
+  checkSecretPaths as checkSecrets,
+  defaultSecretPathContext as secretContext,
+  guardFlagsFromEnv,
+  type BashCheck,
+  type GuardPolicy,
+  type SecretPathContext,
+} from "@quickchatai/pi-quickreview/extensions/bash-guard.js";
+
+let cachedSecretDirs: SecretPathContext | null = null;
+/** The live process's context: dirs resolved once, the cwd read every call. */
+function processSecretContext(): SecretPathContext {
+  cachedSecretDirs ??= secretContext(process.env, process.cwd());
+  return { ...cachedSecretDirs, cwd: process.cwd() };
+}
+
+/** The policy the process describes, read at each call: what the checkers use
+ * when a caller passes none, so a test (or tool) that sets QCR_SANDBOX_ROOT or
+ * QCR_REPLAY sees it at once. The secrets dirs are resolved once. */
+function ambientPolicy(): GuardPolicy {
+  const { cwd: _cwd, ...secrets } = processSecretContext();
+  return {
+    ...guardFlagsFromEnv(process.env, process.cwd()),
+    cwd: process.cwd(),
+    secrets,
+  };
+}
+
+export function checkBashCommand(
+  cmd: string,
+  depth = 0,
+  cwd: string | null = process.cwd(),
+  policy: GuardPolicy = ambientPolicy(),
+): BashCheck {
+  return checkBash(cmd, depth, cwd, policy);
+}
+
+export function checkProcSecrets(cmd: string, cwd: string = process.cwd()): BashCheck {
+  return checkProc(cmd, cwd);
+}
+
+export function checkSecretPaths(cmd: string, ctx?: SecretPathContext): BashCheck {
+  return checkSecrets(cmd, ctx ?? processSecretContext());
+}
+
+export function checkReadPath(path: string, ctx?: SecretPathContext): BashCheck {
+  return checkRead(path, ctx ?? processSecretContext());
+}
+
+export function defaultSecretPathContext(
+  env: Readonly<Record<string, string | undefined>> = process.env,
+  cwd: string = process.cwd(),
+): SecretPathContext {
+  return secretContext(env, cwd);
+}
+
+export function bashGuardConfigFromEnv(
+  env: Readonly<Record<string, string | undefined>> = process.env,
+  cwd: string = process.cwd(),
+) {
+  return configFromEnv(env, cwd);
+}

package/extensions/cli/bash-guard.ts

@@ -0,0 +1,12 @@
+// The env shim for bash-guard: the one place the process's env and cwd become
+// its config (packages/pi-plugin/extensions/bash-guard.ts). The env is read here, once, at
+// activation.
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+  bashGuardConfigFromEnv,
+  createBashGuard,
+} from "@quickchatai/pi-quickreview/extensions/bash-guard.js";
+
+export default function activate(pi: ExtensionAPI): void {
+  void createBashGuard(bashGuardConfigFromEnv(process.env, process.cwd()))(pi);
+}

package/extensions/cli/companion-guard.ts

@@ -0,0 +1,8 @@
+// The env shim for companion-guard: the one place the process's env and cwd
+// become its config (extensions/companion-guard.ts).
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { companionGuardConfigFromEnv, createCompanionGuard } from "../companion-guard.js";
+
+export default function activate(pi: ExtensionAPI): void {
+  void createCompanionGuard(companionGuardConfigFromEnv(process.env, process.cwd()))(pi);
+}

package/extensions/cli/debug-round.ts

@@ -0,0 +1,9 @@
+// The env shim for the debug round: the one place the process's env, cwd and
+// home become its config (extensions/debug-round.ts).
+import { homedir } from "node:os";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { activateDebugRound } from "../debug-round.js";
+
+export default function activate(pi: ExtensionAPI): void {
+  activateDebugRound(pi, process.env, process.cwd(), homedir());
+}

package/extensions/cli/inject-bridge.ts

@@ -0,0 +1,8 @@
+// The env shim for the companion's inbox bridge: the one place the process's
+// env and cwd become its config (extensions/inject-bridge.ts).
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { createInjectBridge, injectBridgeConfigFromEnv } from "../inject-bridge.js";
+
+export default function activate(pi: ExtensionAPI): void {
+  void createInjectBridge(injectBridgeConfigFromEnv(pi, process.env, process.cwd()))(pi);
+}

package/extensions/cli/ledger-pin.ts

@@ -0,0 +1,13 @@
+// The env shim for ledger-pin: the one place the process's env, cwd and stderr
+// become its config (packages/pi-plugin/extensions/ledger-pin.ts).
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+  createLedgerPin,
+  ledgerPinConfigFromEnv,
+} from "@quickchatai/pi-quickreview/extensions/ledger-pin.js";
+
+export default function activate(pi: ExtensionAPI): void {
+  void createLedgerPin(
+    ledgerPinConfigFromEnv(process.env, process.cwd(), { log: (m) => console.error(m) }),
+  )(pi);
+}

package/extensions/cli/lens.ts

@@ -0,0 +1,22 @@
+// The env shim for the interactive pi's lens tools: the one place the process's
+// env, cwd, home and stderr become their config (packages/pi-plugin/extensions/lens.ts).
+import { homedir } from "node:os";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+  interactiveHostFor,
+  interactiveLens,
+} from "@quickchatai/pi-quickreview/extensions/lens.js";
+
+export default function activate(pi: ExtensionAPI): void {
+  if (typeof pi.registerTool !== "function") {
+    console.error("lens: pi.registerTool unavailable — lens and lens_wave not registered.");
+    return;
+  }
+  const env = process.env;
+  void interactiveLens(
+    env,
+    () => process.cwd(),
+    interactiveHostFor(env, homedir()),
+    (line) => console.error(line),
+  )(pi);
+}

package/extensions/cli/muted-theme.ts

@@ -0,0 +1,9 @@
+// The shim pi loads for the fleet muted theme (extensions/muted-theme.ts). It
+// reads nothing from the process; it exists so every extension pi loads by
+// path lives under extensions/cli/.
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { createMutedTheme } from "../muted-theme.js";
+
+export default function activate(pi: ExtensionAPI): void {
+  void createMutedTheme()(pi);
+}

package/extensions/cli/onboarding.ts

@@ -0,0 +1,8 @@
+// The env shim for the onboarding wizard's extension: the one place the
+// process's env and cwd become its config (extensions/onboarding.ts).
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { createOnboarding, onboardingConfigFromEnv } from "../onboarding.js";
+
+export default function activate(pi: ExtensionAPI): void {
+  void createOnboarding(onboardingConfigFromEnv(process.env, process.cwd()))(pi);
+}

package/extensions/cli/setup.ts

@@ -0,0 +1,8 @@
+// The env shim for the companion's setup & scan belt: the one place the
+// process's env and cwd become its config (extensions/setup.ts).
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { createSetup } from "../setup.js";
+
+export default function activate(pi: ExtensionAPI): void {
+  void createSetup({ env: process.env, cwd: process.cwd() })(pi);
+}

package/extensions/cli/tui-view.ts

@@ -0,0 +1,8 @@
+// The env shim for the companion's tui-view extension: the one place the
+// process's env and cwd become its config (extensions/tui-view.ts).
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { createTuiView, resolveFeedDir } from "../tui-view.js";
+
+export default function activate(pi: ExtensionAPI): void {
+  void createTuiView({ feedDir: resolveFeedDir(process.env, process.cwd()) })(pi);
+}