@martian-engineering/lossless-claw 0.9.4 → 0.11.0

package/docs/focus-briefs-implementation-plan.md

@@ -0,0 +1,240 @@
+# Focus Briefs Implementation Plan
+
+## Overview
+
+Focus briefs let a user ask Lossless to build a task-oriented view of existing
+conversation memory. A focus brief is generated by a delegated subagent that can
+search and traverse the canonical summary DAG with Lossless recall tools. The
+brief is not a summary DAG node, is not written to `context_items`, and must not
+be consumed by normal compaction. Recall tools continue to operate on the DAG.
+
+The user-facing name is **focus**. The generated artifact is a **context brief**.
+
+## Command Surface
+
+Use command words rather than flags so the interface works well on mobile:
+
+```text
+/lossless focus
+/lossless focus <prompt>
+/lossless refocus
+/lossless unfocus
+```
+
+- `/lossless focus <prompt>` runs a forced full-sweep compaction, generates or
+  refocuses around the prompt from the fresh summary frontier, and activates the
+  resulting brief.
+- `/lossless focus` reports active/draft focus state, prompt, preview, and diagnostics.
+- `/lossless refocus` refreshes the active focus brief from post-focus summary
+  deltas, preserving the original prompt and using the old brief as the baseline.
+- `/lossless unfocus` deactivates the active focus overlay once overlays exist,
+  then runs a forced full-sweep compaction.
+
+## Architecture Decisions
+
+- Focus brief generation uses a delegated subagent, not a direct summarizer call.
+  The subagent is expected to use `lcm_grep`, `lcm_describe`, and grant-scoped
+  `lcm_expand` to produce evidence-oriented content.
+- Focus briefs are persisted outside the summary DAG. They are inspectable,
+  supersedable, and later activatable, but never replace canonical storage.
+- The first implementation phases deliberately stop before mutating active
+  assembly. This lets us debug generation quality, command behavior, persistence,
+  and TUI inspection before introducing prompt-prefix overlays.
+- The assembler overlay phase must be assembly-only. Canonical `context_items`
+  remain the sole compaction source.
+- New summaries while focus is active should remain visible as post-focus delta.
+  The later overlay implementation should use a coverage watermark rather than
+  relying only on masked summary IDs.
+- Focus, refocus, and unfocus are prompt-prefix lifecycle operations. Because
+  they break prompt caching just like compaction does, they deliberately pair
+  the prefix mutation with forced full-sweep compaction: focus and refocus
+  compact before generation, while unfocus compacts after deactivation.
+
+## Phase 1: Slash Command Generates A Draft Brief
+
+Build the real generation path without changing active context.
+
+### Scope
+
+- Extend `/lossless` parsing with `focus` and `unfocus`.
+- Implement `/lossless focus <prompt>` using the active conversation resolved
+  from session identity.
+- Snapshot active summary context IDs and token counts.
+- Spawn a delegated focus subagent with a scoped expansion grant.
+- Require structured JSON from the child containing markdown brief content,
+  cited summary IDs, expansion prompts, and diagnostics.
+- Return a preview in the command response.
+- Do not persist the brief yet unless Phase 2 is already present.
+- Do not modify assembler, compaction, summaries, parents, or context items.
+
+### Acceptance Criteria
+
+- `/lossless focus <prompt>` returns a generated brief preview.
+- The child session can use `lcm_grep`, `lcm_describe`, and grant-scoped
+  `lcm_expand`.
+- The child task prompt tells it not to call `lcm_expand_query`.
+- Malformed child JSON is handled with a useful error and raw preview.
+- Existing `/lossless` commands keep working.
+
+### Verification
+
+- Parser tests cover `focus`, empty `focus`, `unfocus`, and unknown focus forms.
+- Delegation tests cover child prompt content, grant creation, wait handling,
+  parse success, and parse failure.
+- Command tests cover no active conversation, no prompt, and successful preview.
+
+## Phase 2: Persist Draft Briefs And Expose Them In The TUI
+
+Persist generated briefs outside active context so they can be inspected and
+used as later overlay inputs. Add TUI visibility for generated focus briefs.
+
+### Scope
+
+- Add migrations for focus brief tables.
+- Add a store for focus brief creation, lookup, superseding, and listing.
+- Update `/lossless focus <prompt>` to persist generated briefs as drafts in the pre-overlay phase.
+- Update `/lossless focus` to show latest draft/active state, prompt, preview,
+  source count, cited IDs, generation status, and stale/error diagnostics.
+- Add `/lossless unfocus` as a no-op or draft-state deactivation command until
+  assembly overlays exist.
+- Extend the TUI with a focus brief view so generated briefs can be browsed and
+  read from the terminal.
+- Do not show active focus content inline in conversation yet. That belongs to
+  the later active-overlay phase.
+
+### Suggested Tables
+
+```sql
+CREATE TABLE focus_briefs (
+  brief_id TEXT PRIMARY KEY,
+  conversation_id INTEGER NOT NULL,
+  session_key TEXT,
+  prompt TEXT NOT NULL,
+  content TEXT NOT NULL,
+  status TEXT NOT NULL,
+  token_count INTEGER NOT NULL DEFAULT 0,
+  target_tokens INTEGER NOT NULL DEFAULT 0,
+  covered_latest_at TEXT,
+  covered_message_seq INTEGER,
+  source_context_hash TEXT NOT NULL DEFAULT '',
+  generator_run_id TEXT,
+  generator_session_key TEXT,
+  raw_result_json TEXT,
+  error TEXT,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+  superseded_at TEXT
+);
+
+CREATE TABLE focus_brief_sources (
+  brief_id TEXT NOT NULL,
+  summary_id TEXT NOT NULL,
+  ordinal INTEGER,
+  role TEXT NOT NULL,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  PRIMARY KEY (brief_id, summary_id, role)
+);
+```
+
+### Acceptance Criteria
+
+- Generated briefs are durable and inspectable.
+- Refocus supersedes the previous current draft for the conversation.
+- Failed generations can be recorded without corrupting the latest good brief.
+- TUI can list focus briefs for the selected conversation and display full
+  content plus prompt/metadata.
+- No focus table rows are used by compaction or assembly yet.
+
+### Verification
+
+- Migration tests verify tables and indexes are created.
+- Store tests cover create, list latest, supersede, source recording, and failed
+  generation rows.
+- Command tests verify persisted status and preview.
+- TUI tests cover loading and rendering focus brief rows.
+
+## Phase 3: Brief Quality Contract
+
+Harden the generator prompt and output schema after observing Phase 1/2 output.
+
+### Required Brief Sections
+
+- Focused narrative.
+- Current working state.
+- Evidence map with summary IDs.
+- Expansion guide with exact future recall prompts.
+- Risks, gaps, contradictions, stale assumptions.
+- Likely irrelevant context.
+- Confidence/evidence notes.
+
+### Acceptance Criteria
+
+- The schema captures cited IDs, expansion prompts, truncation state, and
+  confidence notes.
+- The command response and TUI surface enough metadata to troubleshoot brief
+  quality without reading raw DB rows.
+
+## Phase 4: Assembly-Time Overlay
+
+Make active focus mode affect assembled context.
+
+### Scope
+
+- Add active-focus lookup to assembly.
+- Replace covered summary prefix with one `<focus_brief>` user message.
+- Preserve fresh tail and post-focus delta.
+- Keep canonical `context_items` unchanged.
+- Ensure compaction never reads focus brief rows as source material.
+- Promote successful `/lossless focus <prompt>` generations to active overlays.
+- Make `/lossless unfocus` deactivate active overlays without deleting brief history.
+- Run forced full-sweep compaction before focus generation so the delegated
+  subagent reads the freshest balanced summary frontier.
+- Run forced full-sweep compaction before refocus generation, then give the
+  delegated subagent the old active brief plus summaries beyond the old focus
+  watermark as delta input. A successful refocus writes a new active brief with
+  advanced coverage watermarks; a failed refocus leaves the old active brief in
+  place.
+- Run forced full-sweep compaction after unfocus so the normal DAG view is
+  restored with the same cache break that removed the overlay.
+
+### Acceptance Criteria
+
+- Assembled prompts include the active focus brief.
+- Canonical context and DAG remain unchanged.
+- New messages/summaries after the focus watermark remain visible.
+- Unfocus restores normal assembly.
+
+## Phase 5: Unfocus, Refocus, And Drift Diagnostics
+
+Complete the operational lifecycle.
+
+### Scope
+
+- Harden refocus atomicity: failed new generation must not destroy the old active
+  focus.
+- Show delta since focus: message count, summary count, and estimated tokens.
+- Warn when active focus is stale, truncated, or generated from an obsolete
+  source snapshot.
+
+### Acceptance Criteria
+
+- Focus lifecycle is reversible and debuggable.
+- Drift is visible in `/lossless` status and TUI.
+
+## Risks And Mitigations
+
+| Risk | Impact | Mitigation |
+| --- | --- | --- |
+| Child calls `lcm_expand_query` recursively | High | Prompt explicitly forbids it; reuse recursion guard language; subagent should use `lcm_expand` directly. |
+| Brief is accidentally compacted | High | Never store brief as summary or context item; later overlay is assembly-only. |
+| Masking breaks after DAG reshaping | High | Use coverage watermarks in overlay phase; keep masked IDs as diagnostics. |
+| Command responses are too small for full briefs | Medium | Persist full content in Phase 2; command shows preview and brief ID. |
+| Generation quality is weak | Medium | Ship Phases 1/2 before overlay; inspect drafts in TUI; iterate prompt/schema. |
+| Ambient subagent cleanup fails | Medium | Follow existing delegated expansion cleanup/revoke patterns. |
+
+## Not Doing Yet
+
+- No active prompt-prefix mutation in Phases 1 or 2.
+- No `/compact` integration until the Lossless command path is proven.
+- No changes to recall tool search semantics.
+- No destructive cleanup of focus brief history.

