feat: import existing Claude Code sessions (+ fork-resume for live sessions)

[dzshzx]

What

Two related additions for Claude Code, mirroring the existing Codex importer/session machinery.

1. Import existing Claude Code sessions — feat(hub,web)

A Claude counterpart to the Codex desktop importer. Scans ~/.claude/projects/**/*.jsonl, maps user / assistant(text/thinking/tool_use) / tool_result records to imported messages, and persists through a shared engine.

• New flavor-agnostic engine hub/src/web/routes/transcriptImport.ts (target selection / dedupe / persist / event emit, keyed on metadata.<flavor>SessionId); Codex & Claude each keep only their scanner + parser + adapter.
• hub/src/web/routes/claudeDesktop.ts: /api/claude/status|sessions|sync-session (default namespace only), idempotent re-import.
• Web: an "Import Claude sessions" entry mirroring the Codex dialog.

2. Fork-resume sessions that are still live as a background agent — feat(cli)

When resuming a Claude session that is still held open by a running background/interactive agent, claude --resume <id> is rejected (currently running as a background agent), the error was swallowed to {}, and the launcher retried forever.

• Detect liveness via claude agents --json (getLiveAgentKind) and branch a copy with --fork-session (recording metadata.forkedFrom) instead of taking over the live session.
• Stop the launcher's infinite retry on unrecoverable resume errors (MAX_LAUNCH_RETRIES).
• Fix the logger swallowing Error to {} (now {name,message,stack}).
• Dead sessions fall through to plain --resume (unchanged); Codex and other flavors untouched.

Tests

New unit tests for liveness detection, error classification, fork-arg passthrough, launcher retry, and logger serialization. bun run test green across cli/hub/web/shared; bun run build clean.

[github-actions]

Findings

• [Major] Preserve transcript timestamps during direct import — importSingleSession writes every imported row through addMessage, so created_at/invoked_at are stamped with the import time rather than the Claude row timestamp. The hub then sorts sessions by updatedAt and message pages by invokedAt ?? createdAt, so importing an old Claude transcript makes it look active today and collapses historical message timing. Claude JSONL rows already expose timestamp (see existing RawJSONLinesBaseSchema), but the new Claude importer drops it before persistence. Evidence: hub/src/web/routes/transcriptImport.ts:805.
  Suggested fix:

  type ImportedTranscriptMessage = {
      content: ImportedMessageContent
      createdAt?: number
  }
  
  function parseClaudeTimestamp(record: Record<string, unknown>): number | undefined {
      if (typeof record.timestamp !== 'string') return undefined
      const value = Date.parse(record.timestamp)
      return Number.isFinite(value) ? value : undefined
  }
  
  const createdAt = message.createdAt ?? transcript.modifiedAt
  const appendedMessages = messagesToAppend.map((message) =>
      options.store.messages.copyMessageToSession(sessionId!, {
          content: message.content,
          createdAt,
          invokedAt: createdAt,
          localId: undefined,
          scheduledAt: null
      })
  )

Summary

• Review mode: initial
• Found one issue: imported Claude transcripts lose original timestamps, which changes session recency and message chronology in HAPI.

Testing

• Not run (automation). Add a Claude import test with two JSONL rows carrying old ISO timestamp values and assert persisted createdAt/session updatedAt match the transcript timeline, not Date.now().

HAPI Bot

[github-actions]

[MAJOR] addMessage always stamps created_at/invoked_at with Date.now(), so direct-imported Claude rows lose their JSONL timestamp. Because /api/sessions sorts by session updatedAt and message pagination sorts by invokedAt ?? createdAt, importing an old transcript makes it look active at import time and collapses the original message timeline. Claude records already have a timestamp field in the existing raw schema; carry that through the import data and insert with copyMessageToSession (or an equivalent timestamp-aware insert).

Suggested fix:

type ImportedTranscriptMessage = {
    content: ImportedMessageContent
    createdAt?: number
}

function parseClaudeTimestamp(record: Record<string, unknown>): number | undefined {
    if (typeof record.timestamp !== 'string') return undefined
    const value = Date.parse(record.timestamp)
    return Number.isFinite(value) ? value : undefined
}

const createdAt = message.createdAt ?? transcript.modifiedAt
const appendedMessages = messagesToAppend.map((message) =>
    options.store.messages.copyMessageToSession(sessionId!, {
        content: message.content,
        createdAt,
        invokedAt: createdAt,
        localId: undefined,
        scheduledAt: null
    })
)

[github-actions]

Findings

