ams(mcp): the AMS management tool family — governor-gated mutations, doctor, tenant health (#9523) (#9607)

* feat(mcp): add the AMS management tool family behind the governor gate

The miner MCP exposed 11 read-only tools while its entire mutating ops surface was
CLI-only. This adds 10 tools: a dedicated doctor (split out of status so status stays
cheap), a structured metrics snapshot, and eight mutations.

Every mutation dispatches through the miner's existing governor-gated chat-action
chokepoint -- the same boundary the dashboard's own actions use. The MCP layer never
touches a store: it dispatches an action NAME, and the registry structurally refuses any
handler not produced by governorGatedHandler(), whose brand is a private symbol a raw
function cannot forge. That is what makes "an MCP caller cannot reach a write path the
dashboard could not" a property of the code rather than of review discipline, and the
structural test asserts it from both ends.

Three claims I had to correct against the real code rather than ship as written. The
migrate CLI has no dry-run, because applying a migration IS opening the store -- so the
tool has no apply flag either, instead of advertising a safety mode that does not exist.
The deny-hook store keys proposals by (repo, id), so the decide tool takes the repo rather
than scanning every repo's proposals to resolve an id. And purgeRepoAcrossStores is
extracted from runPurge so the tool runs the CLI's own purge over the CLI's own target
list, rather than a second implementation free to miss a store.

collectMinerPredictionMetrics is likewise extracted in the engine: the Prometheus text
renderer now formats those families, so the scrape and the JSON snapshot share one
aggregation and cannot disagree about what a counter means.

validate:mcp earned its keep twice here. It caught the two AMS tenant tools declared but
never registered, and it caught loopover_miner_run_migrations/_purge_repo returning fields
their output schemas did not declare -- the .shape re-wrap that drops looseObject's
catchall, the same -32602 class this epic already fixed once. Both outputs now declare
every field their handlers return.

AMS tenant create/list/destroy are deliberately absent: #9522's loopover_tenant_* tools are
product-parameterized and already serve product "ams", because the control plane's routes
are. Only health and wake -- the pair with no ORB counterpart -- are added. The catalog's
recorded exclusions (calibration floors, raw run-state set, the one-way kill switch) stay
CLI-only, pinned by a test so reversing that decision has to be deliberate.

* test(mcp): cover the miner ops actions and the full dispatch path

The store operations and the registered handlers were only reachable through the MCP tools,
so nothing measured them directly. These drive each action end to end -- action name
through the governor gate to the store call -- plus the validator guard clauses for null,
primitive, and array params, and the fail-closed paths (flag disabled, unknown action,
malformed params never reaching a store).

registerMinerOpsChatActions gains the same evaluateGate seam the dashboard's own
registerPortfolioQueueChatActions already exposes, so a test can drive the dispatch path
without the real chokepoint; production passes none and gets the real one.

paramsOf loses its `?? {}`: every action that calls it has a validator requiring an object,
and dispatchChatAction runs that validator first, so the fallback had no reachable case.

* chore(docs): let #9521's generator own the miner tool table

The hand-edited list this branch added is replaced by the generated one now that #9590 has
landed -- which is what the issue asked for: the tool tables pick new tools up with no
hand-edits. 163 registry entries across the three servers.

* test(mcp): cover the AMS tools' registration and result-shaping layers

codecov/patch was short because the new tool REGISTRATIONS were never driven in-process --
the miner bin's 169 changed lines had 54 uncovered statements, and the AMS tenant handlers
had none of their own tests at all.

These drive every new tool over the in-memory transport against injected seams: the doctor
mapping from status.js's {name, ok, detail} onto the contract's pass/warn/fail, the metrics
snapshot's shared aggregation, and each mutating tool's dispatch and result shaping --
including that a governor refusal comes back as a structured blocked result rather than a
thrown error, and that a purge with confirm absent or false is rejected by the schema
BEFORE any dispatch happens.

The AMS tenant pair gets its not-configured, healthy, and throttled paths, the last of
which is the one that must not be audited as a cycle: the schedule guard refusing a
too-soon wake is the guard working, not work that ran.

Writing the metrics test surfaced a fixture trap worth naming: toPredictionRecords reads
the LEDGER row shape (conclusion/targetId/ts), so a fixture shaped like the downstream
record yields conclusion: undefined and fails output validation. The test now uses the
ledger's own shape.

* test(engine): cover the prediction-metrics split in the engine's OWN suite

codecov reported this file at 35.84% under the `engine` flag while the root vitest suite
showed it fully covered. Both were right: @loopover/engine uploads coverage from its own
node:test suite (packages/loopover-engine/test/**), and that suite had no test for this
file at all — the vitest one lands under `backend` and does not lift the engine flag.

So the aggregation and the renderer get tests where the engine actually measures itself,
including the property the split exists for: every sample `collectMinerPredictionMetrics`
reports appears verbatim in what `renderMinerPredictionMetrics` emits, so the JSON snapshot
and the Prometheus scrape cannot report different numbers.

Also pins the escaping, which is a correctness rule rather than cosmetics: a conclusion is
DATA, so a quote, backslash, or newline inside one must not forge a second series.

Author: JSONbored

apps/loopover-ui/src/lib/mcp-tool-reference.ts

@@ -108,6 +108,20 @@ export const MCP_TOOL_REFERENCE: readonly McpToolReferenceEntry[] = [
     "availability": "both",
     "description": "Create a queued copilot-only LoopOver agent run. The agent plans and explains; it does not edit code or open PRs."
   },
+  {
+    "name": "loopover_ams_tenant_health",
+    "category": "tenant",
+    "locality": "remote",
+    "availability": "cloud",
+    "description": "Operator only. One hosted AMS tenant's health: lifecycle state, its cron-wake cadence, when it last woke, that cycle's outcome, and container health. Read-only, and scoped server-side to the authenticated tenant — a name outside that scope is refused rather than answered."
+  },
+  {
+    "name": "loopover_ams_tenant_wake",
+    "category": "tenant",
+    "locality": "remote",
+    "availability": "cloud",
+    "description": "Operator only. Trigger an immediate cycle for one hosted AMS tenant, instead of waiting for its next scheduled wake. Bounded by the SAME per-tenant schedule guards the cron path obeys — a wake too soon after the last one is reported as throttled rather than forced through."
+  },
   {
     "name": "loopover_apply_labels",
     "category": "agent",
@@ -696,6 +710,27 @@ export const MCP_TOOL_REFERENCE: readonly McpToolReferenceEntry[] = [
     "availability": "both",
     "description": "Mark a contributor's own delivered notifications as read (clears the badge). Self-scoped; pass `ids` to clear specific notifications or omit to clear all."
   },
+  {
+    "name": "loopover_miner_claim_release",
+    "category": "ops",
+    "locality": "miner",
+    "availability": "selfhost",
+    "description": "Release this miner's claim on one issue, so the claim ledger no longer reserves it. Dispatches through the governor-gated chokepoint and is recorded in the event ledger with source=mcp."
+  },
+  {
+    "name": "loopover_miner_deny_hooks_decide",
+    "category": "ops",
+    "locality": "miner",
+    "availability": "selfhost",
+    "description": "Approve or reject one synthesized deny-hook awaiting review. Approving puts it into force for future runs; rejecting discards it. Dispatches through the governor-gated chokepoint and is recorded in the event ledger with source=mcp."
+  },
+  {
+    "name": "loopover_miner_doctor",
+    "category": "ops",
+    "locality": "miner",
+    "availability": "selfhost",
+    "description": "Read-only diagnostic checks for this AMS miner: state directory, engine version match, store reachability, credentials, and configuration. Split out of loopover_miner_status (#9523) so status stays cheap and doctor can grow checks. Every check runs and reports its own pass/warn/fail — nothing is mutated and nothing stops at the first failure."
+  },
   {
     "name": "loopover_miner_get_audit_feed",
     "category": "agent",
@@ -724,6 +759,13 @@ export const MCP_TOOL_REFERENCE: readonly McpToolReferenceEntry[] = [
     "availability": "selfhost",
     "description": "Read-only manage-phase status: the per-managed-PR rows `loopover-miner manage status` reports (branch, CI state, gate verdict, outcome, last-polled-at, queue status/priority) plus the run-level portfolio view (one row per tracked repo: run state, updated-at, PR count). Joins the portfolio queue, the append-only event ledger, and run-state by reusing the existing collectManageStatus/collectRunPortfolio aggregators -- no new join logic. Read-only: never calls GitHub, never mutates local stores. Takes no arguments."
   },
+  {
+    "name": "loopover_miner_get_metrics_snapshot",
+    "category": "ops",
+    "locality": "miner",
+    "availability": "selfhost",
+    "description": "The same Prometheus metric families the `metrics` CLI exports, as structured JSON — so an agent can read them without parsing the text exposition format. Read-only."
+  },
   {
     "name": "loopover_miner_get_plan",
     "category": "agent",
@@ -745,6 +787,20 @@ export const MCP_TOOL_REFERENCE: readonly McpToolReferenceEntry[] = [
     "availability": "selfhost",
     "description": "Read-only per-repo miner run-state (idle/discovering/planning/preparing). Pass repoFullName for a single repo (a null state means none has been recorded for it yet), or omit it to list every repo's state. The read-only analog of ORB's loopover_get_automation_state; adds no state-set or mutation capability."
   },
+  {
+    "name": "loopover_miner_governor_pause",
+    "category": "ops",
+    "locality": "miner",
+    "availability": "selfhost",
+    "description": "Pause this miner's governor: no new work is admitted until it resumes. Administrative control, not a content write — the same action the dashboard's pause button dispatches, through the same governor-gated chokepoint, firing the same notification side-channel. Recorded in the event ledger with source=mcp."
+  },
+  {
+    "name": "loopover_miner_governor_resume",
+    "category": "ops",
+    "locality": "miner",
+    "availability": "selfhost",
+    "description": "Resume this miner's governor after a pause, re-admitting work. The same action the dashboard's resume button dispatches, through the same governor-gated chokepoint. Recorded in the event ledger with source=mcp."
+  },
   {
     "name": "loopover_miner_list_claims",
     "category": "agent",
@@ -766,6 +822,34 @@ export const MCP_TOOL_REFERENCE: readonly McpToolReferenceEntry[] = [
     "availability": "selfhost",
     "description": "Health check for the loopover-miner MCP server. Returns a static status object confirming the server is reachable. Reads no AMS state and takes no arguments."
   },
+  {
+    "name": "loopover_miner_purge_repo",
+    "category": "ops",
+    "locality": "miner",
+    "availability": "selfhost",
+    "description": "Right-to-be-forgotten: delete every trace of one repo from this miner's local stores, returning the same per-store report as the CLI. IRREVERSIBLE — the rows are gone, not archived. Requires confirm=true, elicits confirmation where the client supports it, and dispatches through the governor-gated chokepoint."
+  },
+  {
+    "name": "loopover_miner_queue_release",
+    "category": "ops",
+    "locality": "miner",
+    "availability": "selfhost",
+    "description": "Release one claimed portfolio-queue item back to unclaimed, so another cycle can pick it up. Mirrors the dashboard's release action and dispatches through the same governor-gated chokepoint. Recorded in the event ledger with source=mcp."
+  },
+  {
+    "name": "loopover_miner_queue_requeue",
+    "category": "ops",
+    "locality": "miner",
+    "availability": "selfhost",
+    "description": "Return one portfolio-queue item to the pending pool for another attempt. Mirrors the dashboard's requeue action and dispatches through the same governor-gated chokepoint. Recorded in the event ledger with source=mcp."
+  },
+  {
+    "name": "loopover_miner_run_migrations",
+    "category": "ops",
+    "locality": "miner",
+    "availability": "selfhost",
+    "description": "Apply pending schema migrations to this miner's EXISTING local stores — it never creates a store that is not already there. Reports each store as migrated, up-to-date, or failed. There is no dry-run mode: applying a migration is opening the store, and the CLI has none either. Dispatches through the governor-gated chokepoint."
+  },
   {
     "name": "loopover_miner_status",
     "category": "utility",

packages/loopover-contract/src/tools/ams-tenant.ts

@@ -0,0 +1,72 @@
+// The hosted AMS tenant surface (#9523, #9199).
+//
+// CATALOG AMENDMENT, recorded here rather than improvised: #9523 listed
+// `loopover_ams_tenant_create` / `_list` / `_destroy`, and they are NOT here. #9522 landed
+// `loopover_tenant_create` / `_list` / `_destroy` taking a `product` of "ams" or "orb", because the control
+// plane's own `/v1/tenants` routes are product-parameterized and key their registry by `${product}:${name}`.
+// A second, AMS-only spelling of those three would be two names for one capability -- the same rot that kept
+// `loopover_fleet_get_analytics` out of #9522 -- and would leave an agent guessing which to call. Use the
+// product-parameterized tools with `product: "ams"`.
+//
+// What IS genuinely AMS-specific, and therefore here, is the pair that has no ORB counterpart: a tenant's
+// wake schedule and cycle outcomes, and the ability to trigger a cycle now.
+import { z } from "zod";
+import { defineTool } from "../tool-definition.js";
+
+const TenantName = z.string().min(1).max(200);
+
+export const AmsTenantHealthInput = z.object({
+  name: TenantName.describe("The tenant's name, as reported by loopover_tenant_list with product=ams."),
+});
+
+export const AmsTenantHealthOutput = z.looseObject({
+  configured: z.boolean().describe("False when this deployment administers no hosted tenants."),
+  name: z.string().optional(),
+  state: z.string().optional().describe("The control plane's own lifecycle vocabulary, passed through verbatim."),
+  schedule: z.string().nullable().optional().describe("The cron-wake cadence, or null when the tenant wakes only on demand."),
+  lastWakeAt: z.string().nullable().optional(),
+  lastCycleOutcome: z.string().nullable().optional(),
+  containerHealthy: z.boolean().nullable().optional(),
+  error: z.string().optional(),
+});
+
+export const amsTenantHealthTool = defineTool({
+  name: "loopover_ams_tenant_health",
+  title: "Read a hosted AMS tenant's health",
+  description:
+    "Operator only. One hosted AMS tenant's health: lifecycle state, its cron-wake cadence, when it last woke, that cycle's outcome, and container health. Read-only, and scoped server-side to the authenticated tenant — a name outside that scope is refused rather than answered.",
+  category: "tenant",
+  auth: "internal",
+  locality: "remote",
+  availability: "cloud",
+  input: AmsTenantHealthInput,
+  output: AmsTenantHealthOutput,
+});
+
+export const AmsTenantWakeInput = z.object({
+  name: TenantName,
+});
+
+export const AmsTenantWakeOutput = z.looseObject({
+  configured: z.boolean(),
+  name: z.string().optional(),
+  woken: z.boolean().optional(),
+  throttled: z.boolean().optional().describe("True when the tenant's own schedule guard refused a wake this soon after the last one."),
+  error: z.string().optional(),
+});
+
+export const amsTenantWakeTool = defineTool({
+  name: "loopover_ams_tenant_wake",
+  title: "Wake a hosted AMS tenant now",
+  description:
+    "Operator only. Trigger an immediate cycle for one hosted AMS tenant, instead of waiting for its next scheduled wake. Bounded by the SAME per-tenant schedule guards the cron path obeys — a wake too soon after the last one is reported as throttled rather than forced through.",
+  category: "tenant",
+  auth: "internal",
+  locality: "remote",
+  availability: "cloud",
+  annotations: { readOnlyHint: false, destructiveHint: false },
+  input: AmsTenantWakeInput,
+  output: AmsTenantWakeOutput,
+});
+
+export const AMS_TENANT_TOOLS = [amsTenantHealthTool, amsTenantWakeTool] as const;

packages/loopover-contract/src/tools/index.ts

@@ -147,6 +147,8 @@ import { OPS_TOOLS } from "./ops.js";
 import { FLEET_TOOLS } from "./fleet.js";
 import { TENANT_TOOLS } from "./tenant.js";
 import { INSTANCE_OPS_TOOLS } from "./instance-ops.js";
+import { MINER_OPS_TOOLS } from "./miner-ops.js";
+import { AMS_TENANT_TOOLS } from "./ams-tenant.js";
 import { adminRotateSecretTool } from "./admin-config.js";
 
 export const TOOL_CONTRACTS: readonly ToolContract[] = [
@@ -282,6 +284,8 @@ export const TOOL_CONTRACTS: readonly ToolContract[] = [
   ...OPS_TOOLS,
   ...FLEET_TOOLS,
   ...TENANT_TOOLS,
+  ...MINER_OPS_TOOLS,
+  ...AMS_TENANT_TOOLS,
 ];
 
 const CONTRACTS_BY_NAME: ReadonlyMap<string, ToolContract> = new Map(
@@ -318,3 +322,5 @@ export * from "./ops.js";
 export * from "./fleet.js";
 export * from "./tenant.js";
 export * from "./instance-ops.js";
+export * from "./miner-ops.js";
+export * from "./ams-tenant.js";