loopctl-mcp-server 2.95.0 → 2.97.0

package/README.md

@@ -67,14 +67,44 @@ Or if installed locally:
 | Variable | Description | Default |
 |---|---|---|
 | `LOOPCTL_SERVER` | loopctl server URL | `https://loopctl.com` |
-| `LOOPCTL_API_KEY` | Global API key override (if set, always used) | -- |
-| `LOOPCTL_ORCH_KEY` | Orchestrator role API key (verify, reject, review, import) | -- |
+| `LOOPCTL_API_KEY` | Global API key override: used for every tool except the exact-key ones below, and for the `exact_role: :orchestrator` custody verbs when `LOOPCTL_ORCH_KEY` is unset | -- |
+| `LOOPCTL_ORCH_KEY` | Orchestrator role API key (report, review, import, and the `exact_role: :orchestrator` custody verbs `verify_story` / `reject_story` / `verify_all_in_epic` / `bulk_mark_complete` / `force_unclaim_story` — when it is set, it is the key those five send) | -- |
 | `LOOPCTL_AGENT_KEY` | Agent role API key (contract, claim, start, request-review) | -- |
-| `LOOPCTL_USER_KEY` | User role API key (minted at signup). Required for **first-time BYO LLM key provisioning** (`set_llm_config` / `llm_config` — see [First-time setup](#first-time-setup--provision-your-byo-llm-keys)) and for destructive admin tools like `knowledge_bulk_publish`, and for the [runner tools](#runner-tools-user-key). | -- |
+| `LOOPCTL_USER_KEY` | User role API key (minted at signup). Required for **first-time BYO LLM key provisioning** (`set_llm_config` / `llm_config` — see [First-time setup](#first-time-setup--provision-your-byo-llm-keys)), for destructive admin tools like `knowledge_bulk_publish`, and for the `runner_*` tools plus `place_dispatch` and `resolve_escalation` in [Runner and delivery-loop tools](#runner-and-delivery-loop-tools). **Not for the whole of that section:** `story_stage` takes `LOOPCTL_AGENT_KEY`, and `force_unclaim_story` is `exact_role: :orchestrator`, where a user key is 403'd like any other non-member. | -- |
 | `LOOPCTL_STH_STATE_PATH` | Absolute path for the witness-protocol STH cache file (see [Witness protocol](#witness-protocol-sth)). Optional. | per-(server + key) file under the OS temp dir |
 
 Key resolution priority: `LOOPCTL_API_KEY` > tool-specific key > `LOOPCTL_ORCH_KEY`.
 
+**The exception: tools pinned to an EXACT key.** Some endpoints are gated `exact_role:`,
+where the role hierarchy does NOT apply — a higher-privileged key is refused there exactly
+as a lower one is. For those tools the global override does not silently win over the
+variable the tool names, so a key you set for a specific role is the key that gets sent:
+
+| Tool | Key | When the override applies |
+|---|---|---|
+| `verify_story`, `reject_story`, `verify_all_in_epic`, `bulk_mark_complete`, `force_unclaim_story` | `LOOPCTL_ORCH_KEY` (`exact_role: :orchestrator`) | Pinned **when `LOOPCTL_ORCH_KEY` is set**. With no orchestrator key, `LOOPCTL_API_KEY` is still sent — set it to an orchestrator-role key and these work. |
+| `place_dispatch`, `resolve_escalation` | `LOOPCTL_USER_KEY` (an unlineaged human principal) | Always pinned; `LOOPCTL_API_KEY` is never consulted. |
+| `set_llm_config`, `llm_config` and the other secret-managing tools | `LOOPCTL_USER_KEY` | Always pinned; a secret operation must not run under a non-user global key. |
+
+Why pin at all: the priority above means `LOOPCTL_API_KEY` beats the variable a tool names,
+so an operator who sets `LOOPCTL_ORCH_KEY` for the custody verbs and `LOOPCTL_API_KEY` for
+everything else had the orchestrator key discarded on exactly the calls it was set for. It
+is **not** because the resulting 403 is confusing — `LoopctlWeb.Plugs.RequireRole` runs
+first and answers with `code: "insufficient_role"` and `required_roles: ["orchestrator"]`,
+which names the problem correctly.
+
+`report_story` and `review_complete` are NOT in this table: their gates take a role RANGE
+(`exact_role: [:agent, :orchestrator]` and `[:orchestrator, :user]`), so the
+`LOOPCTL_API_KEY` fallback is what makes the common agent configuration work — that is
+`LOOPCTL_API_KEY` set to an agent key. **`LOOPCTL_AGENT_KEY` alone is not that configuration
+for these two**: the priority above never consults `LOOPCTL_AGENT_KEY` by name, only a tool's
+own key, and `report_story` and `review_complete` both name `LOOPCTL_ORCH_KEY` as theirs — so
+with only `LOOPCTL_AGENT_KEY` set they answer "No API key configured" before reaching their
+gate. Most agent-facing tools do name `LOOPCTL_AGENT_KEY` as their own key and so do work
+under it alone; these two are the exception, and `story_stage` reads it explicitly for the
+same reason. The conditional pin in the first row is that same reasoning applied to the
+single-role gates.
+
 ## First-time setup — provision your BYO LLM keys
 
 **loopctl is agent-native and strictly BYO (bring-your-own-keys).** loopctl fronts
@@ -466,9 +496,9 @@ through the same authenticated + witness/STH path as every static read tool. If
 `/retrieve/tools` fetch fails, listing degrades to the static tools (never errors).
 The generated-tool count per tenant is bounded by the per-tenant entity cap.
 
-### Runner Tools (user key)
+### Runner and delivery-loop tools
 
-Enroll the dev machines that run the agent delivery loop, and see which are connected (issue #809). All four require `LOOPCTL_USER_KEY`; enroll and revoke also require a human-anchored tenant.
+Enroll the dev machines that run the agent delivery loop, see which are connected (issue #809), place work on them and recover a story a runner would not take. The `runner_*` tools require `LOOPCTL_USER_KEY`, and enroll and revoke additionally require a human-anchored tenant. The delivery-loop verbs below do NOT share one key — each row names the key its endpoint's gate demands, and a higher-privileged key does not substitute for an `exact_role` one.
 
 | Tool | Description |
 |---|---|
@@ -476,9 +506,10 @@ Enroll the dev machines that run the agent delivery loop, and see which are conn
 | `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` default, or `triage`), `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`. |
+| `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`. |
 | `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). |
 
 ### Dispatch & Chain of Custody (v2) Tools
 

package/index.js

@@ -42,12 +42,14 @@ import {
   createGeneratedToolsRuntime,
   GENERATED_TOOL_PREFIX,
 } from "./lib/generated-tools.js";
+import { exactKeyMissingMessage, orchestratorKeyArgs } from "./lib/custody-key.js";
 import { createHandoff } from "./lib/handoff.js";
 import { readPayloadFile } from "./lib/payload-path.js";
 import { enrollRunner, listRunners, revokeRunner, runnerPool } from "./lib/runners.js";
 import { claimLeaseNotice, renewStoryClaim as renewStoryClaimRequest } from "./lib/claim-lease.js";
 import { escalateStory as escalateStoryRequest, escalationNotice } from "./lib/escalation.js";
 import {
+  forceUnclaimStory as forceUnclaimStoryRequest,
   placeDispatch as placeDispatchRequest,
   resolveEscalation as resolveEscalationRequest,
   storyStage as storyStageRequest,
@@ -149,12 +151,38 @@ function cachedClientContextHeader() {
   return clientContextHeaderCache;
 }
 
-async function apiCall(method, path, body, keyOverride, { exactKey = false, timeoutMs } = {}) {
+async function apiCall(
+  method,
+  path,
+  body,
+  keyOverride,
+  { exactKey = false, timeoutMs, keyHint } = {},
+) {
   const url = `${getBaseUrl()}${path}`;
-  // Secret-managing tools pass exactKey:true so the request uses the EXACT
-  // role-pinned key (LOOPCTL_USER_KEY) and does NOT fall back to the global
-  // LOOPCTL_API_KEY override — a secret op must never silently run under a
-  // non-user global key (review #12).
+  // `exactKey` sends `keyOverride` VERBATIM instead of consulting `resolveKey`
+  // (defined above), whose priority is LOOPCTL_API_KEY > keyOverride >
+  // LOOPCTL_ORCH_KEY — so without it a global LOOPCTL_API_KEY displaces the key a
+  // tool names. Two families pass it, for two different reasons:
+  //
+  //   - USER-ROLE-PINNED tools pass LOOPCTL_USER_KEY with `exactKey: true`
+  //     UNCONDITIONALLY. Named rather than cited by line, because a line number here
+  //     drifts with every edit above it: `llmConfig` / `setLlmConfig`, the egress
+  //     allowlist verbs (`clearLocalOnly`, `declareTrustedEndpoint`,
+  //     `revokeTrustedEndpoint`), the WebAuthn enrollment and revocation verbs
+  //     (`requestAuthenticatorChallenge`, `enrollAuthenticator`,
+  //     `requestAuthenticatorRevokeChallenge`, `revokeAuthenticator`), and the shared
+  //     `runnerDeps()` / `deliveryDeps()` factories — the latter covering
+  //     `place_dispatch` and `resolve_escalation`, which need an unlineaged human
+  //     principal. `grep -n 'exactKey: true' index.js` is the current list. None of
+  //     them may silently run under a global key of another role (review #12).
+  //   - The `exact_role: :orchestrator` CUSTODY verbs pass it CONDITIONALLY, and
+  //     nothing here decides that: `orchestratorKeyArgs` (`lib/custody-key.js`)
+  //     returns `exactKey` only when LOOPCTL_ORCH_KEY is set, and returns no options
+  //     at all when only LOOPCTL_API_KEY is — an orchestrator-role global key was a
+  //     working, documented configuration before 2.97.0 and still reaches the gate.
+  //     The reason for pinning is the operator's EXPRESSED CHOICE of variable, never
+  //     the shape of the server's 403; `lib/custody-key.js` reads the plug and shows
+  //     why that 403 was never ambiguous.
   const key = exactKey ? keyOverride : resolveKey(keyOverride);
 
   if (!key) {
@@ -162,7 +190,12 @@ async function apiCall(method, path, body, keyOverride, { exactKey = false, time
       error: true,
       status: 0,
       body: exactKey
-        ? "No user-role API key configured. Set LOOPCTL_USER_KEY to a user-role key to manage LLM configuration."
+        ? // `keyHint` names the env var THIS site is pinned to. Without it the message
+          // below talks about LLM configuration, which is right for set_llm_config and
+          // actively misleading for a custody verb that is missing its orchestrator key.
+          keyHint
+          ? exactKeyMissingMessage(keyHint)
+          : "No user-role API key configured. Set LOOPCTL_USER_KEY to a user-role key to manage LLM configuration."
         : "No API key configured. Set LOOPCTL_API_KEY, LOOPCTL_ORCH_KEY, or LOOPCTL_AGENT_KEY.",
     };
   }
@@ -1246,21 +1279,34 @@ async function verifyStory({ story_id, summary, review_type, claim }) {
   if (review_type) body.review_type = review_type;
   if (claim) body.claim = claim;
 
+  // `exact_role: :orchestrator` (`story_verification_controller.ex:29-30`). When
+  // LOOPCTL_ORCH_KEY is set it is sent EXACTLY, because `resolveKey` would otherwise
+  // discard it in favour of a global LOOPCTL_API_KEY on the very calls it was set for.
+  // When it is NOT set, the global key still goes — see lib/custody-key.js for why the
+  // pin is narrowed that way, and for what the 403 from that gate actually says.
+  const orch = orchestratorKeyArgs();
+
   const result = await apiCall(
     "POST",
     `/api/v1/stories/${story_id}/verify`,
     body,
-    process.env.LOOPCTL_ORCH_KEY
+    orch.override,
+    orch.options,
   );
   return toContent(result);
 }
 
 async function rejectStory({ story_id, reason }) {
+  // `exact_role: :orchestrator` (`story_verification_controller.ex:29-30`) — see
+  // lib/custody-key.js.
+  const orch = orchestratorKeyArgs();
+
   const result = await apiCall(
     "POST",
     `/api/v1/stories/${story_id}/reject`,
     { reason },
-    process.env.LOOPCTL_ORCH_KEY
+    orch.override,
+    orch.options,
   );
   return toContent(result);
 }
@@ -1269,21 +1315,31 @@ async function rejectStory({ story_id, reason }) {
 
 async function bulkMarkComplete({ stories }) {
   // stories: [{story_id, summary, review_type}]
+  // `exact_role: :orchestrator` (`bulk_operations_controller.ex:24-25`) — see
+  // lib/custody-key.js.
+  const orch = orchestratorKeyArgs();
+
   const result = await apiCall(
     "POST",
     "/api/v1/stories/bulk/mark-complete",
     { stories },
-    process.env.LOOPCTL_ORCH_KEY
+    orch.override,
+    orch.options,
   );
   return toContent(result);
 }
 
 async function verifyAllInEpic({ epic_id, review_type, summary }) {
+  // `exact_role: :orchestrator` (`story_verification_controller.ex:29-30`, `:verify_all`) —
+  // see lib/custody-key.js.
+  const orch = orchestratorKeyArgs();
+
   const result = await apiCall(
     "POST",
     `/api/v1/epics/${epic_id}/verify-all`,
     { review_type, summary },
-    process.env.LOOPCTL_ORCH_KEY
+    orch.override,
+    orch.options,
   );
   return toContent(result);
 }
@@ -3188,6 +3244,26 @@ async function resolveEscalation(args) {
   return toContent(await resolveEscalationRequest(args, deliveryDeps()));
 }
 
+// #846: force-unclaim is `exact_role: :orchestrator`
+// (`story_verification_controller.ex:29-30`), so this is the one delivery-loop verb that wants
+// the ORCH key. Same selection as the other four custody verbs: when LOOPCTL_ORCH_KEY is set it
+// is sent EXACTLY, because `resolveKey` (`index.js:132-138`) would otherwise discard it for a
+// global LOOPCTL_API_KEY on the one call it was set for; when it is not set, a global key still
+// goes, because an orchestrator-role LOOPCTL_API_KEY was a documented, working configuration
+// before 2.97.0. `orch.resolved` is undefined only when NEITHER is set, which is the one case
+// `forceUnclaimStoryRequest` refuses locally. `keyHint` rides along so the missing-key message
+// names LOOPCTL_ORCH_KEY instead of apiCall's LLM-config default (`index.js:174-181`).
+async function forceUnclaimStory(args) {
+  const orch = orchestratorKeyArgs();
+
+  return toContent(
+    await forceUnclaimStoryRequest(args, {
+      orchKey: orch.resolved,
+      apiCall: (method, path, body) => apiCall(method, path, body, orch.override, orch.options),
+    }),
+  );
+}
+
 // US-26: Signed Tree Head retrieval
 async function getSth({ tenant_id }) {
   const result = await apiCall("GET", `/api/v1/audit/sth/${tenant_id}`);
@@ -7677,9 +7753,14 @@ const TOOLS = [
           type: "string",
           enum: ["implement"],
           description:
-            "What the session is for. `implement` is the only kind loopctl SENDS today — " +
-            "`x-connection.dispatchable_kinds` in the runner contract is the live list, and " +
-            "a kind that is not on it is refused after the claim, not before it.",
+            "What the session is for. `implement` is the only kind THIS tool sends, and the " +
+            "narrowness is deliberate rather than a gap in the contract: `triage` became " +
+            "dispatchable in 1.10.0, but placement CLAIMS the story — that is what mints the " +
+            "custody lineage — while a triage session only reads, and loopctl dispatches " +
+            "triage itself from `detected` without claiming anything. Asking for `triage` " +
+            "here would claim a story for a session that is only deciding whether it is work, " +
+            "put it at `claimed`, and send a triage dispatch carrying no reporter words at " +
+            "all, because nothing on this path builds the triage object.",
         },
         dispatch_id: {
           type: "string",
@@ -7740,6 +7821,52 @@ const TOOLS = [
       required: ["story_id", "to"],
     },
   },
+  {
+    name: "force_unclaim_story",
+    description:
+      "TAKE A STORY BACK from the agent holding it (POST /api/v1/stories/:id/force-unclaim). " +
+      "Two things happen: the story resets to `agent_status: pending` with " +
+      "`assigned_agent_id` cleared, AND — in the same transaction — its delivery stage row " +
+      "follows the release back to `queued`.\n\n" +
+      "IT FREES THE STAGE; IT DOES NOT MAKE THE STORY PLACEABLE. place_dispatch wants " +
+      "`agent_status: contracted` AND stage `queued` (`Placement.claimable/2`), and the " +
+      "release leaves the story at `pending`, whose only transition is `pending -> " +
+      "contracted`. Run place_dispatch straight after this one and you get back the IDENTICAL " +
+      "409 `invalid_transition`. THE REMEDY IS THREE CALLS, in this order: " +
+      "force_unclaim_story, then contract_story, then place_dispatch.\n\n" +
+      "WHEN TO REACH FOR IT. A story sitting at `claimed` with nobody on it is the residue of " +
+      "a compensation that did not complete — it is NOT what a refused dispatch normally " +
+      "leaves. Placement answers a runner's refusal INLINE by releasing the claim itself " +
+      "(`Placement.undo_claim/5`), and if that release fails the claim lease is a further " +
+      "backstop: `Progress.reclaim_expired_claim/3` releases over `:runner_lost` and requeues " +
+      "the stage, unattended, once `claimed_until` has passed. Use this tool to get the story " +
+      "back NOW rather than at lease expiry, or when both of those have left it held.\n\n" +
+      "The release requeues from any stage a claim holds (`claimed`, `worktree`, " +
+      "`implementing`, `reviewing`, `pr_open`, `ci`); a stage no claim holds keeps its stage " +
+      "and is rebound to the new claim epoch; `done` and `failed` are left alone. An ESCALATED " +
+      "story is not this tool's job — use resolve_escalation, which releases AND re-contracts " +
+      "for you, so a story it sends to `queued` really is placeable.\n\n" +
+      "REFUSALS. Requires an ORCHESTRATOR-ROLE key, in LOOPCTL_ORCH_KEY or LOOPCTL_API_KEY: " +
+      "the action is `exact_role: :orchestrator`, so a user or superadmin key is 403'd like " +
+      "any other non-member and reaching for a higher-privileged key does NOT get past it. " +
+      "When LOOPCTL_ORCH_KEY is set it is the key sent, and a global LOOPCTL_API_KEY does not " +
+      "displace it. The orchestrator key must also be LINKED TO " +
+      "A REGISTERED AGENT — an unlinked one is refused 400 naming that — and the tenant must be " +
+      "human-anchored (403 `custody_tier_required` otherwise). 404 for an unknown story, 429 " +
+      "when rate limited. A `story_id` that is not a UUID is refused here, before any call.\n\n" +
+      "It does NOT touch `verified_status`, and it is safe to run twice: on an already-pending " +
+      "story the stage row is written only when it needs to be — a row STRANDED behind the " +
+      "story's claim epoch is rebound to it (the remedy for a row an older release left " +
+      "behind) and an in-flight row is requeued, while a row already at that epoch is left " +
+      "exactly as it is. It takes no request body.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        story_id: { type: "string", description: "The story UUID to free." },
+      },
+      required: ["story_id"],
+    },
+  },
 
   // LCP-1 §9 signed-profile tools
   {
@@ -8771,6 +8898,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     case "resolve_escalation":
       return await resolveEscalation(args);
 
+    case "force_unclaim_story":
+      return await forceUnclaimStory(args);
+
     case "register_custody_owner_key":
       return await registerCustodyOwnerKey(args);
 

package/lib/custody-key.js

@@ -0,0 +1,112 @@
+/**
+ * Key selection for the `exact_role: :orchestrator` custody verbs (loopctl #846 review round 2).
+ *
+ * WHICH VERBS. `verify`, `reject` and `force_unclaim` plus the aggregate `verify_all`
+ * (`lib/loopctl_web/controllers/story_verification_controller.ex:29-30`), and bulk
+ * `verify`/`reject`/`mark_complete`
+ * (`lib/loopctl_web/controllers/bulk_operations_controller.ex:24-25`). All are mounted
+ * `exact_role: :orchestrator`, where the role hierarchy does NOT apply: `RequireRole`'s
+ * exact-role clause tests `api_key.role == exact_role` (`require_role.ex:65-75`), so a `:user`
+ * or `:superadmin` key is refused there exactly as an `:agent` key is.
+ *
+ * WHAT THE PINNING IS FOR — and what it is NOT for.
+ *
+ * NOT for the error message. An earlier draft of this comment, and every copy of it that had
+ * spread across this package and both changelogs, claimed a 403 from that gate "reads as a
+ * custody refusal about the STORY rather than a misconfigured key". That is false and the
+ * source says so: `RequireRole.forbid/3` (`require_role.ex:112-128`) halts with 403,
+ * `code: "insufficient_role"`, `required_roles: ["orchestrator"]` and the message "This
+ * endpoint requires the orchestrator role", and the plug is mounted FIRST, so the request
+ * never reaches the controller and never reaches `Progress.validate_not_self_verify/4` where
+ * the custody 409s are raised. The role error is unambiguous. Do not reintroduce that
+ * justification. It came back twice after being "removed everywhere", so it is no longer swept
+ * by hand: `test/no_false_403_claim.test.js` fails on any assertion of it anywhere in this
+ * package or in either changelog. It admits a quotation like the one above, but only where a
+ * disproof marker sits within a sentence or so of it — a whole-paragraph rule was too loose,
+ * since this refutation runs a dozen lines and its closing "do not reintroduce" would have
+ * excused an assertion at the far end of the very block that disproves the claim.
+ *
+ * What the pinning IS for is an operator's expressed configuration. `resolveKey` in
+ * `index.js` reads `LOOPCTL_API_KEY || keyOverride || LOOPCTL_ORCH_KEY` — the global
+ * override wins over the key the tool names. So an operator who set `LOOPCTL_ORCH_KEY`
+ * specifically for these verbs AND a `LOOPCTL_API_KEY` of some other role for everything else
+ * had the orchestrator key silently discarded on precisely the calls they set it for, and paid a
+ * round trip to learn it. Honouring it costs nothing and is what they asked for.
+ *
+ * WHY IT IS NARROWED TO "WHEN THE ORCH KEY IS SET". Pinning unconditionally is a BEHAVIOURAL
+ * BREAK in a minor release, and the configuration it breaks is one the shipped docs endorsed:
+ * 2.96.0's `README.md:70` describes `LOOPCTL_API_KEY` as "Global API key override (if set,
+ * always used)". `LOOPCTL_API_KEY` set to an orchestrator-role key, with no `LOOPCTL_ORCH_KEY`
+ * at all, was working, documented, and accepted by the gate — the key's ROLE is what the server
+ * tests, and it is `:orchestrator`. An unconditional pin refuses that locally, sends nothing, and
+ * tells the operator their key is the wrong role when it is not. This is the same reasoning that
+ * leaves `report_story` and `review_complete` unpinned in `test/custody_key_pinning.test.js`,
+ * applied consistently.
+ */
+
+/**
+ * The `keyOverride` and options a custody verb should hand `apiCall`, plus the key that will
+ * actually be sent.
+ *
+ * @param {Record<string, string|undefined>} [env]
+ * @returns {{override: string|undefined, options: object, resolved: string|undefined}}
+ *   `override` is `apiCall`'s 4th argument, `options` its 5th, and `resolved` is the key the
+ *   request will carry — `undefined` when no key is configured at all, which is the only case a
+ *   caller may refuse locally on.
+ */
+export function orchestratorKeyArgs(env = process.env) {
+  const orchKey = env.LOOPCTL_ORCH_KEY;
+
+  if (orchKey) {
+    // The operator named a key for this role. Send exactly it: `exactKey` makes `apiCall` use
+    // the override verbatim instead of `resolveKey` — the `const key = exactKey ? keyOverride :
+    // resolveKey(keyOverride)` line in `index.js`.
+    return {
+      override: orchKey,
+      options: { exactKey: true, keyHint: "LOOPCTL_ORCH_KEY" },
+      resolved: orchKey,
+    };
+  }
+
+  const globalKey = env.LOOPCTL_API_KEY;
+
+  if (globalKey) {
+    // No orchestrator key, but a global one. This is the pre-2.97.0 configuration and it is
+    // still allowed to reach the gate: if that key is orchestrator-role it passes, and if it is
+    // not, the server's own 403 names the required role. Refusing it here would break a working
+    // setup to pre-empt an error the server already reports correctly.
+    return { override: undefined, options: {}, resolved: globalKey };
+  }
+
+  // Nothing configured. Pin anyway, so `apiCall`'s missing-key branch (`if (!key)`, in
+  // `index.js`) takes the `keyHint` path and names LOOPCTL_ORCH_KEY rather than falling back to
+  // the LLM-config default. Callers that refuse locally (see `forceUnclaimStory`) branch on
+  // `resolved` being undefined.
+  return {
+    override: undefined,
+    options: { exactKey: true, keyHint: "LOOPCTL_ORCH_KEY" },
+    resolved: undefined,
+  };
+}
+
+/**
+ * What `apiCall` says when an `exactKey` site names a variable (`keyHint`) and no key is
+ * configured at all.
+ *
+ * The message it replaced said "LOOPCTL_API_KEY is deliberately not a fallback for it", which
+ * is now false guidance: this branch is reached only when NEITHER the hinted variable nor
+ * LOOPCTL_API_KEY is set, and setting LOOPCTL_API_KEY to a key of the right role IS a working
+ * configuration (see `orchestratorKeyArgs`). Telling an operator with no keys at all that one
+ * of their two options does not work sends them the long way round.
+ *
+ * What it must NOT say instead is that any key will do: the gate matches the role exactly, so
+ * a higher-privileged key is refused there like any other non-member.
+ */
+export function exactKeyMissingMessage(keyHint) {
+  return (
+    `No API key configured. Set ${keyHint} — or LOOPCTL_API_KEY — to a key of the exact role ` +
+    `this endpoint requires; its gate matches the role exactly, so a higher-privileged key is ` +
+    `refused there like any other. When ${keyHint} is set it is the key sent, and a global ` +
+    `LOOPCTL_API_KEY does not displace it.`
+  );
+}

package/lib/delivery-loop.js

@@ -1,16 +1,17 @@
 /**
- * The delivery loop's OPERATOR verbs (loopctl #803, #850).
+ * The delivery loop's OPERATOR verbs (loopctl #803, #850, #846).
  *
- * Three tools, and they exist because the endpoints behind them were unreachable from any
- * session on the fleet. `POST /api/v1/runners/:runner_id/dispatches` shipped with #842 and no
- * tool called it; `curl` at loopctl is refused by the fleet's own guardrail, deliberately; so
+ * These tools exist because the endpoints behind them were unreachable from any session on the
+ * fleet. `POST /api/v1/runners/:runner_id/dispatches` shipped with #842 and no tool called it;
+ * `curl` at loopctl is refused by the fleet's own guardrail, deliberately; so
  * the only way to place a dispatch was a shell on the production node. That is the same defect
  * as `place/4` shipping with no caller, failing one layer later — the trigger exists and
  * nothing outside the app can pull it.
  *
  * Mark's rule, 2026-09-15: an operator-facing endpoint is not done until an MCP tool calls it,
- * in the same change. These are that rule applied to the three verbs the loop needs to be
- * RUNNABLE (place a dispatch) and OBSERVABLE (read a story's stage, resolve an escalation).
+ * in the same change. These are that rule applied to the verbs the loop needs to be RUNNABLE
+ * (place a dispatch), OBSERVABLE (read a story's stage) and RECOVERABLE (resolve an
+ * escalation, free a story a runner refused).
  *
  * KEY SELECTION is behaviour, not a convention, so it lives here where a test can see it:
  *
@@ -19,6 +20,13 @@
  *     tree, and an agent key is refused `insufficient_role` before anything is written.
  *   - `resolve_escalation` is the HUMAN half of the escalation pair: a `:user` key no dispatch
  *     minted. The agent key that raises an escalation is 403'd on it by design.
+ *   - `force_unclaim_story` is gated `exact_role: :orchestrator`
+ *     (`story_verification_controller.ex:29-30`), so it needs an ORCHESTRATOR-ROLE key and a
+ *     higher-privileged one does NOT substitute: `RequireRole`'s exact-role clause tests
+ *     `api_key.role == exact_role` (`require_role.ex:65-75`), so a `:user` or `:superadmin`
+ *     key is 403'd there exactly as an agent key is. That is a chain-of-custody gate, not an
+ *     oversight. WHICH ENV VAR carries that key is a separate question, and `index.js` decides
+ *     it in `lib/custody-key.js`: LOOPCTL_ORCH_KEY when set, else LOOPCTL_API_KEY.
  *   - `story_stage` is a read and takes whatever key the caller has.
  *
  * SINGLE SOURCE OF TRUTH: `index.js` injects `apiCall`, and the unit suite runs this code
@@ -29,14 +37,88 @@ const MISSING_USER_KEY =
   "LOOPCTL_USER_KEY is required: this verb claims a story and mints a custody dispatch, " +
   "which only an unlineaged user key may do.";
 
+const MISSING_ORCH_KEY =
+  "No API key is configured. Set LOOPCTL_ORCH_KEY to an orchestrator-role key (or " +
+  "LOOPCTL_API_KEY to one). Force-unclaim is gated `exact_role: :orchestrator`, so a user or " +
+  "superadmin key is 403'd there like any other non-member: a higher-privileged key is not a " +
+  "way past it.";
+
 function refuse(body) {
   return { error: true, status: 0, body };
 }
 
+/**
+ * A client-side shape check on the ids that go into a URL PATH: `story_id` and `runner_id`.
+ *
+ * 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
+ * `with` — before the caller is resolved, before anything is minted and before the claim — so a
+ * malformed one answers `422 invalid_payload` with `details: ["dispatch_id: must be a UUID"]`
+ * (`lib/loopctl_web/controllers/dispatch_placement_controller.ex:321-326`). That names the
+ * parameter and the shape, costs nothing on the server, and is the opposite of the ambiguity
+ * below. There is nothing here for a client check to disambiguate. An earlier draft of this
+ * comment said the check covered "every id these verbs take"; it never did.
+ *
+ * WHY THE PATH IDS DO NEED IT — stated correctly, since an earlier draft of this comment said a
+ * malformed id made the server "500", and it does not. loopctl has a deliberate backstop:
+ * `defimpl Plug.Exception, for: Ecto.Query.CastError` maps it to 404
+ * (`lib/loopctl_web/plugs/cast_error_handler.ex:32-35` — the file also carries an
+ * `Ecto.CastError` impl at `:27-30` and an `Ecto.ChangeError` impl at `:37-42`; the query path
+ * below raises the `Ecto.Query.CastError` one), pinned by
+ * `test/loopctl_web/plugs/cast_error_handler_test.exs:9-12`. What the caller actually gets is
+ * `{"error": {"status": 404, "message": "Not found"}}` — the generic body
+ * `LoopctlWeb.ErrorJSON.render("404.json", …)` emits
+ * (`lib/loopctl_web/controllers/error_json.ex:13-15`, wired by `config/config.exs:344-347`).
+ *
+ * That 404 is the problem, not a 500. It is BYTE-IDENTICAL to the 404 for a perfectly
+ * well-formed id that names no story — `FallbackController` answers `{:error, :not_found}` with
+ * the same `%{error: %{status: 404, message: "Not found"}}`
+ * (`lib/loopctl_web/fallback_controller.ex:74-78`) — so it cannot tell an operator which
+ * of the two happened, and the two have opposite remedies: re-read the argument you passed, or
+ * go find the right story. The check here can tell them apart, and does it without a round trip.
+ *
+ * SCOPE OF THAT TRACE. The path read end to end is force-unclaim:
+ * `Progress.force_unclaim_story/3` reaches `lock_story/2` (`lib/loopctl/progress.ex:3467-3470`),
+ * which puts `story_id` straight into a `where` against a `:binary_id` column with no cast. The
+ * other verbs are NOT claimed to reach that same code. They do not need to: a shape check is
+ * worth its line on any argument that is interpolated into a URL path and must be a UUID,
+ * whatever the server would do with a value that is not one. `place_dispatch`'s `story_id` is
+ * the one exception in the other direction — it travels in the body, like `dispatch_id` — and it
+ * is checked because `story_id` is a PATH id in the three sibling verbs and `uuid()` is one
+ * shared check: giving the same parameter two different refusals depending on which verb took it
+ * is worse than checking it once too often.
+ *
+ * THE REFUSAL CARRIES `status: 0`, NOT 404, and that is deliberate. Every local refusal in this
+ * client uses it — `refuse()` below, `apiCall`'s missing-key branch and its network/timeout
+ * branches (`index.js`) — and it means ONE thing: no request was sent, so no server said
+ * anything. The whole result object is JSON-stringified into the tool output (`toContent`,
+ * `index.js`), so a reader sees that 0. Stamping 404 on it instead would make a local refusal
+ * indistinguishable from the server's answer, which is precisely the ambiguity this check
+ * exists to remove. A caller branching on the status therefore sees `0` where it previously saw
+ * `404`; that is a shape change and the 2.97.0 CHANGELOG entry says so.
+ *
+ * The refusal names the SHAPE and never echoes the value. A malformed id is frequently a
+ * token, a path or a pasted line that landed in the wrong argument, and a tool result goes
+ * into the transcript.
+ */
+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) {
-  return typeof value === "string" && value.trim() !== ""
-    ? null
-    : refuse(`\`${field}\` is required.`);
+  if (typeof value !== "string" || value.trim() === "") {
+    return refuse(`\`${field}\` is required.`);
+  }
+
+  if (!UUID_RE.test(value)) {
+    return refuse(
+      `\`${field}\` must be a UUID (8-4-4-4 hex digits then 12, lowercase or upper). ` +
+        `Got a ${value.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 null;
 }
 
 export function placementPath(runnerId) {
@@ -51,6 +133,11 @@ export function resolvePath(storyId) {
   return `/api/v1/stories/${encodeURIComponent(storyId)}/stage/resolve`;
 }
 
+/** Note the HYPHEN: the route is `force-unclaim`, not `force_unclaim`. */
+export function forceUnclaimPath(storyId) {
+  return `/api/v1/stories/${encodeURIComponent(storyId)}/force-unclaim`;
+}
+
 /**
  * `POST /api/v1/runners/:runner_id/dispatches`: claim a queued story and push it to a runner.
  *
@@ -142,3 +229,70 @@ export async function resolveEscalation({ story_id, to, reason } = {}, { userKey
 
   return apiCall("POST", resolvePath(story_id), body);
 }
+
+/**
+ * `POST /api/v1/stories/:id/force-unclaim`: take a story back off the agent holding it.
+ *
+ * TWO things happen. `force_unclaim_story/3` resets `agent_status` to `pending` and clears
+ * `assigned_agent_id` (`release_claim_changes/1`, `progress.ex:1438`); then, in the SAME
+ * transaction, `Stages.follow_release/5` makes the delivery stage row follow the release —
+ * from any stage a claim holds (`claimed`, `worktree`, `implementing`, `reviewing`, `pr_open`,
+ * `ci`) back to `queued`, rebound to the new claim epoch.
+ *
+ * ## IT FREES THE STAGE. IT DOES NOT MAKE THE STORY PLACEABLE.
+ *
+ * This comment used to say the second half was "what makes the story PLACEABLE again", and
+ * that is false. `Placement.claimable/2` (`placement.ex:482-490`) wants `agent_status ==
+ * :contracted` AND stage `queued`; the release leaves the story at `:pending`, and
+ * `@valid_transitions` (`progress.ex:3480`) has `pending: :contracted` and nothing else — so
+ * `place_dispatch` run straight afterwards answers the IDENTICAL 409 `invalid_transition`.
+ *
+ * The remedy is THREE CALLS, in this order, and the tool descriptions say so:
+ * `force_unclaim_story`, then `contract_story`, then `place_dispatch`. (An earlier draft called
+ * it "two steps" and then named three, which is worse than saying nothing: an operator counting
+ * steps runs two of the three and takes the 409 this copy exists to prevent.)
+ * (`resolve_escalation` is the one that does both for you: `Escalations.prepare_story/5`
+ * releases AND re-contracts on the `queued` route, `escalations.ex:335-342`.)
+ *
+ * ## WHEN A STORY IS ACTUALLY PARKED
+ *
+ * Not on an ordinary refusal — that path self-heals. `Placement.place/4` answers a
+ * `Runners.dispatch/3` refusal INLINE with `undo_claim/5` (`placement.ex:562`, `:706-711`),
+ * which releases the claim through this same function, unrecords the session dispatch and
+ * revokes it. If that release itself fails, the claim lease is a further backstop:
+ * `Progress.reclaim_expired_claim/3` (`progress.ex:1612`) releases over `:runner_lost` and
+ * requeues the stage, swept by `ReclaimExpiredClaimsWorker` every five minutes once
+ * `claimed_until` has passed.
+ *
+ * So a story sitting at `claimed` with nobody on it is the RESIDUE OF A FAILED COMPENSATION,
+ * not what a refusal normally leaves. Reach for this tool to get the story back now instead of
+ * at lease expiry, or when both of those have left it held.
+ *
+ * No request body — the story is named in the path.
+ *
+ * ORCHESTRATOR ROLE, and exactly that: the action is `exact_role: :orchestrator`
+ * (`story_verification_controller.ex:29-30`), so a user or superadmin key is refused —
+ * `RequireRole`'s exact-role clause tests `api_key.role == exact_role`
+ * (`require_role.ex:65-75`).
+ *
+ * WHICH ENV VAR supplies that key is `index.js`'s call, made in `lib/custody-key.js`:
+ * LOOPCTL_ORCH_KEY is sent EXACTLY when it is set, so `resolveKey` cannot discard an
+ * operator's deliberate choice in favour of a global LOOPCTL_API_KEY; when it is not set, the
+ * global key still goes, because an orchestrator-role LOOPCTL_API_KEY was a working and
+ * documented configuration before 2.97.0. The refusal below fires only when NEITHER is set.
+ *
+ * NOT because the 403 would be confusing. An earlier draft of this paragraph said a wrong-role
+ * global key "would produce a 403 that reads like the story being unclaimable rather than the
+ * key being wrong". That is false: `RequireRole` is mounted FIRST and halts with 403,
+ * `code: "insufficient_role"`, `required_roles: ["orchestrator"]` and "This endpoint requires
+ * the orchestrator role" (`require_role.ex:112-128`), so the request never reaches the
+ * controller and never reaches the custody 409s in `Progress`. The role error names the role.
+ */
+export async function forceUnclaimStory({ story_id } = {}, { orchKey, apiCall } = {}) {
+  if (!orchKey) return refuse(MISSING_ORCH_KEY);
+
+  const bad = uuid(story_id, "story_id");
+  if (bad) return bad;
+
+  return apiCall("POST", forceUnclaimPath(story_id), null);
+}

package/lib/handoff.js

@@ -19,9 +19,17 @@
  * lib/http-helpers.js). The three HTTP calls are INJECTED (`deps`), so every branch
  * below is testable with fakes and no network.
  *
- * NEVER attempts `create_project`. A work project is human-anchor-gated by design
- * (#505); trying it first is exactly the dead-end #517 hit, and its 403 reads as a wall
- * rather than a redirect.
+ * NEVER attempts `create_project`. A work project is human-anchor-gated by design, so on an
+ * agent-rooted tenant it cannot succeed and the attempt is a wasted round trip — that is the
+ * dead end #517 hit. NOT because the 403 is unhelpful: an earlier draft of this comment said
+ * it "reads as a wall rather than a redirect", and #505 is precisely what stopped that being
+ * true. `ProjectController` mounts `RequireHumanAnchor` on `:create` with an `alternative:`
+ * naming `create_kb_scope` (`lib/loopctl_web/controllers/project_controller.ex:46-58`), which
+ * the plug renders as `remediation.agent_native_alternative`
+ * (`lib/loopctl_web/plugs/require_human_anchor.ex:166-169`), and it mounts that tier gate
+ * BEFORE `RequireRole` (`:62`) so an agent-role key reads THAT 403 rather than
+ * `insufficient_role`. The 403 points at the kb scope. This code goes straight there because
+ * the round trip buys nothing, not because the answer would confuse anyone.
  */
 
 export const HANDOFF_KEY_PREFIX = "handoff:";

package/package.json

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