• [Major] Query the live-agent roster with the same Claude environment used for launch — the new fork decision runs getLiveAgentKind(startFrom) before opts.claudeEnvVars are applied, while the actual SDK launch below uses those env overrides. If a runner/session sets HAPI_CLAUDE_PATH or CLAUDE_CONFIG_DIR through claudeEnvVars, the roster probe can query the default Claude binary/home, miss the live agent, set forkSession=false, and then the real launch resumes against the overridden Claude config and hits the occupied-session failure path instead of forking. Evidence: cli/src/claude/claudeRemote.ts:84.
  Suggested fix:

  if (opts.claudeEnvVars) {
      Object.entries(opts.claudeEnvVars).forEach(([key, value]) => {
          process.env[key] = value;
      });
  }
  process.env.DISABLE_AUTOUPDATER = '1';
  
  let forkSession = false;
  if (startFrom) {
      const liveKind = getLiveAgentKind(startFrom);
      if (liveKind) {
          forkSession = true;
      }
  }

Questions

• None.

Summary

• Review mode: follow-up after new commits
• The previous timestamp finding appears addressed in the follow-up diff, including tests. Found one remaining issue in the live-session fork path when Claude env overrides are supplied.

Testing

• Not run (automation). Add a claudeRemote fork test where claudeEnvVars supplies CLAUDE_CONFIG_DIR or HAPI_CLAUDE_PATH, and assert getLiveAgentKind observes that override before query() is called.

HAPI Bot

[github-actions]

[MAJOR] This roster probe runs before opts.claudeEnvVars are copied into process.env, but the actual launch below uses those env overrides. If the session/runner provides HAPI_CLAUDE_PATH or CLAUDE_CONFIG_DIR, getLiveAgentKind() can query the default Claude binary/home, return null, and then the real launch resumes against the overridden Claude config without --fork-session, re-triggering the occupied-session failure path.

Suggested fix:

if (opts.claudeEnvVars) {
    Object.entries(opts.claudeEnvVars).forEach(([key, value]) => {
        process.env[key] = value;
    });
}
process.env.DISABLE_AUTOUPDATER = '1';

let forkSession = false;
if (startFrom) {
    const liveKind = getLiveAgentKind(startFrom);
    if (liveKind) {
        forkSession = true;
    }
}

[github-actions]

Findings

• [Minor] Wire the Claude import marker into the session list — markClaudeSessionsImported(sessionIds) now records a Claude import timestamp, and the new helper comment says the session list should switch to a “from Claude” time label, but the list still only imports/reads getCodexImportedAt and only has Codex-specific time strings (web/src/components/SessionList.tsx:576). After a successful Claude import the localStorage marker is written, but no subscriber/formatter reads it, so the imported session just shows the normal updated time. Evidence: web/src/router.tsx:529.
  Suggested fix:

  import { getClaudeImportedAt, subscribeClaudeImportedSessions } from '@/lib/claudeImportedSessions'
  
  function getSessionTimeLabel(session: SessionSummary, t: TFunction): string | null {
      const agentSessionId = session.metadata?.agentSessionId
      const importedAt = session.metadata?.flavor === 'codex'
          ? getCodexImportedAt(agentSessionId)
          : session.metadata?.flavor === 'claude'
            ? getClaudeImportedAt(agentSessionId)
            : null
  
      if (importedAt !== null) {
          return session.metadata?.flavor === 'claude'
              ? formatClaudeImportedRelativeTime(importedAt, t)
              : formatCodexImportedRelativeTime(importedAt, t)
      }
      return formatRelativeTime(session.updatedAt, t)
  }

Questions

• None.

Summary

• Review mode: follow-up after new commits
• The previous live-agent env ordering finding appears addressed in this head. One remaining UI wiring issue: Claude import writes a marker that is never rendered by the session list.

Testing

• Not run (automation). Add a SessionList/import-marker test covering a Claude summary with metadata.flavor === 'claude' and a stored Claude imported timestamp.

HAPI Bot

[github-actions]

[MINOR] This writes the new Claude import marker, but the session list never reads it. SessionList still only imports/uses getCodexImportedAt in getSessionTimeLabel, so a successful Claude import stores hapi.claudeImportedSessions and then renders the normal relative updatedAt label instead of the intended “imported from Claude” label.

Suggested fix:

import { getClaudeImportedAt, subscribeClaudeImportedSessions } from '@/lib/claudeImportedSessions'

function getSessionTimeLabel(session: SessionSummary, t: TFunction): string | null {
    const agentSessionId = session.metadata?.agentSessionId
    const importedAt = session.metadata?.flavor === 'codex'
        ? getCodexImportedAt(agentSessionId)
        : session.metadata?.flavor === 'claude'
          ? getClaudeImportedAt(agentSessionId)
          : null

    if (importedAt !== null) {
        return session.metadata?.flavor === 'claude'
            ? formatClaudeImportedRelativeTime(importedAt, t)
            : formatCodexImportedRelativeTime(importedAt, t)
    }
    return formatRelativeTime(session.updatedAt, t)
}

[heavygee]

