@open-everywhere/core 0.1.0

package/scripts/eve-framework-tools.ts

@@ -0,0 +1,367 @@
+// eve-framework-tools — THE ONE READER for "which tools does the installed eve mount, and how".
+//
+// WHY THIS FILE EXISTS (OPE-1258). Until eve 0.45.0 the answer came from three accessors on
+// `dist/src/runtime/framework-tools/index.js` — `getAllFrameworkToolNames`,
+// `getFrameworkToolDefinitions` and `getOptInFrameworkToolNames`. eve 0.45.0 deleted that module
+// outright. Six OE call sites deep-imported it by absolute path, so on the bump they did not fail
+// closed as their comments claimed: an unresolved dynamic import THROWS, and `lint:window-gate`
+// died before it checked anything. Six copies of the same seam also meant six chances to drift.
+//
+// THE REPLACEMENT SEAM. eve now declares its framework tools as PROGRAMMATIC AGENT SOURCES:
+// `dist/src/framework/sources/registry.js` exports `frameworkAgentSourceRegistry`, whose
+// `registrations` list carries, per source, an `applyTo` scope and the virtual modules that source
+// contributes. A framework tool is a module whose `logicalPath` is `tools/<name>.ts`. That is eve's
+// own enumeration, read off the installed package on every run, so a new eve tool arms the lint
+// with no edit here — the property the deleted accessors had, and the reason this is a re-location
+// rather than a hard-coded list.
+//
+//   `applyTo: "all-local-nodes"` → mounted by DEFAULT on every node. Reproduces
+//                                  `getFrameworkToolDefinitions()`, plus `connection_search`,
+//                                  which eve now declares as a default source module rather than
+//                                  registering separately (0.44.3 omitted it from every accessor
+//                                  and OE appended it by hand at each call site).
+//   `applyTo: "root"`            → the root-only delegation verb, `agent`. 0.44.3 put it in
+//                                  `getAllFrameworkToolNames()` and in NEITHER mount set, so it
+//                                  classified "unknown". It still does: this reader reports it
+//                                  in `all` and in neither set.
+//                                  🔴 THE TASK VERB IS NO LONGER HERE. eve 0.51.0 moved
+//                                  `task_cancel` out of the root source and into
+//                                  `all-local-nodes`, so it classifies "default" now and every
+//                                  declared subagent mounts it. scripts/subagents-lint.ts demands
+//                                  a `disableTool()` sentinel for it; a reader who trusted the
+//                                  old sentence would delete that file as spurious. `task_update`
+//                                  made the same move and eve 0.54.1 then deleted the tool.
+//
+// A SECOND AXIS, CROSSING THE MOUNT CLASSES: REQUIRED. eve 0.52.0 added
+// `compiler/default-tool-policy.js`, which names default-mounted slots an app may NOT disable —
+// `connection_search` today. That is not a mount class; it says how a slot must be taken over, not
+// where it mounts. `required` reports it, and {@link readRequiredFrameworkToolSlots} explains why it
+// is read from the bytes and which direction each failure falls.
+//
+// THE ONE SET WITH NO ACCESSOR EQUIVALENT: OPT-IN. eve ships `glob` and `grep` as tools an app must
+// opt into, but 0.46.x records that nowhere machine-readable — they are simply absent from the
+// registry. The public exports map is NOT a substitute: `./tools/sleep` has been exported since
+// 0.44.3 while eve's own `getOptInFrameworkToolNames()` never listed `sleep`, so deriving opt-in
+// from the exports map would invent a framework tool. So the opt-in half is a COMMITTED SNAPSHOT,
+// asserted against the installed dist on every run (the model-catalog-snapshot pattern).
+//
+// 🔴 WHAT FAILS CLOSED, AND WHAT THROWS — the two are not the same, and the difference is the whole
+// safety argument:
+//
+//   * A BROKEN `all` IS FAIL-OPEN. If this reader cannot enumerate eve's tools, the lint checks
+//     nothing and passes. That is the exact failure the deleted accessors caused. So THREE
+//     conditions throw: a registry that does not load, one that yields no tools, and one that
+//     registers tools under an `applyTo` scope this reader cannot classify. The third matters most,
+//     because it is the one that looks healthy: both known sets stay non-empty while the new scope's
+//     tools quietly leave every lint's surface. `all` is therefore built from every name the
+//     registry contains, never from the scopes this file happens to recognise.
+//   * A BROKEN OPT-IN SET IS FAIL-CLOSED. `classifyFrameworkTools` maps every name to "unknown"
+//     when either mount set is `undefined`, and "unknown" DEMANDS a `disableTool()` sentinel. So a
+//     snapshot that stops matching the installed dist returns `optIn: undefined` and the lint gets
+//     stricter, never quieter. {@link readEveFrameworkTools} reports why in `optInDrift`.
+//
+// An opt-in tool eve adds that this snapshot does not know is omitted from `all`. That is
+// behaviourally identical to the old accessors: an opt-in name the app never opts into classified
+// "opt-in", which excused it from the sentinel demand anyway. Only the DEFAULT set arms rule 4, and
+// the default set is read live.
+
+// 🔴 GATES AND CLIs ONLY — NEVER IMPORT THIS FROM A RUNTIME MODULE. It reaches `node_modules/eve`
+// by absolute path, and the hosted Vercel bundle ships no `node_modules/eve` at all: eve inlines the
+// app into one `index.mjs`. A runtime import would therefore throw on the deployed instance and pass
+// every source-checkout test — the OPE-1041 failure class that `EVE_RUNTIME_VERSION`
+// (channels/runtime-rotation.ts) exists to avoid. Every caller today is a lint, a test or `oe-cli`.
+//
+// THE LOCATION IS THE INVARIANT (OPE-1270). This module sits in `packages/core/scripts/`, not in
+// `agent/`, and that is what enforces the rule above — a header alone enforced nothing. Two things
+// follow from the path and neither needs a new gate:
+//   • `scripts/publish-exports-generate.ts` derives every `exports` entry from `agent/**`, so this
+//     module is no longer on the published subpath map. A consumer cannot import it at all.
+//   • `scripts/hosted-externals-lint.ts` scans RUNTIME_SRC_DIRS — `packages/core/agent`,
+//     `packages/adapters/agent`, `agent`, `packages/providers/*/agent`. This path is in none of
+//     them, so the dynamic import below needs no `hosted-inline-exempt` marker.
+// 🔴 MOVING THIS FILE BACK UNDER `agent/` SILENTLY RESTORES BOTH HAZARDS. Keep it here.
+//
+// 🔴 AND THE PATH COSTS ONE THING, which `package.json`'s `files` array pays: a `scripts/**` file is
+// NOT in the tarball unless it is listed by name. `scripts/oe-cli.ts` — a published bin — imports
+// this module STATICALLY, so a missing entry is `ERR_MODULE_NOT_FOUND` at module load on every `oe`
+// subcommand, invisible to every workspace test because the workspace never reads a tarball.
+// `lint:publish` is the only gate that sees it, and it does: it names this exact import. If this
+// file is ever renamed, rename its `files` entry in the same commit.
+
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+/** eve's dist path for the framework tool source registry, relative to the package root. */
+const REGISTRY_PATH = "dist/src/framework/sources/registry.js";
+
+/** eve's dist path for the default-tool policy, which declares the slots it REFUSES to let an app
+ *  disable. Relative to the package root. */
+const POLICY_PATH = "dist/src/compiler/default-tool-policy.js";
+
+/** The committed opt-in snapshot, pinned against eve 0.54.3. Asserted on every run — never trusted. */
+const OPT_IN_SNAPSHOT = ["glob", "grep"] as const;
+
+/** The shape this reader needs off eve's registry. Everything else on it is ignored. */
+interface FrameworkSourceRegistry {
+  readonly registrations: readonly {
+    readonly applyTo: string;
+    readonly source: { readonly modules: readonly { readonly logicalPath: string }[] };
+  }[];
+}
+
+export interface EveFrameworkTools {
+  /** Every framework tool name the installed eve can mount, in sorted order. Never empty. */
+  readonly all: readonly string[];
+  /** The names eve mounts on every node without the app asking. Never empty. */
+  readonly defaultMounted: readonly string[];
+  /** The opt-in names, or `undefined` when the snapshot no longer matches the installed dist. */
+  readonly optIn: readonly string[] | undefined;
+  /** The root-only names — reported for readers that want them; in neither mount set. */
+  readonly rootOnly: readonly string[];
+  /** Why `optIn` is `undefined`, for a gate that wants to say so out loud. */
+  readonly optInDrift: string | undefined;
+  /**
+   * The names eve's `REQUIRED_FRAMEWORK_TOOL_SLOTS` declaration lists, sorted. Empty when the
+   * installed eve declares no such policy. A name here needs an authored REPLACEMENT tool, never a
+   * `disableTool()` sentinel — see {@link readRequiredFrameworkToolSlots}.
+   *
+   * 🔴 THIS IS THE DECLARED SET, NOT THE ENFORCED ONE, AND TODAY THEY ARE NOT THE SAME MECHANISM.
+   * eve 0.54.3's `assertFrameworkToolPolicy` refuses a SENTINEL by comparing the slot against ONE
+   * HARDCODED LITERAL (`"tools/connection_search"`); the set itself is read only by
+   * `applyDefaultToolPolicy`, which uses it to keep a required slot in the graph when an app turns
+   * the framework defaults off. The two coincide because the set has one member. A second member
+   * added without extending the throw would appear here as required while a sentinel for it stayed
+   * legal — see {@link readRequiredFrameworkToolSlots} for what must be re-read first.
+   */
+  readonly required: readonly string[];
+}
+
+/**
+ * Read the framework tool slots eve DECLARES required.
+ *
+ * 🔴 THE DECLARATION AND THE REFUSAL ARE TWO DIFFERENT BYTES IN eve 0.54.3. Only
+ * `applyDefaultToolPolicy` reads `REQUIRED_FRAMEWORK_TOOL_SLOTS`. The refusals live in
+ * `assertFrameworkToolPolicy`, and at 0.54.3 there are TWO of them, on different source kinds:
+ *   • a `disableTool()` SENTINEL is refused for `"tools/connection_search"` and for nothing else;
+ *   • a `kind: "tool"` REPLACEMENT is refused for `"tools/agent"` and `"tools/task_cancel"` unless
+ *     its `behavior.handling` is a dispatch to that slot's own action (`self-agent`, `task-cancel`).
+ * So this reader answers "eve says this slot is required", never "eve would throw here". RE-READ
+ * `assertFrameworkToolPolicy` BEFORE AUTHORING A REPLACEMENT FOR A SECOND SLOT: a no-op replacement
+ * for `tools/agent` or `tools/task_cancel` throws at `eve build` even though a sentinel for them is
+ * legal. If neither throw names the slot, a `disableTool()` sentinel is still legal there, and a
+ * sentinel is the
+ * cheaper zero-hands proof. `scripts/subagent-zero-hands-test.ts` reds on a second declared slot for
+ * exactly this reason, so the re-read cannot be skipped silently.
+ *
+ * WHY THIS IS A BYTE READ (OPE-1537). eve 0.52.0 added
+ * `compiler/default-tool-policy.js`, which declares
+ * `REQUIRED_FRAMEWORK_TOOL_SLOTS = new Set(["tools/connection_search"])`. The set is module-private
+ * — eve exports the two policy functions and not the set — so there is nothing to import. The
+ * alternative to reading the bytes
+ * is finding out at `eve build`, which is exactly the failure this reader exists to pre-empt: a
+ * build throw names eve's file, not OE's invariant, and it lands after the lint that was supposed
+ * to catch it went green.
+ *
+ * 🔴 WHICH DIRECTION IS FAIL-OPEN. `required` is what EXEMPTS a slot from the sentinel demand, so
+ * the dangerous error is OVER-reporting: a name wrongly listed here lets an authored, hands-on tool
+ * sit in that slot with no posture review — the zero-hands invariant lost silently. UNDER-reporting
+ * is the safe direction: the lint keeps demanding a sentinel, and the worst case is an `eve build`
+ * throw — loud, and late, but never a widened subagent. The two inputs land differently:
+ *   * The module is ABSENT → eve enforces nothing, so an empty set is the TRUE answer, not a guess.
+ *     Safe, and the only case that returns without reading a declaration.
+ *   * The module is PRESENT but its declaration cannot be parsed → this reader cannot tell an
+ *     over-report from an under-report, and half of that pair is fail-open. So it THROWS and names
+ *     the file rather than picking the direction on its own.
+ *
+ * @throws when the policy module exists but declares no readable `REQUIRED_FRAMEWORK_TOOL_SLOTS`.
+ */
+export function readRequiredFrameworkToolSlots(eveRoot: string): string[] {
+  const file = join(eveRoot, POLICY_PATH);
+  let source: string;
+  try {
+    source = readFileSync(file, "utf8");
+  } catch {
+    // eve ships no default-tool policy — nothing is required, and every slot stays disableable.
+    return [];
+  }
+
+  const declaration = /REQUIRED_FRAMEWORK_TOOL_SLOTS\s*=\s*new Set\(\[([^\]]*)\]\)/u.exec(source);
+  if (declaration === null) {
+    throw new Error(
+      `eve framework tools: ${POLICY_PATH} exists but declares no readable ` +
+        `\`REQUIRED_FRAMEWORK_TOOL_SLOTS = new Set([...])\`. eve restructured the policy that declares which ` +
+        `framework tool slots an app may not simply disable. Guessing is not safe in both directions: an ` +
+        `OVER-report exempts a slot from the sentinel demand and lets a hands-on tool sit there unreviewed, ` +
+        `and an UNDER-report leaves the failure to surface as an \`eve build\` throw naming eve's file instead ` +
+        `of OE's zero-hands invariant. Read eve's policy module and update this reader.`,
+    );
+  }
+
+  const slots: string[] = [];
+  for (const [, name] of declaration[1]!.matchAll(/["'`]tools\/([A-Za-z0-9_]+)\.?[a-z]*["'`]/gu)) {
+    slots.push(name!);
+  }
+  if (declaration[1]!.trim() !== "" && slots.length === 0) {
+    throw new Error(
+      `eve framework tools: ${POLICY_PATH} declares REQUIRED_FRAMEWORK_TOOL_SLOTS with entries this reader ` +
+        `cannot parse (${declaration[1]!.trim()}). Only \`tools/<name>\` slot literals are understood. Half of ` +
+        `guessing wrong here is fail-OPEN — see the note above.`,
+    );
+  }
+  return [...new Set(slots)].sort();
+}
+
+/** `tools/<name>.ts` → `<name>`; anything else → `undefined`. */
+function toolNameOf(logicalPath: string): string | undefined {
+  const m = /^tools\/(.+)\.ts$/u.exec(logicalPath);
+  return m?.[1];
+}
+
+/** The mount classes one registry yields. `inRegistry` is every tool name it contains, whatever the
+ *  scope — the totality `all` is built from. */
+export interface RegistryMountSets {
+  readonly defaultMounted: ReadonlySet<string>;
+  readonly rootOnly: ReadonlySet<string>;
+  readonly inRegistry: ReadonlySet<string>;
+}
+
+/**
+ * Split one framework-tool source registry into its mount classes. Separated from the reader above
+ * so the two fail-open guards can be DRIVEN — they are the whole safety argument of this file, and a
+ * guard that only ever runs against the one registry the installed eve happens to ship is a guard
+ * nothing has tested (packages/core/scripts/eve-framework-tools-test.ts).
+ *
+ * @throws when either known scope yields no tools, or when a registration carries a scope this
+ *         reader cannot classify. Both are fail-OPEN if allowed through — see the file header.
+ */
+export function deriveRegistryMountSets(registrations: FrameworkSourceRegistry["registrations"]): RegistryMountSets {
+  const defaultMounted = new Set<string>();
+  const rootOnly = new Set<string>();
+  const inRegistry = new Set<string>();
+  const unknownScopes = new Set<string>();
+  for (const registration of registrations) {
+    for (const module of registration.source.modules) {
+      const name = toolNameOf(module.logicalPath);
+      if (name === undefined) continue;
+      inRegistry.add(name);
+      if (registration.applyTo === "all-local-nodes") defaultMounted.add(name);
+      else if (registration.applyTo === "root") rootOnly.add(name);
+      else unknownScopes.add(registration.applyTo);
+    }
+  }
+
+  if (defaultMounted.size === 0 || rootOnly.size === 0) {
+    throw new Error(
+      `eve framework tools: ${REGISTRY_PATH} yielded ${defaultMounted.size} default-mounted and ` +
+        `${rootOnly.size} root-only tools; both must be non-empty. eve restructured its source registry ` +
+        `(the \`applyTo\` scopes, or the \`tools/<name>.ts\` logical-path convention). An empty set here is ` +
+        `fail-OPEN — every framework-tool lint would check nothing — so this throws.`,
+    );
+  }
+  if (unknownScopes.size > 0) {
+    // Such a tool IS in `all`, so no lint goes blind — but its MOUNT CLASS is unknown, and a name
+    // this reader cannot classify would be reported "unknown" without anyone deciding that. Stop
+    // instead: someone has to read the new scope and say which set it belongs in.
+    throw new Error(
+      `eve framework tools: ${REGISTRY_PATH} registers tools under \`applyTo\` scope(s) this reader does not ` +
+        `know: ${[...unknownScopes].sort().join(", ")}. Only "all-local-nodes" (default-mounted) and "root" ` +
+        `(root-only) are classified. Read eve's compiler to see which nodes the new scope reaches, then add it ` +
+        `here — guessing its mount class either demands a disableTool() sentinel eve will reject at build time, ` +
+        `or excuses one that is genuinely needed.`,
+    );
+  }
+  return { defaultMounted, rootOnly, inRegistry };
+}
+
+export interface ReadEveFrameworkToolsOptions {
+  /** Resolve `eve` from here instead of from this module — a `file:` URL or an absolute path to a
+   *  file inside the tree that owns the install. `oe-cli` plans against a CALLER's repo, so it
+   *  passes that repo's `package.json`; every in-repo gate omits it. */
+  readonly resolveFrom?: string;
+}
+
+/**
+ * Read the installed eve's framework tool mount sets.
+ *
+ * @throws if eve's source registry cannot be read or names no tools — see the fail-open note above.
+ */
+export async function readEveFrameworkTools(options: ReadEveFrameworkToolsOptions = {}): Promise<EveFrameworkTools> {
+  const require = createRequire(options.resolveFrom ?? import.meta.url);
+  const eveRoot = dirname(require.resolve("eve/package.json"));
+
+  let registry: FrameworkSourceRegistry;
+  try {
+    // The registry lives in eve's installed dist, so the specifier is built at runtime and no
+    // bundler can inline it. That is safe here and needs no exemption marker: this module lives
+    // outside every dir `lint:hosted-externals` scans, which is the point of the path (OPE-1270).
+    const mod = (await import(pathToFileURL(join(eveRoot, REGISTRY_PATH)).href)) as {
+      frameworkAgentSourceRegistry?: FrameworkSourceRegistry;
+    };
+    const found = mod.frameworkAgentSourceRegistry;
+    if (found === undefined) throw new Error(`${REGISTRY_PATH} exports no \`frameworkAgentSourceRegistry\``);
+    registry = found;
+  } catch (cause) {
+    throw new Error(
+      `eve framework tools: cannot read ${REGISTRY_PATH} from the installed eve (${String(cause)}). ` +
+        `This is eve's own enumeration of the tools it mounts; without it every framework-tool lint checks ` +
+        `NOTHING and passes, which is why this throws instead of degrading. eve moved this module once ` +
+        `already (0.45.0 deleted runtime/framework-tools/index.js) — find its new home and update ` +
+        `REGISTRY_PATH in this file.`,
+      { cause },
+    );
+  }
+
+  const { defaultMounted, rootOnly, inRegistry } = deriveRegistryMountSets(registry.registrations);
+
+  // ── the opt-in snapshot, asserted against the installed dist ────────────────────────────────
+  const exports = JSON.parse(readFileSync(join(eveRoot, "package.json"), "utf8")) as {
+    exports?: Record<string, unknown>;
+  };
+  const exportMap = exports.exports ?? {};
+  const drift: string[] = [];
+  for (const name of OPT_IN_SNAPSHOT) {
+    if (exportMap[`./tools/${name}`] === undefined) {
+      drift.push(`"${name}" has no \`./tools/${name}\` entry in eve's exports map — the app can no longer opt into it`);
+    }
+    if (inRegistry.has(name)) {
+      drift.push(`"${name}" now appears in eve's source registry — it is mounted, not opt-in`);
+    }
+  }
+  const optInDrift =
+    drift.length === 0
+      ? undefined
+      : `the committed opt-in snapshot [${OPT_IN_SNAPSHOT.join(", ")}] no longer matches the installed eve: ` +
+        `${drift.join("; ")}. Every framework tool now classifies "unknown", so each grain-gated one demands a ` +
+        `disableTool() sentinel until the snapshot is re-pinned.`;
+
+  const optIn = optInDrift === undefined ? [...OPT_IN_SNAPSHOT] : undefined;
+  // Built from what the registry ACTUALLY names, not from the two scopes this reader classifies —
+  // see the `inRegistry` note above. Totality over the mounted surface is what every lint keys on.
+  const all = [...new Set([...inRegistry, ...(optIn ?? [])])].sort();
+
+  // ── the slots eve refuses to let an app disable ─────────────────────────────────────────────
+  const required = readRequiredFrameworkToolSlots(eveRoot);
+  // A required slot eve does not MOUNT on a local node would mean one of the two reads is wrong,
+  // and either way the demand this arms would be nonsense: a lint cannot ask for a replacement in a
+  // slot that is never mounted, and eve would then reject the file it asked for.
+  const unmounted = required.filter((name) => !defaultMounted.has(name));
+  if (unmounted.length > 0) {
+    throw new Error(
+      `eve framework tools: ${POLICY_PATH} requires slot(s) ${unmounted.join(", ")} that ${REGISTRY_PATH} does ` +
+        `not register for "all-local-nodes". One of the two reads is stale. A required-but-unmounted slot would ` +
+        `make the subagent lint demand a replacement tool in a slot eve never mounts, so this throws rather ` +
+        `than guessing which read to believe.`,
+    );
+  }
+
+  return {
+    all,
+    defaultMounted: [...defaultMounted].sort(),
+    optIn: optIn === undefined ? undefined : [...optIn].sort(),
+    rootOnly: [...rootOnly].sort(),
+    optInDrift,
+    required,
+  };
+}

package/scripts/oe-cli.ts

@@ -0,0 +1,293 @@
+#!/usr/bin/env node
+// `oe` — the Open Everywhere CLI (OPE-375). One dispatcher, two subcommands today.
+//
+//   oe build                      materialise the eve slot tree from roster.config.ts
+//   oe build --check              verify without writing; the `lint:roster` gate
+//   oe build --show [path]        print the plan (every path with its contents); writes nothing
+//   oe build --json               the machine-readable report the upgrade agent consumes (OPE-377)
+//   oe build --accept             re-write roster.lock.json from the current manifests, then build
+//   oe build --against-summary P  assert eve's .eve/agent-summary.json mounts the plan's static names
+//   oe wrap-untrusted --source X  the sandbox-side taint-envelope util (OPE-361)
+//   oe secret set|list|rm         the OPERATOR-SIDE secrets intake (OPE-408) — writes the deployment's
+//                                 own encrypted credential store directly, so a deployment needs NO
+//                                 channel env vars. Write-only: there is no `oe secret get`.
+//
+// 🔴 EXIT CODES ARE NOT UNIFORM AND THAT IS DELIBERATE. `--json` exits 0 on an `unreviewed` verdict
+// so the upgrade agent can read the report and propose a config diff; `--check` exits 1 for the same
+// state because CI wants the red. Do not "fix" this into consistency — the two callers want
+// different things from the same fact.
+//
+// 🔴 THERE IS NO BYPASS FLAG for an unreviewed contribution. A security patch to core that also
+// ships a new tool reds the deploy until a human runs `--accept`. That is the governance property
+// working, not a bug: an escape hatch under time pressure becomes the default path within a week.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { pathToFileURL } from "node:url";
+import {
+  declaredPackages,
+  goldenPlanLines,
+  ownedSlotDirs,
+  parseRosterConfig,
+  planRoster,
+  type PlanResult,
+} from "../agent/scaffold/roster-plan.js";
+import { SLOT_DIR } from "../agent/scaffold/roster-config.js";
+import { readEveFrameworkTools } from "./eve-framework-tools.js";
+import {
+  CONFIG_FILE,
+  applyPlan,
+  diffAgainstDisk,
+  findRepoRoot,
+  loadRosterConfig,
+  readLock,
+  resolvePackages,
+  unresolvableSpecifiers,
+  writeLock,
+} from "../agent/scaffold/roster-fs.js";
+
+/** The golden plan — one line per planned path with its classification, sorted. It is what restores
+ *  "the roster's git diff is the review surface" once the tree itself is no longer committed. */
+const GOLDEN = "scripts/goldens/roster-plan.txt";
+
+const argv = process.argv.slice(2);
+const subcommand = argv[0] ?? "build";
+
+if (subcommand === "wrap-untrusted") {
+  const { runWrapUntrusted } = await import("./oe-wrap-untrusted.js");
+  const chunks: Buffer[] = [];
+  process.stdin.on("data", (c: Buffer) => chunks.push(c));
+  process.stdin.on("end", () => process.stdout.write(runWrapUntrusted(argv.slice(1), Buffer.concat(chunks).toString("utf8"))));
+} else if (subcommand === "secret") {
+  const { runSecretCommand, readAllStdin } = await import("./oe-secret.js");
+  const code = await runSecretCommand(argv.slice(1), {
+    out: (l) => console.log(l),
+    err: (l) => console.error(l),
+    readStdin: readAllStdin,
+  });
+  process.exit(code);
+} else if (subcommand === "build" || subcommand.startsWith("--")) {
+  await runBuild(subcommand === "build" ? argv.slice(1) : argv);
+} else {
+  console.error(`oe: unknown subcommand "${subcommand}". Known: build, secret, wrap-untrusted.`);
+  process.exit(2);
+}
+
+function flagValue(args: readonly string[], name: string): string | undefined {
+  const i = args.indexOf(name);
+  if (i >= 0 && args[i + 1] !== undefined && !args[i + 1]!.startsWith("--")) return args[i + 1];
+  const inline = args.find((a) => a.startsWith(`${name}=`));
+  return inline === undefined ? undefined : inline.slice(name.length + 1);
+}
+
+/** eve's framework tool names, read through eve's INSTALLED internals in the TARGET repo (the CLI
+ *  plans against a caller's tree, not this one). `undefined` when eve cannot be reached — the
+ *  planner then degrades rule 7 to a shape check rather than passing blind. */
+async function frameworkToolNames(repoRoot: string): Promise<string[] | undefined> {
+  try {
+    const tools = await readEveFrameworkTools({ resolveFrom: pathToFileURL(join(repoRoot, "package.json")).href });
+    return [...tools.all];
+  } catch {
+    return undefined;
+  }
+}
+
+function fail(lines: readonly string[]): never {
+  for (const line of lines) console.error(line);
+  process.exit(1);
+}
+
+async function runBuild(args: readonly string[]): Promise<void> {
+  const check = args.includes("--check");
+  const show = args.includes("--show");
+  const json = args.includes("--json");
+  const accept = args.includes("--accept");
+  const showPath = show ? flagValue(args, "--show") : undefined;
+  const againstSummary = flagValue(args, "--against-summary");
+
+  const repoRoot = findRepoRoot(process.cwd());
+  if (repoRoot === undefined) {
+    fail([`✗ oe build: no ${CONFIG_FILE} found in ${process.cwd()} or any parent directory.`]);
+  }
+
+  const loaded = await loadRosterConfig(repoRoot);
+  if (loaded.error !== undefined) fail([`✗ oe build: ${loaded.error}`]);
+  const parsed = parseRosterConfig(loaded.raw);
+  if (parsed.config === undefined) fail(["✗ oe build: roster.config.ts is not valid.", ...parsed.reds.map((r) => `  - ${r}`)]);
+
+  const agentDir = parsed.config.output?.agentDir ?? "agent";
+  const lockRead = readLock(repoRoot);
+  if (lockRead.error !== undefined) fail([`✗ oe build: ${lockRead.error}`]);
+
+  const packages = await resolvePackages(repoRoot, declaredPackages(parsed.config));
+  const plan = planRoster({
+    config: parsed.config,
+    lock: lockRead.lock,
+    acceptLock: accept,
+    packages,
+    frameworkToolNames: await frameworkToolNames(repoRoot),
+    agentDir,
+  });
+
+  if (json) {
+    process.stdout.write(`${JSON.stringify(buildReport(plan, packages), null, 2)}\n`);
+    // Exit 0 unless the inputs are structurally broken — see the header's exit-code note.
+    process.exit(plan.verdict === "invalid" ? 1 : 0);
+  }
+
+  if (show) {
+    for (const file of plan.files) {
+      if (showPath !== undefined && file.path !== showPath) continue;
+      console.log(`── ${file.path} ${"─".repeat(Math.max(0, 96 - file.path.length))}`);
+      process.stdout.write(file.content);
+    }
+    if (plan.reds.length > 0) fail(["", "✗ oe build --show: the plan above is not buildable:", ...plan.reds.map((r) => `  - ${r}`)]);
+    process.exit(0);
+  }
+
+  if (plan.verdict === "invalid" || plan.verdict === "vanished" || plan.verdict === "unreviewed") {
+    fail([`✗ oe build: ${plan.reds.length} problem(s) — NOTHING was written.`, ...plan.reds.map((r) => `  - ${r}`)]);
+  }
+
+  // §3.2 step 7 — resolve every specifier the plan would emit BEFORE a byte is written.
+  const bad = unresolvableSpecifiers(
+    repoRoot,
+    plan.resolved.filter((r) => r.decision === "mounted").map((r) => `${r.package}/${r.module}`),
+  );
+  if (bad.length > 0) {
+    fail([
+      `✗ oe build: ${bad.length} planned import(s) do not resolve — NOTHING was written.`,
+      ...bad.map(([s, why]) => `  - ${s}: ${why}`),
+      "",
+      "  A manifest offers a module its package does not ship. Fix the package's agent/contributions.ts.",
+    ]);
+  }
+
+  const owned = ownedSlotDirs(agentDir);
+  const goldenLines = goldenPlanLines(plan, agentDir);
+
+  if (check) {
+    const diff = diffAgainstDisk(repoRoot, plan.files, owned);
+    const problems: string[] = [];
+    for (const p of diff.written) problems.push(`DRIFTED · ${p} differs from the plan (hand-edited, or the build is stale).`);
+    for (const p of diff.deleted) problems.push(`STRAY · ${p} is in an owned slot directory but not in the plan.`);
+    const goldenPath = join(repoRoot, GOLDEN);
+    if (existsSync(goldenPath) && readFileSync(goldenPath, "utf8") !== `${goldenLines.join("\n")}\n`) {
+      problems.push(`GOLDEN · ${GOLDEN} does not match the plan. Fix: \`npm run oe:build -- --accept\` and READ the diff — it is the roster review surface.`);
+    }
+    if (problems.length > 0) {
+      fail([`✗ oe build --check: ${problems.length} problem(s).`, ...problems.map((p) => `  - ${p}`), "", "  Fix: `npm run oe:build`."]);
+    }
+    printRollCall(plan, "check");
+    if (againstSummary !== undefined) assertAgainstSummary(repoRoot, againstSummary, plan);
+    process.exit(0);
+  }
+
+  if (accept) {
+    writeLock(repoRoot, plan.lock);
+    console.log(`✓ wrote roster.lock.json — READ THE DIFF: every line is a capability decision.`);
+  }
+
+  const applied = applyPlan(repoRoot, plan.files, owned);
+  const goldenPath = join(repoRoot, GOLDEN);
+  if (existsSync(dirname(goldenPath)) || accept) {
+    mkdirSync(dirname(goldenPath), { recursive: true });
+    writeFileSync(goldenPath, `${goldenLines.join("\n")}\n`);
+  }
+  for (const p of applied.skipped) console.log(`  · left alone (a directory, not a slot file): ${p}`);
+  console.log(
+    `✓ oe build: ${plan.files.length} file(s) — ${applied.written.length} written, ` +
+      `${applied.unchanged.length} unchanged, ${applied.deleted.length} deleted.`,
+  );
+  printRollCall(plan, "build");
+  if (againstSummary !== undefined) assertAgainstSummary(repoRoot, againstSummary, plan);
+}
+
+/**
+ * The roll-call, in the shape `lint:tool-roster` printed. The DECLINED names on SUCCESS are kept
+ * verbatim from that gate: a sentinel disappearing is the change most worth seeing in a CI log.
+ */
+function printRollCall(plan: PlanResult, mode: string): void {
+  const byPackage = new Map<string, { mounted: number; excluded: string[] }>();
+  for (const r of plan.resolved) {
+    const row = byPackage.get(r.package) ?? { mounted: 0, excluded: [] };
+    if (r.decision === "mounted") row.mounted++;
+    else row.excluded.push(`${r.kind}/${r.name}`);
+    byPackage.set(r.package, row);
+  }
+  for (const [pkg, row] of [...byPackage].sort((a, b) => a[0].localeCompare(b[0]))) {
+    console.log(`  ${pkg}: ${row.mounted} mounted${row.excluded.length > 0 ? `, ${row.excluded.length} excluded` : ""}`);
+    if (row.excluded.length > 0) console.log(`    excluded: ${row.excluded.sort().join(", ")}`);
+  }
+  const disabled = Object.keys(plan.frameworkDisabled).sort();
+  console.log(`  eve built-ins declined by sentinel: ${disabled.length > 0 ? disabled.join(", ") : "(none)"}`);
+  console.log(`  providers selected: ${plan.selectedProviders.length > 0 ? plan.selectedProviders.join(", ") : "(none)"} [${mode}]`);
+}
+
+/** §4.4 — the machine-readable report, schema-versioned and stable-ordered. */
+function buildReport(plan: PlanResult, packages: readonly { name: string; version?: string }[]): unknown {
+  const names = [...new Set([...packages.map((p) => p.name), ...Object.keys(plan.lock.packages)])].sort();
+  return {
+    schemaVersion: 1,
+    verdict: plan.verdict,
+    packages: names.map((name) => ({
+      name,
+      installedVersion: packages.find((p) => p.name === name)?.version ?? null,
+      lockedVersion: plan.lock.packages[name]?.version ?? null,
+      unreviewed: plan.unreviewed.filter((u) => u.package === name),
+      vanished: plan.vanished.filter((v) => v.package === name),
+    })),
+    suggestedConfigPatch: plan.unreviewed.map((u) => ({
+      path: [u.package, "exclude", u.name],
+      op: "add",
+      valueHint: "<reason this deployment declines it>",
+    })),
+    roster: {
+      mounted: plan.resolved.filter((r) => r.decision === "mounted").length,
+      excluded: plan.resolved.filter((r) => r.decision === "excluded").length,
+      frameworkDisabled: Object.keys(plan.frameworkDisabled).length,
+    },
+    reds: plan.reds,
+  };
+}
+
+/**
+ * THE SILENT-LOSS GUARD (§6.3 step 1b). eve does NOT error on an empty `agent/tools/` — it mounts
+ * nothing and boots green. A `git clean -xdf`, a forgotten `oe build` or a build-command override
+ * would therefore ship a hands-free agent that looks healthy. This is the only check that runs on
+ * the ARTEFACT rather than on intent, so the deploy chain runs it right after `npm run build`.
+ *
+ * It compares the plan's STATIC projection, not its file count: grain-gated tools resolve at
+ * runtime and are legitimately absent from the summary's static list.
+ */
+function assertAgainstSummary(repoRoot: string, summaryPath: string, plan: PlanResult): void {
+  const abs = join(repoRoot, summaryPath);
+  if (!existsSync(abs)) fail([`✗ oe build --against-summary: ${summaryPath} does not exist — run \`npm run build\` first.`]);
+  let summary: Record<string, { name?: string }[] | undefined>;
+  try {
+    summary = JSON.parse(readFileSync(abs, "utf8")) as Record<string, { name?: string }[]>;
+  } catch (err) {
+    return fail([`✗ oe build --against-summary: ${summaryPath} is not valid JSON (${err instanceof Error ? err.message : String(err)}).`]);
+  }
+  const missing: string[] = [];
+  for (const [kind, section] of [
+    ["channel", "channels"],
+    ["schedule", "schedules"],
+    ["connection", "connections"],
+  ] as const) {
+    const present = new Set((summary[section] ?? []).map((e) => e.name).filter((n): n is string => typeof n === "string"));
+    for (const r of plan.resolved) {
+      if (r.kind !== kind || r.decision !== "mounted") continue;
+      if (!present.has(r.name)) missing.push(`${SLOT_DIR[kind]}/${r.name}`);
+    }
+  }
+  if (missing.length > 0) {
+    fail([
+      `✗ oe build --against-summary: eve resolved a tree missing ${missing.length} statically-mounted name(s):`,
+      ...missing.sort().map((m) => `  - ${m}`),
+      "",
+      "  The built artefact does not carry what the roster plans. Run `oe build`, then `npm run build` again.",
+    ]);
+  }
+  console.log(`✓ oe build --against-summary: every statically-mounted channel/schedule/connection is present in ${summaryPath}.`);
+}