@staix/agent-hub 0.12.26 → 0.12.28

package/src/hub/bus.ts

@@ -46,6 +46,11 @@ export interface BusOptions {
    * the console and the log see it as published.
    */
   silence?: (env: Envelope, peer: PeerId) => string | undefined;
+  /**
+   * Optional: an `important` envelope was just queued for a pull-only peer (issue #398). Advisory only: nothing was
+   * dequeued, steered or journaled for it, and the queue still waits for `Bus.pull`; a throw is swallowed.
+   */
+  onImportantQueued?: (peer: PeerId, counts: { queued: number; important: number }) => void;
 }
 
 /** Serializable delivery state used by the controlled restart coordinator. Bodies stay in the private daemon file. */
@@ -732,6 +737,10 @@ export class Bus {
       if (this.journal) this.pendingOutcomes.push({ id: crypto.randomUUID(), peer: id, state: "failed", createdAt: Date.now(), originals: [lost!], out: [], reason: "queue capacity exceeded" });
       this.emit({ t: "overflow", env: lost!, peer: id });
     }
+    if (queuedEnv.priority === "important" && this.peers.get(id)?.pullOnly) {
+      // Advisory only (issue #398): the envelope stays queued for `pull`; the hook must never affect it.
+      try { this.opts.onImportantQueued?.(id, { queued: queue.length, important: queue.filter((e) => e.priority === "important").length }); } catch { /* a nudge never stops an enqueue */ }
+    }
     this.onQueues?.();
     if (!this.suppressDrain) this.persist();
     if (!this.suppressDrain) void this.drain(id);

package/src/hub/daemon.ts

@@ -38,6 +38,7 @@ import { ensureMlx, type MlxOptions } from "../models/mlx.ts";
 import { PiToolReceipts, packPiShellResult } from "../pi/tool-receipts.ts";
 import { PreEffectToolRefusal } from "./tool-refusal.ts";
 import { processSignature } from "../pi/process-signature.ts";
+import { recordPiReplacement, validatePiSession } from "../pi/session.ts";
 import { profile, proxyEnv, type SandboxNetwork } from "../local/sandbox.ts";
 import { DEFAULT_NETWORK_ALLOW, startEgressProxy, type EgressProxy } from "../local/proxy.ts";
 import { runTool, toolResultFailed, TOOL_SCHEMAS, type ToolApproval, type ApprovalObserver, type ToolContext } from "../local/tools.ts";
@@ -489,6 +490,11 @@ class WsPeer extends BasePeer {
     if (deliveryId) this.delivered.add(deliveryId);
     this.sock.send(JSON.stringify({ t: "deliver", envs, generation: this.generation, ...(deliveryId ? { deliveryId } : {}) }));
   }
