@a-t-h-i/bot-lobby 0.6.80 → 0.7.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (58) hide show
  1. package/THIRD_PARTY_NOTICES.md +0 -1
  2. package/package.json +1 -1
  3. package/prompts/lobby-chat.md +1 -1
  4. package/prompts/master.md +15 -2
  5. package/prompts/panel.md +4 -4
  6. package/prompts/planner.md +2 -2
  7. package/prompts/worker.md +6 -1
  8. package/src/ask/tool.ts +1 -1
  9. package/src/classifier/effort.ts +5 -0
  10. package/src/classifier/files.ts +7 -0
  11. package/src/classifier/knowledge.ts +88 -0
  12. package/src/classifier/lobby.ts +1 -1
  13. package/src/desk/board-client.ts +1 -1
  14. package/src/desk/board.ts +1 -1
  15. package/src/execution/assignment.ts +77 -1
  16. package/src/execution/delegation.ts +80 -27
  17. package/src/execution/verification.ts +216 -0
  18. package/src/knowledge/catalog-tools.ts +1 -1
  19. package/src/knowledge/catalogue.ts +21 -6
  20. package/src/knowledge/compactor.ts +212 -5
  21. package/src/knowledge/oracle-digest.ts +2 -2
  22. package/src/knowledge/paths.ts +9 -0
  23. package/src/knowledge/repo-map.ts +1 -0
  24. package/src/knowledge/retrieval.ts +8 -2
  25. package/src/knowledge/store.ts +68 -14
  26. package/src/lobby/chat-agents.ts +57 -8
  27. package/src/lobby/feed.ts +2 -2
  28. package/src/lobby/knowledge.ts +3 -3
  29. package/src/lobby/pi-commands.ts +1 -1
  30. package/src/lobby/planner.ts +6 -6
  31. package/src/lobby/prompts.ts +2 -2
  32. package/src/lobby/runtime.ts +4 -4
  33. package/src/lobby/service.ts +88 -51
  34. package/src/master/master.ts +87 -14
  35. package/src/master/scout-prefetch.ts +14 -1
  36. package/src/pi/commands.ts +28 -10
  37. package/src/pi/events.ts +21 -10
  38. package/src/pi/owner.ts +21 -3
  39. package/src/pi/start-task.ts +9 -6
  40. package/src/pi/switch-pending.ts +24 -0
  41. package/src/pi/tools.ts +14 -0
  42. package/src/roles/worker.ts +33 -3
  43. package/src/schemas/configuration.ts +9 -0
  44. package/src/schemas/task.ts +18 -0
  45. package/src/schemas/verification.ts +38 -0
  46. package/src/state/metrics.ts +32 -2
  47. package/src/webui/api/knowledge.ts +1 -1
  48. package/src/webui/api/tasks.ts +1 -1
  49. package/src/webui/dev/fake-service.ts +7 -7
  50. package/src/workflow/track.ts +65 -3
  51. package/src/workflow/workflow.ts +142 -17
  52. package/webui/dist/assets/{CodeSurface-v19_sKLO.js → CodeSurface-Bdkhh84z.js} +1 -1
  53. package/webui/dist/assets/{TerminalView-BW7Ik8CM.js → TerminalView-CsDNheS9.js} +1 -1
  54. package/webui/dist/assets/index-Bt0RLI3l.css +2 -0
  55. package/webui/dist/assets/{index-QvpDedq6.js → index-C3Bn07Vr.js} +45 -45
  56. package/webui/dist/build.json +58 -58
  57. package/webui/dist/index.html +2 -2
  58. package/webui/dist/assets/index-BKF36jpt.css +0 -2
