@event4u/agent-config 16.4.0 → 17.0.0

package/src/scripts/_lib/egress_token.ts

@@ -0,0 +1,252 @@
+// The placeholder grammar of docs/contracts/egress-placeholders-v1.md and its
+// one recogniser. The spelling is the one the pre-registered model-fidelity bar
+// selected (internal/bench/egress-placeholders-PREREG.md, endpoint d); no other
+// spelling may exist under src/, which egress_token.test.ts enforces.
+
+import { createHmac, randomBytes } from 'node:crypto';
+
+import { detect, EGRESS_RULES, type EgressClass, type EgressSpan, replaceSpans } from './egress_rules.js';
+
+export const TOKEN_FP_LENGTH = 6;
+
+/**
+ * `__TYPE_n_fingerprint__`, or `__TYPE_n_fingerprint_vK__` for the K-th spelling
+ * of one entity — type upper-case, number from 1, fingerprint lower hex, K from 2.
+ */
+export const TOKEN_PATTERN = /__([A-Z][A-Z0-9]{1,15})_([1-9][0-9]{0,5})_([0-9a-f]{6})(?:_v([2-9]|[1-9][0-9]))?__/g;
+
+const TOKEN_TYPE = /^[A-Z][A-Z0-9]{1,15}$/;
+const MAX_TOKEN_NUMBER = 999_999;
+/** Spellings one entity may carry in a scope; the recogniser parses up to two digits. */
+export const MAX_TOKEN_VARIANT = 99;
+/**
+ * Unknown tokens a scope answers before it stops resolving anything. With a
+ * 24-bit fingerprint this bounds the chance that guessing ever resolves a value
+ * to at most 64 × 2^-24 (about 4 in a million) per scope.
+ */
+export const MAX_FAILED_RESOLUTIONS = 64;
+
+export interface TokenParts {
+    readonly type: string;
+    readonly number: number;
+    readonly fingerprint: string;
+    /** Which spelling of the entity, from 1; 1 carries no suffix. */
+    readonly variant?: number;
+}
+
+export interface ParsedToken extends TokenParts {
+    readonly start: number;
+    readonly end: number;
+}
+
+const TOKEN_FP = /^[0-9a-f]{6}$/;
+
+/** The one writer of the grammar; it refuses parts the recogniser would not parse back. */
+export function formatToken(p: TokenParts): string {
+    if (
+        !TOKEN_TYPE.test(p.type) ||
+        !Number.isInteger(p.number) ||
+        p.number < 1 ||
+        p.number > MAX_TOKEN_NUMBER ||
+        !TOKEN_FP.test(p.fingerprint) ||
+        (p.variant !== undefined &&
+            (!Number.isInteger(p.variant) || p.variant < 1 || p.variant > MAX_TOKEN_VARIANT))
+    ) {
+        throw new Error('formatToken: parts outside the token grammar');
+    }
+    const suffix = p.variant === undefined || p.variant === 1 ? '' : `_v${p.variant}`;
+    return `__${p.type}_${p.number}_${p.fingerprint}${suffix}__`;
+}
+
+export function parseTokens(text: string): ParsedToken[] {
+    const out: ParsedToken[] = [];
+    TOKEN_PATTERN.lastIndex = 0;
+    let m: RegExpExecArray | null;
+    while ((m = TOKEN_PATTERN.exec(text)) !== null) {
+        out.push({
+            type: m[1] as string,
+            number: Number(m[2]),
+            fingerprint: m[3] as string,
+            variant: m[4] === undefined ? 1 : Number(m[4]),
+            start: m.index,
+            end: m.index + m[0].length,
+        });
+    }
+    return out;
+}
+
+interface Entry {
+    readonly type: string;
+    readonly class: EgressClass;
+    readonly number: number;
+    readonly fingerprint: string;
+    /**
+     * Keyed digests of each spelling seen, in order; its index + 1 is the
+     * spelling's variant. A digest, so a credential's spelling is never kept.
+     */
+    readonly spellings: string[];
+}
+
+interface Issued {
+    readonly entry: Entry;
+    /** The spelling this token restores to — identifiers only; a credential value is never kept. */
+    readonly value: string | null;
+}
+
+/**
+ * The form two spellings of one entity share. Only types whose spelling varies
+ * without changing the value are listed; every other type is its own canonical
+ * form, so two spellings of it are two entities.
+ */
+const CANONICAL_FORMS: Readonly<Record<string, (raw: string) => string>> = {
+    IBAN: (raw) => raw.replace(/\s+/g, '').toUpperCase(),
+    CARD: (raw) => raw.replace(/[\s-]+/g, ''),
+    PHONE: (raw) => raw.replace(/[\s().\-/]+/g, ''),
+};
+
+export function canonicalValue(type: string, raw: string): string {
+    return CANONICAL_FORMS[type]?.(raw) ?? raw;
+}
+
+/**
+ * One issuing scope: a random key that is never sent and never persisted, and
+ * the in-memory mapping from minted tokens back to identifier values.
+ */
+export class TokenScope {
+    private readonly key: Uint8Array;
+    private readonly byDigest = new Map<string, Entry>();
+    private readonly byToken = new Map<string, Issued>();
+    private readonly counters = new Map<string, number>();
+    private failedResolutions = 0;
+    /** Keyed digest of the canonical value alone → its class, whatever type it was minted under. */
+    private readonly classByValue = new Map<string, EgressClass>();
+
+    constructor() {
+        this.key = randomBytes(32);
+    }
+
+    /**
+     * The token for one spelling. Spellings with one canonical form share number
+     * and fingerprint and differ in the variant suffix, so each restores to its
+     * own bytes.
+     */
+    mint(type: string, cls: EgressClass, spelling: string): string {
+        const canonical = canonicalValue(type, spelling);
+        if (!TOKEN_TYPE.test(type)) {
+            throw new Error(`TokenScope: type ${JSON.stringify(type)} is outside the token grammar`);
+        }
+        const valueDigest = createHmac('sha256', this.key).update(`value\u0000${canonical}`).digest('hex');
+        const seenClass = this.classByValue.get(valueDigest);
+        if (seenClass !== undefined && seenClass !== cls) {
+            throw new Error(`TokenScope: this value was minted under class ${seenClass}, refusing class ${cls}`);
+        }
+        const digest = createHmac('sha256', this.key).update(`${type}\u0000${canonical}`).digest('hex');
+        const spellingDigest = createHmac('sha256', this.key).update(`spelling\u0000${type}\u0000${spelling}`).digest('hex');
+        const known = this.byDigest.get(digest);
+        if (known !== undefined) {
+            const at = known.spellings.indexOf(spellingDigest);
+            if (at !== -1) return formatToken({ ...known, variant: at + 1 });
+            if (known.spellings.length >= MAX_TOKEN_VARIANT) {
+                throw new Error(`TokenScope: this ${type} has used every variant the grammar can carry`);
+            }
+            known.spellings.push(spellingDigest);
+            return this.issue(known, known.spellings.length, cls, spelling);
+        }
+        const number = (this.counters.get(type) ?? 0) + 1;
+        if (number > MAX_TOKEN_NUMBER) {
+            throw new Error(`TokenScope: ${type} has used every number the grammar can carry`);
+        }
+        this.counters.set(type, number);
+        const entry: Entry = {
+            type,
+            class: cls,
+            number,
+            fingerprint: digest.slice(0, TOKEN_FP_LENGTH),
+            spellings: [spellingDigest],
+        };
+        this.classByValue.set(valueDigest, cls);
+        this.byDigest.set(digest, entry);
+        return this.issue(entry, 1, cls, spelling);
+    }
+
+    private issue(entry: Entry, variant: number, cls: EgressClass, spelling: string): string {
+        const token = formatToken({ ...entry, variant });
+        this.byToken.set(token, { entry, value: cls === 'identifier' ? spelling : null });
+        return token;
+    }
+
+    /** True only for a token this scope minted; token syntax alone proves nothing. */
+    owns(token: string): boolean {
+        return this.byToken.has(token);
+    }
+
+    /** The identifier value a token stands for, or null: unknown, forged, foreign or credential. */
+    resolve(token: string): string | null {
+        if (this.failedResolutions >= MAX_FAILED_RESOLUTIONS) return null;
+        const issued = this.byToken.get(token);
+        if (issued === undefined) {
+            this.failedResolutions += 1;
+            return null;
+        }
+        return issued.value;
+    }
+
+    /** What the scope holds, without any value or spelling digest. */
+    snapshot(): Array<Omit<Entry, 'spellings'> & { variants: number }> {
+        return [...this.byDigest.values()].map(({ spellings, ...rest }) => ({ ...rest, variants: spellings.length }));
+    }
+}
+
+/** Thrown when a rule cannot prove which bytes its secret spans; carries the rule id, never a byte of the text. */
+export class EgressRefusedError extends Error {
+    constructor(readonly rule: string) {
+        super(`egress refused: rule ${rule} could not prove the extent of a detected secret`);
+        this.name = 'EgressRefusedError';
+    }
+}
+
+const RULE_BY_ID = new Map(EGRESS_RULES.map((r) => [r.rule, r]));
+const CLASS_RANK: Readonly<Record<EgressClass, number>> = { credential: 1, identifier: 0 };
+
+/** The bytes each detection obliges a replacement to remove; overlapping extents merge. */
+function replacementSpans(text: string, detected: readonly EgressSpan[]): EgressSpan[] {
+    const extents = detected.map((s) => {
+        const policy = RULE_BY_ID.get(s.rule)?.replacement;
+        if (policy === undefined) throw new EgressRefusedError(s.rule);
+        if (policy === 'detection') return s;
+        const end = policy.through(text, s);
+        if (end === null || end < s.end) throw new EgressRefusedError(s.rule);
+        return { ...s, end };
+    });
+    extents.sort((a, b) => a.start - b.start);
+    const merged: EgressSpan[] = [];
+    for (const s of extents) {
+        const last = merged[merged.length - 1];
+        if (last !== undefined && s.start < last.end) {
+            const keep = CLASS_RANK[s.class] > CLASS_RANK[last.class] ? s : last;
+            merged[merged.length - 1] = { ...keep, start: last.start, end: Math.max(last.end, s.end) };
+        } else {
+            merged.push(s);
+        }
+    }
+    return merged;
+}
+
+/**
+ * Replaces every detected secret with its token, removing each rule's full
+ * replacement extent, not just the bytes that triggered detection. A rule that
+ * cannot prove its extent makes the whole call throw EgressRefusedError: the
+ * text is refused, never partly replaced. A detection is left alone only when it
+ * lies inside a token this scope minted, so a second pass returns the same bytes
+ * while a token-shaped substring planted inside a credential, or a token from
+ * another scope, shields nothing.
+ */
+export function replaceValues(text: string, scope: TokenScope): string {
+    const owned = parseTokens(text).filter((t) => scope.owns(text.slice(t.start, t.end)));
+    const detected = detect(text).filter((s) => !owned.some((t) => t.start <= s.start && s.end <= t.end));
+    const spans = replacementSpans(text, detected);
+    // Mint in text order first: replaceSpans substitutes right to left, and minting
+    // inside its callback would number the last value 1.
+    const tokens = spans.map((s) => scope.mint(s.type, s.class, text.slice(s.start, s.end)));
+    return replaceSpans(text, spans, (_s, i) => tokens[i] as string);
+}

