@hayasaka7/haya-pet 0.2.5 → 0.2.7

package/apps/companion/test/bubble-list-viewport.test.mjs

@@ -0,0 +1,50 @@
+import assert from "node:assert/strict";
+import { test } from "../../../test/harness.mjs";
+import { resolveBubbleListMaxHeight } from "../src/main/bubble-list-viewport.js";
+
+// Layout bottoms for bubbles ~48px tall with a 6px gap.
+const FOUR_BUBBLES = [48, 102, 156, 210];
+
+test("three or fewer bubbles use the height budget alone", () => {
+  assert.equal(resolveBubbleListMaxHeight({ room: 400, bubbleBottoms: [48, 102, 156] }), 400);
+  assert.equal(resolveBubbleListMaxHeight({ room: 400, bubbleBottoms: [48] }), 400);
+  assert.equal(resolveBubbleListMaxHeight({ room: 400, bubbleBottoms: [] }), 400);
+});
+
+test("more than three bubbles cap the viewport at the third bubble's bottom", () => {
+  assert.equal(resolveBubbleListMaxHeight({ room: 400, bubbleBottoms: FOUR_BUBBLES }), 156);
+});
+
+test("the height budget still wins when it is tighter than the count cap", () => {
+  assert.equal(resolveBubbleListMaxHeight({ room: 120, bubbleBottoms: FOUR_BUBBLES }), 120);
+});
+
+test("the minimum height floor applies to both budgets", () => {
+  assert.equal(resolveBubbleListMaxHeight({ room: 40, bubbleBottoms: FOUR_BUBBLES }), 96);
+  assert.equal(resolveBubbleListMaxHeight({ room: 40, bubbleBottoms: [48] }), 96);
+});
+
+test("the room is rounded to whole pixels", () => {
+  assert.equal(resolveBubbleListMaxHeight({ room: 150.6, bubbleBottoms: [48] }), 151);
+});
+
+test("maxVisible and minHeight are configurable", () => {
+  assert.equal(
+    resolveBubbleListMaxHeight({ room: 400, bubbleBottoms: FOUR_BUBBLES, maxVisible: 2 }),
+    102
+  );
+  assert.equal(
+    resolveBubbleListMaxHeight({ room: 40, bubbleBottoms: [48], minHeight: 32 }),
+    40
+  );
+});
+
+test("garbage measurements fall back safely", () => {
+  // Unusable room → the floor keeps the list usable.
+  assert.equal(resolveBubbleListMaxHeight({ room: Number.NaN, bubbleBottoms: [48] }), 96);
+  // Unusable bottom at the cap index → no count cap, height budget alone.
+  assert.equal(
+    resolveBubbleListMaxHeight({ room: 400, bubbleBottoms: [48, 102, Number.NaN, 210] }),
+    400
+  );
+});

package/apps/companion/test/tray-menu.test.mjs

@@ -47,6 +47,16 @@ test("reflects the attach-bubbles checkbox state", () => {
   assert.equal(buildTrayMenu({ ...baseState, attachBubblesToTerminals: false }).find((i) => i.id === "attach_bubbles").checked, false);
 });
 
+test("shows the update item only when a newer version is known", () => {
+  const withoutUpdate = buildTrayMenu(baseState);
+  assert.ok(!withoutUpdate.some((i) => i.id === "update"), "no update item by default");
+
+  const withUpdate = buildTrayMenu({ ...baseState, updateAvailable: { latestVersion: "9.9.9" } });
+  const item = withUpdate.find((i) => i.id === "update");
+  assert.ok(item, "update item appears when an update is known");
+  assert.ok(item.label.includes("9.9.9"), "label names the new version");
+});
+
 test("uses the HAYA Pet brand in the tray hover text", () => {
   assert.equal(buildTrayTooltip(), "HAYA Pet");
 });

package/docs/architecture.md

@@ -70,8 +70,14 @@ profile, so if the user already passes `-p/--profile`, injection is skipped with
 notice. Codex's hook command must be unquoted at the program position (it runs via
 `cmd /c`, which strips a leading quote) and its matchers can't use look-around
 (Rust regex) — see [known-issues.md](known-issues.md). Codex's L4 is **partial**:
