@quickchatai/quickreview 1.1.0 → 1.3.1

package/extensions/setup.ts

@@ -57,7 +57,12 @@ import {
 } from "@quickchatai/pi-quickreview/extensions/pi-tool.js";
 import { fileURLToPath } from "node:url";
 import { configHome, stateHome } from "../src/install.js";
-import { SetupEngine, type CutStatus, type CutView } from "../src/setup/engine.js";
+import { SetupEngine } from "../src/setup/engine.js";
+import {
+  renderCut,
+  renderDraft,
+  renderStatus,
+} from "@quickchatai/pi-quickreview/src/scan/cutrender.js";
 import type { HistoryTheme, HistoryThemesFile } from "../src/setup/history.js";
 import {
   HISTORY_SECTIONS,
@@ -154,75 +159,14 @@ export function renderFacts(facts: RepoFacts, head: string | null): string {
   ].join("\n\n");
 }
 
-export function renderCut(title: string, v: CutView): string {
-  const rows = v.units.map((u) => {
-    const split =
-      u.cases === null
-        ? " — case coverage UNKNOWN"
-        : u.cases.length > 1
-          ? ` — split into ${u.cases.length} cases (${u.cases.map((c) => `${c.id}: ${c.files}f/${c.lines}l`).join(", ")})`
-          : "";
-    const over = u.cases?.some((c) => c.over_budget)
-      ? " [a file alone exceeds one case — a scan reads it in line ranges]"
-      : "";
-    return `  - ${u.name} [${u.kind}] ${u.roots.map(displayRoot).join(", ")}: ${u.files ?? "UNKNOWN"} files, ${u.reviewable ?? "UNKNOWN"} reviewable, ${u.lines ?? "UNKNOWN"} lines${split}${over}${u.note ? ` — ${u.note}` : ""}`;
-  });
-  const lines = [`${title}:`, ...rows];
-  if (v.ignored.length > 0)
-    lines.push(`  ignored: ${v.ignored.join(", ")} (${v.ignored_files ?? "UNKNOWN"} files)`);
-  for (const e of v.errors) lines.push(`  ✗ ${e}`);
-  for (const b of v.blocking_save) lines.push(`  ! ${b}`);
-  return lines.join("\n");
-}
-
-/** How a rendering names the save that makes a draft the cut — the tool, or
- * the `qcr scan units` verb. */
-export interface CutVerbs {
-  save: string;
-}
-export const CUT_TOOL_VERBS: CutVerbs = { save: "setup_unit_cut_save" };
-export const CUT_CLI_VERBS: CutVerbs = { save: "qcr scan units save" };
-
-/** A stored or adjusted draft, and that it is not in use until saved. */
-export function renderDraft(
-  title: string,
-  draft: CutView,
-  verbs: CutVerbs = CUT_TOOL_VERBS,
-): string {
-  return `${renderCut(title, draft)}\n\nNot in use until ${verbs.save}.`;
-}
-
-export function renderStatus(s: CutStatus): string {
-  const out: string[] = [];
-  for (const p of s.problems) out.push(`✗ ${p}`);
-  if (s.saved) {
-    const stale =
-      s.saved.blocking_save.length > 0 ? " — STALE against the repo now, see the ! lines" : "";
-    out.push(
-      renderCut(
-        `Saved unit cut (saved ${s.saved.saved_at}${s.saved.head ? ` at ${s.saved.head.slice(0, 12)}` : ""})${stale}`,
-        s.saved,
-      ),
-    );
-  } else if (s.cut_file_unreadable) {
-    out.push(
-      "Saved unit cut: UNKNOWN — the cut file could not be read (see above); nothing will overwrite it.",
-    );
-  } else {
-    out.push("No saved unit cut yet.");
-  }
-  if (s.draft)
-    out.push(
-      renderCut(
-        `Draft (${s.draft.source}, updated ${s.draft.updated_at}) — not in use until saved`,
-        s.draft,
-      ),
-    );
-  if (s.has_previous)
-    out.push("The cut before the saved one is kept as `previous` in the state home.");
-  return out.join("\n\n");
-}
-
+export {
+  CUT_CLI_VERBS,
+  CUT_TOOL_VERBS,
+  renderCut,
+  renderDraft,
+  renderStatus,
+  type CutVerbs,
+} from "@quickchatai/pi-quickreview/src/scan/cutrender.js";
 export function renderThemes(themes: readonly HistoryTheme[]): string {
   return themes.length === 0
     ? "  (none — an empty history has no themes)"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quickchatai/quickreview",
-  "version": "1.1.0",
+  "version": "1.3.1",
   "private": false,
   "//private": "The root is the published `qcr` CLI: the whole app (TUI, daemon, companion, every verb), installed with npm, pnpm or bun. It depends on the pi plugin (packages/pi-plugin) at its exact version and on pi at the exact pins below. Publishing is a release step of its own, never part of a build.",
   "description": "A 24/7 AI code reviewer for GitHub: a deterministic daemon driving pi review sessions, with an operator TUI and a local qcr review",
@@ -94,11 +94,10 @@
     "prepack": "npm run build",
     "watch": "node scripts/tsc-watch.mjs -b --watch --preserveWatchOutput",
     "dev": "bash scripts/dev-tui.sh",
-    "onboard": "bash scripts/qcr onboard",
     "test": "vitest run",
     "//canary:pi": "The offline pi canaries (tests/pi-canary/): the real pi SDK at the pinned version on pi-ai's faux provider, so no network and no cost. They also run inside `npm test`; this is the named entry point CI requires whenever the pi dependencies change (a bump is gated by it).",
     "canary:pi": "vitest run tests/pi-canary",
-    "//canary:pi:range": "The same canaries on each pi version the plugin's peer range (packages/pi-plugin/package.json) should hold, refusing one outside it: no argument runs the installed pi; `-- --install 1.4.x` fetches another first (the registry: CI's pi-range matrix runs it in a fresh checkout). Needs the build.",
+    "//canary:pi:range": "The same canaries on each pi version the plugin's peer range (packages/pi-plugin/package.json) should hold, refusing one outside it: no argument runs the installed pi; `-- --install 1.4.x` fetches another first (the registry). Run it by hand before a version joins the peer range; CI runs only the installed pi's canaries. Needs the build.",
     "canary:pi:range": "node scripts/pi-canary-range.mjs",
     "//lint": "Deliberately NOT chained into `test` or `build`: scripts/dev-tui.sh blocks on the build before the TUI paints (ruling 5), and an ESLint pass there is seconds of blank terminal. CI runs it as its own step.",
     "lint": "node --max-old-space-size=4096 node_modules/eslint/bin/eslint.js .",
@@ -116,7 +115,7 @@
   },
   "dependencies": {
     "@earendil-works/pi-ai": "1.4.0",
-    "@quickchatai/pi-quickreview": "1.1.0",
+    "@quickchatai/pi-quickreview": "1.3.1",
     "@earendil-works/pi-coding-agent": "1.4.0",
     "better-sqlite3": "13.0.3",
     "smol-toml": "1.9.1"
@@ -132,6 +131,9 @@
     "vitest": "5.0.5",
     "yaml": "2.9.1"
   },
