loopctl-mcp-server 2.108.0 → 2.111.0

package/README.md

@@ -201,7 +201,7 @@ tool parameter.
 | `create_project` | Create a new **work** project (epics/stories/custody). Requires orchestrator+ **and** a `human_anchored` tenant; an agent-rooted tenant gets `403 custody_tier_required` and should use `create_kb_scope`. |
 | `delete_project` | **Requires `LOOPCTL_USER_KEY`.** Delete a project and all of its dependent resources (epics, stories, audit entries). Irreversible — orchestrator role is not sufficient. |
 | `get_progress` | Get progress summary for a project, including story counts by status. Pass `include_cost=true` for cost data. |
-| `import_stories` | Import stories into a project from a structured payload (Epic 12 import format). Pass `merge: true` to add stories to epics that already exist (otherwise duplicates return 409). For large payloads, use `payload_path` to read JSON from disk instead of passing it inline. |
+| `import_stories` | Import stories into a project from a structured payload (Epic 12 import format). Pass `merge: true` to add stories to epics that already exist (otherwise duplicates return 409). For large payloads, use `payload_path` to read JSON from disk instead of passing it inline. With `merge: true`, `report_orphans: true` adds `stories_orphaned` (the project's stories the payload does not mention; nothing is detached) — a signal only on a FULL round-trip of an export; without it the key is absent (#880). |
 
 ### KB Scope Tools (agent key)
 
@@ -243,6 +243,13 @@ Epic 39 Repo Coordination Bus — a lightweight, tenant-isolated channel for age
 | `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. |
+| `list_epics` | **List a project's epics** (`GET /api/v1/projects/:project_id/epics`, loopctl #876): each epic's `id`, `number`, `title`, `description`, `phase`, `position`, `metadata`, `story_count` and `completion_percentage`, paginated, optionally filtered by `phase`. The way to learn an epic id, e.g. an intake source's `target_epic_id`. Any key. |
+| `create_epic` | **Create an epic** in a work project (`POST /api/v1/projects/:project_id/epics`) and return it with its `id`. `number` (fixed for good) and `title` required; `description`, `phase`, `position`, `metadata` optional. `LOOPCTL_ORCH_KEY`, or `LOOPCTL_USER_KEY` (orchestrator or above; sent verbatim when set) on a human-anchored tenant; 403 otherwise, 404 for a project outside your tenant, 422 for a kb scope or an invalid field. |
+| `get_epic` | **Read one epic** with its stories (`GET /api/v1/epics/:id`). Any key; 404 outside your tenant. |
+| `update_epic` | **Correct an epic** (`PATCH /api/v1/epics/:id`): `title`, `description`, `phase`, `position`, `metadata`; `number` is fixed. Absent and null fields are dropped by the endpoint, so a null and a call naming no field are refused locally (an empty string is what clears `description` or `phase`), and **`metadata` REPLACES the stored map whole** — read it first. `LOOPCTL_ORCH_KEY` on a human-anchored tenant. |
+| `delete_epic` | **Delete an epic and every story in it** (`DELETE /api/v1/epics/:id`) — irreversible, the delete cascades. 204 with no body. `LOOPCTL_USER_KEY` (user or above; sent verbatim when set, else the default key) on a human-anchored tenant. 422 when an active intake source targets the epic (revoke it first), and 422 when a dispatch, capability token or verification run references any story in it (those do not cascade). |
+| `delete_story` | **Delete one story** (`DELETE /api/v1/stories/:id`, loopctl #876) — irreversible. 204 with no body. `LOOPCTL_USER_KEY` (sent verbatim when set, else the default key) on a human-anchored tenant. 422 when a dispatch, capability token or verification run references the story (those do not cascade); its change-thread ledger outlives it. |
+| `epic_progress` | **An epic's progress** (`GET /api/v1/epics/:id/progress`): its stories counted by `agent_status` and `verified_status`. Any key. |
 | `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`. |
 
@@ -520,9 +527,10 @@ The order to wire it up, the stage machine these tools move a story through, and
 | `thread_get` | **Read a story's change thread** (`GET /api/v1/stories/:id/thread`, any role): its latest page of checkpoints (`checkpoints_truncated` is true when older ones exist), and its entries in `seq` order, paged with `after_seq` / `limit` (the response's `next_after_seq` is the next page's `after_seq`). Every entry body is untrusted text (`body_untrusted: true`). |
 | `thread_checkpoint` | **Record a checkpoint on the story you hold** (`POST /api/v1/stories/:id/thread/checkpoints`): a pushed commit plus your reasoning in `note`, sent on the key `claim_story` claims with (`LOOPCTL_API_KEY` when set, else `LOOPCTL_AGENT_KEY`). Refusals: 409 `not_claimant`; 409 `stale_claim_epoch` or `claim_not_live` (your claim no longer accepts work: it ended, its lease lapsed, you requested review or reported it); 409 `checkpoint_conflict` (recorded under your claim with another tree or note); 422 for a malformed sha, a commit and tree of different object formats, an empty or oversized note (bytes), or a note carrying a credential (`secret_blocked`). Idempotent on (`commit_sha`, `claim_epoch`). Required: `story_id`, `claim_epoch`, `commit_sha`, `tree_sha`. |
 | `thread_entry` | **Write a message on a story's thread** (`POST /api/v1/stories/:id/thread/entries`): kind `message`, from any principal, optionally naming a `checkpoint_id` of this story. Findings and verdicts come over the runner socket from a review dispatch, fixes through `thread_fix`, and review requests by the request-review flow; all are refused here. A credential in the body or key is 422 `secret_blocked`. Idempotent per author on `idempotency_key` for the same write; a different entry on the same key is 409 `idempotency_key_reused`, and keys starting `loopctl:` are reserved. `principal` picks the key: agent (default, the key `claim_story` uses), orchestrator or user. |
-| `thread_request_review` | **Request a review of a story's thread** (`POST /api/v1/stories/:id/thread/reviews`, `LOOPCTL_ORCH_KEY`, or `LOOPCTL_USER_KEY` with `principal: user`): loopctl places it on `runner_id` as a runner dispatch of kind `review` (the runner must declare `review`), for the next round, on the story's latest checkpoint of the current claim. It claims nothing and returns no credential; the review's findings and verdict arrive over that runner's socket. Rounds are counted per claim. Round 3 only when a material round-2 finding names a checkpoint carrying a round-1 fix recorded before round 2 was placed; never round 4. Idempotent on `dispatch_id`. Refusals: 403 for an agent key; 409 `no_checkpoint`, `review_claim_ended`, `review_ceiling_reached`, `reviewer_not_separate`, `implementer_dispatch_required`, `dispatch_id_conflict`, `review_dispatch_refused` (the runner refused or superseded that review: place a new one with a new `dispatch_id`) and the push's own (`runner_not_connected`, `kind_not_supported`, `budget_unset`, ...); 422 `invalid_uuid` for a malformed `runner_id` or `dispatch_id`; 429 at capacity; 503 `tenant_halted`. Required: `story_id`, `runner_id`. |
+| `thread_request_review` | **Request a review of a story's thread** (`POST /api/v1/stories/:id/thread/reviews`, `LOOPCTL_ORCH_KEY`, or `LOOPCTL_USER_KEY` with `principal: user`): loopctl places it on `runner_id` as a runner dispatch of kind `review` (the runner must declare `review`), for the next round, on the story's latest checkpoint of the current claim. It claims nothing and returns no credential; the review's findings and verdict arrive over that runner's socket. Rounds are counted per claim. Round 3 only when a material round-2 finding names a checkpoint carrying a round-1 fix recorded before round 2 was placed; never round 4. Idempotent on `dispatch_id`. Refusals: 403 for an agent key; 409 `no_checkpoint`, `review_claim_ended`, `review_ceiling_reached`, `reviewer_not_separate`, `unresolvable_dispatch_lineage` (the implementer's lineage cannot be read, so no reviewer can be shown separate), `dispatch_id_conflict`, `review_dispatch_refused` (the runner refused or superseded that review: place a new one with a new `dispatch_id`) and the push's own (`runner_not_connected`, `kind_not_supported`, `budget_unset`, ...); 422 `invalid_uuid` for a malformed `runner_id` or `dispatch_id`; 429 at capacity; 503 `tenant_halted`. Required: `story_id`, `runner_id`. |
 | `thread_review_get` | **Read a review's payload** (`GET /api/v1/stories/:id/thread/reviews/:review_id`, any role): the story, the checkpoint it reads with its diff reference, the thread's latest entries, the latest fixes with the findings each answers (`fixes_truncated` when older ones exist), and the rounds. Bodies and locations are untrusted. |
 | `thread_fix` | **Record a fix on the story you hold** (`POST /api/v1/stories/:id/thread/fixes`), on the key `claim_story` claims with: the checkpoint carrying it (one your current claim recorded after every checkpoint its findings were found in) and the findings of completed rounds it answers. Refusals: 409 `not_claimant`, `stale_claim_epoch`, `claim_not_live`, `idempotency_key_reused`; 422 `fix_checkpoint_required`, `fix_checkpoint_not_current_claim`, `fix_checkpoint_not_after_findings`, `finding_ids_required`, `unknown_finding`, `secret_blocked`; 503 `tenant_halted`. |
+| `thread_stage_report` | **Report a stage transition of the story you claimed yourself on a thread-mode repository** (`POST /api/v1/stories/:id/stage/transitions`, US-45.9): an interactive claim of a thread-mode story is a change thread with no runner, so its claimant moves the delivery stage as a runner would (with the checkpoint's `head_sha` only entering `ci`), never into `merged` and never `merge_refused`: loopctl's App makes and records the merge; after it, `merged` -> `deployed` with the `release_id`. The first report (from `claimed`) enters the claim. A resend of a report that already landed answers 200 with `replayed: true`. On the key `claim_story` claims with. Refusals: 404; 409 `not_claimant`, `stale_claim_epoch`, `claim_not_live` (renew the lease with `renew_story_claim` while you work), `not_interactive_thread_claim`, `effect_conflict` (the body names the recorded `head_sha`), `stale_stage` (the body names the story's stage and recorded effects); 422 `invalid_payload`; 503 `busy`. |
 | `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`. **A delivery story then goes to `escalated`, not back to the queue** (loopctl US-44.4): an operator taking a story back is a human decision, so a release that leaves the stage row at `queued` escalates it over `operator_released` in the same transaction, spending no attempt against the retry ceiling — it is not left in the queue behind the human's back. Put it back to work with `resolve_escalation` `to: queued`, which releases (a no-op by then) AND re-contracts. A story with no delivery stage row is simply left `pending`. 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`. Run again on an already-pending story it is still an operator's release: a row stranded behind the story's claim epoch is rebound, an in-flight row is requeued, and a row then at `queued` — including one already sitting there — is escalated over `operator_released`, as on the first run; a row already escalated, or anywhere else at that epoch, is left alone. Every 500 means the whole release rolled back and the story is still claimed: `audit_chain_append_failed` (the escalation's chain entry was refused) is a server-side condition a re-run meets again until an operator acts; `force_unclaim_failed` (the server log names the step) — call it again. A 422 means the release write itself was rejected. No request body. Required: `story_id` (refused locally if it is not a UUID). |
 | `merge_precondition` | **Run the merge gate over a story's real pull request** (`POST /api/v1/stories/:id/merge-precondition`). Both delivery gates run again over the diff that exists, plus custody, the 12-file / 1000-line hard bound, the head-has-not-moved check and the self-deploy exclusion; the story must be at stage `ci`. **Gate A reads what triage persisted, never the caller**: the lens verdicts recorded with the story's most recent triage, or a human's re-queue of a Gate A escalation — `gate_a_inputs` on the answer says which, and `missing` refuses with `gate_a_inputs_missing`. This tool sends no trio. Decisions: `allow` (recorded against the head; the only thing that licenses a merge), `refuse` (the story is escalated before this returns), `already_merged`, `head_moved`, `unevaluated` (503 with `Retry-After`). **Thread mode** (the current claim was placed under a source with `mode: thread` — the mode is bound to the dispatch at placement): no pull request; the gate judges the latest checkpoint recorded under the story's CURRENT claim, on the branch that claim's dispatch ran on, and adds refusals `empty_change`, `checkpoint_tree_mismatch`, `no_checkpoint_recorded` and `claim_ended` (the claim was released after an earlier one recorded checkpoints); the source's runners must be at contract 1.20.0+ sending checkpoint messages, or every story is refused `no_checkpoint_recorded`; the branch is judged first, and a missing branch in a readable repository (`branch_missing`), a head nobody recorded (`branch_head_unrecorded`), an earlier checkpoint (`branch_head_regressed`), or a head the stage row did not record is `head_moved` back to implementing while the claim is LIVE, and a refusal naming `claim_not_live` (escalated) when it is not; an unreadable repository refuses `pull_request_unavailable`; the diff judged is the three-dot diff against the merge base, so a base that moved on is not a refusal, and a checkpoint the base already contains (its branch deleted or not) is `already_merged` only under a recorded allow naming it, otherwise `checkpoint_on_base_without_allow`; a thread loopctl could not read refuses `thread_unreadable`; CI is read by the checkpoint's exact SHA from both the check-runs and the commit-status APIs (only a job of a GitHub Actions workflow run that a push of the thread branch at that commit triggered satisfies a required check, and only by concluding `success` — a skipped job fails; statuses and other check runs are recorded or ignored, never trusted) against the source's `required_checks` — a failed one refuses `required_check_failed`, one still running or not yet reported is `unevaluated` (`required_check_pending` / `required_check_missing`, retry after the answer's `Retry-After`; neither counts toward the unevaluated bound, and past the gate's CI wait limit from the story's entry into `ci` both are refused `required_check_timed_out`; per name the newest run of each workflow counts and every workflow must pass; a checkpoint changing `.github/workflows/` or `.github/actions/` is refused `ci_definition_changed`), a source requiring none refuses `required_checks_unset`, a failed read is `ci_evidence_unavailable`, and `local-gate` is recorded but never counted; the answer's `ci_evidence` is what was read and is copied onto the checkpoint; the answer carries `mode` (bound at placement, `pr` when the claim has no accepted dispatch whatever the source says now, null only on ledger contention) and `base_sha` (that merge base), an allow records it, and the merge executor merges only while the base head still equals it. Requires an orchestrator- or user-ROLE key (`exact_role: [:orchestrator, :user]`, so an agent key is 403'd); `LOOPCTL_ORCH_KEY` is sent when set, else `LOOPCTL_API_KEY`. 403 `custody_tier_required` without a human anchor, 404 for an unknown story, 422 when the story is not at `ci`. Required: `story_id` (refused locally if not a UUID) and `claim_epoch` (a non-negative integer, refused locally otherwise); optional `effect_proof`. |
 | `intake_source_enroll` | **Bind a GitHub repository to a work project and mint its webhook secret** (`POST /api/v1/intake/sources`) — the step that gives the delivery loop an input, and the row `place_dispatch` reads `repo` and `base_branch` from (its 409 `no_intake_source` means this has not been done; 409 `ambiguous_intake_source` means it has been done twice). **The secret is returned ONCE and can never be read again** — the column is encrypted at rest and redacted on the schema, so no other tool carries it and losing it costs a revoke, a re-enrolment and a reconfigured GitHub webhook. **This tool does not return it either:** a tool result lands in the transcript and the audit log, so it is written to the required `secret_file` with mode 0600 (the handling `runner_enroll` gives a runner credential) and the result carries the source row, the `webhook_url` and that path. The path is reserved before the request, so an existing file or an unwritable directory is refused with nothing enrolled, and any outcome that is not a clean creation withholds the response body — an unparsed 2xx body IS the secret. A 2xx carrying the source and the secret but no webhook path is RECOVERED rather than discarded (the path is derived from the source id, flagged `webhook_url_derived`), and an outcome that proves a source id but no usable secret REVOKES that source rather than leaving it holding the repository's unique slot. Then configure GitHub: Payload URL = the returned `webhook_url`, content type `application/json`, Secret = the contents of the file, and the **Issues** event only — `gh api repos/OWNER/REPO/hooks -f name=web -f config[url]=<webhook_url> -f config[content_type]=json -f config[secret]="$(cat <secret_file>)" -f 'events[]=issues'`. Every later delivery failure is the SAME 401 `invalid_signature` — unknown or revoked source, suspended tenant, missing or wrong signature, or a payload whose `repository.full_name` does not match — so the webhook's Recent Deliveries tab cannot tell you which. `base_branch` is set HERE: it defaults to `master` when the body does not name it, so name `main` for a repository created on GitHub since 2020 or every dispatch is cut from a trunk that does not exist. It is not nullable (a dispatch must name a branch), so null or blank is refused rather than falling back to the default, and `intake_source_update` changes it afterwards. Refusals: 403 `api_key_mint_forbidden` if your key was minted by a dispatch (this mints a credential belonging to no lineage, so only an unlineaged operator key may), 403 `custody_tier_required` on an agent-rooted tenant, 422 for a repository that is not `owner/name`, an ACTIVE source already binding it, a project that is missing / archived / not a work project, or a `target_epic_id` outside that project. `mode` picks the merge route: `pr` (the default when omitted) or `thread`, where the merge gate evaluates the story's latest recorded checkpoint instead of a pull request — which needs the source's runners at contract 1.20.0+ sending checkpoint messages, or every story is refused `no_checkpoint_recorded`; any other value, null included, is refused. The mode is bound to each implement dispatch when it is placed, so it decides only what stories placed afterwards get; a change is always allowed. A `thread` source must also name `required_checks` (422 otherwise): the CI checks the merge gate requires on a checkpoint's exact commit, GitHub Actions check-run names, bounded in number and length by the server; `local-gate` is refused because whoever pushed posts it. Required: `repo_full_name`, `project_id`, `secret_file`. Optional: `base_branch`, `mode`, `required_checks`, and `target_epic_id` — **omitting the epic is not a neutral default**: with no epic every triaged report is escalated to a human and every record stays `pending_triage` until `intake_source_update` names one. Requires `LOOPCTL_USER_KEY`. |

package/index.js

@@ -32,6 +32,9 @@ import {
   buildCorpusCreateBody,
   buildCorpusIndexBody,
   buildCorpusSearchBody,
+  importPath,
+  importPayloadRefusal,
+  importRefusal,
 } from "./lib/http-helpers.js";
 import {
   createWitnessClient,
@@ -53,6 +56,7 @@ import {
   recordCheckpoint as recordCheckpointRequest,
   recordEntry as recordEntryRequest,
   recordFix as recordFixRequest,
+  reportStage as reportStageRequest,
   requestReview as requestReviewRequest,
 } from "./lib/threads.js";
 import {
@@ -62,7 +66,10 @@ import {
   resolveEscalation as resolveEscalationRequest,
   storyStage as storyStageRequest,
 } from "./lib/delivery-loop.js";
-import { updateStory as updateStoryRequest } from "./lib/story-update.js";
+import {
+  deleteStory as deleteStoryRequest,
+  updateStory as updateStoryRequest,
+} from "./lib/story-update.js";
 import {
   enrollIntakeSource,
   listIntakeSources,
@@ -71,6 +78,16 @@ import {
 } from "./lib/intake-sources.js";
 import { mcpVersion as mcpVersionRequest, packageVersion } from "./lib/mcp-version.js";
 import { revokeDispatch as revokeDispatchRequest } from "./lib/dispatch-revoke.js";
+import {
+  createEpic as createEpicRequest,
+  deleteEpic as deleteEpicRequest,
+  deleteKeyHint,
+  epicWriteKeyHint,
+  epicProgress as epicProgressRequest,
+  getEpic as getEpicRequest,
+  listEpics as listEpicsRequest,
+  updateEpic as updateEpicRequest,
+} from "./lib/epics.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).
@@ -189,7 +206,10 @@ async function apiCall(
   //     `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
+  //     principal. `grep -n 'exactKey: true' index.js` is the current list, and it also
+  //     finds `pinnedApiCall`, the epic and story writes' CONDITIONAL pin, which falls back
+  //     to the default key when its variable is unset and is described where it is defined.
+  //     None of the unconditional family
   //     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`)
@@ -1008,15 +1028,25 @@ async function createStory({ project_id, epic_number, epic_id, story }) {
   return toContent(result);
 }
 
-async function importStories({ project_id, payload, payload_path, merge }) {
+async function importStories({ project_id, payload, payload_path, merge, report_orphans }) {
+  // The cheap argument check first, before a payload file is read (#880).
+  const refused = importRefusal({ merge, report_orphans });
+  if (refused) return toContent({ error: true, status: 0, body: refused });
+
   const effectivePayload = await resolvePayload(payload, payload_path);
   if (effectivePayload && effectivePayload.error) {
     return toContent(effectivePayload);
   }
-  const query = merge ? "?merge=true" : "";
+
+  // The payload is the request BODY, and the server reads flags there too: a payload carrying
+  // its own would override or contradict the arguments, so it is refused, not sent.
+  const payloadRefused = importPayloadRefusal(effectivePayload);
+  if (payloadRefused) return toContent({ error: true, status: 0, body: payloadRefused });
+
+  // `report_orphans` asks a merge for `stories_orphaned` (#880); without it the key is absent.
   const result = await apiCall(
     "POST",
-    `/api/v1/projects/${project_id}/import${query}`,
+    importPath(project_id, { merge, report_orphans }),
     effectivePayload,
     process.env.LOOPCTL_ORCH_KEY
   );
@@ -1085,6 +1115,61 @@ async function getStory({ story_id }) {
   return toContent(result);
 }
 
+// --- Epics (loopctl #876) ---
+// Reads travel on the default key (any role passes). Create and update go through
+// `orchestratorPinnedApiCall`: the named orchestrator or user key VERBATIM, so a global
+// LOOPCTL_API_KEY of a lesser role cannot displace it, and the global key when neither is set. The deletes go through `userKeyApiCall`, pinned to LOOPCTL_USER_KEY so a
+// global LOOPCTL_API_KEY cannot displace it: they destroy rows. (`delete_project` is not
+// pinned this way.)
+
+// ONE pinning rule for the epic and story writes: the env var `hint()` names is sent VERBATIM
+// when it is set, so a global LOOPCTL_API_KEY of a lesser role cannot displace it, and with none
+// set the default selection (`resolveKey`) applies. Unlike the unconditional user-key family
+// described above `apiCall`, these fall back rather than refuse: their gates use the role
+// hierarchy (`role:`, never `exact_role:`), so a sufficient global key passes.
+function pinnedApiCall(hint) {
+  return (method, path, body) => {
+    const keyHint = hint();
+
+    return keyHint
+      ? apiCall(method, path, body, process.env[keyHint], { exactKey: true, keyHint })
+      : apiCall(method, path, body);
+  };
+}
+
+// Create and update: LOOPCTL_ORCH_KEY, else LOOPCTL_USER_KEY (`epicWriteKeyHint`).
+const orchestratorPinnedApiCall = pinnedApiCall(epicWriteKeyHint);
+// The deletes: LOOPCTL_USER_KEY (`deleteKeyHint`).
+const userKeyApiCall = pinnedApiCall(deleteKeyHint);
+
+async function listEpics(args) {
+  return toContent(await listEpicsRequest(args, { apiCall }));
+}
+
+async function getEpic(args) {
+  return toContent(await getEpicRequest(args, { apiCall }));
+}
+
+async function epicProgress(args) {
+  return toContent(await epicProgressRequest(args, { apiCall }));
+}
+
+async function createEpic(args) {
+  return toContent(await createEpicRequest(args, { apiCall: orchestratorPinnedApiCall }));
+}
+
+async function updateEpic(args) {
+  return toContent(await updateEpicRequest(args, { apiCall: orchestratorPinnedApiCall }));
+}
+
+async function deleteEpic(args) {
+  return toContent(await deleteEpicRequest(args, { apiCall: userKeyApiCall }));
+}
+
+async function deleteStory(args) {
+  return toContent(await deleteStoryRequest(args, { apiCall: userKeyApiCall }));
+}
+
 // --- Workflow Tools (agent key) ---
 
 async function contractStory({ story_id, story_title, ac_count }) {
@@ -1257,6 +1342,10 @@ async function threadFix(args) {
   return toContent(await recordFixRequest(args, { apiCall: threadApiCall }));
 }
 
+async function threadStageReport(args) {
+  return toContent(await reportStageRequest(args, { apiCall: threadApiCall }));
+}
+
 async function startStory({ story_id, capability }) {
   // Cache first, then DELIVERY of the token claim already minted, then recovery
   // (which mints a fresh one). Delivery also covers a legacy env-var key, whose
@@ -4189,6 +4278,140 @@ const TOOLS = [
       required: ["story"],
     },
   },
+  {
+    name: "list_epics",
+    description:
+      "LIST A PROJECT'S EPICS (GET /api/v1/projects/:project_id/epics, loopctl #876): each " +
+      "epic's `id`, `number`, `title`, `description`, `phase`, `position`, `metadata`, " +
+      "`story_count` and `completion_percentage`, paginated (`page`, " +
+      "`page_size`), optionally filtered by `phase`. The way to learn an epic's id, e.g. the " +
+      "`target_epic_id` an intake source needs. Any key. Refusals: 404 for a project not in " +
+      "your tenant; a malformed `project_id` is refused locally.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        project_id: { type: "string", description: "The project's UUID." },
+        page: { type: "integer", description: "Page number (default 1)." },
+        page_size: { type: "integer", description: "Items per page." },
+        phase: { type: "string", description: "Only epics in this phase." },
+      },
+      required: ["project_id"],
+    },
+  },
+  {
+    name: "create_epic",
+    description:
+      "CREATE AN EPIC in a work project (POST /api/v1/projects/:project_id/epics, loopctl " +
+      "#876) and return it, `id` included. `number` (an integer, fixed for good) and `title` " +
+      "are required; `description`, `phase`, `position` (default 0) and `metadata` are " +
+      "optional. Needs an orchestrator-or-above key on a human-anchored tenant: " +
+      "LOOPCTL_ORCH_KEY, else LOOPCTL_USER_KEY, sent verbatim, else the default key. " +
+      "Refusals: 403 for an agent key or a tenant that is not human-anchored, 404 for a " +
+      "project not in your tenant, 422 for a kb scope (epics live in work projects) or a " +
+      "duplicate or invalid field.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        project_id: { type: "string", description: "The work project's UUID." },
+        number: {
+          type: "integer",
+          minimum: 1,
+          description: "The epic's number, at least 1; cannot change later.",
+        },
+        title: { type: "string", description: "The epic's title." },
+        description: { type: "string", description: "Optional description." },
+        phase: { type: "string", description: "Optional phase." },
+        position: { type: "integer", description: "Optional ordering position (default 0)." },
+        metadata: { type: "object", description: "Optional metadata map." },
+      },
+      required: ["project_id", "number", "title"],
+    },
+  },
+  {
+    name: "get_epic",
+    description:
+      "READ ONE EPIC with its stories (GET /api/v1/epics/:id, loopctl #876). Any key. " +
+      "Refusals: 404 for an epic not in your tenant; a malformed `epic_id` is refused locally.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        epic_id: { type: "string", description: "The epic's UUID (from list_epics or create_epic)." },
+      },
+      required: ["epic_id"],
+    },
+  },
+  {
+    name: "update_epic",
+    description:
+      "CORRECT AN EPIC (PATCH /api/v1/epics/:id, loopctl #876): any of `title`, " +
+      "`description`, `phase`, `position`, `metadata`. `number` cannot change. The endpoint " +
+      "DROPS absent and null fields, so a null and a call naming no field are refused " +
+      "locally; send an EMPTY STRING to clear `description` or `phase` (a blank `title` is a " +
+      "422). `metadata` is REPLACED WHOLE, never merged: read the epic first " +
+      "(get_epic) and send the whole map. Needs an orchestrator-or-above key on a " +
+      "human-anchored tenant: LOOPCTL_ORCH_KEY, else LOOPCTL_USER_KEY, else the default key. Refusals: 403, 404, 422 for an invalid field.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        epic_id: { type: "string", description: "The epic's UUID (from list_epics or create_epic)." },
+        title: { type: "string" },
+        description: { type: "string" },
+        phase: { type: "string" },
+        position: { type: "integer" },
+        metadata: { type: "object", description: "Replaces the stored map whole." },
+      },
+      required: ["epic_id"],
+    },
+  },
+  {
+    name: "delete_epic",
+    description:
+      "DELETE AN EPIC AND EVERY STORY IN IT (DELETE /api/v1/epics/:id, loopctl #876). " +
+      "IRREVERSIBLE: the delete cascades to the epic's stories. Answers 204 with no body. " +
+      "Needs a user-or-above key on a human-anchored tenant: LOOPCTL_USER_KEY, sent verbatim " +
+      "when set (a global LOOPCTL_API_KEY never displaces it), else the default key. " +
+      "Refusals: 403 for a lesser key or a tenant that is not " +
+      "human-anchored, 404 for an epic not in your tenant, 422 when an active intake source " +
+      "targets the epic (revoke it first: intake_source_revoke), 422 when a dispatch, " +
+      "capability token or verification run references any story in it (those do not " +
+      "cascade). A story's change-thread ledger is NOT deleted with it: it outlives the story.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        epic_id: { type: "string", description: "The epic's UUID (from list_epics or create_epic)." },
+      },
+      required: ["epic_id"],
+    },
+  },
+  {
+    name: "delete_story",
+    description:
+      "DELETE ONE STORY (DELETE /api/v1/stories/:id, loopctl #876). IRREVERSIBLE. Answers 204 " +
+      "with no body. Needs a user-or-above key on a human-anchored tenant: LOOPCTL_USER_KEY " +
+      "verbatim when set, else the default key. Refusals: 403 for a lesser key, 404 for a story not in your tenant, 422 when " +
+      "a dispatch, capability token or verification run references the story (those do not " +
+      "cascade). Its change-thread ledger outlives it. A malformed `story_id` is refused " +
+      "locally.",
+    inputSchema: {
+      type: "object",
+      properties: { story_id: { type: "string", description: "The story's UUID." } },
+      required: ["story_id"],
+    },
+  },
+  {
+    name: "epic_progress",
+    description:
+      "AN EPIC'S PROGRESS (GET /api/v1/epics/:id/progress, loopctl #876): its stories " +
+      "counted by `agent_status` and by `verified_status`. Any key. Refusals: 404 for an " +
+      "epic not in your tenant; a malformed `epic_id` is refused locally.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        epic_id: { type: "string", description: "The epic's UUID (from list_epics or create_epic)." },
+      },
+      required: ["epic_id"],
+    },
+  },
   {
     name: "update_story",
     description:
@@ -4257,6 +4480,9 @@ const TOOLS = [
     description:
       "Import stories into a project from a structured payload (Epic 12 import format). " +
       "Pass `merge: true` to add stories to epics that already exist (otherwise duplicates return 409). " +
+      "A merge answers counts; `stories_orphaned` (the project's stories the payload does not " +
+      "mention; nothing is detached) is in the response ONLY with `report_orphans: true`, " +
+      "which is a signal only on a full round-trip of an export (#880). " +
       "For large payloads, use `payload_path` to read JSON from disk instead of passing it inline.",
     inputSchema: {
       type: "object",
@@ -4282,6 +4508,15 @@ const TOOLS = [
             "When false or omitted, duplicates return 409.",
           default: false,
         },
+        report_orphans: {
+          type: "boolean",
+          description:
+            "Merge only. When true the response carries `stories_orphaned`: the project's " +
+            "stories this payload does not mention. Nothing is detached either way. It is a " +
+            "signal only when the payload is a FULL round-trip of an export; on a partial " +
+            "merge every unmentioned story is listed. When false or omitted the key is absent.",
+          default: false,
+        },
       },
       required: ["project_id"],
     },
@@ -4429,7 +4664,13 @@ const TOOLS = [
     name: "claim_story",
     description:
       "Agent claims a contracted story. Uses pessimistic locking to prevent double-claims. " +
-      "Transitions contracted -> assigned. Uses the AGENT key. On a loopctl with claim leases " +
+      "Transitions contracted -> assigned. Uses the AGENT key. On a THREAD-mode repository " +
+      "(its intake source's mode) a claim of a story queued by triage is an interactive " +
+      "change thread (US-45.9): push checkpoints to the loop/ branch and record them with " +
+      "thread_checkpoint, move the story's stage with thread_stage_report, get a runner " +
+      "review with thread_request_review, and loopctl's App merges the checkpoint the gate " +
+      "allows. The mode, base branch and branch are bound when you claim, and the result's " +
+      "`route` names them: push your checkpoints to `route.branch`. On a loopctl with claim leases " +
       "the result leads with the claim's claim_epoch and claimed_until: keep the epoch, and " +
       "renew with renew_story_claim before claimed_until (default lease 24 hours) or the story " +
       "is released back to pending under you. Refused 409 story_held when the story's " +
@@ -4454,7 +4695,9 @@ const TOOLS = [
     description:
       "Renew your claim's lease (POST /api/v1/stories/:id/renew-claim): claimed_until becomes " +
       "now plus the lease length (default 24 hours), measured from NOW. Call it well inside the " +
-      "lease on any story you hold longer than it. A DRIVER-PLACED claim (one a placement took " +
+      "lease on any story you hold longer than it. An interactive thread claim (US-45.9) has no " +
+      "runner keeping it alive: when its lease lapses its checkpoints and stage reports are " +
+      "refused and the thread ends with the claim. A DRIVER-PLACED claim (one a placement took " +
       "for a runner dispatch) is CAPPED AT ITS DISPATCH DEADLINE (claim_lease_cap: " +
       "placed_at + wall_clock_seconds + DISPATCH_LEASE_GRACE_SECONDS at the claim, which is " +
       "the dispatch's deadline_at; moved forward to a resume's time or the runner's " +
@@ -8281,6 +8524,50 @@ const TOOLS = [
       required: ["story_id"],
     },
   },
+  {
+    name: "thread_stage_report",
+    description:
+      "REPORT A STAGE TRANSITION of the story you hold, when you claimed it YOURSELF on a " +
+      "thread-mode repository (POST /api/v1/stories/:id/stage/transitions, US-45.9). An " +
+      "interactive claim of a thread-mode story is a change thread with no runner, so you " +
+      "move its delivery stage the way a runner would: `claimed` -> `worktree` " +
+      "-> `implementing` -> `reviewing` -> `pr_open` -> `ci`, passing `head_sha` (the " +
+      "checkpoint you want merged) ONLY when you enter `ci`; `ci_red`, `review_findings` and " +
+      "`base_moved` send it back to `implementing`. Never into `merged` and never " +
+      "`merge_refused`: loopctl's App makes the merge and records it. After it, report " +
+      "`merged` -> `deployed` with the `release_id` once the deploy lands. Your first report " +
+      "(from `claimed`) enters the claim. Travels on the key claim_story claims " +
+      "with. A resend of a report that already landed answers 200 with `replayed: true`. " +
+      "Refusals: 404 (not your tenant's story); 409 `not_claimant`, `stale_claim_epoch`, " +
+      "`claim_not_live` (your lease lapsed, renew it with renew_story_claim while you work, " +
+      "or you requested review), `not_interactive_thread_claim` (a placed claim, whose runner " +
+      "reports for it, or a pr-mode claim), `effect_conflict` (a different `head_sha` is already recorded; the body names it), " +
+      "`stale_stage` (the story is elsewhere; the body " +
+      "names its stage and recorded effects); 422 `invalid_payload` (a transition or effect " +
+      "you may not report); 503 `busy` (retry).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        story_id: { type: "string", description: "The story UUID." },
+        claim_epoch: { type: "integer", description: "The epoch your claim returned." },
+        from: { type: "string", description: "The stage the story is at." },
+        to: { type: "string", description: "The stage to move it to." },
+        edge: {
+          type: "string",
+          description: "Which transition when from -> to has more than one; default `forward`.",
+        },
+        reason: {
+          type: "string",
+          description: "Required entering `escalated` and on `merge_refused`; stored as untrusted text.",
+        },
+        head_sha: {
+          type: "string",
+          description: "The checkpoint commit, full lowercase hex, when entering `ci`.",
+        },
+      },
+      required: ["story_id", "claim_epoch", "from", "to"],
+    },
+  },
   {
     name: "thread_checkpoint",
     description:
@@ -8340,7 +8627,9 @@ const TOOLS = [
       "REQUEST A REVIEW of a story's change thread (POST /api/v1/stories/:id/thread/reviews). " +
       "loopctl places it on `runner_id` as a runner dispatch of kind `review` — the runner " +
       "must DECLARE `review` on join — for the next round, on the story's latest checkpoint " +
-      "of the current claim. It claims nothing and returns NO credential: the review's " +
+      "of the current claim. The claim may be a runner's or one a session made itself " +
+      "(US-45.9); either way the reviewer is the runner's agent, which may not be the claimant " +
+      "or an agent that recorded a checkpoint of the thread. It claims nothing and returns NO credential: the review's " +
       "findings and verdict come back over that runner's socket, never through this tool. " +
       "Rounds are counted per claim (a story claimed again starts at round 1). Round 2 " +
       "always follows round 1; round 3 only when a material round-2 finding names a checkpoint " +
@@ -8351,7 +8640,9 @@ const TOOLS = [
       "with the same one. Refusals: 403 for an agent key; 409 `no_checkpoint`, " +
       "`review_claim_ended` (no live claim to review), `review_ceiling_reached`, `reviewer_not_separate` (the runner's agent is the claimant, " +
       "recorded a checkpoint, or is on the implementer's lineage chain), " +
-      "`implementer_dispatch_required`, `dispatch_id_conflict`, `review_dispatch_refused` " +
+      "`unresolvable_dispatch_lineage` (the implementer's lineage cannot be read, so no " +
+      "reviewer can be shown separate: refused closed), " +
+      "`dispatch_id_conflict`, `review_dispatch_refused` " +
       "(the runner refused or superseded that review: place a new one with a new " +
       "`dispatch_id`), and the push's own " +
       "(`runner_not_connected`, `kind_not_supported`, `budget_unset`, ...); 422 " +
@@ -9600,6 +9891,20 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 
     case "update_story":
       return await updateStory(args);
+    case "list_epics":
+      return await listEpics(args);
+    case "create_epic":
+      return await createEpic(args);
+    case "get_epic":
+      return await getEpic(args);
+    case "update_epic":
+      return await updateEpic(args);
+    case "delete_epic":
+      return await deleteEpic(args);
+    case "delete_story":
+      return await deleteStory(args);
+    case "epic_progress":
+      return await epicProgress(args);
 
     case "import_stories":
       return await importStories(args);
@@ -9937,6 +10242,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     case "thread_fix":
       return await threadFix(args);
 
+    case "thread_stage_report":
+      return await threadStageReport(args);
+
     case "resolve_escalation":
       return await resolveEscalation(args);
 

package/lib/epics.js

@@ -0,0 +1,163 @@
+/**
+ * The epics surface — `list_epics`, `create_epic`, `get_epic`, `update_epic`, `delete_epic`
+ * and `epic_progress` — the MCP half of the `EpicController` routes (loopctl #876).
+ *
+ * WHY IT EXISTS. The routes were served and no tool reached them, so a session could create
+ * an epic through `import_stories` and then not name it: import answers COUNTS
+ * (`epics_created: 1`), never ids. Enrolling an intake source needs a `target_epic_id`, and
+ * the only way to learn one was to create a throwaway story in the epic and read `epic_id`
+ * back off `list_stories`. `import_stories` was not widened to return ids instead: an epic
+ * also has to be listed, read, corrected and measured after it exists, which a create
+ * response cannot do, so the tools cover the whole surface.
+ *
+ * WHAT THE ENDPOINTS ACCEPT, read from `lib/loopctl_web/controllers/epic_controller.ex`:
+ *
+ *   - create casts `number`, `title`, `description`, `phase`, `position` (default 0) and
+ *     `metadata` (default {}); `number` is required and cannot change afterwards.
+ *   - update takes `title`, `description`, `phase`, `position`, `metadata` and DROPS every
+ *     nil, so a null writes nothing, and a request naming none of them is a 200 that changes
+ *     nothing. Both shapes are refused here, as `update_story` refuses them. An empty string
+ *     is what CLEARS `description` or `phase` (a blank `title` is a 422). `metadata` is
+ *     REPLACED whole, never merged.
+ *   - index pages (`page`, `page_size`) and filters by `phase`.
+ *
+ * KEYS, from the controller's plugs: reads are `role: :agent` (any key); create and update
+ * are `role: :orchestrator` with the hierarchy, and human-anchored; delete is `role: :user`,
+ * human-anchored, and CASCADES to the epic's stories — refused 422 when a dispatch, capability
+ * token or verification run references a story in it (those do not cascade) or an active
+ * intake source targets the epic. `delete_story` is `lib/story-update.js`'s.
+ */
+
+import { uuid as uuidRefusal } from "./delivery-loop.js";
+import { namedBody } from "./story-update.js";
+
+const UPDATABLE = ["title", "description", "phase", "position", "metadata"];
+
+function refuse(body) {
+  return { error: true, status: 0, body };
+}
+
+// A malformed id is refused locally rather than sent, through the SAME guard the other tools
+// use (`lib/delivery-loop.js`'s `uuid`), so a bad id reads the same whichever tool it reached.
+function badId(name, value) {
+  return uuidRefusal(value, name);
+}
+
+// Each builder is ONE template literal, which is the shape `test/tool-surface.js` resolves to
+// the route it names: the query string after `/epics` contributes nothing to the route.
+export function projectEpicsPath(projectId, query = {}) {
+  return `/api/v1/projects/${encodeURIComponent(projectId)}/epics${epicsQuery(query)}`;
+}
+
+export function epicPath(epicId) {
+  return `/api/v1/epics/${encodeURIComponent(epicId)}`;
+}
+
+export function epicProgressPath(epicId) {
+  return `/api/v1/epics/${encodeURIComponent(epicId)}/progress`;
+}
+
+function epicsQuery({ page, page_size, phase } = {}) {
+  const params = new URLSearchParams();
+  // `!= null`, not `!== undefined`: a client sending an optional argument as null means
+  // "not named", and `phase=null` would filter on the literal phase "null".
+  if (page != null) params.set("page", String(page));
+  if (page_size != null) params.set("page_size", String(page_size));
+  if (phase != null) params.set("phase", String(phase));
+  const query = params.toString();
+  return query === "" ? "" : `?${query}`;
+}
+
+export async function listEpics({ project_id, page, page_size, phase } = {}, { apiCall } = {}) {
+  const refused = badId("project_id", project_id);
+  if (refused) return refused;
+
+  // A cleared phase is stored as NULL, so `phase=` would filter on the empty string and match
+  // nothing: an empty list that reads as "no epics". Refused rather than answered wrongly.
+  if (phase === "") {
+    return refuse(
+      "`phase` cannot be empty: no filter selects epics without a phase. Leave it out to list " +
+        "every epic.",
+    );
+  }
+
+  return apiCall("GET", projectEpicsPath(project_id, { page, page_size, phase }));
+}
+
+export async function createEpic(
+  { project_id, number, title, description, phase, position, metadata } = {},
+  { apiCall } = {},
+) {
+  const refused = badId("project_id", project_id);
+  if (refused) return refused;
+
+  // An integer, as the input schema declares, and at least 1, which the server requires.
+  if (!Number.isInteger(number) || number < 1) {
+    return refuse("`number` is required and must be an integer of at least 1; it is fixed for good.");
+  }
+
+  if (typeof title !== "string" || title.trim() === "") {
+    return refuse("`title` is required.");
+  }
+
+  const body = { number, title };
+  if (description !== undefined) body.description = description;
+  if (phase !== undefined) body.phase = phase;
+  if (position !== undefined) body.position = position;
+  if (metadata !== undefined) body.metadata = metadata;
+
+  return apiCall("POST", projectEpicsPath(project_id), body);
+}
+
+export async function getEpic({ epic_id } = {}, { apiCall } = {}) {
+  return badId("epic_id", epic_id) ?? apiCall("GET", epicPath(epic_id));
+}
+
+export async function updateEpic(args = {}, { apiCall } = {}) {
+  const refused = badId("epic_id", args.epic_id);
+  if (refused) return refused;
+
+  // A null is refused, as `update_story` refuses it (`namedBody`). An EMPTY string is what
+  // clears a field: it survives the controller's nil filter and the changeset casts it to nil,
+  // so `description: ""` or `phase: ""` erases it (a blank `title` is a 422).
+  const { body, error } = namedBody(
+    args,
+    UPDATABLE,
+    'To clear `description` or `phase`, send an empty string ("").',
+  );
+  if (error) return refuse(error);
+
+  if (Object.keys(body).length === 0) {
+    return refuse(
+      `Name at least one of ${UPDATABLE.join(", ")}: the endpoint drops every absent field, ` +
+        "so a request with none of them answers 200 and changes nothing.",
+    );
+  }
+
+  return apiCall("PATCH", epicPath(args.epic_id), body);
+}
+
+export async function deleteEpic({ epic_id } = {}, { apiCall } = {}) {
+  return badId("epic_id", epic_id) ?? apiCall("DELETE", epicPath(epic_id), null);
+}
+
+export async function epicProgress({ epic_id } = {}, { apiCall } = {}) {
+  return badId("epic_id", epic_id) ?? apiCall("GET", epicProgressPath(epic_id));
+}
+
+// The key an epic WRITE travels on: `role: :orchestrator` WITH the hierarchy
+// (epic_controller.ex), so a user key passes too. The first of LOOPCTL_ORCH_KEY and
+// LOOPCTL_USER_KEY that is set is named, to be sent VERBATIM; `null` when neither is, and the
+// caller's default key selection applies.
+export function epicWriteKeyHint(env = process.env) {
+  if (env.LOOPCTL_ORCH_KEY) return "LOOPCTL_ORCH_KEY";
+  if (env.LOOPCTL_USER_KEY) return "LOOPCTL_USER_KEY";
+  return null;
+}
+
+// The key a DELETE travels on: LOOPCTL_USER_KEY, sent VERBATIM when it is set, so a global
+// LOOPCTL_API_KEY of a lesser role cannot displace it; `null` when it is not, and the caller's
+// default selection applies. `role: :user` WITH the hierarchy, so the global key may well pass.
+export function deleteKeyHint(env = process.env) {
+  return env.LOOPCTL_USER_KEY ? "LOOPCTL_USER_KEY" : null;
+}

package/lib/http-helpers.js

@@ -361,3 +361,63 @@ export function buildCorpusSearchBody({ query, query_vector, lanes, limit } = {}
   if (limit != null) body.limit = limit;
   return body;
 }
+
+// `true`/`false` or their strings, and nothing else (loopctl #880); `undefined` for anything
+// else, which `importRefusal` turns into a refusal before a path is ever built.
+function importFlag(value) {
+  if (value === undefined || value === null || value === false || value === "false") return false;
+  if (value === true || value === "true") return true;
+  return undefined;
+}
+
+/**
+ * Why an `import_stories` call must not be sent, or `null`. `merge` and `report_orphans` take
+ * `true`/`false` (or their strings) and nothing else, as the server does (loopctl #880): a value
+ * that is neither is REFUSED rather than read as off, which would silently run a fresh import
+ * or drop the orphan list a caller asked for; and `report_orphans` without `merge` is refused,
+ * since orphans are a merge's report.
+ *
+ * @param {{ merge?: unknown, report_orphans?: unknown }} [args]
+ * @returns {string | null}
+ */
+export function importRefusal({ merge, report_orphans } = {}) {
+  if (importFlag(merge) === undefined) return "`merge` must be true or false.";
+  if (importFlag(report_orphans) === undefined) return "`report_orphans` must be true or false.";
+  if (importFlag(report_orphans) && !importFlag(merge)) {
+    return "`report_orphans` needs `merge: true`: orphans are a merge's report.";
+  }
+  return null;
+}
+
+/**
+ * Why an `import_stories` payload must not be sent as the body, or `null`: it carries its own
+ * `merge` or `report_orphans`, which the server reads from the body as well (loopctl #880) and
+ * which would override or contradict the tool's arguments. Pass the flags as arguments.
+ *
+ * @param {unknown} payload
+ * @returns {string | null}
+ */
+export function importPayloadRefusal(payload) {
+  if (!payload || typeof payload !== "object") return null;
+  const carried = ["merge", "report_orphans"].filter((key) => key in payload);
+  return carried.length === 0
+    ? null
+    : `The payload carries ${carried.map((k) => `\`${k}\``).join(" and ")}; pass ` +
+        "import flags as the tool's arguments, not inside the payload.";
+}
+
+/**
+ * Path for `import_stories`, for arguments `importRefusal` accepted. ONE template literal, the
+ * shape `test/tool-surface.js` resolves to the route; the id is encoded so it cannot rewrite
+ * the query.
+ *
+ * @param {string} projectId
+ * @param {{ merge?: unknown, report_orphans?: unknown }} [args]
+ * @returns {string}
+ */
+export function importPath(projectId, { merge, report_orphans } = {}) {
+  return `/api/v1/projects/${encodeURIComponent(projectId)}/import${buildQuery([
+    ["merge", importFlag(merge) ? "true" : null],
+    ["report_orphans", importFlag(report_orphans) ? "true" : null],
+  ])}`;
+}

package/lib/story-update.js

@@ -100,16 +100,30 @@ export function storyPath(storyId) {
  * dropped it (`Map.reject`, `story_controller.ex:443`).
  */
 export function updateBody(args = {}) {
+  return namedBody(
+    args,
+    UPDATABLE,
+    "Send the value you want, or leave the field out.",
+  );
+}
+
+/**
+ * The PATCH body of the `fields` a caller named, for an endpoint whose controller DROPS every
+ * nil before the changeset sees it: `undefined` is omitted, `null` refused (it would answer 200
+ * with the field unchanged). Shared by `update_story` and `update_epic` (`lib/epics.js`), so the
+ * two refuse the same shape the same way; `remedy` is the last sentence of the refusal.
+ */
+export function namedBody(args, fields, remedy) {
   const body = {};
 
-  for (const field of UPDATABLE) {
+  for (const field of fields) {
     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.`,
+          `field unchanged. ${remedy}`,
       };
     }
     body[field] = value;
