@quickchatai/quickreview 1.2.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.2.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.2.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

@@ -94,20 +94,21 @@ the own-account route: it is skipped there.
   `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: re-run `qcr onboard`
-  and ask for it once a review on the board has shown them what it says.
+  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 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 and open the TUI on the board: there they
-select a pull request and press `R` to review it now. If it returns red checks, that is the answer: explain them, fix
+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: the first review is `R` on
-a pull request on the board; then 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/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/cli.ts

@@ -1857,55 +1857,6 @@ export async function cmdSetup(rest: string[]): Promise<number> {
   return 0;
 }
 
-/** `qcr onboard` — the guided setup wizard: pi at the pinned
- * version via npx (works from a bare clone; pi stays a non-dependency), the
- * onboarding prompt + extension + a restricted tool set, then the TUI handoff
- * when the checklist verifies complete. Resumable: run it again after a crash
- * and completed steps are re-verified, not repeated. */
-export async function cmdOnboard(): Promise<number> {
-  const { piPinFromPackageJson, onboardingSessionDir, runOnboard } =
-    await import("./onboard/launch.js");
-  const { checklistComplete } = await import("./onboard/engine.js");
-  const { spawn } = await import("node:child_process");
-  const root = sandboxRoot();
-  // Pin source: config.toml [pi] when it loads; package.json's "qcrPi" block on a
-  // bare clone (config.toml is written later, BY onboarding). Same pinned
-  // version by the rule-7 mirror discipline.
-  let pin: { package: string; version: string } | null = null;
-  try {
-    const { package: pkg, version } = loadConfig().pi;
-    pin = { package: pkg, version };
-  } catch {
-    pin = piPinFromPackageJson(root);
-  }
-  if (!pin)
-    throw new Error(
-      'onboard: pi pin not found (need config.toml [pi] or the package.json "qcrPi" block)',
-    );
-  mkdirSync(onboardingSessionDir(root), { recursive: true });
-  const run = (cmd: string, args: string[]): Promise<number> =>
-    new Promise((resolvePromise) => {
-      const child = spawn(cmd, args, {
-        stdio: "inherit",
-        cwd: root,
-        env: { ...process.env, QCR_ROOT: root },
-      });
-      child.on("error", (err) => {
-        console.error(`onboard: ${cmd} failed to start: ${err.message}`);
-        resolvePromise(1);
-      });
-      child.on("close", (code) => resolvePromise(code ?? 1));
-    });
-  return runOnboard({
-    pin,
-    root,
-    spawn: run,
-    isComplete: () => checklistComplete(join(root, "state")),
-    log: (line) => console.log(line),
-    cliPath: join(root, "dist", "src", "cli.js"),
-  });
-}
-
 export const ARCHIVE_USAGE =
   "usage: qcr archive status [--plan] [--json] | qcr archive run | qcr archive restore <pr> | " +
   "qcr archive extract <pr> --to <dir>";
@@ -2154,6 +2105,16 @@ export async function main(rawArgv: string[]): Promise<void> {
       const { runTui } = await import("./tui/index.js");
       return runTui(rest);
     }
+    case "home": {
+      // the home (src/home/launch.ts): the bin routes a bare `qcr` here too
+      // (src/qcrbin.ts); the image's home mode reaches it through this verb
+      if (rest.length > 0) throw new Error("usage: qcr home");
+      const { homeRunDeps, runHome } = await import("./home/launch.js");
+      // the token taken at startup, when the wrapper handed one over
+      const githubToken = takeHandoffToken();
+      process.exitCode = runHome({ ...homeRunDeps(sandboxRoot()), githubToken: () => githubToken });
+      return;
+    }
     case "companion":
       if (rest.length !== 1) throw new Error("usage: qcr companion <up|down|status|rebuild|plan>");
       return cmdCompanion(rest[0]);
@@ -2161,10 +2122,6 @@ export async function main(rawArgv: string[]): Promise<void> {
       process.exitCode = await cmdMemory(rest);
       return;
     }
-    case "onboard": {
-      process.exitCode = await cmdOnboard();
-      return;
-    }
     case "setup": {
       process.exitCode = await cmdSetup(rest);
       return;
@@ -2273,7 +2230,7 @@ export async function main(rawArgv: string[]): Promise<void> {
     }
     default:
       console.log(
-        "usage: qcr <version|config check [--config-home <dir>]|onboard|setup [validate [<profile>]|commit]|status|spend|today|why <n>|metrics [--pr <n>]|events|takeover <n>|debug-round <n>|release <n>|tui [pr|overseer]|drain <on [--hold]|off>|pause-pr <pr> [--reason <text>]|resume-pr <pr>|review-now <pr>|github-token sync [--gh <path>] [--secrets-dir <dir>]|message <pr> [--may-post] <text...>|archive <status [--plan]|run|restore <pr>|extract <pr> --to <dir>>|install <where|migrate>|" +
+        "usage: qcr <version|config check [--config-home <dir>]|home|setup [validate [<profile>]|commit]|status|spend|today|why <n>|metrics [--pr <n>]|events|takeover <n>|debug-round <n>|release <n>|tui [pr|overseer]|drain <on [--hold]|off>|pause-pr <pr> [--reason <text>]|resume-pr <pr>|review-now <pr>|github-token sync [--gh <path>] [--secrets-dir <dir>]|message <pr> [--may-post] <text...>|archive <status [--plan]|run|restore <pr>|extract <pr> --to <dir>>|install <where|migrate>|" +
           "companion <up|down|status|rebuild>|review [start|status|stop|branch|--uncommitted|--diff FILE|-|<PR number|URL>] [--repo OWNER/NAME] [--base REF] [--preview] [--key K] [--limit USD] [--json]|live [RUN_ID|DIR] [--lens ID] [--round N] [--follow] [--json]|open [RUN_ID|DIR|FILE.jsonl|scan[:RUN]|pr N [--round R]] [--lens ID] [--write] [--print]|scan <preview|start|status|stop|findings|matches|match|suggestions|stage2 propose|stage2 start|dismiss|units show|units propose|units adjust|units save|login|doctor|rebuild>|memory reembed [--user <name>]|memory relayout [--plan|--apply]|backfill [--dry-run] [--limit <n>]|history <digest|pull>|outcomes [--days <n>] [--capture [--read-github]]|lessons [mine|shadow-report [--days <n>]|off|on|suppress <id>|unsuppress <id>]|checklist|compare <pr...>|" +
           "regression [--set <path>] [--clone <path>] [--change <name>] [--limit <n>] [--out <path>]>",
       );