@@ -0,0 +1,216 @@
1
+ /**
2
+ * The verification engine: runs a project's final checks (typecheck, unit
3
+ * tests, build, browser fixtures) through one shared path so completion,
4
+ * `scripts/verify-final.ts` and any concurrent caller execute each check once
5
+ * per fingerprint. Heavy checks run here only — never between intermediate
6
+ * worker steps. Keys cover sources, configuration, dependencies, commands and
7
+ * execution environment, so a recorded pass can be reused while nothing it
8
+ * covered changed, and browser fixtures always consume freshly built assets:
9
+ * `web:check` depends on `web:build` and keys on the built `build.json`.
10
+ */
11
+ import { createHash } from "node:crypto";
12
+ import { spawn, spawnSync, type ChildProcess } from "node:child_process";
13
+ import { existsSync, readdirSync, statSync } from "node:fs";
14
+ import { join } from "node:path";
15
+ import { readFileSync } from "node:fs";
16
+ import type { VerificationReport, VerifyResult, VerifyState } from "../schemas/verification.ts";
17
+ import { POSIX, signalGroup } from "./pi-runner.ts";
18
+
19
+ /** What a check prints; injected so tests run without spawning anything. */
20
+ export type VerifyExec = (command: string, args: readonly string[], options: { cwd: string; timeoutMs: number; signal?: AbortSignal }) => Promise<{ code: number | null; output: string; timedOut: boolean }>;
21
+
22
+ export const DEFAULT_TIMEOUT_MS = 30 * 60_000;
23
+
24
+ export interface VerifyCheck {
25
+ id: string;
26
+ command: string;
27
+ args: readonly string[];
28
+ timeoutMs: number;
29
+ /** Files and directories (walked, without node_modules and dist) that key the result. */
30
+ inputs: readonly string[];
31
+ /** Ids that must pass first; a failed dependency makes this check unavailable. */
32
+ dependsOn?: readonly string[];
33
+ }
34
+
35
+ function killVerificationTree(child: ChildProcess): void {
36
+ if (POSIX) signalGroup(child, "SIGKILL");
37
+ else if (child.pid !== undefined) spawnSync("taskkill", ["/PID", String(child.pid), "/T", "/F"], { timeout: 5_000, windowsHide: true });
38
+ }
39
+
40
+ function captureOutput(child: ChildProcess): () => string {
41
+ let output = "";
42
+ const read = (part: Buffer) => { output = (output + part.toString()).slice(-200_000); };
43
+ child.stdout?.on("data", read);
44
+ child.stderr?.on("data", read);
45
+ return () => output;
46
+ }
47
+
48
+ /** Spawn a check the way the engine runs commands; kill its tree on timeout or abort. */
49
+ export const execVerify: VerifyExec = (command, args, options) => new Promise((resolve) => {
50
+ if (options.signal?.aborted) { resolve({ code: null, output: "", timedOut: false }); return; }
51
+ const child = spawn(command, args, { cwd: options.cwd, env: process.env, detached: POSIX, stdio: ["ignore", "pipe", "pipe"] });
52
+ const output = captureOutput(child);
53
+ let done = false;
54
+ let timedOut = false;
55
+ const abort = () => killVerificationTree(child);
56
+ const finish = (code: number | null) => {
57
+ if (done) return;
58
+ done = true;
59
+ clearTimeout(timer);
60
+ options.signal?.removeEventListener("abort", abort);
61
+ resolve({ code, output: output(), timedOut });
62
+ };
63
+ const timer = setTimeout(() => { timedOut = true; killVerificationTree(child); }, options.timeoutMs).unref();
64
+ options.signal?.addEventListener("abort", abort, { once: true });
65
+ child.on("error", () => finish(null));
66
+ child.on("close", finish);
67
+ });
68
+
69
+ /** Directories never walked for fingerprints: outputs and installed packages. */
70
+ const SKIP = new Set(["node_modules", "dist", ".git"]);
71
+
72
+ function walk(top: string, dir: string, out: string[]): void {
73
+ let entries;
74
+ try {
75
+ entries = readdirSync(join(top, dir), { withFileTypes: true });
76
+ } catch {
77
+ return;
78
+ }
79
+ for (const entry of entries) {
80
+ if (entry.isDirectory()) {
81
+ if (!SKIP.has(entry.name)) walk(top, join(dir, entry.name), out);
82
+ } else if (entry.isFile()) out.push(join(dir, entry.name));
83
+ }
84
+ }
85
+
86
+ /** Inputs as they stand: a content hash per file (an edit that restores size and mtime still changes it), gone files keyed as gone. */
87
+ export function checkFingerprint(top: string, check: VerifyCheck): string {
88
+ const hash = createHash("sha256");
89
+ hash.update(JSON.stringify([check.command, check.args, process.version, process.platform, process.arch,
90
+ Object.entries(process.env).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)]));
91
+ const files: string[] = [];
92
+ for (const input of check.inputs) {
93
+ const full = join(top, input);
94
+ if (!existsSync(full)) files.push(input);
95
+ else if (statSync(full).isDirectory()) walk(top, input, files);
96
+ else files.push(input);
97
+ }
98
+ for (const file of [...new Set(files)].sort()) {
99
+ let stamp = "gone";
100
+ try {
101
+ stamp = createHash("sha256").update(readFileSync(join(top, file))).digest("hex");
102
+ } catch {
103
+ // A deleted or unreadable input keys as gone.
104
+ }
105
+ hash.update(`\0${file}\0${stamp}`);
106
+ }
107
+ return hash.digest("hex").slice(0, 24);
108
+ }
109
+
110
+ export interface FinalCheckSpec {
111
+ script: string;
112
+ check: Omit<VerifyCheck, "command" | "args">;
113
+ }
114
+
115
+ /** The checks a project's own scripts define, in run order; absent scripts are not applicable. */
116
+ export const FINAL_CHECK_SPECS: readonly FinalCheckSpec[] = [
117
+ { script: "typecheck", check: { id: "typecheck", timeoutMs: 10 * 60_000, inputs: ["package.json", "package-lock.json", "tsconfig.json", "src", "webui/tsconfig.json", "webui/src"] } },
118
+ { script: "test", check: { id: "test", timeoutMs: 60 * 60_000, inputs: ["package.json", "package-lock.json", "tsconfig.json", "src", "test"] } },
119
+ { script: "web:build", check: { id: "web:build", timeoutMs: 10 * 60_000, inputs: ["package.json", "package-lock.json", "webui", "src/lobby/prompts.ts", "src/webui/protocol.ts"] } },
120
+ { script: "web:check", check: { id: "web:check", timeoutMs: 60 * 60_000, inputs: ["package.json", "package-lock.json", "playwright.config.ts", "test/web", "webui/dist/build.json", "src"], dependsOn: ["web:build"] } },
121
+ ];
122
+
123
+ /** Read a project's final checks from its package.json scripts. */
124
+ export function finalChecks(top: string): VerifyCheck[] {
125
+ let scripts: Record<string, string> | undefined;
126
+ try {
127
+ scripts = JSON.parse(readFileSync(join(top, "package.json"), "utf8")).scripts;
128
+ } catch {
129
+ return [];
130
+ }
131
+ return FINAL_CHECK_SPECS.flatMap((spec) => {
132
+ const script = scripts?.[spec.script];
133
+ return typeof script === "string" && script.trim() ? [{ ...spec.check, command: "npm", args: ["run", spec.script] }] : [];
134
+ });
135
+ }
136
+
137
+ const inFlight = new Map<string, Promise<VerifyResult>>();
138
+
139
+ function resultOf(id: string, state: VerifyState, summary: string, fingerprint: string, ms = 0, output?: string, reused = false): VerifyResult {
140
+ return { id, state, at: new Date().toISOString(), ms, fingerprint, summary, ...(output ? { output } : {}), ...(reused ? { reused: true } : {}) };
141
+ }
142
+
143
+ /** Run one check: single-flight per fingerprint, so concurrent callers share the work. */
144
+ function runCheck(top: string, check: VerifyCheck, exec: VerifyExec, signal: AbortSignal | undefined): Promise<VerifyResult> {
145
+ const fingerprint = checkFingerprint(top, check);
146
+ const key = `${top}:${check.id}:${fingerprint}`;
147
+ const existing = inFlight.get(key);
148
+ if (existing) return existing;
149
+ const started = Date.now();
150
+ const run = exec(check.command, check.args, { cwd: top, timeoutMs: check.timeoutMs, ...(signal ? { signal } : {}) })
151
+ .then((outcome): VerifyResult => {
152
+ const ms = Date.now() - started;
153
+ if (signal?.aborted) return resultOf(check.id, "cancelled", `${check.id} was cancelled; a cancelled check is not a pass — complete again to re-run it`, fingerprint, ms);
154
+ if (outcome.timedOut) return resultOf(check.id, "fail", `${check.id} timed out after ${Math.round(check.timeoutMs / 60_000)} min`, fingerprint, ms, outcome.output.slice(-4_000));
155
+ if (outcome.code === 0) return resultOf(check.id, "pass", `${check.id} passed`, fingerprint, ms);
156
+ if (outcome.code === null) return resultOf(check.id, "unavailable", `${check.id} could not run (command not found or terminated); an unavailable check is not a pass`, fingerprint, ms, outcome.output.slice(-4_000));
157
+ return resultOf(check.id, "fail", `${check.id} failed with exit ${outcome.code}`, fingerprint, ms, outcome.output.slice(-4_000));
158
+ })
159
+ .catch((error: unknown) => resultOf(check.id, "unavailable", `${check.id} could not run: ${error instanceof Error ? error.message : String(error)}`, fingerprint, Date.now() - started))
160
+ .finally(() => { if (inFlight.get(key) === run) inFlight.delete(key); });
161
+ inFlight.set(key, run);
162
+ return run;
163
+ }
164
+
165
+ export interface VerificationInput {
166
+ top: string;
167
+ checks: readonly VerifyCheck[];
168
+ /** The task's last report: a pass whose fingerprint still matches is reused, not re-run. */
169
+ previous?: VerificationReport;
170
+ exec?: VerifyExec;
171
+ signal?: AbortSignal;
172
+ now?: () => Date;
173
+ }
174
+
175
+ /** Run the final checks once per fingerprint; the report refuses nothing itself — completion does. */
176
+ export async function runVerification(input: VerificationInput): Promise<VerificationReport> {
177
+ const exec = input.exec ?? execVerify;
178
+ const results: VerifyResult[] = [];
179
+ for (const check of input.checks) {
180
+ const fingerprint = checkFingerprint(input.top, check);
181
+ const failedDependency = check.dependsOn?.find((dep) => results.find((result) => result.id === dep)?.state !== "pass");
182
+ if (failedDependency) {
183
+ results.push(resultOf(check.id, "unavailable", `${check.id} was not run: ${failedDependency} did not pass`, fingerprint));
184
+ continue;
185
+ }
186
+ if (input.signal?.aborted) {
187
+ results.push(resultOf(check.id, "cancelled", `${check.id} was cancelled before execution; a cancelled check is not a pass`, fingerprint));
188
+ continue;
189
+ }
190
+ const prior = input.previous?.results.find((result) => result.id === check.id);
191
+ if (!input.signal?.aborted && prior?.state === "pass" && prior.fingerprint === fingerprint) {
192
+ results.push({ ...prior, at: (input.now ?? (() => new Date()))().toISOString(), reused: true });
193
+ } else results.push(await runCheck(input.top, check, exec, input.signal));
194
+ }
195
+ invalidateChangedInputs(input.top, input.checks, results);
196
+ const state = results.length === 0 || results.every((result) => result.state === "pass") ? "passing" : "failing";
197
+ const fingerprint = createHash("sha256").update(results.map((result) => `${result.id}:${result.fingerprint}:${result.state}`).join("\n")).digest("hex").slice(0, 24);
198
+ return { at: (input.now ?? (() => new Date()))().toISOString(), state, fingerprint, results, ...(results.length === 0 ? { note: "no applicable checks: the project defines none of typecheck, test, web:build, web:check" } : {}) };
199
+ }
200
+
201
+ /** Checks cannot pass on inputs that changed while this run was in flight. */
202
+ function invalidateChangedInputs(top: string, checks: readonly VerifyCheck[], results: VerifyResult[]): void {
203
+ for (const result of results) {
204
+ const check = checks.find((entry) => entry.id === result.id)!;
205
+ if (result.state !== "pass" || result.fingerprint === checkFingerprint(top, check)) continue;
206
+ result.state = "fail";
207
+ result.summary = `${result.id} inputs changed during verification; run it again on the current tree`;
208
+ delete result.reused;
209
+ }
210
+ }
211
+
212
+ /** One line per check, failures with their output pointer — what to fix and how to re-verify. */
213
+ export function verificationSummary(report: VerificationReport): string {
214
+ if (report.note) return report.note;
215
+ return report.results.map((result) => `${result.id}: ${result.summary}${result.reused ? " (reused: unchanged since the last pass)" : ""}`).join("; ");
216
+ }
@@ -113,7 +113,7 @@ function registerListTool(pi: ExtensionAPI, configDir: string): void {
113
113
  name: LIST_BOOKMARKS_TOOL,
114
114
  label: "List assignment bookmarks",
115
115
  description:
116
- "List the bookmarked knowledge references selected for this task and assignment (by the classifier or the oracle), with the reason each was picked and who it is for. "
116
+ "List the bookmarked knowledge references selected for this task and assignment (by the classifier or the orchestrator), with the reason each was picked and who it is for. "
117
117
  + "Every line is revalidated against the current catalogue and your access: stale or unauthorized references are never shown. "
118
118
  + "Open a reference with open_knowledge; search beyond the bookmarks with search_knowledge.",
119
119
  parameters: Type.Object({}),
@@ -20,9 +20,9 @@
20
20
  * land through a unique temp file and an atomic rename.
21
21
  */
22
22
  import { createHash, randomUUID } from "node:crypto";
23
- import { mkdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
24
- import { dirname, join, sep } from "node:path";
25
- import { AGENT_DIR_NAMES, KNOWLEDGE_FILES, knowledgeDir, type KnowledgeAgent } from "./paths.ts";
23
+ import { mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
24
+ import { basename, dirname, join, sep } from "node:path";
25
+ import { AGENT_DIR_NAMES, KNOWLEDGE_FILES, historyDir, knowledgeDir, type KnowledgeAgent } from "./paths.ts";
26
26
  import { parseEntries, type EntryKind } from "./edit.ts";
27
27
  import { fileNotesPath, readFileNotes } from "./file-notes.ts";
28
28
 
@@ -63,7 +63,7 @@ export function generationOfRef(ref: string): string | undefined {
63
63
  const SECRET_PATTERN = /(api[-_]?key|secret|password|passwd|credential|private[- ]key)\s*[:=]/i;
64
64
 
65
65
  export type CatalogueKind = "knowledge" | "standard" | "decision" | "completed" | "finding";
66
- export type CatalogueOrigin = "knowledge-file" | "file-note";
66
+ export type CatalogueOrigin = "knowledge-file" | "knowledge-history" | "file-note";
67
67
  export type CatalogueScope = "project" | "task";
68
68
  export type Freshness = "current" | "changed" | "stale";
69
69
  export type Coverage = "complete" | "partial" | "stale" | "unavailable";
@@ -213,8 +213,10 @@ function kindOf(file: string): CatalogueKind {
213
213
 
214
214
  /**
215
215
  * The accepted sources: every agent's four knowledge files in every data
216
- * tree (the live one and the read-only pre-rename ones). Nothing else — no
217
- * repository contents, no session transcripts, no scratchpads — is indexed.
216
+ * tree (the live one and the read-only pre-rename ones), plus the permanent
217
+ * history files archiving keeps (they are searchable, never pruned).
218
+ * Nothing else — no repository contents, no session transcripts, no
219
+ * scratchpads — is indexed.
218
220
  */
219
221
  export function knowledgeSourceRefs(dataRoots: readonly string[]): SourceRef[] {
220
222
  const refs: SourceRef[] = [];
@@ -224,11 +226,24 @@ export function knowledgeSourceRefs(dataRoots: readonly string[]): SourceRef[] {
224
226
  const path = canonicalSource(dataRoot, join(knowledgeDir(dataRoot, agent), file));
225
227
  if (path) refs.push({ key: `kf:${path}`, file: path, agent, kind: kindOf(file), origin: "knowledge-file" });
226
228
  }
229
+ for (const file of historyFiles(dataRoot, agent)) {
230
+ const path = canonicalSource(dataRoot, file);
231
+ if (path) refs.push({ key: `kf:${path}`, file: path, agent, kind: kindOf(basename(file)), origin: "knowledge-history" });
232
+ }
227
233
  }
228
234
  }
229
235
  return refs;
230
236
  }
231
237
 
238
+ /** The agent's archived knowledge files that exist under permanent history/, as absolute paths. */
239
+ function historyFiles(dataRoot: string, agent: KnowledgeAgent): string[] {
240
+ try {
241
+ return readdirSync(historyDir(dataRoot, agent)).filter((file) => KNOWLEDGE_FILES[agent].includes(file)).map((file) => join(historyDir(dataRoot, agent), file));
242
+ } catch {
243
+ return [];
244
+ }
245
+ }
246
+
232
247
  /** The scouts' file notes, one source with one passage per note. */
233
248
  export function fileNoteSourceRef(dataRoot: string | undefined): SourceRef | undefined {
234
249
  if (!dataRoot) return undefined;
@@ -1,8 +1,12 @@
1
- import { mkdirSync, readdirSync, rmSync, writeFileSync } from "node:fs";
2
- import { basename, join } from "node:path";
1
+ import { appendFileSync, mkdirSync, readdirSync, rmSync, writeFileSync } from "node:fs";
2
+ import { basename, dirname, join } from "node:path";
3
3
  import type { KnowledgeAgent } from "./paths.ts";
4
- import { AGENT_DIR_NAMES, KNOWLEDGE_FILES, knowledgeDir } from "./paths.ts";
5
- import { readFirstExisting, readFileOr, writeFileEnsured } from "./store.ts";
4
+ import { AGENT_DIR_NAMES, KNOWLEDGE_FILES, historyDir, knowledgeDir } from "./paths.ts";
5
+ import { refreshCatalogue } from "./catalogue.ts";
6
+ import { readNotes } from "./notes.ts";
7
+ import { pinnedEntries } from "./ledger.ts";
8
+ import { withFileLock } from "../desk/lock.ts";
9
+ import { readFirstExisting, readFileOr, writeFileAtomic } from "./store.ts";
6
10
 
7
11
  export interface OversizedFile {
8
12
  agent: KnowledgeAgent;
@@ -59,7 +63,210 @@ export function compactKnowledgeFile(entry: {
59
63
  const stamp = (entry.now ?? new Date()).toISOString().replace(/[:.]/g, "-");
60
64
  const archive = join(dir, `${basename(entry.file)}.${stamp}.bak`);
61
65
  writeFileSync(archive, previous, "utf8");
62
- writeFileEnsured(path, `${entry.content.trim()}\n`);
66
+ writeFileAtomic(path, `${entry.content.trim()}\n`);
63
67
  pruneArchives(dir, entry.file, Math.max(1, entry.backupCount));
64
68
  return { archive, before: previous.length, after: entry.content.trim().length };
65
69
  }
70
+
71
+ /**
72
+ * Permanent, searchable history: a `history/` sibling of the rotating
73
+ * `archive/` backups. Backup rotation only ever prunes `archive/<Agent>/*.bak`;
74
+ * nothing under `history/` is pruned, so archived material stays findable.
75
+ * The directory itself lives in paths.ts, where the catalogue can index it.
76
+ */
77
+ export function historyPath(dataRoot: string, agent: KnowledgeAgent, file: string): string {
78
+ return join(historyDir(dataRoot, agent), basename(file));
79
+ }
80
+
81
+ /** The material being removed, appended to permanent history under a dated heading before anything is replaced. */
82
+ function appendHistory(dataRoot: string, agent: KnowledgeAgent, file: string, material: string, now: Date): string {
83
+ const path = historyPath(dataRoot, agent, file);
84
+ const heading = `# Archived from ${basename(file)} · ${now.toISOString()}`;
85
+ withFileLock(path, () => {
86
+ mkdirSync(dirname(path), { recursive: true });
87
+ appendFileSync(path, `\n\n${heading}\n\n${material.trim()}\n`, "utf8");
88
+ });
89
+ return path;
90
+ }
91
+
92
+ /** A heading line with everything until the next heading of the same or higher level. */
93
+ interface Section {
94
+ heading: string;
95
+ body: string;
96
+ }
97
+
98
+ /** Split markdown into heading-led sections; leading text before the first heading is its own section. */
99
+ function splitIntoSections(content: string): Section[] {
100
+ const lines = content.split("\n");
101
+ const sections: Section[] = [];
102
+ let current: Section | undefined;
103
+ for (const line of lines) {
104
+ if (/^#{1,6} /.test(line)) {
105
+ if (current) sections.push(current);
106
+ current = { heading: line, body: "" };
107
+ } else if (current) {
108
+ current.body += `${line}\n`;
109
+ } else {
110
+ current = { heading: "", body: `${line}\n` };
111
+ }
112
+ }
113
+ if (current) sections.push(current);
114
+ return sections;
115
+ }
116
+
117
+ function renderSections(sections: readonly Section[]): string {
118
+ return sections.map((section) => `${section.heading}\n${section.body}`.trim()).join("\n\n");
119
+ }
120
+
121
+ function normalized(text: string): string {
122
+ return text.replace(/\s+/g, " ").trim().toLowerCase();
123
+ }
124
+
125
+ /** Actual pinned entries and matching user annotations always survive. */
126
+ function isProtectedSection(section: Section, protectedEntries: readonly string[]): boolean {
127
+ const text = `${section.heading}\n${section.body}`;
128
+ return text.includes("> Note from the user")
129
+ || protectedEntries.some((entry) => entry.trim().length > 0 && text.includes(entry));
130
+ }
131
+
132
+ /** A section that says it was superseded is clearly historical; age alone never archives. */
133
+ function isSuperseded(section: Section): boolean {
134
+ const text = `${section.heading}\n${section.body}`;
135
+ if (/\b(?:unresolved|pending)\b|\b(?:not(?:\s+been|\s+yet)?|never)\s+superseded\b/i.test(text)) return false;
136
+ return /^#{1,6}\s+Superseded(?:\s|$)/i.test(section.heading)
137
+ || /^Status:\s*superseded\s*$/im.test(section.body);
138
+ }
139
+
140
+ export interface MaintenancePlan {
141
+ /** What stays in the active file. */
142
+ keep: string;
143
+ /** What leaves the active file for permanent history. */
144
+ removed: string;
145
+ }
146
+
147
+ /**
148
+ * The conservative maintenance policy: only exact duplicate sections and
149
+ * clearly historical material (completed-task logs, sections explicitly marked
150
+ * superseded) leave the active file. Pinned rules, user annotations, the
151
+ * title section and anything ambiguous stay; age alone never archives.
152
+ */
153
+ export function planMaintenance(file: string, content: string, protectedEntries: readonly string[] = []): MaintenancePlan {
154
+ const sections = splitIntoSections(content);
155
+ const completed = basename(file) === "completed-tasks.md";
156
+ const seen = new Set<string>();
157
+ const keep: Section[] = [];
158
+ const removed: Section[] = [];
159
+ sections.forEach((section, index) => {
160
+ const text = `${section.heading}\n${section.body}`;
161
+ const duplicate = normalized(text).length > 0 && seen.has(normalized(text));
162
+ seen.add(normalized(text));
163
+ const historical = completed ? index > 0 : isSuperseded(section);
164
+ if (index === 0 || isProtectedSection(section, protectedEntries) || (!duplicate && !historical)) keep.push(section);
165
+ else removed.push(section);
166
+ });
167
+ return { keep: renderSections(keep), removed: renderSections(removed) };
168
+ }
169
+
170
+ export type MaintenanceStatus = "maintained" | "busy" | "unchanged" | "failed";
171
+
172
+ export interface MaintenanceResult {
173
+ agent: KnowledgeAgent;
174
+ file: string;
175
+ status: MaintenanceStatus;
176
+ before: number;
177
+ after: number;
178
+ /** The permanent history entry that received the removed material. */
179
+ history: string;
180
+ error?: string;
181
+ }
182
+
183
+ export interface MaintenanceEntry {
184
+ dataRoot: string;
185
+ agent: KnowledgeAgent;
186
+ file: string;
187
+ backupCount: number;
188
+ now?: Date;
189
+ /** A rewritten active file to keep (the Master's compact semantics); absent plans maintenance from the conservative policy. */
190
+ content?: string;
191
+ /** Test seam: called after the history copy is durable, before the active file is replaced. */
192
+ afterArchive?: () => void | Promise<void>;
193
+ }
194
+
195
+ /** One maintenance run per file at a time: a second run on an in-flight file is blocked, never interleaved. */
196
+ const inFlight = new Set<string>();
197
+
198
+ /**
199
+ * Safe automatic maintenance of one knowledge file. The material being
200
+ * removed — the whole previous version — is written to permanent history
201
+ * BEFORE the active file is replaced, and the replacement itself is atomic
202
+ * (temp file + rename), so an interrupted run leaves either the old file or
203
+ * the fully-written new one, and never loses the history copy. The catalogue
204
+ * is refreshed afterwards; a crashed run simply re-indexes on next use.
205
+ */
206
+ export async function maintainKnowledgeFile(entry: MaintenanceEntry): Promise<MaintenanceResult> {
207
+ if (!KNOWLEDGE_FILES[entry.agent].includes(entry.file)) {
208
+ throw new Error(`"${entry.file}" is not a knowledge file for ${entry.agent}`);
209
+ }
210
+ const key = join(entry.dataRoot, AGENT_DIR_NAMES[entry.agent], entry.file);
211
+ if (inFlight.has(key)) return { ...maintenanceBase(entry), status: "busy" };
212
+ inFlight.add(key);
213
+ try {
214
+ return await maintainSnapshot(entry);
215
+ } finally {
216
+ inFlight.delete(key);
217
+ }
218
+ }
219
+
220
+ function maintenanceBase(entry: MaintenanceEntry) {
221
+ return { agent: entry.agent, file: entry.file, before: 0, after: 0, history: historyPath(entry.dataRoot, entry.agent, entry.file) };
222
+ }
223
+
224
+ async function maintainSnapshot(entry: MaintenanceEntry): Promise<MaintenanceResult> {
225
+ const path = join(knowledgeDir(entry.dataRoot, entry.agent), entry.file);
226
+ const previous = readFileOr(path);
227
+ const keep = entry.content ?? planMaintenance(entry.file, previous, maintenanceProtections(entry)).keep;
228
+ const base = { ...maintenanceBase(entry), before: previous.length, after: keep.trim().length };
229
+ if (previous.trim() === keep.trim()) return { ...base, status: "unchanged" };
230
+ appendHistory(entry.dataRoot, entry.agent, entry.file, previous, entry.now ?? new Date());
231
+ await entry.afterArchive?.();
232
+ if (!writeFileAtomic(path, `${keep.trim()}\n`, previous)) {
233
+ return { ...base, after: readFileOr(path).length, status: "failed", error: "Knowledge changed during maintenance; retry on the current file." };
234
+ }
235
+ refreshMaintenanceCatalogue(entry.dataRoot);
236
+ return { ...base, status: "maintained" };
237
+ }
238
+
239
+ function refreshMaintenanceCatalogue(dataRoot: string): void {
240
+ try {
241
+ refreshCatalogue([dataRoot]);
242
+ } catch {
243
+ // Recoverable: the next catalogue use re-indexes the current files.
244
+ }
245
+ }
246
+
247
+ function maintenanceProtections(entry: MaintenanceEntry): string[] {
248
+ const notes = readNotes(entry.dataRoot).filter((note) => note.agent === entry.agent && note.file === entry.file);
249
+ return [...pinnedEntries(entry.dataRoot, entry.agent, entry.file), ...notes.map((note) => note.entry)];
250
+ }
251
+
252
+ export interface MaintenanceSchedule {
253
+ /** Resolves with the maintenance outcome; never rejects (a failure is a "failed" result). */
254
+ done: Promise<MaintenanceResult>;
255
+ }
256
+
257
+ /**
258
+ * Schedule maintenance to run after the current response, outside the
259
+ * response-critical path: the caller proceeds immediately, the file work
260
+ * happens on the next event-loop turn, and failures resolve (not reject) so
261
+ * an unobserved failure can never surface as an unhandled rejection.
262
+ */
263
+ export function scheduleKnowledgeMaintenance(entry: MaintenanceEntry): MaintenanceSchedule {
264
+ const done = new Promise<MaintenanceResult>((resolve) => {
265
+ setImmediate(() => {
266
+ maintainKnowledgeFile(entry).then(resolve, (error: unknown) => {
267
+ resolve({ agent: entry.agent, file: entry.file, status: "failed", before: 0, after: 0, history: historyPath(entry.dataRoot, entry.agent, entry.file), error: error instanceof Error ? error.message : String(error) });
268
+ });
269
+ });
270
+ });
271
+ return { done };
272
+ }
@@ -54,13 +54,13 @@ export function shareDigest(dataRoot: string, items: readonly DigestItem[], now
54
54
  const added: Partial<Record<KnowledgeAgent, number>> = {};
55
55
  for (const item of items) {
56
56
  const text = item.kind === "decision" ? item.text : `- ${item.text}`;
57
- if (applyKnowledge({ dataRoot, agent: item.agent, kind: item.kind, text, now, by: "Oracle", what: "filed this when it compacted its context", source: "Compaction" }).result === "added") added[item.agent] = (added[item.agent] ?? 0) + 1;
57
+ if (applyKnowledge({ dataRoot, agent: item.agent, kind: item.kind, text, now, by: "Orchestrator", what: "filed this when it compacted its context", source: "Compaction" }).result === "added") added[item.agent] = (added[item.agent] ?? 0) + 1;
58
58
  }
59
59
  return added;
60
60
  }
61
61
 
62
62
  /** "2 for the designer, 1 for QA" */
63
63
  export function describeShared(added: Partial<Record<KnowledgeAgent, number>>): string {
64
- const names: Record<KnowledgeAgent, string> = { master: "the oracle", designer: "the designer", backend: "backend", qa: "QA" };
64
+ const names: Record<KnowledgeAgent, string> = { master: "the orchestrator", designer: "the designer", backend: "backend", qa: "QA" };
65
65
  return AGENTS.filter((agent) => added[agent]).map((agent) => `${added[agent]} for ${names[agent]}`).join(", ");
66
66
  }
@@ -11,6 +11,15 @@ export const AGENT_DIR_NAMES: Record<KnowledgeAgent, string> = {
11
11
  qa: "QA",
12
12
  };
13
13
 
14
+ /**
15
+ * Permanent, searchable history: a `history/` sibling of the rotating
16
+ * `archive/` backups. Nothing under `history/` is pruned, so archived
17
+ * material stays findable.
18
+ */
19
+ export function historyDir(dataRoot: string, agent: KnowledgeAgent): string {
20
+ return join(dataRoot, "history", AGENT_DIR_NAMES[agent]);
21
+ }
22
+
14
23
  /** Domain-specific standards file per agent (§21). */
15
24
  export const STANDARDS_FILE: Record<KnowledgeAgent, string> = {
16
25
  master: "standards.md",
@@ -225,6 +225,7 @@ export function withRepoMap(hinter: FileHinter, scope: FileScope, settings: () =
225
225
  const [likely, mapped] = await Promise.all([hinter.block(query, signal, context), map]);
226
226
  return [withoutMapped(likely, mapped), mapped].filter(Boolean).join("\n\n");
227
227
  },
228
+ paths: (query, signal) => hinter.paths?.(query, signal) ?? Promise.resolve([]),
228
229
  tools: () => hinter.tools(),
229
230
  };
230
231
  }
@@ -193,8 +193,14 @@ function rankEntries(entries: readonly CatalogueEntry[], allowed: Map<string, st
193
193
  .map((ranked) => ranked.entry);
194
194
  }
195
195
 
196
+ /** Where a reference lives: the file's name, with `history/` in front of archived material so the two never read alike. */
197
+ function whereOf(entry: CatalogueEntry): string {
198
+ const file = basename(sourceFile(entry.sourceKey));
199
+ return `${entry.origin === "knowledge-history" ? "history/" : ""}${file}${entry.locator.heading ? ` > ${entry.locator.heading}` : ""}`;
200
+ }
201
+
196
202
  function formatRef(entry: CatalogueEntry, notes: readonly KnowledgeNote[], conflict?: string): string {
197
- const where = `${basename(sourceFile(entry.sourceKey))}${entry.locator.heading ? ` > ${entry.locator.heading}` : ""}`;
203
+ const where = whereOf(entry);
198
204
  const fresh = entry.freshness === "changed" ? `changed (r${entry.revision}; verify)` : entry.freshness;
199
205
  const conflicts = conflictIds(entry, notes);
200
206
  const marks = [
@@ -355,7 +361,7 @@ function annotationBlock(entry: CatalogueEntry, notes: readonly KnowledgeNote[],
355
361
  }
356
362
 
357
363
  async function metadataLines(entry: CatalogueEntry, access: Access, notes: readonly KnowledgeNote[]): Promise<string[]> {
358
- const where = `${basename(sourceFile(entry.sourceKey))}${entry.locator.heading ? ` > ${entry.locator.heading}` : ""}`;
364
+ const where = whereOf(entry);
359
365
  const conflicts = conflictIds(entry, notes);
360
366
  const dependency = await dependencyLine(entry, access);
361
367
  return [