loopctl-mcp-server 2.97.0 → 2.98.0

package/README.md

@@ -519,6 +519,7 @@ Key distribution for the dispatch pattern (Epic 26): per-dispatch ephemeral keys
 |---|---|
 | `signup` | **US-26.7.1.** Create a NEW **agent-rooted (KB-tier)** tenant and mint its one-time root API key — entirely through this call, no human operator, no hardware authenticator, no existing API key required. The tenant gets the FULL knowledge-wiki surface but **cannot** perform work-breakdown / chain-of-custody operations (those require a separate human-anchored tenant via the WebAuthn ceremony at `https://loopctl.com/signup`). Rate-limited per client IP (<= 5/hour). The `raw_key` is shown ONCE — save it immediately (e.g. as `LOOPCTL_USER_KEY`). Required: `name`, `slug`, `email`. |
 | `dispatch` | Mint an ephemeral, scoped api_key for a sub-agent dispatch, carrying its lineage path. The `raw_key` is returned ONCE — pass it to the sub-agent's launch args, never store it in env vars; it expires after `expires_in_seconds` (default 3600, max 14400). Required: `role` (`agent`/`orchestrator`), `agent_id`, and `parent_dispatch_id` for every caller a dispatch minted — a dispatch may only be minted INSIDE the caller's own lineage. Omitting `parent_dispatch_id` requests a ROOT dispatch (a new independent lineage tree), which only the tenant's `user`-role operator key may create; anyone else gets `403 root_dispatch_forbidden` with their own dispatch id in `remediation.your_dispatch_id`. A parent outside the caller's lineage is `403 parent_outside_caller_lineage`. Optional: `story_id`. **LCP-1 §9.2 signed profile:** optionally enroll an agent key via `agent_pubkey` (hex) + `alg` + an `attestation` (from `custody_sign_attestation`) + `attestation_conditions`. |
+| `revoke_dispatch` | **Revoke a dispatch AND ITS WHOLE SUBTREE** (`POST /api/v1/dispatches/:id/revoke`), plus the ephemeral api_key each one minted — the revoke matches the dispatch OR any row carrying it in `lineage_path`, so name a LEAF unless you mean the subtree. Reach for it when a dead session's key is blocking new work: an un-revoked key OCCUPIES its agent's slot in the partial unique index `api_keys_one_role_per_agent_idx` (`(tenant_id, agent_id, role)` WHERE `revoked_at IS NULL`), which cannot also test `expires_at` — a partial-index predicate must be IMMUTABLE and `now()` is STABLE — so even an EXPIRED key holds it and the next mint answers `422 agent already has an active key with this role`. Waiting works too, slowly: the expired-dispatch sweep runs every minute and the expired-api-key sweep every five, so the slot clears at the TTL (four hours for a placement session dispatch). For a PARKED STORY prefer `force_unclaim_story`, which revokes that story's own session dispatch and frees the stage as well. It does NOT clear `implementer_dispatch_id`: that is custody provenance, and a revoked dispatch still resolves, so verify/report/review-complete compare the same lineage afterwards. `role: :orchestrator` WITH the hierarchy (orchestrator, user or superadmin all pass; an agent key is `403 insufficient_role`), so no env var is pinned — `LOOPCTL_USER_KEY` is merely PREFERRED, for the ceiling reason next. `403 dispatch_outside_caller_lineage` when the target is not in your lineage — a dispatch may only be revoked by a caller it descends from, because the revoke cascades; the body carries `remediation.your_dispatch_id`, and the tenant's `user`-role operator key may revoke anywhere in its tenant. `403 unlineaged_revoke_forbidden` when your key was minted by no dispatch and is below `user` role — a legacy `LOOPCTL_ORCH_KEY` is exactly that, and with no lineage there is no subtree that would bound a cascading revoke, so it could otherwise revoke the tenant's root; use the operator key, or `force_unclaim_story` for a parked story, or mint a dispatch under an active parent and revoke from inside that lineage. `403 custody_tier_required` on an agent-rooted tenant, `503 tenant_halted` under a custody halt, 404 for an unknown dispatch or another tenant's. Idempotent: an already-revoked dispatch answers 200 with `revoked_count: 0` and its ORIGINAL `revoked_at`. Required: `dispatch_id` (refused locally if it is not a UUID). |
 | `register_custody_owner_key` | **LCP-1 §9.2.** Register/rotate the tenant custody OWNER key — the root of trust the attestation chain hangs from. Private half stays with you; requires `LOOPCTL_USER_KEY` and a human-anchored tenant. Required: `owner_pubkey` (hex). ROTATION additionally requires `rotation_proof` (from `custody_sign_owner_rotation`); first registration needs none. |
 | `list_enrolled_agent_keys` | **LCP-1 §9.1.1 transparency.** List the agent public keys enrolled under your tenant, reconstructed from the tamper-evident audit chain (not a mutable listing). Compare against the keys you generated; any excess is operator-minted. Keyset-paged (`limit`, `cursor`). |
 | `custody_generate_keypair` | **LCP-1 §9.** Generate an Ed25519 keypair LOCALLY (private key never leaves the process). Returns `public_key_hex` + `private_key_hex`. |