+  "overrides": {
+    "undici": "8.12.2"
+  },
   "qcrPi": {
     "//": "Named qcrPi, never `pi`: pi reads a package.json `pi` key as a package manifest, and this root is not a pi package (the plugin is packages/pi-plugin). pi and pi-ai are exact dependencies above (types for the extensions, and the VM boot's plain `npm ci` installs them beside the global CLI the image carries). This block is the mirror a bare checkout without config.toml reads: package and version must equal the dependencies, the lockfile, config.toml [pi], ansible group_vars and every Dockerfile ARG (tests/fences.test.ts [T12], tests/docker-daemon.test.ts). Lens sessions run through our own lens tools (src/engine/lens/), not a pi subagent extension, so no extra extension pin exists.",
     "package": "@earendil-works/pi-coding-agent",

package/prompts/onboarding.md

@@ -26,6 +26,33 @@ never as a lecture up front.
 - **On a fully-finished installation** this session doubles as a diagnostic:
   `onboard_status` re-verifies everything; report what holds and what broke.
 
+## What the person needs, and the fast path
+
+Say this near the start, in two or three short lines. They need three things:
+a **model login** (pi's `/login` opens by itself the first time — any working
+OpenAI login is fine), their **GitHub sign-in** (`gh` logged in; on a Boxes VM
+it already is), and **one repository**. Setup ends once the defaults are in
+place and verified; the TUI then opens on the board, which lists the
+repository's open pull requests — they pick one there and press `R` to review
+it.
+
+Recommend the fast path and take its defaults unless they ask otherwise:
+
+- **topology** — `onboard_topology` with `choice: "local"` (this computer);
+- **GitHub** — `onboard_github_account` with no `github_auth`: where gh is
+  signed in it uses their own account by itself. Call it once to get their
+  recent repositories, then again with `repo`;
+- **ingress** — `onboard_ingress` with no `choice`: polling is the default
+  (the reviewer checks GitHub every few minutes; webhooks can come later);
+- **the first review** — not part of setup: after `finish_and_exit` the board
+  lists the open pull requests, and `R` on one starts its review at once, no
+  label to add.
+
+**Never ask for something no tool takes.** Every question you put to the person
+is a step's input (the tool's parameters say which). If a step asks for nothing,
+do not invent a question for it — run it. When a tool returns a refusal that
+lists options, read those options out; do not add your own.
+
 ## What you teach, when
 
 - **At the start** (one short paragraph): QuickReview is a deterministic
