turntax 0.2.0 → 0.4.0

package/dist/core/advice.js

@@ -3,14 +3,16 @@ import { countO200k } from './tokenize.js';
 import { TOOLS } from './tools.js';
 const DEFAULT_SECTION_TOKENS = 600;
 export function buildAdvice(units, files, opts = {}) {
+    // User-level files take part in checks across files; moving sections or checking paths only makes sense in the repository.
+    const repo = units.filter((u) => !u.scope);
     const advice = [
         ...misconfigured(units),
         ...sizeLimits(units, files),
         ...duplicates(units),
         ...contradictions(units),
-        ...sections(units, opts.sectionTokens ?? DEFAULT_SECTION_TOKENS),
+        ...sections(repo, opts.sectionTokens ?? DEFAULT_SECTION_TOKENS),
         ...nonEnglish(units, opts.english),
-        ...staleReferences(units, opts),
+        ...staleReferences(repo, opts),
     ];
     const order = { high: 0, medium: 1, low: 2 };
     return advice.sort((a, b) => order[a.severity] - order[b.severity] || (b.savingTokens ?? 0) - (a.savingTokens ?? 0));
@@ -263,11 +265,8 @@ function sections(units, threshold) {
         const tools = toolsWith(units, u.path, 'always');
         for (const s of splitSections(u.text)) {
             const tokens = countO200k(s.text);
-            const refs = pathRefs(s.text).filter((r) => !r.startsWith('.'));
-            const dirs = refs.map((r) => r.split('/')[0]);
-            const top = mostCommon(dirs);
-            if (tokens >= 100 && top && top.count >= 2 && top.count / dirs.length >= 0.6) {
-                const scope = commonDir(refs.filter((r) => r.startsWith(top.value + '/')));
+            const scope = sectionScope(s.text);
+            if (scope) {
                 out.push({
                     kind: 'scopable-section',
                     severity: 'medium',
@@ -295,6 +294,17 @@ function sections(units, threshold) {
     }
     return out;
 }
+/** The directory a section is mostly about (for example `packages/api`), or null when it is not scopable. */
+export function sectionScope(text) {
+    if (countO200k(text) < 100)
+        return null;
+    const refs = pathRefs(text).filter((r) => !r.startsWith('.'));
+    const dirs = refs.map((r) => r.split('/')[0]);
+    const top = mostCommon(dirs);
+    if (!top || top.count < 2 || top.count / dirs.length < 0.6)
+        return null;
+    return commonDir(refs.filter((r) => r.startsWith(top.value + '/')));
+}
 /** Longest directory prefix shared by all refs, e.g. `packages/api` for `packages/api/db.ts` and `packages/api/handlers/`. */
 function commonDir(refs) {
     const dirs = refs.map((r) => (r.endsWith('/') ? r.slice(0, -1) : r.slice(0, r.lastIndexOf('/'))).split('/'));

package/dist/core/audit.js

@@ -1,7 +1,9 @@
 import { buildAdvice } from './advice.js';
 import { classify, detectTools } from './classify.js';
+import { defersTools, serverKey } from './mcp.js';
 import { countO200k, offlineCounter } from './tokenize.js';
 import { TOOLS } from './tools.js';
+import { classifyUser } from './user.js';
 export function modelsForTool(tool, models) {
     const spec = TOOLS.find((t) => t.id === tool);
     return spec.families.length ? models.filter((m) => spec.families.includes(m.family)) : models;
@@ -15,9 +17,12 @@ function counterFor(model, opts) {
 }
 export async function audit(files, opts) {
     const turns = opts.turns ?? 100;
-    const allUnits = classify(files);
-    const toolIds = opts.tools ?? detectTools(allUnits);
+    const allUnits = [...classify(files), ...classifyUser(opts.userFiles ?? [])];
+    const servers = opts.mcp?.servers ?? [];
+    const toolIds = opts.tools ??
+        [...new Set([...detectTools(allUnits), ...servers.filter((s) => !s.disabled).map((s) => s.tool)])].sort((a, b) => TOOLS.findIndex((t) => t.id === a) - TOOLS.findIndex((t) => t.id === b));
     const units = allUnits.filter((u) => toolIds.includes(u.tool));
+    const mcp = servers.filter((s) => toolIds.includes(s.tool)).map((s) => mcpRow(s, opts.mcp?.measured));
     // Count each distinct text once per model, only for the tools that run that model.
     const counts = new Map();
     for (const model of opts.models) {
@@ -39,6 +44,8 @@ export async function audit(files, opts) {
         };
         if (u.importedFrom)
             row.importedFrom = u.importedFrom;
+        if (u.scope)
+            row.scope = u.scope;
         if (u.mode !== 'ignored')
             for (const m of modelsForTool(u.tool, opts.models)) {
                 const c = counts.get(m.id)?.get(u.text);
@@ -51,21 +58,48 @@ export async function audit(files, opts) {
         const spec = TOOLS.find((t) => t.id === id);
         const rows = files_.filter((r) => r.tool === id);
         const always = rows.filter((r) => r.mode === 'always');
-        const onDemand = rows.filter((r) => r.mode === 'on-demand');
+        const repoAlways = always.filter((r) => !r.scope);
+        const userAlways = always.filter((r) => r.scope === 'user');
+        const onDemand = rows.filter((r) => r.mode === 'on-demand' && !r.scope);
         const models = modelsForTool(id, opts.models).map((m) => modelCost(m, always, turns));
+        const toolMcp = mcp.filter((r) => r.tool === id && r.status !== 'disabled');
+        const mcpTokens = (scope) => sum(toolMcp.filter((r) => r.scope === scope).map((r) => r.o200k ?? 0));
+        const perTurnO200k = sum(repoAlways.map((r) => r.o200k));
+        const userPerTurnO200k = sum(userAlways.map((r) => r.o200k)) + mcpTokens('user');
+        const mcpPerTurnO200k = mcpTokens('project');
         return {
             tool: id,
             name: spec.name,
-            alwaysFiles: new Set(always.map((r) => r.path)).size,
+            alwaysFiles: new Set(repoAlways.map((r) => r.path)).size,
             onDemandFiles: new Set(onDemand.map((r) => r.path)).size,
-            perTurnO200k: sum(always.map((r) => r.o200k)),
+            perTurnO200k,
             onDemandO200k: sum(onDemand.map((r) => r.o200k)),
+            userAlwaysFiles: new Set(userAlways.map((r) => r.path)).size,
+            userPerTurnO200k,
+            mcpServers: toolMcp.length,
+            mcpPerTurnO200k,
+            mcpMeasured: toolMcp.every((r) => r.status === 'measured'),
+            totalPerTurnO200k: perTurnO200k + mcpPerTurnO200k + userPerTurnO200k,
             models,
             notes: spec.notes,
             sources: spec.sources,
         };
     });
-    return { turns, tools, files: files_, advice: buildAdvice(units, files, opts.advice), models: opts.models };
+    const adviceFiles = [...files, ...(opts.userFiles ?? [])];
+    return { turns, tools, files: files_, advice: buildAdvice(units, adviceFiles, opts.advice), models: opts.models, mcp };
+}
+function mcpRow(s, measured) {
+    const row = { name: s.name, tool: s.tool, configPath: s.configPath, scope: s.scope, transport: s.transport, status: 'not-measured' };
+    if (s.disabled)
+        return { ...row, status: 'disabled' };
+    const m = measured?.get(serverKey(s));
+    if (!m)
+        return row;
+    if ('error' in m)
+        return { ...row, status: 'failed', error: m.error };
+    if (defersTools(s))
+        return { ...row, status: 'measured', tools: m.tools, o200k: m.namesO200k, deferredO200k: m.o200k };
+    return { ...row, status: 'measured', tools: m.tools, o200k: m.o200k };
 }
 function modelCost(model, always, turns) {
     const counts = always.map((r) => r.counts[model.id]);

package/dist/core/diff.js

@@ -0,0 +1,63 @@
+export function diffReports(before, after, base) {
+    const ids = [...new Set([...after.tools.map((t) => t.tool), ...before.tools.map((t) => t.tool)])];
+    const tools = ids.map((id) => {
+        const a = after.tools.find((t) => t.tool === id);
+        const b = before.tools.find((t) => t.tool === id);
+        const av = a?.perTurnO200k ?? null;
+        const bv = b?.perTurnO200k ?? null;
+        return { tool: id, name: (a ?? b).name, before: bv, after: av, delta: (av ?? 0) - (bv ?? 0) };
+    });
+    const alwaysFiles = (r) => {
+        const m = new Map();
+        for (const f of r.files) {
+            if (f.mode !== 'always' || f.scope === 'user')
+                continue;
+            const key = `${f.path}\0${f.part}`;
+            const prev = m.get(key);
+            if (prev)
+                prev.tools.add(f.tool);
+            else
+                m.set(key, { path: f.path, part: f.part, o200k: f.o200k, tools: new Set([f.tool]) });
+        }
+        return m;
+    };
+    const bf = alwaysFiles(before);
+    const af = alwaysFiles(after);
+    const files = [];
+    for (const key of new Set([...bf.keys(), ...af.keys()])) {
+        const b = bf.get(key);
+        const a = af.get(key);
+        const delta = (a?.o200k ?? 0) - (b?.o200k ?? 0);
+        if (a && b && delta === 0)
+            continue;
+        files.push({
+            path: (a ?? b).path,
+            part: (a ?? b).part,
+            before: b?.o200k ?? null,
+            after: a?.o200k ?? null,
+            delta,
+            tools: [...new Set([...(b?.tools ?? []), ...(a?.tools ?? [])])],
+        });
+    }
+    files.sort((x, y) => Math.abs(y.delta) - Math.abs(x.delta) || x.path.localeCompare(y.path));
+    const servers = (r) => new Set((r.mcp ?? []).filter((s) => s.scope === 'project' && s.status !== 'disabled').map((s) => `${s.name} (${s.tool})`));
+    const bs = servers(before);
+    const as = servers(after);
+    return {
+        base,
+        tools,
+        files,
+        mcp: { added: [...as].filter((s) => !bs.has(s)), removed: [...bs].filter((s) => !as.has(s)) },
+    };
+}
+/** Largest per-turn increase across agents (0 when nothing grew). */
+export function maxIncrease(diff) {
+    return Math.max(0, ...diff.tools.map((t) => t.delta));
+}
+/** Validates a parsed JSON report enough to diff against it. */
+export function asDiffInput(data) {
+    const r = data;
+    if (!r || !Array.isArray(r.tools) || !Array.isArray(r.files))
+        throw new Error('not a turntax --json report');
+    return r;
+}

package/dist/core/fix.js

@@ -0,0 +1,431 @@
+import { sectionScope } from './advice.js';
+import { classify } from './classify.js';
+import { isInstructionFile } from './files.js';
+import { basename, findImports, linesWithFences, parseFrontmatter, splitSections } from './markdown.js';
+import { countO200k } from './tokenize.js';
+import { TOOLS } from './tools.js';
+const RANK = { ignored: 0, manual: 1, 'on-demand': 2, always: 3 };
+const toolName = (id) => TOOLS.find((t) => t.id === id)?.name ?? id;
+const names = (ids) => [...ids].map(toolName).join(', ');
+/** Text with LF line endings, plus the line ending to write back. */
+function lf(text) {
+    return { text: text.replace(/\r\n/g, '\n'), eol: text.includes('\r\n') ? '\r\n' : '\n' };
+}
+function contentUnits(units) {
+    return units.filter((u) => u.part !== 'description' && u.mode !== 'ignored');
+}
+/**
+ * A line as compared by the fixes: only list markers and whitespace are ignored. Case, underscores,
+ * asterisks and backticks can carry meaning (`create_user`, globs), so lines that differ there differ.
+ */
+function lineKey(line) {
+    return line.replace(/^\s*(?:[-*+]|\d+[.)])\s+/, '').replace(/\s+/g, ' ').trim();
+}
+/** Prose lines long enough to be meaningful (outside fenced code, not headings), by key. */
+function proseLines(text) {
+    const out = new Map();
+    for (const { line, inFence } of linesWithFences(text)) {
+        const key = lineKey(line);
+        if (!inFence && key.length >= 30 && !key.startsWith('#'))
+            out.set(key, line);
+    }
+    return out;
+}
+function keysOf(text) {
+    return text
+        .split('\n')
+        .map(lineKey)
+        .filter((k) => k.replace(/[#\s]/g, '').length > 0);
+}
+function loadedLines(units) {
+    const out = new Map();
+    for (const u of contentUnits(units)) {
+        const lines = out.get(u.tool) ?? new Map();
+        out.set(u.tool, lines);
+        for (const key of keysOf(u.text))
+            lines.set(key, Math.max(lines.get(key) ?? 0, RANK[u.mode]));
+    }
+    return out;
+}
+/**
+ * Agents that would lose something: every line an agent read before must still be read at least as
+ * often, except the `edited` lines, which need only `need(before)`.
+ */
+function check(before, after, edited, need) {
+    const lost = [];
+    for (const [tool, lines] of before) {
+        const now = after.get(tool);
+        for (const [key, rank] of lines) {
+            if ((now?.get(key) ?? 0) < (edited.has(key) ? need(rank) : rank)) {
+                lost.push(tool);
+                break;
+            }
+        }
+    }
+    return lost;
+}
+class Workspace {
+    tools;
+    state;
+    constructor(input, tools) {
+        this.tools = tools;
+        this.state = this.build(new Map(input.map((f) => [f.path, f])));
+    }
+    build(files) {
+        const units = classify([...files.values()], this.tools);
+        return { files, units, loaded: loadedLines(units) };
+    }
+    get files() {
+        return this.state.files;
+    }
+    get units() {
+        return this.state.units;
+    }
+    /** The state with `edits` applied (null deletes a file). */
+    trial(edits) {
+        const files = new Map(this.state.files);
+        for (const [path, text] of edits) {
+            if (text === null)
+                files.delete(path);
+            else
+                files.set(path, { path, text });
+        }
+        return this.build(files);
+    }
+    check(next, edited, need) {
+        return check(this.state.loaded, next.loaded, new Set(edited), need);
+    }
+    commit(next) {
+        this.state = next;
+    }
+}
+export function planFixes(input, opts = {}) {
+    // Only repository files are ever changed; user-level files (~/...) are not passed in.
+    const ws = new Workspace(input.filter((f) => !f.path.startsWith('~')), opts.tools);
+    // Files reached only through @imports (a README, docs) are for people too; they are never changed.
+    const readOnly = (path) => !isInstructionFile(path)
+        ? `${path} is not an agent instruction file (it is @imported); it is left alone.`
+        : opts.readOnly?.(path)
+            ? `${path} is a symlink, in a symlinked folder or the target of a symlink; it is left alone.`
+            : null;
+    const original = new Map(ws.files);
+    const renames = new Map();
+    const fixes = [];
+    const skipped = [];
+    if (!opts.tools || opts.tools.includes('cursor'))
+        renameCursorRules(ws, readOnly, renames, fixes, skipped);
+    // Moves run before duplicate removal: a move may relax how often lines load, so a line must not be
+    // removed elsewhere on the strength of a copy that is moved later.
+    moveScopableSections(ws, opts, readOnly, fixes, skipped);
+    removeDuplicates(ws, readOnly, fixes, skipped);
+    const renamedTo = new Map([...renames].map(([from, to]) => [to, from]));
+    const changes = [];
+    for (const [path, file] of ws.files) {
+        const from = renamedTo.get(path);
+        const before = original.get(from ?? path)?.text ?? null;
+        if (from)
+            changes.push({ path, before, after: file.text, renamedFrom: from });
+        else if (before !== file.text)
+            changes.push({ path, before, after: file.text });
+    }
+    changes.sort((a, b) => a.path.localeCompare(b.path));
+    return { fixes, skipped, changes };
+}
+/** `.md` files in `.cursor/rules` are ignored by Cursor; `.mdc` is the documented extension. */
+function renameCursorRules(ws, readOnly, renames, fixes, skipped) {
+    for (const f of [...ws.files.values()]) {
+        if (!/^(?:.*\/)?\.cursor\/rules\/.+\.md$/.test(f.path))
+            continue;
+        const to = f.path.replace(/\.md$/, '.mdc');
+        if (readOnly(f.path) || ws.files.has(to)) {
+            skipped.push({ kind: 'misconfigured', paths: [f.path], reason: readOnly(f.path) ?? `${to} already exists.` });
+            continue;
+        }
+        const next = ws.trial(new Map([[f.path, null], [to, f.text]]));
+        const lost = ws.check(next, [], (r) => r);
+        if (lost.length) {
+            skipped.push({ kind: 'misconfigured', paths: [f.path], reason: `${names(lost)} would stop reading it.` });
+            continue;
+        }
+        const mode = next.units.find((u) => u.tool === 'cursor' && u.path === to && u.part !== 'description')?.mode;
+        ws.commit(next);
+        renames.set(f.path, to);
+        fixes.push({
+            kind: 'misconfigured',
+            paths: [f.path, to],
+            message: `Renamed ${f.path} to ${basename(to)} so Cursor reads it` +
+                (mode === 'manual' ? '; without frontmatter it applies only when @-mentioned (add alwaysApply, globs or description).' : '.'),
+            savingTokens: null,
+        });
+    }
+}
+/** Indexes of body lines (after any frontmatter) outside fenced code. */
+function bodyLines(text) {
+    const start = text.split('\n').length - parseFrontmatter(text).body.split('\n').length;
+    return linesWithFences(text)
+        .map(({ line, inFence }, index) => ({ line, inFence, index }))
+        .filter((l) => !l.inFence && l.index >= start);
+}
+/** Drops the given line indexes; a blank line left next to another blank line where a line was removed goes too. */
+function dropLines(lines, drop) {
+    const kept = [];
+    let removed = false;
+    lines.forEach((line, i) => {
+        if (drop.has(i)) {
+            removed = true;
+            return;
+        }
+        if (removed && line.trim() === '' && (kept.length === 0 || kept[kept.length - 1].trim() === ''))
+            return;
+        removed = false;
+        kept.push(line);
+    });
+    return kept;
+}
+/**
+ * Removes a line from a file when every agent that reads the file also reads the same line every turn
+ * from another file. Files read by fewer agents are trimmed first, so the broadest copy stays.
+ */
+function removeDuplicates(ws, readOnly, fixes, skipped) {
+    const readers = (path) => new Set(contentUnits(ws.units).filter((u) => u.path === path).map((u) => u.tool));
+    const order = [...ws.files.keys()].sort((a, b) => readers(a).size - readers(b).size || b.localeCompare(a));
+    for (const path of order) {
+        const tools = readers(path);
+        // Skill, command and subagent bodies are procedures or separate prompts; they are left whole.
+        if (!tools.size || ws.units.some((u) => u.path === path && u.part === 'body'))
+            continue;
+        const { text, eol } = lf(ws.files.get(path).text);
+        const elsewhere = (key) => contentUnits(ws.units).filter((u) => u.path !== path && u.mode === 'always' && proseLines(u.text).has(key));
+        // Lines this file shares with another file that some agent reads every turn.
+        const shared = new Map();
+        const blockers = new Set();
+        const removable = new Set();
+        for (const [key] of proseLines(text)) {
+            const others = elsewhere(key);
+            if (!others.length)
+                continue;
+            shared.set(key, [...new Set(others.map((u) => u.path))]);
+            const missing = [...tools].filter((t) => !others.some((u) => u.tool === t));
+            missing.forEach((t) => blockers.add(t));
+            if (!missing.length)
+                removable.add(key);
+        }
+        if (!shared.size)
+            continue;
+        const otherPaths = [...new Set([...shared.values()].flat())];
+        if (readOnly(path)) {
+            skipped.push({ kind: 'duplicate', paths: [path, ...otherPaths], reason: readOnly(path) });
+            continue;
+        }
+        if (removable.size) {
+            const lines = text.split('\n');
+            const drop = new Set(bodyLines(text).filter((l) => removable.has(lineKey(l.line))).map((l) => l.index));
+            const removed = [...drop].map((i) => lines[i]);
+            const next = ws.trial(new Map([[path, dropLines(lines, drop).join('\n').replace(/\n/g, eol)]]));
+            const lost = ws.check(next, removable, (r) => r);
+            if (lost.length) {
+                skipped.push({ kind: 'duplicate', paths: [path, ...otherPaths], reason: `Kept ${removable.size} line(s) in ${path}: ${names(lost)} would lose context without them (for example a file they @import).` });
+            }
+            else {
+                const everyTurn = contentUnits(ws.units).some((u) => u.path === path && u.mode === 'always');
+                const from = [...new Set([...removable].flatMap((k) => shared.get(k)))];
+                ws.commit(next);
+                fixes.push({
+                    kind: 'duplicate',
+                    paths: [path, ...from],
+                    message: `Removed ${removed.length} line(s) from ${path} that ${names(tools)} already read every turn from ${from.join(', ')}.`,
+                    savingTokens: everyTurn ? countO200k(removed.join('\n')) : 0,
+                });
+            }
+        }
+        const kept = shared.size - removable.size;
+        if (kept && blockers.size)
+            skipped.push({
+                kind: 'duplicate',
+                paths: [path, ...otherPaths],
+                reason: `Kept ${kept} line(s) in ${path} that are also in ${otherPaths.join(', ')}: ${names(blockers)} would lose them.`,
+            });
+    }
+}
+/** Where a section about `scope` can live so it loads only there: the same file name nested, AGENTS.md, or a Claude rule. */
+function targets(source, scope, heading) {
+    const name = basename(source);
+    const slug = heading.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '') || 'section';
+    const out = [];
+    if (['CLAUDE.md', 'AGENTS.md', 'GEMINI.md'].includes(name))
+        out.push({ path: `${scope}/${name}`, header: '' });
+    if (name !== 'AGENTS.md')
+        out.push({ path: `${scope}/AGENTS.md`, header: '' });
+    out.push({ path: `.claude/rules/${slug}.md`, header: `---\npaths:\n  - "${scope}/**"\n---\n\n` });
+    return out;
+}
+const headingLevel = (line) => /^\s{0,3}(#{1,6})\s/.exec(line)?.[1].length ?? 0;
+/** Level 2 and 3 sections of the LF text, each running to the next heading of the same or a higher level. */
+function movableSections(text) {
+    const lines = text.split('\n');
+    const all = splitSections(text).filter((s) => s.heading !== '(top)');
+    return all
+        .map((s) => ({ s, level: headingLevel(lines[s.line - 1]) }))
+        .filter((x) => x.level >= 2)
+        .map(({ s, level }) => {
+        const next = all.find((o) => o.line > s.line && headingLevel(lines[o.line - 1]) <= level);
+        const end = next ? next.line - 1 : lines.length;
+        return { heading: s.heading, start: s.line - 1, end, body: lines.slice(s.line - 1, end).join('\n').replace(/\n+$/, '') };
+    });
+}
+function moveScopableSections(ws, opts, readOnly, fixes, skipped) {
+    const sources = [...new Set(ws.units.filter((u) => u.mode === 'always' && u.part === 'full').map((u) => u.path))].sort();
+    const tried = new Set();
+    for (const path of sources) {
+        // Sections are found in the raw file so that comments and formatting move as they are.
+        for (;;) {
+            const { text, eol } = lf(ws.files.get(path).text);
+            const next = movableSections(text)
+                .map((x) => ({ ...x, scope: sectionScope(x.body) }))
+                .find((x) => x.scope && !tried.has(`${path}\0${x.body}`));
+            if (!next)
+                break;
+            tried.add(`${path}\0${next.body}`);
+            const { heading, body, start, end } = next;
+            const scope = next.scope;
+            const reason = readOnly(path) ?? moveBlocker(body, scope, opts);
+            if (reason) {
+                skipped.push({ kind: 'scopable-section', paths: [path], reason: `Section "${heading}": ${reason}` });
+                continue;
+            }
+            const lines = text.split('\n');
+            const head = lines.slice(0, start);
+            const tail = lines.slice(end);
+            while (head.length && tail.length && head[head.length - 1].trim() === '' && tail[0].trim() === '')
+                tail.shift();
+            const rest = [...head, ...tail].join('\n').replace(/\n*$/, '\n');
+            let moved = false;
+            const refused = [];
+            for (const t of targets(path, scope, heading)) {
+                const existing = ws.files.get(t.path);
+                if (t.path === path || readOnly(t.path) || (existing && t.header))
+                    continue;
+                const target = existing ? lf(existing.text) : { text: '', eol };
+                const targetText = existing ? `${target.text.replace(/\n+$/, '')}\n\n${body}\n` : `${t.header}${body}\n`;
+                const trial = ws.trial(new Map([
+                    [path, rest.replace(/\n/g, eol)],
+                    [t.path, targetText.replace(/\n/g, target.eol)],
+                ]));
+                // Agents that loaded the section every turn may now load it only when working in that folder.
+                const lost = ws.check(trial, keysOf(body), (r) => Math.min(r, RANK['on-demand']));
+                if (lost.length) {
+                    refused.push(`${t.path} (${names(lost)} would lose context)`);
+                    continue;
+                }
+                const readers = [...new Set(ws.units.filter((u) => u.path === path && u.mode === 'always' && u.part !== 'description').map((u) => u.tool))];
+                const reads = (l, tool) => keysOf(body).some((k) => l.get(tool)?.has(k));
+                const added = [...trial.loaded.keys()].filter((tool) => !reads(ws.state.loaded, tool) && reads(trial.loaded, tool));
+                ws.commit(trial);
+                fixes.push({
+                    kind: 'scopable-section',
+                    paths: [path, t.path],
+                    message: `Moved section "${heading}" from ${path} to ${t.path}${existing ? '' : ' (new file)'}; ${names(readers)} load it only when working in ${scope}/.` +
+                        (added.length ? ` Now also read there by ${names(added)}.` : ''),
+                    savingTokens: countO200k(body),
+                });
+                moved = true;
+                break;
+            }
+            if (!moved)
+                skipped.push({
+                    kind: 'scopable-section',
+                    paths: [path],
+                    reason: `Section "${heading}": no target keeps every agent's context: ${refused.join('; ')}. Use --tools to choose the agents to keep it for.`,
+                });
+        }
+    }
+}
+function moveBlocker(body, scope, opts) {
+    if (scope.split('/').some((seg) => seg === '' || seg === '.' || seg === '..'))
+        return `unusual folder ${scope}.`;
+    if (opts.exists && !opts.exists(scope))
+        return `folder ${scope}/ does not exist.`;
+    if (findImports(body).length)
+        return 'it has @imports, which resolve relative to the file they are in.';
+    if (/\]\((?!https?:|#|\/|mailto:)[^)]+\)/.test(body))
+        return 'it has relative links, which resolve relative to the file they are in.';
+    return null;
+}
+/** Unified diff of the planned changes, in the format `git apply` accepts. */
+export function unifiedDiff(changes) {
+    let out = '';
+    for (const c of changes) {
+        const from = c.renamedFrom ?? c.path;
+        out += `diff --git a/${from} b/${c.path}\n`;
+        if (c.renamedFrom) {
+            if (c.before === c.after)
+                out += 'similarity index 100%\n';
+            out += `rename from ${c.renamedFrom}\nrename to ${c.path}\n`;
+            if (c.before === c.after)
+                continue;
+        }
+        if (c.before === null)
+            out += 'new file mode 100644\n';
+        out += `--- ${c.before === null ? '/dev/null' : `a/${from}`}\n+++ b/${c.path}\n`;
+        out += hunks(c.before ?? '', c.after);
+    }
+    return out;
+}
+function split(text) {
+    if (text === '')
+        return [];
+    const lines = text.split('\n');
+    const noEol = lines[lines.length - 1] !== '';
+    if (!noEol)
+        lines.pop();
+    return lines.map((t, i) => ({ text: t, noEol: noEol && i === lines.length - 1 }));
+}
+/** Line diff by longest common subsequence; instruction files are small. */
+function diffLines(a, b) {
+    const n = a.length;
+    const m = b.length;
+    const same = (i, j) => a[i].text === b[j].text && a[i].noEol === b[j].noEol;
+    if (n * m > 4_000_000)
+        return [...a.map((l) => ({ op: '-', ...l })), ...b.map((l) => ({ op: '+', ...l }))];
+    const lcs = Array.from({ length: n + 1 }, () => new Uint32Array(m + 1));
+    for (let i = n - 1; i >= 0; i--)
+        for (let j = m - 1; j >= 0; j--)
+            lcs[i][j] = same(i, j) ? lcs[i + 1][j + 1] + 1 : Math.max(lcs[i + 1][j], lcs[i][j + 1]);
+    const out = [];
+    let i = 0;
+    let j = 0;
+    while (i < n || j < m) {
+        if (i < n && j < m && same(i, j)) {
+            out.push({ op: ' ', ...a[i++] });
+            j++;
+        }
+        else if (i < n && (j === m || lcs[i + 1][j] >= lcs[i][j + 1]))
+            out.push({ op: '-', ...a[i++] });
+        else
+            out.push({ op: '+', ...b[j++] });
+    }
+    return out;
+}
+function hunks(before, after, context = 3) {
+    const lines = diffLines(split(before), split(after));
+    const changed = lines.map((l, i) => (l.op === ' ' ? -1 : i)).filter((i) => i >= 0);
+    let out = '';
+    let k = 0;
+    while (k < changed.length) {
+        const start = Math.max(0, changed[k] - context);
+        let end = Math.min(lines.length, changed[k] + context + 1);
+        while (k + 1 < changed.length && changed[k + 1] - context <= end)
+            end = Math.min(lines.length, changed[++k] + context + 1);
+        k++;
+        const slice = lines.slice(start, end);
+        const prefix = lines.slice(0, start);
+        const oldStart = prefix.filter((l) => l.op !== '+').length;
+        const newStart = prefix.filter((l) => l.op !== '-').length;
+        const oldLen = slice.filter((l) => l.op !== '+').length;
+        const newLen = slice.filter((l) => l.op !== '-').length;
+        out += `@@ -${oldLen ? oldStart + 1 : oldStart},${oldLen} +${newLen ? newStart + 1 : newStart},${newLen} @@\n`;
+        for (const l of slice)
+            out += `${l.op}${l.text}\n${l.noEol ? '\\n' : ''}`;
+    }
+    return out;
+}