teleportation-cli 1.4.0 → 1.4.1

package/.claude/hooks/pre_tool_use.mjs

@@ -19,7 +19,7 @@ const readStdin = () => new Promise((resolve, reject) => {
 
 // Lazy-load metadata extraction (only used on slow path)
 let extractSessionMetadata = null;
-async function getSessionMetadata(cwd) {
+async function getSessionMetadata(cwd, hookInput = null) {
   if (!extractSessionMetadata) {
     const possiblePaths = [
       join(__dirname, '..', '..', 'lib', 'session', 'metadata.js'),
@@ -40,12 +40,41 @@ async function getSessionMetadata(cwd) {
   if (!extractSessionMetadata) return {};
 
   try {
-    return await extractSessionMetadata(cwd);
+    return await extractSessionMetadata(cwd, hookInput);
   } catch (e) {
     return {};
   }
 }
 
+// Lazy-load event data sanitizer (redact API keys, tokens, passwords from timeline events)
+let _sanitizeEventData = null;
+async function loadEventSanitizer() {
+  if (_sanitizeEventData) return _sanitizeEventData;
+
+  const possiblePaths = [
+    join(__dirname, '..', '..', 'lib', 'utils', 'log-sanitizer.js'),
+    join(homedir(), '.teleportation', 'lib', 'utils', 'log-sanitizer.js'),
+  ];
+
+  for (const path of possiblePaths) {
+    try {
+      const mod = await import(path);
+      if (mod.sanitizeEventData) {
+        _sanitizeEventData = mod.sanitizeEventData;
+        return _sanitizeEventData;
+      }
+    } catch {
+      continue;
+    }
+  }
+
+  // Fallback: identity function (don't block tool execution if sanitizer unavailable)
+  // Server-side sanitization in relay provides defense-in-depth
+  log('Warning: sanitizeEventData not found, using identity fallback (relay-side sanitization still active)');
+  _sanitizeEventData = (data) => data;
+  return _sanitizeEventData;
+}
+
 const fetchJson = async (url, opts) => {
   const res = await fetch(url, opts);
   if (!res.ok) throw new Error(`HTTP ${res.status}`);
@@ -105,6 +134,8 @@ function postTimeline(relayUrl, apiKey, body) {
   }
 
   let { session_id, tool_name, tool_input } = input || {};
+  // Cursor sends conversation_id in preToolUse instead of session_id
+  session_id = session_id || input?.conversation_id;
   tool_input = tool_input && typeof tool_input === 'object' ? tool_input : {};
   let claude_session_id = session_id; // Keep original ID
   const hookStartMs = Date.now();
@@ -116,7 +147,9 @@ function postTimeline(relayUrl, apiKey, body) {
     return Math.max(200, Math.min(PRE_TOOL_NETWORK_TIMEOUT_MS, remaining - 100));
   };
 
-  const source = 'cli_interactive';
+  // Detect client: Cursor injects cursor_version in all hook inputs
+  const client = input?.cursor_version ? 'cursor' : 'claude-code';
+  const source = client === 'cursor' ? 'cursor_agent' : 'cli_interactive';
 
   // 1. Recursion Guard
   const SAFE_TOOLS = ['read', 'glob', 'grep', 'websearch', 'bashoutput', 'ls', 'pwd', 'git status'];
@@ -330,12 +363,13 @@ function postTimeline(relayUrl, apiKey, body) {
       log(`[FastPath] Model check error: ${e.message}`);
     }
 
-    // Log tool_use to timeline
+    // Log tool_use to timeline (sanitize to redact secrets from tool_input)
     if (session_id && RELAY_API_URL && RELAY_API_KEY && tool_name) {
       try {
+        const sanitize = await loadEventSanitizer();
         await postTimeline(RELAY_API_URL, RELAY_API_KEY, {
           session_id, type: 'tool_use', source,
-          data: { tool_name, tool_input: tool_input || {}, timestamp: Date.now() }
+          data: sanitize({ tool_name, tool_input: tool_input || {}, timestamp: Date.now() })
         });
       } catch (e) { log(`Failed to log tool_use: ${e.message}`); }
     }
@@ -350,8 +384,10 @@ function postTimeline(relayUrl, apiKey, body) {
   // ═══════════════════════════════════════════════════════════════════════
   log(`[SlowPath] First tool call, registering session ${session_id}`);
 
-  const cwd = process.cwd();
-  const meta = await getSessionMetadata(cwd);
+  // Cursor provides workspace_roots; Claude Code provides cwd.
+  // Fall back to process.cwd() when hook payload doesn't include either.
+  const cwd = input?.cwd || (input?.workspace_roots?.[0]) || process.cwd();
+  const meta = await getSessionMetadata(cwd, input);
   log(`Session metadata: project=${meta.project_name}, hostname=${meta.hostname}, branch=${meta.current_branch}, model=${meta.current_model || 'default'}`);
 
   // Model change detection (full version via metadata)
@@ -422,7 +458,7 @@ function postTimeline(relayUrl, apiKey, body) {
       const res = await fetch(`${daemonUrl}/sessions/register`, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ session_id, claude_session_id, cwd, meta })
+        body: JSON.stringify({ session_id, claude_session_id, cwd, meta: { ...meta, client } })
       }).catch(e => {
         log(`Daemon registration fetch error: ${e.message}`);
         return null;
@@ -437,12 +473,13 @@ function postTimeline(relayUrl, apiKey, body) {
     }
   }
 
-  // Log tool_use event to timeline
+  // Log tool_use event to timeline (sanitize to redact secrets from tool_input)
   if (session_id && RELAY_API_URL && RELAY_API_KEY && tool_name) {
     try {
+      const sanitize = await loadEventSanitizer();
       await postTimeline(RELAY_API_URL, RELAY_API_KEY, {
         session_id, type: 'tool_use', source,
-        data: { tool_name, tool_input: tool_input || {}, timestamp: Date.now() }
+        data: sanitize({ tool_name, tool_input: tool_input || {}, timestamp: Date.now() })
       });
       log(`Logged tool_use event for ${tool_name}`);
     } catch (e) {

package/.claude/hooks/session-register.mjs

@@ -69,13 +69,17 @@ export async function ensureSessionRegistered(session_id, cwd, config, preExtrac
   // Use pre-extracted metadata if provided (avoids duplicate git subprocess calls)
   let metadata;
   if (preExtractedMetadata && Object.keys(preExtractedMetadata).length > 0) {
-    metadata = { ...preExtractedMetadata, session_id, claude_session_id: session_id };
+    const client = preExtractedMetadata.client || 'claude-code';
+    const clientSessionField = client === 'cursor'
+      ? { cursor_conversation_id: session_id }
+      : { claude_session_id: session_id };
+    metadata = { ...preExtractedMetadata, session_id, ...clientSessionField };
     if (env.DEBUG) {
       console.error('[SessionRegister] Using pre-extracted metadata (skipping re-extraction)');
     }
   } else {
     // Fallback: extract metadata (for callers that don't provide it)
-    metadata = { cwd, claude_session_id: session_id };
+    metadata = { cwd, claude_session_id: session_id, client: 'claude-code' };
     try {
       const possiblePaths = [
         join(__dirname, '..', '..', 'lib', 'session', 'metadata.js'),
@@ -96,8 +100,11 @@ export async function ensureSessionRegistered(session_id, cwd, config, preExtrac
       if (metadataModule && metadataModule.extractSessionMetadata && cwd) {
         const extracted = await metadataModule.extractSessionMetadata(cwd);
         extracted.session_id = session_id;
-        extracted.claude_session_id = session_id;
-        metadata = extracted;
+        extracted.client = extracted.client || 'claude-code';
+        const clientSessionField = extracted.client === 'cursor'
+          ? { cursor_conversation_id: session_id }
+          : { claude_session_id: session_id };
+        metadata = { ...extracted, ...clientSessionField };
       }
     } catch (e) {
       if (env.DEBUG) {
@@ -157,7 +164,7 @@ export async function ensureSessionRegistered(session_id, cwd, config, preExtrac
         'Content-Type': 'application/json',
         'Authorization': `Bearer ${RELAY_API_KEY}`
       },
-      body: JSON.stringify({ session_id, meta: metadata })
+      body: JSON.stringify({ session_id, meta: metadata, cwd: metadata.working_directory || cwd })
     });
 
     if (response.ok || response.status === 200) {

package/.claude/hooks/session_end.mjs

@@ -90,6 +90,34 @@ const readStdin = () => new Promise((resolve, reject) => {
       }
     }
 
+    // Mark PID-based session file as ended so daemon stops heartbeating immediately
+    try {
+      const { homedir } = await import('node:os');
+      const { fileURLToPath } = await import('node:url');
+      const { dirname } = await import('node:path');
+      const __hookDir = dirname(fileURLToPath(import.meta.url));
+      const registryPaths = [
+        join(homedir(), '.teleportation', 'lib', 'daemon', 'session-file-registry.js'),
+        // Relative path — consistent with session_start.mjs (__dirname-based, not URL-based)
+        join(__hookDir, '..', '..', 'lib', 'daemon', 'session-file-registry.js'),
+      ];
+      let marked = false;
+      for (const p of registryPaths) {
+        try {
+          const { markSessionEnded } = await import(p);
+          await markSessionEnded(session_id);
+          if (env.DEBUG) console.error(`[SessionEnd] Marked session file ended: ${session_id}`);
+          marked = true;
+          break;
+        } catch { /* try next */ }
+      }
+      if (!marked) {
+        console.error(`[SessionEnd] WARN: Could not mark session file ended — session-file-registry not found at any path`);
+      }
+    } catch (e) {
+      if (env.DEBUG) console.error(`[SessionEnd] Failed to mark session ended: ${e.message}`);
+    }
+
     // Delete registration marker file
     try {
       const registrationMarker = join(tmpdir(), `teleportation-session-${session_id}.registered`);

package/.claude/hooks/session_start.mjs

@@ -128,6 +128,17 @@ function updateSessionMarker(sessionId) {
   } catch {}
 
   let { session_id, cwd } = input || {};
+  // Cursor's sessionStart provides session_id (same as conversation_id) but cwd
+  // comes from workspace_roots, not a top-level cwd field
+  cwd = cwd || input?.workspace_roots?.[0];
+  // Detect client and capture Cursor-specific session context
+  const client = input?.cursor_version ? 'cursor' : 'claude-code';
+  const cursorMeta = client === 'cursor' ? {
+    client,
+    is_background_agent: input?.is_background_agent ?? false,
+    composer_mode: input?.composer_mode || null,
+    cursor_version: input?.cursor_version || null,
+  } : { client };
   const claude_session_id = session_id;
 
   // Check if credentials changed since last session start - user may need to restart
@@ -277,10 +288,55 @@ function updateSessionMarker(sessionId) {
           console.error(`[SessionStart] Captured model: ${meta.current_model}`);
         }
 
+        // If this session was spawned by the task executor as a child of a parent session,
+        // record the parent_session_id so the UI can hide child sessions from the list.
+        const parentSessionId = env.TELEPORTATION_PARENT_SESSION_ID;
+        const taskMeta = parentSessionId ? { parent_session_id: parentSessionId } : {};
+
+        const fullMeta = { ...meta, ...cursorMeta, ...taskMeta };
+
+        // PRIMARY: Write session file for daemon to discover via PID-based polling.
+        // This is fire-and-forget — no timeout, no network, survives daemon restarts.
+        // Cursor sessions use conversation_id not a real claude PID, so skip for them.
+        if (client === 'claude-code' && process.ppid) {
+          try {
+            const registryPaths = [
+              join(homedir(), '.teleportation', 'lib', 'daemon', 'session-file-registry.js'),
+              join(__dirname, '..', '..', 'lib', 'daemon', 'session-file-registry.js'),
+            ];
+            let writeSessionFile = null;
+            for (const p of registryPaths) {
+              try {
+                const mod = await import(p);
+                writeSessionFile = mod.writeSessionFile;
+                break;
+              } catch { /* try next */ }
+            }
+            if (writeSessionFile) {
+              await writeSessionFile({ session_id, claude_pid: process.ppid, cwd: cwd || process.cwd(), meta: fullMeta });
+              if (env.DEBUG) {
+                // Log the parent process name so we can verify ppid points to `claude`
+                // and not an intermediate shell (sh -c "bun hook") in some environments.
+                try {
+                  const { execFile } = await import('node:child_process');
+                  const { promisify: pify } = await import('node:util');
+                  const { stdout } = await pify(execFile)('ps', ['-p', String(process.ppid), '-o', 'comm='], { timeout: 1000 });
+                  console.error(`[SessionStart] Session file written (PID: ${process.ppid}, comm: ${stdout.trim()})`);
+                } catch {
+                  console.error(`[SessionStart] Session file written (PID: ${process.ppid})`);
+                }
+              }
+            }
+          } catch (fileErr) {
+            if (env.DEBUG) console.error(`[SessionStart] Session file write failed: ${fileErr.message}`);
+          }
+        }
+
+        // SECONDARY: HTTP registration with daemon (kept for backward compat with older daemons).
         await fetchWithTimeout(`${daemonUrl}/sessions/register`, {
           method: 'POST',
           headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify({ session_id, claude_session_id, cwd, meta })
+          body: JSON.stringify({ session_id, claude_session_id, cwd, meta: fullMeta })
         }, 2000);
 
         if (env.DEBUG) {

package/.claude/hooks/stop.mjs

@@ -75,6 +75,9 @@ function basicSanitizer(text) {
  * @param {Function} [log] - Optional logging function for warnings
  * @returns {Promise<Function>} - The sanitizer function
  */
+// Shared sanitizeEventData from lib/utils/log-sanitizer.js (loaded alongside sanitizeForLog)
+let sanitizeEventDataFn = null;
+
 async function getSanitizer(log = () => {}) {
   if (sanitizeForLog) return sanitizeForLog;
 
@@ -90,6 +93,7 @@ async function getSanitizer(log = () => {}) {
     try {
       const mod = await import(path);
       sanitizeForLog = mod.sanitizeForLog;
+      sanitizeEventDataFn = mod.sanitizeEventData || null;
       if (sanitizeForLog) return sanitizeForLog;
     } catch (err) {
       // Log import failures for debugging (only in DEBUG mode to avoid noise)
@@ -127,9 +131,10 @@ const isValidSessionId = (id) => {
 /**
  * Truncation length constants - intentionally different for different message types
  *
- * ASSISTANT_RESPONSE_MAX_LENGTH (2000 chars):
+ * ASSISTANT_RESPONSE_MAX_LENGTH (50000 chars / ~50KB):
  *   - Used for assistant conversational responses
- *   - Longer because these are the primary output users want to see
+ *   - Matches the relay API's MAX_EVENT_DATA_SIZE limit per field
+ *   - Responses are primary output users want to read in full
  *   - Less frequent (typically 1 per user turn)
  *
  * MAX_SYSTEM_MESSAGE_LENGTH (1000 chars):
@@ -138,7 +143,7 @@ const isValidSessionId = (id) => {
  *   - Thinking blocks can occur many times per response
  *   - Optimizes storage while maintaining useful context
  */
-const ASSISTANT_RESPONSE_MAX_LENGTH = 2000;
+const ASSISTANT_RESPONSE_MAX_LENGTH = 50000;
 const MAX_SYSTEM_MESSAGE_LENGTH = 1000;
 
 // Max size for full transcript (bytes) - 500KB
@@ -268,42 +273,49 @@ const extractMessageContent = (msg) => {
 
 /**
  * Sanitize event data to remove sensitive information before storing in timeline.
- * Applies sanitization to string fields that may contain secrets.
+ * Delegates to the shared sanitizeEventData from lib/utils/log-sanitizer.js when
+ * available, otherwise falls back to a local implementation.
  *
  * @param {Object} eventData - The event data object
  * @param {Function} sanitizer - The sanitization function
  * @returns {Object} - Sanitized event data
  */
 const sanitizeEventData = (eventData, sanitizer) => {
+  // Use shared module if loaded by getSanitizer()
+  if (sanitizeEventDataFn) {
+    return sanitizeEventDataFn(eventData, sanitizer);
+  }
+
+  // Fallback: local implementation (kept as safety net if shared module unavailable)
   if (!eventData || typeof eventData !== 'object') return eventData;
   if (!sanitizer) return eventData;
 
   const sanitized = { ...eventData };
-
-  // Sanitize known text fields
-  const textFields = ['message', 'summary', 'thinking', 'result', 'error'];
+  const textFields = ['message', 'summary', 'thinking', 'result', 'error', 'stdout', 'stderr', 'content'];
   for (const field of textFields) {
     if (typeof sanitized[field] === 'string') {
       sanitized[field] = sanitizer(sanitized[field]);
     }
   }
 
-  // Sanitize tool_input if it's a string or contains sensitive data
   if (sanitized.tool_input) {
     if (typeof sanitized.tool_input === 'string') {
       sanitized.tool_input = sanitizer(sanitized.tool_input);
     } else if (typeof sanitized.tool_input === 'object') {
-      // Sanitize stringified version of object fields that might contain secrets
-      const inputStr = JSON.stringify(sanitized.tool_input);
-      const sanitizedStr = sanitizer(inputStr);
-      if (inputStr !== sanitizedStr) {
-        try {
-          sanitized.tool_input = JSON.parse(sanitizedStr);
-        } catch {
-          // If parsing fails, use sanitized string
-          sanitized.tool_input = sanitizedStr;
+      // SYNC_WITH: lib/utils/log-sanitizer.js SENSITIVE_KEY_RE
+      const sensitiveKeyRe = /^(password|passwd|pwd|secret|token|api[_-]?key|authorization|credentials?)$/i;
+      const sanitizeValues = (obj, parentKey) => {
+        if (typeof obj === 'string') {
+          if (parentKey && sensitiveKeyRe.test(parentKey)) return '***';
+          return sanitizer(obj);
         }
-      }
+        if (typeof obj !== 'object' || obj === null) return obj;
+        if (Array.isArray(obj)) return obj.map(item => sanitizeValues(item));
+        const result = {};
+        for (const [k, v] of Object.entries(obj)) result[k] = sanitizeValues(v, k);
+        return result;
+      };
+      sanitized.tool_input = sanitizeValues(sanitized.tool_input);
     }
   }
 

package/lib/config/manager.js

@@ -49,6 +49,15 @@ const DEFAULT_CONFIG = {
     enabled: true,
     sound: false
   },
+  transcriptSync: {
+    enabled: false,
+    intervalMs: 300000, // 5 minutes
+    machineId: null,
+    peer: null,
+    peerMirrorDir: null,
+    mode: 'local', // local|push|pull|bidirectional
+    mirrorDir: join(homedir(), '.teleportation', 'transcript-mirror')
+  },
   installation: {
     scope: null,        // 'global' | 'project' | null (not installed)
     hooksPath: null,    // Path where hooks are installed
@@ -99,7 +108,8 @@ function validateConfig(config) {
   const booleanFields = [
     'hooks.autoUpdate',
     'notifications.enabled',
-    'notifications.sound'
+    'notifications.sound',
+    'transcriptSync.enabled'
   ];
 
   booleanFields.forEach(field => {
@@ -109,6 +119,40 @@ function validateConfig(config) {
     }
   });
 
+  // Validate transcript sync block if present
+  if (config.transcriptSync) {
+    const ts = config.transcriptSync;
+    const validModes = ['local', 'push', 'pull', 'bidirectional'];
+
+    if (ts.intervalMs !== undefined) {
+      if (typeof ts.intervalMs !== 'number' || ts.intervalMs < 10000 || ts.intervalMs > 86400000) {
+        errors.push('transcriptSync.intervalMs must be a number between 10000 and 86400000');
+      }
+    }
+
+    if (ts.mode !== undefined && !validModes.includes(ts.mode)) {
+      errors.push('transcriptSync.mode must be one of: local, push, pull, bidirectional');
+    }
+
+    ['mirrorDir', 'peerMirrorDir'].forEach(field => {
+      const value = ts[field];
+      if (value !== null && value !== undefined && typeof value !== 'string') {
+        errors.push(`transcriptSync.${field} must be a string path or null`);
+      }
+    });
+
+    ['machineId', 'peer'].forEach(field => {
+      const value = ts[field];
+      if (value !== null && value !== undefined && typeof value !== 'string') {
+        errors.push(`transcriptSync.${field} must be a string or null`);
+      }
+    });
+
+    if (['push', 'pull', 'bidirectional'].includes(ts.mode)) {
+      warnings.push('Non-local transcript sync modes require repo peer auto-discovery (set via git config teleportation.transcriptSyncPeer)');
+    }
+  }
+
   // Validate installation block if present
   if (config.installation) {
     const installation = config.installation;

package/lib/daemon/session-file-registry.js

@@ -0,0 +1,207 @@
+/**
+ * File-based session registry.
+ *
+ * Hooks write a session file once on session_start. The daemon scans this
+ * directory to discover sessions, checks PID liveness, and heartbeats the
+ * relay on their behalf. This decouples registration from the daemon's HTTP
+ * server — a file write never times out and survives daemon restarts.
+ *
+ * File location: /tmp/teleportation-sessions/<session_id>.json
+ */
+
+import { readdir, readFile, writeFile, unlink, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { tmpdir } from 'node:os';
+
+const execFileAsync = promisify(execFile);
+
+export const SESSIONS_DIR = join(tmpdir(), 'teleportation-sessions');
+
+/** Guard against path traversal: session_ids must be standard lowercase hex UUIDs */
+function assertValidSessionId(session_id) {
+  if (typeof session_id !== 'string' || !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(session_id)) {
+    throw new Error(`Invalid session_id: ${String(session_id)}`);
+  }
+}
+
+/** Ensure the sessions directory exists (mode 0700 — only owner can read/list) */
+export async function ensureSessionsDir(dir = SESSIONS_DIR) {
+  await mkdir(dir, { recursive: true, mode: 0o700 });
+}
+
+/**
+ * Write a session registration file.
+ * Called ONCE by session_start.mjs. Never updated by the hook after this.
+ *
+ * @param {object} opts
+ * @param {string} opts.session_id
+ * @param {number} opts.claude_pid  - process.ppid inside the hook (the parent claude process)
+ * @param {string} opts.cwd
+ * @param {object} opts.meta
+ * @param {string} [opts._dir]      - override directory (for testing)
+ */
+export async function writeSessionFile({ session_id, claude_pid, cwd, meta, _dir }) {
+  assertValidSessionId(session_id);
+  const dir = _dir || SESSIONS_DIR;
+  await ensureSessionsDir(dir);
+  const path = join(dir, `${session_id}.json`);
+  const record = {
+    session_id,
+    claude_pid,
+    cwd,
+    meta: meta || {},
+    registered_at: Date.now(),
+    acked: false,
+    ended: false,
+  };
+  await writeFile(path, JSON.stringify(record, null, 2), { encoding: 'utf8', mode: 0o600 });
+  return record;
+}
+
+/**
+ * Mark a session file as ended (written by session_end.mjs).
+ * Daemon will stop heartbeating on its next poll cycle.
+ *
+ * Note: read-modify-write is not atomic. If session_end.mjs and the daemon
+ * call this simultaneously (e.g., daemon cleanup races with hook), one write
+ * may clobber the other. The window is ~1ms and the worst outcome is a
+ * missed ended=true flag — the daemon will catch the dead PID within 60s.
+ *
+ * @param {string} session_id
+ * @param {string} [_dir] - override directory (for testing)
+ */
+export async function markSessionEnded(session_id, _dir) {
+  assertValidSessionId(session_id);
+  const path = join(_dir || SESSIONS_DIR, `${session_id}.json`);
+  try {
+    const raw = await readFile(path, 'utf8');
+    const record = JSON.parse(raw);
+    record.ended = true;
+    record.ended_at = Date.now();
+    await writeFile(path, JSON.stringify(record, null, 2), { encoding: 'utf8', mode: 0o600 });
+  } catch {
+    // File may not exist if daemon already cleaned it up — that's fine
+  }
+}
+
+/**
+ * Ack a session file (written by daemon after picking it up).
+ *
+ * @param {string} session_id
+ * @param {number} daemon_pid
+ * @param {string} [_dir] - override directory (for testing)
+ */
+export async function ackSessionFile(session_id, daemon_pid, _dir) {
+  assertValidSessionId(session_id);
+  const path = join(_dir || SESSIONS_DIR, `${session_id}.json`);
+  try {
+    const raw = await readFile(path, 'utf8');
+    const record = JSON.parse(raw);
+    record.acked = true;
+    record.daemon_pid = daemon_pid;
+    record.acked_at = Date.now();
+    await writeFile(path, JSON.stringify(record, null, 2), { encoding: 'utf8', mode: 0o600 });
+  } catch {
+    // File may have been deleted concurrently — ignore
+  }
+}
+
+/**
+ * Delete a session file (daemon cleanup after session ends or PID dies).
+ *
+ * @param {string} session_id
+ * @param {string} [_dir] - override directory (for testing)
+ */
+export async function deleteSessionFile(session_id, _dir) {
+  assertValidSessionId(session_id);
+  try {
+    await unlink(join(_dir || SESSIONS_DIR, `${session_id}.json`));
+  } catch {
+    // Already gone — fine
+  }
+}
+
+/**
+ * Read all session files from the sessions directory.
+ * Returns an array of parsed records, skipping malformed files.
+ *
+ * @param {string} [_dir] - override directory (for testing)
+ * @returns {Promise<Array>}
+ */
+export async function readAllSessionFiles(_dir) {
+  const dir = _dir || SESSIONS_DIR;
+  await ensureSessionsDir(dir);
+  let files;
+  try {
+    files = await readdir(dir);
+  } catch {
+    return [];
+  }
+
+  const records = [];
+  for (const file of files) {
+    if (!file.endsWith('.json')) continue;
+    const expectedId = file.slice(0, -5); // strip .json
+    try {
+      const raw = await readFile(join(dir, file), 'utf8');
+      const record = JSON.parse(raw);
+      // Validate session_id is a proper UUID and matches filename to prevent path traversal
+      if (
+        record.session_id &&
+        record.claude_pid &&
+        /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(record.session_id) &&
+        record.session_id === expectedId
+      ) {
+        records.push(record);
+      }
+    } catch {
+      // Malformed or mid-write — skip
+    }
+  }
+  return records;
+}
+
+/**
+ * Check whether a PID belongs to a live `claude` process.
+ *
+ * Uses two signals:
+ * 1. kill -0 (signal 0): tests if the process exists without sending a signal
+ * 2. ps comm=: verifies the process name is "claude" to guard against PID reuse
+ *
+ * Async to avoid blocking the event loop — execSync would stall the daemon's
+ * heartbeat and relay polling for up to 1s per call × N sessions.
+ *
+ * Known edge case: if a new `claude` process reuses the exact PID of a
+ * just-exited session, this returns true until the 60s grace period expires.
+ * Probability is extremely low in practice given PID space on modern systems.
+ *
+ * @param {number} pid
+ * @returns {Promise<boolean>}
+ */
+export async function isClaudePidAlive(pid) {
+  if (!pid || typeof pid !== 'number') return false;
+  try {
+    // kill(pid, 0) throws ESRCH if process doesn't exist, EPERM if exists but no permission
+    process.kill(pid, 0);
+  } catch (e) {
+    // EPERM means process exists but we can't signal it — treat as alive
+    if (e.code === 'EPERM') return true;
+    return false;
+  }
+
+  // Verify process name to guard against PID reuse by non-claude processes.
+  // Uses async execFile to avoid blocking the event loop.
+  try {
+    const { stdout } = await execFileAsync('ps', ['-p', String(pid), '-o', 'comm='], { timeout: 1000 });
+    const comm = stdout.trim();
+    // Accept "claude" or paths ending in "/claude"
+    return comm === 'claude' || comm.endsWith('/claude');
+  } catch {
+    // ps failed (process just died, or ps unavailable in container). When kill -0
+    // already confirmed the process exists (we get here only if kill -0 succeeded),
+    // optimistically treat it as alive — kill -0 is the stronger liveness signal.
+    return true;
+  }
+}