@luuthuong/devboard 0.0.0-stage → 1.0.1

package/server-dist/server/harness/service.js

@@ -0,0 +1,683 @@
+// The knowledge harness on the shared server: owns the clone of the private
+// harness repo, the index, the proposal queue, the librarian and the AI-DLC
+// intents. Commands and pollers call into this one object.
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseDocument } from "yaml";
+import { defaultHarnessSettings } from "../settings.js";
+import { Mutex, devboardDataDir, errorMessage, log, readLines, run, writeFileAtomic } from "../util.js";
+import { CONFIG_FILE, emptyConfig, findProject, ownerRepo, readConfig, repoIdentity, serializeConfig, slugify, } from "./config.js";
+import { ENTRY_SCHEMA_VERSION, entryFileName, isoDay, newEntryId, serializeEntry } from "./entry.js";
+import { IntentStore } from "./intents.js";
+import { KbIndex, formatContext, scopeSpecificity } from "./kbIndex.js";
+import { LIBRARIAN_PROMPT_HEAD, projectMaterial, runLibrarian, transcriptTail } from "./librarian.js";
+import { HOOK_SCRIPT_NAME, buildBundle, hookScriptContent, installHook, linkPack } from "./pack.js";
+import { ProposalStore } from "./proposals.js";
+import { ensureClone, expandHome, fileChangeTimes, isGitRepo, proposeChange, pull, retractChange } from "./repo.js";
+import { InjectionLog, UsageStats } from "./usage.js";
+export const PERSONAL_KB = "personal";
+/** Default routing for every session in a registered project: which harness skill or subagent fits which work. */
+const WORKFLOW_HINT = [
+    "Team workflow (harness). Pick what fits the task; skip it for small questions and read-only lookups.",
+    "- New feature or non-trivial change: use the `aidlc-requirements`, `aidlc-design` and `aidlc-implement` skills in that order, skipping stages the prompt already settles.",
+    "- Before committing code you wrote: run the `code-reviewer` subagent on the diff and fix what it finds.",
+    "- Changes touching auth, input parsing, file paths, process execution, network endpoints or secrets: also run `security-reviewer`.",
+    "- Tests for an approved design: use the `test-writer` subagent.",
+    "- Code is done and checks pass: use `aidlc-pr`. After an incident fix: use `aidlc-postmortem`.",
+    "- Something broke in a surprising way, or you learned a convention or gotcha: use the `project-kb` skill.",
+].join("\n");
+const TEMPLATE_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), "template");
+const IDENTITY_TTL_MS = 60_000;
+/** Re-distill a session only once its transcript grew this much. */
+const DISTILL_MIN_GROWTH = 20_000;
+export class HarnessService {
+    opts;
+    index;
+    proposals;
+    intents;
+    usage;
+    injections;
+    dataDir;
+    config = emptyConfig();
+    repoPath;
+    lastPull;
+    lastError;
+    librarianLock = new Mutex();
+    reloadLock = new Mutex();
+    identityCache = new Map();
+    /** Onboarding pull requests opened by this process and not merged yet, by repo root. */
+    pendingOnboards = new Map();
+    constructor(opts) {
+        this.opts = opts;
+        this.dataDir = opts.dataDir ?? devboardDataDir();
+        this.index = new KbIndex(path.join(this.dataDir, "kb-index"));
+        this.proposals = new ProposalStore(this.dataDir);
+        this.intents = new IntentStore(this.dataDir);
+        this.usage = new UsageStats(this.dataDir);
+        this.injections = new InjectionLog(this.dataDir);
+    }
+    async settings() {
+        const s = await this.opts.settings.read().catch(() => null);
+        const h = s?.harness;
+        const d = defaultHarnessSettings();
+        return { ...d, ...h, librarian: { ...d.librarian, ...h?.librarian } };
+    }
+    get configured() {
+        return !!this.repoPath;
+    }
+    /** Re-read settings and harness.json, and rebuild the index. Safe to call often. */
+    reload() {
+        return this.reloadLock.run(async () => {
+            const s = await this.settings();
+            this.lastError = undefined;
+            if (!s.repoPath) {
+                this.repoPath = undefined;
+                this.config = emptyConfig();
+                this.index.setSources([this.personalSource()]);
+                await this.index.reindex();
+                return;
+            }
+            try {
+                const repoPath = expandHome(s.repoPath);
+                await ensureClone(repoPath, s.gitUrl);
+                this.repoPath = repoPath;
+                this.config = readConfig(repoPath);
+            }
+            catch (e) {
+                this.lastError = errorMessage(e);
+                log.warn("harness", `reload failed: ${this.lastError}`);
+                this.repoPath = undefined;
+                this.config = emptyConfig();
+            }
+            const repo = this.repoPath;
+            const sources = [this.personalSource()];
+            if (repo) {
+                for (const kb of this.config.kbs) {
+                    sources.push({ id: kb.id, root: path.join(repo, kb.path), weight: kb.weight ?? 1, covers: kb.covers ?? [] });
+                }
+            }
+            this.index.setSources(sources);
+            const changed = await this.index.reindex();
+            this.index.setUsefulness(await this.usage.multipliers());
+            if (changed)
+                log.info("harness", `indexed ${changed} changed entr${changed === 1 ? "y" : "ies"}`);
+        });
+    }
+    personalSource() {
+        // Personal notes rank below the team's and only come from this machine.
+        return { id: PERSONAL_KB, root: path.join(this.dataDir, "kb"), weight: 0.5, covers: [] };
+    }
+    /** `git pull` the harness repo and reindex when it moved. */
+    async sync() {
+        if (!this.repoPath)
+            return false;
+        try {
+            const moved = await pull(this.repoPath);
+            this.lastPull = new Date().toISOString();
+            if (moved) {
+                await this.reload();
+                await this.installPack().catch((e) => log.warn("harness", `pack install failed: ${errorMessage(e)}`));
+            }
+            return moved;
+        }
+        catch (e) {
+            this.lastError = errorMessage(e);
+            log.warn("harness", `pull failed: ${this.lastError}`);
+            return false;
+        }
+    }
+    async status() {
+        return {
+            configured: this.configured,
+            repoPath: this.repoPath,
+            kbs: this.index.listSources().map((s) => ({
+                id: s.id,
+                root: s.root,
+                entries: this.index.count(s.id),
+                stale: this.index.all(s.id).filter((e) => this.index.isStale(e.id)).length,
+            })),
+            projects: this.config.projects.map((p) => ({ id: p.id, kbId: p.kbId, name: p.name })),
+            pendingProposals: (await this.proposals.list("pending")).length,
+            lastPull: this.lastPull,
+            indexStore: this.index.storeKind(),
+            error: this.lastError,
+        };
+    }
+    // ── Setup ──────────────────────────────────────────────────────────────────
+    /** Create a new harness repo from the bundled template (an empty or missing folder only). */
+    async initRepo(repoPath) {
+        const target = path.resolve(expandHome(repoPath));
+        const existing = await fs.promises.readdir(target).catch(() => []);
+        if (existing.some((f) => f !== ".git"))
+            throw new Error(`${target} is not empty`);
+        await fs.promises.mkdir(target, { recursive: true });
+        await fs.promises.cp(TEMPLATE_DIR, target, { recursive: true });
+        if (!(await isGitRepo(target)))
+            await run("git", ["init", "-q", "-b", "main"], { cwd: target });
+        await run("git", ["add", "-A"], { cwd: target });
+        await run("git", [
+            "-c",
+            "user.name=DevBoard",
+            "-c",
+            "user.email=devboard@localhost",
+            "commit",
+            "-q",
+            "-m",
+            "chore: create harness",
+        ], { cwd: target });
+        const files = (await run("git", ["ls-files"], { cwd: target })).stdout.split("\n").filter(Boolean);
+        return { repoPath: target, files };
+    }
+    /** Link skills and subagents into ~/.claude, install the SessionStart hook, link agents.yaml. */
+    async installPack() {
+        if (!this.repoPath)
+            throw new Error("no harness repo configured");
+        const { linked, skipped } = await linkPack(this.repoPath);
+        const hook = await installHook(this.dataDir, this.opts.serverUrl, this.opts.token);
+        const agentsLink = path.join(this.dataDir, "agents.yaml");
+        if (!fs.existsSync(agentsLink) && fs.existsSync(path.join(this.repoPath, "agents.yaml"))) {
+            const src = path.join(this.repoPath, "agents.yaml");
+            // Windows file symlinks need admin or Developer Mode; fall back to a copy.
+            await fs.promises
+                .symlink(src, agentsLink)
+                .catch(() => fs.promises
+                .copyFile(src, agentsLink)
+                .catch((e) => log.warn("harness", `agents.yaml link failed: ${errorMessage(e)}`)));
+        }
+        return { linked, skipped, hook };
+    }
+    /** Skills, subagents and a hook script, for `devboard harness install` on a member machine. */
+    async bundle(serverUrl) {
+        if (!this.repoPath)
+            throw new Error("no harness repo configured");
+        const version = (await run("git", ["rev-parse", "--short", "HEAD"], { cwd: this.repoPath })).stdout.trim();
+        // The member's own token is filled in by the CLI; it is never sent back here.
+        return { ...(await buildBundle(this.repoPath, version)), hookScript: hookScriptContent(serverUrl, undefined) };
+    }
+    hookScriptName() {
+        return HOOK_SCRIPT_NAME;
+    }
+    // ── Projects ───────────────────────────────────────────────────────────────
+    /** The repo `dir` belongs to and its harness project. Repo identity is cached for a minute (it costs two git calls). */
+    async projectFor(dir) {
+        const key = path.resolve(dir);
+        const hit = this.identityCache.get(key);
+        let id;
+        if (hit && Date.now() - hit.at < IDENTITY_TTL_MS) {
+            id = hit.id;
+        }
+        else {
+            id = await repoIdentity(dir);
+            this.identityCache.set(key, { id, at: Date.now() });
+            if (this.identityCache.size > 500)
+                this.identityCache.delete(this.identityCache.keys().next().value);
+        }
+        if (!id)
+            return null;
+        return { id, project: findProject(this.config, id) };
+    }
+    async projectCommands(cwd) {
+        const p = await this.projectFor(cwd);
+        return { project: p?.project?.id, ...(p?.project?.commands ?? {}) };
+    }
+    /**
+     * Register a project: harness.json entry, kb/<id>/, the long-lived agents'
+     * repo lists — one pull request — then a bootstrap librarian pass.
+     */
+    async onboard(projectPath, commands) {
+        const repo = this.repoPath;
+        if (!repo)
+            throw new Error("no harness repo configured");
+        const found = await this.projectFor(projectPath);
+        if (!found)
+            throw new Error(`${projectPath} is not a git repository`);
+        if (found.project)
+            return { project: found.project, mode: "none", alreadyRegistered: true };
+        // Its pull request is open but not merged yet: do not open a second one.
+        const pending = this.pendingOnboards.get(found.id.root);
+        if (pending)
+            return pending;
+        const id = slugify(found.id.name);
+        const kbId = this.config.kbs.some((k) => k.id === id) ? `${id}-${Date.now().toString(36)}` : id;
+        const project = {
+            id: kbId,
+            name: found.id.name,
+            remote: found.id.remote,
+            kbId,
+            commands: commands && Object.values(commands).some(Boolean) ? commands : undefined,
+        };
+        const result = await proposeChange(repo, {
+            branch: `onboard/${kbId}`,
+            message: `feat: add project ${found.id.name}`,
+            prTitle: `Add project ${found.id.name} to the harness`,
+            prBody: [
+                `Registers \`${found.id.remote ?? found.id.name}\` with the knowledge harness:`,
+                "",
+                `- \`harness.json\`: project \`${kbId}\` with its own knowledge base \`kb/${kbId}/\``,
+                "- `agents.yaml`: the librarian, triage and ops-watcher agents now watch it",
+                "",
+                "Bootstrap proposals from the project's docs wait for review on the board.",
+            ].join("\n"),
+        }, async (dir) => {
+            const config = readConfig(dir);
+            if (!config.kbs.some((k) => k.id === kbId))
+                config.kbs.push({ id: kbId, path: `kb/${kbId}` });
+            config.projects.push(project);
+            await fs.promises.writeFile(path.join(dir, CONFIG_FILE), serializeConfig(config));
+            await fs.promises.mkdir(path.join(dir, "kb", kbId), { recursive: true });
+            await fs.promises.writeFile(path.join(dir, "kb", kbId, "README.md"), `# ${found.id.name}\n\nKnowledge for \`${found.id.remote ?? found.id.name}\`.\n`);
+            await addRepoToAgents(path.join(dir, "agents.yaml"), ownerRepo(found.id.remote));
+        });
+        const out = { project, url: result.url, mode: result.mode, alreadyRegistered: false };
+        if (result.mode === "local")
+            await this.reload();
+        else
+            this.pendingOnboards.set(found.id.root, out);
+        // Bootstrap in the background: it can take minutes.
+        void this.bootstrap(found.id.root, kbId, found.id.name).catch((e) => log.warn("librarian", `bootstrap failed: ${errorMessage(e)}`));
+        return out;
+    }
+    bootstrap(root, kbId, name) {
+        return this.librarianLock.run(async () => {
+            const s = await this.settings();
+            if (!s.librarian.enabled)
+                return [];
+            const material = await projectMaterial(root, s.librarian.maxTranscriptChars);
+            if (!material.trim())
+                return [];
+            const drafts = await runLibrarian({ mode: "bootstrap", project: name, material, existingTitles: this.index.all(kbId).map((e) => e.title) }, s.librarian.model, root);
+            return this.proposals.add(drafts.map((d) => ({ ...d, kbId, origin: "bootstrap" })));
+        });
+    }
+    // ── Retrieval ──────────────────────────────────────────────────────────────
+    search(q) {
+        return this.index.search(q);
+    }
+    /** Search in the context of a checkout: its project's KB is always included. */
+    async searchFrom(cwd, q) {
+        if (q.onlyKbs?.length)
+            return this.index.search({ ...q, kbIds: q.onlyKbs });
+        const kbIds = new Set(q.kbIds ?? []);
+        kbIds.add(PERSONAL_KB);
+        if (cwd) {
+            const p = await this.projectFor(cwd);
+            if (p?.project)
+                kbIds.add(p.project.kbId);
+        }
+        return this.index.search({ ...q, kbIds: [...kbIds] });
+    }
+    async show(id) {
+        const e = this.index.get(id);
+        if (!e)
+            throw new Error(`entry ${id} not found`);
+        await this.usage.record([id], "shown");
+        return e;
+    }
+    /**
+     * SessionStart hook: the entries most relevant to this session, as hook
+     * output. Unregistered projects get `{}` so the hook is a no-op there.
+     */
+    async sessionContext(args) {
+        const cwd = args.cwd;
+        if (!cwd)
+            return {};
+        const p = await this.projectFor(cwd);
+        if (!p?.project)
+            return {};
+        const s = await this.settings();
+        const link = await this.cardFor(args.session_id ?? args.sessionId, cwd);
+        const text = [link?.name, link?.promptBody].filter(Boolean).join("\n");
+        const files = await touchedFiles(cwd);
+        const hits = this.index.search({
+            text,
+            files,
+            kbIds: [p.project.kbId, PERSONAL_KB],
+            limit: s.injectTopK,
+        });
+        const kbContext = formatContext(hits, s.injectTokenBudget);
+        const context = [kbContext, WORKFLOW_HINT].filter(Boolean).join("\n\n");
+        const injected = kbContext ? hits.slice(0, kbContext.split("\n").length - 1).map((h) => h.entry.id) : [];
+        await this.usage.record(injected, "injected");
+        const sid = args.session_id ?? args.sessionId;
+        const key = link ? `card:${link.id}` : sid ? `session:${sid}` : undefined;
+        if (key)
+            await this.injections.record(key, injected);
+        return { hookSpecificOutput: { hookEventName: "SessionStart", additionalContext: context } };
+    }
+    async cardFor(sessionId, cwd) {
+        const links = await this.opts.store.readLinks();
+        return ((sessionId ? links.find((l) => l.sessionLink?.sessionId === sessionId) : undefined) ??
+            links.find((l) => l.worktreeLink?.path && path.resolve(l.worktreeLink.path) === path.resolve(cwd)));
+    }
+    /** What a card's work did with the knowledge base: its proposals, what it was given, what to re-check. */
+    async cardKnowledge(cardId) {
+        const link = (await this.opts.store.readLinks()).find((l) => l.id === cardId);
+        if (!link)
+            throw new Error(`card ${cardId} not found`);
+        const sessionIds = link.sessionLink?.sessionId ? [link.sessionLink.sessionId] : [];
+        const proposals = await this.proposals.list(undefined, { cardId, sessionIds });
+        const ids = await this.injections.idsFor([`card:${cardId}`, ...sessionIds.map((s) => `session:${s}`)]);
+        const hit = (e) => ({ entry: e, score: 0, via: [], stale: this.index.isStale(e.id) });
+        // A corrected (superseded) entry is no longer what the team believes: leave it out.
+        const injected = ids
+            .map((id) => this.index.get(id))
+            .filter((e) => !!e && !this.index.isSuperseded(e.id))
+            .map(hit);
+        // Only a card's own worktree says what *it* changed; the shared project checkout does not.
+        let review = [];
+        const checkout = link.worktreeLink?.path;
+        const p = checkout && fs.existsSync(checkout) ? await this.projectFor(checkout) : null;
+        if (checkout && p?.project) {
+            const files = await touchedFiles(checkout);
+            if (files.length) {
+                review = this.index
+                    .search({ files, kbIds: [p.project.kbId], limit: 50 })
+                    .filter((h) => h.stale && h.via.includes("scope"));
+            }
+        }
+        return { proposals, injected, review };
+    }
+    /** Pending proposals per card, matched like cardKnowledge does: by card id, else by session. */
+    async pendingByCard() {
+        const bySession = new Map();
+        for (const l of await this.opts.store.readLinks()) {
+            if (l.sessionLink?.sessionId)
+                bySession.set(l.sessionLink.sessionId, l.id);
+        }
+        const out = {};
+        for (const p of await this.proposals.list("pending")) {
+            const id = p.source?.cardId ?? (p.source?.sessionId ? bySession.get(p.source.sessionId) : undefined);
+            if (id)
+                out[id] = (out[id] ?? 0) + 1;
+        }
+        return out;
+    }
+    // ── Proposals ──────────────────────────────────────────────────────────────
+    /** A proposal from a person or an agent. `kbId` defaults to the cwd's project KB. */
+    async propose(input) {
+        let kbId = input.kbId;
+        if (!kbId && input.cwd)
+            kbId = (await this.projectFor(input.cwd))?.project?.kbId;
+        if (!kbId)
+            kbId = PERSONAL_KB;
+        const [added] = await this.proposals.add([{ ...input, kbId, origin: "manual" }]);
+        if (!added)
+            throw new Error("a proposal with this title is already waiting for review");
+        return added;
+    }
+    /** Approve: personal entries are written locally; team entries go to the harness repo by PR. */
+    async approveProposal(id, edits) {
+        const p = await this.proposals.get(id);
+        if (!p)
+            throw new Error(`proposal ${id} not found`);
+        if (p.status !== "pending")
+            throw new Error(`proposal is already ${p.status}`);
+        const merged = { ...p, ...pickEdits(edits) };
+        const entryId = newEntryId();
+        const content = serializeEntry({
+            id: entryId,
+            type: merged.type,
+            title: merged.title,
+            summary: merged.summary,
+            body: merged.body,
+            scope: merged.scope,
+            source: merged.source,
+            confidence: "confirmed",
+            lastVerified: isoDay(),
+            supersedes: merged.supersedes ?? [],
+            schemaVersion: ENTRY_SCHEMA_VERSION,
+        });
+        const rel = entryFileName(merged.type, merged.title, entryId);
+        let prUrl;
+        if (merged.kbId === PERSONAL_KB) {
+            await writeFileAtomic(path.join(this.dataDir, "kb", rel), content);
+        }
+        else {
+            const kb = this.config.kbs.find((k) => k.id === merged.kbId);
+            if (!kb || !this.repoPath)
+                throw new Error(`knowledge base ${merged.kbId} is not configured`);
+            const result = await proposeChange(this.repoPath, {
+                branch: `kb/${entryId.toLowerCase()}`,
+                message: `docs(kb): ${merged.type}: ${merged.title}`,
+                prTitle: `kb(${merged.kbId}): ${merged.title}`,
+                prBody: [
+                    `New **${merged.type}** for \`${merged.kbId}\`.`,
+                    "",
+                    `> ${merged.summary}`,
+                    "",
+                    merged.reason ? `Why: ${merged.reason}` : "",
+                    `Origin: ${merged.origin}${merged.source?.cardId ? ` (card ${merged.source.cardId})` : ""}`,
+                ]
+                    .filter((l) => l !== "")
+                    .join("\n"),
+            }, async (dir) => {
+                const file = path.join(dir, kb.path, rel);
+                await fs.promises.mkdir(path.dirname(file), { recursive: true });
+                await fs.promises.writeFile(file, content);
+            });
+            prUrl = result.url ?? (result.mode === "local" ? `local:${result.commit.slice(0, 10)}` : result.branch);
+        }
+        const updated = await this.proposals.update(id, (x) => {
+            Object.assign(x, pickEdits(edits));
+            x.status = "approved";
+            x.decidedAt = new Date().toISOString();
+            x.entryId = entryId;
+            x.prUrl = prUrl;
+        });
+        await this.reload();
+        return updated;
+    }
+    /**
+     * Undo an approval and put the proposal back in the queue. Personal entries are deleted;
+     * team entries have their pull request closed, or a revert pull request opened once merged.
+     */
+    async undoApproval(id) {
+        const p = await this.proposals.get(id);
+        if (!p)
+            throw new Error(`proposal ${id} not found`);
+        if (p.status !== "approved" || !p.entryId)
+            throw new Error("only an approved proposal can be undone");
+        const rel = entryFileName(p.type, p.title, p.entryId);
+        let revertUrl;
+        if (p.kbId === PERSONAL_KB) {
+            await fs.promises.rm(path.join(this.dataDir, "kb", rel), { force: true });
+        }
+        else {
+            const kb = this.config.kbs.find((k) => k.id === p.kbId);
+            if (!kb || !this.repoPath)
+                throw new Error(`knowledge base ${p.kbId} is not configured`);
+            const r = await retractChange(this.repoPath, path.join(kb.path, rel), { prUrl: p.prUrl, branch: `kb/${p.entryId.toLowerCase()}` }, {
+                branch: `kb/revert-${p.entryId.toLowerCase()}`,
+                message: `docs(kb): remove ${p.type}: ${p.title}`,
+                prTitle: `kb(${p.kbId}): remove ${p.title}`,
+                prBody: `Reverts the approval of **${p.title}** (\`${p.entryId}\`).`,
+            });
+            const v = r.revert;
+            revertUrl = v && (v.url ?? (v.mode === "local" ? `local:${v.commit.slice(0, 10)}` : v.branch));
+        }
+        const updated = await this.proposals.update(id, (x) => {
+            x.status = "pending";
+            x.decidedAt = undefined;
+            x.entryId = undefined;
+            x.prUrl = undefined;
+            x.decisionNote = undefined;
+        });
+        await this.reload();
+        return { proposal: updated, revertUrl };
+    }
+    rejectProposal(id, note) {
+        return this.proposals.update(id, (x) => {
+            if (x.status !== "pending")
+                throw new Error(`proposal is already ${x.status}`);
+            x.status = "rejected";
+            x.decidedAt = new Date().toISOString();
+            x.decisionNote = note?.trim() || undefined;
+        });
+    }
+    // ── Librarian ──────────────────────────────────────────────────────────────
+    /**
+     * Distill a session into proposals. Skips unregistered projects and sessions
+     * whose transcript barely grew since the last pass.
+     */
+    distillSession(args) {
+        return this.librarianLock.run(async () => {
+            const s = await this.settings();
+            if (!s.librarian.enabled || !this.repoPath)
+                return [];
+            const size = (await fs.promises.stat(args.transcriptPath).catch(() => null))?.size ?? 0;
+            const seen = await this.readDistilled();
+            if (size - (seen[args.sessionId] ?? 0) < DISTILL_MIN_GROWTH)
+                return [];
+            const cwd = await transcriptCwd(args.transcriptPath);
+            const p = cwd ? await this.projectFor(cwd) : null;
+            if (!p?.project)
+                return [];
+            const link = (await this.opts.store.readLinks()).find((l) => l.id === args.cardId || l.sessionLink?.sessionId === args.sessionId);
+            const material = await transcriptTail(args.transcriptPath, s.librarian.maxTranscriptChars);
+            // Sessions left behind by earlier librarian runs must not be distilled again.
+            if (material.includes(LIBRARIAN_PROMPT_HEAD)) {
+                seen[args.sessionId] = size;
+                await writeFileAtomic(this.distilledPath(), JSON.stringify(seen, null, 2));
+                return [];
+            }
+            const drafts = await runLibrarian({
+                mode: "session",
+                project: p.project.name ?? p.project.id,
+                material,
+                cardTitle: link?.name,
+                existingTitles: this.index.all(p.project.kbId).map((e) => e.title),
+            }, s.librarian.model, cwd);
+            const source = { sessionId: args.sessionId, cardId: link?.id, pr: link?.prLinks[0]?.url };
+            const added = await this.proposals.add(drafts.map((d) => ({ ...d, kbId: p.project.kbId, source, origin: "librarian" })));
+            seen[args.sessionId] = size;
+            await writeFileAtomic(this.distilledPath(), JSON.stringify(seen, null, 2));
+            if (added.length)
+                log.info("librarian", `${added.length} proposal(s) from session ${args.sessionId.slice(0, 8)}`);
+            return added;
+        });
+    }
+    distilledPath() {
+        return path.join(this.dataDir, "kb-distilled.json");
+    }
+    async readDistilled() {
+        try {
+            return JSON.parse(await fs.promises.readFile(this.distilledPath(), "utf8"));
+        }
+        catch {
+            return {};
+        }
+    }
+    // ── Maintenance ────────────────────────────────────────────────────────────
+    /** Flag entries whose scoped files changed after `lastVerified`, and duplicate titles. */
+    async maintain(projectPaths) {
+        const rootsByKb = new Map();
+        for (const dir of projectPaths) {
+            const p = await this.projectFor(dir).catch(() => null);
+            if (p?.project)
+                rootsByKb.set(p.project.kbId, p.id.root);
+        }
+        // One `git log` per repo (since its oldest verification), then match scopes in memory.
+        const stale = [];
+        for (const [kbId, root] of rootsByKb) {
+            const entries = this.index.all(kbId).filter((e) => e.lastVerified && e.scope.length);
+            if (entries.length === 0)
+                continue;
+            const since = entries.map((e) => verifiedAt(e.lastVerified)).reduce((a, b) => Math.min(a, b));
+            const changes = await fileChangeTimes(root, new Date(since).toISOString());
+            for (const e of entries) {
+                const after = verifiedAt(e.lastVerified);
+                const changed = [...changes]
+                    .filter(([file, at]) => at >= after && e.scope.some((sc) => scopeSpecificity(sc, file) > 0))
+                    .map(([file]) => file);
+                if (changed.length)
+                    stale.push({ id: e.id, title: e.title, kbId: e.kbId, changed });
+            }
+        }
+        this.index.setStale(stale.map((s) => s.id));
+        const byTitle = new Map();
+        for (const e of this.index.all()) {
+            const key = `${e.kbId}\u0000${e.title.toLowerCase().replace(/\W+/g, " ").trim()}`;
+            byTitle.set(key, [...(byTitle.get(key) ?? []), e.id]);
+        }
+        const duplicates = [...byTitle.entries()]
+            .filter(([, ids]) => ids.length > 1)
+            .map(([key, ids]) => ({ title: key.split("\u0000")[1], ids }));
+        this.index.setUsefulness(await this.usage.multipliers());
+        return { stale, duplicates };
+    }
+}
+function pickEdits(edits) {
+    if (!edits)
+        return {};
+    const out = {};
+    if (edits.title?.trim())
+        out.title = edits.title.trim();
+    if (edits.summary?.trim())
+        out.summary = edits.summary.trim();
+    if (edits.body?.trim())
+        out.body = edits.body.trim();
+    if (edits.type)
+        out.type = edits.type;
+    if (Array.isArray(edits.scope))
+        out.scope = edits.scope;
+    return out;
+}
+/** Files changed on this checkout's branch relative to its upstream default branch. */
+async function touchedFiles(cwd) {
+    // origin/HEAD is often unset on a server clone; fall back to the usual default branches.
+    let range = "HEAD";
+    for (const ref of ["origin/HEAD", "@{upstream}", "origin/main", "origin/master"]) {
+        const base = await run("git", ["merge-base", "HEAD", ref], { cwd, timeoutMs: 10_000 });
+        if (base.ok && base.stdout.trim()) {
+            range = base.stdout.trim();
+            break;
+        }
+    }
+    const r = await run("git", ["diff", "--name-only", range], { cwd, timeoutMs: 10_000 });
+    return r.ok ? r.stdout.split(/\r?\n/).filter(Boolean).slice(0, 200) : [];
+}
+/** `lastVerified` as a time: a bare date means the start of that day (UTC). */
+function verifiedAt(lastVerified) {
+    const t = Date.parse(/^\d{4}-\d{2}-\d{2}$/.test(lastVerified) ? `${lastVerified}T00:00:00Z` : lastVerified);
+    return Number.isNaN(t) ? 0 : t;
+}
+/** The working directory recorded in a transcript's first entries. */
+async function transcriptCwd(jsonlPath) {
+    let n = 0;
+    for await (const line of readLines(jsonlPath)) {
+        if (++n > 50)
+            break;
+        try {
+            const cwd = JSON.parse(line)?.cwd;
+            if (typeof cwd === "string" && cwd)
+                return cwd;
+        }
+        catch {
+            // skip
+        }
+    }
+    return undefined;
+}
+/** Add `owner/name` to the triage and ops-watcher agents, keeping the file's comments. */
+async function addRepoToAgents(file, repo) {
+    if (!repo || !fs.existsSync(file))
+        return;
+    const doc = parseDocument(await fs.promises.readFile(file, "utf8"));
+    const agents = doc.get("agents");
+    if (!agents?.items)
+        return;
+    for (const item of agents.items) {
+        const slug = item.get?.("slug");
+        if (slug !== "triage" && slug !== "ops-watcher" && slug !== "librarian")
+            continue;
+        let repos = item.get("repos");
+        if (!repos?.items) {
+            item.set("repos", doc.createNode([]));
+            repos = item.get("repos");
+        }
+        if (!repos.items.some((r) => (r?.value ?? r) === repo))
+            repos.add(doc.createNode(repo));
+    }
+    await fs.promises.writeFile(file, doc.toString());
+}