loopctl-mcp-server 2.97.0 → 2.99.0

package/README.md

@@ -240,6 +240,7 @@ Epic 39 Repo Coordination Bus — a lightweight, tenant-isolated channel for age
 | `list_ready_stories` | List stories that are ready to be worked on (contracted, dependencies met). |
 | `get_story` | Get full details for a single story by ID. |
 | `create_story` | Create a single story inside an existing epic. Use instead of wrapping a story in a bulk import. Accepts either `epic_id` (UUID) or (`project_id` + `epic_number`). |
+| `update_story` | **Correct a filed story** (`PATCH /api/v1/stories/:id`) — its `title`, `description`, `acceptance_criteria`, `estimated_hours` or `metadata`, and nothing else. `number` is fixed at creation and the two status fields are custody state with their own gated endpoints. **Sending `metadata` REPLACES THE WHOLE MAP** — there is no merge on this path, so a partial send silently drops every key you left out and answers 200. Read the story first (`get_story`), then send the complete map; `acceptance_criteria` is replaced whole for the same reason. The one key it can no longer erase is `lifecycle_entered_at`, which is a COLUMN precisely because it used to live in metadata and one ordinary PATCH erased it, restoring the claim -> force-unclaim -> backfill-to-verified launder. A field cannot be set to `null` either: the controller drops every nil before the changeset, so `null` is refused here rather than answering 200 unchanged, and so is an `estimated_hours` no decimal parser accepts. Requires orchestrator role or higher (`LOOPCTL_ORCH_KEY`, or `LOOPCTL_API_KEY` of that role) on a human-anchored tenant. |
 | `backfill_story` | **Bypasses the review/verify chain.** Marks a story as verified when the work was completed outside loopctl (e.g. before the project was onboarded). Refused for any story with `assigned_agent_id` set — those must go through the normal report → review → verify flow, not backfill. Also refused for already `:verified` or `:rejected` stories. Records provenance (`reason`, `evidence_url`, `pr_number`) in `metadata.backfill` and emits a `story.backfilled` webhook. |
 | `get_acceptance_criteria` | List a story's acceptance criteria with each one's verification status. Required: `story_id`. |
 
@@ -474,6 +475,7 @@ Two modes, pinned at creation:
 | Tool | Description |
 |---|---|
 | `list_routes` | List all available API routes on the loopctl server. |
+| `mcp_version` | **Which version of this MCP server you are running, and which one loopctl ships.** Returns `running`, `expected`, a `status` of `current` / `behind` / `ahead` / `unknown`, and the remedy. Takes no API key: it reads loopctl's unauthenticated discovery document (`GET /.well-known/loopctl`), so it answers in a session where nothing else does. MCP binds its tool list at session start, so from inside a session "this tool does not exist" and "this tool exists and my process is older than it" look identical — this is the discriminator. At `current`, a tool you cannot see genuinely is not in this version. At `behind`, the remedy is `/mcp` or a session restart, **never a retry**: the tool list is fixed for the life of the process. `expected` is the version in the tree the deployment you are pointed at was built from, not a registry lookup — so `behind` can briefly precede the npm publish, and `ahead` is normal when running this package from a checkout. If this tool is itself missing from your surface, that is the answer: your process predates 2.99.0. |
 | `get_system_articles` | List or fetch system-scoped (global, cross-tenant) wiki articles. Public — no auth required. Optional: `slug` (fetch one), `category`. |
 
 ### Dynamic per-tenant Context Retriever tools (Epic 30)
@@ -519,6 +521,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

@@ -13,8 +13,7 @@ import {
 import { readFileSync, writeFileSync, renameSync, lstatSync, unlinkSync } from "node:fs";
 import os from "node:os";
 import crypto from "node:crypto";
-import { fileURLToPath } from "node:url";
-import path, { dirname, join } from "node:path";
+import path from "node:path";
 import { applyArgAliases } from "./lib/arg-aliases.js";
 import { clientContextHeader } from "./lib/client-context.js";
 import { resolveClaimSessionId } from "./lib/claim-session.js";
@@ -54,14 +53,16 @@ import {
   resolveEscalation as resolveEscalationRequest,
   storyStage as storyStageRequest,
 } from "./lib/delivery-loop.js";
+import { updateStory as updateStoryRequest } from "./lib/story-update.js";
+import { mcpVersion as mcpVersionRequest, packageVersion } from "./lib/mcp-version.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).
 // Keeping it derived prevents the handshake version from drifting from the
-// published package version.
-const SERVER_VERSION = JSON.parse(
-  readFileSync(join(dirname(fileURLToPath(import.meta.url)), "package.json"), "utf8")
-).version;
+// published package version — and, since #846.7, from the version the
+// `mcp_version` tool reports, which reads it through the same function.
+const SERVER_VERSION = packageVersion();
 
 // ---------------------------------------------------------------------------
 // HTTP helper — witness protocol state
@@ -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,
@@ -3264,6 +3289,36 @@ async function forceUnclaimStory(args) {
   );
 }
 
