@event4u/agent-config 9.10.0 → 9.12.0

package/src/install/ruleInScope.ts

@@ -0,0 +1,133 @@
+/**
+ * The rule-scoping predicate — the ONE decision both pipelines consume.
+ *
+ * ## Why this module exists (and must stay side-effect-free)
+ *
+ * `rule_in_scope` used to live in `src/scripts/condense.ts`, and
+ * `src/install/rule_scope.ts` imported it from there deliberately, so install
+ * semantics could never drift from projection semantics. That intent is right;
+ * the location was not.
+ *
+ * `condense.ts` is maintainer-only CLI tooling and ends in a module-level
+ * self-invoke:
+ *
+ *     const isMain = _isCliEntry();
+ *     if (isMain) { process.exit(main()); }
+ *
+ * `_isCliEntry()` compares `import.meta.url` against `process.argv[1]`. That is
+ * correct for a file run directly — but when esbuild BUNDLES the module into
+ * `dist/install/install.mjs`, `import.meta.url` becomes the bundle's own URL,
+ * which *is* `argv[1]` when a consumer runs `node dist/install/install.mjs`.
+ * The guard then fires inside the installer, `condense.main()` runs, finds no
+ * maintainer source tree in a consumer checkout, prints "No source directory
+ * found" and calls `process.exit(1)` — killing the install.
+ *
+ * That is not hypothetical: it reached CI on all four
+ * `smoke-public-install` legs the moment the installer began importing
+ * `rule_scope.ts` (road-to-consistent-rule-scoping, 2026-07-31).
+ *
+ * So the predicate lives here instead: **no I/O at module load, no CLI entry,
+ * no `process.exit`, and nothing that assumes a maintainer source tree.**
+ * `condense.ts` re-exports it for its four in-repo consumers; the install path
+ * imports it directly and never pulls the projection pipeline along.
+ *
+ * Lives under `src/install/` rather than `src/shared/` because it reads the file
+ * it classifies: an ESLint boundary keeps `src/shared/**` free of Node built-ins,
+ * and the install layer is where credentialled filesystem work already belongs.
+ *
+ * Keep it that way. Anything added to this file ships inside the consumer
+ * installer bundle.
+ */
+
+import * as fs from 'node:fs';
+
+import * as YAML from 'yaml';
+
+/** `yaml.safe_load` semantics: parse failure and `undefined` both → `null`. */
+function parseYaml(text: string): unknown {
+    try {
+        const data = YAML.parse(text, { version: '1.1' });
+        return data === undefined ? null : data;
+    } catch {
+        return null;
+    }
+}
+
+/** Python `str.strip()` — whitespace from both ends, Unicode-aware. */
+function strip(s: string): string {
+    return s.replace(/^\s+/u, '').replace(/\s+$/u, '');
+}
+
+/** Python `str.lstrip("\n")` — leading newlines only. */
+function lstripNewlines(s: string): string {
+    return s.replace(/^\n+/, '');
+}
+
+/**
+ * Split `---`-delimited frontmatter from the body.
+ *
+ * Returns `[{}, content]` for anything that is not well-formed frontmatter —
+ * an absent block, an unterminated block, or a scalar/sequence document. The
+ * caller then sees an untagged artefact, which every axis below fails safe on.
+ */
+export function parseFrontmatter(content: string): [Record<string, unknown>, string] {
+    if (!content.startsWith('---')) {
+        return [{}, content];
+    }
+    const end = content.indexOf('\n---', 3);
+    if (end === -1) {
+        return [{}, content];
+    }
+    const raw = strip(content.slice(3, end));
+    const body = lstripNewlines(content.slice(end + 4));
+    let meta: unknown = parseYaml(raw);
+    if (meta === null || meta === undefined) {
+        meta = {};
+    }
+    if (typeof meta === 'object' && meta !== null && !Array.isArray(meta)) {
+        return [meta as Record<string, unknown>, body];
+    }
+    return [{}, body];
+}
+
+/**
+ * Does the rule at `source_path` project / install under the given scope?
+ *
+ * Three independent axes — `workspaces`, `packs`, `roles`. A `null` axis means
+ * "unset", i.e. that axis does not filter. Two fail-safe rules make the
+ * predicate over-ship rather than under-ship:
+ *
+ * - a KERNEL rule (`type: always` / `alwaysApply: true`) always ships;
+ * - an artefact carrying NO tags on a configured axis ships anyway — an
+ *   untagged rule is unclassified, not excluded.
+ *
+ * Reads the file. Never throws for a missing frontmatter block; a genuinely
+ * unreadable path is the caller's problem (both call sites pre-check).
+ */
+export function rule_in_scope(
+    source_path: string,
+    scope: readonly string[] | null,
+    pack_scope: readonly string[] | null = null,
+    role_scope: readonly string[] | null = null,
+): boolean {
+    if (scope === null && pack_scope === null && role_scope === null) {
+        return true;
+    }
+    const [meta] = parseFrontmatter(fs.readFileSync(source_path, 'utf-8'));
+    if (meta['type'] === 'always' || meta['alwaysApply'] === true) {
+        return true; // kernel always projects
+    }
+    const axis = (key: string, configured: readonly string[] | null): boolean => {
+        if (configured === null) {
+            return true;
+        }
+        const values = Array.isArray(meta[key])
+            ? (meta[key] as unknown[]).map((w) => String(w))
+            : [];
+        if (values.length === 0) {
+            return true; // untagged → fail safe: ship it
+        }
+        return values.some((v) => configured.includes(v));
+    };
+    return axis('workspaces', scope) && axis('packs', pack_scope) && axis('roles', role_scope);
+}

