codex-agent-view 0.4.5 → 0.4.6

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-agent-view",
-  "version": "0.4.5",
+  "version": "0.4.6",
   "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.5` 사용법을 설명한다. **최초 설치만** 일반 터미널에서 아래 exact-version 명령으로 진행한다.
+이 README는 `codex-agent-view@0.4.6` 사용법을 설명한다. **최초 설치만** 일반 터미널에서 아래 exact-version 명령으로 진행한다.
 
 ```bash
-npm install --global codex-agent-view@0.4.5
+npm install --global codex-agent-view@0.4.6
 codex-agent-view install
 ```
 
@@ -40,7 +40,7 @@ Live UI의 기본 언어는 영어이며 language selector에서 **English**, **
 
 ### 현재 상태
 
-`0.4.5`는 아래 구성에 작업 수준 요청 요약, 비개발자용 작업/참여 에이전트 용어, session ID를 제거한 live card와 화면 안 연결·인증 복구를 추가한다.
+`0.4.6`은 lifecycle 정확성을 바로잡는 릴리스다. `SessionEnd`에 최종 우선순위를 부여하고, 끝나지 않은 child activity를 성공으로 추정하지 않은 채 정리하며, 늦게 도착한 event가 완료된 turn을 다시 실행 중으로 열지 못하게 한다. 종료 신호 없이 오래 남은 활동은 무기한 **실행 중**으로 두지 않고 **종료 미확인**으로 표시한다. 아래의 기존 제품 구성은 그대로 유지한다.
 
 - 공식 Codex 앱의 내장 thread tools를 우선 사용하는 app-native active-task snapshot skill
 - `.codex-plugin/plugin.json`, local marketplace catalog, genuine Codex skill
@@ -88,12 +88,15 @@ Codex Agent View는 historical audit이나 session replay 제품이 아니라
 
 - 앱 안의 현재 task snapshot은 공식 Codex 앱이 제공하는 내장 thread tools의 explicit status와 `subAgentActivity`를 우선 사용한다.
 - Hook event는 local monitor의 세부 lifecycle 상태에 대한 source of truth다. Monitor state는 bounded memory에만 있고 재시작하면 새 관찰 window가 시작된다. 별도 private viewer credential은 task history가 아니라 인증 metadata다.
+- `Stop`은 관찰된 root turn과 session/work-item 요약을 즉시 `completed`로 표시한다. 진행 중이던 child agent나 tool은 자체 stop/tool completion 신호를 관찰하지 못했으므로 해당 row에서 별도로 `completion_not_observed`로 표시한다. `SessionEnd`는 terminal priority를 가지며, 그 시점에도 열려 있는 child agent·tool·permission은 완료로 추정하지 않고 `interrupted`로 표시한다.
+- 공식 `SessionEnd` 전달은 최대 30분 지연될 수 있다. 종료 hook을 관찰하지 못한 채 활동이 열린 상태로 남으면 새 event가 없는 5분 뒤 `completion_not_observed`(**종료 미확인**)로 바꾸며 `completed`로 추정하지 않는다. 지연되거나 누락된 terminal event 때문에 오래된 활동을 완료·성공으로 잘못 표시하지 않기 위한 경계다.
 - Read-only viewer credential은 한 설치 수명 동안 monitor 재시작과 upgrade를 넘어 유지되며, runtime/control token은 별도 process-scoped credential이다.
 - 설치·trust·앱 재시작 뒤 첫 trusted hook이 backend를 자동 준비한다. 이는 monitor process 준비이며 Codex 화면이나 tab을 몰래 생성하는 기능이 아니다.
 - 외부 telemetry, 원격 server, account, 필수 SQLite/영구 event store가 없다.
 - 전체 prompt 원문, transcript path, 전체 tool input/output, assistant message를 monitor 상태나 UI에 저장·표시하지 않는다. 위에서 설명한 bounded/redacted 한 줄 작업 요약만 process memory에 유지할 수 있다.
 - 기본 monitor는 진행 중인 작업과 참여 에이전트를 먼저 정렬하고 사람이 읽을 수 있는 label/status를 우선하며, raw ID와 event name은 주 정보로 표시하지 않는다. Live card에는 session ID를 표시하지 않는다.
 - task/subagent 중지·재시작, message 전송, permission 자동 승인·거절 기능이 없다.
