feat: reset an installation with clawctl setup --fresh

[paulcam206]

What Problem This Solves

An operator needs a bounded reset path for a broken installation that stays within owned agent data and reports cleanup failures accurately.

User Impact

clawctl setup --fresh performs a lifecycle-locked reset with pre-reset diagnostics. It is destructive to that installation's agent data; --fresh --force can proceed while explicitly reporting resources it could not remove.

Why This Change Was Made

The reset captures diagnostics before removal and validates the complete ancestor chain before recursive cleanup, keeping deletion within owned paths. It is a bounded installation reset, not a general machine cleanup tool.

Review fixes addressed

• Setup refuses before preparing a host runtime when the Windows build cannot support an isolated session, including clawctl setup --no-isolation on that unsupported build. On a supported build, --no-isolation remains session-free host-runtime setup.
• Gateway Detail returned by inspection is restored to clawctl gateway-service status and stop output.
• Diagnostic output uses a bounded, sanitized log tail so support detail remains useful without exposing unbounded guest output.
• Cleaner containment is handle-bound and validates redirected ancestors before recursive deletion, keeping cleanup inside the owned boundary.
• Cancellation guidance names the operation actually cancelled; only a cancelled fresh reset directs the operator back to --fresh.

Current validation

Latest review hardening: unpackaged automatic direct routing no longer creates a session runtime, and ANSI sanitization consumes complete CSI sequences so control parameters cannot leak into rendered output.

Current layer head: d550ecaae7f0ec009e457431a13174143b0d6244. This layer is included in the final integrated stack tip cce2b02f3acd5791654b7a6b1a5a9c27db5ff63b rebased onto 685ee93b7ebbec1e784205a3544c460bea740e11.

Integrated local gates: exact .NET SDK 10.0.100; Test-DotNetQuality.ps1 with 0 warnings/errors; full solution tests 642/642; NativeAOT x64 and ARM64 publishes for both launcher and session host; NativeAOT CLI, deployment, MXC, signing, runtime-input, release-identity, bundle, isolation-plugin, and packaging-relevance policy suites.

Live x64 MXC evidence: final-tip Developer Mode deployment registered OpenClaw.Gateway_0.1.2451.40134_x64__kaa03rpbbqef6 from workflow payload run 35191206689; openclaw --version returned OpenClaw 2026.9.4 (3a9d69d); clawctl status confirmed the isolated session was running. Earlier final-tip validation also exercised setup, Node.js 24.20.0 reuse, package-qualified activation, detached gateway launch, and redacted diagnostics collection.

Signed package evidence: local NativeAOT x64 and ARM64 packages and a multi-architecture bundle were composed and test-signed. Elevated upgrade validation passed all four proof-release transitions (v0.0.0.0 and v0.0.0.1, standalone and bundle), retained package-family LocalState in every transition, and accepted fresh standalone and bundle installs. The temporary certificate and test package were removed, then the Developer Mode registration was restored.

Layer 10 of 12. Parent: #51 - fix/session-lifecycle-recovery. Child: #53 - docs/session-runtime

