@vellumai/assistant 0.6.4 → 0.6.6

package/src/runtime/routes/schedule-routes.ts

@@ -8,6 +8,7 @@ import { z } from "zod";
 
 import { bootstrapConversation } from "../../memory/conversation-bootstrap.js";
 import { getConversation } from "../../memory/conversation-crud.js";
+import { runScript } from "../../schedule/run-script.js";
 import {
   cancelSchedule,
   completeScheduleRun,
@@ -16,6 +17,7 @@ import {
   describeCronExpression,
   getLastScheduleConversationId,
   getSchedule,
+  getScheduleRuns,
   listSchedules,
   updateSchedule,
 } from "../../schedule/schedule-store.js";
@@ -46,6 +48,7 @@ function handleListSchedules(): Response {
       cronExpression: j.cronExpression,
       timezone: j.timezone,
       message: j.message,
+      script: j.script,
       nextRunAt: j.nextRunAt,
       lastRunAt: j.lastRunAt,
       lastStatus: j.lastStatus,
@@ -108,7 +111,7 @@ function handleCancelSchedule(id: string): Response {
   return handleListSchedules();
 }
 
-const VALID_MODES = ["notify", "execute"] as const;
+const VALID_MODES = ["notify", "execute", "script"] as const;
 const VALID_ROUTING_INTENTS = [
   "single_channel",
   "multi_channel",
@@ -149,6 +152,7 @@ function handleUpdateSchedule(
     "expression",
     "timezone",
     "message",
+    "script",
     "mode",
     "routingIntent",
     "quiet",
@@ -178,6 +182,28 @@ function handleUpdateSchedule(
   return handleListSchedules();
 }
 
+function handleListScheduleRuns(id: string, limit: number): Response {
+  const schedule = getSchedule(id);
+  if (!schedule) {
+    return httpError("NOT_FOUND", "Schedule not found", 404);
+  }
+  const runs = getScheduleRuns(id, limit);
+  return Response.json({
+    runs: runs.map((r) => ({
+      id: r.id,
+      jobId: r.jobId,
+      status: r.status,
+      startedAt: r.startedAt,
+      finishedAt: r.finishedAt,
+      durationMs: r.durationMs,
+      output: r.output,
+      error: r.error,
+      conversationId: r.conversationId,
+      createdAt: r.createdAt,
+    })),
+  });
+}
+
 async function handleRunScheduleNow(
   id: string,
   sendMessageDeps?: SendMessageDeps,
@@ -187,6 +213,38 @@ async function handleRunScheduleNow(
     return httpError("NOT_FOUND", "Schedule not found", 404);
   }
 
+  // ── Script mode (shell command, no LLM) ──────────────────────────
+  if (schedule.mode === "script") {
+    if (!schedule.script) {
+      return httpError(
+        "BAD_REQUEST",
+        "Script schedule has no script command",
+        400,
+      );
+    }
+    const runId = createScheduleRun(schedule.id, `script:${schedule.id}`);
+    try {
+      log.info(
+        { jobId: schedule.id, name: schedule.name },
+        "Executing script schedule manually via HTTP (run now)",
+      );
+      const result = await runScript(schedule.script);
+      completeScheduleRun(runId, {
+        status: result.exitCode === 0 ? "ok" : "error",
+        output: result.stdout || undefined,
+        error: result.stderr || undefined,
+      });
+    } catch (err) {
+      const errorMsg = err instanceof Error ? err.message : String(err);
+      log.warn(
+        { err, jobId: schedule.id, name: schedule.name },
+        "Manual script schedule execution failed",
+      );
+      completeScheduleRun(runId, { status: "error", error: errorMsg });
+    }
+    return handleListSchedules();
+  }
+
   // Check if message is a task invocation (run_task:<task_id>)
   const taskMatch = schedule.message.match(/^run_task:(\S+)$/);
   if (taskMatch) {
@@ -205,10 +263,12 @@ async function handleRunScheduleNow(
               "sendMessageDeps not available for schedule execution",
             );
           }
-          const conversation =
-            await sendMessageDeps.getOrCreateConversation(conversationId, {
+          const conversation = await sendMessageDeps.getOrCreateConversation(
+            conversationId,
+            {
               trustContext: SCHEDULE_GUARDIAN_TRUST_CONTEXT,
-            });
+            },
+          );
           conversation.taskRunId = taskRunId;
           try {
             await conversation.processMessage(
@@ -285,10 +345,12 @@ async function handleRunScheduleNow(
     if (!sendMessageDeps) {
       throw new Error("sendMessageDeps not available for schedule execution");
     }
-    const activeConversation =
-      await sendMessageDeps.getOrCreateConversation(conversationId, {
+    const activeConversation = await sendMessageDeps.getOrCreateConversation(
+      conversationId,
+      {
         trustContext: SCHEDULE_GUARDIAN_TRUST_CONTEXT,
-      });
+      },
+    );
     activeConversation.taskRunId = undefined;
     await activeConversation.processMessage(
       schedule.message,
@@ -331,6 +393,24 @@ export function scheduleRouteDefinitions(deps: {
       }),
       handler: () => handleListSchedules(),
     },
+    {
+      endpoint: "schedules/:id/runs",
+      method: "GET",
+      policyKey: "schedules",
+      summary: "List schedule runs",
+      description: "Return recent invocation history for a schedule.",
+      tags: ["schedules"],
+      responseBody: z.object({
+        runs: z.array(z.unknown()).describe("Schedule run objects"),
+      }),
+      handler: ({ params, url }) => {
+        const rawLimit = Number(url.searchParams.get("limit") ?? 10);
+        const limit = Number.isFinite(rawLimit)
+          ? Math.min(Math.max(Math.floor(rawLimit), 1), 100)
+          : 10;
+        return handleListScheduleRuns(params.id, limit);
+      },
+    },
     {
       endpoint: "schedules/:id/toggle",
       method: "POST",
@@ -376,7 +456,8 @@ export function scheduleRouteDefinitions(deps: {
         expression: z.string(),
         timezone: z.string(),
         message: z.string(),
-        mode: z.string().describe("notify or execute"),
+        script: z.string().nullable().describe("Shell command for script mode"),
+        mode: z.string().describe("notify, execute, or script"),
         routingIntent: z
           .string()
           .describe("single_channel, multi_channel, or all_channels"),

package/src/runtime/routes/settings-routes.ts

@@ -477,9 +477,11 @@ async function handleToolPermissionSimulate(body: {
       body.toolName,
       manifestOverride,
     );
-    const policyContext = { executionTarget };
+    const executionContext =
+      body.isInteractive === false ? "headless" : "conversation";
+    const policyContext = { executionTarget, executionContext } as const;
 
-    const riskLevel = await classifyRisk(
+    const { level: riskLevel } = await classifyRisk(
       body.toolName,
       body.input,
       workingDir,

package/src/runtime/routes/trust-rules-routes.ts

@@ -4,7 +4,13 @@
  * These endpoints manage persistent trust rules independently of
  * the approval-flow trust-rule endpoint in approval-routes.ts.
  * All endpoints are bearer-token authenticated (standard runtime auth).
+ *
+ * Canonicalization is handled centrally inside `addRule`/`updateRule` in
+ * trust-store.ts: legacy clients can keep sending current shapes without
+ * 4xx regressions, but fields invalid for a tool's family (e.g.
+ * `executionTarget` on a URL-tool rule) are silently stripped.
  */
+import { SCOPED_TOOLS } from "@vellumai/ces-contracts";
 import { z } from "zod";
 
 import {
@@ -17,6 +23,9 @@ import { getLogger } from "../../util/logger.js";
 import { httpError } from "../http-errors.js";
 import type { RouteDefinition } from "../http-router.js";
 
+/** O(1) lookup set for scoped tool names. */
+const SCOPED_TOOLS_SET: ReadonlySet<string> = new Set(SCOPED_TOOLS);
+
 const log = getLogger("trust-rules-routes");
 
 /**
@@ -30,7 +39,11 @@ function handleListTrustRules(): Response {
 /**
  * POST /v1/trust-rules/manage — add a trust rule (standalone, not approval-flow).
  *
- * Body: { toolName, pattern, scope, decision, allowHighRisk?, executionTarget? }
+ * Body: { toolName, pattern, scope, decision, executionTarget? }
+ *
+ * Legacy payloads that include fields invalid for the tool's family (e.g.
+ * `executionTarget` on a `web_fetch` rule) are accepted but canonicalized:
+ * the invalid fields are stripped before persistence.
  */
 export async function handleAddTrustRuleManage(
   req: Request,
@@ -40,12 +53,10 @@ export async function handleAddTrustRuleManage(
     pattern?: string;
     scope?: string;
     decision?: string;
-    allowHighRisk?: boolean;
     executionTarget?: string;
   };
 
-  const { toolName, pattern, scope, decision, allowHighRisk, executionTarget } =
-    body;
+  const { toolName, pattern, scope, decision, executionTarget } = body;
 
   if (!toolName || typeof toolName !== "string") {
     return httpError("BAD_REQUEST", "toolName is required", 400);
@@ -60,8 +71,10 @@ export async function handleAddTrustRuleManage(
   if (!pattern || typeof pattern !== "string") {
     return httpError("BAD_REQUEST", "pattern is required", 400);
   }
-  if (!scope || typeof scope !== "string") {
-    return httpError("BAD_REQUEST", "scope is required", 400);
+  // Scope is only required for scoped tools. Non-scoped tools ignore scope.
+  const isScoped = SCOPED_TOOLS_SET.has(toolName);
+  if (isScoped && (!scope || typeof scope !== "string")) {
+    return httpError("BAD_REQUEST", "scope is required for scoped tools", 400);
   }
   const validDecisions = ["allow", "deny", "ask"] as const;
   if (
@@ -76,14 +89,18 @@ export async function handleAddTrustRuleManage(
   }
 
   try {
-    const hasMetadata = allowHighRisk != null || executionTarget != null;
+    // Canonicalization is handled inside addRule — no need to pre-parse here.
+    // Legacy callers that send e.g. executionTarget on a URL-tool rule won't
+    // get a 4xx — the field is simply dropped during normalization in addRule.
     addRule(
       toolName,
       pattern,
-      scope,
+      isScoped ? scope! : "everywhere",
       decision as "allow" | "deny" | "ask",
       undefined,
-      hasMetadata ? { allowHighRisk, executionTarget } : undefined,
+      {
+        ...(executionTarget != null ? { executionTarget } : {}),
+      },
     );
     log.info(
       { toolName, pattern, scope, decision },
@@ -197,12 +214,11 @@ export function trustRulesRouteDefinitions(): RouteDefinition[] {
       requestBody: z.object({
         toolName: z.string().describe("Tool name"),
         pattern: z.string().describe("Allowlist pattern"),
-        scope: z.string().describe("Scope"),
-        decision: z.string().describe("allow, deny, or ask"),
-        allowHighRisk: z
-          .boolean()
-          .describe("Allow high-risk invocations")
+        scope: z
+          .string()
+          .describe("Scope (required for scoped tools, ignored for others)")
           .optional(),
+        decision: z.string().describe("allow, deny, or ask"),
         executionTarget: z.string().describe("Execution target").optional(),
       }),
       responseBody: z.object({

package/src/runtime/routes/work-items-routes.test.ts

@@ -16,7 +16,7 @@ mock.module("../../util/logger.js", () => ({
 
 mock.module("../../permissions/checker.js", () => ({
   check: async () => ({ decision: "prompt" }),
-  classifyRisk: async () => "high",
+  classifyRisk: async () => ({ level: "high" }),
 }));
 
 import { initializeDb } from "../../memory/db.js";

package/src/runtime/routes/work-items-routes.ts

@@ -354,10 +354,11 @@ export async function preflightWorkItem(
   }
 
   const workingDir = process.cwd();
+  const policyContext = { executionContext: "headless" as const };
   const permissions = await Promise.all(
     requiredTools.map(async (tool) => {
-      const risk = await classifyRisk(tool, {}, workingDir);
-      const result = await check(tool, {}, workingDir);
+      const { level: risk } = await classifyRisk(tool, {}, workingDir);
+      const result = await check(tool, {}, workingDir, policyContext);
       return {
         tool,
         description: getToolDescription(tool),

package/src/runtime/services/__tests__/analyze-conversation.test.ts

@@ -50,23 +50,6 @@ mock.module("../../../export/transcript-formatter.js", () => ({
   buildAnalysisTranscript: () => "user: hi",
 }));
 
-// Default config stub — individual tests can override via mockGetConfig.
-interface AnalysisConfigStub {
-  analysis: {
-    modelIntent?: string;
-    modelOverride?: string;
-  };
-}
-const mockGetConfig = mock(
-  (): AnalysisConfigStub => ({
-    analysis: {},
-  }),
-);
-
-mock.module("../../../config/loader.js", () => ({
-  getConfig: mockGetConfig,
-}));
-
 import { AssistantEventHub } from "../../assistant-event-hub.js";
 import type { SendMessageDeps } from "../../http-types.js";
 import { analyzeConversation } from "../analyze-conversation.js";
@@ -90,8 +73,6 @@ beforeEach(() => {
   mockFindAnalysisConversationFor.mockImplementation(() => null);
   mockGetConversationSource.mockReset();
   mockGetConversationSource.mockImplementation(() => null);
-  mockGetConfig.mockReset();
-  mockGetConfig.mockImplementation(() => ({ analysis: {} }));
 });
 
 function makeConversation() {
@@ -221,12 +202,17 @@ describe("analyzeConversation", () => {
     expect(allowedTools).toBeInstanceOf(Set);
     expect(allowedTools?.size).toBe(0);
 
-    // Fires the agent loop.
+    // Fires the agent loop with the analyzeConversation call-site so the
+    // per-call provider config flows through `resolveCallSiteConfig`.
     expect(conversation.runAgentLoop).toHaveBeenCalledWith(
       expect.any(String),
       "msg-1",
       expect.any(Function),
-      expect.objectContaining({ isInteractive: false, isUserMessage: true }),
+      expect.objectContaining({
+        isInteractive: false,
+        isUserMessage: true,
+        callSite: "analyzeConversation",
+      }),
     );
   });
 
@@ -405,40 +391,36 @@ describe("analyzeConversation", () => {
     expect(mockAddMessage).not.toHaveBeenCalled();
   });
 
-  test("auto: passes modelOverride through to getOrCreateConversation when set in config", async () => {
-    mockGetConfig.mockImplementation(() => ({
-      analysis: {
-        modelIntent: "quality-optimized",
-        modelOverride: "claude-opus-4-6",
-      },
-    }));
+  test("auto: routes the agent loop through callSite: 'analyzeConversation'", async () => {
     const conversation = makeConversation();
     const deps = makeDeps(conversation);
 
     await analyzeConversation("conv-1", deps, { trigger: "auto" });
 
-    expect(deps.getOrCreateConversation).toHaveBeenCalledWith(
-      "analysis-new",
-      expect.objectContaining({
-        modelIntent: "quality-optimized",
-        modelOverride: "claude-opus-4-6",
-      }),
+    expect(conversation.runAgentLoop).toHaveBeenCalledWith(
+      expect.any(String),
+      "msg-1",
+      expect.any(Function),
+      expect.objectContaining({ callSite: "analyzeConversation" }),
     );
   });
 
-  test("auto: does not pass modelOverride/modelIntent keys when config leaves them unset", async () => {
+  test("does not thread modelIntent/modelOverride into getOrCreateConversation", async () => {
+    // Per-call model selection now happens via the call-site resolver against
+    // `llm.callSites.analyzeConversation`, not via legacy modelIntent/
+    // modelOverride keys on the conversation create options.
     const conversation = makeConversation();
     const deps = makeDeps(conversation);
 
     await analyzeConversation("conv-1", deps, { trigger: "auto" });
 
-    const [, passedOpts] = (
-      deps.getOrCreateConversation.mock.calls as unknown as Array<
-        [string, Record<string, unknown>]
-      >
-    )[0] ?? ["", {}];
-    expect(passedOpts).toBeDefined();
-    expect("modelIntent" in (passedOpts ?? {})).toBe(false);
-    expect("modelOverride" in (passedOpts ?? {})).toBe(false);
+    const calls = deps.getOrCreateConversation.mock
+      .calls as unknown as Array<[string, Record<string, unknown> | undefined]>;
+    expect(calls.length).toBe(1);
+    const passedOpts = calls[0]?.[1];
+    if (passedOpts !== undefined) {
+      expect("modelIntent" in passedOpts).toBe(false);
+      expect("modelOverride" in passedOpts).toBe(false);
+    }
   });
 });

package/src/runtime/services/analyze-conversation.ts

@@ -8,15 +8,18 @@
  * Two triggers are supported:
  *   - **manual**: user-initiated analysis. Creates a fresh conversation each
  *     invocation, runs with `trustClass: "unknown"`, and strips the tool
- *     surface. Byte-for-byte unchanged from the original route logic.
+ *     surface.
  *   - **auto**: called by the auto-analyze job when a source conversation
  *     reaches a natural pause. Reuses a rolling analysis conversation per
  *     parent (creating one if none exists), runs with `trustClass:
  *     "guardian"`, and keeps the full tool surface so the analysis agent can
- *     write memory and skills directly. Reads optional model overrides from
- *     `analysis.modelIntent` / `analysis.modelOverride` config.
+ *     write memory and skills directly.
+ *
+ * Both triggers route the agent loop through `callSite: 'analyzeConversation'`
+ * so per-call provider/model selection flows through `resolveCallSiteConfig`
+ * against `llm.callSites.analyzeConversation` (falling back to `llm.default`
+ * when no override is set).
  */
-import { getConfig } from "../../config/loader.js";
 import type { ServerMessage } from "../../daemon/message-protocol.js";
 import {
   AUTO_ANALYSIS_GROUP_ID,
@@ -31,7 +34,6 @@ import {
   getMessages,
 } from "../../memory/conversation-crud.js";
 import { resolveConversationId } from "../../memory/conversation-key-store.js";
-import type { ModelIntent } from "../../providers/types.js";
 import { getLogger } from "../../util/logger.js";
 import { buildAssistantEvent } from "../assistant-event.js";
 import { DAEMON_INTERNAL_ASSISTANT_ID } from "../assistant-scope.js";
@@ -173,8 +175,6 @@ export async function analyzeConversation(
   let prompt: string;
   let trustClass: "unknown" | "guardian";
   let stripTools: boolean;
-  let modelIntent: ModelIntent | undefined;
-  let modelOverride: string | undefined;
 
   if (opts.trigger === "manual") {
     const newConv = createConversation({
@@ -205,10 +205,6 @@ export async function analyzeConversation(
     prompt = buildAutoAnalysisPrompt(transcript);
     trustClass = "guardian";
     stripTools = false;
-
-    const analysisConfig = getConfig().analysis;
-    modelIntent = analysisConfig.modelIntent;
-    modelOverride = analysisConfig.modelOverride;
   }
 
   // h. Load the conversation into memory with the appropriate trust
@@ -219,13 +215,10 @@ export async function analyzeConversation(
   // Hoisted ahead of message persistence so the auto branch can detect a
   // still-running prior agent loop on the rolling conversation and bail out
   // before mutating any state. See concurrency guard below.
+  //
   const analysisConversation =
     await deps.sendMessageDeps.getOrCreateConversation(
       analysisConversationId,
-      {
-        ...(modelIntent !== undefined ? { modelIntent } : {}),
-        ...(modelOverride !== undefined ? { modelOverride } : {}),
-      },
     );
 
   // h.1. Concurrency guard (auto trigger only). The rolling analysis
@@ -298,11 +291,14 @@ export async function analyzeConversation(
   analysisConversation.abortController = new AbortController();
   analysisConversation.currentRequestId = crypto.randomUUID();
 
-  // l. Fire-and-forget the agent loop
+  // l. Fire-and-forget the agent loop. `callSite: 'analyzeConversation'`
+  // routes the per-call provider config through `resolveCallSiteConfig`
+  // against `llm.callSites.analyzeConversation`.
   analysisConversation
     .runAgentLoop(prompt, messageId, onEvent, {
       isInteractive: false,
       isUserMessage: true,
+      callSite: "analyzeConversation",
     })
     .catch((err) => {
       log.error(

package/src/runtime/skill-route-registry.ts

@@ -1,9 +1,16 @@
 /**
  * Registry for skill-provided HTTP route handlers.
  *
- * Skills register route matchers + handlers at initialization time. The
- * runtime HTTP server checks the registry for each inbound request before
- * falling through to its own route table.
+ * Skills and plugins register route matchers + handlers at initialization
+ * time. The runtime HTTP server checks the registry for each inbound request
+ * before falling through to its own route table.
+ *
+ * Registrations are identified by an opaque {@link SkillRouteHandle} returned
+ * from {@link registerSkillRoute}. Callers must pass that exact handle back
+ * to {@link unregisterSkillRoute} to remove the registration — pattern text
+ * is intentionally not a stable key, because two owners can legitimately
+ * register the same regex, and keying on `source + flags` would let one
+ * owner's teardown silently drop another owner's route.
  */
 
 import { getLogger } from "../util/logger.js";
@@ -19,31 +26,106 @@ export interface SkillRoute {
   handler: (req: Request, match: RegExpMatchArray) => Promise<Response>;
 }
 
-const routes: SkillRoute[] = [];
+export type SkillRouteMatch =
+  | { kind: "match"; route: SkillRoute; match: RegExpMatchArray }
+  | { kind: "methodMismatch"; allow: string[] };
 
 /**
- * Register a skill-provided HTTP route. Called by skills at initialization time.
+ * Opaque token returned from {@link registerSkillRoute}. The token has no
+ * observable fields — callers must treat it as a black box whose only valid
+ * use is to pass it to {@link unregisterSkillRoute}. Identity comparison on
+ * the token is what the registry keys against, so every call to
+ * `registerSkillRoute` returns a fresh handle even when the route's
+ * `pattern`/`methods`/`handler` are deep-equal to an existing entry.
  */
-export function registerSkillRoute(route: SkillRoute): void {
-  routes.push(route);
+declare const skillRouteHandleBrand: unique symbol;
+export interface SkillRouteHandle {
+  readonly [skillRouteHandleBrand]: true;
+}
+
+interface RegisteredRoute {
+  readonly handle: SkillRouteHandle;
+  readonly route: SkillRoute;
+}
+
+const routes: RegisteredRoute[] = [];
+
+/**
+ * Register a skill- or plugin-provided HTTP route. Called at initialization
+ * time. Returns an opaque handle the caller must retain and pass back to
+ * {@link unregisterSkillRoute} at teardown time. Do not attempt to derive
+ * the handle from the route's pattern — identity is the only stable key.
+ */
+export function registerSkillRoute(route: SkillRoute): SkillRouteHandle {
+  const handle = Object.freeze({}) as SkillRouteHandle;
+  routes.push({ handle, route });
   log.info(
     { pattern: route.pattern.source, methods: route.methods },
     "Skill route registered",
   );
+  return handle;
+}
+
+/**
+ * Unregister a previously-registered skill route by handle.
+ *
+ * Returns `true` if a route was removed, `false` otherwise. Not finding a
+ * match is not an error: the plugin-shutdown path calls this best-effort for
+ * every handle a plugin retained, and a stale handle (e.g. the registry was
+ * cleared externally) should not crash shutdown.
+ */
+export function unregisterSkillRoute(handle: SkillRouteHandle): boolean {
+  const index = routes.findIndex((entry) => entry.handle === handle);
+  if (index === -1) {
+    log.warn({}, "unregisterSkillRoute: no matching route found for handle");
+    return false;
+  }
+  const [removed] = routes.splice(index, 1);
+  log.info(
+    { pattern: removed!.route.pattern.source },
+    "Skill route unregistered",
+  );
+  return true;
 }
 
 /**
- * Try to match an inbound request against registered skill routes.
- * Returns `null` if no route matches.
+ * Try to match an inbound request path + method against registered skill routes.
+ *
+ * - Returns `{ kind: "match", ... }` when a route matches both path and method.
+ * - Returns `{ kind: "methodMismatch", allow }` when one or more routes match
+ *   the path but none accept the method — the caller should respond with 405
+ *   and an `Allow` header listing the accepted methods.
+ * - Returns `null` when no route matches the path at all; the request then
+ *   falls through to JWT auth and the normal route table.
+ *
+ * Method gating lives here so unauthenticated requests with the wrong method
+ * cannot reach skill handlers, and so same-path/different-method route pairs
+ * dispatch to the correct handler.
  */
 export function matchSkillRoute(
   path: string,
   method: string,
-): { route: SkillRoute; match: RegExpMatchArray } | null {
-  for (const route of routes) {
-    if (!route.methods.includes(method)) continue;
-    const match = path.match(route.pattern);
-    if (match) return { route, match };
+): SkillRouteMatch | null {
+  const pathMatches: SkillRoute[] = [];
+  for (const entry of routes) {
+    const match = path.match(entry.route.pattern);
+    if (!match) continue;
+    if (entry.route.methods.includes(method)) {
+      return { kind: "match", route: entry.route, match };
+    }
+    pathMatches.push(entry.route);
   }
-  return null;
+  if (pathMatches.length === 0) return null;
+  const allow = Array.from(new Set(pathMatches.flatMap((r) => r.methods)));
+  return { kind: "methodMismatch", allow };
+}
+
+/**
+ * Test-only helper — drops every registered route. Production code has no
+ * legitimate need for this; a real shutdown walks the handles each owner
+ * retained. Exported so tests that bypass the normal shutdown path (e.g.
+ * those that crash mid-bootstrap) can reset registry state between cases.
+ */
+export function resetSkillRoutesForTests(): void {
+  routes.length = 0;
 }