vibe-pomo 0.1.4 → 0.2.1

package/README.md

@@ -80,7 +80,7 @@ pomodoro start 25m Refactor the auth module
 pomodoro start Refactor the auth module    # uses default duration
 ```
 
-A timer window opens in a new terminal. The agent starts working. You're free.
+If Claude Code is running inside `tmux`, vibe-pomo opens a popup over the current pane so the ongoing task stays covered until you end or break the session. Outside `tmux`, it falls back to a separate timer terminal.
 
 ```
 🍅 Pomodoro
@@ -163,7 +163,7 @@ Recent Sessions
 |--------|--------|-------------|
 | `defaultDurationMs` | ms | Default session duration (25 min = `1500000`) |
 | `decisionStrategy` | `"wait"` / `"break"` | When the agent is blocked: wait silently until you end the session (default), or end immediately |
-| `terminalEmulator` | `"auto"` / name | Terminal for the timer window. Auto-detects from `$TERM_PROGRAM`, `$KITTY_WINDOW_ID`, etc. |
+| `terminalEmulator` | `"auto"` / `"tmux"` / `"tmux-window"` / name | Timer surface. `"tmux"` opens a popup overlay, `"tmux-window"` uses a new tmux window, and `"auto"` prefers the popup when `$TMUX` is set. |
 | `soundOnOvertime` | bool | Play a sound when the timer hits zero |
 
 ---

package/README.zh.md

