loopctl-mcp-server 2.98.0 → 2.100.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)
@@ -502,11 +504,11 @@ Enroll the dev machines that run the agent delivery loop, see which are connecte
 
 | Tool | Description |
 |---|---|
-| `runner_enroll` | Enroll this machine as a runner (`POST /api/v1/runners`). Required: `name` (the machine name the runner declares when it joins) and `token_file` (absolute, or starting with `~/`). Optional: `max_sessions` (1..64, default 2) — how many dispatches loopctl keeps in flight on this machine at once; the tenant's total across its runners is capped separately by the server. The credential is written to `token_file` with mode 0600 and is **never returned**: the result is only `{ runner: {id, name, inserted_at}, token_file }`, because a tool result lands in the transcript and the token lets its holder join as that machine. The file is created exclusively, so an existing path (or a symlink there) is refused before anything is enrolled; missing parent directories are created 0700. If the token cannot be written after enrollment, the runner is revoked before the error returns. Only a 4xx is treated as a refusal: any other failure (timeout, 5xx, a 2xx that did not parse) may have enrolled the runner, so its response body is never echoed, the runner is revoked when the response proves its id, and otherwise the error points at `runner_list` and `runner_revoke`. 422 (name malformed or taken) and 403 (`custody_tier_required`, `api_key_mint_forbidden`) pass through with their code. |
+| `runner_enroll` | Enroll this machine as a runner (`POST /api/v1/runners`). Required: `name` (the machine name the runner declares when it joins) and `token_file` (absolute, or starting with `~/`). Optional: `max_sessions` (1..64, default 2) — the CEILING on how many dispatches loopctl will ever keep in flight on this machine at once, and the value it starts at. Since runner contract 1.13.0 every join re-applies the machine's own declared `max_sessions` bounded by this one, so a machine may take itself down below its grant and cannot raise itself above it: to carry FEWER sessions change `control.max_sessions` in the runner's own config and reconnect, to carry MORE `runner_revoke` it first and then enrol it again (nothing widens the ceiling in place, and enrolling the same name while its runner is active is a 422; the revoke invalidates the credential, so the new token file must reach the machine and the runner be restarted). The tenant's total across its runners is capped separately by the server. The credential is written to `token_file` with mode 0600 and is **never returned**: the result is only `{ runner: {id, name, inserted_at}, token_file }`, because a tool result lands in the transcript and the token lets its holder join as that machine. The file is created exclusively, so an existing path (or a symlink there) is refused before anything is enrolled; missing parent directories are created 0700. If the token cannot be written after enrollment, the runner is revoked before the error returns. Only a 4xx is treated as a refusal: any other failure (timeout, 5xx, a 2xx that did not parse) may have enrolled the runner, so its response body is never echoed, the runner is revoked when the response proves its id, and otherwise the error points at `runner_list` and `runner_revoke`. 422 (name malformed or taken) and 403 (`custody_tier_required`, `api_key_mint_forbidden`) pass through with their code. |
 | `runner_list` | List enrolled runners (`GET /api/v1/runners`). Optional: `include_revoked`. Enrollment only; connection state is `runner_pool`. |
 | `runner_revoke` | Revoke a runner (`DELETE /api/v1/runners/:id`): its credential stops authenticating and its live socket is disconnected. The undo for `runner_enroll`. Idempotent. Required: `id`. |
