mocks.resolveMaintenanceConfig.mockReturnValue({

mode: "warn",

pruneAfterMs: 7 * 24 * 60 * 60 * 1000,

modelRunPruneAfterMs: null,

modelRunPruneAfterConfigured: true,

maxEntries: 500,

resetArchiveRetentionMs: 7 * 24 * 60 * 60 * 1000,

maxDiskBytes: null,

"session.maintenance.maxEntries":

"Caps total session entry count retained in the store to prevent unbounded growth over time. Use lower limits for constrained environments, or higher limits when longer history is required.",

"session.maintenance.modelRunPruneAfter":

"Retention for short-lived gateway model-run probe sessions (`agent:*:explicit:model-run-<uuid>`). Accepts a duration such as `24h` or `2d`; set `false` to disable model-run-specific cleanup. Default: `24h`.",

"Retention for short-lived gateway model-run probe sessions (`agent:*:explicit:model-run-<uuid>`). Default: `24h`, but the unset default only runs under session-entry cap pressure. Set a duration such as `24h` or `2d` for normal age-based cleanup, or `false` to disable.",

"session.maintenance.rotateBytes":

'Deprecated and ignored. Do not use for `sessions.json` growth control; OpenClaw no longer creates automatic rotation backups, and "openclaw doctor --fix" removes this key.',

"session.maintenance.resetArchiveRetention":

capEntryCount,

pruneStaleModelRunEntries,

pruneStaleEntries,

shouldRunModelRunPrune,

type ResolvedSessionMaintenanceConfig,

} from "./store-maintenance.js";

import { loadSessionStore } from "./store.js";

})

: 0;

const preserveSessionKeys = collectSessionMaintenancePreserveKeys([params.activeKey]);

const modelRunPruned = pruneStaleModelRunEntries(

previewStore,

params.maintenance.modelRunPruneAfterMs,

{

log: false,

preserveKeys: preserveSessionKeys,

onPruned: ({ key }) => {

modelRunPrunedKeys.add(key);

},

},

);

const modelRunPruned = shouldRunModelRunPrune({

maintenance: params.maintenance,

entryCount: Object.keys(previewStore).length,

})

? pruneStaleModelRunEntries(previewStore, params.maintenance.modelRunPruneAfterMs, {

log: false,

preserveKeys: preserveSessionKeys,

onPruned: ({ key }) => {

modelRunPrunedKeys.add(key);

},

})

: 0;

const pruned = pruneStaleEntries(previewStore, params.maintenance.pruneAfterMs, {

log: false,

preserveKeys: preserveSessionKeys,

pruneAfterMs: number;

maxEntries: number;

modelRunPruneAfterMs: number | null;

modelRunPruneAfterConfigured: boolean;

resetArchiveRetentionMs: number | null;

maxDiskBytes: number | null;

highWaterBytes: number | null;

capEntryCount,

pruneStaleEntries,

pruneStaleModelRunEntries,

shouldRunModelRunPrune,

shouldRunSessionEntryMaintenance,

type ResolvedSessionMaintenanceConfig,

} from "./store-maintenance.js";

let capped = 0;

if (maintenance.mode === "enforce") {

const preserveSessionKeys = collectSessionMaintenancePreserveKeys();

modelRunPruned = pruneStaleModelRunEntries(store, maintenance.modelRunPruneAfterMs, {

log: false,

preserveKeys: preserveSessionKeys,

});

if (

shouldRunModelRunPrune({

maintenance,

entryCount: beforeCount,

})

) {

modelRunPruned = pruneStaleModelRunEntries(store, maintenance.modelRunPruneAfterMs, {

log: false,

preserveKeys: preserveSessionKeys,

});

}

}

if (maintenance.mode === "enforce" && Object.keys(store).length > maintenance.maxEntries) {

const preserveSessionKeys = collectSessionMaintenancePreserveKeys();

getActiveSessionMaintenanceWarning,

pruneStaleModelRunEntries,

pruneStaleEntries,

shouldRunModelRunPrune,

shouldRunSessionEntryMaintenance,

type ResolvedSessionMaintenanceConfig,

type SessionMaintenanceWarning,

params.operation.activeSessionKey,

]);

const removedSessionFiles = new Map<string, string | undefined>();

const modelRunPruned = pruneStaleModelRunEntries(

params.operation.store,

params.maintenance.modelRunPruneAfterMs,

{

onPruned: ({ entry }) => {

rememberRemovedSessionFile(removedSessionFiles, entry);

},

preserveKeys: preserveSessionKeys,

},

);

const modelRunPruned = shouldRunModelRunPrune({

maintenance: params.maintenance,

entryCount: params.beforeCount,

})

? pruneStaleModelRunEntries(params.operation.store, params.maintenance.modelRunPruneAfterMs, {

onPruned: ({ entry }) => {

rememberRemovedSessionFile(removedSessionFiles, entry);

},

preserveKeys: preserveSessionKeys,

})

: 0;

