mellos-mapping 0.12.0 → 0.14.0

package/README.md

@@ -125,7 +125,10 @@ session's working directory instead: the state file lands in your project,
 same as under Claude Code. The registered path is version-specific — re-run
 the script after updating the plugin.
 
-To watch the live pane beside a Codex session, run
+To watch the live pane beside a Codex session on Windows, run
+`node <plugin root>/scripts/open-pane.mjs <project dir>` — it splits the
+terminal window hosting the session (or falls back to a dedicated
+"mellos-mapping" window; `--window` picks that on purpose). Elsewhere run
 `node <plugin root>/dist/watch.mjs` from the project directory in a second
 terminal (or any terminal split).
 
@@ -154,7 +157,10 @@ get the four `mmap_*` tools and the pane, and bring their own prompting.
    declare the ghost design and keep the map current as it works.
 2. Run `/mellos-mapping:mmap` to open the live pane (Windows Terminal split
    on Windows, tmux split inside tmux, or a printed command to run in any
-   second terminal). Prefer `--ascii` if your font lacks box-drawing glyphs.
+   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.
 3. Watch nodes light up from the bottom. Interrupt when the picture worries
    you — that is what it is for.
 

package/README.zh-CN.md

@@ -115,8 +115,11 @@ node ~/.codex/plugins/cache/mellos-mapping/mellos-mapping/<版本>/scripts/codex
 项目里，与 Claude Code 下行为一致。注册的是版本相关的绝对路径——插件
 更新后重跑一次脚本即可。
 
-要在 Codex 会话旁边看实况面板，在项目目录下的第二个终端（或任意分屏）
-运行 `node <插件根>/dist/watch.mjs`。
+要在 Codex 会话旁边看实况面板，Windows 上运行
+`node <插件根>/scripts/open-pane.mjs <项目目录>`——它会在承载本会话的
+终端窗口里分屏（识别不到就确定性地开到专属的 "mellos-mapping" 窗口；
+`--window` 则是主动选择专属窗口）。其他环境在项目目录下的第二个终端
+（或任意分屏）运行 `node <插件根>/dist/watch.mjs`。
 
 ## 任意 MCP 客户端
 
@@ -143,7 +146,9 @@ npx -y -p mellos-mapping mellos-mapping-watch
    设计，并在工作过程中保持地图与现实一致。
 2. 运行 `/mellos-mapping:mmap` 打开实况分屏（Windows 上是 Windows
    Terminal 分屏，tmux 里是 tmux 分屏，其他环境会打印一条命令让你在
-   第二个终端里运行）。字体缺少制表符字形时用 `--ascii`。
+   第二个终端里运行）。Windows 上即使开着多个终端窗口，分屏也会落在
+   **你的会话所在的窗口**；想让地图独占一个窗口就加 `--window`。字体
+   缺少制表符字形时用 `--ascii`。
 3. 看着节点从底部一路亮起。图让你不安的时候就打断它——这正是它存在的
    意义。
 

package/dist/server.mjs

