jeo-code 0.1.0 → 0.4.5

package/src/cli/runner.ts

@@ -32,6 +32,15 @@ export const COMMANDS: readonly CommandSpec[] = [
       return args => m.runAuthCommand(args);
     },
   },
+  {
+    name: "export",
+    summary: "Export a saved session transcript to Markdown (or --json).",
+    usage: "export [id] [--json] [--system]",
+    loader: async () => {
+      const m = await import("../commands/export");
+      return args => m.runExportCommand(args);
+    },
+  },
   {
     name: "deep-interview",
     summary: "Execute Socratic requirements interview (locks tools while ambiguity > 20%).",
@@ -84,24 +93,16 @@ export const COMMANDS: readonly CommandSpec[] = [
   },
   {
     name: "mcp",
-    summary: "Run joc as an MCP stdio server (subcommand: serve|tools).",
+    summary: "Run jeo as an MCP stdio server (subcommand: serve|tools).",
     usage: "mcp [serve|tools]",
     loader: async () => {
       const m = await import("../commands/mcp");
       return args => m.runMcpCommand(args);
     },
   },
-  {
-    name: "models",
-    summary: "List model aliases + probe local/compatible models.",
-    loader: async () => {
-      const m = await import("../commands/models");
-      return args => m.runModelsCommand(args);
-    },
-  },
   {
     name: "skills",
-    summary: "List bundled workflow skills (joc skills <name> for details).",
+    summary: "List bundled workflow skills (jeo skills <name> for details).",
     usage: "skills [name]",
     loader: async () => {
       const m = await import("../commands/skills");
@@ -110,7 +111,7 @@ export const COMMANDS: readonly CommandSpec[] = [
   },
   {
     name: "resume",
-    summary: "Resume the latest interactive session (or 'joc resume <id>').",
+    summary: "Resume the latest interactive session (or 'jeo resume <id>').",
     usage: "resume [id]",
     loader: async () => {
       const m = await import("../commands/resume");
@@ -135,6 +136,95 @@ export const COMMANDS: readonly CommandSpec[] = [
       return args => m.runEvolveCommand(args);
     },
   },
+  {
+    name: "memory-distill",
+    summary: "(internal) Background session-memory distillation worker spawned on exit.",
+    usage: "memory-distill <payload.json>",
+    loader: async () => {
+      const m = await import("../agent/memory");
+      return args => m.runMemoryDistillCommand(args);
+    },
+  },
+  {
+    name: "state",
+    summary: "Read or update workflow state receipts under .jeo/state (gjc-state parity).",
+    usage: "state <deep-interview|ralplan|team|ultragoal> <read|write|clear|handoff> [--input '<json>'] [--to <skill>] [--json]",
+    loader: async () => {
+      const m = await import("../commands/state");
+      return args => m.runStateCommand(args);
+    },
+  },
+  {
+    name: "session",
+    summary: "List, attach, or remove jeo-managed tmux sessions.",
+    usage: "session [list|attach <name>|rm <name>] [--json]",
+    loader: async () => {
+      const m = await import("../commands/session");
+      return args => m.runSessionCommand(args);
+    },
+  },
+  {
+    name: "update",
+    summary: "Check for (and install) a newer jeo-code release from the npm registry.",
+    usage: "update [--check|--install] [--json] [--strict]",
+    loader: async () => {
+      const m = await import("../commands/update");
+      return args => m.runUpdateCommand(args);
+    },
+  },
+  {
+    name: "gjc",
+    summary: "Run the gjc workflow skill as an autonomous build loop (plan → implement → verify).",
+    usage: "gjc \"<intent>\"",
+    loader: async () => {
+      const m = await import("../commands/gjc");
+      return args => m.runGjcCommand(args);
+    },
+  },
+  {
+    name: "ooo-seed",
+    summary: "Generate an immutable ooo seed from a specification (spec-first automation).",
+    usage: "ooo-seed [args]",
+    loader: async () => {
+      const m = await import("../commands/ooo-seed");
+      return args => m.runOooSeedCommand(args);
+    },
+  },
+  {
+    name: "status",
+    summary: "Show evolution status + engine performance metrics.",
+    loader: async () => {
+      const m = await import("../commands/status");
+      return async () => m.runStatusCommand();
+    },
+  },
+  {
+    name: "evolve-core",
+    summary: "Trigger a self-evolution turn using gjc as a guide (Dev Mode).",
+    usage: "evolve-core [args]",
+    loader: async () => {
+      const m = await import("../commands/evolve-core");
+      return args => m.runEvolveCoreCommand(args);
+    },
+  },
+  {
+    name: "autopilot",
+    summary: "Autonomous build loop (autopilot × autoresearch ratchet).",
+    usage: "autopilot <subcommand> [flags]",
+    loader: async () => {
+      const m = await import("../autopilot");
+      return args => Promise.resolve(m.runAutopilot(args));
+    },
+  },
+  {
+    name: "ledger",
+    summary: "Cross-plan append-only ledger (ledger / review / cleanup).",
+    usage: "ledger <subcommand> [flags]",
+    loader: async () => {
+      const m = await import("../ledger");
+      return args => Promise.resolve(m.runLedger(args));
+    },
+  },
 ];
 
 export function findCommand(name: string): CommandSpec | undefined {
@@ -190,6 +280,10 @@ export function renderHelp(ctx: DispatchContext): string {
   lines.push("Options:");
   lines.push("  -v, --version    Show version.");
   lines.push("  -h, --help       Show help.");
+  lines.push("      --model <id>             Use a session model for launch/one-shot.");
+  lines.push("      --provider <name>        Start launch on a provider default (anthropic/openai/gemini/antigravity/ollama).");
+  lines.push("      --smol|--slow|--plan     Start launch with the configured model role tier.");
+  lines.push("      --thinking <level>       Set thinking budget (minimal/low/medium/high/xhigh).");
   lines.push("");
   return lines.join("\n");
 }
@@ -204,6 +298,38 @@ export function renderCommandHelp(spec: CommandSpec, ctx: DispatchContext): stri
   ].join("\n");
 }
 
+const VALUE_FLAGS = new Set(["--worktree", "--model", "--provider", "--thinking", "--max-steps", "--append-system-prompt", "--skills", "--tools", "--system-prompt"]);
+const OPTIONAL_UUID_FLAGS = new Set(["--resume", "--continue", "-c"]);
+const VALUE_PREFIXES = ["--worktree=", "--model=", "--provider=", "--thinking=", "--max-steps=", "--append-system-prompt=", "--skills=", "--tools=", "--system-prompt="];
+const LAUNCH_ONLY_FLAGS = new Set(["--tmux", "--no-tui", "--no-session", "--list", "--smol", "--slow", "--plan", "-p", "--print", "--no-skills", "--no-tools"]);
+const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+function flagName(arg: string): string {
+  const eq = arg.indexOf("=");
+  return eq === -1 ? arg : arg.slice(0, eq);
+}
+
+
+function leadingGlobalFlag(argv: string[], targets: readonly string[]): boolean {
+  const wanted = new Set(targets);
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]!;
+    if (a === "--") break;
+    const name = flagName(a);
+    if (wanted.has(a) || wanted.has(name)) return true;
+    if (LAUNCH_ONLY_FLAGS.has(name)) continue;
+    if (VALUE_FLAGS.has(name) || VALUE_PREFIXES.some(prefix => a.startsWith(prefix))) {
+      if (!a.includes("=") && argv[i + 1] && !argv[i + 1]!.startsWith("-")) i++;
+      continue;
+    }
+    if (OPTIONAL_UUID_FLAGS.has(name)) {
+      if (argv[i + 1] && UUID_REGEX.test(argv[i + 1]!)) i++;
+      continue;
+    }
+    break;
+  }
+  return false;
+}
 export async function dispatch(argv: string[], ctx: DispatchContext): Promise<number> {
   const first = argv[0];
 
@@ -215,8 +341,16 @@ export async function dispatch(argv: string[], ctx: DispatchContext): Promise<nu
     console.log(renderHelp(ctx));
     return 0;
   }
