mellos-mapping 0.20.3 → 0.23.0

package/scripts/mmap.mjs

@@ -3,9 +3,9 @@
  * `mmap` — the human's entrance to the map pane. A TOGGLE.
  *
  *   mmap                      open the pane for this project, or close the one
- *                             that is already open
+ *                             that belongs to this console
  *   mmap <slug>               open the pane ON that page, or retarget the pane
- *                             that is already open. Never closes anything:
+ *                             that belongs to this console. Never closes anything:
  *                             naming a page is asking to SEE it
  *   mmap [--window] [--ascii] [--no-color] [--no-mouse] [--no-follow]
  *        [--interval <ms>] [--force]
@@ -28,6 +28,7 @@
  */
 import { existsSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
+import { paneFailureMessage } from './watcher-command.mjs';
 
 import {
   DEDICATED_WINDOW_NAME,
@@ -35,9 +36,10 @@ import {
   launchedAsEntry,
   loadPluginPaths,
   placePane,
+  preparePane,
+  awaitNewPane,
   pluginRootOf,
   takeWatcherFlag,
-  paneIsOpen,
   writeFocusRequest,
   writeQuitRequest,
 } from './pane-core.mjs';
@@ -168,37 +170,45 @@ async function main() {
     console.error(parsed.error);
     process.exit(1);
   }
-  if (process.platform !== 'win32') {
-    console.error('mmap opens the pane through Windows Terminal — on other platforms run the watcher yourself:');
-    console.error(`  node "${watchPath}" --file "<project>/${store.STATE_FILE_RELATIVE_PATH}"`);
-    process.exit(1);
-  }
-
-  const candidates = storeSearchPath(process.cwd());
+  const candidates = [store.resolveProjectDirectory(process.cwd())];
   const marker = storeMarkerOf(store.STATE_FILE_RELATIVE_PATH);
   const project = nearestProject(candidates, candidates.map((dir) => existsSync(join(dir, marker))));
   const cfg = { ...parsed.value, projectDir: project.root };
   const mapFile = join(project.root, store.STATE_FILE_RELATIVE_PATH);
-  const action = toggleAction(paneIsOpen(store, mapFile), cfg.pageSlug, cfg.force);
+  const fail = (error) => {
+    console.error(paneFailureMessage(error, cfg, watchPath, mapFile));
+    process.exit(1);
+  };
+  const prepared = preparePane(cfg, store, mapFile);
+  if (!prepared.ok) {
+    fail(prepared.error);
+  }
+  const context = prepared.value;
+  const action = toggleAction(context.viewer !== undefined, cfg.pageSlug, cfg.force);
 
   if (action.kind === 'quit') {
-    writeQuitRequest(store.quitFilePath(mapFile));
+    writeQuitRequest(store.quitFilePath(mapFile, context.viewer.pid));
     console.log(`Closing the map pane for ${project.root}.`);
     return;
   }
   if (action.kind === 'focus') {
-    writeFocusRequest(store.focusFilePath(mapFile), action.page);
+    writeFocusRequest(store.focusFilePath(mapFile, context.viewer.pid), action.page);
     console.log(`The map pane for ${project.root} is already open — showing page "${action.page}".`);
     return;
   }
 
-  const placed = placePane(cfg, watchPath, mapFile);
+  const placed = placePane(cfg, watchPath, mapFile, context.target);
   if (!placed.ok) {
-    console.error(placed.error);
-    process.exit(1);
+    fail(placed.error);
+  }
+  const reported = await awaitNewPane(store, mapFile, context);
+  if (!reported.ok) {
+    fail(reported.error);
   }
   const where =
-    placed.value.mode === PANE_MODE.window
+    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)';
   console.log(`Map opened for ${project.root} ${where}.`);

package/scripts/open-pane.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * Open the live map pane in the RIGHT Windows Terminal window — the AGENT's
+ * Open the live map pane in the owning Windows Terminal or tmux session — the AGENT's
  * launcher, addressed by `/mmap` and by the skill.
  *
  *   node scripts/open-pane.mjs <project-dir> [--page <slug>] [--window] [--force]
@@ -16,7 +16,7 @@
  * machine-readable report on top.
  *
  * --page <slug> opens the map ON that page (the effort under discussion, not
- * whatever page the store lists first). With a watcher already running it
+ * whatever page the store lists first). With a watcher owned by this console already running it
  * writes the one-shot focus file instead — the existing pane retargets within
  * a poll tick — so re-running with --page is also how you steer an open pane.
  * Every other flag belongs to the WATCHER and is forwarded verbatim; an