@@ -22513,7 +22513,7 @@ function summarize(map) {
 
 // src/server/server.ts
 var SERVER_NAME = "mellos-mapping";
-var SERVER_VERSION = "0.12.0";
+var SERVER_VERSION = "0.14.0";
 var ID = external_exports.string().regex(/^[a-z0-9][a-z0-9-]{0,63}$/, "lowercase letters, digits and dashes, 1-64 chars").describe("stable kebab-case identifier");
 var PAGE = ID.optional().describe(
   "page (parallel map) this call targets; omit for the default page. One effort = one page: start a NEW effort on its own page named after the effort, so concurrent sessions never write over each other and the pane can switch between pages."

package/dist/watch.mjs

@@ -1442,6 +1442,131 @@ function nodePanel(map, focusId, unicode, width, pinned, rows = PANEL_CONTENT_RO
   }
   return lines.slice(0, rows);
 }
+var SPLASH_FONT = {
+  M: ["#   #", "## ##", "# # #", "#   #", "#   #"],
+  E: ["####", "#", "###", "#", "####"],
+  L: ["#", "#", "#", "#", "####"],
+  O: [" ###", "#   #", "#   #", "#   #", " ###"],
+  S: [" ####", "#", " ###", "    #", "####"],
+  A: [" ###", "#   #", "#####", "#   #", "#   #"],
+  P: ["####", "#   #", "####", "#", "#"],
+  I: ["###", " #", " #", " #", "###"],
+  N: ["#   #", "##  #", "# # #", "#  ##", "#   #"],
+  G: [" ####", "#", "#  ##", "#   #", " ###"]
+};
+var SPLASH_ROWS = 5;
+var SPLASH_SHADES = {
+  unicode: ["\u2591", "\u2591", "\u2592", "\u2592", "\u2593", "\u2593", "\u2588", "\u2588"],
+  ascii: [".", ".", ":", ":", "=", "=", "#", "#"]
+};
+var WAVE_RAMP = [17, 18, 19, 61, 24, 25, 31, 37, 44, 45, 51, 87, 123, 159, 195];
+var SPINNER_FRAMES = {
+  unicode: ["\u280B", "\u2819", "\u2839", "\u2838", "\u283C", "\u2834", "\u2826", "\u2827", "\u2807", "\u280F"],
+  ascii: ["|", "/", "-", "\\"]
+};
+function wordArt(word) {
+  const glyphs = [...word.toUpperCase()].map((ch) => SPLASH_FONT[ch]).filter((g) => g !== void 0);
+  const widths = glyphs.map((g) => Math.max(...g.map((r) => r.length)));
+  const rows = [];
+  for (let r = 0; r < SPLASH_ROWS; r++) {
+    rows.push(glyphs.map((g, i) => (g[r] ?? "").padEnd(widths[i], " ")).join(" "));
+  }
+  return rows;
+}
+function splashArt() {
+  const words = [wordArt("MELLOS"), wordArt("MAPPING")];
+  const width = Math.max(...words.flat().map((r) => r.length));
+  const centered = words.map((rows) => {
+    const own = Math.max(...rows.map((r) => r.length));
+    return rows.map((r) => " ".repeat(Math.floor((width - own) / 2)) + r);
+  });
+  return [...centered[0], "", ...centered[1]];
+}
+var WAVE_INTERVAL = 18;
+var WAVE_LIFETIME = 64;
+var WAVE_SPEED = 0.9;
+var WAVE_ENVELOPE = 10;
+var WAVE_NUMBER = 0.42;
+var WAVE_LEVELS = 7;
+var WAVE_GAIN = 4.5;
+function waveHash(n) {
+  let h = Math.imul(n + 1, 2654435761) >>> 0;
+  h ^= h >>> 15;
+  h = Math.imul(h, 2246822519) >>> 0;
+  h ^= h >>> 13;
+  return h >>> 0;
+}
+var WAVE_CORNERS = [
+  [0, 0],
+  [1, 0],
+  [0, 1],
+  [1, 1]
+];
+function liveRipples(frame, width, height) {
+  const out = [];
+  const first = Math.floor((frame - WAVE_LIFETIME - WAVE_INTERVAL) / WAVE_INTERVAL);
+  const last = Math.floor(frame / WAVE_INTERVAL);
+  for (let n = Math.max(0, first); n <= last; n++) {
+    const h = waveHash(n);
+    const age = frame - (n * WAVE_INTERVAL + h % WAVE_INTERVAL);
+    if (age < 0 || age > WAVE_LIFETIME) continue;
+    const [fx, fy] = WAVE_CORNERS[h % WAVE_CORNERS.length];
+    out.push({
+      ox: fx * (width - 1),
+      oy: fy * (height - 1),
+      r: age * WAVE_SPEED,
+      fade: 1 - age / WAVE_LIFETIME
+    });
+  }
+  return out;
+}
+function waveAt(ripples, x, y) {
+  let value = 0;
+  for (const w of ripples) {
+    const front = Math.hypot(x - w.ox, (y - w.oy) * 2) - w.r;
+    value += Math.cos(front * WAVE_NUMBER) * Math.exp(-(front * front) / (2 * WAVE_ENVELOPE ** 2)) * w.fade;
+  }
+  return value;
+}
+function waveLevel(value) {
+  return Math.max(-WAVE_LEVELS, Math.min(WAVE_LEVELS, Math.round(value * WAVE_GAIN)));
+}
+function splashFrame(notice, frame, width, height, unicode, color) {
+  const art = splashArt();
+  const artWidth = Math.max(...art.map((r) => r.length));
+  if (width < artWidth + 2 || height < art.length + 2) return void 0;
+  const mode = unicode ? "unicode" : "ascii";
+  const shades = SPLASH_SHADES[mode];
+  const solid = shades[shades.length - 1];
+  const indent = " ".repeat(Math.floor((width - artWidth) / 2));
+  const ripples = liveRipples(frame, artWidth, art.length);
+  const inkOf = (x, y) => {
+    const level = waveLevel(waveAt(ripples, x, y));
+    return color ? `38;5;${WAVE_RAMP[WAVE_LEVELS + level]}` : shades[Math.abs(level)];
+  };
+  const paintRow = (row, y) => {
+    const cells = [...row].map((ch, x) => ch === "#" ? inkOf(x, y) : void 0);
+    let out = "";
+    for (let i = 0; i < cells.length; ) {
+      const cell = cells[i];
+      let j = i;
+      while (j < cells.length && cells[j] === cell) j++;
+      if (cell === void 0) out += " ".repeat(j - i);
+      else out += color ? `\x1B[${cell}m${solid.repeat(j - i)}${RESET}` : cell.repeat(j - i);
+      i = j;
+    }
+    return out;
+  };
+  const spinner = SPINNER_FRAMES[mode];
+  const status = fitWidth(`${spinner[frame % spinner.length]} ${notice}`, Math.max(1, width - 2));
+  const statusIndent = " ".repeat(Math.max(0, Math.floor((width - displayWidth(status)) / 2)));
+  const block = [
+    ...art.map((row, y) => row.trim() === "" ? "" : indent + paintRow(row, y)),
+    "",
+    statusIndent + (color ? `\x1B[90m${status}${RESET}` : status)
+  ];
+  return [...Array.from({ length: Math.max(0, Math.floor((height - block.length) / 2)) }, () => ""), ...block];
+}
 function mapPanel(map, unicode, width, rows = PANEL_CONTENT_ROWS) {
   const g = (s) => STATUS_GLYPH[s][unicode ? 0 : 1];
   const count = (s) => map.nodes.filter((n) => n.status === s).length;
@@ -1466,6 +1591,7 @@ function main() {
   const mouseActive = interactive && cfg.mouse;
   let lastFrame = "";
   let spinnerFrame = 0;
+  let splashTick = 0;
   let map;
   let notice = `waiting for ${cfg.file} ...`;
   let lastCols = process.stdout.columns ?? 0;
@@ -1567,7 +1693,7 @@ function main() {
       lastContent = { w: windowed.contentWidth, h: windowed.contentHeight };
       if (offsetX !== 0 || offsetY !== 0) panned = `  (+${offsetX},+${offsetY})`;
     } else {
-      body = [fitWidth(notice, Math.max(1, cols - 1))];
+      body = (interactive ? splashFrame(notice, splashTick, cols, viewH, cfg.unicode, cfg.color) : void 0) ?? [fitWidth(notice, Math.max(1, cols - 1))];
     }
     if (notice !== "" && map !== void 0) {
       body[body.length - 1] = fitWidth(`  ${notice}`, Math.max(1, cols - 1));
@@ -1854,6 +1980,13 @@ function main() {
   }
   tick();
   setInterval(tick, cfg.intervalMs);
+  if (interactive) {
+    setInterval(() => {
+      if (map !== void 0) return;
+      splashTick++;
+      paint();
+    }, 80);
+  }
 }
 function launchedAsEntry(argv1, moduleUrl) {
   if (argv1 === void 0) return false;
@@ -1868,17 +2001,26 @@ if (launchedAsEntry(process.argv[1], import.meta.url)) {
 }
 export {
   PANEL_ROWS_MIN,
+  WAVE_LEVELS,
+  WAVE_NUMBER,
   anchorOffsets,
   clampPanelRows,
   diveOrigin,
   fitWidth,
   launchedAsEntry,
+  liveRipples,
   mapPanel,
   nearestHit,
   nodePanel,
   pageTabRow,
   panelRowsFromDividerY,
   parseArgs,
+  splashArt,
+  splashFrame,
   topLevelFiles,
+  waveAt,
+  waveHash,
+  waveLevel,
+  wordArt,
   wrapWidth
 };

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "mellos-mapping",
-  "version": "0.12.0",
+  "version": "0.14.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",
   "license": "MIT",
@@ -32,7 +33,8 @@
   "files": [
     "dist",
     "README.zh-CN.md",
-    "scripts/codex-register.mjs"
+    "scripts/codex-register.mjs",
+    "scripts/open-pane.mjs"
   ],
   "engines": {
     "node": ">=18"

package/scripts/open-pane.mjs

@@ -0,0 +1,249 @@
+#!/usr/bin/env node
+/**
+ * Open the live map pane in the RIGHT Windows Terminal window.
+ *
+ *   node scripts/open-pane.mjs <project-dir> [--window] [--ascii] [--force]
+ *
+ * Why this exists: the agent's shell runs on a hidden console (no WT_SESSION),
+ * so a bare `wt -w 0 sp` targets the MOST RECENTLY USED terminal window — with
+ * several windows open the map lands wherever the user last clicked, not
+ * beside the conversation. Verified on Windows 11 / WT single-process mode:
+ * all windows share one WindowsTerminal.exe pid, and the console UI is
+ * attached by default-terminal delegation, so neither pid-matching nor the
+ * process tree can name the hosting window.
+ *
+ * What does work — and what this script does, verifying every step:
+ *
+ *   1. Walk this process's ancestors and AttachConsole to each in turn; write
+ *      a nonce into that console's title. The WT window whose title lights up
+ *      is the one hosting this session. The nonce only shows when the session
+ *      tab is the window's ACTIVE tab — exactly the precondition under which
+ *      `sp` would split beside the conversation, so identification doubles as
+ *      the go/no-go check.
+ *   2. Bring that window to the foreground (plain SetForegroundWindow, then
+ *      the Alt-key unlock, then AttachThreadInput — Windows' foreground lock
+ *      denies the plain call from background processes), verifying with
+ *      GetForegroundWindow after each attempt.
+ *   3. Only then `wt -w 0 sp` — "most recently used" is now provably ours.
+ *
+ * Any step failing falls back to a dedicated window named "mellos-mapping":
+ * deterministic, never a random window. `--window` picks that mode outright
+ * (explicit choice for users who want the map separate from the chat).
+ *
+ * Known race, accepted: if the user focuses a DIFFERENT terminal window in
+ * the ~1s between our focus-verify and wt reading its MRU state, the split
+ * can still land there. The window is at least one the user is actively in.
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const argv = process.argv.slice(2);
+const flags = new Set(argv.filter((a) => a.startsWith('--')));
+const positional = argv.filter((a) => !a.startsWith('--'));
+
+if (positional.length !== 1) {
+  console.error('usage: node scripts/open-pane.mjs <project-dir> [--window] [--ascii] [--force]');
+  process.exit(1);
+}
+if (process.platform !== 'win32') {
+  console.error('open-pane.mjs is Windows Terminal-only — use the tmux/manual route from the command doc.');
+  process.exit(1);
+}
+
+const projectDir = resolve(positional[0]);
+if (!existsSync(projectDir)) {
+  console.error(`project directory does not exist: ${projectDir}`);
+  process.exit(1);
+}
+
+const pluginRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+const watchPath = join(pluginRoot, 'dist', 'watch.mjs');
+if (!existsSync(watchPath)) {
+  console.error(`watcher not found (is the plugin built?): ${watchPath}`);
+  process.exit(1);
+}
+const mapFile = join(projectDir, '.claude', 'mellos-mapping.json');
+
+function runPowerShell(script) {
+  const encoded = Buffer.from(script, 'utf16le').toString('base64');
+  const r = spawnSync(
+    'powershell.exe',
+    ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-EncodedCommand', encoded],
+    { encoding: 'utf8', timeout: 30_000, windowsHide: true },
+  );
+  return r.stdout ?? '';
+}
+
+// One watcher per map file is enough — watch.mjs redraws on change for every
+// viewer of the same file, and piling up panes on repeated /mmap is noise.
+// Matches only watchers this script started (they carry --file <mapFile> on
+// their command line); --force bypasses.
+function watcherAlreadyRunning() {
+  const token = mapFile.replace(/'/g, "''");
+  const out = runPowerShell(
+    `$ErrorActionPreference = 'SilentlyContinue'\n` +
+    `$w = @(Get-CimInstance Win32_Process -Filter "Name='node.exe'" | Where-Object { $_.CommandLine -like '*watch.mjs*' -and $_.CommandLine -like '*${token}*' })\n` +
+    `Write-Output "WATCHERS=$($w.Count)"`,
+  );
+  const m = out.match(/WATCHERS=(\d+)/);
+  return m !== null && Number(m[1]) > 0;
+}
+
+// Prints IDENT=<hwnd|0> and, when identified, FOCUS=<1|0>.
+const IDENTIFY_AND_FOCUS = String.raw`
+$ErrorActionPreference = 'SilentlyContinue'
+Add-Type @"
+using System;
+using System.Text;
+using System.Runtime.InteropServices;
+public class MmapWin {
+  [DllImport("user32.dll")] public static extern bool EnumWindows(EnumWindowsProc cb, IntPtr lp);
+  public delegate bool EnumWindowsProc(IntPtr hWnd, IntPtr lp);
+  [DllImport("user32.dll")] public static extern bool IsWindowVisible(IntPtr hWnd);
+  [DllImport("user32.dll", CharSet=CharSet.Unicode)] public static extern int GetClassName(IntPtr hWnd, StringBuilder sb, int max);
+  [DllImport("user32.dll", CharSet=CharSet.Unicode)] public static extern int GetWindowText(IntPtr hWnd, StringBuilder sb, int max);
+  [DllImport("user32.dll")] public static extern bool SetForegroundWindow(IntPtr hWnd);
+  [DllImport("user32.dll")] public static extern IntPtr GetForegroundWindow();
+  [DllImport("user32.dll")] public static extern bool BringWindowToTop(IntPtr hWnd);
+  [DllImport("user32.dll")] public static extern bool AttachThreadInput(uint a, uint b, bool f);
+  [DllImport("kernel32.dll")] public static extern uint GetCurrentThreadId();
+  [DllImport("user32.dll")] public static extern uint GetWindowThreadProcessId(IntPtr hWnd, out uint pid);
+  [DllImport("user32.dll")] public static extern void keybd_event(byte bVk, byte bScan, uint dwFlags, IntPtr dwExtraInfo);
+  [DllImport("user32.dll")] public static extern bool ShowWindow(IntPtr hWnd, int nCmdShow);
+  [DllImport("user32.dll")] public static extern bool IsIconic(IntPtr hWnd);
+  [DllImport("kernel32.dll")] public static extern bool FreeConsole();
+  [DllImport("kernel32.dll")] public static extern bool AttachConsole(uint pid);
+  [DllImport("kernel32.dll", CharSet=CharSet.Unicode)] public static extern bool SetConsoleTitle(string title);
+  [DllImport("kernel32.dll", CharSet=CharSet.Unicode)] public static extern uint GetConsoleTitle(StringBuilder sb, uint size);
+}
+"@
+function Get-WtWindows {
+  $wins = New-Object System.Collections.ArrayList
+  $cb = {
+    param($h, $lp)
+    if ([MmapWin]::IsWindowVisible($h)) {
+      $cls = New-Object System.Text.StringBuilder 256
+      [void][MmapWin]::GetClassName($h, $cls, 256)
+      if ($cls.ToString() -eq 'CASCADIA_HOSTING_WINDOW_CLASS') {
+        $t = New-Object System.Text.StringBuilder 512
+        [void][MmapWin]::GetWindowText($h, $t, 512)
+        [void]$wins.Add(@{ hwnd = $h.ToInt64(); title = $t.ToString() })
+      }
+    }
+    return $true
+  }
+  [void][MmapWin]::EnumWindows($cb, [IntPtr]::Zero)
+  return ,$wins
+}
+
+$ancestors = @()
+$p = $PID
+for ($i = 0; $i -lt 12 -and $p; $i++) {
+  $proc = Get-CimInstance Win32_Process -Filter "ProcessId=$p"
+  if (-not $proc) { break }
+  if ($i -gt 0) { $ancestors += [uint32]$proc.ProcessId }
+  $p = $proc.ParentProcessId
+}
+
+# The agent CLI (claude/codex/...) is some ancestor holding the console that a
+# WT window renders; hidden-console ancestors just never light a window up.
+$nonce = "__NONCE__"
+$hwnd = [IntPtr]::Zero
+foreach ($apid in $ancestors) {
+  [void][MmapWin]::FreeConsole()
+  if (-not [MmapWin]::AttachConsole($apid)) { continue }
+  $sb = New-Object System.Text.StringBuilder 1024
+  [void][MmapWin]::GetConsoleTitle($sb, 1024)
+  $orig = $sb.ToString()
+  for ($i = 0; $i -lt 6 -and $hwnd -eq [IntPtr]::Zero; $i++) {
+    [void][MmapWin]::SetConsoleTitle($nonce)
+    Start-Sleep -Milliseconds 60
+    foreach ($w in (Get-WtWindows)) {
+      if ($w.title -like "*$nonce*") { $hwnd = [IntPtr]$w.hwnd; break }
+    }
+  }
+  Start-Sleep -Milliseconds 100
+  [void][MmapWin]::SetConsoleTitle($orig)
+  Start-Sleep -Milliseconds 200
+  [void][MmapWin]::FreeConsole()
+  if ($hwnd -ne [IntPtr]::Zero) { break }
+}
+
+if ($hwnd -eq [IntPtr]::Zero) { Write-Output 'IDENT=0'; exit 0 }
+Write-Output "IDENT=$($hwnd.ToInt64())"
+
+if ([MmapWin]::IsIconic($hwnd)) { [void][MmapWin]::ShowWindow($hwnd, 9) }
+$focused = $false
+[void][MmapWin]::SetForegroundWindow($hwnd)
+Start-Sleep -Milliseconds 150
+if ([MmapWin]::GetForegroundWindow() -eq $hwnd) { $focused = $true }
+if (-not $focused) {
+  [MmapWin]::keybd_event(0x12, 0, 0, [IntPtr]::Zero)
+  [void][MmapWin]::SetForegroundWindow($hwnd)
+  [MmapWin]::keybd_event(0x12, 0, 2, [IntPtr]::Zero)
+  Start-Sleep -Milliseconds 150
+  if ([MmapWin]::GetForegroundWindow() -eq $hwnd) { $focused = $true }
+}
+if (-not $focused) {
+  $fgpid = 0
+  $fgThread = [MmapWin]::GetWindowThreadProcessId([MmapWin]::GetForegroundWindow(), [ref]$fgpid)
+  $myThread = [MmapWin]::GetCurrentThreadId()
+  [void][MmapWin]::AttachThreadInput($myThread, $fgThread, $true)
+  [void][MmapWin]::BringWindowToTop($hwnd)
+  [void][MmapWin]::SetForegroundWindow($hwnd)
+  [void][MmapWin]::AttachThreadInput($myThread, $fgThread, $false)
+  Start-Sleep -Milliseconds 150
+  if ([MmapWin]::GetForegroundWindow() -eq $hwnd) { $focused = $true }
+}
+Write-Output "FOCUS=$(if ($focused) { 1 } else { 0 })"
+`;
+
+function paneCommand() {
+  const cmd = ['--title', 'mellos map', '-d', projectDir, 'node', watchPath, '--file', mapFile];
+  if (flags.has('--ascii')) cmd.push('--ascii');
+  return cmd;
+}
+
+function openWt(args, what) {
+  const r = spawnSync('wt', args, { stdio: 'ignore', timeout: 15_000, windowsHide: true });
+  if (r.status !== 0) {
+    console.error(`wt failed to ${what} (exit ${r.status ?? 'timeout'}) — is Windows Terminal installed?`);
+    process.exit(1);
+  }
+}
+
+function openDedicatedWindow(reason) {
+  openWt(['-w', 'mellos-mapping', 'nt', ...paneCommand()], 'open the dedicated window');
+  console.log(`MMAP_PANE mode=window name=mellos-mapping reason=${reason}`);
+  console.log('Map opened in the dedicated "mellos-mapping" window.');
+}
+
+if (!flags.has('--force') && watcherAlreadyRunning()) {
+  console.log('MMAP_PANE already-open');
+  console.log(`A watcher for ${mapFile} is already running — not opening another pane (use --force to override).`);
+  process.exit(0);
+}
+
+if (flags.has('--window')) {
+  openDedicatedWindow('requested');
+  process.exit(0);
+}
+
+const nonce = `MMAP-NONCE-${process.pid}`;
+const out = runPowerShell(IDENTIFY_AND_FOCUS.replaceAll('__NONCE__', nonce));
+const ident = out.match(/IDENT=(\d+)/)?.[1] ?? '0';
+const focused = /FOCUS=1/.test(out);
+
+if (ident === '0') {
+  openDedicatedWindow('session-window-not-identified');
+} else if (!focused) {
+  openDedicatedWindow('session-window-focus-denied');
+} else {
+  // The identified window is foreground right now, so "most recently used"
+  // is deterministically it (see the race note in the header).
+  openWt(['-w', '0', 'sp', '-V', '--size', '0.42', ...paneCommand()], 'split the session window');
+  console.log(`MMAP_PANE mode=split hwnd=${ident}`);
+  console.log('Map opened beside this conversation (vertical split).');
+}