@tduyng/pi-harness-loop 0.0.0-stage → 0.0.2

package/src/index.ts

@@ -0,0 +1,761 @@
+import { appendFileSync, existsSync, readFileSync } from 'node:fs'
+import { join, relative } from 'node:path'
+
+import {
+    formatSkillsForPrompt,
+    getAgentDir,
+    type ExtensionAPI,
+    type ExtensionContext
+} from '@earendil-works/pi-coding-agent'
+import { type Infer, Validator } from 'ata-validator'
+import { t } from 'ata-validator/t'
+
+
+import { revertApplied } from './apply.js'
+import {
+    budgetLeft,
+    fingerprintOf,
+    freshScan,
+    liveScan,
+    loopEnabled,
+    needsCode,
+    notify,
+    pendingTarget,
+    proposeToDisk,
+    readScan,
+    skillFacts,
+    toLive,
+    writeScan,
+    type LiveScan
+} from './auto.js'
+import { DEAD_SKILL_SESSIONS, scanCorpus, type PromptWords, type Recurrence, type SkillUse } from './corpus.js'
+import { findCollapse, proposalTexts, type Collapse } from './diversity.js'
+import { rate, type Effect } from './effect.js'
+import { evaluateInstalls, autoRevert } from './evaluate.js'
+import { findFindings, type Finding } from './findings.js'
+import { appendSpend, readSpend, spentToday, sumSpend, type SpendTotal } from './ledger.js'
+import { confirmOf, installContext, installProposal, installRoots, standingChars } from './install.js'
+import { goalInTheWay } from './coordination.js'
+import { lintManifest, type LintProblem } from './lint.js'
+import { matchLessons, rareTriggersOf, triggersOf } from './match.js'
+import { LESSON_TOOL, LessonParameters, MAX_LESSONS_SHOWN, formatLessons, matchedLessons } from './lesson-tool.js'
+
+type LessonParams = Infer<typeof LessonParameters>
+import { readProducers } from './producer.js'
+import { probeReplay } from './replay.js'
+import {
+    acquireLock,
+    appendInstall,
+    harnessDir,
+    readInstalls,
+    readLessons,
+    readSettings,
+    recordLesson,
+    recordLessonUse,
+    writeLessons
+} from './store.js'
+import { targetFromFinding, targetFromRecurrence, targetFromSkillUse, type Target } from './target.js'
+import { readTranscript, lastUserText } from './transcript.js'
+import { loadHarness, type Harness } from './tree.js'
+import { writePart, type Completion } from './writer.js'
+import type { Install, Lesson } from './types.js'
+
+const WIDGET_KEY = 'harness'
+const MAX_LINES = 20
+const WRITE_TIMEOUT_MS = 120_000
+
+function rarityOf(cwd: string): PromptWords | undefined {
+    const scan = readScan(cwd)
+    return scan === null ? undefined : toLive(scan).prompts
+}
+
+// The tool list is the front of every request, so the lesson tool is armed for a run only
+// when the request names a situation a lesson already covers.
+function armLessonTool(pi: ExtensionAPI, ctx: ExtensionContext, prompt: string): void {
+    const active = pi.getActiveTools()
+    const armed = prompt !== '' && matchedLessons(ctx.cwd, prompt, rarityOf(ctx.cwd)).length > 0
+    if (armed === active.includes(LESSON_TOOL)) return
+    pi.setActiveTools(armed ? [...active, LESSON_TOOL] : active.filter((name) => name !== LESSON_TOOL))
+}
+
+function supersededOnDisk(lessons: Lesson[], installs: Install[]): string[] {
+    return lessons
+        .filter((lesson) => lesson.state === 'superseded')
+        .flatMap((lesson) => {
+            const install = installs.find((entry) => entry.lesson === lesson.id && !entry.reverted)
+            if (install === undefined) return []
+            return [`${lesson.cue} is still in ${install.files.map((file) => file.to).join(', ')}`]
+        })
+}
+
+function reportLines(
+    harness: Harness,
+    findings: Finding[],
+    recurrences: Recurrence[],
+    lessons: string[],
+    stale: string[],
+    installs: Install[],
+    dead: string[],
+    spend: SpendTotal,
+    deadChars: number,
+    collapse: Collapse | null,
+    notAdvertised: number,
+    sessions: number,
+    available: number,
+    next: string,
+    effects: Effect[],
+    staleFindings: string[],
+    needsCodeFindings: Recurrence[]
+): string[] {
+    const lines: string[] = []
+    const active = installs.filter((install) => install.ok && !install.reverted)
+    const standing = standingChars(installs)
+    lines.push(
+        `skills ${harness.skills.length}, agents ${harness.agents.length}, skill block ${harness.skillBlockChars} chars, sessions ${sessions} of ${available}`
+    )
+    lines.push(
+        `installed ${active.length} active, ${installs.length - active.length} reverted, ${Math.round(standing / 4)} tokens of the prompt come from this loop`
+    )
+    if (harness.problems.length === 0) {
+        lines.push('tree: no problems')
+    } else {
+        lines.push(`tree: ${harness.problems.length} problems`)
+        for (const problem of harness.problems) lines.push(`  ${problem.rule} ${problem.entry}: ${problem.detail}`)
+    }
+    if (findings.length === 0) {
+        lines.push('findings: none')
+    } else {
+        lines.push(`findings: ${findings.length}`)
+        for (const finding of findings.slice(0, 3)) lines.push(`  ${finding.id} ${finding.title}`)
+    }
+    if (recurrences.length > 0) {
+        lines.push(`recurrences: ${recurrences.length}`)
+        for (const recurrence of recurrences.slice(0, 5)) lines.push(`  ${recurrence.id} ${recurrence.title}`)
+        if (recurrences.length > 5) lines.push(`  and ${recurrences.length - 5} more`)
+        const held = recurrences.filter((recurrence) => recurrence.blocked !== undefined).length
+        if (held > 0) lines.push(`held: ${held} failures whose sessions edited the same files`)
+    }
+    if (next !== '') lines.push(`the loop will propose: ${next}`)
+    if (notAdvertised > 0) {
+        lines.push(`not advertised: ${notAdvertised} skills, which cost nothing`)
+    }
+    if (dead.length > 0) {
+        const shown = dead.slice(0, 5).join(', ')
+        const more = dead.length > 5 ? ` and ${dead.length - 5} more` : ''
+        lines.push(`never opened in ${sessions} sessions: ${shown}${more} (propose skill-<name>)`)
+        lines.push(`dead advertisement: ${deadChars} of ${harness.skillBlockChars} chars`)
+    }
+    for (const lesson of lessons) lines.push(`lesson ${lesson}`)
+    for (const entry of stale) lines.push(`superseded ${entry}`)
+    if (installs.length > 0) {
+        const kept = installs.filter((install) => install.ok && !install.reverted).length
+        const confirmed = installs.filter((install) => install.confirmOk === true && !install.reverted).length
+        lines.push(
+            `installs: ${kept} kept, ${installs.length - kept} reverted${confirmed > 0 ? `, ${confirmed} confirmed` : ''}`
+        )
+    }
+    if (effects.length > 0) {
+        const held = effects.filter((effect) => effect.verdict === 'held').length
+        const failed = effects.filter((effect) => effect.verdict === 'flat' || effect.verdict === 'worse').length
+        const confounded = effects.filter((effect) => effect.verdict === 'confounded').length
+        const dodged = effects.filter((effect) => effect.verdict === 'avoided').length
+        lines.push(
+            `fixes: ${held} held, ${failed} did not, ${dodged} avoided the tool, ${confounded} confounded, ${effects.length - held - failed - confounded - dodged} too early to judge`
+        )
+        for (const effect of effects
+            .filter(
+                (entry) => entry.verdict === 'flat' || entry.verdict === 'worse' || entry.verdict === 'avoided'
+            )
+            .slice(0, 3)) {
+            lines.push(`  ${effect.finding} ${effect.verdict} ${rate(effect.before)} -> ${rate(effect.after)}`)
+        }
+    }
+    if (needsCodeFindings.length > 0) {
+        lines.push(
+            `needs code, because a prose part did not carry: ${needsCodeFindings
+                .slice(0, 3)
+                .map((recurrence) => recurrence.id)
+                .join(', ')}`
+        )
+    }
+    if (staleFindings.length > 0) {
+        lines.push(`stale findings, skipped: ${staleFindings.slice(0, 2).join(' | ')}`)
+    }
+    const total = spend
+    if (total.proposals > 0) {
+        lines.push(`loop: ${total.proposals} proposals, ${total.turns} turns, ${total.cost.toFixed(4)} cost`)
+    }
+    if (collapse !== null) {
+        lines.push(
+            `the loop repeats itself: ${collapse.pair[0]} and ${collapse.pair[1]} are ${Math.round(collapse.similarity * 100)}% the same`
+        )
+    }
+    if (lines.length > MAX_LINES) lines.push(`  ... ${lines.length - MAX_LINES} more`)
+    return lines.slice(0, MAX_LINES)
+}
+
+function pickTarget(
+    findings: Finding[],
+    recurrences: Recurrence[],
+    dead: SkillUse[],
+    skills: Map<string, { description: string; filePath: string }>,
+    id: string
+): Target | null {
+    if (id === '') {
+        const finding = findings[0]
+        if (finding !== undefined) return targetFromFinding(finding)
+        const recurrence = recurrences[0]
+        if (recurrence !== undefined) return targetFromRecurrence(recurrence)
+        const skill = dead[0]
+        if (skill === undefined) return null
+        const live = skills.get(skill.name)
+        return targetFromSkillUse(
+            skill,
+            live?.description ?? '',
+            live?.filePath ?? ''
+        )
+    }
+    const finding = findings.find((entry) => entry.id === id || entry.kind === id)
+    if (finding !== undefined) return targetFromFinding(finding)
+    const recurrence = recurrences.find((entry) => entry.id === id)
+    if (recurrence !== undefined) return targetFromRecurrence(recurrence)
+    const skill = dead.find((entry) => entry.id === id)
+    if (skill === undefined) return null
+    const live = skills.get(skill.name)
+    return targetFromSkillUse(
+        skill,
+        live?.description ?? '',
+        live?.filePath ?? ''
+    )
+}
+
+async function nextTarget(ctx: ExtensionContext): Promise<{ target: Target; scan: LiveScan } | null> {
+    const cwd = ctx.cwd
+    if (!loopEnabled()) return null
+    evaluateInstalls(cwd)
+    if (!readSettings(cwd).auto) return null
+    if (!budgetLeft(cwd)) return null
+    if (goalInTheWay(ctx.sessionManager.getBranch())) return null
+    const sessionDir = ctx.sessionManager.getSessionDir()
+    const sessionId = ctx.sessionManager.getSessionId()
+    const fingerprint = fingerprintOf(sessionDir, sessionId)
+    const cached = readScan(cwd)
+    const stale = cached === null || cached.fingerprint !== fingerprint
+    const skills = skillFacts(cwd, getAgentDir())
+    const scan = stale ? freshScan(cwd, getAgentDir(), sessionDir, sessionId, skills) : toLive(cached)
+    if (stale) writeScan(cwd, scan)
+    const target = pendingTarget(cwd, scan, skills)
+    if (target === null) return null
+    const recurrence = scan.recurrences.find((entry) => entry.id === target.id)
+    if (recurrence?.command !== undefined) {
+        const verdict = await probeReplay(cwd, recurrence)
+        if (verdict === 'stale') return null
+    }
+    return { target, scan }
+}
+
+interface DriveOutcome {
+    message: string
+    level: 'info' | 'warning'
+}
+
+type SelectedModel = NonNullable<ExtensionContext['model']>
+
+async function completeFor(
+    ctx: ExtensionContext,
+    model: SelectedModel,
+    systemPrompt: string,
+    prompt: string
+): Promise<Completion> {
+    const reply = await ctx.modelRegistry.complete(
+        model,
+        {
+            systemPrompt,
+            messages: [{ role: 'user', content: [{ type: 'text', text: prompt }], timestamp: Date.now() }]
+        },
+        { signal: AbortSignal.timeout(WRITE_TIMEOUT_MS), sessionId: ctx.sessionManager.getSessionId() }
+    )
+    return {
+        text: reply.errorMessage ?? reply.content.flatMap((block) => (block.type === 'text' ? [block.text] : [])).join('\n'),
+        stop: reply.stopReason,
+        input: reply.usage.input,
+        output: reply.usage.output,
+        cost: reply.usage.cost.total
+    }
+}
+
+/** The writer bills to the parent's session, and `/cost` reads this line to say so. */
+function recordOverhead(ctx: ExtensionContext, purpose: string, part: { input: number; output: number; cost: number }): void {
+    try {
+        appendFileSync(
+            join(getAgentDir(), 'overhead.jsonl'),
+            `${JSON.stringify({
+                at: Date.now(),
+                extension: 'harness-loop',
+                sessionId: ctx.sessionManager.getSessionId(),
+                purpose,
+                input: part.input,
+                output: part.output,
+                costUsd: part.cost
+            })}\n`,
+            'utf8'
+        )
+    } catch {}
+}
+
+function partText(dir: string): string {
+    for (const path of [join(dir, 'RULE.md'), join(dir, 'global', 'RULE.md')]) {
+        if (!existsSync(path)) continue
+        const line = readFileSync(path, 'utf8')
+            .split('\n')
+            .map((entry) => entry.trim())
+            .find((entry) => entry !== '' && !entry.startsWith('#'))
+        if (line !== undefined) return line
+    }
+    return ''
+}
+
+function partLesson(cwd: string, target: Target, dir: string, scan: LiveScan): Lesson | null {
+    const confirm = confirmOf(dir)
+    if (confirm === '') return null
+    const text = partText(dir)
+    return {
+        id: `${target.id}-${Date.now()}`,
+        at: Date.now(),
+        cue: target.cue,
+        lesson: text === '' ? `the part in ${relative(cwd, dir)} covers this situation` : text,
+        evidence: target.title,
+        confidence: 'medium',
+        triggers: rareTriggersOf(`${target.title} ${target.cue}`, scan.prompts),
+        kind: target.kind,
+        state: 'installed',
+        confirm
+    }
+}
+
+const SubagentConfig = t.object({ model: t.optional(t.string()) })
+const isSubagentConfig = new Validator(SubagentConfig).isValidObject
+
+/** The model pi already runs chores on, so the writer does not need a setting of its own. */
+export function subagentModel(cwd: string, agentDir: string): string {
+    for (const path of [join(cwd, '.pi', 'subagent.json'), join(agentDir, 'subagent.json')]) {
+        if (!existsSync(path)) continue
+        try {
+            const parsed: unknown = JSON.parse(readFileSync(path, 'utf8'))
+            if (!isSubagentConfig(parsed)) continue
+            const model = parsed.model?.trim() ?? ''
+            if (model !== '') return model
+        } catch {
+            continue
+        }
+    }
+    return ''
+}
+
+export function writerModelName(project: string, env: string, subagent: string): string {
+    if (project !== '') return project
+    if (env !== '') return env
+    return subagent
+}
+
+function writerModelFor(ctx: ExtensionContext): SelectedModel | undefined {
+    const configured = writerModelName(
+        readSettings(ctx.cwd).writerModel.trim(),
+        process.env['PI_HARNESS_WRITER_MODEL']?.trim() ?? '',
+        subagentModel(ctx.cwd, getAgentDir())
+    )
+    const slash = configured.indexOf('/')
+    if (slash < 1) return ctx.model
+    const found = ctx.modelRegistry.find(configured.slice(0, slash), configured.slice(slash + 1))
+    if (found === undefined || !ctx.modelRegistry.hasConfiguredAuth(found)) return ctx.model
+    return found
+}
+
+/** The whole loop for one finding: brief, part, install, record. A part nobody installs is a file. */
+async function drive(ctx: ExtensionContext, target: Target, scan: LiveScan): Promise<DriveOutcome> {
+    const dir = proposeToDisk(ctx.cwd, target, scan)
+    const model = ctx.model === undefined ? undefined : writerModelFor(ctx)
+    if (model === undefined) {
+        appendSpend(ctx.cwd, {
+            at: Date.now(),
+            target: target.id,
+            turns: 0,
+            input: 0,
+            output: 0,
+            cost: 0,
+            outcome: 'recorded'
+        })
+        return { message: `no model is selected, so the brief stays at ${dir}`, level: 'info' }
+    }
+    const brief = readFileSync(join(dir, 'BRIEF.md'), 'utf8')
+    const part = await writePart(dir, brief, (systemPrompt, prompt) => completeFor(ctx, model, systemPrompt, prompt))
+    recordOverhead(ctx, target.id, part)
+    const spend = {
+        at: Date.now(),
+        target: target.id,
+        turns: part.turns,
+        input: part.input,
+        output: part.output,
+        cost: part.cost
+    }
+    if (!part.ok) {
+        appendSpend(ctx.cwd, { ...spend, outcome: 'recorded' })
+        return {
+            message: `wrote no part for ${target.id} (${part.message}). The brief is at ${dir}`,
+            level: 'info'
+        }
+    }
+    const recurrence = scan.recurrences.find((entry) => entry.id === target.id)
+    const lesson = partLesson(ctx.cwd, target, dir, scan)
+    const outcome = await installProposal(dir, target.id, ctx.cwd, {
+        context: installContext(ctx.cwd, getAgentDir()),
+        key: recurrence?.key,
+        command: recurrence?.command,
+        lesson: lesson?.id
+    })
+    if (outcome.state === 'installed' && lesson !== null) recordLesson(ctx.cwd, lesson)
+    appendSpend(ctx.cwd, {
+        ...spend,
+        outcome: outcome.state === 'rejected' ? 'rejected' : outcome.state === 'installed' ? 'installed' : 'recorded'
+    })
+    return { message: `${outcome.message} (${target.id})`, level: outcome.state === 'rejected' ? 'warning' : 'info' }
+}
+
+export default function harnessExtension(pi: ExtensionAPI): void {
+    let scheduled = false
+
+    pi.on('before_agent_start', (event, ctx) => {
+        ctx.ui.setWidget(WIDGET_KEY, undefined)
+        armLessonTool(pi, ctx, event.messageType === 'user' ? (event.prompt ?? '') : '')
+    })
+
+    pi.registerCommand('harness-loop', {
+        description:
+            'Report what this session shows about the harness, propose a fix for one finding, install it when the check passes, revert an install, or clear the report.',
+        handler: async (args, ctx) => {
+            const cwd = ctx.cwd
+            const [command, id] = args.trim().split(/\s+/, 2)
+            if (command !== '') ctx.ui.setWidget(WIDGET_KEY, undefined)
+
+            if (command === 'clear') {
+                ctx.ui.notify('harness: report cleared, and the next prompt clears it too')
+                return
+            }
+
+            if (command === 'revert') {
+                const found = readInstalls(cwd)
+                    .toReversed()
+                    .find((install) => install.id === id)
+                if (found === undefined) {
+                    ctx.ui.notify(id ? `no install named ${id}` : 'name the install to revert', 'error')
+                    return
+                }
+                if (found.reverted) {
+                    ctx.ui.notify(`install ${found.id} is already reverted`, 'info')
+                    return
+                }
+                const release = acquireLock(cwd)
+                if (release === null) {
+                    ctx.ui.notify('another install is running, so this revert waits', 'warning')
+                    return
+                }
+                try {
+                    const result = revertApplied(found.files, installRoots(installContext(cwd, getAgentDir())))
+                    if (result.refused.length > 0) {
+                        ctx.ui.notify(
+                            `left ${result.refused.length} file(s) alone because they changed since the install: ${result.refused[0]}`,
+                            'warning'
+                        )
+                        return
+                    }
+                    appendInstall(cwd, { ...found, at: Date.now(), reverted: true })
+                    ctx.ui.notify(`reverted ${found.finding}: ${result.restored.length} file(s) restored`)
+                } finally {
+                    release()
+                }
+                return
+            }
+
+            if (command === 'install') {
+                if (id === undefined || id === '') {
+                    ctx.ui.notify('name the finding to install', 'error')
+                    return
+                }
+                const dir = join(harnessDir(cwd), id)
+                const recurrence = readScan(cwd)?.recurrences.find((entry) => entry.id === id)
+                const outcome = await installProposal(dir, id, cwd, {
+                    forced: true,
+                    context: installContext(cwd, getAgentDir()),
+                    key: recurrence?.key,
+                    command: recurrence?.command
+                })
+                ctx.ui.notify(outcome.message, outcome.state === 'rejected' ? 'warning' : 'info')
+                return
+            }
+
+            if (command === 'lint') {
+                const problems: LintProblem[] = [
+                    ...loadHarness(cwd, getAgentDir()).problems.map((problem) => ({
+                        rule: problem.rule,
+                        entry: problem.entry,
+                        detail: problem.detail
+                    })),
+                    ...lintManifest(cwd)
+                ]
+                ctx.ui.setWidget(
+                    WIDGET_KEY,
+                    problems.length === 0
+                        ? ['lint: no problems']
+                        : [
+                              `lint: ${problems.length} problems`,
+                              ...problems.map((problem) => `  ${problem.rule} ${problem.entry}: ${problem.detail}`)
+                          ]
+                )
+                ctx.ui.notify(
+                    problems.length === 0 ? 'lint: no problems' : `lint: ${problems.length} problems`,
+                    problems.length === 0 ? 'info' : 'warning'
+                )
+                return
+            }
+
+            if (command !== 'propose') {
+                const harness = loadHarness(cwd, getAgentDir())
+                const branch = ctx.sessionManager.getBranch()
+                const advertised = harness.skills.filter((skill) => !skill.disableModelInvocation)
+                const scan = scanCorpus(
+                    ctx.sessionManager.getSessionDir(),
+                    advertised.map((skill) => skill.name),
+                    join(cwd, '.pi', 'harness', 'corpus-cache.json')
+                )
+                const dead = scan.skills.filter((use) => use.opens === 0 && use.sessions >= DEAD_SKILL_SESSIONS)
+                const deadNames = new Set(dead.map((use) => use.name))
+                const deadChars =
+                    formatSkillsForPrompt(advertised).length -
+                    formatSkillsForPrompt(advertised.filter((skill) => !deadNames.has(skill.name))).length
+                const lessons = matchLessons(readLessons(cwd), lastUserText(branch))
+                    .slice(0, MAX_LESSONS_SHOWN)
+                    .map((lesson) => `${lesson.cue}: ${lesson.lesson}`)
+                const installs = readInstalls(cwd)
+                const stale = supersededOnDisk(readLessons(cwd), installs)
+                const effects = evaluateInstalls(cwd)
+                const needsCodeFindings = scan.recurrences.filter((recurrence) => needsCode(cwd, recurrence))
+                const staleFindings = readProducers(cwd)
+                    .filter((verdict) => verdict.state === 'removed')
+                    .map((verdict) => `${verdict.phrase} (${verdict.detail})`)
+                const pending = pendingTarget(
+                    cwd,
+                    liveScan(scan),
+                    harness.skills.map((skill) => ({
+                        name: skill.name,
+                        description: skill.description,
+                        filePath: skill.filePath,
+                        advertised: !skill.disableModelInvocation
+                    }))
+                )
+                ctx.ui.setWidget(
+                    WIDGET_KEY,
+                    reportLines(
+                        harness,
+                        findFindings(readTranscript(branch)),
+                        scan.recurrences,
+                        lessons,
+                        stale,
+                        installs,
+                        dead.map((use) => use.name),
+                        sumSpend(readSpend(cwd)),
+                        deadChars,
+                        findCollapse(proposalTexts(harnessDir(cwd))),
+                        harness.skills.length - advertised.length,
+                        scan.sessions,
+                        scan.available,
+                        pending?.title ?? '',
+                        effects,
+                        staleFindings,
+                        needsCodeFindings
+                    )
+                )
+                ctx.ui.notify(
+                    `harness: ${advertised.length} advertised skills, ${harness.skills.length - advertised.length} not advertised, ${harness.problems.length} problems, ${scan.recurrences.length} recurrences, ${lessons.length} lessons`
+                )
+                return
+            }
+
+            const harness = loadHarness(cwd, getAgentDir())
+            const advertised = harness.skills.filter((skill) => !skill.disableModelInvocation)
+            const scan = scanCorpus(
+                ctx.sessionManager.getSessionDir(),
+                advertised.map((skill) => skill.name),
+                join(cwd, '.pi', 'harness', 'corpus-cache.json')
+            )
+            const dead = scan.skills.filter((use) => use.opens === 0 && use.sessions >= DEAD_SKILL_SESSIONS)
+            const skills = new Map(
+                harness.skills.map((skill) => [
+                    skill.name,
+                    { description: skill.description, filePath: skill.filePath }
+                ])
+            )
+            const target = pickTarget(
+                findFindings(readTranscript(ctx.sessionManager.getBranch())),
+                scan.recurrences,
+                dead,
+                skills,
+                id ?? ''
+            )
+            if (target === null) {
+                ctx.ui.notify(id ? `no finding or recurrence named ${id}` : 'nothing to propose from', 'error')
+                return
+            }
+            if (goalInTheWay(ctx.sessionManager.getBranch())) {
+                ctx.ui.notify('a goal is active, and it drives the session too. Pause it first.', 'error')
+                return
+            }
+            const recurrence = scan.recurrences.find((entry) => entry.id === target.id)
+            if (recurrence !== undefined && needsCode(cwd, recurrence)) {
+                ctx.ui.notify(
+                    `a prose part already failed for ${target.id}, so the next fix has to live in the tool, not in a rule`,
+                    'warning'
+                )
+                return
+            }
+            if (recurrence?.command !== undefined) {
+                const verdict = await probeReplay(cwd, recurrence)
+                if (verdict === 'stale') {
+                    ctx.ui.notify(`the failure in ${target.id} no longer reproduces, so the finding is stale`, 'info')
+                    return
+                }
+            }
+            const settings = readSettings(cwd)
+            const today = spentToday(readSpend(cwd))
+            if (today.proposals >= settings.maxProposalsPerDay) {
+                ctx.ui.notify(
+                    `the loop spent its budget for today (${today.proposals} proposals, ${today.turns} turns)`,
+                    'warning'
+                )
+                return
+            }
+
+            const outcome = await drive(ctx, target, liveScan(scan))
+            ctx.ui.notify(`harness: ${outcome.message}`, outcome.level)
+        }
+    })
+
+    pi.registerTool({
+        name: LESSON_TOOL,
+        label: 'Lesson',
+        defaultActive: false,
+        description:
+            'Read the lessons this project learned from its own sessions, and record a new one. The lessons are what the past runs showed, kept in the shape of a situation rather than a task.',
+        promptSnippet: 'Lessons learned from earlier sessions in this project',
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+        exposure: 'direct',
+        namespace: {
+            name: 'harness',
+            description: 'The lessons earlier sessions in this project left behind.'
+        },
+        promptGuidelines: [
+            'When the request looks like one an earlier session in this project already hit, call lesson with action match and the request as the cue, before you start working.',
+            'A lesson is a shape of situation, not a task, so it applies to work that looks the same and is not the same.',
+            'Recall once per task, unless the task changes direction.'
+        ],
+        parameters: LessonParameters,
+        async execute(_toolCallId, params: LessonParams, _signal, _onUpdate, ctx) {
+            const cwd = ctx.cwd
+            if (params.action === 'match') {
+                const lessons = matchedLessons(cwd, params.cue ?? '', rarityOf(cwd))
+                for (const lesson of lessons) recordLessonUse(cwd, lesson.id)
+                return {
+                    content: [{ type: 'text', text: formatLessons(lessons) }],
+                    details: { matched: lessons.length }
+                }
+            }
+            if (params.action === 'list') {
+                const lessons = readLessons(cwd)
+                return {
+                    content: [{ type: 'text', text: formatLessons(lessons) }],
+                    details: { lessons: lessons.length }
+                }
+            }
+            if (params.action === 'record') {
+                if (
+                    params.cue === undefined ||
+                    params.lesson === undefined ||
+                    params.confirm === undefined ||
+                    params.evidence === undefined
+                ) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: 'a lesson needs a cue, a lesson, a way to confirm it and the evidence it rests on'
+                            }
+                        ],
+                        details: { recorded: false }
+                    }
+                }
+                const rarity = rarityOf(cwd)
+                const text = `${params.cue} ${params.lesson}`
+                const lesson: Lesson = {
+                    id: `manual-${Date.now()}`,
+                    at: Date.now(),
+                    cue: params.cue,
+                    lesson: params.lesson,
+                    confirm: params.confirm,
+                    evidence: params.evidence,
+                    confidence: params.confidence ?? 'medium',
+                    triggers: rarity === undefined ? triggersOf(text) : rareTriggersOf(text, rarity),
+                    kind: 'repeat-error',
+                    state: 'recorded'
+                }
+                const recorded = recordLesson(cwd, lesson)
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text:
+                                recorded.superseded === null
+                                    ? `recorded: ${lesson.cue}`
+                                    : `recorded: ${lesson.cue}, superseding ${recorded.superseded.cue}`
+                        }
+                    ],
+                    details: { recorded: true }
+                }
+            }
+            const lessons = readLessons(cwd)
+            const found = lessons.find((lesson) => lesson.id === params.id)
+            if (found === undefined) {
+                return {
+                    content: [{ type: 'text', text: `no lesson with the id ${params.id ?? ''}` }],
+                    details: { dropped: false }
+                }
+            }
+            const kept = lessons.filter((lesson) => lesson.id !== found.id)
+            writeLessons(cwd, kept)
+            return {
+                content: [{ type: 'text', text: `dropped: ${found.cue}` }],
+                details: { dropped: true }
+            }
+        }
+    })
+
+    pi.on('agent_settled', (event, ctx) => {
+        if (event.aborted || !ctx.isIdle() || scheduled) return
+        scheduled = true
+        setTimeout(async () => {
+            scheduled = false
+            try {
+                if (readInstalls(ctx.cwd).some((entry) => entry.ok && !entry.reverted)) {
+                    const context = installContext(ctx.cwd, getAgentDir())
+                    for (const line of autoRevert(ctx.cwd, context, evaluateInstalls(ctx.cwd))) {
+                        notify(ctx, line, 'info')
+                    }
+                }
+                const target = await nextTarget(ctx)
+                if (target === null) return
+                const outcome = await drive(ctx, target.target, target.scan)
+                notify(ctx, `harness: ${outcome.message}`, outcome.level)
+            } catch (error) {
+                notify(ctx, `the loop failed: ${error instanceof Error ? error.message : String(error)}`, 'warning')
+            }
+        }, 0)
+    })
+}