@humwick/server 0.0.0-stage → 0.130.1

package/src/services/kernel-command-bridge.ts

@@ -0,0 +1,219 @@
+// Kernel Phase-2 P2-1 (#1409) — the HostCommandDispatcher src adapter.
+//
+// This is the src side of the kernel's `ctx.commands` seam. The kernel declares the narrow
+// `HostCommandDispatcher` interface (kernel/module-host.ts) and never imports src; this adapter
+// implements it by mapping a module's `issue`/`status` onto the async DB gateway (#1910 K2):
+//   issue  → dispatchKernelCommandAsync(...)  (src/services/dispatch-command.ts)
+//   status → getCommandAsync(...)             (src/commands-write.ts, reader pool)
+// Both are async, so a command-timer firing workflow reaches the command bus without a synchronous
+// `getDb()` on the main loop.
+//
+// ── SECURITY — Checkpoint C1 (the crux; coordinator adversarially reviews this) ─────────────────
+// `dispatchKernelCommandAsync` is the SINGLE authz gate: it runs `assertCommandAuthorized` →
+// `assertPathAxesWithinConstraint` (the #968 cwd-constraint gate) before the correlation-keyed command
+// is atomically found-or-created in ONE writer transaction (`commands.createKernelIfAbsent`). This
+// module imports `dispatchKernelCommandAsync` and `getCommandAsync` ONLY — it never imports
+// `createCommand`/`createCommandInternal` or reaches the orchestrator bus directly — so an `issue`
+// STRUCTURALLY cannot dispatch a command without clearing that gate. A `kernel-command-bridge.no-bypass.test.ts`
+// pins this by scanning the source: any future edit that reintroduces a `createCommand` shortcut fails.
+//
+// The kernel `grant` on a HostCommandDecl (e.g. `command:run-command`) maps to — and NEVER widens
+// beyond — the legacy `command:write` + cwd-constrained authz, because the ONLY authority applied is
+// the `AuthContext` the caller-supplied `translate` yields, which `dispatchCommand` gates exactly as
+// the HTTP/bus transports do. The bridge fabricates no authority of its own.
+import { getCommandAsync } from "../commands-write";
+import { KERNEL_CORRELATION_PREFIX, isReservedKernelCorrelationId } from "../kernel-correlation";
+import { dispatchKernelCommandAsync } from "./dispatch-command";
+import type { AuthContext } from "./auth-context";
+import type { HostCommandDispatcher, HostCommandIssueRequest, HostCommandRun, HostCommandStatus } from "@humwick/kernel";
+import type { Command, CommandStatus, CreateCommandInput, TokenConstraints } from "../types";
+
+/** The orchestrator command + auth context ONE kernel command issue maps onto. `translate` owns the
+ *  command-type/param shaping (P2-2 supplies the `run-command` → `scheduler.command` mapping); the
+ *  bridge owns only the authz-gated dispatch, dedup, and status projection. */
+export interface KernelCommandTranslation {
+  readonly input: CreateCommandInput;
+  /** The authority `dispatchCommand` gates the issue through. MUST carry the module's frozen
+   *  create-time identity snapshot as a cwd-constrained COMPONENT token (`command:write` + cwd/
+   *  cwdPrefixes) — never a widened, admin, or bare `system` context. The R1 guard
+   *  (`assertConstrainedComponent`) rejects anything else BEFORE dispatch, so a mis-implemented
+   *  `translate` cannot smuggle a gate-skipping context through. */
+  readonly authContext: AuthContext;
+  /** #2392 — the translation is a genuine scheduler FIRE of an already-authorized timer row, so the
+   *  `approvalMode:open` exemption in `assertCommandAuthorized` applies. Set ONLY by a server-side
+   *  translator selected by `commandName` (timers' `run-command`); it is not reachable from
+   *  `request.input`, which is module/caller-shaped payload. Keeps this path in lockstep with the
+   *  legacy `dispatchScheduledCommand` twin — a divergence would refuse at dispatch what
+   *  `timerInvocationIdentity` already granted. */
+  readonly schedulerFire?: boolean;
+  /** Server-selected scheduler provenance. Like `schedulerFire`, this is a translator result, not
+   * a caller-shaped host-command input, and is forwarded only to the dispatch choke point. */
+  readonly schedulerRequestedVia?: "kernel_timers";
+}
+
+export type KernelCommandTranslator = (request: HostCommandIssueRequest) => KernelCommandTranslation;
+
+export interface KernelCommandDispatcherDeps {
+  /** Maps a kernel issue request onto a concrete `CreateCommandInput` + the authority to gate it. */
+  readonly translate: KernelCommandTranslator;
+}
+
+/** A kernel command declared a `grant` that does not map to the legacy `command:*` authz vocabulary.
+ *  Fail-closed: a host command's authority is ALWAYS `command:write` + cwd-constraint (what
+ *  `dispatchCommand` gates), so a non-`command:` grant has no mapping and must never dispatch. */
+export class UnmappedCommandGrantError extends Error {
+  constructor(readonly commandName: string, readonly grant: string) {
+    super(`kernel command '${commandName}' declares grant '${grant}', which does not map to command:* authz`);
+    this.name = "UnmappedCommandGrantError";
+  }
+}
+
+// The reserved correlation-id namespace for EVERY kernel-issued command (R2) now lives in the
+// low-level `../kernel-correlation` module so the SINGLE command-write choke point (`createCommand`)
+// can enforce it without an import cycle (commands-db ← kernel-correlation, not ← this bridge).
+// Re-exported here to preserve this module's public API — routes/commands.ts and other callers still
+// import both symbols from the bridge.
+export { KERNEL_CORRELATION_PREFIX, isReservedKernelCorrelationId };
+
+/** A module id that cannot be safely embedded in the correlation key (R2). Module ids are kebab
+ *  (`^[a-z][a-z0-9-]*$`, enforced by the manifest) and so cannot carry the `:` delimiter; the bridge
+ *  re-validates at runtime and fail-closes rather than emit a forgeable/ambiguous key. */
+export class InvalidModuleIdError extends Error {
+  constructor(readonly moduleId: string) {
+    super(`kernel module id '${moduleId}' is not a valid correlation-key segment (must be kebab-case, no delimiter)`);
+    this.name = "InvalidModuleIdError";
+  }
+}
+
+/** A kernel-issued command whose resolved {@link AuthContext} is NOT a cwd-constrained component
+ *  token (R1 defense-in-depth). A bare `system`/admin context (no `component`) makes
+ *  `assertCommandAuthorized` early-return and SKIP the #968 cwd gate → arbitrary out-of-cwd shell exec.
+ *  This is thrown BEFORE `dispatchCommand`, so even a mis-implemented `translate` returning an admin
+ *  context can never dispatch a kernel command that bypasses the gate. Fail-closed by construction. */
+export class KernelCommandAuthorityError extends Error {
+  constructor(readonly moduleId: string, readonly commandName: string, reason: string) {
+    super(`kernel command '${moduleId}.${commandName}' refused: ${reason}`);
+    this.name = "KernelCommandAuthorityError";
+  }
+}
+
+/** Kebab-case: a lowercase letter, then letters/digits/hyphens. Matches the manifest's own module-id
+ *  rule; crucially excludes the `:` correlation-key delimiter. */
+const MODULE_ID_PATTERN = /^[a-z][a-z0-9-]*$/;
+
+/** Does the component token pin the cwd(s) a command may run in? Mirrors `dispatch-command`'s
+ *  `hasCwdConstraint`: an unconstrained component would clear `assertCommandAuthorized` WITHOUT the
+ *  #968 path-axis gate ever running, so a kernel command must carry one to be safe-by-construction. */
+function hasCwdConstraint(constraints: TokenConstraints | undefined): boolean {
+  return Boolean(constraints?.cwd || constraints?.cwdPrefixes?.length);
+}
+
+/**
+ * The R1 fail-closed guard: every kernel-issued command MUST resolve to a cwd-constrained COMPONENT
+ * token, never a bare `system`/admin context. This sits on the SINGLE dispatch path (below), BEFORE
+ * `dispatchCommand`, so it structurally covers every kernel command regardless of how `translate` is
+ * (mis-)implemented. Rejecting here means no `createCommand`, no bus touch — nothing dispatches.
+ */
+function assertConstrainedComponent(authContext: AuthContext, request: HostCommandIssueRequest): void {
+  const component = authContext.component;
+  if (!component) {
+    throw new KernelCommandAuthorityError(request.moduleId, request.commandName, "resolved AuthContext carries no component token (a system/admin context would skip the cwd gate)");
+  }
+  if (!hasCwdConstraint(component.constraints)) {
+    throw new KernelCommandAuthorityError(request.moduleId, request.commandName, "resolved component token carries no cwd constraint (the #968 cwd gate would not fire)");
+  }
+}
+
+/** Map an orchestrator command status onto the kernel's coarser {@link HostCommandStatus}. Every
+ *  settled status collapses to a terminal `done`/`failed` — the only point a `{kind:"command"}` wait
+ *  is allowed to fire (see the kernel wait evaluator). */
+function mapStatus(status: CommandStatus): HostCommandStatus {
+  switch (status) {
+    case "pending":
+      return "queued";
+    case "accepted":
+      return "sent";
+    case "running":
+      return "executing";
+    case "succeeded":
+      return "done";
+    case "failed":
+    case "timed_out":
+    case "rejected":
+    case "canceled":
+      return "failed";
+  }
+}
+
+function toHostCommandRun(command: Command): HostCommandRun {
+  return {
+    id: command.id,
+    status: mapStatus(command.status),
+    ...(command.result !== undefined ? { result: command.result } : {}),
+    ...(command.error !== undefined ? { error: command.error } : {}),
+  };
+}
+
+/** The durable, COLLISION-PROOF dedup key the bridge stamps onto `correlation_id` (R2). Namespaced by
+ *  the reserved `kcmd:` prefix + module id + idempotency key. The previous `kcmd:${moduleId}:${key}`
+ *  used an UNESCAPED `:` delimiter, so `(a,"b:c")` and `("a:b",c)` produced the SAME key — and since
+ *  `correlation_id` is externally settable, a `command:write` holder could cross-map a kernel key.
+ *  Fix: LENGTH-PREFIX the module segment (`kcmd:<len>:<moduleId>:<idKey>`), which is injective for any
+ *  `(moduleId, idempotencyKey)` — the reader takes exactly `<len>` chars as the module id, the rest is
+ *  the key, so no two distinct pairs collide. Combined with the kebab moduleId check below (delimiter
+ *  can't appear in the module segment) and the reserved-prefix ingress guard, a kernel command's dedup
+ *  key can be neither forged nor cross-mapped by an externally-supplied `correlation_id`. */
+function correlationKeyFor(request: HostCommandIssueRequest): string {
+  const moduleId = request.moduleId;
+  return `${KERNEL_CORRELATION_PREFIX}${moduleId.length}:${moduleId}:${request.idempotencyKey}`;
+}
+
+/**
+ * The src `HostCommandDispatcher`: the ONLY bridge from a kernel module's `ctx.commands.issue` to the
+ * orchestrator command bus, and it is authz-gated by construction (see the C1 note at the top).
+ */
+export function createKernelCommandDispatcher(deps: KernelCommandDispatcherDeps): HostCommandDispatcher {
+  return {
+    async issue(request: HostCommandIssueRequest): Promise<HostCommandRun> {
+      // Fail-closed grant mapping (C1): a host command's authz is the legacy command:write + cwd
+      // constraint that dispatchKernelCommandAsync enforces. A decl whose grant is not a `command:*`
+      // grant has NO such mapping — reject rather than dispatch under an unintended authority.
+      if (!request.grant.startsWith("command:")) {
+        throw new UnmappedCommandGrantError(request.commandName, request.grant);
+      }
+      // R2: the module id is embedded in the correlation dedup key. Re-validate its charset at
+      // runtime (kebab, no `:` delimiter) — fail-closed rather than emit a forgeable/ambiguous key.
+      if (!MODULE_ID_PATTERN.test(request.moduleId)) {
+        throw new InvalidModuleIdError(request.moduleId);
+      }
+      const correlationId = correlationKeyFor(request);
+      const { input, authContext, schedulerFire, schedulerRequestedVia } = deps.translate(request);
+      // R1 defense-in-depth (safe-by-construction): reject a kernel command whose resolved authority
+      // is NOT a cwd-constrained component token. A bare system/admin context makes
+      // `assertCommandAuthorized` skip the cwd gate → arbitrary out-of-cwd shell exec. This guard sits
+      // on the SINGLE dispatch path, BEFORE dispatch, so it holds even if `translate` is later
+      // mis-implemented to hand back an admin context. Fail-closed: nothing is created.
+      assertConstrainedComponent(authContext, request);
+      // The bridge OWNS `correlation_id` (the dedup key); a translate's own correlation would break
+      // dedup, so it is overridden here deterministically.
+      const gated: CreateCommandInput = { ...input, correlationId };
+      // C1: the sole command-creation path — `dispatchKernelCommandAsync` runs the authz + #968 cwd gate
+      // first, then ATOMICALLY find-or-creates the correlation-keyed command in ONE writer transaction
+      // (`commands.createKernelIfAbsent`). That fold IS the #1408 exactly-once boundary: a re-drive of the
+      // issuing step (a crash AFTER dispatch but BEFORE the journal memo) dedups onto the SAME orchestrator
+      // command instead of the old cross-await `findCommandByCorrelationId` + separate create (which two
+      // processes could both lose). R2: the kernel bridge is the ONLY writer permitted to persist a
+      // `kcmd:`-reserved `correlation_id`; the op bakes in `allowReservedCorrelation`, and the
+      // `createCommandInternal` choke point rejects the reserved namespace for every other ingress.
+      const command = await dispatchKernelCommandAsync(gated, authContext, {
+        schedulerFire: schedulerFire === true,
+        ...(schedulerRequestedVia ? { schedulerRequestedVia } : {}),
+      });
+      return toHostCommandRun(command);
+    },
+    async status(commandId: string): Promise<HostCommandRun | undefined> {
+      const command = await getCommandAsync(commandId);
+      return command ? toHostCommandRun(command) : undefined;
+    },
+  };
+}

