@pi-archimedes/subagent 1.8.1 → 1.8.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-archimedes/subagent",
-  "version": "1.8.1",
+  "version": "1.8.3",
   "type": "module",
   "keywords": [
     "pi-package"
@@ -11,7 +11,7 @@
   ],
   "main": "./src/index.ts",
   "dependencies": {
-    "@pi-archimedes/core": "1.8.1"
+    "@pi-archimedes/core": "1.8.3"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": ">=0.1.0",

package/src/agent-manager.ts

@@ -14,6 +14,13 @@ import {
 import type { AgentConfig } from "./agents.js";
 import { discoverAgentsAll } from "./agents.js";
 import { serializeAgent, validateAgentName } from "./frontmatter-io.js";
+import {
+  writeLocalModel,
+  deleteLocalModel,
+  readLocalConfig,
+  setLocalConfig,
+  type LocalConfig,
+} from "./local-config.js";
 
 // ── Screen constants ────────────────────────────────────────────────────────
 
@@ -1204,7 +1211,7 @@ function setFieldValue(agent: AgentConfig, field: EditField, value: string): voi
 
 // ── Save logic ──────────────────────────────────────────────────────────────
 
-function saveAgent(state: ManagerState, requestRender: () => void): void {
+export function saveAgent(state: ManagerState, requestRender: () => void): void {
   if (!state.editAgent) return;
 
   const agent = state.editAgent;
@@ -1241,18 +1248,77 @@ function saveAgent(state: ManagerState, requestRender: () => void): void {
   const newName = agent.name.endsWith(".md") ? agent.name : `${agent.name}.md`;
   const newPath = path.join(dir, newName);
 
+  // Capture model before entering the try block so it is available in the
+  // catch block for .md rollback if a later step (JSON write, etc.) fails.
+  const model = agent.model;
+
+  // Track whether the .md write succeeded so the catch block knows whether
+  // to restore or clean up the on-disk file.
+  const isRename = oldPath && oldPath !== newPath;
+  let originalContent: string | undefined;
+  if (!isRename && fs.existsSync(newPath)) {
+    // Read existing .md content so we can restore it verbatim if a later
+    // step (JSON write, re-discovery, etc.) fails.
+    originalContent = fs.readFileSync(newPath, "utf-8");
+  }
+  let mdWritten = false;
+  // Track whether the old .md file was already removed during a rename so
+  // the catch block knows whether newPath is the sole surviving copy.
+  let oldPathDeleted = false;
+  // Track whether the JSON config write succeeded so the catch block can
+  // roll it back if a later step (re-discovery, etc.) fails.
+  let jsonWritten = false;
+  // Snapshot of the JSON config captured before the write so the catch
+  // block can restore it. Declared here (not inside try) so it is
+  // accessible in the catch block.
+  let jsonConfigBefore: LocalConfig = {};
+
   try {
     // Ensure directory exists
     fs.mkdirSync(dir, { recursive: true });
 
-    // Serialize and write
-    const content = serializeAgent(agent);
+    // Build a shallow copy without the model for .md serialization so the
+    // live edit object is NOT mutated during serialization. If the .md
+    // write fails below, the live object stays intact for a retry.
+    const mdAgent = { ...agent };
+    delete mdAgent.model;
+
+    // Serialize and write the .md file FIRST. If this fails, no JSON state
+    // is persisted and the live edit object is untouched.
+    const content = serializeAgent(mdAgent);
     fs.writeFileSync(newPath, content, "utf-8");
+    mdWritten = true;
+
+    // Only after the .md write succeeds, perform JSON store mutations.
+    // Capture a backup of the current JSON config so we can roll it back
+    // if a later step (re-discovery, etc.) fails after this write succeeds.
+    jsonConfigBefore = readLocalConfig();
+    // Write/remove the NEW name entry first, then clean up the OLD name.
+    if (model !== undefined) {
+      writeLocalModel(agent.name, model);
+    } else {
+      deleteLocalModel(agent.name);
+    }
+    jsonWritten = true;
+
+    // Handle rename: delete old JSON entry keyed by original name (after
+    // the new entry is safely written). Wrapped in try-catch so a failure
+    // here does not leave the .md written but the live object un-stripped.
+    const originalName = state.editOriginal?.name;
+    if (originalName && originalName !== agent.name) {
+      try {
+        deleteLocalModel(originalName);
+      } catch {
+        // Best-effort: stale entry is harmless and will be cleaned up on
+        // a subsequent save/rename
+      }
+    }
 
-    // Handle rename if name changed
+    // Handle rename: delete old .md file if name changed
     if (oldPath && oldPath !== newPath) {
       try {
         fs.unlinkSync(oldPath);
+        oldPathDeleted = true;
       } catch {
         // Old file may not exist (e.g., new agent)
       }
@@ -1281,7 +1347,52 @@ function saveAgent(state: ManagerState, requestRender: () => void): void {
     state.editDirty = false;
     state.editError = null;
     requestRender();
+
+    // Only strip model from the live edit object AFTER all operations
+    // (including re-discovery) have succeeded. This ensures that if any
+    // step fails, the catch block can restore the model to .md and the
+    // live object retains it for a safe retry.
+    delete agent.model;
   } catch (err) {
+    // Restore prior .md state if the write succeeded but a later step
+    // (JSON write, re-discovery, etc.) failed:
+    //   - rename (old file not yet unlinked): check whether the old file
+    //     still exists. If so, delete newPath so only the original remains.
+    //     If the old file is gone (deleted externally or by a prior attempt),
+    //     newPath may be the sole copy — keep it with a model fallback, or
+    //     delete it when there is no model to fall back on.
+    //   - existing file: write the original content back verbatim.
+    //   - new file with a model: keep a frontmatter fallback so the model
+    //     override survives for the next retry.
+    // If the old .md was already unlinked during rename (oldPathDeleted),
+    // newPath is the sole surviving copy — leave it in place.
+    // If the .md write itself failed (mdWritten is false) there is nothing
+    // to restore on disk.
+    if (mdWritten) {
+      if (isRename && !oldPathDeleted) {
+        if (oldPath && fs.existsSync(oldPath)) {
+          // Old file still exists — safe to delete newPath and restore prior state
+          try { fs.unlinkSync(newPath); } catch { /* best-effort */ }
+        } else if (model !== undefined) {
+          // Old file is gone — keep newPath with model as fallback
+          try { fs.writeFileSync(newPath, serializeAgent({ ...agent, model }), "utf-8"); } catch { /* best-effort */ }
+        } else {
+          // Old file is gone and no model — delete newPath (no prior state to restore)
+          try { fs.unlinkSync(newPath); } catch { /* best-effort */ }
+        }
+      } else if (originalContent !== undefined) {
+        try { fs.writeFileSync(newPath, originalContent, "utf-8"); } catch { /* best-effort */ }
+      } else if (model !== undefined) {
+        try { fs.writeFileSync(newPath, serializeAgent({ ...agent, model }), "utf-8"); } catch { /* best-effort */ }
+      } else {
+        // New file without model — delete it (no prior state to restore)
+        try { fs.unlinkSync(newPath); } catch { /* best-effort */ }
+      }
+    }
+    // Roll back JSON if it was written but a later step failed
+    if (jsonWritten) {
+      try { setLocalConfig(jsonConfigBefore); } catch { /* best-effort */ }
+    }
     state.editError = err instanceof Error ? err.message : "Failed to save agent";
     requestRender();
   }

package/src/agents.test.ts

@@ -0,0 +1,109 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import type { AgentConfig } from "./agents.js";
+import { applyLocalOverrides, formatAgentList } from "./agents.js";
+
+// Redirect getAgentDir() to a temp directory via PI_CODING_AGENT_DIR.
+// This must happen before any function calls so readLocalConfig()
+// resolves agents.local.json to our sandbox directory.
+const testDir = join(tmpdir(), "pi-test-local-config-agents");
+process.env.PI_CODING_AGENT_DIR = testDir;
+
+function makeAgent(
+  name: string,
+  model?: string,
+): AgentConfig {
+  return {
+    name,
+    description: `Agent ${name}`,
+    systemPrompt: "hello",
+    source: "global" as const,
+    filePath: join(testDir, `${name}.md`),
+    ...(model !== undefined ? { model } : {}),
+  };
+}
+
+describe("applyLocalOverrides", () => {
+  beforeEach(() => {
+    mkdirSync(testDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    rmSync(testDir, { recursive: true, force: true });
+  });
+
+  it("sets model from JSON override", () => {
+    const path = join(testDir, "agents.local.json");
+    writeFileSync(path, JSON.stringify({ codex: { model: "o1" } }), "utf-8");
+
+    const agent = makeAgent("codex");
+    applyLocalOverrides([agent]);
+    expect(agent.model).toBe("o1");
+  });
+
+  it("leaves model unchanged when no JSON entry exists", () => {
+    const agent = makeAgent("codex", "M1");
+    applyLocalOverrides([agent]);
+    expect(agent.model).toBe("M1");
+  });
+
+  it("leaves model unchanged when JSON entry has no model field", () => {
+    const path = join(testDir, "agents.local.json");
+    writeFileSync(path, JSON.stringify({ codex: {} }), "utf-8");
+
+    const agent = makeAgent("codex", "M1");
+    applyLocalOverrides([agent]);
+    expect(agent.model).toBe("M1");
+  });
+
+  it("handles empty agent list", () => {
+    expect(() => applyLocalOverrides([])).not.toThrow();
+  });
+
+  it("works with corrupt JSON file (agent model stays unchanged)", () => {
+    const path = join(testDir, "agents.local.json");
+    writeFileSync(path, "{ broken json", "utf-8");
+
+    const agent = makeAgent("codex", "M1");
+    applyLocalOverrides([agent]);
+    expect(agent.model).toBe("M1");
+  });
+});
+
+function mkAgent(overrides: Partial<AgentConfig> & Pick<AgentConfig, "name">): AgentConfig {
+  return {
+    name: overrides.name,
+    description: overrides.description ?? "desc",
+    systemPrompt: overrides.systemPrompt ?? "prompt",
+    source: overrides.source ?? "user",
+    filePath: overrides.filePath ?? "/x.md",
+    ...(overrides.model !== undefined ? { model: overrides.model } : {}),
+    ...(overrides.tools !== undefined ? { tools: overrides.tools } : {}),
+  };
+}
+
+describe("formatAgentList", () => {
+  it("reports no agents when empty", () => {
+    expect(formatAgentList([])).toContain("No agents configured");
+  });
+
+  it("formats a single agent (singular)", () => {
+    const out = formatAgentList([mkAgent({ name: "general" })]);
+    expect(out).toContain("1 agent:");
+    expect(out).toContain("• general [user] — desc");
+  });
+
+  it("formats multiple agents (plural)", () => {
+    const out = formatAgentList([mkAgent({ name: "general" }), mkAgent({ name: "explore" })]);
+    expect(out).toContain("2 agents:");
+  });
+
+  it("includes model and tools overrides only when set", () => {
+    const withExtras = formatAgentList([mkAgent({ name: "reviewer", model: "anthropic/claude-sonnet-4-5", tools: ["read", "bash"] })]);
+    expect(withExtras).toContain("(model: anthropic/claude-sonnet-4-5, 2 tools)");
+    const withoutExtras = formatAgentList([mkAgent({ name: "general" })]);
+    expect(withoutExtras).not.toMatch(/\(model:|tools\)/);
+  });
+});

package/src/agents.ts

@@ -7,6 +7,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
+import { readLocalConfig } from "./local-config.js";
 
 export interface AgentConfig {
   name: string;
@@ -136,6 +137,20 @@ export interface AgentsDiscoveryResult {
   projectDir: string | null; // e.g., .pi/agents or null if not found
 }
 
+/**
+ * Apply local model overrides from agents.local.json to a list of agents.
+ * Reads the config once and mutates matching agents in place.
+ */
+export function applyLocalOverrides(agents: AgentConfig[]): void {
+  const config = readLocalConfig();
+  for (const agent of agents) {
+    const local = config[agent.name];
+    if (local?.model !== undefined) {
+      agent.model = local.model;
+    }
+  }
+}
+
 /**
  * Discover all available agents from global, user and/or project directories.
  * Precedence (highest last): global < user < project
@@ -155,7 +170,9 @@ export function discoverAgents(cwd: string): AgentConfig[] {
   for (const agent of userAgents) agentMap.set(agent.name, agent);
   for (const agent of projectAgents) agentMap.set(agent.name, agent);
 
-  return Array.from(agentMap.values());
+  const all = Array.from(agentMap.values());
+  applyLocalOverrides(all);
+  return all;
 }
 
 /**
@@ -170,6 +187,10 @@ export function discoverAgentsAll(cwd: string): AgentsDiscoveryResult {
   const userAgents = loadAgentsFromDir(userDir, "user");
   const projectAgents = projectDir ? loadAgentsFromDir(projectDir, "project") : [];
 
+  applyLocalOverrides(globalAgents);
+  applyLocalOverrides(userAgents);
+  applyLocalOverrides(projectAgents);
+
   return {
     global: globalAgents,
     user: userAgents,
@@ -186,3 +207,23 @@ export function discoverAgentsAll(cwd: string): AgentsDiscoveryResult {
 export function findAgent(agents: AgentConfig[], name: string): AgentConfig | undefined {
   return agents.find((a) => a.name === name);
 }
+
+/**
+ * Format discovered agents as a compact, readable listing for the `list_agents`
+ * tool. Standard detail: name, source, description, and model/tools overrides
+ * only when set.
+ */
+export function formatAgentList(agents: AgentConfig[]): string {
+  if (agents.length === 0) {
+    return "No agents configured. Create one in ~/.pi/agent/agents/ or .agents/agents/.";
+  }
+  const lines = agents.map((a) => {
+    let line = `• ${a.name} [${a.source}] — ${a.description}`;
+    const extras: string[] = [];
+    if (a.model) extras.push(`model: ${a.model}`);
+    if (a.tools && a.tools.length > 0) extras.push(`${a.tools.length} tools`);
+    if (extras.length > 0) line += ` (${extras.join(", ")})`;
+    return line;
+  });
+  return `${agents.length} agent${agents.length === 1 ? "" : "s"}:\n${lines.join("\n")}`;
+}

package/src/index.ts

@@ -3,7 +3,8 @@ import { Text, TUI } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 // execute.js + agent-manager.js lazy-loaded below to keep subagent tool registration fast
 import { renderSubagentResult } from "./render.js";
-import { discoverAgents, discoverAgentsAll, findAgent } from "./agents.js";
+import { discoverAgents, discoverAgentsAll, findAgent, formatAgentList } from "./agents.js";
+import { validateModel, firstError } from "./model-validation.js";
 import type {
   SubagentDetails,
   SubagentProgress,
@@ -14,7 +15,9 @@ import type {
 // ── JSON Schema for tool parameters (TypeBox) ──────────────────────────────
 
 const TaskItem = Type.Object({
-  agent: Type.Optional(Type.String()),
+  agent: Type.Optional(Type.String({
+    description: "Agent name for this task (optional). If omitted, runs config-less.",
+  })),
   task: Type.String(),
   model: Type.Optional(Type.String()),
   cwd: Type.Optional(Type.String()),
@@ -22,7 +25,7 @@ const TaskItem = Type.Object({
 
 const SUBAGENT_PARAMS_SCHEMA = Type.Object({
   agent: Type.Optional(Type.String({
-    description: "Agent name/identifier (optional, defaults to 'general')",
+    description: "Agent name (optional). If omitted, the subagent runs config-less — parent's current model, all tools, no system-prompt override. Call list_agents to see available agents.",
   })),
   task: Type.Optional(Type.String({
     description: "Task description for the subagent. Required when not using 'tasks' array.",
@@ -55,7 +58,7 @@ export function registerSubagent(pi: ExtensionAPI): void {
     name: "subagent",
     label: "Subagent",
     description:
-      "Delegate tasks to subagents. Provide either 'task' (single) or 'tasks' (parallel). Never omit both. Options: agent, model, cwd.",
+      "Delegate tasks to subagents. Provide either 'task' (single) or 'tasks' (parallel). Agent is optional — omit for a config-less run with the parent's model and all tools. Model override is rarely needed; the agent config or parent model is used by default.",
     parameters: SUBAGENT_PARAMS_SCHEMA,
 
     async execute(
@@ -78,12 +81,34 @@ export function registerSubagent(pi: ExtensionAPI): void {
 
       // Parallel mode
       if (params.tasks && params.tasks.length > 0) {
-        const missingAgents = params.tasks.filter((t) => t.agent && !findAgent(agents, t.agent));
-        if (missingAgents.length > 0) {
+        // Combined pre-spawn checks for parallel mode: unknown agents + invalid
+        // models. If ANY task is invalid, abort the whole batch with a single
+        // tool result listing all errors (no tasks spawn).
+        const errors: string[] = [];
+        const unknownAgents = params.tasks
+          .filter((t) => t.agent && !findAgent(agents, t.agent!))
+          .map((t) => `"${t.agent}"`);
+        if (unknownAgents.length > 0) {
           const available = agents.map((a) => a.name).join(", ") || "none";
-          const unknown = missingAgents.map((t) => `"${t.agent}"`).join(", ");
+          errors.push(`Unknown agent(s): ${unknownAgents.join(", ")}. Available: ${available}. Call list_agents for details.`);
+        }
+        const unknownAgentSet = new Set(unknownAgents.map((n) => n.replace(/"/g, '')));
+        for (const t of params.tasks) {
+          // Skip model validation for tasks already caught by unknown-agent check
+          if (t.agent && unknownAgentSet.has(t.agent)) continue;
+          const taskAgentConfig = t.agent ? findAgent(agents, t.agent) : undefined;
+          const me = firstError(
+            validateModel(t.model, ctx.modelRegistry, { agentName: t.agent }),
+            validateModel(taskAgentConfig?.model, ctx.modelRegistry, {
+              agentName: t.agent,
+              agentFilePath: taskAgentConfig?.filePath,
+            }),
+          );
+          if (me) errors.push(me);
+        }
+        if (errors.length > 0) {
           return {
-            content: [{ type: "text", text: `Unknown agent(s): ${unknown}. Available: ${available}` }],
+            content: [{ type: "text", text: errors.join("\n") }],
             details: {
               mode: "parallel",
               results: [],
@@ -134,7 +159,7 @@ export function registerSubagent(pi: ExtensionAPI): void {
         if (params.agent && !agentConfig) {
           const available = agents.map((a) => a.name).join(", ") || "none";
           return {
-            content: [{ type: "text", text: `Unknown agent: "${params.agent}". Available: ${available}` }],
+            content: [{ type: "text", text: `Unknown agent: "${params.agent}". Available: ${available}. Call list_agents for details.` }],
             details: {
               mode: "single",
               results: [],
@@ -143,6 +168,22 @@ export function registerSubagent(pi: ExtensionAPI): void {
             isError: true,
           };
         }
+        // Pre-spawn model validation (P2): fail fast with a friendly error
+        // instead of spawning a child that will crash on a bogus --model.
+        const modelError = firstError(
+          validateModel(params.model, ctx.modelRegistry, { agentName: params.agent }),
+          validateModel(agentConfig?.model, ctx.modelRegistry, {
+            agentName: params.agent,
+            agentFilePath: agentConfig?.filePath,
+          }),
+        );
+        if (modelError) {
+          return {
+            content: [{ type: "text", text: modelError }],
+            details: { mode: "single", results: [], progress: undefined },
+            isError: true,
+          };
+        }
         const result: SubagentResult = await executeSubagent({
           agent: params.agent ?? undefined,
           agentConfig,
@@ -234,10 +275,29 @@ export function registerSubagent(pi: ExtensionAPI): void {
       }
     },
   });
+
+  registerListAgentsTool(pi);
 }
 
 // ── Helpers ─────────────────────────────────────────────────────────────────
 
+export function registerListAgentsTool(pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: "list_agents",
+    label: "Agents",
+    description:
+      "List available subagent configurations (name, description, source, model/tools overrides). Call before dispatching if unsure which agents exist or which fits the task.",
+    parameters: Type.Object({}),
+    async execute(_id, _params, _signal, _onUpdate, ctx) {
+      const agents = discoverAgents(ctx.cwd);
+      return {
+        content: [{ type: "text" as const, text: formatAgentList(agents) }],
+        details: { count: agents.length },
+      };
+    },
+  });
+}
+
 function formatProgressSummary(progress: SubagentProgress[]): string {
   if (progress.length === 0) return "";
   const lines = progress.map((p) => {

package/src/local-config.test.ts

@@ -0,0 +1,111 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import {
+  mkdirSync,
+  rmSync,
+  existsSync,
+  readdirSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import {
+  readLocalConfig,
+  writeLocalModel,
+  deleteLocalModel,
+} from "./local-config.js";
+
+// Redirect getAgentDir() to a temp directory via PI_CODING_AGENT_DIR.
+// This must happen before any function calls so getLocalConfigPath()
+// resolves to our sandbox directory.
+const testDir = join(tmpdir(), "pi-test-local-config");
+process.env.PI_CODING_AGENT_DIR = testDir;
+
+describe("local-config", () => {
+  beforeEach(() => {
+    mkdirSync(testDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    rmSync(testDir, { recursive: true, force: true });
+  });
+
+  describe("readLocalConfig", () => {
+    it("returns {} when file does not exist", () => {
+      expect(readLocalConfig()).toEqual({});
+    });
+
+    it("returns {} when file is corrupt JSON", () => {
+      const path = join(testDir, "agents.local.json");
+      writeFileSync(path, "{ broken json", "utf-8");
+      expect(readLocalConfig()).toEqual({});
+    });
+
+    it("parses valid JSON correctly", () => {
+      const path = join(testDir, "agents.local.json");
+      writeFileSync(
+        path,
+        JSON.stringify({ codex: { model: "o1" } }),
+        "utf-8",
+      );
+      expect(readLocalConfig()).toEqual({ codex: { model: "o1" } });
+    });
+  });
+
+  describe("writeLocalModel", () => {
+    it("creates file and writes model entry", () => {
+      writeLocalModel("codex", "o1");
+      expect(readLocalConfig()).toEqual({ codex: { model: "o1" } });
+    });
+
+    it("preserves other agent entries when updating one", () => {
+      writeLocalModel("codex", "o1");
+      writeLocalModel("claude", "claude-3.7");
+      expect(readLocalConfig()).toEqual({
+        codex: { model: "o1" },
+        claude: { model: "claude-3.7" },
+      });
+    });
+
+    it("handles model values with special characters", () => {
+      writeLocalModel("openai", "openai/gpt-4.1");
+      expect(readLocalConfig()).toEqual({
+        openai: { model: "openai/gpt-4.1" },
+      });
+    });
+  });
+
+  describe("deleteLocalModel", () => {
+    it("removes the specified agent entry", () => {
+      writeLocalModel("codex", "o1");
+      deleteLocalModel("codex");
+      expect(readLocalConfig()).toEqual({});
+    });
+
+    it("is a no-op when agent does not exist", () => {
+      writeLocalModel("codex", "o1");
+      deleteLocalModel("nonexistent");
+      expect(readLocalConfig()).toEqual({ codex: { model: "o1" } });
+    });
+
+    it("preserves other entries", () => {
+      writeLocalModel("codex", "o1");
+      writeLocalModel("claude", "claude-3.7");
+      deleteLocalModel("codex");
+      expect(readLocalConfig()).toEqual({ claude: { model: "claude-3.7" } });
+    });
+
+    it("does not create file when deleting absent agent on clean install", () => {
+      // No agents.local.json exists yet. Deleting an absent agent should
+      // be a true no-op — it must NOT materialise an empty file on disk.
+      deleteLocalModel("nonexistent");
+      expect(existsSync(join(testDir, "agents.local.json"))).toBe(false);
+    });
+  });
+
+  it("leaves no .tmp file behind after successful write", () => {
+    writeLocalModel("codex", "o1");
+    const files = readdirSync(testDir);
+    expect(files).not.toContain("agents.local.json.tmp");
+    expect(existsSync(join(testDir, "agents.local.json"))).toBe(true);
+  });
+});

package/src/local-config.ts

@@ -0,0 +1,74 @@
+import {
+  readFileSync,
+  writeFileSync,
+  existsSync,
+  renameSync,
+  unlinkSync,
+} from "node:fs";
+import { join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+/** Per-agent local overrides stored in agents.local.json */
+export type LocalConfig = Record<string, { model?: string }>;
+
+/** Returns the path to agents.local.json inside the agent directory. */
+export function getLocalConfigPath(): string {
+  return join(getAgentDir(), "agents.local.json");
+}
+
+/** Read the full agents.local.json, returning {} if missing or corrupt. */
+function readLocalConfigRaw(): LocalConfig {
+  const path = getLocalConfigPath();
+  if (!existsSync(path)) return {};
+  try {
+    return JSON.parse(readFileSync(path, "utf-8"));
+  } catch {
+    return {};
+  }
+}
+
+/** Read agents.local.json, returning {} if missing or corrupt. */
+export function readLocalConfig(): LocalConfig {
+  return readLocalConfigRaw();
+}
+
+/**
+ * Write the full config atomically: write to .tmp then rename.
+ * Falls back to a direct write if rename fails; cleans up .tmp on failure.
+ * Follows the pattern in packages/core/src/settings-io.ts.
+ */
+function writeConfigAtomic(config: LocalConfig): void {
+  const path = getLocalConfigPath();
+  const tmpPath = path + ".tmp";
+  writeFileSync(tmpPath, JSON.stringify(config, null, 2), "utf-8");
+  try {
+    renameSync(tmpPath, path);
+  } catch {
+    try {
+      unlinkSync(tmpPath);
+    } catch {
+      // ignore — tmp file may not exist
+    }
+    writeFileSync(path, JSON.stringify(config, null, 2), "utf-8");
+  }
+}
+
+/** Set the local model override for a given agent, preserving existing entries. */
+export function writeLocalModel(agentName: string, model: string): void {
+  const config = readLocalConfig();
+  config[agentName] = { ...config[agentName], model };
+  writeConfigAtomic(config);
+}
+
+/** Delete the local model override for a given agent (no-op if absent). */
+export function deleteLocalModel(agentName: string): void {
+  const config = readLocalConfig();
+  if (!(agentName in config)) return;
+  delete config[agentName];
+  writeConfigAtomic(config);
+}
+
+/** Write the full local config atomically (backup+restore safe). */
+export function setLocalConfig(config: LocalConfig): void {
+  writeConfigAtomic(config);
+}

package/src/model-validation.test.ts

@@ -0,0 +1,82 @@
+import { describe, it, expect } from "vitest";
+import type { ModelRegistry } from "@earendil-works/pi-coding-agent";
+import { validateModel, firstError } from "./model-validation.js";
+
+function mockRegistry(models: Array<{ provider: string; id: string }>): ModelRegistry {
+  return { getAll: () => models } as unknown as ModelRegistry;
+}
+
+const REGISTRY = mockRegistry([
+  { provider: "anthropic", id: "claude-sonnet-4-5" },
+  { provider: "openai", id: "gpt-5" },
+  { provider: "openrouter", id: "claude-sonnet-4-5" }, // ambiguous bare id across providers
+]);
+
+describe("validateModel", () => {
+  it("accepts a valid canonical provider/id", () => {
+    expect(validateModel("anthropic/claude-sonnet-4-5", REGISTRY)).toEqual({ ok: true });
+  });
+
+  it("accepts case-insensitive provider/id", () => {
+    expect(validateModel("Anthropic/Claude-Sonnet-4-5", REGISTRY)).toEqual({ ok: true });
+  });
+
+  it("accepts a valid unique bare id", () => {
+    expect(validateModel("gpt-5", REGISTRY)).toEqual({ ok: true });
+  });
+
+  it("rejects an ambiguous bare id (>=2 providers)", () => {
+    const r = validateModel("claude-sonnet-4-5", REGISTRY);
+    expect(r.ok).toBe(false);
+  });
+
+  it("rejects an unknown string", () => {
+    const r = validateModel("general", REGISTRY);
+    expect(r.ok).toBe(false);
+    expect((r as { error: string }).error).toContain("not found");
+  });
+
+  it("accepts a thinking suffix by matching the prefix", () => {
+    expect(validateModel("gpt-5:high", REGISTRY)).toEqual({ ok: true });
+  });
+
+  it("accepts provider/id with a thinking suffix", () => {
+    expect(validateModel("anthropic/claude-sonnet-4-5:high", REGISTRY)).toEqual({ ok: true });
+  });
+
+  it("returns ok for empty/undefined model", () => {
+    expect(validateModel(undefined, REGISTRY)).toEqual({ ok: true });
+    expect(validateModel("", REGISTRY)).toEqual({ ok: true });
+    expect(validateModel("   ", REGISTRY)).toEqual({ ok: true });
+  });
+
+  it("returns ok when the registry is empty (defer to child)", () => {
+    expect(validateModel("anything", mockRegistry([]))).toEqual({ ok: true });
+  });
+
+  it("emits the agent-name hint when model equals agentName", () => {
+    const r = validateModel("general", REGISTRY, { agentName: "general" });
+    expect(r.ok).toBe(false);
+    expect((r as { error: string }).error).toContain("looks like an agent name");
+  });
+
+  it("emits the config-pointing message when agentFilePath is set", () => {
+    const r = validateModel("bogus", REGISTRY, {
+      agentName: "reviewer",
+      agentFilePath: "/home/u/.agents/agents/reviewer.md",
+    });
+    expect(r.ok).toBe(false);
+    const err = (r as { error: string }).error;
+    expect(err).toContain("/home/u/.agents/agents/reviewer.md");
+    expect(err).toContain("Fix the model field");
+  });
+});
+
+describe("firstError", () => {
+  it("returns undefined when all ok", () => {
+    expect(firstError({ ok: true }, { ok: true })).toBeUndefined();
+  });
+  it("returns the first error string", () => {
+    expect(firstError({ ok: true }, { ok: false, error: "boom" }, { ok: false, error: "later" })).toBe("boom");
+  });
+});

package/src/model-validation.ts

@@ -0,0 +1,93 @@
+import type { ModelRegistry } from "@earendil-works/pi-coding-agent";
+
+export interface ValidateModelContext {
+  /** Agent name the caller passed (used to detect the agent→model mirror footgun). */
+  agentName?: string | undefined;
+  /** File path of the agent config whose `model:` field is being validated. */
+  agentFilePath?: string | undefined;
+}
+
+export type ValidateModelResult = { ok: true } | { ok: false; error: string };
+
+/**
+ * Find a model by reference, mirroring pi core's `findExactModelReferenceMatch`
+ * rules (that function is not exported; rules read from pi core source):
+ *   - canonical "provider/id" (case-insensitive), OR
+ *   - bare "id" (case-insensitive); ambiguous (>=2 providers share the id) → no match.
+ */
+function findMatch<T extends { provider: string; id: string }>(
+  ref: string,
+  models: readonly T[],
+): T | undefined {
+  const lower = ref.toLowerCase();
+  if (!lower) return undefined;
+  // canonical provider/id
+  const canonical = models.find((m) => `${m.provider}/${m.id}`.toLowerCase() === lower);
+  if (canonical) return canonical;
+  // bare id — must be unique across providers
+  const idMatches = models.filter((m) => m.id.toLowerCase() === lower);
+  return idMatches.length === 1 ? idMatches[0] : undefined;
+}
+
+/**
+ * Validate that a model reference string resolves to a known model.
+ *
+ * Pure gate: returns `{ ok: true }` when valid (no resolved model object —
+ * callers forward the ORIGINAL string to spawn.ts unchanged, preserving any
+ * `:high` thinking suffix for the child's own resolver).
+ *
+ * Matching is against `registry.getAll()` (all known models — a pure
+ * name-existence check; auth is deferred to the child, matching how the
+ * child's `resolveCliModel` resolves against all models). Exact-match only;
+ * fuzzy/alias patterns the child might accept are rejected here (acceptable —
+ * `model` override is discouraged, so legitimate fuzzy usage is ~0).
+ */
+export function validateModel(
+  model: string | undefined,
+  registry: ModelRegistry,
+  context: ValidateModelContext = {},
+): ValidateModelResult {
+  if (!model || !model.trim()) return { ok: true };
+  const all = registry.getAll();
+  if (all.length === 0) return { ok: true }; // unconfigured registry — defer to child
+
+  const ref = model.trim();
+  let matched = findMatch(ref, all);
+  // Thinking-suffix tolerant: if the full string failed but it has a colon,
+  // retry with the prefix before the last colon (handles "claude-sonnet-4-5:high").
+  if (!matched && ref.includes(":")) {
+    const prefix = ref.slice(0, ref.lastIndexOf(":"));
+    if (prefix) matched = findMatch(prefix, all);
+  }
+  if (matched) return { ok: true };
+
+  const sample = all.slice(0, 5).map((m) => `${m.provider}/${m.id}`).join(", ");
+  const more = all.length > 5 ? `, … (${all.length} total)` : "";
+
+  // Prioritize file-path message when both agentName and agentFilePath are set
+  // (more actionable than the generic agent-name hint)
+  if (context.agentFilePath) {
+    return {
+      ok: false,
+      error: `Agent "${context.agentName ?? "unknown"}" is configured with an invalid model "${model}" (in ${context.agentFilePath}). Fix the model field or agents.local.json. Available: ${sample}${more}.`,
+    };
+  }
+  if (context.agentName && ref === context.agentName.trim()) {
+    return {
+      ok: false,
+      error: `Model "${model}" not found — it looks like an agent name, not a model. Omit the model parameter; the agent's configured model or the parent's current model will be used. Available models include: ${sample}${more}.`,
+    };
+  }
+  return {
+    ok: false,
+    error: `Model "${model}" not found. Available models include: ${sample}${more}.`,
+  };
+}
+
+/** Return the first error message from the given results, or undefined if all ok. */
+export function firstError(...results: ValidateModelResult[]): string | undefined {
+  for (const r of results) {
+    if (!r.ok) return r.error;
+  }
+  return undefined;
+}

package/src/save-agent.test.ts

@@ -0,0 +1,483 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { mkdirSync, rmSync, readFileSync, writeFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { saveAgent } from "./agent-manager.js";
+import { discoverAgentsAll } from "./agents.js";
+import { writeLocalModel } from "./local-config.js";
+
+// Mock writeLocalModel to always throw (simulating a JSON store write
+// failure). deleteLocalModel is a no-op since it's never reached in
+// these tests. readLocalConfig / setLocalConfig / getLocalConfigPath
+// use their REAL implementations (via importOriginal) so the saveAgent
+// JSON backup/restore logic can be exercised end-to-end.
+vi.mock("./local-config.js", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("./local-config.js")>();
+  return {
+    ...actual,
+    writeLocalModel: vi.fn(() => {
+      throw new Error("JSON write failed");
+    }),
+    deleteLocalModel: vi.fn(),
+  };
+});
+
+// Partial mock of ./agents.js: keep all original exports but replace
+// discoverAgentsAll with a vi.fn() so individual tests can control its
+// behavior (e.g. throwing to simulate a re-discovery failure). Existing
+// tests never reach discoverAgentsAll because they fail earlier; the
+// default vi.fn() returns undefined which is fine for those paths.
+vi.mock("./agents.js", async (importOriginal) => ({
+  ...((await importOriginal()) as Record<string, unknown>),
+  discoverAgentsAll: vi.fn(),
+}));
+
+// Redirect getAgentDir() to a temp directory via PI_CODING_AGENT_DIR.
+// This must happen before any function calls so readLocalConfig()
+// resolves agents.local.json to our sandbox directory.
+const testDir = join(tmpdir(), "pi-test-save-agent");
+process.env.PI_CODING_AGENT_DIR = testDir;
+
+describe("saveAgent JSON rename cleanup ordering", () => {
+  beforeEach(() => {
+    mkdirSync(testDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    rmSync(testDir, { recursive: true, force: true });
+  });
+
+  it("does not delete old JSON rename entry when .md write fails", () => {
+    // Pre-populate agents.local.json with the OLD name's model override
+    writeFileSync(
+      join(testDir, "agents.local.json"),
+      JSON.stringify({ oldcodex: { model: "claude-3.7" } }),
+      "utf-8",
+    );
+
+    // Make the .md write fail by creating codex.md as a directory.
+    // writeFileSync will throw EISDIR when writing to a directory path.
+    mkdirSync(join(testDir, "codex.md"), { recursive: true });
+
+    const state = {
+      editAgent: {
+        name: "codex",
+        description: "test agent",
+        systemPrompt: "hello world",
+        source: "user",
+        filePath: join(testDir, "oldcodex.md"),
+        model: "gpt-4o",
+      },
+      editOriginal: {
+        name: "oldcodex",
+        description: "test agent",
+        systemPrompt: "hello world",
+        source: "user",
+        filePath: join(testDir, "oldcodex.md"),
+      },
+      agents: [],
+      globalDir: null,
+      userDir: testDir,
+      projectDir: null,
+      editError: null,
+      editDirty: false,
+    };
+
+    saveAgent(state as any, () => {});
+
+    // The .md write failed, so the old JSON rename entry should NOT have been
+    // deleted. If deleteLocalModel(originalName) ran before the .md write
+    // (the bug), the old entry would be gone here.
+    const config = JSON.parse(
+      readFileSync(join(testDir, "agents.local.json"), "utf-8"),
+    );
+    expect(config.oldcodex).toEqual({ model: "claude-3.7" });
+    expect(state.editError).toBeTruthy();
+  });
+});
+
+describe("saveAgent rollback model to .md", () => {
+  beforeEach(() => {
+    mkdirSync(testDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    rmSync(testDir, { recursive: true, force: true });
+  });
+
+  it("restore model to .md when JSON write fails", () => {
+    // writeLocalModel is mocked (vi.mock at top of file) to always throw.
+    // The .md write itself succeeds (real fs.writeFileSync), then the
+    // JSON store write fails, triggering the catch-block rollback.
+
+    const state = {
+      editAgent: {
+        name: "codex",
+        description: "test agent",
+        systemPrompt: "hello world",
+        source: "user",
+        filePath: join(testDir, "codex.md"),
+        model: "openai/gpt-4o",
+      },
+      editOriginal: {
+        name: "codex",
+        description: "test agent",
+        systemPrompt: "hello world",
+        source: "user",
+        filePath: join(testDir, "codex.md"),
+      },
+      agents: [],
+      globalDir: null,
+      userDir: testDir,
+      projectDir: null,
+      editError: null,
+      editDirty: false,
+    };
+
+    saveAgent(state as any, () => {});
+
+    // The .md file should still contain the model field (rollback).
+    const mdContent = readFileSync(join(testDir, "codex.md"), "utf-8");
+    expect(mdContent).toContain("model: openai/gpt-4o");
+
+    // editError should be set.
+    expect(state.editError).toBeTruthy();
+
+    // The live edit in-memory object should still have the model (not deleted).
+    expect(state.editAgent!.model).toBe("openai/gpt-4o");
+  });
+
+  it("restores original .md content when JSON write fails", () => {
+    // writeLocalModel is mocked (vi.mock at top of file) to always throw,
+    // so the .md write succeeds but the JSON store write fails, triggering
+    // the catch-block restore-original path.
+    // Pre-create the .md file with original content (including an old model
+    // override in frontmatter) so saveAgent can capture and restore it.
+    const originalMd = [
+      "---",
+      "name: codex",
+      "description: original description",
+      "model: old-model",
+      "---",
+      "",
+      "original prompt",
+      "",
+    ].join("\n");
+    writeFileSync(join(testDir, "codex.md"), originalMd, "utf-8");
+
+    const state = {
+      editAgent: {
+        name: "codex",
+        description: "new description",
+        systemPrompt: "new prompt",
+        source: "user",
+        filePath: join(testDir, "codex.md"),
+        model: "new-model",
+      },
+      editOriginal: {
+        name: "codex",
+        description: "original description",
+        systemPrompt: "original prompt",
+        source: "user",
+        filePath: join(testDir, "codex.md"),
+      },
+      agents: [],
+      globalDir: null,
+      userDir: testDir,
+      projectDir: null,
+      editError: null,
+      editDirty: false,
+    };
+
+    saveAgent(state as any, () => {});
+
+    // The .md file should have been restored to the original content
+    // verbatim (including the old model), NOT left with the new edit.
+    const mdContent = readFileSync(join(testDir, "codex.md"), "utf-8");
+    expect(mdContent).toContain("model: old-model");
+    expect(mdContent).not.toContain("new description");
+
+    // editError should be set.
+    expect(state.editError).toBeTruthy();
+  });
+});
+
+describe("saveAgent retry safety when re-discovery fails", () => {
+  beforeEach(() => {
+    mkdirSync(testDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    rmSync(testDir, { recursive: true, force: true });
+  });
+
+  it("retains model for retry when re-discovery fails", () => {
+    // Make writeLocalModel succeed for this call only (default mock throws).
+    // This lets execution proceed past the JSON write to discoverAgentsAll.
+    vi.mocked(writeLocalModel).mockImplementationOnce(() => {});
+
+    // Make discoverAgentsAll throw after the save completes.
+    vi.mocked(discoverAgentsAll).mockImplementationOnce(() => {
+      throw new Error("discovery failed");
+    });
+
+    const state = {
+      editAgent: {
+        name: "codex",
+        description: "test agent",
+        systemPrompt: "hello world",
+        source: "user",
+        filePath: join(testDir, "codex.md"),
+        model: "openai/gpt-4o",
+      },
+      editOriginal: {
+        name: "codex",
+        description: "test agent",
+        systemPrompt: "hello world",
+        source: "user",
+        filePath: join(testDir, "codex.md"),
+      },
+      agents: [],
+      globalDir: null,
+      userDir: testDir,
+      projectDir: null,
+      editError: null,
+      editDirty: false,
+    };
+
+    saveAgent(state as any, () => {});
+
+    // The live edit object should still have the model — delete agent.model
+    // only runs after requestRender() which never executed because
+    // discoverAgentsAll threw first.
+    expect(state.editAgent!.model).toBe("openai/gpt-4o");
+
+    // editError should contain the discovery failure message.
+    expect(state.editError).toContain("discovery failed");
+
+    // The .md file should have the model restored by the catch block
+    // rollback (serializeAgent({ ...agent, model })).
+    const mdContent = readFileSync(join(testDir, "codex.md"), "utf-8");
+    expect(mdContent).toContain("model: openai/gpt-4o");
+  });
+
+  it("does not delete renamed .md when re-discovery fails after old file removed", () => {
+    // Allow writeLocalModel to succeed, then make discoverAgentsAll throw
+    // after the rename unlinkSync has already run (oldPath is gone).
+    vi.mocked(writeLocalModel).mockImplementationOnce(() => {});
+    vi.mocked(discoverAgentsAll).mockImplementationOnce(() => {
+      throw new Error("discovery failed");
+    });
+
+    // Pre-create the old .md file (the original agent at oldPath).
+    writeFileSync(
+      join(testDir, "oldcodex.md"),
+      "original rename content",
+      "utf-8",
+    );
+
+    const state = {
+      editAgent: {
+        name: "codex",
+        description: "new description",
+        systemPrompt: "new prompt",
+        source: "user",
+        filePath: join(testDir, "oldcodex.md"), // oldPath
+        model: "openai/gpt-4o",
+      },
+      editOriginal: {
+        name: "oldcodex",
+        description: "original description",
+        systemPrompt: "original prompt",
+        source: "user",
+        filePath: join(testDir, "oldcodex.md"),
+      },
+      agents: [],
+      globalDir: null,
+      userDir: testDir,
+      projectDir: null,
+      editError: null,
+      editDirty: false,
+    };
+
+    saveAgent(state as any, () => {});
+
+    // The old file was deleted during the save (rename unlinkSync succeeded).
+    // newPath should NOT be deleted in the catch block — it is the only
+    // surviving copy of the agent.
+    const newPath = join(testDir, "codex.md");
+    expect(existsSync(newPath)).toBe(true);
+    const newContent = readFileSync(newPath, "utf-8");
+    expect(newContent).toContain("model: openai/gpt-4o");
+
+    // editError should contain the discovery failure message.
+    expect(state.editError).toContain("discovery failed");
+  });
+
+  it("rolls back both .md and JSON when re-discovery fails", () => {
+    // Allow writeLocalModel to succeed so execution proceeds past the JSON
+    // write to discoverAgentsAll, which will throw.
+    vi.mocked(writeLocalModel).mockImplementationOnce(() => {});
+    vi.mocked(discoverAgentsAll).mockImplementationOnce(() => {
+      throw new Error("discovery failed");
+    });
+
+    // Pre-create the .md file with original content (including old model).
+    const originalMd = [
+      "---",
+      "name: codex",
+      "description: original description",
+      "model: old-model",
+      "---",
+      "",
+      "original prompt",
+      "",
+    ].join("\n");
+    writeFileSync(join(testDir, "codex.md"), originalMd, "utf-8");
+
+    // Pre-create agents.local.json with the old model override.
+    writeFileSync(
+      join(testDir, "agents.local.json"),
+      JSON.stringify({ codex: { model: "old-model" } }),
+      "utf-8",
+    );
+
+    const state = {
+      editAgent: {
+        name: "codex",
+        description: "new description",
+        systemPrompt: "new prompt",
+        source: "user",
+        filePath: join(testDir, "codex.md"),
+        model: "new-model",
+      },
+      editOriginal: {
+        name: "codex",
+        description: "original description",
+        systemPrompt: "original prompt",
+        source: "user",
+        filePath: join(testDir, "codex.md"),
+      },
+      agents: [],
+      globalDir: null,
+      userDir: testDir,
+      projectDir: null,
+      editError: null,
+      editDirty: false,
+    };
+
+    saveAgent(state as any, () => {});
+
+    // .md file should be restored to original content (model: old-model).
+    const mdContent = readFileSync(join(testDir, "codex.md"), "utf-8");
+    expect(mdContent).toContain("model: old-model");
+    expect(mdContent).not.toContain("new description");
+
+    // agents.local.json should be restored to old-model via setLocalConfig.
+    const jsonContent = JSON.parse(
+      readFileSync(join(testDir, "agents.local.json"), "utf-8"),
+    );
+    expect(jsonContent.codex).toEqual({ model: "old-model" });
+
+    // The live edit object should still have the new model (retained for retry).
+    expect(state.editAgent!.model).toBe("new-model");
+
+    // editError should be set.
+    expect(state.editError).toBeTruthy();
+  });
+});
+
+describe("saveAgent double-delete prevention on retry", () => {
+  beforeEach(() => {
+    mkdirSync(testDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    rmSync(testDir, { recursive: true, force: true });
+  });
+
+  it("does not delete newPath when old file already absent on retry", () => {
+    vi.mocked(writeLocalModel).mockImplementationOnce(() => {});
+    vi.mocked(writeLocalModel).mockImplementationOnce(() => {});
+    vi.mocked(discoverAgentsAll).mockImplementationOnce(() => {
+      throw new Error("discovery failed");
+    });
+    vi.mocked(discoverAgentsAll).mockImplementationOnce(() => {
+      throw new Error("discovery failed");
+    });
+    writeFileSync(join(testDir, "oldcodex.md"), "original rename content", "utf-8");
+    const state = {
+      editAgent: {
+        name: "codex",
+        description: "new description",
+        systemPrompt: "new prompt",
+        source: "user",
+        filePath: join(testDir, "oldcodex.md"),
+        model: "openai/gpt-4o",
+      },
+      editOriginal: {
+        name: "oldcodex",
+        description: "original description",
+        systemPrompt: "original prompt",
+        source: "user",
+        filePath: join(testDir, "oldcodex.md"),
+      },
+      agents: [],
+      globalDir: null,
+      userDir: testDir,
+      projectDir: null,
+      editError: null,
+      editDirty: false,
+    };
+    saveAgent(state as any, () => {});
+    expect(existsSync(join(testDir, "oldcodex.md"))).toBe(false);
+    const newPath = join(testDir, "codex.md");
+    expect(existsSync(newPath)).toBe(true);
+    saveAgent(state as any, () => {});
+    expect(existsSync(newPath)).toBe(true);
+    expect(state.editError).toContain("discovery failed");
+  });
+});
+
+describe("saveAgent cleanup of model-less new files", () => {
+  beforeEach(() => {
+    mkdirSync(testDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    rmSync(testDir, { recursive: true, force: true });
+  });
+
+  it("deletes new file on failure when no model", () => {
+    vi.mocked(discoverAgentsAll).mockImplementationOnce(() => {
+      throw new Error("discovery failed");
+    });
+    const state = {
+      editAgent: {
+        name: "newagent",
+        description: "test agent",
+        systemPrompt: "hello world",
+        source: "user",
+        filePath: undefined,
+      },
+      editOriginal: {
+        name: "newagent",
+        description: "",
+        systemPrompt: "",
+        source: "user",
+        filePath: undefined,
+      },
+      agents: [],
+      globalDir: null,
+      userDir: testDir,
+      projectDir: null,
+      editError: null,
+      editDirty: false,
+    };
+    saveAgent(state as any, () => {});
+    const newPath = join(testDir, "newagent.md");
+    expect(existsSync(newPath)).toBe(false);
+    expect(state.editError).toBeTruthy();
+  });
+});
+