@event4u/agent-config 9.26.0 → 9.28.0

package/src/scripts/_lib/carrier_divergence.ts

@@ -0,0 +1,135 @@
+/**
+ * One definition of "these two carriers deliver the same rule" — shared by the
+ * C-3 reachability harness and the advisory divergence report.
+ *
+ * WHY THIS IS A LIBRARY AND NOT TWO COPIES. Two surfaces need the comparison
+ * and they ask different questions of it. `measure_scope_dedup` asks *how many*
+ * installed twins a byte-identity dedup could skip, anchored on the projection
+ * source. `report_carrier_divergence` asks *which* rules a reader must look at,
+ * anchored on the union of both carriers. The directory walks are legitimately
+ * different; the comparison is not, and a second copy of it is how "differs only
+ * in the ownership stamp" and "differs in body" drift into meaning two things.
+ *
+ * The comparison itself is the load-bearing part, so it is stated once:
+ *
+ *   1. bytes equal                     → `identical`
+ *   2. equal after removing the two
+ *      installer ownership keys        → `provenance-only`
+ *   3. otherwise                       → `body-diff`
+ *
+ * Class 2 exists because `install.ts` stamps `package:` and `source_path:` into
+ * every rule it installs while the in-repo projection stamps nothing, so a
+ * provenance-only difference survives even a perfect version alignment. Keeping
+ * it apart from class 3 is what turns a bare "0 identical twins" into an answer:
+ * `provenanceOnly == shared` means aligning versions would buy nothing, and
+ * `bodyDiff > 0` means the two carriers are delivering different text — the only
+ * class where a reader has to act.
+ *
+ * NOT A LICENCE TO DEDUP. Classifying a pair `provenance-only` says the bodies
+ * match; it does NOT say the rule is safe to drop from one carrier. Byte-identity
+ * remains the dedup predicate, deliberately — see
+ * `agents/settings/contexts/dedup-reachability-refusal.md`, which records that
+ * decision and its five reopen conditions. Nothing here relaxes it.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/**
+ * The keys `install.ts` adds to every installed rule (`_set_key(fm_lines,
+ * 'package', …)` and `source_path` at install.ts:2733). Removing them is what
+ * separates an installer stamp from a content change.
+ */
+export const OWNERSHIP_KEYS = ['package', 'source_path'] as const;
+
+export type PairVerdict = 'identical' | 'provenance-only' | 'body-diff';
+
+/**
+ * Drop the ownership stamp lines, wherever they appear in the FILE.
+ *
+ * Not scoped to the frontmatter, and the docstring says so because the scope is
+ * wider than the intent. Two reasons it stays this way: `install.ts` writes the
+ * keys without any guarantee about fence position, and `scope_dedup.test.ts`
+ * deliberately pins the fence-less shape (a stamp with no `---` around it) as the
+ * install condition. Residual risk, stated rather than hidden: a rule body that
+ * contains a line literally starting `package:` or `source_path:` — a YAML
+ * example, an indent-free config snippet — has that line removed from both sides,
+ * so a genuine difference confined to such a line would read `provenance-only`
+ * instead of `body-diff`. Measured over the shipped corpus: no rule body carries
+ * one. Re-check that before treating the class as impossible rather than absent.
+ */
+export function stripOwnershipKeys(text: string): string {
+    return text
+        .split('\n')
+        .filter((line) => !OWNERSHIP_KEYS.some((k) => line.startsWith(`${k}:`)))
+        .join('\n');
+}
+
+/**
+ * Compare one rule's two copies.
+ *
+ * Takes buffers rather than paths: the callers already hold them, and a pure
+ * function is what lets both surfaces pin the same three-way split in tests
+ * without a filesystem.
+ */
+export function comparePair(a: Buffer, b: Buffer): PairVerdict {
+    if (a.equals(b)) {
+        return 'identical';
+    }
+    if (stripOwnershipKeys(a.toString('utf-8')) === stripOwnershipKeys(b.toString('utf-8'))) {
+        return 'provenance-only';
+    }
+    return 'body-diff';
+}
+
+export interface RuleDirCensus {
+    files: number;
+    /**
+     * BYTES, not characters — `statSync().size`. The name is kept because every
+     * consumer of this figure (`preamble_byte_census`, `measure_scope_dedup`, the
+     * conformance scan) already divides it by 4 under that name, and one honest
+     * docstring beats a rename that would silently move three published baselines.
+     *
+     * The gap is measured, not assumed: over the 110-rule project tree, 406 502
+     * bytes against 402 823 characters — **0.91 %** overhead from the em-dashes,
+     * arrows and status glyphs the prose uses. So the published token estimate
+     * reads 101 626 where a character basis gives 100 706. Under 1 % and in the
+     * conservative direction for a payload figure, which is why it is documented
+     * rather than repaired; re-measure before quoting it as negligible on a corpus
+     * with more non-ASCII than this one.
+     */
+    chars: number;
+}
+
+/**
+ * How much rule text one carrier delivers.
+ *
+ * `statSync`, not `lstatSync`, on purpose: a project-scope entry is a symlink
+ * into `dist/`, and the bytes the HOST reads are the target's. Measuring the link
+ * would report ~50 bytes per rule and make the whole payload vanish.
+ *
+ * Moved here from `preamble_byte_census` when `conformance_scan` needed it:
+ * that module pulls `yaml` and the cold-start report, and importing a dependency
+ * chain into a bundled CLI path to reach fifteen lines of `statSync` is the wrong
+ * trade. `preamble_byte_census` re-exports this so its own callers are unchanged
+ * and there is still exactly one definition.
+ */
+export function censusRuleDir(dir: string): RuleDirCensus {
+    let files = 0;
+    let chars = 0;
+    let entries: string[];
+    try {
+        entries = fs.readdirSync(dir);
+    } catch {
+        return { files: 0, chars: 0 };
+    }
+    for (const name of entries) {
+        if (!name.endsWith('.md')) continue;
+        try {
+            chars += fs.statSync(path.join(dir, name)).size;
+            files += 1;
+        } catch {
+            // Unreadable entry — skip rather than fail the whole census.
+        }
+    }
+    return { files, chars };
+}

