@event4u/agent-config 16.2.0 → 16.4.0

package/src/scripts/_lib/git_convention_measure.ts

@@ -0,0 +1,344 @@
+/**
+ * Measures the convention an existing history already follows, so a project
+ * with no declaration is offered its own format instead of the shipped default.
+ *
+ * The core is pure — commits, branch names and merge subjects in, a verdict
+ * out — and the thresholds live here as constants: the reference page renders
+ * them from this module, so the bar a reader sees is the bar the code applies.
+ * `readHistory` is the one function that runs git.
+ *
+ * Every figure is a policy heuristic (council 2026-09-04), not a statistically
+ * derived threshold.
+ */
+import { spawnSync } from 'node:child_process';
+
+import { invalidReason } from './git_convention.js';
+import { makeTargetDeps } from './git_convention_carrier.js';
+import { classifySubject, COMMIT_TYPES, TICKET_GRAMMAR, type CommitFormat, type SubjectFamily } from './git_convention_grammar.js';
+
+export const MEASURE_LIMIT = 200;
+export const MEASURE_SINCE = '24 months ago';
+export const MIN_N = 30;
+/** The newest eligible commits read on their own for a recent switch the halves still average away. */
+export const RECENT_WINDOW = MIN_N;
+/** With three or more human authors, over the per-author-capped sample. */
+export const SHARE_BAR = 0.8;
+/** With one or two authors, uncapped: a cap of 20 would put `MIN_N` out of reach. */
+export const SMALL_TEAM_SHARE_BAR = 0.9;
+export const MIN_CAPPED_AUTHORS = 3;
+export const AUTHOR_CAP_PER_HALF = 20;
+export const BULK_IMPORT_FILES = 500;
+/** Merged branches are usually deleted, so far fewer names survive than commits. */
+export const MIN_BRANCHES = 10;
+/** The revision of the families and exclusions; a card measured under another one is re-measured. */
+export const CLASSIFIER_VERSION = '2026-10-06';
+
+export const BOT_AUTHOR = /\[bot\]|dependabot|renovate|github-actions|semantic-release|release-please/i;
+export const AUTOMATION_SUBJECT = /^Revert |^Merge |^chore\(release\)|^Bump |^v?\d+\.\d+\.\d+$/;
+
+export interface HistoryCommit {
+    author: string;
+    email: string;
+    subject: string;
+    /** Files the commit touched, or null when unknown. */
+    files: number | null;
+}
+
+export interface FamilyShare {
+    family: SubjectFamily | 'other';
+    count: number;
+    share: number;
+}
+
+export interface HalfReading {
+    n: number;
+    family: SubjectFamily | 'other' | null;
+    share: number;
+}
+
+export interface SubjectMeasurement {
+    eligible: number;
+    excluded: { bots: number; automation: number; bulk: number };
+    authors: number;
+    capped: boolean;
+    cappedTotal: number;
+    bar: number;
+    families: FamilyShare[];
+    newer: HalfReading;
+    older: HalfReading;
+    halvesAgree: boolean;
+    /** The newest `RECENT_WINDOW` eligible commits, capped per author like the halves. */
+    recent: HalfReading;
+    /** Which reading showed the switch when `migrating`. */
+    migratedBy: 'newer-half' | 'recent-window' | null;
+    /** The family to propose, or null below the bar. */
+    established: SubjectFamily | null;
+    /** True when the newer half, or the newest window, clears the bar on a family other than the history's dominant one. */
+    migrating: boolean;
+    /** Why the history is below the bar; empty when a family is established. */
+    reasons: string[];
+    /** The two strongest families with a grammar, strongest first. */
+    strongest: SubjectFamily[];
+}
+
+function _key(c: HistoryCommit): string {
+    return (c.email || c.author).toLowerCase();
+}
+
+function _cap(commits: readonly HistoryCommit[]): HistoryCommit[] {
+    const seen = new Map<string, number>();
+    return commits.filter((c) => {
+        const k = _key(c);
+        const n = (seen.get(k) ?? 0) + 1;
+        seen.set(k, n);
+        return n <= AUTHOR_CAP_PER_HALF;
+    });
+}
+
+function _shares(commits: readonly HistoryCommit[]): FamilyShare[] {
+    const counts = new Map<SubjectFamily | 'other', number>();
+    for (const c of commits) {
+        const f = classifySubject(c.subject);
+        counts.set(f, (counts.get(f) ?? 0) + 1);
+    }
+    const total = commits.length;
+    return [...counts.entries()]
+        .map(([family, count]) => ({ family, count, share: total === 0 ? 0 : count / total }))
+        .sort((a, b) => b.count - a.count || a.family.localeCompare(b.family));
+}
+
+function _half(commits: readonly HistoryCommit[]): HalfReading {
+    const top = _shares(commits)[0];
+    return { n: commits.length, family: top?.family ?? null, share: top?.share ?? 0 };
+}
+
+function _clears(n: number, top: FamilyShare | HalfReading | undefined, bar: number): top is FamilyShare | HalfReading {
+    return n >= MIN_N && top !== undefined && top.family !== null && top.family !== 'other' && top.share >= bar;
+}
+
+/** `commits` newest first, as `git log` prints them. */
+export function measureSubjects(commits: readonly HistoryCommit[]): SubjectMeasurement {
+    const excluded = { bots: 0, automation: 0, bulk: 0 };
+    const eligible = commits.filter((c) => {
+        if (BOT_AUTHOR.test(c.author) || BOT_AUTHOR.test(c.email)) excluded.bots++;
+        else if (AUTOMATION_SUBJECT.test(c.subject)) excluded.automation++;
+        else if (c.files !== null && c.files > BULK_IMPORT_FILES) excluded.bulk++;
+        else return true;
+        return false;
+    });
+    const authors = new Set(eligible.map(_key)).size;
+    const capped = authors >= MIN_CAPPED_AUTHORS;
+    const bar = capped ? SHARE_BAR : SMALL_TEAM_SHARE_BAR;
+    // Split before capping: a cap over the whole sample lets one author's
+    // newest commits fill the quota and empty the older half.
+    const cut = Math.ceil(eligible.length / 2);
+    const newerRaw = eligible.slice(0, cut);
+    const olderRaw = eligible.slice(cut);
+    const newerSample = capped ? _cap(newerRaw) : newerRaw;
+    const olderSample = capped ? _cap(olderRaw) : olderRaw;
+    const sample = [...newerSample, ...olderSample];
+    const families = _shares(sample);
+    const newer = _half(newerSample);
+    const older = _half(olderSample);
+    const halvesAgree = newer.family !== null && newer.family === older.family;
+    const recent = _half((capped ? _cap(eligible) : eligible).slice(0, RECENT_WINDOW));
+    const top = families[0];
+
+    let established: SubjectFamily | null = null;
+    let migrating = false;
+    let migratedBy: SubjectMeasurement['migratedBy'] = null;
+    const reasons: string[] = [];
+    if (eligible.length < MIN_N) reasons.push(`n ${eligible.length} < ${MIN_N}`);
+    if (top === undefined || top.family === 'other') reasons.push('no family with a grammar leads');
+    else if (top.share < bar) reasons.push(`${top.family} at ${pct(top.share)} < ${pct(bar)}`);
+    if (!halvesAgree && eligible.length > 0) reasons.push(`the halves disagree (newer ${newer.family ?? '—'}, older ${older.family ?? '—'})`);
+    if (reasons.length === 0 && top !== undefined) established = top.family as SubjectFamily;
+    else if (!halvesAgree && _clears(newer.n, newer, bar)) {
+        established = newer.family as SubjectFamily;
+        migrating = true;
+        migratedBy = 'newer-half';
+    }
+    // A switch younger than half the sample: both halves still read the old
+    // family, so only the newest window shows the history has moved on.
+    if (!migrating && recent.n >= RECENT_WINDOW && recent.family !== top?.family && _clears(recent.n, recent, bar)) {
+        established = recent.family as SubjectFamily;
+        migrating = true;
+        migratedBy = 'recent-window';
+        reasons.push(`the newest ${recent.n} read ${recent.family} at ${pct(recent.share)}, not ${top?.family ?? '—'}`);
+    }
+    return {
+        eligible: eligible.length,
+        excluded,
+        authors,
+        capped,
+        cappedTotal: sample.length,
+        bar,
+        families,
+        newer,
+        older,
+        halvesAgree,
+        recent,
+        migratedBy,
+        established,
+        migrating,
+        reasons: established === null || migrating ? reasons : [],
+        strongest: families.filter((f) => f.family !== 'other').slice(0, 2).map((f) => f.family as SubjectFamily),
+    };
+}
+
+export type BranchShape = '{type}/{ticket}-{slug}' | '{type}/{ticket}/{slug}' | '{ticket}-{slug}' | '{ticket}/{slug}' | '{type}/{slug}';
+
+const BRANCH_TYPES = [...COMMIT_TYPES, 'feature', 'bugfix', 'hotfix'].join('|');
+const BRANCH_SHAPES: ReadonlyArray<readonly [BranchShape, RegExp]> = [
+    ['{type}/{ticket}-{slug}', new RegExp(`^(${BRANCH_TYPES})/${TICKET_GRAMMAR}-[^/]+$`)],
+    ['{type}/{ticket}/{slug}', new RegExp(`^(${BRANCH_TYPES})/${TICKET_GRAMMAR}/[^/]+$`)],
+    ['{ticket}-{slug}', new RegExp(`^${TICKET_GRAMMAR}-[^/]+$`)],
+    ['{ticket}/{slug}', new RegExp(`^${TICKET_GRAMMAR}/[^/]+$`)],
+    ['{type}/{slug}', new RegExp(`^(${BRANCH_TYPES})/[^/]+$`)],
+];
+const BOT_BRANCH = /^(dependabot|renovate|release-please)[/-]/;
+
+export interface BranchMeasurement {
+    sampled: number;
+    shapes: { shape: BranchShape | 'other'; count: number; share: number }[];
+    /** A pattern the reader accepts, or null when no shape clears the bar. */
+    pattern: BranchShape | null;
+    share: number;
+}
+
+export function classifyBranch(name: string): BranchShape | 'other' {
+    return BRANCH_SHAPES.find(([, re]) => re.test(name))?.[0] ?? 'other';
+}
+
+/** Branch names without their remote prefix; the default branch and bots already excluded by the caller or here. */
+export function measureBranches(names: readonly string[]): BranchMeasurement {
+    const sample = names.filter((n) => !BOT_BRANCH.test(n));
+    const counts = new Map<BranchShape | 'other', number>();
+    for (const n of sample) {
+        const s = classifyBranch(n);
+        counts.set(s, (counts.get(s) ?? 0) + 1);
+    }
+    const shapes = [...counts.entries()]
+        .map(([shape, count]) => ({ shape, count, share: count / sample.length }))
+        .sort((a, b) => b.count - a.count || a.shape.localeCompare(b.shape));
+    const top = shapes[0];
+    const clear = top !== undefined && top.shape !== 'other' && sample.length >= MIN_BRANCHES && top.share >= SHARE_BAR
+        && invalidReason('branch_pattern', top.shape) === null;
+    return { sampled: sample.length, shapes, pattern: clear ? (top.shape as BranchShape) : null, share: top?.share ?? 0 };
+}
+
+export interface UpdateStyle {
+    merges: number;
+    baseMerges: number;
+    observed: 'merge' | 'linear';
+}
+
+/** Merges of the default branch into a topic branch, read from their default subjects. */
+export function measureUpdateStyle(mergeSubjects: readonly string[], defaultBranch: string): UpdateStyle {
+    const name = defaultBranch.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const base = new RegExp(`^Merge (remote-tracking )?branch '(origin/)?${name}'`);
+    const baseMerges = mergeSubjects.filter((s) => base.test(s)).length;
+    return { merges: mergeSubjects.length, baseMerges, observed: baseMerges > 0 ? 'merge' : 'linear' };
+}
+
+/** The `git.commit_format` value a family maps to, or null when it maps to none. */
+export function formatForFamily(family: SubjectFamily): CommitFormat | null {
+    if (family === 'conventional') return 'ticket-scope';
+    if (family === 'ticket-conventional') return 'ticket-conventional';
+    return null;
+}
+
+/** The `.git-convention.yml` content for a choice, or null when neither key has a value. `update_strategy` is never written. */
+export function teamFile(family: SubjectFamily | null, pattern: BranchShape | null): string | null {
+    const format = family === null ? null : formatForFamily(family);
+    if (format === null && pattern === null) return null;
+    return ['git:', ...(format === null ? [] : [`  commit_format: ${format}`]), ...(pattern === null ? [] : [`  branch_pattern: "${pattern}"`]), ''].join('\n');
+}
+
+export function pct(x: number): string {
+    return `${Math.round(x * 100)} %`;
+}
+
+function _git(cwd: string, args: readonly string[]): string | null {
+    const r = spawnSync('git', args, { cwd, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+    return r.status === 0 ? r.stdout : null;
+}
+
+export interface History {
+    trunk: string;
+    defaultBranch: string;
+    commits: HistoryCommit[];
+    branches: string[];
+    mergeSubjects: string[];
+    /** True when `MEASURE_SINCE` yielded fewer than `MIN_N` commits and the newest ones were read regardless of age. */
+    windowExtended: boolean;
+}
+
+/** No default branch could be resolved, so nothing was sampled; `reason` says why. */
+export interface TrunkUnresolved {
+    unresolved: string;
+}
+
+/**
+ * The default branch as the carrier resolves it, or why there is none. A
+ * branch name guessed in its place (`main`, `master`, the current `HEAD`)
+ * samples another history and proposes a convention from it.
+ */
+function _trunk(cwd: string): { trunk: string; remote: string; name: string } | TrunkUnresolved {
+    const ref = makeTargetDeps(cwd).defaultBranch();
+    if (ref === null) {
+        return { unresolved: 'no default branch could be resolved — origin names none and refs/remotes/origin/HEAD is not set' };
+    }
+    if (_git(cwd, ['rev-parse', '-q', '--verify', `${ref}^{commit}`]) === null) {
+        return { unresolved: `the default branch ${ref} is not in this checkout — fetch it first` };
+    }
+    const slash = ref.indexOf('/');
+    return { trunk: ref, remote: ref.slice(0, slash), name: ref.slice(slash + 1) };
+}
+
+/**
+ * The sample `measureSubjects`, `measureBranches` and `measureUpdateStyle` read,
+ * `TrunkUnresolved` without a default branch, or null outside a git repository.
+ */
+export function readHistory(cwd: string, limit = MEASURE_LIMIT): History | TrunkUnresolved | null {
+    if (_git(cwd, ['rev-parse', '--git-dir']) === null) return null;
+    const t = _trunk(cwd);
+    if ('unresolved' in t) return t;
+    const read = (since: readonly string[]): HistoryCommit[] =>
+        (_git(cwd, ['log', t.trunk, '--no-merges', '-n', String(limit), ...since, '--pretty=format:%x1e%aN%x09%aE%x09%s', '--shortstat']) ?? '')
+            .split('\x1e')
+            .filter((r) => r.trim() !== '')
+            .map((r) => {
+                const [head = '', ...rest] = r.split('\n');
+                const [author = '', email = '', ...subject] = head.split('\t');
+                const stat = /(\d+) files? changed/.exec(rest.join('\n'));
+                return { author, email, subject: subject.join('\t'), files: stat === null ? null : Number(stat[1]) };
+            });
+    // A quiet or archived project has its convention in older commits; a
+    // window that samples nothing would report "below the bar" for a history
+    // that states its format plainly.
+    let commits = read([`--since=${MEASURE_SINCE}`]);
+    let windowExtended = false;
+    if (commits.length < MIN_N) {
+        const all = read([]);
+        windowExtended = all.length > commits.length;
+        if (windowExtended) commits = all;
+    }
+    const refs = _git(cwd, ['for-each-ref', '--format=%(refname:short)', 'refs/remotes']) ?? '';
+    const branches = refs
+        .split('\n')
+        .map((r) => r.trim())
+        .filter((r) => r !== '' && r.includes('/'))
+        .map((r) => ({ remote: r.slice(0, r.indexOf('/')), name: r.slice(r.indexOf('/') + 1) }))
+        .filter((b) => b.name !== 'HEAD' && !(b.name === t.name && b.remote === t.remote))
+        .map((b) => b.name);
+    const merges = _git(cwd, ['log', '--all', '--merges', '-n', String(limit), `--since=${MEASURE_SINCE}`, '--pretty=format:%s']) ?? '';
+    return {
+        trunk: t.trunk,
+        defaultBranch: t.name,
+        commits,
+        branches,
+        mergeSubjects: merges.split('\n').filter((s) => s !== ''),
+        windowExtended,
+    };
+}

package/src/scripts/_lib/gitignore_block.ts

@@ -0,0 +1,314 @@
+/**
+ * The `.gitignore` managed-block logic, with no CLI entry.
+ *
+ * WHY IT IS NOT IN `sync_gitignore.ts` ANY MORE. That file ends in a
+ * `process.exit(main(...))` behind a CLI-entry guard, and `check_installer_import_purity`
+ * refuses any module-level exit reachable from `install.ts`: esbuild inlines the
+ * whole closure into `dist/install/install.mjs`, where the guard comparing
+ * `import.meta.url` to `process.argv[1]` evaluates TRUE because the bundle IS
+ * argv[1]. A consumer install would then exit after writing its payload.
+ *
+ * So the pure half lives here, with no entry and no exit, and `sync_gitignore.ts`
+ * re-exports every name it used to own — the CLI contract and the ported
+ * pytest suite's snake_case call sites are unchanged.
+ *
+ * Everything below is byte-for-byte the behaviour it had in that file,
+ * including the historical quirks downstream consumers pin.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const SECTION_HEADER = '# event4u/agent-config';
+export const SECTION_FOOTER = '# event4u/agent-config — END';
+export const DEFAULT_GITIGNORE = '.gitignore';
+
+const _HERE = fileURLToPath(import.meta.url);
+// _HERE === <repo>/src/scripts/_lib/gitignore_block.ts, so the repo root is
+// three directories up. The retired Python implementation derived
+// DEFAULT_TEMPLATE = <file>.parent.parent.parent / "src" / "config" /
+// "gitignore-block.txt" from one level higher; the extra `..` here is that
+// same root reached from one level deeper.
+export const DEFAULT_TEMPLATE = path.join(
+    path.dirname(_HERE),
+    '..',
+    '..',
+    '..',
+    'src',
+    'config',
+    'gitignore-block.txt',
+);
+
+// Legacy patterns that lived in older versions of src/config/gitignore-block.txt
+// before runtime artefacts moved under /agents/runtime/ (May 2026). They get
+// stripped wherever they appear in the consumer's .gitignore — inside the
+// managed block or outside (older installers / hand-edits). Current canonical
+// equivalents (e.g. /agents/runtime/.agent-prices.md) come from the template
+// and are NOT affected. Leading-slash variants are matched defensively.
+//
+// Authoritative source: src/config/agents-paths.yml entries with `legacy: true`.
+// Manual sync until the generation step from the manifest is implemented
+// (road-to-agents-dir-and-gitignore-hygiene Phase 3.2 follow-on).
+export const LEGACY_PATTERNS: readonly string[] = [
+    '.agent-chat-history',
+    '.agent-chat-history.bak',
+    '.agent-chat-history.*.bak',
+    '.agent-prices.md',
+    '.council-tmp/',
+    // 2.x intermediate: prices cache lived directly under agents/ before
+    // consolidating under agents/runtime/.
+    'agents/.agent-prices.md',
+    // Budget history JSONLs — previously listed explicitly at project
+    // root or under agents/; now covered by the /agents/runtime/
+    // catch-all in the managed block.
+    '.augment-budget-history.jsonl',
+    '.rule-budget-history.jsonl',
+    'agents/.augment-budget-history.jsonl',
+    'agents/.rule-budget-history.jsonl',
+];
+
+export function _strip(ln: string): string {
+    // Python: ln.rstrip("\n").rstrip() — strip a trailing newline, then strip
+    // all trailing whitespace.
+    return ln.replace(/\n+$/, '').replace(/\s+$/, '');
+}
+
+export function _is_entry(ln: string): boolean {
+    // Non-empty, non-comment line = a path/pattern entry.
+    const s = _strip(ln).replace(/^\s+/, '');
+    return Boolean(s) && !s.startsWith('#');
+}
+
+/** Error raised when the template file is missing (→ exit 2 in main). */
+export class TemplateNotFoundError extends Error {
+    constructor(p: string) {
+        super(`template not found: ${p}`);
+        this.name = 'TemplateNotFoundError';
+    }
+}
+
+export function _isFile(p: string): boolean {
+    try {
+        return fs.statSync(p).isFile();
+    } catch {
+        return false;
+    }
+}
+
+/** Python str.splitlines() — split on universal newlines, no trailing empty. */
+export function _splitlines(text: string): string[] {
+    if (text === '') return [];
+    // str.splitlines() splits on \n, \r, \r\n (and more) and does NOT keep a
+    // trailing empty element. The targets here only ever contain \n / \r\n.
+    const parts = text.split(/\r\n|\r|\n/);
+    if (parts.length > 0 && parts[parts.length - 1] === '') parts.pop();
+    return parts;
+}
+
+export function load_template(p: string): string[] {
+    if (!_isFile(p)) {
+        throw new TemplateNotFoundError(p);
+    }
+    const text = fs.readFileSync(p, 'utf-8');
+    // Keep trailing newlines stripped; we splice explicit newlines.
+    return _splitlines(text).map(_strip);
+}
+
+/**
+ * Locate the managed block; return [start_idx, end_idx_exclusive] or null.
+ *
+ * `start_idx` points at the SECTION_HEADER line.
+ * `end_idx_exclusive` points one past the last line of the block.
+ * Honors explicit SECTION_FOOTER when present; otherwise treats the
+ * block as extending to EOF or to the next non-managed section.
+ */
+export function find_block(lines: readonly string[]): [number, number] | null {
+    for (let i = 0; i < lines.length; i += 1) {
+        if (_strip(lines[i] as string) === SECTION_HEADER) {
+            const start = i;
+            // Explicit footer?
+            for (let j = i + 1; j < lines.length; j += 1) {
+                if (_strip(lines[j] as string) === SECTION_FOOTER) {
+                    return [start, j + 1];
+                }
+            }
+            // Legacy: extend to EOF or next non-managed section break.
+            let end = lines.length;
+            for (let j = i + 1; j < lines.length; j += 1) {
+                const s = _strip(lines[j] as string).replace(/^\s+/, '');
+                if (
+                    s.startsWith('#') &&
+                    !s.startsWith('# Agent config') &&
+                    s !== SECTION_HEADER
+                ) {
+                    end = j;
+                    while (end > i + 1 && _strip(lines[end - 1] as string) === '') {
+                        end -= 1;
+                    }
+                    break;
+                }
+            }
+            return [start, end];
+        }
+    }
+    return null;
+}
+
+/** Return entries (paths/patterns) present in the given block. */
+export function block_entries(block_lines: readonly string[]): string[] {
+    return block_lines
+        .filter((ln) => _is_entry(ln))
+        .map((ln) => _strip(ln).replace(/^\s+/, ''));
+}
+
+export function template_entries(template_lines: readonly string[]): string[] {
+    return template_lines.filter((ln) => _is_entry(ln)).map((ln) => ln.replace(/^\s+/, ''));
+}
+
+/** Return a fresh, fully-managed block with START + body + END. */
+export function build_fresh_block(template_lines: readonly string[]): string[] {
+    return [SECTION_HEADER, ...template_lines, SECTION_FOOTER];
+}
+
+/**
+ * Return [new_lines, added_entries].
+ *
+ * - If block missing: append fresh block (preceded by a blank line if the
+ *   file's last line is not already empty).
+ * - If block present and replace=true: rewrite block in full.
+ * - If block present and replace=false: append any missing managed entries
+ *   before the END marker (adding END if absent). User-added lines inside the
+ *   block are preserved.
+ */
+export function sync_block(
+    existing_lines: readonly string[],
+    template_lines: readonly string[],
+    options: { replace?: boolean } = {},
+): [string[], string[]] {
+    const replace = options.replace ?? false;
+    const loc = find_block(existing_lines);
+    const fresh = build_fresh_block(template_lines);
+
+    // Missing block → append with leading blank if needed.
+    if (loc === null) {
+        const newLines = [...existing_lines];
+        if (newLines.length > 0 && _strip(newLines[newLines.length - 1] as string) !== '') {
+            newLines.push('');
+        }
+        newLines.push(...fresh);
+        return [newLines, template_entries(template_lines)];
+    }
+
+    const [start, end] = loc;
+    const head = existing_lines.slice(0, start);
+    let block = existing_lines.slice(start, end);
+    const tail = existing_lines.slice(end);
+
+    if (replace) {
+        const existing = new Set(block_entries(block));
+        const added = template_entries(template_lines).filter((e) => !existing.has(e));
+        return [[...head, ...fresh, ...tail], added];
+    }
+
+    // Append-only mode.
+    const existing_entries = new Set(block_entries(block));
+    const missing = template_entries(template_lines).filter((e) => !existing_entries.has(e));
+    if (missing.length === 0) {
+        return [[...existing_lines], []];
+    }
+
+    // Ensure block ends with SECTION_FOOTER; insert missing entries right
+    // before it.
+    let insert_at: number;
+    if (block.length > 0 && _strip(block[block.length - 1] as string) === SECTION_FOOTER) {
+        insert_at = block.length - 1;
+    } else {
+        block = [...block, SECTION_FOOTER];
+        insert_at = block.length - 1;
+    }
+    const new_block = [...block.slice(0, insert_at), ...missing, ...block.slice(insert_at)];
+    return [[...head, ...new_block, ...tail], missing];
+}
+
+/**
+ * Strip legacy entries from anywhere in the file.
+ *
+ * A line is legacy when its stripped, leading-whitespace-trimmed content
+ * matches a `LEGACY_PATTERNS` entry — with or without a leading slash.
+ * Comments and blank lines are untouched; current managed entries (e.g.
+ * `/agents/.agent-chat-history`) are not in the legacy set and survive.
+ */
+export function cleanup_legacy(lines: readonly string[]): [string[], string[]] {
+    const legacy = new Set(LEGACY_PATTERNS);
+    const kept: string[] = [];
+    const removed: string[] = [];
+    for (const ln of lines) {
+        const s = _strip(ln).replace(/^\s+/, '');
+        if (legacy.has(s) || (s.startsWith('/') && legacy.has(s.slice(1)))) {
+            removed.push(s);
+            continue;
+        }
+        kept.push(ln);
+    }
+    return [kept, removed];
+}
+
+/** Join lines with newlines and enforce exactly one trailing newline. */
+export function format_file(lines: readonly string[]): string {
+    const text = lines.join('\n');
+    return text.replace(/\n+$/, '') + '\n';
+}
+
+/**
+ * Write the managed block into a project that has no wizard to do it.
+ *
+ * WHY IT EXISTS. The block is normally installed by `refresh --project` /
+ * `sync:gitignore`, which the browser wizard reaches. A `--no-ui` install
+ * reaches neither, so a headless consumer ended up with a package that writes
+ * dispatcher state under `agents/` and a `.gitignore` that says nothing about
+ * it: `git status` fills with untracked runtime files the developer did not
+ * create and cannot place.
+ *
+ * APPEND-ONLY, NEVER `replace`. A line a developer put inside the block is
+ * theirs; this adds the managed entries that are missing and touches nothing
+ * else.
+ *
+ * BEST-EFFORT THROUGHOUT. No `.gitignore` and no git repository, an unreadable
+ * template, an unwritable file — each returns 0 quietly. An installer that
+ * failed because it could not tidy a listing would be worse than the listing.
+ *
+ * Returns the number of entries added (0 when nothing changed), and writes
+ * nothing when `dry_run`. Reporting is the caller's: this module owns no
+ * output convention.
+ */
+export function write_managed_block(project_root: string, dry_run: boolean): number {
+    const target = path.join(project_root, DEFAULT_GITIGNORE);
+    let template: string[];
+    try {
+        template = load_template(DEFAULT_TEMPLATE);
+    } catch {
+        return 0;
+    }
+    let existing: string[] = [];
+    if (_isFile(target)) {
+        existing = _splitlines(fs.readFileSync(target, 'utf-8'));
+    } else if (!_isFile(path.join(project_root, '.git')) && !_isDir(path.join(project_root, '.git'))) {
+        return 0;
+    }
+    const [lines, added] = sync_block(existing, template);
+    if (added.length === 0 || dry_run) return added.length;
+    try {
+        fs.writeFileSync(target, format_file(lines), 'utf-8');
+    } catch {
+        return 0;
+    }
+    return added.length;
+}
+
+function _isDir(p: string): boolean {
+    try {
+        return fs.statSync(p).isDirectory();
+    } catch {
+        return false;
+    }
+}