@technomoron/agent-run 0.99.30 → 0.99.32

package/dist/brain/server.js

@@ -0,0 +1,197 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultSocketPath = void 0;
+exports.createBrainServer = createBrainServer;
+exports.serveApiCore = serveApiCore;
+exports.proxyStdio = proxyStdio;
+const fs = require("node:fs");
+const path = require("node:path");
+const http = require("node:http");
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const streamableHttp_js_1 = require("@modelcontextprotocol/sdk/server/streamableHttp.js");
+const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
+const apicore_server_1 = require("@technomoron/apicore-server");
+const zod_1 = require("zod");
+const version_1 = require("../version");
+const store_1 = require("./store");
+const skills_1 = require("./skills");
+const todos_1 = require("./todos");
+const connectors_1 = require("./connectors");
+const git_1 = require("./git");
+var config_1 = require("./config");
+Object.defineProperty(exports, "defaultSocketPath", { enumerable: true, get: function () { return config_1.defaultSocketPath; } });
+function createBrainServer(store) {
+    const server = new mcp_js_1.McpServer({ name: 'agent-brain', version: (0, version_1.packageVersion)() });
+    function tool(name, description, shape, readOnly, handler) {
+        const schema = zod_1.z.object(shape).strict();
+        server.registerTool(name, { description, inputSchema: schema, annotations: { readOnlyHint: readOnly, destructiveHint: false, openWorldHint: false } }, async (input) => {
+            try {
+                const result = await handler(zod_1.z.object(shape).strict().parse(input));
+                return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+            }
+            catch (error) {
+                return { isError: true, content: [{ type: 'text', text: error instanceof Error ? error.message : String(error) }] };
+            }
+        });
+    }
+    const id = zod_1.z.string().min(1).max(200);
+    const revision = zod_1.z.string().regex(/^[a-f0-9]{64}$/);
+    tool('brain_status', 'Show the active project and available scopes.', {}, true, () => ({ profile: store.profile, scopes: store.scopes.map((entry) => entry.scope) }));
+    tool('sync_status', 'Preview Git state and the canonical files eligible for saving. Runtime files, indexes, credentials, and native agent state are excluded.', {}, true, () => (0, git_1.gitPreview)(store));
+    server.registerTool('sync', { description: 'Initialize, save, pull, or push the configuration Git repository. Review sync_status first. Requires explicit user authorization; saving also requires the approved commit message.',
+        inputSchema: { action: zod_1.z.enum(['init', 'save', 'pull', 'push']), confirmed: zod_1.z.literal(true), message: zod_1.z.string().min(1).max(1000).optional() },
+        annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true }
+    }, async ({ action, message }) => {
+        try {
+            return { content: [{ type: 'text', text: JSON.stringify((0, git_1.syncGit)(store, action, message)) }] };
+        }
+        catch (error) {
+            return { isError: true, content: [{ type: 'text', text: error instanceof Error ? error.message : String(error) }] };
+        }
+    });
+    tool('get_context', 'Retrieve relevant constraints and knowledge before substantial work. Check omitted; explicitly fetch required knowledge if the budget excluded it.', {
+        task: zod_1.z.string().max(10000), files: zod_1.z.array(zod_1.z.string()).max(100).optional(), symbols: zod_1.z.array(zod_1.z.string()).max(100).optional()
+    }, true, ({ task, files, symbols }) => store.context(task, files, symbols));
+    tool('search_knowledge', 'Search Markdown knowledge in the active scopes using SQLite FTS.', {
+        query: zod_1.z.string().max(10000), scopes: zod_1.z.array(store_1.scopeSchema).optional(), types: zod_1.z.array(store_1.typeSchema).optional(),
+        includeDeprecated: zod_1.z.boolean().optional(), limit: zod_1.z.number().int().min(1).max(100).optional()
+    }, true, ({ query, ...options }) => store.search(query, options));
+    tool('get_knowledge', 'Read a complete knowledge item and its current revision.', { id }, true, ({ id }) => store.get(id));
+    tool('remember', 'Persist durable knowledge when authorized by the user. Choose scope and a singular type; the server stores it in the matching directory (for example constraint in constraints/, preference in preferences/). Explicit user instructions have authority=user; deductions remain inferred observations. Global writes require explicit global intent. Use todo tools for tasks; skills and templates are separate files.', store_1.knowledgeInput.shape, false, (input) => store.remember(input));
+    tool('amend_knowledge', 'Revise an active item in place using its last-read revision, keeping its id, file name, scope, type, authority, and history. Use this to correct or extend existing knowledge instead of writing a near-duplicate. Scope, type, authority, and review severity cannot be changed this way.', {
+        id, revision, changes: store_1.knowledgeChanges
+    }, false, ({ id, revision, changes }) => store.amend(id, revision, changes));
+    tool('promote', 'Copy active knowledge to another available scope with user authority. Requires explicit user approval; the original is preserved.', {
+        id, scope: store_1.scopeSchema, revision, confirmed: zod_1.z.literal(true)
+    }, false, ({ id, scope, revision }) => store.promote(id, scope, revision));
+    tool('deprecate_knowledge', 'Deprecate outdated knowledge without deleting its history.', { id, revision, reason: zod_1.z.string().max(2000).optional() }, false, ({ id, revision, reason }) => store.deprecate(id, revision, reason));
+    tool('list_skills', 'List available skills and descriptions. Local skills override global skills with the same name.', {}, true, () => (0, skills_1.listSkills)(store));
+    tool('get_skill', 'Load a full skill only when it applies to the current task.', { name: zod_1.z.string().max(100) }, true, ({ name }) => (0, skills_1.getSkill)(store, name));
+    tool('review_context', 'Retrieve constraints, decisions, prior review findings, and path-specific knowledge for a code review.', {
+        task: zod_1.z.string().max(10000), files: zod_1.z.array(zod_1.z.string()).max(100).optional()
+    }, true, ({ task, files }) => store.context(`review constraint decision ${task}`, files));
+    tool('review_list', 'List review findings in severity then number order. Open findings only unless states are given. Each finding carries its label, severity, state, and the revision needed to resolve it.', {
+        severity: zod_1.z.array(store_1.severitySchema).optional(), state: zod_1.z.array(store_1.reviewStateSchema).optional()
+    }, true, ({ severity, state }) => store.reviews({ severity, state }).map((item) => ({
+        finding: item.finding, severity: item.severity, state: item.state ?? 'open', title: item.title,
+        applies_to: item.applies_to, id: item.id, revision: item.revision
+    })));
+    tool('resolve_review', 'Close a review finding as fixed or wontfix, with a reason and the revision you last read. Use wontfix only when the user has said the finding is intentional.', {
+        id, revision, state: zod_1.z.enum(['fixed', 'wontfix']), reason: zod_1.z.string().max(2000).optional()
+    }, false, ({ id, revision, state, reason }) => store.resolveReview(id, revision, state, reason));
+    tool('todo_list', 'List structured tasks in the active scopes.', { status: todos_1.todoInput.shape.status.optional() }, true, ({ status }) => (0, todos_1.listTodos)(store).filter((item) => !status || item.status === status));
+    tool('todo_get', 'Read a task and its revision.', { id }, true, ({ id }) => (0, todos_1.getTodo)(store, id));
+    tool('todo_add', 'Create a local task. Reimporting the same external task returns the existing task.', todos_1.todoInput.shape, false, (input) => (0, todos_1.addTodo)(store, input));
+    tool('todo_update', 'Update a local task using its last-read revision. Does not change remote tasks.', { id, revision, changes: todos_1.todoChanges }, false, ({ id, revision, changes }) => (0, todos_1.updateTodo)(store, id, revision, changes));
+    tool('todo_complete', 'Mark a local task done. Does not change remote tasks.', { id, revision }, false, ({ id, revision }) => (0, todos_1.updateTodo)(store, id, revision, { status: 'done' }));
+    for (const name of ['todo_import', 'todo_sync']) {
+        server.registerTool(name, { description: 'Import tasks from a configured connector. Merge remote changes only when they do not conflict with local edits; report conflicting task IDs. Remote tasks are never modified.',
+            inputSchema: { source: zod_1.z.string().max(100), scope: store_1.scopeSchema }, annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true }
+        }, async ({ source, scope }) => {
+            try {
+                return { content: [{ type: 'text', text: JSON.stringify(await (0, connectors_1.syncConnector)(store, source, scope)) }] };
+            }
+            catch (error) {
+                return { isError: true, content: [{ type: 'text', text: error instanceof Error ? error.message : String(error) }] };
+            }
+        });
+    }
+    return server;
+}
+function requirePrivateSocketDirectory(socketPath) {
+    if (process.platform === 'win32')
+        throw new Error('The agent-brain Unix-socket service requires Linux or macOS.');
+    const stat = fs.lstatSync(path.dirname(socketPath));
+    if (!stat.isDirectory() || stat.uid !== process.getuid() || (stat.mode & 0o077) !== 0)
+        throw new Error('The socket directory must be owned by the current user with mode 0700.');
+}
+async function serveApiCore(configRoot, socketPath) {
+    const directory = path.dirname(socketPath);
+    fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+    requirePrivateSocketDirectory(socketPath);
+    if (fs.existsSync(socketPath))
+        throw new Error(`Socket already exists: ${socketPath}. Stop the running service, or remove the socket after confirming it is stale.`);
+    const api = new apicore_server_1.ApiServer({ authApi: false, origins: [], devMode: false });
+    api.fastify.post('/mcp', async (request, reply) => {
+        if (request.headers.origin)
+            return reply.code(403).send({ error: 'Browser requests are not supported' });
+        if (request.headers['x-agent-brain-root'] !== encodeURIComponent(path.resolve(configRoot)))
+            return reply.code(409).send({ error: 'This service uses a different configuration directory' });
+        const cwdHeader = request.headers['x-agent-brain-cwd'];
+        if (typeof cwdHeader !== 'string')
+            return reply.code(400).send({ error: 'Missing project directory' });
+        let cwd;
+        try {
+            cwd = decodeURIComponent(cwdHeader);
+        }
+        catch {
+            return reply.code(400).send({ error: 'Invalid project directory' });
+        }
+        if (!path.isAbsolute(cwd) || !fs.statSync(cwd, { throwIfNoEntry: false })?.isDirectory())
+            return reply.code(400).send({ error: 'Invalid project directory' });
+        const store = new store_1.BrainStore(configRoot, cwd);
+        const server = createBrainServer(store);
+        const transport = new streamableHttp_js_1.StreamableHTTPServerTransport({ sessionIdGenerator: undefined, enableJsonResponse: true });
+        reply.hijack();
+        try {
+            await server.connect(transport);
+            await transport.handleRequest(request.raw, reply.raw, request.body);
+        }
+        finally {
+            await server.close();
+            store.close();
+        }
+    });
+    api.fastify.route({ method: ['GET', 'DELETE'], url: '/mcp', handler: async (_request, reply) => reply.code(405).send() });
+    await api.fastify.listen({ path: socketPath });
+    fs.chmodSync(socketPath, 0o600);
+    return { close: () => api.fastify.close() };
+}
+async function proxyStdio(socketPath, cwd, configRoot) {
+    const socket = fs.lstatSync(socketPath, { throwIfNoEntry: false });
+    if (!socket)
+        throw new Error(`Agent-brain service is not running at ${socketPath}. Start agent-brain serve with the same --configdir and --socket, or enable its systemd user service.`);
+    requirePrivateSocketDirectory(socketPath);
+    if (!socket.isSocket() || socket.uid !== process.getuid() || (socket.mode & 0o077) !== 0)
+        throw new Error('The brain socket must belong to the current user with mode 0600.');
+    const stdio = new stdio_js_1.StdioServerTransport();
+    let protocolVersion;
+    async function send(message) {
+        const response = await new Promise((resolve, reject) => {
+            const request = http.request({ socketPath, path: '/mcp', method: 'POST', headers: {
+                    'content-type': 'application/json', accept: 'application/json, text/event-stream',
+                    'x-agent-brain-cwd': encodeURIComponent(cwd), 'x-agent-brain-root': encodeURIComponent(path.resolve(configRoot)),
+                    ...(protocolVersion ? { 'mcp-protocol-version': protocolVersion } : {})
+                } }, (response) => {
+                const chunks = [];
+                let bytes = 0;
+                response.on('data', (chunk) => { bytes += chunk.length; if (bytes > 4 * 1024 * 1024)
+                    response.destroy(new Error('Brain response exceeds 4 MiB'));
+                else
+                    chunks.push(chunk); });
+                response.on('error', reject);
+                response.on('end', () => response.statusCode && response.statusCode >= 200 && response.statusCode < 300
+                    ? resolve(Buffer.concat(chunks).toString('utf8')) : reject(new Error(`Brain service returned HTTP ${response.statusCode}`)));
+            });
+            request.setTimeout(30000, () => request.destroy(new Error('Brain service request timed out')));
+            request.on('error', reject);
+            request.end(JSON.stringify(message));
+        });
+        if (response) {
+            const parsed = types_js_1.JSONRPCMessageSchema.parse(JSON.parse(response));
+            if ('result' in parsed && typeof parsed.result.protocolVersion === 'string')
+                protocolVersion = parsed.result.protocolVersion;
+            await stdio.send(parsed);
+        }
+    }
+    stdio.onmessage = (message) => {
+        void send(message).catch(async (error) => {
+            if ('id' in message && 'method' in message)
+                await stdio.send({ jsonrpc: '2.0', id: message.id, error: { code: -32603, message: error instanceof Error ? error.message : String(error) } });
+            else
+                process.stderr.write(`${String(error)}\n`);
+        });
+    };
+    await stdio.start();
+}