+// #846.6: correct a filed story. The action is `role: :orchestrator`
+// (`story_controller.ex:29-30`) and NOT `exact_role:`, so the hierarchy applies and a `:user`
+// or `:superadmin` key passes too. That is why LOOPCTL_ORCH_KEY goes through `resolveKey` as an
+// ordinary override here rather than being pinned with `exactKey` the way the custody verbs
+// are: there is no role a global LOOPCTL_API_KEY could hold that the gate accepts and this
+// override would improve on. Same selection as `create_story` and `backfill_story`.
+async function updateStory(args) {
+  return toContent(
+    await updateStoryRequest(args, {
+      apiCall: (method, path, body) =>
+        apiCall(method, path, body, process.env.LOOPCTL_ORCH_KEY),
+    }),
+  );
+}
+
+// #846.7: what this process is running versus what loopctl ships. NO KEY — `publicApiCall`
+// sends no Authorization header at all, and /.well-known/loopctl is unauthenticated
+// (`router.ex:113-118`), which is the point: the staleness question arises precisely in a
+// session where keyed calls are failing. SERVER_VERSION is passed rather than re-read so the
+// handshake and this report cannot disagree; both come from `packageVersion()`.
+async function mcpVersion(args) {
+  return toContent(
+    await mcpVersionRequest(args, {
+      publicApiCall,
+      version: SERVER_VERSION,
+      baseUrl: getBaseUrl(),
+    }),
+  );
+}
+
 // US-26: Signed Tree Head retrieval
 async function getSth({ tenant_id }) {
   const result = await apiCall("GET", `/api/v1/audit/sth/${tenant_id}`);
@@ -4022,6 +4077,69 @@ const TOOLS = [
       required: ["story"],
     },
   },
+  {
+    name: "update_story",
+    description:
+      "CORRECT A FILED STORY (PATCH /api/v1/stories/:id): its title, description, acceptance " +
+      "criteria, estimate or metadata. This is the tool for a story whose own author found it " +
+      "wrong — a severity that understates the defect, a title that misnames it — without " +
+      "resending its siblings the way import_stories with merge would.\n\n" +
+      "SENDING `metadata` REPLACES THE WHOLE MAP. There is no merge on this path: the field " +
+      "is cast straight onto the story, so a partial send keeps the keys you sent and " +
+      "SILENTLY DROPS every other one, and answers 200. READ THE STORY FIRST (get_story), " +
+      "then send the complete map with your change in it. That erasure is not hypothetical: " +
+      "the marker that says a story has entered the lifecycle — and therefore may not be " +
+      "backfilled straight to `verified` — used to live in metadata, and one ordinary PATCH " +
+      "erased it. It is a COLUMN now (`lifecycle_entered_at`) that NO changeset casts, which " +
+      "is why this endpoint can no longer reach it; every other metadata key is still yours " +
+      "to lose. `acceptance_criteria` is replaced whole for the same reason.\n\n" +
+      "WHAT IT CANNOT DO. Only these five fields are updatable — `number` is fixed at " +
+      "creation, and `agent_status` / `verified_status` are custody state with their own " +
+      "gated endpoints (contract, claim, report, review-complete, verify), never a PATCH. A " +
+      "field cannot be NULLED either: the controller drops every nil before the changeset " +
+      "sees it, so `null` is refused here rather than answering 200 unchanged. Requires an " +
+      "orchestrator-role key or higher (LOOPCTL_ORCH_KEY, or LOOPCTL_API_KEY of that role) " +
+      "and a human-anchored tenant (403 `custody_tier_required` otherwise). 404 for an " +
+      "unknown story; 422 with the changeset errors for a title over 500 characters or a " +
+      "description over 50000. A `story_id` that is not a UUID is refused here, before any " +
+      "call — loopctl answers one with the IDENTICAL 404 an unknown story gets, so that " +
+      "status means one thing only because this tool takes the other case first.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        story_id: { type: "string", description: "The UUID of the story to correct." },
+        title: {
+          type: "string",
+          description: "Replaces the title. Max 500 characters (422 beyond it).",
+        },
+        description: {
+          type: "string",
+          description: "Replaces the description. Max 50000 characters (422 beyond it).",
+        },
+        acceptance_criteria: {
+          type: "array",
+          items: { type: "object" },
+          description:
+            "REPLACES the whole list — each entry is an object, conventionally " +
+            "{ id, description }. Send every criterion you want the story to keep.",
+        },
+        estimated_hours: {
+          type: "number",
+          description:
+            "Replaces the estimate. loopctl parses this with a decimal parser and DROPS the " +
+            "field when the parse fails, so an unparseable value would answer 200 with the " +
+            "old estimate; this tool refuses one instead.",
+        },
+        metadata: {
+          type: "object",
+          description:
+            "REPLACES the whole metadata map — read the story first and send it complete. " +
+            "Anything you leave out is gone.",
+        },
+      },
+      required: ["story_id"],
+    },
+  },
   {
     name: "import_stories",
     description:
@@ -7568,6 +7686,35 @@ const TOOLS = [
       required: [],
     },
   },