package/docs/tui.md

@@ -49,7 +49,7 @@ Lists all agents discovered under `~/.openclaw/agents/`. Select an agent to see
 
 ### Screen 2: Session List
 
-Shows JSONL session files for the selected agent, sorted by last modified time. Each entry shows the filename, last update time, message count, conversation ID (if LCM-tracked), summary count, and large file count.
+Shows JSONL session files for the selected agent, sorted by last modified time. Each entry shows the filename, last update time, message count, conversation ID (if LCM-tracked), summary count, and large file count. If an OpenClaw session has a Codex app-server binding, the row also shows a `codex:` marker with the local backend rollout row count when available.
 
 Sessions load in batches of 50. Scrolling near the bottom automatically loads more.
 
@@ -57,6 +57,8 @@ Sessions load in batches of 50. Scrolling near the bottom automatically loads mo
 |-----|--------|
 | `↑`/`↓` or `k`/`j` | Move cursor |
 | `Enter` | Open conversation |
+| `x` | Open bound Codex backend rollout transcript, when available |
+| `v` | Compare bound Codex backend rollout against the LCM active context |
 | `b`/`Backspace` | Back to agents |
 | `r` | Reload sessions |
 | `q` | Quit |
@@ -84,11 +86,17 @@ For sessions with an LCM `conv_id`, the conversation view uses keyset-paged wind
 | `]` | Load newer message window |
 | `l` | Open **Summary DAG** view |
 | `c` | Open **Context** view |
