loopctl-mcp-server 2.101.0 → 2.104.0

package/index.js

@@ -49,11 +49,18 @@ import { claimLeaseNotice, renewStoryClaim as renewStoryClaimRequest } from "./l
 import { escalateStory as escalateStoryRequest, escalationNotice } from "./lib/escalation.js";
 import {
   forceUnclaimStory as forceUnclaimStoryRequest,
+  mergePrecondition as mergePreconditionRequest,
   placeDispatch as placeDispatchRequest,
   resolveEscalation as resolveEscalationRequest,
   storyStage as storyStageRequest,
 } from "./lib/delivery-loop.js";
 import { updateStory as updateStoryRequest } from "./lib/story-update.js";
+import {
+  enrollIntakeSource,
+  listIntakeSources,
+  revokeIntakeSource,
+  updateIntakeSource,
+} from "./lib/intake-sources.js";
 import { mcpVersion as mcpVersionRequest, packageVersion } from "./lib/mcp-version.js";
 import { revokeDispatch as revokeDispatchRequest } from "./lib/dispatch-revoke.js";
 
@@ -1053,6 +1060,18 @@ async function listReadyStories({ project_id, page, page_size }) {
   return toContentCompact(result);
 }
 
+async function listBlockedStories({ project_id, page, page_size }) {
+  const params = new URLSearchParams();
+  if (project_id != null) params.set("project_id", project_id);
+  if (page != null) params.set("page", String(page));
+  if (page_size != null)
+    params.set("page_size", String(Math.min(page_size, SERVER_MAX_STORY_PAGE_SIZE)));
+
+  const qs = params.toString();
+  const result = await apiCall("GET", `/api/v1/stories/blocked${qs ? `?${qs}` : ""}`);
+  return toContentCompact(result);
+}
+
 async function getStory({ story_id }) {
   const result = await apiCall("GET", `/api/v1/stories/${story_id}`);
   return toContent(result);
@@ -3289,6 +3308,61 @@ async function forceUnclaimStory(args) {
   );
 }
 
+// Epic 44, US-44.1: the merge gate's second run. Same key selection as force-unclaim — the
+// action is `exact_role: [:orchestrator, :user]` and LOOPCTL_ORCH_KEY is pinned when set.
+async function mergePreconditionTool(args) {
+  const orch = orchestratorKeyArgs();
+
+  return toContent(
+    await mergePreconditionRequest(args, {
+      orchKey: orch.resolved,
+      apiCall: (method, path, body) => apiCall(method, path, body, orch.override, orch.options),
+    }),
+  );
+}
+
+// #803/#846: GitHub intake sources — the row that makes a webhook possible, and the binding
+// `place_dispatch` reads `repo` and `base_branch` from. The logic, including how the enrol
+// path keeps the webhook secret out of the tool result, lives in lib/intake-sources.js.
+//
+// THE FACTORY IS DECLARED BELOW THESE FOUR, not above them, and that is load-bearing rather
+// than a style: several sibling guards read a handler's source as the slice from its own
+// `async function` to the NEXT one (`delivery_loop_tools.test.js`, `custody_key_pinning.js`,
+// `mcp_arg_forwarding.js`'s `functionSource`). A plain `function` declaration sitting between
+// two handlers is swallowed by the earlier one's slice — putting `intakeDeps` above
+// `intakeSourceEnroll` made `forceUnclaimStory`'s guard read this factory's
+// `process.env.LOOPCTL_USER_KEY` and correctly fail. Hoisting keeps the call sites valid.
+async function intakeSourceEnroll(args) {
+  return toContent(await enrollIntakeSource(args, intakeDeps()));
+}
+
+async function intakeSourceList(args) {
+  return toContent(await listIntakeSources(args, intakeDeps()));
+}
+
+async function intakeSourceUpdate(args) {
+  return toContent(await updateIntakeSource(args, intakeDeps()));
+}
+
+async function intakeSourceRevoke(args) {
+  return toContent(await revokeIntakeSource(args, intakeDeps()));
+}
+
+// All four take the EXACT user-role key, like the `runner_*` family: the controller is
+// `role: :user` with `RequireHumanAnchor` on the writes, and create additionally requires a
+// caller NO DISPATCH MINTED (`RequireUnlineagedCaller`) — it mints the webhook secret, a
+// credential belonging to no lineage — so a global LOOPCTL_API_KEY of another shape must never
+// stand in for it. `baseUrl` is injected so the webhook URL names the server this process is
+// actually talking to.
+function intakeDeps() {
+  const userKey = process.env.LOOPCTL_USER_KEY;
+  return {
+    userKey,
+    baseUrl: getBaseUrl(),
+    apiCall: (method, path, body) => apiCall(method, path, body, userKey, { exactKey: true }),
+  };
+}
+
 // #846.6: correct a filed story. The action is `role: :orchestrator`
 // (`story_controller.ex:29-30`) and NOT `exact_role:`, so the hierarchy applies and a `:user`
 // or `:superadmin` key passes too. That is why LOOPCTL_ORCH_KEY goes through `resolveKey` as an
