vigiles 29.0.0 → 30.0.0

package/dist/core/layout.d.ts

@@ -10,50 +10,111 @@
  * Paths are repo-relative (POSIX-style, `join`-friendly). The Claude Code
  * implementation is `claudeCodeLayout` in `src/adapters/claude-code/layout.ts`.
  */
+import type { InstructionChain } from "./instruction-chain.js";
+import type { SettingsCodec } from "./settings-codec.js";
+/**
+ * The three kinds of MODEL SURFACE — a thing a session can invoke by name.
+ *
+ * Instructions are deliberately not here: an instruction is READ, a surface is
+ * CALLED. That is why {@link PluginLayout.rulesDir} is not a key — counted, not
+ * felt: five of the seven consumers that range over the surfaces would have had
+ * to grow a `kind !== "rules"` branch (the empty-machine decision, the per-kind
+ * counts, the shape table, the known-homes map, `executableSourceDirs`), which
+ * is the per-value branch this record exists to remove.
+ */
+export type SurfaceKind = "skill" | "agent" | "command";
+/**
+ * Where each model surface lives, keyed by kind — repo-relative and COMPLETE
+ * (`.agents/skills`, never `skills` under a root the reader has to remember).
+ *
+ * A kind with no entry is a surface this harness does not have, and that is the
+ * ONLY spelling of "none": there is no `""`.
+ *
+ * 🔴 A RECORD, NOT A LIST, AND NOT A SECOND FIELD BESIDE A LIST. What this
+ * replaced was `surfaceDirs: readonly string[]` standing beside `skillDir`,
+ * `agentDir` and `commandDir` — four places naming the same three directories,
+ * with nothing relating them. `opencodeLayout` disagreed with itself in exactly
+ * the way that invites: `skillDir: ".opencode/skill"` while `surfaceDirs` held
+ * only the agent and command dirs, so OpenCode's skills were named by the port
+ * and never read by anything. With one record there is no second place to
+ * disagree with, `surfaceDirs()` is derived, and a duplicate kind is a
+ * duplicate object key (TS1117) rather than a conformance finding.
+ */
+export type SurfaceDirs = Readonly<Partial<Record<SurfaceKind, string>>>;
+/**
+ * Where one harness keeps the files vigiles reads: its instruction file, its
+ * model surfaces, its hook registrations and settings, plus the env token
+ * expanded to the plugin root. The loader reads all of it from this descriptor
+ * rather than hard-coding one harness's conventions, which is what lets a
+ * second harness be a VALUE passed to the same loader instead of a fork of it.
+ *
+ * 🔴 EVERY FIELD HOLDS ITS FACT ONCE. Four of the fields this interface used to
+ * have were second copies of a fact another field already held — `surfaceDirs`
+ * beside `skillDir`/`agentDir`/`commandDir`, `intraRefDirs` beside both, and
+ * `materializeRoot` beside `userSurfaceRoot` — and nothing related the copies,
+ * so a layout could disagree with itself and no check would see it. One did:
+ * `opencodeLayout` named a skill dir that `surfaceDirs` omitted, and OpenCode's
+ * skills were read by nothing. The copies are now `surfaceDirs()`,
+ * `executableSourceDirs()` and `materializePrefix()` — functions of what is
+ * left, so there is no second place to disagree with.
+ */
 export interface PluginLayout {
     /** Stable identifier, e.g. "claude-code". */
     readonly name: string;
     /** Plugin manifest, e.g. `.claude-plugin/plugin.json`. */
     readonly manifestPath: string;
-    /** Convention path for a standalone hooks file, e.g. `hooks/hooks.json`. */
-    readonly hooksConventionPath: string;
+    /**
+     * The conventional standalone hooks FILE a plugin may ship instead of inline
+     * registrations, e.g. `hooks/hooks.json`. A file, never a directory.
+     *
+     * Optional because OpenCode has no such file — its `.opencode/plugin` is a
+     * DIRECTORY of JS modules, and naming it here made every reader that treats
+     * this as a file (dirname, parse, round-trip) wrong about it.
+     */
+    readonly hooksConventionPath?: string;
     /** Repo settings carrying hooks, e.g. `.claude/settings.json` or `.codex/config.toml`. */
     readonly settingsPath: string;
     /**
-     * How the settings file is encoded — `"json"` (Claude Code's settings.json) or
-     * `"toml"` (Codex's `config.toml` `[hooks]`). The loader dispatches a parser on
-     * it, so a TOML-configured harness's hooks aren't silently read as zero.
+     * How {@link manifestPath} and {@link settingsPath} are ENCODED — a codec,
+     * not a format name. It knows bytes-to-value and nothing about what the value
+     * means; the hooks-entry SHAPE lives on `HookProtocol.registration`.
+     *
+     * 🔴 IT USED TO BE `settingsFormat: "json" | "toml"`, and nine call sites
+     * branched on it. The type had exactly two inhabitants and both were ours, so
+     * a third-party adapter whose settings are YAML could declare nothing the
+     * core would honour — and the conformance kit re-checked the enum, which is
+     * the tell: a data field whose legal values the core already knows is not
+     * data, it is a hidden `switch`. Six of the nine branches were the encoding
+     * and are now `settings.parse` / `settings.render`; three were the entry
+     * shape and moved to the port that owns shapes.
      */
-    readonly settingsFormat: "json" | "toml";
+    readonly settings: SettingsCodec;
     /** Top-level instruction file, e.g. `CLAUDE.md`. */
     readonly instructionFile: string;
-    /** Surface dirs materialized into the sandbox, e.g. skills/agents/commands. */
-    readonly surfaceDirs: readonly string[];
     /**
-     * Project-level dir under which an END-USER (not a plugin author) keeps the
-     * same surfaces, e.g. `.claude` → `.claude/skills`, `.claude/agents`. When set,
-     * the loader reads each surface from BOTH `<root>/<surface>` (the plugin /
-     * skills-library shape) AND `<root>/<userSurfaceRoot>/<surface>` (the shape a
-     * plain Claude Code user has), normalizing to the same materialized key. Most
-     * Claude Code users are NOT publishing a plugin — their skills live here, so
-     * without this the loader would see an empty machine for a normal repo.
-     * Undefined ⇒ only the primary location is read (backwards-compatible).
+     * Where each model surface lives — see {@link SurfaceDirs}. At least one kind
+     * is required (conformance); a kind this harness does not have is an absent
+     * key, never `""`.
      */
-    readonly userSurfaceRoot?: string;
-    /** Skills dir, holding the nested `<dir>/<name>/SKILL.md`, e.g. `skills`. */
-    readonly skillDir: string;
+    readonly surfaces: SurfaceDirs;
     /**
-     * Subagents dir, holding `<dir>/<name>.md` at ANY depth, e.g. `agents`
-     * (`""` = none). The depth rule, and the identifier that depth implies, are
-     * stated once in {@link AGENT_FILE_LEAF_RE} and {@link agentSurfaceName} —
-     * read those before writing a fourth thing that walks this dir.
+     * The dot-directory a plain END USER keeps the same surfaces under, when the
+     * harness has such a second home (`.claude` → `.claude/skills`). When set,
+     * every surface is read from BOTH `<surface>` and `<userSurfaceRoot>/<surface>`,
+     * and this is ALSO the prefix a relocated scope is keyed under.
+     *
+     * 🔴 IT USED TO BE TWO FIELDS. `materializeRoot` sat beside this one and was
+     * EQUAL to it in all three shipped layouts (`.claude`/`.claude`, `""`/absent,
+     * `""`/absent) while having no defined meaning when they differed — the
+     * scope-key guard existed precisely to catch a layout that named `.claude` as
+     * both its materialize root and a second scope's base, and with one field that
+     * state cannot be written. Absent means the surfaces have exactly one home and
+     * file-map keys equal on-disk paths; see {@link materializePrefix}.
      */
-    readonly agentDir: string;
-    /** Slash-commands dir, holding flat `<dir>/<name>.md`, e.g. `commands`. */
-    readonly commandDir: string;
+    readonly userSurfaceRoot?: string;
     /**
      * Path-scoped RULES dir, holding flat `<dir>/<name>.md`, e.g. `rules`
-     * (`""` or absent = this harness has no such layer).
+     * (absent = this harness has no such layer; `""` is refused by conformance).
      *
      * Claude Code loads `.claude/rules/*.md` as project instructions, scoped by a
      * `paths:` frontmatter key. It is an INSTRUCTION surface — often where a
@@ -62,12 +123,67 @@ export interface PluginLayout {
      * adopter reported five such files arriving in a session labelled "project
      * instructions" while `lint` did not mention them at all (#175.3).
      *
-     * Optional and additive: a layout that omits it behaves exactly as before, so
-     * this adds a directory to the existing checks rather than a new check.
+     * Not a {@link SurfaceKind}: an instruction is read, not invoked — see the
+     * docblock there for the count behind that.
      */
     readonly rulesDir?: string;
-    /** Dir the surfaces are materialized under, e.g. `.claude`. */
-    readonly materializeRoot: string;
+    /**
+     * The WORD a per-machine settings sibling inserts before the extension, e.g.
+     * `local` → `.claude/settings.local.json` (absent = this harness has no
+     * per-machine settings layer that we have OBSERVED).
+     *
+     * 🔴 THE CORE USED TO SYNTHESIZE THIS FOR EVERYBODY, and the function it used
+     * says on its own docblock why that cannot be right: "Both vendors name a
+     * per-machine file by inserting a word before the extension, and they choose
+     * DIFFERENT words — Claude Code `local`, Codex `override` — so the word is the
+     * argument and the spelling is not." `settingsSourcePaths` passed `"local"`
+     * unconditionally three lines below it, so a Codex repository holding
+     * `.codex/config.local.toml` had that file read as a real settings layer, and
+     * a `project_doc_fallback_filenames` in it could name an instruction file we
+     * then scored — out of a file the harness never opens. `opencode.local.json`
+     * the same.
+     *
+     * Absence is the honest default: only the adapter knows whether its vendor
+     * has such a layer, and we model what has been observed rather than what is
+     * plausible by analogy. Every other {@link siblingNamed} caller already lives
+     * in an adapter for exactly this reason.
+     */
+    readonly settingsLocalInfix?: string;
+    /**
+     * Which of the instruction-shaped files the DOMAIN enumerated this harness
+     * loads at a repo-root session, in load order — and for every one it does not
+     * load, WHY. Pure: a function of `files` alone, with no root, no `node:`
+     * module and no way to name a path the domain did not open.
+     *
+     * 🔴 IT REPLACED A GLOB MINI-LANGUAGE AND ITS PRIVATE INTERPRETER.
+     * `HarnessDialect.instructionBudget.alwaysLoaded` was an array of globs an
+     * ADAPTER wrote and the CORE walked the repository to expand, so shipping
+     * `"**\/AGENTS.md"` made vigiles read every directory of somebody else's
+     * project. See `./instruction-chain.ts` for the three defects that had, and
+     * for why none of them is expressible as a better glob.
+     *
+     * {@link instructionFile} still names the PRIMARY root file — the one
+     * `compile` writes, `init` scaffolds and `detect` scores. Whether it is in the
+     * loaded chain, and what else is, is this method's answer and never that
+     * field's.
+     */
+    instructionChain(files: Readonly<Record<string, string>>): InstructionChain;
+    /**
+     * The directory a plugin keeps its EXECUTABLE HOOK SCRIPTS in (`hooks`) —
+     * distinct from where the hooks are REGISTERED ({@link hooksConventionPath},
+     * {@link settingsPath}). Absent means the harness has no scripts directory to
+     * scan (OpenCode's hooks are in-process code modules).
+     *
+     * 🔴 IT REPLACES TWO AD-HOC DERIVATIONS AND ONE HAND-WRITTEN LIST, which is
+     * why it is a field rather than something computed at each site. The list was
+     * `intraRefDirs`, written out per layout and therefore free to disagree with
+     * the surfaces beside it (on `opencode` it did, dropping the skill dir). The
+     * derivations were `hooksConventionPath.split("/")[0]`, copied into `scan.ts`
+     * and `scan-files.ts` — which reads `hooks` from `hooks/hooks.json` but
+     * `.codex` from `.codex/hooks.json`, i.e. it did not name a scripts directory
+     * at all for Codex. Both are now {@link executableSourceDirs}.
+     */
+    readonly hookScriptsDir?: string;
     /** Env token expanded to the plugin's absolute root in hook commands. */
     readonly pluginRootToken: string;
     /**
@@ -87,9 +203,37 @@ export interface PluginLayout {
     readonly mcpConfigFile: string;
     /** Manifest key declaring MCP servers, e.g. `mcpServers`. */
     readonly mcpManifestKey: string;
-    /** Dirs scanned for dangling intra-plugin file references. */
-    readonly intraRefDirs: readonly string[];
 }
