Merge pull request #73 from boxp/feature/boxp-66-session-file-watcher

[codex] Add session history file watcher

Author: boxp

README.ja.md

@@ -92,6 +92,7 @@ ceeker
 **機能:**
 
 - **自動反映**: `sessions.edn` のファイル変更を inotify（Linux）/ WatchService で検知し、TUIを自動更新
+- **session履歴ファイルwatcher**: hookなしでも Claude Code / Codex の JSONL 履歴ファイルからセッションを自動検知
 - **セッション絞り込み**: エージェント種別・ステータス・テキスト検索で表示を絞り込み
 
 **キーバインド:**
@@ -133,7 +134,7 @@ ceeker --list-sessions
 ]
 ```
 
-出力前に ceeker は 1 回だけ同期的に pane 生存確認と capture ベースの状態更新を行います。tmux 更新に失敗した場合でも、保存済みの session list はそのまま返します。
+出力前に ceeker は直近の session 履歴ファイルをスキャンし、その後 1 回だけ同期的に pane 生存確認と capture ベースの状態更新を行います。tmux 更新に失敗した場合でも、保存済みの session list はそのまま返します。
 
 ### ジャンプ後に自動終了
 
@@ -161,9 +162,16 @@ tmux 内のどこからでもポップアップで ceeker を開けます。`--e
 bind-key C-k display-popup -h 80% -w 80% -d "#{pane_current_path}" -E "ceeker --exit-on-jump"
 ```
 
-## セットアップ（必須）
+## セットアップ
 
-インストール後、AIコーディングエージェントからセッションイベントを受信するために hook の設定が**必要**です。
+ceeker は Claude Code / Codex の session 履歴 JSONL ファイルを監視して、セッションを自動検知します:
+
+- Claude Code: `~/.claude/projects/<cwd-slug>/<session-id>.jsonl`
+- Codex: `~/.codex/sessions/YYYY/MM/DD/rollout-<timestamp>-<uuid>.jsonl`
+
+このため、hook 設定なしでも ceeker にセッションが表示されます。Codex は session ファイルだけで追跡できるため、`notify` 設定は任意です。
+
+hook は、より細かいイベントタイミングや最終メッセージを取り込みたい場合に有用です。特に Claude Code の明示的な hook イベントや Codex notify 更新を併用できます。
 
 ### Claude Code
 

README.md

@@ -92,6 +92,7 @@ Displays a list of all active sessions.
 **Features:**
 
 - **Auto-refresh**: Detects file changes to `sessions.edn` via inotify (Linux) / WatchService and automatically updates the TUI
+- **Session file watcher**: Detects Claude Code / Codex sessions from history JSONL files even without hooks
 - **Session filtering**: Filter the display by agent type, status, or text search
 
 **Key bindings:**
@@ -133,7 +134,7 @@ Example output:
 ]
 ```
 
-Before printing, ceeker performs one synchronous pane liveness and capture-based state refresh. If tmux refresh fails, ceeker still returns the stored session list.
+Before printing, ceeker scans recent session history files, then performs one synchronous pane liveness and capture-based state refresh. If tmux refresh fails, ceeker still returns the stored session list.
 
 ### Exit on Jump
 
@@ -161,9 +162,16 @@ You can open ceeker as a popup from anywhere inside tmux. Combine with `--exit-o
 bind-key C-k display-popup -h 80% -w 80% -d "#{pane_current_path}" -E "ceeker --exit-on-jump"
 ```
 
-## Setup (Required)
+## Setup
 
-After installation, you **must** configure hooks so that ceeker can receive session events from your AI coding agents.
+ceeker automatically detects Claude Code and Codex sessions by watching their session history JSONL files:
+
+- Claude Code: `~/.claude/projects/<cwd-slug>/<session-id>.jsonl`
+- Codex: `~/.codex/sessions/YYYY/MM/DD/rollout-<timestamp>-<uuid>.jsonl`
+
+This means sessions can appear in ceeker without hook configuration. Codex sessions are tracked from the session file alone, so `notify` is optional.
+
+Hooks are still useful for richer event timing and final messages, especially if you want explicit Claude Code hook events or Codex notify updates.
 
 ### Claude Code
 

docs/project_docs/BOXP-66/plan.md