+- Sender는 기존 bounded retry와 fail-open 동작을 유지한다. Disk queue나 persistent replay가 없으므로 hook budget 안에 전달하지 못한 event를 나중에 재생하지 않는다.
 - 별도로 실행한 App Server는 앱 내장 thread tools와 다른 process다. 공식 앱의 live source로 간주하거나 둘을 같은 API로 설명하지 않는다.
 
 별도로 실행한 Codex `0.146` App Server의 `thread/list` fallback도 실제 확인했지만 현재 root/subagent가 모두 `notLoaded`로 나타나 공식 앱의 live running/completed 상태를 공유하지 않았다. Persisted parent ID, alias, depth 보강은 가능했지만 live 판별에는 채택하지 않았다. `0.3.0`의 primary snapshot은 이 별도 server가 아니라 현재 공식 앱이 직접 제공하는 내장 thread tools를 사용한다.
@@ -211,16 +214,16 @@ Plugin enable/trust와 앱 재시작 뒤 생성되거나 재개되는 task는 tr
 
 ### npm 설치 명령 참고
 
-아래 명령은 `0.4.5`를 exact version으로 설치한다.
+아래 명령은 `0.4.6`을 exact version으로 설치한다.
 
 ```bash
-npm install --global codex-agent-view@0.4.5
+npm install --global codex-agent-view@0.4.6
 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.5` 설치 경로는 위의 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.6` 설치 경로는 위의 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은 출력하지 않는다.
 
 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.5`. Use the exact-version command below for the one-time terminal installation.
+This README documents `codex-agent-view@0.4.6`. Use the exact-version command below for the one-time terminal installation.
 
 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.5
+npm install --global codex-agent-view@0.4.6
 codex-agent-view install
 ```
 
@@ -40,7 +40,7 @@ In short: install once in a terminal; perform snapshot queries, status checks, l
 
 ## Status
 
-Version `0.4.5` adds the work-level request summary, user-facing work/agent terminology, session-ID-free live cards, and in-panel connection/authentication recovery described above. 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.6` is the lifecycle-correctness release. It gives `SessionEnd` terminal priority, settles unfinished child activity without pretending it succeeded, prevents late events from reopening a finished turn, and reports prolonged unconfirmed activity as **End not confirmed** instead of leaving it indefinitely **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.
 
 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.
 
@@ -78,6 +78,8 @@ Codex Agent View is a live companion, not a historical audit or session-replay p
 
 - The app-native current-task snapshot prioritizes explicit status and `subAgentActivity` from the official Codex app's built-in thread tools.
 - 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.
 - 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.
@@ -85,6 +87,7 @@ Codex Agent View is a live companion, not a historical audit or session-replay p
 - The default monitor sorts active work and participating agents first, uses human-readable labels and statuses as the primary presentation, and keeps raw IDs and event names out of the primary reading path. Session IDs are not shown in the live cards.
 - The product cannot stop or restart tasks/subagents, send messages, or approve/deny permissions.
 - Missing, duplicated, or out-of-order events remain visible as empty, unknown, or degraded state instead of being guessed away.
+- The sender keeps its bounded retry and fail-open behavior. It has no disk-backed queue or persistent replay; an event that cannot be delivered within the hook budget is not replayed later.
 
 A separately launched Codex `0.146` App Server `thread/list` fallback was also tested. It reported both the current root and subagents as `notLoaded`, so it did not share the official app's live running/completed state. That separate process is not the same as the built-in thread tools exposed directly by the current official app; `0.3.0` uses the latter for its primary snapshot.
 
@@ -163,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.5` by exact version.
+The commands below install `0.4.6` by exact version.
 
 ```bash
-npm install --global codex-agent-view@0.4.5
+npm install --global codex-agent-view@0.4.6
 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.5` 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.6` 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.
 
 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-agent-view",
-  "version": "0.4.5",
+  "version": "0.4.6",
   "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",

package/public/app.js

@@ -4,7 +4,15 @@ const SESSION_TOKEN_KEY = "codex-agent-view-access-token";
 const EXCLUDED_SESSION_KEY = "codex-agent-view-excluded-session";
 const LANGUAGE_KEY = "codex-agent-view-language";
 const SUPPORTED_LANGUAGES = new Set(["en", "ko", "es"]);
-const KNOWN_STATUSES = new Set(["running", "waiting", "completed", "unknown"]);
+const KNOWN_STATUSES = new Set([
+  "running",
+  "waiting",
+  "completed",
+  "completion_not_observed",
+  "stale",
+  "interrupted",
+  "unknown",
+]);
 const VIEWER_TOKEN_PATTERN = /^[A-Za-z0-9_-]{43}$/;
 const CANONICAL_SESSION_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
 
