codex-agent-view 0.3.2 → 0.4.0

package/bin/codex-agent-view.mjs

@@ -442,16 +442,90 @@ async function inspectRuntime() {
   }
 }
 
-async function runtimeResponds(runtime) {
+async function runtimeEndpointState(runtime) {
   try {
-    await fetch(`http://${runtime.host}:${runtime.port}/api/state`, {
+    const response = await fetch(`http://${runtime.host}:${runtime.port}/api/state`, {
       headers: { authorization: `Bearer ${runtime.token}` },
       signal: AbortSignal.timeout(1_500),
     });
-    return true;
+    if (!response.ok) {
+      await response.body?.cancel();
+      return "unrelated";
+    }
+    const snapshot = await response.json().catch(() => null);
+    return snapshot?.schema_version === 1 && snapshot?.source_of_truth === "hook"
+      ? "owned"
+      : "unrelated";
   } catch {
+    return "absent";
+  }
+}
+
+async function runtimeResponds(runtime) {
+  return (await runtimeEndpointState(runtime)) === "owned";
+}
+
+async function stopRunningRuntime(preflight) {
+  if (preflight.kind !== "valid") {
+    return false;
+  }
+  const endpointState = await runtimeEndpointState(preflight.info);
+  if (endpointState === "absent") {
     return false;
   }
+  if (endpointState === "unrelated") {
+    throw new Error(
+      "the runtime endpoint was not identified as an owned monitor; plugin and runtime files were preserved",
+    );
+  }
+
+  let response;
+  try {
+    response = await fetch(
+      `http://${preflight.info.host}:${preflight.info.port}/api/internal/shutdown`,
+      {
+        headers: { authorization: `Bearer ${preflight.info.token}` },
+        method: "POST",
+        signal: AbortSignal.timeout(1_500),
+      },
+    );
+  } catch {
+    throw new Error("the owned monitor could not be stopped; plugin files were preserved");
+  }
+  if (!response.ok) {
+    throw new Error(
+      `the owned monitor refused shutdown with HTTP ${response.status}; plugin files were preserved`,
+    );
+  }
+  const result = await response.json().catch(() => null);
+  if (result?.status !== "shutting_down") {
+    throw new Error(
+      "the owned monitor returned an invalid shutdown response; plugin files were preserved",
+    );
+  }
+
+  const deadline = Date.now() + 3_000;
+  while (Date.now() < deadline) {
+    const current = await inspectRuntime();
+    if (current.kind === "absent") {
+      return true;
+    }
+    if (current.kind === "unknown") {
+      await new Promise((resolvePromise) => setTimeout(resolvePromise, 25));
+      continue;
+    }
+    if (current.info.token !== preflight.info.token) {
+      throw new Error(
+        "runtime ownership changed during uninstall; new or unrecognized runtime data was preserved",
+      );
+    }
+    if (!(await runtimeResponds(current.info))) {
+      await removeRuntimeInfo(current.info.token);
+      return true;
+    }
+    await new Promise((resolvePromise) => setTimeout(resolvePromise, 25));
+  }
+  throw new Error("the owned monitor did not stop in time; plugin files were preserved");
 }
 
 async function inspectPluginBundle(destination) {
@@ -593,12 +667,19 @@ async function purgeStaleRuntime(preflight) {
   }
 
   const current = await inspectRuntime();
+  if (current.kind === "absent") {
+    return false;
+  }
   if (current.kind !== "valid" || current.info.token !== preflight.info.token) {
     return true;
   }
-  if (await runtimeResponds(current.info)) {
+  const endpointState = await runtimeEndpointState(current.info);
+  if (endpointState === "owned") {
     throw new Error("the Codex Agent View monitor started during uninstall; runtime data was preserved");
   }
+  if (endpointState === "unrelated") {
+    return true;
+  }
   await removeRuntimeInfo(current.info.token);
   return false;
 }
@@ -624,7 +705,28 @@ async function removeRuntimeRootIfEmpty(root) {
   }
 }
 
+function parseUninstallArgs(args) {
+  let purge = false;
+
+  for (const argument of args) {
+    if (argument === "--purge") {
+      if (purge) {
+        throw new Error("--purge may only be specified once");
+      }
+      purge = true;
+      continue;
+    }
+    if (argument.startsWith("-")) {
+      throw new Error(`unknown uninstall option: ${argument}`);
+    }
+    throw new Error(`unexpected uninstall argument: ${argument}`);
+  }
+
+  return { purge };
+}
+
 async function uninstall(args) {
+  const { purge } = parseUninstallArgs(args);
   const root = runtimeDirectory();
   const bundle = join(root, "marketplace");
   if (dirname(bundle) !== root || bundle === root) {
@@ -636,16 +738,8 @@ async function uninstall(args) {
     throw unmanagedBundleError(bundle);
   }
 
-  const purge = args.includes("--purge");
-  const runtimePreflight = purge ? await inspectRuntime() : { kind: "absent" };
-  if (
-    runtimePreflight.kind === "valid" &&
-    (await runtimeResponds(runtimePreflight.info))
-  ) {
-    throw new Error(
-      "the Codex Agent View monitor is running; stop it before uninstalling with --purge",
-    );
-  }
+  const runtimePreflight = await inspectRuntime();
+  const stoppedMonitor = await stopRunningRuntime(runtimePreflight);
 
   await run("codex", ["plugin", "remove", PLUGIN_ID, "--json"], { allowFailure: true });
   await run("codex", ["plugin", "marketplace", "remove", MARKETPLACE_NAME, "--json"], {
@@ -668,7 +762,11 @@ async function uninstall(args) {
       );
     }
   } else {
-    process.stdout.write("Removed plugin and marketplace bundle. Runtime data was preserved.\n");
+    process.stdout.write(
+      stoppedMonitor
+        ? "Stopped the owned monitor and removed the plugin and marketplace bundle.\n"
+        : "Removed plugin and marketplace bundle. Runtime data was preserved.\n",
+    );
   }
 }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "codex-agent-view",
-  "version": "0.3.2",
-  "description": "Read-only Codex app task view with an optional local live monitor.",
+  "version": "0.4.0",
+  "description": "Read-only Codex app task view with a trusted-hook auto-prepared local live backend.",
   "type": "module",
   "main": "./src/core/index.mjs",
   "exports": "./src/core/index.mjs",
@@ -15,11 +15,13 @@
     "bin/",
     "hooks/",
     "public/",
+    "scripts/auto-start-monitor.mjs",
     "scripts/capture-hook.mjs",
     "scripts/send-hook.mjs",
     "skills/",
     "src/",
     "README.md",
+    "README.ko.md",
     "LICENSE",
     "NOTICE"
   ],

package/public/app.js

@@ -69,6 +69,7 @@ const viewState = {
   hasLoaded: false,
   errorMessage: "",
   canRetry: true,
+  authenticationFailed: false,
   requestInFlight: false,
 };
 
@@ -531,9 +532,9 @@ function setEmptyObservationMessage() {
 
   const steps = document.createElement("ol");
   for (const step of [
-    "Codex Agent View를 실행한 뒤 새 Codex task를 시작합니다.",
-    "설치된 plugin의 현재 hook command를 검토하고 직접 trust했는지 확인합니다.",
-    "plugin 설치 또는 hook trust 변경 후 공식 Codex 앱을 완전히 재시작하고 새 task에서 subagent를 실행합니다.",
+    "Plugin을 설치한 뒤 공식 Codex 앱을 완전히 재시작했는지 확인합니다.",
+    "새 task에서 표시되는 Codex Agent View hook command를 검토하고 직접 trust합니다.",
+    "Trust 이후 새 task를 시작해 subagent 작업을 실행합니다. Hook event가 이 목록에 자동으로 추가됩니다.",
   ]) {
     const item = document.createElement("li");
     item.textContent = step;
@@ -542,7 +543,7 @@ function setEmptyObservationMessage() {
 
   const boundary = document.createElement("p");
   boundary.className = "observation-boundary";
-  boundary.textContent = "Plugin 설치·trust 전에 이미 지나간 event와 monitor가 꺼져 있던 동안의 event는 재생되지 않습니다.";
+  boundary.textContent = "관찰 window는 첫 trusted hook에서 시작합니다. 그 전에 이미 지나간 event와 로컬 상태 수집이 중단된 동안의 event는 재생되지 않으며, 수집이 다시 시작되면 새 관찰 window가 열립니다.";
 
   guidance.append(guidanceTitle, automaticTracking, steps, boundary);
 
@@ -594,12 +595,16 @@ function renderSessions() {
 
   if (viewState.errorMessage) {
     elements.sessionList.hidden = !visibleSessions.length;
-    const description = viewState.sessions.length
-      ? "마지막 정상 상태를 계속 표시합니다."
+    const description = viewState.canRetry
+      ? viewState.sessions.length
+        ? "2초마다 자동으로 다시 연결합니다. 마지막 정상 상태를 계속 표시합니다."
+        : "2초마다 자동으로 다시 연결합니다. Codex 앱에서 이 화면을 그대로 두어도 됩니다."
       : viewState.errorMessage;
     setStateMessage(
       "error",
-      "로컬 monitor에 연결할 수 없습니다.",
+      viewState.canRetry
+        ? "로컬 상태 연결이 끊겨 다시 시도 중입니다."
+        : "이 live view를 인증할 수 없습니다.",
       description,
       viewState.canRetry,
     );
@@ -632,26 +637,27 @@ function render() {
   renderSessions();
 }
 
-function setConnectionStatus(status) {
+function setConnectionStatus(status, labelOverride = "") {
   elements.connectionStatus.dataset.status = status;
   const labels = {
     connecting: "로컬 상태 연결 중",
     connected: "로컬 monitor 연결됨",
-    error: "연결 끊김",
+    error: "연결 끊김 · 재시도 중",
   };
-  elements.connectionLabel.textContent = labels[status];
+  elements.connectionLabel.textContent = labelOverride || labels[status];
 }
 
 async function refreshState() {
-  if (viewState.requestInFlight) {
+  if (viewState.requestInFlight || viewState.authenticationFailed) {
     return;
   }
 
   if (!accessToken) {
     viewState.hasLoaded = true;
     viewState.canRetry = false;
-    viewState.errorMessage = "접근 token이 없습니다. monitor를 다시 실행해 새 주소를 여세요.";
-    setConnectionStatus("error");
+    viewState.authenticationFailed = true;
+    viewState.errorMessage = "이 탭에는 접근 token이 없습니다. Codex 앱에서 Codex Agent View에 live view 열기를 다시 요청하세요.";
+    setConnectionStatus("error", "live view 인증 필요");
     render();
     return;
   }
@@ -671,6 +677,16 @@ async function refreshState() {
       },
     });
 
+    if (response.status === 401 || response.status === 403) {
+      await response.body?.cancel();
+      viewState.hasLoaded = true;
+      viewState.canRetry = false;
+      viewState.authenticationFailed = true;
+      viewState.errorMessage = "이 live view의 인증이 더 이상 유효하지 않습니다. Codex 앱에서 Codex Agent View에 live view 열기를 다시 요청하세요.";
+      setConnectionStatus("error", "live view 인증 필요");
+      return;
+    }
+
     if (!response.ok) {
       throw new Error(`상태 요청 실패 (${response.status})`);
     }
@@ -685,6 +701,7 @@ async function refreshState() {
     setConnectionStatus("connected");
   } catch (error) {
     viewState.hasLoaded = true;
+    viewState.canRetry = true;
     viewState.errorMessage = error instanceof Error
       ? error.message
       : "알 수 없는 연결 오류가 발생했습니다.";
@@ -702,6 +719,10 @@ elements.toolbar.addEventListener("submit", (event) => {
 });
 window.addEventListener("online", refreshState);
 window.addEventListener("offline", () => {
+  if (viewState.authenticationFailed) {
+    return;
+  }
+  viewState.canRetry = true;
   viewState.errorMessage = "이 기기가 오프라인입니다.";
   setConnectionStatus("error");
   render();

package/public/index.html

@@ -126,7 +126,7 @@
 
           <div id="state-message" class="state-message" role="status" aria-live="polite">
             <strong>상태를 불러오는 중입니다.</strong>
-            <span>로컬 monitor에 연결하고 있습니다.</span>
+            <span>Codex 앱의 로컬 상태에 연결하고 있습니다.</span>
           </div>
 
           <ul id="session-list" class="session-list" aria-label="Codex 부모 task 목록" hidden></ul>

package/scripts/auto-start-monitor.mjs

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+
+import { access } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+
+import { startMonitorServer } from "../src/runtime/server.mjs";
+import { autoStartPort, readRuntimeInfo } from "../src/runtime/config.mjs";
+
+const HEALTH_TIMEOUT_MS = 350;
+const OWNER_CHECK_INTERVAL_MS = 1_000;
+const OWNER_FILE = fileURLToPath(
+  new URL("../.codex-plugin/plugin.json", import.meta.url),
+);
+
+async function currentMonitorIsHealthy() {
+  try {
+    const runtime = await readRuntimeInfo();
+    const response = await fetch(
+      `http://${runtime.host}:${runtime.port}/api/state`,
+      {
+        headers: { authorization: `Bearer ${runtime.token}` },
+        signal: AbortSignal.timeout(HEALTH_TIMEOUT_MS),
+      },
+    );
+    return response.ok;
+  } catch {
+    return false;
+  }
+}
+
+async function main() {
+  let monitor;
+  let ownerCheck;
+  let stopRequested = false;
+  let stopping = false;
+  const stop = async () => {
+    stopRequested = true;
+    if (!monitor || stopping) {
+      return;
+    }
+    stopping = true;
+    clearInterval(ownerCheck);
+    try {
+      await monitor.close();
+    } finally {
+      process.exit(0);
+    }
+  };
+
+  process.once("SIGINT", stop);
+  process.once("SIGTERM", stop);
+
+  if (await currentMonitorIsHealthy()) {
+    process.off("SIGINT", stop);
+    process.off("SIGTERM", stop);
+    return;
+  }
+
+  try {
+    monitor = await startMonitorServer({ port: autoStartPort() });
+  } catch (error) {
+    process.off("SIGINT", stop);
+    process.off("SIGTERM", stop);
+    throw error;
+  }
+  if (stopRequested) {
+    await stop();
+    return;
+  }
+
+  // An npm/plugin uninstall removes this owned bundle. The detached monitor
+  // then shuts itself down and removes only the runtime file it still owns.
+  ownerCheck = setInterval(async () => {
+    try {
+      await access(OWNER_FILE);
+    } catch (error) {
+      if (error?.code === "ENOENT" || error?.code === "ENOTDIR") {
+        await stop();
+      }
+    }
+  }, OWNER_CHECK_INTERVAL_MS);
+  ownerCheck.unref();
+}
+
+// Auto-start is an internal hook implementation detail. It must never write a
+// tokenized URL, a local path, or hook-derived data to stdout/stderr.
+main().catch(() => {
+  process.exitCode = 0;
+});

package/scripts/send-hook.mjs

@@ -1,12 +1,16 @@
 #!/usr/bin/env node
 
+import { spawn } from "node:child_process";
 import { basename } from "node:path";
+import { fileURLToPath } from "node:url";
 
 import { minimizePayload } from "./capture-hook.mjs";
 import { readRuntimeInfo } from "../src/runtime/config.mjs";
 
 const MAX_STDIN_BYTES = 2 * 1024 * 1024;
-const SEND_TIMEOUT_MS = 750;
+const SEND_TIMEOUT_MS = 500;
+const AUTO_START_WAIT_MS = 1_600;
+const AUTO_START_POLL_MS = 40;
 const MAX_WORKSPACE_LABEL_LENGTH = 120;
 const CONTROL_CHARACTERS = /[\u0000-\u001f\u007f-\u009f]/g;
 
@@ -55,8 +59,7 @@ function monitorEnvelope(payload) {
     : minimized;
 }
 
-async function send(payload) {
-  const runtime = await readRuntimeInfo();
+async function sendToRuntime(runtime, envelope) {
   const response = await fetch(
     `http://${runtime.host}:${runtime.port}/api/events`,
     {
@@ -65,7 +68,7 @@ async function send(payload) {
         authorization: `Bearer ${runtime.token}`,
         "content-type": "application/json",
       },
-      body: JSON.stringify(monitorEnvelope(payload)),
+      body: JSON.stringify(envelope),
       signal: AbortSignal.timeout(SEND_TIMEOUT_MS),
     },
   );
@@ -74,6 +77,66 @@ async function send(payload) {
   }
 }
 
+function childEnvironment() {
+  const env = {};
+  for (const key of [
+    "CODEX_AGENT_VIEW_AUTO_START_PORT",
+    "CODEX_AGENT_VIEW_RUNTIME_DIR",
+    "SystemRoot",
+  ]) {
+    if (typeof process.env[key] === "string") {
+      env[key] = process.env[key];
+    }
+  }
+  return env;
+}
+
+function startMonitorDetached() {
+  const child = spawn(
+    process.execPath,
+    [fileURLToPath(new URL("./auto-start-monitor.mjs", import.meta.url))],
+    {
+      detached: true,
+      env: childEnvironment(),
+      shell: false,
+      stdio: "ignore",
+    },
+  );
+  child.on("error", () => {});
+  child.unref();
+}
+
+async function delay(milliseconds) {
+  await new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+
+async function tryDelivery(envelope) {
+  try {
+    await sendToRuntime(await readRuntimeInfo(), envelope);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function send(payload) {
+  const envelope = monitorEnvelope(payload);
+  if (await tryDelivery(envelope)) {
+    return;
+  }
+
+  startMonitorDetached();
+  const deadline = Date.now() + AUTO_START_WAIT_MS;
+  do {
+    await delay(AUTO_START_POLL_MS);
+    if (await tryDelivery(envelope)) {
+      return;
+    }
+  } while (Date.now() < deadline);
+
+  throw new Error("monitor auto-start delivery timed out");
+}
+
 async function main() {
   try {
     await send(await readStdin());

package/skills/codex-agent-view/SKILL.md

@@ -109,6 +109,13 @@ means that monitor process observed no hook events; it does not prove that the
 Codex app has no tasks. Restarting the in-memory monitor begins a new bounded
 observation window.
 
+After explicit installation, hook review/trust, and a Codex app restart, the
+first trusted hook normally prepares the local backend internally and retries
+delivery of that same privacy-minimized event. The user never registers a task
+ID or runs `start`, `status`, or `doctor` as part of ordinary use. A bounded
+auto-start failure remains fail-open and does not create a persistent replay
+queue.
+
 ## Open the live view only on request
 
 Only when the user explicitly asks to open, show, or start the live view:
@@ -117,7 +124,15 @@ The plugin agent performs the health check and any required start internally.
 The user's entire interaction after installation remains inside the official
 Codex app; do not turn the commands below into instructions for the user.
 
-1. Check monitor health with the packaged CLI.
+The public Codex plugin API cannot create a sidebar, panel, or Browser tab
+without a prompt at app startup. The first live view therefore requires one
+explicit request in a Codex app task. Do not claim that installation alone
+opens a screen. An already-open in-app live tab refreshes and reconnects after
+temporary disconnects while the same monitor observation window and its
+session token remain valid.
+
+1. Check monitor health with the packaged CLI. A trusted hook may already have
+   prepared it automatically.
 2. If it is not running, start it with `codex-agent-view start --no-open` so the
    CLI never launches the operating system's external browser.
 3. Keep the returned tokenized localhost URL private. Never quote it, place it
@@ -133,6 +148,10 @@ Do not restart or replace a healthy monitor merely to recover its URL because
 that would discard its in-memory observation window. Reuse an existing in-app
 monitor tab when possible. Do not close user-owned browser tabs.
 
+If an existing tab has lost its session token or the monitor restarted, do not
+promise automatic recovery across observation windows. Reopen the live view
+through the same explicit in-app workflow without exposing the private URL.
+
 ## Lifecycle and safety
 
 Run `codex-agent-view install` or `codex-agent-view uninstall` only when the
@@ -140,7 +159,15 @@ user explicitly requests that lifecycle action. Explain that install changes
 local Codex plugin registration and requires hook review/trust. Before
 uninstalling, distinguish the default command, which preserves runtime data,
 from `codex-agent-view uninstall --purge`, which removes the configured runtime
-directory.
+directory only within its owned-file safety boundary. Do not ask the user to
+stop an auto-started or foreground monitor first. The uninstall command uses
+the validated runtime bearer token to authenticate and internally shut down a
+healthy owned monitor before removing plugin files. The default command
+preserves remaining runtime-directory data. `--purge` additionally removes
+only an owned stale runtime file and an empty runtime directory; it preserves
+unrecognized files, unrelated loopback services, and non-empty directories.
+If an owned monitor cannot be stopped safely or the endpoint is unrelated,
+report that removal stopped with plugin and runtime files preserved.
 
 Keep every workflow read-only with respect to Codex tasks. Never stop or
 restart a task or subagent, send a message to an agent, approve or deny a

package/skills/show-agents/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: show-agents
+description: Open the Codex Agent View live task and subagent monitor in the official Codex app. Use when the user explicitly selects the bundled Show Agents skill from the app's @ menu.
+---
+
+# Show Agents
+
+Treat selection of the bundled **Show Agents** skill from the Codex app's `@`
+menu as an explicit request to open the live monitor, not as a request for
+terminal instructions or a text-only snapshot. Keep the whole ordinary-use
+workflow inside the calling Codex app task.
+
+## Open the live view
+
+1. Run `codex-agent-view doctor --json` internally and inspect only its
+   structured diagnostics. Capture the result internally; do not quote the
+   command, raw output, runtime path, IDs, or private URL in commentary or the
+   final response.
+2. If diagnostics contain `plugin_version_mismatch`, stop the workflow before
+   running `codex-agent-view status --json`, starting a monitor, or opening a
+   panel. Briefly tell the user inside the current Codex app task that the
+   installed plugin and global CLI versions differ and that the exact intended
+   `codex-agent-view` version must be globally reinstalled before they select
+   **Show Agents** again. Do not perform the reinstall, change Codex settings,
+   expose paths, or quote the diagnostic payload.
+3. Otherwise, check the packaged monitor with
+   `codex-agent-view status --json`. Capture the result internally; do not
+   quote the command, raw output, runtime path, IDs, or private URL in
+   commentary or the final response.
+4. If the monitor is healthy, reuse it. Recover its authenticated URL from the
+   owned private runtime record without restarting it, because restarting would
+   discard the current in-memory observation window.
+5. If the monitor is not healthy, run `codex-agent-view start --no-open` as a
+   persistent internal process and capture the authenticated URL it returns.
+   Never use `--open` or launch an external browser.
+6. Accept the URL only when it uses `http`, host `127.0.0.1`, a valid local
+   port, and the expected non-empty fragment token. Treat every other target as
+   invalid and do not open it.
+7. Call `codex_app__open_in_codex` for the calling task with a browser target,
+   the validated private URL, and `placement: "right"`. Omit `threadId`; never
+   navigate to or open the monitor in another task.
+8. If a previous successful call in the current context supplied the same
+   monitor tab's `tabId`, prefer reopening that browser target by `tabId`.
+   Otherwise open the validated URL. Do not close or replace user-owned tabs.
+
+The in-app Browser capability or site permission may be unavailable or may
+require a user confirmation. Do not claim that the panel opened until
+`codex_app__open_in_codex` reports success. Let Codex show its normal app
+permission request when required; never replace it with terminal instructions.
+
+Never place the tokenized localhost URL in Markdown, plain text, code, logs, or
+user instructions. It may appear only as private agent-internal state and as
+the browser target passed to `codex_app__open_in_codex`.
+
+## Failure behavior
+
+If the official app cannot open a browser panel, Browser is unavailable, or
+site permission is denied, do not expose the private URL or suggest a terminal
+or external-browser workaround. Briefly report that the live panel could not
+be opened and offer the existing app-native task snapshot from the bundled
+`codex-agent-view` skill.
+
+Keep the workflow read-only. Never stop or restart a Codex task or subagent,
+send messages to them, or approve or deny permission requests.

package/skills/show-agents/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Show Agents"
+  short_description: "Open the live agent monitor inside Codex"
+policy:
+  allow_implicit_invocation: false

package/src/runtime/config.mjs

@@ -16,6 +16,21 @@ export const DEFAULT_PORT = 43127;
 export const MAX_EVENT_BODY_BYTES = 64 * 1024;
 export const RUNTIME_SCHEMA_VERSION = 1;
 
+export function autoStartPort(env = process.env) {
+  const configured = env.CODEX_AGENT_VIEW_AUTO_START_PORT;
+  if (configured === undefined || configured === "") {
+    return DEFAULT_PORT;
+  }
+  if (!/^\d+$/.test(configured)) {
+    throw new Error("invalid Codex Agent View auto-start port");
+  }
+  const port = Number(configured);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new Error("invalid Codex Agent View auto-start port");
+  }
+  return port;
+}
+
 export function runtimeDirectory(env = process.env) {
   return resolve(
     env.CODEX_AGENT_VIEW_RUNTIME_DIR || join(homedir(), ".codex-agent-view"),