@@ -31,6 +31,7 @@
  */
 import { existsSync } from 'node:fs';
 import { join, resolve } from 'node:path';
+import { paneFailureMessage } from './watcher-command.mjs';
 
 import {
   DEDICATED_WINDOW_NAME,
@@ -38,9 +39,11 @@ import {
   launchedAsEntry,
   loadPluginPaths,
   placePane,
+  preparePane,
+  revealPane,
+  awaitNewPane,
   pluginRootOf,
   takeWatcherFlag,
-  paneIsOpen,
   writeFocusRequest,
 } from './pane-core.mjs';
 
@@ -108,35 +111,51 @@ async function main() {
     console.error(`project directory does not exist: ${cfg.projectDir}`);
     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 mapFile = join(cfg.projectDir, store.STATE_FILE_RELATIVE_PATH);
 
-  if (!cfg.force && paneIsOpen(store, mapFile)) {
+  const fail = (error) => {
+    console.error(paneFailureMessage(error, cfg, watchPath, mapFile));
+    process.exit(1);
+  };
+
+  const prepared = preparePane(cfg, store, mapFile);
+  if (!prepared.ok) {
+    fail(prepared.error);
+  }
+  const context = prepared.value;
+  if (!cfg.force && context.viewer) {
+    const visible = revealPane(context.target, context.viewer);
+    if (!visible.ok) fail(visible.error);
     if (cfg.pageSlug !== undefined) {
-      writeFocusRequest(store.focusFilePath(mapFile), cfg.pageSlug);
-      console.log(`MMAP_PANE already-open refocused=${cfg.pageSlug}`);
+      writeFocusRequest(store.focusFilePath(mapFile, context.viewer.pid), cfg.pageSlug);
+      console.log(`MMAP_PANE already-open pid=${context.viewer.pid} visibility=${visible.value} refocused=${cfg.pageSlug}`);
       console.log(`A watcher for ${mapFile} is already running — asked it to show page "${cfg.pageSlug}".`);
     } else {
-      console.log('MMAP_PANE already-open');
+      console.log(`MMAP_PANE already-open pid=${context.viewer.pid} visibility=${visible.value}`);
       console.log(`A watcher for ${mapFile} is already running — not opening another pane (use --force to override).`);
     }
     process.exit(0);
   }
 
-  const placed = placePane(cfg, watchPath, mapFile);
+  const placed = placePane(cfg, watchPath, mapFile, context.target);
   if (!placed.ok) {
-    console.error(placed.error);
-    process.exit(1);
+    fail(placed.error);
+  }
+  const reported = await awaitNewPane(store, mapFile, context);
+  if (!reported.ok) {
+    fail(reported.error);
   }
-  if (placed.value.mode === PANE_MODE.window) {
-    console.log(`MMAP_PANE mode=window name=${DEDICATED_WINDOW_NAME} reason=${placed.value.reason}`);
+  const visible = revealPane(context.target, reported.value);
+  if (!visible.ok) fail(visible.error);
+  if (placed.value.backend === 'tmux') {
+    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.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.`);
   } else {
-    console.log(`MMAP_PANE mode=split hwnd=${placed.value.hwnd}`);
+    console.log(`MMAP_PANE mode=split pid=${reported.value.pid} hwnd=${placed.value.hwnd}`);
     console.log('Map opened beside this conversation (vertical split).');
   }
 }

package/scripts/pane-core.mjs

@@ -29,7 +29,9 @@
  *
  * Pure helpers are exported for the spec; nothing here runs on import.
  */
-import { spawnSync } from 'node:child_process';
+import * as terminal from './terminal-session.mjs';
+import { createTmuxAdapter } from './tmux-session.mjs';
+import { watcherArgs } from './watcher-command.mjs';
 import { existsSync, mkdirSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
@@ -185,234 +187,69 @@ export function writeQuitRequest(quitFile) {
 
 /** The `wt` payload that runs the watcher: the pane's title, cwd and command. */
 export function paneCommand(cfg, watchPath, mapFile) {
-  const cmd = ['--title', 'mellos map', '-d', cfg.projectDir, 'node', watchPath, '--file', mapFile, ...cfg.watcherFlags];
-  if (cfg.pageSlug !== undefined) cmd.push('--page', cfg.pageSlug);
-  return cmd;
+  return ['--title', 'mellos map', '-d', cfg.projectDir, 'node', ...watcherArgs(cfg, watchPath, mapFile)];
 }
 
-/** Quote one value into a PowerShell single-quoted string literal. */
-export function powerShellQuote(value) {
-  return `'${value.replace(/'/g, "''")}'`;
-}
-
-/**
- * Script that counts running watchers of `mapFile`.
- *
- * String.IndexOf, not `-like`: a wildcard match treats `[`, `]`, `?` and `*`
- * in the path as pattern syntax, so a project under `C:\work\[wip]\app` never
- * matched its own watcher and every /mmap opened another pane. Ordinal
- * case-insensitive keeps the old matching behavior for Windows paths that
- * differ only in case.
- */
-export function watcherProbeScript(mapFile) {
-  return (
-    `$ErrorActionPreference = 'SilentlyContinue'\n` +
-    `$needle = ${powerShellQuote(mapFile)}\n` +
-    `$w = @(Get-CimInstance Win32_Process -Filter "Name='node.exe'" | Where-Object {\n` +
-    `  $_.CommandLine -and\n` +
-    `  $_.CommandLine.IndexOf('watch.mjs', [StringComparison]::OrdinalIgnoreCase) -ge 0 -and\n` +
-    `  $_.CommandLine.IndexOf($needle, [StringComparison]::OrdinalIgnoreCase) -ge 0\n` +
-    `})\n` +
-    `Write-Output "WATCHERS=$($w.Count)"`
-  );
-}
+/** Explicitly requested independent window; default opens never fall back here. */
+export const DEDICATED_WINDOW_NAME = 'mellos-mapping';
+const SPLIT_SIZE = '0.42';
 
-// 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
+/** Pure reuse rule: a live viewer belongs to a console, not just to a project. */
+export function selectPaneViewer(viewers, owners) {
+  return viewers.find((viewer) => viewer.owner !== undefined && owners.includes(viewer.owner));
 }
 
-$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
-}
+const platformTerminal = () => process.platform === 'win32' ? terminal : createTmuxAdapter();
 
-# 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 }
-    }
+/** 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
+    ? { 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)) {
+    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.' };
   }
-  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 }
+  return { ok: true, value: {
+    target: { ...session, mode: cfg.mode, owner: session.owner ?? viewer?.owner },
+    viewer,
+    previousPids: viewers.map((item) => item.pid),
+  } };
 }
-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 })"
-`;
-
-/** How long the window probe may take before it is abandoned, in ms. */
-const PROBE_TIMEOUT_MS = 30_000;
-/** How long `wt` may take to open a pane before it is abandoned, in ms. */
-const WT_TIMEOUT_MS = 15_000;
-/** Fraction of the session window the split pane takes. */
-const SPLIT_SIZE = '0.42';
-/** Name of the window the pane falls back to — deterministic, never a random one. */
-export const DEDICATED_WINDOW_NAME = 'mellos-mapping';
 
