mindvest-atlas 0.48.0 → 0.49.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mindvest-atlas",
-  "version": "0.48.0",
+  "version": "0.49.0",
   "description": "Atlas CLI \u2014 OAuth login, tool calls, and live alert/flow streaming for the Atlas trading API",
   "type": "module",
   "bin": {

package/src/commands/computer-use.js

@@ -92,11 +92,29 @@ const OPS = {
   'mouse-up': ['mouse_up', 0],
   'key-down': ['key_down', 1],
   'key-up': ['key_up', 1],
+  // ── WINDOWS, BY NAME ──────────────────────────────────────────────────
+  // A window that is not on the screen is not gone, it is minimised, and a run
+  // with no way to say so hunted for it with the mouse and gave up (owner,
+  // 2026-09-06: "unable to navigate multiple pages or minimize etc"). A named
+  // command beats a key chord, which goes wherever the focus is and reports
+  // success either way.
+  windows: ['windows', 0],
+  minimize: ['minimize_window', 1],
+  maximize: ['maximize_window', 1],
+  restore: ['restore_window', 1],
+  'close-window': ['close_window', 1],
+  'move-window': ['move_window', 3],
+  'resize-window': ['resize_window', 3],
+  // ── A PAGE THAT IS TALLER THAN THE SCREEN ─────────────────────────────
+  'scroll-to': ['scroll_to', 1],
+  'scan-page': ['scan_page', 0],
 };
 // Which values are numbers. Passing "840" as a string to click() would move the
-// pointer nowhere and report success.
+// pointer nowhere and report success. THE SAME SET THE PYTHON CLI USES: a verb
+// that takes numbers in one runtime and strings in the other is a verb nobody
+// can rely on.
 const NUMERIC = new Set(['use-screen', 'click', 'double-click', 'right-click',
-  'middle-click', 'triple-click', 'move', 'drag', 'scroll']);
+  'middle-click', 'triple-click', 'move', 'drag', 'scroll', 'wait', 'region']);
 
 /** This shell's holding id, made once and remembered. Shared with `atlas run`
  *  so everything typed at one prompt lands in ONE session: the log reads as a

package/src/commands/historical.js

@@ -1,7 +1,7 @@
 // `atlas historical-contract --symbol NVDA --expiry 2026-07-13 --strike 205 --side call
 //                            --from 2026-07-08 --to 2026-07-10`
 //
-// Day-by-day price + greeks for ONE option contract. This is a friendly front end over
+// Day-by-day price, greeks and volume for ONE option contract. This is a friendly front end over
 // the `Historical-Contract-Greeks` tool: short flags (--expiry / --from / --to), a
 // side shorthand (--call / --put), per-flag "you forgot this one" errors, and a table
 // instead of raw JSON. The generic caller still works (`atlas historical-contract-greeks
@@ -51,12 +51,16 @@ export function printHistoricalHelp() {
   println(c.bold('OPTIONAL'));
   println('  --to, --end <D>            Last day to report (default: same as --from)');
   println('  --no-greeks                Prices only — skip the greeks (faster)');
+  println('  --no-volume                Skip the traded volume (faster on long ranges)');
   println('  --json                     Raw JSON instead of the table');
   println();
   println(c.bold('NOTES'));
   println(c.dim('  The daily price is the MID of the last bid/ask before the 4pm close.'));
   println(c.dim('  Greeks are calculated, not reported: no data provider publishes greeks for'));
   println(c.dim('  past dates, so implied volatility is solved from that day\'s closing mid.'));
+  println(c.dim('  Volume IS reported (the official daily figure, not a count off the tape),'));
+  println(c.dim('  but reading it costs extra requests, so a long range or a far-from-the-money'));
+  println(c.dim('  strike may come back without it, and will say so.'));
   println(c.dim('  Open interest is not available for past dates at all.'));
   println(c.dim('  One contract per call, up to 90 trading days.'));
   println();
@@ -112,6 +116,7 @@ export function buildHistoricalBody(args) {
   if (to) body.to_date = String(to);
   // `--no-greeks` parses to flags.greeks === false (the --no- convention).
   if (flags.greeks === false || flags['include-greeks'] === false) body.include_greeks = false;
+  if (flags.volume === false || flags['include-volume'] === false) body.include_volume = false;
   return { body };
 }
 

package/src/config.js

@@ -2,7 +2,7 @@
 import path from 'node:path';
 import os from 'node:os';
 
-export const VERSION = '0.48.0';
+export const VERSION = '0.49.0';
 export const DEFAULT_BASE_URL = 'https://atlasmcp.finmanagerai.com';
 export const DEFAULT_SCOPE = 'atlas broker';
 export const CLIENT_NAME = 'Atlas CLI';

package/src/helpers/atlas_env.py

@@ -998,6 +998,183 @@ def screens():
     return [{"index": 1, "x": 0, "y": 0, "width": int(w), "height": int(h), "primary": True}]
 
 
+# ── THE PICTURE AND THE POINTER HAVE TO USE THE SAME NUMBERS ────────────────
+#
+# A screenshot is taken in the display's REAL pixels. The pointer moves in the
+# coordinate space the OS hands to applications. On Windows those are the same
+# once the process declares itself DPI-aware, which _gui() does. On a Retina Mac
+# they are NOT: the picture is 2880 across and the pointer's desk is 1440, so a
+# position read honestly off the picture lands at twice its distance from the
+# corner and every single click misses (owner, 2026-09-06: "it misses the
+# click"). Nothing errors; the press just goes somewhere else.
+#
+# So the ratio is measured once and the picture is SAVED IN POINTER NUMBERS.
+# What you read off it is what you press. There is nothing to remember, nothing
+# to multiply, and no way to get it wrong.
+_SCALE = {"px": None}
+_MSS = {"local": None}
+
+
+def _capture_scale():
+    """Picture pixels per pointer step. 1 nearly everywhere, 2 on a Retina Mac."""
+    if _SCALE["px"] is not None:
+        return _SCALE["px"]
+    got = 1.0
+    try:
+        mons = screens()
+        prim = next((m for m in mons if m.get("primary")), mons[0] if mons else None)
+        w, _h = _gui().size()
+        if prim and w and prim.get("width"):
+            r = float(prim["width"]) / float(w)
+            # Only a real, clean ratio counts. Anything odd is left alone rather
+            # than guessed at: a wrong scale is worse than no scale.
+            if 1.4 < r < 4.5:
+                got = round(r * 2) / 2.0
+    except Exception:
+        got = 1.0
+    _SCALE["px"] = got
+    return got
+
+
+def _mss_session():
+    """One mss per thread, kept. Opening one per grab costs a connection to the
+    display server every time, which is most of what a quick look costs."""
+    import mss as _mss
+    import threading as _th
+    if _MSS["local"] is None:
+        _MSS["local"] = _th.local()
+    sct = getattr(_MSS["local"], "sct", None)
+    if sct is None:
+        sct = _mss.mss()
+        _MSS["local"].sct = sct
+    return sct
+
+
+def _grab(m):
+    """One monitor, as (picture, raw bytes).
+
+    The raw bytes are for COMPARING: hashing what came off the display is a
+    tenth of the cost of encoding a PNG to find out nothing had moved. None when
+    this machine's capture cannot hand them over, which only means every look
+    counts as a change.
+    """
+    box = {"left": int(m["x"]), "top": int(m["y"]),
+           "width": int(m["width"]), "height": int(m["height"])}
+    try:
+        from PIL import Image as _Im
+        shot = _mss_session().grab(box)
+        return _Im.frombytes("RGB", shot.size, shot.bgra, "raw", "BGRX"), bytes(shot.raw)
+    except ImportError:
+        pass
+    # WITHOUT mss, STILL THE RIGHT SCREEN. pyautogui grabs a region of the
+    # virtual desktop, which is all this ever needed; mss is only faster.
+    try:
+        img = _gui().screenshot(region=(box["left"], box["top"], box["width"], box["height"]))
+    except Exception as err:
+        # Some platforms cannot reach a monitor left of the origin, where x is
+        # negative. Say so rather than handing back the primary and letting
+        # every coordinate read off it be wrong.
+        raise RuntimeError(
+            "Could not photograph screen %s on this computer (%s). Install mss "
+            "for multi-screen capture, or use_screen(%s) to work on the main one."
+            % (m.get("index"), err, _primary_index(screens()))
+        )
+    try:
+        return img, img.tobytes()
+    except Exception:
+        return img, None
+
+
+def _grid_step(w, h):
+    big = max(w, h)
+    return 100 if big <= 1400 else (200 if big <= 3000 else 400)
+
+
+def _draw_grid(img, ox, oy, unit=1.0):
+    """A ruler, in the numbers you would actually click.
+
+    Reading a position off a picture by eye is the one thing a model is poor at,
+    and it is the whole job here. So the picture carries its own coordinates:
+    a dotted line every so often and the DESKTOP number written against it, which
+    already includes this screen's origin. Read the label, click the label. That
+    removes the arithmetic that made every click on a second monitor land one
+    screen to the left, and it turns "about a third of the way across" into a
+    number.
+    """
+    try:
+        from PIL import ImageDraw
+    except ImportError:
+        return img
+    try:
+        w, h = img.size
+    except Exception:
+        return img
+    # `unit` is picture pixels per DESKTOP step. The picture may be saved
+    # smaller than the desk it shows, so the lines are placed at round DESKTOP
+    # numbers and then converted, never the other way round: the label has to be
+    # a number that can be clicked.
+    unit = float(unit) or 1.0
+    step = _grid_step(int(w / unit), int(h / unit))
+    try:
+        d = ImageDraw.Draw(img)
+    except Exception:
+        return img                 # not something that can be drawn on
+    line = (255, 0, 170)
+    try:
+        desk = step
+        while desk * unit < w:
+            gx = int(round(desk * unit))
+            d.point([(gx, gy) for gy in range(0, h, 7)], fill=line)
+            label = str(desk + int(ox))
+            d.rectangle([gx + 1, 1, gx + 7 + 6 * len(label), 13], fill=(17, 17, 20))
+            d.text((gx + 4, 3), label, fill=(255, 210, 240))
+            desk += step
+        desk = step
+        while desk * unit < h:
+            gy = int(round(desk * unit))
+            d.point([(gx, gy) for gx in range(0, w, 7)], fill=line)
+            label = str(desk + int(oy))
+            d.rectangle([1, gy + 1, 7 + 6 * len(label), gy + 13], fill=(17, 17, 20))
+            d.text((4, gy + 3), label, fill=(255, 210, 240))
+            desk += step
+    except Exception:
+        pass                       # a ruler is help, never a reason to fail
+    return img
+
+
+def _shot_cap():
+    """The longest edge a saved picture may have. 0 turns the cap off.
+
+    A LOOK IS NOT FINISHED UNTIL IT HAS BEEN READ. A full 4K desktop is a slow
+    encode and a slower upload, and the model reading it downscales to about
+    this anyway, so the pixels past here are paid for twice and used never.
+
+    It costs nothing in aim, which is the part that would matter: the ruler is
+    drawn in DESKTOP numbers after the resize, and a point half way between two
+    labels is half way between them whatever size the picture is.
+    """
+    try:
+        return max(0, int(os.environ.get("ATLAS_COMPUTER_SHOT_MAX", "1600")))
+    except ValueError:
+        return 1600
+
+
+def _grid_wanted():
+    """On unless somebody turned it off."""
+    return str(os.environ.get("ATLAS_COMPUTER_GRID", "1")).strip().lower() not in ("0", "off", "false", "no")
+
+
+def _save_shot(img, out):
+    """Written fast. This is a local file that a model opens once; spending a
+    fifth of a second squeezing it smaller is a fifth of a second of the
+    person's time, every look."""
+    try:
+        img.save(out, "PNG", compress_level=1)
+    except Exception:
+        img.save(out)
+    return out
+
+
 def _primary_index(mons):
     for m in mons:
         if m.get("primary"):
@@ -1113,6 +1290,23 @@ def _current_screen():
                 {"index": 1, "x": 0, "y": 0, "width": 0, "height": 0, "primary": True})
 
 
+def _pointer_box(m):
+    """A monitor's bounds in the numbers CLICKS use.
+
+    screens() measures in the display's real pixels, because that is what a
+    grab needs. Everything a caller says is in pointer steps. On a Retina Mac
+    those differ by two, so a bounds check done in the wrong one refuses points
+    that are plainly on the screen and accepts points that are not.
+    """
+    sc = _capture_scale()
+    if sc <= 1.01:
+        return m
+    out = dict(m)
+    for k in ("x", "y", "width", "height"):
+        out[k] = int(round(float(m.get(k) or 0) / sc))
+    return out
+
+
 def _on_screen(x, y):
     """Refuse a point that is not on the screen this run is working on.
 
@@ -1121,7 +1315,7 @@ def _on_screen(x, y):
     """
     if x is None or y is None:
         return
-    m = _current_screen()
+    m = _pointer_box(_current_screen())
     if not m.get("width"):
         return
     inside = (m["x"] <= int(x) < m["x"] + m["width"]) and (m["y"] <= int(y) < m["y"] + m["height"])
@@ -1155,80 +1349,107 @@ def _on_screen(x, y):
     )
 
 
-def screen(path=None):
+def screen(path=None, grid=None):
     """A picture of THE SCREEN this run is working on, and its path.
 
     ONE screen, never several joined together: see use_screen(). Which one it
     was is written into the log, so a replay never leaves you wondering what you
     are looking at.
 
+    THE PICTURE IS IN THE NUMBERS YOU CLICK IN, and it says them out loud.
+
+      * It is saved in POINTER space, so a Retina Mac's 2880-wide grab is a
+        1440-wide picture: what you measure is what you press, with nothing to
+        halve (owner, 2026-09-06: "it misses the click").
+      * A dotted ruler is drawn over it, labelled with DESKTOP coordinates -
+        this screen's origin already added. Read the nearest labels, count the
+        gap, click that number. On a second monitor that also ends the mistake
+        of clicking a position measured inside the picture.
+
+    Pass grid=False for a clean picture when you want to look at the pixels
+    themselves rather than aim at them.
+
     WHAT COMES BACK IS THE PATH, and on a multi-screen machine also where that
     screen STARTS:
 
-        {"path": "...png", "screen": 2, "x": 1920, "y": 0,
-         "note": "add x 1920, y 0 to positions you read off this picture"}
-
-    That matters and it is the easiest thing here to get wrong. The picture is
-    an image whose top left is 0,0; the pointer lives on the whole desktop,
-    where that same corner may be 1920,0. A position read straight off the
-    picture and clicked lands one screen to the left, and on a two-monitor desk
-    that is EVERY click. Add the origin.
+        {"path": "...png", "screen": 2, "x": 1920, "y": 0, "grid": 200,
+         "note": "the ruler is labelled in desktop coordinates - click what it says"}
 
-    On a single screen the origin is 0,0 and this is just the path, as before.
+    IDENTICAL PICTURES ARE NOT RE-SAVED. If nothing on the screen moved since
+    the last look, the previous file comes back rather than an encode of the
+    same pixels: the compare is a hash of the raw grab and costs a tenth of what
+    writing the PNG does.
 
     Not dashboard.shot(): that one draws this project's DASHBOARD in a frame. Two
     things called screenshot, one of them the whole desktop, is a mistake
     somebody makes once with a real click.
     """
     m = _current_screen()
+    box = _pointer_box(m)
+    want_grid = _grid_wanted() if grid is None else bool(grid)
 
     def take():
-        out = path or os.path.join(_session_dir(), "screen-%d.png" % int(__import__("time").time() * 1000))
-        try:
-            import mss as _mss
-            import mss.tools as _tools
-            with _mss.mss() as sct:
-                shot = sct.grab({"left": m["x"], "top": m["y"],
-                                 "width": m["width"], "height": m["height"]})
-                _tools.to_png(shot.rgb, shot.size, output=out)
-            return out
-        except ImportError:
-            # WITHOUT mss, STILL THE RIGHT SCREEN. This used to photograph the
-            # whole primary display whatever use_screen had said, and then the
-            # log recorded "Looked at screen 2" beside a picture of screen 1
-            # (owner, 2026-09-06: "the screener and screenshot not taking the
-            # right"). A picture that lies about which screen it is of is worse
-            # than no picture: everything measured on it is measured on the
-            # wrong desk.
-            #
-            # pyautogui can grab a REGION of the virtual desktop, which is all
-            # this ever needed. Nothing about it requires mss; mss is only
-            # faster.
+        import hashlib
+        img, raw = _grab(m)
+        digest = hashlib.md5(raw).hexdigest() if raw is not None else None
+        seen = _last_look()
+        # NOTHING MOVED, SO NOTHING IS WRITTEN. The expensive part of a look is
+        # the PNG, not the grab, and re-encoding pixels somebody already has is
+        # the commonest thing a run does while it waits for a page.
+        if (digest and not path and seen.get("hash") == digest and seen.get("path")
+                and os.path.exists(seen["path"])):
+            _remember_look(digest, seen["path"], changed=False)
+            return seen["path"]
+        # POINTER SPACE FIRST, so one picture pixel is one clickable step...
+        sc = _capture_scale()
+        unit = 1.0
+        if sc > 1.01:
             try:
-                shot = _gui().screenshot(region=(int(m["x"]), int(m["y"]),
-                                                 int(m["width"]), int(m["height"])))
-            except Exception as err:
-                # Some platforms cannot reach a monitor left of the origin, where
-                # x is negative. Say so rather than handing back the primary and
-                # letting every coordinate read off it be wrong.
-                raise RuntimeError(
-                    "Could not photograph screen %s on this computer (%s). Install "
-                    "mss for multi-screen capture, or use_screen(%s) to work on "
-                    "the main one." % (m["index"], err, _primary_index(screens()))
-                )
-            shot.save(out)
-            return out
+                from PIL import Image as _Im
+                w = max(1, int(round(img.width / sc)))
+                h = max(1, int(round(img.height / sc)))
+                whole = int(round(sc))
+                img = (img.reduce(whole) if abs(sc - whole) < 0.01 and whole > 1
+                       else img.resize((w, h), _Im.BILINEAR))
+            except Exception:
+                pass
+        # ...and then, only for the sake of what has to read it, no bigger than
+        # it needs to be. The ruler is drawn after this and in desktop numbers,
+        # so aiming is untouched.
+        cap = _shot_cap()
+        try:
+            longest = max(img.width, img.height)
+            if cap and longest > cap:
+                from PIL import Image as _Im2
+                unit = float(cap) / float(longest)
+                img = img.resize((max(1, int(img.width * unit)),
+                                  max(1, int(img.height * unit))), _Im2.BILINEAR)
+        except Exception:
+            unit = 1.0
+        if want_grid:
+            img = _draw_grid(img, box.get("x") or 0, box.get("y") or 0, unit)
+        out = path or os.path.join(_session_dir(), "screen-%d.png" % int(__import__("time").time() * 1000))
+        _save_shot(img, out)
+        _remember_look(digest, out, changed=True)
+        return out
+
     out = _do("screen", take, {"monitor": m["index"]})
     # A BARE PATH ON A SINGLE SCREEN, because that is what it has always been and
     # nothing about one monitor needs explaining. Where there is more than one,
     # the offset travels WITH the picture rather than waiting to be asked for:
     # the moment it is needed is the moment the picture is read.
-    if not m.get("x") and not m.get("y"):
+    if not box.get("x") and not box.get("y"):
+        if not want_grid:
+            return out
         return out
-    return {"path": out, "screen": m["index"], "x": m["x"], "y": m["y"],
-            "width": m["width"], "height": m["height"],
-            "note": "add x %s, y %s to positions you read off this picture"
-                    % (m["x"], m["y"])}
+    return {"path": out, "screen": m["index"], "x": box["x"], "y": box["y"],
+            "width": box["width"], "height": box["height"],
+            "grid": _grid_step(box["width"], box["height"]) if want_grid else 0,
+            "note": ("the ruler drawn on this picture is labelled in DESKTOP "
+                     "coordinates - click the numbers it shows, do not add "
+                     "anything to them") if want_grid else
+                    "add x %s, y %s to positions you read off this picture"
+                    % (box["x"], box["y"])}
 
 
 # ── STAYING ALIVE BETWEEN COMMANDS ──────────────────────────────────────────
@@ -1361,14 +1582,46 @@ def base64_token():
     return base64.urlsafe_b64encode(os.urandom(18)).decode("ascii").rstrip("=")
 
 
+def _look_note():
+    return os.path.join(_session_dir(), "last-screen.json")
+
+
+def _last_look():
+    """The previous look: what the screen hashed to, and where that picture is.
+
+    On disk, because a shell run is a row of separate processes and each one has
+    to know what the one before it saw.
+    """
+    import json as _j
+    try:
+        with open(_look_note(), encoding="utf-8") as fh:
+            got = _j.loads(fh.read())
+        return got if isinstance(got, dict) else {}
+    except Exception:
+        return {}
+
+
+def _remember_look(digest, path, changed):
+    import json as _j
+    try:
+        with open(_look_note(), "w", encoding="utf-8") as fh:
+            fh.write(_j.dumps({"hash": digest, "path": path, "changed": bool(changed)}))
+    except OSError:
+        pass
+
+
 def _screen_changed(path):
-    """True when this picture differs from the one before it.
+    """True when the last picture differs from the one before it.
 
-    Compared by content, not by time: a screen that is still is genuinely
-    unchanged, and telling a reader so saves it opening an image to discover
-    nothing moved. Kept in the session folder, so it works across the separate
-    processes a shell run is made of.
+    Compared by CONTENT, not by time, and compared on the raw grab before any
+    encoding: screen() has already done that work and written down the verdict,
+    so this is a read rather than a second hash of a file just written. Telling a
+    reader "nothing moved" saves them opening an image to discover it.
     """
+    seen = _last_look()
+    if path and seen.get("path") == path and "changed" in seen:
+        return bool(seen["changed"])
+    # A picture taken by something other than screen(): fall back to hashing it.
     import hashlib
     if not path:
         return True
@@ -1377,21 +1630,70 @@ def _screen_changed(path):
             now = hashlib.md5(fh.read()).hexdigest()
     except OSError:
         return True
-    mark = os.path.join(_session_dir(), "last-screen.txt")
-    was = None
-    try:
-        with open(mark, encoding="utf-8") as fh:
-            was = fh.read().strip()
-    except OSError:
-        pass
-    try:
-        with open(mark, "w", encoding="utf-8") as fh:
-            fh.write(now)
-    except OSError:
-        pass
+    was = seen.get("hash")
+    _remember_look(now, path, changed=was != now)
     return was != now
 
 
+def _frame_digest(m=None):
+    """What the screen looks like RIGHT NOW, as a hash, with nothing written.
+
+    The cheap half of a look. Used to find out whether a page has finished
+    moving, which is a question asked many times per run and never needs a file.
+    """
+    import hashlib
+    try:
+        _img, raw = _grab(m or _current_screen())
+        return hashlib.md5(raw).hexdigest()
+    except Exception:
+        return None
+
+
+def _settle(most_s, quiet=2, step=0.12, was_before=None):
+    """Wait for the screen to STOP MOVING, up to a limit. Returns what it waited.
+
+    A fixed pause is wrong in both directions: too long on a screen that was
+    already still, too short on a page that is still painting. So this watches
+    instead, and returns the moment two looks in a row agree. Most of the time
+    that is a quarter of what a fixed wait would have cost, and on a slow page
+    it is the one that is actually correct.
+    """
+    import time as _time
+    most_s = max(0.0, float(most_s))
+    if most_s <= 0:
+        return 0.0
+    began = _time.time()
+    same = 0
+    was = _frame_digest()
+    if was is None:
+        _time.sleep(most_s)             # nothing to watch with: the old behaviour
+        return most_s
+    # WAIT FOR IT TO START, NOT ONLY TO STOP. A click on a link is followed by a
+    # moment where nothing has happened yet, and a screen that has not begun to
+    # change is perfectly still: settling alone declares it done and hands back a
+    # picture of the page you were already on, so the next turn is spent
+    # discovering that and asking again. Half the allowance goes on waiting for
+    # the first sign of movement; the rest on waiting for it to finish.
+    if was_before is not None and was == was_before:
+        while _time.time() - began < most_s / 2.0:
+            _time.sleep(step)
+            now = _frame_digest()
+            if now is not None and now != was_before:
+                was = now
+                break
+    while _time.time() - began < most_s:
+        _time.sleep(step)
+        now = _frame_digest()
+        if now is not None and now == was:
+            same += 1
+            if same >= quiet:
+                break
+        else:
+            same = 0
+        was = now
+    return _time.time() - began
+
+
 def do(*steps, **kw):
     """Do several things, then look ONCE. The fast loop.
 
@@ -1415,11 +1717,19 @@ def do(*steps, **kw):
     into something worth reading. Between the steps there is nothing to see that
     you did not already know was coming.
 
-    `settle` waits before the picture, for a page that is still moving. Set
-    `look=False` when the next thing you do does not depend on what happened.
+    `settle` is now a CEILING, not a pause. It waits for the screen to stop
+    moving and gets on with it the moment it has, so a still screen costs a
+    quarter of a second instead of six tenths and a page still painting gets the
+    whole allowance. Raise it for something slow; `look=False` skips the picture
+    entirely when the next thing you do does not depend on what happened.
     """
-    settle = float(kw.get("settle", 0.6))
+    settle = float(kw.get("settle", 1.2))
     look = kw.get("look", True)
+    # What it looked like before any of this, so the wait afterwards can tell
+    # "nothing has happened yet" from "it happened and is done". Only worth
+    # measuring when there is going to be a wait: settle=0 says do not wait, and
+    # a grab taken to inform a wait that will not happen is pure cost.
+    before = _frame_digest() if look and steps and float(kw.get("settle", 1.2)) > 0 else None
     did = []
     for step in steps:
         if not step:
@@ -1455,8 +1765,7 @@ def do(*steps, **kw):
     if not look:
         return {"did": did}
     if settle > 0:
-        import time as _time
-        _time.sleep(settle)
+        _settle(settle, was_before=before)
     # THE WORK SUCCEEDING AND THE LOOK FAILING ARE TWO DIFFERENT THINGS.
     #
     # Every step ran, and then the picture at the end could not be taken, and the
@@ -1612,6 +1921,207 @@ def scroll(x=None, y=None, delta_x=0, delta_y=0):
     return _do("scroll", go, {"x": x, "y": y, "delta_x": delta_x, "delta_y": delta_y})
 
 
+def _all_windows():
+    g = _gui()
+    try:
+        got = list(g.getAllWindows())
+    except Exception as err:
+        raise RuntimeError(
+            "This computer cannot list its windows from here (%s). On Windows "
+            "that works out of the box; on macOS and Linux it usually does not, "
+            "so click the window you want instead." % err
+        )
+    return [w for w in got if str(getattr(w, "title", "") or "").strip()]
+
+
+def _one_window(title):
+    """The window whose title contains `title`. Raises if there is no such thing.
+
+    NOT ATLAS, unless somebody asked for it. Minimising or closing the window
+    that shows what this run is doing is the same self-inflicted wound as
+    clicking Stop, and it is easier to do by accident because a title match is
+    fuzzy.
+    """
+    want = str(title or "").strip()
+    if not want:
+        raise RuntimeError("Say which window, by any part of its title. windows() lists them.")
+    hit = [w for w in _all_windows() if want.lower() in str(getattr(w, "title", "")).lower()]
+    if not hit:
+        open_now = ", ".join(sorted({str(getattr(w, "title", ""))[:40] for w in _all_windows()})[:10])
+        raise RuntimeError(
+            'No window whose title contains "%s". Open right now: %s. windows() '
+            "lists them all." % (want, open_now or "nothing this can see")
+        )
+    got = hit[0]
+    if not _MAY_USE_ATLAS["ok"] and _is_atlas_title(str(getattr(got, "title", ""))):
+        raise RuntimeError(
+            '"%s" is Atlas Remote Control, which is showing the person what this '
+            "run is doing. Touching its window is not something to decide on your "
+            "own: if they asked for it, call use_atlas_app() first." % got.title
+        )
+    return got
+
+
+def windows(title=""):
+    """Every window that is open, with where it is and what state it is in.
+
+        [{"title": "Edge", "x": 0, "y": 0, "width": 1920, "height": 1040,
+          "minimized": False, "maximized": True, "active": True}, ...]
+
+    LOOK HERE BEFORE HUNTING WITH THE MOUSE. A window you cannot see is not gone,
+    it is minimised, and the answer to that is one call rather than a search
+    across a desktop for an icon.
+    """
+    def go():
+        out = []
+        for w in _all_windows():
+            t = str(getattr(w, "title", "") or "")
+            if title and str(title).lower() not in t.lower():
+                continue
+            out.append({
+                "title": t[:160],
+                "x": int(getattr(w, "left", 0) or 0), "y": int(getattr(w, "top", 0) or 0),
+                "width": int(getattr(w, "width", 0) or 0), "height": int(getattr(w, "height", 0) or 0),
+                "minimized": bool(getattr(w, "isMinimized", False)),
+                "maximized": bool(getattr(w, "isMaximized", False)),
+                "active": bool(getattr(w, "isActive", False)),
+            })
+        return out
+    return _do("windows", go, {"title": str(title)[:120]})
+
+
+def _window_action(what, title, verb):
+    def go():
+        w = _one_window(title)
+        fn = getattr(w, verb, None)
+        if not callable(fn):
+            raise RuntimeError(
+                "This computer cannot %s a window from here. Click its own "
+                "button in the title bar instead." % what
+            )
+        fn()
+        return True
+    return _do(what, go, {"title": str(title)[:120]})
+
+
+def minimize_window(title):
+    """Put a window out of the way, by name. Beats win+down, which goes wherever
+    the focus is and reports success either way."""
+    return _window_action("minimize_window", title, "minimize")
+
+
+def maximize_window(title):
+    """Fill the screen with one window. Do this before working in it: a maximised
+    window is in a known place, so positions hold across a run."""
+    return _window_action("maximize_window", title, "maximize")
+
+
+def restore_window(title):
+    """Bring a minimised window back to the size it was."""
+    return _window_action("restore_window", title, "restore")
+
+
+def close_window(title):
+    """Close a window. It may ask about unsaved work, so look afterwards."""
+    return _window_action("close_window", title, "close")
+
+
+def move_window(title, x, y):
+    """Put a window somewhere. Useful for getting two side by side."""
+    def go():
+        _one_window(title).moveTo(int(x), int(y))
+        return True
+    return _do("move_window", go, {"title": str(title)[:120], "x": x, "y": y})
+
+
+def resize_window(title, width, height):
+    """Make a window a size you chose, so what is in it is where you expect."""
+    def go():
+        _one_window(title).resizeTo(int(width), int(height))
+        return True
+    return _do("resize_window", go, {"title": str(title)[:120],
+                                     "width": width, "height": height})
+
+
+# ── PAGES THAT ARE TALLER THAN THE SCREEN ───────────────────────────────────
+#
+# A picture shows what is VISIBLE. The rest of a long page is not missing, it is
+# below the fold, and a run that treats the picture as the whole thing concludes
+# the button is not there (owner, 2026-09-06: "unable to navigate multiple pages
+# ... scrolling down the page if it is cut off"). These two are the answer:
+# one scrolls to an end, the other reads the whole thing a screenful at a time.
+
+
+def scroll_to(where="bottom", x=None, y=None, most=40, amount=900):
+    """Scroll until the page stops moving. `where` is "bottom" or "top".
+
+        scroll_to("bottom")           # the end of the list
+        scroll_to("top", *middle)     # back up before reading it again
+
+    Stops as soon as two scrolls in a row change nothing, so it costs what the
+    page is long rather than a fixed number of turns, and it cannot spin for
+    ever on something that scrolls infinitely: `most` is the ceiling.
+    """
+    step = -abs(int(amount)) if str(where).lower().startswith("bot") else abs(int(amount))
+
+    def go():
+        g = _gui()
+        if x is not None and y is not None:
+            g.moveTo(int(x), int(y))
+        was = _frame_digest()
+        moved = 0
+        for _ in range(max(1, int(most))):
+            g.scroll(step)
+            import time as _time
+            _time.sleep(0.12)
+            now = _frame_digest()
+            if now is not None and now == was:
+                break
+            was = now
+            moved += 1
+        return {"scrolled": moved, "reached_end": moved < int(most)}
+    return _do("scroll_to", go, {"where": str(where), "x": x, "y": y})
+
+
+def scan_page(x=None, y=None, most=10, amount=None, grid=None):
+    """Read a page that does not fit: one picture per screenful, top to bottom.
+
+        pages = scan_page()
+        # -> {"pictures": [...4 paths...], "screens": 4, "reached_end": True}
+
+    This is what to do when what you want is not in the picture. It scrolls by
+    just under a screen each time so nothing falls between two of them, stops the
+    moment a scroll changes nothing, and hands back every picture in order. One
+    call, and you have the whole page instead of a guess about what is under it.
+
+    It does NOT return to the top afterwards: you are usually about to click
+    something you just saw. scroll_to("top") when you want to be back.
+    """
+    m = _pointer_box(_current_screen())
+    step = int(amount) if amount else max(200, int((m.get("height") or 900) * 0.82))
+
+    def go():
+        g = _gui()
+        if x is not None and y is not None:
+            g.moveTo(int(x), int(y))
+        shots, was = [], None
+        end = False
+        import time as _time
+        for _ in range(max(1, int(most))):
+            got = screen(grid=grid)
+            shots.append(got if isinstance(got, str) else got.get("path"))
+            here = _frame_digest()
+            if here is not None and here == was:
+                end = True
+                shots.pop()                    # the same screenful twice is not a page
+                break
+            was = here
+            g.scroll(-abs(step))
+            _time.sleep(0.18)
+        return {"pictures": shots, "screens": len(shots), "reached_end": end}
+    return _do("scan_page", go, {"x": x, "y": y, "step": step})
+
+
 def wait(ms):
     """Wait, and say so. A pause nobody recorded looks like a hang in a replay.
 
@@ -1671,6 +2181,9 @@ _MAY_USE_ATLAS = {"ok": os.environ.get("ATLAS_MAY_DRIVE_APP", "") == "1"}
 _ACTS_ON_A_WINDOW = (
     "click", "double_click", "right_click", "middle_click", "triple_click",
     "drag", "scroll", "type", "key", "key_down", "key_up", "mouse_down", "mouse_up",
+    # These two turn the wheel many times over, so they are as much "acting in
+    # whatever window is in front" as one scroll is.
+    "scroll_to", "scan_page",
 )
 
 
@@ -1726,9 +2239,15 @@ def _on_the_strip(x, y):
         return False
 
 
+def _is_atlas_title(title):
+    """Is that Atlas's own window? Asked of a NAME rather than of the front
+    window, because a window command names the one it acts on."""
+    low = str(title or "").lower()
+    return any(name in low for name in _ATLAS_WINDOWS) if low else False
+
+
 def _in_the_atlas_window():
-    front = _front_window().lower()
-    return any(name in front for name in _ATLAS_WINDOWS) if front else False
+    return _is_atlas_title(_front_window())
 
 #: How far the pointer can drift before it was somebody's hand.
 #:

package/src/util/format.js

@@ -100,9 +100,13 @@ export function formatContractHistory(d) {
 
   // Only show greek columns when the response actually carries them (--no-greeks).
   const hasGreeks = days.some((r) => r.delta !== null && r.delta !== undefined);
+  // Same rule for volume: the column appears only if a day actually carries one,
+  // so an empty VOL column never implies the contract sat untraded.
+  const hasVolume = days.some((r) => r.volume !== null && r.volume !== undefined);
   const head =
     'DATE'.padEnd(12) + 'DTE'.padStart(4) + 'BID'.padStart(9) + 'ASK'.padStart(9) +
     'MID'.padStart(9) + 'SPOT'.padStart(10) +
+    (hasVolume ? 'VOL'.padStart(10) : '') +
     (hasGreeks ? 'IV'.padStart(8) + 'DELTA'.padStart(9) + 'GAMMA'.padStart(9) + 'THETA'.padStart(9) : '');
   out.push(c.dim(head));
 
@@ -113,11 +117,16 @@ export function formatContractHistory(d) {
       cell(r.bid, 2, 9) + cell(r.ask, 2, 9) +
       c.bold(cell(r.mid, 2, 9).replace(/^(\s*)/, '$1')) +
       cell(r.underlying_price, 2, 10);
+    if (hasVolume) {
+      row += (r.volume === null || r.volume === undefined
+        ? '—' : r.volume.toLocaleString('en-US')).padStart(10);
+    }
     if (hasGreeks) {
       row += ivCell(r.iv, 8) + cell(r.delta, 3, 9) + cell(r.gamma, 3, 9) + cell(r.theta, 3, 9);
     }
     out.push(row);
     if (r.greeks_error) out.push(c.dim(`  ↳ no greeks: ${r.greeks_error}`));
+    if (r.volume_error) out.push(c.dim(`  ↳ no volume: ${r.volume_error}`));
   }
 
   // Never let a missing day pass silently — a holiday and a never-quoted strike look
@@ -127,6 +136,9 @@ export function formatContractHistory(d) {
     for (const s of d.skipped) out.push(c.dim(`skipped ${s.date}: ${s.reason}`));
   }
   if (d.truncated) out.push(c.yellow(String(d.truncated)));
+  // Say it out loud: a table with no VOL column and no explanation reads as
+  // "this contract never traded".
+  if (d.volume_omitted) out.push(c.yellow(`volume not fetched: ${d.volume_omitted}`));
   if (d.note) { out.push(''); out.push(c.dim(d.note)); }
   return out;
 }