@hmharness/evolution 0.1.0

package/dist/patches.d.ts.bad-1788466569598

@@ -0,0 +1,75 @@
+/**
+ * @hmh/evolution - patches
+ * CODE-LEVEL self-evolution: the evolution loop can now propose source-code
+ * patches (not just prompt-level skills), test them on an isolated git
+ * branch, and merge or revert based on the benchmark gate.
+ *
+ * The Darwin Gödel Machine insight: an agent that can only take notes
+ * (skills/memory) learns WHAT to do; an agent that can patch its own code
+ * learns WHAT IT CAN DO. This module is the bridge.
+ *
+ * Safety model (same shape as the skill gate, extended to code):
+ *  1. patches may only modify files under packages/.../src/ (never config,
+ *     never security code, never the kernel loop itself)
+ *  2. every patch runs on a git branch (sandbox), never on main
+ *  3. the bench gate must show no regression (same double-sample rule)
+ *  4. revert = git checkout main + branch delete (zero residue)
+ */
+import { readFile } from 'node:fs/promises';
+/** A proposed code change: find-and-replace in one source file. */
+export interface CodePatch {
+    name: string;
+    description: string;
+    /** relative path from repo root, must match packages/.../src/.../*.ts */
+    file: string;
+    /** exact string to find in the file (must be unique) */
+    find: string;
+    /** replacement string */
+    replace: string;
+    /** why this change helps (for the audit log) */
+    reason: string;
+}
+export interface PatchOutcome {
+    name: string;
+    action: 'merged' | 'reverted' | 'error';
+    reason: string;
+    branch?: string;
+}
+/** Guard: only source files inside packages, never kernel internals. */
+export declare function isPatchableFile(file: string): boolean;
+/** Validate + apply a patch to a file on disk. Returns error if find-string
+ *  is not found or not unique. */
+export declare function applyPatch(repoRoot: string, patch: CodePatch): Promise<string>;
+/** Create a sandbox git branch for testing a patch. */
+export declare function createSandbox(repoRoot: string, name: string): Promise<string>;
+/** Commit the patch on the sandbox branch so it is fully isolated from main. */
+export declare function commitOnSandbox(repoRoot: string, patchName: string): Promise<void>;
+/** Merge the sandbox branch back to main (patch promoted). */
+export declare function mergeSandbox(repoRoot: string, branch: string): Promise<void>;
+/** Run the bench gate on the current branch. Returns pass rate (0-1) or -1 on build failure. */
+export declare function sandboxBench(repoRoot: string, runCase: (c: import('./bench.ts').BenchCase, skillsPrompt: string) => Promise<string>, cases: import('./bench.ts').BenchCase[]): Promise<number>;
+/** Revert: go back to main, delete the sandbox branch (zero residue). */
+export declare function revertSandbox(repoRoot: string, branch: string): Promise<void>;
+/**
+ * Full sandbox cycle: apply patch on a branch, rebuild, bench, merge or revert.
+ * This is the CODE-LEVEL equivalent of the skill A/B gate.
+ */
+export declare function runPatchSandbox(opts: {
+    repoRoot: string;
+    patch: CodePatch;
+    baselineRate: number;
+    runCase: (c: import('./bench.ts').BenchCase, skillsPrompt: string) => Promise<string>;
+    benchCases: import('./bench.ts').BenchCase[];
+    log?: (line: string) => void;
+}): Promise<PatchOutcome>;
+/**
+ * Meta-model call: propose code patches from session signals.
+ * The model sees the signals + the target file's current source and
+ * outputs find/replace pairs. Constrained to optimization prompts:
+ * fix a bug, speed up a hot path, improve error messages.
+ */
+export declare function proposePatches(provider: {
+    baseUrl: string;
+    apiKey: string;
+    model: string;
+}, signals: Record<string, unknown>, readFileFn: typeof readFile, repoRoot: string, say: (l: string) => void): Promise<CodePatch[]>;

package/dist/patches.js