@@ -42,33 +69,46 @@ never as a lecture up front.
   (what the reviewer learns and keeps). Explain each only when its step is in
   front of you.
 
-## The last three steps
+## GitHub, in one step
+
+`onboard_github_account` is the GitHub question. On their own account it saves
+their token (0600, never shown — say so), installs a refresh every 20 minutes,
+and creates the trigger labels if their account may. Read out its refresh line
+as it is: on a machine without `crontab` it says what lapses and gives the
+manual command. If they want a GitHub App instead, call it with
+`github_auth: "app"`; the App steps then take over. Never call the App step on
+the own-account route: it is skipped there.
+
+## The last steps
 
 - **Bring-up is slow the first time.** Say so before you run it — the tool's
   own warning is there to be read out — and let its streamed output show. A
   long build is expected, not a hang.
-- **The proof round is the point of the whole session.** Ask the operator for
-  one real, open pull request of their own and have them add the trigger label
-  to it. Then follow it. When the review comes back, show it to them and let
-  them read it: this is their first sight of what the reviewer says, and it
-  still cannot have posted anywhere.
-- **The go-live offer is theirs, and only theirs.** Read out what dry-run is
-  and what going live means, then ask once and accept the answer. Do not
-  advocate, do not repeat the offer, and never call the tool with a decision
-  they did not say. Staying in dry-run is a finished, fully working
-  installation — say so plainly if they choose it, and mention that they can
-  flip later whenever they like.
+- **The reviewer needs its own model login.** The review sessions run in the
+  daemon's container, and a login never transfers from this machine into it.
+  Once the stack is up, the LLM auth step's `daemon_login` check names the one
+  command that opens it; ask them to run it in a second terminal, sign in, and
+  tell you — then re-run the LLM auth step. Without it the first review on the
+  board would fail at once.
+- **The first review and go-live come after setup.** `onboard_proof_round` and
+  `onboard_go_live` are marked "after setup": setup finishes without them. Do
+  not run them here unless the person asks. Say plainly that the installation
+  stays in dry-run (every intended GitHub write is recorded, nothing is
+  posted), and that going live is their decision later, from the home
+  (Advanced → "Dry-run or live"), once a review has shown them what it says.
 
 ## Finishing
 
