loopctl-mcp-server 2.100.0 → 2.102.0

package/README.md

@@ -70,7 +70,7 @@ Or if installed locally:
 | `LOOPCTL_API_KEY` | Global API key override: used for every tool except the exact-key ones below, and for the `exact_role: :orchestrator` custody verbs when `LOOPCTL_ORCH_KEY` is unset | -- |
 | `LOOPCTL_ORCH_KEY` | Orchestrator role API key (report, review, import, and the `exact_role: :orchestrator` custody verbs `verify_story` / `reject_story` / `verify_all_in_epic` / `bulk_mark_complete` / `force_unclaim_story` — when it is set, it is the key those five send) | -- |
 | `LOOPCTL_AGENT_KEY` | Agent role API key (contract, claim, start, request-review) | -- |
-| `LOOPCTL_USER_KEY` | User role API key (minted at signup). Required for **first-time BYO LLM key provisioning** (`set_llm_config` / `llm_config` — see [First-time setup](#first-time-setup--provision-your-byo-llm-keys)), for destructive admin tools like `knowledge_bulk_publish`, and for the `runner_*` tools plus `place_dispatch` and `resolve_escalation` in [Runner and delivery-loop tools](#runner-and-delivery-loop-tools). **Not for the whole of that section:** `story_stage` takes `LOOPCTL_AGENT_KEY`, and `force_unclaim_story` is `exact_role: :orchestrator`, where a user key is 403'd like any other non-member. | -- |
+| `LOOPCTL_USER_KEY` | User role API key (minted at signup). Required for **first-time BYO LLM key provisioning** (`set_llm_config` / `llm_config` — see [First-time setup](#first-time-setup--provision-your-byo-llm-keys)), for destructive admin tools like `knowledge_bulk_publish`, and for the `runner_*` and `intake_source_*` tools plus `place_dispatch` and `resolve_escalation` in [Runner and delivery-loop tools](#runner-and-delivery-loop-tools). **Not for the whole of that section:** `story_stage` takes `LOOPCTL_AGENT_KEY`, and `force_unclaim_story` is `exact_role: :orchestrator`, where a user key is 403'd like any other non-member. | -- |
 | `LOOPCTL_STH_STATE_PATH` | Absolute path for the witness-protocol STH cache file (see [Witness protocol](#witness-protocol-sth)). Optional. | per-(server + key) file under the OS temp dir |
 
 Key resolution priority: `LOOPCTL_API_KEY` > tool-specific key > `LOOPCTL_ORCH_KEY`.
@@ -84,6 +84,7 @@ variable the tool names, so a key you set for a specific role is the key that ge
 |---|---|---|
 | `verify_story`, `reject_story`, `verify_all_in_epic`, `bulk_mark_complete`, `force_unclaim_story` | `LOOPCTL_ORCH_KEY` (`exact_role: :orchestrator`) | Pinned **when `LOOPCTL_ORCH_KEY` is set**. With no orchestrator key, `LOOPCTL_API_KEY` is still sent — set it to an orchestrator-role key and these work. |
 | `place_dispatch`, `resolve_escalation` | `LOOPCTL_USER_KEY` (an unlineaged human principal) | Always pinned; `LOOPCTL_API_KEY` is never consulted. |
+| `intake_source_enroll`, `intake_source_list`, `intake_source_update`, `intake_source_revoke` | `LOOPCTL_USER_KEY` | Always pinned; `LOOPCTL_API_KEY` is never consulted. The endpoint is `role: :user` with the hierarchy, but enrolling MINTS the webhook secret — a credential belonging to no dispatch lineage — so the caller must itself be unlineaged (`RequireUnlineagedCaller`) or it is refused 403 `api_key_mint_forbidden`. |
 | `set_llm_config`, `llm_config` and the other secret-managing tools | `LOOPCTL_USER_KEY` | Always pinned; a secret operation must not run under a non-user global key. |
 
 Why pin at all: the priority above means `LOOPCTL_API_KEY` beats the variable a tool names,
@@ -500,18 +501,24 @@ The generated-tool count per tenant is bounded by the per-tenant entity cap.
 
 ### Runner and delivery-loop tools
 
-Enroll the dev machines that run the agent delivery loop, see which are connected (issue #809), place work on them and recover a story a runner would not take. The `runner_*` tools require `LOOPCTL_USER_KEY`, and enroll and revoke additionally require a human-anchored tenant. The delivery-loop verbs below do NOT share one key — each row names the key its endpoint's gate demands, and a higher-privileged key does not substitute for an `exact_role` one.
+Enroll the dev machines that run the agent delivery loop, see which are connected (issue #809), bind the repositories whose issues feed it, place work on them and recover a story a runner would not take. The `runner_*` and `intake_source_*` tools require `LOOPCTL_USER_KEY`, and their writes additionally require a human-anchored tenant. The delivery-loop verbs below do NOT share one key — each row names the key its endpoint's gate demands, and a higher-privileged key does not substitute for an `exact_role` one.
+
+**A loop with no intake source has no input.** `intake_source_enroll` is the step that points a GitHub repository at loopctl, and the same row is where `place_dispatch` reads `repo` and `base_branch` from — its 409 `no_intake_source` names exactly this. The webhook secret it returns is written to a file and never appears in a tool result; see that row.
 
 | Tool | Description |
 |---|---|
 | `runner_enroll` | Enroll this machine as a runner (`POST /api/v1/runners`). Required: `name` (the machine name the runner declares when it joins) and `token_file` (absolute, or starting with `~/`). Optional: `max_sessions` (1..64, default 2) — the CEILING on how many dispatches loopctl will ever keep in flight on this machine at once, and the value it starts at. Since runner contract 1.13.0 every join re-applies the machine's own declared `max_sessions` bounded by this one, so a machine may take itself down below its grant and cannot raise itself above it: to carry FEWER sessions change `control.max_sessions` in the runner's own config and reconnect, to carry MORE `runner_revoke` it first and then enrol it again (nothing widens the ceiling in place, and enrolling the same name while its runner is active is a 422; the revoke invalidates the credential, so the new token file must reach the machine and the runner be restarted). The tenant's total across its runners is capped separately by the server. The credential is written to `token_file` with mode 0600 and is **never returned**: the result is only `{ runner: {id, name, inserted_at}, token_file }`, because a tool result lands in the transcript and the token lets its holder join as that machine. The file is created exclusively, so an existing path (or a symlink there) is refused before anything is enrolled; missing parent directories are created 0700. If the token cannot be written after enrollment, the runner is revoked before the error returns. Only a 4xx is treated as a refusal: any other failure (timeout, 5xx, a 2xx that did not parse) may have enrolled the runner, so its response body is never echoed, the runner is revoked when the response proves its id, and otherwise the error points at `runner_list` and `runner_revoke`. 422 (name malformed or taken) and 403 (`custody_tier_required`, `api_key_mint_forbidden`) pass through with their code. |
 | `runner_list` | List enrolled runners (`GET /api/v1/runners`). Optional: `include_revoked`. Enrollment only; connection state is `runner_pool`. |
 | `runner_revoke` | Revoke a runner (`DELETE /api/v1/runners/:id`): its credential stops authenticating and its live socket is disconnected. The undo for `runner_enroll`. Idempotent. Required: `id`. |
-| `runner_pool` | The tenant's connected runners from Presence (`GET /api/v1/runners/pool`): per machine name, `runner_id`, `joined_at`, `draining`, the latest `sample`, `live_sockets` (above 1 means more than one process holds the credential), and the `node` and `machine_id` (Fly Machine) holding the socket. `in_flight` and `max_sessions` are the capacity loopctl holds in Postgres — what dispatch reserves against — and are null only for a runner revoked while its socket drains; `reported_in_flight` and `reported_max_sessions` are the runner's own last report: `reported_in_flight` is a hint (the runner counts sessions, loopctl counts reservations), while `reported_max_sessions` is what `max_sessions` is copied from on every join (contract 1.13.0), capped at `enrolled_max_sessions` which is also returned. The two can differ in EITHER direction. `max_sessions` BELOW it happens when the machine is declaring above its enrolled ceiling (`enrolled_max_sessions` is what makes that one visible in the payload; the rest are not), when the declaration write has not LANDED — it can fail under lock contention on the runner row and is retried on that socket's 30-second recheck, downward only — or when the socket joined a node older than contract 1.13.0 and has not reconnected since. `max_sessions` ABOVE it happens when the machine declared `0`, held as `1` because the column is 1..64 while this field shows the raw `0`, and again when a declaration write has not landed and the row keeps an older, larger number. A `reported_max_sessions` of 0 means the machine is taking no work and `place_dispatch` refuses a new placement on it, like `draining`. Presence converges only within a cluster. |
-| `place_dispatch` | **Place a queued story on a runner** (`POST /api/v1/runners/:runner_id/dispatches`): claims it under a freshly minted custody dispatch and pushes the work. The control-side trigger of the delivery loop. 409 `runner_declines_work` when the machine declares `draining` or `max_sessions` 0 — refused before the mint, so nothing was claimed; a retry carrying a `dispatch_id` loopctl already holds is re-sent anyway, because its claim is already standing. Required: `story_id`, `runner_id` (from `runner_pool`). Optional: `kind` (`implement`, the only kind this tool sends — `triage` is dispatchable on the contract but placement CLAIMS the story, which triage must not do), `dispatch_id` (the idempotency key — generated when absent; pass the SAME one to retry rather than start a second session), `branch`, `base_branch`, `wall_clock_seconds`, `max_turns`. The story object is NOT a parameter: loopctl builds it from its own rows and refuses a caller-supplied one. The story must be `contracted` with its stage at `queued`. Requires `LOOPCTL_USER_KEY`. |
+| `runner_pool` | The tenant's connected runners from Presence (`GET /api/v1/runners/pool`): per machine name, `runner_id`, `joined_at`, `draining`, the latest `sample`, `live_sockets` (above 1 means more than one process holds the credential), and the `node` and `machine_id` (Fly Machine) holding the socket. `in_flight` and `max_sessions` are the capacity loopctl holds in Postgres — what dispatch reserves against — and are null only for a runner revoked while its socket drains; `reported_in_flight` and `reported_max_sessions` are the runner's own last report: `reported_in_flight` is a hint (the runner counts sessions, loopctl counts reservations), while `reported_max_sessions` is what `max_sessions` is copied from on every join (contract 1.13.0), capped at `enrolled_max_sessions` which is also returned. The two can differ in EITHER direction. `max_sessions` BELOW it happens when the machine is declaring above its enrolled ceiling (`enrolled_max_sessions` is what makes that one visible in the payload; the rest are not), when the declaration write has not LANDED — it can fail under lock contention on the runner row and is retried on that socket's 30-second recheck, downward only — or when the socket joined a node older than contract 1.13.0 and has not reconnected since. `max_sessions` ABOVE it happens when the machine declared `0`, held as `1` because the column is 1..64 while this field shows the raw `0`, and again when a declaration write has not landed and the row keeps an older, larger number. A `reported_max_sessions` of 0 means the machine is taking no work and `place_dispatch` refuses a new placement on it, like `draining`. `branch_prefixes` is what the machine declared it ACCEPTS as a branch-name prefix (runner contract 1.14.0): loopctl derives a branch starting with the FIRST entry, and `[]` means it declared no constraint. Read it when `place_dispatch` refuses 409 `no_conforming_branch`, and when a connected machine refuses every dispatch 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`. Presence converges only within a cluster. |
+| `place_dispatch` | **Place a queued story on a runner** (`POST /api/v1/runners/:runner_id/dispatches`): claims it under a freshly minted custody dispatch and pushes the work. The control-side trigger of the delivery loop. 409 `runner_declines_work` when the machine declares `draining` or `max_sessions` 0 — refused before the mint, so nothing was claimed; a retry carrying a `dispatch_id` loopctl already holds is re-sent anyway, because its claim is already standing. Required: `story_id`, `runner_id` (from `runner_pool`). Optional: `kind` (`implement`, the only kind this tool sends — `triage` is dispatchable on the contract but placement CLAIMS the story, which triage must not do), `dispatch_id` (the idempotency key — generated when absent; pass the SAME one to retry rather than start a second session), `base_branch`, `wall_clock_seconds`, `max_turns`, and `branch` — **which you should not send**. Since runner contract 1.14.0 loopctl DERIVES the branch from the story number and an id fragment, behind a prefix the target runner declared it accepts (`branch_prefixes`, visible on `runner_pool`), which is a per-machine fact only the server can read. A branch you name is never rewritten, only judged, and it must satisfy three things: it must be a valid git ref name (422 `invalid_branch_name`, which also refuses a non-string such as `null`), it must start with one of that machine's declared prefixes (422 `branch_not_allowed`), and it must END WITH THIS STORY'S OWN SUFFIX (422 `branch_not_unique`) so that two stories on one repository can never be given one branch — you may choose the prefix, you may not drop the suffix. Nothing is claimed on any of them, and the fix is to drop the field. `base_branch` is judged as a git ref name too (422 `invalid_branch_name`): it reaches git on the runner just as `branch` does. It is NOT story-unique — every dispatch cutting from `master` is the normal case. A retry naming a different `branch` from the one this dispatch was already sent on is 422 `branch_conflict`: the branch is recorded at the first push and re-sent verbatim, because a session may be running on it right now. 409 `no_conforming_branch` is the machine's problem rather than the request's: it declares prefixes and none of them can produce a valid branch name carrying the story number and id fragment that keeps two stories off one branch, so nothing was claimed and an operator has to fix `branch_prefixes` on that box — the body echoes the declared prefixes. A retry carrying a `dispatch_id` loopctl already holds is never refused for either prefix reason: its claim is already standing, so the declaration only steers the name. The story object is NOT a parameter: loopctl builds it from its own rows and refuses a caller-supplied one. The story must be `contracted` with its stage at `queued`. Requires `LOOPCTL_USER_KEY`. |
 | `story_stage` | **Where a story is in the delivery machine** (`GET /api/v1/stories/:id/stage`): stage, `claim_epoch`, `lock_version`, `attempts`, the runner holding it, and the escalation reason when parked. `stage: null` means the loop has never touched it. This is how you watch a run, and the only way to see why a stage report was refused `stale_stage`. `escalation_reason` is untrusted session text. Required: `story_id`. |
 | `resolve_escalation` | **Move an escalated story off `escalated`, as a human** (`POST /api/v1/stories/:id/stage/resolve`): `to` is `queued` (work it again), `done` or `failed`. The other half of `escalate_story` — without it a parked story stays parked for ever. Requires `LOOPCTL_USER_KEY` on a key no dispatch minted: a session cannot resolve the escalation it raised. Optional: `reason`. |
 | `force_unclaim_story` | **Take a story back from the agent holding it** (`POST /api/v1/stories/:id/force-unclaim`). Resets it to `agent_status: pending` with `assigned_agent_id` cleared AND makes the delivery stage row follow the release back to `queued`. **It frees the STAGE; it does not make the story placeable.** `place_dispatch` wants `contracted` + `queued` (see its own row in this table), and the release leaves the story at `pending`, whose only transition is `pending -> contracted` — so running `place_dispatch` next answers the identical 409 `invalid_transition`. The remedy is three calls, in this order: `force_unclaim_story`, then `contract_story`, then `place_dispatch`. A story parked at `claimed` with nobody on it is the residue of a compensation that did not complete, not what a refused dispatch normally leaves: placement releases the claim inline when a runner refuses, and the claim lease releases it unattended once `claimed_until` passes — reach for this to get it back now, or when both of those left it held. Requeues from any stage a claim holds; a stage no claim holds keeps its stage and is rebound to the new epoch; `done` and `failed` are untouched. For an ESCALATED story use `resolve_escalation` instead — that one releases AND re-contracts, so its `queued` really is placeable. Requires an orchestrator-ROLE key: the action is `exact_role: :orchestrator`, so a user or superadmin key is 403'd like any other non-member. Put it in `LOOPCTL_ORCH_KEY` (which is then the key sent, and a global `LOOPCTL_API_KEY` does not displace it) or, with no orchestrator key set, in `LOOPCTL_API_KEY`. The orchestrator key must be linked to a registered agent (400 otherwise) and the tenant must be human-anchored (403 `custody_tier_required` otherwise). Does not touch `verified_status`. Safe to run twice: on an already-pending story the stage row is written only if it is stranded behind the story's claim epoch or still in flight. No request body. Required: `story_id` (refused locally if it is not a UUID). |
+| `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. Required: `repo_full_name`, `project_id`, `secret_file`. Optional: `base_branch`, 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`. |
+| `intake_source_list` | List the tenant's intake sources (`GET /api/v1/intake/sources`): `id` (the webhook URL is `/api/v1/intake/github/<id>`), `project_id`, `repo_full_name`, `base_branch`, `target_epic_id`, `revoked_at`, timestamps. **The webhook secret is not here and is not anywhere** — it is returned once by `intake_source_enroll`, so this is not how to recover one. Use it to find the source behind a 409 `no_intake_source` or `ambiguous_intake_source`, to check a repository's `base_branch` before placing work, and to identify a source left behind by an enrolment whose outcome was unknown. Optional: `include_revoked`. Requires `LOOPCTL_USER_KEY`; the only one of the four that does not also need a human-anchored tenant. |
+| `intake_source_update` | **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. Presence decides — a field you do not name is left exactly as it was, and naming neither is 422 `nothing_to_update`. **Do not send `target_epic_id: null` to mean "not changing this":** an explicit null is the only way to CLEAR the epic, which returns the source to escalating every report instead of filing a story. `base_branch` has no cleared state and a null there is refused locally. This is how a source already pointed at the wrong trunk is corrected — `intake_source_enroll` takes `base_branch` itself, so a `main` repository no longer needs a second call — and the remedy for a source with no epic — every record from it stays `pending_triage` and is retried until one is named, then they promote on the next run with nothing lost. Revoked sources are 404, not a no-op: revoking clears the target so the epic can be deleted, and repointing one would put that block back. 422 when the epic is not in this source's project. Required: `source_id` (refused locally if it is not a UUID — the server answers the same 404 for malformed and unknown). Requires `LOOPCTL_USER_KEY` and a human-anchored tenant. |
+| `intake_source_revoke` | **Revoke an intake source** (`DELETE /api/v1/intake/sources/:id`). The 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. Afterwards every delivery to that 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 — a second revoke answers 200 with the original `revoked_at`. It frees the repository's uniqueness slot (the index is partial on not-yet-revoked), so a source with a lost secret, a wrong project or a typo'd repository is corrected by revoking and enrolling again; and it clears `target_epic_id`, which is what makes that epic deletable and is the remedy an epic-delete refusal names. Required: `source_id` (refused locally if it is not a UUID). Requires `LOOPCTL_USER_KEY` and a human-anchored tenant. |
 
 ### Dispatch & Chain of Custody (v2) Tools
 

package/index.js

@@ -54,6 +54,12 @@ import {
   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";
 
@@ -3289,6 +3295,48 @@ async function forceUnclaimStory(args) {
   );
 }
 
+// #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
@@ -7948,6 +7996,12 @@ const TOOLS = [
       "write has not landed and the row keeps an older, larger number. A reported_max_sessions " +
       "of 0 means the machine is taking no work and place_dispatch refuses a new placement on " +
       "it, like draining. " +
+      "branch_prefixes is what the machine declared it ACCEPTS as a branch-name prefix (runner " +
+      "contract 1.14.0): loopctl derives a branch starting with the FIRST entry, and [] means " +
+      "the machine declared no constraint. Read it when place_dispatch refuses 409 " +
+      "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. " +
       "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 " +
@@ -7981,7 +8035,26 @@ const TOOLS = [
       "NEW dispatch_id. Read `draining` and `reported_max_sessions` from runner_pool before " +
       "choosing a machine. It refuses a NEW placement only: retrying with a dispatch_id " +
       "loopctl already holds still re-sends that dispatch, because its claim is already " +
-      "standing and a draining machine is asked to finish what it holds, not to take more.",
+      "standing and a draining machine is asked to finish what it holds, not to take more.\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. " +
+      "The body echoes the declared prefixes; the fix is on that machine's own configuration, " +
+      "not in this call. 422 `branch_not_allowed` is the other half: you passed a `branch` " +
+      "outside those prefixes, so the machine would have refused the dispatch — omit it and " +
+      "loopctl derives a conforming one. 422 `invalid_branch_name` is a different refusal " +
+      "again: a ref field you passed — `branch` OR `base_branch`, which reaches git on the " +
+      "runner just as `branch` does — is not a string, or is not a valid git ref name, so no " +
+      "machine could create it; nothing was claimed and the remedy is in this call. 422 " +
+      "`branch_not_unique` means the `branch` you passed does not end with this story's own " +
+      "suffix, so two stories on one repository could share a branch and the second session " +
+      "would find the first's work there: keep your prefix and append the suffix the error " +
+      "names, or omit `branch`. 422 `branch_conflict` means a retry named a different branch " +
+      "from the one this dispatch was already sent on — the branch is recorded at the first " +
+      "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.",
     inputSchema: {
       type: "object",
       properties: {
@@ -8017,8 +8090,30 @@ const TOOLS = [
             "project bound to NO intake source (409 `no_intake_source`) or to TWO (409 " +
             "`ambiguous_intake_source`) — both refusals name these two parameters.",
         },
-        branch: { type: "string", description: "Optional. The branch the session works on." },
-        base_branch: { type: "string", description: "Optional. The branch it is cut from." },
+        branch: {
+          type: "string",
+          description:
+            "Optional, and you almost certainly should NOT pass it. loopctl derives the " +
+            "branch from the story number and an id fragment, behind a prefix the TARGET " +
+            "RUNNER declared it accepts on join (`branch_prefixes`, runner contract 1.14.0) " +
+            "— a per-machine fact only the server can read, and the reason this is derived " +
+            "rather than named. A branch you pass is never rewritten, so one outside that " +
+            "machine's prefixes is refused 422 `branch_not_allowed`, one that is not a valid " +
+            "git ref name (or is not a string at all, such as null) is refused 422 " +
+            "`invalid_branch_name`, and one that does not END WITH THIS STORY'S OWN SUFFIX " +
+            "is refused 422 `branch_not_unique` — you may choose the prefix, you may not " +
+            "drop the suffix, which is what keeps two stories on one repository off one " +
+            "branch. Nothing is claimed on any of them. runner_pool shows each machine's " +
+            "`branch_prefixes`.",
+        },
+        base_branch: {
+          type: "string",
+          description:
+            "Optional. The ref the session cuts FROM; defaults to the project's intake " +
+            "source. Judged as a git ref name exactly as `branch` is (422 " +
+            "`invalid_branch_name`, nothing claimed), but NOT story-unique — every dispatch " +
+            "cutting from master is the normal case.",
+        },
         wall_clock_seconds: { type: "integer", description: "Optional. Overrides the default." },
         max_turns: { type: "integer", description: "Optional. Overrides the default." },
       },
@@ -8117,6 +8212,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",
@@ -9159,6 +9464,18 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     case "force_unclaim_story":
       return await forceUnclaimStory(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/intake-sources.js

@@ -0,0 +1,554 @@
+/**
+ * GitHub intake sources — `/api/v1/intake/sources` (loopctl #803, #846).
+ *
+ * ## The defect these exist for
+ *
+ * loopctl's agent delivery loop is built end to end — webhook intake, triage, the stage
+ * machine, placement, the unattended driver — and until these tools it had never received a
+ * GitHub issue, because nothing outside the app could create the one row that makes a
+ * webhook possible. All five intake-source routes were declared `gap` in
+ * `test/route_coverage.test.js`: no tool reached any of them, and `claude-config`'s
+ * `hooks/orchestrator-guardrail.sh` refuses a `curl` carrying `loopctl.com` from every
+ * session on the fleet, deliberately. So the loop's own wiring step was reachable by a human
+ * with `iex` on the production node and by nothing else — loopctl's "an operator-facing
+ * endpoint is not done until an MCP tool calls it" failing at the step the whole loop starts
+ * from.
+ *
+ * An intake source does two things, and the second is why `place_dispatch` cares:
+ *
+ *   1. It mints the webhook secret and names the URL GitHub must POST to, so issues from one
+ *      repository reach one project's queue.
+ *   2. It BINDS that project to a `repo_full_name` and a `base_branch`, which is where
+ *      `Loopctl.Delivery.DispatchPayload` reads the repository and trunk from. A project
+ *      bound to none is the `409 no_intake_source` refusal; bound to two, the `409
+ *      ambiguous_intake_source` one.
+ *
+ * ## THE SECRET IS NEVER RETURNED BY THESE TOOLS
+ *
+ * `POST /api/v1/intake/sources` returns `webhook_secret` ONCE. It cannot be re-read: the
+ * column is `Loopctl.Vault.Binary` with `redact: true` and is absent from the schema's
+ * `@derive {Jason.Encoder, only: [...]}` list (`lib/loopctl/intake/source.ex`), so neither
+ * the list nor the update response carries it. Lose it and the only remedy is to revoke the
+ * source, enrol again, and reconfigure the GitHub webhook.
+ *
+ * A tool result is JSON-stringified into the session transcript AND the audit log, so this
+ * follows what `runner_enroll` already does with the runner credential (`lib/runners.js`):
+ * `secret_file` is REQUIRED, the secret is written there with mode 0600, and the tool returns
+ * the source row, the webhook URL and the path. The secret reaches GitHub from the file —
+ * `config[secret]=$(cat <file>)` — so it never has to pass through a transcript at all.
+ *
+ * The file is RESERVED (`O_CREAT|O_EXCL`, 0600) before the API is called, so an existing path
+ * or an unwritable directory is refused while there is still nothing to lose. Every outcome
+ * that is not a clean 2xx of the expected shape withholds the response body, because a 2xx
+ * whose JSON failed to parse reaches this code as `{error: true, status: 201, body: "<first
+ * 200 characters of the raw text>"}` — which is the secret.
+ *
+ * ## WHERE THIS DIFFERS FROM `runner_enroll`
+ *
+ * The RECOVERY is the same: an outcome that is not a clean creation revokes the source when
+ * the response proved its id, since the secret cannot be re-read and an unusable source still
+ * holds the repository's unique slot.
+ *
+ * What is not the same is the fallback when no id was proved. `enrollRunner` scrapes the
+ * runner id out of an unparseable 2xx body, because a runner found by NAME alone might be an
+ * earlier, legitimate enrollment. An intake source needs no such scraping:
+ * `intake_sources_active_repo_uidx` is unique on `(tenant_id, lower(repo_full_name))` WHERE
+ * `revoked_at IS NULL` — CASE-INSENSITIVELY, because GitHub names are — so at most one ACTIVE
+ * source ever binds a repository however it was spelled, and `intake_source_list` identifies
+ * it exactly. That branch therefore names the pair of tools rather than guessing at an id.
+ *
+ * MATCH THAT LISTING CASE-INSENSITIVELY. The uniqueness folds case; the STORED value does not
+ * — the row keeps the spelling it was enrolled with — so a source enrolled as
+ * `MKREYMAN/loopctl` refuses a re-enrolment of `mkreyman/loopctl` with a 422 while a reader
+ * comparing the two exactly concludes there is nothing to revoke.
+ *
+ * A source whose secret nobody holds is also INERT rather than dangerous: no delivery can
+ * ever be signed for it, so every POST to its URL is refused `401 invalid_signature`. What it
+ * does cost is that unique slot — a second enrolment of the same repository is refused 422
+ * until it is revoked — which is why a write failure after a successful create revokes it
+ * here rather than leaving it.
+ *
+ * ## KEY
+ *
+ * `LOOPCTL_USER_KEY`, for all four, pinned exactly (`exactKey`) the way the `runner_*` family
+ * is. The controller mounts `RequireRole, role: :user` — the HIERARCHY form, so a
+ * `:superadmin` key would pass too and this package holds no such variable — plus
+ * `RequireHumanAnchor` on create/update/delete and `RequireUnlineagedCaller` on create
+ * (`lib/loopctl_web/controllers/intake_source_controller.ex:27-29`). That last one is why a
+ * global `LOOPCTL_API_KEY` must not stand in: creating a source MINTS A CREDENTIAL that
+ * belongs to no dispatch lineage, so a caller whose own key a dispatch minted is refused
+ * `403 api_key_mint_forbidden`, exactly as it is on `POST /api/v1/api_keys`.
+ *
+ * ## `repo_full_name` IS NOT SHAPE-CHECKED HERE, AND THAT IS A DECISION
+ *
+ * The server's refusal is a 422 naming the field with `must be owner/name`, which is
+ * unambiguous and needs no client to disambiguate it — unlike the UUID checks below, which
+ * exist because a malformed path id and an unknown one produce the SAME 404
+ * (the long comment over `uuid()` in `lib/delivery-loop.js` has the trace). Mirroring
+ * `Source.repo_format/0` here would put a second copy of that regex in a second language,
+ * free to drift, to catch a refusal the server already words better.
+ */
+
+import nodePath from "node:path";
+import os from "node:os";
+import defaultFs from "node:fs/promises";
+
+import { uuid as uuidRefusal } from "./delivery-loop.js";
+import { expandHome, TOKEN_DIR_MODE, TOKEN_FILE_FLAGS, TOKEN_FILE_MODE } from "./runners.js";
+
+export const SOURCES_PATH = "/api/v1/intake/sources";
+
+const MISSING_USER_KEY =
+  "No user-role API key configured. Set LOOPCTL_USER_KEY to a user-role key to use the " +
+  "intake-source tools (intake_source_enroll, intake_source_list, intake_source_update, " +
+  "intake_source_revoke). The create path additionally requires a key NO DISPATCH MINTED — " +
+  "it mints the webhook secret, which belongs to no lineage — so an ephemeral dispatch key " +
+  "is refused 403 api_key_mint_forbidden however privileged it is.";
+
+function refuse(body) {
+  return { error: true, status: 0, body };
+}
+
+/**
+ * `target_epic_id` when the caller sent SOMETHING for it — the shared `uuid()` check, except
+ * for a blank value.
+ *
+ * `uuid()` answers "`target_epic_id` is required" for an empty or blank string, which is the
+ * OPPOSITE of the truth for this field: it is optional everywhere it appears. A caller that
+ * has read "an explicit null CLEARS it" and cannot emit a JSON null — a model filling a
+ * `type: "string"` schema — sends `""` to mean the clear, is told the optional field is
+ * required, and its likeliest next move is to invent an epic id, which is a WRONG epic rather
+ * than a refused call.
+ *
+ * A blank is refused rather than TAKEN AS the clear, and the asymmetry is deliberate: on
+ * update, clearing is a real mutation that returns the source to escalating every report to a
+ * human, and `""` is equally consistent with a caller whose variable was empty by accident.
+ * On enrol, accepting it would silently produce the source with no epic that this tool's own
+ * description warns is not a neutral default. Both cases refuse and name the remedy.
+ */
+function epicRefusal(value, { clearable }) {
+  if (typeof value === "string" && value.trim() === "") {
+    return refuse(
+      "`target_epic_id` is OPTIONAL, and an empty string is not how to say so. " +
+        (clearable
+          ? "Send null to CLEAR the epic (which returns the source to escalating every report " +
+            "to a human), or leave the field out entirely to leave it exactly as it is."
+          : "Leave the field out entirely, which enrols the source with no epic — every " +
+            "report from it is then escalated to a human until intake_source_update names " +
+            "one.") +
+        " Otherwise send the epic's UUID.",
+    );
+  }
+
+  return uuidRefusal(value, "target_epic_id");
+}
+
+export function sourcePath(sourceId) {
+  return `${SOURCES_PATH}/${encodeURIComponent(sourceId)}`;
+}
+
+/**
+ * The source fields this client will put in a tool result, named one by one.
+ *
+ * AN ALLOWLIST IN THIS PROCESS, not a restatement of the server's. Every tool result is
+ * JSON-stringified into the session transcript and into `~/.claude/audit/`, so echoing the
+ * server's object verbatim would rest this module's headline property — the webhook secret
+ * never enters a transcript — entirely on `@derive {Jason.Encoder, only: [...]}` in
+ * `lib/loopctl/intake/source.ex` continuing to exclude it. One commit adding `:webhook_secret`
+ * back to that list, or adding a field derived from it, would carry it into every transcript
+ * from then on with nothing here to stop it. `enrollRunner` reshapes its response for exactly
+ * this reason (`lib/runners.js`), and this is the same defence.
+ *
+ * The cost is that a genuinely new server field is invisible until this list names it. That is
+ * the intended direction of the failure: a missing field is a visible gap, a leaked secret is
+ * not.
+ */
+export function publicSource(source) {
+  if (!source || typeof source !== "object") return source;
+
+  return {
+    id: source.id,
+    project_id: source.project_id,
+    repo_full_name: source.repo_full_name,
+    base_branch: source.base_branch,
+    target_epic_id: source.target_epic_id,
+    revoked_at: source.revoked_at,
+    inserted_at: source.inserted_at,
+    updated_at: source.updated_at,
+  };
+}
+
+/**
+ * The absolute URL to configure on the GitHub webhook, from the `webhook_path` the server
+ * returned. The path is joined to the server this process is talking to, because a webhook
+ * pointed at a different host than the one holding the source is a delivery that can never
+ * authenticate.
+ */
+export function webhookUrl(baseUrl, webhookPath) {
+  const base = typeof baseUrl === "string" ? baseUrl.replace(/\/+$/, "") : "";
+  return `${base}${webhookPath}`;
+}
+
+/**
+ * `POST /api/v1/intake/sources` — bind a GitHub repository to a work project and write the
+ * webhook secret to `secret_file`, never returning it.
+ *
+ * Resolves to `{ source, webhook_url, secret_file }` or an `{ error: true, status, body }`
+ * shape. It never throws.
+ */
+export async function enrollIntakeSource(
+  { repo_full_name, project_id, target_epic_id, base_branch, secret_file } = {},
+  { userKey, apiCall, baseUrl, fs = defaultFs, homedir = os.homedir() } = {},
+) {
+  if (!userKey) return refuse(MISSING_USER_KEY);
+
+  if (typeof repo_full_name !== "string" || repo_full_name.trim() === "") {
+    return refuse(
+      "`repo_full_name` is required: the repository as `owner/name`, e.g. " +
+        "`mkreyman/home_care_billing`. Not a URL.",
+    );
+  }
+
+  const badProject = uuidRefusal(project_id, "project_id");
+  if (badProject) return badProject;
+
+  // OPTIONAL. Absent means the question has not been answered, and a report from a source
+  // that names no epic is ESCALATED to a human rather than landing in an epic chosen for it
+  // (`lib/loopctl/intake/source.ex`). An explicit null means the same thing on create.
+  if (target_epic_id !== undefined && target_epic_id !== null) {
+    const badEpic = epicRefusal(target_epic_id, { clearable: false });
+    if (badEpic) return badEpic;
+  }
+
+  // OPTIONAL, and read by PRESENCE at the server: omitted, the column takes its `master`
+  // default; named, the value is validated. There is no cleared state for it — every dispatch
+  // must name a branch to cut from — so a null or an empty string is a 422 there and is
+  // refused here, where the reason can be stated. This is the same shape `updateIntakeSource`
+  // refuses, and the two must not disagree about what a valid branch is.
+  if (base_branch !== undefined) {
+    if (typeof base_branch !== "string" || base_branch.trim() === "") {
+      return refuse(
+        "`base_branch` must be a non-empty branch name, or must be left out entirely. It " +
+          "cannot be null or blank: every dispatch for this repository is cut from it, so " +
+          "there is no cleared state for it and the server answers 422. Leave it out for " +
+          "`master`, or send `main` for a repository created on GitHub since 2020.",
+      );
+    }
+  }
+
+  if (typeof secret_file !== "string" || secret_file.trim() === "") {
+    return refuse(
+      "`secret_file` is required: the path the webhook secret is written to (mode 0600). " +
+        "The server returns that secret ONCE and it can never be read again, and a tool " +
+        "result lands in the session transcript and the audit log — so it is written to a " +
+        "file instead, and GitHub is configured from that file.",
+    );
+  }
+
+  const secretPath = expandHome(secret_file, homedir);
+  if (!nodePath.isAbsolute(secretPath)) {
+    return refuse(`secret_file must be absolute or start with ~/ (got '${secret_file}').`);
+  }
+
+  let handle;
+  try {
+    await fs.mkdir(nodePath.dirname(secretPath), { recursive: true, mode: TOKEN_DIR_MODE });
+    handle = await fs.open(secretPath, TOKEN_FILE_FLAGS, TOKEN_FILE_MODE);
+  } catch (err) {
+    if (err?.code === "EEXIST") {
+      return refuse(
+        `secret_file '${secretPath}' already exists; refusing to overwrite it. Nothing was ` +
+          "enrolled. Choose a new path, or remove the file yourself if its source is revoked.",
+      );
+    }
+    return refuse(
+      `Could not create secret_file '${secretPath}' (${err?.code || "error"}). Nothing was ` +
+        "enrolled.",
+    );
+  }
+
+  // The identity of the file this call created, taken BEFORE anything is written, so the file
+  // can still be told apart from a replacement if the handle later becomes unusable.
+  let opened;
+  try {
+    opened = await handle.stat();
+  } catch (err) {
+    await closeQuietly(handle);
+    return refuse(
+      `Could not stat the new secret_file '${secretPath}' (${err?.code || "error"}). Nothing ` +
+        "was enrolled; an empty file may remain at that path.",
+    );
+  }
+
+  const body = { repo_full_name, project_id };
+  if (target_epic_id !== undefined && target_epic_id !== null) {
+    body.target_epic_id = target_epic_id;
+  }
+  if (base_branch !== undefined) body.base_branch = base_branch;
+
+  let result;
+  try {
+    result = await apiCall("POST", SOURCES_PATH, body);
+  } catch {
+    result = { error: true, status: 0, body: "Intake-source request failed." };
+  }
+
+  // A 4xx is a refusal: nothing was committed, and its body is the server's error, which
+  // carries the code the caller needs. Pass it through as it came.
+  if (result && result.error === true && result.status >= 400 && result.status < 500) {
+    const removed = await discardReservation(fs, handle, secretPath, opened);
+    return removed ? result : { ...result, secret_file_not_removed: secretPath };
+  }
+
+  const source = result && result.error !== true ? result.source : undefined;
+  const secret = result && result.error !== true ? result.webhook_secret : undefined;
+  const webhookPath = result && result.error !== true ? result.webhook_path : undefined;
+
+  const sourceId =
+    source && typeof source.id === "string" && source.id !== "" ? source.id : undefined;
+  const sentPath = typeof webhookPath === "string" && webhookPath !== "" ? webhookPath : undefined;
+  const usableSecret = typeof secret === "string" && secret !== "";
+
+  // A 2xx carrying a usable source AND its secret but no `webhook_path` is RECOVERABLE, and
+  // discarding it throws away the one thing that cannot be recovered: the secret is returned
+  // once. The path is a pure function of the id — `/api/v1/intake/github/<id>`, the route this
+  // module's header names — so it is derived rather than lost. A FALLBACK only: what the
+  // server sent always wins, and the result says when the URL was derived, because a derived
+  // one is a claim this process is making and not something the server answered.
+  const derivedPath = sentPath === undefined && sourceId !== undefined;
+  const path = derivedPath ? `/api/v1/intake/github/${encodeURIComponent(sourceId)}` : sentPath;
+
+  if (!sourceId || !usableSecret || path === undefined) {
+    const removed = await discardReservation(fs, handle, secretPath, opened);
+    return ambiguousEnrollment(result, apiCall, sourceId, repo_full_name, secretPath, removed);
+  }
+
+  try {
+    await handle.writeFile(secret);
+    await handle.sync();
+    await handle.close();
+  } catch (err) {
+    const removed = await discardReservation(fs, handle, secretPath, opened);
+    const revoked = await revoke(apiCall, source.id);
+    return refuse(
+      `The intake source for '${repo_full_name}' (${source.id}) was created, but its webhook ` +
+        `secret could not be written to '${secretPath}' (${err?.code || "error"}). The secret ` +
+        "is returned once and cannot be re-read, so the source is unusable and " +
+        (revoked.ok
+          ? "was revoked. "
+          : `revoking it FAILED (${revoked.detail}); revoke it with intake_source_revoke ` +
+            `source_id ${source.id} — until you do, a second source for this repository is ` +
+            "refused 422. ") +
+        reservationOutcome(secretPath, removed),
+    );
+  }
+
+  return {
+    source: publicSource(source),
+    webhook_url: webhookUrl(baseUrl, path),
+    ...(derivedPath ? { webhook_url_derived: true } : {}),
+    secret_file: secretPath,
+  };
+}
+
+/**
+ * Every outcome that is neither a 4xx refusal nor a well-formed creation: a timeout, a
+ * network error, a 5xx from the edge after the commit, or a 2xx whose body did not parse or
+ * lacks the secret. NO RESPONSE BODY IS EVER ECHOED — a 2xx body that failed to parse is the
+ * creation itself, secret included, and `apiCall` puts its first 200 characters in `body`.
+ *
+ * WHEN THE RESPONSE PROVES AN ID, THE SOURCE IS REVOKED HERE, exactly as `enrollRunner` does:
+ * reaching this function means the secret cannot be relied on, so the source can never
+ * authenticate a delivery while still holding the repository's unique slot. Leaving that to
+ * the operator asked them to do by hand what this process could already prove and do itself.
+ *
+ * With NO id — an unparseable body, a timeout — the recovery names the tools instead, because
+ * it can: an ACTIVE source is unique per repository (`intake_sources_active_repo_uidx`), so
+ * the list identifies it exactly.
+ */
+async function ambiguousEnrollment(result, apiCall, sourceId, repoFullName, secretPath, removed) {
+  const status = result && Number.isInteger(result.status) ? result.status : undefined;
+
+  const what =
+    status === 0 && typeof result.body === "string"
+      ? `Intake-source outcome unknown (${result.body}).`
+      : `Intake-source outcome unknown (HTTP ${status ?? "?"}; response body withheld: it may ` +
+        "contain the webhook secret).";
+
+  let next;
+  if (sourceId) {
+    const revoked = await revoke(apiCall, sourceId);
+    next = revoked.ok
+      ? `The response identified source ${sourceId}; it was revoked, since its secret cannot ` +
+        "be recovered and an unusable source holds this repository's unique slot. Enrol again."
+      : `The response identified source ${sourceId}, but revoking it FAILED ` +
+        `(${revoked.detail}); revoke it with intake_source_revoke source_id ${sourceId} — ` +
+        "until you do, a second source for this repository is refused 422.";
+  } else {
+    next =
+      `A source for '${repoFullName}' may exist with a secret nobody holds — it can never ` +
+      "authenticate a delivery, and it holds that repository's unique slot, so a second " +
+      "enrolment is refused 422 until it is gone. Run intake_source_list, and revoke any " +
+      `active source whose repo_full_name equals '${repoFullName}' IGNORING CASE with ` +
+      "intake_source_revoke before enrolling again — the uniqueness is case-insensitive " +
+      "(`lower(repo_full_name)`) while the stored value keeps whatever spelling it was " +
+      "enrolled with, so an exact match can miss the row that is blocking you.";
+  }
+
+  return {
+    error: true,
+    status: status ?? 0,
+    body: `${what} ${next} ${reservationOutcome(secretPath, removed)}`,
+  };
+}
+
+/** `GET /api/v1/intake/sources`, optionally including revoked ones. */
+export async function listIntakeSources({ include_revoked } = {}, { userKey, apiCall } = {}) {
+  if (!userKey) return refuse(MISSING_USER_KEY);
+  const query = include_revoked ? "?include_revoked=true" : "";
+  const result = await apiCall("GET", `${SOURCES_PATH}${query}`, null);
+
+  // RESHAPED, for the reason in `publicSource`: a listing is the widest surface here — every
+  // source the tenant has, in one tool result — so a server-side widening of what a source
+  // serialises to would land in the transcript N times rather than once. An error passes
+  // through untouched; only the rows are named.
+  if (!result || result.error === true || !Array.isArray(result.sources)) return result;
+
+  return { ...result, sources: result.sources.map(publicSource) };
+}
+
+/**
+ * `PATCH /api/v1/intake/sources/:id` — set the epic triaged stories land in, and/or the
+ * branch dispatches for this repository are cut from.
+ *
+ * PRESENCE DECIDES, on both fields, and the controller reads it with `Map.fetch/2` — see
+ * `LoopctlWeb.IntakeSourceController.update/2` and its `put_if_present/4`: a field you do not
+ * send is left exactly as it was. So `undefined` here means "not named" and is omitted from
+ * the body. (Named by FUNCTION, not by line range: the range this cited rotted inside one PR,
+ * when that same PR added `base_branch` to `create/2` above it.)
+ *
+ * `target_epic_id: null` IS FORWARDED, because null is the endpoint's only way to clear the
+ * target and clearing it is a real operation — a source that names no epic escalates every
+ * report to a human instead of filing a story. That is the opposite of `update_story`, which
+ * refuses a null because the server would drop it and answer 200 having changed nothing
+ * (`lib/story-update.js`). The hazard is on the caller and the description says so in the
+ * imperative: do not send `target_epic_id: null` to mean "I am not changing this".
+ *
+ * `base_branch: null` is refused here. It is NOT nullable — every `implement` dispatch must
+ * name a branch to cut from, so there is no unanswered state for it — and the server's cast
+ * uses `empty_values: []` precisely so that a caller who SENT a value gets an answer about
+ * the value it sent, which is a 422.
+ */
+export async function updateIntakeSource(args = {}, { userKey, apiCall } = {}) {
+  if (!userKey) return refuse(MISSING_USER_KEY);
+
+  const bad = uuidRefusal(args.source_id, "source_id");
+  if (bad) return bad;
+
+  const body = {};
+
+  if (args.target_epic_id !== undefined) {
+    if (args.target_epic_id !== null) {
+      const badEpic = epicRefusal(args.target_epic_id, { clearable: true });
+      if (badEpic) return badEpic;
+    }
+    body.target_epic_id = args.target_epic_id;
+  }
+
+  if (args.base_branch !== undefined) {
+    if (args.base_branch === null) {
+      return refuse(
+        "`base_branch` cannot be null: every dispatch must name a branch to cut from, so " +
+          "there is no cleared state for it and the server answers 422. Send the branch you " +
+          "want (`master`, `main`, …), or leave the field out to keep the current one.",
+      );
+    }
+    body.base_branch = args.base_branch;
+  }
+
+  if (Object.keys(body).length === 0) {
+    return refuse(
+      "Nothing to update. Name at least one of `target_epic_id` (null clears it) or " +
+        "`base_branch`. A body carrying neither is refused 422 `nothing_to_update`, because a " +
+        "field you do not send is left exactly as it was.",
+    );
+  }
+
+  const result = await apiCall("PATCH", sourcePath(args.source_id), body);
+
+  if (!result || result.error === true || !result.source) return result;
+
+  return { ...result, source: publicSource(result.source) };
+}
+
+/**
+ * `DELETE /api/v1/intake/sources/:id` — REVOKE the source. The row is kept.
+ *
+ * Named for what it does rather than for its HTTP verb: `Loopctl.Intake.revoke_source/3` sets
+ * `revoked_at`, clears `target_epic_id` and appends an `intake_source_revoked` audit entry.
+ * Nothing is destroyed, deliveries already received are kept, and the row still comes back
+ * from `intake_source_list` with `include_revoked`.
+ */
+export async function revokeIntakeSource({ source_id } = {}, { userKey, apiCall } = {}) {
+  if (!userKey) return refuse(MISSING_USER_KEY);
+
+  const bad = uuidRefusal(source_id, "source_id");
+  if (bad) return bad;
+
+  const result = await apiCall("DELETE", sourcePath(source_id), null);
+
+  // The fourth path that carries a source object back, reshaped for the same reason as the
+  // other three. The reviewer named enrol, list and update; revoke returns the revoked row.
+  if (!result || result.error === true || !result.source) return result;
+
+  return { ...result, source: publicSource(result.source) };
+}
+
+async function revoke(apiCall, sourceId) {
+  try {
+    const result = await apiCall("DELETE", sourcePath(sourceId), null);
+    if (result && result.error) return { ok: false, detail: `status ${result.status}` };
+    return { ok: true };
+  } catch {
+    return { ok: false, detail: "request error" };
+  }
+}
+
+function reservationOutcome(secretPath, removed) {
+  return removed
+    ? `The secret_file '${secretPath}' was removed; the same path can be used again.`
+    : `The secret_file '${secretPath}' could NOT be removed: delete it before enrolling again ` +
+        "at that path.";
+}
+
+async function closeQuietly(handle) {
+  try {
+    await handle.close();
+  } catch {
+    // already closed, or the close is what failed
+  }
+}
+
+/**
+ * Close the handle and remove the file this call created. Removal is by path, so it first
+ * checks that the path still names the file identified by `opened`, the stat taken right
+ * after the open. Resolves to whether the path no longer holds that file.
+ */
+async function discardReservation(fs, handle, secretPath, opened) {
+  await closeQuietly(handle);
+
+  let current;
+  try {
+    current = await fs.lstat(secretPath);
+  } catch (err) {
+    return err?.code === "ENOENT";
+  }
+  if (current.ino !== opened.ino || current.dev !== opened.dev) return false;
+
+  try {
+    await fs.unlink(secretPath);
+    return true;
+  } catch (err) {
+    return err?.code === "ENOENT";
+  }
+}

package/package.json

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