package/src/install/rule_scope.ts

@@ -1,8 +1,12 @@
 /**
- * Install-time rule scoping — Pipeline B of consumer-scoped rule projection
+ * Install-time rule scoping for the consumer install
  * (road-to-request-scoped-rule-load Phase 1b).
  *
- * The projection filter (`rule_in_scope`, condense.ts) covered only the
+ * Naming: this is the CONSUMER INSTALL path, not `docs/architecture.md`'s
+ * Pipeline B (which is the `.augment/` projection). Earlier drafts called it
+ * "Pipeline B" and collided with that name; use "the consumer install" here.
+ *
+ * The projection filter (`rule_in_scope`, now `shared/ruleInScope.ts`) covered only the
  * maintainer projection; the consumer install pipeline shipped rules
  * unfiltered (dead `EXCLUDE_RULES` in install.sh; no exclude at all on the
  * global payload). This module is the ONE scoping surface both install
@@ -28,7 +32,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 
-import { rule_in_scope } from '../scripts/condense.js';
+import { rule_in_scope } from './ruleInScope.js';
 
 /**
  * Rules excluded from EVERY consumer install path regardless of scope —

package/src/install/toolDetection.ts

@@ -71,6 +71,44 @@ export function knownToolIds(): readonly string[] {
     return Object.keys(TOOL_SIGNALS);
 }
 
+/**
+ * Executable names declared for `id` on `$PATH`, in table order. Empty for
+ * tools detected only by a config dir / app bundle (and for the two
+ * signal-less ids). Exposed so callers that need the resolved *path* (not
+ * just a boolean) can reuse this table instead of restating the binary names.
+ */
+export function toolBinaries(id: string): readonly string[] {
+    return TOOL_SIGNALS[id]?.bins ?? [];
+}
+
+/**
+ * First declared binary for `id` that resolves on `$PATH`, or `null`. This is
+ * the path-returning twin of `detectInstalledTools`, which reports presence as
+ * a boolean across all three signal kinds — a tool can be "installed" (config
+ * dir present) while this returns `null` (no executable on `$PATH`).
+ */
+export function resolveToolBinary(id: string, pathEnv?: string): string | null {
+    const env = pathEnv ?? process.env['PATH'] ?? '';
+    for (const bin of toolBinaries(id)) {
+        const resolved = resolveBinaryPath(bin, env);
+        if (resolved !== null) return resolved;
+    }
+    return null;
+}
+
+/** Absolute path of `name` on `pathEnv`, or `null`. Mirrors `binOnPath`'s probe order. */
+function resolveBinaryPath(name: string, pathEnv: string): string | null {
+    if (pathEnv.length === 0) return null;
+    for (const dir of pathEnv.split(delimiter)) {
+        if (dir.length === 0) continue;
+        for (const candidate of [name, `${name}.exe`, `${name}.cmd`]) {
+            const full = join(dir, candidate);
+            if (existsSync(full)) return full;
+        }
+    }
+    return null;
+}
+
 /**
  * Is an executable named `name` resolvable on `$PATH`? Exported for one-off
  * presence checks (e.g. `rtk` on the Editor-and-tooling step). Defaults to
@@ -81,14 +119,7 @@ export function isBinaryOnPath(name: string, pathEnv?: string): boolean {
 }
 
 function binOnPath(name: string, pathEnv: string): boolean {
-    if (pathEnv.length === 0) return false;
-    for (const dir of pathEnv.split(delimiter)) {
-        if (dir.length === 0) continue;
-        if (existsSync(join(dir, name))) return true;
-        // Windows-style executables.
-        if (existsSync(join(dir, `${name}.exe`)) || existsSync(join(dir, `${name}.cmd`))) return true;
-    }
-    return false;
+    return resolveBinaryPath(name, pathEnv) !== null;
 }
 
 function isToolInstalled(signal: ToolSignal, home: string, pathEnv: string): boolean {

package/src/install/wizard-plan.ts

@@ -91,6 +91,16 @@ const CLAUDE_SKILL_BUNDLE: ReadonlyArray<readonly [string, string]> = [
  * — they either follow a marker-only convention (handled by bridges in
  * Phase A6) or have no markdown convention at all.
  */
