Loading files
50b3be768This file is pinned to the selected release. Download the original to open it in your design tool.
import { afterEach, describe, expect, it, vi } from 'vitest'
import { mkdirSync, mkdtempSync, rmSync, utimesSync, writeFileSync } from 'fs'
import { tmpdir } from 'os'
import { join } from 'path'
import { claudeContinuation } from './sessionRepair.js'
/**
* Repair binds a live launcher back to a session the daemon lost track of. The danger is not failing to
* find one — that only costs a tile until the next turn — it is finding the WRONG one and pointing an
* agent at another agent's transcript. So these tests are mostly about when it must refuse.
*/
const dirs: string[] = []
afterEach(() => {
for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true })
delete process.env.GROK_HOME
vi.resetModules()
})
function tempRoot(): string {
const dir = mkdtempSync(join(tmpdir(), 'repair-'))
dirs.push(dir)
return dir
}
/** A claude-shaped transcript: `<id>.jsonl` under a project dir, first line carrying its cwd. */
function writeTranscript(root: string, project: string, id: string, cwd: string, mtimeMs: number): void {
const dir = join(root, project)
mkdirSync(dir, { recursive: true })
const file = join(dir, `${id}.jsonl`)
writeFileSync(file, `${JSON.stringify({ type: 'session', cwd, id })}\n`)
utimesSync(file, new Date(mtimeMs), new Date(mtimeMs))
}
async function load(claudeProjectsDir: string) {
vi.resetModules()
process.env.CLAUDE_PROJECTS_DIR = claudeProjectsDir
return import('./sessionRepair.js')
}
const STARTED_AT = Date.parse('2026-08-03T09:00:00Z')
const CWD = '/Users/demo/work/project'
describe('session repair', () => {
it('finds the session the running engine started in this directory', async () => {
const root = tempRoot()
writeTranscript(root, 'proj', 'sess-live', CWD, STARTED_AT + 5_000)
const { findLiveSession } = await load(root)
await expect(findLiveSession('claude', CWD, STARTED_AT))
.resolves.toMatchObject({ sessionId: 'sess-live' })
})
it('finds the cwd even when the transcript opens with bookkeeping lines', async () => {
// Claude's first records are `leafUuid` / `mode` with no cwd anywhere in them. A first-line-only read
// therefore matched NO claude session on a real machine — the repair returned null for a pane whose
// transcript was sitting right there.
const root = tempRoot()
const dir = join(root, 'proj')
mkdirSync(dir, { recursive: true })
const file = join(dir, 'sess-meta-first.jsonl')
writeFileSync(file, [
JSON.stringify({ type: 'summary', leafUuid: 'x', sessionId: 'sess-meta-first' }),
JSON.stringify({ type: 'x-mode', mode: 'default', sessionId: 'sess-meta-first' }),
JSON.stringify({ type: 'user', cwd: CWD, sessionId: 'sess-meta-first' }),
'',
].join('\n'))
utimesSync(file, new Date(STARTED_AT + 5_000), new Date(STARTED_AT + 5_000))
const { findLiveSession } = await load(root)
await expect(findLiveSession('claude', CWD, STARTED_AT))
.resolves.toMatchObject({ sessionId: 'sess-meta-first' })
})
it('ignores a session that predates the process now running the pane', async () => {
// A transcript older than the engine cannot be what it is running — that would be a resume, and
// resumes name their id on the command line (discoverTmuxResumes handles those).
const root = tempRoot()
writeTranscript(root, 'proj', 'sess-yesterday', CWD, STARTED_AT - 24 * 3_600_000)
const { findLiveSession } = await load(root)
await expect(findLiveSession('claude', CWD, STARTED_AT)).resolves.toBeNull()
})
it('ignores a session belonging to a different directory', async () => {
const root = tempRoot()
writeTranscript(root, 'other', 'sess-elsewhere', '/Users/demo/other', STARTED_AT + 5_000)
const { findLiveSession } = await load(root)
await expect(findLiveSession('claude', CWD, STARTED_AT)).resolves.toBeNull()
})
it('does not hand a just-exited session to the engine that replaced it', async () => {
// Real sequence: `/exit`, then relaunch in the same pane seconds later. The dead transcript's last
// write is still fresh, so a mtime-only rule with a generous slack bound the NEW agent to the OLD
// session id (measured on a live pane). Its file was created before this process and has not been
// written to since it started — neither tier may accept it.
const root = tempRoot()
const dir = join(root, 'proj')
mkdirSync(dir, { recursive: true })
const file = join(dir, 'sess-just-exited.jsonl')
writeFileSync(file, `${JSON.stringify({ type: 'user', cwd: CWD })}\n`)
const born = Date.now() // the temp file's real birthtime
const lastWrite = born + 20_000 // it wrote, then the user exited…
utimesSync(file, new Date(lastWrite), new Date(lastWrite))
const { findLiveSession } = await load(root)
// …and the replacement process started AFTER that last write.
await expect(findLiveSession('claude', CWD, born + 40_000)).resolves.toBeNull()
})
it('still finds a RESUMED session, whose file is old but freshly written', async () => {
// The other side of the same coin: `claude --resume` writes to a transcript created earlier. A write
// that lands after the process started is what marks it as the one being run right now.
const root = tempRoot()
const dir = join(root, 'proj')
mkdirSync(dir, { recursive: true })
const file = join(dir, 'sess-resumed.jsonl')
writeFileSync(file, `${JSON.stringify({ type: 'user', cwd: CWD })}\n`)
const born = Date.now()
const startedAt = born + 30_000 // the engine started well after the file was created…
utimesSync(file, new Date(startedAt + 10_000), new Date(startedAt + 10_000)) // …and wrote after that
const { findLiveSession } = await load(root)
await expect(findLiveSession('claude', CWD, startedAt))
.resolves.toMatchObject({ sessionId: 'sess-resumed' })
})
it('refuses to choose when two agents are running in the same directory', async () => {
// The whole point: a wrong guess wires one agent's tile to the other's transcript, and nothing
// downstream could tell. Staying invisible for one more turn is the cheaper failure.
const root = tempRoot()
writeTranscript(root, 'proj', 'sess-a', CWD, STARTED_AT + 5_000)
writeTranscript(root, 'proj', 'sess-b', CWD, STARTED_AT + 9_000)
const { findLiveSession } = await load(root)
await expect(findLiveSession('claude', CWD, STARTED_AT)).resolves.toBeNull()
})
it('picks the transcript path along with the id, so the session can actually be tailed', async () => {
const root = tempRoot()
writeTranscript(root, 'proj', 'sess-live', CWD, STARTED_AT + 1_000)
const { findLiveSession } = await load(root)
const found = await findLiveSession('claude', CWD, STARTED_AT)
expect(found?.transcriptPath).toBe(join(root, 'proj', 'sess-live.jsonl'))
})
it('skips sidecar files that are not transcripts', async () => {
// Command Code writes `<id>.checkpoints.jsonl` next to the real transcript; adopting one would
// register a session id that no reader can follow.
const root = tempRoot()
const dir = join(root, 'proj')
mkdirSync(dir, { recursive: true })
const sidecar = join(dir, 'sess-live.checkpoints.jsonl')
writeFileSync(sidecar, `${JSON.stringify({ cwd: CWD })}\n`)
utimesSync(sidecar, new Date(STARTED_AT + 5_000), new Date(STARTED_AT + 5_000))
const { findLiveSession } = await load(root)
await expect(findLiveSession('claude', CWD, STARTED_AT)).resolves.toBeNull()
})
it('says nothing rather than throwing when the engine store is missing', async () => {
const { findLiveSession } = await load(join(tempRoot(), 'does-not-exist'))
await expect(findLiveSession('claude', CWD, STARTED_AT)).resolves.toBeNull()
})
it('has no answer for cursor, and says so instead of guessing', async () => {
// Cursor transcripts are located by id, not listed by directory; its resumes have their own path.
const { findLiveSession } = await load(tempRoot())
await expect(findLiveSession('cursor', CWD, STARTED_AT)).resolves.toBeNull()
})
})
/**
* Muse opens sessions of its OWN under the user's workspace — memory reminders are the ones seen live.
* They share the workspace_root, sit at the same depth, and are BORN LATER, so they beat the real session
* on every signal repair used to look at. Measured on a live machine: the daemon tailed an 11-line
* reminder session while the conversation ran on in another file, and web and device received nothing.
*/
describe('session repair — muse', () => {
/** `<MUSE_HOME>/sessions/YYYY/MM/DD/<uuid>/session.jsonl`, with the workspace on line one. */
function writeMuseSession(
home: string,
id: string,
workspace: string,
events: ReadonlyArray<{ scope: string; event: Record<string, unknown> }>,
mtimeMs: number,
): void {
const dir = join(home, 'sessions', '2026', '08', '06', id)
mkdirSync(dir, { recursive: true })
const file = join(dir, 'session.jsonl')
const lines = [JSON.stringify({ payload: { record: { workspace_root: workspace } } })]
for (const { scope, event } of events) lines.push(JSON.stringify({ payload: { kind: scope, event } }))
writeFileSync(file, `${lines.join('\n')}\n`)
utimesSync(file, new Date(mtimeMs), new Date(mtimeMs))
}
// `payload.kind` is the discriminator: a RUN is a conversation turn, a TASK is scheduler bookkeeping.
// Note the run is asserted WITHOUT a prompt — a scheduled run is a real turn nobody typed.
const runTurn = { scope: 'run', event: { kind: 'started', prompt: 'xin chao' } }
const scheduledRun = { scope: 'run', event: { kind: 'started', prompt: '' } }
const taskOnly = [
{ scope: 'task', event: { kind: 'started', task_id: 't-1' } },
{ scope: 'task', event: { kind: 'status', message: 'opening' } },
]
async function loadMuse(museHome: string) {
vi.resetModules()
process.env.MUSE_HOME = museHome
return import('./sessionRepair.js')
}
it('ignores a session nobody typed into, and binds the one they did', async () => {
const home = tempRoot()
writeMuseSession(home, 'real-session', CWD, [runTurn], STARTED_AT + 5_000)
writeMuseSession(home, 'reminder-session', CWD, taskOnly, STARTED_AT + 9_000) // younger: used to win
const { findLiveSession } = await loadMuse(home)
await expect(findLiveSession('muse', CWD, STARTED_AT))
.resolves.toMatchObject({ sessionId: 'real-session' })
})
it('binds a SCHEDULED run, whose prompt is empty because nobody typed it', async () => {
// The filter must key on the run lifecycle, not on the presence of a prompt: a scheduled run is a
// real turn the scheduler triggered. Requiring a prompt would leave those sessions unbindable.
const home = tempRoot()
writeMuseSession(home, 'scheduled-session', CWD, [scheduledRun], STARTED_AT + 5_000)
const { findLiveSession } = await loadMuse(home)
await expect(findLiveSession('muse', CWD, STARTED_AT))
.resolves.toMatchObject({ sessionId: 'scheduled-session' })
})
it('binds nothing at all when the only candidate has no user turn', async () => {
const home = tempRoot()
writeMuseSession(home, 'reminder-session', CWD, taskOnly, STARTED_AT + 5_000)
const { findLiveSession } = await loadMuse(home)
await expect(findLiveSession('muse', CWD, STARTED_AT)).resolves.toBeNull()
})
it('still refuses when two real sessions share a directory', async () => {
// The filter narrows the field; it must not resolve a genuine tie. Two sessions someone typed into
// is the case the "one muse agent per directory" rule prevents upstream — repair stays fail-closed,
// because guessing here wires one agent's tile to the other's transcript.
const home = tempRoot()
writeMuseSession(home, 'session-a', CWD, [runTurn], STARTED_AT + 5_000)
writeMuseSession(home, 'session-b', CWD, [runTurn], STARTED_AT + 6_000)
const { findLiveSession } = await loadMuse(home)
await expect(findLiveSession('muse', CWD, STARTED_AT)).resolves.toBeNull()
})
})
describe('session repair — Grok', () => {
it('derives cwd and session id from the encoded updates.jsonl layout', async () => {
const home = tempRoot()
const id = '8184b11d-175e-46cb-9cee-cf41cafe70d2'
const file = join(home, 'sessions', encodeURIComponent(CWD), id, 'updates.jsonl')
mkdirSync(join(file, '..'), { recursive: true })
writeFileSync(file, '{}\n')
vi.resetModules()
process.env.GROK_HOME = home
const { findLiveSession } = await import('./sessionRepair.js')
await expect(findLiveSession('grok', CWD, STARTED_AT)).resolves.toEqual({ sessionId: id, transcriptPath: file })
})
it('reads the .cwd sidecar used by Grok for a long-path hash directory', async () => {
const home = tempRoot()
const id = '98ee3dac-175e-46cb-9cee-cf41cafe70d2'
const group = join(home, 'sessions', 'cwd-hash-123')
const file = join(group, id, 'updates.jsonl')
mkdirSync(join(file, '..'), { recursive: true })
writeFileSync(join(group, '.cwd'), `${CWD}\n`)
writeFileSync(file, '{}\n')
vi.resetModules()
process.env.GROK_HOME = home
const { findLiveSession } = await import('./sessionRepair.js')
await expect(findLiveSession('grok', CWD, STARTED_AT)).resolves.toEqual({ sessionId: id, transcriptPath: file })
})
})
/** A codex rollout-shaped transcript: session_meta line one, under <codexHome>/sessions/. */
function writeCodexRollout(codexHome: string, id: string, cwd: string, mtimeMs: number): string {
const dir = join(codexHome, 'sessions')
mkdirSync(dir, { recursive: true })
const file = join(dir, `rollout-2026-08-03T09-00-00-${id}.jsonl`)
writeFileSync(file, `${JSON.stringify({ type: 'session_meta', payload: { id, cwd } })}\n`)
utimesSync(file, new Date(mtimeMs), new Date(mtimeMs))
return file
}
describe('session repair — Codex profiles', () => {
it('scans the agent\'s own codexHome profile, not the default', async () => {
const profile = tempRoot()
const id = 'a1b2c3d4-1111-4a4a-8a8a-000000000001'
const file = writeCodexRollout(profile, id, CWD, STARTED_AT + 5_000)
vi.resetModules()
const { findLiveSession } = await import('./sessionRepair.js')
await expect(findLiveSession('codex', CWD, STARTED_AT, { codexHome: profile, bornOnly: true }))
.resolves.toEqual({ sessionId: id, transcriptPath: file })
})
it('finds nothing when no codexHome override is given and the rollout lives in a custom profile', async () => {
const profile = tempRoot()
const defaultHome = tempRoot() // an empty stand-in default, so the assertion cannot depend on this machine's real ~/.codex
const id = 'a1b2c3d4-1111-4a4a-8a8a-000000000002'
writeCodexRollout(profile, id, CWD, STARTED_AT + 5_000)
vi.resetModules()
process.env.CODEX_HOME = defaultHome
const { findLiveSession } = await import('./sessionRepair.js')
try {
// No opts.codexHome: falls back to the default CODEX_HOME, which does not contain this rollout.
await expect(findLiveSession('codex', CWD, STARTED_AT, { bornOnly: true })).resolves.toBeNull()
} finally {
delete process.env.CODEX_HOME
}
})
})
describe('claudeContinuation', () => {
it('follows a continued-in marker to the new session file', async () => {
const dir = tempRoot()
const oldPath = join(dir, 'old-session.jsonl')
const newId = 'b6758945-6852-4214-8a42-2b448d8ad391'
writeFileSync(
oldPath,
[
JSON.stringify({ type: 'session', cwd: CWD, id: 'old-session' }),
JSON.stringify({ type: 'continued-in', sessionId: 'old-session', continuedInSessionId: newId }),
].join('\n') + '\n',
)
writeFileSync(join(dir, `${newId}.jsonl`), `${JSON.stringify({ type: 'session', cwd: CWD, id: newId })}\n`)
await expect(claudeContinuation(oldPath)).resolves.toEqual({
sessionId: newId,
transcriptPath: join(dir, `${newId}.jsonl`),
})
})
it('returns null when the transcript has not rotated', async () => {
const dir = tempRoot()
const path = join(dir, 'session.jsonl')
writeFileSync(path, `${JSON.stringify({ type: 'session', cwd: CWD, id: 'session' })}\n`)
await expect(claudeContinuation(path)).resolves.toBeNull()
})
it('returns null when the continued-in target file does not exist yet', async () => {
const dir = tempRoot()
const oldPath = join(dir, 'old-session.jsonl')
writeFileSync(
oldPath,
`${JSON.stringify({ type: 'continued-in', continuedInSessionId: 'not-written-yet' })}\n`,
)
await expect(claudeContinuation(oldPath)).resolves.toBeNull()
})
it('finds the marker even past a large tail (bounded read)', async () => {
const dir = tempRoot()
const oldPath = join(dir, 'old-session.jsonl')
const newId = 'b6758945-6852-4214-8a42-2b448d8ad391'
const filler = JSON.stringify({ type: 'assistant', text: 'x'.repeat(200) })
const lines = Array.from({ length: 50 }, () => filler)
lines.push(JSON.stringify({ type: 'continued-in', continuedInSessionId: newId }))
writeFileSync(oldPath, lines.join('\n') + '\n')
writeFileSync(join(dir, `${newId}.jsonl`), `${JSON.stringify({ type: 'session', cwd: CWD, id: newId })}\n`)
await expect(claudeContinuation(oldPath)).resolves.toEqual({
sessionId: newId,
transcriptPath: join(dir, `${newId}.jsonl`),
})
})
it('returns null for a missing file', async () => {
await expect(claudeContinuation('/nonexistent/path/session.jsonl')).resolves.toBeNull()
})
})