-| `runner_pool` | The tenant's connected runners from Presence (`GET /api/v1/runners/pool`): per machine name, `runner_id`, `joined_at`, `draining`, the latest `sample`, `live_sockets` (above 1 means more than one process holds the credential), and the `node` and `machine_id` (Fly Machine) holding the socket. `in_flight` and `max_sessions` are the capacity loopctl holds in Postgres — what dispatch reserves against — and are null only for a runner revoked while its socket drains; `reported_in_flight` and `reported_max_sessions` are the runner's own last report, a hint. Presence converges only within a cluster. |
-| `place_dispatch` | **Place a queued story on a runner** (`POST /api/v1/runners/:runner_id/dispatches`): claims it under a freshly minted custody dispatch and pushes the work. The control-side trigger of the delivery loop. Required: `story_id`, `runner_id` (from `runner_pool`). Optional: `kind` (`implement`, the only kind this tool sends — `triage` is dispatchable on the contract but placement CLAIMS the story, which triage must not do), `dispatch_id` (the idempotency key — generated when absent; pass the SAME one to retry rather than start a second session), `branch`, `base_branch`, `wall_clock_seconds`, `max_turns`. The story object is NOT a parameter: loopctl builds it from its own rows and refuses a caller-supplied one. The story must be `contracted` with its stage at `queued`. Requires `LOOPCTL_USER_KEY`. |
+| `runner_pool` | The tenant's connected runners from Presence (`GET /api/v1/runners/pool`): per machine name, `runner_id`, `joined_at`, `draining`, the latest `sample`, `live_sockets` (above 1 means more than one process holds the credential), and the `node` and `machine_id` (Fly Machine) holding the socket. `in_flight` and `max_sessions` are the capacity loopctl holds in Postgres — what dispatch reserves against — and are null only for a runner revoked while its socket drains; `reported_in_flight` and `reported_max_sessions` are the runner's own last report: `reported_in_flight` is a hint (the runner counts sessions, loopctl counts reservations), while `reported_max_sessions` is what `max_sessions` is copied from on every join (contract 1.13.0), capped at `enrolled_max_sessions` which is also returned. The two can differ in EITHER direction. `max_sessions` BELOW it happens when the machine is declaring above its enrolled ceiling (`enrolled_max_sessions` is what makes that one visible in the payload; the rest are not), when the declaration write has not LANDED — it can fail under lock contention on the runner row and is retried on that socket's 30-second recheck, downward only — or when the socket joined a node older than contract 1.13.0 and has not reconnected since. `max_sessions` ABOVE it happens when the machine declared `0`, held as `1` because the column is 1..64 while this field shows the raw `0`, and again when a declaration write has not landed and the row keeps an older, larger number. A `reported_max_sessions` of 0 means the machine is taking no work and `place_dispatch` refuses a new placement on it, like `draining`. Presence converges only within a cluster. |
+| `place_dispatch` | **Place a queued story on a runner** (`POST /api/v1/runners/:runner_id/dispatches`): claims it under a freshly minted custody dispatch and pushes the work. The control-side trigger of the delivery loop. 409 `runner_declines_work` when the machine declares `draining` or `max_sessions` 0 — refused before the mint, so nothing was claimed; a retry carrying a `dispatch_id` loopctl already holds is re-sent anyway, because its claim is already standing. Required: `story_id`, `runner_id` (from `runner_pool`). Optional: `kind` (`implement`, the only kind this tool sends — `triage` is dispatchable on the contract but placement CLAIMS the story, which triage must not do), `dispatch_id` (the idempotency key — generated when absent; pass the SAME one to retry rather than start a second session), `branch`, `base_branch`, `wall_clock_seconds`, `max_turns`. The story object is NOT a parameter: loopctl builds it from its own rows and refuses a caller-supplied one. The story must be `contracted` with its stage at `queued`. Requires `LOOPCTL_USER_KEY`. |
 | `story_stage` | **Where a story is in the delivery machine** (`GET /api/v1/stories/:id/stage`): stage, `claim_epoch`, `lock_version`, `attempts`, the runner holding it, and the escalation reason when parked. `stage: null` means the loop has never touched it. This is how you watch a run, and the only way to see why a stage report was refused `stale_stage`. `escalation_reason` is untrusted session text. Required: `story_id`. |
 | `resolve_escalation` | **Move an escalated story off `escalated`, as a human** (`POST /api/v1/stories/:id/stage/resolve`): `to` is `queued` (work it again), `done` or `failed`. The other half of `escalate_story` — without it a parked story stays parked for ever. Requires `LOOPCTL_USER_KEY` on a key no dispatch minted: a session cannot resolve the escalation it raised. Optional: `reason`. |
 | `force_unclaim_story` | **Take a story back from the agent holding it** (`POST /api/v1/stories/:id/force-unclaim`). Resets it to `agent_status: pending` with `assigned_agent_id` cleared AND makes the delivery stage row follow the release back to `queued`. **It frees the STAGE; it does not make the story placeable.** `place_dispatch` wants `contracted` + `queued` (see its own row in this table), and the release leaves the story at `pending`, whose only transition is `pending -> contracted` — so running `place_dispatch` next answers the identical 409 `invalid_transition`. The remedy is three calls, in this order: `force_unclaim_story`, then `contract_story`, then `place_dispatch`. A story parked at `claimed` with nobody on it is the residue of a compensation that did not complete, not what a refused dispatch normally leaves: placement releases the claim inline when a runner refuses, and the claim lease releases it unattended once `claimed_until` passes — reach for this to get it back now, or when both of those left it held. Requeues from any stage a claim holds; a stage no claim holds keeps its stage and is rebound to the new epoch; `done` and `failed` are untouched. For an ESCALATED story use `resolve_escalation` instead — that one releases AND re-contracts, so its `queued` really is placeable. Requires an orchestrator-ROLE key: the action is `exact_role: :orchestrator`, so a user or superadmin key is 403'd like any other non-member. Put it in `LOOPCTL_ORCH_KEY` (which is then the key sent, and a global `LOOPCTL_API_KEY` does not displace it) or, with no orchestrator key set, in `LOOPCTL_API_KEY`. The orchestrator key must be linked to a registered agent (400 otherwise) and the tenant must be human-anchored (403 `custody_tier_required` otherwise). Does not touch `verified_status`. Safe to run twice: on an already-pending story the stage row is written only if it is stranded behind the story's claim epoch or still in flight. No request body. Required: `story_id` (refused locally if it is not a UUID). |

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,15 +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
@@ -3289,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}`);
@@ -4047,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:
@@ -7593,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)
   {
@@ -7755,8 +7877,18 @@ const TOOLS = [
           minimum: 1,
           maximum: 64,
           description:
-            "How many dispatches loopctl keeps in flight on this machine at once (default 2). " +
-            "The tenant's total across all its runners is capped separately by the server.",
+            "The CEILING on how many dispatches loopctl will ever keep in flight on this " +
+            "machine at once (default 2), and the value it starts at. Since runner contract " +
+            "1.13.0 every join re-applies the machine's own declared max_sessions BOUNDED BY " +
+            "this one, so a machine may take itself down below its grant and cannot raise " +
+            "itself above it. To make a machine carry FEWER sessions, change " +
+            "control.max_sessions in the runner's own config and reconnect it — no call here " +
+            "is needed. To let it carry MORE than its grant, runner_revoke it FIRST and then " +
+            "enrol it again: nothing widens this in place, and enrolling the same machine name " +
+            "while its current runner is active is a 422. The revoke invalidates the " +
+            "credential, so the new token_file must reach the machine and the runner be " +
+            "restarted. The tenant's total across all its runners is capped separately by " +
+            "the server.",
         },
       },
       required: ["name", "token_file"],
@@ -7800,7 +7932,23 @@ const TOOLS = [
       "and machine_id (Fly Machine) holding the socket. in_flight and max_sessions are the " +
       "CAPACITY loopctl holds in Postgres — the slots dispatch reserves against — and are null " +
       "only for a runner revoked while its socket drains; reported_in_flight and " +
-      "reported_max_sessions are what the runner itself last reported, a hint. live_sockets " +
+      "reported_max_sessions are what the runner itself last reported. reported_in_flight is a " +
+      "hint (the runner counts sessions, loopctl counts reservations); reported_max_sessions is " +
+      "NOT — since contract 1.13.0 loopctl copies it into max_sessions on every join, capped at " +
+      "the runner's enrolled_max_sessions, which is also returned. The two can differ in EITHER " +
+      "direction, so read a difference rather than assuming it. max_sessions BELOW " +
+      "reported_max_sessions happens when the machine is declaring above the ceiling it was " +
+      "enrolled with (enrolled_max_sessions is what makes that one visible in the payload; the " +
+      "rest are not), when the declaration write has not LANDED — it can fail under lock " +
+      "contention " +
+      "on the runner row and is retried on that socket's 30-second recheck, downward only — or " +
+      "when the socket joined a node older than contract 1.13.0 and has not reconnected since. " +
+      "max_sessions ABOVE reported_max_sessions happens when the machine declared 0, which the " +
+      "1..64 column holds as 1 while this field shows the raw 0, and again when a declaration " +
+      "write has not landed and the row keeps an older, larger number. A reported_max_sessions " +
+      "of 0 means the machine is taking no work and place_dispatch refuses a new placement on " +
+      "it, like draining. " +
+      "live_sockets " +
       "above 1 means more than one process holds that runner's credential. A killed runner " +
       "disappears once its socket closes. Presence converges only " +
       "within a cluster, so on an unclustered multi-node deployment a runner on another node is " +
@@ -7826,7 +7974,14 @@ const TOOLS = [
       "IDEMPOTENT on `dispatch_id`, which is generated for you unless you pass one — pass the " +
       "SAME id to retry a call that timed out, or you start a second session on the same " +
       "story. Requires LOOPCTL_USER_KEY: only an unlineaged user key may root the custody " +
-      "lineage this mints.",
+      "lineage this mints.\n\n" +
+      "409 `runner_declines_work` means the machine's live socket declares `draining` (or a " +
+      "max_sessions of 0, which says the same thing). NOTHING WAS CLAIMED — it is refused " +
+      "before the mint — so place on another runner rather than repairing anything, with a " +
+      "NEW dispatch_id. Read `draining` and `reported_max_sessions` from runner_pool before " +
+      "choosing a machine. It refuses a NEW placement only: retrying with a dispatch_id " +
+      "loopctl already holds still re-sends that dispatch, because its claim is already " +
+      "standing and a draining machine is asked to finish what it holds, not to take more.",
     inputSchema: {
       type: "object",
       properties: {
@@ -7851,6 +8006,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." },
@@ -8669,6 +8835,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);
 
@@ -8957,6 +9126,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     case "list_routes":
       return await listRoutes();
 
+    case "mcp_version":
+      return await mcpVersion(args);
+
     case "dispatch":
       return await createDispatch(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/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.98.0",
+  "version": "2.100.0",
   "description": "MCP server for loopctl — structural trust for AI development loops",
   "type": "module",
   "main": "index.js",