[freeqaz]

Problem

Six PRs merged on 2026-10-24 changed what Agent save, deploy or credential source creation answers, with no breaking-changes entry:

• fix(openshell): refuse dedicated openclaw with several sandbox serviceaccounts at admission #3514: OpenShell refuses dedicated OpenClaw with several gateway.operatorWorkspaceResources ServiceAccounts at save and deploy, and openclaw.executionModes drops dedicated when admission would refuse it.
• fix(ssh): refuse gateway authentication and secret bindings ssh cannot deliver at deploy admission #3516: SSH deploy refuses Gateway authentication and secretBindings that SSH cannot deliver (409 / 400 instead of 202 and failed preparation).
• fix(plugins): refuse plugins the agent's harness cannot run at save and admission #3517: Agent save, preflight, provisioning and deploy refuse plugins whose Harness the Plugin Driver cannot run.
• fix(repo): refuse installation-wide access next to another binding at agent save #3524: installation-wide repository access next to another binding is refused at save with 400 (it was a 404 at deploy).
• fix(credential-proxy): name the git-only proxy refusal instead of a 503 or a bare 404 #3531: the Git-only Credential Proxy composition and unprotected bindings answer named 409s instead of 503 / 404.
• fix(repo): name the paths that work for an openshell install and the missing repository driver #3534: repository bindings without repository settings answer 409 instead of 503; two refusal messages changed.

Each one changes what a stored Agent or an API client sees after an upgrade, so operators need a notice (dogfood finding D687).

Change

• breaking-changes.md: one 2026-10-24 notice per PR in the house format (what breaks, who is affected, how to tell, steps), newest first. Each names the exact status code and message the PR's code and tests use.
• The page was at 2320 words, so its six oldest 2026-10-24 notices move unchanged to a new page, breaking-changes-earlier-2026-10-24.md. The intro of every notice page links it, and docs.json registers it after the main page.

Verification

• pnpm docs:check passes: 294 pages and 4614 links validated, no page over the hard limit (breaking-changes.md 2197 words, the new page under the review threshold).
• prettier --check passes on every touched file.
• Each message was checked against the merged diff and the tests of its PR.

Risks

Docs only. The moved notices are unchanged; only their page changes, and no other page links their anchors.

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

ClawSweeper review complete

ClawSweeper finished reviewing this revision. The review result is being finalized.

View the workflow run.

[clawsweeper]

Codex review: needs changes before merge.

What this changes

This PR adds six upgrade notices and moves six older notices to a linked archive page.

Example: An API client saves repositoryBindings on an Installation without repository settings.

• Before: The upgrade guide does not explain the change from 503 to 409.
• After: The guide names RESOURCE_CONFLICT and explains how to remove the bindings or configure repository access.

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	Useful and focused documentation with one low-impact factual overstatement; runtime proof is not required for this diff.
Proof confidence	🌊 off-meta tidepool	Not applicable: This PR changes documentation only; source inspection supports the notices, and the body reports documentation and formatting checks.
Patch quality	🐚 platinum hermit (4/6)	1 actionable review finding remain.

Product

Kind: Docs · Worth it: Yes · Fix scope: Complete
User problem: Operators and API clients lack upgrade notices explaining earlier admission refusals and changed HTTP statuses.
Reason: The maintainer-authored direction improves upgrade guidance using established documentation owners; the current page remains one coherent upgrade-notice topic despite exceeding the review threshold.

Merge readiness

⛔ Needs changes before merge - 1 item remains

Keep this useful, maintainer-authored documentation update open; it fills missing operator notices and needs one small accuracy correction.

Priority: P3
Reviewed head: 15f7e10d39c72826d9e197107846558c74c928db

Before merge

• Preserve the Gateway Harness source exception in the notice (P3) - For a Git Agent using its ready, matching Gateway Harness credential source, admitProxyPlan explicitly counts that ordinary source and does not reject it for lacking Proxy ownership. The unconditional statement here says this supported binding answers 409, contradicting the recovery advice immediately below. Qualify the statement, and its shortened message quotation, with the existing exception for the ready Gateway Harness source beside repository Git.

Findings

• [P3] Preserve the Gateway Harness source exception in the notice — docs/guides/deploy/breaking-changes.md:47-49

Agent review details

How this fits together

The deployment guide translates controller admission changes into operator symptoms and recovery steps; docs.json exposes the current and archived notices.

flowchart LR
  A[Controller admission behavior] --> B[Breaking change notices]
  B --> C[Operator upgrade decisions]
  B --> D[Earlier notice archive]
  E[Documentation navigation] --> B
  E --> D

Loading

Technical review

Best possible solution:

Keep the six notices and archive rotation, while explicitly preserving the Gateway Harness source exception in the Credential Proxy notice.

