@martian-engineering/lossless-claw 0.9.2 → 0.9.4

package/docs/configuration.md

@@ -53,11 +53,20 @@ 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,
     "maxColdCacheCatchupPasses": 2,
     "hotCachePressureFactor": 4,
-    "hotCacheBudgetHeadroomRatio": 0.2
+    "hotCacheBudgetHeadroomRatio": 0.2,
+    "coldCacheObservationThreshold": 3,
+    "criticalBudgetPressureRatio": 0.70
   },
   "dynamicLeafChunkTokens": {
     "enabled": true,
@@ -114,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 |
@@ -173,6 +190,7 @@ openclaw plugins install --link /path/to/lossless-claw
 | `cacheAwareCompaction.hotCachePressureFactor` | `number` | `4` | `LCM_HOT_CACHE_PRESSURE_FACTOR` | Multiplier applied to the hot-cache leaf trigger before raw-history pressure overrides cache preservation. |
 | `cacheAwareCompaction.hotCacheBudgetHeadroomRatio` | `number` | `0.2` | `LCM_HOT_CACHE_BUDGET_HEADROOM_RATIO` | Minimum fraction of the real token budget that must remain free before hot-cache incremental compaction is skipped entirely. |
 | `cacheAwareCompaction.coldCacheObservationThreshold` | `integer` | `3` | `LCM_COLD_CACHE_OBSERVATION_THRESHOLD` | Consecutive cold observations required before non-explicit cache misses are treated as truly cold. This dampens one-off routing noise and provider failover blips. |
+| `cacheAwareCompaction.criticalBudgetPressureRatio` | `number` | `0.70` | `LCM_CRITICAL_BUDGET_PRESSURE_RATIO` | Fraction of the token budget at which deferred compaction bypasses hot-cache delay so prompt-mutating debt can run before overflow. Set to `1` to disable this bypass. |
 
 #### `dynamicLeafChunkTokens`
 
@@ -189,6 +207,7 @@ When cache-aware compaction is enabled:
 - hot cache skips incremental maintenance entirely when the assembled context is still comfortably below the real token budget
 - hot cache also gets a short hysteresis window so one ambiguous turn does not immediately discard a recently healthy cache signal
 - cold cache still allows bounded catch-up passes via `cacheAwareCompaction.maxColdCacheCatchupPasses`
+- once `currentTokenCount >= criticalBudgetPressureRatio * tokenBudget`, deferred compaction bypasses hot-cache delay so prompt-mutating debt can run before emergency overflow handling
 
 When incremental leaf compaction still runs on a hot cache, follow-on condensed passes are suppressed so the maintenance cycle only pays for the leaf pass that was explicitly justified.
 

package/docs/tui.md

@@ -245,8 +245,8 @@ Scans for genuinely truncated summaries and can rewrite them in place. This is n
 # Preview repairs for one conversation
 lcm-tui doctor 44 --show-diff
 
-# Apply repairs with an OpenAI-compatible backend
-lcm-tui doctor 44 --apply --provider openai --model gpt-5.3-codex --base-url https://proxy.example.com/openai
+# Apply repairs through Codex CLI OAuth after `codex login`
+lcm-tui doctor 44 --apply --provider openai-codex --model gpt-5.3-codex
 
 # Scan only across every conversation
 lcm-tui doctor --all
@@ -263,6 +263,8 @@ lcm-tui doctor --all
 | `--show-diff` | Show unified diff for each fix |
 | `--timestamps` | Inject timestamps into rewrite source text |
 
+Use `--provider openai-codex` when you want ChatGPT Plus/Pro OAuth from the Codex CLI. Keep `--provider openai` for direct OpenAI-compatible HTTP calls with a raw `OPENAI_API_KEY`, including custom `--base-url` proxies.
+
 ### `lcm-tui repair`
 
 Finds and fixes corrupted summaries (those containing the `[LCM fallback summary]` marker from failed summarization attempts).
@@ -280,7 +282,10 @@ lcm-tui repair 44 --apply
 # Repair a specific summary
 lcm-tui repair 44 --summary-id sum_abc123 --apply
 
-# Repair through an OpenAI-compatible backend
+# Repair through Codex CLI OAuth after `codex login`
+lcm-tui repair 44 --apply --provider openai-codex --model gpt-5.3-codex
+
+# Repair through a custom OpenAI-compatible proxy with a raw API key
 lcm-tui repair 44 --apply --provider openai --model gpt-5.3-codex --base-url https://proxy.example.com/openai
 ```
 
@@ -316,10 +321,10 @@ lcm-tui rewrite 44 --depth 0 --apply
 # Rewrite everything bottom-up
 lcm-tui rewrite 44 --all --apply --diff
 
-# Rewrite with OpenAI Responses API
-lcm-tui rewrite 44 --summary sum_abc123 --provider openai --model gpt-5.3-codex --apply
+# Rewrite with Codex CLI OAuth after `codex login`
+lcm-tui rewrite 44 --summary sum_abc123 --provider openai-codex --model gpt-5.3-codex --apply
 
-# Rewrite through a custom OpenAI-compatible proxy
+# Rewrite through a custom OpenAI-compatible proxy with a raw API key
 lcm-tui rewrite 44 --summary sum_abc123 --provider openai --model gpt-5.3-codex --base-url https://proxy.example.com/openai --apply
 
 # Use custom prompt templates
@@ -412,10 +417,10 @@ lcm-tui backfill my-agent session_abc123 --apply --recompact --single-root
 # Import + compact + transplant into an active conversation
 lcm-tui backfill my-agent session_abc123 --apply --transplant-to 653
 
-# Backfill using OpenAI
-lcm-tui backfill my-agent session_abc123 --apply --provider openai --model gpt-5.3-codex
+# Backfill using Codex CLI OAuth after `codex login`
+lcm-tui backfill my-agent session_abc123 --apply --provider openai-codex --model gpt-5.3-codex
 
-# Backfill through a custom OpenAI-compatible proxy
+# Backfill through a custom OpenAI-compatible proxy with a raw API key
 lcm-tui backfill my-agent session_abc123 --apply --provider openai --model gpt-5.3-codex --base-url https://proxy.example.com/openai
 ```
 

package/openclaw.plugin.json

@@ -1,9 +1,20 @@
 {
   "id": "lossless-claw",
   "kind": "context-engine",
+  "activation": {
+    "onStartup": true
+  },
   "skills": [
     "skills/lossless-claw"
   ],
+  "contracts": {
+    "tools": [
+      "lcm_grep",
+      "lcm_describe",
+      "lcm_expand",
+      "lcm_expand_query"
+    ]
+  },
   "uiHints": {
     "enabled": {
       "label": "Enabled",
@@ -177,6 +188,10 @@
       "label": "Cold Cache Observation Threshold",
       "help": "Consecutive cold observations required before non-explicit cache misses are treated as truly cold"
     },
+    "cacheAwareCompaction.criticalBudgetPressureRatio": {
+      "label": "Critical Budget Pressure Ratio",
+      "help": "Fraction of token budget at which deferred compaction fires regardless of prompt-cache state. Defaults to 0.70 — set to 1 to disable the override and let cache-aware throttling fully control deferral."
+    },
     "dynamicLeafChunkTokens.enabled": {
       "label": "Dynamic Leaf Chunk Tokens",
       "help": "When enabled, incremental compaction uses a larger working leaf chunk in busy sessions and keeps the static floor in quieter sessions"
@@ -201,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\"}])"
@@ -370,6 +401,11 @@
           "coldCacheObservationThreshold": {
             "type": "integer",
             "minimum": 1
+          },
+          "criticalBudgetPressureRatio": {
+            "type": "number",
+            "minimum": 0,
+            "maximum": 1
           }
         }
       },
@@ -402,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.2",
+  "version": "0.9.4",
   "description": "Lossless Context Management plugin for OpenClaw — DAG-based conversation summarization with incremental compaction",
   "type": "module",
   "main": "dist/index.js",
@@ -31,20 +31,34 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@mariozechner/pi-agent-core": "0.66.1",
-    "@mariozechner/pi-ai": "0.66.1",
-    "@mariozechner/pi-coding-agent": "0.66.1",
     "@sinclair/typebox": "0.34.48"
   },
   "devDependencies": {
     "@changesets/changelog-github": "^0.6.0",
     "@changesets/cli": "^2.30.0",
+    "@mariozechner/pi-agent-core": "0.66.1",
+    "@mariozechner/pi-ai": "0.66.1",
+    "@mariozechner/pi-coding-agent": "0.66.1",
     "esbuild": "^0.28.0",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"
   },
   "peerDependencies": {
-    "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": {
+      "optional": true
+    },
+    "@mariozechner/pi-ai": {
+      "optional": true
+    },
+    "@mariozechner/pi-coding-agent": {
+      "optional": true
+    }
   },
   "publishConfig": {
     "access": "public"
@@ -52,7 +66,17 @@
   "openclaw": {
     "extensions": [
       "./dist/index.js"
-    ]
+    ],
+    "compat": {
+      "pluginApi": ">=2026.2.17 <2026.6.0",
+      "minGatewayVersion": "2026.2.17",
+      "tested": [
+        "2026.5.2"
+      ]
+    },
+    "build": {
+      "openclawVersion": "2026.2.17"
+    }
   },
   "repository": {
     "type": "git",

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

@@ -103,12 +103,14 @@ Good defaults:
 - `hotCachePressureFactor: 4`
 - `hotCacheBudgetHeadroomRatio: 0.2`
 - `coldCacheObservationThreshold: 3`
+- `criticalBudgetPressureRatio: 0.70`
 
 Operationally:
 
 - hot cache stretches the incremental leaf trigger to `dynamicLeafChunkTokens.max`
 - hot cache skips incremental maintenance entirely when the assembled context is comfortably below the real token budget
 - hot cache gets a short hysteresis window so a recent cache hit stays "hot" briefly unless telemetry shows a break
+- critical token-budget pressure bypasses hot-cache delay once the live prompt reaches `criticalBudgetPressureRatio * tokenBudget`
 - if hot-cache maintenance still runs, it stays leaf-only and suppresses follow-on condensed passes
 
 ### `dynamicLeafChunkTokens`
@@ -233,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`
@@ -428,6 +456,24 @@ Default:
 
 - `3`
 
+#### `cacheAwareCompaction.criticalBudgetPressureRatio`
+
+Fraction of the token budget at which deferred compaction bypasses hot-cache delay.
+
+Why it matters:
+
+- lets prompt-mutating deferred compaction run before the runtime falls back to emergency overflow handling
+- preserves cache-aware throttling below the pressure threshold
+- can be set to `1` to disable this pressure bypass
+
+Default:
+
+- `0.70`
+
+Env override:
+
+- `LCM_CRITICAL_BUDGET_PRESSURE_RATIO`
+
 ### `dynamicLeafChunkTokens`
 
 #### `dynamicLeafChunkTokens.enabled`