package/src/services/kernel-control-host.ts

@@ -0,0 +1,78 @@
+// KAPI-1 W4c fix 1 (PRIORITY · functional · fixes BOTH mounts) — the SHARED, catalog-aware control
+// host construction. Factored out of `kernel-control-http.ts` + `kernel-control-mcp.ts` so the two
+// mounts CANNOT drift: both build their host here.
+//
+// The bug this fixes: the control host previously registered ONLY the `control` module, so its
+// `EntityPersistence` knew only the `control` module's tables. `listEntities`/`getEntity` for another
+// live module (e.g. `timers`) look the table up in that per-host in-memory registry
+// (`EntityPersistence.#lookupTable`, `kernel/persistence.ts`), so they returned empty/404 even when a
+// real `kernel_entity__timers__timer` row existed. (Event `replay` already reads the shared
+// `kernel_events` table by SQL, so events were cross-module already; entities were the gap.)
+//
+// The fix — the "register all live module manifests with the control host" option from the brief
+// (chosen over a separate shared/catalog host as the smallest change that reuses the existing
+// `ModuleHost.register` path): register the `control` module PLUS every live kernel module manifest
+// ({@link observableModules}) so the host's `EntityPersistence` has their entity tables installed and
+// cross-module entity lookups resolve real rows. Registration is idempotent `CREATE TABLE IF NOT
+// EXISTS` DDL against the shared schema (the same tables the timers supervisor mounts).
+//
+// Authz is UNCHANGED: observability stays admin-gated inside the `control` module (G-M1 / K-C3). This
+// only fixes WHICH rows exist to the host, never who may read them.
+import {
+  type ControlModule,
+  type ModuleDefinition,
+  type ModuleHost,
+  type ModuleManifest,
+  createControlModule,
+  createModuleHost,
+} from "@humwick/kernel";
+import { timers } from "@humwick/kernel/timers.pilot";
+import { landing } from "@humwick/kernel/landing";
+import { createGatewayKernelPersistence } from "../db/kernel-persistence-async";
+
+/**
+ * The live kernel modules whose entity tables the control host must know about so `listEntities`/
+ * `getEntity` return real rows for EVERY module, not just `control` — the module-agnostic
+ * observability the epic (#1415) mandates. Register a future durable module here to light it up in
+ * the dashboard + MCP tools "for free". `control` itself is registered separately (it is the module
+ * being served); it declares no entities, so it is not in this list.
+ */
+function observableModules(): readonly ModuleDefinition<ModuleManifest>[] {
+  const modules: ModuleDefinition<ModuleManifest>[] = [timers, landing];
+  return modules;
+}
+
+export interface ControlHostBundle {
+  readonly host: ModuleHost;
+  readonly control: ControlModule;
+}
+
+/**
+ * Build the catalog-aware control host shared by BOTH the HTTP mount and the MCP binding. The
+ * `control` module closes over the host's own journal/event/entity persistence
+ * (`ModuleHost.kernelControlDeps()`); registering the {@link observableModules} afterward mutates
+ * those SAME persistence instances' table registries, so the control module's reads see every live
+ * module's rows.
+ *
+ * The host is built on the async gateway persistence (K3, #1910) — no raw `Database` is held by kernel
+ * code. Registration installs each module's schema through the gateway writer, and every control read
+ * routes through `ModuleHost.invoke`, which awaits per-module registration readiness before touching a
+ * table, so a request can never observe a half-installed schema. Callers still cache the returned bundle
+ * keyed by the ambient db handle — NOT because the host binds to it (it does not), but so an isolated
+ * test that swaps `getDb()` out rebuilds the host and reinstalls the observable-module schema on the new
+ * handle instead of serving one bound to the prior connection.
+ */
+export async function buildControlHost(): Promise<ControlHostBundle> {
+  const host = createModuleHost({ persistence: createGatewayKernelPersistence() });
+  const control = createControlModule(host.kernelControlDeps());
+  host.register(control);
+  for (const module of observableModules()) {
+    if (module.id === control.id) continue; // never double-register the served control module
+    host.register(module);
+  }
+  // Await the async schema installs before returning: the ON-gated observable-module tables must EXIST
+  // before this host serves a request (or a test reads them out of band). A never-registered module's
+  // table is never created, so OFF-mode stays a zero-footprint no-op (finding C).
+  await host.whenReady();
+  return { host, control };
+}