[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 real behavior proof before merge. Reviewed September 17, 2026, 4:01 PM ET / 20:01 UTC (Revision 26).

ClawSweeper review

What this changes

Adds an explicit installation reset with pre-reset diagnostics, optional forced recovery, bounded local cleanup, and sanitized gateway log output.

Merge readiness

⛔ Blocked before merge - 5 items remain

This remains useful work absent from the default branch. The reviewed fixes address the earlier code concerns, but destructive-reset authority still needs focused production-path evidence before merge.

Priority: P2
Reviewed head: d550ecaae7f0ec009e457431a13174143b0d6244

Review scores

Measure	Result	What it means
Overall readiness	🦐 gold shrimp (3/6)	The implementation and supplemental tests are useful, while unresolved final-effect authority proof limits merge confidence.
Proof confidence	🦐 gold shrimp (3/6)	Needs stronger real behavior proof before merge: Authority-chain proof required: the captured Windows setup/status and signed-upgrade observations do not exercise InstallationLifecycle through physical fresh cleanup. Show an allowed nonempty reset, outside sentinels surviving path replacement, and foreign or stale ownership rejected before backend deletion or automatic host launch. Only this authority-specific requirement applies to the collaborator-authored PR. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
Patch quality	🦐 gold shrimp (3/6)	Security review found an item that needs attention.

Verification

Check	Result	Evidence
Real behavior	Needs proof	Needs stronger real behavior proof before merge: Authority-chain proof required: the captured Windows setup/status and signed-upgrade observations do not exercise InstallationLifecycle through physical fresh cleanup. Show an allowed nonempty reset, outside sentinels surviving path replacement, and foreign or stale ownership rejected before backend deletion or automatic host launch. Only this authority-specific requirement applies to the collaborator-authored PR. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
Evidence reviewed	8 items	Default branch still lacks reset: The default-branch command tree exposes setup without fresh or force options. The supplied related stack remains open; no merged replacement establishes that this work is obsolete. Release boundary: GitHub identifies v2026.9.4-msix.0 as the latest release, targeting the inspected default-branch revision; it does not contain this reset command. Introduced reset and recovery boundary: The pinned base-to-head diff validates package inputs, holds the lifecycle lock, records diagnostics, tears down external resources, and clears local state. Force explicitly permits local cleanup after unconfirmed external cleanup and warns that cleared ownership records cannot support later automatic removal.
Findings	None	None.
Security	Needs attention	Demonstrate containment at the final destructive operation: The cleaner uses validated handles, but the available evidence does not exercise the installation lifecycle with post-validation path replacement or foreign/stale ownership and show rejection before destructive I/O.

How this fits together

The Windows launcher manages the packaged OpenClaw runtime and its isolated agent session. Reset combines operator flags, saved ownership records, backend teardown, and local filesystem cleanup before provisioning a replacement session.

flowchart TD
  A[Operator requests fresh setup] --> B[Validate package and session support]
  B --> C[Lock lifecycle and save diagnostics]
  C --> D[Remove owned session and recovery]
  D --> E{Cleanup confirmed or force selected}
  E -->|No| F[Report incomplete reset]
  E -->|Yes| G[Clear validated local roots]
  G --> H[Provision session and report result]

Loading

Before merge

• Add real behavior proof - Needs stronger real behavior proof before merge: Authority-chain proof required: the captured Windows setup/status and signed-upgrade observations do not exercise InstallationLifecycle through physical fresh cleanup. Show an allowed nonempty reset, outside sentinels surviving path replacement, and foreign or stale ownership rejected before backend deletion or automatic host launch. Only this authority-specific requirement applies to the collaborator-authored PR. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
• Resolve security concern: Demonstrate containment at the final destructive operation - The cleaner uses validated handles, but the available evidence does not exercise the installation lifecycle with post-validation path replacement or foreign/stale ownership and show rejection before destructive I/O.
• Resolve merge risk (P1) - Host-authority deletion traverses storage associated with the isolated session; the supplied evidence does not demonstrate outside-data preservation during post-validation path replacement or rejection of foreign/stale ownership before final effects.
• Resolve merge risk (P1) - Forced reset intentionally clears ownership records despite unresolved external cleanup, potentially leaving resources that require backend administrative removal; production reset evidence has not established this recovery outcome.
• Complete next step (P2) - Add the scoped Windows reset and authority evidence described above, including forced-reset residual reporting. Terminal output or logs are sufficient; screenshots or recordings are welcome when they show the observations. Redact private paths, endpoints, credentials, and personal identifiers. Update the PR body to trigger re-review; if needed, ask a maintainer to comment @clawsweeper re-review.

Findings

• [medium] Demonstrate containment at the final destructive operation — src/OpenClaw.Launcher/Session/InstallationStateCleaner.cs:65

Agent review details

Security

Needs attention: No concrete exploit was established, but the destructive authority boundary retains a material proof gap.

Review metrics

Metric	Value	Why it matters
Production and test growth	Production +893/-241 (net +652); tests +1199/-154 (net +1045)	Production growth is explained by the reset lifecycle, containment cleaner, and diagnostic output; tests account for most added lines.

Merge-risk options

Maintainer options:

1. Demonstrate the reset boundary (recommended)
   Provide Windows production-path evidence covering owned reset completion, outside-data preservation, ownership rejection, and forced-reset residual reporting.

Technical review

Best possible solution:

Retain the explicit, bounded reset design with final-effect containment proof and observable recovery guidance when forced cleanup leaves external resources behind.

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

Not applicable as a feature request; no new concrete code defect was established, and the destructive Windows path was not executed during this read-only review.

Is this the best way to solve the issue?

Yes, the explicit lifecycle-locked reset is a coherent extension of existing teardown and setup; merge confidence still depends on proving containment and recovery through the production boundary.

AGENTS.md: not found in the target repository.

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

Labels

Label justifications:

• P2: This is a bounded operator recovery feature without evidence of an urgent released regression.
• merge-risk: 🚨 security-boundary: The reset introduces host-authority deletion whose containment under adversarial path replacement needs final-effect proof.
• merge-risk: 🚨 session-state: Forced reset can discard ownership records while external resources remain unresolved.
• rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🦐 gold shrimp and patch quality is 🦐 gold shrimp.
• status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs stronger real behavior proof before merge: Authority-chain proof required: the captured Windows setup/status and signed-upgrade observations do not exercise InstallationLifecycle through physical fresh cleanup. Show an allowed nonempty reset, outside sentinels surviving path replacement, and foreign or stale ownership rejected before backend deletion or automatic host launch. Only this authority-specific requirement applies to the collaborator-authored PR. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Evidence

Security concerns:

• [medium] Demonstrate containment at the final destructive operation — src/OpenClaw.Launcher/Session/InstallationStateCleaner.cs:65
  The cleaner uses validated handles, but the available evidence does not exercise the installation lifecycle with post-validation path replacement or foreign/stale ownership and show rejection before destructive I/O.
  Confidence: 0.9

What I checked:

• Default branch still lacks reset: The default-branch command tree exposes setup without fresh or force options. The supplied related stack remains open; no merged replacement establishes that this work is obsolete. (src/OpenClaw.Launcher/ClawCtlCommandLine.cs, 685ee93b7ebb)
• Release boundary: GitHub identifies v2026.9.4-msix.0 as the latest release, targeting the inspected default-branch revision; it does not contain this reset command. (685ee93b7ebb)
• Introduced reset and recovery boundary: The pinned base-to-head diff validates package inputs, holds the lifecycle lock, records diagnostics, tears down external resources, and clears local state. Force explicitly permits local cleanup after unconfirmed external cleanup and warns that cleared ownership records cannot support later automatic removal. (src/OpenClaw.Launcher/Program.cs:453, d550ecaae7f0)
• Physical deletion authority: The cleaner captures root identities, reopens validated directories, and delegates deletion to handle-relative traversal. The existing TrustedPath implementation separates traversal handles from delete handles; failed deletion of a remaining entry prevents successful cleanup. (src/OpenClaw.Launcher/Session/InstallationStateCleaner.cs:65, d550ecaae7f0)
• Discussion and prior concerns addressed: The disabled-isolation branch now rejects fresh reset before host preparation, addressing ChazGo's combination concern at feat: reset an installation with clawctl setup --fresh #52 (comment). Automatic unpackaged routing avoids creating a session runtime; packaged fallback validates saved ownership; gateway output consumes complete CSI sequences. Session-only management remains separate from host-runtime preparation. (src/OpenClaw.Launcher/Program.cs:430, d550ecaae7f0)
• Captured proof and remaining coverage: The complete supplied body at sourceRevision d475511ffa6d1fa506d1f62ef646bfadd35955df0f69b4c893dbb9795a48e178 reports integrated Windows setup/status, NativeAOT validation, and four signed upgrade transitions with LocalState retained. Those are useful observations, but none reports physical fresh-reset completion or forbidden-owner/path-replacement outcomes. Reset orchestration tests substitute FailingFreshLifecycle, RecordingCleaner, and a fake MXC client; standalone cleaner tests provide supplemental filesystem coverage. (tests/OpenClaw.Launcher.Tests/ProgramTests.cs:481, d550ecaae7f0)

Likely related people:

• paulcam206: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)
• Linus Huang: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)

