@martian-engineering/lossless-claw 0.12.0 → 0.13.0

package/docs/configuration.md

@@ -30,6 +30,23 @@ Most installations only need to override a handful of keys. If you want a comple
   "statelessSessionPatterns": [],
   "skipStatelessSessions": true,
   "contextThreshold": 0.75,
+  "contextThresholdOverrides": [
+    {
+      "name": "large-context-models",
+      "match": { "modelContextWindowMin": 900000 },
+      "contextThreshold": 0.15
+    },
+    {
+      "name": "small-context-models",
+      "match": { "modelContextWindowMax": 250000 },
+      "contextThreshold": 0.2
+    },
+    {
+      "name": "telegram-sessions",
+      "match": { "sessionPattern": "agent:*:telegram:**" },
+      "contextThreshold": 0.3
+    }
+  ],
   "freshTailCount": 64,
   "freshTailMaxTokens": 24000,
   "promptAwareEviction": false,
@@ -64,11 +81,14 @@ Most installations only need to override a handful of keys. If you want a comple
   "timezone": "America/Los_Angeles",
   "pruneHeartbeatOk": false,
   "transcriptGcEnabled": false,
+  "enableSummaryThinking": true,
   "maxAssemblyTokenBudget": 30000,
   "summaryMaxOverageFactor": 3,
   "customInstructions": "",
   "circuitBreakerThreshold": 5,
   "circuitBreakerCooldownMs": 1800000,
+  "replayFloodThresholdExternal": 3,
+  "replayFloodThresholdInternal": 32,
   "fallbackProviders": [],
   "proactiveThresholdCompactionMode": "deferred",
   "autoRotateSessionFiles": {
@@ -78,6 +98,11 @@ Most installations only need to override a handful of keys. If you want a comple
     "startup": "rotate",
     "runtime": "rotate"
   },
