@event4u/agent-config 16.5.0 → 17.0.0

package/src/install/conflict.ts

@@ -2,7 +2,7 @@
  * Conflict resolution — Phase A5 (simplified, three modes).
  *
  * Three decisions only, replacing the legacy `prompt → write / skip /
- * abort` triple from `scripts/install.py:_resolve_file_conflict`:
+ * abort` triple from `_resolve_file_conflict` in the retired Python installer:
  *
  * - `write`   — target either does not exist OR policy authorises overwrite.
  * - `skip`    — target exists, known path, not forced: leave it alone.
@@ -18,9 +18,11 @@
 import { existsSync } from 'node:fs';
 
 import { sha256File } from './plan.js';
+import { isLedgerMigration } from './preserve.js';
 import {
     classifyOwnership,
-    recordedHashesForRoot,
+    ledgerListedPaths,
+    recordedHashesWithLedger,
     type RecordedHashes,
 } from './recordedOwnership.js';
 import type {
@@ -102,7 +104,7 @@ export type JsonArray = ReadonlyArray<JsonValue>;
 /**
  * Recursive object merge — overlay wins, nested dicts merged, arrays replaced.
  *
- * Mirrors `scripts/install.py:deep_merge`. Arrays do **not** concatenate;
+ * Mirrors `deep_merge` in the retired Python installer. Arrays do **not** concatenate;
  * Claude / Cursor / Cline hook configs rely on whole-array replacement to
  * stay idempotent across re-runs.
  *
@@ -197,7 +199,7 @@ export const CONFLICT_BATCH_THRESHOLD = 5;
  *   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`.