-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: PROBE_TIMEOUT_MS, windowsHide: true },
-  );
-  return r.stdout ?? '';
+/** 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' };
 }
 
-/**
- * Is a pane of `mapFile` already open?
- *
- * One pane 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.
- *
- * The panes answer this themselves: each one refreshes a report in the
- * store while it is up (the viewers channel, src/store/store.ts), so a live
- * report IS a live pane. Exact, instant, cross-platform, and the same
- * answer the MCP server reads when it tells an assistant whether anybody is
- * looking — three surfaces, one truth.
- *
- * The process scan below is the fallback for exactly one case: a watcher
- * that started before this version and publishes no report. It costs a
- * PowerShell round trip and only ever runs on the path that is about to
- * open a window anyway. It can go once no pre-0.20.2 pane can still be up.
- *
- * @param store - the store module (dist/store-paths.mjs), the plugin's one
- *   definition of where anything lives.
- */
-export function paneIsOpen(store, mapFile) {
-  if (store.readLiveViewers(mapFile, Date.now()).length > 0) return true;
-  if (process.platform !== 'win32') return false;
-  const m = runPowerShell(watcherProbeScript(mapFile)).match(/WATCHERS=(\d+)/);
-  return m !== null && Number(m[1]) > 0;
-}
-
-function openWt(args, what) {
-  const r = spawnSync('wt', args, { stdio: 'ignore', timeout: WT_TIMEOUT_MS, windowsHide: true });
-  return r.status === 0
-    ? { ok: true, value: undefined }
-    : { ok: false, error: `wt failed to ${what} (exit ${r.status ?? 'timeout'}) — is Windows Terminal installed?` };
-}
-
-/**
- * Open the pane, wherever it can honestly be put.
- *
- * `--window` (cfg.mode === PANE_MODE.window) goes straight to the dedicated
- * window. Otherwise the session's own Windows Terminal window is identified
- * by a console-title nonce and brought to the foreground; only once it is
- * provably the foreground window does `wt -w 0 sp` split it, because
- * "most recently used" is the only thing `wt` can be told to target. Either
- * step failing falls back to the dedicated window — deterministic, never a
- * random one.
- *
- * @returns ok with how it was placed (the caller words the news for its own
- *   audience), or err with a message when `wt` itself refused.
- */
-export function placePane(cfg, watchPath, mapFile) {
-  const dedicated = (reason) => {
-    const opened = openWt(['-w', DEDICATED_WINDOW_NAME, 'nt', ...paneCommand(cfg, watchPath, mapFile)], 'open the dedicated window');
-    return opened.ok ? { ok: true, value: { mode: PANE_MODE.window, reason } } : opened;
-  };
-  if (cfg.mode === PANE_MODE.window) return dedicated('requested');
-
-  const nonce = `MMAP-NONCE-${process.pid}`;
-  const out = runPowerShell(IDENTIFY_AND_FOCUS.replaceAll('__NONCE__', nonce));
-  const ident = out.match(/IDENT=(\d+)/)?.[1] ?? '0';
-  if (ident === '0') return dedicated('session-window-not-identified');
-  if (!/FOCUS=1/.test(out)) return dedicated('session-window-focus-denied');
-
-  // The identified window is foreground right now, so "most recently used" is
-  // deterministically it. Known race, accepted: a user who focuses a DIFFERENT
-  // terminal window in the ~1s before wt reads its MRU state can still get the
-  // split there — a window they are at least actively in.
-  const split = openWt(
-    ['-w', '0', 'sp', '-V', '--size', SPLIT_SIZE, ...paneCommand(cfg, watchPath, mapFile)],
-    'split the session window',
-  );
-  return split.ok ? { ok: true, value: { mode: PANE_MODE.split, hwnd: ident } } : split;
+/** 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);
+  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');
+    return opened.ok ? { ok: true, value: { ...target, reason: 'requested' } } : opened;
+  }
+  const focused = io.focusSession(target.hwnd);
+  if (!focused.ok) return focused;
+  const opened = io.openWt([
+    '-w', '0', 'sp', '-V', '--size', SPLIT_SIZE, ...payload,
+    ';', 'move-focus', 'previous',
+  ], 'split the session window');
+  return opened.ok ? { ok: true, value: target } : opened;
+}
+
+/** Wait for the newly launched, correctly bound watcher rather than an older window. */
+export async function awaitNewPane(store, mapFile, context, timeoutMs = 8_000) {
+  const deadline = Date.now() + timeoutMs;
+  do {
+    const viewer = store.readLiveViewers(mapFile, Date.now()).find((item) =>
+      item.owner === context.target.owner && !context.previousPids.includes(item.pid));
+    if (viewer) return { ok: true, value: viewer };
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  } while (Date.now() < deadline);
+  return { ok: false, error: 'The requested pane has not reported in. Its placement is unverified; do not assume that another open map is the requested split.' };
 }

package/scripts/terminal-session.mjs

@@ -0,0 +1,137 @@
+/** Windows Terminal adapter. No project paths, reuse policy or persistent state. */
+import { spawnSync } from 'node:child_process';
+
+const NATIVE = String.raw`
+$ErrorActionPreference = 'Stop'
+$ProgressPreference = 'SilentlyContinue'
+Add-Type @"
+using System;
+using System.Text;
+using System.Runtime.InteropServices;
+public class MmapSession {
+  public delegate bool Callback(IntPtr hwnd, IntPtr lp);
+  [DllImport("user32.dll")] public static extern bool EnumWindows(Callback cb, 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 text, int size);
+  [DllImport("user32.dll", CharSet=CharSet.Unicode)] public static extern int GetWindowText(IntPtr hwnd, StringBuilder text, int size);
+  [DllImport("user32.dll")] public static extern IntPtr GetForegroundWindow();
+  [DllImport("user32.dll")] public static extern bool SetForegroundWindow(IntPtr hwnd);
+  [DllImport("kernel32.dll")] public static extern bool FreeConsole();
+  [DllImport("kernel32.dll")] public static extern bool AttachConsole(uint pid);
+  [DllImport("kernel32.dll")] public static extern uint GetConsoleProcessList(uint[] list, uint size);
+  [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 text, uint size);
+}
+"@
+`;
+
+/** A temporary title identifies the active session without guessing from titles or MRU order. */
+export function sessionProbeScript(nonce) {
+  return NATIVE + String.raw`
+$processes = @{}
+Get-CimInstance Win32_Process | ForEach-Object { $processes[[uint32]$_.ProcessId] = $_ }
+$cursor = [uint32]$PID
+$seen = @{}
+$hwnd = [IntPtr]::Zero
+for ($depth = 0; $depth -lt 16 -and $processes.ContainsKey($cursor); $depth++) {
+  [void][MmapSession]::FreeConsole()
+  if ([MmapSession]::AttachConsole($cursor)) {
+    $members = New-Object uint32[] 4096
+    $count = [MmapSession]::GetConsoleProcessList($members, $members.Length)
+    if ($count -gt 0 -and $count -le $members.Length) {
+      $root = $members[0..($count - 1)] | ForEach-Object { $processes[$_] } |
+        Where-Object { $_ -and $_.CreationDate } | Sort-Object CreationDate | Select-Object -First 1
+      if ($root) {
+        $owner = "split-$($root.ProcessId)-$($root.CreationDate.ToUniversalTime().Ticks)"
+        if (-not $seen.ContainsKey($owner)) {
+          $seen[$owner] = $true
+          Write-Output "CONSOLE=$owner"
+          $text = New-Object System.Text.StringBuilder 1024
+          [void][MmapSession]::GetConsoleTitle($text, 1024)
+          $original = $text.ToString()
+          try {
+            for ($attempt = 0; $attempt -lt 6 -and $hwnd -eq [IntPtr]::Zero; $attempt++) {
+              [void][MmapSession]::SetConsoleTitle('__NONCE__')
+              Start-Sleep -Milliseconds 60
+              $matches = New-Object System.Collections.ArrayList
+              $callback = {
+                param($window, $unused)
+                if ([MmapSession]::IsWindowVisible($window)) {
+                  $class = New-Object System.Text.StringBuilder 256
+                  [void][MmapSession]::GetClassName($window, $class, 256)
+                  if ($class.ToString() -eq 'CASCADIA_HOSTING_WINDOW_CLASS') {
+                    $title = New-Object System.Text.StringBuilder 1024
+                    [void][MmapSession]::GetWindowText($window, $title, 1024)
+                    if ($title.ToString().Contains('__NONCE__')) { [void]$matches.Add($window) }
+                  }
+                }
+                return $true
+              }
+              [void][MmapSession]::EnumWindows($callback, [IntPtr]::Zero)
+              if ($matches.Count -eq 1) { $hwnd = $matches[0] }
+            }
+          } finally {
+            [void][MmapSession]::SetConsoleTitle($original)
+            [void][MmapSession]::FreeConsole()
+          }
+          if ($hwnd -ne [IntPtr]::Zero) {
+            Write-Output "OWNER=$owner"
+            break
+          }
+        }
+      }
+    }
+  }
+  $cursor = [uint32]$processes[$cursor].ParentProcessId
+}
+[void][MmapSession]::FreeConsole()
+Write-Output "IDENT=$($hwnd.ToInt64())"
+`.replaceAll('__NONCE__', nonce);
+}
+
+function powershell(script, timeout = 30_000) {
+  const result = spawnSync('powershell.exe', [
+    '-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-EncodedCommand',
+    Buffer.from(script, 'utf16le').toString('base64'),
+  ], { encoding: 'utf8', windowsHide: true, timeout });
+  return result.status === 0
+    ? { ok: true, value: result.stdout }
+    : { ok: false, error: `Terminal session probe failed (${result.error?.message ?? `exit ${result.status}`}).` };
+}
+
+export function parseSessionProbe(output) {
+  const owners = [...output.matchAll(/^CONSOLE=(split-\d+-\d+)\r?$/gm)].map((m) => m[1]);
+  const hwnd = /^IDENT=([1-9]\d*)\r?$/m.exec(output)?.[1];
+  const owner = /^OWNER=(split-\d+-\d+)\r?$/m.exec(output)?.[1];
+  return { owners, ...(hwnd && owner && owners.includes(owner) ? { hwnd, owner } : {}) };
+}
+
+export function inspectSession() {
+  const result = powershell(sessionProbeScript(`MMAP-SESSION-${process.pid}-${Date.now()}`));
+  return result.ok ? { ok: true, value: parseSessionProbe(result.value) } : result;
+}
+
+/** WT's -w 0 is MRU-based, so it is only usable after verifying the exact foreground HWND. */
+export function focusSession(hwnd) {
+  if (!/^[1-9]\d*$/.test(hwnd)) return { ok: false, error: 'Invalid terminal window handle.' };
+  const result = powershell(NATIVE + `
+$window = [IntPtr]${hwnd}
+if ([MmapSession]::GetForegroundWindow() -ne $window) {
+  [void][MmapSession]::SetForegroundWindow($window)
+  Start-Sleep -Milliseconds 150
+}
+Write-Output "FOCUS=$([MmapSession]::GetForegroundWindow() -eq $window)"
+`, 5_000);
+  if (!result.ok) return result;
+  return /^FOCUS=True\r?$/m.test(result.value)
+    ? { ok: true, value: undefined }
+    : { ok: false, error: 'The session window was identified, but Windows refused to focus it. Activate the PowerShell tab for this conversation and retry; no separate window was opened.' };
+}
+
+export function openWt(args, what) {
+  // This is the requested interactive application. SW_HIDE also hides new WT windows.
+  const result = spawnSync('wt', args, { stdio: 'ignore', timeout: 15_000, windowsHide: false });
+  return result.status === 0
+    ? { ok: true, value: undefined }
+    : { ok: false, error: `wt failed to ${what} (${result.error?.message ?? `exit ${result.status}`}).` };
+}