+/**
+ * The one deploy-source row that carries install-time rule scoping.
+ *
+ * Exported so the CLI global path (`scripts/install.ts::_deploy_global_content`)
+ * keys its filter off the SAME string this expander does. Two paths agreeing on
+ * the predicate but disagreeing on which source it applies to would reproduce
+ * exactly the divergence rule scoping exists to prevent.
+ */
+export const RULE_SOURCE_REL = 'dist/agent-src/rules';
+
 export const GLOBAL_DEPLOY_SOURCES: Readonly<Record<string, ReadonlyArray<readonly [string, string]>>> = {
     'claude-code': CLAUDE_SKILL_BUNDLE,
     augment: [
@@ -193,9 +203,9 @@ export function expandWizardSources(inputs: WizardExpandInputs): PlanSource[] {
             const srcDir = join(packageRoot, srcRel);
             const destDir = destSub.length === 0 ? destRoot : join(destRoot, destSub);
             // Rule sources get the install-time scoping filter — the same
-            // predicate the projection path uses (Phase 1b: Pipeline B may
-            // never drift from Pipeline A).
-            const isRuleSource = srcRel === 'dist/agent-src/rules';
+            // predicate the projection path uses (Phase 1b: the consumer
+            // install may never drift from Pipeline A, the source projection).
+            const isRuleSource = srcRel === RULE_SOURCE_REL;
             out.push({
                 toolId,
                 srcDir,

package/src/scripts/_cli/cmd_conformance.ts

@@ -37,6 +37,7 @@ import * as installed_tools from '../_lib/installed_tools.js';
 import { atomicAppendLine } from '../../install/atomic.js';
 import { readRecentEntries } from '../../install/txlog.js';
 import { detectToolPresence } from '../../install/detect.js';
+import { resolvePackageRoot } from '../_lib/package_root.js';
 import {
     _classify,
     _collect_manifest_entries,
@@ -56,7 +57,7 @@ type Dict = Record<string, unknown>;
 const _HERE = fileURLToPath(import.meta.url);
 
 /** Package root — two levels above `src/scripts/_cli/`. */
-export const PACKAGE_ROOT = path.resolve(path.dirname(_HERE), '..', '..', '..');
+export const PACKAGE_ROOT = resolvePackageRoot(import.meta.url);
 
 /** Ordered registry of conformance check identifiers. */
 export const CONFORMANCE_CHECK_IDS = [

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';