fix(cli): target portable Podman during cleanup

[senthilr-nv]

Summary

Portable OpenClaw launch cleanup now targets the receipt-owned rootless Podman container instead of querying the unrelated default Docker daemon. The Docker path is unchanged, and portable cleanup still fails closed when runtime, lifecycle generation, socket, or container identity cannot be proved.

Related Issue

Fixes #8584

Changes

• Qualify the local Podman API socket's owner, mode, path chain, and exact identity before permission hardening, then validate the receipt-owned container ID, name, labels, sandbox ID, and running state before privileged cleanup.
• Normalize the current user's Podman socket directory to owner-only 0700 without following symlinks, allowing the standard rootless systemd 0660 socket only inside that private directory.
• Strip ambient Podman remote selectors and pass the qualified local socket explicitly to Docker-compatible registry and exec operations.
• Bind portable receipts to the current registry lifecycle generation, retire them on destroy or re-registration, and restrict legacy receipts to their exact container ID.
• Migrate retained schema-2 installs that predate lifecycle generations only after qualified local Podman authority, exact receipt-owned container identity, and an unchanged full registry-row compare-and-set all succeed.
• Cover successful routing plus stale-receipt, missing, duplicate, renamed, relabeled, replaced, stopped, unsafe-socket, ambient-remote, and endpoint-rotation failures.
• Keep post-merge portable launch evidence on one full E2E target ID for a real chat turn, /exit, exit status 0, and the OpenClaw 2770/660 mutable config permission contract.

Type of Change

• Code change (feature, bug fix, or refactor)
• Code change with doc updates
• Doc only (prose changes, no code sample modifications)
• Doc only (includes code sample changes)

Quality Gates

• Tests added or updated for changed behavior
• Existing tests cover changed behavior — justification:
• Tests not applicable — justification:
• Docs updated for user-facing behavior changes
• Docs not applicable — justification: The command reference and troubleshooting guide already document /exit, exit-code preservation, fail-closed OpenClaw permission restoration, the 2770/660 contract, and the portable Docker-compatible Podman path. This fix restores and hardens that existing contract without adding a supported surface.
• Sensitive paths changed (security, policy, credentials, preflight, onboarding, inference, runner, sandbox, or messaging)
• Sensitive-path review completed or maintainer-approved waiver recorded — reviewer/approval link/justification: The maintainer authored fix(portable): launch cannot clean up OpenClaw permissions under rootless Podman #8584 and explicitly approved implementation. Review covered receipt lifecycle, runtime selection, socket/path identity, permission mutation ordering, and exact container identity with fail-closed negative regression coverage.
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

Documentation Writer Review

• Documentation writer subagent reviewed the completed changes
• Result: no-docs-needed
• Evidence: Recovery now safely completes an interrupted legacy portable receipt migration after the matching sandbox registry generation was committed. It revalidates exact local Podman authority and container identity without repeating the registry update. This transparent retry changes no documented interface, configuration, default, remediation, or support claim.
• Agent: Codex Desktop

DGX Station Hardware Evidence

• Tested on DGX Station
• Tested commit:
• Station profile/scenario:
• Result:
• Supporting evidence:

Verification

• PR description includes a Signed-off-by: line and every commit appears as Verified in GitHub
• Normal pre-commit, commit-msg, and pre-push hooks passed, or npm run validate:pr passed after refreshing origin/main when hooks were skipped or unavailable
• Targeted behavior tests pass for the current change set, or tests are marked not applicable above — command/result or justification: Current PR commit b0b33face passes the focused lifecycle/migration/privileged-exec suites (72/72), Biome, npm run typecheck:cli, npm run checks:repository, npm run test-size:check, npm run test-conditionals:scan, npm run build:cli, git diff --check, and all commit hooks. Its parent dded31205 cleanly merged updated upstream main without changing the PR patch and passed the six focused socket/lifecycle/migration/create-flow/privileged-exec/registry suites (148/148). Earlier npm run test:changed reached 4,213 passing tests; six unrelated 5-second host timeouts occurred in Hermes watcher/rebuild recovery tests, with the rebuild test passing on an isolated rerun.
• Applicable broad gate passed — npm test for broad runtime/test-harness changes; npm run check for repo-wide validation/coverage changes — command/result:
• Quality Gates section completed with required justifications or waivers
• No secrets, API keys, or credentials committed
• npm run docs builds without warnings (doc changes only)
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only)

