[freeqaz]

Problem

Two repository-delivery startup refusals were plain Errors. API and worker startup therefore logged only STARTUP_FAILED, and the chart's upgrade check printed no field:

• validateOpenShellRepositoryTransport used one message for eight unmet repository.openShell requirements: "OpenShell Git requires prepared GitHub custody, the bundled Kubernetes/OpenShell pair and an authenticated HTTPS gateway." This is the rest of finding 2216; fix(egress): name the refused field in an authority block #3260 fixed the same problem for authority blocks.
• With repository.nativeSender, a Compute network.repositoryCredentials peer that was missing or not on port 8443 got a generic message (finding 2227, the sibling of 2226 fixed in fix(config): name the refused field for a leftover repository broker peer #3268).

Change

• validateOpenShellRepositoryTransport throws InstallationFieldError with one detail per unmet requirement. Each detail has a JSON Pointer and a schema code, and its message never echoes a value. Details are bounded as in fix(egress): name the refused field in an authority block #3260. The pointers are:

  • /repository/preparedGitHub
  • /backend/<i>/configuration/endpoint (must be an https:// URL)
  • /backend/<i>/configuration/auth or .../auth/mode (must be bearerTokenFile or mtls; mtls when observedHookPreviewWorkspace is set)
  • /drivers/sandbox or /drivers/sandbox/package
  • /drivers/compute
  • /backend, when the github or openshell entry is missing

  loadInstallationConfiguration passes the OpenShell Backend's index so the pointer names the right backend entry.

• The native peer refusal is an InstallationFieldError: REQUIRED at /drivers/compute/configuration/network/repositoryCredentials when the peer is absent, and INVALID_VALUE at .../repositoryCredentials/port otherwise.

• Startup and the upgrade check report both refusals as DRIVER_CONFIGURATION_INVALID through the existing startupConfigurationFailure path.

Verification

• tests/integration/sandbox-driver-startup.test.mjs:
  • The protected OpenShell Git load test gains a case with no preparedGitHub and a plaintext, unauthenticated gateway. It asserts three details: /repository/preparedGitHub REQUIRED, and /backend/0/configuration/endpoint and /auth/mode INVALID_VALUE. It also asserts that the endpoint value is not echoed.
  • A table test covers the requirements that earlier startup checks normally catch first.
• tests/integration/configuration-startup.test.mjs: a new test checks the missing peer and the wrong-port peer through the log filter. It also boots API and worker and asserts DRIVER_CONFIGURATION_INVALID with the field. It replaces two regex cases in the repository-startup table.
• The new tests fail on main and pass 10/10 at 2 CPUs.
• Full runs pass:
  • sandbox-driver-startup: 114 pass, 1 skip, the same as on main
  • configuration-startup: 41/41
  • installation-change-preflight: 7/7
• tsc --build, eslint and prettier are clean on the touched files.

Risks

Low. The same configurations are refused as before, now with field-level diagnostics. Anything that matched the old message text needs updating. Only the two table cases did, and this PR replaces them.

[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 maintainer review before merge.

What this changes

This PR identifies refused repository delivery settings in API, worker, and installation-check diagnostics.

Example: Native repository delivery is selected without drivers.compute.configuration.network.repositoryCredentials.

• Before: API startup reports STARTUP_FAILED without naming the missing setting.
• After: API startup reports DRIVER_CONFIGURATION_INVALID with REQUIRED at /drivers/compute/configuration/network/repositoryCredentials.

Review scores

Measure	Result	What it means
Overall readiness	🦐 gold shrimp (3/6)	A focused, source-supported repair with meaningful regression coverage and no identified defect; execution evidence remains test-based.
Proof confidence	🦐 gold shrimp (3/6)	This collaborator-authored diagnostic repair is outside the ordinary contributor-proof gate; supplied verification consists of reported test results and inspected tests exercising the production loader, formatter, and native-peer API/worker startup.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Product

Kind: Bug fix · Worth it: Yes · Fix scope: Complete
User problem: Operators cannot identify which repository delivery setting caused API or worker startup to refuse an Installation.
Reason: The collaborator-authorized diagnostic repair makes existing refusals actionable while retaining the supported configuration and security boundaries.

Merge readiness

✅ Ready for maintainer review

Keep this PR open: it fixes two diagnostic gaps still present on main, preserves existing validation, and introduces no identified correctness or security defect.

Priority: P2
Reviewed head: 58162450c99e42de058e5f96f85b89648083d722

Before merge

None.

Findings

None.

Tests

• Missing end-to-end proof: No separate runtime artifact demonstrates the OpenShell multi-field refusal through API, worker, or Helm, and the reported failing-base/passing-head comparison was not independently executed.

Agent review details

How this fits together

Installation composition validates operator configuration before startup; the shared failure mapper and log filter turn refusals into API, worker, and Helm installation-check diagnostics.

flowchart TB
  A[Installation configuration] --> B[Repository delivery validation]
  B --> C[Installation field error]
  C --> D[Startup failure mapping]
  D --> E[Filtered diagnostics]
  E --> F[API and worker logs]
  E --> G[Helm installation check]

Loading

Technical review

Best possible solution:

Keep the existing validation owners and emit bounded, value-free field diagnostics through the shared startup failure pipeline.

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

Current-main source shows both plain errors bypassing typed configuration diagnostics, while the added scenarios provide concrete invalid configurations; no target code was executed during this review.

Is this the best way to solve the issue?

The patch repairs the existing validation owners, preserves their acceptance rules, and reuses the established diagnostic pipeline without adding another configuration mechanism.

AGENTS.md: found and applied where relevant.

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

Provenance checked

• OpenShell repository transport requirements keeps the original intent (3115679: Credential Proxy Implementation #2487 established prepared credential custody and the supported Kubernetes/OpenShell transport boundary.)
• Native repository service peer keeps the original intent (2fd3d79: Repository credentials: platform lifecycle and Kubernetes delivery #235 connected repository credentials to lifecycle ownership and Kubernetes delivery; the later native-sender configuration retains the exact port-8443 peer requirement.)

Testing

Proof path: in-process harness.

Security

None.

Evidence

What I checked:

• Current-main diagnostic gaps: Fetched main retains the plain Error for OpenShell transport requirements and the plain Error for a missing or wrong-port native repository peer. (apps/controller/src/composition/installation-config.ts:880, 38ecfca18762)
• Pinned introduced change: The introduced hunks preserve the rejection predicates, add fixed field details, and obtain the OpenShell Backend index from the same validated array that supplies the selected Backend. (apps/controller/src/drivers/egress-proxy/openshell-configuration.ts:66, 58162450c99e)
• Existing diagnostic pipeline: InstallationFieldError bounds details to 32; startupConfigurationFailure maps it to DRIVER_CONFIGURATION_INVALID, and configurationLogDetails filters the emitted details before logging. (apps/controller/src/startup-failure.ts:49, 58162450c99e)
• Meaningful startup regression coverage: The native-peer test checks missing peers and ports 8442 and 8444 through production loading and formatting, then boots the real API and worker and checks the missing-field diagnostic. (tests/integration/configuration-startup.test.mjs:2246, 58162450c99e)
• OpenShell loader coverage: The extended loader scenario checks three independent field details for missing prepared custody and an unauthenticated HTTP gateway, including suppression of the configured endpoint sentinel; gateway observations remain controlled. (tests/integration/sandbox-driver-startup.test.mjs:5777, 58162450c99e)
• Related repairs and discussion: fix(egress): name the refused field in an authority block #3260 established the reused field-error pipeline, while fix(config): name the refused field for a leftover repository broker peer #3268 repaired the opposite native-peer mismatch; neither covers these remaining refusals, and the author discussion requests re-review without adding runtime artifacts.

Review metrics

Metric	Value	Why it matters
Change footprint	Production +85/-20 lines; tests +177/-8 lines	The growth replaces combined refusals with individual diagnostics and adds loader, filtering, and startup-process coverage.

Labels

Label changes:

No label changes.

Label justifications:

• P2: This focused operator-diagnostic repair identifies already-refused configuration without changing transport admission or authorization.
• rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🦐 gold shrimp and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR.

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.

History

Review history (1 earlier review cycle)

• reviewed 2026-10-23T04:06:32.275Z sha 54711dc :: needs maintainer review before merge. :: none

Reviewed October 23, 2026, 12:30 AM ET / 04:30 UTC (Revision 2).

[freeqaz]

@clawsweeper re-review

[clawsweeper]

🦞👀
Exact review queued.

Re-review progress:

• State: Complete
• Detail: The durable review result and its route handoff completed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/39900845444
• Updated: 2026-10-23T04:32:33.932Z