@quickchatai/quickreview 1.1.0 → 1.3.1

package/src/onboard/engine.ts

@@ -1,26 +1,49 @@
-// OnboardingEngine — the seam of the onboarding wizard: a checklist state
-// machine plus deterministic step implementations behind injected adapters.
-// pi is a thin driver over this engine (extensions/onboarding.ts registers one
-// tool per step); the engine
-// itself is fully drivable from tests and from a non-LLM fallback entry, and
-// nothing in here touches the network, Docker, or a real pi except through
-// the adapters.
+// OnboardingEngine: the onboarding wizard's checklist, the plugin's setup
+// checklist (@quickchatai/pi-quickreview/src/setupchecklist.ts, the step registry
+// and its engine) bound to this app's adapters and state. pi is a thin
+// driver over it (extensions/onboarding.ts registers one tool per step); the
+// engine itself is fully drivable from tests and from a non-LLM fallback
+// entry, and nothing in here touches the network, Docker, or a real pi except
+// through the adapters.
 //
-// Resumability contract:
-//   - checklist state persists to state/onboarding/checklist.json after every
-//     step, tmp+rename atomic (the verdicts.ts convention);
-//   - startup reconciles claimed state against reality: a step claimed done is
-//     re-verified with its verify(), never trusted from the file alone;
-//   - a fully-done checklist re-runs as verify-only (the wizard doubles as a
-//     diagnostic);
-//   - a corrupt/unreadable checklist degrades to a fresh one (the resume
-//     re-verifies everything anyway) — never a crash.
-//
-// The finish path writes the first-run marker state/companion/first-run.json
-// ({"completed_at": "<iso>"}) exactly once — the contract the companion's
-// first-run greeting consumes. Keep the path and shape stable.
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
-import { basename, dirname, join, resolve } from "node:path";
+// What this module adds to the core's checklist:
+//   - the wizard's adapter set (OnboardAdapters) and its step type;
+//   - where the checklist lives: state/onboarding/checklist.json, tmp+rename
+//     atomic, re-verified on resume (the core's resumability contract);
+//   - the finish path's first-run marker, state/companion/first-run.json
+//     ({"completed_at": "<iso>"}), written exactly once: the contract the
+//     companion's first-run greeting consumes. Keep the path and shape
+//     stable.
+import {
+  SetupChecklist,
+  checklistCompleteNow,
+  readChecklistFile,
+  writeAtomic,
+  type ChecklistAdapters,
+  type ChecklistFile,
+  type SetupStep,
+  type StepContext as ChecklistStepContext,
+  type StepRegistry,
+  type VerifyAllResult,
+} from "@quickchatai/pi-quickreview/src/setupchecklist.js";
+import type { StepForward, StepForwardRequest } from "./stepforward.js";
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+export {
+  CHECKLIST_VERSION,
+  failures,
+  readTextOrNull,
+  writeAtomic,
+  type CheckResult,
+  type ChecklistFile,
+  type ReconcileReport,
+  type StepRecord,
+  type StepReport,
+  type StepRunResult,
+  type StepStatusLine,
+  type VerifyAllResult,
+} from "@quickchatai/pi-quickreview/src/setupchecklist.js";
 
 // ---- adapters ---------------------------------------------------------------
 
