Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

43.6 KB
Raw Blame
/**
 * 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. Prefer the engine's process evidence; when no
 * exact process lookup applies, narrow the engine's store by 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 { readdir, readlink, realpath, stat } from 'fs/promises'
import { basename, dirname, isAbsolute, join, sep } from 'path'
import { homedir } from 'node:os'
import { env } from '../config/env.js'
import type { SessionStoreContract } from '../engines/facets/sessionStore.js'
import { identityBytes, identityEntries, identityFile, identityHead, identityLines, identityScanBudget, IdentityReadUnavailable } from '../engines/kit/identityScan.js'
import { sessionIdentityMetaOf } from '../engines/sessionFiles.js'
import { exactTranscript, exactWorkspaces } from '../engines/kit/exactTranscript.js'
import { readSessionHeader } from '../engines/kit/sessionIdentity.js'
import { sessionStoreOf } from '../engines/sessionStoreContracts.js'
import type { AgentEngine } from '../engines/types.js'
import { HERMES_HOMES, HERMES_HISTORY_ID_RE, HERMES_ID_SQL, HERMES_SOURCE, HERMES_SOURCE_SQL } from '../engines/hermes/contract.js'
import { readStorePool } from '../engines/kit/storePool.js'
import { isInteractiveSource } from '../engines/kit/storeSource.js'
import { museSessionIdentity, piSessionFolder, readPiHead } from '../engines/repairIdentities.js'
import { PI_HEADER, PI_SESSION_ID } from '../engines/pi/contract.js'
import { transcriptOf, processSessionOf as nativeProcessSession } from '../engines/identities.js'
import { COPILOT_CWD } from '../engines/copilot/contract.js'
import { recordCwd } from '../engines/kit/sessionLocation.js'
import { sqliteReadAll, type SqliteParam } from './sqliteRead.js'
import { sqlitePreflightMessage } from './sqliteAvailability.js'
import { nativeSessionRoots } from './engineHomes.js'
import { nativeOpenFileSession, type NativeConversationOptions } from './nativeConversation.js'
import type { ProcessIdentity } from './terminalTypes.js'
import { NativeEvidenceBudget } from '../engines/kit/nativeEvidence.js'
import { verifyProcessRecord } from '../engines/kit/processRecordEvidence.js'
import { NativePaths } from '../engines/kit/nativePaths.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

/** Known empty homes still require native probes. Do not let a saved catalog bypass the walk bound. */
function repairRoots(engine: AgentEngine, profile?: string): string[] {
  const roots = nativeSessionRoots(engine, profile)
  if (roots.length > 64) throw new IdentityReadUnavailable('the known session-home limit was reached')
  return roots
}

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
}

/** How deep Muse's session folders sit (`sessions/YYYY/MM/DD/<uuid>/`): every folder inside one is Muse's own
 *  (`subagent/`, `tool-outputs/`, `approval-review/`, and whatever a later version adds), never a conversation
 *  of the pane, so it is skipped rather than walked into and counted against MAX_DEPTH. */
const MUSE_SESSION_FOLDER_DEPTH = 4

interface TranscriptFile { path: string; mtimeMs: number; birthMs: number }

/** Collect a complete bounded pool. Truncation must never make two conversations look like one. */
async function transcripts(root: string, budget: { remaining: number }, out: TranscriptFile[], excluded: readonly string[] = [], depth = 0, leafDepth?: number): Promise<void> {
  for await (const entry of identityEntries(root, budget, depth === 0)) {
    const full = join(root, entry.name)
    if (entry.isDirectory()) {
      if (excluded.includes(entry.name) || (leafDepth !== undefined && depth >= leafDepth)) continue
      if (depth >= MAX_DEPTH) throw new IdentityReadUnavailable('the transcript depth limit was reached')
      await transcripts(full, budget, out, excluded, depth + 1, leafDepth)
      continue
    }
    if (!entry.name.endsWith('.jsonl') || entry.name.includes('.checkpoints.')) continue
    if (out.length >= MAX_FILES) throw new IdentityReadUnavailable('the transcript count limit was reached')
    try {
      const info = await stat(full)
      if (!info.isFile()) throw new IdentityReadUnavailable('a transcript is not a regular file')
      out.push({ path: full, mtimeMs: info.mtimeMs, birthMs: info.birthtimeMs || info.mtimeMs })
    } catch (error) {
      if (error instanceof IdentityReadUnavailable) throw error
      throw new IdentityReadUnavailable('a transcript could not be inspected')
    }
  }
}

