aibroker 0.58.1 → 0.60.0

package/dist/daemon/core-handlers.d.ts

@@ -20,6 +20,7 @@ import type { IpcServer } from "../ipc/server.js";
 import type { AdapterRegistry } from "./adapter-registry.js";
 import type { APIBackend } from "../backend/api.js";
 import type { HybridSessionManager } from "../core/hybrid.js";
+import type { SessionSnapshot } from "../adapters/iterm/core.js";
 import type { IpcRequest } from "../types/ipc.js";
 /**
  * Best human-readable identity for whoever made this call, for the audit trail.
@@ -57,10 +58,37 @@ export declare function callerItermId(req: IpcRequest): string | undefined;
  * demand to reply that the sender can never see), and no `[Session:...]`
  * prefix is typed (the prefix tells the receiving Claude to route a reply
  * back to a sender, but a beat's label is not a registered session).
+ *
+ * When a message IS deposited, only a one-line pointer is typed — never the
+ * full body. Typing the full body and pressing Enter submits it as an
+ * ordinary prompt, which fires the target's own `hooks/drain-mailbox.mjs`
+ * UserPromptSubmit hook on that same submission. That hook drains the very
+ * message this call just deposited and re-injects it as a system-reminder —
+ * so the full content showed up twice in one turn: once as the typed prompt,
+ * once again from the mailbox. Reproduced live 2026-09-23 on both an idle and
+ * a busy target — not a busy-only race. A short pointer and the deposited
+ * body are different strings, so the hook's drain is the only place the full
+ * content appears, and a multi-line body is never typed into a live pane at
+ * all — the failure mode where only the last line survived typing cannot
+ * recur here because there is nothing but one line to type.
  */
 export declare function sendToSessionDelivery(message: string, senderLabel: string, noReply: boolean): {
     typed: string;
     deposit: boolean;
 };
+/**
+ * The sender's identity for the mailbox "from" field and the `[Session:X]`
+ * prefix — bare, unlike callerLabel()'s `session:`-prefixed audit actor.
+ *
+ * paiName first, then the session's own stable id — never the raw iTerm
+ * name/title, which is the terminal's OWN dynamic display text (a spinner
+ * glyph plus tab title for a busy Claude Code session) and not an identity.
+ * A sender not found in the live snapshot (worker child process, or a bare
+ * CLI call with no pane at all) falls back to whatever id it claimed — for a
+ * worker that id is a fabricated, non-live marker (see ipc/client.ts), so it
+ * naturally fails to match any session and a reply to it is refused rather
+ * than silently reaching the wrong pane.
+ */
+export declare function resolveSenderLabel(req: IpcRequest, snapshots: SessionSnapshot[]): string;
 export declare function registerCoreHandlers(server: IpcServer, registry: AdapterRegistry, _apiBackend: APIBackend, manager: HybridSessionManager): void;
 //# sourceMappingURL=core-handlers.d.ts.map