@@ -40,7 +63,7 @@ export interface ProcessRunner {
  * fake every field; extensions/onboarding.ts builds the real set. Steps use
  * fetch (manifest exchange, health probes) and prompter (non-LLM fallback
  * entry) as they need them; preflight needs neither. */
-export interface OnboardAdapters {
+export interface OnboardAdapters extends ChecklistAdapters {
   /** HTTP seam (GitHub App manifest exchange, health endpoints, …). */
   fetch: typeof fetch;
   runner: ProcessRunner;
@@ -60,101 +83,26 @@ export interface OnboardAdapters {
    * so no step builds a config path itself. */
   paths: { stateDir: string; configPath: string };
   log?: (line: string) => void;
+  /** Opens the local memory forward for one step call (src/onboard/stepforward.ts):
+   * the compose route's memory engine is reachable from this machine only
+   * through it. The real assembly sets it; absent (every test), no forward is
+   * opened and the step sees whatever already listens. */
+  memoryForward?: (req: StepForwardRequest) => Promise<StepForward | null>;
 }
 
 // ---- step vocabulary --------------------------------------------------------
 
-export interface CheckResult {
-  name: string;
-  ok: boolean;
-  detail: string;
-}
-
-/** What run() and verify() both return. `data` (run only) is persisted onto
- * the step's checklist record and handed back as ctx.data on later calls. */
-export interface StepReport {
-  ok: boolean;
-  checks: CheckResult[];
-  data?: Record<string, unknown>;
-}
-
-export interface StepContext {
-  adapters: OnboardAdapters;
-  /** The tool call's inputs — the operator's answer to a step that asks one
-   * (`{}` for a step that declares no `parameters`, and always on verify()).
-   * A step that needs an answer and does not get one must return a refusal
-   * naming the options, never a guess: the wizard offers, the operator picks. */
-  input: Readonly<Record<string, unknown>>;
-  /** Recorded operator choices (topology, auth route, captured uid, …). */
-  choices: Readonly<Record<string, unknown>>;
-  /** This step's persisted data from a previous run ({} on first run). */
-  data: Readonly<Record<string, unknown>>;
-  /** Record an operator choice / derived fact for later steps (persisted with
-   * the step result). */
-  recordChoice(key: string, value: unknown): void;
-}
+export type StepContext = ChecklistStepContext<OnboardAdapters>;
 
 /**
  * One onboarding step (the registered set is defaultSteps in
- * src/onboard/steps/index.ts); the interface is the extension point:
- *   - `id` must be tool-name-safe ([a-z][a-z0-9_]*) — the pi extension
- *     registers each step as tool `onboard_<id>`;
- *   - `explain` is the teach-text the guide relays before running the step;
- *   - `enabled` gates on recorded choices (e.g. the VM route's steps are
- *     disabled on the laptop topology); absent ⇒ always enabled;
- *   - `run` performs the step; `verify` re-checks its outcome against reality
- *     and must be safe to call any number of times.
+ * src/onboard/steps/index.ts): the core's SetupStep over the wizard's
+ * adapters. The pi extension registers each step as tool `onboard_<id>`.
  */
-export interface OnboardingStep {
-  id: string;
-  title: string;
-  explain: string;
-  /** Ascending display/registration order. */
-  order: number;
-  /** JSON-schema object the step's pi tool declares, for steps that need the
-   * operator's answer (a choice, a hostname). Absent ⇒ the tool takes no
-   * input, which is the common case. */
-  parameters?: unknown;
-  enabled?(choices: Readonly<Record<string, unknown>>): boolean;
-  run(ctx: StepContext): Promise<StepReport>;
-  verify(ctx: StepContext): Promise<StepReport>;
-}
-
-export function failures(checks: readonly CheckResult[]): string[] {
-  return checks.filter((c) => !c.ok).map((c) => `${c.name}: ${c.detail}`);
-}
+export type OnboardingStep = SetupStep<OnboardAdapters>;
 
 // ---- checklist file ---------------------------------------------------------
 
-export const CHECKLIST_VERSION = 1;
-
-export interface StepRecord {
-  status: "pending" | "done";
-  completed_at: string | null;
-  /** Last successful re-verification (resume / finish). */
-  verified_at: string | null;
-  /** Why a claimed-done step was demoted, or other engine notes. */
-  note: string | null;
-  data: Record<string, unknown>;
-}
-
-export interface ChecklistFile {
-  version: number;
-  created_at: string;
-  updated_at: string;
-  /** Set exactly once, by finish() when every enabled step verifies green.
-   * History — when onboarding first finished; it never moves and never clears. */
-  completed_at: string | null;
-  /** When a completed checklist stopped verifying (a demotion, a failed run,
-   * a refused finish, a newly-enabled unfinished step, a step run again —
-   * a run changes what the full verification checked); null/absent while the
-   * completion still holds. A green finish() clears it. Whether onboarding is
-   * complete now is `completed_at` set and this unset. */
-  reopened_at?: string | null;
-  choices: Record<string, unknown>;
-  steps: Record<string, StepRecord>;
-}
-
 export function checklistPath(stateDir: string): string {
   return join(stateDir, "onboarding", "checklist.json");
 }
@@ -165,32 +113,9 @@ export function firstRunMarkerPath(stateDir: string): string {
   return join(stateDir, "companion", "first-run.json");
 }
 
-function isPlainObject(v: unknown): v is Record<string, unknown> {
-  return typeof v === "object" && v !== null && !Array.isArray(v);
-}
-
 /** Read the checklist; null when absent or unreadable (both mean "fresh"). */
 export function readChecklist(stateDir: string): ChecklistFile | null {
-  const path = checklistPath(stateDir);
-  if (!existsSync(path)) return null;
-  try {
-    const raw = JSON.parse(readFileSync(path, "utf8")) as unknown;
-    if (typeof raw !== "object" || raw === null) return null;
-    const file = raw as ChecklistFile;
-    // Every field the engine dereferences is checked here: a file that parses
-    // but lacks one (hand-edited, foreign) would otherwise throw out of a
-    // step predicate or record() on every call — a wedge, not a fresh start.
-    if (typeof file.version !== "number") return null;
-    if (!isPlainObject(file.choices)) return null;
-    if (file.completed_at !== null && typeof file.completed_at !== "string") return null;
-    if (!isPlainObject(file.steps)) return null;
-    for (const rec of Object.values(file.steps)) {
-      if (!isPlainObject(rec) || !isPlainObject(rec.data)) return null;
-    }
-    return file;
-  } catch {
-    return null;
-  }
+  return readChecklistFile(checklistPath(stateDir));
 }
 
 /** Does the checklist file say onboarding finished? The CLI's post-exit
@@ -198,13 +123,7 @@ export function readChecklist(stateDir: string): ChecklistFile | null {
  * re-verification, so "the file says so" is a verified claim). */
 export function checklistComplete(stateDir: string): boolean {
   const file = readChecklist(stateDir);
-  return file !== null && completeNow(file);
-}
-
-/** Is onboarding complete NOW: finished once, and not reopened since. The one
- * reading of the two fields, for the file on disk and the engine's copy. */
-function completeNow(file: Pick<ChecklistFile, "completed_at" | "reopened_at">): boolean {
-  return typeof file.completed_at === "string" && !file.reopened_at;
+  return file !== null && checklistCompleteNow(file);
 }
 
 /** `<sandbox root>` — the parent of `paths.stateDir`, by the adapters'
@@ -213,306 +132,36 @@ export function sandboxRoot(paths: { readonly stateDir: string }): string {
   return resolve(paths.stateDir, "..");
 }
 
-/** tmp+rename atomic write — the one writer every onboarding file write goes
- * through (the checklist, config.toml, .env, the inventory): a reader, the
- * daemon's own loader one bind mount away included, never sees a half-written
- * file, and an interrupted write leaves the previous file whole. */
-export function writeAtomic(path: string, content: string): void {
-  mkdirSync(dirname(path), { recursive: true });
-  const tmp = join(dirname(path), `.${basename(path)}.onboard.tmp`);
-  writeFileSync(tmp, content);
-  renameSync(tmp, path);
-}
-
-/** A file's text, or null when it cannot be read for any reason. For a read
- * where only ABSENCE may be null, read it yourself. */
-export function readTextOrNull(path: string): string | null {
-  try {
-    return readFileSync(path, "utf8");
-  } catch {
-    return null;
-  }
-}
-
 // ---- engine -----------------------------------------------------------------
 
-export interface StepStatusLine {
-  id: string;
-  title: string;
-  explain: string;
-  status: "pending" | "done" | "disabled";
-  note: string | null;
-}
-
-export interface ReconcileReport {
-  /** Claimed-done steps whose verify() held. */
-  verified: string[];
-  /** Claimed-done steps whose verify() failed — demoted to pending. */
-  demoted: Array<{ id: string; failures: string[] }>;
-}
-
-export interface StepRunResult {
-  id: string;
-  ok: boolean;
-  checks: CheckResult[];
-  failures: string[];
-}
-
-export interface VerifyAllResult {
-  ok: boolean;
-  results: Array<{ id: string; ok: boolean; failures: string[] }>;
-}
-
 export type FinishResult =
   | { ok: true; completed_at: string; marker_written: boolean }
   | { ok: false; results: VerifyAllResult["results"] };
 
-export class OnboardingEngine {
-  private readonly registry: OnboardingStep[];
-  private checklist: ChecklistFile;
-
+export class OnboardingEngine extends SetupChecklist<OnboardAdapters> {
   constructor(
-    steps: OnboardingStep[],
-    private readonly adapters: OnboardAdapters,
+    steps: StepRegistry<OnboardAdapters> | readonly OnboardingStep[],
+    adapters: OnboardAdapters,
   ) {
-    this.registry = [...steps].sort((a, b) => a.order - b.order);
-    const loaded = readChecklist(adapters.paths.stateDir);
-    if (loaded === null && existsSync(checklistPath(adapters.paths.stateDir))) {
-      adapters.log?.(
-        "onboarding: checklist file unreadable — starting fresh (recorded choices and step progress were reset)",
-      );
-    }
-    this.checklist = loaded ?? this.fresh();
-  }
-
-  private fresh(): ChecklistFile {
-    const now = this.adapters.clock().toISOString();
-    return {
-      version: CHECKLIST_VERSION,
-      created_at: now,
-      updated_at: now,
-      completed_at: null,
-      choices: {},
-      steps: {},
-    };
-  }
-
-  private save(): void {
-    this.checklist.updated_at = this.adapters.clock().toISOString();
-    writeAtomic(
-      checklistPath(this.adapters.paths.stateDir),
-      `${JSON.stringify(this.checklist, null, 2)}\n`,
-    );
-  }
-
-  private record(id: string): StepRecord {
-    const existing = this.checklist.steps[id];
-    if (existing) return existing;
-    const created: StepRecord = {
-      status: "pending",
-      completed_at: null,
-      verified_at: null,
-      note: null,
-      data: {},
-    };
-    this.checklist.steps[id] = created;
-    return created;
-  }
-
-  private ctxFor(id: string, input: Record<string, unknown> = {}): StepContext {
-    return {
-      adapters: this.adapters,
-      input,
-      choices: this.checklist.choices,
-      data: this.record(id).data,
-      recordChoice: (key, value) => {
-        this.checklist.choices[key] = value;
-      },
-    };
-  }
-
-  /** The registered steps, in order (the pi tools register off this). */
-  stepDefs(): readonly OnboardingStep[] {
-    return this.registry;
-  }
-
-  private enabled(step: OnboardingStep): boolean {
-    return step.enabled ? step.enabled(this.checklist.choices) : true;
-  }
-
-  choices(): Readonly<Record<string, unknown>> {
-    return this.checklist.choices;
-  }
-
-  isComplete(): boolean {
-    return completeNow(this.checklist);
-  }
-
-  /** A completed checklist no longer verifies: withdraw the current-completion
-   * claim (the post-exit handoff reads it) without touching the history. */
-  private reopen(): void {
-    if (this.checklist.completed_at === null || this.checklist.reopened_at) return;
-    this.checklist.reopened_at = this.adapters.clock().toISOString();
-  }
-
-  list(): StepStatusLine[] {
-    return this.registry.map((step) => {
-      const rec = this.checklist.steps[step.id];
-      return {
-        id: step.id,
-        title: step.title,
-        explain: step.explain,
-        status: this.enabled(step) ? (rec?.status ?? "pending") : "disabled",
-        note: rec?.note ?? null,
-      };
-    });
+    super(steps, adapters, { file: checklistPath(adapters.paths.stateDir) });
   }
 
   /**
-   * Resume: re-verify every enabled claimed-done step against reality. A step
-   * whose verify() fails is demoted to pending with the failures in its note —
-   * the file's claim is never trusted alone. A fully-done checklist therefore
-   * re-runs as verify-only. Persists once at the end.
-   */
-  async reconcile(): Promise<ReconcileReport> {
-    const report: ReconcileReport = { verified: [], demoted: [] };
-    for (const step of this.registry) {
-      if (!this.enabled(step)) continue;
-      const rec = this.checklist.steps[step.id];
-      if (!rec || rec.status !== "done") {
-        this.reopen();
-        continue;
-      }
-      const outcome = await this.safeVerify(step);
-      if (outcome.ok) {
-        rec.verified_at = this.adapters.clock().toISOString();
-        report.verified.push(step.id);
-      } else {
-        const fails = failures(outcome.checks);
-        rec.status = "pending";
-        rec.note = `re-verification failed: ${fails.join("; ") || "unknown"}`;
-        this.reopen();
-        report.demoted.push({ id: step.id, failures: fails });
-      }
-    }
-    this.save();
-    return report;
-  }
-
-  /** Run one step, optionally with the operator's answer (`input`, the pi
-   * tool's params). Unknown/disabled ids are refusals-as-answers, never
-   * throws (the caller is an LLM tool belt). Persists after the step. */
-  async runStep(id: string, input: Record<string, unknown> = {}): Promise<StepRunResult> {
-    const step = this.registry.find((s) => s.id === id);
-    if (!step) {
-      return {
-        id,
-        ok: false,
-        checks: [],
-        failures: [`unknown step "${id}" — known: ${this.registry.map((s) => s.id).join(", ")}`],
-      };
-    }
-    if (!this.enabled(step)) {
-      return {
-        id,
-        ok: false,
-        checks: [],
-        failures: [`step "${id}" is disabled by the recorded choices`],
-      };
-    }
-    const rec = this.record(id);
-    rec.status = "pending";
-    this.reopen();
-    this.save();
-    let report: StepReport;
-    try {
-      report = await step.run(this.ctxFor(id, input));
-    } catch (err) {
-      report = {
-        ok: false,
-        checks: [{ name: id, ok: false, detail: `step threw: ${String(err)}` }],
-      };
-    }
-    if (report.data) rec.data = { ...rec.data, ...report.data };
-    if (report.ok) {
-      rec.status = "done";
-      rec.completed_at = this.adapters.clock().toISOString();
-      rec.verified_at = null;
-      rec.note = null;
-      // A run acts on the installation (choices, config, deploys) after the
-      // full verification that backed the completion claim: only the next
-      // green finish() may make that claim again.
-      this.reopen();
-    } else {
-      rec.status = "pending";
-      rec.note = `last run failed: ${failures(report.checks).join("; ") || "unknown"}`;
-      this.reopen();
-    }
-    this.save();
-    return { id, ok: report.ok, checks: report.checks, failures: failures(report.checks) };
-  }
-
-  private async safeVerify(step: OnboardingStep): Promise<StepReport> {
-    try {
-      return await step.verify(this.ctxFor(step.id));
-    } catch (err) {
-      return {
-        ok: false,
-        checks: [{ name: step.id, ok: false, detail: `verify threw: ${String(err)}` }],
-      };
-    }
-  }
-
-  /**
-   * Verify every enabled step — done or not. A pending step whose verify()
-   * holds is promoted to done (its outcome exists in reality, which is the
-   * only truth the checklist mirrors); a done step whose verify() fails
-   * reports red here (finish refuses) but demotion is reconcile()'s job.
-   */
-  async verifyAll(): Promise<VerifyAllResult> {
-    const results: VerifyAllResult["results"] = [];
-    for (const step of this.registry) {
-      if (!this.enabled(step)) continue;
-      const outcome = await this.safeVerify(step);
-      const rec = this.record(step.id);
-      if (outcome.ok) {
-        rec.verified_at = this.adapters.clock().toISOString();
-        if (rec.status !== "done") {
-          rec.status = "done";
-          rec.completed_at = rec.completed_at ?? rec.verified_at;
-          rec.note = "verified green without a recorded run";
-        }
-      }
-      results.push({ id: step.id, ok: outcome.ok, failures: failures(outcome.checks) });
-    }
-    this.save();
-    return { ok: results.every((r) => r.ok), results };
-  }
-
-  /**
-   * The finish tool's engine half: re-run the full verification checklist.
-   * Anything red ⇒ refuse with the failures (the caller returns them as the
-   * tool result and does not exit). All green ⇒ mark the checklist complete
-   * and write the first-run marker — once: a marker already on disk is left
+   * The finish tool's engine half: the checklist's full verification. Anything
+   * red ⇒ refuse with the failures (the caller returns them as the tool
+   * result and does not exit). All green ⇒ the checklist is complete, and the
+   * first-run marker is written — once: a marker already on disk is left
    * untouched, so the completed_at the companion greets on never moves.
    */
-  async finish(): Promise<FinishResult> {
-    const all = await this.verifyAll();
-    if (!all.ok) {
-      this.reopen();
-      this.save();
-      return { ok: false, results: all.results };
-    }
-    const completedAt = this.checklist.completed_at ?? this.adapters.clock().toISOString();
-    this.checklist.completed_at = completedAt;
-    this.checklist.reopened_at = null;
-    this.save();
+  override async finish(): Promise<FinishResult> {
+    const done = await super.finish();
+    if (!done.ok) return done;
     const marker = firstRunMarkerPath(this.adapters.paths.stateDir);
     let markerWritten = false;
     if (!existsSync(marker)) {
-      writeAtomic(marker, `${JSON.stringify({ completed_at: completedAt })}\n`);
+      writeAtomic(marker, `${JSON.stringify({ completed_at: done.completed_at })}\n`);
       markerWritten = true;
     }
-    return { ok: true, completed_at: completedAt, marker_written: markerWritten };
+    return { ok: true, completed_at: done.completed_at, marker_written: markerWritten };
   }
 }

package/src/onboard/pipin.ts

@@ -0,0 +1,31 @@
+// The pinned pi version, read from package.json. A leaf: the daemon reaches it
+// through src/version.ts, so it imports nothing from the onboarding wizard.
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+export interface PiPin {
+  package: string;
+  version: string;
+}
+
+/** The pin from package.json's "qcrPi" block — the mirror that exists on a bare
+ * public clone, where config.toml does not (the wizard writes it later).
+ * config.toml [pi] stays the preferred source when it loads (cmdOnboard tries
+ * it first); both mirror the same pinned version by rule 7's discipline. */
+export function piPinFromPackageJson(
+  root: string,
+  readFile: (p: string) => string = (p) => readFileSync(p, "utf8"),
+): PiPin | null {
+  try {
+    const pkg = JSON.parse(readFile(join(root, "package.json"))) as {
+      qcrPi?: { package?: unknown; version?: unknown };
+    };
+    const pi = pkg.qcrPi;
+    if (pi && typeof pi.package === "string" && typeof pi.version === "string") {
+      return { package: pi.package, version: pi.version };
+    }
+  } catch {
+    // fall through — the caller reports the missing pin
+  }
+  return null;
+}

package/src/onboard/stepforward.ts

@@ -0,0 +1,61 @@
+// The memory forward, held open for ONE onboarding step call.
+//
+// On the compose route the memory engine listens only on its own container's
+// loopback; this machine reaches it through the memory forward, the same relay
+// the TUI runs in-process (src/tui/memforward.ts over
+// scripts/companion-memory-forward.mjs). The wizard runs before any TUI, so
+// without this the memory steps' phase B (minting the user keys, the
+// confinement matrix) found nothing listening and sent the operator to a
+// second terminal — and a wizard driven in order never got memory working.
+//
+// A forward that is already listening (`qcr tui`, the systemd unit) is
+// adopted and left alone; one this opens is closed when the step ends, so the
+// wizard leaves nothing running behind it. The real adapter assembly
+// (extensions/onboarding.ts) hands this to the steps; a test's adapters never
+// do, so no test binds a port.
+import { MemoryForward } from "../tui/memforward.js";
+
+export interface StepForwardRequest {
+  /** Where the step reaches memory (the forward's loopback listener). */
+  baseUrl: string;
+  /** The checkout holding scripts/. */
+  repoRoot: string;
+  /** The memory sidecar's container. */
+  container: string;
+  sudoDocker: boolean;
+  log?: (line: string) => void;
+}
+
+export interface StepForward {
+  /** true when this call started the forward (and stop() closes it). */
+  started: boolean;
+  detail: string;
+  stop(): void;
+}
+
+/** Open (or adopt) the local memory forward; null when none could be made to
+ * answer, with nothing left bound. */
+export async function openStepMemoryForward(
+  req: StepForwardRequest,
+  env: NodeJS.ProcessEnv = process.env,
+): Promise<StepForward | null> {
+  const forward = new MemoryForward({
+    baseUrl: req.baseUrl,
+    repoRoot: req.repoRoot,
+    env,
+    local: true,
+    sudoDocker: req.sudoDocker,
+    container: req.container,
+    ...(req.log ? { log: req.log } : {}),
+  });
+  const status = await forward.ensure();
+  if (status.state === "owned")
+    return {
+      started: true,
+      detail: `opened a memory forward to ${req.container} for this step; it closes when the step ends, and \`qcr tui\` runs its own`,
+      stop: () => forward.stop(),
+    };
+  if (status.state === "adopted") return { started: false, detail: status.detail, stop: () => {} };
+  forward.stop();
+  return null;
+}

package/src/onboard/steps/appslug.ts

@@ -50,7 +50,7 @@ import {
   tomlString,
   type TomlEdit,
 } from "./configfill.js";
-import { CHOICE_KEYS, botLoginFor } from "../choices.js";
+import { CHOICE_KEYS, botLoginFor, userAuthRecorded } from "../choices.js";
 import { api, readCredentials } from "./githubapp.js";
 
 export const APP_SLUG_STEP_ID = "app_slug_reconcile";
@@ -254,6 +254,9 @@ export function appSlugStep(opts: AppSlugStepOptions = {}): OnboardingStep {
       "slug, so this step asks the App itself who it is and corrects [github] app_slug and bot_login to match. It matters more " +
       "than it looks: bot_login is how the reviewer recognises its own reviews and comments, and a wrong one fails silently.",
     order: 65,
+    // There is no App slug on the own-account route: `[github] app_slug` is ""
+    // and bot_login is the person's login (the github_account step writes both).
+    enabled: (choices) => !userAuthRecorded(choices),
     async run(ctx): Promise<StepReport> {
       return reconcile(ctx, true);
     },