workmap 0.1.0__py3-none-any.whl

workmap/drivers/__init__.py

@@ -0,0 +1,93 @@
+"""Terminal drivers, and the contract every one of them meets.
+
+One driver exists. The point of this package is that the second one is a new
+file rather than a diff against the first, and that "the contract" is a list
+something can be checked against instead of a paragraph at the top of a module.
+
+    CONTRACT   the names a driver must define, and what each is for
+    for_host() pick the driver for the terminal we are actually running in
+
+A driver is a plain module. There is no base class, because there is nothing
+to share: two drivers speaking to two different applications have no
+implementation in common, only a shape. `tests/test_driver_contract.py` checks
+the shape.
+"""
+from __future__ import annotations
+
+import os
+
+# Every name a driver has to define, and why it exists. The prose is here
+# rather than in a docstring because the conformance test reads these keys, so
+# adding a capability to the contract and forgetting to check for it is not
+# possible.
+CONTRACT = {
+    # -- reading ----------------------------------------------------------
+    "list_terminal_tabs":
+        "-> [{window_id:int, title:str, tty:str, profile:str}] for every tab "
+        "open. The desk is built from this and nothing else.",
+    "terminal_status":
+        '-> {"ok": bool, "reason": str, "fix": str}. Why the last query '
+        "failed, so the UI can say so instead of drawing an empty desk and "
+        "implying the machine is idle, and what the reader can do about it. "
+        "`fix` is empty when there is nothing useful to suggest: only one of "
+        "these failures is a permission problem, and the Automation "
+        "instructions were once printed for all of them.",
+    "owner_pids":
+        "(ps rows) -> pids of the emulator itself. The orphan sweep decides "
+        "a process is nobody's by walking its ancestry, and this is what "
+        "makes a live session somebody's. The one that is easy to leave out "
+        "and expensive to get wrong.",
+    "list_profiles":
+        "-> [{name, swatch}] of the colour schemes this emulator has.",
+    "available_profile_names":
+        "-> {str}. Just the names, for validating a remembered choice.",
+    "unsupported_host":
+        '-> "" if this driver can drive the terminal we are in, else why not.',
+    "desktop_bounds":
+        "-> (left, top, right, bottom) of the usable screen.",
+    # -- changing ---------------------------------------------------------
+    "set_window_titles": "({window_id: title}) -> None. Batched.",
+    "set_front_title": "(title) -> None. The front tab only, no scan.",
+    "paint_front_window": "(profile) -> None. The front tab only, no scan.",
+    "apply_profile": "([window_id], profile) -> None.",
+    "place_windows":
+        "([(window_id, (l, t, r, b))]) -> int, how many actually moved. One "
+        "call, not one per window. Not how many were asked to: macOS window "
+        "tiling accepts the write and discards it, so an emulator that cannot "
+        "move a window has to say so rather than let the caller claim it did.",
+    "close_windows":
+        "([window_id]) -> int, how many actually closed. Not how many were "
+        "asked to: an emulator may refuse, and saying so is the contract.",
+    "focus_window": "(window_id) -> None.",
+    "ensure_title_settings":
+        "() -> None. Idempotent. Turn off whatever noise the emulator puts in "
+        "a title by default, once per process.",
+}
+
+# What each driver answers to, by $TERM_PROGRAM. A terminal absent from here
+# is not unsupported, it is undriven: workmap still runs, and says which desk
+# it is actually showing you.
+BY_TERM_PROGRAM = {
+    "Apple_Terminal": "apple_terminal",
+}
+
+DEFAULT = "apple_terminal"
+
+
+def for_host(term_program: str | None = None):
+    """The driver for the terminal we are running in, or the default.
+
+    Falling back rather than failing is deliberate. Running workmap from
+    inside another emulator is not an error, it just means the desk you are
+    shown is not the desk in front of you, and `unsupported_host()` is what
+    says so. Refusing to start would be worse: the orphans are still real.
+    """
+    if term_program is None:
+        term_program = os.environ.get("TERM_PROGRAM", "")
+    name = BY_TERM_PROGRAM.get(term_program.strip(), DEFAULT)
+    return load(name)
+
+
+def load(name: str):
+    from importlib import import_module
+    return import_module(f".{name}", __name__)

