mellos-mapping 0.27.0 → 0.28.0

package/README.md

@@ -337,8 +337,8 @@ get the eight `mmap_*` tools and the pane, and bring their own prompting.
    opens or retargets the pane with `mmap_open` when nobody is — you never
    have to remember to. Open or close it yourself with `mmap` in any
    terminal, or `/mellos-mapping:mmap` in the conversation (Windows
-   Terminal split on Windows, tmux split inside tmux, or a printed command
-   to run in any second terminal). On Windows the pane opens in the terminal
+   Terminal split on Windows, tmux split inside tmux, a Pebrel split inside
+   Pebrel, or a printed command to run in any second terminal). On Windows the pane opens in the terminal
    window hosting YOUR session, even with several windows open; pass
    `--window` to put the map in its own dedicated window instead. Prefer
    `--ascii` if your font lacks box-drawing glyphs.
@@ -359,6 +359,13 @@ the environment of the MCP server (restart it after changing them):
 | `MELLOS_MAPPING_TMUX_TARGET` | Explicit tmux session or pane, such as `work:2.1` or `%7` |
 | `MELLOS_MAPPING_TMUX_SOCKET` | Absolute socket path, for example `/tmp/my-tmux/socket` |
 
+Inside [Pebrel](https://github.com/Kuddev/pebrel), `mmap_open` and `mmap` split the pane that hosts
+the conversation through Pebrel's runtime CLI (`PEBREL_CLI`). The launcher
+confirms which window that pane is in from its process tree, returns input focus
+to the conversation and types the watcher into the new pane's shell (PowerShell,
+cmd or a POSIX shell), which exits with it so the pane closes with the map.
+`--window` opens a new Pebrel window. Inside tmux, tmux owns the split.
+
 Ambiguous sessions, detached sessions and missing tmux produce a concrete error
 and a fully quoted watcher command, including the project and requested page,
 to paste into any visible terminal. Map writes remain available; after an open

package/README.zh-CN.md

