typeclaw 0.35.1 → 0.36.0

package/src/cli/inspect.ts

@@ -12,6 +12,7 @@ import {
   runViewerLoop,
   streamLive,
   type LiveSourceFactory,
+  type SelectOutcome,
   type SessionSummary,
   type ViewerItem,
 } from '@/inspect'
@@ -250,14 +251,17 @@ function useColor(): boolean {
   return Boolean(process.stdout.isTTY)
 }
 
-async function clackSelectItem(items: ViewerItem[], initialKey: string | undefined): Promise<ViewerItem | null> {
-  const { select } = await import('@clack/prompts')
+async function clackSelectItem(
+  items: ViewerItem[],
+  initialKey: string | undefined,
+): Promise<SelectOutcome<ViewerItem>> {
+  const { refreshableSelect } = await import('./inspect-select')
   prepareStdinForClack()
   const keyOf = (item: ViewerItem): string => (item.kind === 'logs' ? 'logs' : item.summary.sessionId)
   const preferred =
     initialKey !== undefined && items.some((i) => keyOf(i) === initialKey) ? initialKey : keyOf(items[0]!)
-  const picked = await select<string>({
-    message: `Pick what to view (showing ${items.length})`,
+  const outcome = await refreshableSelect<string>({
+    message: `Pick what to view (showing ${items.length}) ${c.dim('· r to refresh')}`,
     options: items.map((item) => ({
       value: keyOf(item),
       label: itemLabel(item),
@@ -265,11 +269,15 @@ async function clackSelectItem(items: ViewerItem[], initialKey: string | undefin
     })),
     initialValue: preferred,
   })
-  if (isCancel(picked)) {
+  if (outcome.kind === 'cancelled') {
     cancel('Cancelled.')
-    return null
+    return { kind: 'cancelled' }
+  }
+  if (outcome.kind === 'refresh') {
+    return { kind: 'refresh', highlightKey: outcome.highlightValue }
   }
-  return items.find((i) => keyOf(i) === picked) ?? null
+  const chosen = items.find((i) => keyOf(i) === outcome.value)
+  return chosen !== undefined ? { kind: 'picked', item: chosen } : { kind: 'cancelled' }
 }
 
 async function clackSelectSession(

package/src/config/channels-mutation.ts

@@ -0,0 +1,250 @@
+import { readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { commitSystemFileSync } from '@/git/system-commit'
+import { SecretsBackend } from '@/secrets'
+
+const CONFIG_FILE = 'typeclaw.json'
+const SECRETS_FILE = 'secrets.json'
+
+export const CHANNEL_KINDS = ['slack-bot', 'discord-bot', 'telegram-bot', 'line', 'kakaotalk', 'github'] as const
+
+export type ChannelKind = (typeof CHANNEL_KINDS)[number]
+
+export type ChannelListEntry = {
+  kind: ChannelKind
+  configured: boolean
+  hasSecrets: boolean
+  enabled: boolean
+  detail?: string
+}
+
+export type GithubConfigCleanup = {
+  tunnelsRemoved: number
+  matchRulesRemoved: string[]
+  matchRulesKept: string[]
+}
+
+export type RemoveChannelResult =
+  | {
+      ok: true
+      configRemoved: boolean
+      secretsRemoved: boolean
+      githubCleanup?: GithubConfigCleanup
+      hadRemoteWebhooks: boolean
+    }
+  | { ok: false; reason: string }
+
+export function isChannelKind(value: string): value is ChannelKind {
+  return (CHANNEL_KINDS as ReadonlyArray<string>).includes(value)
+}
+
+export function listChannels(cwd: string): ChannelListEntry[] {
+  const config = readConfigRecordOrEmpty(cwd)
+  const configuredChannels = isObjectRecord(config.channels) ? config.channels : {}
+  const secrets = channelSecretsOrEmpty(readChannelSecrets(cwd))
+
+  return CHANNEL_KINDS.map((kind) => {
+    const channelConfig = configuredChannels[kind]
+    const configured = kind in configuredChannels
+    const hasSecrets = kind in secrets
+    return {
+      kind,
+      configured,
+      hasSecrets,
+      enabled: readEnabled(channelConfig),
+      ...buildDetail(kind, channelConfig, secrets[kind]),
+    }
+  }).filter((entry) => entry.configured || entry.hasSecrets)
+}
+
+export function removeChannel(cwd: string, kind: ChannelKind): RemoveChannelResult {
+  const config = readConfigRecord(cwd)
+  if (!config.ok) return config
+
+  const channels = isObjectRecord(config.value.channels) ? { ...config.value.channels } : {}
+
+  // Bail BEFORE touching typeclaw.json when secrets.json exists but cannot be
+  // read. Otherwise the config write below would strip `channels.<kind>` while
+  // the credential block stays on disk yet unreachable — `removeChannelSync`
+  // would throw on the same parse error, and the next invocation would no
+  // longer see the channel in config OR (the swallowed) secrets, stranding the
+  // credentials with no CLI path to clean them. Failing first keeps the retry
+  // able to target both once the file is fixed.
+  const secretsRead = readChannelSecrets(cwd)
+  if (secretsRead.kind === 'unreadable') {
+    return {
+      ok: false,
+      reason: `${SECRETS_FILE} is unreadable (${secretsRead.reason}). Fix it by hand, then retry \`typeclaw channel remove ${kind}\`.`,
+    }
+  }
+  const secrets = channelSecretsOrEmpty(secretsRead)
+
+  const inConfig = kind in channels
+  const inSecrets = kind in secrets
+  if (!inConfig && !inSecrets) {
+    return { ok: false, reason: `Channel "${kind}" is not configured in ${CONFIG_FILE} or ${SECRETS_FILE}.` }
+  }
+
+  const githubRepos = kind === 'github' ? readGithubRepos(channels.github) : []
+  const hadRemoteWebhooks = githubRepos.length > 0
+
+  delete channels[kind]
+  config.value.channels = channels
+
+  const githubCleanup = kind === 'github' ? cleanGithubConfig(config.value, githubRepos) : undefined
+
+  const write = writeConfig(cwd, config.value, `channel: remove ${kind}`)
+  if (!write.ok) return write
+
+  const secretsRemoved = new SecretsBackend(join(cwd, SECRETS_FILE)).removeChannelSync(kind)
+
+  return {
+    ok: true,
+    configRemoved: inConfig,
+    secretsRemoved,
+    ...(githubCleanup !== undefined ? { githubCleanup } : {}),
+    hadRemoteWebhooks,
+  }
+}
+
+// GitHub `add` writes three config artifacts beyond `channels.github`: a
+// `tunnels[]` entry marked `for: { kind: 'channel', name: 'github' }`,
+// `roles.member.match[]` rules `github:<owner>/<repo>`, and the
+// `docker.file.cloudflared` enablement flag. Removal strips the first two
+// (both channel-owned) but intentionally leaves `docker.file.cloudflared`: it
+// is a shared enablement flag a remaining tunnel may still need. Match-rule
+// stripping is scoped to the configured repos so hand-authored `github:`
+// identities survive.
+function cleanGithubConfig(config: Record<string, unknown>, repos: string[]): GithubConfigCleanup {
+  const tunnelsRemoved = removeGithubTunnels(config)
+  const { removed, kept } = removeGithubMatchRules(config, repos)
+  return { tunnelsRemoved, matchRulesRemoved: removed, matchRulesKept: kept }
+}
+
+function removeGithubTunnels(config: Record<string, unknown>): number {
+  if (!Array.isArray(config.tunnels)) return 0
+  const before = config.tunnels.length
+  config.tunnels = config.tunnels.filter((entry) => !isGithubChannelTunnel(entry))
+  return before - (config.tunnels as unknown[]).length
+}
+
+function isGithubChannelTunnel(entry: unknown): boolean {
+  if (!isObjectRecord(entry)) return false
+  const target = entry.for
+  if (!isObjectRecord(target)) return false
+  return target.kind === 'channel' && target.name === 'github'
+}
+
+function readGithubRepos(githubConfig: unknown): string[] {
+  if (!isObjectRecord(githubConfig) || !Array.isArray(githubConfig.repos)) return []
+  return githubConfig.repos.filter((repo): repo is string => typeof repo === 'string')
+}
+
+function removeGithubMatchRules(
+  config: Record<string, unknown>,
+  repos: string[],
+): { removed: string[]; kept: string[] } {
+  const roles = isObjectRecord(config.roles) ? { ...config.roles } : undefined
+  const member = roles !== undefined && isObjectRecord(roles.member) ? { ...roles.member } : undefined
+  if (roles === undefined || member === undefined || !Array.isArray(member.match)) {
+    return { removed: [], kept: [] }
+  }
+
+  const toRemove = new Set(repos.map((repo) => `github:${repo}`))
+  const removed: string[] = []
+  const kept: string[] = []
+  const next = member.match
+    .filter((rule): rule is string => typeof rule === 'string')
+    .filter((rule) => {
+      if (toRemove.has(rule)) {
+        removed.push(rule)
+        return false
+      }
+      if (rule.startsWith('github:')) kept.push(rule)
+      return true
+    })
+
+  if (removed.length === 0) return { removed: [], kept }
+
+  member.match = next
+  roles.member = member
+  config.roles = roles
+  return { removed, kept }
+}
+
+function buildDetail(kind: ChannelKind, channelConfig: unknown, secretsBlock: unknown): { detail?: string } {
+  if (kind === 'github') {
+    const repos = isObjectRecord(channelConfig) && Array.isArray(channelConfig.repos) ? channelConfig.repos.length : 0
+    return { detail: `${repos} repo${repos === 1 ? '' : 's'}` }
+  }
+  if (kind === 'line' || kind === 'kakaotalk') {
+    if (!isObjectRecord(secretsBlock)) return {}
+    const accounts = isObjectRecord(secretsBlock.accounts) ? Object.keys(secretsBlock.accounts).length : 0
+    const current = typeof secretsBlock.currentAccount === 'string' ? secretsBlock.currentAccount : undefined
+    const accountLabel = `${accounts} account${accounts === 1 ? '' : 's'}`
+    return { detail: current !== undefined ? `${accountLabel} (active: ${current})` : accountLabel }
+  }
+  return {}
+}
+
+function readEnabled(channelConfig: unknown): boolean {
+  if (isObjectRecord(channelConfig) && typeof channelConfig.enabled === 'boolean') return channelConfig.enabled
+  return true
+}
+
+function readConfigRecord(cwd: string): { ok: true; value: Record<string, unknown> } | { ok: false; reason: string } {
+  try {
+    const raw = readFileSync(join(cwd, CONFIG_FILE), 'utf8')
+    const parsed = JSON.parse(raw) as unknown
+    if (!isObjectRecord(parsed)) return { ok: false, reason: `${CONFIG_FILE} must contain a JSON object.` }
+    return { ok: true, value: parsed }
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+      return { ok: false, reason: `${CONFIG_FILE} not found at ${cwd}. Run \`typeclaw init\` first.` }
+    }
+    return { ok: false, reason: `Failed to read ${CONFIG_FILE}: ${(error as Error).message}` }
+  }
+}
+
+function readConfigRecordOrEmpty(cwd: string): Record<string, unknown> {
+  const result = readConfigRecord(cwd)
+  return result.ok ? result.value : {}
+}
+
+type ChannelSecretsRead =
+  | { kind: 'ok'; channels: Record<string, unknown> }
+  | { kind: 'missing' }
+  | { kind: 'unreadable'; reason: string }
+
+function readChannelSecrets(cwd: string): ChannelSecretsRead {
+  try {
+    const channels = new SecretsBackend(join(cwd, SECRETS_FILE)).tryReadChannelsSync()
+    if (channels === null) return { kind: 'missing' }
+    return { kind: 'ok', channels: channels as Record<string, unknown> }
+  } catch (error) {
+    return { kind: 'unreadable', reason: error instanceof Error ? error.message : String(error) }
+  }
+}
+
+function channelSecretsOrEmpty(read: ChannelSecretsRead): Record<string, unknown> {
+  return read.kind === 'ok' ? read.channels : {}
+}
+
+function writeConfig(
+  cwd: string,
+  record: Record<string, unknown>,
+  commitMessage: string,
+): { ok: true } | { ok: false; reason: string } {
+  try {
+    writeFileSync(join(cwd, CONFIG_FILE), `${JSON.stringify(record, null, 2)}\n`)
+  } catch (error) {
+    return { ok: false, reason: `Failed to write ${CONFIG_FILE}: ${(error as Error).message}` }
+  }
+  commitSystemFileSync(cwd, CONFIG_FILE, commitMessage)
+  return { ok: true }
+}
+
+function isObjectRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}

package/src/container/start.ts

@@ -21,6 +21,7 @@ import { buildDockerfile, DOCKERFILE } from '@/init/dockerfile'
 import { ensureDepsInstalled, type EnsureDepsResult } from '@/init/ensure-deps'
 import { buildGitignore, GITIGNORE_FILE } from '@/init/gitignore'
 import { refreshPackageJson } from '@/init/packagejson'
+import { reconcilePluginDeps } from '@/init/reconcile-plugin-deps'
 import { runBunUpdate, type UpdateRunner } from '@/init/run-bun-install'
 import { hostLocaleIsCjk } from '@/shared/host-locale'
 
@@ -247,7 +248,29 @@ export async function start({
     // subsequent installs (PR #243 dogfooding wasted three rebuilds + a
     // manual version bump before this gate existed). Registry-spec users
     // skip the force path because their install is already cache-correct.
-    const forceDepsReinstall = forceBuild && (await hasLocallyLinkedTypeclawDep(cwd))
+
+    // Materialize typeclaw.json#plugins into package.json BEFORE ensureDeps so
+    // the drift detector below sees the newly-written deps as missing and
+    // installs them in the same pass. This makes the plugin list a single
+    // source of truth: the user edits typeclaw.json and never touches
+    // package.json. The agent cannot abuse this to install arbitrary host code —
+    // the security plugin's `pluginAddition` guard gates writes to the plugins
+    // field at owner/trusted trust, so by the time this host-side step runs the
+    // field is trustworthy by construction.
+    const pluginReconcile = await reconcilePluginDeps({
+      cwd,
+      plugins: (await loadTypeclawConfig(cwd)).plugins,
+    }).catch((error: unknown) => ({ error: error instanceof Error ? error.message : String(error) }) as const)
+    if ('error' in pluginReconcile) {
+      return { ok: false, reason: `plugin dependency reconcile failed: ${pluginReconcile.error}` }
+    }
+
+    // Force install when reconcile rewrote package.json. ensureDeps' drift
+    // detector only checks for MISSING dependency names, so a managed plugin's
+    // version bump (dir already present) or a removal (stale dir left behind)
+    // would otherwise leave bun.lock/node_modules out of sync with the
+    // reconciled package.json.
+    const forceDepsReinstall = (forceBuild && (await hasLocallyLinkedTypeclawDep(cwd))) || pluginReconcile.changed
     const deps = await ensureDeps(cwd, { force: forceDepsReinstall })
     if (!deps.ok) {
       return { ok: false, reason: `dependency install failed: ${deps.reason}` }

package/src/init/reconcile-plugin-deps.ts

@@ -0,0 +1,173 @@
+import { existsSync } from 'node:fs'
+import { readFile, writeFile } from 'node:fs/promises'
+import { isAbsolute, join } from 'node:path'
+
+import { splitPluginEntrySpec } from '@/plugin'
+
+const PACKAGE_FILE = 'package.json'
+
+export type ReconcilePluginDepsResult = {
+  changed: boolean
+  files: string[]
+}
+
+export type ResolveLatestVersion = (packageName: string) => Promise<string>
+
+export type ReconcilePluginDepsOptions = {
+  cwd: string
+  plugins: readonly string[]
+  resolveLatest?: ResolveLatestVersion
+}
+
+// Materializes typeclaw.json#plugins into package.json#dependencies so the
+// plugin list is the single source of truth: the user edits typeclaw.json and
+// `start` keeps package.json in sync. The sync is one-way (config → manifest)
+// and bidirectional in effect (entries added to config are written; entries
+// removed from config are pruned). Provenance lives in
+// package.json#typeclaw.managedPlugins so pruning only ever touches deps this
+// step added — never the user's own dependencies or the typeclaw runtime dep.
+export async function reconcilePluginDeps(options: ReconcilePluginDepsOptions): Promise<ReconcilePluginDepsResult> {
+  const { cwd, plugins } = options
+  const resolveLatest = options.resolveLatest ?? resolveLatestFromRegistry
+
+  const pkgPath = join(cwd, PACKAGE_FILE)
+  if (!existsSync(pkgPath)) return { changed: false, files: [] }
+
+  let raw: string
+  try {
+    raw = await readFile(pkgPath, 'utf8')
+  } catch {
+    return { changed: false, files: [] }
+  }
+
+  let pkg: PackageJsonShape
+  try {
+    const parsed = JSON.parse(raw) as unknown
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) return { changed: false, files: [] }
+    pkg = parsed as PackageJsonShape
+  } catch {
+    return { changed: false, files: [] }
+  }
+
+  const dependencies = { ...pkg.dependencies }
+  const previousManaged = readManagedPlugins(pkg)
+  const desired = await resolveDesiredManaged(plugins, previousManaged, resolveLatest)
+
+  let changed = false
+
+  for (const [name, version] of Object.entries(desired)) {
+    if (dependencies[name] !== version) {
+      dependencies[name] = version
+      changed = true
+    }
+  }
+
+  // Prune scoped strictly to the prior managed set: a dep the user hand-added
+  // or a runtime dep is never removed even if its name shape looks plugin-like.
+  for (const name of Object.keys(previousManaged)) {
+    if (!(name in desired) && name in dependencies) {
+      delete dependencies[name]
+      changed = true
+    }
+  }
+
+  if (!managedEqual(previousManaged, desired)) changed = true
+
+  if (!changed) return { changed: false, files: [] }
+
+  const next = withManagedPlugins({ ...pkg, dependencies: sortKeys(dependencies) }, desired)
+  await writeFile(pkgPath, `${JSON.stringify(next, null, 2)}\n`)
+  return { changed: true, files: [PACKAGE_FILE] }
+}
+
+type PackageJsonShape = {
+  dependencies?: Record<string, string>
+  typeclaw?: { managedPlugins?: Record<string, string> } & Record<string, unknown>
+} & Record<string, unknown>
+
+// Classifies config.plugins entries and resolves the version each managed dep
+// should pin to. Local paths are skipped (not npm packages). A bare name (no
+// `@version`) is pinned ONCE: it reuses the version already pinned in the
+// managed set on subsequent starts, and only resolves `latest` for a genuinely
+// new, unmanaged plugin. Without this reuse, an unchanged `typeclaw.json` would
+// re-resolve `latest` on every start and silently rewrite package.json when the
+// registry moves — bypassing the pluginAddition security gate, which only fires
+// on a guarded config write.
+async function resolveDesiredManaged(
+  plugins: readonly string[],
+  previousManaged: Record<string, string>,
+  resolveLatest: ResolveLatestVersion,
+): Promise<Record<string, string>> {
+  const desired: Record<string, string> = {}
+  for (const entry of plugins) {
+    if (isLocalEntry(entry)) continue
+    const { name, versionSpec } = splitPluginEntrySpec(entry)
+    if (name.length === 0) continue
+    if (versionSpec !== undefined) {
+      desired[name] = versionSpec
+    } else {
+      desired[name] = previousManaged[name] ?? (await resolveLatest(name))
+    }
+  }
+  return sortKeys(desired)
+}
+
+function isLocalEntry(entry: string): boolean {
+  return entry.startsWith('./') || entry.startsWith('../') || isAbsolute(entry)
+}
+
+function readManagedPlugins(pkg: PackageJsonShape): Record<string, string> {
+  const managed = pkg.typeclaw?.managedPlugins
+  if (managed === undefined || managed === null || typeof managed !== 'object') return {}
+  const out: Record<string, string> = {}
+  for (const [name, version] of Object.entries(managed)) {
+    if (typeof version === 'string') out[name] = version
+  }
+  return out
+}
+
+function withManagedPlugins(pkg: PackageJsonShape, managed: Record<string, string>): PackageJsonShape {
+  const typeclaw = { ...pkg.typeclaw }
+  if (Object.keys(managed).length === 0) {
+    delete typeclaw.managedPlugins
+  } else {
+    typeclaw.managedPlugins = managed
+  }
+  if (Object.keys(typeclaw).length === 0) {
+    const { typeclaw: _omit, ...rest } = pkg
+    return rest as PackageJsonShape
+  }
+  return { ...pkg, typeclaw }
+}
+
+function managedEqual(a: Record<string, string>, b: Record<string, string>): boolean {
+  const ak = Object.keys(a)
+  const bk = Object.keys(b)
+  if (ak.length !== bk.length) return false
+  for (const k of ak) if (a[k] !== b[k]) return false
+  return true
+}
+
+function sortKeys(obj: Record<string, string>): Record<string, string> {
+  const out: Record<string, string> = {}
+  for (const k of Object.keys(obj).sort()) out[k] = obj[k] as string
+  return out
+}
+
+async function resolveLatestFromRegistry(packageName: string): Promise<string> {
+  const bun = (globalThis as { Bun?: { spawn: typeof Bun.spawn } }).Bun
+  if (!bun) throw new Error(`cannot resolve latest version for ${packageName}: bun runtime not available`)
+  const proc = bun.spawn({
+    cmd: ['bun', 'pm', 'view', packageName, 'version'],
+    stdout: 'pipe',
+    stderr: 'pipe',
+  })
+  const code = await proc.exited
+  if (code !== 0) {
+    const stderr = await new Response(proc.stderr).text()
+    throw new Error(`failed to resolve latest version for ${packageName}: ${stderr.trim() || `exit ${code}`}`)
+  }
+  const version = (await new Response(proc.stdout).text()).trim().replace(/^["']|["']$/g, '')
+  if (version.length === 0) throw new Error(`registry returned no version for ${packageName}`)
+  return version
+}

package/src/inspect/index.ts

@@ -1,7 +1,7 @@
 import { join } from 'node:path'
 
 import { originLabel, shortSessionId } from './label'
-import { renderEvent } from './render'
+import { renderEvent, TimeGate } from './render'
 import { replayJsonl } from './replay'
 import type { SessionSummary } from './session-list'
 import { isSessionIdShape, listSessions, resolveSession } from './session-list'
@@ -23,6 +23,7 @@ export type {
   RunInspectLoopOptions,
   RunViewerLoopOptions,
   SelectItem,
+  SelectOutcome,
   TailController,
 } from './loop'
 export type { ViewerItem } from './item'
@@ -283,9 +284,10 @@ async function streamSession(opts: {
 }): Promise<{ escToPicker: boolean }> {
   if (!opts.json) writeHeader(opts.summary, opts.color, opts.stdout)
 
+  const timeGate = new TimeGate()
   const onEvent = (event: InspectEvent): void => {
     if (opts.json) opts.stdout(JSON.stringify({ sessionId: opts.summary.sessionId, ...event }))
-    else opts.stdout(renderEvent(event, { color: opts.color }))
+    else opts.stdout(renderEvent(event, { color: opts.color, showTime: timeGate.shouldShow(event.cat) }))
   }
 
   const emitHint = (): void => {
@@ -309,6 +311,7 @@ async function streamSession(opts: {
       printFooter()
       emitHint()
     } else if (p.phase === 'live-start') {
+      timeGate.reset()
       opts.stdout(
         divider(opts.color, p.sessionLive ? '─── live ───' : '─── live (session not in registry; broadcasts only) ───'),
       )

package/src/inspect/loop.ts

@@ -10,7 +10,15 @@ export type OpenItemContext = {
   createTailScope: () => TailController
 }
 
-export type SelectItem<TItem> = (items: TItem[], opts: { initialKey?: string }) => Promise<TItem | null>
+// `refresh` (the `r` key) re-lists and re-renders the picker without opening
+// anything; `highlightKey` is the row highlighted when `r` was pressed, so the
+// selection survives the refresh.
+export type SelectOutcome<TItem> =
+  | { kind: 'picked'; item: TItem }
+  | { kind: 'cancelled' }
+  | { kind: 'refresh'; highlightKey?: string }
+
+export type SelectItem<TItem> = (items: TItem[], opts: { initialKey?: string }) => Promise<SelectOutcome<TItem>>
 
 export type OpenItemResult = {
   result: RunInspectResult
@@ -46,8 +54,12 @@ export type RunViewerLoopOptions<TItem> = {
 // inside `openItem` AFTER the picker resolves and disposed before the picker
 // re-opens, so clack always owns a clean cooked-mode stdin.
 export async function runViewerLoop<TItem>(opts: RunViewerLoopOptions<TItem>): Promise<RunInspectResult> {
+  // `preselectKey` auto-opens a row once (the `inspect <id>` arg). `highlightKey`
+  // only seeds the picker's initial highlight (esc-return + `r` refresh) and
+  // never bypasses the picker — keeping the two apart is what lets refresh
+  // re-render the list instead of re-opening the last viewer.
   let preselectKey = opts.preselectKey
-  let lastPickedKey: string | undefined
+  let highlightKey: string | undefined
   // Writable is only safe on the very first list. Returning to the picker means
   // a viewer was just opened and left — any writable session it might represent
   // is gone (detach ends the live session), so subsequent refreshes are
@@ -58,16 +70,21 @@ export async function runViewerLoop<TItem>(opts: RunViewerLoopOptions<TItem>): P
     const items = await opts.listItems({ allowWritable })
     if (items.length === 0) return opts.onEmpty()
 
-    let chosen: TItem | null
+    let chosen: TItem
     if (preselectKey !== undefined) {
-      chosen = items.find((i) => opts.keyOf(i) === preselectKey) ?? null
+      const match = items.find((i) => opts.keyOf(i) === preselectKey) ?? null
       preselectKey = undefined
-      if (chosen === null) return opts.onEmpty()
+      if (match === null) return opts.onEmpty()
+      chosen = match
     } else {
-      const hint = lastPickedKey
-      chosen = await opts.selectItem(items, hint !== undefined ? { initialKey: hint } : {})
-      if (chosen === null) return { ok: false, exitCode: 130, reason: 'cancelled' }
-      lastPickedKey = opts.keyOf(chosen)
+      const outcome = await opts.selectItem(items, highlightKey !== undefined ? { initialKey: highlightKey } : {})
+      if (outcome.kind === 'cancelled') return { ok: false, exitCode: 130, reason: 'cancelled' }
+      if (outcome.kind === 'refresh') {
+        if (outcome.highlightKey !== undefined) highlightKey = outcome.highlightKey
+        continue
+      }
+      chosen = outcome.item
+      highlightKey = opts.keyOf(chosen)
     }
 
     const opened = await opts.openItem(chosen, { createTailScope: opts.createTailScope })

package/src/inspect/render.ts

@@ -6,15 +6,42 @@ import type { InspectEvent } from './types'
 export type RenderOptions = {
   color: boolean
   maxTextLength?: number
+  // When false, the timestamp column is blanked (kept the same width so the tag
+  // column stays aligned). The line view passes this from a TimeGate so a run of
+  // same-category events shows the timestamp only on its first line.
+  showTime?: boolean
 }
 
+const TIME_WIDTH = '--:--:--'.length
+
 export function renderEvent(event: InspectEvent, opts: RenderOptions): string {
-  const time = renderTime(event.ts, opts)
+  const time = opts.showTime === false ? ' '.repeat(TIME_WIDTH) : renderTime(event.ts, opts)
   const tag = renderTag(event, opts)
   const body = renderBody(event, opts)
   return `${time}  ${tag}  ${body}`
 }
 
+// Decides whether an event's timestamp should be shown, given the running render
+// position: a timestamp prints only when the event's category differs from the
+// previous one, so a run of same-category events (e.g. back-to-back thinking
+// blocks or a tool start/end pair) carries a single timestamp at its start.
+export class TimeGate {
+  private prevCat: InspectEvent['cat'] | null = null
+
+  shouldShow(cat: InspectEvent['cat']): boolean {
+    const show = cat !== this.prevCat
+    this.prevCat = cat
+    return show
+  }
+
+  // Clear the running category so the next event always shows its timestamp.
+  // Called at a visible section boundary (the live divider) so the first live
+  // row is stamped even when it shares the last replayed event's category.
+  reset(): void {
+    this.prevCat = null
+  }
+}
+
 const DEFAULT_MAX_TEXT = 200
 
 function renderTime(ts: number, opts: RenderOptions): string {