@event4u/agent-config 16.4.0 → 17.0.0

package/dist/install/noGoRules.js

@@ -0,0 +1,368 @@
+/**
+ * A consumer no-go bullet, sorted into `path`, `command` or `prose`, and
+ * rendered as the deny rule it would become.
+ *
+ * `road-to-a-project-contract-written-down` step 2.1. `/agents:init` asks the
+ * consumer for no-gos and writes them into their own `AGENTS.md`. A sentence
+ * there binds every turn and the agent may still read past it. This is what
+ * turns the two kinds that CAN be enforced into rows the host refuses on, and
+ * what refuses to turn the third kind into anything at all.
+ *
+ * ```
+ * A BULLET THE FUNCTION CANNOT CLASSIFY IS `prose`, NEVER A GUESSED ROW.
+ * A ROW ON A VAGUE SENTENCE BLOCKS LEGITIMATE WORK AND CANNOT SAY WHY.
+ * ```
+ *
+ * Pure: it reads a string and returns a verdict. Nothing here opens a settings
+ * file — the consent prompt and the append are step 2.2's.
+ *
+ * WHAT MAKES A VERDICT. Two independent signals must agree, and either one
+ * missing is `prose`:
+ *
+ *   1. ONE backticked token. The consumer guide's own `## No-gos` shape puts
+ *      the path or the command in backticks. Zero means the bullet names
+ *      neither; two or more means the subject is ambiguous, and picking one
+ *      would be the guess this module exists to refuse.
+ *   2. An action verb from a closed vocabulary. The token's SHAPE says what it
+ *      is; only the verb says what must not happen to it. "`vendor/` is
+ *      generated" carries a path and no action, and choosing `Edit` over `Read`
+ *      on its behalf would widen or narrow a rule nobody wrote.
+ */
+/** Verbs that forbid READING. A `Read` deny also covers edits and writes. */
+const READ_VERBS = ['read', 'open', 'view', 'cat', 'print', 'dump'];
+/** Verbs that forbid CHANGING. `Edit` is the only path rule the host checks. */
+const EDIT_VERBS = [
+    'edit',
+    'modify',
+    'change',
+    'write',
+    'touch',
+    'delete',
+    'remove',
+    'rename',
+    'commit',
+    'overwrite',
+    'regenerate',
+];
+/** Verbs that forbid EXECUTING. */
+const RUN_VERBS = ['run', 'execute', 'invoke', 'call'];
+/**
+ * Words that make a bullet a PROHIBITION rather than a description.
+ *
+ * Required, and that is the correction a review forced: a verb scan alone
+ * accepts "``npm run build`` is the only sanctioned build command" and renders
+ * a deny row over the command the bullet PRESCRIBES. A no-go section is not the
+ * only place a backticked command appears in a sentence with a verb near it.
+ */
+const NEGATIONS = [
+    'never',
+    'not',
+    'no',
+    "don't",
+    'dont',
+    'avoid',
+    'forbidden',
+    'prohibited',
+];
+/**
+ * Text that ends the clause the prohibition governs.
+ *
+ * The second half of the same correction. "Never run migrations in production
+ * - use `php artisan migrate --pretend` instead" negates, carries a run verb,
+ * and carries a backticked command — and the command is the ESCAPE HATCH the
+ * bullet recommends. A separator between the verb and the token means the token
+ * belongs to a different clause, so the verdict is prose.
+ */
+const CLAUSE_BREAK = /(?:^|\s)[-–—](?:\s|$)|[;:,()]|\b(?:instead|use|using|prefer|except|unless|but|rather|need|needs|needed|necessary|required|optional|if|when|while|without|before|after|until|other than)\b/i;
+/**
+ * Words between the negation and the verb that INVERT what the negation does.
+ *
+ * The structural half of the fix, because a word list alone has now failed
+ * three times. "Don't forget to run `npm ci`" negates the OMISSION of the
+ * action, so the sentence prescribes exactly what a deny row would forbid.
+ * The shape is always the same — a negation, a verb of omission or
+ * hesitation, an infinitive marker, then the real verb — and `to` is the part
+ * that gives it away: a prohibition reads "never run X", never "never
+ * <something> to run X".
+ *
+ * So: an infinitive `to` between the negation and the action verb means the
+ * action is the OBJECT of some other verb rather than the thing forbidden.
+ * That catches `forget`, `hesitate`, `fail`, `neglect` and every sibling
+ * nobody has thought of yet, which a fourth word list would not.
+ */
+const INVERTS_THE_NEGATION = /\bto\b/i;
+/** Backticked spans replaced by spaces, so a verb INSIDE the token is not read as the bullet's verb. */
+function maskTokens(bullet) {
+    return bullet.replace(/`[^`]+`/g, (m) => ' '.repeat(m.length));
+}
+/** First index at which any whole word in `words` occurs, or -1. */
+function firstWordIndex(haystack, words) {
+    let best = -1;
+    for (const w of words) {
+        const m = new RegExp(`\\b${w}\\b`, 'i').exec(haystack);
+        if (m !== null && (best === -1 || m.index < best))
+            best = m.index;
+    }
+    return best;
+}
+/** The first action verb at or after `from`, or `null`. */
+function verbAfter(masked, from) {
+    const groups = [
+        ['run', RUN_VERBS],
+        ['read', READ_VERBS],
+        ['edit', EDIT_VERBS],
+    ];
+    let best = null;
+    for (const [action, verbs] of groups) {
+        for (const v of verbs) {
+            const re = new RegExp(`\\b${v.replace("'", "'?")}\\b`, 'gi');
+            let m = re.exec(masked);
+            while (m !== null) {
+                if (m.index >= from && (best === null || m.index < best.start)) {
+                    best = { action, start: m.index, end: m.index + m[0].length };
+                }
+                m = re.exec(masked);
+            }
+        }
+    }
+    return best;
+}
+/** The backticked spans of a bullet, in order. */
+function backticked(bullet) {
+    const out = [];
+    const re = /`([^`]+)`/g;
+    let m = re.exec(bullet);
+    while (m !== null) {
+        const inner = m[1].trim();
+        if (inner.length > 0)
+            out.push(inner);
+        m = re.exec(bullet);
+    }
+    return out;
+}
+/**
+ * Does `token` look like a filesystem path?
+ *
+ * A path separator, a leading dot, or a file extension. A bare word is NOT a
+ * path: `migrations` alone could be a directory or a command, and the guide's
+ * own example writes the trailing slash.
+ */
+/**
+ * File extensions a single-dot token is accepted on.
+ *
+ * A closed list, because neither open rule works. `/\.[A-Za-z0-9]+$/` accepted
+ * `users.id`, `app.debug` and `v2.1`; the replacement that excluded
+ * all-lowercase single-dot tokens refused `package.json`, `main.go` and
+ * `index.js` — a consumer's most likely first no-go — while still accepting
+ * `Users.id` and `my_table.id`. Both were measured; the list is what
+ * distinguishes the two classes.
+ *
+ * It is NOT exhaustive, and an earlier version of this comment said it
+ * distinguished them "without guessing either way", which overstated it.
+ * `Dockerfile`, `Makefile`, `terraform.tfvars`, `build.gradle`, `app.vue` and
+ * a long tail of real extensions fall to prose. The direction is the safe one
+ * — no row is built and a reason is printed — and a consumer who means a path
+ * can always write the trailing slash or a `/`, which both bypass this list.
+ */
+const FILE_EXTENSIONS = new Set([
+    'cjs', 'conf', 'css', 'csv', 'env', 'go', 'html', 'ini', 'java', 'js', 'json', 'jsx',
+    'kt', 'lock', 'log', 'md', 'mjs', 'php', 'pem', 'py', 'rb', 'rs', 'scss', 'sh', 'sql',
+    'sqlite', 'svg', 'toml', 'ts', 'tsx', 'txt', 'xml', 'yaml', 'yml',
+]);
+function looksLikePath(token) {
+    if (/\s/.test(token))
+        return false;
+    if (token.includes('/'))
+        return true;
+    if (token.startsWith('.'))
+        return true;
+    const dot = token.lastIndexOf('.');
+    if (dot <= 0)
+        return false;
+    return FILE_EXTENSIONS.has(token.slice(dot + 1).toLowerCase());
+}
+/**
+ * Characters that make a path token mean something other than it reads.
+ *
+ * `!` is a gitignore NEGATION on the host: a deny row starting with it carves
+ * paths OUT of the deny rules listed before it, so a no-go bullet would weaken
+ * a consumer's existing list while being shown as a deny row. `[`, `]` and `?`
+ * are gitignore character classes, and the host does not escape a rule you
+ * wrote yourself — `reports/[2024]/**` matches `reports/2/`, never the
+ * directory the consumer named.
+ *
+ * A single leading `/` joins them, and the page carries a warning box about it:
+ * a pattern with one leading slash "isn't an absolute path. The single leading
+ * slash anchors at the settings source, not the filesystem root" — the page's
+ * own example of the mistake is elided here because a home-shaped literal in a
+ * published file is what `check_bundle_path_leakage` exists to refuse. A
+ * consumer who writes `` `/etc/passwd` `` means the absolute path, and the row
+ * would guard `<working directory>/etc/passwd` — a path that does not exist.
+ *
+ * `*` is deliberately NOT here: a consumer who writes `src/generated/**` means
+ * that glob, and the guide teaches the trailing slash for everything else.
+ */
+const UNSAFE_PATH_CHARS = /^!|^\/(?!\/)|[[\]?]/;
+const PROSE = (bullet, reason) => ({
+    bullet,
+    kind: 'prose',
+    token: null,
+    action: null,
+    reason,
+});
+/** Strip a leading markdown list marker, if present. */
+function stripMarker(line) {
+    return line.replace(/^\s*[-*+]\s+/, '').trim();
+}
+export function classifyNoGo(raw) {
+    const bullet = stripMarker(raw);
+    if (bullet.length === 0)
+        return PROSE(bullet, 'empty bullet');
+    const tokens = backticked(bullet);
+    if (tokens.length === 0) {
+        return PROSE(bullet, 'names no path and no command in backticks');
+    }
+    if (tokens.length > 1) {
+        return PROSE(bullet, `${String(tokens.length)} backticked tokens — the subject is ambiguous, so no row is built`);
+    }
+    const token = tokens[0];
+    const masked = maskTokens(bullet);
+    const tokenAt = bullet.indexOf(`\`${token}\``);
+    const negAt = firstWordIndex(masked, NEGATIONS);
+    if (negAt === -1) {
+        return PROSE(bullet, 'states no prohibition, so the backticked token may be what the bullet recommends');
+    }
+    const verb = verbAfter(masked, negAt);
+    if (verb === null) {
+        return PROSE(bullet, 'names no action verb, so what must not happen to it is unstated');
+    }
+    // The negation must govern the VERB too, not merely appear earlier in the
+    // line. Without this, "If no cache exists, run `npm run build`" and "There
+    // is no need to run `npm install`" both denied the command they permit —
+    // round 1's finding narrowed rather than closed, measured by round 2.
+    const negToVerb = masked.slice(negAt, verb.start);
+    if (CLAUSE_BREAK.test(negToVerb)) {
+        return PROSE(bullet, 'the prohibition and the action verb sit in different clauses, so the bullet may ' +
+            'be permitting rather than forbidding');
+    }
+    if (INVERTS_THE_NEGATION.test(negToVerb)) {
+        return PROSE(bullet, 'the action is the object of another verb rather than the thing forbidden — ' +
+            '"do not forget to X" asks for X, it does not forbid it');
+    }
+    if (verb.start > tokenAt) {
+        return PROSE(bullet, 'the action verb comes after the token, so the two may not be related');
+    }
+    const between = bullet.slice(verb.end, tokenAt);
+    if (CLAUSE_BREAK.test(between)) {
+        return PROSE(bullet, `\`${token}\` sits in a different clause from the prohibition — it may be the ` +
+            'alternative the bullet recommends, so no rule is built');
+    }
+    if (verb.action === 'run') {
+        return {
+            bullet,
+            kind: 'command',
+            token,
+            action: verb.action,
+            reason: 'a negated run verb over a backticked command',
+        };
+    }
+    const action = verb.action;
+    if (!looksLikePath(token)) {
+        return PROSE(bullet, `a ${action} verb over \`${token}\`, which has no path shape — no rule is built`);
+    }
+    if (UNSAFE_PATH_CHARS.test(token)) {
+        return PROSE(bullet, `\`${token}\` carries a gitignore metacharacter (\`!\`, \`[\`, \`]\` or \`?\`) that the ` +
+            'host does not escape, so a rule built from it would guard something else');
+    }
+    return {
+        bullet,
+        kind: 'path',
+        token,
+        action,
+        reason: action === 'read'
+            ? 'a read verb over a backticked path'
+            : 'an edit verb over a backticked path',
+    };
+}
+/**
+ * Every bullet of a `## No-gos` section, in file order.
+ *
+ * Non-bullet lines — the heading, blanks, a sentence between bullets — are not
+ * no-gos and are skipped rather than classified as prose: a prose verdict is a
+ * statement about a bullet somebody wrote, and a heading is not one.
+ */
+export function classifyNoGos(section) {
+    return section
+        .split('\n')
+        .filter((line) => /^\s*[-*+]\s+\S/.test(line))
+        .map((line) => classifyNoGo(line));
+}
+/** The `##` heading spellings a no-gos section is written under. */
+const NO_GOS_HEADINGS = new Set(['no-gos', 'no-gos (never do this)']);
+/**
+ * The body of a consumer `AGENTS.md`'s `## No-gos` section, or `''`.
+ *
+ * Skips fenced blocks for the reason `report_project_contract` does, and it is
+ * the same load-bearing reason rather than a shared habit: the consumer guide
+ * ships this exact heading INSIDE a ```markdown fence as copy-in material, so a
+ * reader without the skip would classify the guide's own example bullets and
+ * offer to deny `migrations/` in a repository that never asked.
+ */
+export function extractNoGosSection(body) {
+    const out = [];
+    /** The open fence's marker character AND its length. */
+    let fence = null;
+    let inside = false;
+    const lines = body.split('\n');
+    for (let n = 0; n < lines.length; n += 1) {
+        const line = lines[n].trimEnd();
+        const open = /^\s*(`{3,}|~{3,})/.exec(line);
+        if (open !== null) {
+            const marker = open[1];
+            const char = marker[0];
+            if (fence === null) {
+                fence = { char, len: marker.length };
+                continue;
+            }
+            // A fence closes only on the SAME character and at least its own
+            // length. Tracking the character alone let a ````-delimited block
+            // close on its first inner ``` line, so the rest of a guide's
+            // copy-in example was read as the consumer's own rules.
+            if (char === fence.char && marker.length >= fence.len)
+                fence = null;
+            continue;
+        }
+        if (fence !== null)
+            continue;
+        // A setext underline turns the PREVIOUS line into a heading, which
+        // closes the section the same way an ATX heading does — but ONLY when
+        // that previous line is a paragraph. After a blank line or a list
+        // item, CommonMark makes `---` a thematic break, and the first version
+        // of this branch treated every one of them as a heading: it popped the
+        // preceding bullet and closed the section, so a `---` separator before
+        // the next heading silently ate bullets. Silently is the word that
+        // matters — a dropped bullet produces no row AND no reason line, so
+        // the consent screen never mentions it.
+        const prev = out.length > 0 ? out[out.length - 1] : '';
+        const prevIsParagraph = prev.trim().length > 0 && !/^\s*[-*+>#]|^\s*\d+[.)]/.test(prev);
+        if (/^(?:=+|-{2,})\s*$/.test(line) && inside && prevIsParagraph) {
+            out.pop();
+            inside = false;
+            continue;
+        }
+        // ANY heading level closes the section; only a level-two one with a
+        // matching title opens it. Matching `##` alone let a following `#
+        // Appendix` leave the section open, so every bullet of every later
+        // top-level section was classified as a no-go.
+        const h = /^(#{1,6})[ \t]+(.+?)[ \t]*#*$/.exec(line);
+        if (h !== null) {
+            const level2 = h[1].length === 2;
+            inside = level2 && NO_GOS_HEADINGS.has(h[2].trim().toLowerCase());
+            continue;
+        }
+        if (inside)
+            out.push(line);
+    }
+    return out.join('\n');
+}
+//# sourceMappingURL=noGoRules.js.map

package/dist/install/ownershipLedger.js

@@ -0,0 +1,133 @@
+/**
+ * The user-scoped ownership ledger.
+ *
+ * WHY IT EXISTS. A globally installed file's record of what this package wrote
+ * lived only in a PROJECT manifest, and that manifest is written only when the
+ * install runs from a directory carrying project settings. Run the install from
+ * anywhere else and nothing was recorded; run it from a second project and that
+ * project's manifest recorded nothing about the first. With no recorded digest
+ * the writer could not tell a user's edit from our bytes and overwrote it, and
+ * the reaper deleted an edited file the package retired without ever reading it.
+ * Whether an edit survived depended on the working directory of a later install.
+ *
+ * WHERE IT LIVES. In the global deploy inventory every global deploy already
+ * writes (`global_deploy_inventory.ts`, schema 2, additive `digests`), so the
+ * record belongs to the user, not to whichever project an install ran from. The
+ * AI council's reading of ADR-020 (2026-10-16) bounds it: ownership metadata only, no project key, no artefact selection.
+ *
+ * WHAT IT RECORDS per file: the digest of the bytes we INSTALLED and the digest
+ * of the bytes we would install NOW — two, because one cannot distinguish "the
+ * user changed it" from "we shipped a new version of it".
+ *
+ * - A file this run wrote or found identical: both are the on-disk digest.
+ * - A file this run PRESERVED: both are the digest of the content STAGED beside
+ *   it — the package content this installer last produced for the path, the
+ *   meaning the project manifest gives the same field (`manifestFiles.ts`,
+ *   `reconcileToolFiles`). That is what makes the documented resolution work:
+ *   merge the sidecar and the file matches, so the next install is clean.
+ *   Keeping the older digest would leave a correctly merged file looking
+ *   edited forever. What it must never be is a re-hash of the target: that
+ *   records the user's edit as ours, and the next run overwrites it.
+ * - The staged sidecar: its own digest, `kind: "sidecar"` — the only proof that
+ *   this installer wrote that file, so a later version may refresh it.
+ * - A retired file the user edited: kept on disk, kept in the record with
+ *   `packaged_sha256: null`, so the next run reads it as retired-modified again
+ *   instead of as an untracked tagged orphan it would delete.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as global_deploy_inventory from '../scripts/_lib/global_deploy_inventory.js';
+import { sidecarPathFor } from './preserve.js';
+/**
+ * Anchor-relative POSIX path of `abs`, or `null` when it is not under `anchor`.
+ *
+ * Tried against the anchor as given AND its realpath: the reapers report paths
+ * under the RESOLVED anchor, the copy loop under the lexical one, and on macOS
+ * a temp or home tree differs between the two by a symlinked prefix.
+ */
+function relUnder(anchor, abs) {
+    let real = anchor;
+    try {
+        real = fs.realpathSync(anchor);
+    }
+    catch {
+        /* the anchor does not exist yet — the lexical form is all there is */
+    }
+    for (const base of [anchor, real]) {
+        const rel = path.relative(path.resolve(base), path.resolve(abs));
+        if (rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel)) {
+            return rel.split(path.sep).join('/');
+        }
+    }
+    return null;
+}
+/**
+ * Reap what the package no longer ships — sparing edited files — then record
+ * the ledger for one tool and save it.
+ *
+ * Replaces the load → reap → record → save sequence the installer ran inline,
+ * so the two reapers and the record are fed one consistent view: the sidecars
+ * staged this run are part of what "should exist", or the reaper would delete
+ * the package content it was just told to stage.
+ */
+export function recordGlobalDeploy(r) {
+    const inventory = global_deploy_inventory.load_inventory(r.inventoryPath ?? null);
+    const previous = global_deploy_inventory.recorded_digests(r.toolId, r.anchor, inventory);
+    const sidecars = new Map();
+    for (const [abs, digest] of r.staged) {
+        const rel = relUnder(r.anchor, abs);
+        if (rel !== null && digest !== null)
+            sidecars.set(rel, digest);
+    }
+    const keep = new Set([...r.currentFiles, ...sidecars.keys()]);
+    const retainedAbs = [];
+    let reaped = [];
+    const tools = inventory['tools'] ?? {};
+    if (r.toolId in tools) {
+        reaped = reaped.concat(global_deploy_inventory.reap_stale(r.toolId, r.anchor, keep, inventory, false, retainedAbs));
+    }
+    reaped = reaped.concat(global_deploy_inventory.reap_tagged_orphans(r.anchor, [...r.destSubs], keep, r.packageTag, false, previous, retainedAbs));
+    const preservedRel = new Set();
+    for (const abs of r.preserved) {
+        const rel = relUnder(r.anchor, abs);
+        if (rel !== null)
+            preservedRel.add(rel);
+    }
+    const digests = new Map();
+    for (const rel of r.currentFiles) {
+        const abs = path.join(r.anchor, rel);
+        if (preservedRel.has(rel)) {
+            const staged = r.staged.get(sidecarPathFor(abs)) ?? null;
+            const installed = staged ?? previous.get(rel)?.installed_sha256 ?? r.recordedFor(abs);
+            if (typeof installed !== 'string' || installed === '')
+                continue;
+            digests.set(rel, { installed_sha256: installed, packaged_sha256: staged ?? installed });
+            continue;
+        }
+        const onDisk = global_deploy_inventory.file_sha256(abs);
+        if (onDisk === null)
+            continue;
+        digests.set(rel, { installed_sha256: onDisk, packaged_sha256: onDisk });
+    }
+    for (const [rel, digest] of sidecars) {
+        digests.set(rel, { installed_sha256: digest, packaged_sha256: digest, kind: 'sidecar' });
+    }
+    const retained = [...new Set(retainedAbs)].sort();
+    for (const abs of retained) {
+        const rel = relUnder(r.anchor, abs);
+        const prior = rel === null ? undefined : previous.get(rel);
+        if (rel === null || prior === undefined)
+            continue;
+        digests.set(rel, { installed_sha256: prior.installed_sha256, packaged_sha256: null });
+    }
+    global_deploy_inventory.record_deploy(r.toolId, r.anchorRaw, new Set(r.currentFiles), inventory, digests);
+    global_deploy_inventory.save_inventory(inventory, r.inventoryPath ?? null);
+    return { reaped: [...new Set(reaped)].sort(), retained };
+}
+/** The per-file line for a retired file kept because the user edited it. */
+export function retainedFileMessage(target) {
+    return (`Kept ${target}: the package no longer ships this file, but it was edited after it was ` +
+        'installed, so it was not deleted. It is no longer updated by agent-config; delete it ' +
+        'yourself when you no longer need it.');
+}
+//# sourceMappingURL=ownershipLedger.js.map

package/dist/install/plan.js

@@ -1,5 +1,5 @@
 /**
- * Plan builder — Phase A3 port of `scripts/install.py:_build_install_plan`.
+ * Plan builder — Phase A3 port of `_build_install_plan` in the retired Python installer.
  *
  * Pure: walks one or more source directories, computes the target path
  * + SHA-256 of every file, and returns a declarative {@link InstallPlan}.

package/dist/install/preflight.js

@@ -123,22 +123,53 @@ export function checkConflicts(inputs) {
         id: 'conflicts',
         severity: 'warning',
         path: c.path,
-        message: c.ownership === 'recorded-modified'
-            ? `managed ${c.kind} file has been edited since we wrote it`
-            : `existing file conflicts with planned ${c.kind} content`,
+        message: conflictMessage(c),
         // A remedy here may only describe what an install actually does. Before
         // the owner ruling of 2026-09-21 the writer overwrote every deployed
         // file unconditionally, so the `recorded-modified` arm told the
         // operator to back their edit up. It now preserves that file and stages
         // the package content beside it, so the same sentence would be false in
         // the opposite direction — it would understate a protection that ships.
-        // The `unknown` arm is unchanged: nothing is recorded for that path, so
-        // the writer still writes over it.
-        remedy: c.ownership === 'recorded-modified'
-            ? 'installing preserves your edit and stages package content as <path>.agent-config.new; --force replaces it instead'
-            : 'back up this file — installing writes the planned content over it',
+        // The `unknown` arm is NO LONGER one arm. A path the ownership ledger
+        // lists but holds no digest for is preserved too, so the back-up
+        // sentence would be false for it in the same direction the
+        // `recorded-modified` one was — it would tell the operator to save a
+        // file the installer is about to leave alone.
+        remedy: conflictRemedy(c),
     }));
 }
+/** What the operator is being told has happened to one conflicting file. */
+function conflictMessage(c) {
+    if (c.ownership === 'recorded-modified') {
+        return `managed ${c.kind} file has been edited since we wrote it`;
+    }
+    if (c.migration) {
+        return `managed ${c.kind} file predates digest tracking — an edit and an older version look alike here`;
+    }
+    return `existing file conflicts with planned ${c.kind} content`;
+}
+/**
+ * What an install will actually do to it.
+ *
+ * A remedy here may only describe what an install actually does, which is why
+ * the migration arm exists rather than reusing either neighbour: the file is
+ * preserved like an edited one, but the reason is not an edit anyone proved.
+ */
+function conflictRemedy(c) {
+    if (c.ownership === 'recorded-modified') {
+        return 'installing preserves your edit and stages package content as <path>.agent-config.new; --force replaces it instead';
+    }
+    if (c.migration) {
+        // MAY, not WILL, and the hedge is the accurate word rather than a
+        // soft one. The branch preserves only when the bytes differ from
+        // what the install would write, and that comparison needs the
+        // install-time tag, which this surface cannot apply — so a preflight
+        // that promised either outcome would be guessing at the one the
+        // writer settles.
+        return 'installing may preserve this file and stage package content as <path>.agent-config.new rather than overwriting it; the install run says which';
+    }
+    return 'back up this file — installing writes the planned content over it';
+}
 /** Probe 4 — host-detection sanity: report what the target tree looks like. */
 export function checkHostDetection(inputs) {
     const presence = detectToolPresence(inputs.root);