typeclaw 0.36.7 → 0.37.0

package/src/init/index.ts

@@ -10,13 +10,15 @@ import {
   GWS_MULTI_ACCOUNT_PLUGIN_VERSION,
   migrateLegacyConfigShape,
   type Config,
+  type CustomModelMeta,
 } from '@/config'
 import {
   DEFAULT_MODEL_REF,
   KNOWN_PROVIDERS,
+  isKnownModelRef,
   providerForModelRef,
-  type KnownModelRef,
   type KnownProviderId,
+  type ModelRef,
 } from '@/config/providers'
 import { checkDockerAvailable, type DockerAvailability, type DockerExec, start } from '@/container'
 import { commitSystemFile } from '@/git/system-commit'
@@ -171,7 +173,8 @@ export type InitOptions = {
   cwd: string
   // Selected `provider/model` ref written into typeclaw.json. Defaults to
   // DEFAULT_MODEL_REF when callers (or older test fixtures) omit it.
-  model?: KnownModelRef
+  model?: ModelRef | string
+  modelMeta?: CustomModelMeta
   // How the agent will authenticate to the LLM provider. When omitted,
   // defaults to the api-key path with `apiKey` (legacy field, still
   // supported for backwards compat with the old `runInit` signature).
@@ -181,7 +184,8 @@ export type InitOptions = {
   // when both refer to the same provider; the wizard enforces this
   // pairing rule, so by the time we get here `visionAuth` is either
   // (a) absent, or (b) the right auth for `visionModel`'s provider.
-  visionModel?: KnownModelRef
+  visionModel?: ModelRef | string
+  visionModelMeta?: CustomModelMeta
   visionAuth?: LLMAuth
   apiKey?: string
   discordBotToken?: string
@@ -224,7 +228,9 @@ export async function runInit({
   apiKey,
   llmAuth,
   model = DEFAULT_MODEL_REF,
+  modelMeta,
   visionModel,
+  visionModelMeta,
   visionAuth,
   discordBotToken,
   slackBotToken,
@@ -304,7 +310,9 @@ export async function runInit({
   emit({ step: 'scaffold', phase: 'start' })
   await scaffold(cwd, {
     model,
+    ...(modelMeta !== undefined ? { modelMeta } : {}),
     ...(visionModel !== undefined ? { visionModel } : {}),
+    ...(visionModelMeta !== undefined ? { visionModelMeta } : {}),
     withDiscord: wantsDiscord,
     withSlack: wantsSlack,
     withTelegram: wantsTelegram,
@@ -520,8 +528,10 @@ export async function isHatched(dir: string): Promise<boolean> {
 }
 
 export type ScaffoldOptions = {
-  model?: KnownModelRef
-  visionModel?: KnownModelRef
+  model?: ModelRef | string
+  modelMeta?: CustomModelMeta
+  visionModel?: ModelRef | string
+  visionModelMeta?: CustomModelMeta
   withDiscord?: boolean
   withSlack?: boolean
   withTelegram?: boolean
@@ -545,12 +555,14 @@ export async function scaffold(root: string, options: ScaffoldOptions = {}): Pro
   // `memory.*`) is omitted to keep the scaffold minimal — duplicating defaults
   // here would mean every schema change has to be mirrored in two places, and
   // users would feel obligated to maintain values they never set.
-  const models: Record<string, KnownModelRef> = { default: options.model ?? DEFAULT_MODEL_REF }
+  const models: Record<string, string> = { default: options.model ?? DEFAULT_MODEL_REF }
   if (options.visionModel !== undefined) models.vision = options.visionModel
   const config: Record<string, unknown> = {
     $schema: './node_modules/typeclaw/typeclaw.schema.json',
     models,
   }
+  const customModels = collectCustomModels(options)
+  if (Object.keys(customModels).length > 0) config.customModels = customModels
   const channels: Record<string, Record<string, never>> = {}
   if (options.withDiscord) channels['discord-bot'] = {}
   if (options.withSlack) channels['slack-bot'] = {}
@@ -578,12 +590,32 @@ export async function scaffold(root: string, options: ScaffoldOptions = {}): Pro
   await writeFile(join(root, GITIGNORE_FILE), buildGitignore(), { flag: 'wx' }).catch(ignoreExists)
 }
 
+function collectCustomModels(options: ScaffoldOptions): Record<string, CustomModelMeta> {
+  const customModels: Record<string, CustomModelMeta> = {}
+  addCustomModel(customModels, options.model ?? DEFAULT_MODEL_REF, options.modelMeta)
+  if (options.visionModel !== undefined) addCustomModel(customModels, options.visionModel, options.visionModelMeta)
+  return customModels
+}
+
+function addCustomModel(
+  customModels: Record<string, CustomModelMeta>,
+  ref: string,
+  meta: CustomModelMeta | undefined,
+): void {
+  if (isKnownModelRef(ref)) return
+  customModels[ref] = meta ?? {}
+}
+
 // agent-browser ships in every agent: the bundled SKILL.md (src/skills/
 // agent-browser/SKILL.md) is a discovery stub that calls `agent-browser
 // skills get core` at runtime, so the CLI must be installed for the skill
 // to function. The Dockerfile pre-downloads Chromium too, so the agent
 // can drive a browser without any first-run setup.
-const AGENT_BROWSER_VERSION = '^0.26.0'
+//
+// Must match the Dockerfile Layer 4 global install (dockerfile.ts); they are
+// two installs of the same CLI and a skew is silent. Enforced by a guard test
+// in packagejson.test.ts.
+export const AGENT_BROWSER_VERSION = '^0.27.0'
 function buildPackageJson(root: string, name: string): Record<string, unknown> {
   return {
     name,
@@ -738,10 +770,10 @@ export async function writeSecrets(
     slackAppToken,
     telegramBotToken,
   }: {
-    model?: KnownModelRef
+    model?: ModelRef | string
     // Omitted on the OAuth path — credentials live in secrets.json via the OAuth runner.
     apiKey?: string
-    visionModel?: KnownModelRef
+    visionModel?: ModelRef | string
     visionApiKey?: string
     discordBotToken?: string
     slackBotToken?: string

package/src/init/line-auth.ts

@@ -50,30 +50,49 @@ export function lineSecretsPath(agentDir: string): string {
   return join(agentDir, 'secrets.json')
 }
 
+// The SDK persists E2EE (Letter-Sealing) key material under
+// `<AGENT_MESSENGER_CONFIG_DIR>/line-storage/`. The container sets that env to
+// the agent workspace (src/init/dockerfile.ts), but a host-stage login (init /
+// `channel reauth line`) would otherwise fall back to `~/.config/agent-messenger`
+// — so the E2EE key gets written somewhere the container never reads, and inbound
+// Letter-Sealing messages stay undecryptable. Point the host login at the same
+// per-agent dir the container uses so the key lands where the runtime reads it.
+export function lineConfigDir(agentDir: string): string {
+  return join(agentDir, 'workspace', '.agent-messenger')
+}
+
 export async function runLineBootstrap(input: LineLoginInput): Promise<LineBootstrapStatus> {
   try {
     const store = new SecretsLineCredentialStore({ mode: 'host', secretsPath: lineSecretsPath(input.agentDir) })
-    // The LINE SDK persists the minted auth_token + certificate by calling
-    // setAccount() on whatever credential manager the client was built with.
-    // Wiring our secrets.json-backed store in here means a successful login
-    // writes straight to secrets.json#channels.line — no second copy in
-    // ~/.config/agent-messenger to keep in sync.
-    const client = input.client ?? buildLineClient(store)
-
-    const result = await suppressLineTokenInfoDump(() =>
-      input.method === 'qr'
-        ? client.loginWithQR({
-            onQRUrl: async (url) => {
-              await input.callbacks.onQRUrl?.(url)
-            },
-            onPincode: input.callbacks.onPincode,
-          })
-        : client.loginWithEmail({
-            email: input.email,
-            password: input.password,
-            onPincode: input.callbacks.onPincode,
-          }),
-    )
+
+    // The env is set only for the duration of client construction + login (when
+    // the SDK reads it to locate line-storage) and restored after, so a second
+    // bootstrap for a different agent in the same process can't inherit the
+    // first agent's path. An already-set value (the container's Dockerfile env)
+    // is left untouched.
+    const result = await withLineConfigDir(lineConfigDir(input.agentDir), () => {
+      // The LINE SDK persists the minted auth_token + certificate by calling
+      // setAccount() on whatever credential manager the client was built with.
+      // Wiring our secrets.json-backed store in here means a successful login
+      // writes straight to secrets.json#channels.line — no second copy in
+      // ~/.config/agent-messenger to keep in sync.
+      const client = input.client ?? buildLineClient(store)
+
+      return suppressLineTokenInfoDump(() =>
+        input.method === 'qr'
+          ? client.loginWithQR({
+              onQRUrl: async (url) => {
+                await input.callbacks.onQRUrl?.(url)
+              },
+              onPincode: input.callbacks.onPincode,
+            })
+          : client.loginWithEmail({
+              email: input.email,
+              password: input.password,
+              onPincode: input.callbacks.onPincode,
+            }),
+      )
+    })
 
     if (!result.authenticated || result.account_id === undefined) {
       const reason = result.message ?? result.error ?? 'LINE login did not authenticate'
@@ -105,6 +124,16 @@ function buildLineClient(store: SecretsLineCredentialStore): LineLoginClient {
   return new RealLineClient(credManager) as unknown as LineLoginClient
 }
 
+async function withLineConfigDir<T>(dir: string, fn: () => Promise<T>): Promise<T> {
+  const previous = process.env.AGENT_MESSENGER_CONFIG_DIR
+  if (previous === undefined) process.env.AGENT_MESSENGER_CONFIG_DIR = dir
+  try {
+    return await fn()
+  } finally {
+    if (previous === undefined) delete process.env.AGENT_MESSENGER_CONFIG_DIR
+  }
+}
+
 async function suppressLineTokenInfoDump<T>(fn: () => Promise<T>): Promise<T> {
   const previous = lineTokenInfoSuppressionQueue
   let release: () => void = () => {}

package/src/init/models-dev.ts

@@ -1,4 +1,13 @@
-import { KNOWN_PROVIDERS, type KnownModelRef, type KnownProviderId, listKnownModelRefs } from '@/config/providers'
+import type { CustomModelMeta } from '@/config'
+import {
+  KNOWN_PROVIDERS,
+  isKnownModelRef,
+  isModelRef,
+  listKnownModelRefs,
+  providerForModelRef,
+  type KnownProviderId,
+  type ModelRef,
+} from '@/config/providers'
 
 const MODELS_DEV_URL = 'https://models.dev/api.json'
 const REQUEST_TIMEOUT_MS = 10_000
@@ -23,16 +32,24 @@ const PROVIDER_TO_MODELS_DEV: Record<KnownProviderId, string> = {
   xai: 'xai',
   minimax: 'minimax',
   deepseek: 'deepseek',
+  moonshot: 'moonshot',
+  // moonshot-coding (Kimi Code subscription) is a billing surface, not a
+  // separate model catalog. models.dev tracks the underlying Kimi model
+  // metadata under `moonshot`, so we route lookups there; the curated
+  // `kimi-for-coding` alias is surfaced regardless of upstream membership.
+  'moonshot-coding': 'moonshot',
 }
 
 export type ModelOption = {
-  ref: KnownModelRef
+  ref: ModelRef | string
   providerId: KnownProviderId
   providerName: string
   modelId: string
   modelName: string
   reasoning: boolean
   contextWindow: number | null
+  maxTokens?: number | null
+  cost?: ModelOptionCost | null
   curated: boolean
   // True iff the model accepts image input. Sourced from the curated
   // `Model.input` array (which is the source of truth — pi-ai consumes it
@@ -43,6 +60,13 @@ export type ModelOption = {
   supportsVision: boolean
 }
 
+export type ModelOptionCost = {
+  input: number
+  output: number
+  cacheRead: number
+  cacheWrite: number
+}
+
 type ModelsDevModel = {
   id?: string
   name?: string
@@ -51,7 +75,15 @@ type ModelsDevModel = {
   status?: string
   release_date?: string
   modalities?: { input?: string[]; output?: string[] }
-  limit?: { context?: number }
+  limit?: { context?: number; output?: number }
+  cost?: {
+    input?: number
+    output?: number
+    cacheRead?: number
+    cacheWrite?: number
+    cache_read?: number
+    cache_write?: number
+  }
 }
 
 type ModelsDevProvider = {
@@ -99,22 +131,47 @@ export function curatedOptions(): ModelOption[] {
   return refs.map((ref) => buildOption(ref, { curated: true }))
 }
 
-// `data` is the parsed models.dev JSON. We walk only the providers we care
-// about (openai, fireworks-ai) and only emit options for models that are
-// also in our curated allowlist — anything outside the allowlist would fail
-// schema validation when written to typeclaw.json. Curated entries that
-// models.dev doesn't list (e.g. kimi-k2p6-turbo) are still surfaced so the
-// user can pick them.
+export function customModelMetaFromOption(option: ModelOption): CustomModelMeta | undefined {
+  if (isKnownModelRef(option.ref)) return undefined
+  if (!isModelRef(option.ref)) return undefined
+  return {
+    name: option.modelName,
+    reasoning: option.reasoning,
+    input: option.supportsVision ? ['text', 'image'] : ['text'],
+    ...(option.contextWindow !== null ? { contextWindow: option.contextWindow } : {}),
+    ...(option.maxTokens !== undefined && option.maxTokens !== null ? { maxTokens: option.maxTokens } : {}),
+    ...(option.cost !== undefined && option.cost !== null ? { cost: option.cost } : {}),
+  }
+}
+
+// `data` is the parsed models.dev JSON. We keep every curated entry first
+// (including provider-specific aliases models.dev does not list), then append
+// live upstream models whose refs validate against a known TypeClaw provider.
 function mergeWithCurated(data: Record<string, ModelsDevProvider>): ModelOption[] {
   const out: ModelOption[] = []
+  const seen = new Set<string>()
   for (const providerId of Object.keys(KNOWN_PROVIDERS) as KnownProviderId[]) {
     const known = KNOWN_PROVIDERS[providerId]
     const upstream = data[PROVIDER_TO_MODELS_DEV[providerId]]
     const upstreamModels = upstream?.models ?? {}
     for (const modelId of Object.keys(known.models)) {
       const upstreamModel = upstreamModels[modelId]
-      const ref = `${providerId}/${modelId}` as KnownModelRef
+      const ref = `${providerId}/${modelId}`
       out.push(buildOption(ref, { curated: true, upstream: upstreamModel }))
+      seen.add(ref)
+    }
+  }
+
+  for (const providerId of Object.keys(KNOWN_PROVIDERS) as KnownProviderId[]) {
+    const upstream = data[PROVIDER_TO_MODELS_DEV[providerId]]
+    const upstreamModels = upstream?.models ?? {}
+    for (const [fallbackModelId, upstreamModel] of Object.entries(upstreamModels)) {
+      const modelId = upstreamModel.id ?? fallbackModelId
+      if (modelId.trim().length === 0) continue
+      const ref = `${providerId}/${modelId}`
+      if (seen.has(ref) || !isModelRef(ref)) continue
+      out.push(buildOption(ref, { curated: isKnownModelRef(ref), upstream: upstreamModel }))
+      seen.add(ref)
     }
   }
   return out
@@ -125,17 +182,23 @@ type BuildOptionOpts = {
   upstream?: ModelsDevModel
 }
 
-function buildOption(ref: KnownModelRef, opts: BuildOptionOpts): ModelOption {
-  const slash = ref.indexOf('/')
-  const providerId = ref.slice(0, slash) as KnownProviderId
-  const modelId = ref.slice(slash + 1)
+function buildOption(ref: ModelRef | string, opts: BuildOptionOpts): ModelOption {
+  const providerId = providerForModelRef(ref)
+  const modelId = ref.slice(providerId.length + 1)
   const provider = KNOWN_PROVIDERS[providerId]
   const curatedModel = (
     provider.models as Record<
       string,
-      { name: string; contextWindow?: number; reasoning?: boolean; input?: ReadonlyArray<string> }
+      {
+        name: string
+        contextWindow?: number
+        maxTokens?: number
+        reasoning?: boolean
+        input?: ReadonlyArray<string>
+      }
     >
   )[modelId]
+  const input = resolveInput(curatedModel?.input, opts.upstream?.modalities?.input)
   return {
     ref,
     providerId,
@@ -144,16 +207,28 @@ function buildOption(ref: KnownModelRef, opts: BuildOptionOpts): ModelOption {
     modelName: opts.upstream?.name ?? curatedModel?.name ?? modelId,
     reasoning: opts.upstream?.reasoning ?? curatedModel?.reasoning ?? false,
     contextWindow: opts.upstream?.limit?.context ?? curatedModel?.contextWindow ?? null,
+    maxTokens: opts.upstream?.limit?.output ?? curatedModel?.maxTokens ?? null,
+    cost: resolveCost(opts.upstream?.cost),
     curated: opts.curated,
-    supportsVision: resolveSupportsVision(curatedModel?.input, opts.upstream?.modalities?.input),
+    supportsVision: input.includes('image'),
   }
 }
 
-function resolveSupportsVision(
+function resolveInput(
   curatedInput: ReadonlyArray<string> | undefined,
   upstreamInput: ReadonlyArray<string> | undefined,
-): boolean {
-  if (curatedInput !== undefined) return curatedInput.includes('image')
-  if (upstreamInput !== undefined) return upstreamInput.includes('image')
-  return false
+): string[] {
+  if (curatedInput !== undefined) return [...curatedInput]
+  if (upstreamInput !== undefined && upstreamInput.length > 0) return [...upstreamInput]
+  return ['text']
+}
+
+function resolveCost(cost: ModelsDevModel['cost']): ModelOptionCost | null {
+  if (cost === undefined) return null
+  return {
+    input: cost.input ?? 0,
+    output: cost.output ?? 0,
+    cacheRead: cost.cacheRead ?? cost.cache_read ?? 0,
+    cacheWrite: cost.cacheWrite ?? cost.cache_write ?? 0,
+  }
 }

package/src/init/oauth-login.ts

@@ -4,14 +4,14 @@ import {
   KNOWN_PROVIDERS,
   providerForModelRef,
   supportsOAuth,
-  type KnownModelRef,
   type KnownProviderId,
+  type ModelRef,
 } from '@/config/providers'
 import { createSecretsStoreForAgent } from '@/secrets'
 
 export type OAuthLoginResult = { ok: true } | { ok: false; reason: string }
 
-export type OAuthLoginRunner = (options: { cwd: string; model: KnownModelRef }) => Promise<OAuthLoginResult>
+export type OAuthLoginRunner = (options: { cwd: string; model: ModelRef | string }) => Promise<OAuthLoginResult>
 
 // Wrap pi-ai's OAuth callbacks so the CLI doesn't have to know about the
 // upstream callback shape. The CLI sees four lifecycle events:
@@ -76,7 +76,7 @@ export function makeOAuthLoginRunner(callbacks: OAuthCallbacks): OAuthLoginRunne
 // params" without spinning up a real secrets store / browser callback server.
 export type FakeOAuthLoginRunnerOptions = {
   result?: OAuthLoginResult
-  onCalled?: (options: { cwd: string; model: KnownModelRef; providerId: KnownProviderId }) => void
+  onCalled?: (options: { cwd: string; model: ModelRef | string; providerId: KnownProviderId }) => void
 }
 
 export function makeFakeOAuthLoginRunner(options: FakeOAuthLoginRunnerOptions = {}): OAuthLoginRunner {

package/src/init/progress.ts

@@ -0,0 +1,29 @@
+import type { WizardAnswerCheckpointV1, WizardCheckpointStore } from './checkpoint'
+import { isHatched } from './index'
+
+export type InitProgressStatus =
+  | { kind: 'none' }
+  | { kind: 'incomplete'; checkpoint: WizardAnswerCheckpointV1 }
+  | { kind: 'complete-stale-checkpoint'; checkpoint: WizardAnswerCheckpointV1 }
+
+export interface DetectInitProgressOptions {
+  cwd: string
+  checkpointStore: WizardCheckpointStore
+  isHatched?: (dir: string) => Promise<boolean>
+}
+
+// Single shared predicate for "is this init incomplete?", consumed by both the
+// init resume-prompt and the start/restart launchers so the two never drift.
+//
+// `isHatched` is the completion authority — NOT the presence of node_modules,
+// Dockerfile, or typeclaw.json, which are intermediate artifacts that start can
+// regenerate. A checkpoint that outlives a hatched agent (clear failed after a
+// successful run) is reported as `complete-stale-checkpoint` so callers can
+// opportunistically clean it up instead of falsely blocking a working agent.
+export async function detectInitProgress(options: DetectInitProgressOptions): Promise<InitProgressStatus> {
+  const hatchedCheck = options.isHatched ?? isHatched
+  const checkpoint = await options.checkpointStore.load(options.cwd)
+  if (checkpoint === undefined) return { kind: 'none' }
+  if (await hatchedCheck(options.cwd)) return { kind: 'complete-stale-checkpoint', checkpoint }
+  return { kind: 'incomplete', checkpoint }
+}

package/src/init/validate-api-key.ts

@@ -10,6 +10,8 @@ const PROVIDER_PROBE: Partial<Record<KnownProviderId, { url: string; authHeader:
   xai: { url: 'https://api.x.ai/v1/models', authHeader: 'bearer' },
   minimax: { url: 'https://api.minimax.io/v1/models', authHeader: 'bearer' },
   deepseek: { url: 'https://api.deepseek.com/models', authHeader: 'bearer' },
+  moonshot: { url: 'https://api.moonshot.ai/v1/models', authHeader: 'bearer' },
+  'moonshot-coding': { url: 'https://api.kimi.com/coding/v1/models', authHeader: 'bearer' },
 }
 
 // When a base-URL override (ANTHROPIC_BASE_URL / OPENAI_BASE_URL) points at a
@@ -165,6 +167,8 @@ export const API_KEY_DASHBOARD_URL: Partial<Record<KnownProviderId, string>> = {
   xai: 'https://console.x.ai',
   minimax: 'https://platform.minimax.io/user-center/basic-information/interface-key',
   deepseek: 'https://platform.deepseek.com/api_keys',
+  moonshot: 'https://platform.moonshot.ai/console/api-keys',
+  'moonshot-coding': 'https://www.kimi.com/code/console',
 }
 
 // MiniMax sells the same `minimax` provider under two billing surfaces that

package/src/inspect/index.ts

@@ -14,6 +14,8 @@ export { originLabel, shortSessionId } from './label'
 export { renderEvent } from './render'
 export { replayJsonl } from './replay'
 export { streamLive } from './live'
+export { fetchLiveSessions } from './live-list'
+export type { FetchLiveSessionsOptions } from './live-list'
 export { parseDuration, parseFilter } from './types'
 export type { InspectCategory, InspectEvent, InspectFilter } from './types'
 export { runInspectLoop, runViewerLoop } from './loop'
@@ -219,12 +221,17 @@ export async function streamSessionEvents(opts: StreamSessionEventsOptions): Pro
     opts.onEvent(event)
   }
 
-  for await (const event of replayJsonl(
-    opts.summary.sessionFile,
-    opts.onWarn !== undefined ? { onWarn: opts.onWarn } : {},
-  )) {
-    if (aborted()) return { escToPicker: true }
-    deliver(event)
+  // A live-only session (registry-derived, no .jsonl yet) has an empty
+  // sessionFile: skip replay and go straight to the live tail. Replaying ''
+  // would just emit a spurious "file does not exist" warning.
+  if (opts.summary.sessionFile !== '') {
+    for await (const event of replayJsonl(
+      opts.summary.sessionFile,
+      opts.onWarn !== undefined ? { onWarn: opts.onWarn } : {},
+    )) {
+      if (aborted()) return { escToPicker: true }
+      deliver(event)
+    }
   }
   opts.onPhase?.({ phase: 'replay-end' })
 

package/src/inspect/item-list.ts

@@ -1,5 +1,7 @@
+import type { LiveSessionPayload } from '@/shared'
+
 import type { ViewerItem } from './item'
-import { listSessions, type ListSessionsOptions, type SessionSummary } from './session-list'
+import { listSessions, type ListSessionsOptions, mergeLiveSessions, type SessionSummary } from './session-list'
 
 export type ListViewerItemsOptions = ListSessionsOptions & {
   containerRunning: boolean
@@ -9,6 +11,9 @@ export type ListViewerItemsOptions = ListSessionsOptions & {
   // (most-recent) tui transcript — and any older tui transcript the heuristic
   // would otherwise promote — must NOT be offered as a writable live row.
   allowWritable?: boolean
+  // Registry sessions not yet flushed to disk, fetched by the CLI over the
+  // /inspect WS. The lib layer stays I/O-free; the caller owns the connection.
+  liveSessions?: LiveSessionPayload[]
 }
 
 export type ViewerList = {
@@ -23,7 +28,11 @@ export type ViewerList = {
 // sessions are read-only. The `logs` row is appended last (container stdout,
 // available offline) so it sits below the divider in the picker.
 export async function listViewerItems(opts: ListViewerItemsOptions): Promise<ViewerList> {
-  const sessions = await listSessions(opts)
+  const diskSessions = await listSessions(opts)
+  const sessions =
+    opts.liveSessions !== undefined && opts.liveSessions.length > 0
+      ? mergeLiveSessions(diskSessions, opts.liveSessions)
+      : diskSessions
   const allowWritable = opts.allowWritable !== false
   const writableSessionId = opts.containerRunning && allowWritable ? pickWritableSession(sessions) : null
 

package/src/inspect/live-list.ts

@@ -0,0 +1,65 @@
+import type { InspectClientMessage, InspectServerMessage, LiveSessionPayload } from '@/shared'
+
+export type FetchLiveSessionsOptions = {
+  url: string
+  signal?: AbortSignal
+  WebSocketImpl?: typeof WebSocket
+  timeoutMs?: number
+}
+
+const DEFAULT_TIMEOUT_MS = 5_000
+
+// One-shot query of the container's in-memory session registry over the
+// /inspect WS: open, send list_live, read the single reply, close. Failure
+// (container down, timeout, abort) resolves to [] so the picker degrades to the
+// disk-only listing rather than erroring — the live overlay is best-effort.
+export async function fetchLiveSessions(opts: FetchLiveSessionsOptions): Promise<LiveSessionPayload[]> {
+  const WS = opts.WebSocketImpl ?? WebSocket
+  if (opts.signal?.aborted === true) return []
+
+  return new Promise<LiveSessionPayload[]>((resolve) => {
+    let settled = false
+    const ws = new WS(opts.url)
+
+    const finish = (result: LiveSessionPayload[]): void => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      try {
+        ws.close()
+      } catch {
+        /* ignore */
+      }
+      resolve(result)
+    }
+
+    const timer = setTimeout(() => finish([]), opts.timeoutMs ?? DEFAULT_TIMEOUT_MS)
+
+    if (opts.signal !== undefined) {
+      opts.signal.addEventListener('abort', () => finish([]), { once: true })
+    }
+
+    ws.addEventListener('open', () => {
+      const req: InspectClientMessage = { type: 'list_live' }
+      try {
+        ws.send(JSON.stringify(req))
+      } catch {
+        finish([])
+      }
+    })
+
+    ws.addEventListener('message', (e) => {
+      let msg: InspectServerMessage
+      try {
+        msg = JSON.parse(String((e as MessageEvent).data)) as InspectServerMessage
+      } catch {
+        return
+      }
+      if (msg.type === 'live_sessions') finish(msg.sessions)
+      else if (msg.type === 'error') finish([])
+    })
+
+    ws.addEventListener('error', () => finish([]))
+    ws.addEventListener('close', () => finish([]))
+  })
+}

package/src/inspect/open-item.ts

@@ -1,8 +1,11 @@
+import { join } from 'node:path'
+
 import type { LiveSourceFactory, RunInspectResult } from './index'
 import { createTranscriptView, streamInspectTarget } from './index'
 import type { ViewerItem } from './item'
 import { streamLogs } from './logs-item'
 import type { OpenItemContext, OpenItemResult, TailController } from './loop'
+import { resolveSession } from './session-list'
 import { runTuiViewer } from './tui-item'
 import type { InspectFilter } from './types'
 
@@ -28,7 +31,14 @@ export type OpenViewerDeps = {
 // would corrupt input). The line/JSON session path and logs run UNDER the tail
 // scope, which owns the raw-mode esc/q/ctrl-c handling.
 export function openViewerItem(deps: OpenViewerDeps) {
-  return async (item: ViewerItem, ctx: OpenItemContext): Promise<OpenItemResult> => {
+  return async (rawItem: ViewerItem, ctx: OpenItemContext): Promise<OpenItemResult> => {
+    // A live-only row captured `sessionFile: ''` when it was listed. By the time
+    // the user opens it the reply may have flushed to disk AND the registry
+    // entry may be gone — leaving the live tail broadcast-only and skipping the
+    // now-existing transcript. Re-resolve against the sessions dir so a
+    // flushed session opens as its real disk summary (replay + live tail).
+    const item = await reresolveLiveItem(rawItem, deps.cwd, deps.stderr)
+
     if (item.kind === 'tui') {
       const result = await runTuiViewer({
         resolveUrl: deps.resolveTuiUrl,
@@ -93,6 +103,17 @@ export function openViewerItem(deps: OpenViewerDeps) {
   }
 }
 
+export async function reresolveLiveItem(
+  item: ViewerItem,
+  cwd: string,
+  onWarn: (line: string) => void,
+): Promise<ViewerItem> {
+  if (item.kind === 'logs' || item.summary.live !== true) return item
+  const resolved = await resolveSession(join(cwd, 'sessions'), item.summary.sessionId, onWarn)
+  if (!resolved.ok) return item
+  return { kind: 'session', summary: resolved.summary, writable: false }
+}
+
 function toResult(escToPicker: boolean, scope: TailController): RunInspectResult {
   if (scope.intent() === 'exit') return { ok: true, exitCode: 0 }
   if (escToPicker) return { ok: true, exitCode: 0, escToPicker: true }