/**
 * 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
const CWD_SCAN_CHARS = 256 * 1024
/**
 * Claude writes a `file-history-snapshot` record (tens of KB each) per checkpoint, and a long or resumed session can
 * open with dozens of them before the first record that carries its cwd: 4–5 MB in, at line 50–60. They are passed
 * over unread and uncounted, inside this byte bound, so such a session no longer holds every agent in its folder.
 */
const CWD_SCAN_BYTES = 32 * 1024 * 1024
const UNCOUNTED_RECORD = /^\{\s*"type"\s*:\s*"file-history-snapshot"/

/**
 * The first `cwd` in a transcript's head and, when asked, its opening flag named `sidechain` (an engine's session
 * store declares it: `scan.sidechain`). One bounded streaming read (the first 20 counted lines, 256 K characters,
 * within 32 MB; transcripts run to hundreds of MB) shared by every file engine that declares its cwd in-file. Without
 * a flag it stops at the first cwd, exactly as it always did.
 */
async function readTranscriptHead(path: string, sidechain: string | null, requestedCwd?: string): Promise<{ cwd: string; side: boolean | undefined } | null> {
  try {
    let cwd = ''
    let side: boolean | undefined
    let malformed = false
    let found: { cwd: string; side: boolean | undefined } | null = null
    const ended = await identityLines(path, { maxBytes: CWD_SCAN_BYTES, maxLines: CWD_SCAN_LINES, maxChars: CWD_SCAN_CHARS },
      start => UNCOUNTED_RECORD.test(start), async line => {
        if (!line.trim()) return false
        let obj: Record<string, unknown>
        try { obj = JSON.parse(line) as Record<string, unknown> } catch { malformed = true; return false }
        if (!obj || typeof obj !== 'object' || Array.isArray(obj)) { malformed = true; return false }
        if (!cwd && typeof obj.cwd === 'string' && obj.cwd) cwd = obj.cwd
        if (cwd && !isAbsolute(cwd)) throw new IdentityReadUnavailable('the transcript working directory is invalid')
        if (sidechain && side === undefined && typeof obj[sidechain] === 'boolean') side = obj[sidechain] as boolean
        if (cwd && requestedCwd && !await sameDir(cwd, requestedCwd)) { found = { cwd, side }; return true }
        if (side === true || (cwd && (!sidechain || side !== undefined))) { found = { cwd, side }; return true }
        return false
      })
    if (found) return found
    if (ended === 'limit') throw new IdentityReadUnavailable('the transcript header exceeds the read limit')
    if (!cwd || (sidechain && side === undefined && malformed)) {
      throw new IdentityReadUnavailable('the transcript header is incomplete or invalid')
    }
    return { cwd, side }
  } catch (error) {
    if (error instanceof IdentityReadUnavailable) throw error
    throw new IdentityReadUnavailable('a transcript header could not be read')
  }
}

async function readTranscriptMeta(path: string): Promise<TranscriptMeta | null> {
  const head = await readTranscriptHead(path, null)
  return head?.cwd ? { cwd: head.cwd } : null
}

async function ompSessionMeta(path: string): Promise<TranscriptMeta | null> {
  if (basename(path) === '__advisor.jsonl') return null
  return readTranscriptMeta(path)
}

/** omp's sessions root. A symlinked `~/.omp` is resolved: /proc names the file the process actually holds. */
async function ompSessionsRoot(): Promise<string> {
  const root = join(homedir(), '.omp', 'agent', 'sessions')
  return realpath(root).catch(() => root)
}

/**
 * omp's folder for a working directory: the path under the home directory (else the absolute path), its
 * separators turned into `-`, with a leading `-`. `/home/me/src/app` → `-src-app`, `/tmp/x` → `-tmp-x`.
 * Measured on 34 of 34 folders. Pi's `--<path>--` rule does not apply.
 */
export function ompSessionFolder(cwd: string, home: string = homedir()): string {
  const inside = cwd === home || cwd.startsWith(`${home}${sep}`)
  const path = inside ? cwd.slice(home.length).replace(/^[\\/]+/, '') : cwd.replace(/^[\\/]+/, '')
  return `-${path.split(/[\\/]+/).filter(Boolean).join('-')}`
}

async function ompHeldSession(pid: number): Promise<RepairedSession | null> {
  let links: string[]
  try { links = await readdir(`/proc/${pid}/fd`) } catch { return null }
  const root = `${await ompSessionsRoot()}/`
  for (const fd of links) {
    let target = ''
    try { target = await readlink(`/proc/${pid}/fd/${fd}`) } catch { continue }
    if (!target.endsWith('.jsonl') || target.includes('__advisor') || !target.startsWith(root)) continue
    return { sessionId: idFromFile(target), transcriptPath: target }
  }
  return null
}

/**
 * How a scan of `engine`'s declared store reads a file (its session store's `scan`), refusing a session another
 * one delegated to.
 *
 * `head`: the first cwd of the opening lines, as `readTranscriptMeta`, but never a file below a `childFolder`
 * segment of the sessions folder it is in, nor one whose FIRST record carrying the boolean `sidechain` flag says
 * true. Claude's subagents write transcripts of their own in the same tree, which a scan by directory cannot tell
 * from a conversation; left in, the youngest subagent file of a parent still running was picked as the session of
 * the agent born next to it (a fork), and Stop capture then recorded that id. Later records are not consulted for
 * the flag: a main transcript can hold sidechain records, and only its opening says what the file is.
 *
 * `first`: the file's first record (engines/sessionFiles.ts), whose id is the session's (the file name only holds
 * it), and never a child's: a subagent's rollout must never become an agent of its own.
 */
function scanMeta(engine: AgentEngine, scan: SessionStoreContract['scan'], cwd: string): (path: string) => Promise<TranscriptMeta | null> {
  if (scan.from === 'first') {
    return async (path) => {
      const meta = await sessionIdentityMetaOf(engine, path)
      return meta && !meta.isSubagent ? { cwd: meta.cwd, sessionId: meta.id || undefined } : null
    }
  }
  return async (path) => {
    // Relative to the sessions folder it is under (the daemon's own, or a moved home's): that folder itself may
    // legitimately sit under a folder of the child's name.
    // The bounded walk already excludes childFolder below each root. Reading the home
    // catalog again here would make every transcript reopen an unrelated configuration.
    const head = await readTranscriptHead(path, scan.sidechain, cwd)
    return head && head.side !== true && head.cwd ? { cwd: head.cwd } : 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 }

async function fileEngineSession(
  root: string | string[],
  cwd: string,
  startedAtMs: number,
  readMeta: (path: string) => Promise<TranscriptMeta | null>,
  opts?: { bornOnly?: boolean; excludedDirectories?: readonly string[]; leafDepth?: number; excludedSessionId?: string },
): Promise<RepairedSession | null> {
  const since = startedAtMs - START_SLACK_MS
  const born: RepairedSession[] = []
  const wrote: RepairedSession[] = []
  // Several roots are one pool, newest first: one conversation in each of two homes is two agents, as in one.
  const files: TranscriptFile[] = []
  const budget = identityScanBudget()
  for (const directory of typeof root === 'string' ? [root] : root) {
    await transcripts(directory, budget, files, opts?.excludedDirectories, 0, opts?.leafDepth)
  }
  files.sort((a, b) => b.mtimeMs - a.mtimeMs || (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))
  for (const file of files) {
    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 }
    // A fork's source can still be within the process start-time slack. Removing
    // it before uniqueness is decided also lets the fork's own new file be found.
    if (found.sessionId === opts?.excludedSessionId) continue
    ;(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. */
async function reportMissingSqliteOnce(): Promise<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[], excludedSessionId?: string): 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') await reportMissingSqliteOnce()
    return null
  }
  const rows = result.rows
  // These queries return at most two rows. Removing the source from that
  // truncated result cannot establish that the remaining row is unique.
  if (rows.length !== 1) return null // 0 = nothing to adopt, >1 = ambiguous
  const id = rows[0].id
  return typeof id === 'string' && id && id !== excludedSessionId ? { sessionId: id } : null
}

/**
 * Where an OpenCode store keeps its sessions: OpenCode 2's `session_v2`, which has the same columns, when the
 * store has it, else OpenCode 1's `session`. A v2 store still holds the v1 table, only what v1 wrote.
 */
async function opencodeSessionTable(dbPath: string): Promise<'session_v2' | 'session'> {
  const found = await sqliteReadAll(dbPath, "SELECT name FROM sqlite_master WHERE type='table' AND name='session_v2'", [], { maxBuffer: 4096 })
  return found.ok && found.rows.length > 0 ? 'session_v2' : 'session'
}

/** 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 } | undefined,
): 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 identityHead(path, 5)
    const root = recordCwd(head.lines, COPILOT_CWD)
    if (!root || !isAbsolute(root)) throw new IdentityReadUnavailable(head.complete
      ? 'the session header is incomplete or invalid' : 'the session header exceeds the read limit')
    return root ? { cwd: root, sessionId: basename(dirname(path)) } : null
  }, opts)
}

/**
 * The session a live process of an engine with a declared store is running (engines/sessionStoreContracts.ts), in
 * every one of its sessions folders: the daemon's own and each home the person moved (lib/engineHomes.ts), or the
 * agent's own profile alone. The default alone left an agent in a moved home unbound.
 *
 * A process that names its own session in a record (`live.record`) is asked first: unlike a scan by folder, that
 * also identifies an old process in a busy project. One that holds its session file open (`live.open`) is only
 * ever matched by that file once its pid is known (the October 6 parallel-create incident: the only file in a
 * folder can belong to a sibling whose file opened first), and left unbound until then rather than guessed.
 */
async function storeSession(
  engine: AgentEngine,
  store: SessionStoreContract,
  cwd: string,
  startedAtMs: number,
  opts?: { bornOnly?: boolean; excludedSessionId?: string; pid?: number; codexHome?: string; expectedProcess?: ProcessIdentity; nativeBudget?: NativeEvidenceBudget },
): Promise<RepairedSession | null> {
  const scan = scanMeta(engine, store.scan, cwd)
  if ('record' in store.live && opts?.pid) {
    const exact = await processSessionEvidence(engine, opts.pid, cwd, startedAtMs)
    exact.verify()
    // A process that names a conversation it has not written yet has none: a folder scan would guess a sibling's.
    if (exact.session || exact.unwritten) return exact.session
  }
  const sessions = repairRoots(engine, opts?.codexHome)
  const found = opts?.pid && 'open' in store.live
    ? await openFileSessionOf(engine, opts.pid, sessions, cwd,
      { expected: opts.expectedProcess, budget: opts.nativeBudget, excludedSessionId: opts.excludedSessionId })
    : await fileEngineSession(sessions, cwd, startedAtMs, scan,
      { ...opts, ...(store.scan.from === 'head' ? { excludedDirectories: [store.scan.childFolder] } : {}) })
  // The login shell may adopt another home during any native read. Its unseen candidates
  // invalidate this pool; an explicit profile remains independent of unrelated homes.
  if (repairRoots(engine, opts?.codexHome).join('\0') !== sessions.join('\0')) {
    throw new IdentityReadUnavailable('the known session homes changed during discovery')
  }
  return found
}

export async function findLiveSession(
  engine: AgentEngine,
  cwd: string,
  startedAtMs: number,
  // codexHome: the specific agent's own profile (its CODEX_HOME), when it isn't this machine's default —
  // see RegisteredSession.codexHome. Read only for an engine whose sessions follow one (`sessions.profile`).
  // A known fork source cannot identify the child through a file/DB pool or a
  // descriptor opened for copying. Exact native current-session records still can.
  opts?: { bornOnly?: boolean; excludedSessionId?: string; pid?: number; codexHome?: string; hermesHome?: string; expectedProcess?: ProcessIdentity; nativeBudget?: NativeEvidenceBudget },
): Promise<RepairedSession | null> {
  const store = sessionStoreOf(engine)
  if (store) return storeSession(engine, store, cwd, startedAtMs, opts)
  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)
  // Native identity is eager. Optional interpretation cannot keep a process unbound.
  switch (engine) {
    case 'omp': {
      // The file the process holds is exact. Without a pid, only this directory's folder is scanned:
      // the whole store holds every project's sessions and runs out of the scan's entry budget.
      const held = opts?.pid ? await ompHeldSession(opts.pid) : null
      if (held) return held
      return fileEngineSession(join(await ompSessionsRoot(), ompSessionFolder(cwd)), cwd, startedAtMs, ompSessionMeta, 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; Muse
      // keeps more folders of its own there (`tool-outputs/`, `approval-review/`), so nothing below a session
      // folder is walked (MUSE_SESSION_FOLDER_DEPTH).
      return fileEngineSession(join(env.MUSE_HOME, 'sessions'), cwd, startedAtMs, async (path) => {
        if (path.includes(`${sep}subagent${sep}`)) 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.
        const identity = await museSessionIdentity(path, root => sameDir(root, cwd))
        return identity ? { ...identity, sessionId: basename(dirname(path)) } : null
      }, { ...opts, leafDepth: MUSE_SESSION_FOLDER_DEPTH })
    }
    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 identityFile(join(group, '.cwd')).catch(error => {
          if (error instanceof IdentityReadUnavailable) throw error
          throw new IdentityReadUnavailable('the session working directory is unavailable')
        })).trim()
        if (!isAbsolute(root)) throw new IdentityReadUnavailable('the session working directory is invalid')
        return root ? { cwd: root, sessionId: basename(sessionDir) } : null
      }, opts)
    case 'opencode': {
      // time_created is epoch MILLISECONDS here.
      const database = join(env.OPENCODE_DATA_DIR, 'opencode.db')
      return dbEngineSession(
        database,
        `SELECT id FROM ${await opencodeSessionTable(database)} 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)],
        opts?.excludedSessionId,
      )
    }
    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)],
        opts?.excludedSessionId,
      )
    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 found = await readStorePool(HERMES_HOMES, env.HERMES_HOME, {
        sql: `SELECT ${HERMES_ID_SQL} AS id, ${HERMES_SOURCE_SQL} AS source, started_at, typeof(cwd) AS cwd_type,`
          + " CASE WHEN typeof(cwd) = 'text' AND length(CAST(cwd AS BLOB)) <= 4096 AND instr(CAST(cwd AS BLOB), x'00') = 0 THEN cwd END AS cwd"
          + ' FROM sessions LIMIT 8193;',
        params: [], maxRows: 8192, maxBuffer: 40 * 1024 * 1024,
        columns: ['id', 'source', 'cwd', 'started_at'], knownHome: opts?.hermesHome,
      })
      const candidates: RepairedSession[] = []
      for (const { home, aliases, row } of found) {
        // Editor/gateway rows may have no working directory; they cannot claim this process's cwd.
        if (row.cwd === null && row.cwd_type === 'null') continue
        if (typeof row.cwd !== 'string') {
          throw new IdentityReadUnavailable('a Hermes store contains invalid discovery evidence')
        }
        if (!dirs.includes(row.cwd)) continue
        if (typeof row.started_at !== 'number' || !Number.isFinite(row.started_at)) {
          throw new IdentityReadUnavailable('a Hermes store contains invalid discovery evidence')
        }
        if (row.started_at < Math.trunc(sinceMs / 1000)) continue
        if (typeof row.source !== 'string') throw new IdentityReadUnavailable('a Hermes session source is unavailable')
        if (!isInteractiveSource(HERMES_SOURCE, row.source)) continue
        if (typeof row.id !== 'string' || !HERMES_HISTORY_ID_RE.test(row.id)) {
          throw new IdentityReadUnavailable('a Hermes store contains an invalid conversation id')
        }
        if (opts?.hermesHome && !aliases.includes(opts.hermesHome)) continue
        if (row.id === opts?.excludedSessionId) continue
        candidates.push({ sessionId: row.id, hermesHome: opts?.hermesHome ?? home })
      }
      return candidates.length === 1 ? candidates[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)],
        opts?.excludedSessionId,
      )
    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 nativeProcessSession('copilot', env.COPILOT_HOME, opts.pid) : null
      if (locked) {
        const transcriptPath = await transcriptOf('copilot', env.COPILOT_HOME, locked)
        if (await nativeProcessSession('copilot', env.COPILOT_HOME, opts!.pid!) !== locked) {
          throw new IdentityReadUnavailable('the process conversation changed during transcript lookup')
        }
        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 nativeProcessSession('agy', env.AGY_HOME, pid)
  if (!conversationId) return null
  const transcriptPath = await transcriptOf('agy', env.AGY_HOME, conversationId)
  if (await nativeProcessSession('agy', env.AGY_HOME, pid) !== conversationId) {
    throw new IdentityReadUnavailable('the process conversation changed during transcript lookup')
  }
  // 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 transcript behind a session id a process names on its own command line (`claude --resume <id>`,
 * `codex resume <id>`) — the file `registry.register` insists on for the engines with a declared store, which
 * argv does not carry. Found as the store declares (`byId`): in any one project folder directly below a sessions
 * folder (Claude's cwd encoding is its own to define, so the folders are listed rather than the name derived), or
 * by the walk for a file whose name holds the id (Codex's rollouts). 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; cwd?: string },
): Promise<string | null> {
  if (engine === 'pi') {
    // Pi allocates an ID before its first reply creates the file. Look up that
    // exact ID again at Close, including after exit, without guessing by mtime.
    if (!opts?.cwd || !PI_SESSION_ID.test(sessionId)) {
      throw new IdentityReadUnavailable('the Pi conversation location is unavailable', 'The Pi conversation location is unavailable.')
    }
    // The folder and header are native identity, available even when Pi's history reader cannot load.
    const directory = join(env.PI_HOME, 'agent', 'sessions', piSessionFolder(opts.cwd))
    const workspaces = exactWorkspaces()
    return exactTranscript([directory], { kind: 'directory', matches: file => file.endsWith(`_${sessionId}.jsonl`) }, {
      accepts: async (path, version) => {
        const head = await readSessionHeader(PI_HEADER, async bytes => (await identityBytes(path, bytes, version)).toString('utf8'))
          .catch(() => null)
        if (!head || typeof head === 'symbol') {
          throw new IdentityReadUnavailable('the Pi conversation file could not be read', 'The Pi conversation file could not be read.')
        }
        return head.sessionId === sessionId && await workspaces.same(head.cwd, opts.cwd!)
      },
      verify: workspaces.verify,
      ambiguous: 'More than one file matches this Pi conversation.',
    })
  }
  if (!/^[0-9a-f-]{16,128}$/i.test(sessionId)) return null
  const byId = sessionStoreOf(engine)?.byId
  if (!byId) return null
  // In every folder the registry takes a transcript from (registry.validTranscriptPath): the daemon's own and
  // each home the person moved in their shell profile (lib/engineHomes.ts), or an agent's own profile alone.
  // Only the default folders were looked in, so a resume typed into a pane for a conversation in a moved home
  // found no file and never bound, though the registry would have taken it.
  const roots = repairRoots(engine, opts?.codexHome)
  const found = await (byId.layout === 'walk'
    ? exactTranscript(roots, { kind: 'walk', matches: file => file.endsWith(byId.suffix) && file.includes(sessionId) }, {
      accepts: async (path, version) => {
        const meta = await sessionIdentityMetaOf(engine, path, version)
        if (!meta?.id || !byId.id.test(meta.id)) throw new IdentityReadUnavailable('the exact rollout header has no conclusive conversation id')
        return meta.id === sessionId
      },
    })
    : exactTranscript(roots, { kind: 'projects', filename: `${sessionId}${byId.suffix}` }))
  if (repairRoots(engine, opts?.codexHome).join('\0') !== roots.join('\0')) {
    throw new IdentityReadUnavailable('the known session homes changed during exact lookup')
  }
  return found
}

/** Complete native evidence is the sole descriptor authority for discovery and Stop. */
export { nativeOpenFiles as openFiles, nativeProcessFiles as processFilesOf } from './nativeConversation.js'
export function openFileSessionOf(engine: AgentEngine, pid: number, roots: string | string[], cwd: string,
  options: NativeConversationOptions = {},
): Promise<RepairedSession | null> {
  return nativeOpenFileSession(engine, pid, typeof roots === 'string' ? [roots] : roots, cwd, options)
}

/**
 * The session a live process names in a record of its own, for an engine that keeps one (`live.record`):
 * `<home>/<folder>/<pid><suffix>` beside each of its sessions folders, a moved home's too (lib/engineHomes.ts):
 * the default alone was read, so a process in a moved home was never named by its own record. Removed at exit,
 * so Stop captures it before signalling the engine. Null for another engine.
 */
export async function processSessionOf(engine: AgentEngine, pid: number, cwd: string, startedAtMs: number): Promise<RepairedSession | null> {
  const proof = await processSessionEvidence(engine, pid, cwd, startedAtMs)
  proof.verify()
  return proof.session
}

/** Stop retains this proof across its final process probe and any fallback lookup. `unwritten` is the conversation
 * the process names before its first prompt writes it: there is no session yet, and nothing to look for elsewhere. */
export async function processSessionEvidence(engine: AgentEngine, pid: number, cwd: string, startedAtMs: number,
  budget = new NativeEvidenceBudget(),
): Promise<{ session: RepairedSession | null; unwritten?: string; verify(): void }> {
  const live = sessionStoreOf(engine)?.live
  if (!live || !('record' in live) || !Number.isSafeInteger(pid) || pid <= 0 || !Number.isFinite(startedAtMs)) {
    return { session: null, verify() {} }
  }
  const paths = new NativePaths(budget)
  const rule = live.record
  let result: { sessionId: string; transcriptPath: string | null } | null = null
  let selected: string | undefined
  const roots = repairRoots(engine)
  const records: { file: string; text: string | null }[] = []
  const read = (file: string) => identityFile(file).catch(error => {
    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null
    throw error
  })
  for (const sessions of roots) {
    const file = join(dirname(sessions), rule.folder, `${pid}${rule.suffix}`)
    await paths.resolve(file, true)
    const text = await read(file)
    records.push({ file, text })
    if (text === null) continue
    const found = await processRecord(engine, rule, text, pid, cwd, startedAtMs)
    if (!found) continue
    if (result && (result.sessionId !== found.sessionId || result.transcriptPath !== found.transcriptPath)) {
      throw new IdentityReadUnavailable('current process records name different conversations')
    }
    result = found
    selected = file
  }
  // A conversation can change inside the same process while another home is being read.
  // Recheck absent/stale claims too: a newly created claim invalidates the earlier pool.
  // Read the authoritative claim last, retaining the whole pool for the caller's final fence.
  // Stop still has an asynchronous process probe to finish before it can use this claim.
  const recheck = [...records.filter(record => record.file !== selected), ...records.filter(record => record.file === selected)]
  for (const { file, text } of recheck) {
    if (await read(file) !== text) throw new IdentityReadUnavailable('the process records changed during discovery')
  }
  const verify = () => {
    budget.step()
    if (repairRoots(engine).join('\0') !== roots.join('\0')) throw new IdentityReadUnavailable('the known session homes changed during discovery')
    paths.verify()
    // No asynchronous work follows the selected record. This includes negative and stale claims.
    for (const { file, text } of recheck) verifyProcessRecord(file, text, budget)
  }
  return result?.transcriptPath
    ? { session: { sessionId: result.sessionId, transcriptPath: result.transcriptPath }, verify }
    : { session: null, ...(result ? { unwritten: result.sessionId } : {}), verify }
}

type ProcessRecordRule = Extract<SessionStoreContract['live'], { record: unknown }>['record']

async function processRecord(engine: AgentEngine, rule: ProcessRecordRule, text: string, pid: number, cwd: string, startedAtMs: number): Promise<{ sessionId: string; transcriptPath: string | null } | null> {
  try {
    const record = JSON.parse(text)
    if (!record || typeof record !== 'object' || Array.isArray(record)
      || !Number.isSafeInteger(record[rule.pid]) || record[rule.pid] <= 0 || typeof record[rule.start] !== 'string'
      || !Number.isFinite(Date.parse(record[rule.start]))
      || typeof record[rule.cwd] !== 'string' || !isAbsolute(record[rule.cwd])
      || typeof record[rule.id] !== 'string' || !record[rule.id]) {
      throw new IdentityReadUnavailable('the process record is incomplete or invalid')
    }
    const start = record[rule.start]
    const folder = record[rule.cwd]
    const sessionId = record[rule.id]
    // Claude's procStart is UTC in current builds, 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[rule.pid] !== pid || ![Date.parse(start), Date.parse(`${start} UTC`)].includes(startedAtMs)) return null
    if (!await sameDir(folder, cwd)) throw new IdentityReadUnavailable('the current process record names a different working directory')
    // Claude Code writes the transcript with the first prompt, so a harness opened and never used has none. Held, its
    // Change agent waited forever (2026-10-21). A lookup that cannot finish still throws; only a missing file is null.
    // The lookup's own id test answers null too, and a malformed id is no proof the conversation is empty.
    if (!/^[0-9a-f-]{16,128}$/i.test(sessionId)) throw new IdentityReadUnavailable('the process record is incomplete or invalid')
    return { sessionId, transcriptPath: await findResumedTranscript(engine, sessionId) }
  } catch (error) {
    if (error instanceof IdentityReadUnavailable) throw error
    if (error instanceof SyntaxError) throw new IdentityReadUnavailable('the process record is incomplete or invalid')
    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null
    throw new IdentityReadUnavailable('the process record could not be read')
  }
}