@quickchatai/quickreview 1.2.0 → 1.3.2

package/src/home/launch.ts

@@ -0,0 +1,257 @@
+// A bare `qcr`: the home. The app's pinned pi (src/picli.ts), with the plugin
+// and the home's extension loaded, on the person's own pi home.
+//
+//   pi home    the person's own: $PI_CODING_AGENT_DIR as the person set it,
+//              else ~/.pi/agent. The launch never sets it, so the chat, the
+//              panel's login line (which reads the same dir) and every review
+//              use one login.
+//   quiet      no logo, resource list, trust prompt, changelog or model
+//              warning, and nothing written to the person's global pi
+//              settings: the quiet start is project settings in the home's
+//              own working directory (in the app's state home), the per-run
+//              trust flag `--approve`, and an explicit `--model`. The
+//              project settings also carry the pinned pi's version as the
+//              last changelog seen, or pi would record it in the global
+//              settings on a first run.
+//   resume     the sessions live in the state home (`--session-dir`), and
+//              `--continue` opens the most recent one there, or a new one.
+//   tools      `[home] tools = "reviewer"` (the default) names the allowed
+//              tools (src/home/toolnames.ts) and starts no MCP server;
+//              "full" leaves pi's own defaults.
+//   GitHub     the person's own `gh`. In the image (scripts/qcr-host.sh's
+//              home mode) there is no gh config: the wrapper hands the token
+//              over as a file (packages/pi-plugin/src/ghcred.ts), src/cli.ts
+//              takes it at startup, and the home passes it to pi as GH_TOKEN,
+//              in its environment only.
+//
+// `-ne` keeps the person's own extensions out: a plugin they installed in pi
+// themselves would otherwise register its commands twice.
+//
+// Everything effectful is injected; `homeRunDeps()` is the real assembly.
+import { spawnSync } from "node:child_process";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { parse } from "smol-toml";
+import { HOME_DEFAULTS, parseHomeSection, type HomeConfig } from "../config.js";
+import { pluginPackageDir } from "../coreext.js";
+import { locateConfig, stateHome } from "../homes.js";
+import { piCliPath, piPackageDir } from "../picli.js";
+import { HOME_MODEL_ENV, HOME_TOOLS_ENV } from "./adapters.js";
+import { reviewerToolAllowlist } from "./toolnames.js";
+
+type Env = Readonly<Record<string, string | undefined>>;
+
+/** The home's places in the state home. */
+export function homePaths(state: string): { cwd: string; settings: string; sessions: string } {
+  const cwd = join(state, "home");
+  return {
+    cwd,
+    settings: join(cwd, ".pi", "settings.json"),
+    sessions: join(cwd, "sessions"),
+  };
+}
+
+/** The env shim pi loads for the home, in the app at `appRoot`. */
+export function homeExtensionPath(appRoot: string): string {
+  return join(appRoot, "extensions", "cli", "home.ts");
+}
+
+/** The home's project settings, over whatever the file already holds. */
+export function homeProjectSettings(
+  existing: unknown,
+  piVersion: string | null,
+): Record<string, unknown> {
+  const base =
+    typeof existing === "object" && existing !== null && !Array.isArray(existing)
+      ? (existing as Record<string, unknown>)
+      : {};
+  return {
+    ...base,
+    quietStartup: true,
+    ...(piVersion === null ? {} : { lastChangelogVersion: piVersion }),
+  };
+}
+
+export interface HomeLaunchInput {
+  piCli: string;
+  pluginDir: string;
+  appRoot: string;
+  stateHome: string;
+  home: HomeConfig;
+  env: Env;
+  /** A GitHub token handed over to this process, or null: the person's gh. */
+  githubToken?: string | null;
+}
+
+export interface HomeLaunch {
+  /** pi's CLI entry and its arguments, run by this node. */
+  args: string[];
+  cwd: string;
+  env: Record<string, string | undefined>;
+}
+
+/** What a bare `qcr` runs. */
+export function homeLaunch(o: HomeLaunchInput): HomeLaunch {
+  const p = homePaths(o.stateHome);
+  const tools =
+    o.home.tools === "reviewer" ? ["--tools", reviewerToolAllowlist().join(","), "--no-mcp"] : [];
+  return {
+    args: [
+      o.piCli,
+      "--approve",
+      "--no-extensions",
+      "-e",
+      o.pluginDir,
+      "-e",
+      homeExtensionPath(o.appRoot),
+      "--model",
+      o.home.model,
+      ...tools,
+      "--session-dir",
+      p.sessions,
+      "--continue",
+    ],
+    cwd: p.cwd,
+    // PI_CODING_AGENT_DIR passes through as the person set it, or stays unset
+    env: {
+      ...o.env,
+      PI_SKIP_VERSION_CHECK: "1",
+      [HOME_MODEL_ENV]: o.home.model,
+      [HOME_TOOLS_ENV]: o.home.tools,
+      ...(o.githubToken ? { GH_TOKEN: o.githubToken } : {}),
+    },
+  };
+}
+
+export interface HomeRunDeps {
+  env: Env;
+  appRoot: string;
+  stateHome: string;
+  piCli(): string;
+  pluginDir(): string;
+  /** The installed pi's version, or null when it cannot be read. */
+  piVersion(): string | null;
+  /** The GitHub token handed over to this process, or null. */
+  githubToken(): string | null;
+  /** The config's `[home]`; a problem with it is said and the defaults used. */
+  homeConfig(): { home: HomeConfig; problem?: string };
+  readFile(path: string): string;
+  writeFile(path: string, text: string): void;
+  mkdir(path: string): void;
+  /** Run a child with the terminal handed over; its exit code (null: signalled). */
+  run(
+    cmd: string,
+    args: readonly string[],
+    opts: { cwd: string; env: Record<string, string | undefined> },
+  ): { status: number | null; error?: Error };
+  execPath: string;
+  err(line: string): void;
+}
+
+/** A bare `qcr`: open the home. pi's exit code. */
+export function runHome(deps: HomeRunDeps): number {
+  let piCli: string;
+  let pluginDir: string;
+  try {
+    piCli = deps.piCli();
+    pluginDir = deps.pluginDir();
+  } catch (err) {
+    deps.err(`qcr: ${err instanceof Error ? err.message : String(err)}`);
+    return 1;
+  }
+  const { home, problem } = deps.homeConfig();
+  if (problem) deps.err(`qcr: ${problem}; the home opens on its defaults.`);
+  const p = homePaths(deps.stateHome);
+  try {
+    deps.mkdir(p.sessions);
+    deps.mkdir(dirname(p.settings));
+    let existing: unknown = undefined;
+    let before: string | null = null;
+    try {
+      before = deps.readFile(p.settings);
+      existing = JSON.parse(before);
+    } catch {
+      // no settings yet, or not ours to read: written fresh below
+    }
+    const text = `${JSON.stringify(homeProjectSettings(existing, deps.piVersion()), null, 2)}\n`;
+    if (text !== before) deps.writeFile(p.settings, text);
+  } catch (err) {
+    deps.err(
+      `qcr: can't prepare the home in ${p.cwd}: ${err instanceof Error ? err.message : String(err)}`,
+    );
+    return 1;
+  }
+  const launch = homeLaunch({
+    piCli,
+    pluginDir,
+    appRoot: deps.appRoot,
+    stateHome: deps.stateHome,
+    home,
+    env: deps.env,
+    githubToken: deps.githubToken(),
+  });
+  const r = deps.run(deps.execPath, launch.args, { cwd: launch.cwd, env: launch.env });
+  if (r.error) {
+    deps.err(`qcr: pi could not start: ${r.error.message}`);
+    return 1;
+  }
+  return r.status ?? 1;
+}
+
+/** The config's `[home]`, read on its own: the home opens even when the rest
+ * of the config would not load. */
+export function readHomeConfig(
+  env: Env,
+  read: (p: string) => string = (p) => readFileSync(p, "utf8"),
+): { home: HomeConfig; problem?: string } {
+  const path = locateConfig({ env }).path;
+  let raw: string;
+  try {
+    raw = read(path);
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException | null)?.code === "ENOENT")
+      return { home: { ...HOME_DEFAULTS } };
+    return { home: { ...HOME_DEFAULTS }, problem: `can't read ${path}` };
+  }
+  try {
+    return { home: parseHomeSection((parse(raw) as Record<string, unknown>)["home"]) };
+  } catch (err) {
+    return {
+      home: { ...HOME_DEFAULTS },
+      problem: `${path}: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+}
+
+export function homeRunDeps(appRoot: string, env: Env = process.env): HomeRunDeps {
+  return {
+    env,
+    appRoot,
+    stateHome: stateHome(env),
+    piCli: () => piCliPath(),
+    pluginDir: () => pluginPackageDir(),
+    piVersion: () => {
+      try {
+        const pkg = JSON.parse(readFileSync(join(piPackageDir(), "package.json"), "utf8")) as {
+          version?: unknown;
+        };
+        return typeof pkg.version === "string" ? pkg.version : null;
+      } catch {
+        return null;
+      }
+    },
+    // the person's own gh; the image's `qcr home` (src/cli.ts) passes the
+    // token the wrapper handed over
+    githubToken: () => null,
+    homeConfig: () => readHomeConfig(env),
+    readFile: (p) => readFileSync(p, "utf8"),
+    writeFile: (p, t) => writeFileSync(p, t),
+    mkdir: (p) => mkdirSync(p, { recursive: true }),
+    run: (cmd, args, opts) => {
+      const r = spawnSync(cmd, [...args], { stdio: "inherit", cwd: opts.cwd, env: opts.env });
+      return { status: r.status, ...(r.error ? { error: r.error } : {}) };
+    },
+    execPath: process.execPath,
+    err: (l) => console.error(l),
+  };
+}

package/src/home/loginowner.ts

@@ -0,0 +1,248 @@
+// One login per box, as the home sees it: who refreshes
+// the OpenAI login the home signed in to, whether it still works, and the
+// re-login that replaces it safely.
+//
+//   owner     the daemon's refresher holds the login while auto-review runs
+//             on this machine (its single-instance lock, beside auth.json in
+//             the home's own pi agent dir, which the stack mounts:
+//             src/onboard/steps/loginshare.ts). Otherwise the home's pi refreshes it
+//             itself, by pi's own rule: a token inside pi's 5-minute window,
+//             under pi's own lock. While the refresher runs no token gets
+//             near that window, so the home's pi never refreshes: it borrows.
+//   expired   the refresher's record says its refresh fails and the token is
+//             past its expiry (or the grant was refused); or the chat itself
+//             was refused for the login (extensions/home.ts reads pi's error);
+//             or auto-review is paused on it. The login line then says "login
+//             expired", with one key that signs in again.
+//   re-login  pi's own device login (src/home/devicelogin.ts), with the
+//             entrypoint's handover around it (src/loginrefresh/handover.ts):
+//             a running refresher is paused first, and keeps its lock, so its
+//             refresh can never land on top of the new login; the pause is
+//             lifted after, and the refresher re-reads the new login at once,
+//             so auto-review resumes on it.
+//
+// Nothing here reads or prints a token: the refresher's status file carries
+// expiry times and redacted errors only.
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { PI_AUTH_ERROR_RE } from "@quickchatai/pi-quickreview/src/authwatch.js";
+import { holdRefresher, refresherRuns, type HoldOptions } from "../loginrefresh/handover.js";
+import { STATUS_FILE } from "../loginrefresh/refresher.js";
+import { providerLabel, type HomeModel } from "./model.js";
+import {
+  known,
+  unknown,
+  type Known,
+  type LoginHealth,
+  type LoginHold,
+  type LoginOwnerPort,
+} from "./ports.js";
+import {
+  DEVICE_LOGIN_PROVIDERS,
+  loginFailureText,
+  type DeviceCode,
+  type DeviceLoginPort,
+  type LoginFailureKind,
+} from "./setup.js";
+
+/** What the login line says of a login that no longer works. */
+export const LOGIN_EXPIRED = "login expired";
+/** The key that signs in again, while typing (the panel's is `l`). */
+export const RELOGIN_KEY = "alt+l";
+
+type Obj = Record<string, unknown>;
+const isObj = (v: unknown): v is Obj => typeof v === "object" && v !== null && !Array.isArray(v);
+const message = (err: unknown): string => (err instanceof Error ? err.message : String(err));
+
+/** A refresh refused for good: the grant is gone, not a network blip. */
+const REFUSED = /invalid_grant|revoked|refresh_token_(?:reused|expired|invalidated)/i;
+
+/** Why the refresher's record (its loginrefresh.status.json) says the login
+ * no longer works, or null. Pure. */
+export function expiredWhy(record: unknown, now: number): string | null {
+  if (!isObj(record)) return null;
+  const err = record["last_error"];
+  if (typeof err !== "string" || err === "") return null;
+  if (REFUSED.test(err)) return LOGIN_EXPIRED;
+  const expires = typeof record["expires_at"] === "string" ? Date.parse(record["expires_at"]) : NaN;
+  return Number.isFinite(expires) && expires <= now ? LOGIN_EXPIRED : null;
+}
+
+/** An error pi showed in the chat that is the login's (pi-ai's refresh
+ * failure, or the provider refusing the token). */
+export function isLoginError(text: string): boolean {
+  return PI_AUTH_ERROR_RE.test(text) || /OAuth refresh failed/i.test(text);
+}
+
+export interface HostLoginOwnerOptions extends Pick<HoldOptions, "flockBin" | "waitMs"> {
+  /** The home's pi agent dir: its auth.json, and the refresher's files beside it. */
+  loginDir: string;
+  now: () => number;
+  /** Where flock cannot tell: does auto-review's daemon run here? */
+  daemonRuns?: () => Promise<boolean | null>;
+  read?: (p: string) => string;
+}
+
+/** The login in the home's own pi agent dir, beside the refresher that may
+ * hold it. */
+export function hostLoginOwner(o: HostLoginOwnerOptions): LoginOwnerPort {
+  const read = o.read ?? ((p: string) => readFileSync(p, "utf8"));
+  const probe = {
+    ...(o.flockBin ? { flockBin: o.flockBin } : {}),
+    ...(o.daemonRuns ? { refresherRuns: o.daemonRuns } : {}),
+  };
+  return {
+    health: async (): Promise<Known<LoginHealth>> => {
+      const runs = await refresherRuns(o.loginDir, probe);
+      if (runs === null) return unknown("can't tell whether auto-review's login refresher runs");
+      if (!runs) return known({ refresher: "home" });
+      let record: unknown;
+      try {
+        record = JSON.parse(read(join(o.loginDir, STATUS_FILE)));
+      } catch {
+        // it has not written one yet: nothing says the login fails
+        return known({ refresher: "auto-review" });
+      }
+      const why = expiredWhy(record, o.now());
+      const checked =
+        isObj(record) && typeof record["checked_at"] === "string"
+          ? Date.parse(record["checked_at"])
+          : NaN;
+      return known({
+        refresher: "auto-review",
+        ...(why ? { expired: why } : {}),
+        ...(Number.isFinite(checked) ? { checkedAt: checked } : {}),
+      });
+    },
+    hold: (): Promise<LoginHold> =>
+      holdRefresher(o.loginDir, { ...probe, ...(o.waitMs ? { waitMs: o.waitMs } : {}) }),
+  };
+}
+
+// ---- the re-login -----------------------------------------------------------
+
+export interface ReloginOptions {
+  model: HomeModel;
+  /** The box's login: the refresher to pause. Absent: nothing is paused. */
+  owner: LoginOwnerPort | undefined;
+  /** pi's device login, once pi's session exists. */
+  deviceLogin: () => DeviceLoginPort | undefined;
+  onChange?: () => void;
+}
+
+interface Signing {
+  ac: AbortController;
+  code?: DeviceCode;
+  onCode?: (code: DeviceCode) => void;
+}
+
+/** "login expired" → one key, or `home_relogin`: sign in again. */
+export class Relogin {
+  private signing: Signing | null = null;
+  private closed = false;
+
+  constructor(private readonly o: ReloginOptions) {}
+
+  /** A re-login in flight: its code once pi has one. */
+  running(): { code?: DeviceCode } | null {
+    return this.signing === null ? null : this.signing.code ? { code: this.signing.code } : {};
+  }
+
+  private changed(): void {
+    this.o.onChange?.();
+  }
+
+  /** Sign in again. The answer comes once the code is shown (or the login
+   * ended): the sign-in goes on in the background. */
+  async start(): Promise<string> {
+    const m = this.o.model;
+    const s = this.signing;
+    if (s !== null)
+      return s.code
+        ? `Still waiting: open ${s.code.verificationUri} and enter ${s.code.userCode}.`
+        : "The sign-in is starting: the code shows in a moment.";
+    if (this.closed) return "the home has closed";
+    const provider = m.chatProvider();
+    const label = providerLabel(provider);
+    const port = DEVICE_LOGIN_PROVIDERS.has(provider) ? this.o.deviceLogin() : undefined;
+    if (port === undefined) {
+      const why = `sign in to ${label} again with pi's own /login (switch auto-review off first, so its refresher does not write over the new login)`;
+      m.say(`${why[0]!.toUpperCase()}${why.slice(1)}.`, "warn");
+      return why;
+    }
+    const signing: Signing = { ac: new AbortController() };
+    this.signing = signing;
+    this.changed();
+    // the refresher first, when one runs: it keeps its lock and stops writing
+    let hold: LoginHold;
+    try {
+      hold = this.o.owner
+        ? await this.o.owner.hold()
+        : { ok: true, held: false, release: () => {} };
+    } catch (err) {
+      hold = { ok: false, why: message(err) };
+    }
+    if (!hold.ok) {
+      this.signing = null;
+      m.say(`Couldn't sign in again: ${hold.why}. Nothing changed.`, "warn");
+      this.changed();
+      return `the sign-in did not start: ${hold.why}`;
+    }
+    const release = hold.release;
+    const held = hold.held;
+    if (signing.ac.signal.aborted) {
+      release();
+      this.signing = null;
+      return "the home has closed";
+    }
+    m.say(`Signing in to ${label} again with pi's device code.`);
+    let answer!: (text: string) => void;
+    const answered = new Promise<string>((r) => (answer = r));
+    signing.onCode = (c) => {
+      m.say(`Open ${c.verificationUri} and enter the code ${c.userCode}.`);
+      answer(
+        `Open ${c.verificationUri} and enter the code ${c.userCode}. The home finishes the sign-in once you approve it.`,
+      );
+    };
+    void (async () => {
+      let outcome: { ok: true } | { ok: false; kind: LoginFailureKind; why: string };
+      try {
+        outcome = await port.login({
+          provider,
+          signal: signing.ac.signal,
+          onCode: (code) => {
+            signing.code = code;
+            signing.onCode?.(code);
+            this.changed();
+          },
+        });
+      } catch (err) {
+        outcome = { ok: false, kind: "failed", why: message(err) };
+      } finally {
+        // the pause is lifted whatever happened: the refresher re-reads the file
+        release();
+        this.signing = null;
+      }
+      if (outcome.ok) {
+        m.signedInAgain();
+        await m.refresh();
+        m.say(
+          `Signed in to ${label} again.${held ? " Auto-review's refresher has the new login, and auto-review resumes." : ""}`,
+          "ok",
+        );
+        answer(`signed in to ${label} again`);
+      } else {
+        if (outcome.kind !== "cancelled") m.say(loginFailureText(outcome, RELOGIN_KEY), "warn");
+        answer(`the sign-in did not finish: ${outcome.why}`);
+      }
+      this.changed();
+    })();
+    return answered;
+  }
+
+  /** The session ends: a re-login in flight stops, and its pause is lifted. */
+  close(): void {
+    this.closed = true;
+    this.signing?.ac.abort();
+  }
+}