workmap/drivers/apple_terminal.py

@@ -0,0 +1,578 @@
+"""The only module that speaks AppleScript. The terminal driver.
+
+Everything macOS-and-Terminal.app-specific is behind this seam. A driver for
+another emulator reimplements this file and nothing else, so what counts as
+"this file" has to be written down:
+
+    list_terminal_tabs()  -> [{window_id, title, tty, profile}]
+    terminal_status()     -> {"ok": bool, "reason": str}
+    owner_pids(rows)      -> pids of the emulator itself
+    list_profiles()       -> [{name, swatch}]
+    available_profile_names() -> {str}
+    unsupported_host()    -> "" or why this driver cannot drive what you are in
+
+    set_window_titles / apply_profile / place_windows / close_windows
+    paint_front_window / set_front_title / focus_window / ensure_title_settings
+
+`owner_pids` is the one that is easy to leave out and expensive to get wrong.
+The orphan sweep decides a process is nobody's by walking its ancestry; the
+emulator is what makes a process somebody's. On this driver that happened to
+work for free, because Terminal.app is a .app bundle and the sweep already
+skips anything descended from one, so every process in every tab was
+protected by accident rather than by intent. A driver whose emulator is not an
+app bundle would have quietly lost that protection and started offering live
+sessions for killing. It is explicit now.
+"""
+from __future__ import annotations
+
+import contextlib
+import fcntl
+import os
+import re
+import subprocess
+from pathlib import Path
+
+from ..model import executable_of
+from ..procs import run_safe
+from ..themes import ASSIGN_ORDER, PROFILE_SWATCHES
+
+# What this driver drives.
+HOST_APP = "Terminal.app"
+HOST_EXECUTABLE = "Terminal.app/Contents/MacOS/Terminal"
+HOST_TERM_PROGRAM = "Apple_Terminal"   # what Terminal.app sets in the env
+
+
+# Serialize all Terminal AppleScript. Concurrent osascript calls + Shell/Window
+# menus = Terminal UI freeze (dropdown stuck open until force-quit).
+# Runtime state, deliberately not inside the source tree: every copy of
+# workmap (checkout, pipx, uv tool) must contend for the *same* lock, and a
+# pip-installed package has no business writing into site-packages.
+_TERMINAL_LOCK = Path.home() / ".local" / "state" / "workmap" / "terminal.lock"
+
+_titles_simplified = False
+
+# Why the last Terminal query failed, and what the reader can do about it, so
+# the UI can say so instead of rendering an empty desk and implying nothing is
+# open. Only one of the failures is a permission problem, and the Automation
+# instructions used to be printed for all of them.
+_terminal_status: dict = {"ok": True, "reason": "", "fix": ""}
+
+# The action only. Each surface adds its own "then run this again" or "then
+# press r", because the two do not retry the same way.
+AUTOMATION_FIX = "Allow it under System Settings > Privacy & Security > Automation."
+
+
+def terminal_status() -> dict:
+    return dict(_terminal_status)
+
+
+def owner_pids(rows: list[dict]) -> set[int]:
+    """The emulator's own processes, from a `ps` snapshot.
+
+    Anything descended from one of these is a live session someone is sitting
+    in, not an orphan. Part of the driver contract. See the module docstring
+    for why this must not be left to inference.
+
+    Read from the executable, not from anywhere in the command line. This was
+    the fourth outing of the bug this codebase keeps finding: `HOST_EXECUTABLE
+    in r["cmd"]` matched any process that merely mentioned Terminal's path in
+    an argument, and made that process protect its whole subtree. It errs
+    toward protection, so nothing was ever killed by it and nothing on this
+    machine matches it today, which is exactly why it survived three rounds of
+    the same fix elsewhere.
+    """
+    return {r["pid"] for r in rows
+            if executable_of(r["cmd"]).endswith(HOST_EXECUTABLE)}
+
+
+def unsupported_host() -> str:
+    """Why this driver cannot drive the terminal you are actually in.
+
+    Running workmap inside iTerm2 or Ghostty is not an error, but it is not
+    what it looks like either: the AppleScript queries answer for Terminal.app
+    windows, so you get a map of a desk that is not the one in front of you.
+    Say so rather than showing an empty or misleading one.
+    """
+    current = os.environ.get("TERM_PROGRAM", "").strip()
+    if not current or current == HOST_TERM_PROGRAM:
+        return ""
+    return f"showing {HOST_APP} windows only: this looks like {current}"
+
+
+def _note_terminal(ok: bool, reason: str = "", fix: str = "") -> None:
+    _terminal_status["ok"] = ok
+    _terminal_status["reason"] = reason
+    _terminal_status["fix"] = fix
+
+
+def as_string(value: str) -> str:
+    """A Python string as the body of an AppleScript string literal.
+
+    Backslash first, then quote. The other order is not a style preference:
+    it escapes the quote, then escapes the backslash it just wrote, and the
+    literal reopens. Any function here that builds a script by concatenation
+    has to go through this.
+
+    The bug this closes was real and reachable. Escaping only quotes left a
+    name ending in a backslash able to close the literal early, after which
+    the rest of the name was parsed as AppleScript rather than data:
+
+        profile = 'Basic\\" & (do shell script "...") --'
+
+    ran the shell command. Profile names come from the config file and from
+    Terminal's own settings sets, so this is not attacker-facing on a healthy
+    machine, but it is arbitrary code execution from a string this module
+    treats as untrusted everywhere else.
+
+    Control characters are dropped rather than escaped. A tab title with a
+    newline in it is not a title anyone wanted, and leaving them in means
+    every caller has to reason about a second way to end a line.
+    """
+    cleaned = "".join(
+        " " if ch in "\t\n\r" else ch
+        for ch in value if (ch >= " " and ch != "\x7f") or ch in "\t\n\r"
+    )
+    return cleaned.replace("\\", "\\\\").replace('"', '\\"')
+
+
+def _osascript(script: str, *, timeout: float = 8.0) -> str:
+    """Run AppleScript against Terminal under a process lock + timeout.
+
+    Without this, paint/refresh/organize pile up Apple Events on Terminal's
+    main thread and menus (Shell → New Tab, etc.) freeze mid-open.
+    """
+    try:
+        _TERMINAL_LOCK.parent.mkdir(parents=True, exist_ok=True)
+        lock = open(_TERMINAL_LOCK, "a+", encoding="utf-8")
+    except OSError:
+        # A read-only home, a full disk, or ~/.local/state existing as a
+        # file. Serialising Apple Events is an optimisation; not being able
+        # to is not a reason to end with a traceback in place of the desk.
+        lock = None
+    with contextlib.ExitStack() as stack:
+        if lock is not None:
+            stack.enter_context(lock)
+            try:
+                fcntl.flock(lock.fileno(), fcntl.LOCK_EX)
+            except OSError:
+                pass
+        try:
+            out = subprocess.check_output(
+                ["osascript"],
+                input=script,
+                text=True,
+                stderr=subprocess.PIPE,
+                timeout=timeout,
+            )
+            _note_terminal(True)
+            return out
+        except subprocess.TimeoutExpired:
+            _note_terminal(False, "Terminal isn't responding",
+                           "It may be busy; give it a moment.")
+        except subprocess.CalledProcessError as exc:
+            err = (exc.stderr or "").strip()
+            if "-1743" in err or "not allowed" in err.lower():
+                reason, fix = ("macOS hasn't authorised Terminal automation",
+                               AUTOMATION_FIX)
+            elif "-600" in err or "not running" in err.lower():
+                reason, fix = "Terminal isn't running", "Open Terminal."
+            else:
+                reason, fix = "Terminal automation failed", ""
+            _note_terminal(False, reason, fix)
+        except OSError:
+            _note_terminal(False, "could not run osascript", "")
+        return ""
+
+_profiles_cache: list[dict] | None = None
+
+
+def list_profiles(*, refresh: bool = False) -> list[dict]:
+    """Terminal's settings sets, cached. Otherwise it is an osascript
+    round-trip per redraw for a list that only changes when you edit
+    Terminal's preferences."""
+    global _profiles_cache
+    if _profiles_cache is not None and not refresh:
+        return list(_profiles_cache)
+    script = '''
+tell application "Terminal"
+  set out to ""
+  repeat with s in settings sets
+    set out to out & (name of s) & linefeed
+  end repeat
+  return out
+end tell
+'''
+    raw = _osascript(script, timeout=4.0)
+    if not raw.strip():
+        raw = "\n".join(PROFILE_SWATCHES.keys())
+    names = [ln.strip() for ln in raw.splitlines() if ln.strip()]
+    out = []
+    for name in names:
+        sw = PROFILE_SWATCHES.get(name, {"bg": "#333", "fg": "#eee", "rail": "#666"})
+        out.append({"name": name, "swatch": sw})
+    # stable order: assign order first, then the rest
+    order = {n: i for i, n in enumerate(ASSIGN_ORDER)}
+    out.sort(key=lambda p: (order.get(p["name"], 100), p["name"]))
+    _profiles_cache = out
+    return list(out)
+
+_available_profiles: set[str] | None = None
+
+
+def available_profile_names() -> set[str]:
+    global _available_profiles
+    if _available_profiles is None:
+        _available_profiles = {p["name"] for p in list_profiles()}
+    return _available_profiles
+
+
+def list_terminal_tabs() -> list[dict]:
+    """List Terminal windows/tabs with a light, race-safe AppleScript.
+
+    Snapshot window ids first (don't iterate a live `windows` list, that
+    throws -1728 when tabs open/close mid-scan and blocks Shell menus).
+    Skip `busy` and `processes`: ps already has that, and those queries are
+    the expensive main-thread work.
+
+    Properties are read for every tab at once rather than a tab at a time.
+    Each property access is an Apple Event onto Terminal's main thread and
+    they cost about 5ms each, so asking per tab made the whole scan scale with
+    the number of tabs open: measured on a real desk, 9 tabs took 0.57s and 49
+    took 3.7s, heading for the timeout below at somewhere under a hundred.
+    `tty of every tab` is one event for the lot, which leaves the cost
+    proportional to windows instead. Same output, verified against the
+    per-tab version on a live desk.
+    """
+    script = r'''
+tell application "Terminal"
+  set out to ""
+  set widList to {}
+  try
+    set widList to id of every window
+  end try
+  repeat with wid in widList
+    try
+      set w to window id wid
+      set out to out & "WINDOW|" & wid & "|" & (name of w) & linefeed
+      set ttys to tty of every tab of w
+      set sets to name of current settings of every tab of w
+      repeat with i from 1 to (count of ttys)
+        set tn to item i of ttys
+        set sn to item i of sets
+        if tn is missing value then set tn to ""
+        if sn is missing value then set sn to ""
+        set out to out & "TAB|" & wid & "|" & tn & "|profile=" & sn & linefeed
+      end repeat
+    end try
+  end repeat
+  return out
+end tell
+'''
+    # Generous, because the honest reason this takes a while is usually a big
+    # desk rather than a wedged Terminal, and reporting "Terminal isn't
+    # responding" to someone with sixty tabs open would be a lie.
+    raw = _osascript(script, timeout=20.0)
+    if not raw.strip():
+        return []
+    windows: dict[int, str] = {}
+    tabs: list[dict] = []
+    # Both record types put the free-text field last and split up to it, so a
+    # window title or a profile name containing the separator stays whole. A
+    # line whose id is not a number is not one of ours: window titles are
+    # written by whatever is running in the tab, and a newline in one would
+    # otherwise turn the rest of that title into a record of its own.
+    for line in raw.splitlines():
+        try:
+            if line.startswith("WINDOW|"):
+                _, wid_s, name = line.split("|", 2)
+                windows[int(wid_s)] = name
+                continue
+            if not line.startswith("TAB|"):
+                continue
+            _, wid_s, tty, rest = line.split("|", 3)
+            wid = int(wid_s)
+        except ValueError:
+            continue
+        profile = rest[len("profile="):] if rest.startswith("profile=") else ""
+        tabs.append({
+                "window_id": wid,
+                "title": windows.get(wid, ""),
+                "tty": tty,
+                "busy": False,
+                "procs": "",
+                "profile": profile,
+            })
+    return tabs
+
+
+def desktop_bounds() -> tuple[int, int, int, int]:
+    """The usable screen, as (left, top, right, bottom).
+
+    Signed. A second display arranged to the left of or above the main one
+    has negative coordinates, and reading the digits without their sign
+    turned -1512 into 1512: the rect collapsed and `organize` piled every
+    window into a sliver. Only ever seen on one display here, which is
+    exactly the kind of thing one machine cannot show you.
+    """
+    raw = run_safe([
+        "osascript", "-e",
+        'tell application "Finder" to get bounds of window of desktop'
+    ], timeout=5.0).strip()
+    nums = [int(x) for x in re.findall(r"-?\d+", raw)]
+    if len(nums) >= 4:
+        return nums[0], nums[1], nums[2], nums[3]
+    return 0, 0, 1440, 900
+
+
+def paint_front_window(profile: str) -> None:
+    safe = as_string(profile)
+    script = f'''
+tell application "Terminal"
+  set current settings of selected tab of front window to settings set "{safe}"
+end tell
+'''
+    _osascript(script, timeout=3.0)
+
+
+def apply_profile(window_ids: list[int], profile: str) -> None:
+    if not window_ids:
+        return
+    safe = as_string(profile)
+    # Each window in its own `try`, like set_window_titles and place_windows.
+    # Without it a single id that has closed since the scan raises and every
+    # window after it in the batch goes unpainted.
+    lines = ['tell application "Terminal"']
+    for wid in window_ids:
+        lines.append("try")
+        lines.append(f"  set w to first window whose id is {wid}")
+        lines.append("  repeat with t in tabs of w")
+        lines.append(f'    set current settings of t to settings set "{safe}"')
+        lines.append("  end repeat")
+        lines.append("end try")
+    lines.append("end tell")
+    _osascript("\n".join(lines), timeout=6.0)
+
+
+def set_window_title(window_id: int, title: str) -> None:
+    set_window_titles({window_id: title})
+
+
+def set_window_titles(titles: dict[int, str]) -> None:
+    """Batch custom titles into one AppleScript (avoids N main-thread hits)."""
+    if not titles:
+        return
+    lines = ['tell application "Terminal"']
+    for wid, title in titles.items():
+        safe = as_string(title)
+        lines.append("try")
+        lines.append(f"  set w to first window whose id is {wid}")
+        lines.append("  repeat with t in tabs of w")
+        lines.append(f'    set custom title of t to "{safe}"')
+        lines.append("  end repeat")
+        lines.append("end try")
+    lines.append("end tell")
+    _osascript("\n".join(lines), timeout=6.0)
+
+
+def set_front_title(title: str) -> None:
+    safe = as_string(title)
+    script = f'''
+tell application "Terminal"
+  set custom title of selected tab of front window to "{safe}"
+end tell
+'''
+    _osascript(script, timeout=3.0)
+
+
+def ensure_title_settings() -> None:
+    """Idempotent: only rewrite profile title prefs once per process."""
+    global _titles_simplified
+    if _titles_simplified:
+        return
+    simplify_title_settings()
+    _titles_simplified = True
+
+
+def simplify_title_settings() -> None:
+    """Turn off noisy Terminal title bits (command path, 80×24) on known profiles."""
+    names = [
+        "Basic", "Ocean", "Grass", "Homebrew", "Red Sands", "Pro", "Novel",
+        "Silver Aerogel", "Man Page", "Solid Colors", "Clear Dark", "Clear Light",
+    ]
+    lines = ['tell application "Terminal"']
+    for n in names:
+        safe = as_string(n)
+        lines.append('try')
+        lines.append(f'  tell settings set "{safe}"')
+        lines.append("    set title displays window size to false")
+        lines.append("    set title displays shell path to false")
+        lines.append("    set title displays custom title to true")
+        lines.append("  end tell")
+        lines.append("end try")
+    lines.append("end tell")
+    _osascript("\n".join(lines), timeout=5.0)
+
+
+def focus_window(window_id: int) -> None:
+    script = f'''
+tell application "Terminal"
+  activate
+  set w to first window whose id is {window_id}
+  set index of w to 1
+end tell
+'''
+    _osascript(script, timeout=3.0)
+
+
+def _rect_text(rect: tuple[int, int, int, int]) -> str:
+    """A rectangle as Terminal writes one, so the two can be compared."""
+    return ",".join(str(int(n)) for n in rect)
+
+
+def _read_bounds(blob: str) -> dict[int, str]:
+    """`id=l,t,r,b` lines back into a mapping. A line it cannot read is
+    dropped rather than guessed at, which makes that window count as unmoved:
+    the safe direction, because the alternative is claiming a window landed
+    somewhere on the strength of a line nothing could parse."""
+    out: dict[int, str] = {}
+    for line in blob.splitlines():
+        wid, _, rect = line.strip().partition("=")
+        rect = rect.replace(" ", "")
+        if wid.isdigit() and rect:
+            out[int(wid)] = rect
+    return out
+
+
+def place_windows(placements: list[tuple[int, tuple[int, int, int, int]]],
+                  *, front_first: bool = True) -> int:
+    """Move/resize windows in one Apple Event. Returns how many actually moved.
+
+    Not how many were asked to move, for the same reason `close_windows`
+    counts survivors rather than requests. macOS window tiling takes
+    `set bounds` and throws it away. Measured on this machine: a window in a
+    tile group answered the same bounds before and after, with no error raised
+    anywhere in the script and nothing for the caller to notice. Terminal
+    reports the tiled frame while the write lands on the frame the window
+    would return to if you dragged it out, so `organize` was telling people it
+    had laid out windows that had not moved a pixel.
+
+    A window counts as placed if its bounds changed, or if it was already at
+    the rectangle it was asked for. Comparing the result against the requested
+    rectangle alone would be wrong: Terminal keeps the size it is given and
+    slides the origin to keep the window on screen, so asking for y=10 under a
+    36 pixel menu bar gives back y=33, and that is a window that moved.
+
+    The one thing this cannot tell apart is a request that clamps to exactly
+    where the window already sits, which reads as unmoved. `organize` does not
+    generate one: it works inside `_usable_desktop()`, which is already inset
+    from the menu bar and the dock.
+    """
+    if not placements:
+        return 0
+
+    def probe(var: str) -> list[str]:
+        out = [f'set {var} to ""']
+        for wid, _rect in placements:
+            out += ["try",
+                    f'  set {var} to {var} & "{wid}=" & '
+                    f"((bounds of window id {wid}) as text) & linefeed",
+                    "end try"]
+        return out
+
+    lines = ['tell application "Terminal"', "activate"]
+    # Without this a bounds list joins with no separator at all, and
+    # `0,69,1728,1117` comes back as `06917281117`, which no reader can split.
+    lines.append("set AppleScript's text item delimiters to \",\"")
+    lines += probe("before")
+    for wid, (x1, y1, x2, y2) in placements:
+        lines += [
+            "try",
+            f"  set w to first window whose id is {wid}",
+            "  try",
+            "    set visible of w to true",
+            "  end try",
+            "  try",
+            "    set miniaturized of w to false",
+            "  end try",
+            f"  set bounds of w to {{{x1}, {y1}, {x2}, {y2}}}",
+        ]
+        if front_first:
+            lines.append("  set index of w to 1")
+        lines.append("end try")
+    # Terminal reports the old frame for a moment after accepting a move, so
+    # without this the check races the write and every window reads as stuck.
+    lines.append("delay 0.4")
+    lines += probe("after")
+    lines += ['return before & "--" & after', "end tell"]
+    raw = _osascript("\n".join(lines), timeout=10.0)
+    if not terminal_status()["ok"]:
+        return 0
+    before_blob, _, after_blob = raw.partition("--")
+    was, now = _read_bounds(before_blob), _read_bounds(after_blob)
+    placed = 0
+    for wid, rect in placements:
+        after = now.get(wid)
+        if after is None:
+            # Gone, or a window Terminal will not answer for. Either way it is
+            # not on screen where this asked it to be.
+            continue
+        if after != was.get(wid) or after == _rect_text(rect):
+            placed += 1
+    return placed
+
+
+def close_windows(window_ids: list[int]) -> int:
+    """Close these Terminal windows. Returns how many actually closed.
+
+    Not how many were asked to close, which is what this used to return.
+    Terminal puts a sheet on any window with something still running in it
+    ("Closing this tab will terminate the running process X"), and `close`
+    returns straight away without waiting for the answer. So the window stays
+    on screen, wearing a dialog, while workmap reports it closed.
+
+    Which windows are left is the only honest answer, so it asks. Dismissing
+    the sheet is deliberately not attempted: agreeing to it kills whatever is
+    running in that tab, and workmap has two keys that already do that on
+    purpose. The user gets told what is waiting for them instead.
+
+    It asks twice, and the second question is why. "How many of these are
+    gone now" counts an id that was already gone as one this call closed,
+    and ids come off the last refresh: a window the user closed by hand a
+    moment ago is exactly that. Measured against a real Terminal, closing an
+    id that had already gone reported one closed. So it takes the ones that
+    were open before, and counts how many of those are not open after.
+
+    A closed window stays addressable rather than raising: measured, it
+    answers `exists` true, `visible` false, and no tabs. So having a tab is
+    the test for open, which is also what puts a window on the desk map.
+    One definition, used in both places.
+    """
+    if not window_ids:
+        return 0
+
+    def probe(var):
+        out = [f'set {var} to ""']
+        for wid in window_ids:
+            out += ["try",
+                    f"  if (count of tabs of window id {wid}) > 0 then",
+                    f'    set {var} to {var} & "{wid}" & linefeed',
+                    "  end if",
+                    "end try"]
+        return out
+
+    lines = ['tell application "Terminal"']
+    lines += probe("started")
+    for wid in window_ids:
+        lines += ["try", f"  close (first window whose id is {wid})", "end try"]
+    # Terminal needs a moment to take a window down before it stops answering
+    # for it; without this the survivor check races the close it just asked for.
+    lines.append("delay 0.4")
+    lines += probe("ended")
+    lines += ['return started & "--" & ended', "end tell"]
+    raw = _osascript("\n".join(lines), timeout=10.0)
+    if not terminal_status()["ok"]:
+        return 0
+    started, _, ended = raw.partition("--")
+    was_open = {ln.strip() for ln in started.splitlines() if ln.strip()}
+    still_open = {ln.strip() for ln in ended.splitlines() if ln.strip()}
+    return len(was_open - still_open)