Loading files
This file is pinned to the selected release. Download the original to open it in your design tool.
52a6c9020This file is pinned to the selected release. Download the original to open it in your design tool.
/**
* Find the session a live discovered engine process is running, when no hook has bound one yet.
*
* Process discovery can see an engine immediately, including after a daemon restart, but a session id is
* owned by the engine and may not be present in argv. Ask the engine's own store which session belongs to
* that pane's directory and process start time.
*
* Two rules keep it honest:
* - **Started after the engine process did.** A session older than the process cannot be the one it is
* running now. (Resumed agents name their id on the command line and are adopted from argv instead —
* see tmuxAgentDiscovery.)
* - **Unique or nothing.** Two candidate sessions in one directory means two agents there, and guessing
* would hand one agent's transcript to the other's tile. Ambiguity returns null; the agent stays
* unbound until its next turn, which is recoverable — mis-binding is not.
*/
import { open, readdir, readFile, realpath, stat } from 'fs/promises'
import { basename, dirname, join, sep } from 'path'
import { env } from '../config/env.js'
import { museEvent, museWorkspaceRoot } from '../engines/muse/normalizer.js'
import type { AgentEngine } from '../engines/types.js'
import { readCodexRolloutMeta, resolveCodexRollout } from '../engines/codex/rollout.js'
import { agyConversationForPid, findAgyTranscript } from '../engines/agy/session.js'
import { copilotSessionCwd, copilotSessionForPid, findCopilotTranscript } from '../engines/copilot/session.js'
import { hermesDbPath, listHermesHomes } from '../engines/hermes/home.js'
import { sqlitePreflightMessage } from './sqliteAvailability.js'
import { sqliteReadAll, type SqliteParam } from './sqliteRead.js'
/**
* Clock granularity only. `ps` reports start time to the second, so a file created in the same second
* must still count as "after".
*
* Deliberately small. It was 60s, and that let a session the user had JUST exited be handed to the engine
* they started seconds later in the same pane: the old transcript's last write fell inside the window, so
* the new agent came up wearing the dead session's id (measured — `/exit`, relaunch, and repair re-bound
* `6899ff76`). Whatever is picked here must belong to the process running NOW.
*/
const START_SLACK_MS = 5_000
/** Directories to walk per engine root. Deep enough for codex's <year>/<month>/<day> layout. */
const MAX_DEPTH = 4
const MAX_FILES = 400
export interface RepairedSession {
sessionId: string
/** File-backed engines only; the DB-backed ones are read by session id. */
transcriptPath?: string
/** Hermes only: which home's store the session was found in, when it was not the default one. */
hermesHome?: string
}
interface TranscriptFile { path: string; mtimeMs: number; birthMs: number }
/** Every `.jsonl` under `root`, newest first, capped. Checkpoint/sidecar files are not transcripts. */
async function transcripts(root: string, depth = 0): Promise<TranscriptFile[]> {
if (depth > MAX_DEPTH) return []
let entries
try { entries = await readdir(root, { withFileTypes: true }) } catch { return [] }
const out: TranscriptFile[] = []
for (const entry of entries) {
const full = join(root, entry.name)
if (entry.isDirectory()) { out.push(...await transcripts(full, depth + 1)); continue }
if (!entry.name.endsWith('.jsonl') || entry.name.includes('.checkpoints.')) continue
try {
const info = await stat(full)
out.push({ path: full, mtimeMs: info.mtimeMs, birthMs: info.birthtimeMs || info.mtimeMs })
} catch { /* vanished mid-scan */ }
}
return out.sort((a, b) => b.mtimeMs - a.mtimeMs).slice(0, MAX_FILES)
}
/**
* The `cwd` a transcript declares, from its opening lines.
*
* Not just line one: claude opens with bookkeeping records (`leafUuid`, `mode`) that carry no cwd, so a
* first-line-only read found nothing for every claude session on the computer — caught when a live repair
* returned null for a pane whose transcript was sitting right there. pi and Command Code do put it on
* line one; scanning a few lines covers all three without knowing which is which.
*/
const CWD_SCAN_LINES = 20
async function readTranscriptMeta(path: string): Promise<TranscriptMeta | null> {
try {
const head = (await readFile(path, 'utf-8')).slice(0, 256 * 1024)
for (const line of head.split('\n', CWD_SCAN_LINES)) {
if (!line.trim()) continue
let obj: Record<string, unknown>
try { obj = JSON.parse(line) as Record<string, unknown> } catch { continue }
if (typeof obj.cwd === 'string' && obj.cwd) return { cwd: obj.cwd }
}
return null
} catch { return null }
}
/** Session id from `<id>.jsonl`, or from pi's `<timestamp>_<id>.jsonl`. */
function idFromFile(path: string): string {
const base = path.split('/').pop()?.replace(/\.jsonl$/, '') ?? ''
const underscore = base.lastIndexOf('_')
return underscore === -1 ? base : base.slice(underscore + 1)
}
/**
* Compare two directories as the filesystem sees them, not as strings.
*
* On macOS `/tmp` is a symlink to `/private/tmp`, so discovery reporting one and an engine recording the
* other describe the SAME directory and would never match textually — measured: a repair that resolved
* correctly for `/private/tmp/synctest` returned null for `/tmp/synctest`.
*/
export async function sameDir(a: string, b: string): Promise<boolean> {
if (a === b) return true
const [ra, rb] = await Promise.all([
realpath(a).catch(() => a),
realpath(b).catch(() => b),
])
return ra === rb
}
/**
* Two tiers, because two different things look alike from here.
*
* born — the transcript was CREATED after the process started: a session this engine opened itself.
* wrote — created earlier but written to after the process started: a session it RESUMED.
*
* Preferring `born` is what stops a just-exited session from being handed to its replacement: the dead
* transcript was created before the new process, and its final write lands before the new process starts,
* so it qualifies for neither tier and the pane stays unbound until the real session appears.
*/
interface TranscriptMeta { cwd: string | null; sessionId?: string }
const str = (v: unknown): string => (typeof v === 'string' ? v : '')
/**
* True once a muse session has opened a RUN — the lifecycle a conversation is made of.
*
* Not "has a prompt": a scheduled run is a real turn whose prompt is empty, because the scheduler
* triggered it rather than a person. `payload.kind` is what separates the two lifecycles that share the
* name `started`; a `task` one is scheduler bookkeeping and several fire inside a single run.
*/
function hasRun(lines: string[]): boolean {
for (const line of lines) {
const record = museEvent(line)
if (record?.scope === 'run' && str(record.event.kind) === 'started') return true
}
return false
}
async function fileEngineSession(
root: string,
cwd: string,
startedAtMs: number,
readMeta: (path: string) => Promise<TranscriptMeta | null>,
opts?: { bornOnly?: boolean },
): Promise<RepairedSession | null> {
const since = startedAtMs - START_SLACK_MS
const born: RepairedSession[] = []
const wrote: RepairedSession[] = []
for (const file of await transcripts(root)) {
if (file.mtimeMs < since) break // sorted newest-first: everything after is older still
const meta = await readMeta(file.path)
if (!meta?.cwd || !await sameDir(meta.cwd, cwd)) continue
const found = { sessionId: meta.sessionId || idFromFile(file.path), transcriptPath: file.path }
;(file.birthMs >= since ? born : wrote).push(found)
}
// "Unique or nothing" at each tier: two candidates means two agents in one directory, and a wrong guess
// wires one agent's tile to the other's transcript.
if (born.length === 1) return born[0]
if (born.length > 1) return null
// `bornOnly`: the caller is binding an agent that has NEVER had a session. Accepting the `wrote` tier
// there hands it whatever session was last touched in this directory — measured: exit the engine,
// run `claude` again in the same pane, and the new agent adopted the PREVIOUS conversation,
// so the web opened a fresh tab already full of old messages. A resume the user asked for by name is
// matched from argv by the discovery path instead, which needs no guessing.
if (opts?.bornOnly) return null
return wrote.length === 1 ? wrote[0] : null
}
let missingSqliteReported = false
/** The store-backed repair branch cannot work without a SQLite reader; warn on the first miss only. */
function reportMissingSqliteOnce(): void {
if (missingSqliteReported) return
missingSqliteReported = true
console.warn(sqlitePreflightMessage() ?? '[preflight] no SQLite reader available')
}
/** Read-only, through the same helper the readers use, so a repair can never write to the user's store. */
async function dbEngineSession(dbPath: string, sql: string, params: SqliteParam[]): Promise<RepairedSession | null> {
const result = await sqliteReadAll(dbPath, sql, params, { maxBuffer: 1024 * 1024 })
if (!result.ok) {
// No reader at all is not a transient DB lock, and repair returning null forever with no signal is
// how "my opencode agents never appear on Ubuntu" looks from the outside. Say it once.
if (result.reason === 'missing') reportMissingSqliteOnce()
return null
}
const rows = result.rows
if (rows.length !== 1) return null // 0 = nothing to adopt, >1 = ambiguous
const id = rows[0].id
return typeof id === 'string' && id ? { sessionId: id } : null
}
/** One `?` per directory, for an `IN (…)` over both spellings of the cwd. */
function placeholders(count: number): string {
return Array.from({ length: count }, () => '?').join(', ')
}
/**
* The session a discovered engine process is running in `cwd`, or null when it cannot be said for certain.
*
* `startedAtMs` is when the engine process started (`ps` lstart). Cursor is absent on purpose: its
* transcripts are located by id rather than listed by directory, and its resumes already have a
* dedicated discovery path.
*/
/**
* Copilot names its session directory by uuid, so the cwd lives inside the file — on the first record,
* `session.start.data.context.cwd`. `readTranscriptMeta` scans the first lines for a bare `cwd`, but
* Copilot nests it, so this reads it out itself.
*/
async function copilotDirectoryScan(
cwd: string,
startedAtMs: number,
opts?: { bornOnly?: boolean },
): Promise<RepairedSession | null> {
return fileEngineSession(join(env.COPILOT_HOME, 'session-state'), cwd, startedAtMs, async (path) => {
if (basename(path) !== 'events.jsonl') return null
const head = (await readFile(path, 'utf8').catch(() => '')).split('\n', 5)
const root = copilotSessionCwd(head)
return root ? { cwd: root, sessionId: basename(dirname(path)) } : null
}, opts)
}
export async function findLiveSession(
engine: AgentEngine,
cwd: string,
startedAtMs: number,
// codexHome: the specific agent's own CODEX_HOME profile, when it isn't this machine's default —
// see RegisteredSession.codexHome. Only the 'codex' case below reads it.
opts?: { bornOnly?: boolean; pid?: number; codexHome?: string },
): Promise<RepairedSession | null> {
const sinceMs = startedAtMs - START_SLACK_MS
// The DB engines match on a directory STRING, so ask for both spellings of it (see sameDir).
const real = await realpath(cwd).catch(() => cwd)
const dirs = real === cwd ? [cwd] : [cwd, real]
const dirList = placeholders(dirs.length)
switch (engine) {
case 'claude': {
// Native Claude publishes a PID-to-conversation record even before a hook binds it.
// Unlike a directory scan this also identifies an old process in a busy project.
const exact = opts?.pid ? await claudeProcessSession(opts.pid, cwd, startedAtMs) : null
return exact ?? fileEngineSession(env.CLAUDE_PROJECTS_DIR, cwd, startedAtMs, readTranscriptMeta, opts)
}
case 'codex':
// Codex writes no `cwd` on line one; its rollout meta carries it — and says whether the rollout
// belongs to a subagent, which must never become an agent of its own.
// Its session id lives INSIDE the file: the name is `rollout-<timestamp>-<id>.jsonl`, so deriving
// the id from the filename produced the literal string "rollout-…" (seen on a live pane).
return fileEngineSession(join(opts?.codexHome || env.CODEX_HOME, 'sessions'), cwd, startedAtMs, async (path) => {
const meta = readCodexRolloutMeta(path)
return meta && !meta.isSubagent ? { cwd: meta.cwd, sessionId: meta.id || undefined } : null
}, opts)
case 'pi':
return fileEngineSession(join(env.PI_HOME, 'agent', 'sessions'), cwd, startedAtMs, readTranscriptMeta, opts)
case 'commandcode':
return fileEngineSession(join(env.COMMANDCODE_HOME, 'projects'), cwd, startedAtMs, readTranscriptMeta, opts)
case 'muse':
// Muse's hooks never fire, so this scan is the ONLY way a muse pane is ever bound. The tree is
// `sessions/YYYY/MM/DD/<session-uuid>/session.jsonl` (4 levels — exactly MAX_DEPTH) and nothing in
// the path names the project: `workspace_root` in the first record is the only link. Sub-agent
// files live one level deeper under `subagent/`, and must never be adopted as agents of their own.
return fileEngineSession(join(env.MUSE_HOME, 'sessions'), cwd, startedAtMs, async (path) => {
if (path.includes(`${sep}subagent${sep}`)) return null
const lines = (await readFile(path, 'utf-8').catch(() => '')).split('\n')
const root = museWorkspaceRoot(lines[0] ?? '')
if (!root) return null
// Muse opens sessions of its OWN under the same workspace_root — memory reminders
// (`memory_reminder_child_session_linked`) are the ones seen live. They are indistinguishable from
// the user's session by path, workspace or birth time, and being younger they WIN the `born` tier:
// measured, the daemon tailed an 11-line reminder session while the real conversation ran on in
// another file, so web and device received nothing at all. What separates them is that a session
// being conversed in has opened a RUN.
if (!hasRun(lines)) return null
return { cwd: root, sessionId: basename(dirname(path)) }
}, opts)
case 'amp':
// The transcripts scanned here are the adapter's own — Amp keeps no conversation on disk, so its
// plugin writes one per thread as `<AMP_SESSIONS_DIR>/<threadId>.jsonl` with `cwd` on the first
// line. That makes the ordinary file scan work unchanged, and the file name IS the session id.
//
// Amp also offers a second, exact answer that this deliberately does not use: `session.json` maps
// `tmux:<pane>@<server-pid>,<session>` to the thread started in that pane. It is a better key than a
// directory — but `findLiveSession` is asked about a cwd, not a pane, and a repair that silently
// needed a different question would be the kind of split path this file exists to avoid.
return fileEngineSession(env.AMP_SESSIONS_DIR, cwd, startedAtMs, readTranscriptMeta, opts)
case 'grok':
// `updates.jsonl` lives under `<encoded-cwd>/<uuid>/`; long cwd values use a hashed group with a
// `.cwd` sidecar. The file itself is ACP updates and carries no cwd, so derive it from that group.
return fileEngineSession(join(env.GROK_HOME, 'sessions'), cwd, startedAtMs, async (path) => {
if (basename(path) !== 'updates.jsonl') return null
const sessionDir = dirname(path)
const group = dirname(sessionDir)
let root = ''
try { root = decodeURIComponent(basename(group)) } catch { /* hashed layout below */ }
if (!root.startsWith('/')) root = (await readFile(join(group, '.cwd'), 'utf8').catch(() => '')).trim()
return root ? { cwd: root, sessionId: basename(sessionDir) } : null
}, opts)
case 'opencode':
// time_created is epoch MILLISECONDS here.
return dbEngineSession(
join(env.OPENCODE_DATA_DIR, 'opencode.db'),
`SELECT id FROM session WHERE directory IN (${dirList}) AND parent_id IS NULL`
+ ' AND (time_created >= ? OR time_updated >= ?)'
+ ' ORDER BY time_updated DESC LIMIT 2;',
[...dirs, Math.trunc(sinceMs), Math.trunc(sinceMs)],
)
case 'kilo':
// Same store shape as opencode (measured: `session` is byte-identical between the two DBs), and
// time_created is epoch MILLISECONDS here too — the real row on this machine reads 1786091927554.
return dbEngineSession(
join(env.KILO_DATA_DIR, 'kilo.db'),
`SELECT id FROM session WHERE directory IN (${dirList}) AND parent_id IS NULL`
+ ' AND (time_created >= ? OR time_updated >= ?)'
+ ' ORDER BY time_updated DESC LIMIT 2;',
[...dirs, Math.trunc(sinceMs), Math.trunc(sinceMs)],
)
case 'hermes': {
// started_at is epoch SECONDS (fractional).
//
// EVERY home, not just the default: `hermes -p <name>` keeps its sessions in
// `~/.hermes/profiles/<name>/state.db`, and a repair that only asked the default store could
// never rebind a profile agent after a restart (openharness#191). Each store is asked on its
// own and the answers are pooled, so two homes claiming the same cwd is ambiguous — exactly as
// two rows in one store already are — rather than "whichever home was listed first".
const homes = await listHermesHomes()
const found: RepairedSession[] = []
for (const home of homes) {
const one = await dbEngineSession(
hermesDbPath(home),
`SELECT id FROM sessions WHERE cwd IN (${dirList}) AND started_at >= ?`
+ ' ORDER BY started_at DESC LIMIT 2;',
[...dirs, Math.trunc(sinceMs / 1000)],
)
if (one) found.push({ ...one, hermesHome: home })
if (found.length > 1) return null
}
return found[0] ?? null
}
case 'devin':
// created_at is epoch SECONDS (integer).
return dbEngineSession(
join(env.DEVIN_HOME, 'sessions.db'),
// created_at is when the session began; last_activity_at moves when devin resumes into it, which
// is the only marker a continued session leaves behind.
`SELECT id FROM sessions WHERE working_directory IN (${dirList})`
+ ' AND (created_at >= ? OR last_activity_at >= ?)'
+ ' ORDER BY last_activity_at DESC LIMIT 2;',
[...dirs, Math.trunc(sinceMs / 1000), Math.trunc(sinceMs / 1000)],
)
case 'copilot': {
// The lock the process holds is the only thing a `/resume` leaves behind, and it is exact.
// Fall through to the directory scan when there is no pid or no lock yet (a brand-new session
// takes its lock only once Copilot creates it).
const locked = opts?.pid ? await copilotSessionForPid(env.COPILOT_HOME, opts.pid) : null
if (locked) {
const transcriptPath = await findCopilotTranscript(env.COPILOT_HOME, locked)
return { sessionId: locked, transcriptPath: transcriptPath ?? undefined }
}
return copilotDirectoryScan(cwd, startedAtMs, opts)
}
case 'agy':
// The one engine here that cannot be found by directory. agy's transcript records no cwd, its
// brain directory is named by the conversation id, and `conversation_summaries.db` — which looks
// like the index for exactly this — holds only IDE rows, never CLI ones (measured on 1.1.14).
//
// What it does leave is `presence/<conversationId>.lock`, held open by the live process for the
// life of the conversation. That is a pid→conversation map and a liveness test in one, so repair
// asks the process rather than the directory. Without a pid there is nothing to ask.
return opts?.pid ? agySession(opts.pid) : null
default:
return null
}
}
/** The conversation the given `agy` pid is holding, if its transcript exists yet. */
async function agySession(pid: number): Promise<RepairedSession | null> {
const conversationId = await agyConversationForPid(env.AGY_HOME, pid)
if (!conversationId) return null
const transcriptPath = await findAgyTranscript(env.AGY_HOME, conversationId)
// A conversation with no transcript is one agy has opened but not written to; registry derives the
// path anyway, so bind it and let the watcher pick the file up when it appears.
return { sessionId: conversationId, transcriptPath: transcriptPath ?? undefined }
}
/** The last `maxBytes` of a file, as text. Bounded so a multi-MB transcript costs nothing to check. */
async function tailBytes(path: string, maxBytes: number): Promise<string> {
const handle = await open(path, 'r')
try {
const info = await handle.stat()
const start = Math.max(0, info.size - maxBytes)
const length = info.size - start
if (length <= 0) return ''
const buffer = Buffer.alloc(length)
await handle.read(buffer, 0, length, start)
return buffer.toString('utf-8')
} finally {
await handle.close()
}
}
const CLAUDE_CONTINUATION_TAIL_BYTES = 4 * 1024
/** Enough of a continuation to see whether anybody ever spoke in it. Its first turn is within a few
* lines of the top — the records before it are bookkeeping (mode, file history, title, agent name). */
const CLAUDE_CONTINUATION_HEAD_BYTES = 256 * 1024
async function headBytes(path: string, maxBytes: number): Promise<string> {
const handle = await open(path, 'r')
try {
const length = Math.min((await handle.stat()).size, maxBytes)
if (length <= 0) return ''
const buffer = Buffer.alloc(length)
await handle.read(buffer, 0, length, 0)
return buffer.toString('utf-8')
} finally {
await handle.close()
}
}
/**
* Whether a transcript holds a CONVERSATION, rather than being the file Claude opens for a session
* nobody has spoken in yet.
*
* `claude` writes the same `continued-in` marker for a BACKGROUND session as for a rollover, and the
* file it points at then holds two bookkeeping lines (`ai-title`, `agent-name`) and never grows,
* while the real conversation goes on in the original file. Following that marker moved an agent onto
* an empty session: its tile went quiet, and the conversation archived when the engine exited was the
* empty one — Open then asked `claude --resume <background id>`, which the CLI refuses outright
* ("is running as a background session … run `claude attach`"). Measured on one machine: of nine
* `continued-in` markers, three named a background session and every one of those files had exactly
* these two lines and no turn.
*/
async function hasConversationTurn(path: string): Promise<boolean> {
let head: string
try {
head = await headBytes(path, CLAUDE_CONTINUATION_HEAD_BYTES)
} catch {
return false
}
for (const line of head.split('\n')) {
if (!line.trim() || (!line.includes('"user"') && !line.includes('"assistant"'))) continue
try {
const record = JSON.parse(line) as { type?: unknown }
if (record.type === 'user' || record.type === 'assistant') return true
} catch { /* a line cut by the read bound, or one this version does not know */ }
}
// Nothing in the head, but more file than we read: a continuation can open on a `file-history-snapshot`
// large enough to push the first turn past the bound, and the thing being ruled out is two short
// lines. Anything this size is a conversation, so the bound must never be what refuses one.
return head.length >= CLAUDE_CONTINUATION_HEAD_BYTES
}
/**
* Claude rolls a long conversation's transcript over to a NEW file on its own (compaction, a resume
* chain) — the old file's last line names the new session and Claude simply starts writing there. No
* fresh SessionStart/UserPromptSubmit fires for it on its own if the actual turn that follows is
* served by a pooled/"spare" worker process rather than one spawned directly in the pane — so a
* hook-only bind can be left pointed at a transcript that has gone permanently quiet while the real
* conversation continues one file over. This is a cheap, bounded check for exactly that marker, read
* from the tail since it is always the very last line and tiny.
*/
export async function claudeContinuation(transcriptPath: string): Promise<RepairedSession | null> {
let tail: string
try {
tail = await tailBytes(transcriptPath, CLAUDE_CONTINUATION_TAIL_BYTES)
} catch {
return null
}
const lines = tail.split('\n').map((line) => line.trim()).filter(Boolean)
const lastLine = lines[lines.length - 1]
if (!lastLine) return null
let record: Record<string, unknown>
try {
record = JSON.parse(lastLine) as Record<string, unknown>
} catch {
return null
}
const nextId = record.type === 'continued-in' && typeof record.continuedInSessionId === 'string'
? record.continuedInSessionId
: ''
if (!nextId) return null
const nextPath = join(dirname(transcriptPath), `${nextId}.jsonl`)
try {
if (!(await stat(nextPath)).isFile()) return null
} catch {
return null
}
// A marker alone does not prove the conversation moved: the same one is written for a background
// session, whose file never holds a turn. Waiting for one costs nothing — this runs on every
// reconciler pass, so a continuation that is real binds on the pass after its first turn lands.
if (!await hasConversationTurn(nextPath)) return null
return { sessionId: nextId, transcriptPath: nextPath }
}
/**
* The transcript behind a session id a claude/codex process names on its own command line
* (`claude --resume <id>`, `codex resume <id>`) — the file `registry.register` insists on for those
* two engines, which argv does not carry. Claude keeps one file per session under
* `<projects>/<encoded cwd>/<id>.jsonl`; the cwd encoding is Claude's to define, so the project
* folders are listed rather than the name derived. Codex names its rollout after the thread id, and
* the rollout walker already knows that layout. Only a file that exists is returned: a resume of a
* session this machine never wrote (or one that was deleted) binds nothing.
*/
export async function findResumedTranscript(
engine: AgentEngine,
sessionId: string,
opts?: { codexHome?: string },
): Promise<string | null> {
if (!/^[0-9a-f-]{16,}$/i.test(sessionId)) return null
if (engine === 'codex') return resolveCodexRollout(sessionId, join(opts?.codexHome || env.CODEX_HOME, 'sessions'))
if (engine !== 'claude') return null
let projects: string[]
try { projects = await readdir(env.CLAUDE_PROJECTS_DIR) } catch { return null }
for (const project of projects) {
const candidate = join(env.CLAUDE_PROJECTS_DIR, project, `${sessionId}.jsonl`)
try {
if ((await stat(candidate)).isFile()) return candidate
} catch { /* not this project */ }
}
return null
}
/** Claude's native process record is removed at exit; capture it before Stop signals the engine. */
export async function claudeProcessSession(pid: number, cwd: string, startedAtMs: number): Promise<RepairedSession | null> {
if (!Number.isSafeInteger(pid) || pid <= 0 || !Number.isFinite(startedAtMs)) return null
try {
const record = JSON.parse(await readFile(join(dirname(env.CLAUDE_PROJECTS_DIR), 'sessions', `${pid}.json`), 'utf8'))
// procStart is UTC in current Claude, while older builds used the host's local ps format.
// Both represent the exact second, not the metadata file's modification time or a recycled PID.
if (record.pid !== pid || typeof record.procStart !== 'string'
|| ![Date.parse(record.procStart), Date.parse(`${record.procStart} UTC`)].includes(startedAtMs)
|| typeof record.cwd !== 'string' || !await sameDir(record.cwd, cwd)
|| typeof record.sessionId !== 'string') return null
const transcriptPath = await findResumedTranscript('claude', record.sessionId)
return transcriptPath ? { sessionId: record.sessionId, transcriptPath } : null
} catch { return null }
}