+/** The kinds, in the order every derived list emits them. Iterating a record's
+ *  own keys would make the output depend on literal order in each layout; this
+ *  makes it depend on nothing. */
+export declare const SURFACE_KINDS: readonly ["skill", "agent", "command"];
+/**
+ * Every surface dir a layout declares — what the `surfaceDirs` FIELD used to
+ * be, minus the possibility of disagreeing with the per-kind fields, because
+ * there are no per-kind fields left to disagree with.
+ */
+export declare function surfaceDirs(layout: PluginLayout): readonly string[];
+/**
+ * Dirs whose non-prose files are scanned for intra-plugin references, and
+ * checked for misplacement inside the manifest dir: the surfaces plus
+ * {@link PluginLayout.hookScriptsDir}.
+ *
+ * Equal to the old hand-written `intraRefDirs` as a SET on Claude Code and
+ * Codex; on `opencode` it gains `.opencode/skill`, which the hand list had left
+ * out along with the rest of that layout's skill surface.
+ */
+export declare function executableSourceDirs(layout: PluginLayout): readonly string[];
+/**
+ * The prefix a relocated surface is keyed under — `userSurfaceRoot` when the
+ * harness has a second home for its surfaces, `""` when the surfaces carry
+ * their own prefix and a file-map key equals the on-disk path.
+ *
+ * One line, named, because it used to be a FIELD (`materializeRoot`) and the
+ * only thing that kept it equal to `userSurfaceRoot` was that nobody had
+ * written a layout where they differed.
+ */
+export declare function materializePrefix(layout: PluginLayout): string;
 /**
  * How DEEP a harness reads its {@link PluginLayout.agentDir} — the one statement
  * of that rule, as a RegExp source fragment matching the part of a path AFTER
@@ -120,6 +264,49 @@ export interface PluginLayout {
  * this. A fourth reader that hard-codes a depth is the defect coming back.
  */
 export declare const AGENT_FILE_LEAF_RE = "(?:.+/)?[^/]+\\.md";
