fix(build): gate the artifact routed CLI on the component capability judgment; changeset patch

Codex review on #419: emission, the AB4765 warning, and the registration
invariant now use `componentCapabilities ?? capabilities` — the same judgment
`inspect` reports — via the new `TargetRegistry.componentCapabilityState` /
`hostsComponent` accessors, so a component override can never disagree with
what the artifact ships. The changeset is `patch` per the pre-1.0 policy
(minor is reserved for breaking changes).

Author: ScriptedAlchemy

.changeset/387-artifact-routed-cli.md

@@ -1,5 +1,5 @@
 ---
-"agent-bundle": minor
+"agent-bundle": patch
 ---
 
 Emit the routed CLI (`src/cli/**`) into every host artifact as

packages/agent-bundle/src/adapters/registry.ts

@@ -185,7 +185,14 @@ const snapshotArtifactLayout = (
   // A supported `cli` capability promises a home for the compiled routed CLI,
   // and the compiler emits it at exactly one place (`bin/<name>.mjs`), so the
   // promise is checked before any early return and against that fixed layout.
-  const cliSupported = capabilityIsSupported(adapter.capabilities[cliBinCapability]);
+  // The judgment is the component one (`componentCapabilities ?? capabilities`)
+  // because that is what decides emission; malformed declarations are
+  // reported by the capability validators, not here.
+  const componentCapabilities = adapter.componentCapabilities === undefined
+    ? undefined
+    : record(adapter.componentCapabilities);
+  const cliJudgment = (componentCapabilities ?? adapter.capabilities)[cliBinCapability];
+  const cliSupported = isCapabilityState(cliJudgment) && capabilityIsSupported(cliJudgment);
   const missingCliBinLayout = (): Error =>
     new Error(`Target adapter "${adapter.name}" declares a supported ${cliBinCapability} capability without a routed CLI bin layout.`);
   const declaredLayout = adapter.artifactLayout;
@@ -673,10 +680,20 @@ export class TargetRegistry implements NormalizationTargetRegistry {
     return this.#adapters.get(name)?.capabilities[capability];
   }
 
+  componentCapabilityState(name: string, capability: string): CapabilityState | undefined {
+    const adapter = this.#adapters.get(name);
+    return adapter === undefined ? undefined : (adapter.componentCapabilities ?? adapter.capabilities)[capability];
+  }
+
   supports(name: string, capability: string): boolean {
     return capabilityIsSupported(this.capabilityState(name, capability));
   }
 
+  /** True when the target emits components needing `capability`, by the same judgment `inspect` reports. */
+  hostsComponent(name: string, capability: string): boolean {
+    return capabilityIsSupported(this.componentCapabilityState(name, capability));
+  }
+
   names(): readonly string[] {
     return Object.freeze([...this.#adapters.keys()]);
   }

packages/agent-bundle/src/build/cli-bins.ts

@@ -41,9 +41,13 @@ export const cliBinWorkerArtifactPath = (name: string): string => `${cliBinDirec
 export const routedCliBins = (model: NormalizedPlugin): readonly NormalizedBinEntry[] =>
   Object.freeze((model.packageBuild?.bins ?? []).filter((bin) => bin.generatedCli !== undefined));
 
-/** True when the target's adapter admits the routed CLI bin into its artifact. */
+/**
+ * True when the target's adapter admits the routed CLI bin into its artifact —
+ * by the component judgment (`componentCapabilities ?? capabilities`), so
+ * emission and `inspect` accounting can never disagree.
+ */
 export const targetHostsCliBin = (registry: TargetRegistry, target: string): boolean =>
-  registry.supports(target, cliBinCapability);
+  registry.hostsComponent(target, cliBinCapability);
 
 export interface CompiledCliBin extends CompiledEntry {
   readonly id: string;

packages/agent-bundle/src/config/validate.ts

@@ -1,8 +1,9 @@
 import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from 'node:fs';
 import { basename, extname, isAbsolute, join, posix, relative, resolve, sep } from 'node:path';
 
-import { cliBinCapability } from '../adapters/capability-state.ts';
+import { capabilityIsSupported, cliBinCapability } from '../adapters/capability-state.ts';
 import { type EntryExportScan, scanEntryExportsSource } from '../build/entry-exports.ts';
+import type { CapabilityState } from '../core/capabilities.ts';
 import { toPosixRelative } from '../core/paths.ts';
 import { isPlainRecord, isRecord } from '../core/strict-json.ts';
 import type { Diagnostic } from '../core/diagnostics.ts';
@@ -2146,11 +2147,28 @@ const routedCliBinTargetDiagnostics = (
   registry: NormalizationTargetRegistry,
 ): Diagnostic[] => {
   const diagnostics: Diagnostic[] = [];
+  // The judgment must be the one emission and `inspect` use: the adapter's
+  // component override when published, otherwise its plain capabilities. A
+  // registry exposing neither accessor falls back to its boolean view.
+  const judgmentFor = (target: string): { readonly known: true; readonly state: CapabilityState | undefined } | { readonly known: false } => {
+    if (registry.componentCapabilityState !== undefined) {
+      return { known: true, state: registry.componentCapabilityState(target, cliBinCapability) };
+    }
+    if (registry.capabilityState !== undefined) {
+      return { known: true, state: registry.capabilityState(target, cliBinCapability) };
+    }
+    return { known: false };
+  };
   for (const bin of model.packageBuild?.bins ?? []) {
     if (bin.generatedCli === undefined) continue;
     for (const target of model.targets) {
-      if (!registry.has(target.name) || registry.supports(target.name, cliBinCapability)) continue;
-      const capability = registry.capabilityState?.(target.name, cliBinCapability);
+      if (!registry.has(target.name)) continue;
+      const judged = judgmentFor(target.name);
+      const supported = judged.known
+        ? capabilityIsSupported(judged.state)
+        : registry.supports(target.name, cliBinCapability);
+      if (supported) continue;
+      const capability = judged.known ? judged.state : undefined;
       let judgment: string;
       if (capability === undefined) {
         judgment = `the target publishes no ${cliBinCapability} capability row`;

packages/agent-bundle/src/core/types.ts

@@ -705,6 +705,13 @@ export interface NormalizationTargetRegistry {
     targetNames: readonly string[],
   ): readonly NormalizationHostBinSource[];
   capabilityState?(name: string, capability: string): CapabilityState | undefined;
+  /**
+   * The judgment that decides component emission for one target: the
+   * adapter's `componentCapabilities` override when it publishes one (a key
+   * it omits reads as no row), otherwise its `capabilities`. Emission and
+   * `inspect` accounting must consult the same judgment.
+   */
+  componentCapabilityState?(name: string, capability: string): CapabilityState | undefined;
   configExtensions(): readonly NormalizationConfigExtension[];
   defaultTargetNames(): readonly string[];
   has(name: string): boolean;

packages/agent-bundle/tests/adapter-capability-states.test.ts

@@ -938,6 +938,27 @@ it('publishes the routed CLI bin capability with its bin layout on every built-i
     ...cursor,
     artifactLayout: { ...layoutWithoutBin, cliBin: { allowedSuffixes: ['.js', '.mjs'], directory: 'bin' } },
   })).not.toThrow();
+
+  // Emission follows the component judgment `inspect` reports
+  // (`componentCapabilities ?? capabilities`), so an override that withdraws
+  // `cli` hosts no bin (and needs no layout), while an override that grants it
+  // needs the layout even if the top-level row is absent.
+  const withdrawn = new TargetRegistry().register({
+    ...cursor,
+    artifactLayout: layoutWithoutBin,
+    componentCapabilities: { ...cursor.componentCapabilities, cli: unavailableCapability('withdrawn for this host') },
+  });
+  expect(withdrawn.supports('cursor', 'cli')).toBe(true);
+  expect(withdrawn.hostsComponent('cursor', 'cli')).toBe(false);
+  expect(withdrawn.componentCapabilityState('cursor', 'cli')).toEqual({ reason: 'withdrawn for this host', state: 'unavailable' });
+  expect(() => new TargetRegistry().register({
+    ...cursor,
+    artifactLayout: layoutWithoutBin,
+    capabilities: capabilitiesWithoutCli,
+    componentCapabilities: { cli: cursor.capabilities.cli! },
+  })).toThrow(/supported cli capability without a routed CLI bin layout/u);
+  expect(registry.hostsComponent('cursor', 'cli')).toBe(true);
+  expect(registry.hostsComponent('unknown-target', 'cli')).toBe(false);
 });
 
 it('rejects a malformed inspection component capability when the adapter registers', () => {