+  /** Advisory nudge (issue #398): important work waits in the pull queue. Not a delivery: nothing to settle or journal. */
+  notifyQueued(counts: { queued: number; important: number }): void {
+    if (!this.sock || !this.pullOnly) return;
+    this.sock.send(JSON.stringify({ t: "queued", queued: counts.queued, important: counts.important }));
+  }
   owns(sock: Sock): boolean { return this.sock === sock; }
   nativeStarted(session: string): void {
     if (!this.sock) return;
@@ -769,7 +775,8 @@ export async function startDaemon(opts: DaemonOptions) {
   const staleOff = config.experiments?.stale_notices === "deliver";
   if (staleOff) log("experiment: stale notices are delivered as before 0.12.4 (the issue #106 ablation)");
   const requestedPeerStops = new Set<string>();
-  const bus = new Bus({ rostered: membershipAllowed, deliveryHeld: peer => requestedPeerStops.has(peer) || rosterChanging === peer, journal, batchMax: config.batch_max, batchMs: config.batch_ms, queueCap: config.queue_cap, condense: (envs) => inference?.condense(envs) ?? Promise.resolve(envs), admit, relevant: (peer, env) => env.refs?.supervision || env.refs?.backlog ? relevantNotice(peer, env) : staleOff || relevantNotice(peer, env), silence });
+  const bus = new Bus({ rostered: membershipAllowed, deliveryHeld: peer => requestedPeerStops.has(peer) || rosterChanging === peer, journal, batchMax: config.batch_max, batchMs: config.batch_ms, queueCap: config.queue_cap, condense: (envs) => inference?.condense(envs) ?? Promise.resolve(envs), admit, relevant: (peer, env) => env.refs?.supervision || env.refs?.backlog ? relevantNotice(peer, env) : staleOff || relevantNotice(peer, env), silence,
+    onImportantQueued: (peer, counts) => { const p = bus.peers.get(peer); if (p instanceof WsPeer) p.notifyQueued(counts); } });
   startupCleanup.push(() => bus.closeJournal());
   const manualPaused = new Set<PeerId>(bus.manualPausedPeers()); // recovery never lifts an operator's pause
   const conductorHolds = new ConductorHolds(join(opts.stateDir, "hub.db"));
@@ -2406,6 +2413,7 @@ export async function startDaemon(opts: DaemonOptions) {
   let piAutoRestartAt = -Infinity;
   let piAutoRestartPending = false;
   const replacingPi = new Set<PiPeer>();
+  const piReplacementAuthority = Symbol("console Pi replacement");
   /** pi.auto_start at hub start (#269): in Pi's start mode, and said out loud when it could not be done. */
   const autoStartPi = () => void hubStart("pi", "pi.auto_start").then(
     (result) => { if (result.ok !== true) notify(`pi.auto_start did not start Pi: ${String(result.error)}`); },
@@ -2414,7 +2422,8 @@ export async function startDaemon(opts: DaemonOptions) {
     replacingPi.add(pi);
     try { await pi.stop(); } finally { replacingPi.delete(pi); }
   }
-  function startPeer(peer: string, args: { model?: string; route?: string; mode?: "headless" | "tui"; backend?: "auto" | "dgx" | "mlx"; sessionId?: string; sessionFile?: string; fresh?: boolean; unattended?: boolean; providerProfile?: string }): Promise<Record<string, unknown>> {
+  function startPeer(peer: string, args: { model?: string; route?: string; mode?: "headless" | "tui"; backend?: "auto" | "dgx" | "mlx"; sessionId?: string; sessionFile?: string; replaceSession?: boolean; fresh?: boolean; unattended?: boolean; providerProfile?: string }, replacementAuthority?: symbol): Promise<Record<string, unknown>> {
+    if (args.replaceSession !== undefined && (args.replaceSession !== true || replacementAuthority !== piReplacementAuthority || peer !== "pi")) return Promise.resolve({ ok: false, error: "Pi session replacement requires explicit person authorization" });
     if (stopping) return Promise.resolve({ ok: false, error: "hub is stopping" });
     if (!membershipAllowed(peer)) return Promise.resolve({ ok: false, error: `${peer} is off roster; a person can add it with ahub roster add ${peer}` });
     if (rosterChanging === peer) return Promise.resolve({ ok: false, error: `${peer} roster change is in progress` });
@@ -2544,7 +2553,7 @@ export async function startDaemon(opts: DaemonOptions) {
     };
   }
 
-  async function startPeerOnce(peer: string, args: { model?: string; route?: string; mode?: "headless" | "tui"; backend?: "auto" | "dgx" | "mlx"; sessionId?: string; sessionFile?: string; fresh?: boolean; unattended?: boolean; providerProfile?: string }): Promise<Record<string, unknown>> {
+  async function startPeerOnce(peer: string, args: { model?: string; route?: string; mode?: "headless" | "tui"; backend?: "auto" | "dgx" | "mlx"; sessionId?: string; sessionFile?: string; replaceSession?: boolean; fresh?: boolean; unattended?: boolean; providerProfile?: string }): Promise<Record<string, unknown>> {
     let unmute: (() => void) | undefined;
     try {
       return await startPeerBody(peer, args, (p) => { unmute = muteState(p); });
@@ -2553,7 +2562,7 @@ export async function startDaemon(opts: DaemonOptions) {
     }
   }
 
-  async function startPeerBody(peer: string, args: { model?: string; route?: string; mode?: "headless" | "tui"; backend?: "auto" | "dgx" | "mlx"; sessionId?: string; sessionFile?: string; fresh?: boolean; unattended?: boolean; providerProfile?: string }, mute: (p: PeerAdapter) => void): Promise<Record<string, unknown>> {
+  async function startPeerBody(peer: string, args: { model?: string; route?: string; mode?: "headless" | "tui"; backend?: "auto" | "dgx" | "mlx"; sessionId?: string; sessionFile?: string; replaceSession?: boolean; fresh?: boolean; unattended?: boolean; providerProfile?: string }, mute: (p: PeerAdapter) => void): Promise<Record<string, unknown>> {
     if (peer === "jcode" && args.mode !== undefined && args.mode !== "headless") return { ok: false, error: "Jcode native TUI driving is unverified; use headless" };
     if (peer === "qwen" && args.mode !== undefined && args.mode !== "headless") return { ok: false, error: "Qwen TUI is not offered before its native verification; use ahub qwen --mode headless" };
     if (peer === "kimi") {
@@ -2581,7 +2590,18 @@ export async function startDaemon(opts: DaemonOptions) {
       if (args.model !== undefined && !["dgx/coding", "dgx/fast", "mlx/fast"].includes(args.model)) return { ok: false, error: "unknown Pi model alias" };
     }
     const existing = bus.peers.get(peer);
-    if (peer === "pi" && existing instanceof PiPeer) {
+    if (args.replaceSession) {
+      if (recoveryActive()) return { ok: false, error: "recovery is holding session replacement" };
+      if (!args.sessionFile || args.sessionId || args.fresh) return { ok: false, error: "Pi replacement requires --replace-session --session-file <managed-file>, without --session-id or fresh" };
+      if (!(existing instanceof PiPeer) || !existing.replacementReady || piReceipts?.unsettled || [...permissions.values()].some(p => p.peer === "pi")) return { ok: false, error: "Pi replacement requires an existing offline, settled owner with no live/unknown process, tools, receipts or approvals" };
+      const selected = validatePiSession(opts.stateDir, opts.cwd, args.sessionFile);
+      const previous = existing.recoveryMetadata();
+      recordPiReplacement(opts.stateDir, instanceId, previous, selected);
+      args = { ...args, ...selected };
+      mute(existing);
+      await stopPiForReplacement(existing);
+    }
+    if (peer === "pi" && existing instanceof PiPeer && !args.replaceSession) {
       let saved = existing.recoveryMetadata();
       const launch = saved.launch as Record<string, unknown>;
       if ((args.sessionId && saved.sessionId && args.sessionId !== saved.sessionId) || (args.sessionFile && saved.sessionFile && args.sessionFile !== saved.sessionFile)) return { ok: false, error: "Pi already owns a different session; refusing to replace its identity" };
@@ -3876,6 +3896,9 @@ export async function startDaemon(opts: DaemonOptions) {
         writeStatus(); // the claim has to be visible before the preface, or a standing-by session takes the id back
         void ensurePreface(c.peer).finally(() => {
           if (sock.readyState === WebSocket.OPEN && membershipAllowed(c.peer!)) ws.attach(sock);
+          // Important work queued while no session held the id gets its nudge now (#398); a push session ignores it.
+          const important = ws.owns(sock) ? bus.queuedImportant(c.peer!) : 0;
+          if (important) ws.notifyQueued({ queued: bus.queued(c.peer!), important });
         });
       }
       return void reply({ t: "welcome", projectId, instanceId, cwd: opts.cwd, protocol: PROTOCOL });
@@ -3935,7 +3958,7 @@ export async function startDaemon(opts: DaemonOptions) {
           peer.lastInboxAt = Date.now();
           writeStatus();
           if (envs.length) log(`${peer.id} read ${envs.length} queued message(s) through hub_inbox`);
-          return void reply({ ok: true, envs, waiting: bus.queued(peer.id) });
+          return void reply({ ok: true, envs, waiting: bus.queued(peer.id), waitingImportant: bus.queuedImportant(peer.id) });
         } catch { return void reply({ ok: false, error: "delivery journal unavailable" }); }
       }
       case "delivery_complete": {
@@ -4255,7 +4278,7 @@ export async function startDaemon(opts: DaemonOptions) {
         if (c.role !== "console") return void reply({ t: "started", ok: false, error: "start is a console command; use hub_peer_start with the conductor role" });
         if (recoveryActive() && !(recoveryPhase === "restored" && msg.operationId === recoveryOperationId)) return void reply({ t: "started", ok: false, error: "recovery is holding mutations" });
         if (recoveryActive() && !recoveryPeerAllowed(String(msg.peer))) return void reply({ t: "started", ok: false, error: "peer is not part of the recovery roster" });
-        startPeer(String(msg.peer), msg.args ?? {})
+        startPeer(String(msg.peer), msg.args ?? {}, msg.args?.replaceSession === true ? piReplacementAuthority : undefined)
           .catch((e: Error) => ({ ok: false, error: e.message }))
           .then((r) => {
             if (!r.ok) log(`start ${msg.peer} failed: ${r.error}`);

package/src/hub/ui.ts

@@ -6,8 +6,6 @@ import { PEER_START_RETRY_MS } from "./start-mode.ts";
 import { taskProgress } from "../ui/task-progress.ts";
 import { officeModel } from "../ui/office-model.ts";
 import { needs } from "../ui/needs.ts";
-import { CHARACTERS } from "../pet/characters.ts";
-import { petPixels } from "../pet/pixels.ts";
 import { createHash, randomBytes } from "node:crypto";
 import { readFileSync } from "node:fs";
 
@@ -41,7 +39,7 @@ export function startDashboard(options: DashboardOptions) {
     .replace("/* TASK_PROGRESS_MODEL */", () => `const taskProgress = ${taskProgress.toString()};`)
     .replace("/* PEER_START_RETRY_MS */", () => `const PEER_START_RETRY_MS = ${PEER_START_RETRY_MS};`)
     .replace("/* OFFICE_MODEL */", () => `const officeModel = ${officeModel.toString()};`)
-    .replace("/* PET_MODEL */", () => `const needs = ${needs.toString()}; const petCharacters = ${JSON.stringify(Object.fromEntries(Object.entries(CHARACTERS).map(([id, character]) => [id, { name: character.name, accent: character.accent, frames: { blocks: Object.fromEntries(Object.entries(character.frames.blocks).map(([pose, sizes]) => [pose, { full: sizes.full }])) } }])))}; const petPixels = ${petPixels.toString()};`);
+    .replace("/* NEEDS_MODEL */", () => `const needs = ${needs.toString()};`);
   const hashes = (tag: string) => [...html.matchAll(new RegExp(`<${tag}>([\\s\\S]*?)</${tag}>`, "g"))]
     .map((m) => `'sha256-${createHash("sha256").update(m[1]!).digest("base64")}'`).join(" ");
   const headers = {

package/src/pet/config.ts

@@ -1,14 +1,47 @@
-import { readFileSync } from "node:fs";
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
 import { join } from "node:path";
 import { characterId, type CharacterId, type PetSize, type PetGlyphs } from "./frame.ts";
 
-export interface PetConfig { enabled: boolean; blink: boolean; bell: boolean; character?: CharacterId; size?: PetSize; glyphs?: PetGlyphs; notice?: string }
+export type PetPalette = "blue" | "teal" | "violet" | "ochre";
+const PALETTES: Record<string, PetPalette> = { a: "blue", b: "teal", c: "violet", d: "ochre", blue: "blue", teal: "teal", violet: "violet", ochre: "ochre" };
+export function petPalette(value: unknown): PetPalette | undefined {
+  return typeof value === "string" ? PALETTES[value.toLowerCase()] : undefined;
+}
+export interface PetConfig { enabled: boolean; blink: boolean; bell: boolean; character?: CharacterId; size?: PetSize; glyphs?: PetGlyphs; palette?: PetPalette; notice?: string; window?: boolean }
+/** Console-local presentation only; it merges pet.palette into config.local.json and grants no authority. */
+export function savePetPalette(cwd: string, value: string): string {
+  const palette = petPalette(value);
+  if (!palette) throw new Error("Unknown pet palette; use blue, teal, violet or ochre (a/b/c/d).");
+  const dir = join(cwd, ".agenthub");
+  const path = join(dir, "config.local.json");
+  let file: Record<string, unknown> = {};
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("malformed");
+    file = parsed as Record<string, unknown>;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw new Error("Cannot update config.local.json; it is malformed.");
+  }
+  const pet = file.pet && typeof file.pet === "object" && !Array.isArray(file.pet) ? file.pet as Record<string, unknown> : {};
+  mkdirSync(dir, { recursive: true });
+  const temporary = join(dir, `config.local.${randomUUID()}.tmp`);
+  try {
+    writeFileSync(temporary, JSON.stringify({ ...file, pet: { ...pet, palette } }, null, 2) + "\n", { flag: "wx" });
+    renameSync(temporary, path);
+  } finally { rmSync(temporary, { force: true }); }
+  return `Pet palette set to ${palette}.`;
+}
 /** Console-local presentation only; this reader never writes config or grants authority. */
 export function loadPetConfig(cwd: string): PetConfig {
   let value: unknown;
+  let enabled = true;
   for (const name of ["config.json", "config.local.json"]) {
     try {
       const file = JSON.parse(readFileSync(join(cwd, ".agenthub", name), "utf8"));
+      // A window-only local opt-in does not undo inherited pet:false presentation.
+      if (file.pet === false) enabled = false;
+      else if (file.pet !== undefined && !(file.pet && typeof file.pet === "object" && !Array.isArray(file.pet) && Object.keys(file.pet).length === 1 && Object.hasOwn(file.pet, "window"))) enabled = true;
       if (file.pet !== undefined) value = value && typeof value === "object" && file.pet && typeof file.pet === "object" ? { ...value, ...file.pet } : file.pet;
     } catch (error) {
       if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
@@ -19,13 +52,17 @@ export function loadPetConfig(cwd: string): PetConfig {
   if (value === undefined) return defaults;
   if (!value || typeof value !== "object" || Array.isArray(value)) return { ...defaults, notice: "Unknown pet configuration; using stai line defaults." };
   const row = value as Record<string, unknown>;
-  const invalid = Object.keys(row).some(key => !["character", "size", "glyphs", "blink", "bell"].includes(key)) ||
+  const invalid = Object.keys(row).some(key => !["character", "size", "glyphs", "blink", "bell", "palette", "window"].includes(key)) ||
     row.character !== undefined && !characterId(row.character) || row.size !== undefined && !["line", "mini", "full"].includes(row.size as string) ||
     row.glyphs !== undefined && (typeof row.glyphs !== "string" || !["auto", "ascii", "blocks"].includes(row.glyphs)) ||
-    row.blink !== undefined && typeof row.blink !== "boolean" || row.bell !== undefined && typeof row.bell !== "boolean";
-  return { enabled: true, blink: typeof row.blink === "boolean" ? row.blink : true, bell: typeof row.bell === "boolean" ? row.bell : false,
+    row.palette !== undefined && !petPalette(row.palette) ||
+    row.blink !== undefined && typeof row.blink !== "boolean" || row.bell !== undefined && typeof row.bell !== "boolean" || row.window !== undefined && typeof row.window !== "boolean";
+  const palette = petPalette(row.palette);
+  return { enabled, blink: typeof row.blink === "boolean" ? row.blink : true, bell: typeof row.bell === "boolean" ? row.bell : false,
+    ...(typeof row.window === "boolean" ? { window: row.window } : {}),
     ...(characterId(row.character) && row.character !== "stai" ? { character: row.character } : {}),
     ...(row.size === "mini" || row.size === "full" ? { size: row.size } : {}),
     ...(row.glyphs === "ascii" || row.glyphs === "blocks" ? { glyphs: row.glyphs } : {}),
+    ...(palette && palette !== "teal" ? { palette } : {}),
     ...(invalid ? { notice: "Unknown pet option; using stai line defaults for that option." } : {}) };
 }

package/src/pet/window.html

@@ -0,0 +1,114 @@
+<!doctype html>
+<html lang="en">
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta http-equiv="Content-Security-Policy" content="default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; connect-src 'none'; base-uri 'none'; form-action 'none'">
+<title>agent-hub pet</title>
+<style>
+:root { color-scheme: dark; font: 12px system-ui, sans-serif; color: #eceef3; }
+html, body { margin: 0; background: transparent; overflow: hidden; }
+body { width: 150px; height: 150px; display: flex; align-items: center; flex-direction: column; justify-content: flex-end; gap: 4px; padding-bottom: 4px; box-sizing: border-box; }
+button { font: inherit; color: inherit; cursor: pointer; border: 0; background: transparent; border-radius: 10px; }
+button:focus-visible, input:focus-visible { outline: 2px solid #79dfb2; outline-offset: 2px; }
+#pet { width: 63px; height: 58px; padding: 0; cursor: grab; touch-action: none; }
+#pet:active { cursor: grabbing; }
+svg { width: 100%; height: 100%; overflow: visible; image-rendering: pixelated; filter: drop-shadow(0 1px 1px #687a78) drop-shadow(0 0 1px #687a78); }
+[data-palette="blue"] svg { filter: drop-shadow(0 1px 1px #64748b) drop-shadow(0 0 1px #64748b); }
+[data-palette="violet"] svg { filter: drop-shadow(0 1px 1px #796d8b) drop-shadow(0 0 1px #796d8b); }
+[data-palette="ochre"] svg { filter: drop-shadow(0 1px 1px #81725f) drop-shadow(0 0 1px #81725f); }
+rect { fill: #168b87; }
+[data-palette="blue"] rect { fill: #3979d6; }
+[data-palette="violet"] rect { fill: #8864cc; }
+[data-palette="ochre"] rect { fill: #be7a22; }
+[data-state="waiting"] rect { fill: #c4880f; }
+[data-state="blocked"] rect { fill: #cf6156; }
+[data-state="review"] rect { fill: #8a6cd8; }
+[data-state="offline"] rect { fill: #6f7787; }
+body[data-state="working"] #frame { animation: working-bob 0.7s steps(3, end) infinite; }
+@keyframes working-bob {
+  0%, 100% { transform: translateY(0); }
+  50% { transform: translateY(-4px); }
+}
+@media (prefers-reduced-motion: reduce) {
+  body[data-state="working"] #frame { animation: none; }
+}
+#pill { display: flex; align-items: center; gap: 4px; border-radius: 14px; padding: 3px 7px; background: #242936ed; font-size: 11px; }
+#pill button { padding: 2px 4px; }
+#composer { width: 100%; background: #242936f5; padding: 4px; border-radius: 10px; box-sizing: border-box; }
+#composer[hidden] { display: none; }
+/* Hidden by opacity only: visibility would drop the #state live region from the a11y tree. */
+#pill { opacity: 0; pointer-events: none; transition: opacity .12s ease; }
+#pet:hover ~ #pill, #pet:focus-visible ~ #pill, #pill:hover, #pill:focus-within, body[data-hover] #pill, body[data-composing] #pill { opacity: 1; pointer-events: auto; }
+input { width: 100%; box-sizing: border-box; border: 1px solid #657081; border-radius: 6px; padding: 5px; background: #111722; color: #eceef3; font: 13px system-ui; }
+#result { margin-top: 2px; min-height: 12px; font-size: 11px; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+</style>
+<button id="pet" aria-label="Open agent-hub dashboard"><svg id="frame" role="img" aria-label="Pet" viewBox="0 0 60 64"></svg></button>
+<div id="pill"><span id="state" aria-live="polite">Starting</span><button id="pencil" aria-label="Write a console message">✎</button><button id="close" aria-label="Close pet window">×</button></div>
+<div id="composer" hidden><input id="message" aria-label="Console message" placeholder="Message, Enter to send" maxlength="65536"><div id="result" role="status">Esc to cancel</div></div>
+<script>
+const post = body => window.webkit.messageHandlers.pet.postMessage(body);
+const pet = document.getElementById('pet'), frame = document.getElementById('frame'), pill = document.getElementById('pill');
+const state = document.getElementById('state'), composer = document.getElementById('composer'), input = document.getElementById('message'), result = document.getElementById('result');
+let signature = '', drag, sending = false;
+const draw = (x, y, w, h) => {
+  const rect = document.createElementNS('http://www.w3.org/2000/svg', 'rect');
+  rect.setAttribute('x', x); rect.setAttribute('y', y); rect.setAttribute('width', w); rect.setAttribute('height', h);
+  return rect;
+};
+window.update = view => {
+  if (view.offline) {
+    document.body.dataset.state = 'offline'; state.textContent = 'Offline';
+    document.getElementById('pencil').disabled = true; return;
+  }
+  document.getElementById('pencil').disabled = false;
+  document.body.dataset.state = view.state;
+  document.body.dataset.palette = view.palette;
+  state.textContent = view.state + (view.act ? ' · act ' + view.act : '') + (view.watch ? ' · watch ' + view.watch : '');
+  pet.setAttribute('aria-label', 'Open dashboard, ' + state.textContent);
+  const next = JSON.stringify(view.frame);
+  if (signature === next) return;
+  signature = next;
+  frame.setAttribute('viewBox', '0 0 ' + view.frame.width + ' ' + view.frame.height);
+  frame.replaceChildren(...view.frame.pixels.map(([x, y]) => draw(x, y, 1, 1)));
+};
+window.focusInput = () => { document.body.dataset.composing = ''; composer.hidden = false; input.focus(); };
+window.commandResult = ok => { sending = false; input.disabled = false; result.textContent = ok ? 'Sent' : 'Not confirmed; check the dashboard.'; if (ok) { input.value = ''; composer.hidden = true; delete document.body.dataset.composing; } };
+document.getElementById('pencil').addEventListener('click', () => post({ kind: 'pencil' }));
+document.getElementById('close').addEventListener('click', () => post({ kind: 'close' }));
+input.addEventListener('keydown', event => {
+  if (event.key === 'Escape') { composer.hidden = true; delete document.body.dataset.composing; pet.focus(); }
+  if (event.key === 'Enter' && !event.isComposing && input.value.trim() && !sending) {
+    event.preventDefault(); sending = true; input.disabled = true; result.textContent = 'Sending'; post({ kind: 'send', text: input.value });
+  }
+});
+// The native host polls the global mouse position against this rect (pet + pill) and
+// calls hoverChanged, because an inactive accessory panel never fires CSS :hover.
+window.hoverChanged = on => { if (on) document.body.dataset.hover = ''; else delete document.body.dataset.hover; };
+const postHotspot = () => {
+  const a = pet.getBoundingClientRect(), b = pill.getBoundingClientRect();
+  const x = Math.min(a.x, b.x), y = Math.min(a.y, b.y);
+  post({ kind: 'hotspot', x, y, w: Math.max(a.right, b.right) - x, h: Math.max(a.bottom, b.bottom) - y });
+};
+// While the panel is key, 1/2/3/4 switch the palette (blue/teal/violet/ochre) and save it.
+const KEY_PALETTES = { '1': 'blue', '2': 'teal', '3': 'violet', '4': 'ochre' };
+document.addEventListener('keydown', event => {
+  const palette = KEY_PALETTES[event.key];
+  if (!palette || event.target === input) return;
+  document.body.dataset.palette = palette;
+  post({ kind: 'palette', palette });
+});
+pet.addEventListener('pointerdown', event => { drag = { x: event.screenX, y: event.screenY, moved: false }; pet.setPointerCapture(event.pointerId); });
+pet.addEventListener('pointermove', event => {
+  if (!drag) return;
+  const dx = event.screenX - drag.x, dy = event.screenY - drag.y;
+  if (!dx && !dy) return;
+  drag.moved = true; drag.x = event.screenX; drag.y = event.screenY;
+  post({ kind: 'drag', dx, dy });
+});
+pet.addEventListener('pointerup', () => { const moved = drag?.moved; drag = null; if (!moved) post({ kind: 'open' }); });
+pet.addEventListener('pointercancel', () => { drag = null; });
+pet.addEventListener('keydown', event => { if (event.key === 'Enter' || event.key === ' ') { event.preventDefault(); post({ kind: 'open' }); } });
+postHotspot();
+post({ kind: 'ready' });
+</script>
+</html>

package/src/pet/window.jxa.js

@@ -0,0 +1,122 @@
+// Local AppKit/WebKit surface. No shell evaluation or remote content.
+ObjC.import('Cocoa');
+ObjC.import('WebKit');
+var panel, web, app, viewPath, positionPath, readyPath, cliArgv, timer, hoverTimer, bridge;
+var offlineAt = 0, commands = [], exiting = false, hotspot = null, hovering = false;
+function ignoreCompletion(result, error) {}
+function evaluate(source) { web.evaluateJavaScriptCompletionHandler(source, ignoreCompletion); }
+// An inactive accessory panel receives no mouse-moved events, so hover reveal is
+// polled from the global mouse position against the hotspot rect the page posts.
+function pollHover() {
+  if (!hotspot || exiting) return;
+  var mouse = $.NSEvent.mouseLocation, frame = panel.frame;
+  var x = mouse.x - frame.origin.x, y = frame.origin.y + frame.size.height - mouse.y;
+  var inside = x >= hotspot.x && x <= hotspot.x + hotspot.w && y >= hotspot.y && y <= hotspot.y + hotspot.h;
+  if (inside !== hovering) { hovering = inside; evaluate('hoverChanged(' + inside + ')'); }
+}
+function savePosition() {
+  var origin = panel.frame.origin;
+  $(JSON.stringify({ x: origin.x, y: origin.y })).writeToFileAtomicallyEncodingError(positionPath, true, $.NSUTF8StringEncoding, null);
+}
+function quit() { exiting = true; savePosition(); app.terminate(null); }
+function runCommand(command, extra, argv) {
+  if (exiting || commands.length >= 8) return;
+  var task = $.NSTask.alloc.init;
+  task.executableURL = $.NSURL.fileURLWithPath(argv[0]);
+  var args = argv.slice(1).concat([command]).concat(extra);
+  task.arguments = $(args); // argv array only; message text is a single argument.
+  task.standardInput = $.NSFileHandle.fileHandleWithNullDevice;
+  task.standardOutput = $.NSFileHandle.fileHandleWithNullDevice;
+  task.standardError = $.NSFileHandle.fileHandleWithNullDevice;
+  if (task.launchAndReturnError(null)) commands.push({ task: task, command: command });
+  else evaluate('commandResult(false)');
+}
+ObjC.registerSubclass({ name: 'AhubPetPanel', superclass: 'NSPanel', methods: {
+  canBecomeKeyWindow: { types: ['bool', []], implementation: function() { return true; } },
+  canBecomeMainWindow: { types: ['bool', []], implementation: function() { return false; } }
+} });
+// JXA cannot resolve WKScriptMessageHandler by name on some macOS versions;
+// WebKit invokes the exact Objective-C selector on this retained subclass.
+ObjC.registerSubclass({ name: 'AhubPetBridge', superclass: 'NSObject', methods: {
+  'userContentController:didReceiveScriptMessage:': { types: ['void', ['id', 'id']], implementation: function(controller, message) {
+    var body = ObjC.deepUnwrap(message.body);
+    if (!body || typeof body !== 'object' || exiting) return;
+    if (body.kind === 'ready') {
+      tick();
+      $('ready').writeToFileAtomicallyEncodingError(readyPath, true, $.NSUTF8StringEncoding, null);
+    } else if (body.kind === 'pencil') {
+      panel.orderFrontRegardless; panel.makeKeyWindow;
+      evaluate('focusInput()');
+    } else if (body.kind === 'drag' && typeof body.dx === 'number' && typeof body.dy === 'number' && isFinite(body.dx) && isFinite(body.dy) && Math.abs(body.dx) <= 2000 && Math.abs(body.dy) <= 2000) {
+      var origin = panel.frame.origin;
+      panel.setFrameOrigin($.NSMakePoint(origin.x + body.dx, origin.y - body.dy));
+      savePosition();
+    } else if (body.kind === 'hotspot' && typeof body.x === 'number' && typeof body.y === 'number' && typeof body.w === 'number' && typeof body.h === 'number' && isFinite(body.x) && isFinite(body.y) && Math.abs(body.x) <= 500 && Math.abs(body.y) <= 500 && body.w > 0 && body.h > 0 && body.w <= 500 && body.h <= 500) {
+      hotspot = { x: body.x, y: body.y, w: body.w, h: body.h };
+    } else if (body.kind === 'send' && typeof body.text === 'string' && body.text.trim() && body.text.length <= 65536 && body.text.indexOf('\0') === -1) {
+      runCommand('say', ['--', body.text], cliArgv);
+    } else if (body.kind === 'palette' && typeof body.palette === 'string' && /^(blue|teal|violet|ochre)$/.test(body.palette)) {
+      runCommand('pet', ['--palette', body.palette], cliArgv);
+    } else if (body.kind === 'open') runCommand('ui', [], cliArgv);
+    else if (body.kind === 'close') quit();
+  } },
+  'tick:': { types: ['void', ['id']], implementation: function(sender) { tick(); } },
+  'hover:': { types: ['void', ['id']], implementation: function(sender) { pollHover(); } }
+} });
+function tick() {
+  var value;
+  try { value = JSON.parse(ObjC.unwrap($.NSString.stringWithContentsOfFileEncodingError(viewPath, $.NSUTF8StringEncoding, null))); }
+  catch (error) { value = { offline: true }; }
+  evaluate('update(' + JSON.stringify(value) + ')');
+  if (value.offline === true) { if (!offlineAt) offlineAt = Date.now(); if (Date.now() - offlineAt >= 2000) quit(); }
+  else offlineAt = 0;
+  commands = commands.filter(function(item) {
+    if (item.task.isRunning) return true;
+    if (item.command === 'say') evaluate('commandResult(' + (Number(item.task.terminationStatus) === 0) + ')');
+    return false;
+  });
+}
+function run(argv) {
+  if (argv.length !== 3) throw new Error('Invalid pet window arguments');
+  viewPath = argv[0];
+  var htmlPath = argv[1];
+  cliArgv = JSON.parse(argv[2]);
+  if (!Array.isArray(cliArgv) || cliArgv.length !== 4 || cliArgv.some(function(arg) { return typeof arg !== 'string'; }) || cliArgv[2] !== '--project') throw new Error('Invalid CLI argv');
+  var stateDir = ObjC.unwrap($(viewPath).stringByDeletingLastPathComponent);
+  positionPath = stateDir + '/pet-window-pos.json';
+  var owner = JSON.parse(ObjC.unwrap($.NSString.stringWithContentsOfFileEncodingError(stateDir + '/pet-window.pid', $.NSUTF8StringEncoding, null)));
+  readyPath = stateDir + '/pet-window-ready-' + owner.token;
+  app = $.NSApplication.sharedApplication;
+  app.setActivationPolicy($.NSApplicationActivationPolicyAccessory);
+  var screen = $.NSScreen.mainScreen.visibleFrame;
+  var W = 150, H = 150;
+  var origin = { x: screen.origin.x + screen.size.width - (W + 20), y: screen.origin.y + 80 };
+  try {
+    var saved = JSON.parse(ObjC.unwrap($.NSString.stringWithContentsOfFileEncodingError(positionPath, $.NSUTF8StringEncoding, null)));
+    if (typeof saved.x === 'number' && typeof saved.y === 'number' && isFinite(saved.x) && isFinite(saved.y)) origin = saved;
+  } catch (error) {}
+  var screens = $.NSScreen.screens;
+  var visible = false;
+  for (var i = 0; i < screens.count; i++) {
+    var frame = screens.objectAtIndex(i).visibleFrame;
+    if (origin.x >= frame.origin.x && origin.y >= frame.origin.y && origin.x + W <= frame.origin.x + frame.size.width && origin.y + H <= frame.origin.y + frame.size.height) visible = true;
+  }
+  if (!visible) origin = { x: screen.origin.x + screen.size.width - (W + 20), y: screen.origin.y + 80 };
+  panel = $.AhubPetPanel.alloc.initWithContentRectStyleMaskBackingDefer($.NSMakeRect(origin.x, origin.y, W, H), $.NSWindowStyleMaskBorderless | $.NSWindowStyleMaskNonactivatingPanel, $.NSBackingStoreBuffered, false);
+  panel.title = 'agent-hub pet'; panel.opaque = false; panel.backgroundColor = $.NSColor.clearColor;
+  panel.level = $.NSFloatingWindowLevel;
+  panel.collectionBehavior = $.NSWindowCollectionBehaviorCanJoinAllSpaces | $.NSWindowCollectionBehaviorStationary;
+  panel.hidesOnDeactivate = false;
+  panel.acceptsMouseMovedEvents = true; // CSS :hover while key; pollHover() covers the inactive case
+  var config = $.WKWebViewConfiguration.alloc.init;
+  bridge = $.AhubPetBridge.alloc.init;
+  config.userContentController.addScriptMessageHandlerName(bridge, 'pet');
+  web = $.WKWebView.alloc.initWithFrameConfiguration($.NSMakeRect(0, 0, W, H), config);
+  web.setValueForKey(false, 'drawsBackground');
+  panel.contentView = web;
+  web.loadFileURLAllowingReadAccessToURL($.NSURL.fileURLWithPath(htmlPath), $.NSURL.fileURLWithPath(htmlPath));
+  panel.orderFrontRegardless; panel.makeKeyWindow;
+  timer = $.NSTimer.scheduledTimerWithTimeIntervalTargetSelectorUserInfoRepeats(1, bridge, 'tick:', null, true);
+  hoverTimer = $.NSTimer.scheduledTimerWithTimeIntervalTargetSelectorUserInfoRepeats(0.1, bridge, 'hover:', null, true);
+  app.run;
+}

package/src/pet/window.ts

@@ -0,0 +1,154 @@
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { readPet, type PetView } from "../cli/pet.ts";
+import { CHARACTERS, type CharacterId } from "./characters.ts";
+import { loadPetConfig, type PetConfig, type PetPalette } from "./config.ts";
+import { petPixels } from "./pixels.ts";
+import { processLiveness, processSignature } from "../pi/process-signature.ts";
+
+export const PET_WINDOW_UNSUPPORTED = "The floating pet window is supported only on macOS; use ahub pet in this terminal.";
+export type WindowView = { offline: true } | { state: NonNullable<PetView["summary"]>["state"]; act: number; watch: number; character: CharacterId; blink: boolean; palette: PetPalette; frame: ReturnType<typeof petPixels> };
+
+/** No ids, task text, paths or notices leave the existing readPet projection. */
+export function windowView(view: PetView, config: PetConfig, now = Date.now()): WindowView {
+  if (view.unavailable || !view.summary) return { offline: true };
+  const { state, act, watch } = view.summary;
+  const character = config.character ?? "stai";
+  const pose = state === "waiting" && config.blink && Math.floor(now / 1000) % 2 ? "waitingBlink" : state;
+  return { state, act, watch, character, blink: config.blink, palette: config.palette ?? "teal", frame: petPixels(CHARACTERS[character].frames.blocks[pose].full) };
+}
+
+export function writePetView(stateDir: string, view: WindowView): void {
+  const temporary = join(stateDir, `pet-view.${randomUUID()}.tmp`);
+  try {
+    writeFileSync(temporary, JSON.stringify(view), { flag: "wx", mode: 0o600 });
+    renameSync(temporary, join(stateDir, "pet-view.json"));
+  } finally { rmSync(temporary, { force: true }); }
+}
+
+interface WindowOwner { pid: number; signature: string; token: string; ready?: boolean }
+const ownerPath = (stateDir: string) => join(stateDir, "pet-window.pid");
+function readOwner(stateDir: string): WindowOwner | undefined {
+  try {
+    const row = JSON.parse(readFileSync(ownerPath(stateDir), "utf8"));
+    if (!Number.isSafeInteger(row.pid) || row.pid <= 0 || typeof row.signature !== "string" || !/^[a-f0-9]{64}$/.test(row.signature) || typeof row.token !== "string") throw new Error();
+    return row;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return;
+    throw new Error("Cannot confirm the pet window owner; pidfile retained.");
+  }
+}
+function removeOwner(stateDir: string, token: string): void {
+  if (readOwner(stateDir)?.token === token) rmSync(ownerPath(stateDir));
+}
+
+/** Exclusive creation, including during startup; stale owners require an explicit --close. */
+export function claimPetWindow(stateDir: string): { owner: WindowOwner; release(): void } | undefined {
+  mkdirSync(stateDir, { recursive: true, mode: 0o700 });
+  const signature = processSignature(process.pid);
+  if (!signature) throw new Error("Cannot confirm the pet window process identity.");
+  const owner: WindowOwner = { pid: process.pid, signature, token: randomUUID() };
+  try { writeFileSync(ownerPath(stateDir), JSON.stringify(owner), { flag: "wx", mode: 0o600 }); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+    const prior = readOwner(stateDir);
+    if (prior && processLiveness(prior.pid, prior.signature) === "live") return;
+    throw new Error("Pet window owner is stale or unconfirmed; run ahub pet --window --close before starting it.");
+  }
+  return { owner, release: () => removeOwner(stateDir, owner.token) };
+}
+
+export function petWindowArgv(projectDir: string): string[] {
+  return [process.execPath, join(import.meta.dir, "../cli/main.js"), "--project", projectDir];
+}
+
+/** Launch the host from the authorized CLI; never wait on or open the real JXA in tests. */
+export async function startPetWindow(stateDir: string, projectDir: string, platform: string = process.platform): Promise<string> {
+  if (platform !== "darwin") return PET_WINDOW_UNSUPPORTED;
+  const prior = readOwner(stateDir);
+  if (prior) {
+    if (processLiveness(prior.pid, prior.signature) === "live" && prior.ready) return "Pet window is already running.";
+    throw new Error("Pet window owner is starting, stale or unconfirmed; use --close before retrying.");
+  }
+  const child = spawn(process.execPath, [join(import.meta.dir, "window.ts"), stateDir, projectDir], { detached: true, stdio: "ignore" });
+  child.unref();
+  let failed = false;
+  child.on("error", () => { failed = true; });
+  const deadline = Date.now() + 5000;
+  while (Date.now() < deadline && !failed) {
+    const owner = readOwner(stateDir);
+    if (owner?.ready && processLiveness(owner.pid, owner.signature) === "live") return "Pet window started.";
+    if (child.exitCode !== null || child.signalCode !== null) break;
+    await Bun.sleep(50);
+  }
+  throw new Error("Pet window startup was not confirmed; use --close before retrying.");
+}
+
+export async function closePetWindow(stateDir: string, platform: string = process.platform): Promise<string> {
+  if (platform !== "darwin") return PET_WINDOW_UNSUPPORTED;
+  const owner = readOwner(stateDir);
+  if (!owner) return "Pet window is not running.";
+  const live = processLiveness(owner.pid, owner.signature);
+  if (live === "unknown") throw new Error("Cannot confirm the pet window owner; nothing was stopped.");
+  if (live === "live") {
+    process.kill(owner.pid, "SIGTERM");
+    const deadline = Date.now() + 5000;
+    while (Date.now() < deadline && processLiveness(owner.pid, owner.signature) !== "gone") await Bun.sleep(50);
+    if (processLiveness(owner.pid, owner.signature) !== "gone") throw new Error("Pet window stop was not confirmed; pidfile retained.");
+  }
+  removeOwner(stateDir, owner.token);
+  return "Pet window closed.";
+}
+
+export interface PetWindowHostOptions {
+  read?: () => PetView;
+  config?: () => PetConfig;
+  // Injectable child argv for process-level lifecycle tests; the CLI never accepts it.
+  childArgv?: string[];
+}
+export async function runPetWindowHost(stateDir: string, projectDir: string, options: PetWindowHostOptions = {}): Promise<void> {
+  const claim = claimPetWindow(stateDir);
+  if (!claim) return;
+  const readyFile = join(stateDir, `pet-window-ready-${claim.owner.token}`);
+  let child: ReturnType<typeof Bun.spawn> | undefined;
+  let timer: ReturnType<typeof setInterval> | undefined;
+  const refresh = () => {
+    let config: PetConfig;
+    try { config = (options.config ?? (() => loadPetConfig(projectDir)))(); }
+    catch { config = { enabled: true, blink: true, bell: false }; }
+    const view = (options.read ?? (() => readPet(stateDir)))();
+    writePetView(stateDir, windowView(view, config));
+  };
+  const stop = () => { if (timer) clearInterval(timer); child?.kill("SIGTERM"); };
+  try {
+    refresh();
+    child = Bun.spawn(options.childArgv ?? ["/usr/bin/osascript", "-l", "JavaScript", join(import.meta.dir, "window.jxa.js"), join(stateDir, "pet-view.json"), join(import.meta.dir, "window.html"), JSON.stringify(petWindowArgv(projectDir))], { cwd: projectDir, stdin: "ignore", stdout: "ignore", stderr: "ignore" });
+    process.on("SIGTERM", stop); process.on("SIGINT", stop);
+    timer = setInterval(() => { try { refresh(); } catch { stop(); } }, 1000);
+    // The child posts this file only once its panel and page have loaded.
+    const readyDeadline = Date.now() + 4000;
+    while (!existsSync(readyFile) && child.exitCode === null && Date.now() < readyDeadline) await Bun.sleep(50);
+    if (existsSync(readyFile)) {
+      rmSync(readyFile);
+      const temporary = join(stateDir, `pet-owner.${claim.owner.token}.tmp`);
+      try {
+        writeFileSync(temporary, JSON.stringify({ ...claim.owner, ready: true }), { flag: "wx", mode: 0o600 });
+        renameSync(temporary, ownerPath(stateDir));
+      } finally { rmSync(temporary, { force: true }); }
+    } else stop();
+    await child.exited;
+  } finally {
+    if (timer) clearInterval(timer);
+    process.off("SIGTERM", stop); process.off("SIGINT", stop);
+    rmSync(readyFile, { force: true });
+    claim.release();
+  }
+}
+
+if (import.meta.main) {
+  const [stateDir, projectDir] = process.argv.slice(2);
+  if (!stateDir || !projectDir || process.platform !== "darwin") process.exit(1);
+  try { await runPetWindowHost(stateDir, projectDir); } catch { process.exitCode = 1; }
+}