@quickchatai/quickreview 1.1.0 → 1.2.0

package/src/tui/companion.ts

@@ -41,7 +41,7 @@ import {
   stateHome,
   type InstallEnv,
 } from "../install.js";
-import type { CompanionConfig } from "../config.js";
+import { COMPANION_IMAGE, type CompanionConfig } from "../config.js";
 import { writeAtomic } from "../channelfs.js";
 import { appStamp } from "../appstamp.js";
 import { TOKEN_FILE } from "./ghread.js";
@@ -453,6 +453,15 @@ export function companionInjectDir(cfg: Pick<CompanionConfig, "repo_dir" | "sess
  * `qcr scan` the companion runs) knows it is inside the companion container. */
 export const IN_COMPANION_ENV = "QCR_IN_COMPANION";
 
+/** The published release image's repository (src/onboard/steps/compose.ts
+ * RELEASE_IMAGE_REPO): a tag under it is pulled, never built locally. */
+const RELEASE_IMAGE_PREFIX = "ghcr.io/quickchatai/quickreview:";
+
+/** Is `image` a published release tag (pulled, never built over)? */
+export function isReleaseImage(image: string): boolean {
+  return image.startsWith(RELEASE_IMAGE_PREFIX);
+}
+
 /** The release image's mode word for the companion container
  * (docker/entrypoint.sh): provision pi, start the tmux server, stay alive. */
 export const COMPANION_MODE = "companion";