package/index.js

@@ -54,6 +54,7 @@ import {
   resolveEscalation as resolveEscalationRequest,
   storyStage as storyStageRequest,
 } from "./lib/delivery-loop.js";
+import { revokeDispatch as revokeDispatchRequest } from "./lib/dispatch-revoke.js";
 
 // Single source of truth for the server version: the package.json this file
 // ships with (npm always includes package.json in the published tarball).
@@ -2918,6 +2919,30 @@ async function createDispatch({
   return toContent(result);
 }
 
+// #862: the reachable half of `Dispatches.revoke/2`.
+//
+// LOOPCTL_USER_KEY is PREFERRED but NOT pinned, and the distinction is the whole point.
+// The role gate is `role: :orchestrator` WITH the hierarchy, not `exact_role`, so pinning
+// one variable would refuse configurations the server accepts — the break #861 round 2 had
+// to revert. But the endpoint also applies the LINEAGE CEILING, and there an UNLINEAGED
+// caller passes only at `role: :user` (`403 unlineaged_revoke_forbidden` otherwise, review
+// #862 finding 1). A bare legacy LOOPCTL_ORCH_KEY is exactly that shape, so sending it by
+// default made the commonest configuration the refused one.
+//
+// So the key is passed as an ORDINARY override, not with `exactKey`: `resolveKey`'s order is
+// LOOPCTL_API_KEY > this > LOOPCTL_ORCH_KEY. A global key still wins (it may be the operator
+// key, or a dispatch-minted one revoking inside its own subtree — both legitimate), the
+// operator key is next, and a legacy orchestrator key is still SENT rather than refused
+// locally, so the caller gets the server's own message naming what to do instead.
+async function revokeDispatch(args) {
+  return toContent(
+    await revokeDispatchRequest(args, {
+      apiCall: (method, path, body) =>
+        apiCall(method, path, body, process.env.LOOPCTL_USER_KEY),
+    }),
+  );
+}
+
 // LCP-1 §9.2: register/rotate the tenant custody owner key (root of trust).
 // ROTATION (an owner key already exists) requires `rotation_proof`: a hex Ed25519
 // signature by the OUTGOING owner key over owner_rotation_preimage(tenant_id,
@@ -7638,6 +7663,64 @@ const TOOLS = [
     },
   },
 