package/dist/brain/skills.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getSkills = getSkills;
+exports.listSkills = listSkills;
+exports.getSkill = getSkill;
+const path = require("node:path");
+const zod_1 = require("zod");
+const store_1 = require("./store");
+const templates_1 = require("../templates");
+const manifest_1 = require("../manifest");
+const metadata = zod_1.z.object({
+    name: zod_1.z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/),
+    description: zod_1.z.string().trim().min(1),
+    tags: zod_1.z.array(zod_1.z.string()).default([]),
+    extends: zod_1.z.string().regex(/^global:[a-zA-Z0-9][a-zA-Z0-9._-]*$/).optional()
+});
+function getSkills(store) {
+    const profile = store.profile ?? 'default';
+    const directory = store.scopeDirectory(store.profile ? 'project' : 'default');
+    const env = (0, templates_1.createNunjucksEnv)(store.configRoot);
+    const context = (0, templates_1.buildRenderContext)(store.projectRoot, directory, store.configRoot, (0, manifest_1.normalizeManifest)((0, manifest_1.loadManifest)(store.configRoot, directory, profile), profile), env);
+    const skills = new Map();
+    const globalSkills = new Map();
+    for (const { scope, directory } of store.scopes) {
+        for (const file of store.files(path.join(directory, 'skills')).filter((file) => path.basename(file) === 'SKILL.md')) {
+            const text = env.renderString(store.read(file), context);
+            const document = (0, store_1.readMarkdown)(text);
+            const parsed = metadata.parse(document.metadata);
+            if (path.basename(path.dirname(file)) !== parsed.name)
+                throw new Error(`Skill name must match directory: ${file}`);
+            let content = document.content;
+            if (parsed.extends) {
+                const parent = globalSkills.get(parsed.extends.slice('global:'.length));
+                if (!parent || parent.scope !== 'global' || scope === 'global')
+                    throw new Error(`Missing global parent for skill ${parsed.name}`);
+                content = `${parent.content}\n\n${content}`;
+            }
+            skills.set(parsed.name, { ...parsed, scope, content, source: path.relative(store.configRoot, file) });
+            if (scope === 'global')
+                globalSkills.set(parsed.name, skills.get(parsed.name));
+        }
+    }
+    return [...skills.values()];
+}
+function listSkills(store) {
+    return getSkills(store).map(({ content: _content, ...skill }) => skill);
+}
+function getSkill(store, name) {
+    const skill = getSkills(store).find((item) => item.name === name);
+    if (!skill)
+        throw new Error(`Skill not found: ${name}`);
+    return skill;
+}

