@martian-engineering/lossless-claw 0.9.3 → 0.9.4

package/docs/configuration.md

@@ -53,6 +53,12 @@ Most installations only need to override a handful of keys. If you want a comple
   "circuitBreakerCooldownMs": 1800000,
   "fallbackProviders": [],
   "proactiveThresholdCompactionMode": "deferred",
+  "autoRotateSessionFiles": {
+    "enabled": true,
+    "sizeBytes": 2097152,
+    "startup": "rotate",
+    "runtime": "rotate"
+  },
   "cacheAwareCompaction": {
     "enabled": true,
     "cacheTTLSeconds": 300,
@@ -117,9 +123,17 @@ openclaw plugins install --link /path/to/lossless-claw
 | `pruneHeartbeatOk` | `boolean` | `false` | `LCM_PRUNE_HEARTBEAT_OK` | Retroactively removes `HEARTBEAT_OK` turn cycles from persisted storage. |
 | `transcriptGcEnabled` | `boolean` | `false` | `LCM_TRANSCRIPT_GC_ENABLED` | Enables transcript rewrite GC during `maintain()`; disabled by default so transcript rewrites stay opt-in. |
 | `proactiveThresholdCompactionMode` | `"deferred" \| "inline"` | `"deferred"` | `LCM_PROACTIVE_THRESHOLD_COMPACTION_MODE` | Controls whether proactive threshold compaction is deferred into maintenance debt by default or run inline for legacy behavior. |
+| `autoRotateSessionFiles.enabled` | `boolean` | `true` | `LCM_AUTO_ROTATE_SESSION_FILES_ENABLED` | Enables automatic rotation for oversized LCM-managed session JSONL files. |
+| `autoRotateSessionFiles.sizeBytes` | `integer` | `2097152` | `LCM_AUTO_ROTATE_SESSION_FILES_SIZE_BYTES` | Byte threshold that triggers automatic session-file rotation. |
+| `autoRotateSessionFiles.startup` | `"rotate" \| "warn" \| "off"` | `"rotate"` | `LCM_AUTO_ROTATE_SESSION_FILES_STARTUP` | Startup behavior for oversized indexed OpenClaw session transcripts that also have active LCM bootstrap state. |
+| `autoRotateSessionFiles.runtime` | `"rotate" \| "warn" \| "off"` | `"rotate"` | `LCM_AUTO_ROTATE_SESSION_FILES_RUNTIME` | Runtime behavior after `afterTurn()` and `maintain()` check the current transcript size. |
 
 > **Multi-profile note:** `OPENCLAW_STATE_DIR` (set by the host OpenClaw gateway) controls where state is stored. When two gateways run on the same host (e.g. separate bot personas), each gateway sets its own `OPENCLAW_STATE_DIR` and lossless-claw automatically uses that directory for the database, large-file payloads, auth-profile lookups, and legacy secrets — no per-profile plugin config is needed.
 
+Automatic session-file rotation uses the same safe path as `/lcm rotate`: runtime rotation replaces the rolling `rotate-latest` SQLite backup, rewrites only the live session transcript, keeps the active LCM conversation and durable history intact, and refreshes the bootstrap checkpoint. Startup rotation first scans OpenClaw's current indexed session stores for configured agents, then intersects those candidates with active LCM conversations and matching bootstrap file mappings. If multiple startup candidates need rotation, one pre-rotation LCM database backup is created for the batch before any transcript is rewritten. Rotation never runs for ignored sessions, stateless sessions, or sessions without active LCM state. The preserved JSONL tail follows the existing rotate behavior, which is controlled by `freshTailCount`.
+
+Every automatic decision emits grep-able log lines prefixed with `[lcm] auto-rotate:`. Startup emits one compact summary line with `phase=startup`, `action=summary`, `scanned`, `eligible`, `rotated`, `warned`, `skipped`, `durationMs`, `bytesRemoved`, and backup fields when a batch backup was created; quiet skips such as missing files, missing bootstrap mappings, and below-threshold files are counted there instead of producing one line per candidate. Rotation detail lines include `phase`, `action`, `sessionId`, `sessionKey`, `sessionFile`, `sizeBytes`, `thresholdBytes`, `durationMs`, `backupPath`, `bytesRemoved`, `preservedTailMessageCount`, and `checkpointSize`; real warning lines include the same available context plus `reason` or `error`.
+
 ### Compaction thresholds and summary sizing
 
 | Key | Type | Default | Env override | Purpose |

package/openclaw.plugin.json

@@ -1,6 +1,9 @@
 {
   "id": "lossless-claw",
   "kind": "context-engine",
+  "activation": {
+    "onStartup": true
+  },
   "skills": [
     "skills/lossless-claw"
   ],
@@ -213,6 +216,22 @@
       "label": "Proactive Threshold Compaction Mode",
       "help": "Choose deferred compaction debt by default or keep legacy inline proactive compaction"
     },
+    "autoRotateSessionFiles.enabled": {
+      "label": "Auto-Rotate Session Files",
+      "help": "Automatically rotate oversized LCM-managed session JSONL files after startup and runtime checks"
+    },
+    "autoRotateSessionFiles.sizeBytes": {
+      "label": "Auto-Rotate Size Bytes",
+      "help": "Session JSONL byte threshold for automatic rotation (default: 2097152)"
+    },
+    "autoRotateSessionFiles.startup": {
+      "label": "Startup Auto-Rotate",
+      "help": "Startup behavior for oversized indexed OpenClaw session files with active LCM state: rotate, warn, or off"
+    },
+    "autoRotateSessionFiles.runtime": {
+      "label": "Runtime Auto-Rotate",
+      "help": "Runtime behavior for oversized current LCM session files: rotate, warn, or off"
+    },
     "fallbackProviders": {
       "label": "Fallback Providers",
       "help": "Explicit fallback provider/model pairs for compaction summarization (e.g., [{\"provider\": \"anthropic\", \"model\": \"claude-haiku-4-5\"}])"
@@ -419,6 +438,35 @@
           "inline"
         ]
       },
