@4xeoz/re-entry 0.2.4 → 0.2.6

package/README.md

@@ -16,6 +16,16 @@ Codex may read and write.
 npx @4xeoz/re-entry install
 ```
 
+`npx` runs a temporary copy, so it does not leave a permanent shell command behind. Install the
+small CLI globally once if you want to use `re-entry` from any folder afterward:
+
+```sh
+npm install --global @4xeoz/re-entry
+```
+
+The package installs both `re-entry` and the older `reentry` spelling; `re-entry` is the documented
+command.
+
 This uses the deployed Re-entry Cloud Receiver by default:
 `https://reentry-cloud.vercel.app`.
 
@@ -27,6 +37,10 @@ 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.
@@ -70,11 +84,13 @@ preview.
 
 ```sh
 re-entry status
+re-entry listen
 re-entry --help
 ```
 
 The status view checks the local authorization, background job, Receiver reachability, Node, and
-Codex. Useful development commands are:
+Codex. `listen` watches the already-running background Connector and displays new activity until
+you press Ctrl+C; it does not start a competing second poller. Useful development commands are:
 
 ```sh
 re-entry doctor --codex-cd /absolute/path/to/project
@@ -83,6 +99,15 @@ re-entry claim-once --codex-cd /absolute/path/to/project
 re-entry start --codex-cd /absolute/path/to/project
 ```
 
