docs(next): retarget NEXT.md at the one thing blocking the review gate

[kjgbot]

Retargeted at 4037ba1. This PR originally named agent-relay: command not found (exit 127) as the blocker. #198 closed that. The body below now matches the file; the earlier version is left in the comment history rather than edited away.

The headline

The review swarm has never succeeded. Not once.

TOTAL runs: 76   failure: 75   cancelled: 1   successes: 0
first  2026-08-30T20:22:22Z
latest 2026-09-06T04:03:35Z

A week, seventy-six runs, no verdict ever produced. Any claim that gate 3 is "architecturally complete" has to survive that number: most of its nine requirements describe behaviour downstream of a launch that has never happened.

What is actually broken

Launch cloud swarm fails after exactly ten minutes (run 34007204726, 02:44:24Z → 02:54:27Z):

Device login expired before it was approved. Run the command again to get a new code.

The CLI tried to authenticate by browser device code and waited for an approval that cannot happen in CI.

The cause is the pinned version, not a missing secret. agent-relay authenticates from the environment through a dependency, and the pinned build does not contain that code:

package	CLOUD_API_KEY in @agent-relay/cloud/dist/api-client.js
agent-relay@11.10.3	present
agent-relay@11.8.3 (#198's pin)	0 occurrences

WorkflowApiKeyClient.fromEnv reads env.CLOUD_API_KEY, and workflows.js:550 prefers it over the stored login, so with the variable set the device flow is never reached. identity.js:134 states the intent outright: "CI can inject identity without a login."

Precedent: AgentWorkforce/relay's relayflow-pr-proof.yml runs this exact shape in production against published 11.10.3. Nothing here is novel.

What the package asks for

1. Bump fix(review-swarm): install the CLI the gate runs #198's pin 11.8.3 → 11.10.3. Keep pinning; only the version was wrong.
2. Set CLOUD_API_URL and CLOUD_API_KEY on the launch step.
3. Mint per AgentWorkforce/cloud → docs/runbooks/relay-ci-workflow-credential.md (CI_TOKEN_PROFILE=workflow-invoke). An operator mints; a repository administrator stores it — the runbook does not authorize an agent to create GitHub secrets.
4. Fix the preflight, which currently cannot fail. Validate cloud authentication checks one variable for non-emptiness, never attempts an authentication, and passed green on the run whose authentication failed.

Why this is a package and not a patch

RFC-0001 decision #6 and the charter's second hard rail: the Lead cannot edit the gates that judge its work, and review-swarm.yml is that gate. It has been left broken rather than quietly patched.

Note

ops/NEXT.md is rewritten by four open PRs (#189, #194, #199, #200). Whichever lands last conflicts, and resolving by taking one side wholesale silently discards three. Consolidate before merging any of them.

🤖 Generated with Claude Code

https://claude.ai/code/session_01FtQSAcGDta5VH9xiZFT4sR

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Team

Run ID: a9d2f60c-f539-44cb-83d6-4fdf14eec9bc

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Free

Run ID: f858b7e7-ba40-4f29-a64e-c4db66ab5f43

📥 Commits

Reviewing files that changed from the base of the PR and between 5cc0b2a and 4037ba1.

📒 Files selected for processing (1)

• ops/NEXT.md

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

ops/NEXT.md replaces the gate-3 design plan with an authentication incident handoff. It records failed runs, identifies credential configuration issues, specifies remediation steps, and defines acceptance and scope controls.

Changes

Authentication Incident Handoff

Layer / File(s)	Summary
Incident evidence and diagnosis ops/NEXT.md	The document records 76 failed or cancelled runs, outage causes, device-login evidence, and the authentication differences between agent-relay versions.
Credential remediation plan ops/NEXT.md	The document specifies upgrading to 11.10.3, configuring CLOUD_API_URL and CLOUD_API_KEY, provisioning a scoped CI credential, and validating both variables before launch.
Acceptance and merge controls ops/NEXT.md	The document defines success or failure evidence, limits changes to .github/ and one secret, forbids human credentials, and requires consolidation with four open pull requests.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Poem

A rabbit checks the relay gate,
And counts the runs that failed to wait.
Two cloud keys join the morning flight,
A scoped CI token keeps things right.
Preflight guards the launch tonight.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[kjgbot]

Collides with #189, which I should have found before opening this. #189 (drive: cloud run 56b36757, opened 19:09Z) also rewrites ops/NEXT.md. I wrote this package without surveying open PRs first.

They are not equivalent, so this is not simply "close one":

• This PR's NEXT.md is more current. drive: cloud run 56b36757 #189's version asks someone to verify the review-swarm against nine requirements and to fix a missing @types/node — and drive: cloud run 56b36757 #189's own NEEDS_HUMAN.md then reports that the dependency was already present. It does not name the exit-127 agent-relay: command not found blocker, which is what actually stops the gate today.
• drive: cloud run 56b36757 #189 carries something this PR does not, and it should not be lost: a reproducible SDK test failure, plus a sdk/package-lock.json change I have not reviewed.

Suggested resolution: take this NEXT.md, keep #189's NEEDS_HUMAN.md, and review its lockfile diff separately. But that is a call for whoever merges — I am not merging either (see below and #193).

[kjgbot]

Status update on the collision noted above, so this PR is decision-ready.

#189's substantive content is resolved and out of the way. Its NEEDS_HUMAN.md finding — the one thing that made it more than a stale rewrite — is root-caused as #195 and fixed in #196. I have recommended closing #189 pending a look at its sdk/package-lock.json diff, which is the only part of it nobody has evaluated.

That leaves this PR as the only live proposal for ops/NEXT.md, and its target is unchanged and still correct: the review gate fails on every flows PR at Launch cloud swarm with agent-relay: command not found, exit 127, because nothing installs the CLI. Confirmed again this tick against #196's run.

The design question in the body still stands and still needs a human, and it is the reason this is a NEXT.md and not a patch: the fix belongs in review-swarm.yml, which on a pull_request event is taken from the PR head — so an install step there is PR-author-editable, and RFC-0001 line 75 bars the Lead from editing the gates that judge its work. I am not routing around either constraint.

Practical consequence worth stating plainly: #196 cannot go green until this lands, and neither can anything else. It is the one blocker with fleet-wide reach.

[kjgbot]

Correcting myself: this PR is not blocking the others

I said on this PR that "#196 cannot go green until this lands, and neither can anything else," and called it the one blocker with fleet-wide reach. The first half is true and the second is wrong, and the difference matters for whoever picks this up.

mergeStateStatus for #193, #194 and #196 is UNSTABLE, not BLOCKED. A failing required check produces BLOCKED; UNSTABLE means checks are failing and none of them gates the merge. So the review check is failing and not required. All three PRs are MERGEABLE right now.

(I cannot read branch protection directly — admin=false, and that endpoint 404s for non-admins, so it proves nothing either way. mergeStateStatus does not depend on my permissions.)

What actually follows:

• True: review stays red on every flows PR until the CLI install lands. The signal is broken.
• False, as I put it: that this blocks anything. It does not. Nothing is queued behind this PR mechanically — what fix(kernel): a worker-reported failure must journal why, not just its label #196 is waiting for is a reviewer, not a green check.
• The part worth more attention than my original claim: the review gate currently provides no enforcement at all. It is failing on every PR and nothing requires it, so anything in this repo can be merged unreviewed. A gate that is both broken and advisory is worse than a gate that is merely broken, because the red is easy to read as "blocked" — which is exactly how I read it, twice.

That also makes my own position honest to state: I have push=true. My not merging tonight is a rail I am holding, not a wall I am hitting. I would rather say that plainly than keep describing myself as constrained by machinery that is not actually there.

This PR is still worth landing — the swarm signal has no value while it exits 127. It is just not load-bearing for anyone else's merge.

[kjgbot]

Retargeted at 4037ba1 — this package named the wrong blocker, and now names the verified one

When I opened this, the gate failed at agent-relay: command not found. #198 closed that. The gate still fails, and I have since traced the actual cause end to end, so this package would have sent someone at a problem that no longer exists.

The blocker is the pinned version, not a missing secret:

package	CLOUD_API_KEY in @agent-relay/cloud/dist/api-client.js
agent-relay@11.10.3	present
agent-relay@11.8.3 (#198's pin)	0 occurrences

WorkflowApiKeyClient.fromEnv reads env.CLOUD_API_KEY, and workflows.js:550 prefers it over the stored login — so with the variable set, cloud run never reaches the device flow that hung for ten minutes. That code is simply absent from the pinned build. AgentWorkforce/relay runs this exact shape in production against published 11.10.3.

The rewritten package carries the four concrete steps (bump the pin, set both variables, mint per the cloud runbook, fix the preflight), the evidence chain for each, and an explicit note that an operator mints while a repository administrator stores — the runbook does not authorize an agent to touch GitHub secrets.

It also now leads with the number that frames the whole gate-3 question:

TOTAL runs: 76   failure: 75   cancelled: 1   successes: 0
first 2026-08-30  ·  latest 2026-09-06

A week, seventy-six runs, no verdict ever produced. Nothing downstream of authentication has ever executed, which is worth holding next to any claim that the gate is architecturally complete.

Why I rewrote rather than opened a new PR: ops/NEXT.md is already contested by four PRs (#189, #194, #199, #200). Adding a fifth would have made the collision worse while claiming to fix it. This keeps the count where it is and makes the surviving version the one with verified content.

Still not merging it myself, and step 4 in particular remains something I cannot do: fixing Validate cloud authentication means editing the gate that judges my work.