openclaw - 💡(How to fix) Fix Clarify session retention semantics: .deleted archives and pruneAfter double duty are misleading [2 comments, 2 participants]

Session retention semantics are currently hard to reason about, both for humans and LLM agents operating OpenClaw.

This is not a data-loss bug. The observed behavior appears technically intentional, but the terminology/configuration shape is very misleading in practice.

Current confusing behavior

There are at least these distinct states:

VISIBLE
= entry exists in sessions.json, transcript is <sessionId>.jsonl

.deleted.* FILE
= entry was removed from sessions.json, but transcript still exists as <sessionId>.jsonl.deleted.<timestamp>

PHYSICALLY REMOVED
= no sessions.json entry and no transcript file remains

The problem is that .deleted.* does not mean “deleted” in the normal operator sense. It means “removed from the session store but retained on disk”. That is closer to “archived”, “detached”, or “removed-from-store”.

This is especially confusing when debugging or asking an agent to reason about whether a session was deleted. Humans naturally read “deleted” as “gone”; here it means “renamed and retained”.

pruneAfter also does double duty

session.maintenance.pruneAfter appears to control two different transitions:

1. VISIBLE entry older than pruneAfter
   → remove entry from sessions.json
   → rename transcript to *.deleted.<timestamp>

2. existing *.deleted.* older than pruneAfter
   → physically remove the file

So the same setting controls both:

VISIBLE → .deleted.* FILE
.deleted.* FILE → PHYSICALLY REMOVED

That makes deterministic explanation hard. It also makes “pruneAfter” ambiguous: is it the visible session retention, or the retained transcript retention? Currently it is both.

cron.sessionRetention behaves similarly for isolated cron run sessions: it first removes the cron session entry and renames the transcript to .deleted.*, then a later cleanup removes .deleted.* files after the same retention window.

Subagent timer confusion

agents.defaults.subagents.archiveAfterMinutes is also easy to misread as a hard retention guarantee. In practice it is a best-effort/in-memory timer; if the Gateway restarts, pending subagent timers can be lost, and old subagent sessions remain visible until manual cleanup or session.maintenance.pruneAfter catches them.

Why this matters

OpenClaw agents often inspect/manage their own sessions. In a real debugging session, even GPT-5.5 repeatedly produced wrong explanations after seeing the config because the state names and retention knobs are counterintuitive:

• “deleted from session store”
• “renamed to .deleted.* but retained”
• “physically removed from disk”

all sound too similar under the current terminology.

Suggested improvements

1. Rename the .deleted. suffix to something that does not imply physical deletion, e.g.:

   • .archived.
   • .detached.
   • .removed-from-store.
   • .retained.

   Backward compatibility could keep recognizing existing .deleted.* files.

2. Split session.maintenance.pruneAfter into two explicit settings, for example:

session.maintenance.detachAfter = "10d"
session.maintenance.deleteDetachedAfter = "10d"

or:

session.maintenance.visibleEntryRetention = "10d"
session.maintenance.retainedTranscriptRetention = "10d"

1. Document lifecycle as explicit state transitions, e.g.:

VISIBLE
→ RESET-FILE
→ PHYSICALLY REMOVED

VISIBLE
→ DETACHED/ARCHIVED-FILE
→ PHYSICALLY REMOVED

1. Document that subagent archiveAfterMinutes is best-effort and can be lost on Gateway restart.

2. Document that isolated cron sessionRetention first detaches/renames the transcript, and only later physically removes the retained transcript.

The core request: make the state names and config knobs match operator intuition, so “deleted” means physically gone, while retained transcripts use a non-destructive term like “archived” or “detached”.