@4xeoz/re-entry 0.2.3 → 0.2.5

package/README.md

@@ -19,23 +19,27 @@ npx @4xeoz/re-entry install
 This uses the deployed Re-entry Cloud Receiver by default:
 `https://reentry-cloud.vercel.app`.
 
-The interactive CLI lets you choose the Codex workspace with ↑/↓ and Enter. If you want to choose
-the workspace explicitly, pass it directly:
+The interactive CLI first offers Desktop, the current folder, or a small folder browser. Choose
+with ↑/↓ and Enter. If you want to skip the picker, pass the workspace directly:
 
 ```sh
 npx @4xeoz/re-entry install \
   --codex-cd /absolute/path/to/your/project
 ```
 
+The guided screen stays intentionally small: **Workspace → System check → Connect Re-entry**. It
+shows one clear next command when setup finishes; internal Connector IDs, credential paths, and log
+paths stay out of the normal success screen.
+
 Run this from the Host project directory, your home directory, or another normal working
 directory—not from a checked-out `runtime/local-connector` package directory. npm can treat that
 source directory as the package itself and fail to create the temporary executable link.
 
-If npm prints `sh: re-entry: command not found`, the package is present but that npm installation
-has an `npx` temporary-bin `PATH` bug. Use the reliable one-time global installation instead:
+If your npm installation cannot create the temporary `npx` executable, use the one-time global
+installation instead:
 
 ```sh
-npm install --global @4xeoz/re-entry@0.2.1
+npm install --global @4xeoz/re-entry
 re-entry install --codex-cd /absolute/path/to/your/project
 ```
 
