loopctl-mcp-server 3.2.0 → 3.3.0

package/README.md

@@ -259,7 +259,7 @@ Epic 39 Repo Coordination Bus — a lightweight, tenant-isolated channel for age
 | Tool | Description |
 |---|---|
 | `contract_story` | Agent acknowledges a story's acceptance criteria. Transitions pending -> contracted. Refused 409 `story_held` when the story's delivery stage is `escalated`, `done` or `failed` — it is not available to agents even when it reads `pending`; an escalated story becomes available again only after `resolve_escalation` sends it to `queued`. |
-| `claim_story` | Agent claims a contracted story with pessimistic locking. Transitions contracted -> assigned. On a loopctl with claim leases the result leads with the claim's `claim_epoch` and `claimed_until`; keep the epoch for `renew_story_claim`. Both are absent on an older server. Refused 409 `story_held` when the story's delivery stage is `escalated`, `done` or `failed` — even when it reads `pending` or `contracted`; an escalated story is claimable again only after `resolve_escalation` sends it to `queued`, a done or failed one never is. |
+| `claim_story` | Agent claims a contracted story with pessimistic locking. Transitions contracted -> assigned. On a loopctl with claim leases the result leads with the claim's `claim_epoch` and `claimed_until`; keep the epoch for `renew_story_claim`. Both are absent on an older server. Refused 409 `story_held` when the story's delivery stage is `escalated`, `done` or `failed` — even when it reads `pending` or `contracted`; an escalated story is claimable again only after `resolve_escalation` sends it to `queued`, a done or failed one never is. Refused 409 `chg_root_review_only` when the key descends from an intake source's `chg_root_dispatch_id`: chg-server's keys may only review. |
 | `renew_story_claim` | Renew your claim's lease (`POST /stories/:id/renew-claim`, agent key). A claim not renewed before `claimed_until` (default 24 hours, `STORY_CLAIM_LEASE_SECONDS`) is released back to `pending` under you, so renew well inside it on any story held longer. A driver-placed claim — one a placement took for a runner dispatch — is capped at its dispatch deadline (`claim_lease_cap`: placed_at + `wall_clock_seconds` + `DISPATCH_LEASE_GRACE_SECONDS` at the claim, sent to the runner as `deadline_at`; moved forward to a resume's time or the runner's acceptance + `wall_clock_seconds` + the grace, only while the claim is live; never earlier than a `deadline_at` already sent), and its `claimed_until` already IS that cap: renewing it writes nothing and returns the claim as it stands, never moving `claimed_until` past it. Required: `story_id`, `claim_epoch` (from the claim). Refusals pass through: 400 epoch missing or malformed, 422 `not_claimed`, 409 `stale_claim_epoch` (the claim has ended: stop working it), 409 `not_claimant`, 409 `lease_cap_reached` (a driver-placed claim already at its cap: nothing is renewed, stop working it). Needs a loopctl server with claim leases. |
 | `escalate_story` | Park a story you hold for a HUMAN and stop (`POST /stories/:id/escalate`, agent key). This is what an unattended session calls INSTEAD of asking a question — a headless run has no way to ask, so escalating is the affordance. Use it when the request contradicts an existing story, KB decision or documented behaviour, when it inverts or removes behaviour a previous story deliberately added, when it is a workflow change rather than a defect fix, or when it needs a business call — not for an ordinary blocker. ONE-WAY from your side: only a human moves the story off `escalated`, so on success STOP and report. Required: `story_id`, `claim_epoch`, `reason` (verbatim, treated as untrusted data, length capped by the server in codepoints — a 400 names the bound); optional `payload` object. Idempotent under the same epoch. Refusals pass through: 409 `stale_claim_epoch`, 409 `not_claimant`, 404 `unknown_story_stage`, 400 for a malformed epoch or reason. An orchestrator or user key is 403'd on purpose. |
 | `start_story` | Agent starts work on a claimed story. Transitions assigned -> implementing. |
@@ -269,22 +269,22 @@ Epic 39 Repo Coordination Bus — a lightweight, tenant-isolated channel for age
 
 | Tool | Description |
 |---|---|