+Test the local Codex handoff without waiting for Cloud work:
+
+```sh
+re-entry test "Reply with: Re-entry is working."
+```
+
+This starts one fresh local Codex process through the same adapter seam used by real deliveries. It
+does not create a Grant, claim Receiver work, or prove the browser/WebMCP return path.
+
 To pause or remove the local Connector:
 
 ```sh

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@4xeoz/re-entry",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "type": "module",
   "description": "Outbound Local Connector process for the Re-entry Core local preview.",
   "publishConfig": {
@@ -10,7 +10,10 @@
     "README.md",
     "src"
   ],
-  "bin": "./src/main.mjs",
+  "bin": {
+    "re-entry": "./src/main.mjs",
+    "reentry": "./src/main.mjs"
+  },
   "exports": {
     ".": "./src/index.mjs",
     "./connector": "./src/local-connector.mjs",

package/src/activity-monitor.mjs

@@ -0,0 +1,107 @@
+import { open, stat } from "node:fs/promises";
+
+const MAX_LINE_BYTES = 16 * 1_024;
+const MAX_READ_BYTES = 64 * 1_024;
+
+/**
+ * Follow new JSON events written by the installed background Connector.
+ * The monitor starts at the end of each file and never starts another Connector poller.
+ */
+export async function followConnectorActivity(options) {
+  requireOptions(options);
+  const cursors = await Promise.all(options.paths.map(initializeCursor));
+  const pollIntervalMs = options.pollIntervalMs ?? 350;
+  if (!Number.isSafeInteger(pollIntervalMs) || pollIntervalMs < 10 || pollIntervalMs > 5_000) {
+    throw new TypeError("Activity monitor poll interval is invalid");
+  }
+
+  while (!options.signal.aborted) {
+    for (const cursor of cursors) {
+      await readNewEvents(cursor, options.onEvent);
+    }
+    await waitForNextRead(pollIntervalMs, options.signal);
+  }
+}
+
+async function initializeCursor(path) {
+  try {
+    const metadata = await stat(path);
+    return { path, offset: metadata.size, pending: "" };
+  } catch (error) {
+    if (error?.code === "ENOENT") return { path, offset: 0, pending: "" };
+    throw error;
+  }
+}
+
+async function readNewEvents(cursor, onEvent) {
+  let handle;
+  try {
+    handle = await open(cursor.path, "r");
+    const metadata = await handle.stat();
+    if (metadata.size < cursor.offset) {
+      cursor.offset = 0;
+      cursor.pending = "";
+    }
+    if (metadata.size === cursor.offset) return;
+    const length = Math.min(metadata.size - cursor.offset, MAX_READ_BYTES);
+    const buffer = Buffer.alloc(length);
+    const { bytesRead } = await handle.read(buffer, 0, length, cursor.offset);
+    cursor.offset += bytesRead;
+    const lines = `${cursor.pending}${buffer.subarray(0, bytesRead).toString("utf8")}`.split("\n");
+    cursor.pending = lines.pop() ?? "";
+    if (Buffer.byteLength(cursor.pending, "utf8") > MAX_LINE_BYTES) cursor.pending = "";
+    for (const line of lines) {
+      const event = parseEvent(line);
+      if (event) await onEvent(event);
+    }
+  } catch (error) {
+    if (error?.code !== "ENOENT") throw error;
+  } finally {
+    await handle?.close();
+  }
+}
+
+function parseEvent(line) {
+  if (line.length === 0 || Buffer.byteLength(line, "utf8") > MAX_LINE_BYTES) return null;
+  try {
+    const value = JSON.parse(line);
+    if (!value || typeof value !== "object" || Array.isArray(value) || typeof value.event !== "string") {
+      return null;
+    }
+    return value;
+  } catch {
+    return null;
+  }
+}
+
+function waitForNextRead(milliseconds, signal) {
+  if (signal.aborted) return Promise.resolve();
+  return new Promise((resolve) => {
+    const timer = setTimeout(done, milliseconds);
+    function done() {
+      clearTimeout(timer);
+      signal.removeEventListener("abort", done);
+      resolve();
+    }
+    signal.addEventListener("abort", done, { once: true });
+  });
+}
+
+function requireOptions(options) {
+  if (!options || typeof options !== "object" || Array.isArray(options)) {
+    throw new TypeError("Activity monitor options are required");
+  }
+  const fields = Object.keys(options);
+  if (fields.some((field) => !["paths", "signal", "onEvent", "pollIntervalMs"].includes(field))) {
+    throw new TypeError("Activity monitor options contain an unsupported field");
+  }
+  if (
+    !Array.isArray(options.paths) ||
+    options.paths.length !== 2 ||
+    options.paths.some((path) => typeof path !== "string" || path.length === 0) ||
+    !(options.signal instanceof AbortSignal) ||
+    typeof options.onEvent !== "function"
+  ) {
+    throw new TypeError("Activity monitor options are invalid");
+  }
+}

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/codex-exec-adapter.mjs

@@ -22,6 +22,7 @@ const MIN_COMMAND_TIMEOUT_MS = 100;
 const MAX_COMMAND_TIMEOUT_MS = 60_000;
 const MAX_REFERENCE_BYTES = 4 * 1_024;
 const CONTROL_CHARACTER_PATTERN = /[\u0000-\u001f\u007f]/;
+const PROMPT_CONTROL_CHARACTER_PATTERN = /[\u0000-\u0009\u000b-\u001f\u007f]/;
 
 /**
  * Create the fresh-session Codex adapter that lives inside the Local Connector process.
@@ -54,11 +55,11 @@ export function createCodexExecAdapter(options) {
         return activationResult(activation, "rejected", "activation_rejected", null);
       }
 
-      await runCodexExec({
+      await runCodexPrompt({
         executable,
         workingDirectory,
         prompt: buildContinuationPrompt(activation),
-        timeoutMs: commandTimeoutMs,
+        commandTimeoutMs,
         spawnCommand,
       });
       return activationResult(
@@ -71,6 +72,30 @@ export function createCodexExecAdapter(options) {
   });
 }
 
+/**
+ * Run one local prompt through the same fresh Codex process seam used by real activations.
+ * This helper carries no Receiver authority and is intended only for an explicit local smoke test.
+ */
+export async function runCodexPrompt(options) {
+  requireExactRecord(
+    options,
+    ["workingDirectory", "prompt", "executable", "commandTimeoutMs", "spawnCommand"],
+    ["workingDirectory", "prompt"],
+    "Codex prompt options",
+  );
+  const workingDirectory = validateCodexWorkingDirectory(options.workingDirectory);
+  const executable = options.executable === undefined
+    ? discoverCodexExecutable()
+    : requireReference(options.executable, "Codex executable");
+  const prompt = requirePrompt(options.prompt);
+  const timeoutMs = requireTimeout(options.commandTimeoutMs ?? 60_000);
+  const spawnCommand = options.spawnCommand ?? spawn;
+  if (typeof spawnCommand !== "function") {
+    throw new TypeError("Codex prompt spawnCommand must be a function");
+  }
+  await runCodexExec({ executable, workingDirectory, prompt, timeoutMs, spawnCommand });
+}
+
 function buildContinuationPrompt(activation) {
   return [
     "You are a Re-entry continuation agent.",
@@ -183,6 +208,19 @@ function requireReference(value, label) {
   return value;
 }
 
+function requirePrompt(value) {
+  if (
+    typeof value !== "string" ||
+    value.length === 0 ||
+    value.trim() !== value ||
+    Buffer.byteLength(value, "utf8") > MAX_REFERENCE_BYTES ||
+    PROMPT_CONTROL_CHARACTER_PATTERN.test(value)
+  ) {
+    throw new TypeError("Codex prompt is invalid");
+  }
+  return value;
+}
+
 function requireExactRecord(value, allowedFields, requiredFields, label) {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
     throw new TypeError(`${label} must be an object`);

package/src/main.mjs

@@ -9,7 +9,8 @@ import { randomBytes } from "node:crypto";
 import process from "node:process";
 
 import { LocalConnectorClient } from "@webmcp-challenge/reentry-core/local-connector-client";
-import { createCodexExecAdapter } from "./codex-exec-adapter.mjs";
+import { followConnectorActivity } from "./activity-monitor.mjs";
+import { createCodexExecAdapter, runCodexPrompt } from "./codex-exec-adapter.mjs";
 import {
   discoverCodexExecutable,
   requireSupportedNode,
@@ -47,8 +48,8 @@ async function main() {
       process.stdout.write(`${CONNECTOR_VERSION}\n`);
       return;
     }
-    const { command, flags } = parseArguments(argumentsList);
-    validateCommandFlags(command, flags);
+    const { command, flags, positionals } = parseArguments(argumentsList);
+    validateCommandFlags(command, flags, positionals);
     ui = createTerminalUi({ interactive: flags.json !== true && process.stdout.isTTY === true });
     requireSupportedNode();
     if (command === "doctor") {
@@ -67,6 +68,14 @@ async function main() {
       await status(flags, ui);
       return;
     }
+    if (command === "listen") {
+      await listen(flags, ui);
+      return;
+    }
+    if (command === "test") {
+      await testCodex(flags, positionals, ui);
+      return;
+    }
     if (command === "stop") {
       await stop(flags, ui);
       return;
@@ -111,12 +120,14 @@ Connect this Mac once, then receive approved work in Codex in the background.
 
 Usage:
   re-entry install                                      Recommended first run
-  re-entry status                                          Check the connection
-  re-entry start                                          Run in this terminal
+  re-entry listen                                      Watch live activity
+  re-entry test "Reply with hello"                     Test Codex locally
 
 Commands:
   install      Check this Mac, connect the Re-entry account, and start at login
   status       Show account, Receiver, service, Node.js, and Codex readiness
+  listen       Watch the background Connector until you press Ctrl+C
+  test         Start one fresh local Codex session with the supplied prompt
   stop         Stop the background Connector without removing its credential
   uninstall    Stop the Connector and remove its local service data
   connect      Authorize this Mac without installing the background service
@@ -134,6 +145,7 @@ Common options:
   --help                 Show this help
   --version              Show the installed version
 
+Both commands are installed: re-entry and reentry.
 The Connector opens no inbound port. Host keys never belong on this Mac.
 `);
 }
