@event4u/agent-config 9.10.0 → 9.11.0

package/src/scripts/_lib/changelog_eras.ts

@@ -409,13 +409,97 @@ function _rstrip(text: string): string {
     return text.replace(/\s+$/u, '');
 }
 
+/**
+ * Split a current-era body into (carry-over, archived) at `boundary`.
+ *
+ * The archive is named `pre-<boundary>`, so by its own contract it may only
+ * hold entries STRICTLY OLDER than the boundary. Sections at or above it —
+ * i.e. the incoming release's own entry, when it is already prepended — stay
+ * in the new era.
+ *
+ * On a fresh release run the body never contains the incoming entry (the split
+ * runs before the prepend), so the carry-over is empty and this is a no-op.
+ * On a `--resume` run the entry IS already committed and the bump step is
+ * correctly skipped, so without this partition the split archived the release
+ * it was named after and nothing ever put it back: the current era ended up
+ * empty and the `changelog-entry` CI gate went red. That is the 9.10.0
+ * failure. The partition makes the two orderings converge.
+ *
+ * Changelog bodies are newest-first, so the carry-over is a prefix — but the
+ * scan is per-heading rather than "stop at the first older one" so a
+ * hand-edited out-of-order body cannot silently archive a newer entry.
+ */
+export function _partition_era_body(
+    body: readonly string[],
+    boundary: string,
+): { carry: string[]; archived: string[] } {
+    const b = _RELEASE_VERSION_RE.exec(boundary.trim());
+    if (!b) {
+        throw new Error(`not a bare semver (X.Y.Z): '${boundary}'`);
+    }
+    const bound: [number, number, number] = [
+        Number.parseInt(b[1]!, 10),
+        Number.parseInt(b[2]!, 10),
+        Number.parseInt(b[3]!, 10),
+    ];
+
+    // Section boundaries: every `## [X.Y.Z]` heading starts a new section.
+    // Content before the first heading (there should be none) rides along with
+    // the archive, matching the pre-fix behaviour for that shape.
+    const starts: number[] = [];
+    for (let i = 0; i < body.length; i++) {
+        if (VERSION_HEADING_RE.test(body[i]!)) {
+            starts.push(i);
+        }
+    }
+    if (starts.length === 0) {
+        return { carry: [], archived: [...body] };
+    }
+
+    const carry: string[] = [];
+    const archived: string[] = [...body.slice(0, starts[0]!)];
+    for (let s = 0; s < starts.length; s++) {
+        const from = starts[s]!;
+        const to = s + 1 < starts.length ? starts[s + 1]! : body.length;
+        const section = body.slice(from, to);
+        const m = VERSION_HEADING_RE.exec(body[from]!);
+        const v = m?.groups?.['version'];
+        const parsed = v ? _RELEASE_VERSION_RE.exec(v) : null;
+        if (parsed === null || parsed === undefined) {
+            archived.push(...section);
+            continue;
+        }
+        const cur: [number, number, number] = [
+            Number.parseInt(parsed[1]!, 10),
+            Number.parseInt(parsed[2]!, 10),
+            Number.parseInt(parsed[3]!, 10),
+        ];
+        const isOlder =
+            cur[0] < bound[0] ||
+            (cur[0] === bound[0] && cur[1] < bound[1]) ||
+            (cur[0] === bound[0] && cur[1] === bound[1] && cur[2] < bound[2]);
+        (isOlder ? archived : carry).push(...section);
+    }
+    return { carry, archived };
+}
+
+/** Drop trailing blank lines (in place semantics, returns the same array). */
+function _trim_trailing_blanks(xs: string[]): string[] {
+    while (xs.length > 0 && xs[xs.length - 1]!.trim() === '') {
+        xs.pop();
+    }
+    return xs;
+}
+
 /**
  * Execute `plan` against the on-disk CHANGELOG.md.
  *
  * - Refuses to overwrite an existing archive file.
- * - Moves every entry in the current era body into the new archive.
+ * - Moves every entry OLDER than the boundary into the new archive; an
+ *   already-prepended entry for the incoming release stays in the new era
+ *   (see `_partition_era_body`).
  * - Replaces the current era block with the collapsed pointer + the
- *   freshly-labelled new current era header (empty body).
+ *   freshly-labelled new current era header.
  */
 export function perform_split(plan: SplitPlan): void {
     if (fs.existsSync(plan.archive_path)) {
@@ -433,21 +517,31 @@ export function perform_split(plan: SplitPlan): void {
     }
 
     const [body_start, , next_era_line] = _era_body_bounds(lines, current_idx);
-    const entries = lines.slice(body_start, next_era_line);
-    // Trim trailing blank lines so the archive doesn't accumulate them.
-    while (entries.length > 0 && entries[entries.length - 1]!.trim() === '') {
-        entries.pop();
-    }
+    const body = lines.slice(body_start, next_era_line);
+    // Entries at/above the boundary (a resume run's already-prepended release
+    // entry) stay in the new era; only older ones are archived.
+    const { carry, archived } = _partition_era_body(body, plan.boundary);
+    // Trim trailing blank lines so neither side accumulates them.
+    _trim_trailing_blanks(archived);
+    _trim_trailing_blanks(carry);
 
     const collapsed = _splitlines(_rstrip_newlines(collapsed_era_block(plan.boundary)));
     const new_era = _splitlines(_rstrip_newlines(new_era_intro_block(plan.new_era_label, plan.boundary)));
 
     const head = lines.slice(0, current_idx);
     const tail = lines.slice(next_era_line);
-    const new_lines = [...head, ...collapsed, '', ...new_era, '', ...tail];
+    const new_lines = [
+        ...head,
+        ...collapsed,
+        '',
+        ...new_era,
+        '',
+        ...(carry.length > 0 ? [...carry, ''] : []),
+        ...tail,
+    ];
     const new_text = _rstrip(new_lines.join('\n')) + '\n';
 
-    const archive_body = entries.length > 0 ? _rstrip(entries.join('\n')) + '\n' : '';
+    const archive_body = archived.length > 0 ? _rstrip(archived.join('\n')) + '\n' : '';
     const archive_text = archive_file_header(plan.boundary) + archive_body;
 
     fs.mkdirSync(path.dirname(plan.archive_path), { recursive: true });

package/src/scripts/_lib/environment_detector.ts

@@ -0,0 +1,441 @@
+/**
+ * Read-only environment detection — one report, no spend (Phase 1 of
+ * `road-to-zero-ceremony-detection`).
+ *
+ * Answers "what does this machine already have?" in a single pass so the
+ * `doctor` surface and the council's transport resolution read the SAME
+ * facts instead of each probing on its own. Three record kinds:
+ *
+ * - `hosts` — which AI hosts are installed, their resolved binary, version.
+ * - `auth`  — which provider credentials are PRESENT, and of which source.
+ * - `keys`  — the `api_key_ref`-shaped reference for each present key.
+ *
+ * ## Guarantees
+ *
+ * - **Zero network.** Nothing here opens a socket. Enforced by the static
+ *   import check in the test suite, not by convention.
+ * - **Zero spend.** The only subprocess is `<binary> --version`, which no
+ *   provider bills. No completion, no token, ever — the roadmap's
+ *   install-time-completion item was cut for exactly this reason.
+ * - **Presence, never validity.** An `auth` record says "a credential of this
+ *   shape exists at this path". It does NOT say the credential works, is
+ *   unexpired, or is accepted by the provider. Runtime auth failure stays
+ *   authoritative (`CliClient._AUTH_FAILURE_PATTERNS`).
+ * - **Read-only.** Reads the filesystem and the injected env map; writes
+ *   nothing, creates no directory.
+ *
+ * ## No third probe shape — what each field absorbs
+ *
+ * Auth probing already existed in two shapes before this module and a third
+ * must not appear. This module composes; it re-implements nothing:
+ *
+ * | Field | Absorbed from |
+ * |---|---|
+ * | `hosts[].installed` | `install/toolDetection.ts::detectInstalledTools` (the 23-host signal table) |
+ * | `hosts[].binary` | `install/toolDetection.ts::resolveToolBinary` (same table, path-returning) |
+ * | `hosts[].version` | `install/agentSwitchDetection.ts::parseVersionOutput` (the first-dotted-number parser) |
+ * | `auth` (`openai`, `cli-*`) | `_cli/cmd_doctor.ts`'s read-only `$CODEX_HOME/auth.json` probe — `codexHome()` moved HERE and imported back, so there is one definition |
+ * | `auth` (`anthropic`, `cli-subscription`) | `_lib/claude_plugin.ts::claude_config_dir` (`CLAUDE_CONFIG_DIR` override incl.) |
+ * | `auth` (`key-file`) | `_lib/user_global_paths.ts::resolve_with_fallback` (new namespace, legacy read-fallback) |
+ *
+ * The council's TTL'd `AuthCache` (`ai_council/solo_dispatch.ts`) is the third
+ * existing shape and is deliberately NOT absorbed: it caches a *liveness*
+ * verdict from an injected probe that may spend a call. This module only
+ * reports presence, so it needs no TTL — a per-process memo is enough.
+ *
+ * ## Known limitation — CLI logins the filesystem does not reveal
+ *
+ * A vendor CLI that stores its subscription credential OUTSIDE the filesystem
+ * is undetectable here. Measured case: on macOS the `claude` CLI keeps its
+ * OAuth credential in the system Keychain, so `~/.claude/.credentials.json`
+ * is absent even for a logged-in Claude Pro user. The detector reports
+ * `cli-subscription` only where a credential FILE exists (Linux, and the
+ * `CLAUDE_CONFIG_DIR` profile layouts).
+ *
+ * Consequence, stated because it costs money: with no detectable CLI login,
+ * `mode: auto` skips the cli rung and resolves to `api` — metered — for a user
+ * who does hold a subscription. This is a FALSE NEGATIVE, which is the
+ * direction this module is built to fail in (a false positive would claim a
+ * subscription that is not there and switch the USD gate off). The remedy is an
+ * explicit `mode: cli` on the member; `doctor` shows the detected source so the
+ * gap is visible rather than silent. Reading the Keychain would require a
+ * `security(1)` subprocess against a credential store — a spend-free but
+ * privacy-relevant probe, and out of scope here.
+ *
+ * @see docs/contracts/ai-council-config.md § Transport modes — the billing rules
+ *      `classifyBilling` implements.
+ */
+
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+
+import {
+    detectInstalledTools,
+    knownToolIds,
+    resolveToolBinary,
+} from '../../install/toolDetection.js';
+import { parseVersionOutput } from '../../install/agentSwitchDetection.js';
+import { claude_config_dir } from './claude_plugin.js';
+import { hardenedSpawnEnv } from './spawn_env.js';
+import { resolve_with_fallback, type EnvMap } from './user_global_paths.js';
+
+/** Where a present credential was found. Never a claim that it works. */
+export type AuthSource = 'cli-subscription' | 'cli-api-key' | 'key-file' | 'env-key';
+
+/**
+ * How a call against this provider is paid for.
+ *
+ * `subscription` — covered by a flat-rate plan the user already pays; the USD
+ * cost gate does not apply (`cli_call_budget` guards the quota instead).
+ * `per-token` — metered spend; the full `cost_budget` applies.
+ */
+export type BillingClass = 'subscription' | 'per-token';
+
+/** Version string when parseable, the literal `'unknown'` when not, `null` when unprobed. */
+export type HostVersion = string | 'unknown' | null;
+
+export interface DetectedHost {
+    readonly id: string;
+    readonly installed: boolean;
+    /** Resolved executable path, or `null` when the host has no binary on `$PATH`. */
+    readonly binary: string | null;
+    readonly version: HostVersion;
+}
+
+export interface DetectedAuth {
+    readonly provider: string;
+    readonly source: AuthSource;
+    /** A filesystem path, or `env:<VAR>` — presence evidence only. */
+    readonly evidence: string;
+}
+
+export interface DetectedKey {
+    readonly provider: string;
+    /** `api_key_ref`-shaped: `file:<name>.key` or `env:<VAR>`. */
+    readonly ref: string;
+}
+
+export interface EnvironmentReport {
+    readonly hosts: readonly DetectedHost[];
+    readonly auth: readonly DetectedAuth[];
+    readonly keys: readonly DetectedKey[];
+}
+
+/**
+ * Provider → (default CLI binary, community-wrapper flag).
+ *
+ * Mirrors the `CliClient` subclass attributes without importing the client
+ * layer. The boolean is the load-bearing billing input: a VENDOR-OFFICIAL CLI
+ * (`false`) runs under the user's subscription; a COMMUNITY wrapper (`true`)
+ * shells out to the same paid API and stays metered. Canonical here so
+ * `cmd_doctor` and this module cannot drift.
+ */
+export const PROVIDER_CLI_META: Readonly<Record<string, readonly [string, boolean]>> = {
+    anthropic: ['claude', false],
+    openai: ['codex', false],
+    gemini: ['gemini', false],
+    xai: ['grok', true],
+    perplexity: ['perplexity', true],
+};
+
+/** Provider → environment variable carrying a raw API key. */
+const PROVIDER_ENV_KEY: Readonly<Record<string, string>> = {
+    anthropic: 'ANTHROPIC_API_KEY',
+    openai: 'OPENAI_API_KEY',
+    gemini: 'GEMINI_API_KEY',
+    xai: 'XAI_API_KEY',
+    perplexity: 'PERPLEXITY_API_KEY',
+};
+
+/** Provider → key-file name under the user-global root (`file:` ref target). */
+const PROVIDER_KEY_FILE: Readonly<Record<string, string>> = {
+    anthropic: 'anthropic.key',
+    openai: 'openai.key',
+    gemini: 'gemini.key',
+    xai: 'xai.key',
+    perplexity: 'perplexity.key',
+};
+
+/** Providers this module knows how to classify, in a stable order. */
+export function knownProviders(): readonly string[] {
+    return Object.keys(PROVIDER_CLI_META);
+}
+
+/** True when `provider`'s CLI is a community wrapper around the paid API. */
+export function isCommunityCli(provider: string): boolean {
+    return PROVIDER_CLI_META[provider]?.[1] ?? false;
+}
+
+/**
+ * Billing class from (provider, detected auth source) — NEVER from transport.
+ *
+ * This signature is the invariant: there is no transport / mode parameter, so
+ * no caller can make billing depend on which transport was chosen. That is
+ * what keeps the per-provider rules intact when `auto` picks a transport at
+ * invocation time: a vendor-official CLI logged in under a subscription is
+ * unmetered; everything else — including a community CLI and including an
+ * unknown source — is metered, i.e. deliberately over-gated.
+ *
+ * `null` source means "nothing detected" and classifies as `per-token`: the
+ * safe direction is to keep the USD gate on.
+ */
+export function classifyBilling(provider: string, source: AuthSource | null): BillingClass {
+    if (source !== 'cli-subscription') return 'per-token';
+    if (isCommunityCli(provider)) return 'per-token';
+    return 'subscription';
+}
+
+/**
+ * Codex CLI home — `CODEX_HOME` env override (the codex CLI's own
+ * convention), else `~/.codex`. Single definition; `cmd_doctor` imports it.
+ */
+export function codexHome(env?: EnvMap | null): string {
+    const map = env ?? process.env;
+    const override = (map['CODEX_HOME'] ?? '').trim();
+    return override !== '' ? override : path.join(homeOf(env), '.codex');
+}
+
+function homeOf(env?: EnvMap | null): string {
+    const map = env ?? process.env;
+    const injected = (map['HOME'] ?? '').trim();
+    return injected !== '' ? injected : os.homedir();
+}
+
+const VERSION_PROBE_TIMEOUT_MS = 2000;
+
+/** Injected `<binary> --version` runner. Returns raw combined output, or `null`. */
+export type VersionProbe = (binary: string) => string | null;
+
+export interface DetectEnvironmentOptions {
+    /** Home directory override (tests / fixture machines). */
+    readonly home?: string;
+    /** `$PATH` override (tests / fixture machines). */
+    readonly pathEnv?: string;
+    /** Environment map override; also carries `CODEX_HOME` / `EVENT4U_CONFIG_HOME`. */
+    readonly env?: EnvMap;
+    /**
+     * Version probe override. Omit to spawn `<binary> --version` with a
+     * hardened env and a 2s timeout; pass `() => null` to skip probing.
+     */
+    readonly probeVersion?: VersionProbe;
+}
+
+/**
+ * `<binary> --version` under a hardened env. Never throws — a spawn error,
+ * timeout, signal, or unparseable output all collapse to `null`, which the
+ * caller degrades to `'unknown'`.
+ *
+ * Hardened per `docs/spawn-site-policy.md` (this runs on the consumer runtime
+ * via `doctor`). Note the env scrub deliberately does NOT strip
+ * `CLAUDE_CONFIG_DIR` — see `docs/threat-model.md` row i.
+ */
+function defaultProbeVersion(binary: string): string | null {
+    try {
+        const res = spawnSync(binary, ['--version'], {
+            timeout: VERSION_PROBE_TIMEOUT_MS,
+            encoding: 'utf-8',
+            windowsHide: true,
+            env: hardenedSpawnEnv(),
+        });
+        if (res.error !== undefined || res.signal !== null) return null;
+        return `${res.stdout ?? ''}\n${res.stderr ?? ''}`;
+    } catch {
+        return null;
+    }
+}
+
+function isFile(p: string): boolean {
+    try {
+        return fs.statSync(p).isFile();
+    } catch {
+        return false;
+    }
+}
+
+function exists(p: string): boolean {
+    try {
+        return fs.existsSync(p);
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Classify a codex `auth.json` by which credential shape it carries.
+ *
+ * OAuth tokens ⇒ the user logged in with a ChatGPT plan (`cli-subscription`);
+ * anything else ⇒ metered (`cli-api-key`). A present-but-unreadable or
+ * malformed file also reports `cli-api-key` — the over-gated direction, since
+ * assuming a plan would switch the USD gate off on no evidence.
+ */
+function classifyCodexAuth(authPath: string): AuthSource {
+    let data: unknown;
+    try {
+        data = JSON.parse(fs.readFileSync(authPath, 'utf-8'));
+    } catch {
+        // Present but unreadable: over-gate (metered) rather than assume a plan.
+        return 'cli-api-key';
+    }
+    if (typeof data !== 'object' || data === null || Array.isArray(data)) {
+        return 'cli-api-key';
+    }
+    const d = data as Record<string, unknown>;
+    const tokens = d['tokens'];
+    const hasOauth =
+        typeof tokens === 'object' &&
+        tokens !== null &&
+        !Array.isArray(tokens) &&
+        Object.keys(tokens as Record<string, unknown>).length > 0;
+    if (hasOauth) return 'cli-subscription';
+    return 'cli-api-key';
+}
+
+/** Provider-specific `cli-subscription` evidence path, or `null` when none applies. */
+function cliSubscriptionEvidence(
+    provider: string,
+    home: string,
+    env: EnvMap,
+    claudeConfigDir: string,
+): { source: AuthSource; evidence: string } | null {
+    if (provider === 'anthropic') {
+        const configDir = claudeConfigDir;
+        for (const rel of ['.credentials.json', 'credentials.json']) {
+            const p = path.join(configDir, rel);
+            if (isFile(p)) return { source: 'cli-subscription', evidence: p };
+        }
+        return null;
+    }
+    if (provider === 'openai') {
+        const p = path.join(codexHome(env), 'auth.json');
+        if (isFile(p)) return { source: classifyCodexAuth(p), evidence: p };
+        return null;
+    }
+    if (provider === 'gemini') {
+        const p = path.join(home, '.gemini', 'oauth_creds.json');
+        if (isFile(p)) return { source: 'cli-subscription', evidence: p };
+        return null;
+    }
+    // xai / perplexity ship no subscription login — their CLIs read an API key.
+    return null;
+}
+
+function detectHosts(opts: DetectEnvironmentOptions): DetectedHost[] {
+    const installedMap = detectInstalledTools({
+        ...(opts.home !== undefined ? { home: opts.home } : {}),
+        pathEnv: opts.pathEnv,
+    });
+    const probe = opts.probeVersion ?? defaultProbeVersion;
+    const out: DetectedHost[] = [];
+    for (const id of knownToolIds()) {
+        const binary = resolveToolBinary(id, opts.pathEnv);
+        let version: HostVersion = null;
+        if (binary !== null) {
+            let raw: string | null;
+            try {
+                raw = probe(binary);
+            } catch {
+                raw = null;
+            }
+            // An unparseable version degrades to 'unknown' — never throws,
+            // never omits the host from the report.
+            version = raw === null ? 'unknown' : (parseVersionOutput(raw) ?? 'unknown');
+        }
+        out.push({ id, installed: installedMap[id] ?? false, binary, version });
+    }
+    return out;
+}
+
+function detectAuth(opts: DetectEnvironmentOptions): {
+    auth: DetectedAuth[];
+    keys: DetectedKey[];
+} {
+    const env = opts.env ?? process.env;
+    const home = opts.home ?? homeOf(opts.env);
+    // Delegate to claude_plugin's resolver on the live path (it owns the
+    // CLAUDE_CONFIG_DIR override); derive from the injected home otherwise.
+    const claudeConfigDir =
+        opts.home === undefined && opts.env === undefined
+            ? claude_config_dir()
+            : ((env['CLAUDE_CONFIG_DIR'] ?? '').trim() || path.join(home, '.claude'));
+    const auth: DetectedAuth[] = [];
+    const keys: DetectedKey[] = [];
+
+    for (const provider of knownProviders()) {
+        const cli = cliSubscriptionEvidence(provider, home, env, claudeConfigDir);
+        if (cli !== null) {
+            auth.push({ provider, source: cli.source, evidence: cli.evidence });
+        }
+
+        const keyFile = PROVIDER_KEY_FILE[provider];
+        if (keyFile !== undefined) {
+            let resolved: string | null = null;
+            try {
+                resolved = resolve_with_fallback(keyFile, { env });
+            } catch {
+                resolved = null;
+            }
+            if (resolved !== null && exists(resolved)) {
+                auth.push({ provider, source: 'key-file', evidence: resolved });
+                keys.push({ provider, ref: `file:${keyFile}` });
+            }
+        }
+
+        const envVar = PROVIDER_ENV_KEY[provider];
+        if (envVar !== undefined && (env[envVar] ?? '').trim() !== '') {
+            auth.push({ provider, source: 'env-key', evidence: `env:${envVar}` });
+            keys.push({ provider, ref: `env:${envVar}` });
+        }
+    }
+    return { auth, keys };
+}
+
+/**
+ * Strongest auth source detected for `provider`, or `null`.
+ *
+ * "Strongest" is the transport-preference order `auto` walks: a vendor CLI
+ * login beats a stored key. Pure over an already-built report.
+ */
+export function strongestAuth(
+    report: EnvironmentReport,
+    provider: string,
+): DetectedAuth | null {
+    const order: readonly AuthSource[] = [
+        'cli-subscription',
+        'cli-api-key',
+        'key-file',
+        'env-key',
+    ];
+    for (const source of order) {
+        const hit = report.auth.find((a) => a.provider === provider && a.source === source);
+        if (hit !== undefined) return hit;
+    }
+    return null;
+}
+
+let _cached: EnvironmentReport | null = null;
+
+/**
+ * Build the environment report.
+ *
+ * Cached per process for the no-argument call (the production shape) so
+ * `doctor` and transport resolution observe one consistent snapshot; any call
+ * that injects options bypasses the cache and returns a fresh read, so tests
+ * and fixture machines never poison each other. Reset with
+ * `resetEnvironmentCache()`.
+ */
+export function detectEnvironment(opts: DetectEnvironmentOptions = {}): EnvironmentReport {
+    const isDefaultCall = Object.keys(opts).length === 0;
+    if (isDefaultCall && _cached !== null) return _cached;
+    const hosts = detectHosts(opts);
+    const { auth, keys } = detectAuth(opts);
+    const report: EnvironmentReport = { hosts, auth, keys };
+    if (isDefaultCall) _cached = report;
+    return report;
+}
+
+/** Drop the per-process memo. Tests only. */
+export function resetEnvironmentCache(): void {
+    _cached = null;
+}

package/src/scripts/_lib/package_root.ts

@@ -0,0 +1,72 @@
+/**
+ * Layout-independent package-root resolution for the `_cli` delegate commands.
+ *
+ * `src/scripts/_cli/*.ts` sits three levels below the package root, so every
+ * delegate command derived the root with three hard-coded parent hops. Then the
+ * delegate precompile (`fa51c5a54`) started bundling those same modules into
+ * `dist/cli-delegate/*.js` — **two** levels below the root. Fixed hop counts are
+ * correct in exactly one of the two layouts, and nothing failed loudly: three
+ * hops from the bundle lands on `<pkg>/..`, which for a scoped install is
+ * `node_modules/@event4u`. `conformance` then reported `dist/router.json` and
+ * `src/scripts/hook_manifest.yaml` as missing — files that ship fine — and the
+ * 9.11.0 release PR's `tarball E2E` went red on both Node majors.
+ *
+ * The fix is to stop counting hops. Anchor on the marker that actually defines
+ * the root: the `package.json` whose `name` is this package. That answer holds
+ * for the source tree, for any bundle depth, for npm-global, npx, and
+ * vendor/bin symlink invocations — and it keeps holding if either directory
+ * ever moves.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/** `name` in this package's own package.json — the root marker. */
+export const PACKAGE_NAME = '@event4u/agent-config';
+
+/**
+ * Bound on the upward walk. Deep enough for any real install path, finite so a
+ * malformed start value can never spin.
+ */
+const MAX_ASCENT = 16;
+
+/**
+ * Absolute package root for the module at `fromUrlOrPath` (pass
+ * `import.meta.url`).
+ *
+ * Walks up looking for the package.json whose `name` is {@link PACKAGE_NAME}.
+ * A consumer's own package.json encountered on the way is skipped by that name
+ * check, so an install nested under another project resolves correctly.
+ *
+ * `legacyHops` is the pre-existing hop count for the *source* layout and is
+ * used only if no marker is found. Falling back beats throwing during CLI
+ * startup: a wrong path yields one actionable "missing file" message, while an
+ * exception takes down every command in the delegate.
+ */
+export function resolvePackageRoot(fromUrlOrPath: string, legacyHops = 3): string {
+    const start = fromUrlOrPath.startsWith('file:') ? fileURLToPath(fromUrlOrPath) : fromUrlOrPath;
+    const startDir = path.dirname(start);
+
+    let dir = startDir;
+    for (let i = 0; i < MAX_ASCENT; i++) {
+        const manifest = path.join(dir, 'package.json');
+        if (fs.existsSync(manifest)) {
+            try {
+                const parsed = JSON.parse(fs.readFileSync(manifest, 'utf8')) as { name?: unknown };
+                if (parsed.name === PACKAGE_NAME) {
+                    return dir;
+                }
+            } catch {
+                // Unreadable / unparseable manifest — not our marker; keep ascending.
+            }
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir) {
+            break; // filesystem root
+        }
+        dir = parent;
+    }
+
+    return path.resolve(startDir, ...(Array.from({ length: legacyHops }, () => '..') as string[]));
+}