package/src/home/memory.ts

@@ -0,0 +1,176 @@
+// Memory in the home: its own switch, off by default, independent of
+// auto-review. On this machine the memory engine is the compose stack's
+// `memory` service (OpenViking and its local embedder): on is that container
+// running, off is it stopped, with what it learned kept in its volume.
+//
+// Switching it on sets memory up the wizard's way when it never was: the
+// memory step places the root key, the engine is started (it reads that key
+// at boot), the memory step runs again until the engine answers and mints the
+// user keys (memoryPhaseB), then memory_user_keys. On a machine whose
+// stack was never brought up it brings the stack up through switch-on's own
+// steps (never the go-live, and never a confirm) and leaves the daemon as it
+// found it: memory on never switches auto-review on. Switching auto-review
+// off never stops memory (src/home/autoreview.ts stops the daemon alone).
+import type {
+  ChecklistAdapters,
+  SetupChecklist,
+} from "@quickchatai/pi-quickreview/src/setupchecklist.js";
+import { OnboardingEngine, type OnboardAdapters, type ProcessRunner } from "../onboard/engine.js";
+import { BROUGHT_UP_CHOICE_KEY } from "../onboard/steps/bringup.js";
+import {
+  DAEMON_SERVICE,
+  MEMORY_SERVICE,
+  composeArgs,
+  readEnvText,
+} from "../onboard/steps/compose.js";
+import { readEnvKey } from "../onboard/steps/ingress.js";
+import { MEMORY_CHOICE_KEY, MEMORY_STEP_ID, waitsOnServer } from "../onboard/steps/memory.js";
+import { MEMORY_KEYS_STEP_ID } from "../onboard/steps/memorykeys.js";
+import { serviceState } from "./autoreview.js";
+import {
+  known,
+  type Known,
+  type MemoryPort,
+  type MemoryState,
+  type SwitchResult,
+} from "./ports.js";
+import {
+  MACHINE_CHECKS_STEP_ID,
+  memoryPhaseB,
+  runSteps,
+  switchOnInput,
+  switchOnRegistry,
+  type StepsRun,
+  type SwitchOnStepOptions,
+} from "./switchon.js";
+
+/** compose's memory cap when the project `.env` names none
+ * (docker-compose.yml `mem_limit: ${QCR_MEMORY_LIMIT:-4g}`). */
+export const DEFAULT_MEMORY_LIMIT = "4g";
+
+/** "4g" → "up to 4 GB of RAM"; a value compose would not read is said as is. */
+export function ramCostOf(limit: string): string {
+  const m = /^\s*(\d+(?:\.\d+)?)\s*([kmgt])?b?\s*$/i.exec(limit);
+  if (!m) return `up to ${limit.trim()} of RAM`;
+  const unit = { k: "KB", m: "MB", g: "GB", t: "TB" }[(m[2] ?? "").toLowerCase()] ?? "bytes";
+  return `up to ${m[1]} ${unit} of RAM`;
+}
+
+/** The memory engine's state from its container's. */
+export function memoryStateOf(c: Known<"running" | "restarting" | "stopped">): Known<MemoryState> {
+  if (c.kind === "unknown") return c;
+  return known(c.value === "running" ? "on" : c.value === "restarting" ? "starting" : "off");
+}
+
+export interface ComposeMemoryOptions extends SwitchOnStepOptions {
+  root: string;
+  runner: ProcessRunner;
+  stepAdapters: (log: (line: string) => void) => OnboardAdapters;
+  /** The configured repository, for a first bring-up's own-account step. */
+  repo: () => Promise<string | null>;
+  /** Between phase B's tries while the engine starts (tests skip the wait). */
+  sleep?: (ms: number) => Promise<void>;
+}
+
+const firstLine = (s: string): string => s.trim().split("\n")[0]?.trim() || "no output";
+
+/** The memory step's answer when the person turns memory on. */
+const MEMORY_YES = switchOnInput(MEMORY_STEP_ID, {
+  answers: { memory: true, confirmed: false },
+  repo: null,
+});
+
+/**
+ * Memory on, on a stack brought up before. Set up when it never was (or was
+ * declined): phase A places the root key, and when the engine does not run
+ * yet that is all it can do, so the engine is started (it reads the key at
+ * boot) and phase B runs once it answers (memoryPhaseB). Otherwise the engine
+ * is started as it is. Then its user keys, when that step is not done.
+ */
+export async function memoryOnStack<A extends ChecklistAdapters>(
+  e: SetupChecklist<A>,
+  o: Pick<StepsRun<A>, "progress" | "sleep"> & { startMemory: () => Promise<SwitchResult> },
+): Promise<SwitchResult> {
+  const configured = e.list().find((s) => s.id === MEMORY_STEP_ID);
+  let waits = false;
+  if (configured?.status !== "done" || e.choices()[MEMORY_CHOICE_KEY] === "declined") {
+    o.progress?.("Setting memory up…");
+    const r = await e.runStep(MEMORY_STEP_ID, MEMORY_YES);
+    if (!r.ok && !waitsOnServer(r.checks)) return { ok: false, detail: r.failures.join("; ") };
+    waits = !r.ok;
+  }
+  if (waits) {
+    const b = await memoryPhaseB({ ...o, checklist: e }, MEMORY_YES);
+    if (!b.ok) return { ok: false, detail: b.detail };
+  } else {
+    const up = await o.startMemory();
+    if (!up.ok) return up;
+  }
+  const keys = e.list().find((s) => s.id === MEMORY_KEYS_STEP_ID);
+  if (keys && keys.status !== "done" && keys.status !== "disabled") {
+    const r = await e.runStep(MEMORY_KEYS_STEP_ID);
+    if (!r.ok) return { ok: false, detail: `the engine runs, but ${r.failures.join("; ")}` };
+  }
+  return { ok: true, detail: "Memory is on." };
+}
+
+export function composeMemory(o: ComposeMemoryOptions): MemoryPort {
+  const compose = async (args: string[], what: string): Promise<SwitchResult> => {
+    const r = await o.runner.run("docker", composeArgs(o.root, args));
+    return r.code === 0
+      ? { ok: true, detail: what }
+      : {
+          ok: false,
+          detail: `docker compose ${args.join(" ")} exited ${r.code}: ${firstLine(r.stderr || r.stdout)}`,
+        };
+  };
+  const engine = (log: (line: string) => void): OnboardingEngine =>
+    new OnboardingEngine(switchOnRegistry(o), o.stepAdapters(log));
+  const startMemory = (): Promise<SwitchResult> =>
+    compose(["up", "-d", MEMORY_SERVICE], "the memory engine runs");
+
+  return {
+    status: async () => memoryStateOf(await serviceState(o.runner, o.root, MEMORY_SERVICE)),
+    control: {
+      ramCost: () =>
+        ramCostOf(
+          (readEnvKey(readEnvText(o.root), "QCR_MEMORY_LIMIT") ?? "").trim() ||
+            DEFAULT_MEMORY_LIMIT,
+        ),
+      switchOn: async (progress) => {
+        const e = engine((l) => progress?.(l));
+        if (typeof e.choices()[BROUGHT_UP_CHOICE_KEY] !== "string") {
+          // No stack yet: switch-on's steps bring it up with memory, and the
+          // daemon is put back as it was (off), so auto-review stays off.
+          const daemonWas = await serviceState(o.runner, o.root, DAEMON_SERVICE);
+          const checks = await e.runStep(MACHINE_CHECKS_STEP_ID);
+          if (!checks.ok) return { ok: false, detail: checks.failures.join("; ") };
+          const steps: string[] = [];
+          const walked = await runSteps(
+            {
+              checklist: e,
+              memory: true,
+              repo: await o.repo(),
+              startMemory,
+              ...(o.sleep ? { sleep: o.sleep } : {}),
+              ...(progress ? { progress } : {}),
+            },
+            steps,
+          );
+          if (!walked.ok) return { ok: false, detail: walked.detail };
+          if (daemonWas.kind === "known" && daemonWas.value !== "running") {
+            const stopped = await compose(["stop", DAEMON_SERVICE], "");
+            if (!stopped.ok) return { ok: false, detail: `memory is on, but ${stopped.detail}` };
+          }
+          return { ok: true, detail: "Memory is on." };
+        }
+        return memoryOnStack(e, {
+          startMemory,
+          ...(o.sleep ? { sleep: o.sleep } : {}),
+          ...(progress ? { progress } : {}),
+        });
+      },
+      switchOff: () => compose(["stop", MEMORY_SERVICE], "Memory is off. What it learned is kept."),
+    },
+  };
+}