@hayasaka7/haya-pet 0.2.8 → 0.3.1

package/CHANGELOG.md

@@ -7,6 +7,38 @@ All notable changes to HAYA Pet are documented here. This project adheres to
 > 0.2.0 npm publish; they are listed under 0.2.1, which is the first version that
 > ships them.
 
+## [0.3.1]
+
+### Fixed
+- **Clicks pass through the empty space around the pet.** The overlay used the
+  pet's whole rectangular sprite cell as its click target, so the transparent
+  margins around the character still swallowed clicks meant for the window
+  behind it. The pet now intercepts the mouse only where the current frame
+  actually has opaque pixels — sampled live from the canvas, with no per-frame
+  cost — so the catch area hugs the visible silhouette. The resize grip is
+  unaffected: it still reveals and works across the pet's full bounding box.
+- **Interrupting a turn no longer leaves the pet stuck "thinking".** When you
+  press Esc while the agent is working — especially mid-thought, with no tool
+  running — neither Claude Code nor Codex fires a hook (`Stop` only fires on a
+  normal turn end), so the pet kept spinning on *thinking* until the 30 s stale
+  sweep. The transcript watchers now recognise each client's interrupt marker
+  (Claude's `[Request interrupted by user]` message; Codex's `turn_aborted`
+  record) and report a new `interrupted` status — a red ✕ that, unlike a real
+  failure, is **not** treated as a finished session, so the bubble stays put
+  (the session is still alive) instead of disappearing, and returns to the live
+  status as soon as you continue.
+
+## [0.3.0]
+
+### Fixed
+- **A fresh install now shows a real pet.** The package has always shipped a
+  ready-to-use pet (`assets/fallback-pet`), but discovery only scanned the
+  user's pet folders (`~/.codex/pets`, `~/.haya-pet/pets`), so a new user with
+  no pets got a blue "dev placeholder" box and an empty pet list instead. The
+  bundled pet is now composed into discovery as a last resort — appended after
+  any of the user's own pets (which still win and stay the default) and deduped
+  by id — so the overlay always renders a real character out of the box.
+
 ## [0.2.8]
 
 ### Fixed

package/apps/cli/src/haya-pet.js

@@ -14,7 +14,7 @@ import { watchCodexGuardianReviews as defaultWatchCodexGuardianReviews } from ".
 import { ensureCompanionConnection } from "../../../packages/cli-core/src/companion-launcher.js";
 import { createIpcClient as defaultCreateIpcClient } from "../../../packages/daemon-core/src/ipc-server.js";
 import { getDefaultPaths } from "../../../packages/platform-core/src/paths.js";
-import { discoverPets as defaultDiscoverPets } from "../../../packages/pet-core/src/discovery.js";
+import { discoverPetsWithFallback as defaultDiscoverPets } from "../../../packages/pet-core/src/discovery.js";
 import { createStateFile as defaultCreateStateFile } from "../../../packages/app-state/src/state-file.js";
 import { getSelectedPetId, setSelectedPet, getHooksEnabled, setHooksEnabled } from "../../../packages/app-state/src/state.js";
 import { checkForUpdate, UPDATE_COMMAND } from "../../../packages/app-state/src/update-check.js";
@@ -241,6 +241,22 @@ async function runRunCommand(parsed, dependencies) {
             updatedAt: now()
           })
           .catch(() => {});
+      },
+      // Esc-interrupt fires no Stop hook, so without this the pet stays stuck on
+      // "thinking"/"running". The transcript's interrupt marker is the only signal.
+      onInterrupt: () => {
+        hookDebugLog(env, now, { source: "transcript", event: "interrupted", state: "interrupted" });
+        messageSender
+          .send({
+            type: "state",
+            sessionId,
+            state: "interrupted",
+            summary: "interrupted",
+            confidence: 0.9,
+            source: "client_log",
+            updatedAt: now()
+          })
+          .catch(() => {});
       }
     });
     stopWatcher = watcher.stop;
@@ -277,6 +293,24 @@ async function runRunCommand(parsed, dependencies) {
             state: event.state
           });
 
