@martian-engineering/lossless-claw 0.13.1 → 0.13.2

package/README.md

@@ -8,8 +8,10 @@ Lossless Context Management plugin for [OpenClaw](https://github.com/openclaw/op
 - [Quick start](#quick-start)
 - [Configuration](#configuration)
 - [Commands And Skill](#commands-and-skill)
+- [Session Migration CLI](#session-migration-cli)
 - [Documentation](#documentation)
 - [Development](#development)
+  - [Line endings](#line-endings)
 - [Security](#security)
 - [License](#license)
 
@@ -33,31 +35,50 @@ Nothing is lost. Raw messages stay in the database. Summaries link back to their
 
 The plugin now ships a bundled `lossless-claw` skill plus a small plugin command surface for supported OpenClaw chat/native command providers:
 
-- `/lcm` shows version, enablement/selection state, DB path and size, summary counts, and summary-health status
-- `/lcm backup` creates a timestamped backup of the current LCM SQLite database
-- `/lcm rotate` rewrites the active session transcript into a compact tail-preserving form without changing the live OpenClaw session identity or current LCM conversation
-- `/lcm doctor` scans for broken or truncated summaries
-- `/lcm doctor clean` shows read-only high-confidence junk diagnostics for archived subagents, cron sessions, and NULL-key orphaned subagent runs
-- `/lcm status` shows plugin, conversation, and maintenance state including deferred compaction debt
-- `/lossless` is an alias for `/lcm` on supported native command surfaces
+- `/lossless` shows version, enablement/selection state, DB path and size, summary counts, and summary-health status
+- `/lossless backup` creates a timestamped backup of the current LCM SQLite database
+- `/lossless rotate` rewrites the active session transcript into a compact tail-preserving form without changing the live OpenClaw session identity or current LCM conversation
+- `/lossless doctor` scans for broken or truncated summaries
+- `/lossless doctor clean` shows read-only high-confidence junk diagnostics for archived subagents, cron sessions, and NULL-key orphaned subagent runs
+- `/lossless status` shows plugin, conversation, and maintenance state including deferred compaction debt
+- `/lcm` is the shorter alias for `/lossless`
 
 These are plugin slash/native commands, not root shell CLI subcommands. Supported examples:
 
-- `/lcm`
-- `/lcm backup`
-- `/lcm rotate`
-- `/lcm doctor`
-- `/lcm doctor clean`
 - `/lossless`
+- `/lossless backup`
+- `/lossless rotate`
+- `/lossless doctor`
+- `/lossless doctor clean`
+- `/lcm`
 
 Not currently supported as root CLI commands:
 
-- `openclaw lcm`
 - `openclaw lossless`
+- `openclaw lcm`
+- `openclaw /lossless`
 - `openclaw /lcm`
 
 The bundled skill focuses on configuration, diagnostics, architecture, and recall-tool usage. Its reference set lives under `skills/lossless-claw/references/`.
 
+## Session Migration CLI
+
+`lossless-claw-migrate-sessions` is a one-time shell CLI for backfilling OpenClaw JSONL session files into `lcm.db` after lossless-claw was disabled, missing, or installed after sessions already existed. It is not a background replay loop and it does not run summarization.
+
+Run it in dry-run mode first:
+
+```bash
+npx --package @martian-engineering/lossless-claw@latest lossless-claw-migrate-sessions --state-dir ~/.openclaw
+```
+
+Apply the import only after reviewing the dry-run output:
+
+```bash
+npx --package @martian-engineering/lossless-claw@latest lossless-claw-migrate-sessions --state-dir ~/.openclaw --apply
+```
+
+The command defaults to `${OPENCLAW_STATE_DIR:-~/.openclaw}` and `${OPENCLAW_STATE_DIR:-~/.openclaw}/lcm.db`. `--apply` creates a timestamped SQLite backup before writing when the database already exists. Use `--file <path>` or repeatable `--sessions-dir <path>` for targeted imports, `--since <iso-date>` or `--limit <n>` to narrow a batch, and `--json` for machine-readable output.
+
 ## Quick start
 
 ### Prerequisites
@@ -73,13 +94,19 @@ The bundled skill focuses on configuration, diagnostics, architecture, and recal
 Use OpenClaw's plugin installer (recommended):
 
 ```bash
-openclaw plugins install @martian-engineering/lossless-claw
+openclaw plugins install @martian-engineering/lossless-claw@latest
 ```
 
 If you're running from a local OpenClaw checkout, use:
 
 ```bash
-pnpm openclaw plugins install @martian-engineering/lossless-claw
+pnpm openclaw plugins install @martian-engineering/lossless-claw@latest
+```
+
+Use exact versions only for rollback or reproducible canary testing. OpenClaw records an exact install spec such as `@martian-engineering/lossless-claw@0.12.0` as a pinned update track, so OpenClaw plugin update sync will keep that version until you move back to the stable track:
+
+```bash
+openclaw plugins update @martian-engineering/lossless-claw@latest
 ```
 
 For local plugin development, build your working copy first, then link it instead of copying files:
@@ -313,7 +340,7 @@ For large sessions, neither command is a perfect “keep my live agent context,
 - `/new` keeps writing into the same active LCM conversation row.
 - `/reset` changes OpenClaw session flow, which is heavier than users often want when their real problem is just LCM row size.
 
-`/lcm rotate` fills that gap. Before trimming the transcript, it forces leaf-only compaction for raw context outside the preserved live tail so older transcript messages are represented by LCM summaries. It then replaces one rolling `rotate-latest` SQLite backup, rewrites the current session transcript down to the preserved live tail plus current session settings, and refreshes the bootstrap frontier on the same active LCM conversation so dropped transcript history is not replayed. Existing durable messages, summaries, context items, and conversation identity stay in place; only the transcript backing is compacted. If you want additional timestamped snapshots instead, run `/lcm backup`.
+`/lossless rotate` fills that gap. Before trimming the transcript, it forces leaf-only compaction for raw context outside the preserved live tail so older transcript messages are represented by LCM summaries. It then replaces one rolling `rotate-latest` SQLite backup, rewrites the current session transcript down to the preserved live tail plus current session settings, and refreshes the bootstrap frontier on the same active LCM conversation so dropped transcript history is not replayed. Existing durable messages, summaries, context items, and conversation identity stay in place; only the transcript backing is compacted. If you want additional timestamped snapshots instead, run `/lossless backup`.
 
 `newSessionRetainDepth` (or `LCM_NEW_SESSION_RETAIN_DEPTH`) controls how much summary structure survives `/new`:
 
@@ -519,6 +546,22 @@ tui/                        # Interactive terminal UI (Go)
 .goreleaser.yml             # GoReleaser config for TUI binary releases
 ```
 
+### Line endings
+
+This repository codifies LF line endings through `.gitattributes` so diffs stay
+stable across macOS, Linux, and Windows development environments.
+
+- Git should store text files with LF endings in the repository.
+- The root `* text=auto eol=lf` rule normalizes newly added text files.
+- Common source, documentation, lockfile, template, and config extensions are
+  listed explicitly so contributors and tooling see the expected policy.
+- Binary assets and SQLite/database files are marked `binary` to avoid unsafe
+  newline conversion.
+- If your editor or operating system prefers CRLF locally, keep the repository
+  rules authoritative and avoid committing CRLF-only rewrites.
+- After changing line-ending rules, prefer a focused normalization commit so
+  future functional changes remain easy to review.
+
 ## Security
 
 Please report suspected vulnerabilities privately. See [SECURITY.md](SECURITY.md)