OpenClaw Runtime Stabilizer

Public engineering artifact, reliability case study, and read-only verification toolkit for OpenClaw runtime/session-store incidents.

Current public release: v1.1.0.

This repository documents a real stabilization workflow for a local AI agent runtime after session-store inconsistency, dashboard session collisions, orphaned session entries, and runtime/config drift. The public edition focuses on safe diagnosis, reproducible documentation, evidence redaction, rollback discipline, operational verification, mock-based read-only tooling, fixture-driven tests, structured logging, advisory version checks, and Markdown reporting.

Target runtime

The work documented in this repository was performed against:

OpenClaw 2026.6.8

All concrete runtime assumptions should be treated as version-scoped to OpenClaw 2026.6.8 unless revalidated on another release.

See docs/TARGET_RUNTIME.md.

Why this matters

Local AI agent runtimes are stateful systems. When sessions, registries, dashboards, compaction artifacts, and runtime bundles drift out of sync, the result can look like data loss even when transcripts still exist on disk. A safe repair workflow must preserve data first, verify state before modifying it, and avoid destructive resets.

Scope

This public edition includes:

• incident analysis and executive summary
• target runtime/version note
• troubleshooting matrix for similar symptoms
• read-only session-store analyzer
• mock session-store environments for safe testing
• fixture-driven Node.js test suite
• structured JSONL logging for operator runs
• advisory upstream version check
• optional GUI wrapper plan
• Markdown report generation
• architecture notes for the stabilization approach
• rollback and verification policy
• redaction policy for public release
• sanitized evidence summary
• examples for safe environment documentation

This repository intentionally does not publish private transcripts, raw local logs, machine-specific paths, hostnames, tokens, or one-click destructive repair operations.

Install

Requirements:

• Node.js 20 or newer
• npm

Clone and install:

git clone https://github.com/melkhamesey2/openclaw-runtime-stabilizer.git
cd openclaw-runtime-stabilizer
npm install

There are currently no external runtime dependencies. npm install is still useful as a standard project setup step and for future compatibility.

Run the read-only verifier

Run against the bundled mock dataset:

npm run verify:mock

Equivalent direct command:

node tools/verify-readonly.mjs examples/mock-session-store

The verifier prints a JSON report. It does not write, delete, rename, repair, or mutate source session data.

Structured logging

Run the verifier with a persistent JSONL log file:

npm run verify -- examples/mock-session-store --log-file logs/stabilizer.log
npm run verify:mock:logged

Each log line includes timestamp, level, message, and structured metadata. This is intended for operator review after a terminal closes or a run fails.

Advisory version check

Check an upstream OpenClaw repository release without installing or changing anything:

npm run version:check -- --repo owner/OpenClaw --current 2026.6.8

The version checker is advisory only. It compares the supplied local version with the latest GitHub release for the supplied repository and never updates OpenClaw.

Run tests and full checks

Run the Node.js test suite:

npm test

Run the full project check:

npm run check

The check workflow uses npm lifecycle hooks:

• precheck runs a local self-check.
• check runs tests, mock verification, and Markdown report generation.
• postcheck repeats the self-check so the automation boundary is explicit.

Current npm scripts:

Script	Purpose
npm run verify -- <dir>	Run the verifier on a supplied session-store directory.
npm run verify:mock	Run the verifier on the bundled mock fixture.
npm run verify:mock:logged	Run mock verification and write logs/stabilizer.log.
npm run version:check -- --repo <owner/name> --current <version>	Run advisory upstream version drift check.
npm test	Run the analyzer test suite.
npm run report -- <dir> <output.md>	Generate a Markdown report from a session-store directory.
npm run report:mock	Generate reports/mock-session-store-report.md from the mock fixture.
npm run check	Run self-checks, tests, mock verification, and report generation.

Large-file handling

The analyzer is designed for large JSONL transcript files. It uses streaming file reads for transcript hashing and line-by-line JSONL validation instead of loading entire transcript files into memory.

Useful large-file options:

node tools/verify-readonly.mjs examples/mock-session-store --large-file-bytes 1048576
node tools/verify-readonly.mjs examples/mock-session-store --max-jsonl-line-bytes 1048576

• --large-file-bytes controls when the report labels a transcript as large-file mode.
• --max-jsonl-line-bytes bounds deep JSON validation for unusually large single JSONL lines.

Example verifier output

A shortened mock finding looks like this:

{
  "ok": true,
  "summary": {
    "registryEntries": 6,
    "warnings": 2,
    "findings": 6
  },
  "findings": [
    {
      "severity": "warning",
      "code": "MISSING_TRANSCRIPT_FILE",
      "message": "Registry points to a transcript file that does not exist."
    }
  ]
}

For a human-readable version, run:

npm run report:mock

Fixtures

The repository includes several safe fixtures:

Fixture	Purpose
examples/mock-session-store/	Mixed incident-like registry for golden expectations.
examples/clean-session-store/	Clean registry used to verify zero findings.
examples/malformed-session-store/	JSONL parse-error fixture.
examples/mock-large-session-store/	Bounded large-line fixture for streaming/line-limit behavior.

Optional GUI wrapper

The core project remains CLI-first. A future optional GUI can wrap the existing CLI commands with CustomTkinter without duplicating verifier logic. See docs/GUI_WRAPPER_PLAN.md.

Quick reading path

1. docs/TARGET_RUNTIME.md
2. docs/EXECUTIVE_SUMMARY.md
3. docs/TROUBLESHOOTING_MATRIX.md
4. examples/mock-session-store/README.md
5. src/session-store-analyzer.mjs
6. src/logger.mjs
7. tools/verify-readonly.mjs
8. tools/check-openclaw-version.mjs
9. tools/generate-markdown-report.mjs
10. test/session-store-analyzer.test.mjs
11. docs/INCIDENT_TIMELINE.md
12. docs/ARCHITECTURE.md
13. docs/OPERATIONAL_VERIFICATION.md
14. docs/ROLLBACK_POLICY.md
15. docs/REDACTION_POLICY.md
16. evidence/SANITIZED_EVIDENCE_SUMMARY.md

Repository map

.
├── README.md
├── LICENSE
├── NOTICE
├── SECURITY.md
├── CONTRIBUTING.md
├── package.json
├── docs/
│   ├── ARCHITECTURE.md
│   ├── EXECUTIVE_SUMMARY.md
│   ├── FINAL_REPORT_AR.md
│   ├── GUI_WRAPPER_PLAN.md
│   ├── INCIDENT_TIMELINE.md
│   ├── OPERATIONAL_VERIFICATION.md
│   ├── PROJECT_STATUS.md
│   ├── REDACTION_POLICY.md
│   ├── RELEASE_NOTES.md
│   ├── REPOSITORY_MAP.md
│   ├── ROADMAP.md
│   ├── ROLLBACK_POLICY.md
│   ├── TARGET_RUNTIME.md
│   └── TROUBLESHOOTING_MATRIX.md
├── evidence/
│   └── SANITIZED_EVIDENCE_SUMMARY.md
├── examples/
│   ├── redacted-environment.example
│   ├── mock-session-store/
│   ├── clean-session-store/
│   ├── malformed-session-store/
│   └── mock-large-session-store/
├── src/
│   ├── README.md
│   ├── logger.mjs
│   └── session-store-analyzer.mjs
├── tools/
│   ├── README.md
│   ├── verify-readonly.mjs
│   ├── check-openclaw-version.mjs
│   └── generate-markdown-report.mjs
├── test/
│   └── session-store-analyzer.test.mjs
├── reports/
│   └── generated locally by npm run report:mock