package/src/services/kernel-control-http.ts

@@ -0,0 +1,119 @@
+// KAPI-1 completing-step 2a (GH #1416 §4.2, K-C5) — the LIVE `/api/kernel` HTTP mount.
+//
+// This is THE auth boundary the #389 fail-open could reopen, so the wiring is deliberately narrow and
+// safe-by-construction:
+//
+//   • The control module is mounted ONLY through {@link createControlHttpApp} — never the generic
+//     `createHttpApp` and never a raw `identify` resolver. `createControlHttpApp` wires the fail-closed
+//     `controlHttpIdentity` internally, so the only knob this file supplies is a `VerifiedClaimsResolver`.
+//   • That resolver ({@link resolveControlClaims}) calls `getComponentAuth` on the EXACT request and
+//     returns `null` for every missing/invalid/non-component credential (⇒ the invoker default-denies ⇒
+//     403). It derives `actor`, `scopes`, and `resolvedIdentity` SOLELY from the verified component token
+//     via the kernel's `controlClaimsFromComponentToken` mint (sol finding 1) — never
+//     `authContextFromRequest` (the #389 `*`-scope credential-less fallback), never a client-supplied
+//     actor/scope header/body/query value.
+//
+// The outer `src/security.ts` coarse rule (`isKernelControlRequestAuthorized`) is an additional
+// defense-in-depth gate applied by the server before dispatch here — NEVER the sole gate; this resolver
+// plus the kernel invoker's default-deny are authoritative.
+import {
+  createControlHttpApp,
+  controlClaimsFromComponentToken,
+  type VerifiedClaimsResolver,
+} from "@humwick/kernel";
+import { buildControlHost } from "./kernel-control-host";
+import { getDbGeneration, listAgents } from "../db";
+import { getComponentAuth } from "../security";
+import { resolveCallerAgentId } from "../agent-ref";
+import { VERSION } from "../config";
+import type { TokenConstraints } from "../types";
+
+/**
+ * The per-request claims resolver — the crux of the hard requirement. It authenticates the caller by
+ * verifying a COMPONENT TOKEN on the exact incoming request (signature + expiry + revocation, via
+ * {@link getComponentAuth}); a request with no token, an invalid/forged/expired/revoked token, or a
+ * non-component credential (e.g. the raw god token or an integration token) yields `null`, which the
+ * control app maps to the zero-grant anonymous identity ⇒ the kernel invoker returns 403.
+ *
+ * Identity is derived STRICTLY from the verified token, never the request surface a client controls:
+ *   • `scopes`           = `token.scope`                                     (the kernel mint reads this)
+ *   • `actor`            = `resolveCallerAgentId(token.constraints, …) ?? token.sub`  (signed constraints)
+ *   • `resolvedIdentity` = the token's own kind/scopes/constraints          (the kernel mint freezes it)
+ *
+ * `resolveCallerAgentId` receives ONLY the token's signed constraints, so a spoofed `x-actor`/`x-scopes`
+ * header (or a body/query field) can never influence the resolved identity.
+ */
+export const resolveControlClaims: VerifiedClaimsResolver = (c) => {
+  // No-query token extraction (#1419): the kernel surface honors ONLY Authorization: Bearer /
+  // X-Agent-Relay-Token — never `?token=` — so kernel tokens can't leak via URL/access logs.
+  const token = getComponentAuth(c.req.raw, { allowQueryToken: false });
+  if (!token) return null; // missing / invalid / non-component ⇒ default-deny (403)
+  return controlClaimsFromComponentToken(
+    { sub: token.sub, scope: token.scope, constraints: token.constraints as Record<string, unknown> | undefined },
+    (t) => resolveCallerAgentId(t.constraints as TokenConstraints | undefined, () => listAgents()) ?? t.sub,
+  );
+};
+
+/** The minimal serving shape this module needs from the derived control app (avoids a direct `hono`
+ *  type import in src — hono resolves only from the kernel package). */
+interface FetchApp {
+  fetch(req: Request): Response | Promise<Response>;
+}
+
+// Cache the wired app KEYED BY the connection generation: prod inits once so this builds a single host;
+// a test that re-inits a fresh `:memory:` database transparently rebuilds without reading the raw handle.
+// Registering the control module runs `CREATE TABLE IF NOT EXISTS` for
+// the kernel's generic tables — idempotent against the shared prod schema (the timers supervisor mounts
+// the same way).
+let cached: { generation: number; app: Promise<FetchApp> } | undefined;
+
+async function buildControlApp(): Promise<FetchApp> {
+  // Catalog-aware host (KAPI-1 W4c fix 1): registers `control` PLUS every live module manifest so
+  // cross-module entity reads resolve real rows. Shared with the MCP binding via `buildControlHost`
+  // so the two mounts cannot drift. The host runs on the async gateway persistence (K3, #1910); its
+  // build awaits schema readiness so the app never serves a request before its tables exist.
+  const { host, control } = await buildControlHost();
+  // ONLY createControlHttpApp — no generic createHttpApp, no raw `identify`. The doc route it serves
+  // (`/openapi.json`) lives UNDER `/api/kernel`, so it is covered by the outer coarse security rule
+  // (it is never reachable unauthenticated — the server gates the whole subtree before dispatch here).
+  return createControlHttpApp(host, control, resolveControlClaims, {
+    docPath: "/openapi.json",
+    info: { title: "Humwick Kernel Control API", version: VERSION },
+  }) as unknown as FetchApp;
+}
+
+function controlApp(): Promise<FetchApp> {
+  const generation = getDbGeneration();
+  if (cached && cached.generation === generation) return cached.app;
+  const app = buildControlApp();
+  cached = { generation, app };
+  // Never cache a REJECTED build (e.g. a transient install failure): drop it so the next request retries.
+  app.catch(() => { if (cached?.app === app) cached = undefined; });
+  return app;
+}
+
+const KERNEL_MOUNT_PREFIX = "/api/kernel";
+
+/** True for any path under the live control mount (the server dispatches these here). */
+export function isKernelControlPath(pathname: string): boolean {
+  return pathname === KERNEL_MOUNT_PREFIX || pathname.startsWith(`${KERNEL_MOUNT_PREFIX}/`);
+}
+
+/**
+ * Dispatch one `/api/kernel/*` request to the derived control app. The `/api/kernel` prefix is stripped
+ * so the app matches its own derived routes (`/instances`, `/instances/{id}/cancel`, `/openapi.json`, …);
+ * the request's headers and query string are preserved verbatim so the resolver's `getComponentAuth`
+ * reads the SAME credential the caller presented. Identity is resolved per-request inside the app — this
+ * function never inspects or forwards a caller-supplied identity.
+ */
+export async function handleKernelControlRequest(req: Request): Promise<Response> {
+  const url = new URL(req.url);
+  url.pathname = url.pathname.slice(KERNEL_MOUNT_PREFIX.length) || "/";
+  const app = await controlApp();
+  return app.fetch(new Request(url, req));
+}
+
+/** Test seam: drop the cached app so a suite that swaps the db handle starts clean. */
+export function resetKernelControlAppForTests(): void {
+  cached = undefined;
+}