+| `o` | Open **Focus Briefs** view |
 | `f` | Open **Large Files** view |
+| `v` | Open **Codex ↔ LCM** comparison view |
 | `b`/`Backspace` | Back to sessions |
 | `r` | Reload messages |
 | `q` | Quit |
 
+### Codex ↔ LCM Comparison
+
+For Codex app-server bound sessions, the comparison view renders native Codex backend rollout rows beside the Lossless-managed active context items for the same OpenClaw session. The panes are index-aligned for inspection rather than treated as a causal one-to-one mapping: Codex rows show what the backend session recorded, while LCM rows show summaries and fresh-tail messages that Lossless would assemble.
+
 ## Summary DAG View
 
 The core inspection tool. Shows the full hierarchy of LCM summaries for a conversation as an expandable tree.
@@ -161,6 +169,22 @@ The status bar shows totals: how many summaries, how many messages, total items,
 | `b`/`Backspace` | Back to conversation |
 | `q` | Quit |
 
+## Focus Briefs View
+
+Lists focus briefs generated for the selected LCM conversation. Each row shows status, creation time, brief ID, token count, and prompt preview. The detail panel shows generator metadata, source/citation counts, post-focus drift diagnostics, cited and expanded summary IDs, the original focus prompt, and the generated brief content.
+
+This view is read-only. When a focus brief is active, the conversation and active-context screens show a compact focus banner with the brief ID, prompt preview, token count, and stale/source-snapshot diagnostics.
+
+| Key | Action |
+|-----|--------|
+| `↑`/`↓` or `k`/`j` | Move cursor |
+| `g`/`G` | Jump to first/last |
+| `Shift+J` | Scroll detail panel down |
+| `Shift+K` | Scroll detail panel up |
+| `r` | Reload focus briefs |
+| `b`/`Backspace` | Back to conversation |
+| `q` | Quit |
+
 ## Large Files View
 
 Lists files that exceeded the large file threshold (default 25k tokens) and were intercepted by LCM. Shows file ID, display name, MIME type, byte size, and creation time. The detail panel shows the exploration summary that was generated as a lightweight stand-in.

