@tduyng/pi-timbre 0.0.0-stage → 0.0.2

package/src/index.ts

@@ -0,0 +1,695 @@
+import { closeSync, existsSync, globSync, openSync, readFileSync, readSync, statSync } from 'node:fs'
+import { isAbsolute, resolve } from 'node:path'
+import type { AssistantMessage, TextContent } from '@earendil-works/pi-ai'
+import {
+    BeforeAgentStartEvent,
+    BeforeAgentStartEventResult,
+    ExtensionAPI,
+    ExtensionContext,
+    isToolCallEventType,
+    MessageEndEvent,
+    ToolResultEvent
+} from '@earendil-works/pi-coding-agent'
+import { Validator } from 'ata-validator'
+import { t } from 'ata-validator/t'
+
+import { loadConfig, type Config } from './config.js'
+import {
+    type Domain,
+    type Effect,
+    appendNotice,
+    effect,
+    load,
+    memoryPath,
+    merge,
+    noticed,
+    record,
+    save,
+    type Memory,
+    type Settings
+} from './memory.js'
+
+import { GUIDE_TOOL_NAME, registerGuide } from './guide.js'
+import { classify, type Profile } from './register.js'
+import { codeCheckProblem, codePath, scanCodeBatch, type CodeFinding } from './code.js'
+import {
+    formatCodeFindings,
+    formatFindRequest,
+    formatFixRequest,
+    formatHits,
+    formatStats,
+    type FixTarget
+} from './report.js'
+import { catalogAvailable, generationRules } from './rules.js'
+import { aggregateSpans } from './segments.js'
+import { type Hit, isIgnored, proseLength, proseLineChars, scanProse } from './scan.js'
+import {
+    burstiness,
+    hasClauseStack,
+    hasLongSentenceRun,
+    hasStaccatoRun,
+    isMonotone,
+    repeatedOpening,
+    wordCount
+} from './stats.js'
+
+type AssistantContent = AssistantMessage['content']
+
+type ToolResultPatch = { content: ToolResultEvent['content'] }
+
+const PROSE_FILE = /\.(md|mdx|markdown|txt)$/i
+const PATH_TOKEN = /^@|[/\\]|\.[A-Za-z0-9]{1,8}$/
+const GLOB_TOKEN = /[*?[]/
+const GLOB_EXCLUDE = /(^|\/)(node_modules|\.git|dist|build|out|coverage|target|vendor|\.venv|\.next)(\/|$)/
+const MAX_FIX_FILES = 10
+const MAX_FIX_FILE_BYTES = 2 * 1024 * 1024
+const SUBCOMMANDS = ['on', 'off', 'fix', 'reset', 'stats', 'status']
+
+function setGuideTool(pi: ExtensionAPI, enabled: boolean): void {
+    const active = pi.getActiveTools()
+    if (active.length === 0) return
+    if (active.includes(GUIDE_TOOL_NAME) === enabled) return
+    pi.setActiveTools(enabled ? [...active, GUIDE_TOOL_NAME] : active.filter((name) => name !== GUIDE_TOOL_NAME))
+}
+
+const MIN_CHAT_PROSE = 40
+
+const DEFAULT_NOTE = ' (project default until changed again; next turn re-primes the cache)'
+
+export default function timbre(pi: ExtensionAPI): void {
+    const config = loadConfig()
+    if (!config.enabled) return
+
+    registerGuide(pi)
+
+    pi.on('session_start', (_event, ctx) => {
+        reportedCode.clear()
+        try {
+            const over = carriedOver(forProject(ctx.cwd), config)
+            if (over.length === 0) return
+            ctx.ui.notify(
+                `timbre: overrides from an earlier /timbre are still active — ${over.join(', ')}. Run /timbre to review, or /timbre reset to clear.`,
+                'info'
+            )
+        } catch {}
+    })
+
+    let preventing = config.prevent
+
+    let settingsReady = false
+
+    let turnPrevented = config.prevent
+    const preventedNow = (): boolean => turnPrevented
+
+    const touchedCode = new Set<string>()
+    const reportedCode = new Map<string, string>()
+    let noticesHeld = 0
+    const reportedNotes = new Set<string>()
+    let block: { path: string; text: string } | undefined
+
+    let cached: { path: string; memory: Memory; mtimeMs: number; size: number } | undefined
+    const stamp = (path: string) => {
+        const stat = statSync(path, { throwIfNoEntry: false })
+        return { mtimeMs: stat?.mtimeMs ?? 0, size: stat?.size ?? 0 }
+    }
+    const remember = (path: string, memory: Memory): void => {
+        cached = { path, memory, ...stamp(path) }
+    }
+    const forProject = (cwd: string): Memory => {
+        const path = memoryPath(cwd)
+        const now = stamp(path)
+        if (cached?.path === path && cached.mtimeMs === now.mtimeMs && cached.size === now.size) {
+            return cached.memory
+        }
+        const memory = load(path)
+        remember(path, memory)
+        return memory
+    }
+
+    const commit = (cwd: string, next: Memory): void => {
+        const path = memoryPath(cwd)
+        const merged = merge(forProject(cwd), next)
+        save(path, merged)
+        remember(path, merged)
+    }
+
+    const ensureSettings = (cwd: string): void => {
+        if (settingsReady) return
+        settingsReady = true
+        const mem = forProject(cwd)
+        if (mem.settings?.prevent !== undefined) preventing = mem.settings.prevent
+    }
+
+    const persistSettings = (cwd: string, settings: Settings): void => {
+        const path = memoryPath(cwd)
+        const mem = forProject(cwd)
+        const next: Memory = { ...mem, settings: { ...mem.settings, ...settings } }
+        save(path, next)
+        remember(path, next)
+    }
+
+    const healthWarnings = (): string[] => moduleHealthWarnings(config)
+
+    const statusText = (): string => (preventing ? 'on' : 'off')
+    const syncStatus = (ctx: ExtensionContext | undefined): void => {
+        try {
+            ctx?.ui?.setStatus?.('timbre', `timbre: ${statusText()}`)
+        } catch {}
+    }
+
+    pi.on('session_compact', () => {
+        reportedNotes.clear()
+    })
+
+    pi.on(
+        'before_agent_start',
+        (event: BeforeAgentStartEvent, ctx: ExtensionContext): BeforeAgentStartEventResult | undefined => {
+            try {
+                ensureSettings(ctx.cwd)
+            } catch {}
+            turnPrevented = preventing
+            syncStatus(ctx)
+            // Armed for the whole session: the tool list is the front of every request.
+            setGuideTool(pi, true)
+            if (!preventing) return undefined
+            try {
+                const path = memoryPath(ctx.cwd)
+                if (block?.path !== path) block = { path, text: generationRules() }
+                if (block.text === '') return undefined
+                const current = event.systemPromptOptions.appendSystemPrompt ?? ''
+                if (current.includes(block.text)) return undefined
+                event.systemPromptOptions.appendSystemPrompt = current ? `${current}\n\n${block.text}` : block.text
+                return undefined
+            } catch {
+                return undefined
+            }
+        }
+    )
+
+    pi.on('message_end', (event: MessageEndEvent, ctx: ExtensionContext): undefined => {
+        if (!config.watchChat) return undefined
+        try {
+            if (event.message.role !== 'assistant') return undefined
+            const text = textOf(event.message.content)
+            if (proseLength(text) < MIN_CHAT_PROSE) return undefined
+
+            const { hits, chars } = scanProse(text)
+            const memory = forProject(ctx.cwd)
+            commit(
+                ctx.cwd,
+                record(
+                    memory,
+                    hits.map((h) => h.id),
+                    {
+                        at: Date.now(),
+                        prevented: preventedNow(),
+                        domain: 'prose',
+                        chars,
+                        hits: hits.length,
+                        cacheRead: event.message.usage.cacheRead,
+                        cacheWrite: event.message.usage.cacheWrite
+                    }
+                )
+            )
+        } catch {}
+        return undefined
+    })
+
+    pi.on('tool_call', (event, ctx) => {
+        try {
+            const code = codePath(event, ctx.cwd)
+            if (code !== null) touchedCode.add(code)
+
+            let path: string
+            let text: string
+            if (isToolCallEventType('write', event)) {
+                path = event.input.path
+                text = event.input.content
+            } else if (isToolCallEventType('edit', event)) {
+                path = event.input.path
+                text = event.input.edits.map((e) => e.newText).join('\n\n')
+            } else {
+                return undefined
+            }
+            if (!PROSE_FILE.test(path) || text === '') return undefined
+
+            const head = readHeader(isAbsolute(path) ? path : resolve(ctx.cwd, path))
+            if (head !== null && isIgnored(head)) return undefined
+
+            // One notice per file per session. 86% of prose writes land on ten files, so
+            // most writes to a path have already been noticed in this session.
+            if (!preventing) return undefined
+            const session = ctx.sessionManager.getSessionId()
+            const memory = forProject(ctx.cwd)
+            if (noticed(memory, session, path)) {
+                noticesHeld += 1
+                return undefined
+            }
+            commit(ctx.cwd, appendNotice(memory, { at: Date.now(), session, path }))
+            return undefined
+        } catch {
+            return undefined
+        }
+    })
+
+    // One oxlint spawn per turn. The note prefers the model's next write or edit result, which is
+    // where it is unambiguous and free. A turn whose last act is a write would otherwise lose it,
+    // so what is left goes into the transcript as a custom_message entry: a `continue: true` would
+    // ask for a model request, and a follow-up message is the stale report this replaced.
+    pi.on('turn_end', async (_event, _ctx: ExtensionContext) => {
+        let codeNote: string | undefined
+        const paths = [...touchedCode]
+        touchedCode.clear()
+        if (paths.length > 0 && config.enabled) {
+            const findings = await scanCodeBatch(paths)
+            if (findings !== null) {
+                const fresh = freshFindings(findings, reportedCode)
+                // Overwrites whatever an earlier turn left undelivered, so a note can never
+                // outlive the turn whose code it describes.
+                if (fresh.length > 0) codeNote = formatCodeFindings(fresh)
+            }
+        }
+        /**
+         * The note goes into the session rather than out as a message: `continue: true` would
+         * ask for a model request, and a follow-up message is the stale report this replaced.
+         * An entry costs neither and keeps its own provenance.
+         */
+        if (codeNote === undefined) return undefined
+        return {
+            entries: [
+                { type: 'custom_message' as const, customType: 'timbre-code-note', content: codeNote, display: false }
+            ]
+        }
+    })
+
+    pi.on(
+        'tool_result',
+        async (event: ToolResultEvent, ctx: ExtensionContext): Promise<ToolResultPatch | undefined> => {
+            try {
+                const found = inspectProse(event, ctx.cwd)
+                if (found === null) return undefined
+
+                const { path, hits, chars, note: scannedNote, domain } = found
+
+                commit(
+                    ctx.cwd,
+                    record(
+                        forProject(ctx.cwd),
+                        hits.map((h) => h.id),
+                        { at: Date.now(), prevented: preventedNow(), domain, chars, hits: hits.length }
+                    )
+                )
+
+                const reportKey = `${ctx.sessionManager.getSessionId()}\n${path}\n${scannedNote}`
+                const repeat = scannedNote !== '' && reportedNotes.has(reportKey)
+                if (scannedNote !== '') reportedNotes.add(reportKey)
+                const parts = [scannedNote === '' || repeat ? undefined : scannedNote].filter(
+                    (part): part is string => part !== undefined
+                )
+                if (parts.length === 0) return undefined
+                return { content: [...event.content, { type: 'text' as const, text: parts.join('\n\n') }] }
+            } catch {
+                return undefined
+            }
+        }
+    )
+
+    const setPrevention = async (ctx: ExtensionContext, next: boolean): Promise<void> => {
+        preventing = next
+        persistSettings(ctx.cwd, { prevent: next })
+        syncStatus(ctx)
+        ctx.ui.notify(`timbre: prevention ${next ? 'on' : 'off'}${DEFAULT_NOTE}`, 'info')
+    }
+
+    pi.registerShortcut('ctrl+alt+t', {
+        description: 'Toggle timbre prevention',
+        handler: async (ctx) => {
+            try {
+                ensureSettings(ctx.cwd)
+            } catch {}
+            await setPrevention(ctx, !preventing)
+        }
+    })
+
+    pi.registerCommand('timbre', {
+        description: 'Prose prevention status, effect measurement, and on/off',
+        handler: async (args, ctx) => {
+            const raw = args.trim()
+            const arg = raw.toLowerCase()
+
+            if (arg === 'on' || arg === 'off') {
+                await setPrevention(ctx, arg === 'on')
+                return
+            }
+            const fixArgs = /^fix\b([\s\S]*)$/.exec(raw)
+            if (fixArgs) {
+                requestFix(pi, ctx, fixArgs[1]!.trim())
+                return
+            }
+            if (arg === 'reset') {
+                const ok = await ctx.ui.confirm('timbre', 'Discard all recorded samples for this project?')
+                if (ok) {
+                    const path = memoryPath(ctx.cwd)
+                    const cleared: Memory = { version: 1, samples: [] }
+                    save(path, cleared)
+                    remember(path, cleared)
+                    block = undefined
+                    preventing = config.prevent
+                    settingsReady = false
+                    syncStatus(ctx)
+                    ctx.ui.notify('timbre: memory cleared, live overrides reset to the env defaults', 'info')
+                }
+                return
+            }
+            if (arg !== '' && arg !== 'stats' && arg !== 'status') {
+                ctx.ui.notify(`timbre: no subcommand "${raw}". Try: ${SUBCOMMANDS.join(', ')}`, 'warning')
+                return
+            }
+
+            const memory = forProject(ctx.cwd)
+            const effects: Array<[Domain, Effect]> = [['prose', effect(memory, 'prose')]]
+            const stats = formatStats(memory, effects, preventing)
+            const provenance = configProvenance(memory, config)
+            const warnings = healthWarnings()
+            const body = [...provenance, '', stats].join('\n')
+            if (warnings.length === 0) {
+                ctx.ui.notify(body, 'info')
+            } else {
+                ctx.ui.notify(`${warnings.map((w) => `timbre: ${w}`).join('\n')}\n\n${body}`, 'warning')
+            }
+        },
+        getArgumentCompletions: (prefix) =>
+            SUBCOMMANDS.filter((c) => c.startsWith(prefix)).map((c) => ({ value: c, label: c }))
+    })
+}
+
+/**
+ * The oxlint paths are parameters so a test can force the fault, the same way `scanCodeBatch`
+ * takes them. A spawn whose config is missing returns null, which reads exactly like a clean
+ * file, so without this a code check that can never run is indistinguishable from one that does.
+ */
+export function moduleHealthWarnings(config: Config, bin?: string, rules?: string): string[] {
+    const warnings: string[] = []
+    if (!catalogAvailable())
+        warnings.push('rule catalog failed to load from disk; layer 0 is injecting nothing this session')
+    const codeProblem = codeCheckProblem(bin, rules)
+    if (codeProblem !== undefined) warnings.push(codeProblem)
+    return warnings
+}
+
+type Inspection = { path: string; hits: Hit[]; chars: number; note: string; domain: Domain }
+
+function inspectProse(event: ToolResultEvent, cwd: string): Inspection | null {
+    const path = prosePath(event, cwd)
+    if (path === null) return null
+    const text = writtenText(event)
+    if (text === null) return null
+
+    const head = readHeader(path)
+    if (head !== null && isIgnored(head)) return null
+
+    const profile = classify(path)
+    const { hits: scanned, chars } = scanProse(text)
+    const hits = [
+        ...(event.toolName === 'edit' ? scanned.filter((h) => h.id !== 'unclosed-fence') : scanned),
+        ...rhythmHits(text, profile)
+    ]
+    const note = formatHits(path, hits)
+    return { path, hits, chars, note: registerNote(note, profile.register), domain: 'prose' }
+}
+
+function scanDisk(path: string): FixTarget | { error: string } {
+    if (!PROSE_FILE.test(path)) return { error: `${path} is not a prose file (.md, .mdx, .markdown, .txt)` }
+
+    let text: string
+    try {
+        if (statSync(path).size > MAX_FIX_FILE_BYTES) return { error: `${path} is too large to scan safely` }
+        text = readFileSync(path, 'utf8')
+    } catch {
+        return { error: `${path} could not be read` }
+    }
+    if (isIgnored(text)) return { error: `${path} opts out with a lint-disable marker` }
+
+    const profile = classify(path)
+    const { hits } = scanProse(text)
+    const allHits = [...hits, ...rhythmHits(text, profile)]
+    const segments = aggregateSpans(proseLineChars(text), allHits)
+    return { path, register: profile.register, hits: allHits, segments }
+}
+
+function namesFile(token: string, cwd: string): boolean {
+    if (token.startsWith('@') || GLOB_TOKEN.test(token) || PROSE_FILE.test(token)) return true
+    if (!PATH_TOKEN.test(token)) return false
+    return existsSync(isAbsolute(token) ? token : resolve(cwd, token))
+}
+
+function expandGlob(pattern: string, cwd: string): string[] {
+    try {
+        return globSync(pattern.includes('/') ? pattern : `**/${pattern}`, {
+            cwd,
+            exclude: (match) => GLOB_EXCLUDE.test(match)
+        })
+            .filter((match) => PROSE_FILE.test(match))
+            .toSorted()
+            .map((match) => resolve(cwd, match))
+    } catch {
+        return []
+    }
+}
+
+function requestFix(pi: ExtensionAPI, ctx: ExtensionContext, raw: string): void {
+    const tokens = raw.split(/\s+/).filter((token) => token !== '')
+    const names = tokens.filter((token) => namesFile(token, ctx.cwd))
+    let rest = raw
+    for (;;) {
+        const token = /^(\S+)\s*/.exec(rest)
+        if (token === null || !namesFile(token[1]!, ctx.cwd)) break
+        rest = rest.slice(token[0].length)
+    }
+    const instruction = rest.trim()
+
+    const problems: string[] = []
+    const paths: string[] = []
+    for (const name of names) {
+        const cleaned = name.replace(/^@/, '')
+        if (GLOB_TOKEN.test(cleaned)) {
+            const matched = expandGlob(cleaned, ctx.cwd)
+            if (matched.length === 0) problems.push(`${cleaned} matches no prose file`)
+            paths.push(...matched)
+        } else paths.push(isAbsolute(cleaned) ? cleaned : resolve(ctx.cwd, cleaned))
+    }
+
+    const deliver = ctx.isIdle() ? undefined : ({ deliverAs: 'followUp' } as const)
+    const fullRules = generationRules()
+
+    if (paths.length === 0 && problems.length === 0) {
+        if (instruction === '') {
+            const usage = 'Usage: /timbre fix <path|glob> ... [instructions], as in /timbre fix *.md keep it short'
+            ctx.ui.notify(usage, 'warning')
+            return
+        }
+        pi.sendUserMessage(formatFindRequest(instruction, fullRules), deliver)
+        return
+    }
+
+    let targets: FixTarget[] = []
+    const clean: FixTarget[] = []
+    for (const path of new Set(paths)) {
+        const found = scanDisk(path)
+        if ('error' in found) problems.push(found.error)
+        else if (found.hits.length === 0) clean.push(found)
+        else targets.push(found)
+    }
+
+    if (targets.length === 0) {
+        if (clean.length > 0 && instruction !== '') {
+            if (problems.length > 0) ctx.ui.notify(`timbre: skipped\n  ${problems.join('\n  ')}`, 'warning')
+            pi.sendUserMessage(formatFixRequest(clean.slice(0, MAX_FIX_FILES), instruction, fullRules), deliver)
+            return
+        }
+        const cleanNote =
+            clean.length > 3
+                ? [`${clean.length} files scan clean, nothing to rewrite`]
+                : clean.map((file) => `${file.path} scans clean, nothing to rewrite`)
+        ctx.ui.notify(`timbre: ${[...problems, ...cleanNote].join('\n')}`, problems.length > 0 ? 'warning' : 'info')
+        return
+    }
+    if (targets.length > MAX_FIX_FILES) {
+        problems.push(
+            `${targets.length} files carry tells, rewriting the first ${MAX_FIX_FILES}. Run it again for the rest.`
+        )
+        targets = targets.slice(0, MAX_FIX_FILES)
+    }
+    if (problems.length > 0) ctx.ui.notify(`timbre: skipped\n  ${problems.join('\n  ')}`, 'warning')
+
+    pi.sendUserMessage(formatFixRequest(targets, instruction, fullRules), deliver)
+}
+
+const WriteArgs = t.object({ content: t.string() })
+const isWriteArgs = new Validator(WriteArgs).isValidObject
+const EditArgs = t.object({ edits: t.array(t.object({ newText: t.string() })) })
+const isEditArgs = new Validator(EditArgs).isValidObject
+
+function writtenText(event: Pick<ToolResultEvent, 'toolName' | 'input'>): string | null {
+    if (event.toolName === 'write' && isWriteArgs(event.input)) {
+        return event.input.content
+    }
+    if (event.toolName === 'edit' && isEditArgs(event.input)) {
+        return event.input.edits.map((e) => e.newText).join('\n\n')
+    }
+    return null
+}
+
+function rhythmHits(text: string, profile: Profile): Hit[] {
+    if (profile.terseIsCorrect) return []
+    const hits: Hit[] = []
+
+    const b = burstiness(text)
+    if (wordCount(text) >= 50 && isMonotone(b)) {
+        hits.push({
+            line: 0,
+            id: 'monotone-rhythm',
+            tier: 2,
+            hint: `Sentence lengths barely vary (${b.count} sentences, mean ${b.mean.toFixed(0)} words). Mix short and long.`,
+            text: ''
+        })
+    }
+    if (hasStaccatoRun(text)) {
+        hits.push({
+            line: 0,
+            id: 'staccato-run',
+            tier: 2,
+            hint: 'Four or more short sentences in a row. One is emphasis, a run is engineering.',
+            text: ''
+        })
+    }
+    const opening = repeatedOpening(text)
+    if (opening !== null) {
+        hits.push({
+            line: 0,
+            id: 'repeated-opening',
+            tier: 2,
+            hint: 'Three or more consecutive sentences open the same way. Merge sentences or vary the opening.',
+            text: opening
+        })
+    }
+    if (hasLongSentenceRun(text)) {
+        hits.push({
+            line: 0,
+            id: 'long-sentence-run',
+            tier: 2,
+            hint: 'Three or more long sentences in a row. Split one; one idea per sentence.',
+            text: ''
+        })
+    }
+    if (hasClauseStack(text)) {
+        hits.push({
+            line: 0,
+            id: 'clause-stack',
+            tier: 2,
+            hint: 'Several sentences stack three or more subordinate clauses. Split one; one clause, one idea.',
+            text: ''
+        })
+    }
+    if (text.split(/\s+/).filter((w) => w !== '').length >= 120 && !text.includes('\n\n')) {
+        hits.push({
+            line: 0,
+            id: 'wall-paragraph',
+            tier: 2,
+            hint: 'One paragraph carries the whole argument. Split it; short paragraphs are easier to read.',
+            text: ''
+        })
+    }
+    return hits
+}
+
+// Both sides key on `hit.path`: oxlint can answer with a relative path where the write recorded an
+// absolute one, and comparing those two bases made every lookup miss, so the check reported nothing.
+export function freshFindings(findings: CodeFinding[], reported: Map<string, string>): CodeFinding[] {
+    const signatures = new Map<string, string[]>()
+    for (const hit of findings) {
+        const rows = signatures.get(hit.path)
+        if (rows === undefined) signatures.set(hit.path, [`${hit.id}:${hit.line}`])
+        else rows.push(`${hit.id}:${hit.line}`)
+    }
+    const fresh: CodeFinding[] = []
+    for (const [path, rows] of signatures) {
+        const signature = rows.toSorted().join(',')
+        if (signature === reported.get(path)) continue
+        reported.set(path, signature)
+        fresh.push(...findings.filter((hit) => hit.path === path))
+    }
+    return fresh
+}
+
+export function prosePath(event: Pick<ToolResultEvent, 'toolName' | 'isError' | 'input'>, cwd: string): string | null {
+    if (event.isError) return null
+    if (event.toolName !== 'write' && event.toolName !== 'edit') return null
+    const path = String(event.input['path'] ?? '')
+    if (!PROSE_FILE.test(path)) return null
+    return isAbsolute(path) ? path : resolve(cwd, path)
+}
+
+export function textOf(content: AssistantContent): string {
+    return content
+        .filter((block): block is TextContent => block.type === 'text')
+        .map((block) => block.text)
+        .join('\n\n')
+}
+
+function registerNote(note: string, register: string): string {
+    if (register === 'reference' || register === 'changelog') {
+        return `${note}\nRegister is ${register}: terse and plain is correct here, do not add voice.`
+    }
+    return note
+}
+
+function readHeader(path: string, bytes = 1600): string | null {
+    let fd: number | undefined
+    try {
+        fd = openSync(path, 'r')
+        const buf = Buffer.alloc(bytes)
+        const n = readSync(fd, buf, 0, bytes, 0)
+        return buf.toString('utf8', 0, n)
+    } catch {
+        return null
+    } finally {
+        if (fd !== undefined) closeSync(fd)
+    }
+}
+
+type FieldInfo = {
+    name: string
+    envName: string
+    envValue: boolean
+    file?: boolean
+    active: boolean
+    carried: boolean
+}
+
+function settingFields(memory: Memory, config: Config): FieldInfo[] {
+    const set = memory.settings ?? {}
+    const mk = (name: string, envName: string, envValue: boolean, file: boolean | undefined): FieldInfo => {
+        const active = file !== undefined ? file : envValue
+        return { name, envName, envValue, file, active, carried: file !== undefined && file !== envValue }
+    }
+    return [mk('prevent', 'TIMBRE_PREVENT', config.prevent, set.prevent)]
+}
+
+function activeLabel(f: FieldInfo): string {
+    return f.active ? 'on' : 'off'
+}
+
+export function configProvenance(memory: Memory, config: Config): string[] {
+    return settingFields(memory, config).map((f) => {
+        const source = `· ${f.file !== undefined ? 'state file' : `env ${f.envName}`}`.padEnd(34)
+        const mark = f.carried ? '⚠ carried over' : ''
+        return `  ${f.name.padEnd(9)}${activeLabel(f).padEnd(11)}${source}${mark}`
+    })
+}
+
+export function carriedOver(memory: Memory, config: Config): string[] {
+    return settingFields(memory, config)
+        .filter((f) => f.carried)
+        .map((f) => `${f.name} ${activeLabel(f)}`)
+}