typeclaw 0.10.0 → 0.11.1

package/src/cli/init.ts

@@ -1,12 +1,10 @@
 import { randomBytes } from 'node:crypto'
-import { readFile } from 'node:fs/promises'
 
 import { cancel, confirm, intro, isCancel, log, note, password, select, spinner, text } from '@clack/prompts'
 import { defineCommand } from 'citty'
 
 import {
   KNOWN_PROVIDERS,
-  providerForModelRef,
   supportsApiKey as providerSupportsApiKey,
   supportsOAuth as providerSupportsOAuth,
   type KnownModelRef,
@@ -14,9 +12,12 @@ import {
 } from '@/config/providers'
 import { checkDockerAvailable, type DockerAvailability } from '@/container'
 import {
+  appendOrReplaceEnvKey,
   findAgentDir,
   formatEagerGithubWebhookInstallResult,
+  hasEnvKey,
   hasExistingChannelSecrets,
+  hasExistingOAuthCredentials,
   isDirectoryNonEmpty,
   isHatched,
   readExistingProviderApiKey,
@@ -34,7 +35,8 @@ import { makeOAuthLoginRunner, type OAuthLoginResult } from '@/init/oauth-login'
 import { API_KEY_DASHBOARD_URL, validateApiKey, type KeyValidationResult } from '@/init/validate-api-key'
 
 import { buildOAuthCallbacks } from './oauth-callbacks'
-import { c, done, errorLine, printSlackAppManifestSetup } from './ui'
+import { CANCEL_SYMBOL, promptPrivateKeyPem } from './prompt-pem'
+import { c, done, errorLine, printDiscordInviteHint, printSlackAppManifestSetup } from './ui'
 
 // ESC and Ctrl+C both produce clack's cancel symbol (the keypress layer
 // aliases both to the same "cancel" action — there's no way to tell them
@@ -79,8 +81,17 @@ export const init = defineCommand({
     name: 'init',
     description: 'initialize a new typeclaw agent in the current directory',
   },
-  async run() {
+  args: {
+    reset: {
+      type: 'boolean',
+      description:
+        'ignore any partial secrets.json state from an earlier aborted run and re-prompt for every credential',
+      default: false,
+    },
+  },
+  async run({ args }) {
     const cwd = process.cwd()
+    const reset = args.reset === true
 
     const existingAgent = findAgentDir(cwd)
     if (existingAgent !== null && existingAgent !== cwd) {
@@ -129,7 +140,7 @@ export const init = defineCommand({
 
     let collected: CollectedInputs
     try {
-      collected = await collectWizardInputs(cwd, defaultWizardPrompts)
+      collected = await collectWizardInputs(cwd, defaultWizardPrompts, { reset })
     } catch (error) {
       if (error instanceof WizardAbortedError) {
         if (error.oauthCredentialsSaved) {
@@ -330,17 +341,13 @@ type StepId =
 export interface WizardPrompts {
   loadCatalog: () => Promise<NonNullable<WizardState['catalog']>>
   readExistingApiKey: (cwd: string, providerId: KnownProviderId) => Promise<string | null>
+  hasExistingOAuthCredentials: (cwd: string, providerId: KnownProviderId) => Promise<boolean>
   pickProvider: (options: ModelOption[], initial: KnownProviderId | undefined) => Promise<StepResult<KnownProviderId>>
   pickModel: (
     options: ModelOption[],
     providerId: KnownProviderId,
     initial: KnownModelRef | undefined,
   ) => Promise<StepResult<ModelOption>>
-  askReuseExistingKey: (
-    provider: (typeof KNOWN_PROVIDERS)[KnownProviderId],
-    existingApiKey: string | null,
-    initial: boolean | undefined,
-  ) => Promise<StepResult<'reuse' | 'prompt'>>
   pickAuthMethod: (
     provider: (typeof KNOWN_PROVIDERS)[KnownProviderId],
     initial: 'api-key' | 'oauth' | undefined,
@@ -358,17 +365,12 @@ export interface WizardPrompts {
   ) => Promise<StepResult<ModelOption>>
   pickChannel: (initial: ChannelChoice | undefined) => Promise<StepResult<ChannelChoice>>
   hasExistingChannelSecrets: (cwd: string, channel: Exclude<ChannelChoice, 'none'>) => Promise<boolean>
-  askReuseExistingChannel: (channel: Exclude<ChannelChoice, 'none'>) => Promise<StepResult<'reuse' | 'prompt'>>
-  runChannelFlow: (choice: ChannelChoice) => Promise<StepResult<CollectedInputs['channelSecrets']>>
+  runChannelFlow: (choice: ChannelChoice, cwd: string) => Promise<StepResult<CollectedInputs['channelSecrets']>>
   runOAuthLogin: (
     provider: (typeof KNOWN_PROVIDERS)[KnownProviderId],
     cwd: string,
     model: KnownModelRef,
   ) => Promise<OAuthLoginResult>
-  // Asked after a failed OAuth login. `apiKeyAvailable` is true when the
-  // provider also supports api-key auth (so the wizard can offer a fallback
-  // path); false for OAuth-only providers like openai-codex, where the only
-  // options are retry or abort.
   askOAuthFailureRecovery: (
     provider: (typeof KNOWN_PROVIDERS)[KnownProviderId],
     reason: string,
@@ -376,14 +378,18 @@ export interface WizardPrompts {
   ) => Promise<OAuthFailureRecovery>
 }
 
+export type CollectWizardInputsOptions = {
+  reset?: boolean
+}
+
 export type OAuthFailureRecovery = 'retry' | 'api-key' | 'abort'
 
 export const defaultWizardPrompts: WizardPrompts = {
   loadCatalog,
   readExistingApiKey: readExistingProviderApiKey,
+  hasExistingOAuthCredentials,
   pickProvider,
   pickModel: pickModelForProvider,
-  askReuseExistingKey,
   pickAuthMethod,
   askApiKey,
   validateApiKey,
@@ -391,7 +397,6 @@ export const defaultWizardPrompts: WizardPrompts = {
   pickVisionModel,
   pickChannel,
   hasExistingChannelSecrets,
-  askReuseExistingChannel,
   runChannelFlow,
   runOAuthLogin: async (provider, cwd, model) => {
     const { callbacks, dispose } = buildOAuthCallbacks(provider.name)
@@ -404,7 +409,12 @@ export const defaultWizardPrompts: WizardPrompts = {
   askOAuthFailureRecovery,
 }
 
-export async function collectWizardInputs(cwd: string, prompts: WizardPrompts): Promise<CollectedInputs> {
+export async function collectWizardInputs(
+  cwd: string,
+  prompts: WizardPrompts,
+  options: CollectWizardInputsOptions = {},
+): Promise<CollectedInputs> {
+  const reset = options.reset === true
   const catalog = await prompts.loadCatalog()
   const state: WizardState = { catalog }
   let step: StepId = 'pick-provider'
@@ -425,6 +435,21 @@ export async function collectWizardInputs(cwd: string, prompts: WizardPrompts):
     return result
   }
 
+  const readExistingApiKey = async (providerId: KnownProviderId): Promise<string | null> => {
+    if (reset) return null
+    return await prompts.readExistingApiKey(cwd, providerId)
+  }
+
+  const hasExistingOAuth = async (providerId: KnownProviderId): Promise<boolean> => {
+    if (reset) return false
+    return await prompts.hasExistingOAuthCredentials(cwd, providerId)
+  }
+
+  const hasExistingChannel = async (channel: Exclude<ChannelChoice, 'none'>): Promise<boolean> => {
+    if (reset) return false
+    return await prompts.hasExistingChannelSecrets(cwd, channel)
+  }
+
   while (true) {
     switch (step) {
       case 'pick-provider': {
@@ -456,17 +481,15 @@ export async function collectWizardInputs(cwd: string, prompts: WizardPrompts):
 
       case 'reuse-existing-key': {
         const provider = KNOWN_PROVIDERS[state.providerId!]
-        const existingApiKey = await prompts.readExistingApiKey(cwd, state.providerId!)
-        const decision = onResult(
-          step,
-          await prompts.askReuseExistingKey(provider, existingApiKey, state.reuseExisting),
-        )
-        if (decision.kind === 'back') {
-          step = 'pick-model'
-          break
-        }
-        if (decision.value === 'reuse' && existingApiKey !== null) {
-          log.info(`Using existing ${provider.name} API key from secrets.json.`)
+        // Auto-resume: if `secrets.json` already has a usable api-key for
+        // this provider, reuse it silently. Issue #330: re-running init
+        // after a partial abort should pick up where the user left off
+        // without re-prompting for credentials they already supplied.
+        // `--reset` bypasses this by making `readExistingApiKey` return
+        // null, falling through to the normal auth-method flow.
+        const existingApiKey = await readExistingApiKey(state.providerId!)
+        if (existingApiKey !== null) {
+          log.info(`Reusing existing ${provider.name} API key from secrets.json.`)
           state.llmAuth = { kind: 'api-key', apiKey: existingApiKey }
           state.reuseExisting = true
           step = stepAfterDefaultAuth(state)
@@ -482,11 +505,29 @@ export async function collectWizardInputs(cwd: string, prompts: WizardPrompts):
         const provider = KNOWN_PROVIDERS[state.providerId!]
         const result = onResult(step, await prompts.pickAuthMethod(provider, state.authMethod))
         if (result.kind === 'back') {
-          step = 'reuse-existing-key'
+          // Skip past `reuse-existing-key` — it is a silent auto-resume
+          // step with no user prompt, so unwind directly to pick-model
+          // (the prior user-visible step). This only fires when
+          // pickAuthMethod was an interactive choice (dual-auth providers);
+          // single-method providers return autoValue and never reach the
+          // back branch.
+          step = 'pick-model'
           break
         }
         state.authMethod = result.value
         if (result.value === 'oauth') {
+          // Auto-resume: skip the browser flow when OAuth credentials are
+          // already on disk from a prior partial run. The fresh-tokens path
+          // and the resume path both leave `state.llmAuth = oauth-completed`,
+          // so downstream steps (vision, channel, scaffold) can't tell the
+          // difference. `--reset` short-circuits this by making
+          // `hasExistingOAuth` return false.
+          if (await hasExistingOAuth(state.providerId!)) {
+            log.info(`Reusing existing ${provider.name} OAuth credentials from secrets.json.`)
+            state.llmAuth = { kind: 'oauth-completed' }
+            step = stepAfterDefaultAuth(state)
+            break
+          }
           // Run the browser login eagerly so the user sees the OAuth URL the
           // moment they pick "OAuth (browser login)" — not at the end of the
           // wizard. On failure we ask the user how to recover (retry / fall
@@ -583,9 +624,9 @@ export async function collectWizardInputs(cwd: string, prompts: WizardPrompts):
           step = 'pick-channel'
           break
         }
-        const existingVisionKey = await prompts.readExistingApiKey(cwd, state.visionProviderId!)
+        const existingVisionKey = await readExistingApiKey(state.visionProviderId!)
         if (existingVisionKey !== null) {
-          log.info(`Using existing ${KNOWN_PROVIDERS[state.visionProviderId!].name} API key from secrets.json.`)
+          log.info(`Reusing existing ${KNOWN_PROVIDERS[state.visionProviderId!].name} API key from secrets.json.`)
           state.visionLlmAuth = { kind: 'api-key', apiKey: existingVisionKey }
           state.visionReuseExisting = true
           step = 'pick-channel'
@@ -606,6 +647,16 @@ export async function collectWizardInputs(cwd: string, prompts: WizardPrompts):
         }
         state.visionAuthMethod = result.value
         if (result.value === 'oauth') {
+          // Auto-resume mirror of the default-provider branch above: skip
+          // the browser flow when vision OAuth credentials are already on
+          // disk. The same `--reset` short-circuit applies via
+          // `hasExistingOAuth`.
+          if (await hasExistingOAuth(state.visionProviderId!)) {
+            log.info(`Reusing existing ${provider.name} OAuth credentials from secrets.json.`)
+            state.visionLlmAuth = { kind: 'oauth-completed' }
+            step = 'pick-channel'
+            break
+          }
           // Same eager-login + recovery-prompt rationale as the default-provider branch above.
           const login = await runOAuthLoginSafely(prompts, provider, cwd, state.visionModel!.ref)
           if (!login.ok) {
@@ -667,31 +718,26 @@ export async function collectWizardInputs(cwd: string, prompts: WizardPrompts):
 
       case 'reuse-existing-channel': {
         const choice = state.channelChoice as Exclude<ChannelChoice, 'none'>
-        const present = await prompts.hasExistingChannelSecrets(cwd, choice)
+        // Auto-resume: when usable channel credentials already exist on
+        // disk, reuse them silently — mirrors the api-key and OAuth
+        // resume paths above. `--reset` short-circuits via
+        // `hasExistingChannel` returning false, falling through to the
+        // normal channel-flow prompts.
+        const present = await hasExistingChannel(choice)
         if (!present) {
           state.channelReuseOffered = false
           state.channelReuseExisting = false
           step = 'channel-flow'
           break
         }
+        log.info(`Reusing existing ${channelDisplayName(choice)} credentials from secrets.json.`)
         state.channelReuseOffered = true
-        const decision = onResult(step, await prompts.askReuseExistingChannel(choice))
-        if (decision.kind === 'back') {
-          step = 'pick-channel'
-          break
-        }
-        if (decision.value === 'reuse') {
-          log.info(`Using existing ${channelDisplayName(choice)} credentials from secrets.json.`)
-          state.channelReuseExisting = true
-          return finalize(state, {})
-        }
-        state.channelReuseExisting = false
-        step = 'channel-flow'
-        break
+        state.channelReuseExisting = true
+        return finalize(state, {})
       }
 
       case 'channel-flow': {
-        const result = onResult(step, await prompts.runChannelFlow(state.channelChoice!))
+        const result = onResult(step, await prompts.runChannelFlow(state.channelChoice!, cwd))
         if (result.kind === 'back') {
           step = state.channelReuseOffered === true ? 'reuse-existing-channel' : 'pick-channel'
           break
@@ -818,31 +864,6 @@ async function pickModelForProvider(
   return value(picked)
 }
 
-async function askReuseExistingKey(
-  provider: (typeof KNOWN_PROVIDERS)[KnownProviderId],
-  existingApiKey: string | null,
-  initial: boolean | undefined,
-): Promise<StepResult<'reuse' | 'prompt'>> {
-  if (!providerSupportsApiKey(provider) || existingApiKey === null) return value('prompt')
-  const reuse = await confirm({
-    message: `Reuse existing ${provider.name} API key from secrets.json?`,
-    initialValue: initial ?? true,
-  })
-  if (isCancel(reuse)) return back()
-  return value(reuse === true ? 'reuse' : 'prompt')
-}
-
-async function askReuseExistingChannel(
-  channel: Exclude<ChannelChoice, 'none'>,
-): Promise<StepResult<'reuse' | 'prompt'>> {
-  const reuse = await confirm({
-    message: `Reuse existing ${channelDisplayName(channel)} credentials from secrets.json?`,
-    initialValue: true,
-  })
-  if (isCancel(reuse)) return back()
-  return value(reuse === true ? 'reuse' : 'prompt')
-}
-
 async function pickAuthMethod(
   provider: (typeof KNOWN_PROVIDERS)[KnownProviderId],
   initial: 'api-key' | 'oauth' | undefined,
@@ -1011,7 +1032,10 @@ async function pickChannel(initial: ChannelChoice | undefined): Promise<StepResu
   return value(choice)
 }
 
-async function runChannelFlow(choice: ChannelChoice): Promise<StepResult<CollectedInputs['channelSecrets']>> {
+async function runChannelFlow(
+  choice: ChannelChoice,
+  cwd: string,
+): Promise<StepResult<CollectedInputs['channelSecrets']>> {
   switch (choice) {
     case 'none':
       return value({})
@@ -1024,7 +1048,7 @@ async function runChannelFlow(choice: ChannelChoice): Promise<StepResult<Collect
     case 'telegram':
       return runTelegramFlow()
     case 'github':
-      return runGithubFlow()
+      return runGithubFlow(cwd)
   }
 }
 
@@ -1042,6 +1066,7 @@ async function runDiscordFlow(): Promise<StepResult<CollectedInputs['channelSecr
     validate: (v) => (v && v.length > 0 ? undefined : 'Token is required'),
   })
   if (isCancel(token)) return back()
+  printDiscordInviteHint(token)
   return value({ discordBotToken: token })
 }
 
@@ -1144,7 +1169,7 @@ async function runSlackFlow(): Promise<StepResult<CollectedInputs['channelSecret
   }
 }
 
-async function runGithubFlow(): Promise<StepResult<CollectedInputs['channelSecrets']>> {
+async function runGithubFlow(cwd: string): Promise<StepResult<CollectedInputs['channelSecrets']>> {
   note(
     [
       'Choose PAT auth for a quick setup, or GitHub App auth for expiring installation tokens.',
@@ -1171,6 +1196,10 @@ async function runGithubFlow(): Promise<StepResult<CollectedInputs['channelSecre
         value: 'cloudflare-quick',
         label: 'Cloudflare Quick Tunnel — no signup, URL rotates on restart (recommended)',
       },
+      {
+        value: 'cloudflare-named',
+        label: 'Cloudflare Named Tunnel — stable URL, needs Cloudflare account + domain',
+      },
       { value: 'external', label: 'External URL — I have my own reverse proxy / tunnel' },
       { value: 'none', label: 'None — configure later by hand-editing typeclaw.json' },
     ],
@@ -1185,6 +1214,8 @@ async function runGithubFlow(): Promise<StepResult<CollectedInputs['channelSecre
         })
       : undefined
   if (isCancel(webhookUrl)) return back()
+  const namedCreds = tunnelProvider === 'cloudflare-named' ? await promptGithubCloudflareNamedTunnel(cwd) : undefined
+  if (namedCreds === null) return back()
   const port = await text({
     message: 'Local webhook port inside the agent container',
     initialValue: '8975',
@@ -1214,12 +1245,41 @@ async function runGithubFlow(): Promise<StepResult<CollectedInputs['channelSecre
       tunnelProvider,
       ...(webhookUrl !== undefined ? { webhookUrl } : {}),
       webhookPort: Number(port),
+      ...(namedCreds !== undefined ? namedCreds : {}),
       repos: parseGithubRepos(reposRaw),
       auth,
     },
   })
 }
 
+async function promptGithubCloudflareNamedTunnel(cwd: string): Promise<{ hostname: string; tokenEnv: string } | null> {
+  const tokenEnv = 'CLOUDFLARE_TUNNEL_TOKEN'
+  note(
+    [
+      'Cloudflare Named Tunnel needs a tunnel you created in the Zero Trust dashboard:',
+      '  1. Networks → Tunnels → Create a tunnel → Cloudflared. Copy the token shown on the install screen.',
+      '  2. Public Hostname tab → Add: subdomain + your-domain, service type HTTP, URL localhost:<webhook port>.',
+      `  3. Paste the token below when prompted — TypeClaw will write it to .env as ${tokenEnv}.`,
+      'A tunnel without a Public Hostname registers but routes nothing.',
+    ].join('\n'),
+    'Cloudflare named tunnel',
+  )
+  const hostname = await text({
+    message: 'Public hostname configured in the dashboard (https://...)',
+    validate: (v) => validateGithubUrl(v ?? '', 'Hostname is required'),
+  })
+  if (isCancel(hostname)) return null
+  if (!hasEnvKey(cwd, tokenEnv)) {
+    const token = await password({
+      message: `Cloudflare tunnel token (will be written to .env as ${tokenEnv})`,
+      validate: (v) => (v && v.length > 0 ? undefined : 'Token is required'),
+    })
+    if (isCancel(token)) return null
+    appendOrReplaceEnvKey(cwd, tokenEnv, token)
+  }
+  return { hostname, tokenEnv }
+}
+
 async function promptGithubPatAuth(): Promise<{ type: 'pat'; pat: string } | null> {
   const pat = await password({
     message: 'GitHub fine-grained PAT',
@@ -1240,11 +1300,8 @@ async function promptGithubAppAuth(): Promise<{
     validate: (v) => validatePositiveInteger(v ?? '', 'App ID is required'),
   })
   if (isCancel(appId)) return null
-  const privateKeyInput = await text({
-    message: 'GitHub App private key PEM, escaped PEM, or path to .pem file',
-    validate: (v) => (v && v.length > 0 ? undefined : 'Private key is required'),
-  })
-  if (isCancel(privateKeyInput)) return null
+  const privateKey = await promptPrivateKeyPem('GitHub App private key PEM, escaped PEM, or path to .pem file')
+  if (privateKey === CANCEL_SYMBOL) return null
   const installationId = await text({
     message: 'Installation ID (optional; leave blank to auto-discover)',
     validate: (v) =>
@@ -1255,17 +1312,11 @@ async function promptGithubAppAuth(): Promise<{
   return {
     type: 'app',
     appId: Number(appId),
-    privateKey: await resolveGithubPrivateKey(privateKeyInput),
+    privateKey,
     ...(parsedInstallationId !== undefined ? { installationId: parsedInstallationId } : {}),
   }
 }
 
-async function resolveGithubPrivateKey(input: string): Promise<string> {
-  const normalized = input.replace(/\\n/g, '\n')
-  if (normalized.includes('-----BEGIN') && normalized.includes('PRIVATE KEY-----')) return normalized
-  return await readFile(input, 'utf8')
-}
-
 function parseGithubRepos(input: string): string[] {
   return input
     .split(',')
@@ -1432,18 +1483,6 @@ function reportHatching(event: Extract<InitStepEvent, { step: 'hatching' }>): vo
   }
 }
 
-export async function decideExistingApiKeyReuse(
-  provider: (typeof KNOWN_PROVIDERS)[KnownProviderId],
-  existingApiKey: string | null,
-  askReuse: (message: string) => Promise<unknown>,
-): Promise<'reuse' | 'prompt' | 'cancel'> {
-  if (!providerSupportsApiKey(provider) || existingApiKey === null) return 'prompt'
-
-  const reuse = await askReuse(`Reuse existing ${provider.name} API key from secrets.json?`)
-  if (isCancel(reuse)) return 'cancel'
-  return reuse === true ? 'reuse' : 'prompt'
-}
-
 function uniqueProviders(options: ModelOption[]): KnownProviderId[] {
   const seen = new Set<KnownProviderId>()
   const out: KnownProviderId[] = []

package/src/cli/inspect-controller.ts

@@ -0,0 +1,66 @@
+// Pure controller for the inspect CLI's esc/ctrl-c key dispatch.
+// Owns the AbortController lifecycle and the bare-ESC debounce timer,
+// independent of process.stdin / TTY raw mode (which is wired in src/cli/inspect.ts).
+// Extracted for testability: the lifecycle bug we want to pin is "armForStream's
+// signal must remain valid across pause()/resume() cycles" — verifying that without
+// a real TTY requires this seam.
+
+export type EscChunkResult = { sigint: boolean }
+
+export type EscController = {
+  armForStream: () => AbortSignal
+  onChunk: (chunk: Buffer) => EscChunkResult
+  clearPending: () => void
+  dispose: () => void
+}
+
+export function createEscController({ debounceMs }: { debounceMs: number }): EscController {
+  let currentCtrl: AbortController | null = null
+  let pendingEsc: ReturnType<typeof setTimeout> | null = null
+
+  const clearPending = (): void => {
+    if (pendingEsc !== null) {
+      clearTimeout(pendingEsc)
+      pendingEsc = null
+    }
+  }
+
+  return {
+    armForStream: () => {
+      clearPending()
+      currentCtrl = new AbortController()
+      return currentCtrl.signal
+    },
+    onChunk: (chunk) => {
+      if (chunk.length === 0) return { sigint: false }
+      if (chunk[0] === 0x03) {
+        // Ctrl-C in raw mode arrives as a byte (terminal driver does not generate
+        // SIGINT). Surface to the caller so it can re-issue SIGINT via the OS;
+        // we deliberately keep the AbortController lifecycle separate from SIGINT.
+        return { sigint: true }
+      }
+      if (chunk.length === 1 && chunk[0] === 0x1b) {
+        // Bare ESC: schedule the abort. A follow-up byte within debounceMs (CSI
+        // sequences from arrow keys, mouse, paste) cancels the pending fire.
+        // Snapshot currentCtrl so a late-firing timer can't abort a controller
+        // created by a subsequent armForStream() call.
+        clearPending()
+        const ctrl = currentCtrl
+        pendingEsc = setTimeout(() => {
+          pendingEsc = null
+          ctrl?.abort()
+        }, debounceMs)
+        return { sigint: false }
+      }
+      // Any other byte arriving within the ESC window is the second byte of a CSI
+      // sequence; cancel the pending abort.
+      clearPending()
+      return { sigint: false }
+    },
+    clearPending,
+    dispose: () => {
+      clearPending()
+      currentCtrl = null
+    },
+  }
+}

package/src/cli/inspect.ts

@@ -5,6 +5,7 @@ import { findAgentDir } from '@/init'
 import { runInspectLoop, streamLive, type LiveSourceFactory, type SessionSummary } from '@/inspect'
 import { originLabel, shortSessionId } from '@/inspect/label'
 
+import { createEscController } from './inspect-controller'
 import { cancel, c, errorLine, isCancel } from './ui'
 
 const ESC_LISTEN_DELAY_MS = 50
@@ -55,9 +56,9 @@ export const inspectCommand = defineCommand({
       ...(sinceArg !== undefined ? { since: sinceArg } : {}),
       json: isJson,
       color,
-      selectSession: (sessions) => {
+      selectSession: (sessions, selectOpts) => {
         escListener?.pause()
-        return clackSelect(sessions).finally(() => {
+        return clackSelect(sessions, selectOpts?.initialSessionId).finally(() => {
           escListener?.resume()
         })
       },
@@ -124,29 +125,12 @@ function createEscListener(): EscListener | null {
   const stdin = process.stdin
   if (!stdin.isTTY || typeof stdin.setRawMode !== 'function') return null
 
-  let currentCtrl: AbortController | null = null
-  let pendingEsc: ReturnType<typeof setTimeout> | null = null
+  const ctrl = createEscController({ debounceMs: ESC_LISTEN_DELAY_MS })
   let active = false
 
   const onData = (chunk: Buffer): void => {
-    if (chunk.length === 0) return
-    const first = chunk[0]
-    if (first === 0x03) {
-      process.kill(process.pid, 'SIGINT')
-      return
-    }
-    if (chunk.length === 1 && first === 0x1b) {
-      if (pendingEsc !== null) clearTimeout(pendingEsc)
-      pendingEsc = setTimeout(() => {
-        pendingEsc = null
-        currentCtrl?.abort()
-      }, ESC_LISTEN_DELAY_MS)
-      return
-    }
-    if (pendingEsc !== null) {
-      clearTimeout(pendingEsc)
-      pendingEsc = null
-    }
+    const { sigint } = ctrl.onChunk(chunk)
+    if (sigint) process.kill(process.pid, 'SIGINT')
   }
 
   const start = (): void => {
@@ -166,27 +150,28 @@ function createEscListener(): EscListener | null {
       /* terminal already torn down */
     }
     stdin.pause()
-    if (pendingEsc !== null) {
-      clearTimeout(pendingEsc)
-      pendingEsc = null
-    }
+    ctrl.clearPending()
   }
 
   return {
     armForStream: () => {
-      currentCtrl = new AbortController()
+      const signal = ctrl.armForStream()
       start()
-      return currentCtrl.signal
+      return signal
     },
     pause: () => {
       stop()
     },
     resume: () => {
-      currentCtrl = new AbortController()
+      // Resume the listener WITHOUT replacing the AbortController.
+      // The signal returned by armForStream() is held by the live source
+      // through streamSession's combinedSignal; replacing the controller
+      // here would orphan that signal so a subsequent ESC press could
+      // not abort the live tail.
       start()
     },
     stop: () => {
-      currentCtrl = null
+      ctrl.dispose()
       stop()
     },
   }
@@ -204,8 +189,15 @@ function useColor(): boolean {
   return Boolean(process.stdout.isTTY)
 }
 
-async function clackSelect(sessions: SessionSummary[]): Promise<SessionSummary | null> {
+async function clackSelect(
+  sessions: SessionSummary[],
+  initialSessionId: string | undefined,
+): Promise<SessionSummary | null> {
   const { select } = await import('@clack/prompts')
+  const preferred =
+    initialSessionId !== undefined && sessions.some((s) => s.sessionId === initialSessionId)
+      ? initialSessionId
+      : sessions[0]?.sessionId
   const picked = await select<string>({
     message: `Pick a session to inspect (showing ${sessions.length})`,
     options: sessions.map((s) => ({
@@ -213,7 +205,7 @@ async function clackSelect(sessions: SessionSummary[]): Promise<SessionSummary |
       label: formatRowLabel(s),
       ...(s.firstPrompt !== null ? { hint: truncate(s.firstPrompt, 60) } : { hint: '(no prompt)' }),
     })),
-    initialValue: sessions[0]?.sessionId,
+    initialValue: preferred,
   })
   if (isCancel(picked)) {
     cancel('Cancelled.')