+  "independentLogFile": {
+    "enabled": true,
+    "file": "/tmp/openclaw/lossless-claw-2026-05-19.log",
+    "maxFileBytes": 104857600
+  },
   "cacheAwareCompaction": {
     "enabled": true,
     "cacheTTLSeconds": 300,
@@ -148,17 +173,23 @@ openclaw plugins install --link /path/to/lossless-claw
 | `timezone` | `string` | `TZ` or system timezone | `TZ` | IANA timezone used for timestamp rendering in summaries. |
 | `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. |
+| `enableSummaryThinking` | `boolean` | `true` | `LCM_ENABLE_SUMMARY_THINKING` | When true, requests low reasoning budget from the model during summarization calls. Set to false to disable reasoning and keep summarization output concise. |
 | `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.createBackups` | `boolean` | `false` | `LCM_AUTO_ROTATE_SESSION_FILES_CREATE_BACKUPS` | Creates or replaces the rolling `rotate-latest` SQLite backup before automatic session-file rotation. Manual `/lcm rotate` backups are always created. |
 | `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 post-turn checks. Runtime `rotate` logs deferral for active session JSONL rewrites and leaves direct rotation to startup or manual `/lcm rotate`. |
+| `independentLogFile.enabled` | `boolean` | `true` | `LCM_LOG_FILE_ENABLED` | Writes lossless-claw JSONL logs to an independent plugin-owned file in addition to OpenClaw's runtime logger. |
+| `independentLogFile.file` | `string` | `/tmp/openclaw/lossless-claw-YYYY-MM-DD.log` | `LCM_LOG_FILE` | Optional log path. A dated `lossless-claw-YYYY-MM-DD.log` path rolls over daily. |
+| `independentLogFile.maxFileBytes` | `integer` | `104857600` | `LCM_LOG_MAX_FILE_BYTES` | Size threshold for rotating the active lossless-claw log file to `.1.log` through `.5.log`. |
 
 > **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 rewrites only the live session transcript, keeps the active LCM conversation and durable history intact, and refreshes the bootstrap checkpoint. Before manual or startup rewrites, rotation forces leaf-only compaction for raw context outside the preserved tail so trimmed transcript messages are covered by LCM summaries without running unrelated summary-condensation passes. 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. Runtime rotation checks from `afterTurn()` and `maintain()` intentionally do not directly rewrite active session JSONL because embedded prompt-lock fences can still be open while tool-call loops and host background maintenance overlap; runtime `rotate` logs a deferral until startup, manual `/lcm rotate`, or a future host-owned full-transcript rewrite primitive is available. Automatic rotation does not create a SQLite backup by default; set `autoRotateSessionFiles.createBackups` to `true` to make startup rotation create one pre-rotation LCM database backup for the batch before any transcript is rewritten. Manual `/lcm rotate` always keeps its backup-backed behavior regardless of this flag. 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`. Transcript GC uses the host-provided `rewriteTranscriptEntries` primitive and defers until host-approved background maintenance when `transcriptGcEnabled` is enabled.
 
+Lossless-claw writes routine operational JSONL logs by default at `/tmp/openclaw/lossless-claw-YYYY-MM-DD.log`, beside OpenClaw's `/tmp/openclaw/openclaw-YYYY-MM-DD.log`. Routine info and debug lines go to the independent file instead of the shared OpenClaw log. Startup banners and warning/error lines still go through OpenClaw's runtime logger so gateway-level startup and failure diagnostics remain visible. The independent file follows the same practical rotation model as OpenClaw: a dated filename rolls over when the local date changes, stale dated files are pruned after 3 days, and an oversized active file is rotated through `.1.log` to `.5.log`.
+
 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
@@ -166,6 +197,7 @@ Every automatic decision emits grep-able log lines prefixed with `[lcm] auto-rot
 | Key | Type | Default | Env override | Purpose |
 | --- | --- | --- | --- | --- |
 | `contextThreshold` | `number` | `0.75` | `LCM_CONTEXT_THRESHOLD` | Fraction of the active model context window that triggers compaction. |
+| `contextThresholdOverrides` | `Array<{ name?: string; match: object; contextThreshold: number }>` | `[]` | none | Optional ordered rules that override `contextThreshold` by model id, model context-window range, or session glob pattern. |
 | `freshTailCount` | `integer` | `64` | `LCM_FRESH_TAIL_COUNT` | Number of newest messages always kept raw. |
 | `freshTailMaxTokens` | `integer` | unset | `LCM_FRESH_TAIL_MAX_TOKENS` | Optional token cap for the protected fresh tail. The newest message is always preserved even if it exceeds the cap. |
 | `promptAwareEviction` | `boolean` | `false` | `LCM_PROMPT_AWARE_EVICTION_ENABLED` | When enabled, budget-constrained assembly keeps older evictable items by prompt relevance instead of pure chronology. This improves retrieval under tight budgets, but it can reduce prompt-cache hit rates because the preserved prefix changes as prompts change. |
@@ -223,6 +255,8 @@ Summary calls are executed through OpenClaw's `api.runtime.llm.complete` capabil
 | `circuitBreakerThreshold` | `integer` | `5` | `LCM_CIRCUIT_BREAKER_THRESHOLD` | Consecutive auth failures before the summarization circuit breaker trips. |
 | `circuitBreakerCooldownMs` | `integer` | `1800000` | `LCM_CIRCUIT_BREAKER_COOLDOWN_MS` | Cooldown before the summarization circuit breaker resets automatically. |
 | `stripInjectedContextTags` | `string[]` | `["active_memory_plugin", "relevant-memories", "relevant_memories", "hindsight_memories"]` | `LCM_STRIP_INJECTED_CONTEXT_TAGS` | XML tag names whose blocks are stripped from message content before compaction summarization. Memory/context plugins inject these via `prependContext`; stripping prevents ephemeral retrieval context from polluting compacted summaries. Env var format is comma-separated tag names. Set to `[]` (or empty env string) to disable. |
+| `replayFloodThresholdExternal` | `integer` | `3` | `LCM_REPLAY_FLOOD_THRESHOLD_EXTERNAL` | Max replay-like messages allowed in a single SQLite-second for `role=user` before `assertNoReplayTimestampFlood` refuses the batch. Defaults to `3` to preserve replay defense for third-partyly-rebroadcastable input. |
+| `replayFloodThresholdInternal` | `integer` | `32` | `LCM_REPLAY_FLOOD_THRESHOLD_INTERNAL` | Max identical messages allowed in a single SQLite-second for `role=tool/assistant/system` before the anti-replay guard refuses the batch. Defaults to `32` to absorb legitimate idempotent sub-agent bursts (same-second tool returns like `{"status":"ok"}`). |
 
 ### Nested objects
 
@@ -249,7 +283,7 @@ Summary calls are executed through OpenClaw's `api.runtime.llm.complete` capabil
 
 Automatic compaction is threshold-only:
 
-- `afterTurn()` evaluates `contextThreshold` against the active token budget
+- `afterTurn()` evaluates the resolved context threshold against the active token budget
 - below threshold, no automatic compaction runs and no leaf debt is recorded
 - at or above threshold, inline mode runs a threshold full sweep immediately
 - deferred mode records one coalesced `"threshold"` maintenance row and normally drains it in the background or host-approved `maintain()`
@@ -257,6 +291,8 @@ Automatic compaction is threshold-only:
 
 Lossless still records prompt-cache telemetry for status and diagnostics, but cache hotness no longer delays threshold debt. Legacy `cacheAwareCompaction.*` and `dynamicLeafChunkTokens.*` settings remain accepted so existing OpenClaw config continues to load, but they do not change automatic compaction behavior.
 
+`contextThresholdOverrides` are optional and never replace the global fallback. Each rule's `match` object can include `model`, `modelContextWindowMin`, `modelContextWindowMax`, and `sessionPattern`; all fields in a rule must match. If several rules match, Lossless picks the highest-specificity rule, then the earliest rule in the array for ties. Exact `model` matches have higher specificity than `sessionPattern` matches, and session-pattern matches have higher specificity than context-window range matches. Threshold selection logs include the chosen threshold, source, rule index/name, token budget, threshold tokens, model, context-window value, and match reason.
+
 Full sweeps first run leaf passes until there are no more eligible raw-message chunks outside the fresh tail. Condensation is then driven by summarized-prefix pressure: the routine condensation phase obeys `sweepMaxDepth`, and if the summarized prefix still exceeds `summaryPrefixTargetTokens`, a pressure phase may use `condensedMinFanoutHard` and condense deeper. Total context pressure starts the sweep, but does not by itself force deeper condensation once the raw prefix has been summarized.
 
 A single sweep is bounded by both `maxSweepIterations` (a hard cap on summarizer passes) and `sweepDeadlineMs` (a wall-clock budget). When either limit is reached the sweep stops before starting another pass and returns the consistent partial result built so far, logging a `compactFullSweep stopped at …` warning. This keeps a slow or rate-limited summarizer from hanging the agent turn — remaining context pressure is picked up by the next sweep.

package/openclaw.plugin.json

@@ -25,6 +25,10 @@
       "label": "Context Threshold",
       "help": "Fraction of context window that triggers compaction (0.0–1.0)"
     },
