@event4u/agent-config 9.10.0 → 9.11.0

package/src/scripts/ai_council/config.ts

@@ -14,12 +14,16 @@
  * Validation contract (8 rules, all enforced at load time):
  *
  * 1. `enabled` is a bool.
- * 2. `defaults.mode` ∈ {`api`, `manual`, `cli`}; per-member mode same
- *    set. Semantics: `api` = SDK call against a stored key (billable);
+ * 2. `defaults.mode` ∈ {`api`, `manual`, `cli`, `auto`}; per-member mode
+ *    same set. Semantics: `api` = SDK call against a stored key (billable);
  *    `manual` = copy & paste — human transports prompt + reply between
  *    the agent and an external chat surface (free); `cli` = shell out to
  *    a locally-installed CLI under subscription auth (free for
- *    first-party CLIs, billable for community wrappers).
+ *    first-party CLIs, billable for community wrappers); `auto` = pick
+ *    per provider per invocation (cli → api → unavailable), resolved by
+ *    `transport_resolver.ts`. `auto` is opt-in — it is never the shipped
+ *    default, because flipping it would move an existing user's spend
+ *    from per-token dollars onto subscription quota with no config edit.
  * 3. `members.<name>` keys are restricted to the known provider set.
  * 4. `cost_budget.*` numeric fields are >= 0.
  * 5. Enabled members carry a non-empty `model` and `api_key_ref` when
@@ -30,7 +34,8 @@
  *    even if syntactically plausible.
  * 7. Resolved `file:` key paths must have mode 0o600 (delegated to
  *    `resolve_api_key`; runs at use-time, not parse-time).
- * 8. `binary:` is only valid when the member's effective mode is `cli`;
+ * 8. `binary:` is only valid when the member's effective mode is `cli` or
+ *    `auto` (auto may resolve to the cli rung);
  *    `cli_call_budget.max_calls_per_day.<provider>` keys must be valid
  *    providers.
  *
@@ -60,7 +65,7 @@ const _VALID_PROVIDERS: ReadonlySet<string> = new Set([
     'xai',
     'perplexity',
 ]);
-const _VALID_MODES: ReadonlySet<string> = new Set(['api', 'manual', 'cli']);
+const _VALID_MODES: ReadonlySet<string> = new Set(['api', 'manual', 'cli', 'auto']);
 
 /**
  * Prefixes that signal "this is a raw API key" so we refuse it loudly
@@ -1655,10 +1660,13 @@ function _build_member(
                 `members.${name}.binary must be a non-empty string when set.`,
             );
         }
-        if (effective_mode !== 'cli') {
+        // `auto` may resolve to the cli rung, so a binary override is
+        // legitimate there too — rejecting it would make `auto` unusable for
+        // anyone whose CLI is not on `$PATH` under its default name.
+        if (effective_mode !== 'cli' && effective_mode !== 'auto') {
             throw new CouncilConfigError(
                 `members.${name}.binary is only valid when the member's ` +
-                    `effective mode is 'cli' (got ${_pyRepr(effective_mode)}). Set ` +
+                    `effective mode is 'cli' or 'auto' (got ${_pyRepr(effective_mode)}). Set ` +
                     `\`mode: cli\` on the member or \`defaults.mode: cli\` to use ` +
                     `this field.`,
             );

package/src/scripts/ai_council/modes.ts

@@ -12,17 +12,43 @@
  * - `manual`   — copy-paste loop with the user as transport (free).
  * - `cli`      — shell out to a locally-installed provider CLI under the
  *                user's subscription auth. `billable=False`.
+ * - `auto`     — resolve per provider per invocation (cli → api → unavailable).
+ *                Accepted here as a VALUE; the concrete transport is chosen by
+ *                `transport_resolver.ts`, which owns the chain and the billing
+ *                classification. `manual` is never part of the auto chain.
  *
  * Resolution precedence — first non-empty wins:
  *
  *     1. Invocation flag      e.g. `/council mode:manual`
  *     2. Per-member setting   `ai_council.members.<name>.mode`
- *     3. Global setting       `ai_council.mode`
+ *     3. Global setting       `ai_council.mode` OR `ai_council.defaults.mode`
+ *                             (see `resolve_global_mode` — both shapes reach
+ *                             this resolver, and they must agree)
  *     4. Built-in default     `manual`
+ *
+ * ## Two distinct defaults — the reconciliation (road-to-zero-ceremony-detection)
+ *
+ * The contract used to describe a single fallback (`"api"`) while this module
+ * implemented `manual`. Both were right about different layers, and the docs
+ * conflated them. They are now named separately:
+ *
+ * - **Loader default** — when a config file omits `defaults.mode` entirely,
+ *   `config.ts::_build_defaults` fills `api`. Unchanged; this is what every
+ *   real config observes, because the loader always populates the key.
+ * - **Built-in fallback** — when NO layer supplies a mode at all (a settings
+ *   dict handed straight to the resolver, no config file involved), the answer
+ *   is `manual`, below. That is the fail-closed direction the no-silent-spend
+ *   Iron Law requires: a caller who supplied no transport preference has not
+ *   asked to spend money, so the free transport wins.
  */
 