-When every step reports done, say that `finish_and_exit` will re-verify the
-whole checklist one last time and, only if all green, close this session and
-open the TUI. If it returns red checks, that is the answer: explain them, fix
+When every setup step reports done (the "after setup" ones need not be), say
+that `finish_and_exit` will re-verify the whole checklist one last time and,
+only if all green, close this session: the home then lists the repository's
+pull requests, and they select one and press `alt+r` to review it now. If it
+returns red checks, that is the answer: explain them, fix
 what can be fixed through the step tools, and try again. Never present
 onboarding as finished while anything is red, and never tell the operator to
 quit around a red check.
 
-Before `finish_and_exit`, pass on what comes next, as the go-live step's
-`next` line says it: set up the repo with `qcr setup` (or `I` on the TUI
-board). Until then the reviewer knows nothing about this codebase. It is a
+Before `finish_and_exit`, pass on what comes next: the first review is `alt+r`
+on a pull request in the home; then tune the reviewer to the repository with
+the home's "Tune to this repo" (`t` on the panel). Until then the reviewer knows nothing about this codebase. It is a
 recommendation, once — never start it from here.

package/schemas/review-result.v1.json

@@ -137,6 +137,10 @@
     "post": {
       "$ref": "#/$defs/post"
     },
+    "post_ready": {
+      "type": "string",
+      "description": "A finished PR review that was not posted: the file it is kept in, which a host that asks the person later posts through the gate exactly as `--to pr` would have."
+    },
     "run_id": {
       "type": "string",
       "description": "A detached run's id (start, status, stop)."
@@ -149,6 +153,14 @@
       "type": "string",
       "description": "What a detached run reviews."
     },
+    "started_at": {
+      "type": "number",
+      "description": "When a detached run was started, ms since the epoch."
+    },
+    "ended_at": {
+      "type": "number",
+      "description": "When a detached run ended (its exit or its stop), ms since the epoch; absent while it runs."
+    },
     "elapsed_s": {
       "type": "integer",
       "minimum": 0
@@ -165,6 +177,50 @@
           "items": {
             "type": "string"
           }
+        },
+        "live": {
+          "type": "object",
+          "description": "The running round's live log, projected: what the parent and each lens are doing now.",
+          "properties": {
+            "round": { "type": "integer", "minimum": 1 },
+            "parent_status": { "enum": ["active", "settled"] },
+            "last_activity": { "type": "string" },
+            "updated_at": { "type": "string" },
+            "active_tool": { "type": "string" },
+            "agents": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "required": ["agent", "status", "duration_ms", "tool_count"],
+                "properties": {
+                  "agent": { "type": "string" },
+                  "status": { "enum": ["running", "completed", "failed"] },
+                  "duration_ms": {
+                    "type": "number",
+                    "minimum": 0,
+                    "description": "The lens's time so far; a running lens's counts from its start between updates."
+                  },
+                  "tool_count": {
+                    "type": "number",
+                    "minimum": 0,
+                    "description": "Tool calls the lens has started; a finished lens keeps its final count."
+                  },
+                  "current_tool": {
+                    "type": "string",
+                    "description": "The running (or last) tool, as `<tool>: <args>` or the bare name."
+                  },
+                  "current_target": {
+                    "type": "string",
+                    "description": "While the lens runs: the path its current tool works on, when it names one."
+                  },
+                  "line": {
+                    "type": "string",
+                    "description": "The lens as one line a person reads: `security · read src/x.ts · 7 tools · 0:41`."
+                  }
+                }
+              }
+            }
+          }
         }
       }
     },
@@ -234,6 +290,10 @@
             "kind": {
               "enum": ["pr", "branch", "uncommitted", "diff"],
               "description": "What is reviewed: a pull request, the current branch against its base, the uncommitted working tree, or a unified diff handed in (`--diff`). Only a pr target can be posted."
+            },
+            "uncommitted": {
+              "const": true,
+              "description": "A branch target reviewed together with the working tree's uncommitted edits, as one review. Absent otherwise."
             }
           }
         },

package/scripts/deploy.sh

@@ -46,9 +46,10 @@
 #                      cloudflared when the inventory enables it), the
 #                      containers, the image stamp, the pi settings and the
 #                      reviewer stub, and the state/status.json heartbeat the