@@ -0,0 +1,238 @@
+/**
+ * @hmharness/evolution - patches
+ * CODE-LEVEL self-evolution: the evolution loop can now propose source-code
+ * patches (not just prompt-level skills), test them on an isolated git
+ * branch, and merge or revert based on the benchmark gate.
+ *
+ * The Darwin Gödel Machine insight: an agent that can only take notes
+ * (skills/memory) learns WHAT to do; an agent that can patch its own code
+ * learns WHAT IT CAN DO. This module is the bridge.
+ *
+ * Safety model (same shape as the skill gate, extended to code):
+ *  1. patches may only modify files under packages/.../src/ (never config,
+ *     never security code, never the kernel loop itself)
+ *  2. every patch runs on a git branch (sandbox), never on main
+ *  3. the bench gate must show no regression (same double-sample rule)
+ *  4. revert = git checkout main + branch delete (zero residue)
+ */
+import { readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const execCb = promisify(execFile);
+/** git executable: PATH first, then known Windows locations (this repo's
+ *  dev machine has git only outside the test-process PATH). */
+async function git(args, opts) {
+    const { homedir } = await import('node:os');
+    // .cmd shims can't execFile-spawn on modern Node (EINVAL) - real .exe only
+    const candidates = [
+        'git',
+        'C:\\Program Files\\Git\\cmd\\git.exe',
+        'C:\\Program Files (x86)\\Git\\cmd\\git.exe',
+        'C:\\Program Files\\Microsoft Visual Studio\\18\\Enterprise\\Common7\\IDE\\CommonExtensions\\Microsoft\\TeamFoundation\\Team Explorer\\Git\\cmd\\git.exe',
+    ];
+    let lastErr;
+    for (const exe of candidates) {
+        try {
+            return await execCb(exe, args, { ...opts, windowsHide: true });
+        }
+        catch (err) {
+            lastErr = err;
+            const msg = String(err);
+            if (!/ENOENT|not found|EINVAL/i.test(msg))
+                throw err; // real failure, not missing-exe
+        }
+    }
+    throw lastErr;
+}
+/** Guard: only source files inside packages, never kernel internals. */
+export function isPatchableFile(file) {
+    if (!/^packages\/[a-z-]+\/src\/[a-zA-Z0-9_/.-]+\.ts$/.test(file))
+        return false;
+    // never allow patching the kernel loop itself (bootstrapping paradox)
+    if (file.startsWith('packages/kernel/src/loop'))
+        return false;
+    if (file.startsWith('packages/kernel/src/provider'))
+        return false;
+    // never config or security
+    if (/config|security|mcp/.test(file))
+        return false;
+    return true;
+}
+/** Validate + apply a patch to a file on disk. Returns error if find-string
+ *  is not found or not unique. */
+export async function applyPatch(repoRoot, patch) {
+    if (!isPatchableFile(patch.file)) {
+        return `refused: ${patch.file} is not a patchable source file (must be packages/*/src/*.ts, not kernel loop/provider/config)`;
+    }
+    const filePath = join(repoRoot, patch.file);
+    let content;
+    try {
+        content = await readFile(filePath, 'utf8');
+    }
+    catch {
+        return `file not found: ${patch.file}`;
+    }
+    const count = content.split(patch.find).length - 1;
+    if (count === 0)
+        return `find-string not found in ${patch.file}`;
+    if (count > 1)
+        return `find-string appears ${count}x in ${patch.file} (must be unique)`;
+    const patched = content.replace(patch.find, patch.replace);
+    await writeFile(filePath, patched, 'utf8');
+    return 'applied';
+}
+/** Create a sandbox git branch for testing a patch. */
+export async function createSandbox(repoRoot, name) {
+    const branch = `evolve/${name}-${Date.now().toString(36)}`;
+    // stash any stray working-tree changes first so the branch starts clean
+    await git(['stash', '--include-untracked'], { cwd: repoRoot, timeout: 10_000 }).catch(() => undefined);
+    await git(['checkout', '-b', branch], { cwd: repoRoot, timeout: 10_000 });
+    return branch;
+}
+/** Commit the patch on the sandbox branch so it is fully isolated from main. */
+export async function commitOnSandbox(repoRoot, patchName) {
+    await git(['add', '-A'], { cwd: repoRoot, timeout: 10_000 });
+    await git(['commit', '-m', `evolve(code-patch): ${patchName}`, '--no-verify'], { cwd: repoRoot, timeout: 15_000 });
+}
+/** Merge the sandbox branch back to main (patch promoted). */
+export async function mergeSandbox(repoRoot, branch) {
+    await git(['checkout', 'main'], { cwd: repoRoot, timeout: 10_000 });
+    await git(['merge', '--no-edit', branch], { cwd: repoRoot, timeout: 15_000 });
+    await git(['branch', '-D', branch], { cwd: repoRoot, timeout: 5000 });
+}
+/** Run the bench gate on the current branch. Returns pass rate (0-1) or -1 on build failure. */
+export async function sandboxBench(repoRoot, runCase, cases) {
+    // rebuild all packages (the patch may affect any layer)
+    try {
+        await execCb('npm', ['run', 'build'], { cwd: repoRoot, timeout: 120_000, windowsHide: true });
+    }
+    catch {
+        return -1; // build failed = automatic reject
+    }
+    // double-sample rule: each case must pass BOTH runs
+    let pass = 0;
+    for (const c of cases) {
+        let ok = true;
+        for (let i = 0; i < 2 && ok; i++) {
+            try {
+                const out = await runCase(c, '');
+                ok = c.expect.every((e) => out.toLowerCase().includes(e.toLowerCase()));
+            }
+            catch {
+                ok = false;
+            }
+        }
+        if (ok)
+            pass++;
+    }
+    return cases.length > 0 ? pass / cases.length : -1;
+}
+/** Revert: go back to main, delete the sandbox branch (zero residue). */
+export async function revertSandbox(repoRoot, branch) {
+    await git(['checkout', 'main'], { cwd: repoRoot, timeout: 10_000 });
+    // discard any uncommitted changes on the sandbox branch
+    await git(['reset', '--hard', 'HEAD'], { cwd: repoRoot, timeout: 5000 });
+    await git(['branch', '-D', branch], { cwd: repoRoot, timeout: 5000 });
+}
+/**
+ * Full sandbox cycle: apply patch on a branch, rebuild, bench, merge or revert.
+ * This is the CODE-LEVEL equivalent of the skill A/B gate.
+ */
+export async function runPatchSandbox(opts) {
+    const say = opts.log ?? (() => undefined);
+    const { patch } = opts;
+    say(`  code-patch "${patch.name}": creating sandbox branch`);
+    let branch = '';
+    try {
+        branch = await createSandbox(opts.repoRoot, patch.name);
+        const applyResult = await applyPatch(opts.repoRoot, patch);
+        if (applyResult !== 'applied') {
+            await revertSandbox(opts.repoRoot, branch);
+            return { name: patch.name, action: 'error', reason: applyResult, branch };
+        }
+        // commit on the branch BEFORE benching: the patch must be fully isolated
+        // so a later checkout of main can never carry uncommitted patch changes
+        await commitOnSandbox(opts.repoRoot, patch.name);
+        say(`  code-patch "${patch.name}": applied + committed on branch, rebuilding + benching`);
+        const rate = await sandboxBench(opts.repoRoot, opts.runCase, opts.benchCases);
+        if (rate < 0) {
+            await revertSandbox(opts.repoRoot, branch);
+            return { name: patch.name, action: 'reverted', reason: 'build failed in sandbox', branch };
+        }
+        if (rate < opts.baselineRate) {
+            await revertSandbox(opts.repoRoot, branch);
+            return { name: patch.name, action: 'reverted', reason: `bench ${rate} < baseline ${opts.baselineRate}`, branch };
+        }
+        say(`  code-patch "${patch.name}": bench ${rate} >= baseline ${opts.baselineRate}, merging`);
+        await mergeSandbox(opts.repoRoot, branch);
+        return { name: patch.name, action: 'merged', reason: `bench ${rate} >= baseline (merged to main)`, branch };
+    }
+    catch (err) {
+        if (branch) {
+            try {
+                await revertSandbox(opts.repoRoot, branch);
+            }
+            catch { /* best effort */ }
+        }
+        return { name: patch.name, action: 'error', reason: String(err).slice(0, 200), branch };
+    }
+}
+/**
+ * Meta-model call: propose code patches from session signals.
+ * The model sees the signals + the target file's current source and
+ * outputs find/replace pairs. Constrained to optimization prompts:
+ * fix a bug, speed up a hot path, improve error messages.
+ */
+export async function proposePatches(provider, signals, readFileFn, repoRoot, say) {
+    // pick candidate files: the most-used tools from insights
+    const toolFiles = {
+        run_command: 'packages/agent/src/tools.ts',
+        web_search: 'packages/agent/src/tools.ts',
+        web_fetch: 'packages/agent/src/tools.ts',
+        harmony_build: 'packages/domain-harmony/src/index.ts',
+        harmony_devices: 'packages/domain-harmony/src/devices.ts',
+        // add more as insights reveal hot paths
+    };
+    const toolsUsed = (signals.toolUsage ?? {});
+    const hotTools = Object.entries(toolsUsed)
+        .filter(([t]) => toolFiles[t])
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 2)
+        .map(([t]) => t);
+    if (hotTools.length === 0)
+        return [];
+    const fileContents = {};
+    for (const t of hotTools) {
+        const f = toolFiles[t];
+        try {
+            fileContents[f] = (await readFileFn(join(repoRoot, f), 'utf8')).slice(0, 6000);
+        }
+        catch { /* skip */ }
+    }
+    const system = [
+        'You are the code-evolution module of hmharness. Given session signals and the CURRENT source of the most-used tool files, propose at most 1 code patch as a JSON object.',
+        'A patch is: {"name":"kebab-case","description":"one line","file":"packages/.../src/...ts","find":"exact string from the source (must be unique)","replace":"the improved code","reason":"why"}',
+        'Rules: ONLY optimize what the signals show is slow/broken/verbose. Keep patches SMALL (under 20 lines of change). Do NOT restructure. Do NOT touch security, config, or the agent loop. If nothing genuinely needs a code fix, return [].',
+        'Respond with ONLY a JSON array.',
+    ].join('\n');
+    const user = `Session signals:\n${JSON.stringify(signals, null, 2)}\n\nHot tool source files:\n${JSON.stringify(fileContents, null, 2)}\n\nPropose at most 1 patch (or []).`;
+    say('  code-evolution: asking meta-model for patch proposals');
+    try {
+        const { chat } = await import('@hmharness/kernel');
+        const r = await chat(provider, [
+            { role: 'system', content: system },
+            { role: 'user', content: user },
+        ]);
+        const text = r.message.content ?? '[]';
+        const start = text.indexOf('[');
+        const end = text.lastIndexOf(']');
+        if (start < 0 || end < 0)
+            return [];
+        const parsed = JSON.parse(text.slice(start, end + 1));
+        return parsed.filter((p) => p.file && p.find && p.replace && isPatchableFile(p.file));
+    }
+    catch {
+        return [];
+    }
+}