+    "contextThresholdOverrides": {
+      "label": "Context Threshold Overrides",
+      "help": "Optional ordered rules that override contextThreshold by model, model context-window range, or session glob pattern"
+    },
     "sweepMaxDepth": {
       "label": "Sweep Max Depth",
       "help": "Preferred maximum condensation source depth during routine full sweeps (0 = leaf only, -1 = unlimited). Pressure sweeps may go deeper when summarized context remains above target."
@@ -201,6 +205,14 @@
       "label": "Circuit Breaker Cooldown (ms)",
       "help": "Cooldown before the summarization circuit breaker auto-resets"
     },
+    "replayFloodThresholdExternal": {
+      "label": "Replay Flood Threshold (External)",
+      "help": "Max replay-like messages allowed in a single SQLite-second for third-party roles (role=user) before the anti-replay guard refuses the batch. Defaults to 3 to preserve replay defense for third-partyly-rebroadcastable input."
+    },
+    "replayFloodThresholdInternal": {
+      "label": "Replay Flood Threshold (Internal)",
+      "help": "Max identical messages allowed in a single SQLite-second for internal roles (role=tool/assistant/system) before the anti-replay guard refuses the batch. Defaults to 32 to absorb legitimate idempotent sub-agent bursts."
+    },
     "cacheAwareCompaction.enabled": {
       "label": "Cache-Aware Compaction (Deprecated)",
       "help": "Deprecated compatibility setting. Automatic compaction is now threshold-only and does not use prompt-cache hot/cold state."
@@ -249,6 +261,10 @@
       "label": "Transcript GC",
       "help": "Enable transcript rewrite GC during maintain(); disabled by default"
     },
