loopctl-mcp-server 3.0.0 → 3.2.0

package/README.md

@@ -527,12 +527,13 @@ The order to wire it up, the stage machine these tools move a story through, and
 | `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`. `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 it 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. 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. 409 `runner_exhausted` when the machine's subscription (its own, or one it shares an account with) is exhausted — also refused before the mint, and the body carries `usage_exhausted_until`, when it clears on its own. 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, and a retry naming a different `base_branch` from the recorded one is 422 `base_branch_conflict`, because the merge gate judges against the recorded base. 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 `pending` or `contracted` (a pending one is contracted by the placement), its dependencies met, with its stage at `queued`. A retry also moves the claim's deadline to now + its `wall_clock_seconds` + `DISPATCH_LEASE_GRACE_SECONDS` (never earlier than the one already sent), and 409 `dispatch_claim_ended` means the claim that `dispatch_id` was placed under has ended — nothing was pushed or written; place again with a new `dispatch_id`. 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`. |
+| `change_binding_get` | **The chg changes bound to a story** (`GET /api/v1/stories/:id/changes`, loopctl US-47.7): every change a chg `submitted` event bound to the story, OLDEST FIRST so the current one is last, each with `repo`, `change_id`, `current`, `superseded_at`, `submitter_not_claimant`, `inserted_at`, and its APPLIED events in `event_seq` order (`event_seq`, `kind`, `revision`, `sha`, `occurred_at`, `applied_at`; never the event `data` payload). Bounded by the server, bounds in `meta` (`max_bindings`, `max_events_per_change`): the newest of each are kept, so the current binding is always listed, and `binding_count` / `applied_event_count` / `events_truncated` say when more exist. Any tenant key reads it (`role: :agent` with the hierarchy), so nothing is pinned: `LOOPCTL_API_KEY` when set, else `LOOPCTL_AGENT_KEY`, else `LOOPCTL_ORCH_KEY`. 404 when the story is not your tenant's — another tenant's id answers exactly like an unknown one; 401 without a valid key; 400 for a superadmin key without `X-Impersonate-Tenant`; no role is refused. Required: `story_id` (refused locally if not a UUID). |
 | `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`. **A delivery story then goes to `escalated`, not back to the queue** (loopctl US-44.4): an operator taking a story back is a human decision, so a release that leaves the stage row at `queued` escalates it over `operator_released` in the same transaction, spending no attempt against the retry ceiling — it is not left in the queue behind the human's back. Put it back to work with `resolve_escalation` `to: queued`, which releases (a no-op by then) AND re-contracts. A story with no delivery stage row is simply left `pending`. A story parked at `claimed` with nobody on it is the residue of a compensation that did not complete, not what a refused dispatch normally leaves: placement releases the claim inline when a runner refuses, and the claim lease releases it unattended once `claimed_until` passes — reach for this to get it back now, or when both of those left it held. Requeues from any stage a claim holds; a stage no claim holds keeps its stage and is rebound to the new epoch; `done` and `failed` are untouched. For an ESCALATED story use `resolve_escalation` instead — that one releases AND re-contracts, so its `queued` really is placeable. Requires an orchestrator-ROLE key: the action is `exact_role: :orchestrator`, so a user or superadmin key is 403'd like any other non-member. Put it in `LOOPCTL_ORCH_KEY` (which is then the key sent, and a global `LOOPCTL_API_KEY` does not displace it) or, with no orchestrator key set, in `LOOPCTL_API_KEY`. The orchestrator key must be linked to a registered agent (400 otherwise) and the tenant must be human-anchored (403 `custody_tier_required` otherwise). Does not touch `verified_status`. Run again on an already-pending story it is still an operator's release: a row stranded behind the story's claim epoch is rebound, an in-flight row is requeued, and a row then at `queued` — including one already sitting there — is escalated over `operator_released`, as on the first run; a row already escalated, or anywhere else at that epoch, is left alone. Every 500 means the whole release rolled back and the story is still claimed: `audit_chain_append_failed` (the escalation's chain entry was refused) is a server-side condition a re-run meets again until an operator acts; `force_unclaim_failed` (the server log names the step) — call it again. A 422 means the release write itself was rejected. No request body. Required: `story_id` (refused locally if it is not a UUID). |
-| `merge_precondition` | **Run the merge gate over a story's real pull request** (`POST /api/v1/stories/:id/merge-precondition`). Both delivery gates run again over the diff that exists, plus custody, the 12-file / 1000-line hard bound, the head-has-not-moved check and the self-deploy exclusion; the story must be at stage `ci`. **Gate A reads what triage persisted, never the caller**: the lens verdicts recorded with the story's most recent triage, or a human's re-queue of a Gate A escalation — `gate_a_inputs` on the answer says which, and `missing` refuses with `gate_a_inputs_missing`. This tool sends no trio. Decisions: `allow` (recorded against the head; the only thing that licenses a merge), `refuse` (the story is escalated before this returns), `already_merged`, `head_moved`, `unevaluated` (503 with `Retry-After`). Requires an orchestrator- or user-ROLE key (`exact_role: [:orchestrator, :user]`, so an agent key is 403'd); `LOOPCTL_ORCH_KEY` is sent when set, else `LOOPCTL_API_KEY`. 403 `custody_tier_required` without a human anchor, 404 for an unknown story, 422 when the story is not at `ci`. Required: `story_id` (refused locally if not a UUID) and `claim_epoch` (a non-negative integer, refused locally otherwise); optional `effect_proof`. |
-| `intake_source_enroll` | **Bind a GitHub repository to a work project and mint its webhook secret** (`POST /api/v1/intake/sources`) — the step that gives the delivery loop an input, and the row `place_dispatch` reads `repo` and `base_branch` from (its 409 `no_intake_source` means this has not been done; 409 `ambiguous_intake_source` means it has been done twice). **The secret is returned ONCE and can never be read again** — the column is encrypted at rest and redacted on the schema, so no other tool carries it and losing it costs a revoke, a re-enrolment and a reconfigured GitHub webhook. **This tool does not return it either:** a tool result lands in the transcript and the audit log, so it is written to the required `secret_file` with mode 0600 (the handling `runner_enroll` gives a runner credential) and the result carries the source row, the `webhook_url` and that path. The path is reserved before the request, so an existing file or an unwritable directory is refused with nothing enrolled, and any outcome that is not a clean creation withholds the response body — an unparsed 2xx body IS the secret. A 2xx carrying the source and the secret but no webhook path is RECOVERED rather than discarded (the path is derived from the source id, flagged `webhook_url_derived`), and an outcome that proves a source id but no usable secret REVOKES that source rather than leaving it holding the repository's unique slot. Then configure GitHub: Payload URL = the returned `webhook_url`, content type `application/json`, Secret = the contents of the file, and the **Issues** event only — `gh api repos/OWNER/REPO/hooks -f name=web -f config[url]=<webhook_url> -f config[content_type]=json -f config[secret]="$(cat <secret_file>)" -f 'events[]=issues'`. Every later delivery failure is the SAME 401 `invalid_signature` — unknown or revoked source, suspended tenant, missing or wrong signature, or a payload whose `repository.full_name` does not match — so the webhook's Recent Deliveries tab cannot tell you which. `base_branch` is set HERE: it defaults to `master` when the body does not name it, so name `main` for a repository created on GitHub since 2020 or every dispatch is cut from a trunk that does not exist. It is not nullable (a dispatch must name a branch), so null or blank is refused rather than falling back to the default, and `intake_source_update` changes it afterwards. Refusals: 403 `api_key_mint_forbidden` if your key was minted by a dispatch (this mints a credential belonging to no lineage, so only an unlineaged operator key may), 403 `custody_tier_required` on an agent-rooted tenant, 422 for a repository that is not `owner/name`, an ACTIVE source already binding it, a project that is missing / archived / not a work project, or a `target_epic_id` outside that project. `mode` is the merge route: `pr` (the default when omitted) is the only one; any other value, null included, is refused. The mode is bound to each implement dispatch when it is placed, so it decides only what stories placed afterwards get; a change is always allowed. `required_checks` are the CI checks story verification judges a story's commit by, GitHub Actions job names, bounded in number and length by the server; `local-gate` is refused because whoever pushed posts it. Story verification judges a story's commit against the same `required_checks` in EITHER mode, satisfied only by a job of a push run of the story's branch; it first needs a GitHub credential for this tenant, its own token (`set_github_credential`) or an entry in the operator's `VERIFICATION_OPERATOR_TOKEN_TENANTS` (`credential_unavailable` otherwise, whatever the list holds); then a `pr` source that names none records `no_required_checks` and reads nothing, so naming them is how a pr source opts in, and a source that names some has its (tenant, repository) credential resolved before any GitHub read (`credential_unavailable` if there is none). Required: `repo_full_name`, `project_id`, `secret_file`. Optional: `base_branch`, `mode`, `required_checks`, and `target_epic_id` — **omitting the epic is not a neutral default**: with no epic every triaged report is escalated to a human and every record stays `pending_triage` until `intake_source_update` names one. Requires `LOOPCTL_USER_KEY`. |
-| `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`, `mode` (`pr`), `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, `base_branch`, the branch every dispatch for this repository is cut from, `mode` (`pr`, the only merge route), and `required_checks`, the checks story verification judges a story's commit by — once the tenant has a GitHub credential, its own token (`set_github_credential`) or an entry in the operator's `VERIFICATION_OPERATOR_TOKEN_TENANTS` (`credential_unavailable` otherwise), a source naming none records `no_required_checks` and reads nothing, and one naming some has its (tenant, repository) credential resolved before any GitHub read (`local-gate` is refused). Presence decides — a field you do not name is left exactly as it was, and naming none of them is 422 `nothing_to_update`. `mode` has no cleared state either, and a null or unknown value is refused locally; A change is always allowed and affects only stories placed afterwards: each implement dispatch records the mode, and the base branch, it was placed under, and the merge gate reads those. **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. |
+| `merge_precondition` | **Run the merge gate over a story's real pull request** (`POST /api/v1/stories/:id/merge-precondition`). Both delivery gates run again over the diff that exists, plus custody, the 12-file / 1000-line hard bound, the head-has-not-moved check and the self-deploy exclusion; the story must be at stage `ci`. **Gate A reads what triage persisted, never the caller**: the lens verdicts recorded with the story's most recent triage, or a human's re-queue of a Gate A escalation — `gate_a_inputs` on the answer says which, and `missing` refuses with `gate_a_inputs_missing`. This tool sends no trio. Decisions: `allow` (recorded against the head; the only thing that licenses a merge), `refuse` (the story is escalated before this returns), `already_merged`, `head_moved`, `unevaluated` (503 with `Retry-After`). Requires an orchestrator- or user-ROLE key (`exact_role: [:orchestrator, :user]`, so an agent key is 403'd); `LOOPCTL_ORCH_KEY` is sent when set, else `LOOPCTL_API_KEY`. 403 `custody_tier_required` without a human anchor, 404 for an unknown story, 409 `change_protocol_enrolled` when the story's intake source is in mode `chg` (the PR route is closed; land with `chg submit` — decided before any GitHub read, nothing escalated), 422 when the story is not at `ci`. Required: `story_id` (refused locally if not a UUID) and `claim_epoch` (a non-negative integer, refused locally otherwise); optional `effect_proof`. |
+| `intake_source_enroll` | **Bind a GitHub repository to a work project and mint its webhook secret** (`POST /api/v1/intake/sources`) — the step that gives the delivery loop an input, and the row `place_dispatch` reads `repo` and `base_branch` from (its 409 `no_intake_source` means this has not been done; 409 `ambiguous_intake_source` means it has been done twice). **The secret is returned ONCE and can never be read again** — the column is encrypted at rest and redacted on the schema, so no other tool carries it and losing it costs a revoke, a re-enrolment and a reconfigured GitHub webhook. **This tool does not return it either:** a tool result lands in the transcript and the audit log, so it is written to the required `secret_file` with mode 0600 (the handling `runner_enroll` gives a runner credential) and the result carries the source row, the `webhook_url` and that path. The path is reserved before the request, so an existing file or an unwritable directory is refused with nothing enrolled, and any outcome that is not a clean creation withholds the response body — an unparsed 2xx body IS the secret. A 2xx carrying the source and the secret but no webhook path is RECOVERED rather than discarded (the path is derived from the source id, flagged `webhook_url_derived`), and an outcome that proves a source id but no usable secret REVOKES that source rather than leaving it holding the repository's unique slot. Then configure GitHub: Payload URL = the returned `webhook_url`, content type `application/json`, Secret = the contents of the file, and the **Issues** event only — `gh api repos/OWNER/REPO/hooks -f name=web -f config[url]=<webhook_url> -f config[content_type]=json -f config[secret]="$(cat <secret_file>)" -f 'events[]=issues'`. Every later delivery failure is the SAME 401 `invalid_signature` — unknown or revoked source, suspended tenant, missing or wrong signature, or a payload whose `repository.full_name` does not match — so the webhook's Recent Deliveries tab cannot tell you which. `base_branch` is set HERE: it defaults to `master` when the body does not name it, so name `main` for a repository created on GitHub since 2020 or every dispatch is cut from a trunk that does not exist. It is not nullable (a dispatch must name a branch), so null or blank is refused rather than falling back to the default, and `intake_source_update` changes it afterwards. Refusals: 403 `api_key_mint_forbidden` if your key was minted by a dispatch (this mints a credential belonging to no lineage, so only an unlineaged operator key may), 403 `custody_tier_required` on an agent-rooted tenant, 422 for a repository that is not `owner/name`, an ACTIVE source already binding it, a project that is missing / archived / not a work project, or a `target_epic_id` outside that project. `mode` is the merge route: `pr` (the default when omitted; the merge gate reads a pull request) or `chg` (Epic 47: the change protocol lands the repository's changes with `chg submit`, and `merge_precondition` refuses every story on the source with 409 `change_protocol_enrolled`); any other value, null included, is refused. A `chg` enrolment needs `change_events_secret` (or, preferred, `change_events_secret_file`, a path the tool reads so the value never enters the transcript) AND `chg_root_dispatch_id` in the same call — refused locally and 422 at the server without them — and a root that is not a parentless, unrevoked, orchestrator-role dispatch of this tenant is 422 `chg_root_invalid` (a child, a revoked or agent-role dispatch, another tenant's and an unknown id all alike). The change-events secret is write-only: no response and no tool result ever carries it. `required_checks` are the CI checks story verification judges a story's commit by, GitHub Actions job names, bounded in number and length by the server; `local-gate` is refused because whoever pushed posts it. Story verification judges a story's commit against the same `required_checks` in EITHER mode, satisfied only by a job of a push run of the story's branch; it first needs a GitHub credential for this tenant, its own token (`set_github_credential`) or an entry in the operator's `VERIFICATION_OPERATOR_TOKEN_TENANTS` (`credential_unavailable` otherwise, whatever the list holds); then a `pr` source that names none records `no_required_checks` and reads nothing, so naming them is how a pr source opts in, and a source that names some has its (tenant, repository) credential resolved before any GitHub read (`credential_unavailable` if there is none). Required: `repo_full_name`, `project_id`, `secret_file`. Optional: `base_branch`, `mode`, `required_checks`, `change_events_secret` / `change_events_secret_file`, `chg_root_dispatch_id`, 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`, `mode` (`pr` or `chg`), `chg_root_dispatch_id`, `target_epic_id`, `revoked_at`, timestamps. **The webhook secret is not here and is not anywhere**, and neither is a `chg` source's change-events secret — 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, `base_branch`, the branch every dispatch for this repository is cut from, `mode` (`pr` or `chg`), a `chg` source's `change_events_secret` / `change_events_secret_file` and `chg_root_dispatch_id`, and `required_checks`, the checks story verification judges a story's commit by — once the tenant has a GitHub credential, its own token (`set_github_credential`) or an entry in the operator's `VERIFICATION_OPERATOR_TOKEN_TENANTS` (`credential_unavailable` otherwise), a source naming none records `no_required_checks` and reads nothing, and one naming some has its (tenant, repository) credential resolved before any GitHub read (`local-gate` is refused). Presence decides — a field you do not name is left exactly as it was, and naming none of them is 422 `nothing_to_update`. `mode` has no cleared state either, and a null or unknown value is refused locally. Each implement dispatch records the base branch it was placed under, and the merge gate reads that; `mode` is not bound that way — the gate reads the source's current mode. **Switching to `chg` closes the PR route for every story on the source at once** (409 `change_protocol_enrolled`; land with `chg submit`), and the switch itself is 409 `pr_route_in_flight`, naming `story_ids`, while a story of the project sits at `ci` holding a merge allow it has not merged on. The resulting source must carry both credentials, named here or kept from an earlier `chg` stint (422 naming the missing one), and the root is re-checked on every write that leaves the source `chg`, a secret rotation or a base-branch edit included (422 `chg_root_invalid`; switching to `pr` is never blocked by it). Switching to `pr` KEEPS both and ignores them; on a `pr` source an explicit null clears either, on a `chg` source it is a 422. Naming either credential, or setting `mode` to `chg` (which re-activates the kept ones), needs the tenant's operator key, one no dispatch minted (403 `chg_registration_forbidden` otherwise — a key minted by a dispatch beneath yours is refused the same way), and the secret never comes back. **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

