FEA-1444: Add Codex hook event dedup + renderer opt-in toggle

Layer 2 — Event-level dedup against rollout-tail:
- New filterEventsAlreadyCapturedByHooks in codex-import.js. Runs before
  importSession in importCodexSession; queries existing events for rows
  matching (session_id, event_type, COALESCE(tool_name, ''), created_at
  truncated to whole seconds) and drops duplicates. Hook-handler-inserted
  rows land first (real-time); the ~5s-later rollout-tail no-ops on match.
- The dedup statement is cached per-dbModule via WeakMap so a batch of
  many changed sessions compiles the SQL once, not once per session.
- Best-effort: any prepare/query failure is swallowed and the event is
  kept. False negatives (cosmetic duplicates) are preferred over false
  positives (silently dropped events). Sub-second timestamp drift handled
  by the substr(?, 1, 19) match.

Layer 3 — Renderer opt-in toggle:
- apps/desktop/src/main/app.ts: new IPC handlers
  desktop:{get,set}-agent-monitor-codex-hooks-opt-in that call the
  already-exported isAgentMonitorCodexHooksOptIn /
  setAgentMonitorCodexHooksOptIn. Gated on the master Agent Dashboard
  flag, matching the Claude pair shape exactly.
- apps/desktop/src/main/preload.ts: mirror bridge methods exposing the
  two channels to the renderer.