+    "enableSummaryThinking": {
+      "label": "Enable Summary Thinking",
+      "help": "Request low reasoning budget from the model during summarization calls"
+    },
     "proactiveThresholdCompactionMode": {
       "label": "Proactive Threshold Compaction Mode",
       "help": "Choose deferred compaction debt by default or keep legacy inline proactive compaction"
@@ -273,6 +289,18 @@
       "label": "Runtime Auto-Rotate",
       "help": "Runtime behavior for oversized current LCM session files: rotate, warn, or off"
     },
+    "independentLogFile.enabled": {
+      "label": "Independent Log File",
+      "help": "Write lossless-claw JSONL logs to a plugin-owned file in addition to OpenClaw's runtime logger"
+    },
+    "independentLogFile.file": {
+      "label": "Independent Log Path",
+      "help": "Optional lossless-claw log path; defaults to /tmp/openclaw/lossless-claw-YYYY-MM-DD.log with daily rollover"
+    },
+    "independentLogFile.maxFileBytes": {
+      "label": "Independent Log Max Bytes",
+      "help": "Byte threshold for size rotation of the current lossless-claw log file (default: 104857600)"
+    },
     "fallbackProviders": {
       "label": "Fallback Providers",
       "help": "Explicit runtime LLM fallback provider/model pairs for compaction summarization; entries require plugins.entries.lossless-claw.llm policy"
@@ -294,6 +322,50 @@
         "minimum": 0,
         "maximum": 1
       },
+      "contextThresholdOverrides": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "match",
+            "contextThreshold"
+          ],
+          "properties": {
+            "name": {
+              "type": "string"
+            },
+            "match": {
+              "type": "object",
+              "additionalProperties": false,
+              "minProperties": 1,
+              "properties": {
+                "model": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "modelContextWindowMin": {
+                  "type": "integer",
+                  "minimum": 1
+                },
+                "modelContextWindowMax": {
+                  "type": "integer",
+                  "minimum": 1
+                },
+                "sessionPattern": {
+                  "type": "string",
+                  "minLength": 1
+                }
+              }
+            },
+            "contextThreshold": {
+              "type": "number",
+              "minimum": 0,
+              "maximum": 1
+            }
+          }
+        }
+      },
       "sweepMaxDepth": {
         "type": "integer",
         "minimum": -1
@@ -454,6 +526,14 @@
         "type": "integer",
         "minimum": 1
       },
+      "replayFloodThresholdExternal": {
+        "type": "integer",
+        "minimum": 1
+      },
+      "replayFloodThresholdInternal": {
+        "type": "integer",
+        "minimum": 1
+      },
       "cacheAwareCompaction": {
         "type": "object",
         "additionalProperties": false,
@@ -511,6 +591,9 @@
       "transcriptGcEnabled": {
         "type": "boolean"
       },
+      "enableSummaryThinking": {
+        "type": "boolean"
+      },
       "proactiveThresholdCompactionMode": {
         "type": "string",
         "enum": [
@@ -550,6 +633,22 @@
           }
         }
       },
+      "independentLogFile": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "enabled": {
+            "type": "boolean"
+          },
+          "file": {
+            "type": "string"
+          },
+          "maxFileBytes": {
+            "type": "integer",
+            "minimum": 1
+          }
+        }
+      },
       "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.12.0",
+  "version": "0.13.0",
   "description": "Lossless Context Management plugin for OpenClaw — DAG-based conversation summarization with threshold compaction",
   "type": "module",
   "main": "dist/index.js",
