pi-m3fix 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hypernewbie
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,118 @@
+# pi-m3fix
+
+[![CI](https://github.com/hypernewbie/pi-m3fix/actions/workflows/ci.yml/badge.svg)](https://github.com/hypernewbie/pi-m3fix/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/pi-m3fix.svg)](https://www.npmjs.com/package/pi-m3fix)
+
+Pi extension for repairing session files affected by flattened reasoning blocks.
+
+## Install
+
+From npm (recommended, versioned):
+
+```bash
+pi install npm:pi-m3fix
+```
+
+Pin to a specific version:
+
+```bash
+pi install npm:pi-m3fix@0.2.1
+```
+
+From GitHub, latest `main`:
+
+```bash
+pi install git:github.com/hypernewbie/pi-m3fix
+```
+
+From GitHub, pinned to a released tag:
+
+```bash
+pi install git:github.com/hypernewbie/pi-m3fix@v0.2.1
+```
+
+`v0.1.0` was broken (see [CHANGELOG.md](CHANGELOG.md)) and has been removed. Do not install it.
+
+Local development checkout:
+
+```bash
+pi install /path/to/pi-m3fix
+```
+
+Restart Pi or run `/reload`, then use `/m3fix`.
+
+## Usage
+
+```text
+/m3fix [partial-session-id|session-file] [options]
+```
+
+Examples:
+
+```text
+/m3fix --dry-run
+/m3fix --force-live
+/m3fix 019f311c --provider m3 --api anthropic-messages --model MiniMax-M3
+/m3fix /absolute/path/to/session.jsonl --dry-run
+```
+
+Options:
+
+- `--dry-run`, `-n` — show changes without writing.
+- `--force-live` — repair the loaded session and reload it from disk.
+- `--provider <id>` — override the target provider.
+- `--api <api>` — override the target API.
+- `--model <id>` — override the target model.
+- `--no-relabel` — skip provider/API/model relabeling.
+- `--no-unflatten` — skip text-to-thinking repair.
+- `--allow-empty-signature` — force the signature/unflatten repair even if compat metadata is missing/unproven for the current model. Use this for custom providers (e.g. MiniMax M3 through an anthropic-messages-compatible endpoint) that tolerate empty thinking signatures but don't have `compat.allowEmptySignature: true` registered.
+
+## Behavior
+
+For assistant messages, `/m3fix` can:
+
+1. Set `provider`, `api`, and `model` to the selected target model.
+2. Clear stale `thinkingSignature` values on non-redacted thinking blocks.
+3. Convert active-context text blocks back into thinking blocks.
+
+Active context is computed from Pi's session tree using the current leaf and compaction metadata, so branched sessions are handled correctly.
+
+Signature clearing and text-to-thinking repair only run for compatible Anthropic Messages reasoning models. "Compatible" is determined like this:
+
+- If you pass an explicit `--provider`/`--api`/`--model` target with `--api anthropic-messages`, the repair runs — this is treated as an informed opt-in, same as the original `underp.py` script, and does not require `compat.allowEmptySignature` to be registered.
+- If you rely on the currently selected model (no explicit target), the repair only runs if that model's registry entry has `compat.allowEmptySignature: true`. Otherwise it's skipped with a warning, unless you pass `--allow-empty-signature` to force it.
+
+If the repair is skipped, `provider`/`api`/`model` relabeling and signature blanking still happen, but leaked-reasoning text blocks are **not** converted back into `thinking` blocks — leaving corrupted context that the model can imitate on the next turn. If your model output starts degrading right after `/m3fix`, check the notification for a "does not have compat.allowEmptySignature=true" warning and re-run with `--allow-empty-signature` or explicit `--provider/--api/--model` flags.
+
+Redacted thinking blocks are never modified.
+
+## Safety
+
+- Creates a one-time `.bak2` backup before writing.
+- Writes through a temporary file and atomic rename.
+- Re-opens the repaired file with Pi's `SessionManager` to validate it.
+- Refuses to modify the loaded session unless `--force-live` is supplied.
+
+## Development
+
+```bash
+npm install
+npm test
+npm run typecheck
+npm pack --dry-run
+```
+
+## Releasing (maintainers)
+
+CI publishes to npm via [OIDC trusted publishing](https://docs.npmjs.com/trusted-publishers/) — no npm token involved. To cut a release:
+
+1. Bump `version` in `package.json`.
+2. Commit, then tag `vX.Y.Z` matching that version and push both:
+   ```bash
+   git tag -a vX.Y.Z -m "vX.Y.Z"
+   git push origin main
+   git push origin vX.Y.Z
+   ```
+3. CI runs tests, verifies the tag matches `package.json`'s version, then publishes via OIDC. Provenance is generated automatically.
+
+The npm package's Trusted Publisher is configured to only accept publishes from this repo's `.github/workflows/ci.yml` workflow. Publishing access via classic/granular tokens is disabled on npmjs.com ("Require two-factor authentication and disallow tokens"), so a compromised or misconfigured token cannot publish a release.

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "pi-m3fix",
+  "version": "0.2.1",
+  "description": "Pi extension that repairs flattened reasoning blocks in compacted sessions",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "session-repair",
+    "m3"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hypernewbie/pi-m3fix.git"
+  },
+  "homepage": "https://github.com/hypernewbie/pi-m3fix",
+  "bugs": "https://github.com/hypernewbie/pi-m3fix/issues",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "vitest --run",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-ai": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.80.3",
+    "@earendil-works/pi-ai": "^0.80.3",
+    "@types/node": "^24.12.4",
+    "tsx": "^4.23.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.9"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "files": [
+    "src/",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/src/args.ts

@@ -0,0 +1,98 @@
+export interface M3FixOptions {
+	query?: string;
+	dryRun: boolean;
+	forceLive: boolean;
+	noRelabel: boolean;
+	noUnflatten: boolean;
+	allowEmptySignature: boolean;
+	target?: {
+		provider?: string;
+		api?: string;
+		model?: string;
+	};
+}
+
+const TARGET_FLAGS = new Set(["--provider", "--api", "--model"]);
+
+export function parseCommandArgs(input: string): M3FixOptions {
+	const options: M3FixOptions = {
+		dryRun: false,
+		forceLive: false,
+		noRelabel: false,
+		noUnflatten: false,
+		allowEmptySignature: false,
+	};
+
+	const positional: string[] = [];
+	const tokens = tokenize(input);
+
+	for (let i = 0; i < tokens.length; i++) {
+		const token = tokens[i];
+		if (token === "--dry-run" || token === "-n") {
+			options.dryRun = true;
+		} else if (token === "--force-live") {
+			options.forceLive = true;
+		} else if (token === "--no-relabel") {
+			options.noRelabel = true;
+		} else if (token === "--no-unflatten") {
+			options.noUnflatten = true;
+		} else if (token === "--allow-empty-signature") {
+			options.allowEmptySignature = true;
+		} else if (TARGET_FLAGS.has(token)) {
+			const value = tokens[++i];
+			if (value === undefined) {
+				throw new Error(`Missing value for ${token}`);
+			}
+			options.target ??= {};
+			if (token === "--provider") options.target.provider = value;
+			if (token === "--api") options.target.api = value;
+			if (token === "--model") options.target.model = value;
+		} else if (token.startsWith("-")) {
+			throw new Error(`Unknown flag: ${token}`);
+		} else {
+			positional.push(token);
+		}
+	}
+
+	if (positional.length > 1) {
+		throw new Error("Expected at most one positional argument (session UUID or path)");
+	}
+	options.query = positional[0];
+
+	return options;
+}
+
+function tokenize(input: string): string[] {
+	const tokens: string[] = [];
+	let current = "";
+	let inQuotes = false;
+	let quoteChar = "";
+
+	for (const char of input) {
+		if (inQuotes) {
+			if (char === quoteChar) {
+				inQuotes = false;
+				tokens.push(current);
+				current = "";
+			} else {
+				current += char;
+			}
+		} else if (char === '"' || char === "'") {
+			inQuotes = true;
+			quoteChar = char;
+		} else if (/\s/.test(char)) {
+			if (current.length > 0) {
+				tokens.push(current);
+				current = "";
+			}
+		} else {
+			current += char;
+		}
+	}
+
+	if (current.length > 0) {
+		tokens.push(current);
+	}
+
+	return tokens;
+}

package/src/index.ts

@@ -0,0 +1,122 @@
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { parseCommandArgs } from "./args.ts";
+import { findSessionFiles } from "./session-find.ts";
+import { resolveTargetModel } from "./target-model.ts";
+import { repairSessionFile } from "./repair.ts";
+
+export default function piM3FixExtension(pi: ExtensionAPI) {
+	pi.registerCommand("m3fix", {
+		description: "Repair flattened reasoning blocks in a Pi session JSONL file",
+		handler: async (args, ctx) => {
+			try {
+				await runM3Fix(args, ctx);
+			} catch (error) {
+				const message = error instanceof Error ? error.message : String(error);
+				if (ctx.hasUI) {
+					ctx.ui.notify(`m3fix failed: ${message}`, "error");
+				} else {
+					console.error(`m3fix failed: ${message}`);
+				}
+			}
+		},
+	});
+}
+
+async function runM3Fix(args: string, ctx: ExtensionCommandContext) {
+	const options = parseCommandArgs(args);
+	const currentSessionFile = ctx.sessionManager.getSessionFile();
+
+	const matches = await findSessionFiles({
+		query: options.query,
+		currentSessionFile,
+	});
+
+	if (matches.length === 0) {
+		notify(ctx, "No persisted session file matched the query.", "error");
+		return;
+	}
+
+	let selectedFile: string;
+	if (matches.length === 1) {
+		selectedFile = matches[0].file;
+	} else if (ctx.hasUI) {
+		const choice = await ctx.ui.select(
+			"Multiple sessions matched. Pick one:",
+			matches.map((m) => m.file),
+		);
+		if (!choice) {
+			notify(ctx, "No session selected.", "warning");
+			return;
+		}
+		selectedFile = choice;
+	} else {
+		notify(ctx, `Multiple sessions matched: ${matches.map((m) => m.file).join(", ")}`, "error");
+		return;
+	}
+
+	const resolved = resolveTargetModel({
+		currentModel: ctx.model,
+		explicit: options.target,
+		forceAllowEmptySignature: options.allowEmptySignature,
+	});
+
+	if (!resolved) {
+		notify(ctx, "Could not resolve target model. Use --provider/--api/--model.", "error");
+		return;
+	}
+
+	const { target, compat } = resolved;
+
+	// Safety: refuse to modify the currently loaded session unless forced
+	if (selectedFile === currentSessionFile && !options.forceLive) {
+		notify(
+			ctx,
+			"Refusing to modify the currently loaded session file. Use --force-live, or /quit and run again.",
+			"error",
+		);
+		return;
+	}
+
+	if (!compat.compatible && !options.noUnflatten) {
+		notify(ctx, `${compat.reason} Skipping signature blank/unflatten.`, "warning");
+	}
+
+	const result = await repairSessionFile(selectedFile, {
+		target,
+		dryRun: options.dryRun,
+		noRelabel: options.noRelabel,
+		noUnflatten: options.noUnflatten,
+		allowEmptySignature: compat.compatible,
+	});
+
+	const mode = options.dryRun ? "Would" : "Did";
+	notify(
+		ctx,
+		`${mode} relabel ${result.stats.relabeled}, blank ${result.stats.blanked}, unflatten ${result.stats.unflattened} blocks (${result.stats.activeAssistantTurns} turns).`,
+		result.changed ? "info" : "warning",
+	);
+
+	if (result.backupPath) {
+		notify(ctx, `Backup: ${result.backupPath}`, "info");
+	}
+
+	if (!options.dryRun && result.changed && selectedFile === currentSessionFile) {
+		notify(ctx, "Session file repaired. Reloading from disk...", "info");
+		const switchResult = await ctx.switchSession(selectedFile, {
+			withSession: async (newCtx) => {
+				notify(newCtx, "Repaired session reloaded.", "info");
+			},
+		});
+		if (switchResult.cancelled) {
+			notify(ctx, "Session reload was cancelled. /quit and re-run pi, or /resume to load the repaired file.", "warning");
+		}
+	}
+}
+
+function notify(ctx: ExtensionCommandContext, message: string, level: "info" | "warning" | "error") {
+	if (ctx.hasUI) {
+		ctx.ui.notify(message, level);
+	} else {
+		console.log(`[${level}] ${message}`);
+	}
+}

package/src/repair.ts

@@ -0,0 +1,226 @@
+import { readFile, writeFile, rename } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { SessionManager, type SessionEntry, type SessionMessageEntry } from "@earendil-works/pi-coding-agent";
+import type { TargetModel } from "./target-model.ts";
+
+export interface RepairStats {
+	relabeled: number;
+	blanked: number;
+	unflattened: number;
+	activeAssistantTurns: number;
+}
+
+export interface RepairResult {
+	changed: boolean;
+	stats: RepairStats;
+	backupPath?: string;
+}
+
+export interface RepairOptions {
+	target: TargetModel;
+	dryRun?: boolean;
+	noRelabel?: boolean;
+	noUnflatten?: boolean;
+	allowEmptySignature?: boolean;
+}
+
+export async function repairSessionFile(
+	sessionFile: string,
+	options: RepairOptions,
+): Promise<RepairResult> {
+	const sm = await SessionManager.open(sessionFile);
+	const activeIds = new Set<string>();
+	let lastActiveAssistantId: string | undefined;
+
+	for (const entry of buildActiveEntries(sm)) {
+		activeIds.add(entry.id);
+		if (entry.type === "message" && entry.message.role === "assistant") {
+			lastActiveAssistantId = entry.id;
+		}
+	}
+
+	const raw = await readFile(sessionFile, "utf8");
+	const lines = raw.split(/\r?\n/).filter((line) => line.trim().length > 0);
+	const stats: RepairStats = {
+		relabeled: 0,
+		blanked: 0,
+		unflattened: 0,
+		activeAssistantTurns: 0,
+	};
+
+	let changed = false;
+	const outputLines: string[] = [];
+
+	for (const line of lines) {
+		const entry = JSON.parse(line) as SessionEntry;
+
+		if (entry.type === "message" && entry.message.role === "assistant") {
+			const wasChanged = transformAssistantEntry(
+				entry as SessionMessageEntry,
+				activeIds,
+				lastActiveAssistantId,
+				options,
+				stats,
+			);
+			if (wasChanged) changed = true;
+		}
+
+		outputLines.push(JSON.stringify(entry));
+	}
+
+	if (options.dryRun || !changed) {
+		return { changed, stats };
+	}
+
+	const backupPath = `${sessionFile}.bak2`;
+	if (!existsSync(backupPath)) {
+		await writeFile(backupPath, raw, "utf8");
+	}
+
+	const tempPath = `${sessionFile}.tmp-${Date.now()}`;
+	await writeFile(tempPath, outputLines.join("\n") + "\n", "utf8");
+	await rename(tempPath, sessionFile);
+
+	await SessionManager.open(sessionFile);
+
+	return { changed, stats, backupPath };
+}
+
+function buildActiveEntries(sm: SessionManager): SessionEntry[] {
+	const allEntries = sm.getEntries();
+	const byId = new Map<string, SessionEntry>();
+	for (const entry of allEntries) {
+		byId.set(entry.id, entry);
+	}
+
+	const leafId = sm.getLeafId();
+	let leaf: SessionEntry | undefined;
+	if (leafId) {
+		leaf = byId.get(leafId);
+	}
+	if (!leaf) {
+		leaf = allEntries[allEntries.length - 1];
+	}
+	if (!leaf) {
+		return [];
+	}
+
+	const path: SessionEntry[] = [];
+	let current: SessionEntry | undefined = leaf;
+	while (current) {
+		path.push(current);
+		current = current.parentId ? byId.get(current.parentId) : undefined;
+	}
+	path.reverse();
+
+	let compaction: SessionEntry & { type: "compaction"; firstKeptEntryId?: string } | undefined;
+	let compactionIdx = -1;
+	for (let i = 0; i < path.length; i++) {
+		const entry = path[i];
+		if (entry.type === "compaction") {
+			compaction = entry as SessionEntry & { type: "compaction"; firstKeptEntryId?: string };
+			compactionIdx = i;
+		}
+	}
+
+	if (!compaction) {
+		return path;
+	}
+
+	const active: SessionEntry[] = [];
+	let foundFirstKept = false;
+	for (let i = 0; i < compactionIdx; i++) {
+		const entry = path[i];
+		if (entry.id === compaction.firstKeptEntryId) {
+			foundFirstKept = true;
+		}
+		if (foundFirstKept) {
+			active.push(entry);
+		}
+	}
+	for (let i = compactionIdx + 1; i < path.length; i++) {
+		active.push(path[i]);
+	}
+
+	return active;
+}
+
+function transformAssistantEntry(
+	entry: SessionMessageEntry,
+	activeIds: Set<string>,
+	lastActiveAssistantId: string | undefined,
+	options: RepairOptions,
+	stats: RepairStats,
+): boolean {
+	let changed = false;
+	const message = entry.message as unknown as Record<string, unknown>;
+	const content = Array.isArray(message.content) ? (message.content as Array<Record<string, unknown>>) : [];
+
+	if (!options.noRelabel) {
+		if (message.provider !== options.target.provider) {
+			message.provider = options.target.provider;
+			changed = true;
+		}
+		if (message.api !== options.target.api) {
+			message.api = options.target.api;
+			changed = true;
+		}
+		if (message.model !== options.target.model) {
+			message.model = options.target.model;
+			changed = true;
+		}
+		if (changed) {
+			stats.relabeled++;
+		}
+	}
+
+	for (const block of content) {
+		if (block.type === "thinking") {
+			if (block.redacted === true) {
+				continue;
+			}
+			if (block.thinkingSignature !== "" && block.thinkingSignature !== undefined) {
+				block.thinkingSignature = "";
+				stats.blanked++;
+				changed = true;
+			}
+		}
+	}
+
+	const isActive = activeIds.has(entry.id);
+	const isLastActiveAssistant = entry.id === lastActiveAssistantId;
+	const hasThinking = content.some((block) => block.type === "thinking");
+
+	if (
+		isActive &&
+		!isLastActiveAssistant &&
+		!options.noUnflatten &&
+		options.allowEmptySignature &&
+		!hasThinking
+	) {
+		const newContent: Array<Record<string, unknown>> = [];
+		let convertedThisTurn = false;
+
+		for (const block of content) {
+			if (block.type === "text" && typeof block.text === "string" && block.text.trim().length > 0) {
+				newContent.push({
+					type: "thinking",
+					thinking: block.text,
+					thinkingSignature: "",
+				});
+				stats.unflattened++;
+				convertedThisTurn = true;
+				changed = true;
+			} else {
+				newContent.push(block);
+			}
+		}
+
+		if (convertedThisTurn) {
+			message.content = newContent;
+			stats.activeAssistantTurns++;
+		}
+	}
+
+	return changed;
+}

package/src/session-find.ts

@@ -0,0 +1,47 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { SessionManager } from "@earendil-works/pi-coding-agent";
+
+export interface SessionFindOptions {
+	query?: string;
+	currentSessionFile?: string;
+}
+
+export interface SessionFindResult {
+	file: string;
+	matchedBy: "current" | "path" | "search";
+}
+
+export async function findSessionFile(options: SessionFindOptions): Promise<SessionFindResult | undefined> {
+	const results = await findSessionFiles(options);
+	return results[0];
+}
+
+export async function findSessionFiles(options: SessionFindOptions): Promise<SessionFindResult[]> {
+	// No query -> current session file
+	if (!options.query) {
+		if (!options.currentSessionFile) {
+			return [];
+		}
+		return [{ file: options.currentSessionFile, matchedBy: "current" }];
+	}
+
+	// Absolute path
+	const resolved = resolve(options.query);
+	if (existsSync(resolved)) {
+		return [{ file: resolved, matchedBy: "path" }];
+	}
+
+	// Search by partial UUID / filename across all sessions
+	const sessions = await SessionManager.listAll();
+	const query = options.query.toLowerCase();
+
+	return sessions
+		.filter((session) => {
+			const file = session.path.toLowerCase();
+			const id = session.id?.toLowerCase() ?? "";
+			const name = session.name?.toLowerCase() ?? "";
+			return file.includes(query) || id.includes(query) || name.includes(query);
+		})
+		.map((session) => ({ file: session.path, matchedBy: "search" as const }));
+}

package/src/target-model.ts

@@ -0,0 +1,133 @@
+import type { Model } from "@earendil-works/pi-ai";
+
+export interface TargetModel {
+	provider: string;
+	api: string;
+	model: string;
+}
+
+export interface CompatibilityResult {
+	compatible: boolean;
+	reason: string;
+}
+
+export function resolveTargetModel(options: {
+	currentModel?: Model<any>;
+	explicit?: { provider?: string; api?: string; model?: string };
+	forceAllowEmptySignature?: boolean;
+}): { target: TargetModel; source: "current" | "explicit"; compat: CompatibilityResult } | undefined {
+	if (options.forceAllowEmptySignature) {
+		const target = resolveTarget(options);
+		if (!target) return undefined;
+		return {
+			target: target.value,
+			source: target.source,
+			compat: {
+				compatible: true,
+				reason: "--allow-empty-signature forced the repair regardless of compat metadata.",
+			},
+		};
+	}
+
+	// Explicit overrides take precedence. If the caller explicitly names a target,
+	// trust them the same way underp.py does: don't gate on registry metadata that
+	// may not exist for custom/proxy providers.
+	if (options.explicit && (options.explicit.provider || options.explicit.api || options.explicit.model)) {
+		const target: TargetModel = {
+			provider: options.explicit.provider ?? options.currentModel?.provider ?? "",
+			api: options.explicit.api ?? options.currentModel?.api ?? "",
+			model: options.explicit.model ?? options.currentModel?.id ?? "",
+		};
+
+		if (!target.provider || !target.api || !target.model) {
+			return undefined;
+		}
+
+		return {
+			target,
+			source: "explicit",
+			compat: checkExplicitCompat(target),
+		};
+	}
+
+	// Fall back to current model, and require registry-confirmed compat since we
+	// have no explicit instruction from the caller.
+	const model = options.currentModel;
+	if (!model) {
+		return undefined;
+	}
+
+	const target: TargetModel = {
+		provider: model.provider,
+		api: model.api,
+		model: model.id,
+	};
+
+	return {
+		target,
+		source: "current",
+		compat: checkModelCompat(model),
+	};
+}
+
+function resolveTarget(options: {
+	currentModel?: Model<any>;
+	explicit?: { provider?: string; api?: string; model?: string };
+}): { value: TargetModel; source: "current" | "explicit" } | undefined {
+	if (options.explicit && (options.explicit.provider || options.explicit.api || options.explicit.model)) {
+		const target: TargetModel = {
+			provider: options.explicit.provider ?? options.currentModel?.provider ?? "",
+			api: options.explicit.api ?? options.currentModel?.api ?? "",
+			model: options.explicit.model ?? options.currentModel?.id ?? "",
+		};
+		if (!target.provider || !target.api || !target.model) return undefined;
+		return { value: target, source: "explicit" };
+	}
+
+	const model = options.currentModel;
+	if (!model) return undefined;
+	return {
+		value: { provider: model.provider, api: model.api, model: model.id },
+		source: "current",
+	};
+}
+
+function checkExplicitCompat(target: TargetModel): CompatibilityResult {
+	// We only know the API string here; empty-signature repair is only defined for
+	// anthropic-messages. Registry compat metadata is not consulted for explicit
+	// targets because custom/proxy providers frequently omit it even when the
+	// backend tolerates empty signatures. Use --no-unflatten to opt out.
+	if (target.api !== "anthropic-messages") {
+		return {
+			compatible: false,
+			reason: `Target API is "${target.api}". The signature/unflatten repair only applies to anthropic-messages models.`,
+		};
+	}
+
+	return {
+		compatible: true,
+		reason: "Target API is anthropic-messages. Explicit target trusted; pass --no-unflatten to skip signature/unflatten repair.",
+	};
+}
+
+function checkModelCompat(model: Model<any>): CompatibilityResult {
+	if (model.api !== "anthropic-messages") {
+		return {
+			compatible: false,
+			reason: `Current model API is "${model.api}". The signature/unflatten repair only applies to anthropic-messages models.`,
+		};
+	}
+
+	const compat = (model.compat ?? {}) as { allowEmptySignature?: boolean };
+	if (compat.allowEmptySignature !== true) {
+		return {
+			compatible: false,
+			reason: `Current model ${model.provider}/${model.id} does not have compat.allowEmptySignature=true. Pass --allow-empty-signature to force the repair anyway.`,
+		};
+	}
+
+	return {
+		compatible: true,
+		reason: `Current model ${model.provider}/${model.id} supports empty thinking signatures.`,
+	};
+}