+  {
+    name: "mcp_version",
+    description:
+      "WHICH VERSION OF THIS MCP SERVER YOU ARE ACTUALLY RUNNING, and which one loopctl " +
+      "ships. Answers `running`, `expected`, a `status` of current / behind / ahead / " +
+      "unknown, and the remedy. Needs no API key and reads loopctl's unauthenticated " +
+      "discovery document, so it answers in a session where nothing else does.\n\n" +
+      "WHAT IT IS FOR. MCP binds its tool list at session start, so 'this tool does not " +
+      "exist' and 'this tool exists and my process is older than it' look IDENTICAL from " +
+      "inside a session — a name that is not in the surface. That is how a merged, deployed, " +
+      "green tool got reported as a missing capability. This is the discriminator: at " +
+      "`current`, a tool you cannot see genuinely is not in this version, so look for another " +
+      "name or file it rather than waiting. At `behind`, your surface is stale and the tool " +
+      "may well exist.\n\n" +
+      "THE REMEDY FOR `behind` IS /mcp OR A SESSION RESTART, NEVER A RETRY: the tool list is " +
+      "fixed for the life of this process, so the same call will fail the same way for ever. " +
+      "If a reconnect does not pick the tool up, npm may not have finished publishing yet — " +
+      "the deploy and the publish run independently — so wait and reconnect again.\n\n" +
+      "`expected` is the version in the tree the DEPLOYMENT you are pointed at was built " +
+      "from (loopctl publishes it at /.well-known/loopctl), not a registry lookup; nothing " +
+      "here talks to npm. `ahead` is normal when running this package from a checkout. And " +
+      "if this tool is itself absent from your surface, that IS the answer: your process " +
+      "predates 2.99.0.",
+    inputSchema: {
+      type: "object",
+      properties: {},
+      required: [],
+    },
+  },
 
   // Dispatch Tool (US-26.2.3)
   {
@@ -7638,6 +7785,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",
@@ -7768,6 +7973,17 @@ const TOOLS = [
             "Optional. The idempotency key. Generated when absent; pass the id you used " +
             "before to RETRY rather than start a second session.",
         },
+        repo: {
+          type: "string",
+          description:
+            "Optional. `owner/name` of the repository the session works in, OVERRIDING the " +
+            "repository loopctl would derive from the project's intake source. Pass " +
+            "`base_branch` alongside it: the derivation supplies both from one intake " +
+            "source, so naming a repository whose base branch loopctl still has to guess " +
+            "is how a session gets cut from the wrong trunk. Required in practice on a " +
+            "project bound to NO intake source (409 `no_intake_source`) or to TWO (409 " +
+            "`ambiguous_intake_source`) — both refusals name these two parameters.",
+        },
         branch: { type: "string", description: "Optional. The branch the session works on." },
         base_branch: { type: "string", description: "Optional. The branch it is cut from." },
         wall_clock_seconds: { type: "integer", description: "Optional. Overrides the default." },
@@ -8586,6 +8802,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     case "create_story":
       return await createStory(args);
 
+    case "update_story":
+      return await updateStory(args);
+
     case "import_stories":
       return await importStories(args);
 
@@ -8874,9 +9093,15 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     case "list_routes":
       return await listRoutes();
 
+    case "mcp_version":
+      return await mcpVersion(args);
+
     case "dispatch":
       return await createDispatch(args);
 
+    case "revoke_dispatch":
+      return await revokeDispatch(args);
+
     case "runner_enroll":
       return await runnerEnroll(args);
 

package/lib/delivery-loop.js

@@ -50,6 +50,14 @@ function refuse(body) {
 /**
  * A client-side shape check on the ids that go into a URL PATH: `story_id` and `runner_id`.
  *
+ * EXPORTED, because it is one check and not a pattern to copy. `update_story`
+ * (`lib/story-update.js`) interpolates a `story_id` into a path exactly as the verbs below do
+ * and shipped without it, which is the way a rule stated in a comment decays: the comment says
+ * "any argument interpolated into a URL path", and the check was reachable only from this file.
+ * A second implementation would give the same parameter two different refusals depending on
+ * which tool took it — the thing the paragraph on `place_dispatch`'s `story_id` below already
+ * refuses to do.
+ *
  * NOT on `place_dispatch`'s `dispatch_id`, which is an id and is forwarded unchecked. That is a
  * decision and not an omission: it travels in the request BODY, and `Placement.place/4` casts it
  * with `fetch_uuid/2` (`lib/loopctl/delivery/placement.ex:786-791`) as the second clause of its
@@ -104,7 +112,7 @@ function refuse(body) {
  */
 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 uuid(value, field) {
+export function uuid(value, field) {
   if (typeof value !== "string" || value.trim() === "") {
     return refuse(`\`${field}\` is required.`);
   }

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/lib/mcp-version.js

@@ -0,0 +1,216 @@
+/**
+ * `mcp_version` — the running package's version, and loopctl's expectation of it (#846.7).
+ *
+ * ## THE DEFECT
+ *
+ * MCP binds at session start. A tool merged, green and deployed is still not callable until
+ * the package publishes AND the session reconnects, and from inside that session the two
+ * states "this tool does not exist" and "this tool exists and my process is older than it" are
+ * IDENTICAL: both are a name that is not in the surface. loopctl #861 is the measured case —
+ * `force_unclaim_story` merged at 00:32:45Z on 2026-09-16 and the session that needed it to
+ * free a parked story reported the capability as MISSING while it was merely STALE.
+ *
+ * The remedy is the one the runner contract already uses. A runner sends its
+ * `contract_version` on join and loopctl answers with its own
+ * (`lib/loopctl_web/runner_channel.ex:155`, `{:ok, %{contract_version:
+ * RunnerContract.version()}}`), so a runner holding a vendored 1.11.0 against a server
+ * speaking 1.12.0 KNOWS it is behind instead of discovering it through a missing field. Both
+ * sides publish; neither has to infer.
+ *
+ * ## WHY A TOOL OF ITS OWN, RATHER THAN A FIELD ON AN EXISTING CALL
+ *
+ * The version is ALREADY published on this connection and it reaches nobody who needs it:
+ * `new Server({ name: "loopctl", version: SERVER_VERSION }, …)` in `index.js` puts it in the
+ * MCP handshake, which the model never sees. So "report it on the tool surface" has to mean
+ * something a session can CALL, and three properties decide which:
+ *
+ *   - IT MUST ANSWER WITH NO KEY. The staleness question arises exactly when calls are
+ *     failing, and every other cheap call needs a configured key of some role. This one reads
+ *     `/.well-known/loopctl`, which is unauthenticated (`lib/loopctl_web/router.ex:113-118`,
+ *     `pipe_through :api` with no auth pipeline), through `publicApiCall` — so it answers on a
+ *     process with nothing configured at all.
+ *   - A FIELD IS ONLY READ BY SOMEONE ALREADY MAKING THAT CALL. Bolting the version onto
+ *     `list_routes` answers a session that had another reason to list routes, which is not the
+ *     session in trouble, and it changes that tool's response shape for every existing caller.
+ *   - THE TOOL'S OWN ABSENCE IS PART OF THE ANSWER. A name missing from the surface is the one
+ *     signal a stale process can still emit: no `mcp_version` means the process predates
+ *     2.99.0. A field cannot be absent in a way anyone notices without first making the call
+ *     that carries it.
+ *
+ * ## WHAT `expected` ACTUALLY IS — stated precisely, because it is not "the npm latest"
+ *
+ * `GET /.well-known/loopctl` returns `mcp_server.npm_version`, read by the DEPLOYED SERVER at
+ * ITS compile time from this repository's own `mcp-server/package.json`
+ * (`lib/loopctl_web/controllers/well_known_controller.ex:20-27`, an `@external_resource` +
+ * `File.read` at module compile). So `expected` is the version in the tree that deployment was
+ * built from — not a registry lookup, and this client never talks to npm.
+ *
+ * Two consequences a caller must not be surprised by:
+ *
+ *   - `behind` can be true for a few minutes with nothing to install yet: a merge to master
+ *     that bumps `mcp-server/package.json` triggers the deploy and
+ *     `.github/workflows/mcp-autopublish.yml` INDEPENDENTLY, so the deployed server can
+ *     advertise a version npm has not finished publishing. The remedy does not change —
+ *     reconnect, once it is published — but "behind" is not by itself proof that a newer
+ *     package is installable this second.
+ *   - `ahead` is normal on a development machine running the package from a checkout, and it
+ *     means the deployment is older than your client rather than anything being wrong.
+ *
+ * NEITHER SIDE IS A GATE. Nothing here refuses a call, and nothing should: this is a report so
+ * that a session stops guessing, exactly as the join reply is for a runner.
+ */
+
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+/** RFC 8615 discovery document. Unauthenticated; see the header. */
+export const DISCOVERY_PATH = "/.well-known/loopctl";
+
+/**
+ * The version of the `package.json` this module ships beside.
+ *
+ * SINGLE SOURCE OF TRUTH, and the reason this is a function rather than a literal is the whole
+ * of #846.7 one layer down: a hardcoded constant that drifts from the package reports a
+ * version nobody is running. npm always includes `package.json` in the published tarball, so
+ * this read works from an `npx` install exactly as it does from a checkout. `index.js` derives
+ * its handshake version from here too, so the handshake, this tool and the package cannot
+ * disagree.
+ */
+export function packageVersion(readFile = readFileSync) {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  return JSON.parse(readFile(path.join(here, "..", "package.json"), "utf8")).version;
+}
+
+/**
+ * Compare two dot-separated versions numerically.
+ *
+ * Returns -1 / 0 / 1, or `null` when either side is not a version this can order. A
+ * prerelease suffix (`2.98.0-rc.1`) is compared on its numeric prefix alone and the suffix is
+ * ignored: this package has never published one, and inventing a precedence rule for a case
+ * that does not occur would be a claim the tests could not check.
+ */
+export function compareVersions(a, b) {
+  const parse = (v) => {
+    if (typeof v !== "string") return null;
+    const core = v.trim().split(/[-+]/)[0];
+    const parts = core.split(".");
+    if (parts.length === 0 || !parts.every((p) => /^\d+$/.test(p))) return null;
+    return parts.map(Number);
+  };
+
+  const left = parse(a);
+  const right = parse(b);
+  if (!left || !right) return null;
+
+  for (let i = 0; i < Math.max(left.length, right.length); i++) {
+    const l = left[i] ?? 0;
+    const r = right[i] ?? 0;
+    if (l !== r) return l < r ? -1 : 1;
+  }
+  return 0;
+}
+
+const REMEDY = {
+  current:
+    "Nothing to do. Because these agree, a tool you cannot see genuinely does not exist in " +
+    "this version — look for it under another name, or file it. Do not wait for it to appear.",
+  behind:
+    "Your MCP process is older than the tool surface loopctl ships. A tool you cannot see may " +
+    "well exist: run /mcp to reconnect, or restart the session. DO NOT RETRY THE CALL — MCP " +
+    "binds its tool list at session start, so the same process will answer the same way for " +
+    "ever. If the reconnect does not pick it up, npm may not have finished publishing that " +
+    "version yet (the deploy and the publish run independently); wait and reconnect again.",
+  ahead:
+    "Your MCP process is NEWER than the deployment's own tree, which is normal when running " +
+    "this package from a checkout. Nothing to do about the client; a tool it declares may " +
+    "call an endpoint this deployment does not serve yet.",
+  unknown:
+    "loopctl's expected version could not be read, so staleness is undecided — this says " +
+    "nothing about whether a missing tool exists. Check LOOPCTL_SERVER and the network. The " +
+    "running version above is still exact.",
+};
+
+/**
+ * What `result.body` adds to a failed discovery request, as a sentence to append.
+ *
+ * `status 0` ALONE IS NOT A DIAGNOSIS, and this tool exists for exactly the session where the
+ * diagnosis is the whole answer. `publicApiCall` uses status 0 for every local failure and puts
+ * the cause in `body`: `Network error: <message> (<cause>)` — which is where an `ENOTFOUND` or a
+ * `ECONNREFUSED` lives — or `Request timed out after 30s` (`index.js`, its `catch` around
+ * `fetch`). A caller reading only the 0 learns that no server answered and nothing about why,
+ * so a typo'd LOOPCTL_SERVER, a dead network and a slow one are one message. An HTTP failure
+ * puts the server's own error body there instead, which is equally the thing to read.
+ *
+ * Bounded and never trusted to be a string: `apiCall`-shaped bodies are parsed JSON as often as
+ * text, and this string goes into a tool result a session reads.
+ */
+function cause(body) {
+  if (body === undefined || body === null || body === "") return "";
+
+  const text = typeof body === "string" ? body : safeJson(body);
+  if (!text) return "";
+
+  const trimmed = text.replace(/\s+/g, " ").trim();
+  if (trimmed === "") return "";
+
+  return ` ${trimmed.length > 300 ? `${trimmed.slice(0, 300)}… (truncated)` : trimmed}`;
+}
+
+function safeJson(value) {
+  try {
+    return JSON.stringify(value);
+  } catch {
+    // A circular or otherwise unserialisable body must not turn a version report into a
+    // throw — the whole contract of this tool is that it always answers.
+    return "";
+  }
+}
+
+/**
+ * `mcp_version`: what this process is running, what loopctl expects, and what the difference
+ * means.
+ *
+ * Never an error result. A discovery document that cannot be read yields `status: "unknown"`
+ * WITH the running version, because half the answer is the half the caller most needs and a
+ * version report that fails when the network does would be useless in the situation it is for.
+ */
+export async function mcpVersion(_args = {}, { publicApiCall, version, baseUrl } = {}) {
+  const running = version ?? packageVersion();
+
+  let expected = null;
+  let detail = null;
+
+  const result = await publicApiCall("GET", DISCOVERY_PATH, null);
+
+  if (result && result.error) {
+    detail = `loopctl discovery request failed (status ${result.status}).${cause(result.body)}`;
+  } else {
+    expected = result?.mcp_server?.npm_version ?? null;
+    if (!expected) {
+      detail =
+        "loopctl's discovery document carried no mcp_server.npm_version. That field is part " +
+        "of the published schema, so its absence means an older deployment.";
+    }
+  }
+
+  const order = expected === null ? null : compareVersions(running, expected);
+  const status =
+    order === null ? "unknown" : order < 0 ? "behind" : order > 0 ? "ahead" : "current";
+
+  if (status === "unknown" && expected !== null && detail === null) {
+    detail = `Neither "${running}" nor "${expected}" could be ordered as a version.`;
+  }
+
+  return {
+    running,
+    expected,
+    status,
+    remedy: REMEDY[status],
+    // WHICH deployment answered. `expected` is that deployment's own tree, so a session
+    // pointed at a staging LOOPCTL_SERVER is comparing against staging and not production,
+    // and a verdict with no server named cannot be acted on.
+    server: baseUrl ?? null,
+    ...(detail ? { detail } : {}),
+  };
+}

package/lib/story-update.js

@@ -0,0 +1,170 @@
+/**
+ * `update_story` — `PATCH /api/v1/stories/:id` (loopctl #846.6).
+ *
+ * WHY IT EXISTS. The endpoint has been served since before this package's write surface was
+ * built (`lib/loopctl_web/router.ex:477`, `StoryController, :update`) and no MCP tool reached
+ * it, so a session that filed a story and then found its own severity wrong could not correct
+ * it. `create_story`, `import_stories` and `backfill_story` were the whole write surface;
+ * `import_stories` with `merge: true` posts a WHOLE EPIC payload, so correcting one field
+ * means resending every sibling and risking them. That is the rule in loopctl's CLAUDE.md —
+ * an operator-facing endpoint is not done until an MCP tool calls it — failing for the third
+ * time on one workflow.
+ *
+ * WHAT THE ENDPOINT ACTUALLY ACCEPTS, read rather than assumed. `StoryController.update/2`
+ * (`lib/loopctl_web/controllers/story_controller.ex:429-455`) builds its attrs from exactly
+ * five params — `title`, `description`, `acceptance_criteria`, `estimated_hours`, `metadata`
+ * (`:434-440`) — and then DROPS every nil (`Map.reject`, `:443`). `Story.update_changeset/2`
+ * casts the same five (`lib/loopctl/work_breakdown/story.ex:189-195`). Nothing else on a story
+ * is reachable here: `number` cannot change after creation, and the two status fields have
+ * their own custody endpoints.
+ *
+ * THREE CONSEQUENCES OF THAT `Map.reject`, all of them things a caller would otherwise learn
+ * from a 200 that changed nothing:
+ *
+ *   1. A field cannot be NULLED through this endpoint. `description: null` is dropped before
+ *      the changeset sees it, so it is a no-op and not an erase.
+ *   2. An UNPARSEABLE `estimated_hours` is silently ignored: `parse_decimal/1`
+ *      (`story_controller.ex:530-538`) answers nil for a string `Decimal.parse/1` rejects, and
+ *      nil is then dropped. The request answers 200 with the old value. That is the one shape
+ *      refused locally below — the same reasoning as the UUID check in `lib/delivery-loop.js`:
+ *      the server's answer cannot be told apart from success, and a client check can.
+ *   3. A request naming NO updatable field is a 200 that writes an audit entry and changes
+ *      nothing (`Stories.update_story/4` logs `action: "updated"` unconditionally,
+ *      `lib/loopctl/work_breakdown/stories.ex:213-249`). Refused here.
+ *
+ * ## `metadata` IS REPLACED WHOLE, AND THAT IS THE HAZARD THIS TOOL MUST ANNOUNCE
+ *
+ * `metadata` is an ordinary `:map` field (`story.ex:84`) in the cast list above, so the map
+ * sent REPLACES the stored one — there is no merge anywhere on this path. A caller sending
+ * `{"severity": "high"}` to a story whose metadata holds six keys keeps one and loses five,
+ * and the response is a 200.
+ *
+ * That is not merely lossy, it is the laundering hazard loopctl's CLAUDE.md documents. The
+ * story field `lifecycle_entered_at` — the marker that says a story once entered the lifecycle,
+ * and therefore may not be backfilled straight to `verified` — lived in `metadata` first, and
+ * one ordinary PATCH erased it, restoring the claim -> force-unclaim -> backfill-to-verified
+ * launder. It is a COLUMN now (`story.ex:102`) precisely so that no changeset casts it, and
+ * the comment above it (`story.ex:95-101`) says never to add it to a cast list. Both halves
+ * check out: it is absent from `update_changeset/2`'s cast list above, and from
+ * `changeset/2`'s. So this endpoint can no longer erase THAT marker — and a partial `metadata`
+ * send still silently drops every other key, which is why the tool description leads with
+ * "read the story first, then send the whole map".
+ *
+ * ## KEY
+ *
+ * ORCHESTRATOR, with the hierarchy applying: the action is mounted `role: :orchestrator`
+ * (`story_controller.ex:29-30`), NOT `exact_role:`, so `RequireRole` admits a `:user` or
+ * `:superadmin` key too (`require_role.ex`'s hierarchy clause). Nothing is pinned here for
+ * that reason — `LOOPCTL_ORCH_KEY` is passed as an ordinary override, so a global
+ * `LOOPCTL_API_KEY` of any sufficient role still wins, exactly as it does for `create_story`
+ * and `backfill_story`. The tenant must also be human-anchored (`RequireHumanAnchor`,
+ * `story_controller.ex:35-36`): an agent-rooted tenant is refused 403 `custody_tier_required`.
+ *
+ * ## `story_id` IS SHAPE-CHECKED, ON THE SHARED GUARD AND NOT A SECOND COPY
+ *
+ * This tool shipped without one while all four verbs in `lib/delivery-loop.js` had it, and the
+ * omission made this file's own tool description false: it promises "404 for an unknown story"
+ * as that status's only meaning. A malformed id gets the SAME 404.
+ * `StoryController.update/2` reaches `Stories.get_story/2`
+ * (`lib/loopctl/work_breakdown/stories.ex:185-190`), whose `AdminRepo.get_by(Story, id:
+ * story_id, …)` puts the value into a `where` against a `:binary_id` column with no cast; the
+ * `Ecto.Query.CastError` that raises is mapped to 404 by loopctl's deliberate backstop
+ * (`lib/loopctl_web/plugs/cast_error_handler.ex:32-35`), and the body is
+ * `LoopctlWeb.ErrorJSON`'s generic `{"error": {"status": 404, "message": "Not found"}}` — byte
+ * for byte what `FallbackController` answers for a well-formed id naming no story
+ * (`lib/loopctl_web/fallback_controller.ex:74-78`). Two opposite remedies, one answer.
+ *
+ * The check is `uuid()`, IMPORTED from `lib/delivery-loop.js` rather than reimplemented, so the
+ * refusal a caller reads for a bad `story_id` does not depend on which tool they reached for.
+ * Its reasoning — why the refusal carries `status: 0` and never echoes the value — is the long
+ * comment over it there, and it is not restated here.
+ */
+
+import { uuid as uuidRefusal } from "./delivery-loop.js";
+
+const UPDATABLE = ["title", "description", "acceptance_criteria", "estimated_hours", "metadata"];
+
+function refuse(body) {
+  return { error: true, status: 0, body };
+}
+
+export function storyPath(storyId) {
+  return `/api/v1/stories/${encodeURIComponent(storyId)}`;
+}
+
+/**
+ * Build the PATCH body from the fields the caller actually named.
+ *
+ * `undefined` means "not named" and is omitted. `null` is NOT silently omitted: it is refused,
+ * because a caller writing it means to clear the field and the server would answer 200 having
+ * dropped it (`Map.reject`, `story_controller.ex:443`).
+ */
+export function updateBody(args = {}) {
+  const body = {};
+
+  for (const field of UPDATABLE) {
+    const value = args[field];
+    if (value === undefined) continue;
+    if (value === null) {
+      return {
+        error: `\`${field}\` cannot be set to null through this endpoint. The controller drops ` +
+          `every nil before the changeset sees it, so the request would answer 200 with the ` +
+          `field unchanged. Send the value you want, or leave the field out.`,
+      };
+    }
+    body[field] = value;
+  }
+
+  return { body };
+}
+
+/**
+ * `PATCH /api/v1/stories/:id` — correct a filed story's title, description, acceptance
+ * criteria, estimate or metadata.
+ */
+export async function updateStory(args = {}, { apiCall } = {}) {
+  const bad = uuidRefusal(args.story_id, "story_id");
+  if (bad) return bad;
+
+  const { story_id } = args;
+
+  const { body, error } = updateBody(args);
+  if (error) return refuse(error);
+
+  if (Object.keys(body).length === 0) {
+    return refuse(
+      "Nothing to update. Name at least one of: " +
+        UPDATABLE.join(", ") +
+        ". A request carrying none of them is a 200 that changes nothing and still writes an " +
+        "audit entry.",
+    );
+  }
+
+  if (body.estimated_hours !== undefined && !numeric(body.estimated_hours)) {
+    return refuse(
+      "`estimated_hours` must be a number, or a string a decimal parser accepts. loopctl " +
+        "parses it with Decimal.parse/1 and DROPS the field when that fails, so an " +
+        "unparseable value answers 200 with the estimate unchanged — indistinguishable from " +
+        "success.",
+    );
+  }
+
+  if (body.metadata !== undefined && !plainObject(body.metadata)) {
+    return refuse(
+      "`metadata` must be an object. The server validates the same thing and answers 422 " +
+        "(`must be a map`); refusing here says so without a round trip.",
+    );
+  }
+
+  return apiCall("PATCH", storyPath(story_id), body);
+}
+
+function numeric(value) {
+  if (typeof value === "number") return Number.isFinite(value);
+  if (typeof value !== "string") return false;
+  return /^[+-]?(\d+(\.\d*)?|\.\d+)([eE][+-]?\d+)?$/.test(value.trim());
+}
+
+function plainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/package.json

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