@event4u/agent-config 9.10.0 → 9.11.0

package/src/scripts/_cli/cmd_converge.ts

@@ -39,6 +39,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import * as YAML from 'yaml';
 
 import * as user_global_paths from '../_lib/user_global_paths.js';
+import { resolvePackageRoot } from '../_lib/package_root.js';
 
 type Dict = Record<string, unknown>;
 
@@ -67,7 +68,7 @@ const _HERE = fileURLToPath(import.meta.url);
 
 /** Resolve the @event4u/agent-config package root (this repo). */
 function _package_root(): string {
-    return path.resolve(path.dirname(_HERE), '..', '..', '..');
+    return resolvePackageRoot(import.meta.url);
 }
 
 const SETTINGS_FILENAME = 'agent-settings.yml';

package/src/scripts/_cli/cmd_doctor.ts

@@ -102,7 +102,22 @@ import {
 } from '../_lib/agent_settings.js';
 import * as ai_council_clients from '../ai_council/clients.js';
 import * as ai_council_config from '../ai_council/config.js';
+import {
+    PROVIDER_CLI_META,
+    codexHome,
+    detectEnvironment,
+} from '../_lib/environment_detector.js';
+import {
+    absentCouncilFacts,
+    buildDetectionReport,
+    detectionJson,
+    renderDetectionLines,
+    type CouncilFacts,
+    type CouncilMemberFacts,
+    type DetectionReport,
+} from './detection_report.js';
 import { review_gate_doctor_signal } from '../ai_team/review_gate.js';