@@ -120,7 +120,7 @@ pomodoro start 25m Refactor the auth module
 pomodoro start Refactor the auth module    # 使用默认时长
 ```
 
-计时器窗口打开，代理开始工作，你自由了。
+如果 Claude Code 跑在 `tmux` 里，vibe-pomo 会在当前 pane 上弹出一个覆盖式 popup，把正在进行的任务界面盖住，直到你结束或中断番茄钟。非 `tmux` 环境下则回退到单独的计时器终端窗口。
 
 ### 3. 会话进行中
 
@@ -177,7 +177,7 @@ Recent Sessions
 |------|------|------|
 | `defaultDurationMs` | 毫秒数 | 默认会话时长（25 分钟 = `1500000`） |
 | `decisionStrategy` | `"wait"` / `"break"` | 代理被阻塞时的策略：静默等待直到你结束会话（默认），或立即结束 |
-| `terminalEmulator` | `"auto"` / 名称 | 计时器窗口使用的终端。从 `$TERM_PROGRAM`、`$KITTY_WINDOW_ID` 等自动检测 |
+| `terminalEmulator` | `"auto"` / `"tmux"` / `"tmux-window"` / 名称 | 计时器展示方式。`"tmux"` 打开覆盖式 popup，`"tmux-window"` 使用新的 tmux window，`"auto"` 在检测到 `$TMUX` 时优先使用 popup |
 | `soundOnOvertime` | 布尔值 | 计时归零时播放提示音 |
 
 ---

package/bin/pomodoro.mjs

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { spawn } from 'node:child_process'
+import { execFileSync } from 'node:child_process'
 import { fileURLToPath } from 'node:url'
 import { dirname, join } from 'node:path'
 import { readLock, removeLock } from '../src/shared/lockfile.mjs'
@@ -110,11 +111,17 @@ async function cmdStart(args) {
 
   // Launch timer TUI in a new terminal window
   const timerEntry = join(ROOT, 'src', 'tui', 'timer', 'index.tsx')
-  const launched = await launchTerminal(TSX, timerEntry, resp.sessionId, config.terminalEmulator)
+  const launched = await launchTerminal({
+    tsx: TSX,
+    entryFile: timerEntry,
+    sessionId: resp.sessionId,
+    termPref: config.terminalEmulator,
+  })
 
   if (!launched) {
-    console.log(`\nOpen the timer in a new terminal:`)
-    console.log(`  tsx ${timerEntry} ${resp.sessionId}`)
+    console.log(`POMODORO_TIMER_NOT_LAUNCHED`)
+    console.log(`  To watch the timer: node ${TSX} ${timerEntry} ${resp.sessionId}`)
+    console.log(`  To end the session: node ${join(ROOT, 'bin', 'pomodoro.mjs')} stop`)
   }
 }
 
@@ -179,7 +186,7 @@ async function cmdStopDaemon() {
 
 // ── Terminal launch helpers ───────────────────────────────────────────────────
 
-async function launchTerminal(tsx, entryFile, sessionId, termPref) {
+async function launchTerminal({ tsx, entryFile, sessionId, termPref }) {
   const terminals = termPref && termPref !== 'auto'
     ? [termPref]
     : detectTerminals()
@@ -197,9 +204,12 @@ function detectTerminals() {
     list.push('wt', 'cmd')
     return list
   }
-  if (process.env.KITTY_WINDOW_ID)        list.push('kitty')
+  // Prefer a modal overlay when Claude Code is running inside tmux.
+  if (process.env.TMUX)                       list.push('tmux-popup')
+  if (process.env.STY)                        list.push('screen')
+  if (process.env.KITTY_WINDOW_ID)            list.push('kitty')
   if (process.env.TERM_PROGRAM === 'WezTerm') list.push('wezterm')
-  list.push('gnome-terminal', 'xfce4-terminal', 'konsole', 'xterm', 'alacritty', 'wezterm', 'kitty')
+  list.push('tmux-window', 'gnome-terminal', 'xfce4-terminal', 'konsole', 'xterm', 'alacritty', 'wezterm', 'kitty')
   return list
 }
 
@@ -212,6 +222,10 @@ function buildCmd(term, tsx, entryFile, sessionId) {
   switch (term) {
     case 'wt':             return ['wt', 'new-tab', '--', 'cmd.exe', '/k', inner]
     case 'cmd':            return ['cmd.exe', '/c', `start cmd.exe /k "${inner}"`]
+    case 'tmux':
+    case 'tmux-popup':     return buildTmuxPopupCmd(tsx, entryFile, sessionId)
+    case 'tmux-window':    return ['tmux', 'new-window', inner]
+    case 'screen':         return ['screen', '-X', 'screen', 'bash', '-c', inner]
     case 'gnome-terminal': return ['gnome-terminal', '--', 'bash', '-c', inner]
     case 'xfce4-terminal': return ['xfce4-terminal', '-e', inner]
     case 'konsole':        return ['konsole', '-e', inner]
@@ -244,8 +258,7 @@ function isInsideClaudeCode() {
 
 function spawnWatcher(sessionId) {
   const watcherPath = join(ROOT, 'src', 'watcher.mjs')
-  // Watch the grandparent process (Claude Code's Node.js process)
-  const watchPid = process.ppid
+  const watchPid = getWatchPid()
   const child = spawn(process.execPath, [watcherPath, String(watchPid), sessionId], {
     detached: true,
     stdio: 'ignore',
@@ -253,6 +266,45 @@ function spawnWatcher(sessionId) {
   child.unref()
 }
 
+function buildTmuxPopupCmd(tsx, entryFile, sessionId) {
+  const timerCmd = [
+    'POMODORO_MODAL=1',
+    shellQuote(process.execPath),
+    shellQuote(tsx),
+    shellQuote(entryFile),
+    shellQuote(sessionId),
+  ].join(' ')
+
+  return [
+    'tmux',
+    'display-popup',
+    '-E',
+    '-w', '90%',
+    '-h', '90%',
+    '-T', 'Pomodoro',
+    `bash -lc ${shellQuote(timerCmd)}`,
+  ]
+}
+
+function shellQuote(value) {
+  return `'${String(value).replace(/'/g, `'\\''`)}'`
+}
+
+function getWatchPid() {
+  if (isWin) return process.ppid
+
+  try {
+    const out = execFileSync('ps', ['-o', 'ppid=', '-p', String(process.ppid)], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim()
+    const ppid = Number.parseInt(out, 10)
+    if (Number.isInteger(ppid) && ppid > 1) return ppid
+  } catch {}
+
+  return process.ppid
+}
+
 function formatMs(ms) {
   const m = Math.floor(ms / 60000)
   const s = Math.floor((ms % 60000) / 1000)

package/install.mjs

@@ -109,10 +109,28 @@ argument-hint: "[duration e.g. 25m] [task description]"
 node ${pomodoroPath} start $ARGUMENTS
 \`\`\`
 
-## Step 2: Work autonomously during the focus session
+## Step 2: Check if timer window launched
+
+Read the output from Step 1 carefully.
+
+If the output contains **\`POMODORO_TIMER_NOT_LAUNCHED\`**, the system could not open a separate timer window (common in SSH, VSCode, or headless environments). In this case you MUST tell the user BEFORE doing any work:
+
+> ⚠️ **No timer window could be opened automatically.**
+>
+> Run one of these in another terminal to control your Pomodoro:
+> - **Watch timer:** (the command shown on the "To watch" line above)
+> - **End session:** (the command shown on the "To end" line above)
+>
+> I'll now work on your task. The session will stay active until you run the stop command.
+
+After telling the user that once, continue immediately. Do not wait for a reply.
+
+## Step 3: Work autonomously during the focus session
 
 The user has started a Pomodoro focus session and **will not be checking the screen** until the timer ends. Do not interrupt them.
 
+**Current project**: Check \`\$CLAUDE_PROJECT_DIR\` or run \`pwd\` — work only on files in that directory. Do not reference or modify any other project.
+
 **Task**: $ARGUMENTS
 
 - Focus only on what is **unambiguously clear** from the task description

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibe-pomo",
-  "version": "0.1.4",
+  "version": "0.2.1",
   "description": "You and your agent, both in flow. A Pomodoro timer for Claude Code that keeps agents working autonomously while you stay deep in focus — uninterrupted.",
   "type": "module",
   "bin": {
@@ -33,14 +33,12 @@
     "tui": "tsx src/tui/index.tsx"
   },
   "dependencies": {
-    "better-sqlite3": "^9.4.3",
     "ink": "^5.1.0",
     "ink-text-input": "^6.0.0",
     "react": "^18.3.1",
     "tsx": "^4.19.2"
   },
   "devDependencies": {
-    "@types/better-sqlite3": "^7.6.8",
     "@types/react": "^18.3.1"
   },
   "engines": {

package/src/daemon/db.mjs

@@ -1,146 +1,130 @@
-import Database from 'better-sqlite3'
 import { homedir } from 'node:os'
 import { join } from 'node:path'
-import { mkdirSync } from 'node:fs'
+import { mkdirSync, readFileSync, writeFileSync, existsSync } from 'node:fs'
 
-const DB_PATH = join(homedir(), '.claude', 'pomodoro.db')
+const DATA_PATH = join(homedir(), '.claude', 'pomodoro-data.json')
 
-function openDb() {
+// ── In-memory store (loaded once, flushed on every write) ─────────────────────
+
+let _data = null
+
+function load() {
+  if (_data) return _data
   mkdirSync(join(homedir(), '.claude'), { recursive: true })
-  const db = new Database(DB_PATH)
-  db.pragma('journal_mode = WAL')
-
-  db.exec(`
-    CREATE TABLE IF NOT EXISTS sessions (
-      id             INTEGER PRIMARY KEY AUTOINCREMENT,
-      project_hash   TEXT NOT NULL,
-      project_path   TEXT NOT NULL,
-      started_at     INTEGER NOT NULL,
-      ended_at       INTEGER,
-      planned_ms     INTEGER NOT NULL,
-      actual_ms      INTEGER,
-      cycles         INTEGER DEFAULT 1,
-      status         TEXT NOT NULL,
-      task           TEXT,
-      agent_summary  TEXT,   -- from .claude/pomodoro-summary.md
-      user_activity  TEXT    -- what the user did during this session (entered at session end)
-    );
-
-    -- Migrate existing tables: add new columns if they don't exist yet
-    -- (SQLite doesn't support IF NOT EXISTS for columns, so we use a safe approach)
-
-
-    CREATE TABLE IF NOT EXISTS notifications (
-      id                INTEGER PRIMARY KEY AUTOINCREMENT,
-      session_id        INTEGER REFERENCES sessions(id),
-      received_at       INTEGER NOT NULL,
-      released_at       INTEGER,
-      notification_json TEXT NOT NULL
-    );
-
-    CREATE VIEW IF NOT EXISTS project_stats AS
-    SELECT
-      project_path,
-      COUNT(*)               AS total_sessions,
-      SUM(cycles)            AS total_cycles,
-      SUM(actual_ms) / 60000 AS total_minutes,
-      MAX(started_at)        AS last_active
-    FROM sessions
-    WHERE status != 'broken'
-    GROUP BY project_path;
-  `)
-
-  // Safe column migrations for existing databases
-  const cols = db.prepare(`PRAGMA table_info(sessions)`).all().map((c) => c.name)
-  if (!cols.includes('agent_summary')) {
-    db.exec(`ALTER TABLE sessions ADD COLUMN agent_summary TEXT`)
+  if (existsSync(DATA_PATH)) {
+    try { _data = JSON.parse(readFileSync(DATA_PATH, 'utf8')) } catch {}
   }
-  if (!cols.includes('user_activity')) {
-    db.exec(`ALTER TABLE sessions ADD COLUMN user_activity TEXT`)
+  if (!_data) _data = { sessions: [], notifications: [], nextId: 1 }
+  // Backfill nextId in case file was created without it
+  if (!_data.nextId) {
+    const maxId = Math.max(0, ...(_data.sessions ?? []).map((s) => s.id ?? 0))
+    _data.nextId = maxId + 1
   }
-
-  return db
+  return _data
 }
 
-let _db = null
-function getDb() {
-  if (!_db) _db = openDb()
-  return _db
+function flush() {
+  writeFileSync(DATA_PATH, JSON.stringify(_data, null, 2), 'utf8')
 }
 
+// ── Public API (mirrors the old better-sqlite3 interface exactly) ─────────────
+
 export function startSession({ projectHash, projectPath, plannedMs, task }) {
-  const db = getDb()
-  const result = db.prepare(`
-    INSERT INTO sessions (project_hash, project_path, started_at, planned_ms, task, status)
-    VALUES (?, ?, ?, ?, ?, 'running')
-  `).run(projectHash, projectPath, Date.now(), plannedMs, task ?? null)
-  return result.lastInsertRowid
+  const data = load()
+  const id = data.nextId++
+  data.sessions.push({
+    id,
+    project_hash:   projectHash,
+    project_path:   projectPath,
+    started_at:     Date.now(),
+    ended_at:       null,
+    planned_ms:     plannedMs,
+    actual_ms:      null,
+    cycles:         1,
+    status:         'running',
+    task:           task ?? null,
+    agent_summary:  null,
+    user_activity:  null,
+  })
+  flush()
+  return id
 }
 
-export function endSession(sessionId, { actualMs, status, agentSummary }) {
-  const db = getDb()
-  db.prepare(`
-    UPDATE sessions
-    SET ended_at = ?, actual_ms = ?, status = ?, agent_summary = ?
-    WHERE id = ?
-  `).run(Date.now(), actualMs, status, agentSummary ?? null, sessionId)
+export function endSession(id, { actualMs, status, agentSummary }) {
+  const data = load()
+  const s = data.sessions.find((s) => s.id === id)
+  if (!s) return
+  s.ended_at     = Date.now()
+  s.actual_ms    = actualMs
+  s.status       = status
+  s.agent_summary = agentSummary ?? null
+  flush()
 }
 
-export function updateSessionActivity(sessionId, { userActivity }) {
-  const db = getDb()
-  db.prepare(`UPDATE sessions SET user_activity = ? WHERE id = ?`)
-    .run(userActivity ?? null, sessionId)
+export function updateSessionActivity(id, { userActivity }) {
+  const data = load()
+  const s = data.sessions.find((s) => s.id === id)
+  if (!s) return
+  s.user_activity = userActivity ?? null
+  flush()
 }
 
 export function saveNotification(sessionId, { notificationJson, receivedAt, releasedAt }) {
-  const db = getDb()
-  db.prepare(`
-    INSERT INTO notifications (session_id, received_at, released_at, notification_json)
-    VALUES (?, ?, ?, ?)
-  `).run(sessionId, receivedAt, releasedAt ?? null, notificationJson)
+  const data = load()
+  data.notifications.push({
+    id:                data.nextId++,
+    session_id:        sessionId,
+    received_at:       receivedAt,
+    released_at:       releasedAt ?? null,
+    notification_json: notificationJson,
+  })
+  flush()
+}
+
+// ── Aggregation helpers ───────────────────────────────────────────────────────
+
+function projectStats() {
+  const data = load()
+  const map = new Map()
+  for (const s of data.sessions) {
+    if (s.status === 'broken') continue
+    const key = s.project_path
+    if (!map.has(key)) map.set(key, { project_path: key, total_sessions: 0, total_cycles: 0, total_minutes: 0, last_active: 0 })
+    const row = map.get(key)
+    row.total_sessions++
+    row.total_cycles  += s.cycles ?? 1
+    row.total_minutes += Math.floor((s.actual_ms ?? 0) / 60000)
+    if (s.started_at > row.last_active) row.last_active = s.started_at
+  }
+  return [...map.values()].sort((a, b) => b.last_active - a.last_active)
 }
 
 /** Return stats for Dashboard TUI */
 export function getStats() {
-  const db = getDb()
-  const projects = db.prepare(`
-    SELECT project_path, total_sessions, total_cycles, total_minutes, last_active
-    FROM project_stats ORDER BY last_active DESC LIMIT 10
-  `).all()
-
-  const recent = db.prepare(`
-    SELECT project_path, task, actual_ms, status, started_at, agent_summary, user_activity
-    FROM sessions ORDER BY started_at DESC LIMIT 8
-  `).all()
-
+  const data = load()
+  const projects = projectStats().slice(0, 10)
+  const recent = [...data.sessions]
+    .sort((a, b) => b.started_at - a.started_at)
+    .slice(0, 8)
+    .map(({ project_path, task, actual_ms, status, started_at, agent_summary, user_activity }) =>
+      ({ project_path, task, actual_ms, status, started_at, agent_summary, user_activity }))
   return { projects, recent }
 }
 
 /** Return all sessions for a project, for detailed review */
 export function getProjectSessions(projectPath) {
-  const db = getDb()
-  return db.prepare(`
-    SELECT id, task, started_at, ended_at, actual_ms, status, agent_summary, user_activity
-    FROM sessions
-    WHERE project_path = ?
-    ORDER BY started_at DESC
-  `).all(projectPath)
+  const data = load()
+  return data.sessions
+    .filter((s) => s.project_path === projectPath)
+    .sort((a, b) => b.started_at - a.started_at)
+    .map(({ id, task, started_at, ended_at, actual_ms, status, agent_summary, user_activity }) =>
+      ({ id, task, started_at, ended_at, actual_ms, status, agent_summary, user_activity }))
 }
 
 /** Print stats to stdout as a formatted table */
 export function printStats() {
-  const db = getDb()
-
-  const projects = db.prepare(`
-    SELECT
-      project_path,
-      total_sessions,
-      total_cycles,
-      total_minutes,
-      last_active
-    FROM project_stats
-    ORDER BY last_active DESC
-  `).all()
+  const data = load()
+  const projects = projectStats()
 
   if (projects.length === 0) {
     console.log('No completed sessions yet.')
@@ -165,18 +149,14 @@ export function printStats() {
       truncated.padEnd(36) +
       String(row.total_sessions).padStart(9) +
       String(row.total_cycles).padStart(8) +
-      String(row.total_minutes ?? 0).padStart(9) +
+      String(row.total_minutes).padStart(9) +
       `  ${date}`
     )
   }
 
-  // Recent sessions
-  const recent = db.prepare(`
-    SELECT project_path, task, actual_ms, cycles, status, started_at
-    FROM sessions
-    ORDER BY started_at DESC
-    LIMIT 10
-  `).all()
+  const recent = [...data.sessions]
+    .sort((a, b) => b.started_at - a.started_at)
+    .slice(0, 10)
 
   console.log('\nRecent Sessions\n' + '─'.repeat(72))
   console.log(
@@ -191,17 +171,15 @@ export function printStats() {
   for (const s of recent) {
     const taskLabel = (s.task ?? '(no task)').slice(0, 37).padEnd(38)
     const mins = s.actual_ms ? String(Math.round(s.actual_ms / 60000)).padStart(5) : '   —'
-    const cyc = String(s.cycles).padStart(5)
+    const cyc = String(s.cycles ?? 1).padStart(5)
     const status = s.status.padEnd(12)
     const date = new Date(s.started_at).toLocaleDateString()
     console.log(`${taskLabel}${mins}${cyc}  ${status}  ${date}`)
     if (s.agent_summary) {
-      const line = s.agent_summary.split('\n')[0].slice(0, 68)
-      console.log(`  🤖 ${line}`)
+      console.log(`  🤖 ${s.agent_summary.split('\n')[0].slice(0, 68)}`)
     }
     if (s.user_activity) {
-      const line = s.user_activity.slice(0, 68)
-      console.log(`  👤 ${line}`)
+      console.log(`  👤 ${s.user_activity.slice(0, 68)}`)
     }
   }
 

package/src/daemon/index.mjs

@@ -21,6 +21,8 @@ const sessions = new Map()
 
 /** sessionId → DB row id */
 const dbIds = new Map()
+/** sessionId → DB row id for sessions that already ended but may still receive user activity */
+const finishedDbIds = new Map()
 
 // ── IPC Handlers ─────────────────────────────────────────────────────────────
 
@@ -78,9 +80,10 @@ ipc.on(MSG.SESSION_BREAK, (msg) => {
 })
 
 ipc.on(MSG.SESSION_UPDATE_ACTIVITY, (msg) => {
-  const dbId = dbIds.get(msg.sessionId)
+  const dbId = dbIds.get(msg.sessionId) ?? finishedDbIds.get(msg.sessionId)
   if (!dbId) return { error: 'session not found' }
   updateSessionActivity(dbId, { userActivity: msg.userActivity })
+  finishedDbIds.delete(msg.sessionId)
   return { ok: true }
 })
 
@@ -163,6 +166,10 @@ function wireSessionEvents(session) {
     }
 
     sessions.delete(sessionId)
+    if (dbId) {
+      finishedDbIds.set(sessionId, dbId)
+      setTimeout(() => finishedDbIds.delete(sessionId), 30 * 60 * 1000).unref()
+    }
     dbIds.delete(sessionId)
 
     ipc.broadcast({ type: EVT.SESSION_ENDED, sessionId, status, actualMs })

package/src/daemon/ipc.mjs

@@ -62,7 +62,7 @@ export class IpcServer {
           const handler = this.#handlers['query']
           if (handler) {
             const state = await handler(msg, socket)
-            if (state) socket.write(encode({ type: EVT.STATE, ...state }))
+            if (state) socket.write(encode({ type: EVT.SNAPSHOT, ...state }))
           }
           continue
         }

package/src/daemon/session.mjs

@@ -58,6 +58,7 @@ export class Session extends EventEmitter {
     return {
       sessionId: this.id,
       projectDir: this.projectDir,
+      projectHash: this.projectHash,
       task: this.task,
       plannedMs: this.plannedMs,
       state: this.#state,

package/src/hooks/notification.mjs

@@ -1,9 +1,10 @@
 /**
  * Notification hook — queue notifications during an active Pomodoro session.
  */
-import { readLock, projectHash } from '../shared/lockfile.mjs'
+import { readLock } from '../shared/lockfile.mjs'
 import { sendAndReceive } from '../shared/ipcClient.mjs'
-import { STATE, MSG } from '../shared/protocol.mjs'
+import { MSG } from '../shared/protocol.mjs'
+import { findActiveSession } from '../shared/findActiveSession.mjs'
 
 async function readStdin() {
   return new Promise((resolve) => {
@@ -20,8 +21,6 @@ async function main() {
   if (!lock) process.exit(0)
 
   const projectDir = process.env.CLAUDE_PROJECT_DIR ?? process.cwd()
-  const hash = projectHash(projectDir)
-
   let state
   try {
     state = await sendAndReceive({ type: MSG.QUERY })
@@ -29,10 +28,7 @@ async function main() {
     process.exit(0)
   }
 
-  const active = state.sessions?.find(
-    (s) => s.projectHash === hash &&
-           (s.state === STATE.RUNNING || s.state === STATE.OVERTIME)
-  )
+  const active = findActiveSession(state.sessions, projectDir)
   if (!active) process.exit(0)
 
   const raw = await readStdin()

package/src/hooks/preToolUse.mjs

@@ -2,9 +2,10 @@
  * PreToolUse hook — auto-approve tool calls during an active Pomodoro session.
  * Transparency: if no daemon running or no active session for this project, exits 0.
  */
-import { readLock, projectHash } from '../shared/lockfile.mjs'
+import { readLock } from '../shared/lockfile.mjs'
 import { sendAndReceive } from '../shared/ipcClient.mjs'
-import { STATE, MSG } from '../shared/protocol.mjs'
+import { MSG } from '../shared/protocol.mjs'
+import { findActiveSession } from '../shared/findActiveSession.mjs'
 
 async function main() {
   const lock = readLock()
@@ -19,12 +20,7 @@ async function main() {
     process.exit(0)
   }
 
-  // Find an active session for this project
-  const hash = projectHash(projectDir)
-  const active = state.sessions?.find(
-    (s) => s.projectHash === hash &&
-           (s.state === STATE.RUNNING || s.state === STATE.OVERTIME)
-  )
+  const active = findActiveSession(state.sessions, projectDir)
 
   if (active) {
     process.stdout.write(JSON.stringify({

package/src/hooks/stop.mjs

@@ -2,9 +2,10 @@
  * Stop hook — called when Claude Code agent finishes.
  * Blocks the agent if a Pomodoro is active for this project.
  */
-import { readLock, projectHash } from '../shared/lockfile.mjs'
+import { readLock } from '../shared/lockfile.mjs'
 import { sendAndReceive } from '../shared/ipcClient.mjs'
-import { STATE, MSG } from '../shared/protocol.mjs'
+import { MSG } from '../shared/protocol.mjs'
+import { findActiveSession } from '../shared/findActiveSession.mjs'
 
 async function readStdin() {
   return new Promise((resolve) => {
@@ -21,8 +22,6 @@ async function main() {
   if (!lock) process.exit(0)
 
   const projectDir = process.env.CLAUDE_PROJECT_DIR ?? process.cwd()
-  const hash = projectHash(projectDir)
-
   let state
   try {
     state = await sendAndReceive({ type: MSG.QUERY })
@@ -30,10 +29,7 @@ async function main() {
     process.exit(0)
   }
 
-  const active = state.sessions?.find(
-    (s) => s.projectHash === hash &&
-           (s.state === STATE.RUNNING || s.state === STATE.OVERTIME)
-  )
+  const active = findActiveSession(state.sessions, projectDir)
   if (!active) process.exit(0)
 
   const raw = await readStdin()
@@ -60,6 +56,7 @@ async function main() {
         `Time remaining: ${resp.remainingFormatted}.`,
         'The user is not available. Do not send messages or notifications.',
         'Record any pending decisions in `.claude/pomodoro-pending.md` and wait quietly.',
+        'If the user asks how to end the session, tell them to run: pomodoro stop',
       ].join(' '),
     }) + '\n')
   }

package/src/shared/findActiveSession.mjs

@@ -0,0 +1,27 @@
+import { resolve } from 'node:path'
+import { projectHash } from './lockfile.mjs'
+import { STATE } from './protocol.mjs'
+
+function normalizeProjectDir(projectDir) {
+  return resolve(projectDir ?? process.cwd())
+}
+
+function isActiveSession(session) {
+  return session?.state === STATE.RUNNING || session?.state === STATE.OVERTIME
+}
+
+/**
+ * Match the current Claude project to the daemon's active session.
+ * Prefer the stable hash, but fall back to normalized projectDir for
+ * compatibility with older snapshots that did not include projectHash.
+ */
+export function findActiveSession(sessions, projectDir) {
+  const normalizedDir = normalizeProjectDir(projectDir)
+  const hash = projectHash(normalizedDir)
+
+  return sessions?.find((session) => {
+    if (!isActiveSession(session)) return false
+    if (session.projectHash === hash) return true
+    return normalizeProjectDir(session.projectDir) === normalizedDir
+  }) ?? null
+}

package/src/tui/timer/TimerApp.tsx

@@ -34,6 +34,7 @@ export function TimerApp({
 }: TimerAppProps) {
   const { stdout } = useStdout()
   const width = stdout?.columns ?? 60
+  const isModal = process.env.POMODORO_MODAL === '1'
 
   const [timerState, setTimerState] = useState(initialState)
   const [remaining, setRemaining] = useState(initialRemaining)
@@ -97,13 +98,13 @@ export function TimerApp({
   useInput((input, key) => {
     if (phase === 'activity-input') return // TextInput handles keys in this phase
     if (phase === 'done') {
-      if (input === 'q' || key.escape) process.exit(0)
+      if (!isModal && (input === 'q' || key.escape)) process.exit(0)
       return
     }
     if (timerState === STATE.ENDED) return
     if (input === 'e' || input === 'E') sendEnd()
     if (input === 'b' || input === 'B') sendBreak()
-    if (input === 'q' || key.escape) process.exit(0)
+    if (!isModal && (input === 'q' || key.escape)) process.exit(0)
   })
 
   const isOvertime = timerState === STATE.OVERTIME
@@ -141,10 +142,10 @@ export function TimerApp({
 
   // ── Timer phase ───────────────────────────────────────────────────────────
   const keybindings = isEnded
-    ? '[Q] Quit'
+    ? (isModal ? 'Submit your notes to close the Pomodoro overlay' : '[Q] Quit')
     : isOvertime
-      ? '[E] End Session    [B] Break    [Q] Quit'
-      : '[B] Break    [Q] Quit'
+      ? (isModal ? '[E] End Session    [B] Break' : '[E] End Session    [B] Break    [Q] Quit')
+      : (isModal ? '[B] Break' : '[B] Break    [Q] Quit')
 
   return (
     <Box flexDirection="column" width={width} paddingX={2} paddingY={1}>
@@ -159,6 +160,12 @@ export function TimerApp({
       <Box marginTop={1}>
         <Text color="gray" dimColor>{keybindings}</Text>
       </Box>
+
+      {isModal && (
+        <Box marginTop={1}>
+          <Text color="gray" dimColor>The current Claude Code pane will stay covered until you end or break this Pomodoro.</Text>
+        </Box>
+      )}
     </Box>
   )
 }