feat(cli): headless session resume — -p --continue chains multi-turn runs

- headless runs persist their finished RunState in the TUI's chat format
  ({projectDataDir}/chats/<id>/) — sessions are interchangeable between the
  TUI and headless surfaces
- levelcode -p --continue [id] resumes the most recent session (or a given
  session_id) by passing previousRun to the agent; TUI conversations can be
  continued headlessly and vice versa
- success result events gain session_id so CI can chain: run 1 → capture
  session_id → run 2 --continue <id>
- missing session → exit 2 with an actionable message
- 7 new tests (store round-trip, resume passthrough, session_id emission,
  no-save-on-failure)

Author: yethikrishna

cli/src/headless/__tests__/run-headless.test.ts

@@ -1,9 +1,14 @@
-import { describe, it, expect } from 'bun:test'
+import { describe, it, expect, beforeEach, afterEach } from 'bun:test'
+import * as fs from 'fs'
+import * as os from 'os'
+import * as path from 'path'
 
 import { runHeadless } from '../run-headless'
+import { loadHeadlessRunState, saveHeadlessRunState } from '../session-store'
+import { setProjectRoot } from '../../project-files'
 
 import type { PrintModeEvent } from '@levelcode/common/types/print-mode'
-import type { LevelCodeClient } from '@levelcode/sdk'
+import type { LevelCodeClient, RunState } from '@levelcode/sdk'
 
 type Sink = { stdout: string[]; stderr: string[] }
 
@@ -162,6 +167,108 @@ describe('runHeadless', () => {
   })
 })
 