-#                      status collector reads. It also warns 14 days before the
-#                      VM's ghcr pull token expires (the expiry that
-#                      scripts/vm-ghcr-login.sh recorded).
+#                      status collector reads. It also warns 14 days before a
+#                      private mirror's ghcr pull token expires (the expiry
+#                      that scripts/vm-ghcr-login.sh recorded; the public
+#                      release images need no login, so no record).
 #
 # `sync`, `dev` and `rebuild` are gone (the on-VM rsync and build are deleted):
 # they refuse with a pointer to `release`. A pre-release fix is a release.
@@ -1083,8 +1084,9 @@ release_problem() {
   fi
 }
 
-# The VM's ghcr pull token expires (1 year, by ruling), and a lapsed one fails
-# the updater's pull. scripts/vm-ghcr-login.sh records the expiry on this
+# The release images are public and pull with no login. A private mirror's
+# ghcr pull token expires (1 year, by ruling), and a lapsed one fails the
+# updater's pull. scripts/vm-ghcr-login.sh records the expiry on this
 # controller; release and verify read it back. Within GHCR_WARN_DAYS of it
 # (or past it) the plan line starts with WARNING. Warn only, never a refusal.
 GHCR_WARN_DAYS=14
@@ -1095,7 +1097,7 @@ ghcr_expiry_status() {
   local file iso epoch now days
   file="$(qcr_ghcr_expiry_file 2>/dev/null)" || file=""
   if [[ -z "$file" || ! -s "$file" ]]; then
-    GHCR_EXPIRY_LINE="no recorded expiry for the VM's ghcr pull token (scripts/vm-ghcr-login.sh records it when the owner logs the VM in)"
+    GHCR_EXPIRY_LINE="no ghcr login recorded: the release images are public and pull without one (a private mirror logs the VM in with scripts/vm-ghcr-login.sh, which records its expiry)"
     return 0
   fi
   iso="$(head -1 "$file" | tr -d '[:space:]')"

package/scripts/mint-token.sh

@@ -1,15 +1,21 @@
 #!/usr/bin/env bash
-# mint-token.sh — GitHub App installation token for the pi sessions' `gh` prefixing.
+# mint-token.sh — the daemon's GitHub token for the pi sessions' `gh` prefixing
+# and the git credential helper.
 #
-# Shell equivalent of packages/pi-plugin/src/githubAuth.ts:
+# Under `[github] auth = "user"` (the person's own credential, polling-only;
+# SECURITY.md) it prints the token file `<secrets dir>/github_token`
+# that the host-side refresher (`qcr github-token sync`) keeps fresh, and does
+# nothing else: no App, no JWT, no cache. --refresh re-reads the same file.
+#
+# Otherwise (`auth = "app"`, the default) it is the shell equivalent of
+# packages/pi-plugin/src/githubAuth.ts:
 #   * RS256 app JWT, iat = now-60s, exp = iat+9min (≤10 min ceiling)
 #   * installation id resolved via GET /app/installations
 #   * POST /app/installations/{id}/access_tokens for the installation token
 #   * token + expires_at cached; reused while (expires_at - now) > 5 min
 #   * single-flight via an mkdir lock; --refresh re-mints (the 401 path)
 #
-# The app PEM is the only credential — there is no personal-token path here.
-# Prints the bare token to stdout. stdlib tools only: bash, openssl, curl, python3.
+# The app PEM is the App route's only credential. Prints the bare token to stdout. stdlib tools only: bash, openssl, curl, python3.
 #
 # Usage:  mint-token.sh [--refresh]
 #   e.g.  GH_TOKEN="$(scripts/mint-token.sh)" gh pr view 123
@@ -63,6 +69,21 @@ cfg_sed() { # crude fallback: first `key = "value"` inside [section]
 # ~/.config/quickreview-bot). The same answer the daemon's loader reaches.
 SECRETS_DIR="$(qcr_locate_secrets "$(cfg github secrets_dir || true)")" || exit 1
 
+# ---- auth = "user": the person's token file, as written ---------------------
+
+AUTH="$(cfg github auth 2>/dev/null || true)"
+AUTH="${AUTH:-app}"
+if [[ "$AUTH" == "user" ]]; then
+  TOKEN_FILE="$SECRETS_DIR/github_token"
+  [[ -r "$TOKEN_FILE" ]] ||
+    die "unreadable user token: $TOKEN_FILE ([github] auth = \"user\"; run \`qcr github-token sync\` on the host)"
+  token="$(tr -d '[:space:]' < "$TOKEN_FILE")"
+  [[ -n "$token" ]] || die "empty user token file: $TOKEN_FILE (run \`qcr github-token sync\` on the host)"
+  printf '%s\n' "$token"
+  exit 0
+fi
+[[ "$AUTH" == "app" ]] || die "[github] auth must be \"app\" or \"user\" (got \"$AUTH\")"
+
 APP_ID_FILE="$SECRETS_DIR/app_id"
 PEM_FILE="$SECRETS_DIR/app.pem"
 [[ -r "$APP_ID_FILE" ]] || die "unreadable app id: $APP_ID_FILE"

package/scripts/qcr-host.sh

@@ -12,7 +12,10 @@
 #                        `stop` find it by label. `stop` sends `docker stop -t
 #                        <grace>`, then `docker kill`: the container is the
 #                        hard-kill backstop for a driver whose loop is frozen.
-#   qcr                  a bare qcr opens the operator TUI (tui mode)
+#   qcr                  a bare qcr (or `qcr home`) opens the home: the image's
+#                        pi with the plugin and its panel (home mode)
+#   qcr tui              the operator TUI (tui mode), the one verb that starts
+#                        the companion
 #   qcr login [provider] pi's own /login, stored in the qcr-login volume
 #   qcr update [version] pull a newer image and repin this file
 #
@@ -21,8 +24,8 @@
 #   a worktree's common git dir              at its own path     read-only
 #   the qcr-state volume                     /opt/qcr/state      read-write
 #   the qcr-login volume                     /qcr-login          read-only
-#                                            (only `login` mounts it read-write,
-#                                            at pi's agent dir; its files are in
+#                                            (only `login` and the home mount it
+#                                            read-write, at pi's agent dir; its files are in
 #                                            group 4747, which every call joins,
 #                                            so a uid change never loses the login)
 #   ~/.config/qcr/profiles                   /qcr-config/profiles read-only
@@ -219,11 +222,20 @@ split=1
 drop=0
 gh=1
 case "$verb" in
+  # The home is the person's own pi, as `qcr` from npm opens it: pi's agent
+  # dir on the login volume, read-write (its device login lands there), its
+  # config and sessions on the state volume, and the GitHub token for its `gh`.
   '')
-    mode=tui
+    mode=home
     tty=1
     split=0
     ;;
+  home)
+    mode=home
+    tty=1
+    split=0
+    drop=1
+    ;;
   tui)
     mode=tui
     tty=1
