@quickchatai/quickreview 0.0.0-stage → 1.2.0

package/scripts/render-review.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# render-review.sh — render this round's review body and inline comments from
+# its findings record (`[review] render_outputs`, packages/pi-plugin/src/reviewrender.ts).
+#
+#   reads  state/findings/pr-<n>-round-<k>.json
+#   writes state/pr-<n>-round-<k>-review.md and state/pr-<n>-round-<k>-comments.json
+#
+# It posts nothing and reaches nothing outside state/: the session then posts
+# those two files through post-review.sh / approve-pr.sh, so every posting-time
+# guard still applies.
+#
+# Usage: render-review.sh <pr-number> <round-number>
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+. "$ROOT/scripts/install-locator.sh"
+CONFIG="$(qcr_locate_config "$ROOT")" || exit 1
+
+die() { echo "render-review: $*" >&2; exit 1; }
+PR="${1:-}"; ROUND="${2:-}"
+[[ "$PR" =~ ^[0-9]+$ && "$ROUND" =~ ^[0-9]+$ ]] || die "usage: render-review.sh <pr-number> <round-number>"
+
+BOT="$(sed -n '/^\[github\]/,/^\[/p' "$CONFIG" | sed -n 's/^[[:space:]]*bot_login[[:space:]]*=[[:space:]]*"\{0,1\}\([^"#]*\)"\{0,1\}.*/\1/p' | head -n1 | sed 's/[[:space:]]*$//' || true)"
+exec node "$ROOT/dist/src/reviewrendercli.js" "$ROOT" "$PR" "$ROUND" "$BOT"

package/scripts/reply-thread.sh

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+# reply-thread.sh — reply to an existing PR review comment (author ping-pong).
+#
+# A thin client of the daemon's post endpoint (src/ipc/postshim.ts). The host
+# a session runs on holds no GitHub credential and no config: the daemon
+# builds the payload, runs the posting-time guards and posts through the one
+# MutationGate with the install's dry_run. This script keeps its seeded name
+# and arguments and does nothing else; without the worker socket and the
+# capability fd in env the client refuses.
+#
+# Usage: reply-thread.sh <pr-number> <comment-id> <body-file>
+
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+exec node "$ROOT/dist/src/ipc/postshim.js" reply "$@"

package/scripts/required-passes.py

@@ -0,0 +1,112 @@
+#!/usr/bin/env python3
+"""required-passes.py — the posting route's required-pass check.
+
+    required-passes.py <state.db> <round-progress-dir> <pr> <round_no>
+
+Prints one line and exits:
+  0  "complete" or "unknown: <why>"  — posting may go on
+  3  "missing: <lens> (...)"         — a required pass failed and never
+                                       completed; post NOTHING
+The shell mirror of src/requiredpasses.ts (`requiredPassGap`): the required
+rows are the round's recorded plan rows marked `required` by the plan builder
+(pass-baseline and the risk passes), the evidence is the session's live
+round-progress snapshot. Only positive evidence blocks: an unreadable plan supplies
+no required rows, so the result is complete; with required rows, an unreadable
+snapshot, or a snapshot of another round, is unknown and never blocks.
+tests/required-passes.test.ts runs this against the TypeScript rule.
+"""
+import json
+import os
+import re
+import sqlite3
+import sys
+
+TIER_SUFFIX = re.compile(r"--(?:terra-med|sol-med|sol-high)$")
+
+
+def lens_for_agent(agent):
+    return TIER_SUFFIX.sub("", agent)
+
+
+def load_plans(db, pr, round_no):
+    try:
+        con = sqlite3.connect(f"file:{db}?mode=ro", uri=True, timeout=5)
+        try:
+            try:
+                row = con.execute(
+                    "SELECT pass_plan, sweep_plan FROM rounds WHERE pr = ? AND round_no = ? ORDER BY id DESC LIMIT 1",
+                    (pr, round_no),
+                ).fetchone()
+            except sqlite3.OperationalError:
+                # Older databases predate the optional pre-approval sweep.
+                row = con.execute(
+                    "SELECT pass_plan, NULL FROM rounds WHERE pr = ? AND round_no = ? ORDER BY id DESC LIMIT 1",
+                    (pr, round_no),
+                ).fetchone()
+        finally:
+            con.close()
+    except Exception:
+        return (None, None)
+    if not row:
+        return (None, None)
+    def parse(raw):
+        try:
+            plan = json.loads(raw)
+            return plan if isinstance(plan, list) else None
+        except Exception:
+            return None
+    return (parse(row[0]), parse(row[1]))
+
+
+def load_progress(progress_dir, pr):
+    try:
+        with open(os.path.join(progress_dir, f"pr-{pr}.json")) as fh:
+            value = json.load(fh)
+    except Exception:
+        return None
+    if not isinstance(value, dict) or value.get("pr") != pr or not isinstance(value.get("agents"), list):
+        return None
+    return value
+
+
+def gap(plan, progress, round_no, sweep_plan=None):
+    required = {}
+    for phase, rows in (("plan", plan), ("sweep", sweep_plan)):
+        for row in rows or []:
+            if isinstance(row, dict) and row.get("required") is True and isinstance(row.get("lens"), str):
+                key = (phase, row["lens"])
+                required[key] = required.get(key, 0) + 1
+    if not required:
+        return ("complete", None)
+    if progress is None:
+        return ("unknown", "no readable round-progress snapshot")
+    if progress.get("round_no") != round_no:
+        return ("unknown", f"round-progress snapshot is for round {progress.get('round_no', '?')}, not {round_no}")
+    missing = []
+    for (phase, lens), rows in required.items():
+        runs = [
+            a for a in progress["agents"]
+            if isinstance(a, dict) and isinstance(a.get("agent"), str) and lens_for_agent(a["agent"]) == lens
+            and (a.get("phase") == "sweep" if phase == "sweep" else a.get("phase") in (None, "plan"))
+        ]
+        completed = sum(1 for a in runs if a.get("status") == "completed")
+        failed = [a for a in runs if a.get("status") == "failed"]
+        if failed and completed < rows:
+            errors = "; ".join(a.get("error") or "failed" for a in failed)
+            missing.append(f"{'sweep ' if phase == 'sweep' else ''}{lens} ({completed}/{rows} completed, {len(failed)} failed: {errors})")
+    return ("missing", ", ".join(missing)) if missing else ("complete", None)
+
+
+def main(argv):
+    if len(argv) != 5 or not argv[3].isdigit() or not argv[4].isdigit():
+        print("unknown: usage: required-passes.py <state.db> <round-progress-dir> <pr> <round_no>")
+        return 0
+    db, progress_dir, pr, round_no = argv[1], argv[2], int(argv[3]), int(argv[4])
+    plan, sweep_plan = load_plans(db, pr, round_no)
+    state, detail = gap(plan, load_progress(progress_dir, pr), round_no, sweep_plan)
+    print(state if detail is None else f"{state}: {detail}")
+    return 3 if state == "missing" else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))