package/src/scripts/_lib/empty_cycles.ts

@@ -2,7 +2,7 @@
  * A double trigger is one event, not two outcomes.
  *
  * Hosts fire the same slot more than once for a single logical event —
- * `run_continuation_hook.ts` documents the same quirk on `stop` and dedupes it
+ * `run_continuation_hook.ts` documented the same quirk on `stop` and deduped it
  * with an ordinal + open-count + short-window key. The consequence here is
  * arithmetic rather than cosmetic: if a duplicate fire writes a second outcome
  * record, every per-asset rate computed over the stream is inflated by exactly

package/src/scripts/_lib/environment_detector.ts

@@ -90,8 +90,12 @@ export type AuthSource = 'cli-subscription' | 'cli-api-key' | 'key-file' | 'env-
  * `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.
+ * `free-quota` — a `base_url` route whose free terms carry a dated proof; USD 0.
+ * `self-hosted` — a loopback route whose probe showed local weights; USD 0.
+ *
+ * `classifyBilling` never returns the last two: only a route resolution can.
  */
-export type BillingClass = 'subscription' | 'per-token';
+export type BillingClass = 'subscription' | 'per-token' | 'free-quota' | 'self-hosted';
 
 /** Version string when parseable, the literal `'unknown'` when not, `null` when unprobed. */
 export type HostVersion = string | 'unknown' | null;
@@ -124,39 +128,50 @@ export interface EnvironmentReport {
 }
 
 /**
- * Provider → (default CLI binary, community-wrapper flag).
+ * One row per provider: the default CLI binary, whether that CLI is a
+ * community wrapper, the environment variable carrying a raw API key, and the
+ * key-file name under the user-global root. Adding a provider is this one
+ * edit; a row missing any field is no provider at all (`providerRow`).
  *
- * Mirrors the `CliClient` subclass attributes without importing the client
- * layer. The boolean is the load-bearing billing input: a VENDOR-OFFICIAL CLI
+ * `community` 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.
+ * shells out to the same paid API and stays metered. Mirrors the `CliClient`
+ * subclass attributes without importing the client layer.
  */
-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],
-};
+export interface ProviderRow {
+    readonly cli: string;
+    readonly community: boolean;
+    readonly envKey: string;
+    readonly keyFile: string;
+}
 
-/** 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',
+export const PROVIDER_TABLE: Readonly<Record<string, ProviderRow>> = {
+    anthropic: { cli: 'claude', community: false, envKey: 'ANTHROPIC_API_KEY', keyFile: 'anthropic.key' },
+    openai: { cli: 'codex', community: false, envKey: 'OPENAI_API_KEY', keyFile: 'openai.key' },
+    gemini: { cli: 'gemini', community: false, envKey: 'GEMINI_API_KEY', keyFile: 'gemini.key' },
+    xai: { cli: 'grok', community: true, envKey: 'XAI_API_KEY', keyFile: 'xai.key' },
+    perplexity: { cli: 'perplexity', community: true, envKey: 'PERPLEXITY_API_KEY', keyFile: 'perplexity.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',
-};
+/** The complete row for `provider`, or null when it is absent or any field is missing. */
+export function providerRow(provider: string, table: Readonly<Record<string, ProviderRow>> = PROVIDER_TABLE): ProviderRow | null {
+    const row = table[provider] as Partial<ProviderRow> | undefined;
+    if (row === undefined) return null;
+    const complete =
+        typeof row.cli === 'string' && row.cli !== '' &&
+        typeof row.community === 'boolean' &&
+        typeof row.envKey === 'string' && row.envKey !== '' &&
+        typeof row.keyFile === 'string' && row.keyFile !== '';
+    return complete ? (row as ProviderRow) : null;
+}
+
+/** Provider → (default CLI binary, community-wrapper flag); a projection of `PROVIDER_TABLE`. */
+export const PROVIDER_CLI_META: Readonly<Record<string, readonly [string, boolean]>> = Object.fromEntries(
+    Object.keys(PROVIDER_TABLE).flatMap((p) => {
+        const row = providerRow(p);
+        return row === null ? [] : [[p, [row.cli, row.community] as const]];
+    }),
+);
 
 /** Providers this module knows how to classify, in a stable order. */
 export function knownProviders(): readonly string[] {
@@ -419,7 +434,7 @@ function detectAuth(opts: DetectEnvironmentOptions): {
             auth.push({ provider, source: cli.source, evidence: cli.evidence });
         }
 
-        const keyFile = PROVIDER_KEY_FILE[provider];
+        const keyFile = providerRow(provider)?.keyFile;
         if (keyFile !== undefined) {
             let resolved: string | null = null;
             try {
@@ -433,7 +448,7 @@ function detectAuth(opts: DetectEnvironmentOptions): {
             }
         }
 
-        const envVar = PROVIDER_ENV_KEY[provider];
+        const envVar = providerRow(provider)?.envKey;
         if (envVar !== undefined && (env[envVar] ?? '').trim() !== '') {
             auth.push({ provider, source: 'env-key', evidence: `env:${envVar}` });
             keys.push({ provider, ref: `env:${envVar}` });

package/src/scripts/_lib/exemption_shape.ts

@@ -91,6 +91,80 @@ export function lemmasNamed(reason: string): string[] {
     return DISPOSITION_LEMMAS.filter((l) => new RegExp(`\\b(?:${l.source})`, 'i').test(reason)).map((l) => l.name);
 }
 
+/**
+ * Does this reason quote the owner search it ran — in ONE clause, a search verb,
+ * what was searched for, where, and an empty result?
+ *
+ * A disposition word says what was rejected; it does not say anyone looked for
+ * an existing owner first, and re-arrival of an owned subject as a new file is
+ * the measured cost. The AI council of 2026-10-16 refused a first version that tested the three parts anywhere in the reason:
+ * "grep was considered; agents/roadmaps contains plans; another check returned
+ * 0 hits" passed and describes no search. So all of it has to sit in one clause
+ * (split on `;` and on a sentence-ending period):
+ *
+ * - a verb — `grep`, `rg`, `find`, searched, scanned — or `roadmap:context`;
+ * - a query — a quoted pattern, or `for <identifiers>`; `roadmap:context`
+ *   carries its own;
+ * - the whole roadmap tree as scope — its root, its `/*` glob, or a brace set
+ *   naming `later` and `stubs`; one subdirectory alone is not a
+ *   search for an owner, and `archive/` owns nothing new (an archived file
+ *   lands nothing);
+ * - an EMPTY result, or one whose every hit is named as a non-owner with
+ *   `only` ("returns only archived files"). A search that found an owner is a
+ *   reason to land the finding there, never to add a file.
+ *
+ * Like the disposition check, this sees that a search is QUOTED, not that it was
+ * run or was a good one. The council's stronger objection — author-written prose
+ * is not provenance — is why this reports and does not refuse.
+ */
+const SEARCH_VERB_RE = /\b(?:grep|rg|ripgrep|find|search(?:ed|es|ing)?|scan(?:ned|s)?)\b|roadmap:context/i;
+const SEARCH_QUERY_RE = /\bfor\s+\S|['"`][^'"`\s][^'"`]*['"`]|roadmap:context/i;
+const SEARCH_SCOPE_RE =
+    /agents\/roadmaps(?:\/\*|\/\{(?=[^}]*\blater\b)(?=[^}]*\bstubs\b)[^}]*\}|\/?(?=[\s,;:)`'"]|$))|roadmap:context/i;
+const SEARCH_EMPTY_RE = new RegExp(
+    [
+        String.raw`\b(?:returns?|returned|found|finds|yield(?:s|ed)?|gives?|gave|match(?:es|ed)?|shows?|showed|lists?|listed)\b[^;]{0,40}?\b(?:nothing|none|no\b|zero|0\b|only\b)`,
+        String.raw`(?:^|[\s(:→>-])(?:0|no|zero)\s+(?:hits?|match(?:es)?|results?|files?|owners?)\b`,
+        String.raw`(?:→|->)\s*(?:nothing|none|no\b|0\b|empty)`,
+    ].join('|'),
+    'i',
+);
+
+/** One clause per `;` or sentence-ending period; a period inside `tokens.json` does not split. */
+function clauses(reason: string): string[] {
+    return reason.split(/;|\.(?=\s|$)/);
+}
+
+/**
+ * `only` followed by a live (non-archived) roadmap file path is a search that
+ * FOUND an owner, unlike "only archived files", which names no owner.
+ */
+const ONLY_NAMES_OWNER_RE = /\bonly\b[^;]*?agents\/roadmaps\/(?!archive\/)[\w.-]+(?:\/[\w.-]+)*\.md\b/i;
+
+export function quotesOwnerSearch(reason: string): boolean {
+    return clauses(reason).some(
+        (c) =>
+            SEARCH_VERB_RE.test(c) &&
+            SEARCH_QUERY_RE.test(c) &&
+            SEARCH_SCOPE_RE.test(c) &&
+            SEARCH_EMPTY_RE.test(c) &&
+            !ONLY_NAMES_OWNER_RE.test(c),
+    );
+}
+
+/**
+ * The added exemptions that quote no owner search. REPORT-ONLY: the estate gate
+ * prints these as warnings and stays green, by the council verdict above, until a
+ * report-only window has been read.
+ */
+export function unsearchedExemptions(
+    exempt: readonly { readonly file: string; readonly reason: string }[],
+): ExemptionFinding[] {
+    return exempt
+        .filter((e) => namesDisposition(e.reason) && !quotesOwnerSearch(e.reason))
+        .map((e) => ({ file: e.file, kind: 'unsearched' as const, twin: null, reason: e.reason }));
+}
+
 /**
  * The comparison key for "two added files say the same thing".
  *
@@ -106,7 +180,7 @@ export function reasonKey(reason: string): string {
 /** One added file whose exemption reason does not hold up. */
 export interface ExemptionFinding {
     readonly file: string;
-    readonly kind: 'shapeless' | 'duplicate';
+    readonly kind: 'shapeless' | 'unsearched' | 'duplicate';
     /** For `duplicate`, the other added file carrying the same reason. */
     readonly twin: string | null;
     readonly reason: string;

package/src/scripts/_lib/floor_posture.ts

@@ -0,0 +1,185 @@
+/**
+ * floor_posture — what stands between a destructive shell command and its
+ * execution on this machine, reported for `hooks:doctor` and written nowhere.
+ *
+ * WHY. The destructive-action floor has two possible carriers on `claude`: the
+ * host's own OS sandbox and this package's `pre_tool_use` hook. Neither is
+ * visible from inside a session. The trampoline in `hooks/hooks.json` exits 0
+ * when it reaches no dispatcher (contracted in `docs/contracts/hook-architecture-v1.md`),
+ * so a machine where no hook runs looks exactly like a session where no hook had
+ * anything to say. This module names that state "floor not running".
+ *
+ * REPORT, NEVER WRITE — the `host_permission_checks` pattern. Sandbox and hook
+ * settings are the consumer's; a doctor that rewrites them has decided their
+ * posture for them. Every key is named on every run, absent included, because
+ * "absent" and "did not look" must not read the same.
+ *
+ * The sandbox keys were read from the Claude Code 2.1.302 binary's own strings
+ * on 2026-10-18: `sandbox.enabled`, `sandbox.failIfUnavailable` ("Exit with an
+ * error at startup if sandbox.enabled is true but the sandbox cannot start") and
+ * `sandbox.allowUnsandboxedCommands`. Managed settings are not read, so a
+ * policy-locked value is reported as whatever the user layers say.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+/** Injected so a test never reads the developer's own machine. */
+export interface FloorPostureDeps {
+    projectRoot: string;
+    homeDir: string;
+    env: NodeJS.ProcessEnv;
+    readFile: (p: string) => string | null;
+    exists: (p: string) => boolean;
+    isExecutable: (p: string) => boolean;
+    onPath: (bin: string) => boolean;
+}
+
+/** Which dispatcher the trampoline would reach, in its own order. */
+export type FloorRuntime = "project-bundle" | "runtime-current" | "cli" | "floor-not-running";
+
+export interface FloorPosture {
+    runtime: FloorRuntime;
+    sandbox: {
+        enabled: boolean | null;
+        failIfUnavailable: boolean | null;
+        allowUnsandboxedCommands: boolean | null;
+    };
+    /** `PreToolUse` hooks in the settings layers that are not this package's dispatcher. */
+    foreignPreToolUseHooks: number;
+    unreadable: string[];
+}
+
+function _executable(p: string): boolean {
+    try {
+        fs.accessSync(p, fs.constants.X_OK);
+        return fs.statSync(p).isFile();
+    } catch {
+        return false;
+    }
+}
+
+/** Default deps — the only place the real filesystem and PATH are touched. */
+export function defaultFloorPostureDeps(projectRoot: string): FloorPostureDeps {
+    const env = process.env;
+    return {
+        projectRoot,
+        homeDir: os.homedir(),
+        env,
+        readFile: (p) => {
+            try {
+                return fs.readFileSync(p, "utf8");
+            } catch {
+                return null;
+            }
+        },
+        exists: (p) => fs.existsSync(p),
+        isExecutable: _executable,
+        onPath: (bin) =>
+            (env["PATH"] ?? "").split(path.delimiter).some((dir) => dir !== "" && _executable(path.join(dir, bin))),
+    };
+}
+
+/**
+ * The trampoline's resolution order, mirrored: the project's own bundle with
+ * `node` on PATH, then the installed runtime's pinned node, then the CLI.
+ */
+function _runtime(deps: FloorPostureDeps): FloorRuntime {
+    const root = deps.projectRoot;
+    const bundle = path.join(root, "node_modules", "@event4u", "agent-config", "dist", "hooks", "dispatch.js");
+    const selfHosted =
+        deps.exists(path.join(root, "dist", "hooks", "dispatch.js")) &&
+        deps.exists(path.join(root, "src", "scripts", "hook_manifest.yaml"));
+    if ((deps.exists(bundle) || selfHosted) && deps.onPath("node")) return "project-bundle";
+
+    const configHome = deps.env["EVENT4U_CONFIG_HOME"] || path.join(deps.homeDir, ".event4u", "agent-config");
+    const current = path.join(configHome, "runtime", "current");
+    const node = (deps.readFile(path.join(current, "node")) ?? "").split("\n")[0]?.trim() ?? "";
+    if (node && deps.isExecutable(node) && deps.exists(path.join(current, "dist", "hooks", "dispatch.js"))) {
+        return "runtime-current";
+    }
+
+    if (deps.isExecutable(path.join(root, "agent-config")) || deps.onPath("agent-config")) return "cli";
+    return "floor-not-running";
+}
+
+function _bool(v: unknown): boolean | null {
+    return typeof v === "boolean" ? v : null;
+}
+
+/**
+ * Is this hook command this package's own dispatcher? The invocation, not a
+ * name: `rewrite-dispatch.js` or a path containing `agent-config` is another
+ * hook, and counting it as ours would hide the warning it exists for.
+ */
+function _ours(command: string): boolean {
+    return /dispatch(?:\.js"?|:hook) --platform claude\b/.test(command);
+}
+
+export function readFloorPosture(deps: FloorPostureDeps): FloorPosture {
+    const layers = [
+        path.join(deps.homeDir, ".claude", "settings.json"),
+        path.join(deps.projectRoot, ".claude", "settings.json"),
+        path.join(deps.projectRoot, ".claude", "settings.local.json"),
+    ];
+    const sandbox: FloorPosture["sandbox"] = { enabled: null, failIfUnavailable: null, allowUnsandboxedCommands: null };
+    const unreadable: string[] = [];
+    let foreign = 0;
+    for (const file of layers) {
+        const raw = deps.readFile(file);
+        if (raw === null) continue;
+        let parsed: Record<string, unknown>;
+        try {
+            parsed = JSON.parse(raw) as Record<string, unknown>;
+        } catch {
+            unreadable.push(file);
+            continue;
+        }
+        const box = parsed["sandbox"];
+        if (box !== null && typeof box === "object") {
+            for (const key of Object.keys(sandbox) as Array<keyof FloorPosture["sandbox"]>) {
+                const value = _bool((box as Record<string, unknown>)[key]);
+                if (value !== null) sandbox[key] = value;
+            }
+        }
+        const hooks = (parsed["hooks"] as Record<string, unknown> | undefined)?.["PreToolUse"];
+        for (const group of Array.isArray(hooks) ? hooks : []) {
+            const entries = (group as Record<string, unknown> | null)?.["hooks"];
+            for (const entry of Array.isArray(entries) ? entries : []) {
+                const command = (entry as Record<string, unknown> | null)?.["command"];
+                if (typeof command === "string" && !_ours(command)) foreign += 1;
+            }
+        }
+    }
+    return { runtime: _runtime(deps), sandbox, foreignPreToolUseHooks: foreign, unreadable };
+}
+
+const RUNTIME_TEXT: Record<FloorRuntime, string> = {
+    // "reaches", not "runs": what was checked is that the trampoline finds a
+    // dispatcher, not that a PreToolUse entry is registered or enabled.
+    "project-bundle": "reaches a dispatcher — the project's own bundle",
+    "runtime-current": "reaches a dispatcher — the installed runtime's",
+    cli: "reaches a dispatcher — through the agent-config CLI",
+    "floor-not-running":
+        "floor not running — the trampoline reaches no dispatcher and exits 0, so no hook runs in a session here",
+};
+
+function _key(name: string, value: boolean | null): string {
+    return `${name}: ${value === null ? "absent" : String(value)}`;
+}
+
+export function renderFloorPosture(p: FloorPosture): string[] {
+    const lines = [
+        `hook runtime: ${RUNTIME_TEXT[p.runtime]}`,
+        _key("sandbox.enabled", p.sandbox.enabled),
+        _key("sandbox.failIfUnavailable", p.sandbox.failIfUnavailable),
+        _key("sandbox.allowUnsandboxedCommands", p.sandbox.allowUnsandboxedCommands),
+        p.foreignPreToolUseHooks === 0
+            ? "other PreToolUse hooks: none in the settings layers"
+            : `other PreToolUse hooks: ${p.foreignPreToolUseHooks} PreToolUse hook(s) not from agent-config — ` +
+              "one may rewrite the command after this package's verdict",
+    ];
+    for (const file of p.unreadable) lines.push(`unreadable: ${file} is not valid JSON`);
+    lines.push("a guardrail, not a security boundary — agent-config never writes these settings");
+    return lines;
+}