@@ -555,7 +567,8 @@ fi
 # ---- the GitHub token (GITHUB_TOKEN, GH_TOKEN, gh; no App on a laptop) -----
 
 # The claim call only reads git: it needs no token, and a token file is read once.
-if [ "$split" = 1 ] && [ "$gh" = 1 ] && [ "$phase" != claim ]; then
+# The home is handed it too: its `gh` lists and opens the pull requests.
+if { [ "$split" = 1 ] || [ "$mode" = home ]; } && [ "$gh" = 1 ] && [ "$phase" != claim ]; then
   token="${GITHUB_TOKEN:-}"
   [ -n "$token" ] || token="${GH_TOKEN:-}"
   if [ -z "$token" ] && command -v gh >/dev/null 2>&1; then
@@ -603,6 +616,16 @@ if [ "$mode" = login ]; then
   # pi's own /login, written to the login volume: the only read-write mount of
   # it. A login needs no repo, no state and no profiles.
   set -- "$@" --mount "type=volume,src=qcr-login,dst=/home/qcr/.pi/agent"
+elif [ "$mode" = home ]; then
+  # The home works on a GitHub repository, not on the directory you stand in:
+  # no repo mount. pi's agent dir is the login volume, read-write, as login's
+  # is. Its state home, sessions and config.toml (the repository it picks,
+  # which it writes) live on the state volume, so they persist and stay
+  # writable; the install home is never mounted.
+  set -- "$@" --mount "type=volume,src=qcr-login,dst=/home/qcr/.pi/agent"
+  set -- "$@" --mount "type=volume,src=qcr-state,dst=/opt/qcr/state"
+  set -- "$@" -e QCR_STATE_HOME=/opt/qcr/state/home
+  set -- "$@" -e QCR_CONFIG=/opt/qcr/state/home/config.toml
 else
   # The repo, read-only; a worktree's common git dir at its own path.
   set -- "$@" --mount "type=bind,src=$root,dst=/repo,readonly" -w "/repo$rel"