@@ -0,0 +1,34 @@
+# BOXP-66 Session File Watcher
+
+## Goal
+
+Detect Claude Code and Codex sessions from their JSONL session history files so ceeker can show sessions before hook/notify events arrive.
+
+## Design Decisions
+
+- Added `ceeker.watch.sessions` as the single owner of session history parsing, incremental tailing, one-shot scans, pane-id resolution, and WatchService polling.
+- Kept WatchService and file reads inside `async/thread` via `start-session-watcher!`; the stop channel is unbuffered and is closed by the caller.
+- Used in-memory file offsets for incremental tailing. Each JSONL line is capped at 1 MiB; invalid or oversized lines are ignored.
+- One-shot `scan-recent-sessions!` scans JSONL files modified within the last 24 hours by default. It is called by TUI startup and `--list-sessions` before pane/capture refresh.
+- Codex `session_meta` establishes `session-id` and `cwd`; later `event_msg` lines update the accumulated per-file session state. `task_complete` maps to `:completed` and stores `last_agent_message`.
+- Claude lines with `sessionId`, `cwd`, or `timestamp` map to `:running`; assistant lines also record message content when present.
+- Pane-id resolution reuses `ceeker.tmux.pane/list-pane-info` and the new `find-agent-pid-in-tree`. On Linux it reads `/proc/<pid>/environ` for `TMUX_PANE`; otherwise it only falls back when exactly one cwd/agent candidate exists.
+- Store normalization now deduplicates entries with the same `:session-id`, preferring pane-id keyed entries and otherwise the newest `:last-updated`.
+- Watcher writes skip older same-session data so a stale file event does not overwrite newer hook/capture state.
+
+## Verification
+
+- Parser tests cover Claude and Codex JSONL events.
+- Tail tests cover offset-based append reads.
+- Pane resolution tests mock tmux and `/proc` access.
+- Store tests cover session-id deduplication.
+- Scan tests use temporary fixture directories.
+- Worker tests verify stop-channel shutdown.
+
+## Review Fix Plan
+
+- Add regression coverage for Claude assistant JSONL lines so `:last-message` remains available after scan, including when a following non-message event arrives.
+- Add regression coverage for synchronous scans when a JSONL file disappears between enumeration and opening; the scan should warn on stderr and continue.
+- Update session event merging to preserve incoming `:last-message` for any status and keep the accumulated value when later events omit it.
+- Wrap per-file scan reads in `try`/`catch` so unreadable files are skipped without aborting startup or `--list-sessions`.
+- Run `make ci` and commit the fix in English.

src/ceeker/session_list.clj

@@ -1,7 +1,8 @@
 (ns ceeker.session-list
   "Shared session list access for TUI and CLI."
   (:require [ceeker.state.store :as store]
-            [ceeker.tmux.pane :as pane]))
+            [ceeker.tmux.pane :as pane]
+            [ceeker.watch.sessions :as session-watch]))
 
 (defn sort-sessions
   "Sorts sessions the same way as the TUI list."
@@ -24,6 +25,7 @@
 (defn refresh-session-state!
   "Refreshes pane liveness and capture-based session states once."
   [state-dir]
+  (session-watch/scan-recent-sessions! {:state-dir state-dir})
   (pane/close-stale-sessions! state-dir)
   (pane/refresh-session-states! state-dir))
 

src/ceeker/state/store.clj

@@ -101,25 +101,85 @@
     incoming
     existing))
 
