@event4u/agent-config 16.0.0 → 16.2.0

package/src/scripts/install.ts

@@ -20,13 +20,17 @@
  * Usage:
  *   tsx src/scripts/install.ts                     # defaults: rule_loading_tier=balanced
  *   tsx src/scripts/install.ts --profile=minimal   # set rule_loading_tier=minimal (kernel only)
- *   tsx src/scripts/install.ts --force             # accepted (no-op): installs always overwrite
+ *   tsx src/scripts/install.ts --force             # replace managed files the user has edited
  *   tsx src/scripts/install.ts --skip-bridges      # only create .agent-settings.yml
  *   tsx src/scripts/install.ts --project <dir>     # override project root
  *
- * Idempotent — safe to run multiple times. A run always refreshes every
- * deployed file with the current package content; user configuration
- * (.agent-settings.yml) is merged by the settings layer, never clobbered.
+ * Idempotent — safe to run multiple times. A run refreshes every deployed file
+ * with the current package content, EXCEPT a managed file whose bytes diverge
+ * from the digest the install manifest recorded: that one is preserved, package
+ * content is staged beside it as `<path>.agent-config.new`, and the run exits 3
+ * rather than 0 so the staleness is stated, not silent; `--force` replaces it
+ * instead. Contract + state machine: `install/preserve.ts`, `conflictTracker.ts`.
+ * User config (.agent-settings.yml) is settings-layer merged, never clobbered.
  *
  * --- Parity notes (ADR-200) ---
  *
@@ -72,11 +76,17 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import type * as YamlModule from 'yaml';
 
 import { build_merge_entries } from './_lib/json_pointers.js';
+import { withHostEnv } from './_lib/host_env_write.js';
+import { jsonDumpsCompact, jsonDumpsIndent } from './_lib/json_python_parity.js';
 import { is_claude_builtin_name } from './_lib/claude_builtin_names.js';
 import * as installed_lock from './_lib/installed_lock.js';
 import * as mcp_bridge from './_lib/mcp_bridge.js';
 import * as mcp_consent from './_lib/mcp_consent_residual.js';
 import * as scoped_projection from './_lib/scoped_projection.js';
+import { createConflictTracker } from '../install/conflictTracker.js';
+import { mkdirp, pathExists, resolvePath, sha256OfFile } from '../install/fsPrimitives.js';
+import { filesByToolFromBridges as _files_by_tool_from_bridges, filesByToolFromDeploy as _files_by_tool_from_deploy, hydrateRecordedInventories, preservedIndex, readRecordedByTool, reconcileToolFiles, type ManifestFileEntry } from '../install/manifestFiles.js';
+import { EXIT_COMPLETED_WITH_CONFLICTS } from '../install/preserve.js';
 import * as surface_tiers from './_lib/surface_tiers.js';
 import * as global_deploy_inventory from './_lib/global_deploy_inventory.js';
 import * as rule_layer_overlap from './_lib/rule_layer_overlap.js';
@@ -113,6 +123,8 @@ import {
 } from './_lib/model_tier.js';
 import { main as cmdMigrateMain } from './_cli/cmd_migrate.js';
 import { SCOPE_DETECT_AI_DIRS, SCOPE_DETECT_MANIFESTS } from '../install/detect.js';
+import { getLogPath } from '../install/paths.js';
+import { appendTxLog } from '../install/txlog.js';
 
 // ---------------------------------------------------------------------------
 // Python-runtime parity helpers
@@ -143,15 +155,6 @@ function expanduser(p: string): string {
     return p;
 }
 