package/scripts/vm-ghcr-login.sh

@@ -1,7 +1,10 @@
 #!/usr/bin/env bash
-# vm-ghcr-login.sh — log the review VM in to ghcr.io, so it can pull the
-# release images. Run by the owner, on the controller. Idempotent: running it
-# again replaces the login and the recorded expiry.
+# vm-ghcr-login.sh — log the review VM in to ghcr.io, so it can pull images
+# that are not public: a private mirror named by QC_RELEASE_IMAGE and
+# QC_RELEASE_MEMORY_IMAGE. The release images are public and pull with no
+# login, so a VM on them needs none of this. Run by the owner, on the
+# controller. Idempotent: running it again replaces the login and the recorded
+# expiry.
 #
 # The credential is a CLASSIC personal access token, scoped read:packages and
 # nothing else (the one carve-out from the App-only credential rule, for the
@@ -26,7 +29,7 @@
 #   scripts/vm-ghcr-login.sh --version X.Y.Z [--vm HOST] [--login USER] [--token-file FILE]
 #   pbpaste | scripts/vm-ghcr-login.sh --version X.Y.Z      # token on stdin
 #
-#   --version      a published release version; both images must exist at it
+#   --version      a published version; both images must exist at it
 #   --vm           ssh target (default: $QC_VM_HOST, else the inventory's first host)
 #   --login        the GitHub login to store (default: the token's own; if given
 #                  it must be the token's)

package/src/archive/restore.ts

@@ -32,13 +32,7 @@ import { readdir } from "node:fs/promises";
 import { join, relative } from "node:path";
 import type { StateStore } from "../state.js";
 import { yieldToLoop } from "@quickchatai/pi-quickreview/src/yieldloop.js";
