@cmodjs/core 4.0.3 → 4.1.1

package/src/runtime/lifecycle.ts

@@ -1,9 +1,9 @@
-import type { Args, ClassicHookInputs, EventResult, Frozen, HookBudget, HookFailure, PluginOptions, RenderElement, Timer } from 'claude-code'
+import type { Args, Caught, ClassicHookInputs, EventResult, Frozen, HookBudget, PluginOptions, RenderElement, Timer } from 'claude-code'
 import type { Step } from '../installer.js'
 
 import type { Allowed, Imports, Mod, ModDefinition, Reservation, SettingsFile, SettingsFileChange, SettingsFileChangeListener, Subscription, Timer as ModTimer } from '../mod.js'
 import type { Options, OptionValues } from '../options.js'
-import { consentPath, dataFolder, finishStepsMethod, grantFix, coreVersion, isAtLeast, marketplaceOf, parseConsent, pendingStepsMethod, parseEvent, permissionWords, readRecord, readSteps, recordPath, scriptsSha256, storeFolder, updatesToTurnOn, type ReadFile, type RunnerEvent, type Steps } from '../records.js'
+import { consentPath, dataFolder, finishStepsMethod, grantFix, coreVersion, isAtLeast, isProgramNewer, marketplaceOf, parseConsent, pendingStepsMethod, parseEvent, permissionWords, programPath, readRecord, readSteps, recordPath, scriptsSha256, storeFolder, updatesToTurnOn, type ReadFile, type RunnerEvent, type Steps } from '../records.js'
 import { homePrefix, ifMissing, relativePath } from '../utils/paths.js'
 import { firstLine, formatExit, messageOf } from '../utils/text.js'
 import type { Claude } from './claude.js'