Independent retained-install acceptance passed on nc-gpu-aug5 without a permission workaround. A preserved schema-2 receipt and Docker registry row with no lifecycle generation were migrated to schema 3 with both receipt and registry bound to container 4019ad7d...f493; a fresh session returned PR8585_B4_RETAINED_OK, /exit returned status 0, Podman parent/socket modes were 0700/0660, and /sandbox/.openclaw plus openclaw.json were 2770/660. The documented Brev 169.254.1.2/32 loopback prerequisite lost during reboot was restored; no chmod or receipt/registry edits were used. Current commit b0b33face additionally makes an interrupted registry-claim/receipt-write migration retry revalidate the same authority and identity before finishing the receipt upgrade without another registry compare-and-set.

---

Signed-off-by: Senthil Ravichandran senthilr@nvidia.com

Summary by CodeRabbit

• Bug Fixes

  • Improved portable-profile recovery and privileged command execution by reliably targeting the correct running sandbox container.
  • Added safeguards for container identity, platform, socket location, runtime authority, lifecycle generation, and running state.
  • Hardened rootless runtime socket directories and validated secure permissions.
  • Restores required sandbox directory and configuration-file permissions after recovery.
  • Improved launch completion handling, including clean exit commands and accurate status reporting.

• Tests

  • Expanded end-to-end coverage for portable launches, recovery, container routing, socket security, receipt lifecycle, and permission restoration.
  • Added automated validation for the portable launch workflow on the main branch.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Portable launch now resolves the receipt-owned rootless Podman container for privileged cleanup. It validates socket authority, container identity, labels, name, and running state. The workflow tests chat, /exit, permission restoration, and exit status.

Changes

Portable Podman execution