-export const VALID_MODES: ReadonlySet<string> = new Set(['api', 'manual', 'cli']);
+export const VALID_MODES: ReadonlySet<string> = new Set(['api', 'manual', 'cli', 'auto']);
 
+/**
+ * Built-in fallback when no layer supplies a mode. `manual` — free, no key,
+ * no spend. NOT the same as the loader's `defaults.mode` default (`api`); see
+ * the module header.
+ */
 export const DEFAULT_MODE = 'manual';
 
 /** Raised when a configured / invoked mode is not in `VALID_MODES`. */
@@ -72,6 +98,46 @@ function _pyReprList(items: string[]): string {
     return `[${items.map((i) => _pyRepr(i)).join(', ')}]`;
 }
 
+/**
+ * Extract the global transport mode from an `ai_council` block, accepting BOTH
+ * shapes the block legitimately arrives in.
+ *
+ * `council_cli.ts::_synthesize_ai_council_block` FLATTENS the loader's
+ * `defaults.mode` onto a top-level `mode` key, so the normal path presents the
+ * flat shape. But `build_members` is on the exported surface, and callers that
+ * hand it a RAW `.ai-council.yml`-shaped dict present the nested shape. Reading
+ * only the flat key silently dropped the configured default on that path and
+ * fell through to `DEFAULT_MODE`.
+ *
+ * Flat wins when both are present — it is the synthesized, already-resolved
+ * value. Returns `null` when neither shape carries a usable string, letting the
+ * precedence chain continue to the built-in.
+ */
+export function resolve_global_mode(
+    aiBlock: ReadonlyMap<string, unknown> | Record<string, unknown> | null | undefined,
+): string | null {
+    if (aiBlock === null || aiBlock === undefined) {
+        return null;
+    }
+    const flat = _normalise(_settingsGet(aiBlock, 'mode'));
+    if (flat !== null) {
+        return flat;
+    }
+    const defaults = _settingsGet(aiBlock, 'defaults');
+    if (defaults === null || defaults === undefined) {
+        return null;
+    }
+    if (!(defaults instanceof Map) && typeof defaults !== 'object') {
+        return null;
+    }
+    if (Array.isArray(defaults)) {
+        return null;
+    }
+    return _normalise(
+        _settingsGet(defaults as ReadonlyMap<string, unknown> | Record<string, unknown>, 'mode'),
+    );
+}
+
 export interface ResolveModeOptions {
     invocationMode?: string | null;
     memberSettings?: ReadonlyMap<string, unknown> | Record<string, unknown> | null;

package/src/scripts/ai_council/transport_resolver.ts

@@ -0,0 +1,331 @@
+/**
+ * Transport resolution for `mode: auto`, plus the two guards that keep it
+ * honest (Phase 2 of `road-to-zero-ceremony-detection`).
+ *
+ * `modes.ts` answers "which mode did the config ask for" — a pure precedence
+ * walk over four layers. This module answers the next question: when that
+ * answer is `auto`, which concrete transport does THIS machine support right
+ * now, how is it billed, and what happens when the chosen rung fails
+ * mid-invocation.
+ *
+ * ## The `auto` chain
+ *
+ *     cli   — the provider's CLI binary resolves AND a credential is present
+ *     api   — else a key resolves
+ *     ∅     — else unavailable, with a one-line reason
+ *
+ * `manual` is deliberately NOT in the chain. It is free and always "available"
+ * (the human is the transport), so an availability-ranked chain would always
+ * end there and `auto` would silently become "ask the human to copy-paste".
+ * Manual stays an explicit opt-in.
+ *
+ * ## The billing invariant
+ *
+ * Billing is classified from (provider, detected auth source) by
+ * `classifyBilling` in `_lib/environment_detector.ts` — never from the
+ * transport this module picked. That is the property that keeps the existing
+ * per-provider rules intact under `auto`:
+ *
+ * - a VENDOR-OFFICIAL CLI under a subscription login is unmetered, so the USD
+ *   cost gate stays off and `cli_call_budget` guards the plan quota instead;
+ * - a COMMUNITY wrapper (`grok`, `perplexity`) shells out to the same paid API
+ *   and stays metered even though the transport is also spelled `cli`;
+ * - an unknown source is metered — deliberately over-gated.
+ *
+ * `makesProviderCall` below IS transport-derived, and is not a billing term:
+ * it records that `manual` performs no provider call at all, which is why no
+ * amount of billing classification applies to it.
+ *
+ * @see docs/contracts/ai-council-config.md § Transport modes
+ */
+
+import {
+    classifyBilling,
+    isCommunityCli,
+    strongestAuth,
+    PROVIDER_CLI_META,
+    type AuthSource,
+    type BillingClass,
+    type EnvironmentReport,
+} from '../_lib/environment_detector.js';
+
+/** A concrete transport a member can actually run on. `auto` is not one. */
+export type Transport = 'api' | 'manual' | 'cli';
+
+/** The accepted values of the `mode` key, including the resolver-only `auto`. */
+export const VALID_TRANSPORT_MODES: ReadonlySet<string> = new Set([
+    'api',
+    'manual',
+    'cli',
+    'auto',
+]);
+
+export interface ResolvedTransport {
+    /** False when `auto` found no usable rung; `reason` then says why. */
+    readonly available: boolean;
+    /** The concrete transport, or `null` when unavailable. */
+    readonly transport: Transport | null;
+    /** How a provider call is paid for. From auth source only — never from `transport`. */
+    readonly billing: BillingClass;
+    /** The auth source the classification used, or `null` when none was detected. */
+    readonly authSource: AuthSource | null;
+    /** Transport-derived, NOT a billing term: `manual` performs no provider call. */
+    readonly makesProviderCall: boolean;
+    /** One-line reason. Non-empty exactly when `available` is false. */
+    readonly reason: string | null;
+}
+
+export interface ResolveTransportOptions {
+    readonly provider: string;
+    /** The mode `resolve_mode` returned — `api` | `manual` | `cli` | `auto`. */
+    readonly mode: string;
+    /** The single read-only environment report. */
+    readonly report: EnvironmentReport;
+    /** Member-level `binary:` override, when set. Counts as a resolved binary. */
+    readonly binaryOverride?: string | null;
+    /**
+     * Whether the member's `api_key_ref` resolves. Defaults to "a key-file or
+     * env-key auth record exists for this provider" from the report.
+     */
+    readonly apiKeyPresent?: boolean;
+}
+
+/** Auth sources that mean "the provider CLI can authenticate". */
+const CLI_AUTH_SOURCES: ReadonlySet<AuthSource> = new Set(['cli-subscription', 'cli-api-key']);
+
+/** Auth sources that mean "a stored key exists for the api transport". */
+const KEY_AUTH_SOURCES: ReadonlySet<AuthSource> = new Set(['key-file', 'env-key']);
+
+function hasSource(
+    report: EnvironmentReport,
+    provider: string,
+    allowed: ReadonlySet<AuthSource>,
+): boolean {
+    return report.auth.some((a) => a.provider === provider && allowed.has(a.source));
+}
+
+/** Resolved CLI binary for `provider` from the report, or `null`. */
+function cliBinary(report: EnvironmentReport, provider: string): string | null {
+    const meta = PROVIDER_CLI_META[provider];
+    if (meta === undefined) return null;
+    const binaryName = meta[0];
+    const host = report.hosts.find(
+        (h) => h.binary !== null && stripExeSuffix(basename(h.binary)) === binaryName,
+    );
+    return host?.binary ?? null;
+}
+
+/** Last path segment, separator-agnostic (no `node:path` import needed). */
+function basename(p: string): string {
+    const parts = p.split(/[/\\]/);
+    return parts[parts.length - 1] ?? p;
+}
+
+/** Strip a Windows executable suffix so `claude.cmd` matches `claude`. */
+function stripExeSuffix(name: string): string {
+    return name.replace(/\.(exe|cmd)$/i, '');
+}
+
+/**
+ * Resolve one member's transport.
+ *
+ * Explicit `api` / `manual` / `cli` pass through unchanged — this function
+ * never overrides a mode the user or a per-member override asked for. Only
+ * `auto` walks the chain.
+ */
+export function resolveTransport(opts: ResolveTransportOptions): ResolvedTransport {
+    const { provider, mode, report } = opts;
+    const auth = strongestAuth(report, provider);
+    const authSource = auth?.source ?? null;
+    const billing = classifyBilling(provider, authSource);
+
+    if (mode === 'manual') {
+        return {
+            available: true,
+            transport: 'manual',
+            // Classified from the auth source like every other member; it is
+            // simply never consulted because no provider call happens.
+            billing,
+            authSource,
+            makesProviderCall: false,
+            reason: null,
+        };
+    }
+
+    if (mode === 'api' || mode === 'cli') {
+        return {
+            available: true,
+            transport: mode,
+            billing,
+            authSource,
+            makesProviderCall: true,
+            reason: null,
+        };
+    }
+
+    if (mode !== 'auto') {
+        return unavailable(
+            provider,
+            billing,
+            `mode=${JSON.stringify(mode)} is not one of ` +
+                `${[...VALID_TRANSPORT_MODES].sort().join(', ')}`,
+        );
+    }
+
+    // ── the auto chain ──────────────────────────────────────────────────
+    const override = (opts.binaryOverride ?? null)?.trim() ?? null;
+    const binary = override !== null && override !== '' ? override : cliBinary(report, provider);
+    const cliAuthed = hasSource(report, provider, CLI_AUTH_SOURCES);
+
+    if (binary !== null && cliAuthed) {
+        return {
+            available: true,
+            transport: 'cli',
+            billing,
+            authSource,
+            makesProviderCall: true,
+            reason: null,
+        };
+    }
+
+    const keyPresent = opts.apiKeyPresent ?? hasSource(report, provider, KEY_AUTH_SOURCES);
+    if (keyPresent) {
+        return {
+            available: true,
+            transport: 'api',
+            billing,
+            authSource,
+            makesProviderCall: true,
+            reason: null,
+        };
+    }
+
+    return unavailable(provider, billing, autoUnavailableReason(provider, binary, cliAuthed));
+}
+
+function unavailable(
+    _provider: string,
+    billing: BillingClass,
+    reason: string,
+): ResolvedTransport {
+    return {
+        available: false,
+        transport: null,
+        // Unavailable members never spend, but the class stays over-gated so a
+        // caller that ignores `available` cannot read this as "free".
+        billing,
+        authSource: null,
+        makesProviderCall: false,
+        reason,
+    };
+}
+
+/** The one-line reason `auto` prints when no rung resolved. */
+function autoUnavailableReason(
+    provider: string,
+    binary: string | null,
+    cliAuthed: boolean,
+): string {
+    const expected = PROVIDER_CLI_META[provider]?.[0] ?? provider;
+    if (binary === null && !cliAuthed) {
+        return (
+            `no transport available: \`${expected}\` is not on PATH and no key resolves ` +
+            `— install the CLI and log in, or add an api_key_ref`
+        );
+    }
+    if (binary === null) {
+        return (
+            `no transport available: a credential is present but \`${expected}\` is not ` +
+            `on PATH and no key resolves — install the CLI, or add an api_key_ref`
+        );
+    }
+    return (
+        `no transport available: \`${expected}\` is on PATH but not authenticated and no ` +
+        `key resolves — log in to the CLI, or add an api_key_ref`
+    );
+}
+
+// ── mid-flight fallback ─────────────────────────────────────────────────
+
+/**
+ * Why a CLI call failed, normalised from `CliClient._classify_stderr` and the
+ * `binary_missing` skip reason.
+ */
+export type CliFailureClass =
+    | 'binary_missing'
+    | 'auth_rejected'
+    | 'cli_unsupported'
+    | 'timeout'
+    | 'server_error'
+    | 'quota_exhausted'
+    | 'other';
+
+/**
+ * Failure classes that may fall through to the `api` rung.
+ *
+ * All three share one property: the CLI provably never reached the provider,
+ * so retrying on another transport cannot double-charge. Everything absent
+ * from this set — notably `timeout` and `server_error` — may have left a
+ * half-completed call behind, and falling through would risk paying twice for
+ * one question. `quota_exhausted` is excluded for a different reason: the
+ * quota is a cap the user deliberately set, so routing around it would defeat
+ * the guard rather than recover from a fault.
+ */
+const FALLBACK_ELIGIBLE: ReadonlySet<CliFailureClass> = new Set([
+    'binary_missing',
+    'auth_rejected',
+    'cli_unsupported',
+]);
+
+/** Normalise a raw client error / skip reason into a `CliFailureClass`. */
+export function classifyCliFailure(raw: string): CliFailureClass {
+    const s = raw.trim().toLowerCase();
+    if (s === 'binary_missing' || s === 'file_not_found') return 'binary_missing';
+    if (s === 'auth_expired' || s === 'auth_rejected' || s === 'unauthorized') {
+        return 'auth_rejected';
+    }
+    if (s === 'cli_unsupported' || s === 'unsupported' || s === 'parse_failed') {
+        return 'cli_unsupported';
+    }
+    if (s === 'timeout') return 'timeout';
+    if (s === 'cli_quota_exhausted' || s === 'quota_exhausted') return 'quota_exhausted';
+    if (/^exit_5\d\d$/.test(s) || s === 'server_error' || s === 'os') return 'server_error';
+    return 'other';
+}
+
+/** True when `failure` is eligible to fall through to the `api` rung. */
+export function isFallbackEligible(failure: CliFailureClass): boolean {
+    return FALLBACK_ELIGIBLE.has(failure);
+}
+
+/**
+ * One-shot, per-provider fallback ledger for a single invocation.
+ *
+ * Construct one per council run. `attempt` returns `'api'` at most ONCE per
+ * provider, and only for a fallback-eligible failure class; every later call
+ * for that provider returns `'stop'`. This is the double-spend guard: a
+ * timeout never falls through, and an eligible failure never falls through
+ * twice.
+ */
+export class MidFlightFallback {
+    private readonly used = new Set<string>();
+
+    /** `'api'` to retry on the api rung, `'stop'` to surface the failure. */
+    attempt(provider: string, failure: CliFailureClass): 'api' | 'stop' {
+        if (!isFallbackEligible(failure)) return 'stop';
+        if (this.used.has(provider)) return 'stop';
+        this.used.add(provider);
+        return 'api';
+    }
+
+    /** Providers that have already spent their one fallback. */
+    spent(): readonly string[] {
+        return [...this.used].sort();
+    }
+}
+
+/**
+ * True when `provider`'s CLI transport is a community wrapper — re-exported
+ * so callers reasoning about `auto` do not have to reach into the detector.
+ */
+export { isCommunityCli };

package/src/scripts/check_bundle_path_leakage.ts

@@ -62,10 +62,16 @@ const REPO = path.resolve(path.dirname(_HERE), '..', '..');
 
 // Tracked directories that may hold a build-generated bundle. Only
 // `dist/install/` is force-included in `.gitignore` today (`!/dist/install/`);
-// `dist/hooks/` and `dist/mcp/` are listed defensively in case a future
-// change tracks them too — `git ls-files` on an untracked directory returns
-// nothing, so listing an as-yet-untracked root here is always safe.
-const BUNDLE_ROOTS: readonly string[] = ['dist/install', 'dist/hooks', 'dist/mcp'];
+// `dist/hooks/`, `dist/mcp/` and `dist/cli-delegate/` are listed defensively
+// in case a future change tracks them too — `git ls-files` on an untracked
+// directory returns nothing, so listing an as-yet-untracked root here is
+// always safe.
+const BUNDLE_ROOTS: readonly string[] = [
+    'dist/install',
+    'dist/hooks',
+    'dist/mcp',
+    'dist/cli-delegate',
+];
 
 interface LeakPattern {
     readonly name: string;

package/src/scripts/check_dependency_floors.ts

@@ -0,0 +1,153 @@
+#!/usr/bin/env tsx
+/**
+ * check_dependency_floors — keep every runtime dependency floor at a settled
+ * minor, so consumers on `prefer-offline=true` or a lagging registry mirror
+ * cannot hit `ETARGET — No matching version found`
+ * (road-to-zero-ceremony-install § Phase 2).
+ *
+ * Why a gate and not a retry: `dependencies` are resolved on the CONSUMER's
+ * machine by npm, BEFORE our `bin` is executed. When resolution fails, npx
+ * aborts and no code of ours ever runs — so this failure mode cannot be
+ * caught, retried, or explained from inside the CLI. It can only be made
+ * unreachable at publish time, which is what this gate does. CONTRIBUTING
+ * § "Runtime dependency floors" states the rule in prose; this is its teeth.
+ *
+ * The rule: a caret floor pins the minimum compatible version, so its patch
+ * component is `.0` (`^9.5.0`, never `^9.6.1`). A floor pinned to a
+ * just-published patch fails against cached registry metadata that predates
+ * it, even though the version exists on public npm.
+ *
+ * Exact pins (no range operator) are a different, deliberate mechanism — an
+ * ABI lock — and are allowed only when listed in EXACT_PIN_EXCEPTIONS with a
+ * reason, so a drive-by pin cannot hide among them.
+ *
+ * SECURITY FLOORS OUTRANK THIS RULE. A floor whose patch component is non-zero
+ * *because everything below it carries an advisory* must never be lowered to
+ * satisfy resolvability — that trades a rare install failure for a live CVE.
+ * Those live in SECURITY_FLOOR_EXCEPTIONS with the advisory and the vulnerable
+ * range, and the gate then enforces the floor rather than fighting it.
+ *
+ * Usage:
+ *   ./scripts-run src/scripts/check_dependency_floors [--json]
+ *
+ * Exit codes: 0 green · 1 a floor violates the rule · 2 misuse / unreadable manifest.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const REPO_ROOT = path.resolve(fileURLToPath(import.meta.url), '..', '..', '..');
+
+/**
+ * Dependencies deliberately pinned to an exact version, with the reason. An
+ * exact pin cannot suffer the freshest-patch failure (the version is either
+ * cached or it is not), but it also forfeits patch fixes — so each one is
+ * named here rather than silently tolerated.
+ */
+export const EXACT_PIN_EXCEPTIONS: Readonly<Record<string, string>> = {
+    'web-tree-sitter': 'ABI-locked against tree-sitter-wasms; see code-graph engine pin',
+    'tree-sitter-wasms': 'ABI-locked against web-tree-sitter; see code-graph engine pin',
+};
+
+/**
+ * Floors that are non-settled ON PURPOSE, because every version below them is
+ * vulnerable. The required range is pinned here so the gate ENFORCES the floor
+ * instead of asking for it to be lowered — lowering one trades a rare install
+ * failure for a live advisory, which is never the right trade.
+ */
+export const SECURITY_FLOOR_EXCEPTIONS: Readonly<Record<string, { required: string; reason: string }>> = {
+    '@fastify/static': {
+        required: '^10.1.2',
+        reason:
+            'high-severity route-guard bypass via path traversal (CVSS 7.5) affects <=10.1.1; ' +
+            '10.1.2 is the fix. Verified with npm audit on a clean 10.1.0 install, 2026-07-31.',
+    },
+};
+
+/** A settled caret floor: `^X.Y.0`. */
+const SETTLED_CARET = /^\^\d+\.\d+\.0$/;
+
+/** An exact version with no range operator: `1.2.3`. */
+const EXACT_VERSION = /^\d+\.\d+\.\d+$/;
+
+/**
+ * Every violation in `dependencies`, as human-readable lines. Empty array
+ * means the manifest cannot produce a freshest-patch `ETARGET` for a consumer.
+ */
+export function evaluate(dependencies: Readonly<Record<string, string>>): string[] {
+    const errors: string[] = [];
+    for (const [name, range] of Object.entries(dependencies)) {
+        const security = SECURITY_FLOOR_EXCEPTIONS[name];
+        if (security !== undefined) {
+            // The floor is the control. Enforce it; never ask for it to settle.
+            if (range !== security.required) {
+                errors.push(
+                    `${name}@${range}: security floor must stay at ${security.required} — ${security.reason}`,
+                );
+            }
+            continue;
+        }
+        if (EXACT_VERSION.test(range)) {
+            if (!(name in EXACT_PIN_EXCEPTIONS)) {
+                errors.push(
+                    `${name}@${range}: exact pin without an entry in EXACT_PIN_EXCEPTIONS — ` +
+                        'add the reason there, or use a settled caret floor (^X.Y.0)',
+                );
+            }
+            continue;
+        }
+        if (SETTLED_CARET.test(range)) continue;
+        if (range.startsWith('^')) {
+            errors.push(
+                `${name}@${range}: caret floor is not a settled minor — lower the patch to ` +
+                    `.0 (e.g. ${range.replace(/\.\d+$/, '.0')}) so a lagging registry mirror ` +
+                    'can still resolve it',
+            );
+            continue;
+        }
+        errors.push(
+            `${name}@${range}: unsupported range shape — use a settled caret floor (^X.Y.0), ` +
+                'or an exact pin listed in EXACT_PIN_EXCEPTIONS',
+        );
+    }
+    return errors;
+}
+
+export function main(argv: readonly string[] = process.argv.slice(2)): number {
+    const asJson = argv.includes('--json');
+    const manifestPath = path.join(REPO_ROOT, 'package.json');
+    let dependencies: Record<string, string>;
+    try {
+        const raw = JSON.parse(fs.readFileSync(manifestPath, 'utf-8')) as {
+            dependencies?: Record<string, string>;
+        };
+        dependencies = raw.dependencies ?? {};
+    } catch (err) {
+        process.stderr.write(`❌  dependency floors: cannot read ${manifestPath}: ${String(err)}\n`);
+        return 2;
+    }
+    if (Object.keys(dependencies).length === 0) {
+        process.stderr.write('❌  dependency floors: no runtime dependencies found — gate would pass vacuously\n');
+        return 2;
+    }
+    const errors = evaluate(dependencies);
+    if (asJson) {
+        process.stdout.write(`${JSON.stringify({ checked: Object.keys(dependencies).length, errors }, null, 2)}\n`);
+        return errors.length > 0 ? 1 : 0;
+    }
+    if (errors.length > 0) {
+        for (const e of errors) process.stderr.write(`❌  dependency floor: ${e}\n`);
+        return 1;
+    }
+    process.stdout.write(
+        `✅  dependency floors settled (${Object.keys(dependencies).length} runtime deps) — ` +
+            'no freshest-patch ETARGET reachable for a consumer\n',
+    );
+    return 0;
+}
+
+const _selfPath = fileURLToPath(import.meta.url);
+if (process.argv[1] !== undefined && path.resolve(process.argv[1]) === path.resolve(_selfPath)) {
+    process.exit(main());
+}