+ * manifest at `plan.root`, with the user-scoped ownership ledger laid over it.
  */
 export function computeConflicts(
     plan: InstallPlan,
@@ -207,7 +209,15 @@ export function computeConflicts(
     // 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 recorded = recordedOverride ?? recordedHashesWithLedger(plan.root);
+    // Read lazily and once: a pass over a tree whose ledger paths all carry
+    // digests never reaches the branch that needs this, and an unconditional
+    // read would charge every plan for an answer most of them discard.
+    let ledgerFiles: ReadonlySet<string> | null = null;
+    const ledgerLists = (p: string): boolean => {
+        ledgerFiles ??= ledgerListedPaths();
+        return ledgerFiles.has(p);
+    };
     const out: ConflictEntry[] = [];
     for (const entries of Object.values(plan.filesByTool)) {
         for (const entry of entries) {
@@ -225,7 +235,28 @@ export function computeConflicts(
             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;
+            // CANDIDACY, not the verdict, and it is computed BEFORE the
+            // equality short-circuit below rather than after. The migration
+            // branch preserves when the bytes differ from what the run WOULD
+            // write — source plus the install-time tag — while `entry.sha256`
+            // is the digest of the UNTAGGED source. The two comparisons are
+            // not the same for any tagged `.md`, which is most of the deployed
+            // tree, so a file that matches the untagged source can still be
+            // preserved by the writer. Short-circuiting first would make the
+            // preview silent about exactly those, and silence is the one
+            // answer a preview must not give about a file the install is
+            // going to keep. Only the writer can tag before hashing, so only
+            // the writer decides; this reports which entries take that path.
+            const migration =
+                ownership === 'unknown' &&
+                isLedgerMigration({
+                    exists: true,
+                    recordedSha256: recorded.get(entry.path),
+                    onDiskSha256: onDisk,
+                    force: false,
+                    ledgerListed: ledgerLists(entry.path),
+                });
+            if (onDisk === entry.sha256 && !migration) continue;
             out.push({
                 path: entry.path,
                 kind: entry.kind,
@@ -233,6 +264,7 @@ export function computeConflicts(
                 existingSha256: onDisk,
                 mergeable: isJsonTarget(entry),
                 ownership,
+                migration,
             });
         }
     }

package/src/install/conflictTracker.ts

@@ -18,6 +18,7 @@
  */
 import * as crypto from 'node:crypto';
 import * as fs from 'node:fs';
+import * as os from 'node:os';
 import * as path from 'node:path';
 
 import { mkdirp, pathExists, resolvePath, sha256OfFile } from './fsPrimitives.js';
@@ -26,11 +27,24 @@ import {
     conflictSummaryMessage,
     decideDeployWrite,
     foreignSidecarMessage,
+    isLedgerMigration,
+    migrationPreservedMessage,
     preservedFileMessage,
     sidecarPathFor,
     type DeployWriteDecision,
 } from './preserve.js';
-import { recordedHashesForRoot, type RecordedHashes } from './recordedOwnership.js';
+import { ledgerListedPaths, recordedHashesWithLedger, type RecordedHashes } from './recordedOwnership.js';
+
+/**
+ * The bytes a run would write to one target, named rather than computed.
+ *
+ * A copy carries the package file plus its install-time tag; a generated
+ * marker carries its own content. The tracker turns either into a digest, and
+ * only when the migration branch needs one.
+ */
+export type WouldWrite =
+    | { readonly from: string; readonly packageRoot: string | null }
+    | { readonly content: string };
 
 /** The installer-owned reporting surface the tracker borrows. */
 export interface ConflictTrackerHost {
@@ -67,7 +81,23 @@ export interface ConflictTrackerHost {
 export interface ConflictState {
     root: string | null;
     recorded: RecordedHashes | null;
+    /**
+     * Paths the ownership ledger lists, read lazily and cached for the run.
+     *
+     * Same discipline as `recorded`, for the same reason: the ledger is
+     * rewritten at the end of the install, so re-reading it mid-run would
+     * compare a file against a listing this very run had just produced.
+     */
+    ledgerFiles: ReadonlySet<string> | null;
     preserved: string[];
+    /**
+     * Targets this run preserved on the migration branch.
+     *
+     * The report line differs there — the run cannot say the file was edited,
+     * only that it cannot tell — and the writer learns which is which from
+     * `resolve`, not from re-deriving the classification at report time.
+     */
+    migrated: Set<string>;
     /**
      * Sidecar path → the digest of the package content staged there this run.
      *
@@ -85,8 +115,17 @@ export interface ConflictTracker {
     readonly conflictState: ConflictState;
     /** Reset the tracker and point it at the tree whose manifest records ownership. */
     begin(root: string | null): void;
-    /** Decide what the writer does with one deploy target. */
-    resolve(target: string, force: boolean): DeployWriteDecision;
+    /**
+     * Decide what the writer does with one deploy target.
+     *
+     * `would` is required rather than optional: a call site that cannot say
+     * what it would write cannot be classified on the migration branch, and an
+     * optional argument would let a new one skip that branch silently instead
+     * of having to decide.
+     */
+    resolve(target: string, force: boolean, would: WouldWrite): DeployWriteDecision;
+    /** The digest recorded before this run for `target` — what decided a preservation. */
+    recordedDigest(target: string): string | null | undefined;
     /** Stage package content beside a preserved target, then record and report it. */
     preserve(target: string, source: string, packageRoot: string | null): void;
     /** The same, for a managed file the installer generates rather than copies. */
@@ -108,7 +147,9 @@ export function createConflictTracker(host: ConflictTrackerHost): ConflictTracke
     const conflictState: ConflictState = {
         root: null,
         recorded: null,
+        ledgerFiles: null,
         preserved: [],
+        migrated: new Set(),
         staged: new Map(),
     };
 
@@ -129,13 +170,68 @@ export function createConflictTracker(host: ConflictTrackerHost): ConflictTracke
      */
     function recordedHashFor(target: string): string | null | undefined {
         if (conflictState.root === null) return undefined;
-        conflictState.recorded ??= recordedHashesForRoot(conflictState.root);
+        conflictState.recorded ??= recordedHashesWithLedger(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);
     }
 
+    /**
+     * Does the ownership ledger list this path, under either spelling?
+     *
+     * Both keys are tried for the reason `recordedHashFor` documents: on macOS
+     * the temp and home trees sit behind a realpath symlink that rewrites a
+     * `/var` prefix onto its private twin, so a single spelling misses every
+     * entry on the platform this is developed on.
+     */
+    function ledgerLists(target: string): boolean {
+        conflictState.ledgerFiles ??= ledgerListedPaths();
+        const files = conflictState.ledgerFiles;
+        return files.has(path.resolve(target)) || files.has(resolvePath(target));
+    }
+
+    /**
+     * The digest of the bytes this run would write to `target`.
+     *
+     * Built into a temp file rather than hashed off the package source,
+     * because a deployed file is the package bytes PLUS the install-time tag
+     * and the two differ — comparing against the untagged source would call
+     * every up-to-date file divergent. The temp name carries the TARGET's
+     * extension because `tagDeployed` keys on it, the same constraint
+     * `stageInto` works around.
+     *
+     * `null` on any failure, which preserves: this is consulted only where
+     * nothing can be proven, and failing toward the recoverable direction is
+     * the whole point of the branch that calls it.
+     */
+    function wouldWriteDigest(target: string, would: WouldWrite): string | null {
+        // Under the OS temp dir, never beside the target: a host rule directory
+        // loads every `.md` in it, and a process killed before the unlink below
+        // would leave this file there to be loaded as a rule.
+        const tmp = path.join(
+            os.tmpdir(),
+            `agent-config-would.${process.pid}.${crypto.randomBytes(6).toString('hex')}${path.extname(target)}`,
+        );
+        try {
+            if ('content' in would) {
+                fs.writeFileSync(tmp, would.content, 'utf-8');
+            } else {
+                fs.copyFileSync(would.from, tmp);
+                host.tagDeployed(tmp, would.from, would.packageRoot);
+            }
+            return sha256OfFile(tmp);
+        } catch {
+            return null;
+        } finally {
+            try {
+                fs.unlinkSync(tmp);
+            } catch {
+                /* swallow — best-effort cleanup of our own temp file */
+            }
+        }
+    }
+
     /**
      * Produce the bytes this run would have written, then reconcile them with
      * whatever already sits at the sidecar path.
@@ -219,16 +315,24 @@ export function createConflictTracker(host: ConflictTrackerHost): ConflictTracke
         // NDJSON frame and anything downstream reading either.
         if (conflictState.preserved.includes(target)) return;
         conflictState.preserved.push(target);
-        host.warn(preservedFileMessage(target, sidecar));
+        host.warn(
+            conflictState.migrated.has(path.resolve(target))
+                ? migrationPreservedMessage(target, sidecar)
+                : preservedFileMessage(target, sidecar),
+        );
     }
 
     return {
         conflictState,
 
+        recordedDigest: recordedHashFor,
+
         begin(root: string | null): void {
             conflictState.root = root;
             conflictState.recorded = null;
+            conflictState.ledgerFiles = null;
             conflictState.preserved = [];
+            conflictState.migrated = new Set();
             conflictState.staged = new Map();
         },
 
@@ -238,14 +342,28 @@ export function createConflictTracker(host: ConflictTrackerHost): ConflictTracke
          * so a file edited between planning and writing is still classified
          * from the bytes that are actually about to be destroyed.
          */
-        resolve(target: string, force: boolean): DeployWriteDecision {
+        resolve(target: string, force: boolean, would: WouldWrite): DeployWriteDecision {
             const exists = pathExists(target);
-            return decideDeployWrite({
+            const base = {
                 exists,
                 recordedSha256: exists ? recordedHashFor(target) : undefined,
                 onDiskSha256: exists ? sha256OfFile(target) : null,
                 force,
-            });
+                ledgerListed: exists && ledgerLists(target),
+            };
+            // The packaged digest costs a temp write and a tag, so it is
+            // computed only for the targets that can consume it. On a tree
+            // where every ledger-listed path carries a digest — which is every
+            // tree the ledger itself has written — this is false throughout
+            // and the run pays nothing.
+            const migrating = isLedgerMigration(base);
+            const decision = decideDeployWrite(
+                migrating ? { ...base, packagedSha256: wouldWriteDigest(target, would) } : base,
+            );
+            if (decision === 'preserve' && migrating) {
+                conflictState.migrated.add(path.resolve(target));
+            }
+            return decision;
         },
 
         /**

package/src/install/detect.ts

@@ -1,5 +1,5 @@
 /**
- * Detection layer — Phase A2 port of `scripts/install.py:detect_*`.
+ * Detection layer — Phase A2 port of ``detect_` in the retired Python installer*`.
  *
  * Pure functions only: read once, return a plan. No side effects in
  * the detection itself — atomic writes and conflict resolution happen
@@ -98,7 +98,7 @@ export interface ScopeDecision {
 /**
  * Multi-signal scope detection (ADR-007 D2 / Phase 1.3).
  *
- * 1:1 port of `scripts/install.py:detect_scope`. Pure — no side effects.
+ * 1:1 port of `detect_scope` in the retired Python installer. Pure — no side effects.
  */
 export function detectScope(cwd: string): ScopeDecision {
     if (existsSync(join(cwd, SETTINGS_FILE))) {
@@ -241,7 +241,7 @@ export function discoverPacks(workspaceRoot: string): readonly string[] {
 /**
  * Locate the agent-config package root from a project root.
  *
- * 1:1 port of `scripts/install.py:detect_package_root` — prefers an
+ * 1:1 port of `detect_package_root` in the retired Python installer — prefers an
  * npm-installed copy under `node_modules/@event4u/agent-config/`,
  * falls back to the project root itself for in-package development
  * (presence of `src/config/profiles/minimal.ini` is the development-mode

package/src/install/hostPermissionsAdapter.ts

@@ -0,0 +1,136 @@
+/**
+ * How each host spells a permission deny rule, and where that spelling was
+ * read from.
+ *
+ * `road-to-a-project-contract-written-down` step 2.1 named
+ * `src/scripts/hooks/host_lowering.yaml` as the home for this pin. It is not
+ * the home, and the departure is recorded in the roadmap's Decisions table
+ * rather than taken quietly. The measurement that forced it:
+ *
+ *   - That table is keyed `(host, surface, slot)` and its own header states
+ *     its subject — "how each host lowers a dispatcher verdict into its own
+ *     hook contract". A permission deny rule has no slot and no verdict; it is
+ *     consulted BEFORE a tool runs, not after a hook dispatches.
+ *   - `_structure()` there reads only named hook keys, so a `permissions:`
+ *     block added to the YAML would be dropped from the typed table and read
+ *     by nobody, while still moving the compiled body's fingerprint.
+ *
+ * Put to the AI council on 2026-10-13 (anthropic + openai, 2/2 present, both
+ * seats converging): place the fact here, keep the classifier host-neutral,
+ * and let a provenance gate stand in for the plumbing ratification the hook
+ * table would have carried.
+ *
+ * ```
+ * THE CLASSIFIER DECIDES WHAT A BULLET MEANS. THIS DECIDES HOW A HOST SPELLS IT.
+ * A HOST ABSENT FROM THE TABLE IS A HOST NOBODY ESTABLISHED — NEVER A REFUSAL.
+ * ```
+ */
+
+import type { NoGoClassification } from './noGoRules.js';
+
+/**
+ * Everything a later reader needs to re-check one host's spelling.
+ *
+ * `examples` are VERBATIM quotes from the page at `docs_url`, as read on
+ * `docs_at`. They are the grammar the renderer is checked against by
+ * `check_permission_deny_syntax`; they are not independent of the renderer in
+ * the way a live probe would be, and that limit is stated here rather than
+ * implied — see that gate's own honesty note.
+ */
+export interface HostPermissionSyntax {
+    readonly host: string;
+    readonly docs_url: string;
+    /** The day the page was read, ISO. */
+    readonly docs_at: string;
+    /**
+     * Review-by date for this row. No host this package supports publishes a
+     * documentation cadence, so this is a date THIS PACKAGE chose — `docs_at`
+     * plus a year — and never a vendor commitment. The same convention
+     * `host_lowering.yaml` states for its own `expires`.
+     */
+    readonly expires: string;
+    /** Where a row goes in the settings file, as a dotted key path. */
+    readonly deny_key: string;
+    /** Verbatim rule spellings from the page. */
+    readonly examples: readonly string[];
+}
+
+export const HOST_PERMISSION_SYNTAX: Readonly<Record<string, HostPermissionSyntax>> = {
+    claude: {
+        host: 'claude',
+        docs_url: 'https://code.claude.com/docs/en/permissions.md',
+        docs_at: '2026-10-13',
+        expires: '2027-10-13',
+        deny_key: 'permissions.deny',
+        examples: [
+            // "Claude Code checks file permissions against `Edit(path)` and
+            // `Read(path)` rules only. … Use `Edit(docs/**)` in place of
+            // `Write(docs/**)`, `NotebookEdit(docs/**)`, or `MultiEdit(docs/**)`."
+            'Edit(docs/**)',
+            // "To block Claude's file tools from reading a file or directory,
+            // add a `Read` deny rule for its path, such as `Read(./.env)` or
+            // `Read(./secrets/**)`."
+            'Read(./secrets/**)',
+            // "`Bash(npm run build)` | Matches the exact command `npm run build`"
+            'Bash(npm run build)',
+            // "A `*` at the end, with a space before it, also matches the bare
+            // command. `Bash(ls *)` matches `ls`, and `Bash(git log *)` matches
+            // `git log`. That holds only when the trailing `*` is the rule's
+            // only wildcard: `Bash(* --help *)` matches `npm --help x` but not
+            // `npm --help`."
+            'Bash(ls *)',
+        ],
+    },
+};
+
+/** The row for `host`, or `null` when nothing is established for it. */
+export function syntaxFor(host: string): HostPermissionSyntax | null {
+    return HOST_PERMISSION_SYNTAX[host] ?? null;
+}
+
+/**
+ * The path spec a rule carries.
+ *
+ * A trailing `/` means the directory's contents, which the host spells `/**`.
+ * Everything else is passed through as the consumer wrote it: "a deny or ask
+ * rule whose path isn't usable as a gitignore pattern still guards that exact
+ * path", and widening `src/generated` to `src/generated/**` on a guess would be
+ * the same guess the classifier refuses.
+ */
+function pathSpec(token: string): string {
+    return token.endsWith('/') ? `${token}**` : token;
+}
+
+/**
+ * The deny rows `c` becomes on `host`. Empty for prose, and empty for a host
+ * with no established row.
+ *
+ * A COMMAND BECOMES TWO ROWS, and the reason is NOT the one an earlier version
+ * of this comment gave. It claimed `Bash(x *)` never matches the bare `x`; the
+ * page says the opposite one line above the sentence that was read — "A `*` at
+ * the end, with a space before it, also matches the bare command." A review
+ * caught it, and it had reached the roadmap as that step's "one non-obvious
+ * finding", so the correction is recorded rather than quietly applied.
+ *
+ * The real reason is the page's own qualifier: the bare-command match "holds
+ * only when the trailing `*` is the rule's only wildcard". A consumer token
+ * carrying its own `*` breaks that, and the exact row is what still guards the
+ * plain command then. One row would be right for most tokens and silently
+ * wrong for those — Risk 3 in the register, "a rule in the wrong syntax is
+ * accepted by the file and enforced by nothing".
+ *
+ * A READ no-go renders `Read(...)` AND `Edit(...)`. The `Read` deny covers the
+ * Edit and Write tools on the same path, but the page names the exception:
+ * "NotebookEdit isn't covered, so add an `Edit` deny rule for paths no tool may
+ * change." A read no-go over a directory holding notebooks would otherwise
+ * leave NotebookEdit able to change it.
+ */
+export function denyRulesFor(host: string, c: NoGoClassification): readonly string[] {
+    if (syntaxFor(host) === null || c.action === null || c.token === null) return [];
+    if (c.kind === 'command') return [`Bash(${c.token})`, `Bash(${c.token} *)`];
+    if (c.kind === 'path') {
+        const spec = pathSpec(c.token);
+        return c.action === 'read' ? [`Read(${spec})`, `Edit(${spec})`] : [`Edit(${spec})`];
+    }
+    return [];
+}

package/src/install/installThinLayer.ts

@@ -104,6 +104,11 @@ export interface ThinInstalledLayerOptions {
     readonly packageRoot: string;
     /** Absolute paths the conflict tracker preserved; never rewritten here. */
     readonly preserved?: ReadonlySet<string>;
+    /**
+     * The root stub `Body:` pointers are built on, when it is not the package:
+     * the staged runtime, which outlives a cleared package-manager cache.
+     */
+    readonly bodyLinkRoot?: string | null;
 }
 
 /**
@@ -115,7 +120,7 @@ export interface ThinInstalledLayerOptions {
 export function thinInstalledRuleLayer(opts: ThinInstalledLayerOptions): ThinInstalledLayerResult {
     const packageRoot = path.resolve(opts.packageRoot);
     const bodySourceDir = path.join(packageRoot, 'dist', 'agent-src', 'rules');
-    const bodyLinkPrefix = absoluteBodyLinkPrefix(packageRoot);
+    const bodyLinkPrefix = absoluteBodyLinkPrefix(opts.bodyLinkRoot ?? packageRoot);
     const preserved = opts.preserved ?? new Set<string>();
 
     // Scope is `null` on purpose. The copy already applied the install's rule

package/src/install/manifestFiles.ts

@@ -310,3 +310,27 @@ export function preservedIndex(
     }
     return out;
 }
+
+/**
+ * Clear `files[]` on the global-scope entries of `deployed`, in place.
+ *
+ * A consumer commits this lock (`README.md` § Team reproducibility), and a
+ * global entry's files are `$HOME`-rooted absolute paths of whoever installed.
+ * The user-scoped ledger (`ownershipLedger.ts`) holds global ownership, and
+ * `sync` replays a global entry from `name`, `scope` and `bridge_marker` alone,
+ * so the entry stays and its files go. An empty list is written as no `files`
+ * key at all, which is also how a lock committed earlier loses its paths.
+ *
+ * Only for tools whose global deploy ran this install: that run just recorded
+ * their digests in the ledger. A lock-only digest of any other tool is the one
+ * record of a pre-ledger edit, and dropping it first would re-arm the overwrite.
+ */
+export function dropGlobalScopeFiles(
+    entries: ManifestFileEntry[],
+    deployed: ReadonlySet<string>,
+): ManifestFileEntry[] {
+    for (const entry of entries) {
+        if (entry['scope'] === 'global' && deployed.has(String(entry['name']))) entry['files'] = [];
+    }
+    return entries;
+}