package/src/services/kernel-control-mcp.ts

@@ -0,0 +1,193 @@
+// KAPI-1 completing-step 2b (GH #1416 §4.1, K-C2 + K-C5) — the LIVE `relay_kernel_*` MCP binding.
+//
+// This is the MCP-side twin of the `/api/kernel` HTTP mount ({@link ./kernel-control-http}); it mirrors
+// that mount's fail-closed discipline exactly, so the #389 credential-less fail-open cannot reopen over
+// MCP either. The wiring is deliberately narrow and safe-by-construction:
+//
+//   • The tool SURFACE is DERIVED from the control module's manifest via the kernel's `deriveMcpTools`
+//     — never a hand-maintained tool table. `deriveMcpTools` authors a tool ONLY for an op with
+//     `expose.mcp !== false`, so the `*System` reconciler twins are excluded STRUCTURALLY (K-C2 / O1):
+//     no tool is authored for them and there is no MCP path to invoke them. See {@link KERNEL_TOOLS}.
+//   • Every tool's handler is closed over `ModuleHost.invoke` + the CALLER'S VERIFIED identity, resolved
+//     the SAME way the HTTP resolver does: claims are derived SOLELY from a verified COMPONENT token
+//     (`getComponentAuth`, surfaced by `mcpAuthContext` as `auth.component`) through the kernel's
+//     `controlClaimsFromComponentToken` mint — never `auth.scopes` (whose credential-less `server`
+//     fallback is `*`, the #389 fail-open), never the `integration` kind, never a client-supplied
+//     actor/scope, never the god token, never the raw `verifiedControlClaims` mint or a generic path.
+//   • A caller with no verified component identity resolves to the zero-grant anonymous identity, so the
+//     kernel invoker's default-deny returns a 403 (surfaced here as an `McpAuthError`) BEFORE any
+//     handler runs (K-C5).
+//
+// The invoker is the authoritative gate. A tool's advertised `requiredScopes` (from the op's
+// `advertiseScopes`) is defense-in-depth over `ModuleHost.invoke`'s default-deny — advisory visibility,
+// never the sole gate.
+import {
+  type ControlModule,
+  type ControlModuleDeps,
+  type DerivedMcpTool,
+  type ModuleHost,
+  type VerifiedControlClaims,
+  CONTROL_ADMIN_GRANT,
+  OpError,
+  SYSTEM_ADMIN_GRANT,
+  controlClaimsFromComponentToken,
+  controlInvocationIdentity,
+  createControlModule,
+  deriveMcpTools,
+  toMcpInputJsonSchema,
+} from "@humwick/kernel";
+import { buildControlHost } from "./kernel-control-host";
+import { getDbGeneration, listAgents } from "../db";
+import { resolveCallerAgentId } from "../agent-ref";
+import { McpAuthError, McpNotFoundError } from "../mcp-errors";
+import { ValidationError } from "../db";
+import type { ToolDefinition, VerifiedMcpAuthContext } from "../mcp/types";
+import type { TokenConstraints } from "../types";
+
+/** The MCP tool-name prefix for every derived control tool: `relay_kernel_<opName>` (GH #1416 §4.1).
+ *  Overrides `deriveMcpTools`' default (the module id, `control`) so the tools sit in the `relay_*`
+ *  namespace every other Humwick MCP tool uses. */
+const KERNEL_TOOL_PREFIX = "relay_kernel";
+
+/**
+ * The STATIC control-tool surface, derived once from the module manifest. The manifest (op names,
+ * input schemas, grants, `advertiseScopes`, and — critically — the `expose.mcp` flags) is
+ * db-independent: `defineModule` only validates the manifest and the handlers merely close over `deps`
+ * lexically (never invoked at build time), so a schema-only module built with inert deps yields the
+ * exact same tool set the live host serves. This lets the surface be a module-load-time constant
+ * (consumed by the MCP server's `tools/list`) while invocation still routes through the real
+ * db-bound host.
+ *
+ * K-C2 / O1: because the surface comes from `deriveMcpTools`, the four `*System` twins
+ * (`expose.mcp === false`) are ABSENT by construction — the exclusion is asserted against the `expose`
+ * flags, not a name list. See `kernel-control-mcp.test.ts`.
+ */
+const SCHEMA_MODULE: ControlModule = createControlModule({} as ControlModuleDeps);
+const DERIVED_TOOLS: DerivedMcpTool[] = deriveMcpTools(SCHEMA_MODULE, { prefix: KERNEL_TOOL_PREFIX });
+
+/** Tool name → the control op it invokes (`relay_kernel_listInstances` → `listInstances`). The ONLY
+ *  op names present are the MCP-exposed ones, so a lookup miss (e.g. a `*System` twin name) is a hard
+ *  "unknown tool" — there is no transport path to the twins. */
+const TOOL_TO_OP: ReadonlyMap<string, string> = new Map(DERIVED_TOOLS.map((t) => [t.name, t.opName]));
+
+/**
+ * Broaden an op's ADVERTISED scope requirement (admin-only reads ⇒ `control:admin`; owner reads ⇒
+ * `control:read`; control ops ⇒ `control:write`) to the set the kernel invoker ACTUALLY accepts, so the
+ * MCP framework's advisory `hasAnyScope` gate is never STRICTER than the authoritative invoker (HTTP
+ * parity — the HTTP mount has no such per-op transport gate). This mirrors the kernel's
+ * `controlGrantsForScopes` expansion (O2): the two admin scopes each map to the `control:read` +
+ * `control:write` grants and satisfy the in-handler `isControlAdmin` check, so an admin token invokes
+ * EVERY exposed op — including a token that carries only `control:admin`, exactly as over HTTP. The
+ * invoker's default-deny remains the real gate; broadening only keeps the advisory gate fail-closed-
+ * consistent with it (it can reject more than the invoker via a narrower op grant, never less).
+ */
+function gateScopesFor(advertised: readonly string[]): string[] {
+  return [...new Set<string>([...advertised, CONTROL_ADMIN_GRANT, SYSTEM_ADMIN_GRANT])];
+}
+
+/** The `relay_kernel_*` MCP tool definitions spread into the server's tool list. `requiredScopes` is
+ *  the advisory transport gate ({@link gateScopesFor} — the invoker-equivalent acceptance set); the
+ *  kernel invoker's default-deny is the authoritative gate. */
+export const KERNEL_TOOLS: ToolDefinition[] = DERIVED_TOOLS.map((tool) => ({
+  name: tool.name,
+  description: tool.description,
+  requiredScopes: gateScopesFor(tool.requiredScopes),
+  inputSchema: toMcpInputJsonSchema(tool),
+}));
+
+/** True for any `relay_kernel_*` control tool — the dispatch discriminator the MCP server routes on. */
+export function isKernelControlTool(name: string): boolean {
+  return TOOL_TO_OP.has(name);
+}
+
+/**
+ * Resolve the caller's VERIFIED control claims from the MCP auth context — the crux of the hard
+ * requirement, and the exact analog of the HTTP mount's `resolveControlClaims`. Claims are minted
+ * SOLELY from a verified component token:
+ *   • Only `auth.kind === "component"` with a present `auth.component` (a signature+expiry+revocation
+ *     verified token, from `getComponentAuth`) produces claims. The `integration` and credential-less
+ *     `server` kinds — the latter carrying the `*` fallback scopes that are the #389 fail-open — yield
+ *     `null` ⇒ default-deny.
+ *   • `scopes`  = `token.scope` verbatim (never `auth.scopes`, never a client-supplied value).
+ *   • `actor`   = `resolveCallerAgentId(token.constraints, …) ?? token.sub` — derived ONLY from the
+ *     token's signed constraints, so a spoofed header/arg can never influence it.
+ * Routed through the kernel's `controlClaimsFromComponentToken` mint (never the raw `verifiedControlClaims`).
+ *
+ * Takes a {@link VerifiedMcpAuthContext}, NOT a plain `McpAuthContext`: `auth.component` is the branded
+ * {@link import("../mcp/types").VerifiedComponentAuth} that only `mcpAuthContext` can produce from a
+ * `getComponentAuth`-verified token, so a fabricated `{ kind:"component", component:{…} }` literal cannot
+ * be passed here (W4b-mcp finding 5).
+ */
+export function resolveMcpControlClaims(auth: VerifiedMcpAuthContext): VerifiedControlClaims | null {
+  if (auth.kind !== "component" || !auth.component) return null; // integration / server / anon ⇒ deny
+  // No-query token (KAPI-1 W4c fix 2, #1419): the kernel MCP dispatch path is HEADER-ONLY, matching
+  // the HTTP kernel surface (`allowQueryToken:false`). A component credential presented via the URL
+  // `?token=` mints NO control claims here ⇒ default-deny — even though non-kernel MCP tools still
+  // honor `?token=` unchanged (`mcpAuthContext` marks the source without altering their behavior).
+  if (auth.componentViaQuery) return null;
+  const token = auth.component;
+  return controlClaimsFromComponentToken(
+    { sub: token.sub, scope: token.scope, constraints: token.constraints as Record<string, unknown> | undefined },
+    (t) => resolveCallerAgentId(t.constraints as TokenConstraints | undefined, () => listAgents()) ?? t.sub,
+  );
+}
+
+// Cache the wired host KEYED BY the connection generation — identical to the HTTP mount's cache
+// discipline: prod inits once; a fresh test database rebuilds without reading the raw handle. The catalog-aware host
+// ({@link buildControlHost}, shared with the HTTP mount so the two can't drift) registers the
+// `control` module PLUS every live module manifest, so cross-module entity reads resolve real rows.
+let cached: { generation: number; bundle: Promise<{ host: ModuleHost; control: ControlModule }> } | undefined;
+
+function controlHost(): Promise<{ host: ModuleHost; control: ControlModule }> {
+  const generation = getDbGeneration();
+  if (cached && cached.generation === generation) return cached.bundle;
+  const bundle = buildControlHost();
+  cached = { generation, bundle };
+  // Never cache a REJECTED build: drop it so the next tool call retries construction.
+  bundle.catch(() => { if (cached?.bundle === bundle) cached = undefined; });
+  return bundle;
+}
+
+/**
+ * Dispatch one `relay_kernel_*` tool call through the kernel invoker under the caller's verified
+ * identity. The op name comes from the DERIVED tool map (a `*System` twin name is not present ⇒
+ * "unknown tool"); identity is resolved per-call from the verified component token — a caller with no
+ * such identity is rejected BEFORE the host is built (W4c fix 3a), and this function never inspects or
+ * trusts a client-supplied actor/scope. The invoker
+ * owns authorization (default-deny), I/O validation, and the atomic commit; its typed `OpError` is
+ * mapped to the MCP error protocol (403 ⇒ `McpAuthError`, 404 ⇒ `McpNotFoundError`, else a validation
+ * error).
+ */
+export async function dispatchKernelControlTool(
+  auth: VerifiedMcpAuthContext,
+  name: string,
+  args: Record<string, unknown>,
+): Promise<unknown> {
+  const opName = TOOL_TO_OP.get(name);
+  if (!opName) throw new ValidationError(`unknown tool: ${name}`);
+  const claims = resolveMcpControlClaims(auth);
+  // Authorize the verified claims BEFORE building the lazy host (KAPI-1 W4c fix 3a): an anonymous /
+  // forged / non-component / query-token call mints no claims, so reject it HERE — one layer before
+  // `controlHost(...)` — so an unauthorized call never triggers host construction (and, pre-fix-3b,
+  // request-time DDL). This is the same 403 the invoker's default-deny returned for the zero-grant
+  // anonymous identity; the invoker remains the authoritative gate for an authenticated caller.
+  if (claims === null) throw new McpAuthError("kernel control requires a verified component token");
+  const identity = controlInvocationIdentity(claims);
+  const { host, control } = await controlHost();
+  try {
+    return await host.invoke(control, opName, identity, args);
+  } catch (error) {
+    if (error instanceof OpError) {
+      if (error.status === 403) throw new McpAuthError(error.message);
+      if (error.status === 404) throw new McpNotFoundError(error.message);
+      throw new ValidationError(error.message);
+    }
+    throw error;
+  }
+}
+
+/** Test seam: drop the cached host so a suite that swaps the db handle starts clean (mirrors the HTTP
+ *  mount's `resetKernelControlAppForTests`). */
+export function resetKernelControlMcpForTests(): void {
+  cached = undefined;
+}

