@quickchatai/quickreview 0.0.0-stage → 1.2.0

package/extensions/inline-bash.ts

@@ -0,0 +1,102 @@
+/**
+ * VENDORED VERBATIM from the pinned pi package's shipped example:
+ * @earendil-works/pi-coding-agent examples/extensions/inline-bash.ts
+ * (copied at 0.84.1; byte-identical at 0.84.4).
+ * Copied rather than referenced in-image because the load path must survive a
+ * pi version bump and be guardable host-side like every other /workspace
+ * extension. Re-copy on a pi pin bump (rule 7); do not hand-edit below this
+ * header. Companion QoL only — never loaded by VM sessions.
+ *
+ * Inline Bash Extension - expands inline bash commands in user prompts.
+ *
+ * Start pi with this extension:
+ *   pi -e ./examples/extensions/inline-bash.ts
+ *
+ * Then type prompts with inline bash:
+ *   What's in !{pwd}?
+ *   The current branch is !{git branch --show-current} and status: !{git status --short}
+ *   My node version is !{node --version}
+ *
+ * The !{command} patterns are executed and replaced with their output before
+ * the prompt is sent to the agent.
+ *
+ * Note: Regular !command syntax (whole-line bash) is preserved and works as before.
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+export default function (pi: ExtensionAPI) {
+	const PATTERN = /!\{([^}]+)\}/g;
+	const TIMEOUT_MS = 30000;
+
+	pi.on("input", async (event, ctx) => {
+		const text = event.text;
+
+		// Don't process if it's a whole-line bash command (starts with !)
+		// This preserves the existing !command behavior
+		if (text.trimStart().startsWith("!") && !text.trimStart().startsWith("!{")) {
+			return { action: "continue" };
+		}
+
+		// Check if there are any inline bash patterns
+		if (!PATTERN.test(text)) {
+			return { action: "continue" };
+		}
+
+		// Reset regex state after test()
+		PATTERN.lastIndex = 0;
+
+		let result = text;
+		const expansions: Array<{ command: string; output: string; error?: string }> = [];
+
+		// Find all matches first (to avoid issues with replacing while iterating)
+		const matches: Array<{ full: string; command: string }> = [];
+		let match = PATTERN.exec(text);
+		while (match) {
+			matches.push({ full: match[0], command: match[1] });
+			match = PATTERN.exec(text);
+		}
+
+		// Execute each command and collect results
+		for (const { full, command } of matches) {
+			try {
+				const bashResult = await pi.exec("bash", ["-c", command], {
+					timeout: TIMEOUT_MS,
+				});
+
+				const output = bashResult.stdout || bashResult.stderr || "";
+				const trimmed = output.trim();
+
+				if (bashResult.code !== 0 && bashResult.stderr) {
+					expansions.push({
+						command,
+						output: trimmed,
+						error: `exit code ${bashResult.code}`,
+					});
+				} else {
+					expansions.push({ command, output: trimmed });
+				}
+
+				result = result.replace(full, trimmed);
+			} catch (err) {
+				const errorMsg = err instanceof Error ? err.message : String(err);
+				expansions.push({ command, output: "", error: errorMsg });
+				result = result.replace(full, `[error: ${errorMsg}]`);
+			}
+		}
+
+		// Show what was expanded (if UI available)
+		if (ctx.hasUI && expansions.length > 0) {
+			const summary = expansions
+				.map((e) => {
+					const status = e.error ? ` (${e.error})` : "";
+					const preview = e.output.length > 50 ? `${e.output.slice(0, 50)}...` : e.output;
+					return `!{${e.command}}${status} -> "${preview}"`;
+				})
+				.join("\n");
+
+			ctx.ui.notify(`Expanded ${expansions.length} inline command(s):\n${summary}`, "info");
+		}
+
+		return { action: "transform", text: result, images: event.images };
+	});
+}

package/extensions/login-route.ts

@@ -0,0 +1,220 @@
+// login-route — a pi that has no usable model login says so, and opens pi's
+// own /login; a pi whose model names one OpenAI provider while the person
+// logged in with the other runs the same model on the login that exists.
+//
+// Loaded by every CLI pi Quickreview starts for a person: the onboarding
+// wizard (registered by extensions/onboarding.ts, which opens the login for
+// the person), the companion, a takeover and a debug round (the env shim
+// extensions/cli/login-route.ts, which prefills it). An SDK session needs none
+// of this: PiHost routes its model the same way (packages/pi-plugin/src/engine/pisdk.ts).
+//
+// Three behaviours, each on pi's own API:
+//   - Model route. On session_start and before every prompt (the `input`
+//     event, which pi runs before it checks the model's credential), a model
+//     whose provider has no credential is switched to its OpenAI twin when the
+//     twin has one and serves the same id (packages/pi-plugin/src/modelroute.ts).
+//     The provider the spec names always wins when its login exists, so an
+//     install that works today is untouched. pi.setModel does not persist the
+//     switch to settings.
+//   - Login hint. When no usable model is left, a widget says exactly what to
+//     do, and pi's input line holds `/login`, so one Enter opens pi's login.
+//     The widget clears once a model is selected (`model_select`).
+//   - Open (the wizard only). pi runs `/login` only from its editor's submit
+//     (an extension cannot call the command), and the one public way to reach
+//     that submit is an editor component: pi wires its own submit handler
+//     onto every editor an extension installs. So the login is opened by
+//     installing a stock CustomEditor for an instant, submitting `/login`
+//     through the handler pi gave it, and restoring the editor that was there.
+//     When that wiring is not found, the prefilled `/login` is the fallback.
+import {
+  CustomEditor,
+  type ExtensionAPI,
+  type ExtensionContext,
+  type ExtensionFactory,
+  type ExtensionUIContext,
+} from "@earendil-works/pi-coding-agent";
+import type { Api, Model } from "@earendil-works/pi-ai";
+import { routeProvider, twinProvider } from "@quickchatai/pi-quickreview/src/modelroute.js";
+
+/** The widget key the hint is shown under. */
+export const LOGIN_WIDGET = "qcr-login";
+
+/** The command the hint prefills and the wizard submits: pi's own login,
+ * with every provider it offers. */
+export const LOGIN_COMMAND = "/login";
+
+/** What the person reads above the input line while no model is usable:
+ * which logins work and how to reach them in pi's menu (pi 1.4.0's labels),
+ * then how to (re)open the menu. `opened` says whether the menu is on screen. */
+export function loginHintLines(opened: boolean): string[] {
+  return [
+    "Quickreview needs a model login before it can do anything. Any OpenAI login works:",
+    '  - "Sign in with an account", then "OpenAI" (Sign in with ChatGPT) or "OpenAI Codex (legacy)";',
+    '  - "Sign in with an API key", then type openai, pick "OpenAI" and paste your key (sk-...).',
+    opened
+      ? `pi's login menu is open below. Closed it? Type ${LOGIN_COMMAND} and press Enter.`
+      : `Press Enter to open pi's login menu (${LOGIN_COMMAND} is on the input line).`,
+  ];
+}
+
+/** How a pi opens the login when it needs one. */
+export type LoginOpen = "submit" | "prefill";
+
+export interface LoginRouteConfig {
+  /** "submit" opens pi's login menu; "prefill" leaves `/login` on the input
+   * line for one Enter. */
+  open: LoginOpen;
+}
+
+/** The config the env describes: QCR_LOGIN_OPEN=submit, else prefill. */
+export function loginRouteConfigFromEnv(env: NodeJS.ProcessEnv): LoginRouteConfig {
+  return { open: env.QCR_LOGIN_OPEN === "submit" ? "submit" : "prefill" };
+}
+
+/** What the model route did. */
+export type ModelRouteOutcome =
+  /** The current model's provider has a credential. */
+  | "usable"
+  /** The model was moved to its OpenAI twin, whose login exists. */
+  | "switched"
+  /** There is a model, and neither it nor a twin has a credential. */
+  | "unusable"
+  /** There is no model at all. */
+  | "none";
+
+type Registry = Pick<
+  ExtensionContext["modelRegistry"],
+  "find" | "getAvailable" | "getProviderAuthStatus"
+>;
+
+function hasCredential(registry: Registry, provider: string): boolean {
+  try {
+    return registry.getProviderAuthStatus(provider).configured;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Keep the session's model on a login that exists: the model as it is when its
+ * provider has a credential, else its OpenAI twin when that has one.
+ *
+ * VERIFY-ON-PIN (pi 1.4.0): ModelRegistry.getProviderAuthStatus(p).configured
+ * covers a stored login, a stored or runtime key and an environment key, and
+ * the extension pi.setModel returns false (switching nothing) for a provider
+ * without a credential.
+ */
+export async function routeSessionModel(
+  pi: Pick<ExtensionAPI, "setModel">,
+  ctx: { model: Model<Api> | undefined; modelRegistry: Registry },
+): Promise<ModelRouteOutcome> {
+  const model = ctx.model;
+  if (!model) return "none";
+  const registry = ctx.modelRegistry;
+  if (hasCredential(registry, model.provider)) return "usable";
+  if (twinProvider(model.provider) === undefined) return "unusable";
+  const provider = routeProvider(model.provider, model.id, {
+    hasCredential: (p) => hasCredential(registry, p),
+    hasModel: (p, id) => registry.find(p, id) !== undefined,
+  });
+  if (provider === model.provider) return "unusable";
+  const twin = registry.find(provider, model.id);
+  if (twin && (await pi.setModel(twin))) return "switched";
+  return "unusable";
+}
+
+/** Does this pi need a login: no usable model, and none pi could pick? */
+export function needsLogin(outcome: ModelRouteOutcome, registry: Registry): boolean {
+  if (outcome === "usable" || outcome === "switched") return false;
+  if (outcome === "unusable") return true;
+  try {
+    return registry.getAvailable().length === 0;
+  } catch {
+    return true;
+  }
+}
+
+type EditorUi = Pick<ExtensionUIContext, "setEditorComponent" | "getEditorComponent">;
+type MakeEditor = Parameters<ExtensionUIContext["setEditorComponent"]>[0] & {};
+
+/**
+ * Submit `text` through pi's own editor submit, as if typed and Entered. pi
+ * runs its built-in commands (`/login` among them) only from that handler, and
+ * hands it to every editor component an extension installs: so a stock editor
+ * is installed, its handler taken, and the previous editor (pi's default, or
+ * another extension's) restored before anything renders. Returns false, having
+ * submitted nothing, when pi did not wire a handler.
+ *
+ * VERIFY-ON-PIN (pi 1.4.0, interactive-mode.js setCustomEditorComponent):
+ * `newEditor.onSubmit = this.defaultEditor.onSubmit` runs synchronously inside
+ * setEditorComponent, and setEditorComponent(undefined) restores the default
+ * editor with its text.
+ */
+export function submitThroughEditor(
+  ui: EditorUi,
+  text: string,
+  makeEditor: MakeEditor = (tui, theme, keybindings) => new CustomEditor(tui, theme, keybindings),
+): boolean {
+  let made: { onSubmit?: (text: string) => void } | undefined;
+  const previous = ui.getEditorComponent();
+  try {
+    ui.setEditorComponent((tui, theme, keybindings) => {
+      const editor = makeEditor(tui, theme, keybindings);
+      made = editor;
+      return editor;
+    });
+  } catch {
+    made = undefined;
+  }
+  const submit = made?.onSubmit;
+  ui.setEditorComponent(previous);
+  if (typeof submit !== "function") return false;
+  void Promise.resolve()
+    .then(() => submit(text))
+    .catch(() => undefined);
+  return true;
+}
+
+type HintUi = Pick<ExtensionUIContext, "setWidget" | "setEditorText"> & EditorUi;
+
+/** Show the hint and open (or prefill) pi's login. Returns how it was opened. */
+export function openLogin(ui: HintUi, open: LoginOpen): "submitted" | "prefilled" {
+  if (open === "submit" && submitThroughEditor(ui, LOGIN_COMMAND)) {
+    ui.setWidget(LOGIN_WIDGET, loginHintLines(true), { placement: "aboveEditor" });
+    return "submitted";
+  }
+  ui.setWidget(LOGIN_WIDGET, loginHintLines(false), { placement: "aboveEditor" });
+  ui.setEditorText(LOGIN_COMMAND);
+  return "prefilled";
+}
+
+/** Register the model route and the login hint on `pi`. Exported so a host that
+ * builds its own onboarding extension (over `toolDefinitions`) gets the same
+ * first-run login as `qcr onboard`. */
+export function registerLoginRoute(pi: ExtensionAPI, config: LoginRouteConfig): void {
+  if (typeof pi.on !== "function") return;
+  let shown = false;
+  pi.on("session_start", async (_event, ctx) => {
+    const outcome = await routeSessionModel(pi, ctx);
+    if (!ctx.hasUI || !needsLogin(outcome, ctx.modelRegistry)) return;
+    shown = true;
+    openLogin(ctx.ui, config.open);
+  });
+  // pi checks the model's credential after this event, so a login made inside
+  // the session (its default model stays the spec's provider) is routed here.
+  pi.on("input", async (_event, ctx) => {
+    await routeSessionModel(pi, ctx);
+    return { action: "continue" };
+  });
+  pi.on("model_select", (_event, ctx) => {
+    if (!shown || !ctx.hasUI) return;
+    shown = false;
+    ctx.ui.setWidget(LOGIN_WIDGET, undefined);
+  });
+}
+
+/** The factory, for a pi that loads the route by path (its shim) or a host
+ * that composes factories. */
+export function createLoginRoute(config: LoginRouteConfig): ExtensionFactory {
+  return (pi) => registerLoginRoute(pi, config);
+}

package/extensions/muted-theme.json

@@ -0,0 +1,68 @@
+{
+  "name": "muted",
+  "vars": {
+    "text": "#c8ccd4",
+    "muted": "#7f8794",
+    "dim": "#606773",
+    "accent": "#82a6c9",
+    "border": "#526272",
+    "panel": "#20232a",
+    "panelSoft": "#24272f",
+    "panelError": "#302326"
+  },
+  "colors": {
+    "accent": "accent",
+    "border": "border",
+    "borderAccent": "accent",
+    "borderMuted": "dim",
+    "success": "#8fae9a",
+    "error": "#c78388",
+    "warning": "#c7aa78",
+    "muted": "muted",
+    "dim": "dim",
+    "text": "text",
+    "thinkingText": "muted",
+    "selectedBg": "panelSoft",
+    "scrollbarThumb": "#353a45",
+    "userMessageBg": "#252932",
+    "userMessageText": "text",
+    "customMessageBg": "#27252e",
+    "customMessageText": "text",
+    "customMessageLabel": "#a392bd",
+    "toolPendingBg": "panel",
+    "toolSuccessBg": "panel",
+    "toolErrorBg": "panelError",
+    "toolTitle": "#aeb7c4",
+    "toolOutput": "muted",
+    "mdHeading": "#c5ad82",
+    "mdLink": "accent",
+    "mdLinkUrl": "dim",
+    "mdCode": "#9fb8ba",
+    "mdCodeBlock": "#abb3bd",
+    "mdCodeBlockBorder": "dim",
+    "mdQuote": "muted",
+    "mdQuoteBorder": "border",
+    "mdHr": "dim",
+    "mdListBullet": "accent",
+    "toolDiffAdded": "#88a991",
+    "toolDiffRemoved": "#bd8085",
+    "toolDiffContext": "muted",
+    "syntaxComment": "#6f806f",
+    "syntaxKeyword": "#879fc1",
+    "syntaxFunction": "#b7aa82",
+    "syntaxVariable": "#9db3c5",
+    "syntaxString": "#9caf91",
+    "syntaxNumber": "#ad9dbc",
+    "syntaxType": "#84aaa8",
+    "syntaxOperator": "#aeb3bb",
+    "syntaxPunctuation": "#aeb3bb",
+    "thinkingOff": "dim",
+    "thinkingMinimal": "muted",
+    "thinkingLow": "#718da8",
+    "thinkingMedium": "#829bb5",
+    "thinkingHigh": "#9b8eae",
+    "thinkingXhigh": "#ad88b1",
+    "thinkingMax": "#bd8caf",
+    "bashMode": "#8fae9a"
+  }
+}

package/extensions/muted-theme.ts

@@ -0,0 +1,23 @@
+// The fleet-wide low-contrast pi theme — default for EVERY pi session
+// (companion and the VM per-PR/overseer sessions alike). Tool success
+// intentionally uses the same neutral background as pending tools: command
+// completion must not flash a bright green panel at the operator.
+//
+// VERIFY-ON-PIN: session_start's second argument and ctx.ui.setTheme are the
+// documented 0.84.1 extension API, also exercised by pi's mac-system-theme
+// example.
+import type { ExtensionAPI, ExtensionFactory } from "@earendil-works/pi-coding-agent";
+
+export const MUTED_THEME = "muted";
+
+export function createMutedTheme(): ExtensionFactory {
+  return (pi: ExtensionAPI): void => {
+    pi.on("session_start", (_event, ctx) => {
+      const ui = ctx?.ui as
+        { setTheme?: (theme: string) => { success: boolean; error?: string } } | undefined;
+      const result = ui?.setTheme?.(MUTED_THEME);
+      if (result && !result.success)
+        console.error(`[muted-theme] ${result.error ?? "could not select theme"}`);
+    });
+  };
+}

package/extensions/onboarding.ts

@@ -0,0 +1,262 @@
+// onboarding — the wizard's tool belt. Loaded ONLY by `qcr onboard`
+// (per spawn, `-e`, alongside --no-extensions — no ambient extension rides the
+// onboarding session), never registered globally. pi jiti-loads this TS source
+// on the HOST, so it imports the OnboardingEngine source directly and runs it
+// in-process: pi talks, these deterministic tools act, and the LLM never
+// freestyles a shell command (the built-in belt is read-only by argv).
+//
+// One tool per registered engine step (onboard_<id>), plus:
+//   - onboard_status: reconcile + checklist listing (resume re-verifies every
+//     claimed-done step against reality — the file is never trusted alone);
+//   - finish_and_exit: re-runs the FULL verification; anything red comes back
+//     as the tool result (no exit, ever, while red); all green marks the
+//     checklist complete, writes the companion's first-run marker
+//     (state/companion/first-run.json), and triggers pi's deferred shutdown —
+//     the `qcr onboard` process then opens the TUI.
+//
+// Convention notes (same shape as companion-guard/tui-view): degrade, never
+// wedge — a pi without registerTool registers nothing and says so; a missing
+// ctx.shutdown falls back to telling the operator to /exit.
+import { execFile } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import type {
+  ExtensionAPI,
+  ExtensionFactory,
+  ExtensionToolContext,
+} from "@earendil-works/pi-coding-agent";
+import {
+  registerQcrTool,
+  textResult as text,
+  type QcrTool,
+} from "@quickchatai/pi-quickreview/extensions/pi-tool.js";
+import {
+  OnboardingEngine,
+  type CheckResult,
+  type OnboardAdapters,
+  type ReconcileReport,
+  type StepStatusLine,
+} from "../src/onboard/engine.js";
+import { defaultSteps } from "../src/onboard/steps/index.js";
+import { openStepMemoryForward } from "../src/onboard/stepforward.js";
+import { locateConfig } from "../src/install.js";
+import { registerLoginRoute } from "./login-route.js";
+import {
+  ONBOARD_FINISH_TOOL,
+  ONBOARD_STATUS_TOOL,
+  onboardStepToolName,
+} from "../src/onboard/toolnames.js";
+
+const NO_PARAMS = { type: "object", properties: {} } as const;
+
+// ---- real adapters ----------------------------------------------------------
+
+/** The one real adapter assembly. Steps see the host only through this. */
+export function realAdapters(root: string): OnboardAdapters {
+  return {
+    fetch: (input, init) => fetch(input, init),
+    runner: {
+      run: (cmd, args) =>
+        new Promise((resolvePromise) => {
+          execFile(cmd, args, { timeout: 60_000 }, (err, stdout, stderr) => {
+            const code = err === null ? 0 : typeof err.code === "number" ? err.code : 1;
+            resolvePromise({
+              code,
+              stdout: String(stdout),
+              stderr: err && !stderr ? String(err.message) : String(stderr),
+            });
+          });
+        }),
+    },
+    clock: () => new Date(),
+    host: {
+      nodeVersion: process.version,
+      uid: typeof process.getuid === "function" ? process.getuid() : null,
+      inContainer: existsSync("/.dockerenv"),
+    },
+    // The install locator decides which config.toml the wizard edits —
+    // $QCR_CONFIG, else the install's config home (never the checkout's).
+    paths: { stateDir: join(root, "state"), configPath: locateConfig().path },
+    log: (line) => console.error(line),
+    memoryForward: (req) => openStepMemoryForward(req),
+  };
+}
+
+export function buildEngine(root: string): OnboardingEngine {
+  return new OnboardingEngine(defaultSteps(), realAdapters(root));
+}
+
+// ---- rendering --------------------------------------------------------------
+
+export function renderChecks(checks: readonly CheckResult[]): string {
+  return checks.map((c) => `${c.ok ? "✓" : "✗"} ${c.name} — ${c.detail}`).join("\n");
+}
+
+export function renderStatus(
+  lines: readonly StepStatusLine[],
+  reconciled: ReconcileReport,
+): string {
+  const rows = lines.map((l) => {
+    const mark =
+      l.status === "done"
+        ? "[done]"
+        : l.status === "disabled"
+          ? "[skipped]"
+          : l.optional
+            ? "[after setup]"
+            : "[ ]";
+    return `${mark} ${l.id} — ${l.title}${l.note ? ` (${l.note})` : ""}`;
+  });
+  const demoted = reconciled.demoted.map(
+    (d) => `re-verification demoted ${d.id}: ${d.failures.join("; ")}`,
+  );
+  return [
+    "Onboarding checklist (claimed-done steps were just re-verified against reality):",
+    ...rows,
+    ...demoted,
+  ].join("\n");
+}
+
+// ---- tool belt --------------------------------------------------------------
+
+/**
+ * Build the tool definitions over an engine. `shutdown` is injected so tests
+ * assert the finish tool's refusal/exit behaviour without a pi; activate wires
+ * the real ctx probe.
+ */
+export function toolDefinitions(
+  engine: OnboardingEngine,
+  shutdown: (ctx?: Pick<ExtensionToolContext, "shutdown">) => void,
+): QcrTool[] {
+  const stepTools: QcrTool[] = engine.stepDefs().map((step) => ({
+    name: onboardStepToolName(step.id),
+    label: step.title,
+    description:
+      `${step.explain} Deterministic: runs the "${step.id}" onboarding step's real checks and returns one ✓/✗ line per check. ` +
+      "Safe to re-run; a failed run leaves the step pending.",
+    promptSnippet: `Run the ${step.id} onboarding step`,
+    // A step that needs the operator's answer declares its own schema; the
+    // params land on the step as ctx.input (the ingress choice is one).
+    // Everything else takes no input at all.
+    parameters: step.parameters ?? NO_PARAMS,
+    execute: async (_id, params) => {
+      const result = await engine.runStep(step.id, params ?? {});
+      if (result.ok)
+        return text(`Step "${step.id}" completed and recorded.\n${renderChecks(result.checks)}`);
+      // A refusal (a disabled or unknown step) runs no checks: its reason is
+      // the engine's failures, and there are no red checks to fix.
+      if (result.checks.length === 0)
+        return text(
+          `Step "${step.id}" REFUSED — ${result.failures.join("; ") || "no reason given"}.`,
+        );
+      return text(
+        `Step "${step.id}" FAILED — fix the red checks and run it again.\n${renderChecks(result.checks)}`,
+      );
+    },
+  }));
+
+  const status: QcrTool = {
+    name: ONBOARD_STATUS_TOOL,
+    label: "Onboarding status",
+    description:
+      "The checklist: every step in order with its status. Re-verifies each claimed-done step against reality first " +
+      "(the state file is never trusted alone), so call this at the start of every session and after anything changes outside the tools.",
+    promptSnippet: "Read and re-verify the onboarding checklist",
+    parameters: NO_PARAMS,
+    execute: async () => {
+      const reconciled = await engine.reconcile();
+      return text(renderStatus(engine.list(), reconciled));
+    },
+  };
+
+  const finish: QcrTool = {
+    name: ONBOARD_FINISH_TOOL,
+    label: "Finish onboarding",
+    description:
+      "Re-run EVERY verification. While anything is red this refuses and returns the failures — it never exits on red. " +
+      "When all green it marks onboarding complete, writes the companion first-run marker, and shuts this session down; " +
+      "the wizard process then opens the TUI.",
+    promptSnippet: "Verify everything and, only when green, finish onboarding",
+    parameters: NO_PARAMS,
+    execute: async (_id, _params, _signal, _onUpdate, ctx) => {
+      const result = await engine.finish();
+      if (!result.ok) {
+        const red = result.results
+          .filter((r) => !r.ok && !r.optional)
+          .map((r) => `✗ ${r.id}: ${r.failures.join("; ") || "not verified"}`);
+        return text(
+          `Not finished — these verifications are red:\n${red.join("\n")}\n` +
+            "Fix them (or run the step tools again), then call finish_and_exit once more.",
+        );
+      }
+      // Green: shut down AFTER this result is returned. The 250ms defer is
+      // belt-and-braces so the model sees the confirmation first.
+      // VERIFY-ON-PIN: ctx.shutdown's own idle-deferral (pi's ExtensionContext) may
+      // make the timer redundant — the onboarding smoke step is the evidence.
+      setTimeout(() => shutdown(ctx), 250);
+      return text(
+        `Every step verified green — onboarding is complete (recorded ${result.completed_at}).\n` +
+          `${result.marker_written ? "First-run marker written for the companion greeting." : "First-run marker already present — left untouched."}\n` +
+          "This session now shuts down and the TUI opens: the board lists the repository's open pull requests — " +
+          "select one and press R to review it now (dry-run: nothing is posted).",
+      );
+    },
+  };
+
+  return [...stepTools, status, finish];
+}
+
+// ---- activation -------------------------------------------------------------
+
+export interface OnboardingConfig {
+  /** The checkout the wizard inspects and writes the install's config for. */
+  root: string;
+}
+
+/** The root the env describes: QCR_ROOT, else `cwd`. */
+export function onboardingConfigFromEnv(env: NodeJS.ProcessEnv, cwd: string): OnboardingConfig {
+  return { root: env.QCR_ROOT ?? cwd };
+}
+
+/** The factory that registers the wizard's tools. The env shim is
+ * extensions/cli/onboarding.ts. */
+export function createOnboarding(config: OnboardingConfig): ExtensionFactory {
+  return (pi) => registerOnboarding(pi, config);
+}
+
+/**
+ * The onboarding session's first-run login: when pi has no usable model
+ * login, pi's own /login menu opens with a widget that says which logins work
+ * (any OpenAI one), and an OpenAI model whose provider has no login runs on
+ * the twin login that exists (extensions/login-route.ts). `qcr onboard`
+ * registers it with the tools; a host that builds its own onboarding
+ * extension over `toolDefinitions` + `registerQcrTool` calls it too.
+ */
+export function registerOnboardingSession(pi: ExtensionAPI): void {
+  registerLoginRoute(pi, { open: "submit" });
+}
+
+function registerOnboarding(pi: ExtensionAPI, config: OnboardingConfig): void {
+  registerOnboardingSession(pi);
+  if (typeof pi.registerTool !== "function") {
+    // Degrade loudly, never wedge: pi still starts, the guide can only talk.
+    console.error(
+      "onboarding: pi.registerTool unavailable — no wizard tools registered; this pi cannot run onboarding.",
+    );
+    return;
+  }
+  const engine = buildEngine(config.root);
+  const shutdown = (ctx?: Pick<ExtensionToolContext, "shutdown">): void => {
+    const fn = ctx?.shutdown ?? (pi as { shutdown?: () => void | Promise<void> }).shutdown;
+    if (typeof fn === "function") {
+      // VERIFY-ON-PIN: deferred clean shutdown with exit code 0 (pi 1.4.0's
+      // ExtensionContext.shutdown). Bound to the named onboarding smoke step.
+      void fn.call(ctx ?? pi);
+    } else {
+      console.error(
+        "onboarding: no shutdown API on this pi — type /exit to leave; the wizard will open the TUI.",
+      );
+    }
+  };
+  for (const def of toolDefinitions(engine, shutdown)) registerQcrTool(pi, def);
+}