-import {
-  archiveStamp,
-  bundlePassOf,
-  freshPassId,
-  identityFields,
-  sameRecorded,
-} from "./archivewrite.js";
+import { archiveStamp, bundlePassOf, freshPassId, identityFields } from "./archivewrite.js";
 import { readBundleRecords } from "./bundle.js";
 import { sameIdentity } from "./fsutil.js";
 import {
@@ -182,20 +176,23 @@ export async function restorePr(
         const steady = sameIdentity(live, after);
         if (steady && d.bytes === r.bytes && d.sha256 === r.sha256) {
           out.present += 1;
-          // Its identity is recorded unless it is the one the archive record
-          // already holds (a source that was never unlinked). A file an
-          // earlier restore pass put back — one that died before its entry
-          // was written — has a NEW inode: unrecorded, a re-archive after a
-          // re-close would not know it and would compress the same bytes
-          // again under `.v2`, instead of reusing the archived copy.
-          if (!sameRecorded(r, live))
-            restored.push({
-              source: r.source,
-              archive: r.archive,
-              sha256: r.sha256,
-              ...identityFields(live),
-              present: true,
-            });
+          // Its identity is recorded, always. A file an earlier restore pass
+          // put back — one that died before its entry was written — is
+          // unknown to the manifest otherwise, and a re-archive after a
+          // re-close would compress the same bytes again under `.v2` instead
+          // of reusing the archived copy. Its identity is no sign of whether
+          // it was ever unlinked: the filesystem hands a freed inode number
+          // back, and the restore gave the file its original size and mtime,
+          // so a file put back can carry exactly the identity the archive
+          // record holds. Recording a source that was never unlinked costs
+          // one `reused` entry at the re-archive, nothing more.
+          restored.push({
+            source: r.source,
+            archive: r.archive,
+            sha256: r.sha256,
+            ...identityFields(live),
+            present: true,
+          });
         } else out.liveDiffers.push(r.source);
         continue;
       }

package/src/botworker.ts

@@ -439,7 +439,14 @@ export async function runBotWorker(args: WorkerArgs, deps: WorkerDeps): Promise<
     // The login: borrowed, blanked, and checked against this worker's own cap.
     let auth: EngineAuth;
     try {
-      auth = engineCredentials({ srcDir: spec.agent_dir, needMs: spec.wall_clock_ms, now });
+      auth = engineCredentials({
+        srcDir: spec.login_dir ?? spec.agent_dir,
+        needMs: spec.wall_clock_ms,
+        now,
+        // a shared pi home holds the person's other logins too: only the
+        // review's providers are admitted
+        ...(spec.providers !== undefined ? { providers: spec.providers } : {}),
+      });
     } catch (e) {
       if (e instanceof AuthError) throw new Stop(EXIT.auth, e.message);
       throw e;
@@ -461,7 +468,11 @@ export async function runBotWorker(args: WorkerArgs, deps: WorkerDeps): Promise<
         ownsProcess: true,
         homeDir: homedir(),
         ...(ids !== null && !("refused" in ids) ? { toolUid: ids } : {}),
-        fenceDirs: [...loginSourceDirs(env), ...credentialPaths(env, spec.env)],
+        fenceDirs: [
+          ...loginSourceDirs(env),
+          ...(spec.login_dir ? [spec.login_dir] : []),
+          ...credentialPaths(env, spec.env),
+        ],
         credentials: auth.credentials,
         settings: agentDirSettings(spec.agent_dir),
       });

package/src/channelfs.ts

@@ -1,26 +1,3 @@
-// The file I/O of the scan's TUI↔companion records and channel files (the
-// run record, the findings store, the stop and stage-2 start requests and
-// their answers). A dependency-free leaf, so the two setup leaves the TUI
-// imports (scanreport.ts, stage2request.ts) share it without reaching each
-// other at runtime.
-import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
-import { dirname } from "node:path";
-
-/** A file's text, or null when it is ABSENT — any other failure throws, so a
- * reader can tell "not written yet" from "cannot be read". */
-export function readTextIfPresent(path: string): string | null {
-  try {
-    return readFileSync(path, "utf8");
-  } catch (err) {
-    if ((err as NodeJS.ErrnoException).code === "ENOENT") return null;
-    throw err;
-  }
-}
-
-/** tmp+rename: a reader never sees a half-written file. */
-export function writeAtomic(path: string, text: string): void {
-  mkdirSync(dirname(path), { recursive: true });
-  const tmp = `${path}.${process.pid}.tmp`;
-  writeFileSync(tmp, text);
-  renameSync(tmp, path);
-}
+// Moved to the plugin (packages/pi-plugin/src/scan/channelfs.ts): this name
+// stays for the app's importers.
+export * from "@quickchatai/pi-quickreview/src/scan/channelfs.js";

package/src/ciretry.ts

@@ -4,6 +4,7 @@
 // is re-queued when its CI turns green, so its session can decide again.
 //
 // Nothing here triggers, re-runs or cancels CI: the one CI call is a GET.
+import { botAccountLogin } from "@quickchatai/pi-quickreview/src/identity.js";
 import {
   classifyCi,
   type CheckSummary,
@@ -125,7 +126,7 @@ export async function retryWithheldApproval(
     { type: "trigger", source: "reconcile" },
     {},
     {
-      botLogin: cfg.github.bot_login,
+      botLogin: botAccountLogin(cfg.github),
       ...(deps.now ? { now: deps.now } : {}),
       reason: "ci-green:withheld-approval-retry",
     },