@bitkyc08/opencodex 2.7.31 → 2.7.33

package/src/cli/models.ts

@@ -1,11 +1,18 @@
 /**
- * `ocx models` subcommand — list available models from configured providers.
- *
- * Usage:
- *   ocx models [--provider <name>] [--json]
+ * `ocx models` subcommand — list configured models and manage custom models.
  */
-import { hasOwnProvider, loadConfig } from "../config";
-import type { OcxConfig } from "../types";
+import { randomUUID } from "node:crypto";
+import { createInterface } from "node:readline/promises";
+import { syncModelsToCodex } from "../codex/sync";
+import { hasOwnProvider, isValidProviderName, loadConfig, saveConfig } from "../config";
+import { routedSlug } from "../providers/slug-codec";
+import { findLiveProxy } from "../server/proxy-liveness";
+import type { OcxConfig, OcxCustomModel } from "../types";
+
+const ADD_USAGE = "Usage: ocx models add <provider> <modelId> [--display-name <name>] [--context-window <tokens>] [--modalities text,image,audio]";
+const REMOVE_USAGE = "Usage: ocx models remove <customId|provider/modelId> [--yes]";
+const LIST_CUSTOM_USAGE = "Usage: ocx models list-custom [--json]";
+const ALLOWED_MODALITIES = new Set(["text", "image", "audio"]);
 
 interface ModelEntry {
   provider: string;
@@ -75,7 +82,175 @@ function consumeFlagValue(args: string[], flag: string): string | undefined {
   return value;
 }
 
-export function handleModels(args: string[]): void {
+function fail(message: string, usage?: string): never {
+  console.error(`Error: ${message}`);
+  if (usage) console.error(usage);
+  process.exit(1);
+}
+
+function rejectUnexpectedArgs(args: string[], usage: string): void {
+  if (args.length === 0) return;
+  const unknown = args.filter(arg => arg.startsWith("-"));
+  fail(
+    unknown.length > 0
+      ? `Unknown flag(s): ${unknown.join(", ")}`
+      : `Unexpected argument(s): ${args.join(", ")}`,
+    usage,
+  );
+}
+
+async function syncCustomModelsIfLive(): Promise<void> {
+  const live = await findLiveProxy();
+  if (!live) return;
+  await syncModelsToCodex(live.port).catch(error => {
+    console.error(`Warning: custom model saved, but catalog sync failed: ${error instanceof Error ? error.message : String(error)}`);
+  });
+}
+
+async function handleCustomAdd(args: string[]): Promise<void> {
+  const rest = [...args];
+  const provider = rest.shift()?.trim() ?? "";
+  const modelId = rest.shift()?.trim() ?? "";
+  const displayNameValue = consumeFlagValue(rest, "--display-name");
+  const contextWindowValue = consumeFlagValue(rest, "--context-window");
+  const modalitiesValue = consumeFlagValue(rest, "--modalities");
+  rejectUnexpectedArgs(rest, ADD_USAGE);
+
+  if (!provider || !modelId) fail("provider and modelId are required", ADD_USAGE);
+  if (!isValidProviderName(provider)) fail(`invalid provider name "${provider}"`);
+  if (modelId.includes("/")) fail("modelId must not contain /");
+
+  const config = loadConfig();
+  if (!hasOwnProvider(config.providers, provider)) {
+    fail(`provider "${provider}" is not configured. See: ocx provider list`);
+  }
+
+  const displayName = displayNameValue?.trim() || undefined;
+  if (displayName?.includes("/")) fail("displayName must not contain /");
+
+  let contextWindow: number | undefined;
+  if (contextWindowValue !== undefined) {
+    contextWindow = Number(contextWindowValue);
+    if (!Number.isInteger(contextWindow) || contextWindow <= 0) {
+      fail("context window must be a positive integer");
+    }
+  }
+
+  let inputModalities: string[] | undefined;
+  if (modalitiesValue !== undefined) {
+    inputModalities = modalitiesValue.split(",").map(value => value.trim());
+    const invalid = inputModalities.filter(value => !ALLOWED_MODALITIES.has(value));
+    if (inputModalities.length === 0 || invalid.length > 0) {
+      fail("modalities must be comma-separated values from text|image|audio");
+    }
+    inputModalities = [...new Set(inputModalities)];
+  }
+
+  const existing = config.customModels ?? [];
+  const slug = routedSlug(provider, modelId);
+  if (existing.some(model => routedSlug(model.provider, model.modelId) === slug)) {
+    fail(`custom model "${slug}" already exists`);
+  }
+
+  const entry: OcxCustomModel = {
+    id: randomUUID(),
+    provider,
+    modelId,
+    ...(displayName ? { displayName } : {}),
+    ...(contextWindow ? { contextWindow } : {}),
+    ...(inputModalities ? { inputModalities } : {}),
+    addedAt: new Date().toISOString(),
+  };
+  config.customModels = [...existing, entry];
+  saveConfig(config);
+  await syncCustomModelsIfLive();
+  console.log(`Added custom model ${slug} (${entry.id}).`);
+}
+
+async function confirmCustomRemoval(model: OcxCustomModel): Promise<boolean> {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    fail("remove requires --yes in non-interactive mode");
+  }
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const answer = (await rl.question(`Remove custom model ${routedSlug(model.provider, model.modelId)}? [y/N] `)).trim().toLowerCase();
+    return answer === "y" || answer === "yes";
+  } finally {
+    rl.close();
+  }
+}
+
+async function handleCustomRemove(args: string[]): Promise<void> {
+  const rest = [...args];
+  const confirmed = consumeFlag(rest, "--yes");
+  const target = rest.shift()?.trim() ?? "";
+  rejectUnexpectedArgs(rest, REMOVE_USAGE);
+  if (!target) fail("custom model id or provider/modelId is required", REMOVE_USAGE);
+
+  const config = loadConfig();
+  const existing = config.customModels ?? [];
+  const index = target.includes("/")
+    ? existing.findIndex(model => routedSlug(model.provider, model.modelId) === target)
+    : existing.findIndex(model => model.id === target);
+  if (index === -1) fail(`custom model "${target}" not found`);
+
+  const model = existing[index];
+  if (!confirmed && !(await confirmCustomRemoval(model))) {
+    console.log("Cancelled.");
+    return;
+  }
+
+  const next = existing.filter((_, modelIndex) => modelIndex !== index);
+  config.customModels = next.length > 0 ? next : undefined;
+  saveConfig(config);
+  await syncCustomModelsIfLive();
+  console.log(`Removed custom model ${routedSlug(model.provider, model.modelId)}.`);
+}
+
+function customModelCells(model: OcxCustomModel): string[] {
+  return [
+    model.id.slice(0, 8),
+    model.modelId,
+    model.displayName ?? "-",
+    model.contextWindow ? `${Math.round(model.contextWindow / 1000)}k` : "-",
+    model.inputModalities?.join(",") ?? "-",
+  ];
+}
+
+function printCustomModelGroup(provider: string, models: OcxCustomModel[]): void {
+  const rows = models.map(customModelCells);
+  const headers = ["ID", "MODEL", "DISPLAY NAME", "CONTEXT", "MODALITIES"];
+  const widths = headers.map((header, column) => Math.max(header.length, ...rows.map(row => row[column].length)));
+  const line = (cells: string[]) => cells.map((cell, column) => cell.padEnd(widths[column])).join("  ");
+  console.log(`${provider}:`);
+  console.log(`  ${line(headers)}`);
+  for (const row of rows) console.log(`  ${line(row)}`);
+  console.log();
+}
+
+function handleCustomList(args: string[]): void {
+  const rest = [...args];
+  const wantsJson = consumeFlag(rest, "--json");
+  rejectUnexpectedArgs(rest, LIST_CUSTOM_USAGE);
+  const models = loadConfig().customModels ?? [];
+  if (wantsJson) {
+    console.log(JSON.stringify(models, null, 2));
+    return;
+  }
+  if (models.length === 0) {
+    console.log("No custom models registered.");
+    return;
+  }
+  const byProvider = new Map<string, OcxCustomModel[]>();
+  for (const model of models) {
+    const group = byProvider.get(model.provider) ?? [];
+    group.push(model);
+    byProvider.set(model.provider, group);
+  }
+  for (const [provider, providerModels] of byProvider) printCustomModelGroup(provider, providerModels);
+}
+
+function handleConfiguredModels(args: string[]): void {
   const restArgs = [...args];
   const wantsJson = consumeFlag(restArgs, "--json");
   const providerFilter = consumeFlagValue(restArgs, "--provider");
@@ -136,3 +311,27 @@ export function handleModels(args: string[]): void {
   console.log("* = default model for provider");
   console.log("Note: providers with liveModels may have additional models at runtime.");
 }
+
+function runCustomCommand(command: Promise<void>): void {
+  command.catch(error => {
+    console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
+    process.exitCode = 1;
+  });
+}
+
+export function handleModels(args: string[]): void {
+  const [subcommand, ...rest] = args;
+  if (subcommand === "add") {
+    runCustomCommand(handleCustomAdd(rest));
+    return;
+  }
+  if (subcommand === "remove") {
+    runCustomCommand(handleCustomRemove(rest));
+    return;
+  }
+  if (subcommand === "list-custom") {
+    handleCustomList(rest);
+    return;
+  }
+  handleConfiguredModels(subcommand === "list" ? rest : args);
+}

package/src/codex/auth-api.ts

@@ -77,6 +77,7 @@ function poolAccountDto(
   return {
     id: account.id,
     email: maskEmail(account.email) ?? account.email,
+    ...(account.alias !== undefined ? { alias: account.alias } : {}),
     ...(account.plan !== undefined ? { plan: account.plan } : {}),
     ...(account.logLabel !== undefined ? { logLabel: account.logLabel } : {}),
     isMain: false,
@@ -168,9 +169,13 @@ async function verifyCodexAccountWarmup(
 }
 
 function expireCodexAuthFlow(flowId: string | null, error = "Login cancelled"): void {
-  if (!flowId) return;
-  codexAuthLoginState.set(flowId, { status: "error", error, doneAt: Date.now() });
-  setTimeout(() => codexAuthLoginState.delete(flowId), 30_000);
+  const ids = flowId
+    ? [flowId]
+    : [...codexAuthLoginState].filter(([, state]) => state.status === "pending").map(([id]) => id);
+  for (const id of ids) {
+    codexAuthLoginState.set(id, { status: "error", error, doneAt: Date.now() });
+    setTimeout(() => codexAuthLoginState.delete(id), 30_000);
+  }
 }
 
 let mainAccountCache: { email: string | null; plan: string | null; quota: Omit<StoredAccountQuota, "updatedAt"> | null; ts: number } | null = null;
@@ -258,6 +263,7 @@ interface PoolQuotaResult {
 
 export interface CodexAuthAccountDto {
   id: string;
+  alias?: string;
   email: string;
   plan?: string | null;
   logLabel?: string;
@@ -442,6 +448,24 @@ export async function handleCodexAuthAPI(
     return jsonResponse({ ok: true });
   }
 
+  if (url.pathname === "/api/codex-auth/accounts/alias" && req.method === "PUT") {
+    const body = await req.json().catch(() => ({})) as { id?: unknown; alias?: unknown };
+    const id = typeof body.id === "string" ? body.id.trim() : "";
+    const alias = typeof body.alias === "string" ? body.alias.trim() : "";
+    if (!id || !ACCOUNT_ID_RE.test(id)) return jsonResponse({ error: "Invalid account id format" }, 400);
+    if (id === MAIN_CODEX_ACCOUNT_ID) return jsonResponse({ error: "Main Codex account alias is not configurable" }, 400);
+    if (typeof body.alias !== "string" || alias.length > 80 || /[\x00-\x1f\x7f]/.test(alias)) {
+      return jsonResponse({ error: "Alias must be a string of at most 80 printable characters" }, 400);
+    }
+    const runtimeConfig = getRuntimeConfig(config);
+    const account = (runtimeConfig.codexAccounts ?? []).find(candidate => candidate.id === id && !candidate.isMain);
+    if (!account) return jsonResponse({ error: "Account not found" }, 404);
+    if (alias) account.alias = alias;
+    else delete account.alias;
+    saveRuntimeConfig(config, runtimeConfig);
+    return jsonResponse({ ok: true, id, alias: alias || null });
+  }
+
   if (url.pathname === "/api/codex-auth/active" && req.method === "PUT") {
     let body: { accountId: string | null };
     try { body = (await req.json()) as typeof body; } catch { return jsonResponse({ error: "Invalid JSON" }, 400); }

package/src/codex/catalog.ts

@@ -690,7 +690,7 @@ export function materializeBundledCodexCatalog(path: string, deps: BundledCatalo
 
 function loadCatalogForSync(path: string): RawCatalog | null {
   const bundled = isDefaultCatalogPath(path) ? loadBundledCodexCatalog() : null;
-  if (bundled) return bundled;
+  if (bundled) return JSON.parse(JSON.stringify(bundled)) as RawCatalog;
   const catalog = readCatalog(path);
   if (catalog && findNativeTemplate(catalog)) return catalog;
   return readCatalog(catalogBackupPathFor(path))
@@ -829,6 +829,66 @@ function ensureUltraReasoningLevel(entry: RawEntry): void {
   entry.supported_reasoning_levels = levels;
 }
 
+/** Reasoning-effort labels accepted by the installed Codex binary's bundled catalog. */
+export function codexSupportedReasoningEfforts(deps: BundledCatalogDeps = {}): Set<string> | null {
+  const bundled = loadBundledCodexCatalog(deps);
+  if (!bundled) return null;
+  const efforts = new Set<string>();
+  for (const model of bundled.models ?? []) {
+    if (typeof model.slug !== "string" || model.slug.includes("/")) continue;
+    const levels = Array.isArray(model.supported_reasoning_levels) ? model.supported_reasoning_levels : [];
+    for (const level of levels) {
+      const effort = (level as { effort?: unknown })?.effort;
+      if (typeof effort === "string") efforts.add(effort);
+    }
+    if (typeof model.default_reasoning_level === "string") efforts.add(model.default_reasoning_level);
+  }
+  return efforts.size > 0 ? efforts : null;
+}
+
+/** Highest surviving rung at or below the original default, with a conservative empty fallback. */
+export function clampedDefaultEffort(original: string, surviving: readonly string[]): string {
+  if (surviving.length === 0) return "medium";
+  const ranked = [...surviving]
+    .map(effort => ({ effort, rank: codexEffortRank(effort) }))
+    .sort((a, b) => a.rank - b.rank);
+  const originalRank = codexEffortRank(original);
+  const atOrBelow = ranked.filter(item => item.rank >= 0 && item.rank <= originalRank);
+  return (atOrBelow.at(-1) ?? ranked[0]!).effort;
+}
+
+/** Remove reasoning efforts the installed Codex binary cannot deserialize from one entry. */
+export function clampEntryToCodexSupportedEfforts(entry: RawEntry, supported: Set<string> | null): void {
+  if (!supported) return;
+  const levels = Array.isArray(entry.supported_reasoning_levels)
+    ? entry.supported_reasoning_levels as Array<{ effort?: string }>
+    : null;
+  if (levels && levels.length > 0) {
+    const kept = levels.filter(level => typeof level?.effort === "string" && supported.has(level.effort));
+    entry.supported_reasoning_levels = kept.length > 0
+      ? kept
+      : CODEX_REASONING_LEVELS
+        .filter(level => level.effort === "low" || level.effort === "medium" || level.effort === "high")
+        .map(level => ({ ...level }));
+  }
+  const currentDefault = entry.default_reasoning_level;
+  if (typeof currentDefault === "string" && !supported.has(currentDefault)) {
+    const surviving = (Array.isArray(entry.supported_reasoning_levels) ? entry.supported_reasoning_levels : [])
+      .flatMap(level => typeof (level as { effort?: string })?.effort === "string"
+        ? [(level as { effort: string }).effort]
+        : []);
+    entry.default_reasoning_level = clampedDefaultEffort(currentDefault, surviving);
+  }
+}
+
+/** Clamp every catalog entry to the reasoning ladder accepted by the installed Codex binary. */
+export function clampCatalogModelsToCodexSupport(models: RawEntry[], deps: BundledCatalogDeps = {}): RawEntry[] {
+  const supported = codexSupportedReasoningEfforts(deps);
+  if (!supported) return models;
+  for (const entry of models) clampEntryToCodexSupportedEfforts(entry, supported);
+  return models;
+}
+
 /**
  * Native entry from the pinned upstream snapshot, finished for emission. Keeps the entry's
  * OWN identity (display_name, description, priority, availability_nux — it is the model's own
@@ -1450,7 +1510,16 @@ export async function gatherRoutedModels(config: OcxConfig): Promise<CatalogMode
     else warnUncataloguedComboOnce(id, combo, members);
   }
   all.sort((a, b) => (a.provider === b.provider ? a.id.localeCompare(b.id) : a.provider.localeCompare(b.provider)));
-  return all;
+  const customModels = (config.customModels ?? []).map(cm => ({
+    id: cm.modelId,
+    provider: cm.provider,
+    ...(cm.contextWindow ? { contextWindow: cm.contextWindow } : {}),
+    ...(cm.inputModalities ? { inputModalities: cm.inputModalities } : {}),
+  }));
+  // Custom rows override discovered rows that encode to the same Codex-facing slug.
+  const customKeys = new Set(customModels.map(c => routedSlug(c.provider, c.id)));
+  const deduped = all.filter(m => !customKeys.has(routedSlug(m.provider, m.id)));
+  return [...deduped, ...customModels];
 }
 
 const openAiApiCollisionWarnings = new Set<string>();
@@ -1926,6 +1995,7 @@ export async function syncCatalogModels(config: OcxConfig): Promise<{ added: num
   // native template can never leak supports_websockets while the flag is off.
   const wsEnabled = websocketsEnabled(config);
   catalog.models = mergeCatalogEntriesForSync(catalog.models ?? [], goEntries, baseline, featured, wsEnabled, goIds, template, disabledNativeSlugs(config), gatheredProviderNames, multiAgentMode, exactComboSlugs, hasPhysicalComboProvider);
+  clampCatalogModelsToCodexSupport(catalog.models);
 
   atomicWriteFile(catalogPath, JSON.stringify(catalog, null, 2) + "\n");
   return { added: goEntries.length, path: catalogPath };

package/src/config.ts

@@ -6,7 +6,8 @@ import * as z from "zod/v4";
 import { comboConfigIssues } from "./combos/types";
 import { hardenSecretDir, hardenSecretPath } from "./lib/windows-secret-acl";
 import { providerDestinationConfigError } from "./lib/destination-policy";
-import type { OcxConfig } from "./types";
+import { openRouterRoutingConfigError } from "./providers/openrouter-routing";
+import { OPENAI_PROVIDER_TIER_VERSION, type OcxConfig } from "./types";
 
 let _atomicSeq = 0;
 
@@ -155,6 +156,28 @@ function isAlreadyExistsError(error: unknown): boolean {
   return (error as NodeJS.ErrnoException | undefined)?.code === "EEXIST";
 }
 
+/**
+ * Classify an existing `.pre-openai-tiers-v2.bak` snapshot.
+ *
+ * - `"stale"`: unparseable JSON (not written by us / truncated) or already a
+ *   post-migration (tier v2) snapshot — safe to delete or replace.
+ * - `"rollback"`: parses as a valid pre-migration (v1) config — a
+ *   user-intentional rollback point that must never be silently destroyed.
+ *
+ * Shared by the startup migration backup path and `ocx init` cleanup so both
+ * apply the same preservation policy (issue #257 / sol review 260722).
+ */
+export function classifyOpenAiTierBackup(backupBytes: Uint8Array): "stale" | "rollback" {
+  try {
+    // Use Buffer.from to ensure proper UTF-8 decoding from Uint8Array/Buffer.
+    const parsed = JSON.parse(Buffer.from(backupBytes).toString("utf8")) as Record<string, unknown>;
+    return parsed.openaiProviderTierVersion === 2 ? "stale" : "rollback";
+  } catch {
+    // Unparseable: not a config file we created, treat as stale.
+    return "stale";
+  }
+}
+
 export function backupConfigBeforeOpenAiTierMigration(
   configPath = getConfigPath(),
   io: OpenAiTierBackupIO = {
@@ -178,8 +201,24 @@ export function backupConfigBeforeOpenAiTierMigration(
   // docs/fixtures and is never reused or overwritten as the v2 snapshot.
   const backup = `${source}.pre-openai-tiers-v2.bak`;
   if (io.exists(backup)) {
-    if (!sameBytes(original, io.read(backup))) throw new OpenAiTierBackupCollisionError();
-    return "reused";
+    if (!sameBytes(original, io.read(backup))) {
+      // The backup differs from the current config. Only treat it as stale when it is
+      // clearly not a user-intentional rollback point:
+      //   - unparseable JSON: written by a different tool or truncated
+      //   - already at tier version 2: the backup is from a post-migration config (e.g.
+      //     ocx init wrote a fresh v2 config, making the old backup obsolete)
+      // A backup that parses as a valid pre-migration (v1) config is kept as-is and
+      // we throw a collision error, because silently replacing a user-created rollback
+      // point would be surprising and potentially destructive.
+      const backupBytes = io.read(backup);
+      if (classifyOpenAiTierBackup(backupBytes) === "rollback") {
+        throw new OpenAiTierBackupCollisionError();
+      }
+      console.warn("[openai-provider-migration] Replacing stale pre-migration backup (post-migration config was rewritten since last migration).");
+      io.unlink(backup);
+    } else {
+      return "reused";
+    }
   }
   const temp = `${backup}.ocx.${process.pid}.${++_atomicSeq}.tmp`;
   let published = false;
@@ -374,6 +413,20 @@ const configSchema = z.object({
       });
     }
     const provider = config.providers[name];
+    const openRouterRoutingError = openRouterRoutingConfigError(provider);
+    if (openRouterRoutingError) {
+      ctx.addIssue({
+        code: "custom",
+        path: [
+          "providers",
+          name,
+          openRouterRoutingError.startsWith("modelOpenRouterRouting")
+            ? "modelOpenRouterRouting"
+            : "openRouterRouting",
+        ],
+        message: openRouterRoutingError,
+      });
+    }
     if (Object.hasOwn(provider, "virtualModels")) {
       ctx.addIssue({
         code: "custom",
@@ -641,6 +694,10 @@ export function getDefaultConfig(): OcxConfig {
   // Adding extra providers (e.g. opencode-go) and switching defaultProvider is a user/runtime choice.
   return {
     port: 10100,
+    // Fresh/re-initialized configs are already written in the current three-tier
+    // OpenAI shape. Mark them as such so startup does not mistake them for a
+    // legacy config and collide with an immutable backup from an earlier setup.
+    openaiProviderTierVersion: OPENAI_PROVIDER_TIER_VERSION,
     providers: {
       openai: {
         adapter: "openai-responses",

package/src/oauth/github-copilot.ts

@@ -395,6 +395,7 @@ export async function loginGithubCopilot(ctrl: OAuthController): Promise<OAuthCr
   ctrl.onAuth?.({
     url: device.verifyUrl,
     instructions: `Enter code: ${device.userCode}`,
+    deviceCode: device.userCode,
   });
   ctrl.onProgress?.("Waiting for GitHub device authorization…");
   const github = await pollGithubDeviceToken(

package/src/oauth/index.ts

@@ -646,7 +646,7 @@ export function submitManualLoginCode(provider: string, input: string): { ok: tr
   return { ok: true };
 }
 
-export interface OAuthAccountSummary { id: string; email?: string; active: boolean; needsReauth?: boolean; expiresAt?: number }
+export interface OAuthAccountSummary { id: string; alias?: string; email?: string; active: boolean; needsReauth?: boolean; expiresAt?: number }
 
 export function getLoginStatus(provider: string): { loggedIn: boolean; email?: string; source?: OAuthCredentials["source"]; error?: string; done: boolean; activeAccountId?: string; accounts?: OAuthAccountSummary[] } {
   const cred = getCredential(provider);
@@ -654,6 +654,7 @@ export function getLoginStatus(provider: string): { loggedIn: boolean; email?: s
   const set = getAccountSet(provider);
   const accounts: OAuthAccountSummary[] | undefined = set?.accounts.map(a => ({
     id: a.id,
+    ...(a.alias ? { alias: a.alias } : {}),
     email: maskEmail(a.credential.email) ?? undefined,
     active: a.id === set.activeAccountId,
     ...(a.needsReauth ? { needsReauth: true } : {}),
@@ -695,7 +696,7 @@ export function cancelLoginFlow(provider: string): boolean {
   return true;
 }
 
-export async function startLoginFlow(provider: string, opts?: LoginOpts): Promise<{ url: string; instructions?: string }> {
+export async function startLoginFlow(provider: string, opts?: LoginOpts): Promise<{ url: string; instructions?: string; deviceCode?: string }> {
   const def = OAUTH_PROVIDERS[provider];
   if (!def) throw new UnsupportedOAuthProviderError(provider);
   const existing = loginState.get(provider);
@@ -709,9 +710,9 @@ export async function startLoginFlow(provider: string, opts?: LoginOpts): Promis
   return new Promise((resolve, reject) => {
     let urlResolved = false;
     const ctrl: OAuthController = {
-      onAuth: ({ url, instructions }) => {
+      onAuth: ({ url, instructions, deviceCode }) => {
         urlResolved = true;
-        resolve({ url, instructions });
+        resolve({ url, instructions, deviceCode });
       },
       onProgress: () => {},
       // GUI fallback when the browser cannot hit the loopback callback server.

package/src/oauth/kiro.ts

@@ -50,7 +50,9 @@ export function readKiroCliSqlite(): ImportedKiroToken | null {
 
 /**
  * Import-first login: kiro-cli SQLite → KIRO_ACCESS_TOKEN env → manual paste (CLI only).
- * In GUI (no onManualCodeInput) with no SQLite token and no env, throws a clear error — never hangs.
+ * When no local token is available, resolves the login flow via onAuth with instructions
+ * so the GUI renders the paste-input field, then blocks on onManualCodeInput for the token.
+ * If neither onAuth nor onManualCodeInput is available, throws a clear error.
  */
 export async function loginKiro(ctrl: OAuthController): Promise<OAuthCredentials> {
   const imported = readImportedKiroCredential();
@@ -71,6 +73,15 @@ export async function loginKiro(ctrl: OAuthController): Promise<OAuthCredentials
   }
 
   if (ctrl.onManualCodeInput) {
+    // Resolve the login flow immediately so the GUI receives instructions and
+    // shows the paste-input field. Without this, onManualCodeInput blocks
+    // forever and the HTTP response never reaches the dashboard.
+    ctrl.onAuth?.({
+      url: "",
+      instructions:
+        "No kiro-cli token found. Paste a Kiro access token below (starts with 'aoa'). " +
+        "Run `kiro-cli login` first, or set KIRO_ACCESS_TOKEN.",
+    });
     ctrl.onProgress?.("No kiro-cli token found. Paste a Kiro access token (starts with 'aoa').");
     const raw = (await ctrl.onManualCodeInput()).trim();
     if (raw) return { access: raw, refresh: "", expires: Date.now() + 3600_000, source: "manual" };

package/src/oauth/store.ts

@@ -179,6 +179,7 @@ function normalizeAccount(value: unknown): ProviderAccount | null {
   const credential = normalizeCredential(candidate.credential);
   if (!credential) return null;
   const account: ProviderAccount = { id: candidate.id, credential };
+  if (typeof candidate.alias === "string" && candidate.alias.trim()) account.alias = candidate.alias.trim();
   if (candidate.needsReauth === true) account.needsReauth = true;
   if (typeof candidate.addedAt === "number") account.addedAt = candidate.addedAt;
   return account;
@@ -341,6 +342,16 @@ export async function setActiveAccount(provider: string, accountId: string): Pro
   });
 }
 
+export async function setAccountAlias(provider: string, accountId: string, alias: string | undefined): Promise<boolean> {
+  return await mutateStore(store => {
+    const account = store[provider]?.accounts.find(a => a.id === accountId);
+    if (!account) return false;
+    if (alias) account.alias = alias;
+    else delete account.alias;
+    return true;
+  });
+}
+
 /** Remove one account by id; active removal promotes the first remaining account. */
 export async function removeAccount(provider: string, accountId: string): Promise<boolean> {
   return await mutateStore(store => {

package/src/oauth/types.ts

@@ -21,6 +21,8 @@ export type OAuthCredentials = {
 export interface ProviderAccount {
   /** Stable short id, generated once at append time; never re-derived after rotation. */
   id: string;
+  /** User-owned display label; never participates in auth identity or routing. */
+  alias?: string;
   credential: OAuthCredentials;
   /** Terminal refresh failure (invalid_grant / reused / revoked) — re-login required. */
   needsReauth?: boolean;
@@ -34,7 +36,7 @@ export interface ProviderAccountSet {
 }
 
 export interface OAuthController {
-  onAuth?(info: { url: string; instructions?: string }): void;
+  onAuth?(info: { url: string; instructions?: string; deviceCode?: string }): void;
   onProgress?(message: string): void;
   onManualCodeInput?(expectedState?: string): Promise<string>;
   signal?: AbortSignal;