+import { resolvePackageRoot } from '../_lib/package_root.js';
 import {
     LEGACY_ALL,
     excludedRuleBasenames,
@@ -758,6 +773,7 @@ const CHECK_IDS = [
     'humanizer-runtime',
     'tier-usage-readiness',
     'council-cli',
+    'detection',
     'team',
     'unsupported-combos',
     'wizard-state',
@@ -784,6 +800,7 @@ const GLOBAL_CHECK_IDS: ReadonlySet<string> = new Set([
     'humanizer-runtime',
     'tier-usage-readiness',
     'council-cli',
+    'detection',
     'team',
     'wizard-state',
     'settings-review-pending',
@@ -994,7 +1011,7 @@ function _check_manifest_integrity(manifest: Dict): Dict {
 /** Resolve the @event4u/agent-config package root (this repo). */
 function _package_root(): string {
     // cmd_doctor lives at src/scripts/_cli/cmd_doctor.{py,ts}; parents[3] = repo.
-    return path.resolve(path.dirname(_HERE), '..', '..', '..');
+    return resolvePackageRoot(import.meta.url);
 }
 
 /** Read `version` from this package's package.json; null on error. */
@@ -2055,16 +2072,13 @@ function osErrorStr(exc: unknown): string {
 }
 
 /**
- * Provider → (default binary, billable flag). Mirrors the `CliClient`
- * subclass attributes without importing them at module load time.
+ * Provider → (default binary, community-wrapper flag). Canonical definition
+ * lives in `_lib/environment_detector.ts` so this check and the detection
+ * report cannot drift on the billing-relevant boolean; aliased here to keep
+ * the existing call sites unchanged.
  */
-const _CLI_PROVIDER_META: Record<string, [string, boolean]> = {
-    anthropic: ['claude', false],
-    openai: ['codex', false],
-    gemini: ['gemini', false],
-    xai: ['grok', true],
-    perplexity: ['perplexity', true],
-};
+const _CLI_PROVIDER_META: Readonly<Record<string, readonly [string, boolean]>> =
+    PROVIDER_CLI_META;
 
 function _check_council_cli(project_root: string): Dict {
     // Python wraps the council-module import in a try/except ImportError so a
@@ -2207,11 +2221,12 @@ function pyFloat(value: number): string {
 
 /**
  * Codex CLI home — `CODEX_HOME` env override (the codex CLI's own
- * convention), else `~/.codex`.
+ * convention), else `~/.codex`. Single definition in
+ * `_lib/environment_detector.ts` so the detection report and this check probe
+ * the same path; aliased here to keep the existing call sites unchanged.
  */
 function _codex_home(): string {
-    const env = (process.env['CODEX_HOME'] ?? '').trim();
-    return env !== '' ? env : path.join(os.homedir(), '.codex');
+    return codexHome();
 }
 
 /**
@@ -2368,6 +2383,162 @@ function _read_ai_team_block(project_root: string): Dict {
  * check reports ok ("team mode not configured (default-off)"); WARN fires
  * only on failing sub-signals or inconsistent half-configured states.
  */
+// ---------------------------------------------------------------------------
+// detection check (road-to-zero-ceremony-detection Phases 3 + 4)
+// ---------------------------------------------------------------------------
+
+/** Per-process memo so the check row and the rendered section agree exactly. */
+let _detection_memo: { root: string; report: DetectionReport } | null = null;
+
+/**
+ * Read the council-config facts the detection rows need. Never throws — an
+ * absent or unreadable config degrades to "no config", which the report renders
+ * as a fix rather than a failure.
+ */
+function _read_council_facts(project_root: string): CouncilFacts {
+    const { load_council_config, resolve_config_path } = ai_council_config;
+    const config_path = String(resolve_config_path(project_root));
+    if (!pathExists(config_path)) {
+        return absentCouncilFacts(config_path);
+    }
+    let cfg: ai_council_config.CouncilConfig;
+    try {
+        cfg = load_council_config(config_path);
+    } catch {
+        // An invalid config is reported by the `council-cli` check, which owns
+        // that problem; here it simply means no facts are derivable.
+        return absentCouncilFacts(config_path);
+    }
+    const members: Record<string, CouncilMemberFacts> = {};
+    for (const [name, m] of cfg.members) {
+        members[name] = {
+            enabled: m.enabled,
+            mode: m.mode,
+            binary: m.binary,
+            apiKeyRef: m.api_key_ref,
+        };
+    }
+    const cliCaps: Record<string, number> = {};
+    for (const [provider, cap] of cfg.cli_call_budget.max_calls_per_day) {
+        cliCaps[provider] = cap;
+    }
+    return {
+        configPath: config_path,
+        configPresent: true,
+        enabled: cfg.enabled,
+        defaultsMode: cfg.defaults.mode,
+        members,
+        cliCaps,
+        costBudgetMaxUsd: cfg.cost_budget.max_total_usd,
+    };
+}
+
+/** Build (once per process, per root) the detection report. */
+function _detection_report(project_root: string): DetectionReport {
+    if (_detection_memo !== null && _detection_memo.root === project_root) {
+        return _detection_memo.report;
+    }
+    const council = _read_council_facts(project_root);
+    let used: Record<string, number> = {};
+    try {
+        const counts = ai_council_clients.load_cli_call_counts();
+        for (const provider of Object.keys(council.cliCaps)) {
+            used[provider] = Number((counts as Dict)[provider] ?? 0);
+        }
+    } catch {
+        used = {};
+    }
+    const report = buildDetectionReport({
+        environment: detectEnvironment(),
+        council,
+        cliCallsUsed: used,
+    });
+    _detection_memo = { root: project_root, report };
+    return report;
+}
+
+/** Test seam — drop the memo so a fixture root is not served a stale report. */
+function _reset_detection_memo(): void {
+    _detection_memo = null;
+}
+
+/**
+ * `detection` health check — what this machine can do, and what it is allowed
+ * to do, as two separate facts.
+ *
+ * Reports per provider: detected · authenticated · auth source · billing class
+ * · enabled-in-config, plus the transport `auto` would pick and a one-line fix
+ * for every unusable capability. All rows come from the read-only, spend-free
+ * detector; nothing here makes a provider call.
+ *
+ * Status model — a recorded consent decision is NOT a defect:
+ *
+ * - no council config, or council disabled → `ok` ("not configured"), with the
+ *   fix. Absent feature ≠ broken feature (same stance as the `team` check).
+ * - detected but `enabled: false` → `ok`. That flag is a deliberate spend gate;
+ *   warning on it would train the user to silence their own consent record.
+ * - enabled to spend but no transport resolves → `warn`. That IS broken: the
+ *   member is permitted to run and cannot.
+ */
+function _check_detection(project_root: string): Dict {
+    const report = _detection_report(project_root);
+    const detected = report.providers.filter((r) => r.detected);
+    const hosts_installed = report.hosts.filter((h) => h.installed).length;
+
+    if (!report.council_config_present) {
+        return {
+            id: 'detection',
+            status: 'ok',
+            message:
+                `${hosts_installed} host(s) · ${detected.length} provider(s) detected · ` +
+                'council not configured (default-off)',
+            remedy: report.providers[0]?.fix ?? `create ${report.council_config_path}`,
+        };
+    }
+
+    if (!report.council_enabled) {
+        return {
+            id: 'detection',
+            status: 'ok',
+            message:
+                `${hosts_installed} host(s) · ${detected.length} provider(s) detected · ` +
+                'council disabled (default-off)',
+            remedy: `set \`enabled: true\` in ${report.council_config_path}`,
+        };
+    }
+
+    const broken = report.providers.filter((r) => r.enabledInConfig && !r.available);
+    const spending = report.providers.filter((r) => r.enabledInConfig && r.available);
+    const unpermitted = detected.filter((r) => !r.enabledInConfig);
+
+    const summary =
+        `${hosts_installed} host(s) · ${spending.length} member(s) ready ` +
+        `(${spending.map((r) => `${r.provider}→${r.transport}/${r.billing}`).join(', ') || 'none'})` +
+        (unpermitted.length === 0
+            ? ''
+            : ` · ${unpermitted.length} detected but not allowed to spend: ` +
+              unpermitted.map((r) => r.provider).join(', '));
+
+    if (broken.length > 0) {
+        return {
+            id: 'detection',
+            status: 'warn',
+            message: `${summary} · ${broken.length} enabled member(s) have no transport`,
+            remedy: broken.map((r) => `${r.provider}: ${r.fix}`).join(' · '),
+        };
+    }
+
+    return {
+        id: 'detection',
+        status: 'ok',
+        message: summary,
+        remedy:
+            unpermitted.length === 0
+                ? `run \`agent-config doctor --check detection\` for the full table`
+                : unpermitted.map((r) => r.fix).join(' · '),
+    };
+}
+
 function _check_team(project_root: string): Dict {
     const ai_team = _read_ai_team_block(project_root);
     const enabled = _settings_flag(ai_team['enabled']);
@@ -2819,6 +2990,7 @@ function _run_checks(
         'humanizer-runtime': () => _check_humanizer_runtime(),
         'tier-usage-readiness': () => _check_tier_usage_readiness(project_root),
         'council-cli': () => _check_council_cli(project_root),
+        'detection': () => _check_detection(project_root),
         team: () => _check_team(project_root),
         'unsupported-combos': () => _check_unsupported_combos(manifest),
         'wizard-state': _check_wizard_state,
@@ -2895,6 +3067,7 @@ function _run_checks_no_manifest(
         'humanizer-runtime': () => _check_humanizer_runtime(),
         'tier-usage-readiness': () => _check_tier_usage_readiness(project_root),
         'council-cli': () => _check_council_cli(project_root),
+        'detection': () => _check_detection(project_root),
         team: () => _check_team(project_root),
         'unsupported-combos': () => _skipped_manifest_check('unsupported-combos'),
         'wizard-state': _check_wizard_state,
@@ -2945,8 +3118,10 @@ function _run_no_manifest(
             );
         }
         _emit_checks_text(checks);
+        _emit_detection_text(project_root, checks);
     } else {
         _emit_checks_text(checks);
+        _emit_detection_text(project_root, checks);
     }
 
     if (opts.check !== null) {
@@ -2983,6 +3158,12 @@ function _emit_json(
     }
     if (checks !== null) {
         payload['checks'] = checks;
+        // The detection section rides along whenever checks ran, so the agent /
+        // GUI contract carries the full provider → transport → billing table
+        // and not just the one-line check row.
+        if (checks.some((c) => c['id'] === 'detection')) {
+            payload['detection'] = detectionJson(_detection_report(project_root));
+        }
     }
     print(_jsonDumpsIndentAscii(payload, 2));
 }
@@ -3002,6 +3183,21 @@ function _emit_checks_text(checks: Dict[]): void {
     print('');
 }
 
+/**
+ * The detection section in text mode. Rendered from the same report the
+ * `detection` check row and the `--json` payload use, so the three cannot
+ * disagree about which members spend money.
+ */
+function _emit_detection_text(project_root: string, checks: Dict[]): void {
+    if (!checks.some((c) => c['id'] === 'detection')) {
+        return;
+    }
+    for (const line of renderDetectionLines(_detection_report(project_root))) {
+        print(line);
+    }
+    print('');
+}
+
 function _emit_text(
     project_root: string,
     missing: Dict[],
@@ -3304,6 +3500,7 @@ function main(argv: string[] | null = null): number {
             print(`  📍  project_root: ${project_root} (origin: ${origin})`);
         }
         _emit_checks_text(checks);
+        _emit_detection_text(project_root, checks);
         if (opts.check === null) {
             _emit_text(project_root, missing, modified, foreign, tag_drift);
         }
@@ -3389,6 +3586,10 @@ export {
     _check_mcp_beta_readiness,
     _check_tier_usage_readiness,
     _check_council_cli,
+    _check_detection,
+    _detection_report,
+    _read_council_facts,
+    _reset_detection_memo,
     _check_team,
     _check_unsupported_combos,
     _check_wizard_state,

package/src/scripts/_cli/cmd_export.ts

@@ -44,6 +44,7 @@ import * as os from 'node:os';
 import * as path from 'node:path';
 import * as crypto from 'node:crypto';
 import { fileURLToPath, pathToFileURL } from 'node:url';
+import { resolvePackageRoot } from '../_lib/package_root.js';
 
 import {
     AIDER_MARKER,
@@ -57,7 +58,7 @@ import {
     ZED_MARKER,
 } from '../install.js';
 
-const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
+const PACKAGE_ROOT = resolvePackageRoot(import.meta.url);
 const TEMPLATES_DIR = path.join(PACKAGE_ROOT, 'dist/agent-src', 'templates');
 
 // ---------------------------------------------------------------------------

package/src/scripts/_cli/cmd_fleet.ts

@@ -32,9 +32,10 @@ import * as YAML from 'yaml';
 
 import { runPreflight, hasBlockingFinding, type PreflightFinding } from '../../install/preflight.js';
 import type { ConflictPolicy } from '../../install/types.js';
+import { resolvePackageRoot } from '../_lib/package_root.js';
 
 const _HERE = fileURLToPath(import.meta.url);
-const PACKAGE_ROOT = path.resolve(path.dirname(_HERE), '..', '..', '..');
+const PACKAGE_ROOT = resolvePackageRoot(import.meta.url);
 
 /** One fleet target, parsed from `fleet.yaml`. */
 export interface FleetRepo {

package/src/scripts/_cli/cmd_migrate.ts

@@ -75,6 +75,7 @@ import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { resolve_project_root } from '../_lib/agent_settings.js';
+import { resolvePackageRoot } from '../_lib/package_root.js';
 // NOTE: the v0→v1 migrator is NOT statically imported. It lives in the
 // consumer-shipped work_engine template, which ships as `.ts` (run via tsx),
 // while this CLI is compiled to `dist/cli/*.js` and run under plain `node` in
@@ -521,7 +522,7 @@ function _load_state_migrator(): StateMigrator | null {
     // Locate the shipped v0→v1 migration driver (`.ts`). Prefer the shipped
     // `dist/` tree; fall back to the dev `src/` tree. A stripped install with
     // no engine yields `null` (Python ImportError parity).
-    const pkg_root = path.resolve(_HERE_DIR, '..', '..', '..');
+    const pkg_root = resolvePackageRoot(import.meta.url);
     const rel = path.join(
         'agent-src', 'templates', 'scripts', 'work_engine', 'migration', 'v0_to_v1.ts',
     );

package/src/scripts/_cli/cmd_preflight.ts

@@ -28,11 +28,12 @@ import {
 } from '../../install/preflight.js';
 import { GLOBAL_DEPLOY_SOURCES, expandWizardSources } from '../../install/wizard-plan.js';
 import type { ConflictPolicy } from '../../install/types.js';
+import { resolvePackageRoot } from '../_lib/package_root.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 
 /** Package root — three levels above `src/scripts/_cli/`. */
-const PACKAGE_ROOT = path.resolve(path.dirname(_HERE), '..', '..', '..');
+const PACKAGE_ROOT = resolvePackageRoot(import.meta.url);
 
 const USAGE =
     'usage: cmd_preflight [-h] [--tools a,b,...] [--target DIR] [--json]\n';

package/src/scripts/_cli/cmd_refresh.ts

@@ -69,8 +69,9 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import * as cli_wrapper from '../_lib/cli_wrapper.js';
 import * as sync_gitignore from '../sync_gitignore.js';
 import * as sync_gitattributes from '../sync_gitattributes.js';
+import { resolvePackageRoot } from '../_lib/package_root.js';
 
-const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
+const PACKAGE_ROOT = resolvePackageRoot(import.meta.url);
 
 // ---------------------------------------------------------------------------
 // Parity primitives (ADR-200).

package/src/scripts/_cli/cmd_update.ts

@@ -67,6 +67,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import * as installed_lock from '../_lib/installed_lock.js';
 import * as update_check from '../_lib/update_check.js';
+import { resolvePackageRoot } from '../_lib/package_root.js';
 import {
     DEFAULT_PROJECT_FILE,
     LOCAL_PROJECT_FILE,
@@ -550,7 +551,7 @@ function _refresh_global_lockfile(version: string, out: OutSink): void {
 
 /** Read `version` from the package's own `package.json`. */
 function _detect_installed_version(): string {
-    const pkg_json = path.join(path.resolve(_HERE_DIR, '..', '..', '..'), 'package.json');
+    const pkg_json = path.join(resolvePackageRoot(import.meta.url), 'package.json');
     try {
         const data = JSON.parse(fs.readFileSync(pkg_json, { encoding: 'utf-8' })) as Record<
             string,

package/src/scripts/_cli/cmd_upgrade.ts

@@ -93,9 +93,10 @@ import * as claude_plugin from '../_lib/claude_plugin.js';
 import { event4u_root, write_target } from '../_lib/user_global_paths.js';
 import { project_settings_path } from '../_lib/agent_settings.js';
 import { _is_source_repo } from './cmd_refresh.js';
+import { resolvePackageRoot } from '../_lib/package_root.js';
 
 const PACKAGE_NAME = '@event4u/agent-config';
-const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
+const PACKAGE_ROOT = resolvePackageRoot(import.meta.url);
 
 // ---------------------------------------------------------------------------
 // Parity primitives (ADR-200).

package/src/scripts/_cli/cmd_versions.ts

@@ -47,6 +47,7 @@ import { spawnSync } from 'node:child_process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { project_settings_path, resolve_project_root } from '../_lib/agent_settings.js';
+import { resolvePackageRoot } from '../_lib/package_root.js';
 
 const PACKAGE_NAME = '@event4u/agent-config';
 
@@ -171,7 +172,7 @@ function _project_root(): string {
 /** Return `version` from the local `package.json`, or `""` if absent. */
 function _local_package_version(): string {
     const candidates = [
-        path.join(path.resolve(_HERE_DIR, '..', '..', '..'), 'package.json'),
+        path.join(resolvePackageRoot(import.meta.url), 'package.json'),
         path.join(_project_root(), 'package.json'),
     ];
     for (const p of candidates) {