OpenClaw CLI Adds Safe Session Archive and Delete Commands on Main

OpenClaw has merged supported CLI lifecycle commands for retiring exact sessions from SSH, CI and other headless workflows:

openclaw sessions archive <key...>
openclaw sessions delete <key...>

The commands are on main; the supplied evidence does not identify a containing release. Do not paste them into production automation until the installed CLI proves it has the new help and behaviour.

What the commands actually own

PR #118791 implements thin Gateway-backed clients rather than direct SQLite mutation:

• archive uses sessions.patch with archived: true;
• delete uses sessions.delete with transcript deletion and the Control UI’s state-aware archived gate;
• keys are preflighted through sessions.list, including archived rows;
• mutations run sequentially and carry the listed session identity as a lifecycle race guard.

That design matters. Session retirement can include transcripts, active runtime state, archives and managed worktrees. A script deleting rows directly would bypass canonical cleanup and cache invalidation.

Safety controls

Both commands support multiple exact keys, --dry-run and --json. Global keys can be scoped with --agent <id>, and Gateway connection settings can be overridden through the supported CLI options.

Deletion requires interactive confirmation unless automation explicitly supplies --yes. Mixed-validity input continues valid keys in order but returns a non-zero exit, so a batch runner must inspect every result rather than treating partial completion as total success.

The upstream record says confirmed deletion reports retained transcript archives and preserved managed worktrees that still require manual cleanup. “Session deleted” therefore does not necessarily mean every associated filesystem artifact was erased.

Archive before delete

Archiving is the safer default when the goal is to remove clutter or retire a load-test key. It preserves a supported path for later inspection while taking the session out of ordinary active views.

Delete only after establishing:

1. the exact agent and session key;
2. whether a run is still active;
3. whether external side effects need reconciliation;
4. where transcript archives are retained; and
5. whether a managed worktree must remain for investigation or be cleaned separately.

Never derive deletion targets from an unreviewed substring match.

Related cache fixes

PR #118768 stops sessions.list from indefinitely caching results whose activeMinutes or completed-child visibility changes as wall-clock time advances. Temporal requests still share one in-flight projection, but completed time-dependent projections are not reused after their boundary passes.

PR #118766 invalidates live SQLite session caches only after Doctor repairs commit, preventing warm readers from retaining stale delivery accounts, parent keys or spawnedBy references.

Interpretation: lifecycle commands are only as safe as the list and identity data used to select their targets. Fresh temporal projections and post-commit cache invalidation reduce the chance of acting on an obsolete view; they do not remove the need to identify exact keys.

Acceptance test

Use disposable sessions with unique markers:

1. create one active, one completed and one already archived fixture;
2. run archive and delete with --dry-run --json and prove no state changed;
3. submit one valid and one invalid key, then verify ordered partial results and a non-zero exit;
4. confirm delete refuses without interaction or --yes;
5. archive an exact key and verify it leaves the active view but appears in archived listing;
6. delete one archived and one active fixture intentionally, then verify unrelated sessions remain;
7. inspect reported transcript archives and managed worktrees rather than assuming they disappeared; and
8. cross an activeMinutes boundary and confirm a new list response reflects wall-clock expiry.

Do not run a destructive test against a session whose tools may still be executing.

Evidence and limits

The official merged PR and commit records establish the commands and cache corrections. Upstream reports built CLI help, 78 focused lifecycle/Gateway tests and a source-blind isolated Gateway proof covering dry-run, partial failure, confirmation and multi-delete behaviour. Direct GitHub extraction returned HTTP 403; the configured search backend was unavailable.

OpenClaw Academy did not delete a live session or inspect a packaged CLI. Option names and cleanup semantics should be verified with the containing build’s own help and official documentation.

Relevant collector IDs are 36435, 36297, 36386, 36215, 36124, 36217 and 36126.

Bottom line

Headless session retirement finally has a supported path. Prefer archive, dry-run exact keys, parse every result, require an explicit destructive confirmation and let the Gateway—not ad hoc SQL—own cleanup.