Do we have a high-confidence way to reproduce the issue?

Current-main admission source explicitly accepts the ready Gateway Harness source beside repository Git, contradicting the notice's unconditional statement about sources outside Proxy ownership.

Is this the best way to solve the issue?

The existing notice format and archive owner are appropriate; qualifying the affected-source statement is the smallest complete correction.

Full review comments:

• [P3] Preserve the Gateway Harness source exception in the notice — docs/guides/deploy/breaking-changes.md:47-49
  For a Git Agent using its ready, matching Gateway Harness credential source, admitProxyPlan explicitly counts that ordinary source and does not reject it for lacking Proxy ownership. The unconditional statement here says this supported binding answers 409, contradicting the recovery advice immediately below. Qualify the statement, and its shortened message quotation, with the existing exception for the ready Gateway Harness source beside repository Git.
  Confidence: 0.98

Overall correctness: patch is correct
Overall confidence: 0.93

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning medium; reviewed against febe65b3486a.

Provenance checked

• Dated notices and archive rotation keeps the original intent (c66531d: Give operators dated symptoms and recovery steps for breaking changes; subsequent archive rotations preserve notices while respecting documentation limits.)

Security

None.

Evidence

Acceptance criteria:

• pnpm docs:check
• pnpm docs:check-length
• pnpm format:check
• git diff --check

What I checked:

• Introduced documentation scope: The pinned introduced diff contains documentation and navigation changes only; the archive preserves the six moved notices and their headings. (docs/guides/deploy/breaking-changes-earlier-2026-10-24.md:10, 15f7e10d39c7)
• Current-main omission: Fetched main still starts its dated notices with chart container resources and lacks this PR's six new entries. (docs/guides/deploy/breaking-changes.md:22, febe65b3486a)
• Gateway Harness source exception: admitProxyPlan counts a ready, matching Gateway Harness source alongside repository Git, so that source does not trigger CredentialSourceUnprotectedError merely because it lacks Proxy ownership. (packages/occ/src/index.ts:5697, febe65b3486a)
• Merged-change context: The bodies of fix(openshell): refuse dedicated openclaw with several sandbox serviceaccounts at admission #3514, fix(ssh): refuse gateway authentication and secret bindings ssh cannot deliver at deploy admission #3516, fix(plugins): refuse plugins the agent's harness cannot run at save and admission #3517, fix(repo): refuse installation-wide access next to another binding at agent save #3524, fix(credential-proxy): name the git-only proxy refusal instead of a 503 or a bare 404 #3531 and fix(repo): name the paths that work for an openshell install and the missing repository driver #3534 confirm the admission and status changes being documented; the earlier omission rationale was that these inputs already failed preparation.
• CI attribution remains unknown: PostgreSQL Application failed in https://github.com/openclaw/openclaw-enterprise/actions/runs/40146115963/job/121027748110, causing the required aggregate to fail. Annotations identify a test failure, but the log redirect was blocked by the network allowlist; no diff-caused failure was established. (15f7e10d39c7)
• Documentation ownership history: The guide's introduction and dated-notice format trace to c66531d, followed by repeated archive rotations and notice updates by freeqaz. One archive history traversal reached an unavailable older object; the supplied provenance and inspected commits establish the relevant intent. (docs/guides/deploy/breaking-changes.md:1, febe65b3486a)

Likely related people:

• freeqaz: Raw commit c66531d adds docs/guides/deploy/breaking-changes.md:1 relative to its recorded parents. This identifies author metadata, not feature responsibility or a PR merger. (role: source-line author; confidence: high; commits: c66531d72b0a; files: docs/guides/deploy/breaking-changes.md)

Review metrics

Metric	Value	Why it matters
Documentation scope	11 documentation files; production code +0/-0	Growth adds six operator notices and relocates six existing notices to respect the page limit.

Labels

Label changes:

• add P3: This is operator documentation maintenance with a narrow wording defect and no runtime changes.
• add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• add status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action.

Label justifications:

• P3: This is operator documentation maintenance with a narrow wording defect and no runtime changes.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action.

Rating scale

6/6 🦀 challenger crab · 5/6 🦞 diamond lobster · 4/6 🐚 platinum hermit · 3/6 🦐 gold shrimp · 2/6 🦪 silver shellfish · 1/6 🧂 unranked krab. Overall follows the weaker of proof and patch quality; ✨ marks media proof (a screenshot, video, or linked artifact) that directly shows the changed behavior.

Workflow

ClawSweeper edits this one comment on every review. Comment @clawsweeper re-review for a fresh review only. Repair and merge execution lanes are retired.

Reviewed October 24, 2026, 8:30 PM ET / October 25, 2026, 00:30 UTC.