dsh-tui-theme 0.5.1 → 0.6.1

package/scripts/validate-themes-against-host.mjs

@@ -1,7 +1,8 @@
 /**
  * Validate bundled themes against matching dsh-TUI source and runtime modules.
- * DSH_TUI_SOURCE_ROOT must point at a dsh-TUI source checkout.
- * DSH_TUI_ADAPTER_DIR must point at the matching lib/types/dsh-adapter directory.
+ * DSH_TUI_SOURCE_ROOT and DSH_TUI_ADAPTER_DIR may point at a matching source
+ * checkout and adapter directory. When omitted, the installed dsh-TUI
+ * devDependency is used as a zero-configuration baseline.
  * Set DSH_TUI_EXPECTED_VERSION only when an explicit release baseline needs
  * to be pinned; ordinary development verifies the supplied host as-is.
  *
@@ -9,25 +10,32 @@
  */
 import { existsSync, mkdtempSync, readFileSync, readdirSync } from 'node:fs'
 import { tmpdir } from 'node:os'
-import { join, resolve } from 'node:path'
+import { dirname, join, resolve } from 'node:path'
 import { fileURLToPath, pathToFileURL } from 'node:url'
 import assert from 'node:assert/strict'
 import ts from 'typescript'
+import { createRequire } from 'node:module'
 
 const pluginRoot = fileURLToPath(new URL('..', import.meta.url))
 const sourceRoot = process.env.DSH_TUI_SOURCE_ROOT
-if (sourceRoot === undefined || sourceRoot === '') {
-  throw new Error('DSH_TUI_SOURCE_ROOT must point at a dsh-TUI source checkout for this host theme validation.')
-}
-const hostRoot = resolve(sourceRoot)
-const customThemePath = join(hostRoot, 'src', 'customTheme.ts')
-const themePath = join(hostRoot, 'src', 'theme.ts')
+const hostRequire = createRequire(import.meta.url)
+const devPackageJson = hostRequire.resolve('@deepseek-harness-tui/dsh-tui/package.json')
+const hostRoot = sourceRoot === undefined || sourceRoot === ''
+  ? dirname(devPackageJson)
+  : resolve(sourceRoot)
+const sourceMode = sourceRoot !== undefined && sourceRoot !== ''
+const customThemePath = sourceMode
+  ? join(hostRoot, 'src', 'customTheme.ts')
+  : join(hostRoot, 'lib', 'types', 'customTheme.js')
+const themePath = sourceMode
+  ? join(hostRoot, 'src', 'theme.ts')
+  : join(hostRoot, 'lib', 'types', 'theme.d.ts')
 
 if (!existsSync(customThemePath) || !existsSync(themePath)) {
-  throw new Error(`dsh-TUI sources not found at ${hostRoot}`)
+  throw new Error(`dsh-TUI ${sourceMode ? 'sources' : 'devDependency build'} not found at ${hostRoot}`)
 }
 
-const hostPackagePath = join(hostRoot, 'package.json')
+const hostPackagePath = sourceMode ? join(hostRoot, 'package.json') : devPackageJson
 if (!existsSync(hostPackagePath)) {
   throw new Error(`dsh-TUI package metadata not found at ${hostPackagePath}`)
 }
@@ -35,10 +43,10 @@ const hostPackage = JSON.parse(readFileSync(hostPackagePath, 'utf8'))
 assert.match(hostPackage.version, /^\d+\.\d+\.\d+(?:[-+].+)?$/u, 'host source must declare a version')
 
 const adapter = process.env.DSH_TUI_ADAPTER_DIR