+(defn- pane-key?
+  "Returns true when key is the canonical pane key for session."
+  [key session]
+  (and (seq (:pane-id session))
+       (= key (:pane-id session))))
+
+(defn- pick-session-id-duplicate
+  "Picks one entry among entries with the same :session-id.
+   A pane-id keyed entry is preferred because pane-id is the
+   canonical live-session key. Otherwise the newest entry wins."
+  [[existing-key existing :as existing-entry]
+   [incoming-key incoming :as incoming-entry]]
+  (let [existing-pane? (pane-key? existing-key existing)
+        incoming-pane? (pane-key? incoming-key incoming)]
+    (cond
+      (and incoming-pane? (not existing-pane?))
+      incoming-entry
+      (and existing-pane? (not incoming-pane?))
+      existing-entry
+      :else
+      (if (= incoming (pick-newer existing incoming))
+        incoming-entry
+        existing-entry))))
+
+(defn- canonicalize-by-pane [sessions]
+  (reduce-kv
+   (fn [acc key session]
+     (let [pane-id (:pane-id session)
+           canonical (if (seq pane-id) pane-id key)]
+       (if-let [existing (get acc canonical)]
+         (assoc acc canonical
+                (pick-newer existing session))
+         (assoc acc canonical session))))
+   {}
+   sessions))
+
+(defn- session-id-winners [sessions]
+  (reduce-kv
+   (fn [acc key session]
+     (if-let [session-id (:session-id session)]
+       (if-let [existing-entry (get acc session-id)]
+         (assoc acc session-id
+                (pick-session-id-duplicate
+                 existing-entry [key session]))
+         (assoc acc session-id [key session]))
+       acc))
+   {}
+   sessions))
+
+(defn- session-id-keys [sessions winners]
+  (into #{}
+        (map first)
+        (filter (fn [[_key session]]
+                  (contains? winners
+                             (:session-id session)))
+                sessions)))
+
 (defn normalize-sessions
   "Re-keys sessions by :pane-id (canonical key).
    Entries with non-empty :pane-id are keyed by pane-id;
    entries without :pane-id keep their original key.
    When multiple entries share the same pane-id, the one
-   with the latest :last-updated wins.
+   with the latest :last-updated wins. When multiple entries
+   share the same :session-id, they are deduplicated and
+   pane-id keyed entries are preferred.
    Returns empty map when sessions is nil."
   [sessions]
   (if (nil? sessions)
     {}
-    (reduce-kv
-     (fn [acc key session]
-       (let [pane-id (:pane-id session)
-             canonical (if (seq pane-id) pane-id key)]
-         (if-let [existing (get acc canonical)]
-           (assoc acc canonical (pick-newer existing session))
-           (assoc acc canonical session))))
-     {}
-     sessions)))
+    (let [by-pane
+          (canonicalize-by-pane sessions)
+          by-session (session-id-winners by-pane)
+          duplicate-keys (session-id-keys by-pane by-session)]
+      (merge
+       (apply dissoc by-pane duplicate-keys)
+       (into {}
+             (map (fn [[_session-id [key session]]]
+                    [key session]))
+             by-session)))))
 
 (defn- read-state-file
   "Reads and parses the sessions.edn file.

src/ceeker/tmux/pane.clj

@@ -82,6 +82,18 @@
             (process-handle-command-line pid))))
     (catch Exception _ nil)))
 
+(defn- pgrep-child-pids
+  "Returns direct child PIDs via pgrep, or nil on failure."
+  [pid]
+  (try
+    (let [result (shell/sh "pgrep" "-P" (str pid))]
+      (if (zero? (:exit result))
+        (remove str/blank?
+                (str/split-lines
+                 (:out result)))
+        ()))
+    (catch Exception _ nil)))
+
 (defn- child-pids
   "Returns direct child PIDs of the given pid via /proc.
    Falls back to pgrep on non-Linux. Returns empty list
@@ -91,15 +103,12 @@
     (let [f (io/file (str "/proc/" pid "/task/"
                           pid "/children"))]
       (if (.exists f)
-        (remove str/blank?
-                (str/split (str/trim (slurp f)) #"\s+"))
-        (let [result (shell/sh
-                      "pgrep" "-P" (str pid))]
-          (if (zero? (:exit result))
-            (remove str/blank?
-                    (str/split-lines
-                     (:out result)))
-            ()))))
+        (try
+          (remove str/blank?
+                  (str/split (str/trim (slurp f)) #"\s+"))
+          (catch Exception _
+            (pgrep-child-pids pid)))
+        (pgrep-child-pids pid)))
     (catch Exception _ nil)))
 
 (defn- agent-pattern
@@ -121,7 +130,7 @@
         (zero? (:exit (shell/sh "kill" "-0" (str pid))))
         (catch Exception _ false)))))
 
-(declare find-agent-in-tree)
+(declare find-agent-in-tree find-agent-pid-in-tree)
 
 (defn- search-children
   "Searches child processes for an agent, returning the best
@@ -137,6 +146,13 @@
           :not-found
           children))
 