package/dist/brain/store.js

@@ -0,0 +1,343 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BrainStore = exports.knowledgeDirectories = exports.knowledgeChanges = exports.knowledgeMetadata = exports.knowledgeInput = exports.reviewStateSchema = exports.severitySchema = exports.typeSchema = exports.scopeSchema = void 0;
+exports.readMarkdown = readMarkdown;
+const fs = require("node:fs");
+const path = require("node:path");
+const node_crypto_1 = require("node:crypto");
+const node_sqlite_1 = require("node:sqlite");
+const yaml_1 = require("yaml");
+const zod_1 = require("zod");
+const project_1 = require("../project");
+const utils_1 = require("../utils");
+const config_1 = require("./config");
+exports.scopeSchema = zod_1.z.enum(['global', 'project', 'default']);
+exports.typeSchema = zod_1.z.enum(['rule', 'preference', 'convention', 'constraint', 'decision', 'spec', 'review', 'memory', 'observation']);
+exports.severitySchema = zod_1.z.enum(['critical', 'high', 'medium', 'low']);
+exports.reviewStateSchema = zod_1.z.enum(['open', 'fixed', 'wontfix']);
+const severityPrefix = { critical: 'C', high: 'H', medium: 'M', low: 'L' };
+const severityOrder = { critical: 0, high: 1, medium: 2, low: 3 };
+exports.knowledgeInput = zod_1.z.object({
+    scope: exports.scopeSchema,
+    type: exports.typeSchema,
+    title: zod_1.z.string().trim().min(1).max(300),
+    content: zod_1.z.string().trim().min(1).max(200000),
+    authority: zod_1.z.enum(['user', 'inferred']).default('inferred'),
+    recall: zod_1.z.enum(['always', 'relevant']).default('relevant'),
+    severity: exports.severitySchema.optional(),
+    tags: zod_1.z.array(zod_1.z.string().max(100)).max(50).default([]),
+    applies_to: zod_1.z.array(zod_1.z.string().max(500)).max(50).default([]),
+    // Naming only. The id in the front matter stays the identity, so files can be renamed freely.
+    filename: zod_1.z.string().regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, 'Use lower-case words separated by single dashes, with no extension').max(100).optional()
+}).strict();
+// finding and state stay optional so review files written before they existed keep parsing.
+exports.knowledgeMetadata = exports.knowledgeInput.omit({ content: true, filename: true }).extend({
+    id: zod_1.z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/),
+    status: zod_1.z.enum(['active', 'deprecated']).default('active'),
+    finding: zod_1.z.string().regex(/^[CHML][1-9][0-9]*$/).optional(),
+    state: exports.reviewStateSchema.optional(),
+    created: zod_1.z.string().default(''),
+    updated: zod_1.z.string().default(''),
+    reason: zod_1.z.string().optional(),
+    promoted_from: zod_1.z.string().optional()
+}).strict();
+// Spelled out rather than derived from knowledgeInput: .partial() keeps .default(), so a
+// derived schema would silently reset every field the caller did not mention.
+exports.knowledgeChanges = zod_1.z.object({
+    title: zod_1.z.string().trim().min(1).max(300).optional(),
+    content: zod_1.z.string().trim().min(1).max(200000).optional(),
+    recall: zod_1.z.enum(['always', 'relevant']).optional(),
+    tags: zod_1.z.array(zod_1.z.string().max(100)).max(50).optional(),
+    applies_to: zod_1.z.array(zod_1.z.string().max(500)).max(50).optional()
+}).strict();
+exports.knowledgeDirectories = {
+    rule: 'rules', preference: 'preferences', convention: 'conventions', constraint: 'constraints',
+    decision: 'decisions', spec: 'specs', review: 'reviews', memory: 'memory', observation: 'observations'
+};
+function readMarkdown(text) {
+    const normalized = text.replace(/\r\n/g, '\n');
+    const match = /^---\n([\s\S]*?)\n---(?:\n|$)/.exec(normalized);
+    return match ? { metadata: (0, yaml_1.parse)(match[1], { maxAliasCount: 50 }), content: normalized.slice(match[0].length).trim() }
+        : { metadata: null, content: normalized.trim() };
+}
+function hash(text) { return (0, node_crypto_1.createHash)('sha256').update(text).digest('hex'); }
+class BrainStore {
+    constructor(configRoot, cwd) {
+        this.configRoot = configRoot;
+        this.cwd = cwd;
+        this.configRoot = path.resolve(configRoot);
+        this.projectRoot = (0, config_1.registeredBrainProject)(this.configRoot, cwd)?.root ?? (0, project_1.findProjectRoot)(cwd);
+        const resolved = (0, project_1.resolveProfileResult)(this.projectRoot, this.configRoot).profile;
+        this.profile = resolved && resolved !== 'default' && ['agent-run.jsonc', 'local.md.njk', 'AGENTS-MODS.md'].some((file) => fs.existsSync(path.join(this.configRoot, resolved, file))) ? resolved : null;
+        this.scopes = [{ scope: 'global', directory: path.join(this.configRoot, 'global') },
+            { scope: this.profile ? 'project' : 'default', directory: path.join(this.configRoot, this.profile ?? 'default') }];
+        this.budget = (0, config_1.readBrainConfig)(this.configRoot)?.contextBudget ?? 16000;
+        this.directory('index');
+        this.directory('runtime');
+        this.db = new node_sqlite_1.DatabaseSync(this.safePath('index', 'knowledge.sqlite'));
+        this.db.exec('PRAGMA busy_timeout = 5000; PRAGMA journal_mode = WAL; CREATE VIRTUAL TABLE IF NOT EXISTS knowledge USING fts5(source UNINDEXED, environment UNINDEXED, title, content, tags);');
+    }
+    close() { this.db.close(); }
+    safePath(...parts) {
+        const target = path.resolve(this.configRoot, ...parts);
+        if (!(0, utils_1.isSamePathOrDescendant)(target, this.configRoot))
+            throw new Error('Path escapes the brain configuration directory');
+        let current = this.configRoot;
+        for (const part of path.relative(this.configRoot, target).split(path.sep).filter(Boolean)) {
+            current = path.join(current, part);
+            try {
+                if (fs.lstatSync(current).isSymbolicLink())
+                    throw new Error(`Symlinks are not supported in brain storage: ${current}`);
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+        }
+        return target;
+    }
+    directory(...parts) {
+        const directory = this.safePath(...parts);
+        fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+        return directory;
+    }
+    scopeDirectory(scope) {
+        const directory = this.scopes.find((entry) => entry.scope === scope)?.directory;
+        if (!directory)
+            throw new Error(`Scope ${scope} is not available in this environment`);
+        return this.safePath(directory);
+    }
+    files(directory) {
+        this.safePath(directory);
+        if (!fs.existsSync(directory))
+            return [];
+        return fs.readdirSync(directory, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name)).flatMap((entry) => {
+            const file = this.safePath(directory, entry.name);
+            return entry.isDirectory() ? this.files(file) : entry.isFile() && entry.name.endsWith('.md') ? [file] : [];
+        });
+    }
+    read(file) {
+        const target = this.safePath(file);
+        if (fs.statSync(target).size > 1024 * 1024)
+            throw new Error(`Markdown file exceeds 1 MiB: ${file}`);
+        return fs.readFileSync(target, 'utf8');
+    }
+    atomicWrite(file, text) {
+        const target = this.safePath(file);
+        this.directory(path.dirname(target));
+        const temporary = `${target}.${(0, node_crypto_1.randomUUID)()}.tmp`;
+        try {
+            fs.writeFileSync(temporary, text, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+            fs.renameSync(temporary, target);
+        }
+        finally {
+            fs.rmSync(temporary, { force: true });
+        }
+    }
+    writeLocked(fn) {
+        const file = this.safePath('runtime', 'brain-write.lock');
+        let descriptor;
+        try {
+            descriptor = fs.openSync(file, 'wx', 0o600);
+        }
+        catch (error) {
+            if (error.code === 'EEXIST')
+                throw new Error('Another brain write is in progress. Retry; after a crashed writer, remove runtime/brain-write.lock.');
+            throw error;
+        }
+        try {
+            fs.writeSync(descriptor, String(process.pid));
+            return fn();
+        }
+        finally {
+            fs.closeSync(descriptor);
+            fs.unlinkSync(file);
+        }
+    }
+    allKnowledge() {
+        const result = [];
+        for (const { scope, directory } of this.scopes) {
+            const directories = [...Object.entries(exports.knowledgeDirectories), ['memory', path.join('notes', 'memory')]];
+            if (scope === 'global')
+                directories.push(['memory', path.relative(directory, path.join(this.configRoot, 'notes', 'memory'))]);
+            for (const [type, folder] of directories) {
+                for (const file of this.files(path.join(directory, folder))) {
+                    const text = this.read(file);
+                    const document = readMarkdown(text);
+                    const source = path.relative(this.configRoot, file);
+                    const legacy = document.metadata !== null && typeof document.metadata === 'object' && !Array.isArray(document.metadata)
+                        && !('id' in document.metadata) && !('type' in document.metadata);
+                    const legacyStatus = legacy ? document.metadata.status : undefined;
+                    const metadata = document.metadata === null || legacy ? {
+                        id: `document-${hash(source).slice(0, 24)}`, scope, type,
+                        title: /^#\s+(.+)$/m.exec(document.content)?.[1] ?? path.basename(file, '.md'),
+                        status: type === 'review' && ['addressed', 'resolved', 'done', 'closed'].includes(String(legacyStatus)) ? 'deprecated' : 'active',
+                        created: '', updated: ''
+                    } : { title: /^#\s+(.+)$/m.exec(document.content)?.[1] ?? path.basename(file, '.md'), ...document.metadata };
+                    const parsed = exports.knowledgeMetadata.safeParse(metadata);
+                    if (!parsed.success)
+                        throw new Error(`Invalid knowledge metadata in ${source}: ${parsed.error.message}`);
+                    if (parsed.data.scope !== scope)
+                        throw new Error(`Knowledge scope does not match its directory: ${source}`);
+                    result.push({ ...parsed.data, content: legacy ? text.trim() : document.content, source, revision: hash(text) });
+                }
+            }
+        }
+        const ids = new Set();
+        for (const item of result) {
+            if (ids.has(item.id))
+                throw new Error(`Duplicate knowledge id: ${item.id}`);
+            ids.add(item.id);
+        }
+        return result;
+    }
+    search(query, options = {}) {
+        const items = this.allKnowledge();
+        const environment = this.profile ?? 'default';
+        this.db.exec('BEGIN IMMEDIATE');
+        try {
+            this.db.prepare('DELETE FROM knowledge WHERE environment = ?').run(environment);
+            const insert = this.db.prepare('INSERT INTO knowledge(source, environment, title, content, tags) VALUES (?, ?, ?, ?, ?)');
+            for (const item of items)
+                insert.run(item.source, environment, item.title, item.content, [...item.tags, item.finding ?? ''].join(' ').trim());
+            this.db.exec('COMMIT');
+        }
+        catch (error) {
+            this.db.exec('ROLLBACK');
+            throw error;
+        }
+        const terms = query.match(/[\p{L}\p{N}_-]+/gu)?.slice(0, 50) ?? [];
+        const ranked = terms.length ? this.db.prepare('SELECT source FROM knowledge WHERE knowledge MATCH ? AND environment = ? ORDER BY bm25(knowledge, 0, 0, 5, 1, 3), source')
+            .all(terms.map((term) => `"${term.replace(/"/g, '""')}"`).join(' OR '), environment).map((row) => String(row.source)) : items.map((item) => item.source);
+        const bySource = new Map(items.map((item) => [item.source, item]));
+        return ranked.map((source) => bySource.get(source)).filter((item) => (options.includeDeprecated || item.status === 'active') && (!options.scopes || options.scopes.includes(item.scope)) &&
+            (!options.types || options.types.includes(item.type))).slice(0, options.limit ?? 50);
+    }
+    context(task, files = [], symbols = []) {
+        const all = this.allKnowledge().filter((item) => item.status === 'active');
+        const always = all.filter((item) => item.recall === 'always');
+        const matching = all.filter((item) => item.applies_to.some((pattern) => files.some((file) => {
+            const relative = path.isAbsolute(file) ? path.relative(this.projectRoot, file) : file;
+            return path.matchesGlob(relative, pattern);
+        })));
+        const selected = [...new Map([...always, ...matching, ...this.search([task, ...symbols].join(' '))].map((item) => [item.id, item])).values()];
+        let size = 0;
+        const items = selected.filter((item) => {
+            const length = JSON.stringify(item).length;
+            if (size + length > this.budget)
+                return false;
+            size += length;
+            return true;
+        });
+        return { items, omitted: selected.length - items.length, profile: this.profile, scopes: this.scopes.map((scope) => scope.scope) };
+    }
+    remember(input) {
+        const value = exports.knowledgeInput.parse(input);
+        if (value.authority === 'inferred' && value.type !== 'observation' && value.type !== 'memory' && value.type !== 'review') {
+            throw new Error('Inferred knowledge must remain an observation, memory, or review until explicitly confirmed.');
+        }
+        if (value.scope === 'global' && value.authority !== 'user')
+            throw new Error('Global writes require explicit user authority.');
+        if (value.type === 'review' && !value.severity)
+            throw new Error('Review findings require a severity: critical, high, medium, or low.');
+        if (value.type !== 'review' && value.severity)
+            throw new Error('Severity applies only to review findings.');
+        return this.writeLocked(() => {
+            const now = new Date().toISOString();
+            const { content, filename, ...metadata } = value;
+            const review = value.severity ? { finding: this.nextFinding(value.scope, value.severity), state: 'open' } : {};
+            const item = { ...metadata, ...review, id: (0, node_crypto_1.randomUUID)(), status: 'active', created: now, updated: now };
+            const directory = path.join(this.scopeDirectory(value.scope), exports.knowledgeDirectories[value.type]);
+            this.atomicWrite(this.availableFile(directory, filename, item.id), `---\n${(0, yaml_1.stringify)(item)}---\n\n${content}\n`);
+            return this.allKnowledge().find((entry) => entry.id === item.id);
+        });
+    }
+    /** Chosen name when one is given and free, otherwise the same name with the id appended. */
+    availableFile(directory, filename, id) {
+        if (!filename)
+            return path.join(directory, `${id}.md`);
+        const preferred = path.join(directory, `${filename}.md`);
+        return fs.existsSync(preferred) ? path.join(directory, `${filename}-${id}.md`) : preferred;
+    }
+    /** Revise an item in place, keeping its id, filename, scope, type, authority, and history. */
+    amend(id, revision, changes) {
+        const parsed = exports.knowledgeChanges.parse(changes);
+        if (Object.keys(parsed).length === 0)
+            throw new Error('Supply at least one field to change.');
+        return this.writeLocked(() => {
+            const item = this.get(id);
+            if (item.revision !== revision)
+                throw new Error('Knowledge changed; read the current revision before amending.');
+            if (item.status !== 'active')
+                throw new Error('Deprecated knowledge cannot be amended.');
+            const { source, revision: _revision, content, ...metadata } = item;
+            const { content: nextContent, ...nextMetadata } = parsed;
+            this.atomicWrite(source, `---\n${(0, yaml_1.stringify)({ ...metadata, ...nextMetadata, updated: new Date().toISOString() })}---\n\n${nextContent ?? content}\n`);
+            return this.get(id);
+        });
+    }
+    /** Next unused finding label for a severity, counting resolved findings so numbers are never reused. */
+    nextFinding(scope, severity) {
+        const prefix = severityPrefix[severity];
+        const used = this.allKnowledge()
+            .filter((item) => item.scope === scope && item.type === 'review' && item.finding?.startsWith(prefix))
+            .map((item) => Number.parseInt(item.finding.slice(prefix.length), 10))
+            .filter((sequence) => Number.isSafeInteger(sequence));
+        return `${prefix}${Math.max(0, ...used) + 1}`;
+    }
+    /** Review findings in severity then sequence order. Open findings only unless states are given. */
+    reviews(options = {}) {
+        const sequence = (item) => Number.parseInt(item.finding.slice(1), 10);
+        return this.allKnowledge()
+            .filter((item) => item.type === 'review' && item.finding && item.severity)
+            .filter((item) => !options.severity || options.severity.includes(item.severity))
+            .filter((item) => (options.state ?? ['open']).includes(item.state ?? 'open'))
+            .sort((left, right) => severityOrder[left.severity] - severityOrder[right.severity] || sequence(left) - sequence(right));
+    }
+    resolveReview(id, revision, state, reason) {
+        return this.writeLocked(() => {
+            const item = this.get(id);
+            if (item.type !== 'review' || !item.finding)
+                throw new Error('Only review findings can be resolved.');
+            if (item.revision !== revision)
+                throw new Error('Knowledge changed; read the current revision before updating.');
+            const { source, revision: _revision, content, ...metadata } = item;
+            this.atomicWrite(source, `---\n${(0, yaml_1.stringify)({ ...metadata, state, status: 'deprecated', updated: new Date().toISOString(), ...(reason ? { reason } : {}) })}---\n\n${content}\n`);
+            return this.get(id);
+        });
+    }
+    deprecate(id, revision, reason) {
+        return this.writeLocked(() => {
+            const item = this.get(id);
+            if (item.revision !== revision)
+                throw new Error('Knowledge changed; read the current revision before updating.');
+            const { source, revision: _revision, content, ...metadata } = item;
+            this.atomicWrite(source, `---\n${(0, yaml_1.stringify)({ ...metadata, status: 'deprecated', updated: new Date().toISOString(), ...(reason ? { reason } : {}) })}---\n\n${content}\n`);
+            return this.get(id);
+        });
+    }
+    promote(id, scope, revision) {
+        return this.writeLocked(() => {
+            const item = this.get(id);
+            if (item.revision !== revision)
+                throw new Error('Knowledge changed; read the current revision before promoting.');
+            if (item.status !== 'active')
+                throw new Error('Deprecated knowledge cannot be promoted.');
+            if (item.scope === scope)
+                throw new Error('Knowledge already belongs to this scope.');
+            const { source: _source, revision: _revision, content, ...metadata } = item;
+            const renumbered = item.severity ? { finding: this.nextFinding(scope, item.severity) } : {};
+            const promoted = { ...metadata, ...renumbered, id: (0, node_crypto_1.randomUUID)(), scope, authority: 'user', promoted_from: id, updated: new Date().toISOString() };
+            const target = path.join(this.scopeDirectory(scope), exports.knowledgeDirectories[item.type]);
+            this.atomicWrite(this.availableFile(target, path.basename(item.source, '.md'), promoted.id), `---\n${(0, yaml_1.stringify)(promoted)}---\n\n${content}\n`);
+            return this.get(promoted.id);
+        });
+    }
+    get(id) {
+        const item = this.allKnowledge().find((entry) => entry.id === id);
+        if (!item)
+            throw new Error(`Knowledge not found in the active scopes: ${id}`);
+        return item;
+    }
+}
+exports.BrainStore = BrainStore;