@@ -35,20 +35,20 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@earendil-works/pi-agent-core": ">=0.74 <1",
-    "@earendil-works/pi-ai": ">=0.74 <1",
-    "@earendil-works/pi-coding-agent": ">=0.74 <1",
     "@sinclair/typebox": "0.34.48"
   },
   "devDependencies": {
     "@changesets/changelog-github": "^0.6.0",
     "@changesets/cli": "^2.30.0",
+    "@earendil-works/pi-agent-core": "^0.79.0",
+    "@earendil-works/pi-ai": "^0.79.0",
+    "@earendil-works/pi-coding-agent": "^0.79.0",
     "esbuild": "^0.28.0",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"
   },
   "peerDependencies": {
-    "openclaw": ">=2026.5.22"
+    "openclaw": ">=2026.5.28"
   },
   "peerDependenciesMeta": {
     "openclaw": {
@@ -63,14 +63,14 @@
       "./dist/index.js"
     ],
     "compat": {
-      "pluginApi": ">=2026.5.22",
-      "minGatewayVersion": "2026.5.22",
+      "pluginApi": ">=2026.5.28",
+      "minGatewayVersion": "2026.5.28",
       "tested": [
-        "2026.5.22"
+        "2026.5.28"
       ]
     },
     "build": {
-      "openclawVersion": "2026.5.22"
+      "openclawVersion": "2026.5.28"
     }
   },
   "repository": {

package/skills/lossless-claw/SKILL.md

@@ -11,10 +11,11 @@ Start here:
 
 1. Confirm whether the user needs configuration help, diagnostics, recall-tool guidance, or session-lifecycle guidance.
 2. If they need a quick health check, tell them to run `/lossless` (`/lcm` is the shorter alias).
-3. If they suspect summary corruption or truncation, use `/lossless doctor`.
-4. If they want high-confidence junk/session cleanup guidance, use `/lossless doctor clean` before recommending any deletes.
-5. If they ask how `/new`, `/reset`, or `/lossless rotate` interacts with LCM, read the session-lifecycle reference before answering.
-6. Load the relevant reference file instead of improvising details from memory.
+3. If they are debugging lossless-claw behavior or failures, check the independent Lossless log before the shared OpenClaw gateway log.
+4. If they suspect summary corruption or truncation, use `/lossless doctor`.
+5. If they want high-confidence junk/session cleanup guidance, use `/lossless doctor clean` before recommending any deletes.
+6. If they ask how `/new`, `/reset`, or `/lossless rotate` interacts with LCM, read the session-lifecycle reference before answering.
+7. Load the relevant reference file instead of improvising details from memory.
 
 Reference map:
 

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

@@ -30,6 +30,44 @@ Good default:
 
 - `0.75`
 
+### `contextThresholdOverrides`
+
+Optional ordered rules that choose a different compaction threshold for matching runtime contexts.
+
+Supported match fields:
+
+- `model`: exact runtime model id, such as `openai/gpt-5.5`
+- `modelContextWindowMin`: match models/windows at or above this token count
+- `modelContextWindowMax`: match models/windows at or below this token count
+- `sessionPattern`: session-key glob, using the same `*` and `**` semantics as ignored/stateless sessions
+
+Rules are AND-matched: if a rule includes both `model` and `sessionPattern`, both must match. If multiple rules match, Lossless picks the highest-specificity rule, then the earliest rule in the array for ties. If no rule matches, it falls back to global `contextThreshold`.
+
+Example:
+
+```json
+{
+  "contextThreshold": 0.75,
+  "contextThresholdOverrides": [
+    {
+      "name": "large-context-models",
+      "match": { "modelContextWindowMin": 900000 },
+      "contextThreshold": 0.15
+    },
+    {
+      "name": "telegram-sessions",
+      "match": { "sessionPattern": "agent:*:telegram:**" },
+      "contextThreshold": 0.3
+    }
+  ]
+}
+```
+
+Debugging:
+
+- threshold-selection logs include the selected threshold, source, rule index/name, token budget, threshold tokens, model, context-window value, and match reason
+- there is no env-var override for `contextThresholdOverrides`; use plugin config for structured rules
+
 ### `freshTailCount`
 
 Keeps the newest messages raw instead of compacting them.
@@ -286,6 +324,20 @@ Why it matters:
 - keep this off unless you want transcript GC to mutate the live session file during maintenance
 - the default is `false`
 
+### `enableSummaryThinking`
+
+Controls whether the summarization model receives a low reasoning budget.
+
+Why it matters:
+
+- when `true` (default), summarization calls request `reasoningIfSupported: "low"`, allowing the model to think before producing summaries — this is the current default behavior
+- when `false`, no explicit reasoning budget is requested, which can reduce cost and keep summarization output more concise when reasoning is not needed for faithful summaries
+- set to `false` when you want to minimize token spend on reasoning during compaction, especially with reasoning-capable models
+
+Env override:
+
+- `LCM_ENABLE_SUMMARY_THINKING`
+
 ### `proactiveThresholdCompactionMode`
 
 Controls whether proactive threshold compaction is deferred into maintenance debt or kept inline for legacy behavior.
@@ -326,6 +378,28 @@ Operational logging:
 - 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
 
+### `independentLogFile`
+
+Writes lossless-claw JSONL logs to an independent plugin-owned file in addition to OpenClaw's runtime logger.
+
+Defaults:
+
+- `enabled: true`
+- `file: /tmp/openclaw/lossless-claw-YYYY-MM-DD.log`
+- `maxFileBytes: 104857600`
+
+Why it matters:
+
+- keeps high-volume `[lcm]` operational traces separate from the shared OpenClaw gateway log
+- still sends startup banners and warning/error lines through OpenClaw's runtime logger, so gateway-level startup and failure diagnostics remain visible
+- a dated `lossless-claw-YYYY-MM-DD.log` path rolls over daily, stale dated files are pruned after 3 days, and oversized files rotate through `.1.log` to `.5.log`
+
+Env overrides:
+
+- `LCM_LOG_FILE_ENABLED`
+- `LCM_LOG_FILE`
+- `LCM_LOG_MAX_FILE_BYTES`
+
 ## Compaction timing and shape
 
 ### `contextThreshold`
@@ -517,6 +591,29 @@ Why it matters:
 - useful when the runtime model window is smaller than the surrounding system assumes
 - can prevent oversized assembly on smaller-context models
 
+## Anti-replay flood guard
+
+The ingest path runs `assertNoReplayTimestampFlood` to refuse batches that look like webhook-style replay attacks (many replay-like user messages or many identical internal messages at the same `created_at`). Because SQLite `datetime('now')` is second-granularity, legitimate idempotent bursts from sub-agents can also trip the guard if it is single-threshold. The role-aware thresholds below split the budget by message origin.
+
+### `replayFloodThresholdExternal`
+
+Max replay-like messages allowed in a single SQLite-second for `role=user` before the guard refuses the batch. Defaults to `3`.
+
+Why it matters:
+
+- preserves replay defense for third-partyly-rebroadcastable input
+- lower values are stricter but risk rejecting legitimate dedup retries from upstream channels
+
+### `replayFloodThresholdInternal`
+
+Max identical messages allowed in a single SQLite-second for `role=tool/assistant/system` before the guard refuses the batch. Defaults to `32`.
+
+Why it matters:
+
+- absorbs legitimate same-second idempotent tool returns (for example, sub-agents emitting many `{"status":"ok"}` results)
+- still bounded so a pathological loop cannot ingest unboundedly under the same timestamp
+- raise it if you operate cron sub-agents that emit very tight bursts; lower it if you want stricter sanity protection
+
 ## Nested objects
 
 ### `cacheAwareCompaction`

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

@@ -1,9 +1,34 @@
 # Diagnostics
 
-For the MVP, use the native command surface first.
+For the MVP, use the native command surface first. For debugging lossless-claw behavior or failures, inspect the independent Lossless log before the shared OpenClaw gateway log.
 
 ## Fast path
 
+### Independent Lossless log
+
+Check this first when lossless-claw needs to debug itself, because routine `[lcm]` info and debug lines are written here instead of the shared OpenClaw gateway log.
+
+Default path:
+
+```bash
+/tmp/openclaw/lossless-claw-YYYY-MM-DD.log
+```
+
+For today's local log, use:
+
+```bash
+tail -n 200 "/tmp/openclaw/lossless-claw-$(date +%F).log"
+```
+
+Useful patterns:
+
+```bash
+rg -n "\\[lcm\\] (auto-rotate|rotate|runtime\\.llm\\.complete|summary|compact|assembly)" /tmp/openclaw/lossless-claw-*.log
+rg -n "warn|error|failed|truncated|deterministic|fallback" /tmp/openclaw/lossless-claw-*.log
+```
+
+The dated default log rolls over daily. Dated files are pruned after 3 days, and oversized active logs rotate through `.1.log` to `.5.log`. Startup banners and warning/error lines are also sent to OpenClaw's runtime logger, so check `/tmp/openclaw/openclaw-YYYY-MM-DD.log` after the Lossless log when you need gateway-level startup or failure context.
+
 ### `/lossless` (`/lcm` alias)
 
 Use this when you need a quick health snapshot.