package/scripts/smoke-companion.sh

@@ -0,0 +1,211 @@
+#!/usr/bin/env bash
+# smoke-companion.sh — the manual checklist for the local companion.
+# `npm run smoke:companion`.
+#
+# Unlike scripts/companion-e2e.sh (throwaway container, fake sinks, proves the
+# plumbing) this walks the REAL companion the way `qcr tui` does it:
+#
+#   1. the image builds / is present
+#   2. qcr companion up → status running → adopt is idempotent
+#   3. pi auth persisted on the pihome volume (SKIPPED until /login has run)
+#   4. the container holds no key file (only the agent socket, ssh config and
+#      known_hosts, rule 8), ssh to the VM works through the agent when the
+#      host has one, and OpenViking is reached through the memory forward
+#   5. an overseer inject lands in the daemon's inject dir — DRY BY DEFAULT:
+#      prints the exact command; only --live actually writes to the VM
+#   6. daily rollover on a faked date (QCR_FAKE_TODAY) against the real
+#      container, into temp state — the persistent rollover state is untouched
+#   7. qcr companion down leaves the volumes (and the conversation) alone
+#
+# Nothing here mutates GitHub. Step 5 is the only step that can touch the VM at
+# all, and it is opt-in.
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")/.." && pwd)"
+LIVE=0
+[[ "${1:-}" == "--live" ]] && LIVE=1
+
+PASS=0
+FAIL=0
+SKIP=0
+pass() { printf 'PASS  %s\n' "$1"; PASS=$((PASS + 1)); }
+fail() { printf 'FAIL  %s\n' "$1"; FAIL=$((FAIL + 1)); }
+skip() { printf 'SKIP  %s\n' "$1"; SKIP=$((SKIP + 1)); }
+step() { printf '\n--- %s\n' "$1"; }
+
+command -v docker >/dev/null 2>&1 || { echo "smoke:companion: docker is required" >&2; exit 2; }
+
+WORK="$(mktemp -d -t qcr-companion-smoke-XXXXXX)"
+# A run that did not succeed keeps the directory: its failure lines point at build.log and ssh.log.
+trap 'rc=$?; if [[ "$rc" -eq 0 ]]; then rm -rf "$WORK"; else echo "smoke:companion: logs kept in $WORK" >&2; fi' EXIT
+
+# dist must exist before any of the node one-liners below.
+(cd "$ROOT" && npm run --silent build)
+
+# Config values, read once through the same loader the TUI uses. The emitted
+# lines are plain KEY="value" pairs; a value containing a double quote or a
+# backslash is rejected rather than eval'd.
+CONF="$(cd "$ROOT" && node --input-type=module -e '
+const { loadConfig } = await import("./dist/src/config.js");
+const c = loadConfig();
+const emit = (k, v) => {
+  if (/["\\$`]/.test(String(v))) throw new Error(`unsafe config value for ${k}: ${v}`);
+  console.log(`${k}="${v}"`);
+};
+emit("CONTAINER", c.companion.container_name);
+emit("IMAGE", c.companion.image);
+emit("PIHOME", c.companion.pihome_volume);
+emit("SESSION", c.companion.session);
+emit("SSH_HOST", c.tui.ssh_host);
+emit("VM_CONTAINER", c.tui.container);
+emit("VM_ROOT", c.tui.remote_sandbox_root);
+emit("SUDO", c.tui.sudo_docker ? 1 : 0);
+')"
+eval "$CONF"
+DOCKER_ON_VM="docker"
+[[ "$SUDO" == "1" ]] && DOCKER_ON_VM="sudo docker"
+
+# remote_sandbox_root ships empty: the container's qcr.layout label decides
+# (the same probe as src/tui/layout.ts).
+if [[ -z "$VM_ROOT" ]]; then
+  LAYOUT="$(ssh "$SSH_HOST" "$DOCKER_ON_VM inspect -f '{{index .Config.Labels \"qcr.layout\"}}' $VM_CONTAINER" 2>/dev/null || true)"
+  VM_ROOT="$(cd "$ROOT" && node --input-type=module -e '
+const { rootForLayout } = await import("./dist/src/tui/layout.js");
+console.log(rootForLayout(process.argv[1] === "release" ? "release" : "legacy"));
+' "$LAYOUT")"
+fi
+
+QCR="$ROOT/scripts/qcr"
+
+# The app's build stamp (src/appstamp.ts) for the image's qcr.build-sha label.
+app_stamp() {
+  node --input-type=module -e 'const m = await import(process.argv[1]); console.log(m.appStamp(process.argv[2]));' \
+    "$1/dist/src/appstamp.js" "$1"
+}
+
+# --- 1. image ----------------------------------------------------------------
+step "image"
+# The release image (docker/Dockerfile) compiles the app itself.
+if docker image inspect "$IMAGE" >/dev/null 2>&1; then
+  pass "image $IMAGE present"
+elif docker build -t "$IMAGE" -f "$ROOT/docker/Dockerfile" \
+  --build-arg BUILD_SHA="$(app_stamp "$ROOT")" \
+  "$ROOT" >"$WORK/build.log" 2>&1; then
+  pass "image $IMAGE built"
+else
+  fail "image $IMAGE builds (see $WORK/build.log)"
+fi
+
+# --- 2. lifecycle ------------------------------------------------------------
+step "qcr companion up / status"
+if "$QCR" companion up >"$WORK/up.log" 2>&1; then pass "qcr companion up: $(tail -1 "$WORK/up.log")"; else fail "qcr companion up ($(tail -1 "$WORK/up.log"))"; fi
+if "$QCR" companion up >"$WORK/up2.log" 2>&1 && grep -q "adopted" "$WORK/up2.log"; then
+  pass "second up adopts, never spawns a twin"
+else
+  fail "second up adopts (got: $(tail -1 "$WORK/up2.log"))"
+fi
+if "$QCR" companion status 2>&1 | grep -q running; then pass "qcr companion status: running"; else fail "qcr companion status: running"; fi
+
+# --- 3. pi auth --------------------------------------------------------------
+step "pi auth (one-time /login)"
+if docker exec "$CONTAINER" sh -c 'test -f "$HOME/.pi/agent/auth.json"' >/dev/null 2>&1; then
+  pass "auth.json persisted on volume $PIHOME"
+else
+  skip "auth.json absent — run: docker exec -it $CONTAINER tmux attach -t $SESSION, then /login"
+fi
+
+# --- 4. full ssh through the agent, no key in the container; memory reachable --
+# Rule 8: the companion holds the owner's full ssh
+# to the VM as the host's agent socket, ssh config and known_hosts, mounted
+# read-only. A key FILE in the container is the failure; ssh itself working is
+# expected whenever the host has an agent.
+step "companion holds no key file"
+keys="$(docker exec "$CONTAINER" sh -c 'ls -A "$HOME/.ssh" 2>/dev/null' | grep -vxE 'config|known_hosts' || true)"
+if [ -n "$keys" ]; then
+  fail "~/.ssh in the container holds more than config and known_hosts: $keys (rule 8: never a key file)"
+else
+  pass "~/.ssh holds at most config and known_hosts"
+fi
+step "ssh to the VM through the host's agent"
+if [ -z "${SSH_AUTH_SOCK:-}" ]; then
+  skip "no ssh agent on this host — the companion gets none either"
+elif docker exec "$CONTAINER" ssh -o BatchMode=yes -o ConnectTimeout=5 "$SSH_HOST" true >"$WORK/ssh.log" 2>&1; then
+  pass "ssh $SSH_HOST works inside the container, through the agent"
+else
+  fail "ssh $SSH_HOST failed inside the container (see $WORK/ssh.log) — is the agent mounted? (rule 8)"
+fi
+
+step "memory reachable from inside the container"
+MEM_URL="${QCR_MEMORY_ENDPOINT:-http://198.51.100.1:1933}"
+if docker exec "$CONTAINER" node -e "
+  fetch('$MEM_URL/health').then(r => r.ok ? process.exit(0) : process.exit(1)).catch(() => process.exit(1))
+" >"$WORK/memory.log" 2>&1; then
+  pass "OpenViking /health reachable at $MEM_URL"
+else
+  skip "OpenViking unreachable at $MEM_URL — is the forward installed? (scripts/companion-memory-forward.mjs status)"
+fi
+
+# --- 5. overseer inject (dry by default) -------------------------------------
+step "overseer inject (dry-run unless --live)"
+INJECT_DIR="$VM_ROOT/inject/overseer"
+NAME="$(date -u +%Y-%m-%dT%H-%M-%SZ)-smoke.md"
+# Exactly the shape src/tui/msg.ts writes: atomic tmp+mv into the daemon's
+# inject dir, content on stdin so it never rides a command line.
+WRITE_CMD="$DOCKER_ON_VM exec -i $VM_CONTAINER sh -c \"mkdir -p '$INJECT_DIR' && cat > '$INJECT_DIR/.$NAME.tmp' && mv '$INJECT_DIR/.$NAME.tmp' '$INJECT_DIR/$NAME'\""
+PROBE_CMD="$DOCKER_ON_VM exec $VM_CONTAINER sh -c \"test -f '$INJECT_DIR/.done/$NAME'\""
+if [[ "$LIVE" == "1" ]]; then
+  if printf '[companion smoke] ignore me — smoke:companion inject check.\n' |
+     ssh "$SSH_HOST" "$WRITE_CMD" >"$WORK/inject.log" 2>&1; then
+    sleep 5
+    if ssh "$SSH_HOST" "$PROBE_CMD" >/dev/null 2>&1; then
+      pass "overseer inject delivered (bridge archived it)"
+    else
+      fail "overseer inject delivered — file still pending in $INJECT_DIR"
+    fi
+  else
+    fail "overseer inject write ($(tail -1 "$WORK/inject.log"))"
+  fi
+else
+  printf '      would run: ssh %s %s\n' "$SSH_HOST" "$WRITE_CMD"
+  skip "overseer inject — pass --live to actually write to the VM"
+fi
+
+# --- 6. rollover on a faked date ---------------------------------------------
+step "daily rollover (QCR_FAKE_TODAY, temp state)"
+mkdir -p "$WORK/state" "$WORK/inject"
+printf '{"last_open_date":"1999-12-31","updated_at":""}\n' > "$WORK/state/rollover.json"
+if (cd "$ROOT" && QCR_FAKE_TODAY=2099-01-01 node --input-type=module -e '
+const { loadConfig } = await import("./dist/src/config.js");
+const { CompanionRollover } = await import("./dist/src/tui/rollover.js");
+const { realDockerRunner } = await import("./dist/src/tui/companion.js");
+const work = process.argv[1];
+const r = new CompanionRollover(loadConfig().companion, realDockerRunner, {
+  statePath: `${work}/state/rollover.json`,
+  policyStatePath: `${work}/state/alert-policy.json`,
+  templatePath: "prompts/companion-day-open.md",
+  injectDir: `${work}/inject`,
+});
+const report = await r.run();
+for (const s of report.steps) console.log(`      · ${s}`);
+if (report.verdict.kind !== "rollover") { console.error(`expected a rollover, got ${report.verdict.kind}`); process.exit(1); }
+if (!report.dayOpen || /\{\{\w+\}\}/.test(report.dayOpen)) { console.error("day-open has unfilled placeholders"); process.exit(1); }
+' "$WORK"); then
+  pass "rollover archived + assembled the day-open message"
+  # It went to the temp inject dir, never the live one.
+  if [[ -f "$WORK/inject/2099-01-01-day-open.md" ]]; then
+    pass "day-open queued ($(wc -c <"$WORK/inject/2099-01-01-day-open.md") bytes, temp dir only)"
+  else
+    fail "day-open queued"
+  fi
+else
+  fail "rollover on a faked date"
+fi
+printf '      note: this killed the live companion pi session; qcr tui respawns it.\n'
+
+# --- 7. down -----------------------------------------------------------------
+step "qcr companion down"
+if "$QCR" companion down >"$WORK/down.log" 2>&1; then pass "qcr companion down: $(tail -1 "$WORK/down.log")"; else fail "qcr companion down"; fi
+if docker volume inspect "$PIHOME" >/dev/null 2>&1; then pass "pihome volume $PIHOME survived the stop"; else fail "pihome volume $PIHOME survived the stop"; fi
+
+printf '\n=== companion smoke: %d passed, %d failed, %d skipped\n' "$PASS" "$FAIL" "$SKIP"
+[[ "$FAIL" -eq 0 ]]

package/scripts/tui-deploy-runner.mjs

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+// Detached child for the TUI deploy tab: `deploy.sh release <version>`. The
+// operator's checkout is rebuilt by the pull that follows a release, which
+// re-execs the TUI; this process must outlive that re-exec and leave a durable
+// result the new TUI generation can attach to.
+import { closeSync, fsyncSync, mkdirSync, openSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { spawn } from "node:child_process";
+
+const [root, logPath, resultPath, version] = process.argv.slice(2);
+if (!root || !logPath || !resultPath || !version) process.exit(2);
+// The same spelling scripts/deploy.sh accepts for a release: it names an image tag.
+if (!/^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.]+)?$/.test(version)) process.exit(2);
+mkdirSync(dirname(logPath), { recursive: true });
+const logFd = openSync(logPath, "a", 0o600);
+const child = spawn("bash", [join(root, "scripts", "deploy.sh"), "release", version], {
+  cwd: root,
+  env: { ...process.env, ANSIBLE_FORCE_COLOR: "0", PY_COLORS: "0", NO_COLOR: "1" },
+  stdio: ["ignore", logFd, logFd],
+});
+
+let stopping = false;
+const stop = () => {
+  if (stopping) return;
+  stopping = true;
+  try {
+    child.kill("SIGTERM");
+  } catch {
+    /* already gone */
+  }
+};
+process.on("SIGTERM", stop);
+process.on("SIGINT", stop);
+
+let finished = false;
+const finish = (code, signal, error) => {
+  if (finished) return;
+  finished = true;
+  closeSync(logFd);
+  const result = {
+    code: typeof code === "number" ? code : null,
+    signal: signal ?? null,
+    ...(error ? { error: String(error) } : {}),
+    finished_at: new Date().toISOString(),
+  };
+  const tmp = `${resultPath}.tmp-${process.pid}`;
+  const fd = openSync(tmp, "w", 0o600);
+  writeFileSync(fd, `${JSON.stringify(result, null, 2)}\n`);
+  fsyncSync(fd);
+  closeSync(fd);
+  renameSync(tmp, resultPath);
+};
+
+child.on("error", (err) => {
+  finish(1, null, err);
+  process.exit(1);
+});
+child.on("close", (code, signal) => {
+  finish(code, signal);
+  process.exit(typeof code === "number" ? code : 1);
+});

package/scripts/verify-dist.mjs

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+// Does `dist/` actually contain what the build claims to have produced?
+//
+// Why this exists: `tsconfig.json` runs `incremental` (so
+// `npm run dev`'s blocking typecheck is ~1s instead of ~4s) plus
+// `noEmitOnError` (so a failing build cannot re-exec the TUI from a
+// half-written dist). Together they leave one hole: tsc decides what to emit
+// from its BUILD INFO, not from what is on disk. Delete one emitted file —
+//
+//     rm dist/src/tui/startup.js && npx tsc -b   # exit 0
+//
+// — and tsc says everything is up to date and emits nothing. `npm run build`
+// reports success over a `dist/` that is missing a module. The same state
+// arrives from an interrupted build, a half-copied tree, or a `find … -delete`
+// that went wider than intended.
+//
+// That is survivable in `dev-tui.sh` (node throws ERR_MODULE_NOT_FOUND on the
+// spot). It is not survivable in `deploy.sh`, which rsyncs `dist/` to the VM:
+// the missing module ships, and the daemon crashes there instead of here.
+//
+// So "the build succeeded" means "and the output is on disk", for the app's
+// dist/ and for every project the root tsconfig.json references (the review
+// core's packages/pi-plugin/dist). Cheap (a few hundred stats),
+// dependency-free, and runs from a bare checkout.
+//
+// The reverse hole too: tsc never deletes the output of an input that is gone.
+// A source moved or removed leaves its old compiled module behind — still
+// importable, still hashed into the companion's app stamp, still copied into
+// an image built from the host's dist/. So a compiled module with no source
+// among the current inputs is an error as well, and the fix is the same cold
+// build.
+import { existsSync, readFileSync, readdirSync, rmSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+export const ROOT = resolve(HERE, "..");
+
+/** tsconfig.json carries `//` comments; JSON.parse does not. */
+export function readTsconfig(root = ROOT) {
+  const raw = readFileSync(join(root, "tsconfig.json"), "utf8");
+  return JSON.parse(raw.replace(/^\s*\/\/.*$/gm, ""));
+}
+
+/**
+ * Every `.ts` tsc is asked to compile, as repo-relative POSIX paths.
+ *
+ * Deliberately derived from tsconfig's own `include`/`exclude` rather than
+ * hard-coded: the excluded set (e.g. `extensions/inline-bash.ts`, loaded from
+ * source by pi's jiti) can change, and a checker that disagrees with the
+ * compiler is worse than no checker.
+ * `.d.ts` files declare types and emit nothing.
+ * The explicit `.mjs` include (allowJs, for the vendored OpenViking helpers)
+ * lists those files too: tsc copies them, and the worker needs them in dist/.
+ */
+export function inputFiles(root = ROOT, cfg = readTsconfig(root)) {
+  const includeRoots = (cfg.include ?? [])
+    .map((pattern) => pattern.split("/")[0])
+    .filter((dir, i, all) => all.indexOf(dir) === i);
+  const excluded = new Set((cfg.exclude ?? []).map((p) => p.replace(/\/+$/, "")));
+  // A plain-JS tree the include names (`dir/**/*.mjs`, with allowJs) is emitted
+  // too, under the same name.
+  const jsDirs = (cfg.include ?? [])
+    .filter((pattern) => pattern.endsWith(".mjs"))
+    .map((pattern) => pattern.split("/**")[0]);
+  const out = [];
+  const walk = (relDir) => {
+    if (excluded.has(relDir)) return;
+    let entries;
+    try {
+      entries = readdirSync(join(root, relDir), { withFileTypes: true });
+    } catch {
+      return; // an include root that does not exist here is not a failure
+    }
+    for (const entry of entries) {
+      const rel = `${relDir}/${entry.name}`;
+      if (excluded.has(rel)) continue;
+      if (entry.isDirectory()) walk(rel);
+      else if (entry.name.endsWith(".ts") && !entry.name.endsWith(".d.ts")) out.push(rel);
+      else if (entry.name.endsWith(".mjs") && jsDirs.some((dir) => rel.startsWith(`${dir}/`)))
+        out.push(rel);
+    }
+  };
+  for (const dir of includeRoots) walk(dir);
+  return out.sort();
+}
+
+/** Where tsc puts a given input. No `rootDir` is set, so the inferred one is
+ * the repo root and the tree is mirrored under `outDir` (`dist/src/…`). A `.mjs`
+ * keeps its name. */
+export function emittedPath(relTs, cfg = readTsconfig()) {
+  return `${cfg.compilerOptions?.outDir ?? "dist"}/${relTs.replace(/\.ts$/, ".js")}`;
+}
+
+/** The projects `tsc -b` builds: the root's, and each one its `references`
+ * name (packages/pi-plugin, the review core), as repo-relative directories
+ * ("" is the root). */
+export function projectDirs(root = ROOT) {
+  const refs = (readTsconfig(root).references ?? []).map((r) => r.path.replace(/\/+$/, ""));
+  return ["", ...refs];
+}
+
+/** Inputs whose compiled output is not on disk, across every project the
+ * build compiles, as repo-relative paths. Empty = the build is real. */
+export function missingArtifacts(root = ROOT) {
+  return projectDirs(root).flatMap((dir) => {
+    const at = join(root, dir);
+    const cfg = readTsconfig(at);
+    const rel = (p) => (dir ? `${dir}/${p}` : p);
+    return inputFiles(at, cfg)
+      .map((f) => ({ source: rel(f), emitted: rel(emittedPath(f, cfg)) }))
+      .filter(({ emitted }) => !existsSync(join(root, emitted)));
+  });
+}
+
+/** Compiled modules (`.js`, `.mjs`) in a project's outDir that no current
+ * input emits, as repo-relative paths: what a moved or deleted source left
+ * behind. Empty = nothing stale. */
+export function orphanedArtifacts(root = ROOT) {
+  return projectDirs(root).flatMap((dir) => {
+    const at = join(root, dir);
+    const cfg = readTsconfig(at);
+    const rel = (p) => (dir ? `${dir}/${p}` : p);
+    const outDir = cfg.compilerOptions?.outDir ?? "dist";
+    const emitted = new Set(inputFiles(at, cfg).map((f) => emittedPath(f, cfg)));
+    const out = [];
+    const walk = (relDir) => {
+      let entries;
+      try {
+        entries = readdirSync(join(at, relDir), { withFileTypes: true });
+      } catch {
+        return;
+      }
+      for (const entry of entries) {
+        const p = `${relDir}/${entry.name}`;
+        if (entry.isDirectory()) walk(p);
+        else if (/\.m?js$/.test(entry.name) && !emitted.has(p)) out.push(rel(p));
+      }
+    };
+    walk(outDir);
+    return out.sort();
+  });
+}
+
+/** Deletes what `orphanedArtifacts` finds, with each module's map and
+ * declarations, and returns the modules removed. tsc never deletes the output
+ * of a moved or removed source, and a dist/ is ours alone, so the build clears
+ * the leftovers rather than failing every existing checkout. */
+export function removeOrphanedArtifacts(root = ROOT) {
+  const orphans = orphanedArtifacts(root);
+  for (const f of orphans) {
+    const stem = f.replace(/\.(m?)js$/, "");
+    for (const p of [
+      f,
+      `${f}.map`,
+      `${stem}.d.ts`,
+      `${stem}.d.ts.map`,
+      `${stem}.d.mts`,
+      `${stem}.d.mts.map`,
+    ])
+      rmSync(join(root, p), { force: true });
+  }
+  return orphans;
+}
+
+const COLD_BUILD = "  rm -rf dist packages/*/dist node_modules/.cache && npm run build";
+
+function main() {
+  const root = process.argv[2] ? resolve(process.argv[2]) : ROOT;
+  for (const dir of projectDirs(root)) {
+    const at = join(root, dir);
+    const outDir = join(at, readTsconfig(at).compilerOptions?.outDir ?? "dist");
+    if (!existsSync(outDir)) {
+      console.error(
+        `verify-dist: ${relative(root, outDir) || outDir} does not exist — the build produced nothing.`,
+      );
+      process.exit(1);
+    }
+  }
+  const removed = removeOrphanedArtifacts(root);
+  if (removed.length > 0)
+    console.error(
+      `verify-dist: removed ${removed.length} compiled file(s) whose source is gone (moved or deleted).`,
+    );
+  const missing = missingArtifacts(root);
+  if (missing.length === 0) return;
+  console.error(
+    `verify-dist: the build reported success but ${missing.length} compiled file(s) are missing from a dist/:`,
+  );
+  for (const { source, emitted } of missing.slice(0, 20))
+    console.error(`  ${emitted}   (from ${source})`);
+  if (missing.length > 20) console.error(`  … and ${missing.length - 20} more`);
+  console.error("");
+  console.error("This is `incremental`: tsc emits from its build info, not from what is on disk,");
+  console.error("so a file deleted after the last successful build is never re-emitted. Fix with:");
+  console.error(COLD_BUILD);
+  process.exit(1);
+}
+
+// `node scripts/verify-dist.mjs` runs the check; importing it does not.
+if (process.argv[1] && resolve(process.argv[1]) === resolve(fileURLToPath(import.meta.url))) main();