@@ -70,6 +70,7 @@ import {
 } from "./lib/intake-sources.js";
 import { mcpVersion as mcpVersionRequest, packageVersion } from "./lib/mcp-version.js";
 import { revokeDispatch as revokeDispatchRequest } from "./lib/dispatch-revoke.js";
+import { changeBindingGet as changeBindingGetRequest } from "./lib/change-bindings.js";
 import {
   clearGithubCredential as clearGithubCredentialRequest,
   githubCredential as githubCredentialRequest,
@@ -3432,6 +3433,22 @@ async function storyStage(args) {
   );
 }
 
+// US-47.7: a READ, `role: :agent` with the hierarchy, so any role's key clears the gate and
+// nothing is pinned. LOOPCTL_AGENT_KEY is passed as this tool's own key for the reason
+// storyStage gives above — `resolveKey` never reads it by name, and a session on an
+// agent-key-only config is exactly the one asking which change its story is bound to. It is an
+// OVERRIDE, not `exactKey`, so `resolveKey`'s order holds: LOOPCTL_API_KEY when set, else
+// LOOPCTL_AGENT_KEY, else LOOPCTL_ORCH_KEY.
+async function changeBindingGet(args) {
+  const key = process.env.LOOPCTL_AGENT_KEY;
+
+  return toContent(
+    await changeBindingGetRequest(args, {
+      apiCall: (method, path, body) => apiCall(method, path, body, key),
+    }),
+  );
+}
+
 async function resolveEscalation(args) {
   return toContent(await resolveEscalationRequest(args, deliveryDeps()));
 }
