@cmodjs/core 0.2.3 → 1.0.0

package/src/runtime/lifecycle.ts

@@ -1,23 +1,34 @@
-import type { Args, EventResult, Frozen, HookBudget, HookStream, PluginOptions, ProcessSpawnChunk, ProcessSpawnResult } from 'claude-code'
-import type { HookInput, Mod, ModDefinition, ModEvent, ModHook, PaneHandle } from '../mod.js'
+import type { Args, EventResult, Frozen, HookBudget, PluginOptions, RenderElement } from 'claude-code'
+import type { Step } from '../installer.js'
+import { hooks, PreToolUse, type Allowed, type Disposable, type Hook, type HookInput, type HookListener, type HookOptions, type Imports, type Mod, type ModDefinition, type PaneHandle, type SettingsFile, type Toast } from '../mod.js'
 import type { Options, OptionValues } from '../options.js'
-import { consentPath, dataFolder, finishStepsMethod, isAtLeast, marketplaceOf, oldestCmodFor, openPageMethod, parseConsent, pendingStepsMethod, parseEvent, permissionWords, readRecord, readSteps, scriptsSha256, settingsPagesMethod, storeFolder, updatesToTurnOn, type ReadFile, type RunnerEvent, type Steps } from '../records.js'
-import { relativePath } from '../utils/paths.js'
-import { formatExit, listed, messageOf } from '../utils/text.js'
+import { changelogPage, consentPath, dataFolder, finishStepsMethod, isAtLeast, marketplaceOf, oldestCmodFor, openPageMethod, parseConsent, pendingStepsMethod, parseEvent, permissionWords, readRecord, readSteps, recordPath, scriptsSha256, settingsPagesMethod, storeFolder, updatesToTurnOn, type ReadFile, type RunnerEvent, type Steps } from '../records.js'
+import { ifMissing, relativePath } from '../utils/paths.js'
+import { firstLine, formatExit, listed, messageOf } from '../utils/text.js'
 import type { Claude } from './claude.js'
 import { beforeDeadline } from './deadline.js'
-import { answerCall, dependencyCalls, notInstalled } from './dependencies.js'
+import { announcedOf, announcementMs, announcementOf } from './announce.js'
+import { bind } from './bound.js'
+import { serveConversations } from './conversations.js'
+import { answerCall, cmodPluginName, dependencyCalls, notInstalled, withBareRefusals } from './dependencies.js'
+import { keepEngine } from './engine.js'
 import { classicHook, heldDecisionHook, permissionEvents, preToolUseHook, userSkillHook, type HeldDecisions, type RoutedEvent } from './hooks.js'
-import { checkedAnswer, checkingGrants, checksAnswers, checkWrite, isCovered, itemOf, passedDown, type AnswerCheck, type Grants } from './grants.js'
-import { locatingPrograms, type Programs } from './programs.js'
-import { createModFiles } from './metadata.js'
+import { checkedAnswer, checkingGrants, checkSettings, checksAnswers, checkWrite, isCovered, itemOf, passedDown, programAddresses, type AnswerCheck, type Grants } from './grants.js'
+import { cmodError, lastLineOf, locatingPrograms, readLines, 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 } from './sessions.js'
+import type { SessionChange } from '../session/conversation.js'
+import { matches } from '../utils/matcher.js'
 import { createState } from './state.js'
+import { createToaster, showFailure, type Failure, type ShownToast, type Toaster } from './toaster.js'
 import { toolCalls } from './tool-calls.js'