package/dist/patches.js.bad-1788466569598

@@ -0,0 +1,238 @@
+/**
+ * @hmh/evolution - patches
+ * CODE-LEVEL self-evolution: the evolution loop can now propose source-code
+ * patches (not just prompt-level skills), test them on an isolated git
+ * branch, and merge or revert based on the benchmark gate.
+ *
+ * The Darwin Gödel Machine insight: an agent that can only take notes
+ * (skills/memory) learns WHAT to do; an agent that can patch its own code
+ * learns WHAT IT CAN DO. This module is the bridge.
+ *
+ * Safety model (same shape as the skill gate, extended to code):
+ *  1. patches may only modify files under packages/.../src/ (never config,
+ *     never security code, never the kernel loop itself)
+ *  2. every patch runs on a git branch (sandbox), never on main
+ *  3. the bench gate must show no regression (same double-sample rule)
+ *  4. revert = git checkout main + branch delete (zero residue)
+ */
+import { readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const execCb = promisify(execFile);
+/** git executable: PATH first, then known Windows locations (this repo's
+ *  dev machine has git only outside the test-process PATH). */
+async function git(args, opts) {
+    const { homedir } = await import('node:os');
+    // .cmd shims can't execFile-spawn on modern Node (EINVAL) - real .exe only
+    const candidates = [
+        'git',
+        'C:\\Program Files\\Git\\cmd\\git.exe',
+        'C:\\Program Files (x86)\\Git\\cmd\\git.exe',
+        'C:\\Program Files\\Microsoft Visual Studio\\18\\Enterprise\\Common7\\IDE\\CommonExtensions\\Microsoft\\TeamFoundation\\Team Explorer\\Git\\cmd\\git.exe',
+    ];
+    let lastErr;
+    for (const exe of candidates) {
+        try {
+            return await execCb(exe, args, { ...opts, windowsHide: true });
+        }
+        catch (err) {
+            lastErr = err;
+            const msg = String(err);
+            if (!/ENOENT|not found|EINVAL/i.test(msg))
+                throw err; // real failure, not missing-exe
+        }
+    }
+    throw lastErr;
+}
+/** Guard: only source files inside packages, never kernel internals. */
+export function isPatchableFile(file) {
+    if (!/^packages\/[a-z-]+\/src\/[a-zA-Z0-9_/.-]+\.ts$/.test(file))
+        return false;
+    // never allow patching the kernel loop itself (bootstrapping paradox)
+    if (file.startsWith('packages/kernel/src/loop'))
+        return false;
+    if (file.startsWith('packages/kernel/src/provider'))
+        return false;
+    // never config or security
+    if (/config|security|mcp/.test(file))
+        return false;
+    return true;
+}
+/** Validate + apply a patch to a file on disk. Returns error if find-string
+ *  is not found or not unique. */
+export async function applyPatch(repoRoot, patch) {
+    if (!isPatchableFile(patch.file)) {
+        return `refused: ${patch.file} is not a patchable source file (must be packages/*/src/*.ts, not kernel loop/provider/config)`;
+    }
+    const filePath = join(repoRoot, patch.file);
+    let content;
+    try {
+        content = await readFile(filePath, 'utf8');
+    }
+    catch {
+        return `file not found: ${patch.file}`;
+    }
+    const count = content.split(patch.find).length - 1;
+    if (count === 0)
+        return `find-string not found in ${patch.file}`;
+    if (count > 1)
+        return `find-string appears ${count}x in ${patch.file} (must be unique)`;
+    const patched = content.replace(patch.find, patch.replace);
+    await writeFile(filePath, patched, 'utf8');
+    return 'applied';
+}
+/** Create a sandbox git branch for testing a patch. */
+export async function createSandbox(repoRoot, name) {
+    const branch = `evolve/${name}-${Date.now().toString(36)}`;
+    // stash any stray working-tree changes first so the branch starts clean
+    await git(['stash', '--include-untracked'], { cwd: repoRoot, timeout: 10_000 }).catch(() => undefined);
+    await git(['checkout', '-b', branch], { cwd: repoRoot, timeout: 10_000 });
+    return branch;
+}
+/** Commit the patch on the sandbox branch so it is fully isolated from main. */
+export async function commitOnSandbox(repoRoot, patchName) {
+    await git(['add', '-A'], { cwd: repoRoot, timeout: 10_000 });
+    await git(['commit', '-m', `evolve(code-patch): ${patchName}`, '--no-verify'], { cwd: repoRoot, timeout: 15_000 });
+}
+/** Merge the sandbox branch back to main (patch promoted). */
+export async function mergeSandbox(repoRoot, branch) {
+    await git(['checkout', 'main'], { cwd: repoRoot, timeout: 10_000 });
+    await git(['merge', '--no-edit', branch], { cwd: repoRoot, timeout: 15_000 });
+    await git(['branch', '-D', branch], { cwd: repoRoot, timeout: 5000 });
+}
+/** Run the bench gate on the current branch. Returns pass rate (0-1) or -1 on build failure. */
+export async function sandboxBench(repoRoot, runCase, cases) {
+    // rebuild all packages (the patch may affect any layer)
+    try {
+        await execCb('npm', ['run', 'build'], { cwd: repoRoot, timeout: 120_000, windowsHide: true });
+    }
+    catch {
+        return -1; // build failed = automatic reject
+    }
+    // double-sample rule: each case must pass BOTH runs
+    let pass = 0;
+    for (const c of cases) {
+        let ok = true;
+        for (let i = 0; i < 2 && ok; i++) {
+            try {
+                const out = await runCase(c, '');
+                ok = c.expect.every((e) => out.toLowerCase().includes(e.toLowerCase()));
+            }
+            catch {
+                ok = false;
+            }
+        }
+        if (ok)
+            pass++;
+    }
+    return cases.length > 0 ? pass / cases.length : -1;
+}
+/** Revert: go back to main, delete the sandbox branch (zero residue). */
+export async function revertSandbox(repoRoot, branch) {
+    await git(['checkout', 'main'], { cwd: repoRoot, timeout: 10_000 });
+    // discard any uncommitted changes on the sandbox branch
+    await git(['reset', '--hard', 'HEAD'], { cwd: repoRoot, timeout: 5000 });
+    await git(['branch', '-D', branch], { cwd: repoRoot, timeout: 5000 });
+}
+/**
+ * Full sandbox cycle: apply patch on a branch, rebuild, bench, merge or revert.
+ * This is the CODE-LEVEL equivalent of the skill A/B gate.
+ */
+export async function runPatchSandbox(opts) {
+    const say = opts.log ?? (() => undefined);
+    const { patch } = opts;
+    say(`  code-patch "${patch.name}": creating sandbox branch`);
+    let branch = '';
+    try {
+        branch = await createSandbox(opts.repoRoot, patch.name);
+        const applyResult = await applyPatch(opts.repoRoot, patch);
+        if (applyResult !== 'applied') {
+            await revertSandbox(opts.repoRoot, branch);
+            return { name: patch.name, action: 'error', reason: applyResult, branch };
+        }
+        // commit on the branch BEFORE benching: the patch must be fully isolated
+        // so a later checkout of main can never carry uncommitted patch changes
+        await commitOnSandbox(opts.repoRoot, patch.name);
+        say(`  code-patch "${patch.name}": applied + committed on branch, rebuilding + benching`);
+        const rate = await sandboxBench(opts.repoRoot, opts.runCase, opts.benchCases);
+        if (rate < 0) {
+            await revertSandbox(opts.repoRoot, branch);
+            return { name: patch.name, action: 'reverted', reason: 'build failed in sandbox', branch };
+        }
+        if (rate < opts.baselineRate) {
+            await revertSandbox(opts.repoRoot, branch);
+            return { name: patch.name, action: 'reverted', reason: `bench ${rate} < baseline ${opts.baselineRate}`, branch };
+        }
+        say(`  code-patch "${patch.name}": bench ${rate} >= baseline ${opts.baselineRate}, merging`);
+        await mergeSandbox(opts.repoRoot, branch);
+        return { name: patch.name, action: 'merged', reason: `bench ${rate} >= baseline (merged to main)`, branch };
+    }
+    catch (err) {
+        if (branch) {
+            try {
+                await revertSandbox(opts.repoRoot, branch);
+            }
+            catch { /* best effort */ }
+        }
+        return { name: patch.name, action: 'error', reason: String(err).slice(0, 200), branch };
+    }
+}
+/**
+ * Meta-model call: propose code patches from session signals.
+ * The model sees the signals + the target file's current source and
+ * outputs find/replace pairs. Constrained to optimization prompts:
+ * fix a bug, speed up a hot path, improve error messages.
+ */
+export async function proposePatches(provider, signals, readFileFn, repoRoot, say) {
+    // pick candidate files: the most-used tools from insights
+    const toolFiles = {
+        run_command: 'packages/agent/src/tools.ts',
+        web_search: 'packages/agent/src/tools.ts',
+        web_fetch: 'packages/agent/src/tools.ts',
+        harmony_build: 'packages/domain-harmony/src/index.ts',
+        harmony_devices: 'packages/domain-harmony/src/devices.ts',
+        // add more as insights reveal hot paths
+    };
+    const toolsUsed = (signals.toolUsage ?? {});
+    const hotTools = Object.entries(toolsUsed)
+        .filter(([t]) => toolFiles[t])
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 2)
+        .map(([t]) => t);
+    if (hotTools.length === 0)
+        return [];
+    const fileContents = {};
+    for (const t of hotTools) {
+        const f = toolFiles[t];
+        try {
+            fileContents[f] = (await readFileFn(join(repoRoot, f), 'utf8')).slice(0, 6000);
+        }
+        catch { /* skip */ }
+    }
+    const system = [
+        'You are the code-evolution module of hmharness. Given session signals and the CURRENT source of the most-used tool files, propose at most 1 code patch as a JSON object.',
+        'A patch is: {"name":"kebab-case","description":"one line","file":"packages/.../src/...ts","find":"exact string from the source (must be unique)","replace":"the improved code","reason":"why"}',
+        'Rules: ONLY optimize what the signals show is slow/broken/verbose. Keep patches SMALL (under 20 lines of change). Do NOT restructure. Do NOT touch security, config, or the agent loop. If nothing genuinely needs a code fix, return [].',
+        'Respond with ONLY a JSON array.',
+    ].join('\n');
+    const user = `Session signals:\n${JSON.stringify(signals, null, 2)}\n\nHot tool source files:\n${JSON.stringify(fileContents, null, 2)}\n\nPropose at most 1 patch (or []).`;
+    say('  code-evolution: asking meta-model for patch proposals');
+    try {
+        const { chat } = await import('@hmh/kernel');
+        const r = await chat(provider, [
+            { role: 'system', content: system },
+            { role: 'user', content: user },
+        ]);
+        const text = r.message.content ?? '[]';
+        const start = text.indexOf('[');
+        const end = text.lastIndexOf(']');
+        if (start < 0 || end < 0)
+            return [];
+        const parsed = JSON.parse(text.slice(start, end + 1));
+        return parsed.filter((p) => p.file && p.find && p.replace && isPatchableFile(p.file));
+    }
+    catch {
+        return [];
+    }
+}