Rank-up moves

Optional improvements that raise the rating; they are not merge blockers.

• Add redacted Windows production-path output showing nonempty reset completion and the outcome of forced recovery after incomplete external cleanup.
• Show outside sentinels surviving path replacement and foreign or stale ownership rejected before backend deletion or automatic host launch.

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

History

Review history (25 earlier review cycles; latest 8 shown)

• reviewed 2026-09-17T16:11:46.062Z sha da65d8d :: needs real behavior proof before merge. :: [P2] Preserve automatic direct startup without package identity | [P3] Consume the full ANSI sequence before resuming log output
• reviewed 2026-09-17T16:23:56.893Z sha 378a702 :: needs real behavior proof before merge. :: [P2] Preserve automatic direct startup without package identity | [P3] Consume the full ANSI sequence before resuming log output
• reviewed 2026-09-17T16:38:45.944Z sha 3efca09 :: needs real behavior proof before merge. :: [P2] Preserve automatic direct startup without package identity | [P3] Consume the full ANSI sequence before resuming log output
• reviewed 2026-09-17T16:57:37.571Z sha abc7020 :: needs real behavior proof before merge. :: [P2] Preserve automatic direct startup without package identity | [P3] Consume the full ANSI sequence before resuming log output
• reviewed 2026-09-17T17:05:16.497Z sha abc7020 :: needs real behavior proof before merge. :: [P2] Preserve automatic direct startup without package identity | [P3] Consume the full ANSI sequence before resuming log output
• reviewed 2026-09-17T19:02:33.851Z sha b7d8091 :: needs real behavior proof before merge. :: [P2] Avoid conflicting delete access when retaining the cleanup root
• reviewed 2026-09-17T19:22:51.117Z sha 9e9a97d :: needs real behavior proof before merge. :: none
• reviewed 2026-09-17T19:40:20.187Z sha df91da6 :: needs real behavior proof before merge. :: none