@event4u/agent-config 16.0.0 → 16.1.0

package/dist/install/claudeRuleRewrite.js

@@ -109,8 +109,8 @@ export function _withPreservedKeys(rendered, original) {
  * extraction and never up through a baseline raise. So the caller gets one call
  * and a list of strings.
  */
-export function rewriteAndReport(rulesDir, quiet, info, warn, wrappers) {
-    const result = rewriteClaudeRules(rulesDir);
+export function rewriteAndReport(rulesDir, quiet, info, warn, wrappers, preserved = new Set()) {
+    const result = rewriteClaudeRules(rulesDir, preserved);
     // The flat-command wrapper report rides along rather than sitting at the
     // call site: `install.ts` is thousands of lines past
     // `check_source_size_budget`'s ceiling, and this module is the one place
@@ -188,9 +188,18 @@ export function renderClaudeRule(sourceText) {
  * detected and skipped rather than re-run — re-running is the silent-widening
  * failure this module exists to fix, applied to its own output.
  *
+ * `preserved` names destinations the conflict tracker kept because the user had
+ * edited them. They are skipped outright. This pass re-renders frontmatter and
+ * re-adds only `package:` / `source_path:`, so any key the user added is
+ * dropped — and every `always` rule and every mixed-trigger rule deploys
+ * without a `paths:` block, so the already-host-form guard above lets them
+ * straight through. Without this set, the same run that reported a file
+ * preserved went on to rewrite it, and the edit survived in the body while
+ * disappearing from the frontmatter.
+ *
  * Returns counts rather than printing. The caller owns the reporting surface.
  */
-export function rewriteClaudeRules(rulesDir) {
+export function rewriteClaudeRules(rulesDir, preserved = new Set()) {
     const result = { rewritten: 0, scoped: [], dropped: [], failed: [] };
     let entries;
     try {
@@ -201,6 +210,8 @@ export function rewriteClaudeRules(rulesDir) {
     }
     for (const name of entries.filter((n) => n.endsWith('.md')).sort()) {
         const full = path.join(rulesDir, name);
+        if (preserved.has(path.resolve(full)))
+            continue;
         let stat;
         try {
             stat = fs.lstatSync(full);

package/dist/install/conflict.js

@@ -16,13 +16,14 @@
  */
 import { existsSync } from 'node:fs';
 import { sha256File } from './plan.js';
+import { classifyOwnership, recordedHashesForRoot, } from './recordedOwnership.js';
 /**
  * Decide what to do with a single planned target.
  *
  * Decision matrix (mirrors the Python legacy with the 3-option prompt
  * collapsed into `surface`):
  *
- * | Exists? | Idempotent? | Known? | Force? | → Outcome  |
+ * | Exists? | Idempotent? | Known? | Force? | → Outcome  |  code-comment-allow report-comment -- pre-existing decision matrix; this file entered the gate's changed-file scope for an unrelated edit
  * |---------|-------------|--------|--------|------------|
  * | no      | —           | —      | —      | `write`    |
  * | yes     | yes         | —      | —      | `skip`     |
@@ -31,9 +32,23 @@ import { sha256File } from './plan.js';
  * | yes     | no          | no     | yes    | `write`    |
  * | yes     | no          | no     | no     | `surface`  |
  *
- * Headless callers (B1 CLI) collapse `surface` to `skip` automatically
- * because there is no UI to defer to; the apply layer records the entry
- * under {@link ApplyResult.conflicts} so the wizard can pick it up next.
+ * Deliberately NOT extended with the recorded-digest ownership that
+ * {@link computeConflicts} consumes. This function has no caller in `src/` —
+ * the only references are its own definition and the `{@link}` above — so an
+ * `ownership` input would be a parameter nobody supplies, on a decision
+ * nobody reads. The ownership split lives where it is live: in the report.
+ *
+ * What this resolver decides is in any case NOT what the installer does. The
+ * single writer is `src/scripts/install.ts`, whose conflict resolver
+ * (`src/install/conflictTracker.ts`) reads nothing from this module; `skip`
+ * here means "the planner would not touch it", never "your edit is safe".
+ *
+ * Since the owner ruling of 2026-09-21 that writer no longer overwrites
+ * unconditionally — a managed file diverging from its recorded digest is
+ * preserved and the package content staged beside it (`src/install/preserve.ts`).
+ * The two still reach that answer independently: this module decides from a
+ * plan, the writer re-hashes the destination at the moment it is about to
+ * mutate it. A `skip` here remains a statement about the plan.
  */
 export function resolveFileConflict(inputs) {
     const { targetPath, idempotent, exists, policy } = inputs;
@@ -121,14 +136,38 @@ export const CONFLICT_BATCH_THRESHOLD = 5;
  *
  * Pure-ish — reads from the filesystem only to compute idempotency
  * (`existsSync` + `sha256File`). Skips bridges (`sha256 === null`) since
- * bridge writers own a separate idempotency model. Skips entries whose
- * `path` is in `policy.knownPaths`, and skips entries that are
- * byte-equal to the planned content. Returns an empty array when
+ * bridge writers own a separate idempotency model, and skips entries that
+ * are byte-equal to the planned content. Returns an empty array when
  * `policy.force` is true — overwrite mode silences the screen.
+ *
+ * Ownership (Phase 5.1) replaces the blanket `policy.knownPaths` skip:
+ *
+ * - `recorded-unchanged` — ours and untouched. Skipped, and now for a reason
+ *   that survives a package upgrade: the planned bytes differing from the
+ *   recorded bytes is an upgrade, not a collision. This is a REDUCTION in
+ *   what a manifest-carrying tree reports — `cmd_preflight` builds an empty
+ *   `knownPaths`, so every such file used to be a finding — and it is the
+ *   intended direction: a routine upgrade is not a conflict.
+ * - `recorded-modified`  — ours and edited since. **Reported**, where before
+ *   it was silently dropped whenever the path sat in `knownPaths`. Reported
+ *   is all it is: the installer does not consult this matrix, so being named
+ *   here is not protection from the next deploy.
+ * - `unknown`            — no digest recorded (no manifest, an unreadable
+ *   one, or a bridge entry). Falls back to `policy.knownPaths`, so a tree
+ *   with no manifest reports exactly what it reported before. A tree WITH a
+ *   manifest reports differently in both directions, by design: it gains the
+ *   modified rows above and loses the unchanged ones below.
+ *
+ * `recorded` is injectable for tests; by default it is read from the
+ * manifest at `plan.root`.
  */
-export function computeConflicts(plan) {
+export function computeConflicts(plan, recordedOverride) {
+    // Force returns before the manifest is read. As a default parameter the
+    // map was built at call entry and discarded on the next line, so every
+    // force-mode plan paid a read and a YAML parse for nothing.
     if (plan.policy.force)
         return [];
+    const recorded = recordedOverride ?? recordedHashesForRoot(plan.root);
     const out = [];
     for (const entries of Object.values(plan.filesByTool)) {
         for (const entry of entries) {
@@ -138,9 +177,19 @@ export function computeConflicts(plan) {
                 continue;
             if (!existsSync(entry.path))
                 continue;
-            if (plan.policy.knownPaths.has(entry.path))
-                continue;
+            // The on-disk digest is computed BEFORE the ownership decision so
+            // that decision can consume it. Behaviour-identical to computing it
+            // after the `knownPaths` test — the remaining guards are unchanged.
+            // The added cost is one digest per EXISTING path in
+            // `policy.knownPaths`, the set the removed short-circuit used to
+            // skip; everything else was already being hashed. That set is empty
+            // for `cmd_preflight` and caller-supplied for the plan route.
             const onDisk = sha256File(entry.path);
+            const ownership = classifyOwnership(recorded.get(entry.path), onDisk);
+            if (ownership === 'recorded-unchanged')
+                continue;
+            if (ownership === 'unknown' && plan.policy.knownPaths.has(entry.path))
+                continue;
             if (onDisk === entry.sha256)
                 continue;
             out.push({
@@ -149,6 +198,7 @@ export function computeConflicts(plan) {
                 plannedSha256: entry.sha256,
                 existingSha256: onDisk,
                 mergeable: isJsonTarget(entry),
+                ownership,
             });
         }
     }

package/dist/install/conflictTracker.js

@@ -0,0 +1,218 @@
+/**
+ * Per-run conflict tracking for `agent-config init` — the stateful half of the
+ * owner ruling of 2026-09-21 (road-to-a-conformance-check-that-can-fail
+ * Phase 5.1). The decision itself is pure and lives in `./preserve.ts`; this
+ * module holds the per-run state that decision needs, stages the sidecar, and
+ * folds the result into the run's exit code.
+ *
+ * It sits beside the decision rather than inside `src/scripts/install.ts`
+ * because that file is the largest source this package ships and
+ * `check_source_size_budget` ratchets exactly that number. A feature's state
+ * machine is paid for here, where it is also the coherent unit: everything in
+ * this file is about one question — may the writer replace this managed file,
+ * and what does it owe the operator when it may not.
+ *
+ * The installer's reporting surface (`warn`, `fail`, the transaction log, the
+ * NDJSON progress stream) is injected rather than imported: importing it would
+ * be a cycle, and re-implementing it would give one install run two voices.
+ */
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { mkdirp, pathExists, resolvePath, sha256OfFile } from './fsPrimitives.js';
+import { EXIT_COMPLETED_WITH_CONFLICTS, conflictSummaryMessage, decideDeployWrite, foreignSidecarMessage, preservedFileMessage, sidecarPathFor, } from './preserve.js';
+import { recordedHashesForRoot } from './recordedOwnership.js';
+/**
+ * Build a tracker bound to one installer's reporting surface.
+ *
+ * A factory rather than module-level state so the reporting surface is injected
+ * rather than imported. It is NOT what keeps two installs in one process apart:
+ * `src/scripts/install.ts` calls this once at module scope, so both runs share
+ * the instance and therefore the `preserved` list. `begin()` is what scopes the
+ * state to a run, and it is the only thing that does.
+ */
+export function createConflictTracker(host) {
+    const conflictState = {
+        root: null,
+        recorded: null,
+        preserved: [],
+        staged: new Map(),
+    };
+    /**
+     * Recorded digest for `target`, or `undefined` when this tree cannot say.
+     *
+     * Two keys are tried, and the plain `path.resolve` one comes FIRST because
+     * it is the form that actually matches: `_file_entry` records the path
+     * verbatim as the copy loop built it, and `readRecordedHashes` re-resolves
+     * with `path.resolve` and no realpath. Looking up only the realpath would
+     * miss every entry on macOS, where the temp and home trees sit behind the
+     * realpath symlink that rewrites a `/var` prefix onto its private twin —
+     * the feature would have been inert on the platform it was developed on.
+     * (Spelled out rather than quoted: `check_bundle_path_leakage` scans the
+     * tracked bundles this file is compiled into, and the literal form is a
+     * build-machine path leak there.) The realpath is kept as a second key so
+     * a manifest written through a symlinked deploy root still resolves.
+     */
+    function recordedHashFor(target) {
+        if (conflictState.root === null)
+            return undefined;
+        conflictState.recorded ??= recordedHashesForRoot(conflictState.root);
+        const plain = path.resolve(target);
+        if (conflictState.recorded.has(plain))
+            return conflictState.recorded.get(plain);
+        const real = resolvePath(target);
+        return real === plain ? undefined : conflictState.recorded.get(real);
+    }
+    /**
+     * Produce the bytes this run would have written, then reconcile them with
+     * whatever already sits at the sidecar path.
+     *
+     * The candidate is built into a temp file FIRST so the comparison is against
+     * the bytes that would actually be staged rather than against the raw
+     * package source — those differ, because a deployed file is the package
+     * bytes plus the install-time `package:` tag, and comparing the untagged
+     * source would call every already-staged sidecar stale and rewrite it on
+     * every run.
+     *
+     * The temp name ends in the TARGET's extension because `_inject_package_tag`
+     * keys on it: a sidecar is `<name>.md.agent-config.new`, whose extension is
+     * `.new`, so tagging it in place would silently do nothing.
+     */
+    function stageInto(target, sidecar, produce) {
+        mkdirp(path.dirname(sidecar));
+        const tmp = path.join(path.dirname(sidecar), `.${path.basename(sidecar)}.${process.pid}.${crypto.randomBytes(6).toString('hex')}${path.extname(target)}`);
+        const discard = () => {
+            try {
+                fs.unlinkSync(tmp);
+            }
+            catch {
+                /* swallow — best-effort cleanup of our own temp file */
+            }
+        };
+        let candidate;
+        try {
+            produce(tmp);
+            candidate = sha256OfFile(tmp);
+        }
+        catch (exc) {
+            discard();
+            host.fail(`Could not stage package content for ${target} at ${sidecar}: ${String(exc)}. ` +
+                'Nothing was written; the managed file is unchanged.');
+        }
+        if (pathExists(sidecar)) {
+            const onDisk = sha256OfFile(sidecar);
+            // Three outcomes, and only the third is a refusal. Identical bytes:
+            // already staged, so the file is left alone. Bytes this tree
+            // RECORDED staging: an earlier run staged them against an older
+            // package version and the user has not merged them yet — the
+            // staging workflow behaving as designed, so the stale copy is
+            // refreshed. Anything else is unattributable and the run stops.
+            //
+            // Ownership is decided by the recorded digest, never by whether the
+            // bytes match the CURRENT package: that test called every unmerged
+            // sidecar foreign the moment a new version shipped, and aborted the
+            // whole install saying it could not show it wrote a file it had
+            // written one version earlier.
+            if (onDisk !== null && onDisk === candidate) {
+                discard();
+                conflictState.staged.set(sidecar, onDisk);
+                return;
+            }
+            if (onDisk === null || onDisk !== recordedHashFor(sidecar)) {
+                discard();
+                host.fail(foreignSidecarMessage(target, sidecar));
+            }
+        }
+        try {
+            fs.renameSync(tmp, sidecar);
+        }
+        catch (exc) {
+            discard();
+            host.fail(`Could not stage package content for ${target} at ${sidecar}: ${String(exc)}. ` +
+                'Nothing was written; the managed file is unchanged.');
+        }
+        conflictState.staged.set(sidecar, candidate);
+        host.logWrite(sidecar);
+    }
+    /** Record and report one preserved target, once per destination. */
+    function record(target, sidecar) {
+        // Deduped: two plan entries can resolve to one destination, and a count
+        // is a promise about FILES. Double-counting inflates the summary, the
+        // NDJSON frame and anything downstream reading either.
+        if (conflictState.preserved.includes(target))
+            return;
+        conflictState.preserved.push(target);
+        host.warn(preservedFileMessage(target, sidecar));
+    }
+    return {
+        conflictState,
+        begin(root) {
+            conflictState.root = root;
+            conflictState.recorded = null;
+            conflictState.preserved = [];
+            conflictState.staged = new Map();
+        },
+        /**
+         * The on-disk digest is computed HERE rather than carried from the
+         * plan: this runs immediately before the caller copies over `target`,
+         * so a file edited between planning and writing is still classified
+         * from the bytes that are actually about to be destroyed.
+         */
+        resolve(target, force) {
+            const exists = pathExists(target);
+            return decideDeployWrite({
+                exists,
+                recordedSha256: exists ? recordedHashFor(target) : undefined,
+                onDiskSha256: exists ? sha256OfFile(target) : null,
+                force,
+            });
+        },
+        /**
+         * Stage the package content beside a preserved target.
+         *
+         * The staged bytes are what the installer WOULD have written — the
+         * package file plus its install-time tag — so merging the sidecar by
+         * hand yields a file that matches the digest this run records and still
+         * carries the ownership evidence the reaper reads.
+         */
+        preserve(target, source, packageRoot) {
+            const sidecar = sidecarPathFor(target);
+            stageInto(target, sidecar, (tmp) => {
+                fs.copyFileSync(source, tmp);
+                host.tagDeployed(tmp, source, packageRoot);
+            });
+            record(target, sidecar);
+        },
+        /**
+         * The same, for a managed file the installer GENERATES rather than
+         * copies (the Claude Desktop marker).
+         *
+         * Those writers are recorded in the manifest with a digest, so they are
+         * in the class the ruling covers, and one of them wrote unconditionally
+         * — ignoring even `--force` — because the tracker was wired only into
+         * the copy loop.
+         */
+        preserveContent(target, content) {
+            const sidecar = sidecarPathFor(target);
+            stageInto(target, sidecar, (tmp) => fs.writeFileSync(tmp, content, 'utf-8'));
+            record(target, sidecar);
+        },
+        /**
+         * Runs before the installer's terminal NDJSON frame so that frame can
+         * carry the count. A failing run keeps its own code — a conflict never
+         * masks a failure.
+         */
+        finalizeRc(rc) {
+            const count = conflictState.preserved.length;
+            if (count === 0)
+                return rc;
+            host.emitProgress({ type: 'conflicts', count, paths: [...conflictState.preserved] });
+            // `warn` writes to stderr and is deliberately NOT gated on QUIET:
+            // the wizard runs the installer with QUIET set, and a preserved
+            // edit is the one thing a silent run must still say.
+            host.warn(conflictSummaryMessage(count));
+            return rc === 0 ? EXIT_COMPLETED_WITH_CONFLICTS : rc;
+        },
+    };
+}
+//# sourceMappingURL=conflictTracker.js.map

package/dist/install/fsPrimitives.js

@@ -0,0 +1,54 @@
+/**
+ * Filesystem primitives shared by the installer and its conflict tracker.
+ *
+ * These four moved out of `src/scripts/install.ts` when `conflictTracker.ts`
+ * needed them. The tracker cannot import the installer — that is a cycle — and
+ * re-declaring `pathExists` / `sha256OfFile` beside it would put two
+ * definitions of "does this file exist" and "what are its bytes" on the same
+ * install path, which is the one place they have to agree. Passing them in as
+ * callbacks was the other option and it buys nothing: they are pure, total
+ * functions of their arguments carrying no installer state, so a shared module
+ * is both the smaller wiring and the more honest unit.
+ *
+ * The selection rule is exactly that — shared with `conflictTracker.ts`. The
+ * installer's other private helpers (`expanduser`, `isDir`, `readText`, …) stay
+ * where they are; moving them too would be a restructure this change does not
+ * need and cannot justify.
+ */
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+/** `Path.resolve()` — absolute, symlink-resolved where possible. */
+export function resolvePath(p) {
+    try {
+        return fs.realpathSync(path.resolve(p));
+    }
+    catch {
+        return path.resolve(p);
+    }
+}
+export function pathExists(p) {
+    try {
+        fs.statSync(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** `path.mkdir(parents=True, exist_ok=True)`. */
+export function mkdirp(p) {
+    fs.mkdirSync(p, { recursive: true });
+}
+/** `hashlib.sha256(data).hexdigest()` of a file's bytes, or null when unreadable. */
+export function sha256OfFile(p) {
+    let data;
+    try {
+        data = fs.readFileSync(p);
+    }
+    catch {
+        return null;
+    }
+    return crypto.createHash('sha256').update(data).digest('hex');
+}
+//# sourceMappingURL=fsPrimitives.js.map