+/**
+ * How DEEP a harness reads its {@link PluginLayout.rulesDir} — the one statement
+ * of that rule, as a RegExp source fragment matching the part of a path AFTER
+ * `<rulesDir>/`. Same shape and same reason as {@link AGENT_FILE_LEAF_RE}.
+ *
+ * 🔴 IT USED TO SAY `[^/]+`, in the scan classifier, while the loader walked the
+ * directory recursively — so a rule in a subdirectory was READ and never
+ * CLASSIFIED, which means it was never frontmatter-checked, never counted and
+ * never weighed. Verbatim from the vendor page (`code.claude.com/docs/en/memory`,
+ * quoted in zernie/vigiles#262): rules directories are read recursively, "all
+ * `.md` files are discovered recursively".
+ *
+ * The two readers are the scan classifier (`makeClassifier`, scan-core.ts) and
+ * the instruction chain (`core/instruction-chain.ts` implementations). They
+ * quote this instead of each spelling the rule, for the reason the agent
+ * constant above records: two readers that each spell it disagree silently.
+ */
+export declare const RULE_FILE_LEAF_RE = "(?:.+/)?[^/]+\\.md";
+/**
+ * The WHOLE rule-file matcher for a layout — the prefix as well as the leaf.
+ *
+ * 🔴 THE LEAF WAS SHARED AND THE PREFIX WAS NOT, so the two readers the constant
+ * above names went on disagreeing about the half it did not cover. Both spelled
+ * it `(?:^|/)<rulesDir>/`, which is deliberately loose for SURFACES — Claude
+ * Code reads `skills/` at a published plugin's root AND at `.claude/skills`, two
+ * legitimate homes — and wrong for RULES, which have exactly one home. Measured
+ * on the instruction chain at 2026-09-22:
+ *
+ *   loaded: CLAUDE.md · .claude/rules/mine.md · .github/rules/policy.md
+ *                                             · .agents/rules/policy.md
+ *
+ * The bound walks every depth-1 dot-directory's `rules` tree, so ANY of them
+ * matched — 8,000 characters of somebody else's policy charged to the
+ * always-loaded budget and able to push the report over it. Not one foreign
+ * directory, as the review that found it supposed: all of them.
+ *
+ * Anchoring is what {@link PluginLayout.rulesDir} already says in prose —
+ * "Claude Code loads `.claude/rules/*.md`" — and the prefix is built from
+ * `userSurfaceRoot` so that moving either field moves both readers at once.
+ * `null` when the layout declares no rules layer.
+ */
+export declare function rulesHome(layout: Pick<PluginLayout, "rulesDir" | "userSurfaceRoot">): string | null;
+export declare function ruleFileRe(layout: Pick<PluginLayout, "rulesDir" | "userSurfaceRoot">): RegExp | null;
 /**
  * A subagent's identity, per the same docs paragraph: the path under
  * `<agentDir>/` with `/` → `:` and the `.md` dropped, so plugin

package/dist/core/layout.js

@@ -1,7 +1,51 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AGENT_FILE_LEAF_RE = void 0;
+exports.RULE_FILE_LEAF_RE = exports.AGENT_FILE_LEAF_RE = exports.SURFACE_KINDS = void 0;
+exports.surfaceDirs = surfaceDirs;
+exports.executableSourceDirs = executableSourceDirs;
+exports.materializePrefix = materializePrefix;
+exports.rulesHome = rulesHome;
+exports.ruleFileRe = ruleFileRe;
 exports.agentSurfaceName = agentSurfaceName;
+/** The kinds, in the order every derived list emits them. Iterating a record's
+ *  own keys would make the output depend on literal order in each layout; this
+ *  makes it depend on nothing. */
+exports.SURFACE_KINDS = ["skill", "agent", "command"];
+/**
+ * Every surface dir a layout declares — what the `surfaceDirs` FIELD used to
+ * be, minus the possibility of disagreeing with the per-kind fields, because
+ * there are no per-kind fields left to disagree with.
+ */
+function surfaceDirs(layout) {
+    return exports.SURFACE_KINDS.map((k) => layout.surfaces[k]).filter((d) => d !== undefined);
+}
+/**
+ * Dirs whose non-prose files are scanned for intra-plugin references, and
+ * checked for misplacement inside the manifest dir: the surfaces plus
+ * {@link PluginLayout.hookScriptsDir}.
+ *
+ * Equal to the old hand-written `intraRefDirs` as a SET on Claude Code and
+ * Codex; on `opencode` it gains `.opencode/skill`, which the hand list had left
+ * out along with the rest of that layout's skill surface.
+ */
+function executableSourceDirs(layout) {
+    const dirs = surfaceDirs(layout);
+    return layout.hookScriptsDir === undefined
+        ? dirs
+        : [...dirs, layout.hookScriptsDir];
+}
+/**
+ * The prefix a relocated surface is keyed under — `userSurfaceRoot` when the
+ * harness has a second home for its surfaces, `""` when the surfaces carry
+ * their own prefix and a file-map key equals the on-disk path.
+ *
+ * One line, named, because it used to be a FIELD (`materializeRoot`) and the
+ * only thing that kept it equal to `userSurfaceRoot` was that nobody had
+ * written a layout where they differed.
+ */
+function materializePrefix(layout) {
+    return layout.userSurfaceRoot ?? "";
+}
 /**
  * How DEEP a harness reads its {@link PluginLayout.agentDir} — the one statement
  * of that rule, as a RegExp source fragment matching the part of a path AFTER
@@ -32,6 +76,76 @@ exports.agentSurfaceName = agentSurfaceName;
  * this. A fourth reader that hard-codes a depth is the defect coming back.
  */
 exports.AGENT_FILE_LEAF_RE = "(?:.+/)?[^/]+\\.md";