-import { createProgress, createUi, type Progress, type ProgressLine } from './ui.js'
+import { createUi } from './ui.js'
+import { Progress } from '../ui/components.js'
+import { Box, Text } from '../ui/elements.js'
 
 export type Plugin = {
   readonly name: string
@@ -36,6 +47,7 @@ export type Lifecycle<State extends object> = {
   readonly phase: Phase
   readonly mod: Mod<State> | undefined
   readonly failure: unknown
+  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>>
 }
@@ -43,8 +55,9 @@ export type Lifecycle<State extends object> = {
 type ModRuntime = {
   readonly claude: Claude
   readonly router: Router
-  readonly progress: Progress
+  readonly toaster: Toaster
   readonly dataFolder: string
+  readonly store: string
   readonly steps: Steps
   readonly granted: ReadonlySet<string>
   readonly refreshGrants: () => Promise<void>
@@ -55,33 +68,30 @@ type ModRuntime = {
 type ActiveMod<State extends object, Declared extends Options> = {
   readonly mod: Mod<State, Declared>
   readonly added: readonly string[]
+  readonly imports: Imports
 }
 
-const cmodPluginName = 'cmod'
 
 const announcedKey = 'cmod:announced'
 
+const installId = 'cmod:install'
+
 const cmodCheckMs = 1000
 
 const cmodWaitMs = 60_000
 
-const sessionStartHoldMs = (10_000 satisfies HookBudget['ms']) - 1_000
+const startHoldMs = (10_000 satisfies HookBudget['ms']) - 1_000
 
 const dependencyCallMs = 30_000
 
 const cannotStart = /failed to start: /
 
-const missingPath = /(?:^|: )(?:ENOENT|ENOTDIR)\b/
-
 const shellTools: readonly string[] = ['Bash', 'PowerShell']
 
 export async function readPlugin(claude: Claude): Promise<Plugin> {
   const { name, root } = claude.plugin
   const read: ReadFile = async (path) => {
-    const stat = await claude.fs.stat(path).catch((error: unknown) => {
-      if (missingPath.test(messageOf(error))) return undefined
-      throw error
-    })
+    const stat = await claude.fs.stat(path).catch(ifMissing(undefined))
     return stat?.kind === 'file' ? claude.fs.read(path) : undefined
   }
   const manifest = (await readJson(read, `${root}/.claude-plugin/plugin.json`)) as { version?: unknown } | undefined
@@ -144,13 +154,13 @@ export function createLifecycle<State extends object, Declared extends Options =
 ): Lifecycle<State> {
   let router: Router = createRouter()
   let phase: Phase = 'starting'
-  let runtime: Pick<ModRuntime, 'claude' | 'progress'> | undefined
+  let runtime: Pick<ModRuntime, 'claude' | 'toaster'> | undefined
   let programs: Programs | undefined
   let plugin: Plugin | undefined
   const granted = new Set<string>()
-  let line: ProgressLine | undefined
   let activation: Promise<void> | undefined
   let mod: Mod<State> | undefined
+  let imports: Imports | undefined
   let failure: unknown
   let pluginOptions = options
   const installer = createInstaller(definition.name, () => claude())
@@ -165,20 +175,17 @@ export function createLifecycle<State extends object, Declared extends Options =
     return runtime.claude
   }
 
-  const showLine = () => {
-    line ??= runtime?.progress.start(`Installing ${definition.name}`)
-    return line as ProgressLine
-  }
+  const installing = (description?: string | RenderElement) => runtime?.toaster.toast.loading('Installing', { id: installId, ...(description === undefined ? {} : { description }) })
 
-  const endLine = () => {
-    line?.end()
-    line = undefined
+  const toastFailure = (shown: Failure) => {
+    if (runtime !== undefined) showFailure({ name: definition.name, ui: runtime.toaster, claude: runtime.claude }, shown)
   }
 
-  const fail = (reason: string, fix: string) => {
+  const fail = (reason: string, fix: string, retry?: () => Promise<void>) => {
     phase = 'failed'
     failure ??= new Error(`${definition.name}: ${reason}${/[.!?]$/.test(reason) ? '' : '.'} ${fix}`)
-    showLine().fail(reason, fix)
+    const action = retry === undefined ? {} : { action: { label: 'Retry', onClick: () => ((failure = undefined), retry().catch(report)) } }
+    runtime?.toaster.toast.error(reason, { id: installId, description: fix, duration: Infinity, ...action })
   }
 
   const finish = async () => {
@@ -190,7 +197,7 @@ export function createLifecycle<State extends object, Declared extends Options =
   const recordThroughCmod = async () => {
     if (plugin === undefined || (await cmodVersion(claude())) === undefined) return
     const { code, lastError } = await readLines(claude().process.spawn({ argv: ['cmod', 'setup', plugin.root, '--events'] }), (text) => {
-      if (parseEvent(text).kind === 'done') shouldRecord = false
+      if (parseEvent(text).type === 'done') shouldRecord = false
     })
     if (shouldRecord) throw new Error(`cmod setup ${formatExit(code, lastError)}`)
   }
@@ -206,11 +213,11 @@ export function createLifecycle<State extends object, Declared extends Options =
   const saveOption = async (key: string, text: string): Promise<string | undefined> => {
     const option = (definition.options as Options | undefined)?.[key]
     if (option === undefined || plugin === undefined) return `${definition.name} has no option ${key}.`
-    const value = option.kind === 'number' ? Number(text) : option.kind === 'toggle' ? text.trim() === 'true' : option.kind === 'list' ? text.split(',').map((item) => item.trim()).filter((item) => item !== '') : text
-    const misfit = option.kind === 'toggle' && !['true', 'false'].includes(text.trim()) ? 'takes true or false' : fitsOption(option, value)
+    const value = option.type === 'number' ? Number(text) : option.type === 'toggle' ? text.trim() === 'true' : option.type === 'list' ? text.split(',').map((item) => item.trim()).filter((item) => item !== '') : text
+    const misfit = option.type === 'toggle' && !['true', 'false'].includes(text.trim()) ? 'takes true or false' : fitsOption(option, value)
     if (misfit !== undefined) return `${option.title} ${misfit}.`
-    const saved = await claude().config.set({ key: `${plugin.name}.${key}`, value })
-    return saved.deny
+    const saved = await claude().process.run(['cmod', 'option', plugin.name, key, Array.isArray(value) ? value.join(',') : String(value)])
+    return saved.exitCode === 0 ? undefined : cmodError(saved.stderr, 'option') || `cmod option ${formatExit(saved.exitCode, '')}.`
   }
 
   const askOptions = async (missing: MissingOptions): Promise<boolean> => {
@@ -227,19 +234,33 @@ export function createLifecycle<State extends object, Declared extends Options =
     return true
   }
 
+  const isStepDone = async (active: Mod<State>, step: Step<State>) => {
+    try {
+      return await step.isDone(active)
+    } catch (error) {
+      toastFailure({ id: `step:${step.title}`, message: `The ${step.title} step's isDone failed`, error })
+      return false
+    }
+  }
+
   const pendingSteps = async (active: Mod<State>) => {
     const pending: string[] = []
-    for (const step of definition.installer ?? []) if (!(await Promise.resolve(step.isDone(active)).catch(() => false))) pending.push(step.title)
+    for (const step of definition.installer ?? []) if (!(await isStepDone(active, step))) pending.push(step.title)
     return pending
   }
 
   const runSteps = async (active: Mod<State>) => {
     const steps = asksPerson ? (definition.installer ?? []) : []
     for (const [index, step] of steps.entries()) {
-      if (await Promise.resolve(step.isDone(active)).catch(() => false)) continue
+      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) {
-        claude().ui.log(`${definition.name} needs ${steps.length - index === 1 ? 'one more step' : `${steps.length - index} more steps`}, starting with ${step.title}. Run /mods ${definition.name} to finish.`)
+        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}. Finish them in /mods ${definition.name}.`,
+          duration: Infinity,
+          action: { label: 'Finish', onClick: () => active.settings.open() },
+        })
         break
       }
     }
@@ -249,7 +270,7 @@ export function createLifecycle<State extends object, Declared extends Options =
   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), steps: plugin.steps, granted, refreshGrants, checksPermissions, 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, checksPermissions, options: pluginOptions }).catch(async (error: unknown) => {
       if (error instanceof MissingOptions && (await askOptions(error))) return undefined
       fail(messageOf(error), error instanceof MissingOptions ? `Set ${error.keys.length === 1 ? 'it' : 'them'} in /config.` : 'Fix it, then run /reload-plugins.')
       throw error
@@ -257,47 +278,58 @@ export function createLifecycle<State extends object, Declared extends Options =
     if (active === undefined) return activate()
     const { added } = active
     mod = active.mod
+    imports = active.imports
     router = activeRouter
     phase = 'active'
     runtime.claude.ui.invalidate('ui.render')
-    endLine()
-    void runSteps(active.mod).catch((error: unknown) => claude().ui.log(`${definition.name}: its installer stopped: ${messageOf(error)}`))
+    void runSteps(active.mod).catch((error: unknown) => toastFailure({ id: 'cmod:steps', message: 'Its installer stopped', error }))
     const missed = missedSessionStart
     missedSessionStart = undefined
     const lateAnswer = missed === undefined ? {} : await activeRouter.dispatch('classic.SessionStart', missed, async () => ({})).catch((error: unknown) => {
-      claude().ui.log(`${definition.name}: the SessionStart hook failed: ${messageOf(error)}`)
+      toastFailure({ id: 'classic.SessionStart', message: 'The SessionStart hook failed', error })
       return {}
     })
     if (Object.keys(lateAnswer).length > 0) {
       runtime.claude.ui.log(`${definition.name} started after Claude Code's SessionStart, so Claude Code did not read the answer of its SessionStart hooks.`, { to: 'debug' })
     }
     const version = plugin.version ?? ''
-    if ((await runtime.claude.store.get(announcedKey)) === version) return
-    await runtime.claude.store.set(announcedKey, version)
-    runtime.claude.ui.toast(`${definition.name} is ready`)
-    if (added.length > 0) runtime.claude.ui.log(`${definition.name} added ${listed(added)}.`)
+    const announced = announcedOf(await runtime.claude.store.get(announcedKey))
+    if (announced?.version === version) {
+      runtime.toaster.toast.dismiss(installId)
+      return
+    }
+    await runtime.claude.store.set(announcedKey, { version, added })
+    const { toaster } = runtime
+    void announcementOf(runtime.claude, plugin, granted, added, announced)
+      .then(({ message, ...options }) => toaster.toast.success(message, { id: installId, duration: announcementMs, ...options }))
+      .catch((error: unknown) => toastFailure({ id: installId, message: 'Could not say what it installed', error }))
   }
 
   const updatesToShow = async () => {
     const [home, configHome] = await Promise.all([claude().env.home(), claude().env.configHome()])
     const configRoot = configHome ?? `${home ?? ''}/.claude`
-    const known = await claude().fs.read(`${configRoot}/plugins/known_marketplaces.json`).then((text): unknown => JSON.parse(text), () => undefined)
+    const known = await claude()
+      .fs.read(`${configRoot}/plugins/known_marketplaces.json`)
+      .then((text): unknown => JSON.parse(text))
+      .catch(ifMissing(undefined))
     return updatesToTurnOn(marketplaceOf(claude().plugin.root, claude().plugin.name), await claude().settings.read({ source: 'user' }), known)
   }
 
-  const askConsent = async (event: Extract<RunnerEvent, { kind: 'needs-consent' }>) => {
+  const askConsent = async (event: Extract<RunnerEvent, { type: 'needs-consent' }>) => {
     const name = definition.name
     if ((await claude().session.surfaces()).length === 0) {
-      showLine().wait(`Waiting for consent: run cmod install ${name}`)
       claude().ui.log(`${name} waits for consent to run ${event.install}. Run cmod install ${name} in a terminal.`)
       return
     }
-    showLine().wait('Waiting for your answer')
-    if (await installer.consent({ ...event, updates: await updatesToShow().catch(() => undefined) })) return install(event.sha256)
+    installing('Waiting for your answer')
+    const updates = await updatesToShow().catch((error: unknown) => {
+      toastFailure({ id: 'cmod:updates', message: 'Could not read whether its marketplace updates automatically', error })
+      return undefined
+    })
+    if (await installer.consent({ ...event, updates })) return install(event.sha256)
     await installer.close()
     phase = 'declined'
-    endLine()
-    claude().ui.log(`${name} is not installed. Run cmod install ${name} to install it.`)
+    runtime?.toaster.toast('Not installed', { id: installId, description: `Run cmod install ${name} to install it.` })
   }
 
   const install = async (consent?: string): Promise<void> => {
@@ -306,29 +338,28 @@ export function createLifecycle<State extends object, Declared extends Options =
     phase = 'installing'
     const found = await cmodVersion(claude())
     if (!fits(found)) return waitForcmod(found)
-    endLine()
-    const progress = showLine()
+    installing()
     let outcome: RunnerEvent | undefined
     const argv = ['cmod', 'setup', plugin.root, '--events', ...(consent === undefined ? [] : ['--consent', consent])]
     const { code, lastError } = await readLines(claude().process.spawn({ argv }), (text) => {
       const event = parseEvent(text)
-      if (event.kind === 'progress') progress.report(event)
-      if (event.kind === 'done' || event.kind === 'failed' || event.kind === 'needs-consent') outcome = event
+      if (event.type === 'progress') installing(progressOf(event))
+      if (event.type === 'done' || event.type === 'failed' || event.type === 'needs-consent') outcome = event
     })
-    if (outcome?.kind === 'done') {
+    if (outcome?.type === 'done') {
       for (const item of plugin.steps.permissions ?? []) granted.add(item)
       return finish()
     }
-    if (outcome?.kind === 'needs-consent') return askConsent(outcome)
-    const reason = outcome?.kind === 'failed' ? outcome.message : `cmod setup ${formatExit(code, lastError)}`
-    fail(reason, `Fix the cause, then run: cmod install ${definition.name}`)
+    if (outcome?.type === 'needs-consent') return askConsent(outcome)
+    const reason = outcome?.type === 'failed' ? outcome.message : `cmod setup ${formatExit(code, lastError)}`
+    fail(reason, `Fix the cause, then retry, or run cmod install ${definition.name} in a terminal.`, install)
   }
 
   const fits = (found: string | undefined): found is string => found !== undefined && isAtLeast(found, oldestCmodFor(plugin?.steps ?? {}))
 
   const waitForcmod = (found: string | undefined) => {
     phase = 'waiting'
-    showLine().wait('Waiting for cmod')
+    installing('Waiting for cmod')
     let latest = found
     let check: Promise<void> | undefined
     const stop = () => {
@@ -350,7 +381,7 @@ export function createLifecycle<State extends object, Declared extends Options =
         })
     })
     const longWait = claude().clock.after(cmodWaitMs, () =>
-      showLine().wait(
+      installing(
         latest === undefined
           ? "Still waiting for cmod to download cmod. See cmod's own line."
           : `PATH finds cmod ${latest}, and ${definition.name} needs cmod ${oldestCmodFor(plugin?.steps ?? {})} or later. Run npm i -g @cmodjs/cli, or put ~/.local/bin ahead of the old cmod on PATH.`,
@@ -359,14 +390,14 @@ export function createLifecycle<State extends object, Declared extends Options =
   }
 
   const bootstrap = async (root: string) => {
-    const progress = showLine()
+    installing()
     phase = 'installing'
     const { code, lastError } = await readLines(claude().process.spawn({ argv: ['sh', '-c', './setup/bootstrap.sh'], cwd: root }), (text) => {
       const event = parseEvent(text)
-      if (event.kind === 'progress') progress.report(event)
+      if (event.type === 'progress') installing(progressOf(event))
     })
     if (code === 0) return finish()
-    fail(`bootstrap ${formatExit(code, lastError)}`, `Run ./setup/bootstrap.sh in ${root} to see the whole log.`)
+    fail(`bootstrap ${formatExit(code, lastError)}`, `Run ./setup/bootstrap.sh in ${root} to see the whole log.`, () => bootstrap(root))
   }
 
   const report = (error: unknown) => {
@@ -375,14 +406,30 @@ export function createLifecycle<State extends object, Declared extends Options =
   }
 
   let consentMs = 0
-  const consentStamp = async (path: string) => {
-    const stat = await claude().fs.stat(path).catch(() => undefined)
+  const stampOf = async (path: string) => {
+    const stat = await claude().fs.stat(path).catch(ifMissing(undefined))
     return stat?.kind === 'file' ? stat.mtimeMs : 0
   }
+  let recordMs = 0
+  let readStarted: ((claude: Claude) => Promise<Plugin>) | undefined
+  const recover = async () => {
+    if (plugin === undefined || readStarted === undefined || (phase !== 'failed' && phase !== 'declined')) return
+    const modifiedMs = await stampOf(recordPath(plugin.store, plugin.name))
+    if (modifiedMs === recordMs) return
+    recordMs = modifiedMs
+    const current = await readStarted(claude())
+    if (!current.isInstalled) return
+    plugin = current
+    failure = undefined
+    activation = undefined
+    await refreshGrants()
+    await finish()
+  }
+
   const refreshGrants = async () => {
     if (plugin === undefined || plugin.name === cmodPluginName) return
     const path = consentPath(plugin.store)
-    const modifiedMs = await consentStamp(path)
+    const modifiedMs = await stampOf(path)
     if (modifiedMs === consentMs) return
     consentMs = modifiedMs
     const approved = modifiedMs === 0 ? [] : (parseConsent(JSON.parse(await claude().fs.read(path)), path)[plugin.name] ?? [])
@@ -403,7 +450,7 @@ export function createLifecycle<State extends object, Declared extends Options =
       droppedParts.add(item)
       const declared = plugin?.steps.permissions ?? []
       const fix = declared.includes(item) ? `Turn it on in /mods ${definition.name}.` : `It needs "permissions": { "${item}": true } in package.json "cmod".`
-      claude().ui.log(`${definition.name} answered ${part} without your grant to "${permissionWords(item)}", so cmod dropped it. ${fix}`)
+      runtime?.toaster.toast.warning(`Answered ${part} without your grant to "${permissionWords(item)}", so cmod dropped it`, { id: `dropped:${item}`, description: fix, duration: Infinity })
     },
   }
 
@@ -419,14 +466,16 @@ export function createLifecycle<State extends object, Declared extends Options =
     if (activation !== undefined && phase !== 'active') await activation
   }
 
-  const holdSessionStart = () =>
-    new Promise<void>((resolve) => {
-      const limit = claude().clock.after(sessionStartHoldMs, resolve)
-      void startSettled.then(whenActive).then(() => {
-        limit.cancel()
-        resolve()
-      })
-    })
+  const holdUntilStarted = (): Promise<void> =>
+    runtime === undefined
+      ? startSettled.then(whenActive)
+      : new Promise<void>((resolve) => {
+          const limit = claude().clock.after(startHoldMs, resolve)
+          void startSettled.then(whenActive).then(() => {
+            limit.cancel()
+            resolve()
+          })
+        })
 
   return {
     get phase() {
@@ -438,10 +487,13 @@ export function createLifecycle<State extends object, Declared extends Options =
     get failure() {
       return failure
     },
+    get toasts() {
+      return runtime?.toaster.shown ?? []
+    },
     async start(claudeCalls, read) {
       if (runtime !== undefined) return
       programs = locatingPrograms(claudeCalls)
-      runtime = { claude: programs.claude, progress: createProgress(claudeCalls) }
+      runtime = { claude: programs.claude, toaster: createToaster(claudeCalls, definition.name) }
       try {
         await programs.refresh()
         const started = await read(claudeCalls).catch((error: unknown) => {
@@ -450,8 +502,10 @@ export function createLifecycle<State extends object, Declared extends Options =
         })
         if (started === undefined) return
         plugin = started
+        readStarted = read
         for (const item of started.granted) granted.add(item)
-        consentMs = await consentStamp(consentPath(started.store))
+        consentMs = await stampOf(consentPath(started.store))
+        recordMs = await stampOf(recordPath(started.store, started.name))
         if (started.isInstalled) {
           shouldRecord = started.shouldRecord
           if (shouldRecord) record()
@@ -464,6 +518,7 @@ 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)
       if (event === 'classic.SessionStart') missedSessionStart = undefined
@@ -472,9 +527,11 @@ export function createLifecycle<State extends object, Declared extends Options =
         return next(e)
       }
       if (shouldRecord && event === 'classic.UserPromptSubmit') record()
-      await (event === 'classic.SessionStart' ? holdSessionStart() : whenActive())
+      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
+      await (event === 'classic.SessionStart' || isCallToThisMod ? holdUntilStarted() : whenActive())
       if (event === 'classic.SessionStart' && phase !== 'active') missedSessionStart = e as Frozen<Args<'classic.SessionStart'>>
-      if (event === 'cmod.call' && phase !== 'active' && (e as Frozen<Args<'cmod.call'>>).to === definition.name) {
+      if (isCallToThisMod && phase !== 'active') {
         const isStopped = phase === 'declined' || phase === 'failed'
         return { deny: isStopped ? notInstalled(definition.name) : `${definition.name} is installing. Try again when it's ready.` } as EventResult<N>
       }
@@ -487,17 +544,18 @@ export function createLifecycle<State extends object, Declared extends Options =
       if (checksAnswers(event) && phase === 'active') return checkedRoute(event, e, next)
       const answer = router.dispatch(event, e, next)
       const render = e as Frozen<Args<'ui.render'>>
-      if (event !== 'ui.render' || render.component !== 'AbovePrompt' || runtime === undefined || !runtime.progress.isShown) return answer as Promise<EventResult<N>>
-      return runtime.progress.draw((await answer) as EventResult<'ui.render'>, runtime.claude.ui.resolve(render), render.viewport?.columns) as EventResult<N>
+      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) as EventResult<N>
     },
   }
 }
 
 async function createMod<State extends object, Declared extends Options>(definition: ModDefinition<State, string, Declared>, runtime: ModRuntime): Promise<ActiveMod<State, Declared>> {
-  const { router, progress } = runtime
-  const claude = checkingKeys(runtime.claude, definition.name, runtime.steps.keys ?? {})
+  const { router, toaster } = runtime
+  const report = (failure: Failure) => void showFailure({ name: definition.name, ui: toaster, claude: runtime.claude }, failure)
+  const claude = withBareRefusals(checkingKeys(runtime.claude, toaster.toast, runtime.steps.keys ?? {}))
   const added: string[] = []
-  const hookEvents: ModEvent[] = []
+  const hooksAdded: Hook[] = []
   const announce = (feature: string) => {
     added.push(feature)
   }
@@ -513,18 +571,22 @@ async function createMod<State extends object, Declared extends Options>(definit
     configRoot,
     projectRoot: () => modState.root,
     freeFolders: () => [modState.root, runtime.dataFolder],
+    freeAddresses: () => programAddresses(mod),
   }
   const checked = checkingGrants(claude, grants)
+  const places: Places = { home, configRoot, projectRoot: () => modState.root }
   const files = createModFiles({
     name: definition.name,
     claude,
-    places: { home, configRoot, projectRoot: () => modState.root },
+    places,
     checkWrite: (path) => checkWrite(grants, `metadata.update(${path})`, path),
+    report,
   })
   const pages = new Map<string, { readonly title: string; readonly handle: PaneHandle }>()
   const settingsPages: Mod<State>['settings'] = {
     page(page) {
       if (pages.has(page.id)) throw new Error(`${definition.name}: the settings page "${page.id}" is already added. Give each page its own id.`)
+      if (page.id === changelogPage) throw new Error(`${definition.name}: the settings page id "${changelogPage}" opens the mod's CHANGELOG.md in /mods. Give the page another id.`)
       pages.set(page.id, { title: page.title, handle: area.ui.pane(page) })
     },
     async open(pageId) {
@@ -540,81 +602,141 @@ async function createMod<State extends object, Declared extends Options>(definit
   let cwd = startCwd
   let loadedCwd = startCwd
   let staleCwd: string | undefined
-  const area = createUi<State>({ name: definition.name, claude, router, progress, announce, mod: () => mod })
-  const modState = createState<State>({ name: definition.name, initial: definition.state ?? {}, session, root, claude, changed: area.changed })
-  const modOptions = createOptions({ name: definition.name, declared: definition.options ?? {}, fromClaude: runtime.options, claude, changed: modState.changed })
+  let forkedFrom: string | undefined
+  let parentAsked: Promise<string | undefined> | undefined
+  let hasEarlierPrompts = true
+  const area = createUi<State>({ name: definition.name, claude, router, toaster, report, announce, mod: () => mod })
+  const askParent = async (): Promise<string | undefined> => {
+    if (definition.name === cmodPluginName) return undefined
+    try {
+      const parent = await claude.cmod.call({ to: cmodPluginName, method: 'forkParent', input: null })
+      return typeof parent === 'string' ? parent : undefined
+    } catch (error) {
+      claude.ui.log(`${definition.name} starts without the session values of the conversation it was forked from: ${messageOf(error)}`, { to: 'debug' })
+      return undefined
+    }
+  }
+  const forkParent = () =>
+    (parentAsked ??= askParent().then((parent) => {
+      forkedFrom = parent
+      return parent
+    }))
+  const modState = createState<State>({ name: definition.name, initial: definition.state ?? {}, session, root, claude, report, changed: area.changed, forkParent })
+  const modOptions = createOptions({ name: definition.name, declared: definition.options ?? {}, fromClaude: runtime.options, claude, report, changed: modState.changed })
   const held: HeldDecisions | undefined = runtime.checksPermissions() ? new Map() : undefined
-  const mod: Mod<State, Declared> = {
-    name: definition.name,
-    state: modState.state,
-    get options() {
-      return modOptions.values as OptionValues<Declared>
-    },
-    dataFolder: runtime.dataFolder,
-    on(event, hook, options) {
-      const bounded = options?.timeoutMs === undefined ? hook : timedHook(definition.name, event, hook, checkedMs(definition.name, `the ${event} hook's timeoutMs`, options.timeoutMs), claude)
-      if (!hookEvents.includes(event)) hookEvents.push(event)
-      if (event === 'PreToolUse') router.add('tool.call', preToolUseHook(definition.name, bounded as ModHook<'PreToolUse'>, claude, agents, held))
-      else router.add(`classic.${event as Exclude<ModEvent, 'PreToolUse'>}`, classicHook(definition.name, event as Exclude<ModEvent, 'PreToolUse'>, bounded as ModHook<Exclude<ModEvent, 'PreToolUse'>>, claude, agents))
-    },
-    use: (job) => job({ mod, announce, reserveName, toolCalls: agents }),
-    every(ms, hook) {
-      let isRunning = false
-      return claude.clock.every(checkedMs(definition.name, 'mod.every', ms), () => {
-        if (isRunning) return
-        isRunning = true
-        void Promise.resolve()
-          .then(hook)
-          .catch((error: unknown) => claude.ui.log(`${definition.name}: the every ${ms} ms hook failed: ${messageOf(error)}`))
-          .finally(() => {
-            isRunning = false
-          })
-      })
-    },
-    ui: area.ui,
-    process: {
-      run: (argv, init) => checked.process.run(argv, init),
-      spawn: (argv, init) => checked.process.spawn({ ...init, argv }),
+  const expand = (path: string) => (path === '~' || path.startsWith('~/') ? resolvedPath(path, places) : path)
+  const settingsFile = (source: 'user' | 'project' | 'local'): SettingsFile => ({
+    read: () => checked.settings.read({ source }),
+    async update(values) {
+      await checkSettings(grants, source, Object.keys(values))
+      await claude.cmod.call({ to: cmodPluginName, method: 'updateSettings', input: { mod: definition.name, source, project: modState.root, values } })
     },
+  })
+  const client = createSessionsClient({ name: definition.name, claude: checked, report: (id, message, error) => report({ id, message, error }) })
+  let followed: Parameters<typeof client.follow>[0] | undefined
+  const followFolders = (project: string, folder: string) => {
+    if (followed === undefined) return
+    followed = { ...followed, project, cwd: folder }
+    client.follow(followed)
+  }
+  const imports: Imports = {
+    sessions: client.sessions,
+    settings: { user: settingsFile('user'), project: settingsFile('project'), local: settingsFile('local') },
+    model: { complete: (completion, options) => checked.model.complete(completion, options) },
     fs: {
-      read: (path) => checked.fs.read(path),
-      write: (path, text) => checked.fs.write(path, text),
-      list: (path) => checked.fs.list(path),
-      exists: (path) => checked.fs.exists(path),
-      stat: (path, options) => checked.fs.stat(path, options),
+      read: (path) => checked.fs.read(expand(path)),
+      write: (path, text) => checked.fs.write(expand(path), text),
+      exists: (path) => checked.fs.exists(expand(path)),
       find: (glob) => files.find(glob),
+      list: async (path) => (await checked.fs.list(path === undefined ? undefined : expand(path))).map(({ name, kind, size, mtimeMs, isLink }) => ({ name, isFile: kind === 'file', isFolder: kind === 'dir', isLink, size, modifiedAt: mtimeMs })),
+      async stat(path, options) {
+        const { kind, size, mtimeMs, isLink, realPath } = await checked.fs.stat(expand(path), options)
+        return { isFile: kind === 'file', isFolder: kind === 'dir', isLink, size, modifiedAt: mtimeMs, ...(realPath === undefined ? {} : { realPath }) }
+      },
     },
     metadata: {
       read: (path) => files.read(path),
       update: (path, change) => files.update(path, change),
     },
+    process: {
+      run: (argv, init) => checked.process.run(argv, init),
+      spawn: (argv, init) => checked.process.spawn({ ...init, argv }),
+    },
     http: { fetch: (url, init) => checked.http.fetch(url, init) },
-    settings: settingsPages,
-    session: {
-      messages: ((args?: { readonly agentId: string }) => (args === undefined ? checked.session.messages() : checked.session.messages({ agentId: args.agentId }))) as Mod<State>['session']['messages'],
-      async append(text) {
-        const added = await checked.session.append({ message: { type: 'user', content: [{ type: 'text', text }] } })
-        if (added.deny !== undefined) throw new Error(`${definition.name}: Claude Code refused the note: ${added.deny}`)
-      },
-      async submit(text) {
-        const submitted = await checked.prompt.submit({ text })
-        if ('drop' in submitted && typeof submitted.drop === 'string') throw new Error(`${definition.name}: Claude Code dropped the prompt: ${submitted.drop}`)
-      },
+  }
+  const allowed = (permission: string): Allowed => ({ allows: (value) => isCovered(granted, itemOf(permission, value), home) })
+  const flag = (permission: string) => isCovered(granted, permission, home)
+  const timer = (ms: number, subject: string, start: (ms: number, run: () => void) => { cancel(): void }, listener: () => unknown): Disposable => {
+    let isRunning = false
+    const started = start(checkedMs(definition.name, `mod.${subject}`, ms), () => {
+      if (isRunning) return
+      isRunning = true
+      void Promise.resolve()
+        .then(() => {
+          bind(imports)
+          return listener()
+        })
+        .catch((error: unknown) => report({ id: `${subject}:${ms}`, message: `The ${subject} ${ms} ms timer failed`, error }))
+        .finally(() => {
+          isRunning = false
+        })
+    })
+    return { dispose: () => started.cancel() }
+  }
+  const mod: Mod<State, Declared> = {
+    name: definition.name,
+    folder: claude.plugin.root,
+    dataFolder: runtime.dataFolder,
+    state: modState.state,
+    get options() {
+      return modOptions.values as OptionValues<Declared>
     },
-    agent: { spawn: (args) => checked.agent.spawn(args) },
-    model: { complete: (completion, options) => checked.model.complete(completion, options) },
     permissions: {
-      has: (name: string, value?: string) => isCovered(granted, itemOf(name, value), home),
-    },
-    claude: { ...checked, on: (event, hook) => router.add(event, hook) },
-    get projectRoot() {
-      return modState.root
+      get conversation() {
+        return flag('conversation')
+      },
+      get prompt() {
+        return flag('prompt')
+      },
+      get model() {
+        return flag('model')
+      },
+      get tasks() {
+        return flag('tasks')
+      },
+      get tools() {
+        return flag('tools')
+      },
+      get approve() {
+        return flag('approve')
+      },
+      network: allowed('network'),
+      run: allowed('run'),
+      files: allowed('files'),
+      config: allowed('config'),
     },
-    get cwd() {
-      return cwd
+    on(hook: Hook, matcherOrListener: unknown, listenerOrOptions?: unknown, maybeOptions?: HookOptions): Disposable {
+      const hasMatcher = typeof listenerOrOptions === 'function'
+      const listener = (hasMatcher ? listenerOrOptions : matcherOrListener) as HookListener<Hook>
+      const matcher = hasMatcher ? matcherOrListener : undefined
+      const options = (hasMatcher ? maybeOptions : listenerOrOptions) as HookOptions | undefined
+      if (!hooks.includes(hook)) throw new Error(`${definition.name}: mod.on takes one of Claude Code's hooks, such as PreToolUse, not ${String(hook)}.`)
+      const matched: HookListener<Hook> = matcher === undefined ? listener : (input) => (matches(input, matcher) ? listener(input) : undefined)
+      const bounded = options?.timeoutMs === undefined ? matched : timedHook(hook, matched, checkedMs(definition.name, `the ${hook} hook's timeoutMs`, options.timeoutMs), claude, toaster.toast)
+      if (!hooksAdded.includes(hook)) hooksAdded.push(hook)
+      if (hook === PreToolUse) return router.add('tool.call', preToolUseHook(definition.name, bounded as HookListener<typeof PreToolUse>, claude, agents, held))
+      const classic: Exclude<Hook, typeof PreToolUse> = hook
+      return router.add(`classic.${classic}`, classicHook(definition.name, classic, bounded as HookListener<typeof classic>, claude, agents, report))
     },
+    every: (ms, listener) => timer(ms, 'every', claude.clock.every, listener),
+    after: (ms, listener) => timer(ms, 'after', claude.clock.after, listener),
+    use: (job) => job({ mod, announce, reserveName }),
+    log: (text) => claude.ui.log(`${definition.name}: ${text}`, { to: 'debug' }),
+    ui: { ...area.ui, notice: (callId, text) => claude.ui.notice(callId, text) },
+    settings: settingsPages,
     dependencies: dependencyCalls(claude, (call, task) => beforeDeadline(claude, { ms: dependencyCallMs }, call, task)),
   }
+  bind(imports)
   const followSession = async (isAfterCd = false) => {
     try {
       const [nextRoot, reportedCwd] = await Promise.all([claude.session.root(), claude.session.cwd()])
@@ -625,8 +747,10 @@ async function createMod<State extends object, Declared extends Options>(definit
       const nextCwd = staleCwd === undefined ? reportedCwd : nextRoot
       if (!hasMovedRoot && nextCwd === oldCwd) return
       cwd = nextCwd
+      followFolders(nextRoot, nextCwd)
       await modState.moveTo(nextRoot).catch((error: unknown) => {
         if (cwd === nextCwd) cwd = loadedCwd
+        followFolders(modState.root, cwd)
         throw error
       })
       if (hasMovedRoot) await modOptions.load(nextRoot)
@@ -636,18 +760,33 @@ async function createMod<State extends object, Declared extends Options>(definit
       const moved: HookInput<'CwdChanged'> = { session_id: await claude.session.id(), cwd: nextCwd, hook_event_name: 'CwdChanged', old_cwd: oldCwd, new_cwd: nextCwd }
       await router.dispatch('classic.CwdChanged', moved as Frozen<Args<'classic.CwdChanged'>>, async () => ({}))
     } catch (error) {
-      claude.ui.log(`${definition.name} keeps the state of ${modState.root} until the next prompt or folder move: ${messageOf(error)}`)
+      report({ id: 'cmod:follow', message: `Keeps the state of ${modState.root} until the next prompt or folder move`, error })
     }
   }
+  const followCurrent = async (title: string | undefined) => {
+    const [id, model, usage] = await Promise.all([claude.session.id(), claude.session.model(), claude.session.usage()])
+    followed = { id, title: title ?? '', project: modState.root, cwd, model, startedAt: new Date(usage.startedAt).toISOString(), ...(forkedFrom === undefined ? {} : { forkedFrom }) }
+    client.follow(followed)
+  }
   router.add('classic.SessionStart', async (e, next) => {
-    await modState.switchSession(e.session_id, e.source).catch((error: unknown) => {
-      claude.ui.log(`${definition.name} kept its session values from before the ${e.source}: ${messageOf(error)}`)
+    const previous = followed?.id
+    if (e.source === 'fork' && previous !== undefined && previous !== e.session_id) forkedFrom = previous
+    else if (e.session_id !== previous) {
+      forkedFrom = undefined
+      parentAsked = undefined
+    }
+    hasEarlierPrompts = e.source !== 'startup' && e.source !== 'clear'
+    await modState.switchSession(e.session_id, e.source, e.transcript_path).catch((error: unknown) => {
+      report({ id: 'cmod:session', message: `Kept its session values from before the ${e.source}`, error })
     })
+    await followCurrent(e.session_title).catch((error: unknown) => report({ id: 'cmod:current', message: 'Kept the details of the session from before', error }))
     return next(e)
   })
   router.add('classic.UserPromptSubmit', async (e, next) => {
     staleCwd = undefined
     await followSession()
+    const isPerson = e.source === undefined || e.source === 'user' || e.source === 'sdk'
+    await followCurrent(e.session_title || (isPerson && !hasEarlierPrompts && client.sessions.current.title === '' ? firstLine(e.prompt) : undefined)).catch((error: unknown) => report({ id: 'cmod:current', message: 'Kept the details of the session from before', error }))
     return next(e)
   })
   for (const event of ['classic.PostToolUse', 'classic.PostToolUseFailure'] as const) {
@@ -663,44 +802,56 @@ async function createMod<State extends object, Declared extends Options>(definit
   })
   router.add('skill.prompt', userSkillHook(claude))
   const api = Object.fromEntries(Object.entries(definition.api ?? {}).map(([method, run]) => [method, (input: never) => run(input, mod)]))
+  const conversations = definition.name === cmodPluginName ? serveConversations({ claude, router, store: runtime.store, project: () => modState.root, report: (id, message, error) => report({ id, message, error }) }) : undefined
   router.add('cmod.call', async (e, next) => {
     if (e.to !== definition.name) return next(e)
+    const call = e as typeof e & { readonly caller?: string }
+    if (e.method === conversationMethods.changed && call.caller === cmodPluginName) {
+      if (!flag('conversation')) return { value: null }
+      const { session: changedSession, change } = e.input as { readonly session: string; readonly change: SessionChange }
+      client.changed(changedSession, change)
+      return { value: null }
+    }
     if (e.method === settingsPagesMethod) return { value: [...pages].map(([id, { title }]) => ({ id, title })) }
     if (e.method === openPageMethod) {
       await settingsPages.open(String(e.input))
       return { value: null }
     }
-    return answerCall(definition.name, api, e)
+    const served = await conversations?.answer(call)
+    return served ?? answerCall(definition.name, api, e)
   })
   const agents = toolCalls(claude, router)
+  keepEngine(mod, { claude: checked, router, toolCalls: agents, report })
   const names = new Set<string>()
-  const reserveName = (kind: string, name: string, taken: string) => {
-    const key = `${kind}:${name}`
+  const reserveName = (type: string, name: string, taken: string): Disposable => {
+    const key = `${type}:${name}`
     if (names.has(key)) throw new Error(taken)
     names.add(key)
+    return { dispose: () => void names.delete(key) }
   }
   await failsAs('its state did not load', () => modState.load())
   await failsAs('its options did not load', () => modOptions.load(root))
   const missing = modOptions.missing
   if (missing.length > 0) throw new MissingOptions(missing, missing.map((key) => definition.options?.[key]?.title ?? key))
+  await failsAs('the details of its session did not load', () => followCurrent(undefined))
   await failsAs('its setup function threw', () => definition.setup(mod))
   const permissionHooks = permissionEvents.filter((event) => router.has(event))
   if (permissionHooks.length > 0 && !runtime.checksPermissions()) {
     throw new Error(`it decides permissions on ${listed(permissionHooks)}, so hooks/register.ts must call registerPermissionCheck(addHook) after registerMod`)
   }
-  if (held !== undefined && hookEvents.includes('PreToolUse')) router.add('tool.check', heldDecisionHook(held))
+  if (held !== undefined && hooksAdded.includes(PreToolUse)) router.add('tool.check', heldDecisionHook(held))
   await failsAs('its open panes did not load', () => area.restorePanes())
-  if (hookEvents.length > 0) added.push(`${hookEvents.length === 1 ? 'a hook' : 'hooks'} on ${listed(hookEvents)}`)
-  return { mod, added }
+  if (hooksAdded.length > 0) added.push(`${hooksAdded.length === 1 ? 'a hook' : 'hooks'} on ${listed(hooksAdded)}`)
+  return { mod, added, imports }
 }
 
-function checkingKeys(claude: Claude, name: string, keys: Readonly<Record<string, string>>): Claude {
+function checkingKeys(claude: Claude, toast: Toast, keys: Readonly<Record<string, string>>): Claude {
   const bound = Object.entries(keys)
   if (bound.length === 0) return claude
   const register: Claude['command']['register'] = (command) => {
     for (const [key, commandName] of bound) {
       if (commandName === command.name && command.immediate !== true) {
-        claude.ui.log(`${name}: ${key} runs /${command.name}, which waits for Claude's turn to end and adds a row to the conversation. Give /${command.name} immediate: true.`)
+        toast.warning(`${key} runs /${command.name}, which waits for Claude's turn to end`, { id: `key:${key}`, description: `It adds a row to the conversation. Give /${command.name} immediate: true.`, duration: Infinity })
       }
     }
     return claude.command.register(command)
@@ -715,11 +866,11 @@ function checkedMs(name: string, subject: string, ms: number): number {
   return ms
 }
 
-function timedHook<E extends ModEvent>(name: string, event: E, hook: ModHook<E>, ms: number, claude: Claude): ModHook<E> {
+function timedHook<H extends Hook>(event: H, hook: HookListener<H>, ms: number, claude: Claude, toast: Toast): HookListener<H> {
   return (input) =>
     new Promise((resolve, reject) => {
       const timer = claude.clock.after(ms, () => {
-        claude.ui.log(`${name}: the ${event} hook passed its ${ms / 1000} s timeout`)
+        toast.warning(`The ${event} hook passed its ${ms / 1000} s timeout`, { id: `timeout:${event}` })
         resolve(undefined)
       })
       Promise.resolve()
@@ -745,25 +896,6 @@ async function failsAs(subject: string, step: () => unknown): Promise<void> {
   }
 }
 
-async function readLines(stream: HookStream<ProcessSpawnChunk, ProcessSpawnResult>, onLine: (text: string) => void): Promise<{ code: number | null; lastError: string }> {
-  let pending = ''
-  let lastError = ''
-  let piece = await stream.next()
-  while (piece.done !== true) {
-    if (piece.value.stream === 'stderr') {
-      lastError = lastLineOf(piece.value.text) ?? lastError
-    } else {
-      const lines = `${pending}${piece.value.text}`.split('\n')
-      pending = lines.pop() ?? ''
-      for (const text of lines) onLine(text)
-    }
-    piece = await stream.next()
-  }
-  if (pending !== '') onLine(pending)
-  return { code: piece.value.code, lastError }
-}
-
-function lastLineOf(text: string): string | undefined {
-  const trimmed = text.trim()
-  return trimmed === '' ? undefined : trimmed.slice(trimmed.lastIndexOf('\n') + 1).trim()
+function progressOf({ done, total, label }: Extract<RunnerEvent, { type: 'progress' }>): RenderElement {
+  return Box({ gap: 2, children: [Progress({ value: total > 0 ? (done / total) * 100 : 0 }), Text({ dimColor: true, wrap: 'truncate-end', children: label })] })
 }