codex-agent-view 0.4.7 → 0.4.8

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-agent-view",
-  "version": "0.4.7",
+  "version": "0.4.8",
   "description": "Follow Codex work and participating agent progress in a clear, read-only live view inside the official Codex app.",
   "author": {
     "name": "Junho Yoon",

package/README.ko.md

@@ -10,10 +10,10 @@ Codex Agent View는 Codex가 지금 어떤 작업을 수행하고 있고 어떤
 
 ### 빠른 시작: 설치 후에는 Codex 앱 안에서만 사용
 
-이 README는 `codex-agent-view@0.4.7` 사용법을 설명한다. **최초 설치만** 일반 터미널에서 아래 exact-version 명령으로 진행한다.
+이 README는 `codex-agent-view@0.4.8` release candidate 사용법을 설명한다. 해당 version이 공개된 뒤 **최초 설치만** 일반 터미널에서 아래 exact-version 명령으로 진행한다.
 
 ```bash
-npm install --global codex-agent-view@0.4.7
+npm install --global codex-agent-view@0.4.8
 codex-agent-view install
 ```
 
@@ -30,9 +30,9 @@ codex-agent-view install
 
 **지금 사용해보기는 skill 호출이 아니다.** Codex plugin의 `interface.defaultPrompt`는 starter text이며, `$show-agents`처럼 보이는 text도 skill 선택으로 해석된다고 보장되지 않는다. 따라서 Codex Agent View는 plugin 카드 starter prompt를 정의하지 않는다. `@codex-agent-view`로 plugin을 선택한 다음 Codex 앱의 skill UI에서 `$show-agents`를 명시적으로 선택한다. 일반 사용에는 terminal command, 외부 browser 또는 localhost URL 관리가 필요 없다.
 
-Trust된 첫 hook이 도착하면 plugin sender가 로컬 backend를 내부적으로 준비하고 같은 event 전달을 재시도한다. 사용자는 task ID를 등록하거나 `start`, `status`, `doctor`를 실행할 필요가 없다. **Show Agents**는 healthy backend를 재사용하고 Codex 앱 안에서 live 화면 열기를 시도한다. 앱이 필요한 Browser capability를 제공하지 않거나 permission이 허용되지 않으면 private URL을 노출하는 대신 화면을 열 수 없다고 안내한다. Tokenized localhost URL은 대화에 노출하지 않으며 외부 browser도 정상 사용 흐름에 포함되지 않는다.
+Trust된 첫 hook이 도착하면 plugin sender가 로컬 backend를 내부적으로 준비하고 같은 event 전달을 재시도한다. 사용자는 task ID를 등록하거나 `start`, `status`, `doctor`를 실행할 필요가 없다. 정상 경로의 **Show Agents**는 내부 `prepare-live-view` command 1회와 Codex in-app Browser open 요청 1회만 수행한다. Command는 runtime bearer를 보내기 전에 fresh nonce/HMAC ownership proof로 exact owned monitor를 검증하고, 그 process의 runtime token으로 서명한 1회용 60초 bootstrap grant를 발급받는다. URL fragment에는 이 bounded grant만 들어가며 installation-owned viewer credential과 runtime/control token은 들어가지 않는다. 모든 request는 exact `127.0.0.1:<port>` authority와 origin-form target을 사용한다. Cookie, CORS access, external browser와 사용자가 관리하는 localhost URL은 없다.
 
-공개 Codex plugin API에는 prompt 없이 앱 시작과 동시에 sidebar, panel 또는 Browser tab을 생성하는 기능이 없다. 따라서 live 화면을 열 때 Codex 앱 안에서 `$show-agents` skill을 한 번 명시 선택해야 한다. 이미 오른쪽에 열린 live tab은 2초마다 자동 갱신하고, backend가 같은 loopback origin으로 돌아오면 일시 연결 단절·monitor 재시작·package upgrade 뒤에도 자동 재연결한다. Live view를 호출한 task 자신은 앱이 제공한 `CODEX_THREAD_ID`로 제외하므로 viewer task가 목록 위에 반복 노출되지 않는다. Monitor가 재시작되면 live 관찰 window는 새로 시작하며 read-only viewer credential만 유지된다.
+공개 Codex plugin API에는 prompt 없이 앱 시작과 동시에 sidebar, panel 또는 Browser tab을 생성하는 기능이 없다. 따라서 live 화면을 열 때 Codex 앱 안에서 `$show-agents` skill을 한 번 명시 선택해야 한다. Bootstrap은 access/recovery/refresh가 절대 연장할 수 없는 signed 30분 credential-family 만료 시각을 처음에 고정한다. 15분 access credential은 같은 family 안에서만 자동 갱신되어 그 tab이 family 끝까지 끊기지 않는다. Recovery는 `localStorage`가 아니라 tab-scoped `sessionStorage`에만 둔다. 인증 이력이 없는 tab에는 작동하지 않는 button이 없고, family가 만료되면 실제 `$show-agents` skill을 다시 호출해야 한다. Validated `CODEX_THREAD_ID`는 family에 signed binding된다. Bootstrap은 발급 process 안에서 1회만 쓸 수 있고 monitor가 재시작되면 즉시 무효가 된다.
 
 Live UI의 기본 언어는 영어이며 language selector에서 **English**, **한국어**, **Español**을 고를 수 있다. 활동은 refresh 때 접히는 disclosure toggle 없이 계속 보이고, 2초 polling 간격도 유지한다. 각 작업에는 `UserPromptSubmit`에서 만든 첫 번째 유효 요청 요약을 표시할 수 있다. Sender는 원문 중 최대 4,096자만 검사하고 일반적인 credential, 이메일 주소, 링크와 절대 경로를 가린 뒤 한 줄·최대 180자로 제한하며 전체 요청 원문은 즉시 버린다. 이후의 짧은 follow-up은 이 첫 요약을 덮지 않는다. 실제 확인한 `SubagentStart` payload는 `agent_id`, `agent_type`만 제공하며 전용 할당 작업 설명 field가 없다. 따라서 작업 전체의 요청 요약은 보여주되 prompt나 tool input에서 에이전트별 할당 내용을 추측하지 않는다.
 
@@ -40,7 +40,7 @@ Live UI의 기본 언어는 영어이며 language selector에서 **English**, **
 
 ### 현재 상태
 
-`0.4.7`은 lifecycle 정확성 patch를 완성한다. `SessionEnd` 최종 우선순위, 늦은 event 차단과 정직한 **종료 미확인** 표시에 더해, 정상 또는 늦게 도착한 `SubagentStop`과 `PostToolUse`가 recent activity의 대응 start 항목을 **중지됨** 또는 **완료**로 갱신한다. 따라서 종료된 agent나 tool의 이전 recent activity가 잘못 **실행 중**으로 남지 않는다. 아래의 기존 제품 구성은 그대로 유지한다.
+`0.4.8`은 더 빠르고 복구 가능하며 최소 권한인 live-view open을 목표로 하는 release candidate다. 정상 `$show-agents` 경로는 내부 준비 command 1회와 in-app Browser open 요청 1회로 줄어든다. Runtime bearer 전에는 ownership을 증명하고 URL에는 1회용 60초 process-signed bootstrap grant만 넣는다. Fixed 30분 signed family 안에서 15분 access를 자동 갱신하고 recovery는 tab-scoped이며 family deadline을 연장하지 않는다. Monitor restart는 사용 전 bootstrap만 무효화하고 이미 exchange된 family는 original expiry까지 새 in-memory 관찰 window에 재연결할 수 있다. Family 만료 뒤에는 actual skill을 다시 호출해야 한다. Source `npm run check`는 153개 test, plugin validation과 package dry-run을 통과했다. 공식 Codex in-app Browser에서는 grant 인증, fragment 제거, 같은 tab bare-root recovery button 성공과 새 tab의 recovery button 부재를 확인했다. Updated 공식 앱 hook의 실제 전달은 현재 app process 재시작 전이라 아직 미확인이다. npm publish, GitHub Release, CI와 public exact install은 아직 주장하지 않는다.
 
 - 공식 Codex 앱의 내장 thread tools를 우선 사용하는 app-native active-task snapshot skill
 - `.codex-plugin/plugin.json`, local marketplace catalog, genuine Codex skill
@@ -106,7 +106,7 @@ Codex Agent View는 historical audit이나 session replay 제품이 아니라
 - Plugin 카드의 **지금 사용해보기**는 `@codex-agent-view`만 선택한다. Starter text를 덧붙이거나 skill을 dispatch한다고 주장하지 않는다. Live view를 열거나 다시 열 때 Codex 앱에서 `$show-agents`를 명시 선택하며, 별도 monitor 실행이나 task ID 등록은 필요 없다.
 - npm은 plugin bundle, 내부 hook sender/runtime과 static UI를 사용자 machine에 배포하는 최초 설치 경로다.
 - Live view는 사용자가 앱 안에서 `$show-agents`를 명시 호출했을 때만 열린다. 외부 website나 telemetry dashboard가 아니다.
-- 공개 plugin API는 앱 시작 시 no-prompt sidebar/panel/Browser tab 생성을 제공하지 않는다. 최초 live view 열기에는 앱 안 skill 선택이 한 번 필요하고, 열린 tab은 같은 설치의 viewer credential과 loopback origin이 유지되는 동안 일시 단절·monitor 재시작·upgrade 뒤에도 자동 갱신·재연결한다.
+- 공개 plugin API는 앱 시작 시 no-prompt sidebar/panel/Browser tab 생성을 제공하지 않는다. 최초 live view 열기에는 앱 안 skill 선택이 한 번 필요하다. Current candidate의 tab은 fixed 30분 credential family 안에서 access를 자동 갱신한다. Monitor restart는 아직 교환하지 않은 bootstrap만 무효화하고 이미 발급된 family는 original deadline까지 같은 port에서 재연결할 수 있다. Family 만료 뒤에는 actual skill을 다시 호출해야 한다.
 - Universal Plugins Directory는 npm의 대체재가 아니다. 공개 directory의 in-app custom UI 경로는 public HTTPS MCP server와 domain verification이 필요해 local-only/no-external-server 원칙과 충돌한다. 현재는 별도의 listing/skills 제출 가능성만 검토하며, 심사·publish 전에는 Codex plugin 검색으로 설치할 수 있다고 안내하지 않는다.
 
 Hook event가 누락·중복·역순으로 올 수 있으므로 UI의 `unknown`, `stopped_without_start`, 빈 상태는 그대로 해석해야 한다. 빈 session 목록은 “이 monitor가 event를 관찰하지 못함”이며 “실행 중인 task가 없음”의 증거가 아니다.
@@ -121,7 +121,7 @@ Hook event가 누락·중복·역순으로 올 수 있으므로 UI의 `unknown`,
 4. Language selector에서 **English**, **한국어**, **Español**을 선택한다. 기본값은 영어이고 언어 전환 뒤에도 2초 refresh는 유지된다.
 5. 앱의 Browser capability 또는 permission을 사용할 수 없으면 private localhost URL을 노출하거나 외부 browser를 여는 대신 실패를 안내한다.
 
-오른쪽 live 화면을 닫았다면 Codex 앱 task에서 `@codex-agent-view`를 선택하고 `$show-agents`를 다시 명시 호출한다. 붙여 넣은 `@codex-agent-view $show-agents` 문자열이 skill 선택으로 재해석된다고 가정하지 않는다. 열린 tab은 일시 단절·monitor 재시작·upgrade 뒤에도 자동 재연결한다. 요청 실패 화면에는 **연결 다시 시도** 버튼이 있고, 인증이 거부되거나 사라진 화면에는 앱 안 복구 안내와 현재 tab의 인증을 다시 확인하는 버튼이 나타난다. 다만 페이지가 private credential을 스스로 발급하거나 복구할 수는 없으므로 재확인이 실패하면 Codex 앱에서 실제 `$show-agents` skill을 선택해 새 인증 화면을 연다. 복구에 terminal command, private URL 복사 또는 외부 browser는 필요 없다. 재시작된 monitor는 과거 event를 재생하지 않고 새 in-memory 관찰 window를 표시한다.
+오른쪽 live 화면을 닫았다면 Codex 앱 task에서 `@codex-agent-view`를 선택하고 `$show-agents`를 다시 명시 호출한다. 붙여 넣은 `@codex-agent-view $show-agents` 문자열이 skill 선택으로 재해석된다고 가정하지 않는다. Fixed 30분 family 동안 같은 tab은 recovery를 `sessionStorage`에만 보관하고 15분 access를 자동 갱신하며, page-level access가 없거나 거부될 때 **다시 연결** button을 표시한다. 다른 tab이나 인증 이력이 없는 tab에는 recovery가 없다. Family 만료 뒤에는 actual `$show-agents` skill을 다시 호출해야 한다. 복구에 terminal command, private URL 복사, cookie, CORS access 또는 외부 browser는 필요 없다. Monitor restart는 새 in-memory 관찰 window를 시작하고 이전 process의 미사용 bootstrap을 즉시 무효화한다.
 
 ### 요구사항과 검증 범위
 
@@ -214,16 +214,16 @@ Plugin enable/trust와 앱 재시작 뒤 생성되거나 재개되는 task는 tr
 
 ### npm 설치 명령 참고
 
-아래 명령은 `0.4.7`을 exact version으로 설치한다.
+아래 명령은 공개 후 `0.4.8`을 exact version으로 설치한다.
 
 ```bash
-npm install --global codex-agent-view@0.4.7
+npm install --global codex-agent-view@0.4.8
 codex-agent-view install
 ```
 
 이 두 명령 뒤에는 Codex 앱을 완전히 다시 열고 Plugins 화면에서 설치·활성화와 hook trust를 확인한 다음 새 task를 만든다. 첫 trusted hook이 backend 준비와 event 전달을 내부 처리하므로 사용자가 monitor CLI를 실행하지 않는다. Plugin 카드의 **지금 사용해보기**로 `@codex-agent-view`를 선택하고 앱에서 `$show-agents`를 명시 선택한다. Panel을 닫은 뒤에도 같은 방식으로 skill을 다시 선택한다.
 
-`0.4.7` 설치 경로는 위의 global package 설치와 명시적인 `codex-agent-view install` command 조합이다. 이후 일반 사용은 Codex 앱 안에서 진행한다. 이전의 유효한 설치에서 upgrade하면 installation-owned read-only viewer credential을 유지하며, `0.4.3`에서 검증한 legacy `0.4.2` migration 동작도 그대로 보존한다. Token과 private URL은 출력하지 않는다.
+`0.4.8` 설치 경로는 위의 global package 설치와 명시적인 `codex-agent-view install` command 조합이다. 이후 일반 사용은 Codex 앱 안에서 진행한다. Upgrade의 explicit `install`은 existing authenticated maintenance lifecycle로 healthy owned `0.4.7` monitor를 먼저 정지한 뒤 registration과 bundle을 교체한다. Installation-owned viewer credential과 `0.4.3`에서 검증한 legacy `0.4.2` migration 경계는 보존한다. 정상 Show Agents workflow는 persistent token을 출력하지 않고 Browser target에도 넣지 않는다.
 
 Version별 npm, install, migration, CI, tag와 GitHub Release evidence는 [docs/distribution.md](docs/distribution.md)에 보존한다. 각 evidence는 실제 확인한 뒤에만 갱신한다.
 

package/README.md

@@ -8,12 +8,12 @@ Codex Agent View gives you a clear, read-only view of what Codex is working on a
 
 ## Quick start: install once, then stay inside the Codex app
 
-This README documents `codex-agent-view@0.4.7`. Use the exact-version command below for the one-time terminal installation.
+This README documents the `codex-agent-view@0.4.8` release candidate. Use the exact-version command below for the one-time terminal installation after that version is published.
 
 Universal Plugins Directory search installation is not available yet, so use a regular terminal for the **initial installation only**:
 
 ```bash
-npm install --global codex-agent-view@0.4.7
+npm install --global codex-agent-view@0.4.8
 codex-agent-view install
 ```
 
@@ -30,9 +30,9 @@ After installation:
 
 **Quick start is not a skill invocation.** Codex plugin `interface.defaultPrompt` values are starter text, and text that looks like `$show-agents` is not guaranteed to be interpreted as a skill selection. Codex Agent View therefore defines no plugin-card starter prompt. Select the plugin with `@codex-agent-view`, then explicitly select `$show-agents` using the Codex app's skill UI. Routine use still requires neither a terminal command, an external browser, nor a localhost URL.
 
-When the first trusted hook arrives, the plugin sender internally prepares the local backend and retries delivery of that same event. Users do not register task IDs or run `start`, `status`, or `doctor`. **Show Agents** reuses the healthy backend and attempts to open the live view in the Codex app without exposing a tokenized localhost URL or using an external browser. If the app does not provide the required Browser capability or permission, the skill reports that it could not open the view instead of exposing a private URL.
+When the first trusted hook arrives, the plugin sender internally prepares the local backend and retries delivery of that same event. Users do not register task IDs or run `start`, `status`, or `doctor`. On its normal path, **Show Agents** runs one internal `prepare-live-view` command and makes one Codex in-app Browser open request. Before sending the runtime bearer, the command verifies a fresh nonce/HMAC ownership proof from the exact owned monitor. It then obtains a one-time, 60-second bootstrap grant signed by that process's runtime token. Only that bounded grant enters the URL fragment: the installation-owned viewer credential and runtime/control token do not. Every request uses the exact `127.0.0.1:<port>` authority and origin-form target. No cookie, CORS access, external browser, or user-managed localhost URL is involved.
 
-The public Codex plugin API does not provide no-prompt app-start creation of a sidebar, panel, or Browser tab. Opening the live view therefore requires one explicit `$show-agents` skill selection inside the Codex app. Once the right-side live tab is open, it refreshes every two seconds and automatically reconnects after a temporary disconnect, monitor restart, or package upgrade when the backend returns on the same loopback origin. The task that invoked the live view is excluded using the app-provided `CODEX_THREAD_ID`, so the monitor does not keep promoting its own viewer task. The live observation window still resets when the monitor process restarts; only the read-only viewer credential survives.
+The public Codex plugin API does not provide no-prompt app-start creation of a sidebar, panel, or Browser tab. Opening the live view therefore requires one explicit `$show-agents` skill selection inside the Codex app. The bootstrap fixes one signed 30-minute credential-family expiry that access, recovery, and refresh can never extend. Fifteen-minute access credentials refresh automatically only inside that family, so the same tab remains connected until the family ends. Recovery is tab-scoped `sessionStorage`, not `localStorage`. A previously authenticated tab can therefore use **Reconnect** after losing page-level access, while a tab with no authentication history shows no nonfunctional button. When the family expires, the actual `$show-agents` skill must be invoked again. The invoking task's validated `CODEX_THREAD_ID` remains signed into the family. A bootstrap is one-use within its issuing process and becomes invalid immediately when that monitor restarts; a family already exchanged under the persistent viewer signing key can reconnect on the same origin until its original absolute expiry.
 
 The live UI defaults to English and offers **English**, **Korean**, and **Spanish** in its language selector. Activity remains visible rather than hidden behind refresh-sensitive disclosure toggles, and the two-second polling interval is unchanged. Each work item can show its first valid short request summary derived from `UserPromptSubmit`: the sender inspects at most 4,096 characters, redacts common credentials, email addresses, links, and absolute paths, collapses the result to one line, bounds it to 180 characters, and immediately discards the full request. Later follow-ups do not replace that first valid summary. Verified `SubagentStart` payloads still provide only `agent_id` and `agent_type`; they do not provide a dedicated assignment description. The monitor therefore shows the work-level request summary but does not invent an agent-specific assignment from prompts or tool input.
 
@@ -40,7 +40,7 @@ In short: install once in a terminal; perform snapshot queries, status checks, l
 
 ## Status
 
-Version `0.4.7` completes the lifecycle-correctness patch. In addition to terminal `SessionEnd`, late-event protection, and honest **End not confirmed** state, normal or late `SubagentStop` and `PostToolUse` events now refine the matching earlier start entry in recent activity to **Stopped** or **Completed**. A finished agent or tool therefore no longer leaves its prior recent-activity row falsely **Running**. It retains the app-native snapshot skill, privacy-minimized hooks, bounded in-memory reducer, local authenticated live backend, and explicit install/remove plus maintainer-diagnostic CLI commands.
+Version `0.4.8` is a release candidate focused on faster, recoverable, least-privilege live-view opening. Its normal `$show-agents` path is reduced to one internal preparation command followed by one in-app Browser open request. Ownership is proven before the runtime bearer is sent; the URL carries only a one-use, 60-second process-signed bootstrap grant. A fixed 30-minute signed family supports automatic 15-minute access refresh and tab-scoped recovery without extending the family deadline. Monitor restart invalidates only an unused bootstrap; an exchanged family can reconnect to the new in-memory observation window until its original expiry. Family expiry requires the actual skill again. Source `npm run check` passes all 153 tests plus plugin validation and package dry-run. In the official Codex in-app Browser, grant authentication, fragment removal, same-tab bare-root recovery, and absence of a recovery button in a new tab were observed. Updated official-app hook delivery remains unverified until the current app process is restarted. npm publication, GitHub Release, CI, and public exact installation are not yet claimed.
 
 Plugin installation and lifecycle payloads were verified with Homebrew Codex CLI and the Codex executable embedded in the official app. However, a real-use attempt that installed and enabled `0.2.0` in an already-running official app process delivered zero events while two subagents ran. The monitor, registration, enablement, and installed bundle were healthy, while app logs showed no sender invocation. Evidence indicates that the same process retained a pre-install `hooks/list` snapshot; persisted exact-hook trust is not exposed through CLI JSON, so the precise skip boundary remains unconfirmed.
 
@@ -80,7 +80,7 @@ Codex Agent View is a live companion, not a historical audit or session-replay p
 - Hooks remain the source of truth for detailed lifecycle state in the trusted-hook auto-prepared local live backend. Its operational state exists only in bounded process memory; restart begins a new observation window. The separate private viewer credential is authentication metadata, not stored task history.
 - `Stop` marks the observed root turn and the session/work-item summary `completed` immediately. If a child agent or tool was still active, its own row is separately marked `completion_not_observed` because no child stop/tool completion signal was observed. `SessionEnd` has terminal priority; any child agent, tool, or permission still open at that point is shown as `interrupted`, not silently completed.
 - Official `SessionEnd` delivery may be delayed by up to 30 minutes. If no ending hook is observed while activity still appears open, five minutes without a new event changes it to `completion_not_observed` (**End not confirmed**), never inferred `completed`. This keeps a delayed or missing terminal event from turning stale activity into a false success.
-- The viewer credential is read-only and remains stable across monitor restarts and package upgrades during one installation. The runtime/control token remains separate and process-scoped.
+- The installation-owned viewer credential remains private to local runtime files for ownership/legacy boundaries. The runtime/control token remains separate and process-scoped. The normal live-view URL contains neither credential; it contains only a one-use, process-signed 60-second bootstrap grant.
 - After installation, hook trust, and an app restart, the first trusted hook automatically prepares the backend. This prepares a local process; it does not create app UI without a user action.
 - There is no external telemetry, remote server, account, required SQLite/persistent event store, or remote control.
 - Full prompt text, transcript paths, full tool input/output, and assistant messages are not retained or displayed by the monitor. Only the bounded, redacted one-line work summary described above may be retained in process memory.
@@ -109,7 +109,7 @@ Use this flow in a **new task** after completing installation and enablement in
 4. Choose **English**, **Korean**, or **Spanish** from the language selector. English is the default, and changing language does not stop the two-second refresh.
 5. If the app's Browser capability or permission is unavailable, the skill reports the failure without exposing a private localhost URL or opening an external browser.
 
-If you close the right-side live view, select `@codex-agent-view` and explicitly invoke `$show-agents` again in a Codex app task. Do not rely on a pasted `@codex-agent-view $show-agents` string being reparsed as a skill selection. An open tab refreshes and reconnects automatically after temporary disconnects, monitor restarts, and upgrades. If a request fails, the live view provides a **Retry connection** button. If authentication is rejected or missing, it also provides an in-app recovery explanation and a button to check the current tab again; because the page cannot mint or recover a private credential by itself, use the actual `$show-agents` skill in the Codex app to open a newly authenticated view when that check cannot succeed. No terminal command, private URL copy, or external browser is part of recovery. A restarted monitor presents a new in-memory observation window rather than replaying earlier activity.
+If you close the right-side live view, select `@codex-agent-view` and explicitly invoke `$show-agents` again in a Codex app task. Do not rely on a pasted `@codex-agent-view $show-agents` string being reparsed as a skill selection. During its fixed 30-minute family, the same tab keeps recovery only in `sessionStorage`, refreshes 15-minute access automatically, and offers **Reconnect** when page-level access is missing or rejected. A different or never-authenticated tab has no recovery credential. Family expiry requires the actual `$show-agents` skill again. No terminal command, private URL copy, cookie, CORS access, or external browser is part of recovery. A restarted monitor presents a new in-memory observation window; an unused bootstrap issued by the old process is immediately invalid.
 
 ## Requirements and tested versions
 
@@ -166,16 +166,16 @@ After plugin enablement/trust and an app restart, the first trusted hook interna
 
 ## Install from npm
 
-The commands below install `0.4.7` by exact version.
+The commands below install `0.4.8` by exact version after publication.
 
 ```bash
-npm install --global codex-agent-view@0.4.7
+npm install --global codex-agent-view@0.4.8
 codex-agent-view install
 ```
 
 After these two commands, fully reopen the Codex app, verify installation, enablement, and hook trust, then create a new task. The first trusted hook prepares the backend and delivers its event internally, so users do not run monitor CLI commands. Use the plugin card's **Quick start** action to select `@codex-agent-view`, then explicitly select `$show-agents` in the app. Repeat that explicit skill selection after closing the panel.
 
-The `0.4.7` installation path is the global package install followed by the explicit `codex-agent-view install` command above. Routine use remains inside the Codex app afterward. When upgrading an older valid installation, `install` preserves the installation-owned read-only viewer credential; the legacy `0.4.2` migration behavior remains as documented for `0.4.3`. Neither token nor the private URL is printed.
+The `0.4.8` installation path is the global package install followed by the explicit `codex-agent-view install` command above. Routine use remains inside the Codex app afterward. During an upgrade, explicit `install` first stops a healthy owned `0.4.7` monitor through the existing authenticated maintenance lifecycle, then replaces registration and bundle files. It preserves the installation-owned viewer credential and the historical `0.4.2` migration boundary. The normal Show Agents workflow prints neither persistent token and does not put either one in the Browser target.
 
 Version-specific npm, install, migration, CI, tag, and GitHub Release evidence is preserved in [Distribution](docs/distribution.md). That evidence is updated only after each item is actually verified.
 

package/bin/codex-agent-view.mjs

@@ -10,6 +10,7 @@ import {
   writeFile,
 } from "node:fs/promises";
 import { spawn } from "node:child_process";
+import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -17,6 +18,7 @@ import { fileURLToPath } from "node:url";
 import { startMonitorServer } from "../src/runtime/server.mjs";
 import {
   DEFAULT_PORT,
+  LOOPBACK_HOST,
   ensureViewerToken,
   readRuntimeInfo,
   readViewerToken,
@@ -32,6 +34,21 @@ const PLUGIN_ID = "codex-agent-view@codex-agent-view";
 const MARKETPLACE_NAME = "codex-agent-view";
 const BUNDLE_MARKER = ".codex-agent-view-owned.json";
 const BUNDLE_MARKER_SCHEMA_VERSION = 1;
+const PREPARE_LIVE_VIEW_WAIT_MS = 2_000;
+const PREPARE_LIVE_VIEW_POLL_MS = 40;
+const VIEWER_GRANT_TIMEOUT_MS = 1_000;
+const MAX_BOOTSTRAP_CREDENTIAL_LENGTH = 1_024;
+const SIGNED_BOOTSTRAP_CREDENTIAL_PATTERN =
+  /^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]{43}$/;
+const OWNERSHIP_PROOF_DOMAIN = "codex-agent-view/runtime-ownership/v1";
+const OWNERSHIP_PROOF_TIMEOUT_MS = 1_000;
+const KNOWN_PRE_PROOF_MANAGED_VERSIONS = new Set([
+  "0.2.0", "0.2.1",
+  "0.3.0", "0.3.1", "0.3.2",
+  "0.4.0", "0.4.1", "0.4.2", "0.4.3", "0.4.4", "0.4.5", "0.4.6", "0.4.7",
+]);
+const CANONICAL_THREAD_ID_PATTERN =
+  /^[0-9a-f]{8}-(?:[0-9a-f]{4}-){3}[0-9a-f]{12}$/i;
 const INSTALL_ENTRIES = [
   ".agents",
   ".codex-plugin",
@@ -68,6 +85,13 @@ Start prints the local URL without opening an external browser unless --open is
 `);
 }
 
+class LiveViewPreparationError extends Error {
+  constructor(code) {
+    super(code);
+    this.code = code;
+  }
+}
+
 function parseStartArgs(args) {
   let open = false;
   let legacyNoOpen = false;
@@ -195,6 +219,9 @@ async function start(args) {
 
 async function fetchState() {
   const runtime = await readRuntimeInfo();
+  if ((await runtimeEndpointState(runtime)) !== "owned") {
+    throw new Error("the runtime endpoint was not identified as an owned monitor");
+  }
   const response = await fetch(`http://${runtime.host}:${runtime.port}/api/state`, {
     headers: { authorization: `Bearer ${runtime.token}` },
     signal: AbortSignal.timeout(1_500),
@@ -483,7 +510,7 @@ async function revokeViewerCredential(preflight) {
   };
 }
 
-async function runtimeEndpointState(runtime) {
+async function legacyRuntimeEndpointState(runtime) {
   try {
     const response = await fetch(`http://${runtime.host}:${runtime.port}/api/state`, {
       headers: { authorization: `Bearer ${runtime.token}` },
@@ -502,15 +529,254 @@ async function runtimeEndpointState(runtime) {
   }
 }
 
-async function runtimeResponds(runtime) {
-  return (await runtimeEndpointState(runtime)) === "owned";
+async function runtimeEndpointState(
+  runtime,
+  { allowLegacyBearerProbe = false } = {},
+) {
+  const ownership = await runtimeOwnershipState(runtime);
+  if (ownership !== "unrelated" || !allowLegacyBearerProbe) {
+    return ownership;
+  }
+  return legacyRuntimeEndpointState(runtime);
+}
+
+async function runtimeResponds(runtime, options) {
+  return (await runtimeEndpointState(runtime, options)) === "owned";
+}
+
+function expectedOwnershipProof(nonce, runtimeToken) {
+  return createHmac("sha256", runtimeToken)
+    .update(OWNERSHIP_PROOF_DOMAIN)
+    .update("\0")
+    .update(nonce)
+    .digest("base64url");
+}
+
+async function runtimeOwnershipState(runtime) {
+  const nonce = randomBytes(32).toString("base64url");
+  let response;
+  try {
+    response = await fetch(
+      `http://${runtime.host}:${runtime.port}/api/internal/ownership-proof`,
+      {
+        body: JSON.stringify({ nonce }),
+        headers: { "content-type": "application/json" },
+        method: "POST",
+        signal: AbortSignal.timeout(OWNERSHIP_PROOF_TIMEOUT_MS),
+      },
+    );
+  } catch {
+    return "absent";
+  }
+  if (response.status !== 200) {
+    await response.body?.cancel();
+    return "unrelated";
+  }
+  const payload = await response.json().catch(() => null);
+  if (
+    payload === null ||
+    typeof payload !== "object" ||
+    Array.isArray(payload) ||
+    Object.keys(payload).sort().join(",") !== "proof,status" ||
+    payload.status !== "owned" ||
+    typeof payload.proof !== "string" ||
+    !/^[A-Za-z0-9_-]{43}$/.test(payload.proof)
+  ) {
+    return "unrelated";
+  }
+  const supplied = Buffer.from(payload.proof);
+  const expected = Buffer.from(expectedOwnershipProof(nonce, runtime.token));
+  return supplied.length === expected.length && timingSafeEqual(supplied, expected)
+    ? "owned"
+    : "unrelated";
+}
+
+async function inspectInstalledBundleForLiveView() {
+  const destination = join(runtimeDirectory(), "marketplace");
+  const stats = await pathExists(destination);
+  if (!stats) {
+    throw new LiveViewPreparationError("plugin_not_installed");
+  }
+  if (!stats.isDirectory() || stats.isSymbolicLink()) {
+    throw new LiveViewPreparationError("plugin_bundle_unowned");
+  }
+
+  const marker = await readJsonRegularFile(join(destination, BUNDLE_MARKER));
+  if (
+    marker?.schema_version !== BUNDLE_MARKER_SCHEMA_VERSION ||
+    marker?.package !== MARKETPLACE_NAME ||
+    marker?.plugin_id !== PLUGIN_ID
+  ) {
+    throw new LiveViewPreparationError("plugin_bundle_unowned");
+  }
+
+  const manifest = await readJsonRegularFile(
+    join(destination, ".codex-plugin", "plugin.json"),
+  );
+  if (manifest?.name !== MARKETPLACE_NAME || typeof manifest.version !== "string") {
+    throw new LiveViewPreparationError("plugin_bundle_invalid");
+  }
+  if (manifest.version !== (await packageVersion())) {
+    throw new LiveViewPreparationError("plugin_version_mismatch");
+  }
+}
+
+function autoStartEnvironment() {
+  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("../scripts/auto-start-monitor.mjs", import.meta.url))],
+    {
+      detached: true,
+      env: autoStartEnvironment(),
+      shell: false,
+      stdio: "ignore",
+    },
+  );
+  child.on("error", () => {});
+  child.unref();
+}
+
+async function liveViewRuntimeState() {
+  const runtime = await inspectRuntime();
+  if (runtime.kind === "unknown") {
+    throw new LiveViewPreparationError("runtime_record_invalid");
+  }
+  if (runtime.kind === "absent") {
+    return { kind: "not_running" };
+  }
+  const endpoint = await runtimeOwnershipState(runtime.info);
+  if (endpoint === "owned") {
+    return { info: runtime.info, kind: "owned" };
+  }
+  if (endpoint === "absent") {
+    return { kind: "not_running" };
+  }
+  throw new LiveViewPreparationError("unowned_runtime");
+}
+
+function inheritedExcludedSessionId() {
+  const inheritedThreadId = process.env.CODEX_THREAD_ID;
+  return (
+    typeof inheritedThreadId === "string" &&
+    CANONICAL_THREAD_ID_PATTERN.test(inheritedThreadId)
+      ? inheritedThreadId.toLowerCase()
+      : null
+  );
+}
+
+async function requestViewerGrant(runtime, excludeSessionId) {
+  let response;
+  try {
+    response = await fetch(
+      `http://${runtime.host}:${runtime.port}/api/internal/viewer-grant`,
+      {
+        body: JSON.stringify({ exclude_session_id: excludeSessionId }),
+        headers: {
+          authorization: `Bearer ${runtime.token}`,
+          "content-type": "application/json",
+        },
+        method: "POST",
+        signal: AbortSignal.timeout(VIEWER_GRANT_TIMEOUT_MS),
+      },
+    );
+  } catch (error) {
+    throw new LiveViewPreparationError(
+      error?.name === "TimeoutError" || error?.name === "AbortError"
+        ? "viewer_grant_timeout"
+        : "viewer_grant_unavailable",
+    );
+  }
+  if (response.status !== 201) {
+    await response.body?.cancel();
+    throw new LiveViewPreparationError("viewer_grant_rejected");
+  }
+  const payload = await response.json().catch(() => null);
+  const credential = payload?.bootstrap_credential;
+  if (
+    payload === null ||
+    typeof payload !== "object" ||
+    Array.isArray(payload) ||
+    Object.keys(payload).sort().join(",") !==
+      "bootstrap_credential,expires_in_ms,status" ||
+    payload.status !== "granted" ||
+    payload.expires_in_ms !== 60_000 ||
+    typeof credential !== "string" ||
+    credential.length > MAX_BOOTSTRAP_CREDENTIAL_LENGTH ||
+    !SIGNED_BOOTSTRAP_CREDENTIAL_PATTERN.test(credential) ||
+    credential === runtime.token ||
+    credential === runtime.viewer_token
+  ) {
+    throw new LiveViewPreparationError("viewer_grant_invalid_response");
+  }
+  return credential;
+}
+
+function liveViewTarget(runtime, bootstrapCredential) {
+  return `http://${LOOPBACK_HOST}:${runtime.port}/#grant=${encodeURIComponent(bootstrapCredential)}`;
+}
+
+async function prepareLiveView(args) {
+  try {
+    if (args.length > 0) {
+      throw new LiveViewPreparationError("invalid_arguments");
+    }
+    await inspectInstalledBundleForLiveView();
+    let runtime = await liveViewRuntimeState();
+    let reused = runtime.kind === "owned";
+    if (!reused) {
+      startMonitorDetached();
+      const deadline = Date.now() + PREPARE_LIVE_VIEW_WAIT_MS;
+      do {
+        await new Promise((resolvePromise) =>
+          setTimeout(resolvePromise, PREPARE_LIVE_VIEW_POLL_MS),
+        );
+        runtime = await liveViewRuntimeState();
+        if (runtime.kind === "owned") break;
+      } while (Date.now() < deadline);
+    }
+    if (runtime.kind !== "owned") {
+      throw new LiveViewPreparationError("monitor_start_timeout");
+    }
+    const bootstrapCredential = await requestViewerGrant(
+      runtime.info,
+      inheritedExcludedSessionId(),
+    );
+    process.stdout.write(
+      `${JSON.stringify({
+        ok: true,
+        reused,
+        target: liveViewTarget(runtime.info, bootstrapCredential),
+      })}\n`,
+    );
+  } catch (error) {
+    const code =
+      error instanceof LiveViewPreparationError
+        ? error.code
+        : "live_view_preparation_failed";
+    process.stdout.write(`${JSON.stringify({ ok: false, error: { code } })}\n`);
+    process.exitCode = 1;
+  }
 }
 
-async function stopRunningRuntime(preflight) {
+async function stopRunningRuntime(preflight, options = {}) {
   if (preflight.kind !== "valid") {
     return false;
   }
-  const endpointState = await runtimeEndpointState(preflight.info);
+  const endpointState = await runtimeEndpointState(preflight.info, options);
   if (endpointState === "absent") {
     return false;
   }
@@ -560,7 +826,7 @@ async function stopRunningRuntime(preflight) {
         "runtime ownership changed during uninstall; new or unrecognized runtime data was preserved",
       );
     }
-    if (!(await runtimeResponds(current.info))) {
+    if (!(await runtimeResponds(current.info, options))) {
       await removeRuntimeInfo(current.info.token);
       return true;
     }
@@ -590,7 +856,15 @@ async function inspectPluginBundle(destination) {
   ) {
     return { kind: "unmanaged" };
   }
-  return { kind: "managed" };
+  return { kind: "managed", version: manifest.version };
+}
+
+function legacyBearerProbeOptions(bundle) {
+  return {
+    allowLegacyBearerProbe:
+      bundle.kind === "managed" &&
+      KNOWN_PRE_PROOF_MANAGED_VERSIONS.has(bundle.version),
+  };
 }
 
 function unmanagedBundleError(destination) {
@@ -670,6 +944,9 @@ async function install() {
     ? runtime.info.viewer_token || runtime.info.token
     : undefined;
   await ensureViewerToken(process.env, { seedToken });
+  if (runtime.kind === "valid") {
+    await stopRunningRuntime(runtime, legacyBearerProbeOptions(bundle));
+  }
   await copyPluginBundle(destination);
   if (!existing) {
     await run("codex", ["plugin", "marketplace", "add", destination, "--json"]);
@@ -711,7 +988,7 @@ function isBroadRuntimeRoot(root) {
   );
 }
 
-async function purgeStaleRuntime(preflight) {
+async function purgeStaleRuntime(preflight, options = {}) {
   if (preflight.kind !== "valid") {
     return preflight.kind === "unknown";
   }
@@ -723,7 +1000,7 @@ async function purgeStaleRuntime(preflight) {
   if (current.kind !== "valid" || current.info.token !== preflight.info.token) {
     return true;
   }
-  const endpointState = await runtimeEndpointState(current.info);
+  const endpointState = await runtimeEndpointState(current.info, options);
   if (endpointState === "owned") {
     throw new Error("the Codex Agent View monitor started during uninstall; runtime data was preserved");
   }
@@ -790,7 +1067,11 @@ async function uninstall(args) {
 
   const runtimePreflight = await inspectRuntime();
   const viewerPreflight = await inspectViewerCredential();
-  const stoppedMonitor = await stopRunningRuntime(runtimePreflight);
+  const lifecycleProbeOptions = legacyBearerProbeOptions(bundlePreflight);
+  const stoppedMonitor = await stopRunningRuntime(
+    runtimePreflight,
+    lifecycleProbeOptions,
+  );
 
   await run("codex", ["plugin", "remove", PLUGIN_ID, "--json"], { allowFailure: true });
   await run("codex", ["plugin", "marketplace", "remove", MARKETPLACE_NAME, "--json"], {
@@ -799,7 +1080,10 @@ async function uninstall(args) {
   await removeManagedPluginBundle(bundle);
   const viewerCredential = await revokeViewerCredential(viewerPreflight);
   if (purge) {
-    const preservedRuntimeFile = await purgeStaleRuntime(runtimePreflight);
+    const preservedRuntimeFile = await purgeStaleRuntime(
+      runtimePreflight,
+      lifecycleProbeOptions,
+    );
     const removedRoot = await removeRuntimeRootIfEmpty(root);
     if (removedRoot) {
       process.stdout.write(`Removed plugin, marketplace, and runtime data from ${root}.\n`);
@@ -842,6 +1126,8 @@ async function main() {
     await status(args);
   } else if (command === "doctor") {
     await doctor(args);
+  } else if (command === "prepare-live-view") {
+    await prepareLiveView(args);
   } else if (command === "install") {
     await install(args);
   } else if (command === "uninstall") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-agent-view",
-  "version": "0.4.7",
+  "version": "0.4.8",
   "description": "Follow Codex work and participating agent progress in a clear, read-only live view inside the official Codex app.",
   "type": "module",
   "main": "./src/core/index.mjs",