+          // Esc-interrupt fires no Stop hook, so without this the pet stays stuck
+          // on "thinking"/"running" until the stale sweep.
+          if (event.type === "turn_aborted") {
+            activeToolCalls.clear();
+            messageSender
+              .send({
+                type: "state",
+                sessionId,
+                state: "interrupted",
+                summary: "interrupted",
+                confidence: 0.9,
+                source: "client_log",
+                updatedAt: now()
+              })
+              .catch(() => {});
+            return;
+          }
+
           if (event.type === "tool_started") {
             activeToolCalls.add(event.toolCallId);
             messageSender

package/apps/cli/test/haya-pet.test.mjs

@@ -683,6 +683,56 @@ test("a transcript denial clears the stuck approval to idle", async () => {
   assert.equal(idle.updatedAt, 42);
 });
 
+test("a transcript interrupt reports a failed status for Claude", async () => {
+  const sent = [];
+  let fireInterrupt;
+  await runAiPet(["run", "--client", "claude-code", "--", "claude"], {
+    cwd: process.cwd(),
+    env: { HAYA_PET_HOOKS: "1", USERPROFILE: "C:\\Users\\A" },
+    now: () => 42,
+    heartbeatIntervalMs: 10,
+    send: async (message) => sent.push(message),
+    injectClaudeHooks: () => ({ settingsPath: "/tmp/s.json", cleanup: () => {} }),
+    watchClaudeTranscript: ({ onInterrupt }) => { fireInterrupt = onInterrupt; return { stop: () => {} }; },
+    runGenericCommand: async (options) => {
+      // Simulate the user pressing Esc to interrupt mid-turn.
+      fireInterrupt({ type: "interrupted" });
+      return { sessionId: options.sessionId, pid: 1, exitCode: 0 };
+    }
+  });
+
+  const interrupted = sent.find((m) => m.type === "state" && m.source === "client_log");
+  assert.ok(interrupted, "a client_log state was sent on interrupt");
+  assert.equal(interrupted.state, "interrupted");
+  assert.equal(interrupted.summary, "interrupted");
+  assert.equal(interrupted.updatedAt, 42);
+});
+
+test("a transcript turn_aborted reports a failed status for Codex", async () => {
+  const sent = [];
+  let fireToolEvent;
+  await runAiPet(["run", "--client", "codex", "--", "codex"], {
+    cwd: process.cwd(),
+    env: { USERPROFILE: "C:\\Users\\A" },
+    now: () => 42,
+    heartbeatIntervalMs: 10,
+    send: async (message) => sent.push(message),
+    createStateFile: hooksStateFile(true),
+    injectCodexHooks: () => ({ profileName: "haya-pet", cleanup: () => {} }),
+    watchCodexTranscript: ({ onToolEvent }) => { fireToolEvent = onToolEvent; return { stop: () => {} }; },
+    runGenericCommand: async (options) => {
+      // Simulate the user pressing Esc: Codex writes a turn_aborted record.
+      fireToolEvent({ type: "turn_aborted", reason: "interrupted" });
+      return { sessionId: options.sessionId, pid: 1, exitCode: 0 };
+    }
+  });
+
+  const interrupted = sent.find((m) => m.type === "state" && m.source === "client_log" && m.state === "interrupted");
+  assert.ok(interrupted, "a client_log interrupted state was sent on turn_aborted");
+  assert.equal(interrupted.summary, "interrupted");
+  assert.equal(interrupted.updatedAt, 42);
+});
+
 test("non-hook-capable clients are never injected even with HAYA_PET_HOOKS=1", async () => {
   const calls = [];
   await runAiPet(["run", "--client", "generic", "--", "aider"], {

package/apps/companion/src/main/index.js

@@ -18,7 +18,7 @@ import { resolveSavedPosition } from "./display-manager.js";
 import { getPetScale, setPetScale, setSelectedPet, updateGlobalPetPosition } from "./position-store.js";
 import { buildTrayMenu, buildTrayTooltip } from "./tray-menu.js";
 import { createStateFile } from "./state-file.js";
-import { discoverPets } from "./pet-loader.js";
+import { discoverPetsWithFallback } from "./pet-loader.js";
 import { checkForUpdate, UPDATE_PAGE_URL } from "../../../../packages/app-state/src/update-check.js";
 
 const STALE_SWEEP_INTERVAL_MS = 10_000;
@@ -67,7 +67,7 @@ if (!app.requestSingleInstanceLock()) {
 async function bootstrap() {
   positionState = await stateFile.load();
   petScale = clampScale(getPetScale(positionState));
-  pets = await discoverPets(paths.petSearchPaths);
+  pets = await discoverPetsWithFallback(paths.petSearchPaths);
 
   // Clients fire no event at the moment the user ACCEPTS a permission prompt
   // (only denial/finish are observable), so a waiting_approval session would

package/apps/companion/src/main/pet-loader.js

@@ -1,2 +1,6 @@
 // Re-exported from pet-core so the companion and CLI share one discovery path.
-export { discoverPets, loadPetFromDir } from "../../../../packages/pet-core/src/discovery.js";
+export {
+  discoverPets,
+  discoverPetsWithFallback,
+  loadPetFromDir
+} from "../../../../packages/pet-core/src/discovery.js";

package/apps/companion/src/renderer/pet-hit-test.js

@@ -0,0 +1,23 @@
+// Pure helpers for the pet's pixel-precise click-through. The browser glue in
+// pet-window.js supplies the live pixel alpha and the canvas bounding box; these
+// functions hold the (testable) decisions.
+
+// Default minimum alpha for a pixel to count as "the pet" rather than the
+// transparent margin of its sprite cell. A small threshold ignores faint
+// anti-aliased edges so the click-through hugs the visible silhouette.
+export const DEFAULT_ALPHA_THRESHOLD = 16;
+
+// Top-left inclusive, bottom-right exclusive — matches canvas pixel indexing so
+// the same predicate works for both bounding-box and per-pixel tests.
+export function isPointInsideRect(point, rect) {
+  return (
+    point.x >= rect.left &&
+    point.x < rect.right &&
+    point.y >= rect.top &&
+    point.y < rect.bottom
+  );
+}
+
+export function isOpaqueAlpha(alpha, threshold = DEFAULT_ALPHA_THRESHOLD) {
+  return alpha >= threshold;
+}

package/apps/companion/src/renderer/pet-window.js

@@ -19,12 +19,15 @@ import { resolvePanelPlacement } from "../main/panel-placement.js";
 import { resolveBubbleListMaxHeight } from "../main/bubble-list-viewport.js";
 import { createInteractionController } from "./interaction-controller.js";
 import { createBubbleList } from "./session-bubbles.js";
+import { isOpaqueAlpha, isPointInsideRect } from "./pet-hit-test.js";
 
 const bridge = window.aiPet;
 const petEl = document.getElementById("pet");
 const canvas = document.getElementById("pet-canvas");
 const gripEl = document.getElementById("pet-resize-grip");
-const ctx = canvas.getContext("2d");
+// willReadFrequently: the click-through hit-test samples a single pixel on every
+// pointer move (see pointerHitsPetPixel), so keep the canvas CPU-backed.
+const ctx = canvas.getContext("2d", { willReadFrequently: true });
 const panelEl = document.getElementById("bubbles");
 
 // The sprite's natural cell size; the canvas is this times the user's scale.
@@ -190,6 +193,10 @@ function playOneShot(action) {
 
 canvas.addEventListener("pointerdown", (event) => {
   canvas.setPointerCapture(event.pointerId);
+  // Hold click-through off for the whole press: a drag swaps to the running
+  // frames, whose opaque pixels differ from the grabbed one, so re-running the
+  // pixel test mid-gesture could flip the window to pass-through and drop it.
+  petPressed = true;
   dragOffset = { x: event.offsetX, y: event.offsetY };
   // Window-local (clientX/Y) coords throughout — the overlay covers the work area.
   controller.pointerDown({ x: event.clientX, y: event.clientY, time: performance.now() });
@@ -206,11 +213,18 @@ canvas.addEventListener("pointermove", (event) => {
 canvas.addEventListener("pointerup", (event) => {
   // Click / double-click are delivered asynchronously via onAction; only the
   // synchronous drag-end is handled here.
+  petPressed = false;
   const result = controller.pointerUp({ x: event.clientX, y: event.clientY, time: performance.now() });
   if (result?.type === "drag-end") {
     animationState = clearDragAction(animationState);
     bridge?.savePetPosition?.(petLocal);
   }
+  refreshMouseIgnore(event.clientX, event.clientY);
+});
+
+canvas.addEventListener("pointercancel", () => {
+  petPressed = false;
+  animationState = clearDragAction(animationState);
 });
 
 // --- Resize grip: drag to scale the pet, double-click to reset ---
@@ -310,23 +324,54 @@ function renderBubbles() {
 // The overlay window covers a large area but should only intercept the mouse
 // over the pet and the bubble chips; everywhere else must pass through to the
 // desktop. The window is created ignoring mouse events (with forwarding), and
-// we flip it back on whenever the cursor is over an `.interactive` element.
+// we flip it back on whenever the cursor is over an `.interactive` element. Over
+// the pet canvas we go further and only intercept where the sprite has opaque
+// pixels, so the transparent margins of the cell pass clicks through too.
 
 let mouseIgnored;
+let petPressed = false; // a press/drag is in progress on the pet canvas
 let lastPointer = { x: -1, y: -1 };
 
+// True when the cursor is over a non-transparent pixel of the current frame. The
+// canvas already holds the current frame at the current scale, so sampling it
+// directly needs no atlas math. (Electron lets us read a file://-drawn canvas;
+// if a future version ever taints it, getImageData throws and we fall back to
+// treating the whole canvas box as interactive.)
+function pointerHitsPetPixel(x, y) {
+  if (!spritesheet) {
+    return true; // dev placeholder has no sprite: keep the whole box interactive
+  }
+  const rect = canvas.getBoundingClientRect();
+  if (!isPointInsideRect({ x, y }, rect)) {
+    return false;
+  }
+  const lx = Math.floor(x - rect.left);
+  const ly = Math.floor(y - rect.top);
+  try {
+    return isOpaqueAlpha(ctx.getImageData(lx, ly, 1, 1).data[3]);
+  } catch {
+    return true; // tainted canvas: degrade to full-box interactivity
+  }
+}
+
 function refreshMouseIgnore(x, y) {
   // While the grip is captured, the pointer can briefly leave it (the pet only
   // approximately tracks the diagonal); flipping click-through mid-drag would
-  // drop the pointerup, so hold interaction until the drag ends.
-  if (resizeDrag) {
+  // drop the pointerup, so hold interaction until the drag ends. The same holds
+  // for a press/drag on the pet body (petPressed).
+  if (resizeDrag || petPressed) {
     return;
   }
   if (!Number.isFinite(x) || !Number.isFinite(y)) {
     return;
   }
-  const target = document.elementFromPoint(x, y);
-  const interactive = Boolean(target && target.closest(".interactive"));
+  const interactiveEl = document.elementFromPoint(x, y)?.closest(".interactive");
+  let interactive = Boolean(interactiveEl);
+  // Pixel precision applies only to the pet body; the grip and bubbles (their
+  // own .interactive elements) keep their full hit area.
+  if (interactiveEl === canvas) {
+    interactive = pointerHitsPetPixel(x, y);
+  }
   const ignore = !interactive;
   if (ignore !== mouseIgnored) {
     mouseIgnored = ignore;
@@ -334,9 +379,20 @@ function refreshMouseIgnore(x, y) {
   }
 }
 
+// The resize grip reveals whenever the cursor is over the pet's bounding box —
+// the same judgement as before — kept independent of the pixel-precise
+// click-through so passing clicks through transparent areas never hides it. The
+// window forwards move events even while click-through is on, so this stays
+// accurate over transparent (passed-through) areas too.
+function refreshGripVisibility(x, y) {
+  const inside = Number.isFinite(x) && Number.isFinite(y) && isPointInsideRect({ x, y }, canvas.getBoundingClientRect());
+  petEl.classList.toggle("show-grip", inside || Boolean(resizeDrag));
+}
+
 window.addEventListener("mousemove", (event) => {
   lastPointer = { x: event.clientX, y: event.clientY };
   refreshMouseIgnore(event.clientX, event.clientY);
+  refreshGripVisibility(event.clientX, event.clientY);
 });
 
 if (bridge) {

package/apps/companion/src/renderer/styles.css

@@ -61,7 +61,10 @@ body {
   transition: opacity 0.15s ease;
 }
 
-#pet:hover .resize-grip,
+/* .show-grip is toggled by pet-window.js based on the pet's bounding box, so the
+   grip's reveal is independent of the pixel-precise click-through (which would
+   otherwise hide it over the sprite's transparent corners). */
+#pet.show-grip .resize-grip,
 .resize-grip.active {
   opacity: 1;
 }

package/apps/companion/test/pet-hit-test.test.mjs

@@ -0,0 +1,30 @@
+import assert from "node:assert/strict";
+import { test } from "../../../test/harness.mjs";
+import { isOpaqueAlpha, isPointInsideRect } from "../src/renderer/pet-hit-test.js";
+
+const RECT = { left: 10, top: 20, right: 110, bottom: 220 };
+
+test("isPointInsideRect includes the top-left edge and excludes the bottom-right", () => {
+  assert.equal(isPointInsideRect({ x: 10, y: 20 }, RECT), true); // top-left corner is inside
+  assert.equal(isPointInsideRect({ x: 60, y: 120 }, RECT), true); // centre
+  assert.equal(isPointInsideRect({ x: 110, y: 120 }, RECT), false); // right edge is exclusive
+  assert.equal(isPointInsideRect({ x: 60, y: 220 }, RECT), false); // bottom edge is exclusive
+});
+
+test("isPointInsideRect rejects points outside the box", () => {
+  assert.equal(isPointInsideRect({ x: 9, y: 120 }, RECT), false);
+  assert.equal(isPointInsideRect({ x: 60, y: 19 }, RECT), false);
+  assert.equal(isPointInsideRect({ x: 200, y: 300 }, RECT), false);
+});
+
+test("isOpaqueAlpha compares against the threshold (default 16)", () => {
+  assert.equal(isOpaqueAlpha(255), true);
+  assert.equal(isOpaqueAlpha(16), true); // threshold is inclusive
+  assert.equal(isOpaqueAlpha(15), false);
+  assert.equal(isOpaqueAlpha(0), false);
+});
+
+test("isOpaqueAlpha honours a custom threshold", () => {
+  assert.equal(isOpaqueAlpha(120, 128), false);
+  assert.equal(isOpaqueAlpha(128, 128), true);
+});

package/docs/architecture.md

@@ -99,9 +99,16 @@ L2/PTY tradeoffs.
 
 The overlay is a transparent, always-on-top window spanning the work area, kept
 click-through except over the pet and bubble chips (via `setIgnoreMouseEvents`
-with mouse-move forwarding). The pet is positioned inside the window and dragged
-via CSS; the bubble panel is placed on whichever side of the pet has room so it
-stays fully on-screen. The pet currently lives on a single display's work area.
+with mouse-move forwarding). Over the pet the hit test is **pixel-precise**: the
+renderer samples the live canvas (`getImageData`) at the cursor and only
+intercepts where the current frame has opaque pixels, so the transparent margins
+of the sprite cell pass clicks through too. The press/drag is held interactive
+for its whole duration (the running frames have a different silhouette), and the
+resize grip keeps its own bounding-box reveal so pixel precision never hides it
+(`pet-hit-test.js`, `pet-window.js`). The pet is positioned inside the window and
+dragged via CSS; the bubble panel is placed on whichever side of the pet has room
+so it stays fully on-screen. The pet currently lives on a single display's work
+area.
 
 The bubble panel shows at most three sessions and scrolls for the rest (capped
 by the smaller of a height budget and a count budget, see

package/docs/known-issues.md

@@ -103,6 +103,32 @@ Issues found in live use, with their current status.
   `Notification` hook by type (`permission_prompt`→approval, `idle_prompt`→idle) so
   non-approval notifications no longer masquerade as approvals.
 
+## ✅ Resolved: pet stuck on "thinking" after an Esc interrupt
+
+- **Symptom:** With hooks enabled, pressing Esc to interrupt the agent — most
+  visibly while it was *thinking* with no tool running — left the pet spinning on
+  *thinking* (or *running*) until the 30 s stale sweep, instead of showing the
+  turn was cut short. Affected both Claude Code and Codex.
+- **Root cause:** Neither client fires a hook on an interrupt. `Stop` fires only
+  on a *normal* turn end, so the hook-driven status had no event to leave the
+  working state. A timeout was rejected (same reasoning as the denial case — it
+  would misreport a genuinely long turn).
+- **Fix:** The existing **L3 transcript watchers** already tail each client's
+  session JSONL, so they now also recognise the interrupt marker each client
+  *does* write — ground truth, not a timer. Claude records a synthetic user
+  message `[Request interrupted by user]` (and `…for tool use]`); Codex records
+  an `event_msg` with `payload.type: "turn_aborted"`. On seeing it the wrapper
+  reports a dedicated **`interrupted`** state (summary "interrupted", source
+  `client_log`).
+- **Why a new state, not `failed`:** the first attempt reported `failed`, which
+  *looked* right (red ✕) but is in `bubble-linger.js`'s `ENDED_STATES`, so the
+  linger logic treated the interrupt as a finished session and **hid the bubble
+  after ~2 s** — even though the session was still alive (no unregister on an
+  interrupt). `interrupted` maps to the same red ✕ kind and the same one-shot pet
+  reaction as `failed`, but is **not** terminal (not in `ENDED_STATES` or the
+  pet's `TERMINAL_STATES`), so the bubble stays visible until the next turn (or a
+  real exit). Heartbeats keep it from going stale.
+
 ## ✅ Resolved: pet stuck on "waiting for approval" after the user ACCEPTS
 
 - **Symptom:** The denial fix above covered "deny", but **accepting** a prompt

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hayasaka7/haya-pet",
-  "version": "0.2.8",
+  "version": "0.3.1",
   "type": "module",
   "description": "Generic AI CLI pet runtime foundation.",
   "keywords": [

package/packages/adapters/src/claude-transcript.js

@@ -17,6 +17,12 @@ const REJECTION_MARKERS = Object.freeze([
   "user chose not to"
 ]);
 
+// When the user presses Esc, Claude fires no Stop hook — it writes a synthetic
+// USER message carrying this marker (e.g. "[Request interrupted by user]" or
+// "[Request interrupted by user for tool use]"). That's the only signal the turn
+// was aborted, so the pet doesn't stay stuck on "thinking"/"running".
+const INTERRUPT_MARKER = "request interrupted by user";
+
 // Returns a resolution event for a single transcript line, or undefined.
 // Currently we only surface denials — the approve path is already covered by the
 // PostToolUse hook, and emitting on every result would race with it.
@@ -33,6 +39,8 @@ export function parseTranscriptLine(line) {
     return undefined;
   }
 
+  const isUserMessage = entry?.message?.role === "user";
+
   for (const block of content) {
     if (block?.type === "tool_result" && block.is_error === true) {
       const text = extractText(block.content).toLowerCase();
@@ -40,6 +48,14 @@ export function parseTranscriptLine(line) {
         return { type: "tool_denied", toolUseId: block.tool_use_id };
       }
     }
+
+    // Only a user message carries the synthetic interrupt marker; guarding on the
+    // role avoids matching the assistant merely quoting the phrase.
+    if (block?.type === "text" && isUserMessage) {
+      if (extractText(block).toLowerCase().includes(INTERRUPT_MARKER)) {
+        return { type: "interrupted" };
+      }
+    }
   }
 
   return undefined;

package/packages/adapters/src/codex-transcript.js

@@ -12,12 +12,12 @@ export function parseCodexTranscriptLine(line, options = {}) {
     return undefined;
   }
 
-  if (entry?.type !== "response_item") {
+  if (!entry || typeof entry !== "object") {
     return undefined;
   }
 
   // Skip records from before the current session (used when replaying a
-  // freshly-discovered transcript so an earlier session's tool calls don't
+  // freshly-discovered transcript so an earlier session's events don't
   // masquerade as live activity). Records without a parseable timestamp are
   // kept — losing live events is worse than a rare stale one.
   const minTimestampMs = options.minTimestampMs ?? 0;
@@ -33,6 +33,17 @@ export function parseCodexTranscriptLine(line, options = {}) {
     return undefined;
   }
 
+  // The user pressing Esc aborts the turn. Codex fires no Stop hook on an abort,
+  // so this event_msg is the only signal the turn ended by interruption — without
+  // it the pet stays stuck on "thinking" until the stale sweep.
+  if (entry.type === "event_msg" && payload.type === "turn_aborted") {
+    return { type: "turn_aborted", reason: typeof payload.reason === "string" ? payload.reason : undefined };
+  }
+
+  if (entry.type !== "response_item") {
+    return undefined;
+  }
+
   if (payload.type === "function_call" || payload.type === "custom_tool_call") {
     const toolName = typeof payload.name === "string" ? payload.name : undefined;
     const toolCallId = typeof payload.call_id === "string" ? payload.call_id : undefined;

package/packages/adapters/test/claude-transcript.test.mjs

@@ -68,3 +68,41 @@ test("parseTranscriptLines collects only denial events from a batch", () => {
     { type: "tool_denied", toolUseId: "toolu_b" }
   ]);
 });
+
+function interruptLine(text = "[Request interrupted by user]") {
+  return JSON.stringify({
+    type: "user",
+    message: { role: "user", content: [{ type: "text", text }] },
+    interruptedMessageId: "msg_1"
+  });
+}
+
+test("parseTranscriptLine detects a user interrupt during text generation", () => {
+  assert.deepEqual(parseTranscriptLine(interruptLine()), { type: "interrupted" });
+});
+
+test("parseTranscriptLine detects a user interrupt during tool use", () => {
+  assert.deepEqual(
+    parseTranscriptLine(interruptLine("[Request interrupted by user for tool use]")),
+    { type: "interrupted" }
+  );
+});
+
+test("parseTranscriptLine ignores the interrupt phrase quoted by the assistant", () => {
+  const line = JSON.stringify({
+    message: { role: "assistant", content: [{ type: "text", text: "Earlier you saw [Request interrupted by user]." }] }
+  });
+  assert.equal(parseTranscriptLine(line), undefined);
+});
+
+test("parseTranscriptLine ignores a normal user prompt", () => {
+  const line = JSON.stringify({ message: { role: "user", content: [{ type: "text", text: "fix this bug" }] } });
+  assert.equal(parseTranscriptLine(line), undefined);
+});
+
+test("parseTranscriptLines collects interrupt events alongside denials", () => {
+  assert.deepEqual(parseTranscriptLines([interruptLine(), rejectionLine("toolu_z")]), [
+    { type: "interrupted" },
+    { type: "tool_denied", toolUseId: "toolu_z" }
+  ]);
+});

package/packages/adapters/test/codex-transcript.test.mjs

@@ -95,3 +95,25 @@ test("parseCodexTranscriptLines can skip records older than the session start",
     }
   ]);
 });
+
+test("parseCodexTranscriptLine detects a user-interrupted turn", () => {
+  const event = parseCodexTranscriptLine(JSON.stringify({
+    type: "event_msg",
+    payload: { type: "turn_aborted", reason: "interrupted" }
+  }));
+
+  assert.deepEqual(event, { type: "turn_aborted", reason: "interrupted" });
+});
+
+test("parseCodexTranscriptLine skips a turn_aborted older than the session start", () => {
+  const old = JSON.stringify({
+    timestamp: "2026-06-08T10:59:59.000Z",
+    type: "event_msg",
+    payload: { type: "turn_aborted", reason: "interrupted" }
+  });
+
+  assert.equal(
+    parseCodexTranscriptLine(old, { minTimestampMs: Date.parse("2026-06-08T11:00:00.000Z") }),
+    undefined
+  );
+});

package/packages/cli-core/src/claude-transcript-watcher.js

@@ -34,6 +34,7 @@ export function watchClaudeTranscript(options = {}) {
     homeDir = process.env.USERPROFILE || process.env.HOME,
     startedAt = 0,
     onDenial = () => {},
+    onInterrupt = () => {},
     pollIntervalMs = DEFAULT_POLL_MS,
     projectsRoot,
     transcriptPath: fixedPath,
@@ -82,6 +83,8 @@ export function watchClaudeTranscript(options = {}) {
       for (const event of parseTranscriptLines(lines)) {
         if (event.type === "tool_denied") {
           onDenial(event);
+        } else if (event.type === "interrupted") {
+          onInterrupt(event);
         }
       }
     } catch {

package/packages/cli-core/test/claude-transcript-watcher.test.mjs

@@ -17,6 +17,14 @@ function rejection(toolUseId) {
   })}\n`;
 }
 
+function interrupt() {
+  return `${JSON.stringify({
+    type: "user",
+    message: { role: "user", content: [{ type: "text", text: "[Request interrupted by user]" }] },
+    interruptedMessageId: "msg_1"
+  })}\n`;
+}
+
 test("claudeProjectDirName sanitizes drive + separators like Claude does", () => {
   assert.equal(claudeProjectDirName("D:\\Projects\\AI\\haya-pet"), "D--Projects-AI-haya-pet");
   assert.equal(claudeProjectDirName("/home/a/proj"), "-home-a-proj");
@@ -119,3 +127,23 @@ test("watchClaudeTranscript handles a line split across two appends", () => {
 
   watcher.stop();
 });
+
+test("watchClaudeTranscript reports an interrupt appended after it starts tailing", () => {
+  const dir = mkdtempSync(join(tmpdir(), "transcript-"));
+  const path = join(dir, "session.jsonl");
+  writeFileSync(path, "");
+
+  const interrupts = [];
+  const watcher = watchClaudeTranscript({
+    transcriptPath: path,
+    onInterrupt: (event) => interrupts.push(event),
+    ...noopTimers
+  });
+  watcher._tick();
+
+  appendFileSync(path, interrupt());
+  watcher._tick();
+  assert.deepEqual(interrupts, [{ type: "interrupted" }]);
+
+  watcher.stop();
+});

package/packages/cli-core/test/codex-transcript-watcher.test.mjs

@@ -15,6 +15,14 @@ function toolStart(toolName = "shell_command", callId = "call_1", timestamp) {
   })}\n`;
 }
 
+function turnAborted(timestamp) {
+  return `${JSON.stringify({
+    ...(timestamp ? { timestamp } : {}),
+    type: "event_msg",
+    payload: { type: "turn_aborted", reason: "interrupted" }
+  })}\n`;
+}
+
 test("discoverCodexTranscript finds the newest session jsonl under date folders", () => {
   const root = mkdtempSync(join(tmpdir(), "codex-sessions-"));
   const oldDir = join(root, "2026", "06", "07");
@@ -106,3 +114,24 @@ test("watchCodexTranscript replays current-session records when a transcript is
 
   watcher.stop();
 });
+
+test("watchCodexTranscript forwards a turn_aborted interrupt event", () => {
+  const dir = mkdtempSync(join(tmpdir(), "codex-transcript-"));
+  const path = join(dir, "session.jsonl");
+  writeFileSync(path, "");
+
+  const events = [];
+  const watcher = watchCodexTranscript({
+    transcriptPath: path,
+    onToolEvent: (event) => events.push(event),
+    ...noopTimers
+  });
+
+  watcher._tick();
+  appendFileSync(path, turnAborted());
+  watcher._tick();
+
+  assert.deepEqual(events, [{ type: "turn_aborted", reason: "interrupted" }]);
+
+  watcher.stop();
+});

package/packages/pet-core/src/atlas.js

@@ -39,6 +39,7 @@ const AI_STATE_TO_PET_ACTION = Object.freeze({
   reviewing: "review",
   compacting: "review",
   failed: "failed",
+  interrupted: "failed",
   success: "jumping",
   stale: "waiting",
   exited: "jumping"

package/packages/pet-core/src/discovery.js

@@ -1,6 +1,6 @@
 import { readdir as fsReaddir, readFile as fsReadFile, stat as fsStat } from "node:fs/promises";
-import { join } from "node:path";
-import { pathToFileURL } from "node:url";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { parsePetManifest } from "./manifest.js";
 
 // Scans pet search paths for Codex-compatible pets. Each pet is a directory
@@ -28,6 +28,33 @@ export async function discoverPets(searchPaths = [], deps = {}) {
   return pets;
 }
 
+// discoverPets only scans the user's pet folders (~/.codex/pets, ~/.haya-pet/pets),
+// so a fresh install with no pets renders the dev placeholder instead of a real
+// character. The package ships a ready-to-use pet; this composes it in as a
+// last resort — appended after the user's pets so a real install still wins for
+// the default selection, and deduped by id so a user who copied it in isn't
+// shown two. The bundled directory is injectable so this stays testable.
+export async function discoverPetsWithFallback(searchPaths = [], deps = {}) {
+  const pets = await discoverPets(searchPaths, deps);
+  const fallbackDir = deps.fallbackPetDir ?? getBundledFallbackPetDir();
+  const fallback = await loadPetFromDir(fallbackDir, deps);
+
+  if (!fallback || pets.some((pet) => pet.manifest.id === fallback.manifest.id)) {
+    return pets;
+  }
+
+  return [...pets, fallback];
+}
+
+// Absolute path to the bundled fallback pet, resolved relative to this module so
+// it works the same for global installs, npm link, and source checkouts. The
+// asset lives at the package root (assets/fallback-pet); this file sits three
+// levels below it (packages/pet-core/src).
+export function getBundledFallbackPetDir() {
+  const here = dirname(fileURLToPath(import.meta.url));
+  return join(here, "..", "..", "..", "assets", "fallback-pet");
+}
+
 export async function loadPetFromDir(petDir, deps = {}) {
   const { readFile, stat } = resolveFs(deps);
   const manifestPath = join(petDir, "pet.json");

package/packages/pet-core/test/discovery.test.mjs

@@ -1,7 +1,12 @@
 import assert from "node:assert/strict";
 import { join } from "node:path";
 import { test } from "../../../test/harness.mjs";
-import { discoverPets, loadPetFromDir } from "../src/discovery.js";
+import {
+  discoverPets,
+  discoverPetsWithFallback,
+  getBundledFallbackPetDir,
+  loadPetFromDir
+} from "../src/discovery.js";
 
 function manifest(id, name) {
   return JSON.stringify({ id, name, spritesheet: "spritesheet.webp" });
@@ -91,3 +96,60 @@ test("returns undefined for an invalid manifest", async () => {
 test("tolerates missing search directories", async () => {
   assert.deepEqual(await discoverPets([join("does-not-exist")], fakeFs()), []);
 });
+
+test("falls back to the bundled pet when the user has no pets", async () => {
+  const fallbackDir = join("bundled", "fallback-pet");
+  const fs = fakeFs({
+    files: {
+      [join(fallbackDir, "pet.json")]: manifest("fallback-pet", "Fallback"),
+      [join(fallbackDir, "spritesheet.webp")]: "x"
+    }
+  });
+
+  const pets = await discoverPetsWithFallback([join("empty")], { ...fs, fallbackPetDir: fallbackDir });
+  assert.equal(pets.length, 1);
+  assert.equal(pets[0].manifest.id, "fallback-pet");
+});
+
+test("appends the bundled pet after the user's own pets", async () => {
+  const root = join("petsdir");
+  const fallbackDir = join("bundled", "fallback-pet");
+  const fs = fakeFs({
+    dirs: { [root]: ["cat"] },
+    files: {
+      [join(root, "cat", "pet.json")]: manifest("cat", "Cat"),
+      [join(root, "cat", "spritesheet.webp")]: "x",
+      [join(fallbackDir, "pet.json")]: manifest("fallback-pet", "Fallback"),
+      [join(fallbackDir, "spritesheet.webp")]: "x"
+    }
+  });
+
+  const pets = await discoverPetsWithFallback([root], { ...fs, fallbackPetDir: fallbackDir });
+  assert.deepEqual(pets.map((pet) => pet.manifest.id), ["cat", "fallback-pet"]);
+});
+
+test("does not duplicate the bundled pet when the user already installed it", async () => {
+  const root = join("petsdir");
+  const fallbackDir = join("bundled", "fallback-pet");
+  const fs = fakeFs({
+    dirs: { [root]: ["fallback-pet"] },
+    files: {
+      [join(root, "fallback-pet", "pet.json")]: manifest("fallback-pet", "User Copy"),
+      [join(root, "fallback-pet", "spritesheet.webp")]: "x",
+      [join(fallbackDir, "pet.json")]: manifest("fallback-pet", "Bundled"),
+      [join(fallbackDir, "spritesheet.webp")]: "x"
+    }
+  });
+
+  const pets = await discoverPetsWithFallback([root], { ...fs, fallbackPetDir: fallbackDir });
+  assert.equal(pets.length, 1);
+  assert.equal(pets[0].manifest.name, "User Copy");
+});
+
+// Guards both the package-relative path resolution and that the asset actually
+// ships: if either breaks, a fresh install renders the dev placeholder again.
+test("ships a bundled fallback pet that loads from disk", async () => {
+  const pet = await loadPetFromDir(getBundledFallbackPetDir());
+  assert.ok(pet, "bundled fallback pet should load from the shipped package");
+  assert.equal(pet.manifest.id, "fallback-pet");
+});

package/packages/protocol/src/messages.js

@@ -8,6 +8,9 @@ export const AI_CLIENT_STATES = Object.freeze([
   "reviewing",
   "compacting",
   "failed",
+  // The user interrupted the turn (Esc). Looks like a failure (red ✕) but is NOT
+  // terminal — the session is still alive, so its bubble must not linger-out.
+  "interrupted",
   "success",
   "stale",
   "exited"

package/packages/protocol/test/messages.test.mjs

@@ -20,11 +20,14 @@ test("declares normalized AI states and state sources from the plan", () => {
     "reviewing",
     "compacting",
     "failed",
+    "interrupted",
     "success",
     "stale",
     "exited"
   ]);
 
+  assert.equal(isAiClientState("interrupted"), true);
+
   assert.deepEqual(STATE_SOURCES, [
     "wrapper",
     "pty_output",

package/packages/session-core/src/bubble-view.js

@@ -16,6 +16,9 @@ const STATUS_KIND_BY_STATE = Object.freeze({
   waiting_approval: "attention",
   stale: "attention",
   failed: "failed",
+  // An interrupt shows the same red ✕ as a failure, but it is a live (non-ended)
+  // state — see bubble-linger ENDED_STATES — so the bubble stays put.
+  interrupted: "failed",
   idle: "done",
   success: "done",
   exited: "done"

package/packages/session-core/src/pet-state.js

@@ -4,14 +4,16 @@ import { mapAiStateToPetAction } from "../../pet-core/src/atlas.js";
 const TERMINAL_STATES = new Set(["exited", "success"]);
 
 // States that should NOT drive a looping stable action. success/exited are
-// terminal; failed is a timed reaction (a stray error must not pin the pet on
-// the "failed" animation forever).
-const NON_STABLE_STATES = new Set(["exited", "success", "failed"]);
+// terminal; failed/interrupted are timed reactions (a stray error or an Esc must
+// not pin the pet on the "failed" animation forever). Note interrupted is NOT in
+// TERMINAL_STATES — the session is still alive, it just had its turn cut short.
+const NON_STABLE_STATES = new Set(["exited", "success", "failed", "interrupted"]);
 
 // States that play a one-shot reaction exactly once when first entered.
 const ONE_SHOT_BY_STATE = Object.freeze({
   success: "jumping",
-  failed: "failed"
+  failed: "failed",
+  interrupted: "failed"
 });
 
 // Active-work states. Transitioning from one of these to idle means a turn

package/packages/session-core/src/summaries.js

@@ -8,6 +8,7 @@ const STATUS_LABELS = Object.freeze({
   reviewing: "Reviewing",
   compacting: "Compacting context",
   failed: "Failed",
+  interrupted: "Interrupted",
   success: "Done",
   stale: "Stale",
   exited: "Exited"

package/packages/session-core/test/bubble-linger.test.mjs

@@ -12,6 +12,22 @@ test("ENDED_STATES covers the process-finished states", () => {
   assert.ok(ENDED_STATES.has("failed"));
   assert.ok(!ENDED_STATES.has("idle"));
   assert.ok(!ENDED_STATES.has("running_tool"));
+  // An interrupt ends the TURN, not the session — the session is still alive, so
+  // its bubble must NOT linger-out and vanish.
+  assert.ok(!ENDED_STATES.has("interrupted"));
+});
+
+test("keeps an interrupted bubble visible (the session is still alive)", () => {
+  // Long after any linger window would have elapsed, an interrupted bubble stays.
+  const result = resolveVisibleBubbles({
+    bubbles: [bubble("a", "interrupted")],
+    now: 1_000_000,
+    lingerState: { a: 1000 },
+    lingerMs: 2000
+  });
+  assert.deepEqual(result.visible.map((b) => b.sessionId), ["a"]);
+  assert.deepEqual(result.lingerState, {});
+  assert.equal(result.nextWakeMs, undefined);
 });
 
 test("keeps active (non-ended) bubbles visible with no linger tracking", () => {

package/packages/session-core/test/bubble-view.test.mjs

@@ -85,6 +85,14 @@ test("resolves failure to the 'failed' status kind (red cross)", () => {
   assert.equal(resolveBubbleStatusKind("failed"), "failed");
 });
 
+test("resolves an interrupt to the 'failed' status kind (red cross) but keeps it a live state", () => {
+  assert.equal(resolveBubbleStatusKind("interrupted"), "failed");
+  const view = buildBubbleView({ ...baseSession, state: "interrupted", summary: "interrupted" }, 6_000);
+  assert.equal(view.statusKind, "failed");
+  assert.equal(view.statusLabel, "Interrupted");
+  assert.equal(view.petAction, "failed");
+});
+
 test("resolves idle/finished states to the 'done' status kind (check mark)", () => {
   for (const state of ["idle", "success", "exited"]) {
     assert.equal(resolveBubbleStatusKind(state), "done", state);

package/packages/session-core/test/pet-state.test.mjs

@@ -82,6 +82,29 @@ test("a failed session still yields to active work for the stable action", () =>
   assert.equal(result.stableAction, "running");
 });
 
+test("an interrupt is a one-shot reaction, not a sticky stable action (like failed)", () => {
+  const result = resolveCompanionPetState({
+    bubbles: [bubble("a", "interrupted")],
+    prioritySessionId: "a",
+    previousStates: { a: "thinking" }
+  });
+  // plays the failed reaction once on the interrupt...
+  assert.deepEqual(result.oneShots, ["failed"]);
+  // ...but does not pin the pet on a looping action, and the session stays alive
+  // (still in the active bubble list, unlike exited/success).
+  assert.equal(result.stableAction, "idle");
+  assert.deepEqual(result.activeBubbles.map((b) => b.sessionId), ["a"]);
+});
+
+test("does not repeat the interrupt reaction while it stays interrupted", () => {
+  const result = resolveCompanionPetState({
+    bubbles: [bubble("a", "interrupted")],
+    prioritySessionId: "a",
+    previousStates: { a: "interrupted" }
+  });
+  assert.deepEqual(result.oneShots, []);
+});
+
 test("celebrates with a one-shot jump when a working turn finishes (working -> idle)", () => {
   const result = resolveCompanionPetState({
     bubbles: [bubble("a", "idle")],