typeclaw 0.35.1 → 0.36.0

package/src/bundled-plugins/security/policies/plugin-addition.ts

@@ -0,0 +1,240 @@
+import { readFile, realpath } from 'node:fs/promises'
+import path from 'node:path'
+
+import { parseConfigJson } from '@/config'
+import { splitPluginEntrySpec } from '@/plugin'
+
+import type { SecuritySeverity } from '../permissions'
+import { ACKNOWLEDGE_GUARDS, type SecurityBlock, isGuardAcknowledged } from '../policy'
+
+export const GUARD_PLUGIN_ADDITION = 'pluginAddition'
+// Classified `medium` (silent-attack axis), same tier and rationale as
+// `rolePromotion` and `cronPromotion`. Adding (or version-bumping) a plugin in
+// typeclaw.json is a deferred host-code-execution grant: the entry is
+// materialized into package.json by `reconcilePluginDeps` and installed by the
+// next host `typeclaw start`, at which point npm lifecycle scripts run as the
+// operator on the host. `plugins` is restart-required and typeclaw.json is
+// force-committed by auto-backup, so the operator sees the change in `git log`
+// and backup commits BEFORE any install fires — an operator-reviewable window
+// between the privileged write and the privileged execution. Owner and trusted
+// bypass without ack; member and guest are blocked.
+//
+// What counts as a plugin addition (any of):
+//   1. A new entry appeared in `plugins[]` (by package name).
+//   2. An existing entry's pinned version spec changed (`foo@1` -> `foo@2`):
+//      a different package version is a different body of host code, the same
+//      shape as cron's body-changed finding.
+//
+// What does NOT count (allowed without ack):
+//   - Removing an entry from `plugins[]` (a privilege REDUCTION; uninstalling
+//     runs no untrusted code).
+//   - Reordering entries.
+//   - Local-path entries (`./`, `../`, absolute): these are never installed
+//     from a registry, so there is no lifecycle-script execution to gate. They
+//     are confined to the agent dir by the loader.
+//
+// Failure-open is deliberate, same direction as the sibling guards: an
+// unreadable/unparseable existing typeclaw.json makes every proposed entry look
+// new and blocks. The only false positive is an operator authoring a fresh
+// config with plugins, which they ack in the same call.
+export const GUARD_PLUGIN_ADDITION_SEVERITY: SecuritySeverity = 'medium'
+
+export type PluginAdditionFinding =
+  | { kind: 'plugin-added'; name: string; versionSpec: string }
+  | { kind: 'version-changed'; name: string; from: string; to: string }
+
+export async function checkPluginAdditionGuard(options: {
+  tool: string
+  args: Record<string, unknown>
+  agentDir: string
+}): Promise<SecurityBlock | undefined> {
+  const { tool, args, agentDir } = options
+  if (tool !== 'write' && tool !== 'edit') return undefined
+
+  const rawPath = args.path
+  if (typeof rawPath !== 'string') return undefined
+
+  const targetPath = path.resolve(agentDir, rawPath)
+  if (!(await pathIsTypeclawJson(agentDir, targetPath))) return undefined
+
+  if (isGuardAcknowledged(args, GUARD_PLUGIN_ADDITION)) return undefined
+
+  const editRefusal = refuseRiskyEdit(tool, args, targetPath)
+  if (editRefusal) return editRefusal
+
+  const newContent = await intendedContent(tool, args, targetPath)
+  if (newContent === undefined) return undefined
+
+  const newPlugins = parsePluginsFromContent(newContent)
+  if (newPlugins === undefined) return undefined
+
+  const oldPlugins = await readExistingPlugins(targetPath)
+  const findings = diffPlugins(oldPlugins, newPlugins)
+  if (findings.length === 0) return undefined
+
+  return {
+    block: true,
+    reason: buildBlockReason(tool, targetPath, findings),
+  }
+}
+
+export function diffPlugins(before: readonly string[], after: readonly string[]): PluginAdditionFinding[] {
+  const findings: PluginAdditionFinding[] = []
+  const beforeByName = new Map<string, string | undefined>()
+  for (const entry of before) {
+    if (isLocalEntry(entry)) continue
+    const { name, versionSpec } = splitPluginEntrySpec(entry)
+    beforeByName.set(name, versionSpec)
+  }
+
+  for (const entry of after) {
+    if (isLocalEntry(entry)) continue
+    const { name, versionSpec } = splitPluginEntrySpec(entry)
+    if (!beforeByName.has(name)) {
+      findings.push({ kind: 'plugin-added', name, versionSpec: versionSpec ?? '<latest>' })
+      continue
+    }
+    const priorSpec = beforeByName.get(name)
+    if (priorSpec !== versionSpec) {
+      findings.push({
+        kind: 'version-changed',
+        name,
+        from: priorSpec ?? '<latest>',
+        to: versionSpec ?? '<latest>',
+      })
+    }
+  }
+  return findings
+}
+
+function isLocalEntry(entry: string): boolean {
+  return entry.startsWith('./') || entry.startsWith('../') || path.isAbsolute(entry)
+}
+
+function parsePluginsFromContent(content: string): readonly string[] | undefined {
+  const result = parseConfigJson(content, { migrate: false })
+  if (!result.ok) return undefined
+  return result.config.plugins ?? []
+}
+
+async function readExistingPlugins(targetPath: string): Promise<readonly string[]> {
+  let raw: string
+  try {
+    raw = await readFile(targetPath, 'utf8')
+  } catch {
+    return []
+  }
+  const result = parseConfigJson(raw, { migrate: false })
+  if (!result.ok) return []
+  return result.config.plugins ?? []
+}
+
+// See the parallel rationale block in role-promotion.ts — Oracle PR #305
+// findings #5 and #6 (symlinked managed file + case-insensitive FS).
+async function pathIsTypeclawJson(agentDir: string, targetPath: string): Promise<boolean> {
+  const resolvedAgentDir = path.resolve(agentDir)
+  const canonicalManagedPath = path.join(resolvedAgentDir, 'typeclaw.json')
+  const resolvedTarget = path.resolve(targetPath)
+  if (canonicalManagedPath === resolvedTarget) return true
+  const realCanonical = await resolveRealPath(canonicalManagedPath)
+  const realTarget = await resolveRealPath(resolvedTarget)
+  return realCanonical === realTarget
+}
+
+// Symmetric with role/cron-promotion's refuseRiskyEdit. See Oracle PR #305
+// finding #4: simulator-vs-real divergence on multi-edit, plus non-unique
+// oldText ambiguity. Conservative refusal keeps the guard honest without
+// re-implementing the edit-diff semantics inside the security plugin.
+function refuseRiskyEdit(tool: string, args: Record<string, unknown>, targetPath: string): SecurityBlock | undefined {
+  if (tool !== 'edit') return undefined
+  const edits = args.edits
+  if (!Array.isArray(edits)) return undefined
+  if (edits.length > 1) {
+    return {
+      block: true,
+      reason: [
+        `Guard \`${GUARD_PLUGIN_ADDITION}\` refuses multi-edit on ${targetPath}: the security guard's edit simulator cannot match the pi-coding-agent edit tool's original-content semantics for multi-edit calls.`,
+        'Use `write` with the full file content instead — this is the canonical workflow for managed config files.',
+      ].join(' '),
+    }
+  }
+  return undefined
+}
+
+async function intendedContent(
+  tool: string,
+  args: Record<string, unknown>,
+  targetPath: string,
+): Promise<string | undefined> {
+  if (tool === 'write') {
+    return typeof args.content === 'string' ? args.content : undefined
+  }
+  const edits = args.edits
+  if (!Array.isArray(edits)) return undefined
+  let content: string
+  try {
+    content = await readFile(targetPath, 'utf8')
+  } catch {
+    return undefined
+  }
+  for (const edit of edits) {
+    if (!edit || typeof edit !== 'object') return undefined
+    const { oldText, newText } = edit as Record<string, unknown>
+    if (typeof oldText !== 'string' || typeof newText !== 'string') return undefined
+    if (oldText.length === 0) return undefined
+    const firstIdx = content.indexOf(oldText)
+    if (firstIdx === -1) return undefined
+    if (content.indexOf(oldText, firstIdx + 1) !== -1) return undefined
+    content = content.slice(0, firstIdx) + newText + content.slice(firstIdx + oldText.length)
+  }
+  return content
+}
+
+function buildBlockReason(tool: string, targetPath: string, findings: readonly PluginAdditionFinding[]): string {
+  const lines: string[] = []
+  for (const f of findings) {
+    const name = sanitizeForReason(f.name)
+    if (f.kind === 'plugin-added') {
+      lines.push(`new plugin \`${name}\` (${sanitizeForReason(f.versionSpec)}) would be installed on the host`)
+    } else {
+      lines.push(
+        `plugin \`${name}\` version changes \`${sanitizeForReason(f.from)}\` -> \`${sanitizeForReason(f.to)}\``,
+      )
+    }
+  }
+  return [
+    `Guard \`${GUARD_PLUGIN_ADDITION}\` blocked ${tool} on ${sanitizeForReason(targetPath)}: this change introduces a deferred host-code-execution grant — ${lines.join('; ')}.`,
+    "Plugin entries in typeclaw.json#plugins are materialized into package.json and installed by the next host `typeclaw start`, where npm lifecycle scripts run as the operator on the host. Even an `owner` operating from TUI must not silently add plugins on behalf of a channel message: the canonical attack is a prompt-injected agent writing a malicious package name into plugins[] so the operator's next start runs its postinstall.",
+    `If this is genuinely intentional and the operator explicitly asked for it (not a channel message), retry with \`${ACKNOWLEDGE_GUARDS}.${GUARD_PLUGIN_ADDITION}: true\` in the tool arguments.`,
+  ].join(' ')
+}
+
+const MAX_REASON_TOKEN_LEN = 200
+
+function sanitizeForReason(value: string): string {
+  // eslint-disable-next-line no-control-regex
+  const cleaned = value.replace(/[\u0000-\u001f\u007f]/g, '').replace(/`/g, "'")
+  if (cleaned.length <= MAX_REASON_TOKEN_LEN) return cleaned
+  return `${cleaned.slice(0, MAX_REASON_TOKEN_LEN)}...`
+}
+
+async function resolveRealPath(absolutePath: string): Promise<string> {
+  const pending: string[] = []
+  let current = absolutePath
+  while (true) {
+    try {
+      const real = await realpath(current)
+      return path.join(real, ...pending.reverse())
+    } catch (err) {
+      if (!isNotFound(err)) throw err
+    }
+    const parent = path.dirname(current)
+    if (parent === current) return absolutePath
+    pending.push(path.basename(current))
+    current = parent
+  }
+}
+
+function isNotFound(err: unknown): boolean {
+  return err instanceof Error && 'code' in err && (err as { code: unknown }).code === 'ENOENT'
+}

package/src/channels/adapters/line.ts

@@ -1,5 +1,6 @@
 import {
   LineClient as RealLineClient,
+  type LineCredentialManager,
   LineListener as RealLineListener,
   type LineAccountCredentials,
   type LineChat,
@@ -53,7 +54,7 @@ export type LineCredentialStore = {
   getAccount(id?: string): Promise<LineAccountCredentials | null>
 }
 
-const LineClient = RealLineClient as unknown as new () => LineClient
+const LineClient = RealLineClient as unknown as new (credManager?: LineCredentialManager) => LineClient
 const LineListener = RealLineListener as unknown as new (client: LineClient) => LineListener
 
 export type LineAdapterLogger = {
@@ -75,6 +76,7 @@ export type LineAdapterOptions = {
   selfAliasesRef?: () => readonly string[]
   credentialsStore?: LineCredentialStore
   client?: LineClient
+  clientFactory?: (credManager?: LineCredentialManager) => LineClient
   listenerFactory?: (client: LineClient) => LineListener
 }
 
@@ -163,7 +165,15 @@ function clampLimit(requested: number, max: number): number {
 
 export function createLineAdapter(options: LineAdapterOptions): LineAdapter {
   const logger = options.logger ?? consoleLogger
-  const client = options.client ?? new LineClient()
+  // LineListener.connect() re-calls client.login() with NO arguments on every
+  // (re)connect, which resolves credentials via the client's credential manager
+  // rather than the explicit account start() passes. Wire the secrets.json store
+  // in as that manager (same structural cast as src/init/line-auth.ts) so the
+  // reconnect path doesn't fall through to the SDK's default file-based manager
+  // and loop forever on "No account found".
+  const credManager = options.credentialsStore as unknown as LineCredentialManager | undefined
+  const buildClient = options.clientFactory ?? ((cm?: LineCredentialManager) => new LineClient(cm))
+  const client = options.client ?? buildClient(credManager)
   let listener: LineListener | null = null
   let selfUserId: string | null = null
   let connected = false

package/src/cli/channel.ts

@@ -4,6 +4,12 @@ import { cancel, confirm, intro, isCancel, log, note, password, select, spinner,
 import { defineCommand } from 'citty'
 
 import { config } from '@/config'
+import {
+  listChannels,
+  removeChannel,
+  type ChannelListEntry,
+  type GithubConfigCleanup,
+} from '@/config/channels-mutation'
 import { start, status, stop } from '@/container'
 import {
   CHANNEL_KINDS,
@@ -30,7 +36,7 @@ import { SecretsKakaoCredentialStore } from '@/secrets/kakao-store'
 
 import { CANCEL_SYMBOL, promptPrivateKeyPem } from './prompt-pem'
 import { displayQR } from './qr'
-import { c, done, errorLine, printDiscordInviteHint, printSlackAppManifestSetup } from './ui'
+import { c, done, errorLine, printDiscordInviteHint, printSlackAppManifestSetup, successLine } from './ui'
 
 const CHANNEL_LABELS: Record<ChannelKind, string> = {
   'slack-bot': 'Slack',
@@ -185,6 +191,95 @@ const reauthSub = defineCommand({
   },
 })
 
+const listSub = defineCommand({
+  meta: {
+    name: 'list',
+    description: 'list channel adapters configured for this agent',
+  },
+  args: {
+    json: {
+      type: 'boolean',
+      description: 'emit channels as JSON',
+      default: false,
+    },
+  },
+  async run({ args }) {
+    const cwd = findAgentDir(process.cwd()) ?? process.cwd()
+    if (!isInitialized(cwd)) {
+      console.error(errorLine('TypeClaw config file not found. Run `typeclaw init` first, or cd into an agent folder.'))
+      process.exit(1)
+    }
+    const channels = listChannels(cwd)
+    if (args.json) {
+      process.stdout.write(`${JSON.stringify({ channels }, null, 2)}\n`)
+      return
+    }
+    process.stdout.write(`${formatChannelList(channels)}\n`)
+  },
+})
+
+const removeSub = defineCommand({
+  meta: {
+    name: 'remove',
+    description: 'remove a channel adapter from typeclaw.json and secrets.json',
+  },
+  args: {
+    adapter: {
+      type: 'positional',
+      description: `which adapter to remove (${CHANNEL_KINDS.join(' | ')}); omit to pick interactively`,
+      required: false,
+    },
+    yes: {
+      type: 'boolean',
+      description: 'skip the confirmation prompt',
+      default: false,
+    },
+  },
+  async run({ args }) {
+    const cwd = findAgentDir(process.cwd()) ?? process.cwd()
+    if (!isInitialized(cwd)) {
+      console.error(errorLine('TypeClaw config file not found. Run `typeclaw init` first, or cd into an agent folder.'))
+      process.exit(1)
+    }
+
+    const present = presentChannels(listChannels(cwd))
+    if (present.length === 0) {
+      console.error(errorLine('No channels are configured. Nothing to remove.'))
+      process.exit(1)
+    }
+
+    const adapter =
+      args.adapter === undefined ? await pickChannelToRemove(present) : validateRemoveAdapterArg(args.adapter, present)
+
+    if (args.yes !== true) {
+      const confirmed = await confirm({
+        message: `Remove the ${CHANNEL_LABELS[adapter]} channel? This deletes its config and credentials.`,
+        initialValue: false,
+      })
+      if (isCancel(confirmed) || !confirmed) {
+        cancel('Aborted.')
+        process.exit(0)
+      }
+    }
+
+    const result = removeChannel(cwd, adapter)
+    if (!result.ok) {
+      console.error(errorLine(result.reason))
+      process.exit(1)
+    }
+
+    process.stdout.write(`${successLine(`Removed ${CHANNEL_LABELS[adapter]} channel.`)}\n`)
+    if (result.githubCleanup !== undefined) printGithubCleanup(result.githubCleanup)
+    if (result.hadRemoteWebhooks) {
+      log.warn(
+        'GitHub webhooks registered on your repositories were NOT deleted. Remove them by hand at https://github.com/<owner>/<repo>/settings/hooks.',
+      )
+    }
+
+    await maybePromptRestart(cwd, adapter, 'removed')
+  },
+})
+
 export const channelCommand = defineCommand({
   meta: {
     name: 'channel',
@@ -194,9 +289,92 @@ export const channelCommand = defineCommand({
     add: addSub,
     set: setSub,
     reauth: reauthSub,
+    list: listSub,
+    remove: removeSub,
   },
 })
 
+function presentChannels(entries: ChannelListEntry[]): ChannelKind[] {
+  return entries.map((entry) => entry.kind)
+}
+
+async function pickChannelToRemove(present: ChannelKind[]): Promise<ChannelKind> {
+  if (present.length === 1) return present[0]!
+  const selected = await select<ChannelKind>({
+    message: 'Pick a channel to remove',
+    options: present.map((kind) => ({ value: kind, label: CHANNEL_LABELS[kind] })),
+    initialValue: present[0],
+  })
+  if (isCancel(selected)) {
+    cancel('Aborted.')
+    process.exit(0)
+  }
+  return selected
+}
+
+function validateRemoveAdapterArg(adapter: string, present: ChannelKind[]): ChannelKind {
+  if (!isChannelKind(adapter)) {
+    console.error(errorLine(`Unknown adapter "${adapter}". Expected one of: ${CHANNEL_KINDS.join(', ')}.`))
+    process.exit(1)
+  }
+  if (!present.includes(adapter)) {
+    console.error(
+      errorLine(
+        `${CHANNEL_LABELS[adapter]} ("${adapter}") is not configured. Run \`typeclaw channel list\` to see what is.`,
+      ),
+    )
+    process.exit(1)
+  }
+  return adapter
+}
+
+function formatChannelList(channels: ChannelListEntry[]): string {
+  if (channels.length === 0) return c.dim('No channels configured.')
+
+  const kindWidth = Math.max(4, ...channels.map((ch) => ch.kind.length))
+  const statusWidth = Math.max(6, ...channels.map((ch) => channelStatusText(ch).length))
+  const lines: string[] = []
+  lines.push(c.dim(`${'KIND'.padEnd(kindWidth)}  ${'STATUS'.padEnd(statusWidth)}  DETAIL`))
+  for (const ch of channels) {
+    const statusText = channelStatusText(ch)
+    const status = channelStatusOk(ch)
+      ? c.green(statusText.padEnd(statusWidth))
+      : c.yellow(statusText.padEnd(statusWidth))
+    const detail = ch.detail ?? ''
+    lines.push(`${ch.kind.padEnd(kindWidth)}  ${status}  ${c.dim(detail)}`)
+  }
+  return lines.join('\n')
+}
+
+function channelStatusOk(ch: ChannelListEntry): boolean {
+  return ch.configured && ch.hasSecrets && ch.enabled
+}
+
+function channelStatusText(ch: ChannelListEntry): string {
+  if (!ch.configured) return 'secrets-only'
+  if (!ch.hasSecrets) return 'no-secrets'
+  if (!ch.enabled) return 'disabled'
+  return 'ready'
+}
+
+function printGithubCleanup(cleanup: GithubConfigCleanup): void {
+  const parts: string[] = []
+  if (cleanup.tunnelsRemoved > 0) {
+    parts.push(`removed ${cleanup.tunnelsRemoved} GitHub webhook tunnel${cleanup.tunnelsRemoved === 1 ? '' : 's'}`)
+  }
+  if (cleanup.matchRulesRemoved.length > 0) {
+    parts.push(
+      `removed ${cleanup.matchRulesRemoved.length} repo match rule${cleanup.matchRulesRemoved.length === 1 ? '' : 's'}`,
+    )
+  }
+  if (parts.length > 0) process.stdout.write(`${c.dim(`Also ${parts.join(', ')}.`)}\n`)
+  if (cleanup.matchRulesKept.length > 0) {
+    log.warn(
+      `Left ${cleanup.matchRulesKept.length} other \`github:\` match rule(s) in roles.member untouched: ${cleanup.matchRulesKept.join(', ')}.`,
+    )
+  }
+}
+
 async function resolveReauthableAdapter(
   requested: string | undefined,
   configured: Set<ChannelKind>,
@@ -1269,12 +1447,16 @@ function reportLineAuth(result: LineAuthResult): string {
   return `LINE login failed: ${result.reason}`
 }
 
-async function maybePromptRestart(cwd: string, channel: ChannelKind): Promise<void> {
+async function maybePromptRestart(
+  cwd: string,
+  channel: ChannelKind,
+  verb: 'added' | 'removed' = 'added',
+): Promise<void> {
   const label = CHANNEL_LABELS[channel]
   const current = await status({ cwd }).catch(() => null)
   if (current === null || current.kind !== 'running') {
     done({
-      title: c.green(`${label} channel added.`),
+      title: c.green(`${label} channel ${verb}.`),
       hints: [
         { label: 'Start the agent:', command: 'typeclaw start' },
         { label: 'Then check status:', command: 'typeclaw status' },
@@ -1284,13 +1466,12 @@ async function maybePromptRestart(cwd: string, channel: ChannelKind): Promise<vo
   }
 
   const restartNow = await confirm({
-    message:
-      'Channel config is restart-required and the agent container is running. Restart it now to apply the new channel?',
+    message: `Channel config is restart-required and the agent container is running. Restart it now to apply the ${verb} channel?`,
     initialValue: true,
   })
   if (isCancel(restartNow) || !restartNow) {
     done({
-      title: c.green(`${label} channel added.`),
+      title: c.green(`${label} channel ${verb}.`),
       hints: [
         { label: 'Apply later:', command: 'typeclaw restart' },
         { label: 'Check status:', command: 'typeclaw status' },
@@ -1310,7 +1491,9 @@ async function maybePromptRestart(cwd: string, channel: ChannelKind): Promise<vo
     process.exit(1)
   }
   done({
-    title: c.green(`${label} channel added. Restarted ${started.plan.containerName} on host port ${started.hostPort}.`),
+    title: c.green(
+      `${label} channel ${verb}. Restarted ${started.plan.containerName} on host port ${started.hostPort}.`,
+    ),
     hints: [
       { label: 'Attach TUI:', command: 'typeclaw tui' },
       { label: 'Follow logs:', command: 'typeclaw logs -f' },

package/src/cli/inspect-select.ts

@@ -0,0 +1,121 @@
+import type { Readable, Writable } from 'node:stream'
+import { styleText } from 'node:util'
+
+import { SelectPrompt, settings } from '@clack/core'
+import { limitOptions, S_BAR, S_BAR_END, S_RADIO_ACTIVE, S_RADIO_INACTIVE, symbolBar } from '@clack/prompts'
+
+export type RefreshableOption<Value> = { value: Value; label: string; hint?: string; disabled?: boolean }
+
+export type RefreshableSelectResult<Value> =
+  | { kind: 'picked'; value: Value }
+  | { kind: 'cancelled' }
+  | { kind: 'refresh'; highlightValue: Value }
+
+export type RefreshableSelectOptions<Value> = {
+  message: string
+  options: RefreshableOption<Value>[]
+  initialValue?: Value
+  maxItems?: number
+  input?: Readable
+  output?: Writable
+}
+
+export const REFRESH_KEY = 'r'
+
+// The cursor's value, falling back to the first row so a refresh on an empty
+// cursor still carries a stable highlight.
+export function highlightAt<Value>(options: RefreshableOption<Value>[], cursor: number): Value | undefined {
+  return options[cursor]?.value ?? options[0]?.value
+}
+
+// `refreshed` distinguishes an `r`-triggered abort (which also resolves to the
+// cancel symbol) from a genuine ESC/Ctrl-C cancel.
+export function toSelectResult<Value>(
+  result: Value | symbol,
+  refresh: { refreshed: boolean; highlightValue?: Value },
+): RefreshableSelectResult<Value> {
+  if (refresh.refreshed) return { kind: 'refresh', highlightValue: refresh.highlightValue as Value }
+  if (typeof result === 'symbol') return { kind: 'cancelled' }
+  return { kind: 'picked', value: result }
+}
+
+// A drop-in `select` that adds an `r`-to-refresh affordance. `@clack/prompts`'s
+// `select` hides its prompt instance, so it can't expose the `key` event or the
+// live cursor; dropping to `@clack/core`'s SelectPrompt is the only seam that
+// can observe `r` without racing clack's own raw-mode stdin handling. The render
+// below is ported from `@clack/prompts`'s select so the picker looks identical.
+export async function refreshableSelect<Value>(
+  opts: RefreshableSelectOptions<Value>,
+): Promise<RefreshableSelectResult<Value>> {
+  const optionsList = opts.options
+  const refreshController = new AbortController()
+  const refresh: { refreshed: boolean; highlightValue?: Value } = { refreshed: false }
+
+  const prompt = new SelectPrompt<RefreshableOption<Value>>({
+    options: optionsList,
+    initialValue: opts.initialValue,
+    signal: refreshController.signal,
+    ...(opts.input !== undefined ? { input: opts.input } : {}),
+    ...(opts.output !== undefined ? { output: opts.output } : {}),
+    render() {
+      return renderSelect(this as SelectPrompt<RefreshableOption<Value>>, opts.message, {
+        ...(opts.maxItems !== undefined ? { maxItems: opts.maxItems } : {}),
+        ...(opts.output !== undefined ? { output: opts.output } : {}),
+      })
+    },
+  })
+
+  prompt.on('key', (char) => {
+    if (char !== REFRESH_KEY) return
+    refresh.refreshed = true
+    refresh.highlightValue = highlightAt(optionsList, prompt.cursor)
+    // Reuse the prompt's own signal-abort cancel path: it sets state to cancel
+    // and runs close() (raw-mode + listener teardown), resolving `.prompt()`.
+    refreshController.abort()
+  })
+
+  const result = (await prompt.prompt()) as Value | symbol
+  return toSelectResult(result, refresh)
+}
+
+function renderSelect<Value>(
+  prompt: SelectPrompt<RefreshableOption<Value>>,
+  message: string,
+  limits: { maxItems?: number; output?: Writable },
+): string {
+  const hasGuide = settings.withGuide
+  const titlePrefixBar = `${symbolBar(prompt.state)}  `
+  const title = `${hasGuide ? `${styleText('gray', S_BAR)}\n` : ''}${titlePrefixBar}${message}\n`
+
+  if (prompt.state === 'submit' || prompt.state === 'cancel') {
+    const closePrefix = hasGuide ? `${styleText('gray', S_BAR)}  ` : ''
+    const label = prompt.options[prompt.cursor]?.label ?? ''
+    const closed = prompt.state === 'cancel' ? styleText(['strikethrough', 'dim'], label) : styleText('dim', label)
+    const tail = prompt.state === 'cancel' && hasGuide ? `\n${styleText('gray', S_BAR)}` : ''
+    return `${title}${closePrefix}${closed}${tail}`
+  }
+
+  const prefix = hasGuide ? `${styleText('cyan', S_BAR)}  ` : ''
+  const prefixEnd = hasGuide ? styleText('cyan', S_BAR_END) : ''
+  const rendered = limitOptions({
+    cursor: prompt.cursor,
+    options: prompt.options,
+    ...(limits.maxItems !== undefined ? { maxItems: limits.maxItems } : {}),
+    ...(limits.output !== undefined ? { output: limits.output } : {}),
+    style: (item, active) => optionLine(item, item.disabled === true ? 'disabled' : active ? 'active' : 'inactive'),
+  }).join(`\n${prefix}`)
+  return `${title}${prefix}${rendered}\n${prefixEnd}\n`
+}
+
+function optionLine<Value>(option: RefreshableOption<Value>, state: 'inactive' | 'active' | 'disabled'): string {
+  const { label } = option
+  if (state === 'disabled') {
+    const hint = option.hint !== undefined ? ` ${styleText('dim', `(${option.hint})`)}` : ''
+    return `${styleText('gray', S_RADIO_INACTIVE)} ${styleText('gray', label)}${hint}`
+  }
+  if (state === 'active') {
+    const hint = option.hint !== undefined ? ` ${styleText('dim', `(${option.hint})`)}` : ''
+    return `${styleText('green', S_RADIO_ACTIVE)} ${label}${hint}`
+  }
+  return `${styleText('dim', S_RADIO_INACTIVE)} ${styleText('dim', label)}`
+}