-| `report_story` | Reviewer confirms the implementation is done. Transitions implementing -> reported_done. Accepts optional `token_usage` object. Under the LCP-1 §9.3 signed profile, pass the `claim` from `custody_sign_claim`. |
-| `review_complete` | Record that a review has been completed for a story. Required before verify. Under the signed profile, pass the `claim` from `custody_sign_claim`. |
+| `report_story` | Reviewer confirms the implementation is done. Transitions implementing -> reported_done. Accepts optional `token_usage` object. Under the LCP-1 §9.3 signed profile, pass the `claim` from `custody_sign_claim`. Refused 409 `chg_root_review_only` for a key descending from an intake source's `chg_root_dispatch_id`. |
+| `review_complete` | Record that a review has been completed for a story. Required before verify. Under the signed profile, pass the `claim` from `custody_sign_claim`. On a story bound to a chg change (loopctl US-47.5), after the existing custody gates: only a key chg-server minted for the review — a strict descendant of the intake source's `chg_root_dispatch_id` — may record it (409 `chg_reviewer_required`, the root key included); `commit_sha` is REQUIRED and must be the sha of a submitted revision of the story's current change (422 `commit_sha_not_bound`); one reviewer dispatch records one verdict (409 `chg_review_already_recorded`). `commit_sha` is ignored on any other story. |
 
 ### Verification Tools (orchestrator key)
 
 | Tool | Description |
 |---|---|