Heads-up from the fork: we have a cursor flavor of the multi-agent session import picker in flight (feat/agent-session-import-picker, targets Fixes #732).

Plan is to rebase onto this PR and land cursor behind the Claude importer — same SessionImportPicker shell, thin CursorSessionSyncDialog, parallel /api/cursor/* hub routes (ACP verify-probe; not transcript JSONL).

Will avoid duplicating the picker logic you extracted here.

[heavygee]

Follow-up from the fork: cursor flavor for the multi-agent import picker is in a draft PR stacked on this branch:

• Compare (cursor-only delta): heavygee/hapi@dzshzx:feat/claude-session-import...heavygee:feat/agent-session-import-picker
• Draft PR (blocked on this merging first): will link once feat(hub,web): cursor flavor for multi-agent session import (#732) #945 exists

Plan: merge #942 first, then rebase cursor import onto main. Same SessionImportPicker shell; parallel /api/cursor/* hub routes (strict ACP verify-probe).

Separate track: MCP display_image stateful-transport fix is #944 (cli-only, no dependency on this PR).

[heavygee]

Draft cursor follow-up is #945 (blocked on this PR merging first).

[github-actions]

Findings

• [Minor] Wire the Claude import marker into the session list — markClaudeSessionsImported(sessionIds) now writes a browser-side import timestamp after Claude sync, but SessionList still only reads the Codex marker and Codex time strings, so imported Claude sessions render the normal updated time instead of the intended “imported from Claude” state. Evidence web/src/router.tsx:534 and existing reader web/src/components/SessionList.tsx:581.
  Suggested fix:

  import { getClaudeImportedAt, subscribeClaudeImportedSessions } from '@/lib/claudeImportedSessions'
  
  function formatClaudeImportedRelativeTime(value: number, t: TFunction): string | null {
      // mirror formatCodexImportedRelativeTime with Claude locale keys
  }
  
  function getSessionTimeLabel(session: SessionSummary, t: TFunction): string | null {
      const agentSessionId = session.metadata?.agentSessionId
      const importedAt = session.metadata?.flavor === 'codex'
          ? getCodexImportedAt(agentSessionId)
          : session.metadata?.flavor === 'claude'
            ? getClaudeImportedAt(agentSessionId)
            : null
  
      if (importedAt !== null) {
          return session.metadata?.flavor === 'claude'
              ? formatClaudeImportedRelativeTime(importedAt, t)
              : formatCodexImportedRelativeTime(importedAt, t)
      }
      return formatRelativeTime(session.updatedAt, t)
  }

Questions

• None.

Summary

• Review mode: follow-up after new commits
• One remaining UI wiring issue: the Claude import flow records an import timestamp that no rendered session-list code consumes. Residual risk: I did not run the full test suite in this review pass.

Testing

• Not run (automation).

HAPI Bot

[github-actions]

[MINOR] markClaudeSessionsImported(sessionIds) persists a Claude import timestamp, but the only session-list reader still checks Codex imports (web/src/components/SessionList.tsx:581), so this new marker is never displayed.

Suggested fix:

const importedAt = session.metadata?.flavor === 'codex'
    ? getCodexImportedAt(agentSessionId)
    : session.metadata?.flavor === 'claude'
      ? getClaudeImportedAt(agentSessionId)
      : null

[github-actions]

Findings

• [Minor] Wire Claude import markers into the session time label — the new Claude import flow records browser-side import timestamps after a successful sync, but the session list still only reads Codex import markers. As a result, imported Claude sessions keep showing the normal updated time instead of the intended imported-from-Claude state. Evidence web/src/router.tsx:534; unchanged reader context web/src/components/SessionList.tsx:581.
  Suggested fix:

  import { getClaudeImportedAt, subscribeClaudeImportedSessions } from '@/lib/claudeImportedSessions'
  
  function formatClaudeImportedRelativeTime(value: number, t: TFunction): string | null {
      // mirror formatCodexImportedRelativeTime with Claude locale keys
  }
  
  const agentSessionId = session.metadata?.agentSessionId
  const importedAt = session.metadata?.flavor === 'codex'
      ? getCodexImportedAt(agentSessionId)
      : session.metadata?.flavor === 'claude'
        ? getClaudeImportedAt(agentSessionId)
        : null

Questions

• None.

Summary

• Review mode: follow-up after new commits
• The previous Claude import timestamp wiring issue is still present at the latest head. Residual risk: I reviewed source context and did not run the full test suite in this automation pass.

Testing

• Not run (automation).

HAPI Bot

[github-actions]

[MINOR] markClaudeSessionsImported(sessionIds) records the Claude import timestamp, but SessionList still only reads the Codex marker (web/src/components/SessionList.tsx:581). Imported Claude sessions therefore never render the new imported-from-Claude time label.

Suggested fix:

const agentSessionId = session.metadata?.agentSessionId
const importedAt = session.metadata?.flavor === 'codex'
    ? getCodexImportedAt(agentSessionId)
    : session.metadata?.flavor === 'claude'
      ? getClaudeImportedAt(agentSessionId)
      : null