-/** `Path.resolve()` — absolute, symlink-resolved where possible. */
-function resolvePath(p: string): string {
-    try {
-        return fs.realpathSync(path.resolve(p));
-    } catch {
-        return path.resolve(p);
-    }
-}
-
 function isFile(p: string): boolean {
     try {
         return fs.statSync(p).isFile();
@@ -168,15 +171,6 @@ function isDir(p: string): boolean {
     }
 }
 
-function pathExists(p: string): boolean {
-    try {
-        fs.statSync(p);
-        return true;
-    } catch {
-        return false;
-    }
-}
-
 function isSymlink(p: string): boolean {
     try {
         return fs.lstatSync(p).isSymbolicLink();
@@ -193,11 +187,6 @@ function writeText(p: string, content: string): void {
     fs.writeFileSync(p, content, 'utf-8');
 }
 
-/** `path.mkdir(parents=True, exist_ok=True)`. */
-function mkdirp(p: string): void {
-    fs.mkdirSync(p, { recursive: true });
-}
-
 /**
  * `sorted(Path.glob(pattern))` with PyYAML/pathlib component-wise ordering.
  * We only need a non-recursive `*.glob("<pat>")`; pathlib sorts the matched
@@ -238,17 +227,6 @@ function countZips(directory: string): number {
     return n;
 }
 
-/** `hashlib.sha256(data).hexdigest()` of a file's bytes, or null when unreadable. */
-function sha256OfFile(p: string): string | null {
-    let data: Buffer;
-    try {
-        data = fs.readFileSync(p);
-    } catch {
-        return null;
-    }
-    return crypto.createHash('sha256').update(data).digest('hex');
-}
-
 /**
  * Atomic write mirroring the Python `tempfile.mkstemp(...) → os.fdopen → write
  * → os.chmod(0o644) → os.replace` pattern in `_write_consumer_bridge_marker`
@@ -299,108 +277,6 @@ function utcStamp(now?: Date): string {
     );
 }
 
-// --- JSON byte-parity (ensure_ascii=False; insertion order) ---
-
-function _jsonStrNoAscii(s: string): string {
-    // json.dumps(ensure_ascii=False): escape control chars + " + \, keep >=0x20
-    let out = '"';
-    for (const ch of s) {
-        const code = ch.codePointAt(0) as number;
-        switch (ch) {
-            case '"':
-                out += '\\"';
-                break;
-            case '\\':
-                out += '\\\\';
-                break;
-            case '\n':
-                out += '\\n';
-                break;
-            case '\r':
-                out += '\\r';
-                break;
-            case '\t':
-                out += '\\t';
-                break;
-            case '\b':
-                out += '\\b';
-                break;
-            case '\f':
-                out += '\\f';
-                break;
-            default:
-                if (code < 0x20) {
-                    out += '\\u' + code.toString(16).padStart(4, '0');
-                } else {
-                    out += ch;
-                }
-        }
-    }
-    return out + '"';
-}
-
-function _jsonScalar(value: unknown): string | null {
-    if (value === null || value === undefined) return 'null';
-    if (typeof value === 'boolean') return value ? 'true' : 'false';
-    if (typeof value === 'number') {
-        if (!Number.isFinite(value)) {
-            if (Number.isNaN(value)) return 'NaN';
-            return value > 0 ? 'Infinity' : '-Infinity';
-        }
-        // Our payloads carry only integers; render as-is.
-        return String(value);
-    }
-    if (typeof value === 'string') return _jsonStrNoAscii(value);
-    return null;
-}
-
-function _dumpIndent(value: unknown, indent: number, depth: number): string {
-    const scalar = _jsonScalar(value);
-    if (scalar !== null) return scalar;
-    const pad = ' '.repeat(indent * (depth + 1));
-    const closePad = ' '.repeat(indent * depth);
-    if (Array.isArray(value)) {
-        if (value.length === 0) return '[]';
-        const items = value.map((v) => pad + _dumpIndent(v, indent, depth + 1));
-        return `[\n${items.join(',\n')}\n${closePad}]`;
-    }
-    if (typeof value === 'object' && value !== null) {
-        const obj = value as Record<string, unknown>;
-        const keys = Object.keys(obj);
-        if (keys.length === 0) return '{}';
-        const items = keys.map(
-            (k) => `${pad}${_jsonStrNoAscii(k)}: ${_dumpIndent(obj[k], indent, depth + 1)}`,
-        );
-        return `{\n${items.join(',\n')}\n${closePad}}`;
-    }
-    return _jsonStrNoAscii(String(value));
-}
-
-/** `json.dumps(data, indent=N, ensure_ascii=False)` (sort_keys=False). */
-function jsonDumpsIndent(value: unknown, indent: number): string {
-    return _dumpIndent(value, indent, 0);
-}
-
-/** `json.dumps(obj, separators=(",", ":"))` — compact, ensure_ascii=False here. */
-function jsonDumpsCompact(value: unknown): string {
-    const scalar = _jsonScalar(value);
-    if (scalar !== null) return scalar;
-    if (Array.isArray(value)) {
-        return '[' + value.map((v) => jsonDumpsCompact(v)).join(',') + ']';
-    }
-    if (typeof value === 'object' && value !== null) {
-        const obj = value as Record<string, unknown>;
-        return (
-            '{' +
-            Object.keys(obj)
-                .map((k) => `${_jsonStrNoAscii(k)}:${jsonDumpsCompact(obj[k])}`)
-                .join(',') +
-            '}'
-        );
-    }
-    return _jsonStrNoAscii(String(value));
-}
-
 /** Lazy YAML safe_load mirroring PyYAML (version 1.1), `{}` on every error. */
 function yamlSafeLoad(text: string): unknown {
     let YAML: typeof YamlModule;
@@ -482,6 +358,11 @@ function _emit_progress_terminal(rc: number): void {
     if (!state.PROGRESS_NDJSON) return;
     if (rc === 0) {
         _emit_progress({ type: 'done' });
+    } else if (rc === EXIT_COMPLETED_WITH_CONFLICTS) {
+        // A conflict is a completion, not a failure, so the count rides on
+        // `done`, not an `error` frame. Zero conflicts never reach here, so that
+        // frame stays byte-identical to `{"type":"done"}`.
+        _emit_progress({ type: 'done', conflicts: tracker.conflictState.preserved.length });
     } else {
         _emit_progress({ type: 'error', code: 'E_INSTALL', exitCode: rc });
     }
@@ -553,10 +434,21 @@ function _is_interactive(): boolean {
     }
 }
 
-function _resolve_file_conflict(_target: string, _force_hint: boolean): string {
-    // del force_hint / del target — deploys always overwrite our own content.
-    return 'write';
-}
+/**
+ * Per-run conflict tracking; the state machine, the sidecar staging and the
+ * exit-code folding live in `src/install/conflictTracker.ts`, and only the
+ * wiring is here. Module scope, like `state` above, because
+ * `_copy_dir_dereferencing_symlinks` is reached through six `_deploy_*` frames
+ * carrying no project root — `begin()` scopes the tracker to a run instead.
+ */
+const tracker = createConflictTracker({
+    warn,
+    fail,
+    logWrite: (target) => _log_tx_entry('write', target),
+    emitProgress: (frame) => _emit_progress(frame),
+    tagDeployed: (target, source, package_root) =>
+        _inject_package_tag(target, source, package_root),
+});
 
 // --- File utilities ---
 
@@ -1105,10 +997,8 @@ function _heal_legacy_claude_plugin_ids(p: string): string[] {
 function ensure_claude_bridge(project_root: string, force: boolean): Record<string, unknown>[] {
     const target = path.join(project_root, '.claude', 'settings.json');
     const healed = _heal_legacy_claude_plugin_ids(target);
-    for (const pid of healed) {
-        success(`.claude/settings.json: removed stale plugin id \`${pid}\``);
-    }
-    const bridge = { enabledPlugins: { [CLAUDE_PLUGIN_ID]: true } };
+    for (const pid of healed) success(`.claude/settings.json: removed stale plugin id \`${pid}\``);
+    const bridge = withHostEnv({ enabledPlugins: { [CLAUDE_PLUGIN_ID]: true } }, project_root, success);
     return merge_json_file(target, bridge, force || healed.length > 0, '.claude/settings.json');
 }
 
@@ -2444,75 +2334,36 @@ void prompt_collision_choice;
 
 // --- Manifest / inventory helpers (lazy-import twins are eager static here) ---
 
-function _sha256_of_file(p: string): string | null {
-    return sha256OfFile(p);
-}
-
-function _file_entry(p: string, kind: string, hash_content: boolean): Record<string, unknown> {
-    return {
-        path: p,
-        kind,
-        sha256: hash_content ? _sha256_of_file(p) : null,
-    };
-}
-
 type DeployResult = scoped_projection.DeployTuple;
 
-function _files_by_tool_from_deploy(
-    deploy_results: Record<string, DeployResult>,
-): Record<string, Record<string, unknown>[]> {
-    const out: Record<string, Record<string, unknown>[]> = {};
-    for (const tool_id of Object.keys(deploy_results)) {
-        const [, , status, paths] = deploy_results[tool_id] as DeployResult;
-        if (status === 'deployed') {
-            out[tool_id] = paths.map((p) => _file_entry(p, 'deployed', true));
-        } else if (status === 'marker') {
-            out[tool_id] = paths.map((p) => _file_entry(p, 'marker', true));
-        } else {
-            out[tool_id] = [];
-        }
-    }
-    return out;
-}
-
-function _files_by_tool_from_bridges(
-    tools: Set<string>,
-    project_root: string,
-    scope: string,
-): Record<string, Record<string, unknown>[]> {
-    const out: Record<string, Record<string, unknown>[]> = {};
-    for (const tool_id of [...tools].sort()) {
-        const marker = _bridge_marker(tool_id, scope);
-        if (!marker) continue;
-        let marker_path = marker;
-        if (!path.isAbsolute(marker_path)) {
-            marker_path = path.join(project_root, marker_path);
-        }
-        out[tool_id] = [_file_entry(marker_path, 'bridge', false)];
-    }
-    return out;
-}
-
 function _update_installed_tools_manifest(
     project_root: string,
     tools: Set<string>,
     scope: string,
     force: boolean,
-    files_by_tool: Record<string, Record<string, unknown>[]> | null = null,
+    files_by_tool: Record<string, ManifestFileEntry[] | null> | null = null,
     merged_keys_by_tool: Record<string, Record<string, unknown>[]> | null = null,
 ): number {
     const target = installed_tools.manifest_path(project_root);
     const existing = (installed_tools.read_manifest(target) ?? {}) as Record<string, unknown>;
-    let entries = Array.isArray(existing['tools'])
-        ? ([...(existing['tools'] as unknown[])] as Record<string, unknown>[])
-        : [];
+    // Hydrated because `read_manifest` drops nested `files[]` by design: without
+    // this, rewriting the manifest erases every recorded digest it did not just
+    // rebuild, and an unrecorded managed file is overwritten on the next run.
+    const prior = readRecordedByTool(target, project_root);
+    const preserved = preservedIndex(tracker.conflictState.preserved, tracker.conflictState.staged);
+    let entries = hydrateRecordedInventories(
+        Array.isArray(existing['tools'])
+            ? ([...(existing['tools'] as unknown[])] as Record<string, unknown>[])
+            : [],
+        prior,
+    );
 
     const version = installed_lock.current_package_version();
 
     for (const tool_id of [...tools].sort()) {
         const marker = _bridge_marker(tool_id, scope);
         if (!marker) continue;
-        const files = files_by_tool ? (files_by_tool[tool_id] ?? null) : null;
+        const files = reconcileToolFiles(files_by_tool?.[tool_id], prior.get(tool_id), preserved);
         const merged_keys = merged_keys_by_tool ? (merged_keys_by_tool[tool_id] ?? null) : null;
         try {
             entries = installed_tools.upsert_tool(entries, {
@@ -2890,6 +2741,25 @@ function _escapes_package_root(resolved: string, package_root: string | null): b
     return !global_deploy_inventory.is_ancestor(root, resolved);
 }
 
+/**
+ * Append one `write`/`skip` entry to the transaction log, through the same
+ * `appendTxLog` module the recovery-dismiss route calls — one writer, two
+ * callers, identical entry shape. Failure is swallowed: the log is a recovery
+ * aid, never a condition for the install itself to proceed.
+ */
+function _log_tx_entry(kind: 'write' | 'skip', target: string): void {
+    try {
+        appendTxLog(getLogPath(), {
+            ts: new Date().toISOString(),
+            kind,
+            path: target,
+            sha256: kind === 'write' ? sha256OfFile(target) : null,
+        });
+    } catch {
+        /* swallow — the log is a recovery aid, not a precondition */
+    }
+}
+
 /**
  * Copy `src` → `dest`, dereferencing symlinks, returning
  * `[written, skipped, written_paths]`.
@@ -2925,10 +2795,15 @@ function _copy_dir_dereferencing_symlinks(
             return [0, 0, written_paths];
         }
         mkdirp(path.dirname(dest));
-        const decision = _resolve_file_conflict(dest, force);
-        if (decision === 'skip') return [0, 1, written_paths];
+        const decision = tracker.resolve(dest, force);
+        if (decision === 'preserve') {
+            tracker.preserve(dest, resolved_src, package_root);
+            _log_tx_entry('skip', dest);
+            return [0, 1, written_paths];
+        }
         fs.copyFileSync(src, dest); // follow_symlinks=True is fs.copyFileSync default
         _inject_package_tag(dest, src, package_root);
+        _log_tx_entry('write', dest);
         written_paths.push(dest);
         return [1, 0, written_paths];
     }
@@ -2995,14 +2870,17 @@ function _copy_dir_dereferencing_symlinks(
         if (file_filter !== null && !file_filter(entry)) {
             continue;
         }
-        const decision = _resolve_file_conflict(target, force);
-        if (decision === 'skip') {
+        const decision = tracker.resolve(target, force);
+        if (decision === 'preserve') {
+            tracker.preserve(target, resolved, package_root);
             skipped += 1;
+            _log_tx_entry('skip', target);
             continue;
         }
         mkdirp(path.dirname(target));
         fs.copyFileSync(resolved, target);
         _inject_package_tag(target, resolved, package_root);
+        _log_tx_entry('write', target);
         written += 1;
         written_paths.push(target);
     }
@@ -3014,7 +2892,7 @@ function _claude_desktop_bundles_dir(): string {
 }
 
 function _write_claude_desktop_marker(
-    _force: boolean,
+    force: boolean,
     lockfile_path: string,
     bundles_dir: string,
     bundle_count: number,
@@ -3023,7 +2901,15 @@ function _write_claude_desktop_marker(
     const target = path.join(anchor, 'agent-config.md');
     mkdirp(anchor);
     const body = claudeDesktopMarkerBody(lockfile_path, anchor, bundles_dir, bundle_count);
+    // Generated, but manifest-recorded with a digest — so it is in the class the
+    // preservation ruling covers, and it used to write unconditionally, ignoring
+    // even `--force`, because the tracker was wired only into the copy loop.
+    if (tracker.resolve(target, force) === 'preserve') {
+        tracker.preserveContent(target, body);
+        return [0, 1, []];
+    }
     writeText(target, body);
+    _log_tx_entry('write', target);
     return [1, 0, [target]];
 }
 
@@ -3217,6 +3103,7 @@ function _deploy_global_content(
                 info,
                 warn,
                 res,
+                new Set(tracker.conflictState.preserved.map((p) => path.resolve(p))),
             );
         }
 
@@ -4927,10 +4814,16 @@ function main(argv: string[]): number {
             const rc = _run_migrate_to_global(detect_root);
             if (rc !== 0) return rc;
         }
-        const rc = install_global(parsed_tools, opts.force, detect_root, opts.core_only);
+        tracker.begin(detect_root);
+        const rc = tracker.finalizeRc(
+            install_global(parsed_tools, opts.force, detect_root, opts.core_only),
+        );
         _emit_progress_terminal(rc);
-        if (rc === 0 && wizard_handoff) {
-            return _wizard_spawn(detect_root, false);
+        // A preserved edit does not withhold the wizard, but it survives one: a
+        // zero from the wizard must not erase the conflict signal this run earned.
+        if ((rc === 0 || rc === EXIT_COMPLETED_WITH_CONFLICTS) && wizard_handoff) {
+            const wizard_rc = _wizard_spawn(detect_root, false);
+            return wizard_rc === 0 ? rc : wizard_rc;
         }
         return rc;
     }
@@ -4938,10 +4831,12 @@ function main(argv: string[]): number {
     const project_root =
         custom_path || resolvePath(opts.project || process.env['PROJECT_ROOT'] || process.cwd());
     const is_first_run = !pathExists(path.join(project_root, SETTINGS_FILE));
-    const rc = _main_project_install(opts, project_root, parsed_tools, is_first_run);
+    tracker.begin(project_root);
+    let rc = _main_project_install(opts, project_root, parsed_tools, is_first_run);
     if (rc === 0 && opts.interactive) {
         run_interactive_init(project_root, opts.force);
     }
+    rc = tracker.finalizeRc(rc);
     _emit_progress_terminal(rc);
     return rc;
 }
@@ -5185,7 +5080,7 @@ function _main_project_install(
     }
 
     if (!opts.skip_bridges) {
-        const files_by_tool = _files_by_tool_from_bridges(parsed_tools, project_root, 'project');
+        const files_by_tool = _files_by_tool_from_bridges(parsed_tools, project_root, 'project', _bridge_marker);
         const rc = _update_installed_tools_manifest(
             project_root,
             parsed_tools,
@@ -5301,6 +5196,7 @@ export {
     _format_global_root_for_marker,
     _files_by_tool_from_bridges,
     _files_by_tool_from_deploy,
+    _update_installed_tools_manifest,
     _verify_deploy_targets,
     _wizard_should_launch,
     _dry_run_summary,
@@ -5363,6 +5259,9 @@ export {
     // road-to-local-ci-trust: exported for the symlink-confinement tests
     // (PR #1076 review-gate finding).
     _copy_dir_dereferencing_symlinks,
+    // road-to-a-conformance-check-that-can-fail Phase 5.1: the wired tracker,
+    // so the preservation path is testable (owner ruling 2026-09-21).
+    tracker,
     _preview_global_reap,
     _resolve_global_rule_scope,
     _rule_filter_for_source,

package/src/scripts/janitor.ts

@@ -87,6 +87,13 @@ const TTL_CONFIG: ReadonlyArray<{
         owner: 'maintainer',
         reviewBy: '2026-11-10',
     },
+    {
+        dir: 'agents/runtime/state/memory-recall',
+        ttlDays: 7,
+        description: 'Per-session memory-recall latch (one flag per delivered memory slug)',
+        owner: 'maintainer',
+        reviewBy: '2026-11-10',
+    },
     {
         dir: 'agents/runtime/state/end-review-nudge',
         ttlDays: 7,