-| `verify_story` | Orchestrator verifies a reported_done story. Transitions reported_done -> verified. Under the signed profile, pass the `claim` from `custody_sign_claim`. |
-| `reject_story` | Orchestrator rejects a story with a reason. The reject releases the claim, and a delivery story may be re-contracted or escalated in the same transaction. A 500 `audit_chain_append_failed` (the escalation's chain entry was refused) means the WHOLE call rolled back: the story is unchanged, and a re-run meets the same server-side condition until an operator acts. |
+| `verify_story` | Orchestrator verifies a reported_done story. Transitions reported_done -> verified. Under the signed profile, pass the `claim` from `custody_sign_claim`. Refused 409 `chg_root_cannot_verify` for a key descending from an intake source's `chg_root_dispatch_id` (loopctl US-47.5). |
+| `reject_story` | Orchestrator rejects a story with a reason. The reject releases the claim, and a delivery story may be re-contracted or escalated in the same transaction. A 500 `audit_chain_append_failed` (the escalation's chain entry was refused) means the WHOLE call rolled back: the story is unchanged, and a re-run meets the same server-side condition until an operator acts. Refused 409 `chg_root_cannot_verify` for a key descending from an intake source's `chg_root_dispatch_id` (loopctl US-47.5). |
 
 ### Bulk Tools (orchestrator key)
 
 | Tool | Description |
 |---|---|
-| `bulk_mark_complete` | **Backfill-only.** Bulk-marks pre-existing, never-dispatched stories (pending, unassigned, no dispatch lineage) as complete in a single call. Dispatched stories are refused — they must go through the normal report → review → verify flow. |
-| `verify_all_in_epic` | Bulk verify all reported_done, unverified stories in an epic. |
+| `bulk_mark_complete` | **Backfill-only.** Bulk-marks pre-existing, never-dispatched stories (pending, unassigned, no dispatch lineage) as complete in a single call. Dispatched stories are refused — they must go through the normal report → review → verify flow. Refused 409 `chg_root_cannot_verify` for the whole batch for a chg-rooted key (loopctl US-47.5). |
+| `verify_all_in_epic` | Bulk verify all reported_done, unverified stories in an epic. Refused 409 `chg_root_cannot_verify` for the whole epic for a chg-rooted key (loopctl US-47.5). |
 
 ### Token Efficiency Tools
 
@@ -664,6 +664,8 @@ loopctl enforces that nobody marks their own work as done. The API returns `409`
 
 The implementer's final action is `request_review`. All subsequent steps (report, review, verify) must come from different agents.
 
+On a story bound to a chg change (loopctl US-47.5) the review comes from chg-server: `review_complete` takes it only from a key chg-server minted beneath its registered `chg_root_dispatch_id` (409 `chg_reviewer_required`), naming the reviewed revision as `commit_sha` (422 `commit_sha_not_bound`), one verdict per reviewer dispatch (409 `chg_review_already_recorded`). chg-server's keys never certify or implement: `verify_story`, `reject_story`, `verify_all_in_epic` and `bulk_mark_complete` answer 409 `chg_root_cannot_verify`, `claim_story` and `report_story` 409 `chg_root_review_only`. A chg story that lands with no review for its landed revision is escalated over `review_missing` and is not verified without a human.
+
 ## Witness protocol (STH)
 
 Every authenticated request echoes the caller's last-known Signed Tree Head (STH)

package/index.js

@@ -1372,12 +1372,15 @@ async function reportStory({ story_id, artifact_type, artifact_path, token_usage
   return toContent(result);
 }
 
-async function reviewComplete({ story_id, review_type, findings_count, fixes_count, disproved_count, summary, claim }) {
+async function reviewComplete({ story_id, review_type, findings_count, fixes_count, disproved_count, summary, commit_sha, claim }) {
   const body = { review_type };
   if (findings_count != null) body.findings_count = findings_count;
   if (fixes_count != null) body.fixes_count = fixes_count;
   if (disproved_count != null) body.disproved_count = disproved_count;
   if (summary) body.summary = summary;
+  // loopctl US-47.5: the reviewed chg revision. Forwarded as given and judged server-side
+  // (422 commit_sha_not_bound), so a malformed value reaches the one place that can say why.
+  if (commit_sha != null) body.commit_sha = commit_sha;
   if (claim) body.claim = claim;
 
   const result = await apiCall(
@@ -1400,7 +1403,7 @@ async function verifyStory({ story_id, summary, review_type, claim }) {
   if (review_type) body.review_type = review_type;
   if (claim) body.claim = claim;
 
-  // `exact_role: :orchestrator` (`story_verification_controller.ex:29-30`). When
+  // `exact_role: :orchestrator` (`story_verification_controller.ex:30-31`). When
   // LOOPCTL_ORCH_KEY is set it is sent EXACTLY, because `resolveKey` would otherwise
   // discard it in favour of a global LOOPCTL_API_KEY on the very calls it was set for.
   // When it is NOT set, the global key still goes — see lib/custody-key.js for why the
@@ -1418,7 +1421,7 @@ async function verifyStory({ story_id, summary, review_type, claim }) {
 }
 
 async function rejectStory({ story_id, reason }) {
-  // `exact_role: :orchestrator` (`story_verification_controller.ex:29-30`) — see
+  // `exact_role: :orchestrator` (`story_verification_controller.ex:30-31`) — see
   // lib/custody-key.js.
   const orch = orchestratorKeyArgs();
 
@@ -1436,7 +1439,7 @@ async function rejectStory({ story_id, reason }) {
 
 async function bulkMarkComplete({ stories }) {
   // stories: [{story_id, summary, review_type}]
-  // `exact_role: :orchestrator` (`bulk_operations_controller.ex:24-25`) — see
+  // `exact_role: :orchestrator` (`bulk_operations_controller.ex:25-26`) — see
   // lib/custody-key.js.
   const orch = orchestratorKeyArgs();
 
@@ -1451,7 +1454,7 @@ async function bulkMarkComplete({ stories }) {
 }
 
 async function verifyAllInEpic({ epic_id, review_type, summary }) {
-  // `exact_role: :orchestrator` (`story_verification_controller.ex:29-30`, `:verify_all`) —
+  // `exact_role: :orchestrator` (`story_verification_controller.ex:30-31`, `:verify_all`) —
   // see lib/custody-key.js.
   const orch = orchestratorKeyArgs();
 
@@ -3454,7 +3457,7 @@ async function resolveEscalation(args) {
 }
 
 // #846: force-unclaim is `exact_role: :orchestrator`
-// (`story_verification_controller.ex:29-30`), so this is the one delivery-loop verb that wants
+// (`story_verification_controller.ex:30-31`), so this is the one delivery-loop verb that wants
 // the ORCH key. Same selection as the other four custody verbs: when LOOPCTL_ORCH_KEY is set it
 // is sent EXACTLY, because `resolveKey` (`index.js:132-138`) would otherwise discard it for a
 // global LOOPCTL_API_KEY on the one call it was set for; when it is not set, a global key still
@@ -4725,7 +4728,9 @@ const TOOLS = [
       "reads pending or contracted — move on. An escalated story is claimable again only " +
       "after resolve_escalation sends it to queued; a done or failed one never is. Refused " +
       "409 dependencies_not_met when a story it depends on, or one in an epic its epic " +
-      "depends on, is not verified: list_blocked_stories names them.",
+      "depends on, is not verified: list_blocked_stories names them. Refused 409 " +
+      "chg_root_review_only when the key descends from an intake source's " +
+      "chg_root_dispatch_id: chg-server's keys may only review.",
     inputSchema: {
       type: "object",
       properties: {
@@ -4871,7 +4876,9 @@ const TOOLS = [
     description:
       "Reviewer (a DIFFERENT agent from the implementer) confirms the implementation is done. " +
       "Chain-of-custody: the implementing agent cannot call this. " +
-      "Transitions implementing -> reported_done. Uses the ORCH key.",
+      "Transitions implementing -> reported_done. Uses the ORCH key. Refused 409 " +
+      "chg_root_review_only when the key descends from an intake source's " +
+      "chg_root_dispatch_id: chg-server's keys may only review.",
     inputSchema: {
       type: "object",
       properties: {
@@ -4906,7 +4913,16 @@ const TOOLS = [
     name: "review_complete",
     description:
       "Record that a review has been completed for a story. " +
-      "Must be called before verify_story. Uses the ORCH key.",
+      "Must be called before verify_story. Uses the ORCH key. " +
+      "On a story BOUND TO A chg CHANGE (loopctl US-47.5) three more rules apply, after the " +
+      "existing custody gates (self_review_blocked, caller_lineage_required, " +
+      "unresolvable_dispatch_lineage), never instead of them: the key must be one chg-server " +
+      "minted for the review — a strict descendant of the intake source's " +
+      "chg_root_dispatch_id — else 409 chg_reviewer_required (chg-server's root key is " +
+      "refused too); commit_sha is REQUIRED and must be the sha of a submitted revision of " +
+      "the story's current change, else 422 commit_sha_not_bound; and one reviewer dispatch " +
+      "records one verdict, a second is 409 chg_review_already_recorded. On any other story " +
+      "commit_sha is ignored and not stored.",
     inputSchema: {
       type: "object",
       properties: {
@@ -4935,6 +4951,13 @@ const TOOLS = [
           type: "string",
           description: "Optional: summary of the review outcome.",
         },
+        commit_sha: {
+          type: "string",
+          description:
+            "REQUIRED on a story bound to a chg change: the reviewed revision commit, 40 or " +
+            "64 lowercase hex characters, the sha of a submitted revision of the story's " +
+            "current change (422 commit_sha_not_bound otherwise). Ignored on any other story.",
+        },
         claim: CLAIM_SCHEMA,
       },
       required: ["story_id", "review_type"],
@@ -4947,7 +4970,15 @@ const TOOLS = [
     description:
       "Orchestrator verifies a reported_done story. " +
       "Requires a review_record to exist (call review_complete first). " +
-      "Transitions reported_done -> verified. Uses the ORCH key.",
+      "Transitions reported_done -> verified. Uses the ORCH key. Refused 409 " +
+      "chg_root_cannot_verify when the key descends from an intake source's " +
+      "chg_root_dispatch_id (loopctl US-47.5): chg-server's keys review and never verify — " +
+      "use an orchestrator key outside chg's tree. A story BOUND TO A chg CHANGE is verified " +
+      "only on a chg review of its LANDED revision (the revision commit of the newest " +
+      "applied landed event of its current change), else 409 " +
+      "chg_review_not_for_landed_revision — have chg dispatch a review naming that sha; and " +
+      "never while its stage is escalated over review_missing, else 409 " +
+      "review_missing_escalated — a human resolves it first (resolve_escalation).",
     inputSchema: {
       type: "object",
       properties: {
@@ -4976,7 +5007,10 @@ const TOOLS = [
       "The reject releases the claim, and a delivery story may be re-contracted or escalated " +
       "in the same transaction. A 500 `audit_chain_append_failed` (the escalation's chain " +
       "entry was refused) means the WHOLE call rolled back: the story is unchanged, and a " +
-      "re-run meets the same server-side condition until an operator acts.",
+      "re-run meets the same server-side condition until an operator acts. Refused 409 " +
+      "chg_root_cannot_verify when the key descends from an intake source's " +
+      "chg_root_dispatch_id (loopctl US-47.5): reject is a custody decision chg-server's " +
+      "keys never make.",
     inputSchema: {
       type: "object",
       properties: {
@@ -4999,7 +5033,9 @@ const TOOLS = [
     description:
       "Bulk mark multiple stories as complete (backfill-only for never-dispatched work). " +
       "ADMIN USE ONLY: backfill pre-existing completed work into pending stories that never entered the dispatch lifecycle. " +
-      "For dispatched stories, use the normal report/review/verify flow. Each story entry needs a story_id, summary, and review_type. Uses the ORCH key.",
+      "For dispatched stories, use the normal report/review/verify flow. Each story entry needs a story_id, summary, and review_type. Uses the ORCH key. " +
+      "Refused 409 chg_root_cannot_verify for the whole batch when the key descends from an intake source's chg_root_dispatch_id (loopctl US-47.5). " +
+      "A story bound to a chg change is a per-story error leading with review_missing_escalated or chg_review_not_for_landed_revision, the same landed-review gate verify_story applies.",
     inputSchema: {
       type: "object",
       properties: {
@@ -5033,7 +5069,11 @@ const TOOLS = [
     name: "verify_all_in_epic",
     description:
       "Bulk verify all reported_done, unverified stories in an epic. " +
-      "Convenience endpoint for the orchestrator after a review pass. Uses the ORCH key.",
+      "Convenience endpoint for the orchestrator after a review pass. Uses the ORCH key. " +
+      "Refused 409 chg_root_cannot_verify for the whole epic, verifying nothing, when the key " +
+      "descends from an intake source's chg_root_dispatch_id (loopctl US-47.5). A story bound " +
+      "to a chg change is skipped into errors with review_missing_escalated or " +
+      "chg_review_not_for_landed_revision, the same landed-review gate verify_story applies.",
     inputSchema: {
       type: "object",
       properties: {

package/lib/custody-key.js

@@ -2,9 +2,9 @@
  * Key selection for the `exact_role: :orchestrator` custody verbs (loopctl #846 review round 2).
  *
  * WHICH VERBS. `verify`, `reject` and `force_unclaim` plus the aggregate `verify_all`
- * (`lib/loopctl_web/controllers/story_verification_controller.ex:29-30`), and bulk
+ * (`lib/loopctl_web/controllers/story_verification_controller.ex:30-31`), and bulk
  * `verify`/`reject`/`mark_complete`
- * (`lib/loopctl_web/controllers/bulk_operations_controller.ex:24-25`). All are mounted
+ * (`lib/loopctl_web/controllers/bulk_operations_controller.ex:25-26`). All are mounted
  * `exact_role: :orchestrator`, where the role hierarchy does NOT apply: `RequireRole`'s
  * exact-role clause tests `api_key.role == exact_role` (`require_role.ex:65-75`), so a `:user`
  * or `:superadmin` key is refused there exactly as an `:agent` key is.

package/lib/delivery-loop.js

@@ -21,7 +21,7 @@
  *   - `resolve_escalation` is the HUMAN half of the escalation pair: a `:user` key no dispatch
  *     minted. The agent key that raises an escalation is 403'd on it by design.
  *   - `force_unclaim_story` is gated `exact_role: :orchestrator`
- *     (`story_verification_controller.ex:29-30`), so it needs an ORCHESTRATOR-ROLE key and a
+ *     (`story_verification_controller.ex:30-31`), so it needs an ORCHESTRATOR-ROLE key and a
  *     higher-privileged one does NOT substitute: `RequireRole`'s exact-role clause tests
  *     `api_key.role == exact_role` (`require_role.ex:65-75`), so a `:user` or `:superadmin`
  *     key is 403'd there exactly as an agent key is. That is a chain-of-custody gate, not an
@@ -293,7 +293,7 @@ export async function resolveEscalation({ story_id, to, reason } = {}, { userKey
  * No request body — the story is named in the path.
  *
  * ORCHESTRATOR ROLE, and exactly that: the action is `exact_role: :orchestrator`
- * (`story_verification_controller.ex:29-30`), so a user or superadmin key is refused —
+ * (`story_verification_controller.ex:30-31`), so a user or superadmin key is refused —
  * `RequireRole`'s exact-role clause tests `api_key.role == exact_role`
  * (`require_role.ex:65-75`).
  *

package/package.json

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