package/dist/daemon/core-handlers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"core-handlers.d.ts","sourceRoot":"","sources":["../../src/daemon/core-handlers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAoB9D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AA0ClD;;;;;GAKG;AACH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,GAAG,SAAS,CAIjE;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,OAAO,GACf;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAIrC;AAgBD,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,SAAS,EACjB,QAAQ,EAAE,eAAe,EACzB,WAAW,EAAE,UAAU,EACvB,OAAO,EAAE,oBAAoB,GAC5B,IAAI,CAy6DN"}
+{"version":3,"file":"core-handlers.d.ts","sourceRoot":"","sources":["../../src/daemon/core-handlers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAiB9D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAIjE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AA0ClD;;;;;GAKG;AACH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,GAAG,SAAS,CAIjE;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,OAAO,GACf;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAIrC;AAmBD;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,UAAU,EAAE,SAAS,EAAE,eAAe,EAAE,GAAG,MAAM,CAKxF;AAED,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,SAAS,EACjB,QAAQ,EAAE,eAAe,EACzB,WAAW,EAAE,UAAU,EACvB,OAAO,EAAE,oBAAoB,GAC5B,IAAI,CAuiEN"}

package/dist/daemon/core-handlers.js

@@ -23,7 +23,7 @@ import { broadcastStatus, broadcastVoice, broadcastImage, broadcastText, handleM
 import { mqttRequestDebugState } from "../adapters/pailot/mqtt-broker.js";
 import { WatcherClient } from "../ipc/client.js";
 import { saveVoiceConfig, setPersistentSessionName, getPersistentSessionName, getAllPersistentSessionNames, removePersistentSessionName, lookupPersistentName } from "../core/persistence.js";
-import { voiceConfig, setVoiceConfig, activeItermSessionId, lastRoutedSessionId, getAibpBridge, depositToSessionMailbox, drainSessionMailbox } from "../core/state.js";
+import { voiceConfig, setVoiceConfig, activeItermSessionId, lastRoutedSessionId, getAibpBridge, depositToSessionMailbox, drainSessionMailbox, peekSessionMailbox } from "../core/state.js";
 import { splitIntoChunks } from "../adapters/kokoro/media.js";
 import { stripMarkdown } from "../core/markdown.js";
 import { listPaiProjects, findPaiProject, launchPaiProject } from "./pai-projects.js";
@@ -31,7 +31,7 @@ import { readSessionContent, readAllSessionContent } from "./session-content.js"
 import { promptUnsentText, inputLineDecision } from "./manage.js";
 import { statusCache, hashContent } from "../core/status-cache.js";
 import { clearAllPaiNames } from "../adapters/iterm/core.js";
-import { snapshotAllSessions, setSessionTitle, itermViewerSessionId, aibrokerIdForPane, isClaudeSession } from "../transport/sync-facade.js";
+import { snapshotAllSessions, setSessionTitle, itermViewerSessionId, aibrokerIdForPane, isClaudeSession, wasLastEnumerationReliable } from "../transport/sync-facade.js";
 import { matchSession, resolveCallerSession } from "../core/session-match.js";
 import { audit, noteInbound } from "./audit.js";
 import { setItermSessionVar, setItermTabName, setItermBadge, revealItermSession } from "../adapters/iterm/sessions.js";
@@ -105,11 +105,24 @@ export function callerItermId(req) {
  * demand to reply that the sender can never see), and no `[Session:...]`
  * prefix is typed (the prefix tells the receiving Claude to route a reply
  * back to a sender, but a beat's label is not a registered session).
+ *
+ * When a message IS deposited, only a one-line pointer is typed — never the
+ * full body. Typing the full body and pressing Enter submits it as an
+ * ordinary prompt, which fires the target's own `hooks/drain-mailbox.mjs`
+ * UserPromptSubmit hook on that same submission. That hook drains the very
+ * message this call just deposited and re-injects it as a system-reminder —
+ * so the full content showed up twice in one turn: once as the typed prompt,
+ * once again from the mailbox. Reproduced live 2026-09-23 on both an idle and
+ * a busy target — not a busy-only race. A short pointer and the deposited
+ * body are different strings, so the hook's drain is the only place the full
+ * content appears, and a multi-line body is never typed into a live pane at
+ * all — the failure mode where only the last line survived typing cannot
+ * recur here because there is nothing but one line to type.
  */
 export function sendToSessionDelivery(message, senderLabel, noReply) {
     return noReply
         ? { typed: message, deposit: false }
-        : { typed: `[Session:${senderLabel}] ${message}`, deposit: true };
+        : { typed: `[Session:${senderLabel}] message in your mailbox — shown above if your drain hook ran, otherwise read with aibroker_receive`, deposit: true };
 }
 function callerLabel(req) {
     const id = callerItermId(req);
@@ -119,11 +132,34 @@ function callerLabel(req) {
             const paiName = lookupPersistentName(getAllPersistentSessionNames(), snap.id, snap.aibrokerId);
             // Namespaced per the audit multi-writer contract: bare names collide
             // across producers once more than one writes to the trail.
-            return `session:${paiName ?? snap.name}`;
+            // snap.id, not snap.name: the raw iTerm name reflects the terminal's
+            // OWN dynamic title (spinner glyph + tab title for a Claude Code
+            // session — "◑ Generic session content (claude)"), not an identity.
+            return `session:${paiName ?? snap.id}`;
         }
     }
     return `session:${id ?? req.tmuxPane ?? req.sessionId ?? "unknown"}`;
 }
+/**
+ * The sender's identity for the mailbox "from" field and the `[Session:X]`
+ * prefix — bare, unlike callerLabel()'s `session:`-prefixed audit actor.
+ *
+ * paiName first, then the session's own stable id — never the raw iTerm
+ * name/title, which is the terminal's OWN dynamic display text (a spinner
+ * glyph plus tab title for a busy Claude Code session) and not an identity.
+ * A sender not found in the live snapshot (worker child process, or a bare
+ * CLI call with no pane at all) falls back to whatever id it claimed — for a
+ * worker that id is a fabricated, non-live marker (see ipc/client.ts), so it
+ * naturally fails to match any session and a reply to it is refused rather
+ * than silently reaching the wrong pane.
+ */
+export function resolveSenderLabel(req, snapshots) {
+    const senderItermId = callerItermId(req);
+    const senderSnap = senderItermId ? snapshots.find((s) => s.id === senderItermId) : undefined;
+    if (senderSnap)
+        return senderSnap.paiName ?? senderSnap.id;
+    return senderItermId ?? "unknown";
+}
 export function registerCoreHandlers(server, registry, _apiBackend, manager) {
     server.on("register_adapter", async (req) => {
         const { name, socketPath } = req.params;
@@ -152,7 +188,11 @@ export function registerCoreHandlers(server, registry, _apiBackend, manager) {
             return {
                 index: i + 1,
                 sessionId: s.id,
-                name: s.name,
+                // A chosen name IS the session's name; the tab title (auto-titler,
+                // process string) is only what it falls back to. Raw title stays
+                // beside it so a lying display can be told from a lying name.
+                name: paiName ?? s.tabTitle ?? s.name,
+                tabTitle: s.tabTitle,
                 paiName,
                 atPrompt: s.atPrompt,
                 // Measured first, guessed only when there is no measurement: a pane
@@ -162,7 +202,19 @@ export function registerCoreHandlers(server, registry, _apiBackend, manager) {
                 active: s.id === activeItermSessionId,
             };
         });
-        return { ok: true, result: { sessions } };
+        // A failed osascript enumeration reads identically to a truly empty
+        // machine unless this says otherwise — see wasLastEnumerationReliable().
+        const enumerationFailed = !wasLastEnumerationReliable();
+        return {
+            ok: true,
+            result: {
+                sessions,
+                enumerationFailed,
+                ...(enumerationFailed
+                    ? { enumerationDetail: "iTerm AppleScript enumeration failed; list may be incomplete" }
+                    : {}),
+            },
+        };
     });
     server.on("switch", async (req) => {
         const { target } = req.params;
@@ -230,10 +282,15 @@ export function registerCoreHandlers(server, registry, _apiBackend, manager) {
         const live = snapshotAllSessions();
         const persistentNames = getAllPersistentSessionNames();
         const activeSnap = live.find((s) => s.id === activeItermSessionId);
+        // Same reliability flag the `sessions` handler reports — the hub is only
+        // as healthy as its ability to see what is actually running.
+        const enumerationOk = wasLastEnumerationReliable();
         return {
             ok: true,
             result: {
                 version: HUB_VERSION,
+                status: enumerationOk ? "ok" : "degraded",
+                ...(enumerationOk ? {} : { detail: "iTerm AppleScript session enumeration is failing; session list may be stale or incomplete" }),
                 adapters: registry.list().map(a => a.name),
                 activeSessions: live.length,
                 activeSession: activeSnap
@@ -648,6 +705,18 @@ export function registerCoreHandlers(server, registry, _apiBackend, manager) {
     server.on("session_content", async (req) => {
         const { sessionId, lines } = req.params;
         const lineCount = lines ?? 100;
+        // Display fields follow the same authority as the `sessions` handler: the
+        // chosen (persistent) name first, then the tab title, with the raw title
+        // kept in tabTitle. The content read reports the terminal's own process
+        // name, which is not what a human calls the session.
+        const snaps = new Map(snapshotAllSessions().map((s) => [s.id, s]));
+        const persistentNames = getAllPersistentSessionNames();
+        const display = (id, raw) => {
+            const snap = snaps.get(id);
+            const paiName = lookupPersistentName(persistentNames, id, snap?.aibrokerId) ?? raw.paiName;
+            const tabTitle = snap?.tabTitle ?? null;
+            return { name: paiName ?? tabTitle ?? raw.name, tabTitle, paiName };
+        };
         if (sessionId) {
             const content = readSessionContent(sessionId, lineCount);
             if (!content)
@@ -663,6 +732,7 @@ export function registerCoreHandlers(server, registry, _apiBackend, manager) {
                 result: {
                     session: {
                         ...content,
+                        ...display(sessionId, content),
                         contentHash,
                         changed,
                         cachedSummary: cached?.summary ?? null,
@@ -681,6 +751,7 @@ export function registerCoreHandlers(server, registry, _apiBackend, manager) {
                 statusCache.touch(c.sessionId);
             return {
                 ...c,
+                ...display(c.sessionId, c),
                 contentHash,
                 changed,
                 cachedSummary: cached?.summary ?? null,
@@ -850,11 +921,12 @@ export function registerCoreHandlers(server, registry, _apiBackend, manager) {
      * sendToSessionDelivery() for why both matter for a beat.
      */
     server.on("send_to_session", async (req) => {
-        const { target, message, noReply = false } = req.params;
-        if (!target)
+        const { target: targetParam, message, noReply = false } = req.params;
+        if (!targetParam)
             return { ok: false, error: "target is required" };
         if (!message)
             return { ok: false, error: "message is required" };
+        const target = targetParam;
         /**
          * `peer/session` goes to that machine, everything else stays here.
          *
@@ -873,38 +945,30 @@ export function registerCoreHandlers(server, registry, _apiBackend, manager) {
                     : { ok: false, error: forwarded.error ?? "the peer refused it" };
             }
         }
-        const snapshots = snapshotAllSessions();
         // Enrich with persistent names so target-by-name matches a renamed session
         // (tmux names key on the durable @aibroker_id, not the volatile pane id).
-        const persistentNames = getAllPersistentSessionNames();
-        for (const snap of snapshots) {
-            snap.paiName = lookupPersistentName(persistentNames, snap.id, snap.aibrokerId);
-        }
-        let itermSessionId = null;
-        let resolvedName = null;
-        const asNumber = parseInt(target, 10);
-        if (!Number.isNaN(asNumber) && String(asNumber) === target.trim()) {
-            // Numeric index (1-based)
-            const snap = snapshots[asNumber - 1];
-            if (snap) {
-                itermSessionId = snap.id;
-                resolvedName = snap.paiName ?? snap.name;
+        function withPersistentNames(snaps) {
+            const persistentNames = getAllPersistentSessionNames();
+            for (const snap of snaps) {
+                snap.paiName = lookupPersistentName(persistentNames, snap.id, snap.aibrokerId);
             }
-        }
-        else if (/^[0-9A-Fa-f-]{20,}$/.test(target)) {
-            // Looks like an iTerm UUID — use directly if it exists
-            const snap = snapshots.find((s) => s.id === target);
-            if (snap) {
-                itermSessionId = snap.id;
-                resolvedName = snap.paiName ?? snap.name;
+            return snaps;
+        }
+        function resolveTarget(snaps) {
+            const asNumber = parseInt(target, 10);
+            if (!Number.isNaN(asNumber) && String(asNumber) === target.trim()) {
+                // Numeric index (1-based)
+                const snap = snaps[asNumber - 1];
+                return snap ? { id: snap.id, name: snap.paiName ?? snap.name } : { id: null, name: null };
             }
-            else {
+            if (/^[0-9A-Fa-f-]{20,}$/.test(target)) {
+                // Looks like an iTerm UUID — use directly if it exists
+                const snap = snaps.find((s) => s.id === target);
+                if (snap)
+                    return { id: snap.id, name: snap.paiName ?? snap.name };
                 // Trust the caller — they may have a valid ID not yet in the snapshot
-                itermSessionId = target;
-                resolvedName = target;
+                return { id: target, name: target };
             }
-        }
-        else {
             // Name match, case-insensitive, preferring paiName over the raw name.
             //
             // Ranked rather than first-match. A substring search over every tab will
@@ -920,31 +984,68 @@ export function registerCoreHandlers(server, registry, _apiBackend, manager) {
             // `prefer` is what keeps a live Claude session ahead of a shell, and
             // substring is enabled here (unlike dispatch) because a human typing a
             // target expects "clickr" to find "Clickr (node)".
-            const best = matchSession([target], snapshots, {
+            const best = matchSession([target], snaps, {
                 kinds: ["exact", "normalised", "substring"],
                 prefer: (s) => (isClaudeSession(s.id) ? 1 : 0),
             });
-            if (best) {
-                itermSessionId = best.session.id;
-                resolvedName = best.label;
-            }
+            return best ? { id: best.session.id, name: best.label } : { id: null, name: null };
+        }
+        let snapshots = withPersistentNames(snapshotAllSessions());
+        let { id: itermSessionId, name: resolvedName } = resolveTarget(snapshots);
+        /*
+         * A failed/empty enumeration must not read as "no such session". Observed
+         * live: `send_to_session` reported target "AIBroker" not found, with an
+         * EMPTY session list, while that session was live — a listing seconds
+         * later (past the snapshot cache TTL) showed 14 sessions. Retry fresh a
+         * couple of times before giving up, since osascript failures are usually
+         * transient (iTerm busy, a slow poll).
+         */
+        for (let attempt = 0; !itermSessionId && !wasLastEnumerationReliable() && attempt < 2; attempt++) {
+            await new Promise((r) => setTimeout(r, 400));
+            snapshots = withPersistentNames(snapshotAllSessions({ fresh: true }));
+            ({ id: itermSessionId, name: resolvedName } = resolveTarget(snapshots));
         }
         if (!itermSessionId) {
+            // Still nothing — but if the enumeration itself never came back
+            // reliable, "not found" is a lie: iTerm never actually answered, so
+            // there is no evidence the target doesn't exist. Queue by the
+            // requested name instead of dropping it, using the id the session was
+            // last known under (persisted names survive an enumeration outage).
+            if (!wasLastEnumerationReliable()) {
+                const persistedId = Object.entries(getAllPersistentSessionNames())
+                    .find(([, name]) => name.toLowerCase() === target.toLowerCase())?.[0];
+                if (persistedId) {
+                    const senderLabel = resolveSenderLabel(req, snapshots);
+                    const evicted = depositToSessionMailbox(persistedId, senderLabel, message);
+                    if (evicted) {
+                        audit({
+                            action: "send", actor: `session:${evicted.from}`, target,
+                            outcome: "evicted", body: evicted.content,
+                            reason: "mailbox full — oldest undrained message discarded to make room",
+                        });
+                    }
+                    audit({
+                        action: "send", actor: `session:${senderLabel}`, target,
+                        outcome: "queued", body: message,
+                        reason: "iTerm enumeration was unreliable — could not confirm the session is live, queued by its last known id",
+                    });
+                    return {
+                        ok: true,
+                        result: {
+                            sent: true, delivered: false, queued: true,
+                            sessionId: persistedId, name: target,
+                            note: "iTerm did not answer reliably, so this could not be typed. Queued in the session's mailbox by its last known name; readable with aibroker_receive once it's live.",
+                        },
+                    };
+                }
+            }
             return {
                 ok: false,
                 error: `Session "${target}" not found. Available sessions: ${snapshots.map((s, i) => `${i + 1}:${s.paiName ?? s.name}`).join(", ")}`,
             };
         }
         // Resolve the sender's name for the mailbox "from" label and the prefix.
-        // Takes the id from either field — see callerItermId for why that matters
-        // and what it looks like when it does not happen.
-        const senderItermId = callerItermId(req);
-        const senderSnap = senderItermId
-            ? snapshots.find((s) => s.id === senderItermId)
-            : undefined;
-        const senderLabel = senderSnap
-            ? (senderSnap.paiName ?? senderSnap.name)
-            : (senderItermId ?? "unknown");
+        const senderLabel = resolveSenderLabel(req, snapshots);
         // Refuse before depositing OR typing: if the target is a shell, the message
         // is not merely undeliverable, it is executable. Say so plainly rather than
         // reporting a generic write failure.
@@ -1076,6 +1177,13 @@ export function registerCoreHandlers(server, registry, _apiBackend, manager) {
      *
      * Returns all pending messages deposited by send_to_session from other sessions.
      * The queue is cleared on read (drain semantics). Returns empty array if no messages.
+     * Destructive in one call — interactive callers (aibroker_receive) only.
+     *
+     * The drain-mailbox hook must NOT use this: its 1.5 s client timeout can fire
+     * after the daemon has already emptied the mailbox, losing the message (live
+     * 2026-09-25). The hook uses the two-phase pair below instead:
+     * session_mailbox_peek (read without clearing) → emit → session_mailbox_ack
+     * (clear what was peeked). A lost ack means redelivery, not loss.
      *
      * The caller's iTerm session ID is taken from req.itermSessionId (set by IPC server
      * from the session context) or from the explicit sessionId param as a fallback.
@@ -1083,17 +1191,44 @@ export function registerCoreHandlers(server, registry, _apiBackend, manager) {
      * iTerm2 session IDs in env vars have the form "w0t0p0:UUID". We normalize to just
      * the UUID so mailbox keys match snapshot IDs.
      */
-    server.on("session_mailbox_receive", async (req) => {
+    const mailboxSessionId = (req) => {
         const { sessionId: explicitSessionId } = req.params;
         const rawId = req.itermSessionId ?? explicitSessionId ?? req.sessionId;
-        if (!rawId) {
+        if (!rawId)
+            return undefined;
+        // Normalize "w0t0p0:UUID" → "UUID"
+        return rawId.includes(":") ? rawId.split(":").pop() : rawId;
+    };
+    server.on("session_mailbox_receive", async (req) => {
+        const itermSessionId = mailboxSessionId(req);
+        if (!itermSessionId) {
             return { ok: false, error: "Cannot determine session ID — pass sessionId param or run inside an iTerm session" };
         }
-        // Normalize "w0t0p0:UUID" → "UUID"
-        const itermSessionId = rawId.includes(":") ? rawId.split(":").pop() : rawId;
         const messages = drainSessionMailbox(itermSessionId);
         return { ok: true, result: { messages, sessionId: itermSessionId } };
     });
+    /** Phase 1 of the hook's drain: return the pending messages WITHOUT clearing. */
+    server.on("session_mailbox_peek", async (req) => {
+        const itermSessionId = mailboxSessionId(req);
+        if (!itermSessionId) {
+            return { ok: false, error: "Cannot determine session ID — pass sessionId param or run inside an iTerm session" };
+        }
+        return { ok: true, result: { messages: peekSessionMailbox(itermSessionId), sessionId: itermSessionId } };
+    });
+    /**
+     * Phase 2 of the hook's drain: clear what was peeked, return how many went.
+     * An optional count clears only the oldest N, so a message deposited after
+     * the peek survives for the next one.
+     */
+    server.on("session_mailbox_ack", async (req) => {
+        const itermSessionId = mailboxSessionId(req);
+        if (!itermSessionId) {
+            return { ok: false, error: "Cannot determine session ID — pass sessionId param or run inside an iTerm session" };
+        }
+        const { count } = req.params;
+        const cleared = drainSessionMailbox(itermSessionId, count).length;
+        return { ok: true, result: { cleared, sessionId: itermSessionId } };
+    });
     // ── Unified MCP Support ──
     /**
      * adapter_call — Proxy an IPC call to a named adapter through the hub.
@@ -1465,7 +1600,16 @@ export function registerCoreHandlers(server, registry, _apiBackend, manager) {
         if (req.tmuxPane) {
             const tmuxPane = req.tmuxPane;
             const durableId = aibrokerIdForPane(tmuxPane) ?? tmuxPane;
-            setPersistentSessionName(durableId, name);
+            // One name, one live holder: refused here while another live session owns
+            // it (2026-09-26 — a second tab took a live session's name, and the parked
+            // sweeps two mornings later traced back to exactly that write).
+            const claim = setPersistentSessionName(durableId, name);
+            if (!claim.ok) {
+                return {
+                    ok: false,
+                    error: `Name "${name}" is held by live session ${claim.heldBy?.slice(0, 8) ?? "unknown"} — release it there first (close that tab, or rename it).`,
+                };
+            }
             setSessionTitle(tmuxPane, name);
             manager.updateName(durableId, name);
             // Visible surfaces: if this pane is being viewed in an iTerm tab, set the
@@ -1516,6 +1660,24 @@ export function registerCoreHandlers(server, registry, _apiBackend, manager) {
             log(`rename: caller claimed session ${claimedId.slice(0, 8)}, which is not open; ` +
                 `using ${itermSessionId.slice(0, 8)} found via tty ${req.callerTty}`);
         }
+        // One name, one live holder. The claim is checked BEFORE any surface is
+        // written: on 2026-09-26 21:07 a second tab registered a name a live session
+        // had held for days, the store then answered the name with both ids, and a
+        // daemon restart bound dispatch to the newcomer — which was at a shell by
+        // morning, so both daily sweeps parked without the real session ever being
+        // asked. Refused here, the existing holder keeps the name untouched.
+        let nameClaim = { ok: true };
+        if (itermSessionId) {
+            nameClaim = setPersistentSessionName(itermSessionId, name);
+            if (!nameClaim.ok) {
+                log(`rename: refused — name "${name}" held by live session ${nameClaim.heldBy?.slice(0, 8)}`);
+                return {
+                    ok: false,
+                    error: `Name "${name}" is held by live session ${nameClaim.heldBy?.slice(0, 8) ?? "unknown"} — release it there first (close that tab, or rename it).`,
+                };
+            }
+            log(`Persisted name "${name}" for iTerm session ${itermSessionId.slice(0, 8)}`);
+        }
         // Update in hub's session manager
         if (itermSessionId) {
             // updateName searches by backendSessionId (iTerm2 UUID)
@@ -1526,12 +1688,6 @@ export function registerCoreHandlers(server, registry, _apiBackend, manager) {
             if (session)
                 manager.updateName(session.id, name);
         }
-        // Persist the user-chosen name so it survives daemon restarts and
-        // can be re-asserted after Claude Code's auto-title overwrites it.
-        if (itermSessionId) {
-            setPersistentSessionName(itermSessionId, name);
-            log(`Persisted name "${name}" for iTerm session ${itermSessionId.slice(0, 8)}`);
-        }
         // Set iTerm2 visuals directly if we know the session
         if (itermSessionId) {
             setItermSessionVar(itermSessionId, name);