package/dist/radar.d.ts

@@ -0,0 +1,3 @@
+/** The newest radar brief, capped (the meta-model needs a headline, not
+ *  the whole document; stale-brief protection via the filename date). */
+export declare function latestRadarBrief(home: string, maxChars?: number, maxAgeDays?: number): Promise<string | null>;

package/dist/radar.js

@@ -0,0 +1,40 @@
+/**
+ * @hmharness/evolution - radar (ops-signal feed)
+ * The ops keeper's ecosystem radar scans OpenHarmony release sources and
+ * writes dated briefs (home/ops/briefs/YYYY-MM-DD.md). This module hands
+ * the NEWEST brief text to the evolution loop as context: toolchain flags
+ * and API surfaces move with releases, and a skill proposal that doesn't
+ * know "ArkUI 5.1.2 shipped last week" proposes stale advice.
+ *
+ * Read-only and best-effort: evolution never triggers a scan (that's
+ * `hmh ops scan`'s own budgeted job) - it reads what the keeper already
+ * published, and an absent brief simply means no ecosystem signal.
+ */
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+/** The newest radar brief, capped (the meta-model needs a headline, not
+ *  the whole document; stale-brief protection via the filename date). */
+export async function latestRadarBrief(home, maxChars = 1200, maxAgeDays = 14) {
+    const dir = join(home, 'ops', 'briefs');
+    let files;
+    try {
+        files = (await readdir(dir)).filter((f) => /^\d{4}-\d{2}-\d{2}\.md$/.test(f)).sort();
+    }
+    catch {
+        return null;
+    }
+    const latest = files[files.length - 1];
+    if (!latest)
+        return null;
+    const date = latest.replace(/\.md$/, '');
+    if (Date.now() - new Date(date + 'T00:00:00Z').getTime() > maxAgeDays * 86400_000) {
+        return null; // too old to be ecosystem "news"
+    }
+    try {
+        const text = (await readFile(join(dir, latest), 'utf8')).trim();
+        return text.length > 20 ? text.slice(0, maxChars) : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/skills.d.ts

@@ -0,0 +1,54 @@
+export type SkillState = 'draft' | 'canary' | 'active' | 'archived';
+export interface SkillEntry {
+    name: string;
+    description: string;
+    file: string;
+    state: SkillState;
+}
+/** Skills the user pinned: evolution never moves, merges or decays them.
+ *  Marked by a .pin file next to SKILL.md (cheap, visible, git-friendly). */
+export declare function pinSkill(home: string, name: string): Promise<boolean>;
+export declare function unpinSkill(home: string, name: string): Promise<boolean>;
+export declare function isPinned(file: string): Promise<boolean>;
+/**
+ * Install skills from a git URL or a local directory (`hmh skills add <src>`).
+ * Handles the three common repo layouts: SKILL.md at the root (single skill),
+ * skills/<name>/SKILL.md (multi-skill pack, e.g. greensock/gsap-skills), and
+ * <name>/SKILL.md one level down. Existing skill names are never overwritten.
+ */
+export declare function installSkills(src: string, home: string): Promise<{
+    installed: string[];
+    skipped: string[];
+}>;
+export declare function listSkills(home: string): Promise<SkillEntry[]>;
+export declare function listDrafts(home: string): Promise<SkillEntry[]>;
+/** Canary-state skills: promoted through the bench gates but still under
+ *  impact evaluation - injected into a sample of sessions, watermarked. */
+export declare function listCanary(home: string): Promise<SkillEntry[]>;
+export declare function skillsToPrompt(entries: SkillEntry[]): string;
+/** Write (or overwrite) a draft; drafts are cheap and reversible by deletion. */
+export declare function writeDraft(home: string, name: string, skillMd: string): Promise<string>;
+/**
+ * Promote a draft. Default target is `canary` (P0: bench-passing skills
+ * earn a canary slot first; full activation happens through the impact
+ * loop, not on the gate alone). `{canary: false}` promotes straight to
+ * active (used by the impact loop once evidence clears, and by `hmh skills
+ * promote`). If a same-name skill exists at the destination it is archived
+ * first (timestamped snapshot) so promotion is always reversible.
+ */
+export declare function promoteSkill(home: string, name: string, opts?: {
+    canary?: boolean;
+}): Promise<{
+    file: string;
+    archivedPrevious: boolean;
+}>;
+/** Graduate a canary skill to full active (the impact loop's decision). */
+export declare function promoteCanary(home: string, name: string): Promise<boolean>;
+/** Retire a canary skill back to draft (impact loop's rejection path) -
+ *  nothing is ever deleted (append-only red line). */
+export declare function retireCanary(home: string, name: string): Promise<boolean>;
+/** Restore the most recent archived snapshot of a skill back to active. */
+export declare function rollbackSkill(home: string, name: string): Promise<boolean>;
+/** Demote an active skill back to draft without deleting anything. */
+export declare function unpromoteSkill(home: string, name: string): Promise<boolean>;
+export declare function deleteDraft(home: string, name: string): Promise<boolean>;