+/**
+ * How DEEP a harness reads its {@link PluginLayout.rulesDir} — the one statement
+ * of that rule, as a RegExp source fragment matching the part of a path AFTER
+ * `<rulesDir>/`. Same shape and same reason as {@link AGENT_FILE_LEAF_RE}.
+ *
+ * 🔴 IT USED TO SAY `[^/]+`, in the scan classifier, while the loader walked the
+ * directory recursively — so a rule in a subdirectory was READ and never
+ * CLASSIFIED, which means it was never frontmatter-checked, never counted and
+ * never weighed. Verbatim from the vendor page (`code.claude.com/docs/en/memory`,
+ * quoted in zernie/vigiles#262): rules directories are read recursively, "all
+ * `.md` files are discovered recursively".
+ *
+ * The two readers are the scan classifier (`makeClassifier`, scan-core.ts) and
+ * the instruction chain (`core/instruction-chain.ts` implementations). They
+ * quote this instead of each spelling the rule, for the reason the agent
+ * constant above records: two readers that each spell it disagree silently.
+ */
+exports.RULE_FILE_LEAF_RE = "(?:.+/)?[^/]+\\.md";
+/**
+ * The WHOLE rule-file matcher for a layout — the prefix as well as the leaf.
+ *
+ * 🔴 THE LEAF WAS SHARED AND THE PREFIX WAS NOT, so the two readers the constant
+ * above names went on disagreeing about the half it did not cover. Both spelled
+ * it `(?:^|/)<rulesDir>/`, which is deliberately loose for SURFACES — Claude
+ * Code reads `skills/` at a published plugin's root AND at `.claude/skills`, two
+ * legitimate homes — and wrong for RULES, which have exactly one home. Measured
+ * on the instruction chain at 2026-09-22:
+ *
+ *   loaded: CLAUDE.md · .claude/rules/mine.md · .github/rules/policy.md
+ *                                             · .agents/rules/policy.md
+ *
+ * The bound walks every depth-1 dot-directory's `rules` tree, so ANY of them
+ * matched — 8,000 characters of somebody else's policy charged to the
+ * always-loaded budget and able to push the report over it. Not one foreign
+ * directory, as the review that found it supposed: all of them.
+ *
+ * Anchoring is what {@link PluginLayout.rulesDir} already says in prose —
+ * "Claude Code loads `.claude/rules/*.md`" — and the prefix is built from
+ * `userSurfaceRoot` so that moving either field moves both readers at once.
+ * `null` when the layout declares no rules layer.
+ */
+function rulesHome(layout) {
+    const dir = layout.rulesDir;
+    if (dir === undefined || dir === "")
+        return null;
+    const root = layout.userSurfaceRoot;
+    return root === undefined || root === "" ? dir : `${root}/${dir}`;
+}
+function ruleFileRe(layout) {
+    // 🔴 THREE READERS, ONE SPELLING. The regexp here, the disk walk in
+    // `surface-discovery-fs.ts` and the bound in `core/instruction-chain.ts` all
+    // need "where does this layout keep its rules"; each one spelling it
+    // separately is how #271 happened — the walk joined `<base>/<rulesDir>` for
+    // EVERY dot-directory while this anchored to one, so the pair disagreed about
+    // a repository they were both handed. `rulesHome` is that answer, once.
+    const under = rulesHome(layout);
+    return under === null
+        ? null
+        : new RegExp(`^${escapeRe(under)}/${exports.RULE_FILE_LEAF_RE}$`);
+}
+/**
+ * ⚠️ The fourth copy of this three-liner in `src/` (`core/linters.ts`,
+ * `rule-inventory.ts`, `tool-intercept.ts`, `test-coverage-files.ts` hold the
+ * others). Consolidating them is its own change with its own callers to walk;
+ * duplicating it here is the smaller of two wrongs while the subject is a
+ * measured over-report.
+ */
+function escapeRe(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
 /**
  * A subagent's identity, per the same docs paragraph: the path under
  * `<agentDir>/` with `/` → `:` and the `.md` dropped, so plugin

package/dist/core/lethal-trifecta.d.ts

@@ -181,12 +181,17 @@ export declare function skillFenceLegs(disallowed: readonly string[], dialect: H
 /**
  * Whether THIS harness understands a skill-level `disallowed-tools:` at all.
  *
- * Read off the dialect record that already exists — `skillFrontmatter` is exactly
- * "which SKILL.md keys this harness understands", and `disallowed-tools` is one of
- * the Claude-Code-only ones. No new capability flag: a second field saying the
- * same thing is a second thing to keep true, and the compiler already branches on
- * this one (`renderSkillFrontmatter` emits the tool keys under `"claude-code"` and
- * omits them under `"minimal"`).
+ * Read off the dialect record that already exists — `skillFrontmatterKeys` is
+ * exactly "which SKILL.md keys this harness reads", so the question "is there a
+ * fence here?" is the membership of the one key that IS the fence. No new
+ * capability flag: a second field saying the same thing is a second thing to
+ * keep true, and the compiler already emits from this one.
+ *
+ * 🔴 IT USED TO ASK THE WRONG QUESTION. The body was
+ * `dialect.skillFrontmatter === "claude-code"` — a harness name standing in for
+ * a key, which made a harness that read `disallowed-tools:` under any other name
+ * unfenceable by construction. The function already HAD its capability name;
+ * only the fact it read was wrong.
  */
 export declare function dialectSupportsSkillFence(dialect: HarnessDialect): boolean;
 /**
@@ -197,7 +202,7 @@ export declare function dialectSupportsSkillFence(dialect: HarnessDialect): bool
  * the block comment above for the measurement).
  *
  * 🔴 AND IT IS A CLAUDE-CODE MECHANISM, which this applied to every harness. On a
- * Codex repo (`skillFrontmatter: "minimal"` — name + description only, and our own
+ * Codex repo (`skillFrontmatterKeys: ["name", "description"]` — and our own
  * compiler drops the tool keys there) every skill was reported as holding all
  * three legs, scored against Safety, and handed the remedy "add a
  * `disallowed-tools:` line". That line is INERT in Codex: the author does the

package/dist/core/lethal-trifecta.js

@@ -537,15 +537,20 @@ const PREAPPROVAL_NOTE = "`allowed-tools:` does NOT fence a skill — it PRE-APP
 /**
  * Whether THIS harness understands a skill-level `disallowed-tools:` at all.
  *
- * Read off the dialect record that already exists — `skillFrontmatter` is exactly
- * "which SKILL.md keys this harness understands", and `disallowed-tools` is one of
- * the Claude-Code-only ones. No new capability flag: a second field saying the
- * same thing is a second thing to keep true, and the compiler already branches on
- * this one (`renderSkillFrontmatter` emits the tool keys under `"claude-code"` and
- * omits them under `"minimal"`).
+ * Read off the dialect record that already exists — `skillFrontmatterKeys` is
+ * exactly "which SKILL.md keys this harness reads", so the question "is there a
+ * fence here?" is the membership of the one key that IS the fence. No new
+ * capability flag: a second field saying the same thing is a second thing to
+ * keep true, and the compiler already emits from this one.
+ *
+ * 🔴 IT USED TO ASK THE WRONG QUESTION. The body was
+ * `dialect.skillFrontmatter === "claude-code"` — a harness name standing in for
+ * a key, which made a harness that read `disallowed-tools:` under any other name
+ * unfenceable by construction. The function already HAD its capability name;
+ * only the fact it read was wrong.
  */
 function dialectSupportsSkillFence(dialect) {
-    return dialect.skillFrontmatter === "claude-code";
+    return dialect.skillFrontmatterKeys.includes("disallowed-tools");
 }
 /**
  * The lethal-trifecta finding for a MODEL-INVOCABLE SKILL, computed from its
@@ -555,7 +560,7 @@ function dialectSupportsSkillFence(dialect) {
  * the block comment above for the measurement).
  *
  * 🔴 AND IT IS A CLAUDE-CODE MECHANISM, which this applied to every harness. On a
- * Codex repo (`skillFrontmatter: "minimal"` — name + description only, and our own
+ * Codex repo (`skillFrontmatterKeys: ["name", "description"]` — and our own
  * compiler drops the tool keys there) every skill was reported as holding all
  * three legs, scored against Safety, and handed the remedy "add a
  * `disallowed-tools:` line". That line is INERT in Codex: the author does the

package/dist/core/live-driver.d.ts

@@ -0,0 +1,137 @@
+/**
+ * HarnessLiveDriver — how vigiles drives THIS harness against a REAL model on
+ * the user's own credentials, as `HarnessTestDriver` (`./harness-driver.js`) is
+ * the same seam for the MOCK tiers.
+ *
+ * 🔴 IT IS WHAT `scan-behavioral.ts:buildProbe` BUILT BY SWITCHING ON A NAME.
+ * That function answered four questions — which eval driver, how firing shows
+ * in the trace, may the probe stub the bodies, is the runner reachable — and
+ * answered all four from `harness === "codex"`. The switch is gone because each
+ * adapter now brings the object; `ProbeHarness`, the hand-written
+ * `"claude-code" | "codex"` union it switched on, is gone with it.
+ *
+ * ⚠️ AND IT IS DELIBERATELY NOT FOUR BOOLEANS ON THE ADAPTER. A flag is a
+ * legitimate capability only when it cannot disagree with the ports the adapter
+ * already carries; a `skillFiring: boolean` beside an eval driver can, and a
+ * `tsc` probe shows the type cannot relate them (an adapter carrying the Codex
+ * eval driver and `skillFiring: true` compiles clean). That is the `subagents`
+ * argument at `./adapter.ts` pointing the other way: there is a port here, so
+ * the port is the thing, and the boolean would be a second copy of a fact the
+ * port already holds. See `docs/design/port-redesign-names-half-2026-09-22.md`.
+ */
+import type { EvalDriver, Trace } from "./eval-driver.js";
+/**
+ * Whether a REAL model is reachable for the executing tiers, and on whose bill.
+ *
+ * A tagged union rather than a boolean because the CLI acts on all three arms
+ * differently: it SKIPS on `none` (printing `fix`), RUNS on the other two, and
+ * words the consent prompt "spends API credits" only on `metered`. A boolean
+ * would have forced the wording question back onto a second predicate, which is
+ * exactly the pair it replaces.
+ *
+ * WHAT THIS REPLACES: a per-harness name check OR-ed with one harness's env-var
+ * knowledge, plus the two literal "authenticate … or set …" strings that printed
+ * for every harness regardless of which one was driving.
+ */
+export type ModelAccess = {
+    readonly kind: "none";
+    /** One line: what is missing, in THIS harness's words — the sentence the
+     *  CLI prints instead of running. It names this harness's binary and
+     *  credential, so a repo on one harness is never told to authenticate
+     *  another one's CLI. */
+    readonly fix: string;
+}
+/** Reachable on a plan the user already pays for: $0 metered for this run. */
+ | {
+    readonly kind: "subscription";
+}
+/** Reachable on a per-token key: this run bills. The consent prompt says so. */
+ | {
+    readonly kind: "metered";
+};
+/**
+ * How a skill's FIRING shows up in this harness's eval trace.
+ *
+ * `event` — a discrete skill-selection record in the trace, which the
+ * selection-collision matrix and the adversarial gate REQUIRE: they ask "WHICH
+ * skill fired", and an inference cannot answer that.
+ *
+ * `inferred` — no such record, so firing is deduced from something else the
+ * model did (reading the skill's instruction file, say), which can be wrong in
+ * BOTH directions. `caveat` is the sentence a report prints above an inferred
+ * number, so a possibly-wrong figure never reads as a measurement.
+ *
+ * The same fact as `EvalDriver.experimental` (a public field, kept for
+ * compatibility); `adapter-contract.test.ts` asserts the two agree.
+ */
+export type SkillFiringSignal = {
+    readonly kind: "event";
+} | {
+    readonly kind: "inferred";
+    readonly caveat: string;
+};
+/**
+ * The executing tiers' driver for one harness.
+ *
+ * 🔴 IT LIVES IN THE `harnessTesting: true` ARM, NOT BEHIND A FLAG OF ITS OWN.
+ * On every implementation in this repo live-eval ⇔ mock-testable, and the
+ * capability's own docblock already claims both ("deterministic harness tests +
+ * evals"). A second flag equal to the first everywhere is the defect this port
+ * redesign keeps removing — a fact stored twice with nothing relating the
+ * copies. If a harness ever goes live WITHOUT going mockable (a closed CLI with
+ * its own fixed model), split the arm then; today that shape has zero
+ * implementations and splitting it now would freeze a guess into the type.
+ */
+export interface HarnessLiveDriver {
+    /** The runner + parser that spawn the real binary and read its stream. */
+    readonly evalDriver: EvalDriver;
+    /**
+     * See {@link ModelAccess}. Read from `env` where the harness allows it
+     * (never a spent token); a binary probe where it does not. Takes the
+     * environment rather than reading `process.env` so the decision is testable
+     * and the adapter holds no ambient state.
+     */
+    access(env: Readonly<Record<string, string | undefined>>): ModelAccess;
+    /** See {@link SkillFiringSignal}. */
+    readonly firing: SkillFiringSignal;
+    /**
+     * The predicate "did `skill` fire" over one trace.
+     *
+     * `plugin.name` is the manifest name the DOMAIN read (some harnesses namespace
+     * a plugin's skill as `<plugin>:<skill>`, others use the bare name); it is
+     * HANDED IN, so this method reads no disk — the same bound `claims` and
+     * `detect` keep, for the same reason.
+     */
+    firedFor(skill: string, plugin: {
+        readonly name: string | null;
+    }): (t: Trace) => boolean;
+    /**
+     * May the probe rebuild the plugin to skills-only STUBS before measuring?
+     *
+     * `false` means the real bodies are installed. That is a MEASURED LIMITATION,
+     * not a capability: stubbing a plugin whose shape the harness did not define
+     * is unvalidated, so the honest answer is to install the real skills and
+     * detect firing regardless of body. Named here rather than keyed by harness
+     * name in the probe, which is where it used to live.
+     */
+    readonly installsStubs: boolean;
+}
+/**
+ * A live driver whose firing signal is a discrete EVENT — the only accepted
+ * argument for the selection-collision matrix and the adversarial gate, which
+ * cannot be computed from an inference.
+ */
+export type EventFiringDriver = HarnessLiveDriver & {
+    readonly firing: {
+        readonly kind: "event";
+    };
+};
+/**
+ * Narrows the DRIVER, which an inline `d.firing.kind === "event"` does not:
+ * TypeScript narrows the discriminated PROPERTY, so the driver itself stays
+ * `HarnessLiveDriver` and passing it where an {@link EventFiringDriver} is
+ * wanted is still an error (measured — probe P2 in the design doc). The
+ * negative arm keeps its `caveat`, which is what the n/a note prints.
+ */
+export declare function isEventFiring(d: HarnessLiveDriver): d is EventFiringDriver;
+//# sourceMappingURL=live-driver.d.ts.map