@quickchatai/quickreview 1.1.0 → 1.3.1

package/src/onboard/steps/llmauth.ts

@@ -130,19 +130,56 @@ export function hostAuthJsonPath(home: string): string {
  * without its slash, and the entry pi writes into auth.json on /login. */
 const OAUTH_PROVIDER = OAUTH_PREFIX.replace(/\/$/, "");
 
-/** Does this host's auth.json hold a ChatGPT (openai-codex) OAuth login? The
- * file existing proves nothing: pi keeps every provider's login there, and a
- * logged-out pi can leave `{}` behind. Unreadable or malformed ⇒ false. */
-export function hostHasOAuthLogin(authPath: string): boolean {
+/** pi's /login labels for the two ChatGPT subscription logins (pi 1.4.0).
+ * VERIFY-ON-PIN. */
+export const OAUTH_LOGIN_LABEL = "OpenAI Codex (legacy)";
+export const CHATGPT_LOGIN_LABEL = "Sign in with ChatGPT";
+
+/** pi 1.4's newer "Sign in with ChatGPT" on the `openai` provider, which an
+ * OpenAI API key stored by /login also lands on. Every model spec reaches pi
+ * through the credential-aware route (packages/pi-plugin/src/modelroute.ts),
+ * so an `openai-codex/` model runs on this login when it is the one there:
+ * any OpenAI login serves the review. VERIFY-ON-PIN. */
+const CHATGPT_PROVIDER = API_PREFIX.replace(/\/$/, "");
+
+/** Where to sign in, and which logins count: what every "log in" message
+ * says, in pi 1.4.0's /login labels. */
+export const ANY_OPENAI_LOGIN =
+  `any OpenAI login works: at pi's /login pick "Sign in with an account", then "OpenAI" (${CHATGPT_LOGIN_LABEL}) ` +
+  `or "${OAUTH_LOGIN_LABEL}"; or "Sign in with an API key", then "OpenAI"`;
+
+/** The OpenAI logins in a pi auth.json: each ChatGPT subscription login (the
+ * shipped `openai-codex` and pi 1.4's newer `openai`), and whether an OpenAI
+ * API key was stored by /login (`{"openai":{"type":"api_key","key":…}}`).
+ * The file existing proves nothing: pi keeps every provider's login there,
+ * and a logged-out pi can leave `{}` behind. Unreadable ⇒ none. */
+export function hostOpenAILogins(authPath: string): { oauth: string[]; apiKey: boolean } {
   try {
     const parsed = JSON.parse(readFileSync(authPath, "utf8")) as Record<string, unknown>;
-    const cred = parsed?.[OAUTH_PROVIDER] as Record<string, unknown> | undefined;
-    return typeof cred === "object" && cred !== null && cred.type === "oauth";
+    const cred = (provider: string): Record<string, unknown> | null => {
+      const c = parsed?.[provider];
+      return typeof c === "object" && c !== null ? (c as Record<string, unknown>) : null;
+    };
+    const key = cred(CHATGPT_PROVIDER);
+    return {
+      oauth: [OAUTH_PROVIDER, CHATGPT_PROVIDER].filter((p) => cred(p)?.type === "oauth"),
+      apiKey: key?.type === "api_key" && typeof key.key === "string" && key.key.trim() !== "",
+    };
   } catch {
-    return false;
+    return { oauth: [], apiKey: false };
   }
 }
 
+/** Does this host's auth.json hold a ChatGPT subscription login (either one)? */
+export function hostHasOAuthLogin(authPath: string): boolean {
+  return hostOAuthProviders(authPath).length > 0;
+}
+
+/** Every ChatGPT subscription login in this auth.json. Unreadable ⇒ none. */
+export function hostOAuthProviders(authPath: string): string[] {
+  return hostOpenAILogins(authPath).oauth;
+}
+
 function hostHome(): string {
   return process.env.HOME ?? homedir();
 }
@@ -356,18 +393,24 @@ export type LoginState =
   "absent" | "no-pi-volume" | "stopped" | "no-auth" | "wrong-provider" | "ok" | "undetectable";
 
 /**
- * The in-container login check: the same question `hostHasOAuthLogin` asks of
- * the host — is there an `openai-codex` entry of type `oauth`? — asked by the
- * container's own node, so only an exit code ever leaves it (never a token,
- * which on the VM route would otherwise cross ssh). Exit 0 = logged in,
- * 3 = no auth.json / empty, 4 = an auth.json without that login (`{}`, or
- * another provider picked at pi's /login menu). Anything else (no node) is
- * undetectable, never a pass.
+ * The in-container login check: the same question `hostOpenAILogins` asks of
+ * the host — is there an OpenAI login? — asked by the container's own node, so
+ * only an exit code ever leaves it (never a token, which on the VM route would
+ * otherwise cross ssh). Any OpenAI login counts, because the engine runs the
+ * same model on whichever exists (packages/pi-plugin/src/modelroute.ts): an
+ * `openai-codex` or `openai` entry of type `oauth`, or an `openai` API key.
+ * Exit 0 = logged in, 3 = no auth.json / empty, 4 = an auth.json without an
+ * OpenAI login (`{}`, or another provider picked at pi's /login menu).
+ * Anything else (no node) is undetectable, never a pass.
  */
 export const CONTAINER_LOGIN_SCRIPT =
   "const fs=require('fs');let t='';try{t=fs.readFileSync(process.argv[1],'utf8')}catch{process.exit(3)}" +
   "if(!t.trim())process.exit(3);let a;try{a=JSON.parse(t)}catch{process.exit(4)}" +
-  `const c=a&&a[${JSON.stringify(OAUTH_PROVIDER)}];process.exit(c&&typeof c==='object'&&c.type==='oauth'?0:4)`;
+  "const c=(k)=>{const v=a&&a[k];return !!v&&typeof v==='object'?v:null};" +
+  "const o=(k)=>c(k)?.type==='oauth';" +
+  `const key=c(${JSON.stringify(CHATGPT_PROVIDER)});` +
+  "const k=!!key&&key.type==='api_key'&&typeof key.key==='string'&&key.key.trim()!=='';" +
+  `process.exit(o(${JSON.stringify(OAUTH_PROVIDER)})||o(${JSON.stringify(CHATGPT_PROVIDER)})||k?0:4)`;
 
 export interface LoginProbe {
   state: LoginState;
@@ -483,8 +526,8 @@ function loginCheck(
         name,
         ok: false,
         detail:
-          `${label}: auth.json on the pi home (${probe.mount}) holds no ChatGPT (${OAUTH_PROVIDER}) OAuth login — ` +
-          "a /login to another provider does not count. Attach and log in with the ChatGPT option: " +
+          `${label}: auth.json on the pi home (${probe.mount}) holds no OpenAI login — ` +
+          `a /login to another provider does not count. Attach and log in (${ANY_OPENAI_LOGIN}): ` +
           `${steps}.`,
       };
     case "no-pi-volume":
@@ -575,7 +618,7 @@ export function companionSessionName(configText: string): string {
 
 // ---- the operator-facing text ----------------------------------------------
 
-export const ROUTE_QUESTION =
+const ROUTE_CHOICES =
   "How should the review sessions authenticate to OpenAI?\n" +
   "  1) oauth — a ChatGPT subscription. Cost is your plan, flat. The catch: pi's OAuth tokens live in the\n" +
   "     pi home of whichever process logged in and DO NOT transfer between this host and the containers, so\n" +
@@ -583,8 +626,29 @@ export const ROUTE_QUESTION =
   "     companion container. Each is guided when its surface first needs it.\n" +
   "  2) api — one OpenAI API key, metered per token. One paste covers the daemon and its review sessions (the daemon\n" +
   "     container's entrypoint exports the key file as OPENAI_API_KEY), and the wizard rewrites all five model strings\n" +
-  "     for you. The companion container is not handed the key: it keeps its own login.\n" +
-  "Answer 1/oauth or 2/api:";
+  "     for you. The companion container is not handed the key: it keeps its own login.\n";
+
+export const ROUTE_QUESTION = `${ROUTE_CHOICES}Answer 1/oauth or 2/api:`;
+
+/** The same question where no prompter can ask it: the pi-driven wizard
+ * passes the operator's answer as this step's `route` input. */
+export const ROUTE_INPUT_QUESTION =
+  `${ROUTE_CHOICES}Ask the operator which one, then run this step again with route: "oauth" or route: "api". ` +
+  "Never ask them to type the answer anywhere else: there is no other prompt.";
+
+/** The step's input schema: the operator's route answer (pi-driven flow). */
+const ROUTE_PARAMETERS = {
+  type: "object",
+  properties: {
+    route: {
+      type: "string",
+      enum: ["oauth", "api"],
+      description:
+        'The operator\'s answer: "oauth" (a ChatGPT subscription) or "api" (an OpenAI API key). ' +
+        "Omit it to keep the recorded route, or to read both options out.",
+    },
+  },
+} as const;
 
 export const KEY_QUESTION = `paste the OpenAI API key (it is written straight to the ${OPENAI_KEY_FILE} secrets file, 0600, never to a command line):`;
 
@@ -635,12 +699,16 @@ interface RouteDecision {
  *      route is what pi will really use, so the config must say so;
  *   3. otherwise a valid key file;
  *   4. otherwise the previously recorded route;
- *   5. otherwise: no answer yet — the step goes red with the choice text.
+ *   5. otherwise an OpenAI API key this host's pi stored at /login: the
+ *      wizard's own session runs on a key, so the api route is the one in use
+ *      (the daemon still takes its key from the secrets file);
+ *   6. otherwise: no answer yet — the step goes red with the choice text.
  */
 async function decideRoute(
   ctx: StepContext,
   keyFile: KeyFileState,
   hostLogin: boolean,
+  hostApiKey = false,
 ): Promise<RouteDecision> {
   const prompter = ctx.adapters.prompter;
   if (prompter) {
@@ -652,15 +720,24 @@ async function decideRoute(
       return { route: kept, source: "kept the recorded route (empty answer)" };
     return { route: null, source: `did not understand the answer — reply 1/oauth or 2/api` };
   }
+  const answered = typeof ctx.input.route === "string" ? parseRouteAnswer(ctx.input.route) : null;
+  if (answered) return { route: answered, source: "you chose it" };
   if (hostLogin)
     return {
       route: "oauth",
-      source: "a completed pi login is on this host, and pi prefers auth.json over any env key",
+      source:
+        "a completed ChatGPT login is on this host, and pi prefers auth.json over any env key",
     };
   if (keyFile.valid)
     return { route: "api", source: `a valid ${OPENAI_KEY_FILE} is in the secrets dir` };
   const kept = recordedRoute(ctx);
   if (kept) return { route: kept, source: "the recorded route" };
+  if (hostApiKey)
+    return {
+      route: "api",
+      source:
+        "this host's pi signed in with an OpenAI API key (its /login), and holds no ChatGPT login",
+    };
   return { route: null, source: "nothing on disk says which route this installation uses" };
 }
 
@@ -793,20 +870,22 @@ async function oauthLoginChecks(
 ): Promise<CheckResult[]> {
   const checks: CheckResult[] = [];
   const authPath = hostAuthJsonPath(home);
-  const hostOk = hostHasOAuthLogin(authPath);
+  const logins = hostOpenAILogins(authPath);
+  const hostOk = logins.oauth.length > 0 || logins.apiKey;
   checks.push(
     hostOk
       ? {
           name: "wizard_login",
           ok: true,
-          detail: `this host's pi is logged in (${authPath}) — login 1 of 3 done`,
+          detail: `this host's pi is logged in (${authPath}, ${[...logins.oauth, ...(logins.apiKey ? ["an OpenAI API key"] : [])].join(" + ")}) — login 1 of 3 done`,
         }
       : {
           name: "wizard_login",
           ok: false,
           detail:
-            `no ChatGPT (${OAUTH_PROVIDER}) OAuth login in this host's pi (${authPath}). Log in from this very session — type /login at pi's input line ` +
-            "and follow the browser flow — then run this step again. This is login 1 of 3; the two container logins come later.",
+            `no OpenAI login in this host's pi (${authPath}). Log in from this very session — type /login at pi's input line ` +
+            `(${ANY_OPENAI_LOGIN}) and follow its flow — then run this step again. This is login 1 of 3; ` +
+            "the two container logins come later.",
         },
   );
   const runner = ctx.adapters.runner;
@@ -852,6 +931,7 @@ export function llmAuthStep(opts: { transport?: TransportOptions } = {}): Onboar
     // After preflight (10) and the topology question (20): the spec's second
     // question, and everything after it assumes a decided route.
     order: 30,
+    parameters: ROUTE_PARAMETERS,
 
     async run(ctx): Promise<StepReport> {
       const home = hostHome();
@@ -878,14 +958,19 @@ export function llmAuthStep(opts: { transport?: TransportOptions } = {}): Onboar
         rootOf(ctx.adapters),
       );
       let keyFile = readKeyFileState(secretsDir);
-      const hostLogin = hostHasOAuthLogin(hostAuthJsonPath(home));
+      const logins = hostOpenAILogins(hostAuthJsonPath(home));
+      const hostLogin = logins.oauth.length > 0;
 
-      const decision = await decideRoute(ctx, keyFile, hostLogin);
+      const decision = await decideRoute(ctx, keyFile, hostLogin, logins.apiKey);
       if (decision.route === null) {
-        checks.push({ name: "route", ok: false, detail: `${decision.source}.\n${ROUTE_QUESTION}` });
+        const question = ctx.adapters.prompter ? ROUTE_QUESTION : ROUTE_INPUT_QUESTION;
+        checks.push({ name: "route", ok: false, detail: `${decision.source}.\n${question}` });
         return { ok: false, checks };
       }
       const route = decision.route;
+      // An answer is recorded at once, so a re-run (a login still owed, say)
+      // keeps it without asking again.
+      if (decision.source === "you chose it") ctx.recordChoice(CHOICE_KEYS.authRoute, route);
       checks.push({ name: "route", ok: true, detail: `${route} route — ${decision.source}` });
 
       let credentialChanged =

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
@@ -700,6 +716,15 @@ function serverUnreachableDetail(ctx: StepContext, base: string, why: string): s
   const flags = forwardFlags(ctx);
   const cmd = (sub: string): string =>
     `\`cd ${root} && node scripts/companion-memory-forward.mjs ${sub} ${flags}\``;
+  if (topologyOf(ctx.choices) !== "vm")
+    return (
+      `no OpenViking answering at ${base} (${why}). The root key is in place, which is what the daemon needs at boot. ` +
+      "Before the bring-up that is expected, and nothing is needed from you: the bring-up step starts the memory engine, " +
+      "and the memory_user_keys step after it reaches it through a memory forward the wizard opens itself, then mints " +
+      "the two user keys. If the stack is already up, the memory container is the thing to check " +
+      "(`docker compose ps memory`, `docker compose logs memory`); a forward that stays up outside the wizard is " +
+      `${cmd("install")} (the systemd unit) or \`qcr tui\`, which starts one.`
+    );
   return (
     `no OpenViking answering at ${base} (${why}). The root key is in place, which is what the daemon needs at boot. ` +
     "The memory engine listens only on its own container's loopback (the memory sidecar on the laptop route), so this machine reaches it through the memory " +
@@ -896,7 +921,7 @@ export function memoryStep(opts: MemoryStepOptions = {}): OnboardingStep {
     };
   };
 
-  return {
+  const step: OnboardingStep = {
     id: MEMORY_STEP_ID,
     title: "Memory: mint, place and confine the OpenViking keys",
     explain:
@@ -1000,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.`
@@ -1216,6 +1241,54 @@ export function memoryStep(opts: MemoryStepOptions = {}): OnboardingStep {
       return { ok: checks.every((c) => c.ok), checks };
     },
   };
+
+  // On the compose route the engine is reachable from this machine only
+  // through the memory forward, and the wizard runs before any TUI has opened
+  // one: each call holds one open for its own duration (adopting a running
+  // forward, closing one it started). A declined memory needs no server.
+  const withForward = async (
+    ctx: StepContext,
+    body: () => Promise<StepReport>,
+  ): Promise<StepReport> => {
+    const open = ctx.adapters.memoryForward;
+    const declined =
+      ctx.input.choice === "declined" ||
+      (ctx.input.choice === undefined && ctx.choices[MEMORY_CHOICE_KEY] === "declined");
+    if (!open || declined || topologyOf(ctx.choices) === "vm") return body();
+    const facts = remoteFactsFor(ctx.adapters, ctx.choices);
+    let forward: Awaited<ReturnType<typeof open>> = null;
+    try {
+      forward = await open({
+        baseUrl: resolvePaths(opts, ctx).base,
+        repoRoot: rootOf(ctx.adapters),
+        container: facts.memoryContainer,
+        sudoDocker: facts.sudo,
+        log: (line) => ctx.adapters.log?.(line),
+      });
+    } catch {
+      forward = null;
+    }
+    try {
+      const report = await body();
+      return forward?.started
+        ? {
+            ...report,
+            checks: [
+              { name: "memory-forward", ok: true, detail: forward.detail },
+              ...report.checks,
+            ],
+          }
+        : report;
+    } finally {
+      forward?.stop();
+    }
+  };
+
+  return {
+    ...step,
+    run: (ctx) => withForward(ctx, () => step.run(ctx)),
+    verify: (ctx) => withForward(ctx, () => step.verify(ctx)),
+  };
 }
 
 /**