- apps/desktop/src/renderer/index.html: new #codexDashConsent toggle row
  directly below the existing #claudeDashConsent. Same visibility
  semantics (shown only on agent-settings route), same disabled-when-
  master-off behavior, same hint text reset on master flag re-enable
  (Codex hint reset now mirrors Claude's after a review-flagged gap).
  refreshCodexHooksToggle is called when the user toggles the Claude
  hooks toggle so the sibling's on/off badge stays in sync.

Test:
- apps/desktop/test/agent-session-event-dedup.test.ts (new): 4 unit
  tests on the filter against a sandbox SQLite DB. Covers (1) duplicate
  filter with sub-second drift, (2) non-duplicate survival across
  mixed events, (3) best-effort behavior on DB errors, (4) empty-events
  no-op. Uses the conditional-skip pattern (skipReason ? { skip: ... }
  : undefined) because Node test runner treats skip: null as "skip with
  no reason" rather than "don't skip" — gotcha learned during debugging.

Independent code review (second pass on the cumulative diff) surfaced:
- Medium: Codex hint stale after master flag re-enable (Claude hint was
  reset in the else branch, Codex hint wasn't). Fixed.
- Low: Comment inaccuracy about which toggle "unblocks the master flag"
  in wireClaudeHooksToggle. Rewritten.
- Low: Dedup statement prepared once per session inside the batch loop
  instead of once per process. Cached via WeakMap.
All three addressed in this commit.

Testing:
- pnpm -C apps/desktop typecheck: clean
- pnpm -C apps/desktop lint: clean
- pnpm -C apps/desktop build:agent-monitor: clean (Layer 1 hard-gates
  + sidecar SQLite gate continue to pass)
- pnpm -C apps/desktop test (full suite): 1945/1945 pass, 0 fail
- New agent-session-event-dedup.test.ts: 4/4 pass
- agent-monitor-hooks-core.test.ts (from Layer 1): 10/10 pass (no
  regression)

Risks:
- Cross-second timestamp drift between hook and rollout-tail can defeat
  dedup. Documented design tradeoff: false negatives are cosmetic
  duplicates; false positives would silently drop events. Will revisit
  with a content-hash dedup key in a follow-up if cosmetic duplication
  becomes visible in practice.
- IPC handler test coverage deferred. Both new handlers are shallow
  plumbing that call already-tested functions (covered by Layer 1's
  agent-monitor-hooks-core.test.ts). Typecheck validates the signatures
  + preload bridge types.
- Renderer JS duplicates the Claude/Codex toggle pattern. Per CLAUDE.md
  this is the kind of duplication worth extracting, but inline renderer
  JS makes a shared helper awkward; deferred to a separate cleanup
  ticket if the pattern repeats with a third harness.

Author: Andrew Eye

apps/desktop/scripts/agent-monitor-codex/codex-import.js

@@ -30,6 +30,16 @@ const catchupCache = createCatchupCache({ persistPath: ingestCachePath("codex")
  * or { skipped: true } when the file has no usable content.
  */
 function importCodexSession(dbModule, session) {
+  // FEA-1444 dedup: if the user opted into Codex hooks, the same logical
+  // event will already be in `events` (inserted ~5s earlier by the hook
+  // handler). Without this filter the rollout-tail importer would create a
+  // duplicate row for every Codex event after the user opts in. Match on
+  // (session_id, event_type, tool_name, created_at-truncated-to-second) —
+  // hooks and rollout-tail timestamps usually agree within sub-second
+  // granularity for the same logical event. False negatives are tolerable
+  // (cosmetic duplicates); false positives would silently drop events, so
+  // the match is intentionally narrow.
+  filterEventsAlreadyCapturedByHooks(dbModule, session);
   const result = importSession(dbModule, session);
   // Stamp the harness regardless of skipped/backfilled — cheap, idempotent,
   // and self-heals rows imported before the `harness` column existed.
@@ -42,6 +52,73 @@ function importCodexSession(dbModule, session) {
   return { sessionId: session.sessionId, result, reactivated };
 }
 
+/**
+ * FEA-1444: filter session.events in place, removing any whose
+ * (session_id, event_type, COALESCE(tool_name, ''), created_at-rounded-to-second)
+ * already exists in the `events` table. The hook handler inserts in real time;
+ * rollout-tail catches up ~5s later — so the dedup query consistently sees
+ * hook-sourced rows first when both paths are active.
+ *
+ * No-op when session.events is empty or the events query fails (best-effort;
+ * never block the import on a dedup-time error).
+ */
+// FEA-1444 dedup-stmt cache: the filter runs per-session inside
+// importCodexSession, which itself runs inside the importBatch transaction
+// loop. Caching the prepared statement on the dbModule keeps us at O(1)
+// compilations per process instead of O(sessions) per batch. The cache is
+// keyed by dbModule so a fresh DatabaseSync in tests gets a fresh stmt.
+const dedupStmtCache = new WeakMap();
+function getDedupCheckStmt(dbModule) {
+  let stmt = dedupStmtCache.get(dbModule);
+  if (stmt) return stmt;
+  // Truncate created_at to seconds via `substr(?, 1, 19)` so sub-second
+  // timestamp drift between the hook payload and the rollout file doesn't
+  // produce a false negative.
+  stmt = dbModule.db.prepare(
+    "SELECT 1 FROM events " +
+      "WHERE session_id = ? AND event_type = ? " +
+      "AND COALESCE(tool_name, '') = COALESCE(?, '') " +
+      "AND substr(COALESCE(created_at, ''), 1, 19) = substr(COALESCE(?, ''), 1, 19) " +
+      "LIMIT 1",
+  );
+  dedupStmtCache.set(dbModule, stmt);
+  return stmt;
+}
+
+function filterEventsAlreadyCapturedByHooks(dbModule, session) {
+  if (!session || !Array.isArray(session.events) || session.events.length === 0) {
+    return;
+  }
+  let checkStmt;
+  try {
+    checkStmt = getDedupCheckStmt(dbModule);
+  } catch {
+    return; // schema mismatch or db locked — fall through, accept duplicates
+  }
+  const filtered = [];
+  for (const ev of session.events) {
+    if (!ev || typeof ev !== "object") {
+      filtered.push(ev);
+      continue;
+    }
+    try {
+      const hit = checkStmt.get(
+        session.sessionId,
+        ev.event_type ?? null,
+        ev.tool_name ?? null,
+        ev.created_at ?? null,
+      );
+      if (hit) {
+        continue; // already captured by the hook handler — drop the duplicate
+      }
+    } catch {
+      // best-effort — on any per-row failure, keep the event
+    }
+    filtered.push(ev);
+  }
+  session.events = filtered;
+}
+
 /**
  * Parse + import every discovered Codex rollout file. Designed to be cheap on
  * repeat runs: importSession skips already-imported sessions (or backfills
@@ -107,4 +184,9 @@ async function importAllCodexSessions(dbModule, opts = {}) {
   return { imported, skipped, errors };
 }
 
-module.exports = { importAllCodexSessions, importCodexSession };
+module.exports = {
+  importAllCodexSessions,
+  importCodexSession,
+  // Exposed for regression coverage of FEA-1444 dedup.
+  filterEventsAlreadyCapturedByHooks,
+};

apps/desktop/src/main/app.ts

@@ -69,7 +69,9 @@ import { DesktopWindow } from "./window.js";
 import { AgentMonitorSidecar } from "./agent-monitor-sidecar.js";
 import { AgentSessionSyncService } from "./agent-session-sync-service.js";
 import {
+  isAgentMonitorCodexHooksOptIn,
   isAgentMonitorHooksEnabled,
+  setAgentMonitorCodexHooksOptIn,
   setAgentMonitorHooksEnabled,
   syncAgentMonitorHooksOnBoot,
 } from "./agent-monitor-hooks.js";
@@ -2499,6 +2501,26 @@ export class DesktopApplication {
         return setAgentMonitorHooksEnabled(enabled === true);
       },
     );
+    // FEA-1444: opt-in toggle for Codex hooks. Surfaced as a sibling of the
+    // Claude hooks toggle in the Agent Dashboard view. Gated on the master
+    // Agent Dashboard flag for the same reason the Claude toggle is — the
+    // sidecar must be running to receive the forwarded hook events.
+    ipcMain.handle("desktop:get-agent-monitor-codex-hooks-opt-in", () =>
+      this.isAgentMonitorEnabled() && isAgentMonitorCodexHooksOptIn(),
+    );
+    ipcMain.handle(
+      "desktop:set-agent-monitor-codex-hooks-opt-in",
+      (_event, optIn: boolean) => {
+        if (!this.isAgentMonitorEnabled()) {
+          return {
+            ok: false,
+            enabled: false,
+            error: "Agent Dashboard is disabled in Settings.",
+          };
+        }
+        return setAgentMonitorCodexHooksOptIn(optIn === true);
+      },
+    );
     ipcMain.handle("desktop:get-logs", () => gatewayLog.getEntries());
     ipcMain.handle("desktop:clear-logs", () => {
       gatewayLog.clear();

apps/desktop/src/main/preload.ts

@@ -136,6 +136,16 @@ const desktopApi = {
       "desktop:set-agent-monitor-hooks-enabled",
       enabled,
     ) as Promise<{ ok: boolean; enabled: boolean; error?: string }>,
+  // FEA-1444: Codex hook opt-in. Mirrors the Claude pair above.
+  getAgentMonitorCodexHooksOptIn: () =>
+    ipcRenderer.invoke(
+      "desktop:get-agent-monitor-codex-hooks-opt-in",
+    ) as Promise<boolean>,
+  setAgentMonitorCodexHooksOptIn: (optIn: boolean) =>
+    ipcRenderer.invoke(
+      "desktop:set-agent-monitor-codex-hooks-opt-in",
+      optIn,
+    ) as Promise<{ ok: boolean; enabled: boolean; error?: string }>,
   getAllFlags: () =>
     ipcRenderer.invoke("desktop:get-all-flags") as Promise<unknown>,
   onFlagsChanged: (callback: () => void) => {

apps/desktop/src/renderer/index.html

@@ -3404,6 +3404,17 @@ <h1>See every coding agent you use — in one place</h1>
           <span>Enable Claude Code session tracking</span>
           <span id="claudeDashHooksHint" style="color:var(--muted-foreground,#888)">— off (no changes to your global Claude config)</span>
         </div>
+        <!-- FEA-1444: opt-in toggle for Codex hook ingestion. Sibling of the
+             Claude toggle above. Requires `[features].codex_hooks = true` in
+             ~/.codex/config.toml on the Codex side. -->
+        <div id="codexDashConsent" style="display:none;align-items:center;gap:10px;padding:10px 14px;border-bottom:1px solid var(--border,#2a2a2a);font-size:13px">
+          <label class="toggle-switch" title="Installs Codex CLI hooks in ~/.codex/hooks.json so this dashboard receives live session events from Codex (in addition to the rollout-tail watcher that already runs). Requires `[features].codex_hooks = true` in ~/.codex/config.toml. Off by default; fully removable.">
+            <input type="checkbox" id="codexDashHooksToggle" />
+            <span class="toggle-track"></span>
+          </label>
+          <span>Enable Codex CLI session tracking (experimental)</span>
+          <span id="codexDashHooksHint" style="color:var(--muted-foreground,#888)">— off (rollout-tail watcher continues)</span>
+        </div>
         <div id="claudeDashStatus" class="dash-loading" aria-live="polite"></div>
         <iframe id="claudeDashFrame" title="Claude Code Agent Monitor" style="display:none;width:100%;border:0;background:#fff"></iframe>
       </section>
@@ -3971,6 +3982,11 @@ <h3 class="settings-group-title">Labs</h3>
           if (consent) {
             consent.style.display = id === "agent-settings" ? "flex" : "none";
           }
+          // FEA-1444: sibling Codex toggle gets the same visibility treatment.
+          const codexConsent = document.getElementById("codexDashConsent");
+          if (codexConsent) {
+            codexConsent.style.display = id === "agent-settings" ? "flex" : "none";
+          }
           startClaudeDashboard();
           navigateAgentRoute(item.route);
         } else {
@@ -4030,13 +4046,26 @@ <h3 class="settings-group-title">Labs</h3>
         const status = document.getElementById("claudeDashStatus");
         const toggle = document.getElementById("claudeDashHooksToggle");
         const hint = document.getElementById("claudeDashHooksHint");
+        // FEA-1444: same disable-when-master-off treatment for the Codex toggle.
+        const codexToggle = document.getElementById("codexDashHooksToggle");
+        const codexHint = document.getElementById("codexDashHooksHint");
 
         if (toggle) {
           toggle.disabled = !cachedAgentMonitorEnabled;
           if (!cachedAgentMonitorEnabled) {
             toggle.checked = false;
           }
         }
+        if (codexToggle) {
+          codexToggle.disabled = !cachedAgentMonitorEnabled;
+          if (!cachedAgentMonitorEnabled) {
+            codexToggle.checked = false;
+          }
+        }
+        if (codexHint && !cachedAgentMonitorEnabled) {
+          codexHint.textContent =
+            "— enable Agent Dashboard in Settings to manage session tracking";
+        }
 
         if (!cachedAgentMonitorEnabled) {
           stopClaudeDashboardPoll();
@@ -4059,8 +4088,16 @@ <h3 class="settings-group-title">Labs</h3>
             activateTab("settings");
             activateSettingsTab("relay-gateway");
           }
-        } else if (hint) {
-          hint.textContent = "— off (no changes to your global Claude config)";
+        } else {
+          if (hint) {
+            hint.textContent = "— off (no changes to your global Claude config)";
+          }
+          // FEA-1444: mirror Claude hint reset for Codex so the stale
+          // "enable Agent Dashboard in Settings..." text doesn't linger
+          // after the user turns the master flag back on.
+          if (codexHint) {
+            codexHint.textContent = "— off (rollout-tail watcher continues)";
+          }
         }
 
         // Render the initial view once the enabled-state is known on boot.
@@ -4110,6 +4147,62 @@ <h3 class="settings-group-title">Labs</h3>
         } catch (_) { /* leave as-is */ }
       }
 
+      // FEA-1444: Codex hook opt-in toggle. Mirrors the Claude pair above.
+      async function refreshCodexHooksToggle() {
+        const toggle = document.getElementById("codexDashHooksToggle");
+        const hint = document.getElementById("codexDashHooksHint");
+        if (!toggle) return;
+        if (!cachedAgentMonitorEnabled) {
+          toggle.disabled = true;
+          if (hint) {
+            hint.textContent =
+              "— enable Agent Dashboard in Settings to manage session tracking";
+          }
+          return;
+        }
+        try {
+          const optedIn = await api.getAgentMonitorCodexHooksOptIn();
+          toggle.checked = !!optedIn;
+          toggle.disabled = false;
+          if (hint) {
+            hint.textContent = optedIn
+              ? "— on (Codex hooks installed in ~/.codex/hooks.json; also set [features].codex_hooks = true in ~/.codex/config.toml)"
+              : "— off (rollout-tail watcher continues)";
+          }
+        } catch (_) { /* leave as-is */ }
+      }
+
+      (function wireCodexHooksToggle() {
+        const toggle = document.getElementById("codexDashHooksToggle");
+        const hint = document.getElementById("codexDashHooksHint");
+        if (!toggle) return;
+        toggle.addEventListener("change", async () => {
+          const want = toggle.checked;
+          toggle.disabled = true;
+          if (hint) hint.textContent = want ? "— enabling…" : "— disabling…";
+          try {
+            const res = await api.setAgentMonitorCodexHooksOptIn(want);
+            if (!res || !res.ok) {
+              toggle.checked = !want;
+              if (hint) {
+                hint.textContent =
+                  "— failed: " + ((res && res.error) || "unknown error");
+              }
+            } else {
+              await refreshCodexHooksToggle();
+            }
+          } catch (e) {
+            toggle.checked = !want;
+            if (hint) {
+              hint.textContent =
+                "— failed: " + (e && e.message ? e.message : "error");
+            }
+          } finally {
+            toggle.disabled = false;
+          }
+        });
+      })();
+
       (function wireClaudeHooksToggle() {
         const toggle = document.getElementById("claudeDashHooksToggle");
         const hint = document.getElementById("claudeDashHooksHint");
@@ -4125,6 +4218,11 @@ <h3 class="settings-group-title">Labs</h3>
               hint.textContent = "— failed: " + ((res && res.error) || "unknown error");
             } else {
               await refreshClaudeHooksToggle();
+              // FEA-1444: refresh sibling Codex toggle state so its on/off
+              // badge stays in sync after a successful Claude-toggle change.
+              // (The master `agentMonitorEnabled` flag, not this toggle,
+              // controls the Codex toggle's disabled state.)
+              await refreshCodexHooksToggle();
             }
           } catch (e) {
             toggle.checked = !want;
@@ -4161,6 +4259,9 @@ <h3 class="settings-group-title">Labs</h3>
           return;
         }
         void refreshClaudeHooksToggle();
+        // FEA-1444: also refresh the sibling Codex toggle on dashboard mount
+        // so its on/off badge reflects the persisted state.
+        void refreshCodexHooksToggle();
         if (claudeDashLoaded) { sizeClaudeFrame(); return; }
         renderDashLoading();