@@ -15,14 +15,14 @@ import { answerCall, answeringOwnCalls, cmodPluginName, dependencyCalls, withBar
 import { keepEngine } from './engine.js'
 import { classicFailure, classicHook, userSkillHook, type Hook, type HookFields, type HookListener, type RoutedEvent } from './hooks.js'
 import type { PermissionRoutes } from './permission-check.js'
-import { checkedAnswer, checkingGrants, checkSettings, checksAnswers, checkWrite, isCovered, itemOf, passedDown, programAddresses, type AnswerCheck, type Grants } from './grants.js'
-import { cmodError, locatingPrograms, readLines, type Programs } from './programs.js'
+import { checkedAnswer, checkingGrants, checkRun, checkSettings, checksAnswers, checkWrite, isCovered, itemOf, passedDown, programAddresses, type AnswerCheck, type Grants } from './grants.js'
+import { cmodError, locatingPrograms, readLines, spawnCmod, type Programs } from './programs.js'
 import { createModFiles, resolvedPath, type Places } from './metadata.js'
 import { fitsOption } from '../options.js'
 import { createInstaller } from './installer.js'
 import { createOptions, MissingOptions } from './options.js'
 import { createRouter, type Router, type RouterNext } from './router.js'
-import { conversationMethods, createSessionsClient, type SessionsClient } from './sessions.js'
+import { conversationMethods, createSessionsClient, type SessionColor, type SessionsClient } from './sessions.js'
 import type { SessionChange, TurnData } from '../session/conversation.js'
 import type { BeforeEvent } from '../session/session.js'
 import { matches } from '../utils/matcher.js'
@@ -31,9 +31,9 @@ import { createToaster, type Failure, type ShownToast, type Toaster } from './to
 import { toolCalls } from './tool-calls.js'
 import { createHotkeys } from './hotkeys.js'
 import { servePages, type Pages } from './pages.js'
-import { drawnParts } from './parts.js'
+import { drawnParts, type DrawnParts } from './parts.js'
 import { createWatches } from './watches.js'
-import { createUi, partMethods, type PartDraw, type PartsUpdate, type SettingsTab, type UiArea } from './ui.js'
+import { createUi, partMethods, type BorrowedMarkdown, type PartDraw, type PartPress, type PartsUpdate, type SettingsTab, type ShownPages, type UiArea } from './ui.js'
 import { serveWidgets } from './widgets.js'
 import { Progress } from '../ui/components.js'
 import { Box, Text } from '../ui/elements.js'
@@ -58,7 +58,7 @@ export type Lifecycle<State extends object> = {
   readonly toasts: readonly ShownToast[]
   start(claude: Claude, read: (claude: Claude) => Promise<Plugin>): Promise<void>
   route<N extends RoutedEvent>(event: N, e: Frozen<Args<N>>, next: RouterNext<N>): Promise<EventResult<N>>
-  caught<N extends RoutedEvent>(event: N, e: Frozen<Args<N>>, next: RouterNext<N>, failure: HookFailure): Promise<EventResult<N>>
+  caught<N extends RoutedEvent>(event: N, e: Frozen<Args<N>>, next: RouterNext<N>, failure: Caught): Promise<EventResult<N>>
   raise(method: string, payload: Readonly<Record<string, unknown>>): Promise<unknown>
 }
 
@@ -73,6 +73,7 @@ type ModRuntime = {
   readonly refreshGrants: () => Promise<void>
   readonly permissionRoutes: () => PermissionRoutes | undefined
   readonly options: PluginOptions
+  readonly nextDraw: () => number
 }
 
 type ActiveMod<State extends object, Declared extends Options> = {
@@ -97,6 +98,10 @@ const installRetrySeconds = [2, 4, 8, 16, 32, 64, 128] as const
 
 const cmodCheckMs = 1000
 
+const recordCheckMs = 1000
+
+const drawsPerMs = 1000
+
 const cmodWaitMs = 60_000
 
 const cmodSlowCheckMs = 10_000
@@ -135,7 +140,8 @@ export async function readPlugin(claude: Claude): Promise<Plugin> {
   })
   if (version === undefined || record?.scriptsSha256 !== scripts) return { ...plugin, isInstalled: false, shouldRecord: false }
   const isInstalled = record.version === version || record.root === root
-  return { ...plugin, isInstalled, shouldRecord: isInstalled && record.version !== version }
+  const programModifiedMs = record.program === null ? undefined : (await claude.fs.stat(programPath(store, record.program, record.version)).catch(ifMissing(undefined)))?.mtimeMs
+  return { ...plugin, isInstalled, shouldRecord: isInstalled && (record.version !== version || isProgramNewer(record, programModifiedMs)) }
 }
 
 async function filesBelow(claude: Claude, folder: string): Promise<string[]> {
@@ -193,13 +199,20 @@ export function createLifecycle<State extends object, Declared extends Options =
   let raise: SessionsClient['raise'] | undefined
   let failure: unknown
   let pluginOptions = options
-  const installer = createInstaller(definition.name, () => claude(), {
-    show: (open) => {
-      if (phase !== 'active') runtime?.toaster.toast.dismiss(installId)
-      runtime?.toaster.toast.info('Installing', { id: askingId, description: 'Waiting for your answer', duration: Infinity, action: { label: 'Answer', onClick: open } })
+  let drawCount = 0
+  const nextDraw = () => (drawCount += 1)
+  const installer = createInstaller(
+    definition.name,
+    () => claude(),
+    {
+      show: (open) => {
+        if (phase !== 'active') runtime?.toaster.toast.dismiss(installId)
+        runtime?.toaster.toast.info('Installing', { id: askingId, description: 'Waiting for your answer', duration: Infinity, action: { label: 'Answer', onClick: open } })
+      },
+      hide: () => runtime?.toaster.toast.dismiss(askingId),
     },
-    hide: () => runtime?.toaster.toast.dismiss(askingId),
-  })
+    nextDraw,
+  )
   let shouldRecord = false
   let recording: Promise<void> | undefined
   let missedSessionStart: Frozen<Args<'classic.SessionStart'>> | undefined
@@ -221,6 +234,7 @@ export function createLifecycle<State extends object, Declared extends Options =
     failure ??= new Error(`${definition.name}: ${reason}${/[.!?]$/.test(reason) ? '' : '.'}${fix === undefined ? '' : ` ${fix}`}`, { cause: error })
     const again = retry === undefined ? {} : { retry: () => ((failure = undefined), stopRetrying(), retry().catch(report)) }
     toastFailure({ id: installId, message: reason, ...(fix === undefined ? {} : { description: fix }), ...(error === undefined ? {} : { error }), ...again })
+    watchRecord()
   }
 
   let consented: string | undefined
@@ -332,27 +346,31 @@ export function createLifecycle<State extends object, Declared extends Options =
 
   const runSteps = async (active: Mod<State>) => {
     const steps = asksPerson ? (definition.installer ?? []) : []
-    for (const [index, step] of steps.entries()) {
-      if (await isStepDone(active, step)) continue
-      const isAnswered = (await claude().session.surfaces()).length > 0 && (await installer.step(active, step, index + 1, steps.length))
-      if (!isAnswered) {
-        runtime?.toaster.toast.warning(steps.length - index === 1 ? 'Needs one more step' : `Needs ${steps.length - index} more steps`, {
-          id: 'cmod:steps',
-          description: `Starting with ${step.title}.`,
-          duration: Infinity,
-          action: { label: 'Finish', onClick: () => runSteps(active) },
-        })
-        break
+    try {
+      for (const [index, step] of steps.entries()) {
+        if (await isStepDone(active, step)) continue
+        const isAnswered = (await claude().session.surfaces()).length > 0 && (await installer.step(active, step, index + 1, steps.length))
+        if (!isAnswered) {
+          runtime?.toaster.toast.warning(steps.length - index === 1 ? 'Needs one more step' : `Needs ${steps.length - index} more steps`, {
+            id: 'cmod:steps',
+            description: `Starting with ${step.title}.`,
+            duration: Infinity,
+            action: { label: 'Finish', onClick: () => runSteps(active) },
+          })
+          break
+        }
       }
+    } finally {
+      await installer.close()
     }
-    await installer.close()
   }
 
   const activate = async (): Promise<void> => {
     if (runtime === undefined || plugin === undefined) return
     const activeRouter = createRouter()
-    const active = await createMod(definition, { ...runtime, router: activeRouter, dataFolder: dataFolder(plugin.store, plugin.name), store: plugin.store, steps: plugin.steps, granted, refreshGrants, permissionRoutes, options: pluginOptions }).catch(async (error: unknown) => {
+    const active = await createMod(definition, { ...runtime, router: activeRouter, dataFolder: dataFolder(plugin.store, plugin.name), store: plugin.store, steps: plugin.steps, granted, refreshGrants, permissionRoutes, options: pluginOptions, nextDraw }).catch(async (error: unknown) => {
       if (error instanceof MissingOptions && (await askOptions(error))) return undefined
+      await installer.close()
       fail(messageOf(error), error instanceof MissingOptions ? `Retry asks for ${error.keys.length === 1 ? 'it' : 'them'}.` : undefined, begin, error)
       throw error
     })
@@ -363,7 +381,9 @@ export function createLifecycle<State extends object, Declared extends Options =
     raise = active.raise
     router = activeRouter
     phase = 'active'
+    stopWatchingRecord()
     runtime.claude.ui.invalidate('ui.render')
+    if (definition.name === cmodPluginName) runtime.claude.ui.invalidate('command.describe')
     void runSteps(active.mod).catch((error: unknown) => toastFailure({ id: 'cmod:steps', message: 'Its installer stopped', error }))
     const missed = missedSessionStart
     missedSessionStart = undefined
@@ -418,9 +438,14 @@ export function createLifecycle<State extends object, Declared extends Options =
       toastFailure({ id: 'cmod:updates', message: 'Could not read whether its marketplace updates automatically', error })
       return undefined
     })
-    const isAccepted = await installer.consent({ ...event, updates })
+    const installedElsewhere = new Promise<'installed'>((resolve) => (settleAsked = () => resolve('installed')))
+    watchRecord()
+    const answer = await Promise.race([installer.consent({ ...event, program: plugin?.steps.program ?? '', updates }), installedElsewhere]).finally(() => {
+      settleAsked = undefined
+    })
     await installer.close()
-    if (isAccepted) {
+    if (answer === 'installed') return startInstalled()
+    if (answer) {
       consented = event.sha256
       return install(consented)
     }
@@ -544,20 +569,45 @@ export function createLifecycle<State extends object, Declared extends Options =
   }
   let recordMs = 0
   let readStarted: ((claude: Claude) => Promise<Plugin>) | undefined
-  const recover = async (): Promise<boolean> => {
-    if (plugin === undefined || readStarted === undefined || (phase !== 'failed' && phase !== 'declined')) return false
+  const isNewlyInstalled = async (): Promise<boolean> => {
+    if (plugin === undefined || readStarted === undefined) return false
     const modifiedMs = await stampOf(recordPath(plugin.store, plugin.name))
     if (modifiedMs === recordMs) return false
     recordMs = modifiedMs
     const current = await readStarted(claude())
     if (!current.isInstalled) return false
     plugin = current
+    return true
+  }
+  const startInstalled = async () => {
     failure = undefined
     activation = undefined
     await refreshGrants()
     await finish()
+  }
+  let settleAsked: (() => void) | undefined
+  const recover = async (): Promise<boolean> => {
+    if ((settleAsked === undefined && phase !== 'failed' && phase !== 'declined') || !(await isNewlyInstalled())) return false
+    if (settleAsked === undefined) await startInstalled()
+    else settleAsked()
     return true
   }
+  let recordCheck: Timer | undefined
+  let checking: Promise<void> | undefined
+  const watchRecord = () => {
+    recordCheck ??= claude().clock.every(recordCheckMs, () => {
+      checking ??= recover()
+        .then(() => undefined)
+        .catch((error: unknown) => claude().ui.log(`${definition.name} could not read whether another cmod installed it: ${messageOf(error)}`, { to: 'debug' }))
+        .finally(() => {
+          checking = undefined
+        })
+    })
+  }
+  const stopWatchingRecord = () => {
+    recordCheck?.cancel()
+    recordCheck = undefined
+  }
 
   const refreshGrants = async () => {
     if (plugin === undefined || plugin.name === cmodPluginName) return
@@ -639,6 +689,7 @@ export function createLifecycle<State extends object, Declared extends Options =
       runtime = { claude: programs.claude, toaster: createToaster(claudeCalls, definition.name, () => plugin?.version, () => openSettings('permissions')) }
       readStarted = read
       try {
+        drawCount = (await claudeCalls.clock.now()) * drawsPerMs
         await programs.refresh()
         await begin().catch(report)
       } finally {
@@ -647,8 +698,13 @@ export function createLifecycle<State extends object, Declared extends Options =
     },
     async route<N extends RoutedEvent>(event: N, e: Frozen<Args<N>>, next: RouterNext<N>): Promise<EventResult<N>> {
       if (imports !== undefined) bind(imports)
-      if (event === 'ui.render' && installer.draws(e as Frozen<Args<'ui.render'>>)) return installer.draw(e as Frozen<Args<'ui.render'>>) as EventResult<N>
-      if (event === 'ui.close') installer.closed((e as Frozen<Args<'ui.close'>>).id)
+      const asked = e as Frozen<Args<'cmod.call'>> & { readonly caller?: string }
+      if (event === 'cmod.call' && asked.to === definition.name && asked.caller === cmodPluginName) {
+        if (asked.method === partMethods.shown) installer.hear(asked.input as ShownPages)
+        const answered = installer.answer(asked.method, asked.input)
+        if (answered !== undefined) return (await answered.catch((error: unknown) => ({ deny: `${definition.name}: ${messageOf(error)}` }))) as EventResult<N>
+        if (asked.method === partMethods.shown && phase !== 'active') return { value: null } as EventResult<N>
+      }
       if (event === 'classic.SessionStart') {
         missedSessionStart = undefined
         hasHeardSessionStart = true
@@ -659,9 +715,10 @@ export function createLifecycle<State extends object, Declared extends Options =
       }
       if (shouldRecord && event === 'classic.UserPromptSubmit') record()
       if (event === 'classic.UserPromptSubmit' || event === 'classic.SessionStart') await recover().catch((error: unknown) => claude().ui.log(`${definition.name} stays stopped: ${messageOf(error)}`, { to: 'debug' }))
-      const isCallToThisMod = event === 'cmod.call' && (e as Frozen<Args<'cmod.call'>>).to === definition.name
+      const tool = (e as { readonly tool?: unknown }).tool
+      const isCallToThisMod = (event === 'cmod.call' && (e as Frozen<Args<'cmod.call'>>).to === definition.name) || (event === 'tool.call' && typeof tool === 'string' && tool.startsWith(`mcp__${definition.name}__`))
       if (event === 'cmod.call' && !isCallToThisMod) return next(e)
-      await (event === 'classic.SessionStart' || isCallToThisMod ? holdUntilStarted() : whenActive())
+      await (event === 'classic.SessionStart' || event === 'session.append' || isCallToThisMod ? holdUntilStarted() : whenActive())
       if (event === 'classic.SessionStart' && phase !== 'active') {
         missedSessionStart = e as Frozen<Args<'classic.SessionStart'>>
         return next(e)
@@ -673,7 +730,11 @@ export function createLifecycle<State extends object, Declared extends Options =
       const call = e as Frozen<Args<'cmod.call'>>
       if (event === 'cmod.call' && call.to === definition.name && mod !== undefined) {
         if (call.method === pendingStepsMethod) return { value: await pendingSteps(mod) } as EventResult<N>
-        if (call.method === finishStepsMethod) return (await runSteps(mod), { value: null }) as EventResult<N>
+        if (call.method === finishStepsMethod) {
+          const active = mod
+          const opened = await installer.collect(() => Promise.race([runSteps(active).catch((error: unknown) => void toastFailure({ id: 'cmod:steps', message: 'Could not finish the setup', error })), installer.shown()]))
+          return { value: opened } as EventResult<N>
+        }
       }
       if (event === 'classic.UserPromptSubmit' || event === 'classic.SessionStart') await refreshGrants().catch((error: unknown) => claude().ui.log(`${definition.name} keeps its grants from before: ${messageOf(error)}`, { to: 'debug' }))
       if (event === 'classic.UserPromptSubmit' && phase === 'active' && !hasHeardSessionStart) {
@@ -686,14 +747,15 @@ export function createLifecycle<State extends object, Declared extends Options =
       if (event !== 'ui.render' || render.component !== 'AbovePrompt' || runtime === undefined) return answer
       return runtime.toaster.draw((await answer) as EventResult<'ui.render'>, runtime.claude.ui.resolve(render), render.props, render.requestId) as EventResult<N>
     },
-    async caught<N extends RoutedEvent>(event: N, e: Frozen<Args<N>>, next: RouterNext<N>, { kind, message }: HookFailure): Promise<EventResult<N>> {
+    async caught<N extends RoutedEvent>(event: N, e: Frozen<Args<N>>, next: RouterNext<N>, { error: { kind, message }, called }: Caught): Promise<EventResult<N>> {
       const call = e as Frozen<Args<'cmod.call'>>
       const isAsk = event === 'cmod.call' && call.to === definition.name && beforeAskOf(call) !== undefined
       const reasons: Readonly<Record<string, string>> = { timeout: `it ran past the ${hookMs / 1000} s Claude Code gives a hook`, throw: message ?? 'it threw' }
       const reason = reasons[kind]
       if (reason === undefined) return isAsk ? ({ value: null } as EventResult<N>) : next(e)
       const error = new Error(reason)
-      toastFailure({ id: `stopped:${event}`, message: `Claude Code stopped its ${event.replace(/^classic\./, '')} hook`, error })
+      const failedBeneath = called && kind === 'throw' ? await next(e).then(() => undefined, messageOf) : undefined
+      if (failedBeneath === undefined || failedBeneath !== message) toastFailure({ id: `stopped:${event}`, message: `Claude Code stopped its ${event.replace(/^classic\./, '')} hook`, error })
       return router.dispatchFailure(event, e, error, next)
     },
   }
@@ -737,7 +799,13 @@ async function createMod<State extends object, Declared extends Options>(definit
   let parentAsked: Promise<string | undefined> | undefined
   let hasEarlierPrompts = true
   let agentType: string | undefined
-  const area = createUi<State>({ name: definition.name, claude, router, report, announce, mod: () => mod })
+  let parts: DrawnParts | undefined
+  const borrowed: BorrowedMarkdown = (styler, cached, input) => {
+    const name = `The markdown style of ${styler}`
+    void parts?.fill(styler, cached, input, name)?.then(() => claude.ui.invalidate('ui.render'))
+    return parts?.element(styler, cached, `${styler}/markdown:`, name, `markdown:${styler}`)
+  }
+  const area = createUi<State>({ name: definition.name, claude, router, report, announce, mod: () => mod, borrowed, nextDraw: runtime.nextDraw })
   const askParent = async (): Promise<string | undefined> => {
     if (definition.name === cmodPluginName) return undefined
     try {
@@ -1003,9 +1071,23 @@ async function createMod<State extends object, Declared extends Options>(definit
   const conversations = definition.name === cmodPluginName ? serveConversations({ claude, router, store: runtime.store, project: () => modState.root, report: (id, message, error) => report({ id, message, error }), clear: (id) => toaster.toast.dismiss(id) }) : undefined
   let pages: Pages | undefined
   const reportPart = (id: string, message: string, error: unknown) => report({ id, message, error })
-  const parts = drawnParts({ claude, report: reportPart, press: (to, input) => pages?.press(to, input) })
-  const widgets = conversations === undefined ? undefined : serveWidgets({ claude, router, store: runtime.store, report: reportPart, turnClosedBy: (rowId) => conversations.turnClosedBy(rowId), parts })
-  pages = widgets === undefined ? undefined : servePages({ claude, router, report: reportPart, widgets, parts })
+  const pressElsewhere = (to: string, input: PartPress) =>
+    void claude.cmod.call({ to, method: partMethods.press, input }).catch((error: unknown) => {
+      parts?.forget(to)
+      claude.ui.invalidate('ui.render')
+      reportPart(`press:${to}`, `${to} did not take the press`, error)
+    })
+  parts = drawnParts({ claude, report: reportPart, press: (to, input) => (pages === undefined ? pressElsewhere(to, input) : pages.press(to, input)) })
+  const widgets = conversations === undefined ? undefined : serveWidgets({ claude, router, store: runtime.store, report: reportPart, turnClosedBy: (rowId) => conversations.turnClosedBy(rowId), parts, markdownIn: area.markdownIn })
+  pages = widgets === undefined ? undefined : servePages({ claude, router, report: reportPart, widgets, parts, tellStylers: area.restyled })
+  const tellColor = (to: string, told: SessionColor) => {
+    if (told.session === '' || to === cmodPluginName) return
+    claude.clock.after(0, () => void claude.cmod.call({ to, method: conversationMethods.sessionColor, input: told }).catch((error: unknown) => claude.ui.log(`cmod: ${to} did not hear the session's color: ${messageOf(error)}`, { to: 'debug' })))
+  }
+  conversations?.onColor((told) => {
+    client.recolor(told)
+    for (const { mod: to } of pages?.declared() ?? []) tellColor(to, told)
+  })
   router.add('cmod.call', async (e, next) => {
     if (e.to !== definition.name) return next(e)
     const call = e as typeof e & { readonly caller?: string }
@@ -1015,15 +1097,21 @@ async function createMod<State extends object, Declared extends Options>(definit
       client.changed(changedSession, change, isInProject !== false)
       return { value: null }
     }
+    if (e.method === conversationMethods.sessionColor && call.caller === cmodPluginName) {
+      client.recolor(e.input as SessionColor)
+      return { value: null }
+    }
     const ask = beforeAskOf(call)
     if (ask !== undefined) return { value: (await client.answerBefore(ask.session, ask.event, ask.change, ask.isInProject)) ?? null }
     if (e.method === partMethods.changed && call.caller !== undefined && pages !== undefined) {
-      return { value: { isHeld: pages.update(call.caller, e.input as PartsUpdate) } }
+      const update = e.input as PartsUpdate
+      if (update.parts !== undefined && conversations !== undefined) tellColor(call.caller, conversations.color())
+      return { value: { isHeld: pages.update(call.caller, update), stylers: pages.stylers() } }
     }
-    if (call.caller === cmodPluginName) {
+    if (call.caller !== undefined) {
       const turn = e.method === partMethods.draw ? (e.input as { readonly turn?: TurnData }).turn : undefined
-      const answered = area.answer(e.method, turn === undefined ? e.input : { ...(e.input as PartDraw), turn: client.turn(turn) })
-      if (answered !== undefined) return answered
+      const answered = area.answer(e.method, turn === undefined ? e.input : { ...(e.input as PartDraw), turn: client.turn(turn) }, call.caller)
+      if (answered !== undefined) return answered.catch((error: unknown) => ({ deny: `${definition.name}: ${messageOf(error)}` }))
     }
     const served = await conversations?.answer(call)
     return served ?? answerCall(definition.name, api, e)
@@ -1033,7 +1121,20 @@ async function createMod<State extends object, Declared extends Options>(definit
     return ask === undefined ? { deny: `${definition.name}: ${error.message}` } : { value: client.failedBefore(ask.session, ask.event, ask.change, ask.isInProject, error) ?? null }
   })
   const agents = toolCalls(claude, router)
-  keepEngine(mod, { claude: checked, router, toolCalls: agents, report, hasPermissionCheck: () => runtime.permissionRoutes() !== undefined, answerInput: area.answerInput, ...(widgets === undefined ? {} : { widgets }), ...(pages === undefined ? {} : { pages }) })
+  keepEngine(mod, {
+    claude: checked,
+    router,
+    toolCalls: agents,
+    report,
+    hasPermissionCheck: () => runtime.permissionRoutes() !== undefined,
+    answerInput: area.answerInput,
+    spawnCmod: async (args, program) => {
+      await checkRun(grants, 'process.spawn', program.argv)
+      return spawnCmod(claude, args, session, program.env)
+    },
+    ...(widgets === undefined ? {} : { widgets }),
+    ...(pages === undefined ? {} : { pages }),
+  })
   const names = new Set<string>()
   const reserveName = (type: string, name: string, taken: string): Reservation => {
     const key = `${type}:${name}`

package/src/runtime/pages.ts

@@ -1,10 +1,12 @@
 import type { RenderElement } from 'claude-code'
 import { isObject } from '../records.js'
+import { Text } from '../ui/elements.js'
 import { messageOf } from '../utils/text.js'
 import type { Claude } from './claude.js'
+import { cmodPluginName } from './dependencies.js'
 import type { DrawnParts } from './parts.js'
 import type { Router } from './router.js'
-import { partMethods, type PageDeclaration, type PageRequest, type PartPress, type PartsUpdate, type ShownPages } from './ui.js'
+import { partMethods, stalePress, type PageDeclaration, type PageRequest, type PartPress, type PartsUpdate, type ShownPages } from './ui.js'
 import type { Widgets } from './widgets.js'
 
 const askedWaitMs = 1000
@@ -15,6 +17,7 @@ export type PageApply = (mod: string, requests: readonly PageRequest[]) => Promi
 
 export type Pages = {
   declared(): readonly ModPages[]
+  stylers(): readonly string[]
   element(mod: string, page: string, params: unknown, columns: number, isFocused: boolean): RenderElement | undefined
   press(mod: string, press: PartPress): void
   update(mod: string, update: PartsUpdate): boolean
@@ -27,8 +30,23 @@ export function pagesOf(input: unknown): PageDeclaration[] {
   return listed.filter(isObject).flatMap((each) => (typeof each['id'] === 'string' && typeof each['title'] === 'string' && (each['place'] === 'sidebar' || each['place'] === 'settings') ? [{ id: each['id'], title: each['title'], place: each['place'] }] : []))
 }
 
-export function servePages({ claude, router, report, widgets, parts }: { readonly claude: Claude; readonly router: Router; readonly report: (id: string, message: string, error: unknown) => void; readonly widgets: Pick<Widgets, 'update'>; readonly parts: DrawnParts }): Pages {
+export function servePages({
+  claude,
+  router,
+  report,
+  widgets,
+  parts,
+  tellStylers,
+}: {
+  readonly claude: Claude
+  readonly router: Router
+  readonly report: (id: string, message: string, error: unknown) => void
+  readonly widgets: Pick<Widgets, 'update'>
+  readonly parts: DrawnParts
+  readonly tellStylers: (stylers: readonly string[]) => void
+}): Pages {
   const declared = new Map<string, readonly PageDeclaration[]>()
+  const stylers = new Set<string>()
   const asking = new Map<string, Promise<void>>()
   const pressing = new Set<Promise<void>>()
   let waiting: { readonly mod: string; readonly requests: readonly PageRequest[] }[] = []
@@ -44,16 +62,18 @@ export function servePages({ claude, router, report, widgets, parts }: { readonl
     for (const { mod, requests } of taken) await run(mod, requests)
   }
 
-  const settle = async () => {
-    while (pressing.size > 0) await Promise.allSettled(pressing)
+  const settle = async (earlier: ReadonlySet<Promise<void>>) => {
+    const own = () => [...pressing].filter((pending) => !earlier.has(pending))
+    for (let pending = own(); pending.length > 0; pending = own()) await Promise.allSettled(pending)
     await takeWaiting()
   }
 
   const wrapped = async <Answer>(next: () => Promise<Answer>): Promise<Answer> => {
     inputDepth += 1
+    const earlier = new Set(pressing)
     try {
       const answer = await next()
-      await settle()
+      await settle(earlier)
       return answer
     } finally {
       inputDepth -= 1
@@ -77,9 +97,22 @@ export function servePages({ claude, router, report, widgets, parts }: { readonl
     return pending
   }
 
+  const restyle = (mod: string, isStyler: boolean) => {
+    if (!isStyler && !stylers.delete(mod)) return
+    if (isStyler) stylers.add(mod)
+    parts.forget(mod)
+    const listed = [...stylers]
+    tellStylers(listed)
+    for (const told of declared.keys()) {
+      if (told !== cmodPluginName) void claude.cmod.call({ to: told, method: partMethods.stylers, input: listed }).catch((error: unknown) => claude.ui.log(`cmod: ${told} did not hear which mods style markdown: ${messageOf(error)}`, { to: 'debug' }))
+    }
+  }
+
   const update = (mod: string, { parts: listing, redraw, requests, isAsked }: PartsUpdate) => {
     if (listing !== undefined) declared.set(mod, pagesOf(listing))
-    if (listing !== undefined || redraw === true) widgets.update(mod, { ...(listing === undefined ? {} : { parts: listing }), ...(redraw === undefined ? {} : { redraw }) })
+    if (listing !== undefined) restyle(mod, isObject(listing) && listing['stylesMarkdown'] === true)
+    const isRedrawn = redraw === true || requests?.some((request) => 'open' in request) === true
+    if (listing !== undefined || isRedrawn) widgets.update(mod, { ...(listing === undefined ? {} : { parts: listing }), ...(isRedrawn ? { redraw: true } : {}) })
     if (requests === undefined || requests.length === 0) return false
     if (isAsked !== true) return (void run(mod, requests), false)
     waiting.push({ mod, requests })
@@ -96,7 +129,8 @@ export function servePages({ claude, router, report, widgets, parts }: { readonl
         (error: unknown) => {
           parts.forget(mod)
           claude.ui.invalidate('ui.render')
-          report(`press:${mod}`, `${mod} did not take the press`, error)
+          if (messageOf(error).includes(stalePress)) claude.ui.log(`cmod: ${mod} draws its page again, because the button pressed was from an older drawing:${messageOf(error)}`, { to: 'debug' })
+          else report(`press:${mod}`, `${mod} did not take the press`, error)
         },
       )
       .finally(() => pressing.delete(pending))
@@ -104,21 +138,31 @@ export function servePages({ claude, router, report, widgets, parts }: { readonl
     if (inputDepth === 0) void pending.then(takeWaiting)
   }
 
-  const cacheKey = (page: string, params: unknown, columns: number, isFocused: boolean) => `${page}\u0000${JSON.stringify(params ?? null)}\u0000${columns}\u0000${isFocused}`
+  const lastDrawn = new Map<string, { readonly params: string; readonly cached: string }>()
+
+  const plain = <Data,>(data: Data): Data => JSON.parse(JSON.stringify(data)) as Data
 
   return {
     declared: () => [...declared].map(([mod, pages]) => ({ mod, pages })),
+    stylers: () => [...stylers],
     element(mod, page, params, columns, isFocused) {
       if (!declared.has(mod)) void ask(mod)
-      const cached = cacheKey(page, params, columns, isFocused)
+      const given = JSON.stringify(params ?? null)
+      const cached = `${page}\u0000${given}\u0000${columns}\u0000${isFocused}`
       const name = `The ${page} page of ${mod}`
-      void parts.fill(mod, cached, { page, params: params ?? null, columns, isFocused }, name)?.then(() => claude.ui.invalidate('ui.render'))
-      return parts.element(mod, cached, `${mod}/${page}:`, name, `page:${mod}/${page}`)
+      const keyPrefix = `${mod}/${page}:`
+      void parts.fill(mod, cached, { page, params: plain(params ?? null), columns, isFocused }, name)?.then(() => claude.ui.invalidate('ui.render'))
+      const failure = parts.failure(mod, cached)
+      const drawnAt = (key: string) => parts.element(mod, key, keyPrefix, name, `page:${mod}/${page}`)
+      const last = lastDrawn.get(keyPrefix)
+      const drawn = drawnAt(cached)
+      if (drawn !== undefined) lastDrawn.set(keyPrefix, { params: given, cached })
+      return drawn ?? (last?.params === given ? drawnAt(last.cached) : undefined) ?? (failure === undefined ? undefined : Text({ color: 'error', children: `${name} could not draw: ${failure}` }))
     },
     press,
     update,
     tell(mod, shown) {
-      void claude.cmod.call({ to: mod, method: partMethods.shown, input: shown }).catch((error: unknown) => claude.ui.log(`cmod: ${mod} did not hear which of its pages show: ${messageOf(error)}`, { to: 'debug' }))
+      void claude.cmod.call({ to: mod, method: partMethods.shown, input: plain(shown) }).catch((error: unknown) => claude.ui.log(`cmod: ${mod} did not hear which of its pages show: ${messageOf(error)}`, { to: 'debug' }))
     },
     apply(listener) {
       applyTo = listener

package/src/runtime/parts.ts

@@ -7,10 +7,11 @@ import { partMethods, type DrawnPart, type PartPress } from './ui.js'
 export type DrawnParts = {
   fill(mod: string, cached: string, input: Readonly<Record<string, unknown>>, name: string): Promise<void> | undefined
   element(mod: string, cached: string, keyPrefix: string, name: string, reportId: string): RenderElement | undefined
+  failure(mod: string, cached: string): string | undefined
   forget(mod: string): void
 }
 
-type Drawn = { readonly data: DrawnPart | null; readonly generation: number }
+type Drawn = { readonly data: DrawnPart | null; readonly failure?: string; readonly generation: number }
 
 const keptDrawings = 200
 
@@ -26,9 +27,9 @@ export function drawnParts({ claude, report, press }: { readonly claude: Claude;
       const key = keyOf(mod, cached)
       const generation = generationOf(mod)
       if (drawn.get(key)?.generation === generation) return undefined
-      const keep = (data: DrawnPart | null) => {
+      const keep = (data: DrawnPart | null, failure?: string) => {
         drawn.delete(key)
-        drawn.set(key, { data, generation })
+        drawn.set(key, { data, ...(failure === undefined ? {} : { failure }), generation })
         const [oldest] = drawn.keys()
         if (drawn.size > keptDrawings && oldest !== undefined) drawn.delete(oldest)
         if (generationOf(mod) !== generation) claude.ui.invalidate('ui.render')
@@ -41,7 +42,7 @@ export function drawnParts({ claude, report, press }: { readonly claude: Claude;
             (data) => keep((data ?? null) as DrawnPart | null),
             (error: unknown) => {
               claude.ui.log(`cmod: ${name} drew nothing: ${messageOf(error)}`, { to: 'debug' })
-              keep(null)
+              keep(drawn.get(key)?.data ?? null, messageOf(error))
             },
           )
           .finally(() => drawing.delete(key))
@@ -63,6 +64,9 @@ export function drawnParts({ claude, report, press }: { readonly claude: Claude;
         return undefined
       }
     },
+    failure(mod, cached) {
+      return drawn.get(keyOf(mod, cached))?.failure
+    },
     forget(mod) {
       generations.set(mod, generationOf(mod) + 1)
     },

package/src/runtime/programs.ts

@@ -35,9 +35,13 @@ export async function readLines(stream: HookStream<ProcessSpawnChunk, ProcessSpa
   return { code: piece.value.code, lastError }
 }
 
+export function spawnCmod(claude: Claude, args: readonly string[], session: string, env: Readonly<Record<string, string>> = {}): HookStream<ProcessSpawnChunk, ProcessSpawnResult> {
+  return claude.process.spawn({ argv: ['cmod', ...args], env: { ...env, CLAUDE_CODE_SESSION_ID: session } })
+}
+
 export async function runCmod(claude: Claude, args: readonly string[], session: string): Promise<string> {
   const lines: string[] = []
-  const { code, lastError } = await readLines(claude.process.spawn({ argv: ['cmod', ...args], env: { CLAUDE_CODE_SESSION_ID: session } }), (line) => void lines.push(line))
+  const { code, lastError } = await readLines(spawnCmod(claude, args, session), (line) => void lines.push(line))
   if (code !== 0) throw new Error(cmodError(lastError, args[0]) || `cmod ${args.slice(0, 2).join(' ')} ${formatExit(code, '')}.`)
   return lines.join('\n')
 }