package/doctor-contract-api.d.ts

@@ -0,0 +1,34 @@
+export type LosslessRuntimeLlmModelRef = {
+  field: string;
+  modelRef: string;
+  configPath: string;
+};
+
+export type LosslessRuntimeLlmSkippedModelRef = {
+  field: string;
+  configPath: string;
+  reason: string;
+};
+
+export type LegacyConfigRule = {
+  path: string[];
+  message: string;
+  match?: (value: unknown, root: Record<string, unknown>) => boolean;
+};
+
+export const legacyConfigRules: LegacyConfigRule[];
+
+export function normalizeCompatibilityConfig(params: { cfg: unknown }): {
+  config: any;
+  changes: string[];
+};
+
+export function collectLosslessRuntimeLlmModelRefs(cfg: unknown): {
+  modelRefs: LosslessRuntimeLlmModelRef[];
+  skipped: LosslessRuntimeLlmSkippedModelRef[];
+};
+
+export function collectLosslessSubagentModelRefs(cfg: unknown): {
+  modelRefs: LosslessRuntimeLlmModelRef[];
+  skipped: LosslessRuntimeLlmSkippedModelRef[];
+};

package/doctor-contract-api.js

@@ -0,0 +1,349 @@
+const PLUGIN_ID = "lossless-claw";
+const ENTRY_PATH = ["plugins", "entries", PLUGIN_ID];
+const CONFIG_PATH = [...ENTRY_PATH, "config"];
+
+function isRecord(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+function readString(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : "";
+}
+
+function readEntry(cfg) {
+  const plugins = isRecord(cfg) ? cfg.plugins : undefined;
+  const entries = isRecord(plugins) ? plugins.entries : undefined;
+  const entry = isRecord(entries) ? entries[PLUGIN_ID] : undefined;
+  return isRecord(entry) ? entry : undefined;
+}
+
+function readConfig(cfg) {
+  const config = readEntry(cfg)?.config;
+  return isRecord(config) ? config : undefined;
+}
+
+function readModelOverridePolicy(cfg, policyKey) {
+  const policy = readEntry(cfg)?.[policyKey];
+  if (!isRecord(policy)) {
+    return {
+      allowModelOverride: false,
+      allowedModels: [],
+    };
+  }
+  return {
+    allowModelOverride: policy.allowModelOverride === true,
+    allowedModels: Array.isArray(policy.allowedModels) ? policy.allowedModels : [],
+  };
+}
+
+function readLlmPolicy(cfg) {
+  return readModelOverridePolicy(cfg, "llm");
+}
+
+function readSubagentPolicy(cfg) {
+  return readModelOverridePolicy(cfg, "subagent");
+}
+
+function toModelRef(provider, model) {
+  const modelId = readString(model);
+  if (!modelId) {
+    return undefined;
+  }
+  const slash = modelId.indexOf("/");
+  if (slash > 0 && slash < modelId.length - 1) {
+    const directProvider = modelId.slice(0, slash).trim();
+    const directModel = modelId.slice(slash + 1).trim();
+    return directProvider && directModel ? `${directProvider}/${directModel}` : undefined;
+  }
+  const providerId = readString(provider);
+  return providerId ? `${providerId}/${modelId}` : undefined;
+}
+
+function uniqueModelRefs(modelRefs) {
+  const seen = new Set();
+  return modelRefs.filter((entry) => {
+    const key = `${entry.field}:${entry.modelRef}`;
+    if (seen.has(key)) {
+      return false;
+    }
+    seen.add(key);
+    return true;
+  });
+}
+
+/** Collect configured Lossless summary model refs that doctor can safely allowlist. */
+function collectLosslessRuntimeLlmModelRefs(cfg) {
+  const config = readConfig(cfg);
+  if (!config) {
+    return { modelRefs: [], skipped: [] };
+  }
+
+  const modelRefs = [];
+  const skipped = [];
+  const addConfiguredModel = (field, model, provider, configPath) => {
+    const modelId = readString(model);
+    if (!modelId) {
+      return;
+    }
+    const modelRef = toModelRef(provider, modelId);
+    if (modelRef) {
+      modelRefs.push({ field, modelRef, configPath });
+      return;
+    }
+    skipped.push({
+      field,
+      configPath,
+      reason: `${field} is a bare model without a provider; use provider/model or set the matching provider field so doctor can update plugins.entries.${PLUGIN_ID}.llm.allowedModels.`,
+    });
+  };
+
+  addConfiguredModel(
+    "summaryModel",
+    config.summaryModel,
+    config.summaryProvider,
+    [...CONFIG_PATH, "summaryModel"].join("."),
+  );
+  addConfiguredModel(
+    "largeFileSummaryModel",
+    config.largeFileSummaryModel,
+    config.largeFileSummaryProvider,
+    [...CONFIG_PATH, "largeFileSummaryModel"].join("."),
+  );
+
+  if (Array.isArray(config.fallbackProviders)) {
+    for (const [index, fallback] of config.fallbackProviders.entries()) {
+      if (!isRecord(fallback)) {
+        skipped.push({
+          field: "fallbackProviders",
+          configPath: `${[...CONFIG_PATH, "fallbackProviders"].join(".")}[${index}]`,
+          reason:
+            "fallbackProviders entries must be objects with provider and model before doctor can update llm.allowedModels.",
+        });
+        continue;
+      }
+      const modelRef = toModelRef(fallback.provider, fallback.model);
+      if (modelRef) {
+        modelRefs.push({
+          field: "fallbackProviders",
+          modelRef,
+          configPath: `${[...CONFIG_PATH, "fallbackProviders"].join(".")}[${index}]`,
+        });
+      } else if (readString(fallback.model) || readString(fallback.provider)) {
+        skipped.push({
+          field: "fallbackProviders",
+          configPath: `${[...CONFIG_PATH, "fallbackProviders"].join(".")}[${index}]`,
+          reason:
+            "fallbackProviders entries need both provider and model before doctor can update llm.allowedModels.",
+        });
+      }
+    }
+  }
+
+  return {
+    modelRefs: uniqueModelRefs(modelRefs),
+    skipped,
+  };
+}
+
+/** Collect configured Lossless expansion model refs that doctor can safely allowlist. */
+function collectLosslessSubagentModelRefs(cfg) {
+  const config = readConfig(cfg);
+  if (!config) {
+    return { modelRefs: [], skipped: [] };
+  }
+
+  const modelRefs = [];
+  const skipped = [];
+  const modelId = readString(config.expansionModel);
+  if (modelId) {
+    const modelRef = toModelRef(config.expansionProvider, modelId);
+    if (modelRef) {
+      modelRefs.push({
+        field: "expansionModel",
+        modelRef,
+        configPath: [...CONFIG_PATH, "expansionModel"].join("."),
+      });
+    } else {
+      skipped.push({
+        field: "expansionModel",
+        configPath: [...CONFIG_PATH, "expansionModel"].join("."),
+        reason:
+          `expansionModel is a bare model without a provider; use provider/model or set plugins.entries.${PLUGIN_ID}.config.expansionProvider so doctor can update plugins.entries.${PLUGIN_ID}.subagent.allowedModels.`,
+      });
+    }
+  }
+
+  return {
+    modelRefs: uniqueModelRefs(modelRefs),
+    skipped,
+  };
+}
+
+function collectMissingPolicyEntries(cfg) {
+  const { modelRefs, skipped } = collectLosslessRuntimeLlmModelRefs(cfg);
+  const policy = readLlmPolicy(cfg);
+  const allowedStrings = new Set(policy.allowedModels.filter((entry) => typeof entry === "string"));
+  const missingRefs = allowedStrings.has("*")
+    ? []
+    : modelRefs.filter((entry) => !allowedStrings.has(entry.modelRef));
+  return {
+    modelRefs,
+    skipped,
+    missingRefs,
+    missingAllowModelOverride: modelRefs.length > 0 && policy.allowModelOverride !== true,
+  };
+}
+
+function collectMissingSubagentPolicyEntries(cfg) {
+  const { modelRefs, skipped } = collectLosslessSubagentModelRefs(cfg);
+  const policy = readSubagentPolicy(cfg);
+  const allowedStrings = new Set(policy.allowedModels.filter((entry) => typeof entry === "string"));
+  const missingRefs = allowedStrings.has("*")
+    ? []
+    : modelRefs.filter((entry) => !allowedStrings.has(entry.modelRef));
+  return {
+    modelRefs,
+    skipped,
+    missingRefs,
+    missingAllowModelOverride: modelRefs.length > 0 && policy.allowModelOverride !== true,
+  };
+}
+
+function hasIssueForField(cfg, field) {
+  const issues = collectMissingPolicyEntries(cfg);
+  return (
+    issues.missingAllowModelOverride ||
+    issues.missingRefs.some((entry) => entry.field === field) ||
+    issues.skipped.some((entry) => entry.field === field)
+  );
+}
+
+function hasSubagentIssueForField(cfg, field) {
+  const issues = collectMissingSubagentPolicyEntries(cfg);
+  return (
+    issues.missingAllowModelOverride ||
+    issues.missingRefs.some((entry) => entry.field === field) ||
+    issues.skipped.some((entry) => entry.field === field)
+  );
+}
+
+function needsPolicyRepair(issues) {
+  return issues.missingAllowModelOverride || issues.missingRefs.length > 0;
+}
+
+/** Doctor warning rules for Lossless runtime LLM and subagent model override policy. */
+export const legacyConfigRules = [
+  {
+    path: [...CONFIG_PATH, "summaryModel"],
+    message:
+      'Lossless summaryModel uses api.runtime.llm.complete model overrides. Configure plugins.entries.lossless-claw.llm.allowModelOverride and allowedModels, or run "openclaw doctor --fix".',
+    match: (_value, root) => hasIssueForField(root, "summaryModel"),
+  },
+  {
+    path: [...CONFIG_PATH, "largeFileSummaryModel"],
+    message:
+      'Lossless largeFileSummaryModel uses api.runtime.llm.complete model overrides. Configure plugins.entries.lossless-claw.llm.allowModelOverride and allowedModels, or run "openclaw doctor --fix".',
+    match: (_value, root) => hasIssueForField(root, "largeFileSummaryModel"),
+  },
+  {
+    path: [...CONFIG_PATH, "fallbackProviders"],
+    message:
+      'Lossless fallbackProviders use api.runtime.llm.complete model overrides. Configure plugins.entries.lossless-claw.llm.allowModelOverride and allowedModels, or run "openclaw doctor --fix".',
+    match: (_value, root) => hasIssueForField(root, "fallbackProviders"),
+  },
+  {
+    path: [...CONFIG_PATH, "expansionModel"],
+    message:
+      'Lossless expansionModel uses delegated sub-agent model overrides. Configure plugins.entries.lossless-claw.subagent.allowModelOverride and allowedModels, or run "openclaw doctor --fix".',
+    match: (_value, root) => hasSubagentIssueForField(root, "expansionModel"),
+  },
+];
+
+function cloneRootWithLosslessEntry(cfg) {
+  const root = isRecord(cfg) ? { ...cfg } : {};
+  const plugins = isRecord(root.plugins) ? { ...root.plugins } : {};
+  const entries = isRecord(plugins.entries) ? { ...plugins.entries } : {};
+  const entry = isRecord(entries[PLUGIN_ID]) ? { ...entries[PLUGIN_ID] } : {};
+
+  root.plugins = plugins;
+  plugins.entries = entries;
+  entries[PLUGIN_ID] = entry;
+
+  return { root, entry };
+}
+
+function ensurePolicy(entry, policyKey) {
+  const policy = isRecord(entry[policyKey]) ? { ...entry[policyKey] } : {};
+  entry[policyKey] = policy;
+  return policy;
+}
+
+function applyModelOverridePolicyRepair({ policy, issues, changes, policyPath, subject }) {
+  if (issues.modelRefs.length === 0) {
+    return;
+  }
+
+  if (policy.allowModelOverride !== true) {
+    policy.allowModelOverride = true;
+    changes.push(
+      `Set plugins.entries.lossless-claw.${policyPath}.allowModelOverride = true for configured Lossless ${subject} model overrides.`,
+    );
+  }
+
+  const currentAllowed = Array.isArray(policy.allowedModels) ? [...policy.allowedModels] : [];
+  const allowedStrings = new Set(currentAllowed.filter((entry) => typeof entry === "string"));
+  const added = [];
+  if (!allowedStrings.has("*")) {
+    for (const { modelRef } of issues.modelRefs) {
+      if (!allowedStrings.has(modelRef)) {
+        currentAllowed.push(modelRef);
+        allowedStrings.add(modelRef);
+        added.push(modelRef);
+      }
+    }
+  }
+
+  if (added.length > 0 || !Array.isArray(policy.allowedModels)) {
+    policy.allowedModels = currentAllowed;
+    changes.push(
+      `Added plugins.entries.lossless-claw.${policyPath}.allowedModels entries for configured Lossless ${subject} models: ${added.join(", ")}`,
+    );
+  }
+}
+
+/** Add the minimal plugin policies needed for configured Lossless model overrides. */
+export function normalizeCompatibilityConfig({ cfg }) {
+  const issues = collectMissingPolicyEntries(cfg);
+  const subagentIssues = collectMissingSubagentPolicyEntries(cfg);
+  const repairRuntimeLlmPolicy = needsPolicyRepair(issues);
+  const repairSubagentPolicy = needsPolicyRepair(subagentIssues);
+  if (!repairRuntimeLlmPolicy && !repairSubagentPolicy) {
+    return { config: cfg, changes: [] };
+  }
+
+  const { root, entry } = cloneRootWithLosslessEntry(cfg);
+  const changes = [];
+
+  if (repairRuntimeLlmPolicy) {
+    applyModelOverridePolicyRepair({
+      policy: ensurePolicy(entry, "llm"),
+      issues,
+      changes,
+      policyPath: "llm",
+      subject: "summary",
+    });
+  }
+  if (repairSubagentPolicy) {
+    applyModelOverridePolicyRepair({
+      policy: ensurePolicy(entry, "subagent"),
+      issues: subagentIssues,
+      changes,
+      policyPath: "subagent",
+      subject: "expansion",
+    });
+  }
+
+  return { config: root, changes };
+}
+
+export { collectLosslessRuntimeLlmModelRefs, collectLosslessSubagentModelRefs };