@hayasaka7/haya-pet 0.1.0 → 0.2.1

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

@@ -17,12 +17,12 @@ test("parses generic run command arguments", () => {
   );
 });
 
-test("observation is on by default and --no-observe opts out", () => {
-  assert.equal(parseAiPetArgs(["run", "--client", "codex"]).observe, true);
-  assert.equal(parseAiPetArgs(["run", "--no-observe", "--client", "codex"]).observe, false);
+test("native passthrough is the default and --observe opts in", () => {
+  assert.equal(parseAiPetArgs(["run", "--client", "codex"]).observe, false);
+  assert.equal(parseAiPetArgs(["run", "--observe", "--client", "codex"]).observe, true);
 
   const parsedWithCommand = parseAiPetArgs(["run", "--", "claude", "--resume"]);
-  assert.equal(parsedWithCommand.observe, true);
+  assert.equal(parsedWithCommand.observe, false);
   assert.equal(parsedWithCommand.childCommand, "claude");
   assert.deepEqual(parsedWithCommand.childArgs, ["--resume"]);
 });
@@ -326,6 +326,271 @@ test("stop command is a no-op when nothing is running", async () => {
   assert.ok(lines.some((line) => line.includes("not running")));
 });
 
+test("parses the state command", () => {
+  assert.deepEqual(parseAiPetArgs(["state", "thinking", "--session", "sess_q"]), {
+    command: "state",
+    state: "thinking",
+    summary: undefined,
+    session: "sess_q"
+  });
+});
+
+const hooksStateFile = (hooksEnabled) => () => ({
+  load: async () => ({ settings: { hooksEnabled } }),
+  save: async (state) => state
+});
+
+test("claude-code does NOT inject hooks by default (safe out-of-box)", async () => {
+  const calls = [];
+  let injected = 0;
+  await runAiPet(["run", "--client", "claude-code", "--", "claude"], {
+    cwd: process.cwd(),
+    env: { USERPROFILE: "C:\\Users\\A" },
+    heartbeatIntervalMs: 10,
+    send: async () => {},
+    createStateFile: hooksStateFile(false),
+    injectClaudeHooks: () => { injected += 1; return { settingsPath: "x", cleanup: () => {} }; },
+    runGenericCommand: async (options) => {
+      calls.push(options);
+      return { sessionId: "s", pid: 1, exitCode: 0 };
+    }
+  });
+
+  assert.equal(injected, 0, "no hook injection unless opted in");
+  assert.deepEqual(calls[0].args, []);
+});
+
+test("persisted `hooks on` opts claude-code into injection without an env var", async () => {
+  const calls = [];
+  let injected = 0;
+  await runAiPet(["run", "--client", "claude-code", "--", "claude"], {
+    cwd: process.cwd(),
+    env: { USERPROFILE: "C:\\Users\\A" }, // no HAYA_PET_HOOKS
+    heartbeatIntervalMs: 10,
+    send: async () => {},
+    createStateFile: hooksStateFile(true), // persisted preference = on
+    injectClaudeHooks: () => { injected += 1; return { settingsPath: "/tmp/s.json", cleanup: () => {} }; },
+    watchClaudeTranscript: () => ({ stop: () => {} }),
+    runGenericCommand: async (options) => {
+      calls.push(options);
+      return { sessionId: options.sessionId, pid: 1, exitCode: 0 };
+    }
+  });
+
+  assert.equal(injected, 1, "config preference enables hooks");
+  assert.deepEqual(calls[0].args, ["--settings", "/tmp/s.json"]);
+});
+
+test("HAYA_PET_NO_HOOKS=1 overrides a persisted `hooks on`", async () => {
+  const calls = [];
+  let injected = 0;
+  await runAiPet(["run", "--client", "claude-code", "--", "claude"], {
+    cwd: process.cwd(),
+    env: { HAYA_PET_NO_HOOKS: "1", USERPROFILE: "C:\\Users\\A" },
+    heartbeatIntervalMs: 10,
+    send: async () => {},
+    createStateFile: hooksStateFile(true),
+    injectClaudeHooks: () => { injected += 1; return { settingsPath: "x", cleanup: () => {} }; },
+    runGenericCommand: async (options) => {
+      calls.push(options);
+      return { sessionId: "s", pid: 1, exitCode: 0 };
+    }
+  });
+
+  assert.equal(injected, 0, "env override forces hooks off");
+  assert.deepEqual(calls[0].args, []);
+});
+
+test("hooks command parses and persists the toggle", async () => {
+  assert.deepEqual(parseAiPetArgs(["hooks"]), { command: "hooks", action: "status" });
+  assert.deepEqual(parseAiPetArgs(["hooks", "on"]), { command: "hooks", action: "on" });
+  assert.throws(() => parseAiPetArgs(["hooks", "bogus"]), /Unknown hooks action/);
+
+  let saved;
+  const lines = [];
+  const store = {
+    load: async () => ({ settings: { hooksEnabled: false } }),
+    save: async (state) => { saved = state; return state; }
+  };
+  const result = await runAiPet(["hooks", "on"], {
+    homeDir: "C:\\Users\\A",
+    createStateFile: () => store,
+    print: (line) => lines.push(line)
+  });
+
+  assert.equal(result.enabled, true);
+  assert.equal(saved.settings.hooksEnabled, true);
+  assert.ok(lines.some((l) => l.includes("on")));
+});
+
+test("persisted `hooks on` injects a Codex profile via -p at the front of args", async () => {
+  const calls = [];
+  let injected = 0;
+  await runAiPet(["run", "--client", "codex", "--", "codex"], {
+    cwd: process.cwd(),
+    env: { USERPROFILE: "C:\\Users\\A" }, // no HAYA_PET_HOOKS
+    heartbeatIntervalMs: 10,
+    send: async () => {},
+    createStateFile: hooksStateFile(true),
+    injectCodexHooks: () => { injected += 1; return { profileName: "haya-pet", cleanup: () => {} }; },
+    runGenericCommand: async (options) => {
+      calls.push(options);
+      return { sessionId: options.sessionId, pid: 1, exitCode: 0 };
+    }
+  });
+
+  assert.equal(injected, 1, "config preference enables Codex hooks");
+  assert.deepEqual(calls[0].args, ["-p", "haya-pet"], "profile flag goes at the front");
+});
+
+test("codex hooks also start a transcript watcher for tool activity", async () => {
+  const sent = [];
+  let fireToolEvent;
+  let stopped = false;
+
+  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: () => { stopped = true; } };
+    },
+    runGenericCommand: async (options) => {
+      fireToolEvent({
+        type: "tool_started",
+        toolCallId: "call_shell",
+        toolName: "shell_command",
+        state: "running_tool"
+      });
+      fireToolEvent({
+        type: "tool_finished",
+        toolCallId: "call_shell"
+      });
+      return { sessionId: options.sessionId, pid: 1, exitCode: 0 };
+    }
+  });
+
+  assert.ok(stopped, "transcript watcher is stopped after the wrapped command exits");
+  assert.deepEqual(
+    sent.filter((message) => message.type === "state" && message.source === "client_log").map((message) => message.state),
+    ["running_tool", "thinking"]
+  );
+  assert.ok(sent.every((message) => message.updatedAt === undefined || message.updatedAt === 42));
+});
+
+test("codex hooks are skipped (with a notice) when the user passes their own -p", async () => {
+  const calls = [];
+  let injected = 0;
+  const lines = [];
+  await runAiPet(["run", "--client", "codex", "--", "codex", "-p", "mine"], {
+    cwd: process.cwd(),
+    env: { USERPROFILE: "C:\\Users\\A" },
+    heartbeatIntervalMs: 10,
+    send: async () => {},
+    createStateFile: hooksStateFile(true),
+    print: (line) => lines.push(line),
+    injectCodexHooks: () => { injected += 1; return { profileName: "haya-pet", cleanup: () => {} }; },
+    runGenericCommand: async (options) => {
+      calls.push(options);
+      return { sessionId: options.sessionId, pid: 1, exitCode: 0 };
+    }
+  });
+
+  assert.equal(injected, 0, "user's profile is respected — no injection");
+  assert.deepEqual(calls[0].args, ["-p", "mine"], "user args untouched");
+  assert.ok(lines.some((l) => /skipped/i.test(l)), "user is told why");
+});
+
+test("codex does NOT inject hooks by default (safe out-of-box)", async () => {
+  const calls = [];
+  let injected = 0;
+  await runAiPet(["run", "--client", "codex", "--", "codex"], {
+    cwd: process.cwd(),
+    env: { USERPROFILE: "C:\\Users\\A" },
+    heartbeatIntervalMs: 10,
+    send: async () => {},
+    createStateFile: hooksStateFile(false),
+    injectCodexHooks: () => { injected += 1; return { profileName: "haya-pet", cleanup: () => {} }; },
+    runGenericCommand: async (options) => {
+      calls.push(options);
+      return { sessionId: "s", pid: 1, exitCode: 0 };
+    }
+  });
+
+  assert.equal(injected, 0, "no hook injection unless opted in");
+  assert.deepEqual(calls[0].args, []);
+});
+
+test("HAYA_PET_HOOKS=1 opts claude-code into --settings + HAYA_PET_SESSION_ID", async () => {
+  const calls = [];
+  let watched = 0;
+  await runAiPet(["run", "--client", "claude-code", "--", "claude"], {
+    cwd: process.cwd(),
+    env: { HAYA_PET_HOOKS: "1", USERPROFILE: "C:\\Users\\A", HOME: "/home/a" },
+    heartbeatIntervalMs: 10,
+    send: async () => {},
+    injectClaudeHooks: () => ({ settingsPath: "/tmp/s.json", cleanup: () => {} }),
+    watchClaudeTranscript: () => { watched += 1; return { stop: () => {} }; },
+    runGenericCommand: async (options) => {
+      calls.push(options);
+      return { sessionId: options.sessionId, pid: 1, exitCode: 0 };
+    }
+  });
+
+  assert.equal(calls.length, 1);
+  assert.deepEqual(calls[0].args, ["--settings", "/tmp/s.json"]);
+  assert.equal(calls[0].env.HAYA_PET_SESSION_ID, calls[0].sessionId);
+  assert.ok(calls[0].sessionId, "a session id was generated and shared via env");
+  assert.equal(watched, 1, "transcript watcher started for approval-denial recovery");
+});
+
+test("a transcript denial clears the stuck approval to idle", async () => {
+  const sent = [];
+  let fireDenial;
+  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: ({ onDenial }) => { fireDenial = onDenial; return { stop: () => {} }; },
+    runGenericCommand: async (options) => {
+      // Simulate the user denying a permission mid-session.
+      fireDenial({ type: "tool_denied", toolUseId: "toolu_1" });
+      return { sessionId: options.sessionId, pid: 1, exitCode: 0 };
+    }
+  });
+
+  const idle = sent.find((m) => m.type === "state" && m.source === "client_log");
+  assert.ok(idle, "a client_log state was sent on denial");
+  assert.equal(idle.state, "idle");
+  assert.equal(idle.summary, "approval denied");
+  assert.equal(idle.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"], {
+    cwd: process.cwd(),
+    env: { HAYA_PET_HOOKS: "1", USERPROFILE: "C:\\Users\\A" },
+    heartbeatIntervalMs: 10,
+    send: async () => {},
+    injectClaudeHooks: () => { throw new Error("should not inject for generic"); },
+    injectCodexHooks: () => { throw new Error("should not inject for generic"); },
+    runGenericCommand: async (options) => {
+      calls.push(options);
+      return { sessionId: "s", pid: 1, exitCode: 0 };
+    }
+  });
+  assert.deepEqual(calls[0].args, []);
+});
+
 async function waitFor(predicate) {
   const startedAt = Date.now();
 

package/apps/companion/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haya-pet/companion",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "private": true,
   "type": "module",
   "description": "Electron overlay companion app for the AI CLI pet runtime.",

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

@@ -3,6 +3,11 @@ import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
 import { createDaemonRuntime } from "../../../../packages/daemon-core/src/daemon-runtime.js";
 import { createIpcServer } from "../../../../packages/daemon-core/src/ipc-server.js";
+import {
+  createApprovalWatchCoordinator,
+  watchForApprovedProcess
+} from "../../../../packages/daemon-core/src/approval-process-watcher.js";
+import { createProcessSnapshotLister } from "../../../../packages/platform-core/src/process-snapshot.js";
 import { getDefaultPaths } from "../../../../packages/platform-core/src/paths.js";
 import { getPlatformCapabilities } from "../../../../packages/platform-core/src/capabilities.js";
 import { buildBubbleViews } from "../../../../packages/session-core/src/bubble-view.js";
@@ -38,6 +43,7 @@ let runtime;
 let currentWorkArea;
 let currentDisplayId;
 let petLocal = { x: 0, y: 0 };
+let approvalWatch;
 
 // Electron singleton: a second launch forwards to the running instance.
 if (!app.requestSingleInstanceLock()) {
@@ -54,8 +60,40 @@ async function bootstrap() {
   positionState = await stateFile.load();
   pets = await discoverPets(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
+  // otherwise look stuck until its tool completed. The approval watcher flips
+  // it to running_tool when the approved command verifiably starts — a new
+  // persistent process under the client — and never on a timer, so a genuinely
+  // unanswered prompt keeps warning. Unsupported platforms simply skip this.
+  const processLister = createProcessSnapshotLister();
+  approvalWatch = processLister
+    ? createApprovalWatchCoordinator({
+        createWatcher: ({ rootPid, onApproved }) =>
+          watchForApprovedProcess({ rootPid, listProcesses: processLister, onApproved }),
+        onApproved: (sessionId) => {
+          try {
+            runtime.handleMessage({
+              type: "state",
+              sessionId,
+              state: "running_tool",
+              summary: "approved",
+              confidence: 0.6,
+              source: "client_log",
+              updatedAt: Date.now()
+            });
+          } catch {
+            // The session may have unregistered between detection and report.
+          }
+        }
+      })
+    : undefined;
+
   runtime = createDaemonRuntime({
-    onSessionChanged: () => pushSessions()
+    onSessionChanged: (session) => {
+      approvalWatch?.onSessionChanged(session);
+      pushSessions();
+    }
   });
 
   ipcServer = await createIpcServer({
@@ -85,6 +123,7 @@ async function bootstrap() {
 
   app.on("before-quit", async () => {
     clearInterval(sweep);
+    approvalWatch?.stopAll();
     await ipcServer?.close();
   });
 }

package/apps/companion/test/position-store.test.mjs

@@ -17,7 +17,8 @@ test("creates default position state", () => {
     sessions: {},
     settings: {
       displayMode: "hybrid",
-      attachBubblesToTerminals: true
+      attachBubblesToTerminals: true,
+      hooksEnabled: false
     }
   });
 });

package/docs/architecture.md

@@ -48,14 +48,46 @@ as each client allows:
 | Tier | Source | Fidelity |
 |---|---|---|
 | L1 | Process wrapper (lifecycle only) | session exists / exit code |
-| L2 | PTY output observation (`--observe`, default) | activity-based working/idle |
-| L3 | Client logs / state files | client-specific (future) |
-| L4 | Official plugin/hooks | richest (future) |
+| L2 | PTY output observation (`--observe`, opt-in) | activity-based working/idle |
+| L3 | Client logs / state files / process tree | transcript watchers (Claude denial, Codex tools) + approval-accept detection |
+| L4 | Client hooks | richest — implemented for Claude Code (full) and Codex (partial) |
+
+The **default** is native passthrough (`stdio: "inherit"`) for full terminal
+fidelity, with **L1 lifecycle** status for every client. Richer status is opt-in:
+**Claude Code** and **Codex** gain **L4 hooks** when enabled with the global
+`haya-pet hooks on` (persisted; or per-run via `HAYA_PET_HOOKS=1`). Both report
+in-session activity through the shared, client-agnostic `haya-pet state` command
+(lifecycle still comes from the wrapper's exit code); any client gains **L2** with
+`--observe`. Hooks are opt-in because injecting them triggers the client's one-time
+*review hooks* trust prompt.
+
+The injection mechanism differs per client. **Claude Code** takes a stable
+`claude --settings <file>`. **Codex** has no per-invocation settings flag, so the
+wrapper writes a stable `$CODEX_HOME/haya-pet.config.toml` profile and prepends
+`-p haya-pet` to the codex args (a profile layers on top of the user's base config,
+leaving auth/model/MCP intact, and is inert otherwise). Codex allows only one
+profile, so if the user already passes `-p/--profile`, injection is skipped with a
+notice. Codex's hook command must be unquoted at the program position (it runs via
+`cmd /c`, which strips a leading quote) and its matchers can't use look-around
+(Rust regex) — see [known-issues.md](known-issues.md). Codex's L4 is **partial**:
+`PreToolUse`/`PermissionRequest` don't fire upstream yet, so only `thinking`/`idle`
+arrive today.
+
+Hooks alone can't see one moment: clients emit **no event when the user accepts a
+permission prompt** (denial and completion are observable; the accept click is
+not). The companion bridges it with **L3 process-tree observation**: while a
+session sits in `waiting_approval`, it polls the client's process subtree (the
+wrapper reported the pid at register), and when a new descendant process appears
+and persists across two polls — the approved command verifiably running — the
+session flips to `running_tool`. No timers: an unanswered prompt keeps warning
+until a real event resolves it (`approval-process-watcher.js`,
+`process-snapshot.js`; Windows/macOS/Linux listers).
 
 L2 is **activity-based**: any visible output → *working*; a short quiet window →
 *idle*; success/failure come from the real exit code, never from scraping output
-text. Keyword heuristics exist but are opt-in (unreliable on rich TUIs). See
-[known-issues.md](known-issues.md) for the current L2/PTY tradeoffs.
+text. It is opt-in because routing input through a PTY (ConPTY on Windows) breaks
+special keys like Shift+Tab — see [known-issues.md](known-issues.md) for the
+L2/PTY tradeoffs.
 
 ## Overlay model
 
@@ -85,8 +117,9 @@ packages/
   session-core/    registry, priority, summaries, bubble views, linger, pet-state
   task-core/       task status, events, store, approvals, replies, controls
   adapters/        client info, heuristics, capabilities, output observer, routing
-  daemon-core/     IPC server/transport, runtime bridge, singleton
-  platform-core/   platform, paths, capabilities
+  daemon-core/     IPC server/transport, runtime bridge, singleton,
+                   approval process watcher (waiting_approval -> running_tool)
+  platform-core/   platform, paths, capabilities, process snapshots (win/mac/linux)
 apps/
   cli/             haya-pet entrypoint + parser (run / start / stop / pets)
   companion/       Electron overlay app (main + renderer)
@@ -141,4 +174,48 @@ helper. In progress:
 - Faithful PTY passthrough (see [known-issues.md](known-issues.md)).
 - Production overlay/IPC validation across all platforms.
 
+### Deferred: focus a session's terminal on bubble click
+
+Clicking a session bubble should raise/focus the terminal window running that
+session. Deferred because it can't be done as a clean cross-OS feature yet:
+
+- **Windows** — doable now: the helper already *locates* the window (HWND); add a
+  `focus` op that calls `SetForegroundWindow` (+ the usual `AllowSetForegroundWindow`
+  / attach-thread-input dance), then wire bubble click → IPC → helper.
+- **macOS** — needs an (unbuilt) Accessibility/window-list helper and a
+  user-granted Accessibility permission.
+- **Linux X11** — needs the (unbuilt) X11 helper (EWMH `_NET_ACTIVE_WINDOW`).
+- **Linux Wayland** — blocked by the compositor security model; no portable API to
+  focus another app's window.
+
+Implementation sketch when picked up: bubble `click` in `session-bubbles.js` →
+`haya-pet:focus-session` IPC with `sessionId` → main resolves `session.pid`
+(/`terminalPid`) → terminal helper `focus` op (per-OS), with a graceful no-op
+where unsupported.
+
+### Deferred: per-session token usage
+
+Show each session's token usage on its bubble. Feasible as an **L3 client-log
+adapter** (`source: "client_log"`) — and it's cross-OS, since only the log path
+differs by client, not by OS. There is no generic source: the process wrapper
+only sees terminal bytes, so usage must come from each client's own logs.
+
+- **Claude Code** — confirmed: per-turn `usage` (`input_tokens`, `output_tokens`,
+  `cache_creation_input_tokens`, `cache_read_input_tokens`) in
+  `~/.claude/projects/<encoded-cwd>/<session-uuid>.jsonl`. Clean JSONL to parse.
+- **Codex** — usage exists in its logs (`~/.codex/history.jsonl`, `sessions/`,
+  sqlite) but in a messier shape; needs a dedicated adapter + investigation.
+- **Generic / other clients** — no reliable source; the adapter should no-op.
+
+Implementation sketch when picked up: a per-client usage adapter tails the
+session's transcript (matched via the session's `cwd` → the newest `.jsonl` in
+that project dir), sums usage across turns, and emits an optional `usage` field
+(protocol addition) → `session-core` stores it → the bubble renders it
+(e.g. `↑ in / ↓ out`). Open questions: (1) which metric to surface — cache-read
+tokens are huge under prompt caching, so likely show output + input, with total
+context separate; (2) disambiguating multiple concurrent sessions in the same
+project dir (by start time / newest file). The JSONL parser is pure and
+TDD-friendly. Investigate non-Claude client adapters (Codex, etc.) as part of
+this.
+
 See [`../PROGRESS.md`](../PROGRESS.md) for the detailed log.

package/docs/cross-os-qa.md

@@ -0,0 +1,72 @@
+# Cross-OS QA Matrix
+
+Use this checklist before release candidates and after changes to IPC, windowing, display handling, terminal attachment, or CLI process wrapping.
+
+## Automated Gates
+
+- [ ] `npm test` passes on the target branch.
+- [ ] Generic command lifecycle emits register, running state, heartbeat, final state, and unregister.
+- [ ] Daemon accepts local IPC messages and updates the session registry.
+- [ ] CLI can run through daemon IPC without an injected sender.
+- [ ] Pet preview loads a Codex-compatible `1536x1872` spritesheet.
+- [ ] Pet manifest parsing and atlas/action validation pass (`pet-core`).
+- [ ] Generic regex heuristics map sample output to normalized states (`adapters`).
+- [ ] Task status mapping, event normalization, and control gating pass (`task-core`).
+- [ ] Session bubble view models build with status label, summary, action, and elapsed (`session-core`).
+- [ ] PTY output observer infers debounced `pty_output` states from sample client output (`adapters`).
+- [ ] Reply/approval routing dispatches to injectors and safely refuses unsupported adapters (`adapters`).
+
+## Manual Platform Matrix
+
+| Platform | Shell/Terminal | Display Setup | Required Checks |
+|---|---|---|---|
+| Windows 11 | PowerShell | 100% DPI | `haya-pet run --client generic -- node -e "setTimeout(() => process.exit(0), 1000)"`; daemon sees session exit; overlay opens without focus stealing. |
+| Windows 11 | Windows Terminal | 125% DPI | Pet drag/click/double-click; position persists after restart; terminal attachment helper reports best-effort capability. |
+| Windows 11 | Windows Terminal | 150% or mixed DPI | Saved offscreen position clamps to visible work area; session bubbles remain visible. |
+| macOS current stable | Terminal.app | Retina display | Unix socket IPC works; transparent overlay opens; click/drag behavior works; position persists. |
+| macOS current stable | iTerm2 | External display | Moving terminal across displays does not lose session bubble fallback; permission denial produces best-effort/fallback state. |
+| Ubuntu Linux X11 | GNOME Terminal | Single display | Unix socket IPC works; transparent overlay opens; X11 terminal strategy reports best-effort. |
+| Ubuntu or Fedora Linux Wayland | Default terminal | Single display | Overlay fallback mode works; terminal attachment reports manual fallback; global pet plus cluster/session bubbles remain usable. |
+
+## Release Acceptance Gates
+
+- [ ] No platform stores prompts, screenshots, or raw terminal logs by default.
+- [ ] Windows uses `\\.\pipe\haya-petd` for local IPC.
+- [ ] macOS/Linux use `~/.haya-pet/haya-petd.sock` for local IPC.
+- [ ] Windows state path is under `%LOCALAPPDATA%\haya-pet\state.json`.
+- [ ] macOS/Linux state path is under `~/.haya-pet/state.json`.
+- [ ] If transparent overlay fails, a normal companion window is available.
+- [ ] If terminal attachment fails, global pet plus manual/cluster bubbles remain available.
+- [ ] Wayland does not use unsupported global positioning assumptions.
+- [ ] Saved display IDs are validated; missing displays fall back to primary visible work area.
+- [ ] Task talk controls are hidden or disabled when adapter capability is unsupported.
+- [ ] Reply composer shows "Open terminal to reply" for wrapper-only adapters (no blind injection).
+- [ ] Approvals require explicit approve/deny and are never auto-approved.
+- [ ] Companion runs as a single instance; a second launch focuses the existing pet.
+- [ ] A stale daemon lock (dead PID) is reclaimed; a live one forwards.
+
+## Companion App Smoke Test (per OS)
+
+Run from `apps/companion` after `npm install`:
+
+- [ ] `npm start` opens the overlay; empty space stays click-through.
+- [ ] Single click → waving; double click → jumping; drag moves and persists.
+- [ ] Running `haya-pet run --client generic -- sleep 10` shows a session bubble.
+- [ ] Two concurrent sessions show two bubbles without renderer conflicts.
+- [ ] Selecting a bubble opens the task talk window (peek mode).
+- [ ] Tray menu can show/hide the pet and reset its position.
+
+## Current Implementation Status
+
+- Shared protocol/session/pet core: automated coverage exists.
+- Pet asset manifest + validation + frame animator: automated coverage exists.
+- Client adapters (info, generic/PTY heuristics, capabilities): automated coverage exists.
+- Task talk core (status, events, store, approvals, replies, controls): automated coverage exists.
+- Session summaries + bubble view models: automated coverage exists.
+- Daemon singleton decision logic + tray menu model + position state file: automated coverage exists.
+- Cross-OS platform paths and capabilities: automated coverage exists.
+- Test-mode IPC server/client: automated coverage exists.
+- Electron overlay app: implemented as glue (`apps/companion`) consuming the pure cores; requires `electron` install and manual run/QA per OS (not unit-tested).
+- Production OS endpoint behavior: needs manual validation on Windows, macOS, and Linux.
+- Terminal attachment: facade + documented IPC contract (`native/README.md`). Windows helper is implemented in .NET and compiles + runs; macOS/Linux helper binaries are still TODO. Node helper client (`terminal-helper-client.js`) is unit-tested.
+- PTY output observer + reply/approval routing: implemented and unit-tested as pure cores. Live wiring (real PTY via node-pty; bidirectional IPC + real injectors) is a later phase.