@@ -47,7 +55,13 @@ const MESSAGES = Object.freeze({
     statusRunning: "Running",
     statusWaiting: "Waiting",
     statusCompleted: "Completed",
+    statusCompletionNotObserved: "End not confirmed",
+    statusStale: "Stale · end not confirmed",
+    statusInterrupted: "Interrupted",
     statusUnknown: "Unknown",
+    completionNotObservedExplanation: "No end signal was received for this item, so completion cannot be confirmed.",
+    staleExplanation: "This status is out of date and no end signal was received. Completion cannot be confirmed.",
+    interruptedExplanation: "This activity was still open when the work ended; its own completion signal was not observed.",
     connectingCopy: "Connecting to the Codex app's local status.",
     sessionListAria: "Codex work list",
     privacyPrompt: "This view shows only a shortened request summary; it never displays the full request or tool inputs.",
@@ -180,7 +194,13 @@ const MESSAGES = Object.freeze({
     statusRunning: "실행 중",
     statusWaiting: "대기",
     statusCompleted: "완료",
+    statusCompletionNotObserved: "종료 확인 안 됨",
+    statusStale: "오래된 상태 · 종료 확인 안 됨",
+    statusInterrupted: "중단됨",
     statusUnknown: "알 수 없음",
+    completionNotObservedExplanation: "이 항목의 종료 신호를 받지 못해 완료 여부를 확정할 수 없습니다.",
+    staleExplanation: "상태 정보가 오래되었고 종료 신호를 받지 못했습니다. 완료 여부를 확정할 수 없습니다.",
+    interruptedExplanation: "전체 작업이 끝날 때 이 활동이 열린 상태였습니다. 이 활동 자체의 완료 신호는 확인되지 않았습니다.",
     connectingCopy: "Codex 앱의 로컬 상태에 연결하고 있습니다.",
     sessionListAria: "Codex 작업 목록",
     privacyPrompt: "이 화면은 짧게 줄인 요청 요약만 표시하며, 전체 요청이나 도구 입력은 표시하지 않습니다.",
@@ -313,7 +333,13 @@ const MESSAGES = Object.freeze({
     statusRunning: "En ejecución",
     statusWaiting: "En espera",
     statusCompleted: "Completado",
+    statusCompletionNotObserved: "Fin no confirmado",
+    statusStale: "Estado desactualizado · fin no confirmado",
+    statusInterrupted: "Interrumpido",
     statusUnknown: "Desconocido",
+    completionNotObservedExplanation: "No se recibió una señal de fin para este elemento, por lo que no se puede confirmar que haya terminado.",
+    staleExplanation: "El estado está desactualizado y no se recibió una señal de fin. No se puede confirmar que haya terminado.",
+    interruptedExplanation: "Esta actividad seguía abierta cuando terminó el trabajo; no se observó su propia señal de finalización.",
     connectingCopy: "Conectando al estado local de la aplicación Codex.",
     sessionListAria: "Lista de trabajos de Codex",
     privacyPrompt: "Esta vista solo muestra un resumen abreviado de la solicitud; nunca muestra la solicitud completa ni las entradas de herramientas.",
@@ -414,14 +440,26 @@ const STATUS_KEYS = Object.freeze({
   running: "statusRunning",
   waiting: "statusWaiting",
   completed: "statusCompleted",
+  completion_not_observed: "statusCompletionNotObserved",
+  stale: "statusStale",
+  interrupted: "statusInterrupted",
   unknown: "statusUnknown",
 });
 
 const STATUS_ORDER = Object.freeze({
   running: 0,
   waiting: 1,
-  unknown: 2,
-  completed: 3,
+  completion_not_observed: 2,
+  stale: 2,
+  interrupted: 3,
+  unknown: 4,
+  completed: 5,
+});
+
+const STATUS_EXPLANATION_KEYS = Object.freeze({
+  completion_not_observed: "completionNotObservedExplanation",
+  stale: "staleExplanation",
+  interrupted: "interruptedExplanation",
 });
 
 const ACTIVITY_KEYS = Object.freeze({
@@ -693,6 +731,9 @@ function normalizeCoreStatus(value) {
   ) {
     return "completed";
   }
+  if (value === "completion_not_observed" || value === "stale" || value === "interrupted") {
+    return value;
+  }
   return normalizeStatus(value);
 }
 
@@ -783,13 +824,13 @@ function normalizeDiagnostic(value) {
 }
 
 function deriveSessionStatus(session, agents, recentActivities) {
-  if (session.permission?.status === "waiting_for_user") {
-    return "waiting";
-  }
   const reportedStatus = normalizeCoreStatus(session.status);
-  if (reportedStatus === "running" || reportedStatus === "completed") {
+  if (reportedStatus !== "unknown") {
     return reportedStatus;
   }
+  if (session.permission?.status === "waiting_for_user") {
+    return "waiting";
+  }
   if (
     agents.some((agent) => agent.status === "running") ||
     recentActivities[0]?.status === "running"
@@ -924,12 +965,24 @@ function createStatusBadge(status) {
   dot.setAttribute("aria-hidden", "true");
 
   const label = document.createElement("span");
-  label.textContent = t(STATUS_KEYS[status]);
+  label.textContent = t(STATUS_KEYS[status] ?? "statusUnknown");
 
   badge.append(dot, label);
   return badge;
 }
 
+function createStatusExplanation(status) {
+  const messageKey = STATUS_EXPLANATION_KEYS[status];
+  if (!messageKey) {
+    return null;
+  }
+
+  const explanation = document.createElement("p");
+  explanation.className = "status-explanation";
+  explanation.textContent = t(messageKey);
+  return explanation;
+}
+
 function createTime(timestampMs, prefix) {
   const wrapper = document.createElement("span");
   wrapper.className = "time-label";
@@ -1006,10 +1059,16 @@ function createAgentItem(agent) {
     document.createTextNode(` · ${formatDuration(agent.startedAtMs, agent.stoppedAtMs)}`),
   );
 
+  const statusExplanation = createStatusExplanation(agent.status);
+
   const technicalRows = [[t("agentId"), agent.agentId]];
   technicalRows.push([t("rawProfile"), agent.agentType]);
 
-  item.append(heading, metadata, createTechnicalInfo(technicalRows));
+  item.append(heading, metadata);
+  if (statusExplanation) {
+    item.append(statusExplanation);
+  }
+  item.append(createTechnicalInfo(technicalRows));
   return item;
 }
 
@@ -1081,6 +1140,10 @@ function createSessionCard(session) {
     createStatusBadge(session.status),
     createTime(session.lastActivityAtMs, t("recentActivity")),
   );
+  const statusExplanation = createStatusExplanation(session.status);
+  if (statusExplanation) {
+    sessionState.append(statusExplanation);
+  }
 
   cardHeader.append(identity, sessionState);
 
@@ -1156,10 +1219,15 @@ function sessionMatchesQuery(session, query) {
 }
 
 function sessionMatchesStatus(session, status) {
+  const matchesStatus = (candidate) => (
+    candidate === status ||
+    (status === "completion_not_observed" && candidate === "stale")
+  );
   return (
     status === "all" ||
-    session.status === status ||
-    session.agents.some((agent) => agent.status === status)
+    matchesStatus(session.status) ||
+    session.agents.some((agent) => matchesStatus(agent.status)) ||
+    session.recentActivities.some((activity) => matchesStatus(activity.status))
   );
 }
 

package/public/index.html

@@ -129,6 +129,8 @@
                 <option value="running" data-i18n="statusRunning">Running</option>
                 <option value="waiting" data-i18n="statusWaiting">Waiting</option>
                 <option value="completed" data-i18n="statusCompleted">Completed</option>
+                <option value="completion_not_observed" data-i18n="statusCompletionNotObserved">End not confirmed</option>
+                <option value="interrupted" data-i18n="statusInterrupted">Interrupted</option>
                 <option value="unknown" data-i18n="statusUnknown">Unknown</option>
               </select>
             </div>

package/public/styles.css

@@ -25,6 +25,10 @@
   --waiting-soft: #fff0ce;
   --completed: #45605f;
   --completed-soft: #e5eceb;
+  --unconfirmed: #8a4f18;
+  --unconfirmed-soft: #f9e8d6;
+  --interrupted: #765226;
+  --interrupted-soft: #f2e8d9;
   --unknown: #6b6678;
   --unknown-soft: #ece9f2;
   --danger: #a13838;
@@ -597,6 +601,16 @@ h1 {
   background: linear-gradient(110deg, var(--running-soft), var(--surface-raised) 72%);
 }
 
+.session-card[data-status="completion_not_observed"],
+.session-card[data-status="stale"] {
+  border-color: color-mix(in srgb, var(--unconfirmed) 52%, var(--border-default));
+}
+
+.session-card[data-status="completion_not_observed"] .session-header,
+.session-card[data-status="stale"] .session-header {
+  background: linear-gradient(110deg, var(--unconfirmed-soft), var(--surface-raised) 72%);
+}
+
 .session-header {
   display: flex;
   align-items: center;
@@ -666,6 +680,17 @@ h1 {
   background: var(--completed-soft);
 }
 
+.status-badge[data-status="completion_not_observed"],
+.status-badge[data-status="stale"] {
+  color: var(--unconfirmed);
+  background: var(--unconfirmed-soft);
+}
+
+.status-badge[data-status="interrupted"] {
+  color: var(--interrupted);
+  background: var(--interrupted-soft);
+}
+
 .status-badge[data-status="running"] .status-dot,
 .activity-marker[data-status="running"] {
   background: var(--running);
@@ -681,6 +706,31 @@ h1 {
   background: var(--completed);
 }
 
+.status-badge[data-status="completion_not_observed"] .status-dot,
+.status-badge[data-status="stale"] .status-dot,
+.activity-marker[data-status="completion_not_observed"],
+.activity-marker[data-status="stale"] {
+  background: var(--unconfirmed);
+}
+
+.status-badge[data-status="interrupted"] .status-dot,
+.activity-marker[data-status="interrupted"] {
+  background: var(--interrupted);
+}
+
+.status-explanation {
+  max-width: 34rem;
+  margin: 0;
+  color: var(--text-secondary);
+  font-size: var(--text-xs);
+  line-height: 1.4;
+}
+
+.session-state .status-explanation {
+  max-width: 24rem;
+  text-align: right;
+}
+
 .time-label,
 .agent-metadata,
 .activity-metadata {
@@ -726,6 +776,13 @@ h1 {
   border-color: color-mix(in srgb, var(--running) 42%, var(--border-default));
 }
 
+.agent-item[data-status="completion_not_observed"],
+.agent-item[data-status="stale"],
+.agent-item[data-status="interrupted"] {
+  background: color-mix(in srgb, var(--unconfirmed-soft) 58%, var(--surface-raised));
+  border-color: color-mix(in srgb, var(--unconfirmed) 38%, var(--border-default));
+}
+
 .agent-heading {
   display: flex;
   align-items: center;
@@ -933,6 +990,10 @@ footer p {
     align-items: flex-start;
   }
 
+  .session-state .status-explanation {
+    text-align: left;
+  }
+
   .session-header {
     gap: var(--space-3);
     padding: var(--space-4);
@@ -980,6 +1041,10 @@ footer p {
     --waiting-soft: #493819;
     --completed: #a9bfbb;
     --completed-soft: #34433f;
+    --unconfirmed: #f2b879;
+    --unconfirmed-soft: #493421;
+    --interrupted: #dcc09a;
+    --interrupted-soft: #423729;
     --unknown: #bbb3ca;
     --unknown-soft: #3c3746;
     --danger: #f19a9a;

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

@@ -118,6 +118,19 @@ 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.
 
+When a CLI or live-monitor snapshot returns lifecycle statuses, preserve their
+meaning exactly:
+
+- A session/work-item `completed` status is grounded in an observed `Stop` or
+  terminal `SessionEnd`; report it as observed completion, not inferred
+  success.
+- `completion_not_observed` means active state had no new event for the default
+  five-minute window and no ending hook was observed. Render it as **End not
+  confirmed**. Never reinterpret it as either `running` or `completed`.
+- `interrupted` means the parent/session became terminal while a child agent or
+  tool had no own stop/completion signal. Never rewrite it as `running` or
+  `completed`, and do not invent a success or failure result.
+
 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

package/src/core/monitor-store.mjs

@@ -5,6 +5,7 @@ const DEFAULT_LIMITS = Object.freeze({
   maxAgentsPerSession: 100,
   maxDiagnostics: 100,
   maxSessions: 50,
+  staleAfterMs: 5 * 60 * 1000,
 });
 
 function positiveInteger(value, name) {
@@ -74,7 +75,30 @@ function applyWorkspaceLabel(session, event) {
   session.workspace_label_observed_at_ms = event.received_at_ms;
 }
 
-function deriveSessionStatus(session) {
+function hasActiveState(session) {
+  return (
+    session.permission.status === "waiting_for_user" ||
+    session.root_turn.status === "running" ||
+    [...session.agents.values()].some(({ status }) => status === "running") ||
+    [...session.tools.values()].some(({ status }) => status === "running")
+  );
+}
+
+function isStaleActiveSession(session, nowMs, staleAfterMs) {
+  return (
+    !session.lifecycle.end_observed &&
+    hasActiveState(session) &&
+    nowMs - session.last_seen_at_ms >= staleAfterMs
+  );
+}
+
+function deriveSessionStatus(session, nowMs, staleAfterMs) {
+  if (session.lifecycle.end_observed) {
+    return "completed";
+  }
+  if (isStaleActiveSession(session, nowMs, staleAfterMs)) {
+    return "completion_not_observed";
+  }
   if (session.permission.status === "waiting_for_user") {
     return "waiting_for_user";
   }
@@ -85,12 +109,92 @@ function deriveSessionStatus(session) {
   ) {
     return "running";
   }
-  if (session.lifecycle.end_observed) {
+  if (session.root_turn.status === "completed") {
     return "completed";
   }
   return "observed";
 }
 
+function settleRunningState(session, status, options = {}) {
+  const turnId = options.turnId;
+  const settledAgentIds = new Set();
+  const settledToolUseIds = new Set();
+  for (const agent of session.agents.values()) {
+    if (
+      agent.status === "running" &&
+      (turnId === undefined || agent.turn_id === turnId)
+    ) {
+      agent.status = status;
+      settledAgentIds.add(agent.agent_id);
+    }
+  }
+  for (const tool of session.tools.values()) {
+    if (
+      tool.status === "running" &&
+      (turnId === undefined || tool.turn_id === turnId)
+    ) {
+      tool.status = status;
+      settledToolUseIds.add(tool.tool_use_id);
+    }
+  }
+  for (const activity of session.recent_activities) {
+    if (
+      activity.status === "running" &&
+      ((activity.type === "subagent_started" &&
+        settledAgentIds.has(activity.agent_id)) ||
+        (activity.type === "tool_started" &&
+          settledToolUseIds.has(activity.tool_use_id)))
+    ) {
+      activity.status = status;
+    }
+  }
+}
+
+function clearPermission(session, activityStatus) {
+  const permission = session.permission;
+  if (permission.status !== "waiting_for_user") {
+    return;
+  }
+  for (const activity of session.recent_activities) {
+    if (
+      activity.type === "permission_requested" &&
+      activity.status === "waiting_for_user" &&
+      activity.turn_id === permission.turn_id &&
+      activity.tool_name === permission.tool_name
+    ) {
+      activity.status = activityStatus;
+      break;
+    }
+  }
+  session.permission = { status: "idle" };
+}
+
+function settleRootTurnActivity(session, status) {
+  for (const activity of session.recent_activities) {
+    if (
+      activity.type === "turn_started" &&
+      activity.status === "running" &&
+      activity.turn_id === session.root_turn.turn_id
+    ) {
+      activity.status = status;
+      break;
+    }
+  }
+}
+
+function resetTransientState(session) {
+  session.agents.clear();
+  session.tools.clear();
+  session.root_turn = {
+    status: "idle",
+    turn_id: null,
+    started_at_ms: null,
+    stopped_at_ms: null,
+    has_out_of_order_events: false,
+  };
+  session.permission = { status: "idle" };
+}
+
 function touchMapEntry(map, key, value) {
   map.delete(key);
   map.set(key, value);
@@ -109,7 +213,14 @@ function addActivity(session, event, status, limit) {
     received_at_ms: event.received_at_ms,
   };
 
-  for (const field of ["turn_id", "agent_id", "agent_type", "tool_name", "tool_use_id"]) {
+  for (const field of [
+    "turn_id",
+    "agent_id",
+    "agent_type",
+    "tool_name",
+    "tool_use_id",
+    "session_start_source",
+  ]) {
     if (field in event) {
       activity[field] = event[field];
     }
@@ -125,11 +236,35 @@ function applySessionEvent(session, event, limits) {
   const lifecycle = session.lifecycle;
   if (event.type === "session_started") {
     const resumedAfterEnd = lifecycle.end_observed;
+    const startsNewEpoch =
+      resumedAfterEnd ||
+      event.session_start_source === "resume" ||
+      event.session_start_source === "clear";
+    if (event.session_start_source === "compact") {
+      if (resumedAfterEnd) {
+        return "stale";
+      }
+      lifecycle.start_observed = true;
+      lifecycle.started_at_ms ??= event.received_at_ms;
+      addActivity(session, event, "observed", limits.maxActivitiesPerSession);
+      return "applied";
+    }
+    if (lifecycle.start_observed && !startsNewEpoch) {
+      return "duplicate";
+    }
+    if (startsNewEpoch) {
+      if (!resumedAfterEnd) {
+        settleRootTurnActivity(session, "completion_not_observed");
+        clearPermission(session, "completion_not_observed");
+        settleRunningState(session, "completion_not_observed");
+      }
+      resetTransientState(session);
+    }
     lifecycle.start_observed = true;
-    lifecycle.started_at_ms ??= event.received_at_ms;
+    lifecycle.started_at_ms = event.received_at_ms;
     lifecycle.end_observed = false;
     lifecycle.ended_at_ms = null;
-    lifecycle.has_out_of_order_events ||= resumedAfterEnd;
+    lifecycle.has_out_of_order_events = false;
     addActivity(session, event, "observed", limits.maxActivitiesPerSession);
     return "applied";
   }
@@ -140,9 +275,11 @@ function applySessionEvent(session, event, limits) {
   lifecycle.end_observed = true;
   lifecycle.ended_at_ms = event.received_at_ms;
   lifecycle.has_out_of_order_events = !lifecycle.start_observed;
+  settleRootTurnActivity(session, "completed");
   session.root_turn.status = "completed";
   session.root_turn.stopped_at_ms ??= event.received_at_ms;
-  session.permission = { status: "idle" };
+  clearPermission(session, "interrupted");
+  settleRunningState(session, "interrupted");
   addActivity(session, event, "completed", limits.maxActivitiesPerSession);
   return "applied";
 }
@@ -150,9 +287,10 @@ function applySessionEvent(session, event, limits) {
 function applyTurnEvent(session, event, limits) {
   const turn = session.root_turn;
   if (event.type === "turn_started") {
-    if (turn.turn_id === event.turn_id && turn.status === "running") {
-      return "duplicate";
+    if (turn.turn_id === event.turn_id) {
+      return turn.status === "running" ? "duplicate" : "stale";
     }
+    settleRunningState(session, "completion_not_observed");
     session.root_turn = {
       status: "running",
       turn_id: event.turn_id,
@@ -160,7 +298,12 @@ function applyTurnEvent(session, event, limits) {
       stopped_at_ms: null,
       has_out_of_order_events: false,
     };
-    session.permission = { status: "idle" };
+    if (
+      session.permission.status !== "waiting_for_user" ||
+      session.permission.turn_id !== event.turn_id
+    ) {
+      clearPermission(session, "completion_not_observed");
+    }
     addActivity(session, event, "running", limits.maxActivitiesPerSession);
     return "applied";
   }
@@ -169,6 +312,9 @@ function applyTurnEvent(session, event, limits) {
     return "duplicate";
   }
   const startObserved = turn.turn_id === event.turn_id && turn.started_at_ms !== null;
+  if (startObserved) {
+    settleRootTurnActivity(session, "completed");
+  }
   session.root_turn = {
     status: "completed",
     turn_id: event.turn_id,
@@ -176,7 +322,15 @@ function applyTurnEvent(session, event, limits) {
     stopped_at_ms: event.received_at_ms,
     has_out_of_order_events: !startObserved,
   };
-  session.permission = { status: "idle" };
+  if (
+    session.permission.status === "waiting_for_user" &&
+    session.permission.turn_id === event.turn_id
+  ) {
+    clearPermission(session, "completion_not_observed");
+  }
+  settleRunningState(session, "completion_not_observed", {
+    turnId: event.turn_id,
+  });
   addActivity(
     session,
     event,
@@ -192,6 +346,7 @@ function applySubagentEvent(session, event, limits) {
     agent = {
       agent_id: event.agent_id,
       agent_type: event.agent_type,
+      turn_id: event.turn_id,
       status: "unknown",
       started_at_ms: null,
       stopped_at_ms: null,
@@ -225,6 +380,7 @@ function applySubagentEvent(session, event, limits) {
   }
 
   agent.agent_type = event.agent_type;
+  agent.turn_id = event.turn_id;
   agent.last_seen_at_ms = Math.max(agent.last_seen_at_ms, event.received_at_ms);
   touchMapEntry(session.agents, event.agent_id, agent);
   trimMap(session.agents, limits.maxAgentsPerSession);
@@ -282,7 +438,7 @@ function applyToolEvent(session, event, limits) {
       permission.turn_id === event.turn_id &&
       event.received_at_ms >= permission.requested_at_ms
     ) {
-      session.permission = { status: "idle" };
+      clearPermission(session, "completed");
     }
   }
 
@@ -328,9 +484,29 @@ function applyPermissionEvent(session, event, limits) {
 }
 
 function applyEvent(session, event, limits) {
-  if (event.type === "session_started" || event.type === "session_ended") {
+  if (event.type === "session_started") {
+    return applySessionEvent(session, event, limits);
+  }
+  if (
+    session.lifecycle.end_observed &&
+    event.type !== "tool_completed" &&
+    event.type !== "subagent_stopped"
+  ) {
+    return event.type === "session_ended" ? "duplicate" : "stale";
+  }
+  if (event.type === "session_ended") {
     return applySessionEvent(session, event, limits);
   }
+  if (
+    session.root_turn.status === "completed" &&
+    session.root_turn.turn_id === event.turn_id &&
+    (event.type === "turn_started" ||
+      event.type === "permission_requested" ||
+      event.type === "tool_started" ||
+      event.type === "subagent_started")
+  ) {
+    return "stale";
+  }
   if (event.type === "turn_started" || event.type === "turn_stopped") {
     return applyTurnEvent(session, event, limits);
   }
@@ -343,22 +519,51 @@ function applyEvent(session, event, limits) {
   return applyPermissionEvent(session, event, limits);
 }
 
-function snapshotSession(session) {
+function snapshotSession(session, nowMs, staleAfterMs) {
+  const staleActive = isStaleActiveSession(session, nowMs, staleAfterMs);
   return {
     session_id: session.session_id,
     workspace_label: session.workspace_label,
     task_summary: session.task_summary,
-    status: deriveSessionStatus(session),
+    status: deriveSessionStatus(session, nowMs, staleAfterMs),
     first_seen_at_ms: session.first_seen_at_ms,
     last_seen_at_ms: session.last_seen_at_ms,
     agents: [...session.agents.values()]
-      .map(({ start_observed, stop_observed, ...agent }) => ({ ...agent }))
+      .map(({ start_observed, stop_observed, ...agent }) => ({
+        ...agent,
+        ...(staleActive && agent.status === "running"
+          ? { status: "completion_not_observed" }
+          : {}),
+      }))
       .sort((left, right) => right.last_seen_at_ms - left.last_seen_at_ms),
-    root_turn: { ...session.root_turn },
+    tools: [...session.tools.values()]
+      .map(({ start_observed, completion_observed, ...tool }) => ({
+        ...tool,
+        ...(staleActive && tool.status === "running"
+          ? { status: "completion_not_observed" }
+          : {}),
+      }))
+      .sort((left, right) => right.last_seen_at_ms - left.last_seen_at_ms),
+    root_turn: {
+      ...session.root_turn,
+      ...(staleActive && session.root_turn.status === "running"
+        ? { status: "completion_not_observed" }
+        : {}),
+    },
     recent_activities: session.recent_activities.map((activity) => ({
       ...activity,
+      ...(staleActive &&
+      (activity.status === "running" ||
+        activity.status === "waiting_for_user")
+        ? { status: "completion_not_observed" }
+        : {}),
     })),
-    permission: { ...session.permission },
+    permission: {
+      ...session.permission,
+      ...(staleActive && session.permission.status === "waiting_for_user"
+        ? { status: "completion_not_observed" }
+        : {}),
+    },
   };
 }
 
@@ -381,6 +586,10 @@ export function createMonitorStore(options = {}) {
       options.maxSessions ?? DEFAULT_LIMITS.maxSessions,
       "maxSessions",
     ),
+    staleAfterMs: positiveInteger(
+      options.staleAfterMs ?? DEFAULT_LIMITS.staleAfterMs,
+      "staleAfterMs",
+    ),
   };
   const now = options.now ?? Date.now;
   if (typeof now !== "function") {
@@ -445,12 +654,15 @@ export function createMonitorStore(options = {}) {
   }
 
   function getSnapshot() {
+    const snapshotAtMs = now();
     return {
       schema_version: 1,
       source_of_truth: "hook",
       updated_at_ms: updatedAtMs,
       sessions: [...sessions.values()]
-        .map(snapshotSession)
+        .map((session) =>
+          snapshotSession(session, snapshotAtMs, limits.staleAfterMs),
+        )
         .sort((left, right) => right.last_seen_at_ms - left.last_seen_at_ms),
       diagnostics: diagnostics.map((diagnostic) => ({ ...diagnostic })),
     };

package/src/core/normalize-hook-payload.mjs

@@ -11,6 +11,12 @@ const NORMALIZED_EVENT_TYPES = Object.freeze({
 });
 
 const SESSION_EVENT_TYPES = new Set(["session_started", "session_ended"]);
+const SESSION_START_SOURCES = new Set([
+  "startup",
+  "resume",
+  "clear",
+  "compact",
+]);
 
 const MAX_IDENTIFIER_LENGTH = 512;
 const MAX_LABEL_LENGTH = 256;
@@ -189,6 +195,13 @@ export function normalizeHookPayload(payload, options = {}) {
   }
 
   const event = commonEvent(payload, type, receivedAtMs);
+  if (
+    type === "session_started" &&
+    typeof payload.source === "string" &&
+    SESSION_START_SOURCES.has(payload.source)
+  ) {
+    event.session_start_source = payload.source;
+  }
   const workspaceLabel = optionalWorkspaceLabel(payload);
   if (workspaceLabel) {
     event.workspace_label = workspaceLabel;