@quickchatai/quickreview 1.2.0 → 1.3.2

package/src/onboard/steps/loginshare.ts

@@ -0,0 +1,258 @@
+// Switch-on's login step: one OpenAI login per box. The daemon's
+// container reviews on the login the home signed in to, the host pi home's
+// auth.json, instead of a login of its own.
+//
+//   .env      QCR_PI_LOGIN_DIR = the home's pi agent dir. docker-compose.yml
+//             mounts it at /opt/qcr/login and names it to the daemon
+//             (QCR_LOGIN_DIR), so the refresher keeps that one file and every
+//             worker borrows it; pi's settings stay in the container's own
+//             pi home, never the person's.
+//   config    [login_refresh] enabled = true, so the daemon runs its single
+//             refresher on that file while auto-review runs. The config must
+//             still load with it (its margin outlasts the longest worker
+//             cap), or nothing is written.
+//   restart   a stack brought up before is recreated, so the daemon has the
+//             mount and reads the config at boot (its volumes, so its data,
+//             are kept). A first switch-on's bring-up starts it this way.
+//   proof     a stack brought up before keeps its image pin and its extracted
+//             docker-compose.yml, which may be an older release's. So the
+//             compose file must define the mount before anything is written,
+//             and the running daemon must show it reviews on the login (its
+//             QCR_LOGIN_DIR, the login in the mount, an image whose
+//             refresher reads that dir) before the step says so. Until then
+//             the step is not done, and the next switch-on runs it again.
+//
+// The hand-over needs nothing more: while the refresher runs it refreshes far
+// ahead of pi's own window, so the home's pi, a borrower now, never has a
+// token to refresh; switching auto-review off stops the daemon, the refresher
+// with it, and the home's pi refreshes on its own again (src/home/loginowner.ts).
+// The single-instance lock lives beside the shared auth.json, so a second
+// refresher on this box is refused whoever starts it.
+//
+// A remote server (the advanced route) never gets this step: it signs in on
+// its own device login, and the host's login is never copied there.
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parse } from "smol-toml";
+import { parseConfig } from "../../config.js";
+import type {
+  CheckResult,
+  OnboardingStep,
+  ProcessRunner,
+  StepContext,
+  StepReport,
+} from "../engine.js";
+import { CONTAINER_LOGIN_DIR, LOGIN_DIR_ENV } from "../../loginrefresh/supervisor.js";
+import { BROUGHT_UP_CHOICE_KEY } from "./bringup.js";
+import {
+  DAEMON_SERVICE,
+  composeArgs,
+  daemonExec,
+  readEnvText,
+  releaseVersion,
+  rootOf,
+  writeAtomic,
+} from "./compose.js";
+import { assertNoDryRunEdit, patchToml, type TomlEdit } from "./configfill.js";
+import { readEnvKey, setEnvKey } from "./ingress.js";
+import { topologyOf } from "./topology.js";
+
+export const LOGIN_SHARE_STEP_ID = "login_share";
+/** The project .env key docker-compose.yml mounts the host's login from. */
+export const PI_LOGIN_DIR_ENV = "QCR_PI_LOGIN_DIR";
+
+export interface LoginShareOptions {
+  /** The home's pi agent dir, where its login is. Absent: nothing is shared
+   * and the daemon keeps a login of its own. */
+  loginDir?: string;
+}
+
+const firstLine = (s: string): string => s.trim().split("\n")[0]?.trim() || "no output";
+const message = (err: unknown): string => (err instanceof Error ? err.message : String(err));
+
+/** Does the config run the refresher? null when it cannot be read. */
+export function refresherEnabled(configText: string): boolean | null {
+  try {
+    const t = (parse(configText) as Record<string, unknown>)["login_refresh"];
+    return (
+      typeof t === "object" && t !== null && (t as Record<string, unknown>)["enabled"] === true
+    );
+  } catch {
+    return null;
+  }
+}
+
+/** The config with the refresher on; null when it is on already. */
+export function refresherPatch(configText: string): string | null {
+  if (refresherEnabled(configText) === true) return null;
+  const edits: TomlEdit[] = [{ section: "login_refresh", key: "enabled", value: "true" }];
+  assertNoDryRunEdit(edits);
+  return patchToml(configText, edits);
+}
+
+const fail = (name: string, detail: string): StepReport => ({
+  ok: false,
+  checks: [{ name, ok: false, detail }],
+});
+
+/** The upgrade a stack too old for a shared login needs, said once. */
+function upgradeFix(root: string): string {
+  const version = releaseVersion(root);
+  return (
+    `Fix: update the stack in ${root} to a release with the shared login` +
+    `${version ? ` (QCR_VERSION=${version} in its .env, and that release's docker-compose.yml)` : ""}, ` +
+    "then switch auto-review on again"
+  );
+}
+
+/** Does the project's docker-compose.yml mount a shared login? null when
+ * there is no compose file yet (the bring-up places it, this release's). */
+export function composeMountsLogin(root: string): boolean | null {
+  let text: string;
+  try {
+    text = readFileSync(join(root, "docker-compose.yml"), "utf8");
+  } catch {
+    return null;
+  }
+  return text.includes(PI_LOGIN_DIR_ENV);
+}
+
+/** The running daemon, asked whether it reviews on the shared login: the
+ * compose definition hands it the dir, the mount holds the login, and its
+ * image's refresher reads that dir. Exit codes name which failed. */
+export const DAEMON_LOGIN_PROBE = [
+  "sh",
+  "-c",
+  `test "$${LOGIN_DIR_ENV}" = ${CONTAINER_LOGIN_DIR} || exit 3; ` +
+    `test -s ${CONTAINER_LOGIN_DIR}/auth.json || exit 4; ` +
+    `grep -q ${LOGIN_DIR_ENV} dist/src/loginrefresh/supervisor.js 2>/dev/null || exit 5`,
+] as const;
+
+/** Ask the running daemon (DAEMON_LOGIN_PROBE). A daemon that cannot be
+ * asked is not one that reviews on the login: never claimed. */
+export async function daemonLoginCheck(runner: ProcessRunner, root: string): Promise<CheckResult> {
+  const r = await daemonExec(runner, root, DAEMON_LOGIN_PROBE);
+  if (r.code === 0)
+    return { name: "daemon", ok: true, detail: "the daemon reviews on your login, data kept" };
+  const why =
+    r.code === 3
+      ? `the running daemon is not handed the login (its ${LOGIN_DIR_ENV} is not ${CONTAINER_LOGIN_DIR}): the stack's docker-compose.yml is an older release's`
+      : r.code === 4
+        ? `the running daemon sees no login at ${CONTAINER_LOGIN_DIR}: the stack's docker-compose.yml does not mount it`
+        : r.code === 5
+          ? "the running daemon's image predates the shared login: it would keep reviewing on a login of its own"
+          : `can't ask the running daemon whether it reviews on your login: ${firstLine(r.stderr || r.stdout)}`;
+  return { name: "daemon", ok: false, detail: `${why}. ${upgradeFix(root)}` };
+}
+
+export function loginShareStep(o: LoginShareOptions = {}): OnboardingStep {
+  const state = async (ctx: StepContext): Promise<StepReport> => {
+    if (o.loginDir === undefined)
+      return {
+        ok: true,
+        checks: [{ name: "login", ok: true, detail: "no home login to share here" }],
+      };
+    const env = readEnvKey(readEnvText(rootOf(ctx.adapters)), PI_LOGIN_DIR_ENV);
+    let config: string;
+    try {
+      config = readFileSync(ctx.adapters.paths.configPath, "utf8");
+    } catch (err) {
+      return fail("login", `can't read ${ctx.adapters.paths.configPath}: ${message(err)}`);
+    }
+    const checks: CheckResult[] = [
+      env === o.loginDir
+        ? { name: "login", ok: true, detail: `auto-review reviews on your login in ${o.loginDir}` }
+        : {
+            name: "login",
+            ok: false,
+            detail: `the stack does not mount your login (${PI_LOGIN_DIR_ENV} is ${env === null ? "unset" : JSON.stringify(env)})`,
+          },
+      refresherEnabled(config) === true
+        ? { name: "refresher", ok: true, detail: "its refresher keeps the login fresh" }
+        : { name: "refresher", ok: false, detail: "[login_refresh] is not enabled" },
+    ];
+    return { ok: checks.every((c) => c.ok), checks };
+  };
+
+  return {
+    id: LOGIN_SHARE_STEP_ID,
+    title: "Share your login with auto-review",
+    explain:
+      "Auto-review reviews on the OpenAI login this home signed in to: one login per machine, which its refresher keeps fresh while it runs.",
+    // after the config steps (memory is 60), before the daemon starts (69)
+    order: 66,
+    enabled: (choices) => topologyOf(choices) === "local",
+    async run(ctx): Promise<StepReport> {
+      const dir = o.loginDir;
+      if (dir === undefined) return state(ctx);
+      const auth = join(dir, "auth.json");
+      if (!existsSync(auth))
+        return fail(
+          "login",
+          `there is no login at ${auth} yet: sign in in the home first, then switch auto-review on again`,
+        );
+      // compose expands `$` in an .env value and treats ` #` as a comment
+      if (/[$\n]|\s#/.test(dir))
+        return fail(
+          "login",
+          `${dir} can't be passed to Docker Compose through .env (a \`$\`, a newline or a space before #): set PI_CODING_AGENT_DIR to a plainer path`,
+        );
+      const configPath = ctx.adapters.paths.configPath;
+      let config: string;
+      try {
+        config = readFileSync(configPath, "utf8");
+      } catch (err) {
+        return fail("refresher", `can't read ${configPath}: ${message(err)}`);
+      }
+      const patched = refresherPatch(config);
+      if (patched !== null) {
+        try {
+          parseConfig(patched);
+        } catch (err) {
+          return fail(
+            "refresher",
+            `[login_refresh] enabled = true would not load in ${configPath}: ${message(err)} — nothing was written`,
+          );
+        }
+      }
+      const root = rootOf(ctx.adapters);
+      if (composeMountsLogin(root) === false)
+        return fail(
+          "daemon",
+          `${join(root, "docker-compose.yml")} is an older release's: it does not mount a shared login, so the daemon would keep a login of its own. Nothing was written. ${upgradeFix(root)}`,
+        );
+      const envText = readEnvText(root);
+      const nextEnv = setEnvKey(envText, PI_LOGIN_DIR_ENV, dir);
+      if (patched !== null) writeAtomic(configPath, patched);
+      if (nextEnv !== envText) writeAtomic(join(root, ".env"), nextEnv);
+      const checks: CheckResult[] = [
+        {
+          name: "login",
+          ok: true,
+          detail: `auto-review reviews on your login in ${dir}, and its refresher keeps it fresh while it runs`,
+        },
+      ];
+      const changed = patched !== null || nextEnv !== envText;
+      if (typeof ctx.choices[BROUGHT_UP_CHOICE_KEY] === "string") {
+        if (changed) {
+          // the mount and the config are read when the container starts
+          const r = await ctx.adapters.runner.run(
+            "docker",
+            composeArgs(root, ["up", "-d", "--no-deps", "--force-recreate", DAEMON_SERVICE]),
+          );
+          if (r.code !== 0)
+            return fail(
+              "daemon",
+              `\`docker compose up -d --force-recreate ${DAEMON_SERVICE}\` exited ${r.code}: ${firstLine(r.stderr || r.stdout)}`,
+            );
+        }
+        // a stack brought up before says so itself, or the step is not done
+        const daemon = await daemonLoginCheck(ctx.adapters.runner, root);
+        checks.push(daemon);
+        if (!daemon.ok) return { ok: false, checks };
+      }
+      return { ok: true, checks };
+    },
+    verify: state,
+  };
+}

package/src/onboard/steps/memory.ts

@@ -77,7 +77,7 @@ import { dirname, join, resolve, sep } from "node:path";
 import { pathToFileURL } from "node:url";
 import { OPENVIKING_DEFAULTS, parseConfig } from "../../config.js";
 import { configHome, locateKeysFile, locateSecrets } from "../../install.js";
-import { tuiMemoryBaseUrl } from "../../tui/memory.js";
+import { tuiMemoryBaseUrl } from "../../tui/memoryurl.js";
 import { shellQuote } from "../../tui/remote.js";
 import { CHOICE_KEYS, MEMORY_CHOICE_IDS, type MemoryChoice } from "../choices.js";
 import { deliverConfigChange } from "./configdelivery.js";
@@ -481,6 +481,22 @@ export const DECLINED_CHECKS: readonly CheckResult[] = [
 /** The check row that reports the daemon's on/off switch. */
 export const MEMORY_SWITCH_CHECK = "memory-switch";
 
+/** The check row that says phase B waits on a server not answering yet. */
+export const MEMORY_SERVER_CHECK = "memory-server";
+
+/** A run that landed phase A (the root key) and stopped only because the
+ * server is not up yet: on a stack not running memory, the bring-up starts
+ * it and the memory_user_keys step finishes phase B. Any other failure is a
+ * failure. */
+export function waitsOnServer(checks: readonly CheckResult[]): boolean {
+  const failed = checks.filter((c) => !c.ok);
+  return (
+    failed.length > 0 &&
+    failed.every((c) => c.name === MEMORY_SERVER_CHECK) &&
+    checks.some((c) => c.name === "root-key" && c.ok)
+  );
+}
+
 /**
  * Tell the DAEMON the operator's answer: `[openviking] enabled =
  * false` on a decline — its word for "off", under which memory health reports
@@ -1009,7 +1025,7 @@ export function memoryStep(opts: MemoryStepOptions = {}): OnboardingStep {
         const ready = await serverReady(ctx.adapters.fetch, base, prov);
         if (!ready.ok) {
           checks.push({
-            name: "memory-server",
+            name: MEMORY_SERVER_CHECK,
             ok: false,
             detail: ready.answering
               ? `OpenViking answers at ${base} but is not ready (${ready.detail}). Check the engine and embedder logs, then run this step again; the memory forward already reaches it.`

package/src/onboard/steps/repoconfig.ts

@@ -0,0 +1,85 @@
+// The repository the home's setup checklist picks, written into config.toml:
+// the config fill's writer (configfill.ts) over the template or the
+// install's config, never touching dry_run.
+import { parse } from "smol-toml";
+import { assertNoDryRunEdit, changedEdits, patchToml, tomlString } from "./configfill.js";
+
+const message = (err: unknown): string => (err instanceof Error ? err.message : String(err));
+
+/** The repository pick, as the config takes it. */
+export interface RepoConfigChoice {
+  repo: string;
+  baseBranch: string | null;
+  timezone: string | null;
+  ownerName: string | null;
+  ownerLogin: string | null;
+}
+
+/** A config value as text, "" when absent or not a string. */
+function valueIn(doc: Record<string, unknown> | null, section: string, key: string): string {
+  const table = doc?.[section];
+  if (typeof table !== "object" || table === null) return "";
+  const v = (table as Record<string, unknown>)[key];
+  return typeof v === "string" ? v.trim() : "";
+}
+
+/** The config text with the choice in it, from `existing` (null: none yet,
+ * so the template). What changed is named; a config that is not TOML is
+ * refused, since what it holds cannot be seen. */
+export function renderRepoConfig(
+  existing: string | null,
+  template: string,
+  choice: RepoConfigChoice,
+): { ok: true; text: string; wrote: string[] } | { ok: false; why: string } {
+  const fresh = existing === null;
+  const source = existing ?? template;
+  let doc: Record<string, unknown> | null = null;
+  try {
+    doc = parse(source);
+  } catch (err) {
+    return {
+      ok: false,
+      why: `${fresh ? "the shipped template" : "the config"} is not valid TOML (${message(err)}); nothing was written`,
+    };
+  }
+  const fill = (section: string, key: string): boolean =>
+    fresh || valueIn(doc, section, key) === "";
+  const wanted = [
+    { section: "github", key: "repo", value: tomlString(choice.repo) },
+    ...(choice.baseBranch
+      ? [{ section: "github", key: "base_branch", value: tomlString(choice.baseBranch) }]
+      : []),
+    ...(choice.timezone && fill("ops", "timezone")
+      ? [{ section: "ops", key: "timezone", value: tomlString(choice.timezone) }]
+      : []),
+    ...(choice.ownerName && fill("owner", "name")
+      ? [{ section: "owner", key: "name", value: tomlString(choice.ownerName) }]
+      : []),
+    ...(choice.ownerLogin && fill("owner", "github_login")
+      ? [{ section: "owner", key: "github_login", value: tomlString(choice.ownerLogin) }]
+      : []),
+  ];
+  assertNoDryRunEdit(wanted);
+  const edits = changedEdits(source, wanted);
+  const text = edits.length > 0 ? patchToml(source, edits) : source;
+  let after: Record<string, unknown>;
+  try {
+    after = parse(text);
+  } catch (err) {
+    return {
+      ok: false,
+      why: `the patched config would not parse (${message(err)}); nothing was written`,
+    };
+  }
+  if (valueIn(after, "github", "repo") !== choice.repo)
+    return {
+      ok: false,
+      why: "the patched config does not carry the repository; nothing was written",
+    };
+  if (fresh && after["dry_run"] !== true)
+    return {
+      ok: false,
+      why: "the shipped template no longer ships dry_run = true; nothing was written (invariant 6)",
+    };
+  return { ok: true, text, wrote: edits.map((e) => `[${e.section}] ${e.key}`) };
+}

package/src/onboard/toolnames.ts

@@ -1,6 +1,6 @@
 // The onboarding session's tool names: one source for the extension that
-// registers them (extensions/onboarding.ts) and the argv that activates them
-// (launch.ts `onboardingPiArgv`).
+// registers them (extensions/onboarding.ts) and the `--tools` allowlist that
+// activates them (`onboardingToolAllowlist`).
 //
 // pi's `--tools <list>` is an allowlist over EVERY tool, extension tools
 // included (pi 1.4.0: createAgentSession({ tools }) leaves an extension tool

package/src/piagentdir.ts

@@ -0,0 +1,12 @@
+// pi's agent dir, the way pi itself finds it: a leaf, so the npm verbs
+// (src/npmverbs.ts) and the home's login reader (src/home/adapters.ts) read
+// one rule without importing each other.
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/** pi's agent dir: `$PI_CODING_AGENT_DIR`, else `~/.pi/agent`, as pi reads it. */
+export function piAgentDir(env: Readonly<Record<string, string | undefined>>): string {
+  const set = (env["PI_CODING_AGENT_DIR"] ?? "").trim();
+  if (set !== "") return set;
+  return join((env["HOME"] ?? "").trim() || homedir(), ".pi", "agent");
+}

package/src/pilogin.ts

@@ -4,15 +4,24 @@
 // (src/scanbox.ts) share it without one reaching the other.
 
 /** pi itself, with `/login` (or `/login <provider>`) typed and sent for the
- * user: pi runs in a fresh tmux session; once its input box is drawn (two
- * editor borders on screen) the keys go in, and again every 0.3 s until pi's
- * login menu shows — an Enter sent while pi still starts is lost, and a
- * `/login` left in the editor then only needs the Enter. After 30 s the
- * terminal attaches regardless, so every login pi offers is there and
- * quitting pi ends it. `pi` is the pi to start: the companion image's CLI on
- * its PATH by default; the release image's entrypoint passes its one pi,
- * node_modules/.bin/pi (src/picli.ts `piCliIn`), and `qcr login` the pinned
- * package's own bin (src/picli.ts `piCliPath`). */
+ * user: pi runs in a fresh tmux session, and qcr reads pi's input box, the
+ * lines between the last two editor borders on screen, every 0.3 s (a second
+ * after a key, which counts as three polls toward the 30 s). Empty, it gets the keys and an Enter; still holding exactly
+ * the keys, one more Enter (an Enter sent while pi still starts is lost, and
+ * the first one may only accept the autocomplete). Anything else in the box is
+ * one of pi's menus (the provider list, a provider's own login methods), and
+ * no key goes in again. pi draws every selection in that box, so this holds
+ * whatever title pi or a provider gives the menu, where an Enter would pick
+ * its default: a browser login, opened again on every poll. pi starts with
+ * `--no-approve`: a login needs nothing from the folder qcr was run in, so a
+ * project folder neither stops it at pi's trust prompt nor gets trusted. A pi
+ * that has already exited ends the wait at once. After 30 s the terminal
+ * attaches regardless, so every login pi offers is there and quitting pi ends
+ * it; a failed attach (no terminal) ends the session instead of leaving pi
+ * running where nobody can reach it. `pi` is the pi to start: the
+ * companion image's CLI on its PATH by default; the release image's entrypoint
+ * passes its one pi, node_modules/.bin/pi (src/picli.ts `piCliIn`), and
+ * `qcr login` the pinned package's own bin (src/picli.ts `piCliPath`). */
 export function loginInPi(provider?: string, pi: string = "pi"): string[] {
   if (provider !== undefined && !/^[A-Za-z0-9._-]+$/.test(provider))
     throw new Error(
@@ -22,16 +31,23 @@ export function loginInPi(provider?: string, pi: string = "pi"): string[] {
   if (!/^[A-Za-z0-9._/@+-]+$/.test(pi))
     throw new Error(`scan login: pi ${JSON.stringify(pi)} is not a plain path`);
   const keys = provider ? `/login ${provider}` : "/login";
+  // The input box, its side padding (pi's editorPaddingX) trimmed and blank
+  // lines dropped; awk fails while fewer than two borders are drawn (pi still
+  // starting), and the loop then only waits.
+  const box =
+    `tmux capture-pane -p -t "$s" 2>/dev/null | awk '/──────────/ { b[++n] = NR } { l[NR] = $0 } ` +
+    `END { if (n < 2) exit 1; for (i = b[n - 1] + 1; i < b[n]; i++) ` +
+    `{ sub(/^ +/, "", l[i]); sub(/ +$/, "", l[i]); if (l[i] != "") print l[i] } }'`;
   return [
     "sh",
     "-c",
-    `s=qcr-login-$$; tmux new-session -d -s "$s" ${pi} || exit 1; i=0; ` +
-      `while [ $i -lt 100 ]; do p=$(tmux capture-pane -p -t "$s"); ` +
-      `case "$p" in *"Select authentication"*|*"Select provider"*) break;; esac; ` +
-      `if [ "$(printf '%s\\n' "$p" | grep -cF '──────────')" -ge 2 ]; then ` +
-      `if printf '%s\\n' "$p" | grep -qxF '${keys}'; then tmux send-keys -t "$s" Enter; ` +
-      `else tmux send-keys -t "$s" -l '${keys}'; tmux send-keys -t "$s" Enter; fi; fi; ` +
+    `s=qcr-login-$$; tmux new-session -d -s "$s" ${pi} --no-approve || exit 1; i=0; ` +
+      `while [ $i -lt 100 ]; do tmux has-session -t "$s" 2>/dev/null || break; ` +
+      `if e=$(${box}); then ` +
+      `if [ -z "$e" ]; then tmux send-keys -t "$s" -l '${keys}'; tmux send-keys -t "$s" Enter; sleep 1; i=$((i+3)); ` +
+      `elif [ "$e" = '${keys}' ]; then tmux send-keys -t "$s" Enter; sleep 1; i=$((i+3)); ` +
+      `else break; fi; fi; ` +
       `sleep 0.3; i=$((i+1)); done; ` +
-      `exec tmux attach -t "$s"`,
+      `tmux attach -t "$s" || { tmux kill-session -t "$s" 2>/dev/null; exit 1; }`,
   ];
 }

package/src/qcrbin.ts

@@ -3,11 +3,12 @@
 // verbs a person runs from an npm install are routed here first and load only
 // what they use, so they work where that native driver cannot load:
 //
-//   qcr                the admin TUI (`qcr tui`)
+//   qcr                the home: the app's own pi (src/home/launch.ts)
+//   qcr tui            the admin TUI (src/cli.ts)
 //   qcr version        the install's identity (src/version.ts)
 //   qcr review …       a daemonless review (src/reviewcli.ts)
 //   qcr login [p]      pi's own /login in the pinned pi (src/npmverbs.ts)
-//   qcr pi [args]      the pinned pi with the qcr plugin preloaded
+//   qcr pi [args]      the pinned pi with the qcr plugin and /selfimprove
 //   qcr update         the installing package manager updates qcr
 //
 // Every other verb goes to src/cli.ts `main` unchanged. The image's
@@ -22,10 +23,11 @@ import { MissingConfigError } from "./missingconfig.js";
 export const BIN_HELP = [
   "qcr — QuickReview",
   "",
-  "  qcr                     open the admin TUI",
+  "  qcr                     open the home: pi with the plugin and your pull requests",
+  "  qcr tui                 open the admin TUI",
   "  qcr review [target]     review code here, with no daemon (`qcr review --help`)",
   "  qcr login [provider]    log in with pi's own /login, for the review sessions",
-  "  qcr pi [args]           pi with the qcr plugin (/review, /scan, /selfimprove, /qcr-setup)",
+  "  qcr pi [args]           pi with the qcr plugin (/qcr-review, /qcr-scan, /qcr-setup) and /selfimprove",
   "  qcr update              update qcr with the package manager that installed it",
   "  qcr version [--json]    this install's version, schemas and pi pin",
   "",
@@ -33,19 +35,19 @@ export const BIN_HELP = [
 ].join("\n");
 
 /** The verbs that never print the update notice: the ones that hand the
- * terminal over (the TUI, pi) or are about versions themselves. */
-const QUIET_VERBS = new Set(["tui", "pi", "update", "version", "login"]);
+ * terminal over (the home, the TUI, pi) or are about versions themselves. */
+const QUIET_VERBS = new Set(["home", "tui", "pi", "update", "version", "login"]);
 
 /** What `runBin` would do with `argv`, before doing it. */
 export type BinRoute =
-  | { route: "tui" }
+  | { route: "home" }
   | { route: "help" }
   | { route: "pi"; args: string[] }
   | { route: "version" | "update" | "login" | "review"; args: string[]; json: boolean }
   | { route: "app"; argv: string[] };
 
 export function binRoute(argv: readonly string[]): BinRoute {
-  if (argv.length === 0) return { route: "tui" };
+  if (argv.length === 0 || (argv.length === 1 && argv[0] === "home")) return { route: "home" };
   // pi's arguments are pi's, `--json` included
   if (argv[0] === "pi") return { route: "pi", args: argv.slice(1) };
   // `qcr message` carries free text: src/cli.ts reads its argv as it is
@@ -115,8 +117,11 @@ async function maybeNotice(json: boolean): Promise<void> {
 
 async function route(r: BinRoute): Promise<void> {
   switch (r.route) {
-    case "tui":
-      return appMain(["tui"]);
+    case "home": {
+      const { homeRunDeps, runHome } = await import("./home/launch.js");
+      process.exitCode = runHome(homeRunDeps(await packageRoot()));
+      return;
+    }
     case "help":
       console.log(BIN_HELP);
       try {
@@ -181,6 +186,6 @@ export async function runBin(argv: readonly string[]): Promise<void> {
     return;
   }
   const verb = r.route === "app" ? r.argv.find((a) => a !== "--json") : r.route;
-  if (r.route !== "tui" && r.route !== "help" && !QUIET_VERBS.has(verb ?? ""))
+  if (r.route !== "help" && !QUIET_VERBS.has(verb ?? ""))
     await maybeNotice("json" in r ? r.json : r.route === "app" && r.argv.includes("--json"));
 }