@@ -4242,6 +4316,32 @@ const TOOLS = [
       required: ["project_id"],
     },
   },
+  {
+    name: "list_blocked_stories",
+    description:
+      "List stories with an unverified dependency — a story they depend on, or a story in an " +
+      "epic their epic depends on — each with the blocking dependencies. It is by dependency " +
+      "alone, WHATEVER the story's own status: an in-flight or finished story whose " +
+      "prerequisite was later rejected is listed too. The rows carry no delivery stage: the " +
+      "ones the dispatch driver skips are those whose story_stage is queued (check with " +
+      "story_stage), and place_dispatch refuses them 409 dependencies_not_met. " +
+      "Compact; paginated (page/page_size) with total_count. Refuses 422 when project_id is " +
+      "not a UUID. Key: agent role or higher.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        project_id: {
+          type: "string",
+          description: "Optional: the UUID of a project to limit the list to.",
+        },
+        page: { type: "integer", description: "Page number (default 1)." },
+        page_size: {
+          type: "integer",
+          description: "Stories per page (default 100, max 500).",
+        },
+      },
+    },
+  },
   {
     name: "get_story",
     description: "Get full details for a single story by ID.",
@@ -4263,7 +4363,11 @@ const TOOLS = [
     description:
       "Agent acknowledges a story's acceptance criteria to claim the contract. " +
       "Transitions the story from pending to contracted. " +
-      "story_title and ac_count must match the actual story to prevent silent misclaims.",
+      "story_title and ac_count must match the actual story to prevent silent misclaims. " +
+      "Refused 409 story_held when the story's delivery stage is escalated, done or failed: " +
+      "it is not available to agents even when it reads pending — move on. An escalated " +
+      "story becomes available again only after resolve_escalation sends it to queued; a " +
+      "done or failed one never does.",
     inputSchema: {
       type: "object",
       properties: {
@@ -4290,7 +4394,12 @@ const TOOLS = [
       "Transitions contracted -> assigned. Uses the AGENT key. 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.",
+      "is released back to pending under you. Refused 409 story_held when the story's " +
+      "delivery stage is escalated, done or failed: it is not yours to claim even when it " +
+      "reads pending or contracted — move on. An escalated story is claimable again only " +
+      "after resolve_escalation sends it to queued; a done or failed one never is. Refused " +
+      "409 dependencies_not_met when a story it depends on, or one in an epic its epic " +
+      "depends on, is not verified: list_blocked_stories names them.",
     inputSchema: {
       type: "object",
       properties: {
@@ -4306,12 +4415,22 @@ const TOOLS = [
     name: "renew_story_claim",
     description:
       "Renew your claim's lease (POST /api/v1/stories/:id/renew-claim): claimed_until becomes " +
-      "now plus the lease length, measured from NOW. Call it well inside the lease on any story " +
-      "you hold longer than it. Uses the AGENT key, the same key as claim_story. Refusals pass " +
+      "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 " +
+      "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 " +
+      "acceptance + wall_clock_seconds + the grace, only while the claim is live; never " +
+      "earlier than a deadline_at already sent), and its claimed_until already IS that cap: " +
+      "renewing it writes nothing and returns the claim as it stands, so renewing " +
+      "never moves claimed_until past that instant. " +
+      "Uses the AGENT key, the same key as claim_story. Refusals pass " +
       "through: 400 claim_epoch missing or not a non-negative integer; 422 not_claimed (the " +
       "story is not assigned or implementing); 409 stale_claim_epoch (the claim has ENDED: it " +
       "expired and was reclaimed, released, or claimed again, so stop working it); 409 " +
-      "not_claimant (your key's agent is not the story's assigned agent).",
+      "not_claimant (your key's agent is not the story's assigned agent); " +
+      "409 lease_cap_reached (a driver-placed claim already at its cap: nothing is renewed " +
+      "and the claim ends there, so stop working it).",
     inputSchema: {
       type: "object",
       properties: {
@@ -4527,7 +4646,11 @@ const TOOLS = [
     name: "reject_story",
     description:
       "Orchestrator rejects a story with a reason. " +
-      "Creates a verification_result with result=fail. Uses the ORCH key.",
+      "Creates a verification_result with result=fail. Uses the ORCH key. " +
+      "The reject releases the claim, and a delivery story may be re-contracted or escalated " +
+      "in the same transaction. A 500 `audit_chain_append_failed` (the escalation's chain " +
+      "entry was refused) means the WHOLE call rolled back: the story is unchanged, and a " +
+      "re-run meets the same server-side condition until an operator acts.",
     inputSchema: {
       type: "object",
       properties: {
@@ -7954,6 +8077,11 @@ const TOOLS = [
       "no_conforming_branch, and when a machine refuses dispatches with branch_not_allowed — a " +
       "runner that ENFORCES a prefix and declares none shows [] here, which is that " +
       "misconfiguration made visible. Per-CONNECTION, like kinds. " +
+      "usage_exhausted_until (runner contract 1.17.0) is until when the machine's SUBSCRIPTION " +
+      "is exhausted, or null: while it is in the future nothing is placed on the machine and " +
+      "place_dispatch refuses 409 runner_exhausted. It is the EFFECTIVE value — the latest of " +
+      "the machine's own and every machine's sharing its account — so a machine that never " +
+      "reported anything can show one; capacity returns at that instant on its own. " +
       "live_sockets " +
       "above 1 means more than one process holds that runner's credential. A killed runner " +
       "disappears once its socket closes. Presence converges only " +
@@ -7969,7 +8097,8 @@ const TOOLS = [
       "push the work (POST /api/v1/runners/:runner_id/dispatches). This is the control-side " +
       "trigger of the agent delivery loop — the verb that turns a story the loop has decided " +
       "to build into a session running on a machine. Get `runner_id` and its free slots from " +
-      "runner_pool; the story must be `contracted` with its delivery stage at `queued` " +
+      "runner_pool; the story must be `pending` or `contracted` (a pending one is contracted " +
+      "by the placement), its dependencies met, with its delivery stage at `queued` " +
       "(story_stage shows where it is).\n\n" +
       "The STORY OBJECT is not a parameter: loopctl builds it from its own rows and refuses a " +
       "caller-supplied one, because a control plane able to hand a runner prose is able to " +
@@ -7988,6 +8117,11 @@ const TOOLS = [
       "choosing a machine. It refuses a NEW placement only: retrying with a dispatch_id " +
       "loopctl already holds still re-sends that dispatch, because its claim is already " +
       "standing and a draining machine is asked to finish what it holds, not to take more.\n\n" +
+      "409 `runner_exhausted` means the machine's subscription (its own, or one it shares an " +
+      "account with) is exhausted, so every session placed there would end usage_exhausted. " +
+      "NOTHING WAS CLAIMED; the body carries `usage_exhausted_until`, when it clears on its " +
+      "own. Place on another runner — runner_pool shows `usage_exhausted_until` per machine. " +
+      "Like `runner_declines_work` it refuses a NEW placement only.\n\n" +
       "409 `no_conforming_branch` means the machine declares `branch_prefixes` (runner " +
       "contract 1.14.0) and none of them can produce a valid branch name carrying the story " +
       "number and id fragment that keeps two stories off one branch. NOTHING WAS CLAIMED. " +
@@ -8006,7 +8140,15 @@ const TOOLS = [
       "push and re-sent verbatim, because a session may be running on it right now. Neither " +
       "prefix refusal can be raised by a RETRY carrying a dispatch_id loopctl already " +
       "holds: its claim is already standing, so a declaration that changed under you only " +
-      "steers the name and never strands the story.",
+      "steers the name and never strands the story.\n\n" +
+      "A RETRY also moves the claim's deadline: the re-sent dispatch carries deadline_at = now + " +
+      "its wall_clock_seconds + DISPATCH_LEASE_GRACE_SECONDS (never earlier than the one already " +
+      "sent), so a late or a longer retry gets its whole clock. 409 `dispatch_claim_ended` means " +
+      "the claim that dispatch_id was placed under has ENDED — its lease ran out, or the story " +
+      "left assigned/implementing: nothing was pushed or written and the claim is not revived. " +
+      "Place the story again with a NEW dispatch_id once it is placeable. 409 " +
+      "`dependencies_not_met` means a story it depends on, or one in an epic its epic depends on, " +
+      "is not verified: nothing was minted, claimed or pushed; place it once they are.",
     inputSchema: {
       type: "object",
       properties: {
@@ -8117,6 +8259,46 @@ const TOOLS = [
       required: ["story_id", "to"],
     },
   },
+  {
+    name: "merge_precondition",
+    description:
+      "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 (`verified_status: verified` by a separate lineage), 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`.\n\n" +
+      "GATE A READS WHAT TRIAGE PERSISTED, NEVER YOU. Its input is the lens verdicts recorded " +
+      "with the story's most recent triage, or a human's re-queue of a Gate A escalation; this " +
+      "tool sends no trio. `gate_a_inputs` on the answer says which (`persisted_triage`, " +
+      "`human_resolution`, or `missing` — which refuses with `gate_a_inputs_missing`).\n\n" +
+      "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` " +
+      "(back to implementing), `unevaluated` (503 with Retry-After: a transient forge fault; " +
+      "retry after the delay, nothing transitioned).\n\n" +
+      "REFUSALS. Needs an ORCHESTRATOR- or USER-role key: the action is `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` on a tenant without a human anchor, " +
+      "404 for an unknown story, 422 when `claim_epoch` is missing or the story is not at `ci` " +
+      "or has no stage row. A `story_id` that is not a UUID or a bad `claim_epoch` is refused " +
+      "here, before any call.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        story_id: { type: "string", description: "The story UUID, at stage `ci`." },
+        claim_epoch: {
+          type: "integer",
+          description: "The claim epoch you act under; it fences the escalation a refusal writes.",
+        },
+        effect_proof: {
+          type: "object",
+          description:
+            "Optional effect proof for a change touching an effect path. Judged and recorded; " +
+            "it cannot turn a `prove_effect` outcome into an allow.",
+        },
+      },
+      required: ["story_id", "claim_epoch"],
+    },
+  },
   {
     name: "force_unclaim_story",
     description:
@@ -8124,12 +8306,13 @@ const TOOLS = [
       "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" +
+      "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 when the release leaves the stage " +
+      "row at `queued` loopctl escalates it over `operator_released` in the same transaction — " +
+      "it is not left in the queue behind the human's back. It spends no attempt " +
+      "against the retry ceiling. To put it back to work, call resolve_escalation with " +
+      "`to: queued`: that releases (a no-op now) AND re-contracts, so the story is placeable " +
+      "again. A story with no delivery stage row is simply left `pending`, as before.\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 " +
@@ -8150,11 +8333,18 @@ const TOOLS = [
       "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.",
+      "It does NOT touch `verified_status`. RUN AGAIN on an already-pending story, it is still " +
+      "an operator's release and does what one does: a row STRANDED behind the story's claim " +
+      "epoch is rebound to it (the remedy for a row an older release left behind), an " +
+      "in-flight row is requeued, and a row that is then at `queued` — including one that was " +
+      "already sitting there — is ESCALATED over `operator_released`, like the first run. A " +
+      "row already escalated, or anywhere else at that epoch, is left exactly as it is. 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) is remedied by calling it again. A 422 means the release " +
+      "write itself was rejected. It takes no request body.",
     inputSchema: {
       type: "object",
       properties: {
@@ -8164,6 +8354,216 @@ const TOOLS = [
     },
   },
 
+  {
+    name: "intake_source_enroll",
+    description:
+      "BIND A GITHUB REPOSITORY TO A WORK PROJECT and mint its webhook secret (POST " +
+      "/api/v1/intake/sources). This is how the agent delivery loop gets an input at all: " +
+      "until a repository has an intake source, no webhook anywhere points at loopctl and no " +
+      "issue can reach a queue. It is also the binding place_dispatch reads — a project bound " +
+      "to no source refuses 409 `no_intake_source`, and one bound to two refuses 409 " +
+      "`ambiguous_intake_source`; this tool is what those two refusals mean by enrolling a " +
+      "source.\n\n" +
+      "THE WEBHOOK SECRET IS RETURNED ONCE AND CAN NEVER BE READ AGAIN. The column is " +
+      "encrypted at rest and redacted on the schema, so neither intake_source_list nor " +
+      "intake_source_update ever carries it; losing it costs a revoke, a second enrolment and " +
+      "a reconfigured GitHub webhook. THIS TOOL DOES NOT RETURN IT EITHER — a tool result " +
+      "lands in the session transcript and the audit log, so the secret is written to " +
+      "`secret_file` with mode 0600 (the same handling runner_enroll gives a runner " +
+      "credential) and the result carries only 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 while there is still nothing to lose, and any outcome that is not " +
+      "a clean creation withholds the response body because an unparsed 2xx body IS the " +
+      "secret. A 2xx that carries the source and the secret but no webhook path is RECOVERED " +
+      "rather than discarded — the path is derived from the source id and the result says so " +
+      "with `webhook_url_derived` — while an outcome that proves a source id but no usable " +
+      "secret REVOKES that source, since it could never authenticate a delivery and would " +
+      "hold the repository's unique slot.\n\n" +
+      "THEN CONFIGURE GITHUB — the tool stops at the loopctl end and this is the other half. " +
+      "On the repository: Settings > Webhooks > Add webhook, Payload URL = the `webhook_url` " +
+      "returned, Content type = application/json, Secret = the contents of `secret_file`, and " +
+      "under 'Let me select individual events' tick ISSUES ONLY. The secret is the HMAC key " +
+      "GitHub signs the RAW body with as `X-Hub-Signature-256`; loopctl verifies it before " +
+      "trusting a byte. In one command, without the secret ever passing through this " +
+      "transcript: 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'\n\n" +
+      "EVERY delivery failure afterwards is the SAME 401 `invalid_signature` — an unknown or " +
+      "revoked source, a suspended tenant, a missing or wrong signature, and a payload whose " +
+      "`repository.full_name` does not match this source's repository. That is deliberate (a " +
+      "valid signature for the wrong repository is a misrouted or replayed delivery), and it " +
+      "means the webhook's own Recent Deliveries tab cannot tell you which of them happened.\n\n" +
+      "REFUSALS. 403 `api_key_mint_forbidden` if your key was minted by a dispatch: this call " +
+      "mints a credential belonging to no lineage, so only a key that is itself unlineaged — " +
+      "the tenant's operator key in LOOPCTL_USER_KEY — may make it, and reaching for a more " +
+      "privileged ephemeral key does not get past it. 403 `custody_tier_required` on an " +
+      "agent-rooted tenant, which may not open an intake surface for itself (an intake source " +
+      "admits outside text into the queue of a project whose stories an implementer will act " +
+      "on). 422 when the repository is not `owner/name`, when an ACTIVE source already binds " +
+      "that repository (revoke it first — the uniqueness is partial on not-yet-revoked), when " +
+      "the project is missing, archived or not a work project, or when `target_epic_id` names " +
+      "an epic outside that project. 429 when rate limited.\n\n" +
+      "NAME `base_branch` AT ENROLMENT for a repository whose trunk is not `master`. It is the " +
+      "branch every dispatch for this repository is cut FROM, it defaults to `master` when the " +
+      "body does not name it, and GitHub has created repositories with `main` since 2020 — so " +
+      "an unnamed branch on a `main` repository sends every dispatch to cut from a branch that " +
+      "does not exist, and the failure arrives after the claim. There is no cleared state for " +
+      "it (a dispatch must name one), so null or blank is refused rather than falling back to " +
+      "the default; intake_source_update changes it afterwards.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        repo_full_name: {
+          type: "string",
+          description:
+            "The repository as `owner/name`, e.g. `mkreyman/home_care_billing`. Not a URL. " +
+            "Matched case-insensitively against each delivery's `repository.full_name`.",
+        },
+        project_id: {
+          type: "string",
+          description:
+            "The ACTIVE WORK project (UUID) whose queue this repository's issues feed. A `kb` " +
+            "scope or an archived project is a 422.",
+        },
+        target_epic_id: {
+          type: "string",
+          description:
+            "Optional. The epic a story triaged from this source's issues is created in; it " +
+            "must belong to the project above. OMITTING IT IS NOT A NEUTRAL DEFAULT: with no " +
+            "epic, a triaged report is ESCALATED to a human instead of becoming a story, and " +
+            "every record from this source stays `pending_triage` and is retried until " +
+            "intake_source_update names one — at which point they all promote on the next run " +
+            "with nothing lost. Unanswered is the safe state rather than a guess.",
+        },
+        base_branch: {
+          type: "string",
+          description:
+            "Optional. The branch every dispatch for this repository is cut FROM, and the " +
+            "`base_branch` an unattended dispatch carries. Omit it for `master`; send `main` " +
+            "for a repository created on GitHub since 2020, or the loop places work against a " +
+            "branch that does not exist. NOT nullable, unlike target_epic_id — there is no " +
+            "unanswered state for a branch a dispatch must name — so null or blank is refused " +
+            "here rather than silently taking the default. Changed later with " +
+            "intake_source_update.",
+        },
+        secret_file: {
+          type: "string",
+          description:
+            "REQUIRED. Absolute path (or starting with `~/`) the webhook secret is written to, " +
+            "mode 0600. It is never returned in the result. Refused if the path already " +
+            "exists, and nothing is enrolled in that case.",
+        },
+      },
+      required: ["repo_full_name", "project_id", "secret_file"],
+    },
+  },
+  {
+    name: "intake_source_list",
+    description:
+      "LIST THE TENANT'S GITHUB INTAKE SOURCES (GET /api/v1/intake/sources): per source its " +
+      "`id` (the webhook URL is /api/v1/intake/github/<id>), `project_id`, `repo_full_name`, " +
+      "`base_branch`, `target_epic_id`, `revoked_at` and timestamps. Active sources only " +
+      "unless `include_revoked` is true.\n\n" +
+      "THE WEBHOOK SECRET IS NOT HERE AND IS NOT ANYWHERE. It is returned once by " +
+      "intake_source_enroll and the column is redacted on the schema, so this is not the way " +
+      "to recover one — revoking and enrolling again is. Use this to find the source behind a " +
+      "409 `no_intake_source` (the project is bound to none) or a 409 " +
+      "`ambiguous_intake_source` (bound to two, so revoke the one that no longer applies), to " +
+      "check a repository's `base_branch` before placing work, and to identify a source left " +
+      "behind by an enrolment whose outcome was unknown. Requires LOOPCTL_USER_KEY; this read " +
+      "is the one action of the four that does not need a human-anchored tenant.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        include_revoked: {
+          type: "boolean",
+          description: "Include revoked sources. Default false.",
+        },
+      },
+    },
+  },
+  {
+    name: "intake_source_update",
+    description:
+      "SET WHERE A SOURCE'S WORK LANDS (PATCH /api/v1/intake/sources/:id): `target_epic_id`, " +
+      "the epic triaged stories are created in, and `base_branch`, the branch every dispatch " +
+      "for this repository is cut FROM and carries.\n\n" +
+      "PRESENCE DECIDES, AND A FIELD YOU DO NOT NAME IS LEFT EXACTLY AS IT WAS. Naming " +
+      "neither is refused 422 `nothing_to_update` rather than being a silent no-op. DO NOT " +
+      "SEND `target_epic_id: null` TO MEAN 'I AM NOT CHANGING THIS' — an explicit null is the " +
+      "only way to CLEAR the epic, and clearing it returns the source to escalating every " +
+      "report to a human instead of filing a story. Leave the field out instead. " +
+      "`base_branch` has no cleared state at all (every dispatch must name a branch to cut " +
+      "from), so a null there is refused.\n\n" +
+      "THIS IS THE FIX FOR A SOURCE ALREADY POINTED AT THE WRONG TRUNK. intake_source_enroll " +
+      "now takes `base_branch` itself, so a `main` repository is enrolled correctly in one " +
+      "call; this is what corrects one that was not — a source enrolled before the parameter " +
+      "existed, or enrolled without it, places work against a trunk that does not exist until " +
+      "it is repointed. It " +
+      "is also the remedy for a source enrolled before it had an epic: until one is named " +
+      "every record from it stays `pending_triage` and is retried, and the moment one is they " +
+      "promote on the next run with nothing lost.\n\n" +
+      "REVOKED SOURCES ARE 404, not a no-op: revoking CLEARS the target epic precisely so that " +
+      "epic can be deleted, and repointing a source that will never report again would put " +
+      "that block back. 422 when the epic is not in this source's project. Requires " +
+      "LOOPCTL_USER_KEY and a human-anchored tenant (403 `custody_tier_required`). A " +
+      "`source_id` that is not a UUID is refused here, before any call — the server answers " +
+      "the same 404 for a malformed id as for an unknown one.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        source_id: {
+          type: "string",
+          description: "The intake source UUID (from intake_source_list).",
+        },
+        target_epic_id: {
+          type: ["string", "null"],
+          description:
+            "The epic triaged stories land in; it must belong to this source's project. An " +
+            "explicit null CLEARS it, which returns the source to escalating every report. " +
+            "Omit the field entirely to leave the current value alone.",
+        },
+        base_branch: {
+          type: "string",
+          description:
+            "The branch dispatches for this repository are cut from, e.g. `main`. 1-255 " +
+            "characters, not nullable. Omit to leave the current value alone.",
+        },
+      },
+      required: ["source_id"],
+    },
+  },
+  {
+    name: "intake_source_revoke",
+    description:
+      "REVOKE A GITHUB INTAKE SOURCE (DELETE /api/v1/intake/sources/:id). The HTTP verb is " +
+      "DELETE and the action is a REVOKE: `revoked_at` is stamped, the row is kept, and " +
+      "intake_source_list still returns it with `include_revoked`. Nothing already received " +
+      "is discarded.\n\n" +
+      "Afterwards every delivery to that webhook URL is refused 401 `invalid_signature`, " +
+      "exactly as a wrong secret is — so the GitHub webhook does not know it has been cut off " +
+      "and should be deleted on the repository too. IDEMPOTENT: revoking twice answers 200 " +
+      "with the original `revoked_at`.\n\n" +
+      "TWO THINGS IT UNBLOCKS. It frees the repository's uniqueness slot, so a source with a " +
+      "lost secret, a wrong project or a typo'd repository is corrected by revoking and " +
+      "enrolling again — the active-repository index is partial on not-yet-revoked, so the " +
+      "422 `an active intake source already binds this repository` clears the moment this " +
+      "returns. And it CLEARS `target_epic_id`, which is what makes that epic deletable: the " +
+      "reference blocks an epic delete, and this is the remedy that refusal names.\n\n" +
+      "Requires LOOPCTL_USER_KEY and a human-anchored tenant (403 `custody_tier_required`). " +
+      "404 for an unknown source or another tenant's; a `source_id` that is not a UUID is " +
+      "refused here, before any call, because the server answers that same 404 for both.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        source_id: {
+          type: "string",
+          description: "The intake source UUID to revoke (from intake_source_list).",
+        },
+      },
+      required: ["source_id"],
+    },
+  },
+
   // LCP-1 §9 signed-profile tools
   {
     name: "register_custody_owner_key",
@@ -8895,6 +9295,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     case "list_ready_stories":
       return await listReadyStories(args);
 
+    case "list_blocked_stories":
+      return await listBlockedStories(args);
+
     case "get_story":
       return await getStory(args);
 
@@ -9206,6 +9609,21 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     case "force_unclaim_story":
       return await forceUnclaimStory(args);
 
+    case "merge_precondition":
+      return await mergePreconditionTool(args);
+
+    case "intake_source_enroll":
+      return await intakeSourceEnroll(args);
+
+    case "intake_source_list":
+      return await intakeSourceList(args);
+
+    case "intake_source_update":
+      return await intakeSourceUpdate(args);
+
+    case "intake_source_revoke":
+      return await intakeSourceRevoke(args);
+
     case "register_custody_owner_key":
       return await registerCustodyOwnerKey(args);
 

package/lib/claim-lease.js

@@ -2,7 +2,9 @@
  * Story claim leases (loopctl #803/#810, MCP side under #809).
  *
  * A claim now carries a LEASE (`claimed_until`, default 24h, STORY_CLAIM_LEASE_SECONDS)
- * and a FENCE (`claim_epoch`, bumped by every claim and every release). A claim that is not
+ * and a FENCE (`claim_epoch`, bumped by every claim and every release). A claim a placement
+ * took for a runner dispatch also carries `claim_lease_cap` (#879): its dispatch deadline,
+ * which no renewal moves the lease past. A claim that is not
  * renewed before `claimed_until` is released back to `pending` under the agent still
  * working it. `renew_story_claim` is the MCP path to `POST /stories/:id/renew-claim`, and
  * `claimLeaseNotice` puts the epoch and the deadline at the top of a `claim_story` result so
@@ -13,8 +15,9 @@
  * travels on is testable behaviour rather than a source pattern.
  *
  * Nothing is validated client-side beyond `story_id`: the server's 400 (missing or
- * non-integer epoch), 422 `not_claimed`, 409 `stale_claim_epoch` and 409 `not_claimant`
- * pass through unchanged, because each one tells the agent something different to do.
+ * non-integer epoch), 422 `not_claimed`, 409 `stale_claim_epoch`, 409 `not_claimant` and
+ * 409 `lease_cap_reached` pass through unchanged, because each one tells the agent
+ * something different to do.
  */
 
 export function renewClaimPath(storyId) {
@@ -45,8 +48,14 @@ export function claimLeaseNotice(result) {
       "story is released back to pending under you."
     : "no lease (claimed_until is null), so it is never released automatically.";
 
+  // #879: a driver-placed claim is capped at its dispatch deadline, and no renewal passes it.
+  const cap = story.claim_lease_cap
+    ? ` This claim is CAPPED at its dispatch deadline ${story.claim_lease_cap}: renewing never ` +
+      "moves claimed_until past it."
+    : "";
+
   return (
-    `CLAIM LEASE: claim_epoch ${story.claim_epoch}, ${lease} Keep claim_epoch; ` +
+    `CLAIM LEASE: claim_epoch ${story.claim_epoch}, ${lease}${cap} Keep claim_epoch; ` +
     "renew_story_claim requires it. A 409 stale_claim_epoch means the claim has ended: stop working it."
   );
 }