-  // Bare invocation or a leading global flag (e.g. `joc`, `joc --tmux`,
-  // `joc --tmux --worktree <path>`) routes to the interactive agent — gjc parity.
+  if (leadingGlobalFlag(argv, ["--version", "-v"])) {
+    console.log(`${ctx.appName} v${ctx.version}`);
+    return 0;
+  }
+  if (leadingGlobalFlag(argv, ["--help", "-h"])) {
+    console.log(renderHelp(ctx));
+    return 0;
+  }
+  // Bare invocation or a leading global flag (e.g. `jeo`, `jeo --tmux`,
+  // `jeo --tmux --worktree <path>`) routes to the interactive agent — gjc parity.
   if (!first || first.startsWith("-")) {
     const run = await findCommand("launch")!.loader();
     await run(argv);
@@ -232,7 +366,7 @@ export async function dispatch(argv: string[], ctx: DispatchContext): Promise<nu
     return 1;
   }
 
-  // Per-command help: `joc <cmd> --help`.
+  // Per-command help: `jeo <cmd> --help`.
   const rest = argv.slice(1);
   if (rest.includes("--help") || rest.includes("-h")) {
     console.log(renderCommandHelp(spec, ctx));

package/src/cli.ts

@@ -1,8 +1,11 @@
 #!/usr/bin/env bun
 import { dispatch } from "./cli/runner";
+import pkg from "../package.json";
 
-const APP_NAME = "joc";
-const VERSION = "0.1.0";
+const APP_NAME = "jeo";
+// Single source of truth: package.json. A hardcoded copy here drifted from the
+// published version (`jeo update` compares the local version against the registry).
+const VERSION = pkg.version;
 const MIN_BUN_VERSION = "1.3.14";
 
 if (typeof Bun !== "undefined" && Bun.semver?.order(Bun.version, MIN_BUN_VERSION) < 0) {
@@ -13,5 +16,11 @@ if (typeof Bun !== "undefined" && Bun.semver?.order(Bun.version, MIN_BUN_VERSION
 }
 process.title = APP_NAME;
 
-const code = await dispatch(process.argv.slice(2), { appName: APP_NAME, version: VERSION });
-if (code !== 0) process.exit(code);
+try {
+  const code = await dispatch(process.argv.slice(2), { appName: APP_NAME, version: VERSION });
+  if (code !== 0) process.exit(code);
+} catch (err) {
+  // Service-readiness: never surface a raw stack trace to users; clean error + non-zero exit.
+  process.stderr.write(`error: ${(err as Error)?.message ?? String(err)}\n`);
+  process.exit(1);
+}

package/src/commands/AGENTS.md

@@ -0,0 +1,40 @@
+<!-- Parent: ../AGENTS.md -->
+<!-- Generated: 2026-06-11 | Updated: 2026-06-11 -->
+
+# commands
+
+## Purpose
+Concrete implementations of `jeo` subcommands (e.g., launch, setup, team, ultragoal).
+
+## Key Files
+| File | Description |
+|------|-------------|
+| `launch.ts` | The primary interactive/one-shot execution command |
+| `setup.ts` | Guided configuration command |
+| `team.ts` | Multi-agent coordination command |
+| `status.ts` / `update.ts` | Inspection and maintenance commands |
+
+## Subdirectories
+*(None)*
+
+## For AI Agents
+
+### Working In This Directory
+- Commands should handle their own specific setup but delegate core logic to `src/agent/` or `src/tui/`.
+- Maintain clean separation between interactive (TTY) and non-interactive modes.
+
+### Testing Requirements
+- Mock standard streams (stdout/stdin) to test command outputs.
+
+### Common Patterns
+- Command handlers take parsed options, initialize context, and run the main loop or utility function.
+
+## Dependencies
+
+### Internal
+- Connects `src/cli/` routing to `src/agent/` and `src/tui/`.
+
+### External
+*(None)*
+
+<!-- MANUAL: -->

package/src/commands/approve.ts

@@ -1,9 +1,12 @@
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import {
+  readGlobalConfig,
   readWorkflowState,
   writeWorkflowState,
 } from "../agent/state";
+import { PlanSchema, normalizePlanShape, parseYaml } from "../agent/plan";
+import { getSubagentRole, subagentRoleIds } from "../agent/subagents";
 
 export async function runApproveCommand(args: string[] = []): Promise<void> {
   const cwd = process.cwd();
@@ -29,7 +32,7 @@ export async function runApproveCommand(args: string[] = []): Promise<void> {
   // Read ralplan state
   const ralplanState = await readWorkflowState("ralplan", cwd);
   if (!ralplanState) {
-    console.log(`[ERROR] No ralplan workflow state found. Please run 'joc ralplan' first.`);
+    console.log(`[ERROR] No ralplan workflow state found. Please run 'jeo ralplan' first.`);
     process.exitCode = 1;
     return;
   }
@@ -40,10 +43,23 @@ export async function runApproveCommand(args: string[] = []): Promise<void> {
     return;
   }
 
+  // Compare canonical (symlink-resolved) paths so a relative arg, an absolute arg,
+  // or a /var↔/private/var (macOS) form all match the stored plan path.
+  const canonical = async (p: string): Promise<string> => {
+    try {
+      return await fs.realpath(p);
+    } catch {
+      return p;
+    }
+  };
   const resolvedStatePath = path.resolve(cwd, ralplanState.plan_path);
-  if (resolvedStatePath !== resolvedInputPath) {
+  const [canonInput, canonState] = await Promise.all([canonical(resolvedInputPath), canonical(resolvedStatePath)]);
+  if (canonInput !== canonState) {
     console.log(
-      `[ERROR] Provided plan path does not match the active plan in the ralplan state.`
+      `[ERROR] Provided plan path does not match the active plan in the ralplan state.\n` +
+      `  provided: ${resolvedInputPath}\n` +
+      `  active:   ${resolvedStatePath}\n` +
+      `  Run 'jeo approve "${resolvedStatePath}"' to approve the active plan.`
     );
     process.exitCode = 1;
     return;
@@ -55,6 +71,49 @@ export async function runApproveCommand(args: string[] = []): Promise<void> {
     return;
   }
 
+  // Round-10 #4 (architect ref 8-Round10Planning): approval is a GATE, not a
+  // rubber stamp — validate the plan against the exact contract `jeo team`
+  // enforces, so a schema-invalid/unknown-role plan is refused HERE instead of
+  // aborting later at execution time.
+  try {
+    const parsed = PlanSchema.safeParse(normalizePlanShape(parseYaml(await fs.readFile(resolvedInputPath, "utf-8"))));
+    if (!parsed.success) {
+      console.log(
+        `[ERROR] Refusing to approve: the plan is not in the shape 'jeo team' executes (top-level 'steps:' list of { name, role? }).\n` +
+        `  ${parsed.error.issues[0]?.message ?? "schema mismatch"}\n` +
+        `  Fix ${resolvedInputPath} or re-run 'jeo ralplan'.`,
+      );
+      process.exitCode = 1;
+      return;
+    }
+    const cfg = await readGlobalConfig();
+    const unknown = [...new Set(parsed.data.steps.map(s => s.role?.trim()).filter((r): r is string => !!r && !getSubagentRole(r, cfg)))];
+    if (unknown.length > 0) {
+      console.log(
+        `[ERROR] Refusing to approve: plan references unknown subagent role(s): ${unknown.join(", ")}.\n` +
+        `  Known roles: ${subagentRoleIds(cfg).join(", ")}. Fix ${resolvedInputPath} or re-run 'jeo ralplan'.`,
+      );
+      process.exitCode = 1;
+      return;
+    }
+  } catch (err: any) {
+    console.log(`[ERROR] Refusing to approve: the plan file is not parseable YAML (${err.message}). Fix ${resolvedInputPath} or re-run 'jeo ralplan'.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  // Round-11: approval also requires the PERSISTED consensus verdict — a plan
+  // that never passed (or failed) the critic gate cannot be approved. States
+  // from older ralplan runs lack the field; re-running ralplan heals them.
+  if (ralplanState.consensus !== "okay") {
+    console.log(
+      `[ERROR] Refusing to approve: the plan lacks an [OKAY] consensus verdict (recorded: ${ralplanState.consensus ?? "none"}).\n` +
+      `  Re-run 'jeo ralplan' so the consensus critic can review the plan, then approve again.`,
+    );
+    process.exitCode = 1;
+    return;
+  }
+
   // Update ralplan-state.json to approved: true
   ralplanState.approved = true;
   await writeWorkflowState("ralplan", ralplanState, cwd);

package/src/commands/auth.ts

@@ -1,5 +1,10 @@
+import * as path from "node:path";
+import * as os from "node:os";
+import * as fs from "node:fs/promises";
+import { type StoredOAuth } from "../agent/state";
 import { createInterface } from "node:readline/promises";
 import { readGlobalConfig } from "../agent/state";
+import { jeoEnv } from "../util/env";
 import {
   OAUTH_FLOWS,
   OAUTH_FLOW_REGISTRY,
@@ -17,12 +22,24 @@ export async function runAuthCommand(args: string[]): Promise<void> {
   const sub = args[0];
   if (!sub || sub === "status") return runAuthStatus();
   if (sub === "login") return runAuthLogin(args.slice(1));
+  if (sub === "import") return runAuthImport(args.slice(1));
   if (sub === "logout") return runAuthLogout(args[1] as AuthProvider | undefined);
   if (sub === "refresh") return runAuthRefresh(args[1] as AuthProvider | undefined);
-  console.log(`Unknown auth subcommand: ${sub}\nUsage: joc auth [login|logout|refresh|status] [provider] [--token <bearer>]`);
+  console.log(`Unknown auth subcommand: ${sub}\nUsage: jeo auth [login|logout|refresh|status|import] [provider] [--token <bearer>] [--import]`);
   process.exitCode = 1;
 }
 
+const CLOUD_PROVIDERS: readonly AuthProvider[] = ["anthropic", "openai", "gemini", "antigravity"]
+/** True (and prints an error + sets exit code) when `p` is given but not a known provider. */
+function rejectInvalidProvider(p: string | undefined): boolean {
+  if (p !== undefined && !(CLOUD_PROVIDERS as readonly string[]).includes(p)) {
+    console.log(`Unknown provider '${p}'. Use one of: ${CLOUD_PROVIDERS.join(", ")}.`);
+    process.exitCode = 1;
+    return true;
+  }
+  return false;
+}
+
 function fmtExpiry(expires?: number): string {
   if (!expires) return "";
   const ms = expires - Date.now();
@@ -34,13 +51,20 @@ function fmtExpiry(expires?: number): string {
 
 async function runAuthStatus(): Promise<void> {
   const cfg = await readGlobalConfig();
-  console.log("\n=== joc auth status ===");
+  console.log("\n=== jeo auth status ===");
   console.log("Provider     API key   OAuth");
-  for (const p of ["anthropic", "openai", "gemini"] as AuthProvider[]) {
+  for (const p of ["anthropic", "openai", "gemini", "antigravity"] as AuthProvider[]) {
     const snap = await snapshotProvider(p);
-    const key = snap.apiKey ? "set" : "—";
+    const key = p === "antigravity" ? "—" : (snap.apiKey ? "set" : "—");
     let oauth = "—";
-    if (snap.oauth) {
+    if (p === "antigravity") {
+      const fallback = snap.oauth ? snap : await snapshotProvider("gemini");
+      if (fallback.oauth) {
+        oauth = snap.oauth
+          ? `set (refreshable)${fmtExpiry(snap.oauthExpires)}${snap.oauthEmail ? ` <${snap.oauthEmail}>` : ""}`
+          : "via gemini fallback";
+      }
+    } else if (snap.oauth) {
       oauth = snap.oauthHasRefresh ? "set (refreshable)" : "set (manual)";
       oauth += fmtExpiry(snap.oauthExpires);
       if (snap.oauthEmail) oauth += ` <${snap.oauthEmail}>`;
@@ -55,7 +79,19 @@ async function runAuthStatus(): Promise<void> {
 async function runAuthLogin(rest: string[]): Promise<void> {
   const tokenIdx = rest.indexOf("--token");
   const manualToken = tokenIdx >= 0 ? rest[tokenIdx + 1] : undefined;
-  const provider = rest.find((a, i) => a !== "--token" && rest[i - 1] !== "--token") as AuthProvider | undefined;
+  const isImport = rest.includes("--import");
+  const provider = rest.find((a, i) => a !== "--token" && rest[i - 1] !== "--token" && a !== "--import") as AuthProvider | undefined;
+
+  if (rejectInvalidProvider(provider)) return;
+
+  if (isImport) {
+    if (provider !== "gemini") {
+      console.log(`[FAILED] Import is only supported for 'gemini' provider.`);
+      process.exitCode = 1;
+      return;
+    }
+    return runAuthImport(["gemini"]);
+  }
 
   const rl = createInterface({ input: process.stdin, output: process.stdout });
   const chosen = provider ?? (await selectProvider(rl));
@@ -72,37 +108,142 @@ async function runAuthLogin(rest: string[]): Promise<void> {
     return;
   }
 
-  const flow = OAUTH_FLOW_REGISTRY[chosen];
-  console.log(`\n=== joc auth login — ${flow.label} ===`);
-  if (!flow.verifiedEndToEnd && flow.note) console.log(`Note: ${flow.note}`);
-  for (const line of OAUTH_FLOWS[chosen].instructions) console.log("  " + line);
-  console.log("");
+  try {
+    const { email } = await interactiveOAuthLogin(chosen, rl);
+    console.log(`\n[SUCCESS] OAuth login complete for ${chosen}${email ? ` (${email})` : ""}.`);
+    console.log("Stored access + refresh tokens in ~/.jeo/config.json; jeo will auto-refresh on expiry.");
+  } catch (err) {
+    console.log(`\n[FAILED] ${(err as Error).message}`);
+    console.log("Tip: paste the redirect URL when prompted, or use 'jeo auth login <provider> --token <bearer>'.");
+    process.exitCode = 1;
+  } finally {
+    rl.close();
+  }
+}
+
+async function runAuthImport(rest: string[]): Promise<void> {
+  const provider = rest.find(a => a !== "--import") as AuthProvider | undefined;
+  if (!provider) {
+    console.log("Usage: jeo auth import <provider>");
+    process.exitCode = 1;
+    return;
+  }
+  if (rejectInvalidProvider(provider)) return;
+  if (provider !== "gemini") {
+    console.log(`[FAILED] Import is only supported for 'gemini' provider.`);
+    process.exitCode = 1;
+    return;
+  }
 
+  try {
+    const credsPath = jeoEnv("GEMINI_CREDS_PATH") || path.join(os.homedir(), ".gemini", "oauth_creds.json");
+    let content: string;
+    try {
+      content = await fs.readFile(credsPath, "utf-8");
+    } catch (err: any) {
+      console.log(`[FAILED] Failed to read Gemini credentials file: ${err.message}`);
+      process.exitCode = 1;
+      return;
+    }
+
+    let creds: any;
+    try {
+      creds = JSON.parse(content);
+    } catch (err: any) {
+      console.log(`[FAILED] Failed to parse Gemini credentials JSON: ${err.message}`);
+      process.exitCode = 1;
+      return;
+    }
+
+    if (!creds || !creds.access_token) {
+      console.log(`[FAILED] Missing access_token in Gemini credentials.`);
+      process.exitCode = 1;
+      return;
+    }
+
+    let email: string | undefined;
+    if (creds.id_token) {
+      const parts = creds.id_token.split(".");
+      if (parts.length >= 2) {
+        try {
+          const base64 = parts[1].replace(/-/g, "+").replace(/_/g, "/");
+          const payload = JSON.parse(atob(base64));
+          email = payload.email;
+        } catch {}
+      }
+    }
+
+    let expires = typeof creds.expiry_date === "number" ? creds.expiry_date : (typeof creds.expiry_date === "string" ? parseInt(creds.expiry_date, 10) : undefined);
+    if (isNaN(expires as number)) expires = undefined;
+
+    const imported: StoredOAuth = {
+      access: creds.access_token,
+      refresh: creds.refresh_token,
+      expires,
+      email,
+    };
+
+    const { setOauthCredential } = await import("../auth/storage");
+    await setOauthCredential("gemini", imported);
+
+    console.log(`[SUCCESS] Imported OAuth credentials for gemini (also usable as the Antigravity fallback when the backend accepts gemini-cli tokens).`);
+    if (email) {
+      console.log(`Account email: ${email}`);
+    }
+    const expiryMsg = expires ? fmtExpiry(expires) : "";
+    console.log(`Expiry status:${expiryMsg || " valid"}`);
+  } catch (err: any) {
+    console.log(`[FAILED] ${err.message}`);
+    process.exitCode = 1;
+  }
+}
+
+/** Prompt object the OAuth manual-code fallback needs (a readline interface satisfies it). */
+export interface OAuthPrompt {
+  question(query: string, options?: { signal?: AbortSignal }): Promise<string>;
+}
+
+/**
+ * Run the interactive OAuth login flow for a provider using an existing prompt
+ * (readline) interface. Shared by `jeo auth login` and the REPL `/provider login`.
+ * Prints flow instructions, opens the browser, and resolves with the account email.
+ */
+export async function interactiveOAuthLogin(
+  provider: AuthProvider,
+  prompt: OAuthPrompt,
+  log: (s: string) => void = console.log,
+): Promise<{ email?: string }> {
+  const flow = OAUTH_FLOW_REGISTRY[provider];
+  log(`\n=== OAuth login — ${flow.label} ===`);
+  if (!flow.verifiedEndToEnd && flow.note) log(`Note: ${flow.note}`);
+  for (const line of OAUTH_FLOWS[provider].instructions) log("  " + line);
+  log("");
+
+  // Abort the pending "Paste redirect URL…" question once the flow settles.
+  // Without this the dangling readline question survives a SUCCESS/FAILED
+  // result, reprints its prompt over the result line, and queues in FRONT of
+  // any follow-up question (the `jeo setup` API-key fallback appeared hung).
+  const ac = new AbortController();
   const ctrl: OAuthController = {
+    signal: ac.signal,
     onAuth: ({ url, instructions }) => {
-      console.log(`Opening browser:\n  ${url}\n`);
-      if (instructions) console.log(instructions + "\n");
+      log(`Opening browser:\n  ${url}\n`);
+      if (instructions) log(instructions + "\n");
       void openInBrowser(url);
     },
-    onProgress: msg => console.log(`  … ${msg}`),
+    onProgress: msg => log(`  … ${msg}`),
     onManualCodeInput: async () =>
-      (await rl.question("Paste redirect URL or code (or wait for the browser callback): ")).trim(),
+      (await prompt.question("Paste redirect URL or code (or wait for the browser callback): ", { signal: ac.signal })).trim(),
   };
-
   try {
-    const { email } = await interactiveLogin(chosen, ctrl);
-    console.log(`\n[SUCCESS] OAuth login complete for ${chosen}${email ? ` (${email})` : ""}.`);
-    console.log("Stored access + refresh tokens in ~/.joc/config.json; joc will auto-refresh on expiry.");
-  } catch (err) {
-    console.log(`\n[FAILED] ${(err as Error).message}`);
-    console.log("Tip: paste the redirect URL when prompted, or use 'joc auth login <provider> --token <bearer>'.");
-    process.exitCode = 1;
+    return await interactiveLogin(provider, ctrl);
   } finally {
-    rl.close();
+    ac.abort();
   }
 }
 
 async function runAuthLogout(provider?: AuthProvider): Promise<void> {
+  if (rejectInvalidProvider(provider)) return;
   const rl = createInterface({ input: process.stdin, output: process.stdout });
   const chosen = provider ?? (await selectProvider(rl, "logout"));
   rl.close();
@@ -113,10 +254,11 @@ async function runAuthLogout(provider?: AuthProvider): Promise<void> {
 
 async function runAuthRefresh(provider?: AuthProvider): Promise<void> {
   if (!provider) {
-    console.log("Usage: joc auth refresh <provider>");
+    console.log("Usage: jeo auth refresh <provider>");
     process.exitCode = 1;
     return;
   }
+  if (rejectInvalidProvider(provider)) return;
   const result = await refreshOAuthToken(provider);
   console.log(
     result.refreshed