@@ -560,6 +569,23 @@ export class CompanionLifecycle {
    * companion's tmux server. A field so tests need not wait it out. */
   wrapperStartWaitMs = WRAPPER_START_WAIT_MS;
 
+  /** An image already on this machine to run instead of BUILDING the default
+   * one: the release image a compose box pulled (`ghcr.io/…:<QCR_VERSION>`,
+   * the same docker/Dockerfile CI built). Consulted only on a cold create,
+   * only while `[companion] image` is the shipped default, and only when no
+   * local build of that default exists — so an explicit image and a
+   * contributor's `qcr companion rebuild` both keep winning. */
+  preferredImage: string | undefined;
+
+  /** The image this instance runs: `[companion] image`, until a cold create
+   * adopts `preferredImage`. */
+  private imageInUse: string | undefined;
+
+  /** The image a create runs (and a build tags). */
+  get image(): string {
+    return this.imageInUse ?? this.cfg.image;
+  }
+
   /** The shared socket in `tmux-socket` mode, else undefined. */
   get socketPath(): string | undefined {
     return this.mode === "tmux-socket" ? tmuxSocketPath(this.cfg) : undefined;
@@ -620,7 +646,7 @@ export class CompanionLifecycle {
     // The agent is reached by its mounted socket; no key is in the container.
     if (this.sshSources().agent !== undefined) argv.push("--env", `SSH_AUTH_SOCK=${SSH.agent}`);
     // The release image, in its companion mode (docker/entrypoint.sh).
-    argv.push(this.cfg.image, COMPANION_MODE);
+    argv.push(this.image, COMPANION_MODE);
     return argv;
   }
 
@@ -672,6 +698,13 @@ export class CompanionLifecycle {
       "--theme",
       `${ext}/muted-theme.json`,
       "--extension",
+      // The login route (extensions/login-route.ts), before the inject bridge so
+      // the day-open delivery meets a routed model: a companion whose model's
+      // provider has no login runs the same model on the other OpenAI login
+      // when that one exists, and a companion with no usable login at all says
+      // which logins work and leaves `/login` on its input line.
+      `${ext}/cli/login-route.ts`,
+      "--extension",
       // Day-open channel: the daemon's inject bridge, unmodified. It
       // drains its directory on session_start before it starts watching, so
       // the rollover can queue the opening message before pi is spawned and
@@ -926,10 +959,27 @@ export class CompanionLifecycle {
 
   /** True when the companion image exists locally. */
   async imageExists(): Promise<boolean> {
-    const res = await this.docker(["image", "inspect", this.cfg.image]);
+    const res = await this.docker(["image", "inspect", this.image]);
     return res.ok;
   }
 
+  /**
+   * Before a cold create builds the default image: adopt the preferred
+   * (already-pulled release) image when the default is not built here and the
+   * preferred one is. True when the image to run now exists.
+   */
+  private async adoptPreferredImage(onProgress?: (line: string) => void): Promise<boolean> {
+    if (await this.imageExists()) return true;
+    const preferred = this.preferredImage;
+    if (preferred === undefined || preferred === "" || this.cfg.image !== COMPANION_IMAGE)
+      return false;
+    const res = await this.docker(["image", "inspect", preferred]);
+    if (!res.ok) return false;
+    this.imageInUse = preferred;
+    onProgress?.(`using the release image ${preferred}, already pulled — no local build`);
+    return true;
+  }
+
   /** Remove the container, running or not. Volumes (pihome: OAuth, the
    * conversation) survive — this replaces the container, never its memory. */
   async removeContainer(): Promise<void> {
@@ -945,9 +995,22 @@ export class CompanionLifecycle {
     if (!res.ok) throw new Error(`docker rm ${this.cfg.container_name} failed: ${errText(res)}`);
   }
 
+  /** `docker pull` of a configured release image the machine does not have. */
+  private async pullImage(onProgress?: (line: string) => void): Promise<void> {
+    onProgress?.(`pulling ${this.image} (first run — a few minutes)…`);
+    const res = await this.docker(["pull", this.image], { timeoutMs: 1_800_000 });
+    if (!res.ok) throw new Error(`docker pull ${this.image} failed: ${errText(res)}`);
+    onProgress?.(`${this.image} pulled`);
+  }
+
   /** Throws when the image cannot be built (`imageBuildProblem`) — asked
    * before anything is removed for a rebuild. */
   checkBuildable(): void {
+    if (isReleaseImage(this.image))
+      throw new Error(
+        `${this.image} is a published release image — it is pulled (docker pull ${this.image}), never built over; ` +
+          `set [companion] image = "${COMPANION_IMAGE}" to build one from this checkout`,
+      );
     const problem = imageBuildProblem(this.cfg.build_context, (p) => this.fs.exists(p));
     if (problem !== null) throw new Error(problem);
   }
@@ -960,21 +1023,21 @@ export class CompanionLifecycle {
   async buildImage(onProgress?: (line: string) => void): Promise<void> {
     this.checkBuildable();
     const ctx = this.cfg.build_context;
-    onProgress?.(`building ${this.cfg.image} image (first run — takes a few minutes)…`);
+    onProgress?.(`building ${this.image} image (first run — takes a few minutes)…`);
     // The stamp is the checkout's; the build reads an assembled copy of the
     // release context, so it works on the legacy builder too.
     const stamp = this.stampOf(ctx);
     const built = this.assembleContext(ctx);
     let res;
     try {
-      res = await this.docker(appImageBuildArgv(this.cfg.image, built, stamp), {
+      res = await this.docker(appImageBuildArgv(this.image, built, stamp), {
         timeoutMs: 1_800_000,
       });
     } finally {
       if (built !== ctx) rmSync(built, { recursive: true, force: true });
     }
-    if (!res.ok) throw new Error(`docker build ${this.cfg.image} failed: ${errText(res)}`);
-    onProgress?.(`${this.cfg.image} image built`);
+    if (!res.ok) throw new Error(`docker build ${this.image} failed: ${errText(res)}`);
+    onProgress?.(`${this.image} image built`);
   }
 
   // ---- memory wiring --------------------------------------------------------
@@ -1266,8 +1329,13 @@ export class CompanionLifecycle {
       onProgress?.(`companion container unstartable (${firstLine(errText(started))}) — recreating`);
       await this.forceRemove();
     }
-    // Self-healing first run: build the image rather than failing on its absence.
-    if (!(await this.imageExists())) await this.buildImage(onProgress);
+    // Self-healing first run: the pulled release image when there is one,
+    // else build the image rather than failing on its absence — or, for a
+    // configured release image, pull it (a release tag is never built over).
+    if (!(await this.adoptPreferredImage(onProgress))) {
+      if (isReleaseImage(this.image)) await this.pullImage(onProgress);
+      else await this.buildImage(onProgress);
+    }
     const homes = this.hostHomes();
     this.ensureDirs([
       this.cfg.feed_dir,
@@ -1280,7 +1348,7 @@ export class CompanionLifecycle {
       homes.github,
     ]);
     const created = await this.docker(this.runArgv(), { timeoutMs: 120_000 });
-    if (!created.ok) throw new Error(`docker run ${this.cfg.image} failed: ${errText(created)}`);
+    if (!created.ok) throw new Error(`docker run ${this.image} failed: ${errText(created)}`);
     return st.exists || recreating ? "recreated" : "created";
   }
 

package/src/tui/connect.ts

@@ -11,7 +11,7 @@
 // the exact remedy; pressing `s` is the operator asking for this prompt.
 import { spawnSync } from "node:child_process";
 import type { TuiConfig } from "../config.js";
-import { transportOf } from "./remote.js";
+import { NO_SSH_HOST_STDERR, transportOf } from "./remote.js";
 
 export function masterCheckArgv(cfg: TuiConfig): string[] {
   return ["-O", "check", cfg.ssh_host];
@@ -51,6 +51,12 @@ export function ensureSshMaster(
   // at the call sites) so the board's `s` reconnect hook and any future caller
   // inherit the guarantee: in local mode this function spawns nothing.
   if (transportOf(cfg) === "local") return { kind: "local" };
+  // No host, nothing to connect to: `ssh "" true` only ever fails on name
+  // resolution, and the passphrase prompt it promises would never come.
+  if (cfg.ssh_host.trim() === "") {
+    say(NO_SSH_HOST_STDERR);
+    return { kind: "failed", detail: NO_SSH_HOST_STDERR };
+  }
   if (ssh(masterCheckArgv(cfg), false).status === 0) return { kind: "alive" };
   say(
     `connecting to ${cfg.ssh_host} — enter the GCP key passphrase if asked (once; the connection is shared for 4h)`,

package/src/tui/filters.ts

@@ -5,7 +5,8 @@
 // they never touch the poller's snapshot or the memory store.
 import { normalizeTag } from "../memory/store.js";
 import type { MemoryEntry } from "./memory.js";
-import { sortPrs, type SnapshotPr } from "./model.js";
+import type { StatusSnapshot } from "../state.js";
+import { offeredPrs, sortPrs, type SnapshotPr } from "./model.js";
 
 export interface BoardFilter {
   /** Case-insensitive substring match against the PR author login. */
@@ -76,10 +77,13 @@ export function applyMemoryFilter<T extends Pick<MemoryEntry, "tags">>(
  * companion driver all derive rows from here, so a verb can never address a
  * row the filter hid. */
 export function visiblePrs(view: {
-  snapshot?: { prs: SnapshotPr[] };
+  snapshot?: { prs: SnapshotPr[]; open_prs?: StatusSnapshot["open_prs"] };
   boardFilter?: BoardFilter | null;
 }): SnapshotPr[] {
-  return applyBoardFilter(sortPrs(view.snapshot?.prs ?? []), view.boardFilter);
+  const tracked = applyBoardFilter(sortPrs(view.snapshot?.prs ?? []), view.boardFilter);
+  // The repo's other open PRs follow, offered for review — under a filter the
+  // board shows only what the filter names.
+  return view.boardFilter != null ? tracked : [...tracked, ...offeredPrs(view.snapshot)];
 }
 
 /** The memory view's indicator, same shape as the board's. */

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 onboarding checklist is not complete: run qcr onboard
+                     (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,15 @@ 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 this checkout holds locally (the compose project's .env, the
+  // onboarding checklist, the Docker socket's mode). 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 routeFacts = deps.routeFacts ?? readRouteFacts(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 +474,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 +585,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 +629,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 +657,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 +760,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 +1059,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 +1086,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 +1101,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 +1469,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 +1511,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.