@zenera/cli 1.1.25 → 1.1.26

package/dist/meta/finetune/command.js

@@ -1,30 +1,37 @@
 import { liveHolder } from '@zenera/neo';
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, writeFileSync, } from 'node:fs';
+import { join, resolve } from 'node:path';
 import { editorFiles } from "../editor.js";
-import { bold, cyan, dim, green, invalidError, json, note, parse, red, usageError, write, yellow, } from "../host.js";
+import { bold, CliError, cyan, dim, EXIT, green, invalidError, json, note, parse, red, usageError, write, yellow, } from "../host.js";
+import { costChanges, measure, overLimits } from "./cost.js";
 import { drift } from "./dataset/drift.js";
 import { DatasetStore } from "./dataset/store.js";
 import { runLoop } from "./loop.js";
-import { attemptsOf } from "./report.js";
+import { analyzeSession, attemptsOf } from "./report.js";
 import { retry } from "./retry.js";
 import { resultOf, selection } from "./sampler.js";
-import { DEFAULTS, FAILURES_IN_A_ROW, FINETUNE_DIR, LEGACY_FINETUNE_DIR, spawnZen, Tuning, } from "./tuning.js";
+import { DEFAULTS, FAILURES_IN_A_ROW, FINETUNE_DIR, LEGACY_FINETUNE_DIR, readJson, spawnZen, Tuning, } from "./tuning.js";
+import { liveView, startView } from "./view.js";
 // ---------------------------------------------------------------------------
 // zen meta finetune
 // ---------------------------------------------------------------------------
-export const FINETUNE_USAGE = 'zen meta finetune <start|status|stop|retry|session> [options]';
+export const FINETUNE_USAGE = 'zen meta finetune <start|status|stop|serve|retry|session|gate> [options]';
 export const FINETUNE_HELP = [
     'Tuning:',
     '  zen meta finetune start [options]         train every case: run, analyze, apply, run again',
     '  zen meta finetune [status]                where it stands; the detail is finetune/STATUS.md',
     '  zen meta finetune stop                    finish the steps in flight, then stop',
+    '  zen meta finetune serve                   the tuning live in a browser, while it is not running',
     '  zen meta finetune retry --difficult       give difficult cases another round, then start',
-    "  zen meta finetune session <case>          resume that case's analyze session",
+    "  zen meta finetune session <case>          resume the analyze session of that case's latest try",
+    '  zen meta finetune gate <apply dir>        would this apply pass? - for the apply agent',
     '',
-    '  start: -N <workers> (4), -M <apply at> (= workers), --tries <n> (4), --mem-tries <n> (3),',
-    '  --merge-every <k> (3), --seed <n>, --class <c>, --id <glob>, --rubric yes|no, --limit <n>,',
-    '  --force (past drift).',
+    '  start: -N <workers> (4), -M <apply at> (4), --tries <n> (4), --mem-tries <n> (3),',
+    '  --class <c>, --id <glob>, --rubric yes|no, --limit <n> and --more <n> (this start only);',
+    '  what an apply may do: --budget <bytes> (1500), --max-growth <pct> (50),',
+    '  --skill-cap <bytes> (12000), --max-skills <n> (10); after it, --recheck <n> (3).',
+    '  More - --merge-every, --seed, --force: zen meta finetune --help.',
     '  In a terminal start draws what runs now, the tokens and the log; --plain does not.',
     '  Settings are kept in finetune/loop.json; start again to resume where it stopped.',
 ];