package/src/scripts/_lib/git_common_dir.ts

@@ -0,0 +1,128 @@
+/**
+ * Resolve a repository's **common git directory** — the one directory every
+ * worktree of a repo shares.
+ *
+ * Extracted from `_cli/cmd_doctor.ts::_git_config_path`, which has resolved the
+ * `commondir` file this way since the git-identity check shipped. It is
+ * extracted rather than re-implemented on purpose: a repo with two different
+ * answers to "where is the common dir" is a bug waiting for a symlinked parent,
+ * and the worktree-cleanup work already hit that class once.
+ *
+ * ## Why this reads files instead of shelling out to git
+ *
+ * `git rev-parse --git-common-dir` is the obvious implementation and is wrong
+ * for the callers here, twice over:
+ *
+ * 1. **Inherited `GIT_DIR` overrides discovery.** Git hooks export `GIT_DIR`,
+ *    and every child inherits it, so `execFileSync('git', …, { cwd })` silently
+ *    resolves against the *hook's* repository rather than `cwd` — in a linked
+ *    worktree those differ, and the symptom is wrong data, not an error. That
+ *    is exactly what `_lib/git_env.ts` exists to strip. A file-based resolution
+ *    has nothing to override and needs no such guard.
+ * 2. **The raw output is not comparable across checkouts.** Measured
+ *    2026-08-07: from a main checkout `git rev-parse --git-common-dir` prints
+ *    the **relative** `.git`; from a linked worktree it prints an absolute
+ *    path. A consumer comparing the raw strings concludes the two checkouts
+ *    have different common dirs. Only the resolved realpath is a repo identity.
+ *
+ * ## Symlinked parents converge
+ *
+ * Measured on a throwaway repo reached both directly and through a symlinked
+ * ancestor: all four accesses (main / worktree × real / symlinked) resolve to
+ * the same directory, because the returned path is realpath-normalised here.
+ * This is the opposite of the worktree-cleanup finding that motivated the
+ * check — there realpath reporting caused a mis-classification; here it is the
+ * property that makes one shared register possible.
+ *
+ * Never throws: every caller treats "no common dir" as a reason to degrade,
+ * not as an error worth failing a hook over.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** `fs.realpathSync` that falls back to the input when the path is unreadable. */
+function realpath_or_self(p: string): string {
+    try {
+        return fs.realpathSync(p);
+    } catch {
+        return p;
+    }
+}
+
+/**
+ * The **per-worktree** git directory for `project_root` — `.git` in a plain
+ * checkout, the linked gitdir in a worktree. This is where `HEAD` lives, so it
+ * is the right anchor for "which branch is THIS checkout on", as opposed to
+ * `git_common_dir` which is deliberately shared across worktrees.
+ */
+export function git_dir(project_root: string): string | null {
+    const dot_git = path.join(project_root, '.git');
+    try {
+        const st = fs.statSync(dot_git);
+        if (st.isDirectory()) {
+            return realpath_or_self(dot_git);
+        }
+        const m = fs.readFileSync(dot_git, 'utf-8').match(/^gitdir:\s*(.+)\s*$/m);
+        if (m === null) {
+            return null;
+        }
+        return realpath_or_self(path.resolve(project_root, m[1]!.trim()));
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Current branch name for `project_root`, or `null` on a detached HEAD or
+ * outside a repo.
+ *
+ * Reads `<git-dir>/HEAD` directly rather than shelling out, for the same reason
+ * as everything else in this module: hooks export `GIT_DIR`, and an inherited
+ * one silently redirects `git` to the wrong repository.
+ */
+export function current_branch(project_root: string): string | null {
+    const gd = git_dir(project_root);
+    if (gd === null) return null;
+    try {
+        const head = fs.readFileSync(path.join(gd, 'HEAD'), 'utf-8').trim();
+        const m = head.match(/^ref:\s*refs\/heads\/(.+)$/);
+        return m === null ? null : m[1]!.trim();
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * The common git directory for `project_root`, realpath-normalised, or `null`
+ * when `project_root` is not inside a git repository.
+ *
+ * - Plain checkout → `<project_root>/.git`.
+ * - Linked worktree → the `commondir` target of the worktree's gitdir, i.e. the
+ *   main checkout's `.git`, which is identical from every worktree of the repo.
+ * - Worktree gitdir without a `commondir` file → the gitdir itself (degenerate,
+ *   but the historical behaviour and not this change's to alter).
+ */
+export function git_common_dir(project_root: string): string | null {
+    const dot_git = path.join(project_root, '.git');
+    try {
+        const st = fs.statSync(dot_git);
+        if (st.isDirectory()) {
+            return realpath_or_self(dot_git);
+        }
+        // Linked worktree: `.git` is a FILE containing "gitdir: <path>".
+        const m = fs.readFileSync(dot_git, 'utf-8').match(/^gitdir:\s*(.+)\s*$/m);
+        if (m === null) {
+            return null;
+        }
+        const gitdir = path.resolve(project_root, m[1]!.trim());
+        const commondir_file = path.join(gitdir, 'commondir');
+        if (fs.existsSync(commondir_file)) {
+            const common = path.resolve(gitdir, fs.readFileSync(commondir_file, 'utf-8').trim());
+            return realpath_or_self(common);
+        }
+        return realpath_or_self(gitdir);
+    } catch {
+        return null;
+    }
+}

package/src/scripts/_lib/host_capability.ts

@@ -1,5 +1,5 @@
 /**
- * Host-capability manifest normalizer.
+ * Host-capability manifest normalizer + committed capability registry.
  *
  * Pure, no-I/O helper that takes a partial / unknown object (typically the
  * `subagents.host_capabilities` override from `.agent-settings.yml`, or the
@@ -11,6 +11,18 @@
  *   have no subagent primitive.
  * - A missing or non-boolean field resolves to `false`, never `true`.
  * - `schema_version` is always forced to `1`.
+ *
+ * `resolveHostCapabilities` (F5, road-to-orchestrator-discipline-carriers)
+ * adds a resolution order in front of the safe default so a fresh install on
+ * a KNOWN host does not ship delegation dead by default:
+ *
+ *   explicit `subagents.host_capabilities` override (wins, whole-object,
+ *   unchanged semantics) → committed registry row for the detected host
+ *   (`HOST_CAPABILITY_REGISTRY`) → `SAFE_DEFAULT` (all false).
+ *
+ * The registry lists only OBSERVED capabilities for a host this repo has
+ * actually measured (see the roadmap's transcript evidence) — never a
+ * speculative entry for a host nobody has verified.
  */
 
 /** Resolved host-capability manifest. All booleans, `schema_version` fixed at 1. */
@@ -57,3 +69,74 @@ export function normalizeHostManifest(input: unknown): HostCapabilityManifest {
         separate_quota_pool: asBool(src.separate_quota_pool),
     };
 }
+
+/**
+ * Committed registry — known host identifiers → OBSERVED capability sets.
+ *
+ * Keyed by the platform identifier this repo already uses for the same host
+ * across the hook/dispatch layer (`--platform claude`, `platforms['claude']`
+ * in `claude_settings_hooks.ts`, `TOOL_IDS` in `probe_skill_registration.ts`)
+ * — NOT the separate `toolDetection.ts` binary-detection id (`'claude-code'`),
+ * which names a different namespace (installed-CLI presence, not the running
+ * host identity a hook/dispatch envelope carries).
+ *
+ * Each row is partial: an omitted field stays at the `SAFE_DEFAULT` `false`
+ * when the row is applied. Claude Code is the one host this roadmap's
+ * transcript evidence measured spawning and running subagents concurrently
+ * (`Agent` tool dispatch, parallel tool-use blocks); polling and a separate
+ * quota pool were never observed, so they stay `false` — add a field only
+ * once it is itself observed, never by inference.
+ */
+const HOST_CAPABILITY_REGISTRY: Readonly<Record<string, Partial<HostCapabilityManifest>>> = {
+    claude: { subagent_spawn: true, parallel_spawn: true },
+};
+
+/**
+ * Resolve the effective host-capability manifest for `hostId`.
+ *
+ * Resolution order (highest wins), per
+ * `host-capability-manifest.md § Resolution`:
+ *
+ * 1. `override` — the `subagents.host_capabilities` settings value, when
+ *    present as a non-null object. Normalized exactly as {@link normalizeHostManifest}
+ *    always has: a WHOLE-OBJECT override, each field independently coerced,
+ *    a field absent from the override object resolves to `false`. This is
+ *    the pre-existing, unchanged behavior — a present override still wins
+ *    outright over the registry row, it does not merge field-by-field with it.
+ * 2. The committed {@link HOST_CAPABILITY_REGISTRY} row for `hostId`, when no
+ *    override is present and the host is known.
+ * 3. `SAFE_DEFAULT` — unknown `hostId`, or no override and no registry row.
+ *
+ * `hostId` is a caller-supplied identifier (e.g. the same string a hook
+ * envelope's `platform` field carries) — this function does no environment
+ * probing of its own; see `host-capability-manifest.md` for why resolution
+ * stays a per-session, agent/caller-supplied fact rather than a live probe.
+ *
+ * An array override does NOT count as present (F8, review): `typeof [] ===
+ * 'object'` in JS, so a bare `typeof override === 'object'` check let a
+ * stray array reach `normalizeHostManifest`, which reads named properties
+ * off it (`.subagent_spawn`, …) that an array never has — every field
+ * silently coerces to `false`, exactly like an explicit empty-object
+ * override, even though nobody supplied one. An array is not a manifest
+ * shape at all, so it is treated the same as `null`/non-object: fall
+ * through to the registry row.
+ */
+export function resolveHostCapabilities(
+    hostId: string | null | undefined,
+    override?: unknown,
+): HostCapabilityManifest {
+    if (
+        override !== undefined &&
+        override !== null &&
+        typeof override === 'object' &&
+        !Array.isArray(override)
+    ) {
+        return normalizeHostManifest(override);
+    }
+    const row =
+        hostId !== null && hostId !== undefined ? HOST_CAPABILITY_REGISTRY[hostId] : undefined;
+    if (row === undefined) {
+        return { ...SAFE_DEFAULT };
+    }
+    return { ...SAFE_DEFAULT, ...row, schema_version: 1 };
+}