+      "autoRotateSessionFiles": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "enabled": {
+            "type": "boolean"
+          },
+          "sizeBytes": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "startup": {
+            "type": "string",
+            "enum": [
+              "rotate",
+              "warn",
+              "off"
+            ]
+          },
+          "runtime": {
+            "type": "string",
+            "enum": [
+              "rotate",
+              "warn",
+              "off"
+            ]
+          }
+        }
+      },
       "databasePath": {
         "description": "Path to LCM SQLite database (preferred key; alias of dbPath, default: <OPENCLAW_STATE_DIR>/lcm.db)",
         "type": "string"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@martian-engineering/lossless-claw",
-  "version": "0.9.3",
+  "version": "0.9.4",
   "description": "Lossless Context Management plugin for OpenClaw — DAG-based conversation summarization with incremental compaction",
   "type": "module",
   "main": "dist/index.js",
@@ -44,10 +44,10 @@
     "vitest": "^3.0.0"
   },
   "peerDependencies": {
-    "@mariozechner/pi-agent-core": "*",
-    "@mariozechner/pi-ai": "*",
-    "@mariozechner/pi-coding-agent": "*",
-    "openclaw": "*"
+    "@mariozechner/pi-agent-core": ">=0.66 <1",
+    "@mariozechner/pi-ai": ">=0.66 <1",
+    "@mariozechner/pi-coding-agent": ">=0.66 <1",
+    "openclaw": ">=2026.2.17 <2026.6.0"
   },
   "peerDependenciesMeta": {
     "@mariozechner/pi-agent-core": {
@@ -68,8 +68,11 @@
       "./dist/index.js"
     ],
     "compat": {
-      "pluginApi": ">=2026.2.17",
-      "minGatewayVersion": "2026.2.17"
+      "pluginApi": ">=2026.2.17 <2026.6.0",
+      "minGatewayVersion": "2026.2.17",
+      "tested": [
+        "2026.5.2"
+      ]
     },
     "build": {
       "openclawVersion": "2026.2.17"

package/skills/lossless-claw/references/config.md

@@ -235,6 +235,32 @@ Why it matters:
 - `/lossless status` and `/lcm status` surface pending/running/last-failure maintenance state so operators can see when compaction is queued
 - background `maintain()` can still do non-prompt-mutating work, but prompt-mutating debt is consumed pre-assembly once cache is cold or the next turn is already approaching overflow
 
+### `autoRotateSessionFiles`
+
+Automatically rotates oversized LCM-managed session JSONL files.
+
+Defaults:
+
+- `enabled: true`
+- `sizeBytes: 2097152`
+- `startup: "rotate"`
+- `runtime: "rotate"`
+
+Why it matters:
+
+- prevents very large OpenClaw session JSONL files from choking fallback/gateway startup while LCM owns the durable context
+- runtime rotation uses the same backup-backed safe path as `/lossless rotate` / `/lcm rotate`
+- startup scans OpenClaw's current indexed session stores for configured agents, intersects those candidates with active LCM bootstrap state, and creates one pre-rotation DB backup for the startup batch
+- only runs for active, writable LCM conversations; ignored sessions, stateless sessions, sessions outside the indexed startup candidate set, and sessions without active LCM state are skipped
+- the preserved transcript tail follows the normal rotate behavior controlled by `freshTailCount`
+
+Operational logging:
+
+- every decision is logged with the prefix `[lcm] auto-rotate:`
+- startup emits one compact `action=summary` line with `scanned`, `eligible`, `rotated`, `warned`, `skipped`, `durationMs`, and `bytesRemoved`
+- rotate logs include `phase`, `action`, `sessionId`, `sessionKey`, `sessionFile`, `sizeBytes`, `thresholdBytes`, `durationMs`, `backupPath`, `bytesRemoved`, `preservedTailMessageCount`, and `checkpointSize`
+- real warning logs include the same available context plus `reason` or `error`; quiet startup skips such as missing files, missing bootstrap mappings, and below-threshold files are counted in the summary instead of logged per candidate
+
 ## Compaction timing and shape
 
 ### `contextThreshold`