@quickchatai/quickreview 1.1.0 → 1.2.0

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/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: [

package/src/tui/remote.ts

@@ -337,8 +337,16 @@ export function killInFlightSsh(): number {
   return killed;
 }
 
+/** What the ssh runner answers for an empty host — spawned, `ssh "" …` would
+ * die on "Could not resolve hostname" and every surface would print an ssh
+ * remedy with no host in it. */
+export const NO_SSH_HOST_STDERR =
+  '[tui] ssh_host is empty — run `qcr onboard`, or set [tui] target = "local"';
+
 export const realSshRunner: SshRunner = (host, argv, opts) =>
-  runChild("ssh", ["-o", "BatchMode=yes", host, argv.map(shellQuote).join(" ")], opts);
+  host.trim() === ""
+    ? Promise.resolve({ ok: false, stdout: "", stderr: NO_SSH_HOST_STDERR, code: null })
+    : runChild("ssh", ["-o", "BatchMode=yes", host, argv.map(shellQuote).join(" ")], opts);
 
 /**
  * The laptop topology's runner — the same argv every builder above

package/src/tui/route.ts

@@ -0,0 +1,173 @@
+// The TUI's route — which daemon the board reads, and how — resolved ONCE,
+// before the first frame, from config.toml's [tui] block plus three local
+// facts that cost no docker, network or directory walk: the compose
+// project's `.env`, the onboarding checklist, and whether this user can open
+// the Docker socket without sudo.
+//
+// Why a resolution step at all. `[tui]` ships VM-shaped defaults (target
+// "ssh", sudo docker, the VM host's state path), and on one box a fresh
+// install opens the TUI before onboarding's config_fill has written its
+// local values — or with a hand-written config that never names them. Every
+// builder in remote.ts reads the config it is handed, and the transport is
+// still decided by the explicit `target` knob alone (`transportOf`); this
+// module only decides which config that is, and says so once when it departs
+// from the file:
+//
+//   * `target = "ssh"` with an EMPTY `ssh_host` cannot reach anything. When
+//     this checkout is a compose project (the checklist recorded the local
+//     topology, or none was recorded and the project `.env` pins a release)
+//     the route is the local stack, said once; otherwise the route is
+//     `unconfigured` and every surface shows the one precise remedy instead
+//     of an ssh command with no host in it.
+//   * On the local route the state dir is the release image's
+//     (`/opt/qcr/state`, the compose `qcr-state` volume) whenever the knob
+//     still holds the VM default, the daemon's `-daemon-N` container implies
+//     its `-memory-N` sidecar for the memory forward, and sudo is dropped
+//     when the socket answers this user without it (a non-interactive
+//     `sudo docker` behind the alt screen can only fail).
+//
+// An operator's explicit, non-default value always wins: nothing here
+// overwrites a value the file states differently from the shipped default.
+import { accessSync, constants, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { TUI_DEFAULTS, type TuiConfig } from "../config.js";
+import { readChecklist, type ChecklistFile } from "../onboard/engine.js";
+import { CHOICE_KEYS } from "../onboard/choices.js";
+import { NO_SSH_HOST_STDERR } from "./remote.js";
+
+/** The release image's state dir inside the daemon container (the compose
+ * `qcr-state` volume; src/onboard/steps/ingress.ts CONTAINER_STATE_DIR). */
+export const RELEASE_STATE_DIR = "/opt/qcr/state";
+
+/** The bundled compose project's daemon and memory containers
+ * (docker-compose.yml `name: quickreview`). */
+export const COMPOSE_DAEMON_CONTAINER = "quickreview-daemon-1";
+export const COMPOSE_MEMORY_CONTAINER = "quickreview-memory-1";
+
+/** The legacy daemon container (no `qcr.layout` label): the one container whose
+ * in-container state dir is still the VM-shaped default. */
+const LEGACY_CONTAINER = "quickreview-sandbox";
+
+export interface RouteFacts {
+  /** The compose project directory (this checkout): remedy text names it. */
+  projectDir: string;
+  /** `<project>/.env`, or null when there is none. */
+  projectEnv: string | null;
+  /** The onboarding checklist, or null when absent or unreadable. */
+  checklist: ChecklistFile | null;
+  /** Can this user open the Docker socket without sudo? undefined = no socket
+   * found to ask (no local Docker, or a remote DOCKER_HOST). */
+  dockerSocketAccess: boolean | undefined;
+}
+
+export interface TuiRoute {
+  /** The config every TUI remote op is built from. */
+  cfg: TuiConfig;
+  /** One-time lines for the notice line: where the route departs from the file. */
+  notes: string[];
+  /** Set when nothing can be reached: the precise reason and remedy, shown in
+   * place of any ssh diagnosis. */
+  unconfigured?: string;
+}
+
+/** The precise message for `target = "ssh"` with no host and no local stack —
+ * the same words the ssh runner answers an empty host with. */
+export const EMPTY_SSH_HOST = NO_SSH_HOST_STDERR;
+
+/** `QCR_VERSION=` from a project `.env` — "" when absent. */
+export function pinnedVersion(envText: string | null): string {
+  if (envText === null) return "";
+  const m = /^QCR_VERSION=(.*)$/m.exec(envText);
+  return m ? (m[1] ?? "").trim().replace(/^["']|["']$/g, "") : "";
+}
+
+/** The recorded topology, or null when the checklist recorded none. */
+function recordedTopology(checklist: ChecklistFile | null): "local" | "vm" | null {
+  const raw = checklist?.choices[CHOICE_KEYS.topology];
+  return raw === "local" || raw === "vm" ? raw : null;
+}
+
+/** The `-memory-N` sidecar a compose `-daemon-N` container implies, or "". */
+export function composeMemoryFor(container: string): string {
+  const m = /^(.+)-daemon-(\d+)$/.exec(container);
+  return m ? `${m[1]}-memory-${m[2]}` : "";
+}
+
+/** Pure: the effective [tui] config for these facts. */
+export function resolveTuiRoute(file: TuiConfig, facts: RouteFacts): TuiRoute {
+  const notes: string[] = [];
+  let cfg: TuiConfig = { ...file };
+  if (cfg.target === "ssh" && cfg.ssh_host.trim() === "") {
+    const topology = recordedTopology(facts.checklist);
+    const composeProject = pinnedVersion(facts.projectEnv) !== "";
+    if (topology === "local" || (topology === null && composeProject)) {
+      cfg = {
+        ...cfg,
+        target: "local",
+        container:
+          cfg.container === TUI_DEFAULTS.container ? COMPOSE_DAEMON_CONTAINER : cfg.container,
+      };
+      notes.push(
+        `[tui] target is "ssh" with no ssh_host — reading the local compose stack in ${facts.projectDir} instead ` +
+          '(run `qcr onboard`, or set [tui] target = "local", to make it explicit)',
+      );
+    } else {
+      return {
+        cfg,
+        notes,
+        unconfigured:
+          topology === "vm"
+            ? "[tui] ssh_host is empty — the VM route's ssh alias is written by onboarding: run `qcr onboard`"
+            : EMPTY_SSH_HOST,
+      };
+    }
+  }
+  if (cfg.target !== "local") return { cfg, notes };
+  if (cfg.remote_state_dir === TUI_DEFAULTS.remote_state_dir && cfg.container !== LEGACY_CONTAINER)
+    cfg = { ...cfg, remote_state_dir: RELEASE_STATE_DIR };
+  if ((cfg.memory_container ?? "").trim() === "") {
+    const memory = composeMemoryFor(cfg.container);
+    if (memory !== "") cfg = { ...cfg, memory_container: memory };
+  }
+  if (cfg.sudo_docker && facts.dockerSocketAccess === true) cfg = { ...cfg, sudo_docker: false };
+  return { cfg, notes };
+}
+
+/** The Docker socket this process would talk to: `DOCKER_HOST` when it is a
+ * unix socket, the default path otherwise; undefined for a remote daemon. */
+export function dockerSocketPath(env: NodeJS.ProcessEnv): string | undefined {
+  const host = (env["DOCKER_HOST"] ?? "").trim();
+  if (host === "") return "/var/run/docker.sock";
+  return host.startsWith("unix://") ? host.slice("unix://".length) : undefined;
+}
+
+/** One `access(2)` on the socket — no docker call, no walk. */
+export function probeSocketAccess(
+  path: string | undefined,
+  access: (p: string, mode: number) => void = accessSync,
+): boolean | undefined {
+  if (path === undefined) return undefined;
+  try {
+    access(path, constants.R_OK | constants.W_OK);
+    return true;
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code;
+    return code === "EACCES" || code === "EPERM" ? false : undefined;
+  }
+}
+
+/** The facts, read from this checkout: two small files and one access(2). */
+export function readRouteFacts(root: string, env: NodeJS.ProcessEnv = process.env): RouteFacts {
+  let projectEnv: string | null = null;
+  try {
+    projectEnv = readFileSync(join(root, ".env"), "utf8");
+  } catch {
+    projectEnv = null;
+  }
+  return {
+    projectDir: root,
+    projectEnv,
+    checklist: readChecklist(join(root, "state")),
+    dockerSocketAccess: probeSocketAccess(dockerSocketPath(env)),
+  };
+}

package/src/tui/setupstate.ts

@@ -0,0 +1,52 @@
+// Is onboarding finished? Read from the checklist file the wizard keeps
+// (src/onboard/engine.ts), so a TUI opened halfway through `qcr onboard` says
+// so on its first frame instead of troubleshooting a daemon nobody has started
+// yet.
+//
+// Only a checklist that EXISTS and is not complete counts: an install that
+// never ran the wizard (a hand-written config, the VM operator's own setup)
+// has no checklist and gets no banner. The next step is the first enabled step,
+// in the wizard's own order, that the file does not record as done — the same
+// predicates the engine applies, so the TUI cannot name a step the wizard would
+// skip.
+import { type ChecklistFile } from "../onboard/engine.js";
+
+export interface SetupState {
+  /** The title of the first pending step ("the final verification" when only
+   * finish is left), or undefined when it could not be computed. */
+  next: string | undefined;
+}
+
+/** The one sentence every surface uses. */
+export function setupLine(s: SetupState): string {
+  return `setup not finished — run \`qcr onboard\` to continue${s.next ? ` (next: ${s.next})` : ""}`;
+}
+
+/** Complete now: finished once and not reopened since (engine.ts `completeNow`). */
+function completeNow(file: ChecklistFile): boolean {
+  return typeof file.completed_at === "string" && !file.reopened_at;
+}
+
+/** undefined = nothing to say (no checklist, or onboarding is complete). */
+export async function setupStateOf(
+  checklist: ChecklistFile | null,
+): Promise<SetupState | undefined> {
+  if (checklist === null || completeNow(checklist)) return undefined;
+  let next: string | undefined;
+  try {
+    const { defaultSteps } = await import("../onboard/steps/index.js");
+    const steps = [...defaultSteps()].sort((a, b) => a.order - b.order);
+    const pending = steps.find(
+      (s) =>
+        !s.optional &&
+        (s.enabled ? s.enabled(checklist.choices) : true) &&
+        checklist.steps[s.id]?.status !== "done",
+    );
+    next = pending?.title ?? "the final verification";
+  } catch {
+    // The step registry could not be loaded: the banner still says setup is
+    // unfinished, without naming a step it could not compute.
+    next = undefined;
+  }
+  return { next };
+}

package/src/tui/sshtriage.ts

@@ -25,13 +25,22 @@ import { existsSync } from "node:fs";
 import { homedir } from "node:os";
 import type { TuiConfig } from "../config.js";
 import { masterCheckArgv } from "./connect.js";
-import { shellQuote, transportOf } from "./remote.js";
+import { NO_SSH_HOST_STDERR, shellQuote, transportOf } from "./remote.js";
 
 export type ConnectionClass =
   /** The VM answers — master alive, or a fresh connection succeeded. */
   | "ok"
-  /** `[tui] target = "local"`: there is no ssh anywhere. */
+  /** `[tui] target = "local"`: there is no ssh anywhere, and the daemon
+   * container is running on this machine. */
   | "local"
+  /** Local route: Docker answers, but the daemon container is absent or not
+   * running (the stack is not up yet, or it stopped). */
+  | "local-down"
+  /** Local route: the local Docker itself did not answer this user. */
+  | "local-docker"
+  /** Nothing to connect to: `target = "ssh"` with no `ssh_host` (onboarding
+   * has not written the route yet). No ssh is ever spawned for it. */
+  | "unconfigured"
   /** The agent cannot offer the key ssh wants for this host. */
   | "no-agent-key"
   /** A ControlMaster socket is there and does not answer. */
@@ -413,6 +422,112 @@ export interface TriageDeps {
   run?: ProbeRunner;
   exists?: (path: string) => boolean;
   home?: string;
+  /** The compose project directory, for the local route's remedy line. */
+  projectDir?: string;
+  /** The route resolver's reason nothing can be reached (src/tui/route.ts);
+   * defaults to the empty-ssh_host sentence. */
+  unconfigured?: string;
+}
+
+/** Is this a local-route diagnosis (no ssh anywhere)? */
+export function isLocalDiagnosis(d: Pick<ConnectionDiagnosis, "kind">): boolean {
+  return d.kind === "local" || d.kind === "local-down" || d.kind === "local-docker";
+}
+
+/** A diagnosis under which the daemon can answer: the board's "connected". */
+export function connectionUsable(d: Pick<ConnectionDiagnosis, "kind">): boolean {
+  return d.kind === "ok" || d.kind === "local";
+}
+
+/** `docker inspect` of the daemon container's state, for the local route.
+ * `sudo -n` when sudo is configured: a password prompt behind the alt screen
+ * is a hang, so a sudo that would ask fails instead. */
+export function localDaemonProbeArgv(cfg: TuiConfig): { cmd: string; argv: string[] } {
+  const inspect = ["inspect", "-f", "{{.State.Status}}", cfg.container];
+  return cfg.sudo_docker
+    ? { cmd: "sudo", argv: ["-n", "docker", ...inspect] }
+    : { cmd: "docker", argv: inspect };
+}
+
+/** How to bring the stack up from here. */
+export function composeUpRemedy(projectDir: string | undefined, container: string): string {
+  return projectDir
+    ? `docker compose --project-directory ${shellQuote(projectDir)} up -d`
+    : `docker start ${shellQuote(container)}`;
+}
+
+/** Pure: the local route's diagnosis from one `docker inspect`. */
+export function classifyLocal(
+  cfg: TuiConfig,
+  res: ProbeResult,
+  projectDir?: string,
+): ConnectionDiagnosis {
+  const c = cfg.container;
+  const out = res.stdout.trim();
+  const evidence = firstLine(res.stderr);
+  const detail = evidence ? { detail: evidence } : {};
+  if (res.status === 0 && out === "running") {
+    return {
+      kind: "local",
+      cause: `local docker — the daemon container ${c} is running on this machine (no ssh)`,
+      remedy: "",
+    };
+  }
+  if (res.status === 0) {
+    return {
+      kind: "local-down",
+      cause: `the daemon container ${c} is ${out || "not running"} — start it`,
+      remedy: composeUpRemedy(projectDir, c),
+    };
+  }
+  if (res.timedOut) {
+    return {
+      kind: "local-docker",
+      cause: "local Docker did not answer in time",
+      remedy: "docker info",
+      ...detail,
+    };
+  }
+  const text = `${res.stderr}
+${res.stdout}`;
+  if (/no such (object|container)/i.test(text)) {
+    return {
+      kind: "local-down",
+      cause: `no daemon container ${c} on this machine — the compose stack is not up (it starts at onboarding's bring-up step)`,
+      remedy: composeUpRemedy(projectDir, c),
+    };
+  }
+  if (/a password is required|a terminal is required/i.test(text)) {
+    return {
+      kind: "local-docker",
+      cause: "[tui] sudo_docker is on and sudo wants a password the TUI cannot type",
+      remedy:
+        'sudo usermod -aG docker "$USER"   # then log in again, and set [tui] sudo_docker = false',
+      ...detail,
+    };
+  }
+  if (/permission denied/i.test(text)) {
+    return {
+      kind: "local-docker",
+      cause: "this user cannot open the local Docker socket",
+      remedy: 'sudo usermod -aG docker "$USER"   # then log in again',
+      ...detail,
+    };
+  }
+  if (/ENOENT|not found|no such file/i.test(text) && !/daemon/i.test(text)) {
+    return {
+      kind: "local-docker",
+      cause: "there is no docker command on this machine",
+      remedy: "docker --version",
+      ...detail,
+    };
+  }
+  return {
+    kind: "local-docker",
+    cause: `local Docker is not answering — ${evidence || "no error text"}`,
+    remedy: "docker info",
+    ...detail,
+  };
 }
 
 const CONFIG_TIMEOUT_MS = 5_000;
@@ -458,14 +573,20 @@ export async function triageConnection(
   cfg: TuiConfig,
   deps: TriageDeps = {},
 ): Promise<ConnectionDiagnosis> {
+  const run = deps.run ?? realProbeRunner;
   if (transportOf(cfg) === "local") {
+    // No ssh anywhere: the one probe is local docker's own answer about the
+    // daemon container.
+    const probe = localDaemonProbeArgv(cfg);
+    return classifyLocal(cfg, await run(probe.cmd, probe.argv, CONFIG_TIMEOUT_MS), deps.projectDir);
+  }
+  if (cfg.ssh_host.trim() === "") {
     return {
-      kind: "local",
-      cause: "local transport — the daemon runs on this machine, no ssh involved",
-      remedy: "",
+      kind: "unconfigured",
+      cause: deps.unconfigured ?? NO_SSH_HOST_STDERR,
+      remedy: "qcr onboard",
     };
   }
-  const run = deps.run ?? realProbeRunner;
   const exists = deps.exists ?? existsSync;
   const home = deps.home ?? homedir();
   const host = cfg.ssh_host;

package/src/tui/theme.ts

@@ -3,7 +3,7 @@
 // legend — a glance at the color tells the state without reading. Verdicts
 // and anomalies get their own fixed colors.
 import { ACCENT, MUTED } from "./design.js";
-import { STATE_GLYPHS } from "./model.js";
+import { OFFERED_GLYPH, STATE_GLYPHS } from "./model.js";
 import { ESC, rgb } from "./paint.js";
 
 export const FG = {
@@ -78,6 +78,7 @@ export function legendLine(): string {
     [STATE_GLYPHS.queued, "queued", FG.queued],
     [STATE_GLYPHS.awaiting_author, "author", FG.awaiting_author],
     [STATE_GLYPHS.tracked, "tracked", FG.tracked],
+    [OFFERED_GLYPH, "not reviewed", FG.dim],
     ["↻", "stale", FG.accent],
   ];
   return parts

package/src/tui/unwedge.ts

@@ -26,6 +26,7 @@ import type { App } from "./app.js";
 import { sanitizeText } from "./paint.js";
 import type { SshRunner } from "./remote.js";
 import { remoteSandboxRoot, resolveLayout } from "./layout.js";
+import { operatorCommandWriteScriptAt } from "../operatorwrite.js";
 
 /** The commands this channel may produce. Deliberately a closed set: the
  * daemon's whitelist is the authority, and this is the narrower subset that
@@ -94,20 +95,7 @@ export function commandFileName(now: Date, seq: number, client?: string): string
  * (`tests/levers.test.ts`).
  */
 export function operatorCommandWriteScript(cfg: TuiConfig, name: string): string {
-  const root = commandDirFor(cfg);
-  const dir = operatorCommandDirFor(cfg);
-  const tmp = `.${name}.tmp`;
-  return (
-    `[ -d '${root}' ] || { echo 'daemon commands dir ${root} missing - is the daemon running?' >&2; exit 1; }; ` +
-    `mkdir -p '${dir}' || exit 1; ` +
-    `[ ! -L '${dir}' ] || { echo '${dir} is a symlink - refusing to write the operator command' >&2; exit 1; }; ` +
-    `R=$(cd -P '${root}' && pwd -P) || exit 1; ` +
-    `cd -P '${dir}' || exit 1; ` +
-    `[ "$(pwd -P)" = "$R/operator" ] || { echo '${dir} was replaced while writing - refusing to write the operator command' >&2; exit 1; }; ` +
-    `chown -h 0:0 . && chmod 0755 . || exit 1; ` +
-    `find . -maxdepth 1 -name '*.json' -mmin +1440 -delete 2>/dev/null; ` +
-    `rm -f '${tmp}' '${name}' && cat > '${tmp}' && chmod 0644 '${tmp}' && mv '${tmp}' '${name}'`
-  );
+  return operatorCommandWriteScriptAt(commandDirFor(cfg), name);
 }
 
 /** argv for the atomic command write. The payload rides STDIN, never the