-`PreToolUse`/`PermissionRequest` don't fire upstream yet, so only `thinking`/`idle`
-arrive today.
+`PreToolUse` doesn't fire upstream yet, so tool activity comes from an L3
+transcript watcher tailing the session rollout. `PermissionRequest` fires, but
+once at approval-request creation — before Codex routes the request to either
+the user or its guardian auto-reviewer ("Approve for me"), which never prompts
+the user at all. An L3 **guardian-trunk watcher** tails the guardian's own
+rollout (`source: {subagent:{other:"guardian"}}`, parented to the main thread)
+and refines the state: review running → `reviewing`, verdict allow →
+`running_tool`, verdict deny → `thinking`.
 
 Hooks alone can't see one moment: clients emit **no event when the user accepts a
 permission prompt** (denial and completion are observable; the accept click is

package/docs/known-issues.md

@@ -2,6 +2,85 @@
 
 Issues found in live use, with their current status.
 
+## ✅ Resolved: false "waiting for approval" while Codex auto-reviews an approval (Approve for me)
+
+- **Symptom:** Running Codex under the pet with the **"Approve for me"** preset
+  (`approvals_reviewer = auto_review`; the user's config had the legacy alias
+  `guardian_subagent`), the pet showed *waiting for approval* whenever an action
+  needed approval — even though Codex's guardian was reviewing it automatically
+  and the user was never asked anything. The false state lasted the whole review
+  (~8–30 s per request, up to Codex's 90 s review timeout) plus the approved
+  command's runtime.
+- **Root cause (verified against codex-rs 0.139.0 source + a live trunk
+  rollout):** Codex fires the `PermissionRequest` hook once, at approval-request
+  creation, **before** routing — and for guardian-routed requests the human
+  approval UI is *never* shown: a guardian `allow` lets the action proceed; a
+  guardian `deny` returns the rationale to the **model** as a rejected tool call
+  ("This action was rejected due to unacceptable risk. …"), so no human decision
+  is ever pending. Our Codex hook table mapped `PermissionRequest` →
+  `waiting_approval` unconditionally. No better hook exists: nothing fires on
+  guardian start/finish (the guardian session is `SubAgentSource::Other`, which
+  is excluded from Subagent hooks), and `GuardianAssessment` events are
+  explicitly not persisted to the main rollout (`rollout/src/policy.rs`).
+- **Fix:** an **L3 guardian-trunk watcher** (`codex-guardian-watcher.js` +
+  `adapters/codex-guardian.js`). The guardian runs as its own Codex session that
+  writes its own rollout under `~/.codex/sessions` — session_meta has
+  `source: {subagent: {other: "guardian"}}` and `parent_thread_id` = the main
+  thread; each review is one turn (`task_started` → `task_complete` with the
+  verdict JSON in `last_agent_message`, e.g. `{"outcome":"allow"}`). The watcher
+  binds the trunk to the wrapped session's main thread id and maps real events:
+  review turn starts → **reviewing**; verdict `allow` → **running_tool**
+  ("reviewer approved" — the action verifiably proceeds); verdict `deny` →
+  **thinking** ("reviewer denied" — the model received the rejection and keeps
+  working). An unreadable verdict reports nothing, so a pending cue is never
+  cleared on a guess. With `approvals_reviewer = "user"` ("Ask for approval")
+  there is no trunk and behavior is unchanged: `PermissionRequest` →
+  *waiting for approval* until the user decides (process-tree/denial detection
+  resolve it, as before).
+- **Known limitations (accepted):** (1) A ≤ ~1 s *waiting for approval* flicker
+  can precede *reviewing* (the hook fires immediately; the trunk poll is 700 ms).
+  (2) Reviews of a **collab subagent's** actions (multi-agent runs) have their
+  own trunks keyed to the subagent's thread and are not watched; a subagent's
+  `PermissionRequest` can still briefly show *waiting for approval* until the
+  next main-session event. (3) After a guardian deny the pet shows *thinking*,
+  not *waiting for approval* — by design: Codex resolves the request itself and
+  the model decides what to do next (it may ask the user in chat, which then
+  surfaces as turn-end *idle*). The TUI's passive `/approve` denial-override
+  picker is not a blocking prompt.
+
+## ✅ Resolved: Codex `/quit` hung on its goodbye (and the pet kept showing "working")
+
+- **Symptom:** Exiting Codex with `/quit` printed the token-usage goodbye and the
+  `codex resume` hint, but the terminal never returned to a prompt and the pet
+  kept showing the session as ongoing. Ctrl+C exited fine. Only happened under
+  `haya-pet run`.
+- **Root cause (verified against codex-rs 0.139.0 source + a live orphaned
+  process):** the `haya-pet state` hook reporter had three **unbounded awaits**
+  in its IPC path — pipe connect, write drain, and `socket.end()` → `close` —
+  and the CLI entry's `process.exit()` only runs after the command resolves, so
+  one never-settling await made a reporter hang forever. Codex awaits every
+  hook child with a **default 600 s timeout**
+  (`hooks/engine/discovery.rs` `timeout_sec.unwrap_or(600)`;
+  `command_runner.rs` `timeout(…, child.wait_with_output())`), and `Stop` hooks
+  are awaited in turn completion (`core/hook_runtime.rs run_turn_stop_hooks`)
+  with the TUI exiting only after `ShutdownComplete`. So one hung turn-end
+  `state idle` reporter produced BOTH symptoms: the idle report never arrived
+  (pet stuck on "working"), and `/quit` waited up to 10 minutes on the hook
+  child after printing its goodbye. Ctrl+C kills Codex without that wait and
+  orphans the reporter — exactly what live process-tree monitoring showed (a
+  parentless reporter under the hook node version).
+- **Fix:** every IPC await now has a hard deadline (`cli-core/deadline.js`).
+  The reporter races its whole connect→send→close against **2 s** and exits
+  with `{ ok:false, reason:"timeout" }` on the deadline (one best-effort status
+  update lost; `HAYA_PET_HOOK_DEBUG` logs a `timeout: true` line for evidence).
+  The wrapper's companion connection gets the same guard (**5 s** per
+  send/close) so a wedged companion can never keep the wrapper — and the user's
+  terminal — alive after the wrapped CLI exits. Dead sessions still resolve via
+  the registry's stale/drop sweep, so a lost message self-heals.
+- **Note:** why a pipe await occasionally never settles (companion busy/wedged
+  at that moment) is not yet pinned down; the deadline makes it harmless and
+  the debug log will show `timeout: true` entries if it recurs.
+
 ## ✅ Resolved: pet stuck on "waiting for approval" after a manual denial
 
 - **Symptom:** With Claude Code hooks enabled, denying a permission prompt left the
@@ -176,10 +255,16 @@ observation (`--observe`) or L1 lifecycle as the fallback. Current state:
     activity is covered by an L3 Codex transcript watcher that tails
     `~/.codex/sessions` JSONL: normal tools report `running_tool`, `apply_patch`
     reports `editing_files`, and HAYA Pet returns to `thinking` after active tool
-    calls drain. `PermissionRequest` (the *waiting for approval* cue — the
-    highest-value state) is **unconfirmed**; it likely depends on an
-    approval-required flow and needs a dedicated test before the feature is worth
-    wiring in.
+    calls drain.
+  - **`PermissionRequest` fires** (confirmed live on 0.139.0), but **once, at
+    approval-request creation, before routing** — under "Approve for me"
+    (`approvals_reviewer = auto_review` / legacy `guardian_subagent`) the user is
+    never actually prompted, so the hook alone over-reports *waiting for
+    approval*. An L3 **guardian-trunk watcher** tails the guardian reviewer's own
+    rollout (`source: {subagent:{other:"guardian"}}`, `parent_thread_id` = main
+    thread) and refines the state: review running → *reviewing*, verdict `allow`
+    → *running_tool*, verdict `deny` → *thinking*. See the resolved
+    false-waiting-for-approval entry above.
 - **Antigravity (`agy`)** — **not yet implemented** (no hook injection). Uses
   `--observe` or L1 lifecycle. A Gemini-schema hook adapter is a planned follow-up.
 - **Generic / unknown** — no hooks; PTY observation (`--observe`) or L1 lifecycle.
@@ -194,7 +279,7 @@ remains a possible follow-up.
 |---|---|---|
 | L1 | process wrapper | default; session lifecycle + exit code |
 | L4 | client hooks | opt-in via `haya-pet hooks on` (Claude Code full, Codex partial); reports through `haya-pet state …` |
-| L3 | client logs | Codex session JSONL watcher for tool activity; Claude denial recovery; future clients can add similar transcript adapters |
+| L3 | client logs | Codex session JSONL watcher for tool activity; Codex guardian-trunk watcher for auto-review status; Claude denial recovery; future clients can add similar transcript adapters |
 | L3 | process tree | approval-accept detection: a `waiting_approval` session flips to `running_tool` when the approved command verifiably starts under the client's pid |
 | L2 | PTY output scraping | opt-in via `--observe` (terminal-fidelity tradeoff) |
 

package/docs/troubleshooting.md

@@ -16,7 +16,8 @@ deferred problems with known root causes.
 | Terminal scroll / Shift+Tab / backspace odd while a CLI runs under `haya-pet run` | Fixed — `haya-pet run` now uses native passthrough by default (full fidelity). If you opted into `--observe`, drop it. See [known-issues.md](known-issues.md). |
 | Pet shows only **idle/lifecycle** while **Claude Code** works | Live in-session status is opt-in: run `haya-pet hooks on` once (persisted). The first `haya-pet run` afterward shows a one-time Claude *review hooks* prompt — approve it. Also make sure the companion is running (`haya-pet start`). Check the toggle with `haya-pet hooks status`. |
 | Typing doesn't work / **Claude Code** TUI frozen under `haya-pet run` | You have hooks enabled and Claude is showing its *review hooks* trust prompt (approve it once), or your Claude is too old for `--settings`. Run `haya-pet hooks off` (or set `HAYA_PET_NO_HOOKS=1`) for native passthrough with lifecycle-only status — typing and Shift+Tab work normally. |
-| Pet shows only **idle/lifecycle** while **Codex** works | Live status is opt-in: run `haya-pet hooks on` once (persisted, global), then `haya-pet run --client codex -- codex`; approve Codex's one-time *review hooks* prompt. `thinking`/`idle` come from hooks and `running_tool`/`editing_files` from a transcript watcher; *waiting for approval* doesn't fire yet (upstream [openai/codex#16732](https://github.com/openai/codex/issues/16732)). |
+| Pet shows only **idle/lifecycle** while **Codex** works | Live status is opt-in: run `haya-pet hooks on` once (persisted, global), then `haya-pet run --client codex -- codex`; approve Codex's one-time *review hooks* prompt. `thinking`/`idle` come from hooks, `running_tool`/`editing_files` from a transcript watcher, and approval states from the `PermissionRequest` hook plus a guardian-review watcher. |
+| Pet showed **waiting for approval** while **Codex** auto-reviewed the request ("Approve for me") | Fixed — with `approvals_reviewer = auto_review` (legacy `guardian_subagent`) Codex's guardian decides without asking you; the pet now shows **reviewing** during the assessment, then **working** on an allow verdict or **thinking** on a deny. *Waiting for approval* still shows when Codex actually asks you (`approvals_reviewer = "user"`). |
 | **Codex** live status didn't turn on / you pass your own `-p`/`--profile` | Codex allows only one profile, so haya-pet skips hook injection when you supply your own and prints a notice. Drop your `-p` for that run to get live status, or accept lifecycle-only. |
 | Pet shows only **idle/lifecycle** while **Antigravity** (`agy`) works | Antigravity has no hook adapter yet. Add `--observe` for coarse PTY activity, or accept lifecycle-only status. |
 | Claude hooks fail with **"hook exited with code 1"** | The hook command must not bake an **fnm**/node-manager *per-shell* node path (`…\fnm_multishells\<pid>_…\node.exe`) that dies when the shell exits. haya-pet bakes the stable `realpath`-resolved node path into the temp settings instead. Update to the latest version. |
@@ -24,7 +25,9 @@ deferred problems with known root causes.
 | Pet stayed on **waiting for approval** after I denied a tool | Fixed — Claude fires no hook on a manual denial, so the wrapper tails the session transcript and clears to **idle** when the denial is recorded. A genuinely-pending approval (you haven't decided yet) correctly keeps alerting — there's no timer. |
 | Pet stayed on **waiting for approval** after I *approved* a command | Fixed — Claude also fires no hook at the accept moment, so the companion watches the client's process tree while a session waits: when the approved command verifiably starts (a new persistent process under the client), the pet flips to **working**. Expect a ~2–3s lag after your click. File-edit approvals (no process) resolve at completion, which is near-instant. |
 | Want to see which status events fire | Set `HAYA_PET_HOOK_DEBUG=<file.jsonl>` before `haya-pet run`; each hook- and transcript-sourced status appends one JSON line (timestamp, state, and source/event). |
+| Don't want the update check / notice | Set `HAYA_PET_NO_UPDATE_CHECK=1`. The check is a daily, cached HTTPS request to the npm registry (no session data); it is already skipped automatically when output is piped. |
 | Pet stays **idle** after force-quitting a CLI | The wrapper marks the session stale ~15s after the heartbeat stops, then drops it. Exiting normally (incl. Ctrl+C) reports **exited** immediately. |
+| **Codex `/quit`** printed its goodbye but the terminal hung (pet stuck on "working") | Fixed — a hook reporter could hang on a pipe await and Codex waits up to 600s for hook children at shutdown. Reporters now hard-deadline at 2s. Update to the latest version. |
 | Ctrl+C doesn't exit the CLI cleanly under `haya-pet run` | Fixed — the wrapper no longer dies on Ctrl+C; the signal reaches the CLI, which exits, and the pet shows the result. |
 | `ENOENT … electron\path.txt` | Electron's install extraction was interrupted — see below. |
 

package/package.json

@@ -1,8 +1,30 @@
 {
   "name": "@hayasaka7/haya-pet",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "type": "module",
   "description": "Generic AI CLI pet runtime foundation.",
+  "keywords": [
+    "haya-pet",
+    "desktop-pet",
+    "virtual-pet",
+    "desktop-companion",
+    "ai",
+    "ai-agents",
+    "coding-agents",
+    "ai-cli",
+    "codex",
+    "codex-cli",
+    "claude-code",
+    "gemini-cli",
+    "aider",
+    "antigravity",
+    "electron",
+    "cli",
+    "terminal",
+    "developer-tools",
+    "local-first",
+    "productivity"
+  ],
   "license": "MIT",
   "author": "Ai Hayasaka",
   "repository": {

package/packages/adapters/src/codex-guardian.js

@@ -0,0 +1,131 @@
+// Pure parser for Codex guardian-review rollouts. When `approvals_reviewer` is
+// `auto_review` (legacy alias `guardian_subagent`, the TUI's "Approve for me"),
+// Codex routes approval requests to a guardian subagent instead of prompting the
+// user — the PermissionRequest hook still fires at request creation, but the
+// human approval UI never appears. The only persisted trace of the review is a
+// separate "guardian trunk" rollout under ~/.codex/sessions whose session_meta
+// carries source.subagent.other == "guardian" and parent_thread_id == the main
+// thread; each review is one turn there (task_started → task_complete with the
+// verdict JSON in last_agent_message). Verified against codex-cli 0.139.0
+// (codex-rs guardian/review_session.rs; rollout/src/policy.rs excludes the
+// GuardianAssessment events themselves from persistence).
+
+// Classify a rollout's first JSONL line (the session_meta record) so watchers
+// can tell main sessions, guardian review sessions, and other subagents apart.
+export function classifyCodexSessionMeta(line) {
+  let entry;
+  try {
+    entry = JSON.parse(line);
+  } catch {
+    return undefined;
+  }
+
+  if (entry?.type !== "session_meta") {
+    return undefined;
+  }
+
+  const payload = entry.payload;
+  if (!payload || typeof payload !== "object") {
+    return undefined;
+  }
+
+  const threadId = typeof payload.id === "string" ? payload.id : undefined;
+  const parentThreadId =
+    typeof payload.parent_thread_id === "string" ? payload.parent_thread_id : undefined;
+
+  return { kind: resolveSessionKind(payload), threadId, parentThreadId };
+}
+
+function resolveSessionKind(payload) {
+  const subagentSource =
+    typeof payload.source === "object" && payload.source !== null
+      ? payload.source.subagent
+      : undefined;
+
+  if (typeof subagentSource === "object" && subagentSource !== null) {
+    if (subagentSource.other === "guardian") {
+      return "guardian";
+    }
+    return "subagent";
+  }
+
+  if (payload.thread_source === "subagent") {
+    return "subagent";
+  }
+
+  return "main";
+}
+
+// Parse one guardian-trunk JSONL line into a review lifecycle event. Each review
+// turn yields task_started (the guardian began assessing an approval request)
+// and task_complete (verdict in last_agent_message: `{"outcome":"allow"|"deny"}`,
+// optionally with risk_level/rationale). An unreadable verdict maps to
+// outcome: undefined so callers can leave the pet state untouched (safe: the
+// existing waiting cue stays up rather than being cleared on a guess).
+export function parseGuardianTranscriptLine(line, options = {}) {
+  let entry;
+  try {
+    entry = JSON.parse(line);
+  } catch {
+    return undefined;
+  }
+
+  if (entry?.type !== "event_msg") {
+    return undefined;
+  }
+
+  // Same replay guard as the main transcript parser: skip records from before
+  // the current session, keep records without a parseable timestamp.
+  const minTimestampMs = options.minTimestampMs ?? 0;
+  if (minTimestampMs > 0 && typeof entry.timestamp === "string") {
+    const timestampMs = Date.parse(entry.timestamp);
+    if (Number.isFinite(timestampMs) && timestampMs < minTimestampMs) {
+      return undefined;
+    }
+  }
+
+  const payload = entry.payload;
+  if (!payload || typeof payload !== "object") {
+    return undefined;
+  }
+
+  if (payload.type === "task_started") {
+    return { type: "review_started" };
+  }
+
+  if (payload.type === "task_complete") {
+    return { type: "review_finished", outcome: parseVerdictOutcome(payload.last_agent_message) };
+  }
+
+  return undefined;
+}
+
+function parseVerdictOutcome(lastAgentMessage) {
+  if (typeof lastAgentMessage !== "string") {
+    return undefined;
+  }
+
+  let verdict;
+  try {
+    verdict = JSON.parse(lastAgentMessage);
+  } catch {
+    return undefined;
+  }
+
+  const outcome = verdict?.outcome;
+  return outcome === "allow" || outcome === "deny" ? outcome : undefined;
+}
+
+export function parseGuardianTranscriptLines(lines, options = {}) {
+  const events = [];
+  for (const line of lines) {
+    if (typeof line !== "string" || line.trim() === "") {
+      continue;
+    }
+    const event = parseGuardianTranscriptLine(line, options);
+    if (event) {
+      events.push(event);
+    }
+  }
+  return events;
+}

package/packages/adapters/src/codex-hooks.js

@@ -33,8 +33,17 @@
 //  - NOT FIRING (0.137): PreToolUse — so `running_tool` / `editing_files` never
 //    arrive in practice yet (upstream coverage gap, openai/codex#16732). The
 //    entries are kept (harmless no-ops) so they light up once Codex fixes it.
-//  - UNTESTED: PermissionRequest / PreCompact / SubagentStart|Stop (no approval /
-//    compaction / subagent occurred in the probe).
+//  - PermissionRequest (verified live on 0.139.0, semantics from codex-rs
+//    source): fires ONCE at approval-request creation, BEFORE the request is
+//    routed to the guardian auto-reviewer or the user. Under "Approve for me"
+//    (approvals_reviewer=auto_review, legacy alias guardian_subagent) the user
+//    is never prompted at all, so waiting_approval from this hook over-reports;
+//    the wrapper's codex-guardian-watcher refines it to reviewing /
+//    running_tool / thinking from the guardian's own rollout. The guardian
+//    fires NO hooks itself (SubAgentSource::Other is excluded from Subagent
+//    hooks), so these entries can't see it.
+//  - UNTESTED: PreCompact / SubagentStart|Stop (no compaction / subagent
+//    occurred in the probe).
 //
 // OPEN QUESTION (injection): unlike `claude --settings <file>`, Codex has no
 // per-invocation settings-file flag. Candidate non-mutating paths, best first:

package/packages/adapters/test/codex-guardian.test.mjs

@@ -0,0 +1,174 @@
+import assert from "node:assert/strict";
+import { test } from "../../../test/harness.mjs";
+import {
+  classifyCodexSessionMeta,
+  parseGuardianTranscriptLine,
+  parseGuardianTranscriptLines
+} from "../src/codex-guardian.js";
+
+function metaLine(payload) {
+  return JSON.stringify({ timestamp: "2026-06-12T01:36:41.556Z", type: "session_meta", payload });
+}
+
+test("classifyCodexSessionMeta identifies a main session", () => {
+  const line = metaLine({
+    id: "main-1",
+    parent_thread_id: null,
+    originator: "codex-tui",
+    source: "cli",
+    thread_source: "user"
+  });
+
+  assert.deepEqual(classifyCodexSessionMeta(line), {
+    kind: "main",
+    threadId: "main-1",
+    parentThreadId: undefined
+  });
+});
+
+test("classifyCodexSessionMeta identifies a guardian review session", () => {
+  const line = metaLine({
+    id: "guardian-1",
+    parent_thread_id: "main-1",
+    source: { subagent: { other: "guardian" } },
+    thread_source: "subagent"
+  });
+
+  assert.deepEqual(classifyCodexSessionMeta(line), {
+    kind: "guardian",
+    threadId: "guardian-1",
+    parentThreadId: "main-1"
+  });
+});
+
+test("classifyCodexSessionMeta identifies non-guardian subagent sessions", () => {
+  const bySource = metaLine({
+    id: "agent-1",
+    parent_thread_id: "main-1",
+    source: { subagent: { other: "collab" } }
+  });
+  const byThreadSource = metaLine({
+    id: "agent-2",
+    parent_thread_id: "main-1",
+    source: "cli",
+    thread_source: "subagent"
+  });
+
+  assert.equal(classifyCodexSessionMeta(bySource).kind, "subagent");
+  assert.equal(classifyCodexSessionMeta(byThreadSource).kind, "subagent");
+});
+
+test("classifyCodexSessionMeta rejects non-meta and malformed lines", () => {
+  assert.equal(classifyCodexSessionMeta("not json"), undefined);
+  assert.equal(classifyCodexSessionMeta("{}"), undefined);
+  assert.equal(
+    classifyCodexSessionMeta(JSON.stringify({ type: "response_item", payload: { type: "message" } })),
+    undefined
+  );
+  assert.equal(classifyCodexSessionMeta(metaLine(null)), undefined);
+});
+
+test("parseGuardianTranscriptLine maps task_started to review_started", () => {
+  const line = JSON.stringify({
+    timestamp: "2026-06-12T01:36:41.557Z",
+    type: "event_msg",
+    payload: { type: "task_started", turn_id: "turn-1" }
+  });
+
+  assert.deepEqual(parseGuardianTranscriptLine(line), { type: "review_started" });
+});
+
+test("parseGuardianTranscriptLine extracts the verdict from task_complete", () => {
+  const allow = JSON.stringify({
+    type: "event_msg",
+    payload: { type: "task_complete", turn_id: "turn-1", last_agent_message: '{"outcome":"allow"}' }
+  });
+  const deny = JSON.stringify({
+    type: "event_msg",
+    payload: {
+      type: "task_complete",
+      turn_id: "turn-2",
+      last_agent_message:
+        '{"risk_level":"high","user_authorization":"low","outcome":"deny","rationale":"too risky"}'
+    }
+  });
+
+  assert.deepEqual(parseGuardianTranscriptLine(allow), { type: "review_finished", outcome: "allow" });
+  assert.deepEqual(parseGuardianTranscriptLine(deny), { type: "review_finished", outcome: "deny" });
+});
+
+test("parseGuardianTranscriptLine reports an unknown outcome when the verdict is unreadable", () => {
+  const garbled = JSON.stringify({
+    type: "event_msg",
+    payload: { type: "task_complete", turn_id: "turn-1", last_agent_message: "I think it is fine" }
+  });
+  const missing = JSON.stringify({
+    type: "event_msg",
+    payload: { type: "task_complete", turn_id: "turn-1" }
+  });
+  const unexpected = JSON.stringify({
+    type: "event_msg",
+    payload: { type: "task_complete", turn_id: "turn-1", last_agent_message: '{"outcome":"maybe"}' }
+  });
+
+  assert.deepEqual(parseGuardianTranscriptLine(garbled), { type: "review_finished", outcome: undefined });
+  assert.deepEqual(parseGuardianTranscriptLine(missing), { type: "review_finished", outcome: undefined });
+  assert.deepEqual(parseGuardianTranscriptLine(unexpected), { type: "review_finished", outcome: undefined });
+});
+
+test("parseGuardianTranscriptLine ignores unrelated and malformed records", () => {
+  assert.equal(parseGuardianTranscriptLine("not json"), undefined);
+  assert.equal(
+    parseGuardianTranscriptLine(
+      JSON.stringify({ type: "event_msg", payload: { type: "token_count" } })
+    ),
+    undefined
+  );
+  assert.equal(
+    parseGuardianTranscriptLine(
+      JSON.stringify({ type: "response_item", payload: { type: "message", role: "assistant" } })
+    ),
+    undefined
+  );
+});
+
+test("parseGuardianTranscriptLine skips records from before the session start", () => {
+  const old = JSON.stringify({
+    timestamp: "2026-06-12T01:00:00.000Z",
+    type: "event_msg",
+    payload: { type: "task_started", turn_id: "turn-0" }
+  });
+  const fresh = JSON.stringify({
+    timestamp: "2026-06-12T02:00:00.000Z",
+    type: "event_msg",
+    payload: { type: "task_started", turn_id: "turn-1" }
+  });
+  const untimestamped = JSON.stringify({
+    type: "event_msg",
+    payload: { type: "task_started", turn_id: "turn-2" }
+  });
+  const minTimestampMs = Date.parse("2026-06-12T01:30:00.000Z");
+
+  assert.equal(parseGuardianTranscriptLine(old, { minTimestampMs }), undefined);
+  assert.deepEqual(parseGuardianTranscriptLine(fresh, { minTimestampMs }), { type: "review_started" });
+  assert.deepEqual(parseGuardianTranscriptLine(untimestamped, { minTimestampMs }), {
+    type: "review_started"
+  });
+});
+
+test("parseGuardianTranscriptLines collects events and skips blank lines", () => {
+  const lines = [
+    "",
+    JSON.stringify({ type: "event_msg", payload: { type: "task_started", turn_id: "t1" } }),
+    "   ",
+    JSON.stringify({
+      type: "event_msg",
+      payload: { type: "task_complete", turn_id: "t1", last_agent_message: '{"outcome":"allow"}' }
+    })
+  ];
+
+  assert.deepEqual(parseGuardianTranscriptLines(lines), [
+    { type: "review_started" },
+    { type: "review_finished", outcome: "allow" }
+  ]);
+});

package/packages/app-state/src/state.js

@@ -105,7 +105,10 @@ export function parsePositionState(text) {
       settings: {
         ...defaults.settings,
         ...(isPlainObject(parsed.settings) ? parsed.settings : {})
-      }
+      },
+      // Cached npm update-check result (see update-check.js) — must survive a
+      // load/save round-trip or every run would re-fetch from the registry.
+      ...(isPlainObject(parsed.updateCheck) ? { updateCheck: parsed.updateCheck } : {})
     };
   } catch {
     return defaults;