@@ -149,9 +161,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",
@@ -179,21 +194,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");
+    }
   }
 }
 
@@ -215,18 +235,16 @@ async function pair(flags, ui, options = {}) {
   if (ui.interactive) ui.wait("Contacting Re-entry…");
   const credentials = await client.pair({ userCode }, async ({ verificationUri }) => {
     if (ui.interactive) {
-      ui.stopWait("Re-entry ready", "approval link created");
-      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");
     }
@@ -240,7 +258,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`);
   }
@@ -257,8 +276,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",
@@ -274,8 +295,8 @@ 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,
@@ -286,12 +307,10 @@ async function connect(flags, ui, options = {}) {
     { deviceName: flags["device-name"] ?? defaultDeviceName() },
     async ({ verificationUri }) => {
       if (ui.interactive) {
-        ui.stopWait("Re-entry ready", "secure approval link created");
-        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",
@@ -301,7 +320,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");
     }
@@ -315,8 +334,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",
@@ -327,22 +348,33 @@ 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.");
+      ui.next("re-entry listen", "Watch live activity. Press Ctrl+C when you are done.");
+    }
   } else {
     process.stdout.write(`${JSON.stringify({
       event: "connector_status",
@@ -359,6 +391,109 @@ async function status(flags, ui) {
   }
 }
 
+async function listen(flags, ui) {
+  if (ui.interactive) {
+    ui.begin("Live activity", "Watch the background Connector. Ctrl+C closes this view.");
+  }
+  const service = await inspectMacConnectorService();
+  const credentials = await new LocalConnectorCredentialStore({
+    filename: defaultCredentialFile(),
+  }).load();
+  if (!service.running || !credentials) {
+    if (ui.interactive) {
+      if (!credentials) ui.warning("Account", "not connected");
+      if (!service.running) ui.warning("Background", "not running");
+      ui.next("re-entry install", "Finish setup and start the background Connector.");
+    } else {
+      process.stdout.write(`${JSON.stringify({
+        event: "connector_listener_unavailable",
+        connected: Boolean(credentials),
+        service_running: service.running,
+      })}\n`);
+    }
+    return;
+  }
+
+  if (ui.interactive) {
+    ui.success("Background", "running");
+    ui.success("Account", "connected");
+    ui.wait("Listening for approved work…");
+  } else {
+    process.stdout.write('{"event":"connector_listener_started"}\n');
+  }
+
+  const stopSignal = createStopSignal();
+  try {
+    await followConnectorActivity({
+      paths: defaultConnectorLogFiles(),
+      signal: stopSignal.signal,
+      onEvent(event) {
+        if (ui.interactive) reportLiveActivity(event, ui);
+        else process.stdout.write(`${JSON.stringify(event)}\n`);
+      },
+    });
+  } finally {
+    stopSignal.close();
+    if (ui.interactive) {
+      ui.stopWait("Live view closed", "the background Connector is still running", "info");
+    } else {
+      process.stdout.write('{"event":"connector_listener_stopped"}\n');
+    }
+  }
+}
+
+async function testCodex(flags, positionals, ui) {
+  const prompt = requireTestPrompt(positionals);
+  const runtimeFlags = await withWorkspaceDirectory(flags, ui);
+  const readiness = inspectReadiness(runtimeFlags);
+  if (ui.interactive) {
+    ui.begin("Test Codex", "Run one local prompt through the Re-entry Codex adapter.");
+    ui.success("Codex", "ready");
+    ui.success("Workspace", readiness.workingDirectory);
+    ui.info("Prompt", prompt);
+    ui.wait("Starting a fresh Codex session…");
+  }
+  await runCodexPrompt({
+    workingDirectory: readiness.workingDirectory,
+    executable: readiness.installation.executable,
+    prompt,
+    commandTimeoutMs: readBoundedNumber(
+      flags["activation-timeout"] ?? 60_000,
+      100,
+      60_000,
+      "connector_activation_timeout_invalid",
+    ),
+  });
+  if (ui.interactive) {
+    ui.stopWait("Codex", "completed the local test");
+    ui.complete("Test passed", "The same fresh-session process seam is ready for Re-entry work.");
+    ui.next("re-entry listen", "Watch the background Connector for approved work.");
+  } else {
+    process.stdout.write('{"event":"connector_codex_test_passed"}\n');
+  }
+}
+
+function reportLiveActivity(event, ui) {
+  if (event.event === "connector_waiting") return;
+  if (event.event === "connector_activation_result") {
+    const accepted = event.outcome === "accepted";
+    ui.stopWait(
+      accepted ? "Work received" : "Work finished",
+      accepted ? "a fresh Codex session was started" : String(event.outcome ?? "unknown"),
+      accepted ? "success" : "warning",
+    );
+  } else if (event.event === "connector_poll_failed" || event.event === "local_connector_failed") {
+    ui.stopWait("Connection interrupted", "Re-entry is retrying", "warning");
+  } else if (event.event === "connector_ready") {
+    ui.stopWait("Connector", "ready", "success");
+  } else if (event.event === "connector_stopped") {
+    ui.stopWait("Background", "stopped", "warning");
+  } else {
+    ui.stopWait("Activity", event.event.replaceAll("_", " "), "info");
+  }
+  ui.wait("Listening for approved work…");
+}
+
 async function stop(flags, ui) {
   if (ui.interactive) {
     ui.begin("Stop the Connector", "Pause background delivery without removing your account connection");
@@ -366,8 +501,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",
@@ -389,8 +525,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",
@@ -401,16 +537,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),
@@ -418,11 +556,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 listen", "Watch live activity. Press Ctrl+C when you are done.");
   } else {
     process.stdout.write(`${JSON.stringify({
       event: "connector_service_installed",
@@ -435,12 +571,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",
@@ -647,9 +784,14 @@ function parseArguments(argumentsList) {
     ...(hasExplicitCommand ? argumentsList.slice(commandIndex + 1) : argumentsList.slice(commandIndex)),
   ];
   const flags = {};
+  const positionals = [];
   for (let index = 0; index < rest.length; index += 1) {
     const value = rest[index];
-    if (!value.startsWith("--")) throw cliFailure("connector_argument_invalid");
+    if (!value.startsWith("--")) {
+      if (command !== "test") throw cliFailure("connector_argument_invalid");
+      positionals.push(value);
+      continue;
+    }
     const name = value.slice(2);
     if (name === "json" || name === "yes") {
       if (Object.hasOwn(flags, name)) throw cliFailure("connector_argument_invalid");
@@ -661,15 +803,17 @@ function parseArguments(argumentsList) {
     flags[name] = next;
     index += 1;
   }
-  return { command, flags };
+  return { command, flags, positionals };
 }
 
-function validateCommandFlags(command, flags) {
+function validateCommandFlags(command, flags, positionals) {
   const allowedByCommand = {
     doctor: new Set(["codex-binary", "codex-cd", "json"]),
     pair: new Set(["receiver", "code", "credential-file", "json"]),
     connect: new Set(["receiver", "device-name", "credential-file", "json"]),
     status: new Set(["credential-file", "codex-cd", "codex-binary", "json"]),
+    listen: new Set(["json"]),
+    test: new Set(["codex-cd", "codex-binary", "activation-timeout", "json"]),
     stop: new Set(["json"]),
     uninstall: new Set(["credential-file", "yes", "json"]),
     install: new Set([
@@ -704,7 +848,11 @@ function validateCommandFlags(command, flags) {
     ]),
   };
   const allowed = allowedByCommand[command];
-  if (!allowed || Object.keys(flags).some((name) => !allowed.has(name))) {
+  if (
+    !allowed ||
+    Object.keys(flags).some((name) => !allowed.has(name)) ||
+    (command !== "test" && positionals.length > 0)
+  ) {
     throw cliFailure("connector_argument_invalid");
   }
 }
@@ -719,6 +867,14 @@ function defaultCredentialFile() {
   return join(homedir(), ".webmcp-connector", "credentials.json");
 }
 
+function defaultConnectorLogFiles() {
+  const stateDirectory = join(homedir(), ".webmcp-connector");
+  return [
+    join(stateDirectory, "connector.log"),
+    join(stateDirectory, "connector-error.log"),
+  ];
+}
+
 function defaultDeviceName() {
   const value = hostname().trim();
   return value.length >= 2 && Buffer.byteLength(value, "utf8") <= 80
@@ -726,6 +882,31 @@ function defaultDeviceName() {
     : "This Mac";
 }
 
+function displayReceiver(origin) {
+  try {
+    return new URL(origin).host;
+  } catch {
+    return origin;
+  }
+}
+
+function requireTestPrompt(positionals) {
+  if (!Array.isArray(positionals) || positionals.length !== 1) {
+    throw cliFailure("connector_test_prompt_missing");
+  }
+  const value = positionals[0];
+  if (
+    typeof value !== "string" ||
+    value.trim() !== value ||
+    value.length === 0 ||
+    Buffer.byteLength(value, "utf8") > 4 * 1_024 ||
+    /[\u0000-\u001f\u007f]/.test(value)
+  ) {
+    throw cliFailure("connector_test_prompt_invalid");
+  }
+  return value;
+}
+
 function readBoundedNumber(value, minimum, maximum, code) {
   const number = typeof value === "number" ? value : Number(value);
   if (!Number.isSafeInteger(number) || number < minimum || number > maximum) {
@@ -824,6 +1005,9 @@ function errorHint(error) {
     connector_service_load_failed: "run `re-entry install` again; if it still fails, inspect the Connector error log",
     connector_uninstall_confirmation_required: "run uninstall interactively and type DELETE, or pass `--yes` in a deliberate script",
     connector_service_stop_failed: "check the Connector status and try `re-entry stop` again",
+    connector_test_prompt_missing: "use `re-entry test \"Reply with: Re-entry is working.\"`",
+    connector_test_prompt_invalid: "use one short, single-line prompt inside quotes",
+    connector_activation_timeout_invalid: "use an activation timeout between 100 and 60000 milliseconds",
   };
   return hints[error?.code] ?? "check the Receiver address and try again";
 }

package/src/terminal-ui.mjs

@@ -8,19 +8,15 @@ 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([
+  "   ____  _____      _____ _   _ _____ ______   __",
+  "  |  _ \\| ____|    | ____| \\ | |_   _|  _ \\ \\ / /",
+  "  | |_) |  _| _____|  _| |  \\| | | | | |_) | \\ V /",
+  "  |  _ <| |__|_____| |___| |\\  | | | |  _ <   | |",
+  "  |_| \\_\\_____|    |_____|_| \\_| |_| |_| \\_\\  |_|",
+]);
 
 /**
  * Small dependency-free terminal presentation for the Local Connector CLI.
@@ -36,7 +32,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 +40,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 +105,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

@@ -4,6 +4,8 @@ import { dirname, join, resolve } from "node:path";
 import { emitKeypressEvents } from "node:readline";
 import process from "node:process";
 
+import { REENTRY_WORDMARK } from "./terminal-ui.mjs";
+
 const MAX_VISIBLE_DIRECTORIES = 12;
 
 /**
@@ -77,7 +79,7 @@ export async function chooseWorkspaceDirectory(options = {}) {
     }
   } finally {
     input.setRawMode(wasRaw);
-    output.write("\n");
+    output.write("\u001b[2J\u001b[H");
   }
 }
 
@@ -158,19 +160,22 @@ async function readableDirectories(directory) {
 
 function renderPicker(output, { title, current, choices, selected, truncated = false }) {
   output.write("\u001b[2J\u001b[H");
-  output.write("RE-ENTRY WORKSPACE\n\n");
-  output.write(`${title}\n`);
-  if (current) output.write(`Current folder: ${current}\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) {
     const choice = choices[index];
-    output.write(`${index === selected ? "❯" : " "} ${choice.label}\n`);
-    if (choice.detail) output.write(`    ${choice.detail}\n`);
+    output.write(`  ${index === selected ? "❯" : " "}  ${choice.label}\n`);
+    if (choice.detail) output.write(`       ${choice.detail}\n`);
   }
   if (truncated) {
-    output.write(`\nShowing the first ${MAX_VISIBLE_DIRECTORIES} folders. Open a folder to continue.\n`);
+    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) {