Find OpenClaw sessions in configured state directories

[uttamdeb]

Summary

• Discover sessions under OPENCLAW_STATE_DIR/agents and resolve OPENCLAW_HOME using OpenClaw's home precedence and fallbacks. Preserve explicit constructor paths and the four historical roots.
• Share resolved roots between discovery, probes, and the session-cache fingerprint. Relative overrides remain correct when the working directory changes.
• Backfill finalized history at daily cache v76, then refresh it when OpenClaw roots change. Preserve archived provider slices and retry incomplete backfills.

Rebased on upstream 9a40cc60. Upstream's Copilot v75 migration and guarded rederive threshold are preserved. The original eleven commits are retained; one additional commit covers migration from v75 and updates the documentation. Final head: e4126922.

Data provenance and validation scope

The JSONL and SQLite regression tests use controlled fixtures. There is no live OpenClaw installation on this test machine, so I am not claiming validation against one.

For additional evidence, I replayed the timestamped assistant-event excerpt that an OpenClaw user published in openclaw/openclaw#26645. The report identifies OpenClaw 2026.2.23 and a Kimi K2.5 session. JSON comments/whitespace were normalized; the published event fields, including timestamp, model, usage, and logged cost, were retained. The excerpt was placed under an isolated relocated agents directory; it contains no prompt or response text.

That source reports a vendor-side input-underreporting problem. This replay validates discovery and preservation of the recorded fields, not API billing accuracy or a full live installation. The maintainer's real-world validation request remains for review; this is supplemental evidence with explicit provenance.

CLI before and after

Command on each checkout, with isolated HOME/config/cache paths and OPENCLAW_STATE_DIR selecting the copied excerpt:

node --import tsx src/cli.ts status --provider openclaw --period lifetime --format menubar-json --no-optimize --no-timeline

Checkout	Calls	Input	Output	Cache read	Cache write	Logged cost
Upstream 9a40cc60	0	0	0	0	0	$0.00
This branch e4126922	1	21,516	5	21,248	0	$0.02

The branch's CLI also reports the model as Kimi K2.5. Its session-count basis is marked partial, consistent with replaying one excerpt rather than a complete session. Direct provider checks confirm that the explicit constructor reads the same event on both checkouts, while default discovery finds it only on this branch. Assertions compare the parsed fields against the source event.

The separate controlled JSONL reproduction also retains its original result: main discovers 0 default sessions / 1 explicit session; the branch discovers 1 / 1, preserving the fixture's 12,345 input and 678 output tokens.

The resolver follows OpenClaw's state resolver, home normalization, and required-home fallback.

Cache and regression coverage

• Absolute, relative, tilde, blank, and unset overrides; home precedence, unset placeholders, Termux, and unavailable OS-home resolution.
• JSONL and SQLite discovery, explicit constructors, probes, mirrored sessions, and Windows case aliases.
• Warm session-cache changes and settled history adopted from literal v51, v73, v74, and v75 caches, including archived Claude usage.
• Same-version finalized history after changing OPENCLAW_STATE_DIR, OPENCLAW_HOME, or cwd under a relative override. Partial parses retain the prior fingerprint and retry; unchanged roots reuse history.
• The literal v75 migration test fails if v75 is reused: only the archived 50 input tokens remain instead of 150 including relocated usage. Restoring v76 passes all 14 discovery/cache tests.
• Independent read-only review of the final rebased diff found no confirmed code issues. Normal older-cache adoption forces a full backfill by marking it incomplete; upstream's partial-survival guards are retained.

Testing / Verification

Node 24.9.0, unchanged upstream 9a40cc60, exact final branch head e4126922:

• Initial full branch suite: 5,230 passed, 2 failed, 30 skipped (386 passed files, 2 failed, 2 skipped).
• Initial full main suite: 5,185 passed, 4 failed, 30 skipped (383 passed files, 4 failed, 2 skipped).
• Both branch failures also occur on main: the CLI budget overview case and proxy-path add/list/dedupe/remove case exceeded their original 30-second limits. Their serial branch reruns passed in 19.8s and 18.9s, without changing timeouts.
• Main's additional failures were the rooted-project-filter case's 30-second limit and the cold-dashboard exit case's 1-second process-exit deadline. All four main failures passed serial reruns with the original limits (13.2s project-filter case, 7.1s whole dashboard-exit case, 22.1s budget case, 18.8s proxy-path case).
• The branch adds 43 test cases and introduces zero new failing cases. Initial full-run failures are retained and disclosed; these are not reported as all-green full runs.
• npm run build, npx tsc --noEmit, and git diff --check passed.
• Both controlled-fixture and public-excerpt before/after checks passed, including the CLI assertions above.

Full suites on main and branch used the normal npm test scope:

npm test -- --configLoader runner --maxWorkers 2 --reporter=default --reporter=json --outputFile.json=<external-report-path>

The two full runs ran concurrently. Selected failures were then rerun serially with --maxWorkers 1 after both full runs finished, using -t to select the failed cases. The four serial refresh-lock suites remain excluded by the repository's normal npm test script. No Electron or native-app code is changed.

• Full main and branch suites run and compared; original failures and successful reruns disclosed.
• Build and TypeScript checks succeed.
• Actual CLI output supplied for a reporter-posted transcript excerpt, with provenance and scope disclosed.
• Live local relocated OpenClaw installation proof: unavailable on this machine.
• Not a UI change.

This is an existing-provider discovery fix. No original user logs are modified or deleted.