From 7e0e66997d7110001a6d37e6069403b1b61defe0 Mon Sep 17 00:00:00 2001 From: Joakim Persson Date: Mon, 7 Sep 2026 21:43:01 +0200 Subject: [PATCH] =?UTF-8?q?docs(env):=20name=20MEMPALACE=5FMAILBOX=5FNOTIF?= =?UTF-8?q?Y=20=E2=80=94=20auto-detect=20cannot=20work=20in=20a=20containe?= =?UTF-8?q?r?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Unset means the mailbox is silent outside the pi TUI, and the reason is structural: docker exec does not forward KITTY_WINDOW_ID/TERM_PROGRAM, so 'desktop' detection always falls through to OSC 777, which Kitty does not implement — the notification then silently does nothing, the worst failure for a feature whose only job is to break a silence. Documents the four modes, and that MEMPALACE_MAILBOX_POLL_MS is a FLOOR BETWEEN activity-coupled polls rather than a wall-clock interval (an idle session polls zero times) — the exact expectation mismatch reported today. --- .env.example | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/.env.example b/.env.example index 1f332f8..d745ee3 100644 --- a/.env.example +++ b/.env.example @@ -87,6 +87,35 @@ SSH_KEY_PATH=~/.ssh # MEMPALACE_PI_REMOTE_PATH=/data/feed # MEMPALACE_PI_DEVICE= +# ── Mailbox notification: MUST BE NAMED, auto-detect CANNOT work here ── +# The mempalace extension polls the logstream for fleet asks addressed to this +# device and queues them into the next turn. That part needs no config. The +# NOTIFICATION that tells the human it happened does, and unset means SILENT +# outside the pi TUI. +# +# Why there is no working default: terminal identity lives in env vars set by +# the emulator (KITTY_WINDOW_ID, TERM_PROGRAM) and `docker exec` does NOT +# forward them — inside the container pi sees only TERM=xterm-256color no matter +# what is rendering it. So "desktop" auto-detection always falls through to +# OSC 777, which Kitty does not implement, and the notification silently does +# nothing: the worst outcome for a feature whose only job is to break a silence. +# Naming the protocol is what makes it fire. +# +# kitty OSC 99 desktop notification (correct for Kitty, incl. over SSH) +# osc777 OSC 777 (tmux/iTerm2/foot and others) +# desktop OSC 99 if KITTY_WINDOW_ID is visible, else OSC 777 — inside a +# container that means effectively always OSC 777, so prefer naming +# 0 / off suppress entirely (in-TUI notify still shows) +# MEMPALACE_MAILBOX_NOTIFY=kitty +# +# Cadence, if the delivery ever feels late: the poll is coupled to session +# activity (it runs when the agent settles), NOT to a wall clock. +# MEMPALACE_MAILBOX_POLL_MS is therefore a FLOOR BETWEEN POLLS (default 300000), +# not a promise of one every 5 minutes — an idle session polls zero times, and +# session start does the first look. +# MEMPALACE_MAILBOX_POLL_MS=300000 +# MEMPALACE_MAILBOX_RESURFACE_MS=3600000 + # ── LAN access from the container (host-OS-agnostic) ───────────────── # On VM-backed hosts (macOS OrbStack / Docker Desktop) the container can't # reach the host's directly-attached LAN peers by default. The entrypoint