@@ -310,8 +310,8 @@ npx -y -p mellos-mapping mellos-mapping-watch
    （见[谁在看](#谁在看)）；没人看的时候，Claude 用 `mmap_open` 自己
    把面板开出来或切到该看的那一页——你不需要记着去开它。想自己开关，
    在任意终端敲 `mmap`，或者在对话里用 `/mellos-mapping:mmap`
-   （Windows 上是 Windows Terminal 分屏，tmux 里是 tmux 分屏，其他
-   环境会打印一条命令让你在第二个终端里运行）。Windows 上即使开着多个
+   （Windows 上是 Windows Terminal 分屏，tmux 里是 tmux 分屏，Pebrel 里
+   是 Pebrel 分屏，其他环境会打印一条命令让你在第二个终端里运行）。Windows 上即使开着多个
    终端窗口，分屏也会落在**你的会话所在的窗口**；想让地图独占一个窗口
    就加 `--window`。字体缺少制表符字形时用 `--ascii`。
 3. 看着节点从底部一路亮起。图让你不安的时候就打断它——这正是它存在的
@@ -330,6 +330,12 @@ tmux 服务中唯一已连接的会话。默认在右侧分屏并保留输入焦
 | `MELLOS_MAPPING_TMUX_TARGET` | 指定 tmux 会话或面板，例如 `work:2.1` 或 `%7` |
 | `MELLOS_MAPPING_TMUX_SOCKET` | socket 的绝对路径，例如 `/tmp/my-tmux/socket` |
 
+在 [Pebrel](https://github.com/Kuddev/pebrel) 里，`mmap_open` 与 `mmap` 通过 Pebrel 运行时 CLI
+（`PEBREL_CLI`）分屏承载本会话的面板。启动器用进程树确认该面板所在的窗口，
+把输入焦点还给对话，再把 watcher 命令输入新面板的 shell（PowerShell、cmd
+或 POSIX shell）；shell 随 watcher 一起退出，地图关闭时面板也随之关闭。
+`--window` 会新开一个 Pebrel 窗口。在 tmux 里则由 tmux 负责分屏。
+
 目标不明确、会话未连接或没有安装 tmux 时，启动器会返回具体原因，以及
 包含项目、页面和正确引号的一条完整 watcher 命令，可以粘贴到可见终端。
 地图仍可正常写入；打开失败后，助手只在环境变化或你要求重试时再次打开。

package/commands/mmap.md

@@ -104,7 +104,12 @@ Follow the platform-appropriate route:
    also set `MELLOS_MAPPING_TMUX_SOCKET` to its absolute path, then restart the
    MCP server. Do not guess a session or open a detached window.
 
-3. **Neither**: print the watcher command and tell the user to run it in any
+3. **Pebrel** (`PEBREL_CLI` set and not inside tmux): use the same `mmap_open`
+   tool or launcher command as route 1. It splits the Pebrel pane hosting this
+   conversation, returns input focus to it and types the watcher into the new
+   pane's shell; `--window` opens a new Pebrel window.
+
+4. **None of these**: print the watcher command and tell the user to run it in any
    second terminal themselves (add `--ascii` if their font lacks box-drawing
    characters). The launcher's own failure message quotes it in full, with
    absolute paths — relay that one verbatim. Written by hand it is

package/dist/mmap.mjs

@@ -15,8 +15,11 @@ function watcherArgs(cfg, watchPath, mapFile) {
   if (cfg.pageSlug !== void 0) args.push("--page", cfg.pageSlug);
   return args;
 }
+function posixQuote(arg) {
+  return "'" + arg.replaceAll("'", `'"'"'`) + "'";
+}
 function manualWatcherCommand(cfg, watchPath, mapFile, nodePath = process.execPath) {
-  return [nodePath, ...watcherArgs(cfg, watchPath, mapFile)].map((arg) => "'" + arg.replaceAll("'", `'"'"'`) + "'").join(" ");
+  return [nodePath, ...watcherArgs(cfg, watchPath, mapFile)].map(posixQuote).join(" ");
 }
 function paneFailureMessage(error, cfg, watchPath, mapFile, platform = process.platform) {
   return platform === "win32" ? error : `${error}
@@ -29,11 +32,13 @@ var terminal_session_exports = {};
 __export(terminal_session_exports, {
   focusSession: () => focusSession,
   inspectSession: () => inspectSession,
+  kind: () => kind,
   openWt: () => openWt,
   parseSessionProbe: () => parseSessionProbe,
   sessionProbeScript: () => sessionProbeScript
 });
 import { spawnSync } from "node:child_process";
+var kind = "wt";
 var NATIVE = String.raw`
 $ErrorActionPreference = 'Stop'
 $ProgressPreference = 'SilentlyContinue'
@@ -158,13 +163,144 @@ function openWt(args, what) {
   return result.status === 0 ? { ok: true, value: void 0 } : { ok: false, error: `wt failed to ${what} (${result.error?.message ?? `exit ${result.status}`}).` };
 }
 
-// scripts/tmux-session.mjs
+// scripts/pebrel-session.mjs
 import { spawnSync as spawnSync2 } from "node:child_process";
 import { createHash } from "node:crypto";
+var CTL_TIMEOUT_MS = 1e4;
+var SPLIT_RATIO = "0.42";
+var TERMINAL_TAB_KINDS = ["shell", "profile"];
+function hostedByPebrel(env) {
+  return Boolean(env.PEBREL_CLI && env.PEBREL_PANE_ID) && !env.TMUX;
+}
+function shellCommandLine(executable, argv) {
+  const shell = executable.toLowerCase().replace(/\.exe$/, "");
+  switch (shell) {
+    case "pwsh":
+    case "powershell":
+      return { ok: true, value: `& ${argv.map(powershellQuote).join(" ")}; exit` };
+    case "cmd":
+      return argv.some((arg) => /["%]/.test(arg)) ? { ok: false, error: 'cmd cannot quote a path containing " or %; no pane was kept.' } : { ok: true, value: `${argv.map((arg) => `"${arg}"`).join(" ")} & exit` };
+    case "sh":
+    case "bash":
+    case "zsh":
+    case "dash":
+    case "ksh":
+      return { ok: true, value: `exec ${argv.map(posixQuote).join(" ")}` };
+    default:
+      return { ok: false, error: `The new Pebrel pane runs ${executable}; the map starts only from PowerShell, cmd or a POSIX shell. No pane was kept.` };
+  }
+}
+function powershellQuote(arg) {
+  return `'${arg.replace(/['‘’‚‛]/g, "$&$&")}'`;
+}
+function createPebrelAdapter({ env = process.env, spawn = spawnSync2, nodePath = process.execPath, pid = process.pid } = {}) {
+  function ctl(command, ...args) {
+    const result = spawn(env.PEBREL_CLI, ["ctl", command, ...args.map(String)], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout: CTL_TIMEOUT_MS,
+      windowsHide: true
+    });
+    const reply = parseReply(result.stdout);
+    return reply?.ok === true ? { ok: true, value: reply.result } : { ok: false, error: `pebrel ctl ${command} failed: ${reply?.error?.message ?? result.error?.message ?? (result.stderr?.trim() || `exit ${result.status}`)}` };
+  }
+  function hosts(window, pane, processId) {
+    const tree = ctl("procs", "--window", window, "--pane", pane);
+    return tree.ok ? { ok: true, value: tree.value.processes.some((item) => item.pid === processId) } : tree;
+  }
+  function inspectSession2(cfg) {
+    const snapshot = ctl("snapshot");
+    if (!snapshot.ok) return snapshot;
+    const pane = Number(env.PEBREL_PANE_ID);
+    for (const window of snapshot.value.windows) {
+      if (!window.tabs.some((tab) => tab.panes.some((item) => item.id === pane))) continue;
+      const ours = hosts(window.id, pane, pid);
+      if (!ours.ok) return ours;
+      if (!ours.value) continue;
+      const identity = [snapshot.value.process_id, cfg.mode, cfg.mode === "window" ? "" : `${window.id}:${pane}`];
+      const owner = `pebrel-${createHash("sha256").update(JSON.stringify(identity)).digest("hex").slice(0, 24)}`;
+      return { ok: true, value: { backend: "pebrel", window: window.id, pane, owner, owners: [owner] } };
+    }
+    return { ok: false, error: `This process is not running inside Pebrel pane ${env.PEBREL_PANE_ID}; no pane was opened.` };
+  }
+  function createPane(target) {
+    if (target.mode === "window") return ctl("new-window");
+    const split = ctl("split", "--window", target.window, "--pane", target.pane, "--direction", "right");
+    if (!split.ok) return split;
+    const created = split.value.action;
+    const focused = ctl("focus", "--window", target.window, "--pane", target.pane);
+    const resized = focused.ok ? ctl("resize-pane", "--window", created.window_id, "--pane", created.pane_id, "--ratio", SPLIT_RATIO) : focused;
+    if (resized.ok) return split;
+    ctl("close-pane", "--window", created.window_id, "--pane", created.pane_id);
+    return resized;
+  }
+  function startWatcher(cfg, watchPath, mapFile, target, created) {
+    const tree = ctl("procs", "--window", created.window_id, "--pane", created.pane_id);
+    if (!tree.ok) return tree;
+    const shell = tree.value.processes.find((item) => item.depth === 0)?.executable ?? "no shell";
+    const line = shellCommandLine(shell, [nodePath, ...watcherArgs(cfg, watchPath, mapFile), "--owner", target.owner]);
+    return line.ok ? ctl("prompt", "--window", created.window_id, "--pane", created.pane_id, "--text", line.value) : line;
+  }
+  function openPane(cfg, watchPath, mapFile, target) {
+    const created = createPane(target);
+    if (!created.ok) return created;
+    const pane = created.value.action;
+    const started = startWatcher(cfg, watchPath, mapFile, target, pane);
+    if (started.ok) return { ok: true, value: { ...target, opened: { window: pane.window_id, pane: pane.pane_id } } };
+    ctl("close-pane", "--window", pane.window_id, "--pane", pane.pane_id);
+    return started;
+  }
+  function locate(processId) {
+    const snapshot = ctl("snapshot");
+    if (!snapshot.ok) return snapshot;
+    for (const window of snapshot.value.windows) {
+      for (const tab of window.tabs.filter((item) => TERMINAL_TAB_KINDS.includes(item.kind))) {
+        for (const pane of tab.panes.filter((item) => item.ssh_destination === null)) {
+          const found = hosts(window.id, pane.id, processId);
+          if (!found.ok) return found;
+          if (found.value) return { ok: true, value: { window, tab, pane } };
+        }
+      }
+    }
+    return { ok: false, error: "The live watcher could not be located in any Pebrel pane; visibility is unverified." };
+  }
+  function revealPane(target, viewer) {
+    const located = locate(viewer.pid);
+    if (!located.ok) return located;
+    const { window, tab, pane } = located.value;
+    if (zoomedOver(tab, pane.id)) {
+      const unzoomed = ctl("zoom-pane", "--window", window.id, "--pane", tab.zoomed_pane_id, "--zoomed", "false");
+      if (!unzoomed.ok) return unzoomed;
+    }
+    if (!tab.active) {
+      const focused = ctl("focus", "--window", window.id, "--pane", target.mode === "window" ? pane.id : target.pane);
+      if (!focused.ok) return focused;
+    }
+    const after = ctl("snapshot");
+    if (!after.ok) return after;
+    const shown = after.value.windows.find((item) => item.id === window.id)?.tabs.find((item) => item.panes.some((member) => member.id === pane.id));
+    return shown?.active && !zoomedOver(shown, pane.id) ? { ok: true, value: "visible" } : { ok: false, error: "The watcher is running, but its Pebrel pane is not visible in its window." };
+  }
+  return { kind: "pebrel", inspectSession: inspectSession2, openPane, revealPane };
+}
+function zoomedOver(tab, paneId) {
+  return tab.zoomed_pane_id !== void 0 && tab.zoomed_pane_id !== null && tab.zoomed_pane_id !== paneId;
+}
+function parseReply(stdout) {
+  try {
+    return JSON.parse(stdout);
+  } catch {
+    return void 0;
+  }
+}
+
+// scripts/tmux-session.mjs
+import { spawnSync as spawnSync3 } from "node:child_process";
+import { createHash as createHash2 } from "node:crypto";
 var SESSION_FORMAT = "#{session_id}	#{session_attached}";
 var TARGET_FORMAT = "#{socket_path}	#{session_id}	#{session_created}	#{session_attached}	#{pane_id}	#{pane_pid}";
 var PANE_FORMAT = "#{pane_id}	#{pane_pid}	#{window_id}	#{window_active}	#{window_zoomed_flag}	#{pane_active}";
-function createTmuxAdapter({ env = process.env, spawn = spawnSync2, nodePath = process.execPath } = {}) {
+function createTmuxAdapter({ env = process.env, spawn = spawnSync3, nodePath = process.execPath } = {}) {
   const inherited = /^(.*),\d+,(\d+)$/.exec(env.TMUX ?? "");
   const socket = env.MELLOS_MAPPING_TMUX_SOCKET || inherited?.[1];
   function run(args, socketPath = socket) {
@@ -196,7 +332,7 @@ function createTmuxAdapter({ env = process.env, spawn = spawnSync2, nodePath = p
     if (!(Number(attached) > 0)) return { ok: false, error: `tmux session ${session} has no attached client. Attach it before retrying.` };
     const identity = [socketPath, session, created, cfg.mode, cfg.mode === "window" ? "" : pane];
     const selectedViewer = cfg.mode === "split" ? viewers.find((viewer) => viewer.pid === Number(panePid) && /^tmux-[a-f0-9]{24}$/.test(viewer.owner ?? "")) : void 0;
-    const owner = selectedViewer?.owner ?? `tmux-${createHash("sha256").update(JSON.stringify(identity)).digest("hex").slice(0, 24)}`;
+    const owner = selectedViewer?.owner ?? `tmux-${createHash2("sha256").update(JSON.stringify(identity)).digest("hex").slice(0, 24)}`;
     return { ok: true, value: { backend: "tmux", socket: socketPath, session, pane, owner, owners: [owner] } };
   }
   function revealPane(target, viewer) {
@@ -298,14 +434,14 @@ var SPLIT_SIZE = "0.42";
 function selectPaneViewer(viewers, owners) {
   return viewers.find((viewer) => viewer.owner !== void 0 && owners.includes(viewer.owner));
 }
-var platformTerminal = () => process.platform === "win32" ? terminal_session_exports : createTmuxAdapter();
+var platformTerminal = () => hostedByPebrel(process.env) ? createPebrelAdapter() : process.platform === "win32" ? terminal_session_exports : createTmuxAdapter();
 function preparePane(cfg, store, mapFile, io = platformTerminal()) {
   const viewers = store.readLiveViewers(mapFile, Date.now());
-  const inspected = io.kind === "tmux" ? io.inspectSession(cfg, viewers) : cfg.mode === PANE_MODE.window ? { ok: true, value: { owners: ["window"], owner: "window" } } : io.inspectSession();
+  const inspected = io.kind !== "wt" ? io.inspectSession(cfg, viewers) : cfg.mode === PANE_MODE.window ? { ok: true, value: { owners: ["window"], owner: "window" } } : io.inspectSession();
   if (!inspected.ok) return inspected;
   const session = inspected.value;
   const viewer = selectPaneViewer(viewers, session.owners);
-  if (io.kind !== "tmux" && cfg.mode === PANE_MODE.split && !session.hwnd && (!viewer || cfg.force)) {
+  if (io.kind === "wt" && cfg.mode === PANE_MODE.split && !session.hwnd && (!viewer || cfg.force)) {
     return { ok: false, error: "Could not identify this conversation\u2019s active Windows Terminal pane. Activate its PowerShell tab and retry; no separate window was opened. Use --window only if you want a separate window." };
   }
   return { ok: true, value: {
@@ -315,7 +451,7 @@ function preparePane(cfg, store, mapFile, io = platformTerminal()) {
   } };
 }
 function placePane(cfg, watchPath, mapFile, target, io = platformTerminal()) {
-  if (io.kind === "tmux") return io.openPane(cfg, watchPath, mapFile, target);
+  if (io.kind !== "wt") return io.openPane(cfg, watchPath, mapFile, target);
   const payload = [...paneCommand(cfg, watchPath, mapFile), "--owner", target.owner];
   if (target.mode === PANE_MODE.window) {
     const opened2 = io.openWt(["-w", DEDICATED_WINDOW_NAME, "nt", ...payload], "open the requested window");
@@ -451,7 +587,7 @@ async function main() {
   if (!reported.ok) {
     fail(reported.error);
   }
-  const where = placed.value.backend === "tmux" ? placed.value.mode === PANE_MODE.window ? "in a new tmux window" : "beside this terminal (tmux split)" : placed.value.mode === PANE_MODE.window ? `in the dedicated "${DEDICATED_WINDOW_NAME}" window (${placed.value.reason})` : "beside this terminal (vertical split)";
+  const where = placed.value.backend === "tmux" ? placed.value.mode === PANE_MODE.window ? "in a new tmux window" : "beside this terminal (tmux split)" : placed.value.backend === "pebrel" ? placed.value.mode === PANE_MODE.window ? "in a new Pebrel window" : "beside this terminal (Pebrel split)" : placed.value.mode === PANE_MODE.window ? `in the dedicated "${DEDICATED_WINDOW_NAME}" window (${placed.value.reason})` : "beside this terminal (vertical split)";
   console.log(`Map opened for ${project.root} ${where}.`);
   if (!project.found) {
     console.log(

package/dist/server.mjs

@@ -24383,9 +24383,9 @@ function viewTool() {
 function openTool() {
   return {
     title: "Open the map pane",
-    description: 'For automatic display beside the current ChatGPT desktop conversation in Codex mode, use surface: "web-terminal", then call open_in_codex with the returned browser hostOpen object. No paste or Computer Use is needed. For the native host terminal, use surface: "codex-terminal": prepare absolute watcher commands for the current project, then ask the host to open its right terminal. This does not launch the watcher or type into that terminal. Agent exec PTYs cannot be attached using their numeric session ids. For a document panel, use surface: "markdown": generate MD + SVG files, enable automatic preview updates after successful map writes, then use the HOST file-opening tool to display the returned absolute Markdown path on the right of the current conversation. Generated does not mean visible: this server cannot open or observe the desktop side panel. For interactive maps, choose surface: "web": start or reuse a project-local web viewer and pass the returned URL to the host browser-opening tool. Markdown and terminal remain available. The default surface is "terminal", preserving the terminal workflow. Put the live map on the user\'s screen: a terminal pane beside this conversation that redraws on every write. Call it whenever a result says `pane: CLOSED` \u2014 and do NOT ask permission first, because a user who has set a mapping policy has already said they want to see the map. With a pane already open this RETARGETS it to `page` instead of opening a second one, so it is also how you show the user a particular page when they ask for one. It never closes a pane: taking the map off the screen belongs to the user (the `q` key in the pane, or typing `mmap` in a terminal). The reply says whether a pane actually reported itself in afterwards, not merely that a command was run. Automatic terminal opening supports Windows Terminal and tmux on Linux/macOS. omp (Oh My Pi) has no side panel of its own: there the routes are this same terminal pane (a Windows Terminal split, or a tmux split on Linux/macOS) and the web viewer, whose URL the session opens with its own browser tool. If opening fails, relay the reason and copyable command; retry only after the environment changes or the user asks.',
+    description: 'For automatic display beside the current ChatGPT desktop conversation in Codex mode, use surface: "web-terminal", then call open_in_codex with the returned browser hostOpen object. No paste or Computer Use is needed. For the native host terminal, use surface: "codex-terminal": prepare absolute watcher commands for the current project, then ask the host to open its right terminal. This does not launch the watcher or type into that terminal. Agent exec PTYs cannot be attached using their numeric session ids. For a document panel, use surface: "markdown": generate MD + SVG files, enable automatic preview updates after successful map writes, then use the HOST file-opening tool to display the returned absolute Markdown path on the right of the current conversation. Generated does not mean visible: this server cannot open or observe the desktop side panel. For interactive maps, choose surface: "web": start or reuse a project-local web viewer and pass the returned URL to the host browser-opening tool. Markdown and terminal remain available. The default surface is "terminal", preserving the terminal workflow. Put the live map on the user\'s screen: a terminal pane beside this conversation that redraws on every write. Call it whenever a result says `pane: CLOSED` \u2014 and do NOT ask permission first, because a user who has set a mapping policy has already said they want to see the map. With a pane already open this RETARGETS it to `page` instead of opening a second one, so it is also how you show the user a particular page when they ask for one. It never closes a pane: taking the map off the screen belongs to the user (the `q` key in the pane, or typing `mmap` in a terminal). The reply says whether a pane actually reported itself in afterwards, not merely that a command was run. Automatic terminal opening supports Windows Terminal, tmux on Linux/macOS, and Pebrel, which splits the conversation\'s own pane. omp (Oh My Pi) has no side panel of its own: there the routes are this same terminal pane (a Windows Terminal split, or a tmux split on Linux/macOS) and the web viewer, whose URL the session opens with its own browser tool. If opening fails, relay the reason and copyable command; retry only after the environment changes or the user asks.',
     inputSchema: closed({
-      surface: external_exports.enum(["terminal", "codex-terminal", "markdown", "web", "web-terminal"]).optional().describe("web-terminal = automatically started mmap terminal in a local browser page; codex-terminal = prepare a command for the desktop host terminal; web = local browser viewer; markdown = MD/SVG; terminal = Windows Terminal or tmux launcher (default)"),
+      surface: external_exports.enum(["terminal", "codex-terminal", "markdown", "web", "web-terminal"]).optional().describe("web-terminal = automatically started mmap terminal in a local browser page; codex-terminal = prepare a command for the desktop host terminal; web = local browser viewer; markdown = MD/SVG; terminal = Windows Terminal, tmux or Pebrel launcher (default)"),
       page: id(
         "page to show first \u2014 the page THIS effort lives on, the same slug you pass to the other tools. Omit only for the default page: without it a fresh pane opens on whichever page was written last, which after a gap is rarely the one under discussion."
       ).optional(),
@@ -24516,6 +24516,9 @@ function readMaps(stateFile, input) {
   return { resource, project, page: input.page ?? null, revision, total, items: records, nextCursor: offset + limit < total ? Buffer.from(JSON.stringify({ revision, query: queryHash, offset: offset + limit })).toString("base64url") : null };
 }
 
+// src/support/version.ts
+var VERSION = "0.28.0";
+
 // src/server/presence.ts
 var DEFAULT_PAGE_NAME = "(default)";
 var DEFAULT_PAGE_ABSENT = "(default: absent)";
@@ -24632,7 +24635,7 @@ Relay the launcher reason and any copyable fallback command. Do not retry mmap_o
   }
   if (paneShows(viewers, page2)) {
     const visible = /^MMAP_PANE [^\r\n]*\bvisibility=visible(?:\s|$)/m.test(run.output);
-    return `pane: running and reporting ${pageName2(page2)} \u2014 ${visible ? "the launcher verified its tmux window is active and its pane is visible in the attached session." : "terminal visibility is not confirmed by the process heartbeat."}
+    return `pane: running and reporting ${pageName2(page2)} \u2014 ${visible ? "the launcher verified the terminal shows its pane: its window or tab is active and no other pane is zoomed over it." : "terminal visibility is not confirmed by the process heartbeat."}
 ${run.output}`;
   }
   if (viewers.length > 0) {
@@ -24650,7 +24653,6 @@ function launcherViewerPid(run) {
 
 // src/server/server.ts
 var SERVER_NAME = "mellos-mapping";
-var SERVER_VERSION = "0.27.0";
 function text(s, isError = false) {
   return { content: [{ type: "text", text: s }], ...isError ? { isError: true } : {} };
 }
@@ -24669,7 +24671,7 @@ function saveFailed(error2) {
   return text(`save failed, nothing changed (retry): ${describeStoreError(error2)}`, true);
 }
 function buildServer(stateFile, userConfigFile, launch = launchPane) {
-  const server = new McpServer({ name: SERVER_NAME, version: SERVER_VERSION }, { instructions: "Maps persist across conversations. Before mapping or resuming work, use mmap_read to discover pages, then read the relevant records and revision. A new conversation is not a new effort. Reuse verified nodes; submit only necessary changes with expectedRevision. mmap_view is a picture, not the editable data. Read mmap_setup for the user mapping policy." });
+  const server = new McpServer({ name: SERVER_NAME, version: VERSION }, { instructions: "Maps persist across conversations. Before mapping or resuming work, use mmap_read to discover pages, then read the relevant records and revision. A new conversation is not a new effort. Reuse verified nodes; submit only necessary changes with expectedRevision. mmap_view is a picture, not the editable data. Read mmap_setup for the user mapping policy." });
   let paneOpenFailure;
   const currentPaneLine = (page2) => paneLine(stateFile, page2, paneOpenFailure);
   const projectConfigFile = configFilePath(stateFile);
@@ -24910,7 +24912,6 @@ if (launchedAsEntry(process.argv[1], import.meta.url)) {
 }
 export {
   SERVER_NAME,
-  SERVER_VERSION,
   buildServer,
   launchedAsEntry,
   launcherArgs,

package/dist/terminal-worker.mjs

@@ -1787,6 +1787,9 @@ function paint(scene, opts) {
   return { canvas, hits };
 }
 
+// src/support/version.ts
+var VERSION = "0.28.0";
+
 // src/store/atomic.ts
 import { mkdirSync as mkdirSync2, renameSync, rmSync, writeFileSync } from "node:fs";
 import { dirname as dirname3 } from "node:path";
@@ -2210,13 +2213,14 @@ var CLEAR_SCREEN = "\x1B[H\x1B[2J";
 var MOUSE_ON = "\x1B[?1003h\x1B[?1006h";
 var MOUSE_OFF = "\x1B[?1003l\x1B[?1006l";
 var RESET = "\x1B[0m";
+var COMMAND_DONE = "\x1B]133;D;0\x07";
 function terminalRestoreSequence(mouseActive, alternateScreen = false) {
   return (mouseActive ? MOUSE_OFF : "") + RESET + (alternateScreen ? LEAVE_SCREEN : "") + SHOW_CURSOR + (alternateScreen ? "" : "\n");
 }
 function openTerminalSession(options) {
   const { interactive, write } = options;
   const mouseActive = interactive && options.mouse;
-  write((interactive ? ENTER_SCREEN : "") + HIDE_CURSOR + CLEAR_SCREEN + (mouseActive ? MOUSE_ON : ""));
+  write((interactive ? COMMAND_DONE + ENTER_SCREEN : "") + HIDE_CURSOR + CLEAR_SCREEN + (mouseActive ? MOUSE_ON : ""));
   const timer = mouseActive ? setInterval(() => write(HIDE_CURSOR + MOUSE_ON), 1e3) : void 0;
   timer?.unref();
   let closed = false;
@@ -2233,7 +2237,7 @@ function openTerminalSession(options) {
 // src/watch/frame-output.ts
 function frameDifference(previous, next) {
   const compatible = previous?.columns === next.columns;
-  let output2 = "";
+  let output2 = previous?.title === next.title ? "" : `\x1B]2;${next.title}\x07`;
   for (let row = 0; row < Math.max(next.rows.length, previous?.rows.length ?? 0); row++) {
     const text = next.rows[row] ?? "";
     if (compatible && text === previous?.rows[row]) continue;
@@ -2535,6 +2539,8 @@ function dividerRow(width, unicode, follow) {
   let bar = (unicode ? "\u2500" : "-").repeat(width);
   const gripAt = Math.max(0, Math.floor((width - grip.length) / 2));
   if (width > grip.length + 2) bar = bar.slice(0, gripAt) + grip + bar.slice(gripAt + grip.length);
+  const version = ` v${VERSION} `;
+  if (1 + version.length < gripAt) bar = bar.slice(0, 1) + version + bar.slice(1 + version.length);
   if (follow) {
     const tag = unicode ? " \u21E2 follow " : " > follow ";
     const at = width - tag.length - 1;
@@ -2560,6 +2566,7 @@ var CONFIRM_WINDOW_MS = 3e3;
 var FALLBACK_COLUMNS = 100;
 var FALLBACK_ROWS = 30;
 var DEFAULT_PAGE_TAB_LABEL = "main";
+var PANE_TITLE = "mellos map";
 function usableColumns(cols) {
   return Math.max(1, cols - 1);
 }
@@ -2762,7 +2769,7 @@ function mapPanel(map, unicode, width, rows = PANEL_CONTENT_ROWS) {
   const parts = [`${map.layers.length} layers`, `${map.nodes.length} nodes`, `${map.edges.length} edges`];
   if (map.lanes.length > 0) parts.push(`${map.lanes.length} lanes`);
   const lines = [
-    { text: fitWidth(map.title ?? "mellos map", width), sgr: "1" },
+    { text: fitWidth(map.title ?? PANE_TITLE, width), sgr: "1" },
     { text: fitWidth(parts.join(" \xB7 "), width), sgr: "90" },
     // documentation kinds document structure, not progress
     { text: fitWidth(isNeutralKind(map) ? `${map.kind} diagram` : counts, width), sgr: isNeutralKind(map) ? "90" : "" },
@@ -2821,11 +2828,12 @@ function runWatcher(cfg, io = nativeWatcherIO()) {
   const viewWidth = () => usableColumns(io.output.columns ?? FALLBACK_COLUMNS);
   const viewHeight = () => Math.max(1, (io.output.rows ?? FALLBACK_ROWS) - (1 + panelContentRows) - 1 - tabRows());
   const dividerY = () => tabRows() + viewHeight() + 1;
+  const pageTitleOf = (file) => mapOf(entryOf(pane, file))?.title ?? (pageIdOfFile(cfg.file, file) ?? DEFAULT_PAGE_TAB_LABEL);
   const pageTabsOf = (files) => files.map((f) => {
     const entry = entryOf(pane, f);
     const m = mapOf(entry);
     return {
-      title: m?.title ?? (pageIdOfFile(cfg.file, f) ?? DEFAULT_PAGE_TAB_LABEL),
+      title: pageTitleOf(f),
       status: m !== void 0 ? mapStatus(m) : "planned",
       active: f === pane.activeFile,
       fresh: entry?.fresh ?? false,
@@ -3028,7 +3036,8 @@ the map pane stopped: ${e instanceof Error ? e.stack ?? e.message : String(e)}
       footer
     ];
     if (frameOutput !== void 0) {
-      frameOutput.present({ columns: cols, rows });
+      const title = pane.activeFile === void 0 ? PANE_TITLE : `${PANE_TITLE} \xB7 ${pageTitleOf(pane.activeFile)}`;
+      frameOutput.present({ columns: cols, rows, title });
     } else {
       const frame = HOME + rows.map((row) => row + ERASE_LINE_END).join("\n");
       if (frame !== lastFrame) {

package/dist/watch.mjs

@@ -1787,6 +1787,9 @@ function paint(scene, opts) {
   return { canvas, hits };
 }
 
+// src/support/version.ts
+var VERSION = "0.28.0";
+
 // src/store/atomic.ts
 import { mkdirSync as mkdirSync2, renameSync, rmSync, writeFileSync } from "node:fs";
 import { dirname as dirname3 } from "node:path";
@@ -2210,13 +2213,14 @@ var CLEAR_SCREEN = "\x1B[H\x1B[2J";
 var MOUSE_ON = "\x1B[?1003h\x1B[?1006h";
 var MOUSE_OFF = "\x1B[?1003l\x1B[?1006l";
 var RESET = "\x1B[0m";
+var COMMAND_DONE = "\x1B]133;D;0\x07";
 function terminalRestoreSequence(mouseActive, alternateScreen = false) {
   return (mouseActive ? MOUSE_OFF : "") + RESET + (alternateScreen ? LEAVE_SCREEN : "") + SHOW_CURSOR + (alternateScreen ? "" : "\n");
 }
 function openTerminalSession(options) {
   const { interactive, write } = options;
   const mouseActive = interactive && options.mouse;
-  write((interactive ? ENTER_SCREEN : "") + HIDE_CURSOR + CLEAR_SCREEN + (mouseActive ? MOUSE_ON : ""));
+  write((interactive ? COMMAND_DONE + ENTER_SCREEN : "") + HIDE_CURSOR + CLEAR_SCREEN + (mouseActive ? MOUSE_ON : ""));
   const timer = mouseActive ? setInterval(() => write(HIDE_CURSOR + MOUSE_ON), 1e3) : void 0;
   timer?.unref();
   let closed = false;
@@ -2233,7 +2237,7 @@ function openTerminalSession(options) {
 // src/watch/frame-output.ts
 function frameDifference(previous, next) {
   const compatible = previous?.columns === next.columns;
-  let output = "";
+  let output = previous?.title === next.title ? "" : `\x1B]2;${next.title}\x07`;
   for (let row = 0; row < Math.max(next.rows.length, previous?.rows.length ?? 0); row++) {
     const text = next.rows[row] ?? "";
     if (compatible && text === previous?.rows[row]) continue;
@@ -2536,6 +2540,8 @@ function dividerRow(width, unicode, follow) {
   let bar = (unicode ? "\u2500" : "-").repeat(width);
   const gripAt = Math.max(0, Math.floor((width - grip.length) / 2));
   if (width > grip.length + 2) bar = bar.slice(0, gripAt) + grip + bar.slice(gripAt + grip.length);
+  const version = ` v${VERSION} `;
+  if (1 + version.length < gripAt) bar = bar.slice(0, 1) + version + bar.slice(1 + version.length);
   if (follow) {
     const tag = unicode ? " \u21E2 follow " : " > follow ";
     const at = width - tag.length - 1;
@@ -2561,6 +2567,7 @@ var CONFIRM_WINDOW_MS = 3e3;
 var FALLBACK_COLUMNS = 100;
 var FALLBACK_ROWS = 30;
 var DEFAULT_PAGE_TAB_LABEL = "main";
+var PANE_TITLE = "mellos map";
 function usableColumns(cols) {
   return Math.max(1, cols - 1);
 }
@@ -2763,7 +2770,7 @@ function mapPanel(map, unicode, width, rows = PANEL_CONTENT_ROWS) {
   const parts = [`${map.layers.length} layers`, `${map.nodes.length} nodes`, `${map.edges.length} edges`];
   if (map.lanes.length > 0) parts.push(`${map.lanes.length} lanes`);
   const lines = [
-    { text: fitWidth(map.title ?? "mellos map", width), sgr: "1" },
+    { text: fitWidth(map.title ?? PANE_TITLE, width), sgr: "1" },
     { text: fitWidth(parts.join(" \xB7 "), width), sgr: "90" },
     // documentation kinds document structure, not progress
     { text: fitWidth(isNeutralKind(map) ? `${map.kind} diagram` : counts, width), sgr: isNeutralKind(map) ? "90" : "" },
@@ -2822,11 +2829,12 @@ function runWatcher(cfg, io2 = nativeWatcherIO()) {
   const viewWidth = () => usableColumns(io2.output.columns ?? FALLBACK_COLUMNS);
   const viewHeight = () => Math.max(1, (io2.output.rows ?? FALLBACK_ROWS) - (1 + panelContentRows) - 1 - tabRows());
   const dividerY = () => tabRows() + viewHeight() + 1;
+  const pageTitleOf = (file) => mapOf(entryOf(pane, file))?.title ?? (pageIdOfFile(cfg.file, file) ?? DEFAULT_PAGE_TAB_LABEL);
   const pageTabsOf = (files) => files.map((f) => {
     const entry = entryOf(pane, f);
     const m = mapOf(entry);
     return {
-      title: m?.title ?? (pageIdOfFile(cfg.file, f) ?? DEFAULT_PAGE_TAB_LABEL),
+      title: pageTitleOf(f),
       status: m !== void 0 ? mapStatus(m) : "planned",
       active: f === pane.activeFile,
       fresh: entry?.fresh ?? false,
@@ -3029,7 +3037,8 @@ the map pane stopped: ${e instanceof Error ? e.stack ?? e.message : String(e)}
       footer
     ];
     if (frameOutput !== void 0) {
-      frameOutput.present({ columns: cols, rows });
+      const title = pane.activeFile === void 0 ? PANE_TITLE : `${PANE_TITLE} \xB7 ${pageTitleOf(pane.activeFile)}`;
+      frameOutput.present({ columns: cols, rows, title });
     } else {
       const frame = HOME + rows.map((row) => row + ERASE_LINE_END).join("\n");
       if (frame !== lastFrame) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mellos-mapping",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "mcpName": "io.github.GuangminJu/mellos-mapping",
   "description": "A live layered dependency map for bottom-up development — MCP server + terminal pane. Ghost the design first, then light nodes up from the bottom as they are built and verified.",
   "type": "module",
@@ -96,6 +96,7 @@
     "scripts/mmap.mjs",
     "scripts/open-pane.mjs",
     "scripts/pane-core.mjs",
+    "scripts/pebrel-session.mjs",
     "scripts/terminal-session.mjs",
     "scripts/tmux-session.mjs",
     "scripts/watcher-command.mjs"

package/scripts/mmap.mjs

@@ -208,6 +208,8 @@ async function main() {
   const where =
     placed.value.backend === 'tmux'
       ? (placed.value.mode === PANE_MODE.window ? 'in a new tmux window' : 'beside this terminal (tmux split)')
+      : placed.value.backend === 'pebrel'
+      ? (placed.value.mode === PANE_MODE.window ? 'in a new Pebrel window' : 'beside this terminal (Pebrel split)')
       : placed.value.mode === PANE_MODE.window
       ? `in the dedicated "${DEDICATED_WINDOW_NAME}" window (${placed.value.reason})`
       : 'beside this terminal (vertical split)';

package/scripts/open-pane.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * Open the live map pane in the owning Windows Terminal or tmux session — the AGENT's
+ * Open the live map pane in the owning Windows Terminal, tmux or Pebrel session — the AGENT's
  * launcher, addressed by `/mmap` and by the skill.
  *
  *   node scripts/open-pane.mjs <project-dir> [--page <slug>] [--window] [--force]
@@ -151,6 +151,10 @@ async function main() {
     console.log(`MMAP_PANE mode=${placed.value.mode} pid=${reported.value.pid} backend=tmux session=${placed.value.session} visibility=${visible.value}`);
     console.log(placed.value.mode === PANE_MODE.window
       ? 'Map opened in a new tmux window.' : 'Map opened beside this conversation (tmux split).');
+  } else if (placed.value.backend === 'pebrel') {
+    console.log(`MMAP_PANE mode=${placed.value.mode} pid=${reported.value.pid} backend=pebrel window=${placed.value.opened.window} pane=${placed.value.opened.pane} visibility=${visible.value}`);
+    console.log(placed.value.mode === PANE_MODE.window
+      ? 'Map opened in a new Pebrel window.' : 'Map opened beside this conversation (Pebrel split).');
   } else if (placed.value.mode === PANE_MODE.window) {
     console.log(`MMAP_PANE mode=window pid=${reported.value.pid} name=${DEDICATED_WINDOW_NAME} reason=${placed.value.reason}`);
     console.log(`Map opened in the dedicated "${DEDICATED_WINDOW_NAME}" window.`);

package/scripts/pane-core.mjs

@@ -30,6 +30,7 @@
  * Pure helpers are exported for the spec; nothing here runs on import.
  */
 import * as terminal from './terminal-session.mjs';
+import { createPebrelAdapter, hostedByPebrel } from './pebrel-session.mjs';
 import { createTmuxAdapter } from './tmux-session.mjs';
 import { watcherArgs } from './watcher-command.mjs';
 import { existsSync, mkdirSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs';
@@ -199,18 +200,23 @@ export function selectPaneViewer(viewers, owners) {
   return viewers.find((viewer) => viewer.owner !== undefined && owners.includes(viewer.owner));
 }
 
-const platformTerminal = () => process.platform === 'win32' ? terminal : createTmuxAdapter();
+/**
+ * Windows Terminal is composed here from its probe and `wt`; every other
+ * backend is an adapter that places and reveals its own panes.
+ */
+const platformTerminal = () => hostedByPebrel(process.env) ? createPebrelAdapter()
+  : process.platform === 'win32' ? terminal : createTmuxAdapter();
 
 /** Resolve identity before deciding whether to reuse, open or toggle. */
 export function preparePane(cfg, store, mapFile, io = platformTerminal()) {
   const viewers = store.readLiveViewers(mapFile, Date.now());
-  const inspected = io.kind === 'tmux' ? io.inspectSession(cfg, viewers) : cfg.mode === PANE_MODE.window
+  const inspected = io.kind !== 'wt' ? io.inspectSession(cfg, viewers) : cfg.mode === PANE_MODE.window
     ? { ok: true, value: { owners: ['window'], owner: 'window' } }
     : io.inspectSession();
   if (!inspected.ok) return inspected;
   const session = inspected.value;
   const viewer = selectPaneViewer(viewers, session.owners);
-  if (io.kind !== 'tmux' && cfg.mode === PANE_MODE.split && !session.hwnd && (!viewer || cfg.force)) {
+  if (io.kind === 'wt' && cfg.mode === PANE_MODE.split && !session.hwnd && (!viewer || cfg.force)) {
     return { ok: false, error: 'Could not identify this conversation’s active Windows Terminal pane. Activate its PowerShell tab and retry; no separate window was opened. Use --window only if you want a separate window.' };
   }
   return { ok: true, value: {
@@ -222,12 +228,12 @@ export function preparePane(cfg, store, mapFile, io = platformTerminal()) {
 
 /** A process heartbeat alone cannot establish that its pane is on screen. */
 export function revealPane(target, viewer, io = platformTerminal()) {
-  return io.kind === 'tmux' ? io.revealPane(target, viewer) : { ok: true, value: 'unverified' };
+  return io.kind !== 'wt' ? io.revealPane(target, viewer) : { ok: true, value: 'unverified' };
 }
 
 /** Compose a verified target with the watcher payload. Never changes the requested mode. */
 export function placePane(cfg, watchPath, mapFile, target, io = platformTerminal()) {
-  if (io.kind === 'tmux') return io.openPane(cfg, watchPath, mapFile, target);
+  if (io.kind !== 'wt') return io.openPane(cfg, watchPath, mapFile, target);
   const payload = [...paneCommand(cfg, watchPath, mapFile), '--owner', target.owner];
   if (target.mode === PANE_MODE.window) {
     const opened = io.openWt(['-w', DEDICATED_WINDOW_NAME, 'nt', ...payload], 'open the requested window');

package/scripts/pebrel-session.mjs

@@ -0,0 +1,166 @@
+/** Pebrel adapter: split the conversation's own pane through Pebrel's runtime CLI. */
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { posixQuote, watcherArgs } from './watcher-command.mjs';
+
+const CTL_TIMEOUT_MS = 10_000;
+const SPLIT_RATIO = '0.42';
+const TERMINAL_TAB_KINDS = ['shell', 'profile'];
+
+/**
+ * Pebrel exports PEBREL_CLI and PEBREL_PANE_ID to every local pane. A tmux
+ * server inherits them but is not a descendant of that pane, so a conversation
+ * inside tmux belongs to tmux.
+ */
+export function hostedByPebrel(env) {
+  return Boolean(env.PEBREL_CLI && env.PEBREL_PANE_ID) && !env.TMUX;
+}
+
+/**
+ * Pebrel splits always start the default shell, so the watcher is typed as one
+ * line in that shell's own syntax. The line ends the shell with the watcher,
+ * which closes the pane the way a wt or tmux pane closes with its command.
+ */
+export function shellCommandLine(executable, argv) {
+  const shell = executable.toLowerCase().replace(/\.exe$/, '');
+  switch (shell) {
+    case 'pwsh':
+    case 'powershell':
+      return { ok: true, value: `& ${argv.map(powershellQuote).join(' ')}; exit` };
+    case 'cmd':
+      return argv.some((arg) => /["%]/.test(arg))
+        ? { ok: false, error: 'cmd cannot quote a path containing " or %; no pane was kept.' }
+        : { ok: true, value: `${argv.map((arg) => `"${arg}"`).join(' ')} & exit` };
+    case 'sh':
+    case 'bash':
+    case 'zsh':
+    case 'dash':
+    case 'ksh':
+      return { ok: true, value: `exec ${argv.map(posixQuote).join(' ')}` };
+    default:
+      return { ok: false, error: `The new Pebrel pane runs ${executable}; the map starts only from PowerShell, cmd or a POSIX shell. No pane was kept.` };
+  }
+}
+
+/** PowerShell ends a single-quoted string at any of the four single quotes. */
+function powershellQuote(arg) {
+  return `'${arg.replace(/['‘’‚‛]/g, '$&$&')}'`;
+}
+
+export function createPebrelAdapter({ env = process.env, spawn = spawnSync, nodePath = process.execPath, pid = process.pid } = {}) {
+  function ctl(command, ...args) {
+    const result = spawn(env.PEBREL_CLI, ['ctl', command, ...args.map(String)], {
+      encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: CTL_TIMEOUT_MS, windowsHide: true,
+    });
+    const reply = parseReply(result.stdout);
+    return reply?.ok === true
+      ? { ok: true, value: reply.result }
+      : { ok: false, error: `pebrel ctl ${command} failed: ${reply?.error?.message ?? result.error?.message ?? (result.stderr?.trim() || `exit ${result.status}`)}` };
+  }
+
+  function hosts(window, pane, processId) {
+    const tree = ctl('procs', '--window', window, '--pane', pane);
+    return tree.ok ? { ok: true, value: tree.value.processes.some((item) => item.pid === processId) } : tree;
+  }
+
+  function inspectSession(cfg) {
+    const snapshot = ctl('snapshot');
+    if (!snapshot.ok) return snapshot;
+    const pane = Number(env.PEBREL_PANE_ID);
+    // Pane ids are unique only within a window; the process tree says which window is ours.
+    for (const window of snapshot.value.windows) {
+      if (!window.tabs.some((tab) => tab.panes.some((item) => item.id === pane))) continue;
+      const ours = hosts(window.id, pane, pid);
+      if (!ours.ok) return ours;
+      if (!ours.value) continue;
+      const identity = [snapshot.value.process_id, cfg.mode, cfg.mode === 'window' ? '' : `${window.id}:${pane}`];
+      const owner = `pebrel-${createHash('sha256').update(JSON.stringify(identity)).digest('hex').slice(0, 24)}`;
+      return { ok: true, value: { backend: 'pebrel', window: window.id, pane, owner, owners: [owner] } };
+    }
+    return { ok: false, error: `This process is not running inside Pebrel pane ${env.PEBREL_PANE_ID}; no pane was opened.` };
+  }
+
+  function createPane(target) {
+    if (target.mode === 'window') return ctl('new-window');
+    const split = ctl('split', '--window', target.window, '--pane', target.pane, '--direction', 'right');
+    if (!split.ok) return split;
+    const created = split.value.action;
+    const focused = ctl('focus', '--window', target.window, '--pane', target.pane);
+    const resized = focused.ok
+      ? ctl('resize-pane', '--window', created.window_id, '--pane', created.pane_id, '--ratio', SPLIT_RATIO)
+      : focused;
+    if (resized.ok) return split;
+    ctl('close-pane', '--window', created.window_id, '--pane', created.pane_id);
+    return resized;
+  }
+
+  function startWatcher(cfg, watchPath, mapFile, target, created) {
+    const tree = ctl('procs', '--window', created.window_id, '--pane', created.pane_id);
+    if (!tree.ok) return tree;
+    const shell = tree.value.processes.find((item) => item.depth === 0)?.executable ?? 'no shell';
+    const line = shellCommandLine(shell, [nodePath, ...watcherArgs(cfg, watchPath, mapFile), '--owner', target.owner]);
+    return line.ok ? ctl('prompt', '--window', created.window_id, '--pane', created.pane_id, '--text', line.value) : line;
+  }
+
+  function openPane(cfg, watchPath, mapFile, target) {
+    const created = createPane(target);
+    if (!created.ok) return created;
+    const pane = created.value.action;
+    const started = startWatcher(cfg, watchPath, mapFile, target, pane);
+    if (started.ok) return { ok: true, value: { ...target, opened: { window: pane.window_id, pane: pane.pane_id } } };
+    ctl('close-pane', '--window', pane.window_id, '--pane', pane.pane_id);
+    return started;
+  }
+
+  function locate(processId) {
+    const snapshot = ctl('snapshot');
+    if (!snapshot.ok) return snapshot;
+    for (const window of snapshot.value.windows) {
+      for (const tab of window.tabs.filter((item) => TERMINAL_TAB_KINDS.includes(item.kind))) {
+        for (const pane of tab.panes.filter((item) => item.ssh_destination === null)) {
+          const found = hosts(window.id, pane.id, processId);
+          if (!found.ok) return found;
+          if (found.value) return { ok: true, value: { window, tab, pane } };
+        }
+      }
+    }
+    return { ok: false, error: 'The live watcher could not be located in any Pebrel pane; visibility is unverified.' };
+  }
+
+  function revealPane(target, viewer) {
+    const located = locate(viewer.pid);
+    if (!located.ok) return located;
+    const { window, tab, pane } = located.value;
+    if (zoomedOver(tab, pane.id)) {
+      const unzoomed = ctl('zoom-pane', '--window', window.id, '--pane', tab.zoomed_pane_id, '--zoomed', 'false');
+      if (!unzoomed.ok) return unzoomed;
+    }
+    if (!tab.active) {
+      // A split shares the conversation's tab, so focusing the conversation reveals it without taking input.
+      const focused = ctl('focus', '--window', window.id, '--pane', target.mode === 'window' ? pane.id : target.pane);
+      if (!focused.ok) return focused;
+    }
+    const after = ctl('snapshot');
+    if (!after.ok) return after;
+    const shown = after.value.windows.find((item) => item.id === window.id)
+      ?.tabs.find((item) => item.panes.some((member) => member.id === pane.id));
+    return shown?.active && !zoomedOver(shown, pane.id)
+      ? { ok: true, value: 'visible' }
+      : { ok: false, error: 'The watcher is running, but its Pebrel pane is not visible in its window.' };
+  }
+
+  return { kind: 'pebrel', inspectSession, openPane, revealPane };
+}
+
+/** Pebrel 2.2 omits zoomed_pane_id from a tab that has no zoom. */
+function zoomedOver(tab, paneId) {
+  return tab.zoomed_pane_id !== undefined && tab.zoomed_pane_id !== null && tab.zoomed_pane_id !== paneId;
+}
+
+function parseReply(stdout) {
+  try {
+    return JSON.parse(stdout);
+  } catch {
+    return undefined;
+  }
+}

package/scripts/terminal-session.mjs

@@ -1,6 +1,8 @@
 /** Windows Terminal adapter. No project paths, reuse policy or persistent state. */
 import { spawnSync } from 'node:child_process';
 
+export const kind = 'wt';
+
 const NATIVE = String.raw`
 $ErrorActionPreference = 'Stop'
 $ProgressPreference = 'SilentlyContinue'

package/scripts/watcher-command.mjs

@@ -5,10 +5,13 @@ export function watcherArgs(cfg, watchPath, mapFile) {
   return args;
 }
 
-/** POSIX shell quoting is only for the human fallback; adapters use argv. */
+export function posixQuote(arg) {
+  return "'" + arg.replaceAll("'", "'\"'\"'") + "'";
+}
+
+/** The human fallback; adapters that can pass argv never quote. */
 export function manualWatcherCommand(cfg, watchPath, mapFile, nodePath = process.execPath) {
-  return [nodePath, ...watcherArgs(cfg, watchPath, mapFile)]
-    .map(arg => "'" + arg.replaceAll("'", "'\"'\"'") + "'").join(' ');
+  return [nodePath, ...watcherArgs(cfg, watchPath, mapFile)].map(posixQuote).join(' ');
 }
 
 export function paneFailureMessage(error, cfg, watchPath, mapFile, platform = process.platform) {

package/skills/mellos-mapping/SKILL.md

@@ -204,6 +204,9 @@ confirmed open desktop panel. See `docs/codex.md` for transport and lifecycle de
    attached sessions require `MELLOS_MAPPING_TMUX_TARGET`; custom sockets use
    `MELLOS_MAPPING_TMUX_SOCKET` in the MCP server environment. `window: true`
    requests a new tmux window. Do not guess between attached sessions.
+   Inside Pebrel (`PEBREL_CLI` and `PEBREL_PANE_ID` set, not inside tmux) it
+   splits the conversation's own Pebrel pane; `window: true` opens a new
+   Pebrel window.
    Under omp (Oh My Pi) nothing about this changes: the same tool runs the same
    launcher, splitting the Windows Terminal window hosting the omp session
    (tmux split on Linux/macOS) and reusing the pane already bound to it. omp has