@@ -51,8 +55,8 @@ npx --yes --package=@4xeoz/re-entry re-entry install \
 `re-entry install` performs the whole user setup:
 
 ```text
-check Node + find Codex + validate project directory
-  -> choose the Codex workspace with ↑/↓ and Enter when --codex-cd is omitted
+choose Desktop, the current folder, or another Codex workspace
+  -> check Node + find Codex + validate the selected directory
   -> request a device authorization from Re-entry
   -> show the verification URL and wait for the user to press Enter
   -> open Re-entry in the default browser

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@4xeoz/re-entry",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "type": "module",
   "description": "Outbound Local Connector process for the Re-entry Core local preview.",
   "publishConfig": {

package/src/browser-prompt.mjs

@@ -8,7 +8,7 @@ import process from "node:process";
 export async function waitForEnterToOpenBrowser(options = {}) {
   const input = options.input ?? process.stdin;
   const output = options.output ?? process.stdout;
-  const prompt = options.prompt ?? "  Press Enter to open Re-entry in your browser: ";
+  const prompt = options.prompt ?? "\n  Press Enter to open Re-entry  → ";
   const readline = createInterface({ input, output });
   try {
     await readline.question(prompt);

package/src/main.mjs

@@ -32,6 +32,7 @@ import { createTerminalUi } from "./terminal-ui.mjs";
 const DEFAULT_RECEIVER_ORIGIN = process.env.REENTRY_RECEIVER_ORIGIN ?? "https://reentry-cloud.vercel.app";
 const DEFAULT_POLL_INTERVAL_MS = 5_000;
 const DEFAULT_MAX_CONSECUTIVE_ERRORS = 5;
+const DEFAULT_PAIRING_REQUEST_TIMEOUT_MS = 20_000;
 const CONNECTOR_VERSION = readConnectorVersion();
 
 async function main() {
@@ -148,9 +149,12 @@ function readConnectorVersion() {
 }
 
 function doctor(flags, ui) {
-  if (ui.interactive) ui.begin("Check this Mac", "Read-only readiness check");
+  if (ui.interactive) {
+    ui.begin("System check", "Confirm that this Mac is ready for Re-entry.");
+    ui.section("CHECK", "Requirements");
+  }
   const readiness = inspectReadiness(flags);
-  showReadiness(readiness, ui);
+  showReadiness(readiness, ui, { detailed: true });
   if (!ui.interactive) {
     process.stdout.write(`${JSON.stringify({
       event: "connector_ready",
@@ -178,21 +182,26 @@ async function withWorkspaceDirectory(flags, ui) {
   if (flags["codex-cd"] !== undefined || !ui.interactive) {
     return { ...flags, "codex-cd": flags["codex-cd"] ?? process.cwd() };
   }
-  ui.info("Workspace", "choose the folder Codex will open");
   const selected = await chooseWorkspaceDirectory({ startDirectory: process.cwd() });
   if (!selected) throw cliFailure("connector_codex_cd_missing");
-  ui.success("Workspace", selected);
   return { ...flags, "codex-cd": selected };
 }
 
-function showReadiness(readiness, ui) {
+function showReadiness(readiness, ui, options = {}) {
   if (!ui.interactive) return;
-  ui.success("Node.js", process.versions.node);
-  ui.success("Codex", `${readiness.installation.version} · ${readiness.installation.executable}`);
-  if (readiness.workingDirectory) {
-    ui.success("Host project", readiness.workingDirectory);
-  } else {
-    ui.info("Host project", "not selected; pass --codex-cd when starting Codex");
+  ui.success("Node.js", `v${process.versions.node}`);
+  ui.success(
+    "Codex",
+    options.detailed
+      ? `${readiness.installation.version} · ${readiness.installation.executable}`
+      : "ready",
+  );
+  if (options.includeWorkspace !== false) {
+    if (readiness.workingDirectory) {
+      ui.success("Workspace", readiness.workingDirectory);
+    } else {
+      ui.info("Workspace", "selected automatically when Re-entry starts");
+    }
   }
 }
 
@@ -207,20 +216,23 @@ async function pair(flags, ui, options = {}) {
   }
   const userCode = flags.code ?? await askForPairingCode(ui);
   if (ui.interactive) ui.step("Pairing code", "received");
-  const client = new LocalConnectorPairingClient({ baseUrl: receiver });
+  const client = new LocalConnectorPairingClient({
+    baseUrl: receiver,
+    requestTimeoutMs: DEFAULT_PAIRING_REQUEST_TIMEOUT_MS,
+  });
+  if (ui.interactive) ui.wait("Contacting Re-entry…");
   const credentials = await client.pair({ userCode }, async ({ verificationUri }) => {
     if (ui.interactive) {
-      ui.step("Browser", "press Enter to open the Re-entry approval page");
-      ui.info("Open this URL", verificationUri);
+      ui.stopWait("Secure link", "ready");
+      ui.info("Browser link", verificationUri);
       await waitForEnterToOpenBrowser();
-      ui.step("Browser", "opening the Re-entry approval page");
-      ui.wait("Waiting for you to approve this Mac…");
+      ui.wait("Waiting for approval in your browser…");
     } else {
       process.stdout.write(`${JSON.stringify({ event: "pairing_waiting", verification_uri: verificationUri })}\n`);
     }
   });
   if (ui.interactive) {
-    ui.stopWait("Approval received", "the Receiver approved this Connector");
+    ui.stopWait("Approved", "this Mac is connected");
     if (!credentials.browserOpened) {
       ui.warning("Browser", "did not open automatically; use the URL above");
     }
@@ -234,7 +246,8 @@ async function pair(flags, ui, options = {}) {
     connector_expires_at: credentials.connector_expires_at,
   });
   if (ui.interactive) {
-    ui.success("This Mac is paired", `credential saved at ${credentialFile}`);
+    ui.complete("Pairing complete", "Re-entry can now deliver approved work to this Mac.");
+    ui.next("re-entry start", "Wait for approved work in this terminal.");
   } else {
     process.stdout.write(`${JSON.stringify({ event: "connector_paired", connector_id: credentials.connector_id })}\n`);
   }
@@ -251,8 +264,10 @@ async function connect(flags, ui, options = {}) {
   const currentIsValid = current && Date.parse(current.connector_expires_at) > Date.now();
   if (currentIsValid && current.receiver_origin === receiver) {
     if (ui.interactive) {
-      ui.success("Already connected", `${current.connector_id} · ${current.receiver_origin}`);
-      ui.info("Next", "run `re-entry start` to wait for approved work");
+      ui.success("Account", "already connected");
+      if (!options.guidedInstall) {
+        ui.next("re-entry start", "Wait for approved work in this terminal.");
+      }
     } else {
       process.stdout.write(`${JSON.stringify({
         event: "connector_already_connected",
@@ -268,19 +283,22 @@ async function connect(flags, ui, options = {}) {
   }
 
   if (ui.interactive) {
-    ui.step("Re-entry", receiver);
-    ui.step("This Mac", flags["device-name"] ?? defaultDeviceName());
+    if (!options.guidedInstall) ui.info("Re-entry", displayReceiver(receiver));
+    ui.info("This Mac", flags["device-name"] ?? defaultDeviceName());
   }
-  const client = new LocalConnectorPairingClient({ baseUrl: receiver });
+  const client = new LocalConnectorPairingClient({
+    baseUrl: receiver,
+    requestTimeoutMs: DEFAULT_PAIRING_REQUEST_TIMEOUT_MS,
+  });
+  if (ui.interactive) ui.wait("Contacting Re-entry…");
   const credentials = await client.connect(
     { deviceName: flags["device-name"] ?? defaultDeviceName() },
     async ({ verificationUri }) => {
       if (ui.interactive) {
-        ui.step("Browser", "press Enter to open Re-entry sign-in and approval");
-        ui.info("If it does not open", verificationUri);
+        ui.stopWait("Secure link", "ready");
+        ui.info("Browser link", verificationUri);
         await waitForEnterToOpenBrowser();
-        ui.step("Browser", "opening Re-entry sign-in and approval");
-        ui.wait("Waiting for you to connect this Mac…");
+        ui.wait("Waiting for approval in your browser…");
       } else {
         process.stdout.write(`${JSON.stringify({
           event: "connector_authorization_waiting",
@@ -290,7 +308,7 @@ async function connect(flags, ui, options = {}) {
     },
   );
   if (ui.interactive) {
-    ui.stopWait("Approved", "Re-entry linked this Mac to your account");
+    ui.stopWait("Account", "connected");
     if (!credentials.browserOpened) {
       ui.warning("Browser", "did not open automatically; use the URL shown above");
     }
@@ -304,8 +322,10 @@ async function connect(flags, ui, options = {}) {
   };
   await store.save(saved);
   if (ui.interactive) {
-    ui.success("Connected", `credential saved at ${credentialFile}`);
-    ui.info("Next", "run `re-entry start` once; it will keep waiting in the background");
+    if (!options.guidedInstall) {
+      ui.complete("This Mac is connected", "Re-entry can now route approved work here.");
+      ui.next("re-entry start", "Wait for approved work in this terminal.");
+    }
   } else {
     process.stdout.write(`${JSON.stringify({
       event: "connector_connected",
@@ -316,22 +336,32 @@ async function connect(flags, ui, options = {}) {
 }
 
 async function status(flags, ui) {
-  if (ui.interactive) ui.begin("Connector status", "Account, background service, Receiver, and Codex");
+  if (ui.interactive) ui.begin("Status", "A quick check of this Mac and Re-entry.");
   const credentialFile = flags["credential-file"] ?? defaultCredentialFile();
   const credentials = await new LocalConnectorCredentialStore({ filename: credentialFile }).load();
   const readiness = inspectReadiness(flags);
   const service = await inspectMacConnectorService();
   const receiverReady = credentials ? await inspectReceiver(credentials.receiver_origin) : false;
-  showReadiness(readiness, ui);
   const connected = Boolean(credentials && Date.parse(credentials.connector_expires_at) > Date.now());
   if (ui.interactive) {
-    if (connected) ui.success("Account", `${credentials.connector_id} · authorized`);
-    else ui.warning("Re-entry", "not connected; run `re-entry connect`");
-    if (service.running) ui.success("Background", "running at login");
-    else if (service.installed) ui.warning("Background", "installed but not running; run `re-entry install`");
-    else ui.warning("Background", "not installed; run `re-entry install`");
-    if (connected && receiverReady) ui.success("Receiver", `${credentials.receiver_origin} · reachable`);
-    else if (connected) ui.warning("Receiver", `${credentials.receiver_origin} · unavailable`);
+    ui.section("SYSTEM", "This Mac");
+    showReadiness(readiness, ui);
+    ui.section("CONNECTION", "Re-entry");
+    if (connected) ui.success("Account", "connected");
+    else ui.warning("Account", "not connected");
+    if (service.running) ui.success("Background", "running");
+    else if (service.installed) ui.warning("Background", "stopped");
+    else ui.warning("Background", "not installed");
+    if (connected && receiverReady) ui.success("Cloud", "online");
+    else if (connected) ui.warning("Cloud", "unavailable");
+
+    if (!connected || !service.running) {
+      ui.next("re-entry install", "Finish setup and start Re-entry in the background.");
+    } else if (!receiverReady) {
+      ui.next("re-entry status", "Check again when the Re-entry Cloud service is available.");
+    } else {
+      ui.complete("Everything looks good", "Re-entry is ready for approved work.");
+    }
   } else {
     process.stdout.write(`${JSON.stringify({
       event: "connector_status",
@@ -355,8 +385,9 @@ async function stop(flags, ui) {
   const result = await stopMacConnectorService();
   if (ui.interactive) {
     if (!result.supported) ui.warning("Platform", "background service control currently supports macOS only");
-    else if (result.stopped) ui.success("Stopped", "the background Connector is no longer running");
+    else if (result.stopped) ui.complete("Re-entry is paused", "Your account connection is still saved.");
     else ui.info("Already stopped", "no running background Connector was found");
+    if (result.supported) ui.next("re-entry install", "Start Re-entry in the background again.");
   } else {
     process.stdout.write(`${JSON.stringify({
       event: "connector_stopped",
@@ -378,8 +409,8 @@ async function uninstall(flags, ui) {
     credentialFile: flags["credential-file"] ?? defaultCredentialFile(),
   });
   if (ui.interactive) {
-    ui.success("Uninstalled", "local Connector service data was removed");
-    ui.info("Package", "remove the npm package separately with `npm uninstall --global @4xeoz/re-entry`");
+    ui.complete("Removed from this Mac", "The local service, connection, and logs are gone.");
+    ui.next("npx @4xeoz/re-entry install", "Connect this Mac again whenever you are ready.");
   } else {
     process.stdout.write(`${JSON.stringify({
       event: "connector_uninstalled",
@@ -390,16 +421,18 @@ async function uninstall(flags, ui) {
 }
 
 async function install(flags, ui) {
-  if (ui.interactive) {
-    ui.begin("Install Re-entry", "Check Codex, connect your account, then start at login");
-    ui.info("Setup", "choose a workspace, approve this Mac, then leave the Connector running");
-  }
   const runtimeFlags = await withWorkspaceDirectory(flags, ui);
-  if (ui.interactive) ui.info("Receiver", runtimeFlags.receiver ?? DEFAULT_RECEIVER_ORIGIN);
   const readiness = inspectReadiness(runtimeFlags);
-  showReadiness(readiness, ui);
-  const credentials = await connect(runtimeFlags, ui, { quietHeader: true });
-  if (ui.interactive) ui.wait("Installing the background Connector…");
+  if (ui.interactive) {
+    ui.begin("Set up this Mac", "Three quick steps. You only do this once.");
+    ui.section("1 OF 3", "Workspace");
+    ui.success("Selected", readiness.workingDirectory);
+    ui.section("2 OF 3", "System check");
+    showReadiness(readiness, ui, { includeWorkspace: false });
+    ui.section("3 OF 3", "Connect Re-entry", "Approve this Mac in your browser.");
+  }
+  const credentials = await connect(runtimeFlags, ui, { quietHeader: true, guidedInstall: true });
+  if (ui.interactive) ui.wait("Starting Re-entry in the background…");
   const service = await installMacConnectorService({
     nodeExecutable: process.execPath,
     entrypoint: fileURLToPath(import.meta.url),
@@ -407,11 +440,9 @@ async function install(flags, ui) {
     credentialFile: flags["credential-file"] ?? defaultCredentialFile(),
   });
   if (ui.interactive) {
-    ui.stopWait("Installed", "Re-entry will start automatically when you log in");
-    ui.success("Account", credentials.connector_id);
-    ui.info("Logs", service.stdoutPath);
-    ui.info("Commands", "status to inspect · stop to pause · uninstall to remove local setup");
-    ui.info("You are done", "the Connector now waits in the background");
+    ui.stopWait("Background", "running at login");
+    ui.complete("You're all set", "Re-entry is connected and waiting for approved work.");
+    ui.next("re-entry status", "Check the connection at any time.");
   } else {
     process.stdout.write(`${JSON.stringify({
       event: "connector_service_installed",
@@ -424,12 +455,13 @@ async function install(flags, ui) {
 }
 
 async function start(flags, ui) {
-  if (ui.interactive) {
-    ui.begin("Re-entry is starting", "Connect once, then wait quietly for work you approve");
-  }
   const runtimeFlags = await withWorkspaceDirectory(flags, ui);
   const readiness = inspectReadiness(runtimeFlags);
-  showReadiness(readiness, ui);
+  if (ui.interactive) {
+    ui.begin("Start Re-entry", "Wait for work you have approved.");
+    ui.section("READY", "This Mac");
+    showReadiness(readiness, ui);
+  }
   if (!ui.interactive) {
     process.stdout.write(`${JSON.stringify({
       event: "connector_ready",
@@ -715,6 +747,14 @@ function defaultDeviceName() {
     : "This Mac";
 }
 
+function displayReceiver(origin) {
+  try {
+    return new URL(origin).host;
+  } catch {
+    return origin;
+  }
+}
+
 function readBoundedNumber(value, minimum, maximum, code) {
   const number = typeof value === "number" ? value : Number(value);
   if (!Number.isSafeInteger(number) || number < minimum || number > maximum) {
@@ -802,6 +842,10 @@ function errorHint(error) {
     pairing_code_invalid: "use the 16-character code returned by the Host, for example ABCD-EFGH-IJKL-MNOP",
     host_subject_already_paired: "use the existing Connector credential or revoke/reset the preview pairing",
     pairing_expired: "ask the Host backend for a new pairing code",
+    pairing_request_timeout: "the Receiver took too long to answer; check your connection and run the command again",
+    pairing_network_error: "check your internet connection and the Receiver address, then try again",
+    workspace_directory_unavailable: "choose a readable folder or pass --codex-cd /absolute/path",
+    workspace_selection_cancelled: "run the command again when you are ready to choose a workspace",
     device_authorization_expired: "run `re-entry connect` again and approve within ten minutes",
     device_authorization_denied: "run `re-entry connect` again when you are ready to approve this Mac",
     connector_poll_interval_invalid: "use a polling interval between 1000 and 60000 milliseconds",

package/src/terminal-ui.mjs

@@ -8,19 +8,12 @@ const YELLOW = "\u001b[33m";
 const RED = "\u001b[31m";
 const CYAN = "\u001b[36m";
 const SPINNER_FRAMES = ["·", "✦", "✧", "✦"];
-const REENTRY_ASCII = [
-  "  ____  _____       _____ _   _ _____ ____  __   __",
-  " |  _ \\| ____|     | ____| \\ | | ____|  _ \\ \\ \\ / /",
-  " | |_) |  _| _____ |  _| |  \\| |  _| | |_) | \\ V /",
-  " |  _ <| |__|_____| | |___| |\\  | |___|  _ <   | |",
-  " |_| \\_\\_____|     |_____|_| \\_|_____|_| \\_\\  |_|",
-];
-const REENTRY_PANEL = [
-  "  +-----------------------------------------------+",
-  "  |                 RE-ENTRY                     |",
-  "  |              LOCAL CONNECTOR                 |",
-  "  +-----------------------------------------------+",
-];
+const RULE = "  ─────────────────────────────────────────────";
+
+export const REENTRY_WORDMARK = Object.freeze([
+  "  █▀█ █▀▀   █▀▀ █▄░█ ▀█▀ █▀█ █▄█",
+  "  █▀▄ ██▄ ▀ ██▄ █░▀█ ░█░ █▀▄ ░█░",
+]);
 
 /**
  * Small dependency-free terminal presentation for the Local Connector CLI.
@@ -36,7 +29,7 @@ export function createTerminalUi(options = {}) {
   let spinnerFrame = 0;
 
   const style = (value, code) => color ? `${code}${value}${RESET}` : value;
-  const write = (value) => output.write(`${value}\n`);
+  const write = (value = "") => output.write(`${value}\n`);
   const clearSpinnerLine = () => {
     if (spinnerTimer === null) return;
     output.write("\r\u001b[2K");
@@ -44,44 +37,56 @@ export function createTerminalUi(options = {}) {
     spinnerTimer = null;
   };
   const renderSpinner = () => {
-    output.write(`\r\u001b[2K  ${style(SPINNER_FRAMES[spinnerFrame], CYAN)} ${spinnerMessage}`);
+    output.write(`\r\u001b[2K  ${style(SPINNER_FRAMES[spinnerFrame], CYAN)}  ${spinnerMessage}`);
     spinnerFrame = (spinnerFrame + 1) % SPINNER_FRAMES.length;
   };
+  const renderState = (symbol, symbolColor, label, detail) => {
+    clearSpinnerLine();
+    write(`  ${style(symbol, symbolColor)}  ${style(label, BOLD)}${detail ? `  ${style(detail, DIM)}` : ""}`);
+  };
 
   return Object.freeze({
     interactive,
 
     begin(title, subtitle) {
       if (!interactive) return;
-      write("");
-      for (const line of REENTRY_ASCII) write(style(line, BOLD));
-      write("");
-      for (const line of REENTRY_PANEL) write(style(line, BOLD));
-      write("");
-      write(`  ${style("RE-ENTRY", BOLD)} ${style("LOCAL CONNECTOR", DIM)}`);
+      clearSpinnerLine();
+      write();
+      for (const line of REENTRY_WORDMARK) write(style(line, `${BOLD}${CYAN}`));
+      write(`  ${style("LOCAL CONNECTOR", DIM)}`);
+      write();
       write(`  ${style(title, BOLD)}`);
       if (subtitle) write(`  ${style(subtitle, DIM)}`);
-      write("");
+      write(RULE);
+    },
+
+    section(step, title, detail) {
+      if (!interactive) return;
+      clearSpinnerLine();
+      write();
+      write(`  ${style(step, CYAN)}  ${style(title, BOLD)}`);
+      if (detail) write(`     ${style(detail, DIM)}`);
+      write();
     },
 
     step(label, detail) {
       if (!interactive) return;
-      write(`  ${style("→", CYAN)} ${style(label, BOLD)}${detail ? `  ${detail}` : ""}`);
+      renderState("→", CYAN, label, detail);
     },
 
     success(label, detail) {
       if (!interactive) return;
-      write(`  ${style("✓", GREEN)} ${style(label, BOLD)}${detail ? `  ${detail}` : ""}`);
+      renderState("✓", GREEN, label, detail);
     },
 
     info(label, detail) {
       if (!interactive) return;
-      write(`  ${style("·", CYAN)} ${style(label, BOLD)}${detail ? `  ${detail}` : ""}`);
+      renderState("·", CYAN, label, detail);
     },
 
     warning(label, detail) {
       if (!interactive) return;
-      write(`  ${style("!", YELLOW)} ${style(label, BOLD)}${detail ? `  ${detail}` : ""}`);
+      renderState("!", YELLOW, label, detail);
     },
 
     wait(message) {
@@ -97,16 +102,38 @@ export function createTerminalUi(options = {}) {
     stopWait(label, detail, outcome = "success") {
       if (!interactive) return;
       clearSpinnerLine();
-      if (outcome === "warning") this.warning(label, detail);
-      else if (outcome === "info") this.info(label, detail);
-      else this.success(label, detail);
+      if (outcome === "warning") renderState("!", YELLOW, label, detail);
+      else if (outcome === "info") renderState("·", CYAN, label, detail);
+      else renderState("✓", GREEN, label, detail);
+    },
+
+    complete(title, detail) {
+      if (!interactive) return;
+      clearSpinnerLine();
+      write();
+      write(`  ${style("✓", GREEN)}  ${style(title, BOLD)}`);
+      if (detail) write(`     ${style(detail, DIM)}`);
+    },
+
+    next(command, detail) {
+      if (!interactive) return;
+      clearSpinnerLine();
+      write();
+      write(`  ${style("NEXT", CYAN)}`);
+      write(`  ${style("$", CYAN)} ${style(command, BOLD)}`);
+      if (detail) write(`    ${style(detail, DIM)}`);
+      write();
     },
 
     error(label, detail, hint) {
       if (!interactive) return;
       clearSpinnerLine();
-      errorOutput.write(`  ${style("✕", RED)} ${style(label, BOLD)}${detail ? `  ${detail}` : ""}\n`);
-      if (hint) errorOutput.write(`  ${style("Next:", DIM)} ${hint}\n`);
+      errorOutput.write(`\n  ${style("✕", RED)}  ${style(label, BOLD)}\n`);
+      if (detail) errorOutput.write(`     ${style(detail, DIM)}\n`);
+      if (hint) {
+        errorOutput.write(`\n  ${style("NEXT", CYAN)}\n`);
+        errorOutput.write(`  ${style("→", CYAN)}  ${hint}\n\n`);
+      }
     },
 
     close() {

package/src/workspace-picker.mjs

@@ -1,10 +1,12 @@
-import { readdir } from "node:fs/promises";
+import { readdir, stat } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { emitKeypressEvents } from "node:readline";
 import process from "node:process";
 
-const MAX_VISIBLE_DIRECTORIES = 40;
+import { REENTRY_WORDMARK } from "./terminal-ui.mjs";
+
+const MAX_VISIBLE_DIRECTORIES = 12;
 
 /**
  * Let an interactive user choose the directory passed to Codex as its workspace.
@@ -19,19 +21,47 @@ export async function chooseWorkspaceDirectory(options = {}) {
 
   const homeDirectory = resolve(options.homeDirectory ?? homedir());
   const preferredDirectory = resolve(options.startDirectory ?? process.cwd());
-  let current = homeDirectory;
-  const shortcuts = shortcutDirectories(homeDirectory);
   let selected = 0;
   const wasRaw = Boolean(input.isRaw);
   emitKeypressEvents(input);
   input.setRawMode(true);
 
   try {
+    const quickChoices = await createQuickChoices({ homeDirectory, preferredDirectory });
+    while (true) {
+      renderPicker(output, {
+        title: "Choose where Codex should open for approved work.",
+        choices: quickChoices,
+        selected,
+      });
+      const key = await readKey(input);
+      if (key.name === "up") {
+        selected = (selected - 1 + quickChoices.length) % quickChoices.length;
+      } else if (key.name === "down") {
+        selected = (selected + 1) % quickChoices.length;
+      } else if (key.name === "return" || key.name === "enter") {
+        const choice = quickChoices[selected];
+        if (choice.action === "use") return choice.path;
+        if (choice.action === "cancel") throw cancelledFailure();
+        break;
+      } else if (key.name === "escape" || key.sequence === "\u0003") {
+        throw cancelledFailure();
+      }
+    }
+
+    let current = homeDirectory;
+    selected = 0;
     while (true) {
       const directories = await readableDirectories(current);
-      const choices = createChoices({ current, homeDirectory, preferredDirectory, shortcuts, directories });
+      const choices = createBrowserChoices({ current, directories });
       selected = Math.min(selected, choices.length - 1);
-      renderPicker(output, current, choices, selected);
+      renderPicker(output, {
+        title: "Choose another folder.",
+        current,
+        choices,
+        selected,
+        truncated: directories.truncated,
+      });
       const key = await readKey(input);
       if (key.name === "up") {
         selected = (selected - 1 + choices.length) % choices.length;
@@ -40,72 +70,112 @@ export async function chooseWorkspaceDirectory(options = {}) {
       } else if (key.name === "return" || key.name === "enter") {
         const choice = choices[selected];
         if (choice.action === "use") return choice.path;
-        if (choice.action === "cancel") {
-          throw pickerFailure("workspace_selection_cancelled", "Workspace selection was cancelled");
-        }
+        if (choice.action === "cancel") throw cancelledFailure();
         current = choice.path;
         selected = 0;
       } else if (key.name === "escape" || key.sequence === "\u0003") {
-        throw pickerFailure("workspace_selection_cancelled", "Workspace selection was cancelled");
+        throw cancelledFailure();
       }
     }
   } finally {
     input.setRawMode(wasRaw);
-    output.write("\n");
+    output.write("\u001b[2J\u001b[H");
   }
 }
 
-function createChoices({ current, homeDirectory, preferredDirectory, shortcuts, directories }) {
+async function createQuickChoices({ homeDirectory, preferredDirectory }) {
   const choices = [];
-  if (current === homeDirectory && preferredDirectory !== homeDirectory) {
-    choices.push({ label: `Use current folder  ${preferredDirectory}`, action: "use", path: preferredDirectory });
+  const desktop = join(homeDirectory, "Desktop");
+  if (await isDirectory(desktop)) {
+    choices.push({
+      label: "Use Desktop (recommended)",
+      detail: desktop,
+      action: "use",
+      path: desktop,
+    });
   }
-  choices.push({ label: `Use this folder  ${current}`, action: "use", path: current });
-  if (current === homeDirectory) {
-    for (const shortcut of shortcuts) {
-      if (directories.some((directory) => directory.path === shortcut.path)) {
-        choices.push({ label: `Open ${shortcut.label}`, action: "open", path: shortcut.path });
-      }
-    }
+  if (preferredDirectory !== desktop && await isDirectory(preferredDirectory)) {
+    choices.push({
+      label: "Use current folder",
+      detail: preferredDirectory,
+      action: "use",
+      path: preferredDirectory,
+    });
+  }
+  if (choices.length === 0) {
+    choices.push({
+      label: "Use Home",
+      detail: homeDirectory,
+      action: "use",
+      path: homeDirectory,
+    });
   }
+  choices.push({ label: "Choose another folder…", action: "browse", path: homeDirectory });
+  choices.push({ label: "Cancel", action: "cancel", path: null });
+  return choices;
+}
+
+function createBrowserChoices({ current, directories }) {
+  const choices = [
+    { label: "Use this folder", detail: current, action: "use", path: current },
+  ];
   const parent = dirname(current);
-  if (parent !== current) choices.push({ label: `Go up  ${parent}`, action: "open", path: parent });
-  const shortcutPaths = new Set(shortcuts.map((shortcut) => shortcut.path));
-  for (const directory of directories) {
-    if (current === homeDirectory && shortcutPaths.has(directory.path)) continue;
-    choices.push({ label: `Open ${directory.name}`, action: "open", path: directory.path });
+  if (parent !== current) {
+    choices.push({ label: "Go up", detail: parent, action: "open", path: parent });
+  }
+  for (const directory of directories.items) {
+    choices.push({ label: directory.name, action: "open", path: directory.path });
   }
   choices.push({ label: "Cancel", action: "cancel", path: null });
   return choices;
 }
 
-async function readableDirectories(directory) {
-  const entries = await readdir(directory, { withFileTypes: true });
-  return entries
-    .filter((entry) => entry.isDirectory() && !entry.name.startsWith("."))
-    .sort((left, right) => left.name.localeCompare(right.name))
-    .slice(0, MAX_VISIBLE_DIRECTORIES)
-    .map((entry) => ({ name: entry.name, path: join(directory, entry.name) }));
+async function isDirectory(path) {
+  try {
+    return (await stat(path)).isDirectory();
+  } catch {
+    return false;
+  }
 }
 
-function shortcutDirectories(home) {
-  return [
-    { label: "Desktop", path: join(home, "Desktop") },
-    { label: "Documents", path: join(home, "Documents") },
-    { label: "Downloads", path: join(home, "Downloads") },
-    { label: "Home", path: home },
-  ];
+async function readableDirectories(directory) {
+  let entries;
+  try {
+    entries = await readdir(directory, { withFileTypes: true });
+  } catch (error) {
+    const failure = pickerFailure("workspace_directory_unavailable", `Cannot open ${directory}`);
+    failure.cause = error;
+    throw failure;
+  }
+  const directories = entries
+    .filter((entry) => entry.isDirectory() && !entry.name.startsWith("."))
+    .sort((left, right) => left.name.localeCompare(right.name));
+  return {
+    items: directories
+      .slice(0, MAX_VISIBLE_DIRECTORIES)
+      .map((entry) => ({ name: entry.name, path: join(directory, entry.name) })),
+    truncated: directories.length > MAX_VISIBLE_DIRECTORIES,
+  };
 }
 
-function renderPicker(output, current, choices, selected) {
+function renderPicker(output, { title, current, choices, selected, truncated = false }) {
   output.write("\u001b[2J\u001b[H");
-  output.write("RE-ENTRY WORKSPACE\n\n");
-  output.write("Choose the folder where Codex will work. Files stay inside this workspace.\n");
-  output.write(`Current folder: ${current}\n\n`);
+  for (const line of REENTRY_WORDMARK) output.write(`${line}\n`);
+  output.write("  LOCAL CONNECTOR\n\n");
+  output.write("  1 OF 3  WORKSPACE\n");
+  output.write(`  ${title}\n`);
+  if (current) output.write(`  Current: ${current}\n`);
+  output.write("  ─────────────────────────────────────────────\n");
+  output.write("\n");
   for (let index = 0; index < choices.length; index += 1) {
-    output.write(`${index === selected ? "❯" : " "} ${choices[index].label}\n`);
+    const choice = choices[index];
+    output.write(`  ${index === selected ? "❯" : " "}  ${choice.label}\n`);
+    if (choice.detail) output.write(`       ${choice.detail}\n`);
+  }
+  if (truncated) {
+    output.write(`\n  Showing the first ${MAX_VISIBLE_DIRECTORIES} folders.\n`);
   }
-  output.write("\n↑/↓ Move   Enter Select   Esc Cancel");
+  output.write("\n  ↑↓ Move   Enter Select   Esc Cancel");
 }
 
 function readKey(input) {
@@ -118,6 +188,10 @@ function readKey(input) {
   });
 }
 
+function cancelledFailure() {
+  return pickerFailure("workspace_selection_cancelled", "Workspace selection was cancelled");
+}
+
 function pickerFailure(code, message) {
   const error = new Error(message);
   error.code = code;