@@ -8614,6 +8631,34 @@ const TOOLS = [
       required: ["story_id"],
     },
   },
+  {
+    name: "change_binding_get",
+    description:
+      "THE CHG CHANGES BOUND TO A STORY (GET /api/v1/stories/:id/changes, loopctl US-47.7): " +
+      "every change a `submitted` chg event bound to the story, OLDEST FIRST so the current " +
+      "one is last, each with `repo`, `change_id`, `current`, `superseded_at`, " +
+      "`submitter_not_claimant` and `inserted_at`, plus that change's APPLIED events in " +
+      "`event_seq` order (`event_seq`, `kind`, `revision`, `sha`, `occurred_at`, " +
+      "`applied_at`). An event held ahead of a gap is not listed, and the event `data` " +
+      "payload is never returned.\n\n" +
+      "BOUNDED by the server, and the bounds are in `meta`: at most `max_bindings` bindings " +
+      "and `max_events_per_change` events per change, the NEWEST of each, so the current " +
+      "binding is always listed. `binding_count` and each binding's `applied_event_count` / " +
+      "`events_truncated` say when more exist.\n\n" +
+      "Any key of the tenant may read it (`role: :agent` with the hierarchy), so the key is " +
+      "the usual order with LOOPCTL_AGENT_KEY as this tool's own: LOOPCTL_API_KEY when set, " +
+      "else LOOPCTL_AGENT_KEY, else LOOPCTL_ORCH_KEY. REFUSES: 404 when the story " +
+      "is not your tenant's — another tenant's id answers exactly like an unknown one; 401 " +
+      "for no key or one that does not authenticate; 400 for a superadmin key without " +
+      "X-Impersonate-Tenant; 429 when rate limited. No 403: every key role clears the " +
+      "`role: :agent` gate, so none is refused for its role. A malformed " +
+      "`story_id` is refused locally (status 0, nothing sent).",
+    inputSchema: {
+      type: "object",
+      properties: { story_id: { type: "string", description: "The story UUID." } },
+      required: ["story_id"],
+    },
+  },
   {
     name: "resolve_escalation",
     description:
@@ -8661,7 +8706,10 @@ const TOOLS = [
       "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` " +
+      "404 for an unknown story, 409 `change_protocol_enrolled` when the story's intake source " +
+      "is in mode `chg` (the PR route is closed for that repository — land the change with " +
+      "`chg submit`; decided before the stage check and any GitHub read, and nothing is " +
+      "escalated), 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: {
@@ -8792,8 +8840,15 @@ const TOOLS = [
       "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.\n\n" +
-      "`mode` is the merge route, and `pr` (the default) is the only one: the merge gate reads " +
-      "a pull request by number. Any other value, null included, is refused.",
+      "`mode` is the merge route. `pr` (the default): the merge gate reads a pull request by " +
+      "number. `chg` (Epic 47): the change protocol lands the repository's changes with " +
+      "`chg submit`, and merge_precondition refuses every story on the source with 409 " +
+      "`change_protocol_enrolled`. A `chg` enrolment needs `change_events_secret` (or " +
+      "`change_events_secret_file`) AND `chg_root_dispatch_id` in the same call — refused " +
+      "here, and 422 at the server, without them — and a root that is not a parentless, " +
+      "unrevoked, orchestrator-role dispatch of this tenant is 422 `chg_root_invalid`. The " +
+      "change-events secret is write-only: no response and no tool result ever carries it. " +
+      "Any other mode, null included, is refused.",
     inputSchema: {
       type: "object",
       properties: {
@@ -8832,10 +8887,37 @@ const TOOLS = [
         },
         mode: {
           type: "string",
-          enum: ["pr"],
+          enum: ["pr", "chg"],
           description:
-            "Optional. How this repository's changes reach its base branch: `pr`, the default " +
-            "and only value — the merge gate reads a pull request by number. Not nullable.",
+            "Optional. How this repository's changes reach its base branch: `pr` (the " +
+            "default; the merge gate reads a pull request by number) or `chg` (the change " +
+            "protocol lands them and the PR route is closed, 409 `change_protocol_enrolled`; " +
+            "needs the two fields below). Not nullable.",
+        },
+        change_events_secret: {
+          type: "string",
+          description:
+            "WRITE-ONLY; required with `mode: chg`. The HMAC key chg-server signs its event " +
+            "webhook with (POST /api/v1/change_events/:source_id); chg-server must hold the " +
+            "same value. 32-256 bytes (422 otherwise). Encrypted at rest and NEVER returned by " +
+            "any response or tool result. A tool input lands in the transcript, so prefer " +
+            "`change_events_secret_file`. Not GitHub's webhook secret.",
+        },
+        change_events_secret_file: {
+          type: "string",
+          description:
+            "Alternative to `change_events_secret`, and the preferred one: an absolute (or " +
+            "`~/`) path the tool READS the secret from, so the value never passes through the " +
+            "transcript. One trailing newline is stripped. Not both.",
+        },
+        chg_root_dispatch_id: {
+          type: "string",
+          description:
+            "Required with `mode: chg`. The dispatch (UUID) chg-server's key was minted from: " +
+            "a PARENTLESS, UNREVOKED, ORCHESTRATOR-role dispatch of this tenant, minted by the " +
+            "operator key with `dispatch` and no parent. Anything else — a child, a revoked " +
+            "or agent-role dispatch, another tenant's or an unknown id — is refused 422 " +
+            "`chg_root_invalid`, all alike.",
         },
         required_checks: {
           type: "array",
@@ -8868,10 +8950,12 @@ const TOOLS = [
     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`, `mode` (`pr`), `target_epic_id`, `revoked_at` and " +
+      "`base_branch`, `mode` (`pr` or `chg`), `chg_root_dispatch_id`, `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 " +
+      "THE WEBHOOK SECRET IS NOT HERE AND IS NOT ANYWHERE, and neither is a `chg` source's " +
+      "change-events secret, which is never returned at all. The webhook secret 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 " +
@@ -8894,19 +8978,36 @@ const TOOLS = [
     description:
       "SET WHERE A SOURCE'S WORK LANDS (PATCH /api/v1/intake/sources/:id): `target_epic_id`, " +
       "the epic triaged stories are created in, `base_branch`, the branch every dispatch " +
-      "for this repository is cut FROM and carries, and `mode`, the merge route (`pr`, the " +
-      "only one).\n\n" +
+      "for this repository is cut FROM and carries, `mode`, the merge route (`pr` or `chg`), " +
+      "and a `chg` source's `change_events_secret` and `chg_root_dispatch_id`.\n\n" +
       "PRESENCE DECIDES, AND A FIELD YOU DO NOT NAME IS LEFT EXACTLY AS IT WAS. Naming " +
       "none of them 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` and `mode` have no cleared state at all, so a null there is refused. " +
-      "The mode is BOUND to each implement dispatch when it is placed: a change affects " +
-      "only stories placed afterwards, and a story already placed keeps the mode its " +
-      "dispatch recorded, so a change is always allowed. `base_branch` is bound the same " +
-      "way: a story already placed is merge-gated against the base branch its dispatch " +
-      "was sent with.\n\n" +
+      "`base_branch` is BOUND to each implement dispatch when it is placed: a story already " +
+      "placed is merge-gated against the base branch its dispatch was sent with. `mode` is " +
+      "NOT bound that way: the merge gate reads the source's current mode.\n\n" +
+      "SWITCHING TO `chg` closes the PR route for EVERY story on the source at once: " +
+      "merge_precondition reads the source's current mode and answers 409 " +
+      "`change_protocol_enrolled` (land with `chg submit`). The switch is itself refused 409 " +
+      "`pr_route_in_flight`, with the `story_ids`, while any story of the project sits at " +
+      "`ci` holding a merge allow it has not merged on: merge those (or let the gate escalate " +
+      "them) and retry. The resulting source must carry " +
+      "BOTH `change_events_secret` and `chg_root_dispatch_id`, named here or kept from an " +
+      "earlier `chg` stint (422 naming the missing one), and the root is re-checked on EVERY " +
+      "write that leaves the source `chg` — a secret rotation or a base-branch edit included " +
+      "— and whenever one is named (422 `chg_root_invalid` unless it is a parentless, " +
+      "unrevoked, orchestrator-role dispatch of this tenant; a revoked root blocks every such " +
+      "write until a live one is named, while switching to `pr` is never blocked). Switching " +
+      "to `pr` KEEPS both and ignores " +
+      "them; on a `pr` source an explicit null clears either, and on a `chg` source a null is " +
+      "a 422. Naming either credential, or setting `mode` to `chg` (which re-activates the " +
+      "kept ones), needs the tenant's operator key — a user-role key NO DISPATCH MINTED — " +
+      "and anything else is 403 `chg_registration_forbidden`; a key minted by a dispatch " +
+      "beneath yours is refused the same way. The secret is write-only and " +
+      "never comes back.\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 " +
@@ -8943,10 +9044,33 @@ const TOOLS = [
         },
         mode: {
           type: "string",
-          enum: ["pr"],
+          enum: ["pr", "chg"],
           description:
-            "`pr`, the only merge route: the merge gate reads a pull request. Not nullable. " +
-            "Omit to leave the current value alone.",
+            "`pr` (the merge gate reads a pull request) or `chg` (the change protocol lands " +
+            "changes; the PR route is closed). Not nullable. Omit to leave the current value " +
+            "alone.",
+        },
+        change_events_secret: {
+          type: ["string", "null"],
+          description:
+            "WRITE-ONLY. The HMAC key chg-server signs its event webhook with, 32-256 bytes; " +
+            "never returned. Null clears it on a `pr` source (422 on a `chg` one). Prefer " +
+            "`change_events_secret_file`. Omit to leave it alone.",
+        },
+        change_events_secret_file: {
+          type: "string",
+          description:
+            "Alternative to `change_events_secret`: an absolute (or `~/`) path the tool reads " +
+            "the secret from, so it never passes through the transcript. One trailing newline " +
+            "is stripped. Not both.",
+        },
+        chg_root_dispatch_id: {
+          type: ["string", "null"],
+          description:
+            "The parentless, unrevoked, orchestrator-role dispatch of this tenant chg-server's " +
+            "key was minted from; anything else is 422 `chg_root_invalid`, and the root a `chg` " +
+            "source keeps is re-checked on every write to it. Null clears it on a " +
+            "`pr` source (422 on a `chg` one). Omit to leave it alone.",
         },
         required_checks: {
           type: "array",
@@ -10066,6 +10190,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     case "story_stage":
       return await storyStage(args);
 
+    case "change_binding_get":
+      return await changeBindingGet(args);
+
     case "resolve_escalation":
       return await resolveEscalation(args);
 

package/lib/change-bindings.js

@@ -0,0 +1,47 @@
+/**
+ * `change_binding_get` — `GET /api/v1/stories/:id/changes` (loopctl US-47.7, Epic 47).
+ *
+ * A story in a `chg`-mode repository is landed by the change protocol: chg-server delivers
+ * the change's events to loopctl, and a `submitted` event binds the change to the story. This
+ * is the read of that join — the session orchestrating the loop holds a story id and needs to
+ * see which change implements it and how far that change has got.
+ *
+ * ## What the endpoint answers
+ *
+ * The story's bindings OLDEST FIRST (the current one is last), each with `repo`,
+ * `change_id`, `current`, `superseded_at`, `submitter_not_claimant`, `inserted_at`, and its
+ * change's APPLIED events in `event_seq` order (`event_seq`, `kind`, `revision`, `sha`,
+ * `occurred_at`, `applied_at`). Both lists are bounded by the server and the bounds are in the
+ * response's `meta`: a truncated list keeps the NEWEST entries, `binding_count` and each
+ * binding's `applied_event_count` / `events_truncated` say when more exist. The event `data`
+ * payload is not returned.
+ *
+ * ## Refusals
+ *
+ * - `404` — the story is not the caller's tenant's. Another tenant's id answers EXACTLY like
+ *   an id nobody issued; that is the isolation working, not a lookup failure to retry.
+ * - `401` — no key, or one that does not authenticate.
+ * - `400` — a superadmin key without `X-Impersonate-Tenant`.
+ * - `429` — rate limited.
+ *
+ * There is NO 403: the endpoint is `role: :agent` WITH the hierarchy, and every key role
+ * (agent, orchestrator, user, superadmin) is at least that, so no key is refused for its role.
+ *
+ * A malformed id is refused HERE with `status: 0` (no request sent), for the reason
+ * `delivery-loop.js`'s `uuid()` gives: the server would answer the same 404 as an unknown
+ * story, and the two have opposite remedies.
+ */
+
+import { uuid } from "./delivery-loop.js";
+
+export function storyChangesPath(storyId) {
+  return `/api/v1/stories/${encodeURIComponent(storyId)}/changes`;
+}
+
+/** `GET /api/v1/stories/:id/changes`: the story's chg change bindings and applied events. */
+export async function changeBindingGet({ story_id } = {}, { apiCall } = {}) {
+  const bad = uuid(story_id, "story_id");
+  if (bad) return bad;
+
+  return apiCall("GET", storyChangesPath(story_id), null);
+}

package/lib/delivery-loop.js

@@ -84,7 +84,7 @@ function refuse(body) {
  * That 404 is the problem, not a 500. It is BYTE-IDENTICAL to the 404 for a perfectly
  * well-formed id that names no story — `FallbackController` answers `{:error, :not_found}` with
  * the same `%{error: %{status: 404, message: "Not found"}}`
- * (`lib/loopctl_web/fallback_controller.ex:74-78`) — so it cannot tell an operator which
+ * (`lib/loopctl_web/fallback_controller.ex:84-88`) — so it cannot tell an operator which
  * of the two happened, and the two have opposite remedies: re-read the argument you passed, or
  * go find the right story. The check here can tell them apart, and does it without a round trip.
  *

package/lib/intake-sources.js

@@ -74,10 +74,28 @@
  * 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
+ * (`lib/loopctl_web/controllers/intake_source_controller.ex:34-36`). 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`.
+ * `403 api_key_mint_forbidden`, exactly as it is on `POST /api/v1/api_keys`. An update that
+ * names a `chg` credential or sets `mode` to `chg` is held to the same ceiling under its own
+ * code, `403 chg_registration_forbidden`, whose remedy is the operator key itself.
+ *
+ * ## MODE `chg` AND ITS TWO CREDENTIALS (US-47.2, AC-47.7.2)
+ *
+ * A source in `mode: "chg"` has its changes landed by the change protocol (`chg submit`), and
+ * loopctl's merge precondition refuses every story on it with `409 change_protocol_enrolled`.
+ * It needs BOTH `change_events_secret` — the HMAC key chg-server signs its event webhook with,
+ * which the OPERATOR supplies because chg-server must hold the same value — and
+ * `chg_root_dispatch_id`, the parentless orchestrator-role dispatch chg-server's key was minted
+ * from (`422 chg_root_invalid` for anything else, another tenant's included).
+ *
+ * The secret is WRITE-ONLY on both sides: the server never serialises it, and `publicSource`
+ * below never names it, so no tool result carries it. A tool INPUT is recorded in the
+ * transcript too, so `change_events_secret_file` is offered beside it: the tool reads the
+ * value from that file and it never passes through a transcript at all. Exactly one trailing
+ * newline is stripped (what `openssl rand -hex 32 > file` writes); chg-server must hold the
+ * value without it.
  *
  * ## `repo_full_name` IS NOT SHAPE-CHECKED HERE, AND THAT IS A DECISION
  *
@@ -144,18 +162,135 @@ function epicRefusal(value, { clearable }) {
 }
 
 /**
- * The merge routes a source may take: `pr`, the default and the only one (#984 retired
- * `thread`). NOT nullable — the server answers 422 — so a null is refused here where the
- * reason can be stated.
+ * The merge routes a source may take: `pr`, the default, and `chg` (US-47.2), where the change
+ * protocol lands the repository's changes and the PR route is closed. NOT nullable — the
+ * server answers 422 — so a null is refused here where the reason can be stated.
  */
-export const SOURCE_MODES = ["pr"];
+export const SOURCE_MODES = ["pr", "chg"];
 
 export function modeRefusal(mode) {
   if (SOURCE_MODES.includes(mode)) return null;
 
   return refuse(
-    "`mode` must be `pr`, or must be left out entirely (enrolment then takes `pr`, and an " +
-      "update keeps the current value). It cannot be null.",
+    "`mode` must be `pr` or `chg`, or must be left out entirely (enrolment then takes `pr`, " +
+      "and an update keeps the current value). It cannot be null.",
+  );
+}
+
+/**
+ * The `chg` credentials a call NAMED, resolved into the request body fields, or a refusal.
+ *
+ * Resolves to `{ fields }` or `{ refusal }`. `clearable` is the update path, where an explicit
+ * null clears a credential on a `pr` source (the server refuses it on a `chg` one). No branch
+ * of this function puts the secret's value in a message.
+ */
+export async function chgCredentials(args, { clearable, fs = defaultFs, homedir = os.homedir() }) {
+  const fields = {};
+  const { change_events_secret: secret, change_events_secret_file: secretFile } = args;
+
+  if (secret !== undefined && secretFile !== undefined) {
+    return {
+      refusal: refuse(
+        "Send `change_events_secret` OR `change_events_secret_file`, not both: they are two " +
+          "ways of naming the same value.",
+      ),
+    };
+  }
+
+  if (secret !== undefined) {
+    if (secret === null && clearable) {
+      fields.change_events_secret = null;
+    } else if (typeof secret !== "string" || secret === "") {
+      return {
+        refusal: refuse(
+          "`change_events_secret` must be a non-empty string (the server holds it to " +
+            "32-256 bytes)" +
+            (clearable ? ", or null to clear it on a `pr` source." : ".") +
+            " Prefer `change_events_secret_file`, which keeps the value out of the transcript.",
+        ),
+      };
+    } else {
+      fields.change_events_secret = secret;
+    }
+  }
+
+  if (secretFile !== undefined) {
+    const read = await readSecretFile(secretFile, { fs, homedir });
+    if (read.refusal) return read;
+    fields.change_events_secret = read.secret;
+  }
+
+  const root = args.chg_root_dispatch_id;
+
+  if (root !== undefined) {
+    if (root === null && clearable) {
+      fields.chg_root_dispatch_id = null;
+    } else {
+      const badRoot = uuidRefusal(root, "chg_root_dispatch_id");
+      if (badRoot) return { refusal: badRoot };
+      fields.chg_root_dispatch_id = root;
+    }
+  }
+
+  return { fields };
+}
+
+async function readSecretFile(secretFile, { fs, homedir }) {
+  if (typeof secretFile !== "string" || secretFile.trim() === "") {
+    return {
+      refusal: refuse("`change_events_secret_file` must be a path to the file holding the secret."),
+    };
+  }
+
+  const path = expandHome(secretFile, homedir);
+  if (!nodePath.isAbsolute(path)) {
+    return {
+      refusal: refuse(
+        `change_events_secret_file must be absolute or start with ~/ (got '${secretFile}').`,
+      ),
+    };
+  }
+
+  let raw;
+  try {
+    raw = await fs.readFile(path, "utf8");
+  } catch (err) {
+    return {
+      refusal: refuse(
+        `Could not read change_events_secret_file '${path}' (${err?.code || "error"}). ` +
+          "Nothing was sent.",
+      ),
+    };
+  }
+
+  const secret = raw.replace(/\r?\n$/, "");
+  if (secret === "") {
+    return { refusal: refuse(`change_events_secret_file '${path}' is empty. Nothing was sent.`) };
+  }
+
+  return { secret };
+}
+
+/**
+ * `mode: "chg"` at ENROLMENT needs both credentials in the same call (there is no earlier
+ * stint to keep them from), so their absence is refused here, before a secret file is
+ * reserved, with the 422 the server would answer named.
+ */
+function chgEnrolmentRefusal(mode, fields) {
+  if (mode !== "chg") return null;
+
+  const missing = ["change_events_secret", "chg_root_dispatch_id"].filter(
+    (field) => fields[field] === undefined,
+  );
+
+  if (missing.length === 0) return null;
+
+  return refuse(
+    `\`mode: chg\` needs ${missing.map((f) => `\`${f}\``).join(" and ")} in the same call; ` +
+      "the server answers 422 without them. `chg_root_dispatch_id` is the parentless " +
+      "orchestrator-role dispatch chg-server's key was minted from (the operator mints it " +
+      "with `dispatch`, no parent), and the secret is the HMAC key chg-server signs its " +
+      "events with (`change_events_secret_file` keeps it out of the transcript).",
   );
 }
 
@@ -221,6 +356,8 @@ export function publicSource(source) {
     base_branch: source.base_branch,
     mode: source.mode,
     required_checks: source.required_checks,
+    // `change_events_secret` is NEVER named here: write-only (US-47.2).
+    chg_root_dispatch_id: source.chg_root_dispatch_id,
     target_epic_id: source.target_epic_id,
     revoked_at: source.revoked_at,
     inserted_at: source.inserted_at,
@@ -255,6 +392,9 @@ export async function enrollIntakeSource(
     mode,
     required_checks,
     secret_file,
+    change_events_secret,
+    change_events_secret_file,
+    chg_root_dispatch_id,
   } = {},
   { userKey, apiCall, baseUrl, fs = defaultFs, homedir = os.homedir() } = {},
 ) {
@@ -309,6 +449,16 @@ export async function enrollIntakeSource(
     if (badChecks) return badChecks;
   }
 
+  // The `chg` credentials (US-47.2), resolved and judged before a secret file is reserved.
+  const chg = await chgCredentials(
+    { change_events_secret, change_events_secret_file, chg_root_dispatch_id },
+    { clearable: false, fs, homedir },
+  );
+  if (chg.refusal) return chg.refusal;
+
+  const badChg = chgEnrolmentRefusal(mode, chg.fields);
+  if (badChg) return badChg;
+
   if (typeof secret_file !== "string" || secret_file.trim() === "") {
     return refuse(
       "`secret_file` is required: the path the webhook secret is written to (mode 0600). " +
@@ -360,6 +510,7 @@ export async function enrollIntakeSource(
   if (base_branch !== undefined) body.base_branch = base_branch;
   if (mode !== undefined) body.mode = mode;
   if (required_checks !== undefined) body.required_checks = required_checks;
+  Object.assign(body, chg.fields);
 
   let result;
   try {
@@ -514,7 +665,10 @@ export async function listIntakeSources({ include_revoked } = {}, { userKey, api
  * 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 } = {}) {
+export async function updateIntakeSource(
+  args = {},
+  { userKey, apiCall, fs = defaultFs, homedir = os.homedir() } = {},
+) {
   if (!userKey) return refuse(MISSING_USER_KEY);
 
   const bad = uuidRefusal(args.source_id, "source_id");
@@ -553,11 +707,20 @@ export async function updateIntakeSource(args = {}, { userKey, apiCall } = {}) {
     body.required_checks = args.required_checks;
   }
 
+  // Switching to `chg` may rely on credentials an earlier `chg` stint left on the row, so their
+  // absence here is the SERVER's to judge (422 naming the missing one); only their shape is
+  // judged here.
+  const chg = await chgCredentials(args, { clearable: true, fs, homedir });
+  if (chg.refusal) return chg.refusal;
+  Object.assign(body, chg.fields);
+
   if (Object.keys(body).length === 0) {
     return refuse(
       "Nothing to update. Name at least one of `target_epic_id` (null clears it), " +
-        "`base_branch`, `mode` or `required_checks`. A body carrying none of them is refused 422 " +
-        "`nothing_to_update`, because a field you do not send is left exactly as it was.",
+        "`base_branch`, `mode`, `required_checks`, `change_events_secret` (or " +
+        "`change_events_secret_file`) or `chg_root_dispatch_id`. A body carrying none of them " +
+        "is refused 422 `nothing_to_update`, because a field you do not send is left exactly " +
+        "as it was.",
     );
   }
 

package/lib/story-update.js

@@ -72,7 +72,7 @@
  * (`lib/loopctl_web/plugs/cast_error_handler.ex:32-35`), and the body is
  * `LoopctlWeb.ErrorJSON`'s generic `{"error": {"status": 404, "message": "Not found"}}` — byte
  * for byte what `FallbackController` answers for a well-formed id naming no story
- * (`lib/loopctl_web/fallback_controller.ex:74-78`). Two opposite remedies, one answer.
+ * (`lib/loopctl_web/fallback_controller.ex:84-88`). Two opposite remedies, one answer.
  *
  * The check is `uuid()`, IMPORTED from `lib/delivery-loop.js` rather than reimplemented, so the
  * refusal a caller reads for a bad `story_id` does not depend on which tool they reached for.

package/package.json

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