pi-better-openai 0.1.13 → 0.1.15

package/index.ts

@@ -66,10 +66,9 @@ import {
   listCodexPets,
   nextAnimationFrameDelayMs,
   PET_ANIMATION_ROWS,
-  deleteCodexPetKittyPlacement,
+  CodexPetKittyManager,
   registerOpenAIPets,
   renderCodexPetFrame,
-  resetCodexPetKittyCache,
   _petsTest,
 } from "./src/pets.ts";
 
@@ -207,7 +206,10 @@ function formatPetSelectPrompt(
     lines.push(
       "",
       "Not ready:",
-      ...brokenPets.map((pet) => `- ${pet.slug} (${pet.name}) — missing ${pet.spritesheetPath}`),
+      ...brokenPets.map(
+        (pet) =>
+          `- ${pet.slug} (${pet.name}) — ${pet.spritesheetIssue ?? `missing ${pet.spritesheetPath}`}`,
+      ),
     );
   }
   return { message: lines.join("\n"), level: "info" };
@@ -391,9 +393,9 @@ export default function betterOpenAI(pi: ExtensionAPI): void {
   let petAnimationState: PetState | undefined;
   let petAnimationStartedAt = Date.now();
   const petRenderCache = new Map<string, string[]>();
-  const pendingPetKittyCleanupImageIds = new Set<number>();
   const activeToolCallIds = new Set<string>();
   const petImageId = 0x70657401;
+  const petKittyManager = new CodexPetKittyManager(petImageId);
 
   function refresh(ctx: ExtensionContext): ResolvedConfig {
     cachedConfig = resolveConfig(ctx.cwd || process.cwd());
@@ -455,22 +457,11 @@ export default function betterOpenAI(pi: ExtensionAPI): void {
   }
 
   function queuePetKittyCleanup(target = pet): void {
-    if (!target) return;
-    for (const frames of Object.values(target.states)) {
-      for (const frame of frames) {
-        if (frame.kittyImageId !== undefined)
-          pendingPetKittyCleanupImageIds.add(frame.kittyImageId);
-      }
-    }
+    petKittyManager.invalidate(target);
   }
 
   function takePetKittyCleanupSequence(): string {
-    if (pendingPetKittyCleanupImageIds.size === 0) return "";
-    const sequence = Array.from(pendingPetKittyCleanupImageIds)
-      .map((imageId) => deleteCodexPetKittyPlacement(imageId))
-      .join("");
-    pendingPetKittyCleanupImageIds.clear();
-    return sequence;
+    return petKittyManager.takeCleanupSequence();
   }
 
   function withPendingPetKittyCleanup(lines: string[]): string[] {
@@ -480,11 +471,18 @@ export default function betterOpenAI(pi: ExtensionAPI): void {
     return [`${sequence}\x1b[0m${lines[0]}\x1b[0m`, ...lines.slice(1)];
   }
 
-  function flushPetKittyCleanupNow(): void {
-    const sequence = takePetKittyCleanupSequence();
+  function writePetKittySequence(sequence: string): void {
     if (sequence && process.stdout.isTTY) process.stdout.write(sequence);
   }
 
+  function flushPetKittyCleanupNow(): void {
+    writePetKittySequence(takePetKittyCleanupSequence());
+  }
+
+  function disposePetKittyNow(target = pet): void {
+    writePetKittySequence(petKittyManager.dispose(target));
+  }
+
   function rememberPetRender(key: string, lines: string[]): void {
     petRenderCache.set(key, lines);
     while (petRenderCache.size > PET_RENDER_CACHE_LIMIT) {
@@ -514,7 +512,7 @@ export default function betterOpenAI(pi: ExtensionAPI): void {
     petResizeTimer = setTimeout(() => {
       petResizeTimer = undefined;
       petResizeFreezeUntil = 0;
-      resetCodexPetKittyCache(pet, petImageId);
+      petKittyManager.resetForResize(pet);
       resetPetRenderCache();
       updateFooter(ctx);
     }, PET_RESIZE_FREEZE_MS);
@@ -658,7 +656,6 @@ export default function betterOpenAI(pi: ExtensionAPI): void {
     if (!shouldLoadPetForConfig(cfg)) {
       queuedPetRefresh = undefined;
       queuePetKittyCleanup();
-      resetCodexPetKittyCache(pet, petImageId);
       pet = undefined;
       petError = undefined;
       petLoadKey = undefined;
@@ -694,10 +691,7 @@ export default function betterOpenAI(pi: ExtensionAPI): void {
         sizeCells: cfg.pets.sizeCells,
       });
       if (!shouldApplyLoadResult()) return;
-      if (previousPet) {
-        queuePetKittyCleanup(previousPet);
-        resetCodexPetKittyCache(previousPet, petImageId);
-      }
+      if (previousPet) queuePetKittyCleanup(previousPet);
       pet = loadedPet;
       const petIssue = pet
         ? undefined
@@ -716,10 +710,7 @@ export default function betterOpenAI(pi: ExtensionAPI): void {
       }
     } catch (error) {
       if (!shouldApplyLoadResult()) return;
-      if (previousPet) {
-        queuePetKittyCleanup(previousPet);
-        resetCodexPetKittyCache(previousPet, petImageId);
-      }
+      if (previousPet) queuePetKittyCleanup(previousPet);
       pet = undefined;
       petLoadKey = key;
       petError = error instanceof Error ? error.message : String(error);
@@ -1038,6 +1029,7 @@ export default function betterOpenAI(pi: ExtensionAPI): void {
         imageId: petImageId,
         now: elapsedMs,
         durationMultiplier: 1,
+        kittyManager: petKittyManager,
       }),
     ];
   }
@@ -1057,6 +1049,8 @@ export default function betterOpenAI(pi: ExtensionAPI): void {
     let selectedIndex = 0;
     let searchQuery = "";
     let closed = false;
+    let submenuComponent: ReturnType<NonNullable<SettingsPickerItem["submenu"]>> | undefined;
+    let submenuItemIndex: number | undefined;
 
     function currentItems(): SettingsPickerItem[] {
       const allItems = items();
@@ -1078,6 +1072,13 @@ export default function betterOpenAI(pi: ExtensionAPI): void {
       done();
     }
 
+    function closeNestedSubmenu(): void {
+      submenuComponent = undefined;
+      if (submenuItemIndex !== undefined) selectedIndex = submenuItemIndex;
+      submenuItemIndex = undefined;
+      options?.onSelection?.(selectedItem());
+    }
+
     function cycleSelected(direction: 1 | -1 = 1): void {
       const item = selectedItem();
       if (!item?.values?.length) return;
@@ -1090,8 +1091,23 @@ export default function betterOpenAI(pi: ExtensionAPI): void {
       options?.onSelection?.(selectedItem());
     }
 
+    function activateSelected(): void {
+      const item = selectedItem();
+      if (!item) return;
+      if (item.submenu) {
+        submenuItemIndex = selectedIndex;
+        submenuComponent = item.submenu(item.currentValue, (selectedValue?: string) => {
+          if (selectedValue !== undefined) writeSetting(ctx, item.id, selectedValue);
+          closeNestedSubmenu();
+        });
+        return;
+      }
+      cycleSelected(1);
+    }
+
     return {
       render(width: number) {
+        if (submenuComponent) return submenuComponent.render(width);
         const current = currentItems();
         const selected = selectedItem();
         if (!closed) options?.onSelection?.(selected);
@@ -1149,8 +1165,14 @@ export default function betterOpenAI(pi: ExtensionAPI): void {
         );
         return lines;
       },
-      invalidate() {},
+      invalidate() {
+        submenuComponent?.invalidate();
+      },
       handleInput(data: string) {
+        if (submenuComponent) {
+          submenuComponent.handleInput?.(data);
+          return;
+        }
         const current = currentItems();
         if (current.length === 0) {
           if (matchesKey(data, Key.escape) || matchesKey(data, Key.ctrl("c"))) close();
@@ -1168,7 +1190,7 @@ export default function betterOpenAI(pi: ExtensionAPI): void {
           matchesKey(data, Key.space) ||
           data === " "
         )
-          cycleSelected(1);
+          activateSelected();
         else if (matchesKey(data, Key.left)) cycleSelected(-1);
         else if (matchesKey(data, Key.escape) || matchesKey(data, Key.ctrl("c"))) close();
         else if (matchesKey(data, Key.backspace)) {
@@ -1183,7 +1205,35 @@ export default function betterOpenAI(pi: ExtensionAPI): void {
     };
   }
 
-  function buildSettingsItems(ctx: ExtensionContext, cfg: ResolvedConfig): SettingsPickerItem[] {
+  function fastSettingsSummary(ctx: ExtensionContext, cfg: ResolvedConfig): string {
+    if (active) return "on";
+    if (desiredActive)
+      return supportsFast(ctx, cfg.supportedModels) ? "requested" : "requested inactive";
+    return "off";
+  }
+
+  function usageSettingsSummary(cfg: ResolvedConfig): string {
+    return cfg.usage.enabled
+      ? `enabled · ${Math.round(cfg.usage.refreshIntervalMs / 1000)}s`
+      : "disabled";
+  }
+
+  function imageSettingsSummary(cfg: ResolvedConfig): string {
+    return cfg.image.enabled
+      ? `enabled · ${cfg.image.defaultModel} · ${cfg.image.defaultSave}/${cfg.image.outputFormat}`
+      : "disabled";
+  }
+
+  function petSettingsSummary(cfg: ResolvedConfig): string {
+    const selected = cfg.pets.slug || (cfg.pets.enabled ? "first ready" : PET_EMPTY_VALUE);
+    const status = cfg.pets.enabled ? "enabled" : "disabled";
+    return `${status} · ${selected} · ${cfg.pets.placement}`;
+  }
+
+  function buildFastSettingsItems(
+    ctx: ExtensionContext,
+    cfg: ResolvedConfig,
+  ): SettingsPickerItem[] {
     return [
       {
         id: "fast.enabled",
@@ -1199,6 +1249,11 @@ export default function betterOpenAI(pi: ExtensionAPI): void {
         values: ["true", "false"],
         description: "Remember fast-mode state across sessions.",
       },
+    ];
+  }
+
+  function buildFooterSettingsItems(cfg: ResolvedConfig): SettingsPickerItem[] {
+    return [
       {
         id: "footer.mode",
         label: "Footer mode",
@@ -1207,36 +1262,11 @@ export default function betterOpenAI(pi: ExtensionAPI): void {
         description:
           "replace = custom footer, status = pi footer plus status line, off = no Better OpenAI footer/status unless Footer pet is enabled.",
       },
-      {
-        id: "pets.menu",
-        label: "Footer pet",
-        currentValue: "configure",
-        description: "Configure footer pet visibility, animation-state mapping, and size.",
-        submenu: (_value, done) => {
-          setPetSettingsPreviewActive(ctx, true);
-          return settingsSubmenu(
-            "Footer pet settings",
-            () => buildPetSettingsItems(config(ctx)),
-            ctx,
-            () => done(),
-            {
-              onSelection: (item) => {
-                const previewState = petPreviewFromItem(item);
-                if (previewState !== petPreviewState) {
-                  petPreviewState = previewState;
-                  updateFooter(ctx);
-                }
-              },
-              onClose: () => {
-                petPreviewState = undefined;
-                setPetSettingsPreviewActive(ctx, false);
-                updateFooter(ctx);
-              },
-              renderExtra: (width) => renderPetSettingsPreview(ctx, width),
-            },
-          );
-        },
-      },
+    ];
+  }
+
+  function buildUsageSettingsItems(cfg: ResolvedConfig): SettingsPickerItem[] {
+    return [
       {
         id: "usage.enabled",
         label: "Usage display",
@@ -1265,6 +1295,11 @@ export default function betterOpenAI(pi: ExtensionAPI): void {
         values: ["true", "false"],
         description: "Include compact reset countdowns and local reset times.",
       },
+    ];
+  }
+
+  function buildImageSettingsItems(cfg: ResolvedConfig): SettingsPickerItem[] {
+    return [
       {
         id: "image.enabled",
         label: "Image tool",
@@ -1301,6 +1336,14 @@ export default function betterOpenAI(pi: ExtensionAPI): void {
         values: ["30000", "60000", "120000", "180000", "300000"],
         description: "Image request timeout in milliseconds.",
       },
+    ];
+  }
+
+  function buildDiagnosticsSettingsItems(
+    ctx: ExtensionContext,
+    cfg: ResolvedConfig,
+  ): SettingsPickerItem[] {
+    return [
       {
         id: "debug",
         label: "Debug info",
@@ -1330,6 +1373,106 @@ export default function betterOpenAI(pi: ExtensionAPI): void {
     ];
   }
 
+  function buildSettingsSections(ctx: ExtensionContext, cfg: ResolvedConfig): SettingsPickerItem[] {
+    return [
+      {
+        id: "section.fast",
+        label: "Fast mode",
+        currentValue: fastSettingsSummary(ctx, cfg),
+        description: "Configure OpenAI fast mode and persistence.",
+        submenu: (_value, done) =>
+          settingsSubmenu(
+            "Fast mode settings",
+            () => buildFastSettingsItems(ctx, config(ctx)),
+            ctx,
+            () => done(fastSettingsSummary(ctx, config(ctx))),
+          ),
+      },
+      {
+        id: "section.footer",
+        label: "Footer",
+        currentValue: cfg.footer.mode,
+        description: "Configure Better OpenAI footer ownership.",
+        submenu: (_value, done) =>
+          settingsSubmenu(
+            "Footer settings",
+            () => buildFooterSettingsItems(config(ctx)),
+            ctx,
+            () => done(config(ctx).footer.mode),
+          ),
+      },
+      {
+        id: "section.usage",
+        label: "Usage",
+        currentValue: usageSettingsSummary(cfg),
+        description: "Configure subscription usage fetching and display.",
+        submenu: (_value, done) =>
+          settingsSubmenu(
+            "Usage settings",
+            () => buildUsageSettingsItems(config(ctx)),
+            ctx,
+            () => done(usageSettingsSummary(config(ctx))),
+          ),
+      },
+      {
+        id: "section.image",
+        label: "Image tool",
+        currentValue: imageSettingsSummary(cfg),
+        description: "Configure OpenAI image generation defaults.",
+        submenu: (_value, done) =>
+          settingsSubmenu(
+            "Image tool settings",
+            () => buildImageSettingsItems(config(ctx)),
+            ctx,
+            () => done(imageSettingsSummary(config(ctx))),
+          ),
+      },
+      {
+        id: "section.pets",
+        label: "Footer pet",
+        currentValue: petSettingsSummary(cfg),
+        description: "Configure footer pet visibility, animation-state mapping, and size.",
+        submenu: (_value, done) => {
+          setPetSettingsPreviewActive(ctx, true);
+          return settingsSubmenu(
+            "Footer pet settings",
+            () => buildPetSettingsItems(config(ctx)),
+            ctx,
+            () => done(petSettingsSummary(config(ctx))),
+            {
+              onSelection: (item) => {
+                const previewState = petPreviewFromItem(item);
+                if (previewState !== petPreviewState) {
+                  petPreviewState = previewState;
+                  updateFooter(ctx);
+                }
+              },
+              onClose: () => {
+                petPreviewState = undefined;
+                setPetSettingsPreviewActive(ctx, false);
+                updateFooter(ctx);
+              },
+              renderExtra: (width) => renderPetSettingsPreview(ctx, width),
+            },
+          );
+        },
+      },
+      {
+        id: "section.diagnostics",
+        label: "Diagnostics",
+        currentValue: "debug / config",
+        description: "Show Better OpenAI diagnostics and raw config details.",
+        submenu: (_value, done) =>
+          settingsSubmenu(
+            "Diagnostics",
+            () => buildDiagnosticsSettingsItems(ctx, config(ctx)),
+            ctx,
+            () => done("debug / config"),
+          ),
+      },
+    ];
+  }
+
   function writeSetting(ctx: ExtensionContext, id: string, rawValue: string): void {
     const cfg = refresh(ctx);
     const current = readRawConfig(cfg.configPath);
@@ -1422,15 +1565,15 @@ export default function betterOpenAI(pi: ExtensionAPI): void {
           })(),
         );
         const settingsList = new SettingsList(
-          buildSettingsItems(ctx, refresh(ctx)),
-          13,
+          buildSettingsSections(ctx, refresh(ctx)),
+          8,
           getSettingsListTheme(),
           (id, newValue) => {
-            writeSetting(ctx, id, newValue);
+            if (!id.startsWith("section.")) writeSetting(ctx, id, newValue);
             settingsList.updateValue(
               id,
-              buildSettingsItems(ctx, config(ctx)).find((item) => item.id === id)?.currentValue ??
-                newValue,
+              buildSettingsSections(ctx, config(ctx)).find((item) => item.id === id)
+                ?.currentValue ?? newValue,
             );
             tui.requestRender();
           },
@@ -1490,7 +1633,6 @@ export default function betterOpenAI(pi: ExtensionAPI): void {
     tuck: (ctx) => {
       writePetConfig(ctx, { enabled: false });
       queuePetKittyCleanup();
-      resetCodexPetKittyCache(pet, petImageId);
       pet = undefined;
       petError = undefined;
       resetPetRenderCache();
@@ -1543,12 +1685,12 @@ export default function betterOpenAI(pi: ExtensionAPI): void {
           stopPetIdleEmotes();
           stopPetAnimation();
           stopPendingPetRenderRequest();
+          disposePetKittyNow();
           footerInstalled = false;
           requestFooterRender = undefined;
         },
         invalidate() {
           queuePetKittyCleanup();
-          resetCodexPetKittyCache(pet, petImageId);
           resetPetRenderCache();
         },
         render(width: number): string[] {
@@ -1732,6 +1874,7 @@ export default function betterOpenAI(pi: ExtensionAPI): void {
                       imageId: petImageId,
                       now: elapsedMs,
                       durationMultiplier: 1,
+                      kittyManager: petKittyManager,
                     },
                   );
                   petLines.push(...renderedPetLines);
@@ -1778,7 +1921,7 @@ export default function betterOpenAI(pi: ExtensionAPI): void {
 
   function clearFooter(ctx: ExtensionContext): void {
     if (!footerInstalled) return;
-    flushPetKittyCleanupNow();
+    disposePetKittyNow();
     ctx.ui.setFooter(undefined);
     footerInstalled = false;
     requestFooterRender = undefined;
@@ -1885,7 +2028,6 @@ export default function betterOpenAI(pi: ExtensionAPI): void {
   pi.on("session_compact", (_event, ctx) => {
     refreshFooterTotals(ctx);
     queuePetKittyCleanup();
-    resetCodexPetKittyCache(pet, petImageId);
     resetPetRenderCache();
     updateFooter(ctx);
   });
@@ -1893,7 +2035,6 @@ export default function betterOpenAI(pi: ExtensionAPI): void {
   pi.on("session_tree", (_event, ctx) => {
     refreshFooterTotals(ctx);
     queuePetKittyCleanup();
-    resetCodexPetKittyCache(pet, petImageId);
     resetPetRenderCache();
     updateFooter(ctx);
   });
@@ -1927,8 +2068,7 @@ export default function betterOpenAI(pi: ExtensionAPI): void {
     usageTimer = undefined;
     activeToolCallIds.clear();
     uninstallPetResizeGuard();
-    queuePetKittyCleanup();
-    flushPetKittyCleanupNow();
+    disposePetKittyNow();
     resetPetRenderCache();
     clearPetFlash();
     stopPetIdleEmotes();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-openai",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "description": "Personal pi extension that improves OpenAI with fast mode, usage stats, and footer polish.",
   "keywords": [
     "fast",

package/src/pets.ts

@@ -1,5 +1,5 @@
-import type { Dirent } from "node:fs";
-import { access, readdir, readFile } from "node:fs/promises";
+import { constants, type Dirent } from "node:fs";
+import { access, readdir, readFile, stat } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join, resolve, sep } from "node:path";
 import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
@@ -21,6 +21,8 @@ const PET_COLUMNS = 8;
 const PET_ROWS = 9;
 const DEFAULT_CELL_WIDTH = 192;
 const DEFAULT_CELL_HEIGHT = 208;
+const EXPECTED_ATLAS_WIDTH = DEFAULT_CELL_WIDTH * PET_COLUMNS;
+const EXPECTED_ATLAS_HEIGHT = DEFAULT_CELL_HEIGHT * PET_ROWS;
 
 export const PET_ANIMATION_ROWS: Record<PetState, { row: number; durations: number[] }> = {
   idle: { row: 0, durations: [280, 110, 110, 140, 140, 320] },
@@ -42,6 +44,7 @@ export type CodexPetPackage = {
   dir: string;
   spritesheetPath: string;
   hasSpritesheet: boolean;
+  spritesheetIssue?: string;
 };
 
 export type PetFrame = {
@@ -70,6 +73,29 @@ type ThemeLike = {
   fg(color: string, value: string): string;
 };
 
+const TERMINAL_ESCAPE_REGEXP = new RegExp(
+  String.raw`\u001b(?:\][\s\S]*?(?:\u0007|\u001b\\)|[_PX^][\s\S]*?\u001b\\|\[[0-?]*[ -/]*[@-~]|[@-_][0-?]*[ -/]*[@-~])`,
+  "g",
+);
+const CONTROL_CHAR_REGEXP = new RegExp(String.raw`[\u0000-\u001f\u007f-\u009f]+`, "g");
+
+function stripTerminalEscapes(value: string): string {
+  return value.replace(TERMINAL_ESCAPE_REGEXP, "");
+}
+
+function sanitizePetDisplayText(value: string): string | undefined {
+  const sanitized = stripTerminalEscapes(value)
+    .replace(CONTROL_CHAR_REGEXP, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+  return sanitized || undefined;
+}
+
+function sanitizePetAssetPathText(value: string): string | undefined {
+  const sanitized = stripTerminalEscapes(value).replace(CONTROL_CHAR_REGEXP, "").trim();
+  return sanitized || undefined;
+}
+
 export function codexHome(env = process.env, home = homedir()): string {
   return env.CODEX_HOME?.trim() || join(home, ".codex");
 }
@@ -82,24 +108,21 @@ function petInfoFromJson(
   value: unknown,
   fallback: string,
 ): { id?: string; name: string; description?: string; spritesheetPath: string } {
-  if (!isRecord(value)) return { name: fallback, spritesheetPath: "spritesheet.webp" };
-  const id = typeof value.id === "string" && value.id.trim() ? value.id.trim() : undefined;
+  const fallbackName = sanitizePetDisplayText(fallback) ?? "Unnamed pet";
+  if (!isRecord(value)) return { name: fallbackName, spritesheetPath: "spritesheet.webp" };
+  const id = typeof value.id === "string" ? sanitizePetDisplayText(value.id) : undefined;
   const displayName =
-    typeof value.displayName === "string" && value.displayName.trim()
-      ? value.displayName.trim()
-      : undefined;
+    typeof value.displayName === "string" ? sanitizePetDisplayText(value.displayName) : undefined;
   const name =
     displayName ??
-    (typeof value.name === "string" && value.name.trim() ? value.name.trim() : undefined) ??
+    (typeof value.name === "string" ? sanitizePetDisplayText(value.name) : undefined) ??
     id ??
-    fallback;
+    fallbackName;
   const description =
-    typeof value.description === "string" && value.description.trim()
-      ? value.description.trim()
-      : undefined;
+    typeof value.description === "string" ? sanitizePetDisplayText(value.description) : undefined;
   const spritesheetPath =
-    typeof value.spritesheetPath === "string" && value.spritesheetPath.trim()
-      ? value.spritesheetPath.trim()
+    typeof value.spritesheetPath === "string"
+      ? (sanitizePetAssetPathText(value.spritesheetPath) ?? "spritesheet.webp")
       : "spritesheet.webp";
   return { id, name, description, spritesheetPath };
 }
@@ -111,6 +134,48 @@ function resolvePetAssetPath(petDir: string, path: string): string | undefined {
   return resolved === resolvedPetDir || resolved.startsWith(prefix) ? resolved : undefined;
 }
 
+function formatSharpError(error: unknown): string {
+  return (
+    sanitizePetDisplayText(error instanceof Error ? error.message : String(error)) ??
+    "unknown error"
+  );
+}
+
+async function validatePetSpritesheet(
+  petDir: string,
+  spritesheetPath: string,
+): Promise<string | undefined> {
+  const resolvedSpritesheetPath = resolvePetAssetPath(petDir, spritesheetPath);
+  if (!resolvedSpritesheetPath)
+    return `invalid spritesheetPath outside pet folder: ${spritesheetPath}`;
+
+  let fileStat;
+  try {
+    fileStat = await stat(resolvedSpritesheetPath);
+  } catch {
+    return `missing ${spritesheetPath}`;
+  }
+
+  if (!fileStat.isFile()) return `${spritesheetPath} is not a file`;
+
+  try {
+    await access(resolvedSpritesheetPath, constants.R_OK);
+  } catch {
+    return `${spritesheetPath} is not readable`;
+  }
+
+  try {
+    const metadata = await sharp(resolvedSpritesheetPath, { animated: false }).metadata();
+    if (metadata.width !== EXPECTED_ATLAS_WIDTH || metadata.height !== EXPECTED_ATLAS_HEIGHT) {
+      return `invalid atlas dimensions: ${metadata.width ?? "?"}x${metadata.height ?? "?"}; expected ${EXPECTED_ATLAS_WIDTH}x${EXPECTED_ATLAS_HEIGHT}`;
+    }
+  } catch (error) {
+    return `could not read ${spritesheetPath}: ${formatSharpError(error)}`;
+  }
+
+  return undefined;
+}
+
 export async function listCodexPets(home = codexHome()): Promise<CodexPetPackage[]> {
   const dir = codexPetsDir(home);
   let entries: Dirent[];
@@ -131,16 +196,7 @@ export async function listCodexPets(home = codexHome()): Promise<CodexPetPackage
       continue;
     }
     const { id, name, description, spritesheetPath } = petInfoFromJson(parsed, entry.name);
-    let hasSpritesheet = false;
-    try {
-      const resolvedSpritesheetPath = resolvePetAssetPath(petDir, spritesheetPath);
-      if (resolvedSpritesheetPath) {
-        await access(resolvedSpritesheetPath);
-        hasSpritesheet = true;
-      }
-    } catch {
-      hasSpritesheet = false;
-    }
+    const spritesheetIssue = await validatePetSpritesheet(petDir, spritesheetPath);
     pets.push({
       slug: entry.name,
       id,
@@ -148,7 +204,8 @@ export async function listCodexPets(home = codexHome()): Promise<CodexPetPackage
       description,
       dir: petDir,
       spritesheetPath,
-      hasSpritesheet,
+      hasSpritesheet: spritesheetIssue === undefined,
+      spritesheetIssue,
     });
   }
   return pets.sort((a, b) => a.name.localeCompare(b.name));
@@ -222,7 +279,7 @@ export function describeCodexPetSelectionIssue(
         short: `Pet "${matchingPet.name}" is not ready.`,
         message: [
           `Pet "${matchingPet.name}" (${matchingPet.slug}) exists but is not ready.`,
-          `Missing or unreadable file: ${matchingPet.spritesheetPath}`,
+          `Problem: ${matchingPet.spritesheetIssue ?? `missing ${matchingPet.spritesheetPath}`}`,
           "",
           "Run /pets list for diagnostics, then fix the pet folder:",
           `  ${matchingPet.dir}/`,
@@ -266,7 +323,7 @@ export function formatNoReadyCodexPetsMessage(pets: CodexPetPackage[], home = co
   return [
     "Found custom Codex pets, but none are ready.",
     "",
-    "A ready pet needs both pet.json and spritesheet.webp in its pet folder.",
+    `A ready pet needs pet.json and a readable ${EXPECTED_ATLAS_WIDTH}x${EXPECTED_ATLAS_HEIGHT} spritesheet.webp atlas in its pet folder.`,
     "Run /pets list to see what needs fixing, or create a new pet:",
     "",
     formatCodexPetSetupInstructions(home),
@@ -292,12 +349,9 @@ export async function loadCodexPet(
     throw new Error(`Invalid spritesheetPath outside pet folder: ${pet.spritesheetPath}`);
   const source = sharp(spritesheetPath, { animated: false });
   const metadata = await source.metadata();
-  if (
-    metadata.width !== DEFAULT_CELL_WIDTH * PET_COLUMNS ||
-    metadata.height !== DEFAULT_CELL_HEIGHT * PET_ROWS
-  ) {
+  if (metadata.width !== EXPECTED_ATLAS_WIDTH || metadata.height !== EXPECTED_ATLAS_HEIGHT) {
     throw new Error(
-      `Invalid Codex pet atlas dimensions: ${metadata.width ?? "?"}x${metadata.height ?? "?"}; expected ${DEFAULT_CELL_WIDTH * PET_COLUMNS}x${DEFAULT_CELL_HEIGHT * PET_ROWS}.`,
+      `Invalid Codex pet atlas dimensions: ${metadata.width ?? "?"}x${metadata.height ?? "?"}; expected ${EXPECTED_ATLAS_WIDTH}x${EXPECTED_ATLAS_HEIGHT}.`,
     );
   }
   const cellWidth = DEFAULT_CELL_WIDTH;
@@ -401,20 +455,32 @@ export function nextAnimationFrameDelayMs(
   return Math.max(1, Math.ceil(frames[0]?.durationMs ?? 120));
 }
 
-const previousKittyFrameByPlacement = new Map<number, number>();
-
-export function resetCodexPetKittyCache(pet?: LoadedCodexPet, placementImageId?: number): void {
-  if (placementImageId !== undefined) previousKittyFrameByPlacement.delete(placementImageId);
+function markCodexPetKittyFramesUnuploaded(pet?: LoadedCodexPet): void {
   if (!pet) return;
   for (const frames of Object.values(pet.states)) {
     for (const frame of frames) frame.kittyUploaded = false;
   }
 }
 
+function codexPetKittyImageIds(pet?: LoadedCodexPet): number[] {
+  if (!pet) return [];
+  const imageIds = new Set<number>();
+  for (const frames of Object.values(pet.states)) {
+    for (const frame of frames) {
+      if (frame.kittyImageId !== undefined) imageIds.add(frame.kittyImageId);
+    }
+  }
+  return Array.from(imageIds);
+}
+
 export function deleteCodexPetKittyPlacement(imageId: number): string {
   return `\x1b_Ga=d,d=i,i=${imageId},p=1,q=2\x1b\\`;
 }
 
+export function deleteCodexPetKittyImage(imageId: number): string {
+  return `\x1b_Ga=d,d=I,i=${imageId},q=2\x1b\\`;
+}
+
 function placeKittyImage(imageId: number, columns: number, rows: number): string {
   return `\x1b_Ga=p,i=${imageId},p=1,c=${columns},r=${rows},q=2,C=1\x1b\\`;
 }
@@ -446,34 +512,95 @@ function encodeKittyRawRgba(frame: PetFrame, imageId: number): string {
   return chunks.join("");
 }
 
-function renderKittyPetFrame(
-  frame: PetFrame,
-  width: number,
-  options: { sizeCells: number; imageId: number },
-): string[] {
-  const columns = Math.max(1, Math.min(Math.max(1, width - 2), options.sizeCells));
-  const rows = calculateImageRows(
-    { widthPx: frame.widthPx, heightPx: frame.heightPx },
-    columns,
-    getCellDimensions(),
-  );
-  const frameImageId = frame.kittyImageId ?? options.imageId;
-  const previousFrameImageId = previousKittyFrameByPlacement.get(options.imageId);
-  const deletePrevious =
-    previousFrameImageId !== undefined && previousFrameImageId !== frameImageId
-      ? deleteCodexPetKittyPlacement(previousFrameImageId)
-      : "";
-  const deleteCurrent = deleteCodexPetKittyPlacement(frameImageId);
-  const upload = frame.kittyUploaded ? "" : encodeKittyRawRgba(frame, frameImageId);
-  frame.kittyUploaded = true;
-  previousKittyFrameByPlacement.set(options.imageId, frameImageId);
-  const sequence = `${deletePrevious}${deleteCurrent}${upload}${placeKittyImage(frameImageId, columns, rows)}`;
-  const lines: string[] = [];
-  for (let i = 0; i < rows - 1; i++) lines.push("");
-  const moveUp = rows > 1 ? `\x1b[${rows - 1}A` : "";
-  const moveDown = rows > 1 ? `\x1b[${rows - 1}B` : "";
-  lines.push(moveUp + sequence + moveDown);
-  return lines;
+export class CodexPetKittyManager {
+  private previousFrameImageId: number | undefined;
+  private readonly uploadedFrameImageIds = new Set<number>();
+  private readonly pendingCleanupImageIds = new Set<number>();
+
+  constructor(readonly placementImageId: number) {}
+
+  queueCleanup(pet?: LoadedCodexPet): void {
+    for (const imageId of codexPetKittyImageIds(pet)) this.pendingCleanupImageIds.add(imageId);
+  }
+
+  invalidate(pet?: LoadedCodexPet): void {
+    this.queueCleanup(pet);
+    this.previousFrameImageId = undefined;
+    this.uploadedFrameImageIds.clear();
+    markCodexPetKittyFramesUnuploaded(pet);
+  }
+
+  resetForResize(pet?: LoadedCodexPet): void {
+    this.invalidate(pet);
+  }
+
+  dispose(pet?: LoadedCodexPet): string {
+    this.invalidate(pet);
+    return this.takeCleanupSequence();
+  }
+
+  takeCleanupSequence(): string {
+    if (this.pendingCleanupImageIds.size === 0) return "";
+    const sequence = `${deleteCodexPetKittyPlacement(this.placementImageId)}${Array.from(
+      this.pendingCleanupImageIds,
+    )
+      .map((imageId) => deleteCodexPetKittyImage(imageId))
+      .join("")}`;
+    this.pendingCleanupImageIds.clear();
+    return sequence;
+  }
+
+  renderFrame(frame: PetFrame, width: number, options: { sizeCells: number }): string[] {
+    const columns = Math.max(1, Math.min(Math.max(1, width - 2), options.sizeCells));
+    const rows = calculateImageRows(
+      { widthPx: frame.widthPx, heightPx: frame.heightPx },
+      columns,
+      getCellDimensions(),
+    );
+    const frameImageId = frame.kittyImageId ?? this.placementImageId;
+    const deletePrevious =
+      this.previousFrameImageId !== undefined && this.previousFrameImageId !== frameImageId
+        ? deleteCodexPetKittyPlacement(this.previousFrameImageId)
+        : "";
+    const deleteCurrent = deleteCodexPetKittyPlacement(frameImageId);
+    const upload = this.uploadedFrameImageIds.has(frameImageId)
+      ? ""
+      : encodeKittyRawRgba(frame, frameImageId);
+    this.uploadedFrameImageIds.add(frameImageId);
+    frame.kittyUploaded = true;
+    this.previousFrameImageId = frameImageId;
+    // Recent pi-tui versions automatically free Kitty image IDs they own on changed lines.
+    // Pet frames are managed here and intentionally reused across animation loops, so keep
+    // the first Kitty command pointed at a harmless footer-placement ID, not a frame ID.
+    const hostCleanupSentinel =
+      frameImageId !== this.placementImageId
+        ? deleteCodexPetKittyPlacement(this.placementImageId)
+        : "";
+    const sequence = `${hostCleanupSentinel}${deletePrevious}${deleteCurrent}${upload}${placeKittyImage(frameImageId, columns, rows)}`;
+    const lines: string[] = [];
+    for (let i = 0; i < rows - 1; i++) lines.push("");
+    const moveUp = rows > 1 ? `\x1b[${rows - 1}A` : "";
+    const moveDown = rows > 1 ? `\x1b[${rows - 1}B` : "";
+    lines.push(moveUp + sequence + moveDown);
+    return lines;
+  }
+}
+
+const defaultKittyManagers = new Map<number, CodexPetKittyManager>();
+
+function defaultKittyManager(placementImageId: number): CodexPetKittyManager {
+  let manager = defaultKittyManagers.get(placementImageId);
+  if (!manager) {
+    manager = new CodexPetKittyManager(placementImageId);
+    defaultKittyManagers.set(placementImageId, manager);
+  }
+  return manager;
+}
+
+export function resetCodexPetKittyCache(pet?: LoadedCodexPet, placementImageId?: number): void {
+  if (placementImageId !== undefined) defaultKittyManagers.get(placementImageId)?.invalidate(pet);
+  else for (const manager of defaultKittyManagers.values()) manager.invalidate(pet);
+  markCodexPetKittyFramesUnuploaded(pet);
 }
 
 export function renderCodexPetFrame(
@@ -481,7 +608,13 @@ export function renderCodexPetFrame(
   state: PetState,
   width: number,
   theme: ThemeLike,
-  options: { sizeCells: number; imageId: number; now?: number; durationMultiplier?: number },
+  options: {
+    sizeCells: number;
+    imageId: number;
+    now?: number;
+    durationMultiplier?: number;
+    kittyManager?: CodexPetKittyManager;
+  },
 ): string[] {
   const frame = animationFrameAt(
     pet.states[state] ?? pet.states.idle,
@@ -490,7 +623,15 @@ export function renderCodexPetFrame(
   );
   if (!frame) return [];
   const imageProtocol = getCapabilities().images;
-  if (imageProtocol === "kitty") return renderKittyPetFrame(frame, width, options);
+  if (imageProtocol === "kitty") {
+    return (options.kittyManager ?? defaultKittyManager(options.imageId)).renderFrame(
+      frame,
+      width,
+      {
+        sizeCells: options.sizeCells,
+      },
+    );
+  }
   if (!imageProtocol) {
     const fallback = imageFallback(frame.mimeType, {
       widthPx: frame.widthPx,
@@ -540,7 +681,7 @@ const PET_SUBCOMMANDS: AutocompleteItem[] = [
 ];
 
 function petCompletionValue(subcommand: string, pet: CodexPetPackage): string {
-  return `${subcommand} ${pet.name}`;
+  return `${subcommand} ${pet.slug}`;
 }
 
 export async function openAIPetsArgumentCompletions(
@@ -585,7 +726,9 @@ export function formatCodexPetsListMessage(pets: CodexPetPackage[], home = codex
 
   const petLines = pets
     .map((pet) => {
-      const status = pet.hasSpritesheet ? "ready" : `missing ${pet.spritesheetPath}`;
+      const status = pet.hasSpritesheet
+        ? "ready"
+        : (pet.spritesheetIssue ?? `missing ${pet.spritesheetPath}`);
       return `${pet.name} (${pet.slug}) — ${status}${pet.description ? `\n  ${pet.description}` : ""}`;
     })
     .join("\n");