@@ -35,42 +42,74 @@ export const FINETUNE_DETAILS = [
     '  start                  Train every case: run, analyze, apply, run again. Resumes.',
     '  status                 Where it stands (the default). The detail: finetune/STATUS.md',
     '  stop                   Let the steps in flight finish, then stop the running tuning.',
+    '  serve                  Show the tuning live in a browser until Ctrl-C. start does this',
+    '                         itself, and prints the address; serve is for when it is not running.',
     '  retry [ids...]         Another round for difficult cases: --difficult takes them all,',
     '                         ids and globs add to it, --class narrows. Run them with start.',
-    "  session <case>         Print the command that resumes that case's analyze session.",
+    "  session <case>         Print the command that resumes the analyze session of that case's",
+    '                         latest try.',
+    '  gate <apply dir>       Judge an apply in progress as the loop will: bytes moved per',
+    '                         agent, skill and file, any limit broken, and zen check.',
+    '                         Exits 1 when it would be undone. Read-only.',
     '',
-    'Options for start:',
+    'Which cases (start):',
+    '  --class <c>            Only this class. Repeatable.',
+    '  --id <glob>            Only cases whose id matches. Repeatable.',
+    '  --rubric yes|no        Only cases with, or without, a rubric.',
+    '  --limit <n>            Only the first n cases of the order. Not kept.',
+    '  --more <n>             Take at most n cases - new, part-way or failed - then stop.',
+    '                         Parked cases it took still finish. Not kept.',
+    '',
+    'How it runs (start):',
     '  -N, --workers <n>      Cases trained at once. Default 4.',
-    '  -M, --apply-at <n>     Apply once this many requests wait. Default: the workers.',
+    '  -M, --apply-at <n>     Apply once this many cases wait for a fix. Default 4, min 2.',
     '  --tries <n>            Tries without memory before a case is difficult. Default 4.',
     '  --mem-tries <n>        Tries with memory. Default 3.',
     '  --merge-every <k>      Merge the kept memories after k more arrive. Default 3.',
     '  --seed <n>             Order of cases inside a class. Default 1.',
-    '  --class <c>            Only this class. Repeatable.',
-    '  --id <glob>            Only cases whose id matches. Repeatable.',
-    '  --rubric yes|no        Only cases with, or without, a rubric.',
-    '  --limit <n>            Only the first n cases of the order.',
-    '  --force                Start even though the dataset drifted from its sources.',
+    '',
+    'What an apply may do (start):',
+    '  --budget <bytes>       Most one apply may add to what every call reads. Default 1500.',
+    '  --max-growth <pct>     Once that is this much over its size when the tuning began,',
+    '                         an apply may add nothing. Default 50.',
+    '  --skill-cap <bytes>    Most one skill may hold. Default 12000.',
+    '  --max-skills <n>       Most skills one agent may see. Default 10.',
+    '  --recheck <n>          After each apply, run this many completed cases again on it;',
+    '                         one that fails both tries sends its fixes to the next apply.',
+    '                         Default 3, 0 none.',
+    '',
+    'Other (start):',
+    '  --force                Start past dataset drift, and allow -M 1.',
     '  --plain                No live view: print a line per start and stop, as in a pipe.',
     '  --project <name|dir>   Which project. Default: the one you are in.',
     '',
     'One case: without memory, run it and /analyze it until the analysis says done -',
     'parking it until the next apply after each try that is not - then the same with',
-    'the memory the passing run wrote. Tries used up: the case is difficult.',
+    'the memory the passing run wrote. Tries used up: the case is difficult. Each try',
+    'has its own private memory; passing memories are merged into finetune/memories/.',
     '',
-    'No run shares a memory: each try has its own private directory. A case whose',
-    'with-memory run passes submits a copy of that memory; every k submissions are',
-    'merged, with the last merge, into finetune/memories/merged/mNN - numbered,',
-    'never rewritten, each listing the cases it holds.',
+    'A parked case gives its worker back; woken cases take a worker before new ones.',
+    '/finetune-apply fixes the parked cases together: when -M wait, or once nothing',
+    'else can run. No run starts during an apply. What it may do:',
+    '  - Every call reads the house rules, the prompt, preloaded skills and one line per',
+    '    skill, so that is what --budget counts. A skill body is paid only once loaded:',
+    '    moving a procedure from a prompt into a skill is a saving.',
+    '  - One case is an anecdote. A new rule needs two cases asking for it; one is',
+    '    deferred and offered to every later apply until a second asks.',
+    '  - A skill made for a case must be loaded by its next run, or the next apply',
+    '    fixes the description.',
+    '  - It tidies up after itself: the files it touched lose their duplicates and',
+    '    contradictions in the same edit.',
+    '  - zen check must pass and the budget hold, or the edit is undone and tried once',
+    '    more. A second zen check failure stops the tuning; a second budget failure only',
+    '    undoes the apply.',
+    'Every apply is a new version of agents.yaml + agents/. Then --recheck completed',
+    'cases run again on it, as ordinary work - nothing waits. One that fails both tries',
+    'has regressed: its fixes join the queue, and the next apply repairs what broke.',
     '',
-    'A parked case gives its worker back, so another case runs meanwhile; woken cases',
-    'take a worker before new ones. Requests are applied in batches by /finetune-apply:',
-    'when -M cases are parked, or once nothing is running and no case is left to start.',
-    'No run starts during an apply. zen check must pass,',
-    'or the edit is undone. Every apply is a new version of agents.yaml + agents/.',
-    '',
-    'A case is difficult when its tries run out and the analysis still says no; that is',
-    'final for its revision until `retry` gives it another round on the prose of the day.',
+    'A case is difficult when its tries run out and the analysis still says no, or at',
+    'once when all an apply could say of it is structural - a tool, a skill binding,',
+    'the dataset. That is final for its revision until `retry` gives it another round.',
     'A case fails instead when something outside the prose broke - the sandbox, a',
     'provider, a key: it keeps its tries and carries on from that step at the next start.',
     `After ${FAILURES_IN_A_ROW} failures in a row the tuning stops, and says what broke;`,
@@ -84,6 +123,8 @@ export const FINETUNE_DETAILS = [
     'Examples:',
     '  zen meta finetune start -N 4',
     '  zen meta finetune start --class search --limit 6 -N 2 -M 2',
+    '  zen meta finetune start --limit 4 --recheck 0    # quick, cheap',
+    '  zen meta finetune start --more 4',
     '  zen meta finetune',
     '  zen meta finetune retry --difficult --class merge',
     '  zen meta finetune session plan-day',
@@ -96,10 +137,16 @@ const OPTIONS = {
     'mem-tries': { type: 'string' },
     'merge-every': { type: 'string' },
     seed: { type: 'string' },
+    recheck: { type: 'string' },
+    budget: { type: 'string' },
+    'max-growth': { type: 'string' },
+    'skill-cap': { type: 'string' },
+    'max-skills': { type: 'string' },
     class: { type: 'string', multiple: true },
     id: { type: 'string', multiple: true },
     rubric: { type: 'string' },
     limit: { type: 'string' },
+    more: { type: 'string' },
     force: { type: 'boolean' },
     plain: { type: 'boolean' },
     difficult: { type: 'boolean' },
@@ -119,12 +166,16 @@ export async function runFinetune(ctx, project, options = {}) {
             return status(ctx, project);
         case 'stop':
             return stop(project);
+        case 'serve':
+            return serve(ctx, project);
         case 'retry':
             return retryCases(ctx, project, values, rest);
         case 'session':
             return session(project, rest);
+        case 'gate':
+            return gate(ctx, project, rest, options);
         default:
-            throw usageError(`unknown finetune verb: ${verb}`, 'one of: start, status, stop, retry, session');
+            throw usageError(`unknown finetune verb: ${verb}`, 'one of: start, status, stop, serve, retry, session, gate');
     }
 }
 /**
@@ -163,10 +214,9 @@ function whole(text, flag, min = 1) {
 const configFile = (dir) => join(dir, FINETUNE_DIR, 'loop.json');
 export function readConfig(dir) {
     try {
-        return {
-            ...DEFAULTS,
-            ...JSON.parse(readFileSync(configFile(dir), 'utf8')),
-        };
+        // A limit is for one start; older versions kept it, and had a guard and consolidations.
+        const { limit: _, guard, consolidateEvery: __, ...saved } = JSON.parse(readFileSync(configFile(dir), 'utf8'));
+        return { ...DEFAULTS, ...(guard !== undefined ? { recheck: guard } : {}), ...saved };
     }
     catch {
         return { ...DEFAULTS };
@@ -178,22 +228,32 @@ function configFrom(dir, v) {
     if (v.rubric !== undefined && v.rubric !== 'yes' && v.rubric !== 'no') {
         throw usageError('--rubric takes yes or no');
     }
+    const applyAt = whole(v['apply-at'], '-M');
+    if (applyAt === 1 && !v.force) {
+        throw usageError('-M 1 applies what one case asked for, alone', 'one case is an anecdote: use -M 2 or more, or pass --force');
+    }
     const config = {
         ...saved,
         workers,
-        applyAt: whole(v['apply-at'], '-M') ?? (v.workers ? workers : saved.applyAt),
+        // An older version saved -N as -M, so a tuning on one worker kept applying one case at a time.
+        applyAt: applyAt ?? (saved.applyAt < 2 && !v.force ? 2 : saved.applyAt),
         tries: whole(v.tries, '--tries') ?? saved.tries,
         memTries: whole(v['mem-tries'], '--mem-tries') ?? saved.memTries,
         mergeEvery: whole(v['merge-every'], '--merge-every') ?? saved.mergeEvery,
         seed: whole(v.seed, '--seed', 0) ?? saved.seed,
+        recheck: whole(v.recheck, '--recheck', 0) ?? saved.recheck,
+        budget: whole(v.budget, '--budget', 0) ?? saved.budget,
+        maxGrowth: whole(v['max-growth'], '--max-growth', 0) ?? saved.maxGrowth,
+        skillCap: whole(v['skill-cap'], '--skill-cap') ?? saved.skillCap,
+        maxSkills: whole(v['max-skills'], '--max-skills') ?? saved.maxSkills,
         ...(v.class ? { classes: v.class } : {}),
         ...(v.id ? { ids: v.id } : {}),
         ...(v.rubric ? { rubric: v.rubric === 'yes' } : {}),
-        ...(v.limit ? { limit: whole(v.limit, '--limit') } : {}),
     };
+    const limit = whole(v.limit, '--limit');
     mkdirSync(join(dir, FINETUNE_DIR), { recursive: true });
     writeFileSync(configFile(dir), `${JSON.stringify(config, null, 2)}\n`);
-    return config;
+    return limit ? { ...config, limit } : config;
 }
 async function start(ctx, project, values, options) {
     const store = DatasetStore.open(project.dir);
@@ -204,9 +264,11 @@ async function start(ctx, project, values, options) {
     if (!report.clean && !values.force) {
         throw invalidError(`the dataset has drifted from its sources (${report.cases.length} case(s), ${report.uncovered.length} section(s))`, 'refresh it: zen meta run /dataset - or start with --force');
     }
+    const more = whole(values.more, '--more');
     const config = configFrom(project.dir, values);
     const children = new Set();
     const t = new Tuning(project.dir, config, options.zen ?? spawnZen(project.dir, children), options.tickMs);
+    t.more = more;
     if (!options.zen) {
         editorFiles(project.dir);
     }
@@ -233,11 +295,15 @@ async function start(ctx, project, values, options) {
     };
     process.on('SIGINT', onInterrupt);
     note(`${bold('tuning')} ${project.name} · ${config.workers} workers · apply at ${config.applyAt}`);
-    note(dim(`follow it: file://${join(t.dir, 'STATUS.html')}`));
+    const viewing = options.zen ? undefined : await viewOf(project.dir);
+    const url = viewing?.url ?? liveView(project.dir);
+    if (url) {
+        note(dim(`follow it: ${url}`));
+    }
     let close;
     if (!ctx.json && !values.plain && !options.zen && process.stderr.isTTY && process.stdin.isTTY) {
         const { watch } = await import("./tui.js");
-        close = await watch(t, onInterrupt);
+        close = await watch(t, onInterrupt, url);
         drawing = true;
     }
     try {
@@ -246,6 +312,7 @@ async function start(ctx, project, values, options) {
     finally {
         close?.();
         process.off('SIGINT', onInterrupt);
+        await viewing?.close();
     }
     if (!ctx.json) {
         await status(ctx, project);
@@ -276,12 +343,13 @@ function status(ctx, project) {
     }
     const holder = liveHolder(join(dir, 'loop.lock'));
     const c = counts(project.dir);
+    const url = liveView(project.dir);
     if (ctx.json) {
         return json({
             running: Boolean(holder),
             ...c,
             status: join(dir, 'STATUS.md'),
-            html: join(dir, 'STATUS.html'),
+            ...(url ? { url } : {}),
         });
     }
     write(`${bold(project.name)}  ${holder ? green(`running (pid ${holder.pid})`) : dim('not running')}`);
@@ -293,9 +361,51 @@ function status(ctx, project) {
         note(dim(`another round for the difficult ones: ${cyan(`zen meta ${project.name} finetune retry --difficult`)}`));
     }
     if (existsSync(join(dir, 'STATUS.md'))) {
-        note(dim(`the detail: ${cyan(join(dir, 'STATUS.md'))} · ${cyan(`file://${join(dir, 'STATUS.html')}`)}`));
+        note(dim(`the detail: ${cyan(join(dir, 'STATUS.md'))} · ${url ? cyan(url) : `live in a browser: ${cyan(`zen meta ${project.name} finetune serve`)}`}`));
     }
 }
+/** The live view for a tuning, or a note saying why there is none - it never stops one. */
+async function viewOf(projectDir) {
+    if (liveView(projectDir)) {
+        return undefined;
+    }
+    try {
+        return await startView(projectDir);
+    }
+    catch (err) {
+        note(yellow(`no live view: ${err instanceof Error ? err.message : String(err)}`));
+        return undefined;
+    }
+}
+async function serve(ctx, project) {
+    const live = liveView(project.dir);
+    if (live) {
+        if (ctx.json) {
+            return json({ url: live, served: false });
+        }
+        write(live);
+        note(dim('already served by another zen process'));
+        return;
+    }
+    const viewing = await startView(project.dir);
+    if (ctx.json) {
+        json({ url: viewing.url, served: true });
+    }
+    else {
+        write(viewing.url);
+        note(dim('serving the tuning · Ctrl-C stops it'));
+    }
+    await new Promise((settle) => {
+        const done = () => {
+            process.off('SIGINT', done);
+            process.off('SIGTERM', done);
+            settle();
+        };
+        process.once('SIGINT', done);
+        process.once('SIGTERM', done);
+    });
+    await viewing.close();
+}
 function stop(project) {
     const dir = join(project.dir, FINETUNE_DIR);
     if (!liveHolder(join(dir, 'loop.lock'))) {
@@ -329,10 +439,78 @@ function session(project, rest) {
     if (!c) {
         throw invalidError(`no case ${id}`);
     }
-    const file = join(project.dir, FINETUNE_DIR, 'cases', id, `r${c.rev}`, 'session');
-    if (!existsSync(file)) {
+    const t = new Tuning(project.dir, readConfig(project.dir), async () => ({
+        code: 1,
+        stdout: '',
+    }));
+    const latest = attemptsOf(t, c)
+        .reverse()
+        .map((a) => analyzeSession(a.dir))
+        .find(Boolean);
+    if (!latest) {
         throw invalidError(`${id} has not been analyzed yet at revision ${c.rev}`);
     }
-    write(`zen meta resume ${project.name} ${readFileSync(file, 'utf8').trim()}`);
+    write(`zen meta resume ${project.name} ${latest}`);
+}
+/** The gates `#edit` runs after the apply agent exits, run now against the same `before` and limits. */
+async function gate(ctx, project, rest, options) {
+    const [at] = rest;
+    if (!at) {
+        throw usageError('gate of which apply?', 'zen meta finetune gate <apply dir>');
+    }
+    const dir = resolve(ctx.cwd, at);
+    const g = readJson(join(dir, 'gate.json'));
+    if (!g || existsSync(join(dir, 'applied.json'))) {
+        throw invalidError(`${at} is not an apply in progress`, 'pass the apply directory named on the line after /finetune-apply');
+    }
+    const after = await measure(project.dir);
+    const over = overLimits(g.before, after, g.limits);
+    const log = join(dir, 'gate.log');
+    const check = await (options.zen ?? checkOnce(project.dir))(['check', '--no-models', '--no-sandbox'], log);
+    const pass = over.length === 0 && check.code === 0;
+    const grew = after.total - g.before.total;
+    if (ctx.json) {
+        json({
+            pass,
+            alwaysRead: { before: g.before.total, after: after.total },
+            limits: g.limits,
+            over,
+            check: { code: check.code, log },
+        });
+    }
+    else {
+        const moved = costChanges(g.before, after);
+        write([
+            `always read, summed over the agents: ${g.before.total} -> ${after.total} bytes (${grew > 0 ? '+' : ''}${grew}); budget +${g.limits.budget}, ceiling ${g.limits.ceiling}`,
+            '',
+            ...(moved.length > 0 ? moved : ['nothing the agents read changed size']),
+            '',
+            ...(over.length > 0 ? ['over the limits:', ...over.map((o) => `- ${o}`), ''] : []),
+            check.code === 0
+                ? 'zen check: passed'
+                : `zen check: failed (exit ${check.code})\n${tail(log)}`,
+            pass ? 'gate: pass' : 'gate: fail - this apply would be undone',
+        ].join('\n'));
+    }
+    if (!pass) {
+        throw new CliError(over.length > 0 ? 'over the limits' : 'zen check failed', EXIT.failed, over.length > 0 ? 'cut, move or extract, then run gate again' : undefined);
+    }
+}
+const tail = (log) => existsSync(log) ? readFileSync(log, 'utf8').trimEnd().split('\n').slice(-30).join('\n') : '';
+/** `zen check` once, its output to `log` - not the loop's spawn, which records its children. */
+function checkOnce(root) {
+    return async (args, log) => {
+        const fd = openSync(log, 'w');
+        try {
+            const res = spawnSync(process.execPath, [process.argv[1], ...args], {
+                cwd: root,
+                stdio: ['ignore', fd, fd],
+            });
+            return { code: res.status ?? 1, stdout: '' };
+        }
+        finally {
+            closeSync(fd);
+        }
+    };
 }
 //# sourceMappingURL=command.js.map

package/dist/meta/finetune/cost.d.ts

@@ -0,0 +1,46 @@
+import { type ProjectReport } from '../host.ts';
+import type { Config } from './tuning.ts';
+export interface Cost {
+    /** per agent: house rules, prompt, preloaded skills, skill index lines */
+    alwaysRead: Record<string, number>;
+    /** `alwaysRead` summed over the agents */
+    total: number;
+    /** per skill: its SKILL.md */
+    skills: Record<string, number>;
+    /** per agent: the skills it can see */
+    visible: Record<string, number>;
+    /** every markdown file under agents/ */
+    files: Record<string, number>;
+}
+export interface Limits {
+    /** bytes one apply may add to `total` */
+    budget: number;
+    /** above this `total`, an apply may add nothing */
+    ceiling: number;
+    skillCap: number;
+    maxSkills: number;
+}
+/** `gate.json` in an apply's folder: what its budget gate compares against, kept for `finetune gate`. */
+export interface Gate {
+    before: Cost;
+    limits: Limits;
+}
+export declare function measure(root: string): Promise<Cost>;
+export interface Binding {
+    discovery: string;
+    allow?: string[];
+    preload?: string[];
+}
+/** No `skills:` key is the whole catalog as an index, the same as the runtime. */
+export declare const bindingOf: (a: ProjectReport["agents"][number]) => Binding;
+/** The skills a binding lets its agent load. */
+export declare const visibleTo: <S extends {
+    name: string;
+}>(b: Binding, entries: S[]) => S[];
+export declare function costOf(root: string, report: ProjectReport): Cost;
+export declare function limits(start: Cost, c: Config): Limits;
+/** Every limit an edit broke, said so the next attempt can act on it; empty when none. */
+export declare function overLimits(before: Cost, after: Cost, l: Limits): string[];
+/** What moved between two measures, per agent, skill and file - for a person and the next attempt. */
+export declare function costChanges(before: Cost, after: Cost): string[];
+//# sourceMappingURL=cost.d.ts.map

package/dist/meta/finetune/cost.js

@@ -0,0 +1,105 @@
+import { readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { validateProject } from "../host.js";
+export async function measure(root) {
+    return costOf(root, await validateProject({ dir: root }));
+}
+/** No `skills:` key is the whole catalog as an index, the same as the runtime. */
+export const bindingOf = (a) => a.skills ?? { discovery: 'index' };
+/** The skills a binding lets its agent load. */
+export const visibleTo = (b, entries) => entries.filter((s) => !b.allow || b.allow.includes(s.name));
+function size(root, rel) {
+    try {
+        return statSync(join(root, rel)).size;
+    }
+    catch {
+        return 0;
+    }
+}
+export function costOf(root, report) {
+    const entries = report.skills.entries;
+    const skills = Object.fromEntries(entries.map((s) => [s.name, size(root, s.path)]));
+    const alwaysRead = {};
+    const visible = {};
+    for (const a of report.agents) {
+        const binding = bindingOf(a);
+        const seen = visibleTo(binding, entries);
+        const index = binding.discovery === 'index'
+            ? seen.reduce((n, s) => n + Buffer.byteLength(`- ${s.name}: ${s.description}\n`), 0)
+            : 0;
+        const preloaded = (binding.preload ?? []).reduce((n, s) => n + (skills[s] ?? 0), 0);
+        alwaysRead[a.name] =
+            a.instructions.reduce((n, rel) => n + size(root, rel), 0) + preloaded + index;
+        visible[a.name] = seen.length;
+    }
+    const total = Object.values(alwaysRead).reduce((n, b) => n + b, 0);
+    return { alwaysRead, total, skills, visible, files: markdown(root) };
+}
+function markdown(root) {
+    const out = {};
+    let names = [];
+    try {
+        names = readdirSync(join(root, 'agents'), { recursive: true });
+    }
+    catch {
+        return out;
+    }
+    for (const name of names.sort()) {
+        if (name.endsWith('.md')) {
+            const rel = join('agents', name).split('\\').join('/');
+            out[rel] = size(root, rel);
+        }
+    }
+    return out;
+}
+export function limits(start, c) {
+    return {
+        budget: c.budget,
+        // A project that starts nearly empty still gets one apply's worth of room.
+        ceiling: Math.max(start.total + c.budget, Math.round(start.total * (1 + c.maxGrowth / 100))),
+        skillCap: c.skillCap,
+        maxSkills: c.maxSkills,
+    };
+}
+/** Every limit an edit broke, said so the next attempt can act on it; empty when none. */
+export function overLimits(before, after, l) {
+    const out = [];
+    const grew = after.total - before.total;
+    if (grew > l.budget) {
+        out.push(`what the agents always read grew by ${grew} bytes (${before.total} -> ${after.total}), over the budget of ${l.budget}`);
+    }
+    if (grew > 0 && after.total > l.ceiling) {
+        out.push(`what the agents always read is ${after.total} bytes, over the ceiling of ${l.ceiling}: past it an apply may add nothing - cut, move or extract to make room`);
+    }
+    for (const [name, bytes] of Object.entries(after.skills)) {
+        if (bytes > l.skillCap && bytes > (before.skills[name] ?? 0)) {
+            out.push(`skill ${name} holds ${bytes} bytes, over the cap of ${l.skillCap}: split it by when each part is needed`);
+        }
+    }
+    for (const [agent, n] of Object.entries(after.visible)) {
+        if (n > l.maxSkills && n > (before.visible[agent] ?? 0)) {
+            out.push(`agent ${agent} sees ${n} skills, over ${l.maxSkills}: merge skills whose descriptions overlap`);
+        }
+    }
+    return out;
+}
+/** What moved between two measures, per agent, skill and file - for a person and the next attempt. */
+export function costChanges(before, after) {
+    const rows = [];
+    const diff = (label, a, b) => {
+        for (const key of [...new Set([...Object.keys(a), ...Object.keys(b)])].sort()) {
+            const was = a[key] ?? 0;
+            const now = b[key] ?? 0;
+            if (was !== now) {
+                rows.push(`| ${label} | ${key} | ${was} | ${now} | ${now - was > 0 ? '+' : ''}${now - was} |`);
+            }
+        }
+    };
+    diff('always read', before.alwaysRead, after.alwaysRead);
+    diff('skill', before.skills, after.skills);
+    diff('file', before.files, after.files);
+    return rows.length > 0
+        ? ['| What | Name | Before | After | Change |', '| --- | --- | --- | --- | --- |', ...rows]
+        : [];
+}
+//# sourceMappingURL=cost.js.map

package/dist/meta/finetune/dataset/types.d.ts

@@ -87,10 +87,12 @@ export interface NoteRow {
     caseRev: number;
     run?: string;
     verdict?: Verdict;
-    rubric?: Record<string, 'pass' | 'fail'>;
+    rubric?: Record<string, Grade>;
     text: string;
     by: By;
 }
+/** `invalid`: the rubric line itself is broken - it says how one implementation did it, not what is right. */
+export type Grade = 'pass' | 'fail' | 'invalid';
 export type JournalRow = ChangeRow | NoteRow;
 export interface Ignored {
     file: string;

package/dist/meta/finetune/feedback.d.ts

@@ -1,4 +1,4 @@
-import { type Verdict } from './dataset/types.ts';
+import { type Grade, type Verdict } from './dataset/types.ts';
 export type Phase = 'nomem' | 'mem';
 export interface Improvement {
     id: string;
@@ -18,14 +18,26 @@ export interface Feedback {
     phase: Phase;
     attempt: number;
     verdict: Verdict;
-    rubric: Record<string, 'pass' | 'fail'>;
+    rubric: Record<string, Grade>;
     /** right, and nothing left worth changing */
     done: boolean;
     summary: string;
     improvements: Improvement[];
     /** what outside the project made the run void: the sandbox, the network, a provider */
     infra?: string;
+    /** a recheck's: the apply whose version the case failed on, after passing before it */
+    recheck?: string;
+    /** the try's folder, when it is not the case's own attempt folder */
+    dir?: string;
 }
+/** A summary's first paragraph - the verdict, for a table cell or a one-line note. */
+export declare const lead: (summary: string) => string;
+/** A `specification` improvement is for the dataset, never for an apply: prose cannot fix a rubric. */
+export declare const forDataset: (i: Improvement) => boolean;
+/** The improvements an apply can act on. */
+export declare const forProse: (f: {
+    improvements: Improvement[];
+}) => Improvement[];
 export declare const feedbackId: (caseId: string, phase: Phase, attempt: number, round?: number) => string;
 /**
  * The feedback, or what is wrong with the file - said so a model can fix it.