-if (adapter === undefined || adapter === '') {
+if (sourceMode && (adapter === undefined || adapter === '')) {
   throw new Error('DSH_TUI_ADAPTER_DIR must point at dsh-TUI lib/types/dsh-adapter for this host theme validation.')
 }
-const adapterRoot = resolve(adapter)
+const adapterRoot = resolve(adapter || join(hostRoot, 'lib', 'types', 'dsh-adapter'))
 const runtimeThemePath = join(adapterRoot, '..', 'theme.js')
 const runtimeCustomThemePath = join(adapterRoot, '..', 'customTheme.js')
 if (!existsSync(runtimeThemePath) || !existsSync(runtimeCustomThemePath)) {
@@ -86,7 +94,7 @@ function readThemeKeysFromSource(path) {
   return keys
 }
 
-const allKeys = readThemeKeysFromSource(themePath)
+const allKeys = sourceMode ? readThemeKeysFromSource(themePath) : Object.keys(getTheme('dark'))
 assert.deepEqual(
   [...Object.keys(getTheme('dark'))].sort(),
   [...allKeys].sort(),

package/scripts/verify-package.mjs

@@ -40,6 +40,10 @@ for (const required of [
   'lib/types/statusLine.d.ts',
   'lib/types/themeAssets.js',
   'lib/types/themeAssets.d.ts',
+  'lib/types/runtimeThemes.js',
+  'lib/types/runtimeThemes.d.ts',
+  'lib/types/toast.js',
+  'lib/types/toast.d.ts',
   'themes/pink-night.json',
   'themes/pink-day.json',
   'themes/pink-ansi.json',
@@ -49,6 +53,7 @@ for (const required of [
   'scripts/verify.mjs',
   'scripts/verify-package.mjs',
   'scripts/headless-order-test.mjs',
+  'scripts/runtime-themes-headless.mjs',
   'scripts/validate-themes-against-host.mjs',
   'scripts/expected-settings-contract.mjs',
 ]) {
@@ -68,7 +73,15 @@ for (const entry of exportedPaths) {
 for (const name of Object.keys(packageJson.peerDependencies)) {
   if (!name.startsWith('@deepseek-ai/')) continue
   assert.equal(packageJson.dependencies?.[name], undefined, `${name} must not be a runtime dependency`)
-  assert.equal(packageJson.devDependencies?.[name], packageJson.peerDependencies[name], `${name} peer and dev ranges must match`)
+  const peerRange = packageJson.peerDependencies[name]
+  const devRange = packageJson.devDependencies?.[name]
+  // Development baselines may pin one concrete prerelease while the published
+  // peer contract remains a union of compatible release lines.
+  const devAccepted = peerRange.split('||').some(entry => {
+    const candidate = entry.trim()
+    return candidate === devRange || candidate.replace(/^\^/u, '') === devRange
+  })
+  assert.equal(devAccepted, true, `${name} dev pin must be accepted by its peer range`)
 }
 assert.equal(packageJson.dependencies?.['@deepseek-ai/schemastery'], undefined)
 const rootLock = lockfile.packages?.['']

package/scripts/verify.mjs

@@ -44,8 +44,9 @@ const builtinFs = require('node:fs')
 const sandboxThemes = join(sandboxHome, '.dsh-tui', 'themes')
 
 const { name, apply } = await import('../lib/types/index.js')
-const { installBundledThemes } = await import('../lib/types/themeAssets.js')
-const { startStatusLine } = await import('../lib/types/statusLine.js')
+const { installBundledThemes, readBundledThemes, findShadowedBundledThemes } = await import('../lib/types/themeAssets.js')
+const { startStatusLine, invalidateThemePrefCacheForTests } = await import('../lib/types/statusLine.js')
+const { setToastRetryDelaysForTests } = await import('../lib/types/toast.js')
 const {
   themeForBackground,
   readThemePref,
@@ -56,16 +57,27 @@ const {
 } = await import('../lib/types/autoTheme.js')
 
 assert.equal(name, 'dsh-tui-theme')
+const settle = () => new Promise(resolve => setTimeout(resolve, 0))
+const applyAndSettle = async (ctx, config) => {
+  apply(ctx, config)
+  await settle()
+}
 
 /** A stub Cordis-like context; every seam optional and recorded. */
-function makeStubCtx({ status, sections, settingsService } = {}) {
-  const record = { handlers: new Map(), disposers: [], statusCalls: [], sectionsCalls: [], registerCalls: [], watchers: [], warnings: [], infos: [] }
+function makeStubCtx({ status, sections, settingsService, themes, toast, deferThemes = false, deferToast = false } = {}) {
+  const record = { handlers: new Map(), disposers: [], statusCalls: [], sectionsCalls: [], registerCalls: [], watchers: [], themeRegisters: [], warnings: [], infos: [] }
+  let availableThemes = themes
+  let availableToast = toast
+  const deferredThemeCallbacks = []
+  const deferredToastCallbacks = []
   const logger = { info: msg => record.infos.push(String(msg)), warn: msg => record.warnings.push(String(msg)), error: () => {} }
   const base = {
     logger,
     get(serviceName) {
       if (serviceName === 'tuiStatus') return status
       if (serviceName === 'tuiSettingsSections') return sections
+      if (serviceName === 'tuiThemes') return availableThemes
+      if (serviceName === 'tuiToast') return availableToast
       return undefined
     },
     on(event, handler) {
@@ -85,6 +97,16 @@ function makeStubCtx({ status, sections, settingsService } = {}) {
         settings: settingsService,
         tuiStatus: status,
         tuiSettingsSections: sections,
+        tuiThemes: availableThemes,
+        tuiToast: availableToast,
+      }
+      if (deferThemes && availableThemes === undefined && deps.includes('tuiThemes')) {
+        deferredThemeCallbacks.push(callback)
+        return
+      }
+      if (deferToast && availableToast === undefined && deps.includes('tuiToast')) {
+        deferredToastCallbacks.push(callback)
+        return
       }
       if (deps.every(dep => services[dep] !== undefined)) {
         const props = Object.fromEntries(deps.map(dep => [dep, services[dep]]))
@@ -92,11 +114,26 @@ function makeStubCtx({ status, sections, settingsService } = {}) {
       }
     },
   }
+  record.activateThemes = service => {
+    availableThemes = service
+    for (const callback of deferredThemeCallbacks.splice(0)) callback({ ...base, tuiThemes: service })
+  }
+  record.activateToast = service => {
+    availableToast = service
+    for (const callback of deferredToastCallbacks.splice(0)) callback({ ...base, tuiToast: service })
+  }
   return { ctx: base, record }
 }
 
 const fakeStatus = calls => ({ set(key, text) { calls.push([key, text]); return () => {} } })
 const fakeSections = calls => ({ register(section) { calls.push(section); return () => {} } })
+const fakeThemes = (record, { throws = false } = {}) => ({
+  register(descriptor, identity) {
+    record.themeRegisters.push([descriptor, identity])
+    if (throws) throw new Error('runtime registry unavailable')
+    return () => {}
+  },
+})
 const fakeSettingsService = (record, doc) => ({
   register(namespace, schema) {
     record.registerCalls.push([namespace, schema])
@@ -106,6 +143,18 @@ const fakeSettingsService = (record, doc) => ({
     }
   },
 })
+/** Records delivered toasts; the first `dropFirst` shows are dropped (no sink yet). */
+const fakeToast = (deliveries, { dropFirst = 0 } = {}) => {
+  let shown = 0
+  return {
+    show(text, options) {
+      shown += 1
+      if (shown <= dropFirst) return false
+      deliveries.push([String(text), options?.color])
+      return true
+    },
+  }
+}
 
 const emit = (record, event, ...args) => {
   for (const handler of record.handlers.get(event) ?? []) handler(...args)
@@ -138,7 +187,7 @@ const emit = (record, event, ...args) => {
     sections: fakeSections(sectionsCalls),
     settingsService: fakeSettingsService(settingsRecord, {}),
   })
-  apply(ctx)
+  await applyAndSettle(ctx)
 
   // Themes installed into the SANDBOX, never the real home.
   for (const theme of ['pink-night', 'pink-day', 'pink-ansi']) {
@@ -176,8 +225,62 @@ const emit = (record, event, ...args) => {
   console.log('✓ full host: themes installed, status line live, settings wired')
 }
 
+// ── 2a. runtime themes: service owns palettes and static files stay absent ───
+{
+  rmSync(sandboxThemes, { recursive: true, force: true })
+  const registrations = []
+  const themes = { register(descriptor, identity) { registrations.push([descriptor, identity]); return () => {} } }
+  const { ctx } = makeStubCtx({ themes })
+  await applyAndSettle(ctx)
+  assert.equal(existsSync(sandboxThemes), false, 'runtime registration must not create static files')
+  const expected = readBundledThemes().map(({ file, ...theme }) => theme)
+  assert.deepEqual(registrations.map(([descriptor]) => descriptor), expected)
+  assert.equal(
+    registrations.every(([, identity]) => identity?.tuiThemes !== undefined),
+    true,
+    'runtime registrations use the inject-scoped identity',
+  )
+  console.log('✓ runtime themes: three descriptors registered without static files')
+}
+
+// ── 2b. late runtime service: confirmation removes this activation's files ──
+{
+  rmSync(sandboxThemes, { recursive: true, force: true })
+  const { ctx, record } = makeStubCtx({ deferThemes: true })
+  apply(ctx)
+  assert.equal(existsSync(sandboxThemes), true, 'legacy fallback must install synchronously before service arrival')
+  record.activateThemes(fakeThemes(record))
+  await settle()
+  assert.equal(existsSync(sandboxThemes), false, 'late runtime service must remove all fallback files and the empty directory')
+
+  rmSync(sandboxThemes, { recursive: true, force: true })
+  const protectedContext = makeStubCtx({ deferThemes: true })
+  apply(protectedContext.ctx)
+  assert.equal(existsSync(sandboxThemes), true, 'legacy fallback must install before protecting a user edit')
+  const protectedTheme = join(sandboxThemes, 'pink-night.json')
+  writeFileSync(protectedTheme, '{ "name": "pink-night", "colors": { "text": "#123456" } }')
+  protectedContext.record.activateThemes(fakeThemes(protectedContext.record))
+  await settle()
+  assert.equal(existsSync(join(sandboxThemes, 'pink-day.json')), false, 'late runtime service must remove plugin-owned files')
+  assert.equal(existsSync(join(sandboxThemes, 'pink-ansi.json')), false, 'late runtime service must remove plugin-owned files')
+  assert.equal(readFileSync(protectedTheme, 'utf8'), '{ "name": "pink-night", "colors": { "text": "#123456" } }')
+  rmSync(sandboxThemes, { recursive: true, force: true })
+  console.log('✓ runtime race: late service wins and removes static fallback files')
+}
+
+// ── 2c. hostile runtime service: registration failures degrade to warnings ───
+{
+  const themeRecord = { themeRegisters: [] }
+  const { ctx, record } = makeStubCtx({ themes: fakeThemes(themeRecord, { throws: true }) })
+  await applyAndSettle(ctx)
+  assert.equal(record.warnings.length, 3, 'each hostile registration is contained and warned')
+  console.log('✓ hostile runtime service: registration failures warn, never propagate')
+}
+
 // ── 3. idempotence + user-file protection ───────────────────────────────────
 {
+  const seeded = installBundledThemes()
+  assert.equal(seeded.installed.length, 3)
   const again = installBundledThemes()
   assert.deepEqual(again.installed, [])
   assert.deepEqual(again.repaired, [])
@@ -197,7 +300,7 @@ const emit = (record, event, ...args) => {
   rmSync(sandboxHome, { recursive: true, force: true })
   mkdirSync(sandboxHome, { recursive: true })
   const { ctx } = makeStubCtx()
-  apply(ctx, { autoInstallThemes: false })
+  await applyAndSettle(ctx, { autoInstallThemes: false })
   assert.equal(existsSync(join(sandboxHome, '.dsh-tui')), false, 'must not create the dir when disabled')
   console.log('✓ autoInstallThemes=false: leaves the themes dir untouched')
 }
@@ -218,15 +321,27 @@ const emit = (record, event, ...args) => {
   // Same value -> no rewrite churn (mtime-agnostic: pref already matches).
   assert.equal(applyCachedFollow(dataDir), 'pink-day')
 
-  // The follow runner only applies cache and reports its result. It accepts no
-  // stdin/stdout handles and cannot create a raw-mode lease or input listener.
-  const logs = []
-  runFollowSystem(dataDir, () => true, message => logs.push(message))
-  assert.deepEqual(logs, ['follow: applied cached background (pink-day)'])
+  // The follow runner only applies cache and reports its structured outcome.
+  // It accepts no stdin/stdout handles and cannot create a raw-mode lease or
+  // input listener.
+  const reports = []
+  runFollowSystem(dataDir, () => true, outcome => reports.push(outcome))
+  assert.deepEqual(reports, [{ kind: 'applied', theme: 'pink-day', changed: false }])
 
   writeFileSync(join(dataDir, 'theme.json'), JSON.stringify({ theme: 'dark' }, null, 2))
-  runFollowSystem(dataDir, () => false, message => logs.push(message))
+  runFollowSystem(dataDir, () => false, outcome => reports.push(outcome))
   assert.equal(readThemePref(dataDir), 'dark', 'inactive follow preserves manual choice')
+
+  runFollowSystem(dataDir, () => true, outcome => reports.push(outcome))
+  assert.deepEqual(
+    reports.at(-1),
+    { kind: 'applied', theme: 'pink-day', changed: true },
+    'a real pref flip is reported as changed',
+  )
+
+  rmSync(join(dataDir, 'theme-follow.json'), { force: true })
+  runFollowSystem(dataDir, () => true, outcome => reports.push(outcome))
+  assert.deepEqual(reports.at(-1), { kind: 'unavailable' })
   console.log('✓ follow: cached background applies without terminal I/O')
 }
 
@@ -234,7 +349,7 @@ const emit = (record, event, ...args) => {
 {
   const statusCalls = []
   const { ctx } = makeStubCtx({ status: fakeStatus(statusCalls) })
-  apply(ctx, { statusEnabled: false })
+  await applyAndSettle(ctx, { statusEnabled: false })
   assert.equal(statusCalls.length > 0, true, 'render still ran once')
   // Every contribution is cleared (undefined), not rendered.
   for (const [, text] of statusCalls) assert.equal(text, undefined)
@@ -252,7 +367,7 @@ const emit = (record, event, ...args) => {
     sections: fakeSections([]),
     settingsService: fakeSettingsService(settingsRecord, {}),
   })
-  apply(ctx, { followSystem: true })
+  await applyAndSettle(ctx, { followSystem: true })
   // Cordis layer on, empty user layer, no cache yet -> no pref churn.
   assert.equal(existsSync(join(dataDir, 'theme.json')), false)
 
@@ -277,15 +392,17 @@ const emit = (record, event, ...args) => {
     status: fakeStatus(statusCalls),
     settingsService: fakeSettingsService(settingsRecord, {}),
   })
-  apply(ctx)
+  await applyAndSettle(ctx)
   const session = { id: 'g1' }
 
   // Pink active → renders.
   emit(record, 'session/event', session, { type: 'turn/end' })
   assert.match(statusCalls.at(-1)[1], /^✿ · \d{2}:\d{2} · 1✦$/)
 
-  // Non-pink theme active → hidden by default.
+  // Non-pink theme active → hidden by default. The pref cache is dropped so
+  // the rewrite is visible immediately (production invalidation is the TTL).
   writeFileSync(themePrefPath, JSON.stringify({ theme: 'dark' }, null, 2))
+  invalidateThemePrefCacheForTests()
   emit(record, 'session/event', session, { type: 'turn/end' })
   assert.equal(statusCalls.at(-1)[1], undefined)
 
@@ -318,7 +435,7 @@ const emit = (record, event, ...args) => {
     register() { throw new Error('namespace already registered (hot reload)') },
   }
   const { ctx, record } = makeStubCtx({ settingsService: throwingSettings })
-  apply(ctx) // must not throw
+  await applyAndSettle(ctx) // must not throw
   assert.equal(record.warnings.length, 1, 'registration failure logs one warning')
   assert.match(record.warnings[0], /settings namespace registration failed/)
   console.log('✓ hostile settings service: registration failure warns, never propagates')
@@ -331,7 +448,7 @@ const emit = (record, event, ...args) => {
   writeFileSync(join(dataDir, 'theme.json'), JSON.stringify({ theme: 'dark' }, null, 2))
   writeFileSync(join(dataDir, 'theme-follow.json'), JSON.stringify({ light: true, at: 1 }))
   const { ctx } = makeStubCtx()
-  apply(ctx, { followSystem: true })
+  await applyAndSettle(ctx, { followSystem: true })
   assert.equal(readThemePref(dataDir), 'dark', 'without settings, cached follow must not override manual choice')
   console.log('✓ missing settings: cached follow leaves the manual choice intact')
 }
@@ -431,6 +548,27 @@ const emit = (record, event, ...args) => {
     builtinFs.readFileSync = originalRead
     syncBuiltinESMExports()
   }
+
+  // A successful backup followed by a failed replacement is a failure, not a
+  // protected skip: the target is absent until the next boot can retry.
+  const failedHeal = join(targetDir, 'pink-ansi.json')
+  writeFileSync(failedHeal, '{ broken')
+  const originalWrite = builtinFs.writeFileSync
+  try {
+    builtinFs.writeFileSync = (path, data, options) => {
+      if (String(path) === failedHeal && options?.flag === 'wx' && !existsSync(failedHeal)) {
+        throw new Error('ENOSPC: replacement blocked')
+      }
+      return originalWrite(path, data, options)
+    }
+    syncBuiltinESMExports()
+    const failed = installBundledThemes(targetDir, sourceDir)
+    assert.equal(failed.failed.includes('pink-ansi.json'), true)
+    assert.equal(failed.skipped.includes('pink-ansi.json'), false)
+  } finally {
+    builtinFs.writeFileSync = originalWrite
+    syncBuiltinESMExports()
+  }
   console.log('✓ torn installation: corrupt target backed up and reinstalled; user files and unreadable targets untouched')
 }
 
@@ -439,7 +577,7 @@ const emit = (record, event, ...args) => {
   // Default user layer (empty doc): no spurious "follow: disabled" line.
   const settingsRecord = { registerCalls: [], watchers: [] }
   const { ctx, record } = makeStubCtx({ settingsService: fakeSettingsService(settingsRecord, {}) })
-  apply(ctx)
+  await applyAndSettle(ctx)
   assert.equal(
     record.infos.some(message => message.includes('follow: disabled')),
     false,
@@ -455,7 +593,7 @@ const emit = (record, event, ...args) => {
     sections: fakeSections([]),
     settingsService: fakeSettingsService(enabledRecord, { followSystem: true }),
   })
-  apply(enabledCtx)
+  await applyAndSettle(enabledCtx)
   assert.equal(readThemePref(dataDir), 'pink-day', 'an enabled baseline applies the cached background')
   assert.equal(
     enabledInfo.infos.some(message => message.includes('follow: disabled')),
@@ -541,5 +679,243 @@ const emit = (record, event, ...args) => {
   console.log('✓ status lifecycle: session handlers follow tuiStatus activation')
 }
 
+// ── 13. toast feedback: the 0.10 seam surfaces what the logger cannot ───────
+{
+  setToastRetryDelaysForTests([5, 5])
+  const dataDir = join(sandboxHome, '.dsh-tui')
+  mkdirSync(dataDir, { recursive: true })
+
+  // 13a. Startup baseline with a disagreeing cache: one success toast that
+  // points at /reload (the live TUI still shows the previous palette). The
+  // tuiToast seam trails apply on a real host (extensions row), so the send
+  // must survive on the bounded retry until the seam shows up.
+  writeFileSync(join(dataDir, 'theme.json'), JSON.stringify({ theme: 'pink-night' }, null, 2))
+  writeFileSync(join(dataDir, 'theme-follow.json'), JSON.stringify({ light: true, at: 1 }))
+  const baselineDeliveries = []
+  const baselineRecord = { registerCalls: [], watchers: [] }
+  const baselineContext = makeStubCtx({
+    status: fakeStatus([]),
+    sections: fakeSections([]),
+    settingsService: fakeSettingsService(baselineRecord, { followSystem: true }),
+    deferToast: true,
+  })
+  await applyAndSettle(baselineContext.ctx)
+  assert.equal(readThemePref(dataDir), 'pink-day', 'the pref write is synchronous, independent of the toast seam')
+  baselineContext.record.activateToast(fakeToast(baselineDeliveries))
+  const baselineDeadline = Date.now() + 2_000
+  while (baselineDeliveries.length === 0 && Date.now() < baselineDeadline) {
+    await new Promise(resolve => setTimeout(resolve, 5))
+  }
+  assert.equal(baselineDeliveries.length, 1, 'a real baseline pref write toasts exactly once')
+  assert.equal(baselineDeliveries[0][1], 'success')
+  assert.match(baselineDeliveries[0][0], /pink-day/)
+  assert.match(baselineDeliveries[0][0], /reload/)
+
+  // 13b. Stable baseline (pref already matches the cache): quiet.
+  const quietDeliveries = []
+  const quietRecord = { registerCalls: [], watchers: [] }
+  const { ctx: quietCtx } = makeStubCtx({
+    status: fakeStatus([]),
+    sections: fakeSections([]),
+    settingsService: fakeSettingsService(quietRecord, { followSystem: true }),
+    toast: fakeToast(quietDeliveries),
+  })
+  await applyAndSettle(quietCtx)
+  assert.equal(quietDeliveries.length, 0, 'a baseline that changes nothing stays silent')
+
+  // 13c. Toggle confirmations: an explicit enable always answers — with the
+  // matching-cache confirmation, or the honest warning when nothing applies.
+  const toggleDeliveries = []
+  const toggleRecord = { registerCalls: [], watchers: [] }
+  const { ctx: toggleCtx } = makeStubCtx({
+    status: fakeStatus([]),
+    sections: fakeSections([]),
+    settingsService: fakeSettingsService(toggleRecord, {}),
+    toast: fakeToast(toggleDeliveries),
+  })
+  await applyAndSettle(toggleCtx)
+  for (const w of toggleRecord.watchers) w({ followSystem: true })
+  assert.equal(toggleDeliveries.length, 1, 'toggle-on with a matching cache confirms')
+  assert.equal(toggleDeliveries[0][1], 'success')
+  assert.equal(/reload/.test(toggleDeliveries[0][0]), false, 'no reload hint when nothing changed')
+  for (const w of toggleRecord.watchers) w({ followSystem: false })
+  rmSync(join(dataDir, 'theme-follow.json'), { force: true })
+  for (const w of toggleRecord.watchers) w({ followSystem: true })
+  assert.equal(toggleDeliveries.length, 2, 'toggle-on without a cache answers too')
+  assert.equal(toggleDeliveries[1][1], 'warning')
+
+  // 13d. A toast dropped before the host sink exists is retried until delivered.
+  const retryDeliveries = []
+  const retryRecord = { registerCalls: [], watchers: [] }
+  const { ctx: retryCtx } = makeStubCtx({
+    status: fakeStatus([]),
+    sections: fakeSections([]),
+    settingsService: fakeSettingsService(retryRecord, {}),
+    toast: fakeToast(retryDeliveries, { dropFirst: 1 }),
+  })
+  await applyAndSettle(retryCtx)
+  writeFileSync(join(dataDir, 'theme-follow.json'), JSON.stringify({ light: false, at: 1 }))
+  writeFileSync(join(dataDir, 'theme.json'), JSON.stringify({ theme: 'pink-day' }, null, 2))
+  for (const w of retryRecord.watchers) w({ followSystem: true })
+  const retryDeadline = Date.now() + 2_000
+  while (retryDeliveries.length === 0 && Date.now() < retryDeadline) {
+    await new Promise(resolve => setTimeout(resolve, 5))
+  }
+  assert.equal(retryDeliveries.length, 1, 'a dropped toast is retried and delivered')
+  assert.match(retryDeliveries[0][0], /pink-night/)
+
+  // 13e. Toast-seam-less host (dsh-TUI < 0.10): sends are silent no-ops and
+  // the follow feature itself is unchanged. The retry chain stays bounded:
+  // once it gives up, a seam arriving later must not resurrect the abandoned
+  // toast.
+  const legacyRecord = { registerCalls: [], watchers: [] }
+  const legacyContext = makeStubCtx({
+    status: fakeStatus([]),
+    sections: fakeSections([]),
+    settingsService: fakeSettingsService(legacyRecord, {}),
+    deferToast: true,
+  })
+  await applyAndSettle(legacyContext.ctx)
+  writeFileSync(join(dataDir, 'theme-follow.json'), JSON.stringify({ light: true, at: 1 }))
+  writeFileSync(join(dataDir, 'theme.json'), JSON.stringify({ theme: 'dark' }, null, 2))
+  for (const w of legacyRecord.watchers) w({ followSystem: true })
+  assert.equal(readThemePref(dataDir), 'pink-day', 'follow works unchanged without the toast seam')
+  await new Promise(resolve => setTimeout(resolve, 50)) // the [5, 5] chain is long exhausted
+  const lateDeliveries = []
+  legacyContext.record.activateToast(fakeToast(lateDeliveries))
+  await settle()
+  assert.equal(lateDeliveries.length, 0, 'an abandoned toast is not resurrected by a late seam')
+
+  // 13f. Shadow hint: legacy same-named files that are byte-identical to the
+  // bundled copy are pointed out once on runtime confirmation; user edits
+  // stay unmentioned. Files this activation installed itself are excluded
+  // (they were already removed before the check).
+  rmSync(sandboxThemes, { recursive: true, force: true })
+  mkdirSync(sandboxThemes, { recursive: true })
+  for (const theme of ['pink-night', 'pink-day', 'pink-ansi']) {
+    writeFileSync(join(sandboxThemes, `${theme}.json`), readFileSync(join(pluginRoot, 'themes', `${theme}.json`), 'utf8'))
+  }
+  assert.deepEqual(findShadowedBundledThemes().sort(), ['pink-ansi.json', 'pink-day.json', 'pink-night.json'])
+  const shadowDeliveries = []
+  const shadowContext = makeStubCtx({ deferThemes: true, toast: fakeToast(shadowDeliveries) })
+  apply(shadowContext.ctx)
+  shadowContext.record.activateThemes(fakeThemes(shadowContext.record))
+  await settle()
+  assert.equal(shadowDeliveries.length, 1, 'identical legacy files are pointed out once')
+  assert.equal(shadowDeliveries[0][1], undefined, 'the shadow hint is neutral, not an error')
+  assert.match(shadowDeliveries[0][0], /pink-day\.json/)
+
+  rmSync(sandboxThemes, { recursive: true, force: true })
+  installBundledThemes()
+  writeFileSync(join(sandboxThemes, 'pink-night.json'), '{ "name": "pink-night", "colors": { "text": "#123456" } }')
+  const editDeliveries = []
+  const editContext = makeStubCtx({ deferThemes: true, toast: fakeToast(editDeliveries) })
+  apply(editContext.ctx)
+  editContext.record.activateThemes(fakeThemes(editContext.record))
+  await settle()
+  assert.equal(editDeliveries.length, 1)
+  assert.equal(/pink-night\.json/.test(editDeliveries[0][0]), false, 'a user-edited file is never nagged')
+  assert.equal(/pink-day\.json/.test(editDeliveries[0][0]), true)
+
+  // 13g. Corrupt-file self-heal is surfaced as a warning toast. The toast
+  // seam trails apply on a real host, so the send waits on the retry chain.
+  rmSync(sandboxThemes, { recursive: true, force: true })
+  mkdirSync(sandboxThemes, { recursive: true })
+  writeFileSync(join(sandboxThemes, 'pink-day.json'), '{ broken')
+  const healDeliveries = []
+  const healContext = makeStubCtx({ deferThemes: true, deferToast: true })
+  apply(healContext.ctx)
+  healContext.record.activateToast(fakeToast(healDeliveries))
+  const healDeadline = Date.now() + 2_000
+  while (healDeliveries.length === 0 && Date.now() < healDeadline) {
+    await new Promise(resolve => setTimeout(resolve, 5))
+  }
+  assert.equal(healDeliveries.length, 1, 'a repaired theme file is surfaced')
+  assert.equal(healDeliveries[0][1], 'warning')
+  assert.match(healDeliveries[0][0], /pink-day\.json/)
+
+  rmSync(sandboxThemes, { recursive: true, force: true })
+  setToastRetryDelaysForTests([2_000, 4_000])
+  console.log('✓ toast feedback: follow/self-heal/shadow hints delivered, dropped and seam-less sends retried, legacy hosts silent and bounded')
+}
+
+// ── 14. hot path: the token firehose must not reach render or the disk ──────
+{
+  const themePrefPath = join(sandboxHome, '.dsh-tui', 'theme.json')
+  writeFileSync(themePrefPath, JSON.stringify({ theme: 'pink-night' }, null, 2))
+  // Earlier scenarios ran status activations against a different pref; drop
+  // their cached answer so this scenario starts from the fresh sandbox state.
+  invalidateThemePrefCacheForTests()
+  const statusCalls = []
+  const settingsRecord = { registerCalls: [], watchers: [] }
+  const { ctx, record } = makeStubCtx({
+    status: fakeStatus(statusCalls),
+    settingsService: fakeSettingsService(settingsRecord, {}),
+  })
+  await applyAndSettle(ctx)
+  const session = { id: 'h1' }
+  emit(record, 'session/event', session, { type: 'turn/end' })
+  const baselineCalls = statusCalls.length
+  assert.match(statusCalls.at(-1)[1], /1✦$/)
+
+  // A firehose burst (streaming chunks, tool traffic, step brackets) updates
+  // the tracked session but must render nothing and never touch the disk.
+  const originalRead = builtinFs.readFileSync
+  let prefReads = 0
+  try {
+    builtinFs.readFileSync = (path, ...rest) => {
+      if (String(path) === themePrefPath) prefReads += 1
+      return originalRead(path, ...rest)
+    }
+    syncBuiltinESMExports()
+    for (let index = 0; index < 50; index += 1) {
+      emit(record, 'session/event', session, {
+        type: 'assistant/chunk',
+        turn: 1,
+        step: 1,
+        chunk: { type: 'text', text: 'x' },
+      })
+    }
+    emit(record, 'session/event', session, {
+      type: 'tool/call', turn: 1, step: 1, callId: 'c1', name: 'tool', arguments: '{}',
+    })
+    emit(record, 'session/event', session, { type: 'step/end', turn: 1, step: 1 })
+    emit(record, 'session/event', session, { type: 'todo/write', todos: [] })
+    assert.equal(statusCalls.length, baselineCalls, 'firehose events render nothing')
+    assert.equal(prefReads, 0, 'firehose events never read the theme pref')
+
+    // A turn boundary renders — served by the warm pref cache (no disk hit
+    // within the TTL), so even boundary renders stay off the filesystem.
+    emit(record, 'session/event', session, { type: 'turn/end' })
+    assert.equal(statusCalls.length, baselineCalls + 1, 'a turn boundary renders')
+    assert.equal(prefReads, 0, 'the warm cache serves the boundary render')
+
+    // A session switch repaints at its first turn/start with a fresh count.
+    const nextSession = { id: 'h2' }
+    emit(record, 'session/event', nextSession, { type: 'turn/start' })
+    assert.equal(statusCalls.length, baselineCalls + 2)
+    assert.match(statusCalls.at(-1)[1], /0✦$/)
+    assert.equal(prefReads, 0)
+
+    // Inside the TTL a pref rewrite is not yet visible and costs no read…
+    writeFileSync(themePrefPath, JSON.stringify({ theme: 'dark' }, null, 2))
+    emit(record, 'session/event', nextSession, { type: 'turn/end' })
+    assert.equal(statusCalls.length, baselineCalls + 3)
+    assert.match(statusCalls.at(-1)[1], /1✦$/, 'the cached pink pref keeps the line visible')
+    assert.equal(prefReads, 0, 'the TTL serves the stale-but-pink answer without I/O')
+
+    // …after invalidation (TTL expiry in production) the next render re-reads.
+    invalidateThemePrefCacheForTests()
+    emit(record, 'session/event', nextSession, { type: 'turn/end' })
+    assert.equal(prefReads, 1, 'invalidation re-reads the pref exactly once')
+    assert.equal(statusCalls.at(-1)[1], undefined, 'the non-pink pref hides the line')
+  } finally {
+    builtinFs.readFileSync = originalRead
+    syncBuiltinESMExports()
+    invalidateThemePrefCacheForTests()
+  }
+  console.log('✓ hot path: firehose events render nothing and never read the pref; boundaries use the cache')
+}
+
 console.log('\nAll plugin verifications passed.')
 console.log(`(sandbox used: ${sandboxHome} — the real home was never touched)`)