const pruned = pruneStaleEntries(params.operation.store, params.maintenance.pruneAfterMs, {

onPruned: ({ entry }) => {

rememberRemovedSessionFile(removedSessionFiles, entry);

pruneAfterMs: number;

maxEntries: number;

modelRunPruneAfterMs: number | null;

/** True when modelRunPruneAfter was explicitly set instead of using the pressure-gated default. */

modelRunPruneAfterConfigured: boolean;

resetArchiveRetentionMs: number | null;

maxDiskBytes: number | null;

highWaterBytes: number | null;

try {

return parseDurationMs(normalized, { defaultUnit: "d" });

} catch {

return DEFAULT_MODEL_RUN_PRUNE_AFTER_MS;

// The schema rejects invalid explicit values. Keep direct resolver callers fail-closed

// rather than silently enabling the default 24h model-run cleanup.

return null;

}

}

pruneAfterMs,

maxEntries: maintenance?.maxEntries ?? DEFAULT_SESSION_MAX_ENTRIES,

modelRunPruneAfterMs: resolveModelRunPruneAfterMs(maintenance),

modelRunPruneAfterConfigured: maintenance?.modelRunPruneAfter !== undefined,

resetArchiveRetentionMs: resolveResetArchiveRetentionMs(maintenance, pruneAfterMs),

maxDiskBytes,

highWaterBytes: resolveHighWaterBytes(maintenance, maxDiskBytes),

return params.entryCount >= resolveSessionEntryMaintenanceHighWater(params.maxEntries);

}

export function shouldRunModelRunPrune(params: {

maintenance: Pick<

ResolvedSessionMaintenanceConfig,

"maxEntries" | "modelRunPruneAfterConfigured" | "modelRunPruneAfterMs"

>;

entryCount: number;

}): boolean {

if (params.maintenance.modelRunPruneAfterMs == null) {

return false;

}

if (params.maintenance.modelRunPruneAfterConfigured) {

return true;

}

return shouldRunSessionEntryMaintenance({

entryCount: params.entryCount,

maxEntries: params.maintenance.maxEntries,

});

}

export function isGatewayModelRunSessionKey(sessionKey: string): boolean {

if (

!/^agent:[^:]+:explicit:model-run-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(

const match =

/^agent:([^:\s]+):explicit:model-run-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.exec(

sessionKey,

)

) {

);

if (!match) {

return false;

}

const agentId = match[1];

if (!agentId || /\s/.test(agentId)) {

return false;

}

const parsed = parseAgentSessionKey(sessionKey);

if (!parsed || !parsed.agentId.trim()) {

if (!parsed || parsed.agentId !== agentId.toLowerCase()) {

return false;

}

const rest = normalizeLowercaseStringOrEmpty(parsed.rest);

pruneAfterMs: 7 * DAY_MS,

maxEntries: 500,

modelRunPruneAfterMs: DAY_MS,

modelRunPruneAfterConfigured: true,

resetArchiveRetentionMs: 7 * DAY_MS,

maxDiskBytes: null,

highWaterBytes: null,

await fs.writeFile(storePath, JSON.stringify(store), "utf-8");

const cfg = { session: { store: storePath } };

mockLoadConfig.mockReturnValue({

session: {

maintenance: {

mode: "enforce",

pruneAfter: "30d",

maxEntries: 500,

},

},

});

const defaultDryRun = await runSessionsCleanup({

cfg,

opts: { dryRun: true, enforce: true },

targets: [{ agentId: "main", storePath }],

});

expect(defaultDryRun.previewResults[0]?.summary.modelRunPruned).toBe(0);

expect(loadSessionStore(storePath, { skipCache: true })).toHaveProperty(staleModelRun);

mockLoadConfig.mockReturnValue({

session: {

maintenance: {

mode: "enforce",

pruneAfter: "30d",

maxEntries: 500,

modelRunPruneAfter: "24h",

},

},

});

const dryRun = await runSessionsCleanup({

cfg,

opts: { dryRun: true, enforce: true },

expect(loaded).toHaveProperty(recentModelRun);

});

it("saveSessionStore pressure-gates unset default model-run pruning", async () => {

const now = Date.now();

const staleModelRun = "agent:main:explicit:model-run-123e4567-e89b-12d3-a456-426614174020";

const recentModelRun = "agent:main:explicit:model-run-123e4567-e89b-12d3-a456-426614174021";

mockLoadConfig.mockReturnValue({

session: {

maintenance: {

mode: "enforce",

pruneAfter: "30d",

maxEntries: 500,

},

},

});

await saveSessionStore(storePath, {

[staleModelRun]: makeEntry(now - 2 * DAY_MS),

[recentModelRun]: makeEntry(now),

});

expect(loadSessionStore(storePath, { skipCache: true })).toHaveProperty(staleModelRun);

mockLoadConfig.mockReturnValue({

session: {

maintenance: {

mode: "enforce",

pruneAfter: "30d",

maxEntries: 1,

},

},

});

await saveSessionStore(storePath, loadSessionStore(storePath, { skipCache: true }));

const loaded = loadSessionStore(storePath, { skipCache: true });

expect(loaded[staleModelRun]).toBeUndefined();

expect(loaded).toHaveProperty(recentModelRun);

});

it("saveSessionStore prunes stale entries on write", async () => {

applyEnforcedMaintenanceConfig(mockLoadConfig);

pruneAfterMs: 7 * DAY_MS,

maxEntries: 500,

modelRunPruneAfterMs: null,

modelRunPruneAfterConfigured: true,

resetArchiveRetentionMs: null,

maxDiskBytes: null,

highWaterBytes: null,

maxEntries?: number;

/**

* Retention for gateway model-run probe sessions (`agent:*:explicit:model-run-<uuid>`).

* Set `false` to disable model-run-specific cleanup. Default: "24h".

* Unset defaults to "24h" but only runs under session-entry cap pressure;

* setting a duration opts into unconditional age cleanup, and `false` disables.

*/

modelRunPruneAfter?: string | number | false;

/** @deprecated Ignored. Run `openclaw doctor --fix` to remove. */