@xynogen/pix-runtime 0.10.2 → 0.13.0

package/src/exec.ts

@@ -0,0 +1,365 @@
+/**
+ * exec.ts — run a catalogued binary by name, on any OS.
+ *
+ * Every pix package that starts an external program goes through here, so:
+ *   - the binary comes from the one resolver (binary.json → `<agentDir>/bin` →
+ *     known install dirs → PATH), never a bare-name OS lookup;
+ *   - a missing binary is a {@link BinaryMissingError} with an install hint, and
+ *     the async runners download it first when the catalog has a trusted release;
+ *   - Windows `.cmd`/`.bat` shims (npm, npx, pi) run through `cmd.exe` with
+ *     strict quoting, since Node refuses to spawn them without a shell.
+ *
+ * Callers pass the tool's arguments unchanged; this layer never adds a shell
+ * for real executables.
+ */
+
+import {
+	type ChildProcess,
+	type ChildProcessWithoutNullStreams,
+	type SpawnOptions,
+	type SpawnOptionsWithStdioTuple,
+	type SpawnSyncOptions,
+	type StdioNull,
+	type StdioPipe,
+	spawn,
+	spawnSync,
+} from "node:child_process";
+import { join } from "node:path";
+import type { Readable, Writable } from "node:stream";
+import { type EnsureOptions, ensureTool, type ToolStatus } from "./binaries/ensure.ts";
+import { type LookupOptions, type ResolvedTool, requireTool } from "./binaries/resolve.ts";
+import { currentPlatform, type HostPlatform } from "./platform.ts";
+
+// ── Windows shim quoting ────────────────────────────────────────────────────
+// Ported from cross-spawn (MIT): arguments are quoted for the program's
+// CommandLineToArgvW parsing, then cmd.exe metacharacters are caret-escaped.
+// npm-style shims under node_modules/.bin re-parse their arguments, so they get
+// a second round of caret escaping.
+
+const CMD_META = /([()\][%!^"`<>&|;, *?])/g;
+const CMD_SHIM_IN_BIN = /node_modules[\\/]\.bin[\\/][^\\/]+\.cmd$/i;
+
+/** True when `path` is a batch file that needs `cmd.exe` to run. */
+export function isBatchFile(path: string): boolean {
+	return /\.(cmd|bat)$/i.test(path);
+}
+
+/** Quote one argument for a `cmd.exe /d /s /c "…"` line. */
+export function quoteForCmd(arg: string, doubleEscape = false): string {
+	let out = arg.replace(/(\\*)"/g, '$1$1\\"').replace(/(\\*)$/, "$1$1");
+	out = `"${out}"`.replace(CMD_META, "^$1");
+	return doubleEscape ? out.replace(CMD_META, "^$1") : out;
+}
+
+export interface CommandLine {
+	command: string;
+	args: string[];
+	/** Must be passed to spawn so Node does not re-quote the cmd.exe line. */
+	windowsVerbatimArguments?: boolean;
+}
+
+/**
+ * Translate `path args…` into what spawn needs on this host. Real executables
+ * pass through untouched; Windows batch files become one quoted `cmd.exe` line.
+ */
+export function commandLine(
+	path: string,
+	args: readonly string[],
+	host: HostPlatform = currentPlatform(),
+	env: NodeJS.ProcessEnv = process.env,
+): CommandLine {
+	if (host.os !== "win32" || !isBatchFile(path)) return { command: path, args: [...args] };
+	const doubleEscape = CMD_SHIM_IN_BIN.test(path);
+	const line = [
+		path.replace(CMD_META, "^$1"),
+		...args.map((a) => quoteForCmd(a, doubleEscape)),
+	].join(" ");
+	const root = env.SystemRoot ?? env.SYSTEMROOT ?? "C:\\Windows";
+	return {
+		command: env.ComSpec ?? env.COMSPEC ?? join(root, "System32", "cmd.exe"),
+		args: ["/d", "/s", "/c", `"${line}"`],
+		windowsVerbatimArguments: true,
+	};
+}
+
+// ── Runners ─────────────────────────────────────────────────────────────────
+
+export interface ToolExecOptions {
+	cwd?: string;
+	/** Child environment; also where PATH is read for the lookup. Default process.env. */
+	env?: NodeJS.ProcessEnv;
+	/** Kill the child after this many ms (result has `timedOut: true`). */
+	timeoutMs?: number;
+	signal?: AbortSignal;
+	/** Written to stdin, then stdin is closed. */
+	input?: string | Buffer;
+	/** Download progress when the binary is fetched first (async runners only). */
+	onStatus?: (status: ToolStatus) => void;
+	/** Test seam for the host OS. */
+	host?: HostPlatform;
+	/** Cap on captured stdout/stderr bytes each (default 50 MB). */
+	maxBuffer?: number;
+	/** Args are already quoted for the target (cmd.exe `/c` lines); Node must not re-quote. */
+	verbatim?: boolean;
+}
+
+export interface ToolRunResult {
+	/** Exit code, or null when killed by a signal/timeout. */
+	code: number | null;
+	stdout: string;
+	stderr: string;
+	/** Raw stdout for binary output (clipboard images, archives). */
+	stdoutBytes: Buffer;
+	timedOut: boolean;
+	/** Output passed `maxBuffer` and was cut. A zero exit code is then not a complete result. */
+	truncated: boolean;
+	/** The binary that ran and where it was found. */
+	tool: ResolvedTool;
+}
+
+const MAX_BUFFER = 50 * 1024 * 1024;
+/** Time between SIGTERM and SIGKILL, and then before open pipes are dropped. */
+const KILL_GRACE_MS = 1500;
+
+function lookupOpts(opts: ToolExecOptions): LookupOptions {
+	return { env: opts.env, host: opts.host };
+}
+
+/**
+ * Kill a child and its descendants. Windows: `taskkill /T /F` (a cmd.exe wrapper
+ * leaves the shim running otherwise). POSIX: signal the child's process group
+ * (runTool starts it as a group leader), because a descendant that keeps
+ * stdout open would otherwise delay "close" past the timeout.
+ */
+function killTree(
+	child: ChildProcess,
+	host: HostPlatform,
+	env: NodeJS.ProcessEnv,
+	signal: NodeJS.Signals = "SIGTERM",
+): void {
+	if (!child.pid) return;
+	if (host.os === "win32") {
+		if (child.exitCode !== null || child.signalCode !== null) return;
+		const root = env.SystemRoot ?? env.SYSTEMROOT ?? "C:\\Windows";
+		spawnSync(join(root, "System32", "taskkill.exe"), ["/pid", String(child.pid), "/T", "/F"], {
+			stdio: "ignore",
+			windowsHide: true,
+		});
+		return;
+	}
+	// The group can outlive the leader, so do not skip on child exit.
+	try {
+		process.kill(-child.pid, signal);
+	} catch {
+		// ESRCH: the group is gone. EPERM: not a group we own; fall back to the child.
+		if (child.exitCode === null && child.signalCode === null) child.kill(signal);
+	}
+}
+
+type HostOpt = { host?: HostPlatform };
+type Pipe = StdioPipe;
+type Null = StdioNull;
+/** Child whose piped streams are typed non-null, mirroring Node's spawn overloads. */
+type Piped<I, O, E> = ChildProcess & {
+	stdin: I extends Pipe ? Writable : null;
+	stdout: O extends Pipe ? Readable : null;
+	stderr: E extends Pipe ? Readable : null;
+};
+
+/**
+ * Start a resolved binary with Node's spawn options (stdio, detached, …).
+ * Sync lookup, no download; throws {@link BinaryMissingError} when missing.
+ */
+export function spawnTool<I extends Pipe | Null, O extends Pipe | Null, E extends Pipe | Null>(
+	name: string,
+	args: readonly string[],
+	options: SpawnOptionsWithStdioTuple<I, O, E> & HostOpt,
+): Piped<I, O, E>;
+export function spawnTool(
+	name: string,
+	args?: readonly string[],
+	options?: Omit<SpawnOptions, "stdio"> & HostOpt,
+): ChildProcessWithoutNullStreams;
+export function spawnTool(
+	name: string,
+	args: readonly string[],
+	options: SpawnOptions & HostOpt,
+): ChildProcess;
+export function spawnTool(
+	name: string,
+	args: readonly string[] = [],
+	options: SpawnOptions & HostOpt = {},
+): ChildProcess {
+	const { host: hostOpt, ...spawnOpts } = options;
+	const host = hostOpt ?? currentPlatform();
+	const env = spawnOpts.env ?? process.env;
+	const tool = requireTool(name, { env, host });
+	const line = commandLine(tool.path, args, host, env);
+	return spawn(line.command, line.args, {
+		windowsHide: true,
+		...spawnOpts,
+		windowsVerbatimArguments: line.windowsVerbatimArguments ?? spawnOpts.windowsVerbatimArguments,
+	});
+}
+
+/** Run a resolved child to completion, collecting output. */
+function collect(
+	child: ChildProcess,
+	tool: ResolvedTool,
+	opts: ToolExecOptions,
+	host: HostPlatform,
+) {
+	const env = opts.env ?? process.env;
+	const cap = opts.maxBuffer ?? MAX_BUFFER;
+	return new Promise<ToolRunResult>((resolve, reject) => {
+		const out: Buffer[] = [];
+		const err: Buffer[] = [];
+		let outLen = 0;
+		let errLen = 0;
+		let timedOut = false;
+		let truncated = false;
+		const push = (list: Buffer[], chunk: Buffer, len: number): number => {
+			const room = cap - len;
+			if (chunk.length > room) truncated = true;
+			if (room <= 0) return len;
+			list.push(chunk.length > room ? chunk.subarray(0, room) : chunk);
+			return len + Math.min(chunk.length, room);
+		};
+		child.stdout?.on("data", (c: Buffer) => {
+			outLen = push(out, c, outLen);
+		});
+		child.stderr?.on("data", (c: Buffer) => {
+			errLen = push(err, c, errLen);
+		});
+		const escalation: NodeJS.Timeout[] = [];
+		const stop = () => {
+			if (escalation.length > 0) return;
+			killTree(child, host, env);
+			// A child may ignore SIGTERM. A descendant may leave the group and keep a
+			// pipe open. Both would hold "close" forever, so escalate, then drop pipes.
+			escalation.push(
+				setTimeout(() => killTree(child, host, env, "SIGKILL"), KILL_GRACE_MS),
+				setTimeout(() => {
+					child.stdout?.destroy();
+					child.stderr?.destroy();
+				}, KILL_GRACE_MS * 2),
+			);
+		};
+		const timer =
+			opts.timeoutMs && opts.timeoutMs > 0
+				? setTimeout(() => {
+						timedOut = true;
+						stop();
+					}, opts.timeoutMs)
+				: undefined;
+		opts.signal?.addEventListener("abort", stop, { once: true });
+		const done = () => {
+			if (timer) clearTimeout(timer);
+			for (const t of escalation) clearTimeout(t);
+			opts.signal?.removeEventListener("abort", stop);
+		};
+		child.on("error", (e) => {
+			done();
+			reject(e);
+		});
+		child.on("close", (code) => {
+			done();
+			const stdoutBytes = Buffer.concat(out);
+			resolve({
+				code: timedOut ? null : code,
+				stdout: stdoutBytes.toString("utf-8"),
+				stderr: Buffer.concat(err).toString("utf-8"),
+				stdoutBytes,
+				timedOut,
+				truncated,
+				tool,
+			});
+		});
+		// A child may exit without reading stdin (EPIPE). With no listener that is an
+		// uncaught stream error that kills the host. The exit code still reports the
+		// outcome. Other stdin errors come back through child "error" or "close".
+		child.stdin?.on("error", () => {});
+		if (opts.input !== undefined) child.stdin?.end(opts.input);
+		else child.stdin?.end();
+	});
+}
+
+/**
+ * Run `name args…` and capture its output. Downloads the binary first when it
+ * is missing and the catalog has a release for this host (progress via
+ * `onStatus`). Rejects with {@link BinaryMissingError} when it cannot be found.
+ * A non-zero exit resolves normally — check `code`.
+ */
+export async function runTool(
+	name: string,
+	args: readonly string[],
+	opts: ToolExecOptions = {},
+): Promise<ToolRunResult> {
+	const host = opts.host ?? currentPlatform();
+	const ensure: EnsureOptions = {
+		env: opts.env,
+		host,
+		onStatus: opts.onStatus,
+		signal: opts.signal,
+	};
+	const tool = await ensureTool(name, ensure);
+	if (opts.signal?.aborted) throw opts.signal.reason ?? new Error("aborted");
+	const env = opts.env ?? process.env;
+	const line = opts.verbatim
+		? { command: tool.path, args: [...args], windowsVerbatimArguments: true }
+		: commandLine(tool.path, args, host, env);
+	const child = spawn(line.command, line.args, {
+		cwd: opts.cwd,
+		env,
+		stdio: ["pipe", "pipe", "pipe"],
+		// POSIX: own process group, so killTree reaches descendants. On Windows
+		// `detached` opens a new console, and taskkill /T covers the tree.
+		// ponytail: the group also has no controlling terminal, so a tool cannot
+		// prompt on /dev/tty. runTool is for captured, non-interactive runs.
+		// Interactive tools use spawnTool.
+		detached: host.os !== "win32",
+		windowsHide: true,
+		windowsVerbatimArguments: line.windowsVerbatimArguments,
+	});
+	return collect(child, tool, opts, host);
+}
+
+/**
+ * Blocking {@link runTool} for startup probes and sync call sites. Never
+ * downloads; throws {@link BinaryMissingError} when missing.
+ */
+export function runToolSync(
+	name: string,
+	args: readonly string[],
+	opts: Omit<ToolExecOptions, "signal" | "onStatus"> = {},
+): ToolRunResult {
+	const host = opts.host ?? currentPlatform();
+	const env = opts.env ?? process.env;
+	const tool = requireTool(name, lookupOpts({ ...opts, host }));
+	const line = commandLine(tool.path, args, host, env);
+	const sync: SpawnSyncOptions = {
+		cwd: opts.cwd,
+		env,
+		input: opts.input,
+		timeout: opts.timeoutMs,
+		maxBuffer: opts.maxBuffer ?? MAX_BUFFER,
+		windowsHide: true,
+		windowsVerbatimArguments: line.windowsVerbatimArguments,
+	};
+	const r = spawnSync(line.command, line.args, sync);
+	// Over maxBuffer, spawnSync kills the child and sets ENOBUFS. That throws below,
+	// so a sync result is never truncated.
+	if (r.error && (r.error as NodeJS.ErrnoException).code !== "ETIMEDOUT") throw r.error;
+	const stdoutBytes = Buffer.isBuffer(r.stdout) ? r.stdout : Buffer.from(r.stdout ?? "");
+	const stderr = Buffer.isBuffer(r.stderr) ? r.stderr.toString("utf-8") : String(r.stderr ?? "");
+	const timedOut = (r.error as NodeJS.ErrnoException | undefined)?.code === "ETIMEDOUT";
+	return {
+		code: timedOut ? null : r.status,
+		stdout: stdoutBytes.toString("utf-8"),
+		stderr,
+		stdoutBytes,
+		timedOut,
+		truncated: false,
+		tool,
+	};
+}

package/src/extension.ts

@@ -1,9 +1,16 @@
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+	type BashOperations,
+	createLocalBashOperations,
+	createLocalPowerShellOperations,
+	type ExtensionAPI,
+} from "@earendil-works/pi-coding-agent";
+import { syncBinaryStore } from "./binaries/store.ts";
 import { bindHerdrNotify } from "./herdr-notify.ts";
 import { bindAgentStateEvents, resetAgentState, resetUnattendedState } from "./herdr-state.ts";
 import { once } from "./once.ts";
 import { registerPixCommand } from "./pix-command.ts";
 import { pixRuntime } from "./runtime.ts";
+import { userShell } from "./user-shell.ts";
 
 /**
  * Runtime extension entry. Idempotent per `pi` instance: registers `/pix` and
@@ -21,16 +28,38 @@ export default function registerRuntime(pi: ExtensionAPI): void {
 		const unbindAgentState = bindAgentStateEvents(pi.events);
 		const unbindHerdrNotify = bindHerdrNotify(pi.events);
 
+		// User `!` commands: PowerShell on Windows, $SHELL on POSIX (zsh gets rc + aliases).
+		const shell = userShell();
+		// Older Pi has no PowerShell backend. Keep Pi's default shell then.
+		const inner =
+			shell?.kind === "powershell"
+				? createLocalPowerShellOperations?.()
+				: shell && createLocalBashOperations({ shellPath: shell.shellPath });
+		if (shell && inner) {
+			const operations: BashOperations = {
+				exec: (command, cwd, options) => inner.exec(shell.wrap(command), cwd, options),
+			};
+			pi.on("user_bash", () => ({ operations }));
+		}
+
 		let initialized = false;
 		pi.on("session_start", async () => {
 			resetUnattendedState(pi.events);
 			if (initialized) {
 				await runtime.reload({ origin: "reload", source: "session_start" });
 			} else {
-				initialized = true;
 				await runtime.init({ origin: "init", source: "session_start" });
+				// Set only on success: a failed init retries init (with migrations) next session.
+				initialized = true;
 			}
 			surfaceDiagnostics(pi, runtime);
+			// binary.json holds overrides only; drop legacy `null` padding, report bad JSON.
+			try {
+				const store = syncBinaryStore();
+				if (store.error) notifyWarning(pi, `pix: ${store.path} is invalid (${store.error})`);
+			} catch {
+				/* read-only agent dir: the Binaries tab still resolves without the file */
+			}
 		});
 
 		pi.on("session_shutdown", async () => {
@@ -47,7 +76,10 @@ export default function registerRuntime(pi: ExtensionAPI): void {
 function surfaceDiagnostics(pi: ExtensionAPI, runtime: ReturnType<typeof pixRuntime>): void {
 	const errors = runtime.diagnostics().filter((d) => d.severity === "error");
 	if (errors.length === 0) return;
+	notifyWarning(pi, `pix config: ${errors.length} issue(s) — see ${runtime.path}`);
+}
+
+function notifyWarning(pi: ExtensionAPI, msg: string): void {
 	const ui = (pi as unknown as { ui?: { notify?(m: string, t?: string): void } }).ui;
-	const msg = `pix config: ${errors.length} issue(s) — see ${runtime.path}`;
 	ui?.notify?.(msg, "warning");
 }

package/src/hashline.check.mjs

@@ -0,0 +1,11 @@
+import assert from "node:assert/strict";
+import xxhash from "xxhash-wasm";
+
+const { h32, h32Raw } = await xxhash();
+// Official xxHash v0.8.3 tests/sanity_test_vectors.h, empty-input vectors.
+assert.equal(h32("", 0), 0x02cc5d05);
+assert.equal(h32("", 0x9e3779b1), 0x36b78ae7);
+for (const text of ["", "hello", "中文🙂", " a ", "\tconst x = 1;  "]) {
+	assert.equal(h32(text, 0), h32Raw(new TextEncoder().encode(text), 0));
+	console.log(`${(h32(text, 0) & 0xfff).toString(16).toUpperCase().padStart(3, "0")}|${text}`);
+}

package/src/hashline.ts

@@ -0,0 +1,71 @@
+import xxhash from "xxhash-wasm";
+
+// Pi reevaluates shared modules with Jiti. Both tools must share one WASM instance.
+const global = globalThis as typeof globalThis & {
+	__pixHashline?: {
+		initialization?: Promise<void>;
+		h32?: (input: string, seed?: number) => number;
+	};
+};
+const state = global.__pixHashline ?? {};
+global.__pixHashline = state;
+
+export function initHashline(): Promise<void> {
+	state.initialization ??= xxhash()
+		.then((hash) => {
+			state.h32 = hash.h32;
+		})
+		.catch((error) => {
+			throw new Error("Hashline WASM initialization failed", { cause: error });
+		});
+	return state.initialization;
+}
+
+export function hashLine(text: string): string {
+	if (!state.h32) throw new Error("Hashline WASM is not initialized");
+	return (state.h32(text, 0) & 0xfff).toString(16).toUpperCase().padStart(3, "0");
+}
+
+export function anchor(line: number, text: string): string {
+	return `${line}#${hashLine(text)}`;
+}
+
+export function parseAnchor(value: unknown): { line: number; hash: string } {
+	const match = typeof value === "string" ? /^([1-9]\d*)#([0-9A-F]{3})$/.exec(value) : null;
+	if (!match || !Number.isSafeInteger(Number(match[1])))
+		throw new Error(`Invalid anchor: ${String(value)}`);
+	return { line: Number(match[1]), hash: match[2]! };
+}
+
+export type SourceLine = { text: string; ending: string };
+
+export function decodeLines(bytes: Uint8Array): {
+	bom: string;
+	lines: SourceLine[];
+	delimiter: string;
+	finalNewline: boolean;
+} {
+	const decoded = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+	if (decoded.includes("\0")) throw new Error("Unsupported binary text: NUL byte");
+	const bom = decoded.startsWith("\uFEFF") ? "\uFEFF" : "";
+	const text = decoded.slice(bom.length);
+	const lines: SourceLine[] = [];
+	const counts = new Map<string, number>();
+	let start = 0;
+	for (const match of text.matchAll(/\r\n|\r|\n/g)) {
+		const ending = match[0];
+		lines.push({ text: text.slice(start, match.index), ending });
+		counts.set(ending, (counts.get(ending) ?? 0) + 1);
+		start = match.index + ending.length;
+	}
+	if (start < text.length) lines.push({ text: text.slice(start), ending: "" });
+	let delimiter = "\n";
+	let highest = 0;
+	for (const [ending, count] of counts) {
+		if (count > highest) {
+			delimiter = ending;
+			highest = count;
+		}
+	}
+	return { bom, lines, delimiter, finalNewline: lines.length > 0 && lines.at(-1)!.ending !== "" };
+}

package/src/icon-catalog.ts

@@ -99,6 +99,7 @@ const CATALOG = {
 	// ── paste chips (pix-display) ─────────────────────────────────────────
 	"paste.image": { nerd: "\u{F02E9}", unicode: `\u25A3${VS}`, ascii: "img" },
 	"paste.text": { nerd: "\u{F027F}", unicode: `\u25A4${VS}`, ascii: "txt" },
+	"paste.prompt": { nerd: "\u{F0D0}", unicode: `\u2726${VS}`, ascii: "pr" },
 
 	// ── model picker (pix-models) ─────────────────────────────────────────
 	"picker.model": { nerd: "\u{F0229}", unicode: `\u25C8${VS}`, ascii: "M" },

package/src/migrations.ts

@@ -106,7 +106,31 @@ export function importOptimizerSidecar(
 	agentDir: string,
 	ctx: ParseContext,
 ): { changed: boolean; archive?: () => void } {
-	const sidecarPath = join(agentDir, "optimizer.json");
+	const imports = ["optimizer", "voice", "fetch", "search", "toolbox"];
+	let changed = false;
+	const archives: (() => void)[] = [];
+	for (const section of imports) {
+		const result = importSidecar(doc, agentDir, ctx, section);
+		changed ||= result.changed;
+		if (result.archive) archives.push(result.archive);
+	}
+	return {
+		changed,
+		archive: archives.length
+			? () => {
+					for (const archive of archives) archive();
+				}
+			: undefined,
+	};
+}
+
+function importSidecar(
+	doc: RawDocument,
+	agentDir: string,
+	ctx: ParseContext,
+	section: string,
+): { changed: boolean; archive?: () => void } {
+	const sidecarPath = join(agentDir, `${section}.json`);
 	if (!existsSync(sidecarPath)) return { changed: false };
 
 	let raw: Record<string, unknown>;
@@ -118,32 +142,39 @@ export function importOptimizerSidecar(
 		ctx.diagnostic({
 			code: "MIGRATION_FAILED",
 			severity: "warning",
-			path: "optimizer.json",
-			message: "malformed optimizer sidecar left untouched",
+			path: `${section}.json`,
+			message: `malformed ${section} config left unchanged`,
 			cause: err,
 		});
 		return { changed: false };
 	}
 
-	const existing = isObj(doc.optimizer) ? { ...doc.optimizer } : {};
+	const existing = isObj(doc[section]) ? { ...doc[section] } : {};
 	let changed = false;
-	for (const key of OPTIMIZER_KEYS) {
+	for (const key of section === "optimizer" ? OPTIMIZER_KEYS : Object.keys(raw)) {
 		const value = raw[key];
-		if (typeof value === "string" && !(key in existing)) {
+		if ((section !== "optimizer" || typeof value === "string") && !(key in existing)) {
 			existing[key] = value;
 			changed = true;
 		}
 	}
-	if (changed) doc.optimizer = existing;
+	if (changed) doc[section] = existing;
 
-	const hasLegacyToon = typeof raw.toon === "string";
+	const hasLegacyToon = section === "optimizer" && typeof raw.toon === "string";
 	const archive = () => {
 		let target = `${sidecarPath}.migrated-v1`;
 		if (existsSync(target)) target = `${target}.${Date.now()}`;
 		try {
 			renameSync(sidecarPath, target);
-		} catch {
-			// A competing process may have moved it — ENOENT is benign.
+		} catch (err) {
+			if ((err as NodeJS.ErrnoException).code !== "ENOENT")
+				ctx.diagnostic({
+					code: "MIGRATION_FAILED",
+					severity: "warning",
+					path: sidecarPath,
+					message: "config backup failed; original file remains",
+					cause: err,
+				});
 		}
 	};