@quickchatai/quickreview 1.1.0 → 1.3.1

package/src/tui/ghread.ts

@@ -23,6 +23,14 @@
 // `companion-guard` additionally vetoes write-shaped calls against the API
 // (belt); the token's own scope is the brace.
 //
+// Under `[github] auth = "user"` (the person's own credential, SECURITY.md)
+// there is no App to mint from. The companion then gets a COPY of
+// the person's token file (`<secrets dir>/github_token`), re-copied whenever
+// the host refresher rewrites it, in the same env file and the same
+// read-only mount. That token is the person's and is NOT down-scoped: in this
+// mode `companion-guard`'s veto of write-shaped calls is the only fence, and
+// the env file's header says so.
+//
 // Everything here is total at the edge the TUI calls: `refresh()` answers an
 // outcome, never throws — a companion without GitHub is under-equipped, never
 // a companion that does not start.
@@ -160,7 +168,11 @@ const TOKEN_VALUE_RE = /^[A-Za-z0-9_.-]+$/;
 /** The env file's text. Every value is checked against a character set that
  * is inert in both a docker env file and a `source`d shell file. A token
  * outside that set is refused, and the refusal never echoes it. */
-export function renderTokenEnv(tok: ReadToken, repo: string): string {
+export function renderTokenEnv(
+  tok: ReadToken,
+  repo: string,
+  source: "app" | "user" = "app",
+): string {
   if (!TOKEN_VALUE_RE.test(tok.token))
     throw new Error(
       "the minted token has a character an env file cannot carry safely (only A-Z a-z 0-9 _ . - are allowed)",
@@ -169,11 +181,16 @@ export function renderTokenEnv(tok: ReadToken, repo: string): string {
     throw new Error("the token expiry is not a timestamp");
   if (!REPO_RE.test(repo))
     throw new Error(`[github] repo ${JSON.stringify(repo)} is not owner/name`);
+  const header =
+    source === "user"
+      ? '# Copied on the host by qcr from the person\'s own GitHub token ([github] auth = "user").\n' +
+        "# It is NOT down-scoped: it can do what that person can. The companion uses it for reads\n" +
+        "# only, and companion-guard vetoes write-shaped calls. Re-copied when the host refreshes it.\n"
+      : "# Minted on the host by qcr: a READ-ONLY GitHub App installation token\n" +
+        "# (contents / issues / pull requests: read) for one repository. Re-minted before\n" +
+        "# it expires. It cannot write to GitHub.\n";
   return (
-    "# Minted on the host by qcr: a READ-ONLY GitHub App installation token\n" +
-    "# (contents / issues / pull requests: read) for one repository. Re-minted before\n" +
-    "# it expires. It cannot write to GitHub.\n" +
-    `${TOKEN_VAR}=${tok.token}\n${EXPIRES_VAR}=${tok.expires_at}\n${REPO_VAR}=${repo}\n`
+    header + `${TOKEN_VAR}=${tok.token}\n${EXPIRES_VAR}=${tok.expires_at}\n${REPO_VAR}=${repo}\n`
   );
 }
 
@@ -227,10 +244,22 @@ export function tokenExpiry(dir: string, repo?: string): number | undefined {
   return Number.isFinite(ms) ? ms : undefined;
 }
 
+/** The token the env file holds, or undefined. */
+function heldToken(dir: string): string | undefined {
+  try {
+    const text = readFileSync(join(dir, TOKEN_FILE), "utf8");
+    return new RegExp(`^${TOKEN_VAR}=(.*)$`, "m").exec(text)?.[1]?.trim();
+  } catch {
+    return undefined;
+  }
+}
+
 export type TokenOutcome =
   /** The file holds a token with more than the margin left: nothing minted. */
   | { kind: "fresh"; expiresAt: string }
   | { kind: "minted"; expiresAt: string }
+  /** `auth = "user"`: the person's token file was copied in (it changed). */
+  | { kind: "copied"; expiresAt: string }
   /** No App credential on this host: the companion simply has no GitHub. */
   | { kind: "unavailable"; reason: string }
   | { kind: "failed"; reason: string };
@@ -242,6 +271,8 @@ export function tokenOutcomeLine(o: TokenOutcome): string {
       return `read-only GitHub token valid until ${o.expiresAt}`;
     case "minted":
       return `read-only GitHub token minted (valid until ${o.expiresAt})`;
+    case "copied":
+      return "GitHub token copied from the person's own token file (auth = user; used read-only)";
     case "unavailable":
       return `no read-only GitHub token — ${o.reason}`;
     case "failed":
@@ -254,9 +285,12 @@ export interface CompanionGithubTokenOptions {
   dir: string;
   /** `[github] repo`, owner/name. */
   repo: string;
-  /** The resolved App secrets dir (`app_id`, `app.pem`). Read here, on the
-   * host; nothing from it is ever written into `dir`. */
+  /** The resolved secrets dir (`app_id`, `app.pem`; or `github_token` under
+   * `auth = "user"`). Read here, on the host; under "app" nothing from it is
+   * ever written into `dir`. */
   secretsDir: string;
+  /** `[github] auth`. Absent ⇒ "app". */
+  auth?: "app" | "user";
   fetchFn?: FetchFn;
   apiBase?: string;
   now?: () => number;
@@ -276,6 +310,7 @@ export class CompanionGithubToken {
   }
 
   private async doRefresh(): Promise<TokenOutcome> {
+    if (this.opts.auth === "user") return this.copyUserToken();
     const now = (this.opts.now ?? Date.now)();
     const current = tokenExpiry(this.opts.dir, this.opts.repo);
     if (current !== undefined && current - now > REFRESH_MARGIN_MS)
@@ -307,6 +342,38 @@ export class CompanionGithubToken {
     }
   }
 
+  /** `auth = "user"`: copy the person's token file in when it differs from
+   * what the env file holds (or the repo changed). The expiry the file
+   * carries is a re-check time, not GitHub's: a user token's own expiry is
+   * not known here. */
+  private copyUserToken(): TokenOutcome {
+    const source = join(this.opts.secretsDir, "github_token");
+    let token: string;
+    try {
+      token = readFileSync(source, "utf8").trim();
+    } catch {
+      return {
+        kind: "unavailable",
+        reason: `no user token at ${source} (run \`qcr github-token sync\` on the host)`,
+      };
+    }
+    if (token === "")
+      return { kind: "unavailable", reason: `the user token file ${source} is empty` };
+    const expiresAt = new Date((this.opts.now ?? Date.now)() + REFRESH_MARGIN_MS * 2).toISOString();
+    const heldUntil = tokenExpiry(this.opts.dir, this.opts.repo);
+    if (heldUntil !== undefined && heldToken(this.opts.dir) === token)
+      return { kind: "fresh", expiresAt: new Date(heldUntil).toISOString() };
+    try {
+      writeTokenEnv(
+        this.opts.dir,
+        renderTokenEnv({ token, expires_at: expiresAt, permissions: {} }, this.opts.repo, "user"),
+      );
+      return { kind: "copied", expiresAt };
+    } catch (err) {
+      return { kind: "failed", reason: err instanceof Error ? err.message : String(err) };
+    }
+  }
+
   /** Check every `everyMs`; each outcome goes to `onOutcome`. Idempotent. */
   start(onOutcome: (o: TokenOutcome) => void, everyMs: number = CHECK_EVERY_MS): void {
     if (this.timer) return;

package/src/tui/index.ts

@@ -34,7 +34,10 @@ import {
   RELOAD_EXIT_CODE,
   resumeStatePath,
 } from "./reload.js";
-import { killInFlightSsh, runnerFor, transportOf } from "./remote.js";
+import { NO_SSH_HOST_STDERR, killInFlightSsh, runnerFor, transportOf } from "./remote.js";
+import { diagnoseLocalMemory } from "./memforward.js";
+import { realProbeRunner } from "./sshtriage.js";
+import { setupLine } from "./setupstate.js";
 import { chainOnPoll } from "./poll-hooks.js";
 import { deliverMessage } from "./msg.js";
 import type { ConnectionDiagnosis } from "./sshtriage.js";
@@ -60,7 +63,7 @@ export function parseTarget(
   return { kind: "bad", reason: `unknown target '${arg}' — expected a PR number` };
 }
 
-export const TUI_HELP = `qcr tui — live board and operator console for the review daemon (over ssh)
+export const TUI_HELP = `qcr tui — live board and operator console for the review daemon (over ssh, or local docker)
 
 usage: qcr tui [<pr>] [--no-companion] [--no-reload]
 
@@ -95,7 +98,8 @@ keys: 1…8 the eight surfaces — board · memory · digest · tickets · deplo
       board: j/k select · ⏎ focus the PR's pi pane · m quick-message ·
       g github · u unwedge · e events overlay · I set up the repo ·
       Ctrl-q release focus · Ctrl-c ×3 hard-kill the TUI ·
-      s reconnect ssh (GCP passphrase, once) · r refresh ·
+      s re-check the connection (VM: ssh, the one passphrase prompt;
+      local: the daemon container) · r refresh ·
       ? full key map · q quit
 
 troubleshooting:
@@ -106,6 +110,12 @@ troubleshooting:
                      not answering. Nothing is run for you; s re-checks and
                      reports, and offers the one GCP passphrase prompt when a
                      key is what is missing
+  local route        [tui] target = "local" (or an empty ssh_host on a compose
+                     project): every read is docker exec into the daemon
+                     container, no ssh. The board names an absent or stopped
+                     container with the docker compose command that starts it
+  setup not finished the setup checklist is not complete: run qcr (the board
+                     names the next step)
   ▲ DATA STALE       ssh works but status.json stopped updating — the
                      container is down or the daemon hung (qcr-side:
                      ssh <host> sudo docker ps / docker logs)
@@ -355,6 +365,8 @@ export interface RunTuiDeps {
   input?: NodeJS.ReadStream;
   config?: Config;
   exit?: (code: number) => void;
+  /** The route facts (src/tui/route.ts); default: read from this checkout. */
+  routeFacts?: import("./route.js").RouteFacts;
 }
 
 /** First slice of the quit-time wait for an in-flight bring-up. */
@@ -440,7 +452,18 @@ export async function runTui(argv: string | string[] = [], deps: RunTuiDeps = {}
 
   // ---- phase 0: local only, ending in the first frame -----------------------
 
-  const loaded = deps.config ?? loadConfig();
+  const fileConfig = deps.config ?? loadConfig();
+  // The route — which daemon the board reads, and how — from [tui] plus the
+  // facts the stack holds locally (the compose project's .env, the
+  // onboarding checklist, the Docker socket's mode). The stack is the one the
+  // home sets up (src/homes.ts `stackRoot`), so an app installed by a package
+  // manager reads it from its state home. Two small file reads and one
+  // access(2): no docker, network or walk, so it may precede the frame.
+  const { readRouteFacts, resolveTuiRoute, pinnedVersion } = await import("./route.js");
+  const { stackRoot } = await import("../homes.js");
+  const routeFacts = deps.routeFacts ?? readRouteFacts(stackRoot(process.env, sandboxRoot()));
+  const route = resolveTuiRoute(fileConfig.tui, routeFacts);
+  const loaded: Config = { ...fileConfig, tui: route.cfg };
   // In the containerised TUI the companion is a container the host wrapper
   // runs, reached through a shared tmux socket. Its channel dirs are the
   // host's, named by the wrapper in env; nothing here can run docker.
@@ -454,6 +477,11 @@ export async function runTui(argv: string | string[] = [], deps: RunTuiDeps = {}
   const runner = runnerFor(cfg);
 
   const app = new App(cfg, runner, out, input);
+  // A half-finished onboarding is stated on the first frame: the checklist is
+  // the file read above, and the step titles are the wizard's own registry.
+  const { setupStateOf } = await import("./setupstate.js");
+  app.view.setup = await setupStateOf(routeFacts.checklist);
+  for (const line of route.notes) app.notice(line);
 
   // The terminal must come back whatever kills us — raw mode + alt screen
   // surviving a crash is exactly the "only closing the terminal works" trap.
@@ -560,6 +588,17 @@ export async function runTui(argv: string | string[] = [], deps: RunTuiDeps = {}
   // (nativecompanion.ts). The containerised TUI keeps its wrapper-run
   // container: it has no Docker of its own to ask.
   const containerLifecycle = new CompanionLifecycle(full.companion, realDockerRunner);
+  // On a compose box the release image is already pulled (QCR_VERSION in the
+  // project .env): a first start uses it rather than building one from this
+  // checkout. An explicit [companion] image, or a local build already
+  // present, still wins (CompanionLifecycle.ensureUp).
+  {
+    const version = pinnedVersion(routeFacts.projectEnv);
+    if (version !== "") {
+      const { releaseImage } = await import("../onboard/steps/compose.js");
+      containerLifecycle.preferredImage = releaseImage(version);
+    }
+  }
   const selecting = socketMode
     ? undefined
     : new SelectingCompanion(containerLifecycle, realDockerRunner, {
@@ -593,6 +632,7 @@ export async function runTui(argv: string | string[] = [], deps: RunTuiDeps = {}
     dir: companionGithubDir(socketMode ? laptopInstallEnv(process.env) : undefined),
     repo: full.github.repo,
     secretsDir: full.github.secrets_dir,
+    auth: full.github.auth ?? "app",
   });
   let configMirrorTimer: NodeJS.Timeout | undefined;
   const CONFIG_MIRROR_EVERY_MS = 30_000;
@@ -620,8 +660,17 @@ export async function runTui(argv: string | string[] = [], deps: RunTuiDeps = {}
   // never written to the normal screen, where the alt screen's clear would
   // erase them (a visible flicker). With the companion off the same column
   // carries the skipped steps, and stays as the place that says why it is off.
-  const { StartupProgress } = await import("./startup.js");
-  const progress = new StartupProgress(undefined, {
+  const { StartupProgress, STARTUP_STEPS } = await import("./startup.js");
+  // The connection step is named for the route it checks: ssh to the VM, or
+  // the daemon container on this machine.
+  const startupSteps = STARTUP_STEPS.map((step) =>
+    step.key === "ssh" && transportOf(cfg) === "local"
+      ? { ...step, label: "daemon container" }
+      : step.key === "ssh" && route.unconfigured !== undefined
+        ? { ...step, label: "connection" }
+        : step,
+  );
+  const progress = new StartupProgress(startupSteps, {
     onUpdate: (p) => {
       // Kept after the bring-up settles on purpose: a `✗ companion container ·
       // docker is not running` is the most useful thing the column can show,
@@ -714,12 +763,20 @@ export async function runTui(argv: string | string[] = [], deps: RunTuiDeps = {}
     // `[openviking] endpoint = "remote"`, else the daemon container.
     container: tuiMemoryContainer(cfg),
     // A local engine runs in Docker; with none here, memory is off — said
-    // once as the forward's state, never retried as a failure.
-    ...(!socketMode && transportOf(cfg) === "local"
-      ? {
-          offReason: async () => ((await dockerUp()) ? undefined : MEMORY_OFF_NO_DOCKER),
-        }
-      : {}),
+    // once as the forward's state, never retried as a failure. With no ssh
+    // host there is nowhere to forward to: off, with the one remedy, rather
+    // than a relay dialing the script's default host.
+    ...(transportOf(cfg) === "ssh" && cfg.ssh_host.trim() === ""
+      ? { offReason: () => route.unconfigured ?? NO_SSH_HOST_STDERR }
+      : !socketMode && transportOf(cfg) === "local"
+        ? {
+            offReason: async () => ((await dockerUp()) ? undefined : MEMORY_OFF_NO_DOCKER),
+            // A forward that binds but reaches nothing: say whether the memory
+            // container is there at all, and how it is started.
+            diagnoseUpstream: () =>
+              diagnoseLocalMemory(cfg, routeFacts.projectDir, realProbeRunner),
+          }
+        : {}),
     log: (line) => app.notice(line),
   });
   const { buildIssueSink, ticketProjection } = await import("./issuesink.js");
@@ -1005,12 +1062,26 @@ export async function runTui(argv: string | string[] = [], deps: RunTuiDeps = {}
   // gating the first paint and, on a bad day, an interactive prompt. Nothing
   // here is self-healing by design; the TUI reports the cause and the exact
   // command, and `s` re-runs the check.
-  const { diagnosisLine, triageConnection } = await import("./sshtriage.js");
+  const { connectionUsable, diagnosisLine, triageConnection } = await import("./sshtriage.js");
+  const triageDeps = {
+    projectDir: routeFacts.projectDir,
+    ...(route.unconfigured !== undefined ? { unconfigured: route.unconfigured } : {}),
+  };
   const applyDiagnosis = (d: ConnectionDiagnosis): void => {
     app.view.connection = d;
-    if (d.kind === "ok" || d.kind === "local") progress.done("ssh", d.cause);
+    const usable = connectionUsable(d);
+    // Under an unfinished onboarding a stack that is not up yet is expected,
+    // not a fault: the step is skipped with the setup line, never failed.
+    if (usable) progress.done("ssh", d.cause);
+    else if (app.view.setup) progress.skip("ssh", setupLine(app.view.setup));
     else progress.fail("ssh", diagnosisLine(d));
-    app.notice(d.kind === "ok" || d.kind === "local" ? `✓ ${d.cause}` : `✖ ${diagnosisLine(d)}`);
+    app.notice(
+      usable
+        ? `✓ ${d.cause}`
+        : app.view.setup
+          ? setupLine(app.view.setup)
+          : `✖ ${diagnosisLine(d)}`,
+    );
     app.repaint();
   };
   // `s` starts its own async chain, independent of the bring-up. Tracked for
@@ -1018,9 +1089,13 @@ export async function runTui(argv: string | string[] = [], deps: RunTuiDeps = {}
   let pendingReconnect: Promise<void> = Promise.resolve();
   app.hooks.reconnect = () => {
     progress.begin("ssh", "re-checking");
-    app.notice("checking the connection to the VM…");
+    app.notice(
+      transportOf(cfg) === "local"
+        ? "checking the daemon container…"
+        : "checking the connection to the VM…",
+    );
     pendingReconnect = (async () => {
-      let d = await triageConnection(cfg);
+      let d = await triageConnection(cfg, triageDeps);
       // A missing key is the one class the operator can clear from here: `s`
       // is them asking for the single native passphrase prompt. A wedged
       // master or a dead host is reported with its command instead — prompting
@@ -1029,7 +1104,7 @@ export async function runTui(argv: string | string[] = [], deps: RunTuiDeps = {}
         onRealTerminal(() => {
           ensureSshMaster(cfg);
         });
-        d = await triageConnection(cfg);
+        d = await triageConnection(cfg, triageDeps);
       }
       applyDiagnosis(d);
       // Awaited, not fired and forgotten: it is part of "re-run the check and
@@ -1397,7 +1472,7 @@ export async function runTui(argv: string | string[] = [], deps: RunTuiDeps = {}
     // says "nobody has reached this yet", which would be a lie the moment the
     // probes start.
     progress.begin("ssh");
-    const triaged = triageConnection(cfg)
+    const triaged = triageConnection(cfg, triageDeps)
       .then(applyDiagnosis)
       .catch((err: unknown) =>
         progress.fail("ssh", `probe failed: ${String(err instanceof Error ? err.message : err)}`),
@@ -1439,12 +1514,31 @@ export async function runTui(argv: string | string[] = [], deps: RunTuiDeps = {}
       return;
     }
     if (step?.state === "running" && a.poller.state.consecutiveFailures >= 2) {
-      progress.fail(
-        "poll",
-        app.view.connection ? diagnosisLine(app.view.connection) : "status.json unreadable",
-      );
+      if (app.view.setup) progress.skip("poll", setupLine(app.view.setup));
+      else
+        progress.fail(
+          "poll",
+          app.view.connection ? diagnosisLine(app.view.connection) : "status.json unreadable",
+        );
     }
   });
+  // The checklist moves while the wizard runs in another terminal: re-read it
+  // each poll (one small file), and recompute the next step only when it
+  // changed. Finishing onboarding clears the banner on its own.
+  {
+    const { readChecklist } = await import("../onboard/engine.js");
+    let seen = routeFacts.checklist?.updated_at ?? null;
+    chainOnPoll(app, () => {
+      const now = readChecklist(join(routeFacts.projectDir, "state"));
+      const stamp = now?.updated_at ?? null;
+      if (stamp === seen) return;
+      seen = stamp;
+      void setupStateOf(now).then((next) => {
+        app.view.setup = next;
+        app.repaint();
+      });
+    });
+  }
 
   // Restore a hot-reload snapshot before run(), so the first paint is already
   // on the right tab with the right selection.

package/src/tui/memforward.ts

@@ -40,6 +40,9 @@
 // status` reads them) rather than painted as zero.
 import { pathToFileURL } from "node:url";
 import { join } from "node:path";
+import type { TuiConfig } from "../config.js";
+import { shellQuote } from "./remote.js";
+import type { ProbeRunner } from "./sshtriage.js";
 
 /** The container OpenViking runs in, as the TUI and the memory forward reach
  * it: the memory sidecar when `[tui] memory_container` names one, else the
@@ -50,6 +53,33 @@ export function tuiMemoryContainer(tui: { container: string; memory_container?:
   return named !== "" ? named : tui.container;
 }
 
+/**
+ * The local route's account of the memory container, for a forward that
+ * binds but reaches nothing: absent, stopped, or running but not answering
+ * yet. One `docker inspect`; undefined when docker itself gave no usable
+ * answer (the generic line stands).
+ */
+export async function diagnoseLocalMemory(
+  cfg: Pick<TuiConfig, "container" | "memory_container" | "sudo_docker">,
+  projectDir: string,
+  run: ProbeRunner,
+): Promise<string | undefined> {
+  const container = tuiMemoryContainer(cfg);
+  const inspect = ["inspect", "-f", "{{.State.Status}}", container];
+  const res = cfg.sudo_docker
+    ? await run("sudo", ["-n", "docker", ...inspect], 5_000)
+    : await run("docker", inspect, 5_000);
+  const up = `docker compose --project-directory ${shellQuote(projectDir)} up -d memory`;
+  const state = res.stdout.trim();
+  if (res.status === 0 && state === "running")
+    return `the memory container ${container} is running but OpenViking is not answering yet (it takes a minute after a start) — r retries`;
+  if (res.status === 0)
+    return `the memory container ${container} is ${state || "not running"} — start it: ${up}`;
+  if (/no such (object|container)/i.test(`${res.stderr}\n${res.stdout}`))
+    return `the memory container ${container} is not running — it starts at onboarding's bring-up step, or: ${up}`;
+  return undefined;
+}
+
 /** What the forward's `stats()` reports — the fields painted. */
 export interface ForwardStats {
   maxRelays: number;
@@ -166,6 +196,10 @@ export interface MemForwardDeps {
    * forward `off` with it as the detail — no probe, no bind, no retry, and
    * nothing that reads as a failure. */
   offReason?: () => string | undefined | Promise<string | undefined>;
+  /** Asked when the forward listens but nothing answers through it: a precise
+   * account of the upstream (the memory container absent, stopped, still
+   * starting), or undefined to keep the generic line. Never throws. */
+  diagnoseUpstream?: () => Promise<string | undefined>;
 }
 
 const DEFAULT_PROBE_TIMEOUT_MS = 1_500;
@@ -195,12 +229,13 @@ async function httpProbe(baseUrl: string, timeoutMs: number): Promise<boolean> {
  */
 export class MemoryForward {
   private readonly deps: Required<
-    Omit<MemForwardDeps, "env" | "sshHost" | "container" | "offReason">
+    Omit<MemForwardDeps, "env" | "sshHost" | "container" | "offReason" | "diagnoseUpstream">
   > & {
     env: NodeJS.ProcessEnv;
     sshHost?: string;
     container?: string;
     offReason?: MemForwardDeps["offReason"];
+    diagnoseUpstream?: MemForwardDeps["diagnoseUpstream"];
   };
   private handle: ForwarderHandle | null = null;
   /** How many of its addresses our forward bound, kept with the handle so
@@ -228,6 +263,7 @@ export class MemoryForward {
       ...(deps.sshHost ? { sshHost: deps.sshHost } : {}),
       ...(deps.container ? { container: deps.container } : {}),
       ...(deps.offReason ? { offReason: deps.offReason } : {}),
+      ...(deps.diagnoseUpstream ? { diagnoseUpstream: deps.diagnoseUpstream } : {}),
     };
     this.status = {
       state: "off",
@@ -295,7 +331,8 @@ export class MemoryForward {
         alive ? "owned" : "failed",
         alive
           ? this.ownedDetail(this.binds?.bound, this.binds?.wanted)
-          : "the forward we started stopped answering — r retries",
+          : ((await this.upstreamDetail()) ??
+              "the forward we started stopped answering — r retries"),
       );
     }
     if (await this.deps.probe(this.deps.baseUrl, this.deps.probeTimeoutMs)) {
@@ -367,7 +404,10 @@ export class MemoryForward {
       if (!(await this.deps.probe(this.deps.baseUrl, this.deps.probeTimeoutMs))) {
         return this.settle(
           "failed",
-          "the forward we started is listening but upstream is not answering (ssh, VM container or OpenViking) — r retries",
+          (await this.upstreamDetail()) ??
+            (this.deps.local
+              ? "the forward we started is listening but upstream is not answering (the memory container or OpenViking) — r retries"
+              : "the forward we started is listening but upstream is not answering (ssh, VM container or OpenViking) — r retries"),
         );
       }
       return this.settle("owned", this.ownedDetail(bound, cfg.binds.length));
@@ -400,6 +440,15 @@ export class MemoryForward {
     return this.inFlight;
   }
 
+  /** The upstream's own account, when one was wired; total. */
+  private async upstreamDetail(): Promise<string | undefined> {
+    try {
+      return await this.deps.diagnoseUpstream?.();
+    } catch {
+      return undefined;
+    }
+  }
+
   /** A partial bind is a working state, not a failure: loopback alone serves
    * the TUI, and the docker-bridge bind only matters when the companion
    * container is up. Say which, rather than reporting a bare "ok". */

package/src/tui/memory.ts

@@ -52,7 +52,7 @@ import {
 import { countOutcome, emptyRequestCounter, type RequestCounter } from "../memory/health.js";
 import { OpenVikingStore } from "../openviking/store.js";
 import { readRetiredUrisFile, writeRetiredUris } from "../memory/ovsession.js";
-import { keysFilePath, MEMORY } from "./companion.js";
+import { keysFilePath } from "./companion.js";
 
 export { matchesQuery, normalizeTag, refOf } from "../memory/store.js";
 export type {
@@ -227,20 +227,8 @@ export function keysFileReader(
   };
 }
 
-/**
- * Where the TUI reaches OpenViking: the memory forward's loopback listener.
- *
- * `QCR_MEMORY_URL` overrides it wholesale; `QCR_MEMORY_PORT` matches the flag
- * the forward itself takes, so a non-default port only has to be spelled once.
- * `MEMORY.port` is the shared constant the forward and the companion already
- * agree on.
- */
-export function tuiMemoryBaseUrl(env: NodeJS.ProcessEnv = process.env): string {
-  const explicit = (env["QCR_MEMORY_URL"] ?? env["QCR_MEMORY_ENDPOINT"] ?? "").trim();
-  if (explicit !== "") return explicit.replace(/\/+$/, "");
-  const port = Number(env["QCR_MEMORY_PORT"] ?? MEMORY.port) || MEMORY.port;
-  return `http://127.0.0.1:${port}`;
-}
+import { tuiMemoryBaseUrl } from "./memoryurl.js";
+export { tuiMemoryBaseUrl };
 
 // ---- the store ---------------------------------------------------------------
 

package/src/tui/memoryurl.ts

@@ -0,0 +1,22 @@
+// Where this host reaches OpenViking: the memory forward's loopback
+// listener. A leaf module, so a reader of the URL (the wizard's memory step,
+// the home) never imports the TUI's memory store or the companion.
+
+/** The port the memory forward and the companion agree on, the server's own
+ * in the VM container (`[openviking] port`). */
+export const MEMORY_PORT = 1933;
+
+/**
+ * Where the TUI reaches OpenViking: the memory forward's loopback listener.
+ *
+ * `QCR_MEMORY_URL` overrides it wholesale; `QCR_MEMORY_PORT` matches the flag
+ * the forward itself takes, so a non-default port only has to be spelled once.
+ * `MEMORY_PORT` is the shared constant the forward and the companion already
+ * agree on.
+ */
+export function tuiMemoryBaseUrl(env: NodeJS.ProcessEnv = process.env): string {
+  const explicit = (env["QCR_MEMORY_URL"] ?? env["QCR_MEMORY_ENDPOINT"] ?? "").trim();
+  if (explicit !== "") return explicit.replace(/\/+$/, "");
+  const port = Number(env["QCR_MEMORY_PORT"] ?? MEMORY_PORT) || MEMORY_PORT;
+  return `http://127.0.0.1:${port}`;
+}

package/src/tui/model.ts

@@ -3,7 +3,16 @@
 // selection movement.
 import type { PrLifecycleState, StatusSnapshot } from "../state.js";
 
-export type SnapshotPr = StatusSnapshot["prs"][number];
+export type SnapshotPr = StatusSnapshot["prs"][number] & {
+  /** A board-only row: an open PR of the repo the daemon does not track yet
+   * (status.json `open_prs`). It is offered for review (`R`); nothing about it
+   * is known beyond what the PR list says, so no PR verb but `R` and `g`
+   * acts on it. */
+  offered?: true;
+};
+
+/** The glyph of an offered row: open on GitHub, not reviewed yet. */
+export const OFFERED_GLYPH = "○";
 
 export const STATE_GLYPHS: Record<PrLifecycleState, string> = {
   queued: "●",
@@ -14,7 +23,8 @@ export const STATE_GLYPHS: Record<PrLifecycleState, string> = {
 };
 
 /** `↻` prefixes the state glyph when a stale recheck is pending. */
-export function glyphFor(pr: Pick<SnapshotPr, "state" | "stale_recheck">): string {
+export function glyphFor(pr: Pick<SnapshotPr, "state" | "stale_recheck" | "offered">): string {
+  if (pr.offered) return OFFERED_GLYPH;
   const base = STATE_GLYPHS[pr.state] ?? "?";
   return pr.stale_recheck ? `↻${base}` : base;
 }
@@ -79,6 +89,30 @@ export function sortPrs(prs: SnapshotPr[]): SnapshotPr[] {
     .sort((a, b) => rank(a.state) - rank(b.state) || a.number - b.number);
 }
 
+/** The repo's open PRs the daemon does not track (status.json `open_prs`),
+ * newest activity first, as offered board rows. A tracked PR is never offered
+ * twice: its own row is the one the verbs act on. */
+export function offeredPrs(
+  snapshot: Pick<StatusSnapshot, "prs" | "open_prs"> | undefined,
+): SnapshotPr[] {
+  const open = snapshot?.open_prs?.prs ?? [];
+  const tracked = new Set((snapshot?.prs ?? []).filter(onBoard).map((p) => p.number));
+  return open
+    .filter((p) => !tracked.has(p.number))
+    .slice()
+    .sort((a, b) => b.updated_at.localeCompare(a.updated_at) || b.number - a.number)
+    .map((p) => ({
+      number: p.number,
+      state: "tracked" as const,
+      title: p.draft ? `[draft] ${p.title}` : p.title,
+      head_sha: "",
+      stale_recheck: 0,
+      author: p.author,
+      updated_at: p.updated_at,
+      offered: true as const,
+    }));
+}
+
 export interface EventLine {
   ts: string; // HH:MM:SS
   text: string;

package/src/tui/prpause.ts

@@ -20,8 +20,10 @@ import type { SshRunner } from "./remote.js";
 import { commandResultArgv, commandWriteArgv, resultReason } from "./unwedge.js";
 import { resolveLayout } from "./layout.js";
 
-/** The two payloads, read from the daemon's own `Command`. */
-export type PrLeverCommand = Extract<Command, { command: "pause-pr" | "resume-pr" }>;
+/** The payloads, read from the daemon's own `Command`: the pause pair, and
+ * `review-now` (one PR queued for a human-asked round), which rides the same
+ * sealed channel and the same receipt. */
+export type PrLeverCommand = Extract<Command, { command: "pause-pr" | "resume-pr" | "review-now" }>;
 
 export interface PrLeverOutcome {
   ok: boolean;
@@ -132,6 +134,13 @@ export function renderPrLever(
     return { lines, code: 1 };
   }
   if (cmd.command === "resume-pr") return { lines: [`✓ ${pr} resumed`], code: 0 };
+  if (cmd.command === "review-now")
+    return {
+      lines: [
+        `✓ ${pr} queued for review${out.outcome ? ` (${out.outcome})` : ""} — follow it with \`qcr why ${cmd.pr}\` or on the board`,
+      ],
+      code: 0,
+    };
   if (out.issuer !== "operator") {
     return {
       lines: [