@4xeoz/re-entry 0.2.5 → 0.2.7

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`.
 
@@ -74,11 +84,15 @@ 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. If the Receiver rejects a previously saved device credential, the Connector pauses instead
+of retrying forever, and `status`/`listen` tell you to run `re-entry connect` again. `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
@@ -87,6 +101,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/node_modules/@webmcp-challenge/reentry-core/src/cloud-receiver-http.mjs

@@ -42,7 +42,7 @@ export function createCloudReceiverHttpHandler(options) {
   requireReceiver(options.receiver);
 
   return function cloudReceiverHttpHandler(request, response) {
-    handleRequest(options.receiver, request, response).catch((error) => {
+    return handleRequest(options.receiver, request, response).catch((error) => {
       if (response.destroyed) return;
       if (response.headersSent) {
         response.destroy();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@4xeoz/re-entry",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "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/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/credentials.mjs

@@ -49,6 +49,48 @@ export class LocalConnectorCredentialStore {
   }
 }
 
+export function reauthorizationMarkerPath(filename) {
+  if (typeof filename !== "string" || filename.length === 0) {
+    throw new TypeError("Credential filename is required");
+  }
+  return `${filename}.reauthorization-required.json`;
+}
+
+export async function markConnectorReauthorizationRequired(filename, value = {}) {
+  const marker = reauthorizationMarkerPath(filename);
+  await mkdir(dirname(marker), { recursive: true, mode: 0o700 });
+  await writeFile(marker, `${JSON.stringify({
+    receiver_origin: value.receiver_origin ?? null,
+    reason: "connector_identity_invalid",
+    observed_at: new Date().toISOString(),
+  })}\n`, { encoding: "utf8", mode: 0o600 });
+  await chmod(marker, 0o600);
+}
+
+export async function hasConnectorReauthorizationRequired(filename) {
+  try {
+    await readFile(reauthorizationMarkerPath(filename), "utf8");
+    return true;
+  } catch (error) {
+    if (error?.code === "ENOENT") return false;
+    throw credentialFailure(
+      "connector_status_unreadable",
+      "Connector authorization status could not be read",
+      error,
+    );
+  }
+}
+
+export async function clearConnectorReauthorizationRequired(filename) {
+  await unlink(reauthorizationMarkerPath(filename)).catch((error) => {
+    if (error?.code !== "ENOENT") throw credentialFailure(
+      "connector_status_unwritable",
+      "Connector authorization status could not be cleared",
+      error,
+    );
+  });
+}
+
 function normalizeCredentials(value) {
   requireExactRecord(value, CREDENTIAL_FIELDS, CREDENTIAL_FIELDS, "Connector credentials");
   if (value.version !== 1) throw credentialFailure("connector_credentials_invalid", "Connector credential version is unsupported");

package/src/macos-service.mjs

@@ -91,7 +91,7 @@ export async function inspectMacConnectorService(options = {}) {
   return Object.freeze({
     supported: true,
     installed: true,
-    running: result.code === 0,
+    running: result.code === 0 && isLoadedAndRunning(result.stdout),
     plistPath,
   });
 }
@@ -127,6 +127,7 @@ export async function uninstallMacConnectorService(options = {}) {
   const paths = [...new Set([
     service.plistPath,
     credentialFile,
+    `${credentialFile}.reauthorization-required.json`,
     join(stateDirectory, "connector.log"),
     join(stateDirectory, "connector-error.log"),
   ])];
@@ -192,6 +193,7 @@ ${argumentsXml}
 function runLaunchctl(argumentsList) {
   return new Promise((resolve) => {
     const child = spawn("launchctl", argumentsList, { stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
     let stderr = "";
     let settled = false;
     const finish = (result) => {
@@ -199,15 +201,29 @@ function runLaunchctl(argumentsList) {
       settled = true;
       resolve(result);
     };
+    child.stdout.setEncoding("utf8");
+    child.stdout.on("data", (chunk) => {
+      if (stdout.length < 16_384) stdout += chunk;
+    });
     child.stderr.setEncoding("utf8");
     child.stderr.on("data", (chunk) => {
       if (stderr.length < 4_096) stderr += chunk;
     });
-    child.once("error", (error) => finish({ code: -1, stderr: error.message }));
-    child.once("close", (code) => finish({ code: code ?? -1, stderr }));
+    child.once("error", (error) => finish({ code: -1, stdout, stderr: error.message }));
+    child.once("close", (code) => finish({ code: code ?? -1, stdout, stderr }));
   });
 }
 
+function isLoadedAndRunning(stdout) {
+  // Test doubles historically return only { code: 0 }; preserve that contract while
+  // treating launchctl's explicit not-running state as stopped in production.
+  if (stdout === undefined) return true;
+  const state = stdout.match(/^[\t ]*state\s*=\s*([^\r\n]+)$/m)?.[1]?.trim();
+  if (state) return state === "running";
+  const activeCount = stdout.match(/^[\t ]*active count\s*=\s*(\d+)$/m)?.[1];
+  return activeCount !== undefined && Number(activeCount) > 0;
+}
+
 function requireServiceConfiguration(options, operation) {
   if (!options || typeof options !== "object" || Array.isArray(options)) {
     throw serviceFailure("connector_service_input_invalid", `Service ${operation} options are invalid`);

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,
@@ -17,7 +18,12 @@ import {
   verifyCodexExecutable,
 } from "./codex-discovery.mjs";
 import { LocalConnector } from "./local-connector.mjs";
-import { LocalConnectorCredentialStore } from "./credentials.mjs";
+import {
+  LocalConnectorCredentialStore,
+  clearConnectorReauthorizationRequired,
+  hasConnectorReauthorizationRequired,
+  markConnectorReauthorizationRequired,
+} from "./credentials.mjs";
 import { LocalConnectorPairingClient } from "./pairing-client.mjs";
 import { waitForEnterToOpenBrowser } from "./browser-prompt.mjs";
 import { chooseWorkspaceDirectory } from "./workspace-picker.mjs";
@@ -47,8 +53,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 +73,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 +125,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 +150,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.
 `);
 }
@@ -261,8 +278,9 @@ async function connect(flags, ui, options = {}) {
   const credentialFile = flags["credential-file"] ?? defaultCredentialFile();
   const store = new LocalConnectorCredentialStore({ filename: credentialFile });
   const current = await store.load();
+  const reauthorizationRequired = await hasConnectorReauthorizationRequired(credentialFile);
   const currentIsValid = current && Date.parse(current.connector_expires_at) > Date.now();
-  if (currentIsValid && current.receiver_origin === receiver) {
+  if (currentIsValid && current.receiver_origin === receiver && !reauthorizationRequired) {
     if (ui.interactive) {
       ui.success("Account", "already connected");
       if (!options.guidedInstall) {
@@ -321,6 +339,7 @@ async function connect(flags, ui, options = {}) {
     connector_expires_at: credentials.connector_expires_at,
   };
   await store.save(saved);
+  await clearConnectorReauthorizationRequired(credentialFile);
   if (ui.interactive) {
     if (!options.guidedInstall) {
       ui.complete("This Mac is connected", "Re-entry can now route approved work here.");
@@ -339,33 +358,44 @@ async function status(flags, ui) {
   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 reauthorizationRequired = await hasConnectorReauthorizationRequired(credentialFile);
   const readiness = inspectReadiness(flags);
   const service = await inspectMacConnectorService();
   const receiverReady = credentials ? await inspectReceiver(credentials.receiver_origin) : false;
-  const connected = Boolean(credentials && Date.parse(credentials.connector_expires_at) > Date.now());
+  const connected = Boolean(
+    credentials &&
+    Date.parse(credentials.connector_expires_at) > Date.now() &&
+    !reauthorizationRequired,
+  );
   if (ui.interactive) {
     ui.section("SYSTEM", "This Mac");
     showReadiness(readiness, ui);
     ui.section("CONNECTION", "Re-entry");
-    if (connected) ui.success("Account", "connected");
+    if (reauthorizationRequired) ui.warning("Account", "reconnect required");
+    else if (connected) ui.success("Account", "connected");
     else ui.warning("Account", "not connected");
-    if (service.running) ui.success("Background", "running");
+    if (reauthorizationRequired && service.running) ui.warning("Background", "paused until this Mac is reconnected");
+    else 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 (receiverReady) ui.success("Cloud", "online");
+    else if (credentials) ui.warning("Cloud", "unavailable");
 
-    if (!connected || !service.running) {
+    if (reauthorizationRequired) {
+      ui.next("re-entry connect", "Approve this Mac again in your browser; the old credential was rejected.");
+    } else 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",
       connected,
+      reauthorization_required: reauthorizationRequired,
       connector_id: credentials?.connector_id ?? null,
       receiver_origin: credentials?.receiver_origin ?? null,
       receiver_ready: receiverReady,
@@ -378,6 +408,119 @@ 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();
+  const reauthorizationRequired = await hasConnectorReauthorizationRequired(defaultCredentialFile());
+  if (reauthorizationRequired || !service.running || !credentials) {
+    if (ui.interactive) {
+      if (reauthorizationRequired) {
+        ui.warning("Account", "reconnect required; the Cloud Receiver rejected this Mac");
+        ui.next("re-entry connect", "Approve this Mac again in your browser.");
+      }
+      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),
+        reauthorization_required: reauthorizationRequired,
+        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_reauthorization_required" || event.code === "connector_identity_invalid") {
+    ui.stopWait("Reconnect required", "the Cloud Receiver rejected this Mac's saved connection", "warning");
+    ui.next("re-entry connect", "Approve this Mac again in your browser.");
+    return;
+  } 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");
@@ -442,7 +585,7 @@ async function install(flags, ui) {
   if (ui.interactive) {
     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.");
+    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",
@@ -478,6 +621,14 @@ async function start(flags, ui) {
   if (!credentials) {
     if (ui.interactive) ui.info("Re-entry", "first run — browser approval is required once");
     credentials = await connect(runtimeFlags, ui, { quietHeader: true });
+  } else if (await hasConnectorReauthorizationRequired(credentialFile)) {
+    if (ui.interactive) {
+      ui.warning("Account", "this Mac needs to be connected again");
+      ui.next("re-entry connect", "Approve this Mac in your browser, then start the Connector again.");
+    } else {
+      process.stdout.write('{"event":"connector_reauthorization_required"}\n');
+    }
+    return;
   } else if (ui.interactive) {
     ui.success("Re-entry", "existing account connection loaded");
   }
@@ -513,6 +664,18 @@ async function start(flags, ui) {
           if (ui.interactive) ui.wait("Connected. Waiting for approved work…");
         }
       } catch (error) {
+        if (error?.code === "connector_identity_invalid") {
+          await markConnectorReauthorizationRequired(credentialFile, {
+            receiver_origin: credentials.receiver_origin,
+          });
+          if (ui.interactive) {
+            ui.stopWait("Reconnect required", "the Cloud Receiver rejected this Mac's saved connection", "warning");
+            ui.next("re-entry connect", "Approve this Mac again in your browser.");
+          } else {
+            process.stdout.write('{"event":"connector_reauthorization_required"}\n');
+          }
+          return;
+        }
         consecutiveErrors += 1;
         if (ui.interactive) {
           ui.stopWait("Receiver unavailable", `${safeErrorMessage(error)} · ${consecutiveErrors}/${maximumErrors}`, "warning");
@@ -668,9 +831,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");
@@ -682,15 +850,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([
@@ -725,7 +895,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");
   }
 }
@@ -740,6 +914,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
@@ -755,6 +937,23 @@ function displayReceiver(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) {
@@ -838,6 +1037,8 @@ function errorHint(error) {
     connector_node_unsupported: "use Node.js 24 or newer, then run the command again",
     connector_credentials_missing: "connect this Mac once with `re-entry connect`",
     connector_credentials_expired: "run `re-entry connect` to authorize this Mac again",
+    connector_identity_invalid: "run `re-entry connect` and approve this Mac again",
+    connector_reauthorization_required: "run `re-entry connect` and approve this Mac again",
     connector_pairing_code_missing: "ask the Host backend for a new pairing code, then run pair in a terminal",
     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",
@@ -853,6 +1054,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

@@ -11,8 +11,11 @@ const SPINNER_FRAMES = ["·", "✦", "✧", "✦"];
 const RULE = "  ─────────────────────────────────────────────";
 
 export const REENTRY_WORDMARK = Object.freeze([
-  "  █▀█ █▀▀   █▀▀ █▄░█ ▀█▀ █▀█ █▄█",
-  "  █▀▄ ██▄ ▀ ██▄ █░▀█ ░█░ █▀▄ ░█░",
+  "   ____  _____      _____ _   _ _____ ______   __",
+  "  |  _ \\| ____|    | ____| \\ | |_   _|  _ \\ \\ / /",
+  "  | |_) |  _| _____|  _| |  \\| | | | | |_) | \\ V /",
+  "  |  _ <| |__|_____| |___| |\\  | | | |  _ <   | |",
+  "  |_| \\_\\_____|    |_____|_| \\_| |_| |_| \\_\\  |_|",
 ]);
 
 /**