+describe('runHeadless session resume', () => {
+  let tmpDir: string
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'hl-resume-'))
+    setProjectRoot(tmpDir)
+  })
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true })
+  })
+
+  it('errors with exit code 2 when --continue finds no session', async () => {
+    const { capture } = makeSink()
+    const { exitCode, result } = await runHeadless({
+      prompt: 'next turn',
+      outputFormat: 'json',
+      agentOverride: null,
+      continueChat: true,
+      client: fakeClient([]),
+      sink: capture,
+    })
+
+    expect(exitCode).toBe(2)
+    expect(result.is_error).toBe(true)
+    expect(String(result.message)).toContain('No resumable session')
+  })
+
+  it('passes the loaded RunState as previousRun to the client', async () => {
+    const state = { sessionState: { mainAgentState: { messageHistory: [] } } } as unknown as RunState
+    const chatId = saveHeadlessRunState(state)
+    expect(chatId).toBeTruthy()
+
+    let sawPreviousRun: unknown
+    const client = {
+      run: async (opts: any) => {
+        sawPreviousRun = opts.previousRun
+        await opts.handleEvent?.({ type: 'text', text: 'resumed' })
+        return state
+      },
+    } as unknown as LevelCodeClient
+
+    const { exitCode, result } = await runHeadless({
+      prompt: 'next turn',
+      outputFormat: 'json',
+      agentOverride: null,
+      continueChat: true,
+      continueId: chatId!,
+      client,
+      sink: makeSink().capture,
+    })
+
+    expect(exitCode).toBe(0)
+    // Saved state round-trips through JSON, so compare by structure.
+    expect(sawPreviousRun).toEqual(state)
+    expect(result.result).toBe('resumed')
+  })
+
+  it('saves the finished run and reports session_id on success', async () => {
+    const state = { sessionState: { mainAgentState: { messageHistory: [] } } } as unknown as RunState
+    const client = {
+      run: async ({ handleEvent }: any) => {
+        await handleEvent?.({ type: 'text', text: 'done' })
+        return state
+      },
+    } as unknown as LevelCodeClient
+
+    const { capture } = makeSink()
+    const { exitCode, result } = await runHeadless({
+      prompt: 'first turn',
+      outputFormat: 'json',
+      agentOverride: null,
+      client,
+      sink: capture,
+    })
+
+    expect(exitCode).toBe(0)
+    expect(result.session_id).toMatch(/^[0-9a-f-]{36}$/)
+
+    // The saved session is resumable
+    const loaded = loadHeadlessRunState(result.session_id as string)
+    expect(loaded).not.toBeNull()
+  })
+
+  it('does not save a session after a failed run', async () => {
+    const client = {
+      run: async () => {
+        throw new Error('boom')
+      },
+    } as unknown as LevelCodeClient
+
+    const { result } = await runHeadless({
+      prompt: 'failing',
+      outputFormat: 'json',
+      agentOverride: null,
+      client,
+      sink: makeSink().capture,
+    })
+
+    expect(result.is_error).toBe(true)
+    expect(result.session_id).toBeUndefined()
+  })
+})
+
 describe('runHeadless failure contract', () => {
   it('reports failure when the run finishes without any output or finish event', async () => {
     const { sink, capture } = makeSink()

cli/src/headless/__tests__/session-store.test.ts

@@ -0,0 +1,72 @@
+import { describe, it, expect, beforeEach, afterEach } from 'bun:test'
+import * as fs from 'fs'
+import * as os from 'os'
+import * as path from 'path'
+
+import { saveHeadlessRunState, loadHeadlessRunState } from '../session-store'
+import { setProjectRoot, getProjectDataDir } from '../../project-files'
+
+import type { RunState } from '@levelcode/sdk'
+
+const makeRunState = (marker: string): RunState =>
+  ({
+    sessionState: {
+      mainAgentState: { messageHistory: [{ role: 'user', content: marker }] },
+    },
+    output: { type: 'lastMessage', value: [] },
+  }) as unknown as RunState
+
+describe('headless session store', () => {
+  let tmpDir: string
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'hl-session-'))
+    setProjectRoot(tmpDir)
+  })
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true })
+  })
+
+  it('save returns a chat id and the state round-trips by id', () => {
+    const state = makeRunState('resume-me')
+    const chatId = saveHeadlessRunState(state)
+
+    expect(chatId).toBeTruthy()
+    expect(chatId).toMatch(/^[0-9a-f-]{36}$/)
+
+    const loaded = loadHeadlessRunState(chatId!)
+    expect(loaded).not.toBeNull()
+    expect(
+      (loaded as unknown as { sessionState: { mainAgentState: { messageHistory: Array<{ content: string }> } } })
+        .sessionState.mainAgentState.messageHistory[0]!.content,
+    ).toBe('resume-me')
+
+    // Both files exist (TUI-compatible format)
+    const chatDir = path.join(getProjectDataDir(), 'chats', chatId!)
+    expect(fs.existsSync(path.join(chatDir, 'run-state.json'))).toBe(true)
+    expect(fs.existsSync(path.join(chatDir, 'chat-messages.json'))).toBe(true)
+  })
+
+  it('load without an id returns the most recent saved session', () => {
+    const first = saveHeadlessRunState(makeRunState('first'))
+    const second = saveHeadlessRunState(makeRunState('second'))
+
+    expect(first).toBeTruthy()
+    expect(second).toBeTruthy()
+
+    const loaded = loadHeadlessRunState()
+    expect(
+      (loaded as unknown as { sessionState: { mainAgentState: { messageHistory: Array<{ content: string }> } } })
+        .sessionState.mainAgentState.messageHistory[0]!.content,
+    ).toBe('second')
+  })
+
+  it('returns null when no sessions exist', () => {
+    expect(loadHeadlessRunState()).toBeNull()
+  })
+
+  it('returns null for an unknown chat id', () => {
+    expect(loadHeadlessRunState('no-such-id')).toBeNull()
+  })
+})

cli/src/headless/run-headless.ts

@@ -22,6 +22,7 @@ import { getProjectRoot } from '../project-files'
 import { initializeApp } from '../init/init-app'
 import { getLevelCodeClient } from '../utils/levelcode-client'
 import { isSensitiveFile } from '../utils/create-run-config'
+import { saveHeadlessRunState, loadHeadlessRunState } from './session-store'
 
 import type { PrintModeEvent } from '@levelcode/common/types/print-mode'
 import type { FileFilter, LevelCodeClient } from '@levelcode/sdk'
@@ -38,6 +39,9 @@ export type HeadlessOptions = {
   lenientExit?: boolean
   /** Test seam: run against this client instead of the real one. */
   client?: LevelCodeClient
+  /** Resume the most recent conversation (or continueId if provided). */
+  continueChat?: boolean
+  continueId?: string | null
   /** Test seam: capture output instead of writing to the process streams. */
   sink?: {
     stdout: (chunk: string) => void
@@ -142,10 +146,30 @@ export async function runHeadless(options: HeadlessOptions): Promise<HeadlessRes
     }
   }
 