@@ -118,6 +132,14 @@ export function updateBody(args = {}) {
   return { body };
 }
 
+/**
+ * `DELETE /api/v1/stories/:id` — `delete_story`. Refused 404, or 422 when records kept on
+ * purpose (dispatches, capability tokens, verification runs) reference the story.
+ */
+export async function deleteStory({ story_id } = {}, { apiCall } = {}) {
+  return uuidRefusal(story_id, "story_id") ?? apiCall("DELETE", storyPath(story_id), null);
+}
+
 /**
  * `PATCH /api/v1/stories/:id` — correct a filed story's title, description, acceptance
  * criteria, estimate or metadata.

package/lib/threads.js

@@ -109,6 +109,46 @@ export async function recordCheckpoint(
   );
 }
 
+export function stageTransitionsPath(storyId) {
+  return `/api/v1/stories/${encodeURIComponent(storyId)}/stage/transitions`;
+}
+
+/**
+ * `POST /api/v1/stories/:id/stage/transitions` on the key claim_story claimed with (US-45.9):
+ * the claimant of an INTERACTIVE thread claim reports its own story's stage transitions, as a
+ * runner reports a placed claim's.
+ */
+export async function reportStage(
+  { story_id, claim_epoch, from, to, edge, reason, head_sha } = {},
+  { apiCall, env = process.env } = {},
+) {
+  if (!present(story_id)) return missing("story_id");
+  if (!present(from)) return missing("from");
+  if (!present(to)) return missing("to");
+  if (!Number.isInteger(claim_epoch) || claim_epoch < 0) {
+    return {
+      error: true,
+      status: 0,
+      body: "`claim_epoch` is required: the non-negative integer your claim returned.",
+    };
+  }
+
+  return apiCall(
+    "POST",
+    stageTransitionsPath(story_id),
+    compact({
+      claim_epoch,
+      from,
+      to,
+      edge,
+      reason,
+      effects: present(head_sha) ? { head_sha } : undefined,
+    }),
+    env[claimKeyVar(env)],
+    claimKeyVar(env),
+  );
+}
+
 /** `POST /api/v1/stories/:id/thread/entries` on the key `principal` names. */
 export async function recordEntry(
   {

package/package.json

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