+  {
+    name: "revoke_dispatch",
+    description:
+      "REVOKE A DISPATCH AND ITS WHOLE SUBTREE (POST /api/v1/dispatches/:id/revoke), plus the " +
+      "ephemeral api_key each one minted. `Dispatches.revoke/2` matches the dispatch OR any row " +
+      "carrying it in `lineage_path`, so revoking a tree's root revokes the tree — name a LEAF " +
+      "unless you mean the subtree.\n\n" +
+      "WHAT IT IS FOR. A session dispatch whose session is gone still has `revoked_at IS NULL`, " +
+      "so it OCCUPIES its agent's slot in the partial unique index " +
+      "`api_keys_one_role_per_agent_idx` — `(tenant_id, agent_id, role)` WHERE " +
+      "`revoked_at IS NULL`. That index cannot also test `expires_at` (Postgres requires a " +
+      "partial-index predicate to be IMMUTABLE and `now()` is STABLE), so an EXPIRED key still " +
+      "holds the slot and the next mint for that agent answers 422 'agent already has an active " +
+      "key with this role'. Measured on story d9975b31: place_dispatch returned exactly that and " +
+      "wrote nothing.\n\n" +
+      "WAITING ALSO WORKS, SLOWLY. RevokeExpiredDispatchesWorker sweeps expired dispatches every " +
+      "minute and RevokeExpiredApiKeysWorker sweeps expired keys every five, so a stranded " +
+      "credential clears at its TTL — four hours for a placement session dispatch. Use this to " +
+      "not wait. For a PARKED STORY prefer force_unclaim_story: it revokes that story's own " +
+      "session dispatch on its way past, and it frees the stage as well.\n\n" +
+      "IT DOES NOT CLEAR `implementer_dispatch_id`. That is custody provenance, and loopctl " +
+      "resolves it with a read that returns a REVOKED row exactly as it returns a live one, so " +
+      "verify / report / review-complete compare the same lineage afterwards. Revoking kills the " +
+      "credential and changes no custody verdict.\n\n" +
+      "REFUSALS. `role: :orchestrator` WITH the hierarchy, so an orchestrator, user or superadmin " +
+      "key passes and an agent key is 403 insufficient_role — this is not exact_role, so no " +
+      "particular env var is pinned; LOOPCTL_USER_KEY is merely PREFERRED, because of the " +
+      "ceiling below. 403 custody_tier_required on an agent-rooted tenant. " +
+      "403 dispatch_outside_caller_lineage " +
+      "when the target is not in your lineage: a dispatch may only be revoked by a caller it " +
+      "descends from, because the revoke cascades — the body carries your own dispatch id as " +
+      "remediation.your_dispatch_id, and the tenant's user-role operator key may revoke anywhere " +
+      "in its tenant. 403 unlineaged_revoke_forbidden when your key was minted by NO dispatch " +
+      "and is below user role — a legacy LOOPCTL_ORCH_KEY is exactly that: it carries no " +
+      "lineage, so there is no subtree that would bound a cascading revoke, and it would " +
+      "otherwise be able to revoke the tenant's root. Use the user-role operator key, or " +
+      "force_unclaim_story for a parked story, or mint a dispatch under an active parent and " +
+      "revoke from inside that lineage. " +
+      "503 tenant_halted under a custody halt. 404 for an unknown dispatch, and " +
+      "for another tenant's. A `dispatch_id` that is not a UUID is refused here, before any " +
+      "call.\n\n" +
+      "IDEMPOTENT: an already-revoked dispatch answers 200 with revoked_count 0 and its ORIGINAL " +
+      "revoked_at. No request body.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        dispatch_id: {
+          type: "string",
+          description:
+            "UUID of the dispatch to revoke, together with every descendant. From the " +
+            "`dispatch` tool's response, from `implementer_dispatch_id` on a story, or from " +
+            "GET /api/v1/dispatches.",
+        },
+      },
+      required: ["dispatch_id"],
+    },
+  },
+
   // Issue #809: runner enrollment and the Presence pool (user key)
   {
     name: "runner_enroll",
@@ -8877,6 +8960,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     case "dispatch":
       return await createDispatch(args);
 
+    case "revoke_dispatch":
+      return await revokeDispatch(args);
+
     case "runner_enroll":
       return await runnerEnroll(args);
 

package/lib/dispatch-revoke.js

@@ -0,0 +1,125 @@
+/**
+ * `revoke_dispatch` — `POST /api/v1/dispatches/:id/revoke`.
+ *
+ * ## The defect it exists for
+ *
+ * `Loopctl.Dispatches.revoke/3` had no route and no tool, so nothing outside the app
+ * could call it. That made a stranded ephemeral key unfixable rather than merely
+ * inconvenient, because of an invariant two layers down:
+ *
+ * `api_keys_one_role_per_agent_idx` is a PARTIAL UNIQUE index over
+ * `(tenant_id, agent_id, role)` with the predicate
+ * `revoked_at IS NULL AND role NOT IN ('user','superadmin')`. It CANNOT also test
+ * `expires_at` — Postgres requires a partial-index predicate to be IMMUTABLE and
+ * `now()` is STABLE — so the index's idea of "active" is `revoked_at IS NULL` while the
+ * auth pipeline's is `revoked_at IS NULL AND expires_at > now()`. A key whose session
+ * died is unusable for authentication and STILL OCCUPIES its agent's slot, so the next
+ * mint for that agent at that role is refused
+ * `422 agent already has an active key with this role`.
+ *
+ * Measured on story `d9975b31` (2026-09-15): `place_dispatch` answered exactly that 422
+ * and wrote nothing, because a session dispatch from an earlier attempt was never
+ * revoked. Nothing an operator could reach would clear it before its TTL.
+ *
+ * ## WHAT IT REVOKES — say this out loud before calling it
+ *
+ * The dispatch AND EVERY DESCENDANT, plus the ephemeral api_key each one minted. That
+ * is `Dispatches.revoke/3`'s own semantics (its query is
+ * `d.id == ^dispatch_id or ^dispatch_id in d.lineage_path`), not something this tool
+ * adds. Revoking a tree's root revokes the tree.
+ *
+ * ## WHAT IT DOES NOT DO
+ *
+ * It does not clear `stories.implementer_dispatch_id`. That field is custody
+ * provenance: loopctl resolves it with `Dispatches.get_dispatch/2`, which reads a
+ * REVOKED row exactly as it reads a live one, so `verify` / `report` /
+ * `review-complete` compare the same lineage afterwards. Revoking kills the credential
+ * and changes no custody verdict.
+ *
+ * ## REFUSALS
+ *
+ * - `403 insufficient_role` — the endpoint is `role: :orchestrator` WITH the hierarchy,
+ *   so an orchestrator, user or superadmin key passes and an agent key does not. It is
+ *   NOT `exact_role`, so this tool pins no particular env var; it merely PREFERS
+ *   LOOPCTL_USER_KEY, for the ceiling reason two bullets down.
+ * - `403 custody_tier_required` — an agent-rooted tenant. Such a tenant cannot mint a
+ *   dispatch either, so it has none to revoke.
+ * - `403 dispatch_outside_caller_lineage` — THE LINEAGE CEILING. A dispatch may only be
+ *   revoked by a caller it descends from, because the revoke cascades: without it one
+ *   principal could take down another's whole tree, and an implementer could prune the
+ *   pool `select_verifier/3` draws from (it admits only dispatches that are
+ *   `revoked_at IS NULL AND expires_at > now`) until the verifier it prefers is the one
+ *   left. The tenant's `user`-role operator key — one no dispatch minted — may revoke
+ *   anywhere in its tenant. The refusal carries `remediation.your_dispatch_id` when the
+ *   caller has one.
+ * - `403 unlineaged_revoke_forbidden` — THE OTHER HALF OF THAT CEILING, and the one a
+ *   default configuration meets. A key that no dispatch minted carries no lineage, so
+ *   there is no subtree a cascading revoke could be bounded by; it passes only at
+ *   `role: :user`, the tenant's operator key. A legacy LOOPCTL_ORCH_KEY is exactly that
+ *   shape and is refused. Remedies the refusal names: use the user-role operator key,
+ *   `force_unclaim_story` for a parked story (it revokes that story's own session
+ *   dispatch through a path this ceiling does not sit on), or mint a dispatch under an
+ *   active parent and revoke from inside that lineage.
+ * - `503 tenant_halted` — a custody halt suspends this route, like dispatch minting.
+ * - `404` — no such dispatch in your tenant. Another tenant's id answers 404 too.
+ *
+ * ## IDEMPOTENT
+ *
+ * An already-revoked dispatch answers 200 with `revoked_count: 0` and its ORIGINAL
+ * `revoked_at`; the revoke statement only touches rows that are `revoked_at IS NULL`.
+ * Retrying after a timeout is safe and never rewrites a revocation timestamp.
+ *
+ * ## EXPIRY IS SWEPT, SO REACH FOR THIS ONLY WHEN WAITING IS TOO SLOW
+ *
+ * `Loopctl.Workers.RevokeExpiredDispatchesWorker` (cron, every minute) revokes a
+ * dispatch and its key once `expires_at` has passed, and
+ * `RevokeExpiredApiKeysWorker` (every five minutes) catches a key minted with no
+ * dispatch behind it. So a stranded credential DOES clear itself — at its TTL, which for
+ * a placement session dispatch is four hours. This tool is for not waiting.
+ * `force_unclaim_story` also revokes the session dispatch of the story it frees, so on a
+ * parked story that is the one call to make.
+ */
+
+const MISSING_ID =
+  "`dispatch_id` is required: the dispatch to revoke, from `mcp__loopctl__dispatch`'s " +
+  "response or from the `implementer_dispatch_id` on a story.";
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+function refuse(body) {
+  return { error: true, status: 0, body };
+}
+
+export function revokeDispatchPath(dispatchId) {
+  return `/api/v1/dispatches/${encodeURIComponent(dispatchId)}/revoke`;
+}
+
+/**
+ * A malformed id is refused HERE, before any call.
+ *
+ * Not for tidiness: a path id that is not a UUID reaches
+ * `LoopctlWeb.CastErrorHandler`'s `Ecto.Query.CastError` clause and answers 404 — the
+ * SAME 404 a well-formed id naming no dispatch gets. Two problems with opposite remedies
+ * ("fix the argument" versus "that dispatch is gone") would otherwise have one
+ * indistinguishable answer.
+ *
+ * The refusal names the SHAPE and never echoes the value: a malformed id is often a
+ * token or a pasted line that landed in the wrong argument, and a tool result goes into
+ * the transcript.
+ */
+export async function revokeDispatch({ dispatch_id } = {}, { apiCall } = {}) {
+  if (typeof dispatch_id !== "string" || dispatch_id.trim() === "") {
+    return refuse(MISSING_ID);
+  }
+
+  if (!UUID_RE.test(dispatch_id)) {
+    return refuse(
+      "`dispatch_id` must be a UUID (8-4-4-4 hex digits then 12, lowercase or upper). " +
+        `Got a ${dispatch_id.length}-character string that is not one. The value is not ` +
+        "repeated here: a malformed id is often something pasted into the wrong argument, " +
+        "and a tool result lands in the transcript.",
+    );
+  }
+
+  return apiCall("POST", revokeDispatchPath(dispatch_id), null);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loopctl-mcp-server",
-  "version": "2.97.0",
+  "version": "2.98.0",
   "description": "MCP server for loopctl — structural trust for AI development loops",
   "type": "module",
   "main": "index.js",