+(defn- search-child-pids
+  "Searches child processes for a matching agent pid."
+  [children agent-type max-depth]
+  (some #(find-agent-pid-in-tree
+          % agent-type max-depth)
+        children))
+
 (defn find-agent-in-tree
   "Searches the process tree rooted at pid for an agent
    process matching the given agent-type.
@@ -164,6 +180,27 @@
               children agent-type
               (dec max-depth)))))))))
 
+(defn find-agent-pid-in-tree
+  "Searches the process tree rooted at pid for an agent
+   process matching the given agent-type and returns the
+   matching pid as a string. Returns nil when not found or
+   process info is unavailable."
+  ([pid agent-type] (find-agent-pid-in-tree
+                     pid agent-type 5))
+  ([pid agent-type max-depth]
+   (when-not (neg? max-depth)
+     (let [pid-str (str pid)
+           pat (agent-pattern agent-type)
+           cmdline (read-proc-cmdline pid-str)]
+       (cond
+         (nil? cmdline) nil
+         (re-find pat cmdline) pid-str
+         :else
+         (when-let [children (child-pids pid-str)]
+           (search-child-pids
+            children agent-type
+            (dec max-depth))))))))
+
 (defn- session-has-live-agent?
   "Checks if a session's agent is alive by searching the
    process tree of matching tmux panes.

src/ceeker/tui/app.clj

@@ -6,6 +6,7 @@
             [ceeker.tui.input :as input]
             [ceeker.tui.view :as view]
             [ceeker.tui.watcher :as watcher]
+            [ceeker.watch.sessions :as session-watch]
             [clojure.core.async :as async]
             [clojure.java.shell :as shell]
             [clojure.string :as str]))
@@ -155,27 +156,37 @@
 
 (declare create-watcher-for)
 
+(defn- start-runtime-workers [state-dir]
+  (session-watch/scan-recent-sessions!
+   {:state-dir state-dir})
+  {:stop-ch (start-pane-checker! state-dir)
+   :session-stop-ch
+   (session-watch/start-session-watcher!
+    {:state-dir state-dir})})
+
 (defn- setup-runtime
   "Creates startup resources and optionally logs timings."
   [state-dir startup-profile?]
   (let [started-at (System/nanoTime)
         terminal-step (input/create-terminal-profile)
         watcher-step (timed-step
                       #(create-watcher-for state-dir))
-        checker-step (timed-step
-                      #(start-pane-checker! state-dir))]
+        workers-step (timed-step
+                      #(start-runtime-workers state-dir))]
     (when startup-profile?
       (log-startup-profile!
        {:create-terminal-build (:build-ms terminal-step)
         :create-terminal-enter-raw-mode
         (:enter-raw-mode-ms terminal-step)
         :create-terminal-total (:total-ms terminal-step)
         :create-watcher (:elapsed-ms watcher-step)
-        :start-pane-checker (:elapsed-ms checker-step)
+        :start-pane-checker (:elapsed-ms workers-step)
         :total (elapsed-ms started-at)}))
     {:terminal (:terminal terminal-step)
      :watcher (:result watcher-step)
-     :stop-ch (:result checker-step)}))
+     :stop-ch (get-in workers-step [:result :stop-ch])
+     :session-stop-ch
+     (get-in workers-step [:result :session-stop-ch])}))
 
 (defn- get-terminal-height
   "Gets the current terminal height from a JLine terminal."
@@ -376,7 +387,7 @@
   ([] (start-tui! nil))
   ([state-dir] (start-tui! state-dir {}))
   ([state-dir opts]
-   (let [{:keys [terminal watcher stop-ch]}
+   (let [{:keys [terminal watcher stop-ch session-stop-ch]}
          (setup-runtime state-dir
                         (:startup-profile opts))
          exit-on-jump? (:exit-on-jump opts)
@@ -386,7 +397,10 @@
        (tui-loop terminal watcher state-dir exit-on-jump?
                  initial-display-mode)
        (finally
-         (async/close! stop-ch)
+         (when stop-ch
+           (async/close! stop-ch))
+         (when session-stop-ch
+           (async/close! session-stop-ch))
          (print "\033[2J\033[H")
          (flush)
          (watcher/close-watcher watcher)