Layer / File(s)	Summary
Podman socket authority and host preparation src/lib/adapters/podman/*, src/lib/onboard/experimental/portable-host-preparation.*, test/e2e/live/portable-profile-rootless-linux.test.ts	Podman socket directories are hardened before DOCKER_HOST is set. Socket ownership, permissions, symlink handling, and runtime directory modes are tested.
Receipt-backed Podman target resolution src/lib/onboard/experimental/portable-demo-lifecycle.*	The lifecycle code resolves and validates the receipt-owned rootless Podman container. Tests cover socket authority, identity, state, environment isolation, and socket replacement.
Portable privileged-exec routing src/lib/sandbox/privileged-exec.*	Privileged execution uses the resolved Podman host and container ID with root execution and sanitized environment variables. Docker discovery remains the fallback path.
Portable launch workflow and E2E contract .github/workflows/portable-profile-e2e.yaml, test/e2e/live/*, test/e2e/fixtures/availability-env.ts, test/e2e/support/*, test/e2e/mock-parity.json	The workflow provisions rootless Podman, runs portable launch E2E tests, verifies permissions and exit status, uploads artifacts, and cleans up the runtime.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant LaunchE2E
  participant privilegedSandboxExecArgv
  participant resolvePortableDemoPrivilegedExecTarget
  participant Podman
  LaunchE2E->>privilegedSandboxExecArgv: run portable privileged cleanup
  privilegedSandboxExecArgv->>resolvePortableDemoPrivilegedExecTarget: resolve sandbox target
  resolvePortableDemoPrivilegedExecTarget->>Podman: inspect receipt-owned container
  Podman-->>resolvePortableDemoPrivilegedExecTarget: verified container and socket
  resolvePortableDemoPrivilegedExecTarget-->>privilegedSandboxExecArgv: container ID and Docker host
  privilegedSandboxExecArgv-->>LaunchE2E: execute root cleanup command

Loading

Possibly related PRs

• NVIDIA/NemoClaw#8583: Overlaps in portable lifecycle validation for Podman ownership, naming, identity, and socket authority.
• NVIDIA/NemoClaw#8462: Modifies the portable lifecycle and Podman receipt-handling flow.
• NVIDIA/NemoClaw#8477: Updates shared portable-profile E2E workflow validation.

Suggested reviewers: apurvvkumaria, prekshivyas

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 12.50% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The changes implement receipt-owned Podman cleanup, preserve fail-closed identity checks, retain Docker behavior, and add required regression and E2E coverage for issue #8584.
Out of Scope Changes check	✅ Passed	The workflow, runtime validation, socket hardening, cleanup routing, and tests directly support the linked issue objectives.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the main change: targeting the portable Podman container during cleanup.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/fix-portable-cleanup-8584

---

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

[github-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall coverage in commit 96ddc71 in the codex/fix-portable-c... branch remains at 96%, unchanged from commit a506354 in the main branch.

---

_{Updated August 08, 2026 01:09 UTC}

[github-actions]

PR Review Advisor — No blocking findings reported

Advisor assessment: No blocking advisor findings reported
Next action: No advisor follow-up needed.
Findings: 0 blockers · 0 warnings · 0 suggestions

Model lanes

• GPT-5.6 Terra (primary): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Nemotron 3 Ultra (second opinion): Failed after a partial review · low confidence · 0 blockers · 1 warning · 1 suggestion

Second-opinion terminology and E2E selections are advisory. Live E2E does not run automatically for pull requests.

3 semantic terminology decisions

Terminology decisions are advisory. They affect the assessment only when a separate finding identifies concrete semantic impact.

• established — lifecycle generation at src/lib/state/registry/lifecycle-generation.ts:9: Keep `lifecycle generation`; it matches established repository usage.
• established — receipt-owned at src/lib/onboard/experimental/portable-demo-lifecycle.ts:504: Keep `receipt-owned`; it matches established repository usage.
• established — socket authority at src/lib/adapters/podman/socket-authority.ts:88: Keep `socket authority`; the new hardening path expands enforcement without changing its established meaning.

E2E guidance

Advisory only. A maintainer can dispatch the default E2E suite against this exact revision.

Recommended E2E: cloud-inference, cloud-onboard, managed-image-multiarch-startup, managed-image-protected-runtime, security-posture, full-e2e, onboard-repair, onboard-resume

Workflow run details

This automated review informs maintainers. Warnings and suggestions do not require a response. A maintainer decides whether to merge.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.github/workflows/portable-profile-e2e.yaml:
- Around line 152-167: Update the `--user try-restart podman.service` branch to
launch a replacement `podman system service` after stopping the existing process
and removing its socket. Reuse the startup, PID-file, socket-waiting, and
failure-reporting behavior from the `--user enable --now podman.socket` branch
so the socket is available before returning.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: c3fc6670-9efe-422a-b2da-543061654389

📥 Commits

Reviewing files that changed from the base of the PR and between cdaefe8 and 73390f9.

📒 Files selected for processing (11)

• .github/workflows/portable-profile-e2e.yaml
• src/lib/onboard/experimental/portable-demo-lifecycle.test.ts
• src/lib/onboard/experimental/portable-demo-lifecycle.ts
• src/lib/sandbox/privileged-exec.test.ts
• src/lib/sandbox/privileged-exec.ts
• test/e2e/fixtures/availability-env.ts
• test/e2e/live/full-e2e.test.ts
• test/e2e/live/launch-agent-turn.ts
• test/e2e/mock-parity.json
• test/e2e/support/e2e-workflow.test.ts
• test/e2e/support/launch-agent-turn.test.ts

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/lib/onboard/experimental/portable-demo-lifecycle.ts`:
- Around line 434-440: Update the provider construction in the sandbox lifecycle
to always pass a sanitized capture created with podman and podmanEnv, rather
than conditionally spreading it only when deps.podman exists. Ensure every
provider.capture invocation, including ps and inspect, uses podmanEnv and the
validated local Podman runtime.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: ad8e28b6-41ab-4e65-b227-7a0381c434b5

📥 Commits

Reviewing files that changed from the base of the PR and between a1b9e60 and cea4b23.

📒 Files selected for processing (5)

• src/lib/adapters/podman/index.ts
• src/lib/onboard/experimental/portable-demo-lifecycle.test.ts
• src/lib/onboard/experimental/portable-demo-lifecycle.ts
• src/lib/sandbox/privileged-exec.test.ts
• src/lib/sandbox/privileged-exec.ts

🚧 Files skipped from review as they are similar to previous changes (2)

• src/lib/sandbox/privileged-exec.test.ts
• src/lib/sandbox/privileged-exec.ts

[senthilr-nv]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

🧹 Nitpick comments (1)

src/lib/onboard/experimental/portable-demo-lifecycle.test.ts (1)

340-346: 🔒 Security & Privacy | 🔵 Trivial | ⚡ Quick win

Assert the hardening order, not only the call.

Line [346] verifies that hardenSocketDirectory received SOCKET_PATH, but it does not verify that hardening completes before socket-authority capture. If that order regresses, this test still passes while the authority guarantee is untested. Record events in the injected hardener and socketAuthorityDeps, then assert that hardening occurs first, matching src/lib/onboard/experimental/portable-demo-lifecycle.ts Lines [419-462].

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/lib/onboard/experimental/portable-demo-lifecycle.test.ts` around lines
340 - 346, Update the resolveTarget test around hardenSocketDirectory to record
ordered events from the injected hardener and socketAuthorityDeps callbacks.
Assert that the hardening event occurs before socket-authority capture, while
retaining the existing SOCKET_PATH argument assertion and result expectations.

Source: Path instructions

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@src/lib/onboard/experimental/portable-demo-lifecycle.test.ts`:
- Around line 340-346: Update the resolveTarget test around
hardenSocketDirectory to record ordered events from the injected hardener and
socketAuthorityDeps callbacks. Assert that the hardening event occurs before
socket-authority capture, while retaining the existing SOCKET_PATH argument
assertion and result expectations.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 046893cf-0bb3-40c7-8273-093969ee374e

📥 Commits

Reviewing files that changed from the base of the PR and between ede0211 and e99ada7.

📒 Files selected for processing (9)

• .github/workflows/portable-profile-e2e.yaml
• src/lib/adapters/podman/index.ts
• src/lib/adapters/podman/socket-authority.test.ts
• src/lib/adapters/podman/socket-authority.ts
• src/lib/onboard/experimental/portable-demo-lifecycle.test.ts
• src/lib/onboard/experimental/portable-demo-lifecycle.ts
• src/lib/onboard/experimental/portable-host-preparation.test.ts
• src/lib/onboard/experimental/portable-host-preparation.ts
• test/e2e/live/portable-profile-rootless-linux.test.ts

🚧 Files skipped from review as they are similar to previous changes (8)

• src/lib/adapters/podman/index.ts
• src/lib/onboard/experimental/portable-host-preparation.ts
• test/e2e/live/portable-profile-rootless-linux.test.ts
• src/lib/adapters/podman/socket-authority.ts
• src/lib/adapters/podman/socket-authority.test.ts
• src/lib/onboard/experimental/portable-host-preparation.test.ts
• .github/workflows/portable-profile-e2e.yaml
• src/lib/onboard/experimental/portable-demo-lifecycle.ts

[senthilr-nv]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[senthilr-nv]

Exact-head independent live acceptance passed for the production change in this PR.

• Tested SHA: e99ada704694bb8e92847a44b5fc1fefc0d1f783
• Environment: retained receipt-bound portable sandbox on nc-gpu-aug5
• Manual socket workaround: none
• Initial Podman parent/socket: 0755 nvidia:nvidia / 0660 nvidia:nvidia
• Real chat result: PR8585_E99_LIVE_OK with successful final status
• /exit: launch_exit=0, with no cleanup error
• Post-run Podman parent/socket: 0700 nvidia:nvidia / 0660 nvidia:nvidia
• Restored sandbox modes: /sandbox/.openclaw = 2770 sandbox:sandbox; openclaw.json = 660 sandbox:sandbox

Independent code review found no correctness, security, scope, or coverage blockers. Current head 6747593aeb00ead2d394a76e6468059dec4d9458 only adds the CodeRabbit-requested hardening-order regression assertion; production bytes are unchanged from the tested SHA.

[prekshivyas]

Requesting changes for three blocking issues:

1. A stale portable receipt can take precedence over the registry's current runtime owner and route privileged execution to an old Podman container.
2. Portable host preparation honors ambient Podman remote selectors before applying a local chmod to the returned socket path.
3. The new portable-launch E2E emits mismatched target IDs between declaration and completion.

I ran the focused suite (122 tests) and typecheck successfully; these are missing lifecycle and evidence contracts rather than existing test failures.

[prekshivyas]

changes on 197af2f

[P1] Linux CI deterministically fails. The socket test creates its fixture beneath /tmp, while the production code correctly rejects world-writable path components. This already failed CLI shard 2; the test is unchanged in the latest head. Create the fixture beneath a secure directory such as the real user home.

[P2] Portable E2E path filtering misses src/lib/adapters/podman/**. Future isolated changes to this socket-security boundary would not trigger the portable-profile workflow. Add that path and cover it in portableProofInputs.

The original three requested changes are properly addressed: registry-generation binding, sanitized/prequalified Podman sockets, and consistent E2E target IDs. I found no remaining production security blocker across authorization, injection, secrets, dependencies, or error handling. Local focused tests passed: 145 CLI + 47 E2E-support.

[senthilr-nv]

@prekshivyas The retained-install compatibility blocker is addressed at exact head 58cdb28a224aec27544ca1336a82bba350b3120a. A schema-2 receipt whose Docker registry row lacks lifecycleGeneration is now migrated only after qualified local Podman authority, unique exact receipt-owned container identity, expected immutable labels/sandbox ID, and a full unchanged registry-row compare-and-set all succeed. Driver/generation mismatch, replacement, ambiguity, and stale registry state remain fail-closed; the receipt is upgraded to schema 3 only after the registry claim succeeds. Regression coverage exercises real on-disk schema-2/no-generation recovery and privileged cleanup plus ambiguous identity and CAS-failure cases. Focused suites pass 105/105, CLI typecheck/repository/test-size/build/diff checks and normal hooks pass, and the documentation-writer review is PASS (no-docs-needed). Please re-review this exact head; retained current-main/schema-2 live validation has also been requested.

[senthilr-nv]

@prekshivyas The exact head is now 89e1a4f9b8c1a69dc8aa83ae267d129adb86bc50. The only delta from the retained-install migration commit is test-only: the new Podman fixture uses a declarative handler table instead of three if statements, resolving the valid codebase-growth-guardrails failure. Production bytes and regression assertions are unchanged. The migration suite passes 4/4, npm run test-conditionals:scan passes, normal hooks pass, both commits are GitHub-verified, and the final documentation-writer receipt is PASS. Please re-review this exact head.

[senthilr-nv]

@prekshivyas The exact head is now b4a656a4c78f37ef1e7744924c0a09a29b2680b5. I addressed the valid CLI shard failure: the real Unix-socket hardening test had created its fixture beneath world-writable /tmp, which production correctly rejects. The fixture now uses the secure real repository working directory; production bytes, assertions, and migration behavior are unchanged. The socket-authority suite passes 7/7, Biome/diff checks and normal hooks pass, the commit is GitHub-verified, and the final documentation-writer receipt is PASS. Please re-review this exact head.

[senthilr-nv]

@prekshivyas The interrupted schema-2 migration retry gap is addressed in current PR commit b0b33facecd974237a7c1249f86066abd305c15d.

Recovery now re-enters qualified local Podman authority and receipt-owned container validation when a schema-2 receipt already matches the registry generation, then finishes the schema-3 receipt write without repeating the registry compare-and-set. Schema-1 startup-refresh behavior remains unchanged. The new regression pre-commits the registry generation, verifies no second CAS, verifies qualified socket discovery, and verifies the receipt advances to schema 3 with the same generation.

Validation: focused lifecycle/migration/privileged-exec suites 72/72; Biome; CLI type-check; repository, test-size, and conditional guards; CLI build; commit and pre-push hooks; and diff check all pass. The documentation writer review is PASS with no docs needed.

Independent retained-install acceptance also passed on nc-gpu-aug5: a preserved schema-2 receipt and registry row with no generation migrated to schema 3, a fresh session returned PR8585_B4_RETAINED_OK, /exit returned status 0, Podman parent/socket modes were 0700/0660, and sandbox config modes were 2770/660. Only the documented Brev loopback prerequisite lost during reboot was restored; no chmod or receipt/registry edits were used.

Please re-review the current commit.