Show the next operator where to resume an installation

[freeqaz-openai]

An installer loses a Helm response during installation. The next operator needs to decide whether to inspect the original attempt or recover its record before another write. occ installation doctor reports the retained initialization Job; occ installation plan orders the next checks without changing the installation.

On a first install, record the persisted Job UID only when no Job predated the attempt and no concurrent install or upgrade could replace it. Given that original UID, a different UID means the current Job cannot establish the original outcome: recover the original record, even if the replacement's release label has changed. A matching UID identifies the Job; it does not prove completion, Helm release success, or Deployment rollout. Without the original UID, the commands can describe the current Job but cannot link it to the earlier attempt. A native sidecar or uncertain read leaves initialization unknown. Reconcile an uncertain write before another write; do not replay it.

Each Job read uses one kubectl invocation to resolve the target and credentials together, including through a path-selecting gateway. The reader needs named-Job access, not Job or Pod list permission. This observational handoff does not fix Helm write races.

The new TypeScript real-k3d test exercises a replacement with a named-only reader. CI wiring discovers and type-checks TypeScript tests, supplies Go to the k3d lane, and prepares the resources this test needs. At this head, the replacement regression failed against the previous source and passed with the change; the named-reader case also passed against a disposable real cluster.

[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

Adds read-only installation doctor and plan commands, operator guidance, and Kubernetes integration coverage.

Example: An operator resumes release oce.prod with its originally recorded Job UID.

• Before: The operator must interpret the retained initialization Job manually.
• After: The commands identify a replacement Job, leave the original outcome unknown, and direct the operator to reconcile the original attempt.

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	A useful, conservative feature supported by scoped real-environment rehearsal, retained integration coverage, and successful exact-head required CI.
Proof confidence	🐚 platinum hermit (4/6)	The ordinary contributor proof gate does not apply to this collaborator-authored PR; its body records shipped-CLI Kubernetes rehearsals covering retained and replaced Jobs, restricted readers, Pod ownership, and revoked access, with explicit limits on database and runtime conclusions.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Product

Kind: Feature · Worth it: Yes · Fix scope: Complete
User problem: An operator taking over an interrupted installation needs to distinguish retained Job evidence from unknown effects before deciding where to resume.
Reason: The collaborator-authored direction supplies practical handoff guidance without replaying operations or broadening access.

Merge readiness

✅ Ready for maintainer review

Keep open: this PR provides useful installation handoff guidance absent from current main, with no actionable introduced defect found.

Priority: P2
Reviewed head: 55139f9367f83c22e74715822817318e6ac95d5f

Before merge

None.

Findings

None.

Agent review details

How this fits together

The OCC CLI reads one Helm initialization Job through kubectl using the operator's explicit Kubernetes target and prints bounded status evidence and handoff instructions.

flowchart LR
Operator --> CLI
CLI --> Kubectl
Kubectl --> KubernetesAPI
KubernetesAPI --> RetainedJob
RetainedJob --> Evidence
Evidence --> HandoffPlan

Loading

Technical review

Best possible solution:

Land the bounded read-only handoff through the existing CLI while preserving uncertainty about database effects, API attempts, and runtime readiness.

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

This is a new capability; source inspection confirms current main lacks these commands, and the retained integration exercises their Kubernetes boundary.

Is this the best way to solve the issue?

The existing CLI is an appropriate owner, and explicit target selection, UID correlation, and conservative status interpretation provide a focused solution.

AGENTS.md: found and applied where relevant.

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

Provenance checked

• First-install and intentional-upgrade documentation changes intended behavior with a stated reason (0f50b2c: The chart publication workflow documented installing the selected version; the existing examples used upgrade --install.)
• CI test selection and discovery changes intended behavior with a stated reason (ci(impact): skip checks and conformance 1 on test-only prs that do not list it #1786: Test-only selection omitted the baseline lane because typechecking did not read test files; this PR adds TypeScript test checking and restores baseline selection for those inputs.)
• Upgrade startup validation keeps the original intent (33bb745: Validate Installation changes before migration and API replacement so invalid configuration leaves the existing API serving.)

Testing

Proof path: shipped entry point.

Security

None.

Evidence

What I checked:

• Introduced scope and current-main boundary: The pinned introduction diff adds the handoff commands; current main's installation command still exposes only get and deployment-inventory. (internal/occcli/cli.go:171, 55139f9367f8)
• Bounded Kubernetes read: The production command performs a named Job GET, suppresses raw diagnostics, checks recorded UID correlation, and leaves unsupported or contradictory evidence unresolved. (internal/occcli/installation_doctor.go:139, 55139f9367f8)
• Real Kubernetes integration: The retained test builds the CLI, exercises denial before a binding, grants only named Job GET access, rejects foreign-controller completion, and detects a same-name replacement using a dotted Helm release. (tests/integration/installation-handoff-k3d-real.test.ts:104, 55139f9367f8)
• Scoped rehearsal and credited discussion: The full PR body records a disposable Helm/PostgreSQL handoff rehearsal and separate Pod-access and revocation controls; the author's discussion distinguishes hosted replacement coverage from that rehearsal: Show the next operator where to resume an installation #2905 (comment). (55139f9367f8)
• Exact-head CI and inspection limits: The required CI run succeeded for this head: https://github.com/openclaw/openclaw-enterprise/actions/runs/39223713820. Dispatch cancellation records supersession; the failed OpenShell advisory remains unattributed because its redirected log host was blocked. Some historical blobs were unavailable locally; neither limitation establishes a contributor defect. (55139f9367f8)
• Repository policy applied: Read the complete root AGENTS.md; no nested AGENTS.md or matching maintainer notes were present. Checked implemented architecture, test integrity, source-backed documentation, and workspace boundaries; no tests or review helpers were run and the checkout remained clean. (AGENTS.md:1, 55139f9367f8)

Likely related people:

• Free Wortley: Raw commit a5b9815 adds internal/occcli/cli.go:126 relative to its recorded parents. This identifies author metadata, not feature responsibility or a PR merger. (role: source-line author; confidence: high; commits: a5b98151432b; files: internal/occcli/cli.go)

Labels

Label changes:

No label changes.

Label justifications:

• P2: Useful operator recovery guidance with a limited, read-only installation scope.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit 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 (8 earlier review cycles)

• reviewed 2026-10-19T05:28:52.300Z sha 9f3a689 :: needs changes before merge. :: [P2] Add the required installation-workflow integration test | [P3] Document the new commands in their existing reference and flow
• reviewed 2026-10-19T05:51:14.720Z sha 78ce45b :: needs maintainer review before merge. :: none
• reviewed 2026-10-19T05:57:40.049Z sha 8164a1b :: needs changes before merge. :: none
• reviewed 2026-10-19T06:34:54.624Z sha 32fbbfd :: needs maintainer review before merge. :: none
• reviewed 2026-10-19T07:16:17.029Z sha da1eba5 :: needs maintainer review before merge. :: none
• reviewed 2026-10-19T08:24:59.762Z sha 4d195d3 :: needs changes before merge. :: [P2] Accept dotted Helm release names in both handoff commands
• reviewed 2026-10-19T08:37:57.909Z sha 55139f9 :: needs maintainer review before merge. :: none
• reviewed 2026-10-19T08:42:15.455Z sha 55139f9 :: needs maintainer review before merge. :: none

Reviewed October 19, 2026, 6:03 AM ET / 10:03 UTC (Revision 9).

[freeqaz-openai]

@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/39206769324
• Updated: 2026-10-19T05:52:34.394Z

[freeqaz-openai]

@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/39207315102
• Updated: 2026-10-19T05:59:00.164Z