@event4u/agent-config 9.9.0 → 9.11.0

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/managed_agents_folder.ts

@@ -0,0 +1,181 @@
+/**
+ * Detect whether a directory is a project whose `agents/` folder is managed
+ * by this package.
+ *
+ * `.agent-settings.yml` resolution and settings-cascade routing already have
+ * a project-root walker (`find_project_root_with_anchor` in
+ * `_lib/agent_settings.ts`), but that walker answers a different question —
+ * "where does the settings cascade start reading from" — and its `agents/`
+ * check exists only to pick a boundary anchor for that walk (its marker list
+ * mixes package-source-repo-only paths, e.g. `settings/.ai-council.yml`, with
+ * consumer-only paths). It also treats a bare `.git` anywhere in the ancestor
+ * chain as "a project was found", which is the right answer for "where do
+ * settings live" but the wrong answer for "is this THIS package's managed
+ * `agents/` folder" — a third-party repo with an unrelated `agents/`
+ * directory and its own `.git` would resolve to a root there too. No
+ * existing helper answers the narrower managed/unmanaged/not-a-project
+ * question this module exists for.
+ *
+ * Contract — pure, read-only, tolerant:
+ *
+ * - Never writes, never mutates, never touches the network.
+ * - Operates on the given `start` directory directly — it does not walk
+ *   ancestors looking for a project root (that is the caller's job, e.g.
+ *   via `find_project_root` when the caller only has a subdirectory).
+ *   Keeping this helper non-walking keeps it a distinct primitive from the
+ *   settings-root walker above rather than a second, subtly different copy
+ *   of the same walk.
+ * - Silently tolerant of a missing/unreadable `start` — every check falls
+ *   through to `false`, which resolves to `'not-a-project'`.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { SECTION_HEADER as _MANAGED_GITIGNORE_HEADER } from '../sync_gitignore.js';
+
+/**
+ * Three-state answer — never a boolean, because "no `agents/` folder" and
+ * "no project at all" route differently downstream (an unmanaged repo is a
+ * candidate for adoption; a bare directory outside any repo is not a
+ * project the P-routing question even applies to).
+ */
+export type ManagedAgentsFolderStatus = 'managed' | 'unmanaged' | 'not-a-project';
+
+/**
+ * Detection predicate — chosen after inspecting what the installer actually
+ * writes into a consumer project (verified against source, not invented):
+ *
+ *   is_project   := <start>/.git exists (file or directory — worktrees and
+ *                    submodules use a `.git` file, not a directory).
+ *   has_agents   := <start>/agents is a directory.
+ *   has_marker   := ANY of —
+ *     (a) <start>/.gitignore contains the managed-block header line
+ *         `# event4u/agent-config` (`SECTION_HEADER` in
+ *         `sync_gitignore.ts`) — installed by `refresh --project` /
+ *         `sync:gitignore`. Strongest signal: the literal package name, so
+ *         a third-party repo carries it only if it also runs this package.
+ *     (b) <start>/agents/overrides/ is a directory — scaffolded by
+ *         `install.ts` for every consumer project (the "guaranteed
+ *         minimal-consumer surface", ADR-020).
+ *     (c) a resolvable `.agent-settings.yml` exists — canonical
+ *         `<start>/agents/settings/.agent-settings.yml`, or the legacy
+ *         `<start>/.agent-settings.yml` fallback (see
+ *         `project_settings_path` in `_lib/agent_settings.ts`).
+ *
+ *   status := has_agents && has_marker  → 'managed'
+ *             is_project (else)         → 'unmanaged'
+ *             otherwise                 → 'not-a-project'
+ *
+ * Rejected alternatives:
+ *
+ *   - `agents/` existence alone (no marker). Rejected: this is exactly the
+ *     false positive the roadmap phase calls out — an unrelated multi-agent
+ *     framework repo, or any project that happens to name a directory
+ *     `agents/`, would read as managed with zero package-specific evidence.
+ *   - Reusing `find_project_root_with_anchor`'s `_AGENTS_DIR_MARKERS` list
+ *     verbatim (`roadmaps`, `settings/.ai-council.yml`,
+ *     `roadmaps-progress.md`, `overrides`). Rejected: two of those four
+ *     (`settings/.ai-council.yml`, `roadmaps-progress.md`) are `pkg`-scope
+ *     only per `docs/contracts/agents-layout.md`'s consumer-slim-profile
+ *     table — they never appear in an installed consumer project, so
+ *     requiring "any one" would under-detect nothing (they're just dead
+ *     weight for the consumer case) but reusing the *function* would also
+ *     inherit its `.git`-anchor and `.agent-settings.yml`-layer-fallback
+ *     semantics, which answer "where is the settings root" rather than
+ *     "is `agents/` managed" (see module docblock).
+ *   - `agents/roadmaps/` as a marker. Rejected: it is listed as "Optional"
+ *     even in the consumer-slim profile — a managed project with zero
+ *     roadmaps yet (the common case right after install) would false-
+ *     negative.
+ */
+function _existsAt(dir: string, ...segments: readonly string[]): boolean {
+    try {
+        fs.statSync(path.join(dir, ...segments));
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+function _isDirAt(dir: string, ...segments: readonly string[]): boolean {
+    try {
+        return fs.statSync(path.join(dir, ...segments)).isDirectory();
+    } catch {
+        return false;
+    }
+}
+
+function _isFileAt(dir: string, ...segments: readonly string[]): boolean {
+    try {
+        return fs.statSync(path.join(dir, ...segments)).isFile();
+    } catch {
+        return false;
+    }
+}
+
+/** `true` when `start` sits at the root of a git repository (or worktree). */
+function _isGitProject(start: string): boolean {
+    // `.git` is a directory in a normal clone, a file in a worktree or
+    // submodule checkout — `statSync` (not `lstatSync`) is deliberate so a
+    // broken symlink named `.git` does not count as present.
+    return _existsAt(start, '.git');
+}
+
+/** `true` when `<start>/.gitignore` carries the managed-block header line. */
+function _hasManagedGitignoreBlock(start: string): boolean {
+    if (!_isFileAt(start, '.gitignore')) {
+        return false;
+    }
+    let text: string;
+    try {
+        text = fs.readFileSync(path.join(start, '.gitignore'), 'utf-8');
+    } catch {
+        return false;
+    }
+    return text
+        .split(/\r\n|\r|\n/)
+        .some((line) => line.trim() === _MANAGED_GITIGNORE_HEADER);
+}
+
+/** `true` when `<start>/agents/overrides` exists as a directory. */
+function _hasOverridesDir(start: string): boolean {
+    return _isDirAt(start, 'agents', 'overrides');
+}
+
+/**
+ * `true` when a resolvable `.agent-settings.yml` exists — canonical
+ * `agents/settings/.agent-settings.yml`, or the legacy repo-root
+ * `.agent-settings.yml`.
+ */
+function _hasResolvableAgentSettings(start: string): boolean {
+    return (
+        _isFileAt(start, 'agents', 'settings', '.agent-settings.yml') ||
+        _isFileAt(start, '.agent-settings.yml')
+    );
+}
+
+/**
+ * Classify `start` as `'managed'` (an `agents/` folder this package
+ * installed and can safely write project facts into), `'unmanaged'` (a real
+ * project — has a `.git` — with no such folder, or an `agents/` folder this
+ * package did not install), or `'not-a-project'` (no `.git` at `start` at
+ * all — e.g. a bare directory outside any repo).
+ *
+ * Read-only. Does not walk ancestors — `start` is checked directly; pass a
+ * project root (e.g. from `find_project_root`) when the caller only has a
+ * subdirectory.
+ */
+export function detect_managed_agents_folder(start: string): ManagedAgentsFolderStatus {
+    if (!_isGitProject(start)) {
+        return 'not-a-project';
+    }
+    const hasAgentsDir = _isDirAt(start, 'agents');
+    const hasMarker =
+        _hasManagedGitignoreBlock(start) ||
+        _hasOverridesDir(start) ||
+        _hasResolvableAgentSettings(start);
+    if (hasAgentsDir && hasMarker) {
+        return 'managed';
+    }
+    return 'unmanaged';
+}

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[]));
+}