@scrylog/cli 0.1.0

package/src/daemon/collectors/codex/collector.ts

@@ -0,0 +1,661 @@
+import { existsSync, statSync, unwatchFile, watch, watchFile } from "node:fs";
+import type { FSWatcher } from "node:fs";
+import { join, basename } from "node:path";
+import type { ScrylogConfig } from "../../../shared/config";
+import type { SessionModel } from "../../../shared/types";
+import type { DaemonStore } from "../../store";
+import type { Collector } from "../../scheduler";
+import type { Logger } from "../../../shared/logger";
+import { NOOP_LOGGER } from "../../../shared/logger";
+import { ensureHooksDirSafe } from "../../../shared/platform";
+import type { GitCollector } from "../git";
+import { parseJsonlFile } from "./jsonl";
+import { extractActiveSpawnedSubagents, extractMeta, extractState, extractSummary } from "./transcript";
+import { CodexHookFileData, isValidHookData, readHookData, isHookNewer, getHookTime, mergeHookIntoModel, mergeCodexMeta } from "./hooks";
+import { discoverTranscripts, getCodexDir } from "./discovery";
+
+interface WatchedTranscript {
+  sessionId: string;
+  path: string;
+  lastModified: number;
+  size: number;
+  processedLastModified?: number;
+  processedSize?: number;
+}
+
+interface TranscriptEntry {
+  timestamp?: string;
+  type?: string;
+  payload?: {
+    type?: string;
+    name?: string;
+    role?: string;
+    content?: Array<{ type: string; text?: string }>;
+  };
+}
+
+type TerminalTranscriptEvent = "task_complete" | "turn_aborted";
+
+/** Detects a request_user_input function call in the transcript.
+ *  This is the ONLY case where the transcript may override hook state,
+ *  because Codex does not fire a hook for this specific tool. */
+function hasRequestUserInput(entries: TranscriptEntry[]): boolean {
+  for (let i = entries.length - 1; i >= 0; i--) {
+    const entry = entries[i];
+    if (entry?.type === "response_item" && entry.payload?.type === "function_call" && entry.payload?.name === "request_user_input") {
+      return true;
+    }
+    // Skip turn_aborted placeholders — they are not real user responses
+    if (entry?.type === "response_item" && entry.payload?.type === "message" && entry.payload?.role === "user") {
+      const text = entry.payload.content?.map((c) => c.text ?? "").join("") ?? "";
+      if (text.includes("<turn_aborted>")) continue;
+    }
+    // Stop at the first meaningful response_item we hit backwards
+    if (entry?.type === "response_item") break;
+  }
+  return false;
+}
+
+function hasPendingProposedPlan(entries: TranscriptEntry[]): boolean {
+  for (let i = entries.length - 1; i >= 0; i--) {
+    const entry = entries[i];
+    if (entry?.type !== "response_item") continue;
+
+    if (entry.payload?.type === "message" && entry.payload?.role === "user") {
+      const text = entry.payload.content?.map((c) => c.text ?? "").join("") ?? "";
+      if (text.includes("<turn_aborted>")) continue;
+      return false;
+    }
+
+    if (entry.payload?.type !== "message" || entry.payload.role !== "assistant") {
+      return false;
+    }
+
+    const text = entry.payload.content?.map((c) => c.text ?? "").join("") ?? "";
+    return text.trimStart().startsWith("<proposed_plan>");
+  }
+
+  return false;
+}
+
+function hasAnsweredRequestUserInputWork(entries: TranscriptEntry[]): boolean {
+  let sawWorkAfterAnswer = false;
+  let sawRequestUserInputOutput = false;
+
+  for (let i = entries.length - 1; i >= 0; i--) {
+    const entry = entries[i];
+    if (entry?.type !== "response_item" && entry?.type !== "event_msg") continue;
+
+    if (entry.type === "response_item") {
+      const payloadType = entry.payload?.type;
+      if (payloadType === "message" && entry.payload?.role === "user") {
+        const text = entry.payload.content?.map((c) => c.text ?? "").join("") ?? "";
+        if (text.includes("<turn_aborted>")) continue;
+        return false;
+      }
+
+      if (payloadType === "function_call" && entry.payload?.name === "request_user_input") {
+        return sawRequestUserInputOutput && sawWorkAfterAnswer;
+      }
+
+      if (payloadType === "function_call_output") {
+        sawRequestUserInputOutput = true;
+        continue;
+      }
+
+      if (payloadType === "reasoning" || payloadType === "function_call") {
+        sawWorkAfterAnswer = true;
+        continue;
+      }
+
+      if (payloadType === "message" && entry.payload?.role === "assistant") {
+        sawWorkAfterAnswer = true;
+      }
+      continue;
+    }
+
+    if (entry.payload?.type === "agent_message" || entry.payload?.type === "item_completed") {
+      sawWorkAfterAnswer = true;
+    }
+  }
+
+  return false;
+}
+
+function preserveLocationMetadata(model: SessionModel, existing?: SessionModel): SessionModel {
+  if (!existing) return model;
+
+  return {
+    ...model,
+    source: existing.source,
+    project: existing.project ?? model.project,
+    tmux: existing.tmux ?? model.tmux,
+    legacyPaneId: existing.legacyPaneId ?? model.legacyPaneId,
+    processTree: existing.processTree ?? model.processTree,
+    processChain: existing.processChain ?? model.processChain,
+    sample: existing.sample ?? model.sample,
+    toolReasons: existing.toolReasons ?? model.toolReasons,
+    stateReasons: existing.stateReasons ?? model.stateReasons,
+    stableForMs: existing.stableForMs ?? model.stableForMs,
+    currentCommand: existing.currentCommand ?? model.currentCommand,
+    currentPath: existing.currentPath ?? model.currentPath,
+    panePid: existing.panePid ?? model.panePid,
+    tty: existing.tty ?? model.tty,
+    paneTitle: existing.paneTitle ?? model.paneTitle,
+  };
+}
+
+function findTerminalEventAfterHook(entries: TranscriptEntry[], hookEventTime?: number): TerminalTranscriptEvent | null {
+  if (!hookEventTime) return null;
+
+  for (let i = entries.length - 1; i >= 0; i--) {
+    const entry = entries[i];
+    if (entry?.type !== "event_msg") continue;
+    const eventType = entry.payload?.type;
+    if (eventType !== "task_complete" && eventType !== "turn_aborted") continue;
+
+    const timestamp = entry.timestamp ? Date.parse(entry.timestamp) : Number.NaN;
+    if (!Number.isFinite(timestamp) || timestamp <= hookEventTime) return null;
+    return eventType;
+  }
+
+  return null;
+}
+
+export class CodexCollector implements Collector {
+  name = "codex";
+  private store?: DaemonStore;
+  private config?: ScrylogConfig;
+  private logger: Logger = NOOP_LOGGER;
+  private watched = new Map<string, WatchedTranscript>();
+  private hookWatched = new Set<string>();
+  private hookDirWatcher?: FSWatcher;
+  private lastProcessedSeq = new Map<string, number>();
+  private discoveryTimer?: ReturnType<typeof setInterval>;
+  private fallbackTimer?: ReturnType<typeof setInterval>;
+
+  constructor(private readonly gitCollector?: GitCollector) {}
+
+  async start(store: DaemonStore, config: ScrylogConfig, logger: Logger): Promise<void> {
+    this.store = store;
+    this.config = config;
+    this.logger = logger;
+
+    const codexDir = getCodexDir(config);
+    logger.info("codex", "Collector started", { event: "collector.started", collector: this.name, codexDir, hooksEnabled: config.codex.hooksEnabled });
+
+    if (config.codex.hooksEnabled) {
+      this.startHooksDirWatcher(config.codex.hooksDir);
+    }
+
+    this.run();
+    this.discoveryTimer = setInterval(() => this.run(), 30_000);
+    this.fallbackTimer = setInterval(() => this.rereadWatched(), 5_000);
+  }
+
+  async stop(): Promise<void> {
+    if (this.discoveryTimer) clearInterval(this.discoveryTimer);
+    if (this.fallbackTimer) clearInterval(this.fallbackTimer);
+
+    for (const { path } of this.watched.values()) {
+      try { unwatchFile(path); } catch { /* ignore */ }
+    }
+    this.watched.clear();
+
+    for (const hookFile of this.hookWatched) {
+      try { unwatchFile(hookFile); } catch { /* ignore */ }
+    }
+    this.hookWatched.clear();
+    this.lastProcessedSeq.clear();
+
+    if (this.hookDirWatcher) {
+      try { this.hookDirWatcher.close(); } catch { /* ignore */ }
+      this.hookDirWatcher = undefined;
+    }
+
+    this.logger.info("codex", "Collector stopped", { event: "collector.stopped", collector: this.name });
+  }
+
+  // ── Internal ───────────────────────────────────────────────────────────────
+
+  private run(): void {
+    const store = this.store!;
+    const config = this.config!;
+    const codexDir = getCodexDir(config);
+
+    // Build set of session IDs that are hook-managed, so discoverTranscripts
+    // can include their transcripts even past the 24h cutoff.
+    const hookManagedIds = new Set<string>();
+    for (const session of store.getSessions()) {
+      if (session.detectionSource === "codex-hook" && session.tool === "codex") {
+        hookManagedIds.add(session.codex?.sessionId ?? session.id.replace(/^codex:/, ""));
+      }
+    }
+
+    const transcripts = discoverTranscripts(codexDir, hookManagedIds);
+
+    this.logger.debug("codex", "Discovery cycle", {
+      event: "collector.discovery_completed",
+      collector: this.name,
+      codexDir,
+      transcripts: transcripts.length,
+    });
+
+    for (const transcript of transcripts) {
+      this.processTranscript(transcript);
+    }
+
+    const trackedPaths = new Set(transcripts.map((t) => t.path));
+    for (const path of trackedPaths) {
+      if (!this.watched.has(path)) {
+        const transcript = transcripts.find((t) => t.path === path);
+        if (!transcript) continue;
+        this.watched.set(path, transcript);
+        this.logger.debug("codex", "Watching transcript", { sessionId: transcript.sessionId, path });
+        watchFile(path, { interval: 2000 }, () => {
+          const t = this.watched.get(path);
+          if (t) this.processTranscript(t);
+        });
+      }
+    }
+
+    for (const [path, transcript] of this.watched) {
+      if (!trackedPaths.has(path)) {
+        try { unwatchFile(path); } catch { /* ignore */ }
+        this.watched.delete(path);
+        this.logger.debug("codex", "Stopped watching transcript", { sessionId: transcript.sessionId });
+        // Don't remove hook-managed sessions — they have an authoritative lifecycle
+        // managed by hooks. Only remove transcript-sourced sessions.
+        const existingSession = store.getSession(`codex:${transcript.sessionId}`);
+        if (existingSession?.detectionSource !== "codex-hook") {
+          store.removeSession(`codex:${transcript.sessionId}`);
+        }
+      }
+    }
+
+    store.setCollectorStatus(this.name, { running: true, lastRunAt: Date.now() });
+  }
+
+  private processTranscript(transcript: import("./discovery").DiscoveredTranscript): void {
+    const store = this.store!;
+    const config = this.config!;
+    const transcriptMaxBytes = config.retention?.transcriptMaxBytes;
+    const entries = parseJsonlFile(transcript.path, transcriptMaxBytes);
+    const meta = extractMeta(entries);
+    const sessionId = meta.sessionId || transcript.sessionId;
+    const storeId = `codex:${sessionId}`;
+    const existingSession = store.getSession(storeId);
+    const watched = this.watched.get(transcript.path);
+    if (
+      watched?.processedLastModified === transcript.lastModified
+      && watched.processedSize === transcript.size
+      && existingSession
+    ) {
+      return;
+    }
+
+    const transcriptState = extractState(entries);
+    const transcriptSummary = extractSummary(entries);
+
+    // Transcript-based state: detect questions and agent messages
+    let model: SessionModel = {
+      id: `codex:${transcript.sessionId}`,
+      source: "standalone",
+      tool: "codex",
+      state: transcriptState,
+      summary: transcriptSummary ?? (meta.sessionId ? `Codex session` : "Codex session"),
+      lastActivity: transcript.lastModified,
+      codex: {
+        sessionId,
+        transcriptPath: transcript.path,
+        ...(meta.model ? { model: meta.model } : {}),
+        ...(meta.forkedFromId ? { forkedFromId: meta.forkedFromId } : {}),
+        ...(meta.parentSessionId ? { parentSessionId: meta.parentSessionId } : {}),
+        ...(meta.agentNickname ? { agentNickname: meta.agentNickname } : {}),
+        ...(meta.agentRole ? { agentRole: meta.agentRole } : {}),
+      },
+      ...(meta.parentSessionId ? { parentSessionId: meta.parentSessionId } : {}),
+      hasAttention: transcriptState === "waiting-input",
+      detectionSource: "codex-transcript",
+    };
+    model.id = storeId;
+    if (meta.agentNickname && !transcriptSummary) {
+      model.summary = `Codex sub-agent ${meta.agentNickname}`;
+    }
+
+    // Hooks are the authoritative source of state for Codex sessions.
+    // Transcripts enrich metadata (model, subagents, transcriptPath) but
+    // never override state, hasAttention, or activeTool.
+    //
+    // EXCEPTION: Codex does not fire a hook for request_user_input. When the
+    // transcript detects this specific tool call, it may override the hook state
+    // to waiting-input. This is the ONLY transcript override permitted.
+    const transcriptHasRequestUserInput = transcriptState === "waiting-input" && hasRequestUserInput(entries);
+    const transcriptHasProposedPlan = hasPendingProposedPlan(entries);
+    const transcriptIndicatesWaitingInput = transcriptHasRequestUserInput || transcriptHasProposedPlan;
+    const transcriptIndicatesWorking = !transcriptIndicatesWaitingInput && hasAnsweredRequestUserInputWork(entries);
+    const transcriptOverridesHook = existingSession?.detectionSource === "codex-hook" && transcriptIndicatesWaitingInput;
+    const terminalTranscriptEvent = existingSession?.detectionSource === "codex-hook"
+      ? findTerminalEventAfterHook(entries, existingSession.codex?.hookEventTime)
+      : null;
+    const terminalOverridesHook = Boolean(terminalTranscriptEvent && !transcriptIndicatesWaitingInput && !transcriptIndicatesWorking);
+
+    // Check for hook data first — hooks are always authoritative when present.
+    let hookDataFromFile: Partial<SessionModel> | null = null;
+    if (config.codex.hooksEnabled) {
+      const fileHookData = readHookData(config.codex.hooksDir, sessionId) ?? readHookData(config.codex.hooksDir, transcript.sessionId);
+      if (fileHookData && getHookTime(fileHookData) >= transcript.lastModified && isHookNewer(existingSession, fileHookData)) {
+        hookDataFromFile = fileHookData;
+      }
+    }
+
+    if (hookDataFromFile) {
+      // Hook data exists and is authoritative — migrate to codex-hook if needed.
+      model = mergeHookIntoModel(model, hookDataFromFile, transcript.path);
+      model = preserveLocationMetadata(model, existingSession);
+    } else if (existingSession?.detectionSource === "codex-hook") {
+      // Hook-managed session with no fresh hook data. Transcript may override
+      // only for request_user_input (the one case Codex does not fire a hook).
+      const resolvedState = transcriptOverridesHook ? "waiting-input"
+        : transcriptIndicatesWorking ? "working"
+        : terminalOverridesHook ? "idle"
+        : existingSession.state;
+      const resolvedHasAttention = transcriptOverridesHook ? true
+        : transcriptIndicatesWorking ? false
+        : terminalOverridesHook ? false
+        : existingSession.hasAttention;
+      const resolvedSummary = transcriptOverridesHook
+        ? (extractSummary(entries) ?? existingSession.summary)
+        : (existingSession.summary || model.summary);
+
+      model = {
+        ...model,
+        state: resolvedState,
+        hasAttention: resolvedHasAttention,
+        summary: resolvedSummary,
+        activeTool: (terminalOverridesHook || transcriptIndicatesWorking) ? undefined : existingSession.activeTool,
+        detectionSource: "codex-hook",
+        codex: mergeCodexMeta(
+          {
+            sessionId: existingSession.codex?.sessionId ?? transcript.sessionId,
+            transcriptPath: existingSession.codex?.transcriptPath || transcript.path,
+            ...(meta.model ? { model: meta.model } : {}),
+            ...(meta.forkedFromId ? { forkedFromId: meta.forkedFromId } : {}),
+            ...(meta.parentSessionId ? { parentSessionId: meta.parentSessionId } : {}),
+            ...(meta.agentNickname ? { agentNickname: meta.agentNickname } : {}),
+            ...(meta.agentRole ? { agentRole: meta.agentRole } : {}),
+            ...(transcriptOverridesHook ? { attentionKind: "question" } : {}),
+            ...(terminalOverridesHook ? { attentionKind: "none" } : {}),
+          },
+          existingSession.codex ?? {},
+        ),
+        ...(existingSession.parentSessionId ?? meta.parentSessionId ? { parentSessionId: existingSession.parentSessionId ?? meta.parentSessionId } : {}),
+        lastActivity: existingSession.lastActivity,
+      };
+      model = preserveLocationMetadata(model, existingSession);
+    } else if (existingSession?.detectionSource === "codex-transcript" && transcriptIndicatesWaitingInput) {
+      // Transcript-only session where the agent is waiting for user input.
+      // Codex did not fire a hook for this state, so the transcript is the
+      // authoritative source. When a hook finally arrives, detectionSource
+      // migrates to codex-hook automatically via the hook handlers.
+      model = {
+        ...model,
+        state: "waiting-input",
+        hasAttention: true,
+        summary: extractSummary(entries) ?? model.summary,
+        detectionSource: "codex-transcript",
+        codex: mergeCodexMeta(
+          {
+            sessionId: existingSession.codex?.sessionId ?? transcript.sessionId,
+            transcriptPath: existingSession.codex?.transcriptPath || transcript.path,
+            ...(meta.model ? { model: meta.model } : {}),
+            ...(meta.forkedFromId ? { forkedFromId: meta.forkedFromId } : {}),
+            ...(meta.parentSessionId ? { parentSessionId: meta.parentSessionId } : {}),
+            ...(meta.agentNickname ? { agentNickname: meta.agentNickname } : {}),
+            ...(meta.agentRole ? { agentRole: meta.agentRole } : {}),
+            attentionKind: "question",
+          },
+          existingSession.codex ?? {},
+        ),
+        ...(existingSession.parentSessionId ?? meta.parentSessionId ? { parentSessionId: existingSession.parentSessionId ?? meta.parentSessionId } : {}),
+      };
+      model = preserveLocationMetadata(model, existingSession);
+    } else if (!existingSession && transcriptIndicatesWaitingInput) {
+      model = {
+        ...model,
+        state: "waiting-input",
+        hasAttention: true,
+        codex: {
+          sessionId,
+          transcriptPath: transcript.path,
+          ...(model.codex ?? {}),
+          attentionKind: "question",
+        },
+      };
+    }
+
+    if (existingSession && existingSession.detectionSource !== "codex-hook" && existingSession.detectionSource !== "codex-transcript") {
+      model = preserveLocationMetadata(model, existingSession);
+    }
+
+    // Resolve git project info from currentPath (populated by hooks)
+    if (this.gitCollector && model.currentPath && !model.project) {
+      const project = this.gitCollector.resolve(model.currentPath);
+      if (project) model = { ...model, project };
+    }
+
+    store.upsertSession(model);
+    this.upsertActiveSpawnedSubagents(model, extractActiveSpawnedSubagents(entries));
+    const currentWatched = this.watched.get(transcript.path);
+    if (currentWatched) {
+      this.watched.set(transcript.path, {
+        ...currentWatched,
+        lastModified: transcript.lastModified,
+        size: transcript.size,
+        processedLastModified: transcript.lastModified,
+        processedSize: transcript.size,
+      });
+    }
+    this.logger.debug("codex", "Processed transcript", { event: "transcript.processed", sessionId, state: model.state, detectionSource: model.detectionSource, path: transcript.path });
+
+    this.syncChildSessionIds();
+  }
+
+  private upsertActiveSpawnedSubagents(parent: SessionModel, spawned: ReturnType<typeof extractActiveSpawnedSubagents>): void {
+    for (const subagent of spawned) {
+      const id = `codex:${subagent.agentId}`;
+      const existing = this.store!.getSession(id);
+      if (existing) {
+        if (existing.state === "working" || existing.state === "waiting-input") continue;
+        this.store!.upsertSession({
+          ...existing,
+          state: "working",
+          lastActivity: Math.max(existing.lastActivity, parent.lastActivity),
+          parentSessionId: existing.parentSessionId ?? parent.id,
+          codex: mergeCodexMeta(
+            {
+              sessionId: existing.codex?.sessionId ?? subagent.agentId,
+              transcriptPath: existing.codex?.transcriptPath ?? "",
+            },
+            {
+              ...(existing.codex ?? {}),
+              agentId: existing.codex?.agentId ?? subagent.agentId,
+              ...(subagent.agentType ? { agentType: subagent.agentType } : {}),
+              ...(subagent.nickname ? { agentNickname: subagent.nickname } : {}),
+              parentSessionId: existing.parentSessionId ?? parent.id,
+            },
+          ),
+        });
+        continue;
+      }
+      this.store!.upsertSession({
+        id,
+        source: "standalone",
+        tool: "codex",
+        state: "working",
+        summary: subagent.nickname ? `Codex sub-agent ${subagent.nickname}` : "Codex sub-agent",
+        lastActivity: parent.lastActivity,
+        parentSessionId: parent.id,
+        detectionSource: "codex-transcript",
+        codex: {
+          sessionId: subagent.agentId,
+          transcriptPath: "",
+          agentId: subagent.agentId,
+          ...(subagent.agentType ? { agentType: subagent.agentType } : {}),
+          ...(subagent.nickname ? { agentNickname: subagent.nickname } : {}),
+          parentSessionId: parent.id,
+        },
+      });
+    }
+  }
+
+  /** Re-process all watched transcripts (fallback polling) */
+  private rereadWatched(): void {
+    for (const transcript of this.watched.values()) {
+      try {
+        const stat = statSync(transcript.path);
+        this.processTranscript({ ...transcript, lastModified: stat.mtimeMs, size: stat.size });
+      } catch {
+        // File may have been removed
+      }
+    }
+  }
+
+  /** Watch the hooks directory for new/changed files so state updates are near-immediate */
+  private startHooksDirWatcher(hooksDir: string): void {
+    try {
+      ensureHooksDirSafe(hooksDir);
+    } catch {
+      // Directory may be unwritable or fail ownership/permission validation — handled below
+    }
+
+    if (!existsSync(hooksDir)) {
+      this.logger.debug("codex", "Hooks dir not found — skipping watcher", { hooksDir });
+      return;
+    }
+
+    // Watch for new files appearing in the hooks dir
+    try {
+      this.hookDirWatcher = watch(hooksDir, (eventType, filename) => {
+        if (!filename || !filename.endsWith(".json")) return;
+        const sessionId = basename(filename, ".json");
+        this.onHookFileChanged(hooksDir, sessionId, filename);
+      });
+    } catch {
+      this.logger.debug("codex", "Could not watch hooks dir", { hooksDir });
+    }
+  }
+
+  /** Called when a hook file is created or modified */
+  private onHookFileChanged(hooksDir: string, sessionId: string, filename: string): void {
+    const hookFile = join(hooksDir, filename);
+
+    // Start watching this specific file if not already
+    if (!this.hookWatched.has(hookFile)) {
+      this.hookWatched.add(hookFile);
+      watchFile(hookFile, { interval: 500 }, () => {
+        this.onHookFileChanged(hooksDir, sessionId, filename);
+      });
+    }
+
+    // Skip duplicate processing: if the hookSeq hasn't changed, this is a
+    // redundant event from the directory watcher and per-file watchFile.
+    const hookData = readHookData(hooksDir, sessionId);
+    if (!hookData) {
+      // Hook file was deleted (Stop with stop_hook_active=false) — clean up watcher
+      this.unwatchHookFile(hookFile);
+      return;
+    }
+    const incomingSeq = hookData.codex?.hookSeq ?? 0;
+    const lastSeq = this.lastProcessedSeq.get(sessionId) ?? -1;
+    if (incomingSeq <= lastSeq) return;
+    this.lastProcessedSeq.set(sessionId, incomingSeq);
+
+    this.logger.debug("codex", "Hook received — refreshing session", { event: "integration.event_received", sessionId, hookSeq: incomingSeq });
+
+    // Find the corresponding transcript to re-process
+    const transcriptEntry = [...this.watched.values()].find((t) => t.sessionId === sessionId);
+    if (transcriptEntry) {
+      try {
+        const stat = statSync(transcriptEntry.path);
+        this.processTranscript({ ...transcriptEntry, lastModified: stat.mtimeMs, size: stat.size });
+      } catch {
+        // Transcript may have been removed
+      }
+      return;
+    }
+
+    // The transcript may not be watched yet (e.g. a session created via hook before transcript is discovered).
+    // hookData was already read above for dedup — use it to create a minimal session entry.
+
+    const existing = this.store!.getSession(`codex:${sessionId}`);
+    if (existing && !isHookNewer(existing, hookData)) {
+      return;
+    }
+    if (existing) {
+      // Merge hook data into existing session
+      const mergedSummary = hookData.summary ?? existing.summary;
+      this.store!.upsertSession({
+        ...existing,
+        ...hookData,
+        id: existing.id,
+        source: existing.source,
+        summary: mergedSummary,
+        lastActivity: (hookData.lastActivity as number | undefined) ?? existing.lastActivity,
+        activeTool: hookData.activeTool ?? existing.activeTool,
+        codex: mergeCodexMeta(
+          {
+            sessionId,
+            transcriptPath: (hookData.codex?.transcriptPath || existing.codex?.transcriptPath || "") as string,
+          },
+          hookData.codex ?? {},
+        ),
+      });
+      this.logger.debug("codex", "Hook merged into session (no transcript)", { event: "session.upsert_from_hook", sessionId, state: hookData.state });
+    } else {
+      // Minimal stub for a session discovered only via hook
+      const currentPath = hookData.currentPath as string | undefined;
+      const project = (this.gitCollector && currentPath)
+        ? this.gitCollector.resolve(currentPath) ?? undefined
+        : undefined;
+      const stub: SessionModel = {
+        id: `codex:${sessionId}`,
+        source: "standalone",
+        tool: "codex",
+        state: (hookData.state as SessionModel["state"]) ?? "idle",
+        summary: hookData.summary ?? "Codex session",
+        lastActivity: (hookData.lastActivity as number) ?? Date.now(),
+        hasAttention: hookData.hasAttention,
+        activeTool: hookData.activeTool,
+        currentPath,
+        project,
+        parentSessionId: hookData.parentSessionId,
+        detectionSource: "codex-hook",
+        codex: mergeCodexMeta(
+          {
+            sessionId,
+            transcriptPath: (hookData.codex?.transcriptPath ?? "") as string,
+          },
+          hookData.codex ?? {},
+        ),
+      };
+      this.store!.upsertSession(stub);
+      this.logger.debug("codex", "Session created from hook", { event: "session.upsert_from_hook", sessionId, parentSessionId: hookData.parentSessionId, state: stub.state });
+    }
+
+    this.syncChildSessionIds();
+  }
+
+  /** Stop watching a per-file watcher and clean up tracking state */
+  private unwatchHookFile(hookFile: string): void {
+    if (this.hookWatched.has(hookFile)) {
+      this.hookWatched.delete(hookFile);
+      try { unwatchFile(hookFile); } catch { /* ignore */ }
+    }
+  }
+
+  /** Rebuild childSessionIds on parent sessions after any session upsert */
+  private syncChildSessionIds(): void {
+    this.store!.syncChildSessionIds();
+  }
+}