package/src/services/kernel-landing-command.ts

@@ -0,0 +1,28 @@
+import { isLandingCommandType, isRecord, stringValue, validateLandingCommandParams } from "@humwick/sdk";
+import type { HostCommandDispatcher, HostCommandIssueRequest } from "@humwick/kernel";
+import type { ComponentToken, CreateCommandInput } from "../types.ts";
+import type { AuthContext } from "./auth-context.ts";
+import { ServiceAuthError } from "./errors.ts";
+import { createKernelCommandDispatcher, type KernelCommandTranslation } from "./kernel-command-bridge.ts";
+
+function translateLandingCommand(request: HostCommandIssueRequest): KernelCommandTranslation {
+  if (request.commandName !== "execute" || !isRecord(request.input)) {
+    throw new ServiceAuthError("Kernel landing issued an unknown host command");
+  }
+  const type = stringValue(request.input.type);
+  if (!type || !isLandingCommandType(type)) throw new ServiceAuthError("Kernel landing command type is invalid");
+  const params = validateLandingCommandParams(type, request.input.params);
+  const target = `orchestrator-${params.selectedHost.orchestratorId}`;
+  const constraints = { cwdPrefixes: [params.repoRoot] };
+  const component: ComponentToken = { sub: "kernel:landing", role: "kernel-module",
+    scope: ["command:write"], constraints, iat: Math.floor(Date.now() / 1_000) };
+  const authContext: AuthContext = { actor: { id: component.sub, kind: "component" },
+    scopes: component.scope, constraints, callerAgentId: component.sub, component };
+  const input: CreateCommandInput = { type, source: component.sub, target,
+    params: params as unknown as Record<string, unknown> };
+  return { input, authContext };
+}
+
+export function createLandingCommandDispatcher(): HostCommandDispatcher {
+  return createKernelCommandDispatcher({ translate: translateLandingCommand });
+}