+  let previousRun: unknown
+  if (options.continueChat) {
+    const loaded = loadHeadlessRunState(options.continueId ?? undefined)
+    if (!loaded) {
+      const id = options.continueId ?? '(most recent)'
+      const message = `No resumable session found for ${id}. Run levelcode -p without --continue first, or pass a valid session_id.`
+      if (outputFormat === 'text') {
+        err(`error: ${message}
+`)
+        return { exitCode: 2, result: { type: 'result', subtype: 'error_during_execution' as const, is_error: true, message } }
+      }
+      emit({ type: 'system', subtype: 'init', ok: false })
+      emit({ type: 'result', subtype: 'error_during_execution' as const, is_error: true, message })
+      return { exitCode: 2, result: { type: 'result', subtype: 'error_during_execution' as const, is_error: true, message } }
+    }
+    previousRun = loaded
+  }
+
+  let finishedRun: unknown
   try {
-    await client.run({
+    finishedRun = await client.run({
       agent: agentOverride ?? 'base2',
       prompt,
+      ...(previousRun ? { previousRun: previousRun as never } : {}),
       handleEvent,
       maxAgentSteps: 100,
       fileFilter: ((filePath: string) => {
@@ -169,6 +193,14 @@ export async function runHeadless(options: HeadlessOptions): Promise<HeadlessRes
     sawError = true
   }
 
+  // Persist the session for --continue chaining (best-effort).
+  let sessionId: string | null = null
+  if (!sawError && finishedRun) {
+    try {
+      sessionId = saveHeadlessRunState(finishedRun as never)
+    } catch { /* persistence is best-effort */ }
+  }
+
   const result: Record<string, unknown> = {
     type: 'result',
     subtype: sawError
@@ -180,6 +212,7 @@ export async function runHeadless(options: HeadlessOptions): Promise<HeadlessRes
     num_tool_calls: numToolCalls,
     result: finalText,
     project: path.basename(projectRoot),
+    ...(sessionId ? { session_id: sessionId } : {}),
   }
 
   if (outputFormat === 'stream-json') {

cli/src/headless/session-store.ts

@@ -0,0 +1,59 @@
+/**
+ * Headless session persistence — a thin, explicit wrapper over the TUI's
+ * chat-state storage format ({projectDataDir}/chats/<id>/run-state.json).
+ *
+ * Headless runs save their RunState after completion so a later run can
+ * resume them via `levelcode -p --continue [id]`, and the saved format is
+ * the same one the TUI writes — sessions are interchangeable between the
+ * two surfaces.
+ */
+
+import crypto from 'crypto'
+import fs from 'fs'
+import path from 'path'
+
+import { getProjectDataDir } from '../project-files'
+import { loadMostRecentChatState } from '../utils/run-state-storage'
+
+import type { RunState } from '@levelcode/sdk'
+
+const RUN_STATE_FILENAME = 'run-state.json'
+const CHAT_MESSAGES_FILENAME = 'chat-messages.json'
+
+/**
+ * Save a finished headless RunState as a new chat directory.
+ * Returns the chat id (also emitted in the headless `result` event as
+ * session_id) so callers can chain runs with --continue <id>.
+ */
+export function saveHeadlessRunState(runState: RunState): string | null {
+  try {
+    const chatId = crypto.randomUUID()
+    const chatDir = path.join(getProjectDataDir(), 'chats', chatId)
+    fs.mkdirSync(chatDir, { recursive: true })
+    fs.writeFileSync(
+      path.join(chatDir, RUN_STATE_FILENAME),
+      JSON.stringify(runState, null, 2),
+      'utf-8',
+    )
+    // Headless has no transcript view model; an empty messages array keeps
+    // the storage format compatible with loadMostRecentChatState (which
+    // requires both files) and with TUI resume (context comes from runState).
+    fs.writeFileSync(
+      path.join(chatDir, CHAT_MESSAGES_FILENAME),
+      '[]',
+      'utf-8',
+    )
+    return chatId
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Load the RunState to resume: the given chat id, or the most recent chat
+ * in this project (TUI sessions included).
+ */
+export function loadHeadlessRunState(chatId?: string): RunState | null {
+  const loaded = loadMostRecentChatState(chatId)
+  return loaded?.runState ?? null
+}

cli/src/index.tsx

@@ -21,6 +21,7 @@ const options = program.opts<{
   agent?: string
   cwd?: string
   worktree?: string
+  continue?: boolean | string
 }>()
 
 // `doctor` runs from node builtins only — never load the heavy runtime.
@@ -65,6 +66,11 @@ if (argv1 === 'doctor') {
       outputFormat: format as 'text' | 'json' | 'stream-json',
       agentOverride: options.agent?.trim() || null,
       cwdOverride,
+      continueChat: Boolean(options.continue),
+      continueId:
+        typeof options.continue === 'string' && options.continue.trim().length > 0
+          ? options.continue.trim()
+          : null,
     })
     process.exit(exitCode)
   })